Unlucky Launcher v0.0.1-alpha

Rust 原生单文件 Minecraft 启动器：CLI 完整可用（install/launch/accounts/java/diagnose/agent），
MCP server 接入外部 Agent 工具，GUI 开发中。

crates/agent/src/audit.rs

@@ -0,0 +1,283 @@
+//! 审计日志：**每一次工具调用**都留痕（02 文档 §3.1 末条 / mission M16 任务 4）。
+//!
+//! 落盘位置由装配处给（`<data_root>/agent/audit/audit-<日期>.jsonl`，按天分文件，
+//! 见 `PlanDoc/04-data-and-config.md` §2）。一行一条 JSON，只追加不修改。
+//!
+//! 三条纪律：
+//! 1. **参数先脱敏再落盘**（[`crate::redact::redact_args`]）——`set_config` 能改 AI 端点，
+//!    参数里会有 api_key；
+//! 2. 写失败**不打断**工具执行（审计是旁路），但要把失败打到 stderr 留痕；
+//! 3. YOLO 与「是否经确认」分别记录（`yolo=true, confirmed=false` 与
+//!    `yolo=false, confirmed=true` 是两件事，事故复盘的差别就在这）。
+
+use std::fs::OpenOptions;
+use std::io::Write;
+use std::path::{Path, PathBuf};
+use std::sync::Mutex;
+
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+use crate::clock::{date_of_unix_ms, format_unix_ms, SharedClock};
+use crate::redact::redact_args;
+
+/// 一次工具调用的结局（审计用）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum AuditOutcome {
+    /// 成功返回。
+    Ok,
+    /// 工具返回错误（含端口失败、未找到会话等）。
+    ToolError,
+    /// 参数没过 schema 校验（模型给错了参数）。
+    InvalidArgs,
+    /// 用户/策略拒绝。
+    Denied,
+    /// 只发出了确认请求，尚未执行（编排层在把请求交给闸门之前先记一条，
+    /// 这样「AI 想改 X 但被拒」和「用户点了允许」在审计里是两条独立的证据）。
+    AwaitingConfirmation,
+    /// 模型调了不存在的工具。
+    UnknownTool,
+}
+
+/// 一条审计记录。
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct AuditRecord {
+    /// RFC3339 UTC。
+    pub ts: String,
+    /// 会话 id（agent 对话框的会话，不是游戏会话）。
+    pub agent_session_id: String,
+    /// 工具名。
+    pub tool: String,
+    /// 参数（已脱敏）。
+    pub args: Value,
+    /// 结局。
+    pub outcome: AuditOutcome,
+    /// 一句话结果摘要。
+    pub summary: String,
+    /// 是否运行在 YOLO 模式。
+    pub yolo: bool,
+    /// 是否经过用户确认（YOLO 下为 false——自动放行不是"确认"）。
+    pub confirmed: bool,
+    /// 工具执行耗时（毫秒）。
+    pub duration_ms: u64,
+}
+
+/// 审计出口。
+pub trait AuditSink: Send + Sync {
+    /// 记录一条（实现方不应阻塞工具执行链；失败自行吞掉并留痕）。
+    fn record(&self, record: &AuditRecord);
+}
+
+/// 按天滚动的 JSONL 审计（生产实现）。
+pub struct JsonlAudit {
+    dir: PathBuf,
+    clock: SharedClock,
+    guard: Mutex<()>,
+}
+
+impl JsonlAudit {
+    /// `dir` 通常是 `<data_root>/agent/audit`；目录按需创建。
+    #[must_use]
+    pub fn new(dir: impl Into<PathBuf>, clock: SharedClock) -> Self {
+        Self {
+            dir: dir.into(),
+            clock,
+            guard: Mutex::new(()),
+        }
+    }
+
+    /// 给定时刻对应的文件路径（测试与 UI「查看审计」共用）。
+    #[must_use]
+    pub fn path_for(&self, unix_ms: u64) -> PathBuf {
+        self.dir
+            .join(format!("audit-{}.jsonl", date_of_unix_ms(unix_ms)))
+    }
+
+    /// 追加一行；失败返回 `std::io::Error`（由 [`AuditSink::record`] 吞掉并打日志）。
+    fn append(&self, record: &AuditRecord) -> std::io::Result<()> {
+        let path = self.path_for(self.clock.now_unix_ms());
+        let line = serde_json::to_string(record)
+            .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))?;
+        if let Some(parent) = path.parent() {
+            std::fs::create_dir_all(parent)?;
+        }
+        let _guard = self.guard.lock();
+        let mut file = OpenOptions::new().create(true).append(true).open(&path)?;
+        file.write_all(line.as_bytes())?;
+        file.write_all(b"\n")
+    }
+}
+
+impl AuditSink for JsonlAudit {
+    fn record(&self, record: &AuditRecord) {
+        if let Err(err) = self.append(record) {
+            // 审计是旁路：写不进去也不能让工具调用失败，但要留下痕迹。
+            eprintln!("[unlucky-agent] 审计写入失败: {err}");
+        }
+    }
+}
+
+/// 内存审计（测试 + 「P0 不落盘」的降级路径）。
+#[derive(Debug, Default)]
+pub struct MemoryAudit {
+    records: Mutex<Vec<AuditRecord>>,
+}
+
+impl MemoryAudit {
+    /// 空审计。
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// 已记录条数。
+    #[must_use]
+    pub fn len(&self) -> usize {
+        self.records.lock().map(|r| r.len()).unwrap_or(0)
+    }
+
+    /// 是否一条都没有。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.len() == 0
+    }
+
+    /// 取快照。
+    #[must_use]
+    pub fn records(&self) -> Vec<AuditRecord> {
+        self.records.lock().map(|r| r.clone()).unwrap_or_default()
+    }
+
+    /// 按工具名筛出记录（测试断言用）。
+    #[must_use]
+    pub fn records_for(&self, tool: &str) -> Vec<AuditRecord> {
+        self.records()
+            .into_iter()
+            .filter(|r| r.tool == tool)
+            .collect()
+    }
+}
+
+impl AuditSink for MemoryAudit {
+    fn record(&self, record: &AuditRecord) {
+        if let Ok(mut records) = self.records.lock() {
+            records.push(record.clone());
+        }
+    }
+}
+
+/// 丢弃审计（不推荐，只给"连内存都不想留"的极端场景/基准测试）。
+#[derive(Debug, Default, Clone, Copy)]
+pub struct NullAudit;
+
+impl AuditSink for NullAudit {
+    fn record(&self, _record: &AuditRecord) {}
+}
+
+/// 组装一条记录时的"其余字段"（时间戳从时钟取，参数先脱敏）。
+#[derive(Debug, Clone, Copy)]
+pub struct AuditDraft<'a> {
+    /// 工具名。
+    pub tool: &'a str,
+    /// 原始参数（内部会脱敏）。
+    pub args: &'a Value,
+    /// 结局。
+    pub outcome: AuditOutcome,
+    /// 一句话结果摘要。
+    pub summary: &'a str,
+    /// 是否 YOLO。
+    pub yolo: bool,
+    /// 是否经用户确认。
+    pub confirmed: bool,
+    /// 耗时（毫秒）。
+    pub duration_ms: u64,
+}
+
+/// 组装一条审计记录（时间戳从时钟取、参数脱敏，调用方不用自己拼）。
+#[must_use]
+pub fn make_record(
+    clock: &dyn crate::clock::Clock,
+    agent_session_id: &str,
+    draft: AuditDraft<'_>,
+) -> AuditRecord {
+    AuditRecord {
+        ts: format_unix_ms(clock.now_unix_ms()),
+        agent_session_id: agent_session_id.to_string(),
+        tool: draft.tool.to_string(),
+        args: redact_args(draft.args),
+        outcome: draft.outcome,
+        summary: draft.summary.to_string(),
+        yolo: draft.yolo,
+        confirmed: draft.confirmed,
+        duration_ms: draft.duration_ms,
+    }
+}
+
+/// 便捷：给出数据根下的审计目录（`<data_root>/agent/audit`）。
+#[must_use]
+pub fn audit_dir(data_root: &Path) -> PathBuf {
+    data_root.join("agent").join("audit")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::clock::FixedClock;
+    use serde_json::json;
+    use std::sync::Arc;
+
+    #[test]
+    fn record_redacts_args_before_store() {
+        let audit = MemoryAudit::new();
+        let clock = FixedClock::new(1_793_304_753_123);
+        let args = json!({ "path": "ai.api_key", "value": "sk-x" });
+        let rec = make_record(
+            &clock,
+            "s1",
+            AuditDraft {
+                tool: "set_config",
+                args: &args,
+                outcome: AuditOutcome::Ok,
+                summary: "ok",
+                yolo: false,
+                confirmed: true,
+                duration_ms: 3,
+            },
+        );
+        audit.record(&rec);
+        let stored = &audit.records()[0];
+        assert_eq!(stored.args["value"], json!("***"), "敏感路径的值必须掩码");
+        assert_eq!(stored.ts, "2026-10-29T20:12:33.123Z");
+    }
+
+    #[test]
+    fn jsonl_audit_writes_one_line_per_record_per_day() {
+        let dir = std::env::temp_dir().join(format!("unlucky-agent-audit-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        let clock: SharedClock = Arc::new(FixedClock::new(1_793_304_753_123));
+        let audit = JsonlAudit::new(&dir, Arc::clone(&clock));
+        let args = json!({});
+        let rec = make_record(
+            clock.as_ref(),
+            "s1",
+            AuditDraft {
+                tool: "get_config",
+                args: &args,
+                outcome: AuditOutcome::Ok,
+                summary: "ok",
+                yolo: false,
+                confirmed: false,
+                duration_ms: 1,
+            },
+        );
+        audit.record(&rec);
+        audit.record(&rec);
+        let path = dir.join("audit-2026-10-29.jsonl");
+        let content = std::fs::read_to_string(&path).expect("审计文件应存在");
+        assert_eq!(content.lines().count(), 2);
+        let first: AuditRecord = serde_json::from_str(content.lines().next().unwrap()).unwrap();
+        assert_eq!(first.tool, "get_config");
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+}

crates/agent/src/brain/chat.rs

@@ -0,0 +1,267 @@
+//! 对话协议类型 + [`ChatProvider`] trait（四态端点配置在 [`super::provider`]）。
+//!
+//! 这里**没有协议方言**：OpenAI/Ollama/Anthropic 的报文差异全部由实现方
+//! （阶段 B 的 [`super::rig`]）吃掉。本模块只定义循环需要的三样东西：
+//! 消息、请求/回复、流式增量回调。
+//!
+//! 一次工具调用的完整往返：
+//! `Assistant { tool_calls }` → 编排层执行 → `Tool { call_id, name, content }` → 再次补全。
+
+use std::future::Future;
+use std::pin::Pin;
+use std::sync::Arc;
+
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+use super::provider::{ProviderConfig, ProviderError};
+use crate::event::{AgentEvent, AgentEventSink};
+use crate::registry::ToolDefinition;
+
+/// 一条工具调用请求（模型产出）。
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct ToolCall {
+    /// 调用 id（OpenAI 方言的 `tool_call_id`；Ollama 原生没有 id，由适配层生成）。
+    pub id: String,
+    /// 工具名。
+    pub name: String,
+    /// 参数（JSON 对象）。
+    pub arguments: Value,
+}
+
+/// 对话消息。
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "role", rename_all = "snake_case")]
+pub enum ChatMessage {
+    /// 系统提示词（每轮由 [`super::BrainConfig::system_prompt`] 重新注入，不进历史）。
+    System {
+        /// 提示词正文。
+        content: String,
+    },
+    /// 用户输入。
+    User {
+        /// 正文。
+        content: String,
+    },
+    /// 模型回复（可能带工具调用）。
+    Assistant {
+        /// 文本正文（工具调用轮可能为空）。
+        text: String,
+        /// 工具调用。
+        tool_calls: Vec<ToolCall>,
+    },
+    /// 工具结果回灌。
+    Tool {
+        /// 对应调用 id。
+        call_id: String,
+        /// 工具名（Ollama 原生靠 `tool_name` 配对，不是 id）。
+        name: String,
+        /// 结果 JSON 字符串。
+        content: String,
+    },
+}
+
+impl ChatMessage {
+    /// 便捷：系统消息。
+    #[must_use]
+    pub fn system(content: impl Into<String>) -> Self {
+        Self::System {
+            content: content.into(),
+        }
+    }
+
+    /// 便捷：用户消息。
+    #[must_use]
+    pub fn user(content: impl Into<String>) -> Self {
+        Self::User {
+            content: content.into(),
+        }
+    }
+
+    /// 便捷：工具结果消息。
+    #[must_use]
+    pub fn tool(
+        call_id: impl Into<String>,
+        name: impl Into<String>,
+        content: impl Into<String>,
+    ) -> Self {
+        Self::Tool {
+            call_id: call_id.into(),
+            name: name.into(),
+            content: content.into(),
+        }
+    }
+}
+
+/// 一次补全请求。
+#[derive(Debug, Clone, PartialEq)]
+pub struct ChatRequest {
+    /// 模型名。
+    pub model: String,
+    /// 消息（system 在首位）。
+    pub messages: Vec<ChatMessage>,
+    /// 工具定义（双投影的 rig 侧载荷）。
+    pub tools: Vec<ToolDefinition>,
+    /// 采样温度。
+    pub temperature: Option<f32>,
+    /// token 上限。
+    pub max_tokens: Option<u32>,
+}
+
+/// token 用量（本地模型可能不报）。
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Usage {
+    /// 输入 token。
+    pub prompt_tokens: Option<u32>,
+    /// 输出 token。
+    pub completion_tokens: Option<u32>,
+}
+
+/// 一次补全结果。
+#[derive(Debug, Clone, Default, PartialEq)]
+pub struct ChatReply {
+    /// 文本正文。
+    pub text: String,
+    /// 工具调用（非空 ⇒ 循环继续）。
+    pub tool_calls: Vec<ToolCall>,
+    /// 用量。
+    pub usage: Option<Usage>,
+}
+
+impl ChatReply {
+    /// 纯文本回复。
+    #[must_use]
+    pub fn text(text: impl Into<String>) -> Self {
+        Self {
+            text: text.into(),
+            tool_calls: Vec::new(),
+            usage: None,
+        }
+    }
+
+    /// 带工具调用的回复。
+    #[must_use]
+    pub fn with_tool_calls(tool_calls: Vec<ToolCall>) -> Self {
+        Self {
+            text: String::new(),
+            tool_calls,
+            usage: None,
+        }
+    }
+}
+
+/// 流式增量接收者。实现方必须**非阻塞**。
+pub trait DeltaObserver: Send + Sync {
+    /// 收到一段文本增量。
+    fn on_delta(&self, text: &str);
+}
+
+/// 丢弃增量（不关心流式的调用方）。
+#[derive(Debug, Default, Clone, Copy)]
+pub struct NoopObserver;
+
+impl DeltaObserver for NoopObserver {
+    fn on_delta(&self, _text: &str) {}
+}
+
+/// 把增量转成 [`AgentEvent::TextDelta`]（P1 聊天面板逐字渲染就靠它）。
+#[derive(Clone)]
+pub struct EventDeltaObserver {
+    sink: Arc<dyn AgentEventSink>,
+}
+
+impl EventDeltaObserver {
+    /// 用事件流构造。
+    #[must_use]
+    pub fn new(sink: Arc<dyn AgentEventSink>) -> Self {
+        Self { sink }
+    }
+}
+
+impl DeltaObserver for EventDeltaObserver {
+    fn on_delta(&self, text: &str) {
+        self.sink.emit(AgentEvent::TextDelta {
+            text: text.to_string(),
+        });
+    }
+}
+
+/// 收集增量（测试断言流式拼接）。
+#[derive(Debug, Default)]
+pub struct CollectingObserver {
+    chunks: std::sync::Mutex<Vec<String>>,
+}
+
+impl CollectingObserver {
+    /// 收完的内容。
+    #[must_use]
+    pub fn collected(&self) -> String {
+        self.chunks.lock().map(|c| c.concat()).unwrap_or_default()
+    }
+}
+
+impl DeltaObserver for CollectingObserver {
+    fn on_delta(&self, text: &str) {
+        if let Ok(mut chunks) = self.chunks.lock() {
+            chunks.push(text.to_string());
+        }
+    }
+}
+
+/// 补全未来的箱子类型。
+pub type ProviderFuture<'a> =
+    Pin<Box<dyn Future<Output = Result<ChatReply, ProviderError>> + Send + 'a>>;
+
+/// LLM 端点抽象：**这是 agent 唯一的异步边界**。
+///
+/// P0 实现 = 测试里的 mock；阶段 B 实现 = [`super::rig`] 的 rig 适配器。
+/// 换实现（genai / 自写循环）只需要满足本 trait，[`super::Brain`] 不动。
+pub trait ChatProvider: Send + Sync {
+    /// 当前配置（循环用它取 model/temperature，也用它判断是否启用）。
+    fn config(&self) -> &ProviderConfig;
+    /// 一次补全。流式增量通过 `observer` 回吐。
+    fn complete<'a>(
+        &'a self,
+        request: &'a ChatRequest,
+        observer: &'a dyn DeltaObserver,
+    ) -> ProviderFuture<'a>;
+}
+
+/// 装配期用的 provider 工厂：按配置造实现（阶段 B 在这里接 rig，测试接 mock）。
+pub type ProviderFactory =
+    Arc<dyn Fn(&ProviderConfig) -> Result<Arc<dyn ChatProvider>, ProviderError> + Send + Sync>;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::event::MemoryEventSink;
+
+    #[test]
+    fn collecting_observer_concatenates_chunks() {
+        let observer = CollectingObserver::default();
+        observer.on_delta("正在");
+        observer.on_delta("读取日志");
+        assert_eq!(observer.collected(), "正在读取日志");
+    }
+
+    #[test]
+    fn event_observer_emits_text_delta() {
+        let sink = Arc::new(MemoryEventSink::new());
+        let observer = EventDeltaObserver::new(sink.clone());
+        observer.on_delta("嗨");
+        assert_eq!(sink.streamed_text(), "嗨");
+    }
+
+    #[test]
+    fn message_helpers_round_trip_through_json() {
+        let messages = vec![
+            ChatMessage::system("你是助手"),
+            ChatMessage::user("看看日志"),
+            ChatMessage::tool("call_1", "read_game_log", "{}"),
+        ];
+        let json = serde_json::to_string(&messages).expect("可序列化");
+        let back: Vec<ChatMessage> = serde_json::from_str(&json).expect("可反序列化");
+        assert_eq!(back, messages);
+        assert!(json.contains("\"role\":\"tool\""));
+    }
+}

crates/agent/src/brain/exec.rs

@@ -0,0 +1,347 @@
+//! 工具执行编排：schema 校验 → 分级确认 → 执行 → 审计 → 事件。
+//!
+//! **YOLO 只在这里**（mission M16 任务 3 的分工）：工具自己不判断 policy，
+//! 只声明「这次需要确认 + diff」；本模块按 [`ConfirmPolicy`] 决定问不问。
+//!
+//! 一次工具调用最多两条审计记录：
+//! 1. 需要确认时先记一条 `awaiting_confirmation`（「AI 想改 X」本身必须留痕）；
+//! 2. 结局记一条 `ok` / `denied` / `tool_error`（带 `yolo` 与 `confirmed` 标记）。
+//!
+//! 这两条区分了三种在复盘里完全不同的事：用户点了拒绝、YOLO 自动放行、用户点了允许。
+
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::Arc;
+
+use serde_json::{json, Value};
+
+use crate::audit::{make_record, AuditDraft, AuditOutcome, AuditSink};
+use crate::brain::chat::ToolCall;
+use crate::clock::SharedClock;
+use crate::confirm::{ConfirmDecision, ConfirmGate, ConfirmPolicy, ConfirmRequest, DenyGuidance};
+use crate::event::{AgentEvent, AgentEventSink};
+use crate::registry::validate::validate;
+use crate::registry::{ToolCtx, ToolError, ToolRegistry};
+
+/// 一次工具执行的结局（回灌给模型的内容 + 成败标记）。
+#[derive(Debug, Clone, PartialEq)]
+pub struct ToolExecOutcome {
+    /// 回灌内容（结构化）。
+    pub content: Value,
+    /// 是否成功（UI/事件用；模型看的是 `content`）。
+    pub ok: bool,
+}
+
+impl ToolExecOutcome {
+    /// 成功。
+    #[must_use]
+    pub fn ok(content: Value) -> Self {
+        Self { content, ok: true }
+    }
+
+    /// 失败（`code` 给模型看，帮助它改正后重试）。
+    #[must_use]
+    pub fn error(code: &str, message: impl Into<String>) -> Self {
+        Self {
+            content: json!({ "status": "error", "code": code, "message": message.into() }),
+            ok: false,
+        }
+    }
+
+    /// 序列化成回灌给模型的字符串（工具消息的 `content`）。
+    #[must_use]
+    pub fn to_model_content(&self) -> String {
+        serde_json::to_string(&self.content).unwrap_or_else(|_| {
+            json!({ "status": "error", "code": "internal", "message": "结果序列化失败" })
+                .to_string()
+        })
+    }
+}
+
+/// 工具执行器（无状态，可跨轮复用）。
+pub struct ToolExecutor {
+    registry: Arc<ToolRegistry>,
+    audit: Arc<dyn AuditSink>,
+    gate: Arc<dyn ConfirmGate>,
+    policy: ConfirmPolicy,
+    clock: SharedClock,
+    sink: Arc<dyn AgentEventSink>,
+    guidance: DenyGuidance,
+    confirm_seq: AtomicU64,
+}
+
+impl ToolExecutor {
+    /// 装配（默认拒绝口径 = 内置对话：[`DenyGuidance::InApp`]）。
+    pub fn new(
+        registry: Arc<ToolRegistry>,
+        audit: Arc<dyn AuditSink>,
+        gate: Arc<dyn ConfirmGate>,
+        policy: ConfirmPolicy,
+        clock: SharedClock,
+        sink: Arc<dyn AgentEventSink>,
+    ) -> Self {
+        Self {
+            registry,
+            audit,
+            gate,
+            policy,
+            clock,
+            sink,
+            guidance: DenyGuidance::InApp,
+            confirm_seq: AtomicU64::new(0),
+        }
+    }
+
+    /// 换拒绝口径（外部 MCP 客户端用 [`DenyGuidance::External`]：没有弹窗可点）。
+    ///
+    /// 只改**文案**：策略、闸门、审计标记一个字都不变——这正是「同一注册表、
+    /// 同一安全策略、同一审计」在代码上的落点。
+    #[must_use]
+    pub fn with_guidance(mut self, guidance: DenyGuidance) -> Self {
+        self.guidance = guidance;
+        self
+    }
+
+    /// 执行一次工具调用（含确认与审计）。
+    pub async fn execute(
+        &self,
+        agent_session_id: &str,
+        call: &ToolCall,
+        step: usize,
+    ) -> ToolExecOutcome {
+        let started_at = self.clock.now_unix_ms();
+        self.sink.emit(AgentEvent::ToolCallStarted {
+            tool: call.name.clone(),
+            // 与审计同一套脱敏：事件（P1 会持久化）不能带出凭据明文。
+            args: crate::redact::redact_args(&call.arguments),
+            step,
+        });
+
+        let Some(spec) = self.registry.get(&call.name).cloned() else {
+            let message = format!(
+                "没有名为 `{}` 的工具。可用工具：{}",
+                call.name,
+                self.registry.names().join("、")
+            );
+            self.record(
+                agent_session_id,
+                &call.name,
+                &call.arguments,
+                AuditOutcome::UnknownTool,
+                &message,
+                false,
+                false,
+                started_at,
+            );
+            self.finish_event(&call.name, false, &message, false);
+            return ToolExecOutcome::error("unknown_tool", message);
+        };
+
+        if let Err(errors) = validate(&spec.input_schema, &call.arguments) {
+            let message = format!("参数不合法：{}", errors.join("；"));
+            self.record(
+                agent_session_id,
+                &call.name,
+                &call.arguments,
+                AuditOutcome::InvalidArgs,
+                &message,
+                false,
+                false,
+                started_at,
+            );
+            self.finish_event(&call.name, false, &message, false);
+            return ToolExecOutcome::error("invalid_args", message);
+        }
+
+        let ctx = ToolCtx {
+            agent_session_id: agent_session_id.to_string(),
+            confirmed: false,
+        };
+        let quoted = match (spec.handler)(&ctx, &call.arguments) {
+            Ok(output) => output,
+            Err(err) => return self.fail(agent_session_id, call, err, started_at),
+        };
+
+        let Some(confirmation) = quoted.confirmation.clone() else {
+            return self.succeed(agent_session_id, call, quoted, false, false, started_at);
+        };
+
+        // ── 需要确认：决定问不问（YOLO 只影响这里）──
+        let asked = self.policy.requires_confirmation(confirmation.sensitivity);
+        let yolo_auto = !asked && confirmation.sensitivity == crate::confirm::Sensitivity::High;
+
+        if asked {
+            self.record(
+                agent_session_id,
+                &call.name,
+                &call.arguments,
+                AuditOutcome::AwaitingConfirmation,
+                &confirmation.summary,
+                false,
+                false,
+                started_at,
+            );
+            let request = ConfirmRequest {
+                id: format!(
+                    "confirm-{}",
+                    self.confirm_seq.fetch_add(1, Ordering::Relaxed) + 1
+                ),
+                tool: call.name.clone(),
+                summary: confirmation.summary.clone(),
+                details: confirmation.details.clone(),
+                sensitivity: confirmation.sensitivity,
+            };
+            self.sink.emit(AgentEvent::ConfirmRequested {
+                request: Box::new(request.clone()),
+            });
+            if self.gate.request(request).await == ConfirmDecision::Denied {
+                let message = self.guidance.message().to_string();
+                self.record(
+                    agent_session_id,
+                    &call.name,
+                    &call.arguments,
+                    AuditOutcome::Denied,
+                    &message,
+                    false,
+                    false,
+                    started_at,
+                );
+                self.sink.emit(AgentEvent::ToolDenied {
+                    tool: call.name.clone(),
+                    reason: message.clone(),
+                });
+                self.finish_event(&call.name, false, &message, true);
+                return ToolExecOutcome::error("denied", message);
+            }
+        }
+
+        // ── 已获授权（用户允许或 YOLO）：带 confirmed 重放 ──
+        let confirmed_ctx = ToolCtx {
+            agent_session_id: agent_session_id.to_string(),
+            confirmed: true,
+        };
+        match (spec.handler)(&confirmed_ctx, &call.arguments) {
+            Ok(output) => {
+                if let Some(second) = output.confirmation {
+                    // 工具在"已确认"状态下仍要确认 = 实现写错了，明确报出来而不是死循环。
+                    let message = format!(
+                        "工具 `{}` 在已确认状态下仍请求确认：{}",
+                        call.name, second.summary
+                    );
+                    self.record(
+                        agent_session_id,
+                        &call.name,
+                        &call.arguments,
+                        AuditOutcome::ToolError,
+                        &message,
+                        yolo_auto,
+                        asked,
+                        started_at,
+                    );
+                    self.finish_event(&call.name, false, &message, true);
+                    return ToolExecOutcome::error("internal", message);
+                }
+                self.succeed(agent_session_id, call, output, asked, yolo_auto, started_at)
+            }
+            Err(err) => {
+                self.fail_after_confirm(agent_session_id, call, err, asked, yolo_auto, started_at)
+            }
+        }
+    }
+
+    fn succeed(
+        &self,
+        agent_session_id: &str,
+        call: &ToolCall,
+        output: crate::registry::ToolOutput,
+        confirmed: bool,
+        yolo: bool,
+        started_at: u64,
+    ) -> ToolExecOutcome {
+        self.record(
+            agent_session_id,
+            &call.name,
+            &call.arguments,
+            AuditOutcome::Ok,
+            &output.summary,
+            yolo,
+            confirmed,
+            started_at,
+        );
+        self.finish_event(
+            &call.name,
+            true,
+            &output.summary,
+            output.confirmation.is_some(),
+        );
+        ToolExecOutcome::ok(output.content)
+    }
+
+    fn fail(
+        &self,
+        agent_session_id: &str,
+        call: &ToolCall,
+        err: ToolError,
+        started_at: u64,
+    ) -> ToolExecOutcome {
+        self.fail_after_confirm(agent_session_id, call, err, false, false, started_at)
+    }
+
+    fn fail_after_confirm(
+        &self,
+        agent_session_id: &str,
+        call: &ToolCall,
+        err: ToolError,
+        confirmed: bool,
+        yolo: bool,
+        started_at: u64,
+    ) -> ToolExecOutcome {
+        let message = err.message().to_string();
+        self.record(
+            agent_session_id,
+            &call.name,
+            &call.arguments,
+            AuditOutcome::ToolError,
+            &message,
+            yolo,
+            confirmed,
+            started_at,
+        );
+        self.finish_event(&call.name, false, &message, false);
+        ToolExecOutcome::error(err.code(), message)
+    }
+
+    #[allow(clippy::too_many_arguments)]
+    fn record(
+        &self,
+        agent_session_id: &str,
+        tool: &str,
+        args: &Value,
+        outcome: AuditOutcome,
+        summary: &str,
+        yolo: bool,
+        confirmed: bool,
+        started_at: u64,
+    ) {
+        let duration_ms = self.clock.now_unix_ms().saturating_sub(started_at);
+        let draft = AuditDraft {
+            tool,
+            args,
+            outcome,
+            summary,
+            yolo,
+            confirmed,
+            duration_ms,
+        };
+        self.audit
+            .record(&make_record(self.clock.as_ref(), agent_session_id, draft));
+    }
+
+    fn finish_event(&self, tool: &str, ok: bool, summary: &str, requires_confirmation: bool) {
+        self.sink.emit(AgentEvent::ToolCallFinished {
+            tool: tool.to_string(),
+            ok,
+            summary: summary.to_string(),
+            requires_confirmation,
+        });
+    }
+}

crates/agent/src/brain/mod.rs

