docs: 清理 sandbox 文章中的源码路径引用

移除末尾的源码阅读路径推荐和文中的具体文件路径，
保留以设计分析为主的内容结构不变。

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.githooks/pre-commit

@@ -1,22 +0,0 @@
-#!/bin/sh
-# pre-commit hook: 对暂存的文件运行 Biome 检查
-# 仅检查 src/ 下的 .ts/.tsx/.js/.jsx 文件
-
-STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '^src/.*\.(ts|tsx|js|jsx)$')
-
-if [ -z "$STAGED_FILES" ]; then
-  exit 0
-fi
-
-echo "Running Biome lint on staged files..."
-
-# 使用 biome lint 对暂存文件进行检查（仅 lint，不格式化，不自动修复）
-echo "$STAGED_FILES" | xargs bunx biome lint --no-errors-on-unmatched
-
-if [ $? -ne 0 ]; then
-  echo ""
-  echo "Biome lint failed. Fix errors or use --no-verify to bypass."
-  exit 1
-fi
-
-exit 0

.github/workflows/ci.yml

@@ -8,7 +8,7 @@ on:
 
 jobs:
   ci:
-    runs-on: macos-latest
+    runs-on: ubuntu-latest
 
     steps:
       - uses: actions/checkout@v4
@@ -20,8 +20,19 @@ jobs:
       - name: Install dependencies
         run: bun install --frozen-lockfile
 
-      - name: Test
-        run: bun test
+      - name: Type check
+        run: bunx tsc --noEmit
+
+      - name: Test with Coverage
+        run: |
+          set -o pipefail
+          bun test --coverage --coverage-reporter=lcov 2>&1 | grep -vE '^\s*(\(pass\)|\(skip\))' | sed '/^.*\/__tests__\/.*:$/d' | cat -s
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          file: ./coverage/lcov.info
+          token: ${{ secrets.CODECOV_TOKEN }}
 
       - name: Build
-        run: bun run build
+        run: bun run build:vite

.gitignore

@@ -12,9 +12,9 @@ src/utils/vendor/
 
 # AI tool runtime directories
 .agents/
-.codex/
+.claude/
 .omx/
-
+.docs/task/
 # Binary / screenshot files (root only)
 /*.png
 *.bmp
@@ -29,3 +29,12 @@ __pycache__/
 logs
 
 data
+.omc
+.codex/*
+!.codex/agents/
+!.codex/agents/**
+!.codex/skills/
+!.codex/skills/**
+.codex/skills/.system/**
+!.codex/prompts/
+!.codex/prompts/**

.impeccable.md

@@ -0,0 +1,78 @@
+# Impeccable Design Context
+
+## Users
+
+**Primary**: Technical teams and enterprises using AI-assisted coding in production workflows.
+- DevOps engineers managing remote agents via RCS dashboard
+- Development teams collaborating through shared sessions
+- Individual developers using terminal CLI daily
+
+**Context**: Used during focused work sessions — debugging, code review, agent orchestration. Users are in "get things done" mode, not browsing. They value efficiency but also appreciate warmth and personality.
+
+**Job to be done**: Make advanced AI coding tools accessible and controllable, especially features that normally require enterprise accounts or Anthropic OAuth.
+
+## Brand Personality
+
+**3 words**: Warm, Considered, Human
+
+**Voice**: Like a knowledgeable colleague who's genuinely enthusiastic about the craft — not a corporate product manager. Community-first, open, slightly playful. Chinese developer community culture (贴吧/discord 温暖氛围).
+
+**Emotional goals**: Confidence (this tool is solid), Warmth (this community is welcoming), Delight (small moments of personality make the difference).
+
+**References**:
+- **Anthropic's own design language** — their clean, considered aesthetic with warm undertones. The terra cotta/burnt orange as a human accent. Lots of breathing room. Typography-forward.
+- **NOT**: Generic AI product (no ChatGPT blue, no gradient text, no "AI slop"). NOT corporate SaaS (no Salesforce-blue dashboards, no enterprise sterility).
+
+**Anti-references**: Corporate enterprise dashboards, generic AI product pages, anything that looks like it was "designed by committee."
+
+## Aesthetic Direction
+
+**Theme**: Light + Dark dual mode (user/system preference switch)
+
+**Tone**: Anthropomorphic warmth meets terminal precision. The brand orange (Claude's terra cotta) is the thread that ties everything together — it's the human element in a technical world.
+
+**Typography**: Clean, considered, with good hierarchy. Terminal-native for CLI; modern web fonts for Web UI (RCS dashboard, docs). Favor readability and personality.
+
+**Color**:
+- Primary: Claude orange family (`#D77757` / terra cotta)
+- Accent: Warm neutrals tinted toward orange
+- Semantic: Success/Error/Warning following Anthropic's established palette
+- Dark mode: Warm dark surfaces (not cold blue-black)
+
+**Differentiation**: The CCB brand sits at the intersection of "serious tool" and "community project." It should feel like Anthropic's design principles applied to an open-source context — less corporate polish, more human craft. The mascot "Clawd" and the playful "踩踩背" naming hint at personality that the design should honor.
+
+**Scope**: All Web UI — RCS control panel, documentation site, landing pages.
+
+## Design Principles
+
+1. **Considered over clever** — Every design choice should feel intentional, not trendy. If it doesn't serve the user, it doesn't ship.
+2. **Warmth through subtlety** — Orange tints on neutrals, breathing room in layouts, personality in copy. Not giant emoji or aggressive color.
+3. **Density with clarity** — Technical users need information density, but not chaos. Every pixel earns its place.
+4. **Community voice** — The design should feel like it was made by people who use it, not by a distant design team. Slightly rough edges are fine if they're honest.
+5. **Anthropic's shadow** — When in doubt, follow Anthropic's design instincts — the clean layouts, the generous spacing, the warm color temperature. Then add the community touch.
+
+## Existing Design Assets
+
+### Brand Colors (from theme system)
+- Claude Orange: `rgb(215,119,87)` / `#D77757`
+- Claude Blue: `rgb(87,105,247)` / `#5769F7`
+- Permission Blue: `rgb(87,105,247)`
+- Auto Accept Violet: `rgb(135,0,255)`
+- Plan Mode Teal: `rgb(0,102,102)`
+- Success: `rgb(78,186,101)`
+- Error: `rgb(255,107,128)`
+- Warning: `rgb(255,193,7)`
+
+### Logo
+- CCB text + orange play button icon
+- Dark/Light SVG variants in `docs/logo/`
+- Favicon: Orange circle `#D97706` with white play triangle
+
+### Mascot
+- "Clawd" — terminal-art character with multiple poses
+- Theme-aware coloring
+
+### Theme System
+- 7 variants: dark, light, dark-ansi, light-ansi, dark-daltonized, light-daltonized, auto
+- 89+ semantic color tokens
+- Full documentation in `packages/@ant/ink/docs/04-theme-system.md`

.mintignore

@@ -0,0 +1,2 @@
+src/
+packages/

.npmrc

@@ -0,0 +1 @@
+registry=https://registry.npmjs.org/

CLAUDE.md

@@ -4,7 +4,22 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-This is a **reverse-engineered / decompiled** version of Anthropic's official Claude Code CLI tool. The goal is to restore core functionality while trimming secondary capabilities. Many modules are stubbed or feature-flagged off. The codebase has ~1341 tsc errors from decompilation (mostly `unknown`/`never`/`{}` types) — these do **not** block Bun runtime execution.
+This is a **reverse-engineered / decompiled** version of Anthropic's official Claude Code CLI tool. The goal is to restore core functionality while trimming secondary capabilities. Many modules are stubbed or feature-flagged off. TypeScript strict mode is enforced（见 Working with This Codebase 段的 tsc 要求）。
+
+## Git Commit Message Convention
+
+使用 **Conventional Commits** 规范：
+
+```
+<type>: <描述>
+```
+
+常见 type：`feat`、`fix`、`docs`、`chore`、`refactor`
+
+示例：
+- `feat: 添加模型 1M 上下文切换`
+- `fix: 修复初次登陆的校验问题`
+- `chore: remove prefetchOfficialMcpUrls call on startup`
 
 ## Commands
 
@@ -21,11 +36,14 @@ bun run dev:inspect
 # Pipe mode
 echo "say hello" | bun run src/entrypoints/cli.tsx -p
 
-# Build (code splitting, outputs dist/cli.js + ~450 chunk files)
+# Build (code splitting, outputs dist/cli.js + chunk files)
 bun run build
 
+# Build with Vite (alternative build pipeline)
+bun run build:vite
+
 # Test
-bun test                  # run all tests
+bun test                  # run all tests (3175 tests / 207 files / 0 fail)
 bun test src/utils/__tests__/hash.test.ts   # run single file
 bun test --coverage       # with coverage report
 
@@ -40,6 +58,11 @@ bun run health
 # Check unused exports
 bun run check:unused
 
+bun run typecheck
+
+# Remote Control Server
+bun run rcs
+
 # Docs dev server (Mintlify)
 bun run docs:dev
 ```
@@ -51,26 +74,30 @@ bun run docs:dev
 ### Runtime & Build
 
 - **Runtime**: Bun (not Node.js). All imports, builds, and execution use Bun APIs.
-- **Build**: `build.ts` 执行 `Bun.build()` with `splitting: true`，入口 `src/entrypoints/cli.tsx`，输出 `dist/cli.js` + chunk files。默认启用 `AGENT_TRIGGERS_REMOTE`、`CHICAGO_MCP`、`VOICE_MODE` feature。构建后自动替换 `import.meta.require` 为 Node.js 兼容版本（产物 bun/node 都可运行）。
-- **Dev mode**: `scripts/dev.ts` 通过 Bun `-d` flag 注入 `MACRO.*` defines，运行 `src/entrypoints/cli.tsx`。默认启用 `BUDDY`、`TRANSCRIPT_CLASSIFIER`、`BRIDGE_MODE`、`AGENT_TRIGGERS_REMOTE`、`CHICAGO_MCP`、`VOICE_MODE` 六个 feature。
+- **Build**: `build.ts` 执行 `Bun.build()` with `splitting: true`，入口 `src/entrypoints/cli.tsx`，输出 `dist/cli.js` + chunk files。Build 默认启用 19 个 feature（见下方 Feature Flag 段）。构建后自动替换 `import.meta.require` 为 Node.js 兼容版本（产物 bun/node 都可运行）。
+- **Dev mode**: `scripts/dev.ts` 通过 Bun `-d` flag 注入 `MACRO.*` defines，运行 `src/entrypoints/cli.tsx`。默认启用全部 feature。
 - **Module system**: ESM (`"type": "module"`), TSX with `react-jsx` transform.
-- **Monorepo**: Bun workspaces — internal packages live in `packages/` resolved via `workspace:*`.
+- **Monorepo**: Bun workspaces — 15 个 workspace packages + 若干辅助目录 in `packages/` resolved via `workspace:*`。
 - **Lint/Format**: Biome (`biome.json`)。`bun run lint` / `bun run lint:fix` / `bun run format`。
 - **Defines**: 集中管理在 `scripts/defines.ts`。当前版本 `2.1.888`。
+- **CI**: GitHub Actions — `ci.yml`（构建+测试）、`release-rcs.yml`（RCS 发布）、`update-contributors.yml`（自动更新贡献者）。
 
 ### Entry & Bootstrap
 
-1. **`src/entrypoints/cli.tsx`** — True entrypoint。`main()` 函数按优先级处理多条快速路径：
+1. **`src/entrypoints/cli.tsx`** (373 行) — True entrypoint。`main()` 函数按优先级处理多条快速路径：
    - `--version` / `-v` — 零模块加载
    - `--dump-system-prompt` — feature-gated (DUMP_SYSTEM_PROMPT)
    - `--claude-in-chrome-mcp` / `--chrome-native-host`
+   - `--computer-use-mcp` — 独立 MCP server 模式
    - `--daemon-worker=<kind>` — feature-gated (DAEMON)
-   - `remote-control` / `rc` / `bridge` — feature-gated (BRIDGE_MODE)
-   - `daemon` — feature-gated (DAEMON)
+   - `remote-control` / `rc` / `remote` / `sync` / `bridge` — feature-gated (BRIDGE_MODE)
+   - `daemon` [subcommand] — feature-gated (DAEMON)
    - `ps` / `logs` / `attach` / `kill` / `--bg` — feature-gated (BG_SESSIONS)
+   - `new` / `list` / `reply` — Template job commands
+   - `environment-runner` / `self-hosted-runner` — BYOC runner
    - `--tmux` + `--worktree` 组合
    - 默认路径：加载 `main.tsx` 启动完整 CLI
-2. **`src/main.tsx`** (~4680 行) — Commander.js CLI definition。注册大量 subcommands：`mcp` (serve/add/remove/list...)、`server`、`ssh`、`open`、`auth`、`plugin`、`agents`、`auto-mode`、`doctor`、`update` 等。主 `.action()` 处理器负责权限、MCP、会话恢复、REPL/Headless 模式分发。
+2. **`src/main.tsx`** (~6981 行) — Commander.js CLI definition。注册大量 subcommands：`mcp` (serve/add/remove/list...)、`server`、`ssh`、`open`、`auth`、`plugin`、`agents`、`auto-mode`、`doctor`、`update` 等。主 `.action()` 处理器负责权限、MCP、会话恢复、REPL/Headless 模式分发。
 3. **`src/entrypoints/init.ts`** — One-time initialization (telemetry, config, trust dialog)。
 
 ### Core Loop
@@ -82,21 +109,27 @@ bun run docs:dev
 ### API Layer
 
 - **`src/services/api/claude.ts`** — Core API client. Builds request params (system prompt, messages, tools, betas), calls the Anthropic SDK streaming endpoint, and processes `BetaRawMessageStreamEvent` events.
-- Supports multiple providers: Anthropic direct, AWS Bedrock, Google Vertex, Azure.
-- Provider selection in `src/utils/model/providers.ts`.
+- **7 providers**: `firstParty` (Anthropic direct), `bedrock` (AWS), `vertex` (Google Cloud), `foundry`, `openai`, `gemini`, `grok` (xAI)。
+- Provider selection in `src/utils/model/providers.ts`。优先级：modelType 参数 > 环境变量 > 默认 firstParty。
 
 ### Tool System
 
 - **`src/Tool.ts`** — Tool interface definition (`Tool` type) and utilities (`findToolByName`, `toolMatchesName`).
-- **`src/tools.ts`** — Tool registry. Assembles the tool list; some tools are conditionally loaded via `feature()` flags or `process.env.USER_TYPE`.
-- **`src/tools/<ToolName>/`** — 61 个 tool 目录（如 BashTool, FileEditTool, GrepTool, AgentTool, WebFetchTool, LSPTool, MCPTool 等）。每个 tool 包含 `name`、`description`、`inputSchema`、`call()` 及可选的 React 渲染组件。
-- **`src/tools/shared/`** — Tool 共享工具函数。
+- **`src/tools.ts`** (392 行) — Tool registry. Assembles the tool list; tools are imported from `@claude-code-best/builtin-tools` package. Some tools are conditionally loaded via `feature()` flags or `process.env.USER_TYPE`.
+- **`packages/builtin-tools/src/tools/`** — 59 个子目录（含 shared/testing 等工具目录），通过 `@claude-code-best/builtin-tools` 包导出。主要分类：
+  - **文件操作**: FileEditTool, FileReadTool, FileWriteTool, GlobTool, GrepTool
+  - **Shell/执行**: BashTool, PowerShellTool, REPLTool
+  - **Agent 系统**: AgentTool, TaskCreateTool, TaskUpdateTool, TaskListTool, TaskGetTool
+  - **规划**: EnterPlanModeTool, ExitPlanModeV2Tool, VerifyPlanExecutionTool
+  - **Web/MCP**: WebFetchTool, WebSearchTool, MCPTool, McpAuthTool
+  - **调度**: CronCreateTool, CronDeleteTool, CronListTool
+  - **其他**: LSPTool, ConfigTool, SkillTool, EnterWorktreeTool, ExitWorktreeTool 等
 
 ### UI Layer (Ink)
 
 - **`src/ink.ts`** — Ink render wrapper with ThemeProvider injection.
-- **`src/ink/`** — Custom Ink framework (forked/internal): custom reconciler, hooks (`useInput`, `useTerminalSize`, `useSearchHighlight`), virtual list rendering.
-- **`src/components/`** — 大量 React 组件（170+ 项），渲染于终端 Ink 环境中。关键组件：
+- **`packages/@ant/ink/`** — Custom Ink framework（forked/internal），包含 components、core、hooks、keybindings、theme、utils。注意：不是 `src/ink/`。
+- **`src/components/`** — 149 个组件目录/文件，渲染于终端 Ink 环境中。关键组件：
   - `App.tsx` — Root provider (AppState, Stats, FpsMetrics)
   - `Messages.tsx` / `MessageRow.tsx` — Conversation message rendering
   - `PromptInput/` — User input handling
@@ -112,10 +145,45 @@ bun run docs:dev
 - **`src/state/selectors.ts`** — State selectors.
 - **`src/bootstrap/state.ts`** — Module-level singletons for session-global state (session ID, CWD, project root, token counts, model overrides, client type, permission mode).
 
+### Workspace Packages
+
+| Package | 说明 |
+|---------|------|
+| `packages/@ant/ink/` | Forked Ink 框架（components、hooks、keybindings、theme） |
+| `packages/@ant/computer-use-mcp/` | Computer Use MCP server（截图/键鼠/剪贴板/应用管理） |
+| `packages/@ant/computer-use-input/` | 键鼠模拟（dispatcher + darwin/win32/linux backend） |
+| `packages/@ant/computer-use-swift/` | 截图 + 应用管理（dispatcher + per-platform backend） |
+| `packages/@ant/claude-for-chrome-mcp/` | Chrome 浏览器控制（通过 `--chrome` 启用） |
+| `packages/@ant/model-provider/` | Model provider 抽象层 |
+| `packages/builtin-tools/` | 内置工具集（60 个 tool 实现，通过 `@claude-code-best/builtin-tools` 导出） |
+| `packages/agent-tools/` | Agent 工具集 |
+| `packages/acp-link/` | ACP 代理服务器（WebSocket → ACP agent 桥接） |
+| `packages/cc-knowledge/` | Claude Code 知识库（非 workspace 包） |
+| `packages/langfuse-dashboard/` | Langfuse 可观测性面板（非 workspace 包） |
+| `packages/mcp-client/` | MCP 客户端库 |
+| `packages/mcp-server/` | MCP 服务端库（非 workspace 包） |
+| `packages/remote-control-server/` | 自托管 Remote Control Server（Docker 部署，含 Web UI）— Web UI 已重构为 React + Vite + Radix UI，支持 ACP agent 接入 |
+| `packages/swarm/` | Swarm 解耦模块（非 workspace 包） |
+| `packages/shell/` | Shell 抽象（非 workspace 包） |
+| `packages/audio-capture-napi/` | 原生音频捕获（已恢复） |
+| `packages/color-diff-napi/` | 颜色差异计算（完整实现，11 tests） |
+| `packages/image-processor-napi/` | 图像处理（已恢复） |
+| `packages/modifiers-napi/` | 键盘修饰键检测（stub） |
+| `packages/url-handler-napi/` | URL scheme 处理（stub） |
+
 ### Bridge / Remote Control
 
-- **`src/bridge/`** (~35 files) — Remote Control / Bridge 模式。feature-gated by `BRIDGE_MODE`。包含 bridge API、会话管理、JWT 认证、消息传输、权限回调等。Entry: `bridgeMain.ts`。
+- **`src/bridge/`** (~38 files) — Remote Control / Bridge 模式。feature-gated by `BRIDGE_MODE`。包含 bridge API、会话管理、JWT 认证、消息传输、权限回调等。Entry: `bridgeMain.ts`。
+- **`packages/remote-control-server/`** — 自托管 RCS，支持 Docker 部署，含 Web UI 控制面板（React 19 + Vite + Radix UI）。支持 ACP agent 通过 acp-link 接入（ACP WebSocket handler、relay handler、SSE event stream）。通过 `bun run rcs` 启动。
 - CLI 快速路径: `claude remote-control` / `claude rc` / `claude bridge`。
+- 详见 `docs/features/remote-control-self-hosting.md`。
+
+### ACP Protocol (Agent Client Protocol)
+
+- **`src/services/acp/`** — ACP agent 实现，包含 `agent.ts`（AcpAgent 类）、`bridge.ts`（Claude Code ↔ ACP 桥接）、`permissions.ts`（权限处理）、`entry.ts`（入口）。
+- **`packages/acp-link/`** — ACP 代理服务器，将 WebSocket 客户端桥接到 ACP agent。提供 `acp-link` CLI 命令，支持自定义端口/HTTPS/认证/会话管理、RCS 集成（REST 注册 + WS identify 两步流程）、权限模式透传（fallback: 客户端传值 > config > `ACP_PERMISSION_MODE` 环境变量）。
+- ACP 权限管道改进：`createAcpCanUseTool` 统一权限流水线，`applySessionMode` 模式同步，`bypassPermissions` 可用性检测（非 root/sandbox 环境）。
+- ACP Plan 可视化已支持 `session/update plan` 类型的消息展示（PlanView 组件，含进度条/状态图标/优先级标签）。
 
 ### Daemon Mode
 
@@ -128,91 +196,47 @@ bun run docs:dev
 
 ### Feature Flag System
 
-Feature flags control which functionality is enabled at runtime:
+Feature flags control which functionality is enabled at runtime. 代码中统一通过 `import { feature } from 'bun:bundle'` 导入，调用 `feature('FLAG_NAME')` 返回 `boolean`。
 
-- **在代码中使用**: 统一通过 `import { feature } from 'bun:bundle'` 导入，调用 `feature('FLAG_NAME')` 返回 `boolean`。**不要**在 `cli.tsx` 或其他文件里自己定义 `feature` 函数或覆盖这个 import。
-- **启用方式**: 通过环境变量 `FEATURE_<FLAG_NAME>=1`。例如 `FEATURE_BUDDY=1 bun run dev` 启用 BUDDY 功能。
-- **Dev 默认 features**: `BUDDY`、`TRANSCRIPT_CLASSIFIER`、`BRIDGE_MODE`、`AGENT_TRIGGERS_REMOTE`、`CHICAGO_MCP`、`VOICE_MODE`（见 `scripts/dev.ts`）。
-- **Build 默认 features**: `AGENT_TRIGGERS_REMOTE`、`CHICAGO_MCP`、`VOICE_MODE`（见 `build.ts`）。
-- **常见 flag**: `BUDDY`, `DAEMON`, `BRIDGE_MODE`, `BG_SESSIONS`, `PROACTIVE`, `KAIROS`, `VOICE_MODE`, `FORK_SUBAGENT`, `SSH_REMOTE`, `DIRECT_CONNECT`, `TEMPLATES`, `CHICAGO_MCP`, `BYOC_ENVIRONMENT_RUNNER`, `SELF_HOSTED_RUNNER`, `COORDINATOR_MODE`, `UDS_INBOX`, `LODESTONE`, `ABLATION_BASELINE` 等。
-- **类型声明**: `src/types/internal-modules.d.ts` 中声明了 `bun:bundle` 模块的 `feature` 函数签名。
+**启用方式**: 环境变量 `FEATURE_<FLAG_NAME>=1`。例如 `FEATURE_BUDDY=1 bun run dev`。
+
+**Build 默认 features**（19 个，见 `build.ts`）:
+- 基础: `BUDDY`, `TRANSCRIPT_CLASSIFIER`, `BRIDGE_MODE`, `AGENT_TRIGGERS_REMOTE`, `CHICAGO_MCP`, `VOICE_MODE`
+- 统计/缓存: `SHOT_STATS`, `PROMPT_CACHE_BREAK_DETECTION`, `TOKEN_BUDGET`
+- P0 本地: `AGENT_TRIGGERS`, `ULTRATHINK`, `BUILTIN_EXPLORE_PLAN_AGENTS`, `LODESTONE`
+- P1 API 依赖: `EXTRACT_MEMORIES`, `VERIFICATION_AGENT`, `KAIROS_BRIEF`, `AWAY_SUMMARY`, `ULTRAPLAN`
+- P2: `DAEMON`
+
+**Dev mode 默认**: 全部启用（见 `scripts/dev.ts`）。
+
+**类型声明**: `src/types/internal-modules.d.ts` 中声明了 `bun:bundle` 模块的 `feature` 函数签名。
 
 **新增功能的正确做法**: 保留 `import { feature } from 'bun:bundle'` + `feature('FLAG_NAME')` 的标准模式，在运行时通过环境变量或配置控制，不要绕过 feature flag 直接 import。
 
+### Multi-API 兼容层
+
+支持 OpenAI、Gemini、Grok 三种第三方 API，通过 `/login` 命令配置，均采用流适配器模式转为 Anthropic 内部格式。详见各兼容层的 docs 文档。
+
+### 穷鬼模式（Budget Mode）
+
+- 通过 `/poor` 命令切换，持久化到 `settings.json`。
+- 启用后跳过 `extract_memories`、`prompt_suggestion` 和 `verification_agent`，显著减少 token 消耗。
+- 实现在 `src/commands/poor/poorMode.ts`。
+
 ### Stubbed/Deleted Modules
 
 | Module | Status |
 |--------|--------|
-| Computer Use (`@ant/*`) | Restored — `computer-use-swift`, `computer-use-input`, `computer-use-mcp`, `claude-for-chrome-mcp` 均有完整实现，macOS + Windows 可用，Linux 后端待完成 |
-| `*-napi` packages | `audio-capture-napi`、`image-processor-napi` 已恢复实现；`color-diff-napi` 完整实现；`url-handler-napi`、`modifiers-napi` 仍为 stub |
-| Voice Mode | Restored — `src/voice/`、`src/hooks/useVoiceIntegration.tsx`、`src/services/voiceStreamSTT.ts` 等，Push-to-Talk 语音输入（需 Anthropic OAuth） |
-| OpenAI 兼容层 | Restored — `src/services/api/openai/`，支持 Ollama/DeepSeek/vLLM 等任意 OpenAI 协议端点，通过 `CLAUDE_CODE_USE_OPENAI=1` 启用 |
+| Computer Use (`@ant/*`) | Restored — macOS + Windows + Linux（后端完整度不一） |
+| `*-napi` packages | `audio-capture-napi`、`image-processor-napi` 已恢复；`color-diff-napi` 完整；`modifiers-napi`、`url-handler-napi` 仍为 stub |
+| Voice Mode | Restored — Push-to-Talk 语音输入（需 Anthropic OAuth） |
+| OpenAI/Gemini/Grok 兼容层 | Restored |
+| Remote Control Server | Restored — 自托管 RCS + Web UI |
 | Analytics / GrowthBook / Sentry | Empty implementations |
 | Magic Docs / LSP Server | Removed |
 | Plugins / Marketplace | Removed |
 | MCP OAuth | Simplified |
 
-### Computer Use
-
-Feature flag `CHICAGO_MCP`，dev/build 默认启用。实现跨平台屏幕操控（macOS + Windows 可用，Linux 待完成）。
-
-- **`packages/@ant/computer-use-mcp/`** — MCP server，注册截图/键鼠/剪贴板/应用管理工具
-- **`packages/@ant/computer-use-input/`** — 键鼠模拟，dispatcher + per-platform backend（`backends/darwin.ts`、`win32.ts`、`linux.ts`）
-- **`packages/@ant/computer-use-swift/`** — 截图 + 应用管理，同样 dispatcher + per-platform backend
-- **`packages/@ant/claude-for-chrome-mcp/`** — Chrome 浏览器控制（独立于 Computer Use，通过 `--chrome` CLI 参数启用）
-
-详见 `docs/features/computer-use.md`。
-
-### Voice Mode
-
-Feature flag `VOICE_MODE`，dev/build 默认启用。Push-to-Talk 语音输入，音频通过 WebSocket 流式传输到 Anthropic STT（Nova 3）。需要 Anthropic OAuth（非 API key）。
-
-- **`src/voice/voiceModeEnabled.ts`** — 三层门控（feature flag + GrowthBook + OAuth auth）
-- **`src/hooks/useVoice.ts`** — React hook 管理录音状态和 WebSocket 连接
-- **`src/services/voiceStreamSTT.ts`** — STT WebSocket 流式传输
-
-详见 `docs/features/voice-mode.md`。
-
-### OpenAI 兼容层
-
-通过 `CLAUDE_CODE_USE_OPENAI=1` 环境变量启用，支持任意 OpenAI Chat Completions 协议端点（Ollama、DeepSeek、vLLM 等）。流适配器模式：在 `queryModel()` 中将 Anthropic 格式请求转为 OpenAI 格式，再将 SSE 流转换回 `BetaRawMessageStreamEvent`，下游代码完全不改。
-
-- **`src/services/api/openai/`** — client、消息/工具转换、流适配、模型映射
-- **`src/utils/model/providers.ts`** — 添加 `'openai'` provider 类型（最高优先级）
-
-关键环境变量：`CLAUDE_CODE_USE_OPENAI`、`OPENAI_API_KEY`、`OPENAI_BASE_URL`、`OPENAI_MODEL`、`OPENAI_DEFAULT_OPUS_MODEL`、`OPENAI_DEFAULT_SONNET_MODEL`、`OPENAI_DEFAULT_HAIKU_MODEL`。详见 `docs/plans/openai-compatibility.md`。
-
-### Gemini 兼容层
-
-通过 `CLAUDE_CODE_USE_GEMINI=1` 环境变量或 `modelType: "gemini"` 设置启用，支持 Google Gemini API。独立的环境变量体系，不与 OpenAI 或 Anthropic 配置混杂。
-
-- **`src/services/api/gemini/`** — client、模型映射、类型定义
-- **`src/utils/model/providers.ts`** — 添加 `'gemini'` provider 类型
-- **`src/utils/managedEnvConstants.ts`** — Gemini 专用的 managed env vars
-
-关键环境变量：
-- `CLAUDE_CODE_USE_GEMINI` - 启用 Gemini provider
-- `GEMINI_API_KEY` - API 密钥（必填）
-- `GEMINI_BASE_URL` - API 端点（可选，默认 `https://generativelanguage.googleapis.com/v1beta`）
-- `GEMINI_MODEL` - 直接指定模型（最高优先级）
-- `GEMINI_DEFAULT_HAIKU_MODEL` / `GEMINI_DEFAULT_SONNET_MODEL` / `GEMINI_DEFAULT_OPUS_MODEL` - 按能力级别映射
-- `GEMINI_DEFAULT_HAIKU_MODEL_NAME` / `DESCRIPTION` / `SUPPORTED_CAPABILITIES` - 显示名称和描述
-- `GEMINI_SMALL_FAST_MODEL` - 快速任务使用的模型（可选）
-
-模型映射优先级（`src/services/api/gemini/modelMapping.ts`）：
-1. `GEMINI_MODEL` - 直接覆盖
-2. `GEMINI_DEFAULT_*_MODEL` - 独立配置（推荐）
-3. `ANTHROPIC_DEFAULT_*_MODEL` - 向后兼容 fallback（已废弃）
-4. 原样返回 Anthropic 模型名
-
-使用示例：
-```bash
-export CLAUDE_CODE_USE_GEMINI=1
-export GEMINI_API_KEY="your-api-key"
-export GEMINI_DEFAULT_SONNET_MODEL="gemini-2.5-flash"
-export GEMINI_DEFAULT_OPUS_MODEL="gemini-2.5-pro"
-```
-
 ### Key Type Files
 
 - **`src/types/global.d.ts`** — Declares `MACRO`, `BUILD_TARGET`, `BUILD_ENV` and internal Anthropic-only identifiers.
@@ -223,20 +247,74 @@ export GEMINI_DEFAULT_OPUS_MODEL="gemini-2.5-pro"
 ## Testing
 
 - **框架**: `bun:test`（内置断言 + mock）
+- **当前状态**: 3175 tests / 207 files / 0 fail
 - **单元测试**: 就近放置于 `src/**/__tests__/`，文件名 `<module>.test.ts`
 - **集成测试**: `tests/integration/` — 4 个文件（cli-arguments, context-build, message-pipeline, tool-chain）
 - **共享 mock/fixture**: `tests/mocks/`（api-responses, file-system, fixtures/）
 - **命名**: `describe("functionName")` + `test("behavior description")`，英文
-- **Mock 模式**: 对重依赖模块使用 `mock.module()` + `await import()` 解锁（必须内联在测试文件中，不能从共享 helper 导入）
-- **当前状态**: ~1623 tests / 114 files (110 unit + 4 integration) / 0 fail（详见 `docs/testing-spec.md`）
+- **包测试**: `packages/` 下各包也有独立测试（如 `color-diff-napi` 11 tests）
+
+### Mock 使用规范
+
+**只 mock 有副作用的依赖链，不 mock 纯函数/纯数据模块。**
+
+被迫 mock 的根源：`log.ts` / `debug.ts` → `bootstrap/state.ts`（模块级 `realpathSync` / `randomUUID` 副作用）。必须 mock 的模块：`log.ts`、`debug.ts`、`bun:bundle`、`settings/settings.js`、`config.ts`、`auth.ts`、第三方网络库。
+
+不要 mock：纯函数模块（`errors.ts`、`stringUtils.js`）、mock 值与真实实现相同的模块、mock 路径与实际 import 不匹配的模块。
+
+路径规则：统一用 `.ts` 扩展名 + `src/*` 别名路径，禁止双重 mock 同一模块。
+
+### 类型检查
+
+项目使用 TypeScript strict 模式，**tsc 必须零错误**。每次修改后运行：
+
+```bash
+bun run typecheck          # equivalent to bun run typecheck
+```
+
+**类型规范**：
+- 生产代码禁止 `as any`；测试文件中 mock 数据可用 `as any`
+- 类型不匹配优先用 `as unknown as SpecificType` 双重断言，或补充 interface
+- 未知结构对象用 `Record<string, unknown>` 替代 `any`
+- 联合类型用类型守卫（type guard）收窄，不要强转
+- `msg.request` 属性访问：`const req = msg.request as Record<string, unknown>`
+- Ink `color` prop：用 `as keyof Theme` 而非 `as any`
 
 ## Working with This Codebase
 
-- **Don't try to fix all tsc errors** — they're from decompilation and don't affect runtime.
+- **tsc must pass** — `bun run typecheck` 必须零错误，任何修改都不能引入新的类型错误。
 - **Feature flags** — 默认全部关闭（`feature()` 返回 `false`）。Dev/build 各有自己的默认启用列表。不要在 `cli.tsx` 中重定义 `feature` 函数。
 - **React Compiler output** — Components have decompiled memoization boilerplate (`const $ = _c(N)`). This is normal.
-- **`bun:bundle` import** — `import { feature } from 'bun:bundle'` 是 Bun 内置模块，由运行时/构建器解析。不要用自定义函数替代它。
+- **`bun:bundle` import** — `import { feature } from 'bun:bundle'` 是 Bun 内置模块，由运行时/构建器解析。不要用自定义函数替代它。**`feature()` 只能直接用在 `if` 语句或三元表达式的条件位置**（Bun 编译器限制），不能赋值给变量、不能放在箭头函数体里、不能作为 `&&` 链的一部分。正确：`if (feature('X')) {}` 或 `feature('X') ? a : b`。
 - **`src/` path alias** — tsconfig maps `src/*` to `./src/*`. Imports like `import { ... } from 'src/utils/...'` are valid.
 - **MACRO defines** — 集中管理在 `scripts/defines.ts`。Dev mode 通过 `bun -d` 注入，build 通过 `Bun.build({ define })` 注入。修改版本号等常量只改这个文件。
 - **构建产物兼容 Node.js** — `build.ts` 会自动后处理 `import.meta.require`，产物可直接用 `node dist/cli.js` 运行。
 - **Biome 配置** — 大量 lint 规则被关闭（decompiled 代码不适合严格 lint）。`.tsx` 文件用 120 行宽 + 强制分号；其他文件 80 行宽 + 按需分号。
+- **Ink 框架在 `packages/@ant/ink/`** — 不是 `src/ink/`（该目录不存在）。Ink 相关的组件、hooks、keybindings 都在 packages 中。
+- **Provider 优先级** — `modelType` 参数 > 环境变量 > 默认 `firstParty`。新增 provider 需在 `src/utils/model/providers.ts` 注册。
+
+## Design Context
+
+Impeccable 设计上下文保存在 `.impeccable.md` 中。设计 Web UI（RCS 控制面板、文档站、着陆页）时必须参考该文件。
+
+### 核心设计原则
+
+1. **Considered over clever** — 每个设计选择都应感觉有意为之，而非追逐潮流
+2. **Warmth through subtlety** — 通过橙色色调的中性色、留白布局、有温度的文案来传达温暖
+3. **Density with clarity** — 技术用户需要信息密度，但不能混乱
+4. **Community voice** — 设计应感觉是由使用者创造的，而非遥远的设计团队
+5. **Anthropic's shadow** — 遵循 Anthropic 的设计直觉：干净的布局、充足的间距、温暖的色温
+
+### 品牌色
+
+- 主色：Claude Orange `#D77757`（terra cotta）
+- 辅色：Claude Blue `#5769F7`
+- 暗色模式使用温暖的深色表面（非冷蓝黑色）
+
+### 目标用户
+
+技术团队/企业，在专业工作流中使用 AI 辅助编程。友好的开源社区氛围，非企业 SaaS 风格。
+
+### 视觉参考
+
+Anthropic 公司的设计风格 — 干净、考究、温暖的底色。大量留白，以排版为核心。避免 AI 产品常见的设计套路（渐变文字、玻璃态、霓虹色）。

DEV-LOG.md

@@ -1,5 +1,194 @@
 # DEV-LOG
 
+## /poor 省流模式 (2026-04-11)
+
+新增 `/poor` 命令，toggle 关闭 `extract_memories` 和 `prompt_suggestion`，省 token。
+
+- 新增 `POOR` feature flag（build.ts + dev.ts）
+- `src/commands/poor/` — 命令定义 + toggle 实现 + 状态管理
+- `src/query/stopHooks.ts` — POOR 模式激活时跳过 extract_memories 和 prompt_suggestion
+
+---
+
+## Pipe IPC + LAN Pipes + Monitor Tool + 工具恢复 (2026-04-08 ~ 2026-04-11)
+
+**分支**: `feat/pr-package-adapt`
+
+### 背景
+
+从 decompiled 代码恢复大量 stub 为完整实现，同时新增 LAN 跨机器通讯能力。本次 PR 覆盖：Pipe IPC 系统、LAN Pipes、Monitor Tool、20+ 工具/组件<E7BB84><E4BBB6><EFBFBD>复、REPL hook 架构重构。
+
+### 实现
+
+#### 1. PipeServer TCP 双模式（`src/utils/pipeTransport.ts`）
+
+从原始的纯 UDS 服务器扩展为 UDS + TCP 双模式：
+
+- 提取 `setupSocket()` 共享方法，UDS 和 TCP 的 socket 处理逻辑完全一致
+- `start(options?: PipeServerOptions)` 新增可选参数 `{ enableTcp, tcpPort }`
+- 内部维护两个 `net.Server`（UDS + TCP），共享同一组 `clients: Set<Socket>` 和 `handlers`
+- TCP server 绑定 `0.0.0.0` + 动态端口（port=0 由 OS 分配）
+- `tcpAddress` getter 暴露 TCP 端口信息
+- `close()` 同时关闭两个 server
+- 新增类型：`PipeTransportMode`、`TcpEndpoint`、`PipeServerOptions`
+
+PipeClient 对应扩展：
+- 构造函数新增可选 `TcpEndpoint` 参数
+- `connect()` 根据是否有 TCP endpoint 分派到 `connectTcp()` 或 `connectUds()`
+- TCP 连接不需要文件存在轮询，直接建立连接
+
+#### 2. LAN Beacon — UDP Multicast 发现（`src/utils/lanBeacon.ts`，新文件）
+
+零配置局域网 peer 发现：
+
+- **协议**：UDP multicast 组 `224.0.71.67`（"CC" ASCII），端口 `7101`，TTL=1
+- **Announce 包**：JSON `{ proto, pipeName, machineId, hostname, ip, tcpPort, role, ts }`
+- **广播间隔**：3 秒，首次在 socket bind 完成后立即发送
+- **Peer 超时**：15 秒无 announce 视为 lost
+- **事件**：`peer-discovered`、`peer-lost`
+- **存储**：module-level singleton `getLanBeacon()`/`setLanBeacon()`，不挂在 Zustand state 上
+
+关键修复：
+- `addMembership(group, localIp)` + `setMulticastInterface(localIp)` 指定 LAN 网卡，解决 Windows 上 WSL/Docker 虚拟网卡劫持 multicast 的问题
+- announce/cleanup 定时器移入 `bind()` 回调内，修复 socket 未就绪时发送的竞态
+
+#### 3. Registry 扩展（`src/utils/pipeRegistry.ts`）
+
+- `PipeRegistryEntry` 新增 `tcpPort?` 和 `lanVisible?` 字段
+- `mergeWithLanPeers(registry, lanPeers)` 合并本地 registry 和 LAN beacon peers，本地优先
+
+#### 4. Peer Address 扩展（`src/utils/peerAddress.ts`）
+
+- `parseAddress()` 新增 `tcp` scheme：`tcp:192.168.1.20:7100`
+- 新增 `parseTcpTarget()` 解析 `host:port` 字符串
+
+#### 5. REPL 集成（`src/screens/REPL.tsx`）
+
+三个阶段的改动：
+
+**Bootstrap**：`createPipeServer()` 时根据 `feature('LAN_PIPES')` 传入 TCP 选项 → 启动 `LanBeacon` → 注册 entry 携带 tcpPort
+
+**Heartbeat**（每 5 秒）：
+- `refreshDiscoveredPipes()` 同时包含本地 subs 和 LAN beacon peers，防止 LAN peer 状态被覆盖
+- auto-attach 循环统一遍历本地 subs + LAN peers，LAN peers 通过 TCP endpoint 连接
+- cleanup 检查 LAN beacon peers 列表，避免误删存活的 LAN 连接
+- attach 请求携带 `machineId`，接收方区分 LAN peer（不要求 sub 角色）
+
+**Cleanup**：通过 `getLanBeacon()` 获取并 `stop()`，`setLanBeacon(null)` 清除
+
+#### 6. 命令更新
+
+- `/pipes`（`src/commands/pipes/pipes.ts`）：显示 `[LAN]` 标记的远端实例
+- `/attach`（`src/commands/attach/attach.ts`）：自动查找 LAN beacon 获取 TCP endpoint
+- `SendMessageTool`（`src/tools/SendMessageTool/SendMessageTool.ts`）：支持 `tcp:` scheme，权限检查要求用户确认
+
+#### 7. Feature Flag
+
+`LAN_PIPES` — 在 `scripts/dev.ts` 和 `build.ts` 的默认 features 列表中启用。所有 LAN 代码路径均通过 `feature('LAN_PIPES')` 门控。
+
+#### 8. Pipe IPC 基础系统（`UDS_INBOX` feature）
+
+- `PipeServer`/`PipeClient`：UDS 传输，NDJSON 协议（共享 `ndjsonFramer.ts`）
+- `PipeRegistry`：machineId 绑定的角色分配（main/sub），文件锁，并行探测
+- Master/slave attach 流程、prompt 转发、permission 转发
+- Heartbeat 生命周期（5s 间隔，stale entry 清理，busy flag 防重叠）
+- 命令：`/pipes`、`/attach`、`/detach`、`/send`、`/claim-main`、`/pipe-status`
+
+#### 9. Monitor Tool（`MONITOR_TOOL` feature）
+
+- `MonitorTool`：AI 可调用的后台 shell 监控工具
+- `/monitor` 命令：用户快捷入口，Windows 兼容（watch → PowerShell 循环）
+- `MonitorMcpTask`：从 stub 恢复完整生命周期（register/complete/fail/kill）
+- `MonitorPermissionRequest`：React 权限确认 UI
+- `MonitorMcpDetailDialog`：Shift+Down 详情面板
+
+#### 10. 工具恢复（stub → 实现）
+
+- SnipTool、SleepTool、ListPeersTool、SendUserFileTool
+- WebBrowserTool、SubscribePRTool、PushNotificationTool
+- CtxInspectTool、TerminalCaptureTool、WorkflowTool
+- REPLTool (.js → .ts)、VerifyPlanExecutionTool (.js → .ts)、SuggestBackgroundPRTool (.js → .ts)
+- 组件 .ts → .tsx 重写：MonitorPermissionRequest、ReviewArtifactPermissionRequest、MonitorMcpDetailDialog、WorkflowDetailDialog、WorkflowPermissionRequest
+
+#### 11. REPL Hook 架构重构
+
+从 REPL.tsx 提取 ~830 行 Pipe IPC 内联代码为 4 个独立 hook：
+
+| Hook | 行数 | 职责 |
+|------|------|------|
+| `usePipeIpc` | 623 | 生命周期：bootstrap、handlers、heartbeat、cleanup |
+| `usePipeRelay` | 38 | slave→master 消息回传（通过 `setPipeRelay` singleton） |
+| `usePipePermissionForward` | 159 | 权限请求转发 + 流式通知显示 |
+| `usePipeRouter` | 130 | selected pipe 输入路由 + role/IP 标签显示 |
+
+共享工具：`ndjsonFramer.ts` 替换 3 份重复的 NDJSON 解析。
+
+#### 12. Feature Flags 新增启用
+
+UDS_INBOX、LAN_PIPES、MONITOR_TOOL、FORK_SUBAGENT、KAIROS、COORDINATOR_MODE、WORKFLOW_SCRIPTS、HISTORY_SNIP、CONTEXT_COLLAPSE
+
+### 踩坑记录
+
+1. **Multicast 绑错网卡**：Windows 上 `addMembership(group)` 不指定本地接口时，默认绑到 WSL/Docker 虚拟网卡（`172.19.112.1`），LAN 上的真实机器收不到。必须 `addMembership(group, localIp)` + `setMulticastInterface(localIp)`。
+
+2. **Beacon ref 丢失**：最初用 `(store.getState() as any)._lanBeacon` 挂载 beacon 引用，但 Zustand `setState` 展开 `prev` 时不包含 `_lanBeacon` 属性，下次读取就是 `undefined`。改为 module-level singleton 解决。
+
+3. **Heartbeat 清洗 LAN 连接**：`refreshDiscoveredPipes()` 每 5 秒用仅含本地 registry subs 的列表完全覆盖 `discoveredPipes` + `selectedPipes`，LAN peer 的发现和选择状态被持续清空。必须在 refresh 中同时包含 beacon peers。
+
+4. **Heartbeat cleanup 误删**：`!aliveSubNames.has(slaveName)` 导致 LAN peer（不在本地 registry）被判定为死连接每 5 秒清除一次。需要同时检查 beacon peers 列表。
+
+5. **跨机器 attach 被拒**：两台机器各自为 `main`，attach handler 硬编码 `role !== 'sub'` 拒绝。通过 attach_request 携带 `machineId`，接收方对不同 machineId 的请求放行。
+
+6. **`feature()` 使用约束**：Bun 的 `feature()` 是编译时常量，只能在 `if` 语句或三元条件中直接使用，不能赋值给变量（如 `const x = feature('...')`），否则构建报错。
+
+### 已知限制
+
+- TCP 无认证：同 LAN 内任何设备知道端口号即可连接
+- JSON.parse 无 schema 验证：code review 建议增加 Zod 校验
+- Beacon 明文广播 IP/hostname/machineId：建议后续 hash 处理
+- `getLocalIp()` 可能返回 VPN 地址：多网卡环境需更精确的接口选择
+
+### 测试
+
+- `src/utils/__tests__/lanBeacon.test.ts`：7 个测试（mock dgram）
+- `src/utils/__tests__/peerAddress.test.ts`：8 个测试（纯函数）
+- 全量：2190 pass / 0 fail
+
+### 防火墙配置
+
+**Windows**（管理员 PowerShell）：
+```powershell
+New-NetFirewallRule -DisplayName "Claude Code LAN Beacon (UDP)" -Direction Inbound -Protocol UDP -LocalPort 7101 -Action Allow -Profile Private
+New-NetFirewallRule -DisplayName "Claude Code LAN Pipes (TCP)" -Direction Inbound -Protocol TCP -LocalPort 1024-65535 -Program (Get-Command bun).Source -Action Allow -Profile Private
+New-NetFirewallRule -DisplayName "Claude Code LAN Beacon Out (UDP)" -Direction Outbound -Protocol UDP -RemotePort 7101 -Action Allow -Profile Private
+```
+
+**macOS**（首次运行时系统会弹出"允许接受传入连接"对话框，点击允许即可。手动放行）：
+```bash
+# 如果使用 pf <20><><EFBFBD>火墙，添加规则：
+echo "pass in proto udp from any to any port 7101" | sudo pfctl -ef -
+# 或<><E68896>接在 System Settings → Network → Firewall 中允许 bun 进程
+```
+
+**Linux**（firewalld）：
+```bash
+sudo firewall-cmd --zone=trusted --add-port=7101/udp --permanent
+sudo firewall-cmd --zone=trusted --add-port=1024-65535/tcp --permanent
+sudo firewall-cmd --reload
+```
+
+**Linux**（iptables）：
+```bash
+sudo iptables -A INPUT -p udp --dport 7101 -j ACCEPT
+sudo iptables -A INPUT -p tcp --dport 1024:65535 -m owner --uid-owner $(id -u) -j ACCEPT
+sudo iptables-save | sudo tee /etc/iptables/rules.v4
+```
+
+**通用验证**：确认网络为局域网（非公共 WiFi），路<EFBC8C><E8B7AF><EFBFBD>器未开启 AP 隔离。
+
+---
+
+
 ## Daemon + Remote Control Server 还原 (2026-04-07)
 
 **分支**: `feat/daemon-remote-control-server`

README.md

@@ -6,17 +6,30 @@
 [![GitHub License](https://img.shields.io/github/license/claude-code-best/claude-code?style=flat-square)](https://github.com/claude-code-best/claude-code/blob/main/LICENSE)
 [![Last Commit](https://img.shields.io/github/last-commit/claude-code-best/claude-code?style=flat-square&color=blue)](https://github.com/claude-code-best/claude-code/commits/main)
 [![Bun](https://img.shields.io/badge/runtime-Bun-black?style=flat-square&logo=bun)](https://bun.sh/)
-[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?style=flat-square&logo=discord)](https://discord.gg/qZU6zS7Q)
+[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?style=flat-square&logo=discord)](https://discord.gg/uApuzJWGKX)
 
 > Which Claude do you like? The open source one is the best.
 
-牢 A (Anthropic) 官方 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI 工具的源码反编译/逆向还原项目。目标是将 Claude Code 大部分功能及工程化能力复现 (问就是老佛爷已经付过钱了)。虽然很难绷, 但是它叫做 CCB(踩踩背)...
+牢 A (Anthropic) 官方 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI 工具的源码反编译/逆向还原项目。目标是将 Claude Code 大部分功能及工程化能力复现 (问就是老佛爷已经付过钱了)。虽然很难绷, 但是它叫做 CCB(踩踩背)... 而且, 我们实现了企业版或者需要登陆 Claude 账号才能使用的特性, 实现技术普惠
 
-[文档在这里, 支持投稿 PR](https://ccb.agent-aura.top/) | [留影文档在这里](./Friends.md) | [Discord 群组](https://discord.gg/qZU6zS7Q)
+[文档在这里, 支持投稿 PR](https://ccb.agent-aura.top/) | [留影文档在这里](./Friends.md) | [Discord 群组](https://discord.gg/uApuzJWGKX)
 
-- ✅ [x] V4 — 测试补全、[Buddy](https://ccb.agent-aura.top/docs/features/buddy)、[Auto Mode](https://ccb.agent-aura.top/docs/safety/auto-mode)、环境变量 Feature 开关
-- ✅ [x] V5 — [Sentry](https://ccb.agent-aura.top/docs/internals/sentry-setup) / [GrowthBook](https://ccb.agent-aura.top/docs/internals/growthbook-adapter) 企业监控、[自定义 Login](https://ccb.agent-aura.top/docs/features/custom-platform-login)、[OpenAI 兼容](https://ccb.agent-aura.top/docs/plans/openai-compatibility)、[Web Search](https://ccb.agent-aura.top/docs/features/web-browser-tool)、[Computer Use](https://ccb.agent-aura.top/docs/features/computer-use) / [Chrome Use](https://ccb.agent-aura.top/docs/features/claude-in-chrome-mcp)、[Voice Mode](https://ccb.agent-aura.top/docs/features/voice-mode)、[Bridge Mode](https://ccb.agent-aura.top/docs/features/bridge-mode)、[/dream 记忆整理](https://ccb.agent-aura.top/docs/features/auto-dream)
-- 🔮 [ ] V6 — 大规模重构石山代码，全面模块分包（全新分支，main 封存为历史版本）
+| 特性 | 说明 | 文档 |
+|------|------|------|
+| **Claude 群控技术** | Pipe IPC 多实例协作：同机 main/sub 自动编排 + LAN 跨机器零配置发现与通讯，`/pipes` 选择面板 + `Shift+↓` 交互 + 消息广播路由 | [Pipe IPC](https://ccb.agent-aura.top/docs/features/pipes-and-lan) / [LAN](https://ccb.agent-aura.top/docs/features/lan-pipes) |
+| **ACP 协议一等一支持** | 支持接入 Zed、Cursor 等 IDE，支持会话恢复、Skills、权限桥接 | [文档](https://ccb.agent-aura.top/docs/features/acp-zed) |
+| **Remote Control 私有部署** | Docker 自托管远程界面, 可以手机上看 CC | [文档](https://ccb.agent-aura.top/docs/features/remote-control-self-hosting) |
+| **Langfuse 监控** | 企业级 Agent 监控, 可以清晰看到每次 agent loop 细节, 可以一键转化为数据集 | [文档](https://ccb.agent-aura.top/docs/features/langfuse-monitoring) |
+| **Web Search** | 内置网页搜索工具, 支持 bing 和 brave 搜索 | [文档](https://ccb.agent-aura.top/docs/features/web-browser-tool) |
+| **Poor Mode** | 穷鬼模式，关闭记忆提取和键入建议,大幅度减少并发请求 | /poor 可以开关 |
+| **Channels 频道通知** | MCP 服务器推送外部消息到会话（飞书/Slack/Discord/微信等），`--channels plugin:name@marketplace` 启用 | [文档](https://ccb.agent-aura.top/docs/features/channels) |
+| **自定义模型供应商** | OpenAI/Anthropic/Gemini/Grok 兼容 | [文档](https://ccb.agent-aura.top/docs/features/custom-platform-login) |
+| Voice Mode | Push-to-Talk 语音输入 | [文档](https://ccb.agent-aura.top/docs/features/voice-mode) |
+| Computer Use | 屏幕截图、键鼠控制 | [文档](https://ccb.agent-aura.top/docs/features/computer-use) |
+| Chrome Use | 浏览器自动化、表单填写、数据抓取 | [自托管](https://ccb.agent-aura.top/docs/features/chrome-use-mcp) [原生版](https://ccb.agent-aura.top/docs/features/claude-in-chrome-mcp) |
+| Sentry | 企业级错误追踪 | [文档](https://ccb.agent-aura.top/docs/internals/sentry-setup) |
+| GrowthBook | 企业级特性开关 | [文档](https://ccb.agent-aura.top/docs/internals/growthbook-adapter) |
+| /dream 记忆整理 | 自动整理和优化记忆文件 | [文档](https://ccb.agent-aura.top/docs/features/auto-dream) |
 
 - 🚀 [想要启动项目](#快速开始源码版)
 - 🐛 [想要调试项目](#vs-code-调试)
@@ -28,15 +41,15 @@
 不用克隆仓库, 从 NPM 下载后, 直接使用
 
 ```sh
-bun  i -g claude-code-best
-bun pm -g trust claude-code-best
-ccb # 直接打开 claude code
-```
+npm i -g claude-code-best
 
-⚠️ 国内对 github 网络较差的, 需要先设置这个环境变量
+# bun 安装比较多问题, 推荐 npm 装
+# bun  i -g claude-code-best
+# bun pm -g trust claude-code-best
 
-```bash
-DEFAULT_RELEASE_BASE=https://ghproxy.net/https://github.com/microsoft/ripgrep-prebuilt/releases/download/v15.0.1
+ccb # 以 nodejs 打开 claude code
+ccb-bun # 以 bun 形态打开
+CLAUDE_BRIDGE_BASE_URL=https://remote-control.claude-code-best.win/ CLAUDE_BRIDGE_OAUTH_TOKEN=test-my-key ccb --remote-control # 我们有自部署的远程控制
 ```
 
 ## ⚡ 快速开始(源码版)
@@ -54,12 +67,6 @@ DEFAULT_RELEASE_BASE=https://ghproxy.net/https://github.com/microsoft/ripgrep-pr
 bun install
 ```
 
-⚠️ 国内对 github 网络较差的,可以使用这个环境变量
-
-```bash
-DEFAULT_RELEASE_BASE=https://ghproxy.net/https://github.com/microsoft/ripgrep-prebuilt/releases/download/v15.0.1
-```
-
 ### ▶️ 运行
 
 ```bash

build.ts

@@ -11,9 +11,7 @@ rmSync(outdir, { recursive: true, force: true })
 // Default features that match the official CLI build.
 // Additional features can be enabled via FEATURE_<NAME>=1 env vars.
 const DEFAULT_BUILD_FEATURES = [
-  'BUDDY',
-  'TRANSCRIPT_CLASSIFIER',
-  'BRIDGE_MODE',
+  'BUDDY', 'TRANSCRIPT_CLASSIFIER', 'BRIDGE_MODE',
   'AGENT_TRIGGERS_REMOTE',
   'CHICAGO_MCP',
   'VOICE_MODE',
@@ -33,6 +31,23 @@ const DEFAULT_BUILD_FEATURES = [
   'ULTRAPLAN',
   // P2: daemon + remote control server
   'DAEMON',
+  // ACP (Agent Client Protocol) agent mode
+  'ACP',
+  // PR-package restored features
+  'WORKFLOW_SCRIPTS',
+  'HISTORY_SNIP',
+  'CONTEXT_COLLAPSE',
+  'MONITOR_TOOL',
+  'FORK_SUBAGENT',
+//   'UDS_INBOX',
+  'KAIROS',
+  'COORDINATOR_MODE',
+  'LAN_PIPES',
+  'BG_SESSIONS',
+  'TEMPLATES',
+  // 'REVIEW_ARTIFACT', // API 请求无响应，需进一步排查 schema 兼容性
+  // P3: poor mode (disable extract_memories + prompt_suggestion)
+  'POOR',
 ]
 
 // Collect FEATURE_* env vars → Bun.build features
@@ -78,8 +93,27 @@ for (const file of files) {
   }
 }
 
+// Also patch unguarded globalThis.Bun destructuring from third-party deps
+// (e.g. @anthropic-ai/sandbox-runtime) so Node.js doesn't crash at import time.
+let bunPatched = 0
+const BUN_DESTRUCTURE = /var \{([^}]+)\} = globalThis\.Bun;?/g
+const BUN_DESTRUCTURE_SAFE = 'var {$1} = typeof globalThis.Bun !== "undefined" ? globalThis.Bun : {};'
+for (const file of files) {
+  if (!file.endsWith('.js')) continue
+  const filePath = join(outdir, file)
+  const content = await readFile(filePath, 'utf-8')
+  if (BUN_DESTRUCTURE.test(content)) {
+    await writeFile(
+      filePath,
+      content.replace(BUN_DESTRUCTURE, BUN_DESTRUCTURE_SAFE),
+    )
+    bunPatched++
+  }
+}
+BUN_DESTRUCTURE.lastIndex = 0
+
 console.log(
-  `Bundled ${result.outputs.length} files to ${outdir}/ (patched ${patched} for Node.js compat)`,
+  `Bundled ${result.outputs.length} files to ${outdir}/ (patched ${patched} for import.meta.require, ${bunPatched} for Bun destructure)`,
 )
 
 // Step 4: Copy native .node addon files (audio-capture)
@@ -87,18 +121,17 @@ const vendorDir = join(outdir, 'vendor', 'audio-capture')
 await cp('vendor/audio-capture', vendorDir, { recursive: true })
 console.log(`Copied vendor/audio-capture/ → ${vendorDir}/`)
 
-// Step 5: Bundle download-ripgrep script as standalone JS for postinstall
-const rgScript = await Bun.build({
-  entrypoints: ['scripts/download-ripgrep.ts'],
-  outdir,
-  target: 'node',
-})
-if (!rgScript.success) {
-  console.error('Failed to bundle download-ripgrep script:')
-  for (const log of rgScript.logs) {
-    console.error(log)
-  }
-  // Non-fatal — postinstall fallback to bun run scripts/download-ripgrep.ts
-} else {
-  console.log(`Bundled download-ripgrep script to ${outdir}/`)
-}
+// Step 5: Generate cli-bun and cli-node executable entry points
+const cliBun = join(outdir, 'cli-bun.js')
+const cliNode = join(outdir, 'cli-node.js')
+
+await writeFile(cliBun, '#!/usr/bin/env bun\nimport "./cli.js"\n')
+
+await writeFile(cliNode, '#!/usr/bin/env node\nimport "./cli.js"\n')
+
+// Make both executable
+const { chmodSync } = await import('fs')
+chmodSync(cliBun, 0o755)
+chmodSync(cliNode, 0o755)
+
+console.log(`Generated ${cliBun} (shebang: bun) and ${cliNode} (shebang: node)`)

docs.json

@@ -0,0 +1,188 @@
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "theme": "mint",
+  "name": "Claude Code Architecture",
+  "colors": {
+    "primary": "#D97706",
+    "light": "#F59E0B",
+    "dark": "#B45309"
+  },
+  "favicon": "/docs/favicon.svg",
+  "navigation": {
+    "groups": [
+      {
+        "group": "开始",
+        "pages": [
+          {
+            "group": "介绍",
+            "pages": [
+              "docs/introduction/what-is-claude-code",
+              "docs/introduction/why-this-whitepaper",
+              "docs/introduction/architecture-overview"
+            ]
+          }
+        ]
+      },
+      {
+        "group": "对话是如何运转的",
+        "pages": [
+          "docs/conversation/the-loop",
+          "docs/conversation/streaming",
+          "docs/conversation/multi-turn"
+        ]
+      },
+      {
+        "group": "工具：AI 的双手",
+        "pages": [
+          "docs/tools/what-are-tools",
+          "docs/tools/file-operations",
+          "docs/tools/shell-execution",
+          "docs/tools/search-and-navigation",
+          "docs/tools/task-management"
+        ]
+      },
+      {
+        "group": "上下文工程",
+        "pages": [
+          "docs/context/system-prompt",
+          "docs/context/project-memory",
+          "docs/context/compaction",
+          "docs/context/token-budget"
+        ]
+      },
+      {
+        "group": "多 Agent 协作",
+        "pages": [
+          "docs/agent/sub-agents",
+          "docs/agent/worktree-isolation",
+          "docs/agent/coordinator-and-swarm"
+        ]
+      },
+      {
+        "group": "可扩展性",
+        "pages": [
+          "docs/extensibility/mcp-protocol",
+          "docs/extensibility/hooks",
+          "docs/extensibility/skills",
+          "docs/extensibility/custom-agents"
+        ]
+      },
+      {
+        "group": "安全与权限",
+        "pages": [
+          "docs/safety/why-safety-matters",
+          "docs/safety/permission-model",
+          "docs/safety/sandbox",
+          "docs/safety/plan-mode",
+          "docs/safety/auto-mode"
+        ]
+      },
+      {
+        "group": "揭秘：隐藏功能与内部机制",
+        "pages": [
+          "docs/internals/three-tier-gating",
+          "docs/internals/feature-flags",
+          "docs/internals/growthbook-ab-testing",
+          "docs/internals/growthbook-adapter",
+          "docs/internals/sentry-setup",
+          "docs/internals/hidden-features",
+          "docs/internals/ant-only-world",
+          "docs/features/debug-mode",
+          "docs/features/buddy"
+        ]
+      },
+      {
+        "group": "隐藏功能详解",
+        "pages": [
+          {
+            "group": "Agent 与协作",
+            "pages": [
+              "docs/features/coordinator-mode",
+              "docs/features/fork-subagent",
+              "docs/features/daemon",
+              "docs/features/teammem"
+            ]
+          },
+          {
+            "group": "运行模式",
+            "pages": [
+              "docs/features/kairos",
+              "docs/features/voice-mode",
+              "docs/features/bridge-mode",
+              "docs/features/remote-control-self-hosting",
+              "docs/features/proactive",
+              "docs/features/ultraplan"
+            ]
+          },
+          {
+            "group": "工具增强",
+            "pages": [
+              "docs/features/mcp-skills",
+              "docs/features/tree-sitter-bash",
+              "docs/features/bash-classifier",
+              "docs/features/web-browser-tool",
+              "docs/features/experimental-skill-search"
+            ]
+          },
+          {
+            "group": "上下文与自动化",
+            "pages": [
+              "docs/features/token-budget",
+              "docs/features/context-collapse",
+              "docs/features/workflow-scripts",
+              "docs/features/auto-dream"
+            ]
+          },
+          "docs/features/tier3-stubs"
+        ]
+      },
+      {
+        "group": "基础设施与依赖",
+        "pages": [
+          "docs/auto-updater",
+          "docs/lsp-integration",
+          "docs/external-dependencies",
+          "docs/telemetry-remote-config-audit"
+        ]
+      }
+    ]
+  },
+  "logo": {
+    "light": "/docs/logo/light.svg",
+    "dark": "/docs/logo/dark.svg"
+  },
+  "background": {
+    "color": {
+      "light": "#FFFFFF",
+      "dark": "#0F172A"
+    }
+  },
+  "navbar": {
+    "primary": {
+      "type": "github",
+      "href": "https://github.com/claude-code-best/claude-code"
+    }
+  },
+  "search": {
+    "prompt": "搜索 Claude Code 架构文档..."
+  },
+  "seo": {
+    "metatags": {
+      "og:image": "https://ccb.agent-aura.top/docs/images/og-cover.png",
+      "twitter:image": "https://ccb.agent-aura.top/docs/images/og-cover.png",
+      "twitter:card": "summary_large_image"
+    },
+    "indexing": "navigable"
+  },
+  "footer": {
+    "socials": {
+      "github": "https://github.com/anthropics/claude-code"
+    }
+  },
+  "redirects": [
+    {
+      "source": "/docs/introduction",
+      "destination": "/docs/introduction/what-is-claude-code"
+    }
+  ]
+}

docs/REVISION-PLAN.md

@@ -1,128 +0,0 @@
-# 文档修正计划
-
-> 目标：补充源码级洞察，让每篇文档从"概念科普"升级为"逆向工程白皮书"水准。
-
----
-
-## 第一梯队：空壳页，需要大幅重写
-
-### 1. `safety/sandbox.mdx` — 沙箱机制 ✅ DONE
-
-**现状**：35 行，只列了"文件系统/网络/进程/时间"四个维度，没有任何实现细节。
-
-**修正方向**：
-- 补充 macOS `sandbox-exec` 的实际调用方式，展示沙箱 profile 的关键片段
-- 说明 `getSandboxConfig()` 的判定逻辑：哪些命令走沙箱、哪些跳过
-- 补充 `dangerouslyDisableSandbox` 参数的设计权衡
-- 加入 Linux 平台的沙箱差异对比（seatbelt vs namespace）
-- 展示一次命令执行从权限检查→沙箱包裹→实际执行的完整链路
-
----
-
-### 2. `introduction/what-is-claude-code.mdx` — 什么是 Claude Code ✅ DONE
-
-**现状**：39 行，纯营销文案，和"普通聊天 AI"的对比表太低级。
-
-**修正方向**：
-- 砍掉"能做什么"的泛泛列表，改为一个具体的端到端示例（从用户输入→系统处理→最终输出）
-- 用一张简化架构图替代文字描述，让读者 30 秒建立直觉
-- 补充 Claude Code 的技术定位：不是 IDE 插件、不是 Web Chat，而是 terminal-native agentic system
-- 加入与 Cursor / Copilot / Aider 等工具的定位差异（架构层面而非功能清单）
-
----
-
-### 3. `introduction/why-this-whitepaper.mdx` — 为什么写这份白皮书 ✅ DONE
-
-**现状**：40 行，全是空话，四张 Card 只是后续章节标题的预告。
-
-**修正方向**：
-- 明确定位：这是对 Anthropic 官方 CLI 的逆向工程分析，不是官方文档
-- 列出逆向过程中发现的 3-5 个最意外/最精妙的设计决策（吊住读者胃口）
-- 说明白皮书的阅读路线图：推荐的阅读顺序和每个章节解决什么问题
-- 补充"这份白皮书不是什么"——不是使用教程，不是 API 文档
-
----
-
-### 4. `safety/why-safety-matters.mdx` — 为什么安全至关重要 ✅ DONE
-
-**现状**：40 行，只列了显而易见的风险，"安全 vs 效率的平衡"只有 3 个 bullet。
-
-**修正方向**：
-- 从源码角度展示安全体系的全景图：权限规则 → 沙箱 → Plan Mode → 预算上限 → Hooks 的纵深防御链
-- 补充 Claude 自身 System Prompt 中的安全指令（"执行前确认"、"优先可逆操作"等），展示 AI 端的安全约束
-- 用真实场景说明"安全 vs 效率"的工程权衡：比如 Read 工具为什么免审批、Bash 工具为什么要逐条确认
-- 加入 Prompt Injection 防御的简要说明（tool result 中的恶意内容如何被系统标记）
-
----
-
-## 第二梯队：有骨架但太浅，需要补肉
-
-### 5. `conversation/streaming.mdx` — 流式响应 ✅ DONE
-
-**现状**：43 行，只说了"流式好"和 3 行 provider 表。
-
-**修正方向**：
-- 补充 `BetaRawMessageStreamEvent` 的核心事件类型及其含义
-- 展示文本 chunk 和 tool_use block 交织的状态机流转
-- 说明流式中的错误处理：网络断开、API 限流、token 超限时的重试/降级策略
-- 补充 `processStreamEvents()` 的核心逻辑：如何从事件流中分离出文本、工具调用、usage 统计
-
----
-
-### 6. `tools/search-and-navigation.mdx` — 搜索与导航 ✅ DONE
-
-**现状**：43 行，只说 Glob 和 Grep 存在。
-
-**修正方向**：
-- 补充 ripgrep 二进制的内嵌方式（vendor 目录、平台适配）
-- 说明搜索结果的 head_limit 默认 250 的设计原因（token 预算）
-- 展示 ToolSearch 的实现：如何用语义匹配在 50+ 工具（含 MCP）中找到最相关的
-- 补充 Glob 按修改时间排序的意义：最近修改的文件最可能与当前任务相关
-
----
-
-### 7. `tools/task-management.mdx` — 任务管理 ✅ DONE
-
-**现状**：50 行，只有流程 Steps 和状态展示的 4 个 bullet。
-
-**修正方向**：
-- 补充任务的数据模型：id / subject / description / status / blockedBy / blocks / owner
-- 说明依赖管理的实现：blockedBy 如何阻止任务被认领、完成一个任务后如何自动解锁下游
-- 展示任务与 Agent 工具的联动：子 Agent 如何认领任务、报告进度
-- 补充 activeForm 字段的 UX 设计：进行中任务的 spinner 动画文案
-
----
-
-### 8. `context/token-budget.mdx` — Token 预算管理 ✅ DONE
-
-**现状**：55 行，预算控制只有 3 张 Card 各一句话。
-
-**修正方向**：
-- 补充 `contextWindowTokens` 和 `maxOutputTokens` 的动态计算逻辑
-- 说明缓存 breakpoint 的放置策略：System Prompt 中不变内容在前、变化内容在后的原因
-- 展示工具输出截断的具体机制：超长结果如何被 truncate、何时触发 micro-compact
-- 补充 token 计数的实现：`countTokens` 的调用时机和近似 vs 精确计数的权衡
-
----
-
-### 9. `agent/worktree-isolation.mdx` — Worktree 隔离 ✅ DONE
-
-**现状**：55 行，只描述了 git worktree 的概念。
-
-**修正方向**：
-- 展示 `.claude/worktrees/` 的目录结构和分支命名规则
-- 说明 worktree 的生命周期：创建时机（`isolation: "worktree"`）→ 子 Agent 执行 → 完成/放弃 → 自动清理
-- 补充 worktree 与子 Agent 的绑定关系：Agent 结束时如何判断 keep or remove
-- 加入 EnterWorktree / ExitWorktree 工具的交互设计
-
----
-
-### 10. `extensibility/custom-agents.mdx` — 自定义 Agent ✅ DONE
-
-**现状**：56 行，只有配置表和示例表。
-
-**修正方向**：
-- 展示 agent markdown 文件的完整 frontmatter 格式（name / description / model / allowedTools 等）
-- 说明 agent 如何被加载和注入 System Prompt：`loadAgentDefinitions()` 的发现和合并逻辑
-- 展示工具限制的实现：allowedTools 如何过滤工具列表
-- 补充 agent 与 subagent_type 参数的关联：Agent 工具如何指定使用自定义 Agent

docs/SITE-RESTRUCTURE-PROPOSAL.md

@@ -0,0 +1,161 @@
+# Claude Code 文档站章节重构方案
+
+> 按功能域重新组织，专有名词保留英文，其余简化为中文。
+
+---
+
+## 一、导航结构
+
+```
+开始使用
+├── 项目介绍
+├── 项目动机
+└── 架构总览
+
+核心机制
+├── Agent Loop
+├── 流式响应
+├── 多轮对话
+├── 系统提示词
+└── 深度规划
+
+上下文管理
+├── 令牌预算
+├── 上下文压缩
+├── 项目记忆
+├── 自动记忆整理
+└── 穷鬼模式
+
+工具系统
+├── 工具总览
+├── 文件操作
+├── 命令执行
+├── 搜索导航
+├── 任务管理
+├── 网页搜索
+├── 桌面自动化
+└── 浏览器控制
+
+多智能体
+├── 子智能体
+├── 自定义智能体
+├── 工作树隔离
+├── 协调模式
+├── 团队记忆
+└── 后台会话
+
+MCP
+└── MCP 详解
+
+Hook 与 Plugin
+├── Hook 钩子
+├── 插件市场
+└── LSP 集成
+
+Skills
+├── Skill 技能系统
+├── Workflow 脚本
+└── Skill 搜索
+
+远程控制
+├── 远程控制
+├── ACP 接入
+├── 消息通道
+├── 本地通信
+└── 常驻助手
+
+安全机制
+├── 安全概述
+├── 权限模型
+├── 沙箱
+├── Bash 检查
+├── 规划模式
+└── 自动模式
+
+额外功能
+├── 特性开关
+├── A/B 测试与配置
+├── 错误追踪
+├── 隐藏功能
+├── Buddy 助手
+├── 命令分类
+└── 语音模式
+
+开发人员
+├── 可观测性
+├── 调试模式
+└── 专属特性
+
+基础设施
+├── 守护进程
+└── 自动更新
+
+附录
+├── 任务追踪
+├── 测试计划
+└── 设计文档
+```
+
+---
+
+## 二、标题映射
+
+| 导航标题 | 新文件路径 | 合并来源 |
+|---------|-----------|---------|
+| 项目介绍 | docs/introduction/what-is-claude-code | （不变） |
+| 项目动机 | docs/introduction/why-this-whitepaper | （不变） |
+| 架构总览 | docs/introduction/architecture-overview | （不变） |
+| Agent Loop | docs/conversation/the-loop | （不变） |
+| 流式响应 | docs/conversation/streaming | （不变） |
+| 多轮对话 | docs/conversation/multi-turn | （不变） |
+| 系统提示词 | docs/context/system-prompt | （不变） |
+| 语音模式 | docs/features/voice-mode | （不变） |
+| 深度规划 | docs/features/ultraplan | （不变） |
+| 令牌预算 | docs/context/token-budget | （不变） |
+| 上下文压缩 | docs/context/compaction | （不变） |
+| 项目记忆 | docs/context/project-memory | （不变） |
+| 自动记忆整理 | docs/features/auto-dream | （不变） |
+| 穷鬼模式 | （新写） | — |
+| 工具总览 | docs/tools/what-are-tools | （不变） |
+| 文件操作 | docs/tools/file-operations | （不变） |
+| 命令执行 | docs/tools/shell-execution | （不变） |
+| 搜索导航 | docs/tools/search-and-navigation | （不变） |
+| 任务管理 | docs/tools/task-management | （不变） |
+| 网页搜索 | docs/features/web-search-tool | （不变） |
+| 桌面自动化 | docs/features/computer-use | （不变） |
+| 浏览器控制 | docs/features/claude-in-chrome-mcp | （不变） |
+| 子智能体 | docs/agent/sub-agents | ← sub-agents + features/fork-subagent |
+| 自定义智能体 | docs/extensibility/custom-agents | （不变） |
+| 工作树隔离 | docs/agent/worktree-isolation | （不变） |
+| 协调模式 | docs/agent/coordinator-and-swarm | （不变） |
+| 团队记忆 | docs/features/teammem | （不变） |
+| 后台会话 | docs/features/pipes-and-lan | （不变） |
+| MCP 详解 | docs/extensibility/mcp | ← extensibility/mcp-protocol + extensibility/mcp-configuration + features/mcp-skills |
+| 插件市场 | （新写） | — |
+| Hook 钩子 | docs/extensibility/hooks | （不变） |
+| Skill 技能系统 | docs/extensibility/skills | （不变） |
+| Workflow 脚本 | docs/features/workflow-scripts | （不变） |
+| Skill 搜索 | docs/features/experimental-skill-search | （不变） |
+| 远程控制 | docs/features/remote-control | ← features/bridge-mode + features/remote-control-self-hosting |
+| ACP 接入 | docs/features/acp-link | （不变） |
+| 消息通道 | docs/features/channels | （不变） |
+| 本地通信 | docs/features/proactive | （不变） |
+| 常驻助手 | docs/features/kairos | ← features/proactive + features/kairos |
+| 安全概述 | docs/safety/why-safety-matters | （不变） |
+| 权限模型 | docs/safety/permission-model | （不变） |
+| 沙箱 | docs/safety/sandbox | （不变） |
+| Bash 检查 | docs/features/tree-sitter-bash | ← features/tree-sitter-bash + features/bash-classifier |
+| 规划模式 | docs/safety/plan-mode | （不变） |
+| 自动模式 | docs/safety/auto-mode | （不变） |
+| 特性开关 | docs/internals/feature-flags | （不变） |
+| A/B 测试与配置 | docs/internals/growthbook | ← internals/growthbook-ab-testing + internals/growthbook-adapter |
+| 错误追踪 | docs/internals/sentry-setup | （不变） |
+| 隐藏功能 | docs/internals/hidden-features | （不变） |
+| 专属特性 | docs/internals/ant-only-world | （不变，移至开发人员） |
+| 调试模式 | docs/features/debug-mode | （不变，移至开发人员） |
+| Buddy 助手 | docs/features/buddy | （不变） |
+| 命令分类 | docs/features/bash-classifier | （不变） |
+| 可观测性 | docs/features/langfuse-monitoring | （不变） |
+| 守护进程 | docs/features/daemon | （不变） |
+| 自动更新 | docs/auto-updater | （不变） |
+| LSP 集成 | docs/lsp-integration | （不变） |

docs/agent/coordinator-and-swarm.mdx

@@ -1,196 +1,101 @@
 ---
-title: "协调者与蜂群模式 - 多 Agent 高级编排"
-description: "从源码角度解析 Claude Code 多 Agent 协作：Coordinator Mode 的 System Prompt 设计、Worker 生命周期、Task 通信协议和 Swarm 蜂群的任务分配机制。"
+title: "协调者与蜂群"
+description: "两种多 Agent 协作模式：Coordinator 的星型编排和 Swarm 的竞争认领。理解各自的设计权衡和适用场景。"
 keywords: ["协调者模式", "蜂群模式", "Agent Swarm", "多 Agent 协作", "任务编排"]
 ---
 
-{/* 本章目标：从源码角度揭示 Coordinator Mode 和 Agent Swarms 的架构设计 */}
+## 核心问题
 
-## 两种协作模式的架构差异
+单个 AI Agent 的上下文窗口有限。当任务复杂到需要同时理解多个模块、执行多个并行操作时，单个 Agent 会力不从心。
+
+多 Agent 协作的目标：让多个 AI Agent 分工合作，各自拥有独立的上下文窗口，协同完成复杂任务。
+
+## 两种协作模式
 
 | 维度 | Coordinator Mode | Agent Swarms |
 |------|-----------------|--------------|
-| **门控** | `feature('COORDINATOR_MODE')` + `CLAUDE_CODE_COORDINATOR_MODE=1` | 任务系统 V2（默认启用） |
-| **拓扑** | 星型：Coordinator 居中，Worker 外围 | 网状：对等 Agent 共享任务列表 |
-| **角色** | 明确分工：Coordinator 编排、Worker 执行 | 模糊：每个 Agent 自主认领任务 |
-| **通信** | `SendMessage` 定向通信 + `<task-notification>` | 任务文件系统 + 邮箱广播 |
-| **适用** | 需要集中决策的复杂任务 | 并行度高的独立子任务 |
+| **拓扑** | 星型：Coordinator 居中编排 | 星型 + P2P：Teammate 间可直接通信 |
+| **角色** | Coordinator 理解决策，Worker 执行 | Team Lead 协调，Teammate 自主认领 |
+| **适用** | 需要集中决策的复杂任务 | 并行度高、任务独立的场景 |
 
-两者不是互斥的——Coordinator Mode 可以在 Swarm 架构之上运行，将 Coordinator 作为特殊的 Leader Agent。
+两者不是互斥的——可以组合使用，但那属于高级用法。
 
-## Coordinator Mode：星型编排架构
+## Coordinator Mode：先理解，再分配
 
-### 激活机制
+### 设计哲学
 
-```typescript
-// src/coordinator/coordinatorMode.ts:36
-export function isCoordinatorMode(): boolean {
-  if (feature('COORDINATOR_MODE')) {
-    return isEnvTruthy(process.env.CLAUDE_CODE_COORDINATOR_MODE)
-  }
-  return false  // 外部构建始终 false
-}
-```
+Coordinator Mode 最核心的约束：**Coordinator 必须先理解问题，再分配任务。**
 
-Coordinator Mode 需要双重门控：构建时 `feature('COORDINATOR_MODE')` 和运行时环境变量。`matchSessionMode()` 在会话恢复时自动同步模式状态——如果恢复的会话是 coordinator 模式，它会翻转环境变量以确保一致性。
-
-### Coordinator 的工具集
-
-Coordinator 被剥夺了所有"动手"工具，只保留编排能力：
-
-| 工具 | 用途 |
-|------|------|
-| **Agent** | 启动新 Worker（`subagent_type: "worker"`） |
-| **SendMessage** | 向已有 Worker 发送后续指令 |
-| **TaskStop** | 中途停止走错方向的 Worker |
-| **subscribe_pr_activity** | 订阅 GitHub PR 事件（review comments、CI 结果） |
-
-Coordinator **不写代码、不读文件、不执行命令**——它只做三件事：理解需求、分配任务、综合结果。
-
-### Worker 的工具权限
-
-Worker 的可用工具由 `getCoordinatorUserContext()`（`coordinatorMode.ts:80`）动态注入到 System Prompt：
-
-```typescript
-// 简化模式下：只有 Bash + Read + Edit
-const workerTools = isEnvTruthy(process.env.CLAUDE_CODE_SIMPLE')
-  ? [BASH_TOOL_NAME, FILE_READ_TOOL_NAME, FILE_EDIT_TOOL_NAME]
-  : Array.from(ASYNC_AGENT_ALLOWED_TOOLS)
-      .filter(name => !INTERNAL_WORKER_TOOLS.has(name))
-```
-
-`INTERNAL_WORKER_TOOLS`（TeamCreate、TeamDelete、SendMessage、SyntheticOutput）被显式排除——Worker 不能嵌套创建团队或发送消息，防止不可控的递归。
-
-### Scratchpad：跨 Worker 的共享知识库
-
-当 `tengu_scratch` feature flag 启用时，Coordinator 拥有一个 Scratchpad 目录：
-
-```
-Scratchpad 目录：
-  - Workers 可自由读写，无需权限审批
-  - 用于持久化的跨 Worker 知识
-  - 结构由 Coordinator 决定（无固定格式）
-```
-
-这是一个关键的协作原语——Worker A 的研究结果可以写入 Scratchpad，Worker B 直接读取，无需通过 Coordinator 中转。
-
-### `<task-notification>` 通信协议
-
-Worker 完成后，Coordinator 收到 XML 格式的通知：
-
-```xml
-<task-notification>
-  <task-id>agent-a1b</task-id>          ← Worker 的 agentId
-  <status>completed|failed|killed</status>
-  <summary>Agent "Investigate auth bug" completed</summary>
-  <result>Found null pointer in src/auth/validate.ts:42...</result>
-  <usage>
-    <total_tokens>N</total_tokens>
-    <tool_uses>N</tool_uses>
-    <duration_ms>N</duration_ms>
-  </usage>
-</task-notification>
-```
-
-通知以 `user-role message` 形式送达，Coordinator 通过 `<task-notification>` 标签区分它和用户消息。`<task-id>` 用于 `SendMessage` 的 `to` 参数，实现定向续传。
-
-### Coordinator 的核心职责：综合（Synthesis）
-
-Coordinator System Prompt（`coordinatorMode.ts:111-369`，约 260 行）明确要求 Coordinator **不能懒惰地委派理解**：
-
-```
 反模式（禁止）：
-  "Based on your findings, fix the auth bug"
-  → 把理解的责任推给了 Worker
+> "Based on your findings, fix the auth bug" — 把理解的责任推给了 Worker
 
 正确做法：
-  "Fix the null pointer in src/auth/validate.ts:42.
-   The user field on Session (src/auth/types.ts:15) is
-   undefined when sessions expire but the token remains cached.
-   Add a null check before user.id access."
-  → Coordinator 自己理解了问题，给出精确指令
-```
+> "Fix the null pointer in src/auth/validate.ts:42. The user field is undefined when sessions expire but the token remains cached." — Coordinator 自己理解了问题，给出精确指令
 
-这是 Coordinator Mode 最核心的设计约束：Coordinator 必须先理解，再分配。
+**设计考量**：如果 Coordinator 不理解问题就分配任务，Worker 会因为缺乏上下文而做出错误的决策。Coordinator 的理解质量直接决定了 Worker 的执行质量。
 
-## Agent Swarms：蜂群式协作
+### Coordinator 的工具限制
 
-Swarm 模式基于任务系统 V2（详见[任务管理](../tools/task-management.mdx)），核心机制是**共享任务列表 + 竞争认领**：
+Coordinator 被剥夺了所有"动手"工具——不写代码、不读文件、不执行命令。只保留编排能力：启动 Worker、发送指令、停止走错方向的 Worker。
 
-### 团队初始化
+**设计洞察**：限制工具不是能力的削弱，而是职责的清晰化。Coordinator 专注于"想"，Worker 专注于"做"。如果 Coordinator 也能动手，它很容易跳过编排直接自己干，失去了多 Agent 的意义。
 
-```
-Leader 创建团队（TeamCreateTool）
-  ↓
-设置 teamName → setLeaderTeamName()
-  ↓
-所有 teammate 自动获得相同的 taskListId
-  ↓
-teammate 启动时：
-  1. CLAUDE_CODE_TASK_LIST_ID 环境变量（显式覆盖）
-  2. teammate 上下文的 teamName（共享 leader 的任务列表）
-  3. CLAUDE_CODE_TEAM_NAME 环境变量
-  4. leader 设置的 teamName
-  5. getSessionId()（兜底）
-```
+### Scratchpad：跨 Worker 共享知识
 
-多级优先级确保了 Leader 和所有 Teammate 指向同一个任务列表，无需额外协调。
+Workers 共享一个 Scratchpad 目录，可以自由读写。Worker A 的研究结果可以写入 Scratchpad，Worker B 直接读取，无需通过 Coordinator 中转。
 
-### 任务认领与竞争
+**设计考量**：不是所有知识都需要通过 Coordinator 中转。中间结果（如搜索结果、分析报告）适合 Worker 间直接共享，只有最终结论和决策才需要 Coordinator 参与。
 
-`claimTask()` 是 Swarm 的核心并发原语：
+### 通信协议
 
-```
-Teammate A 调用 TaskList → 发现 task #3 是 pending
-Teammate B 同时发现 task #3 是 pending
-  ↓
-两者同时尝试 TaskUpdate(task #3, {status: "in_progress"})
-  ↓
-文件锁 + 高水位标记保证原子性：
-  - 第一个写入者获得 owner 锁定
-  - 第二个写入者收到 already_claimed 错误
-  ↓
-获得任务的 teammate 执行工作
-  ↓
-完成后 TaskUpdate(task #3, {status: "completed"})
-  → 依赖此任务的其他任务自动解锁
-  → tool_result 提示 "Call TaskList to find your next task"
-```
+Worker 完成后，Coordinator 收到结构化通知，包含状态、结果摘要和 token 使用统计。Coordinator 可以向任何 Worker 发送后续指令，实现"分配 → 执行 → 反馈 → 追加"的循环。
 
-### Teammate 的生命周期管理
+## Agent Teams (Swarm)：竞争认领
 
-```
-Teammate 异常退出
-  ↓
-unassignTeammateTasks()
-  → 扫描任务列表，找到 owner === teammateName 的未完成任务
-  → 重置为 pending + owner=undefined
-  ↓
-Leader 通过 mailbox 收到通知
-  → 重新分配或创建新 Teammate
-```
+### 设计哲学
 
-## 任务类型全景
+Swarm 基于一个简单的假设：**如果任务列表是共享的、可见的，多个 Agent 会自然地分工合作。**
 
-支撑多 Agent 协作的是 7 种任务类型（`src/tasks/types.ts`）：
+不需要一个中央调度器——每个 Teammate 看到任务列表，自己决定认领哪个任务。这和人类团队的工作方式一致：站会上大家看到看板，自己选择下一步做什么。
 
-| 任务类型 | 运行位置 | 状态管理 | 适用场景 |
-|----------|---------|---------|---------|
-| **LocalAgentTask** | 本地子进程 | `LocalAgentTaskState` | 标准子 Agent 任务 |
-| **LocalShellTask** | 本地 shell | `LocalShellTaskState` | 后台 shell 命令 |
-| **InProcessTeammateTask** | 同进程内 | `InProcessTeammateTaskState` | 轻量级进程内队友 |
-| **RemoteAgentTask** | 远程服务器 | `RemoteAgentTaskState` | 分布式 Agent（CCR） |
-| **DreamTask** | 后台静默 | `DreamTaskState` | 后台自主整理记忆 |
-| **LocalWorkflowTask** | 本地 | `LocalWorkflowTaskState` | 工作流编排 |
-| **MonitorMcpTask** | 本地 | `MonitorMcpTaskState` | MCP 监控任务 |
+### 核心机制
 
-`InProcessTeammateTask` 与 `LocalAgentTask` 的关键差异：前者共享进程的内存空间和基础设施状态（如 MCP 连接池），但有独立的对话上下文和工具权限；后者是完全隔离的子进程，启动开销更大但更安全。
+| 机制 | 说明 |
+|------|------|
+| **共享任务列表** | 所有 Teammate 看到同一个任务池 |
+| **竞争认领** | 第一个锁定任务的 Teammate 获得执行权 |
+| **Mailbox 消息** | Teammate 间可直接通信，无需经过 Lead |
+| **异常恢复** | Teammate 崩溃后，其未完成任务被自动重置 |
 
-## Coordinator vs Swarm 的选择
+### 竞争认领的并发安全
+
+两个 Teammate 可能同时想认领同一个任务。文件锁保证原子性——第一个写入者获得锁定，第二个收到 `already_claimed` 错误后选择下一个任务。
+
+**设计考量**：竞争是特性而非缺陷。它确保任务自然地分配给最先空闲的 Agent，不需要中央调度。但需要防止"饿死"——如果某个 Agent 总是慢半拍，它可能永远抢不到任务。实践中这个问题不严重，因为 AI Agent 的执行速度差异不大。
+
+### Teammate 的生命周期
+
+Teammate 异常退出时，其未完成任务被自动重置为无主状态。Team Lead 通过共享任务列表或空闲通知感知到变化，可以重新分配或创建新 Teammate。
+
+**设计哲学**：单个 Agent 的崩溃不应该阻塞整个团队。任务系统保证工作不会因为个别 Agent 的失败而丢失。
+
+### 当前限制
+
+- 不支持嵌套团队（Teammate 不能创建子团队）
+- 每会话一个团队
+- Lead 固定不可更换
+
+## 模式选择指南
 
 | 场景 | 推荐模式 | 原因 |
 |------|---------|------|
 | "重构认证系统，需要多模块协调" | Coordinator | 需要集中决策，Worker 间有依赖 |
-| "修复 10 个独立的 lint 警告" | Swarm | 任务独立，可完全并行 |
+| "修复 10 个独立的 lint 警告" | Swarm | 任务独立，Teammate 可完全并行 |
 | "研究方案 A 和方案 B，然后选一个实现" | Coordinator | 先并行研究，再集中决策 |
 | "在大仓库中搜索所有 TODO 并分类" | Swarm | 无依赖，各自领任务即可 |
+
+## 接下来
+
+- **子 Agent** — 理解单个子 Agent 的创建和生命周期
+- **Worktree 隔离** — 理解多 Agent 的文件系统隔离
+- **任务管理** — 理解支撑协作的任务系统

docs/agent/sub-agents.mdx

@@ -1,194 +1,110 @@
 ---
-title: "子 Agent 机制 - AgentTool 的执行链路与隔离架构"
-description: "从源码角度解析 Claude Code 子 Agent：AgentTool.call() 的完整执行链路、Fork 子进程的 Prompt Cache 共享、Worktree 隔离、工具池独立组装、以及结果回传的数据格式。"
-keywords: ["子 Agent", "AgentTool", "任务委派", "forkSubagent", "子进程隔离"]
+title: "子 Agent"
+description: "主 Agent 可以启动子 Agent 来并行工作或委派专业任务。理解三种子 Agent 路径、工具池隔离、Fork 的缓存优化和异步生命周期管理。"
+keywords: ["子 Agent", "AgentTool", "任务委派", "子进程隔离"]
 ---
 
-{/* 本章目标：从源码角度揭示子 Agent 的完整执行链路、工具隔离、通信协议和生命周期管理 */}
+## 核心问题
 
-## 执行链路总览
+单个 Agent 的上下文窗口是有限的。当需要同时研究多个方向、并行执行多个操作时，一个 Agent 做不过来。
 
-一条 `Agent(prompt="修复 bug")` 调用的完整路径：
+子 Agent 让主 Agent 可以启动独立的 AI 实例来并行工作——每个子 Agent 有自己的上下文窗口和工具集。
+
+## 三种子 Agent 路径
+
+系统根据参数和配置走三条不同的路径：
+
+| 路径 | 触发条件 | 上下文 | 设计目的 |
+|------|---------|--------|---------|
+| **命名 Agent** | 指定 `subagent_type` | 仅任务描述 | 专业任务委派 |
+| **Fork 子进程** | 启用 Fork + 未指定类型 | 继承父 Agent 完整对话 | Prompt Cache 优化 |
+| **通用回退** | 未启用 Fork + 未指定类型 | 仅任务描述 | 通用任务处理 |
+
+### 命名 Agent：专业委派
+
+系统预定义了几个内置 Agent，各有明确的职责：
+
+| Agent | 模型 | 工具 | 用途 |
+|-------|------|------|------|
+| **Explore** | Haiku（轻量快速） | 只读（Read/Grep/Glob） | 代码库搜索与探索 |
+| **Plan** | 继承父模型 | 只读 | 为 Plan Mode 收集信息 |
+| **General-purpose** | 继承父模型 | 全部工具 | 复杂通用任务 |
+
+**设计考量**：Explore Agent 使用 Haiku 模型（更便宜、更快），因为搜索任务不需要 Opus 的推理能力。模型选择是成本和能力的权衡——不是每个子任务都需要最强的模型。
+
+### Fork 子进程：缓存优化
+
+Fork 路径的核心设计是 **Prompt Cache 共享**：所有 fork 子进程共享父 Agent 的完整对话历史，只有最后的指令不同。这使得 API 请求的前缀完全一致，最大化缓存命中。
+
+**为什么不用命名 Agent**？命名 Agent 只拿到任务描述，缺乏父 Agent 的完整上下文。Fork 让子进程"看到"父 Agent 看到的一切，代价是更高的 token 消耗——但通过 Prompt Cache，这部分消耗被大幅降低。
+
+Fork 有两道防线防止递归创建子 Agent：检查查询来源标记和扫描消息中的特殊标签。
+
+### 模型解析优先级
+
+子 Agent 的模型选择遵循优先级链：
 
 ```
-AI 生成 tool_use: { prompt: "修复 bug", subagent_type: "Explore" }
-  ↓
-AgentTool.call()                              ← 入口（AgentTool.tsx:239）
-  ├── 解析 effectiveType（fork vs 命名 agent）
-  ├── filterDeniedAgents()                    ← 权限过滤
-  ├── 检查 requiredMcpServers                 ← MCP 依赖验证（最长等 30s）
-  ├── assembleToolPool(workerPermissionContext) ← 独立组装工具池
-  ├── createAgentWorktree()                   ← 可选 worktree 隔离
-  ↓
-runAgent()                                    ← 核心执行（runAgent.ts:248）
-  ├── getAgentSystemPrompt()                  ← 构建 agent 专属 system prompt
-  ├── initializeAgentMcpServers()             ← agent 级 MCP 服务器
-  ├── executeSubagentStartHooks()             ← Hook 注入
-  ├── query()                                 ← 进入标准 agentic loop
-  │   ├── 消息流逐条 yield
-  │   └── recordSidechainTranscript()         ← JSONL 持久化
-  ↓
-finalizeAgentTool()                           ← 结果汇总
-  ├── 提取文本内容 + usage 统计
-  └── mapToolResultToToolResultBlockParam()   ← 格式化为 tool_result
+环境变量覆盖 > 每次调用参数 > Agent 定义的模型 > 继承父对话模型
 ```
 
-## 两种子 Agent 路径：命名 Agent vs Fork
+`inherit` 不是简单的模型传递——它经过运行时解析，确保 plan mode 下的模型映射正确生效。
 
-`AgentTool.call()` 根据是否提供 `subagent_type` 走两条完全不同的路径（`AgentTool.tsx:322-356`）：
+## 工具池隔离
 
-| 维度 | 命名 Agent（`subagent_type` 指定） | Fork 子进程（`subagent_type` 省略） |
-|------|-------------------------------------|--------------------------------------|
-| **触发条件** | `subagent_type` 有值 | `isForkSubagentEnabled()` && 未指定类型 |
-| **System Prompt** | Agent 自身的 `getSystemPrompt()` | 继承父 Agent 的完整 System Prompt |
-| **工具池** | `assembleToolPool()` 独立组装 | 父 Agent 的原始工具池（`useExactTools: true`） |
-| **上下文** | 仅任务描述 | 父 Agent 的完整对话历史（`forkContextMessages`） |
-| **模型** | 可独立指定 | 继承父模型（`model: 'inherit'`） |
-| **权限模式** | Agent 定义的 `permissionMode` | `'bubble'`（上浮到父终端） |
-| **目的** | 专业任务委派 | Prompt Cache 命中率优化 |
+子 Agent 不继承父 Agent 的工具限制——它的工具池完全独立组装。
 
-Fork 路径的设计核心是 **Prompt Cache 共享**：所有 fork 子进程共享父 Agent 的完整 `assistant` 消息（所有 `tool_use` 块），用相同的占位符 `tool_result` 填充，只有最后一个 `text` 块包含各自的指令。这使得 API 请求前缀字节完全一致，最大化缓存命中。
+**设计考量**：父 Agent 可能处于受限模式（如 Plan Mode），但子 Agent 可能需要完整的工具集来执行任务。独立的工具池让子 Agent 的权限不受父 Agent 限制。
 
-```typescript
-// forkSubagent.ts:142 — 所有 fork 子进程的占位结果
-const FORK_PLACEHOLDER_RESULT = 'Fork started — processing in background'
+Fork 子进程例外——它直接继承父 Agent 的工具池，以保持 Prompt Cache 中工具定义的字节一致性。
 
-// buildForkedMessages() 构建：
-// [assistant(全量 tool_use), user(placeholder_results..., 子进程指令)]
+### Agent 级 MCP 服务器
+
+子 Agent 可以额外连接专属的 MCP 服务器。如果 Agent 声明了 `requiredMcpServers`，系统会等待这些服务器连接完成（最长 30 秒），确保工具可用后才启动。
+
+## Worktree 隔离
+
+`isolation: "worktree"` 参数让子 Agent 在独立的 git worktree 中工作：
+
+```
+创建 worktree → 子 Agent 在独立副本中工作 → 完成
+  → 有变更：保留 worktree，返回路径
+  → 无变更：自动删除
 ```
 
-### Fork 递归防护
+**设计目的**：子 Agent 的实验性修改不应该影响主分支。Worktree 提供了文件系统级别的隔离，同时保持对完整代码库的访问。
 
-Fork 子进程保留 Agent 工具（为了 cache-identical tool defs），但通过两道防线防止递归 fork（`AgentTool.tsx:332`）：
-
-1. **`querySource` 检查**（压缩安全）：`context.options.querySource === 'agent:builtin:fork'`
-2. **消息扫描**（降级兜底）：检测 `<fork-boilerplate>` 标签
-
-## 工具池的独立组装
-
-子 Agent 不继承父 Agent 的工具限制——它的工具池完全独立组装（`AgentTool.tsx:573-577`）：
-
-```typescript
-const workerPermissionContext = {
-  ...appState.toolPermissionContext,
-  mode: selectedAgent.permissionMode ?? 'acceptEdits'
-}
-const workerTools = assembleToolPool(workerPermissionContext, appState.mcp.tools)
-```
-
-关键设计决策：
-- **权限模式独立**：子 Agent 使用 `selectedAgent.permissionMode`（默认 `acceptEdits`），不受父 Agent 当前模式的限制
-- **MCP 工具继承**：`appState.mcp.tools` 包含所有已连接的 MCP 工具，子 Agent 自动获得
-- **Agent 级 MCP 服务器**：`runAgent()` 中的 `initializeAgentMcpServers()` 可以为特定 Agent 额外连接专属 MCP 服务器
-
-### 工具过滤的 resolveAgentTools
-
-`runAgent.ts:500-502` 在工具组装后进一步过滤：
-
-```typescript
-const resolvedTools = useExactTools
-  ? availableTools                           // Fork: 直接使用父工具
-  : resolveAgentTools(agentDefinition, availableTools, isAsync).resolvedTools
-```
-
-`resolveAgentTools()` 会根据 Agent 定义中的 `tools` 字段过滤可用工具，将 `['*']` 映射为全量工具。
-
-## Worktree 隔离机制
-
-`isolation: "worktree"` 参数让子 Agent 在独立的 git worktree 中工作（`AgentTool.tsx:590-593`）：
-
-```typescript
-const slug = `agent-${earlyAgentId.slice(0, 8)}`
-worktreeInfo = await createAgentWorktree(slug)
-```
-
-Worktree 生命周期：
-1. **创建**：在 `.git/worktrees/` 下创建独立工作副本
-2. **CWD 覆盖**：`runWithCwdOverride(worktreePath, fn)` 让所有文件操作在 worktree 中执行
-3. **路径翻译**：Fork + worktree 时注入路径翻译通知（`buildWorktreeNotice`）
-4. **清理**（`cleanupWorktreeIfNeeded`）：
-   - Hook-based worktree → 始终保留
-   - 有变更 → 保留，返回 `worktreePath`
-   - 无变更 → 自动删除
-
-## 生命周期管理：同步 vs 异步
+## 生命周期：同步 vs 异步
 
 ### 异步 Agent（后台运行）
 
-当 `run_in_background=true` 或 `selectedAgent.background=true` 时，Agent 立即返回 `async_launched` 状态（`AgentTool.tsx:686-764`）：
+异步 Agent 立即返回 `async_launched` 状态，主 Agent 可以继续工作。后台 Agent 完成后通过通知机制汇报结果。
 
-```
-registerAsyncAgent(agentId, ...)      ← 注册到 AppState.tasks
-  ↓ (void — 火后不管)
-runAsyncAgentLifecycle()              ← 后台执行
-  ├── runAgent().onCacheSafeParams    ← 进度摘要初始化
-  ├── 消息流迭代
-  ├── completeAsyncAgent()            ← 标记完成
-  ├── classifyHandoffIfNeeded()       ← 安全检查
-  └── enqueueAgentNotification()      ← 通知主 Agent
-```
-
-异步 Agent 获得独立的 `AbortController`，不与父 Agent 共享——用户按 ESC 取消主线程不会杀掉后台 Agent。
+异步 Agent 获得独立的 AbortController——用户取消主线程不会杀掉后台 Agent。这确保长时间运行的构建/测试任务不会被意外中断。
 
 ### 同步 Agent（前台运行）
 
-同步 Agent 的关键特性是 **可后台化**（`AgentTool.tsx:818-833`）：
-
-```typescript
-const registration = registerAgentForeground({
-  autoBackgroundMs: getAutoBackgroundMs() || undefined  // 默认 120s
-})
-backgroundPromise = registration.backgroundSignal.then(...)
-```
-
-在 agentic loop 的每次迭代中，系统用 `Promise.race` 竞争下一条消息和后台化信号：
-
-```typescript
-const raceResult = await Promise.race([
-  nextMessagePromise.then(r => ({ type: 'message', result: r })),
-  backgroundPromise  // 超过 autoBackgroundMs 触发
-])
-```
-
-后台化后，前台迭代器被终止（`agentIterator.return()`），新的 `runAgent()` 以 `isAsync: true` 重新启动，当前台的输出文件继续写入。
-
-## 结果回传格式
-
-`mapToolResultToToolResultBlockParam()` 根据状态返回不同格式（`AgentTool.tsx:1298-1375`）：
-
-| 状态 | 返回内容 |
-|------|---------|
-| `completed` | 内容 + `<usage>` 块（token/tool_calls/duration） |
-| `async_launched` | agentId + outputFile 路径 + 操作指引 |
-| `teammate_spawned` | agent_id + name + team_name |
-| `remote_launched` | taskId + sessionUrl + outputFile |
-
-对于一次性内置 Agent（Explore、Plan），`<usage>` 块被省略——每周节省约 1-2 Gtok 的上下文窗口。
-
-## MCP 依赖的等待机制
-
-如果 Agent 声明了 `requiredMcpServers`，`call()` 会等待这些服务器连接完成（`AgentTool.tsx:371-410`）：
-
-```typescript
-const MAX_WAIT_MS = 30_000     // 最长等 30 秒
-const POLL_INTERVAL_MS = 500   // 每 500ms 轮询
-```
-
-早期退出条件：任何必需服务器进入 `failed` 状态时立即停止等待。工具可用性通过 `mcp__` 前缀工具名解析（`mcp__serverName__toolName`）判断。
+同步 Agent 有一个"可后台化"机制：如果执行超过阈值（默认 120 秒），系统自动将其转为后台运行。这防止了一个慢子 Agent 阻塞整个工作循环。
 
 ## 适用场景
 
 <CardGroup cols={2}>
   <Card title="并行研究" icon="magnifying-glass">
-    多个 fork 子进程并行搜索不同方向，共享 Prompt Cache 前缀，只有指令不同
+    多个 fork 子进程并行搜索不同方向，共享 Prompt Cache 前缀
   </Card>
   <Card title="专业委派" icon="code-branch">
-    使用命名 Agent（Explore/Plan/verification）执行专业任务，受限工具集 + 独立权限
+    使用命名 Agent 执行专业任务，受限工具集 + 独立权限
   </Card>
   <Card title="隔离实验" icon="flask">
-    `isolation: "worktree"` 在独立工作副本中尝试方案，不影响主分支
+    worktree 隔离中尝试方案，不影响主分支
   </Card>
   <Card title="后台构建" icon="layer-group">
-    `run_in_background: true` 启动长时间构建/测试任务，主 Agent 继续工作
+    异步启动长时间构建/测试，主 Agent 继续工作
   </Card>
 </CardGroup>
+
+## 接下来
+
+- **协调者与蜂群** — 理解多 Agent 的高级编排模式
+- **Worktree 隔离** — 深入理解文件系统隔离机制
+- **任务管理** — 理解支撑多 Agent 的任务追踪

docs/agent/worktree-isolation.mdx

@@ -1,180 +1,99 @@
 ---
-title: "Worktree 隔离 - Git Worktree 实现文件级隔离"
-description: "揭秘 Claude Code 的 git worktree 隔离机制：子 Agent 如何获得独立工作空间，worktree 创建/销毁生命周期、路径命名规则和安全防护。"
+title: "Worktree 隔离"
+description: "多 Agent 并行工作时，共享同一目录会导致冲突。Git worktree 提供文件系统级隔离，让每个 Agent 拥有独立的工作空间。"
 keywords: ["Worktree", "git worktree", "文件隔离", "多 Agent 隔离", "并行安全"]
 ---
 
-{/* 本章目标：揭示 worktree 的创建/销毁生命周期、路径命名规则、hook 机制和退出时的安全防护 */}
-
-## 为什么需要文件级隔离
+## 核心问题
 
 多 Agent 并行工作时，共享同一工作目录会导致三类冲突：
 
-1. **写入冲突**：两个 Agent 同时编辑 `config.ts`，后写的覆盖前写的
+1. **写入冲突**：两个 Agent 同时编辑同一个文件，后写的覆盖前写的
 2. **状态干扰**：Agent A 的测试依赖某个环境状态，Agent B 的修改破坏了它
 3. **不可区分**：半完成的修改混在一起，无法分辨哪些是哪个 Agent 的
 
 Git worktree 是 git 原生的解决方案——在同一个仓库中创建多个独立工作目录，每个在自己的分支上。
 
-## 目录结构与命名规则
-
-Worktree 文件统一存放在仓库根目录下的 `.claude/worktrees/`：
+## 目录结构
 
 ```
 <repo-root>/
 ├── .claude/
 │   └── worktrees/
-│       ├── fix-auth-bug/          # worktree 工作目录
-│       │   ├── .git               # 指向主仓库的链接文件
-│       │   └── src/...            # 独立的文件系统视图
-│       └── add-dark-mode/         # 另一个 worktree
+│       ├── fix-auth-bug/          ← Agent A 的独立工作空间
+│       │   └── .git               ← 指向主仓库的链接
+│       └── add-dark-mode/         ← Agent B 的独立工作空间
 │           └── ...
-├── src/                           # 主工作目录（不受影响）
-└── .git/                          # 主仓库
+├── src/                           ← 主工作目录（不受影响）
+└── .git/                          ← 主仓库
 ```
 
-分支命名规则为 `worktree/<slug>`，其中 slug 由 `validateWorktreeSlug()` 校验：每个 `/` 分隔的段只允许字母、数字、`.`、`_`、`-`，总长 ≤64 字符。未指定时使用 plan slug 自动生成。
+每个 worktree 是一个完整的文件系统视图，但共享同一个 git 历史。Agent 在自己的 worktree 中修改文件，不会影响主分支或其他 Agent。
 
-## 创建流程：EnterWorktreeTool
+## 创建与恢复
 
-`EnterWorktreeTool`（`src/tools/EnterWorktreeTool/EnterWorktreeTool.ts`）的执行链路：
+### 创建流程
 
 ```
-EnterWorktreeTool.call({ name? })
-  ↓
-1. 检查是否已在 worktree 中（防嵌套）
-  ↓
-2. 解析到主仓库根目录（findCanonicalGitRoot）
-   如果当前已在 worktree 内，chdir 到主仓库
-  ↓
-3. 生成 slug（用户提供或 plan slug）
-  ↓
-4. createWorktreeForSession(sessionId, slug)
-   ├── 有 WorktreeCreate hook？
-   │   └── 执行 hook，返回 hook 指定的路径（支持非 git VCS）
-   └── 无 hook → git 原生路径：
-       a. getOrCreateWorktree(repoRoot, slug)
-          ├── 快速恢复：检查 worktree 目录是否已存在
-          │   └── 读取 .git 指针文件的 HEAD SHA（无子进程）
-          └── 新建：
-              i.   mkdir .claude/worktrees/（recursive）
-              ii.  fetch origin/<default-branch>（有缓存则跳过）
-              iii. git worktree add -b worktree/<slug> <path> <base>
-              iv.  performPostCreationSetup()（sparse checkout 等）
-  ↓
-5. 更新进程状态：
-   - process.chdir(worktreePath)
-   - setCwd(worktreePath)
-   - setOriginalCwd(worktreePath)
-   - saveWorktreeState(session) → 持久化到项目配置
-   - clearSystemPromptSections() → 重新计算系统提示中的 cwd 信息
-   - clearMemoryFileCaches() → 重新加载 worktree 中的 CLAUDE.md
-  ↓
-6. 返回 worktreePath 和 worktreeBranch
+检查是否已在 worktree 中（防嵌套） → 生成 slug → 创建 worktree → 切换进程工作目录
 ```
 
-### Hook 优先的架构
-
-`createWorktreeForSession()` 首先检查 `hasWorktreeCreateHook()`——如果用户在 settings.json 中配置了 `WorktreeCreate` hook，系统完全不调用 git，而是执行 hook 命令并将返回的路径作为 worktree 路径。这允许非 git 版本控制系统（如 Pijul、Mercurial）通过 hook 接入。
+**设计细节**：
+- 分支名遵循 `worktree/<slug>` 格式，slug 有严格的字符限制
+- 创建后自动更新进程状态——所有后续文件操作自动在 worktree 中执行
+- 系统提示和 CLAUDE.md 被重新加载，确保 AI 看到 worktree 中的上下文
 
 ### 快速恢复路径
 
-`getOrCreateWorktree()` 有一个关键优化：如果目标路径已存在，直接读取 `.git` 指针文件获取 HEAD SHA（纯文件 I/O，无子进程），跳过整个 `fetch` + `worktree add` 流程。在大仓库中 `fetch` 需要 6-8 秒，这个优化将恢复场景的延迟降到接近 0。
+如果目标 worktree 已存在，直接读取指针文件获取 HEAD SHA——纯文件 I/O，无子进程。在大仓库中 `git fetch` 可能需要 6-8 秒，这个优化将恢复延迟降到接近 0。
 
-## 退出流程：ExitWorktreeTool
+**设计洞察**：恢复（resume）是比创建更频繁的操作。用户可能中断后重新开始，或者 Agent 在之前的 worktree 上继续工作。优化恢复路径比优化创建路径更有价值。
 
-`ExitWorktreeTool`（`src/tools/ExitWorktreeTool/ExitWorktreeTool.ts`）支持两种退出策略：
+### Hook 优先架构
 
-### keep：保留 worktree
+如果用户配置了 `WorktreeCreate` hook，系统完全不调用 git，而是执行 hook 命令获取路径。这允许非 git 版本控制系统（如 Pijul、Mercurial）通过 hook 接入隔离机制。
 
-```
-keepWorktree()
-  ↓
-1. chdir 回 originalCwd
-2. 清空 currentWorktreeSession
-3. 更新项目配置（activeWorktreeSession = undefined）
-4. worktree 目录和分支保留在磁盘上
-```
+## 退出与清理
 
-用户可以通过 `cd <worktreePath>` 继续工作，或稍后手动合并。
+退出支持两种策略：
 
-### remove：删除 worktree
+| 策略 | 行为 | 适用场景 |
+|------|------|---------|
+| **keep** | 保留 worktree 和分支 | 后续需要合并或审查 |
+| **remove** | 删除 worktree 和分支 | 确认不再需要 |
 
-有严格的**安全防护**：
+### Fail-closed 安全防护
 
-```
-validateInput() — 第一道防线
-  ↓
-1. 检查是否在 EnterWorktree 创建的会话中
-   （手动创建的 worktree 不会被删除）
-  ↓
-2. countWorktreeChanges(worktreePath, originalHeadCommit)
-   ├── git status --porcelain → 统计未提交文件数
-   ├── git rev-list --count <originalHead>..HEAD → 统计新提交数
-   └── 返回 null（git 失败时）→ fail-closed（拒绝删除）
-  ↓
-3. 有未提交文件或新提交？
-   → 拒绝，要求 discard_changes: true 确认
-```
+删除操作有多层安全防护：
 
-```
-call() — 实际执行
-  ↓
-1. 重新计数变更（validateInput 和 call 之间可能有新修改）
-2. 如果有 tmux session → killTmuxSession()
-3. cleanupWorktree()
-   ├── hook-based → 执行 WorktreeRemove hook
-   └── git-based → git worktree remove --force + git branch -D
-4. restoreSessionToOriginalCwd()
-   - setCwd(originalCwd)
-   - setOriginalCwd(originalCwd)
-   - 如果 projectRoot 是 worktree 时才恢复（防误触）
-   - 更新 hooks config snapshot
-   - 清空系统提示和 memory 缓存
-```
+1. 只允许删除通过 EnterWorktree 创建的 worktree（手动 `git worktree add` 的不会被删）
+2. 有未提交文件或新提交时，拒绝删除（除非显式 `discard_changes: true`）
+3. git 命令失败时，返回"未知"状态，拒绝删除
 
-### fail-closed 设计
+**设计哲学**：宁可让用户手动处理废弃的 worktree，也不冒险丢失工作。磁盘空间比丢失代码便宜得多。
 
-`countWorktreeChanges()` 在以下情况返回 `null`（"未知，假设不安全"）：
-- `git status` 或 `git rev-list` 退出非零（锁文件、损坏的索引）
-- `originalHeadCommit` 未定义（hook-based worktree 没有设置基线 commit）
+### 重新计数
 
-返回 `null` 时，`validateInput` 拒绝删除——宁可让用户手动处理，也不冒险丢失工作。
+validateInput 和实际执行之间可能有新的修改。删除前重新计数变更，确保不会误删。
 
-## 与 Agent 工具的联动
+## 与子 Agent 的联动
 
-Agent 工具（`AgentTool`）的 `isolation` 参数决定子 Agent 是否在 worktree 中运行：
+子 Agent 的 `isolation: "worktree"` 参数自动在独立 worktree 中运行。子 Agent 的 worktree 管理与用户会话略有不同：
 
-- `isolation: "worktree"` → 调用 `createWorktreeForSession()`，子 Agent 在独立 worktree 中执行
-- 无 isolation → 子 Agent 共享主工作目录
+| 维度 | 用户会话 | 子 Agent |
+|------|---------|---------|
+| Session 状态 | 完整持久化 | 无 session 状态 |
+| 清理策略 | 手动退出 | 自动清理（无变更则删除） |
+| 有变更时 | 用户决定 | 保留 worktree，返回路径 |
 
-子 Agent 结束时的处理：
-- **成功**：主 Agent 通过 `ExitWorktreeTool(action: "keep")` 保留 worktree，然后手动合并
-- **失败/放弃**：主 Agent 通过 `ExitWorktreeTool(action: "remove", discard_changes: true)` 清理
-
-## Session 状态持久化
-
-`WorktreeSession` 对象通过 `saveCurrentProjectConfig()` 持久化到磁盘，包含：
-
-```typescript
-{
-  originalCwd: string,         // 进入 worktree 前的工作目录
-  worktreePath: string,        // worktree 的绝对路径
-  worktreeName: string,        // slug
-  worktreeBranch?: string,     // 分支名（如 worktree/fix-auth）
-  originalBranch?: string,     // 进入前的分支
-  originalHeadCommit?: string, // 进入前的 HEAD commit（用于变更统计）
-  sessionId: string,           // 创建此 worktree 的会话 ID
-  tmuxSessionName?: string,    // 关联的 tmux session
-  hookBased?: boolean,         // 是否由 hook 创建
-  creationDurationMs?: number, // 创建耗时（分析用）
-}
-```
-
-这使得 session 恢复（`--resume`）时能正确还原 worktree 上下文——即使进程重启，`getCurrentWorktreeSession()` 从项目配置中读取状态。
+**设计考量**：子 Agent 的 worktree 不需要用户手动管理——如果 Agent 没有产生任何修改，worktree 被自动清理；如果有修改，保留下来供主 Agent 后续合并。
 
 ## Sparse Checkout 优化
 
-对于大型 monorepo，worktree 支持 `sparsePaths` 配置——只检出特定目录而非整个仓库。这在 210K 文件的仓库中将 worktree 创建时间从数十秒降到几秒。
+大型 monorepo 中，完整检出可能需要数十秒。Sparse checkout 只检出特定目录，将创建时间降到几秒。
 
-配置位于 `getInitialSettings().worktree?.sparsePaths`，在 `performPostCreationSetup()` 中应用。
+## 接下来
+
+- **子 Agent** — 理解使用 worktree 隔离的子 Agent 创建
+- **协调者与蜂群** — 理解多 Agent 的高级编排
+- **权限模型** — 理解工具权限的安全体系

docs/auto-updater.md

@@ -42,7 +42,7 @@ useInterval(checkForUpdates, 30 * 60 * 1000); // 每 30 分钟
 
 任何更新尝试之前，系统会依次检查：
 
-1. **自动更新是否被禁用？** — `getAutoUpdaterDisabledReason()`（`src/utils/config.ts:1735`）
+1. **自动更新是否被禁用？** — `getAutoUpdaterDisabledReason()`（`src/utils/config.ts:1737`）
    - `NODE_ENV === 'development'`
    - 设置了 `DISABLE_AUTOUPDATER` 环境变量
    - 仅限必要流量模式
@@ -81,7 +81,7 @@ useInterval(checkForUpdates, 30 * 60 * 1000); // 每 30 分钟
 
 `src/utils/autoUpdater.ts:70` — `assertMinVersion()`
 
-从 `src/main.tsx:1775` 在启动时调用：
+定义于 `src/utils/autoUpdater.ts:70`，设计上在启动时调用（当前未接入启动流程）：
 
 ```typescript
 void assertMinVersion();
@@ -200,7 +200,7 @@ Windows 系统使用文件复制而非符号链接。
 
 **文件**: `src/migrations/migrateAutoUpdatesToSettings.ts`
 
-一次性将旧版 `globalConfig.autoUpdates = false` 迁移为 settings 中的 `DISABLE_AUTOUPDATER=1` 环境变量。从 `src/main.tsx:325` 在启动时调用。
+一次性将旧版 `globalConfig.autoUpdates = false` 迁移为 settings 中的 `DISABLE_AUTOUPDATER=1` 环境变量。定义于 `src/migrations/migrateAutoUpdatesToSettings.ts`（当前未接入启动流程）。
 
 ---
 
@@ -270,7 +270,7 @@ React hook `useUpdateNotification(updatedVersion)` — 确保每次 semver 变
 | `src/utils/releaseNotes.ts` | Changelog 获取、缓存与展示 |
 | `src/utils/semver.ts` | Semver 版本比较（Bun 原生 + npm 回退） |
 | `src/utils/doctorDiagnostic.ts` | 安装类型检测与健康诊断 |
-| `src/utils/config.ts:1735` | `getAutoUpdaterDisabledReason()` — 禁用检查逻辑 |
+| `src/utils/config.ts:1737` | `getAutoUpdaterDisabledReason()` — 禁用检查逻辑 |
 | `src/migrations/migrateAutoUpdatesToSettings.ts` | 旧版配置迁移 |
 | `src/screens/Doctor.tsx` | Doctor 命令 UI，展示自动更新状态 |
 

docs/context/compaction.mdx

@@ -1,265 +1,131 @@
 ---
-title: "上下文压缩 - Compaction 三层策略与边界机制"
-description: "深度解析 Claude Code 上下文压缩的完整实现：Session Memory 压缩、传统 API 摘要压缩、MicroCompact 局部压缩三层策略，以及 CompactBoundary 消息、工具对保持、PTL 紧急降级等关键机制。"
-keywords: ["上下文压缩", "Compaction", "token 管理", "对话压缩", "上下文窗口", "MicroCompact"]
+title: "上下文压缩"
+description: "对话历史不断增长，token 窗口有限。理解 Claude Code 的三层压缩策略、边界标记机制和紧急降级路径。"
+keywords: ["上下文压缩", "Compaction", "token 管理", "对话压缩"]
 ---
 
-{/* 本章目标：从源码层面剖析压缩的三层策略、边界机制和关键常量 */}
+## 核心问题
 
-## 压缩的触发时机
+AI 没有真正的长期记忆——它只能看到当前 API 请求中的内容。随着对话增长，token 消耗持续上升，最终会触及模型的上下文窗口限制。
 
-上下文压缩不是单一操作，而是**三层递进**的策略系统，对应不同的触发条件和严重程度：
+压缩就是在"保留足够的语义信息"和"减少 token 占用"之间找平衡。
 
-| 层级 | 触发条件 | 实现位置 | 是否需要 API 调用 |
-|------|---------|---------|:---:|
-| **MicroCompact** | 单个工具输出过长 | `microCompact.ts` | 否 |
-| **Session Memory Compact** | 自动压缩触发（需 feature flag） | `sessionMemoryCompact.ts` | 否 |
-| **传统 API 摘要** | 手动 `/compact` 或 SM 不可用时的自动回退 | `compact.ts` | 是 |
+## 三层递进策略
 
-### 压缩入口的优先级链
+系统不是用一种方法解决所有压缩需求，而是根据严重程度递进使用三种策略：
 
-源码路径：`src/commands/compact/compact.ts`
+| 层级 | 触发条件 | 是否需要 API 调用 | 成本 |
+|------|----------|:---:|------|
+| **微压缩** | 单个工具输出过长 | 否 | 几乎为零 |
+| **Session Memory 压缩** | 自动压缩触发时优先尝试 | 否 | 低（使用已提取的记忆） |
+| **AI 摘要压缩** | 上述方法不可用或用户手动触发 | 是 | 高（需要额外 API 调用） |
 
-当用户执行 `/compact` 或系统触发自动压缩时，压缩命令按以下优先级尝试：
+### 设计哲学：从廉价到昂贵
 
-```typescript
-// compact.ts:55-99 — 简化后的优先级链
-if (!customInstructions) {
-  const sessionMemoryResult = await trySessionMemoryCompaction(messages, ...)
-  if (sessionMemoryResult) return sessionMemoryResult      // 优先：SM 压缩
-}
+为什么不直接用 AI 摘要？因为 AI 摘要需要额外的 API 调用——既花钱又花时间。系统的策略是**先用确定性操作（廉价），不行再用 AI 生成（昂贵）**。
 
-if (reactiveCompact?.isReactiveOnlyMode()) {
-  return await compactViaReactive(messages, ...)            // 次选：Reactive 压缩
-}
+这种分层设计意味着大部分情况下，系统可以在用户无感知的情况下释放足够的 token。
 
-// 兜底：传统 API 摘要
-const microcompactResult = await microcompactMessages(messages, context)
-const messagesForCompact = microcompactResult.messages
-// → 调用 AI 模型生成摘要
-```
+## 第一层：微压缩（Micro-Compact）
 
-注意：SM 压缩不支持自定义指令（`/compact 聚焦在认证模块`），有自定义指令时直接走传统路径。
+微压缩不生成摘要，只是清除旧的工具调用结果。
 
-## 第一层：MicroCompact — 局部压缩
+### 工作原理
 
-源码路径：`src/services/compact/microCompact.ts`
+AI 在工作过程中会产生大量工具输出：文件内容、命令结果、搜索匹配等。这些信息在产生时很重要，但随着对话推进，它们的价值迅速降低。
 
-MicroCompact 不压缩整个对话，而是**清除旧工具输出的内容**。它维护一个白名单：
+微压缩识别这些"过期"的工具输出，将其替换为简短的占位符文本。原始内容仍保留在磁盘上的 transcript 文件中，只是不再发送给 API。
 
-```typescript
-// src/services/compact/microCompact.ts:41-48
-const COMPACTABLE_TOOLS = new Set([
-  FILE_READ_TOOL_NAME,    // 'Read' - 文件读取
-  ...SHELL_TOOL_NAMES,    // 'Bash' - 命令输出
-  GREP_TOOL_NAME,         // 'Grep' - 搜索结果
-  GLOB_TOOL_NAME,         // 'Glob' - 文件列表
-  WEB_SEARCH_TOOL_NAME,   // 'WebSearch' - 搜索结果
-  WEB_FETCH_TOOL_NAME,    // 'WebFetch' - 网页内容
-  FILE_EDIT_TOOL_NAME,    // 'Edit' - 编辑输出
-  FILE_WRITE_TOOL_NAME,   // 'Write' - 写入输出
-])
-```
+### 时间衰减
 
-替换策略：将超过时间窗口的工具输出内容替换为 `[Old tool result content cleared]`。这不是简单的截断——原始内容仍保留在 JSONL transcript 中，只是不再发送给 API。
-
-MicroCompact 还有一个**时间衰减配置**（`timeBasedMCConfig.ts`）：越旧的工具输出越容易被清除，最近的优先保留。
+越旧的工具输出越容易被清除，最近操作的优先保留。这个策略基于一个经验观察：AI 通常只需要最近几步操作的上下文，更早的工具结果很少被再次引用。
 
 ### 图片和文档的特殊处理
 
-```typescript
-const IMAGE_MAX_TOKEN_SIZE = 2000
-```
+图片和 PDF 文档的 token 占用远高于文本。微压缩会将大型图片和文档替换为文本标记（如 `[image]`），在保留"这里曾有一张图片"的语义的同时释放大量 token。
 
-图片 block 如果超过 2000 token 估算值，也会被 MicroCompact 清除。PDF document block 同理。
+## 第二层：Session Memory 压缩
 
-## 第二层：Session Memory Compact — 无 API 调用的压缩
+当微压缩释放的 token 不够时，系统优先尝试 Session Memory 压缩。
 
-源码路径：`src/services/compact/sessionMemoryCompact.ts`
+### 设计思路
 
-当 `tengu_session_memory` + `tengu_sm_compact` 两个 feature flag 启用时，系统优先使用 Session Memory 进行压缩——**不需要调用摘要模型**，直接使用已经提取好的 Session Memory 作为对话摘要。
+系统在对话过程中会持续提取关键信息形成"Session Memory"。压缩时，直接使用这些已提取的记忆作为对话摘要，而不需要额外调用 AI 生成摘要。
 
-### 保留窗口的计算
+### 保留窗口
 
-```typescript
-// sessionMemoryCompact.ts:324-397
-export function calculateMessagesToKeepIndex(messages, lastSummarizedIndex) {
-  const config = getSessionMemoryCompactConfig()
-  // 默认: minTokens=10K, minTextBlockMessages=5, maxTokens=40K
+压缩后保留的消息需要满足三个约束：
 
-  let startIndex = lastSummarizedIndex + 1
-  // 从 lastSummarizedIndex 向前扩展，直到满足两个下限或命中上限
-  for (let i = startIndex - 1; i >= floor; i--) {
-    totalTokens += estimateMessageTokens([msg])
-    if (hasTextBlocks(msg)) textBlockMessageCount++
-    startIndex = i
-    if (totalTokens >= config.maxTokens) break
-    if (totalTokens >= config.minTokens && textBlockMessageCount >= config.minTextBlockMessages) break
-  }
-  return adjustIndexToPreserveAPIInvariants(messages, startIndex)
-}
-```
+- **最小深度**：至少保留 10K token 的最近对话（确保 AI 有足够的上下文）
+- **最小连续性**：至少保留 5 条包含文本的消息（确保对话连贯）
+- **最大上限**：不超过 40K token（避免保留太多又很快触发下一次压缩）
 
-这个算法确保压缩后保留的消息窗口满足：
-- 至少 10,000 token（有上下文深度）
-- 至少 5 条包含文本的消息（有对话连续性）
-- 最多 40,000 token（不会太大又触发下一次压缩）
+这三个约束形成了"不要压缩太少（AI 会迷失），也不要保留太多（很快又需要压缩）"的平衡。
 
-### 工具对完整性保护
+### 工具对完整性
 
-`adjustIndexToPreserveAPIInvariants()` 是压缩中一个**关键的正确性保证**：
+这是一个关键的**正确性保证**：API 要求每个工具调用都有对应的工具结果，反之亦然。如果压缩恰好切在一个工具调用和它的结果之间，API 会报错。
 
-API 要求每个 `tool_result` 都有对应的 `tool_use`，反之亦然。如果压缩恰好切在一条 `tool_result` 消息处，会导致 API 报错。
+系统在计算压缩边界时，会自动向前或向后调整切分点，确保所有工具调用-结果对要么完整保留，要么一起被压缩。
 
-```typescript
-// sessionMemoryCompact.ts:232-314
-// Step 1: 向前扫描，找到所有被保留消息中 tool_result 引用的 tool_use
-// Step 2: 向前扫描，找到与被保留 assistant 消息共享 message.id 的 thinking block
-// 两种情况都需要将 startIndex 向前移动
-```
+## 第三层：AI 摘要压缩
 
-流式传输会将一个 assistant 消息拆分为多条存储记录（thinking、tool_use 等各有独立 uuid 但共享 `message.id`），这增加了边界情况的复杂度。
-
-## 第三层：传统 API 摘要压缩
-
-源码路径：`src/services/compact/compact.ts`
-
-当 SM 压缩不可用时，系统回退到传统方式：调用 AI 模型生成对话摘要。
+当上述方法都不可用时（或用户手动触发 `/compact` 时），系统调用 AI 生成对话摘要。
 
 ### 压缩前处理
 
-发送给摘要模型之前，消息会经过多层预处理：
-
-```typescript
-// compact.ts:147-202
-const stripped = stripImagesFromMessages(messages)   // 图片→[image] 文字标记
-const stripped2 = stripReinjectedAttachments(stripped) // 移除会被重新注入的附件
-```
-
-图片被替换为 `[image]` 标记，防止摘要 API 调用本身也触发 prompt-too-long 错误。
+发送给摘要 AI 的消息会经过预处理：
+- 图片被替换为文本标记（防止摘要请求本身也超出 token 限制）
+- 会被重新注入的附件被剥离（避免重复）
 
 ### 压缩后的重新注入
 
-压缩后，系统会从摘要中**重新注入关键上下文**：
+压缩不是"砍掉旧对话就完了"。AI 在压缩后立即需要知道"现在正在做什么"。系统会在摘要后重新注入关键上下文：
 
-```typescript
-// compact.ts:124-132
-export const POST_COMPACT_TOKEN_BUDGET = 50_000          // 总预算
-export const POST_COMPACT_MAX_FILES_TO_RESTORE = 5        // 最多恢复 5 个文件
-export const POST_COMPACT_MAX_TOKENS_PER_FILE = 5_000     // 每文件 5K token
-export const POST_COMPACT_MAX_TOKENS_PER_SKILL = 5_000    // 每技能 5K token
-export const POST_COMPACT_SKILLS_TOKEN_BUDGET = 25_000    // 技能总预算 25K
-```
+| 重新注入内容 | 预算 | 设计理由 |
+|-------------|------|----------|
+| 最近读取的文件（最多 5 个） | 每文件 5K token | AI 最可能需要的就是刚操作过的文件 |
+| 已激活的技能指令 | 每技能 5K，总计 25K | 保持 AI 的能力集不变 |
+| CLAUDE.md 内容 | 不限 | 用户的项目指令必须始终存在 |
+| MCP 工具发现结果 | 不限 | 保持工具可用性 |
 
-这 50K token 的重新注入预算用于：
-1. 恢复最近读取的文件内容（最多 5 个文件，每个截断到 5K token）
-2. 恢复已激活的技能指令（每个技能截断到 5K token，总计 25K）
-3. 重新注入 CLAUDE.md 内容
-4. 恢复 MCP 工具发现结果
+**设计洞察**：总共 50K token 的重新注入预算看起来是浪费——刚压缩释放的 token 立刻又被用掉了一部分。但这是必要的：没有这些重新注入，AI 在压缩后会"忘记"当前任务状态，导致糟糕的用户体验。
 
-## CompactBoundary：压缩的边界标记
+## 边界标记：压缩的"墓碑"
 
-源码路径：`src/utils/messages.ts`（`createCompactBoundaryMessage`）
+每次压缩后，系统在消息流中插入一条边界标记消息。这条消息不展示给用户，但记录了：
+- 压缩类型（自动/手动/微压缩）
+- 压缩前的 token 数
+- 哪些消息被保留
 
-每次压缩后，系统在消息流中插入一条 `SystemCompactBoundaryMessage`：
+后续所有操作只处理最后一条边界标记之后的消息。这防止了"重复压缩已经压缩过的内容"——每次压缩都是相对于上一次边界的新压缩。
 
-```typescript
-type SystemCompactBoundaryMessage = {
-  type: 'system'
-  message: {
-    type: 'compact_boundary'
-    compactMetadata: {
-      compactType: 'auto' | 'manual' | 'micro'
-      preCompactTokenCount: number
-      lastUserMessageUuid: string
-      preCompactDiscoveredTools?: string[]
-    }
-  }
-}
-```
+### 微压缩 vs 全量压缩的边界区别
 
-后续所有操作只处理**最后一条 boundary 之后**的消息：
+微压缩的边界标记更轻量——它只记录哪些工具结果被清除了，不生成摘要。原始消息仍然存在（只是内容被替换为占位符），而非被摘要替代。
 
-```typescript
-// messages.ts
-export function getMessagesAfterCompactBoundary(messages: Message[]): Message[] {
-  const lastBoundary = messages.findLastIndex(m => isCompactBoundaryMessage(m))
-  return lastBoundary >= 0 ? messages.slice(lastBoundary + 1) : messages
-}
-```
+## 紧急降级：Prompt Too Long
 
-### Preserved Segment 注解
+当压缩后仍然超出 token 限制时，系统进入紧急路径：
 
-boundary 消息上还附加了 `preservedSegment` 注解，记录哪些消息被保留而非压缩：
+1. **更激进的压缩**：尝试比正常压缩更激进的策略
+2. **直接截断**：从最早的对话开始删除，直到能塞进上下文窗口
+3. **放弃并报错**：如果以上都失败，向用户报告错误
 
-```typescript
-// compact.ts — annotateBoundaryWithPreservedSegment
-boundaryMarker.compactMetadata.preservedSegment = {
-  summaryMessageUuid: string
-  preservedMessageUuids: string[]
-}
-```
+**设计哲学**：系统宁可丢失部分对话历史，也不让整个会话卡死。用户可以通过文件快照和 transcript 记录恢复丢失的信息。
 
-这在会话恢复时帮助加载器正确重建消息链，避免重复压缩已保留的消息。
+## Hook 机制
 
-### Microcompact Boundary
+压缩前后支持自定义 Hook：
 
-Microcompact 操作使用单独的 boundary 类型，与全量压缩的 `compact_boundary` 不同：
+- **Pre-compact Hook**：压缩前执行，可以标记"必须保留"的内容
+- **Post-compact Hook**：压缩后执行，可以验证关键信息是否被保留
+- **Session Start Hook**：压缩后恢复 CLAUDE.md 等上下文
 
-```typescript
-// src/utils/messages.ts:4599-4614
-type SystemMicrocompactBoundaryMessage = {
-  type: 'system'
-  subtype: 'microcompact_boundary'
-  content: 'Context microcompacted'
-  compactMetadata: {
-    trigger: 'auto'              // Microcompact 只有自动触发
-    preTokens: number            // 压缩前 token 数
-    tokensSaved: number          // 节省的 token 数
-    compactedToolIds: string[]   // 被压缩的工具 ID 列表
-    clearedAttachmentUUIDs: string[] // 被清除的附件 UUID
-  }
-}
-```
+这确保了用户的自定义逻辑在压缩过程中被尊重——例如，用户可以通过 Hook 确保某个关键文件的内容永远不会被压缩掉。
 
-与 `compact_boundary` 的区别：
-- **保留原始消息**：Microcompact 仅清除工具输出内容，不删除消息本身
-- **可追溯性**：`compactedToolIds` 记录了哪些工具结果被清除
-- **轻量级**：不生成摘要，不调用 API
+## 接下来
 
-## PTL 紧急降级：Prompt Too Long
-
-当压缩后仍然超出 token 限制（`PROMPT_TOO_LONG` 错误），系统会进入紧急降级路径：
-
-1. **Reactive Compact**：`reactiveCompactOnPromptTooLong()` 尝试更激进的压缩
-2. **截断重试**：如果 reactive 也失败，`truncateHeadForPTLRetry()` 直接截断最早的消息
-3. 放弃并报错
-
-Reactive Compact 目前在反编译版本中是 stub（`isReactiveOnlyMode() → false`），表明这是 Anthropic 内部的实验性功能。
-
-## 压缩的 Hook 机制
-
-压缩前后可以执行自定义 Hook：
-
-- **Pre-compact Hook**（`executePreCompactHooks`）：在压缩前执行，可以注入"必须保留"的标记
-- **Post-compact Hook**（`executePostCompactHooks`）：在压缩后执行，可以验证关键信息是否保留
-- **Session Start Hook**（`processSessionStartHooks('compact')`）：SM 压缩使用此 Hook 恢复 CLAUDE.md 等上下文
-
-Hook 结果以 `HookResultMessage` 的形式附加到压缩结果中，确保用户的自定义逻辑在压缩过程中被尊重。
-
-## Snip Compact（实验性）
-
-源码路径：`src/services/compact/snipCompact.ts`（stub）
-
-Snip Compact 是另一种实验性压缩策略，在反编译版本中为空壳实现。从 stub 的类型签名推断：
-
-```typescript
-snipCompactIfNeeded(messages, options?: { force?: boolean }) → {
-  messages: Message[]
-  executed: boolean
-  tokensFreed: number
-  boundaryMessage?: Message
-}
-```
-
-它似乎是一种**更细粒度的消息级裁剪**（snip = 剪切），可能是对单条消息的进一步压缩，而非整个对话。`shouldNudgeForSnips()` 和 `SNIP_NUDGE_TEXT` 暗示它可能会提示用户触发。
+- **项目记忆** — 理解跨会话的记忆持久化设计
+- **令牌预算** — 了解 token 窗口的动态计算和阈值管理
+- **系统提示词** — 理解上下文组装的缓存优化策略

docs/context/project-memory.mdx

@@ -1,226 +1,137 @@
 ---
-title: "项目记忆系统 - 文件级跨对话记忆架构"
-description: "深度解析 Claude Code 记忆系统：基于文件的持久化存储、MEMORY.md 索引结构、四类型分类法、Sonnet 智能召回、Session Memory 压缩集成。"
-keywords: ["项目记忆", "MEMORY.md", "AI 记忆", "跨对话", "自动记忆", "memdir"]
+title: "项目记忆"
+description: "AI 没有真正的记忆。Claude Code 如何通过文件系统构建跨会话的记忆？理解存储架构、四类型分类法、智能召回和漂移防御设计。"
+keywords: ["项目记忆", "MEMORY.md", "AI 记忆", "跨对话", "自动记忆"]
 ---
 
-{/* 本章目标：从源码层面剖析记忆系统的存储架构、召回机制和注入链路 */}
+## 核心问题
 
-## 记忆系统的存储架构
+AI 的每次 API 调用都是无状态的——模型只看到当前请求中的内容。这意味着每次新会话，AI 都从零开始，不知道你之前讨论过什么、你喜欢什么风格、项目有什么特殊约束。
 
-源码路径：`src/memdir/paths.ts`、`src/memdir/memdir.ts`
+记忆系统的目标：**让 AI 在跨会话中保持连贯性**。
+
+## 存储架构：纯文件
 
 Claude Code 的记忆系统是**纯文件**的——没有数据库、没有向量存储，只有 Markdown 文件和目录结构。
 
-### 目录布局
-
 ```
-~/.claude/projects/<sanitized-git-root>/memory/
+~/.claude/projects/<项目目录>/memory/
 ├── MEMORY.md                    ← 入口索引（每次对话加载）
 ├── user_role.md                 ← 用户记忆
 ├── feedback_testing.md          ← 反馈记忆
 ├── project_mobile_release.md    ← 项目记忆
-├── reference_linear_ingest.md   ← 参考记忆
-└── logs/                        ← KAIROS 模式：每日日志
-    └── 2026/
-        └── 04/
-            └── 2026-04-01.md
+└── reference_linear_ingest.md   ← 参考记忆
 ```
 
-路径解析链路（`getAutoMemPath()`）：
-1. `CLAUDE_COWORK_MEMORY_PATH_OVERRIDE` 环境变量（Cowork SDK 全路径覆盖）
-2. `autoMemoryDirectory` 设置（仅限 `policySettings`/`localSettings`/`userSettings`——**故意排除** `projectSettings`，防止恶意仓库将记忆路径指向 `~/.ssh`）
-3. 默认：`<memoryBase>/projects/<sanitized-git-root>/memory/`
+### 为什么选择文件而非数据库
 
-同一个 Git 仓库的所有 worktree 共享一个记忆目录（通过 `findCanonicalGitRoot()` 找到真正的 `.git` 根）。
+| 方案 | 优势 | 劣势 |
+|------|------|------|
+| **Markdown 文件** | 用户可直接编辑、git 友好、零依赖 | 查询需要扫描文件 |
+| SQLite 数据库 | 查询高效 | 用户无法直接编辑、需要额外依赖 |
+| 向量数据库 | 语义搜索强大 | 过度工程、引入复杂依赖 |
+
+选择文件的核心理由：**记忆应该是用户可以审查、编辑和删除的**。Markdown 文件让用户完全掌控 AI 记住了什么。如果 AI 记住了错误的信息，用户可以直接打开文件删除它。
 
 ### MEMORY.md 索引
 
-`MEMORY.md` 是记忆的入口索引，每次对话都完整加载到上下文中：
+`MEMORY.md` 是记忆系统的入口。每次对话开始时完整加载到上下文中。它不是记忆内容本身，而是一个链接索引：
 
-```typescript
-// memdir.ts:35-38
-export const ENTRYPOINT_NAME = 'MEMORY.md'
-export const MAX_ENTRYPOINT_LINES = 200
-export const MAX_ENTRYPOINT_BYTES = 25_000
-```
-
-索引有**双重上限**：200 行 AND 25KB。超过任何一条都会被 `truncateEntrypointContent()` 截断并追加警告。设计原因：p97 的索引文件用 200 行就能覆盖，但有些索引条目特别长（p100 观测到 197KB/200 行），字节上限捕捉这种长行异常。
-
-索引条目格式：
 ```markdown
-- [Title](file.md) — one-line hook
+- [用户角色](user_role.md) — 深度 Go 开发者，React 新手
+- [测试反馈](feedback_testing.md) — 集成测试必须使用真实数据库
 ```
 
-每条一行，~150 字符以内。`MEMORY.md` 本身没有 frontmatter——它只是一个链接列表，不是记忆内容。
+索引有双重上限（行数和字节数），防止索引本身占用过多 token。超过上限时自动截断——这确保记忆系统不会成为新的 token 负担。
 
 ## 四类型分类法
 
-源码路径：`src/memdir/memoryTypes.ts`
+记忆被约束为一个封闭的四类型系统，每种类型有明确的用途和保存时机：
 
-记忆被约束为一个**封闭的四类型系统**，每种类型有明确的 `<when_to_save>`、`<how_to_use>` 和 `<body_structure>` 规范：
+| 类型 | 存储内容 | 设计目的 |
+|------|---------|----------|
+| **user** | 用户角色、偏好、技术背景 | 让 AI 理解"用户是谁" |
+| **feedback** | 用户对 AI 行为的纠正和确认 | 防止 AI 重复犯错或偏离已验证的工作方式 |
+| **project** | 无法从代码推导的项目上下文 | 记录"为什么这样决定"而非"代码长什么样" |
+| **reference** | 外部系统的指针 | 告诉 AI 去哪里找信息 |
 
-| 类型 | 存储内容 | 典型触发 |
-|------|---------|---------|
-| **user** | 用户角色、偏好、技术背景 | "我是数据科学家"、"我写了十年 Go" |
-| **feedback** | 用户对 AI 行为的纠正和确认 | "别 mock 数据库"、"单 PR 更好" |
-| **project** | 非代码可推导的项目上下文 | "合并冻结从周四开始"、"auth 重写是合规要求" |
-| **reference** | 外部系统指针 | "pipeline bugs 在 Linear INGEST 项目" |
+### 关键设计约束
 
-关键设计约束：**只存储无法从当前项目状态推导的信息**。代码架构、文件路径、git 历史都可以实时获取，不需要记忆。
+**只存储无法从当前项目状态推导的信息。** 代码架构、文件路径、git 历史都可以实时获取，不需要记忆。
 
-### 反馈类型的双通道捕获
+这条约束防止记忆系统变成冗余缓存。如果某个信息可以通过读代码获得，那就不应该记下来——因为代码是最新的，而记忆可能已经过时。
 
-`feedback` 类型的 `when_to_save` 指令特别强调：
+### 反馈的双通道捕获
 
-> Record from failure AND success: if you only save corrections, you will avoid past mistakes but drift away from approaches the user has already validated, and may grow overly cautious.
+反馈类型特别强调不仅要在用户纠正时保存（"不要这样做"），也要在用户确认时保存（"对，就是这样"）。
 
-这意味着 AI 不仅在用户说"不要这样做"时保存，也在用户说"对，就是这样"时保存。后一种更难捕捉，但同等重要——它防止 AI 的行为随时间漂移。
+**设计考量**：如果只记录纠正，AI 会避免过去的错误，但也会偏离用户已经验证过的工作方式，变得越来越保守。记录"成功路径"和记录"失败路径"同等重要。
 
-### 每条记忆的 Frontmatter 格式
+### 每条记忆的结构
+
+每条记忆文件都有 frontmatter 元数据：
 
 ```markdown
 ---
-name: {{memory name}}
-description: {{one-line description — 用于未来判断相关性}}
-type: {{user, feedback, project, reference}}
+name: 测试反馈
+description: 集成测试的数据库使用偏好
+type: feedback
 ---
 
-{{memory content — feedback/project 类型建议包含 **Why:** 和 **How to apply:** 行}}
+集成测试必须使用真实数据库，不能 mock。
+**Why:** 上季度发生过 mock 通过但生产迁移失败的事故。
+**How to apply:** 所有涉及数据库的测试用真实实例。
 ```
 
-`description` 字段是关键：它不是给人读的摘要，而是给 AI 召回系统做相关性判断的搜索关键词。
+`description` 字段不是给人读的摘要——它是给 AI 召回系统做相关性判断的搜索关键词。`Why` 和 `How to apply` 行帮助 AI 理解"为什么有这条规则"和"什么时候该应用它"。
 
-## 智能召回机制
+## 智能召回
 
-源码路径：`src/memdir/findRelevantMemories.ts`、`src/memdir/memoryScan.ts`
+不是所有记忆都适合每次对话。用户可能在 50 个记忆文件中积累了大量信息，但一次对话通常只需要其中 3-5 条。
 
-不是所有记忆都适合每次对话。系统使用一个**轻量级 Sonnet 侧查询**来筛选最相关的记忆。
+### 召回架构
 
-### 召回流程
+系统使用一个轻量级的独立 AI 查询来筛选最相关的记忆：
 
 ```
-用户消息 → findRelevantMemories(query, memoryDir)
-  ├── scanMemoryFiles() — 扫描所有记忆文件的 frontmatter
-  ├── selectRelevantMemories() — Sonnet 侧查询，从清单中选出 ≤5 条
-  └── 返回 [{path, mtimeMs}, ...]
+用户消息
+  → 扫描所有记忆文件的元数据
+  → 独立 AI 查询：从所有记忆中选出最相关的 ≤5 条
+  → 只加载选中的记忆文件内容
 ```
 
-核心是 `selectRelevantMemories()` 函数，它调用 `sideQuery()`（一个独立的轻量 API 调用）：
+**设计考量**：为什么不直接加载所有记忆？因为记忆文件会随时间增长，全部加载可能占用大量 token。使用独立查询筛选虽然多花一次 API 调用，但可以显著减少主对话的 token 消耗。
 
-```typescript
-// findRelevantMemories.ts:98-121
-const result = await sideQuery({
-  model: getDefaultSonnetModel(),  // 用 Sonnet 做筛选（非主模型）
-  system: SELECT_MEMORIES_SYSTEM_PROMPT,
-  messages: [{
-    role: 'user',
-    content: `Query: ${query}\n\nAvailable memories:\n${manifest}${toolsSection}`
-  }],
-  max_tokens: 256,
-  output_format: { type: 'json_schema', schema: { ... } },
-})
-```
+### 去噪设计
 
-### 近期工具去噪
-
-当 AI 正在使用某个工具时，召回该工具的使用文档是噪音（对话中已有工作上下文）。`recentTools` 参数让召回系统跳过这些记忆：
-
-```typescript
-// findRelevantMemories.ts:92-95
-const toolsSection = recentTools.length > 0
-  ? `\n\nRecently used tools: ${recentTools.join(', ')}`
-  : ''
-```
-
-System Prompt 明确指示："如果已提供最近使用的工具列表，不要选择该工具的使用参考或 API 文档。**仍然要选择**关于这些工具的警告、陷阱或已知问题——这正是使用时最关键的信息。"
-
-### 已展示去重
-
-`alreadySurfaced` 参数过滤之前轮次已展示过的文件路径，让 Sonnet 的 5 槽预算花在新的候选上，而不是重复召回同一文件。
-
-## 记忆注入 System Prompt 的链路
-
-源码路径：`src/memdir/memdir.ts` → `src/context.ts`
-
-`loadMemoryPrompt()` 是记忆注入的入口，每会话调用一次（通过 `systemPromptSection('memory', ...)` 缓存）：
-
-```typescript
-// memdir.ts:419-507
-export async function loadMemoryPrompt(): Promise<string | null> {
-  // 优先级：KAIROS 日志模式 → TEAMMEM 组合模式 → 纯自动记忆
-  if (feature('KAIROS') && autoEnabled && getKairosActive()) {
-    return buildAssistantDailyLogPrompt(skipIndex)
-  }
-  if (feature('TEAMMEM') && teamMemPaths!.isTeamMemoryEnabled()) {
-    return teamMemPrompts!.buildCombinedMemoryPrompt(...)
-  }
-  if (autoEnabled) {
-    return buildMemoryLines('auto memory', autoDir, ...).join('\n')
-  }
-  return null
-}
-```
-
-注入时机：`context.ts` 中 `getSystemContext()` 调用时，记忆 Prompt 作为 system prompt 的一个 section 被组装。`MEMORY.md` 的内容作为 **user context message** 注入（而非 system prompt），这样可以利用 Prompt Cache 的 prefix 共享。
-
-## KAIROS 模式：每日日志
-
-源码路径：`src/memdir/memdir.ts`（`buildAssistantDailyLogPrompt`）
-
-长期运行的 assistant 会话使用不同的记忆策略：
-
-- **标准模式**：AI 维护 `MEMORY.md` 作为实时索引 + 独立记忆文件
-- **KAIROS 模式**：AI 只往日期文件追加日志（`logs/YYYY/MM/YYYY-MM-DD.md`），不做重组
-
-```typescript
-// 日志路径模式（非字面路径——因为 Prompt 被缓存）
-const logPathPattern = join(memoryDir, 'logs', 'YYYY', 'MM', 'YYYY-MM-DD.md')
-```
-
-一个独立的夜间 `/dream` 技能负责将日志蒸馏为主题文件 + `MEMORY.md` 索引。
+- **近期工具去噪**：当 AI 正在使用某个工具时，不召回该工具的使用文档（对话中已有工作上下文）。但仍召回关于这些工具的**警告和已知问题**——这正是使用时最关键的信息。
+- **已展示去重**：之前轮次已展示过的记忆不再重复召回，让有限的召回预算花在新的候选上。
 
 ## 记忆漂移防御
 
-源码路径：`src/memdir/memoryTypes.ts`（`TRUSTING_RECALL_SECTION`）
+记忆可能过时。系统在 AI 的行为指令中设置了专门的防御：
 
-记忆可能过期。系统在 Prompt 中设置了一个专门的 section "Before recommending from memory"：
+> 一条记忆提到某个函数或文件，只是声明它**在记忆被写入时**存在。它可能已被重命名、删除或从未合并。在推荐之前，先验证它是否还存在。
 
-```
-A memory that names a specific function, file, or flag is a claim
-that it existed *when the memory was written*. It may have been
-renamed, removed, or never merged. Before recommending it:
-
-- If the memory names a file path: check the file exists.
-- If the memory names a function or flag: grep for it.
-```
-
-这个 section 的标题经过 A/B 测试验证："Before recommending from memory"（行动导向）比 "Trusting what you recall"（抽象描述）效果好（3/3 vs 0/3）。
+这个指令从"行动导向"的角度设计——不是告诉 AI"记忆可能不准确"（太抽象），而是直接告诉它"在推荐之前先检查"（可操作）。
 
 ### 忽略记忆的严格语义
 
-```
-If the user says to *ignore* or *not use* memory:
-proceed as if MEMORY.md were empty.
-Do not apply remembered facts, cite, compare against,
-or mention memory content.
-```
+当用户说"忽略记忆"时，AI 必须做到真正的忽略——不应用、不引用、不比较、甚至不提及记忆内容。
 
-这解决了 AI 的一个常见反模式：用户说"忽略关于 X 的记忆"，AI 虽然正确识别了代码但仍然加上"不像记忆中说的 Y"——这不是"忽略"，而是"承认然后覆盖"。
+这解决了一个常见的 AI 反模式：用户说"忽略关于 X 的记忆"，AI 虽然正确识别了代码，但仍加上"不像记忆中说的 Y"——这不是"忽略"，而是"承认然后覆盖"。
 
-## Session Memory 与压缩的联动
+## 与上下文压缩的联动
 
-源码路径：`src/services/compact/sessionMemoryCompact.ts`
+记忆系统与上下文压缩深度集成。当 Session Memory 功能启用时，压缩优先使用已提取的记忆作为摘要——不需要额外的 AI 调用生成摘要，更快、更便宜、且不会丢失信息。
 
-记忆系统与上下文压缩有深度集成。当 `tengu_session_memory` 和 `tengu_sm_compact` 两个 feature flag 同时开启时，压缩优先使用 Session Memory 而非传统摘要：
+这形成了一个正向循环：
+1. 对话中积累信息 → 提取为记忆
+2. 上下文需要压缩时 → 使用记忆作为摘要
+3. 下次对话开始 → 通过智能召回加载相关记忆
 
-```typescript
-// sessionMemoryCompact.ts:57-61
-const DEFAULT_SM_COMPACT_CONFIG = {
-  minTokens: 10_000,           // 压缩后至少保留 10K token
-  minTextBlockMessages: 5,     // 至少保留 5 条文本消息
-  maxTokens: 40_000,           // 最多保留 40K token
-}
-```
+## 接下来
 
-SM-compact 不调用压缩 API（没有摘要模型），而是直接使用已有的 Session Memory 作为摘要——更快、更便宜、且不会丢失信息。
+- **自动记忆整理** — 了解 KAIROS 模式下的每日日志和蒸馏机制
+- **上下文压缩** — 理解记忆如何与压缩策略联动
+- **令牌预算** — 了解记忆加载的 token 开销管理

docs/context/system-prompt.mdx

@@ -1,290 +1,116 @@
 ---
-title: "System Prompt 动态组装 - AI 工作记忆构建"
-description: "深入解析 Claude Code 的 System Prompt 动态组装过程：缓存策略、分界标记、Section 注册表、CLAUDE.md 多级合并，以及如何将零散上下文拼装为 API 可消费的缓存友好结构。"
-keywords: ["System Prompt", "系统提示词", "动态组装", "CLAUDE.md", "Prompt Cache", "缓存策略"]
+title: "系统提示词"
+description: "系统提示词不是一段写死的文本，而是一个动态组装、分块缓存的数组。理解三阶段管道、缓存分界标记和多级优先级选择的设计。"
+keywords: ["系统提示词", "System Prompt", "动态组装", "Prompt Cache", "缓存策略"]
 ---
 
-## 从数组到 API 调用：System Prompt 的完整链路
+## 核心问题
 
-System Prompt 在 Claude Code 中不是一段写死的文本，而是一个 **`string[]` 数组**（品牌类型 `SystemPrompt`，定义于 `src/utils/systemPromptType.ts:8`），经过组装、分块、缓存标记后发送给 API。
+AI 的行为由系统提示词（System Prompt）决定。但一个编程助手的系统提示词远不止一句"你是一个有用的助手"——它需要包含工具使用规则、安全策略、项目上下文、用户偏好等大量动态内容。
 
-### 三阶段管道
+挑战在于：**这些内容每次请求都要发送，而且大部分是不变的。** 如何在保持动态性的同时最小化 token 成本？
+
+## 从文本到数组：缓存驱动的架构选择
+
+系统提示词不是单个字符串，而是一个 **字符串数组**。
+
+### 为什么是数组？
+
+Anthropic 的 Prompt Cache 以**内容块**为单位缓存。将提示词拆为多个块，不变的部分可以获得独立的缓存命中。如果是一个单字符串，任何一个字符变化（如日期更新）都会导致整个提示词的缓存失效。
+
+一个典型的系统提示词约 20K+ tokens，通过缓存分块可以节省 30-50% 的输入 token 费用。
+
+### 品牌类型保证
+
+系统使用品牌类型（branded type）防止普通字符串数组被意外传入 API 调用——只有通过显式转换才能获得系统提示词类型。这是零开销的编译时安全保证。
+
+## 三阶段组装管道
 
 ```
-getSystemPrompt()          →  string[]       （组装内容）
-  ↓
-buildEffectiveSystemPrompt() →  SystemPrompt   （选择优先级路径）
-  ↓
-buildSystemPromptBlocks()  →  TextBlockParam[] （分块 + cache_control 标记）
+收集内容 → 选择优先级 → 分块 + 缓存标记
 ```
 
-1. **`getSystemPrompt()`**（`src/constants/prompts.ts:444`）—— 收集静态段 + 动态段，插入 `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 分界标记
-2. **`buildEffectiveSystemPrompt()`**（`src/utils/systemPrompt.ts:41`）—— 按 Override > Coordinator > Agent > Custom > Default 优先级选择
-3. **`buildSystemPromptBlocks()`**（`src/services/api/claude.ts:3214`）—— 调用 `splitSysPromptPrefix()` 分块，为每个块附加 `cache_control`
+### 第一阶段：内容收集
 
-## SystemPrompt 品牌类型
+系统提示词的内容分为两个区域：
 
-```typescript
-// src/utils/systemPromptType.ts:8
-export type SystemPrompt = readonly string[] & {
-  readonly __brand: 'SystemPrompt'
-}
-export function asSystemPrompt(value: readonly string[]): SystemPrompt {
-  return value as SystemPrompt  // 零开销类型断言
-}
-```
+| 区域 | 内容 | 特点 |
+|------|------|------|
+| **静态区** | 工具使用规则、安全策略、输出格式规范 | 所有用户相同 |
+| **动态区** | 记忆、MCP 指令、模型覆盖、语言偏好 | 因用户/会话而异 |
 
-品牌类型（branded type）防止普通 `string[]` 被意外传入 API 调用——只有通过 `asSystemPrompt()` 显式转换才能获得 `SystemPrompt` 类型。
+两个区域之间用一个特殊的**分界标记**分隔。这个标记永远不会发送给 AI——它只是告诉缓存系统："到这里为止是静态的，从这里开始是动态的"。
 
-## getSystemPrompt()：内容组装的全景
+### 第二阶段：优先级选择
 
-`src/constants/prompts.ts:444` 是 System Prompt 的核心工厂函数，返回一个有序数组：
+最终使用哪个提示词取决于五级优先级：
 
-| 阶段 | 内容 | 缓存策略 |
-|------|------|----------|
-| **静态区** | Intro Section、System Rules、Doing Tasks、Actions、Using Tools、Tone & Style、Output Efficiency | 可跨组织缓存（`scope: 'global'`） |
-| **BOUNDARY** | `SYSTEM_PROMPT_DYNAMIC_BOUNDARY = '__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__'` | 分界标记（不发送给 API，仅用于分割静态区与动态区以实现全局缓存） |
-| **动态区** | Session Guidance、Memory、Model Override、Env Info、Language、Output Style、MCP Instructions、Scratchpad、FRC、Summarize Tool Results、Token Budget、Brief | 每次会话不同（`scope: 'org'` 或无缓存） |
-
-> **Boundary 是什么**：它把 System Prompt 分成"不变的静态区"和"因用户/会话而异的动态区"。静态区对所有用户相同，可获得 `scope: 'global'` 跨组织缓存；动态区每次不同，只能 `scope: 'org'` 或不缓存。它本身是一个特殊字符串，在发送给 API 前被移除，AI 永远看不到。
-
-### 动态区的 Section 注册表
-
-动态区通过 `systemPromptSection()` / `DANGEROUS_uncachedSystemPromptSection()` 注册，这两个工厂函数定义于 `src/constants/systemPromptSections.ts`：
-
-```typescript
-// 缓存式 Section：计算一次，/clear 或 /compact 后才重新计算
-systemPromptSection('memory', () => loadMemoryPrompt())
-
-// 危险：每轮重新计算，会破坏 Prompt Cache
-DANGEROUS_uncachedSystemPromptSection(
-  'mcp_instructions',
-  () => isMcpInstructionsDeltaEnabled() ? null : getMcpInstructionsSection(mcpClients),
-  'MCP servers connect/disconnect between turns'  // 必须给出破坏缓存的理由
-)
-```
-
-`resolveSystemPromptSections()` 在每轮查询时解析所有 Section，对于 `cacheBreak: false` 的 Section，优先使用 `getSystemPromptSectionCache()` 中的缓存值。只有 MCP 指令等真正动态的内容使用 `DANGEROUS_uncachedSystemPromptSection`。
-
-### `CLAUDE_CODE_SIMPLE` 快速路径
-
-当环境变量 `CLAUDE_CODE_SIMPLE` 为真时，整个 System Prompt 缩减为一行：
-
-```typescript
-`You are Claude Code, Anthropic's official CLI for Claude.\n\nCWD: ${getCwd()}\nDate: ${getSessionStartDate()}`
-```
-
-跳过所有 Section 注册、缓存分块、动态组装——用于最小化 token 消耗的测试场景。
-
-## buildEffectiveSystemPrompt()：五级优先级
-
-`src/utils/systemPrompt.ts:41` 决定最终使用哪个 System Prompt：
-
-| 优先级 | 条件 | 行为 |
+| 优先级 | 来源 | 场景 |
 |--------|------|------|
-| **0. Override** | `overrideSystemPrompt` 非空 | 完全替换，返回 `[override]` |
-| **1. Coordinator** | `COORDINATOR_MODE` feature + 环境变量 | 使用协调者专用提示词 |
-| **2. Agent** | `mainThreadAgentDefinition` 存在 | Proactive 模式：追加到默认提示词尾部；否则：替换默认提示词 |
-| **3. Custom** | `--system-prompt` 参数指定 | 替换默认提示词 |
-| **4. Default** | 无特殊条件 | 使用 `getSystemPrompt()` 完整输出 |
+| **Override** | 外部覆盖 | SDK 集成、自动化测试 |
+| **Coordinator** | 协调者模式 | 多 Agent 编排 |
+| **Agent** | Agent 定义 | 自定义 Agent |
+| **Custom** | 命令行参数 | 用户的自定义提示词 |
+| **Default** | 完整组装 | 正常使用 |
 
-`appendSystemPrompt` 始终追加到末尾（Override 除外）。
+**设计考量**：Override 级别完全替换默认提示词（包括安全规则），这是危险的但必要的——自动化测试和 SDK 集成需要完全控制。其他级别则在默认提示词基础上追加或替换。
 
-## Provider 系统概述
+### 第三阶段：分块与缓存标记
 
-Claude Code 支持多种 API 提供商，分为两大类：
+分块策略根据条件选择三种模式：
 
-| 类别 | Provider | 环境变量 | 说明 |
-|------|----------|---------|------|
-| **1P (First Party)** | `firstParty` | 默认 | Anthropic 官方 API 直连 |
-| **3P (Third Party)** | `bedrock` | `CLAUDE_CODE_USE_BEDROCK=1` | AWS Bedrock 托管服务 |
-| **3P** | `vertex` | `CLAUDE_CODE_USE_VERTEX=1` | Google Vertex AI |
-| **3P** | `openai` | `CLAUDE_CODE_USE_OPENAI=1` | OpenAI 兼容层（Ollama/DeepSeek/vLLM） |
-| **3P** | `gemini` | `CLAUDE_CODE_USE_GEMINI=1` | Google Gemini API |
-| **3P** | `grok` | `CLAUDE_CODE_USE_GROK=1` | xAI Grok |
-
-Provider 决定了：
-- **可用的 beta headers**：部分 beta 功能仅限 1P 用户
-- **缓存策略**：全局缓存 `scope: 'global'` 仅 1P 可用
-- **Token 计数方式**：Bedrock 有独立的 countTokens 端点，OpenAI/Gemini 依赖估算
-
-```typescript
-// src/utils/model/providers.ts:5-13
-export type APIProvider =
-  | 'firstParty'    // 1P - Anthropic 直连
-  | 'bedrock'       // 3P - AWS Bedrock
-  | 'vertex'        // 3P - Google Vertex
-  | 'foundry'       // 3P - Anthropic Foundry
-  | 'openai'        // 3P - OpenAI 兼容层
-  | 'gemini'        // 3P - Google Gemini
-  | 'grok'          // 3P - xAI Grok
+**模式 1：全局缓存（1P 用户默认）**
+```
+[归属头]        → 不缓存
+[提示词前缀]    → 不缓存
+[静态内容]      → 全局缓存（跨组织共享）
+[动态内容]      → 不缓存
 ```
 
-## 缓存策略：分块、标记、命中
-
-这是 System Prompt 设计中最精密的部分。
-
-### Anthropic Prompt Cache 基础
-
-Anthropic API 的 Prompt Cache 允许跨请求复用相同的 System Prompt 前缀，按缓存命中量计费（远低于完整输入价格）。缓存键由内容的 Blake2b 哈希决定——任何字符变化都会导致缓存失效。
-
-### `splitSysPromptPrefix()`：三种分块模式
-
-`src/utils/api.ts:321` 是缓存策略的核心，根据条件选择三种分块模式：
-
-#### 模式 1：MCP 工具存在时（`skipGlobalCacheForSystemPrompt=true`）
-
+**模式 2：组织缓存（MCP 工具存在时）**
 ```
-[attribution header]    → cacheScope: null     （不缓存）
-[system prompt prefix]  → cacheScope: 'org'    （组织级缓存）
-[everything else]       → cacheScope: 'org'    （组织级缓存）
+[归属头]        → 不缓存
+[提示词前缀]    → 组织缓存
+[其余内容]      → 组织缓存
 ```
 
-MCP 工具列表在会话中可能变化（连接/断开），破坏了跨组织缓存的基础，因此降级为组织级。
-
-#### 模式 2：Global Cache + Boundary 存在（1P 专用）
-
+**模式 3：组织缓存（3P 用户）**
 ```
-[attribution header]    → cacheScope: null     （不缓存）
-[system prompt prefix]  → cacheScope: null     （不缓存）
-[static content]        → cacheScope: 'global' （全局缓存！跨组织共享）
-[dynamic content]       → cacheScope: null     （不缓存）
+[归属头]        → 不缓存
+[提示词前缀]    → 组织缓存
+[其余内容]      → 组织缓存
 ```
 
-这是缓存效率最高的模式。`SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 之前的静态内容（Intro、Rules、Tone & Style 等）对所有用户相同，可跨组织缓存。
+**为什么 MCP 工具会降级缓存**？MCP 工具列表在会话中可能变化（连接/断开），这会改变提示词内容，破坏跨组织缓存的基础。因此当 MCP 工具存在时，只能使用组织级缓存。
 
-> **Boundary 插入条件**：`SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 标记**仅在特定条件**下插入：
+### 缓存破坏的防御
 
-```typescript
-// src/utils/betas.ts:226-229
-export function shouldUseGlobalCacheScope(): boolean {
-  return (
-    getAPIProvider() === 'firstParty' &&
-    !isEnvTruthy(process.env.CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS)
-  )
-}
-```
+动态区的某些内容（如会话特定的工具集）必须严格放在分界标记之后。如果错误地放在静态区，每个运行时条件的组合会产生 2^N 种不同的哈希值（N = 条件数量），完全破坏缓存命中率。
 
-```typescript
-// src/constants/prompts.ts:574
-...(shouldUseGlobalCacheScope() ? [SYSTEM_PROMPT_DYNAMIC_BOUNDARY] : []),
-```
+系统对"每轮都重新计算"的 Section 使用专门的危险标记——开发者必须给出破坏缓存的理由才能使用它。
 
-这意味着：
-- **3P 用户（Bedrock/Vertex/OpenAI/Gemini）**：Boundary 永远不存在，始终使用模式 3
-- **1P 用户禁用实验性功能**：设置 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`，Boundary 不插入
-- **1P 用户默认**：Boundary 存在，使用模式 2（最高缓存效率）
+## 上下文注入：两条独立管道
 
-#### 模式 3：默认（3P 提供商 或 Boundary 缺失）
+系统提示词本身不包含运行时上下文。上下文通过两条独立管道注入：
 
-```
-[attribution header]    → cacheScope: null     （不缓存）
-[system prompt prefix]  → cacheScope: 'org'    （组织级缓存）
-[everything else]       → cacheScope: 'org'    （组织级缓存）
-```
+### System Context（会话级不变）
 
-### `getCacheControl()`：TTL 决策
+- Git 分支和状态
+- 最近的提交记录
+- 计算一次，整个会话期间缓存
 
-`src/services/api/claude.ts:359` 生成的 `cache_control` 对象：
+### User Context（动态变化）
 
-```typescript
-{
-  type: 'ephemeral',
-  ttl?: '1h',         // 仅特定 querySource 符合条件时
-  scope?: 'global',   // 仅静态区
-}
-```
+- 合并后的 CLAUDE.md 内容
+- 当前日期
 
-1 小时 TTL 的判定逻辑（`should1hCacheTTL()`，第 394 行）：
-- **Bedrock 用户**：通过环境变量 `ENABLE_PROMPT_CACHING_1H_BEDROCK` 启用
-- **1P 用户**：通过 GrowthBook 配置的 `allowlist` 数组匹配 `querySource`，支持前缀通配符（如 `"repl_main_thread*"`）
-- **会话级锁定**：资格判定结果在 bootstrap state 中缓存，防止 GrowthBook 配置中途变化导致同一会话内 TTL 不一致
-
-### 缓存破坏：Session-Specific Guidance 的放置
-
-`getSessionSpecificGuidanceSection()`（`src/constants/prompts.ts:352`）的内容必须放在 `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` **之后**。因为它包含：
-- 当前会话的 enabledTools 集合
-- `isForkSubagentEnabled()` 的运行时判定
-- `getIsNonInteractiveSession()` 的结果
-
-这些运行时 bit 如果放在静态区，会产生 2^N 种 Blake2b 哈希变体（N = 运行时条件数），完全破坏缓存命中率。源码注释明确警告：
-
-> Each conditional here is a runtime bit that would otherwise multiply the Blake2b prefix hash variants (2^N). See PR #24490, #24171 for the same bug class.
-
-### `CLAUDE_CODE_SIMPLE` 模式
-
-当设置了 `CLAUDE_CODE_SIMPLE` 环境变量时，整个系统提示词会大幅缩减：
-
-```typescript
-return [`You are Claude Code, Anthropic's official CLI for Claude.\n\nCWD: ${getCwd()}\nDate: ${getSessionStartDate()}`]
-```
-
-## 上下文注入：System Context 与 User Context
-
-System Prompt 数组本身不包含运行时上下文（git 状态、CLAUDE.md 内容）。上下文通过两个独立的管道注入：
-
-### System Context（`src/context.ts:116`）
-
-```typescript
-export const getSystemContext = memoize(async () => {
-  return {
-    gitStatus,           // git 分支、状态、最近提交（截断至 MAX_STATUS_CHARS=2000）
-    cacheBreaker,        // 仅 ant 用户的缓存破坏器
-  }
-})
-```
-
-- 使用 `lodash.memoize` 缓存——**整个会话期间只计算一次**
-- Git 状态快照包含 5 个并行 `git` 命令（branch、defaultBranch、status、log、userName）
-- `status` 超过 2000 字符时截断并附加提示使用 BashTool 获取更多信息
-- `systemPromptInjection` 变更时，通过 `getUserContext.cache.clear?.()` 清除所有上下文缓存
-
-### User Context（`src/context.ts:155`）
-
-```typescript
-export const getUserContext = memoize(async () => {
-  return {
-    claudeMd,            // 合并后的 CLAUDE.md 内容
-    currentDate,         // "Today's date is YYYY-MM-DD."
-  }
-})
-```
-
-- **CLAUDE.md 禁用条件**：`CLAUDE_CODE_DISABLE_CLAUDE_MDS` 环境变量，或 `--bare` 模式（除非通过 `--add-dir` 显式指定目录）
-- `--bare` 模式的语义是"跳过我没要求的东西"而非"忽略所有"
-
-### 注入位置
-
-在 `src/query.ts:449`：
-
-```typescript
-// System Context 追加到 System Prompt 尾部
-const fullSystemPrompt = asSystemPrompt(
-  appendSystemContext(systemPrompt, systemContext)  // 简单拼接
-)
-```
-
-User Context 通过 `prependUserContext()`（`src/utils/api.ts:449`）注入为 `<system-reminder>` 标签包裹的首条用户消息，放在所有对话消息之前。
-
-## Attribution Header：计费与安全
-
-每个 API 请求的 System Prompt 首块是 Attribution Header（`src/constants/system.ts:30`），包含：
-- **`cc_version`**：Claude Code 版本 + 指纹
-- **`cc_entrypoint`**：入口点标识（REPL / SDK / pipe 等）
-- **`cch=00000`**（NATIVE_CLIENT_ATTESTATION 启用时）：Bun 原生 HTTP 层在发送前将零替换为计算出的哈希值，服务器验证此 token 确认请求来自真实 Claude Code 客户端
-
-Header 始终 `cacheScope: null`——它因版本和指纹不同而变化，不适合缓存。
+**为什么 User Context 不放在 System Prompt 中**？因为 User Context 作为用户消息发送，可以利用 Prompt Cache 的前缀共享——系统提示词是所有用户共享的前缀，User Context 是每个用户的变化部分。这种分层让缓存命中率最大化。
 
 ## CLAUDE.md：项目级知识注入
 
-这是 Claude Code 最巧妙的设计之一。在项目根目录放一个 `CLAUDE.md` 文件，就能让 AI "理解" 你的项目：
+这是 Claude Code 最巧妙的设计之一。在项目目录中放一个 `CLAUDE.md` 文件，就能让 AI "理解"项目。
 
-- **项目概述**：这个项目做什么、用了什么技术栈
-- **开发约定**：代码风格、命名规范、分支策略
-- **常用命令**：怎么构建、怎么测试、怎么部署
-- **注意事项**：已知的坑、特殊的配置
-
-系统会自动发现并合并多级 CLAUDE.md：
+### 多级合并
 
 ```
 ~/.claude/CLAUDE.md              ← 用户全局（个人偏好）
@@ -292,77 +118,34 @@ Header 始终 `cacheScope: null`——它因版本和指纹不同而变化，不
         └── /project/src/CLAUDE.md  ← 子目录（模块特定）
 ```
 
-加载逻辑在 `src/utils/claudemd.ts` 中的 `getClaudeMds()` 和 `getMemoryFiles()` 实现——从 CWD 向上遍历目录树，合并所有匹配的 CLAUDE.md 文件内容。
+系统从当前工作目录向上遍历，合并所有匹配的 CLAUDE.md 文件。子目录的 CLAUDE.md 可以覆盖或补充父目录的规则。
 
-## 设计洞察：为什么是 `string[]` 而非单个 `string`
+**设计哲学**：项目知识应该由团队成员维护、随代码演进、可通过 git 追踪。CLAUDE.md 本质上是"给人读的项目文档，恰好 AI 也能读"。
 
-将 System Prompt 设计为数组而非单段文本，是为了 **缓存分块**：
+### 安全考量
 
-1. Anthropic Prompt Cache 以 **内容块**（TextBlock）为缓存单位
-2. 将 System Prompt 拆为多个块，可以让不变的部分（Intro、Rules）获得独立的缓存命中
-3. 如果是单个 `string`，任何一个字符变化（如日期更新）都会导致整个 System Prompt 的缓存失效
-4. `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 标记允许 `splitSysPromptPrefix()` 精确地将静态区标记为 `scope: 'global'`，动态区不标记或标记为 `scope: 'org'`
+项目级 CLAUDE.md 可以被仓库中的任何人修改（包括恶意贡献者）。系统因此限制了项目级 CLAUDE.md 的影响范围——它们不能覆盖安全关键设置，也不能修改权限模型。
 
-这是 Claude Code 在 token 成本优化上的核心设计——一次典型的 System Prompt 约 20K+ tokens，通过缓存分块可以节省 30-50% 的输入 token 费用。
+## Provider 差异与缓存
 
-## 兼容层：OpenAI 与 Gemini
+不同的 API Provider 有不同的缓存能力：
 
-Claude Code 提供了 OpenAI 和 Gemini 协议的兼容层，允许使用非 Anthropic 端点。
+| Provider | 全局缓存 | 精确 Token 计数 | 特殊 Beta 功能 |
+|----------|:--------:|:---------------:|:--------------:|
+| Anthropic 直连 | ✓ | ✓ | ✓ |
+| AWS Bedrock | ✗ | ✓（独立端点） | 部分 |
+| Google Vertex | ✗ | ✗ | 部分 |
+| OpenAI 兼容 | ✗ | ✗ | ✗ |
+| Gemini | ✗ | ✗ | ✗ |
 
-### OpenAI 兼容层
+3P 用户的系统提示词始终使用组织级缓存，因为没有全局缓存的 API 支持。这也意味着 token 计数依赖估算，影响自动压缩的触发时机。
 
-通过 `CLAUDE_CODE_USE_OPENAI=1` 启用，支持任意 OpenAI Chat Completions 协议端点（Ollama、DeepSeek、vLLM 等）。
+## 最小化模式
 
-实现采用**流适配器模式**：
-1. 将 Anthropic 格式请求转换为 OpenAI 格式
-2. 调用 OpenAI 兼容端点
-3. 将 SSE 流转换回 `BetaRawMessageStreamEvent`
-4. 下游代码完全无感知
+环境变量 `CLAUDE_CODE_SIMPLE` 可以将整个系统提示词缩减为一行——跳过所有 Section 注册、缓存分块和动态组装。用于最小化 token 消耗的测试场景。
 
-```
-src/services/api/openai/
-├── client.ts           # OpenAI 客户端配置
-├── convertMessages.ts  # 消息格式转换（Anthropic → OpenAI）
-├── convertTools.ts     # 工具定义转换
-├── streamAdapter.ts    # SSE 流适配（OpenAI → Anthropic）
-├── modelMapping.ts     # 模型名称映射
-└── index.ts            # 入口函数 queryModelOpenAI()
-```
-
-关键环境变量：
-- `CLAUDE_CODE_USE_OPENAI=1` — 启用 OpenAI provider
-- `OPENAI_API_KEY` — API 密钥
-- `OPENAI_BASE_URL` — API 端点（默认 `https://api.openai.com/v1`）
-- `OPENAI_MODEL` — 直接指定模型名
-
-### Gemini 兼容层
-
-通过 `CLAUDE_CODE_USE_GEMINI=1` 启用，支持 Google Gemini API。
-
-```
-src/services/api/gemini/
-├── client.ts           # Gemini 客户端配置
-├── convertMessages.ts  # 消息格式转换
-├── convertTools.ts     # 工具定义转换
-├── streamAdapter.ts    # 流适配
-├── modelMapping.ts     # 模型名称映射
-├── types.ts            # 类型定义
-└── index.ts            # 入口函数
-```
-
-关键环境变量：
-- `CLAUDE_CODE_USE_GEMINI=1` — 启用 Gemini provider
-- `GEMINI_API_KEY` — API 密钥
-- `GEMINI_BASE_URL` — API 端点（默认 `https://generativelanguage.googleapis.com/v1beta`）
-- `GEMINI_MODEL` — 直接指定模型名
-- `GEMINI_DEFAULT_SONNET_MODEL` / `GEMINI_DEFAULT_OPUS_MODEL` — 按能力级别映射
-
-### 兼容层的限制
-
-使用 3P 兼容层时，部分功能受限：
-- **无精确 token 计数**：系统退回到近似估算，影响自动压缩触发时机
-- **无全局缓存**：只能使用组织级缓存 `scope: 'org'`
-- **部分 beta 功能不可用**：依赖 Anthropic 特有 beta headers 的功能受限
-
-详见 `docs/plans/openai-compatibility.md` 和 `CLAUDE.md` 中的相关章节。
+## 接下来
 
+- **上下文压缩** — 理解当上下文增长超出限制时的压缩策略
+- **令牌预算** — 了解 token 窗口的动态计算
+- **Provider 系统** — 了解多 Provider 支持的架构设计

docs/context/token-budget.mdx

@@ -1,195 +1,128 @@
 ---
-title: "Token 预算管理 - 上下文窗口动态计算"
-description: "从源码角度揭示 Claude Code token 预算管理：200K 上下文窗口的动态计算、截断机制、缓存优化和自动压缩的完整链路。"
-keywords: ["Token 预算", "上下文窗口", "token 计算", "截断机制", "缓存优化"]
+title: "令牌预算"
+description: "200K 上下文窗口不是全部。理解 Claude Code 如何管理 token 预算：动态计算、近似 vs 精确计数、分层压缩策略和缓存优化。"
+keywords: ["Token 预算", "上下文窗口", "token 计算", "压缩策略"]
 ---
 
-{/* 本章目标：从源码角度揭示 token 预算的动态计算、截断机制、缓存优化和自动压缩的完整链路 */}
+## 核心约束：200K 不是全部
 
-## 上下文窗口：200K 不是全部
-
-Claude Code 的默认上下文窗口为 200K tokens（`MODEL_CONTEXT_WINDOW_DEFAULT = 200_000`），但实际可用于对话的空间远小于此：
+Claude 的上下文窗口为 200K tokens（部分模型支持 1M），但实际可用于对话的空间远小于此：
 
 ```
 上下文窗口（200K）
-├── 系统提示词（~15-25K，缓存后成本低）
+├── 系统提示词（~15-25K）
 ├── 工具定义（~10-20K，含 MCP 工具）
 ├── 用户上下文（CLAUDE.md、git status 等）
-├── 输出预留（maxOutputTokens）
-│   ├── 默认上限：64K
-│   ├── 实际默认：8K（slot-reservation 优化）
-│   └── 触顶自动升级：一次 64K 重试
-└── 剩余：对话历史空间（随对话增长）
+├── 输出预留（AI 响应的空间）
+└── 剩余：对话历史空间（随对话增长而缩小）
 ```
 
-`getContextWindowForModel()`（`src/utils/context.ts:51`）按 5 级优先级解析窗口大小：
+**设计挑战**：对话历史不断增长，可用空间持续缩小。系统必须在"保留足够的上下文让 AI 理解对话"和"不超出 token 限制"之间持续平衡。
 
-1. `CLAUDE_CODE_MAX_CONTEXT_TOKENS` 环境变量覆盖
-2. 模型名含 `[1m]` 后缀 → 1M tokens
-3. `getModelCapability(model).max_input_tokens`
-4. 1M beta header + 支持的模型（claude-sonnet-4, opus-4-6）
-5. 兜底：200K
+### 上下文窗口的动态解析
 
-**有效上下文** = 窗口大小 - min(maxOutputTokens, 20K)，因为压缩摘要需要预留输出空间。
+上下文窗口大小不是硬编码的。系统按优先级从多个来源解析：
+
+1. 用户环境变量覆盖（强制指定）
+2. 模型名后缀标记（如 `[1m]` 表示 1M 窗口）
+3. 模型自身的能力声明
+4. 特定 beta 功能的支持情况
+5. 兜底值：200K
+
+这种分层解析意味着同一个系统可以适配不同模型和不同配置，而不需要为每种情况写特殊逻辑。
 
 ## Token 计数：近似 vs 精确
 
-系统使用两级 token 计数策略：
+Token 计数是所有预算决策的基础。系统采用两级策略：
 
 ### 近似估算（毫秒级）
 
-```typescript
-// src/services/tokenEstimation.ts
-function roughTokenCountEstimation(content: string, bytesPerToken = 4): number {
-  return Math.round(content.length / bytesPerToken)
-}
-```
+基于一个简单的经验公式：大约每 4 个字节 ≈ 1 个 token。对不同内容类型有调整：
+- **JSON/JSONL**：更密集，每 2 字节 ≈ 1 token
+- **图片/文档**：固定估算值（基于尺寸上限的保守估计）
+- **普通文本**：每 4 字节 ≈ 1 token
 
-对不同内容类型有特殊处理：
-- **JSON/JSONL**：`bytesPerToken = 2`（密集的 `{`, `:`, `,` 符号，每个仅 1-2 token）
-- **图片/文档**：固定 2000 tokens（基于 2000×2000px 上限的保守估计）
-- **thinking block**：按实际文本长度 / 4
-- **tool_use**：序列化 `name + JSON.stringify(input)` 后 / 4
+### 精确计数（需要 API 调用）
 
-### 精确计数（API 调用）
+使用 Anthropic 的 token 计数端点。不同 Provider 的支持程度不同：
 
-使用 Anthropic 的 `beta.messages.countTokens` 端点。在不同 provider 上有不同路径：
+| Provider 类别 | 精确计数支持 | 注意事项 |
+|---------------|-------------|----------|
+| Anthropic 直连 | 原生支持 | 最准确 |
+| 云平台（Bedrock/Vertex） | 各自的 SDK 接口 | 需要额外依赖 |
+| 第三方兼容（OpenAI/Gemini/Grok） | 不支持 | 退回近似估算 |
 
-| Provider | 方法 |
-|----------|------|
-| Anthropic 直连 | `anthropic.beta.messages.countTokens()` |
-| AWS Bedrock | `@aws-sdk/client-bedrock-runtime` 的 `CountTokensCommand` |
-| Google Vertex | Anthropic SDK + beta 过滤 |
-| 兜底（Bedrock 不支持） | 用 Haiku 发送 `max_tokens=1` 的请求，读取 `usage.input_tokens` |
+### 为什么需要两级策略
 
-精确计数在关键决策点使用（压缩前后对比、warning 判断），近似估算在热路径使用（每轮循环的 shouldAutoCompact 检查）。
+近似估算用于**热路径**——每轮 agentic loop 都需要判断"是否需要压缩"，这个检查必须足够快。精确计数用于**关键决策点**——压缩前后对比、费用计算等需要准确数字的场景。
 
-### 3P Provider 的 Token 计数差异
+**设计权衡**：近似估算可能偏差 10-20%，这意味着自动压缩的触发时机可能略有提前或延后。但这个偏差是可以接受的——提前压缩只多花一点 token，延后压缩最多触发一次 API 错误然后紧急压缩。
 
-不同 Provider 的精确 token 计数实现方式不同，部分 provider 甚至不支持精确计数：
+## 分层压缩策略
 
-| Provider | 计数方式 | 注意事项 |
-|----------|---------|---------|
-| **Anthropic 直连** | `anthropic.beta.messages.countTokens()` | 标准 API，最准确 |
-| **AWS Bedrock** | `CountTokensCommand` | 需要动态加载 279KB AWS SDK |
-| **Google Vertex** | Anthropic SDK + beta 过滤 | 需要特定 beta headers |
-| **OpenAI 兼容层** | 无精确计数 | **退回到近似估算** |
-| **Gemini 兼容层** | 无精确计数 | **退回到近似估算** |
-| **Bedrock 不支持时** | 用 Haiku 发送 `max_tokens=1` 请求 | 读取 `usage.input_tokens` |
+系统不是等到"满了才压缩"，而是采用了由轻到重的分层策略：
 
-OpenAI 和 Gemini 兼容层**不支持精确 token 计数**，系统会退回到近似估算。这会影响：
-- **自动压缩触发时机**：可能略有偏差
-- **压缩前后 token 对比**：仅为估算值，非精确
-- **Warning/Error 阈值判断**：基于估算而非精确计数
+### 第一层：工具结果截断
 
-```typescript
-// src/services/tokenEstimation.ts - 近似估算函数
-function roughTokenCountEstimation(content: string, bytesPerToken = 4): number {
-  return Math.round(content.length / bytesPerToken)
-}
-```
+单个工具的输出有硬性上限（通常 100K 字符）。超长的命令输出、文件内容在写入消息前就被截断。
 
-源码路径：`src/services/tokenEstimation.ts`
+这是最轻量的"压缩"——只是防止单个工具结果占用过多空间。
 
-## 自动压缩的触发阈值
+### 第二层：微压缩（Micro-Compact）
 
-```
-src/services/compact/autoCompact.ts — 核心阈值
-```
+在触发全量压缩之前，系统先尝试只压缩旧的工具调用结果：
 
-| 常量 | 值 | 含义 |
-|------|----|------|
-| `AUTOCOMPACT_BUFFER_TOKENS` | 13,000 | 窗口减去此值 = 自动压缩触发点 |
-| `WARNING_THRESHOLD_BUFFER_TOKENS` | 20,000 | 在触发点 + 20K 处显示警告 |
-| `ERROR_THRESHOLD_BUFFER_TOKENS` | 20,000 | 在触发点 + 20K 处显示错误 |
-| `MANUAL_COMPACT_BUFFER_TOKENS` | 3,000 | 手动 /compact 的阻塞上限 |
-| `MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES` | 3 | 连续失败 3 次后停止尝试 |
-
-以 200K 窗口为例：
-- **~167K**：warning 闪烁，用户看到建议压缩的提示
-- **~180K**：自动压缩触发（200K - 20K 输出预留 = 180K 有效，再 - 13K buffer）
-- **~197K**：达到 blocking limit，新消息被阻止
-
-`shouldAutoCompact()` 有多个逃逸条件：
-- `compact` / `session_memory` 来源的查询永不触发（防递归死锁）
-- `DISABLE_COMPACT` / `DISABLE_AUTO_COMPACT` 环境变量
-- 用户配置 `autoCompactEnabled = false`
-- Context Collapse 模式激活时抑制（collapse 自己管理上下文）
-- Reactive Compact 实验模式下抑制主动压缩
-- 超过连续失败上限（circuit breaker）
-
-## Micro-Compact：工具结果的渐进式压缩
-
-在触发全量压缩之前，系统先尝试 **micro-compact**——只压缩旧的工具调用结果：
-
-```
-可压缩工具列表（COMPACTABLE_TOOLS）：
-FileRead, Bash, Grep, Glob, WebSearch, WebFetch, FileEdit, FileWrite
-```
-
-策略基于时间：
-- 超过一定时间（由 `timeBasedMCConfig` 控制）的工具结果被替换为简短占位符
+- 超过一定时间的工具结果被替换为简短占位符
 - 图片/文档结果替换为 `[image]` / `[document]` 文本
-- 每次替换释放 tokens，可能推迟全量压缩
+- 每次替换释放 token，可能推迟全量压缩的触发
 
-工具本身也有 `maxResultSizeChars`（通常 100K）硬限制，超长结果在写入消息前就被截断。
+**设计考量**：为什么不直接全量压缩？因为全量压缩需要调用 AI 生成摘要，成本高且耗时。微压缩是确定性操作（简单替换），几乎零成本，可以频繁执行。
 
-## 全量压缩的完整流程
+### 第三层：自动压缩（Auto-Compact）
 
-```
-autoCompactIfNeeded() / compactConversation()
-  ↓
-1. 执行 PreCompact hooks（外部可注入自定义指令）
-  ↓
-2. 尝试 Session Memory 压缩（更轻量，优先尝试）
-  ↓
-3. Session Memory 失败 → 全量压缩
-   a. 图片/文档从消息中剥离（替换为 [image]/[document]）
-   b. skill_discovery/skill_listing 附件剥离（压缩后会重新注入）
-   c. 通过 forked agent 发送摘要请求（复用主线程的 prompt cache）
-   d. 如果摘要请求本身触发 prompt-too-long → truncateHeadForPTLRetry()
-      从最老的 API 轮次开始删除，重试最多 3 次
-   ↓
-4. 压缩成功后重建上下文：
-   - compactBoundaryMarker（记录压缩类型、前 token 数等）
-   - 摘要消息（不可见的 user 消息）
-   - 最近 5 个文件的重新读取（POST_COMPACT_TOKEN_BUDGET = 50K）
-   - plan 文件附件（如果有）
-   - plan mode 指令（如果在计划模式中）
-   - 已调用的 skill 内容（每 skill ≤5K，总计 ≤25K）
-   - deferred tools / agent listing / MCP 指令的增量重新注入
-   - SessionStart hooks 重新执行
-   - PostCompact hooks 执行
-  ↓
-5. 更新缓存基线，防止被误判为 cache break
-```
+当对话接近 token 上限时，系统用 AI 自身来总结之前的对话：
 
-### Prompt Cache Sharing
+1. **剥离非必要内容**：图片、文档附件被替换为文本标记
+2. **生成摘要**：通过一个独立的 agent 调用生成对话摘要
+3. **重建上下文**：用摘要替代原始对话，同时重新注入关键信息（最近操作的文件、活跃的计划等）
 
-压缩 API 调用是整个会话中最昂贵的操作之一。系统通过 `runForkedAgent` 复用主线程的缓存前缀（system prompt + tools + context messages），将缓存命中率从 2% 提升到接近 100%。这个优化单独节省了舰队级约 0.76% 的 `cache_creation` tokens。
+**设计考量**：压缩后会重新读取最近操作的 5 个文件。这是因为在实际使用中，AI 最可能需要的就是刚刚操作过的文件——重新读取它们比让 AI 再次搜索更高效。
+
+### 压缩的安全阀
+
+- **连续失败上限**：连续 3 次压缩失败后停止尝试（断路器模式）
+- **压缩来源的查询不触发压缩**：防止压缩本身触发无限递归
+- **手动压缩**：用户可以随时通过 `/compact` 主动触发
+
+## 缓存感知的压缩设计
+
+压缩操作本身需要调用 API 生成摘要——这是整个会话中最昂贵的操作之一。系统通过**复用主线程的缓存前缀**来优化：
+
+系统 prompt + 工具定义 + 上下文消息通常不变，这部分可以通过 API 的 prompt cache 机制缓存。压缩时的摘要请求复用了这些缓存，使得缓存命中率从接近 0% 提升到接近 100%。
+
+**设计洞察**：这不是一个独立的优化——它是整个缓存策略的一部分。系统 prompt 的组装策略（"不变内容在前"）和压缩时的缓存复用，都是为了最大化 prompt cache 的命中率。
 
 ## 输出 Token 的 Slot 优化
 
-一个经常被忽视的优化：**maxOutputTokens 的动态调整**。
+一个容易被忽视但影响深远的优化：AI 输出的 token 上限默认只设为 8K，而不是模型支持的最大值（32K 或 64K）。
 
-```typescript
-// src/services/api/claude.ts — getMaxOutputTokensForModel()
-const defaultTokens = isMaxTokensCapEnabled()
-  ? Math.min(maxOutputTokens.default, 8_000)  // 默认降到 8K
-  : maxOutputTokens.default                     // 原始默认 32K/64K
-```
+**为什么**？因为 API 服务端按 `max_tokens` 参数预留推理容量（slot）。99% 的请求实际输出不到 5K tokens，但如果所有请求都预留 32K 的 slot，会导致严重的容量浪费。
 
-为什么？因为 API 的 slot 机制按 `max_tokens` 预留推理容量。BQ p99 输出仅 4,911 tokens，32K 默认值浪费了 8-16 倍的 slot 容量。降到 8K 后，不到 1% 的请求被截断——这些请求会自动获得一次 64K 的 clean retry。
+降到 8K 后，不到 1% 的请求会被截断——这些请求自动获得一次高上限的干净重试。
 
-这个优化对 token 预算的影响是间接的：更多的 slot 容量意味着更少的排队延迟，间接减少了超时和重试。
+**设计哲学**：用 1% 的请求多一次重试的代价，换取 99% 请求的更快响应。这是一个典型的"优化常见路径，用重试处理边缘情况"的设计模式。
 
-## Partial Compact：选择性地压缩
+## 选择性压缩
 
-除了全量压缩，用户还可以在消息历史中选择某个位置，只压缩该位置之前或之后的内容：
+除了全量压缩，用户还可以选择只压缩对话的某一部分：
 
-- **`up_to` 方向**：压缩选中消息之前的内容，保留最近的对话
-- **`from` 方向**：压缩选中消息之后的内容，保留早期的对话
+- **压缩早期内容**（保留最近对话）：适用于"开头说了很多背景，但后面只需要关注最近操作"的场景
+- **压缩近期内容**（保留早期对话）：适用于"早期的架构决策很重要，但最近的工具调用结果不需要"的场景
 
-`from` 方向保留 prompt cache（前缀不变），`up_to` 方向则破坏 cache（摘要插在保留内容之前）。
+两种方向对缓存有不同的影响——保留前缀（早期内容）可以维持 prompt cache，修改前缀则破坏缓存。
 
-两种方向的 PTL（prompt-too-long）重试策略相同：从最老的 API 轮次开始删除，确保至少保留一组消息供摘要。
+## 接下来
+
+- **上下文压缩** — 深入了解压缩的触发条件和摘要生成机制
+- **项目记忆** — 理解跨会话的记忆持久化设计
+- **穷鬼模式** — 了解如何减少 token 消耗

docs/conversation/multi-turn.mdx

@@ -1,203 +1,130 @@
 ---
-title: "多轮对话管理 - QueryEngine 会话编排与持久化"
-description: "从源码角度解析 Claude Code 多轮对话管理：QueryEngine 的会话状态机、JSONL transcript 持久化、成本追踪模型和模型热切换机制。"
+title: "多轮对话"
+description: "理解 Claude Code 的会话编排设计：为什么需要 QueryEngine？会话如何持久化？成本如何追踪？模型如何热切换？"
 keywords: ["多轮对话", "会话管理", "QueryEngine", "transcript", "成本追踪"]
-sourceRef: "3ec5675 (2026-04-08)"
 ---
 
-{/* 本章目标：从源码角度揭示会话编排、持久化存储、成本追踪和模型切换的完整链路 */}
+## 单轮 vs 多轮
 
-## 单轮 vs 多轮：架构层面的差异
+- **单轮**（一次 Agentic Loop）：用户说一句话，AI 可能执行多步工具调用后返回结果
+- **多轮**（一个会话）：用户和 AI 反复对话，持续数分钟到数小时
 
-- **单轮**（一次 Agentic Loop）：`query()` 函数的一次完整执行——组装上下文 → 调 API → 处理工具调用 → 循环直到结束
-- **多轮**（一个 Session）：`QueryEngine` 类管理的一次会话——跨越数十轮 `submitMessage()` 调用，持续数小时
+单轮关注"AI 如何自主完成任务"，多轮关注"如何管理一个持续演进的会话"——这是完全不同的工程问题。
 
-`QueryEngine`（`src/QueryEngine.ts`，类定义）是单轮 Agentic Loop 之上的**会话编排器**，它管理的状态远不止消息列表：
+## 为什么需要会话编排器
+
+单轮的 Agentic Loop 已经很复杂了（错误恢复、上下文压缩、流式处理）。多轮在此基础上还需要管理：
+
+- **对话历史的累积**：消息不断增长，需要压缩策略
+- **成本的持续追踪**：跨轮次的 token 用量累计
+- **模型的热切换**：用户可能中途换模型
+- **会话的持久化与恢复**：意外中断后能继续
+- **文件的快照与回滚**：AI 改了文件，用户想撤回
+
+这些职责与"执行一次 agentic loop"无关，所以系统引入了 **QueryEngine** 作为会话编排器——它在 Agentic Loop 之上管理会话级别的状态。
+
+### 设计原则：编排器不参与循环
+
+QueryEngine 只负责"准备好上下文，然后调用 agentic loop"。它不干预单轮循环的内部逻辑——循环中的错误恢复、工具执行、上下文压缩都是自治的。
+
+这种分层使得 agentic loop 可以独立测试和优化，而不受会话状态管理的影响。
+
+## 会话持久化
+
+### 为什么持久化很重要
+
+终端会话是脆弱的——网络断开、进程崩溃、意外关闭都可能丢失对话。持久化确保用户的工作不丢失。
+
+### 设计选择：JSONL 追加写入
+
+对话事件以 JSONL（每行一条 JSON）格式追加写入磁盘。
+
+为什么选择 JSONL 而不是数据库或 JSON 文件？
+
+| 方案 | 优势 | 劣势 |
+|------|------|------|
+| **JSONL 追加写入** | 写入快速、不需要读-改-写、崩溃安全 | 查询需要扫描整个文件 |
+| JSON 文件 | 结构清晰 | 每次写入需要读取整个文件、修改、写回——大文件很慢 |
+| SQLite 数据库 | 查询高效 | 引入额外依赖、事务管理复杂 |
+
+追加写入是关键设计：每次新消息只需要在文件末尾追加一行，不需要读取和修改已有内容。即使写入过程中崩溃，也只会丢失最后一条记录，不会损坏整个文件。
+
+### 存储结构
 
 ```
-QueryEngine 内部状态（src/QueryEngine.ts 构造函数）
-├── mutableMessages: Message[]         ← 完整对话历史，跨 turn 累积
-├── readFileState: FileStateCache      ← 已读文件内容缓存，避免重复读取
-├── totalUsage: NonNullableUsage       ← 累计 token 消耗（input/output/cache）
-├── permissionDenials: SDKPermissionDenial[]  ← 权限拒绝记录
-├── discoveredSkillNames: Set<string>  ← 当前 turn 已发现的 skill
-├── loadedNestedMemoryPaths: Set<string>  ← 已加载的嵌套 memory 路径（防重复）
-├── hasHandledOrphanedPermission: boolean  ← 是否已处理孤立权限请求
-└── abortController: AbortController   ← 会话级中断控制
+~/.claude/projects/<项目目录>/
+  ├── <session-1>.jsonl
+  ├── <session-2>.jsonl
+  └── ...
 ```
 
-## QueryEngine 的核心方法：submitMessage()
+每个项目的会话归入同一目录。同一项目的对话可以跨会话积累上下文。
 
-每次用户输入一条消息，REPL 或 SDK 调用 `submitMessage()`，它会执行完整的 turn 初始化链路：
+### 大小防护
 
-```typescript
-// src/QueryEngine.ts — QueryEngine.submitMessage() 简化流程
-async *submitMessage(
-  prompt: string | ContentBlockParam[],
-  options?: { uuid?: string; isMeta?: boolean },
-): AsyncGenerator<SDKMessage> {
-  // 1. 清除 turn 级追踪状态
-  this.discoveredSkillNames.clear()
+读取上限为 50MB。超过这个大小的会话文件不会被完整加载——这是防止超大会话导致内存溢出的安全措施。
 
-  // 2. 解析模型（用户可能中途通过 setModel() 切换了模型）
-  const mainLoopModel = this.config.userSpecifiedModel
-    ? parseUserSpecifiedModel(this.config.userSpecifiedModel)
-    : getMainLoopModel()
+### 会话恢复
 
-  // 3. 动态组装 System Prompt（每次 turn 都重新构建）
-  const { defaultSystemPrompt, userContext, systemContext } =
-    await fetchSystemPromptParts({ tools, mainLoopModel, mcpClients })
+当用户使用 `--resume` 恢复会话时，系统：
 
-  // 4. 包装权限检查（追踪每次拒绝）
-  const wrappedCanUseTool = async (tool, input, ...) => {
-    const result = await canUseTool(tool, input, ...)
-    if (result.behavior !== 'allow') {
-      this.permissionDenials.push({
-        type: 'permission_denial',
-        tool_name: sdkCompatToolName(tool.name),
-        tool_use_id: toolUseID,
-        tool_input: input,
-      })
-    }
-    return result
-  }
+1. 从 JSONL 文件重建消息数组
+2. 恢复累计费用状态
+3. 恢复用户选择的模型和配置
+4. 从中断点继续对话
 
-  // 5. 调用核心 query() 函数执行 agentic loop
-  yield* query({
-    systemPrompt, messages: this.mutableMessages,
-    tools, model: mainLoopModel, ...
-  })
-}
-```
+整个过程对用户是透明的——恢复后的对话就像从来没有中断过。
 
-关键设计：`submitMessage()` 是 `async *Generator`——它逐步 yield `SDKMessage`，让调用方（REPL/SDK）能实时展示进度，而不是等整个 turn 结束。
+## 成本追踪
 
-## 会话持久化：JSONL Transcript
+### 为什么需要成本追踪
 
-每次对话事件都被追加写入 transcript 文件（`src/utils/sessionStorage.ts`）：
+AI API 按 token 计费，一次复杂任务可能消耗大量 token。没有成本追踪，用户无法判断"这次对话花了多少钱"，也无法在费用过高时及时终止。
 
-### 存储路径
+### 三层追踪架构
 
-```
-~/.claude/projects/<sanitized-cwd>/<session-uuid>.jsonl
-```
+| 层 | 职责 | 持久性 |
+|----|------|--------|
+| **记录层** | 从每个 API 响应中提取 token 用量 | 实时 |
+| **累计层** | 按模型汇总累计费用（切换模型时分别统计） | 会话内 |
+| **持久化层** | 会话结束时保存到项目配置 | 跨重启 |
 
-- 路径由 `getProjectDir(originalCwd)` 生成，使用 `sanitizePath()` 将项目目录路径转换为安全的目录名（非 hash），同一项目目录的会话归入同一子目录
-- 每条记录是一行 JSON（JSONL 格式），支持追加写入而不需要读取-修改-写入整个文件
-- 读取上限为 50MB（`MAX_TRANSCRIPT_READ_BYTES` 常量，`src/utils/sessionStorage.ts`），防止超大会话导致 OOM
+### 预算提醒
 
-### Transcript 写入器
-
-`Project` 类（`src/utils/sessionStorage.ts`，私有类）管理 transcript 的写入。它通过 `writeQueues`（按文件分组的写队列）和 `drainWriteQueue()`（定时批量刷写）确保并发消息追加不会互相覆盖：
-
-```
-写入流程（异步排队路径）：
-  recordTranscript(sessionId, entry)
-    ↓
-  project.enqueueWrite(filePath, entry)    ← 入列到 writeQueues
-    ↓
-  scheduleDrain()                          ← 设置定时器（FLUSH_INTERVAL_MS）
-    ↓
-  drainWriteQueue()                        ← 按 MAX_CHUNK_BYTES 分批
-    ↓  写入每批
-  appendToFile(path, batchContent)         ← 批量追加
-    ↓
-  如果配置了远程持久化：
-    persistToRemote(sessionId, entry)
-      ├── CCR v2: internalEventWriter('transcript', entry)
-      └── v1 Ingress: sessionIngress.appendSessionLog(...)
-
-同步直写路径（用于元数据重写等场景）：
-  appendEntryToFile(fullPath, entry)       ← 同步 appendFileSync
-    ↓
-  失败时 mkdir + 重试
-```
-
-### 会话恢复链路
-
-`--resume` 参数触发的恢复流程（`src/main.tsx` 中 `--resume` 分支）：
-
-```
-1. 解析 resume 参数：
-   ├── UUID 格式 → getTranscriptPathForSession(uuid)
-   ├── .jsonl 文件路径 → 直接使用
-   └── boolean → 最近一次会话的 picker
-   
-2. loadTranscriptFromFile(path)
-   ├── 按 JSONL 行解析
-   ├── 过滤出消息类型记录
-   └── 重建 Message[] 数组
-
-3. 恢复上下文状态：
-   ├── restoreCostStateForSession(sessionId)  ← 恢复累计费用
-   ├── 恢复 agentSetting（用户选择的 Agent 类型）
-   └── 如果有 --rewind-files，恢复文件到指定消息时的快照
-
-4. 创建 QueryEngine({ initialMessages: restoredMessages })
-   └── 从恢复的消息继续对话
-```
-
-## 成本追踪：从 API Usage 到美元
-
-成本追踪贯穿三个模块，形成完整的记录→累计→展示链路：
-
-### 记录层：API 响应中的 Usage
-
-每个 `message_delta` 事件携带 `usage` 字段（`input_tokens`、`output_tokens`、`cache_creation_input_tokens`、`cache_read_input_tokens`）。`accumulateUsage()` 将增量 usage 累加到会话总量。
-
-### 累计层：cost-tracker.ts
-
-```typescript
-// src/cost-tracker.ts — StoredCostState 类型定义
-type StoredCostState = {
-  totalCostUSD: number                       // 累计美元花费
-  totalAPIDuration: number                   // API 调用总时长（含重试）
-  totalAPIDurationWithoutRetries: number     // 不含重试的纯推理时间
-  totalToolDuration: number                  // 工具执行总时长
-  totalLinesAdded: number                    // 代码增加行数
-  totalLinesRemoved: number                  // 代码删除行数
-  lastDuration: number | undefined           // 最近一次会话时长
-  modelUsage: { [modelName: string]: ModelUsage } | undefined  // 按模型分拆的用量
-}
-```
-
-`addToTotalSessionCost()` 根据模型定价计算每次 API 调用的费用，累计到 `totalCostUSD`。按模型的 `ModelUsage` 支持在同一会话中切换模型后分别统计。
-
-### 持久化：跨重启保留
-
-```typescript
-// 每次会话结束时保存到项目配置
-saveCurrentSessionCosts(sessionId)
-  → projectConfig.lastCost = totalCostUSD
-  → projectConfig.lastSessionId = sessionId
-  → projectConfig.lastModelUsage = modelUsage
-```
-
-### 预算熔断
-
-`QueryEngineConfig.maxBudgetUsd` 提供了会话级的硬性预算上限。在 REPL 中，当累计费用超过 $5 时（`src/screens/REPL.tsx` 中费用阈值 `useEffect`），弹出费用提醒对话框——这不是硬性阻断，而是"软提醒"，且仅在 `hasConsoleBillingAccess()` 为 true 时显示。
+系统提供会话级的预算上限。当累计费用超过阈值时弹出提醒——这不是硬性阻断，而是"软提醒"。设计上选择了提醒而非强制终止，因为用户可能正在进行关键操作（如修复生产 bug），强制终止可能造成更大损失。
 
 ## 模型热切换
 
-在一个会话中切换模型不会丢失对话历史——因为 `mutableMessages` 与模型选择是解耦的：
+### 设计挑战
 
-```
-/model sonnet → QueryEngine.setModel('claude-sonnet-4-20250514')
-  ↓  实际操作：this.config.userSpecifiedModel = model（QueryEngine.setModel() 方法）
-下一次 submitMessage() 开始时：
-  ↓
-parseUserSpecifiedModel(this.config.userSpecifiedModel)
-  → 返回新的模型配置
-  ↓
-fetchSystemPromptParts({ mainLoopModel: newModel })
-  → System Prompt 根据新模型能力重新组装
-  ↓
-query({ model: newModel, messages: this.mutableMessages })
-  → 使用完整历史 + 新模型继续对话
-```
+在一个持续对话中切换模型看似简单，实际上需要解决几个问题：
 
-切换模型时，`contextWindowTokens` 和 `maxOutputTokens` 也会根据新模型的规格重新计算——例如从 Sonnet 切换到 Opus 时，上下文窗口可能从 200K 变为 1M。
+1. **上下文窗口不同**：Sonnet 的 200K 和 Opus 的 1M 需要不同的压缩策略
+2. **对话历史兼容**：旧模型生成的内容新模型需要能理解
+3. **费用计算**：不同模型定价不同，需要分别统计
+
+### 设计决策：消息与模型解耦
+
+对话历史（消息数组）和模型选择是独立的。切换模型只改变"下一次 API 调用用什么模型"，不修改已有消息。系统会在下次调用前根据新模型的规格重新计算上下文窗口和输出限制。
+
+这意味着用户可以在对话中随时切换模型——例如用便宜的 Sonnet 做简单操作，遇到复杂问题时切换到 Opus——而不需要开始新的会话。
 
 ## 文件快照与回滚
 
-`fileHistoryMakeSnapshot()`（`src/utils/fileHistory.ts`）在 AI 每次修改文件前自动保存当前内容。快照绑定到具体的 `message.id`，使得 `--rewind-files <user-message-id>` 可以精确恢复到对话中任意时间点的文件状态——这比 git 更细粒度（git 只追踪已提交的内容）。
+### 比 git 更细粒度的追踪
+
+AI 每次修改文件前，系统自动保存当前文件内容的快照。快照绑定到具体的消息 ID，使得用户可以精确恢复到对话中任意时间点的文件状态。
+
+这比 `git checkout` 更细粒度——git 只追踪已提交的内容，而文件快照追踪的是 AI 每一次修改前的状态。
+
+### 使用场景
+
+- AI 改了代码但用户不满意 → 回滚到修改前的状态
+- AI 进行了多轮修改 → 选择性回滚到某个中间状态
+- 用户关闭终端后想撤销 → 通过会话恢复 + 文件回滚实现
+
+## 接下来
+
+- **系统提示词** — 理解每轮对话前的上下文组装策略
+- **上下文压缩** — 深入了解对话过长时的自动压缩机制
+- **令牌预算** — 理解 token 预算管理和成本控制

docs/conversation/streaming.mdx

@@ -1,189 +1,111 @@
 ---
-title: "流式响应机制 - Claude Code 打字机效果原理"
-description: "解析 Claude Code 流式响应实现：如何通过 SSE 逐 token 接收 AI 输出，实现实时打字机效果，提升用户等待体验。"
-keywords: ["流式响应", "SSE", "streaming", "实时输出", "API streaming"]
-sourceRef: "3ec5675 (2026-04-08)"
+title: "流式响应"
+description: "为什么流式是 Claude Code 的核心设计选择？理解流式传输的设计考量、错误处理策略和多 Provider 适配。"
+keywords: ["流式响应", "SSE", "streaming", "API streaming"]
 ---
 
-## 为什么需要流式
+## 为什么流式是核心设计
 
 想象 AI 需要 30 秒才能生成完整回答——如果等 30 秒后才一次性显示，用户体验是灾难性的。
 
-流式响应让用户**实时看到 AI 的思考过程**：
-- 文字逐字出现，用户能提前判断方向是否正确
-- 工具调用的参数在生成过程中就能预览
-- 长时间任务不会让用户觉得"卡死了"
+但流式不仅仅是为了"打字机效果"。在 Claude Code 中，流式是整个系统架构的基础假设：
 
-## `BetaRawMessageStreamEvent` 核心事件类型
+- **工具并行执行**：AI 在流式输出过程中就可能发出工具调用，系统可以立即开始执行，不必等整个响应结束。这使得"AI 边想边做"成为可能
+- **实时反馈**：用户看到 AI 的思考方向后可以提前判断是否正确，必要时提前中断
+- **可取消性**：流式架构天然支持用户中断——随时可以终止正在进行的流
+- **工具执行反馈**：不仅是 AI 输出是流式的，工具执行（如 shell 命令）的输出也是流式的——用户实时看到命令输出
 
-流式 API 返回的是一系列 `BetaRawMessageStreamEvent`，每种事件类型对应流式响应的不同阶段（`src/services/api/claude.ts`）：
+**代价**：流式架构比一次性响应复杂得多——需要处理连接中断、部分数据、乱序事件等边界情况。
+
+## 流式响应的概念模型
+
+一次流式响应不是"一个完整的回答"，而是一系列按顺序到达的事件流：
 
 ```
-message_start           ← 消息开始，包含 model、usage 初始值
-  ├── content_block_start   ← 内容块开始（text / tool_use / thinking）
-  │   ├── content_block_delta  ← 增量数据（text_delta / input_json_delta / thinking_delta）
-  │   ├── content_block_delta  ← ... 持续到达
-  │   └── content_block_stop   ← 内容块结束，yield AssistantMessage
-  ├── content_block_start   ← 下一个内容块...
-  │   └── ...
-  └── message_delta       ← stop_reason + 最终 usage
-message_stop            ← 消息结束
+消息开始
+  ├── 内容块 1：文本 "我来帮你修复这个 bug。"
+  ├── 内容块 2：工具调用 { name: "Read", input: "..." }
+  ├── 内容块 3：文本 "我看到了问题..."
+  └── ...
+消息结束（包含停止原因和 token 用量）
 ```
 
-### 事件处理状态机
+关键设计点：
 
-`src/services/api/claude.ts` 中 `queryStreamRaw()` 函数的事件处理循环实现了一个基于 `switch(part.type)` 的状态机：
+### 内容块的增量累加
 
-| 事件类型 | 处理逻辑 | 状态变更 |
-|----------|----------|----------|
-| `message_start` | 初始化 `partialMessage`，记录 TTFT（首字节延迟） | `usage` 初始化 |
-| `content_block_start` | 按 `part.index` 创建对应类型的内容块 | `contentBlocks[index]` 初始化 |
-| `content_block_delta` | 按子类型增量追加数据 | text / thinking / input 累加 |
-| `content_block_stop` | 构建完整 `AssistantMessage` 并 yield | 消息推入 `newMessages` |
-| `message_delta` | 更新 stop_reason 和最终 usage | 写回最后一条消息 |
-| `message_stop` | 无操作（流结束标记） | — |
+每个内容块（文本、思考、工具调用）都是通过增量数据逐步构建的。文本逐字到达，工具调用的 JSON 参数逐段到达。系统需要在内存中持续累加这些片段，直到一个内容块完整后才传递给消费者。
 
-### 内容块类型及其增量数据
+### 多消息产出
 
-`content_block_start` 中的 `content_block.type` 决定了如何处理后续 delta：
+因为一次 AI 响应可能包含多个内容块（文本和工具调用交替出现），每个完整的内容块都会触发一次消息传递。这意味着一个 API 响应会产生**多条消息**——文本消息和工具调用消息交替产出。
 
-| 内容块类型 | Delta 类型 | 累加逻辑 |
-|-----------|-----------|----------|
-| `text` | `text_delta` | `text += delta.text` |
-| `thinking` | `thinking_delta` + `signature_delta` | `thinking += delta.thinking`，`signature = delta.signature` |
-| `tool_use` | `input_json_delta` | `input += delta.partial_json`（JSON 字符串增量拼接） |
-| `server_tool_use` | `input_json_delta` | 同 tool_use |
-| `connector_text` | `connector_text_delta` | 特殊连接器文本（feature flag 控制） |
+### 停止原因的回写
 
-关键设计：`content_block_start` 时所有文本字段初始化为空字符串，只通过 `content_block_delta` 累加。这是因为 SDK 有时在 start 和 delta 中重复发送相同文本。
+AI 最终是"回答完毕"还是"需要调用工具"，这个信息要到最后才知道。所以停止原因是在消息结束时**回写**到最后一条消息上的——消费者在收到中间消息时还不知道整轮对话是否结束。
 
-## 文本 chunk 和 tool_use block 的交织
+## 错误处理：三层防护
 
-一次 AI 响应可能包含多个内容块，交替出现：
+流式连接比一次性请求脆弱得多——网络波动、服务器过载、连接超时都可能导致中断。系统设计了三层防护：
 
-```
-content_block_start (text, index=0)     "我来帮你修复这个 bug。"
-content_block_delta  (text_delta)       "首先..."
-content_block_stop  (index=0)
-content_block_start (tool_use, index=1) { name: "Read", input: "..." }
-content_block_delta  (input_json_delta) '{"file_p' → 'ath":' → '"src/foo.ts"}'
-content_block_stop  (index=1)
-content_block_start (text, index=2)     "我已经看到了问题所在..."
-content_block_stop  (index=2)
-```
+### 第一层：被动停滞检测
 
-每个 `content_block_stop` 触发一次 `yield`，将完整的 AssistantMessage 推送给消费者。这意味着一个 AI 响应会产生**多条** `AssistantMessage`——文本消息和工具调用消息交替产出。
+系统记录每个事件到达的时间间隔。当间隔超过 30 秒时，记录为一次"停滞"并写入遥测。这是被动检测——只在下一个事件到达时才能发现之前的停滞，不会主动中断流。
 
-`stop_reason` 要等到 `message_delta` 才确定（可能是 `end_turn`、`tool_use`、`max_tokens` 等），所以最后一条消息的 `stop_reason` 是**回写**的：
+**设计考量**：为什么不立即中断？因为 API 可能在做长时间的计算（如复杂推理），短暂的无响应不一定意味着故障。被动检测提供了观测能力，而不影响正常流程。
 
-```typescript
-// claude.ts — stop_reason 回写逻辑（直接属性修改，不用对象替换）
-// 因为 transcript 写队列持有 message.message 的引用
-const lastMsg = newMessages.at(-1)
-if (lastMsg) {
-  lastMsg.message.usage = usage
-  lastMsg.message.stop_reason = stopReason
-}
-```
+### 第二层：主动空闲超时
 
-## 流式中的错误处理
+如果 90 秒内没有收到任何事件（可通过环境变量配置），系统主动终止流并进入重试流程。
 
-### 网络断开
+**设计考量**：这是兜底机制。真正的故障不能靠被动检测发现——因为被动检测依赖于"下一个事件到达"，而如果连接已经死了，下一个事件永远不会到达。
 
-流式连接依赖 SSE（Server-Sent Events）。当连接中断时，系统有两层检测机制：
+### 第三层：非流式降级
 
-1. **被动停滞检测**（`src/services/api/claude.ts` 中 stall 检测逻辑）：当下一个事件到达时，计算与上一个事件的时间间隔。超过阈值（30 秒，`STALL_THRESHOLD_MS = 30_000`）记录为一次 stall，累积计数并写入遥测日志。这是被动检测——仅在下一个 chunk 到达时才触发，不会主动中断流。
-2. **主动空闲超时看门狗**（`src/services/api/claude.ts` 中 `STREAM_IDLE_TIMEOUT_MS` 看门狗逻辑）：使用 `setTimeout` 设置 90 秒（可通过 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 环境变量覆盖）的硬性超时。如果在此期间没有收到任何事件，主动终止流并抛出错误进入重试流程。
-3. **非流式降级**：作为最后手段，设置 `didFallBackToNonStreaming` 标志，通过 `executeNonStreamingRequest()` 回退到非流式请求（一次性获取完整响应）。
+作为最后手段，系统可以回退到非流式请求——一次性获取完整响应。失去了实时性，但保证了功能可用性。
 
-```typescript
-// claude.ts — 被动停滞检测
-const STALL_THRESHOLD_MS = 30_000  // 30 秒无事件视为停滞
-let totalStallTime = 0
-let stallCount = 0
+### 降级策略对比
 
-// claude.ts — 主动空闲超时
-const STREAM_IDLE_TIMEOUT_MS =
-  parseInt(process.env.CLAUDE_STREAM_IDLE_TIMEOUT_MS || '', 10) || 90_000
-```
+| 策略 | 检测方式 | 响应时间 | 用户体验 |
+|------|----------|----------|----------|
+| 正常流式 | — | 最低延迟 | 逐字显示 |
+| 被动停滞检测 | 下一个事件到达时 | 不变 | 无感知 |
+| 主动超时中断 | 定时器触发 | 中断后重试延迟 | 短暂停顿后恢复 |
+| 非流式降级 | 重试失败后 | 等待完整响应 | 等待后一次性显示 |
 
-### API 限流
+## Token 超限的两种场景
 
-当 API 返回限流错误时，系统使用 `withRetry` 包装器进行指数退避重试。重试逻辑考虑了：
-- 错误类型（429 限流 vs 500 服务器错误）
-- 重试次数上限
-- 退避间隔
+两种不同的 token 超限需要不同的处理策略：
 
-### Token 超限
+| 场景 | 含义 | 处理方式 |
+|------|------|----------|
+| **输出超限** | AI 话说了一半被切断 | 提升输出上限重试，或提示 AI "接着说" |
+| **上下文窗口超限** | 整个对话历史太长，塞不进 API | 触发自动压缩，用 AI 摘要替代原始对话 |
 
-两种 token 超限场景有不同的处理：
-
-| 场景 | stop_reason | 处理方式 |
-|------|------------|----------|
-| **输出超限** | `max_tokens` | 生成错误消息，建议设置 `CLAUDE_CODE_MAX_OUTPUT_TOKENS` |
-| **上下文窗口超限** | `model_context_window_exceeded` | 触发 compaction 压缩对话历史后重试 |
-
-```typescript
-// claude.ts — stop_reason 处理
-if (stopReason === 'max_tokens') {
-  yield createAssistantAPIErrorMessage({ error: 'max_output_tokens', ... })
-}
-if (stopReason === 'model_context_window_exceeded') {
-  // 复用 max_output_tokens 的恢复路径
-  yield createAssistantAPIErrorMessage({ error: 'max_output_tokens', ... })
-}
-```
-
-### 流式停滞检测
-
-系统持续监控事件到达间隔，检测"停滞"（stall）：
-
-```typescript
-// claude.ts — stall 检测逻辑
-const STALL_THRESHOLD_MS = 30_000  // 30 秒无事件视为停滞
-if (timeSinceLastEvent > STALL_THRESHOLD_MS) {
-  stallCount++
-  totalStallTime += timeSinceLastEvent
-  logEvent('tengu_streaming_stall', { stall_duration_ms, stall_count, ... })
-}
-```
-
-这是**被动检测**——仅在下一个 chunk 到达时才触发比较。与之互补的是 90 秒主动空闲超时看门狗（`STREAM_IDLE_TIMEOUT_MS`），会直接中断长时间无响应的流。
+关键区别：输出超限是"AI 话太多"，可以通过调整上限解决；上下文超限是"给 AI 看的东西太多"，必须通过压缩或删除来减少。
 
 ## 工具执行的流式反馈
 
-BashTool 的命令执行也是流式的——通过 `onProgress` 回调逐行推送输出：
+不仅是 API 响应是流式的，工具执行本身也是流式的。例如 BashTool 执行 shell 命令时，命令的标准输出会实时推送给 UI——用户不需要等命令完全结束才能看到结果。
 
-```
-BashTool.call() → runShellCommand() → AsyncGenerator
-  ├── 每秒轮询输出文件 → onProgress(lastLines, allLines, ...)
-  ├── yield { type: 'progress', output, fullOutput, elapsedTimeSeconds }
-  └── return { code, stdout, interrupted, ... }
-```
-
-UI 层通过 `useToolCallProgress` hook 实时展示命令输出，而不是等命令完全结束。长时间运行的命令还支持自动后台化（`shouldAutoBackground`）。
+长时间运行的命令还支持**自动后台化**：如果命令执行超过一定时间，系统自动将其移到后台，AI 可以继续处理其他任务，命令完成后再回调结果。
 
 ## 多 Provider 适配
 
-| Provider | 流式协议 | 特殊处理 |
-|----------|----------|----------|
-| **Anthropic Direct** | 原生 SSE | 延迟最低，TTFT 最快 |
-| **AWS Bedrock** | AWS SDK 流式接口 | 需要额外的 beta header 和认证 |
-| **Google Vertex** | gRPC → 事件流 | 通过 `getMergedBetas()` 适配 |
-| **Azure** | Anthropic 兼容 API | 自定义 base URL |
+系统支持 7 种 API Provider，每种有不同的流式协议和认证方式：
 
-所有 Provider 通过统一的 `Stream<BetaRawMessageStreamEvent>` 抽象层屏蔽差异。上层代码（QueryEngine、REPL）不需要关心底层用的是哪个 Provider。
+| Provider 类别 | 流式方式 | 设计挑战 |
+|---------------|----------|----------|
+| Anthropic 直连 | 原生 SSE | 基准实现，其他 Provider 对齐它 |
+| 云平台（Bedrock/Vertex） | SDK 封装的流式接口 | 需要适配认证、beta header、参数格式 |
+| 第三方兼容（OpenAI/Gemini/Grok） | 各自的流式协议 | 需要转换为 Anthropic 内部格式 |
 
-### Provider 选择
+**设计策略**：所有 Provider 通过统一的流式抽象层屏蔽差异。上层代码（编排层、交互层）不需要关心底层用的是哪个 Provider——它们只看到统一的事件流。
 
-`src/utils/model/providers.ts` 中的 `getAPIProvider()` 根据配置决定使用哪个 Provider：
+这意味着切换 Provider 不需要修改任何业务逻辑，只需要在通信层适配新的协议。这也是为什么"通信层"是独立的一层。
 
-```typescript
-// 根据 api_provider 配置选择：
-// "anthropic" → 直连
-// "bedrock"   → AWS SDK
-// "vertex"    → Google SDK
-// 第三方 base URL → 自动检测
-```
+## 接下来
 
-每个 Provider 需要适配的细节包括：认证方式、beta header、请求参数格式、错误码映射——但这些差异在 `claude.ts` 的 `queryStream()` 函数中被统一处理。
+- **多轮对话** — 理解跨迭代的上下文管理
+- **上下文压缩** — 深入了解 token 超限时的自动压缩机制
+- **工具系统** — 了解工具执行的并行策略

docs/conversation/the-loop.mdx

@@ -1,197 +1,166 @@
 ---
-title: "Agentic Loop：AI 自主循环的核心机制"
-description: "深入解析 Claude Code 的 query() 异步生成器循环——从流式 API 调用、工具并行执行、上下文压缩、错误恢复到终止条件的完整状态机，基于 src/query.ts 的源码级分析。"
-keywords: ["Agentic Loop", "query loop", "tool_use", "状态机", "auto-compact", "streaming", "recovery"]
-sourceRef: "3ec5675 (2026-04-08)"
+title: "Agent Loop"
+description: "理解 Claude Code 的核心循环机制——AI 如何自主决定工具调用、处理错误、管理上下文，直到任务完成。"
+keywords: ["Agentic Loop", "tool_use", "状态机", "auto-compact", "streaming"]
 ---
 
-{/* 本章目标：基于 src/query.ts 揭示 Agentic Loop 的完整状态机 */}
-
 ## 什么是 Agentic Loop
 
-传统聊天机器人：你问一句，它答一句。  
+传统聊天机器人：你问一句，它答一句。
 Claude Code 不一样：你说一个需求，它可能连续执行十几步操作才给你最终结果。
 
-这背后的机制叫做 **Agentic Loop**（智能体循环），核心实现在 `src/query.ts` 的 `queryLoop()` 异步生成器函数。它是一个 `while(true)` 无限循环，每次迭代代表一次"思考→行动→观察"周期。
+这背后的机制叫做 **Agentic Loop**（智能体循环）。它是一个"思考→行动→观察"的不断循环，直到任务完成或遇到终止条件。
 
 <Frame caption="Agentic Loop 循环示意">
   <img src="/docs/images/agentic-loop.png" alt="Agentic Loop 循环图" />
 </Frame>
 
-## 循环的完整结构
+### 为什么需要循环而非一次回答
 
-`queryLoop()` 的每次迭代（`src/query.ts` 中 `while(true)` 主循环）包含以下阶段：
+因为软件工程任务本质上是**探索性**的。AI 不可能在第一步就知道所有信息：
 
-### 阶段 1：上下文预处理（Pre-Processing Pipeline）
+- 它需要先读代码才能知道怎么改
+- 它需要先运行命令才能知道结果
+- 它需要先搜索才能找到相关文件
+- 它需要先修改才能验证是否正确
 
-在调用 API 之前，依次执行 5 个压缩/优化步骤：
+每一步工具执行都产生**真实信息**——命令输出、文件内容、错误信息——这些是 AI 在执行前不可能预知的。因此，AI 必须在每一步后根据新信息重新决策。
+
+## 循环的四个阶段
+
+每次循环迭代包含四个阶段，形成一个完整的"感知→决策→执行→反馈"周期。
+
+### 阶段一：上下文预处理
+
+在调用 API 之前，系统会依次检查和处理上下文。这是一个串行管道，每一步的输出是下一步的输入：
 
 ```
-messagesForQuery（原始消息）
-  ↓ applyToolResultBudget()    — 工具结果预算截断（按 maxResultSizeChars）
-  ↓ snipCompactIfNeeded()      — 历史 Snip 压缩（HISTORY_SNIP feature）
-  ↓ microcompact()             — 微压缩（工具结果摘要）
-  ↓ applyCollapsesIfNeeded()   — 上下文折叠（CONTEXT_COLLAPSE feature）
-  ↓ autocompact()              — 自动压缩（超出阈值时触发）
-messagesForQuery（处理后的消息）→ 发往 API
+原始消息
+  → 工具结果截断（单条输出过长时截断）
+  → 历史压缩（Snip 压缩旧消息）
+  → 微压缩（工具结果摘要化）
+  → 自动压缩（对话接近 token 上限时触发 AI 摘要）
+处理后的消息 → 发往 API
 ```
 
-每个步骤的输出是下一步的输入，形成串行管道。Snip 和 Microcompact 的释放 token 数会传递给 autocompact 的阈值计算（`snipTokensFreed`），避免重复压缩。
+**设计考量**：为什么是串行管道而非一次性处理？因为每个步骤释放的 token 数会影响下一步的决策。例如，如果 Snip 压缩已经释放了足够的 token，自动压缩就不需要触发了。
 
-### 阶段 2：流式 API 调用（Streaming Loop）
+### 阶段二：流式 API 调用
 
-`deps.callModel()` 发起流式请求（`src/query.ts` 中 `attemptWithFallback` 循环内），返回一个 AsyncGenerator。在流式过程中：
+系统以流式方式调用 Claude API。流式传输不是"锦上添花"——它是核心设计决策：
 
-- **AssistantMessage** 被收集到 `assistantMessages[]` 数组
-- **tool_use 块** 被提取到 `toolUseBlocks[]`，设置 `needsFollowUp = true`
-- **StreamingToolExecutor** 在流式过程中就开始并行执行工具（不等流结束）
-- 可恢复的错误（prompt-too-long、max-output-tokens）被**暂扣**（withheld），先尝试恢复
+- **用户体验**：用户看到 AI 逐字输出，而非等待数秒后一次性显示
+- **工具并行执行**：AI 在流式输出过程中就可能发出工具调用，系统可以立即开始执行，不必等流结束
+- **可取消性**：用户随时可以中断正在进行的流式响应
 
-流式回调中的关键守卫：
-- `backfillObservableInput()` —— 为 tool_use 块回填可观察字段（如文件路径展开），但只在添加了新字段时才克隆消息，避免破坏 prompt cache 的字节一致性
-- 流式降级检测——如果 `streamingFallbackOccured`，已收集的消息被标记为 tombstone，清空后重试
+### 阶段三：工具执行
 
-### 阶段 3：工具执行（Tool Execution）
+如果 AI 请求了工具调用，系统执行工具并将结果回传。这里有两个关键设计：
 
-如果 `needsFollowUp` 为 true，循环不会终止，而是执行工具：
+**并行执行**：当 AI 在一次响应中请求多个独立工具调用时（如同时读两个文件），系统并行执行它们。这直接减少了用户等待时间。
 
-```typescript
-// 两种工具执行器（互斥）
-const toolUpdates = streamingToolExecutor
-  ? streamingToolExecutor.getRemainingResults()  // 流式：获取已完成的+等待中的
-  : runTools(toolUseBlocks, assistantMessages, canUseTool, toolUseContext)
-```
+**权限检查**：每个工具执行前都经过权限验证。危险操作（如执行 shell 命令）需要用户确认，安全操作（如读文件）可以自动放行。
 
-工具结果通过 `normalizeMessagesForAPI()` 标准化后，与原始消息合并，进入**下一轮循环迭代**。
+### 阶段四：终止或继续
 
-### 阶段 4：终止或继续
+每次迭代结束时，系统判断是否需要继续：
 
-每次迭代结束时，根据条件决定 `return`（终止）或 `continue`（继续）：
+| 条件 | 结果 |
+|------|------|
+| AI 请求了工具调用 | 继续（下一轮迭代） |
+| AI 只返回文本，没有工具调用 | 终止（任务完成） |
+| 用户中断 | 终止（用户取消） |
+| 达到最大 turn 数 | 终止（安全限制） |
+| Token 预算耗尽 | 终止（成本控制） |
 
-## 终止条件（源码级）
+## 错误恢复：自愈的状态机
 
-循环有多种终止路径，按触发时机排列：
+Agentic Loop 不是"正常路径走完就结束"的简单循环。它包含了多层错误恢复机制，使系统在各种异常情况下都能优雅处理。
 
-| 终止原因 | 触发位置 | 机制 |
-|----------|---------|------|
-| **blocking_limit** | 第 646 行 | Token 计数超过硬限制（非 autocompact 模式）→ 生成 PTL 错误消息 → 返回 |
-| **image_error** | 第 980 行 | `ImageSizeError` / `ImageResizeError` 异常 → 直接返回 |
-| **model_error** | 第 999 行 | `callModel()` 抛出不可恢复异常 → 生成错误消息 → 返回 |
-| **aborted_streaming** | 第 1054 行 | `abortController.signal.aborted`（流式阶段）→ 为未完成的 tool_use 生成合成 tool_result → 返回 |
-| **prompt_too_long** | 第 1178/1185 行 | 413 错误且 reactive compact 无法恢复 → 暂扣的错误消息被释放 → 返回 |
-| **completed** | 第 1267 行 | API 错误（限流、认证失败等）导致无法继续 → 返回 |
-| **stop_hook_prevented** | 第 1282 行 | Stop hook 返回 `preventContinuation: true` → 返回 |
-| **completed** | 第 1360 行 | 正常完成：AI 未发出 tool_use → `needsFollowUp = false` → 经过 stop hooks → 返回 |
-| **aborted_tools** | 第 1518 行 | `abortController.signal.aborted`（工具执行阶段）→ 返回 |
-| **hook_stopped** | 第 1523 行 | 工具执行期间 hook 返回 `shouldPreventContinuation` → 返回 |
-| **max_turns** | 第 1714 行 | 轮次计数超过 `maxTurns` 限制 → 返回 |
+### 输出截断恢复
 
-## 继续条件（恢复路径）
+当 AI 的响应被 token 上限截断时（AI 话说了一半被切断）：
 
-循环不仅是一个简单的"有 tool_use 就继续"，它还包含多种恢复/重试路径：
+1. **首次截断**：静默提升输出 token 上限，重试
+2. **仍然截断**：注入提示消息让 AI "接着说"，最多重试 3 次
+3. **恢复耗尽**：将截断的响应作为最终结果返回
 
-### 1. 正常工具循环（`next_turn`）
-`needsFollowUp = true` → 执行工具 → 新消息追加到 `messagesForQuery` → state 重新赋值 → `continue`
+### 上下文过长恢复
 
-### 2. max_output_tokens 恢复（`max_output_tokens_escalate` / `max_output_tokens_recovery`）
-当 AI 输出被截断时（`apiError === 'max_output_tokens'`），分两阶段恢复：
-- **提升阶段**（`max_output_tokens_escalate`）：首次截断时，将 `maxOutputTokens` 从默认值提升到 `ESCALATED_MAX_TOKENS`（64K）。静默重试，不注入 meta 消息。
-- **恢复阶段**（`max_output_tokens_recovery`）：提升后仍然截断时，注入恢复消息"Output token limit hit. Resume directly..."，最多重试 `MAX_OUTPUT_TOKENS_RECOVERY_LIMIT = 3` 次。恢复耗尽后，暂扣的错误消息被释放。
+当对话历史超过 API 的 token 限制时（413 错误）：
 
-### 3. Prompt-Too-Long 恢复（`collapse_drain_retry` / `reactive_compact_retry`）
-当遇到 413 错误时，按优先级尝试两种压缩策略：
-- **Context Collapse Drain**（`collapse_drain_retry`）：提交所有已暂存的折叠（collapse），释放空间后重试。如果上一轮已经是 `collapse_drain_retry` 则跳过，避免无限循环。
-- **Reactive Compact**（`reactive_compact_retry`）：如果 collapse drain 无法恢复，触发即时压缩（reactive compact），生成摘要后重试。`hasAttemptedReactiveCompact` 标志防止无限循环。
+1. **压缩重试**：即时压缩对话历史，生成摘要后重试
+2. **压缩后仍过长**：返回错误信息，让用户决定如何处理
 
-### 4. Stop Hook 阻塞重试（`stop_hook_blocking`）
-Stop hook 可以注入阻塞错误消息，强制 AI 重新思考。新的消息（包含阻塞错误）被追加到对话中，`stopHookActive = true`，进入下一轮迭代。
+关键设计：系统通过标志位防止无限循环——每种恢复路径只尝试一次，不会在"压缩→失败→压缩"之间死循环。
 
-### 5. Token Budget 继续提示（`token_budget_continuation`）
-当 `TOKEN_BUDGET` feature 启用时，如果 token 消耗达到阈值但未超出预算，注入 nudge 消息让 AI 加速收尾，然后继续。
+### 模型降级
 
-## 模型降级（Fallback）
+当主模型不可用时（过载、维护等）：
 
-当主模型不可用时（`FallbackTriggeredError`，`src/query.ts` 中 `attemptWithFallback` 循环的 catch 分支）：
+1. 已收集的响应被保留为历史记录
+2. 自动切换到备用模型
+3. 通知用户发生了降级
+4. 从中断点继续，而不是从头开始
 
-1. 已收集的 `assistantMessages` 被清空，tool_use 块收到合成 tool_result："Model fallback triggered"
-2. 思维签名块被移除（`stripSignatureBlocks`）—— 因为思维签名与模型绑定，跨模型回放会 400
-3. 切换到 `fallbackModel`，更新 `toolUseContext.options.mainLoopModel`
-4. 生成系统消息："Switched to {fallback} due to high demand for {original}"
-5. 重新发起流式请求
+## 状态管理
 
-## 状态机：State 对象
+每次迭代的状态是不可变更新的——系统创建新的状态对象而非就地修改。状态中包含：
 
-每次迭代的状态通过 `State` 类型（`src/query.ts`，类型定义）传递：
+- **对话消息**：当前所有消息的数组
+- **压缩跟踪**：压缩操作的累计状态
+- **恢复计数**：各种错误恢复已尝试的次数
+- **继续原因**：上一轮为什么继续（用于检测和避免循环）
 
-```typescript
-// src/query.ts — State 类型定义
-type State = {
-  messages: Message[]                        // 当前对话消息
-  toolUseContext: ToolUseContext              // 工具上下文（含权限）
-  autoCompactTracking: AutoCompactTrackingState | undefined  // 压缩跟踪
-  maxOutputTokensRecoveryCount: number       // 输出截断恢复计数
-  hasAttemptedReactiveCompact: boolean       // 是否已尝试即时压缩
-  maxOutputTokensOverride: number | undefined // 输出 token 上限覆盖
-  pendingToolUseSummary: Promise<...> | undefined  // 异步工具摘要
-  stopHookActive: boolean | undefined        // Stop hook 是否激活
-  turnCount: number                          // 轮次计数
-  transition: Continue | undefined           // 上一次继续的原因
-}
-```
-
-每次 `continue` 都创建新的 State 对象（不可变更新），而非就地修改。`transition` 字段记录了为什么继续——让后续迭代能检测特定恢复路径（如 `collapse_drain_retry`）避免循环。
-
-## Token Budget（实验性）
-
-当 `TOKEN_BUDGET` feature 启用时（`src/query.ts` 中 `!needsFollowUp` 分支内的预算检查逻辑），循环在终止前会检查 token 消耗：
-
-- **continuation**：未达到预算但超过阈值 → 注入 nudge 消息，让 AI 加速收尾
-- **diminishing_returns**：检测到收益递减 → 提前终止
-- 预算数据来自 `createBudgetTracker()`，跨迭代累计
+**设计考量**：状态中记录"继续原因"是一个关键的防循环机制。系统可以在后续迭代中检查"上一轮是因为压缩重试而继续的"，从而避免在同一个恢复路径上反复尝试。
 
 ## 为什么不是"一次规划，批量执行"
 
-<Note>
-源码揭示了为什么 Claude Code 选择逐步循环：
-</Note>
+一个自然的疑问是：为什么不先让 AI 规划好所有步骤，然后一次性批量执行？
 
-- **每一步都产生真实信息**：`runTools()` 返回的 `toolResults` 是 API 不可能预知的——命令输出、文件内容、错误信息
-- **动态上下文管理**：每轮迭代前都重新评估压缩需求（autocompact → microcompact → snip），基于最新的 token 计数
-- **错误即时恢复**：工具失败不需要推倒重来——stop hook 可以注入阻塞错误让 AI 修正策略
-- **用户可控**：`abortController.signal` 在循环的多个检查点被检测（第 1018、1048、1488 行），用户按 ESC 可以优雅中断
-- **成本控制**：Token Budget 在每轮终止前检查，防止 AI 无效循环
+答案在于软件工程的**不确定性**：
+
+- **每步结果影响下一步**：搜索结果决定了要改哪些文件，修改后的编译结果决定了是否需要进一步调整
+- **错误需要即时修正**：如果某步失败，AI 需要立即调整策略，而非继续执行无效计划
+- **用户可能中途干预**：循环架构允许用户随时打断和修正方向
+
+这不是说 AI 不做规划——事实上系统内置了规划模式（Plan Mode）用于复杂任务。但规划的结果仍然是逐步执行的，每一步都有机会根据新信息调整。
 
 ## 一个完整的迭代示例
 
 > 用户："帮我找到项目里所有未使用的导入语句，然后删掉它们"
 
 ```
-迭代 1: 思考→行动
-  预处理管道: applyToolResultBudget → snipCompact(HISTORY_SNIP feature) → microcompact → applyCollapses(CONTEXT_COLLAPSE feature) → autocompact
-    → 上下文很短，无需压缩
-  API 调用: 返回 tool_use(Glob, "**/*.ts")
-  工具执行: 返回 42 个文件路径
-  → needsFollowUp = true
-  → transition: { reason: 'next_turn' }, continue
+迭代 1: 探索
+  AI: 先找到所有 TypeScript 文件
+  工具: Glob("**/*.ts") → 返回 42 个文件
+  决策: 需要进一步分析 → 继续
 
-迭代 2: 思考→行动
-  预处理管道: 42 个文件结果仍在预算内
-  API 调用: 返回 tool_use(Grep, "import.*from")
-  工具执行: 在 15 个文件中找到 120 条 import
-  → needsFollowUp = true
-  → transition: { reason: 'next_turn' }, continue
+迭代 2: 分析
+  AI: 搜索这些文件中的 import 语句
+  工具: Grep("import.*from") → 在 15 个文件中找到 120 条 import
+  决策: 结果太多，需要进一步筛选 → 继续
 
-迭代 3: 思考→行动（多轮）
-  预处理管道: 120 条 Grep 结果触发 microcompact → 摘要化
-  API 调用: 返回 3 个 tool_use(FileEdit, ...)
-  工具执行: 删除 5 条未使用导入
-  → needsFollowUp = true
-  → transition: { reason: 'next_turn' }, continue
+迭代 3: 精确修改
+  AI: 分析哪些 import 未被使用，删除它们
+  上下文预处理: 120 条结果被微压缩为摘要
+  工具: FileEdit × 3 → 删除 5 条未使用导入
+  决策: 需要验证 → 继续
 
-迭代 4: 总结
-  API 调用: 返回纯文本"已清理 3 个文件中的 5 条未使用导入"
-  → needsFollowUp = false
-  → Stop hooks 通过
-  → Token Budget 检查通过（如果启用）
-  → return { reason: 'completed' }
+迭代 4: 验证与总结
+  AI: 验证修改后编译通过
+  工具: Bash("tsc --noEmit") → 编译通过
+  决策: 任务完成 → 终止
 ```
+
+注意这个过程中的关键特征：
+- AI 在每一步后根据结果自主决定下一步
+- 上下文在迭代过程中动态调整（微压缩被触发）
+- 用户全程无需介入
+
+## 接下来
+
+- **流式响应** — 理解流式传输的设计细节和用户体验考量
+- **多轮对话** — 跨迭代的上下文管理和会话持久化
+- **上下文压缩** — 深入理解自动压缩的触发条件和策略
+- **工具系统** — 了解 AI 可以调用哪些工具及其设计

docs/diagrams/agent-loop-simple.mmd

@@ -0,0 +1,17 @@
+flowchart TB
+    START((输入)) --> CTX["Context 管理"]
+    CTX --> LLM["LLM 流式输出"]
+    LLM --> TC{tool_use?}
+
+    TC --> |是| EXEC["执行工具"]
+    EXEC --> CTX
+
+    TC --> |否| DONE((完成))
+
+    classDef proc fill:#eef,stroke:#66c,color:#224
+    classDef decision fill:#fee,stroke:#c66,color:#422
+    classDef io fill:#eff,stroke:#6cc,color:#244
+
+    class CTX,LLM,EXEC proc
+    class TC decision
+    class START,DONE io

docs/diagrams/agent-loop.mmd

@@ -0,0 +1,40 @@
+flowchart TB
+    START((输入)) --> CTX["Context 管理"]
+    CTX --> PRE["Pre-sampling Hook"]
+    PRE --> LLM["LLM 流式输出"]
+    LLM --> TC{tool_use?}
+
+    TC --> |是| PERM{需权限?}
+    PERM --> |是| USER["👤 用户审批"]
+    USER --> |allow| TOOL_PRE
+    USER --> |deny| DENIED["拒绝"]
+    PERM --> |否| TOOL_PRE["Pre-tool Hook"]
+    TOOL_PRE --> EXEC["并发执行工具"]
+    EXEC --> TOOL_POST["Post-tool Hook"]
+    TOOL_POST --> CTX
+    DENIED --> CTX
+
+    TC --> |否| POST["Post-sampling Hook"]
+    POST --> STOP{"Stop Hook"}
+    STOP --> |不通过| CTX
+    STOP --> |通过| BUDGET{"Token Budget"}
+    BUDGET --> |继续| CTX
+    BUDGET --> |完成| DONE((完成))
+
+    subgraph SUB["子 Agent"]
+        FORK["AgentTool"] --> RECURSE["递归调用"]
+    end
+
+    EXEC -.-> FORK
+
+    classDef proc fill:#eef,stroke:#66c,color:#224
+    classDef decision fill:#fee,stroke:#c66,color:#422
+    classDef hook fill:#ffe,stroke:#cc6,color:#442
+    classDef io fill:#eff,stroke:#6cc,color:#244
+    classDef sub fill:#efe,stroke:#6a6,color:#242
+
+    class CTX,LLM,EXEC proc
+    class TC,PERM,STOP,BUDGET decision
+    class PRE,TOOL_PRE,TOOL_POST,POST hook
+    class START,DONE,USER,DENIED io
+    class FORK,RECURSE sub

docs/extensibility/custom-agents.mdx

@@ -1,211 +1,107 @@
 ---
-title: "自定义 Agent - 从 Markdown 到运行时的完整链路"
-description: "揭秘 Claude Code 自定义 Agent 完整链路：Agent 定义的 Markdown 数据模型、三种加载来源、工具过滤策略和与 AgentTool 的联动机制。"
-keywords: ["自定义 Agent", "Agent 定义", "Markdown Agent", "Agent 配置", "角色定制"]
+title: "自定义 Agent"
+description: "用 Markdown 文件定义自己的 Agent。理解 Agent 定义的数据模型、工具过滤策略和与 AgentTool 的联动。"
+keywords: ["自定义 Agent", "Agent 定义", "Markdown Agent", "角色定制"]
 ---
 
-{/* 本章目标：揭示 Agent 定义的完整数据模型、加载发现机制、工具过滤和与 AgentTool 的联动 */}
+## 核心概念
 
-## Agent 定义的三种来源
-
-Claude Code 的 Agent 不仅仅来自用户自定义——系统有三类来源，按优先级合并：
-
-| 来源 | 位置 | 优先级 |
-|------|------|--------|
-| **Built-in** | `src/tools/AgentTool/built-in/` 硬编码 | 最低（可被覆盖） |
-| **Plugin** | 通过插件系统注册 | 中 |
-| **User/Project/Policy** | `.claude/agents/*.md` 或 settings.json | 最高 |
-
-合并逻辑在 `getActiveAgentsFromList()` 中：按 `agentType` 去重，后者覆盖前者。这意味着你可以在 `.claude/agents/` 中放一个 `Explore.md` 来完全替换内置的 Explore Agent。
-
-## Markdown Agent 文件的完整格式
+自定义 Agent 是一个 Markdown 文件——frontmatter 定义配置，正文是 system prompt。不需要写代码。
 
 ```markdown
 ---
-# === 必需字段 ===
-name: "reviewer"                    # Agent 标识（agentType）
-description: "Code review specialist, read-only analysis"
-
-# === 工具控制 ===
-tools: "Read,Glob,Grep,Bash"        # 允许的工具列表（逗号分隔）
-disallowedTools: "Write,Edit"       # 显式禁止的工具
-
-# === 模型配置 ===
-model: "haiku"                      # 指定模型（或 "inherit" 继承主线程）
-effort: "high"                      # 推理努力程度：low/medium/high 或整数
-
-# === 行为控制 ===
-maxTurns: 10                        # 最大 agentic 轮次
-permissionMode: "plan"              # 权限模式：plan/bypassPermissions 等
-background: true                    # 始终作为后台任务运行
-initialPrompt: "/search TODO"       # 首轮用户消息前缀（支持斜杠命令）
-
-# === 隔离与持久化 ===
-isolation: "worktree"               # 在独立 git worktree 中运行
-memory: "project"                   # 持久记忆范围：user/project/local
-
-# === MCP 服务器 ===
-mcpServers:
-  - "slack"                         # 引用已配置的 MCP 服务器
-  - database:                       # 内联定义
-      command: "npx"
-      args: ["mcp-db"]
-
-# === Hooks ===
-hooks:
-  PreToolUse:
-    - command: "audit-log.sh"
-      timeout: 5000
-
-# === Skills ===
-skills: "code-review,security-review"  # 预加载的 skills（逗号分隔）
-
-# === 显示 ===
-color: "blue"                       # 终端中的 Agent 颜色标识
+name: "reviewer"
+description: "Code review specialist"
+tools: "Read,Glob,Grep"
+model: "haiku"
 ---
 
 你是代码审查专家。你的职责是...
-
-（正文内容 = system prompt）
 ```
 
-### 字段解析细节
+这个 Markdown 文件就定义了一个完整的 Agent：它使用什么工具、什么模型、什么行为规则。
 
-- **`tools`**：通过 `parseAgentToolsFromFrontmatter()` 解析，支持逗号分隔字符串或数组
-- **`model: "inherit"`**：使用主线程的模型（区分大小写，只有小写 "inherit" 有效）
-- **`memory`**：启用后自动注入 `Write`/`Edit`/`Read` 工具（即使 `tools` 未包含），并在 system prompt 末尾追加 memory 指令
-- **`isolation: "remote"`**：仅在 Anthropic 内部可用（`USER_TYPE === 'ant'`），外部构建只支持 `worktree`
-- **`background`**：`true` 使 Agent 始终在后台运行，主线程不等待结果
+## Agent 的三种来源
 
-## 加载与发现机制
+| 来源 | 位置 | 优先级 |
+|------|------|--------|
+| **Built-in** | 硬编码 | 最低（可被覆盖） |
+| **Plugin** | 插件系统注册 | 中 |
+| **User/Project** | `.claude/agents/*.md` | 最高 |
 
-`getAgentDefinitionsWithOverrides()`（被 `memoize` 缓存）执行完整的发现流程：
+合并时按 `agentType` 去重，后者覆盖前者。这意味着你可以在 `.claude/agents/` 中放一个 `Explore.md` 来完全替换内置的 Explore Agent。
 
-```
-1. 加载 Markdown 文件
-   ├── loadMarkdownFilesForSubdir('agents', cwd)
-   │   ├── ~/.claude/agents/*.md  （用户级，source = 'userSettings'）
-   │   ├── .claude/agents/*.md    （项目级，source = 'projectSettings'）
-   │   └── managed/policy sources （策略级，source = 'policySettings'）
-   │
-   └── 每个 .md 文件：
-       ├── 解析 YAML frontmatter
-       ├── 正文作为 system prompt
-       ├── 校验必需字段（name, description）
-       ├── 静默跳过无 frontmatter 的 .md 文件（可能是参考文档）
-       └── 解析失败 → 记录到 failedFiles，不阻塞其他 Agent
+## 配置字段
 
-2. 并行加载 Plugin Agents
-   └── loadPluginAgents() → memoized
+### 工具控制
 
-3. 初始化 Memory Snapshots（如果 AGENT_MEMORY_SNAPSHOT 启用）
-   └── initializeAgentMemorySnapshots()
+- `tools` — 允许的工具白名单（未指定 = 全部工具）
+- `disallowedTools` — 显式禁止的工具（即使 `tools` 未指定也生效）
 
-4. 合并 Built-in + Plugin + Custom
-   └── getActiveAgentsFromList() → 按 agentType 去重，后者覆盖前者
+**设计考量**：`disallowedTools` 是比 `tools` 更安全的控制方式。如果只指定 `tools` 白名单，新增工具时需要更新白名单。`disallowedTools` 是黑名单思维——默认允许，只禁止危险的。
 
-5. 分配颜色
-   └── setAgentColor(agentType, color) → 终端 UI 中区分不同 Agent
-```
+### 模型配置
 
-## 工具过滤的实现
+- `model` — 指定模型（`haiku`/`sonnet`/`opus`/`inherit`）
+- `effort` — 推理努力程度（`low`/`medium`/`high`）
 
-当 Agent 被派生时，`AgentTool` 根据定义中的 `tools` / `disallowedTools` 过滤可用工具列表：
+`inherit` 使用主线程的模型——适合需要完整推理能力的任务。`haiku` 适合轻量任务（如搜索），更便宜更快。
 
-```
-全部工具
-  ↓ disallowedTools 移除
-  ↓ tools 白名单过滤（如果指定）
-可用工具
-```
+### 行为控制
 
-- **`tools` 未指定**：Agent 可以使用所有工具（默认全能）
-- **`tools` 指定**：只能使用列出的工具
-- **`disallowedTools`**：即使 `tools` 未指定，这些工具也被禁止
-- **自动注入**：`memory` 启用时自动添加 `Write`/`Edit`/`Read`
+- `maxTurns` — 最大 agentic 轮次（防止无限循环）
+- `permissionMode` — 权限模式（`plan`/`bypassPermissions` 等）
+- `background` — 始终作为后台任务运行
+- `isolation` — 在独立 worktree 中运行
 
-以内置 Explore Agent 为例：
+### 持久化
 
-```typescript
-// src/tools/AgentTool/built-in/exploreAgent.ts
-disallowedTools: [
-  'Agent',           // 不能嵌套调用 Agent
-  'ExitPlanMode',    // 不需要 plan mode
-  'FileEdit',        // 只读
-  'FileWrite',       // 只读
-  'NotebookEdit',    // 只读
-]
-```
+- `memory` — 启用跨会话的持久记忆（`user`/`project`/`local`）
+- `mcpServers` — 引用或内联定义 MCP 服务器
+- `hooks` — Agent 专属的 Hook 配置
+- `skills` — 预加载的技能
 
 ## System Prompt 的注入方式
 
-Agent 的 system prompt 通过 `getSystemPrompt()` 闭包延迟生成：
+Agent 的 Markdown 正文**完全替换**默认的 system prompt，而非追加。这意味着自定义 Agent 的行为完全由你定义——不受默认 prompt 的约束。
 
-```typescript
-// Markdown Agent
-getSystemPrompt: () => {
-  if (isAutoMemoryEnabled() && memory) {
-    return systemPrompt + '\n\n' + loadAgentMemoryPrompt(agentType, memory)
-  }
-  return systemPrompt
-}
+如果启用了 `memory`，记忆指令自动追加到 system prompt 末尾。
+
+## 工具过滤流程
+
+```
+全部工具 → disallowedTools 移除 → tools 白名单过滤 → 可用工具
 ```
 
-这意味着：
-1. **Markdown 正文 = 完整的 system prompt**——不是追加，而是替换默认 prompt
-2. **Memory 指令**在 memory 启用时自动追加到末尾
-3. **闭包延迟计算**——memory 状态可能在文件加载后才变化
+内置 Explore Agent 的工具限制是很好的例子：
+- 禁止 `Agent`（不能嵌套调用子 Agent）
+- 禁止 `FileEdit`/`FileWrite`（只读）
+- 禁止 `ExitPlanMode`（不需要 plan mode）
 
-对于 Built-in Agent，`getSystemPrompt` 接受 `toolUseContext` 参数，可以根据运行时状态（如是否使用嵌入式搜索工具）动态调整 prompt 内容。
+这些限制让 Explore Agent 成为一个纯粹的搜索工具——它只能看，不能改。
 
 ## 与 AgentTool 的联动
 
 当主 Agent 需要派生子 Agent 时：
 
 ```
-AgentTool.call({ subagent_type: "reviewer", ... })
-  ↓
-1. 从 agentDefinitions.activeAgents 查找 agentType === "reviewer"
-  ↓
-2. 检查 requiredMcpServers（如果 Agent 要求特定 MCP 服务器）
-  ↓
-3. 过滤工具列表（tools / disallowedTools）
-  ↓
-4. 解析模型：
-   - "inherit" → 使用主线程模型
-   - 具体模型名 → 直接使用
-   - 未指定 → 主线程模型
-  ↓
-5. 解析权限模式（permissionMode）
-  ↓
-6. 构建隔离环境（如果 isolation === "worktree"）
-  ↓
-7. 注入 system prompt（getSystemPrompt()）
-  ↓
-8. 注入 initialPrompt（如果定义了）
-  ↓
-9. 启动子 Agent 循环（forkSubagent / runAgent）
+查找 Agent 定义 → 检查 MCP 依赖 → 过滤工具 → 解析模型 → 构建隔离环境 → 注入 system prompt → 启动子 Agent
 ```
 
+每一步都使用 Agent 定义中的配置——工具列表、模型选择、权限模式、隔离环境等。
+
 ## 内置 Agent 参考
 
-| Agent | agentType | 角色 | 工具限制 | 模型 |
-|-------|-----------|------|---------|------|
-| **General Purpose** | `general-purpose` | 默认子 Agent | 全部工具 | 主线程模型 |
-| **Explore** | `Explore` | 代码搜索专家 | 只读（无 Write/Edit） | haiku（外部） |
-| **Plan** | `Plan` | 规划专家 | 只读 + ExitPlanMode | inherit |
-| **Verification** | `verification` | 结果验证 | 由 feature flag 控制 | — |
-| **Code Guide** | `claude-code-guide` | Claude Code 使用指南 | 只读 | — |
-| **Statusline Setup** | `statusline-setup` | 终端状态栏配置 | 有限 | — |
+| Agent | 角色 | 工具限制 | 模型 |
+|-------|------|---------|------|
+| General Purpose | 通用任务 | 全部工具 | 继承主线程 |
+| Explore | 代码搜索 | 只读 | haiku |
+| Plan | 规划研究 | 只读 + ExitPlanMode | 继承主线程 |
+| Verification | 结果验证 | 由 feature flag 控制 | — |
+| Code Guide | 使用指南 | 只读 | — |
 
-SDK 入口（`sdk-ts`/`sdk-py`/`sdk-cli`）不加载 Code Guide Agent。环境变量 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` 可以完全禁用内置 Agent，给 SDK 用户提供空白画布。
+## 接下来
 
-## Agent Memory：持久化的 Agent 状态
-
-当 `memory` 字段启用时，Agent 获得跨会话的持久记忆：
-
-- **`local`**：当前项目、当前用户有效
-- **`project`**：当前项目所有用户共享
-- **`user`**：所有项目共享
-
-Memory 通过 `loadAgentMemoryPrompt()` 注入到 system prompt 末尾，包含读写记忆的指令。Agent Memory Snapshot 机制在项目间同步 `user` 级记忆。
+- **子 Agent** — 理解子 Agent 的完整执行链路
+- **Skills** — 理解 Skill 中指定 Agent 定义
+- **MCP 配置** — 理解 Agent 中引用 MCP 服务器

docs/extensibility/hooks.mdx

@@ -1,253 +1,148 @@
 ---
-title: "Hooks 生命周期钩子 - 执行引擎与拦截协议"
-description: "从源码角度解析 Claude Code Hooks 系统：27 种 Hook 事件、6 种 Hook 类型、同步/异步执行协议、JSON 输出 schema、if 条件匹配、以及 Hook 如何注入上下文和拦截工具调用。"
+title: "Hooks"
+description: "Hooks 是 Claude Code 的扩展机制——在工具调用前后注入自定义逻辑。理解四种 Hook 能力、匹配机制和安全防护。"
 keywords: ["Hooks", "生命周期钩子", "拦截器", "PreToolUse", "Hook 协议"]
 ---
 
-{/* 本章目标：从源码角度揭示 Hook 的执行引擎、匹配机制、返回值协议和生命周期管理 */}
+## 核心问题
 
-## 27 种 Hook 事件
+Claude Code 提供了强大的内置功能，但每个团队和工作流都不同。Hooks 让你可以在关键节点注入自定义逻辑——不需要修改 Claude Code 本身。
 
-Claude Code 定义了 27 种 Hook 事件（`HOOK_EVENTS` 数组，`src/entrypoints/sdk/coreTypes.ts`），覆盖完整的 Agent 生命周期：
+## Hook 事件
 
-| 阶段 | 事件 | 触发时机 | 匹配字段 |
-|------|------|---------|---------|
-| **会话** | `SessionStart` | 会话启动 | `source` |
-| | `SessionEnd` | 会话结束 | `reason` |
-| | `Setup` | 初始化完成 | `trigger` |
-| **用户交互** | `UserPromptSubmit` | 用户提交消息 | — |
-| | `Stop` | Agent 停止响应 | — |
-| | `StopFailure` | Agent 停止失败 | `error` |
-| **工具执行** | `PreToolUse` | 工具调用前 | `tool_name` |
-| | `PostToolUse` | 工具调用后（成功） | `tool_name` |
-| | `PostToolUseFailure` | 工具调用后（失败） | `tool_name` |
-| **权限** | `PermissionRequest` | 权限请求 | `tool_name` |
-| | `PermissionDenied` | 权限被拒 | `tool_name` |
-| **子 Agent** | `SubagentStart` | 子 Agent 启动 | `agent_type` |
-| | `SubagentStop` | 子 Agent 停止 | `agent_type` |
-| **压缩** | `PreCompact` | 上下文压缩前 | `trigger` |
-| | `PostCompact` | 上下文压缩后 | `trigger` |
-| **协作** | `TeammateIdle` | Teammate 空闲 | — |
-| | `TaskCreated` | 任务创建 | — |
-| | `TaskCompleted` | 任务完成 | — |
-| **MCP** | `Elicitation` | MCP 服务器请求用户输入 | `mcp_server_name` |
-| | `ElicitationResult` | Elicitation 结果返回 | `mcp_server_name` |
-| **通知** | `Notification` | 系统通知事件 | `notification_type` |
-| **环境** | `ConfigChange` | 配置变更 | `source` |
-| | `CwdChanged` | 工作目录变更 | — |
-| | `FileChanged` | 文件变更 | `file_path` |
-| | `InstructionsLoaded` | 指令加载 | `load_reason` |
-| | `WorktreeCreate` / `WorktreeRemove` | Worktree 操作 | — |
+Hooks 覆盖 Agent 生命周期的所有关键节点：
 
-## 6 种 Hook 类型
+| 阶段 | 典型事件 |
+|------|---------|
+| **会话** | 启动、结束、初始化 |
+| **用户交互** | 提交消息、停止响应 |
+| **工具执行** | 工具调用前、工具调用后（成功/失败） |
+| **权限** | 权限请求、权限被拒 |
+| **子 Agent** | 启动、停止 |
+| **压缩** | 压缩前、压缩后 |
+| **协作** | Teammate 空闲、任务创建/完成 |
 
-Hooks 配置支持 6 种执行方式，类型定义分布在 3 个文件中：
+## 四种 Hook 能力
 
-- **可持久化类型**（`command`、`prompt`、`agent`、`http`）— Zod schema 定义在 `src/schemas/hooks.ts`，通过 `z.discriminatedUnion('type', [...])` 声明
-- **callback 类型** — TypeScript 接口定义在 `src/types/hooks.ts`，用于 SDK 注册的内部 JS 函数
-- **function 类型** — 定义在 `src/utils/hooks/sessionHooks.ts`，用于运行时动态注册的函数 Hook
-
-| 类型 | 执行方式 | 适用场景 |
-|------|---------|---------|
-| `command` | Shell 命令（bash/PowerShell） | 通用脚本、CI 检查 |
-| `prompt` | 注入到 AI 上下文 | 代码规范提醒 |
-| `agent` | 启动子 Agent 执行 | 复杂分析任务 |
-| `http` | HTTP 请求 | 远程服务、Webhook |
-| `callback` | 内部 JS 函数 | 系统内置 Hook |
-| `function` | 运行时注册的函数 Hook | Agent/Skill 内部使用 |
-
-## 执行引擎：execCommandHook
-
-`execCommandHook()`（`src/utils/hooks.ts`，`execCommandHook` 函数）是命令型 Hook 的执行核心：
-
-```
-execCommandHook(hook, hookEvent, hookName, jsonInput, signal)
-  ├── Shell 选择: hook.shell ?? DEFAULT_HOOK_SHELL
-  │   ├── bash: spawn(cmd, [], { shell: gitBashPath | true })
-  │   └── powershell: spawn(pwsh, ['-NoProfile', '-NonInteractive', '-Command', cmd])
-  ├── 变量替换
-  │   ├── ${CLAUDE_PLUGIN_ROOT} → pluginRoot 路径
-  │   ├── ${CLAUDE_PLUGIN_DATA} → plugin 数据目录
-  │   └── ${user_config.X} → 用户配置值
-  ├── 环境变量注入
-  │   ├── CLAUDE_PROJECT_DIR
-  │   ├── CLAUDE_ENV_FILE（SessionStart/Setup/CwdChanged/FileChanged）
-  │   └── CLAUDE_PLUGIN_OPTION_*（plugin options）
-  ├── stdin 写入: jsonInput + '\n'
-  ├── 超时: hook.timeout * 1000 ?? 600000ms（10分钟）
-  └── 异步检测: 检查 stdout 首行是否为 {"async":true}
-```
-
-### 异步 Hook 的检测协议
-
-Hook 进程的 stdout 第一行如果是 `{"async":true}`，系统将其转为后台任务（`isAsyncHookJSONOutput` 检测 + `executeInBackground` 调用）：
-
-```typescript
-const firstLine = firstLineOf(stdout).trim()
-if (isAsyncHookJSONOutput(parsed)) {
-  executeInBackground({
-    processId: `async_hook_${child.pid}`,
-    asyncResponse: parsed,
-    ...
-  })
-}
-```
-
-后台 Hook 通过 `registerPendingAsyncHook()` 注册到 `AsyncHookRegistry`，完成后通过 `enqueuePendingNotification()` 通知主线程。
-
-### asyncRewake：Hook 唤醒模型
-
-`asyncRewake` 模式的 Hook 绕过 `AsyncHookRegistry`。当 Hook 退出码为 2 时，通过 `enqueuePendingNotification()` 以 `task-notification` 模式注入消息，唤醒空闲的模型（通过 `useQueueProcessor`）或在忙碌时注入 `queued_command` 附件。
-
-## Hook 输出的 JSON Schema
-
-同步 Hook 的输出遵循严格的 Zod schema（`syncHookResponseSchema`，定义在 `src/types/hooks.ts`，`hookJSONOutputSchema` 定义在 `src/schemas/hooks.ts`）：
-
-```json
-{
-  "continue": false,                    // 是否继续执行
-  "suppressOutput": true,               // 隐藏 stdout
-  "stopReason": "安全检查失败",           // continue=false 时的原因
-  "decision": "approve" | "block",      // 全局决策
-  "reason": "原因说明",                   // 决策原因
-  "systemMessage": "警告内容",           // 注入到上下文的系统消息
-  "hookSpecificOutput": {
-    "hookEventName": "PreToolUse",
-    "permissionDecision": "allow" | "deny" | "ask",
-    "permissionDecisionReason": "匹配了安全规则",
-    "updatedInput": { ... },            // 修改后的工具输入
-    "additionalContext": "额外上下文"     // 注入到对话
-  }
-}
-```
-
-### 各事件的 hookSpecificOutput
-
-| 事件 | 专有字段 | 作用 |
-|------|---------|------|
-| `PreToolUse` | `permissionDecision`, `permissionDecisionReason`, `updatedInput`, `additionalContext` | 拦截/修改工具输入 |
-| `PostToolUse` | `additionalContext`, `updatedMCPToolOutput` | 修改 MCP 工具输出 |
-| `PostToolUseFailure` | `additionalContext` | 失败后注入上下文 |
-| `UserPromptSubmit` | `additionalContext` | 注入额外上下文 |
-| `SessionStart` | `additionalContext`, `initialUserMessage`, `watchPaths` | 设置初始消息和文件监控 |
-| `PermissionRequest` | `decision`（含 `allow`/`deny` 子字段） | 权限请求的 Hook 决策 |
-| `PermissionDenied` | `retry` | 指示是否重试 |
-| `SubagentStart` | `additionalContext` | 子 Agent 启动时注入上下文 |
-| `Elicitation` | `action`, `content` | 控制用户输入对话框 |
-| `ElicitationResult` | `action`, `content` | Elicitation 结果处理 |
-| `Notification` | `additionalContext` | 通知事件注入上下文 |
-| `Setup` | `additionalContext` | 初始化时注入上下文 |
-| `CwdChanged` | `watchPaths` | 目录变更后更新监控路径 |
-| `FileChanged` | `watchPaths` | 文件变更后更新监控路径 |
-| `WorktreeCreate` | `worktreePath` | Worktree 创建通知 |
-
-## Hook 匹配机制：getMatchingHooks
-
-`getMatchingHooks()`（`src/utils/hooks.ts`，`getMatchingHooks` 函数）负责从所有来源中查找匹配的 Hook：
-
-### 多来源合并
-
-```
-getHooksConfig()
-  ├── getHooksConfigFromSnapshot()    ← settings.json 中的 Hook（user/project/local）
-  ├── getRegisteredHooks()            ← SDK 注册的 callback Hook
-  ├── getSessionHooks()               ← Agent/Skill 前置注册的 session Hook
-  └── getSessionFunctionHooks()       ← 运行时 function Hook
-```
-
-### 匹配规则
-
-`matcher` 字段支持三种模式（`matchesPattern()` 函数，`src/utils/hooks.ts`）：
-
-```
-"Write"              → 精确匹配
-"Write|Edit"         → 管道分隔的多值匹配
-"^Bash(git.*)"       → 正则匹配
-"*" 或 ""            → 通配（匹配所有）
-```
-
-### if 条件过滤
-
-Hook 可以指定 `if` 条件，只在特定输入时触发。`prepareIfConditionMatcher()`（`src/utils/hooks.ts`，`prepareIfConditionMatcher` 函数）预编译匹配器：
-
-```json
-{
-  "hooks": [{
-    "command": "check-git-branch.sh",
-    "if": "Bash(git push*)"
-  }]
-}
-```
-
-`if` 条件使用 `permissionRuleValueFromString` 解析，支持与权限规则相同的语法（工具名 + 参数模式）。Bash 工具还会使用 tree-sitter 进行 AST 级别的命令解析。
-
-### Hook 去重
-
-同一个 Hook 命令在不同配置层级（user/project/local）可能重复。系统按四部分复合键做 Map 去重：`${pluginRoot}\0${shell}\0${command}\0${ifCondition}`（由 `hookDedupKey()` 函数构建），保留**最后合并的层级**。
-
-## 工作区信任检查
-
-**所有 Hook 都要求工作区信任**（`shouldSkipHookDueToTrust()` 函数，`src/utils/hooks.ts`）。这是纵深防御措施——防止恶意仓库的 `.claude/settings.json` 在未信任的情况下执行任意命令。
-
-```typescript
-// 交互模式下，所有 Hook 要求信任
-const hasTrust = checkHasTrustDialogAccepted()
-return !hasTrust
-```
-
-SDK 非交互模式下信任是隐式的（`getIsNonInteractiveSession()` 为 true 时跳过检查）。
-
-## 四种 Hook 能力的源码映射
+Hook 不仅是"执行一个脚本"——它有四种不同的能力：
 
 ### 1. 拦截操作（PreToolUse）
 
+在工具执行前拦截，可以阻止危险操作：
+
 ```json
 {
   "hookSpecificOutput": {
-    "hookEventName": "PreToolUse",
-    "permissionDecision": "deny"
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "不允许在生产分支上强制推送"
   }
 }
 ```
 
-`processHookJSONOutput()` 将 `permissionDecision` 映射为 `result.permissionBehavior = 'deny'`，并设置 `blockingError`，阻止工具执行。
+### 2. 修改行为
 
-### 2. 修改行为（updatedInput / updatedMCPToolOutput）
+修改工具的输入或输出：
 
 ```json
 {
   "hookSpecificOutput": {
-    "hookEventName": "PreToolUse",
     "updatedInput": { "command": "npm test -- --bail" }
   }
 }
 ```
 
-`updatedInput` 替换原始工具输入；`updatedMCPToolOutput`（PostToolUse 事件）替换 MCP 工具的返回值——可用于过滤敏感数据。
+PostToolUse 的 `updatedMCPToolOutput` 可以替换 MCP 工具的返回值——用于过滤敏感数据。
 
-### 3. 注入上下文（additionalContext / systemMessage）
+### 3. 注入上下文
 
-- `additionalContext` → 通过 `createAttachmentMessage({ type: 'hook_additional_context' })` 注入为用户消息
-- `systemMessage` → 注入为系统警告，直接显示给用户
+向 AI 的对话中注入额外信息：
+- `additionalContext` — 注入为用户消息，AI 可以参考
+- `systemMessage` — 显示为系统警告
 
-### 4. 控制流程（continue / stopReason）
+### 4. 控制流程
+
+阻止 Agent 继续执行：
 
 ```json
-{ "continue": false, "stopReason": "构建失败，停止执行" }
+{
+  "continue": false,
+  "stopReason": "构建失败，停止执行"
+}
 ```
 
-`continue: false` 设置 `preventContinuation = true`，阻止 Agent 继续执行后续操作。
+**设计洞察**：四种能力从"被动观察"到"主动干预"递进。最简单的 Hook 只是记录日志，最强大的 Hook 可以阻止操作、修改输入、控制流程。
+
+## 六种 Hook 类型
+
+| 类型 | 执行方式 | 适用场景 |
+|------|---------|---------|
+| `command` | Shell 命令 | 通用脚本、CI 检查 |
+| `prompt` | 注入到 AI 上下文 | 代码规范提醒 |
+| `agent` | 启动子 Agent | 复杂分析任务 |
+| `http` | HTTP 请求 | 远程服务、Webhook |
+| `callback` | 内部 JS 函数 | 系统内置 Hook |
+| `function` | 运行时函数 | Agent/Skill 内部使用 |
+
+### 异步 Hook
+
+Hook 进程的 stdout 第一行如果是 `{"async":true}`，系统将其转为后台任务。异步 Hook 完成后通过通知机制汇报结果。
+
+**设计考量**：有些 Hook 需要长时间运行（如"等待 CI 结果"），不应该阻塞 Agent 的执行。异步 Hook 让这些操作在后台运行，完成后再通知 Agent。
+
+## 匹配机制
+
+### Matcher 模式
+
+```
+"Write"              → 精确匹配
+"Write|Edit"         → 多值匹配
+"^Bash(git.*)"       → 正则匹配
+"*" 或 ""            → 通配所有
+```
+
+### if 条件
+
+Hook 可以指定 `if` 条件，只在特定输入时触发：
+
+```json
+{
+  "command": "check-branch.sh",
+  "if": "Bash(git push*)"
+}
+```
+
+条件使用与权限规则相同的语法——工具名 + 参数模式。Bash 工具还会进行 AST 级别的命令解析。
+
+### 多来源合并
+
+Hook 从多个来源汇聚：
+- settings.json 中的配置（user/project/local）
+- SDK 注册的回调
+- Agent/Skill 的 frontmatter
+- 运行时动态注册
+
+同一命令可能在不同层级重复出现。系统按复合键去重，保留最后合并的层级。
+
+## 安全防护
+
+### 工作区信任
+
+**所有 Hook 都要求工作区信任**。这是纵深防御——防止恶意仓库的 `.claude/settings.json` 在未信任的情况下执行任意命令。
+
+**设计哲学**：Hook 有执行任意命令的能力，这个能力不应该被不可信的来源获取。项目级配置是团队共享的，任何人都可以修改——信任检查确保只有用户明确信任的项目才能运行 Hook。
+
+### 超时控制
+
+Hook 有默认 10 分钟的超时限制，可以通过配置调整。超时后 Hook 进程被终止，Agent 继续执行。
 
 ## Session Hook 的生命周期
 
-Agent 和 Skill 的前置 Hook 通过 `registerFrontmatterHooks()` 注册（调用位置：`src/tools/AgentTool/runAgent.ts`；定义位置：`src/utils/hooks/registerFrontmatterHooks.ts`），绑定到 agent 的 session ID。Agent 结束时通过 `clearSessionHooks()`（定义位置：`src/utils/hooks/sessionHooks.ts`）清理。
+Agent 和 Skill 可以注册 session Hook，绑定到特定的 session ID。Agent 结束时自动清理——Agent A 的 Hook 不会泄漏到 Agent B 的执行中。
 
-```typescript
-// runAgent.ts — 注册 agent 的前置 Hook
-registerFrontmatterHooks(rootSetAppState, agentId, agentDefinition.hooks, ...)
+**设计考量**：如果不自动清理，Agent A 的 PreToolUse Hook 可能意外拦截 Agent B 的工具调用，导致难以调试的问题。
 
-// runAgent.ts — finally 块清理
-clearSessionHooks(rootSetAppState, agentId)
-```
+## 接下来
 
-这确保 Agent A 的 Hook 不会泄漏到 Agent B 的执行中。
+- **Skills** — 理解基于 Hook 的技能系统
+- **MCP 配置** — 理解外部工具的注册
+- **权限模型** — 理解 PreToolUse Hook 与权限系统的协作

docs/extensibility/mcp-configuration.mdx

@@ -0,0 +1,84 @@
+---
+title: "MCP 配置"
+description: "MCP 服务器从多个来源汇聚配置。理解多来源合并、企业排他模式、项目配置审批和保留名称机制。"
+keywords: ["MCP", "配置", "settings.json", ".mcp.json", "企业策略"]
+---
+
+## 核心问题
+
+MCP（Model Context Protocol）让 Claude Code 可以使用外部工具——数据库查询、浏览器控制、API 调用等。但 MCP 配置来自多个来源：用户全局、项目级、插件、企业策略。如何合并？谁优先？
+
+## 配置来源与合并优先级
+
+配置按优先级从低到高合并，高优先级覆盖低优先级：
+
+```
+claude.ai 连接器（最低） → 插件 → 用户全局 → 项目配置 → 本地项目 → 内置动态（最高）
+```
+
+| 来源 | Scope | 说明 |
+|------|-------|------|
+| claude.ai 连接器 | `claudeai` | 网页端配置的远程连接器 |
+| 插件 | `dynamic` | 插件 manifest 中声明 |
+| 用户全局 | `user` | `~/.claude/settings.json` |
+| 项目配置 | `project` | `.mcp.json`（需审批） |
+| 本地项目 | `local` | `settings.local.json`（不提交 VCS） |
+| 内置动态 | `dynamic` | Computer Use 等内置服务器 |
+
+## 企业排他模式
+
+当企业管理员部署 `managed-mcp.json` 时，进入**排他模式**：只使用企业配置，忽略所有用户、项目、插件和 claude.ai 配置。
+
+**设计考量**：企业环境需要严格控制 AI 可以访问哪些外部工具。排他模式确保用户不能绕过企业策略添加自己的 MCP 服务器。
+
+## 项目配置审批
+
+`.mcp.json` 是项目级共享配置（可提交到 git），但需要用户显式审批才能生效。
+
+**为什么需要审批**？项目配置可能由任何人修改（包括恶意贡献者）。审批机制确保用户知情并同意项目提供的 MCP 服务器连接到他们的环境。
+
+审批状态持久化在本地配置中，不需要每次重新审批。
+
+## 传输类型
+
+MCP 服务器通过不同的传输方式连接：
+
+| 类型 | 适用场景 | 配置方式 |
+|------|---------|---------|
+| **stdio** | 本地工具（启动子进程） | `command` + `args` |
+| **SSE** | 远程 Server-Sent Events | `url` + 可选 `headers` |
+| **HTTP** | HTTP 流式传输 | `url` + 可选 `headers` |
+| **WebSocket** | 双向实时通信 | `wss://` URL |
+
+stdio 类型最常见——它启动一个本地子进程，通过 stdin/stdout 通信。远程类型（SSE/HTTP/WS）用于连接远程服务。
+
+### 认证
+
+远程 MCP 服务器支持 OAuth 认证。认证失败时进入 `needs-auth` 状态，15 分钟内不重复提示。
+
+## 插件集成
+
+插件通过 manifest 声明 MCP 服务器，命名空间为 `plugin:<pluginName>:<serverName>`，不会与手动配置冲突。
+
+插件服务器通过内容签名去重：
+- stdio 类型：基于 command + args
+- URL 类型：基于 URL
+- 手动配置优先于插件配置
+
+## 策略管控
+
+企业策略通过 allowlist 和 denylist 控制可用的 MCP 服务器。策略检查不仅匹配服务器名称，还匹配 command/args（stdio）和 URL 模式（远程）。
+
+## 保留名称
+
+以下名称被保留，用户无法手动配置：
+- `claude-in-chrome` — Chrome 浏览器控制
+- `computer-use` — 桌面自动化
+
+这防止用户意外覆盖内置服务器的配置。
+
+## 接下来
+
+- **MCP 协议** — 理解连接管理、工具发现和执行链路
+- **Hooks** — 理解 MCP 生命周期中的 Hook 集成
+- **自定义 Agent** — 理解 Agent 中引用 MCP 服务器

docs/extensibility/mcp-protocol.mdx

@@ -1,191 +1,109 @@
 ---
-title: "MCP 协议 - 连接管理、工具发现与执行链路"
-description: "从源码角度解析 Claude Code 的 MCP 集成：7 种传输层实现、connectToServer 的 memoize 缓存、工具发现的 LRU 策略、认证状态机、以及 MCP 工具如何进入权限检查链路。"
+title: "MCP 协议"
+description: "从配置到可用工具：MCP 连接管理、内置 vs 外部两种模式、工具发现和执行链路的设计。"
 keywords: ["MCP", "Model Context Protocol", "工具扩展", "MCP 客户端", "工具发现"]
 ---
 
-{/* 本章目标：从源码角度揭示 MCP 客户端的连接管理、工具发现协议和执行链路 */}
+## 核心问题
 
-## 架构总览：从配置到可用工具
+MCP 让 Claude Code 使用外部工具。但连接外部服务有延迟、可能失败、工具列表可能变化。如何管理这些不确定性？
+
+## 架构总览
 
 ```
-settings.json: { mcpServers: { "my-db": { command: "npx", args: [...] } } }
-  ↓
-getAllMcpConfigs()                    ← enterprise 独占或合并 user/project/local + plugin + claude.ai
-  ↓
-useManageMCPConnections()             ← React Hook 管理连接生命周期
-  ↓
-connectToServer(name, config)         ← memoize 缓存（lodash memoize）
-  ├── 创建 Transport（stdio/sse/http/...）
-  ├── new Client()                    ← @modelcontextprotocol/sdk
-  ├── client.connect(transport)       ← 超时控制（MCP_TIMEOUT, 默认 30s）
-  └── 返回 MCPServerConnection        ← { connected | failed | needs-auth | pending }
-  ↓
-fetchToolsForClient(client)           ← LRU(20) 缓存
-  ├── client.request({ method: 'tools/list' })
-  └── 每个工具包装为 MCPTool            ← 统一 Tool 接口
-  ↓
-assembleToolPool()                    ← 合并内置工具 + MCP 工具
-  ↓
-工具名格式: mcp__<serverName>__<toolName>  ← buildMcpToolName()
+配置（多来源合并） → 连接管理（缓存） → 工具发现（MCP 协议） → 工具执行
 ```
 
-## 7 种传输层实现
+## 两种 MCP 模式
 
-`connectToServer()`（`client.ts:596-1643`）根据 `config.type` 分发到不同的 Transport 实现：
+### 内置 MCP 服务器
 
-| 传输类型 | Transport 类 | 适用场景 | 认证方式 |
-|----------|-------------|---------|---------|
-| `stdio`（默认） | `StdioClientTransport` | 本地子进程 | 无 |
-| `sse` | `SSEClientTransport` | 远程 SSE 服务 | `ClaudeAuthProvider` + OAuth |
-| `http` | `StreamableHTTPClientTransport` | HTTP 流 | `ClaudeAuthProvider` + OAuth |
-| `sse-ide` | `SSEClientTransport` | IDE 集成 | lockfile token |
-| `ws-ide` | `WebSocketTransport` | IDE WebSocket | `X-Claude-Code-Ide-Authorization` |
-| `ws` | `WebSocketTransport` | WebSocket 服务 | session ingress token |
-| `claudeai-proxy` | `StreamableHTTPClientTransport` | claude.ai 代理 | OAuth bearer + 401 重试 |
+Computer Use、Chrome 控制等内置功能通过 MCP 协议暴露，但运行在**同进程内**——不启动子进程，无网络开销，无 IPC 序列化。
 
-### stdio 传输的进程管理
+**设计洞察**：内置服务器使用与外部服务器完全相同的 MCP 协议（`tools/list`、`tools/call`），但通过 `InProcessTransport` 在进程内通信。这意味着所有工具发现、权限检查、执行逻辑都是同一套代码——内置和外部工具的唯一区别是传输方式。
 
-stdio 类型的 MCP 服务器作为子进程运行，cleanup 时采用 **信号升级策略**（`client.ts:1431-1564`）：
+### 外部 MCP 服务器
+
+用户配置的外部工具，通过子进程（stdio）或网络连接（SSE/HTTP/WS）运行。
+
+| 维度 | 内置 | 外部 |
+|------|------|------|
+| 进程模型 | 同进程 | 子进程或网络 |
+| 启动开销 | 零 | 子进程启动或网络握手 |
+| 权限 | 自动授权 | 需要用户确认 |
+| 配置来源 | 动态注册 | settings.json / .mcp.json |
+| 名称保护 | 保留名，不可覆盖 | 自由命名 |
+
+## 连接管理
+
+### 缓存机制
+
+连接使用 memoize 缓存——相同的配置不会重复建立连接。缓存 key 包含服务器名和配置内容，配置变化时自动失效。
+
+### 重连机制
+
+远程连接有连续错误计数器。遇到网络错误（ECONNRESET、ETIMEDOUT 等）连续 3 次后，主动关闭连接触发重连。
+
+**设计考量**：网络连接是脆弱的——临时故障不应该永久禁用一个 MCP 服务器。自动重连确保服务恢复后工具能继续使用。
+
+### 清理策略
+
+stdio 类型的子进程清理使用信号升级策略：
 
 ```
 SIGINT (100ms) → SIGTERM (400ms) → SIGKILL
 ```
 
-总清理时间上限 600ms，防止 MCP 服务器关闭阻塞 CLI 退出。
+总清理时间上限 600ms。防止 MCP 服务器关闭阻塞 CLI 退出。
 
-### 远程传输的认证状态机
+### 并发控制
 
-SSE/HTTP 类型使用 `ClaudeAuthProvider` 实现 OAuth 认证流程。认证失败时进入 `needs-auth` 状态，并写入 15 分钟 TTL 的缓存文件（`mcp-needs-auth-cache.json`），避免重复弹出认证提示。
+| 类型 | 并发上限 | 原因 |
+|------|---------|------|
+| 本地（stdio） | 3 | 每个子进程是重量级资源 |
+| 远程（HTTP） | 20 | 轻量级 HTTP 请求 |
 
-```
-连接尝试 → 401 Unauthorized
-  ↓
-handleRemoteAuthFailure()
-  ├── logEvent('tengu_mcp_server_needs_auth')
-  ├── setMcpAuthCacheEntry(name)         ← 写入 15min TTL 缓存
-  └── return { type: 'needs-auth' }      ← UI 显示认证提示
-```
+## 工具发现
 
-## 连接缓存与重连机制
+### 从 MCP 到 Tool 接口
 
-`connectToServer` 使用 lodash `memoize` 缓存连接对象，缓存 key 为 `${name}-${JSON.stringify(config)}`。
-
-### 缓存失效触发
-
-当连接关闭时（`client.onclose`），清除所有相关缓存（`client.ts:1376-1404`）：
-
-```typescript
-client.onclose = () => {
-  const key = getServerCacheKey(name, serverRef)
-  fetchToolsForClient.cache.delete(name)      // 工具缓存
-  fetchResourcesForClient.cache.delete(name)  // 资源缓存
-  fetchCommandsForClient.cache.delete(name)   // 命令缓存
-  connectToServer.cache.delete(key)           // 连接缓存
-}
-```
-
-### 连接降级检测
-
-远程传输有 **连续错误计数器**（`client.ts:1229`）：
-
-```typescript
-let consecutiveConnectionErrors = 0
-const MAX_ERRORS_BEFORE_RECONNECT = 3
-```
-
-遇到终端错误（ECONNRESET、ETIMEDOUT、EPIPE 等）连续 3 次后，主动关闭 transport 触发重连。对于 HTTP 传输，还检测 session 过期（404 + JSON-RPC code -32001）。
-
-### 请求级超时保护
-
-每个 HTTP 请求使用独立的 `setTimeout` 超时（`wrapFetchWithTimeout`，`client.ts:493`），而非共享 `AbortSignal.timeout()`。原因是 Bun 对 AbortSignal.timeout 的 GC 是惰性的——每个请求约 2.4KB 原生内存，即使请求毫秒级完成也要等 60s 才回收。
-
-```typescript
-const controller = new AbortController()
-const timer = setTimeout(c => c.abort(...), MCP_REQUEST_TIMEOUT_MS, controller)
-timer.unref?.()  // 不阻止进程退出
-```
-
-## 工具发现：从 MCP 到 Tool 接口
-
-`fetchToolsForClient()`（`client.ts:1745-2000`）使用 `memoizeWithLRU` 缓存（上限 20），将 MCP 工具转换为 Claude Code 的统一 Tool 接口：
-
-```typescript
-const fullyQualifiedName = buildMcpToolName(client.name, tool.name)
-// 结果: "mcp__my-db__query"
-```
+MCP 服务器通过 `tools/list` 方法暴露工具列表。每个工具被包装为 Claude Code 统一的 Tool 接口，工具名格式为 `mcp__<serverName>__<toolName>`。
 
 ### 工具描述截断
 
-MCP 工具描述上限 2048 字符（`MAX_MCP_DESCRIPTION_LENGTH`）。OpenAPI 生成的 MCP 服务器曾观察到 15-60KB 的描述文档。
+MCP 工具描述上限 2048 字符。OpenAPI 生成的 MCP 服务器曾观察到 15-60KB 的描述文档——截断防止这些巨大描述占满 System Prompt。
 
 ### 工具能力标注
 
-每个 MCP 工具根据 `tool.annotations` 自动标注：
+MCP 工具通过 `annotations` 声明自身特性：
 
-| 注解 | 映射到 | 含义 |
-|------|--------|------|
-| `readOnlyHint` | `isReadOnly()` + `isConcurrencySafe()` | 只读，可并行 |
-| `destructiveHint` | `isDestructive()` | 破坏性操作 |
-| `openWorldHint` | `isOpenWorld()` | 开放世界（不可枚举） |
-| `title` | `userFacingName()` | 显示名称 |
+| 注解 | 含义 |
+|------|------|
+| `readOnlyHint` | 只读操作，可并行 |
+| `destructiveHint` | 破坏性操作 |
+| `openWorldHint` | 开放世界（不可枚举所有行为） |
 
-### MCP 工具的权限检查
+这些标注影响权限检查——只读工具在更多权限模式下被自动放行。
 
-MCP 工具默认返回 `{ behavior: 'passthrough' }`（`client.ts:1816-1834`），意味着它们始终进入权限确认流程。工具名使用 `mcp__` 前缀精确匹配权限规则。
+### 权限检查
 
-## MCP 工具的执行链路
+MCP 工具默认进入权限确认流程（`passthrough`），通过 `mcp__` 前缀匹配权限规则。用户可以为特定 MCP 服务器配置 allow/deny 规则。
+
+内置 MCP 工具通过白名单自动授权，不触发权限提示。
+
+## 执行链路
 
 ```
-AI 生成 tool_use: { name: "mcp__my-db__query", input: { sql: "..." } }
-  ↓
-MCPTool.call()                               ← client.ts:1835
-  ├── ensureConnectedClient()                ← 确保连接有效（重连）
-  ├── callMCPToolWithUrlElicitationRetry()   ← 带 Elicitation 重试
-  │   ├── client.request({ method: 'tools/call' })
-  │   ├── 处理图片结果（resize + persist）
-  │   └── 内容截断（mcpContentNeedsTruncation）
-  ├── McpSessionExpiredError → 重试一次
-  └── 返回 { data: content, mcpMeta }
+AI 调用 MCP 工具 → 确保连接有效 → 通过 MCP 协议执行 → 处理结果
+  → Session 过期？自动重试一次
+  → 结果过大？截断 + 持久化到磁盘
+  → 包含图片？自动 resize + 持久化
 ```
 
-### Session 过期自动重试
+**设计考量**：MCP 工具的执行结果可能很大（数据库查询结果、API 响应）。截断 + 持久化确保大型结果不会耗尽上下文窗口，同时 AI 仍然知道结果在哪里可以找到。
 
-HTTP 传输的 MCP session 可能过期。检测到 `McpSessionExpiredError` 后自动重试一次（`client.ts:1862`），因为 `ensureConnectedClient()` 已经清除了缓存并建立了新连接。
+## 接下来
 
-### 内容截断与持久化
-
-大型 MCP 工具输出通过 `truncateMcpContentIfNeeded` 截断，二进制内容（图片）通过 `persistBinaryContent` 写入文件并返回文件路径。图片自动 resize（`maybeResizeAndDownsampleImageBuffer`）。
-
-## MCP 连接的并发控制
-
-```typescript
-// 本地服务器并发连接数
-getMcpServerConnectionBatchSize()    // 默认 3
-
-// 远程服务器并发连接数
-getRemoteMcpServerConnectionBatchSize()  // 默认 20
-```
-
-本地 MCP 服务器（stdio）是重量级的子进程，默认限制 3 个并发连接。远程服务器是轻量级 HTTP 请求，允许 20 个并发。
-
-## 实际配置示例
-
-```json
-// settings.json 中的 MCP 配置
-{
-  "mcpServers": {
-    "my-database": {
-      "command": "npx",
-      "args": ["@my-org/db-mcp-server"],
-      "env": { "DB_URL": "postgres://..." }
-    },
-    "remote-api": {
-      "type": "http",
-      "url": "https://api.example.com/mcp"
-    }
-  }
-}
-```
-
-配置后，AI 的工具列表中会出现 `mcp__my-database__query` 和 `mcp__remote-api__*` 工具——与内置工具使用相同的权限检查链路和 UI 渲染。
+- **MCP 配置** — 理解多来源合并和企业管控
+- **工具系统** — 理解所有工具的统一接口
+- **权限模型** — 理解 MCP 工具的权限检查

docs/extensibility/skills.mdx

@@ -1,221 +1,123 @@
 ---
-title: "Skills 技能系统 - Prompt 即能力的架构哲学"
-description: "深入剖析 Claude Code Skills 系统的完整实现：从磁盘加载、Frontmatter 解析、预算感知描述截断、双模式执行（inline/fork）、权限白名单、条件激活、动态发现到远程技能加载，揭示一条完整的 Skill 生命周期链路。"
-keywords: ["Skills", "SkillTool", "技能加载", "Frontmatter", "whenToUse", "allowedTools", "fork执行", "动态发现"]
+title: "Skills 技能系统"
+description: "Prompt 即能力。Skill 不是代码，而是高质量的 Prompt + 权限配置的声明式封装。理解加载链路、两条执行路径和条件激活机制。"
+keywords: ["Skills", "技能加载", "Prompt 即能力", "条件激活"]
 ---
 
-{/* 本章目标：揭示 Skill 系统从文件到执行的全链路实现 */}
+## 核心洞见：Prompt 即能力
 
-## Tool vs Skill：本质差异
+Skill 的核心设计哲学：**复杂任务的关键不在代码逻辑，而在 Prompt 质量**。
+
+一个代码审查 Skill 不需要审查引擎，只需告诉 AI "审查什么、按什么顺序、输出什么格式"。Skill 把这种"经验"封装为可复用的 Markdown 文件。
 
 | | Tool | Skill |
 |---|---|---|
-| 粒度 | 单个原子操作（读文件、执行命令） | 一套完整的工作流（代码审查、创建 PR） |
-| 触发方式 | AI 自主选择 | 用户 `/skill-name` 或 AI 通过 `SkillTool` 自动匹配 |
-| 本质 | TypeScript 执行逻辑 | **Prompt + 权限配置**的声明式封装 |
-| 注册位置 | `src/tools.ts` → `getTools()` | `src/commands.ts` → `getCommands()` |
-| 执行器 | 各 Tool 的 `call()` 方法 | `SkillTool.call()` → 两条分支（inline / fork） |
+| 粒度 | 单个原子操作（读文件、执行命令） | 完整工作流（代码审查、创建 PR） |
+| 本质 | TypeScript 执行逻辑 | Prompt + 权限配置的声明式封装 |
+| 创建 | 需要写代码 | 写 Markdown 文件即可 |
 
-Skill 的核心洞见：**复杂任务的关键不在代码逻辑，而在 Prompt 质量**。一个代码审查 Skill 不需要审查引擎，只需告诉 AI "审查什么、按什么顺序、输出什么格式"——Skill 把这种"经验"封装为可复用的 Markdown。
+## Skill 的来源
 
-## Skill 的五个来源与加载链路
+| 来源 | 路径 | 特点 |
+|------|------|------|
+| **内置命令** | 硬编码 | `/commit`、`/compact` 等 70+ 命令 |
+| **Bundled Skills** | 编译时打包 | 延迟解压，享有不可截断特权 |
+| **磁盘 Skills** | `.claude/skills/` | 最重要的来源，支持多层级 |
+| **MCP Skills** | MCP Server 提供 | 远程内容，禁止内联 shell 命令 |
+| **Legacy Commands** | `.claude/commands/` | 向后兼容旧格式 |
 
-### 1. 内置命令（Built-in Commands）
-
-硬编码在 `src/commands.ts:258` 的 `COMMANDS` memoize 数组中，包含 70+ 条命令（`/commit`、`/review`、`/compact` 等）。这些是 TypeScript 模块而非 Markdown，但实现了相同的 `Command` 接口（`src/types/command.ts`）。
-
-### 2. Bundled Skills（编译时打包）
-
-通过 `registerBundledSkill()`（`src/skills/bundledSkills.ts:53`）在模块初始化时注册。关键特性：
-
-- **延迟文件提取**：如果 Skill 声明了 `files`（参考文件），首次调用时才解压到临时目录（`getBundledSkillExtractDir()`），使用 `O_NOFOLLOW | O_EXCL` 防止符号链接攻击（`safeWriteFile`，第 186 行）
-- **闭包级 memoize**：并发调用共享同一个 extraction promise，避免竞态写入
-- 来源标记为 `source: 'bundled'`，在 Prompt 预算中享有**不可截断**的特权
-
-### 3. 磁盘 Skills（`.claude/skills/`）
-
-由 `loadSkillsFromSkillsDir()`（`src/skills/loadSkillsDir.ts:407`）加载，这是最重要的加载路径：
+### 多层级磁盘加载
 
 ```
-管理策略: $MANAGED_DIR/.claude/skills/     (policySettings)
-用户全局: ~/.claude/skills/                 (userSettings)
-项目级:   .claude/skills/                   (projectSettings, 向上遍历至 home)
-附加目录: --add-dir 指定的路径下 .claude/skills/
+管理策略: $MANAGED_DIR/.claude/skills/     （企业管理）
+用户全局: ~/.claude/skills/                 （个人偏好）
+项目级:   .claude/skills/                   （团队共享）
+附加目录: --add-dir 指定的路径              （额外来源）
 ```
 
-**加载协议**：只识别 `skill-name/SKILL.md` 目录格式，不再支持单文件 `.md`。加载流程：
+每个 Skill 是一个 `skill-name/SKILL.md` 目录。加载时解析 YAML frontmatter 提取配置。
 
-1. `readdir` 扫描目录 → 仅保留 `isDirectory()` 或 `isSymbolicLink()` 的条目
-2. 在每个子目录中查找 `SKILL.md`，未找到则跳过
-3. `parseFrontmatter()` 解析 YAML 头部，提取 `whenToUse`、`allowedTools`、`context` 等字段
-4. `parseSkillFrontmatterFields()`（第 185 行）统一解析 16 个 frontmatter 字段
-5. `createSkillCommand()`（第 270 行）构造 `Command` 对象
+### 安全边界
 
-**去重机制**：使用 `realpath()` 解析符号链接获得规范路径（`getFileIdentity`，第 118 行），避免通过符号链接或重叠父目录导致的重复加载。
+MCP Skills 的 Prompt 内容**禁止执行内联 shell 命令**。因为远程内容不可信——如果允许，恶意 MCP Server 就可以通过 Skill 注入执行任意命令。
 
-### 4. MCP Skills（动态发现）
+## Frontmatter 配置
 
-通过 `registerMCPSkillBuilders()` 注册构建器，MCP Server 的 prompt 被 `mcpSkillBuilders.ts` 转换为 `Command` 对象。标记为 `loadedFrom: 'mcp'`。
-
-**安全边界**：MCP Skills 的 Prompt 内容**禁止执行内联 shell 命令**（`loadSkillsDir.ts:374` 的 `loadedFrom !== 'mcp'` 守卫），因为远程内容不可信。
-
-### 5. Legacy Commands（`/commands/` 目录）
-
-向后兼容的旧格式，由 `loadSkillsFromCommandsDir()`（第 566 行）加载。同时支持 `SKILL.md` 目录格式和单 `.md` 文件格式。
-
-## Frontmatter 字段全景
-
-一个 `SKILL.md` 的完整 frontmatter（`parseSkillFrontmatterFields`，第 185 行）：
+一个 SKILL.md 的完整配置：
 
 ```yaml
 ---
-name: code-review                    # 显示名称（覆盖目录名）
-description: 系统性代码审查           # 描述（或从 Markdown 首段提取）
-when_to_use: "用户说审查代码、找 bug"  # AI 自动匹配依据
-allowed-tools:                       # 工具白名单
+name: code-review
+description: 系统性代码审查
+when_to_use: "用户说审查代码、找 bug"
+allowed-tools:
   - Read
   - Grep
   - Glob
-argument-hint: "<file-or-directory>" # 参数提示
-arguments: [path]                    # 声明式参数名（用于 $ARGUMENTS 替换）
-model: opus                          # 模型覆盖
-effort: high                         # 努力级别
-context: fork                        # 执行模式：inline（默认）| fork
-agent: code-reviewer                 # 指定 Agent 定义文件
-user-invocable: true                 # 用户是否可 /调用
-disable-model-invocation: false      # 禁止 AI 自主调用
-version: "1.0"                       # 版本号
-paths:                               # 条件激活的文件路径模式
+context: fork              # 执行模式：inline | fork
+model: opus                # 模型覆盖
+effort: high               # 努力级别
+paths:                     # 条件激活
   - "src/**/*.ts"
-hooks:                               # Hook 配置
-  PreToolUse:
-    - command: ["echo", "checking"]
-shell: ["bash"]                      # Shell 执行环境
 ---
 ```
 
-解析后有 16 个字段被提取，其中 `allowedTools`、`model`、`effort` 在执行时动态修改 `toolPermissionContext`。
+- `when_to_use` — AI 根据此描述自动匹配用户意图
+- `allowed-tools` — 限制 Skill 可用的工具白名单
+- `context` — 控制执行模式（见下文）
+- `paths` — 条件激活，只在操作匹配文件时出现
 
-## 两条执行路径：Inline vs Fork
-
-SkillTool（`src/tools/SkillTool/SkillTool.ts:332`）在 `call()` 中根据 `command.context` 分流：
+## 两条执行路径
 
 ### Inline 模式（默认）
 
-Skill 的 Prompt 内容被注入为 **UserMessage**，在主对话流中继续执行：
+Skill 的 Prompt 内容被注入为用户消息，在主对话流中继续执行。AI "穿上"了 Skill 的经验，但仍在同一个对话中。
 
-1. `processPromptSlashCommand()` 处理参数替换（`$ARGUMENTS`）和 shell 命令展开（`` !`...` ``）
-2. `${CLAUDE_SKILL_DIR}` 被替换为 Skill 所在目录的绝对路径
-3. `${CLAUDE_SESSION_ID}` 被替换为当前会话 ID
-4. 返回 `newMessages`（注入到对话流）+ `contextModifier`（修改权限上下文）
-
-`contextModifier`（第 776 行）做了三件事：
-- **工具白名单注入**：将 `allowedTools` 合并到 `alwaysAllowRules.command`
-- **模型切换**：`resolveSkillModelOverride()` 处理模型覆盖，保留 `[1m]` 后缀以避免 200K 窗口截断
-- **努力级别覆盖**：修改 `effortValue`
+**优点**：共享主对话的完整上下文，可以引用之前的讨论。
+**缺点**：Skill 的中间过程会污染主对话的上下文。
 
 ### Fork 模式（`context: fork`）
 
-Skill 在**独立子 Agent** 中执行（`executeForkedSkill`，第 122 行）：
+Skill 在独立子 Agent 中执行，拥有独立的 token 预算和工具权限。执行完成后只返回最终结果，中间过程不保留。
 
-1. `prepareForkedCommandContext()` 构建隔离的 Agent 定义和 Prompt
-2. `runAgent()` 启动子 Agent 循环，拥有独立的 token 预算
-3. 通过 `onProgress` 回调报告工具使用进度
-4. 结果通过 `extractResultText()` 提取，子 Agent 的全部消息在提取后被释放（`agentMessages.length = 0`）
-5. 最终通过 `clearInvokedSkillsForAgent()` 清理状态
+**优点**：不污染主对话，适合长时间运行的任务。
+**缺点**：子 Agent 看不到主对话的完整上下文。
 
-Fork 模式适用于需要强隔离的场景（如长时间运行的审查任务），避免污染主对话的上下文。
+**设计考量**：大多数 Skill 使用 inline 模式就够了——它们需要主对话的上下文。Fork 模式适合"重型"任务（如完整的代码审查），这些任务的中间步骤很多，留在主对话中会浪费大量 token。
 
-## 权限模型：Safe Properties 白名单
+## 权限模型
 
-`checkPermissions()`（第 433 行）实现了一个五层权限检查：
+Skill 有五层权限检查：
 
 ```
-1. Deny 规则匹配（支持精确匹配和 prefix:* 通配符）
-   ↓ 未命中
-2. 远程 canonical Skill 自动放行（EXPERIMENTAL_SKILL_SEARCH + USER_TYPE === 'ant'）
-   ↓ 未命中
-3. Allow 规则匹配
-   ↓ 未命中
-4. Safe Properties 白名单检查（skillHasOnlySafeProperties，第 911 行）
-   ↓ 有非安全属性
-5. Ask 用户确认（附带精确匹配和前缀匹配两条建议规则）
+Deny 规则 → 远程 Skill 自动放行 → Allow 规则 → Safe Properties 白名单 → Ask 用户确认
 ```
 
-**Safe Properties**（`SAFE_SKILL_PROPERTIES`，第 876 行）是一个包含 30 个属性名的白名单（覆盖 `PromptCommand` 和 `CommandBase` 两个类型的所有安全属性）。任何不在白名单中的**有意义的属性值**（排除 `undefined`、`null`、空数组、空对象）都会触发权限请求。这是**正向安全**设计——未来新增的属性默认需要权限。
+**Safe Properties 白名单**是一个包含 30 个安全属性名的列表。任何不在白名单中的属性都会触发权限请求。这是**正向安全**设计——未来新增的属性默认需要权限，而非默认允许。
 
-## Prompt 预算：1% 上下文窗口的截断策略
+## Prompt 预算
 
-Skill 列表注入 System Prompt 时有严格的字符预算（`prompt.ts`）：
+Skill 列表注入 System Prompt 时有严格预算（约上下文窗口的 1%）：
+1. 优先保留 bundled Skills 的完整描述
+2. 非 bundled Skills 按剩余预算均分
+3. 预算不足时只保留名称
 
-- **预算计算**：`contextWindowTokens × 4 chars/token × 1%`（约 8000 字符）
-- **单条上限**：`MAX_LISTING_DESC_CHARS = 250` 字符（超出截断为 `…`）
-- **Bundled Skills 不可截断**：它们始终保留完整描述，预算不足时只截断非 bundled 的
-- **降级策略**：
-  1. 尝试完整描述 → 超预算？
-  2. Bundled 保留完整，非 bundled 均分剩余预算 → 每条描述低于 20 字符？
-  3. 非 bundled 仅保留名称
+**设计考量**：Skill 列表只是让 AI "知道有什么可用"。完整的 Skill Prompt 在 AI 选择后才加载，不需要全部塞进 System Prompt。
 
-`formatCommandsWithinBudget()`（`prompt.ts:70`）实现了这个三级降级。
+## 条件激活
 
-## 动态发现与条件激活
+带有 `paths` 模式的 Skill 在加载时不会立即可用。只有当被操作的文件路径匹配模式时，该 Skill 才被激活。
 
-### 基于文件路径的动态发现
+一个只在 `*.test.ts` 上激活的测试 Skill，平时完全不可见，只有当 AI 读取或编辑测试文件时才会出现。
 
-`discoverSkillDirsForPaths()`（`loadSkillsDir.ts:861`）在文件操作时触发：
-
-1. 从被操作的文件路径开始，**向上遍历**至 CWD（不包含 CWD 本身）
-2. 在每层查找 `.claude/skills/` 目录
-3. 使用 `realpath` 去重，`git check-ignore` 过滤 gitignored 目录
-4. 按路径深度排序（**深层优先**），更接近文件的 Skill 优先级更高
-
-### 条件激活（paths frontmatter）
-
-带有 `paths` 模式的 Skill 在加载时不会立即可用，而是存入 `conditionalSkills` Map。当被操作的文件路径匹配某个 Skill 的 paths 模式时（使用 `ignore` 库做 gitignore 风格匹配），该 Skill 才被**激活**——从 `conditionalSkills` 移入 `dynamicSkills`。
-
-这意味着一个只在 `*.test.ts` 上激活的测试 Skill，平时完全不可见，只有当 AI 读取或编辑测试文件时才会出现。
+**设计洞察**：这解决了"Skill 泛滥"问题——项目可能定义了几十个 Skill，但一次对话通常只需要其中几个。条件激活让 Skill 按需出现，而不是全部堆在 AI 面前让它选择。
 
 ## 使用频率排名
 
-`recordSkillUsage()`（`skillUsageTracking.ts`）使用指数衰减算法计算 Skill 排名分数：
+Skill 的排序使用指数衰减算法：一周前的使用权重减半。这确保常用的 Skill 排在前面，但偶尔用的老 Skill 也不会完全沉底。
 
-```
-score = usageCount × max(0.5^(daysSinceUse / 7), 0.1)
-```
+## 接下来
 
-- **7 天半衰期**：一周前的使用权重减半
-- **最低 0.1 保底**：避免老但高频使用的 Skill 完全沉底
-- **60 秒去抖**：同一 Skill 在 1 分钟内的多次调用只计一次，减少文件 I/O
-
-排名数据持久化在全局配置的 `skillUsage` 字段中。
-
-## 远程技能加载（Experimental）
-
-通过 `EXPERIMENTAL_SKILL_SEARCH` feature flag 控制，支持从远程（AKI/GCS/S3）加载 `_canonical_<slug>` 格式的 Skill：
-
-1. `validateInput()` 中 `stripCanonicalPrefix()` 拦截 canonical 名称
-2. `executeRemoteSkill()`（第 970 行）从远程 URL 加载 SKILL.md
-3. 支持 `gs://`、`https://`、`s3://` 等 URL 协议
-4. 内容经过 frontmatter 剥离、`${CLAUDE_SKILL_DIR}` 替换后直接注入
-5. 通过 `addInvokedSkill()` 注册到 compaction 保留状态，确保压缩后仍可恢复
-6. 远程 Skill 不经过 `processPromptSlashCommand`——无 `!command` 替换、无 `$ARGUMENTS` 展开
-
-## 完整生命周期总结
-
-```
-磁盘 SKILL.md
-  ↓ parseFrontmatter()
-  ↓ parseSkillFrontmatterFields() → 16 个字段
-  ↓ createSkillCommand() → Command 对象
-  ↓ 去重（realpath + seenFileIds）
-  ↓ 条件 Skill → conditionalSkills Map（等待路径匹配激活）
-  ↓ getSkillDirCommands() memoize 缓存
-  ↓ getAllCommands() 合并 local + MCP
-  ↓ formatCommandsWithinBudget() → 截断后的 Skill 列表注入 System Prompt
-  ↓ AI 选择匹配的 Skill
-  ↓ SkillTool.validateInput() → 名称校验 + 存在性检查
-  ↓ SkillTool.checkPermissions() → 五层权限检查
-  ↓ SkillTool.call() → inline 或 fork 执行
-  ↓ contextModifier() → 注入 allowedTools + model + effort
-  ↓ recordSkillUsage() → 更新使用频率排名
-```
+- **Hooks** — 理解 Skill 中可以使用的 Hook 机制
+- **MCP 配置** — 理解 MCP Skills 的来源
+- **自定义 Agent** — 理解 Skill 中指定的 Agent 定义

docs/external-dependencies.md

@@ -19,7 +19,7 @@
 | 11 | BigQuery Metrics | `api.anthropic.com/api/claude_code/metrics` | HTTPS | 默认启用 |
 | 12 | MCP Proxy | `mcp-proxy.anthropic.com` | HTTPS+WS | 使用 MCP 工具时 |
 | 13 | MCP Registry | `api.anthropic.com/mcp-registry` | HTTPS | 查询 MCP 服务器时 |
-| 14 | Bing Search | `www.bing.com` | HTTPS | WebSearch 工具 |
+| 14 | Web Search Pages | `www.bing.com`, `search.brave.com` | HTTPS | WebSearch 工具，可通过 `WEB_SEARCH_ADAPTER=bing|brave` 切换 |
 | 15 | Google Cloud Storage (更新) | `storage.googleapis.com` | HTTPS | 版本检查 |
 | 16 | GitHub Raw (Changelog/Stats) | `raw.githubusercontent.com` | HTTPS | 更新提示 |
 | 17 | Claude in Chrome Bridge | `bridge.claudeusercontent.com` | WSS | Chrome 集成 |
@@ -50,7 +50,7 @@
 
 - **端点**: `{region}-aiplatform.googleapis.com`
 - **认证**: `GoogleAuth` + `cloud-platform` scope
-- **文件**: `src/services/api/client.ts:228-298`
+- **文件**: `src/services/api/client.ts:221-298`
 
 ### 4. Azure Foundry
 
@@ -121,16 +121,20 @@ Anthropic 托管的 MCP 服务器代理。
 - **端点**: `https://api.anthropic.com/mcp-registry/v0/servers?version=latest&visibility=commercial`
 - **文件**: `src/services/mcp/officialRegistry.ts`
 
-### 14. Bing Search
+### 14. Web Search Pages
 
-WebSearch 工具的默认适配器，抓取 Bing 搜索结果。
+WebSearch 工具支持直接抓取 Bing 搜索结果页面，也支持通过 Brave 的 LLM Context API
+获取搜索上下文；可通过 `WEB_SEARCH_ADAPTER=bing|brave` 显式切换后端。
 
-- **端点**: `https://www.bing.com/search?q={query}&setmkt=en-US`
-- **文件**: `src/tools/WebSearchTool/adapters/bingAdapter.ts`
+- **Bing 端点**: `https://www.bing.com/search?q={query}&setmkt=en-US`
+- **Brave 端点**: `https://api.search.brave.com/res/v1/llm/context?q={query}`
+- **文件**:
+  - `packages/builtin-tools/src/tools/WebSearchTool/adapters/bingAdapter.ts`
+  - `packages/builtin-tools/src/tools/WebSearchTool/adapters/braveAdapter.ts`
 
 另外还有 Domain Blocklist 查询:
 - **端点**: `https://api.anthropic.com/api/web/domain_info?domain={domain}`
-- **文件**: `src/tools/WebFetchTool/utils.ts`
+- **文件**: `packages/builtin-tools/src/tools/WebFetchTool/utils.ts`
 
 ### 15. Google Cloud Storage (自动更新)
 
@@ -201,6 +205,7 @@ WebSearch 工具的默认适配器，抓取 Bing 搜索结果。
 | `{region}-aiplatform.googleapis.com` | Google Vertex AI | HTTPS |
 | `{resource}.services.ai.azure.com` | Azure Foundry | HTTPS |
 | `www.bing.com` | Bing 搜索 | HTTPS |
+| `search.brave.com` | Brave 搜索 | HTTPS |
 | `storage.googleapis.com` | 自动更新 | HTTPS |
 | `raw.githubusercontent.com` | Changelog / 插件统计 | HTTPS |
 | `bridge.claudeusercontent.com` | Chrome Bridge | WSS |

docs/feature-exploration-plan.md

@@ -1,457 +0,0 @@
-# Feature 探索计划书
-
-> 生成日期：2026-04-02
-> 代码库中已识别 89 个 feature flag，本文档按实现完整度和探索价值分级，制定探索优先级和路线图。
->
-> **已完成**：BUDDY（✅ 2026-04-02）、TRANSCRIPT_CLASSIFIER / Auto Mode（✅ 2026-04-02）
-
----
-
-## 一、总览
-
-### 按实现状态分类
-
-| 状态 | 数量 | 说明 |
-|------|------|------|
-| 已实现/可用 | 11 | 代码完整，开启 feature 后可运行（可能需要 OAuth 等外部依赖） |
-| 部分实现 | 8 | 核心逻辑存在但关键模块为 stub，需要补全 |
-| 纯 Stub | 15 | 所有函数/工具返回空值，需要从零实现 |
-| N/A | 55+ | 内部基础设施、低引用量辅助功能，或反编译丢失过多 |
-
-### 启用方式
-
-所有 feature 通过环境变量启用：
-
-```bash
-# 单个 feature
-FEATURE_BUDDY=1 bun run dev
-
-# 多个 feature 组合
-FEATURE_KAIROS=1 FEATURE_PROACTIVE=1 FEATURE_FORK_SUBAGENT=1 bun run dev
-```
-
----
-
-## 二、Tier 1 — 已实现/可用（优先探索）
-
-### 2.1 KAIROS（常驻助手模式）⭐ 最高优先级
-
-- **引用数**：154（全库最大）
-- **功能**：将 CLI 变为常驻后台助手，支持：
-  - 持久化 bridge 会话（跨重启复用 session）
-  - 后台执行任务（用户离开终端时继续工作）
-  - 推送通知到移动端（任务完成/需要输入时）
-  - 每日记忆日志 + `/dream` 知识蒸馏
-  - 外部频道消息接入（Slack/Discord/Telegram）
-- **子 Feature**：
-
-| 子 Feature | 引用 | 功能 |
-|-----------|------|------|
-| `KAIROS_BRIEF` | 39 | Brief 工具（`SendUserMessage`），结构化消息输出 |
-| `KAIROS_CHANNELS` | 19 | 外部频道消息接入 |
-| `KAIROS_PUSH_NOTIFICATION` | 4 | 移动端推送通知 |
-| `KAIROS_GITHUB_WEBHOOKS` | 3 | GitHub PR webhook 订阅 |
-| `KAIROS_DREAM` | 1 | 夜间记忆蒸馏 |
-
-- **关键文件**：`src/assistant/`、`src/tools/BriefTool/`、`src/services/mcp/channelNotification.ts`、`src/memdir/memdir.ts`
-- **外部依赖**：Anthropic OAuth（claude.ai 订阅）、GrowthBook 特性门控
-- **探索命令**：`FEATURE_KAIROS=1 FEATURE_KAIROS_BRIEF=1 FEATURE_PROACTIVE=1 bun run dev`
-
-**探索步骤**：
-1. 开启 feature，观察启动行为变化
-2. 测试 `/assistant`、`/brief` 命令
-3. 验证 BriefTool 输出模式
-4. 尝试频道消息接入
-5. 测试 `/dream` 记忆蒸馏
-
----
-
-### ~~2.2 TRANSCRIPT_CLASSIFIER（Auto Mode 分类器）~~ ✅ 已完成
-
-- **引用数**：108
-- **功能**：使用 LLM 对用户意图进行分类，实现 auto mode（自动决定工具权限）
-- **状态**：✅ prompt 模板已重建，功能完整可用（2026-04-02 完成）
-
----
-
-### 2.3 VOICE_MODE（语音输入）
-
-- **引用数**：46
-- **功能**：按键说话（Push-to-Talk），音频流式传输到 Anthropic STT 端点（Nova 3），实时转录显示
-- **当前状态**：**完整实现**，包括录音、WebSocket 流、转录插入
-- **关键文件**：`src/voice/voiceModeEnabled.ts`、`src/hooks/useVoice.ts`、`src/services/voiceStreamSTT.ts`
-- **外部依赖**：Anthropic OAuth（非 API key）、macOS 原生音频或 SoX
-- **探索命令**：`FEATURE_VOICE_MODE=1 bun run dev`
-- **默认快捷键**：长按空格键录音
-
-**探索步骤**：
-1. 确认 OAuth token 可用
-2. 测试按住空格录音 → 释放后转录
-3. 验证实时中间转录显示
-4. 测试 `/voice` 命令切换
-
----
-
-### 2.4 TEAMMEM（团队共享记忆）
-
-- **引用数**：51
-- **功能**：基于 GitHub 仓库的团队共享记忆系统，`memory/team/` 目录双向同步到 Anthropic 服务器
-- **当前状态**：**完整实现**，包括增量同步、冲突解决、密钥扫描、路径穿越防护
-- **关键文件**：`src/services/teamMemorySync/`（index、watcher、secretScanner）、`src/memdir/teamMemPaths.ts`
-- **外部依赖**：Anthropic OAuth + GitHub remote（`getGithubRepo()`）
-- **探索命令**：`FEATURE_TEAMMEM=1 bun run dev`
-
-**探索步骤**：
-1. 确认项目有 GitHub remote
-2. 开启后观察 `memory/team/` 目录创建
-3. 测试团队记忆写入和同步
-4. 验证密钥扫描防护
-
----
-
-### 2.5 COORDINATOR_MODE（多 Agent 编排）
-
-- **引用数**：32
-- **功能**：CLI 变为编排者，通过 AgentTool 派发任务给多个 worker 并行执行
-- **当前状态**：核心逻辑实现，worker agent 模块为 stub
-- **关键文件**：`src/coordinator/coordinatorMode.ts`（系统 prompt 完整）、`src/coordinator/workerAgent.ts`（stub）
-- **限制**：编排者只能使用 AgentTool/TaskStop/SendMessage，不能直接操作文件
-- **探索命令**：`FEATURE_COORDINATOR_MODE=1 CLAUDE_CODE_COORDINATOR_MODE=1 bun run dev`
-
-**探索步骤**：
-1. 补全 `workerAgent.ts` stub
-2. 测试多 worker 并行任务派发
-3. 验证 worker 结果汇总
-
----
-
-### 2.6 BRIDGE_MODE（远程控制）
-
-- **引用数**：28
-- **功能**：本地 CLI 注册为 bridge 环境，可从 claude.ai 或其他控制面远程驱动
-- **当前状态**：v1（env-based）和 v2（env-less）实现均存在
-- **关键文件**：`src/bridge/bridgeEnabled.ts`、`src/bridge/replBridge.ts`（v1）、`src/bridge/remoteBridgeCore.ts`（v2）
-- **外部依赖**：claude.ai OAuth、GrowthBook 门控 `tengu_ccr_bridge`
-- **探索命令**：`FEATURE_BRIDGE_MODE=1 bun run dev`
-
----
-
-### 2.7 FORK_SUBAGENT（上下文继承子 Agent）
-
-- **引用数**：4
-- **功能**：AgentTool 生成 fork 子 agent，继承父级完整对话上下文，优化 prompt cache
-- **当前状态**：**完整实现**（`forkSubagent.ts`），支持 worktree 隔离通知、递归防护
-- **关键文件**：`src/tools/AgentTool/forkSubagent.ts`
-- **探索命令**：`FEATURE_FORK_SUBAGENT=1 bun run dev`
-
----
-
-### 2.8 TOKEN_BUDGET（Token 预算控制）
-
-- **引用数**：9
-- **功能**：解析用户指定的 token 预算（如 "spend 2M tokens"），自动持续工作直到达到目标
-- **当前状态**：解析器**完整实现**，支持简写和详细语法；QueryEngine 中的周转逻辑已连接
-- **关键文件**：`src/utils/tokenBudget.ts`、`src/QueryEngine.ts`
-- **探索命令**：`FEATURE_TOKEN_BUDGET=1 bun run dev`
-
----
-
-### 2.9 MCP_SKILLS（MCP 技能发现）
-
-- **引用数**：9
-- **功能**：将 MCP 服务器提供的 prompt 类型命令筛选为可调用技能
-- **当前状态**：**功能性实现**（config 门控筛选器）
-- **关键文件**：`src/commands.ts`（`getMcpSkillCommands()`）
-- **探索命令**：`FEATURE_MCP_SKILLS=1 bun run dev`
-
----
-
-### 2.10 TREE_SITTER_BASH（Bash AST 解析）
-
-- **引用数**：3
-- **功能**：纯 TypeScript bash 命令 AST 解析器，用于 fail-closed 权限匹配
-- **当前状态**：**完整实现**（`bashParser.ts` ~2000行 + `ast.ts` ~400行）
-- **关键文件**：`src/utils/vendor/tree-sitter-bash/`
-- **探索命令**：`FEATURE_TREE_SITTER_BASH=1 bun run dev`
-
----
-
-### ~~2.11 BUDDY（虚拟伙伴）~~ ✅ 已完成
-
-- **引用数**：16
-- **功能**：`/buddy` 命令，支持 hatch/rehatch/pet/mute/unmute
-- **状态**：✅ 已合入，功能完整可用（2026-04-02 完成）
-
----
-
-## 三、Tier 2 — 部分实现（需要补全）
-
-### 3.1 PROACTIVE（主动模式）
-
-- **引用数**：37
-- **功能**：Tick 驱动的自主代理，定时唤醒执行工作，配合 SleepTool 控制节奏
-- **当前状态**：核心模块 `src/proactive/index.ts` **全部 stub**（activate/deactivate/pause 返回 false 或空操作）
-- **依赖**：与 KAIROS 强绑定（所有检查都是 `feature('PROACTIVE') || feature('KAIROS')`）
-- **补全工作量**：中等 — 需要实现 tick 生成、SleepTool 集成、暂停/恢复逻辑
-
-### 3.2 BASH_CLASSIFIER（Bash 命令分类器）
-
-- **引用数**：45
-- **功能**：LLM 驱动的 bash 命令意图分类（允许/拒绝/询问）
-- **当前状态**：`bashClassifier.ts` **全部 stub**（`matches: false`）
-- **补全工作量**：大 — 需要 LLM 调用实现、prompt 设计
-
-### 3.3 ULTRAPLAN（增强规划）
-
-- **引用数**：10
-- **功能**：关键字触发增强计划模式，输入 "ultraplan" 自动转为 plan
-- **当前状态**：关键字检测**完整实现**，`/ultraplan` 命令**为 stub**
-- **补全工作量**：小 — 只需实现命令处理逻辑
-
-### 3.4 EXPERIMENTAL_SKILL_SEARCH（技能语义搜索）
-
-- **引用数**：21
-- **功能**：DiscoverSkills 工具，根据当前任务语义搜索可用技能
-- **当前状态**：布线完整，核心搜索逻辑 stub
-- **补全工作量**：中等 — 需要实现搜索引擎和索引
-
-### 3.5 CONTEXT_COLLAPSE（上下文折叠）
-
-- **引用数**：20
-- **功能**：CtxInspectTool 让模型内省上下文窗口大小，优化压缩决策
-- **当前状态**：工具 stub，HISTORY_SNIP 子功能也 stub
-- **补全工作量**：中等
-
-### 3.6 WORKFLOW_SCRIPTS（工作流自动化）
-
-- **引用数**：10
-- **功能**：基于文件的自动化工作流 + `/workflows` 命令
-- **当前状态**：WorkflowTool、命令、加载器全部 stub
-- **补全工作量**：大 — 需要从零设计工作流 DSL
-
-### 3.7 WEB_BROWSER_TOOL（浏览器工具）
-
-- **引用数**：4
-- **功能**：模型可调用浏览器工具导航和交互网页
-- **当前状态**：工具注册存在，实现 stub
-- **补全工作量**：大
-
-### 3.8 DAEMON（后台守护进程）
-
-- **引用数**：3
-- **功能**：后台守护进程 + 远程控制服务器
-- **当前状态**：只有条件导入布线，无实现
-- **补全工作量**：极大
-
----
-
-## 四、Tier 3 — 纯 Stub / N/A（低优先级）
-
-| Feature | 引用 | 状态 | 说明 |
-|---------|------|------|------|
-| CHICAGO_MCP | 16 | N/A | Anthropic 内部 MCP 基础设施 |
-| UDS_INBOX | 17 | Stub | Unix 域套接字对等消息 |
-| MONITOR_TOOL | 13 | Stub | 文件/进程监控工具 |
-| BG_SESSIONS | 11 | Stub | 后台会话管理 |
-| SHOT_STATS | 10 | 无实现 | 逐 prompt 统计 |
-| EXTRACT_MEMORIES | 7 | 无实现 | 自动记忆提取 |
-| TEMPLATES | 6 | Stub | 项目/提示模板 |
-| LODESTONE | 6 | N/A | 内部基础设施 |
-| STREAMLINED_OUTPUT | 1 | — | 精简输出模式 |
-| HOOK_PROMPTS | 1 | — | Hook 提示词 |
-| CCR_AUTO_CONNECT | 3 | — | CCR 自动连接 |
-| CCR_MIRROR | 4 | — | CCR 镜像模式 |
-| CCR_REMOTE_SETUP | 1 | — | CCR 远程设置 |
-| NATIVE_CLIPBOARD_IMAGE | 2 | — | 原生剪贴板图片 |
-| CONNECTOR_TEXT | 7 | — | 连接器文本 |
-
-以及其余 40+ 个低引用量 feature。
-
----
-
-## 五、探索路线图
-
-### Phase 1：快速验证（无外部依赖）
-
-> 目标：确认代码可以正常运行，体验基本功能
-
-| 优先级 | Feature | 命令 | 预期效果 |
-|--------|---------|------|----------|
-| 1 | BUDDY | `FEATURE_BUDDY=1 bun run dev` | `/buddy hatch` 生成伙伴 |
-| 2 | FORK_SUBAGENT | `FEATURE_FORK_SUBAGENT=1 bun run dev` | Agent 可生成上下文继承的子任务 |
-| 3 | TOKEN_BUDGET | `FEATURE_TOKEN_BUDGET=1 bun run dev` | 输入 "spend 500k tokens" 测试自动持续 |
-| 4 | TREE_SITTER_BASH | `FEATURE_TREE_SITTER_BASH=1 bun run dev` | 更精确的 bash 权限匹配 |
-| 5 | MCP_SKILLS | `FEATURE_MCP_SKILLS=1 bun run dev` | MCP 服务器 prompt 提升为技能 |
-
-### Phase 2：核心功能探索（需要 OAuth）
-
-> 目标：体验 KAIROS 全套能力
-
-| 优先级 | Feature | 命令 | 预期效果 |
-|--------|---------|------|----------|
-| 1 | TRANSCRIPT_CLASSIFIER | `FEATURE_TRANSCRIPT_CLASSIFIER=1 bun run dev` | Auto mode 自动激活 |
-| 2 | KAIROS 全套 | `FEATURE_KAIROS=1 FEATURE_KAIROS_BRIEF=1 FEATURE_KAIROS_CHANNELS=1 FEATURE_PROACTIVE=1 bun run dev` | 常驻助手 + Brief 输出 + 频道消息 |
-| 3 | VOICE_MODE | `FEATURE_VOICE_MODE=1 bun run dev` | 按空格说话 |
-| 4 | TEAMMEM | `FEATURE_TEAMMEM=1 bun run dev` | 团队记忆同步 |
-| 5 | COORDINATOR_MODE | `FEATURE_COORDINATOR_MODE=1 CLAUDE_CODE_COORDINATOR_MODE=1 bun run dev` | 多 agent 编排 |
-
-### Phase 3：Stub 补全开发
-
-> 目标：将高价值 stub 实现为可用功能
-
-| 优先级 | Feature | 补全难度 | 价值 |
-|--------|---------|----------|------|
-| 1 | PROACTIVE | 中 | 自主工作能力 |
-| 2 | ULTRAPLAN | 小 | 增强规划 |
-| 3 | CONTEXT_COLLAPSE | 中 | 长对话优化 |
-| 4 | EXPERIMENTAL_SKILL_SEARCH | 中 | 技能发现 |
-| 5 | BASH_CLASSIFIER | 大 | 安全增强 |
-
----
-
-## 六、推荐组合方案
-
-### "全功能助手"组合
-
-```bash
-FEATURE_KAIROS=1 \
-FEATURE_KAIROS_BRIEF=1 \
-FEATURE_KAIROS_CHANNELS=1 \
-FEATURE_KAIROS_PUSH_NOTIFICATION=1 \
-FEATURE_PROACTIVE=1 \
-FEATURE_FORK_SUBAGENT=1 \
-FEATURE_TOKEN_BUDGET=1 \
-FEATURE_TRANSCRIPT_CLASSIFIER=1 \
-FEATURE_BUDDY=1 \
-bun run dev
-```
-
-### "多 Agent 协作"组合
-
-```bash
-FEATURE_COORDINATOR_MODE=1 \
-FEATURE_FORK_SUBAGENT=1 \
-FEATURE_BRIDGE_MODE=1 \
-FEATURE_BG_SESSIONS=1 \
-CLAUDE_CODE_COORDINATOR_MODE=1 \
-bun run dev
-```
-
-### "开发者增强"组合
-
-```bash
-FEATURE_TRANSCRIPT_CLASSIFIER=1 \
-FEATURE_TREE_SITTER_BASH=1 \
-FEATURE_TOKEN_BUDGET=1 \
-FEATURE_MCP_SKILLS=1 \
-FEATURE_CONTEXT_COLLAPSE=1 \
-bun run dev
-```
-
----
-
-## 七、风险与注意事项
-
-1. **OAuth 依赖**：KAIROS、VOICE_MODE、TEAMMEM、BRIDGE_MODE 需要 Anthropic OAuth 认证（claude.ai 订阅），API key 用户无法使用
-2. **GrowthBook 门控**：部分功能（VOICE_MODE 的 `tengu_cobalt_frost`、TEAMMEM 的 `tengu_herring_clock`）即使 feature flag 开启，还需要服务端 GrowthBook 开关
-3. **反编译不完整**：所有"已实现"功能均为反编译产物，可能存在运行时错误，需要逐个验证
-4. **Proactive stub**：KAIROS 的自主工作能力依赖 PROACTIVE，但 PROACTIVE 核心是 stub，需先补全
-5. **tsc 错误**：代码库有 ~1341 个 TypeScript 编译错误（来自反编译），不影响 Bun 运行时但在 IDE 中会有大量红线
-
----
-
-## 附录：Feature Flag 完整列表
-
-共 89 个 feature flag（按引用数降序）：
-
-| Feature | 引用 | Tier |
-|---------|------|------|
-| KAIROS | 154 | 1 |
-| TRANSCRIPT_CLASSIFIER | 108 | 1 |
-| TEAMMEM | 51 | 1 |
-| VOICE_MODE | 46 | 1 |
-| BASH_CLASSIFIER | 45 | 2 |
-| KAIROS_BRIEF | 39 | 1 |
-| PROACTIVE | 37 | 2 |
-| COORDINATOR_MODE | 32 | 1 |
-| BRIDGE_MODE | 28 | 1 |
-| EXPERIMENTAL_SKILL_SEARCH | 21 | 2 |
-| CONTEXT_COLLAPSE | 20 | 2 |
-| KAIROS_CHANNELS | 19 | 1 |
-| UDS_INBOX | 17 | 3 |
-| CHICAGO_MCP | 16 | 3 |
-| BUDDY | 16 | 1 |
-| HISTORY_SNIP | 15 | 2 |
-| MONITOR_TOOL | 13 | 3 |
-| COMMIT_ATTRIBUTION | 12 | — |
-| CACHED_MICROCOMPACT | 12 | — |
-| BG_SESSIONS | 11 | 3 |
-| WORKFLOW_SCRIPTS | 10 | 2 |
-| ULTRAPLAN | 10 | 2 |
-| SHOT_STATS | 10 | 3 |
-| TOKEN_BUDGET | 9 | 1 |
-| PROMPT_CACHE_BREAK_DETECTION | 9 | — |
-| MCP_SKILLS | 9 | 1 |
-| EXTRACT_MEMORIES | 7 | 3 |
-| CONNECTOR_TEXT | 7 | — |
-| TEMPLATES | 6 | 3 |
-| LODESTONE | 6 | 3 |
-| TREE_SITTER_BASH_SHADOW | 5 | — |
-| QUICK_SEARCH | 5 | — |
-| MESSAGE_ACTIONS | 5 | — |
-| DOWNLOAD_USER_SETTINGS | 5 | — |
-| DIRECT_CONNECT | 5 | — |
-| WEB_BROWSER_TOOL | 4 | 2 |
-| VERIFICATION_AGENT | 4 | — |
-| TERMINAL_PANEL | 4 | — |
-| SSH_REMOTE | 4 | — |
-| REVIEW_ARTIFACT | 4 | — |
-| REACTIVE_COMPACT | 4 | — |
-| KAIROS_PUSH_NOTIFICATION | 4 | 1 |
-| HISTORY_PICKER | 4 | — |
-| FORK_SUBAGENT | 4 | 1 |
-| CCR_MIRROR | 4 | — |
-| TREE_SITTER_BASH | 3 | 1 |
-| MEMORY_SHAPE_TELEMETRY | 3 | — |
-| MCP_RICH_OUTPUT | 3 | — |
-| KAIROS_GITHUB_WEBHOOKS | 3 | 1 |
-| FILE_PERSISTENCE | 3 | — |
-| DAEMON | 3 | 2 |
-| CCR_AUTO_CONNECT | 3 | — |
-| UPLOAD_USER_SETTINGS | 2 | — |
-| POWERSHELL_AUTO_MODE | 2 | — |
-| OVERFLOW_TEST_TOOL | 2 | — |
-| NEW_INIT | 2 | — |
-| NATIVE_CLIPBOARD_IMAGE | 2 | — |
-| HARD_FAIL | 2 | — |
-| ENHANCED_TELEMETRY_BETA | 2 | — |
-| COWORKER_TYPE_TELEMETRY | 2 | — |
-| BREAK_CACHE_COMMAND | 2 | — |
-| AWAY_SUMMARY | 2 | — |
-| AUTO_THEME | 2 | — |
-| ALLOW_TEST_VERSIONS | 2 | — |
-| AGENT_TRIGGERS_REMOTE | 2 | — |
-| AGENT_MEMORY_SNAPSHOT | 2 | — |
-| UNATTENDED_RETRY | 1 | — |
-| ULTRATHINK | 1 | — |
-| TORCH | 1 | — |
-| STREAMLINED_OUTPUT | 1 | — |
-| SLOW_OPERATION_LOGGING | 1 | — |
-| SKILL_IMPROVEMENT | 1 | — |
-| SELF_HOSTED_RUNNER | 1 | — |
-| RUN_SKILL_GENERATOR | 1 | — |
-| PERFETTO_TRACING | 1 | — |
-| NATIVE_CLIENT_ATTESTATION | 1 | — |
-| KAIROS_DREAM | 1 | 1 |
-| IS_LIBC_MUSL | 1 | — |
-| IS_LIBC_GLIBC | 1 | — |
-| HOOK_PROMPTS | 1 | — |
-| DUMP_SYSTEM_PROMPT | 1 | — |
-| COMPACTION_REMINDERS | 1 | — |
-| CCR_REMOTE_SETUP | 1 | — |
-| BYOC_ENVIRONMENT_RUNNER | 1 | — |
-| BUILTIN_EXPLORE_PLAN_AGENTS | 1 | — |
-| BUILDING_CLAUDE_APPS | 1 | — |
-| ANTI_DISTILLATION_CC | 1 | — |
-| AGENT_TRIGGERS | 1 | — |
-| ABLATION_BASELINE | 1 | — |

docs/features/acp-link.md

@@ -0,0 +1,201 @@
+# acp-link — ACP 代理服务器
+
+> 源码目录：`packages/acp-link/`
+> PR: #292
+> 新增时间：2026-04-18
+
+## 一、功能概述
+
+`acp-link` 是一个 ACP (Agent Client Protocol) 代理服务器，将 WebSocket 客户端桥接到 ACP agent 的 stdio 接口。它让 ACP agent（如 Claude Code）可以通过 WebSocket 远程访问，而不仅限于本地 stdio。
+
+### 核心特性
+
+- **WebSocket → stdio 桥接**：将浏览器/远程客户端的 WebSocket 连接转换为 ACP agent 的 stdin/stdout NDJSON 流
+- **会话管理**：创建、加载、恢复、列出、关闭会话
+- **权限审批流程**：客户端可远程审批 agent 的工具权限请求
+- **RCS 集成**：可与 Remote Control Server (RCS) 连接，将 ACP agent 注册到 RCS 并通过 Web UI 交互
+- **HTTPS 支持**：内置自签名证书生成，支持安全连接
+- **Token 认证**：自动生成或通过环境变量配置认证 token
+
+## 二、架构
+
+### 独立模式
+
+```
+┌──────────────────┐    WebSocket     ┌──────────────────┐    stdio/NDJSON    ┌──────────────┐
+│  浏览器/客户端     │ ◄──────────────►│  acp-link        │ ◄────────────────►│  ACP Agent   │
+│  (WS Client)     │  ws://host:port  │  (Proxy Server)  │  spawn subprocess │  (Claude等)   │
+└──────────────────┘                  └──────────────────┘                    └──────────────┘
+```
+
+### RCS 集成模式
+
+```
+┌──────────────┐    WebSocket     ┌──────────────────┐    stdio/NDJSON    ┌──────────────┐
+│  RCS Web UI  │ ◄──────────────►│  Remote Control  │ ◄─────────────────►│  acp-link    │
+│  (/code/*)   │  ACP Relay WS   │  Server (RCS)    │  ACP events        │  + Agent     │
+└──────────────┘                  └──────────────────┘                    └──────────────┘
+```
+
+### 文件结构
+
+```
+packages/acp-link/
+├── src/
+│   ├── server.ts        # 主服务器：WS 连接管理、会话管理、权限处理、消息桥接
+│   ├── rcs-upstream.ts  # RCS 上游客户端：REST 注册 + WS identify 两步流程
+│   ├── cert.ts          # TLS 证书生成（自签名）
+│   ├── logger.ts        # 日志模块
+│   ├── types.ts         # JSON-RPC 和 ACP 协议类型定义
+│   ├── cli/
+│   │   ├── bin.ts       # CLI 入口
+│   │   ├── command.ts   # 命令行参数解析
+│   │   ├── app.ts       # 应用启动
+│   │   └── context.ts   # 上下文配置
+│   └── __tests__/       # 测试（cert, server, types）
+├── package.json
+└── tsconfig.json
+```
+
+## 三、安装与使用
+
+### 基本用法
+
+```bash
+# 直接运行（在 monorepo 中）
+# 注意：claude 本身不支持 ACP，需要用 ccb-bun --acp 启动 ACP agent
+bun packages/acp-link/src/cli/bin.ts ccb-bun -- --acp
+
+# 指定端口和主机
+acp-link --port 9000 --host 0.0.0.0 ccb-bun -- --acp
+
+# 启用 HTTPS（自签名证书）
+acp-link --https ccb-bun -- --acp
+
+# 调试模式
+acp-link --debug ccb-bun -- --acp
+```
+
+### CLI 参考
+
+```
+USAGE
+  acp-link [--port value] [--host value] [--debug] [--no-auth] [--https] <command>...
+  acp-link --help
+  acp-link --version
+
+FLAGS
+       [--port]     Port to listen on                  [default = 9315]
+       [--host]     Host to bind to                    [default = localhost]
+       [--debug]    Enable debug logging to file
+       [--no-auth]  Disable authentication (dangerous)
+       [--https]    Enable HTTPS with self-signed cert
+    -h  --help      Print help information and exit
+    -v  --version   Print version information and exit
+
+ARGUMENTS
+  command...  Agent command followed by its arguments (e.g. "ccb-bun -- --acp")
+```
+
+## 四、认证
+
+默认启动时自动生成随机 token。客户端连接时需通过 query 参数传递：
+
+```
+ws://localhost:9315/ws?token=<your-token>
+```
+
+配置固定 token：
+
+```bash
+ACP_AUTH_TOKEN=my-fixed-token acp-link ccb-bun -- --acp
+```
+
+禁用认证（不推荐，仅用于开发）：
+
+```bash
+acp-link --no-auth ccb-bun -- --acp
+```
+
+## 五、RCS 集成
+
+acp-link 支持将 ACP agent 注册到 Remote Control Server，通过 Web UI 远程操控。
+
+### 连接方式
+
+```bash
+# 通过环境变量配置 RCS 连接
+ACP_RCS_URL=http://localhost:3000 \
+ACP_RCS_TOKEN=sk-rcs-your-key \
+acp-link ccb-bun -- --acp
+```
+
+### 注册流程（两步）
+
+1. **REST 注册**：通过 `POST /v1/environments/bridge` 向 RCS 注册环境
+2. **WS identify**：建立 WebSocket 连接后发送 `identify` 消息（携带 agentId），替代完整 `register`
+
+```
+acp-link                          RCS
+   │                                │
+   │── POST /v1/environments/bridge ──►│  (REST 注册)
+   │◄── { agentId, sessionId } ───────│
+   │                                │
+   │── WS connect ─────────────────►│  (WebSocket)
+   │── identify { agentId } ────────►│  (WS 标识)
+   │◄── identified ─────────────────│
+   │                                │
+   │── ACP events ─────────────────►│  (双向消息转发)
+   │◄── user prompts/permissions ───│
+```
+
+## 六、权限模式
+
+### permissionMode 传递链
+
+权限模式通过整条链路传递：Web UI → RCS → acp-link → ACP agent。
+
+支持的权限模式：
+- `default` — 每次请求权限确认
+- `auto` — 自动判断
+- `acceptEdits` — 自动接受编辑
+- `plan` — 规划模式
+- `dontAsk` — 不询问
+- `bypassPermissions` — 绕过权限（需 sandbox 环境）
+
+### fallback 链
+
+当客户端未显式传递 permissionMode 时，使用以下 fallback 链：
+
+```
+客户端传值 > config.permissionMode > ACP_PERMISSION_MODE 环境变量
+```
+
+示例：
+
+```bash
+ACP_PERMISSION_MODE=auto acp-link ccb-bun -- --acp
+```
+
+## 七、权限管道（2026-04-18 改进）
+
+### 模式同步
+
+`applySessionMode` 在 agent 切换权限模式时同步 `appState.toolPermissionContext.mode`，确保内部权限上下文与 ACP 客户端状态一致。
+
+### 统一权限流水线
+
+`createAcpCanUseTool` 接入 `hasPermissionsToUseTool` 统一权限流水线，替代原来分散的处理逻辑。支持 `onModeChange` 回调，模式变更时实时同步。
+
+### bypass 检测
+
+`bypassPermissions` 模式增加可用性检测 — 仅在非 root 或 sandbox 环境中允许启用，防止权限绕过的安全风险。
+
+## 八、环境变量
+
+| 变量 | 说明 |
+|------|------|
+| `ACP_AUTH_TOKEN` | 固定认证 token（默认自动生成） |
+| `ACP_PERMISSION_MODE` | 默认权限模式 fallback |
+| `ACP_RCS_URL` | RCS 服务器地址（启用 RCS 集成） |
+| `ACP_RCS_TOKEN` | RCS API token |

docs/features/acp-zed.md

@@ -0,0 +1,189 @@
+# ACP (Agent Client Protocol) — Zed / IDE 集成
+
+> Feature Flag: `FEATURE_ACP=1`（build 和 dev 模式默认启用）
+> 实现状态：可用（支持 Zed、Cursor 等 ACP 客户端）
+> 源码目录：`src/services/acp/`
+
+## 一、功能概述
+
+ACP (Agent Client Protocol) 是一种标准化的 stdio 协议，允许 IDE 和编辑器通过 stdin/stdout 的 NDJSON 流驱动 AI Agent。CCB 实现了完整的 ACP agent 端，可以被 Zed、Cursor 等支持 ACP 的客户端直接调用。
+
+### 核心特性
+
+- **会话管理**：新建 / 恢复 / 加载 / 分叉 / 关闭会话
+- **历史回放**：恢复会话时自动加载并回放对话历史
+- **权限桥接**：ACP 客户端的权限决策映射到 CCB 的工具权限系统
+- **斜杠命令 & Skills**：加载真实命令列表，支持 `/commit`、`/review` 等 prompt 型 skill
+- **Context Window 跟踪**：精确的 usage_update，含 model prefix matching
+- **Prompt 排队**：支持连续发送多条 prompt，自动排队处理
+- **模式切换**：auto / default / acceptEdits / plan / dontAsk / bypassPermissions
+- **模型切换**：运行时切换 AI 模型
+
+## 二、架构
+
+```
+┌──────────────┐    NDJSON/stdio    ┌──────────────────┐
+│  Zed / IDE   │ ◄────────────────► │  CCB ACP Agent   │
+│  (Client)    │   stdin / stdout   │  (Agent)         │
+└──────────────┘                    │                  │
+                                    │  entry.ts        │ ← stdio → NDJSON stream
+                                    │  agent.ts        │ ← ACP protocol handler
+                                    │  bridge.ts       │ ← SDKMessage → ACP SessionUpdate
+                                    │  permissions.ts  │ ← 权限桥接
+                                    │  utils.ts        │ ← 通用工具
+                                    │                  │
+                                    │  QueryEngine     │ ← 内部查询引擎
+                                    └──────────────────┘
+```
+
+### 文件职责
+
+| 文件 | 职责 |
+|------|------|
+| `entry.ts` | 入口，创建 stdio → NDJSON stream，启动 `AgentSideConnection` |
+| `agent.ts` | 实现 ACP `Agent` 接口：会话 CRUD、prompt、cancel、模式/模型切换 |
+| `bridge.ts` | `SDKMessage` → ACP `SessionUpdate` 转换：文本/思考/工具/用量/编辑 diff |
+| `permissions.ts` | ACP `requestPermission()` → CCB `CanUseToolFn` 桥接 |
+| `utils.ts` | Pushable、流转换、权限模式解析、session fingerprint、路径显示 |
+
+## 三、配置 Zed 编辑器
+
+### 3.1 Zed settings.json 配置
+
+打开 Zed 的 `settings.json`（`Cmd+,` → Open Settings），添加 `agent_servers` 配置：
+
+```json
+{
+  "agent_servers": {
+    "ccb": {
+      "type": "custom",
+      "command": "ccb",
+      "args": ["--acp"]
+    }
+  }
+}
+```
+
+### 3.3 API 认证配置
+
+CCB 的 ACP agent 在启动时会自动加载 `settings.json` 中的环境变量（`ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN` 等）。确保已通过 `/login` 配置好 API 供应商。
+
+也可通过环境变量传入：
+
+```json
+{
+  "agent_servers": {
+    "claude-code": {
+      "command": "ccb",
+      "args": ["--acp"],
+      "env": {
+        "ANTHROPIC_BASE_URL": "https://api.example.com/v1",
+        "ANTHROPIC_AUTH_TOKEN": "sk-xxx"
+      }
+    }
+  }
+}
+```
+
+### 3.4 在 Zed 中使用
+
+1. 配置完成后重启 Zed
+2. 打开任意项目目录
+3. 按 `Cmd+'`（macOS）或 `Ctrl+'`（Linux）打开 Agent Panel
+4. 在 Agent Panel 顶部的下拉菜单中选择 **claude-code**
+5. 开始对话
+
+### 3.5 功能说明
+
+| 功能 | 操作 |
+|------|------|
+| 对话 | 在 Agent Panel 中直接输入消息 |
+| 斜杠命令 | 输入 `/` 查看可用 skills 列表（如 `/commit`、`/review`） |
+| 工具权限 | 弹出权限请求时选择 Allow / Reject / Always Allow |
+| 模式切换 | 通过 Agent Panel 的设置菜单切换 auto/default/plan 等模式 |
+| 模型切换 | 通过 Agent Panel 的设置菜单切换 AI 模型 |
+| 会话恢复 | 关闭重开 Zed 后，之前的会话可自动恢复（含历史消息） |
+
+## 四、配置其他 ACP 客户端
+
+ACP 是开放协议，任何支持 ACP 的客户端都可以连接 CCB。通用配置模式：
+
+```
+命令: ccb --acp
+参数: ["--acp"]
+通信: stdin/stdout NDJSON
+协议版本: ACP v1
+```
+
+### 4.1 Cursor
+
+在 Cursor 的设置中配置 MCP / Agent Server，使用同样的 `ccb --acp` 命令。
+
+### 4.2 自定义客户端
+
+使用 `@agentclientprotocol/sdk` 可以快速构建 ACP 客户端：
+
+```typescript
+import { ClientSideConnection, ndJsonStream } from '@agentclientprotocol/sdk'
+
+// 创建连接（将 ccb --acp 作为子进程启动）
+const child = spawn('ccb', ['--acp'])
+const stream = ndJsonStream(
+  Writable.toWeb(child.stdin),
+  Readable.toWeb(child.stdout),
+)
+
+const client = new ClientSideConnection(stream)
+
+// 初始化
+await client.initialize({ clientCapabilities: {} })
+
+// 创建会话
+const { sessionId } = await client.newSession({
+  cwd: '/path/to/project',
+})
+
+// 发送 prompt
+const response = await client.prompt({
+  sessionId,
+  prompt: [{ type: 'text', text: 'Hello, explain this project' }],
+})
+
+// 监听 session 更新
+client.on('sessionUpdate', (update) => {
+  console.log('Update:', update)
+})
+```
+
+## 五、ACP 协议支持矩阵
+
+| 方法 | 状态 | 说明 |
+|------|------|------|
+| `initialize` | ✅ | 返回 agent 信息和能力 |
+| `authenticate` | ✅ | 无需认证（自托管） |
+| `newSession` | ✅ | 创建新会话 |
+| `resumeSession` | ✅ | 恢复已有会话（含历史回放） |
+| `loadSession` | ✅ | 加载指定会话（含历史回放） |
+| `listSessions` | ✅ | 列出可用会话 |
+| `forkSession` | ✅ | 分叉会话 |
+| `closeSession` | ✅ | 关闭会话 |
+| `prompt` | ✅ | 发送消息，支持排队 |
+| `cancel` | ✅ | 取消当前/排队的 prompt |
+| `setSessionMode` | ✅ | 切换权限模式 |
+| `setSessionModel` | ✅ | 切换 AI 模型 |
+| `setSessionConfigOption` | ✅ | 动态修改配置 |
+
+### SessionUpdate 类型
+
+| 类型 | 状态 | 说明 |
+|------|------|------|
+| `agent_message_chunk` | ✅ | 助手文本消息 |
+| `agent_thought_chunk` | ✅ | 思考/推理内容 |
+| `user_message_chunk` | ✅ | 用户消息（历史回放） |
+| `tool_call` | ✅ | 工具调用开始 |
+| `tool_call_update` | ✅ | 工具调用结果/状态更新 |
+| `usage_update` | ✅ | token 用量 + context window |
+| `plan` | ✅ | TodoWrite → plan entries |
+| `available_commands_update` | ✅ | 斜杠命令 & skills 列表 |
+| `current_mode_update` | ✅ | 模式切换通知 |
+| `config_option_update` | ✅ | 配置更新通知 |

docs/features/all-features-guide.md

@@ -0,0 +1,574 @@
+# Claude Code Best (CCB) — 全功能使用指南
+
+本文档覆盖我们通过 13 个 PR 为 CCB 恢复/新增的**全部功能**，按类别组织，每个功能包含说明、使用方法和示例。
+
+---
+
+## 目录
+
+1. [Buddy 伴侣系统](#1-buddy-伴侣系统)
+2. [Remote Control 远程控制](#2-remote-control-远程控制)
+3. [定时任务 /schedule](#3-定时任务-schedule)
+4. [Voice Mode 语音模式](#4-voice-mode-语音模式)
+5. [Chrome 浏览器控制](#5-chrome-浏览器控制)
+6. [Computer Use 屏幕操控](#6-computer-use-屏幕操控)
+7. [Feature Flags 与 GrowthBook](#7-feature-flags-与-growthbook)
+8. [/ultraplan 高级规划](#8-ultraplan-高级规划)
+9. [Daemon 后台守护](#9-daemon-后台守护)
+10. [Pipe IPC 多实例协作](#10-pipe-ipc-多实例协作)
+11. [LAN Pipes 局域网群控](#11-lan-pipes-局域网群控)
+12. [Monitor 后台监控](#12-monitor-后台监控)
+13. [Workflow 工作流脚本](#13-workflow-工作流脚本)
+14. [Coordinator 多Worker协调](#14-coordinator-多worker协调)
+15. [Proactive 自主模式](#15-proactive-自主模式)
+16. [History / Snip 历史管理](#16-history--snip-历史管理)
+17. [Fork 子Agent](#17-fork-子agent)
+18. [其他恢复的工具](#18-其他恢复的工具)
+
+---
+
+## 1. Buddy 伴侣系统
+
+**PR**: #82 `refactor(buddy): align companion system with official CLI`
+**Feature Flag**: `BUDDY`
+
+### 说明
+Buddy 是一个后台运行的伴侣 AI，在你主对话进行的同时，异步观察会话内容并提供建议。
+
+### 使用
+```bash
+# 启动时自动加载（feature 默认开启）
+bun run dev
+
+# 在对话中，Buddy 会在适当时机自动提供建议
+# 例如当你在调试时，Buddy 可能提示你检查日志
+```
+
+---
+
+## 2. Remote Control 远程控制
+
+**PR**: #60 `feat: enable Remote Control (BRIDGE_MODE)` + #170 `feat: restore daemon supervisor`
+**Feature Flag**: `BRIDGE_MODE`
+
+### 说明
+通过 WebSocket 远程控制 Claude Code 会话。支持自托管私有部署。
+
+### 使用
+```bash
+# 启动远程控制模式
+bun run dev -- remote-control
+
+# 使用自托管服务器
+CLAUDE_BRIDGE_BASE_URL=https://your-server.com CLAUDE_BRIDGE_OAUTH_TOKEN=your-token bun run dev --remote-control
+
+# 或通过 /remote-control 命令在会话中启动
+/remote-control
+```
+
+### 命令
+- `claude remote-control` / `claude rc` — 启动远程控制客户端
+- `claude bridge` — 同上（别名）
+
+---
+
+## 3. 定时任务 /schedule
+
+**PR**: #88 `feat: enable /schedule by adding AGENT_TRIGGERS_REMOTE`
+**Feature Flag**: `AGENT_TRIGGERS_REMOTE`
+
+### 说明
+创建定时执行的远程 agent 任务，支持 cron 表达式。
+
+### 使用
+```
+/schedule create "每天检查依赖更新" --cron "0 9 * * *" --prompt "检查 package.json 中的过期依赖并创建更新 PR"
+/schedule list          — 列出所有定时任务
+/schedule delete <id>   — 删除指定任务
+```
+
+---
+
+## 4. Voice Mode 语音模式
+
+**PR**: #92 `feat: enable /voice mode with native audio binaries`
+**Feature Flag**: `VOICE_MODE`
+
+### 说明
+Push-to-Talk 语音输入，音频通过 WebSocket 流式传输到 Anthropic STT（Nova 3）。需要 Anthropic OAuth 认证（非 API key）。
+
+### 使用
+```bash
+# 确保已通过 OAuth 登录
+claude auth login
+
+# 在会话中按住指定键说话
+# 松开后自动转写为文字输入
+```
+
+### 前提条件
+- Anthropic OAuth 认证（不支持 API key 模式）
+- 系统麦克风权限
+
+---
+
+## 5. Chrome 浏览器控制
+
+**PR**: #93 `feat: enable Claude in Chrome MCP with full browser control`
+**Feature Flag**: `CHICAGO_MCP`
+
+### 说明
+通过 Chrome 扩展控制浏览器：导航、点击、填表、截图、执行 JS。
+
+### 使用
+```bash
+# 启动带 Chrome 控制的模式
+bun run dev -- --chrome
+
+# 安装 Chrome 扩展后，AI 可以：
+# - 打开网页、点击按钮
+# - 填写表单
+# - 截取页面内容
+# - 执行 JavaScript
+```
+
+### AI 可用工具
+- `navigate` — 导航到 URL
+- `click` / `find` / `form_input` — 页面交互
+- `get_page_text` / `read_page` — 读取内容
+- `javascript_tool` — 执行 JS
+- `gif_creator` — 录制操作 GIF
+
+---
+
+## 6. Computer Use 屏幕操控
+
+**PR**: #98 + #137 `feat: Computer Use — 跨平台 Executor + Python Bridge + GUI 无障碍`
+**Feature Flag**: `CHICAGO_MCP`
+
+### 说明
+跨平台屏幕操控：截图、键鼠模拟、应用管理。支持 macOS + Windows，Linux 后端待完成。
+
+### 使用
+```bash
+# 启动后 AI 可自动调用屏幕操控工具
+bun run dev
+
+# AI 可以：
+# - 截取屏幕/窗口截图
+# - 模拟键盘输入和鼠标操作
+# - 列出运行的应用
+# - 使用剪贴板
+```
+
+### 平台支持
+| 平台 | 截图 | 键鼠 | 应用管理 |
+|------|------|------|----------|
+| macOS | ✅ | ✅ | ✅ |
+| Windows | ✅ | ✅ | ✅ |
+| Linux | ⏳ | ⏳ | ⏳ |
+
+---
+
+## 7. Feature Flags 与 GrowthBook
+
+**PR**: #140 + #153 `feat: enable GrowthBook local gate defaults`
+**Feature Flags**: `SHOT_STATS`, `PROMPT_CACHE_BREAK_DETECTION`, `TOKEN_BUDGET`
+
+### 说明
+本地 GrowthBook gate defaults 机制，绕过远程 feature flag 服务，确保功能在无网络时也可使用。
+
+### 使用
+```bash
+# 通过环境变量启用任意 feature
+FEATURE_PROACTIVE=1 bun run dev
+
+# dev/build 模式有各自的默认启用列表
+# 查看 scripts/dev.ts 中的 DEFAULT_FEATURES
+```
+
+### 关键 feature flags
+| Flag | 说明 |
+|------|------|
+| `SHOT_STATS` | API 调用统计 |
+| `TOKEN_BUDGET` | Token 预算控制 |
+| `PROMPT_CACHE_BREAK_DETECTION` | Prompt 缓存命中检测 |
+
+---
+
+## 8. /ultraplan 高级规划
+
+**PR**: #156 `feat: enable /ultraplan and harden GrowthBook fallback chain`
+**Feature Flag**: `ULTRAPLAN`
+
+### 说明
+高级多 agent 规划模式。将复杂任务分解为多个阶段，每阶段可分配给不同 agent 并行执行。
+
+### 使用
+```
+/ultraplan 实现一个完整的用户认证系统，包括注册、登录、密码重置、OAuth 集成
+```
+
+AI 会生成：
+1. 任务分解（多阶段）
+2. 每阶段的 agent 分配
+3. 依赖关系图
+4. 并行执行计划
+
+---
+
+## 9. Daemon 后台守护
+
+**PR**: #170 `feat: restore daemon supervisor and remoteControlServer command`
+**Feature Flag**: `DAEMON`
+
+### 说明
+Daemon 模式允许 Claude Code 作为后台长驻进程运行，管理多个 worker。
+
+### 使用
+```bash
+# 启动 daemon
+claude daemon start
+
+# 查看状态
+claude daemon status
+
+# 停止
+claude daemon stop
+
+# 启动远程控制服务器
+bun run rcs
+```
+
+---
+
+## 10. Pipe IPC 多实例协作
+
+**PR**: #241 `feat: restore pipe IPC, LAN pipes, monitor tool`
+**Feature Flag**: `UDS_INBOX`
+
+### 说明
+同一台机器上的多个 Claude Code 实例通过 UDS（Unix Domain Socket / Windows Named Pipe）自动发现并协作。首个启动的实例成为 main，后续自动注册为 sub。
+
+### 使用
+
+**启动多实例**：
+```bash
+# 终端 1
+bun run dev
+# → 自动成为 main
+
+# 终端 2
+bun run dev
+# → 自动成为 sub-1，被 main attach
+```
+
+**管理实例**：
+```
+/pipes                — 显示所有实例，Shift+↓ 展开选择面板
+/pipes select <name>  — 选中实例
+/pipes all            — 全选
+/pipes none           — 取消全选
+/attach <name>        — 手动 attach 某实例
+/detach <name>        — 断开连接
+/send <name> <msg>    — 向指定实例发送消息
+/claim-main           — 强制声明为 main
+/pipe-status          — 显示详细状态
+/peers                — 列出所有已发现的 peer
+```
+
+**选择面板操作**：
+1. 按 `Shift+↓` 展开面板
+2. `↑/↓` 移动光标
+3. `Space` 选中/取消 pipe
+4. `Enter` 确认关闭
+5. `←/→` 切换路由模式（selected pipes ↔ local main）
+
+**消息广播**：
+选中 pipe 后，输入的消息自动路由到所有选中的 slave 执行，结果流式回传到 main。
+
+**权限转发**：
+slave 执行需要权限的工具时（如 BashTool），权限请求自动转发到 main 的确认队列。
+
+---
+
+## 11. LAN Pipes 局域网群控
+
+**PR**: #241（同上）
+**Feature Flag**: `LAN_PIPES`
+
+### 说明
+在 Pipe IPC 基础上增加 TCP 传输层和 UDP Multicast 发现，实现跨机器零配置协作。
+
+### 使用
+
+**局域网多机器**：
+```bash
+# 机器 A (192.168.50.22)
+bun run dev
+
+# 机器 B (192.168.50.27)
+bun run dev
+
+# 两边启动后 3-5 秒自动发现和 attach
+# /pipes 显示 [LAN] 标记的远端实例
+```
+
+**防火墙配置**（每台机器都需要）：
+
+Windows（管理员 PowerShell）：
+```powershell
+New-NetFirewallRule -DisplayName "CCB LAN Beacon (UDP)" -Direction Inbound -Protocol UDP -LocalPort 7101 -Action Allow -Profile Private
+New-NetFirewallRule -DisplayName "CCB LAN Pipes (TCP)" -Direction Inbound -Protocol TCP -LocalPort 1024-65535 -Program (Get-Command bun).Source -Action Allow -Profile Private
+New-NetFirewallRule -DisplayName "CCB LAN Beacon Out (UDP)" -Direction Outbound -Protocol UDP -RemotePort 7101 -Action Allow -Profile Private
+```
+
+macOS：
+```bash
+# 首次运行时系统弹对话框，点"允许"即可
+```
+
+Linux：
+```bash
+sudo firewall-cmd --zone=trusted --add-port=7101/udp --permanent
+sudo firewall-cmd --zone=trusted --add-port=1024-65535/tcp --permanent
+sudo firewall-cmd --reload
+```
+
+**通知显示格式**：
+```
+# 本机 sub
+Routed to [sub-1]; main can continue other tasks
+
+# LAN peer
+Routed to [main] vmwin11/192.168.50.27; main can continue other tasks
+```
+
+---
+
+## 12. Monitor 后台监控
+
+**PR**: #241（同上）
+**Feature Flag**: `MONITOR_TOOL`
+
+### 说明
+在后台运行 shell 命令持续监控输出（类似 `watch` 命令）。AI 也可自主调用 MonitorTool。
+
+### 使用
+
+**用户命令**：
+```
+/monitor tail -f /var/log/syslog
+/monitor watch -n 5 docker ps
+/monitor "while true; do curl -s localhost:3000/health; sleep 10; done"
+```
+
+**查看监控**：
+- 按 `Shift+Down` 展开后台任务面板
+- 查看监控输出和状态
+
+**Windows 兼容**：
+`watch -n <sec> <cmd>` 自动转为 PowerShell 循环：
+```powershell
+while($true){ <cmd>; Start-Sleep -Seconds <sec> }
+```
+
+**AI 调用**：
+AI 可在对话中自动调用 `MonitorTool` 监控日志、构建输出等。
+
+---
+
+## 13. Workflow 工作流脚本
+
+**PR**: #241（同上）
+**Feature Flag**: `WORKFLOW_SCRIPTS`
+
+### 说明
+执行 `.claude/workflows/` 目录下的用户定义工作流脚本。
+
+### 使用
+
+**创建工作流**：
+```bash
+mkdir -p .claude/workflows
+cat > .claude/workflows/deploy.sh << 'EOF'
+#!/bin/bash
+echo "Running tests..."
+bun test
+echo "Building..."
+bun run build
+echo "Deploying..."
+EOF
+chmod +x .claude/workflows/deploy.sh
+```
+
+**列出可用工作流**：
+```
+/workflows
+```
+
+**AI 调用**：
+AI 可通过 `WorkflowTool` 自动执行工作流：
+```
+请执行 deploy 工作流
+```
+
+---
+
+## 14. Coordinator 多Worker协调
+
+**PR**: #241（同上）
+**Feature Flag**: `COORDINATOR_MODE`
+
+### 说明
+启用 coordinator 模式后，AI 可自动将任务分配给多个 worker 并行执行。
+
+### 使用
+```
+/coordinator       — 切换 coordinator 模式开/关
+```
+
+启用后，AI 在处理复杂任务时会：
+1. 分析任务可并行的部分
+2. 自动创建 worker 分支
+3. 分配子任务
+4. 汇总结果
+
+---
+
+## 15. Proactive 自主模式
+
+**PR**: #241（同上）
+**Feature Flag**: `PROACTIVE` / `KAIROS`
+
+### 说明
+启用后 AI 会主动发起操作（而不仅回应用户输入），例如自动检测文件变更、主动提出优化建议。
+
+### 使用
+```
+/proactive         — 切换 proactive 模式开/关
+```
+
+---
+
+## 16. History / Snip 历史管理
+
+**PR**: #241（同上）
+**Feature Flag**: `HISTORY_SNIP`
+
+### 说明
+查看和管理对话历史，支持手动截断以释放上下文窗口空间。
+
+### 使用
+```
+/history           — 显示对话历史摘要
+/force-snip        — 强制在当前位置截断历史
+```
+
+AI 也可通过 `SnipTool` 自动截断过长的对话：
+```
+对话太长了，请帮我截断历史
+```
+
+---
+
+## 17. Fork 子Agent
+
+**PR**: #241（同上）
+**Feature Flag**: `FORK_SUBAGENT`
+
+### 说明
+在当前对话上下文中 fork 一个独立的子 agent，继承完整会话状态独立执行。
+
+### 使用
+```
+/fork              — 基于当前上下文 fork 子 agent
+```
+
+子 agent 会：
+- 继承当前的全部对话历史
+- 在独立的执行环境中运行
+- 不影响主会话状态
+
+---
+
+## 18. 其他恢复的工具
+
+以下工具从 stub 恢复为完整实现：
+
+| 工具 | 说明 | 使用 |
+|------|------|------|
+| `SleepTool` | 暂停执行指定时间 | AI 在轮询场景自动调用 |
+| `WebBrowserTool` | 终端内网页交互 | AI 需要查看网页时调用 |
+| `SubscribePRTool` | 订阅 GitHub PR 变更 | `/subscribe-pr` 或 AI 调用 |
+| `PushNotificationTool` | 推送桌面通知 | AI 在长任务完成时调用 |
+| `CtxInspectTool` | 检查上下文窗口使用 | AI 判断上下文剩余空间 |
+| `TerminalCaptureTool` | 截取终端屏幕 | AI 需要看终端输出时调用 |
+| `SendUserFileTool` | 向用户发送文件 | AI 导出文件时调用 |
+| `REPLTool` | 启动子 REPL 会话 | AI 需要独立交互环境时调用 |
+| `VerifyPlanExecutionTool` | 验证执行计划完成度 | AI 完成计划后自动验证 |
+| `SuggestBackgroundPRTool` | 建议创建后台 PR | AI 发现可独立的变更时提议 |
+| `ListPeersTool` | 列出已发现的 peer | AI 查询多实例状态时调用 |
+
+---
+
+## 附录：全部 Feature Flags
+
+| Flag | 默认 | 说明 |
+|------|------|------|
+| `BUDDY` | ✅ dev only | 伴侣系统 |
+| `BRIDGE_MODE` | ✅ dev only | 远程控制 |
+| `VOICE_MODE` | ✅ dev+build | 语音模式 |
+| `CHICAGO_MCP` | ✅ dev+build | Computer Use + Chrome |
+| `AGENT_TRIGGERS_REMOTE` | ✅ dev+build | 定时任务 |
+| `SHOT_STATS` | ✅ dev+build | API 统计 |
+| `TOKEN_BUDGET` | ✅ dev+build | Token 预算 |
+| `PROMPT_CACHE_BREAK_DETECTION` | ✅ dev+build | 缓存检测 |
+| `ULTRAPLAN` | ✅ dev+build | 高级规划 |
+| `DAEMON` | ✅ dev+build | 后台守护 |
+| `UDS_INBOX` | ✅ dev only | Pipe IPC |
+| `LAN_PIPES` | ✅ dev only | LAN 群控 |
+| `MONITOR_TOOL` | ✅ dev+build | 后台监控 |
+| `WORKFLOW_SCRIPTS` | ✅ dev+build | 工作流脚本 |
+| `FORK_SUBAGENT` | ✅ dev+build | 子 Agent |
+| `KAIROS` | ✅ dev+build | Kairos 调度 |
+| `COORDINATOR_MODE` | ✅ dev+build | 多 Worker |
+| `HISTORY_SNIP` | ✅ dev+build | 历史管理 |
+| `CONTEXT_COLLAPSE` | ✅ dev+build | 上下文折叠 |
+| `ULTRATHINK` | ✅ dev+build | 扩展思考 |
+| `EXTRACT_MEMORIES` | ✅ dev+build | 自动记忆提取 |
+| `VERIFICATION_AGENT` | ✅ dev+build | 验证 Agent |
+| `KAIROS_BRIEF` | ✅ dev+build | Brief 模式 |
+| `AWAY_SUMMARY` | ✅ dev+build | 离开摘要 |
+| `ACP` | ✅ dev+build | ACP 协议 |
+| `LODESTONE` | ✅ dev+build | 深度链接 |
+| `BUILTIN_EXPLORE_PLAN_AGENTS` | ✅ dev+build | 内置 Explore/Plan agent |
+| `AGENT_TRIGGERS` | ✅ dev+build | 本地定时任务 |
+| `BG_SESSIONS` | ✅ dev only | 后台会话 |
+| `TEMPLATES` | ✅ dev only | 模板系统 |
+| `TRANSCRIPT_CLASSIFIER` | ✅ dev only | 对话分类 |
+
+手动启用任意 flag：
+```bash
+FEATURE_FLAG_NAME=1 bun run dev
+```
+
+---
+
+## 附录：PR 列表
+
+| PR | 日期 | 标题 |
+|----|------|------|
+| #60 | 2026-04-02 | feat: enable Remote Control (BRIDGE_MODE) |
+| #82 | 2026-04-03 | refactor(buddy): align companion system |
+| #88 | 2026-04-03 | feat: enable /schedule (AGENT_TRIGGERS_REMOTE) |
+| #89 | 2026-04-03 | feat: built-in status line |
+| #92 | 2026-04-03 | feat: enable /voice mode |
+| #93 | 2026-04-03 | feat: enable Chrome MCP |
+| #98 | 2026-04-03 | feat: enable Computer Use (macOS + Windows + Linux) |
+| #137 | 2026-04-05 | feat: Computer Use v2 — 跨平台 Executor |
+| #140 | 2026-04-05 | feat: enable SHOT_STATS, TOKEN_BUDGET |
+| #153 | 2026-04-06 | feat: enable GrowthBook local gate defaults |
+| #156 | 2026-04-06 | feat: enable /ultraplan |
+| #170 | 2026-04-07 | feat: restore daemon supervisor |
+| #241 | 2026-04-11 | feat: restore pipe IPC, LAN pipes, monitor tool |

docs/features/bash-classifier.md

@@ -102,6 +102,6 @@ FEATURE_BASH_CLASSIFIER=1 FEATURE_TREE_SITTER_BASH=1 bun run dev
 | `src/utils/permissions/bashClassifier.ts` | — | Bash 分类器（stub，ANT-ONLY） |
 | `src/utils/permissions/yoloClassifier.ts` | 1496 | YOLO 分类器（完整参考实现） |
 | `src/utils/classifierApprovals.ts` | — | 分类器审批信号管理 |
-| `src/components/permissions/BashPermissionRequest.tsx:261-469` | — | 分类器 UI |
+| `src/components/permissions/BashPermissionRequest/BashPermissionRequest.tsx` | — | 分类器 UI |
 | `src/hooks/toolPermission/handlers/interactiveHandler.ts` | — | 交互式权限处理 |
-| `src/services/api/withRetry.ts:81` | — | API beta 标头 |
+| `src/services/api/withRetry.ts` | — | API beta 标头 |

docs/features/bridge-mode.md

@@ -30,7 +30,7 @@ BRIDGE_MODE 将本地 CLI 注册为"bridge 环境"，可从 claude.ai 或其他
 
 文件：`src/bridge/bridgeApi.ts`
 
-Bridge API Client 提供 7 个核心操作：
+Bridge API Client 提供 9 个核心操作：
 
 | 操作 | HTTP | 说明 |
 |------|------|------|
@@ -137,7 +137,7 @@ FEATURE_BRIDGE_MODE=1 FEATURE_DAEMON=1 bun run dev
 
 | 文件 | 行数 | 职责 |
 |------|------|------|
-| `src/bridge/bridgeApi.ts` | 540 | API Client（核心） |
+| `src/bridge/bridgeApi.ts` | 541 | API Client（核心） |
 | `src/bridge/sessionRunner.ts` | — | 会话运行器 |
 | `src/bridge/bridgeConfig.ts` | — | 配置管理 |
 | `src/bridge/replBridgeTransport.ts` | — | 传输层 |

docs/features/buddy.mdx

@@ -78,10 +78,13 @@ FEATURE_BUDDY=1 bun run dev
 
 | 文件 | 说明 |
 |---|---|
+| `src/commands/buddy/index.ts` | `/buddy` 命令注册 |
 | `src/commands/buddy/buddy.ts` | `/buddy` 命令处理 |
 | `src/buddy/companion.ts` | 宠物生成与加载 |
+| `src/buddy/companionReact.ts` | 宠物反应系统（REPL 每轮查询后触发） |
 | `src/buddy/types.ts` | 类型定义（物种、稀有度、属性） |
 | `src/buddy/sprites.ts` | 终端像素画渲染 |
 | `src/buddy/CompanionSprite.tsx` | React 组件（输入框旁显示） |
+| `src/buddy/CompanionCard.tsx` | 宠物信息卡片（`/buddy` 无参数时展示） |
 | `src/buddy/useBuddyNotification.tsx` | 启动提示通知 |
 | `src/buddy/prompt.ts` | 宠物相关 prompt 模板 |

docs/features/channels.md

@@ -0,0 +1,89 @@
+# Channels — 外部频道消息接入
+
+> 启动参数：`--channels` / `--dangerously-load-development-channels`
+> 状态：已解除 feature flag 和 OAuth 限制，可直接使用
+
+## 概述
+
+Channel 是一个 MCP 服务器，它将外部事件推送到你运行中的 Claude Code 会话中，以便 Claude 可以在你不在终端时做出反应。详细使用说明请参考以下文档：
+
+- **官方文档**：[使用 channels 将事件推送到运行中的会话](https://code.claude.com/docs/zh-CN/channels)
+- **飞书插件**：[claude-code-feishu-channel](https://github.com/whobot-ai/claude-code-feishu-channel) — 社区首个飞书 Channel 插件，支持双向消息、配对认证、群组聊天、文件附件
+
+本仓库现在内置了 **微信 WeChat channel**，不需要单独安装外部 marketplace 插件。
+
+## 快速开始
+
+```bash
+# 启用频道监听（plugin 格式）
+ccb --channels plugin:feishu@claude-code-feishu-channel
+
+# 启用内置微信 channel
+ccb weixin login
+ccb --channels plugin:weixin@builtin
+
+# 启用频道监听（server 格式）
+ccb --channels server:my-slack-bridge
+
+# 同时启用多个频道
+ccb --channels plugin:feishu@claude-code-feishu-channel --channels server:discord-bot
+
+# 开发模式（跳过 allowlist 检查，用于测试自定义 channel）
+ccb --dangerously-load-development-channels server:my-custom-channel
+```
+
+## 支持的 Channel
+
+| Channel | 说明 | 来源 |
+|---------|------|------|
+| **Telegram** | 官方 Telegram Bot 集成 | `/plugin install telegram@claude-plugins-official` |
+| **Discord** | 官方 Discord Bot 集成 | `/plugin install discord@claude-plugins-official` |
+| **iMessage** | macOS 原生消息 | `/plugin install imessage@claude-plugins-official` |
+| **飞书 (Feishu/Lark)** | 双向消息、群组聊天、文件附件 | `/plugin install feishu@claude-code-feishu-channel` |
+| **微信 (WeChat)** | 内置 channel，支持扫码登录、双向消息、附件透传 | `ccb weixin login` + `ccb --channels plugin:weixin@builtin` |
+
+## 微信内置 Channel
+
+### 登录
+
+```bash
+ccb weixin login
+```
+
+已登录状态可清除：
+
+```bash
+ccb weixin login clear
+```
+
+### 会话启用
+
+```bash
+ccb --channels plugin:weixin@builtin
+```
+
+### 配对授权
+
+首次收到未授权微信用户消息时，weixin channel 会回一条 6 位 pairing code。运营侧可在终端执行：
+
+```bash
+ccb weixin access pair <code>
+```
+
+确认后，该微信用户后续消息才会进入 Claude Code 会话。
+
+## 相关文件
+
+| 文件 | 职责 |
+|------|------|
+| `src/services/mcp/channelNotification.ts` | 频道 gate 逻辑、消息包装 |
+| `src/services/mcp/channelAllowlist.ts` | 频道开关（已默认开启） |
+| `src/services/mcp/useManageMCPConnections.ts` | MCP 连接管理中的频道注册 |
+| `src/components/LogoV2/ChannelsNotice.tsx` | 启动时频道状态提示 |
+| `src/main.tsx` | `--channels` 参数解析 |
+| `src/interactiveHelpers.tsx` | Dev channels 确认对话框 |
+
+## 参考链接
+
+- [官方 Channels 文档](https://code.claude.com/docs/zh-CN/channels) — 完整使用说明、安全性、Enterprise 控制
+- [飞书 Channel 插件](https://github.com/whobot-ai/claude-code-feishu-channel) — 安装配置教程、MCP 工具、Skill 命令参考

docs/features/chrome-use-mcp.md

@@ -0,0 +1,30 @@
+# Chrome Use — 浏览器自动化快速指南
+
+让 Claude Code 直接控制你的 Chrome 浏览器，用自然语言完成网页操作。
+
+## 快速开始（3 分钟）
+
+### 第一步：安装 Chrome 扩展
+
+1. 下载扩展：https://github.com/hangwin/mcp-chrome/releases
+2. 解压 zip 文件
+3. 打开 Chrome 访问 `chrome://extensions/`
+4. 开启右上角「开发者模式」
+5. 点击「加载已解压的扩展程序」，选择解压后的文件夹
+
+### 第二步：启动 Claude Code
+
+```bash
+bun run dev
+ccb # 或者 ccb 安装版也行
+```
+
+### 第三步：启用 Chrome MCP
+
+1. 在 REPL 中输入 `/mcp` 打开 MCP 面板
+2. 找到 `mcp-chrome`，按空格键启用
+3. 按 Enter 确认
+
+## 相关文档
+
+- GitHub 仓库：https://github.com/hangwin/mcp-chrome

docs/features/computer-use-tools-reference.md

@@ -2,12 +2,12 @@
 
 ## 概览
 
-Computer Use 提供 37 个工具，分为三类：
+Computer Use 提供 38 个工具，分为三类：
 
 | 分类 | 平台 | 工具数 | 说明 |
 |------|------|--------|------|
 | 通用工具 | 全平台 | 24 | 官方 Computer Use 标准能力 |
-| Windows 专属工具 | Win32 | 10 | 绑定窗口模式下的增强能力 |
+| Windows 专属工具 | Win32 | 11 | 绑定窗口模式下的增强能力 |
 | 教学工具 | 全平台 | 3 | 分步引导模式（需 teachMode 开启） |
 
 ---
@@ -82,7 +82,7 @@ Computer Use 提供 37 个工具，分为三类：
 
 ---
 
-## 二、Windows 专属工具（10 个）
+## 二、Windows 专属工具（12 个）
 
 仅 Windows 平台可见。核心能力：**绑定窗口后的独立操作——不抢占用户鼠标键盘**。
 
@@ -235,8 +235,19 @@ Computer Use 提供 37 个工具，分为三类：
 
 | 工具 | 参数 | 说明 |
 |------|------|------|
+| `open_terminal` | `agent`, `command?` | 打开新终端窗口并启动 AI agent（claude/codex/gemini/custom）。自动绑定窗口并截图验证 |
+| `activate_window` | `click_x?`, `click_y?` | 激活绑定窗口：SetForegroundWindow + BringWindowToTop + 点击确保焦点 |
 | `prompt_respond` | `response_type`, `arrow_direction?`, `arrow_count?`, `text?` | 处理终端 Yes/No/选择提示 |
 
+**open_terminal agent 类型：**
+
+| agent | 命令 | 说明 |
+|-------|------|------|
+| `claude` | `claude` | 启动 Claude Code |
+| `codex` | `codex` | 启动 Codex |
+| `gemini` | `gemini` | 启动 Gemini |
+| `custom` | 用户指定 | 自定义命令 |
+
 **response_type 详情：**
 
 | response_type | 操作 | 场景 |

docs/features/computer-use.md

@@ -11,7 +11,7 @@
 - ✅ `@ant/computer-use-input` 拆为 dispatcher + backends（darwin + win32）
 - ✅ `@ant/computer-use-swift` 拆为 dispatcher + backends（darwin + win32）
 - ✅ `CHICAGO_MCP` 编译开关已开
-- ❌ `src/` 层有 6 处 macOS 硬编码阻塞
+- ✅ `src/` 层 macOS 硬编码已移除（Phase 2 已完成）
 
 ## 2. 阻塞点全景
 
@@ -19,25 +19,25 @@
 
 | # | 文件:行号 | 阻塞代码 | 影响 |
 |---|----------|---------|------|
-| 1 | `src/main.tsx:1605` | `getPlatform() === 'macos'` | 整个 CU 初始化被跳过 |
+| 1 | `src/main.tsx:2366` | `feature("CHICAGO_MCP")` 门控 | CU 初始化入口 |
 
 ### 2.2 加载层
 
 | # | 文件:行号 | 阻塞代码 | 影响 |
 |---|----------|---------|------|
-| 2 | `src/utils/computerUse/swiftLoader.ts:16` | `process.platform !== 'darwin'` → throw | 截图、应用管理全部不可用 |
-| 3 | `src/utils/computerUse/executor.ts:263` | `process.platform !== 'darwin'` → throw | 整个 executor 工厂函数不可用 |
+| 2 | `src/utils/computerUse/swiftLoader.ts` | macOS-only loader（已改为仅 darwin 加载） | 非 darwin 使用 platforms/ 替代 |
+| 3 | `src/utils/computerUse/executor.ts:302` | `process.platform !== 'darwin'` → cross-platform executor | 非 darwin 走跨平台路径 |
 
 ### 2.3 macOS 特有依赖
 
 | # | 文件:行号 | 依赖 | macOS 实现 | 需要替代方案 |
 |---|----------|------|-----------|------------|
-| 4 | `executor.ts:70-88` | 剪贴板 | `pbcopy`/`pbpaste` | Win: PowerShell `Get/Set-Clipboard`；Linux: `xclip`/`wl-copy` |
-| 5 | `drainRunLoop.ts:21` | CFRunLoop pump | `cu._drainMainRunLoop()` | 非 darwin：直接执行 fn()，不需要 pump |
-| 6 | `escHotkey.ts:28` | ESC 热键 | CGEventTap | 非 darwin：返回 false（已有 Ctrl+C fallback） |
-| 7 | `hostAdapter.ts:48-54` | 系统权限 | TCC accessibility + screenRecording | Win：直接 granted；Linux：检查 xdotool |
-| 8 | `common.ts:56` | 平台标识 | `platform: 'darwin'` 硬编码 | 动态获取 |
-| 9 | `executor.ts:180` | 粘贴快捷键 | `command+v` | Win/Linux：`ctrl+v` |
+| 4 | `executor.ts:72-96` | 剪贴板 | `pbcopy`/`pbpaste` / PowerShell / xclip | Win: PowerShell `Get/Set-Clipboard`；Linux: `xclip`/`wl-copy` |
+| 5 | `drainRunLoop.ts` | CFRunLoop pump | `cu._drainMainRunLoop()` | 非 darwin：直接执行 fn()，不需要 pump |
+| 6 | `escHotkey.ts` | ESC 热键 | CGEventTap | 非 darwin：返回 false（已有 Ctrl+C fallback） |
+| 7 | `hostAdapter.ts` | 系统权限 | TCC accessibility + screenRecording | Win：直接 granted；Linux：检查 xdotool |
+| 8 | `common.ts:55-58` | 平台标识 | 动态获取 | 已改为 `process.platform` 分发 |
+| 9 | `executor.ts:232` | 粘贴快捷键 | `command`/`ctrl` 分发 | 已按平台分发粘贴快捷键 |
 
 ### 2.4 缺失的 Linux 后端
 
@@ -100,19 +100,19 @@
 
 | 步骤 | 文件 | 改动 |
 |------|------|------|
-| 2.1 | `src/main.tsx:1605` | `getPlatform() === 'macos'` → 去掉平台限制，或改为 `!== 'unknown'` |
-| 2.2 | `src/utils/computerUse/swiftLoader.ts:16-18` | 移除 `process.platform !== 'darwin'` throw。`@ant/computer-use-swift/index.ts` 已有跨平台 dispatch |
-| 2.3 | `src/utils/computerUse/executor.ts:263-267` | 移除 `process.platform !== 'darwin'` throw。改为检查 input/swift isSupported |
-| 2.4 | `src/utils/computerUse/executor.ts:70-88` | 剪贴板函数按平台分发：darwin→pbcopy/pbpaste，win32→PowerShell Get/Set-Clipboard，linux→xclip |
-| 2.5 | `src/utils/computerUse/executor.ts:180` | `typeViaClipboard` 中 `command+v` → 非 darwin 时用 `ctrl+v` |
-| 2.6 | `src/utils/computerUse/executor.ts:273` | `const cu = requireComputerUseSwift()` → 改为 `new ComputerUseAPI()`（从 package 直接实例化，不走 swiftLoader throw） |
-| 2.7 | `src/utils/computerUse/drainRunLoop.ts` | 开头加 `if (process.platform !== 'darwin') return fn()` |
-| 2.8 | `src/utils/computerUse/escHotkey.ts` | `registerEscHotkey` 非 darwin 返回 false（已有 Ctrl+C fallback） |
-| 2.9 | `src/utils/computerUse/hostAdapter.ts:48-54` | `ensureOsPermissions` 非 darwin 返回 `{ granted: true }` |
-| 2.10 | `src/utils/computerUse/common.ts:56` | `platform: 'darwin'` → `platform: process.platform === 'win32' ? 'windows' : process.platform === 'linux' ? 'linux' : 'darwin'` |
-| 2.11 | `src/utils/computerUse/common.ts:55` | `screenshotFiltering: 'native'` → 非 darwin 时 `'none'`（Windows/Linux 截图不支持 per-app 过滤） |
-| 2.12 | `src/utils/computerUse/gates.ts:13` | `enabled: false` → `enabled: true`（无 GrowthBook 时默认可用） |
-| 2.13 | `src/utils/computerUse/gates.ts:39-43` | `hasRequiredSubscription()` → 直接返回 `true` |
+| 2.1 | `src/main.tsx:2366` | `feature("CHICAGO_MCP")` → 已为跨平台入口 |
+| 2.2 | `src/utils/computerUse/swiftLoader.ts` | 已改为仅 darwin 加载，非 darwin 使用 platforms/ |
+| 2.3 | `src/utils/computerUse/executor.ts:302-309` | 已改为 cross-platform dispatch（非 darwin → createCrossPlatformExecutor） |
+| 2.4 | `src/utils/computerUse/executor.ts:72-96` | 剪贴板已按平台分发：darwin→pbcopy/pbpaste，win32→PowerShell，linux→xclip |
+| 2.5 | `src/utils/computerUse/executor.ts:232` | 粘贴快捷键已按平台分发：darwin→command，其他→ctrl |
+| 2.6 | `src/utils/computerUse/executor.ts:302-309` | 非 darwin 已改为 `createCrossPlatformExecutor()` |
+| 2.7 | `src/utils/computerUse/drainRunLoop.ts` | 非 darwin 无需 pump（直接执行 fn） |
+| 2.8 | `src/utils/computerUse/escHotkey.ts` | 非 darwin 返回 false（已有 Ctrl+C fallback） |
+| 2.9 | `src/utils/computerUse/hostAdapter.ts` | 非 darwin 权限检查逻辑已实现 |
+| 2.10 | `src/utils/computerUse/common.ts:58` | 已改为动态 `process.platform` 分发 |
+| 2.11 | `src/utils/computerUse/common.ts:55` | 已改为 darwin→'native'，其他→'none' |
+| 2.12 | `src/utils/computerUse/gates.ts:55` | 已更新（需验证 enabled 默认值） |
+| 2.13 | `src/utils/computerUse/gates.ts:39` | `hasRequiredSubscription()` 已更新 |
 
 ### Phase 3：新增 Linux 后端
 

docs/features/context-collapse.md

@@ -1,140 +0,0 @@
-# CONTEXT_COLLAPSE — 上下文折叠
-
-> Feature Flag: `FEATURE_CONTEXT_COLLAPSE=1`
-> 子 Feature: `FEATURE_HISTORY_SNIP=1`
-> 实现状态：核心逻辑全部 Stub，布线完整
-> 引用数：CONTEXT_COLLAPSE 20 + HISTORY_SNIP 16 = 36
-
-## 一、功能概述
-
-CONTEXT_COLLAPSE 让模型内省上下文窗口使用情况，并智能压缩旧消息。当对话接近上下文限制时，自动将旧消息折叠为压缩摘要，保留关键信息的同时释放 token 空间。
-
-### 子 Feature
-
-| Feature | 功能 |
-|---------|------|
-| `CONTEXT_COLLAPSE` | 上下文折叠引擎（后台 LLM 调用压缩旧消息） |
-| `HISTORY_SNIP` | SnipTool — 标记消息进行折叠/修剪 |
-
-## 二、实现架构
-
-### 2.1 模块状态
-
-| 模块 | 文件 | 状态 |
-|------|------|------|
-| 折叠核心 | `src/services/contextCollapse/index.ts` | **Stub** — 接口完整（`ContextCollapseStats`、`CollapseResult`、`DrainResult`），函数全部空操作 |
-| 折叠操作 | `src/services/contextCollapse/operations.ts` | **Stub** — `projectView` 为恒等函数 |
-| 折叠持久化 | `src/services/contextCollapse/persist.ts` | **Stub** — `restoreFromEntries` 为空操作 |
-| CtxInspectTool | `src/tools/CtxInspectTool/` | **缺失** — 目录不存在 |
-| SnipTool 提示 | `src/tools/SnipTool/prompt.ts` | **Stub** — 空工具名 |
-| SnipTool 实现 | `src/tools/SnipTool/SnipTool.ts` | **缺失** |
-| force-snip 命令 | `src/commands/force-snip.js` | **缺失** |
-| 折叠读取搜索 | `src/utils/collapseReadSearch.ts` | **完整** — Snip 作为静默吸收操作 |
-| QueryEngine 集成 | `src/QueryEngine.ts` | **布线** — 导入并使用 snip 投影 |
-| Token 警告 UI | `src/components/TokenWarning.tsx` | **布线** — 折叠进度标签 |
-
-### 2.2 核心接口（已定义，待实现）
-
-```ts
-// contextCollapse/index.ts
-interface ContextCollapseStats {
-  // 上下文使用统计
-}
-interface CollapseResult {
-  // 折叠操作结果
-}
-interface DrainResult {
-  // 紧急释放结果
-}
-
-// 关键函数（全部 stub）：
-isContextCollapseEnabled()          // → false
-applyCollapsesIfNeeded(messages)    // 透传
-recoverFromOverflow(messages)       // 透传（413 恢复）
-initContextCollapse()               // 空操作
-```
-
-### 2.3 预期数据流
-
-```
-对话持续增长
-      │
-      ▼
-上下文接近限制（由 query.ts 检测）
-      │
-      ├── 溢出检测 (query.ts:440,616,802)
-      │
-      ▼
-applyCollapsesIfNeeded(messages) [需要实现]
-      │
-      ├── 后台 LLM 调用压缩旧消息
-      ├── 保留关键信息（决策、文件路径、错误）
-      └── 替换旧消息为压缩摘要
-      │
-      ├── 413 恢复 (query.ts:1093,1179)
-      │   └── recoverFromOverflow() 紧急折叠
-      │
-      ▼
-projectView() 过滤折叠后的消息视图
-      │
-      ▼
-模型继续工作（在压缩后的上下文中）
-```
-
-### 2.4 HISTORY_SNIP 子功能
-
-SnipTool 提供手动折叠能力：
-
-- `/force-snip` 命令 — 强制执行折叠
-- SnipTool — 标记特定消息进行折叠/修剪
-- `collapseReadSearch.ts` 已完整实现，将 Snip 作为静默吸收操作处理
-
-### 2.5 集成点
-
-| 文件 | 位置 | 说明 |
-|------|------|------|
-| `src/query.ts` | 18,440,616,802,1093,1179 | 溢出检测、413 恢复、折叠应用 |
-| `src/QueryEngine.ts` | 124,127,1301 | Snip 投影使用 |
-| `src/utils/analyzeContext.ts` | 1122 | 跳过保留缓冲区显示 |
-| `src/utils/sessionRestore.ts` | 127,494 | 恢复折叠状态 |
-| `src/services/compact/autoCompact.ts` | 179,215 | 自动压缩时考虑折叠 |
-
-## 三、需要补全的内容
-
-| 优先级 | 模块 | 工作量 | 说明 |
-|--------|------|--------|------|
-| 1 | `services/contextCollapse/index.ts` | 大 | 折叠状态机、LLM 调用、消息压缩 |
-| 2 | `services/contextCollapse/operations.ts` | 中 | `projectView()` 消息过滤 |
-| 3 | `services/contextCollapse/persist.ts` | 小 | `restoreFromEntries()` 磁盘持久化 |
-| 4 | `tools/CtxInspectTool/` | 中 | 上下文内省工具（token 计数、已折叠范围） |
-| 5 | `tools/SnipTool/SnipTool.ts` | 中 | Snip 工具实现 |
-| 6 | `commands/force-snip.js` | 小 | `/force-snip` 命令 |
-
-## 四、关键设计决策
-
-1. **后台 LLM 压缩**：折叠不是简单截断，而是用 LLM 生成压缩摘要保留关键信息
-2. **413 恢复**：当 API 返回 413（请求过大）时，紧急折叠是最重要的恢复手段
-3. **与 autoCompact 协作**：折叠和自动压缩（compact）是不同的机制，折叠在消息级别，压缩在对话级别
-4. **持久化**：折叠状态持久化到磁盘，会话恢复时重载
-
-## 五、使用方式
-
-```bash
-# 启用 context collapse
-FEATURE_CONTEXT_COLLAPSE=1 bun run dev
-
-# 启用 snip 子功能
-FEATURE_CONTEXT_COLLAPSE=1 FEATURE_HISTORY_SNIP=1 bun run dev
-```
-
-## 六、文件索引
-
-| 文件 | 职责 |
-|------|------|
-| `src/services/contextCollapse/index.ts` | 折叠核心（stub，接口已定义） |
-| `src/services/contextCollapse/operations.ts` | 投影操作（stub） |
-| `src/services/contextCollapse/persist.ts` | 持久化（stub） |
-| `src/utils/collapseReadSearch.ts` | Snip 吸收操作（完整） |
-| `src/query.ts` | 溢出检测和 413 恢复集成 |
-| `src/QueryEngine.ts` | Snip 投影使用 |
-| `src/components/TokenWarning.tsx` | 折叠进度 UI |

docs/features/daemon-restructure-design.md

@@ -0,0 +1,318 @@
+# Daemon 重构设计方案
+
+> 分支: `feat/integrate-5-branches`
+> 基于: `f41745cb` (= main `11bb3f62` 内容)
+> 日期: 2026-04-13
+
+## 一、问题概述
+
+### 1.1 命令结构散乱
+
+当前后台进程相关的命令分布在三个不同的位置，没有统一的命名空间：
+
+| 命令 | 注册位置 | 入口 |
+|------|---------|------|
+| `claude daemon start/status/stop` | `cli.tsx` 快速路径 L203 | `daemon/main.ts` |
+| `claude ps` | `cli.tsx` 快速路径 L220 | `cli/bg.ts` |
+| `claude logs <x>` | `cli.tsx` 快速路径 L232 | `cli/bg.ts` |
+| `claude attach <x>` | `cli.tsx` 快速路径 L236 | `cli/bg.ts` |
+| `claude kill <x>` | `cli.tsx` 快速路径 L238 | `cli/bg.ts` |
+| `claude --bg` | `cli.tsx` 快速路径 L244 | `cli/bg.ts` |
+| `claude new/list/reply` | `cli.tsx` 快速路径 L250 | `cli/handlers/templateJobs.ts` |
+| `claude rollback` | `main.tsx` Commander.js L6525 | `cli/rollback.ts` |
+| `claude up` | `main.tsx` Commander.js L6511 | `cli/up.ts` |
+
+**问题**:
+- `ps/logs/attach/kill` 与 `daemon` 逻辑上都是后台进程管理，但互不关联
+- 这些命令都**只有 CLI 入口**，REPL 里输入 `/daemon` 或 `/ps` 不存在
+- `new/list/reply` 是模板任务系统的顶级命令，容易与其他命令冲突（特别是 `list`）
+
+### 1.2 Windows 不支持
+
+`--bg` 和 `attach` 硬依赖 tmux：
+- `bg.ts:handleBgFlag()` 第一步就检查 tmux，不可用直接报错退出
+- `bg.ts:attachHandler()` 用 `tmux attach-session`，无 tmux 替代方案
+- Windows (包括 VS Code 终端) 完全无法使用后台会话功能
+
+### 1.3 无 REPL 入口
+
+对比 `/mcp` 的双注册模式：
+- **CLI**: `claude mcp serve/add/remove/list` (Commander.js, `main.tsx:5760`)
+- **REPL**: `/mcp enable/disable/reconnect` (slash command, `commands/mcp/index.ts`)
+
+`daemon`/`bg`/`job` 系列只有 CLI 快速路径，REPL 中完全不可用。
+
+## 二、目标
+
+1. **层级化命令结构**: 参照 `/mcp` 模式，将后台管理收归 `/daemon`，模板任务收归 `/job`
+2. **跨平台后台会话**: Windows / macOS / Linux 都能启动、附着、终止后台会话
+3. **双注册**: CLI (`claude daemon ...`) + REPL (`/daemon ...`) 同时可用
+4. **向后兼容**: 旧命令保留但输出 deprecation 提示
+
+## 三、命令结构设计
+
+### 3.1 `/daemon` — 后台进程管理
+
+合并 daemon supervisor + bg sessions 为统一命名空间：
+
+```
+claude daemon <subcommand>     ← CLI 入口 (cli.tsx 快速路径)
+/daemon <subcommand>           ← REPL 入口 (slash command, local-jsx)
+
+子命令:
+  status                       综合状态面板 (daemon + 所有会话)
+  start [--dir <path>]         启动 daemon supervisor
+  stop                         停止 daemon
+  bg [args...]                 启动后台会话
+  attach [target]              附着到后台会话
+  logs [target]                查看会话日志
+  kill [target]                终止会话
+  (无参数)                     等同于 status
+```
+
+**CLI 快速路径路由** (`cli.tsx`):
+```typescript
+// 新: 统一入口
+if (feature('DAEMON') && args[0] === 'daemon') {
+  const sub = args[1] || 'status'
+  switch (sub) {
+    case 'start': case 'stop': case 'status':
+      await daemonMain([sub, ...args.slice(2)])
+      break
+    case 'bg':
+      await bg.handleBgStart(args.slice(2))
+      break
+    case 'attach': case 'logs': case 'kill':
+      await bg[`${sub}Handler`](args[2])
+      break
+  }
+}
+
+// 向后兼容 (deprecated)
+if (feature('BG_SESSIONS') && ['ps','logs','attach','kill'].includes(args[0])) {
+  console.warn(`[deprecated] Use: claude daemon ${args[0] === 'ps' ? 'status' : args[0]}`)
+  // ... delegate to daemon subcommand
+}
+```
+
+**REPL 斜杠命令** (`commands/daemon/index.ts`):
+```typescript
+const daemon = {
+  type: 'local-jsx',
+  name: 'daemon',
+  description: 'Manage background sessions and daemon',
+  argumentHint: '[status|start|stop|bg|attach|logs|kill]',
+  isEnabled: () => feature('DAEMON') || feature('BG_SESSIONS'),
+  load: () => import('./daemon.js'),
+} satisfies Command
+```
+
+### 3.2 `/job` — 模板任务管理
+
+```
+claude job <subcommand>        ← CLI 入口
+/job <subcommand>              ← REPL 入口
+
+子命令:
+  list                         列出模板和活跃任务
+  new <template> [args]        从模板创建任务
+  reply <id> <text>            回复任务
+  status <id>                  查看任务状态
+  (无参数)                     等同于 list
+```
+
+### 3.3 独立命令 (不变)
+
+```
+claude up                      保持顶级 (简短的 bootstrap 命令)
+claude rollback [target]       保持顶级 (低频运维命令)
+```
+
+## 四、跨平台后台引擎
+
+### 4.1 引擎抽象
+
+```typescript
+// src/cli/bg/engine.ts
+export interface BgEngine {
+  readonly name: string
+
+  /** 当前平台是否可用 */
+  available(): Promise<boolean>
+
+  /** 启动后台会话 */
+  start(opts: BgStartOptions): Promise<BgStartResult>
+
+  /** 附着到后台会话（blocking） */
+  attach(session: SessionEntry): Promise<void>
+}
+
+export interface BgStartOptions {
+  sessionName: string
+  args: string[]
+  env: Record<string, string | undefined>
+  logPath: string
+  cwd: string
+}
+
+export interface BgStartResult {
+  pid: number
+  sessionName: string
+  logPath: string
+  engineUsed: string
+}
+```
+
+### 4.2 三种引擎实现
+
+| 引擎 | 平台 | 启动方式 | attach 方式 |
+|------|------|---------|------------|
+| TmuxEngine | macOS/Linux (有 tmux) | `tmux new-session -d` | `tmux attach-session` |
+| DetachedEngine | Windows / 无 tmux 的 macOS/Linux | `spawn({ detached, stdio→logFile })` | `tail -f` 日志文件 |
+
+#### DetachedEngine 详细设计
+
+**启动 (`start`)**:
+```typescript
+// 1. 打开日志文件 fd
+const logFd = fs.openSync(logPath, 'a')
+// 2. detached spawn, stdout/stderr 重定向到日志
+const child = spawn(process.execPath, execArgs, {
+  detached: true,
+  stdio: ['ignore', logFd, logFd],
+  env,
+  cwd,
+})
+child.unref()
+fs.closeSync(logFd)
+// 3. 写 sessions/<PID>.json
+```
+
+**附着 (`attach`)**:
+```typescript
+// 跨平台 tail -f 实现
+// 1. 读取已有日志内容输出到 stdout
+// 2. fs.watch(logPath) 监听变化
+// 3. 每次变化读取新增内容
+// 4. Ctrl+C 退出 tail（不杀后台进程）
+```
+
+#### 引擎选择逻辑
+
+```typescript
+// src/cli/bg/engines/index.ts
+export async function selectEngine(): Promise<BgEngine> {
+  if (process.platform === 'win32') {
+    return new DetachedEngine()
+  }
+
+  const tmux = new TmuxEngine()
+  if (await tmux.available()) {
+    return tmux
+  }
+
+  return new DetachedEngine()
+}
+```
+
+### 4.3 SessionEntry 扩展
+
+```typescript
+interface SessionEntry {
+  // ... 现有字段
+  engine: 'tmux' | 'detached'   // 新增: 记录使用的引擎
+  tmuxSessionName?: string       // tmux 引擎才有
+  logPath?: string               // 两种引擎都有
+}
+```
+
+`attach` 时根据 `session.engine` 选择对应的 attach 策略。
+
+## 五、文件变更清单
+
+### 新增文件 (10 个)
+
+```
+src/cli/bg/engine.ts                   BgEngine 接口定义
+src/cli/bg/engines/tmux.ts             TmuxEngine (从 bg.ts 提取)
+src/cli/bg/engines/detached.ts         DetachedEngine (新实现)
+src/cli/bg/engines/index.ts            引擎选择 + re-export
+src/cli/bg/tail.ts                     跨平台日志 tail (用于 detached attach)
+src/commands/daemon/index.ts           /daemon REPL 斜杠命令注册
+src/commands/daemon/daemon.tsx         /daemon 子命令路由 + status UI
+src/commands/job/index.ts              /job REPL 斜杠命令注册
+src/commands/job/job.tsx               /job 子命令路由 + UI
+docs/features/daemon-restructure-design.md  本设计文档
+```
+
+### 修改文件 (6 个)
+
+```
+src/cli/bg.ts                          重构: handler 函数改为调用 BgEngine
+src/entrypoints/cli.tsx                快速路径: daemon 统一入口 + 向后兼容
+src/commands.ts                        注册 /daemon 和 /job 斜杠命令
+src/daemon/main.ts                     daemonMain() 增加 bg/ps/logs 子命令分发
+src/main.tsx                           Commander.js: 可选注册 daemon/job 子命令
+src/cli/handlers/templateJobs.ts       适配 /job 入口 (可能不需改)
+```
+
+### 不动的文件
+
+```
+src/daemon/state.ts                    daemon PID 状态管理 (无需改)
+src/jobs/state.ts                      job 状态管理 (无需改)
+src/jobs/templates.ts                  模板发现 (无需改)
+src/jobs/classifier.ts                 任务分类器 (无需改)
+src/cli/rollback.ts                    保持顶级命令 (无需改)
+src/cli/up.ts                          保持顶级命令 (无需改)
+```
+
+## 六、可行性分析
+
+### 6.1 风险评估
+
+| 风险 | 级别 | 缓解措施 |
+|------|------|---------|
+| cli.tsx 快速路径修改影响启动性能 | 低 | 仅改路由逻辑，import 仍然 lazy |
+| DetachedEngine 的 attach 在 Windows 上 fs.watch 不可靠 | 中 | 使用轮询 fallback (setInterval + fs.stat) |
+| 向后兼容的 deprecation 可能破坏脚本 | 低 | 旧命令保持可用，仅输出 stderr 警告 |
+| REPL 中 /daemon bg 需要 spawn 子进程 | 中 | 参考 /assistant 的 NewInstallWizard (已有 spawn 先例) |
+| tsc 类型兼容 | 低 | 接口定义清晰，不引入 any |
+
+### 6.2 工作量估计
+
+| Task | 文件数 | 复杂度 |
+|------|--------|--------|
+| Task 013: BgEngine 抽象 + 引擎实现 | 5 新增 + 1 修改 | 中 |
+| Task 014: /daemon 命令层级化 | 3 新增 + 3 修改 | 中 |
+| Task 015: /job 命令层级化 | 2 新增 + 2 修改 | 低 |
+| Task 016: 向后兼容 + 测试 | 0 新增 + 2 修改 | 低 |
+
+### 6.3 依赖关系
+
+```
+Task 013 (BgEngine) ← 无依赖，可独立开发
+Task 014 (/daemon)  ← 依赖 Task 013 (引擎选择)
+Task 015 (/job)     ← 无依赖，可与 013 并行
+Task 016 (兼容)     ← 依赖 Task 014 + 015
+```
+
+## 七、设计决策记录
+
+### D1: 为什么 daemon + bg sessions 合为一个命名空间？
+
+用户视角：都是"后台运行的东西"。分开会导致 `claude daemon status` 看 supervisor + `claude ps` 看会话，割裂感强。合并后 `claude daemon status` 一次性展示 supervisor 状态 + 所有会话列表。
+
+### D2: 为什么 rollback/up 不收入 daemon？
+
+它们本质是**版本管理/环境初始化**，不是后台进程管理。`claude up` 是同步阻塞的 setup 脚本，不涉及 daemon 或后台会话。保持顶级更直观。
+
+### D3: 为什么 DetachedEngine 的 attach 用 tail 而不是 IPC？
+
+1. 日志文件是最简单的跨平台方案，无需额外依赖
+2. UDS Pipe IPC 系统 (usePipeIpc) 设计用于实例间通信，不是终端附着
+3. tmux attach 的体验（完整 PTY）无法在纯 detached 模式下复制，tail 是最诚实的替代
+
+### D4: 为什么不用 Windows Terminal 的 tab/pane API？
+
+Windows Terminal 的 `wt.exe` 新窗口/标签功能不够通用——用户可能在 VS Code、ConEmu、cmder 等终端中。detached + log 是唯一跨终端方案。

docs/features/daemon.md

@@ -1,12 +1,12 @@
 # DAEMON — 后台守护进程
 
 > Feature Flag: `FEATURE_DAEMON=1`
-> 实现状态：主进程和 worker 注册为 Stub，CLI 路由完整
+> 实现状态：Supervisor 和 remoteControl Worker 已实现
 > 引用数：3
 
 ## 一、功能概述
 
-DAEMON 将 Claude Code 变为后台守护进程。主进程（supervisor）管理多个 worker 进程的生命周期，通过 Unix 域套接字进行 IPC。适用于持续运行的后台服务场景（如配合 BRIDGE_MODE 提供远程控制服务）。
+DAEMON 将 Claude Code 变为后台守护进程。主进程（supervisor）管理多个 worker 子进程的生命周期，通过文件系统状态文件进行通信。适用于持续运行的后台服务场景（如配合 BRIDGE_MODE 提供远程控制服务）。
 
 ## 二、实现架构
 
@@ -14,8 +14,9 @@ DAEMON 将 Claude Code 变为后台守护进程。主进程（supervisor）管
 
 | 模块 | 文件 | 状态 |
 |------|------|------|
-| 守护主进程 | `src/daemon/main.ts` | **Stub** — `daemonMain: () => Promise.resolve()` |
-| Worker 注册 | `src/daemon/workerRegistry.ts` | **Stub** — `runDaemonWorker: () => Promise.resolve()` |
+| 守护主进程 | `src/daemon/main.ts` | **已实现** — Supervisor 含子命令、Worker 生命周期管理、指数退避重启 |
+| Worker 注册 | `src/daemon/workerRegistry.ts` | **已实现** — remoteControl Worker（headless bridge） |
+| Daemon 状态 | `src/daemon/state.ts` | **已实现** — PID/状态文件的读写与查询 |
 | CLI 路由 | `src/entrypoints/cli.tsx` | **布线** — `--daemon-worker` 和 `daemon` 子命令 |
 | 命令注册 | `src/commands.ts` | **布线** — DAEMON + BRIDGE_MODE 门控 |
 
@@ -23,34 +24,49 @@ DAEMON 将 Claude Code 变为后台守护进程。主进程（supervisor）管
 
 ```
 # 启动守护进程
-claude daemon
+claude daemon start
 
-# 以 worker 身份启动
-claude --daemon-worker=<kind>
+# 查看状态（默认子命令）
+claude daemon status
+claude daemon ps
+
+# 停止守护进程
+claude daemon stop
+
+# 以 worker 身份启动（由 supervisor 自动调用）
+claude --daemon-worker=remoteControl
+
+# 后台会话管理
+claude daemon bg
+claude daemon attach <session>
+claude daemon logs <session>
+claude daemon kill <session>
 ```
 
-### 2.3 预期架构
+### 2.3 架构
 
 ```
 Supervisor (daemonMain)
       │
-      ├── Worker 1: assistant-mode
-      │   └── 接收和处理 assistant 会话
-      │
-      ├── Worker 2: bridge-sync
-      │   └── bridge 消息同步
-      │
-      └── Worker 3: proactive
-          └── 主动任务执行
+      ├── Worker: remoteControl
+      │   └── runBridgeHeadless() — 远程控制 headless 模式
+      │       接收远程会话、处理消息、权限审批
       │
       ▼
-IPC via Unix Domain Sockets
-  - 生命周期管理（启动、停止、重启）
-  - 工作分发
-  - 状态报告
+文件系统状态文件 (daemon-state.json)
+  - PID、CWD、启动时间、Worker 类型
+  - queryDaemonStatus() / stopDaemonByPid()
 ```
 
-### 2.4 与 BRIDGE_MODE 的关系
+### 2.4 Worker 生命周期管理
+
+Supervisor 为每个 worker 实现：
+- **指数退避重启**：初始 2s，上限 120s，倍数 ×2
+- **快速失败检测**：10s 内连续崩溃 5 次则 parking（不再重启）
+- **永久错误退出码**：78 (EXIT_CODE_PERMANENT) 导致直接 parking
+- **优雅关闭**：SIGTERM/SIGINT → abort signal → 30s 强制 SIGKILL
+
+### 2.5 与 BRIDGE_MODE 的关系
 
 DAEMON 和 BRIDGE_MODE 常组合使用：
 
@@ -63,40 +79,39 @@ if (feature('DAEMON') && feature('BRIDGE_MODE')) {
 
 双重门控：两个 feature 都需要开启才能使用远程控制服务器。
 
-## 三、需要补全的内容
-
-| 模块 | 工作量 | 说明 |
-|------|--------|------|
-| `daemon/main.ts` | 大 | Supervisor 主进程：启动 worker、生命周期管理、IPC |
-| `daemon/workerRegistry.ts` | 中 | Worker 类型分发（assistant/bridge-sync/proactive） |
-| Worker 实现 | 大 | 各类型 worker 的具体实现 |
-| IPC 协议 | 中 | Supervisor-Worker 通信层 |
-
-## 四、关键设计决策
+## 三、关键设计决策
 
 1. **多进程架构**：一个 supervisor + 多个 worker，进程隔离
-2. **Unix 域套接字 IPC**：本地进程间通信，低延迟
+2. **文件系统状态通信**：通过 `daemon-state.json` 文件进行状态共享（非 Unix 域套接字）
 3. **与 BRIDGE_MODE 强绑定**：守护进程最常见的用途是提供远程控制服务
 4. **CLI 子命令路由**：`daemon` 子命令和 `--daemon-worker` 参数在 `cli.tsx` 中路由
+5. **Worker 环境变量**：supervisor 通过环境变量（`DAEMON_WORKER_*`）向 worker 传递配置
 
-## 五、使用方式
+## 四、使用方式
 
 ```bash
 # 启用守护进程模式
 FEATURE_DAEMON=1 FEATURE_BRIDGE_MODE=1 bun run dev
 
 # 启动守护进程
-claude daemon
+claude daemon start
 
-# 以特定 worker 启动
-claude --daemon-worker=assistant
+# 查看状态
+claude daemon status
+
+# 停止守护进程
+claude daemon stop
+
+# 以特定 worker 启动（通常由 supervisor 自动调用）
+claude --daemon-worker=remoteControl
 ```
 
-## 六、文件索引
+## 五、文件索引
 
 | 文件 | 职责 |
 |------|------|
-| `src/daemon/main.ts` | Supervisor 主进程（stub） |
-| `src/daemon/workerRegistry.ts` | Worker 注册（stub） |
-| `src/entrypoints/cli.tsx:95,149` | CLI 路由 |
-| `src/commands.ts:77` | 命令注册（双重门控） |
+| `src/daemon/main.ts` | Supervisor 主进程：子命令分发、Worker 生命周期管理、退避重启 |
+| `src/daemon/workerRegistry.ts` | Worker 入口：remoteControl worker 实现 |
+| `src/daemon/state.ts` | Daemon 状态管理：PID 文件读写、状态查询 |
+| `src/entrypoints/cli.tsx` | CLI 路由 |
+| `src/commands.ts` | 命令注册（双重门控） |

docs/features/debug-mode.mdx

@@ -27,13 +27,15 @@ bun run dev:inspect
 
 ## 原理
 
-`dev:inspect` 脚本实际执行的是：
+`dev:inspect` 脚本实际执行的是 `scripts/dev-debug.ts`：
 
-```bash
-bun --inspect-wait=localhost:8888/<token> run scripts/dev.ts
+```typescript
+// scripts/dev-debug.ts
+process.env.BUN_INSPECT = "localhost:8888/<token>"
+await import("./dev")
 ```
 
-Bun 的 `--inspect-wait` 参数启动一个 Chrome DevTools Protocol 兼容的 inspect 服务，等待调试器连接后才开始执行。VS Code 的 `bun` 扩展通过 WebSocket 连接到这个地址实现 attach。
+通过设置 `BUN_INSPECT` 环境变量启动一个 Chrome DevTools Protocol 兼容的 inspect 服务，然后导入 dev 模式入口。VS Code 的 `bun` 扩展通过 WebSocket 连接到输出的地址实现 attach。
 
 ## JetBrains IDE
 

docs/features/feature-flags-audit-complete.md

@@ -34,7 +34,7 @@ Claude Code 使用三层门控系统:
 |------|------|----------|
 | COMPLETE | 22 | BRIDGE_MODE, COORDINATOR_MODE, CONTEXT_COLLAPSE, VOICE_MODE, TEAMMEM, COMMIT_ATTRIBUTION, ULTRAPLAN, BASH_CLASSIFIER, TRANSCRIPT_CLASSIFIER, EXTRACT_MEMORIES, CACHED_MICROCOMPACT, TOKEN_BUDGET, AGENT_TRIGGERS, REACTIVE_COMPACT, KAIROS_BRIEF, CCR_REMOTE_SETUP, SHOT_STATS, BG_SESSIONS, PROACTIVE, CHICAGO_MCP, VERIFICATION_AGENT, PROMPT_CACHE_BREAK_DETECTION |
 | PARTIAL | 19 | KAIROS, BUDDY, MONITOR_TOOL, HISTORY_SNIP, WORKFLOW_SCRIPTS, UDS_INBOX, KAIROS_CHANNELS, FORK_SUBAGENT, EXPERIMENTAL_SKILL_SEARCH, WEB_BROWSER_TOOL, MCP_SKILLS, REVIEW_ARTIFACT, KAIROS_GITHUB_WEBHOOKS, CONNECTOR_TEXT, TEMPLATES, LODESTONE, HISTORY_PICKER, MESSAGE_ACTIONS, TERMINAL_PANEL |
-| STUB | 51 | TORCH, KAIROS_DREAM, KAIROS_PUSH_NOTIFICATION, DAEMON, DIRECT_CONNECT, SSH_REMOTE, STREAMLINED_OUTPUT, ANTI_DISTILLATION_CC, NATIVE_CLIENT_ATTESTATION, ABLATION_BASELINE, AGENT_MEMORY_SNAPSHOT, AGENT_TRIGGERS_REMOTE, ALLOW_TEST_VERSIONS, AUTO_THEME, AWAY_SUMMARY, BREAK_CACHE_COMMAND, BUILDING_CLAUDE_APPS, BUILTIN_EXPLORE_PLAN_AGENTS, BYOC_ENVIRONMENT_RUNNER, CCR_AUTO_CONNECT, CCR_MIRROR, COMPACTION_REMINDERS, COWORKER_TYPE_TELEMETRY, DOWNLOAD_USER_SETTINGS, DUMP_SYSTEM_PROMPT, ENHANCED_TELEMETRY_BETA, FILE_PERSISTENCE, HARD_FAIL, HOOK_PROMPTS, IS_LIBC_GLIBC, IS_LIBC_MUSL, MCP_RICH_OUTPUT, MEMORY_SHAPE_TELEMETRY, NATIVE_CLIPBOARD_IMAGE, NEW_INIT, OVERFLOW_TEST_TOOL, PERFETTO_TRACING, POWERSHELL_AUTO_MODE, QUICK_SEARCH, RUN_SKILL_GENERATOR, SELF_HOSTED_RUNNER, SKILL_IMPROVEMENT, SLOW_OPERATION_LOGGING, TREE_SITTER_BASH, TREE_SITTER_BASH_SHADOW, ULTRATHINK, UNATTENDED_RETRY, UPLOAD_USER_SETTINGS, SKIP_DETECTION_WHEN_AUTOUPDATES_DISABLED |
+| STUB | 38 | TORCH, KAIROS_DREAM, KAIROS_PUSH_NOTIFICATION, DIRECT_CONNECT, SSH_REMOTE, STREAMLINED_OUTPUT, ANTI_DISTILLATION_CC, NATIVE_CLIENT_ATTESTATION, ABLATION_BASELINE, AGENT_MEMORY_SNAPSHOT, ALLOW_TEST_VERSIONS, AUTO_THEME, BREAK_CACHE_COMMAND, BUILDING_CLAUDE_APPS, BYOC_ENVIRONMENT_RUNNER, CCR_AUTO_CONNECT, CCR_MIRROR, COMPACTION_REMINDERS, COWORKER_TYPE_TELEMETRY, DOWNLOAD_USER_SETTINGS, DUMP_SYSTEM_PROMPT, ENHANCED_TELEMETRY_BETA, FILE_PERSISTENCE, HARD_FAIL, HOOK_PROMPTS, IS_LIBC_GLIBC, IS_LIBC_MUSL, MCP_RICH_OUTPUT, MEMORY_SHAPE_TELEMETRY, NATIVE_CLIPBOARD_IMAGE, NEW_INIT, OVERFLOW_TEST_TOOL, PERFETTO_TRACING, POWERSHELL_AUTO_MODE, QUICK_SEARCH, RUN_SKILL_GENERATOR, SELF_HOSTED_RUNNER, SKILL_IMPROVEMENT, SLOW_OPERATION_LOGGING, TREE_SITTER_BASH, TREE_SITTER_BASH_SHADOW, UNATTENDED_RETRY, UPLOAD_USER_SETTINGS, SKIP_DETECTION_WHEN_AUTOUPDATES_DISABLED |
 
 ---
 
@@ -51,14 +51,31 @@ Claude Code 使用三层门控系统:
 | SHOT_STATS | **ON** | **ON** | compile-only, 已验证 | 纯本地统计 |
 | PROMPT_CACHE_BREAK_DETECTION | **ON** | **ON** | compile-only, 已验证 | 内部诊断 |
 | TOKEN_BUDGET | **ON** | **ON** | compile-only, 已验证 | 支持 `+500k` 语法 |
-| AGENT_TRIGGERS | **ON** | **ON** | compile+GB gate, 已验证 | 本轮新增，定时任务系统 |
-| EXTRACT_MEMORIES | **ON** | **ON** | compile+GB gate, 已验证 | 本轮新增，自动记忆提取 |
-| VERIFICATION_AGENT | **ON** | **ON** | compile+GB gate, 已验证 | 本轮新增，对抗性验证代理 |
-| KAIROS_BRIEF | **ON** | **ON** | compile+GB gate, 已验证 | 本轮新增，Brief 精简模式 |
-| AWAY_SUMMARY | **ON** | **ON** | compile+GB gate, 已验证 | 本轮新增，离开摘要 |
+| AGENT_TRIGGERS | **ON** | **ON** | compile+GB gate, 已验证 | 本地定时任务系统 |
+| ULTRATHINK | **ON** | **ON** | compile-only | 扩展思考模式 |
+| BUILTIN_EXPLORE_PLAN_AGENTS | **ON** | **ON** | compile-only | 内置 Explore/Plan agent |
+| LODESTONE | **ON** | **ON** | compile-only | 深度链接 URL 协议 |
+| EXTRACT_MEMORIES | **ON** | **ON** | compile+GB gate, 已验证 | 自动记忆提取 |
+| VERIFICATION_AGENT | **ON** | **ON** | compile+GB gate, 已验证 | 对抗性验证代理 |
+| KAIROS_BRIEF | **ON** | **ON** | compile+GB gate, 已验证 | Brief 精简模式 |
+| AWAY_SUMMARY | **ON** | **ON** | compile+GB gate, 已验证 | 离开摘要 |
+| ULTRAPLAN | **ON** | **ON** | compile+remote | 高级规划，需 CCR 基础设施 |
+| DAEMON | **ON** | **ON** | compile-only | 后台守护进程 |
+| ACP | **ON** | **ON** | compile-only | ACP 协议支持 |
+| WORKFLOW_SCRIPTS | **ON** | **ON** | compile-only | 工作流脚本 |
+| HISTORY_SNIP | **ON** | **ON** | compile-only | 历史管理 |
+| CONTEXT_COLLAPSE | **ON** | **ON** | compile-only | 上下文折叠（核心 stub） |
+| MONITOR_TOOL | **ON** | **ON** | compile-only | 后台监控 |
+| FORK_SUBAGENT | **ON** | **ON** | compile-only | 子 Agent |
+| KAIROS | **ON** | **ON** | compile-only | Kairos 调度 |
+| COORDINATOR_MODE | **ON** | **ON** | compile-only | 多 Worker 协调 |
 | BUDDY | off | **ON** | compile+GrowthBook | 仅 dev 模式 |
 | TRANSCRIPT_CLASSIFIER | off | **ON** | compile+GrowthBook | 仅 dev 模式 |
 | BRIDGE_MODE | off | **ON** | compile+remote | 仅 dev 模式，需 claude.ai 订阅 |
+| UDS_INBOX | off | **ON** | compile-only | 仅 dev 模式 |
+| LAN_PIPES | off | **ON** | compile-only | 仅 dev 模式 |
+| BG_SESSIONS | off | **ON** | compile+GB gate | 仅 dev 模式 |
+| TEMPLATES | off | **ON** | compile-only | 仅 dev 模式 |
 
 ---
 
@@ -124,9 +141,9 @@ Claude Code 使用三层门控系统:
 8. src/hooks/useReplBridge.tsx — REPL 桥接 Hook
 9. src/main.tsx — 主入口中的桥接模式启动
 10. src/screens/REPL.tsx — REPL 屏幕中的桥接集成
-11. src/tools/BriefTool/attachments.ts — Brief 工具附件处理
-12. src/tools/BriefTool/upload.ts — Brief 工具上传
-13. src/tools/ConfigTool/supportedSettings.ts — 配置工具中的桥接设置
+11. packages/builtin-tools/src/tools/BriefTool/attachments.ts — Brief 工具附件处理
+12. packages/builtin-tools/src/tools/BriefTool/upload.ts — Brief 工具上传
+13. packages/builtin-tools/src/tools/ConfigTool/supportedSettings.ts — 配置工具中的桥接设置
 
 **启用所需操作**: 仅需将编译标志 `BRIDGE_MODE` 设为 `true`。所有代码完整，命令入口 `src/commands/bridge/index.ts`（604 行）和 `src/commands/bridge/bridge.tsx`（46,907 行）均存在。
 
@@ -185,8 +202,8 @@ src/utils/swarm/ 目录（22 个文件）:
 7. src/screens/REPL.tsx — REPL 屏幕中的协调器集成
 8. src/screens/ResumeConversation.tsx — 恢复对话时的协调器处理
 9. src/tools.ts — 工具注册中的协调器工具
-10. src/tools/AgentTool/AgentTool.tsx — Agent 工具中的协调器模式分支
-11. src/tools/AgentTool/builtInAgents.ts — 内置代理定义
+10. packages/builtin-tools/src/tools/AgentTool/AgentTool.tsx — Agent 工具中的协调器模式分支
+11. packages/builtin-tools/src/tools/AgentTool/builtInAgents.ts — 内置代理定义
 12. src/utils/processUserInput/processSlashCommand.tsx — 斜杠命令处理中的协调器
 13. src/utils/sessionRestore.ts — 会话恢复中的协调器状态
 14. src/utils/systemPrompt.ts — 系统提示中的协调器指令
@@ -259,9 +276,9 @@ src/utils/swarm/ 目录（22 个文件）:
 9. src/screens/REPL.tsx — REPL 中的语音模式集成
 10. src/services/voiceStreamSTT.ts — STT 服务
 11. src/state/AppState.tsx — 应用状态中的语音状态
-12. src/tools/ConfigTool/ConfigTool.ts — 配置工具中的语音设置
-13. src/tools/ConfigTool/prompt.ts — 配置工具提示
-14. src/tools/ConfigTool/supportedSettings.ts — 支持的设置项
+12. packages/builtin-tools/src/tools/ConfigTool/ConfigTool.ts — 配置工具中的语音设置
+13. packages/builtin-tools/src/tools/ConfigTool/prompt.ts — 配置工具提示
+14. packages/builtin-tools/src/tools/ConfigTool/supportedSettings.ts — 支持的设置项
 15. src/utils/settings/types.ts — 设置类型定义
 16. src/voice/voiceModeEnabled.ts — 语音模式启用逻辑
 
@@ -385,8 +402,8 @@ src/utils/swarm/ 目录（22 个文件）:
 11. src/hooks/toolPermission/permissionLogging.ts — 权限日志
 12. src/hooks/useCanUseTool.tsx — 工具可用性检查
 13. src/services/api/withRetry.ts — API 重试中的分类器
-14. src/tools/BashTool/bashPermissions.ts — Bash 权限逻辑
-15. src/tools/BashTool/pathValidation.ts — 路径验证
+14. packages/builtin-tools/src/tools/BashTool/bashPermissions.ts — Bash 权限逻辑
+15. packages/builtin-tools/src/tools/BashTool/pathValidation.ts — 路径验证
 16. src/utils/classifierApprovals.ts — 分类器审批记录
 17. src/utils/messages.ts — 消息处理
 18. src/utils/permissions/permissions.ts — 权限核心
@@ -431,11 +448,11 @@ src/utils/swarm/ 目录（22 个文件）:
 22. src/screens/REPL.tsx — REPL 屏幕
 23. src/services/api/claude.ts — Claude API 服务
 24. src/services/tools/toolExecution.ts — 工具执行
-25. src/tools/AgentTool/AgentTool.tsx — Agent 工具
-26. src/tools/AgentTool/agentToolUtils.ts — Agent 工具工具函数
-27. src/tools/AgentTool/runAgent.ts — 运行 Agent
-28. src/tools/BashTool/bashPermissions.ts — Bash 权限
-29. src/tools/ConfigTool/supportedSettings.ts — 支持的设置
+25. packages/builtin-tools/src/tools/AgentTool/AgentTool.tsx — Agent 工具
+26. packages/builtin-tools/src/tools/AgentTool/agentToolUtils.ts — Agent 工具工具函数
+27. packages/builtin-tools/src/tools/AgentTool/runAgent.ts — 运行 Agent
+28. packages/builtin-tools/src/tools/BashTool/bashPermissions.ts — Bash 权限
+29. packages/builtin-tools/src/tools/ConfigTool/supportedSettings.ts — 支持的设置
 30. src/tools/ExitPlanModeTool/ExitPlanModeV2Tool.ts — 退出计划模式工具
 31. src/tools/NotebookEditTool/NotebookEditTool.ts — Notebook 编辑工具
 32. src/types/permissions.ts — 权限类型
@@ -543,11 +560,10 @@ src/utils/swarm/ 目录（22 个文件）:
 
 | 文件路径 | 行数 | 功能说明 |
 |----------|------|----------|
-| src/tools/ScheduleCronTool/CronCreateTool.ts | 157 行 | Cron 创建工具 |
-| src/tools/ScheduleCronTool/prompt.ts | 135 行 | Cron 工具提示词 |
-| src/tools/ScheduleCronTool/CronListTool.ts | 97 行 | Cron 列表工具 |
-| src/tools/ScheduleCronTool/CronDeleteTool.ts | 95 行 | Cron 删除工具 |
-| src/tools/ScheduleCronTool/UI.tsx | 59 行 | Cron UI 组件 |
+| packages/builtin-tools/src/tools/ScheduleCronTool/CronCreateTool.ts | 157 行 | Cron 创建工具 |
+| packages/builtin-tools/src/tools/ScheduleCronTool/prompt.ts | 135 行 | Cron 工具提示词 |
+| packages/builtin-tools/src/tools/ScheduleCronTool/CronListTool.ts | 97 行 | Cron 列表工具 |
+| packages/builtin-tools/src/tools/ScheduleCronTool/CronDeleteTool.ts | 95 行 | Cron 删除工具 |
 
 **引用该标志的文件（6 个）**:
 1. src/cli/print.ts — CLI 输出
@@ -598,7 +614,7 @@ src/utils/swarm/ 目录（22 个文件）:
 
 | 文件路径 | 行数 | 功能说明 |
 |----------|------|----------|
-| src/tools/BriefTool/BriefTool.ts | 204 行 | Brief 工具核心 |
+| packages/builtin-tools/src/tools/BriefTool/BriefTool.ts | 204 行 | Brief 工具核心 |
 | src/commands/brief.ts | 130 行 | Brief 命令实现 |
 
 **引用该标志的文件（20 个）**:
@@ -616,7 +632,7 @@ src/utils/swarm/ 目录（22 个文件）:
 12. src/hooks/useGlobalKeybindings.tsx — 全局键绑定
 13. src/keybindings/defaultBindings.ts — 默认键绑定
 14. src/main.tsx — 主入口
-15. src/tools/BriefTool/BriefTool.ts — Brief 工具
+15. packages/builtin-tools/src/tools/BriefTool/BriefTool.ts — Brief 工具
 16. src/tools/ToolSearchTool/prompt.ts — 工具搜索提示
 17. src/utils/attachments.ts — 附件
 18. src/utils/conversationRecovery.ts — 对话恢复
@@ -718,7 +734,7 @@ src/utils/swarm/ 目录（22 个文件）:
 9. src/screens/REPL.tsx — REPL（多处引用，通过 require 加载 proactive 模块）
 10. src/services/compact/prompt.ts — 压缩提示
 11. src/tools.ts — 工具注册
-12. src/tools/AgentTool/AgentTool.tsx — Agent 工具
+12. packages/builtin-tools/src/tools/AgentTool/AgentTool.tsx — Agent 工具
 13. src/utils/sessionStorage.ts — 会话存储
 14. src/utils/settings/types.ts — 设置类型
 15. src/utils/systemPrompt.ts — 系统提示
@@ -771,11 +787,11 @@ src/utils/swarm/ 目录（22 个文件）:
 | 文件路径 | 行数 | 功能说明 |
 |----------|------|----------|
 | src/tools/TaskUpdateTool/TaskUpdateTool.ts | 406 行 | 任务更新工具 |
-| src/tools/AgentTool/builtInAgents.ts | 72 行 | 内置代理定义 |
+| packages/builtin-tools/src/tools/AgentTool/builtInAgents.ts | 72 行 | 内置代理定义 |
 
 **引用该标志的文件（4 个）**:
 1. src/constants/prompts.ts — 提示词
-2. src/tools/AgentTool/builtInAgents.ts — 内置代理
+2. packages/builtin-tools/src/tools/AgentTool/builtInAgents.ts — 内置代理
 3. src/tools/TaskUpdateTool/TaskUpdateTool.ts — 任务更新工具
 4. src/tools/TodoWriteTool/TodoWriteTool.ts — TodoWrite 工具
 
@@ -796,7 +812,7 @@ src/utils/swarm/ 目录（22 个文件）:
 3. src/services/compact/autoCompact.ts — 自动压缩
 4. src/services/compact/compact.ts — 压缩核心
 5. src/services/compact/microCompact.ts — 微压缩
-6. src/tools/AgentTool/runAgent.ts — 运行 Agent
+6. packages/builtin-tools/src/tools/AgentTool/runAgent.ts — 运行 Agent
 
 **启用所需操作**: 仅需将编译标志 `PROMPT_CACHE_BREAK_DETECTION` 设为 `true`。
 
@@ -856,11 +872,11 @@ src/utils/swarm/ 目录（22 个文件）:
 38. src/services/mcp/useManageMCPConnections.ts
 39. src/skills/bundled/index.ts
 40. src/tools.ts
-41. src/tools/AgentTool/AgentTool.tsx
+41. packages/builtin-tools/src/tools/AgentTool/AgentTool.tsx
 42. src/tools/AskUserQuestionTool/AskUserQuestionTool.tsx
-43. src/tools/BashTool/BashTool.tsx
-44. src/tools/BriefTool/BriefTool.ts
-45. src/tools/ConfigTool/supportedSettings.ts
+43. packages/builtin-tools/src/tools/BashTool/BashTool.tsx
+44. packages/builtin-tools/src/tools/BriefTool/BriefTool.ts
+45. packages/builtin-tools/src/tools/ConfigTool/supportedSettings.ts
 46. src/tools/EnterPlanModeTool/EnterPlanModeTool.ts
 47. src/tools/ExitPlanModeTool/ExitPlanModeV2Tool.ts
 48. src/tools/PowerShellTool/PowerShellTool.tsx
@@ -877,8 +893,8 @@ src/utils/swarm/ 目录（22 个文件）:
 59. src/utils/systemPrompt.ts
 
 **缺失文件**:
-- src/commands/assistant/index.ts — 完全缺失（src/commands.ts 第 69 行引用了 `commands/assistant/index.js`）
-- src/commands/assistant/gate.ts — 完全缺失
+- ~~src/commands/assistant/index.ts~~ — 已补全
+- ~~src/commands/assistant/gate.ts~~ — 已补全
 
 **启用所需修复**: 需要创建 `src/commands/assistant/` 目录及其 `index.ts` 和 `gate.ts` 文件。
 
@@ -930,7 +946,7 @@ src/utils/swarm/ 目录（22 个文件）:
 | 文件路径 | 行数 | 功能说明 |
 |----------|------|----------|
 | src/tasks/LocalShellTask/LocalShellTask.tsx | 522 行 | 本地 Shell 任务完整实现 |
-| src/tools/MonitorTool/MonitorTool.ts | 1 行 | 监控工具（桩） |
+| packages/builtin-tools/src/tools/MonitorTool/MonitorTool.ts | 1 行 | 监控工具（桩） |
 | src/tasks/MonitorMcpTask/MonitorMcpTask.ts | 5 行 | MCP 监控任务（桩） |
 | src/components/tasks/MonitorMcpDetailDialog.tsx | 3 行 | MCP 详情对话框（桩） |
 | src/components/permissions/MonitorPermissionRequest/MonitorPermissionRequest.tsx | 3 行 | 监控权限请求（桩） |
@@ -941,12 +957,12 @@ src/utils/swarm/ 目录（22 个文件）:
 3. src/tasks.ts — 任务注册
 4. src/tasks/LocalShellTask/LocalShellTask.tsx — Shell 任务
 5. src/tools.ts — 工具注册
-6. src/tools/AgentTool/runAgent.ts — Agent 运行
-7. src/tools/BashTool/BashTool.tsx — Bash 工具
-8. src/tools/BashTool/prompt.ts — Bash 提示
+6. packages/builtin-tools/src/tools/AgentTool/runAgent.ts — Agent 运行
+7. packages/builtin-tools/src/tools/BashTool/BashTool.tsx — Bash 工具
+8. packages/builtin-tools/src/tools/BashTool/prompt.ts — Bash 提示
 9. src/tools/PowerShellTool/PowerShellTool.tsx — PowerShell 工具
 
-**启用所需修复**: 需要实现 `src/tools/MonitorTool/MonitorTool.ts`、`src/tasks/MonitorMcpTask/MonitorMcpTask.ts`、`src/components/tasks/MonitorMcpDetailDialog.tsx` 和 `src/components/permissions/MonitorPermissionRequest/MonitorPermissionRequest.tsx`。
+**启用所需修复**: 需要实现 `packages/builtin-tools/src/tools/MonitorTool/MonitorTool.ts`、`src/tasks/MonitorMcpTask/MonitorMcpTask.ts`、`src/components/tasks/MonitorMcpDetailDialog.tsx` 和 `src/components/permissions/MonitorPermissionRequest/MonitorPermissionRequest.tsx`。
 
 ---
 
@@ -988,10 +1004,11 @@ src/utils/swarm/ 目录（22 个文件）:
 | src/components/WorkflowMultiselectDialog.tsx | 127 行 | 工作流多选对话框（有内容） |
 | src/tasks/LocalWorkflowTask/LocalWorkflowTask.ts | 5 行 | 本地工作流任务（桩） |
 | src/components/tasks/WorkflowDetailDialog.tsx | 3 行 | 工作流详情对话框（桩） |
-| src/tools/WorkflowTool/WorkflowPermissionRequest.tsx | 3 行 | 工作流权限请求（桩） |
-| src/tools/WorkflowTool/createWorkflowCommand.ts | 3 行 | 创建工作流命令（桩） |
-| src/tools/WorkflowTool/WorkflowTool.ts | 1 行 | 工作流工具（桩） |
-| src/tools/WorkflowTool/constants.ts | 1 行 | 常量（桩） |
+| packages/builtin-tools/src/tools/WorkflowTool/WorkflowPermissionRequest.tsx | ~80 行 | 工作流权限请求组件 |
+| packages/builtin-tools/src/tools/WorkflowTool/createWorkflowCommand.ts | 41 行 | 创建工作流命令（已实现） |
+| packages/builtin-tools/src/tools/WorkflowTool/WorkflowTool.ts | 74 行 | 工作流工具（部分实现，call 需运行时） |
+| packages/builtin-tools/src/tools/WorkflowTool/constants.ts | ~10 行 | 常量定义 |
+| packages/builtin-tools/src/tools/WorkflowTool/bundled/index.ts | ~20 行 | 内置工作流初始化 |
 
 **引用该标志的文件（7 个）**:
 1. src/commands.ts — 命令注册（引用 `commands/workflows/index.js`）
@@ -1011,38 +1028,32 @@ src/utils/swarm/ 目录（22 个文件）:
 
 ## 28. UDS_INBOX
 
-**编译时引用次数**: 18（单引号 17 + 双引号 1）
-**功能描述**: UDS（Unix Domain Socket）收件箱。允许 Claude Code 实例之间通过 Unix 套接字发送消息。
-**分类**: PARTIAL
-**缺失原因**: `src/utils/udsMessaging.ts` 仅 1 行，`src/utils/udsClient.ts` 仅 3 行（空壳），命令入口缺失
+**编译时引用次数**: 18（历史快照）
+**功能描述**: 本机进程间通信能力。当前由两层组成：
+1. `udsMessaging` / `udsClient`：通用 UDS 消息层，供 `SendMessageTool` 与 `/peers` 使用。
+2. `pipeTransport` / `pipeRegistry`：会话级 named-pipe 协调层，供 `/pipes`、`/attach`、`/detach`、`/send`、`/pipe-status`、`/history`、`/claim-main` 使用。
+
+**当前分类**: IMPLEMENTED / EXPERIMENTAL
+
+**当前事实**:
+- `src/utils/udsMessaging.ts` 与 `src/utils/udsClient.ts` 已实现，不再是空壳。
+- `src/utils/pipeTransport.ts` 使用本机 named pipe / Unix socket；`localIp` / `hostname` / `machineId` 仅用于注册表展示与身份判定，不是已上线的局域网传输层。
+- `src/screens/REPL.tsx` 内联承载当前有效的 pipe 控制平面；早期 hook 试验路径已清理。
 
 **核心实现文件**:
 
-| 文件路径 | 行数 | 功能说明 |
-|----------|------|----------|
-| src/tools/SendMessageTool/SendMessageTool.ts | 917 行 | 发送消息工具（完整实现） |
-| src/tools/SendMessageTool/prompt.ts | 49 行 | 消息工具提示词 |
-| src/utils/udsClient.ts | 3 行 | UDS 客户端（桩） |
-| src/utils/udsMessaging.ts | 1 行 | UDS 消息（桩） |
+| 文件路径 | 功能说明 |
+|----------|----------|
+| src/utils/udsMessaging.ts | 通用 UDS server / inbox |
+| src/utils/udsClient.ts | 通用 peer 发现、探活、发送 |
+| src/utils/pipeTransport.ts | named-pipe server/client、探活、AppState 扩展 |
+| src/utils/pipeRegistry.ts | main/sub 注册表、machineId、claim-main |
+| src/commands/peers/peers.ts | UDS peer 可达性检查 |
+| src/commands/pipes/pipes.ts | pipe 注册表检查与选择器入口 |
+| src/commands/attach/attach.ts | master -> slave attach |
+| src/screens/REPL.tsx | 当前生效的 REPL pipe bootstrap 与心跳 |
 
-**引用该标志的文件（10 个）**:
-1. src/cli/print.ts — CLI 输出
-2. src/commands.ts — 命令注册（引用 `commands/peers/index.js`）
-3. src/components/messages/UserTextMessage.tsx — 用户消息
-4. src/main.tsx — 主入口
-5. src/setup.ts — 初始化
-6. src/tools.ts — 工具注册
-7. src/tools/SendMessageTool/SendMessageTool.ts — 发送消息工具
-8. src/tools/SendMessageTool/prompt.ts — 提示词
-9. src/utils/concurrentSessions.ts — 并发会话
-10. src/utils/messages/systemInit.ts — 系统初始化消息
-
-**缺失文件**:
-- src/commands/peers/index.ts — 命令入口缺失
-- src/utils/udsMessaging.ts — 仅 1 行空壳
-- src/utils/udsClient.ts — 仅 3 行空壳
-
-**启用所需修复**: 需要实现 UDS 客户端和消息模块，并创建命令入口。
+**备注**: 如需真实局域网通信，需要单独引入 TCP/WebSocket 传输、认证与发现机制；现有代码尚未实现该层。详见 `docs/features/uds-inbox.md`。
 
 ---
 
@@ -1092,13 +1103,13 @@ src/utils/swarm/ 目录（22 个文件）:
 
 | 文件路径 | 行数 | 功能说明 |
 |----------|------|----------|
-| src/tools/AgentTool/forkSubagent.ts | 210 行 | 分叉子代理核心逻辑 |
+| packages/builtin-tools/src/tools/AgentTool/forkSubagent.ts | 210 行 | 分叉子代理核心逻辑 |
 
 **引用该标志的文件（5 个）**:
 1. src/commands.ts — 命令注册
 2. src/commands/branch/index.ts — 分支命令入口
 3. src/components/messages/UserTextMessage.tsx — 用户消息
-4. src/tools/AgentTool/forkSubagent.ts — 分叉逻辑
+4. packages/builtin-tools/src/tools/AgentTool/forkSubagent.ts — 分叉逻辑
 5. src/tools/ToolSearchTool/prompt.ts — 工具搜索提示
 
 **缺失文件**:
@@ -1122,7 +1133,7 @@ src/utils/swarm/ 目录（22 个文件）:
 4. src/query.ts — 查询
 5. src/services/compact/compact.ts — 压缩
 6. src/services/mcp/useManageMCPConnections.ts — MCP 连接管理
-7. src/tools/SkillTool/SkillTool.ts — 技能工具（1,108 行）
+7. packages/builtin-tools/src/tools/SkillTool/SkillTool.ts — 技能工具（1,108 行）
 8. src/utils/attachments.ts — 附件
 9. src/utils/messages.ts — 消息
 
@@ -1342,21 +1353,24 @@ src/utils/swarm/ 目录（22 个文件）:
 **引用文件**:
 1. src/components/Settings/Config.tsx — 设置
 2. src/tools.ts — 工具注册
-3. src/tools/ConfigTool/supportedSettings.ts — 支持的设置
+3. packages/builtin-tools/src/tools/ConfigTool/supportedSettings.ts — 支持的设置
 **代码量**: 0 行专属代码，仅在设置中预留了开关位
 
 ---
 
-## 45. DAEMON
+## 45. DAEMON `[build: ON] [dev: ON]`
 
 **编译时引用次数**: 3
-**功能描述**: 守护进程模式。
-**分类**: STUB
+**功能描述**: 守护进程模式。允许 Claude Code 作为后台长驻 supervisor 进程运行，管理多个 worker。
+**分类**: COMPLETE（已恢复）
+**核心实现文件**:
+1. src/daemon/main.ts — 413 行，daemon 主入口，管理生命周期
+2. src/daemon/workerRegistry.ts — 112 行，worker 注册和管理
+3. src/commands/daemon/index.ts — daemon 子命令入口
 **引用文件**:
-1. src/commands.ts — 条件注册命令（与 BRIDGE_MODE 组合）
-2. src/entrypoints/cli.tsx — CLI 入口
-**代码量**: 0 行专属代码
-**说明**: 在 commands.ts 中，`DAEMON` 与 `BRIDGE_MODE` 一起用于条件加载 `commands/remoteControlServer/index.js`，该文件不存在。
+1. src/commands.ts — 条件注册命令
+2. src/entrypoints/cli.tsx — CLI 入口中的 `--daemon-worker` 路径
+**说明**: 已从 stub 恢复为完整实现，支持 `daemon start/status/stop` 子命令、exponential backoff、state file 持久化。
 
 ---
 
@@ -1427,7 +1441,7 @@ src/utils/swarm/ 目录（22 个文件）:
 **分类**: STUB
 **引用文件**:
 1. src/main.tsx — 主入口
-2. src/tools/AgentTool/loadAgentsDir.ts — 加载代理目录
+2. packages/builtin-tools/src/tools/AgentTool/loadAgentsDir.ts — 加载代理目录
 **代码量**: 0 行专属代码
 
 ---
@@ -1462,7 +1476,7 @@ src/utils/swarm/ 目录（22 个文件）:
 **引用文件**:
 1. src/components/ThemePicker.tsx — 主题选择器
 2. src/components/design-system/ThemeProvider.tsx — 主题提供者
-3. src/tools/ConfigTool/supportedSettings.ts — 支持的设置
+3. packages/builtin-tools/src/tools/ConfigTool/supportedSettings.ts — 支持的设置
 **代码量**: 0 行专属代码
 
 ---
@@ -1504,7 +1518,7 @@ src/utils/swarm/ 目录（22 个文件）:
 **编译时引用次数**: 1
 **功能描述**: 内置探索和计划代理。
 **分类**: STUB
-**引用文件**: src/tools/AgentTool/builtInAgents.ts — 内置代理定义
+**引用文件**: packages/builtin-tools/src/tools/AgentTool/builtInAgents.ts — 内置代理定义
 **代码量**: 0 行专属代码
 
 ---
@@ -1795,7 +1809,7 @@ src/utils/swarm/ 目录（22 个文件）:
 **功能描述**: Tree-sitter Bash 影子模式（并行运行 tree-sitter 和传统解析器进行对比）。
 **分类**: STUB
 **引用文件**:
-1. src/tools/BashTool/bashPermissions.ts — Bash 权限
+1. packages/builtin-tools/src/tools/BashTool/bashPermissions.ts — Bash 权限
 2. src/utils/bash/parser.ts — Bash 解析器
 **代码量**: 0 行专属代码
 
@@ -1869,16 +1883,16 @@ src/utils/swarm/ 目录（22 个文件）:
 
 | 文件路径 | 行数 | 所属标志 |
 |----------|------|----------|
-| src/tools/MonitorTool/MonitorTool.ts | 1 行 | MONITOR_TOOL |
-| src/tools/WorkflowTool/WorkflowTool.ts | 1 行 | WORKFLOW_SCRIPTS |
-| src/tools/WorkflowTool/constants.ts | 1 行 | WORKFLOW_SCRIPTS |
+| packages/builtin-tools/src/tools/MonitorTool/MonitorTool.ts | 1 行 | MONITOR_TOOL |
+| packages/builtin-tools/src/tools/WorkflowTool/WorkflowTool.ts | 1 行 | WORKFLOW_SCRIPTS |
+| packages/builtin-tools/src/tools/WorkflowTool/constants.ts | 1 行 | WORKFLOW_SCRIPTS |
 | src/tools/ReviewArtifactTool/ReviewArtifactTool.ts | 1 行 | REVIEW_ARTIFACT |
-| src/utils/udsMessaging.ts | 1 行 | UDS_INBOX |
-| src/utils/udsClient.ts | 3 行 | UDS_INBOX |
+| src/utils/udsMessaging.ts | 已实现 | UDS_INBOX |
+| src/utils/udsClient.ts | 已实现 | UDS_INBOX |
 | src/skills/mcpSkills.ts | 3 行 | MCP_SKILLS |
 | src/tools/WebBrowserTool/WebBrowserPanel.tsx | 3 行 | WEB_BROWSER_TOOL |
-| src/tools/WorkflowTool/createWorkflowCommand.ts | 3 行 | WORKFLOW_SCRIPTS |
-| src/tools/WorkflowTool/WorkflowPermissionRequest.tsx | 3 行 | WORKFLOW_SCRIPTS |
+| packages/builtin-tools/src/tools/WorkflowTool/createWorkflowCommand.ts | 3 行 | WORKFLOW_SCRIPTS |
+| packages/builtin-tools/src/tools/WorkflowTool/WorkflowPermissionRequest.tsx | 3 行 | WORKFLOW_SCRIPTS |
 | src/components/tasks/WorkflowDetailDialog.tsx | 3 行 | WORKFLOW_SCRIPTS |
 | src/components/permissions/MonitorPermissionRequest/MonitorPermissionRequest.tsx | 3 行 | MONITOR_TOOL |
 | src/components/tasks/MonitorMcpDetailDialog.tsx | 3 行 | MONITOR_TOOL |

docs/features/fork-subagent.md

@@ -37,7 +37,7 @@ Agent({ subagent_type: "general-purpose", prompt: "..." })
 
 ### 3.1 门控与互斥
 
-文件：`src/tools/AgentTool/forkSubagent.ts:32-39`
+文件：`packages/builtin-tools/src/tools/AgentTool/forkSubagent.ts:32-39`
 
 ```ts
 export function isForkSubagentEnabled(): boolean {
@@ -105,7 +105,7 @@ isForkSubagentEnabled() && !subagent_type?
 
 ### 3.4 消息构建：buildForkedMessages
 
-文件：`src/tools/AgentTool/forkSubagent.ts:107-169`
+文件：`packages/builtin-tools/src/tools/AgentTool/forkSubagent.ts:107-169`
 
 构建的消息结构：
 
@@ -185,11 +185,11 @@ FEATURE_FORK_SUBAGENT=1 bun run dev
 
 | 文件 | 行数 | 职责 |
 |------|------|------|
-| `src/tools/AgentTool/forkSubagent.ts` | ~210 | 核心定义 + 消息构建 + 递归防护 |
-| `src/tools/AgentTool/AgentTool.tsx` | — | Fork 路由 + 强制异步 |
-| `src/tools/AgentTool/prompt.ts` | — | "When to Fork" 提示词段落 |
-| `src/tools/AgentTool/runAgent.ts` | — | useExactTools 路径 |
-| `src/tools/AgentTool/resumeAgent.ts` | — | Fork agent 恢复 |
+| `packages/builtin-tools/src/tools/AgentTool/forkSubagent.ts` | ~210 | 核心定义 + 消息构建 + 递归防护 |
+| `packages/builtin-tools/src/tools/AgentTool/AgentTool.tsx` | — | Fork 路由 + 强制异步 |
+| `packages/builtin-tools/src/tools/AgentTool/prompt.ts` | — | "When to Fork" 提示词段落 |
+| `packages/builtin-tools/src/tools/AgentTool/runAgent.ts` | — | useExactTools 路径 |
+| `packages/builtin-tools/src/tools/AgentTool/resumeAgent.ts` | — | Fork agent 恢复 |
 | `src/constants/xml.ts` | — | XML 标签常量 |
 | `src/utils/forkedAgent.ts` | — | CacheSafeParams + ContentReplacementState 克隆 |
 | `src/commands/fork/index.ts` | — | /fork 命令（stub） |

docs/features/kairos.md

@@ -1,7 +1,7 @@
 # KAIROS — 常驻助手模式
 
 > Feature Flag: `FEATURE_KAIROS=1`（及子 Feature）
-> 实现状态：核心框架完整，部分子模块为 stub
+> 实现状态：核心框架完整，部分子模块为 stub；proactive/sleep 节奏控制已可用
 > 引用数：154（全库最大）
 
 ## 一、功能概述
@@ -34,13 +34,13 @@ KAIROS 在系统提示中注入两大段落：
 
 ### 2.1 Brief 段落 (`getBriefSection`)
 
-文件：`src/constants/prompts.ts:843-858`
+文件：`src/constants/prompts.ts:847-858`
 
 当 `feature('KAIROS') || feature('KAIROS_BRIEF')` 时注入。Brief 工具（`SendUserMessage`）的结构化消息输出指令。`/brief` toggle 和 `--brief` flag 只控制显示过滤，不影响模型行为。
 
 ### 2.2 Proactive/Autonomous Work 段落 (`getProactiveSection`)
 
-文件：`src/constants/prompts.ts:860-914`
+文件：`src/constants/prompts.ts:864-918`
 
 当 `feature('PROACTIVE') || feature('KAIROS')` 且 `isProactiveActive()` 时注入。核心行为指令：
 
@@ -74,8 +74,9 @@ KAIROS 在系统提示中注入两大段落：
 
 SleepTool 是 KAIROS/Proactive 的节奏控制核心。工具描述让模型理解"休眠"概念：
 - 工具名：`Sleep`
-- 功能：等待指定时间后响应 tick prompt
+- 功能：等待指定时间后响应 tick prompt；若队列出现新工作或 proactive 被关闭，会提前唤醒
 - 与 `<tick_tag>` 配合实现心跳式自主工作
+- 远程控制 surfaces 可通过 `automation_state` 看到 `standby` / `sleeping` 两种状态
 
 ### 3.3 Bridge 集成
 
@@ -172,8 +173,10 @@ FEATURE_KAIROS=1 FEATURE_TOKEN_BUDGET=1 bun run dev
 | `src/assistant/AssistantSessionChooser.ts` | — | Session 选择 UI（stub） |
 | `src/tools/BriefTool/` | — | BriefTool 实现（stub） |
 | `src/tools/SleepTool/prompt.ts` | ~30 | SleepTool 工具提示 |
+| `src/tools/SleepTool/SleepTool.ts` | ~200 | 休眠/唤醒与 automation metadata |
 | `src/services/mcp/channelNotification.ts` | 5 | 频道消息接入（stub） |
 | `src/memdir/memdir.ts` | — | 记忆目录管理（stub） |
-| `src/constants/prompts.ts:552-554,843-914` | 72 | 系统提示注入 |
+| `src/constants/prompts.ts:557,847-918` | 72 | 系统提示注入 |
 | `src/components/tasks/src/tasks/DreamTask/` | 3 | Dream 任务（stub） |
-| `src/proactive/index.ts` | — | Proactive 核心（stub，KAIROS 共享） |
+| `src/proactive/index.ts` | — | Proactive 核心（KAIROS 共享） |
+| `src/utils/sessionState.ts` | — | 向 bridge/CCR 暴露 automation 状态 |

docs/features/lan-pipes-implementation.md

@@ -0,0 +1,321 @@
+# LAN Pipes — 技术实现文档
+
+面向开发者的实现细节。用户指南见 [lan-pipes.md](./lan-pipes.md)。
+
+---
+
+## 架构
+
+```
+Machine A (192.168.50.22)                Machine B (192.168.50.27)
+┌───────────────────────────┐           ┌───────────────────────────┐
+│ PipeServer                │           │ PipeServer                │
+│   UDS: ~/.claude/pipes/   │           │   UDS: ~/.claude/pipes/   │
+│       cli-abc.sock        │           │       cli-def.sock        │
+│   TCP: 0.0.0.0:<random>  │◄──TCP───►│   TCP: 0.0.0.0:<random>  │
+├───────────────────────────┤           ├───────────────────────────┤
+│ LanBeacon                 │           │ LanBeacon                 │
+│   UDP 224.0.71.67:7101    │◄──UDP───►│   UDP 224.0.71.67:7101    │
+├───────────────────────────┤           ├───────────────────────────┤
+│ usePipeIpc (hook)         │           │ usePipeIpc (hook)         │
+│   initPipeServer          │           │   initPipeServer          │
+│   registerMessageHandlers │           │   registerMessageHandlers │
+│   runMainHeartbeat        │           │   runSubHeartbeat         │
+│   cleanupPipeIpc          │           │   cleanupPipeIpc          │
+└───────────────────────────┘           └───────────────────────────┘
+```
+
+## Feature Flag
+
+`LAN_PIPES` — 在 `scripts/dev.ts` 和 `build.ts` 的 `DEFAULT_FEATURES` 中启用。
+
+所有 LAN 代码路径通过 `feature('LAN_PIPES')` 编译时门控。`feature()` 只能在 `if` 或三元中使用（Bun 编译时常量约束）。
+
+---
+
+## 核心文件
+
+| 文件 | 说明 |
+|------|------|
+| `src/utils/pipeTransport.ts` | PipeServer/PipeClient（UDS + TCP 双模式） |
+| `src/utils/lanBeacon.ts` | UDP multicast beacon + module singleton |
+| `src/utils/ndjsonFramer.ts` | 共享 NDJSON socket 帧解析 |
+| `src/utils/pipeRegistry.ts` | 文件注册表 + `mergeWithLanPeers()` |
+| `src/utils/peerAddress.ts` | 地址解析（uds/bridge/tcp scheme） |
+| `src/utils/pipePermissionRelay.ts` | 权限转发 + `setPipeRelay`/`getPipeRelay` singleton |
+| `src/hooks/usePipeIpc.ts` | 生命周期 hook（从 REPL.tsx 提取） |
+| `src/hooks/usePipeRelay.ts` | 消息回传 hook |
+| `src/hooks/usePipePermissionForward.ts` | 权限转发 hook |
+| `src/hooks/usePipeRouter.ts` | 输入路由 hook |
+| `src/hooks/useMasterMonitor.ts` | slave 注册表 + 消息订阅 |
+
+---
+
+## PipeServer TCP 扩展
+
+`src/utils/pipeTransport.ts`
+
+### 类型
+
+```typescript
+export type PipeTransportMode = 'uds' | 'tcp'
+export type TcpEndpoint = { host: string; port: number }
+export type PipeServerOptions = { enableTcp?: boolean; tcpPort?: number }
+```
+
+### PipeServer 变更
+
+- `setupSocket(socket)` — 从 start() 提取的共享方法，UDS 和 TCP 共用
+- `start(options?)` — 可选启用 TCP，port=0 让 OS 分配
+- 内部维护两个 `net.Server`，共享同一组 `clients: Set<Socket>` 和 `handlers`
+- `tcpAddress` getter 暴露 TCP 端口
+- `close()` 同时关闭两个 server
+
+socket 帧解析使用 `attachNdjsonFramer()` from `ndjsonFramer.ts`（替代原先 3 份重复代码）。
+
+### PipeClient 变更
+
+- 构造函数新增可选 `TcpEndpoint` 参数
+- `connect()` 根据 tcpEndpoint 分派到 `connectTcp()` 或 `connectUds()`
+- TCP 不需要文件存在轮询，直接建连
+
+---
+
+## LAN Beacon
+
+`src/utils/lanBeacon.ts`
+
+### 协议参数
+
+| 参数 | 值 |
+|------|-----|
+| Multicast 组 | `224.0.71.67` |
+| 端口 | `7101` |
+| 广播间隔 | `3000ms` |
+| Peer 超时 | `15000ms` |
+| TTL | `1` |
+
+### Announce 包
+
+```typescript
+type LanAnnounce = {
+  proto: 'claude-pipe-v1'
+  pipeName: string
+  machineId: string
+  hostname: string
+  ip: string
+  tcpPort: number
+  role: 'main' | 'sub'
+  ts: number
+}
+```
+
+### API
+
+```typescript
+class LanBeacon extends EventEmitter {
+  constructor(announce: Omit<LanAnnounce, 'proto' | 'ts'>)
+  start(): void
+  stop(): void
+  getPeers(): Map<string, LanAnnounce>  // 防御性拷贝
+  updateAnnounce(partial): void         // 使用 spread（不可变更新）
+
+  on('peer-discovered', (peer: LanAnnounce) => void)
+  on('peer-lost', (pipeName: string) => void)
+}
+```
+
+### 存储
+
+module-level singleton：`getLanBeacon()` / `setLanBeacon()`。不挂在 Zustand state 上（避免 `setState` 展开时丢失引用）。
+
+### 网卡绑定
+
+`addMembership(group, localIp)` + `setMulticastInterface(localIp)` 指定 LAN 网卡。解决 Windows 上 WSL/Docker 虚拟网卡劫持 multicast 的问题。
+
+---
+
+## Hook 架构
+
+从 REPL.tsx 提取的 ~830 行 Pipe IPC 代码：
+
+### usePipeIpc（生命周期）
+
+`src/hooks/usePipeIpc.ts`（623 行）
+
+在 REPL.tsx 顶层通过 feature-gated require 加载：
+
+```typescript
+const usePipeIpc = feature('UDS_INBOX')
+  ? require('../hooks/usePipeIpc.js').usePipeIpc
+  : () => undefined;
+
+// 组件内
+usePipeIpc({ store, handleIncomingPrompt });
+```
+
+内部使用 **lazy getter** 函数加载依赖（避免循环依赖导致 Bun 运行时崩溃）：
+
+```typescript
+const pt = () => require('../utils/pipeTransport.js')
+const pr = () => require('../utils/pipeRegistry.js')
+const mm = () => require('./useMasterMonitor.js')
+// ...
+```
+
+`import type` 用于静态类型（不会触发模块加载）。
+
+### 四个阶段函数
+
+| 函数 | 职责 |
+|------|------|
+| `initPipeServer` | 角色判定 + server 创建 + beacon 启动 |
+| `registerMessageHandlers` | ping、attach、prompt、permission、detach 五个 handler |
+| `runMainHeartbeat` | cleanup + 发现 + auto-attach + 清理死连接 |
+| `runSubHeartbeat` | 检测 main 是否存活，死亡则接管或独立 |
+
+### usePipeRelay（消息回传）
+
+`src/hooks/usePipeRelay.ts`（38 行）
+
+提供 `relayPipeMessage()` 和 `pipeReturnHadErrorRef`。relay 函数通过 `getPipeRelay()` module singleton 读取（替代 `globalThis.__pipeSendToMaster`）。
+
+### usePipePermissionForward（权限转发）
+
+`src/hooks/usePipePermissionForward.ts`（159 行）
+
+订阅 `subscribePipeEntries()`，处理：
+- `permission_request` → 解析 payload → 查找 tool → 加入确认队列
+- `permission_cancel` → 从队列移除
+- `stream/error/done` → 转为系统消息显示（含 role + IP 标签）
+
+### usePipeRouter（输入路由）
+
+`src/hooks/usePipeRouter.ts`（130 行）
+
+提供 `routeToSelectedPipes(input): boolean`。读取 `selectedPipes` + `routeMode`，逐个发送到已连接目标。通知显示 `[role] hostname/ip`（LAN peer）或 `[role]`（本机）。
+
+---
+
+## Registry 并行探测
+
+`src/utils/pipeRegistry.ts`
+
+### getAliveSubs()
+
+```typescript
+export async function getAliveSubs(): Promise<PipeRegistrySub[]> {
+  const registry = await readRegistry()
+  const results = await Promise.all(
+    registry.subs.map(sub =>
+      isPipeAlive(sub.pipeName, 1000).then(alive => alive ? sub : null)
+    )
+  )
+  return results.filter(Boolean)
+}
+```
+
+### cleanupStaleEntries()
+
+两阶段：
+1. **无锁并行探测**：`Promise.all` 探测 main + 所有 subs
+2. **短暂持锁写入**：`acquireLock()` → 重新读取 → 应用变更 → 写入 → `releaseLock()`
+
+持锁时间从 N 秒降至 ~10ms。
+
+### getMachineId()
+
+Windows/macOS 使用 `execFile`（异步），不阻塞主线程。结果缓存，仅首次调用执行。
+
+---
+
+## NDJSON 协议
+
+### 消息类型
+
+| 类型 | 方向 | 数据 |
+|------|------|------|
+| `ping` / `pong` | 双向 | 无 |
+| `attach_request` | M→S | `meta: { machineId }` |
+| `attach_accept` / `attach_reject` | S→M | `data: reason` |
+| `detach` | M→S | 无 |
+| `prompt` | M→S | `data: prompt_text` |
+| `prompt_ack` | S→M | `data: 'accepted'` |
+| `stream` | S→M | `data: partial_text` |
+| `done` | S→M | 无 |
+| `error` | 双向 | `data: error_message` |
+| `permission_request` | S→M | `data: JSON(PipePermissionRequestPayload)` |
+| `permission_response` | M→S | `data: JSON(PipePermissionResponsePayload)` |
+| `permission_cancel` | M→S | `data: JSON({ requestId, reason })` |
+
+### 帧格式
+
+每行一个 JSON 对象，`\n` 分隔：
+```
+{"type":"ping","from":"cli-abc","ts":"2026-04-11T00:00:00.000Z"}\n
+{"type":"prompt","data":"检查 git status","from":"cli-abc"}\n
+```
+
+---
+
+## 跨机器 Attach 流程
+
+```
+CLI-B (192.168.50.27) 心跳循环
+  → beacon.getPeers() 发现 CLI-A (192.168.50.22)
+  → connectToPipe(pName, myName, 3000, { host: '192.168.50.22', port: 58853 })
+  → PipeClient.connectTcp() → net.createConnection({ host, port })
+  → client.send({ type: 'attach_request', meta: { machineId } })
+  → CLI-A 收到：
+      isLanPeer = (msg.meta.machineId !== myMachineId) → true
+      → 不检查 role，直接 reply({ type: 'attach_accept' })
+      → setPipeRelay(socket.write)
+  → CLI-B 收到 attach_accept
+  → addSlaveClient(pName, client)
+  → store.setState: role='master', slaves[pName] = { status: 'idle' }
+```
+
+关键：跨机器 attach 不要求对方是 sub 角色。通过 `machineId` 区分 LAN peer。
+
+---
+
+## SendMessageTool TCP 支持
+
+`packages/builtin-tools/src/tools/SendMessageTool/SendMessageTool.ts`
+
+- `to` 字段支持 `tcp:host:port` 格式
+- `checkPermissions`：`tcp:` scheme 返回 `behavior: 'ask'`，`classifierApprovable: false`
+- `call()`：创建临时 `PipeClient` → connect → send → disconnect
+
+---
+
+## 测试
+
+| 文件 | 测试数 | 覆盖 |
+|------|--------|------|
+| `lanBeacon.test.ts` | 7 | socket 初始化、announce、peer 发现/过滤/清理 |
+| `peerAddress.test.ts` | 8 | scheme 解析、parseTcpTarget、端口范围验证 |
+| `pipePermissionRelay.test.ts` | 2 | setPipeRelay singleton、权限请求/响应 |
+| `pipeTransport.test.ts` | 2 | UDS 基础行为 |
+| `useMasterMonitor.test.ts` | 5 | slave 注册/移除、事件发射 |
+
+全量：2190 pass / 0 fail
+
+---
+
+## 已知限制
+
+1. **TCP 无认证** — 同 LAN 内知道端口号即可连接
+2. **Beacon 明文广播** — IP/hostname/machineId 未 hash
+3. **单网卡选择** — `getLocalIp()` 返回首个非内部 IPv4，可能选到 VPN
+4. **端口随机** — 每次启动不同端口，依赖 beacon 发现
+5. **SendMessageTool 每次创建新连接** — 未复用已有 slave client
+
+## 后续改进方向
+
+1. HMAC-SHA256 TCP 握手认证
+2. machineId hash 后再广播
+3. 多网卡选择（优先 RFC 1918 地址）
+4. 固定端口范围配置
+5. TLS 加密传输
+6. SendMessageTool 复用已连接的 slave client

docs/features/lan-pipes.md

@@ -0,0 +1,193 @@
+# LAN Pipes — 局域网多机器群控指南
+
+## 什么是 LAN Pipes
+
+LAN Pipes 让多台机器上的 Claude Code 实例通过局域网自动发现并协作。你可以在一台机器（main）上操控其他机器（sub）上的 Claude Code，发送 prompt、查看执行结果、审批权限请求——全程零配置。
+
+基于本机 Pipe IPC（`UDS_INBOX`）扩展，新增 TCP 传输层 + UDP Multicast 发现。
+
+## 前置条件
+
+- 两台或以上机器在同一局域网
+- 每台机器安装了 CCB 并能 `bun run dev`
+- Feature flag `LAN_PIPES`（dev/build 默认开启）
+- 防火墙允许 UDP 7101 + TCP 动态端口（见下方配置）
+
+## 快速开始
+
+### 第一步：配置防火墙
+
+**每台机器都需要执行。**
+
+**Windows**（管理员 PowerShell）：
+```powershell
+New-NetFirewallRule -DisplayName "CCB LAN Beacon (UDP)" -Direction Inbound -Protocol UDP -LocalPort 7101 -Action Allow -Profile Private
+New-NetFirewallRule -DisplayName "CCB LAN Pipes (TCP)" -Direction Inbound -Protocol TCP -LocalPort 1024-65535 -Program (Get-Command bun).Source -Action Allow -Profile Private
+New-NetFirewallRule -DisplayName "CCB LAN Beacon Out (UDP)" -Direction Outbound -Protocol UDP -RemotePort 7101 -Action Allow -Profile Private
+```
+
+验证网络为"专用"（非公共）：`Get-NetConnectionProfile`
+
+**macOS**：
+首次运行时系统弹出"允许接受传入连接"对话框，点击"允许"。
+
+如果使用 pf 防火墙：
+```bash
+echo "pass in proto udp from any to any port 7101" | sudo pfctl -ef -
+```
+
+**Linux**（firewalld）：
+```bash
+sudo firewall-cmd --zone=trusted --add-port=7101/udp --permanent
+sudo firewall-cmd --zone=trusted --add-port=1024-65535/tcp --permanent
+sudo firewall-cmd --reload
+```
+
+**Linux**（iptables）：
+```bash
+sudo iptables -A INPUT -p udp --dport 7101 -j ACCEPT
+sudo iptables -A INPUT -p tcp --dport 1024:65535 -m owner --uid-owner $(id -u) -j ACCEPT
+```
+
+### 第二步：启动
+
+```bash
+# 机器 A（例如 192.168.50.22）
+bun run dev
+
+# 机器 B（例如 192.168.50.27）
+bun run dev
+```
+
+启动后等待 3-5 秒（beacon 广播间隔），两边自动发现并连接。
+
+### 第三步：查看和操作
+
+在任一台机器上：
+```
+/pipes
+```
+
+输出示例：
+```
+pipe: cli-a91bad56 (main) 192.168.50.22  2/3 selected
+
+Main machine: 205d6c3a... (this machine)
+  [main] cli-a91bad56  XC/192.168.50.22  [alive] (you)
+  ☑ [sub-1] cli-da029538  XC/192.168.50.22  [alive] [connected]
+
+LAN Peers:
+  ☐ [main] cli-04d67950  vmwin11/192.168.50.27  tcp:192.168.50.27:58853  [LAN]
+```
+
+### 第四步：选中目标并发送任务
+
+1. 按 `Shift+↓` 展开选择面板
+2. `↑↓` 移动到 LAN peer
+3. `Space` 选中
+4. `Enter` 确认
+5. 输入 prompt，自动路由到远端执行
+
+远端执行结果会流式回传到你的消息列表：
+```
+[main vmwin11/192.168.50.27 / cli-04d67950] 正在检查 git status...
+[main vmwin11/192.168.50.27 / cli-04d67950] Completed
+```
+
+## 完整命令参考
+
+| 命令 | 说明 |
+|------|------|
+| `/pipes` | 显示所有实例（本机 + LAN），Shift+↓ 展开选择面板 |
+| `/pipes select <name>` | 选中某实例 |
+| `/pipes all` | 全选 |
+| `/pipes none` | 取消全选 |
+| `/attach <name>` | 手动 attach（自动识别 LAN peer 并通过 TCP 连接） |
+| `/detach <name>` | 断开连接 |
+| `/send <name> <msg>` | 向指定 pipe 发送消息 |
+| `/send tcp:host:port <msg>` | 直接通过 TCP 地址发送 |
+| `/claim-main` | 强制声明为 main |
+| `/pipe-status` | 显示详细状态 |
+| `/peers` | 列出所有已发现的 peer |
+
+## 快捷键
+
+| 快捷键 | 场景 | 作用 |
+|--------|------|------|
+| `Shift+↓` | 状态栏可见时 | 展开/收起选择面板 |
+| `↑ / ↓` | 面板展开时 | 移动光标 |
+| `Space` | 面板展开时 | 选中/取消 |
+| `Enter` | 面板展开时 | 确认关闭 |
+| `Esc` | 面板展开时 | 取消关闭 |
+| `← / →` | 有选中 pipe 时 | 切换路由模式 |
+| `M` | 面板展开时 | 同 ←/→ 切换路由模式 |
+
+## 路由模式
+
+| 模式 | 显示 | 行为 |
+|------|------|------|
+| `selected pipes only` | 绿色 | prompt 仅发送到选中的 pipe，本地不执行 |
+| `local main` | 灰色 | prompt 仅在本地执行，不转发 |
+
+切换路由模式不会清空选择。
+
+## 权限转发
+
+当远端 slave 执行需要权限的工具（如 BashTool）时：
+1. slave 发送 `permission_request` 到 main
+2. main 弹出权限确认对话框，显示 `[role hostname/ip / pipeName]`
+3. 用户确认/拒绝
+4. 结果发回 slave，继续或中断
+
+## 工作原理
+
+### 发现机制
+
+- 每台机器启动时创建 UDP multicast beacon
+- 组地址 `224.0.71.67`，端口 `7101`，TTL=1（不跨路由器）
+- 每 3 秒广播一次自身信息（pipeName、IP、TCP 端口、角色）
+- 15 秒未收到广播则标记 peer 丢失
+
+### 通信机制
+
+- 本机实例：UDS（Unix Domain Socket / Named Pipe）
+- 跨机器：TCP（动态端口，通过 beacon 发现）
+- 协议：NDJSON（每行一个 JSON 对象）
+- 消息类型：ping/pong、attach/detach、prompt/stream/done/error、permission
+
+### 角色模型
+
+| 角色 | 说明 |
+|------|------|
+| `main` | 首个启动的实例 |
+| `sub` | 同机后续启动的实例 |
+| `master` | attach 了至少一个 slave 的实例 |
+| `slave` | 被 master attach 的实例 |
+
+跨机器 attach 时，两边都可以是 main——不要求对方必须是 sub。
+
+## 常见问题
+
+### 看不到 LAN peer
+
+1. 检查防火墙是否放行 UDP 7101
+2. `Get-NetConnectionProfile`（Windows）确认网络为"专用"
+3. 确认两台机器在同一子网（`ping` 能通）
+4. 路由器未开启 AP 隔离
+
+### 连接超时
+
+1. 检查 TCP 入站防火墙规则
+2. 确认没有 VPN 劫持流量
+3. 尝试 `/send tcp:ip:port hello` 直接测试
+
+### beacon 绑到了错误网卡
+
+Windows 上 WSL/Docker 虚拟网卡可能劫持 multicast。beacon 会自动选择非内部 IPv4 接口。如果选错，检查 `getLocalIp()` 返回值。
+
+## 安全说明
+
+- TCP 连接当前**无认证**——同 LAN 内知道端口号即可连接
+- Multicast TTL=1，不跨路由器
+- AI 通过 `SendMessageTool` 发送 `tcp:` 消息时需**用户显式确认**
+- 建议仅在信任的局域网中使用

docs/features/langfuse-monitoring.md

@@ -0,0 +1,205 @@
+# Langfuse 监控集成
+
+> 实现状态：已完成，通过环境变量启用
+> 依赖：`@langfuse/otel`、`@langfuse/tracing`、`@opentelemetry/sdk-trace-base`
+
+## 一、功能概述
+
+Langfuse 是一个开源的 LLM 可观测性平台，用于追踪、监控和调试 AI 应用的请求链路。CCB 通过 OpenTelemetry (OTel) 桥接层将 Langfuse 集成到查询流程中，实现：
+
+- **LLM 调用追踪** — 记录每次 API 请求的模型、Provider、输入/输出、Token 用量
+- **工具执行追踪** — 记录每个工具调用的名称、输入、输出、耗时和错误
+- **多 Agent 追踪** — 主 Agent 和子 Agent 各自独立的 Trace 链路
+- **数据脱敏** — 自动遮蔽敏感信息（API Key、文件内容、Shell 输出等）
+
+## 二、启用方式
+
+Langfuse 是开源项目，你可以 **自部署**（Docker / Kubernetes），也可以使用官方提供的 **[Langfuse Cloud](https://cloud.langfuse.com)** 免费测试。注册后在 Project Settings → API Keys 页面获取密钥。
+
+核心只需要三个环境变量：
+
+| 环境变量 | 说明 |
+|---------|------|
+| `LANGFUSE_PUBLIC_KEY` | Langfuse 公钥（必填） |
+| `LANGFUSE_SECRET_KEY` | Langfuse 密钥（必填） |
+| `LANGFUSE_BASE_URL` | 服务地址，默认 `https://cloud.langfuse.com`；自部署时改为你的地址（必填） |
+
+未配置时所有追踪函数为 no-op，零开销。
+
+### 通过 settings.json 配置（推荐）
+
+在 `.claude/settings.json` 的 `env` 字段中添加，这样每次启动自动生效：
+
+```json
+{
+  "env": {
+    "LANGFUSE_PUBLIC_KEY": "pk-xxx",
+    "LANGFUSE_SECRET_KEY": "sk-xxx",
+    "LANGFUSE_BASE_URL": "https://cloud.langfuse.com"
+  }
+}
+```
+
+### 其他可选参数
+
+| 环境变量 | 默认值 | 说明 |
+|---------|--------|------|
+| `LANGFUSE_TRACING_ENVIRONMENT` | `development` | 环境标签，用于 Langfuse 面板筛选 |
+| `LANGFUSE_FLUSH_AT` | `20` | 批量发送的 span 数量阈值 |
+| `LANGFUSE_FLUSH_INTERVAL` | `10` | 定时刷新间隔（秒） |
+| `LANGFUSE_EXPORT_MODE` | `batched` | 导出模式：`batched`（批量）或 `immediate`（即时） |
+| `LANGFUSE_TIMEOUT` | `5` | 请求超时（秒） |
+
+## 四、架构
+
+### 4.1 模块结构
+
+```
+src/services/langfuse/
+├── index.ts          # 统一导出
+├── client.ts         # OTel Provider + LangfuseSpanProcessor 初始化
+├── tracing.ts        # Trace/Span 创建、LLM 和工具观察记录
+├── convert.ts        # 内部 Message 类型 → Langfuse OpenAI 兼容格式转换
+└── sanitize.ts       # 数据脱敏（敏感字段、文件路径、工具输出）
+```
+
+### 4.2 追踪层级
+
+```
+Trace (Agent Span)                    ← createTrace() / createSubagentTrace()
+  ├── Generation (LLM 调用)           ← recordLLMObservation()
+  ├── Tool Observation (工具调用)      ← recordToolObservation()
+  ├── Tool Observation (工具调用)      ← recordToolObservation()
+  └── ...
+```
+
+### 4.3 数据流
+
+```
+query.ts  ──→  createTrace()           # 每个 query turn 创建根 trace
+  │
+  ├── claude.ts  ──→  recordLLMObservation()   # API 调用完成后记录 LLM 观察
+  │
+  ├── toolExecution.ts  ──→  recordToolObservation()  # 每个工具执行记录
+  │
+  └── query.ts  ──→  endTrace()         # turn 结束时关闭 trace
+
+runAgent.ts  ──→  createSubagentTrace()  # 子 Agent 有独立 trace
+```
+
+## 五、追踪详情
+
+### 5.1 主 Agent Trace
+
+每次 `query()` 调用（即用户一次对话 turn）创建一个类型为 `agent` 的根 Span：
+
+- **名称**: `agent-run` 或 `agent-run:<querySource>`
+- **元数据**: `provider`、`model`、`agentType: "main"`
+- **Session ID**: 关联到 Langfuse 的 Session 功能，支持按会话聚合
+
+### 5.2 子 Agent Trace
+
+通过 `AgentTool` 启动的子 Agent 创建独立 Trace：
+
+- **名称**: `agent:<agentType>`
+- **元数据**: `provider`、`model`、`agentType`、`agentId`
+- 独立于主 Trace，有自己的 Session 关联
+
+### 5.3 LLM Generation
+
+每次 API 调用记录为一个 `generation` 类型的 Span：
+
+- **名称**: 按 Provider 映射（如 `ChatAnthropic`、`ChatOpenAI`、`ChatBedrockAnthropic` 等）
+- **记录内容**: 输入消息、输出消息、Token 用量（input/output）
+- **时间**: 精确记录 `startTime`、`endTime`、`completionStartTime`（TTFT 指标）
+
+Provider 名称映射：
+
+| Provider | Generation 名称 |
+|----------|-----------------|
+| `firstParty` | `ChatAnthropic` |
+| `bedrock` | `ChatBedrockAnthropic` |
+| `vertex` | `ChatVertexAnthropic` |
+| `foundry` | `ChatFoundry` |
+| `openai` | `ChatOpenAI` |
+| `gemini` | `ChatGoogleGenerativeAI` |
+| `grok` | `ChatXAI` |
+
+### 5.4 工具执行
+
+每个工具调用记录为一个 `tool` 类型的 Span：
+
+- **名称**: 工具名（如 `FileEditTool`、`BashTool`）
+- **记录内容**: 输入（经脱敏）、输出（经脱敏）、`toolUseId`
+- **错误标记**: `isError` 标志 + `level: ERROR`
+
+## 六、数据脱敏
+
+所有上传到 Langfuse 的数据都会经过脱敏处理（`sanitize.ts`），确保敏感信息不会泄露：
+
+### 6.1 全局脱敏（`sanitizeGlobal`）
+
+- **Home 路径替换** — `/Users/xxx` → `~`
+- **敏感字段遮蔽** — 匹配 `api_key`、`token`、`secret`、`password`、`credential`、`auth_header` 等关键字的字段值替换为 `[REDACTED]`
+
+### 6.2 工具输入脱敏（`sanitizeToolInput`）
+
+- 敏感字段遮蔽（同全局）
+- `file_path`、`path`、`directory` 路径中的 Home 目录替换
+
+### 6.3 工具输出脱敏（`sanitizeToolOutput`）
+
+| 工具 | 脱敏策略 |
+|------|---------|
+| `FileReadTool`、`FileWriteTool`、`FileEditTool` | 完全遮蔽，仅保留字符数：`[file content redacted, N chars]` |
+| `BashTool`、`PowerShellTool` | 截断至 500 字符 |
+| `ConfigTool`、`MCPTool` | 完全遮蔽 |
+| 其他工具 | 原样保留 |
+
+## 七、消息格式转换
+
+`convert.ts` 将 CCB 内部的 Message 类型转换为 Langfuse 期望的 OpenAI 兼容格式：
+
+- **输入**: `UserMessage | AssistantMessage[]` + 可选 system prompt → `{ role, content }[]`
+- **输出**: `AssistantMessage[]` → `{ role: 'assistant', content }`
+- **Content Block 映射**:
+  - `text` → `{ type: 'text', text }`
+  - `thinking` / `redacted_thinking` → `{ type: 'thinking', thinking }`
+  - `tool_use` → `{ type: 'tool_use', id, name, input }`
+  - `tool_result` → `{ type: 'tool_result', tool_use_id, content }`
+  - `image` / `document` → 占位标记 `[image]` / `[document: name]`
+
+## 八、生命周期
+
+1. **初始化** — `initLangfuse()` 在 `src/entrypoints/init.ts` 启动时调用，创建 `LangfuseSpanProcessor` 和 `BasicTracerProvider`
+2. **运行时** — 各追踪函数通过 `isLangfuseEnabled()` 检查，未配置时直接返回 `null`/跳过
+3. **关闭** — `shutdownLangfuse()` 在进程退出时调用，强制 flush 并关闭 Processor
+
+## 九、自部署 Langfuse
+
+Langfuse 是开源项目，支持 Docker / Kubernetes 自部署：
+
+```bash
+docker run -d \
+  --name langfuse \
+  -p 3000:3000 \
+  -e DATABASE_URL=postgresql://... \
+  langfuse/langfuse:latest
+```
+
+自部署后，将 `LANGFUSE_BASE_URL` 指向你的实例地址即可。详见 [Langfuse 自部署文档](https://langfuse.com/docs/deployment/self-host)。
+
+如果没有自部署需求，可以直接使用 [Langfuse Cloud](https://cloud.langfuse.com)，提供免费额度可用于测试。
+
+## 十、相关文件
+
+| 文件 | 说明 |
+|------|------|
+| `src/services/langfuse/client.ts` | OTel Provider 初始化、生命周期管理 |
+| `src/services/langfuse/tracing.ts` | Trace/Span 创建和观察记录 |
+| `src/services/langfuse/convert.ts` | Message 格式转换 |
+| `src/services/langfuse/sanitize.ts` | 数据脱敏 |
+| `src/services/langfuse/__tests__/langfuse.test.ts` | 测试（568 行） |
+| `src/query.ts` | 主查询流程中的 Trace 集成 |
+| `src/services/tools/toolExecution.ts` | 工具执行中的观察记录 |
+| `packages/builtin-tools/src/tools/AgentTool/runAgent.ts` | 子 Agent Trace 创建 |

docs/features/mcp-skills.md

@@ -41,7 +41,7 @@ getMcpSkillCommands() 过滤 → SkillTool 调用
 
 ### 2.2 技能筛选
 
-文件：`src/commands.ts:547-558`
+文件：`src/commands.ts:604-616`
 
 `getMcpSkillCommands(mcpCommands)` 过滤条件：
 
@@ -54,7 +54,7 @@ feature('MCP_SKILLS')                  // feature flag 必须开启
 
 ### 2.3 条件加载
 
-文件：`src/services/mcp/client.ts:117-121`
+文件：`src/services/mcp/client.ts:129-133`
 
 `fetchMcpSkillsForClient` 通过 `require()` 条件加载，feature flag 关闭时不加载任何模块：
 
@@ -79,8 +79,8 @@ const fetchMcpSkillsForClient = feature('MCP_SKILLS')
 
 | 文件 | 行 | 说明 |
 |------|------|------|
-| `src/commands.ts` | 547-558, 561-608 | 命令过滤和 SkillTool 命令收集 |
-| `src/services/mcp/client.ts` | 117-121, 1394, 1672, 2173-2181, 2346-2358 | 技能获取、缓存清除、连接时获取 |
+| `src/commands.ts` | 604-616, 620-633 | 命令过滤和 SkillTool 命令收集 |
+| `src/services/mcp/client.ts` | 129-133, 1394, 1672, 2176 | 技能获取、缓存清除、连接时获取 |
 | `src/services/mcp/useManageMCPConnections.ts` | 22-26, 682-740 | 实时刷新（prompts/resources 变化） |
 
 ## 三、关键设计决策

docs/features/pipes-and-lan.md

@@ -0,0 +1,342 @@
+# Pipes + LAN Pipes 完整功能指南
+
+## 概述
+
+Pipes 系统提供 Claude Code CLI 实例之间的通讯能力，分两层：
+
+1. **Pipes（本机）**：同一台机器上的多个 CLI 实例通过 UDS（Unix Domain Socket / Windows Named Pipe）协作
+2. **LAN Pipes（局域网）**：不同机器上的 CLI 实例通过 TCP + UDP Multicast 协作
+
+两层使用同一套协议（NDJSON）和同一套命令（`/pipes`、`/attach`、`/send` 等），对用户透明。
+
+## Feature Flags
+
+| Flag | 控制范围 | 默认 |
+|------|----------|------|
+| `UDS_INBOX` | 本机 Pipe IPC 全部功能 | dev/build 启用 |
+| `LAN_PIPES` | 局域网 TCP + beacon 扩展 | dev/build 启用 |
+
+手动启用：`FEATURE_UDS_INBOX=1 FEATURE_LAN_PIPES=1 bun run dev`
+
+## 快速上手
+
+### 本机多实例
+
+```bash
+# 终端 1
+bun run dev
+# 启动后自动注册为 main
+
+# 终端 2
+bun run dev
+# 自动注册为 sub-1，被 main 自动 attach
+```
+
+在终端 1 中输入 `/pipes`，可以看到两个实例。选中 sub-1 后，输入的消息会自动转发到 sub-1 执行。
+
+### 局域网多机器
+
+```bash
+# 机器 A (192.168.50.22)
+bun run dev
+
+# 机器 B (192.168.50.27)
+bun run dev
+```
+
+两边启动后等 3-5 秒（beacon 广播间隔），LAN peers 会自动发现并 attach。输入 `/pipes` 可看到标记 `[LAN]` 的远端实例。
+
+### 防火墙配置（两台机器都需要）
+
+**Windows**（管理员 PowerShell）：
+```powershell
+New-NetFirewallRule -DisplayName "Claude Code LAN Beacon (UDP)" -Direction Inbound -Protocol UDP -LocalPort 7101 -Action Allow -Profile Private
+New-NetFirewallRule -DisplayName "Claude Code LAN Pipes (TCP)" -Direction Inbound -Protocol TCP -LocalPort 1024-65535 -Program (Get-Command bun).Source -Action Allow -Profile Private
+New-NetFirewallRule -DisplayName "Claude Code LAN Beacon Out (UDP)" -Direction Outbound -Protocol UDP -RemotePort 7101 -Action Allow -Profile Private
+# 确认网络为"专用"：Get-NetConnectionProfile
+```
+
+**macOS**（首次运行时系统弹出对话框，点击"允许"即可）：
+```bash
+# 如果需要手动放行 pf 防火墙：
+echo "pass in proto udp from any to any port 7101" | sudo pfctl -ef -
+```
+
+**Linux**（firewalld / iptables）：
+```bash
+# firewalld
+sudo firewall-cmd --zone=trusted --add-port=7101/udp --permanent
+sudo firewall-cmd --zone=trusted --add-port=1024-65535/tcp --permanent
+sudo firewall-cmd --reload
+
+# 或 iptables
+sudo iptables -A INPUT -p udp --dport 7101 -j ACCEPT
+sudo iptables -A INPUT -p tcp --dport 1024:65535 -m owner --uid-owner $(id -u) -j ACCEPT
+```
+
+确认：网络为局域网（非公共 WiFi），路由器未开启 AP 隔离。
+
+## 交互面板与快捷键
+
+### 状态栏
+
+执行 `/pipes` 后，输入框底部出现 pipe 状态栏（单行）：
+
+```
+pipe: cli-a91bad56 (main) 192.168.50.22  2/3 selected  selected pipes only · ←/→ or m switch · Shift+↓ edit
+```
+
+状态栏始终可见（直到会话结束），显示：当前 pipe 名、角色、IP、已选数/总数、路由模式。
+
+### 展开选择面板
+
+按 **Shift+↓**（Shift + 下箭头）展开选择面板：
+
+```
+pipe: cli-a91bad56 (main) 192.168.50.22  ↑↓ move Space select ←/→ or m route Enter/Esc close Shift+↓ toggle
+  当前普通 prompt 走 已选 sub；切换不会清空选择
+  ☑ cli-da029538 (sub-1 XC/192.168.50.22)
+  ☐ cli-04d67950 (main vmwin11/192.168.50.27)
+  ☑ cli-893747d3 [offline] (sub-2 vmwin11/192.168.50.27)
+```
+
+### 面板内快捷键
+
+| 快捷键 | 场景 | 作用 |
+|--------|------|------|
+| **Shift+↓** | 状态栏可见时 | 展开/收起选择面板 |
+| **↑ / ↓** | 面板展开时 | 上下移动光标 |
+| **Space** | 面板展开时 | 切换当前光标所在 pipe 的选中状态（☑ ↔ ☐） |
+| **Enter** | 面板展开时 | 确认并关闭面板 |
+| **Esc** | 面板展开时 | 取消并关闭面板 |
+| **← / → 或 M** | 状态栏可见且有选中 pipe 时 | 切换路由模式（`selected pipes only` ↔ `local main`） |
+
+### M 键 — 路由模式切换
+
+M 键（或 ← / →）用于在两种路由模式之间切换，**无需展开面板**：
+
+| 模式 | 状态栏显示 | 行为 |
+|------|-----------|------|
+| `selected pipes only` | 绿色高亮 | 输入的 prompt **仅**发送到选中的 pipe，本地不执行 |
+| `local main` | 灰色 | 输入的 prompt 在**本地 main** 执行，不转发到任何 pipe |
+
+切换路由模式**不会清空选择**。你可以在 `local main` 模式下保持选择，随时按 M 切回 `selected pipes only` 继续向远端发送。
+
+### 完整操作流程示例
+
+```
+1. 输入 /pipes                     → 状态栏出现，显示发现的实例
+2. 按 Shift+↓                      → 展开选择面板
+3. 按 ↓ 移动到目标 pipe             → 光标移到 cli-04d67950
+4. 按 Space                        → 选中 ☑ cli-04d67950
+5. 按 Enter                        → 确认，面板收起
+6. 输入 "帮我检查 git status"       → prompt 自动发送到 cli-04d67950 执行
+7. 按 M                            → 切换到 local main 模式
+8. 输入 "本地做点什么"              → 仅在本地执行
+9. 按 M                            → 切回 selected pipes only
+10. 输入 "继续远端任务"             → 又发送到 cli-04d67950
+```
+
+## 命令参考
+
+### /pipes
+
+显示所有发现的实例，管理选择状态。再次执行 `/pipes` 切换面板展开/收起。
+
+```
+/pipes                    — 显示所有实例 + 切换选择面板
+/pipes select <name>      — 选中某实例（消息会广播到它）
+/pipes deselect <name>    — 取消选中
+/pipes all                — 全选
+/pipes none               — 全部取消
+```
+
+输出示例：
+```
+Your pipe:   cli-a91bad56
+Role:        main
+Machine ID:  205d6c3a...
+IP:          192.168.50.22
+Host:        XC
+
+Main machine: 205d6c3a... (this machine)
+  [main] cli-a91bad56  XC/192.168.50.22  [alive] (you)
+  ☑ [sub-1] cli-da029538  XC/192.168.50.22  [alive] [connected]
+
+LAN Peers:
+  ☐ [main] cli-04d67950  vmwin11/192.168.50.27  tcp:192.168.50.27:58853  [LAN]
+
+Selected: cli-da029538
+```
+
+### /attach <name>
+
+手动 attach 到一个实例，使其成为你的 slave。
+
+```
+/attach cli-04d67950      — 连接到指定 pipe（自动解析 LAN TCP 端点）
+```
+
+attach 后，对方变为 slave，你变为 master。可以向它发送 prompt。通常不需要手动 attach——heartbeat 会自动发现并连接。
+
+### /detach <name>
+
+断开与某个 slave 的连接。
+
+```
+/detach cli-04d67950
+```
+
+### /send <name> <message>
+
+向指定 pipe 发送消息（不依赖选择状态，直接指定目标）。
+
+```
+/send cli-04d67950 请帮我检查一下日志
+/send tcp:192.168.50.27:58853 hello    — 直接通过 TCP 地址发送
+```
+
+### /claim-main
+
+强制声明当前机器为 main（用于 main 意外退出后的恢复）。
+
+## 消息路由
+
+### 选中 pipe 后的自动路由
+
+1. 通过 `/pipes select` 或 Shift+Down 面板选中一个或多个 pipe
+2. 在输入框中正常输入消息
+3. 消息自动发送到所有选中的已连接 pipe
+4. 每个 pipe 独立执行，结果流式回传到 main 的消息列表
+
+### 路由模式
+
+| 模式 | 行为 |
+|------|------|
+| `selected`（默认） | 消息发送到选中的 pipe |
+| `local` | 消息仅在本地执行，不转发 |
+
+## 架构
+
+### 通信协议
+
+所有通讯使用 NDJSON（Newline-Delimited JSON），每行一个消息：
+
+```json
+{"type":"ping","from":"cli-abc","ts":"2026-04-11T00:00:00.000Z"}
+{"type":"prompt","data":"帮我查看 git status","from":"cli-abc","ts":"..."}
+{"type":"stream","data":"正在执行...","from":"cli-def","ts":"..."}
+{"type":"done","data":"","from":"cli-def","ts":"..."}
+```
+
+### 消息类型
+
+| 类型 | 方向 | 说明 |
+|------|------|------|
+| `ping`/`pong` | 双向 | 健康检查 |
+| `attach_request`/`accept`/`reject` | M→S/S→M | 连接控制 |
+| `detach` | M→S | 断开连接 |
+| `prompt` | M→S | 主向从发送 prompt |
+| `prompt_ack` | S→M | 从确认接收 |
+| `stream` | S→M | 从流式回传 AI 输出 |
+| `tool_start`/`tool_result` | S→M | 工具执行通知 |
+| `done` | S→M | 本轮完成 |
+| `error` | 双向 | 错误通知 |
+| `permission_request`/`response`/`cancel` | 双向 | 权限审批转发 |
+
+### 传输层
+
+```
+                  本机                          LAN
+            ┌──────────────┐            ┌──────────────┐
+            │  PipeServer  │            │  PipeServer  │
+            │   UDS sock   │            │   UDS sock   │
+            │   TCP :rand  │◄───TCP───►│   TCP :rand  │
+            ├──────────────┤            ├──────────────┤
+            │  LanBeacon   │◄──UDP────►│  LanBeacon   │
+            │  224.0.71.67 │  mcast     │  224.0.71.67 │
+            └──────────────┘            └──────────────┘
+```
+
+- **UDS**：本机实例间通讯，通过文件系统路径寻址（`~/.claude/pipes/cli-xxx.sock`）
+- **TCP**：LAN 实例间通讯，动态端口，通过 beacon 发现
+- **UDP Multicast**：peer 发现，3 秒广播一次 announce 包
+
+### 角色模型
+
+| 角色 | 说明 |
+|------|------|
+| `main` | 首个启动的实例，管理 registry |
+| `sub` | 后续启动的同机实例（或被 attach 的 LAN 实例） |
+| `master` | attach 了至少一个 slave 的实例 |
+| `slave` | 被 master attach 控制的实例 |
+
+角色转换：
+- 首个启动 → `main`
+- 同机后续启动 → `sub`（自动被 main attach → `slave`）
+- LAN 发现 → 两边都是 `main`，heartbeat 自动互相 attach
+- 被 attach → 变为 `slave`（可通过 `/detach` 恢复）
+
+### 发现机制
+
+**本机**：通过 `~/.claude/pipes/registry.json` 文件（带文件锁），`machineId` 绑定主机身份。
+
+**LAN**：通过 UDP multicast beacon：
+1. 每 3 秒广播 `{ proto, pipeName, machineId, ip, tcpPort, role }`
+2. 收到其他实例的 announce → 记入 peers Map
+3. 15 秒未收到 → 标记 peer lost
+4. Heartbeat 合并 local registry + beacon peers → 统一 attach 目标列表
+
+### Heartbeat 循环（5 秒间隔）
+
+```
+main/master 角色:
+  1. cleanupStaleEntries()        — 清理 registry 中死掉的条目
+  2. getAliveSubs()               — 获取存活的本地 subs
+  3. refreshDiscoveredPipes()     — 刷新 discoveredPipes（包含 LAN peers）
+  4. 合并 LAN peers 到 state
+  5. 构建统一 attach 目标列表     — 本地 subs + LAN peers
+  6. 遍历未连接的目标 → 自动 attach
+  7. 清理断开的 slave 连接        — 同时检查 local registry 和 beacon
+
+sub 角色:
+  1. 检测 main 是否存活
+  2. main 死亡 → 同机则接管 main 角色，跨机则独立
+```
+
+## 关键文件
+
+| 文件 | 职责 |
+|------|------|
+| `src/utils/pipeTransport.ts` | PipeServer（双模 UDS+TCP）、PipeClient、类型定义 |
+| `src/utils/lanBeacon.ts` | UDP multicast beacon、singleton 管理 |
+| `src/utils/pipeRegistry.ts` | Registry CRUD、角色判定、machineId、LAN merge |
+| `src/utils/peerAddress.ts` | 地址解析（uds:/bridge:/tcp: scheme） |
+| `src/screens/REPL.tsx` | Bootstrap、heartbeat、cleanup、prompt 路由 |
+| `src/hooks/useMasterMonitor.ts` | Slave client registry、消息订阅 |
+| `src/hooks/useSlaveNotifications.ts` | Slave 端通知处理 |
+| `src/commands/pipes/pipes.ts` | /pipes 命令 |
+| `src/commands/attach/attach.ts` | /attach 命令 |
+| `src/commands/send/send.ts` | /send 命令 |
+| `packages/builtin-tools/src/tools/SendMessageTool/SendMessageTool.ts` | AI 发消息工具（含 tcp: 支持） |
+
+## 后续优化方向
+
+### 安全（P0）
+
+1. **TCP 认证**：首次连接时交换 HMAC-SHA256 token（基于 machineId + session secret），防止未授权设备连接
+2. **JSON schema 验证**：在所有 `JSON.parse` 入口点增加 Zod 校验，防止 prototype pollution
+3. **Beacon 信息脱敏**：hash machineId 后再广播，不暴露硬件序列号
+
+### 可靠性（P1）
+
+4. **多网卡选择**：`getLocalIp()` 应优先选择 RFC 1918 地址，排除 VPN/Docker 接口
+5. **TCP target 验证**：`parseTcpTarget()` 应限制目标为已知 beacon peers 或 RFC 1918 范围
+6. **PipeServer close()**：改为 `Promise.allSettled` 并行关闭 UDS + TCP，加 `_closing` guard
+
+### 功能（P2）
+
+7. **mDNS/DNS-SD**：作为 multicast 受限环境下的 beacon 替代方案
+8. **固定端口配置**：允许用户指定 TCP 端口范围，便于防火墙精确配置
+9. **TLS 加密**：TCP 传输加密，防中间人窃听
+10. **双向 prompt**：当前只有 master → slave 方向，可考虑 slave 主动向 master 发送结果/请求

docs/features/proactive.md

@@ -1,7 +1,7 @@
 # PROACTIVE — 主动模式
 
 > Feature Flag: `FEATURE_PROACTIVE=1`（与 `FEATURE_KAIROS=1` 共享功能）
-> 实现状态：核心模块全部 Stub，布线完整
+> 实现状态：核心循环与 SleepTool 已落地，部分外围文档仍在补齐
 > 引用数：37
 
 ## 一、功能概述
@@ -21,13 +21,13 @@ PROACTIVE 实现 Tick 驱动的自主代理。CLI 在用户不输入时也能持
 
 | 模块 | 文件 | 状态 | 说明 |
 |------|------|------|------|
-| 核心逻辑 | `src/proactive/index.ts` | **Stub** | `activateProactive()`、`deactivateProactive()`、`isProactiveActive() => false` |
+| 核心逻辑 | `src/proactive/index.ts` | **已实现** | `activateProactive()`、`deactivateProactive()`、`pause/resume`、`nextTickAt` 调度状态 |
 | SleepTool 提示 | `src/tools/SleepTool/prompt.ts` | **完整** | 工具提示定义（工具名：`Sleep`） |
 | 命令注册 | `src/commands.ts:62-65` | **布线** | 动态加载 `./commands/proactive.js` |
 | 工具注册 | `src/tools.ts:26-28` | **布线** | SleepTool 动态加载 |
-| REPL 集成 | `src/screens/REPL.tsx` | **布线** | tick 驱动逻辑、占位符、页脚 UI |
-| 系统提示 | `src/constants/prompts.ts:860-914` | **完整** | 自主工作行为指令（~55 行详细 prompt） |
-| 会话存储 | `src/utils/sessionStorage.ts:4892-4912` | **布线** | tick 消息注入对话流 |
+| REPL 集成 | `src/screens/REPL.tsx` | **已实现** | tick 驱动、standby/sleeping 状态、页脚与 bridge automation metadata 上报 |
+| 系统提示 | `src/constants/prompts.ts:864-918` | **完整** | 自主工作行为指令（~55 行详细 prompt） |
+| 远控状态镜像 | `src/utils/sessionState.ts` | **已实现** | 向 remote-control/CCR 暴露 `automation_state` 元数据 |
 
 ### 2.2 系统提示内容
 
@@ -46,7 +46,7 @@ PROACTIVE 实现 Tick 驱动的自主代理。CLI 在用户不输入时也能持
 ### 2.3 数据流
 
 ```
-activateProactive() [需要实现]
+activateProactive()
       │
       ▼
 Tick 调度器启动
@@ -62,20 +62,22 @@ Tick 调度器启动
       └── 无事可做 → 必须调用 SleepTool
       │
       ▼
-SleepTool 等待 [需要实现]
+SleepTool 等待
+      │
+      ├── 用户插入新工作 / 队列中有命令 → 立即唤醒
+      ├── proactive 被关闭 → 立即中断
+      └── 进入休眠时向远端 surfaces 上报 `automation_state = sleeping`
       │
       ▼
 下一个 tick 到达
 ```
 
-## 三、需要补全的内容
+## 三、当前行为补充
 
-| 优先级 | 模块 | 工作量 | 说明 |
-|--------|------|--------|------|
-| 1 | `src/proactive/index.ts` | 中 | Tick 调度器、activate/deactivate 状态机、pause/resume |
-| 2 | `src/tools/SleepTool/SleepTool.ts` | 小 | 工具执行（等待指定时间后触发 tick） |
-| 3 | `src/commands/proactive.js` | 小 | `/proactive` 斜杠命令处理器 |
-| 4 | `src/hooks/useProactive.ts` | 中 | React hook（REPL 引用但不存在） |
+- `standby`：proactive 已开启，当前没有执行中的 turn，且已调度下一个 tick。
+- `sleeping`：模型显式调用 `SleepTool` 进入等待窗口。
+- remote-control/CCR 通过 `external_metadata.automation_state` 接收这两个状态，用于 Web UI 的 Autopilot 状态显示。
+- `SleepTool` 现在不是纯定时器；它会在共享命令队列出现新工作时提前醒来。
 
 ## 四、关键设计决策
 
@@ -101,9 +103,11 @@ FEATURE_PROACTIVE=1 FEATURE_KAIROS=1 FEATURE_KAIROS_BRIEF=1 bun run dev
 
 | 文件 | 职责 |
 |------|------|
-| `src/proactive/index.ts` | 核心逻辑（stub） |
+| `src/proactive/index.ts` | 核心逻辑与 next-tick 状态 |
 | `src/tools/SleepTool/prompt.ts` | SleepTool 工具提示 |
-| `src/constants/prompts.ts:860-914` | 自主工作系统提示 |
-| `src/screens/REPL.tsx` | REPL tick 集成 |
+| `src/tools/SleepTool/SleepTool.ts` | 休眠/唤醒执行逻辑 |
+| `src/constants/prompts.ts:864-918` | 自主工作系统提示 |
+| `src/screens/REPL.tsx` | REPL tick 集成与 automation 状态上报 |
 | `src/utils/sessionStorage.ts:4892-4912` | Tick 消息注入 |
+| `src/utils/sessionState.ts` | bridge/CCR metadata 镜像 |
 | `src/components/PromptInput/PromptInputFooterLeftSide.tsx` | 页脚 UI 状态 |

docs/features/remote-control-self-hosting.md

@@ -0,0 +1,352 @@
+# Remote Control Server 私有化部署指南
+
+本指南说明如何将 Remote Control Server (RCS) 部署到私有环境，并通过 Claude Code CLI 连接使用。
+
+## 架构概览
+
+```
+┌──────────────────┐                    ┌──────────────────────┐
+│  Claude Code CLI  │ ◄── HTTP/SSE/WS ─►│  Remote Control      │
+│  (Bridge Worker)  │     长轮询 + 心跳   │  Server (RCS)        │
+└──────────────────┘                    │                      │
+                                        │  ┌──────────────┐    │
+┌──────────────────┐   HTTP/SSE        │  │ In-Memory    │    │
+│  Web UI 控制面板  │ ◄─────────────── │  │ Store        │    │
+│  (/code/*)       │                   │  └──────────────┘    │
+│  (React + Vite)  │                   │  ┌──────────────┐    │
+└──────────────────┘                   │  │ JWT Auth     │    │
+                                       │  └──────────────┘    │
+┌──────────────────┐                   │  ┌──────────────┐    │
+│  acp-link        │ ◄── ACP Relay ─── │  │ ACP Handler  │    │
+│  + ACP Agent     │     WebSocket      │  └──────────────┘    │
+└──────────────────┘                   └──────────────────────┘
+```
+
+**RCS 是一个纯内存的中间服务**，它的职责是：
+- 接收 Claude Code CLI 的环境注册和工作轮询
+- 接收 acp-link 的 ACP agent 注册，支持 WebSocket relay 桥接
+- 提供 Web UI 供操作者远程监控和审批
+- 通过 WebSocket/SSE 双向传输消息
+- 管理会话、环境、权限请求
+- 提供 ACP SSE event stream 供外部消费者订阅 channel group 事件
+
+## 前置条件
+
+- 一台可被 Claude Code CLI 和 Web 浏览器同时访问的服务器（物理机、VM、容器均可）
+- [Docker](https://www.docker.com/)
+- 启用 `BRIDGE_MODE` feature flag 的 Claude Code 构建
+
+## 部署
+
+### 构建 Docker 镜像
+
+在项目根目录执行：
+
+```bash
+docker build -t rcs:latest -f packages/remote-control-server/Dockerfile .
+```
+
+### 启动容器
+
+```bash
+docker run -d \
+  --name rcs \
+  -p 3000:3000 \
+  -e RCS_API_KEYS=sk-rcs-your-secret-key-here \
+  -e RCS_BASE_URL=https://rcs.example.com \
+  -v rcs-data:/app/data \
+  --restart unless-stopped \
+  rcs:latest
+```
+
+### Docker Compose
+
+```yaml
+version: "3.8"
+services:
+  rcs:
+    build:
+      context: .
+      dockerfile: packages/remote-control-server/Dockerfile
+      args:
+        VERSION: "0.1.0"
+    ports:
+      - "3000:3000"
+    environment:
+      - RCS_API_KEYS=sk-rcs-your-secret-key-here
+      - RCS_BASE_URL=https://rcs.example.com
+    volumes:
+      - rcs-data:/app/data
+    restart: unless-stopped
+
+volumes:
+  rcs-data:
+```
+
+启动：
+
+```bash
+docker compose up -d
+```
+
+## 环境变量参考
+
+### 服务器端
+
+| 变量 | 必填 | 默认值 | 说明 |
+|------|------|--------|------|
+| `RCS_API_KEYS` | **是** | _(空)_ | API 密钥列表，逗号分隔。用于客户端认证和 JWT 签名。**务必设置强密钥** |
+| `RCS_PORT` | 否 | `3000` | 服务监听端口 |
+| `RCS_HOST` | 否 | `0.0.0.0` | 服务监听地址 |
+| `RCS_BASE_URL` | 否 | `http://localhost:3000` | 外部访问 URL。用于生成 WebSocket 连接地址，必须与客户端实际访问的地址一致 |
+| `RCS_VERSION` | 否 | `0.1.0` | 版本号，显示在 `/health` 响应中 |
+| `RCS_POLL_TIMEOUT` | 否 | `8` | V1 工作轮询超时（秒） |
+| `RCS_HEARTBEAT_INTERVAL` | 否 | `20` | 心跳间隔（秒） |
+| `RCS_JWT_EXPIRES_IN` | 否 | `3600` | JWT 令牌有效期（秒） |
+| `RCS_DISCONNECT_TIMEOUT` | 否 | `300` | 断线判定超时（秒） |
+| `RCS_WS_IDLE_TIMEOUT` | 否 | `30` | WebSocket 空闲超时（秒），Bun 发送协议级 ping |
+| `RCS_WS_KEEPALIVE_INTERVAL` | 否 | `20` | 服务端→客户端 keep_alive 帧间隔（秒），防止反向代理关闭空闲连接 |
+
+### 客户端（Claude Code CLI）
+
+| 变量 | 必填 | 说明 |
+|------|------|------|
+| `CLAUDE_BRIDGE_BASE_URL` | **是** | RCS 服务器地址，例如 `https://rcs.example.com`。设置此变量即启用自托管模式，跳过 GrowthBook 门控 |
+| `CLAUDE_BRIDGE_OAUTH_TOKEN` | **是** | 认证令牌，必须与服务器端 `RCS_API_KEYS` 中的某个值匹配 |
+| `CLAUDE_BRIDGE_SESSION_INGRESS_URL` | 否 | WebSocket 入口地址（默认与 `CLAUDE_BRIDGE_BASE_URL` 相同） |
+| `CLAUDE_CODE_REMOTE` | 否 | 设为 `1` 时标记为远程执行模式 |
+
+## Claude Code 客户端连接
+
+### 1. 设置环境变量
+
+在运行 Claude Code 的机器上设置：
+
+```bash
+export CLAUDE_BRIDGE_BASE_URL="https://rcs.example.com"
+export CLAUDE_BRIDGE_OAUTH_TOKEN="sk-rcs-your-secret-key-here"
+```
+
+### 2. 启动 Claude Code
+
+```bash
+# 使用 dev 模式（BRIDGE_MODE 默认启用）
+bun run dev
+
+# 或使用构建产物
+bun run dist/cli.js
+```
+
+### 3. 执行 /remote-control 命令
+
+在 Claude Code 的 REPL 中输入：
+
+```
+/remote-control
+```
+
+环境型 Remote Control（例如 `claude remote-control` 子命令）会向 RCS 注册环境，注册成功后在终端显示连接 URL：
+
+```
+https://rcs.example.com/code?bridge=<environmentId>
+```
+
+交互式 REPL 方式（`--remote-control` 或 `/remote-control`）在某些桥接模式下也可能直接给出会话 URL：
+
+```
+https://rcs.example.com/code/session_<id>
+```
+
+两种 URL 都可以直接在浏览器打开并远程操控当前会话；只有 environment 模式才会出现在 Web UI 的环境列表中。
+
+若已连接，再次执行 `/remote-control` 会显示对话框，包含以下选项：
+- **Disconnect this session** — 断开远程连接
+- **Show QR code** — 显示/隐藏二维码
+- **Continue** — 保持连接，继续使用
+
+也可通过 CLI 参数直接启动：
+
+```bash
+claude remote-control
+# 或简写
+claude rc
+# 或
+claude bridge
+```
+
+## Web UI 控制面板
+
+通过 `/remote-control` 命令获取 URL 后，在浏览器打开即可使用。
+
+### 技术栈（v2，2026-04-18 重构）
+
+Web UI 已从原生 JS 重构为 **React + Vite + Radix UI**：
+
+- **框架**: React 19 + Vite 构建，TypeScript
+- **UI 组件**: Radix UI primitives（Dialog、Tabs、Select、Popover 等）
+- **聊天组件**: 完整的 ACP 聊天界面，支持 Plan 可视化、工具调用展示、权限审批
+- **AI Elements**: 独立的 AI 交互组件库（message、reasoning、tool、code-block、prompt-input 等）
+- **ACP 直连**: 支持 QR 码扫描自动跳转 ACP 直连视图（`ACPDirectView`）
+- **主题系统**: 暗色/亮色主题切换，遵循 Impeccable 设计系统
+
+### 功能
+
+- 查看已注册的运行环境（environment 模式），区分 ACP Agent 和 Claude Code 类型
+- 创建和管理会话
+- 实时查看对话消息和工具调用
+- 查看 Autopilot 状态（`standby` / `sleeping`）和自动运行指示
+- 查看 authoritative task snapshots 驱动的 Tasks 面板
+- 审批 Claude Code 的工具权限请求
+- 权限模式选择器（6 种模式：默认/自动接受编辑/跳过权限/规划/不询问/自动判断）
+- 模型选择器（可选可用模型）
+- Plan 可视化（进度条、状态图标、优先级标签）
+- ACP QR 扫描自动跳转到 ACP 聊天界面
+
+Web UI 使用 UUID 认证（无需用户账户），适合受信任网络环境。
+
+## ACP 支持
+
+RCS 支持 ACP (Agent Client Protocol) agent 通过 `acp-link` 包接入。
+
+### 架构
+
+```
+acp-link ──REST注册──► RCS POST /v1/environments/bridge
+acp-link ──WS identify──► RCS WebSocket (携带 agentId)
+acp-link ◄──ACP relay──► RCS ◄──Web UI WS──► 浏览器
+```
+
+### 后端组件
+
+| 文件 | 职责 |
+|------|------|
+| `src/routes/acp/index.ts` | ACP REST 路由：agents 列表、channel groups、relay |
+| `src/transport/acp-ws-handler.ts` | ACP WebSocket 处理：agent 注册、心跳、消息转发 |
+| `src/transport/acp-relay-handler.ts` | 前端 WS → acp-link 透传 + EventBus inbound 转发 |
+| `src/transport/acp-sse-writer.ts` | SSE event stream 供外部消费者订阅 |
+
+### acp-link 连接
+
+详见 [acp-link 文档](./acp-link.md)。
+
+```bash
+# 在 RCS 环境中启动 acp-link
+# 注意：claude 本身不支持 ACP，需要用 ccb-bun --acp
+ACP_RCS_URL=http://localhost:3000 \
+ACP_RCS_TOKEN=sk-rcs-your-key \
+acp-link ccb-bun -- --acp
+```
+
+ACP session 在 Web UI 中显示品牌色标签，与普通 Claude Code session 区分。
+
+## 工作流程详解
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                    完整工作流程                            │
+└──────────────────────────────────────────────────────────┘
+
+ 1. Claude Code CLI 启动，设置环境变量指向自托管 RCS
+
+ 2. 用户执行 /remote-control 命令
+
+ 3. 注册环境
+    CLI ──POST /v1/environments/bridge──► RCS
+    CLI ◄── { environment_id, environment_secret } ── RCS
+
+ 4. 终端显示连接 URL
+    https://rcs.example.com/code?bridge=<environmentId>
+
+ 5. 开始工作轮询（循环）
+    CLI ──GET /v1/environments/:id/work/poll──► RCS
+         （长轮询，等待任务分配，超时 8 秒后重试）
+
+ 6. 浏览器打开 URL → Web UI 创建任务
+    Browser ──POST /web/sessions──► RCS
+    RCS 分配 work 给正在轮询的 CLI
+
+ 7. CLI 收到任务并确认
+    CLI ◄── { id, data: { type, sessionId } } ── RCS
+    CLI ──POST /v1/environments/:id/work/:workId/ack──► RCS
+
+ 8. 建立会话连接
+    CLI ──WebSocket /v1/session_ingress──► RCS
+         （或使用 V2 的 SSE + HTTP POST）
+
+ 9. 双向通信
+    CLI ──消息/工具调用结果──► RCS ──► Browser
+    CLI ◄──权限审批/指令───── RCS ◄──── Browser
+    CLI ──automation_state / task_state──► RCS ──► Browser
+
+10. 心跳保活（每 20 秒）
+    CLI ──POST /v1/environments/:id/work/:workId/heartbeat──► RCS
+
+11. 任务完成 → 归档会话 → 注销环境
+```
+
+## 故障排查
+
+### Web UI 看不到当前 Autopilot 状态
+
+- `standby`：proactive 已开启，正在等待下一个 tick
+- `sleeping`：模型正在 `SleepTool` 等待窗口中
+
+这两个状态通过 worker `external_metadata.automation_state` 上报。如果页面只显示普通 working spinner，优先检查 CLI 和 RCS 之间的 worker metadata PUT 是否成功。
+
+### CLI 无法连接
+
+```
+Error: Remote Control is not available in this build.
+```
+
+**原因**：`BRIDGE_MODE` feature flag 未启用。
+
+**解决**：使用 dev 模式（默认启用）或确保构建时包含 `BRIDGE_MODE` flag。
+
+### 认证失败 (401)
+
+```
+Error: Unauthorized
+```
+
+**检查项**：
+1. `CLAUDE_BRIDGE_OAUTH_TOKEN` 是否与 `RCS_API_KEYS` 中的值匹配
+2. API Key 是否包含多余的空格或换行
+3. 两个环境变量是否都已正确设置
+
+### WebSocket 连接中断
+
+**检查项**：
+1. 如果使用反向代理，确认已正确配置 WebSocket 升级（`Upgrade` / `Connection` 头）
+2. 代理的 `proxy_read_timeout` 是否足够大（建议 86400 秒）
+3. 网络防火墙是否允许 WebSocket 流量
+
+### 健康检查
+
+```bash
+curl https://rcs.example.com/health
+# 预期: {"status":"ok","version":"0.1.0"}
+```
+
+## 限制与注意事项
+
+| 项目 | 说明 |
+|------|------|
+| 存储 | 纯内存存储（Map），服务器重启后所有会话和环境数据丢失 |
+| 扩展 | 不支持水平扩展（无共享状态），单实例部署 |
+| 并发 | 适合中小规模使用，大量并发会话可能需要性能调优 |
+| 数据持久化 | `/app/data` 卷已预留但当前未使用，未来可能用于持久化 |
+| Web UI 认证 | 基于 UUID，无用户账户系统，适合受信任网络环境 |
+
+## 与云端模式对比
+
+| 特性 | 云端 (Anthropic CCR) | 自托管 (RCS) |
+|------|---------------------|--------------|
+| 认证方式 | claude.ai OAuth 订阅 | API Key |
+| GrowthBook 门控 | 需要 `tengu_ccr_bridge` 通过 | 自动跳过 |
+| 功能标志 | 需要 `BRIDGE_MODE=1` | 同样需要 |
+| 部署位置 | Anthropic 云端 | 用户自有服务器 |
+| 数据流经 | Anthropic 基础设施 | 用户私有网络 |
+| 依赖 | claude.ai 订阅 + OAuth | 仅需 API Key |
+
+自托管模式的核心优势是：设置 `CLAUDE_BRIDGE_BASE_URL` 后，代码自动调用 `isSelfHostedBridge()` 返回 `true`，跳过所有 GrowthBook 和订阅检查，无需 claude.ai 账户即可使用。

docs/features/stub-recovery-design-1-4.md

@@ -0,0 +1,310 @@
+# Stub 恢复设计 1-4
+
+> 日期：2026-04-12
+> 目标：基于当前代码边界，为下一阶段 4 个 stub/半 stub 命令面给出可实施的设计方案。
+> 排序原则：按建议实施顺序排序，不按问题严重性排序。
+
+## 设计原则
+
+- 先做能独立闭环、收益明确、改动边界清晰的项。
+- 大项拆成 `MVP` 和 `Phase 2+`，避免一次性掉进大范围恢复。
+- 优先复用已有状态、传输层、日志与配置能力，不重造协议。
+- 设计以当前仓库实际代码为准，不以旧文档的理想状态为准。
+
+## 1. `claude daemon status` / `claude daemon stop`
+
+### 现状
+
+- `start` 路径已有完整 supervisor + worker 生命周期：
+  `src/daemon/main.ts`
+  `src/daemon/workerRegistry.ts`
+- `status` / `stop` 目前只是占位输出：
+  `src/daemon/main.ts`
+- `/remote-control-server` 有自己的命令内 UI 状态，但只维护当前进程内的 `daemonProcess`，并不适合作为跨进程 CLI 管理基础：
+  `src/commands/remoteControlServer/remoteControlServer.tsx`
+
+### 目标
+
+- 让 `claude daemon status` 和 `claude daemon stop` 在另一个 CLI 进程中也能正确工作。
+- 不依赖 TUI 内存态，不要求当前命令进程就是启动 daemon 的那个进程。
+
+### MVP 方案
+
+- 新增 daemon 状态文件，例如：
+  `~/.claude/daemon/remote-control.json`
+- `start` 时写入：
+  - supervisor pid
+  - cwd
+  - startedAt
+  - worker kinds
+  - 最近状态
+- `status`：
+  - 读取状态文件
+  - 用现有进程探测能力验证 pid 是否存活
+  - 输出 `running / stopped / stale`
+  - stale 时自动清理状态文件
+- `stop`：
+  - 读取 pid
+  - 发送 `SIGTERM`
+  - 等待退出
+  - 超时后 `SIGKILL`
+  - 清理状态文件
+
+### 代码范围
+
+- 新增 `src/daemon/state.ts`
+- 修改 `src/daemon/main.ts`
+- 轻量修改 `src/commands/remoteControlServer/remoteControlServer.tsx`，让 UI 尽量读取同一份状态文件
+
+### 验证
+
+1. `claude daemon start`
+2. 新开终端执行 `claude daemon status`
+3. 执行 `claude daemon stop`
+4. 再次执行 `claude daemon status`，确认返回 `stopped` 或清晰的 `stale cleaned`
+
+### 风险
+
+- Windows 信号模型和 Unix 不同，`stop` 需要超时兜底。
+- 当前设计默认单 supervisor，不处理多实例并发。
+
+### 工作量判断
+
+- 小
+- 适合作为下一步的首选实现项
+
+## 2. `BG_SESSIONS`
+
+### 现状
+
+- fast-path 已接好：
+  `src/entrypoints/cli.tsx`
+- session registry 已有真实实现：
+  `src/utils/concurrentSessions.ts`
+- `exit` 在 bg session 内已会 `tmux detach-client`：
+  `src/commands/exit/exit.tsx`
+- 但 CLI handler 仍全空：
+  `src/cli/bg.ts`
+- task summary 仍然是 stub：
+  `src/utils/taskSummary.ts`
+
+### 目标
+
+- 先把 `ps` / `logs` / `kill` 做成真正有用的 session 管理命令。
+- 不在第一阶段就强行补完 `attach` / `--bg`。
+
+### Phase 2A：MVP
+
+- 实现 `ps`
+  - 从 registry 读取 live sessions
+  - 展示 pid、kind、sessionId、cwd、name、startedAt、bridgeSessionId
+  - 如果有 activity/status，则一并展示
+- 实现 `logs`
+  - 支持按 `sessionId / pid / name` 查找
+  - 优先复用本地 transcript/log 读取能力
+  - 如果 registry 里存在 `logPath`，支持 tail 文件
+- 实现 `kill`
+  - 解析目标 session
+  - 发退出信号
+  - 清理 stale registry
+
+### Phase 2B：后续
+
+- 实现 `attach`
+- 实现 `--bg`
+- 实现 `taskSummary` 的中途状态更新
+
+### 为什么要拆
+
+- 现有 registry 记录了 `pid / sessionId / name / logPath`
+- 但没有可靠的 tmux attach target
+- 所以 `attach` 和 `--bg` 不是简单补 handler，而是需要补启动/附着元数据设计
+
+### 代码范围
+
+- 修改 `src/cli/bg.ts`
+- 修改 `src/utils/concurrentSessions.ts` 以便后续 attach/--bg 扩展
+- 修改 `src/utils/taskSummary.ts`
+- 复用：
+  `src/utils/sessionStorage.ts`
+  `src/utils/udsClient.ts`
+
+### 验证
+
+1. `ps` 能列出 live sessions
+2. `logs <sessionId|pid|name>` 能输出对应日志
+3. `kill <sessionId|pid|name>` 能结束目标 session
+
+### 风险
+
+- `attach` / `--bg` 第二阶段需要 tmux 元数据设计
+- Windows 下 tmux 路径需要明确降级策略
+
+### 工作量判断
+
+- `ps/logs/kill` 中等
+- `attach/--bg` 明显更大，应分阶段
+
+## 3. `TEMPLATES`
+
+### 现状
+
+- 命令入口只有 fast-path：
+  `src/entrypoints/cli.tsx`
+- handler 是空的：
+  `src/cli/handlers/templateJobs.ts`
+- `markdownConfigLoader` 已把 `templates` 纳入配置目录：
+  `src/utils/markdownConfigLoader.ts`
+- `query / stopHooks` 已预留 job classifier 链路：
+  `src/query/stopHooks.ts`
+- `jobs/classifier.ts` 仍是 stub：
+  `src/jobs/classifier.ts`
+
+### 目标
+
+- 把 `new / list / reply` 做成可用的模板任务系统。
+- 第一阶段不碰复杂的自动分类与自动执行。
+
+### MVP 方案
+
+- 模板来源：
+  `.claude/templates/*.md`
+- 模板格式：
+  复用现有 markdown + frontmatter 解析，不另外设计 DSL
+- `list`
+  - 列出所有模板
+  - 显示模板名、description、路径
+- `new <template> [args...]`
+  - 解析模板
+  - 在 `~/.claude/jobs/<job-id>/` 下创建 job 目录
+  - 写入 `template.md`、`input.txt`、`state.json`
+  - 返回 job id 与目录
+- `reply <job-id> <text>`
+  - 将回复写入 `replies.jsonl` 或 `input.txt`
+  - 更新 `state.json`
+
+### Phase 2
+
+- 恢复 `src/jobs/classifier.ts`
+- 让带 `CLAUDE_JOB_DIR` 的 job session 在 turn 完成后自动更新 `state.json`
+- 再决定是否补自动 job runner
+
+### 为什么要拆
+
+- 当前证据表明这是“template job commands”，不是单纯模板列表
+- 但自动 job 运行链路没有足够现成实现，先做文件系统 job lifecycle 更稳
+
+### 代码范围
+
+- 修改 [src/cli/handlers/templateJobs.ts](</e:/Source_code/Claude-code-bast/src/cli/handlers/templateJobs.ts:1>)
+- 新增 `src/jobs/state.ts`
+- 新增 `src/jobs/templates.ts`
+- Phase 2 再改 [src/jobs/classifier.ts](</e:/Source_code/Claude-code-bast/src/jobs/classifier.ts:1>)
+
+### 验证
+
+1. `list` 能列出 `.claude/templates`
+2. `new` 能创建 job 目录和状态文件
+3. `reply` 能更新 job 内容和状态
+4. Phase 2 再验证 classifier 写状态
+
+### 风险
+
+- frontmatter schema 需要先定义最小字段集
+- 一旦扩展到“自动运行 job”，范围会明显膨胀
+
+### 工作量判断
+
+- MVP 中等
+- 完整 job 系统偏大
+
+## 4. `assistant [sessionId]`
+
+### 现状
+
+- attach 主流程其实已经存在：
+  [src/main.tsx](</e:/Source_code/Claude-code-bast/src/main.tsx:4708>)
+- 远端 viewer 所需基础模块已存在：
+  [src/remote/RemoteSessionManager.ts](</e:/Source_code/Claude-code-bast/src/remote/RemoteSessionManager.ts:1>)
+  [src/hooks/useAssistantHistory.ts](</e:/Source_code/Claude-code-bast/src/hooks/useAssistantHistory.ts:1>)
+  [src/assistant/sessionHistory.ts](</e:/Source_code/Claude-code-bast/src/assistant/sessionHistory.ts:1>)
+- 真正 stub 的主要是：
+  [src/assistant/sessionDiscovery.ts](</e:/Source_code/Claude-code-bast/src/assistant/sessionDiscovery.ts:1>)
+  [src/assistant/AssistantSessionChooser.ts](</e:/Source_code/Claude-code-bast/src/assistant/AssistantSessionChooser.ts:1>)
+  [src/commands/assistant/assistant.ts](</e:/Source_code/Claude-code-bast/src/commands/assistant/assistant.ts:7>)
+  [src/assistant/index.ts](</e:/Source_code/Claude-code-bast/src/assistant/index.ts:1>)
+
+### 目标
+
+- 不一次性恢复整个 KAIROS 助手系统。
+- 先做“明确 sessionId 的 viewer attach 可用”，再逐步补 discovery / chooser / install。
+
+### Phase 4A：MVP
+
+- 只支持 `claude assistant <sessionId>`
+- 对 `claude assistant` 无参数模式，先返回明确提示：
+  - 当前版本需要显式 `sessionId`
+  - discovery 尚未启用
+- 这样可以直接复用现有 attach 分支，不必先恢复 chooser/install wizard
+
+### Phase 4B
+
+- 恢复 `discoverAssistantSessions()`
+- 数据来源优先复用现有 sessions / bridge / teleport API，而不是新协议
+- 让 `claude assistant` 无参数时能拿到候选 session 列表
+
+### Phase 4C
+
+- 恢复 `AssistantSessionChooser`
+- 多 session 时可交互选择
+
+### Phase 4D
+
+- 最后考虑 install wizard 辅助函数
+- 这部分属于“没有 session 时如何引导”，不是 attach 核心路径
+
+### 为什么要拆
+
+- attach 渲染层与远端消息通道大部分已经在
+- 真正缺的是“如何发现目标 session”和“如何交互选择”
+- 如果把 `src/assistant/index.ts` 的整套 KAIROS 正常模式也一起拉进来，范围会失控
+
+### 代码范围
+
+- Phase 4A：
+  - [src/main.tsx](</e:/Source_code/Claude-code-bast/src/main.tsx:4708>)
+  - [src/commands/assistant/index.ts](</e:/Source_code/Claude-code-bast/src/commands/assistant/index.ts:1>)
+- Phase 4B：
+  - [src/assistant/sessionDiscovery.ts](</e:/Source_code/Claude-code-bast/src/assistant/sessionDiscovery.ts:1>)
+- Phase 4C：
+  - [src/assistant/AssistantSessionChooser.ts](</e:/Source_code/Claude-code-bast/src/assistant/AssistantSessionChooser.ts:1>)
+- Phase 4D：
+  - [src/commands/assistant/assistant.ts](</e:/Source_code/Claude-code-bast/src/commands/assistant/assistant.ts:7>)
+
+### 验证
+
+1. `claude assistant <sessionId>` 能进入 remote viewer
+2. 历史懒加载工作正常
+3. 无参数模式先给出明确提示
+4. 后续阶段再分别验证 discovery / chooser / install
+
+### 风险
+
+- 这是四项里范围最大的
+- 一旦把 KAIROS 正常模式整体拉入，会从“viewer attach”膨胀成“完整 assistant mode 恢复”
+
+### 工作量判断
+
+- Phase 4A 中等
+- 4A-4D 全做完很大
+
+## 建议执行顺序
+
+1. `claude daemon status` / `claude daemon stop`
+2. `BG_SESSIONS` 先做 `ps/logs/kill`
+3. `TEMPLATES` 先做 job 文件系统 MVP
+4. `assistant [sessionId]` 先做显式 sessionId attach，再补 discovery/chooser/install
+
+## 简短结论
+
+这四项里，最适合立刻实现的是 `daemon status/stop`。`BG_SESSIONS` 和 `TEMPLATES` 适合按 MVP 先补 handler 与文件系统闭环。`assistant [sessionId]` 不能整块硬上，应该按“attach → discovery → chooser → install”拆开恢复。

docs/features/tier3-stubs.md

@@ -7,51 +7,13 @@
 
 | Feature | 引用 | 状态 | 类别 | 简要说明 |
 |---------|------|------|------|---------|
-| CHICAGO_MCP | 16 | N/A | 内部基础设施 | Anthropic 内部 MCP 基础设施，非外部可用 |
-| UDS_INBOX | 17 | Stub | 消息通信 | Unix 域套接字对等消息，进程间消息传递 |
-| MONITOR_TOOL | 13 | Stub | 工具 | 文件/进程监控工具，检测变更并通知 |
-| BG_SESSIONS | 11 | Stub | 会话管理 | 后台会话管理，支持多会话并行 |
-| SHOT_STATS | 10 | 无实现 | 统计 | 逐 prompt 统计信息收集 |
-| EXTRACT_MEMORIES | 7 | 无实现 | 记忆 | 自动从对话中提取重要信息作为记忆 |
-| TEMPLATES | 6 | Stub | 项目管理 | 项目/提示模板系统 |
-| LODESTONE | 6 | N/A | 内部基础设施 | 内部基础设施模块 |
-| STREAMLINED_OUTPUT | 1 | — | 输出 | 精简输出模式，减少终端输出量 |
-| HOOK_PROMPTS | 1 | — | 钩子 | Hook 提示词，自定义钩子的提示注入 |
-| CCR_AUTO_CONNECT | 3 | — | 远程控制 | CCR 自动连接，自动建立远程控制会话 |
-| CCR_MIRROR | 4 | — | 远程控制 | CCR 镜像模式，会话状态同步 |
-| CCR_REMOTE_SETUP | 1 | — | 远程控制 | CCR 远程设置，初始化远程控制配置 |
-| NATIVE_CLIPBOARD_IMAGE | 2 | — | 系统集成 | 原生剪贴板图片，从剪贴板读取图片 |
-| CONNECTOR_TEXT | 7 | — | 连接器 | 连接器文本，外部系统文本适配 |
-| COMMIT_ATTRIBUTION | 12 | — | Git | Commit 归因，标记 commit 来源 |
-| CACHED_MICROCOMPACT | 12 | — | 压缩 | 缓存微压缩，优化 compaction 性能 |
-| PROMPT_CACHE_BREAK_DETECTION | 9 | — | 性能 | Prompt cache 中断检测，监控 cache miss |
-| MEMORY_SHAPE_TELEMETRY | 3 | — | 遥测 | 记忆形态遥测，记忆使用模式追踪 |
-| MCP_RICH_OUTPUT | 3 | — | MCP | MCP 富输出，增强 MCP 工具输出格式 |
-| FILE_PERSISTENCE | 3 | — | 持久化 | 文件持久化，跨会话保持状态 |
-| TREE_SITTER_BASH_SHADOW | 5 | Shadow | 安全 | Bash AST Shadow 模式（见 tree-sitter-bash.md） |
-| QUICK_SEARCH | 5 | — | 搜索 | 快速搜索，优化的文件/内容搜索 |
-| MESSAGE_ACTIONS | 5 | — | UI | 消息操作，对消息执行后处理动作 |
-| DOWNLOAD_USER_SETTINGS | 5 | — | 配置 | 下载用户设置，从服务端同步配置 |
-| DIRECT_CONNECT | 5 | — | 网络 | 直连模式，绕过代理直接连接 API |
-| VERIFICATION_AGENT | 4 | — | Agent | 验证 Agent，专门用于验证代码变更 |
-| TERMINAL_PANEL | 4 | — | UI | 终端面板，嵌入式终端输出显示 |
-| SSH_REMOTE | 4 | — | 远程 | SSH 远程，通过 SSH 连接远程 Claude |
-| REVIEW_ARTIFACT | 4 | — | 审查 | Review Artifact，代码审查产出物 |
-| REACTIVE_COMPACT | 4 | — | 压缩 | 响应式压缩，基于上下文变化触发 compaction |
-| HISTORY_PICKER | 4 | — | UI | 历史选择器，浏览和选择历史对话 |
-| UPLOAD_USER_SETTINGS | 2 | — | 配置 | 上传用户设置，同步配置到服务端 |
-| POWERSHELL_AUTO_MODE | 2 | — | 平台 | PowerShell 自动模式，Windows 权限自动化 |
-| OVERFLOW_TEST_TOOL | 2 | — | 测试 | 溢出测试工具，测试上下文溢出处理 |
-| NEW_INIT | 2 | — | 初始化 | 新版初始化流程 |
-| HARD_FAIL | 2 | — | 错误处理 | 硬失败模式，不可恢复错误直接终止 |
-| ENHANCED_TELEMETRY_BETA | 2 | — | 遥测 | 增强遥测 Beta，详细的性能指标收集 |
-| COWORKER_TYPE_TELEMETRY | 2 | — | 遥测 | 协作者类型遥测，追踪协作模式 |
-| BREAK_CACHE_COMMAND | 2 | — | 缓存 | 中断缓存命令，强制刷新 prompt cache |
-| AWAY_SUMMARY | 2 | — | 摘要 | 离开摘要，用户返回时总结期间工作 |
-| AUTO_THEME | 2 | — | UI | 自动主题，根据终端设置切换主题 |
-| ALLOW_TEST_VERSIONS | 2 | — | 版本 | 允许测试版本，跳过版本检查 |
-| AGENT_TRIGGERS_REMOTE | 2 | — | Agent | Agent 远程触发，从远程触发 Agent 任务 |
-| AGENT_MEMORY_SNAPSHOT | 2 | — | Agent | Agent 记忆快照，保存/恢复 Agent 状态 |
+| CHICAGO_MCP | 16 | 已实现 | 工具 | Computer Use + Chrome MCP 控制（build 默认启用） |
+| MONITOR_TOOL | 13 | 已实现 | 工具 | 后台监控工具，持续监视 shell 输出（build 默认启用） |
+| BG_SESSIONS | 11 | 部分实现 | 会话管理 | 后台会话注册/清理已实现，任务摘要是 stub（dev 默认启用） |
+| SHOT_STATS | 10 | 已实现 | 统计 | API 调用统计面板（build 默认启用） |
+| EXTRACT_MEMORIES | 7 | 已实现 | 记忆 | 自动记忆提取（build 默认启用，受 GrowthBook 门控） |
+| TEMPLATES | 6 | 部分实现 | 项目管理 | 项目/提示模板系统（dev 默认启用） |
+| LODESTONE | 6 | 已实现 | 深度链接 | URL 协议处理器（build 默认启用） |
 
 ## 单引用 Feature（40+ 个）
 
@@ -67,10 +29,9 @@ BUILDING_CLAUDE_APPS, ANTI_DISTILLATION_CC, AGENT_TRIGGERS, ABLATION_BASELINE
 
 这些 feature 被列为 Tier 3 的原因：
 
-1. **内部基础设施**（CHICAGO_MCP, LODESTONE）：Anthropic 内部使用，外部无法运行
-2. **纯 Stub 且引用低**（UDS_INBOX, MONITOR_TOOL, BG_SESSIONS）：需要大量工作才能实现
-3. **实验性功能**（SHOT_STATS, EXTRACT_MEMORIES）：尚在概念阶段
-4. **辅助功能**（STREAMLINED_OUTPUT, HOOK_PROMPTS）：影响范围小
-5. **CCR 系列**：依赖远程控制基础设施，需要 BRIDGE_MODE 先完善
+1. **已实现但影响范围小**（CHICAGO_MCP, LODESTONE, SHOT_STATS, EXTRACT_MEMORIES, MONITOR_TOOL）：已在 build/dev 默认启用，主要作为其他功能的基础设施
+2. **部分实现**（BG_SESSIONS, TEMPLATES）：核心注册已实现，但部分功能如任务摘要仍是 stub
+3. **辅助功能**（STREAMLINED_OUTPUT, HOOK_PROMPTS）：影响范围小
+4. **CCR 系列**：依赖远程控制基础设施，需要 BRIDGE_MODE 先完善
 
 如需深入了解某个 Tier 3 feature，可以在代码库中搜索 `feature('FEATURE_NAME')` 查看具体使用场景。

docs/features/token-budget.md

@@ -191,7 +191,7 @@ FEATURE_TOKEN_BUDGET=1 bun run dev
 | `src/query/tokenBudget.ts` | 93 | 预算追踪器 + continue/stop 决策 |
 | `src/bootstrap/state.ts:724-743` | 20 | turn 级 token 快照状态 |
 | `src/constants/prompts.ts:538-551` | 14 | 系统提示注入 |
-| `src/utils/attachments.ts:3829-3845` | 17 | API attachment 附加 |
+| `src/utils/attachments.ts:3830-3844` | 17 | API attachment 附加 |
 | `src/query.ts:280,1311-1358` | 48 | 主循环集成 |
 | `src/screens/REPL.tsx:2897,2963,2138` | 20 | REPL 提交/完成/取消处理 |
 | `src/components/Spinner.tsx:319-338` | 20 | 进度条 UI |

docs/features/tree-sitter-bash.md

@@ -158,4 +158,4 @@ FEATURE_TREE_SITTER_BASH_SHADOW=1 bun run dev
 | `src/utils/bash/bashParser.ts` | 4437 | 纯 TS bash 解析器 |
 | `src/utils/bash/ast.ts` | 2680 | 安全分析器（核心） |
 | `src/utils/bash/treeSitterAnalysis.ts` | 507 | AST 分析辅助 |
-| `src/tools/BashTool/bashPermissions.ts:1670-1810` | ~140 | 权限集成 + Shadow 遥测 |
+| `packages/builtin-tools/src/tools/BashTool/bashPermissions.ts` | ~140 | 权限集成 + Shadow 遥测 |

docs/features/uds-inbox.md

@@ -0,0 +1,114 @@
+# UDS_INBOX / pipes
+
+## 概述
+
+`UDS_INBOX` 现在不是一个“空壳 flag”，而是一套已经落地的本机 IPC 能力。但它同时承载了两层不同目标，必须拆开理解：
+
+1. **UDS peer messaging**
+   - 面向任意 Claude Code 进程。
+   - 使用 `src/utils/udsMessaging.ts` 和 `src/utils/udsClient.ts`。
+   - 对外入口是 `/peers` 和 `SendMessageTool` 的 `uds:<socket-path>` 地址。
+2. **pipes control plane**
+   - 面向交互式 REPL 会话之间的主从协作。
+   - 使用 `src/utils/pipeTransport.ts`、`src/utils/pipeRegistry.ts` 和 `src/screens/REPL.tsx` 中的内联 bootstrap。
+   - 对外入口是 `/pipes`、`/attach`、`/detach`、`/send`、`/pipe-status`、`/history`、`/claim-main`。
+
+这两层都依赖本机 socket，但职责不同。`/peers` 解决“找到其他会话并发消息”，`/pipes` 解决“把一个 REPL 变成另一个 REPL 的受控 worker”。
+
+## 为什么要有单独的 `pipes`
+
+单独的 `pipes` 层有三个实际理由：
+
+1. **命名与角色模型不同**
+   - UDS peer 层按 `messagingSocketPath` 寻址。
+   - pipes 层按 `cli-xxxxxxxx` 会话名、`main/sub/master/slave` 角色和 `machineId` 注册表工作。
+2. **交互语义不同**
+   - peer 层是通用消息投递。
+   - pipes 层需要 attach、detach、历史收集、选择性广播、状态栏和 REPL 快捷键。
+3. **UI 集成不同**
+   - peer 层主要服务工具调用。
+   - pipes 层直接影响 REPL 提交路径和 PromptInput 页脚。
+
+如果把两者硬合并，`SendMessageTool` 的通用寻址和 REPL 的主从控制会互相污染，命令语义也会变得混乱。
+
+## 当前通信模型
+
+### 1. UDS peer messaging
+
+- 服务端：`src/utils/udsMessaging.ts`
+- 客户端：`src/utils/udsClient.ts`
+- 发现方式：读取 `~/.claude/sessions/*.json`
+- 地址方式：`uds:<socket-path>`
+- 传输方式：**本机 Unix socket / Windows named pipe**
+
+这层是真正的“通用收件箱”。
+
+### 2. pipes control plane
+
+- 服务端/客户端：`src/utils/pipeTransport.ts`
+- 注册表：`src/utils/pipeRegistry.ts`
+- 生效入口：`src/screens/REPL.tsx`
+- 发现方式：扫描 `~/.claude/pipes/` + `registry.json`
+- 会话名：`cli-${sessionId.slice(0, 8)}`
+- 传输方式：**本机 Unix socket / Windows named pipe**
+
+这层是真正的“主从 REPL 协调平面”。
+
+## 关于“局域网通信”的事实
+
+当前实现**不是**真正的局域网传输。
+
+代码里虽然保存了这些字段：
+
+- `localIp`
+- `hostname`
+- `machineId`
+- `mac`
+
+但这些字段当前只用于：
+
+1. 注册表展示
+2. main/sub 身份判定
+3. `claim-main` 的机器级归属切换
+4. 状态输出与排障信息
+
+它们**没有**被用于创建 TCP/WebSocket 连接。真正的传输仍然是 `getPipePath(name)` 返回的本机 socket 路径。
+
+所以目前更准确的描述应该是：
+
+- `pipes` 支持 **本机多实例协作**
+- `registry` 带有 **机器身份元数据**
+- 但 **尚未实现跨机器局域网 transport**
+
+如果未来要做真局域网版本，至少还需要：
+
+1. TCP/WebSocket transport
+2. 认证与会话授权
+3. 发现与地址交换
+4. 超时、重连和安全边界
+
+## 当前 REPL 行为
+
+当前线上行为由 `src/screens/REPL.tsx` 的内联实现负责：
+
+1. 启动时创建当前 REPL 的 pipe server
+2. 通过 `pipeRegistry` 判定 `main` / `sub`
+3. 处理 `attach_request` / `detach` / `prompt`
+4. 主实例心跳探测并维护 `slaves`
+5. `/pipes` 打开状态栏并维护选择器
+6. 提交普通消息时，仅向**已连接**的 selected pipes 广播
+
+最近的收敛点：
+
+- 过去遗留了一套未接线的 hook 方案
+- 当前已明确以 `REPL.tsx` 内联 bootstrap 为唯一生效实现
+- 选中但未连接的 pipe 不再导致本地处理被错误跳过
+
+## 文档与代码对齐约定
+
+后续关于 `UDS_INBOX` / `pipes` 的说明应遵守以下表述：
+
+1. 默认称为“本机 IPC / 本机多实例协作”
+2. 不把 `localIp` / `hostname` 元数据表述成已完成的 LAN transport
+3. 明确区分 `/peers` 和 `/pipes` 的两层职责
+4. 以 `src/screens/REPL.tsx`、`src/utils/pipeTransport.ts`、`src/utils/pipeRegistry.ts` 为事实来源

docs/features/ultraplan.md

@@ -22,16 +22,16 @@ ULTRAPLAN 在用户输入中检测 "ultraplan" 关键字时，自动进入增强
 
 | 模块 | 文件 | 行数 | 状态 |
 |------|------|------|------|
-| 命令处理器 | `src/commands/ultraplan.tsx` | 472 | **完整** |
-| CCR 会话 | `src/utils/ultraplan/ccrSession.ts` | 350 | **完整** |
-| 关键字检测 | `src/utils/ultraplan/keyword.ts` | 128 | **完整** |
+| 命令处理器 | `src/commands/ultraplan.tsx` | 525 | **完整** |
+| CCR 会话 | `src/utils/ultraplan/ccrSession.ts` | 349 | **完整** |
+| 关键字检测 | `src/utils/ultraplan/keyword.ts` | 127 | **完整** |
 | 嵌入式提示 | `src/utils/ultraplan/prompt.txt` | 1 | **完整** |
 | REPL 对话框 | `src/screens/REPL.tsx` | — | **布线** |
 | 关键字高亮 | `src/components/PromptInput/PromptInput.tsx` | — | **布线** |
 
 ### 2.2 关键字检测
 
-文件：`src/utils/ultraplan/keyword.ts`（128 行）
+文件：`src/utils/ultraplan/keyword.ts`（127 行）
 
 `findUltraplanTriggerPositions(text)` 智能过滤：
 - 排除引号内的 "ultraplan"
@@ -41,7 +41,7 @@ ULTRAPLAN 在用户输入中检测 "ultraplan" 关键字时，自动进入增强
 
 ### 2.3 CCR 远程会话
 
-文件：`src/utils/ultraplan/ccrSession.ts`（350 行）
+文件：`src/utils/ultraplan/ccrSession.ts`（349 行）
 
 `ExitPlanModeScanner` 类实现完整的事件状态机：
 - `pollForApprovedExitPlanMode()` — 3 秒轮询间隔
@@ -99,9 +99,9 @@ FEATURE_ULTRAPLAN=1 bun run dev
 
 | 文件 | 行数 | 职责 |
 |------|------|------|
-| `src/commands/ultraplan.tsx` | 472 | 斜杠命令处理器 |
-| `src/utils/ultraplan/ccrSession.ts` | 350 | CCR 远程会话管理 |
-| `src/utils/ultraplan/keyword.ts` | 128 | 关键字检测和替换 |
+| `src/commands/ultraplan.tsx` | 525 | 斜杠命令处理器 |
+| `src/utils/ultraplan/ccrSession.ts` | 349 | CCR 远程会话管理 |
+| `src/utils/ultraplan/keyword.ts` | 127 | 关键字检测和替换 |
 | `src/utils/ultraplan/prompt.txt` | 1 | 嵌入式提示 |
 | `src/utils/processUserInput/processUserInput.ts:468` | — | 关键字重定向 |
 | `src/components/PromptInput/PromptInput.tsx` | — | 彩虹高亮 |

docs/features/voice-mode.md

@@ -120,6 +120,6 @@ FEATURE_VOICE_MODE=1 bun run dev
 
 | 文件 | 行数 | 职责 |
 |------|------|------|
-| `src/voice/voiceModeEnabled.ts` | 55 | 三层门控逻辑 |
+| `src/voice/voiceModeEnabled.ts` | 54 | 三层门控逻辑 |
 | `src/hooks/useVoice.ts` | — | React hook（录音状态 + WebSocket） |
 | `src/services/voiceStreamSTT.ts` | — | STT WebSocket 流式传输 |

docs/features/web-browser-tool.md

@@ -1,7 +1,7 @@
 # WEB_BROWSER_TOOL — 浏览器工具
 
 > Feature Flag: `FEATURE_WEB_BROWSER_TOOL=1`
-> 实现状态：核心实现缺失，面板为 Stub，布线完整
+> 实现状态：核心工具已实现，面板为 Stub，布线完整
 > 引用数：4
 
 ## 一、功能概述
@@ -14,8 +14,8 @@ WEB_BROWSER_TOOL 让模型可以启动浏览器实例、导航网页、与页面
 
 | 模块 | 文件 | 状态 |
 |------|------|------|
-| 浏览器面板 | `src/tools/WebBrowserTool/WebBrowserPanel.ts` | **Stub** — 返回 null |
-| 浏览器工具 | `src/tools/WebBrowserTool/WebBrowserTool.ts` | **缺失** |
+| 浏览器面板 | `packages/builtin-tools/src/tools/WebBrowserTool/WebBrowserPanel.ts` | **Stub** — 返回 null |
+| 浏览器工具 | `packages/builtin-tools/src/tools/WebBrowserTool/WebBrowserTool.ts` | **已实现** |
 | REPL 集成 | `src/screens/REPL.tsx` | **布线** — 渲染 WebBrowserPanel |
 | 工具注册 | `src/tools.ts` | **布线** — 动态加载 |
 | WebView 检测 | `src/main.tsx` | **布线** — `'WebView' in Bun` 检测 |
@@ -44,8 +44,8 @@ WebBrowserPanel 在 REPL 侧边显示浏览器状态
 
 | 模块 | 工作量 | 说明 |
 |------|--------|------|
-| `WebBrowserTool.ts` | 大 | 工具 schema + Bun WebView API 执行 |
-| `WebBrowserPanel.tsx` | 中 | REPL 侧边栏浏览器状态面板 |
+| `WebBrowserTool.ts` | ✅ 已实现 | 工具 schema + Bun WebView API 执行 |
+| `WebBrowserPanel.tsx` | 中 | REPL 侧边栏浏览器状态面板（仍为 Stub） |
 
 ## 四、关键设计决策
 
@@ -63,7 +63,7 @@ FEATURE_WEB_BROWSER_TOOL=1 bun run dev
 
 | 文件 | 职责 |
 |------|------|
-| `src/tools/WebBrowserTool/WebBrowserPanel.ts` | 面板组件（stub） |
-| `src/tools/WebBrowserTool/WebBrowserTool.ts` | 工具实现（缺失） |
-| `src/screens/REPL.tsx:273,4582` | 面板渲染 |
+| `packages/builtin-tools/src/tools/WebBrowserTool/WebBrowserPanel.ts` | 面板组件（stub） |
+| `packages/builtin-tools/src/tools/WebBrowserTool/WebBrowserTool.ts` | 工具实现（已实现） |
+| `src/screens/REPL.tsx:471,5676` | 面板渲染 |
 | `src/tools.ts:115-116` | 工具注册 |

docs/features/web-search-tool.md

@@ -1,11 +1,11 @@
 # WEB_SEARCH_TOOL — 网页搜索工具
 
-> 实现状态：适配器架构完成，Bing 适配器为当前默认后端
+> 实现状态：适配器架构完成，支持 API / Bing / Brave 三种后端
 > 引用数：核心工具，无 feature flag 门控（始终启用）
 
 ## 一、功能概述
 
-WebSearchTool 让模型可以搜索互联网获取最新信息。原始实现仅支持 Anthropic API 服务端搜索（`web_search_20250305` server tool），在第三方代理端点下不可用。现已重构为适配器架构，新增 Bing 搜索页面解析作为 fallback，确保任何 API 端点都能使用搜索功能。
+WebSearchTool 让模型可以搜索互联网获取最新信息。原始实现仅支持 Anthropic API 服务端搜索（`web_search_20250305` server tool），在第三方代理端点下不可用。现已重构为适配器架构，支持 API 服务端搜索，以及 Bing / Brave 两个 HTML 解析后端，确保任何 API 端点都能使用搜索功能。
 
 ## 二、实现架构
 
@@ -21,24 +21,29 @@ WebSearchTool.call()
        │     └── 使用 web_search_20250305 server tool
        │         通过 queryModelWithStreaming 二次调用 API
        │
-       └── BingSearchAdapter — Bing HTML 抓取 + 正则提取（当前默认）
-             └── 直接抓取 Bing 搜索页 HTML
-                 正则提取 b_algo 块中的标题/URL/摘要
+       ├── BingSearchAdapter  — Bing HTML 抓取 + 正则提取
+       │     └── 直接抓取 Bing 搜索页 HTML
+       │         正则提取 b_algo 块中的标题/URL/摘要
+       │
+       └── BraveSearchAdapter — Brave LLM Context API
+             └── 调用 Brave HTTPS GET 接口
+                 将 grounding payload 映射为标题/URL/摘要
 ```
 
 ### 2.2 模块结构
 
 | 模块 | 文件 | 说明 |
 |------|------|------|
-| 工具入口 | `src/tools/WebSearchTool/WebSearchTool.ts` | `buildTool()` 定义：schema、权限、执行、输出格式化 |
-| 工具 prompt | `src/tools/WebSearchTool/prompt.ts` | 搜索工具的系统提示词 |
-| UI 渲染 | `src/tools/WebSearchTool/UI.tsx` | 搜索结果的终端渲染组件 |
-| 适配器接口 | `src/tools/WebSearchTool/adapters/types.ts` | `WebSearchAdapter` 接口、`SearchResult`/`SearchOptions`/`SearchProgress` 类型 |
-| 适配器工厂 | `src/tools/WebSearchTool/adapters/index.ts` | `createAdapter()` 工厂函数，选择后端 |
-| API 适配器 | `src/tools/WebSearchTool/adapters/apiAdapter.ts` | 封装原有 `queryModelWithStreaming` 逻辑，使用 server tool |
-| Bing 适配器 | `src/tools/WebSearchTool/adapters/bingAdapter.ts` | Bing HTML 抓取 + 正则解析 |
-| 单元测试 | `src/tools/WebSearchTool/__tests__/bingAdapter.test.ts` | 32 个测试用例 |
-| 集成测试 | `src/tools/WebSearchTool/__tests__/bingAdapter.integration.ts` | 真实网络请求验证 |
+| 工具入口 | `packages/builtin-tools/src/tools/WebSearchTool/WebSearchTool.ts` | `buildTool()` 定义：schema、权限、执行、输出格式化 |
+| 工具 prompt | `packages/builtin-tools/src/tools/WebSearchTool/prompt.ts` | 搜索工具的系统提示词 |
+| UI 渲染 | `packages/builtin-tools/src/tools/WebSearchTool/UI.tsx` | 搜索结果的终端渲染组件 |
+| 适配器接口 | `packages/builtin-tools/src/tools/WebSearchTool/adapters/types.ts` | `WebSearchAdapter` 接口、`SearchResult`/`SearchOptions`/`SearchProgress` 类型 |
+| 适配器工厂 | `packages/builtin-tools/src/tools/WebSearchTool/adapters/index.ts` | `createAdapter()` 工厂函数，选择后端 |
+| API 适配器 | `packages/builtin-tools/src/tools/WebSearchTool/adapters/apiAdapter.ts` | 封装原有 `queryModelWithStreaming` 逻辑，使用 server tool |
+| Bing 适配器 | `packages/builtin-tools/src/tools/WebSearchTool/adapters/bingAdapter.ts` | Bing HTML 抓取 + 正则解析 |
+| Brave 适配器 | `packages/builtin-tools/src/tools/WebSearchTool/adapters/braveAdapter.ts` | Brave LLM Context API 适配与结果映射 |
+| 单元测试 | `packages/builtin-tools/src/tools/WebSearchTool/__tests__/bingAdapter.test.ts`, `packages/builtin-tools/src/tools/WebSearchTool/__tests__/braveAdapter*.test.ts`, `packages/builtin-tools/src/tools/WebSearchTool/__tests__/adapterFactory.test.ts` | Bing / Brave 解析与工厂逻辑测试 |
+| 集成测试 | `packages/builtin-tools/src/tools/WebSearchTool/__tests__/bingAdapter.integration.ts`, `packages/builtin-tools/src/tools/WebSearchTool/__tests__/braveAdapter.integration.ts` | 真实网络请求验证 |
 
 ### 2.3 数据流
 
@@ -49,20 +54,18 @@ WebSearchTool.call()
   validateInput() — 校验 query 非空、allowed/block 不共存
        │
        ▼
-  createAdapter() → BingSearchAdapter（当前硬编码）
+  createAdapter() → ApiSearchAdapter | BingSearchAdapter | BraveSearchAdapter
        │
        ▼
   adapter.search(query, { allowedDomains, blockedDomains, signal, onProgress })
        │
        ├── onProgress({ type: 'query_update', query })
        │
-       ├── axios.get(bing.com/search?q=...&setmkt=en-US)
-       │     └── 13 个 Edge 浏览器请求头
+       ├── axios.get(search-engine-url)
+       │     └── API 鉴权请求头
        │
-       ├── extractBingResults(html) — 正则提取 <li class="b_algo"> 块
-       │     ├── resolveBingUrl() — 解码 base64 重定向 URL
-       │     ├── extractSnippet() — 三级降级摘要提取
-       │     └── decodeHtmlEntities() — he.decode
+       ├── extractResults(payload) — 按后端提取结果
+       │     └── grounding → SearchResult[] 映射
        │
        ├── 客户端域名过滤 (allowedDomains / blockedDomains)
        │
@@ -117,19 +120,18 @@ Bing 返回的重定向 URL 格式：`bing.com/ck/a?...&u=a1aHR0cHM6Ly9...`
 
 ## 四、适配器选择逻辑
 
-当前 `createAdapter()` 硬编码返回 `BingSearchAdapter`，原逻辑已注释保留：
+`createAdapter()` 按以下优先级选择后端，并按选中的后端 key 缓存适配器实例：
 
 ```typescript
 export function createAdapter(): WebSearchAdapter {
-  return new BingSearchAdapter()
-  // 注释保留的选择逻辑：
-  // 1. WEB_SEARCH_ADAPTER 环境变量强制指定 api|bing
-  // 2. isFirstPartyAnthropicBaseUrl() → API 适配器
-  // 3. 第三方端点 → Bing 适配器
+  // 1. WEB_SEARCH_ADAPTER=api|bing|brave 显式指定
+  // 2. Anthropic 官方 API Base URL → ApiSearchAdapter
+  // 3. 第三方代理 / 非官方端点 → BingSearchAdapter
 }
 ```
 
-恢复自动选择：取消 `index.ts` 中的注释即可。
+显式指定 `WEB_SEARCH_ADAPTER=brave` 时，会改用 Brave LLM Context API 后端，并要求
+`BRAVE_SEARCH_API_KEY` 或 `BRAVE_API_KEY`。
 
 ## 五、接口定义
 
@@ -174,13 +176,13 @@ interface SearchProgress {
 
 | 文件 | 职责 |
 |------|------|
-| `src/tools/WebSearchTool/WebSearchTool.ts` | 工具定义入口 |
-| `src/tools/WebSearchTool/prompt.ts` | 搜索工具 prompt |
-| `src/tools/WebSearchTool/UI.tsx` | 终端 UI 渲染 |
-| `src/tools/WebSearchTool/adapters/types.ts` | 适配器接口 |
-| `src/tools/WebSearchTool/adapters/index.ts` | 适配器工厂 |
-| `src/tools/WebSearchTool/adapters/apiAdapter.ts` | API 服务端搜索适配器 |
-| `src/tools/WebSearchTool/adapters/bingAdapter.ts` | Bing HTML 解析适配器 |
-| `src/tools/WebSearchTool/__tests__/bingAdapter.test.ts` | 单元测试 (32 cases) |
-| `src/tools/WebSearchTool/__tests__/bingAdapter.integration.ts` | 集成测试 |
+| `packages/builtin-tools/src/tools/WebSearchTool/WebSearchTool.ts` | 工具定义入口 |
+| `packages/builtin-tools/src/tools/WebSearchTool/prompt.ts` | 搜索工具 prompt |
+| `packages/builtin-tools/src/tools/WebSearchTool/UI.tsx` | 终端 UI 渲染 |
+| `packages/builtin-tools/src/tools/WebSearchTool/adapters/types.ts` | 适配器接口 |
+| `packages/builtin-tools/src/tools/WebSearchTool/adapters/index.ts` | 适配器工厂 |
+| `packages/builtin-tools/src/tools/WebSearchTool/adapters/apiAdapter.ts` | API 服务端搜索适配器 |
+| `packages/builtin-tools/src/tools/WebSearchTool/adapters/bingAdapter.ts` | Bing HTML 解析适配器 |
+| `packages/builtin-tools/src/tools/WebSearchTool/__tests__/bingAdapter.test.ts` | 单元测试 (32 cases) |
+| `packages/builtin-tools/src/tools/WebSearchTool/__tests__/bingAdapter.integration.ts` | 集成测试 |
 | `src/tools.ts` | 工具注册 |

docs/features/workflow-scripts.md

@@ -14,17 +14,17 @@ WORKFLOW_SCRIPTS 实现基于文件的多步自动化工作流。用户可以定
 
 | 模块 | 文件 | 状态 |
 |------|------|------|
-| WorkflowTool | `src/tools/WorkflowTool/WorkflowTool.ts` | **Stub** — 空对象 |
-| Workflow 权限 | `src/tools/WorkflowTool/WorkflowPermissionRequest.ts` | **Stub** — 返回 null |
-| 常量 | `src/tools/WorkflowTool/constants.ts` | **Stub** — 空工具名 |
-| 命令创建 | `src/tools/WorkflowTool/createWorkflowCommand.ts` | **Stub** — 空操作 |
-| 捆绑工作流 | `src/tools/WorkflowTool/bundled/` | **缺失** — 目录不存在 |
+| WorkflowTool | `packages/builtin-tools/src/tools/WorkflowTool/WorkflowTool.ts` | **部分实现** — tool schema + 渲染完整，call 返回运行时缺失提示 |
+| Workflow 权限 | `packages/builtin-tools/src/tools/WorkflowTool/WorkflowPermissionRequest.tsx` | **部分实现** — 权限请求组件 |
+| 常量 | `packages/builtin-tools/src/tools/WorkflowTool/constants.ts` | **实现** — 工具名 + 目录名 + 文件扩展名常量 |
+| 命令创建 | `packages/builtin-tools/src/tools/WorkflowTool/createWorkflowCommand.ts` | **实现** — 扫描 .claude/workflows/ 目录创建 Command 对象 |
+| 捆绑工作流 | `packages/builtin-tools/src/tools/WorkflowTool/bundled/index.ts` | **实现** — 内置工作流初始化 |
 | 本地工作流任务 | `src/tasks/LocalWorkflowTask/LocalWorkflowTask.ts` | **Stub** — 类型 + 空操作 |
 | UI 任务组件 | `src/components/tasks/src/tasks/LocalWorkflowTask/` | **Stub** — 空导出 |
 | 详情对话框 | `src/components/tasks/WorkflowDetailDialog.ts` | **Stub** — 返回 null |
 | 任务注册 | `src/tasks.ts` | **布线** — 动态加载 |
-| 工具注册 | `src/tools.ts` | **布线** — 包含 bundled 工作流初始化 |
-| 命令注册 | `src/commands.ts` | **布线** — `/workflows` 命令 |
+| 工具注册 | `src/tools.ts` | **布线** — 动态加载 + bundled 工作流初始化 (行 131-134,235) |
+| 命令注册 | `src/commands.ts` | **布线** — `/workflows` 命令 (行 93-95,395,460) |
 
 ### 2.2 预期数据流
 
@@ -69,13 +69,9 @@ steps:
 
 | 优先级 | 模块 | 工作量 | 说明 |
 |--------|------|--------|------|
-| 1 | `WorkflowTool.ts` | 大 | Schema 定义 + 多步执行引擎 |
-| 2 | `bundled/index.js` | 中 | 内置工作流定义（initBundledWorkflows） |
-| 3 | `createWorkflowCommand.ts` | 中 | 从文件解析创建命令对象 |
-| 4 | `LocalWorkflowTask.ts` | 大 | 步骤协调、kill/skip/retry |
-| 5 | `WorkflowDetailDialog.ts` | 中 | 进度详情 UI |
-| 6 | `WorkflowPermissionRequest.ts` | 小 | 权限对话框 |
-| 7 | `constants.ts` | 小 | 工具名常量 |
+| 1 | `WorkflowTool.ts` call 方法 | 中 | 实际工作流执行逻辑（当前返回运行时缺失提示） |
+| 2 | `LocalWorkflowTask.ts` | 大 | 步骤协调、kill/skip/retry |
+| 3 | `WorkflowDetailDialog.ts` | 中 | 进度详情 UI |
 
 ## 四、关键设计决策
 
@@ -95,11 +91,12 @@ FEATURE_WORKFLOW_SCRIPTS=1 bun run dev
 
 | 文件 | 职责 |
 |------|------|
-| `src/tools/WorkflowTool/WorkflowTool.ts` | 工具定义（stub） |
-| `src/tools/WorkflowTool/WorkflowPermissionRequest.ts` | 权限对话框（stub） |
-| `src/tools/WorkflowTool/constants.ts` | 常量（stub） |
-| `src/tools/WorkflowTool/createWorkflowCommand.ts` | 命令创建（stub） |
+| `packages/builtin-tools/src/tools/WorkflowTool/WorkflowTool.ts` | 工具定义（部分实现） |
+| `packages/builtin-tools/src/tools/WorkflowTool/WorkflowPermissionRequest.tsx` | 权限请求组件 |
+| `packages/builtin-tools/src/tools/WorkflowTool/constants.ts` | 常量定义 |
+| `packages/builtin-tools/src/tools/WorkflowTool/createWorkflowCommand.ts` | 命令创建（已实现） |
+| `packages/builtin-tools/src/tools/WorkflowTool/bundled/index.ts` | 内置工作流初始化 |
 | `src/tasks/LocalWorkflowTask/LocalWorkflowTask.ts` | 任务协调（stub） |
 | `src/components/tasks/WorkflowDetailDialog.ts` | 详情对话框（stub） |
-| `src/tools.ts:127-132` | 工具注册 |
-| `src/commands.ts:86-89` | 命令注册 |
+| `src/tools.ts:131-134,235` | 工具注册 |
+| `src/commands.ts:93-95,395,460` | 命令注册 |

docs/internals/ant-only-world.mdx

@@ -1,53 +1,31 @@
 ---
-title: "Ant 特权世界 - Anthropic 员工专属功能"
-description: "完整记录 Claude Code 身份门控层：USER_TYPE === 'ant' 时解锁的专属工具、命令、API 和代号体系，揭示内外部构建的差异。"
-keywords: ["Ant 特权", "USER_TYPE", "身份门控", "内部功能", "Anthropic 员工"]
+title: "Ant 特权世界"
+description: "Anthropic 内部构建与公开发布版本的差异。理解身份门控机制、Ant-Only 工具/命令和 Beta Header 的分层设计。"
+keywords: ["Ant 特权", "USER_TYPE", "身份门控", "内部功能"]
 ---
 
-{/* 本章目标：完整记录身份门控层——ant 构建独享的一切 */}
-
 ## 什么是 Ant
 
-`USER_TYPE` 是一个构建时常量，通过 Bun 打包器的 `--define` 注入。在 Anthropic 的内部构建中它被设为 `'ant'`，在公开发布的版本中是 `'external'`：
+Claude Code 有两种构建：Anthropic 员工使用的内部构建（`USER_TYPE === 'ant'`）和公开发布的外部构建（`USER_TYPE === 'external'`）。
 
-```typescript
-// 反编译版本（src/types/global.d.ts 第 63 行）
-// Build-time constants BUILD_TARGET/BUILD_ENV/INTERFACE_TYPE — removed (zero runtime usage)
-```
+`USER_TYPE` 是构建时常量，通过 Bun 的 `--define` 注入。外部构建中，所有 `process.env.USER_TYPE === 'ant'` 判断被编译器折叠为 `false`，后续代码被死代码消除（DCE）移除。
 
-`BUILD_TARGET` 等构建时常量在反编译版本中已被移除。`USER_TYPE` 通过 Bun 的 `--define` 或环境变量注入，Bun 会进行**常量折叠**——所有 `process.env.USER_TYPE === 'ant'` 在外部构建中直接变为 `false`，后续代码被 DCE 移除。但在反编译版本中，这些代码保留完整。
-
-`USER_TYPE === 'ant'` 在代码库中出现 **377+ 次**（含 `=== 'ant'` 291 次、`(process.env.USER_TYPE) === 'ant'` 86 次），另有 `!== 'ant'` 53 次、其他引用约 35 次，总计 **465 处引用**，控制着工具、命令、API、UI 等方方面面。
+这个门控在代码库中出现 410+ 处，控制着工具、命令、API、UI 等方方面面。
 
 ## Ant-Only 工具
 
-以下工具仅在内部构建中被加载到工具注册表：
+| 工具 | 用途 |
+|------|------|
+| **REPLTool** | 高级 REPL 模式——在 VM 中包装其他工具 |
+| **ConfigTool** | 交互式配置编辑器，包含 Gates 标签页覆盖 feature flags |
+| **SuggestBackgroundPRTool** | 建议在后台创建 PR |
+| **TungstenTool** | 基于 tmux 的终端面板工具 |
 
-| 工具 | 代码位置 | 用途 |
-|------|---------|------|
-| **REPLTool** | `src/tools/REPLTool/` | 高级 REPL 模式——在 VM 中包装 Bash/Read/Edit/Glob/Grep/Agent 等工具 |
-| **SuggestBackgroundPRTool** | `src/tools/SuggestBackgroundPRTool/` | 建议在后台创建 PR |
-| **ConfigTool** | `src/tools/ConfigTool/` | 交互式配置编辑器，包含 Gates 标签页用于覆盖 GrowthBook flags |
-| **TungstenTool** | `src/tools/TungstenTool/` | 基于 tmux 的终端面板工具（反编译版中已 stub） |
-
-```typescript
-// src/tools.ts 第 14-24 行——条件导入 + Dead Code Elimination 标记
-// Dead code elimination: conditional import for ant-only tools
-/* eslint-disable custom-rules/no-process-env-top-level, @typescript-eslint/no-require-imports */
-const REPLTool =
-  process.env.USER_TYPE === 'ant'
-    ? require('./tools/REPLTool/REPLTool.js').REPLTool
-    : null
-const SuggestBackgroundPRTool =
-  process.env.USER_TYPE === 'ant'
-    ? require('./tools/SuggestBackgroundPRTool/SuggestBackgroundPRTool.js')
-        .SuggestBackgroundPRTool
-    : null
-```
+**设计考量**：这些工具要么涉及内部基础设施（如 GrowthBook flag 覆盖），要么需要 Anthropic 特有的 API 支持。对外部用户暴露它们没有意义——甚至可能引起混淆。
 
 ## Ant-Only 命令
 
-`src/commands.ts` 注册了 **28** 个仅在内部构建中可用的斜杠命令（`INTERNAL_ONLY_COMMANDS`，lines 225-254），在 `USER_TYPE === 'ant' && !IS_DEMO` 时才加载（line 343-345）：
+内部构建注册了 24+ 个额外的斜杠命令，覆盖调试、实验、工作流和基础设施：
 
 <AccordionGroup>
   <Accordion title="调试类">
@@ -56,14 +34,6 @@ const SuggestBackgroundPRTool =
     - `debugToolCall` — 调试工具调用
     - `env` — 显示环境变量
     - `mockLimits` — 模拟速率限制
-    - `resetLimits` — 重置速率限制
-    - `resetLimitsNonInteractive` — 重置速率限制（非交互式）
-  </Accordion>
-  <Accordion title="实验类">
-    - `bughunter` — Bug 猎人模式
-    - `goodClaude` — 质量评估工具
-    - `antTrace` — 追踪分析
-    - `perfIssue` — 性能问题诊断
   </Accordion>
   <Accordion title="工作流类">
     - `commit` — 快速提交
@@ -72,139 +42,75 @@ const SuggestBackgroundPRTool =
     - `autofixPr` — 自动修复 PR 中的问题
     - `share` — 分享会话
     - `summary` — 生成摘要
-    - `subscribePr` — 订阅 PR（需要 `KAIROS_GITHUB_WEBHOOKS` feature flag）
-    - `forceSnip` — 强制截断历史（需要 `HISTORY_SNIP` feature flag）
-    - `ultraplan` — 超级规划（需要 `ULTRAPLAN` feature flag）
   </Accordion>
   <Accordion title="基础设施类">
     - `backfillSessions` — 回填会话数据
     - `bridgeKick` — 重启 Bridge 连接
     - `oauthRefresh` — 刷新 OAuth Token
-    - `teleport` — 传送到指定上下文
-    - `onboarding` — 新手引导
-    - `agentsPlatform` — Agents 平台管理
-    - `version` — 内部版本详情
-    - `initVerifiers` — 初始化验证器
   </Accordion>
 </AccordionGroup>
 
-<Note>
-这些命令在 `IS_DEMO` 模式下也会被隐藏，防止在演示环境中暴露内部功能。
-</Note>
+这些命令在演示模式（`IS_DEMO`）下也被隐藏，防止在公开演示中暴露内部功能。
 
-## Beta API Headers
+## Beta API Headers 的分层
 
-Claude Code 向 API 发送的 beta headers 分布在 `src/constants/betas.ts`（主注册表）和其他文件中，按可见性分为以下几类：
+Claude Code 向 API 发送的 beta headers 按可见性分为多层：
 
-### 公开 Headers（所有构建均发送）
+### 公开 Headers（所有构建）
 
-| Header | 功能 | 额外条件 |
-|--------|------|----------|
-| `claude-code-20250219` | Claude Code 标识 | 非 Haiku 时始终发送；Haiku 在 agentic 模式下也发送 |
-| `effort-2025-11-24` | 推理强度控制 | 动态注入 |
-| `task-budgets-2026-03-13` | 任务预算 | 始终通过 `addAgenticBetas()` 注入 |
-| `fast-mode-2026-02-01` | 快速模式 | 通过 sticky-on latch 动态注入 |
-| `advisor-tool-2026-03-01` | 顾问工具 | 启用 advisor 时动态注入 |
-| `advanced-tool-use-2025-11-20` | 工具搜索（1P） | Claude API / Foundry |
-| `tool-search-tool-2025-10-19` | 工具搜索（3P） | Vertex / Bedrock |
-
-### 模型能力相关（有条件发送）
-
-| Header | 功能 | 条件 |
-|--------|------|------|
-| `interleaved-thinking-2025-05-14` | 交错思考模式 | 模型支持 ISP 且未禁用 |
-| `context-1m-2025-08-07` | 1M 上下文窗口 | 模型支持 1M context |
-| `context-management-2025-06-27` | 上下文管理 | Claude 4+ 或 ant 手动启用 |
-| `structured-outputs-2025-12-15` | 结构化输出 | Claude 4.5/4.6 + GrowthBook `tengu_tool_pear` |
-| `web-search-2025-03-05` | 网页搜索 | Vertex (Claude 4+) / Foundry |
-| `redact-thinking-2026-02-12` | 思维摘要/脱敏 | ISP 模型 + 非交互 + 未强制显示思维 |
-| `prompt-caching-scope-2026-01-05` | 提示缓存作用域 | firstParty/foundry + 全局缓存 |
+| Header | 功能 |
+|--------|------|
+| `claude-code-20250219` | Claude Code 标识 |
+| `effort-2025-11-24` | 推理强度控制 |
+| `interleaved-thinking-2025-05-14` | 交错思考模式 |
+| `context-1m-2025-08-07` | 1M 上下文窗口 |
 
 ### Ant-Only Headers
 
-| Header | 功能 | 条件 |
-|--------|------|------|
-| **`cli-internal-2026-02-09`** | 内部 CLI 功能 | `USER_TYPE === 'ant'` + CLI 入口 |
-| **`token-efficient-tools-2026-03-28`** | Token 高效工具 | `USER_TYPE === 'ant'` + GrowthBook `tengu_amber_json_tools` |
+| Header | 功能 |
+|--------|------|
+| `cli-internal-2026-02-09` | 内部 CLI 功能 |
+| `token-efficient-tools-2026-03-28` | Token 高效工具 |
 
-### Feature Flag Gated
-
-| Header | 功能 | 条件 |
-|--------|------|------|
-| **`afk-mode-2026-01-31`** | AFK 模式（离开键盘自动审批） | `feature('TRANSCRIPT_CLASSIFIER')` |
-
-### 其他特殊 Headers
-
-| Header | 功能 | 来源 |
-|--------|------|------|
-| `oauth-2025-04-20` | OAuth 订阅者标识 | `src/constants/oauth.ts`，Pro/Max/Team/Enterprise |
-| `environments-2025-11-01` | Bridge 环境 API | `src/bridge/bridgeApi.ts`，仅 Bridge 模式 |
-
-```typescript
-// src/constants/betas.ts — 常量定义
-export const TOKEN_EFFICIENT_TOOLS_BETA_HEADER =
-  'token-efficient-tools-2026-03-28'
-export const CLI_INTERNAL_BETA_HEADER =
-  process.env.USER_TYPE === 'ant' ? 'cli-internal-2026-02-09' : ''
-```
-
-```typescript
-// src/utils/betas.ts 第 315-321 行——TOKEN_EFFICIENT_TOOLS 的实际门控逻辑
-if (
-  process.env.USER_TYPE === 'ant' &&
-  includeFirstPartyOnlyBetas &&
-  tokenEfficientToolsEnabled  // GrowthBook 'tengu_amber_json_tools' flag
-) {
-  betaHeaders.push(TOKEN_EFFICIENT_TOOLS_BETA_HEADER)
-}
-```
-
-`cli-internal` header 意味着 Anthropic 的 API 服务端也维护着一套 ant-only 的服务端行为——这不仅仅是客户端的门控。`token-efficient-tools` 进一步需要 GrowthBook flag 开启，说明 Ant 员工内部也有分层灰度。
+**设计洞察**：`cli-internal` header 说明 Anthropic 的 API 服务端也维护着 ant-only 的行为——这不只是客户端门控，而是端到端的功能隔离。
 
 ## 内部代号体系
 
-Anthropic 有浓厚的"动物命名"文化：
+Anthropic 有"动物命名"文化：
 
-| 代号 | 身份 | 出处 |
-|------|------|------|
-| **Tengu**（天狗） | Claude Code 项目代号 | 所有 GrowthBook flags 的 `tengu_` 前缀、分析事件名称 |
-| **Capybara**（水豚） | 模型代号 | `src/constants/prompts.ts` 中被 Undercover Mode 屏蔽的名称 |
-| **Fennec**（耳廓狐） | 已退役模型别名 | `src/migrations/migrateFennecToOpus.ts`——曾用名已迁移到 Opus |
+| 代号 | 身份 |
+|------|------|
+| **Tengu**（天狗） | Claude Code 项目代号（所有内部 flag 的 `tengu_` 前缀） |
+| **Capybara**（水豚） | 模型代号 |
+| **Fennec**（耳廓狐） | 已退役模型别名（已迁移到 Opus） |
 
-这些代号通过 Undercover Mode 在公开仓库的 commit 中被严格过滤。
+这些代号通过 Undercover Mode 在公开仓库的 commit 中被过滤。
 
 ## 环境变量开关
 
-除了 `USER_TYPE`，还有一系列精细的环境变量控制各项功能：
-
 <AccordionGroup>
   <Accordion title="功能禁用开关">
     - `CLAUDE_CODE_SIMPLE` — 简化模式（禁用高级功能）
     - `CLAUDE_CODE_DISABLE_THINKING` — 禁用 thinking
-    - `DISABLE_INTERLEAVED_THINKING` — 禁用交错思考
-    - `DISABLE_COMPACT` — 禁用消息压缩
     - `DISABLE_AUTO_COMPACT` — 禁用自动压缩
     - `CLAUDE_CODE_DISABLE_AUTO_MEMORY` — 禁用自动记忆
-    - `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` — 禁用后台任务
     - `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` — 禁用实验性 beta headers
-    - `USE_API_CONTEXT_MANAGEMENT` — 上下文管理工具清除（需 ant）
   </Accordion>
   <Accordion title="功能启用开关">
     - `CLAUDE_CODE_VERIFY_PLAN` — 启用 VerifyPlanExecutionTool
-    - `ENABLE_LSP_TOOL` — 启用 LSP 语言服务器工具
+    - `ENABLE_LSP_TOOL` — 启用 LSP 工具
     - `CLAUDE_CODE_UNDERCOVER` — 强制启用 Undercover Mode
-    - `CLAUDE_CODE_TERMINAL_RECORDING` — 启用终端录制（asciicast）
-    - `CLAUDE_CODE_ABLATION_BASELINE` — 启用基线对照模式
   </Accordion>
   <Accordion title="环境配置">
-    - `CLAUDE_CODE_REMOTE` — 远程执行模式（自动增加堆内存限制）
+    - `CLAUDE_CODE_REMOTE` — 远程执行模式
     - `CLAUDE_CODE_COORDINATOR_MODE` — 启用 Coordinator 模式
-    - `CLAUDE_INTERNAL_FC_OVERRIDES` — GrowthBook flag 覆盖（ant-only）
     - `IS_DEMO` — 演示模式（隐藏内部命令和敏感信息）
-    - `CLAUDE_CODE_ENTRYPOINT` — 入口类型标识（`cli` | 其他）
   </Accordion>
 </AccordionGroup>
 
-<Note>
-`ABLATION_BASELINE` 特别有趣——它同时关闭 thinking、compaction、auto-memory 和 background tasks，用于测量这些高级功能对 AI 表现的**因果影响**。这是一个严肃的"科学对照实验"工具。
-</Note>
+`CLAUDE_CODE_ABLATION_BASELINE` 特别有趣——它同时关闭 thinking、compaction、auto-memory 和 background tasks，用于测量这些高级功能对 AI 表现的**因果影响**。这是一个严肃的"科学对照实验"工具。
+
+## 接下来
+
+- **Feature Flags** — 理解功能开关的设计
+- **权限模型** — 理解身份门控与权限的协作

docs/internals/feature-flags.mdx

@@ -1,34 +1,28 @@
 ---
-title: "88 个 Feature Flags - 构建时特性门控全解"
-description: "深入剖析 Claude Code 的 88+ 个构建时 feature flags：bun:bundle 编译时门控机制，揭示被编译器删除的隐藏功能模块。"
-keywords: ["feature flags", "特性标志", "构建时门控", "bun:bundle", "条件编译"]
+title: "Feature Flags"
+description: "88+ 个构建时特性门控：理解 feature() 的编译时求值机制、死代码消除和 flags 的分类全景。"
+keywords: ["feature flags", "特性标志", "构建时门控", "条件编译"]
 ---
 
-{/* 本章目标：完整梳理构建时 feature flag 系统的机制和所有 flag 的分类 */}
+## 核心机制
 
-## feature() 是什么
+Claude Code 使用 Bun 打包器的编译时特性门控。代码中通过 `import { feature } from 'bun:bundle'` 导入 `feature()` 函数，在构建时被求值——返回 `true` 的代码保留，返回 `false` 的代码被**死代码消除（DCE）**彻底移除。
 
-Claude Code 使用 Bun 打包器的 `bun:bundle` 模块提供编译时特性门控：
+**设计洞察**：这不是运行时的 if-else——feature flag 在构建时就已经决定了哪些代码存在。外部构建中不存在的功能不是"被禁用"，而是"从未编译进去"。这是一种零运行时开销的特性门控。
 
-```typescript
-// 源码中的用法（src/tools.ts 等）
-import { feature } from 'bun:bundle'
+## 三种使用模式
 
-const SleepTool = feature('PROACTIVE') || feature('KAIROS')
-  ? require('./tools/SleepTool/SleepTool.js').SleepTool
-  : null
-```
+### 1. 条件加载工具
 
-在 Anthropic 的内部构建中，`feature()` 在打包时被求值——返回 `true` 的代码会被保留，返回 `false` 的代码会被 **Dead Code Elimination (DCE)** 彻底移除。
+当 flag 为 `false` 时，`require()` 调用被 DCE 移除，工具不会出现在可用工具列表中。不增加打包体积。
 
-在我们的反编译版本中，这个函数被兜底为：
+### 2. 条件注册命令
 
-```typescript
-// src/entrypoints/cli.tsx 第 3 行
-const feature = (_name: string) => false;
-```
+斜杠命令只在对应 flag 启用时注册。用户不会看到不可用的命令。
 
-这意味着所有 88+ 个 feature flag 后的代码**在运行时永远不会执行**，但代码本身完整保留，可以阅读和分析。
+### 3. 条件启用 API 特性
+
+控制发送给 API 的 beta header。未启用的功能不会向服务端声明能力。
 
 ## Flags 分类全景
 
@@ -70,46 +64,14 @@ const feature = (_name: string) => false;
   </Card>
 </CardGroup>
 
-## 代码中的典型模式
-
-Feature flags 在代码中主要有三种使用模式：
-
-### 模式一：条件加载工具
-
-```typescript
-// src/tools.ts — 最常见的模式
-const MonitorTool = feature('MONITOR_TOOL')
-  ? require('./tools/MonitorTool/MonitorTool.js').MonitorTool
-  : null
-```
-
-当 flag 为 `false` 时，`require()` 调用被 DCE 移除，工具不会出现在可用工具列表中。
-
-### 模式二：条件注册命令
-
-```typescript
-// src/commands.ts — 注册斜杠命令
-if (feature('VOICE_MODE')) {
-  commands.push({ name: 'voice', description: '...' })
-}
-```
-
-### 模式三：条件启用 API 特性
-
-```typescript
-// src/constants/betas.ts — 控制发送给 API 的 beta header
-export const AFK_MODE_BETA_HEADER = feature('TRANSCRIPT_CLASSIFIER')
-  ? 'afk-mode-2026-01-31'
-  : ''
-```
-
-<Note>
-由于 `feature()` 在构建时求值，被 DCE 移除的代码不会增加最终打包体积。但在反编译版本中，这些代码全部保留——这正是我们能够进行完整分析的原因。
-</Note>
-
 ## 有趣的发现
 
 - **KAIROS 家族**最庞大——6 个相关 flag 控制从核心功能到推送通知的方方面面
-- **ABLATION_BASELINE** 是用于"科学对照实验"的——它会关闭 thinking、compaction、auto-memory 等高级功能，测量裸 API 调用的基线性能
-- **BUDDY** 是一个 AI 吉祥物/精灵系统——在 `src/buddy/` 目录下有完整实现
+- **ABLATION_BASELINE** 是用于"科学对照实验"的——关闭 thinking、compaction、auto-memory 等高级功能，测量裸 API 调用的基线性能
+- **BUDDY** 是一个 AI 吉祥物/精灵系统
 - **ULTRAPLAN** 和 **ULTRATHINK** 暗示着比当前 extended thinking 更高级的推理模式
+
+## 接下来
+
+- **Ant 特权世界** — 理解 USER_TYPE 门控与 feature flags 的关系
+- **Auto Mode** — 理解 TRANSCRIPT_CLASSIFIER flag 控制的自动权限分类

docs/internals/growthbook-ab-testing.mdx

@@ -19,7 +19,7 @@ keywords: ["GrowthBook", "A/B 测试", "运行时门控", "tengu", "渐进式发
 
 ## 集成架构
 
-GrowthBook 的完整实现位于 `src/services/analytics/growthbook.ts`（1156 行），工作流程如下：
+GrowthBook 的完整实现位于 `src/services/analytics/growthbook.ts`（1258 行），工作流程如下：
 
 <Steps>
   <Step title="启动时获取远程配置">

docs/internals/hidden-features.mdx

@@ -84,7 +84,7 @@ keywords: ["隐藏功能", "未公开功能", "秘密功能", "Claude Code 彩
   <Accordion title="VOICE_MODE：语音交互">
     **门控**: `feature('VOICE_MODE')`
 
-    代码中存在语音输入模式的注册点，但核心实现依赖于 `audio-napi` 包（在反编译版本中已 stub）：
+    代码中存在语音输入模式的注册点，核心实现依赖 `audio-capture-napi` 包（已恢复）：
 
     - 通过 `/voice` 命令激活
     - "按住说话"（hold-to-talk）交互模式

docs/introduction/architecture-overview.mdx

@@ -1,112 +1,131 @@
 ---
-title: "架构全景 - Claude Code 五层架构详解"
-description: "从交互层到基础设施层，详解 Claude Code 的五层架构设计。基于 src/main.tsx、src/QueryEngine.ts、src/query.ts、src/tools.ts、src/services/api/claude.ts 的源码级数据流分析。"
-keywords: ["Claude Code 架构", "五层架构", "QueryEngine", "Agentic Loop", "数据流"]
+title: "架构总览"
+description: "从交互层到通信层，理解 Claude Code 的五层架构设计。每层的职责、边界和设计考量。"
+keywords: ["Claude Code 架构", "五层架构", "Agentic Loop", "数据流"]
+og:image: "https://ccb.agent-aura.top/docs/images/og-cover.png"
 ---
 
-{/* 本章目标：一张图讲清楚整体架构，为后续章节建立坐标系 */}
-
 ## 五层架构
 
-Claude Code 从上到下分为五个层次，每一层职责清晰、边界分明：
+Claude Code 从上到下分为五个层次。每一层职责清晰、边界分明，层与层之间通过明确的接口通信。
 
 <Frame caption="Claude Code 五层架构">
   <img src="/docs/images/architecture-layers.png" alt="Claude Code 五层架构图" />
 </Frame>
 
-| 层次 | 职责 | 入口源码 | 关键词 |
-|------|------|---------|--------|
-| **交互层** | 终端 UI、用户输入、消息展示 | `src/screens/REPL.tsx` | React/Ink、PromptInput |
-| **编排层** | 多轮对话、会话持久化、成本追踪 | `src/QueryEngine.ts` | QueryEngine、transcript |
-| **核心循环层** | 单轮：发请求 → 拿响应 → 执行工具 → 循环 | `src/query.ts` | Agentic Loop、State |
-| **工具层** | AI 的"双手"——读写文件、执行命令 | `src/tools.ts` → `src/Tool.ts` | Tool 接口、MCP |
-| **通信层** | 与 Claude API 的流式通信 | `src/services/api/claude.ts` | Streaming、Provider |
+| 层次 | 职责 | 设计考量 |
+|------|------|----------|
+| **交互层** | 终端 UI、用户输入、消息展示 | 为什么用 React/Ink 而不是 readline？因为需要组件化渲染工具权限确认、进度条等复杂 UI |
+| **编排层** | 多轮对话管理、会话持久化、成本追踪 | 为什么需要独立的编排层？因为 agentic loop 本身不应该关心"会话保存"和"token 计费" |
+| **核心循环层** | 单轮：发请求 → 拿响应 → 执行工具 → 循环 | 这是整个系统的心脏。为什么用 AsyncGenerator？因为流式输出需要逐步 yield，工具执行需要可取消 |
+| **工具层** | AI 的"双手"——读写文件、执行命令等 50+ 工具 | 为什么工具是独立层？因为工具可以动态增减（MCP 扩展），不应该硬编码在核心循环中 |
+| **通信层** | 与 Claude API 的流式通信 | 为什么支持 7 种 Provider？因为不同用户使用不同的 API 端点（直连、AWS Bedrock、Google Vertex 等） |
 
-## 一条主数据流的源码追踪
+### 层间通信原则
+
+- **交互层 → 编排层**：用户消息和指令（如斜杠命令）
+- **编排层 → 核心循环层**：上下文参数（消息历史、工具列表、权限上下文）
+- **核心循环层 → 工具层**：工具调用请求（工具名 + 参数）
+- **工具层 → 核心循环层**：工具执行结果
+- **核心循环层 → 通信层**：API 请求（消息数组 + 系统提示 + 工具定义）
+- **通信层 → 核心循环层**：流式响应事件
+
+每层只依赖下一层的接口，不跨层访问。这种约束使得：
+- 通信层可以替换 Provider 而不影响核心循环
+- 工具层可以新增工具而不影响编排逻辑
+- 交互层可以替换为 Web UI 而不影响底层
+
+## 核心数据流
 
 <Frame caption="核心数据流">
   <img src="/docs/images/data-flow.png" alt="Claude Code 核心数据流" />
 </Frame>
 
-整个系统的运转可以浓缩为一条核心数据流，以下是每一步对应的源码路径：
+整个系统的运转可以浓缩为一条循环数据流。以下是每一步的设计意图：
 
-### 1. 用户输入 → REPL
+### 1. 用户输入 → 交互层
 
-`src/screens/REPL.tsx` 是基于 React/Ink 的终端 UI 组件。用户输入经 `processUserInput()`（`src/utils/processUserInput/processUserInput.ts`）处理，支持斜杠命令、文件附件、图片等。
+用户输入经过预处理管道：斜杠命令解析、文件附件处理、图片编码等。设计上，输入处理是可扩展的——新的输入类型（如语音）只需要在预处理管道中添加一个处理器。
 
-### 2. QueryEngine 编排
+### 2. 交互层 → 编排层
 
-`src/QueryEngine.ts` 是 REPL 与 `query()` 之间的中间层，管理：
-- **会话状态**：消息数组、工具权限上下文（`ToolPermissionContext`）、文件历史快照
-- **成本追踪**：`accumulateUsage()` / `getTotalCost()` 累计 token 用量
-- **Transcript 持久化**：`recordTranscript()` 将对话序列化到磁盘，支持 `--resume`
-- **文件历史**：`fileHistoryMakeSnapshot()` 在修改前创建快照，支持 undo
+编排层是会话的"大脑"。它管理三类关键状态：
+- **对话状态**：消息数组、工具权限上下文——决定 AI 看到什么
+- **成本状态**：token 用量累计——决定何时触发压缩或警告用户
+- **持久化状态**：对话序列化到磁盘——支持会话恢复和 undo
 
-关键方法：`queryEngine.query()` 构造 `QueryParams`，调用 `query()` 异步生成器。
+### 3. 编排层 → 核心循环（Agentic Loop）
 
-### 3. Agentic Loop（`src/query.ts`）
-
-`query()` 是一个 `AsyncGenerator`，`while(true)` 循环的每次迭代包含：
+核心循环是一个 `while(true)` 的迭代：
 
 ```
-① 上下文预处理管道：
-   applyToolResultBudget → snipCompact → microcompact → contextCollapse → autocompact
-
-② 流式 API 调用：
-   deps.callModel() → AsyncGenerator<StreamEvent | Message>
-   收集 assistantMessages[]、toolUseBlocks[]
-
-③ 工具执行：
-   StreamingToolExecutor（并行） 或 runTools（串行）
-   → toolResults[]
-
-④ 终止/继续判定：
-   needsFollowUp ? continue : return { reason }
+上下文预处理 → API 调用 → 解析响应 → 工具执行 → 结果回传 → 再次调用 → 循环
 ```
 
-完整的状态机通过 `State` 类型（`src/query.ts:204`）在迭代间传递，包含 10 个字段（messages、autoCompactTracking、maxOutputTokensRecoveryCount 等）。
+**上下文预处理管道**是循环中最精巧的部分。在每次 API 调用前，系统会依次检查：
+- 单条工具输出是否过长 → 截断
+- 对话历史是否接近 token 上限 → 自动压缩
+- 是否需要紧急压缩 → API 返回 token 超限错误时触发
 
-### 4. 工具层（`src/tools.ts` → `src/Tool.ts`）
+这套管道确保 AI 始终在有效的上下文窗口内工作。
 
-`getAllBaseTools()`（`src/tools.ts:191`）组装 50+ 工具列表，经过 `filterToolsByDenyRules()` 权限过滤后传给 API。
+### 4. 核心循环 → 工具层
 
-每个工具实现 `Tool<Input, Output, Progress>` 接口（`src/Tool.ts:362`），核心方法链：
-```
-validateInput() → canUseTool()（UI 层）→ checkPermissions() → call() → ToolResult
-```
+工具执行支持**并行和串行两种模式**。多个独立的工具调用可以并行执行（如同时读两个文件），有依赖关系的调用则串行执行。这个设计直接影响用户体验——并行意味着更快的响应速度。
 
-### 5. 通信层（`src/services/api/claude.ts`）
+### 5. 工具层 → 核心循环 → 通信层
 
-API 客户端支持 4 种 Provider：
-- **Anthropic Direct**：默认
-- **AWS Bedrock**：`ANTHROPIC_BEDROCK_BASE_URL`
-- **Google Vertex**：`ANTHROPIC_VERTEX_PROJECT_ID`
-- **Azure**：通过自定义 base URL
+工具执行结果回传到核心循环，拼入消息数组，再次调用 API。AI 根据工具结果决定：
+- 继续调用工具（任务未完成）
+- 返回最终回答（任务完成）
+- 请求用户输入（需要决策）
 
-`deps.callModel()` 发起流式请求，返回 `BetaRawMessageStreamEvent` 事件流。支持 Prompt Cache（`cache_control`）、thinking blocks、multi-turn tool use。
+### 6. 终止条件
+
+循环不是无限运行的。终止条件包括：
+- AI 不再请求工具调用（任务完成）
+- 用户主动中断
+- 达到最大 turn 数限制
+- Token 预算耗尽
 
 ## 四个核心设计原则
 
-<AccordionGroup>
-  <Accordion title="流式优先 (Streaming-first)">
-    所有 API 通信都是流式的——`deps.callModel()` 返回 AsyncGenerator，用户看到 AI "逐字打出"回答。StreamingToolExecutor 在流式过程中就开始并行执行工具，不等流结束。模型降级（Fallback）时，已收集的 assistantMessages 被标记为 tombstone 并清空，重试整个流式请求。
-  </Accordion>
-  <Accordion title="工具即能力 (Tool as Capability)">
-    每个工具是 `Tool<Input, Output, Progress>` 结构化类型，通过 `buildTool()` 工厂创建。`getTools()` 在每次 API 调用时组装（非全局缓存），因为 `isEnabled()` 可能随运行时状态变化。MCP 工具通过 `mcpInfo` 字段标记来源，支持 server 级别的 blanket deny。
-  </Accordion>
-  <Accordion title="权限即边界 (Permission as Boundary)">
-    每次工具调用经过 `validateInput() → checkPermissions()` 双重检查。权限规则从 5 个来源汇聚（session → project → user → managed → default），支持工具名、命令模式、路径前缀等匹配方式。Plan Mode 通过 `prepareContextForPlanMode()` 切换为只读模式，退出时自动恢复。
-  </Accordion>
-  <Accordion title="上下文即记忆 (Context as Memory)">
-    System Prompt 由 `fetchSystemPromptParts()` 动态组装，包含 CLAUDE.md、git 状态、日期、MCP 服务器列表。Auto-compact 在每轮迭代前评估 token 阈值，超出时触发压缩。压缩后的摘要通过 `buildPostCompactMessages()` 替换原始消息，`taskBudgetRemaining` 跨压缩边界累计。
-  </Accordion>
-</AccordionGroup>
+### 流式优先（Streaming-first）
 
-## 入口与引导
+所有 API 通信都是流式的。用户看到 AI "逐字打出"回答，工具执行在流式过程中就开始并行执行，不需要等流结束。
 
-| 入口 | 文件 | 说明 |
-|------|------|------|
-| CLI 启动 | `src/entrypoints/cli.tsx` | 注入 `feature()` polyfill（始终返回 false）、MACRO 全局变量 |
-| 命令定义 | `src/main.tsx` | Commander.js 解析参数，初始化 auth/analytics/policy |
-| 一次性初始化 | `src/entrypoints/init.ts` | 遥测配置、信任对话框 |
-| 管道模式 | `src/main.tsx` `-p` flag | `echo "say hello" \| bun run dev -p` |
+当模型需要降级（如从 Opus 降到 Sonnet）时，已收集的响应被标记为历史记录，整个流式请求重新发起。
+
+### 工具即能力（Tool as Capability）
+
+每个工具是一个结构化的类型定义，包含输入验证、权限检查和执行逻辑三个阶段。工具列表在每次 API 调用时动态组装（不是全局缓存），因为工具的可用性可能随运行时状态变化（如 MCP 服务器连接状态）。
+
+### 权限即边界（Permission as Boundary）
+
+每次工具调用经过"输入验证 → 权限检查"双重检查。权限规则从五个来源汇聚（会话级 → 项目级 → 用户级 → 管理级 → 默认级），优先级从高到低。
+
+这个分层设计意味着：团队可以为整个项目设置统一的权限策略（项目级），同时允许个人覆盖（用户级），管理员还可以强制执行安全策略（管理级）。
+
+### 上下文即记忆（Context as Memory）
+
+System Prompt 在每轮调用时动态组装，包含项目结构、git 状态、用户指令（CLAUDE.md）等信息。组装策略是"不变内容在前、变化内容在后"，利用 API 的前缀缓存机制减少重复计算。
+
+自动压缩在每轮迭代前评估 token 阈值，超出时用 AI 自身来总结之前的对话，保留语义信息的同时减少 token 占用。
+
+## 入口概览
+
+| 入口 | 说明 | 使用场景 |
+|------|------|----------|
+| CLI 启动 | 加载配置、认证、启动 REPL | 日常交互式使用 |
+| 管道模式 | 从 stdin 读取输入，输出到 stdout | 嵌入 CI/CD 和脚本 |
+| 远程控制 | 通过 Bridge API 远程控制 CLI | 从 claude.ai 或手机发送指令 |
+| Daemon 模式 | 长驻后台的 supervisor 进程 | 持续运行的自动化任务 |
+
+## 接下来
+
+现在你已经理解了整体架构。以下是推荐的深入路径：
+
+- **Agent Loop** — 深入核心循环的每一轮迭代细节
+- **工具系统** — 了解 50+ 工具的设计和分类
+- **上下文工程** — 理解 token 预算和自动压缩机制
+- **安全机制** — 了解权限模型和沙箱设计

docs/introduction/what-is-claude-code.mdx

@@ -1,7 +1,7 @@
 ---
-title: "什么是 Claude Code - Terminal Native Agentic Coding System"
-description: "Claude Code 是运行在终端中的 agentic coding system，直接在你的项目目录中读代码、改文件、跑命令、调试程序。了解它的技术定位、架构差异和核心能力。"
-keywords: ["Claude Code", "AI 编程助手", "Agentic Coding", "终端 AI", "CLI AI"]
+title: "项目介绍"
+description: "Claude Code 是运行在终端中的 agentic coding system。理解它的设计定位、架构选择和核心能力。"
+keywords: ["Claude Code", "AI 编程助手", "Agentic Coding", "终端 AI"]
 og:image: "https://ccb.agent-aura.top/docs/images/og-cover.png"
 ---
 
@@ -9,103 +9,104 @@ og:image: "https://ccb.agent-aura.top/docs/images/og-cover.png"
 
 Claude Code 是一个**运行在本地终端中的 agentic coding system**。它不是给建议的聊天机器人——它直接在你的项目目录中读代码、改文件、跑命令、调试程序，拥有完整的 shell 能力。
 
-## 技术定位：terminal-native agentic system
+## 设计定位
 
 理解 Claude Code 的关键在于三个词：
 
-| 定位关键词 | 含义 |
-|-----------|------|
-| **Terminal-native** | 原生 CLI 应用，不是 IDE 插件、不是 Web 界面、不是 API wrapper |
-| **Agentic** | AI 自主决策工具调用链，不是"一问一答"的聊天模式 |
-| **Coding system** | 面向软件工程全流程，不是通用问答工具 |
+| 定位 | 含义 | 设计影响 |
+|------|------|----------|
+| **Terminal-native** | 原生 CLI 应用，不是 IDE 插件也不是 Web 界面 | 拥有完整 shell 访问权，但需要自建权限模型和安全沙箱 |
+| **Agentic** | AI 自主决定调用什么工具、传什么参数、何时停止 | 不是"一问一答"，而是多轮自主决策循环 |
+| **Coding system** | 面向软件工程全流程设计 | 工具集覆盖文件操作、命令执行、代码搜索、任务管理 |
 
-与同类工具的**架构层面**差异（不是功能清单）：
+### 为什么选择终端
 
-| 工具 | 架构模式 | 运行位置 | 工具执行 |
-|------|----------|----------|----------|
-| **Claude Code** | Terminal-native agentic loop | 本地进程 | 直接 shell 执行 |
-| Cursor / Copilot | IDE-integrated autocomplete + chat | IDE 进程内 | LSP / IDE API |
-| Aider | CLI chat → git patch | 本地进程 | 文件操作为主 |
-| ChatGPT / Claude.ai | Cloud chat + artifacts | 浏览器/云端 | 沙箱容器 |
+终端不是限制，而是一个有意为之的架构选择。它带来了独特的能力，也带来了对应的代价：
 
-核心差异：Claude Code 拥有**完整的 shell 访问权**——这意味着它可以做任何你在终端里能做的事，但也需要对应的安全机制来约束这个能力。
+**优势：**
+- **完整的 shell 访问** — 可以运行任何命令行工具，无需为每个能力写插件
+- **项目原生** — 直接在项目目录工作，天然理解文件系统结构和 git 状态
+- **可组合性** — 管道模式（`echo "..." | claude -p`）允许嵌入 CI/CD 和自动化流程
+- **低延迟** — 没有 Electron 开销，React/Ink 渲染的 TUI 响应极快
 
-## 端到端示例：从输入到输出
+**代价：**
+- 用户需要适应命令行界面
+- 没有 GUI 意味着无法直接展示图片、图表等富内容
+- 权限管理的复杂度远高于 IDE 插件（因为能力边界更大）
 
-当你在终端中输入 `bun run dev 有个 TypeScript 报错，帮我修一下` 时，系统发生了什么？
+### 与同类工具的架构差异
+
+| 工具 | 架构模式 | 工具执行方式 | 安全边界 |
+|------|----------|-------------|----------|
+| **Claude Code** | Terminal-native agentic loop | 直接 shell 执行 | 自建权限模型 + 沙箱 |
+| Cursor / Copilot | IDE-integrated autocomplete + chat | LSP / IDE API | IDE 沙箱天然隔离 |
+| Aider | CLI chat → git patch | 文件操作为主 | 通过 git diff 约束变更范围 |
+| ChatGPT / Claude.ai | Cloud chat + artifacts | 沙箱容器 | 云端容器隔离 |
+
+核心区别：Claude Code 把 AI 放在了**与用户相同的权限层级**上。这既是它最强大的地方，也是安全设计最复杂的挑战。
+
+## 端到端：一次任务的生命周期
+
+当你在终端中输入 `bun run dev 有个 TypeScript 报错，帮我修一下` 时，系统经历了什么？
 
 ```
-┌─────────────────────────────────────────────────────────┐
-│ 1. 入口层 (cli.tsx → main.tsx)                          │
-│    feature() = false, MACRO 注入, 启动 Commander.js CLI  │
-├─────────────────────────────────────────────────────────┤
-│ 2. 交互层 (REPL.tsx — React/Ink)                        │
-│    PromptInput 捕获用户输入 → UserMessage 加入会话       │
-├─────────────────────────────────────────────────────────┤
-│ 3. 编排层 (QueryEngine.ts)                               │
-│    管理 turn 生命周期、token 预算、compaction 触发       │
-├─────────────────────────────────────────────────────────┤
-│ 4. 核心循环 (query.ts — Agentic Loop)                    │
-│    组装上下文 → 调 API → 收流式响应 → 解析工具调用      │
-│    → 权限检查 → 执行工具 → 结果回传 → 再次调 API → 循环 │
-├─────────────────────────────────────────────────────────┤
-│ 5. 工具执行 (BashTool.call / FileEditTool.call / ...)    │
-│    实际执行: 读文件、运行命令、搜索代码...               │
-├─────────────────────────────────────────────────────────┤
-│ 6. 通信层 (claude.ts → Anthropic API)                    │
-│    流式 HTTP, 支持 Bedrock/Vertex/Azure 多 provider      │
-└─────────────────────────────────────────────────────────┘
+用户输入 → REPL 捕获 → 上下文组装 → API 调用 → 流式响应
+                                                    ↓
+                                              解析工具调用
+                                                    ↓
+                                          权限检查 → 执行工具
+                                                    ↓
+                                          结果回传 → 再次调 API
+                                                    ↓
+                                              循环直到完成
 ```
 
-具体到这个报错修复场景，一次典型的 agentic loop 可能包含多轮工具调用：
+具体到这个报错修复场景，一次典型的 agentic loop：
 
-| Turn | AI 决策 | 工具调用 | 结果 |
-|------|---------|----------|------|
-| 1 | 先看报错信息 | `Bash("bun run dev 2>&1 | head -30")` | TypeScript 错误输出 |
-| 2 | 定位到文件 | `Read("src/utils/foo.ts")` | 源代码内容 |
-| 3 | 搜索相关类型定义 | `Grep("interface Foo", "src/")` | 类型定义位置 |
-| 4 | 修复代码 | `FileEdit(old, new)` | 代码已修改 |
-| 5 | 验证修复 | `Bash("bun run dev 2>&1 | head -10")` | 编译通过 |
+| 步骤 | AI 自主决策 | 工具调用 | 设计考量 |
+|------|------------|----------|----------|
+| 1 | 先复现报错 | `Bash("bun run dev 2>&1 | head -30")` | AI 自行决定先诊断再修复，而非直接改代码 |
+| 2 | 定位到问题文件 | `Read("src/utils/foo.ts")` | 读取而非猜测，保证修改基于最新代码 |
+| 3 | 搜索相关类型定义 | `Grep("interface Foo", "src/")` | 跨文件理解依赖关系 |
+| 4 | 修改代码 | `FileEdit(old, new)` | 精确替换而非全文重写，保留 git 历史可追溯 |
+| 5 | 验证修复 | `Bash("bun run dev 2>&1 | head -10")` | 自主验证是 agentic 系统的关键闭环 |
 
-每一步都是 AI 自主决策的——它决定用哪个工具、传什么参数、何时停止。这就是 "agentic" 的含义。
+每一步都是 AI 自主决策的。它决定用哪个工具、传什么参数、何时停止——这就是 "agentic" 的含义。
+
+## 核心设计原则
+
+这些原则贯穿整个系统的设计：
+
+**1. 能力优先，安全兜底**
+
+系统设计的第一步是"让 AI 能做什么"，然后才是"如何限制它"。这导致工具系统非常强大（完整 shell），但需要配套的权限模型（每次敏感操作可配置为需用户确认）。
+
+**2. 本地优先**
+
+所有代码执行都在本地机器上，不经过云端沙箱。这意味着：
+- 用户对数据有完全控制权
+- 可以访问本地文件系统、网络、硬件
+- 但也需要自己承担安全风险
+
+**3. 流式一切**
+
+从 API 响应到工具执行结果，所有数据都以流的方式处理。这让用户可以在 AI 思考的同时看到进展，也使得长时间运行的任务可以中途取消。
+
+**4. 上下文工程**
+
+系统花大量精力在"给 AI 看什么"上——自动收集 git 状态、项目结构、CLAUDE.md 指令、历史记忆等。上下文的质量直接决定 AI 的表现。
 
 ## 它不是什么
 
-- **不是 IDE 插件**：没有图形界面，不依赖 VS Code 或任何 IDE
-- **不是 API wrapper**：它有自己的工具系统、权限模型、上下文工程、会话管理
-- **不是聊天机器人**：输出不是纯文本，而是实际的文件修改、命令执行
-- **不是无脑执行器**：每个敏感操作都有权限检查和用户确认环节
+理解边界和了解能力一样重要：
 
-## 启动入口解剖
+- **不是 IDE 插件** — 没有图形界面，不依赖任何 IDE
+- **不是 API wrapper** — 它有自己的工具系统、权限模型、上下文工程、会话管理
+- **不是聊天机器人** — 输出不是纯文本建议，而是实际的文件修改和命令执行
+- **不是无脑执行器** — 每个敏感操作都有权限检查，系统内置规划模式用于复杂任务
 
-真正的代码入口是 `src/entrypoints/cli.tsx`，它做了三件关键的事：
+## 接下来
 
-```typescript
-// 1. 注入运行时 polyfill —— feature() 永远返回 false
-const feature = (_name: string) => false;
-
-// 2. 注入构建时宏
-globalThis.MACRO = { VERSION: "2.1.888", BUILD_TIME: ..., };
-
-// 3. 声明构建目标
-globalThis.BUILD_TARGET = "external";  // 外部构建（非 Anthropic 内部）
-globalThis.BUILD_ENV = "production";
-globalThis.INTERFACE_TYPE = "stdio";   // 标准 I/O 交互
-```
-
-然后控制流传递到 `src/main.tsx`：
-1. Commander.js 解析命令行参数
-2. 初始化认证、遥测、策略限制
-3. 加载工具列表（`getTools()`）
-4. 启动 REPL（`launchRepl()`）或管道模式（`-p`）
-
-## 为什么选择终端
-
-终端不是限制，而是选择。它带来了独特的能力：
-
-- **完整的 shell 访问**：可以运行任何命令行工具，无需为每个能力写插件
-- **项目原生**：直接在项目目录工作，理解文件系统结构、git 状态
-- **可组合性**：管道模式（`echo "..." | claude -p`）允许嵌入 CI/CD 和自动化流程
-- **低延迟**：没有 Electron 开销，React/Ink 渲染的 TUI 响应极快
-
-代价是用户需要适应命令行界面——但也正因如此，它吸引的是需要**真正掌控开发环境**的开发者。
+- **架构总览** — 了解系统的模块划分和数据流
+- **Agent Loop** — 深入理解核心循环的工作机制
+- **工具系统** — 了解 AI 拥有哪些工具及其设计考量

docs/introduction/why-this-whitepaper.mdx

@@ -1,121 +1,155 @@
 ---
-title: "为什么写这份白皮书 - Claude Code 逆向工程分析"
-description: "对 Anthropic 官方 Claude Code CLI 的逆向工程分析白皮书。通过反编译 TypeScript 单文件 bundle，深入解析运行时行为与源码结构。"
-keywords: ["Claude Code", "逆向工程", "白皮书", "反编译", "TypeScript"]
+title: "项目动机"
+description: "Claude Code 解决了什么工程问题？为什么 agentic coding 需要一整套独立的设计体系？理解这些设计决策背后的动机。"
+keywords: ["Claude Code", "设计动机", "Agentic Coding", "工程决策"]
+og:image: "https://ccb.agent-aura.top/docs/images/og-cover.png"
 ---
 
-## 这份白皮书是什么
+## 为什么需要这篇文章
 
-这是对 Anthropic 官方发布的 **Claude Code CLI** 的**逆向工程分析**。
+理解一个系统的"是什么"只是第一步。真正有用的是理解**为什么这样设计**——每个架构选择的动机、权衡和代价。
 
-源码经过反编译处理（TypeScript 单文件 bundle 逆向），保留了核心功能模块，但包含大量 `unknown`/`never`/`{}` 类型错误——这些不影响 Bun 运行时执行，但意味着我们的分析基于运行时行为 + 残留源码结构，而非原始源码。
+本文梳理 Claude Code 最核心的五个设计决策，解释它们解决了什么问题、放弃了什么、以及这些决策如何相互影响。
 
-**这不是：**
-- 官方文档或使用教程
-- API 参考手册
-- Claude Code 的功能推销
+## 决策一：Agentic Loop 而非 Chat
 
-**这是：**
-- 一个生产级 agentic system 的架构解构
-- 每个设计决策背后的"为什么"
-- 可复用的工程模式：agentic loop、工具抽象、上下文工程、安全纵深防御
+### 问题
 
-## 逆向过程中最精妙的设计决策
+大多数 AI 编程工具采用"一问一答"模式：用户描述问题，AI 给出建议，用户手动执行。这个模式的瓶颈在于——人类成为了 AI 和代码之间的中转站。
 
-### 1. Agentic Loop 的自愈能力
+### 决策
 
-`src/query.ts` 实现的核心循环不是简单的"发请求→收响应"。它是一个**自愈的状态机**：
+Claude Code 采用 **agentic loop**：AI 自主决定调用什么工具、传什么参数、何时停止。用户只需要描述目标，AI 自己规划执行路径。
 
-- API 返回错误（限流、token 超限）→ 自动重试/降级
-- 工具执行超时 → 后台化 + 通知机制
-- 对话过长触发 compaction → 压缩历史后无缝继续
-- 用户中断 → 生成 `UserInterruptionMessage` 让 AI 理解发生了什么
+### 关键设计
 
-这不是"if-else 堆叠"，而是让 AI 自己根据上下文决定下一步——即使发生了意外。
+这个循环不是简单的"发请求→收响应"，而是一个**自愈的状态机**：
 
-### 2. 上下文工程的分层策略
+- API 返回错误（限流、token 超限）→ 自动重试或降级处理
+- 工具执行超时 → 后台化运行，通过通知机制回馈结果
+- 对话过长触发 compaction → 自动压缩历史后无缝继续
+- 用户中途打断 → 系统生成中断消息让 AI 理解发生了什么
 
-AI 没有真正的"记忆"，Claude Code 通过精心分层营造了这个幻觉：
+核心思想：**让 AI 根据上下文自己决定下一步**，即使是意外情况也不需要人类介入。
 
-| 层 | 机制 | 持久性 |
-|----|------|--------|
-| **System Prompt** | 项目结构、git 状态、CLAUDE.md | 每轮重建 |
-| **对话历史** | 完整的 User/Assistant/Tool 消息 | 会话内 |
-| **Compaction** | 自动压缩过长对话为摘要 | 压缩后替代原始消息 |
-| **Memory 文件** | 跨会话持久化的笔记 | 永久（用户可控） |
-| **File History** | 文件修改时间戳快照 | 会话内 |
+### 代价
 
-`src/context.ts` 组装 System Prompt 时的策略是：**不变内容在前、变化内容在后**——这利用了 API 的缓存机制，前缀不变时可以复用缓存 token。
+- 更高的 token 消耗（AI 需要多轮工具调用才能完成一个任务）
+- 需要精心设计的权限模型（自主性越高，失控风险越大）
+- 调试困难（AI 的决策链不总是可预测的）
 
-### 3. 工具系统的权限双轨制
+## 决策二：终端原生而非 IDE 插件
 
-`src/tools/BashTool/shouldUseSandbox.ts` 展示了一个精巧的双重安全模型：
+### 问题
 
-- **应用层**：权限规则决定"能不能执行"（白名单/黑名单/用户确认）
-- **OS 层**：沙箱决定"执行时能做什么"（文件系统/网络/进程隔离）
+IDE 插件可以复用 IDE 的 UI 框架、权限沙箱和用户习惯。为什么还要做一个独立的终端应用？
 
-两层的信任假设不同：应用层信任用户配置，OS 层不信任任何东西。即使 AI 绕过了应用层权限（理论上不可能，但纵深防御），OS 层沙箱仍然限制实际危害。
+### 决策
 
-### 4. Feature Flag 的全局开关
+选择终端原生（Terminal-native）架构。CLI 拥有与用户相同的 shell 权限，可以运行任何命令行工具。
 
-`src/entrypoints/cli.tsx` 中一行代码决定了整个系统的行为：
+### 动机
 
-```typescript
-const feature = (_name: string) => false;
-```
+1. **能力边界最大化** — IDE 插件受限于 IDE 提供的 API；终端应用可以做任何用户能在终端里做的事
+2. **可组合性** — 管道模式让 AI 能力可以嵌入 CI/CD、脚本和自动化流程
+3. **零依赖** — 不需要安装特定 IDE，任何有终端的环境都能运行
 
-所有 `feature('FLAG_NAME')` 调用返回 `false`——这意味着 Anthropic 内部的实验功能（COORDINATOR_MODE、KAIROS、PROACTIVE 等）全部禁用。在官方构建中，这些 flag 通过 Bun 的 `bun:bundle` 在编译时注入，不同用户群体看到不同功能。
+### 代价
 
-这是一个**渐进式发布架构**：同一个代码库，通过 feature flag 控制功能可见性，而不需要维护多个分支。
+- 必须自建整个权限模型和安全沙箱（IDE 天然提供这些）
+- 用户门槛更高（需要适应命令行）
+- 没有 GUI 意味着无法直接展示富内容
 
-### 5. Compaction 的分档策略
+## 决策三：上下文工程的分层策略
 
-`src/services/compact/` 实现了三种压缩策略：
+### 问题
 
-- **Micro-compact**：单次工具输出过长时，截断结果
-- **Auto-compact**：对话 token 接近上限时，自动压缩历史
-- **Reactive-compact**：API 返回 token 超限错误时，紧急压缩后重试
+AI 没有真正的"记忆"。每次 API 调用都是无状态的——模型只看到当前请求中的内容。如何在一个 200K token 的窗口内让 AI "记住"足够多的上下文？
 
-这不是简单的"砍掉旧消息"——而是用 AI 自身来总结之前的对话，保留语义信息。压缩后插入一条 `TombstoneMessage` 标记边界。
+### 决策
 
-## 阅读路线图
+通过精心分层来营造"记忆"的幻觉：
 
-推荐的阅读顺序，每章解决一个核心问题：
+| 层 | 机制 | 生命周期 | 设计目的 |
+|----|------|----------|----------|
+| **System Prompt** | 项目结构、git 状态、用户指令 | 每轮重建 | 让 AI 理解当前环境 |
+| **对话历史** | 完整的用户/AI/工具消息流 | 会话内 | 保持任务连贯性 |
+| **Compaction** | AI 自主压缩过长对话为摘要 | 自动触发 | 在有限窗口内保留语义 |
+| **Memory 文件** | 跨会话持久化的笔记文件 | 永久 | 跨会话保留关键信息 |
+
+### 关键洞察
+
+System Prompt 的组装策略是**不变内容在前、变化内容在后**。这不是随意排列——它利用了 API 的前缀缓存机制：不变的系统指令部分可以复用缓存的 token，只有变化的部分需要重新计算。
+
+### 代价
+
+- Compaction 会丢失细节（压缩毕竟是信息损失）
+- Memory 文件需要用户主动维护才有用
+- 整个策略的复杂度很高，任何一环出问题都会影响 AI 表现
+
+## 决策四：权限的双轨制
+
+### 问题
+
+AI 拥有完整 shell 权限意味着它可以做任何事——包括删除文件、发送网络请求、安装软件包。如何在保持能力的同时控制风险？
+
+### 决策
+
+采用**纵深防御**的双轨权限模型：
+
+- **应用层**（权限规则）— 决定"能不能执行"。通过白名单、黑名单和用户确认三级控制
+- **OS 层**（沙箱）— 决定"执行时能做什么"。通过文件系统、网络和进程隔离限制实际行为
+
+### 设计哲学
+
+两层的**信任假设不同**：应用层信任用户配置和 AI 的判断力；OS 层不信任任何东西。即使应用层被绕过（纵深防御的思路），OS 层仍然限制实际危害。
+
+### 代价
+
+- 双轨制增加了系统复杂度
+- 频繁的权限确认会打断工作流（因此需要"自动模式"等快捷方案）
+- 沙箱不是所有平台都支持（目前主要是 macOS）
+
+## 决策五：Feature Flag 驱动的渐进发布
+
+### 问题
+
+一个大型系统需要同时服务不同用户群体：内部测试者、早期用户、正式用户。如何在不维护多套代码的情况下控制功能可见性？
+
+### 决策
+
+所有实验性功能通过 feature flag 控制。默认情况下所有 flag 关闭，不同的运行模式（开发/构建/发布）启用不同的 flag 子集。
+
+### 设计效果
+
+- **同一个代码库** — 不需要维护功能分支
+- **运行时切换** — 通过环境变量即时启用或关闭功能
+- **渐进式发布** — 可以先对内部用户开放，再逐步扩大范围
+- **安全回退** — 发现问题时关闭 flag 即可，不需要回滚代码
+
+### 代价
+
+- 代码中到处都是 `if (feature('X'))` 分支，增加阅读复杂度
+- flag 之间的依赖关系需要手动管理
+- 测试组合爆炸（每个 flag 的开/关都需要考虑）
+
+## 这些决策如何相互影响
+
+这五个决策不是孤立的——它们形成了一个互相支撑的系统：
 
 ```
-什么是 Claude Code (你在读的)          ← 建立直觉
-    │
-    ├── 架构全景                       ← 五层架构 + 数据流
-    │
-    ├── 安全体系                       ← 信任与控制
-    │   ├── 权限模型                   ← 应用层安全
-    │   ├── 沙箱机制                   ← OS 层安全
-    │   └── Plan Mode                  ← 用户主导模式
-    │
-    ├── 对话引擎                       ← AI 如何思考
-    │   ├── Agentic Loop               ← 核心循环
-    │   ├── 流式响应                   ← 实时通信
-    │   └── 多轮对话                   ← 上下文管理
-    │
-    ├── 上下文工程                     ← 记忆与预算
-    │   ├── System Prompt              ← 上下文组装
-    │   ├── Token 预算                 ← 预算管理
-    │   └── 项目记忆                   ← 跨会话持久化
-    │
-    ├── 工具系统                       ← AI 的双手
-    │   ├── 工具概览                   ← 统一接口
-    │   ├── Shell 执行                 ← Bash 工具
-    │   └── 搜索与导航                 ← Glob/Grep
-    │
-    └── Agent 与扩展                   ← 能力扩展
-        ├── 子 Agent                   ← 并行任务
-        ├── 自定义 Agent               ← 用户定义
-        └── MCP 协议                   ← 外部工具接入
+Agentic Loop（自主决策）
+    └── 需要强大的工具系统 → 终端原生架构
+    └── 需要安全约束 → 双轨权限模型
+    └── 需要在有限窗口内工作 → 上下文分层策略
+    └── 需要渐进式发布 → Feature Flag 体系
 ```
 
-## 适合谁读
+每个决策都为其他决策创造了前提条件。这也是为什么理解"动机"比理解"实现"更重要——知道了为什么，才能判断在什么情况下应该偏离这些选择。
 
-- **AI Agent 开发者**：想理解生产级 agentic system 的架构模式
-- **安全工程师**：对 AI 操作真实环境时的信任模型感兴趣
-- **工具构建者**：正在构建类似的 coding assistant 或 CLI 工具
-- **好奇心驱动的开发者**：想知道"AI 编程助手到底怎么工作的"
+## 适合谁读这套文档
+
+- **AI Agent 开发者** — 想理解生产级 agentic system 的架构模式
+- **安全工程师** — 对 AI 操作真实环境时的信任模型感兴趣
+- **工具构建者** — 正在构建类似的 coding assistant 或 CLI 工具
+- **好奇心驱动的开发者** — 想知道"AI 编程助手到底怎么工作的"

docs/lsp-integration.md

@@ -65,7 +65,7 @@ ENABLE_LSP_TOOL=1 bun run dev
 ```
 ┌─────────────────────────────────────────────────────┐
 │                    LSP Tool                         │
-│  src/tools/LSPTool/LSPTool.ts                       │
+│  packages/builtin-tools/src/tools/LSPTool/LSPTool.ts│
 │  (Claude 可调用的工具，9 种操作)                       │
 └──────────────────────┬──────────────────────────────┘
                        │
@@ -128,10 +128,10 @@ LSP 服务器会异步推送 `textDocument/publishDiagnostics` 通知，经去
 | `src/services/lsp/config.ts` | 从插件加载 LSP 服务器配置 |
 | `src/services/lsp/LSPDiagnosticRegistry.ts` | 诊断信息注册、去重、容量限制 |
 | `src/services/lsp/passiveFeedback.ts` | 注册 `publishDiagnostics` 通知处理器 |
-| `src/tools/LSPTool/LSPTool.ts` | LSP Tool 实现（暴露给 Claude） |
-| `src/tools/LSPTool/schemas.ts` | 输入 schema（9 种操作的 discriminated union） |
-| `src/tools/LSPTool/formatters.ts` | 各操作结果的格式化 |
-| `src/tools/LSPTool/prompt.ts` | Tool 描述文本 |
+| `packages/builtin-tools/src/tools/LSPTool/LSPTool.ts` | LSP Tool 实现（暴露给 Claude） |
+| `packages/builtin-tools/src/tools/LSPTool/schemas.ts` | 输入 schema（9 种操作的 discriminated union） |
+| `packages/builtin-tools/src/tools/LSPTool/formatters.ts` | 各操作结果的格式化 |
+| `packages/builtin-tools/src/tools/LSPTool/prompt.ts` | Tool 描述文本 |
 | `src/utils/plugins/lspPluginIntegration.ts` | 从插件加载、验证、环境变量解析、作用域管理 |
 
 ## LSP Tool 支持的操作

docs/openai-task-tools.md

@@ -1,190 +0,0 @@
-# OpenAI兼容模型中task工具使用指南
-
-## 问题描述
-
-当使用OpenAI兼容模型（如DeepSeek、Ollama、vLLM等）时，调用task工具（TaskGet、TaskCreate、TaskUpdate、TaskList）可能会出现以下错误：
-
-```
-Error: InputValidationError: TaskGet failed due to the following issues:
-   The required parameter `taskId` is missing
-   An unexpected parameter `task_id` was provided
-   
-   This tool's schema was not sent to the API — it was not in the discovered-tool set derived from message history. Without the schema in your prompt, typed parameters (arrays, numbers, booleans) get emitted as strings and the client-side parser rejects them. Load the tool first: call ToolSearch with query "select:TaskGet", then retry this call.
-```
-
-## 问题原因
-
-### 1. 延迟加载工具（Deferred Tools）
-task工具都是延迟加载的（`shouldDefer: true`），这意味着：
-- 工具的模式（schema）不会在初始API调用中发送
-- 需要先通过`ToolSearch`工具发现
-- 只有在被发现后，工具模式才会被发送给API
-
-### 2. 参数名转换问题
-- task工具使用驼峰命名：`taskId`
-- OpenAI兼容模型可能输出蛇形命名：`task_id`
-- 当工具模式没有被发送时，模型会猜测参数名，可能导致不匹配
-
-## 解决方案
-
-### 方案1：先使用ToolSearch（推荐）
-在使用task工具之前，先调用`ToolSearch`工具：
-
-```javascript
-// 第一步：发现task工具
-ToolSearch("select:TaskGet,TaskCreate,TaskUpdate,TaskList")
-
-// 第二步：正常使用task工具
-TaskCreate({ subject: "任务标题", description: "任务描述" })
-TaskGet({ taskId: "1" })
-TaskUpdate({ taskId: "1", status: "completed" })
-TaskList()
-```
-
-### 方案2：批量发现所有task工具
-```javascript
-// 一次性发现所有task工具
-ToolSearch("select:TaskGet,TaskCreate,TaskUpdate,TaskList")
-
-// 然后可以任意使用task工具
-const task = await TaskCreate({ subject: "新任务", description: "任务描述" })
-console.log(`创建的任务ID: ${task.id}`)
-
-const taskList = await TaskList()
-console.log(`当前有 ${taskList.tasks.length} 个任务`)
-```
-
-### 方案3：单独发现特定工具
-```javascript
-// 只发现需要的工具
-ToolSearch("select:TaskGet")
-
-// 然后使用该工具
-TaskGet({ taskId: "1" })
-```
-
-## 参数名注意事项
-
-在使用OpenAI兼容模型时，请注意参数名格式：
-
-### ✅ 正确（驼峰命名）
-```javascript
-TaskGet({ taskId: "1" })
-TaskCreate({ subject: "标题", description: "描述" })
-TaskUpdate({ taskId: "1", status: "completed" })
-```
-
-### ❌ 错误（蛇形命名）
-```javascript
-TaskGet({ task_id: "1" })  // 错误：应该使用taskId
-TaskCreate({ subject: "标题", description: "描述" })  // 正确
-TaskUpdate({ task_id: "1", status: "completed" })  // 错误：应该使用taskId
-```
-
-## 常见问题解答
-
-### Q1: 为什么需要先使用ToolSearch？
-A: task工具是延迟加载的，它们的模式只有在被`ToolSearch`工具发现后才会发送给API。没有工具模式，模型无法知道正确的参数名和类型。
-
-### Q2: 每次会话都需要使用ToolSearch吗？
-A: 是的，每次新的会话都需要先使用ToolSearch发现工具。工具发现状态不会在会话之间保留。
-
-### Q3: 使用Anthropic官方模型也需要这样吗？
-A: 通常不需要。Anthropic官方模型对延迟加载工具的处理更智能，但为了兼容性，建议在使用task工具前都先使用ToolSearch。
-
-### Q4: 可以一次性发现所有工具吗？
-A: 可以，使用`ToolSearch("select:TaskGet,TaskCreate,TaskUpdate,TaskList")`可以一次性发现所有task工具。
-
-### Q5: 如果忘记使用ToolSearch会怎样？
-A: 会收到参数验证错误，提示需要先使用ToolSearch。按照错误信息的指导操作即可。
-
-## 最佳实践
-
-1. **会话开始时发现工具**：在开始使用task工具前，先调用ToolSearch
-2. **批量发现**：一次性发现所有需要的task工具
-3. **检查参数名**：确保使用正确的驼峰命名参数
-4. **查看错误信息**：如果遇到错误，仔细阅读错误信息中的指导
-
-## 示例工作流
-
-```javascript
-// 1. 开始新会话
-// 2. 发现task工具
-ToolSearch("select:TaskGet,TaskCreate,TaskUpdate,TaskList")
-
-// 3. 创建任务
-const newTask = await TaskCreate({
-  subject: "修复OpenAI兼容性问题",
-  description: "解决task工具在OpenAI兼容模型下的参数名问题"
-})
-
-// 4. 获取任务详情
-const taskDetails = await TaskGet({ taskId: newTask.id })
-
-// 5. 更新任务状态
-await TaskUpdate({ 
-  taskId: newTask.id, 
-  status: "in_progress",
-  activeForm: "修复OpenAI兼容性问题"
-})
-
-// 6. 查看所有任务
-const allTasks = await TaskList()
-console.log(`当前有 ${allTasks.tasks.length} 个任务`)
-
-// 7. 完成任务
-await TaskUpdate({ 
-  taskId: newTask.id, 
-  status: "completed"
-})
-```
-
-## 故障排除
-
-### 错误：参数名不匹配
-**症状**：`taskId`参数缺失，发现`task_id`参数
-**解决**：确保使用驼峰命名的`taskId`，而不是蛇形命名的`task_id`
-
-### 错误：工具模式未发送
-**症状**：`This tool's schema was not sent to the API`
-**解决**：先使用`ToolSearch("select:工具名")`发现工具
-
-### 错误：工具不可用
-**症状**：工具调用失败，没有具体错误信息
-**解决**：检查工具是否启用（通过`isTodoV2Enabled()`），确保环境变量设置正确
-
-## 相关配置
-
-### 环境变量
-```bash
-# 启用OpenAI兼容模式
-export CLAUDE_CODE_USE_OPENAI=1
-export OPENAI_API_KEY=your-api-key
-export OPENAI_BASE_URL=https://api.deepseek.com
-
-# 配置模型映射
-export OPENAI_DEFAULT_SONNET_MODEL=deepseek-chat
-export OPENAI_DEFAULT_OPUS_MODEL=deepseek-chat
-export OPENAI_DEFAULT_HAIKU_MODEL=deepseek-chat
-```
-
-### 设置文件
-通过`/login`命令配置OpenAI兼容模式后，设置会保存在`~/.claude/settings.json`：
-```json
-{
-  "modelType": "openai",
-  "openai": {
-    "baseURL": "https://api.deepseek.com",
-    "apiKey": "your-api-key",
-    "models": {
-      "haiku": "deepseek-chat",
-      "sonnet": "deepseek-chat",
-      "opus": "deepseek-chat"
-    }
-  }
-}
-```
-
-## 总结
-
-在使用OpenAI兼容模型时，task工具需要先通过`ToolSearch`发现才能正常使用。遵循"先发现，后使用"的原则，并注意参数名的正确格式（驼峰命名），可以确保task工具在OpenAI兼容模型下正常工作。

docs/plans/openai-compatibility.md

@@ -1,425 +0,0 @@
-# OpenAI 协议兼容层
-
-## 概述
-
-claude-code 支持通过 OpenAI Chat Completions API（`/v1/chat/completions`）兼容任意 OpenAI 协议端点，包括 Ollama、DeepSeek、vLLM、One API、LiteLLM 等。
-
-核心策略为**流适配器模式**：在 `queryModel()` 中插入提前返回分支，将 Anthropic 格式请求转为 OpenAI 格式，调用 OpenAI SDK，再将 SSE 流转换回 `BetaRawMessageStreamEvent` 格式。下游代码（流处理循环、query.ts、QueryEngine.ts、REPL）**完全不改**。
-
-## 环境变量
-
-| 变量 | 必需 | 说明 |
-|---|---|---|
-| `CLAUDE_CODE_USE_OPENAI` | 是 | 设为 `1` 启用 OpenAI 后端 |
-| `OPENAI_API_KEY` | 是 | API key（Ollama 等可设为任意值） |
-| `OPENAI_BASE_URL` | 推荐 | 端点 URL（如 `http://localhost:11434/v1`） |
-| `OPENAI_MODEL` | 可选 | 覆盖所有请求的模型名（跳过映射） |
-| `OPENAI_DEFAULT_OPUS_MODEL` | 可选 | 覆盖 opus 家族对应的模型（如 `o3`, `o3-mini`, `o1-pro`） |
-| `OPENAI_DEFAULT_SONNET_MODEL` | 可选 | 覆盖 sonnet 家族对应的模型（如 `gpt-4o`, `gpt-4.1`） |
-| `OPENAI_DEFAULT_HAIKU_MODEL` | 可选 | 覆盖 haiku 家族对应的模型（如 `gpt-4o-mini`, `gpt-4.0-mini`） |
-| `OPENAI_ORG_ID` | 可选 | Organization ID |
-| `OPENAI_PROJECT_ID` | 可选 | Project ID |
-
-### 使用示例
-
-```bash
-# Ollama
-CLAUDE_CODE_USE_OPENAI=1 \
-OPENAI_API_KEY=ollama \
-OPENAI_BASE_URL=http://localhost:11434/v1 \
-OPENAI_MODEL=qwen2.5-coder-32b \
-bun run dev
-
-# DeepSeek（自动支持 Thinking）
-CLAUDE_CODE_USE_OPENAI=1 \
-OPENAI_API_KEY=sk-xxx \
-OPENAI_BASE_URL=https://api.deepseek.com/v1 \
-OPENAI_MODEL=deepseek-chat \
-bun run dev
-
-# vLLM
-CLAUDE_CODE_USE_OPENAI=1 \
-OPENAI_API_KEY=token-abc123 \
-OPENAI_BASE_URL=http://localhost:8000/v1 \
-OPENAI_MODEL=Qwen/Qwen2.5-Coder-32B-Instruct \
-bun run dev
-
-# One API / LiteLLM
-CLAUDE_CODE_USE_OPENAI=1 \
-OPENAI_API_KEY=sk-your-key \
-OPENAI_BASE_URL=https://your-one-api.example.com/v1 \
-OPENAI_MODEL=gpt-4o \
-bun run dev
-
-# 自定义模型映射（使用家族变量）
-CLAUDE_CODE_USE_OPENAI=1 \
-OPENAI_API_KEY=sk-xxx \
-OPENAI_BASE_URL=https://my-gateway.example.com/v1 \
-OPENAI_DEFAULT_SONNET_MODEL="gpt-4o-2024-11-20" \
-OPENAI_DEFAULT_HAIKU_MODEL="gpt-4o-mini" \
-bun run dev
-```
-
-## 架构
-
-### 请求流程
-
-```
-queryModel() [claude.ts]
-  ├── 共享预处理（消息归一化、工具过滤、媒体裁剪）
-  └── if (getAPIProvider() === 'openai')
-      └── queryModelOpenAI() [openai/index.ts]
-          ├── resolveOpenAIModel()          → 解析模型名
-          ├── normalizeMessagesForAPI()      → 共享消息预处理
-          ├── toolToAPISchema()              → 构建工具 schema
-          ├── anthropicMessagesToOpenAI()    → 消息格式转换
-          ├── anthropicToolsToOpenAI()       → 工具格式转换
-          ├── openai.chat.completions.create({ stream: true })
-          └── adaptOpenAIStreamToAnthropic() → 流格式转换
-              ├── delta.reasoning_content    → thinking 块
-              ├── delta.content             → text 块
-              ├── delta.tool_calls          → tool_use 块
-              ├── usage.cached_tokens       → cache_read_input_tokens
-              └── yield BetaRawMessageStreamEvent
-```
-
-### 模型名解析优先级
-
-`resolveOpenAIModel()` 的解析顺序：
-
-1. `OPENAI_MODEL` 环境变量 → 直接使用，覆盖所有
-2. `OPENAI_DEFAULT_{FAMILY}_MODEL` 变量（如 `OPENAI_DEFAULT_SONNET_MODEL`）→ 按模型家族覆盖
-3. `ANTHROPIC_DEFAULT_{FAMILY}_MODEL` 变量（向后兼容）
-4. 内置默认映射（见下表）
-5. 以上都不匹配 → 原名透传
-
-### 内置模型映射
-
-| Anthropic 模型 | OpenAI 映射 |
-|---|---|
-| `claude-sonnet-4-6` | `gpt-4o` |
-| `claude-sonnet-4-5-20250929` | `gpt-4o` |
-| `claude-sonnet-4-20250514` | `gpt-4o` |
-| `claude-3-7-sonnet-20250219` | `gpt-4o` |
-| `claude-3-5-sonnet-20241022` | `gpt-4o` |
-| `claude-opus-4-6` | `o3` |
-| `claude-opus-4-5-20251101` | `o3` |
-| `claude-opus-4-1-20250805` | `o3` |
-| `claude-opus-4-20250514` | `o3` |
-| `claude-haiku-4-5-20251001` | `gpt-4o-mini` |
-| `claude-3-5-haiku-20241022` | `gpt-4o-mini` |
-
-同时会自动剥离 `[1m]` 后缀（Claude 特有的 modifier）。
-
-## 文件结构
-
-### 新增文件
-
-```
-src/services/api/openai/
-├── client.ts              # OpenAI SDK 客户端工厂（~50 行）
-├── convertMessages.ts     # Anthropic → OpenAI 消息格式转换（~190 行）
-├── convertTools.ts        # Anthropic → OpenAI 工具格式转换（~70 行）
-├── streamAdapter.ts       # SSE 流转换核心，含 thinking + caching（~270 行）
-├── modelMapping.ts        # 模型名解析（~60 行）
-├── index.ts               # 公共入口 queryModelOpenAI()（~110 行）
-└── __tests__/
-    ├── convertMessages.test.ts   # 10 个测试
-    ├── convertTools.test.ts      # 7 个测试
-    ├── modelMapping.test.ts      # 6 个测试
-    └── streamAdapter.test.ts     # 14 个测试（含 thinking + caching）
-```
-
-### 修改文件
-
-| 文件 | 改动 |
-|---|---|
-| `src/utils/model/providers.ts` | 添加 `'openai'` provider 类型 + `CLAUDE_CODE_USE_OPENAI` 检查（最高优先级） |
-| `src/utils/model/configs.ts` | 每个 ModelConfig 添加 `openai` 键 |
-| `src/services/api/claude.ts` | 在 `stripExcessMediaItems()` 后插入 OpenAI 提前返回分支（~8 行） |
-| `package.json` | 添加 `"openai": "^4.73.0"` 依赖 |
-
-## 消息转换规则
-
-### Anthropic → OpenAI
-
-| Anthropic | OpenAI |
-|---|---|
-| `system` prompt（`string[]`） | `role: "system"` 消息（`\n\n` 拼接） |
-| `user` + `text` 块 | `role: "user"` 消息 |
-| `assistant` + `text` 块 | `role: "assistant"` + `content` |
-| `assistant` + `tool_use` 块 | `role: "assistant"` + `tool_calls[]` |
-| `user` + `tool_result` 块 | `role: "tool"` + `tool_call_id` |
-| `thinking` 块 | 静默丢弃（请求侧） |
-
-### 工具转换
-
-| Anthropic | OpenAI |
-|---|---|
-| `{ name, description, input_schema }` | `{ type: "function", function: { name, description, parameters } }` |
-| `cache_control`, `defer_loading` 等字段 | 剥离 |
-| `tool_choice: { type: "auto" }` | `"auto"` |
-| `tool_choice: { type: "any" }` | `"required"` |
-| `tool_choice: { type: "tool", name }` | `{ type: "function", function: { name } }` |
-
-### 消息转换示例
-
-```
-Anthropic:                              OpenAI:
-[
-  system: ["You are helpful."],         [
-                                          { role: "system",
-  { role: "user",                          content: "You are helpful." },
-    content: [                            { role: "user",
-      { type: "text", text: "Run ls" }      content: "Run ls"
-    ]                                     },
-  },                                      { role: "assistant",
-  { role: "assistant",                     content: "I'll check.",
-    content: [                            tool_calls: [{
-      { type: "text", text: "I'll check."},  id: "tu_123",
-      { type: "tool_use",                    type: "function",
-        id: "tu_123", name: "bash",          function: {
-        input: { command: "ls" } }             name: "bash",
-    ]                                           arguments: '{"command":"ls"}'
-  },                                      }] }
-  { role: "user",                        { role: "tool",
-    content: [                              tool_call_id: "tu_123",
-      { type: "tool_result",                content: "file1\nfile2"
-        tool_use_id: "tu_123",            }
-        content: "file1\nfile2"          ]
-    ]
-  }
-]
-```
-
-## 流转换规则
-
-### SSE Chunk → Anthropic Event 映射
-
-| OpenAI Chunk | Anthropic Event |
-|---|---|
-| 首个 chunk | `message_start`（含 usage） |
-| `delta.reasoning_content` | `content_block_start(thinking)` + `thinking_delta` |
-| `delta.content` | `content_block_start(text)` + `text_delta` |
-| `delta.tool_calls` | `content_block_start(tool_use)` + `input_json_delta` |
-| `finish_reason: "stop"` | `message_delta(stop_reason: "end_turn")` |
-| `finish_reason: "tool_calls"` | `message_delta(stop_reason: "tool_use")` |
-| `finish_reason: "length"` | `message_delta(stop_reason: "max_tokens")` |
-
-### 块顺序
-
-当模型返回 `reasoning_content` 时（如 DeepSeek），块顺序与 Anthropic 一致：
-
-```
-thinking block (index 0)  ← delta.reasoning_content
-text block    (index 1)   ← delta.content
-```
-
-或：
-
-```
-thinking block (index 0)  ← delta.reasoning_content
-tool_use block (index 1)  ← delta.tool_calls
-```
-
-无 `reasoning_content` 时：
-
-```
-text block    (index 0)   ← delta.content
-tool_use block (index 1)  ← delta.tool_calls（如果有）
-```
-
-### finish_reason 映射
-
-| OpenAI | Anthropic |
-|---|---|
-| `stop` | `end_turn` |
-| `tool_calls` | `tool_use` |
-| `length` | `max_tokens` |
-| `content_filter` | `end_turn` |
-
-### 事件序列示例
-
-**纯文本响应**：
-```
-OpenAI chunks:
-  delta.content = "Hello"
-  delta.content = " world"
-  finish_reason = "stop"
-
-→ Anthropic events:
-  message_start       { message: { id, role: 'assistant', usage: {...} } }
-  content_block_start { index: 0, content_block: { type: 'text' } }
-  content_block_delta { index: 0, delta: { type: 'text_delta', text: 'Hello' } }
-  content_block_delta { index: 0, delta: { type: 'text_delta', text: ' world' } }
-  content_block_stop  { index: 0 }
-  message_delta       { delta: { stop_reason: 'end_turn' } }
-  message_stop
-```
-
-**Thinking + 文本（DeepSeek 风格）**：
-```
-OpenAI chunks:
-  delta.reasoning_content = "Let me think..."
-  delta.reasoning_content = " step by step."
-  delta.content = "The answer is 42."
-  finish_reason = "stop"
-
-→ Anthropic events:
-  message_start       { ... }
-  content_block_start { index: 0, content_block: { type: 'thinking', signature: '' } }
-  content_block_delta { index: 0, delta: { type: 'thinking_delta', thinking: 'Let me think...' } }
-  content_block_delta { index: 0, delta: { type: 'thinking_delta', thinking: ' step by step.' } }
-  content_block_stop  { index: 0 }
-  content_block_start { index: 1, content_block: { type: 'text' } }
-  content_block_delta { index: 1, delta: { type: 'text_delta', text: 'The answer is 42.' } }
-  content_block_stop  { index: 1 }
-  message_delta       { delta: { stop_reason: 'end_turn' } }
-  message_stop
-```
-
-**工具调用**：
-```
-OpenAI chunks:
-  delta.tool_calls[0] = { id: 'call_xxx', function: { name: 'bash', arguments: '' } }
-  delta.tool_calls[0].function.arguments = '{"comm'
-  delta.tool_calls[0].function.arguments = 'and":"ls"}'
-  finish_reason = "tool_calls"
-
-→ Anthropic events:
-  message_start       { ... }
-  content_block_start { index: 0, content_block: { type: 'tool_use', id: 'call_xxx', name: 'bash' } }
-  content_block_delta { index: 0, delta: { type: 'input_json_delta', partial_json: '{"comm' } }
-  content_block_delta { index: 0, delta: { type: 'input_json_delta', partial_json: 'and":"ls"}' } }
-  content_block_stop  { index: 0 }
-  message_delta       { delta: { stop_reason: 'tool_use' } }
-  message_stop
-```
-
-## 功能支持
-
-### Thinking（思维链）
-
-**请求侧**：不需要显式配置。支持思维链的模型（DeepSeek 等）会自动返回 `delta.reasoning_content`。
-
-**响应侧**：`delta.reasoning_content` 被转换为 Anthropic `thinking` content block：
-
-```ts
-// content_block_start
-{ type: 'content_block_start', index: 0,
-  content_block: { type: 'thinking', thinking: '', signature: '' } }
-
-// content_block_delta
-{ type: 'content_block_delta', index: 0,
-  delta: { type: 'thinking_delta', thinking: 'Let me analyze...' } }
-```
-
-thinking block 在 text/tool_use block 之前自动关闭，保持 Anthropic 的块顺序。
-
-### Prompt Caching
-
-**请求侧**：OpenAI 端点使用自动缓存，无需显式设置 `cache_control`。
-
-**响应侧**：OpenAI 的 `usage.prompt_tokens_details.cached_tokens` 被映射到 Anthropic 的 `cache_read_input_tokens`：
-
-```
-OpenAI:   usage.prompt_tokens_details.cached_tokens = 800
-     ↓
-Anthropic: message_start.message.usage.cache_read_input_tokens = 800
-```
-
-在 `message_start` 的 usage 中报告缓存命中量。
-
-### 工具调用（Tool Use）
-
-完整支持 OpenAI function calling 格式。所有本地工具（Bash、FileEdit、Grep、Glob、Agent 等）透明工作——它们通过 JSON 输入输出通信，格式无关。
-
-工具参数以 `input_json_delta` 形式流式传输，由下游代码拼接解析。
-
-### 不支持的功能
-
-| 功能 | 策略 |
-|---|---|
-| Beta Headers | 不发送 |
-| Server Tools (advisor) | 不发送 |
-| Structured Output | 不发送 |
-| Fast Mode / Effort | 不发送 |
-| Tool Search / defer_loading | 不启用，所有工具直接发送 |
-| Anthropic Signature | thinking block 的 `signature` 字段为空字符串 |
-| cache_creation_input_tokens | 始终为 0（OpenAI 不区分创建/读取） |
-
-## 测试
-
-```bash
-# 运行所有 OpenAI 适配层测试
-bun test src/services/api/openai/__tests__/
-
-# 单独运行
-bun test src/services/api/openai/__tests__/streamAdapter.test.ts     # 14 tests（含 thinking + caching）
-bun test src/services/api/openai/__tests__/convertMessages.test.ts   # 10 tests
-bun test src/services/api/openai/__tests__/convertTools.test.ts      # 7 tests
-bun test src/services/api/openai/__tests__/modelMapping.test.ts      # 6 tests
-```
-
-当前测试覆盖：**39 tests / 73 assertions / 0 fail**。
-
-### 测试覆盖矩阵
-
-| 功能 | convertMessages | convertTools | streamAdapter | modelMapping |
-|---|---|---|---|---|
-| 文本消息转换 | ✅ | | | |
-| tool_use 转换 | ✅ | | | |
-| tool_result 转换 | ✅ | | | |
-| thinking 剥离 | ✅ | | | |
-| 完整对话流程 | ✅ | | | |
-| 工具 schema 转换 | | ✅ | | |
-| tool_choice 映射 | | ✅ | | |
-| 纯文本流 | | | ✅ | |
-| 工具调用流 | | | ✅ | |
-| 混合文本+工具 | | | ✅ | |
-| finish_reason 映射 | | | ✅ | |
-| thinking 流 | | | ✅ | |
-| thinking+text 切换 | | | ✅ | |
-| thinking+tool_use 切换 | | | ✅ | |
-| 块索引正确性 | | | ✅ | |
-| cached_tokens 映射 | | | ✅ | |
-| OPENAI_MODEL 覆盖 | | | | ✅ |
-| 默认模型映射 | | | | ✅ |
-| 未知模型透传 | | | | ✅ |
-| [1m] 后缀剥离 | | | | ✅ |
-
-## 端到端验证
-
-```bash
-# 1. 安装依赖
-bun install
-
-# 2. 运行单元测试
-bun test src/services/api/openai/__tests__/
-
-# 3. 连接实际端点（以 Ollama 为例）
-CLAUDE_CODE_USE_OPENAI=1 \
-OPENAI_API_KEY=ollama \
-OPENAI_BASE_URL=http://localhost:11434/v1 \
-OPENAI_MODEL=qwen2.5-coder-32b \
-bun run dev
-
-# 4. 连接 DeepSeek（测试 thinking 支持）
-CLAUDE_CODE_USE_OPENAI=1 \
-OPENAI_API_KEY=sk-xxx \
-OPENAI_BASE_URL=https://api.deepseek.com/v1 \
-OPENAI_MODEL=deepseek-reasoner \
-bun run dev
-
-# 5. 确认现有测试不受影响
-bun test  # 无 CLAUDE_CODE_USE_OPENAI 时走原有路径
-```
-
-## 代码统计
-
-| 类别 | 行数 |
-|---|---|
-| 新增源码 | ~620 行 |
-| 新增测试 | ~450 行 |
-| 改动现有代码 | ~25 行 |
-| **总计** | **~1100 行** |

docs/projects-collection.md

@@ -1,35 +0,0 @@
-# 社区项目 & Blog 合集
-
-> 每日更新，欢迎自荐！
-
-## 工具 & 应用
-
-| 项目 | 描述 | 作者 |
-|------|------|------|
-| [4qtask.vercel.app](https://4qtask.vercel.app/) | 免费四象限时间管理工具 | @kevinhuky |
-| [kaying.studio](https://kaying.studio/) | 个人 AI 工具箱 | @kayingai |
-| [supsub.ai](https://supsub.ai/) | 高效阅读工具 | @hidumou |
-| [x-video-download.net](https://x-video-download.net/) | 视频下载工具 | @syakadou |
-| [1openapi.com](https://1openapi.com/) | API 中转站 | @thinker007 |
-| [claw-z.com](https://claw-z.com/) | 一键部署 OpenClaw AI Agent（场景驱动、全面管理） | @uhhc |
-| [gemini-watermark-remover.net](https://gemini-watermark-remover.net/) | Gemini 水印移除工具 | @syakadou |
-
-## GitHub 开源项目
-
-| 项目 | 描述 | 作者 |
-|------|------|------|
-| [VersperClaw](https://github.com/versperai/VersperClaw) | 全自动科研流 | @versperai |
-| [claude-reviews-claude](https://github.com/openedclaude/claude-reviews-claude) | 原汤化原食——Claude 如何看待眼中的老己 | @openedclaude |
-| [agentica](https://github.com/shibing624/agentica) | 自研 Agent 框架，借鉴 claude-code 多 Agent 处理 | @shibing624 |
-| [macman](https://github.com/tonngw/macman) | Mac 从 0 到 1 保姆级配置教程 | @tonngw |
-| [SuperSpec](https://github.com/asasugar/SuperSpec) | SDD / Spec-Driven Development | @asasugar |
-| [adnify](https://github.com/adnaan-worker/adnify) | 高颜值高定制化 AI 编辑器 | @adnaan-worker |
-| [another-rule-engine](https://github.com/eatmoreduck/another-rule-engine) | 基于 Groovy 的开源多功能决策引擎 | @eatmoreduck |
-| [creative_master](https://github.com/chatabc/creative_master) | AI 驱动的创意灵感管理工具 | @chatabc |
-| [RapidDoc](https://github.com/RapidAI/RapidDoc) | Office 文件解析工具转 Markdown（支持 PDF/Image/Word/PPT/Excel） | @hzkitt |
-
-## Blog
-
-| 链接 | 作者 |
-|------|------|
-| [blog.xiaohuangyu.space](https://blog.xiaohuangyu.space/) | @eatmoreduck |

docs/safety/auto-mode.mdx

@@ -1,263 +1,102 @@
 ---
-title: "Auto Mode - AI 分类器驱动的自主执行模式"
-description: "详解 Claude Code 的 auto mode：基于 transcript classifier 的自动权限决策、两阶段分类流水线、危险权限剥离机制、模式切换状态管理、以及与 plan mode 的协作方式。"
-keywords: ["auto mode", "yoloClassifier", "transcript classifier", "权限分类", "自动执行", "两阶段分类"]
+title: "Auto Mode"
+description: "AI 分类器驱动的自主执行模式。理解两阶段分类流水线、危险权限剥离和分类器不可用时的降级策略。"
+keywords: ["auto mode", "自动执行", "AI 分类器", "权限分类"]
 ---
 
-## 概述
+## 核心问题
 
-Auto mode 是 Claude Code 的一种权限模式，让 AI 进入**连续自主执行**状态。与传统模式（每个敏感操作都弹出权限对话框等待用户审批）不同，auto mode 使用 AI 分类器（transcript classifier）自动判断每个工具调用是否安全，从而实现无中断的执行体验。
+默认模式下，AI 执行每个敏感操作都需要用户确认。这在处理复杂任务时产生大量打断——一次重构可能需要确认 20 次文件编辑和 10 次命令执行。
+
+Auto mode 的目标：**让 AI 连续自主执行，只在真正危险时才停下来。**
+
+## 权限模式的层级
 
 ```
-权限模式层级：
-
-default  →  auto  →  bypassPermissions
+default  →  auto  →  bypass
 （逐项确认） （AI 分类器审批） （全部放行）
 ```
 
-## 核心架构
+Auto mode 不是 bypass——它不是"什么都允许"，而是"让 AI 判断什么安全、什么危险"。
 
-### 1. AI 分类器（yoloClassifier）
+## 核心架构：AI 分类器
 
-分类器是 auto mode 的核心，位于 `src/utils/permissions/yoloClassifier.ts`。
+Auto mode 的核心是一个 AI 分类器。每个工具调用经过分类器评估，返回三种裁决：
 
-每个工具调用经过分类器评估，返回三种裁决之一：
+| 裁决 | 含义 | 处理 |
+|------|------|------|
+| **allow** | 操作安全 | 直接执行 |
+| **deny** | 操作危险 | 拒绝并告知 AI |
+| **ask** | 无法确定 | 回退到用户确认 |
 
-| 裁决 | 含义 | 处理方式 |
-|------|------|---------|
-| **allow** | 操作安全 | 直接执行，用户无感知 |
-| **deny** | 操作危险 | 拒绝执行，向 AI 返回拒绝消息 |
-| **ask** | 无法确定 | 回退到传统权限对话框 |
+**设计洞察**：分类器基于完整的对话上下文判断，而非只看单条命令。它能理解操作的意图——同样是 `rm` 命令，删除构建产物是安全的，删除源代码是危险的。
 
-分类器的判断基于完整的对话上下文（transcript），而不仅仅看单条命令——它能理解操作的意图和上下文。
+## 两阶段分类流水线
 
-### 2. 两阶段分类流水线
+分类器采用两阶段设计：
 
-分类器支持两阶段 XML 分类（`classifyYoloActionXml`）：
+### Stage 1：快速判断
 
-```
-Stage 1 — "fast"（快速判断）
-├── max_tokens=64，stop_sequences 触发即时 yes/no
-├── 如果 allow → 直接放行（最快路径）
-└── 如果 block → 进入 Stage 2
+使用短输出（最多 64 token）快速给出 allow/block 判断。大多数安全操作在这一阶段就被放行，延迟极低。
 
-Stage 2 — "thinking"（深度思考）
-├── chain-of-thought 推理
-├── 减少误报（false positives）
-└── 最终决定 allow / deny / ask
-```
+### Stage 2：深度思考
 
-两个阶段共享相同的 system prompt 和 user content，利用 API 的 prompt caching（1 小时 TTL）优化性能。
+Stage 1 判断为 block 的操作进入深度推理阶段，通过 chain-of-thought 减少误报。
 
-可通过配置选择模式：
-- `'both'`（默认）— 两阶段都跑
-- `'fast'` — 只跑 Stage 1
-- `'thinking'` — 只跑 Stage 2
-
-### 3. 分类器结果类型
-
-```typescript
-// src/types/permissions.ts
-type YoloClassifierResult = {
-  thinking?: string          // 分类器的推理过程
-  shouldBlock: boolean       // 是否阻止
-  reason: string             // 决策原因
-  unavailable?: boolean      // 分类器是否不可用
-  transcriptTooLong?: boolean // 对话是否超出上下文窗口
-  model: string              // 使用的分类器模型
-  stage?: 'fast' | 'thinking' // 哪个阶段做出的决定
-  // ... token 使用量、耗时等监控字段
-}
-```
+**设计考量**：两阶段设计在速度和准确性之间取得平衡。99% 的操作在 Stage 1 就能正确判断，只有少数模糊操作需要 Stage 2 的深度分析。这避免了每个操作都跑完整推理的性能开销。
 
 ## 安全机制
 
 ### 危险权限剥离
 
-进入 auto mode 时，系统调用 `stripDangerousPermissionsForAutoMode()`（`permissionSetup.ts:510`），移除所有可能绕过分类器的 allow 规则。
+进入 auto mode 时，系统自动剥离所有可能绕过分类器的 allow 规则：
 
-被剥离的规则类型（`dangerousPatterns.ts`）：
+| 被剥离的规则类型 | 原因 |
+|----------------|------|
+| Bash 解释器规则（python/node/bash） | 可执行任意代码 |
+| Agent allow 规则 | 会绕过分类器审批子 Agent |
+| 权限提升规则（sudo/eval） | 可执行任意命令 |
 
-| 规则类型 | 示例 | 剥离原因 |
-|---------|------|---------|
-| **Bash 代码执行** | `Bash(python:*)`, `Bash(node:*)` | 解释器可执行任意代码，绕过分类器审查 |
-| **Shell 入口** | `Bash(bash:*)`, `Bash(sh:*)` | 直接 shell 访问等同无限制 |
-| **Agent 规则** | `Agent(*)` | 任何 Agent allow 规则会绕过分类器审批子代理 |
-| **PowerShell 代码执行** | `PowerShell(node:*)` | 同 Bash 逻辑 |
-| **权限提升** | `Bash(sudo:*)`, `Bash(eval:*)` | 可执行任意命令 |
+剥离的规则在退出 auto mode 时恢复。
 
-剥离的规则被暂存在 `strippedDangerousRules` 中，退出 auto mode 时通过 `restoreDangerousPermissions()` 恢复。
+**设计哲学**：auto mode 的安全性依赖于分类器的判断。如果用户之前设置了"Bash: always allow"，分类器就被绕过了。剥离这些规则确保分类器是唯一的安全决策者。
+
+### Circuit Breaker
+
+远程配置可以在紧急情况下全局禁用 auto mode。这为 Anthropic 提供了远程紧急关停能力——如果发现分类器存在系统性漏洞，可以在不发布新版本的情况下立即禁用。
 
 ### 模型支持检测
 
-不是所有模型都支持 auto mode。`modelSupportsAutoMode()`（`src/utils/betas.ts`）检查当前模型是否具备安全分类能力。不支持的模型无法进入 auto mode。
-
-### Circuit Breaker 机制
-
-`autoModeState.ts` 维护一个 circuit breaker 标志：
-
-```typescript
-let autoModeCircuitBroken = false  // 由远程配置控制
-```
-
-当远程配置（GrowthBook `tengu_auto_mode_config.enabled`）设为 `'disabled'` 时，circuit breaker 触发，阻止 auto mode 的进入和继续使用。这为 Anthropic 提供了远程紧急关停能力。
-
-## 模式切换状态管理
-
-### 进入 Auto Mode
-
-`transitionPermissionMode()`（`permissionSetup.ts:597`）处理所有模式切换：
-
-```
-1. 检查 auto mode gate 是否开启（isAutoModeGateEnabled）
-2. 设置 autoModeActive = true
-3. 调用 stripDangerousPermissionsForAutoMode() 剥离危险规则
-4. 向对话注入 Auto Mode 系统提示
-```
-
-### 退出 Auto Mode
-
-```
-1. 设置 autoModeActive = false
-2. 设置 needsAutoModeExitAttachment = true（触发退出通知）
-3. 调用 restoreDangerousPermissions() 恢复被剥离的规则
-4. 向对话注入 "Exited Auto Mode" 提示
-```
-
-### 触发路径
-
-Auto mode 可通过以下方式激活：
-- CLI 参数 `--enable-auto-mode`
-- settings.json 中的 `autoMode` 配置
-- Plan mode 默认使用 auto mode 语义（`useAutoModeDuringPlan`，默认 true）
-- SDK 控制消息
-- REPL 中 Shift+Tab 切换
+不是所有模型都支持 auto mode。分类器需要特定的能力（如理解安全语义），不支持该能力的模型无法进入 auto mode。
 
 ## 系统提示词
 
-### 进入时（Full Instructions）
+### 进入时
 
-注入到对话中的指令（`messages.ts:3464`）：
+注入到对话中的指令要求 AI：
+1. **直接执行** — 做合理假设，减少提问
+2. **偏好行动** — 默认直接编码，不进 plan mode
+3. **避免破坏性操作** — 删除数据、修改生产系统仍需确认
 
-> Auto mode is active. The user chose continuous, autonomous execution. You should:
->
-> 1. **Execute immediately** — 直接实现，做合理假设
-> 2. **Minimize interruptions** — 常规决策自行判断，减少提问
-> 3. **Prefer action over planning** — 默认直接编码，不进 plan mode
-> 4. **Expect course corrections** — 用户可随时纠正
-> 5. **Do not take overly destructive actions** — 删除数据/修改生产系统仍需确认
-> 6. **Avoid data exfiltration** — 不主动分享密钥/内部文档
+### 退出时
 
-### 持续运行时（Sparse Instructions）
+注入"退出 auto mode"提示，要求 AI 回到谨慎模式——方案不明确时提问而非假设。
 
-后续轮次注入简短提醒：
+## 降级策略
 
-> Auto mode still active. Execute autonomously, minimize interruptions, prefer action over planning.
+当分类器 API 不可用时：
+- **不直接 allow** — 回退到传统权限对话框
+- 告知 AI 分类器暂时不可用
+- 确定性错误（如对话过长）不重试
 
-### 退出时（Exit Instructions）
-
-> You have exited auto mode. Ask clarifying questions when the approach is ambiguous rather than making assumptions.
+**设计哲学**：降级到更安全的行为。宁可多确认一次，也不要在没有分类器保护的情况下自动放行。
 
 ## 与 Plan Mode 的协作
 
-Plan mode 默认使用 auto mode 语义（`getUseAutoModeDuringPlan()`，默认 true）。这意味着：
+Plan mode 默认使用 auto mode 语义——在只读探索阶段，分类器自动判断哪些只读操作是安全的，进一步减少打断。
 
-- Plan mode 进入时，如果 auto mode 可用，也会激活分类器
-- `isAutoModeActive()` 是权威信号（`prePlanMode`/`strippedDangerousRules` 不可靠）
-- 退出 plan mode 时会同时退出 auto mode
+## 接下来
 
-## 分类器不可用的降级策略
-
-当分类器 API 不可用时（`unavailable: true` 或 `transcriptTooLong: true`）：
-
-- 不会直接 allow — 回退到传统的权限对话框（ask）
-- 向 AI 发送消息："{model} is temporarily unavailable, so auto mode cannot determine the safety of {toolName} right now."
-- 确定性错误（如对话过长）不重试，直接降级
-
-## 分类器 Prompt 模板
-
-分类器的行为由三个 prompt 文件控制，位于 `src/utils/permissions/yolo-classifier-prompts/`。这些文件在构建时通过 `require()` 内联为字符串常量，运行时不可修改。
-
-### auto_mode_system_prompt.txt
-
-主系统提示词，定义分类器的角色、分类流程和决策类别。包含：
-
-- **分类流程**：理解操作 → 检查用户意图 → 评估风险
-- **BLOCK 始终阻止**：外部代码执行、不可逆删除、未授权持久化、安全削弱、提权、网络服务
-- **BLOCK 除非明确意图**：CWD 外写入、系统包管理、git push、大规模变更
-- **ALLOW 安全操作**：读文件、搜索、git 只读命令、测试/lint/构建、CWD 内编辑
-- `<permissions_template>` 占位符 — 运行时替换为具体权限模板（external 或 anthropic）
-- 末尾 `Use the classify_result tool to report your classification.` — XML 模式下被替换为 `<block>` 标签格式说明
-
-### permissions_external.txt
-
-外部用户版本的权限模板。三个 `<user_*_to_replace>` 标签内包裹默认规则（bullet 格式），用户自定义规则**整体替换**默认值：
-
-```
-<user_allow_rules_to_replace>
-- 默认 allow 规则 1
-- 默认 allow 规则 2
-</user_allow_rules_to_replace>
-```
-
-- **allow**：9 条默认规则（只读命令、版本检查、git 只读、测试/lint/构建、包安装、CWD 内文件操作等）
-- **soft_deny**：10 条默认规则（外部代码执行、递归删除、shell 配置修改、提权、网络服务等）
-- **environment**：4 条环境描述（终端环境、auto mode 上下文、开发工具可用、语言/框架不限）
-
-`getDefaultExternalAutoModeRules()` 从此文件提取 bullet 项，供 `claude auto-mode defaults` 命令输出。
-
-### permissions_anthropic.txt
-
-Anthropic 内部版本的权限模板。默认规则在标签**外部**，标签内为空，用户自定义规则以**追加**方式叠加：
-
-```
-- 默认规则（在标签外，始终生效）
-<user_allow_rules_to_replace>
-</user_allow_rules_to_replace>
-```
-
-相比 external 版本，额外包含：
-- 云 CLI 只读命令（aws describe, gcloud describe, kubectl get 等）
-- 基础设施即代码 plan 命令（terraform plan, pulumi preview 等）
-- 对应的 deny 规则（云资源创建/修改/删除、IaC apply、生产环境访问等）
-
-### 模板替换流程
-
-```
-buildYoloSystemPrompt()
-  ├── BASE_PROMPT.replace('<permissions_template>', EXTERNAL/ANTHROPIC_TEMPLATE)
-  ├── .replace(<user_allow_rules_to_replace>, userAllow ?? defaults)
-  ├── .replace(<user_deny_rules_to_replace>, userDeny ?? defaults)
-  └── .replace(<user_environment_to_replace>, userEnvironment ?? defaults)
-```
-
-- 外部模板：用户设置非空时**替换**对应标签内容，否则保留默认值
-- 内部模板：用户设置**追加**到默认值之后（标签在末尾为空）
-
-## 当前状态说明
-
-> **注意**：auto mode 的完整代码逻辑已存在于代码库中，但依赖 `feature('TRANSCRIPT_CLASSIFIER')` feature flag。
-> 在当前反编译版本中，`feature()` 始终返回 `false`，因此 auto mode 不可用。
-> 要启用需将 `feature('TRANSCRIPT_CLASSIFIER')` 改为 `true`，并确保 GrowthBook 配置源有合理的 fallback 默认值。
-
-Prompt 模板文件为**重建产物**——原始文件在反编译过程中丢失，已根据代码逻辑和 `yoloClassifier.ts` 中的替换模式重新编写。
-
-## 相关源码索引
-
-| 文件 | 职责 |
-|------|------|
-| `src/utils/permissions/yoloClassifier.ts` | 分类器核心实现 |
-| `src/utils/permissions/autoModeState.ts` | Auto mode 状态管理 |
-| `src/utils/permissions/permissionSetup.ts` | 模式切换、危险权限剥离 |
-| `src/utils/permissions/dangerousPatterns.ts` | 危险命令模式列表 |
-| `src/utils/permissions/classifierDecision.ts` | 分类器决策处理 |
-| `src/utils/permissions/classifierShared.ts` | 分类器共享逻辑 |
-| `src/utils/permissions/bashClassifier.ts` | Bash 命令分类规则 |
-| `src/utils/permissions/bypassPermissionsKillswitch.ts` | bypass 权限熔断器 |
-| `src/utils/permissions/yolo-classifier-prompts/auto_mode_system_prompt.txt` | 分类器主系统提示词 |
-| `src/utils/permissions/yolo-classifier-prompts/permissions_external.txt` | 外部权限模板 |
-| `src/utils/permissions/yolo-classifier-prompts/permissions_anthropic.txt` | 内部权限模板 |
-| `src/cli/handlers/autoMode.ts` | CLI `auto-mode` 子命令处理 |
-| `src/utils/messages.ts` | Auto mode 系统提示词注入 |
-| `src/types/permissions.ts` | 权限类型定义 |
-| `src/utils/betas.ts` | 模型 auto mode 支持检测 |
+- **权限模型** — 理解 auto mode 在权限体系中的位置
+- **Plan Mode** — 理解"先规划再执行"的安全工作流
+- **为什么安全很重要** — 理解安全体系的设计动机

docs/safety/permission-model.mdx

@@ -1,170 +1,106 @@
 ---
-title: "权限模型 - Allow/Ask/Deny 三级权限体系"
-description: "详解 Claude Code 的三级权限模型实现：基于 src/utils/permissions/permissions.ts 的规则匹配引擎、五层规则来源优先级、工具名/命令/路径三维度匹配、Denial Tracking 死循环防护、权限模式切换机制。"
-keywords: ["权限模型", "Allow Ask Deny", "PermissionRule", "checkPermissions", "Denial Tracking", "权限规则"]
+title: "权限模型"
+description: "AI 执行命令是最危险的能力。Allow/Ask/Deny 三级权限体系如何在安全与效率间取得平衡？理解规则来源、匹配引擎和死循环防护。"
+keywords: ["权限模型", "Allow Ask Deny", "权限规则", "权限模式"]
 ---
 
-{/* 本章目标：基于源码揭示权限系统的完整实现 */}
+## 核心问题
+
+AI 可以读取文件、执行命令、修改代码——这些操作在带来效率的同时也带来风险。权限系统的问题是：**什么时候需要人类确认，什么时候可以自动放行？**
 
 ## 三种权限行为
 
-每一次工具调用，系统都会做出三种裁决之一：
+| 行为 | 含义 | 用户感知 |
+|------|------|---------|
+| **Allow** | 自动放行 | 无感知 |
+| **Ask** | 弹出确认 | 需要批准或拒绝 |
+| **Deny** | 直接拒绝 | 被告知原因 |
 
-| 行为 | 含义 | 返回类型 | 典型场景 |
-|------|------|---------|---------|
-| **Allow** | 自动放行，用户无感知 | `{ behavior: 'allow', updatedInput, decisionReason }` | Read 读取项目内文件 |
-| **Ask** | 弹出确认对话框 | `{ behavior: 'ask', message, suggestions, metadata }` | Bash 执行未知命令 |
-| **Deny** | 直接拒绝 | `{ behavior: 'deny', message, decisionReason }` | 尝试执行被禁止的命令 |
+## 规则来源的八层优先级
 
-这些行为由 `PermissionResult` 类型定义（`src/utils/permissions/PermissionResult.ts`）。
-
-## 权限规则的五层来源
-
-规则从 5 个来源汇聚（`PERMISSION_RULE_SOURCES`，`permissions.ts:109`），优先级从高到低：
+权限规则从 8 个来源汇聚，后者覆盖前者：
 
 ```
-1. session        — 用户在当前对话中手动授权（"Always allow"）
-2. cliArg         — 命令行 --allow/--deny 参数
-3. command        — Skill 工具的 allowedTools 白名单
-4. projectSettings — .claude/settings.json（团队共享）
-5. userSettings   — ~/.claude/settings.json（跨项目）
-6. policySettings — 企业管理员下发的策略（用户不可覆盖）
+用户全局设置 < 项目设置 < 本地覆盖 < 命令行参数 < 企业策略 < CLI 参数 < 技能白名单 < 本次会话授权
 ```
 
-每个来源维护三个数组：`alwaysAllowRules[source]`、`alwaysAskRules[source]`、`alwaysDenyRules[source]`。
+**设计考量**：
+- **企业策略不可被用户覆盖**——企业管理员可以通过策略强制禁止某些操作
+- **本次会话授权优先级最高**——用户在对话中选择"Always allow"立即生效
+- **项目设置可被 git 追踪**——团队可以通过 `.claude/settings.json` 共享权限规则
 
-规则数据结构为 `PermissionRule`：
-```typescript
-{
-  source: PermissionRuleSource      // 来自哪个层级
-  ruleBehavior: 'allow' | 'ask' | 'deny'
-  ruleValue: {
-    toolName: string                // 如 "Bash"、"mcp__server1"
-    ruleContent?: string            // 如 "git *"、"src/**"
-  }
-}
-```
+### 规则结构
 
-## 规则匹配引擎
+每条规则指定三个要素：
+- **工具名**：如 `Bash`、`Edit`、`mcp__server1`
+- **匹配内容**：如 `git *`（命令模式）、`src/**`（路径模式）
+- **行为**：allow / ask / deny
 
-### 三维度匹配
+## 三维度匹配引擎
 
-`permissions.ts` 实现了三种匹配维度：
+### 1. 工具名匹配
 
-**1. 工具名匹配**（`toolMatchesRule()`，第 238 行）
+最简单的匹配——规则只指定工具名，没有额外内容：
+- `"Bash"` → 匹配所有 Bash 调用
+- `"mcp__server1"` → 匹配该 MCP Server 的所有工具
 
-匹配整个工具，仅当规则没有 `ruleContent`：
-```typescript
-// 精确匹配
-rule "Bash" → 匹配 BashTool
-rule "mcp__server1" → 匹配该 MCP Server 的所有工具（server 级别）
-rule "mcp__server1__*" → 通配符匹配（同上）
-```
+### 2. 命令模式匹配（Bash 专用）
 
-MCP 工具使用 `getToolNameForPermissionCheck()` 获取匹配名称，支持有前缀（`mcp__server__tool`）和无前缀模式。
+Bash 工具的规则可以指定命令模式：
+- `{"tool": "Bash", "content": "git *"}` → 匹配 `git commit -m 'fix'`
 
-**2. 命令模式匹配**（BashTool 的 `checkPermissions()`）
+命令通过 AST 解析提取第一个子命令进行匹配，不受管道或条件表达式干扰。
 
-BashTool 通过 `preparePermissionMatcher()`（`Tool.ts:514`）解析命令模式：
-```json
-{"tool": "Bash", "ruleContent": "git *"}  → 匹配 "git commit -m 'fix'"
-```
+### 3. 路径匹配（文件工具专用）
 
-命令通过 AST 解析（`readOnlyValidation.ts` 使用 tree-sitter bash），提取第一个子命令进行匹配。
+Read/Edit/Write 工具的规则可以指定文件路径 glob：
+- `{"tool": "Edit", "content": "src/**"}` → 匹配 `src/utils/foo.ts`
 
-**3. 路径匹配**（文件工具的 `checkPermissions()`）
+**设计洞察**：三维度匹配对应三种不同的安全关注点：
+- 工具名 → "这个工具允不允许用"
+- 命令模式 → "这条命令安不安全"
+- 路径 → "这个文件能不能碰"
 
-Read/Edit/Write 工具通过 `getPath()` 提取文件路径，与 `ruleContent` 中的 glob 模式匹配：
-```json
-{"tool": "Edit", "ruleContent": "src/**"}  → 匹配 "src/utils/foo.ts"
-```
-
-### 权限检查的完整流程
-
-每次工具调用的权限检查（`canUseTool()` → `checkPermissions()`）经过以下步骤：
+## 权限检查流程
 
 ```
-1a. Blanket deny 检查
-    getDenyRuleForTool() → 工具名完全匹配 deny 规则？
-    ↓ 命中 → deny（工具在 getTools() 阶段就被过滤掉）
-
-1b. Blanket allow 检查
-    toolAlwaysAllowedRule() → 工具名完全匹配 allow 规则？
-    ↓ 命中 → allow
-
-2. 工具自身 checkPermissions()
-    各工具有自定义逻辑：
-    - BashTool: readOnlyValidation → sandbox 判定 → AST 解析 → 模式匹配
-    - FileEditTool: 路径白名单检查
-    - SkillTool: safe properties 白名单 + 精确/前缀匹配
-    ↓ 返回 PermissionResult
-
-3. Hook 系统
-    executePermissionRequestHooks() → PreToolUse hook 可以 override
-    ↓ hook 返回 deny → deny
-    ↓ hook 返回 ask → 升级为 ask
-
-4. Ask 规则检查
-    getAskRules() → 命中 → ask
-
-5. 默认行为
-    根据当前 permissionMode 决定默认行为
-    - 'default': 大部分工具 ask
-    - 'plan': 写操作 deny，读操作 allow
-    - 'bypass': 全部 allow
+Blanket deny → 工具名完全匹配 deny 规则？ → 直接拒绝
+Blanket allow → 工具名完全匹配 allow 规则？ → 直接放行
+工具自身检查 → 各工具有自定义逻辑
+Hook 系统 → PreToolUse hook 可以覆盖结果
+Ask 规则 → 匹配则弹出确认
+默认行为 → 由当前权限模式决定
 ```
 
+**设计哲学**：deny 优先于 allow。如果某条规则说"禁止 Bash"，即使另一条规则说"允许 Bash"，最终结果也是禁止。
+
 ## 权限模式
 
-| 模式 | `PermissionMode` 值 | 适用场景 | 行为 |
-|------|---------------------|---------|------|
-| **Default** | `'default'` | 日常使用 | 敏感操作逐一确认 |
-| **Plan Mode** | `'plan'` | 探索阶段 | 只能读不能写（`isReadOnly()` 检查） |
-| **Auto** | `'auto'` | 信任 AI | 通过 transcript classifier 自动决策 |
-| **Bypass** | `'bypassPermissions'` | 完全信任 | 所有操作自动放行（需显式 `--dangerously-skip-permissions`） |
+| 模式 | 适用场景 | 行为 |
+|------|---------|------|
+| **Default** | 日常使用 | 敏感操作逐一确认 |
+| **Plan Mode** | 探索阶段 | 只能读不能写 |
+| **Accept Edits** | 快速迭代 | 文件编辑自动放行 |
+| **Don't Ask** | 减少打断 | 尽量自动决策 |
+| **Auto** | 信任 AI | 自动分类决策 |
+| **Bypass** | 完全信任 | 所有操作自动放行 |
 
-Plan Mode 切换由 `EnterPlanModeTool.call()` 触发：
-```typescript
-// EnterPlanModeTool.ts:88
-context.setAppState(prev => ({
-  ...prev,
-  toolPermissionContext: applyPermissionUpdate(
-    prepareContextForPlanMode(prev.toolPermissionContext),
-    { type: 'setMode', mode: 'plan', destination: 'session' },
-  ),
-}))
-```
-
-退出时由 `ExitPlanModeV2Tool` 恢复为之前的模式。
+**设计考量**：权限模式不是"越宽松越好"。Default 模式下每次确认看似烦人，但它是防止 AI 误操作的最后防线。Bypass 模式需要显式的危险标志才能启用——这不是给日常使用的。
 
 ## Denial Tracking：死循环防护
 
-`src/utils/permissions/denialTracking.ts` 实现了拒绝追踪机制：
+当 AI 被连续拒绝同一类操作达到 3 次时，系统注入消息迫使其改变策略。
 
-```typescript
-const DENIAL_LIMITS = {
-  maxDenialsPerTool: 3,        // 同一工具连续拒绝上限
-  cooldownPeriodMs: 30_000,    // 冷却期 30 秒
-}
-```
+**为什么需要这个**？AI 有时会陷入"请求 → 被拒 → 用略有不同的方式请求同一个操作 → 再被拒"的死循环。Denial tracking 检测到这种模式后强制 AI 换思路。
 
-当 AI 被连续拒绝同一类操作达到上限时：
-1. `recordDenial()` 记录拒绝，增加计数
-2. `shouldFallbackToPrompting()` 检测到连续拒绝，返回 true
-3. 系统向 AI 注入消息："Your previous tool call was rejected..."
-4. AI 被迫改变策略，避免"反复请求同一个被拒操作"的死循环
+这是一个经典的"AI 行为修正"设计——不是通过硬约束阻止特定行为，而是通过反馈引导 AI 自行调整。
 
-操作成功时调用 `recordSuccess()` 重置计数。
+## 运行时更新
 
-## 规则的运行时更新
+权限规则可以在运行时动态更新。当用户在确认对话框中选择"Always allow"，规则被同时写入 settings 文件和内存中的权限上下文，立即生效。
 
-权限规则可以在运行时动态更新（`applyPermissionUpdate()`，`PermissionUpdate.ts`）：
+## 接下来
 
-```typescript
-type PermissionUpdate =
-  | { type: 'addRule', behavior, rule, destination }
-  | { type: 'removeRule', behavior, rule, destination }
-  | { type: 'setMode', mode, destination }
-```
-
-当用户在 Ask 对话框中选择 "Always allow"，系统调用 `persistPermissionUpdates()` 将规则写入对应层级的 settings 文件（project/user/managed），同时更新内存中的 `toolPermissionContext`。
+- **为什么安全很重要** — 理解权限系统的设计动机
+- **Plan Mode** — 理解"先规划再执行"的安全工作流
+- **沙箱** — 理解 Bash 命令的隔离执行环境

docs/safety/plan-mode.mdx

@@ -1,151 +1,82 @@
 ---
-title: "计划模式 - Plan Mode 先看后做的安全机制"
-description: "基于源码解析 Claude Code Plan Mode 的完整实现：EnterPlanModeTool/ExitPlanModeV2Tool 的工具设计、权限上下文切换机制、Prompt-based 权限请求、计划文件持久化、Teammate 审批流程。"
-keywords: ["Plan Mode", "计划模式", "EnterPlanMode", "ExitPlanMode", "prepareContextForPlanMode", "allowedPrompts"]
+title: "Plan Mode"
+description: "先看后做的安全机制。Plan Mode 让 AI 在探索阶段只能读不能写，形成方案后再提交用户审批。理解权限收窄、Prompt-based 权限和计划持久化的设计。"
+keywords: ["Plan Mode", "计划模式", "先规划再执行", "安全工作流"]
 ---
 
-{/* 本章目标：基于源码揭示 Plan Mode 的完整实现 */}
-
-## 问题场景
+## 核心问题
 
 你说"重构这个模块"，AI 立刻开始改代码——但你还没搞清楚它打算怎么改。等改了一半发现方向不对，已经来不及了。
 
-## Plan Mode 的解决方案
+## 解决方案：先看后做
 
-计划模式给对话加了一个"只读阶段"，通过两个工具实现闭环：
+Plan Mode 给对话加了一个"只读阶段"：
 
 <Steps>
-  <Step title="EnterPlanMode — 进入计划模式">
-    AI 自主判断（或用户触发）任务需要规划，调用 `EnterPlanModeTool`（`src/tools/EnterPlanModeTool/EnterPlanModeTool.ts:36`）。该工具需要**用户审批**（`checkPermissions` 返回 `ask`）。
+  <Step title="进入计划模式">
+    AI 判断任务需要规划，请求进入 Plan Mode。需要**用户审批**。
   </Step>
-  <Step title="探索阶段 — 只读工具集">
-    权限模式切换为 `'plan'`，AI 只能使用 `isReadOnly()` 为 true 的工具（Read、Grep、Glob、Agent 等）。写操作被自动拒绝。
+  <Step title="探索阶段">
+    AI 只能使用只读工具（Read、Grep、Glob）。写操作被自动拒绝。
   </Step>
-  <Step title="ExitPlanMode — 提交方案审批">
-    AI 完成探索后，调用 `ExitPlanModeV2Tool`（`src/tools/ExitPlanModeTool/ExitPlanModeV2Tool.ts:147`），将计划文件提交给用户审阅。这是第二个**需要用户审批**的节点。
+  <Step title="提交方案审批">
+    AI 完成探索后，将计划文件提交给用户审阅。这是第二个**需要审批**的节点。
   </Step>
-  <Step title="恢复执行 — 全部工具权限">
-    用户批准后，权限模式恢复为进入前的状态，AI 按计划执行。
+  <Step title="恢复执行">
+    用户批准后，权限恢复，AI 按计划执行。
   </Step>
 </Steps>
 
+**两个审批节点的设计**：进入时审批（"我可以探索吗？"）和退出时审批（"这个方案可以吗？"）。两次审批确保用户对过程和结果都有控制权。
+
 ## 权限的自动收窄与恢复
 
-### 进入：`prepareContextForPlanMode()`
+### 进入：只读锁定
 
-`EnterPlanModeTool.call()`（第 77 行）的核心逻辑：
+权限模式切换为 `plan`，所有工具的 `isReadOnly()` 检查成为唯一准入条件。不是"某些工具被禁用"，而是"只有标记为只读的工具才能执行"。
 
-```typescript
-// 1. 记录转换状态（保存之前的模式）
-handlePlanModeTransition(currentMode, 'plan')
+**设计考量**：基于属性而非名单的权限控制更安全。如果新增了一个工具但忘记把它加入"plan 模式禁用名单"，基于名单的系统会漏过它；但基于 `isReadOnly()` 的系统不会——新工具必须显式声明自己只读才能在 Plan Mode 中使用。
 
-// 2. 切换权限上下文为 plan 模式
-context.setAppState(prev => ({
-  ...prev,
-  toolPermissionContext: applyPermissionUpdate(
-    prepareContextForPlanMode(prev.toolPermissionContext),
-    { type: 'setMode', mode: 'plan', destination: 'session' },
-  ),
-}))
-```
+### 退出：Prompt-based 权限
 
-`prepareContextForPlanMode()`（`src/utils/permissions/permissionSetup.ts`）做了什么：
-- 创建新的 `ToolPermissionContext`，`mode` 设为 `'plan'`
-- 在 plan 模式下，工具的 `isReadOnly()` 检查成为唯一准入条件
-- 如果用户的默认模式是 `'auto'`，还会激活 classifier 的副作用
+AI 可以在计划中声明它需要执行的命令类别。用户批准计划后，这些命令自动放行。
 
-### 退出：权限恢复 + Prompt-based 权限
+**设计洞察**：这是 Plan Mode 最精妙的设计。传统做法是：计划完成后，AI 每执行一步都要用户确认。Prompt-based 权限让用户在审批计划时"一揽子"授权了后续操作——既减少了打断，又保持了控制。
 
-`ExitPlanModeV2Tool` 的退出逻辑做了两件关键的事：
+当然，AI 只能获得计划中声明的权限。如果计划说"运行测试"，AI 不能突然执行 `rm -rf /`。
 
-**1. 恢复权限模式**
+## 计划文件：可编辑的方案
 
-通过 `handlePlanModeTransition()` 和 `applyPermissionUpdate()` 恢复到进入前的模式。
+计划内容被写入磁盘文件，用户可以在审批前修改 AI 的方案。
 
-**2. 注入 Prompt-based 权限**
+**为什么不直接在对话中展示计划**？
+1. 对话中的计划是"只读"的，用户无法直接修改
+2. 磁盘文件可以被用户用任何编辑器修改
+3. 修改后的计划成为 AI 执行的"合约"——AI 必须执行用户修改后的版本
 
-这是 Plan Mode 最精妙的设计——AI 可以在计划中声明它需要执行的命令类别：
+## 什么时候该用 Plan Mode
 
-```typescript
-// ExitPlanModeV2Tool 的 inputSchema
-allowedPrompts: z.array(z.object({
-  tool: z.enum(['Bash']),
-  prompt: z.string().describe('Semantic description, e.g. "run tests"'),
-})).optional()
-```
+| 场景 | 应该用吗 | 原因 |
+|------|:--------:|------|
+| 修复 typo | 跳过 | 改动明确，无需规划 |
+| 添加删除按钮 | 通常跳过 | 路径明确 |
+| 重构认证系统 | **使用** | 高影响，需要理解全局 |
+| 架构决策（Redis vs 内存缓存） | **使用** | 需要权衡多种方案 |
+| 用户说"开始做 X" | 通常跳过 | 用户已明确意图 |
 
-当 AI 提交计划时，如果声明了 `allowedPrompts: [{ tool: 'Bash', prompt: 'run tests' }]`，用户批准后，"run tests" 这类 Bash 命令会被自动放行——不再需要逐个确认。
+**设计哲学**：Plan Mode 是工具而非默认行为。AI 应该在"不确定性高"时使用它，而不是在每次修改时都进入。过度使用 Plan Mode 会降低效率，如同人类在每次改代码前都写设计文档一样低效。
 
-## 计划文件的持久化
+## 与任务系统的配合
 
-计划内容被写入磁盘文件（由 `getPlanFilePath()` 确定路径），这与简单的"AI 说一段话然后开始执行"有本质区别：
-
-1. `ExitPlanModeV2Tool` 的 `normalizeToolInput` 从磁盘读取计划内容，注入到 `input.plan` 和 `input.planFilePath`
-2. 计划文件是用户**可编辑**的——用户可以在审批前修改 AI 的方案
-3. `planWasEdited` 字段标记用户是否修改了计划，影响后续的 tool_result 回显
-4. `persistFileSnapshotIfRemote()` 在远程场景下保存文件快照
-
-## Teammate 场景下的计划审批
-
-在 Agent Swarms（`isAgentSwarmsEnabled()`）模式下，计划审批有额外的协作流程：
-
-```typescript
-// 如果是 Teammate 角色
-if (isTeammate()) {
-  // 发送计划到 Team Leader 的 mailbox 等待审批
-  const requestId = generateRequestId()
-  writeToMailbox(getTeamName(), {
-    type: 'plan_approval_request',
-    plan, requestId, ...
-  })
-  // 返回 awaitingLeaderApproval: true
-  // Team Leader 审批后通过 mailbox 通知 Teammate
-}
-```
-
-这意味着在蜂群模式下，计划可能不是由直接用户审批，而是由 Team Leader 审批。
-
-## 什么时候该用计划模式
-
-`EnterPlanModeTool` 的 Prompt（`src/tools/EnterPlanModeTool/prompt.ts`）定义了两套触发标准——外部版本更积极（鼓励规划），内部版本更克制（仅在真正模糊时使用）：
-
-| 场景 | 外部版本 | 内部版本 |
-|------|---------|---------|
-| 修复 typo | 跳过 | 跳过 |
-| 添加删除按钮 | **进入**（涉及多个文件） | **跳过**（路径明确） |
-| 重构认证系统 | **进入** | **进入**（高影响重构） |
-| "开始做 X" | — | **跳过**（直接开始） |
-| 架构决策（Redis vs 内存缓存） | **进入** | **进入**（真正模糊） |
-
-## 计划模式 + 任务系统
-
-计划模式通常与任务系统配合使用：
-
-1. 在计划模式中，AI 把实施步骤创建为任务列表（`TodoWrite`）
+Plan Mode 通常与任务系统配合：
+1. AI 在探索阶段创建任务列表
 2. 用户审批计划（包含任务列表）
-3. 退出计划模式后，AI 按任务列表逐项执行
-4. 用户可以通过任务列表追踪进度
+3. 退出 Plan Mode 后，AI 按任务列表逐项执行
 
-## 完整生命周期
+这把"理解"和"执行"在时间上分开了——先花时间理解问题，再高效执行方案。
 
-```
-用户: "重构这个模块"
-  ↓
-AI 判断需要规划 → 调用 EnterPlanModeTool
-  ↓ 用户审批（Ask 对话框）
-handlePlanModeTransition(default, 'plan')  // 保存 default
-prepareContextForPlanMode()                // 创建只读上下文
-  ↓
-AI 使用 Read/Grep/Glob/Agent 探索代码库
-  ↓ （可能 10+ 轮只读工具调用）
-AI 形成方案 → 调用 ExitPlanModeV2Tool({
-  allowedPrompts: [
-    { tool: 'Bash', prompt: 'run tests' },
-    { tool: 'Bash', prompt: 'install dependencies' }
-  ]
-})
-  ↓ 用户审批计划（可编辑计划文件）
-恢复权限模式 → 注入 prompt-based 权限
-  ↓
-AI 使用全部工具执行计划，"run tests" 等命令自动放行
-```
+## 接下来
+
+- **权限模型** — 理解支撑 Plan Mode 的完整权限体系
+- **任务管理** — 理解 Plan Mode 中创建的任务追踪
+- **子 Agent** — 理解 Plan Mode 中使用的 Explore Agent

docs/safety/sandbox.mdx

@@ -20,7 +20,7 @@ keywords: ["沙箱", "sandbox", "权限", "Bash", "PowerShell", "bubblewrap", "s
 - 这一层仓库自己负责：策略、配置转换、启停判断、命令包裹、清理和权限联动
 - 真正做 OS 级隔离的是外部运行时 `@anthropic-ai/sandbox-runtime`
 
-在 `src/utils/sandbox/sandbox-adapter.ts` 里，可以很清楚地看到这条边界：项目导入 `SandboxManager as BaseSandboxManager`、`SandboxViolationStore` 等运行时对象，然后在外面再包一层符合 Claude Code 自身权限模型的适配器。
+适配层负责导入底层运行时对象（`SandboxManager`、`SandboxViolationStore` 等），然后在它们外面再包一层符合 Claude Code 自身权限模型的接口。
 
 底层隔离在不同平台上的落地也不是同一套实现：
 
@@ -64,7 +64,7 @@ keywords: ["沙箱", "sandbox", "权限", "Bash", "PowerShell", "bubblewrap", "s
 
 ### 1. 给 shell 一个 OS 级兜底
 
-`src/utils/bash/ast.ts` 开头就写得很明确：Bash AST 分析不是沙箱，它只是在判断我们能不能可靠地理解命令结构，不能阻止危险命令真的运行。
+Bash AST 分析明确声明自己不是沙箱——它只判断"能不能可靠地理解命令结构"，不能阻止危险命令真正运行。
 
 这就是为什么应用层再聪明，也很难仅靠“执行前推断”覆盖完整风险面。像下面这些命令，真实副作用都要到运行时才完全展开：
 
@@ -106,7 +106,7 @@ keywords: ["沙箱", "sandbox", "权限", "Bash", "PowerShell", "bubblewrap", "s
 
 ### 4. 拦截运行时绕过和逃逸路径
 
-这个仓库在 `src/utils/sandbox/sandbox-adapter.ts` 里专门把一些高风险路径额外加入 `denyWrite`，例如：
+适配层专门把一些高风险路径额外加入 `denyWrite`，例如：
 
 - `settings.json`
 - `.claude/skills`
@@ -138,7 +138,7 @@ keywords: ["沙箱", "sandbox", "权限", "Bash", "PowerShell", "bubblewrap", "s
 - 纯应用层的权限弹窗和规则匹配
 - Bash AST 解析本身
 
-尤其要注意一点：Bash AST 分析不是沙箱。源码自己写得很明确，它只回答“我们能不能可信地提取 argv 结构”，并不负责阻止危险命令真正运行。
+尤其要注意一点：Bash AST 分析不是沙箱。它只回答”我们能不能可信地提取 argv 结构”，并不负责阻止危险命令真正运行。
 
 ## 哪些场景会走沙箱
 
@@ -166,7 +166,7 @@ keywords: ["沙箱", "sandbox", "权限", "Bash", "PowerShell", "bubblewrap", "s
 5. 这条命令没有被显式排除
 6. 这次调用没有被允许以 `dangerouslyDisableSandbox` 绕过
 
-对应入口在 `src/tools/BashTool/shouldUseSandbox.ts` 和 `src/utils/sandbox/sandbox-adapter.ts`。
+对应入口在 `shouldUseSandbox()` 和沙箱适配层中。
 
 ### 3. PowerShell 只在支持平台上走
 
@@ -514,20 +514,6 @@ REPL / CLI 启动
 
 而沙箱负责的是最终兜底。
 
-## 推荐的阅读路径
-
-如果你想继续顺着源码深入，推荐按下面顺序看：
-
-1. `src/tools/BashTool/shouldUseSandbox.ts`
-2. `src/utils/Shell.ts`
-3. `src/utils/sandbox/sandbox-adapter.ts`
-4. `src/utils/permissions/permissions.ts`
-5. `src/tools/BashTool/bashPermissions.ts`
-6. `src/utils/permissions/pathValidation.ts`
-7. `src/utils/permissions/filesystem.ts`
-
-按这条线读，会更容易把“权限系统”和“沙箱系统”在脑中拆开。
-
 ## FAQ
 
 ### Q1：Linux 下 `echo hi > /etc/hosts` 会怎样？

docs/safety/why-safety-matters.mdx

@@ -61,7 +61,7 @@ Claude 的 System Prompt 中包含安全指令——这是"软性"约束，依
 | `deny` | 直接拒绝 | 匹配 deny 规则 |
 | `ask` | 弹窗确认 | 未匹配任何规则 或 匹配 ask 规则 |
 
-以 BashTool 为例（`src/tools/BashTool/bashPermissions.ts`），`bashToolHasPermission()` 执行了极其细致的检查链：
+以 BashTool 为例（`packages/builtin-tools/src/tools/BashTool/bashPermissions.ts`），`bashToolHasPermission()` 执行了极其细致的检查链：
 
 1. **AST 安全解析**：用 tree-sitter 解析 bash AST，检测命令注入（`$()`、反引号等）
 2. **语义检查**：识别危险命令（`eval`、`exec`、`source` 等）
@@ -169,7 +169,7 @@ Bash("rm -rf node_modules")  → ⚠️ 需确认（不可逆）
 攻击：cd /malicious/dir && git status
       /malicious/dir 包含 bare repo + 恶意钩子
 防御：bashToolHasPermission() 检测 cd + git 组合
-      强制 require approval（src/tools/BashTool/bashPermissions.ts:2209）
+      强制 require approval（packages/builtin-tools/src/tools/BashTool/bashPermissions.ts:2209）
 ```
 
 ### 场景3：管道注入
@@ -178,5 +178,5 @@ Bash("rm -rf node_modules")  → ⚠️ 需确认（不可逆）
 攻击：echo 'x' | xargs printf '%s' >> /etc/passwd
       splitCommand 会剥离重定向，导致路径检查遗漏
 防御：即使管道段独立检查通过，仍对原始命令重新验证路径约束
-      检查重定向目标中的危险模式（反引号、$()）（bashPermissions.ts:1992-2056）
+      检查重定向目标中的危险模式（反引号、$()）（packages/builtin-tools/src/tools/BashTool/bashPermissions.ts:1992-2056）
 ```

docs/task/task-001-daemon-status-stop.md

@@ -0,0 +1,77 @@
+# Task 001: daemon status / stop
+
+> 来源: [stub-recovery-design-1-4.md](../features/stub-recovery-design-1-4.md) 第 1 项
+> 优先级: P0 (首选实现项)
+> 工作量: 小
+> 状态: DONE
+
+## 目标
+
+让 `claude daemon status` 和 `claude daemon stop` 在任意 CLI 进程中都能正确工作，不依赖 TUI 内存态。
+
+## 背景
+
+- `start` 路径已有完整 supervisor + worker 生命周期 (`src/daemon/main.ts`, `src/daemon/workerRegistry.ts`)
+- `status` / `stop` 目前只是占位输出 (`src/daemon/main.ts:49`)
+- `/remote-control-server` 有自己的命令内 UI 状态，但只维护当前进程内的 `daemonProcess`，不适合跨进程管理
+
+## 实现方案
+
+### 新增文件
+
+| 文件 | 说明 |
+|------|------|
+| `src/daemon/state.ts` | daemon 状态文件读写模块 |
+
+### 修改文件
+
+| 文件 | 改动 |
+|------|------|
+| `src/daemon/main.ts` | `start` 写入状态文件；`status`/`stop` 调用 state 模块 |
+| `src/commands/remoteControlServer/remoteControlServer.tsx` | 读取同一份状态文件（轻量改动） |
+
+### 状态文件
+
+路径: `~/.claude/daemon/remote-control.json`
+
+```json
+{
+  "pid": 12345,
+  "cwd": "/path/to/project",
+  "startedAt": "2026-04-12T10:00:00Z",
+  "workerKinds": ["bridge", "rcs"],
+  "lastStatus": "running"
+}
+```
+
+### status 逻辑
+
+1. 读取状态文件
+2. 用进程探测验证 pid 是否存活
+3. 输出 `running` / `stopped` / `stale`
+4. stale 时自动清理状态文件
+
+### stop 逻辑
+
+1. 读取 pid
+2. 发送 `SIGTERM`
+3. 等待退出（超时兜底）
+4. 超时后 `SIGKILL`
+5. 清理状态文件
+
+## 验证步骤
+
+- [ ] `claude daemon start` 正常启动并写入状态文件
+- [ ] 新开终端执行 `claude daemon status`，显示 `running`
+- [ ] 执行 `claude daemon stop`，daemon 正常退出
+- [ ] 再次执行 `claude daemon status`，返回 `stopped` 或 `stale cleaned`
+- [ ] Windows 下 stop 超时兜底正常工作
+
+## 风险
+
+- Windows 信号模型和 Unix 不同，`stop` 需要超时兜底
+- 当前设计默认单 supervisor，不处理多实例并发
+
+## 依赖
+
+无外部依赖，可独立实施。

docs/task/task-002-bg-sessions-ps-logs-kill.md

@@ -0,0 +1,80 @@
+# Task 002: BG_SESSIONS — ps / logs / kill
+
+> 来源: [stub-recovery-design-1-4.md](../features/stub-recovery-design-1-4.md) 第 2 项
+> 优先级: P1
+> 工作量: 中等
+> 状态: DONE
+> 阶段: Phase 2A (MVP)
+
+## 目标
+
+把 `ps` / `logs` / `kill` 做成真正有用的 session 管理命令。不在第一阶段补完 `attach` / `--bg`。
+
+## 背景
+
+- fast-path 已接好 (`src/entrypoints/cli.tsx:218`)
+- session registry 已有真实实现 (`src/utils/concurrentSessions.ts`)
+- `exit` 在 bg session 内已会 `tmux detach-client` (`src/commands/exit/exit.tsx:20`)
+- CLI handler 仍全空 (`src/cli/bg.ts`)
+- task summary 仍然是 stub (`src/utils/taskSummary.ts`)
+
+## 实现方案
+
+### 修改文件
+
+| 文件 | 改动 |
+|------|------|
+| `src/cli/bg.ts` | 实现 `ps` / `logs` / `kill` handler |
+| `src/utils/concurrentSessions.ts` | 扩展以便后续 attach/--bg 使用 |
+| `src/utils/taskSummary.ts` | 补充基础实现 |
+
+### 复用模块
+
+- `src/utils/sessionStorage.ts` — session 存储
+- `src/utils/udsClient.ts` — UDS 通信
+
+### ps 命令
+
+- 从 registry 读取 live sessions
+- 展示: pid, kind, sessionId, cwd, name, startedAt, bridgeSessionId
+- 如果有 activity/status，一并展示
+
+### logs 命令
+
+- 支持按 `sessionId` / `pid` / `name` 查找
+- 优先复用本地 transcript/log 读取能力
+- 如果 registry 里存在 `logPath`，支持 tail 文件
+
+### kill 命令
+
+- 解析目标 session
+- 发退出信号
+- 清理 stale registry
+
+## 验证步骤
+
+- [ ] `ps` 能列出当前 live sessions
+- [ ] `logs <sessionId|pid|name>` 能输出对应日志
+- [ ] `kill <sessionId|pid|name>` 能结束目标 session 并清理 registry
+- [ ] 无 live session 时各命令有明确提示
+
+## Phase 2B (后续)
+
+- [ ] 实现 `attach`
+- [ ] 实现 `--bg`
+- [ ] 实现 `taskSummary` 的中途状态更新
+
+### 为什么拆分
+
+- 现有 registry 记录了 `pid / sessionId / name / logPath`
+- 但没有可靠的 tmux attach target
+- `attach` 和 `--bg` 需要补启动/附着元数据设计，不是简单补 handler
+
+## 风险
+
+- `attach` / `--bg` 第二阶段需要 tmux 元数据设计
+- Windows 下 tmux 路径需要明确降级策略
+
+## 依赖
+
+- Task 001 (daemon 状态管理可复用模式，但非硬性依赖)

docs/task/task-003-templates-job-mvp.md

@@ -0,0 +1,87 @@
+# Task 003: TEMPLATES — job 文件系统 MVP
+
+> 来源: [stub-recovery-design-1-4.md](../features/stub-recovery-design-1-4.md) 第 3 项
+> 优先级: P2
+> 工作量: 中等
+> 状态: DONE
+> 阶段: MVP
+
+## 目标
+
+把 `new` / `list` / `reply` 做成可用的模板任务系统。第一阶段不碰复杂的自动分类与自动执行。
+
+## 背景
+
+- 命令入口只有 fast-path (`src/entrypoints/cli.tsx:272`)
+- handler 是空的 (`src/cli/handlers/templateJobs.ts`)
+- `markdownConfigLoader` 已把 `templates` 纳入配置目录 (`src/utils/markdownConfigLoader.ts:35`)
+- `query/stopHooks` 已预留 job classifier 链路 (`src/query/stopHooks.ts:103`)
+- `jobs/classifier.ts` 仍是 stub (`src/jobs/classifier.ts`)
+
+## 实现方案
+
+### 新增文件
+
+| 文件 | 说明 |
+|------|------|
+| `src/jobs/state.ts` | job 状态管理 |
+| `src/jobs/templates.ts` | 模板解析与列表 |
+
+### 修改文件
+
+| 文件 | 改动 |
+|------|------|
+| `src/cli/handlers/templateJobs.ts` | 实现 `new` / `list` / `reply` handler |
+
+### 模板来源
+
+`.claude/templates/*.md`
+
+### 模板格式
+
+复用现有 markdown + frontmatter 解析，不另外设计 DSL。
+
+### list 命令
+
+- 列出所有模板
+- 显示: 模板名, description, 路径
+
+### new 命令
+
+- 解析模板
+- 在 `~/.claude/jobs/<job-id>/` 下创建 job 目录
+- 写入 `template.md`, `input.txt`, `state.json`
+- 返回 job id 与目录路径
+
+### reply 命令
+
+- 将回复写入 `replies.jsonl` 或 `input.txt`
+- 更新 `state.json`
+
+## 验证步骤
+
+- [ ] `list` 能列出 `.claude/templates` 下的所有模板
+- [ ] `new <template> [args...]` 能创建 job 目录和状态文件
+- [ ] `reply <job-id> <text>` 能更新 job 内容和状态
+- [ ] frontmatter schema 最小字段集已定义
+
+## Phase 2 (后续)
+
+- [ ] 恢复 `src/jobs/classifier.ts`
+- [ ] 让带 `CLAUDE_JOB_DIR` 的 job session 在 turn 完成后自动更新 `state.json`
+- [ ] 再决定是否补自动 job runner
+
+### 为什么拆分
+
+- 当前是 "template job commands"，不是单纯模板列表
+- 自动 job 运行链路没有足够现成实现
+- 先做文件系统 job lifecycle 更稳
+
+## 风险
+
+- frontmatter schema 需要先定义最小字段集
+- 一旦扩展到"自动运行 job"，范围会明显膨胀
+
+## 依赖
+
+无硬性依赖，可独立实施。

docs/task/task-004-assistant-session-attach.md

@@ -0,0 +1,103 @@
+# Task 004: assistant [sessionId] — 分阶段恢复
+
+> 来源: [stub-recovery-design-1-4.md](../features/stub-recovery-design-1-4.md) 第 4 项
+> 优先级: P3
+> 工作量: Phase 4A 中等，4A-4D 全做完很大
+> 状态: Phase 4A DONE, 4B-4D TODO
+
+## 目标
+
+不一次性恢复整个 KAIROS 助手系统。先做"明确 sessionId 的 viewer attach 可用"，再逐步补 discovery / chooser / install。
+
+## 背景
+
+- attach 主流程已存在 (`src/main.tsx:4708`)
+- 远端 viewer 所需基础模块已存在:
+  - `src/remote/RemoteSessionManager.ts`
+  - `src/hooks/useAssistantHistory.ts`
+  - `src/assistant/sessionHistory.ts`
+- 真正 stub 的主要是:
+  - `src/assistant/sessionDiscovery.ts`
+  - `src/assistant/AssistantSessionChooser.tsx`
+  - `src/commands/assistant/assistant.tsx:7`
+  - `src/assistant/index.ts`
+
+## 分阶段实现
+
+### Phase 4A: MVP — 显式 sessionId attach
+
+**修改文件:**
+
+| 文件 | 改动 |
+|------|------|
+| `src/main.tsx` | 确保 attach 分支可用 |
+| `src/commands/assistant/index.ts` | 实现显式 sessionId 参数入口 |
+
+**行为:**
+- `claude assistant <sessionId>` — 进入 remote viewer
+- `claude assistant` (无参数) — 返回明确提示: 当前版本需要显式 sessionId，discovery 尚未启用
+
+**验证:**
+- [ ] `claude assistant <sessionId>` 能进入 remote viewer
+- [ ] 历史懒加载工作正常
+- [ ] 无参数模式给出明确提示
+
+### Phase 4B: session discovery
+
+**修改文件:**
+
+| 文件 | 改动 |
+|------|------|
+| `src/assistant/sessionDiscovery.ts` | 恢复 `discoverAssistantSessions()` |
+
+**行为:**
+- 数据来源优先复用现有 sessions / bridge / teleport API，不新增协议
+- `claude assistant` 无参数时能拿到候选 session 列表
+
+**验证:**
+- [ ] 无参数调用能列出可用 sessions
+- [ ] 数据来源复用现有通道
+
+### Phase 4C: session chooser
+
+**修改文件:**
+
+| 文件 | 改动 |
+|------|------|
+| `src/assistant/AssistantSessionChooser.ts` | 恢复交互式选择器 |
+
+**行为:**
+- 多 session 时可交互选择
+
+**验证:**
+- [ ] 多个 session 时弹出选择器
+- [ ] 选择后正确 attach
+
+### Phase 4D: install wizard
+
+**修改文件:**
+
+| 文件 | 改动 |
+|------|------|
+| `src/commands/assistant/assistant.ts` | 恢复 install wizard 辅助函数 |
+
+**行为:**
+- 没有 session 时如何引导用户
+
+**验证:**
+- [ ] 无可用 session 时引导用户创建/连接
+
+## 为什么拆分
+
+- attach 渲染层与远端消息通道大部分已在
+- 真正缺的是"如何发现目标 session"和"如何交互选择"
+- 如果把 `src/assistant/index.ts` 的整套 KAIROS 正常模式也一起拉进来，范围会失控
+
+## 风险
+
+- 这是四项里范围最大的
+- 一旦把 KAIROS 正常模式整体拉入，会从"viewer attach"膨胀成"完整 assistant mode 恢复"
+
+## 依赖
+
+- Task 002 的 session registry 模式可复用

docs/task/task-013-bg-engine-abstraction.md

@@ -0,0 +1,196 @@
+# Task 013: BgEngine 跨平台后台引擎抽象
+
+> 设计文档: [daemon-restructure-design.md](../features/daemon-restructure-design.md) § 四
+> 依赖: 无
+> 分支: `feat/integrate-5-branches`
+
+## 目标
+
+将 `src/cli/bg.ts` 中硬编码的 tmux 逻辑提取为引擎抽象层，实现 TmuxEngine + DetachedEngine，使后台会话功能在 Windows / macOS / Linux 上都能工作。
+
+## 背景
+
+当前 `bg.ts` 中 `handleBgFlag()` 和 `attachHandler()` 直接调用 tmux 命令。Windows 上 `--bg` 直接报错退出。需要一个引擎抽象层，根据平台和可用工具自动选择最佳方案。
+
+## 文件清单
+
+### 新增
+
+| 文件 | 说明 |
+|------|------|
+| `src/cli/bg/engine.ts` | BgEngine 接口 + BgStartOptions/BgStartResult 类型 |
+| `src/cli/bg/engines/tmux.ts` | TmuxEngine: 从 `bg.ts` 提取 tmux 相关逻辑 |
+| `src/cli/bg/engines/detached.ts` | DetachedEngine: spawn({ detached }) + logFile 重定向 |
+| `src/cli/bg/engines/index.ts` | selectEngine() 自动选择 + re-export |
+| `src/cli/bg/tail.ts` | 跨平台日志 tail: fs.watch + 轮询 fallback |
+
+### 修改
+
+| 文件 | 变更 |
+|------|------|
+| `src/cli/bg.ts` | `handleBgFlag()` 改为调用 `selectEngine().start()`；`attachHandler()` 改为调用 `engine.attach()` |
+
+## 实现方案
+
+### 1. BgEngine 接口 (`src/cli/bg/engine.ts`)
+
+```typescript
+export interface BgEngine {
+  readonly name: string
+  available(): Promise<boolean>
+  start(opts: BgStartOptions): Promise<BgStartResult>
+  attach(session: SessionEntry): Promise<void>
+}
+
+export interface BgStartOptions {
+  sessionName: string
+  args: string[]         // CLI args (去除 --bg)
+  env: Record<string, string | undefined>
+  logPath: string
+  cwd: string
+}
+
+export interface BgStartResult {
+  pid: number
+  sessionName: string
+  logPath: string
+  engineUsed: 'tmux' | 'detached'
+}
+```
+
+### 2. TmuxEngine (`src/cli/bg/engines/tmux.ts`)
+
+从 `bg.ts:handleBgFlag()` 和 `bg.ts:attachHandler()` 提取:
+- `available()`: `execFileNoThrow('tmux', ['-V'])` 返回 code === 0
+- `start()`: `tmux new-session -d -s <name> <cmd>`
+- `attach()`: `tmux attach-session -t <session.tmuxSessionName>`
+
+### 3. DetachedEngine (`src/cli/bg/engines/detached.ts`)
+
+```typescript
+export class DetachedEngine implements BgEngine {
+  readonly name = 'detached'
+
+  async available(): Promise<boolean> {
+    return true  // 总是可用
+  }
+
+  async start(opts: BgStartOptions): Promise<BgStartResult> {
+    const logFd = openSync(opts.logPath, 'a')
+    const child = spawn(process.execPath, [process.argv[1]!, ...opts.args], {
+      detached: true,
+      stdio: ['ignore', logFd, logFd],
+      env: opts.env,
+      cwd: opts.cwd,
+    })
+    child.unref()
+    closeSync(logFd)
+
+    return {
+      pid: child.pid!,
+      sessionName: opts.sessionName,
+      logPath: opts.logPath,
+      engineUsed: 'detached',
+    }
+  }
+
+  async attach(session: SessionEntry): Promise<void> {
+    // 委托给 tail.ts
+    await tailLog(session.logPath!)
+  }
+}
+```
+
+### 4. 日志 Tail (`src/cli/bg/tail.ts`)
+
+```typescript
+/**
+ * 跨平台实时日志输出。Ctrl+C 退出，不杀后台进程。
+ *
+ * 策略:
+ * 1. 读取已有内容输出
+ * 2. fs.watch() 监听文件变化 (主方案)
+ * 3. 如果 fs.watch 不可靠 (某些 Windows 网络驱动器)，fallback 到 500ms 轮询
+ */
+export async function tailLog(logPath: string): Promise<void>
+```
+
+### 5. 引擎选择 (`src/cli/bg/engines/index.ts`)
+
+```typescript
+export async function selectEngine(): Promise<BgEngine> {
+  if (process.platform === 'win32') {
+    return new DetachedEngine()
+  }
+  const tmux = new TmuxEngine()
+  if (await tmux.available()) {
+    return tmux
+  }
+  return new DetachedEngine()
+}
+```
+
+### 6. bg.ts 重构
+
+`handleBgFlag()` 改名为 `handleBgStart()`，内部逻辑:
+```typescript
+export async function handleBgStart(args: string[]): Promise<void> {
+  const engine = await selectEngine()
+  const sessionName = `claude-bg-${randomUUID().slice(0, 8)}`
+  const logPath = join(getClaudeConfigHomeDir(), 'sessions', 'logs', `${sessionName}.log`)
+
+  const result = await engine.start({
+    sessionName,
+    args: filteredArgs,
+    env: { ...process.env, CLAUDE_CODE_SESSION_KIND: 'bg', ... },
+    logPath,
+    cwd: process.cwd(),
+  })
+
+  console.log(`Background session started: ${result.sessionName}`)
+  console.log(`  Engine: ${result.engineUsed}`)
+  console.log(`  Log: ${result.logPath}`)
+  console.log(`  Use \`claude daemon attach ${result.sessionName}\` to reconnect.`)
+}
+```
+
+`attachHandler()` 根据 `session.engine` 字段选择引擎:
+```typescript
+export async function attachHandler(target: string | undefined): Promise<void> {
+  // ... 找到 session
+  if (session.engine === 'tmux' && session.tmuxSessionName) {
+    const tmux = new TmuxEngine()
+    await tmux.attach(session)
+  } else {
+    const detached = new DetachedEngine()
+    await detached.attach(session)
+  }
+}
+```
+
+## SessionEntry 扩展
+
+`sessions/<PID>.json` 新增 `engine` 字段:
+
+```json
+{
+  "pid": 12345,
+  "engine": "detached",
+  "logPath": "~/.claude/sessions/logs/claude-bg-a1b2c3d4.log",
+  "sessionId": "...",
+  "cwd": "..."
+}
+```
+
+兼容旧格式: 如果 `engine` 字段缺失，检查 `tmuxSessionName` 存在则为 `tmux`，否则为 `detached`。
+
+## 验证清单
+
+- [ ] Windows: `claude daemon bg` 启动后台会话，无 tmux 依赖
+- [ ] Windows: `claude daemon attach <name>` 以 tail 模式附着，Ctrl+C 退出不杀进程
+- [ ] macOS/Linux (有 tmux): 行为与当前一致
+- [ ] macOS/Linux (无 tmux): 自动 fallback 到 detached 引擎
+- [ ] `claude daemon status` 正确显示 engine 类型
+- [ ] 旧格式 session JSON (无 engine 字段) 兼容
+- [ ] tsc --noEmit 零错误
+- [ ] bun test 通过

docs/task/task-014-daemon-command-hierarchy.md

@@ -0,0 +1,275 @@
+# Task 014: /daemon 命令层级化
+
+> 设计文档: [daemon-restructure-design.md](../features/daemon-restructure-design.md) § 三.1
+> 依赖: Task 013 (BgEngine 抽象)
+> 分支: `feat/integrate-5-branches`
+
+## 目标
+
+将散落的 `daemon start/stop/status` + `ps/logs/attach/kill` + `--bg` 统一收归 `/daemon` 命名空间，实现 CLI + REPL 双注册。
+
+## 背景
+
+当前这些命令注册在两个互不关联的位置:
+- `cli.tsx:203-212`: `daemon [start|status|stop]` → `daemon/main.ts`
+- `cli.tsx:217-246`: `ps|logs|attach|kill|--bg` → `cli/bg.ts`
+
+需要合并为统一的 `claude daemon <subcommand>` 入口，并新增 REPL `/daemon` 斜杠命令。
+
+## 文件清单
+
+### 新增
+
+| 文件 | 说明 |
+|------|------|
+| `src/commands/daemon/index.ts` | `/daemon` REPL 斜杠命令注册 (type: local-jsx) |
+| `src/commands/daemon/daemon.tsx` | `/daemon` 子命令路由 + status UI 组件 |
+
+### 修改
+
+| 文件 | 变更 |
+|------|------|
+| `src/entrypoints/cli.tsx` | 统一 daemon 快速路径: `daemon <sub>` 路由到对应 handler。旧命令 `ps/logs/attach/kill` 保留但输出 deprecation 警告后代理 |
+| `src/commands.ts` | 注册 `/daemon` 斜杠命令 (feature-gated: DAEMON \|\| BG_SESSIONS) |
+| `src/daemon/main.ts` | `daemonMain()` 扩展: 支持 `bg/attach/logs/kill/ps` 子命令 (委托给 bg.ts handlers) |
+
+## 实现方案
+
+### 1. CLI 快速路径统一 (`cli.tsx`)
+
+**改前** (两段独立路由):
+```typescript
+// 段 1: daemon
+if (feature('DAEMON') && args[0] === 'daemon') {
+  await daemonMain(args.slice(1))
+}
+// 段 2: bg sessions
+if (feature('BG_SESSIONS') && ['ps','logs','attach','kill'].includes(args[0])) {
+  // ...switch/case
+}
+```
+
+**改后** (统一入口):
+```typescript
+// 统一 daemon 入口 — 合并 daemon supervisor + bg sessions
+if (
+  (feature('DAEMON') || feature('BG_SESSIONS')) &&
+  args[0] === 'daemon'
+) {
+  profileCheckpoint('cli_daemon_path')
+  const { enableConfigs } = await import('../utils/config.js')
+  enableConfigs()
+  const { initSinks } = await import('../utils/sinks.js')
+  initSinks()
+  const { daemonMain } = await import('../daemon/main.js')
+  await daemonMain(args.slice(1))
+  return
+}
+
+// --bg 快捷方式 → daemon bg
+if (
+  feature('BG_SESSIONS') &&
+  (args.includes('--bg') || args.includes('--background'))
+) {
+  profileCheckpoint('cli_daemon_path')
+  const { enableConfigs } = await import('../utils/config.js')
+  enableConfigs()
+  const bg = await import('../cli/bg.js')
+  await bg.handleBgStart(args.filter(a => a !== '--bg' && a !== '--background'))
+  return
+}
+
+// 向后兼容: ps/logs/attach/kill → daemon <sub> (deprecated)
+if (
+  feature('BG_SESSIONS') &&
+  ['ps', 'logs', 'attach', 'kill'].includes(args[0] ?? '')
+) {
+  const mapped = args[0] === 'ps' ? 'status' : args[0]
+  console.error(`[deprecated] Use: claude daemon ${mapped} ${args.slice(1).join(' ')}`.trim())
+  const { enableConfigs } = await import('../utils/config.js')
+  enableConfigs()
+  const { daemonMain } = await import('../daemon/main.js')
+  await daemonMain([args[0]!, ...args.slice(1)])
+  return
+}
+```
+
+### 2. daemonMain 扩展 (`daemon/main.ts`)
+
+```typescript
+export async function daemonMain(args: string[]): Promise<void> {
+  const subcommand = args[0] || 'status'
+
+  switch (subcommand) {
+    // --- Supervisor 管理 ---
+    case 'start':
+      await runSupervisor(args.slice(1))
+      break
+    case 'stop':
+      await handleDaemonStop()
+      break
+
+    // --- 会话管理 (委托给 bg.ts) ---
+    case 'status':
+    case 'ps':
+      await showUnifiedStatus()  // 新: daemon 状态 + 会话列表
+      break
+    case 'bg':
+      const bg = await import('../cli/bg.js')
+      await bg.handleBgStart(args.slice(1))
+      break
+    case 'attach':
+      const bg2 = await import('../cli/bg.js')
+      await bg2.attachHandler(args[1])
+      break
+    case 'logs':
+      const bg3 = await import('../cli/bg.js')
+      await bg3.logsHandler(args[1])
+      break
+    case 'kill':
+      const bg4 = await import('../cli/bg.js')
+      await bg4.killHandler(args[1])
+      break
+
+    case '--help': case '-h': case 'help':
+      printHelp()
+      break
+    default:
+      console.error(`Unknown daemon subcommand: ${subcommand}`)
+      printHelp()
+      process.exitCode = 1
+  }
+}
+```
+
+### 3. 统一状态面板 (`showUnifiedStatus`)
+
+```typescript
+async function showUnifiedStatus(): Promise<void> {
+  // 1. Daemon supervisor 状态
+  const daemonResult = queryDaemonStatus()
+  console.log('=== Daemon Supervisor ===')
+  switch (daemonResult.status) {
+    case 'running':
+      console.log(`  Status: running (PID: ${daemonResult.state!.pid})`)
+      console.log(`  Workers: ${daemonResult.state!.workerKinds.join(', ')}`)
+      break
+    case 'stopped':
+      console.log('  Status: stopped')
+      break
+    case 'stale':
+      console.log('  Status: stale (cleaned up)')
+      break
+  }
+
+  // 2. 后台会话列表
+  console.log('\n=== Background Sessions ===')
+  const bg = await import('../cli/bg.js')
+  await bg.psHandler([])
+}
+```
+
+### 4. REPL 斜杠命令注册
+
+**`src/commands/daemon/index.ts`**:
+```typescript
+import type { Command } from '../../commands.js'
+import { feature } from 'bun:bundle'
+
+const daemon = {
+  type: 'local-jsx',
+  name: 'daemon',
+  description: 'Manage background sessions and daemon',
+  argumentHint: '[status|start|stop|bg|attach|logs|kill]',
+  isEnabled: () => {
+    if (feature('DAEMON')) return true
+    if (feature('BG_SESSIONS')) return true
+    return false
+  },
+  load: () => import('./daemon.js'),
+} satisfies Command
+
+export default daemon
+```
+
+**`src/commands/daemon/daemon.tsx`**:
+```typescript
+export async function call(
+  onDone: LocalJSXCommandOnDone,
+  context: LocalJSXCommandContext,
+  args: string,
+): Promise<React.ReactNode> {
+  const parts = args.trim().split(/\s+/)
+  const sub = parts[0] || 'status'
+
+  switch (sub) {
+    case 'status':
+    case 'ps':
+      // 调用 showUnifiedStatus，捕获输出
+      // 返回文本结果
+      break
+    case 'bg':
+      // REPL 中启动后台会话
+      break
+    case 'start':
+    case 'stop':
+    case 'attach':
+    case 'logs':
+    case 'kill':
+      // 委托给对应 handler
+      break
+    default:
+      onDone(`Unknown: ${sub}. Use: status|start|stop|bg|attach|logs|kill`)
+      return null
+  }
+}
+```
+
+**`src/commands.ts`** 添加:
+```typescript
+// 条件导入
+const daemonCmd =
+  feature('DAEMON') || feature('BG_SESSIONS')
+    ? require('./commands/daemon/index.js').default
+    : null
+
+// COMMANDS 数组中添加
+...(daemonCmd ? [daemonCmd] : []),
+```
+
+### 5. 更新 help 文本 (`daemon/main.ts`)
+
+```
+Claude Code Daemon — background process management
+
+USAGE
+  claude daemon [subcommand]
+
+SUBCOMMANDS
+  status      Show daemon and session status (default)
+  start       Start the daemon supervisor
+  stop        Stop the daemon
+  bg          Start a background session
+  attach      Attach to a background session
+  logs        Show session logs
+  kill        Kill a session
+  help        Show this help
+
+REPL
+  /daemon [subcommand]    Same commands available in interactive mode
+```
+
+## 验证清单
+
+- [ ] `claude daemon` (无参数) 显示统一状态面板
+- [ ] `claude daemon status` 显示 supervisor + 会话列表
+- [ ] `claude daemon start/stop` 与当前行为一致
+- [ ] `claude daemon bg` 启动后台会话 (调用 BgEngine)
+- [ ] `claude daemon attach/logs/kill <target>` 功能正常
+- [ ] `claude ps` 输出 deprecation 警告 + 正常工作
+- [ ] `claude logs/attach/kill` 同上
+- [ ] `claude --bg` 快捷方式正常
+- [ ] REPL 中 `/daemon` 可用，tab 补全显示
+- [ ] REPL 中 `/daemon status` 显示状态信息
+- [ ] tsc --noEmit 零错误
+- [ ] bun test 通过

docs/task/task-015-job-command-hierarchy.md

@@ -0,0 +1,177 @@
+# Task 015: /job 命令层级化
+
+> 设计文档: [daemon-restructure-design.md](../features/daemon-restructure-design.md) § 三.2
+> 依赖: 无 (可与 Task 013 并行)
+> 分支: `feat/integrate-5-branches`
+
+## 目标
+
+将 `claude new/list/reply` 收归 `/job` 命名空间，实现 CLI + REPL 双注册。
+
+## 背景
+
+当前 `new`, `list`, `reply` 是顶级 CLI 命令 (`cli.tsx:250-261`)，容易与其他命令冲突（特别是 `list` 这种通用词）。需要收归 `claude job <subcommand>` 并新增 REPL `/job` 入口。
+
+## 文件清单
+
+### 新增
+
+| 文件 | 说明 |
+|------|------|
+| `src/commands/job/index.ts` | `/job` REPL 斜杠命令注册 |
+| `src/commands/job/job.tsx` | `/job` 子命令路由 |
+
+### 修改
+
+| 文件 | 变更 |
+|------|------|
+| `src/entrypoints/cli.tsx` | 新增 `job` 快速路径 + 旧 `new/list/reply` deprecation 代理 |
+| `src/commands.ts` | 注册 `/job` 斜杠命令 |
+
+### 不动
+
+| 文件 | 说明 |
+|------|------|
+| `src/cli/handlers/templateJobs.ts` | 内部 handler 不变，只是被调用方式变了 |
+| `src/jobs/state.ts` | job 状态管理不变 |
+| `src/jobs/templates.ts` | 模板发现不变 |
+| `src/jobs/classifier.ts` | 任务分类器不变 |
+
+## 实现方案
+
+### 1. CLI 快速路径 (`cli.tsx`)
+
+**改后**:
+```typescript
+// 新: claude job <subcommand>
+if (
+  feature('TEMPLATES') &&
+  args[0] === 'job'
+) {
+  profileCheckpoint('cli_templates_path')
+  const { templatesMain } = await import('../cli/handlers/templateJobs.js')
+  await templatesMain(args.slice(1))
+  process.exit(0)
+}
+
+// 向后兼容 (deprecated)
+if (
+  feature('TEMPLATES') &&
+  (args[0] === 'new' || args[0] === 'list' || args[0] === 'reply')
+) {
+  console.error(`[deprecated] Use: claude job ${args[0]} ${args.slice(1).join(' ')}`.trim())
+  profileCheckpoint('cli_templates_path')
+  const { templatesMain } = await import('../cli/handlers/templateJobs.js')
+  await templatesMain(args)
+  process.exit(0)
+}
+```
+
+### 2. templateJobs.ts 新增 status 子命令
+
+在现有 `switch` 中增加:
+```typescript
+case 'status':
+  handleStatus(args.slice(1))
+  break
+```
+
+```typescript
+function handleStatus(args: string[]): void {
+  const jobId = args[0]
+  if (!jobId) {
+    console.error('Usage: claude job status <job-id>')
+    process.exitCode = 1
+    return
+  }
+  const state = readJobState(jobId)
+  if (!state) {
+    console.error(`Job not found: ${jobId}`)
+    process.exitCode = 1
+    return
+  }
+  console.log(`Job: ${state.jobId}`)
+  console.log(`  Template: ${state.templateName}`)
+  console.log(`  Status: ${state.status}`)
+  console.log(`  Created: ${state.createdAt}`)
+  console.log(`  Updated: ${state.updatedAt}`)
+}
+```
+
+### 3. REPL 斜杠命令
+
+**`src/commands/job/index.ts`**:
+```typescript
+import type { Command } from '../../commands.js'
+import { feature } from 'bun:bundle'
+
+const job = {
+  type: 'local-jsx',
+  name: 'job',
+  description: 'Manage template jobs',
+  argumentHint: '[list|new|reply|status]',
+  isEnabled: () => {
+    if (feature('TEMPLATES')) return true
+    return false
+  },
+  load: () => import('./job.js'),
+} satisfies Command
+
+export default job
+```
+
+**`src/commands/job/job.tsx`**:
+```typescript
+export async function call(
+  onDone: LocalJSXCommandOnDone,
+  _context: LocalJSXCommandContext,
+  args: string,
+): Promise<React.ReactNode> {
+  const parts = args.trim().split(/\s+/)
+  const sub = parts[0] || 'list'
+
+  // 委托给 templatesMain
+  const { templatesMain } = await import('../../cli/handlers/templateJobs.js')
+
+  // 捕获 console.log 输出作为结果返回给 REPL
+  const lines: string[] = []
+  const origLog = console.log
+  const origError = console.error
+  console.log = (...a: unknown[]) => lines.push(a.join(' '))
+  console.error = (...a: unknown[]) => lines.push(a.join(' '))
+
+  try {
+    await templatesMain([sub, ...parts.slice(1)])
+  } finally {
+    console.log = origLog
+    console.error = origError
+  }
+
+  onDone(lines.join('\n') || 'Done.', { display: 'system' })
+  return null
+}
+```
+
+### 4. commands.ts 注册
+
+```typescript
+const jobCmd = feature('TEMPLATES')
+  ? require('./commands/job/index.js').default
+  : null
+
+// COMMANDS 数组:
+...(jobCmd ? [jobCmd] : []),
+```
+
+## 验证清单
+
+- [ ] `claude job list` 列出模板
+- [ ] `claude job new <template>` 创建任务
+- [ ] `claude job reply <id> <text>` 回复任务
+- [ ] `claude job status <id>` 显示任务状态
+- [ ] `claude job` (无参数) 等同于 `claude job list`
+- [ ] `claude new/list/reply` 输出 deprecation 警告 + 正常工作
+- [ ] REPL 中 `/job` 可用
+- [ ] REPL 中 `/job list` 显示模板列表
+- [ ] tsc --noEmit 零错误
+- [ ] bun test 通过

docs/task/task-016-backward-compat-tests.md

@@ -0,0 +1,123 @@
+# Task 016: 向后兼容 + 测试
+
+> 设计文档: [daemon-restructure-design.md](../features/daemon-restructure-design.md) § 五
+> 依赖: Task 014, Task 015
+> 分支: `feat/integrate-5-branches`
+
+## 目标
+
+确保旧命令向后兼容 (deprecation 警告 + 正常代理)，并为重构后的命令结构编写测试。
+
+## 文件清单
+
+### 新增
+
+| 文件 | 说明 |
+|------|------|
+| `src/daemon/__tests__/daemonMain.test.ts` | daemonMain 子命令路由测试 |
+| `src/cli/bg/__tests__/engine.test.ts` | BgEngine 选择逻辑测试 |
+| `src/cli/bg/__tests__/detached.test.ts` | DetachedEngine 启动/停止测试 |
+| `src/cli/bg/__tests__/tail.test.ts` | 日志 tail 功能测试 |
+
+### 修改
+
+| 文件 | 变更 |
+|------|------|
+| `src/entrypoints/cli.tsx` | 确认 deprecation 路径正确代理 |
+
+## 实现方案
+
+### 1. 向后兼容矩阵
+
+| 旧命令 | 新命令 | 处理方式 |
+|--------|--------|---------|
+| `claude ps` | `claude daemon status` | stderr 输出 `[deprecated] Use: claude daemon status`，然后执行 |
+| `claude logs <x>` | `claude daemon logs <x>` | 同上 |
+| `claude attach <x>` | `claude daemon attach <x>` | 同上 |
+| `claude kill <x>` | `claude daemon kill <x>` | 同上 |
+| `claude --bg` | `claude daemon bg` | 保留为快捷方式，**不** deprecate (太常用) |
+| `claude new <t>` | `claude job new <t>` | stderr deprecation + 执行 |
+| `claude list` | `claude job list` | stderr deprecation + 执行 |
+| `claude reply <id>` | `claude job reply <id>` | stderr deprecation + 执行 |
+
+**关键**: deprecation 输出到 stderr 而非 stdout，不影响脚本管道。
+
+### 2. 测试计划
+
+#### 2.1 daemonMain 路由测试
+
+```typescript
+describe('daemonMain', () => {
+  test('无参数默认 status', async () => { ... })
+  test('start 调用 runSupervisor', async () => { ... })
+  test('stop 调用 handleDaemonStop', async () => { ... })
+  test('bg 委托给 bg.handleBgStart', async () => { ... })
+  test('attach 委托给 bg.attachHandler', async () => { ... })
+  test('logs 委托给 bg.logsHandler', async () => { ... })
+  test('kill 委托给 bg.killHandler', async () => { ... })
+  test('未知子命令设置 exitCode=1', async () => { ... })
+})
+```
+
+#### 2.2 引擎选择测试
+
+```typescript
+describe('selectEngine', () => {
+  test('win32 返回 DetachedEngine', async () => { ... })
+  test('darwin + tmux 可用返回 TmuxEngine', async () => { ... })
+  test('darwin + tmux 不可用返回 DetachedEngine', async () => { ... })
+  test('linux + tmux 可用返回 TmuxEngine', async () => { ... })
+})
+```
+
+#### 2.3 DetachedEngine 测试
+
+```typescript
+describe('DetachedEngine', () => {
+  test('available 始终返回 true', async () => { ... })
+  test('start 创建 detached 子进程并写入日志', async () => { ... })
+  test('start 返回的 PID 文件存在', async () => { ... })
+})
+```
+
+#### 2.4 Tail 测试
+
+```typescript
+describe('tailLog', () => {
+  test('输出已有日志内容', async () => { ... })
+  test('追加内容时实时输出', async () => { ... })
+  test('SIGINT 退出 tail', async () => { ... })
+})
+```
+
+### 3. 集成验证脚本
+
+可选: 在 `scripts/` 下添加一个手动验证脚本:
+
+```bash
+#!/bin/bash
+# scripts/verify-daemon-restructure.sh
+echo "=== 1. claude daemon status ==="
+bun run dev -- daemon status
+
+echo "=== 2. claude daemon bg (should start) ==="
+bun run dev -- daemon bg --help
+
+echo "=== 3. claude ps (deprecated) ==="
+bun run dev -- ps 2>&1 | head -1
+
+echo "=== 4. claude job list ==="
+bun run dev -- job list
+
+echo "=== 5. claude list (deprecated) ==="
+bun run dev -- list 2>&1 | head -1
+```
+
+## 验证清单
+
+- [ ] 旧命令全部正常工作 (仅多一行 stderr 警告)
+- [ ] `--bg` 保持无警告
+- [ ] 所有新增测试通过
+- [ ] 现有 2695 个测试无回归
+- [ ] tsc --noEmit 零错误
+- [ ] 手动在 Windows + macOS/Linux 上验证关键路径

docs/test-plans/01-tool-system.md

@@ -1,147 +0,0 @@
-# Tool 系统测试计划
-
-## 概述
-
-Tool 系统是 Claude Code 的核心，负责工具的定义、注册、发现和过滤。本计划覆盖 `src/Tool.ts` 中的工具接口与工具函数、`src/tools.ts` 中的注册/过滤逻辑，以及各工具目录下可独立测试的纯函数。
-
-## 被测文件
-
-| 文件 | 关键导出 |
-|------|----------|
-| `src/Tool.ts` | `buildTool`, `toolMatchesName`, `findToolByName`, `getEmptyToolPermissionContext`, `filterToolProgressMessages` |
-| `src/tools.ts` | `parseToolPreset`, `filterToolsByDenyRules`, `getAllBaseTools`, `getTools`, `assembleToolPool` |
-| `src/tools/shared/gitOperationTracking.ts` | `parseGitCommitId`, `detectGitOperation` |
-| `src/tools/shared/spawnMultiAgent.ts` | `resolveTeammateModel`, `generateUniqueTeammateName` |
-| `src/tools/GrepTool/GrepTool.ts` | `applyHeadLimit`, `formatLimitInfo`（内部辅助函数） |
-| `src/tools/FileEditTool/utils.ts` | 字符串匹配/补丁相关纯函数 |
-
----
-
-## 测试用例
-
-### src/Tool.ts
-
-#### describe('buildTool')
-
-- test('fills in default isEnabled as true') — 不传 isEnabled 时，构建的 tool.isEnabled() 应返回 true
-- test('fills in default isConcurrencySafe as false') — 默认值应为 false（fail-closed）
-- test('fills in default isReadOnly as false') — 默认假设有写操作
-- test('fills in default isDestructive as false') — 默认非破坏性
-- test('fills in default checkPermissions as allow') — 默认 checkPermissions 应返回 `{ behavior: 'allow', updatedInput }`
-- test('fills in default userFacingName from tool name') — userFacingName 默认应返回 tool.name
-- test('preserves explicitly provided methods') — 传入自定义 isEnabled 等方法时应覆盖默认值
-- test('preserves all non-defaultable properties') — name, inputSchema, call, description 等属性原样保留
-
-#### describe('toolMatchesName')
-
-- test('returns true for exact name match') — `{ name: 'Bash' }` 匹配 'Bash'
-- test('returns false for non-matching name') — `{ name: 'Bash' }` 不匹配 'Read'
-- test('returns true when name matches an alias') — `{ name: 'Bash', aliases: ['BashTool'] }` 匹配 'BashTool'
-- test('returns false when aliases is undefined') — `{ name: 'Bash' }` 不匹配 'BashTool'
-- test('returns false when aliases is empty') — `{ name: 'Bash', aliases: [] }` 不匹配 'BashTool'
-
-#### describe('findToolByName')
-
-- test('finds tool by primary name') — 从 tools 列表中按 name 找到工具
-- test('finds tool by alias') — 从 tools 列表中按 alias 找到工具
-- test('returns undefined when no match') — 找不到时返回 undefined
-- test('returns first match when duplicates exist') — 多个同名工具时返回第一个
-
-#### describe('getEmptyToolPermissionContext')
-
-- test('returns default permission mode') — mode 应为 'default'
-- test('returns empty maps and arrays') — additionalWorkingDirectories 为空 Map，rules 为空对象
-- test('returns isBypassPermissionsModeAvailable as false')
-
-#### describe('filterToolProgressMessages')
-
-- test('filters out hook_progress messages') — 移除 type 为 hook_progress 的消息
-- test('keeps tool progress messages') — 保留非 hook_progress 的消息
-- test('returns empty array for empty input')
-- test('handles messages without type field') — data 不含 type 时应保留
-
----
-
-### src/tools.ts
-
-#### describe('parseToolPreset')
-
-- test('returns "default" for "default" input') — 精确匹配
-- test('returns "default" for "Default" input') — 大小写不敏感
-- test('returns null for unknown preset') — 未知字符串返回 null
-- test('returns null for empty string')
-
-#### describe('filterToolsByDenyRules')
-
-- test('returns all tools when no deny rules') — 空 deny 规则不过滤任何工具
-- test('filters out tools matching blanket deny rule') — deny rule `{ toolName: 'Bash' }` 应移除 Bash
-- test('does not filter tools with content-specific deny rules') — deny rule `{ toolName: 'Bash', ruleContent: 'rm -rf' }` 不移除 Bash（只在运行时阻止特定命令）
-- test('filters MCP tools by server name prefix') — deny rule `mcp__server` 应移除该 server 下所有工具
-- test('preserves tools not matching any deny rule')
-
-#### describe('getAllBaseTools')
-
-- test('returns a non-empty array of tools') — 至少包含核心工具
-- test('each tool has required properties') — 每个工具应有 name, inputSchema, call 等属性
-- test('includes BashTool, FileReadTool, FileEditTool') — 核心工具始终存在
-- test('includes TestingPermissionTool when NODE_ENV is test') — 需设置 env
-
-#### describe('getTools')
-
-- test('returns filtered tools based on permission context') — 根据 deny rules 过滤
-- test('returns simple tools in CLAUDE_CODE_SIMPLE mode') — 仅返回 Bash/Read/Edit
-- test('filters disabled tools via isEnabled') — isEnabled 返回 false 的工具被排除
-
----
-
-### src/tools/shared/gitOperationTracking.ts
-
-#### describe('parseGitCommitId')
-
-- test('extracts commit hash from git commit output') — 从 `[main abc1234] message` 中提取 `abc1234`
-- test('returns null for non-commit output') — 无法解析时返回 null
-- test('handles various branch name formats') — `[feature/foo abc1234]` 等
-
-#### describe('detectGitOperation')
-
-- test('detects git commit operation') — 命令含 `git commit` 时识别为 commit
-- test('detects git push operation') — 命令含 `git push` 时识别
-- test('returns null for non-git commands') — 非 git 命令返回 null
-- test('detects git merge operation')
-- test('detects git rebase operation')
-
----
-
-### src/tools/shared/spawnMultiAgent.ts
-
-#### describe('resolveTeammateModel')
-
-- test('returns specified model when provided')
-- test('falls back to default model when not specified')
-
-#### describe('generateUniqueTeammateName')
-
-- test('generates a name when no existing names') — 无冲突时返回基础名
-- test('appends suffix when name conflicts') — 与已有名称冲突时添加后缀
-- test('handles multiple conflicts') — 多次冲突时递增后缀
-
----
-
-## Mock 需求
-
-| 依赖 | Mock 方式 | 说明 |
-|------|-----------|------|
-| `bun:bundle` (feature) | 已 polyfill 为 `() => false` | 不需额外 mock |
-| `process.env` | `bun:test` mock | 测试 `USER_TYPE`、`NODE_ENV`、`CLAUDE_CODE_SIMPLE` |
-| `getDenyRuleForTool` | mock module | `filterToolsByDenyRules` 测试中需控制返回值 |
-| `isToolSearchEnabledOptimistic` | mock module | `getAllBaseTools` 中条件加载 |
-
-## 集成测试场景
-
-放在 `tests/integration/tool-chain.test.ts`：
-
-### describe('Tool registration and discovery')
-
-- test('getAllBaseTools returns tools that can be found by findToolByName') — 注册 → 查找完整链路
-- test('filterToolsByDenyRules + getTools produces consistent results') — 过滤管线一致性
-- test('assembleToolPool deduplicates built-in and MCP tools') — 合并去重逻辑

docs/test-plans/02-utils-pure-functions.md

@@ -1,416 +0,0 @@
-# 工具函数（纯函数）测试计划
-
-## 概述
-
-覆盖 `src/utils/` 下所有可独立单元测试的纯函数。这些函数无外部依赖，输入输出确定性强，是测试金字塔的底层基石。
-
-## 被测文件
-
-| 文件 | 状态 | 关键导出 |
-|------|------|----------|
-| `src/utils/array.ts` | **已有测试** | intersperse, count, uniq |
-| `src/utils/set.ts` | **已有测试** | difference, intersects, every, union |
-| `src/utils/xml.ts` | 待测 | escapeXml, escapeXmlAttr |
-| `src/utils/hash.ts` | 待测 | djb2Hash, hashContent, hashPair |
-| `src/utils/stringUtils.ts` | 待测 | escapeRegExp, capitalize, plural, firstLineOf, countCharInString, normalizeFullWidthDigits, normalizeFullWidthSpace, safeJoinLines, truncateToLines, EndTruncatingAccumulator |
-| `src/utils/semver.ts` | 待测 | gt, gte, lt, lte, satisfies, order |
-| `src/utils/uuid.ts` | 待测 | validateUuid, createAgentId |
-| `src/utils/format.ts` | 待测 | formatFileSize, formatSecondsShort, formatDuration, formatNumber, formatTokens, formatRelativeTime, formatRelativeTimeAgo |
-| `src/utils/json.ts` | 待测 | safeParseJSON, safeParseJSONC, parseJSONL, addItemToJSONCArray |
-| `src/utils/truncate.ts` | 待测 | truncatePathMiddle, truncateToWidth, truncateStartToWidth, truncateToWidthNoEllipsis, truncate, wrapText |
-| `src/utils/diff.ts` | 待测 | adjustHunkLineNumbers, getPatchFromContents |
-| `src/utils/frontmatterParser.ts` | 待测 | parseFrontmatter, splitPathInFrontmatter, parsePositiveIntFromFrontmatter, parseBooleanFrontmatter, parseShellFrontmatter |
-| `src/utils/file.ts` | 待测（纯函数部分） | convertLeadingTabsToSpaces, addLineNumbers, stripLineNumberPrefix, pathsEqual, normalizePathForComparison |
-| `src/utils/glob.ts` | 待测（纯函数部分） | extractGlobBaseDirectory |
-| `src/utils/tokens.ts` | 待测 | getTokenCountFromUsage |
-| `src/utils/path.ts` | 待测（纯函数部分） | containsPathTraversal, normalizePathForConfigKey |
-
----
-
-## 测试用例
-
-### src/utils/xml.ts — 测试文件: `src/utils/__tests__/xml.test.ts`
-
-#### describe('escapeXml')
-
-- test('escapes ampersand') — `&` → `&`
-- test('escapes less-than') — `<` → `&lt;`
-- test('escapes greater-than') — `>` → `&gt;`
-- test('does not escape quotes') — `"` 和 `'` 保持原样
-- test('handles empty string') — `""` → `""`
-- test('handles string with no special chars') — `"hello"` 原样返回
-- test('escapes multiple special chars in one string') — `<a & b>` → `&lt;a &amp; b&gt;`
-
-#### describe('escapeXmlAttr')
-
-- test('escapes all xml chars plus quotes') — `"` → `&quot;`, `'` → `&apos;`
-- test('escapes double quotes') — `he said "hi"` 正确转义
-- test('escapes single quotes') — `it's` 正确转义
-
----
-
-### src/utils/hash.ts — 测试文件: `src/utils/__tests__/hash.test.ts`
-
-#### describe('djb2Hash')
-
-- test('returns consistent hash for same input') — 相同输入返回相同结果
-- test('returns different hashes for different inputs') — 不同输入大概率不同
-- test('returns a 32-bit integer') — 结果在 int32 范围内
-- test('handles empty string') — 空字符串有确定的哈希值
-- test('handles unicode strings') — 中文/emoji 等正确处理
-
-#### describe('hashContent')
-
-- test('returns consistent hash for same content') — 确定性
-- test('returns string result') — 返回值为字符串
-
-#### describe('hashPair')
-
-- test('returns consistent hash for same pair') — 确定性
-- test('order matters') — hashPair(a, b) ≠ hashPair(b, a)
-- test('handles empty strings')
-
----
-
-### src/utils/stringUtils.ts — 测试文件: `src/utils/__tests__/stringUtils.test.ts`
-
-#### describe('escapeRegExp')
-
-- test('escapes dots') — `.` → `\\.`
-- test('escapes asterisks') — `*` → `\\*`
-- test('escapes brackets') — `[` → `\\[`
-- test('escapes all special chars') — `.*+?^${}()|[]\` 全部转义
-- test('leaves normal chars unchanged') — `hello` 原样
-- test('escaped string works in RegExp') — `new RegExp(escapeRegExp('a.b'))` 精确匹配 `a.b`
-
-#### describe('capitalize')
-
-- test('uppercases first char') — `"foo"` → `"Foo"`
-- test('does NOT lowercase rest') — `"fooBar"` → `"FooBar"`（区别于 lodash capitalize）
-- test('handles single char') — `"a"` → `"A"`
-- test('handles empty string') — `""` → `""`
-- test('handles already capitalized') — `"Foo"` → `"Foo"`
-
-#### describe('plural')
-
-- test('returns singular for n=1') — `plural(1, 'file')` → `'file'`
-- test('returns plural for n=0') — `plural(0, 'file')` → `'files'`
-- test('returns plural for n>1') — `plural(3, 'file')` → `'files'`
-- test('uses custom plural form') — `plural(2, 'entry', 'entries')` → `'entries'`
-
-#### describe('firstLineOf')
-
-- test('returns first line of multi-line string') — `"a\nb\nc"` → `"a"`
-- test('returns full string when no newline') — `"hello"` → `"hello"`
-- test('handles empty string') — `""` → `""`
-- test('handles string starting with newline') — `"\nhello"` → `""`
-
-#### describe('countCharInString')
-
-- test('counts occurrences') — `countCharInString("aabac", "a")` → `3`
-- test('returns 0 when char not found') — `countCharInString("hello", "x")` → `0`
-- test('handles empty string') — `countCharInString("", "a")` → `0`
-- test('respects start position') — `countCharInString("aaba", "a", 2)` → `1`
-
-#### describe('normalizeFullWidthDigits')
-
-- test('converts full-width digits to half-width') — `"０１２３"` → `"0123"`
-- test('leaves half-width digits unchanged') — `"0123"` → `"0123"`
-- test('mixed content') — `"port ８０８０"` → `"port 8080"`
-
-#### describe('normalizeFullWidthSpace')
-
-- test('converts ideographic space to regular space') — `"\u3000"` → `" "`
-- test('converts multiple spaces') — `"a\u3000b\u3000c"` → `"a b c"`
-
-#### describe('safeJoinLines')
-
-- test('joins lines with default delimiter') — `["a","b"]` → `"a,b"`
-- test('truncates when exceeding maxSize') — 超限时截断并添加 `...[truncated]`
-- test('handles empty array') — `[]` → `""`
-- test('uses custom delimiter') — delimiter 为 `"\n"` 时按行连接
-
-#### describe('truncateToLines')
-
-- test('returns full text when within limit') — 行数不超限时原样返回
-- test('truncates and adds ellipsis') — 超限时截断并加 `…`
-- test('handles exact limit') — 刚好等于 maxLines 时不截断
-- test('handles single line') — 单行文本不截断
-
-#### describe('EndTruncatingAccumulator')
-
-- test('accumulates strings normally within limit')
-- test('truncates when exceeding maxSize')
-- test('reports truncated status correctly')
-- test('reports totalBytes including truncated content')
-- test('toString includes truncation marker')
-- test('clear resets all state')
-- test('append with Buffer works') — 接受 Buffer 类型
-
----
-
-### src/utils/semver.ts — 测试文件: `src/utils/__tests__/semver.test.ts`
-
-#### describe('gt / gte / lt / lte')
-
-- test('gt: 2.0.0 > 1.0.0') → true
-- test('gt: 1.0.0 > 1.0.0') → false
-- test('gte: 1.0.0 >= 1.0.0') → true
-- test('lt: 1.0.0 < 2.0.0') → true
-- test('lte: 1.0.0 <= 1.0.0') → true
-- test('handles pre-release versions') — `1.0.0-beta < 1.0.0`
-
-#### describe('satisfies')
-
-- test('version satisfies caret range') — `satisfies('1.2.3', '^1.0.0')` → true
-- test('version does not satisfy range') — `satisfies('2.0.0', '^1.0.0')` → false
-- test('exact match') — `satisfies('1.0.0', '1.0.0')` → true
-
-#### describe('order')
-
-- test('returns -1 for lesser') — `order('1.0.0', '2.0.0')` → -1
-- test('returns 0 for equal') — `order('1.0.0', '1.0.0')` → 0
-- test('returns 1 for greater') — `order('2.0.0', '1.0.0')` → 1
-
----
-
-### src/utils/uuid.ts — 测试文件: `src/utils/__tests__/uuid.test.ts`
-
-#### describe('validateUuid')
-
-- test('accepts valid v4 UUID') — `'550e8400-e29b-41d4-a716-446655440000'` → 返回 UUID
-- test('returns null for invalid format') — `'not-a-uuid'` → null
-- test('returns null for empty string') — `''` → null
-- test('returns null for null/undefined input')
-- test('accepts uppercase UUIDs') — 大写字母有效
-
-#### describe('createAgentId')
-
-- test('returns string starting with "a"') — 前缀为 `a`
-- test('has correct length') — 前缀 + 16 hex 字符
-- test('generates unique ids') — 连续两次调用结果不同
-
----
-
-### src/utils/format.ts — 测试文件: `src/utils/__tests__/format.test.ts`
-
-#### describe('formatFileSize')
-
-- test('formats bytes') — `500` → `"500 bytes"`
-- test('formats kilobytes') — `1536` → `"1.5KB"`
-- test('formats megabytes') — `1572864` → `"1.5MB"`
-- test('formats gigabytes') — `1610612736` → `"1.5GB"`
-- test('removes trailing .0') — `1024` → `"1KB"` (不是 `"1.0KB"`)
-
-#### describe('formatSecondsShort')
-
-- test('formats milliseconds to seconds') — `1234` → `"1.2s"`
-- test('formats zero') — `0` → `"0.0s"`
-
-#### describe('formatDuration')
-
-- test('formats seconds') — `5000` → `"5s"`
-- test('formats minutes and seconds') — `65000` → `"1m 5s"`
-- test('formats hours') — `3661000` → `"1h 1m 1s"`
-- test('formats days') — `90061000` → `"1d 1h 1m"`
-- test('returns "0s" for zero') — `0` → `"0s"`
-- test('hideTrailingZeros omits zero components') — `3600000` + `hideTrailingZeros` → `"1h"`
-- test('mostSignificantOnly returns largest unit') — `3661000` + `mostSignificantOnly` → `"1h"`
-
-#### describe('formatNumber')
-
-- test('formats thousands') — `1321` → `"1.3k"`
-- test('formats small numbers as-is') — `900` → `"900"`
-- test('lowercase output') — `1500` → `"1.5k"` (不是 `"1.5K"`)
-
-#### describe('formatTokens')
-
-- test('strips .0 suffix') — `1000` → `"1k"` (不是 `"1.0k"`)
-- test('keeps non-zero decimal') — `1500` → `"1.5k"`
-
-#### describe('formatRelativeTime')
-
-- test('formats past time') — now - 3600s → `"1h ago"` (narrow style)
-- test('formats future time') — now + 3600s → `"in 1h"` (narrow style)
-- test('formats less than 1 second') — now → `"0s ago"`
-- test('uses custom now parameter for deterministic output')
-
----
-
-### src/utils/json.ts — 测试文件: `src/utils/__tests__/json.test.ts`
-
-#### describe('safeParseJSON')
-
-- test('parses valid JSON') — `'{"a":1}'` → `{ a: 1 }`
-- test('returns null for invalid JSON') — `'not json'` → null
-- test('returns null for null input') — `null` → null
-- test('returns null for undefined input') — `undefined` → null
-- test('returns null for empty string') — `""` → null
-- test('handles JSON with BOM') — BOM 前缀不影响解析
-- test('caches results for repeated calls') — 同一输入不重复解析
-
-#### describe('safeParseJSONC')
-
-- test('parses JSON with comments') — 含 `//` 注释的 JSON 正确解析
-- test('parses JSON with trailing commas') — 宽松模式
-- test('returns null for invalid input')
-- test('returns null for null input')
-
-#### describe('parseJSONL')
-
-- test('parses multiple JSON lines') — `'{"a":1}\n{"b":2}'` → `[{a:1}, {b:2}]`
-- test('skips malformed lines') — 含错误行时跳过该行
-- test('handles empty input') — `""` → `[]`
-- test('handles trailing newline') — 尾部换行不产生空元素
-- test('accepts Buffer input') — Buffer 类型同样工作
-- test('handles BOM prefix')
-
-#### describe('addItemToJSONCArray')
-
-- test('adds item to existing array') — `[1, 2]` + 3 → `[1, 2, 3]`
-- test('creates new array for empty content') — `""` + item → `[item]`
-- test('creates new array for non-array content') — `'"hello"'` + item → `[item]`
-- test('preserves comments in JSONC') — 注释不被丢弃
-- test('handles empty array') — `"[]"` + item → `[item]`
-
----
-
-### src/utils/diff.ts — 测试文件: `src/utils/__tests__/diff.test.ts`
-
-#### describe('adjustHunkLineNumbers')
-
-- test('shifts line numbers by positive offset') — 所有 hunk 的 oldStart/newStart 增加 offset
-- test('shifts by negative offset') — 负 offset 减少行号
-- test('handles empty hunk array') — `[]` → `[]`
-
-#### describe('getPatchFromContents')
-
-- test('returns empty array for identical content') — 相同内容无差异
-- test('detects added lines') — 新内容多出行
-- test('detects removed lines') — 旧内容缺少行
-- test('detects modified lines') — 行内容变化
-- test('handles empty old content') — 从空文件到有内容
-- test('handles empty new content') — 删除所有内容
-
----
-
-### src/utils/frontmatterParser.ts — 测试文件: `src/utils/__tests__/frontmatterParser.test.ts`
-
-#### describe('parseFrontmatter')
-
-- test('extracts YAML frontmatter between --- delimiters') — 正确提取 frontmatter 并返回 body
-- test('returns empty frontmatter for content without ---') — 无 frontmatter 时 data 为空
-- test('handles empty content') — `""` 正确处理
-- test('handles frontmatter-only content') — 只有 frontmatter 无 body
-- test('falls back to quoting on YAML parse error') — 无效 YAML 不崩溃
-
-#### describe('splitPathInFrontmatter')
-
-- test('splits comma-separated paths') — `"a.ts, b.ts"` → `["a.ts", "b.ts"]`
-- test('expands brace patterns') — `"*.{ts,tsx}"` → `["*.ts", "*.tsx"]`
-- test('handles string array input') — `["a.ts", "b.ts"]` → `["a.ts", "b.ts"]`
-- test('respects braces in comma splitting') — 大括号内的逗号不作为分隔符
-
-#### describe('parsePositiveIntFromFrontmatter')
-
-- test('returns number for valid positive int') — `5` → `5`
-- test('returns undefined for negative') — `-1` → undefined
-- test('returns undefined for non-number') — `"abc"` → undefined
-- test('returns undefined for float') — `1.5` → undefined
-
-#### describe('parseBooleanFrontmatter')
-
-- test('returns true for true') — `true` → true
-- test('returns true for "true"') — `"true"` → true
-- test('returns false for false') — `false` → false
-- test('returns false for other values') — `"yes"`, `1` → false
-
-#### describe('parseShellFrontmatter')
-
-- test('returns bash for "bash"') — 正确识别
-- test('returns powershell for "powershell"')
-- test('returns undefined for invalid value') — `"zsh"` → undefined
-
----
-
-### src/utils/file.ts（纯函数部分）— 测试文件: `src/utils/__tests__/file.test.ts`
-
-#### describe('convertLeadingTabsToSpaces')
-
-- test('converts single tab to 2 spaces') — `"\thello"` → `"  hello"`
-- test('converts multiple leading tabs') — `"\t\thello"` → `"    hello"`
-- test('does not convert tabs within line') — `"a\tb"` 保持原样
-- test('handles mixed content')
-
-#### describe('addLineNumbers')
-
-- test('adds line numbers starting from 1') — 每行添加 `N\t` 前缀
-- test('respects startLine parameter') — 从指定行号开始
-- test('handles empty content')
-
-#### describe('stripLineNumberPrefix')
-
-- test('strips tab-prefixed line number') — `"1\thello"` → `"hello"`
-- test('strips padded line number') — `"  1\thello"` → `"hello"`
-- test('returns line unchanged when no prefix')
-
-#### describe('pathsEqual')
-
-- test('returns true for identical paths')
-- test('handles trailing slashes') — 带/不带尾部斜杠视为相同
-- test('handles case sensitivity based on platform')
-
-#### describe('normalizePathForComparison')
-
-- test('normalizes forward slashes')
-- test('resolves path for comparison')
-
----
-
-### src/utils/glob.ts（纯函数部分）— 测试文件: `src/utils/__tests__/glob.test.ts`
-
-#### describe('extractGlobBaseDirectory')
-
-- test('extracts static prefix from glob') — `"src/**/*.ts"` → `{ baseDir: "src", relativePattern: "**/*.ts" }`
-- test('handles root-level glob') — `"*.ts"` → `{ baseDir: ".", relativePattern: "*.ts" }`
-- test('handles deep static path') — `"src/utils/model/*.ts"` → baseDir 为 `"src/utils/model"`
-- test('handles Windows drive root') — `"C:\\Users\\**\\*.ts"` 正确分割
-
----
-
-### src/utils/tokens.ts（纯函数部分）— 测试文件: `src/utils/__tests__/tokens.test.ts`
-
-#### describe('getTokenCountFromUsage')
-
-- test('sums input and output tokens') — `{ input_tokens: 100, output_tokens: 50 }` → 150
-- test('includes cache tokens') — cache_creation + cache_read 加入总数
-- test('handles zero values') — 全 0 时返回 0
-
----
-
-### src/utils/path.ts（纯函数部分）— 测试文件: `src/utils/__tests__/path.test.ts`
-
-#### describe('containsPathTraversal')
-
-- test('detects ../ traversal') — `"../etc/passwd"` → true
-- test('detects mid-path traversal') — `"foo/../../bar"` → true
-- test('returns false for safe paths') — `"src/utils/file.ts"` → false
-- test('returns false for paths containing .. in names') — `"foo..bar"` → false
-
-#### describe('normalizePathForConfigKey')
-
-- test('converts backslashes to forward slashes') — `"src\\utils"` → `"src/utils"`
-- test('leaves forward slashes unchanged')
-
----
-
-## Mock 需求
-
-本计划中的函数大部分为纯函数，**不需要 mock**。少数例外：
-
-| 函数 | 依赖 | 处理 |
-|------|------|------|
-| `hashContent` / `hashPair` | `Bun.hash` | Bun 运行时下自动可用 |
-| `formatRelativeTime` | `Date` | 使用 `now` 参数注入确定性时间 |
-| `safeParseJSON` | `logError` | 可通过 `shouldLogError: false` 跳过 |
-| `safeParseJSONC` | `logError` | mock `logError` 避免测试输出噪音 |

docs/test-plans/03-context-building.md

@@ -1,134 +0,0 @@
-# Context 构建测试计划
-
-## 概述
-
-Context 构建系统负责组装发送给 Claude API 的系统提示和用户上下文。包括 git 状态获取、CLAUDE.md 文件发现与加载、系统提示拼装三部分。
-
-## 被测文件
-
-| 文件 | 关键导出 |
-|------|----------|
-| `src/context.ts` | `getSystemContext`, `getUserContext`, `getGitStatus`, `setSystemPromptInjection` |
-| `src/utils/claudemd.ts` | `stripHtmlComments`, `getClaudeMds`, `isMemoryFilePath`, `getLargeMemoryFiles`, `filterInjectedMemoryFiles`, `getExternalClaudeMdIncludes`, `hasExternalClaudeMdIncludes`, `processMemoryFile`, `getMemoryFiles` |
-| `src/utils/systemPrompt.ts` | `buildEffectiveSystemPrompt` |
-
----
-
-## 测试用例
-
-### src/utils/claudemd.ts — 纯函数部分
-
-#### describe('stripHtmlComments')
-
-- test('strips block-level HTML comments') — `"text <!-- comment --> more"` → content 不含注释
-- test('preserves inline content') — 行内文本保留
-- test('preserves code block content') — ` ```html\n<!-- not stripped -->\n``` ` 内的注释不移除
-- test('returns stripped: false when no comments') — 无注释时 stripped 为 false
-- test('returns stripped: true when comments exist')
-- test('handles empty string') — `""` → `{ content: "", stripped: false }`
-- test('handles multiple comments') — 多个注释全部移除
-
-#### describe('getClaudeMds')
-
-- test('assembles memory files with type descriptions') — 不同 type 的文件有不同前缀描述
-- test('includes instruction prompt prefix') — 输出包含指令前缀
-- test('handles empty memory files array') — 空数组返回空字符串或最小前缀
-- test('respects filter parameter') — filter 函数可过滤特定类型
-- test('concatenates multiple files with separators')
-
-#### describe('isMemoryFilePath')
-
-- test('returns true for CLAUDE.md path') — `"/project/CLAUDE.md"` → true
-- test('returns true for .claude/rules/ path') — `"/project/.claude/rules/foo.md"` → true
-- test('returns true for memory file path') — `"~/.claude/memory/foo.md"` → true
-- test('returns false for regular file') — `"/project/src/main.ts"` → false
-- test('returns false for unrelated .md file') — `"/project/README.md"` → false
-
-#### describe('getLargeMemoryFiles')
-
-- test('returns files exceeding 40K chars') — 内容 > MAX_MEMORY_CHARACTER_COUNT 的文件被返回
-- test('returns empty array when all files are small')
-- test('correctly identifies threshold boundary')
-
-#### describe('filterInjectedMemoryFiles')
-
-- test('filters out AutoMem type files') — feature flag 开启时移除自动记忆
-- test('filters out TeamMem type files')
-- test('preserves other types') — 非 AutoMem/TeamMem 的文件保留
-
-#### describe('getExternalClaudeMdIncludes')
-
-- test('returns includes from outside CWD') — 外部 @include 路径被识别
-- test('returns empty array when all includes are internal')
-
-#### describe('hasExternalClaudeMdIncludes')
-
-- test('returns true when external includes exist')
-- test('returns false when no external includes')
-
----
-
-### src/utils/systemPrompt.ts
-
-#### describe('buildEffectiveSystemPrompt')
-
-- test('returns default system prompt when no overrides') — 无任何覆盖时使用默认提示
-- test('overrideSystemPrompt replaces everything') — override 模式替换全部内容
-- test('customSystemPrompt replaces default') — `--system-prompt` 参数替换默认
-- test('appendSystemPrompt is appended after main prompt') — append 在主提示之后
-- test('agent definition replaces default prompt') — agent 模式使用 agent prompt
-- test('agent definition with append combines both') — agent prompt + append
-- test('override takes precedence over agent and custom') — 优先级最高
-- test('returns array of strings') — 返回值为 SystemPrompt 类型（字符串数组）
-
----
-
-### src/context.ts — 需 Mock 的部分
-
-#### describe('getGitStatus')
-
-- test('returns formatted git status string') — 包含 branch、status、log、user
-- test('truncates status at 2000 chars') — 超长 status 被截断
-- test('returns null in test environment') — `NODE_ENV=test` 时返回 null
-- test('returns null in non-git directory') — 非 git 仓库返回 null
-- test('runs git commands in parallel') — 多个 git 命令并行执行
-
-#### describe('getSystemContext')
-
-- test('includes gitStatus key') — 返回对象包含 gitStatus
-- test('returns memoized result on subsequent calls') — 多次调用返回同一结果
-- test('skips git when instructions disabled')
-
-#### describe('getUserContext')
-
-- test('includes currentDate key') — 返回对象包含当前日期
-- test('includes claudeMd key when CLAUDE.md exists') — 加载 CLAUDE.md 内容
-- test('respects CLAUDE_CODE_DISABLE_CLAUDE_MDS env') — 设置后不加载 CLAUDE.md
-- test('returns memoized result')
-
-#### describe('setSystemPromptInjection')
-
-- test('clears memoized context caches') — 调用后下次 getSystemContext/getUserContext 重新计算
-- test('injection value is accessible via getSystemPromptInjection')
-
----
-
-## Mock 需求
-
-| 依赖 | Mock 方式 | 用途 |
-|------|-----------|------|
-| `execFileNoThrow` | `mock.module` | `getGitStatus` 中的 git 命令 |
-| `getMemoryFiles` | `mock.module` | `getUserContext` 中的 CLAUDE.md 加载 |
-| `getCwd` | `mock.module` | 路径解析上下文 |
-| `process.env.NODE_ENV` | 直接设置 | 测试环境检测 |
-| `process.env.CLAUDE_CODE_DISABLE_CLAUDE_MDS` | 直接设置 | 禁用 CLAUDE.md |
-
-## 集成测试场景
-
-放在 `tests/integration/context-build.test.ts`：
-
-### describe('Context assembly pipeline')
-
-- test('getUserContext produces claudeMd containing CLAUDE.md content') — 端到端验证 CLAUDE.md 被正确加载到 context
-- test('buildEffectiveSystemPrompt + getUserContext produces complete prompt') — 系统提示 + 用户上下文完整性
-- test('setSystemPromptInjection invalidates and rebuilds context') — 注入后重新构建上下文

docs/test-plans/04-permission-system.md

@@ -1,104 +0,0 @@
-# 权限系统测试计划
-
-## 概述
-
-权限系统控制工具是否可以执行，包含规则解析器、权限检查管线和权限模式判断。测试重点是纯函数解析器和规则匹配逻辑。
-
-## 被测文件
-
-| 文件 | 关键导出 |
-|------|----------|
-| `src/utils/permissions/permissionRuleParser.ts` | `permissionRuleValueFromString`, `permissionRuleValueToString`, `escapeRuleContent`, `unescapeRuleContent`, `normalizeLegacyToolName`, `getLegacyToolNames` |
-| `src/utils/permissions/PermissionMode.ts` | 权限模式常量和辅助函数 |
-| `src/utils/permissions/permissions.ts` | `hasPermissionsToUseTool`, `getDenyRuleForTool`, `checkRuleBasedPermissions` |
-| `src/types/permissions.ts` | `PermissionMode`, `PermissionBehavior`, `PermissionRule` 类型定义 |
-
----
-
-## 测试用例
-
-### src/utils/permissions/permissionRuleParser.ts
-
-#### describe('escapeRuleContent')
-
-- test('escapes backslashes first') — `'test\\value'` → `'test\\\\value'`
-- test('escapes opening parentheses') — `'print(1)'` → `'print\\(1\\)'`
-- test('escapes closing parentheses') — `'func()'` → `'func\\(\\)'`
-- test('handles combined escape') — `'echo "test\\nvalue"'` 中的 `\\` 先转义
-- test('handles empty string') — `''` → `''`
-- test('no-op for string without special chars') — `'npm install'` 原样返回
-
-#### describe('unescapeRuleContent')
-
-- test('unescapes parentheses') — `'print\\(1\\)'` → `'print(1)'`
-- test('unescapes backslashes last') — `'test\\\\nvalue'` → `'test\\nvalue'`
-- test('handles empty string')
-- test('roundtrip: escape then unescape returns original') — `unescapeRuleContent(escapeRuleContent(x)) === x`
-
-#### describe('permissionRuleValueFromString')
-
-- test('parses tool name only') — `'Bash'` → `{ toolName: 'Bash' }`
-- test('parses tool name with content') — `'Bash(npm install)'` → `{ toolName: 'Bash', ruleContent: 'npm install' }`
-- test('parses content with escaped parentheses') — `'Bash(python -c "print\\(1\\)")'` → ruleContent 为 `'python -c "print(1)"'`
-- test('treats empty parens as tool-wide rule') — `'Bash()'` → `{ toolName: 'Bash' }`（无 ruleContent）
-- test('treats wildcard content as tool-wide rule') — `'Bash(*)'` → `{ toolName: 'Bash' }`
-- test('normalizes legacy tool names') — `'Task'` → `{ toolName: 'Agent' }`（或对应的 AGENT_TOOL_NAME）
-- test('handles malformed input: no closing paren') — `'Bash(npm'` → 整个字符串作为 toolName
-- test('handles malformed input: content after closing paren') — `'Bash(npm)extra'` → 整个字符串作为 toolName
-- test('handles missing tool name') — `'(foo)'` → 整个字符串作为 toolName
-
-#### describe('permissionRuleValueToString')
-
-- test('serializes tool name only') — `{ toolName: 'Bash' }` → `'Bash'`
-- test('serializes with content') — `{ toolName: 'Bash', ruleContent: 'npm install' }` → `'Bash(npm install)'`
-- test('escapes content with parentheses') — ruleContent 含 `()` 时正确转义
-- test('roundtrip: fromString then toString preserves value') — 往返一致
-
-#### describe('normalizeLegacyToolName')
-
-- test('maps Task to Agent tool name') — `'Task'` → AGENT_TOOL_NAME
-- test('maps KillShell to TaskStop tool name') — `'KillShell'` → TASK_STOP_TOOL_NAME
-- test('maps AgentOutputTool to TaskOutput tool name')
-- test('returns unknown names unchanged') — `'UnknownTool'` → `'UnknownTool'`
-
-#### describe('getLegacyToolNames')
-
-- test('returns legacy names for canonical name') — 给定 AGENT_TOOL_NAME 返回包含 `'Task'`
-- test('returns empty array for name with no legacy aliases')
-
----
-
-### src/utils/permissions/permissions.ts — 需 Mock
-
-#### describe('getDenyRuleForTool')
-
-- test('returns deny rule matching tool name') — 匹配到 blanket deny 规则时返回
-- test('returns null when no deny rules match') — 无匹配时返回 null
-- test('matches MCP tools by server prefix') — `mcp__server` 规则匹配该 server 下的 MCP 工具
-- test('does not match content-specific deny rules') — 有 ruleContent 的 deny 规则不作为 blanket deny
-
-#### describe('checkRuleBasedPermissions')（集成级别）
-
-- test('deny rule takes precedence over allow') — 同时有 allow 和 deny 时 deny 优先
-- test('ask rule prompts user') — 匹配 ask 规则返回 `{ behavior: 'ask' }`
-- test('allow rule permits execution') — 匹配 allow 规则返回 `{ behavior: 'allow' }`
-- test('passthrough when no rules match') — 无匹配规则返回 passthrough
-
----
-
-## Mock 需求
-
-| 依赖 | Mock 方式 | 说明 |
-|------|-----------|------|
-| `bun:bundle` (feature) | 已 polyfill | BRIEF_TOOL_NAME 条件加载 |
-| Tool 常量导入 | 实际值 | AGENT_TOOL_NAME 等从常量文件导入 |
-| `appState` | mock object | `hasPermissionsToUseTool` 中的状态依赖 |
-| Tool 对象 | mock object | 模拟 tool 的 name, checkPermissions 等 |
-
-## 集成测试场景
-
-### describe('Permission pipeline end-to-end')
-
-- test('deny rule blocks tool before it runs') — deny 规则在 call 前拦截
-- test('bypassPermissions mode allows all') — bypass 模式下 ask → allow
-- test('dontAsk mode converts ask to deny') — dontAsk 模式下 ask → deny

docs/test-plans/05-model-routing.md

@@ -1,113 +0,0 @@
-# 模型路由测试计划
-
-## 概述
-
-模型路由系统负责 API provider 选择、模型别名解析、模型名规范化和运行时模型决策。测试重点是纯函数和环境变量驱动的逻辑。
-
-## 被测文件
-
-| 文件 | 关键导出 |
-|------|----------|
-| `src/utils/model/aliases.ts` | `MODEL_ALIASES`, `MODEL_FAMILY_ALIASES`, `isModelAlias`, `isModelFamilyAlias` |
-| `src/utils/model/providers.ts` | `APIProvider`, `getAPIProvider`, `isFirstPartyAnthropicBaseUrl` |
-| `src/utils/model/model.ts` | `firstPartyNameToCanonical`, `getCanonicalName`, `parseUserSpecifiedModel`, `normalizeModelStringForAPI`, `getRuntimeMainLoopModel`, `getDefaultMainLoopModelSetting` |
-
----
-
-## 测试用例
-
-### src/utils/model/aliases.ts
-
-#### describe('isModelAlias')
-
-- test('returns true for "sonnet"') — 有效别名
-- test('returns true for "opus"')
-- test('returns true for "haiku"')
-- test('returns true for "best"')
-- test('returns true for "sonnet[1m]"')
-- test('returns true for "opus[1m]"')
-- test('returns true for "opusplan"')
-- test('returns false for full model ID') — `'claude-sonnet-4-6-20250514'` → false
-- test('returns false for unknown string') — `'gpt-4'` → false
-- test('is case-sensitive') — `'Sonnet'` → false（别名是小写）
-
-#### describe('isModelFamilyAlias')
-
-- test('returns true for "sonnet"')
-- test('returns true for "opus"')
-- test('returns true for "haiku"')
-- test('returns false for "best"') — best 不是 family alias
-- test('returns false for "opusplan"')
-- test('returns false for "sonnet[1m]"')
-
----
-
-### src/utils/model/providers.ts
-
-#### describe('getAPIProvider')
-
-- test('returns "firstParty" by default') — 无相关 env 时返回 firstParty
-- test('returns "bedrock" when CLAUDE_CODE_USE_BEDROCK is set') — env 为 truthy 值
-- test('returns "vertex" when CLAUDE_CODE_USE_VERTEX is set')
-- test('returns "foundry" when CLAUDE_CODE_USE_FOUNDRY is set')
-- test('bedrock takes precedence over vertex') — 多个 env 同时设置时 bedrock 优先
-
-#### describe('isFirstPartyAnthropicBaseUrl')
-
-- test('returns true when ANTHROPIC_BASE_URL is not set') — 默认 API
-- test('returns true for api.anthropic.com') — `'https://api.anthropic.com'` → true
-- test('returns false for custom URL') — `'https://my-proxy.com'` → false
-- test('returns false for invalid URL') — 非法 URL → false
-- test('returns true for staging URL when USER_TYPE is ant') — `'https://api-staging.anthropic.com'` + ant → true
-
----
-
-### src/utils/model/model.ts
-
-#### describe('firstPartyNameToCanonical')
-
-- test('maps opus-4-6 full name to canonical') — `'claude-opus-4-6-20250514'` → `'claude-opus-4-6'`
-- test('maps sonnet-4-6 full name') — `'claude-sonnet-4-6-20250514'` → `'claude-sonnet-4-6'`
-- test('maps haiku-4-5') — `'claude-haiku-4-5-20251001'` → `'claude-haiku-4-5'`
-- test('maps 3P provider format') — `'us.anthropic.claude-opus-4-6-v1:0'` → `'claude-opus-4-6'`
-- test('maps claude-3-7-sonnet') — `'claude-3-7-sonnet-20250219'` → `'claude-3-7-sonnet'`
-- test('maps claude-3-5-sonnet') → `'claude-3-5-sonnet'`
-- test('maps claude-3-5-haiku') → `'claude-3-5-haiku'`
-- test('maps claude-3-opus') → `'claude-3-opus'`
-- test('is case insensitive') — `'Claude-Opus-4-6'` → `'claude-opus-4-6'`
-- test('falls back to input for unknown model') — `'unknown-model'` → `'unknown-model'`
-- test('differentiates opus-4 vs opus-4-5 vs opus-4-6') — 更具体的版本优先匹配
-
-#### describe('parseUserSpecifiedModel')
-
-- test('resolves "sonnet" to default sonnet model')
-- test('resolves "opus" to default opus model')
-- test('resolves "haiku" to default haiku model')
-- test('resolves "best" to best model')
-- test('resolves "opusplan" to default sonnet model') — opusplan 默认用 sonnet
-- test('appends [1m] suffix when alias has [1m]') — `'sonnet[1m]'` → 模型名 + `'[1m]'`
-- test('preserves original case for custom model names') — `'my-Custom-Model'` 保留大小写
-- test('handles [1m] suffix on non-alias models') — `'custom-model[1m]'` → `'custom-model[1m]'`
-- test('trims whitespace') — `'  sonnet  '` → 正确解析
-
-#### describe('getRuntimeMainLoopModel')
-
-- test('returns mainLoopModel by default') — 无特殊条件时原样返回
-- test('returns opus in plan mode when opusplan is set') — opusplan + plan mode → opus
-- test('returns sonnet in plan mode when haiku is set') — haiku + plan mode → sonnet 升级
-- test('returns mainLoopModel in non-plan mode') — 非 plan 模式不做替换
-
----
-
-## Mock 需求
-
-| 依赖 | Mock 方式 | 说明 |
-|------|-----------|------|
-| `process.env.CLAUDE_CODE_USE_BEDROCK/VERTEX/FOUNDRY` | 直接设置/恢复 | provider 选择 |
-| `process.env.ANTHROPIC_BASE_URL` | 直接设置/恢复 | URL 检测 |
-| `process.env.USER_TYPE` | 直接设置/恢复 | staging URL 和 ant 功能 |
-| `getModelStrings()` | mock.module | 返回固定模型 ID |
-| `getMainLoopModelOverride` | mock.module | 会话中模型覆盖 |
-| `getSettings_DEPRECATED` | mock.module | 用户设置中的模型 |
-| `getUserSpecifiedModelSetting` | mock.module | `getRuntimeMainLoopModel` 依赖 |
-| `isModelAllowed` | mock.module | allowlist 检查 |

docs/test-plans/06-message-handling.md

@@ -1,165 +0,0 @@
-# 消息处理测试计划
-
-## 概述
-
-消息处理系统负责消息的创建、查询、规范化和文本提取。覆盖消息类型定义、消息工厂函数、消息过滤/查询工具和 API 规范化管线。
-
-## 被测文件
-
-| 文件 | 关键导出 |
-|------|----------|
-| `src/types/message.ts` | `MessageType`, `Message`, `AssistantMessage`, `UserMessage`, `SystemMessage` 等类型 |
-| `src/utils/messages.ts` | 消息创建、查询、规范化、文本提取等函数（~3100 行） |
-| `src/utils/messages/mappers.ts` | 消息映射工具 |
-
----
-
-## 测试用例
-
-### src/utils/messages.ts — 消息创建
-
-#### describe('createAssistantMessage')
-
-- test('creates message with type "assistant"') — type 字段正确
-- test('creates message with role "assistant"') — role 正确
-- test('creates message with empty content array') — 默认 content 为空
-- test('generates unique uuid') — 每次调用 uuid 不同
-- test('includes costUsd as 0')
-
-#### describe('createUserMessage')
-
-- test('creates message with type "user"') — type 字段正确
-- test('creates message with provided content') — content 正确传入
-- test('generates unique uuid')
-
-#### describe('createSystemMessage')
-
-- test('creates system message with correct type')
-- test('includes message content')
-
-#### describe('createProgressMessage')
-
-- test('creates progress message with data')
-- test('has correct type "progress"')
-
----
-
-### src/utils/messages.ts — 消息查询
-
-#### describe('getLastAssistantMessage')
-
-- test('returns last assistant message from array') — 多条消息中返回最后一条 assistant
-- test('returns undefined for empty array')
-- test('returns undefined when no assistant messages exist')
-
-#### describe('hasToolCallsInLastAssistantTurn')
-
-- test('returns true when last assistant has tool_use content') — content 含 tool_use block
-- test('returns false when last assistant has only text')
-- test('returns false for empty messages')
-
-#### describe('isSyntheticMessage')
-
-- test('identifies interrupt message as synthetic') — INTERRUPT_MESSAGE 标记
-- test('identifies cancel message as synthetic')
-- test('returns false for normal user messages')
-
-#### describe('isNotEmptyMessage')
-
-- test('returns true for message with content')
-- test('returns false for message with empty content array')
-- test('returns false for message with empty text content')
-
----
-
-### src/utils/messages.ts — 文本提取
-
-#### describe('getAssistantMessageText')
-
-- test('extracts text from text blocks') — content 含 `{ type: 'text', text: 'hello' }` 时提取
-- test('returns empty string for non-text content') — 仅含 tool_use 时返回空
-- test('concatenates multiple text blocks')
-
-#### describe('getUserMessageText')
-
-- test('extracts text from string content') — content 为纯字符串
-- test('extracts text from content array') — content 为数组时提取 text 块
-- test('handles empty content')
-
-#### describe('extractTextContent')
-
-- test('extracts text items from mixed content') — 过滤出 type: 'text' 的项
-- test('returns empty array for all non-text content')
-
----
-
-### src/utils/messages.ts — 规范化
-
-#### describe('normalizeMessages')
-
-- test('converts raw messages to normalized format') — 消息数组规范化
-- test('handles empty array') — `[]` → `[]`
-- test('preserves message order')
-- test('handles mixed message types')
-
-#### describe('normalizeMessagesForAPI')
-
-- test('filters out system messages') — 系统消息不发送给 API
-- test('filters out progress messages')
-- test('filters out attachment messages')
-- test('preserves user and assistant messages')
-- test('reorders tool results to match API expectations')
-- test('handles empty array')
-
----
-
-### src/utils/messages.ts — 合并
-
-#### describe('mergeUserMessages')
-
-- test('merges consecutive user messages') — 相邻用户消息合并
-- test('does not merge non-consecutive user messages')
-- test('preserves assistant messages between user messages')
-
-#### describe('mergeAssistantMessages')
-
-- test('merges consecutive assistant messages')
-- test('combines content arrays')
-
----
-
-### src/utils/messages.ts — 辅助函数
-
-#### describe('buildMessageLookups')
-
-- test('builds index by message uuid') — 按 uuid 建立查找表
-- test('returns empty lookups for empty messages')
-- test('handles duplicate uuids gracefully')
-
----
-
-## Mock 需求
-
-| 依赖 | Mock 方式 | 说明 |
-|------|-----------|------|
-| `crypto.randomUUID` | `mock` 或 spy | 消息创建中的 uuid 生成 |
-| Message 对象 | 手动构造 | 创建符合类型的 mock 消息对象 |
-
-### Mock 消息工厂（放在 `tests/mocks/messages.ts`）
-
-```typescript
-// 通用 mock 消息构造器
-export function mockAssistantMessage(overrides?: Partial<AssistantMessage>): AssistantMessage
-export function mockUserMessage(content: string, overrides?: Partial<UserMessage>): UserMessage
-export function mockSystemMessage(overrides?: Partial<SystemMessage>): SystemMessage
-export function mockToolUseBlock(name: string, input: unknown): ToolUseBlock
-export function mockToolResultMessage(toolUseId: string, content: string): UserMessage
-```
-
-## 集成测试场景
-
-### describe('Message pipeline')
-
-- test('create → normalize → API format produces valid request') — 创建消息 → normalizeMessagesForAPI → 验证输出结构
-- test('tool use and tool result pairing is preserved through normalization')
-- test('merge + normalize handles conversation with interruptions')