@@ -0,0 +1,323 @@
+//! Agent 大脑：Provider 抽象 + 对话循环 + 流式事件。
+//!
+//! 选型（M10 定稿）：`rig-core` + `rig-agent`，**版本锁 `=0.45.x`**——上游 12 周 5 个 minor
+//! 的 breaking 频率决定了必须锁死；依赖面只在本文件收口，其它模块不许直接碰 rig，
+//! 以便随时换 genai / 自写循环逃生（`DevDocs/PlanDoc/02-ai-agent-design.md` §0）。
+//!
+//! Provider 形态（02 §2）：OpenAI 兼容（默认，含本地 llama.cpp `127.0.0.1:PORT/v1`）、
+//! Anthropic 原生、Ollama 原生、以及「禁用」——禁用时规则引擎仍可用。
+//!
+//! 统一 trait（M16 落地）：`stream_chat(messages, tools) -> Stream<Event>`，含 tool_call 事件。
+//! 本 crate 的落地形态是 [`chat::ChatProvider::complete`]（`request + observer → ChatReply`）：
+//! rig 0.45 的流在 [`rig`] 适配层里展开成增量回调，循环侧只消费「文本增量 + 工具调用」两件事。
+//! **rig 依赖面收口在 [`rig`] 一个文件**，本文件不 `use rig_*`。
+//!
+//! ## 对话循环（02 文档 §3.3）
+//!
+//! ```text
+//! run_turn(user_input)
+//!   ├─ provider.complete(request)  ← 流式增量经 EventDeltaObserver → UI
+//!   ├─ 有 tool_calls → ToolExecutor.execute（校验/确认/YOLO/审计）→ Tool 消息回灌
+//!   └─ 没有 tool_calls → 结束，返回最终文本
+//! ```
+//!
+//! 三条不变量：
+//! 1. **system prompt 每轮重新注入**，不进历史（改提示词立刻生效，也不会被压缩逻辑吃掉）；
+//! 2. 工具结果**永远回灌**（包括失败），模型才有机会改正；
+//! 3. 步数上限 [`DEFAULT_MAX_STEPS`] 兜底，防止模型在两个工具间打转烧 token。
+
+pub mod chat;
+pub mod exec;
+pub mod provider;
+pub mod rig;
+
+use std::fmt;
+use std::sync::Arc;
+
+use crate::audit::AuditSink;
+use crate::clock::SharedClock;
+use crate::confirm::{ConfirmGate, ConfirmPolicy};
+use crate::event::{AgentEvent, AgentEventSink};
+use crate::registry::ToolRegistry;
+
+pub use chat::{
+    ChatMessage, ChatProvider, ChatReply, ChatRequest, DeltaObserver, EventDeltaObserver,
+    NoopObserver, ProviderFactory, ProviderFuture, ToolCall, Usage,
+};
+pub use exec::{ToolExecOutcome, ToolExecutor};
+pub use provider::{ProviderConfig, ProviderError, ProviderKind};
+
+/// 一轮对话最多几轮工具调用。
+pub const DEFAULT_MAX_STEPS: usize = 8;
+
+/// 内置系统提示词（P0 版本；P2 会按实例上下文按需注入）。
+#[must_use]
+pub fn default_system_prompt() -> String {
+    [
+        "你是 Unlucky-Launcher（ULL，Minecraft 启动器）的内置助手。",
+        "你能调用工具：读配置（get_config）、改配置（set_config）、列出游戏会话（list_game_sessions）、",
+        "读会话日志（read_game_log）、跑崩溃规则引擎（diagnose_crash）。",
+        "纪律：",
+        "1. 先查后改：改任何配置前先用 get_config 确认键名与现值。",
+        "2. 崩溃问题先看 diagnose_crash 的规则结论；规则未命中或需要更多信息时，才用 read_game_log",
+        "   取 stderr / exit / crash_found，不要拉全量日志。",
+        "3. 只能改 get_config 列出的可写键。敏感键会要求用户确认：被拒绝就换方案，不要重复尝试同一改动。",
+        "4. 用中文回答，给用户可以立即执行的下一步；不确定时直说不确定，不要编造规则或日志内容。",
+    ]
+    .join("\n")
+}
+
+/// 循环参数。
+#[derive(Debug, Clone)]
+pub struct BrainConfig {
+    /// 最多几轮工具调用。
+    pub max_steps: usize,
+    /// 系统提示词。
+    pub system_prompt: String,
+}
+
+impl Default for BrainConfig {
+    fn default() -> Self {
+        Self {
+            max_steps: DEFAULT_MAX_STEPS,
+            system_prompt: default_system_prompt(),
+        }
+    }
+}
+
+impl BrainConfig {
+    /// 自定义提示词（步数用默认）。
+    #[must_use]
+    pub fn with_system_prompt(system_prompt: impl Into<String>) -> Self {
+        Self {
+            max_steps: DEFAULT_MAX_STEPS,
+            system_prompt: system_prompt.into(),
+        }
+    }
+}
+
+/// 循环的旁路依赖（审计/确认/时钟/事件）。
+pub struct BrainDeps {
+    /// 审计出口。
+    pub audit: Arc<dyn AuditSink>,
+    /// 确认闸门（P0 = [`crate::confirm::NoUiGate`]）。
+    pub gate: Arc<dyn ConfirmGate>,
+    /// YOLO 等策略快照。
+    pub policy: ConfirmPolicy,
+    /// 时间源。
+    pub clock: SharedClock,
+    /// 事件出口。
+    pub sink: Arc<dyn AgentEventSink>,
+}
+
+impl BrainDeps {
+    /// 装配。
+    pub fn new(
+        audit: Arc<dyn AuditSink>,
+        gate: Arc<dyn ConfirmGate>,
+        policy: ConfirmPolicy,
+        clock: SharedClock,
+        sink: Arc<dyn AgentEventSink>,
+    ) -> Self {
+        Self {
+            audit,
+            gate,
+            policy,
+            clock,
+            sink,
+        }
+    }
+}
+
+/// 一轮对话的结局。
+#[derive(Debug, Clone, PartialEq)]
+pub struct TurnOutcome {
+    /// 最终文本（可能是空的，例如撞上步数上限且模型最后一句只有工具调用）。
+    pub text: String,
+    /// 用掉的轮次。
+    pub steps: usize,
+    /// 工具调用总次数。
+    pub tool_calls: usize,
+    /// 为什么停下来。
+    pub stopped_reason: StopReason,
+}
+
+/// 停止原因。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum StopReason {
+    /// 模型给出了最终回答。
+    Completed,
+    /// 撞上 [`BrainConfig::max_steps`]。
+    StepLimit,
+}
+
+/// 循环级错误。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum BrainError {
+    /// AI 被禁用（规则引擎仍可用）。
+    Disabled,
+    /// provider 报错。
+    Provider(ProviderError),
+}
+
+impl fmt::Display for BrainError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Disabled => f.write_str(DISABLED_MESSAGE),
+            Self::Provider(err) => write!(f, "LLM 调用失败：{err}"),
+        }
+    }
+}
+
+impl std::error::Error for BrainError {}
+
+/// AI 被禁用时给用户的话（装配层直接展示，不用先构造 Brain）。
+pub const DISABLED_MESSAGE: &str =
+    "AI 已禁用：请在设置 → AI 中配置端点。规则引擎崩溃诊断不受影响。";
+
+/// 对话循环。
+pub struct Brain {
+    provider: Arc<dyn ChatProvider>,
+    registry: Arc<ToolRegistry>,
+    executor: ToolExecutor,
+    config: BrainConfig,
+    sink: Arc<dyn AgentEventSink>,
+}
+
+impl Brain {
+    /// 装配。
+    pub fn new(
+        provider: Arc<dyn ChatProvider>,
+        registry: Arc<ToolRegistry>,
+        deps: BrainDeps,
+        config: BrainConfig,
+    ) -> Self {
+        let executor = ToolExecutor::new(
+            Arc::clone(&registry),
+            Arc::clone(&deps.audit),
+            Arc::clone(&deps.gate),
+            deps.policy,
+            Arc::clone(&deps.clock),
+            Arc::clone(&deps.sink),
+        );
+        Self {
+            provider,
+            registry,
+            executor,
+            config,
+            sink: deps.sink,
+        }
+    }
+
+    /// 当前 provider 配置（设置页/UI 展示用）。
+    #[must_use]
+    pub fn provider_config(&self) -> &ProviderConfig {
+        self.provider.config()
+    }
+
+    /// 跑一轮对话。`history` 由调用方持有（P1 落盘为 `agent/sessions/*.jsonl`）。
+    ///
+    /// # Errors
+    /// AI 被禁用（[`BrainError::Disabled`]）或 provider 报错（[`BrainError::Provider`]）。
+    pub async fn run_turn(
+        &self,
+        agent_session_id: &str,
+        history: &mut Vec<ChatMessage>,
+        user_input: &str,
+    ) -> Result<TurnOutcome, BrainError> {
+        if !self.provider.config().is_enabled() {
+            self.sink.emit(AgentEvent::Error {
+                message: DISABLED_MESSAGE.to_string(),
+            });
+            return Err(BrainError::Disabled);
+        }
+
+        self.sink.emit(AgentEvent::TurnStarted {
+            session_id: agent_session_id.to_string(),
+            user_text: user_input.to_string(),
+        });
+        history.push(ChatMessage::user(user_input));
+
+        let observer = EventDeltaObserver::new(Arc::clone(&self.sink));
+        let mut tool_calls = 0usize;
+        let mut last_text = String::new();
+        let mut used_steps = 0usize;
+
+        for step in 1..=self.config.max_steps {
+            used_steps = step;
+            let request = self.build_request(history);
+            let reply = match self.provider.complete(&request, &observer).await {
+                Ok(reply) => reply,
+                Err(err) => {
+                    self.sink.emit(AgentEvent::Error {
+                        message: err.to_string(),
+                    });
+                    return Err(BrainError::Provider(err));
+                }
+            };
+
+            if !reply.text.trim().is_empty() {
+                last_text = reply.text.clone();
+                self.sink.emit(AgentEvent::AssistantText {
+                    text: reply.text.clone(),
+                });
+            }
+
+            if reply.tool_calls.is_empty() {
+                history.push(ChatMessage::Assistant {
+                    text: reply.text.clone(),
+                    tool_calls: Vec::new(),
+                });
+                self.sink.emit(AgentEvent::TurnFinished {
+                    steps: step,
+                    text: reply.text.clone(),
+                });
+                return Ok(TurnOutcome {
+                    text: reply.text,
+                    steps: step,
+                    tool_calls,
+                    stopped_reason: StopReason::Completed,
+                });
+            }
+
+            history.push(ChatMessage::Assistant {
+                text: reply.text.clone(),
+                tool_calls: reply.tool_calls.clone(),
+            });
+            for call in &reply.tool_calls {
+                let outcome = self.executor.execute(agent_session_id, call, step).await;
+                tool_calls += 1;
+                history.push(ChatMessage::tool(
+                    call.id.clone(),
+                    call.name.clone(),
+                    outcome.to_model_content(),
+                ));
+            }
+        }
+
+        self.sink.emit(AgentEvent::TurnFinished {
+            steps: used_steps,
+            text: last_text.clone(),
+        });
+        Ok(TurnOutcome {
+            text: last_text,
+            steps: used_steps,
+            tool_calls,
+            stopped_reason: StopReason::StepLimit,
+        })
+    }
+
+    fn build_request(&self, history: &[ChatMessage]) -> ChatRequest {
+        let config = self.provider.config();
+        let mut messages = Vec::with_capacity(history.len() + 1);
+        messages.push(ChatMessage::system(self.config.system_prompt.clone()));
+        messages.extend_from_slice(history);
+        ChatRequest {
+            model: config.model.clone(),
+            messages,
+            tools: self.registry.definitions(),
+            temperature: config.temperature,
+            max_tokens: config.max_tokens,
+        }
+    }
+}

crates/agent/src/brain/provider.rs

@@ -0,0 +1,340 @@
+//! Provider 四态端点配置（02 文档 §2）。
+//!
+//! | 形态 | 端点 | 备注 |
+//! |------|------|------|
+//! | OpenAI 兼容（默认） | `base_url` + `api_key` + `model` | 覆盖 OpenAI/DeepSeek/Qwen/GLM/**本地 llama.cpp server**（`http://127.0.0.1:8080/v1`）/LM Studio |
+//! | Anthropic 原生 | `api_key` + `model` | Claude 系列（没有可用的 Rust 单厂商 SDK，见 research/02 §3.6） |
+//! | Ollama 原生 | `http://127.0.0.1:11434` | 本地另一种主流 |
+//! | 禁用 | — | 完全关闭 agent，规则引擎（`diagnose_crash`）仍可用 |
+//!
+//! 本文件只放**配置与校验**；对话协议在 [`super::chat`]。这样 rig 的 pre-1.0 破坏面
+//! （research/02 §7 R1）被关在 [`super::rig`] 一个文件里，这里连 rig 的名字都不出现。
+
+use std::fmt;
+
+use serde::{Deserialize, Serialize};
+
+/// 本地 llama.cpp server 的默认 OpenAI 兼容端点（research/02 §5.1）。
+pub const LLAMACPP_DEFAULT_BASE_URL: &str = "http://127.0.0.1:8080/v1";
+/// Ollama 默认端点（research/02 §5.2）。
+pub const OLLAMA_DEFAULT_BASE_URL: &str = "http://127.0.0.1:11434";
+/// Anthropic 官方 API 端点。
+pub const ANTHROPIC_DEFAULT_BASE_URL: &str = "https://api.anthropic.com";
+
+/// Provider 四态。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ProviderKind {
+    /// OpenAI 兼容（含本地 llama.cpp / LM Studio / DeepSeek / Qwen…）。
+    OpenAiCompatible,
+    /// Anthropic 原生。
+    Anthropic,
+    /// Ollama 原生。
+    Ollama,
+    /// 完全禁用 agent。
+    Disabled,
+}
+
+impl ProviderKind {
+    /// 该形态是否必须提供 API key（本地推理通常不需要）。
+    #[must_use]
+    pub fn requires_api_key(self) -> bool {
+        matches!(self, Self::Anthropic)
+    }
+
+    /// 该形态的默认端点（OpenAI 兼容没有统一默认值，必须显式填；
+    /// 本地 llama.cpp 走 [`ProviderConfig::llamacpp_local`] 带的显式默认）。
+    #[must_use]
+    pub fn default_base_url(self) -> &'static str {
+        match self {
+            Self::OpenAiCompatible => "",
+            Self::Anthropic => ANTHROPIC_DEFAULT_BASE_URL,
+            Self::Ollama => OLLAMA_DEFAULT_BASE_URL,
+            Self::Disabled => "",
+        }
+    }
+
+    /// 设置页展示名。
+    #[must_use]
+    pub fn display_name(self) -> &'static str {
+        match self {
+            Self::OpenAiCompatible => "OpenAI 兼容",
+            Self::Anthropic => "Anthropic 原生",
+            Self::Ollama => "Ollama 原生",
+            Self::Disabled => "已禁用",
+        }
+    }
+}
+
+/// Provider 配置（设置 → AI 的一份快照）。
+///
+/// `api_key` 只在进程内存在，**任何日志/审计/事件都不得带它**——
+/// `Debug` 是手写的（掩码 key），要连形态一起看用 [`ProviderConfig::redacted_debug`]。
+#[derive(Clone, PartialEq, Serialize, Deserialize)]
+pub struct ProviderConfig {
+    /// 四态。
+    pub kind: ProviderKind,
+    /// 端点；空串表示用 [`ProviderKind::default_base_url`]。
+    pub base_url: String,
+    /// 模型名；`Disabled` 时可为空。
+    pub model: String,
+    /// API key（本地推理可空）。
+    pub api_key: Option<String>,
+    /// 采样温度。
+    pub temperature: Option<f32>,
+    /// 单次回复 token 上限。
+    pub max_tokens: Option<u32>,
+}
+
+impl Default for ProviderConfig {
+    fn default() -> Self {
+        Self::disabled()
+    }
+}
+
+impl ProviderConfig {
+    fn base(kind: ProviderKind, base_url: &str, model: &str) -> Self {
+        Self {
+            kind,
+            base_url: base_url.to_string(),
+            model: model.to_string(),
+            api_key: None,
+            temperature: None,
+            max_tokens: None,
+        }
+    }
+
+    /// OpenAI 兼容端点（云端或自建）。
+    #[must_use]
+    pub fn openai_compatible(base_url: &str, model: &str) -> Self {
+        Self::base(ProviderKind::OpenAiCompatible, base_url, model)
+    }
+
+    /// 本机 llama.cpp server（用户就在跑 llama-server 的默认场景）。
+    #[must_use]
+    pub fn llamacpp_local(model: &str) -> Self {
+        Self::base(
+            ProviderKind::OpenAiCompatible,
+            LLAMACPP_DEFAULT_BASE_URL,
+            model,
+        )
+    }
+
+    /// Anthropic 原生。
+    #[must_use]
+    pub fn anthropic(model: &str) -> Self {
+        Self::base(ProviderKind::Anthropic, ANTHROPIC_DEFAULT_BASE_URL, model)
+    }
+
+    /// 本机 Ollama。
+    #[must_use]
+    pub fn ollama(model: &str) -> Self {
+        Self::base(ProviderKind::Ollama, OLLAMA_DEFAULT_BASE_URL, model)
+    }
+
+    /// 禁用 agent。
+    #[must_use]
+    pub fn disabled() -> Self {
+        Self::base(ProviderKind::Disabled, "", "")
+    }
+
+    /// 带上 API key。
+    #[must_use]
+    pub fn with_api_key(mut self, api_key: impl Into<String>) -> Self {
+        self.api_key = Some(api_key.into());
+        self
+    }
+
+    /// 带上温度。
+    #[must_use]
+    pub fn with_temperature(mut self, temperature: f32) -> Self {
+        self.temperature = Some(temperature);
+        self
+    }
+
+    /// agent 是否启用。
+    #[must_use]
+    pub fn is_enabled(&self) -> bool {
+        self.kind != ProviderKind::Disabled
+    }
+
+    /// 实际使用的端点（空则回落默认值）。
+    #[must_use]
+    pub fn resolved_base_url(&self) -> &str {
+        if self.base_url.trim().is_empty() {
+            self.kind.default_base_url()
+        } else {
+            self.base_url.trim()
+        }
+    }
+
+    /// 配置是否可用（装配期调用一次，错就进设置页提示而不是等到对话时炸）。
+    ///
+    /// # Errors
+    /// 禁用、缺模型名、缺端点、缺 API key 时返回可读错误。
+    pub fn validate(&self) -> Result<(), ProviderError> {
+        if !self.is_enabled() {
+            return Err(ProviderError::new(
+                "AI 已禁用：请在设置 → AI 中选择端点（规则引擎诊断不受影响）",
+            ));
+        }
+        if self.model.trim().is_empty() {
+            return Err(ProviderError::new("没有配置模型名（model）"));
+        }
+        if self.resolved_base_url().trim().is_empty() {
+            return Err(ProviderError::new(format!(
+                "{} 需要填写端点（base_url）",
+                self.kind.display_name()
+            )));
+        }
+        if self.kind.requires_api_key()
+            && self
+                .api_key
+                .as_deref()
+                .is_none_or(|key| key.trim().is_empty())
+        {
+            return Err(ProviderError::new(format!(
+                "{} 需要 API key",
+                self.kind.display_name()
+            )));
+        }
+        Ok(())
+    }
+
+    /// 可打印的形态描述（**key 已掩码**，给日志/审计/设置页用）。
+    #[must_use]
+    pub fn redacted_debug(&self) -> String {
+        let key = match self.api_key.as_deref() {
+            None => "无".to_string(),
+            Some(k) if k.trim().is_empty() => "无".to_string(),
+            Some(_) => crate::redact::MASK.to_string(),
+        };
+        format!(
+            "{} base_url={} model={} api_key={key}",
+            self.kind.display_name(),
+            self.resolved_base_url(),
+            if self.model.is_empty() {
+                "（未设置）"
+            } else {
+                &self.model
+            },
+        )
+    }
+}
+
+impl fmt::Debug for ProviderConfig {
+    /// 手写 Debug：**key 掩码**（`api_key` 是唯一不能出现在日志里的字段）。
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("ProviderConfig")
+            .field("kind", &self.kind)
+            .field("base_url", &self.resolved_base_url())
+            .field("model", &self.model)
+            .field(
+                "api_key",
+                &self.api_key.as_deref().map(|_| crate::redact::MASK),
+            )
+            .field("temperature", &self.temperature)
+            .field("max_tokens", &self.max_tokens)
+            .finish()
+    }
+}
+
+/// Provider 层错误（消息面向用户：端点连不上、key 无效、模型不存在）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProviderError {
+    message: String,
+}
+
+impl ProviderError {
+    /// 从可读文本构造。
+    #[must_use]
+    pub fn new(message: impl Into<String>) -> Self {
+        Self {
+            message: message.into(),
+        }
+    }
+}
+
+impl fmt::Display for ProviderError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(&self.message)
+    }
+}
+
+impl std::error::Error for ProviderError {}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn local_defaults_match_research() {
+        assert_eq!(
+            ProviderConfig::llamacpp_local("qwen2.5").resolved_base_url(),
+            LLAMACPP_DEFAULT_BASE_URL
+        );
+        assert_eq!(
+            ProviderConfig::ollama("llama3").resolved_base_url(),
+            OLLAMA_DEFAULT_BASE_URL
+        );
+        assert_eq!(
+            ProviderConfig::anthropic("claude-sonnet-4").resolved_base_url(),
+            ANTHROPIC_DEFAULT_BASE_URL
+        );
+    }
+
+    #[test]
+    fn validate_requires_model_base_url_and_key() {
+        assert!(!ProviderConfig::disabled().is_enabled());
+        assert!(ProviderConfig::disabled().validate().is_err());
+        assert!(ProviderConfig::llamacpp_local("").validate().is_err());
+        assert!(ProviderConfig::llamacpp_local("qwen").validate().is_ok());
+        // OpenAI 兼容必须显式给端点
+        assert!(ProviderConfig::openai_compatible("", "gpt-4o-mini")
+            .validate()
+            .is_err());
+        assert!(
+            ProviderConfig::openai_compatible("https://api.deepseek.com/v1", "deepseek-chat")
+                .validate()
+                .is_ok()
+        );
+        assert!(ProviderConfig::anthropic("claude").validate().is_err());
+        assert!(ProviderConfig::anthropic("claude")
+            .with_api_key("sk-ant")
+            .validate()
+            .is_ok());
+    }
+
+    #[test]
+    fn redacted_debug_never_leaks_key() {
+        let config =
+            ProviderConfig::openai_compatible("https://api.deepseek.com/v1", "deepseek-chat")
+                .with_api_key("sk-super-secret");
+        let text = config.redacted_debug();
+        assert!(!text.contains("sk-super-secret"), "{text}");
+        assert!(text.contains(crate::redact::MASK));
+        // `{:?}` 也必须掩码：Debug 是 panic 消息/日志的默认出口。
+        let debug = format!("{config:?}");
+        assert!(!debug.contains("sk-super-secret"), "{debug}");
+        assert!(debug.contains(crate::redact::MASK), "{debug}");
+    }
+
+    #[test]
+    fn empty_base_url_falls_back_to_default() {
+        let mut config = ProviderConfig::ollama("llama3");
+        config.base_url = String::new();
+        assert_eq!(config.resolved_base_url(), OLLAMA_DEFAULT_BASE_URL);
+    }
+
+    #[test]
+    fn four_states_serialize_as_snake_case() {
+        assert_eq!(
+            serde_json::to_string(&ProviderKind::OpenAiCompatible).unwrap(),
+            "\"open_ai_compatible\""
+        );
+        assert_eq!(
+            serde_json::to_string(&ProviderConfig::disabled()).unwrap(),
+            "{\"kind\":\"disabled\",\"base_url\":\"\",\"model\":\"\",\"api_key\":null,\"temperature\":null,\"max_tokens\":null}"
+        );
+    }
+}

crates/agent/src/brain/rig.rs

@@ -0,0 +1,368 @@
+//! rig 适配层：[`ChatProvider`] 的**唯一**实现，也是整个 crate 唯一允许 `use rig_*` 的文件。
+//!
+//! 依赖面收窄纪律（`DevDocs/PlanDoc/02-ai-agent-design.md` §0 + research/02 §7 R1）：
+//! rig 是 pre-1.0、12 周 5 个 minor、CHANGELOG 满是 `[**breaking**]`（0.43 把 MCP 拆出 rig-agent、
+//! 0.45 升 rmcp 3.5 并改 owned connection）。所以把它关在这一个文件里：它变了，只有这里编译失败，
+//! [`super::ChatProvider`] 以上的循环/编排/审计一行不用动。
+//!
+//! ## 0.45 的接线（实读源码，非照文档猜）
+//!
+//! ```text
+//! ProviderConfig ─┬─ OpenAiCompatible → OpenAIConfig::new(key).with_base_url(url).client().chat(model)
+//!                 ├─ Anthropic        → AnthropicConfig::new(key).with_base_url(url).client().completion(model)
+//!                 ├─ Ollama           → OllamaConfig::new().with_base_url(url).client().completion(model)
+//!                 └─ Disabled         → 不构造（Brain::run_turn 已提前返回）
+//!                        ↓ Model<W>.erase()
+//!                 DynModel<Completion>（wire + transport 擦除，本文件只持有这一个类型）
+//! ```
+//!
+//! 循环侧只要两件事：流式文本增量、以及折好的 [`ChatReply`]（文本 + 工具调用）。
+//! 所以这里用 `model.stream(request)` 边转发 [`StreamEvent::Text`] 增量给 [`DeltaObserver`]，
+//! 最后 `Streamed::finish()` 拿到完整 [`CompletionResponse`]——工具调用从响应里取，
+//! 不自己拼分片 JSON（拼分片是 rig 的 `ReplyFold` 已经做过的事）。
+//!
+//! ## 三个已确认的坑
+//!
+//! 1. **llama.cpp 默认端点就是 `http://localhost:8080/v1`**（`providers/llamacpp/mod.rs`），
+//!    与 [`LLAMACPP_DEFAULT_BASE_URL`] 一致。这里统一走 OpenAI 方言 + 显式 base_url：
+//!    llama.cpp / LM Studio / DeepSeek 都是 OpenAI 兼容面，方言差异主要在默认端点与特有位
+//!    （`chat_template_kwargs`、`num_ctx`）——真要下发这些，再换成 `providers::llamacpp` 方言或
+//!    Ollama 的 `native_completion`。
+//! 2. **Ollama 原生方言的工具结果用 `tool_name` 配对（没有 id）**，OpenAI 方言用 `tool_call_id`。
+//!    这里走 rig 的 `Ollama::completion`（OpenAI 兼容 `/v1/chat/completions`），由 rig 负责回灌形状；
+//!    要下发 `num_ctx`（崩溃日志几千行，上下文必须可配）才需要 `native_completion`，留作 P1。
+//! 3. **取消**：`Streamed` 是普通 future/stream，丢弃即断开——P0 用「丢弃 future」实现停止生成，
+//!    P1 接 UI 的「停止」按钮时按 rig 的取消语义（drop stream）对齐即可，不需要 unsafe。
+//!
+//! ## 逃生口（保留但不是 Plan A）
+//!
+//! rig 的破坏变更真伤到（或 Rust 1.92 MSRV 追不上 rig 的 1.97.1）时：换 `genai`
+//! （provider + function calling，无 agent 循环）或自己写 OpenAI 方言（约 300~500 行）。
+//! **代价只是实现一个新的 [`ChatProvider`]**——这正是把它关在一个文件里的意义。
+//!
+//! [`LLAMACPP_DEFAULT_BASE_URL`]: super::provider::LLAMACPP_DEFAULT_BASE_URL
+//! [`StreamEvent::Text`]: rig_core::streaming::StreamEvent::Text
+
+use std::sync::Arc;
+
+use futures_util::StreamExt;
+use rig_core::completion::{CompletionRequest, ToolDefinition as RigToolDefinition};
+use rig_core::error::ProviderError as RigError;
+use rig_core::message::{
+    AssistantContent as RigAssistantContent, AssistantMessage as RigAssistantMessage, CallId,
+    Message as RigMessage, Text as RigText, ToolCall as RigToolCall, ToolFunction,
+    ToolName as RigToolName, ToolResult, ToolResultContent, UserContent,
+};
+use rig_core::operation::Completion;
+use rig_core::providers::anthropic::AnthropicConfig;
+use rig_core::providers::ollama::OllamaConfig;
+use rig_core::providers::openai::OpenAIConfig;
+use rig_core::streaming::{Item, StreamEvent};
+use rig_core::DynModel;
+
+use super::chat::{
+    ChatMessage, ChatProvider, ChatReply, ChatRequest, DeltaObserver, ProviderFactory,
+    ProviderFuture,
+};
+use super::provider::{ProviderConfig, ProviderError, ProviderKind};
+
+/// 锁定的 rig 版本（与 `Cargo.toml` 的唯一记录点，避免两处不一致）。
+pub const RIG_VERSION_PIN: &str = "=0.45.0";
+
+/// 擦掉 wire / transport 之后的补全模型——本文件对外只暴露这一个 rig 类型之外的东西。
+type ErasedModel = DynModel<Completion>;
+
+/// rig 实现的 [`ChatProvider`]：四态配置 + 一个擦除后的模型。
+pub struct RigProvider {
+    config: ProviderConfig,
+    model: ErasedModel,
+}
+
+impl RigProvider {
+    /// 按配置造 provider。`Disabled`、缺模型名、缺 key 都在这里被拒（fail-fast）。
+    ///
+    /// # Errors
+    /// AI 被禁用、配置不完整、或 rig 端点构造失败时返回可读错误。
+    pub fn new(config: ProviderConfig) -> Result<Self, ProviderError> {
+        config.validate()?;
+        let model = build_model(&config)?;
+        Ok(Self { config, model })
+    }
+
+    /// 装配层用的工厂：`ProviderFactory` 直接塞给 `crates/app`。
+    #[must_use]
+    pub fn factory() -> ProviderFactory {
+        Arc::new(|config: &ProviderConfig| {
+            Ok(Arc::new(Self::new(config.clone())?) as Arc<dyn ChatProvider>)
+        })
+    }
+}
+
+impl ChatProvider for RigProvider {
+    fn config(&self) -> &ProviderConfig {
+        &self.config
+    }
+
+    fn complete<'a>(
+        &'a self,
+        request: &'a ChatRequest,
+        observer: &'a dyn DeltaObserver,
+    ) -> ProviderFuture<'a> {
+        Box::pin(async move {
+            let rig_request = build_request(request)?;
+            let mut stream = self.model.stream(rig_request).map_err(map_error)?;
+
+            // 先转发增量，再拿折好的完整响应（工具调用只从响应取，不拼分片）。
+            let mut text = String::new();
+            while let Some(item) = stream.next().await {
+                match item.map_err(map_error)? {
+                    Item::Event(StreamEvent::Text { text: fragment, .. }) => {
+                        text.push_str(&fragment);
+                        observer.on_delta(&fragment);
+                    }
+                    Item::Event(_) | Item::Unknown(_) => {}
+                }
+            }
+            let response = stream.finish().await.map_err(map_error)?;
+            to_reply(&response, text)
+        })
+    }
+}
+
+/// 四态 → rig 模型。
+fn build_model(config: &ProviderConfig) -> Result<ErasedModel, ProviderError> {
+    let model = config.model.trim().to_string();
+    let base_url = config.resolved_base_url().to_string();
+    let api_key = config.api_key.clone().unwrap_or_default();
+    let erased = match config.kind {
+        ProviderKind::OpenAiCompatible => OpenAIConfig::new(api_key)
+            .with_base_url(base_url)
+            .client()
+            .chat(model)
+            .erase(),
+        ProviderKind::Anthropic => AnthropicConfig::new(api_key)
+            .with_base_url(base_url)
+            .client()
+            .completion(model)
+            .erase(),
+        ProviderKind::Ollama => OllamaConfig::new()
+            .with_base_url(base_url)
+            .client()
+            .completion(model)
+            .erase(),
+        ProviderKind::Disabled => {
+            return Err(ProviderError::new(
+                "AI 已禁用：请在设置 → AI 中选择端点（规则引擎诊断不受影响）",
+            ))
+        }
+    };
+    Ok(erased)
+}
+
+/// 本方消息 → rig 补全请求。
+fn build_request(request: &ChatRequest) -> Result<CompletionRequest, ProviderError> {
+    let mut history = to_rig_messages(&request.messages)?;
+    // rig 把历史最后一条当 prompt，其余是上下文；空历史没有可发的 prompt。
+    let prompt = history
+        .pop()
+        .ok_or_else(|| ProviderError::new("对话历史为空：至少需要一条用户消息"))?;
+    let prompt = Arc::unwrap_or_clone(prompt);
+    let tools = request
+        .tools
+        .iter()
+        .map(to_rig_tool)
+        .collect::<Result<Vec<_>, _>>()?;
+
+    Ok(CompletionRequest::new(prompt)
+        .messages(history)
+        .tools(tools)
+        .temperature(request.temperature.map(f64::from))
+        .max_tokens(request.max_tokens.map(u64::from)))
+}
+
+/// 本方工具定义 → rig 工具定义（入参都是裸 JSON Schema，这正是双投影的支点）。
+fn to_rig_tool(tool: &crate::registry::ToolDefinition) -> Result<RigToolDefinition, ProviderError> {
+    let name = tool_name(&tool.name)?;
+    Ok(RigToolDefinition::new(
+        name,
+        tool.description.clone(),
+        tool.input_schema.clone(),
+    ))
+}
+
+/// 本方消息 → rig 消息。
+fn to_rig_messages(messages: &[ChatMessage]) -> Result<Vec<Arc<RigMessage>>, ProviderError> {
+    let mut out = Vec::with_capacity(messages.len());
+    for message in messages {
+        let rig = match message {
+            ChatMessage::System { content } => RigMessage::system(content.clone()),
+            ChatMessage::User { content } => RigMessage::user(content.clone()),
+            ChatMessage::Assistant { text, tool_calls } => {
+                let mut parts = Vec::with_capacity(tool_calls.len() + 1);
+                if !text.trim().is_empty() {
+                    parts.push(RigAssistantContent::Text(RigText::new(text.clone())));
+                }
+                for call in tool_calls {
+                    parts.push(RigAssistantContent::ToolCall(RigToolCall::new(
+                        CallId::from_wire(call.id.clone()),
+                        ToolFunction::new(tool_name(&call.name)?, call.arguments.clone()),
+                    )));
+                }
+                RigMessage::Assistant(RigAssistantMessage::new(parts))
+            }
+            ChatMessage::Tool {
+                call_id,
+                name,
+                content,
+            } => RigMessage::User {
+                content: vec![UserContent::ToolResult(ToolResult {
+                    call: CallId::from_wire(call_id.clone()),
+                    name: tool_name(name)?,
+                    content: vec![ToolResultContent::text(content.clone())],
+                    is_error: false,
+                })],
+            },
+        };
+        out.push(Arc::new(rig));
+    }
+    Ok(out)
+}
+
+/// rig 响应 → 本方回复（文本 + 工具调用 + 用量）。
+fn to_reply(
+    response: &rig_core::completion::CompletionResponse,
+    streamed: String,
+) -> Result<ChatReply, ProviderError> {
+    let mut text = streamed;
+    let mut tool_calls = Vec::new();
+    for part in &response.choice {
+        match part {
+            RigAssistantContent::Text(chunk) => {
+                if text.is_empty() {
+                    text.push_str(&chunk.text);
+                }
+            }
+            RigAssistantContent::ToolCall(call) => {
+                if let Some(raw) = call.function.invalid_arguments.as_deref() {
+                    return Err(ProviderError::new(format!(
+                        "模型返回的工具调用参数不是 JSON 对象（工具 `{}`）：{raw}",
+                        call.function.name.as_str()
+                    )));
+                }
+                tool_calls.push(super::chat::ToolCall {
+                    id: call.id.to_string(),
+                    name: call.function.name.as_str().to_string(),
+                    arguments: serde_json::Value::Object(call.function.arguments.clone()),
+                });
+            }
+            // 推理链/图片/未知块不进对话循环（P0 只消费文本 + 工具调用）。
+            _ => {}
+        }
+    }
+    Ok(ChatReply {
+        text,
+        tool_calls,
+        usage: Some(super::chat::Usage {
+            prompt_tokens: response
+                .usage
+                .input_tokens
+                .and_then(|v| u32::try_from(v).ok()),
+            completion_tokens: response
+                .usage
+                .output_tokens
+                .and_then(|v| u32::try_from(v).ok()),
+        }),
+    })
+}
+
+/// rig 错误 → 本方错误（文案面向用户）。
+fn map_error(error: RigError) -> ProviderError {
+    ProviderError::new(error.to_string())
+}
+
+/// 工具名 → rig 的 [`RigToolName`]（空名是唯一的非法输入）。
+fn tool_name(name: &str) -> Result<RigToolName, ProviderError> {
+    RigToolName::new(name)
+        .map_err(|_| ProviderError::new("工具名不能为空（ToolSpec 注册阶段应已拦截）"))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn tool(id: &str, name: &str) -> super::super::chat::ToolCall {
+        super::super::chat::ToolCall {
+            id: id.to_string(),
+            name: name.to_string(),
+            arguments: serde_json::json!({ "path": "appearance.theme_mode" }),
+        }
+    }
+
+    #[test]
+    fn disabled_config_is_rejected_before_touching_the_network() {
+        let Err(err) = RigProvider::new(ProviderConfig::disabled()) else {
+            panic!("禁用态应在构造阶段被拒");
+        };
+        assert!(err.to_string().contains("禁用"));
+    }
+
+    #[test]
+    fn anthropic_without_key_is_rejected() {
+        assert!(RigProvider::new(ProviderConfig::anthropic("claude-sonnet-4")).is_err());
+        assert!(RigProvider::new(
+            ProviderConfig::anthropic("claude-sonnet-4").with_api_key("sk-ant")
+        )
+        .is_ok());
+    }
+
+    #[test]
+    fn local_states_build_offline() {
+        assert!(RigProvider::new(ProviderConfig::llamacpp_local("qwen2.5-7b")).is_ok());
+        assert!(RigProvider::new(ProviderConfig::ollama("llama3.1")).is_ok());
+    }
+
+    #[test]
+    fn request_maps_messages_and_tools() {
+        let request = ChatRequest {
+            model: "mock".to_string(),
+            messages: vec![
+                ChatMessage::system("你是助手"),
+                ChatMessage::user("把主题换成浅色"),
+                ChatMessage::Assistant {
+                    text: String::new(),
+                    tool_calls: vec![tool("call_1", "set_config")],
+                },
+                ChatMessage::tool("call_1", "set_config", "{\"status\":\"written\"}"),
+            ],
+            tools: vec![crate::registry::ToolDefinition {
+                name: "set_config".to_string(),
+                description: "改配置".to_string(),
+                input_schema: serde_json::json!({ "type": "object" }),
+            }],
+            temperature: Some(0.5),
+            max_tokens: Some(512),
+        };
+        let built = build_request(&request).expect("应能构造");
+        assert_eq!(built.chat_history.len(), 4);
+        assert_eq!(built.tools.len(), 1);
+        assert_eq!(built.tools[0].name.as_str(), "set_config");
+        assert_eq!(built.temperature, Some(0.5));
+        assert_eq!(built.max_tokens, Some(512));
+        // 工具结果在 rig 0.45 里是 user 角色的 ToolResult 内容块
+        let json = serde_json::to_string(&built.chat_history[3]).expect("可序列化");
+        assert!(json.contains("toolresult"), "{json}");
+    }
+
+    #[test]
+    fn empty_history_is_a_readable_error() {
+        let request = ChatRequest {
+            model: "m".to_string(),
+            messages: Vec::new(),
+            tools: Vec::new(),
+            temperature: None,
+            max_tokens: None,
+        };
+        let err = build_request(&request).unwrap_err();
+        assert!(err.to_string().contains("对话历史为空"));
+    }
+}

crates/agent/src/clock.rs

@@ -0,0 +1,139 @@
+//! 时间源：审计日志、事件流、工具耗时都要时间戳，但**测试不能依赖真实时钟**
+//! （否则断言不稳定）。所以照既有做法注入 [`Clock`]。
+//!
+//! 时间戳格式化自己实现（[`format_unix_ms`]），不引 `chrono`：agent 的依赖面按
+//! `DevDocs/PlanDoc/02-ai-agent-design.md` §0 越窄越好，RFC3339 UTC 只需要一个
+//! 民用历换算（Howard Hinnant 的 `civil_from_days`）。
+
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::Arc;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+/// 时间源。生产用 [`SystemClock`]，测试用 [`FixedClock`]。
+pub trait Clock: Send + Sync {
+    /// 当前 Unix 毫秒时间戳。
+    fn now_unix_ms(&self) -> u64;
+}
+
+/// 真实系统时钟（单调性不保证，审计只要"大致有序"）。
+#[derive(Debug, Default, Clone, Copy)]
+pub struct SystemClock;
+
+impl Clock for SystemClock {
+    fn now_unix_ms(&self) -> u64 {
+        SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .map_or(0, |d| d.as_millis() as u64)
+    }
+}
+
+/// 可控时钟：测试里固定起点、必要时手动推进。
+#[derive(Debug)]
+pub struct FixedClock {
+    ms: AtomicU64,
+    step_ms: u64,
+}
+
+impl FixedClock {
+    /// 从固定时间戳开始，每次读走一步 `step_ms`（0 = 不自动推进）。
+    #[must_use]
+    pub fn new(start_ms: u64) -> Self {
+        Self {
+            ms: AtomicU64::new(start_ms),
+            step_ms: 0,
+        }
+    }
+
+    /// 每次读取自动前进 `step_ms`，用来断言工具耗时字段。
+    #[must_use]
+    pub fn with_step(start_ms: u64, step_ms: u64) -> Self {
+        Self {
+            ms: AtomicU64::new(start_ms),
+            step_ms,
+        }
+    }
+
+    /// 手动推进。
+    pub fn advance(&self, ms: u64) {
+        self.ms.fetch_add(ms, Ordering::Relaxed);
+    }
+}
+
+impl Clock for FixedClock {
+    fn now_unix_ms(&self) -> u64 {
+        if self.step_ms == 0 {
+            return self.ms.load(Ordering::Relaxed);
+        }
+        self.ms.fetch_add(self.step_ms, Ordering::Relaxed) + self.step_ms
+    }
+}
+
+/// `Arc<dyn Clock>` 的简写。
+pub type SharedClock = Arc<dyn Clock>;
+
+/// Unix 毫秒 → `YYYY-MM-DDTHH:MM:SS.mmmZ`（UTC）。
+#[must_use]
+pub fn format_unix_ms(ms: u64) -> String {
+    let secs = (ms / 1000) as i64;
+    let millis = ms % 1000;
+    let days = secs.div_euclid(86_400);
+    let sod = secs.rem_euclid(86_400);
+    let (y, m, d) = civil_from_days(days);
+    let (h, mi, s) = (sod / 3600, (sod % 3600) / 60, sod % 60);
+    format!("{y:04}-{m:02}-{d:02}T{h:02}:{mi:02}:{s:02}.{millis:03}Z")
+}
+
+/// Unix 毫秒 → `YYYY-MM-DD`（UTC），审计落盘按天分文件用。
+#[must_use]
+pub fn date_of_unix_ms(ms: u64) -> String {
+    let (y, m, d) = civil_from_days(((ms / 1000) as i64).div_euclid(86_400));
+    format!("{y:04}-{m:02}-{d:02}")
+}
+
+/// 1970-01-01 起的天数 → (年, 月, 日)。
+fn civil_from_days(days: i64) -> (i64, u32, u32) {
+    let z = days + 719_468;
+    let era = if z >= 0 { z } else { z - 146_096 } / 146_097;
+    let doe = (z - era * 146_097) as u64; // [0, 146096]
+    let yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365; // [0, 399]
+    let y = yoe as i64 + era * 400;
+    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100); // [0, 365]
+    let mp = (5 * doy + 2) / 153; // [0, 11]
+    let d = (doy - (153 * mp + 2) / 5 + 1) as u32;
+    let m = if mp < 10 { mp + 3 } else { mp - 9 } as u32;
+    (if m <= 2 { y + 1 } else { y }, m, d)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn formats_epoch_and_known_instants() {
+        assert_eq!(format_unix_ms(0), "1970-01-01T00:00:00.000Z");
+        // 2026-10-29T20:12:33.123Z
+        assert_eq!(
+            format_unix_ms(1_793_304_753_123),
+            "2026-10-29T20:12:33.123Z"
+        );
+        assert_eq!(date_of_unix_ms(1_793_304_753_123), "2026-10-29");
+    }
+
+    #[test]
+    fn handles_leap_day() {
+        // 2024-02-29T00:00:00Z
+        assert_eq!(
+            format_unix_ms(1_709_164_800_000),
+            "2024-02-29T00:00:00.000Z"
+        );
+    }
+
+    #[test]
+    fn fixed_clock_can_step() {
+        let clock = FixedClock::with_step(1_000, 5);
+        assert_eq!(clock.now_unix_ms(), 1_005);
+        assert_eq!(clock.now_unix_ms(), 1_010);
+        clock.advance(10);
+        assert_eq!(clock.now_unix_ms(), 1_025);
+    }
+}

crates/agent/src/confirm.rs

@@ -0,0 +1,235 @@
+//! 分级确认协议（02 文档 §3.1「分级确认」+ §4b「YOLO」）。
+//!
+//! 分工：
+//! - **工具**只声明「这次调用需要确认」并给出 diff（[`ConfirmRequest`]），不自己做决定；
+//! - **编排层**（[`crate::brain::exec`]）拿 [`ConfirmPolicy`] 决定是问人、还是走 YOLO；
+//! - **UI** 在 P1 通过 [`ConfirmGate`] 接进来（P0 只有事件 + fail-closed 的默认实现）。
+//!
+//! fail-closed 是刻意的：P0 没有确认弹窗，敏感键的写入**一律拒绝**而不是静默放行
+//! （research/02 §7 R9「写操作的破坏半径」）。
+
+use std::collections::VecDeque;
+use std::future::Future;
+use std::pin::Pin;
+use std::sync::Mutex;
+
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+/// 敏感等级。**与 M12 `setting::spec::Sensitivity` 逐字一致**
+/// （`DevDocs/SubAgentsTalk/setting-接口约定.md` §8）：
+///
+/// | 等级 | 语义 |
+/// |------|------|
+/// | `Low` | 静默生效 |
+/// | `Medium` | 静默生效，审计里能查到（每次调用本来都审计，这里只是标记用途） |
+/// | `High` | 必须用户确认（YOLO 可跳过确认，但**仍受白名单约束**） |
+///
+/// 「AI 完全不能写」的键（`ai.api_key` 等凭据）由 M12 的 `writable=false` 表达，
+/// 它们**不进白名单**，agent 侧走「不在白名单」的拒绝分支，不需要第四级。
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum Sensitivity {
+    /// 静默生效。
+    #[default]
+    Low,
+    /// 静默生效但审计标记（下载源、语言、日志级别）。
+    Medium,
+    /// 必须用户确认（数据目录、Java 路径、代理、AI 端点/YOLO 开关）。
+    High,
+}
+
+/// 一个待确认的操作：给用户看的措辞 + 结构化细节（UI 画 diff 用）。
+#[derive(Debug, Clone, Serialize, PartialEq)]
+pub struct ConfirmRequest {
+    /// 请求 id（编排层生成，UI 回填决定时原样带回）。
+    pub id: String,
+    /// 工具名。
+    pub tool: String,
+    /// 一句话请求（「AI 请求把 `instance.java.path` 改为 `D:\jdk17`」）。
+    pub summary: String,
+    /// 结构化细节（`{"path":…, "old":…, "new":…}`）。
+    pub details: Value,
+    /// 敏感等级。
+    pub sensitivity: Sensitivity,
+}
+
+/// 用户决定。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ConfirmDecision {
+    /// 允许这一次。
+    Approved,
+    /// 拒绝（工具调用返回「用户拒绝」给模型）。
+    Denied,
+    /// 允许，且本会话后续不再询问（UI 的「全部允许」）。
+    ///
+    /// 编排层当前**只当普通放行**处理（`brain/exec.rs` 不区分两者）；「据此临时开 YOLO」
+    /// 是 P1 的行为，落地前不要按已实现来看。
+    ApprovedAll,
+}
+
+impl ConfirmDecision {
+    /// 是否放行（`Approved` 与 `ApprovedAll` 都放行）。
+    #[must_use]
+    pub fn is_approved(self) -> bool {
+        matches!(self, Self::Approved | Self::ApprovedAll)
+    }
+}
+
+/// 确认闸门：P1 由 app 的 Slint 弹窗实现；测试用 [`ScriptedGate`]。
+pub trait ConfirmGate: Send + Sync {
+    /// 发起确认并等待决定（UI 未接时由实现方立即给出 fail-closed 结果）。
+    fn request(&self, request: ConfirmRequest) -> ConfirmFuture;
+}
+
+/// 确认未来的箱子类型。
+pub type ConfirmFuture = Pin<Box<dyn Future<Output = ConfirmDecision> + Send + 'static>>;
+
+/// 一律放行（YOLO 单测 / 未来"用户已信任该工具"场景）。
+#[derive(Debug, Default, Clone, Copy)]
+pub struct AutoApproveGate;
+
+impl ConfirmGate for AutoApproveGate {
+    fn request(&self, _request: ConfirmRequest) -> ConfirmFuture {
+        Box::pin(async { ConfirmDecision::Approved })
+    }
+}
+
+/// 一律拒绝（fail-closed 的极简形态）。
+#[derive(Debug, Default, Clone, Copy)]
+pub struct AutoDenyGate;
+
+impl ConfirmGate for AutoDenyGate {
+    fn request(&self, _request: ConfirmRequest) -> ConfirmFuture {
+        Box::pin(async { ConfirmDecision::Denied })
+    }
+}
+
+/// P0 默认闸门：**没有确认 UI** → 一律拒绝（fail-closed）。
+///
+/// 请求本身已经由编排层作为 [`crate::event::AgentEvent::ConfirmRequested`] 发出去了，
+/// 所以 P0 的行为是「敏感操作既不静默执行，也不卡住对话」：事件流里留下了
+/// 「AI 想改 X」的完整记录，P1 接上弹窗后同一个事件直接变成可点的确认框。
+#[derive(Debug, Default, Clone, Copy)]
+pub struct NoUiGate;
+
+impl ConfirmGate for NoUiGate {
+    fn request(&self, _request: ConfirmRequest) -> ConfirmFuture {
+        Box::pin(async { ConfirmDecision::Denied })
+    }
+}
+
+/// 脚本化闸门：按顺序返回预设决定，用完之后走 `default`（测试用）。
+pub struct ScriptedGate {
+    decisions: Mutex<VecDeque<ConfirmDecision>>,
+    default: ConfirmDecision,
+}
+
+impl ScriptedGate {
+    /// 依次给出 `decisions`，耗尽后返回 `default`。
+    #[must_use]
+    pub fn new(
+        decisions: impl IntoIterator<Item = ConfirmDecision>,
+        default: ConfirmDecision,
+    ) -> Self {
+        Self {
+            decisions: Mutex::new(decisions.into_iter().collect()),
+            default,
+        }
+    }
+}
+
+impl ConfirmGate for ScriptedGate {
+    fn request(&self, _request: ConfirmRequest) -> ConfirmFuture {
+        let decision = self
+            .decisions
+            .lock()
+            .ok()
+            .and_then(|mut q| q.pop_front())
+            .unwrap_or(self.default);
+        Box::pin(async move { decision })
+    }
+}
+
+/// 确认策略（编排层用）。YOLO 的真实开关在设置里，这里只是当次运行的快照。
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub struct ConfirmPolicy {
+    /// 自动批准全部工具调用（设置 → AI → YOLO，默认关）。
+    pub yolo: bool,
+}
+
+/// 拒绝时的引导口径：**内置对话**有弹窗可点，**外部 MCP** 没有 UI——这条差别只在
+/// 「拒绝文案」上，策略本身完全相同（同一条 `ConfirmPolicy`、同一份审计）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum DenyGuidance {
+    /// 内置对话：弹窗拒绝（或 P0 的 fail-closed）。
+    InApp,
+    /// 外部 MCP 客户端：引导用户去设置页确认，或打开 YOLO。
+    External,
+}
+
+impl DenyGuidance {
+    /// 拒绝后回给模型/用户的一句话（区分「谁拒的」与「下一步怎么办」）。
+    #[must_use]
+    pub fn message(self) -> &'static str {
+        match self {
+            Self::InApp => "用户拒绝了这次操作，未做任何修改",
+            Self::External => {
+                "这次操作需要用户确认，但当前是外部 MCP 客户端（没有确认弹窗），已按默认策略拒绝。\
+                 请让用户在启动器设置页手动修改，或在设置 → AI 里打开 YOLO 模式后重试（审计照记）。"
+            }
+        }
+    }
+}
+
+impl ConfirmPolicy {
+    /// 该等级是否需要**询问**用户：只有 `High` 会问；YOLO 下连 `High` 也不问
+    /// （02 文档 §4b：YOLO 跳过分级确认，但**仍受白名单约束**——能改的键没变少）。
+    #[must_use]
+    pub fn requires_confirmation(self, sensitivity: Sensitivity) -> bool {
+        !self.yolo && sensitivity == Sensitivity::High
+    }
+
+    /// 该等级是否可以直接执行（不需要询问）。
+    #[must_use]
+    pub fn auto_approves(self, sensitivity: Sensitivity) -> bool {
+        !self.requires_confirmation(sensitivity)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn low_and_medium_keys_never_ask() {
+        let policy = ConfirmPolicy { yolo: false };
+        assert!(!policy.requires_confirmation(Sensitivity::Low));
+        assert!(!policy.requires_confirmation(Sensitivity::Medium));
+        assert!(policy.auto_approves(Sensitivity::Low));
+        assert!(policy.auto_approves(Sensitivity::Medium));
+    }
+
+    #[test]
+    fn high_keys_ask_unless_yolo() {
+        assert!(ConfirmPolicy { yolo: false }.requires_confirmation(Sensitivity::High));
+        assert!(!ConfirmPolicy { yolo: false }.auto_approves(Sensitivity::High));
+        assert!(!ConfirmPolicy { yolo: true }.requires_confirmation(Sensitivity::High));
+        assert!(ConfirmPolicy { yolo: true }.auto_approves(Sensitivity::High));
+    }
+
+    #[test]
+    fn sensitivity_matches_m12_levels() {
+        // 序列化名必须与 M12 `setting::spec::Sensitivity` 一致
+        assert_eq!(serde_json::to_string(&Sensitivity::Low).unwrap(), "\"low\"");
+        assert_eq!(
+            serde_json::to_string(&Sensitivity::Medium).unwrap(),
+            "\"medium\""
+        );
+        assert_eq!(
+            serde_json::to_string(&Sensitivity::High).unwrap(),
+            "\"high\""
+        );
+    }
+}

crates/agent/src/event.rs

@@ -0,0 +1,197 @@
+//! agent 事件流：**UI 与审计之外的观察者**都从这里接（02 文档 §1 的「event channel」）。
+//!
+//! P0 只做输出（[`AgentEventSink`]），P1 的 Slint 聊天面板订阅同一路事件把
+//! 「正在读取日志…」「请求修改设置：下载并发 64→16」画出来，确认弹窗直接复用
+//! [`AgentEvent::ConfirmRequested`]。
+//!
+//! 实现方必须**非阻塞**：`emit` 在对话循环的同步路径上被调用。
+
+use std::sync::mpsc::Sender;
+use std::sync::Mutex;
+
+use serde::Serialize;
+use serde_json::Value;
+
+use crate::confirm::ConfirmRequest;
+
+/// 一条 agent 事件（全部可序列化：P1 走 IPC 给 app 时不写两套类型）。
+#[derive(Debug, Clone, Serialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum AgentEvent {
+    /// 一轮对话开始。
+    TurnStarted {
+        /// agent 会话 id。
+        session_id: String,
+        /// 用户输入。
+        user_text: String,
+    },
+    /// 流式文本增量（P1 聊天面板逐字渲染）。
+    TextDelta {
+        /// 增量文本。
+        text: String,
+    },
+    /// 模型这一轮的非流式完整文本（流式之外的兜底，也是审计用的正文）。
+    AssistantText {
+        /// 文本。
+        text: String,
+    },
+    /// 开始执行一个工具调用。
+    ToolCallStarted {
+        /// 工具名。
+        tool: String,
+        /// 模型给的参数。
+        args: Value,
+        /// 第几轮工具循环（从 1 开始）。
+        step: usize,
+    },
+    /// 一个工具调用结束。
+    ToolCallFinished {
+        /// 工具名。
+        tool: String,
+        /// 是否成功。
+        ok: bool,
+        /// 一句话结果摘要（UI 直接显示）。
+        summary: String,
+        /// 这次是否触发了确认请求。
+        requires_confirmation: bool,
+    },
+    /// 需要用户确认（P0 只发事件，P1 变成可点的弹窗）。
+    ConfirmRequested {
+        /// 待确认请求。
+        request: Box<ConfirmRequest>,
+    },
+    /// 工具调用被拒绝（策略或用户）。
+    ToolDenied {
+        /// 工具名。
+        tool: String,
+        /// 拒绝原因。
+        reason: String,
+    },
+    /// 一轮对话结束。
+    TurnFinished {
+        /// 实际用掉的最大工具轮次。
+        steps: usize,
+        /// 最终给用户看的文本。
+        text: String,
+    },
+    /// 循环级错误（provider 挂了、AI 被禁用…）。
+    Error {
+        /// 人类可读原因。
+        message: String,
+    },
+}
+
+/// 事件出口。
+pub trait AgentEventSink: Send + Sync {
+    /// 发一条事件。实现方不得阻塞。
+    fn emit(&self, event: AgentEvent);
+}
+
+/// 丢弃事件。
+#[derive(Debug, Default, Clone, Copy)]
+pub struct NoopSink;
+
+impl AgentEventSink for NoopSink {
+    fn emit(&self, _event: AgentEvent) {}
+}
+
+/// 内存事件流（测试断言 + P0 的「暂不接 UI」）。
+#[derive(Debug, Default)]
+pub struct MemoryEventSink {
+    events: Mutex<Vec<AgentEvent>>,
+}
+
+impl MemoryEventSink {
+    /// 空 sink。
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// 取快照。
+    #[must_use]
+    pub fn events(&self) -> Vec<AgentEvent> {
+        self.events.lock().map(|e| e.clone()).unwrap_or_default()
+    }
+
+    /// 已发条数。
+    #[must_use]
+    pub fn len(&self) -> usize {
+        self.events.lock().map(|e| e.len()).unwrap_or(0)
+    }
+
+    /// 是否还没发过事件。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.len() == 0
+    }
+
+    /// 拼接所有文本增量（测试断言「流式内容拼起来等于完整文本」）。
+    #[must_use]
+    pub fn streamed_text(&self) -> String {
+        self.events()
+            .into_iter()
+            .filter_map(|e| match e {
+                AgentEvent::TextDelta { text } => Some(text),
+                _ => None,
+            })
+            .collect()
+    }
+}
+
+impl AgentEventSink for MemoryEventSink {
+    fn emit(&self, event: AgentEvent) {
+        if let Ok(mut events) = self.events.lock() {
+            events.push(event);
+        }
+    }
+}
+
+/// 标准库 channel 出口（P1 的 app 用一个线程收、喂给 Slint 的事件循环）。
+#[derive(Debug, Clone)]
+pub struct MpscSink {
+    tx: Sender<AgentEvent>,
+}
+
+impl MpscSink {
+    /// 包一个 `std::sync::mpsc::Sender`。
+    #[must_use]
+    pub fn new(tx: Sender<AgentEvent>) -> Self {
+        Self { tx }
+    }
+}
+
+impl AgentEventSink for MpscSink {
+    fn emit(&self, event: AgentEvent) {
+        // 接收端已关闭说明 UI 没了，事件直接丢弃（不能拖累对话）。
+        let _ = self.tx.send(event);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn memory_sink_collects_and_concatenates_deltas() {
+        let sink = MemoryEventSink::new();
+        sink.emit(AgentEvent::TextDelta {
+            text: "正在".into(),
+        });
+        sink.emit(AgentEvent::TextDelta {
+            text: "读取日志".into(),
+        });
+        assert_eq!(sink.streamed_text(), "正在读取日志");
+        assert_eq!(sink.len(), 2);
+    }
+
+    #[test]
+    fn mpsc_sink_forwards() {
+        let (tx, rx) = std::sync::mpsc::channel();
+        let sink = MpscSink::new(tx);
+        sink.emit(AgentEvent::Error {
+            message: "boom".into(),
+        });
+        assert!(matches!(rx.recv(), Ok(AgentEvent::Error { .. })));
+    }
+}

crates/agent/src/lib.rs

@@ -0,0 +1,45 @@
+//! Unlucky-Launcher AI Agent（`unlucky_agent`）。
+//!
+//! 形态定案（决策 D4）：**内置 Agent 客户端 + 对外的 MCP server 双形态，共享同一个工具内核**。
+//! 设计定稿：`DevDocs/PlanDoc/02-ai-agent-design.md`。
+//!
+//! 三条不能破的边界：
+//! 1. 工具只定义一次（[`registry`]），内置客户端与 MCP server 都把同一个 `ToolSpec` 投影出去；
+//! 2. AI 是 Port 不是 Service——LLM 不可用时规则引擎仍能诊断；
+//! 3. AI 永不接触账户凭据；写配置受 schema 白名单约束并留审计。
+//!
+//! 与 core 的关系：agent 依赖 core 的公共 API，core 不知道 agent 的存在。
+//! 落地方式是把需要 core 的能力收成[`port`]里的五个 trait（配置读写 / 会话日志 / 崩溃诊断 /
+//! 实例与 Java / 账户），由装配层用 core 的实现填充——这样 M12/M14/M15/M18/M31/M33 未合并时
+//! agent 也能独立编译、独立测试。装配处有两条：`crates/app`（GUI）与 `ull agent serve`（headless）。
+//!
+//! 当前状态：工具内核 + 对话循环 + 审计（P0 定稿）+ **对外 MCP server**（M39）已落地。
+//! 两个外部依赖都收口在单文件：[`brain::rig`] 对 rig、[`mcp`] 对 rmcp（3.8.x）——
+//! 它们升 breaking 时只有那两个模块编译失败，上层的循环/编排/审计一行不用动。
+//!
+//! 模块分工：
+//! - [`registry`] 工具注册表（唯一真相源 + 双投影载荷）；
+//! - [`tools`] 工具 v1 实现（配置读写 / 会话日志 / 崩溃诊断）；
+//! - [`brain`] Provider 抽象 + 对话循环 + 工具编排；
+//! - [`mcp`] 对外 MCP server（rmcp 双投影 + stdio / Streamable HTTP 传输）；
+//! - [`confirm`] 分级确认协议与 YOLO 策略；
+//! - [`audit`] 每次工具调用的审计留痕；
+//! - [`event`] 面向 UI 的事件流；
+//! - [`port`] 与 core 的接触面（依赖倒置）；
+//! - [`redact`] 密钥/主目录脱敏；
+//! - [`clock`] 可注入时间源（审计/事件用）；
+//! - [`testing`] 五个端口的 mock 实现（供本 crate、app 与 MCP 契约测试复用）。
+
+#![forbid(unsafe_code)]
+
+pub mod audit;
+pub mod brain;
+pub mod clock;
+pub mod confirm;
+pub mod event;
+pub mod mcp;
+pub mod port;
+pub mod redact;
+pub mod registry;
+pub mod testing;
+pub mod tools;

crates/agent/src/mcp/mod.rs

@@ -0,0 +1,159 @@
+//! 对外 MCP server（02 文档 §1「双形态共享一个工具内核」的第二形态）。
+//!
+//! 传输定论（§0）：**Streamable HTTP on 127.0.0.1 是主力**（外部 agent 起 stdio 会变成
+//! 双实例抢数据目录锁），**stdio 形态保留**给 llama.cpp server 的内置 MCP client。
+//!
+//! 与内置客户端的关系：两侧都只吃 [`crate::registry::ToolRegistry`] 的 `(name, description,
+//! input_schema)`，并且**都必须走** [`crate::brain::exec::ToolExecutor`]——schema 校验、
+//! 分级确认、YOLO、审计一个字都不少。所以「用户在聊天里让 AI 改配置」与「Claude Code
+//! 通过 MCP 改配置」是同一条路径（02 §1 的铁律）。
+//!
+//! 安全边界（MCP 场景的差别只有一条）：
+//! - 敏感键（`Sensitivity::High`）默认**拒绝**而不是弹窗——外部客户端没有我们的 UI；
+//!   拒绝文案引导用户去设置页确认，或在设置里打开 `ai.yolo`（YOLO 下照记 `yolo=true` 审计）；
+//! - 写工具默认不暴露（`agent.mcp.allow_write=false`）：只读子集注册进注册表，
+//!   调写工具会得到「没有这个工具 + 可用工具清单」（并留一条 `unknown_tool` 审计）。
+//!
+//! 依赖面纪律：整个 crate 只有本模块允许 `use rmcp::`（与 `brain::rig` 对 rig 的规则同形）。
+
+pub mod projection;
+pub mod sample;
+pub mod serve;
+pub mod server;
+
+use std::fmt;
+
+pub use sample::{config_samples, ConfigSamples};
+pub use serve::{bind, serve_http, serve_http_on, serve_stdio};
+pub use server::RegistryServer;
+
+/// 一次 MCP server 运行的配置（由设置键 `agent.mcp.*` + 命令行覆盖合成）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct McpConfig {
+    /// 监听地址。**只允许回环地址**（默认 `127.0.0.1`）：MCP 工具能改配置，不能对外开。
+    pub host: String,
+    /// Streamable HTTP 端口（默认 47823，设置键 `agent.mcp.port`）。
+    pub port: u16,
+    /// 访问令牌（`Authorization: Bearer <token>`）；`None` = 不校验（仅限回环监听时允许）。
+    pub token: Option<String>,
+    /// 是否只暴露只读工具（默认 **true**；`agent.mcp.allow_write=true` 才放开写侧）。
+    pub read_only: bool,
+}
+
+impl Default for McpConfig {
+    fn default() -> Self {
+        Self {
+            host: "127.0.0.1".to_string(),
+            port: 47823,
+            token: None,
+            read_only: true,
+        }
+    }
+}
+
+impl McpConfig {
+    /// `host:port` 形态的监听地址（IPv6 字面量自动加方括号，`::1` 不会拼成 `::1:47823`）。
+    #[must_use]
+    pub fn socket_addr(&self) -> String {
+        if self.host.contains(':') {
+            format!("[{}]:{}", self.host, self.port)
+        } else {
+            format!("{}:{}", self.host, self.port)
+        }
+    }
+
+    /// MCP 端点 URL（客户端配置样例里用的那串）。
+    #[must_use]
+    pub fn url(&self) -> String {
+        format!("http://{}/mcp", self.socket_addr())
+    }
+
+    /// 拒绝非回环监听——这是安全铁律的**代码化**，不是文档里的建议。
+    ///
+    /// # Errors
+    /// `host` 不是回环地址时返回 [`McpServeError::NotLoopback`]。
+    pub fn ensure_loopback(&self) -> Result<(), McpServeError> {
+        let host = self.host.trim();
+        if host == "127.0.0.1" || host == "localhost" || host == "::1" {
+            return Ok(());
+        }
+        Err(McpServeError::NotLoopback(host.to_string()))
+    }
+}
+
+/// MCP server 启动/运行期错误（文案面向用户，可直接进 CLI 输出）。
+#[derive(Debug)]
+pub enum McpServeError {
+    /// 监听地址不是回环地址。
+    NotLoopback(String),
+    /// 端口被占用（最常见：另一个 `ull agent serve` 已经在跑）。
+    PortInUse {
+        /// 监听地址（`127.0.0.1:47823`）。
+        addr: String,
+    },
+    /// 其他 IO 失败（权限、端口不足、传输中断）。
+    Io(String),
+}
+
+impl fmt::Display for McpServeError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::NotLoopback(host) => write!(
+                f,
+                "拒绝在 `{host}` 上监听：MCP server 只允许回环地址（127.0.0.1 / localhost / ::1）"
+            ),
+            Self::PortInUse { addr } => write!(
+                f,
+                "端口已被占用：{addr}。可能另一个 `ull agent serve` 正在运行；\
+                 用 `--port <端口>` 或设置键 `agent.mcp.port` 换一个"
+            ),
+            Self::Io(message) => write!(f, "MCP server 传输失败：{message}"),
+        }
+    }
+}
+
+impl std::error::Error for McpServeError {}
+
+impl From<std::io::Error> for McpServeError {
+    fn from(error: std::io::Error) -> Self {
+        Self::Io(error.to_string())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn only_loopback_hosts_are_accepted() {
+        let mut cfg = McpConfig::default();
+        assert!(cfg.ensure_loopback().is_ok());
+        cfg.host = "localhost".to_string();
+        assert!(cfg.ensure_loopback().is_ok());
+        cfg.host = "::1".to_string();
+        assert_eq!(cfg.url(), "http://[::1]:47823/mcp");
+        assert!(cfg.ensure_loopback().is_ok());
+        cfg.host = "0.0.0.0".to_string();
+        let err = cfg.ensure_loopback().unwrap_err();
+        assert!(matches!(err, McpServeError::NotLoopback(_)));
+        assert!(err.to_string().contains("回环地址"));
+    }
+
+    #[test]
+    fn default_is_read_only_on_the_documented_port() {
+        let cfg = McpConfig::default();
+        assert!(cfg.read_only);
+        assert_eq!(cfg.port, 47823);
+        assert_eq!(cfg.url(), "http://127.0.0.1:47823/mcp");
+    }
+
+    #[test]
+    fn port_in_use_message_is_actionable() {
+        let err = McpServeError::PortInUse {
+            addr: "127.0.0.1:47823".to_string(),
+        };
+        let text = err.to_string();
+        assert!(text.contains("--port"), "{text}");
+        assert!(text.contains("agent.mcp.port"), "{text}");
+    }
+}

crates/agent/src/mcp/projection.rs

@@ -0,0 +1,106 @@
+//! 双投影的 **MCP 侧**：`ToolDefinition` → rmcp `Tool`（`ToolRoute::new_dyn` 的属性入参）。
+//!
+//! rig 侧在 [`crate::brain::rig`]（`ToolDefinition → RigToolDefinition`）。两侧都只吃裸
+//! `serde_json::Value` schema，所以「一致性」是可断言的：`tests/mcp_contract.rs` 遍历注册表，
+//! 断言 MCP 侧的 `(name, description, input_schema)` 与注册表逐项相等——这就是
+//! research/02 §6.2 建议进 CI 的那条契约。
+//!
+//! 额外一位信息：`annotations.read_only_hint`。MCP 客户端拿它决定「这个工具能不能
+//! 静默调用」，我们用它把 [`Access`] 语义透出去（只读提示，不是权限——权限在编排层）。
+
+use std::sync::Arc;
+
+use rmcp::model::{JsonObject, Tool, ToolAnnotations};
+use serde_json::Value;
+
+use crate::registry::{Access, ToolDefinition, ToolRegistry};
+
+/// 一个 `ToolDefinition` → rmcp `Tool`。
+///
+/// 注册表在注册阶段已保证 `input_schema` 根是 `object`，所以这里的兜底分支
+/// （非对象 → 空 schema）只是为了不 panic：真走到它说明注册校验被绕过了。
+#[must_use]
+pub fn tool_attr(definition: &ToolDefinition, access: Access) -> Tool {
+    let schema: JsonObject = match &definition.input_schema {
+        Value::Object(map) => map.clone(),
+        _ => JsonObject::new(),
+    };
+    let mut attr = Tool::new(
+        definition.name.clone(),
+        definition.description.clone(),
+        Arc::new(schema),
+    );
+    let mut annotations = ToolAnnotations::default();
+    annotations.read_only_hint = Some(access == Access::ReadOnly);
+    annotations.destructive_hint = Some(access == Access::Mutating);
+    attr.annotations = Some(annotations);
+    attr
+}
+
+/// 注册表 → rmcp `Tool` 列表（顺序同注册顺序，便于两侧比对）。
+#[must_use]
+pub fn tool_attrs(registry: &ToolRegistry) -> Vec<Tool> {
+    registry
+        .specs()
+        .iter()
+        .map(|spec| tool_attr(&spec.definition(), spec.access))
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::testing::mock_ports;
+    use crate::tools::build_v1_registry;
+    use serde_json::json;
+
+    fn registry() -> ToolRegistry {
+        let (ports, _settings) = mock_ports();
+        build_v1_registry(&ports).expect("注册表应装配成功")
+    }
+
+    #[test]
+    fn projection_keeps_name_description_and_schema() {
+        let registry = registry();
+        let attrs = tool_attrs(&registry);
+        assert_eq!(attrs.len(), registry.len());
+
+        for (attr, spec) in attrs.iter().zip(registry.specs()) {
+            let definition = spec.definition();
+            assert_eq!(attr.name.as_ref(), definition.name);
+            assert_eq!(
+                attr.description.as_deref(),
+                Some(definition.description.as_str()),
+                "{} 的说明必须逐字相等",
+                definition.name
+            );
+            let projected = Value::Object((*attr.input_schema).clone());
+            assert_eq!(
+                projected, definition.input_schema,
+                "{} 的 JSON Schema 必须逐字相等",
+                definition.name
+            );
+        }
+    }
+
+    #[test]
+    fn read_only_hint_matches_access() {
+        let registry = registry();
+        for (attr, spec) in tool_attrs(&registry).iter().zip(registry.specs()) {
+            let hint = attr
+                .annotations
+                .as_ref()
+                .and_then(|a| a.read_only_hint)
+                .unwrap_or(false);
+            assert_eq!(hint, spec.access == Access::ReadOnly, "{}", attr.name);
+        }
+    }
+
+    #[test]
+    fn schema_root_stays_an_object_on_the_wire() {
+        for attr in tool_attrs(&registry()) {
+            let value = Value::Object((*attr.input_schema).clone());
+            assert_eq!(value["type"], json!("object"), "{}", attr.name);
+        }
+    }
+}

crates/agent/src/mcp/sample.rs

@@ -0,0 +1,80 @@
+//! 对外客户端配置样例（用户把它们粘进 Claude Code / Cursor 就能连上）。
+//!
+//! 为什么要生成而不是写在文档里：端口与令牌是**用户本机**的值，手抄必错。
+//! 两个客户端的形状不同（02 §0）：
+//! - **Claude Code**：`{"type":"http","url":…}`（`type` 必填，缺了会被当成 stdio）
+//! - **Cursor**：`{"url":…}`（`mcp.json` 里只认 url；多写 type 会被忽略但不报错）
+//!
+//! 令牌只在设置里非空时出现——回环 + 无令牌是允许的（研究里“至少一个 token”是建议不是铁律，
+//! 而我们用 `McpConfig::ensure_loopback` 硬性禁掉对外监听）。
+
+use serde_json::{json, Value};
+
+/// 客户端配置样例（三件套：端点 URL + 两份可直接粘的 JSON）。
+#[derive(Debug, Clone, PartialEq)]
+pub struct ConfigSamples {
+    /// `http://127.0.0.1:<port>/mcp`。
+    pub url: String,
+    /// Claude Code（`claude mcp add` / `~/.claude.json` 的 `mcpServers` 片段）。
+    pub claude_code: Value,
+    /// Cursor（`.cursor/mcp.json` 的 `mcpServers` 片段）。
+    pub cursor: Value,
+}
+
+/// 生成样例。`token` 非空时补 `headers.Authorization`。
+#[must_use]
+pub fn config_samples(url: &str, token: Option<&str>) -> ConfigSamples {
+    let headers = token
+        .filter(|t| !t.trim().is_empty())
+        .map(|t| json!({ "Authorization": format!("Bearer {t}") }));
+
+    let mut claude_entry = json!({ "type": "http", "url": url });
+    let mut cursor_entry = json!({ "url": url });
+    if let Some(headers) = &headers {
+        claude_entry["headers"] = headers.clone();
+        cursor_entry["headers"] = headers.clone();
+    }
+
+    ConfigSamples {
+        url: url.to_string(),
+        claude_code: json!({ "mcpServers": { "unlucky-launcher": claude_entry } }),
+        cursor: json!({ "mcpServers": { "unlucky-launcher": cursor_entry } }),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn claude_code_needs_type_http_and_cursor_does_not() {
+        let samples = config_samples("http://127.0.0.1:47823/mcp", None);
+        assert_eq!(
+            samples.claude_code["mcpServers"]["unlucky-launcher"]["type"],
+            json!("http")
+        );
+        assert_eq!(
+            samples.claude_code["mcpServers"]["unlucky-launcher"]["url"],
+            json!("http://127.0.0.1:47823/mcp")
+        );
+        assert!(samples.cursor["mcpServers"]["unlucky-launcher"]
+            .get("type")
+            .is_none());
+        assert_eq!(
+            samples.cursor["mcpServers"]["unlucky-launcher"]["url"],
+            json!("http://127.0.0.1:47823/mcp")
+        );
+    }
+
+    #[test]
+    fn token_becomes_bearer_header_and_empty_token_is_skipped() {
+        let with = config_samples("http://127.0.0.1:1/mcp", Some("s3cret"));
+        let header = &with.cursor["mcpServers"]["unlucky-launcher"]["headers"]["Authorization"];
+        assert_eq!(header, &json!("Bearer s3cret"));
+
+        let without = config_samples("http://127.0.0.1:1/mcp", Some("  "));
+        assert!(without.claude_code["mcpServers"]["unlucky-launcher"]
+            .get("headers")
+            .is_none());
+    }
+}

crates/agent/src/mcp/serve.rs

@@ -0,0 +1,144 @@
+//! 两种传输：stdio（llama.cpp 内置 MCP client 用）与 Streamable HTTP（主力）。
+//!
+//! 传输定论（02 §0）：**外部 MCP 主力是 127.0.0.1 上的 Streamable HTTP**，
+//! 因为 stdio 形态要被外部 agent 拉起 = 同一份数据目录出现第二个实例，
+//! 迟早撞上单写者锁（M18 的会话 jsonl、M12 的 launcher.json 都是单写者）。
+//! stdio 保留给**已经常驻的**本地模型服务（llama.cpp server 的 MCP client 由它自己拉子进程）。
+//!
+//! 令牌：`Authorization: Bearer <agent.mcp.token>`。设置里为空 = 不校验（只允许回环监听，
+//! `McpConfig::ensure_loopback` 已经拦掉对外监听）。research/02 §4.4 的原话是
+//! 「至少要有 headers 里的一枚随机 token」——我们做成可配、默认留空但样例里带。
+
+use std::net::SocketAddr;
+
+use axum::extract::Request;
+use axum::http::header::AUTHORIZATION;
+use axum::http::StatusCode;
+use axum::middleware::Next;
+use axum::response::{IntoResponse, Response};
+use rmcp::transport::streamable_http_server::session::local::LocalSessionManager;
+use rmcp::transport::streamable_http_server::{StreamableHttpServerConfig, StreamableHttpService};
+use rmcp::ServiceExt;
+use tokio::net::TcpListener;
+
+use crate::mcp::server::RegistryServer;
+use crate::mcp::{McpConfig, McpServeError};
+
+/// stdio 形态：读 stdin 写 stdout，直到对端关闭。
+///
+/// 注意：**stdout 只能有 JSON-RPC**。任何日志都要走 stderr（否则客户端解析失败）。
+///
+/// # Errors
+/// 传输中断或初始化失败时返回 [`McpServeError`]。
+pub async fn serve_stdio(server: RegistryServer) -> Result<(), McpServeError> {
+    let service = server
+        .serve(rmcp::transport::stdio())
+        .await
+        .map_err(|error| McpServeError::Io(format!("stdio 初始化失败：{error}")))?;
+    service
+        .waiting()
+        .await
+        .map_err(|error| McpServeError::Io(format!("stdio 传输中断：{error}")))?;
+    Ok(())
+}
+
+/// 绑定 Streamable HTTP 监听（**只绑回环**），返回实际地址。
+///
+/// 拆出来是为了让调用方在进入 `axum::serve` 之前就能打印「监听在哪」——
+/// 端口被占用时也能拿到一条可操作的错误（tower 的提醒：撞端口要给出换端口的指引）。
+///
+/// # Errors
+/// 非回环地址、端口被占用、或绑定失败时返回 [`McpServeError`]。
+pub async fn bind(cfg: &McpConfig) -> Result<(SocketAddr, TcpListener), McpServeError> {
+    cfg.ensure_loopback()?;
+    let addr = cfg.socket_addr();
+    let listener = TcpListener::bind(&addr).await.map_err(|error| {
+        if error.kind() == std::io::ErrorKind::AddrInUse {
+            McpServeError::PortInUse { addr: addr.clone() }
+        } else {
+            McpServeError::Io(format!("绑定 {addr} 失败：{error}"))
+        }
+    })?;
+    let local = listener
+        .local_addr()
+        .map_err(|error| McpServeError::Io(error.to_string()))?;
+    Ok((local, listener))
+}
+
+/// Streamable HTTP 形态：`POST /mcp` 一条 JSON-RPC 请求 / 一条响应。
+///
+/// `json_response = true`：简单请求直接回 `application/json`（脚本与裸 JSON-RPC
+/// 客户端最省事；需要服务端推送时 rmcp 会自动回落到 SSE）。
+///
+/// # Errors
+/// 绑定失败（见 [`bind`]）或服务运行期致命错误时返回 [`McpServeError`]。
+pub async fn serve_http(server: RegistryServer, cfg: McpConfig) -> Result<(), McpServeError> {
+    let (local, listener) = bind(&cfg).await?;
+    serve_http_on(server, cfg, local, listener).await
+}
+
+/// 在已绑定的监听上跑（测试用临时端口，避免抢 47823）。
+///
+/// # Errors
+/// 服务运行期致命错误时返回 [`McpServeError`]。
+pub async fn serve_http_on(
+    server: RegistryServer,
+    cfg: McpConfig,
+    local: SocketAddr,
+    listener: TcpListener,
+) -> Result<(), McpServeError> {
+    let http_config = StreamableHttpServerConfig::default()
+        .with_json_response(true)
+        .with_legacy_session_mode(false);
+    let factory_server = server.clone();
+    let service: StreamableHttpService<RegistryServer, LocalSessionManager> =
+        StreamableHttpService::new(
+            move || Ok(factory_server.clone()),
+            std::sync::Arc::new(LocalSessionManager::default()),
+            http_config,
+        );
+
+    let token = cfg.token.clone();
+    let app = axum::Router::new()
+        .nest_service("/mcp", service)
+        .layer(axum::middleware::from_fn(
+            move |request: Request, next: Next| {
+                let token = token.clone();
+                async move { authorize(token, request, next).await }
+            },
+        ));
+
+    eprintln!(
+        "[unlucky-agent] MCP server 监听 http://{local}/mcp（{} 个工具；令牌：{}）",
+        server.tool_count(),
+        if cfg.token.is_some() {
+            "已启用"
+        } else {
+            "未设置（仅回环监听）"
+        }
+    );
+
+    axum::serve(listener, app)
+        .await
+        .map_err(|error| McpServeError::Io(error.to_string()))
+}
+
+/// Bearer 令牌闸门：未配置 = 放行；配置了则严格比对。
+async fn authorize(token: Option<String>, request: Request, next: Next) -> Response {
+    let Some(expected) = token else {
+        return next.run(request).await;
+    };
+    let presented = request
+        .headers()
+        .get(AUTHORIZATION)
+        .and_then(|value| value.to_str().ok())
+        .unwrap_or_default();
+    if presented == format!("Bearer {expected}") {
+        return next.run(request).await;
+    }
+    (
+        StatusCode::UNAUTHORIZED,
+        "缺少或错误的 Authorization: Bearer <agent.mcp.token>",
+    )
+        .into_response()
+}

crates/agent/src/mcp/server.rs

@@ -0,0 +1,243 @@
+//! rmcp `ServerHandler`：把同一份注册表挂成 MCP 工具路由。
+//!
+//! 每次 `tools/call` 都走 [`ToolExecutor`]——schema 校验、确认闸门、YOLO、审计、
+//! 事件**与内置客户端完全同一条路径**（02 §1 铁律）。工具级失败返回
+//! `CallToolResult::error`（客户端能看到文案），协议级错误只留给「路由不到」的情况
+//! （research/02 §3.2：`Err(McpError)` 会被大多数客户端吞成 "internal error"）。
+
+use std::sync::Arc;
+
+use rmcp::handler::server::tool::{ToolCallContext, ToolRoute, ToolRouter};
+use rmcp::model::{
+    CallToolRequestParams, CallToolResponse, CallToolResult, ContentBlock, Implementation,
+    ListToolsResult, PaginatedRequestParams, ServerCapabilities, ServerConfig, Tool,
+};
+use rmcp::service::RequestContext;
+use rmcp::{ErrorData as McpError, RoleServer, ServerHandler};
+use serde_json::Value;
+
+use crate::brain::chat::ToolCall;
+use crate::brain::exec::ToolExecutor;
+use crate::mcp::projection::tool_attr;
+use crate::registry::{Access, ToolRegistry};
+
+/// MCP server 的 `ServerHandler` 实现。
+///
+/// `Clone` 是 Streamable HTTP 要的：每个会话/请求由工厂造一份（共享同一批 `Arc`，
+/// 因此审计与策略仍是同一份）。
+#[derive(Clone)]
+pub struct RegistryServer {
+    router: ToolRouter<RegistryServer>,
+    visible: Arc<Vec<Tool>>,
+    session_id: String,
+}
+
+impl std::fmt::Debug for RegistryServer {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("RegistryServer")
+            .field("session_id", &self.session_id)
+            .field("tools", &self.visible.len())
+            .finish()
+    }
+}
+
+impl RegistryServer {
+    /// 用注册表 + 执行器装配。
+    ///
+    /// **`router_registry` 必须是完整注册表**（含写工具），`executor` 才决定「哪些工具真能跑」：
+    /// - 只读模式：`-executor` 用 `read_only_subset()` 装配，`tools/list` 只列只读项，
+    ///   硬调写工具会路由到执行器 → `unknown_tool`（**tool-level 错误 + 审计**），
+    ///   而不是 rmcp 的协议级 `-32602 tool not found`（那个客户端只会显示 "internal error"）。
+    /// - 写模式：两者都是完整注册表。
+    ///
+    /// `session_id` 进审计的 `agent_session_id` 字段（`mcp-http` / `mcp-stdio`），
+    /// 让复盘时能区分「内置对话改的」和「外部 MCP 改的」。
+    #[must_use]
+    pub fn new(
+        router_registry: Arc<ToolRegistry>,
+        executor: Arc<ToolExecutor>,
+        session_id: impl Into<String>,
+        read_only: bool,
+    ) -> Self {
+        let mut router = ToolRouter::new();
+        for spec in router_registry.specs() {
+            let attr = tool_attr(&spec.definition(), spec.access);
+            router.add_route(route(attr, Arc::clone(&executor)));
+        }
+        let visible: Vec<Tool> = router_registry
+            .specs()
+            .iter()
+            .filter(|spec| !read_only || spec.access == Access::ReadOnly)
+            .map(|spec| tool_attr(&spec.definition(), spec.access))
+            .collect();
+        Self {
+            router,
+            visible: Arc::new(visible),
+            session_id: session_id.into(),
+        }
+    }
+
+    /// 本 server **对外可见**的工具（`tools/list` 的内容）。
+    #[must_use]
+    pub fn tools(&self) -> Vec<Tool> {
+        (*self.visible).clone()
+    }
+
+    /// 审计用的会话标签。
+    #[must_use]
+    pub fn session_id(&self) -> &str {
+        &self.session_id
+    }
+
+    /// 对外可见的工具数（启动日志/断言用）。
+    #[must_use]
+    pub fn tool_count(&self) -> usize {
+        self.visible.len()
+    }
+}
+
+fn route(attr: Tool, executor: Arc<ToolExecutor>) -> ToolRoute<RegistryServer> {
+    ToolRoute::new_dyn(attr, move |context: ToolCallContext<'_, RegistryServer>| {
+        let executor = Arc::clone(&executor);
+        let session_id = context.service.session_id().to_string();
+        let name = context.name().to_string();
+        let arguments = context
+            .arguments
+            .clone()
+            .map_or_else(|| Value::Object(serde_json::Map::new()), Value::Object);
+
+        Box::pin(async move {
+            let call = ToolCall {
+                id: format!("mcp-{name}"),
+                name,
+                arguments,
+            };
+            let outcome = executor.execute(&session_id, &call, 0).await;
+            let text = outcome.to_model_content();
+            let content = vec![ContentBlock::text(text)];
+            let result = if outcome.ok {
+                CallToolResult::structured(outcome.content)
+            } else {
+                CallToolResult::error(content)
+            };
+            Ok(result.into())
+        })
+    })
+}
+
+impl ServerHandler for RegistryServer {
+    fn get_info(&self) -> ServerConfig {
+        ServerConfig::new(ServerCapabilities::builder().enable_tools().build())
+            .with_server_info(Implementation::new(
+                "unlucky-launcher",
+                env!("CARGO_PKG_VERSION"),
+            ))
+            .with_instructions(
+                "Unlucky-Launcher 的工具服务：读写启动器配置、看实例/版本/Java、读游戏日志、跑崩溃诊断。\
+                 账户凭据永不经由本服务出口；写配置受 schema 白名单与敏感键确认约束。",
+            )
+    }
+
+    async fn list_tools(
+        &self,
+        _request: Option<PaginatedRequestParams>,
+        _context: RequestContext<RoleServer>,
+    ) -> Result<ListToolsResult, McpError> {
+        Ok(ListToolsResult::with_all_items(self.tools()))
+    }
+
+    async fn call_tool(
+        &self,
+        request: CallToolRequestParams,
+        context: RequestContext<RoleServer>,
+    ) -> Result<CallToolResponse, McpError> {
+        let call_context = ToolCallContext::new(self, request, context);
+        self.router.call(call_context).await
+    }
+
+    fn get_tool(&self, name: &str) -> Option<Tool> {
+        self.router.get(name).cloned()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::audit::MemoryAudit;
+    use crate::clock::{FixedClock, SharedClock};
+    use crate::confirm::{AutoDenyGate, ConfirmPolicy};
+    use crate::event::NoopSink;
+    use crate::testing::mock_ports;
+    use crate::tools::build_v1_registry;
+    use serde_json::json;
+
+    fn server(registry: Arc<ToolRegistry>, read_only: bool) -> (RegistryServer, Arc<MemoryAudit>) {
+        let audit = Arc::new(MemoryAudit::new());
+        let clock: SharedClock = Arc::new(FixedClock::new(1_793_304_753_123));
+        let exposed = if read_only {
+            Arc::new(registry.read_only_subset())
+        } else {
+            Arc::clone(&registry)
+        };
+        let executor = Arc::new(ToolExecutor::new(
+            exposed,
+            audit.clone(),
+            Arc::new(AutoDenyGate),
+            ConfirmPolicy::default(),
+            clock,
+            Arc::new(NoopSink),
+        ));
+        (
+            RegistryServer::new(registry, executor, "mcp-test", read_only),
+            audit,
+        )
+    }
+
+    fn registry() -> Arc<ToolRegistry> {
+        let (ports, _settings) = mock_ports();
+        Arc::new(build_v1_registry(&ports).expect("注册表应装配成功"))
+    }
+
+    #[test]
+    fn lists_every_registered_tool_in_write_mode() {
+        let registry = registry();
+        let (server, _audit) = server(Arc::clone(&registry), false);
+        let tools = server.tools();
+        assert_eq!(tools.len(), registry.len());
+        assert_eq!(server.tool_count(), registry.len());
+        assert_eq!(server.session_id(), "mcp-test");
+        assert!(tools.iter().any(|tool| tool.name == "set_config"));
+    }
+
+    #[test]
+    fn read_only_mode_hides_the_writing_tool_but_keeps_it_routable() {
+        let (server, _audit) = server(registry(), true);
+        let names: Vec<String> = server.tools().iter().map(|t| t.name.to_string()).collect();
+        assert!(!names.iter().any(|n| n == "set_config"), "{names:?}");
+        assert!(names.iter().any(|n| n == "get_config"));
+        assert_eq!(names.len(), 9);
+        // 路由仍然存在（否则 rmcp 会回协议级 -32602，客户端看到的是 "internal error"），
+        // 真正拦下来的是只读子集执行器 → tool-level 错误 + 审计。
+        assert!(server.router.get("set_config").is_some());
+    }
+
+    #[test]
+    fn info_advertises_tools_and_a_stable_identity() {
+        let (server, _audit) = server(registry(), false);
+        let info = server.get_info();
+        assert!(info.capabilities.tools.is_some());
+        assert_eq!(info.server_info.name, "unlucky-launcher");
+    }
+
+    #[test]
+    fn get_tool_returns_the_projected_attr() {
+        let (server, _audit) = server(registry(), false);
+        let attr = server.get_tool("get_config").expect("工具存在");
+        assert_eq!(attr.name, "get_config");
+        assert_eq!(
+            Value::Object((*attr.input_schema).clone())["type"],
+            json!("object")
+        );
+        assert!(server.get_tool("nope").is_none());
+    }
+}

crates/agent/src/port.rs

@@ -0,0 +1,315 @@
+//! 端口层（port）：agent 与 `ull-core` 各模块之间**唯一**的接触面。
+//!
+//! 为什么不直接 `use ull_core::*`：M12（setting）/ M14（game）/ M15（diagnose）/ M18（launch）
+//! 与本 crate 并行开发，直接依赖会把 agent 的编译期绑死在别人的 API 日期上。这里用
+//! **依赖倒置**——agent 只声明自己需要的形状（本文件的 trait + 结构体），由 `crates/app`
+//! 在装配处用 `ull-core` 的实现去满足（`#![forbid(unsafe_code)]` 的纯适配层）。
+//!
+//! | 端口 | 提供的工具 | 对方模块 / 数据源 |
+//! |------|-----------|------------------|
+//! | [`SettingPort`] | `get_config` / `set_config` | M12 · `config/*.json` schema |
+//! | [`GameSessionPort`] | `list_game_sessions` / `read_game_log` | M18 · `agent/sessions/game/{index,<id>}.jsonl` |
+//! | [`DiagnosePort`] | `diagnose_crash` | M15 · 规则引擎 |
+//!
+//! 形状依据（以对方文件为准，改字段先改对方文件）：
+//! - `DevDocs/SubAgentsTalk/launch-接口约定.md` §2/§5（事件行 + 索引行）
+//! - `DevDocs/SubAgentsTalk/agent-ToolSpec约定.md`（本 crate 对外的对齐说明）
+//!
+//! 错误一律用 `Result<T, String>`：错误文本会**原样进工具结果**给模型与用户看
+//! （rmcp 的 `CallToolResult::error` 同理——协议级错误不给模型看，见 research/02 §3.2）。
+//! 因此端口实现写中文、面向用户、可执行（「配置键 `x` 不存在」而不是 `ENOENT`）。
+
+use std::collections::BTreeMap;
+use std::sync::Arc;
+
+use serde::Serialize;
+use serde_json::Value;
+
+use crate::confirm::Sensitivity;
+
+pub mod game;
+
+pub use game::{
+    AccountPort, AccountSummary, GamePort, InstanceSummary, JavaRuntimeSummary, JavaStatus,
+    VersionSummary,
+};
+
+/// 端口调用结果的错误文本（面向用户可读，直接进工具结果）。
+pub type PortResult<T> = Result<T, String>;
+
+/// agent 需要的全部端口。装配处（`crates/app` / `ull agent serve`）用它一次性注入。
+#[derive(Clone)]
+pub struct Ports {
+    /// 配置读写（M12）。
+    pub setting: Arc<dyn SettingPort>,
+    /// 游戏会话与日志（M18）。
+    pub sessions: Arc<dyn GameSessionPort>,
+    /// 崩溃规则引擎（M15）。
+    pub diagnose: Arc<dyn DiagnosePort>,
+    /// 实例 / 版本 / Java（M14 + M33）。
+    pub game: Arc<dyn GamePort>,
+    /// 账户元数据（M31，**只有公开字段**，凭据永不出口）。
+    pub accounts: Arc<dyn AccountPort>,
+}
+
+// ───────────────────────────── 配置（M12） ─────────────────────────────
+
+/// AI 可写白名单里的一个键，带**敏感分级**（02 文档 §3.1 的「分级确认」依据）。
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+pub struct SettingKey {
+    /// 点分路径，如 `download.concurrency`、`java.selected_path`（键名以 M12 的 schema 为准）。
+    pub path: String,
+    /// 敏感等级（M12 `Low/Medium/High`）：只有 `High` 需要用户确认。
+    pub sensitivity: Sensitivity,
+    /// 值类型（`string` / `integer` / `boolean` / `enum` / `json`），用于错误提示。
+    pub value_type: String,
+    /// 一句话说明，同时进 `get_config` 概要与模型上下文。
+    pub description: String,
+}
+
+/// 一次成功的写入，带旧值即「diff」（research/02 §6.4 的 dry-run 落点）。
+#[derive(Debug, Clone, Serialize, PartialEq)]
+pub struct SettingChange {
+    /// 被修改的键路径。
+    pub path: String,
+    /// 修改前的值；键此前不存在时为 `None`。
+    pub old: Option<Value>,
+    /// 写入后的值。
+    pub new: Value,
+}
+
+/// 配置端口（M12 实现，`ull-core::setting` 的 schema API 直译）。
+///
+/// agent 侧只做**白名单 + 敏感分级 + 确认编排**，值本身的范围/类型校验归 setting 模块所有
+/// （单一真相源：配置 schema 在 M12，agent 不复制一份）。
+pub trait SettingPort: Send + Sync {
+    /// 全量概要（`get_config()` 无参时返回）：键 → 当前值的扁平表，敏感键已脱敏。
+    fn summary(&self) -> Value;
+    /// 读单个键。键不存在时返回人类可读错误。
+    ///
+    /// **凭据契约**：`writable=false` 的凭据类键（`ai.api_key` 等）必须**拒绝或掩码**，
+    /// 不得返回明文——agent 侧还有一道 `redact::is_sensitive_key` 守卫，但端口是数据的
+    /// 第一道闸（模型上下文与对话历史都会带上这里的返回值）。
+    fn get(&self, path: &str) -> PortResult<Value>;
+    /// 写单个键（值校验由实现方负责），返回 diff。
+    fn set(&self, path: &str, value: &Value) -> PortResult<SettingChange>;
+    /// **AI 可写白名单**（含敏感分级）。不在表里的键 agent 一律拒绝。
+    fn writable_keys(&self) -> Vec<SettingKey>;
+    /// 配置 schema 的给 AI 版本（`get_config_schema` 工具）：只含 AI 可写键与
+    /// `x-ai-sensitivity` 标注，凭据类键天然不在其中（M12 `SettingSchema::to_json_schema`）。
+    fn schema(&self) -> Value;
+}
+
+// ──────────────────────── 游戏会话与日志（M18） ────────────────────────
+
+/// `index.jsonl` 一行 → 一个会话摘要（同 id 多行由实现方取最后一行）。
+///
+/// 字段对齐 `launch-接口约定.md` §5；对方新增字段时这里补 `Option`，不破坏旧实现。
+#[derive(Debug, Clone, Default, Serialize, PartialEq)]
+pub struct GameSessionSummary {
+    /// 会话 id，格式 `YYYYMMDDTHHMMSS-<6 位 hex>`（UTC）。
+    pub session_id: String,
+    /// 实例 id。
+    pub instance_id: Option<String>,
+    /// 实例显示名。
+    pub instance_name: Option<String>,
+    /// MC 版本。
+    pub game_version: Option<String>,
+    /// 启动时间（RFC3339 UTC）。
+    pub started_at: Option<String>,
+    /// 结束时间；会话未结束时为 `None`。
+    pub ended_at: Option<String>,
+    /// 时长毫秒。
+    pub duration_ms: u64,
+    /// 退出码；未正常结束时可能缺失。
+    pub exit_code: Option<i32>,
+    /// `exit_type`：`normal|application_error|jvm_error|sigkill|sigterm|killed|interrupted`。
+    pub exit_type: Option<String>,
+    /// exit 0 但疑似静默失败（D8 升级 1）。
+    pub silent_failure: bool,
+    /// 是否检测到游戏窗口。
+    pub window_detected: bool,
+    /// 事件条数。
+    pub event_count: u64,
+    /// 是否发现 crash-report / hs_err。
+    pub crash_found: bool,
+    /// 规则引擎首选结论 id（`diagnosis` 事件的 top candidate）。
+    pub diagnosis_top: Option<String>,
+}
+
+/// `read_game_log` 的查询条件：**按事件 seq 切片**，不是按行号
+/// （stdout/stderr 是一行一事件，但同一条日志行可能被切成多块，见 launch §1）。
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct LogQuery {
+    /// 起始 `seq`（含）。
+    pub from_seq: Option<u64>,
+    /// 结束 `seq`（含）。
+    pub to_seq: Option<u64>,
+    /// 只要这些 `kind`（空 = 全部）。未知 kind 由实现方忽略而不是报错（前向兼容）。
+    pub kinds: Vec<String>,
+    /// 最多返回多少条事件（工具层已钳到 [`crate::tools::session::MAX_LOG_EVENTS`]）。
+    pub max_events: usize,
+}
+
+/// 一条事件行（`{v,seq,ts,t_ms,kind,session_id,payload}`），落盘时已脱敏。
+#[derive(Debug, Clone, Serialize, PartialEq)]
+pub struct LogEvent {
+    /// 会话内单调递增序号。
+    pub seq: u64,
+    /// RFC3339 UTC。
+    pub ts: String,
+    /// 距会话开始的毫秒数。
+    pub t_ms: u64,
+    /// 事件类型（`stdout|stderr|exit|crash_found|diagnosis|…`）。
+    pub kind: String,
+    /// 事件负载，原样透传（已脱敏）。
+    pub payload: Value,
+}
+
+/// 一页日志事件 + 全量统计（模型拿到摘要就不会盲目翻页，防 token 爆炸）。
+#[derive(Debug, Clone, Default, Serialize, PartialEq)]
+pub struct LogPage {
+    /// 会话 id。
+    pub session_id: String,
+    /// 文件内事件总数。
+    pub total_events: u64,
+    /// 命中过滤条件的事件数。
+    pub matched_events: u64,
+    /// 是否因 `max_events` 截断。
+    pub truncated: bool,
+    /// 全量 kind 计数（不受过滤影响）。
+    pub kind_counts: BTreeMap<String, u64>,
+    /// 首事件时间。
+    pub first_ts: Option<String>,
+    /// 末事件时间。
+    pub last_ts: Option<String>,
+    /// 本次返回的事件（已按 seq 升序）。
+    pub events: Vec<LogEvent>,
+}
+
+/// 会话端口（M18 实现，`ull-core::launch::session_index` + `session` 的读侧）。
+///
+/// 读取**必须容忍最后一行不完整**（会话被 kill 时 jsonl 尾部可能截断）——这是实现方义务，
+/// 由 `launch-接口约定.md` §1 规定，agent 只消费结果。
+pub trait GameSessionPort: Send + Sync {
+    /// 按 `started_at` 倒序、按 `session_id` 去重后的会话列表；`instance_id` 非空时过滤。
+    fn list_sessions(
+        &self,
+        limit: usize,
+        instance_id: Option<&str>,
+    ) -> PortResult<Vec<GameSessionSummary>>;
+    /// 按 [`LogQuery`] 切片读取一个会话的事件流。
+    fn read_log(&self, session_id: &str, query: &LogQuery) -> PortResult<LogPage>;
+}
+
+// ───────────────────────── 崩溃诊断（M15） ─────────────────────────
+
+/// 六维修复动作（M15 `diagnose::rules::FixActionKind`，internally-tagged enum，
+/// YAML 里写 `kind:`）。序列化名与 M15 逐字相同：`change_java|adjust_memory|
+/// change_graphics|remove_mod|reinstall|seek_help`。
+#[derive(Debug, Clone, Copy, Serialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum FixActionKind {
+    /// 换 Java（大版本上下界/指定实现）。
+    ChangeJava,
+    /// 调 Xmx/Xms、64 位 Java、系统虚拟内存。
+    AdjustMemory,
+    /// 驱动/渲染器/分辨率/覆盖层。
+    ChangeGraphics,
+    /// 删/禁/换 mod。
+    RemoveMod,
+    /// 重装/修组件（java|game_jar|loader|natives|libraries|assets|mods…）。
+    Reinstall,
+    /// 导出诊断包 / 需要更多信息。
+    SeekHelp,
+}
+
+/// 一条修复建议（M15 的 `MaterializedFixAction { kind, tool, args }` + 一句人话）。
+///
+/// `tool` 是 M15 给的**语义动作 id**（`java.set` / `memory.set` / …）。P0 没有这些细分工具，
+/// 所以 agent 侧按 [`FixActionKind`] 桥接到现有工具（见 [`crate::tools::diagnose`]），
+/// `tool` 只原样透传给模型与审计，不用于分发。
+#[derive(Debug, Clone, Serialize, PartialEq)]
+pub struct FixAction {
+    /// 六维动作类别。
+    pub kind: FixActionKind,
+    /// 语义动作 id（如 `memory.set`）；P1 落对应工具后可直接当工具名。
+    pub tool: String,
+    /// 一句话建议（可为空，agent 会按 `kind` 补兜底文案）。
+    pub label: String,
+    /// 已做模板替换与单位换算的参数（M15 `materialize()` 的产物）。
+    pub args: std::collections::BTreeMap<String, String>,
+}
+
+/// 一条诊断候选（M15 `DiagnosisRecord::candidates[]`）。
+#[derive(Debug, Clone, Serialize, PartialEq)]
+pub struct DiagnosisCandidate {
+    /// 规则 id（如 `jvm.32bit`）。
+    pub id: String,
+    /// `critical|error|warn|info`。
+    pub severity: String,
+    /// 分组（`jvm|memory|graphics|integrity|mod|…`）。
+    pub category: String,
+    /// 置信度 0.0~1.0。
+    pub confidence: f32,
+    /// i18n key（如 `diagnose.cause.jvm.32bit`）。
+    pub message_key: String,
+    /// **渲染后**的人类可读结论（M15 保证非空；agent 侧只在极旧数据上回落 `message_key`）。
+    pub message: String,
+    /// 更细的处理建议（M15 `detail`，可能为空）。
+    pub detail: String,
+    /// 证据行（已脱敏）。
+    pub evidence: Vec<String>,
+    /// 该候选的修复动作。
+    pub fix_actions: Vec<FixAction>,
+}
+
+/// 退出摘要（M15 `DiagnosisRecord::exit`，与 launch 的 `exit` 事件同源）。
+#[derive(Debug, Clone, Default, Serialize, PartialEq)]
+pub struct ExitSummary {
+    /// 退出码。
+    pub code: Option<i32>,
+    /// `normal|application_error|jvm_error|sigkill|sigterm|killed|interrupted`。
+    pub exit_type: Option<String>,
+    /// exit 0 但疑似静默失败。
+    pub silent_failure: bool,
+}
+
+/// 规则引擎结论：**这就是给 LLM 的全部输入**（不是裸日志）。
+#[derive(Debug, Clone, Serialize, PartialEq)]
+pub struct CrashDiagnosis {
+    /// 会话 id。
+    pub session_id: String,
+    /// `rules|ai`（谁产出的）。
+    pub source: String,
+    /// 规则拿不准、需要更多信息时置 true（此时才值得让 LLM 深挖）。
+    pub needs_more_info: bool,
+    /// 主因候选，`candidates[0]` 即首因（M15 已按 priority→confidence 排序）。
+    pub candidates: Vec<DiagnosisCandidate>,
+    /// 被抑制的次要候选。
+    pub secondary: Vec<DiagnosisCandidate>,
+    /// 会话级关键片段（`crash_found.excerpt` / `hs_err` 摘要，已脱敏）。
+    pub evidence: Vec<String>,
+    /// 退出摘要。
+    pub exit: ExitSummary,
+}
+
+impl CrashDiagnosis {
+    /// 首选候选（主因）。
+    #[must_use]
+    pub fn top(&self) -> Option<&DiagnosisCandidate> {
+        self.candidates.first()
+    }
+
+    /// 最高置信度（没有候选时为 0）。
+    #[must_use]
+    pub fn top_confidence(&self) -> f32 {
+        self.top().map_or(0.0, |c| c.confidence)
+    }
+}
+
+/// 诊断端口（M15 实现）。agent 只做「调规则引擎 → 把结论 + 片段交给 LLM」。
+pub trait DiagnosePort: Send + Sync {
+    /// 对一个会话跑规则引擎。会话不存在/没有日志时返回人类可读错误。
+    fn diagnose(&self, session_id: &str) -> PortResult<CrashDiagnosis>;
+}

crates/agent/src/port/game.rs

@@ -0,0 +1,152 @@
+//! 实例 / 版本 / Java / 账户四个读侧端口（M39 的只读工具集用）。
+//!
+//! 与 [`super`] 的既有三个端口同形：trait 由 agent 声明，实现在装配层用 `unlucky-core` 填充。
+//! 拆分出来的原因是 `port.rs` 挨着 400 行硬上限（`guards.yml` 的 file-size 门禁）——
+//! 「会话与日志」「崩溃诊断」留在父模块，「游戏与账户」在这里，语义上也是一刀干净的分界。
+//!
+//! **凭据红线**（D9 / 02 文档 §3.1）：账户端口只露 [`AccountSummary`] 的公开字段。
+//! `Credentials`（access token / 刷新令牌 / authlib 密码）在 core 的 Secret 体系里，
+//! 根本不出现在本文件的类型里，因此不可能被工具结果带出去。
+
+use serde::Serialize;
+
+use super::PortResult;
+
+// ───────────────────────── 实例 / 版本（M14） ─────────────────────────
+
+/// 一个实例（`profiles.json` 一行）的摘要：模型只需要「能定位、能判断载荷在不在」。
+#[derive(Debug, Clone, Default, Serialize, PartialEq, Eq)]
+pub struct InstanceSummary {
+    /// 实例 id。
+    pub id: String,
+    /// 显示名。
+    pub name: String,
+    /// 版本 id（如 `1.21.1` / `fabric-loader-0.16.9-1.21.1`）。
+    pub version_id: String,
+    /// 该版本的载荷是否真的在 `versions/` 下（`false` = 装了档案但载荷缺失）。
+    pub version_present: bool,
+    /// 独立游戏目录（未覆盖时为 `None`）。
+    pub game_dir: Option<String>,
+    /// 实例级 Java 覆盖路径（未覆盖时为 `None`）。
+    pub java_path: Option<String>,
+    /// 上次启动时刻（Unix 毫秒；从未启动为 `None`）。
+    pub last_played_at: Option<u64>,
+}
+
+/// 已安装版本的摘要（`versions/<id>/` 的存在性 + 可读的元信息）。
+#[derive(Debug, Clone, Default, Serialize, PartialEq, Eq)]
+pub struct VersionSummary {
+    /// 版本 id。
+    pub id: String,
+    /// 版本 JSON 里声明的 `type`（`release` / `snapshot` / 加载器自报），读不到为 `None`。
+    pub kind: Option<String>,
+    /// 被几个实例引用。
+    pub instance_count: usize,
+}
+
+// ──────────────────────────── Java（M33） ────────────────────────────
+
+/// 一个探测到的 Java 运行时。
+#[derive(Debug, Clone, Default, Serialize, PartialEq, Eq)]
+pub struct JavaRuntimeSummary {
+    /// `java` 可执行文件路径。
+    pub binary: String,
+    /// 完整版本串（`21.0.2` / `1.8.0_402`）。
+    pub version: Option<String>,
+    /// 主版本号（8 / 17 / 21）。
+    pub major: Option<u32>,
+    /// 发行方（temurin / oracle / microsoft / zulu …）。
+    pub vendor: Option<String>,
+    /// 来源类别（`instance` / `managed` / `env` / `system`）。
+    pub origin: String,
+}
+
+/// Java 现状（`get_java_status`）。
+#[derive(Debug, Clone, Default, Serialize, PartialEq, Eq)]
+pub struct JavaStatus {
+    /// 默认堆内存（MB，`java.default_memory_mb`）。
+    pub default_memory_mb: Option<u64>,
+    /// 托管 JDK 的扫描根。
+    pub managed_roots: Vec<String>,
+    /// 探测到的候选（已去重，优先级从高到低）。
+    pub candidates: Vec<JavaRuntimeSummary>,
+}
+
+// ──────────────────────────── 账户（M31） ────────────────────────────
+
+/// 账户的**公开字段**摘要。凭据类字段刻意不存在（凭据红线）。
+#[derive(Debug, Clone, Default, Serialize, PartialEq, Eq)]
+pub struct AccountSummary {
+    /// 条目 id。
+    pub id: String,
+    /// 轨道：`offline` / `microsoft` / `authlib`。
+    pub kind: String,
+    /// Minecraft 档案 UUID（32 位无连字符）。
+    pub profile_id: String,
+    /// 玩家名（可能为空串 = 有档案但名字待刷新）。
+    pub profile_name: String,
+    /// 登录名（仅 authlib 轨有值）。
+    pub login_name: Option<String>,
+    /// 创建时刻（Unix 毫秒）。
+    pub created_at_ms: u64,
+}
+
+/// 游戏资产端口（M14 实例/版本 + M33 Java 探测）。
+pub trait GamePort: Send + Sync {
+    /// 全部实例（按上次启动时间倒序）。
+    fn list_instances(&self) -> PortResult<Vec<InstanceSummary>>;
+    /// 已安装版本清单。
+    fn list_versions(&self) -> PortResult<Vec<VersionSummary>>;
+    /// Java 现状（候选 + 托管根 + 默认内存）。
+    fn java_status(&self) -> PortResult<JavaStatus>;
+}
+
+/// 账户端口（M31）。实现方只允许读 `AccountStore::accounts()`（`AccountMeta`），
+/// **不得**调用 `credentials()`——那是凭据出口，agent 侧没有对应字段可以承接。
+pub trait AccountPort: Send + Sync {
+    /// 账户清单（公开字段）。
+    fn list_accounts(&self) -> PortResult<Vec<AccountSummary>>;
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn account_summary_has_no_credential_fields() {
+        // 把摘要序列化成 JSON：任何 token / password / secret 形态的键都不许出现。
+        // 这是凭据红线的**可执行断言**——将来有人往结构体里加字段，这条测试先炸。
+        let summary = AccountSummary {
+            id: "a1".to_string(),
+            kind: "offline".to_string(),
+            profile_id: "0123456789abcdef0123456789abcdef".to_string(),
+            profile_name: "Steve".to_string(),
+            login_name: Some("steve@example.com".to_string()),
+            created_at_ms: 1_793_304_753_123,
+        };
+        let json = serde_json::to_string(&summary).expect("可序列化");
+        for forbidden in ["token", "password", "secret", "credential", "refresh"] {
+            assert!(
+                !json.to_lowercase().contains(forbidden),
+                "账户摘要不得包含 `{forbidden}`：{json}"
+            );
+        }
+    }
+
+    #[test]
+    fn java_status_round_trips() {
+        let status = JavaStatus {
+            default_memory_mb: Some(2048),
+            managed_roots: vec!["/data/java-managed".to_string()],
+            candidates: vec![JavaRuntimeSummary {
+                binary: "/jdk/bin/java".to_string(),
+                version: Some("21.0.2".to_string()),
+                major: Some(21),
+                vendor: Some("temurin".to_string()),
+                origin: "managed".to_string(),
+            }],
+        };
+        assert_eq!(status.candidates.len(), 1);
+        assert_eq!(status.candidates[0].major, Some(21));
+    }
+}

crates/agent/src/redact.rs

@@ -0,0 +1,217 @@
+//! 脱敏：审计日志的参数、以及日志工具返回文本的**第二道**防线。
+//!
+//! 第一道在 launch 落盘时（`launch-接口约定.md` §4：`<redacted:token>` / `<home>` /
+//! `<redacted:opaque>`），所以这里不重复实现那套；本模块只兜两件事：
+//! 1. 审计日志里的参数可能含 API key（`set_config` 能改 AI 端点）→ 按键名掩码；
+//! 2. 日志正文万一含用户主目录绝对路径（旧会话、第三方 mod 输出）→ 掩码用户名段。
+//!
+//! 幂等：对已脱敏文本再跑一遍结果不变（`<home>` / `***` 原样保留）。
+
+use serde_json::{Map, Value};
+
+/// 掩码占位。
+pub const MASK: &str = "***";
+
+/// 键名是否敏感（不区分大小写，含子串即算）。
+///
+/// 覆盖：`api_key` / `apikey` / `accessToken` / `session_token` / `password` /
+/// `secret` / `authorization` / `credential`。
+#[must_use]
+pub fn is_sensitive_key(key: &str) -> bool {
+    const NEEDLES: [&str; 8] = [
+        "api_key",
+        "apikey",
+        "token",
+        "password",
+        "passwd",
+        "secret",
+        "authorization",
+        "credential",
+    ];
+    let lower = key.to_ascii_lowercase();
+    NEEDLES.iter().any(|n| lower.contains(n))
+}
+
+/// 审计用：递归把敏感键的值换成 [`MASK`]（保留结构，读审计的人仍能看出改的是哪个键）。
+///
+/// 除了「键名本身敏感」之外，还认 `set_config {path, value}` 这种**值随路径敏感**的形状：
+/// 当同级的 `path` 是敏感键名（`ai.api_key`）时，`value`/`old`/`new` 一律掩码——
+/// 否则审计日志会把 API key 原文写进磁盘。
+#[must_use]
+pub fn redact_args(value: &Value) -> Value {
+    match value {
+        Value::Object(map) => {
+            let sensitive_path = map
+                .get("path")
+                .and_then(Value::as_str)
+                .is_some_and(is_sensitive_key);
+            let mut out = Map::with_capacity(map.len());
+            for (k, v) in map {
+                let mask = is_sensitive_key(k)
+                    || (sensitive_path && matches!(k.as_str(), "value" | "old" | "new"));
+                let masked = if mask {
+                    Value::String(MASK.to_string())
+                } else {
+                    redact_args(v)
+                };
+                out.insert(k.clone(), masked);
+            }
+            Value::Object(out)
+        }
+        Value::Array(items) => Value::Array(items.iter().map(redact_args).collect()),
+        other => other.clone(),
+    }
+}
+
+/// 文本脱敏：用户主目录段 + `Bearer` 令牌。已脱敏文本原样返回（幂等）。
+#[must_use]
+pub fn redact_text(text: &str) -> String {
+    let masked = mask_user_dirs(text);
+    mask_bearer(&masked)
+}
+
+/// 任意 JSON 的每个字符串都过 [`redact_text`]（工具结果出口的第二道防线）。
+///
+/// 与 [`redact_args`] 的分工：那个按键名掩码（审计参数），这个按**内容**掩码
+/// （日志正文、账户展示名之类可能夹带主目录/Bearer 的字符串）。
+#[must_use]
+pub fn redact_texts(value: &Value) -> Value {
+    match value {
+        Value::String(text) => Value::String(redact_text(text)),
+        Value::Array(items) => Value::Array(items.iter().map(redact_texts).collect()),
+        Value::Object(map) => Value::Object(
+            map.iter()
+                .map(|(key, child)| (key.clone(), redact_texts(child)))
+                .collect(),
+        ),
+        other => other.clone(),
+    }
+}
+
+/// `C:\Users\<名>` / `/home/<名>` / `/Users/<名>` → 用户名段替换为 [`MASK`]。
+fn mask_user_dirs(text: &str) -> String {
+    let lower = text.to_ascii_lowercase();
+    let mut out = String::with_capacity(text.len());
+    let mut cursor = 0usize;
+    while cursor < text.len() {
+        let Some((start, marker_len)) = find_marker(&lower, cursor) else {
+            out.push_str(&text[cursor..]);
+            break;
+        };
+        out.push_str(&text[cursor..start + marker_len]);
+        let name_start = start + marker_len;
+        let name_end = segment_end(text, name_start);
+        let segment = &text[name_start..name_end];
+        if segment.is_empty() || segment == MASK || segment.eq_ignore_ascii_case("<home>") {
+            out.push_str(segment);
+        } else {
+            out.push_str(MASK);
+        }
+        cursor = name_end;
+    }
+    out
+}
+
+/// 找最靠前的用户目录标记，返回 `(字节位置, 标记长度)`。标记须与 `lower` 同源。
+fn find_marker(lower: &str, from: usize) -> Option<(usize, usize)> {
+    const MARKERS: [&str; 3] = ["c:\\users\\", "/home/", "/users/"];
+    MARKERS
+        .iter()
+        .filter_map(|m| lower[from..].find(m).map(|p| (from + p, m.len())))
+        .min_by_key(|(start, _)| *start)
+}
+
+/// 从 `from` 起取到下一个路径分隔符/空白/引号为止。
+fn segment_end(text: &str, from: usize) -> usize {
+    const STOPS: [char; 9] = ['\\', '/', '"', '\'', ' ', '\t', '\n', '\r', ','];
+    text[from..]
+        .find(STOPS)
+        .map_or(text.len(), |offset| from + offset)
+}
+
+/// `Bearer <token>` → `Bearer ***`。
+fn mask_bearer(text: &str) -> String {
+    let mut out = String::with_capacity(text.len());
+    let mut cursor = 0usize;
+    while let Some(pos) = text[cursor..].find("Bearer ") {
+        let token_start = cursor + pos + "Bearer ".len();
+        let token_end = segment_end(text, token_start);
+        out.push_str(&text[cursor..token_start]);
+        if token_end > token_start {
+            out.push_str(MASK);
+        }
+        cursor = token_end;
+    }
+    out.push_str(&text[cursor..]);
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn masks_sensitive_arg_keys_only() {
+        let args = json!({
+            "path": "launcher.theme",
+            "value": "light",
+            "nested": { "accessToken": "abc", "keep": 1 },
+            "list": [{ "password": "p" }]
+        });
+        let red = redact_args(&args);
+        // 非敏感路径：值原样保留（审计要能看出改成了什么）
+        assert_eq!(red["value"], json!("light"));
+        assert_eq!(red["path"], json!("launcher.theme"));
+        // 键名敏感：值掩码
+        assert_eq!(red["nested"]["accessToken"], json!(MASK));
+        assert_eq!(red["nested"]["keep"], json!(1));
+        assert_eq!(red["list"][0]["password"], json!(MASK));
+    }
+
+    #[test]
+    fn masks_value_when_path_itself_is_sensitive() {
+        // `set_config {path: "ai.api_key", value: "sk-…"}` 是最容易漏的泄漏点
+        let args = json!({ "path": "ai.api_key", "value": "sk-super-secret" });
+        let red = redact_args(&args);
+        assert_eq!(red["value"], json!(MASK));
+        let rendered = red.to_string();
+        assert!(!rendered.contains("sk-super-secret"), "{rendered}");
+    }
+
+    #[test]
+    fn masks_windows_and_posix_home() {
+        assert_eq!(
+            redact_text(r"C:\Users\aska\.minecraft\logs\latest.log"),
+            r"C:\Users\***\.minecraft\logs\latest.log"
+        );
+        assert_eq!(
+            redact_text("/home/aska/.minecraft/logs"),
+            "/home/***/.minecraft/logs"
+        );
+    }
+
+    #[test]
+    fn keeps_already_redacted_and_is_idempotent() {
+        let once = redact_text(r"C:\Users\aska\game\log.txt");
+        assert_eq!(once, r"C:\Users\***\game\log.txt");
+        assert_eq!(redact_text(&once), once);
+        assert_eq!(redact_text("<home>/.minecraft"), "<home>/.minecraft");
+    }
+
+    #[test]
+    fn masks_bearer_token() {
+        assert_eq!(
+            redact_text("Authorization: Bearer eyJhbGciOi.payload.sig"),
+            "Authorization: Bearer ***"
+        );
+    }
+
+    #[test]
+    fn detects_sensitive_key_names() {
+        assert!(is_sensitive_key("ai.api_key"));
+        assert!(is_sensitive_key("AccessToken"));
+        assert!(is_sensitive_key("proxy.password"));
+        assert!(!is_sensitive_key("download.concurrency"));
+    }
+}

crates/agent/src/registry/mod.rs

@@ -0,0 +1,260 @@
+//! 工具注册表：整个 agent 的**唯一真相源**。
+//!
+//! 一个 `ToolSpec`（名称 + 描述 + serde JSON Schema）投影两份：
+//! - 内置客户端的 rig `DynamicTool` 视图；
+//! - 对外 MCP server 的 rmcp `ToolRouter` 视图。
+//!
+//! 两份投影必须一致，用契约测试固定（同 name / 同 description / 同 schema）。
+//! 设计依据：`DevDocs/PlanDoc/02-ai-agent-design.md` §1。
+//!
+//! 工具 v1 清单（M16 起，M39 扩到十个）：`get_config` / `set_config` / `get_config_schema` /
+//! `list_instances` / `list_versions` / `get_java_status` / `list_accounts` /
+//! `list_game_sessions` / `read_game_log` / `diagnose_crash`。
+//!
+//! 安全策略随工具走：敏感键分级确认、YOLO 模式标记、审计留痕（02 §3.1 / §4b）。
+//!
+//! ## 落地形态
+//!
+//! ```text
+//! registry（Vec<ToolSpec>）
+//!   ├─ definitions() → rig `DynamicTool::new`    （内置 agent，`brain::rig`）
+//!   └─ definitions() → rmcp `ToolRoute::new_dyn` （外部 MCP，`mcp::projection`）
+//! ```
+//!
+//! 防漂移的关键一招（research/02 §6.2 建议进 CI）：**契约测试**遍历注册表，断言两侧
+//! 投影拿到的 `(name, description, schema)` 逐字节相等。因为两侧都只吃
+//! [`ToolDefinition`]，这条约束在本 crate 里天然成立——测试只需要锁住
+//! 「definition 是纯投影」+「schema 根必须是 object」+「名字不重复」。
+//!
+//! 注册表**不持有任何端口**：工具闭包在构造时就捕获了 `Arc<dyn …Port>`，注册表只是索引。
+
+pub mod schema;
+pub mod spec;
+pub mod validate;
+
+use std::collections::{BTreeMap, BTreeSet};
+use std::fmt;
+use std::sync::Arc;
+
+pub use spec::{
+    Access, Confirmation, ToolCtx, ToolDefinition, ToolError, ToolFn, ToolOutput, ToolSpec,
+};
+
+/// 注册失败原因。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum RegistryError {
+    /// 工具名为空或重复。
+    DuplicateName(String),
+    /// schema 不合法（根必须是 `type: object`，否则 MCP 侧直接拒收）。
+    InvalidSchema {
+        /// 工具名。
+        tool: String,
+        /// 原因。
+        reason: String,
+    },
+    /// 说明为空（模型靠 description 选工具，空说明等于没有这个工具）。
+    EmptyDescription(String),
+}
+
+impl fmt::Display for RegistryError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::DuplicateName(name) => write!(f, "工具名重复或为空：`{name}`"),
+            Self::InvalidSchema { tool, reason } => {
+                write!(f, "工具 `{tool}` 的 schema 不合法：{reason}")
+            }
+            Self::EmptyDescription(name) => write!(f, "工具 `{name}` 缺少说明"),
+        }
+    }
+}
+
+impl std::error::Error for RegistryError {}
+
+/// 工具注册表。
+#[derive(Debug, Default, Clone)]
+pub struct ToolRegistry {
+    specs: Vec<Arc<ToolSpec>>,
+    index: BTreeMap<String, usize>,
+}
+
+impl ToolRegistry {
+    /// 空注册表。
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// 注册一个工具。注册即校验名/schema/说明，**运行时不再做二次判断**。
+    ///
+    /// # Errors
+    /// 名字重复或为空、schema 根不是 object、说明为空时返回 [`RegistryError`]。
+    pub fn register(&mut self, spec: ToolSpec) -> Result<(), RegistryError> {
+        let name = spec.name.trim();
+        if name.is_empty() || self.index.contains_key(name) {
+            return Err(RegistryError::DuplicateName(name.to_string()));
+        }
+        if spec.description.trim().is_empty() {
+            return Err(RegistryError::EmptyDescription(name.to_string()));
+        }
+        if spec.input_schema.get("type").and_then(|t| t.as_str()) != Some("object") {
+            return Err(RegistryError::InvalidSchema {
+                tool: name.to_string(),
+                reason: "根类型必须是 object（rig 与 rmcp 的入参都是对象 schema）".to_string(),
+            });
+        }
+        self.index.insert(name.to_string(), self.specs.len());
+        self.specs.push(Arc::new(spec));
+        Ok(())
+    }
+
+    /// 按名查找。
+    #[must_use]
+    pub fn get(&self, name: &str) -> Option<&Arc<ToolSpec>> {
+        self.index.get(name).and_then(|i| self.specs.get(*i))
+    }
+
+    /// 全部工具（按注册顺序，模型看到的顺序稳定）。
+    #[must_use]
+    pub fn specs(&self) -> &[Arc<ToolSpec>] {
+        &self.specs
+    }
+
+    /// 工具名列表（错误提示/审计用）。
+    #[must_use]
+    pub fn names(&self) -> Vec<&str> {
+        self.specs.iter().map(|s| s.name).collect()
+    }
+
+    /// 工具数量。
+    #[must_use]
+    pub fn len(&self) -> usize {
+        self.specs.len()
+    }
+
+    /// 是否没有工具。
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.specs.is_empty()
+    }
+
+    /// **投影 1/2 的公共载荷**：`(name, description, input_schema)`。
+    #[must_use]
+    pub fn definitions(&self) -> Vec<ToolDefinition> {
+        self.specs.iter().map(|s| s.definition()).collect()
+    }
+
+    /// 只读子集（P1 的 `--readonly` 外部 MCP 模式用）。
+    #[must_use]
+    pub fn read_only_definitions(&self) -> Vec<ToolDefinition> {
+        self.specs
+            .iter()
+            .filter(|s| s.access == Access::ReadOnly)
+            .map(|s| s.definition())
+            .collect()
+    }
+
+    /// **只读模式**的注册表副本（外部 MCP 默认形态）。
+    ///
+    /// 返回的是「物理上不含写工具」的新注册表：`tools/list` 里看不到 `set_config`，
+    /// 硬调它也会在编排层得到 `unknown_tool`（并留一条审计），而不是静默执行。
+    /// 这比「列表过滤 + 调用拦截」两套逻辑更不容易漏——只有一份子集，两侧天然一致。
+    #[must_use]
+    pub fn read_only_subset(&self) -> Self {
+        let mut subset = Self::new();
+        for spec in self.specs.iter().filter(|s| s.access == Access::ReadOnly) {
+            let name = spec.name.to_string();
+            if subset.index.insert(name, subset.specs.len()).is_none() {
+                subset.specs.push(Arc::clone(spec));
+            }
+        }
+        subset
+    }
+
+    /// 名 → access（装配处检查白名单/只读模式）。
+    #[must_use]
+    pub fn access_of(&self, name: &str) -> Option<Access> {
+        self.get(name).map(|s| s.access)
+    }
+
+    /// 去重后的名字集合（契约测试用）。
+    #[must_use]
+    pub fn unique_names(&self) -> BTreeSet<&str> {
+        self.specs.iter().map(|s| s.name).collect()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::registry::schema::{non_empty_string, object};
+    use serde_json::{json, Value};
+
+    fn echo(name: &'static str) -> ToolSpec {
+        ToolSpec::read_only(
+            name,
+            "回显",
+            object(&[("text", non_empty_string("文本"))], &["text"]),
+            Arc::new(|_ctx: &ToolCtx, args: &Value| Ok(ToolOutput::ok(args.clone(), "echo"))),
+        )
+    }
+
+    #[test]
+    fn register_and_lookup() {
+        let mut reg = ToolRegistry::new();
+        reg.register(echo("echo")).unwrap();
+        assert_eq!(reg.len(), 1);
+        assert_eq!(reg.names(), vec!["echo"]);
+        assert!(reg.get("echo").is_some());
+        assert!(reg.get("nope").is_none());
+        assert_eq!(reg.access_of("echo"), Some(Access::ReadOnly));
+    }
+
+    #[test]
+    fn rejects_duplicate_empty_and_non_object_schema() {
+        let mut reg = ToolRegistry::new();
+        reg.register(echo("echo")).unwrap();
+        assert_eq!(
+            reg.register(echo("echo")),
+            Err(RegistryError::DuplicateName("echo".into()))
+        );
+
+        let bad = ToolSpec::read_only(
+            "bad",
+            "x",
+            json!({ "type": "array" }),
+            Arc::new(|_, _| Ok(ToolOutput::ok(Value::Null, "x"))),
+        );
+        assert!(matches!(
+            reg.register(bad),
+            Err(RegistryError::InvalidSchema { .. })
+        ));
+
+        let no_desc = ToolSpec::read_only(
+            "nodesc",
+            "  ",
+            json!({ "type": "object" }),
+            Arc::new(|_, _| Ok(ToolOutput::ok(Value::Null, "x"))),
+        );
+        assert!(matches!(
+            reg.register(no_desc),
+            Err(RegistryError::EmptyDescription(_))
+        ));
+    }
+
+    #[test]
+    fn definitions_are_stable_and_filterable() {
+        let mut reg = ToolRegistry::new();
+        reg.register(echo("a")).unwrap();
+        reg.register(ToolSpec::mutating(
+            "b",
+            "写",
+            json!({ "type": "object" }),
+            Arc::new(|_, _| Ok(ToolOutput::ok(Value::Null, "b"))),
+        ))
+        .unwrap();
+        assert_eq!(reg.definitions().len(), 2);
+        assert_eq!(reg.read_only_definitions().len(), 1);
+        assert_eq!(reg.definitions()[0].name, "a");
+        assert_eq!(reg.unique_names().len(), 2);
+    }
+}

crates/agent/src/registry/schema.rs

@@ -0,0 +1,116 @@
+//! JSON Schema 构造helper。
+//!
+//! 工具参数 schema 一律**手写 JSON**（research/02 §6.2：`rig` 的 `DynamicTool::new` 与
+//! rmcp 的 `ToolRoute::new_dyn` 吃的都是裸 `serde_json::Value`），所以不需要 schemars 派生。
+//! 手写的好处是同一份 schema 直接喂两方，坏处是啰嗦——这个模块把啰嗦收敛到几个函数。
+//!
+//! 生成的 schema 一律按 **JSON Schema 2020-12** 的写法（rmcp 支持该版本；
+//! `additionalProperties: false` 让模型少给野参数，[`super::validate`] 会执行它）。
+
+use serde_json::{json, Map, Value};
+
+/// 对象 schema。`properties` 按给定顺序写入（JSON 对象保序，UI 展示稳定）。
+#[must_use]
+pub fn object(properties: &[(&str, Value)], required: &[&str]) -> Value {
+    let mut props = Map::new();
+    for (name, schema) in properties {
+        props.insert((*name).to_string(), schema.clone());
+    }
+    json!({
+        "type": "object",
+        "properties": Value::Object(props),
+        "required": required,
+        "additionalProperties": false,
+    })
+}
+
+/// 任意 JSON 值（不校验类型）。
+#[must_use]
+pub fn any() -> Value {
+    json!({})
+}
+
+/// 字符串。
+#[must_use]
+pub fn string(description: &str) -> Value {
+    json!({ "type": "string", "description": description })
+}
+
+/// 非空字符串（`minLength: 1`，省掉一堆「路径不能为空」的运行时判断）。
+#[must_use]
+pub fn non_empty_string(description: &str) -> Value {
+    json!({ "type": "string", "description": description, "minLength": 1 })
+}
+
+/// 枚举字符串。
+#[must_use]
+pub fn string_enum(values: &[&str], description: &str) -> Value {
+    json!({ "type": "string", "description": description, "enum": values })
+}
+
+/// 布尔。
+#[must_use]
+pub fn boolean(description: &str) -> Value {
+    json!({ "type": "boolean", "description": description })
+}
+
+/// 带范围约束的整数。
+#[must_use]
+pub fn integer(description: &str, minimum: i64, maximum: i64) -> Value {
+    json!({
+        "type": "integer",
+        "description": description,
+        "minimum": minimum,
+        "maximum": maximum,
+    })
+}
+
+/// 字符串数组（可选条数上限）。
+#[must_use]
+pub fn string_array(description: &str, max_items: u64) -> Value {
+    json!({
+        "type": "array",
+        "description": description,
+        "items": { "type": "string" },
+        "maxItems": max_items,
+    })
+}
+
+/// 枚举字符串数组（如 `kinds: ["stderr","exit"]`）。
+#[must_use]
+pub fn enum_string_array(values: &[&str], description: &str, max_items: u64) -> Value {
+    json!({
+        "type": "array",
+        "description": description,
+        "items": { "type": "string", "enum": values },
+        "maxItems": max_items,
+        "uniqueItems": true,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::registry::validate::validate;
+
+    #[test]
+    fn object_records_required_and_forbids_extras() {
+        let schema = object(
+            &[("path", non_empty_string("键路径")), ("value", any())],
+            &["path", "value"],
+        );
+        assert_eq!(schema["type"], json!("object"));
+        assert_eq!(schema["additionalProperties"], json!(false));
+        assert_eq!(schema["required"], json!(["path", "value"]));
+        assert!(validate(&schema, &json!({ "path": "a", "value": 1 })).is_ok());
+    }
+
+    #[test]
+    fn integer_builder_carries_bounds() {
+        let schema = integer("条数", 1, 500);
+        assert_eq!(schema["minimum"], json!(1));
+        assert_eq!(schema["maximum"], json!(500));
+        assert!(validate(&schema, &json!(0)).is_err());
+        assert!(validate(&schema, &json!(500)).is_ok());
+    }
+}

crates/agent/src/registry/spec.rs

@@ -0,0 +1,262 @@
+//! 工具的**唯一定义类型**（[`ToolSpec`]）与它的两份投影载荷（[`ToolDefinition`]）。
+//!
+//! 双投影的支点在 research/02 §6.2：`rig::tool::DynamicTool::new(name, description,
+//! parameters: serde_json::Value, ..)` 与 `rmcp::ToolRoute::new_dyn(name, description,
+//! schema, handler)` 的入参**都是裸 JSON Schema**。所以本 crate 只维护一份
+//! [`ToolSpec`]，由 [`ToolSpec::definition`] 生成两侧共用的 `(name, description, schema)`。
+//!
+//! 工具实现是**同步**的：端口调用全是本地文件/内存，没有网络 IO；异步只存在于
+//! provider 边界（[`crate::brain::provider::ChatProvider`]）。P1 若出现网络类工具
+//! （mod 搜索/版本安装）再升成 `Fn -> BoxFuture`，不影响调用方语义。
+
+use std::fmt;
+use std::sync::Arc;
+
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+use crate::confirm::Sensitivity;
+
+/// 工具的副作用等级（外部 MCP 只读模式、P1 的 `--readonly` 都按它筛）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum Access {
+    /// 只读：可以给外部 agent、可以在无确认的情况下调用。
+    ReadOnly,
+    /// 会改用户数据（写配置），受白名单 + 分级确认约束。
+    Mutating,
+}
+
+/// 工具定义的三元组：**双投影就投这个**。
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct ToolDefinition {
+    /// 工具名（模型可见，`snake_case`）。
+    pub name: String,
+    /// 一句话说明（模型可见）。
+    pub description: String,
+    /// 参数 JSON Schema（2020-12，根类型必须 `object`）。
+    pub input_schema: Value,
+}
+
+/// 工具调用上下文：编排层注入，工具只读。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ToolCtx {
+    /// agent 对话会话 id（审计用；与游戏 session_id 不是一回事）。
+    pub agent_session_id: String,
+    /// 是否已获确认。**只有编排层能置 true**（YOLO 或用户点了允许），
+    /// 工具据此决定「先报价再执行」还是「直接执行」。
+    pub confirmed: bool,
+}
+
+/// 工具的返回。
+#[derive(Debug, Clone, PartialEq)]
+pub struct ToolOutput {
+    /// 给模型/审计的结构化结果（编排层序列化成 JSON 字符串回灌）。
+    pub content: Value,
+    /// 一句话摘要（UI 展示 + 审计 summary）。
+    pub summary: String,
+    /// 非空表示「这次没执行，先要确认」（[`crate::confirm::ConfirmRequest`] 的原料）。
+    pub confirmation: Option<Confirmation>,
+}
+
+/// 待确认的操作详情（dry-run 的产物）。
+#[derive(Debug, Clone, PartialEq)]
+pub struct Confirmation {
+    /// 一句话请求（「AI 请求把 X 从 A 改为 B」）。
+    pub summary: String,
+    /// 结构化 diff（`{"path":…,"old":…,"new":…}`）。
+    pub details: Value,
+    /// 敏感等级（决定 YOLO 能不能跳过）。
+    pub sensitivity: Sensitivity,
+}
+
+impl ToolOutput {
+    /// 成功返回。
+    #[must_use]
+    pub fn ok(content: Value, summary: impl Into<String>) -> Self {
+        Self {
+            content,
+            summary: summary.into(),
+            confirmation: None,
+        }
+    }
+
+    /// 需要确认（本次**没有**产生副作用）。
+    #[must_use]
+    pub fn needs_confirmation(
+        summary: impl Into<String>,
+        details: Value,
+        sensitivity: Sensitivity,
+    ) -> Self {
+        let summary = summary.into();
+        Self {
+            content: serde_json::json!({
+                "status": "needs_confirmation",
+                "summary": summary,
+            }),
+            confirmation: Some(Confirmation {
+                summary: summary.clone(),
+                details,
+                sensitivity,
+            }),
+            summary,
+        }
+    }
+}
+
+/// 工具错误。**全部面向用户可读**——它们会作为工具结果回到模型，
+/// 由模型决定重试还是换方案（rmcp 的 `Ok(CallToolResult::error(..))` 同义，
+/// 见 research/02 §3.2：协议级 `Err` 会被客户端吞掉，不能用来报业务错误）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ToolError {
+    /// 参数语义不合法（schema 校验之外的规则，如路径不在白名单）。
+    NotAllowed(String),
+    /// 找不到对象（会话/键/文件）。
+    NotFound(String),
+    /// 端口（M12/M15/M18）报错，文本原样透传。
+    Port(String),
+    /// 工具自身内部错误（不该发生）。
+    Internal(String),
+}
+
+impl ToolError {
+    /// 一句话文案（写日志/审计用）。
+    #[must_use]
+    pub fn message(&self) -> &str {
+        match self {
+            Self::NotAllowed(m) | Self::NotFound(m) | Self::Port(m) | Self::Internal(m) => m,
+        }
+    }
+
+    /// 错误码（审计与 UI 分类用）。
+    #[must_use]
+    pub fn code(&self) -> &'static str {
+        match self {
+            Self::NotAllowed(_) => "not_allowed",
+            Self::NotFound(_) => "not_found",
+            Self::Port(_) => "port_error",
+            Self::Internal(_) => "internal",
+        }
+    }
+}
+
+impl fmt::Display for ToolError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(self.message())
+    }
+}
+
+impl std::error::Error for ToolError {}
+
+/// 工具处理函数。
+pub type ToolFn = Arc<dyn Fn(&ToolCtx, &Value) -> Result<ToolOutput, ToolError> + Send + Sync>;
+
+/// 一个工具的完整定义 + 实现。
+#[derive(Clone)]
+pub struct ToolSpec {
+    /// 工具名（`snake_case`，同时是 MCP 侧的工具名）。
+    pub name: &'static str,
+    /// 说明。
+    pub description: &'static str,
+    /// 参数 schema（根必须 object）。
+    pub input_schema: Value,
+    /// 副作用等级。
+    pub access: Access,
+    /// 实现。
+    pub handler: ToolFn,
+}
+
+impl fmt::Debug for ToolSpec {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("ToolSpec")
+            .field("name", &self.name)
+            .field("access", &self.access)
+            .finish_non_exhaustive()
+    }
+}
+
+impl ToolSpec {
+    /// 建一个只读工具。
+    #[must_use]
+    pub fn read_only(
+        name: &'static str,
+        description: &'static str,
+        input_schema: Value,
+        handler: ToolFn,
+    ) -> Self {
+        Self {
+            name,
+            description,
+            input_schema,
+            access: Access::ReadOnly,
+            handler,
+        }
+    }
+
+    /// 建一个会改数据的工具。
+    #[must_use]
+    pub fn mutating(
+        name: &'static str,
+        description: &'static str,
+        input_schema: Value,
+        handler: ToolFn,
+    ) -> Self {
+        Self {
+            name,
+            description,
+            input_schema,
+            access: Access::Mutating,
+            handler,
+        }
+    }
+
+    /// 投影成两侧共用的 `(name, description, schema)`。
+    #[must_use]
+    pub fn definition(&self) -> ToolDefinition {
+        ToolDefinition {
+            name: self.name.to_string(),
+            description: self.description.to_string(),
+            input_schema: self.input_schema.clone(),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::registry::schema::{non_empty_string, object};
+    use serde_json::json;
+
+    fn echo_handler() -> ToolFn {
+        Arc::new(|_ctx: &ToolCtx, args: &Value| Ok(ToolOutput::ok(args.clone(), "echo")))
+    }
+
+    #[test]
+    fn definition_is_a_pure_projection() {
+        let spec = ToolSpec::read_only(
+            "echo",
+            "回显",
+            object(&[("text", non_empty_string("文本"))], &["text"]),
+            echo_handler(),
+        );
+        let def = spec.definition();
+        assert_eq!(def.name, "echo");
+        assert_eq!(def.description, "回显");
+        assert_eq!(def.input_schema, spec.input_schema);
+        assert_eq!(spec.access, Access::ReadOnly);
+    }
+
+    #[test]
+    fn confirmation_carries_details() {
+        let out = ToolOutput::needs_confirmation(
+            "AI 请求修改 x",
+            json!({ "path": "x" }),
+            Sensitivity::High,
+        );
+        assert_eq!(out.content["status"], json!("needs_confirmation"));
+        let confirmation = out.confirmation.expect("必须有待确认详情");
+        assert_eq!(confirmation.sensitivity, Sensitivity::High);
+        assert_eq!(confirmation.summary, out.summary);
+        assert_eq!(confirmation.details, json!({ "path": "x" }));
+    }
+}

crates/agent/src/registry/validate.rs

@@ -0,0 +1,332 @@
+//! 参数校验：JSON Schema 2020-12 的**最小子集**实现。
+//!
+//! 为什么不引 `jsonschema` crate：agent 的 schema 全是自己手写的（[`super::schema`]），
+//! 用到的关键字只有 `type/required/properties/additionalProperties/enum/minimum/maximum/
+//! minLength/minItems/maxItems/uniqueItems/items`。三百行的校验器换掉一棵依赖树，
+//! 对 Win7 单文件形态（D12）值得。
+//!
+//! 校验失败的文案是给**模型**看的（它会据此改正参数重试），所以要具体：
+//! 「参数 `limit` 必须是 1~500 的整数，实际是 2000」，不是 `schema validation failed`。
+
+use serde_json::Value;
+
+/// 校验入口。返回全部错误（一次给全，省模型来回试错）。
+///
+/// # Errors
+/// 参数不符合 schema 时返回人类可读的错误列表。
+pub fn validate(schema: &Value, args: &Value) -> Result<(), Vec<String>> {
+    let mut errors = Vec::new();
+    validate_at(schema, args, "", &mut errors);
+    if errors.is_empty() {
+        Ok(())
+    } else {
+        Err(errors)
+    }
+}
+
+/// 只取第一条错误（日志/审计摘要用）。
+#[must_use]
+pub fn first_error(schema: &Value, args: &Value) -> Option<String> {
+    validate(schema, args)
+        .err()
+        .and_then(|errors| errors.into_iter().next())
+}
+
+fn validate_at(schema: &Value, value: &Value, path: &str, errors: &mut Vec<String>) {
+    let Some(schema) = schema.as_object() else {
+        return; // `{}` = 任意值
+    };
+
+    if let Some(expected) = schema.get("type").and_then(Value::as_str) {
+        if !type_matches(expected, value) {
+            errors.push(format!(
+                "参数 {} 应为 {}，实际是 {}",
+                label(path),
+                expected,
+                type_name(value)
+            ));
+            return; // 类型都不对，后面的范围检查没有意义
+        }
+    }
+
+    if let Some(allowed) = schema.get("enum").and_then(Value::as_array) {
+        if !allowed.iter().any(|v| v == value) {
+            let list: Vec<String> = allowed.iter().map(render).collect();
+            errors.push(format!(
+                "参数 {} 只能取 [{}]，实际是 {}",
+                label(path),
+                list.join(", "),
+                render(value)
+            ));
+        }
+    }
+
+    check_bounds(schema, value, path, errors);
+
+    match value {
+        Value::Object(map) => {
+            let required = schema.get("required").and_then(Value::as_array);
+            for name in required.into_iter().flatten().filter_map(Value::as_str) {
+                if !map.contains_key(name) {
+                    errors.push(format!("缺少必填参数 {}", label(&join(path, name))));
+                }
+            }
+            let properties = schema.get("properties").and_then(Value::as_object);
+            for (key, entry) in map {
+                match properties.and_then(|p| p.get(key)) {
+                    Some(sub) => validate_at(sub, entry, &join(path, key), errors),
+                    None => {
+                        if schema.get("additionalProperties").and_then(Value::as_bool)
+                            == Some(false)
+                        {
+                            let known: Vec<&str> = properties
+                                .map(|p| p.keys().map(String::as_str).collect())
+                                .unwrap_or_default();
+                            errors.push(format!(
+                                "参数 {} 不是可接受的参数名（可用：{}）",
+                                label(&join(path, key)),
+                                if known.is_empty() {
+                                    "无".to_string()
+                                } else {
+                                    known.join(", ")
+                                }
+                            ));
+                        }
+                    }
+                }
+            }
+        }
+        Value::Array(items) => {
+            if let Some(sub) = schema.get("items") {
+                for (i, item) in items.iter().enumerate() {
+                    validate_at(sub, item, &format!("{path}[{i}]"), errors);
+                }
+            }
+        }
+        _ => {}
+    }
+}
+
+fn check_bounds(
+    schema: &serde_json::Map<String, Value>,
+    value: &Value,
+    path: &str,
+    errors: &mut Vec<String>,
+) {
+    let number = value.as_f64();
+    let minimum = schema.get("minimum").and_then(Value::as_f64);
+    let maximum = schema.get("maximum").and_then(Value::as_f64);
+    if let (Some(n), Some(min), Some(max)) = (number, minimum, maximum) {
+        if n < min || n > max {
+            errors.push(format!(
+                "参数 {} 必须在 {}~{} 之间，实际是 {}",
+                label(path),
+                render_number(min),
+                render_number(max),
+                render_number(n)
+            ));
+            return;
+        }
+    } else if let (Some(n), Some(min)) = (number, minimum) {
+        if n < min {
+            errors.push(format!(
+                "参数 {} 不能小于 {}，实际是 {}",
+                label(path),
+                render_number(min),
+                render_number(n)
+            ));
+        }
+    } else if let (Some(n), Some(max)) = (number, maximum) {
+        if n > max {
+            errors.push(format!(
+                "参数 {} 不能大于 {}，实际是 {}",
+                label(path),
+                render_number(max),
+                render_number(n)
+            ));
+        }
+    }
+
+    if let Some(text) = value.as_str() {
+        if let Some(min_len) = schema.get("minLength").and_then(Value::as_u64) {
+            if (text.chars().count() as u64) < min_len {
+                errors.push(format!(
+                    "参数 {} 不能为空（最少 {} 个字符）",
+                    label(path),
+                    min_len
+                ));
+            }
+        }
+    }
+
+    if let Some(items) = value.as_array() {
+        if let Some(max_items) = schema.get("maxItems").and_then(Value::as_u64) {
+            if items.len() as u64 > max_items {
+                errors.push(format!(
+                    "参数 {} 最多 {} 项，实际 {} 项",
+                    label(path),
+                    max_items,
+                    items.len()
+                ));
+            }
+        }
+        if let Some(min_items) = schema.get("minItems").and_then(Value::as_u64) {
+            if (items.len() as u64) < min_items {
+                errors.push(format!(
+                    "参数 {} 至少 {} 项，实际 {} 项",
+                    label(path),
+                    min_items,
+                    items.len()
+                ));
+            }
+        }
+        if schema.get("uniqueItems").and_then(Value::as_bool) == Some(true) {
+            if let Some(duplicate) = first_duplicate(items) {
+                errors.push(format!(
+                    "参数 {} 不能有重复项（{} 出现了多次）",
+                    label(path),
+                    render(duplicate)
+                ));
+            }
+        }
+    }
+}
+
+/// 数组里第一个重复出现的元素（`uniqueItems` 用；`null` 也算一个值）。
+fn first_duplicate(items: &[Value]) -> Option<&Value> {
+    items
+        .iter()
+        .enumerate()
+        .find(|(index, item)| items.iter().take(*index).any(|prev| prev == *item))
+        .map(|(_, item)| item)
+}
+
+fn type_matches(expected: &str, value: &Value) -> bool {
+    match expected {
+        "object" => value.is_object(),
+        "array" => value.is_array(),
+        "string" => value.is_string(),
+        "boolean" => value.is_boolean(),
+        "null" => value.is_null(),
+        "integer" => value.as_f64().is_some_and(|n| n.fract() == 0.0),
+        "number" => value.is_number(),
+        _ => true, // 未知关键字不拦（前向兼容）
+    }
+}
+
+fn type_name(value: &Value) -> &'static str {
+    match value {
+        Value::Null => "null",
+        Value::Bool(_) => "boolean",
+        Value::Number(n) if n.as_f64().is_some_and(|f| f.fract() == 0.0) => "integer",
+        Value::Number(_) => "number",
+        Value::String(_) => "string",
+        Value::Array(_) => "array",
+        Value::Object(_) => "object",
+    }
+}
+
+fn label(path: &str) -> String {
+    if path.is_empty() {
+        "（根）".to_string()
+    } else {
+        format!("`{path}`")
+    }
+}
+
+fn join(path: &str, key: &str) -> String {
+    if path.is_empty() {
+        key.to_string()
+    } else {
+        format!("{path}.{key}")
+    }
+}
+
+fn render(value: &Value) -> String {
+    match value {
+        Value::String(s) => format!("\"{s}\""),
+        other => other.to_string(),
+    }
+}
+
+fn render_number(n: f64) -> String {
+    if n.fract() == 0.0 {
+        format!("{}", n as i64)
+    } else {
+        n.to_string()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::registry::schema::{
+        enum_string_array, integer, non_empty_string, object, string_array, string_enum,
+    };
+    use serde_json::json;
+
+    fn errors(schema: &Value, args: &Value) -> Vec<String> {
+        validate(schema, args).unwrap_err()
+    }
+
+    #[test]
+    fn accepts_valid_and_reports_missing_required() {
+        let schema = object(
+            &[("session_id", non_empty_string("会话 id"))],
+            &["session_id"],
+        );
+        assert!(validate(&schema, &json!({ "session_id": "20261029T124501-9f3c2a" })).is_ok());
+        let errs = errors(&schema, &json!({}));
+        assert_eq!(errs.len(), 1);
+        assert!(errs[0].contains("缺少必填参数 `session_id`"), "{errs:?}");
+    }
+
+    #[test]
+    fn rejects_empty_string_and_wrong_type() {
+        let schema = object(
+            &[("session_id", non_empty_string("会话 id"))],
+            &["session_id"],
+        );
+        assert!(errors(&schema, &json!({ "session_id": "" }))[0].contains("不能为空"));
+        assert!(errors(&schema, &json!({ "session_id": 1 }))[0].contains("应为 string"));
+    }
+
+    #[test]
+    fn rejects_out_of_range_and_unknown_keys() {
+        let schema = object(
+            &[
+                ("limit", integer("条数", 1, 500)),
+                ("kinds", string_array("类型", 8)),
+            ],
+            &[],
+        );
+        let errs = errors(&schema, &json!({ "limit": 2000 }));
+        assert!(errs[0].contains("1~500"), "{errs:?}");
+        let errs = errors(&schema, &json!({ "limit": 1, "evil": true }));
+        assert!(errs[0].contains("不是可接受的参数名"), "{errs:?}");
+    }
+
+    #[test]
+    fn checks_enum_and_nested_objects() {
+        let schema = object(&[("level", string_enum(&["error", "warn"], "级别"))], &[]);
+        assert!(validate(&schema, &json!({ "level": "error" })).is_ok());
+        assert!(errors(&schema, &json!({ "level": "fatal" }))[0].contains("只能取"));
+    }
+
+    #[test]
+    fn rejects_duplicate_items_when_unique() {
+        let schema = object(
+            &[("kinds", enum_string_array(&["stderr", "exit"], "类型", 4))],
+            &[],
+        );
+        let errs = errors(&schema, &json!({ "kinds": ["stderr", "exit", "stderr"] }));
+        assert!(errs[0].contains("不能有重复项"), "{errs:?}");
+        assert!(validate(&schema, &json!({ "kinds": ["stderr", "exit"] })).is_ok());
+    }
+
+    #[test]
+    fn integer_type_rejects_fraction() {
+        assert!(validate(&json!({ "type": "integer" }), &json!(1.5)).is_err());
+        assert!(validate(&json!({ "type": "integer" }), &json!(2.0)).is_ok());
+    }
+}

crates/agent/src/testing.rs

@@ -0,0 +1,190 @@
+//! 测试替身：五个端口的 **mock 实现**（无盘、无网络、无时间依赖）。
+//!
+//! 放在库内（而不是只在 `#[cfg(test)]`）是刻意的：`crates/app` 装配时也要能给
+//! 自己的单测造一套「无盘」环境，且 P1/M39 的 MCP 契约测试要复用同一批假数据。
+//!
+//! 按端口拆文件（`port.rs` 挨 400 行上限的同款理由）：`settings` 配置、`sessions`
+//! 会话日志在下面，`game` 实例/Java/账户与 `diagnose` 诊断各一个子模块。
+//! 对外名字不变，`unlucky_agent::testing::MockSettings` 之类照旧可用（走 re-export）。
+
+pub mod diagnose;
+pub mod game;
+pub mod settings;
+
+use std::collections::{BTreeMap, BTreeSet};
+
+use serde_json::{json, Value};
+
+use crate::port::{GameSessionPort, GameSessionSummary, LogEvent, LogPage, LogQuery, PortResult};
+
+pub use diagnose::MockDiagnose;
+pub use game::{MockAccounts, MockGame};
+pub use settings::MockSettings;
+
+/// 内存会话端口。
+#[derive(Debug, Default)]
+pub struct MockSessions {
+    sessions: Vec<GameSessionSummary>,
+    events: BTreeMap<String, Vec<LogEvent>>,
+}
+
+impl MockSessions {
+    /// 空数据。
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// 加一个会话及其事件流。
+    pub fn add(&mut self, summary: GameSessionSummary, events: Vec<LogEvent>) {
+        self.events.insert(summary.session_id.clone(), events);
+        self.sessions.push(summary);
+    }
+
+    /// 便捷：造一个崩溃会话（`exit_code=1` + stderr + crash_found）。
+    #[must_use]
+    pub fn crashing_session(session_id: &str) -> (GameSessionSummary, Vec<LogEvent>) {
+        let summary = GameSessionSummary {
+            session_id: session_id.to_string(),
+            instance_id: Some("inst-1".to_string()),
+            instance_name: Some("1.20.1 Forge".to_string()),
+            game_version: Some("1.20.1".to_string()),
+            started_at: Some("2026-10-29T12:45:01.123Z".to_string()),
+            ended_at: Some("2026-10-29T12:46:31.123Z".to_string()),
+            duration_ms: 90_000,
+            exit_code: Some(1),
+            exit_type: Some("application_error".to_string()),
+            silent_failure: false,
+            window_detected: true,
+            event_count: 5,
+            crash_found: true,
+            diagnosis_top: Some("forge_missing_library".to_string()),
+        };
+        let events = vec![
+            event(
+                0,
+                "stdout",
+                json!({ "line": "Starting Minecraft 1.20.1", "level": "info" }),
+            ),
+            event(
+                1,
+                "stderr",
+                json!({ "line": "java.lang.NoClassDefFoundError: cpw/mods/bootstraplauncher/BootstrapLauncher", "level": "error" }),
+            ),
+            event(
+                2,
+                "crash_found",
+                json!({ "source": "crash_report", "path": r"C:\Users\aska\.minecraft\crash-reports\crash-1.txt", "excerpt": "Description: Mod loading failure" }),
+            ),
+            event(
+                3,
+                "exit",
+                json!({ "code": 1, "exit_type": "application_error", "silent_failure": false }),
+            ),
+            event(
+                4,
+                "session_end",
+                json!({ "reason": "exit", "duration_ms": 90000 }),
+            ),
+        ];
+        (summary, events)
+    }
+}
+
+fn event(seq: u64, kind: &str, payload: Value) -> LogEvent {
+    LogEvent {
+        seq,
+        ts: format!("2026-10-29T12:45:0{seq}.000Z"),
+        t_ms: seq * 1_000,
+        kind: kind.to_string(),
+        payload,
+    }
+}
+
+impl GameSessionPort for MockSessions {
+    fn list_sessions(
+        &self,
+        limit: usize,
+        instance_id: Option<&str>,
+    ) -> PortResult<Vec<GameSessionSummary>> {
+        let mut out: Vec<GameSessionSummary> = self
+            .sessions
+            .iter()
+            .filter(|s| instance_id.is_none_or(|id| s.instance_id.as_deref() == Some(id)))
+            .cloned()
+            .collect();
+        out.sort_by(|a, b| b.started_at.cmp(&a.started_at));
+        out.truncate(limit);
+        Ok(out)
+    }
+
+    fn read_log(&self, session_id: &str, query: &LogQuery) -> PortResult<LogPage> {
+        let events = self
+            .events
+            .get(session_id)
+            .ok_or_else(|| format!("会话 `{session_id}` 不存在"))?;
+        let mut kind_counts = BTreeMap::new();
+        for event in events {
+            *kind_counts.entry(event.kind.clone()).or_insert(0u64) += 1;
+        }
+        let matched: Vec<&LogEvent> = events
+            .iter()
+            .filter(|e| query.from_seq.is_none_or(|from| e.seq >= from))
+            .filter(|e| query.to_seq.is_none_or(|to| e.seq <= to))
+            .filter(|e| query.kinds.is_empty() || query.kinds.contains(&e.kind))
+            .collect();
+        let max = if query.max_events == 0 {
+            matched.len()
+        } else {
+            query.max_events
+        };
+        let truncated = matched.len() > max;
+        Ok(LogPage {
+            session_id: session_id.to_string(),
+            total_events: events.len() as u64,
+            matched_events: matched.len() as u64,
+            truncated,
+            kind_counts,
+            first_ts: events.first().map(|e| e.ts.clone()),
+            last_ts: events.last().map(|e| e.ts.clone()),
+            events: matched.into_iter().take(max).cloned().collect(),
+        })
+    }
+}
+
+/// 一次性造好全部端口的 [`crate::port::Ports`]（含一个崩溃会话，够跑通对话与日志工具）。
+#[must_use]
+pub fn mock_ports() -> (crate::port::Ports, std::sync::Arc<MockSettings>) {
+    use std::sync::Arc;
+    let settings = Arc::new(MockSettings::new());
+    let (summary, events) = MockSessions::crashing_session("20261029T124501-9f3c2a");
+    let mut sessions = MockSessions::new();
+    sessions.add(summary, events);
+    let ports = crate::port::Ports {
+        setting: settings.clone(),
+        sessions: Arc::new(sessions),
+        diagnose: Arc::new(MockDiagnose::new()),
+        game: Arc::new(MockGame::new()),
+        accounts: Arc::new(MockAccounts::new()),
+    };
+    (ports, settings)
+}
+
+/// 测试里常用的「全部工具名」集合（契约测试与 MCP 投影比对用）。
+#[must_use]
+pub fn expected_v1_tool_names() -> BTreeSet<&'static str> {
+    [
+        "get_config",
+        "get_config_schema",
+        "set_config",
+        "list_game_sessions",
+        "read_game_log",
+        "diagnose_crash",
+        "list_instances",
+        "list_versions",
+        "get_java_status",
+        "list_accounts",
+    ]
+    .into_iter()
+    .collect()
+}

crates/agent/src/testing/diagnose.rs

@@ -0,0 +1,87 @@
+//! 内存诊断端口（`DiagnosePort` 的测试替身）。
+
+use crate::port::{
+    CrashDiagnosis, DiagnosePort, DiagnosisCandidate, ExitSummary, FixAction, FixActionKind,
+    PortResult,
+};
+
+/// 内存诊断端口（固定返回一份规则结论）。
+#[derive(Debug, Clone)]
+pub struct MockDiagnose {
+    report: Option<CrashDiagnosis>,
+}
+
+impl Default for MockDiagnose {
+    fn default() -> Self {
+        Self {
+            report: Some(Self::forge_missing_library()),
+        }
+    }
+}
+
+impl MockDiagnose {
+    /// 构造使用默认结论的端口。
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// 让端口对所有会话返回「会话不存在」。
+    #[must_use]
+    pub fn unavailable() -> Self {
+        Self { report: None }
+    }
+
+    /// 默认结论：Forge 缺库（对应 analyse/02 的高发场景）。
+    #[must_use]
+    pub fn forge_missing_library() -> CrashDiagnosis {
+        CrashDiagnosis {
+            session_id: String::new(),
+            source: "rules".to_string(),
+            needs_more_info: false,
+            candidates: vec![DiagnosisCandidate {
+                id: "integrity.forge_missing_library".to_string(),
+                severity: "error".to_string(),
+                category: "integrity".to_string(),
+                confidence: 0.86,
+                message_key: "diagnose.cause.integrity.forge_missing_library".to_string(),
+                message: "Forge 启动缺少 bootstraplauncher 库，通常是版本组件未下载完整"
+                    .to_string(),
+                detail: "在实例上重装 Forge 组件（或先用官方启动器补全一次再回来）".to_string(),
+                evidence: vec![
+                    "java.lang.NoClassDefFoundError: cpw/mods/bootstraplauncher/BootstrapLauncher"
+                        .to_string(),
+                ],
+                fix_actions: vec![FixAction {
+                    kind: FixActionKind::Reinstall,
+                    tool: "component.reinstall".to_string(),
+                    label: "重装该版本的 Forge 组件".to_string(),
+                    args: [("component".to_string(), "forge".to_string())]
+                        .into_iter()
+                        .collect(),
+                }],
+            }],
+            secondary: Vec::new(),
+            evidence: vec!["Description: Mod loading failure".to_string()],
+            exit: ExitSummary {
+                code: Some(1),
+                exit_type: Some("application_error".to_string()),
+                silent_failure: false,
+            },
+        }
+    }
+}
+
+impl DiagnosePort for MockDiagnose {
+    fn diagnose(&self, session_id: &str) -> PortResult<CrashDiagnosis> {
+        self.report.clone().map_or_else(
+            || Err(format!("会话 `{session_id}` 不存在")),
+            |report| {
+                Ok(CrashDiagnosis {
+                    session_id: session_id.to_string(),
+                    ..report
+                })
+            },
+        )
+    }
+}

crates/agent/src/testing/game.rs

@@ -0,0 +1,158 @@
+//! 实例 / 版本 / Java / 账户四个只读端口的测试替身。
+
+use crate::port::game::{
+    AccountPort, AccountSummary, GamePort, InstanceSummary, JavaRuntimeSummary, JavaStatus,
+    VersionSummary,
+};
+use crate::port::PortResult;
+
+/// 内存游戏端口：一个 1.20.1 Forge 实例 + 两个已安装版本 + 两个 Java 候选。
+#[derive(Debug, Clone)]
+pub struct MockGame {
+    instances: Vec<InstanceSummary>,
+    versions: Vec<VersionSummary>,
+    java: JavaStatus,
+    fail: Option<String>,
+}
+
+impl Default for MockGame {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl MockGame {
+    /// 默认假数据（够跑通 `list_instances` / `list_versions` / `get_java_status`）。
+    #[must_use]
+    pub fn new() -> Self {
+        Self {
+            instances: vec![InstanceSummary {
+                id: "inst-1".to_string(),
+                name: "1.20.1 Forge".to_string(),
+                version_id: "1.20.1-forge-47.2.20".to_string(),
+                version_present: true,
+                game_dir: None,
+                java_path: Some(r"D:\jdk17\bin\java.exe".to_string()),
+                last_played_at: Some(1_793_304_753_123),
+            }],
+            versions: vec![
+                VersionSummary {
+                    id: "1.20.1-forge-47.2.20".to_string(),
+                    kind: Some("release".to_string()),
+                    instance_count: 1,
+                },
+                VersionSummary {
+                    id: "1.21.1".to_string(),
+                    kind: Some("release".to_string()),
+                    instance_count: 0,
+                },
+            ],
+            java: JavaStatus {
+                default_memory_mb: Some(2048),
+                managed_roots: vec![r"D:\ULL\.ULL\data\java-managed".to_string()],
+                candidates: vec![
+                    JavaRuntimeSummary {
+                        binary: r"D:\ULL\.ULL\data\java-managed\jdk-17-temurin\bin\java.exe"
+                            .to_string(),
+                        version: Some("17.0.13".to_string()),
+                        major: Some(17),
+                        vendor: Some("temurin".to_string()),
+                        origin: "managed".to_string(),
+                    },
+                    JavaRuntimeSummary {
+                        binary: "/usr/bin/java".to_string(),
+                        version: Some("21.0.2".to_string()),
+                        major: Some(21),
+                        vendor: None,
+                        origin: "PATH".to_string(),
+                    },
+                ],
+            },
+            fail: None,
+        }
+    }
+
+    /// 让三个查询全部返回同一个错误（测端口错误透传）。
+    #[must_use]
+    pub fn failing(message: &str) -> Self {
+        Self {
+            fail: Some(message.to_string()),
+            ..Self::new()
+        }
+    }
+
+    fn fail(&self) -> Option<String> {
+        self.fail.clone()
+    }
+}
+
+impl GamePort for MockGame {
+    fn list_instances(&self) -> PortResult<Vec<InstanceSummary>> {
+        self.fail().map_or_else(|| Ok(self.instances.clone()), Err)
+    }
+
+    fn list_versions(&self) -> PortResult<Vec<VersionSummary>> {
+        self.fail().map_or_else(|| Ok(self.versions.clone()), Err)
+    }
+
+    fn java_status(&self) -> PortResult<JavaStatus> {
+        self.fail().map_or_else(|| Ok(self.java.clone()), Err)
+    }
+}
+
+/// 内存账户端口：一个离线账户。**只有公开字段**，凭据无处可放。
+#[derive(Debug, Clone)]
+pub struct MockAccounts {
+    accounts: Vec<AccountSummary>,
+    fail: Option<String>,
+}
+
+impl Default for MockAccounts {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl MockAccounts {
+    /// 一个离线账户（Steve）。
+    #[must_use]
+    pub fn new() -> Self {
+        Self {
+            accounts: vec![AccountSummary {
+                id: "acc-1".to_string(),
+                kind: "offline".to_string(),
+                profile_id: "8667ba71b85a4004af54457a9734eed7".to_string(),
+                profile_name: "Steve".to_string(),
+                login_name: None,
+                created_at_ms: 1_793_304_753_123,
+            }],
+            fail: None,
+        }
+    }
+
+    /// 空账户列表（测「没有账户」的提示文案）。
+    #[must_use]
+    pub fn empty() -> Self {
+        Self {
+            accounts: Vec::new(),
+            fail: None,
+        }
+    }
+
+    /// 让查询失败（测端口错误透传）。
+    #[must_use]
+    pub fn failing(message: &str) -> Self {
+        Self {
+            fail: Some(message.to_string()),
+            ..Self::new()
+        }
+    }
+}
+
+impl AccountPort for MockAccounts {
+    fn list_accounts(&self) -> PortResult<Vec<AccountSummary>> {
+        self.fail
+            .clone()
+            .map_or_else(|| Ok(self.accounts.clone()), Err)
+    }
+}

crates/agent/src/testing/settings.rs

@@ -0,0 +1,201 @@
+//! 内存配置端口（`SettingPort` 的测试替身）。
+
+use std::collections::BTreeMap;
+use std::sync::Mutex;
+
+use serde_json::{json, Map, Value};
+
+use crate::confirm::Sensitivity;
+use crate::port::{PortResult, SettingChange, SettingKey, SettingPort};
+
+/// 内存配置端口。
+#[derive(Debug, Default)]
+pub struct MockSettings {
+    keys: Vec<SettingKey>,
+    values: Mutex<BTreeMap<String, Value>>,
+    fail_set: Mutex<Option<String>>,
+    set_calls: Mutex<usize>,
+}
+
+/// 与 `PlanDoc/04` §3 / M12 `setting-接口约定.md` §8 的键表一致的默认白名单
+/// （覆盖三档敏感度；`ai.api_key` 这类凭据是 `writable=false`，**故意不在这里**）。
+fn default_keys() -> Vec<SettingKey> {
+    fn key(
+        path: &str,
+        sensitivity: Sensitivity,
+        value_type: &str,
+        description: &str,
+    ) -> SettingKey {
+        SettingKey {
+            path: path.to_string(),
+            sensitivity,
+            value_type: value_type.to_string(),
+            description: description.to_string(),
+        }
+    }
+    vec![
+        key(
+            "appearance.theme_mode",
+            Sensitivity::Low,
+            "enum",
+            "界面主题",
+        ),
+        key(
+            "download.concurrency",
+            Sensitivity::Low,
+            "integer",
+            "下载并发（1~256）",
+        ),
+        key(
+            "java.default_memory_mb",
+            Sensitivity::Low,
+            "integer",
+            "最大内存（512~65536 MB）",
+        ),
+        key("download.region", Sensitivity::Medium, "enum", "下载源区域"),
+        key("ai.model", Sensitivity::Medium, "text", "AI 模型名"),
+        key(
+            "java.selected_path",
+            Sensitivity::High,
+            "path",
+            "Java 可执行文件路径",
+        ),
+        key("download.proxy_url", Sensitivity::High, "text", "HTTP 代理"),
+        key("ai.base_url", Sensitivity::High, "text", "AI 端点"),
+        key(
+            "core.data_mode",
+            Sensitivity::High,
+            "enum",
+            "数据目录模式（portable/standard/custom）",
+        ),
+    ]
+}
+
+impl MockSettings {
+    /// 用默认白名单 + 一批初值造一个。
+    #[must_use]
+    pub fn new() -> Self {
+        let mut values = BTreeMap::new();
+        values.insert("appearance.theme_mode".to_string(), json!("metro_dark"));
+        values.insert("download.concurrency".to_string(), json!(8));
+        values.insert("java.default_memory_mb".to_string(), json!(2048));
+        Self {
+            keys: default_keys(),
+            values: Mutex::new(values),
+            fail_set: Mutex::new(None),
+            set_calls: Mutex::new(0),
+        }
+    }
+
+    /// 让接下来的 `set` 全部失败（测错误透传）。
+    pub fn fail_set_with(&self, message: &str) {
+        if let Ok(mut slot) = self.fail_set.lock() {
+            *slot = Some(message.to_string());
+        }
+    }
+
+    /// 当前值（断言「未确认时没有写进去」）。
+    #[must_use]
+    pub fn value_of(&self, path: &str) -> Option<Value> {
+        self.values.lock().ok().and_then(|v| v.get(path).cloned())
+    }
+
+    /// 直接塞一个值，模拟 M12 真实实现里存在的**任意键**（含凭据键）。
+    ///
+    /// 白名单以外的键也能塞——测「`get_config` 不把凭据读给模型」需要它
+    /// （`ai.api_key` 是 `writable=false`，故意不在白名单里）。
+    pub fn seed_value(&self, path: &str, value: Value) {
+        if let Ok(mut values) = self.values.lock() {
+            values.insert(path.to_string(), value);
+        }
+    }
+
+    /// 成功写入次数。
+    #[must_use]
+    pub fn set_calls(&self) -> usize {
+        self.set_calls.lock().map(|n| *n).unwrap_or(0)
+    }
+}
+
+impl SettingPort for MockSettings {
+    fn summary(&self) -> Value {
+        let values = self.values.lock().map(|v| v.clone()).unwrap_or_default();
+        let mut map = serde_json::Map::new();
+        for key in &self.keys {
+            let value = values.get(&key.path).cloned().unwrap_or(Value::Null);
+            map.insert(key.path.clone(), value);
+        }
+        Value::Object(map)
+    }
+
+    fn get(&self, path: &str) -> PortResult<Value> {
+        self.values
+            .lock()
+            .ok()
+            .and_then(|v| v.get(path).cloned())
+            .ok_or_else(|| format!("配置键 `{path}` 没有值"))
+    }
+
+    fn set(&self, path: &str, value: &Value) -> PortResult<SettingChange> {
+        if let Ok(slot) = self.fail_set.lock() {
+            if let Some(message) = slot.as_ref() {
+                return Err(message.clone());
+            }
+        }
+        let old = self.get(path).ok();
+        if let Ok(mut values) = self.values.lock() {
+            values.insert(path.to_string(), value.clone());
+        }
+        if let Ok(mut calls) = self.set_calls.lock() {
+            *calls += 1;
+        }
+        Ok(SettingChange {
+            path: path.to_string(),
+            old,
+            new: value.clone(),
+        })
+    }
+
+    fn writable_keys(&self) -> Vec<SettingKey> {
+        self.keys.clone()
+    }
+
+    fn schema(&self) -> Value {
+        // 与 `core::setting::catalog::SettingSchema::to_json_schema` 同形：
+        // 只含白名单键 + `x-ai-sensitivity`，凭据键天然缺席。
+        let mut properties = Map::new();
+        for key in &self.keys {
+            properties.insert(
+                key.path.clone(),
+                json!({
+                    "type": key.value_type,
+                    "description": key.description,
+                    "x-ai-sensitivity": key.sensitivity,
+                }),
+            );
+        }
+        json!({
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "title": "ull.launcher",
+            "type": "object",
+            "additionalProperties": false,
+            "properties": properties,
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn schema_excludes_credential_keys() {
+        let schema = MockSettings::new().schema();
+        let json = schema.to_string();
+        assert!(
+            !json.contains("ai.api_key"),
+            "schema 不得包含凭据键：{json}"
+        );
+        assert!(json.contains("download.concurrency"));
+    }
+}

crates/agent/src/tools/accounts.rs

@@ -0,0 +1,110 @@
+//! `list_accounts`：账户清单（**凭据永不出口**）。
+//!
+//! 这个工具存在的理由很具体：用户常问「我有哪几个号 / 这局用的是哪个号」。
+//! 但 D4/D9 的凭据红线是硬的——工具结果会回灌模型、也可能被发往远端 LLM，
+//! 所以：
+//! 1. 端口只回 [`crate::port::AccountSummary`]（`AccountMeta` 的公开字段）；
+//! 2. 本文件里**没有任何**能表达 token / 密码的类型（连字段名都不出现）；
+//! 3. 工具结果再过一遍 [`crate::redact`]，兜住实现方把凭据塞进 `profile_name` 的意外。
+
+use std::sync::Arc;
+
+use serde_json::{json, Value};
+
+use crate::port::AccountPort;
+use crate::registry::schema::object;
+use crate::registry::{
+    RegistryError, ToolCtx, ToolError, ToolFn, ToolOutput, ToolRegistry, ToolSpec,
+};
+
+/// 工具名。
+pub const LIST_ACCOUNTS: &str = "list_accounts";
+
+/// 注册 `list_accounts`。
+///
+/// # Errors
+/// 工具名重复/schema 非法时返回 [`RegistryError`]。
+pub fn register(
+    registry: &mut ToolRegistry,
+    port: Arc<dyn AccountPort>,
+) -> Result<(), RegistryError> {
+    let handler: ToolFn = Arc::new(move |_ctx: &ToolCtx, _args: &Value| {
+        let accounts = port.list_accounts().map_err(ToolError::Port)?;
+        let count = accounts.len();
+        let display: Vec<String> = accounts
+            .iter()
+            .map(|a| {
+                if a.profile_name.trim().is_empty() {
+                    format!("{}（{}）", a.id, a.kind)
+                } else {
+                    format!("{}（{}）", a.profile_name, a.kind)
+                }
+            })
+            .collect();
+        let mut content = json!({
+            "count": count,
+            "accounts": accounts,
+            "credential_policy": "账户凭据（access token / 刷新令牌 / authlib 密码）永不经由 AI 工具出口",
+        });
+        // 兜底脱敏：端口实现若把敏感串塞进了公开字段，这里也不会带出去。
+        content = crate::redact::redact_texts(&content);
+        Ok(ToolOutput::ok(
+            content,
+            if count == 0 {
+                "还没有任何账户".to_string()
+            } else {
+                format!("账户 {count} 个：{}", display.join("、"))
+            },
+        ))
+    });
+
+    registry.register(ToolSpec::read_only(
+        LIST_ACCOUNTS,
+        "列出启动器里已登录的账户（展示名 / 轨道 offline|microsoft|authlib / 档案 UUID / 创建时间）。**永不返回任何凭据**：令牌与密码不在工具结果的类型里，需要登录态请让用户在启动器界面查看。",
+        object(&[], &[]),
+        handler,
+    ))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::testing::MockAccounts;
+
+    fn registry(port: Arc<dyn AccountPort>) -> ToolRegistry {
+        let mut registry = ToolRegistry::new();
+        register(&mut registry, port).expect("注册应成功");
+        registry
+    }
+
+    fn call(registry: &ToolRegistry) -> Value {
+        let spec = registry.get(LIST_ACCOUNTS).expect("工具存在").clone();
+        let ctx = ToolCtx {
+            agent_session_id: "s1".to_string(),
+            confirmed: false,
+        };
+        (spec.handler)(&ctx, &json!({})).expect("应成功").content
+    }
+
+    #[test]
+    fn lists_accounts_without_credentials() {
+        let content = call(&registry(Arc::new(MockAccounts::new())));
+        assert_eq!(content["count"], json!(1));
+        assert_eq!(content["accounts"][0]["profile_name"], json!("Steve"));
+        // 只扫账户数据本身：`credential_policy` 那句说明文字里本来就写着 "token"。
+        let fields = content["accounts"].to_string().to_lowercase();
+        for forbidden in ["token", "password", "refresh", "secret"] {
+            assert!(
+                !fields.contains(forbidden),
+                "账户字段含 `{forbidden}`：{fields}"
+            );
+        }
+    }
+
+    #[test]
+    fn empty_list_is_not_an_error() {
+        let content = call(&registry(Arc::new(MockAccounts::empty())));
+        assert_eq!(content["count"], json!(0));
+        assert_eq!(content["accounts"], json!([]));
+    }
+}

crates/agent/src/tools/config.rs

@@ -0,0 +1,345 @@
+//! `get_config` / `set_config`（02 文档 §3.1「有权限修改 ULL 各项配置」）。
+//!
+//! 安全边界都落在这里，但**分级确认的"要不要问"不在这里**：
+//! 工具只负责「白名单过滤 → 生成 diff → 需要确认时只报价不执行」，
+//! 问不问由编排层按 [`crate::confirm::ConfirmPolicy`] 决定（YOLO 也只改那一处）。
+//!
+//! 值校验（类型/范围/schema）归 M12 的配置 schema 所有：agent 不复制一份，
+//! 否则两处规则迟早漂移（02 文档 §3.1「schema 强校验」）。
+
+use std::sync::Arc;
+
+use serde_json::{json, Value};
+
+use crate::confirm::Sensitivity;
+use crate::port::{SettingKey, SettingPort};
+use crate::registry::schema::{any, non_empty_string, object, string};
+use crate::registry::{
+    RegistryError, ToolCtx, ToolError, ToolFn, ToolOutput, ToolRegistry, ToolSpec,
+};
+
+/// 读配置。
+pub const GET_CONFIG: &str = "get_config";
+/// 写配置。
+pub const SET_CONFIG: &str = "set_config";
+/// 错误提示里最多列多少个可写键（防"把白名单灌给模型"）。
+pub const MAX_LISTED_KEYS: usize = 16;
+/// 摘要里值的最大展示长度。
+const BRIEF_CHARS: usize = 60;
+
+/// 注册两个配置工具。
+///
+/// # Errors
+/// 工具名重复/schema 非法时返回 [`RegistryError`]。
+pub fn register(
+    registry: &mut ToolRegistry,
+    port: Arc<dyn SettingPort>,
+) -> Result<(), RegistryError> {
+    registry.register(get_config_spec(Arc::clone(&port)))?;
+    registry.register(set_config_spec(port))
+}
+
+fn get_config_spec(port: Arc<dyn SettingPort>) -> ToolSpec {
+    let handler: ToolFn = Arc::new(move |_ctx: &ToolCtx, args: &Value| {
+        let path = args
+            .get("path")
+            .and_then(Value::as_str)
+            .map(str::trim)
+            .filter(|p| !p.is_empty());
+        match path {
+            None => {
+                let summary = port.summary();
+                let writable = port.writable_keys();
+                Ok(ToolOutput::ok(
+                    json!({
+                        "scope": "all",
+                        "values": summary,
+                        "writable_keys": writable.iter().map(describe_key).collect::<Vec<_>>(),
+                    }),
+                    format!(
+                        "读取全部配置概要（{} 个键，其中 {} 个 AI 可写）",
+                        summary.as_object().map_or(0, serde_json::Map::len),
+                        writable.len()
+                    ),
+                ))
+            }
+            Some(path) => {
+                // 凭据类键一律不读：值会进 ToolOutput.content → 回灌模型 → 发往远端 LLM，
+                // 违反本 crate 的硬边界（AI 永不接触账户凭据，见 `lib.rs`）。
+                // 这是 agent 侧的第二道防线：第一道是 M12 不把凭据放白名单/概要。
+                if crate::redact::is_sensitive_key(path) {
+                    return Err(ToolError::NotAllowed(format!(
+                        "`{path}` 是凭据类配置，AI 不可读取也不可写入；请让用户自己在设置页查看。"
+                    )));
+                }
+                let value = port.get(path).map_err(ToolError::Port)?;
+                Ok(ToolOutput::ok(
+                    json!({ "scope": "key", "path": path, "value": value }),
+                    format!("读取配置 `{path}` = {}", brief(&value)),
+                ))
+            }
+        }
+    });
+
+    ToolSpec::read_only(
+        GET_CONFIG,
+        "读取启动器配置。不带 path 返回全部配置概要（含 AI 可写键及其敏感等级）；带 path 返回单个键的值。",
+        object(
+            &[(
+                "path",
+                string("配置键点分路径，如 `download.concurrency`；省略则返回全部概要"),
+            )],
+            &[],
+        ),
+        handler,
+    )
+}
+
+fn set_config_spec(port: Arc<dyn SettingPort>) -> ToolSpec {
+    let handler: ToolFn =
+        Arc::new(move |ctx: &ToolCtx, args: &Value| apply_set_config(port.as_ref(), ctx, args));
+
+    ToolSpec::mutating(
+        SET_CONFIG,
+        "修改启动器配置（仅限白名单内的键）。普通键立即生效；敏感键（Java 路径/数据目录/代理/AI 端点）会先返回 needs_confirmation，等用户确认后才会真正写入。值必须符合该键的类型与范围。",
+        object(
+            &[
+                ("path", non_empty_string("配置键点分路径，必须是 get_config 列出的可写键")),
+                ("value", any()),
+            ],
+            &["path", "value"],
+        ),
+        handler,
+    )
+}
+
+/// `set_config` 的实现（独立成函数便于单测直接调用）。
+///
+/// # Errors
+/// 键不在白名单、值缺失、端口写入失败时返回 [`ToolError`]。
+pub fn apply_set_config(
+    port: &dyn SettingPort,
+    ctx: &ToolCtx,
+    args: &Value,
+) -> Result<ToolOutput, ToolError> {
+    let path = args
+        .get("path")
+        .and_then(Value::as_str)
+        .map(str::trim)
+        .filter(|p| !p.is_empty())
+        .ok_or_else(|| ToolError::NotAllowed("缺少参数 `path`".to_string()))?
+        .to_string();
+    let value = args
+        .get("value")
+        .cloned()
+        .ok_or_else(|| ToolError::NotAllowed("缺少参数 `value`".to_string()))?;
+
+    let keys = port.writable_keys();
+    let key = keys
+        .iter()
+        .find(|k| k.path == path)
+        .ok_or_else(|| ToolError::NotAllowed(not_writable_message(&keys, &path)))?;
+
+    // 旧值读不到不影响写（首次设置），只是 diff 少一半。
+    let old = port.get(&path).ok();
+
+    if !ctx.confirmed && key.sensitivity == Sensitivity::High {
+        let diff = json!({
+            "path": path,
+            "old": old,
+            "new": value,
+            "sensitivity": key.sensitivity,
+            "description": key.description,
+        });
+        return Ok(ToolOutput::needs_confirmation(
+            format!(
+                "AI 请求把 `{path}` 从 {} 改为 {}（{}）",
+                brief_opt(&old),
+                brief(&value),
+                sensitivity_label(key.sensitivity)
+            ),
+            diff,
+            key.sensitivity,
+        ));
+    }
+
+    let change = port.set(&path, &value).map_err(ToolError::Port)?;
+    Ok(ToolOutput::ok(
+        json!({
+            "status": "written",
+            "path": change.path,
+            "old": change.old,
+            "new": change.new,
+            "sensitivity": key.sensitivity,
+        }),
+        format!(
+            "已把 `{}` 从 {} 改为 {}",
+            change.path,
+            brief_opt(&change.old),
+            brief(&change.new)
+        ),
+    ))
+}
+
+/// 白名单拒绝的文案：说清"不能写"并给出可写键（模型会据此改用正确路径）。
+fn not_writable_message(keys: &[SettingKey], path: &str) -> String {
+    let listed: Vec<&str> = keys
+        .iter()
+        .take(MAX_LISTED_KEYS)
+        .map(|k| k.path.as_str())
+        .collect();
+    let rest = keys.len().saturating_sub(listed.len());
+    let tail = if rest > 0 {
+        format!("，另有 {rest} 个键见 get_config 概要")
+    } else {
+        String::new()
+    };
+    format!(
+        "配置键 `{path}` 不在 AI 可写白名单内。可写键（{} 个）：{}{tail}",
+        keys.len(),
+        listed.join("、")
+    )
+}
+
+fn describe_key(key: &SettingKey) -> Value {
+    json!({
+        "path": key.path,
+        "sensitivity": key.sensitivity,
+        "value_type": key.value_type,
+        "description": key.description,
+    })
+}
+
+fn sensitivity_label(sensitivity: Sensitivity) -> &'static str {
+    match sensitivity {
+        Sensitivity::Low => "普通",
+        Sensitivity::Medium => "中等（静默但审计）",
+        Sensitivity::High => "敏感，需确认",
+    }
+}
+
+fn brief(value: &Value) -> String {
+    let rendered = match value {
+        Value::String(s) => s.clone(),
+        other => other.to_string(),
+    };
+    truncate(&rendered)
+}
+
+fn brief_opt(value: &Option<Value>) -> String {
+    value
+        .as_ref()
+        .map_or_else(|| "（未设置）".to_string(), brief)
+}
+
+fn truncate(text: &str) -> String {
+    if text.chars().count() <= BRIEF_CHARS {
+        return text.to_string();
+    }
+    let head: String = text.chars().take(BRIEF_CHARS).collect();
+    format!("{head}…")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::testing::MockSettings;
+
+    fn ctx(confirmed: bool) -> ToolCtx {
+        ToolCtx {
+            agent_session_id: "s1".to_string(),
+            confirmed,
+        }
+    }
+
+    #[test]
+    fn rejects_keys_outside_whitelist() {
+        let port = MockSettings::new();
+        let err = apply_set_config(
+            &port,
+            &ctx(true),
+            &json!({ "path": "java.random.thing", "value": 1 }),
+        )
+        .unwrap_err();
+        assert!(matches!(err, ToolError::NotAllowed(_)));
+        assert!(err.message().contains("不在 AI 可写白名单内"));
+        assert!(err.message().contains("download.concurrency"));
+        assert_eq!(port.set_calls(), 0);
+    }
+
+    #[test]
+    fn normal_key_writes_without_confirmation() {
+        let port = MockSettings::new();
+        let out = apply_set_config(
+            &port,
+            &ctx(false),
+            &json!({ "path": "download.concurrency", "value": 16 }),
+        )
+        .unwrap();
+        assert!(out.confirmation.is_none());
+        assert_eq!(out.content["status"], json!("written"));
+        assert_eq!(port.value_of("download.concurrency"), Some(json!(16)));
+    }
+
+    #[test]
+    fn medium_key_writes_silently_too() {
+        // M12：Medium = 静默生效但审计标记，不弹窗
+        let port = MockSettings::new();
+        let out = apply_set_config(
+            &port,
+            &ctx(false),
+            &json!({ "path": "download.region", "value": "cn" }),
+        )
+        .unwrap();
+        assert!(out.confirmation.is_none());
+        assert_eq!(port.set_calls(), 1);
+    }
+
+    #[test]
+    fn high_key_quotes_first_then_writes_after_confirm() {
+        let port = MockSettings::new();
+        let args = json!({ "path": "java.selected_path", "value": "D:/jdk17/bin/java.exe" });
+
+        let quoted = apply_set_config(&port, &ctx(false), &args).unwrap();
+        let confirmation = quoted.confirmation.expect("High 键应要求确认");
+        assert_eq!(confirmation.sensitivity, Sensitivity::High);
+        assert_eq!(confirmation.details["new"], json!("D:/jdk17/bin/java.exe"));
+        assert_eq!(port.set_calls(), 0, "未确认前不得写入");
+
+        let written = apply_set_config(&port, &ctx(true), &args).unwrap();
+        assert!(written.confirmation.is_none());
+        assert_eq!(port.set_calls(), 1);
+        assert_eq!(
+            port.value_of("java.selected_path"),
+            Some(json!("D:/jdk17/bin/java.exe"))
+        );
+    }
+
+    #[test]
+    fn locked_credential_key_is_not_writable() {
+        // M12：ai.api_key 是 writable=false，不在白名单里 → 任何情况下都拒绝
+        let port = MockSettings::new();
+        let err = apply_set_config(
+            &port,
+            &ctx(true),
+            &json!({ "path": "ai.api_key", "value": "sk-x" }),
+        )
+        .unwrap_err();
+        assert!(matches!(err, ToolError::NotAllowed(_)));
+        assert_eq!(port.set_calls(), 0);
+    }
+
+    #[test]
+    fn port_error_is_passed_through() {
+        let port = MockSettings::new();
+        port.fail_set_with("磁盘只读");
+        let err = apply_set_config(
+            &port,
+            &ctx(true),
+            &json!({ "path": "appearance.theme_mode", "value": "metro_light" }),
+        )
+        .unwrap_err();
+        assert_eq!(err.code(), "port_error");
+        assert!(err.message().contains("磁盘只读"));
+    }
+}

crates/agent/src/tools/diagnose.rs

@@ -0,0 +1,335 @@
+//! `diagnose_crash`（02 文档 §3.2 第三条）。
+//!
+//! 流水线是「**规则在前、模型补位**」（analyse/02 §8.3）：本工具只跑 M15 的规则引擎，
+//! 把**结构化结论 + 关键片段**交给模型，绝不让模型读裸日志。规则未命中
+//! （`candidates` 空 / `needs_more_info`）时，模型再去用 `read_game_log` 自己找证据。
+//!
+//! P0 与 M15 的桥：M15 的修复动作指向 `java.set` / `memory.set` 这些 **P1 才有的**语义工具 id。
+//! P0 只有 `set_config`，所以这里按 [`FixActionKind`] 生成 `p0_next_steps`
+//! （`adjust_memory` → `set_config {"path":"java.default_memory_mb"}`，`change_java` →
+//! `set_config {"path":"java.selected_path"}`，见 [`MEMORY_KEY`] / [`JAVA_KEY`]），
+//! 剩下的动作明确标成「P0 无工具，解释给用户」。
+
+use std::sync::Arc;
+
+use serde_json::{json, Value};
+
+use crate::port::{CrashDiagnosis, DiagnosePort, DiagnosisCandidate, FixAction, FixActionKind};
+use crate::redact::redact_text;
+use crate::registry::schema::{integer, non_empty_string, object};
+use crate::registry::{
+    RegistryError, ToolCtx, ToolError, ToolFn, ToolOutput, ToolRegistry, ToolSpec,
+};
+
+/// 诊断工具名。
+pub const DIAGNOSE_CRASH: &str = "diagnose_crash";
+/// 单次返回的证据行上限（防 token 爆炸）。
+pub const MAX_EVIDENCE_LINES: usize = 40;
+/// 证据行默认条数。
+pub const DEFAULT_EVIDENCE_LINES: usize = 20;
+/// 单条证据最大字符数。
+pub const MAX_EVIDENCE_CHARS: usize = 400;
+/// 内存建议的配置键（M12 白名单里的键名，见 `setting-接口约定.md` §8）。
+pub const MEMORY_KEY: &str = "java.default_memory_mb";
+/// Java 路径的配置键。
+pub const JAVA_KEY: &str = "java.selected_path";
+
+/// 注册诊断工具。
+///
+/// # Errors
+/// 工具名重复/schema 非法时返回 [`RegistryError`]。
+pub fn register(
+    registry: &mut ToolRegistry,
+    port: Arc<dyn DiagnosePort>,
+) -> Result<(), RegistryError> {
+    let handler: ToolFn = Arc::new(move |_ctx: &ToolCtx, args: &Value| {
+        let session_id = args
+            .get("session_id")
+            .and_then(Value::as_str)
+            .map(str::trim)
+            .filter(|s| !s.is_empty())
+            .ok_or_else(|| ToolError::NotAllowed("缺少参数 `session_id`".to_string()))?;
+        let max_lines = args
+            .get("max_evidence_lines")
+            .and_then(Value::as_u64)
+            .map_or(DEFAULT_EVIDENCE_LINES, |n| n as usize)
+            .clamp(1, MAX_EVIDENCE_LINES);
+        let report = port.diagnose(session_id).map_err(ToolError::Port)?;
+        Ok(render(&report, max_lines))
+    });
+
+    registry.register(ToolSpec::read_only(
+        DIAGNOSE_CRASH,
+        "对某次游戏会话跑规则引擎（59 条崩溃规则）并返回结构化结论：主因、置信度、证据行、修复动作。规则未命中时会提示需要更多信息——此时再用 read_game_log 取 stderr/exit 片段。",
+        object(
+            &[
+                ("session_id", non_empty_string("会话 id，来自 list_game_sessions")),
+                (
+                    "max_evidence_lines",
+                    integer("返回多少条证据行", 1, MAX_EVIDENCE_LINES as i64),
+                ),
+            ],
+            &["session_id"],
+        ),
+        handler,
+    ))
+}
+
+/// 把规则引擎结论压成工具结果。
+fn render(report: &CrashDiagnosis, max_evidence_lines: usize) -> ToolOutput {
+    let candidates: Vec<Value> = report
+        .candidates
+        .iter()
+        .map(|c| render_candidate(c, max_evidence_lines))
+        .collect();
+    let secondary: Vec<Value> = report
+        .secondary
+        .iter()
+        .take(5)
+        .map(|c| {
+            json!({
+                "id": c.id,
+                "severity": c.severity,
+                "category": c.category,
+                "confidence": c.confidence,
+                "message": message_of(c),
+            })
+        })
+        .collect();
+    let next_steps: Vec<Value> = report
+        .candidates
+        .iter()
+        .flat_map(|c| c.fix_actions.iter())
+        .map(bridge_to_p0)
+        .collect();
+
+    let content = json!({
+        "session_id": report.session_id,
+        "source": report.source,
+        "needs_more_info": report.needs_more_info,
+        "exit": report.exit,
+        "top_confidence": report.top_confidence(),
+        "candidates": candidates,
+        "secondary": secondary,
+        "evidence": cap_lines(&report.evidence, max_evidence_lines),
+        "p0_next_steps": next_steps,
+    });
+
+    ToolOutput::ok(content, summarize(report))
+}
+
+fn render_candidate(candidate: &DiagnosisCandidate, max_evidence_lines: usize) -> Value {
+    json!({
+        "id": candidate.id,
+        "severity": candidate.severity,
+        "category": candidate.category,
+        "confidence": candidate.confidence,
+        "message": message_of(candidate),
+        "detail": candidate.detail,
+        "evidence": cap_lines(&candidate.evidence, max_evidence_lines),
+        "fix_actions": candidate.fix_actions,
+    })
+}
+
+/// `message` 为空时回落显示 i18n key（装配层没渲染时至少不丢信息）。
+fn message_of(candidate: &DiagnosisCandidate) -> String {
+    let text = candidate.message.trim();
+    if text.is_empty() {
+        candidate.message_key.clone()
+    } else {
+        text.to_string()
+    }
+}
+
+fn summarize(report: &CrashDiagnosis) -> String {
+    match report.top() {
+        Some(top) => {
+            let label = top
+                .fix_actions
+                .first()
+                .map(action_label)
+                .unwrap_or_else(|| "没有可执行的修复动作".to_string());
+            format!(
+                "规则引擎命中 {} 条候选，主因 `{}`（置信度 {:.2}）；建议：{label}",
+                report.candidates.len(),
+                top.id,
+                top.confidence
+            )
+        }
+        None if report.needs_more_info => {
+            "规则引擎未命中，且需要更多信息（用 read_game_log 取 stderr/exit 片段后再判断）"
+                .to_string()
+        }
+        None => "规则引擎未命中（59 条规则都不匹配），需要结合日志片段人工/AI 判断".to_string(),
+    }
+}
+
+/// M15 的语义动作 → P0 现有工具。返回给模型看的"下一步"。
+fn bridge_to_p0(action: &FixAction) -> Value {
+    let label = action_label(action);
+    match action.kind {
+        FixActionKind::AdjustMemory => {
+            let value = pick_memory_mb(action).map_or(Value::Null, |mb| json!(mb));
+            json!({
+                "action": action.tool,
+                "kind": action.kind,
+                "label": label,
+                "suggested_tool": "set_config",
+                "suggested_args": { "path": MEMORY_KEY, "value": value },
+            })
+        }
+        FixActionKind::ChangeJava => {
+            let value = pick_arg(action, &["path", "java_path", "binary", "value"])
+                .map_or(Value::Null, |p| json!(p));
+            json!({
+                "action": action.tool,
+                "kind": action.kind,
+                "label": label,
+                "suggested_tool": "set_config",
+                "suggested_args": { "path": JAVA_KEY, "value": value },
+            })
+        }
+        other => json!({
+            "action": action.tool,
+            "kind": other,
+            "label": label,
+            "suggested_tool": Value::Null,
+            "unavailable_reason": "P0 没有对应工具（P1 落地），请把这个建议解释给用户",
+        }),
+    }
+}
+
+/// 动作的人话：优先 M15 给的 `label`，否则按 kind 兜底。
+fn action_label(action: &FixAction) -> String {
+    let label = action.label.trim();
+    if !label.is_empty() {
+        return label.to_string();
+    }
+    match action.kind {
+        FixActionKind::ChangeJava => "换一个匹配的 Java 版本".to_string(),
+        FixActionKind::AdjustMemory => "调整最大内存".to_string(),
+        FixActionKind::ChangeGraphics => "调整图形设置/驱动".to_string(),
+        FixActionKind::RemoveMod => "移除或替换冲突的 Mod".to_string(),
+        FixActionKind::Reinstall => "重装/修复对应组件".to_string(),
+        FixActionKind::SeekHelp => "导出诊断包并反馈".to_string(),
+    }
+}
+
+/// 从动作参数里挑内存上限：先看常见键，再退化成"第一个带数字的值"。
+fn pick_memory_mb(action: &FixAction) -> Option<i64> {
+    if let Some(value) = pick_arg(
+        action,
+        &["value", "suggest", "mb", "max_mb", "xmx", "xmx_mb"],
+    ) {
+        if let Some(mb) = parse_mb(&value) {
+            return Some(mb);
+        }
+    }
+    action.args.values().find_map(|v| parse_mb(v))
+}
+
+fn pick_arg(action: &FixAction, keys: &[&str]) -> Option<String> {
+    keys.iter()
+        .find_map(|key| action.args.get(*key).cloned())
+        .filter(|v| !v.trim().is_empty())
+}
+
+/// `"4096"` / `"4G"` / `"6144M"` → MB。
+fn parse_mb(raw: &str) -> Option<i64> {
+    let text = raw.trim().to_ascii_lowercase();
+    let (number, scale) = if let Some(rest) = text.strip_suffix('g') {
+        (rest, 1024)
+    } else if let Some(rest) = text.strip_suffix("gb") {
+        (rest, 1024)
+    } else if let Some(rest) = text.strip_suffix('m') {
+        (rest, 1)
+    } else if let Some(rest) = text.strip_suffix("mb") {
+        (rest, 1)
+    } else {
+        (text.as_str(), 1)
+    };
+    number.trim().parse::<i64>().ok().map(|n| n * scale)
+}
+
+fn cap_lines(lines: &[String], max_lines: usize) -> Vec<String> {
+    lines
+        .iter()
+        .take(max_lines)
+        .map(|line| {
+            let masked = redact_text(line);
+            if masked.chars().count() <= MAX_EVIDENCE_CHARS {
+                masked
+            } else {
+                let head: String = masked.chars().take(MAX_EVIDENCE_CHARS).collect();
+                format!("{head}…")
+            }
+        })
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::testing::MockDiagnose;
+
+    fn call(port: &MockDiagnose, session_id: &str) -> ToolOutput {
+        let report = port.diagnose(session_id).expect("mock 应返回结论");
+        render(&report, DEFAULT_EVIDENCE_LINES)
+    }
+
+    #[test]
+    fn renders_candidates_with_p0_bridge_for_reinstall() {
+        let out = call(&MockDiagnose::new(), "s-1");
+        assert_eq!(out.content["candidates"].as_array().unwrap().len(), 1);
+        let confidence = out.content["top_confidence"].as_f64().unwrap();
+        assert!((confidence - 0.86).abs() < 1e-6, "{confidence}");
+        let steps = out.content["p0_next_steps"].as_array().unwrap();
+        assert_eq!(steps[0]["kind"], json!("reinstall"));
+        assert_eq!(steps[0]["suggested_tool"], Value::Null);
+        assert!(out.summary.contains("建议：重装该版本的 Forge 组件"));
+    }
+
+    #[test]
+    fn bridges_memory_action_to_set_config() {
+        let mut report = MockDiagnose::forge_missing_library();
+        if let Some(candidate) = report.candidates.first_mut() {
+            candidate.fix_actions = vec![FixAction {
+                kind: FixActionKind::AdjustMemory,
+                tool: "memory.set".to_string(),
+                label: String::new(),
+                args: [("suggest".to_string(), "4G".to_string())]
+                    .into_iter()
+                    .collect(),
+            }];
+        }
+        let out = render(&report, 5);
+        let steps = out.content["p0_next_steps"].as_array().unwrap();
+        assert_eq!(steps[0]["suggested_tool"], json!("set_config"));
+        assert_eq!(steps[0]["suggested_args"]["path"], json!(MEMORY_KEY));
+        assert_eq!(steps[0]["suggested_args"]["value"], json!(4096));
+        assert_eq!(steps[0]["label"], json!("调整最大内存"));
+    }
+
+    #[test]
+    fn parses_memory_units() {
+        assert_eq!(parse_mb("4096"), Some(4096));
+        assert_eq!(parse_mb("4G"), Some(4096));
+        assert_eq!(parse_mb("6144mb"), Some(6144));
+        assert_eq!(parse_mb("abc"), None);
+    }
+
+    #[test]
+    fn empty_candidates_says_need_more_info() {
+        let report = CrashDiagnosis {
+            session_id: "s-2".into(),
+            source: "rules".into(),
+            needs_more_info: true,
+            candidates: vec![],
+            secondary: vec![],
+            evidence: vec![],
+            exit: crate::port::ExitSummary::default(),
+        };
+        let out = render(&report, 5);
+        assert!(out.summary.contains("需要更多信息"));
+    }
+}

crates/agent/src/tools/game.rs

@@ -0,0 +1,199 @@
+//! 实例 / 版本 / Java 三个只读工具（M39 任务 3 的读侧）。
+//!
+//! 全部只读、全部走 [`crate::port::GamePort`]：agent 不自己去翻 `versions/` 目录，
+//! 也不自己扫 JDK——那两件事的真相源在 M14（game）与 M33（java），重复一份必然漂。
+//!
+//! 输出形状刻意做成「摘要 + 上限」：实例可能几十个、Java 候选可能十几个，
+//! 一次全塞给模型等于烧 token（02 §3.2 的「单次返回上限防 token 爆炸」同理）。
+
+use std::sync::Arc;
+
+use serde_json::{json, Value};
+
+use crate::port::GamePort;
+use crate::registry::schema::{integer, object};
+use crate::registry::{
+    RegistryError, ToolCtx, ToolError, ToolFn, ToolOutput, ToolRegistry, ToolSpec,
+};
+
+/// 实例列表工具名。
+pub const LIST_INSTANCES: &str = "list_instances";
+/// 版本列表工具名。
+pub const LIST_VERSIONS: &str = "list_versions";
+/// Java 现状工具名。
+pub const GET_JAVA_STATUS: &str = "get_java_status";
+/// 单次最多返回多少个实例/版本。
+pub const MAX_ROWS: usize = 50;
+
+/// 注册三个只读工具。
+///
+/// # Errors
+/// 工具名重复/schema 非法时返回 [`RegistryError`]。
+pub fn register(registry: &mut ToolRegistry, port: Arc<dyn GamePort>) -> Result<(), RegistryError> {
+    registry.register(list_instances_spec(Arc::clone(&port)))?;
+    registry.register(list_versions_spec(Arc::clone(&port)))?;
+    registry.register(java_status_spec(port))
+}
+
+fn limit_arg(args: &Value) -> usize {
+    args.get("limit")
+        .and_then(Value::as_u64)
+        .map_or(MAX_ROWS, |n| usize::try_from(n).unwrap_or(MAX_ROWS))
+        .clamp(1, MAX_ROWS)
+}
+
+fn limit_schema() -> Value {
+    integer(
+        &format!("最多返回多少条（1~{MAX_ROWS}，默认 {MAX_ROWS}）"),
+        1,
+        MAX_ROWS as i64,
+    )
+}
+
+fn list_instances_spec(port: Arc<dyn GamePort>) -> ToolSpec {
+    let handler: ToolFn = Arc::new(move |_ctx: &ToolCtx, args: &Value| {
+        let limit = limit_arg(args);
+        let mut instances = port.list_instances().map_err(ToolError::Port)?;
+        let total = instances.len();
+        instances.truncate(limit);
+        Ok(ToolOutput::ok(
+            json!({
+                "total": total,
+                "shown": instances.len(),
+                "truncated": total > instances.len(),
+                "instances": instances,
+            }),
+            format!("列出 {}/{} 个实例", instances.len(), total),
+        ))
+    });
+
+    ToolSpec::read_only(
+        LIST_INSTANCES,
+        "列出启动器里的游戏实例（id / 名称 / 版本 id / 载荷是否已安装 / 独立游戏目录 / 实例级 Java）。要看某个实例的日志先用 list_game_sessions。",
+        object(&[("limit", limit_schema())], &[]),
+        handler,
+    )
+}
+
+fn list_versions_spec(port: Arc<dyn GamePort>) -> ToolSpec {
+    let handler: ToolFn = Arc::new(move |_ctx: &ToolCtx, args: &Value| {
+        let limit = limit_arg(args);
+        let mut versions = port.list_versions().map_err(ToolError::Port)?;
+        let total = versions.len();
+        versions.truncate(limit);
+        Ok(ToolOutput::ok(
+            json!({
+                "total": total,
+                "shown": versions.len(),
+                "truncated": total > versions.len(),
+                "versions": versions,
+            }),
+            format!("列出 {}/{} 个已安装版本", versions.len(), total),
+        ))
+    });
+
+    ToolSpec::read_only(
+        LIST_VERSIONS,
+        "列出已安装的游戏版本（`versions/<id>/` 下真实存在的载荷），带类型与被几个实例引用。判断「实例的载荷缺没缺」时配合 list_instances 的 version_present 一起看。",
+        object(&[("limit", limit_schema())], &[]),
+        handler,
+    )
+}
+
+fn java_status_spec(port: Arc<dyn GamePort>) -> ToolSpec {
+    let handler: ToolFn = Arc::new(move |_ctx: &ToolCtx, _args: &Value| {
+        let status = port.java_status().map_err(ToolError::Port)?;
+        let majors: Vec<String> = status
+            .candidates
+            .iter()
+            .filter_map(|c| c.major.map(|m| m.to_string()))
+            .collect();
+        Ok(ToolOutput::ok(
+            json!({
+                "default_memory_mb": status.default_memory_mb,
+                "managed_roots": status.managed_roots,
+                "candidate_count": status.candidates.len(),
+                "majors": majors,
+                "candidates": status.candidates,
+            }),
+            format!(
+                "Java 候选 {} 个（主版本 {}）",
+                status.candidates.len(),
+                if majors.is_empty() {
+                    "无".to_string()
+                } else {
+                    majors.join("/")
+                }
+            ),
+        ))
+    });
+
+    ToolSpec::read_only(
+        GET_JAVA_STATUS,
+        "读取 Java 现状：托管扫描根、默认堆内存、探测到的全部运行时（路径 / 版本 / 主版本 / 发行方 / 来源）。启动报「不支持的 class 版本」「找不到 Java」时先看这里。",
+        object(&[], &[]),
+        handler,
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::testing::MockGame;
+
+    fn registry() -> ToolRegistry {
+        let mut registry = ToolRegistry::new();
+        register(&mut registry, Arc::new(MockGame::new())).expect("注册应成功");
+        registry
+    }
+
+    fn call(registry: &ToolRegistry, name: &str, args: Value) -> Value {
+        let spec = registry.get(name).expect("工具存在").clone();
+        let ctx = ToolCtx {
+            agent_session_id: "s1".to_string(),
+            confirmed: false,
+        };
+        (spec.handler)(&ctx, &args).expect("应成功").content
+    }
+
+    #[test]
+    fn lists_instances_with_limit() {
+        let content = call(&registry(), LIST_INSTANCES, json!({ "limit": 1 }));
+        assert_eq!(content["total"], json!(1));
+        assert_eq!(content["instances"][0]["id"], json!("inst-1"));
+        assert_eq!(content["truncated"], json!(false));
+    }
+
+    #[test]
+    fn lists_versions() {
+        let content = call(&registry(), LIST_VERSIONS, json!({}));
+        assert_eq!(content["total"], json!(2));
+        assert_eq!(content["versions"][0]["id"], json!("1.20.1-forge-47.2.20"));
+    }
+
+    #[test]
+    fn java_status_summarises_majors() {
+        let content = call(&registry(), GET_JAVA_STATUS, json!({}));
+        assert_eq!(content["candidate_count"], json!(2));
+        assert_eq!(content["majors"], json!(["17", "21"]));
+        assert_eq!(content["default_memory_mb"], json!(2048));
+    }
+
+    #[test]
+    fn port_errors_are_passed_through() {
+        let mut registry = ToolRegistry::new();
+        register(
+            &mut registry,
+            Arc::new(MockGame::failing("versions 目录不可读")),
+        )
+        .expect("注册应成功");
+        let spec = registry.get(LIST_VERSIONS).expect("工具存在").clone();
+        let ctx = ToolCtx {
+            agent_session_id: "s1".to_string(),
+            confirmed: false,
+        };
+        let err = (spec.handler)(&ctx, &json!({})).unwrap_err();
+        assert_eq!(err.code(), "port_error");
+        assert!(err.message().contains("versions 目录不可读"));
+    }
+}

crates/agent/src/tools/mod.rs

@@ -0,0 +1,39 @@
+//! 工具集 v1（02 文档 §3）：配置读写 / 会话与日志 / 崩溃诊断 / 实例与 Java / 账户。
+//!
+//! 分工边界（重要，评审时按这条看）：
+//! - **工具**：参数语义 → 端口调用 → 结构化结果；需要确认时**只报价不执行**。
+//! - **编排层**（[`crate::brain::exec`]）：schema 校验、确认闸门、YOLO 判定、审计、事件。
+//! - **端口**（[`crate::port`]）：真正的 IO 与领域校验（M12/M14/M15/M18/M31/M33 拥有）。
+//!
+//! 这样「YOLO」只在一个地方（编排层），工具的测试不需要关心 policy。
+//!
+//! 双投影：这里的注册表是**唯一真相源**，内置客户端投成 rig `DynamicTool`，
+//! 对外 MCP server 投成 rmcp `ToolRoute`（[`crate::mcp`]）。工具数量与顺序对外一致。
+
+pub mod accounts;
+pub mod config;
+pub mod diagnose;
+pub mod game;
+pub mod schema_tool;
+pub mod session;
+
+use crate::port::Ports;
+use crate::registry::{RegistryError, ToolRegistry};
+
+/// 组装 v1 的全部工具。注册顺序 = 模型看到的顺序（只读在前，写在后）。
+///
+/// 顺序不是随便排的：模型在长工具表里更容易选中靠前的项，所以「先看再改」
+/// （`get_config*` 在 `set_config` 之前）是刻意的提示。
+///
+/// # Errors
+/// 工具名重复 / schema 非法时返回 [`RegistryError`]（属于编码错误，装配期就该炸）。
+pub fn build_v1_registry(ports: &Ports) -> Result<ToolRegistry, RegistryError> {
+    let mut registry = ToolRegistry::new();
+    config::register(&mut registry, ports.setting.clone())?;
+    schema_tool::register(&mut registry, ports.setting.clone())?;
+    game::register(&mut registry, ports.game.clone())?;
+    accounts::register(&mut registry, ports.accounts.clone())?;
+    session::register(&mut registry, ports.sessions.clone())?;
+    diagnose::register(&mut registry, ports.diagnose.clone())?;
+    Ok(registry)
+}

crates/agent/src/tools/schema_tool.rs

@@ -0,0 +1,84 @@
+//! `get_config_schema`：把 M12 的配置 schema（**只含 AI 可写键**）投给模型。
+//!
+//! 为什么单独一个工具而不是塞进 `get_config`：模型要能「先看有哪些键、类型是什么、
+//! 哪些是敏感键」，再决定要不要写——这是一次性的静态信息，和读当前值不是同一件事。
+//! 拆开还能让 token 预算更可控（schema 比概要大一个量级）。
+//!
+//! 凭据边界：schema 由 M12 的 `SettingSchema::to_json_schema()` 生成，只遍历
+//! `ai.writable && !deprecated` 的键，`ai.api_key`（`locked`）天然不在其中。
+
+use std::sync::Arc;
+
+use serde_json::{json, Value};
+
+use crate::port::SettingPort;
+use crate::registry::schema::object;
+use crate::registry::{
+    RegistryError, ToolCtx, ToolError, ToolFn, ToolOutput, ToolRegistry, ToolSpec,
+};
+
+/// 工具名。
+pub const GET_CONFIG_SCHEMA: &str = "get_config_schema";
+
+/// 注册 `get_config_schema`。
+///
+/// # Errors
+/// 工具名重复/schema 非法时返回 [`RegistryError`]。
+pub fn register(
+    registry: &mut ToolRegistry,
+    port: Arc<dyn SettingPort>,
+) -> Result<(), RegistryError> {
+    let handler: ToolFn = Arc::new(move |_ctx: &ToolCtx, _args: &Value| {
+        let schema = port.schema();
+        if schema.get("properties").is_none() {
+            return Err(ToolError::Port(
+                "配置 schema 不可用：装配层没有提供 SettingPort::schema()".to_string(),
+            ));
+        }
+        let writable = schema
+            .get("properties")
+            .and_then(Value::as_object)
+            .map_or(0, serde_json::Map::len);
+        Ok(ToolOutput::ok(
+            json!({
+                "scope": "ai_writable_schema",
+                "writable_key_count": writable,
+                "schema": schema,
+            }),
+            format!("读取配置 schema（{writable} 个 AI 可写键）"),
+        ))
+    });
+
+    registry.register(ToolSpec::read_only(
+        GET_CONFIG_SCHEMA,
+        "读取启动器配置的 JSON Schema（只含 AI 可写键）。每个键带类型、取值范围、说明与 `x-ai-sensitivity` 敏感等级；凭据类键不会出现。写配置前先看它。",
+        object(&[], &[]),
+        handler,
+    ))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::testing::MockSettings;
+
+    fn ctx() -> ToolCtx {
+        ToolCtx {
+            agent_session_id: "s1".to_string(),
+            confirmed: false,
+        }
+    }
+
+    #[test]
+    fn returns_schema_without_credentials() {
+        let port: Arc<dyn SettingPort> = Arc::new(MockSettings::new());
+        let mut registry = ToolRegistry::new();
+        register(&mut registry, port).expect("注册应成功");
+        let spec = registry.get(GET_CONFIG_SCHEMA).expect("工具存在").clone();
+        let out = (spec.handler)(&ctx(), &json!({})).expect("应返回 schema");
+        let text = out.content.to_string();
+        assert!(out.content["writable_key_count"].as_u64().unwrap_or(0) > 0);
+        assert!(text.contains("x-ai-sensitivity"));
+        assert!(!text.contains("ai.api_key"), "凭据键不得进 schema：{text}");
+    }
+}

crates/agent/src/tools/session.rs

@@ -0,0 +1,388 @@
+//! `list_game_sessions` / `read_game_log`（02 文档 §3.2「能读取某次游戏崩溃日志」）。
+//!
+//! 数据源是 M18 的会话事件流（`DevDocs/SubAgentsTalk/launch-接口约定.md`）：
+//! - 列表读 `index.jsonl`（每会话一行摘要，同 id 取最后一行）；
+//! - 日志读 `<session-id>.jsonl`，**按 `seq` 切片 + 按 `kind` 过滤**，不是按行号。
+//!
+//! 两条防 token 爆炸的硬约束：
+//! 1. 单次最多 [`MAX_LOG_EVENTS`] 条事件（默认 [`DEFAULT_LOG_EVENTS`]）；
+//! 2. 单条 payload 里的字符串超过 [`MAX_PAYLOAD_CHARS`] 截断。
+//!
+//! 脱敏：launch 落盘前已经做过一遍（`<home>` / `<redacted:token>`），本工具再跑一遍
+//! [`crate::redact::redact_text`] 作为第二道防线（幂等，旧会话/第三方 mod 输出可能漏网）。
+
+use std::sync::Arc;
+
+use serde_json::{json, Map, Value};
+
+use crate::port::{GameSessionPort, LogEvent, LogPage, LogQuery};
+use crate::redact::redact_text;
+use crate::registry::schema::{enum_string_array, integer, non_empty_string, object, string};
+use crate::registry::{
+    RegistryError, ToolCtx, ToolError, ToolFn, ToolOutput, ToolRegistry, ToolSpec,
+};
+
+/// 列出游戏会话。
+pub const LIST_GAME_SESSIONS: &str = "list_game_sessions";
+/// 读一个会话的日志。
+pub const READ_GAME_LOG: &str = "read_game_log";
+
+/// 单次返回的事件上限（防 token 爆炸的硬闸）。
+pub const MAX_LOG_EVENTS: usize = 500;
+/// 默认返回条数。
+pub const DEFAULT_LOG_EVENTS: usize = 100;
+/// 单条 payload 字符串的展示上限（字符）。
+pub const MAX_PAYLOAD_CHARS: usize = 800;
+/// 列表默认/最大条数。
+pub const DEFAULT_SESSION_LIMIT: usize = 10;
+/// 列表最大条数。
+pub const MAX_SESSION_LIMIT: usize = 50;
+
+/// `launch-接口约定.md` §3 的事件类型（schema 里给模型做枚举；未知 kind 仍可透传）。
+pub const KNOWN_KINDS: [&str; 13] = [
+    "session_start",
+    "java_selected",
+    "cmd_built",
+    "natives_extracted",
+    "proc_start",
+    "stdout",
+    "stderr",
+    "window_detected",
+    "exit",
+    "crash_found",
+    "diagnosis",
+    "killed",
+    "session_end",
+];
+
+/// 注册两个日志工具。
+///
+/// # Errors
+/// 工具名重复/schema 非法时返回 [`RegistryError`]。
+pub fn register(
+    registry: &mut ToolRegistry,
+    port: Arc<dyn GameSessionPort>,
+) -> Result<(), RegistryError> {
+    registry.register(list_sessions_spec(Arc::clone(&port)))?;
+    registry.register(read_log_spec(port))
+}
+
+fn list_sessions_spec(port: Arc<dyn GameSessionPort>) -> ToolSpec {
+    let handler: ToolFn = Arc::new(move |_ctx: &ToolCtx, args: &Value| {
+        let limit = args
+            .get("limit")
+            .and_then(Value::as_u64)
+            .map_or(DEFAULT_SESSION_LIMIT, |n| n as usize)
+            .clamp(1, MAX_SESSION_LIMIT);
+        let instance_id = args.get("instance_id").and_then(Value::as_str);
+        let sessions = port
+            .list_sessions(limit, instance_id)
+            .map_err(ToolError::Port)?;
+
+        if sessions.is_empty() {
+            return Ok(ToolOutput::ok(
+                json!({ "sessions": [], "count": 0 }),
+                "没有游戏会话记录（还没启动过游戏，或数据目录不对）".to_string(),
+            ));
+        }
+
+        let crashed = sessions
+            .iter()
+            .filter(|s| s.crash_found || s.silent_failure || s.exit_code.is_some_and(|c| c != 0))
+            .count();
+        let summary = format!(
+            "最近 {} 个游戏会话，其中 {crashed} 个崩溃/异常退出；最近一次 {}（{}）",
+            sessions.len(),
+            sessions[0].session_id,
+            sessions[0].started_at.as_deref().unwrap_or("启动时间未知")
+        );
+        Ok(ToolOutput::ok(
+            json!({ "sessions": sessions, "count": sessions.len(), "problem_count": crashed }),
+            summary,
+        ))
+    });
+
+    ToolSpec::read_only(
+        LIST_GAME_SESSIONS,
+        "列出最近的游戏会话（启动时间、退出码、是否崩溃、规则引擎首选结论）。用于定位要读哪一次会话的日志。",
+        object(
+            &[
+                ("limit", integer("返回条数", 1, MAX_SESSION_LIMIT as i64)),
+                ("instance_id", string("只看某个实例的会话；省略则全部实例")),
+            ],
+            &[],
+        ),
+        handler,
+    )
+}
+
+fn read_log_spec(port: Arc<dyn GameSessionPort>) -> ToolSpec {
+    let handler: ToolFn = Arc::new(move |_ctx: &ToolCtx, args: &Value| {
+        let session_id = args
+            .get("session_id")
+            .and_then(Value::as_str)
+            .map(str::trim)
+            .filter(|s| !s.is_empty())
+            .ok_or_else(|| ToolError::NotAllowed("缺少参数 `session_id`".to_string()))?
+            .to_string();
+
+        let kinds: Vec<String> = args
+            .get("kinds")
+            .and_then(Value::as_array)
+            .map(|items| {
+                items
+                    .iter()
+                    .filter_map(Value::as_str)
+                    .map(str::to_string)
+                    .collect()
+            })
+            .unwrap_or_default();
+
+        let max_events = args
+            .get("max_events")
+            .and_then(Value::as_u64)
+            .map_or(DEFAULT_LOG_EVENTS, |n| n as usize)
+            .clamp(1, MAX_LOG_EVENTS);
+
+        let query = LogQuery {
+            from_seq: args.get("from_seq").and_then(Value::as_u64),
+            to_seq: args.get("to_seq").and_then(Value::as_u64),
+            kinds,
+            max_events,
+        };
+        let page = port
+            .read_log(&session_id, &query)
+            .map_err(ToolError::Port)?;
+        Ok(render_page(&page))
+    });
+
+    ToolSpec::read_only(
+        READ_GAME_LOG,
+        "读取某次游戏会话的事件流（stdout/stderr 按行、退出事件、crash-report 摘录）。可按 seq 区间和事件类型过滤；单次最多 500 条、单条最长 800 字符，优先用 kinds 过滤 stderr/exit/crash_found 而不是拉全量。",
+        object(
+            &[
+                ("session_id", non_empty_string("会话 id，来自 list_game_sessions")),
+                ("from_seq", integer("起始 seq（含）", 0, 9_007_199_254_740_991)),
+                ("to_seq", integer("结束 seq（含）", 0, 9_007_199_254_740_991)),
+                (
+                    "kinds",
+                    enum_string_array(&KNOWN_KINDS, "只要这些事件类型；省略则全部", 13),
+                ),
+                ("max_events", integer("最多返回多少条", 1, MAX_LOG_EVENTS as i64)),
+            ],
+            &["session_id"],
+        ),
+        handler,
+    )
+}
+
+/// 把端口返回的一页日志压成工具结果（含摘要，模型据此决定要不要继续翻页）。
+fn render_page(page: &LogPage) -> ToolOutput {
+    let events: Vec<Value> = page.events.iter().map(render_event).collect();
+    let kind_summary = page
+        .kind_counts
+        .iter()
+        .map(|(kind, count)| format!("{kind}×{count}"))
+        .collect::<Vec<_>>()
+        .join(", ");
+
+    let (content, summary) = if events.is_empty() {
+        (
+            json!({
+                "session_id": page.session_id,
+                "total_events": page.total_events,
+                "matched_events": 0,
+                "truncated": false,
+                "kind_counts": page.kind_counts,
+                "first_ts": page.first_ts,
+                "last_ts": page.last_ts,
+                "events": [],
+                "hint": "没有符合过滤条件的事件；把 kinds/from_seq/to_seq 放宽再试",
+            }),
+            format!(
+                "会话 {} 没有匹配的事件（共 {} 条）",
+                page.session_id, page.total_events
+            ),
+        )
+    } else {
+        let truncated_note = if page.truncated {
+            "（已截断）"
+        } else {
+            ""
+        };
+        (
+            json!({
+                "session_id": page.session_id,
+                "total_events": page.total_events,
+                "matched_events": page.matched_events,
+                "truncated": page.truncated,
+                "kind_counts": page.kind_counts,
+                "first_ts": page.first_ts,
+                "last_ts": page.last_ts,
+                "events": events,
+            }),
+            format!(
+                "会话 {}：共 {} 条事件，返回 {} 条{truncated_note}；类型分布 {kind_summary}",
+                page.session_id,
+                page.total_events,
+                events.len(),
+            ),
+        )
+    };
+    ToolOutput::ok(content, summary)
+}
+
+fn render_event(event: &LogEvent) -> Value {
+    json!({
+        "seq": event.seq,
+        "ts": event.ts,
+        "t_ms": event.t_ms,
+        "kind": event.kind,
+        "payload": shrink(&event.payload),
+    })
+}
+
+/// 递归脱敏 + 截断（第二道脱敏防线）。
+fn shrink(value: &Value) -> Value {
+    match value {
+        Value::String(text) => Value::String(cap(&redact_text(text))),
+        Value::Array(items) => Value::Array(items.iter().map(shrink).collect()),
+        Value::Object(map) => {
+            let mut out = Map::with_capacity(map.len());
+            for (key, item) in map {
+                out.insert(key.clone(), shrink(item));
+            }
+            Value::Object(out)
+        }
+        other => other.clone(),
+    }
+}
+
+fn cap(text: &str) -> String {
+    let length = text.chars().count();
+    if length <= MAX_PAYLOAD_CHARS {
+        return text.to_string();
+    }
+    let head: String = text.chars().take(MAX_PAYLOAD_CHARS).collect();
+    format!("{head}…（已截断 {} 字符）", length - MAX_PAYLOAD_CHARS)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::testing::MockSessions;
+    use serde_json::json;
+
+    const SESSION: &str = "20261029T124501-9f3c2a";
+
+    fn mock() -> MockSessions {
+        let (summary, events) = MockSessions::crashing_session(SESSION);
+        let (older, older_events) = MockSessions::crashing_session("20261028T100000-aaaaaa");
+        let mut sessions = MockSessions::new();
+        sessions.add(summary, events);
+        sessions.add(older, older_events);
+        sessions
+    }
+
+    fn registry() -> ToolRegistry {
+        let mut registry = ToolRegistry::new();
+        register(&mut registry, Arc::new(mock())).expect("注册应成功");
+        registry
+    }
+
+    /// 走**真实注册表 → 真实 handler**，不复制实现（否则测的是复制品）。
+    fn call(tool: &str, args: Value) -> ToolOutput {
+        let registry = registry();
+        let spec = registry.get(tool).expect("工具应存在").clone();
+        (spec.handler)(
+            &ToolCtx {
+                agent_session_id: "s1".to_string(),
+                confirmed: false,
+            },
+            &args,
+        )
+        .expect("工具应成功")
+    }
+
+    #[test]
+    fn lists_sessions_newest_first() {
+        let out = call(LIST_GAME_SESSIONS, json!({ "limit": 5 }));
+        assert_eq!(out.content["count"], json!(2));
+        assert_eq!(out.content["sessions"][0]["session_id"], json!(SESSION));
+        assert_eq!(out.content["problem_count"], json!(2));
+        assert!(out.summary.contains("2 个崩溃/异常退出"));
+    }
+
+    #[test]
+    fn list_respects_limit() {
+        let out = call(LIST_GAME_SESSIONS, json!({ "limit": 1 }));
+        assert_eq!(out.content["count"], json!(1));
+    }
+
+    #[test]
+    fn filters_by_kind_and_keeps_summary() {
+        let out = call(
+            READ_GAME_LOG,
+            json!({ "session_id": SESSION, "kinds": ["stderr"] }),
+        );
+        assert_eq!(out.content["events"].as_array().unwrap().len(), 1);
+        assert_eq!(out.content["kind_counts"]["stdout"], json!(1));
+        assert!(out.summary.contains("共 5 条事件"));
+    }
+
+    #[test]
+    fn truncates_when_more_events_than_cap() {
+        let out = call(
+            READ_GAME_LOG,
+            json!({ "session_id": SESSION, "max_events": 2 }),
+        );
+        assert_eq!(out.content["events"].as_array().unwrap().len(), 2);
+        assert_eq!(out.content["truncated"], json!(true));
+        assert_eq!(out.content["matched_events"], json!(5));
+    }
+
+    #[test]
+    fn masks_user_dir_in_payload() {
+        let out = call(
+            READ_GAME_LOG,
+            json!({ "session_id": SESSION, "kinds": ["crash_found"] }),
+        );
+        let payload = &out.content["events"][0]["payload"];
+        assert_eq!(
+            payload["path"],
+            json!(r"C:\Users\***\.minecraft\crash-reports\crash-1.txt")
+        );
+    }
+
+    #[test]
+    fn reports_empty_result_with_hint() {
+        let out = call(
+            READ_GAME_LOG,
+            json!({ "session_id": SESSION, "kinds": ["window_detected"] }),
+        );
+        assert_eq!(out.content["events"], json!([]));
+        assert!(out.content["hint"].is_string());
+    }
+
+    #[test]
+    fn caps_long_payload_text() {
+        let long = "x".repeat(MAX_PAYLOAD_CHARS + 10);
+        assert!(cap(&long).contains("已截断 10 字符"));
+    }
+
+    #[test]
+    fn unknown_session_is_a_port_error() {
+        let registry = registry();
+        let spec = registry.get(READ_GAME_LOG).expect("工具应存在").clone();
+        let err = (spec.handler)(
+            &ToolCtx {
+                agent_session_id: "s1".to_string(),
+                confirmed: false,
+            },
+            &json!({ "session_id": "nope" }),
+        )
+        .unwrap_err();
+        assert_eq!(err.code(), "port_error");
+        assert!(err.message().contains("不存在"));
+    }
+}