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

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

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

.claude/skills/teach-me/SKILL.md

@@ -41,8 +41,7 @@ All teach-me data is stored under `.claude/skills/teach-me/records/`:
 .claude/skills/teach-me/records/
 ├── learner-profile.md     # Cross-topic notes (created on first session)
 └── {topic-slug}/
-    ├── session.md         # Learning state: concepts, status, notes
+    └── session.md         # Learning state: concepts, status, notes
-    └── {topic-slug}-notes.md  # Learner-facing summary notes (generated at session end)
 ```
 
 **Slug**: Topic in kebab-case, 2-5 words. Example: "Python decorators" → `python-decorators`
@@ -276,8 +275,7 @@ Update `session.md` after each round:
 When all concepts mastered or user ends session:
 
 1. Update `session.md` with final state.
-2. **Generate learner-facing notes** — write `{topic-slug}-notes.md` in the topic directory. This is a standalone reference document the learner can review later. See "Notes Generation" below for format.
+2. Update `.claude/skills/teach-me/records/learner-profile.md` (keep under 30 lines):
-3. Update `.claude/skills/teach-me/records/learner-profile.md` (keep under 30 lines):
 
 ```markdown
 # Learner Profile
@@ -295,48 +293,7 @@ Updated: {timestamp}
 - Python decorators (8/10 concepts, 2025-01-15)
 ```
 
-4. Give a brief text summary of what was covered, key insights, and areas for further study.
+3. Give a brief text summary of what was covered, key insights, and areas for further study.
-
-## Notes Generation
-
-At session end, generate a learner-facing notes file at `{topic-slug}/{topic-slug}-notes.md`. This file is **written for the learner to review later**, not for the tutor. It should be self-contained and organized as a quick-reference.
-
-### Notes Structure
-
-```markdown
-# {Topic} 核心笔记
-
-## 1. {Section Name}
-{Key concept, mechanism, or principle}
-* **One-line summary**: {what it does / why it matters}
-* **Detail**: {brief explanation, 2-4 sentences max}
-* **Example** (if applicable): {code snippet, command, or concrete scenario}
-
----
-
-## 2. {Section Name}
-...
-
----
-
-## n. 实战参数 / Cheat Sheet (if applicable)
-{Practical commands, config, or quick-reference table}
-
-| Parameter / Concept | What it does | Tuning tip |
-|---------------------|-------------|------------|
-| ... | ... | ... |
-```
-
-### Notes Writing Rules
-
-1. **Start with "what & why"** before "how". Each section should answer: what is this, why does it exist, what problem does it solve.
-2. **Use analogies sparingly but effectively**. Only include an analogy if it clarifies a non-obvious mechanism (e.g., "PagedAttention is like OS virtual memory paging").
-3. **Include trade-offs**. Every optimization or design choice has a cost. Always state it (e.g., "TP improves throughput but increases communication latency").
-4. **Code / command examples should be minimal**. Under 10 lines, self-contained, with comments explaining the key flags.
-5. **Organize by concept dependency**, not by chronological teaching order. Foundation concepts first, advanced ones last.
-6. **No quiz questions, no misconceptions, no tutor-side notes**. This is a clean reference document.
-7. **Language matches the session**. If the session was in Chinese, notes are in Chinese (technical terms can stay in English).
-8. **Keep it under 150 lines**. If it gets too long, the learner won't review it. Be ruthless about cutting fluff.
 
 ## Resuming Sessions
 

.editorconfig

@@ -1,8 +1,8 @@
 root = true
 
 [*]
-indent_style = space
+indent_style = tab
-indent_size = 2
+indent_size = 4
 end_of_line = lf
 charset = utf-8
 trim_trailing_whitespace = true

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,52 +0,0 @@
----
-name: Bug 报告
-description: 报告一个可复现的 bug
-title: "bug: "
-labels: ["bug"]
-assignees: []
----
-
-## 发帖前必读
-
-- [ ] 我已经搜索过 [现有 Issues](https://github.com/claude-code-best/claude-code/issues)，没有找到重复。
-- [ ] 我使用的是 **最新版本**（`bun run build` 或最新 release）。
-- [ ] 我已经阅读过 [README](https://github.com/claude-code-best/claude-code) 和相关文档。
-
-**未完成以上检查的 Issue 将被直接关闭。**
-
----
-
-## 运行环境
-
-| 项目| 值|
-|---|---|
-| 操作系统| 例如 macOS 15.4、Ubuntu 24.04|
-| Bun 版本| 例如 `bun --version` 的输出|
-| Claude Code 版本| 例如 `2.4.3` 或 commit hash|
-| 安装方式| `bun run build` / npm / 其他|
-| 模型| 例如 claude-sonnet-4-6、claude-opus-4-7|
-
-## 复现步骤
-
-1.
-2.
-3.
-
-## 期望行为
-
-<!-- 应该发生什么？ -->
-
-## 实际行为
-
-<!-- 实际发生了什么？如有必要可附截图。 -->
-
-## 相关日志
-
-<!-- 粘贴终端输出或错误信息，请使用 triple backticks 代码块。 -->
-
-```text
-```
-
-## 补充信息
-
-<!-- 其他上下文 — 配置、环境变量、尝试过的 workaround 等。 -->

.github/ISSUE_TEMPLATE/config.yml

@@ -1,8 +0,0 @@
-blank_issues_enabled: false
-contact_links:
-  - name: 💬 讨论区
-    url: https://github.com/claude-code-best/claude-code/discussions
-    about: 使用问题、功能建议和一般讨论 — 请使用 Discussions 而非 Issues。
-  - name: 📖 项目文档
-    url: https://github.com/claude-code-best/claude-code
-    about: 提交 issue 前，请先阅读 README 和相关文档，你的问题可能已经有答案了。

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,31 +0,0 @@
----
-name: 功能建议
-description: 提出新功能或改进建议
-title: "feat: "
-labels: ["enhancement"]
-assignees: []
----
-
-## 发帖前必读
-
-- [ ] 我已经搜索过 [现有 Issues](https://github.com/claude-code-best/claude-code/issues)，没有找到重复。
-- [ ] 这是功能建议，不是 Bug 报告或使用问题。
-- [ ] 使用问题请前往 [Discussions](https://github.com/claude-code-best/claude-code/discussions)。
-
----
-
-## 要解决的问题
-
-<!-- 这个功能解决什么问题？为什么需要它？ -->
-
-## 建议方案
-
-<!-- 描述你建议的实现方式，尽量简洁具体。 -->
-
-## 考虑过的替代方案
-
-<!-- 还有没有想到的其他实现思路？ -->
-
-## 补充信息
-
-<!-- 截图、草图、参考资料，或其他有助于说明需求的内容。 -->

.github/workflows/ci.yml

@@ -2,60 +2,37 @@ name: CI
 
 on:
   push:
-    branches: [main, "feature/*", "feat/*"]
+    branches: [main, feature/*]
   pull_request:
-    branches: [main, "feat/*"]
+    branches: [main]
-  workflow_dispatch:
-
-permissions:
-  contents: read
 
 jobs:
   ci:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2, 2026-04-25
+      - uses: actions/checkout@v4
-        env:
-          GIT_CONFIG_COUNT: 2
-          GIT_CONFIG_KEY_0: init.defaultBranch
-          GIT_CONFIG_VALUE_0: main
-          GIT_CONFIG_KEY_1: advice.defaultBranchName
-          GIT_CONFIG_VALUE_1: "false"
 
-      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2, 2026-04-25
+      - uses: oven-sh/setup-bun@v2
         with:
           bun-version: latest
 
       - name: Install dependencies
-        env:
-          CLAUDE_CODE_SKIP_CHROME_MCP_SETUP: "1"
         run: bun install --frozen-lockfile
 
-      - name: Lint and format check
-        run: bunx biome ci .
-
       - name: Type check
-        run: bun run typecheck
+        run: bunx tsc --noEmit
 
       - name: Test with Coverage
         run: |
-          # Tolerate pre-existing flaky tests (Bun mock pollution / order-dependent state).
-          # We still require lcov.info to be generated and contain real coverage data.
           set -o pipefail
-          bun test --coverage --coverage-reporter lcov --coverage-dir coverage 2>&1 | grep -vE '^\s*(\(pass\)|\(skip\))' | sed '/^.*\/__tests__\/.*:$/d' | cat -s
+          bun test --coverage --coverage-reporter=lcov 2>&1 | grep -vE '^\s*(\(pass\)|\(skip\))' | sed '/^.*\/__tests__\/.*:$/d' | cat -s
-          test -s coverage/lcov.info
-          grep -q '^SF:' coverage/lcov.info
 
-      # codecov 坏了，老是失败，先注释掉
+      - name: Upload coverage to Codecov
-      # - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
-      #   if: ${{ github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository }}
+        with:
-      #   uses: codecov/codecov-action@75cd11691c0faa626561e295848008c8a7dddffe # v5, 2026-04-25
+          file: ./coverage/lcov.info
-      #   with:
+          token: ${{ secrets.CODECOV_TOKEN }}
-      #     fail_ci_if_error: true
-      #     files: ./coverage/lcov.info
-      #     disable_search: true
-      #     token: ${{ secrets.CODECOV_TOKEN }}
 
       - name: Build
         run: bun run build:vite

.github/workflows/publish-npm.yml

@@ -1,79 +0,0 @@
-name: Publish to npm
-
-on:
-  push:
-    tags:
-      - "v*"
-  workflow_dispatch:
-    inputs:
-      version:
-        description: "版本号 (例如: v1.9.0)"
-        required: true
-        type: string
-
-permissions:
-  contents: write
-  packages: write
-  id-token: write
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2, 2026-04-25
-        with:
-          ref: ${{ github.event.inputs.version || github.ref }}
-
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6, 2026-04-25
-        with:
-          node-version: "24"
-          registry-url: "https://registry.npmjs.org"
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2, 2026-04-25
-        with:
-          bun-version: latest
-
-      - name: Install dependencies
-        run: bun install --frozen-lockfile
-      - name: Type check
-        run: bun run typecheck
-
-      - name: Run tests
-        run: bun test
-
-      - name: Publish to npm
-        run: npm publish --provenance --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-      - name: Generate changelog
-        id: changelog
-        run: |
-          VERSION="${{ github.event.inputs.version || github.ref_name }}"
-          PREV_TAG=$(git tag --sort=-version:refname | grep -v "^${VERSION#v}$" | head -1)
-
-          if [ -n "$PREV_TAG" ]; then
-            COMMITS=$(git log "${PREV_TAG}..${VERSION}" --pretty=format:"- %s (%h)" --no-merges)
-          else
-            COMMITS=$(git log --pretty=format:"- %s (%h)" --no-merges -20)
-          fi
-
-          {
-            echo "commits<<EOF"
-            echo "$COMMITS"
-            echo "EOF"
-          } >> "$GITHUB_OUTPUT"
-
-      - name: Create GitHub Release
-        uses: softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65 # v2, 2026-04-25
-        with:
-          name: ${{ github.event.inputs.version || github.ref_name }}
-          body: |
-            ## What's Changed
-
-            ${{ steps.changelog.outputs.commits }}
-
-            **Full Changelog**: https://github.com/${{ github.repository }}/compare/${{ github.event.inputs.version || github.ref_name }}^...${{ github.event.inputs.version || github.ref_name }}
-          draft: false
-          prerelease: ${{ contains(github.event.inputs.version || github.ref_name, 'rc') || contains(github.event.inputs.version || github.ref_name, 'beta') || contains(github.event.inputs.version || github.ref_name, 'alpha') }}

.github/workflows/release-rcs.yml

@@ -17,17 +17,17 @@ jobs:
       packages: write
 
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2, 2026-04-25
+      - uses: actions/checkout@v4
 
       - name: Login to GHCR
-        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3, 2026-04-25
+        uses: docker/login-action@v3
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3, 2026-04-25
+        uses: docker/setup-buildx-action@v3
 
       - name: Extract version
         id: version
@@ -47,7 +47,7 @@ jobs:
           echo "tags=$TAGS" >> "$GITHUB_OUTPUT"
 
       - name: Build Docker image
-        uses: docker/build-push-action@ca052bb54ab0790a636c9b5f226502c73d547a25 # v5, 2026-04-25
+        uses: docker/build-push-action@v5
         with:
           context: .
           file: packages/remote-control-server/Dockerfile

.github/workflows/update-contributors.yml

@@ -1,8 +1,11 @@
 name: Update Contributors
 
 on:
+  push:
+    branches:
+      - main
   schedule:
-    - cron: '0 0 * * 1'  # 每周一更新一次
+    - cron: '0 0 * * *'  # 每天更新一次
 
 permissions:
   contents: write
@@ -11,17 +14,17 @@ jobs:
   update:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2, 2026-04-25
+      - uses: actions/checkout@v4
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
 
-      - uses: jaywcjlove/github-action-contributors@86707f6d4c2469ce6b46bc3367253ebd41ee242c # main, 2026-04-25
+      - uses: jaywcjlove/github-action-contributors@main
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           output: "contributors.svg"
           repository: ${{ github.repository }}
 
-      - uses: stefanzweifel/git-auto-commit-action@b863ae1933cb653a53c021fe36dbb774e1fb9403 # v5, 2026-04-25
+      - uses: stefanzweifel/git-auto-commit-action@v5
         with:
           commit_message: "docs: update contributors"
           file_pattern: "contributors.svg"

.gitignore

@@ -5,8 +5,7 @@ coverage
 .env
 *.log
 .idea
-.vscode/*
+.vscode
-!.vscode/extensions.json
 *.suo
 *.lock
 src/utils/vendor/
@@ -20,11 +19,6 @@ src/utils/vendor/
 /*.png
 *.bmp
 
-# Internal system prompt documents
-Claude-Opus-*.txt
-Claude-Sonnet-*.txt
-Claude-Haiku-*.txt
-
 # Agent / tool state dirs
 .swarm/
 .agents/__pycache__/
@@ -44,15 +38,3 @@ data
 .codex/skills/.system/**
 !.codex/prompts/
 !.codex/prompts/**
-teach-me
-credentials.json
-
-# Session-scoped progress / state files written by agents and skills
-# (autofix-pr persistence, test-progress checkpoint, recovery notes).
-# Transient, never meant to enter the repo.
-.claude-impl-state.md
-.claude-progress.md
-.claude-recovery.md
-.test-progress.md
-.squash-tmp/
-.git.*-backup

.husky/pre-commit

@@ -1 +0,0 @@
-npx lint-staged

.tool-versions

@@ -1 +0,0 @@
-bun 1.3.13

.vscode/extensions.json

@@ -1,8 +0,0 @@
-{
-  "recommendations": [
-    "biomejs.biome",
-    "ms-typescript.typescript",
-    "oven.bun-vscode",
-    "editorconfig.editorconfig"
-  ]
-}

AGENTS.md

@@ -1,357 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) and other AI coding agents when working with code in this repository.
-
-## 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. TypeScript strict mode is enforced — **`bunx tsc --noEmit` must pass with zero errors**.
-
-## Git Commit Message Convention
-
-使用 **Conventional Commits** 规范：
-
-```
-<type>: <描述>
-```
-
-常见 type：`feat`、`fix`、`docs`、`chore`、`refactor`
-
-示例：
-- `feat: 添加模型 1M 上下文切换`
-- `fix: 修复初次登陆的校验问题`
-- `chore: remove prefetchOfficialMcpUrls call on startup`
-
-## Commands
-
-```bash
-# Install dependencies
-bun install
-
-# Dev mode (runs cli.tsx with MACRO defines injected via -d flags)
-bun run dev
-
-# Dev mode with debugger (set BUN_INSPECT=9229 to pick port)
-bun run dev:inspect
-
-# Pipe mode
-echo "say hello" | bun run src/entrypoints/cli.tsx -p
-
-# 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 src/utils/__tests__/hash.test.ts   # run single file
-bun test --coverage                         # with coverage report
-
-# Lint & Format (Biome)
-bun run lint              # check only
-bun run lint:fix          # auto-fix
-bun run format            # format all src/
-
-# Health check
-bun run health
-
-# Check unused exports
-bun run check:unused
-
-# Full check (typecheck + lint + test) — run after completing any task
-bun run test:all
-bun run typecheck
-
-# Remote Control Server
-bun run rcs
-
-# Docs dev server (Mintlify)
-bun run docs:dev
-```
-
-详细的测试规范、覆盖状态和改进计划见 `docs/testing-spec.md`。
-
-## Architecture
-
-### 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。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 — 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()` 函数按优先级处理多条快速路径：
-   - `--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` / `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`** (~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
-
-- **`src/query.ts`** — The main API query function. Sends messages to Claude API, handles streaming responses, processes tool calls, and manages the conversation turn loop.
-- **`src/QueryEngine.ts`** — Higher-level orchestrator wrapping `query()`. Manages conversation state, compaction, file history snapshots, attribution, and turn-level bookkeeping. Used by the REPL screen.
-- **`src/screens/REPL.tsx`** — The interactive REPL screen (React/Ink component). Handles user input, message display, tool permission prompts, and keyboard shortcuts.
-
-### 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.
-- **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; 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 等
-- **`src/tools/shared/`** / **`packages/builtin-tools/src/tools/shared/`** — Tool 共享工具函数。
-
-### UI Layer (Ink)
-
-- **`src/ink.ts`** — Ink render wrapper with ThemeProvider injection.
-- **`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
-  - `permissions/` — Tool permission approval UI
-  - `design-system/` — 复用 UI 组件（Dialog, FuzzyPicker, ProgressBar, ThemeProvider 等）
-- Components use React Compiler runtime (`react/compiler-runtime`) — decompiled output has `_c()` memoization calls throughout.
-
-### State Management
-
-- **`src/state/AppState.tsx`** — Central app state type and context provider. Contains messages, tools, permissions, MCP connections, etc.
-- **`src/state/AppStateStore.ts`** — Default state and store factory.
-- **`src/state/store.ts`** — Zustand-style store for AppState (`createStore`).
-- **`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/` | 键盘修饰键检测（macOS FFI 实现） |
-| `packages/url-handler-napi/` | URL scheme 处理（环境变量 + CLI 参数读取） |
-
-### Bridge / Remote Control
-
-- **`src/bridge/`** — 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
-
-- **`src/daemon/`** — Daemon 模式（长驻 supervisor）。feature-gated by `DAEMON`。包含 `main.ts`（entry）和 `workerRegistry.ts`（worker 管理）。
-
-### Context & System Prompt
-
-- **`src/context.ts`** — Builds system/user context for the API call (git status, date, CLAUDE.md contents, memory files).
-- **`src/utils/claudemd.ts`** — Discovers and loads CLAUDE.md files from project hierarchy.
-
-### Feature Flag System
-
-Feature flags control which functionality is enabled at runtime. 代码中统一通过 `import { feature } from 'bun:bundle'` 导入，调用 `feature('FLAG_NAME')` 返回 `boolean`。
-
-**启用方式**: 环境变量 `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 兼容层
-
-所有兼容层均采用流适配器模式：将第三方 API 格式转为 Anthropic 内部格式，下游代码完全不改。通过 `/login` 命令配置。
-
-#### OpenAI 兼容层
-
-通过 `CLAUDE_CODE_USE_OPENAI=1` 启用，支持 Ollama/DeepSeek/vLLM 等任意 OpenAI Chat Completions 协议端点。含 DeepSeek thinking mode 支持。
-
-- **`src/services/api/openai/`** — client、消息/工具转换、流适配、模型映射
-- 关键环境变量：`CLAUDE_CODE_USE_OPENAI`、`OPENAI_API_KEY`、`OPENAI_BASE_URL`、`OPENAI_MODEL`
-
-#### Gemini 兼容层
-
-通过 `CLAUDE_CODE_USE_GEMINI=1` 启用。独立环境变量体系。
-
-- **`src/services/api/gemini/`** — client、模型映射、类型定义
-- 关键环境变量：`GEMINI_API_KEY`（必填）、`GEMINI_MODEL`（直接指定）、`GEMINI_DEFAULT_SONNET_MODEL`/`GEMINI_DEFAULT_OPUS_MODEL`（按能力映射）
-- 模型映射优先级：`GEMINI_MODEL` > `GEMINI_DEFAULT_*_MODEL` > `ANTHROPIC_DEFAULT_*_MODEL`(已废弃) > 原样返回
-
-#### Grok 兼容层
-
-通过 `CLAUDE_CODE_USE_GROK=1` 启用。自定义模型映射支持 xAI Grok API。
-
-- **`src/services/api/grok/`** — client、模型映射
-
-详见各兼容层的 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 — macOS + Windows + Linux（后端完整度不一） |
-| `*-napi` packages | 全部已恢复/实现：`audio-capture-napi`、`image-processor-napi` 已恢复；`color-diff-napi` 完整；`modifiers-napi`（macOS FFI）；`url-handler-napi`（环境变量+CLI） |
-| 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 | Restored — Magic Docs 自动更新 + LSP 服务器管理器 |
-| Plugins / Marketplace | Restored — 插件安装/卸载/启用/禁用 + Marketplace 浏览 |
-| MCP OAuth | Simplified |
-
-### Key Type Files
-
-- **`src/types/global.d.ts`** — Declares `MACRO`, `BUILD_TARGET`, `BUILD_ENV` and internal Anthropic-only identifiers.
-- **`src/types/internal-modules.d.ts`** — Type declarations for `bun:bundle`, `bun:ffi`, `@anthropic-ai/mcpb`.
-- **`src/types/message.ts`** — Message type hierarchy (UserMessage, AssistantMessage, SystemMessage, etc.).
-- **`src/types/permissions.ts`** — Permission mode and result types.
-
-## Testing
-
-- **框架**: `bun:test`（内置断言 + mock）
-- **单元测试**: 就近放置于 `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")`，英文
-- **包测试**: `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`、第三方网络库。
-
-**`log.ts` 和 `debug.ts` 使用共享 mock**（`tests/mocks/log.ts` / `tests/mocks/debug.ts`），不要在测试文件中内联 mock 定义。使用方式：
-
-```ts
-import { logMock } from "../../../tests/mocks/log";
-mock.module("src/utils/log.ts", logMock);
-
-import { debugMock } from "../../../../tests/mocks/debug";
-mock.module("src/utils/debug.ts", debugMock);
-```
-
-源文件导出变更时只需更新 `tests/mocks/` 下的对应文件，不需要逐个修改测试。
-
-不要 mock：纯函数模块（`errors.ts`、`stringUtils.js`）、mock 值与真实实现相同的模块、mock 路径与实际 import 不匹配的模块。
-
-路径规则：统一用 `.ts` 扩展名 + `src/*` 别名路径，禁止双重 mock 同一模块。
-
-### 类型检查
-
-项目使用 TypeScript strict 模式，**tsc 必须零错误**。每次修改后运行：
-
-```bash
-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
-
-- **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 内置模块，由运行时/构建器解析。不要用自定义函数替代它。**`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 产品常见的设计套路（渐变文字、玻璃态、霓虹色）。

CLAUDE.md

@@ -1,10 +1,10 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) and other AI coding agents when working with code in this repository.
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
 ## 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. TypeScript strict mode is enforced — **`bun run precheck` 必须零错误通过**（包含 typecheck + lint fix + test）。
+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
 
@@ -43,16 +43,14 @@ bun run build
 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
+bun test --coverage       # with coverage report
 
-# Lint & Format (Biome) — 日常开发用 precheck 代替单独调用
+# Lint & Format (Biome)
-bun run lint              # lint check (全项目)
+bun run lint              # check only
-bun run lint:fix          # auto-fix lint issues
+bun run lint:fix          # auto-fix
-bun run format            # format all (全项目)
+bun run format            # format all src/
-bun run check             # lint + format check (全项目)
-bun run check:fix         # lint + format auto-fix
 
 # Health check
 bun run health
@@ -60,8 +58,7 @@ bun run health
 # Check unused exports
 bun run check:unused
 
-# Full check (typecheck + lint fix + test) — 任务完成后必须运行
+bun run typecheck
-bun run precheck
 
 # Remote Control Server
 bun run rcs
@@ -70,29 +67,24 @@ bun run rcs
 bun run docs:dev
 ```
 
-详细的测试规范、覆盖状态和改进计划见 `src/**/__tests__/` 与 `tests/integration/`。
+详细的测试规范、覆盖状态和改进计划见 `docs/testing-spec.md`。
 
 ## Architecture
 
 ### 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。Build 默认启用 19 个 feature（见下方 Feature Flag 段）。构建后自动替换 `import.meta.require` 为 Node.js 兼容版本（产物 bun/node 都可运行）。构建时会将 `vendor/audio-capture/` 和 `src/utils/vendor/ripgrep/` 复制到 `dist/vendor/` 下。
+- **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 都可运行）。
-- **Build (Vite)**: `vite.config.ts` + `scripts/post-build.ts`，代码分割模式，chunk 输出到 `dist/chunks/`。post-build 遍历 `dist/` 和 `dist/chunks/` 下所有 `.js` 文件做 `globalThis.Bun` 解构 patch，复制 vendor 文件到 `dist/vendor/`。
-- **Vendor 路径解析**: 构建后 chunk 文件位于 `dist/` 或 `dist/chunks/` 下，vendor 二进制在 `dist/vendor/`。`src/utils/distRoot.ts` 提供共享的 `distRoot` 函数，通过 `import.meta.url` 路径中 `lastIndexOf('dist')` 或 `lastIndexOf('src')` 定位根目录。`ripgrep.ts`、`computerUse/setup.ts`、`claudeInChrome/setup.ts`、`updateCCB.ts` 均使用 `distRoot` 而非内联 `import.meta.url` 路径推算。`packages/audio-capture-napi/src/index.ts` 有独立的 `lastIndexOf('dist')` 逻辑，功能等价。
-- **为什么 Vite 必须代码分割**: Bun/JSC 会全量解析单个大 JS 文件的 bytecode 和 JIT，单文件 17MB 产物导致 RSS 暴涨至 ~1GB（Node/V8 懒解析仅需 ~220MB）。代码分割为 600+ 小 chunk 后 Bun 按需加载，`--version` RSS 从 966MB 降至 35MB，完整加载从 1GB+ 降至 ~500MB。
 - **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 — 17 个 workspace packages + 若干辅助目录 in `packages/` resolved via `workspace:*`。
+- **Monorepo**: Bun workspaces — 15 个 workspace packages + 若干辅助目录 in `packages/` resolved via `workspace:*`。
-- **Lint/Format**: Biome (`biome.json`)。覆盖 `src/`、`scripts/`、`packages/` 全项目（含 `packages/@ant/`）。`bun run lint` / `bun run lint:fix` / `bun run format` / `bun run check` / `bun run check:fix`。42 条规则因 decompiled 代码被关闭，仅保留 `recommended` 基线。
+- **Lint/Format**: Biome (`biome.json`)。`bun run lint` / `bun run lint:fix` / `bun run format`。
-- **Pre-commit**: husky + lint-staged。提交时自动对暂存文件执行 `biome check --fix`（TS/JS）和 `biome format --write`（JSON）。
+- **Defines**: 集中管理在 `scripts/defines.ts`。当前版本 `2.1.888`。
-- **CI Lint**: `ci.yml` 在依赖安装后、类型检查前执行 `bunx biome ci .`，lint 或格式化不达标则 CI 失败。
+- **CI**: GitHub Actions — `ci.yml`（构建+测试）、`release-rcs.yml`（RCS 发布）、`update-contributors.yml`（自动更新贡献者）。
-- **Defines**: 集中管理在 `scripts/defines.ts`。当前版本 `2.2.1`。
-- **CI**: GitHub Actions — `ci.yml`（lint + 构建 + 测试）、`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`
@@ -105,7 +97,7 @@ bun run docs:dev
    - `environment-runner` / `self-hosted-runner` — BYOC runner
    - `--tmux` + `--worktree` 组合
    - 默认路径：加载 `main.tsx` 启动完整 CLI
-2. **`src/main.tsx`** (~5674 行) — 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
@@ -123,19 +115,15 @@ bun run docs:dev
 ### Tool System
 
 - **`src/Tool.ts`** — Tool interface definition (`Tool` type) and utilities (`findToolByName`, `toolMatchesName`).
-- **`src/tools.ts`** — 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`.
+- **`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`.
-- **`src/constants/tools.ts`** — `CORE_TOOLS` 白名单常量（38 个核心工具名），用于 `isDeferredTool` 白名单制判定。
+- **`packages/builtin-tools/src/tools/`** — 59 个子目录（含 shared/testing 等工具目录），通过 `@claude-code-best/builtin-tools` 包导出。主要分类：
-- **`packages/builtin-tools/src/tools/`** — 60 个工具目录（含 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
-  - **工具发现**: SearchExtraToolsTool, ExecuteExtraTool, SyntheticOutput（CORE_TOOLS，用于延迟工具按需加载）
   - **其他**: LSPTool, ConfigTool, SkillTool, EnterWorktreeTool, ExitWorktreeTool 等
-- **`src/tools/shared/`** / **`packages/builtin-tools/src/tools/shared/`** — Tool 共享工具函数。
-- **`src/services/searchExtraTools/`** — TF-IDF 工具索引模块（`toolIndex.ts`），为延迟工具提供语义搜索能力。复用 `localSearch.ts` 的 TF-IDF 算法函数（`computeWeightedTf`、`computeIdf`、`cosineSimilarity` 已导出）。修改这些函数时需同步检查工具索引测试。`prefetch.ts` 的 `extractQueryFromMessages` 复用了 `skillSearch/prefetch.ts` 的同名导出函数，修改 skill prefetch 的该函数时需同步检查工具预取行为。工具预取使用独立的 `discoveredToolsThisSession` Set，与 skill prefetch 的去重集合互不影响。
 
 ### UI Layer (Ink)
 
@@ -170,23 +158,25 @@ bun run docs:dev
 | `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/` | 键盘修饰键检测（macOS FFI 实现） |
+| `packages/modifiers-napi/` | 键盘修饰键检测（stub） |
-| `packages/url-handler-napi/` | URL scheme 处理（环境变量 + CLI 参数读取） |
+| `packages/url-handler-napi/` | URL scheme 处理（stub） |
-| `packages/weixin/` | 微信集成（非 workspace 包） |
-
-辅助目录（无 package.json，非 workspace 包）: `langfuse-dashboard`（Langfuse 面板）、`shared-web-ui`（共享 Web UI 组件）、`highlight-code`（代码高亮）、`claude-pencil`（编辑器）、`vscode-ide-bridge`（VS Code 桥接）、`pokemon`（示例/测试）。
 
 ### Bridge / Remote Control
 
-- **`src/bridge/`** — 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/modes/remote-control-self-hosting.md`。
+- 详见 `docs/features/remote-control-self-hosting.md`。
 
 ### ACP Protocol (Agent Client Protocol)
 
@@ -210,18 +200,12 @@ Feature flags control which functionality is enabled at runtime. 代码中统一
 
 **启用方式**: 环境变量 `FEATURE_<FLAG_NAME>=1`。例如 `FEATURE_BUDDY=1 bun run dev`。
 
-**Build 默认 features**（65+ 个，见 `build.ts` 中 `DEFAULT_BUILD_FEATURES`）:
+**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`, `ACP`
+- P2: `DAEMON`
-- 工作流: `WORKFLOW_SCRIPTS`, `HISTORY_SNIP`, `MONITOR_TOOL`, `KAIROS`
-- 多 worker: `COORDINATOR_MODE`, `BG_SESSIONS`, `TEMPLATES`
-- 连接器: `CONNECTOR_TEXT`, `COMMIT_ATTRIBUTION`, `DIRECT_CONNECT`
-- 实验性: `EXPERIMENTAL_SKILL_SEARCH`, `EXPERIMENTAL_SEARCH_EXTRA_TOOLS`
-- 模式: `POOR`, `SSH_REMOTE`
-- 已禁用: `CONTEXT_COLLAPSE`, `FORK_SUBAGENT`, `UDS_INBOX`, `LAN_PIPES`, `REVIEW_ARTIFACT`, `TEAMMEM`, `SKILL_LEARNING`
 
 **Dev mode 默认**: 全部启用（见 `scripts/dev.ts`）。
 
@@ -231,30 +215,7 @@ Feature flags control which functionality is enabled at runtime. 代码中统一
 
 ### Multi-API 兼容层
 
-所有兼容层均采用流适配器模式：将第三方 API 格式转为 Anthropic 内部格式，下游代码完全不改。通过 `/login` 命令配置。
+支持 OpenAI、Gemini、Grok 三种第三方 API，通过 `/login` 命令配置，均采用流适配器模式转为 Anthropic 内部格式。详见各兼容层的 docs 文档。
-
-#### OpenAI 兼容层
-
-通过 `CLAUDE_CODE_USE_OPENAI=1` 启用，支持 Ollama/DeepSeek/vLLM 等任意 OpenAI Chat Completions 协议端点。含 DeepSeek thinking mode 支持。
-
-- **`src/services/api/openai/`** — client、消息/工具转换、流适配、模型映射
-- 关键环境变量：`CLAUDE_CODE_USE_OPENAI`、`OPENAI_API_KEY`、`OPENAI_BASE_URL`、`OPENAI_MODEL`
-
-#### Gemini 兼容层
-
-通过 `CLAUDE_CODE_USE_GEMINI=1` 启用。独立环境变量体系。
-
-- **`src/services/api/gemini/`** — client、模型映射、类型定义
-- 关键环境变量：`GEMINI_API_KEY`（必填）、`GEMINI_MODEL`（直接指定）、`GEMINI_DEFAULT_SONNET_MODEL`/`GEMINI_DEFAULT_OPUS_MODEL`（按能力映射）
-- 模型映射优先级：`GEMINI_MODEL` > `GEMINI_DEFAULT_*_MODEL` > `ANTHROPIC_DEFAULT_*_MODEL`(已废弃) > 原样返回
-
-#### Grok 兼容层
-
-通过 `CLAUDE_CODE_USE_GROK=1` 启用。自定义模型映射支持 xAI Grok API。
-
-- **`src/services/api/grok/`** — client、模型映射
-
-详见各兼容层的 docs 文档。
 
 ### 穷鬼模式（Budget Mode）
 
@@ -267,14 +228,13 @@ Feature flags control which functionality is enabled at runtime. 代码中统一
 | Module | Status |
 |--------|--------|
 | Computer Use (`@ant/*`) | Restored — macOS + Windows + Linux（后端完整度不一） |
-| `*-napi` packages | 全部已恢复/实现：`audio-capture-napi`、`image-processor-napi` 已恢复；`color-diff-napi` 完整；`modifiers-napi`（macOS FFI）；`url-handler-napi`（环境变量+CLI） |
+| `*-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 |
-| `packages/shell/`, `packages/swarm/`, `packages/mcp-server/`, `packages/cc-knowledge/` | Removed — 功能合并或废弃 |
 | Analytics / GrowthBook / Sentry | Empty implementations |
-| Magic Docs / LSP Server | Restored — Magic Docs 自动更新 + LSP 服务器管理器 |
+| Magic Docs / LSP Server | Removed |
-| Plugins / Marketplace | Restored — 插件安装/卸载/启用/禁用 + Marketplace 浏览 |
+| Plugins / Marketplace | Removed |
 | MCP OAuth | Simplified |
 
 ### Key Type Files
@@ -287,8 +247,9 @@ Feature flags control which functionality is enabled at runtime. 代码中统一
 ## Testing
 
 - **框架**: `bun:test`（内置断言 + mock）
+- **当前状态**: 3175 tests / 207 files / 0 fail
 - **单元测试**: 就近放置于 `src/**/__tests__/`，文件名 `<module>.test.ts`
-- **集成测试**: `tests/integration/` — 6 个文件（cli-arguments, context-build, message-pipeline, tool-chain, autonomy-lifecycle-user-flow, dependency-overrides）
+- **集成测试**: `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")`，英文
 - **包测试**: `packages/` 下各包也有独立测试（如 `color-diff-napi` 11 tests）
@@ -299,70 +260,16 @@ Feature flags control which functionality is enabled at runtime. 代码中统一
 
 被迫 mock 的根源：`log.ts` / `debug.ts` → `bootstrap/state.ts`（模块级 `realpathSync` / `randomUUID` 副作用）。必须 mock 的模块：`log.ts`、`debug.ts`、`bun:bundle`、`settings/settings.js`、`config.ts`、`auth.ts`、第三方网络库。
 
-**`log.ts` 和 `debug.ts` 使用共享 mock**（`tests/mocks/log.ts` / `tests/mocks/debug.ts`），不要在测试文件中内联 mock 定义。使用方式：
-
-```ts
-import { logMock } from "../../../tests/mocks/log";
-mock.module("src/utils/log.ts", logMock);
-
-import { debugMock } from "../../../../tests/mocks/debug";
-mock.module("src/utils/debug.ts", debugMock);
-```
-
-源文件导出变更时只需更新 `tests/mocks/` 下的对应文件，不需要逐个修改测试。
-
 不要 mock：纯函数模块（`errors.ts`、`stringUtils.js`）、mock 值与真实实现相同的模块、mock 路径与实际 import 不匹配的模块。
 
 路径规则：统一用 `.ts` 扩展名 + `src/*` 别名路径，禁止双重 mock 同一模块。
 
-#### 跨文件 mock 污染（process-global `mock.module`）
-
-**Bun 的 `mock.module` 是进程全局的（last-write-wins），不是 per-file 隔离的。** 一个测试文件的 `mock.module` 会污染同一进程中所有其他测试文件的 `require`/`import`。
-
-**关键事实（Bun 1.x 实测验证）：**
-- 测试文件执行顺序**不是严格字母序**，不要假设文件 A 一定在文件 B 之前执行。
-- `mock.module` 在 `beforeAll` 内部调用时**不会被提升**（hoist），但仍会污染后续加载的文件。
-- `require()` 和 `import()` 共享同一模块注册表，`mock.module` 对两者都生效。
-- 一个模块一旦被某个文件的 `mock.module` 替换，同一进程中所有后续 `require`/`import` 都会返回 mock 值，即使调用方使用不同的 specifier 路径。
-
-**核心规则：不要 mock 被测模块的上层业务模块。**
-
-错误做法（会污染同目录的 `api.test.ts`）：
-```ts
-// launchSchedule.test.ts — 直接 mock 源 API 模块 ❌
-mock.module('src/commands/schedule/triggersApi.js', () => ({
-  listTriggers: listTriggersMock,
-  // ...
-}))
-```
-
-正确做法（mock 底层 HTTP 层，不污染业务模块）：参考 `launchSkillStore.test.ts`、`launchVault.test.ts` 的模式。
-```ts
-// launchSchedule.test.ts — mock axios 而非 triggersApi ✅
-import { setupAxiosMock } from '../../../../tests/mocks/axios.js'
-
-const axiosHandle = setupAxiosMock()
-axiosHandle.stubs.get = axiosGetMock
-axiosHandle.stubs.post = axiosPostMock
-
-beforeAll(() => { axiosHandle.useStubs = true })
-afterAll(() => { axiosHandle.useStubs = false })
-```
-
-**判断标准：** 如果目录下同时有 `launch*.test.ts`（集成测试）和 `api.test.ts`（回归测试），`launch*.test.ts` 必须 mock axios 而非源 API 模块。`api.test.ts` 需要测试真实 API 模块的 HTTP 方法/URL/错误处理逻辑，被 mock 后就无法测试。
-
-**排查 mock 污染的方法：**
-1. 单独运行可疑文件确认其通过：`bun test path/to/suspect.test.ts`
-2. 与同目录其他文件一起运行定位污染源：`bun test path/to/__tests__/`
-3. 在两个文件中各加 `console.error('[file] milestone')` 追踪实际执行顺序
-4. 检查 `mock.module` 的 specifier 是否与同目录其他测试的 `require`/`import` 路径解析到同一模块
-
 ### 类型检查
 
 项目使用 TypeScript strict 模式，**tsc 必须零错误**。每次修改后运行：
 
 ```bash
-bun run precheck
+bun run typecheck          # equivalent to bun run typecheck
 ```
 
 **类型规范**：
@@ -375,16 +282,14 @@ bun run precheck
 
 ## Working with This Codebase
 
-- **precheck must pass** — `bun run precheck`（typecheck + lint fix + test）必须零错误，任何修改都不能引入新的类型/lint/测试错误。
+- **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 内置模块，由运行时/构建器解析。不要用自定义函数替代它。**`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 配置** — 42 条 lint 规则因 decompiled 代码被关闭，仅保留 `recommended` 基线。格式化覆盖全项目（`src/`、`scripts/`、`packages/`，含 `packages/@ant/`）。`.tsx` 文件用 120 行宽 + 强制分号；其他文件 80 行宽 + 按需分号。JSON 格式化已启用。`.editorconfig` 与 Biome 配置对齐（2-space 缩进）。修改任何代码后应运行 `bun run precheck` 确认无类型/lint/格式/测试问题，pre-commit hook 会自动拦截不合格提交。
+- **Biome 配置** — 大量 lint 规则被关闭（decompiled 代码不适合严格 lint）。`.tsx` 文件用 120 行宽 + 强制分号；其他文件 80 行宽 + 按需分号。
-- **tsc 与 Biome 冲突处理** — 当 tsc 要求声明属性（赋值使用）但 biome 报 `noUnusedPrivateClassMembers`（只写不读）时，用 `// biome-ignore lint/correctness/noUnusedPrivateClassMembers: <原因>` 抑制 lint 警告，保留类型声明。`biome ci` 必须零 warnings。
-- **`@ts-expect-error` 维护** — 只在下方代码确实有类型错误时保留 `@ts-expect-error`。如果类型系统已更新导致 directive 变为 unused（TS2578），直接移除注释。MACRO 替换产生的永假比较（如 `'production' === 'development'`）仍需保留 `@ts-expect-error`。
 - **Ink 框架在 `packages/@ant/ink/`** — 不是 `src/ink/`（该目录不存在）。Ink 相关的组件、hooks、keybindings 都在 packages 中。
 - **Provider 优先级** — `modelType` 参数 > 环境变量 > 默认 `firstParty`。新增 provider 需在 `src/utils/model/providers.ts` 注册。
 

README.md

@@ -10,33 +10,32 @@
 
 > Which Claude do you like? The open source one is the best.
 
-牢 A (Anthropic) 官方 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 完整复原的工程化项目。虽然很难绷, 但是它叫做 CCB(踩踩背)... 而且, 我们实现了企业版或者需要登陆 Claude 账号才能使用的特性, 并在此基础上扩展了更多好玩的特性。
+牢 A (Anthropic) 官方 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI 工具的源码反编译/逆向还原项目。目标是将 Claude Code 大部分功能及工程化能力复现 (问就是老佛爷已经付过钱了)。虽然很难绷, 但是它叫做 CCB(踩踩背)... 而且, 我们实现了企业版或者需要登陆 Claude 账号才能使用的特性, 实现技术普惠
 
-[Peri Code](https://github.com/KonghaYao/peri)：Claude Code 兼容的 Rust Agent，多年大模型经验匠心制作，国内大模型（DeepSeek/GLM）精调，CPU/内存极致优化，在开发版/树莓派上也能跑 CC 一样的体验。
+[文档在这里, 支持投稿 PR](https://ccb.agent-aura.top/) | [留影文档在这里](./Friends.md) | [Discord 群组](https://discord.gg/uApuzJWGKX)
 
-[文档在这里](https://ccb.agent-aura.top/) | [留影文档在这里](./Friends.md) | [Discord 群组，群主在线答疑](https://discord.gg/uApuzJWGKX)
+| 特性 | 说明 | 文档 |
+|------|------|------|
+| **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) |
 
-| 特性                        | 说明                                                                                                                         | 文档                                                                                                                                      |
+- 🚀 [想要启动项目](#快速开始源码版)
-| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| **Claude 群控技术**         | Pipe IPC 多实例协作：同机 main/sub 自动编排 + LAN 跨机器零配置发现与通讯，`/pipes` 选择面板 + `Shift+↓` 交互 + 消息广播路由 | [Pipe IPC](https://ccb.agent-aura.top/docs/features/agents/uds-inbox) / [LAN](https://ccb.agent-aura.top/docs/features/agents/lan-pipes)                |
-| **ACP 协议一等一支持**      | 支持接入 Zed、Cursor 等 IDE，支持会话恢复、Skills、权限桥接                                                                  | [文档](https://ccb.agent-aura.top/docs/features/agents/acp-zed)                                                                                  |
-| **Remote Control 私有部署** | Docker 自托管远程界面, 可以手机上看 CC                                                                                       | [文档](https://ccb.agent-aura.top/docs/features/modes/remote-control-self-hosting)                                                              |
-| **Langfuse 监控**           | 企业级 Agent 监控, 可以清晰看到每次 agent loop 细节, 可以一键转化为数据集                                                    | [文档](https://ccb.agent-aura.top/docs/features/tools/langfuse-monitoring)                                                                      |
-| **Web Search**              | 内置网页搜索工具, 支持 bing 和 brave 搜索                                                                                    | [文档](https://ccb.agent-aura.top/docs/features/external/web-browser-tool)                                                                         |
-| **Poor Mode**               | 穷鬼模式，关闭记忆提取和键入建议,大幅度减少并发请求                                                                          | /poor 可以开关                                                                                                                            |
-| **Channels 频道通知**       | MCP 服务器推送外部消息到会话（飞书/Slack/Discord/微信等），`--channels plugin:name@marketplace` 启用                         | [文档](https://ccb.agent-aura.top/docs/features/external/channels)                                                                                 |
-| **自定义模型供应商**        | OpenAI/Anthropic/Gemini/Grok 兼容  (`/login`)                                                                                          | [文档](https://ccb.agent-aura.top/docs/getting-started/model-providers)                                                                        |
-| Voice Mode                  | 语音输入，支持豆包语言输入（`/voice doubao`）                                                                   | [文档](https://ccb.agent-aura.top/docs/features/external/voice-mode)                                                                               |
-| Computer Use                | 屏幕截图、键鼠控制                                                                                                           | [文档](https://ccb.agent-aura.top/docs/features/external/computer-use)                                                                             |
-| Chrome Use                  | 浏览器自动化、表单填写、数据抓取                                                                                             | [自托管](https://ccb.agent-aura.top/docs/features/external/chrome-use-mcp) [原生版](https://ccb.agent-aura.top/docs/features/external/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/modes/auto-dream)                                                                               |
-
-- 🚀 [想要启动项目](#-快速开始源码版)
 - 🐛 [想要调试项目](#vs-code-调试)
 - 📖 [想要学习项目](#teach-me-学习项目)
 
+
 ## ⚡ 快速开始(安装版)
 
 不用克隆仓库, 从 NPM 下载后, 直接使用
@@ -46,16 +45,13 @@ npm i -g claude-code-best
 
 # bun 安装比较多问题, 推荐 npm 装
 # bun  i -g claude-code-best
-# bun pm -g trust claude-code-best @claude-code-best/mcp-chrome-bridge
+# bun pm -g trust claude-code-best
 
 ccb # 以 nodejs 打开 claude code
 ccb-bun # 以 bun 形态打开
-ccb update # 更新到最新版本
 CLAUDE_BRIDGE_BASE_URL=https://remote-control.claude-code-best.win/ CLAUDE_BRIDGE_OAUTH_TOKEN=test-my-key ccb --remote-control # 我们有自部署的远程控制
 ```
 
-> **安装/更新失败？** 先 `npm rm -g claude-code-best` 清理旧版本，再 `npm i -g claude-code-best@latest`。仍失败则指定版本号：`npm i -g claude-code-best@<版本号>`
-
 ## ⚡ 快速开始(源码版)
 
 ### ⚙️ 环境要求
@@ -63,66 +59,11 @@ CLAUDE_BRIDGE_BASE_URL=https://remote-control.claude-code-best.win/ CLAUDE_BRIDG
 一定要最新版本的 bun 啊, 不然一堆奇奇怪怪的 BUG!!! bun upgrade!!!
 
 - 📦 [Bun](https://bun.sh/) >= 1.3.11
-
-**安装 Bun：**
-
-```bash
-# Linux 和 macOS
-curl -fsSL https://bun.sh/install | bash
-
-# Windows (PowerShell)
-powershell -c "irm bun.sh/install.ps1 | iex"
-```
-
-**安装后的操作：**
-
-1. **让当前终端识别 `bun` 命令**
-
-   安装脚本会把 `~/.bun/bin` 写入对应的 shell 配置文件。macOS 默认 zsh 环境通常会看到：
-
-   ```text
-   Added "~/.bun/bin" to $PATH in "~/.zshrc"
-   ```
-
-   可以按安装脚本提示重启当前 shell：
-
-   ```bash
-   exec /bin/zsh
-   ```
-
-   如果你使用 bash，重新加载 bash 配置：
-
-   ```bash
-   source ~/.bashrc
-   ```
-
-   Windows PowerShell 用户关闭并重新打开 PowerShell 即可。
-
-2. **验证 Bun 是否可用**
-
-   ```bash
-   bun --help
-   bun --version
-   ```
-
-3. **如果已经安装过 Bun，更新到最新版本**
-
-   ```bash
-   bun upgrade
-   ```
-
 - ⚙️ 常规的配置 CC 的方式, 各大提供商都有自己的配置方式
 
-### 📍 命令执行位置
-
-- 安装或检查 Bun 的命令可以在任意目录执行：
-  `curl -fsSL https://bun.sh/install | bash`、`bun --help`、`bun --version`、`bun upgrade`
-- 安装本项目依赖、启动开发模式、构建项目时，必须先进入本仓库根目录，也就是包含 `package.json` 的目录。
-
 ### 📥 安装
 
 ```bash
-cd /path/to/claude-code
 bun install
 ```
 
@@ -149,16 +90,17 @@ bun run build
 
 需要填写的字段：
 
-| 📌 字段      | 📝 说明       | 💡 示例                      |
+| 📌 字段 | 📝 说明 | 💡 示例 |
-| ------------ | ------------- | ---------------------------- |
+|------|------|------|
-| Base URL     | API 服务地址  | `https://api.example.com/v1` |
+| Base URL | API 服务地址 | `https://api.example.com/v1` |
-| API Key      | 认证密钥      | `sk-xxx`                     |
+| API Key | 认证密钥 | `sk-xxx` |
-| Haiku Model  | 快速模型 ID   | `claude-haiku-4-5-20251001`  |
+| Haiku Model | 快速模型 ID | `claude-haiku-4-5-20251001` |
-| Sonnet Model | 均衡模型 ID   | `claude-sonnet-4-6`          |
+| Sonnet Model | 均衡模型 ID | `claude-sonnet-4-6` |
-| Opus Model   | 高性能模型 ID | `claude-opus-4-6`            |
+| Opus Model | 高性能模型 ID | `claude-opus-4-6` |
 
 - ⌨️ **Tab / Shift+Tab** 切换字段，**Enter** 确认并跳到下一个，最后一个字段按 Enter 保存
 
+
 > ℹ️ 支持所有 Anthropic API 兼容服务（如 OpenRouter、AWS Bedrock 代理等），只要接口兼容 Messages API 即可。
 
 ## Feature Flags
@@ -178,17 +120,16 @@ TUI (REPL) 模式需要真实终端，无法直接通过 VS Code launch 启动
 ### 步骤
 
 1. **终端启动 inspect 服务**：
-
    ```bash
    bun run dev:inspect
    ```
-
    会输出类似 `ws://localhost:8888/xxxxxxxx` 的地址。
-2. **VS Code 附着调试器**：
 
+2. **VS Code 附着调试器**：
    - 在 `src/` 文件中打断点
    - F5 → 选择 **"Attach to Bun (TUI debug)"**
 
+
 ## Teach Me 学习项目
 
 我们新加了一个 teach-me skills, 通过问答式引导帮你理解这个项目的任何模块。(调整 [sigma skill 而来](https://github.com/sanyuan0704/sanyuan-skills))
@@ -215,7 +156,7 @@ TUI (REPL) 模式需要真实终端，无法直接通过 VS Code launch 启动
 ## 相关文档及网站
 
 - **在线文档（Mintlify）**: [ccb.agent-aura.top](https://ccb.agent-aura.top/) — 文档源码位于 [`docs/`](docs/) 目录，欢迎投稿 PR
-- **DeepWiki**: [https://deepwiki.com/claude-code-best/claude-code](https://deepwiki.com/claude-code-best/claude-code)
+- **DeepWiki**: <https://deepwiki.com/claude-code-best/claude-code>
 
 ## Contributors
 
@@ -233,10 +174,6 @@ TUI (REPL) 模式需要真实终端，无法直接通过 VS Code launch 启动
  </picture>
 </a>
 
-## 致谢
-
-- [doubaoime-asr](https://github.com/starccy/doubaoime-asr) — 豆包 ASR 语音识别 SDK，为 Voice Mode 提供无需 Anthropic OAuth 的语音输入方案
-
 ## 许可证
 
 本项目仅供学习研究用途。Claude Code 的所有权利归 [Anthropic](https://www.anthropic.com/) 所有。

README_EN.md

@@ -48,64 +48,11 @@ Sponsor placeholder.
 Make sure you're on the latest version of Bun, otherwise you'll run into all sorts of weird bugs. Run `bun upgrade`!
 
 - [Bun](https://bun.sh/) >= 1.3.11
-
-**Install Bun:**
-
-```bash
-# Linux and macOS
-curl -fsSL https://bun.sh/install | bash
-
-# Windows (PowerShell)
-powershell -c "irm bun.sh/install.ps1 | iex"
-```
-
-**Post-installation steps:**
-
-1. **Make `bun` available in the current terminal**
-
-   The installer adds `~/.bun/bin` to the matching shell configuration file. On macOS with the default zsh shell, you may see:
-
-   ```text
-   Added "~/.bun/bin" to $PATH in "~/.zshrc"
-   ```
-
-   Restart the current shell as the installer suggests:
-
-   ```bash
-   exec /bin/zsh
-   ```
-
-   If you use bash, reload the bash configuration:
-
-   ```bash
-   source ~/.bashrc
-   ```
-
-   Windows PowerShell users can close and reopen PowerShell.
-
-2. **Verify that Bun is available:**
-   ```bash
-   bun --help
-   bun --version
-   ```
-
-3. **Update to latest version (if already installed):**
-   ```bash
-   bun upgrade
-   ```
-
 - Standard Claude Code configuration — each provider has its own setup method
 
-### Command Execution Location
-
-- Bun installation and checking commands can be run from any directory:
-  `curl -fsSL https://bun.sh/install | bash`, `bun --help`, `bun --version`, `bun upgrade`
-- Project dependency installation, development mode, and builds must be run from this repository root, the directory containing `package.json`.
-
 ### Install
 
 ```bash
-cd /path/to/claude-code
 bun install
 ```
 
@@ -188,7 +135,7 @@ The TUI (REPL) mode requires a real terminal and cannot be launched directly via
 ## Documentation & Links
 
 - **Online docs (Mintlify)**: [ccb.agent-aura.top](https://ccb.agent-aura.top/) — source in [`docs/`](docs/), PR contributions welcome
-- **DeepWiki**: https://deepwiki.com/claude-code-best/claude-code
+- **DeepWiki**: <https://deepwiki.com/claude-code-best/claude-code>
 
 ## Contributors
 

biome.json

@@ -1,118 +1,114 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.4.12/schema.json",
+	"$schema": "https://biomejs.dev/schemas/2.4.10/schema.json",
-  "vcs": {
+	"vcs": {
-    "enabled": true,
+		"enabled": true,
-    "clientKind": "git",
+		"clientKind": "git",
-    "useIgnoreFile": true
+		"useIgnoreFile": true
-  },
+	},
-  "files": {
+	"files": {
-    "includes": [
+		"includes": ["**", "!!**/dist", "!!**/packages/@ant"]
-      "**",
+	},
-      "!!**/dist",
+	"formatter": {
-      "!!**/.claude/workflows",
+		"enabled": true,
-      "!!**/*.workflow.mjs"
+		"indentStyle": "space",
-    ]
+		"indentWidth": 2,
-  },
+		"lineWidth": 80
-  "formatter": {
+	},
-    "enabled": true,
+	"linter": {
-    "indentStyle": "space",
+		"enabled": true,
-    "indentWidth": 2,
+		"rules": {
-    "lineWidth": 80
+			"recommended": true,
-  },
+			"suspicious": {
-  "linter": {
+				"noExplicitAny": "off",
-    "enabled": true,
+				"noAssignInExpressions": "off",
-    "rules": {
+				"noDoubleEquals": "off",
-      "recommended": true,
+				"noRedeclare": "off",
-      "suspicious": {
+				"noImplicitAnyLet": "off",
-        "noExplicitAny": "off",
+				"noGlobalIsNan": "off",
-        "noAssignInExpressions": "off",
+				"noFallthroughSwitchClause": "off",
-        "noDoubleEquals": "off",
+				"noShadowRestrictedNames": "off",
-        "noRedeclare": "off",
+				"noArrayIndexKey": "off",
-        "noImplicitAnyLet": "off",
+				"noConsole": "off",
-        "noGlobalIsNan": "off",
+				"noConfusingLabels": "off",
-        "noFallthroughSwitchClause": "off",
+				"useIterableCallbackReturn": "off"
-        "noShadowRestrictedNames": "off",
+			},
-        "noArrayIndexKey": "off",
+			"style": {
-        "noConsole": "off",
+				"useConst": "off",
-        "noConfusingLabels": "off",
+				"noNonNullAssertion": "off",
-        "useIterableCallbackReturn": "off"
+				"noParameterAssign": "off",
-      },
+				"useDefaultParameterLast": "off",
-      "style": {
+				"noUnusedTemplateLiteral": "off",
-        "useConst": "off",
+				"useTemplate": "off",
-        "noNonNullAssertion": "off",
+				"useNumberNamespace": "off",
-        "noParameterAssign": "off",
+				"useNodejsImportProtocol": "off",
-        "useDefaultParameterLast": "off",
+				"useImportType": "off"
-        "noUnusedTemplateLiteral": "off",
+			},
-        "useTemplate": "off",
+			"complexity": {
-        "useNumberNamespace": "off",
+				"noForEach": "off",
-        "useNodejsImportProtocol": "off",
+				"noBannedTypes": "off",
-        "useImportType": "off"
+				"noUselessConstructor": "off",
-      },
+				"noStaticOnlyClass": "off",
-      "complexity": {
+				"useOptionalChain": "off",
-        "noForEach": "off",
+				"noUselessSwitchCase": "off",
-        "noBannedTypes": "off",
+				"noUselessFragments": "off",
-        "noUselessConstructor": "off",
+				"noUselessTernary": "off",
-        "noStaticOnlyClass": "off",
+				"noUselessLoneBlockStatements": "off",
-        "useOptionalChain": "off",
+				"noUselessEmptyExport": "off",
-        "noUselessSwitchCase": "off",
+				"useArrowFunction": "off",
-        "noUselessFragments": "off",
+				"useLiteralKeys": "off"
-        "noUselessTernary": "off",
+			},
-        "noUselessLoneBlockStatements": "off",
+			"correctness": {
-        "noUselessEmptyExport": "off",
+				"noUnusedVariables": "off",
-        "useArrowFunction": "off",
+				"noUnusedImports": "off",
-        "useLiteralKeys": "off"
+				"useExhaustiveDependencies": "off",
-      },
+				"noSwitchDeclarations": "off",
-      "correctness": {
+				"noUnreachable": "off",
-        "noUnusedVariables": "off",
+				"useHookAtTopLevel": "off",
-        "noUnusedImports": "off",
+				"noVoidTypeReturn": "off",
-        "useExhaustiveDependencies": "off",
+				"noConstantCondition": "off",
-        "noSwitchDeclarations": "off",
+				"noUnusedFunctionParameters": "off"
-        "noUnreachable": "off",
+			},
-        "useHookAtTopLevel": "off",
+			"a11y": {
-        "noVoidTypeReturn": "off",
+				"recommended": false
-        "noConstantCondition": "off",
+			},
-        "noUnusedFunctionParameters": "off"
+			"nursery": {
-      },
+				"recommended": false
-      "a11y": {
+			}
-        "recommended": false
+		}
-      },
+	},
-      "nursery": {
+	"json": {
-        "recommended": false
+		"formatter": {
-      }
+			"enabled": false
-    }
+		}
-  },
+	},
-  "json": {
+	"javascript": {
-    "formatter": {
+		"formatter": {
-      "enabled": true
+			"quoteStyle": "single",
-    }
+			"semicolons": "asNeeded",
-  },
+			"arrowParentheses": "asNeeded",
-  "css": {
+			"trailingCommas": "all"
-    "parser": {
+		}
-      "tailwindDirectives": true
+	},
-    }
+	"overrides": [
-  },
+		{
-  "javascript": {
+			"includes": ["**/*.tsx"],
-    "formatter": {
+			"javascript": {
-      "quoteStyle": "single",
+				"formatter": {
-      "semicolons": "asNeeded",
+					"semicolons": "always"
-      "arrowParentheses": "asNeeded",
+				}
-      "trailingCommas": "all"
+			},
-    }
+			"formatter": {
-  },
+				"lineWidth": 120
-  "overrides": [
+			}
-    {
+		},
-      "includes": ["**/*.tsx"],
+		{
-      "javascript": {
+			"includes": ["scripts/**", "packages/**", "**/*.js", "**/*.mjs", "**/*.jsx"],
-        "formatter": {
+			"formatter": {
-          "semicolons": "always"
+				"enabled": false
-        }
+			}
-      },
+		}
-      "formatter": {
+	],
-        "lineWidth": 120
+	"assist": {
-      }
+		"enabled": false
-    }
+	}
-  ],
-  "assist": {
-    "enabled": false
-  }
 }

build.ts

@@ -1,7 +1,6 @@
 import { readdir, readFile, writeFile, cp } from 'fs/promises'
 import { join } from 'path'
 import { getMacroDefines } from './scripts/defines.ts'
-import { DEFAULT_BUILD_FEATURES } from './scripts/defines.ts'
 
 const outdir = 'dist'
 
@@ -9,6 +8,48 @@ const outdir = 'dist'
 const { rmSync } = await import('fs')
 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',
+  'AGENT_TRIGGERS_REMOTE',
+  'CHICAGO_MCP',
+  'VOICE_MODE',
+  'SHOT_STATS',
+  'PROMPT_CACHE_BREAK_DETECTION',
+  'TOKEN_BUDGET',
+  // P0: local features
+  'AGENT_TRIGGERS',
+  'ULTRATHINK',
+  'BUILTIN_EXPLORE_PLAN_AGENTS',
+  'LODESTONE',
+  // P1: API-dependent features
+  'EXTRACT_MEMORIES',
+  'VERIFICATION_AGENT',
+  'KAIROS_BRIEF',
+  'AWAY_SUMMARY',
+  '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
 const envFeatures = Object.keys(process.env)
   .filter(k => k.startsWith('FEATURE_'))
@@ -21,14 +62,7 @@ const result = await Bun.build({
   outdir,
   target: 'bun',
   splitting: true,
-  sourcemap: 'linked',
+  define: getMacroDefines(),
-  define: {
-    ...getMacroDefines(),
-    // React production mode — eliminates _debugStack Error objects
-    // (6,889 objects × ~1.7KB = 12MB in development builds) and removes
-    // prop-type / key warnings not useful in a production CLI tool.
-    'process.env.NODE_ENV': JSON.stringify('production'),
-  },
   features,
 })
 
@@ -63,8 +97,7 @@ for (const file of files) {
 // (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 =
+const BUN_DESTRUCTURE_SAFE = 'var {$1} = typeof globalThis.Bun !== "undefined" ? globalThis.Bun : {};'
-  'var {$1} = typeof globalThis.Bun !== "undefined" ? globalThis.Bun : {};'
 for (const file of files) {
   if (!file.endsWith('.js')) continue
   const filePath = join(outdir, file)
@@ -83,14 +116,10 @@ console.log(
   `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) and vendored binaries (ripgrep)
+// Step 4: Copy native .node addon files (audio-capture)
-const audioCaptureDir = join(outdir, 'vendor', 'audio-capture')
+const vendorDir = join(outdir, 'vendor', 'audio-capture')
-await cp('vendor/audio-capture', audioCaptureDir, { recursive: true })
+await cp('vendor/audio-capture', vendorDir, { recursive: true })
-console.log(`Copied vendor/audio-capture/ → ${audioCaptureDir}/`)
+console.log(`Copied vendor/audio-capture/ → ${vendorDir}/`)
-
-const ripgrepDir = join(outdir, 'vendor', 'ripgrep')
-await cp('src/utils/vendor/ripgrep', ripgrepDir, { recursive: true })
-console.log(`Copied src/utils/vendor/ripgrep/ → ${ripgrepDir}/`)
 
 // Step 5: Generate cli-bun and cli-node executable entry points
 const cliBun = join(outdir, 'cli-bun.js')

codecov.yml

@@ -1,51 +0,0 @@
-coverage:
-  status:
-    project:
-      default:
-        target: auto
-        threshold: 1%
-    patch:
-      default:
-        target: 100%
-        only_pulls: true
-
-ignore:
-  - "**/*.tsx"
-  # parseArgs has 3 defensive `/* istanbul ignore next */` checks that are
-  # structurally unreachable (guaranteed by upstream invariants). Bun's
-  # coverage doesn't honor istanbul comments, so we ignore the file at
-  # codecov level — covered logic has 59/62 lines hit.
-  - "src/commands/agents-platform/parseArgs.ts"
-  # resumeAgent's patch lines (1 import + 1 call to filterParentToolsForFork)
-  # require the full async-agent orchestration chain (registerAsyncAgent,
-  # assembleToolPool, runAgent, sessionStorage, agentContext, cwd-override,
-  # 15+ deps) to spawn a "resumed fork" context. Mocking all of them just to
-  # exercise one line is heavy and brittle. Verified 1/2 of patch lines hit
-  # already (the import); the call site is covered by integration tests
-  # outside the unit-test scope.
-  - "packages/builtin-tools/src/tools/AgentTool/resumeAgent.ts"
-  - "**/*.test.ts"
-  - "**/*.test.tsx"
-  - "**/__tests__/**"
-  - "tests/**"
-  - "scripts/**"
-  - "docs/**"
-  - "packages/@ant/ink/**"
-  - "packages/@ant/computer-use-mcp/**"
-  - "packages/@ant/computer-use-input/**"
-  - "packages/@ant/computer-use-swift/**"
-  - "packages/@ant/claude-for-chrome-mcp/**"
-  - "packages/audio-capture-napi/**"
-  - "packages/color-diff-napi/**"
-  - "packages/image-processor-napi/**"
-  - "packages/modifiers-napi/**"
-  - "packages/url-handler-napi/**"
-  - "packages/remote-control-server/web/**"
-  - "src/types/**"
-  - "**/*.d.ts"
-  - "build.ts"
-  - "vite.config.ts"
-
-comment:
-  layout: "diff,flags,files"
-  require_changes: false

docs-outline-draft.md

@@ -1,688 +0,0 @@
-# Claude Code（反编译重建版）文档大纲
-
-这份文档分两个视角并行展开：**产品文档**面向"想让工具跑起来并融入日常工作流"的使用者，按用户旅程组织；**开发者设计探秘**面向想理解内部原理、挖掘决策背后动机的工程师，按"被约束逼出的设计链"组织。两者覆盖同一套代码，但章节切分、措辞、锚点指向各不相同，让不同读者按自己的路径进入。
-
----
-
-## 第一部分：产品文档大纲（使用者视角）
-
-按"安装 → 配置 → 日常 → 扩展 → 进阶 → 排错"线性旅程组织。每章标题呼应用户想做什么，而非工具有什么。
-
-### 1. 第一章：从零开始 —— 安装、首次启动与环境要求
-
-章节摘要：把工具装到本机，跑通第一次对话。覆盖 Bun 运行时、Node.js 兼容产物、dev/build 两种使用方式，以及首次启动的信任对话框与初始化流程。
-
-子章节：
-
-- 我需要先装什么？Bun 与 Node.js 的取舍
-- 三种安装方式：`bun run dev`、构建产物 `dist/cli.js`、Vite 构建链
-- 第一次启动会发生什么：trust dialog、init 流程、telemetry 询问
-- 快速路径命令一览（`--version` / `-v` / `--help`）
-- 把 `claude` 设为全局命令：`cli-bun.js` 与 `cli-node.js` 双入口
-- 环境自检：`bun run health` 与 `claude doctor`
-
-锚点：
-- `docs/getting-started/installation.mdx`
-- `docs/getting-started/quickstart.mdx`
-- `src/entrypoints/cli.tsx`、`src/entrypoints/init.ts`
-- `build.ts`、`scripts/dev.ts`
-- 命令：`bun run dev` / `bun run build` / `bun run health` / `claude doctor` / `claude --version`
-
-### 2. 第二章：让 Claude 听你的 —— 配置 Provider 与模型
-
-章节摘要：回答"我用哪家 API？"这个最高频问题。覆盖 7 个 Provider 的切换方式、引导式登录、环境变量清单，以及"为什么我切了 Provider 没生效"和"我改了 key 为什么没生效"两个高频排错。
-
-子章节：
-
-- 一张表看懂 7 个 Provider：Anthropic / OpenAI 兼容 / Gemini / Grok / Bedrock / Vertex / Foundry
-- 三种切换方式：`/provider` 命令、`/login` 引导式登录、`CLAUDE_CODE_USE_*` 环境变量
-- 中国 LLM 引导式登录：DeepSeek / 智谱 GLM / 通义千问 / Moonshot / Cerebras / Groq
-- 用 ChatGPT 订阅当后端：`OPENAI_AUTH_MODE=chatgpt` 的设备码流程、`~/.claude/openai-chatgpt-auth.json` 凭证存储、与 Codex CLI 跨工具共享 `~/.codex/auth.json`、5 分钟刷新偏差窗口
-- 每个 Provider 的 key 配置清单（`OPENAI_API_KEY` / `GEMINI_API_KEY` / `GROK_API_KEY` 或 `XAI_API_KEY` / `AWS_REGION` / `ANTHROPIC_VERTEX_PROJECT_ID` / `ANTHROPIC_FOUNDRY_*`）
-- 模型映射是怎么决定的：`PROVIDER_MODEL` > `PROVIDER_DEFAULT_{FAMILY}_MODEL` > `ANTHROPIC_DEFAULT_*` > 默认表
-- 为什么切了 Provider 没生效？`modelType` 优先级、`/provider unset` 只清 Provider 不清 key、`isFirstPartyAnthropicBaseUrl()` TODO 陷阱（只设 `OPENAI_BASE_URL` 没设 `ANTHROPIC_BASE_URL` 会让 firstParty 行为泄漏）
-- **我改了 API key 但没生效？** —— 模块级 client cache 陷阱：`getOpenAIClient()`/`getGrokClient()` 会话级缓存客户端实例，中途改 key 必须重启或调用 `clearOpenAIClientCache()`
-- 本地模型与自托管端点：Ollama / vLLM / DeepSeek 自托管
-- DeepSeek 思维模式自动检测与三格式注入；为什么必须回显 `reasoning_content: ''`（空字符串），否则下一次请求会被 400 拒绝
-- `/effort` 与 `CLAUDE_CODE_EFFORT_LEVEL` 的取值语义：`low` / `medium` / `high` / `xhigh` 四档，以及它在 ChatGPT Responses API 上如何落地为 `reasoning.effort` 参数
-
-锚点：
-- `docs/getting-started/model-providers.mdx`
-- `src/commands/provider.ts`、`src/commands/login/login.tsx`
-- `src/components/ConsoleOAuthFlow.tsx`、`src/utils/chinaLlmProviders.ts`
-- `src/utils/model/providers.ts`
-- `src/services/api/openai/`、`src/services/api/gemini/`、`src/services/api/grok/`
-- `src/services/api/openai/client.ts:39`（`getOpenAIClient` 模块级缓存）
-- `src/services/api/openai/responsesAdapter.ts`（Responses API 适配器）
-- `src/services/api/client.ts`（`isFirstPartyAnthropicBaseUrl` 陷阱）
-- `src/services/providerUsage/adapters/openai.ts:62`（限流响应头解析）
-- 命令：`/provider <name>` / `/provider unset` / `/login` / `/model` / `/effort`
-
-### 3. 第三章：日常对话 —— 交互式 REPL 怎么用
-
-章节摘要：装好之后每天打开 `claude` 会做什么。覆盖发消息、看流式回复、中断、恢复会话、切模型、切权限模式、查看 token 消耗等高频日常操作。
-
-子章节：
-
-- 发消息、看流式回复、Esc 中断、Ctrl+C 退出
-- 会话怎么持久化：恢复上一次对话（`/resume`）、查看历史（`/history`）、清空上下文（`/clear`）
-- 切换模型与思考强度：`/model`、`/effort`（low/medium/high/xhigh）、ultrathink 触发词
-- 权限模式：默认询问 / 自动批准 / 全部拒绝 / sandbox 切换
-- 看 token 与费用：`/cost`、`/usage`、`/stats`、状态栏显示
-- 上下文管理与自动压缩：`/compact`、自动 compact 触发条件、`/force-snip` 强制剪裁
-- 把对话导出与分享：`/export`、`/share`、`/summary`，各自的产物格式与隐私边界（谁会看到什么、是否包含凭证）
-- 更换主题、输出风格、语言：`/theme`、`/output-style`、`/lang`
-- 配置项目记忆：CLAUDE.md 与 `@include` 指令、`/memory` 命令
-
-锚点：
-- `src/screens/REPL.tsx`、`src/query.ts`、`src/QueryEngine.ts`、`src/context.ts`、`src/utils/claudemd.ts`
-- `src/commands/clear/`、`compact/`、`cost/`、`usage/`、`history/`、`resume/`、`model/`、`effort/`、`mode/`、`memory/`、`export/`、`share/`、`theme/`
-- 命令：`claude` / `claude -p '...'` / `claude --resume`
-
-### 4. 第四章：slash 命令速查 —— 不用记全部，按场景找
-
-章节摘要：把上百个 slash 命令按"我想做什么"分类，让用户能快速找到自己需要的那一个，而不是背诵命令清单。
-
-子章节：
-
-- 会话与上下文类：`/clear` `/compact` `/resume` `/history` `/context` `/rewind` `/force-snip`
-- 模型与 Provider 类：`/model` `/provider` `/effort` `/login` `/logout`
-- 费用与限额类：`/cost` `/usage` `/stats` `/rate-limit-options`（待核实是否存在） `/reset-limits`（待核实是否存在）；实际机制是通过响应头 `x-ratelimit-*-requests/tokens` 与 `Reset-After` 自动追踪限流
-- 配置与个性化类：`/theme` `/output-style` `/lang` `/keybindings` `/config` `/env`
-- 项目与文件类：`/add-dir` `/files` `/diff` `/context` `/ctx_viz`
-- 插件与扩展类：`/plugin` `/skills` `/skill-store` `/reload-plugins` `/hooks`
-- 工作流自动化类：`/commit` `/commit-push-pr` `/review` `/plan` `/schedule` `/loop`
-- 诊断与帮助类：`/help` `/doctor` `/status` `/version` `/feedback`
-- 隐藏与实验类：`/bughunter` `/advisor` `/insights` `/thinkback` `/torch`
-
-锚点：
-- `src/commands/`、`src/commands/help/`、`doctor/`、`config/`、`env/`
-- 命令：`/help` / `claude <cmd> --help`
-- 注意：`/rate-limit-options` 与 `/reset-limits` 在 findings 中没有对应锚点，应标记为"待核实是否存在"，或替换为已验证的"通过响应头追踪限流"机制
-
-### 5. 第五章：扩展 Claude 的能力 —— MCP Server、插件、Skill
-
-章节摘要：当内置工具不够用时怎么办。覆盖接入现成 MCP server、自己写一个、安装社区插件、用 Skill 沉淀工作流。
-
-子章节：
-
-- MCP 是什么？什么时候应该用 MCP 而不是普通工具
-- 用 `claude mcp add` 接入现成 MCP server（stdio / SSE / HTTP）
-- 管理已接入的 server：`claude mcp list` / `remove` / `serve`
-- MCP OAuth 简化流程与认证（`/mcp-auth`）
-- 自己写一个 MCP server 的最小骨架
-- Computer Use / Chrome 控制 / 语音输入这些内置 MCP 怎么开
-- 插件系统：`/plugin` 浏览、安装、启用、禁用、卸载
-- Marketplace 浏览与插件市场
-- Skill 是什么？`/skills` 与 `/skill-store` 的区别
-- 怎么写一个自己的 Skill 并复用
-- Skill 搜索与延迟工具加载：SearchExtraTools 与 ExecuteExtraTool
-
-锚点：
-- `docs/features/tools/`
-- `docs/features/external/chrome-control.md`、`computer-use.md`、`voice-mode.md`、`web-browser-tool.md`
-- `src/commands/mcp/`、`plugin/`、`skills/`、`skill-store/`、`skill-search/`
-- `src/services/searchExtraTools/`
-- `packages/@ant/computer-use-mcp/`、`packages/@ant/claude-for-chrome-mcp/`
-- 命令：`claude mcp add/list/remove/serve` / `/plugin` / `/skills` / `/skill-store`
-
-### 6. 第六章：让 Claude 帮你跑大任务 —— 子代理、Plan 模式、Task 系统
-
-章节摘要：当任务超过单次对话、需要并行或分阶段执行时怎么办。覆盖 Agent 工具、Task 系统、Plan 模式、worktree 隔离。
-
-子章节：
-
-- 什么时候该派子代理？单线程 vs 并行 vs 分阶段
-- Agent 工具：在对话里 spawn 一个子代理处理子任务
-- Task 系统：TaskCreate / TaskUpdate / TaskList / TaskGet 管理任务清单
-- Plan 模式：先想清楚再动手（`/plan`、EnterPlanMode、ExitPlanModeV2、VerifyPlanExecution）
-- Goal 命令：给定目标后让 Claude 自主推进（`/goal`）
-- Worktree 隔离：在独立 git worktree 里跑实验性改动
-- Coordinator 模式：多 worker 协作（`COORDINATOR_MODE` feature）
-- Workflow 脚本：把多步工作流固化成可重放脚本（`/workflows`）
-- Ultra-batch 与 dispatching-parallel-agents Skill 的取舍
-
-锚点：
-- `docs/features/agents/`
-- `packages/agent-tools/`
-- `packages/builtin-tools/src/tools/AgentTool/`、`TaskCreateTool/`、`EnterPlanModeTool/`、`EnterWorktreeTool/`
-- `src/commands/plan/`、`goal/`、`workflows/`、`coordinator.ts`
-- Skill：ultra-batch / dispatching-parallel-agents / experiment-driven-research
-
-### 7. 第七章：让 Claude 长时间帮你干活 —— Daemon、Background Sessions、Schedule
-
-章节摘要：当任务需要小时级持续运行、定时触发、或后台并行多个会话时怎么办。覆盖 daemon 模式、bg sessions、cron/schedule、loop。
-
-子章节：
-
-- Daemon 是什么？跟普通 REPL 的区别（长驻 supervisor + worker）
-- 启停 daemon：`claude daemon start/stop/bg/attach/logs/kill/status`
-- `--daemon-worker=<kind>` 精简 worker 的用途
-- Background Sessions：`claude --bg` / `claude ps` / `claude attach` / `claude kill`
-- Template Jobs：`claude job new/list/reply` 模板化任务
-- 定时调度：`/schedule` 创建远程 cron 触发器、`/loop` 本地循环、`cron-list` / `cron-delete`
-- 用 `/loop` 让 Claude 每 N 分钟自动跑一次任务
-- Schedule 触发器与 RCS 的关系
-- 什么时候该用 daemon，什么时候用 background session，什么时候用 schedule
-
-锚点：
-- `src/daemon/`、`src/commands/daemon/`、`attach/`、`tasks/`、`job/`、`schedule/`、`loop`
-- Skill：loop / cron-list / cron-delete / schedule
-- 命令：`claude daemon <subcmd>` / `claude --bg` / `claude ps` / `claude attach` / `claude kill`
-
-### 8. 第八章：跨机器与跨团队协作 —— Bridge、Remote Control、ACP
-
-章节摘要：当 Claude 需要跑在远程机器、被外部客户端调用、或接入 IDE/团队工具时怎么办。覆盖 Bridge 模式、自托管 RCS、ACP 协议、IDE 桥接。
-
-子章节：
-
-- Bridge 模式是什么？什么时候启用（`BRIDGE_MODE` feature）
-- Remote Control 快速路径：`claude remote-control` / `rc` / `remote` / `sync` / `bridge`
-- 自托管 RCS：Docker 部署、Web UI 控制面板、`bun run rcs`
-- RCS Web UI：会话管理、ACP agent 接入、SSE 事件流
-- ACP 协议：把 Claude Code 暴露成 ACP agent（`claude --acp`）
-- ACP 权限管道与 `session/update` plan 可视化
-- acp-link：WebSocket 客户端桥接到 ACP agent
-- IDE 桥接：VS Code 集成（`vscode-ide-bridge/`、`/ide` 命令）
-- SSH 远程模式：`SSH_REMOTE` feature 与 `/remote-setup`、`/remote-env`
-- 与 Codex CLI 跨工具凭证共享（`~/.codex/auth.json`、`~/.claude/openai-chatgpt-auth.json`）
-
-锚点：
-- `docs/features/modes/remote-control-self-hosting.md`
-- `docs/features/agents/acp.md`、`pipes-and-lan.md`
-- `src/bridge/`、`src/services/acp/`
-- `packages/remote-control-server/`、`packages/acp-link/`、`vscode-ide-bridge/`
-- `src/commands/bridge/`、`remoteControlServer/`、`remote-setup/`、`remote-env/`、`ide/`
-- 命令：`claude remote-control` / `claude rc` / `claude bridge` / `claude --acp` / `bun run rcs`
-
-### 9. 第九章：省钱、提速、定制 —— 穷鬼模式、缓存、Hooks、配置文件
-
-章节摘要：当 token 账单偏高、响应偏慢、或想让 Claude 自动响应某些事件时怎么办。覆盖穷鬼模式、prompt 缓存、hooks、settings.json、keybindings，以及权限规则写作指南。
-
-子章节：
-
-- 穷鬼模式（`/poor`）：跳过 `extract_memories` / `prompt_suggestion` / `verification_agent`，对各 Provider 都生效（含兼容层），持久化到 `settings.json`
-- Prompt 缓存怎么工作？缓存断点检测（`PROMPT_CACHE_BREAK_DETECTION`）
-- Token 预算管理：`TOKEN_BUDGET` feature 与 `/cost` 联动
-- Hooks：在 `settings.json` 里写"每次 X 发生就执行 Y"
-- `settings.json` vs `settings.local.json`：团队共享 vs 个人覆盖
-- CLAUDE.md 四层层级与优先级：Managed / User / Project / Local
-- `@include` 指令：在 CLAUDE.md 里引用其他文件
-- `keybindings.json`：自定义快捷键与 chord
-- **权限规则配置指南**：`allow` / `deny` 规则的具体语法（含工具名匹配、glob 模式、规则优先级）、`/permissions` 命令、沙箱模式与 `bypassPermissions` 在非 root/sandbox 环境的可用性检测
-- Feature flag 运行时开关：`FEATURE_<NAME>=1`，以及已知禁用清单（`CONTEXT_COLLAPSE` / `HISTORY_SNIP` / `FORK_SUBAGENT` / `UDS_INBOX` / `LAN_PIPES` / `REVIEW_ARTIFACT` / `SKILL_LEARNING` / `TEAMMEM`）与启用后果
-
-锚点：
-- `src/commands/poor/poorMode.ts`
-- `src/commands/hooks/`、`permissions/`、`config/`、`keybindings/`
-- `src/utils/claudemd.ts`、`src/context.ts`
-- Skill：update-config / keybindings-help
-- 命令：`/poor` / `/hooks` / `/config` / `/permissions` / `/env`
-
-### 10. 第十章：可观测性与排错 —— 卡住了怎么办
-
-章节摘要：当 Claude 报错、卡住、行为异常或想理解它在做什么时怎么办。覆盖 doctor、debug、日志、Langfuse 追踪、常见错误对照表。
-
-子章节：
-
-- 第一步永远先跑：`claude doctor` 与 `bun run health`
-- **Provider 报错对照表**：401（key 无效） / 403（地区限制） / 429（限流，看 `x-ratelimit-*` 头与 `Reset-After`） / `overloaded_error`（1305 / 上游过载） / 模型不存在
-- OpenAI/Gemini/Grok 兼容层特有坑：模型映射失败（Gemini 硬抛异常）、`reasoning_content` 缺失导致 DeepSeek 400、限流响应头解析
-- Bedrock Opus 4.7 的 400 错误与 `anthropic_beta` 体剥离补丁：何时打、SDK 升级后如何通过 `scripts/probe-bedrock-beta-fix.ts` 检测是否还需要
-- MCP server 连不上：stdio 路径、SSE 超时、OAuth 失败排查清单
-- 权限被拒、工具被禁用、deferred tool 没加载
-- 内存膨胀与长会话：`performanceShim`、`clearMarks`、`/compact`、`/force-snip`
-- 调试模式：`BUN_INSPECT=<port>`、`--dump-system-prompt`、`/debug-tool-call`
-- Langfuse 追踪：每次查询的 `provider` 字段（`openai` / `gemini` / `grok` / `getAPIProvider()`）与 `recordLLMObservation`
-- 导出会话给同事看：`/export`、`/share`、`/recap` 的产物格式与隐私边界
-- 反馈与上报 bug：`/feedback`、`/perf-issue`、`/bughunter`
-- 已知禁用的 feature flag 清单与启用后果
-
-锚点：
-- `docs/features/tools/langfuse-monitoring.md`
-- `src/commands/doctor/`、`debug-tool-call/`、`feedback/`、`perf-issue/`、`heapdump/`
-- `src/utils/performanceShim.ts`
-- `src/services/api/bedrockClient.ts:29`
-- `src/services/providerUsage/adapters/openai.ts:62`
-- `scripts/probe-bedrock-beta-fix.ts`
-- 命令：`claude doctor` / `bun run health` / `BUN_INSPECT=9229 bun run dev:inspect` / `claude --dump-system-prompt`
-
-### 11. 第十一章：自动化与 CI 集成 —— 把 Claude 嵌入流水线
-
-章节摘要：当想在 CI、脚本、cron、容器里无交互调用 Claude 时怎么办。覆盖 pipe 模式、headless、BYOC runner、容器环境变量、与 ACP/Bridge 的交汇点。
-
-子章节：
-
-- Pipe 模式：`echo '...' | claude -p` 一次性调用
-- Headless 模式：无 TTY 环境下的行为差异
-- **BYOC runner**：`claude environment-runner` / `claude self-hosted-runner`（与第八章 ACP、Bridge 的交汇点）
-- 容器环境：`CLAUDE_CODE_REMOTE=true` 自动调内存上限（`--max-old-space-size=8192`）
-- `CLAUDE_CODE_FORCE_INTERACTIVE`：嵌套 bun 启动的 TTY 欺骗
-- `CLAUDE_CODE_ABLATION_BASELINE`：L0 消融基线的用途
-- 在 GitHub Actions 里跑 claude（`install-github-app`、`subscribe-pr`、`commit-push-pr`）
-- 定时任务：用 `/schedule` 或 cron + pipe 实现巡检
-- 退出码与 `pipe-status`：脚本里判断成功失败
-
-锚点：
-- `src/entrypoints/cli.tsx`
-- `src/commands/pipe-status/`、`install-github-app/`、`subscribe-pr/`、`commit-push-pr.ts`
-- 命令：`claude -p` / `claude environment-runner` / `claude self-hosted-runner` / `claude --bg`
-
-### 12. 第十二章：进阶实验性能力与社区生态
-
-章节摘要：给愿意折腾的用户一张"还能玩什么"的地图。覆盖实验 feature、buddy、监控、advisor、teleport 等小众但强大的命令。
-
-子章节：
-
-- 实验性 feature flag 速览：`BUDDY` / `KAIROS` / `LODESTONE` / `ULTRAPLAN` / `MONITOR_TOOL`
-- Skill 搜索实验：`EXPERIMENTAL_SKILL_SEARCH` / `EXPERIMENTAL_SEARCH_EXTRA_TOOLS`（编译进 build，运行时默认 OFF，`SKILL_SEARCH_ENABLED=1` 开启）
-- Buddy 协作与 `/buddy` 命令
-- Kairos 简报与 `/brief`、Away Summary、`/recap`
-- Advisor、insights、thinkback：让 Claude 反思自己的输出
-- Teleport 与 pipes：跨会话消息传递
-- Local vault 与 memory stores：长期记忆的多后端
-- TUI 实验、stickers、output-style 自定义
-- 贡献者生态：`/feedback`、GitHub issues、`bun run docs:dev` 本地起文档站
-
-锚点：
-- `src/commands/buddy/`、`brief.ts`、`recap/`、`advisor.ts`、`insights.ts`、`thinkback/`、`teleport/`、`pipes/`、`local-vault/`、`memory-stores/`、`tui/`、`stickers/`、`output-style/`
-- 命令：`bun run docs:dev` / `FEATURE_<NAME>=1 bun run dev`
-
-### 13. 第十三章：安全 —— 凭证、权限、刷新、共享（交叉补充）
-
-章节摘要：当前两份大纲都没有连贯的安全章节。把凭证存储、权限模式、OAuth 刷新、跨工具凭证共享集中讲清楚，让用户知道自己的密钥和令牌去了哪里。
-
-子章节：
-
-- 凭证存储位置清单：`~/.claude/`、`~/.claude/openai-chatgpt-auth.json`、`~/.codex/auth.json`、`~/.claude.json`、`settings.json` / `settings.local.json`
-- OAuth 设备码流程：ChatGPT 订阅路径与 Anthropic OAuth 各自的设备码握手
-- OAuth 令牌自动刷新的 5 分钟偏差窗口
-- 权限模式语义：默认询问 / 自动批准 / 全部拒绝 / sandbox / `bypassPermissions`（非 root/sandbox 环境检测）
-- JWT 认证（Bridge 模式）：token 签发、传输、回收
-- `/share` 与 `/export` 的隐私边界：哪些字段会泄漏、是否包含凭证、给同事前要做什么
-- 跨工具凭证共享的隐私影响：Codex CLI 共享 `~/.codex/auth.json` 的含义
-
-锚点：
-- `src/commands/login/login.tsx`
-- `src/services/api/openai/chatgptAuth.ts:327`
-- `src/components/ConsoleOAuthFlow.tsx:1294`
-- `src/commands/permissions/`、`share/`、`export/`
-- `src/services/acp/permissions.ts`
-
----
-
-## 第二部分：开发者设计探秘大纲（开发者视角）
-
-按"被约束逼出的决策链"组织：从最戏剧性的设计动机（JSC 内存暴涨）出发，逐层剥开入口、核心循环、工具系统、Provider 抽象、UI 框架、状态管理、运行时补丁、Feature Flag、特殊模式、测试策略、反编译指纹。每章都回答"为什么这么设计？"。
-
-### 1. 序章：一份被反编译重建的 CLI，为什么处处是"约束的印记"
-
-章节摘要：开篇先回答整个项目最根本的好奇心——这不是 Anthropic 原版，而是反编译产物在 Bun/JSC 约束下的重建。点明全书主线：每一个看似奇怪的设计背后，都藏着一个具体的运行时约束或反编译痕迹。
-
-子章节：
-
-- 反编译的语义：为什么 stub 模块、feature-gated 代码、React Compiler 的 `_c()` 是正常的
-- 全书的叙事主线：约束（JSC 内存、Bun DCE、运行时类型补丁）如何驱动架构
-- 如何阅读本书：每章锚点都指向真实 `文件:行号`，请打开编辑器对照
-- 两类禁用 feature 的诚实区分：反编译丢失导致的 stub（`CONTEXT_COLLAPSE` / `HISTORY_SNIP` / `FORK_SUBAGENT`）vs 功能原本就 stubbed 的（`SKILL_LEARNING` / `TEAMMEM`）—— 这两类经常被混淆
-
-锚点：
-- `src/types/react-compiler-runtime.d.ts:1`
-- `src/types/global.d.ts:9`、`global.d.ts:59`
-- `CLAUDE.md`
-
-### 2. 第一章：Code Splitting 不是优化，是生存需求
-
-章节摘要：全书最戏剧性的设计动机——单文件 17MB 产物让 Bun/JSC 全量解析导致 RSS 暴涨到 ~1GB，而 Node/V8 懒解析仅需 ~220MB。项目因此被迫切成 600+ chunks，`--version` 的 RSS 从 966MB 骤降到 35MB。
-
-子章节：
-
-- JSC 的贪婪解析 vs V8 懒解析：实验数据（17MB → 1GB vs 220MB）
-- 为什么 Vite 必须代码分割而不是单文件：Bun 按需加载 chunks 的原理
-- 双构建管线：`Bun.build()` vs Vite，各自的 chunk 布局（`dist/` vs `dist/chunks/`）
-- post-build 阶段为什么必须 patch `globalThis.Bun` 解构（`@anthropic-ai/sandbox-runtime` 在 Node.js 启动会崩）
-- 构建产物同时兼容 bun/node：`import.meta.require` → `createRequire` 的运行时探测
-
-锚点：
-- `build.ts:23`、`build.ts:43`、`build.ts:62`
-- `vite.config.ts:94`
-- `scripts/post-build.ts`
-- `src/utils/distRoot.ts:15`
-
-### 3. 第二章：入口的 Fast-Path 优先级链 —— 为什么 --version 必须零模块加载
-
-章节摘要：`cli.tsx` 的 `main()` 函数按优先级串起十几条快速路径，最极端的是 `--version` / `-v` 零模块加载。背后的设计哲学：CLI 启动延迟是用户体验第一杀手，每个子命令都应该尽可能晚地加载它真正需要的代码。
-
-子章节：
-
-- Fast-Path 优先级链：`--version` → `--dump-system-prompt` → MCP servers → `daemon-worker` → bridge → BG sessions → 默认 `main.tsx`
-- **为什么 `CLAUDE_CODE_ABLATION_BASELINE` 必须 inline 在 cli.tsx 顶层**：BashTool / AgentTool / PowerShellTool 在 import 时就把 `DISABLE_BACKGROUND_TASKS` 等环境变量捕获进模块级 `const`，`init()` 跑得太晚无法影响它们 —— 这是一条脆弱但必要的初始化顺序依赖
-- MACRO 编译期注入的三层防线：dev 模式 `-d` flag、build `Bun.build define`、运行时 fallback `globalThis.MACRO`
-- 为什么版本号单一来源在 `package.json` 而不是 hardcoded（避免漂移）
-- 双入口 `cli-bun.js` / `cli-node.js`：同一份产物被两个运行时执行
-
-锚点：
-- `src/entrypoints/cli.tsx:5`、`cli.tsx:11`、`cli.tsx:56`、`cli.tsx:76`、`cli.tsx:79`
-- `scripts/defines.ts:18`、`defines.ts:39`
-- `scripts/dev.ts:17`
-
-### 4. 第三章：performanceShim —— JSC 内存泄漏的运行时补丁
-
-章节摘要：`src/utils/performanceShim.ts` 必须是 `cli.tsx` 的第一行 import。JSC 的原生 Performance 把 marks/measures 存进永不收缩的 C++ Vector，长会话累积数百 MB 死容量。这个 shim 在 React/OTel 捕获原生引用之前劫持全局 performance。
-
-子章节：
-
-- JSC 原生 Performance 的陷阱：C++ Vector 永不收缩
-- 为什么保留 `performance.now()` 走原生，只劫持 `mark` / `measure` / `getEntries`
-- 为什么必须最先 import：React reconciler 和 OTel 会捕获原生引用
-- `query.ts` 的 finally 块兜底 `clearMarks` / `clearMeasures` —— 防 sub-agent 直接 import query 时 shim 没装上
-- 为什么 dev 模式 `NODE_ENV='production'`：避免 6,889+ `_debugStack` Error 对象（12MB）
-
-锚点：
-- `src/utils/performanceShim.ts:1`、`performanceShim.ts:18`、`performanceShim.ts:162`
-- `src/query.ts:460`
-
-### 5. 第四章：核心 Query Loop —— 为什么 query() 是 async generator
-
-章节摘要：`src/query.ts` 的 `query()` 是 `async function*`，yield `StreamEvent` / `Message` / `TombstoneMessage` / `ToolUseSummaryMessage`，最终 return `Terminal`。背后的设计：流式响应必须能够把"结果"与"副作用"解耦，调用方可以选择性消费。
-
-子章节：
-
-- async generator vs callback：为什么用 yield 而不是事件发射器
-- `queryLoop()` 的委托模式：thinking 块的 3 条硬约束（`max_thinking_length>0`、不能是最后一块、跨工具轨迹保留）
-- `MAX_OUTPUT_TOKENS_RECOVERY_LIMIT=3`：`max_output_tokens` 错误为什么会对调用方扣留（yield 会终止会话）
-- `QueryEngine` 作为 `query()` 之上的会话编排器：messages / fileCache / usage 跨 turn 持久
-- `snipReplay` 回调：让 feature-gated 字符串留在 gated 模块外，`QueryEngine` 在 `bun test` 下仍可测
-
-锚点：
-- `src/query.ts:181`、`query.ts:276`、`query.ts:367`、`query.ts:393`、`query.ts:460`
-- `src/QueryEngine.ts:138`、`QueryEngine.ts:192`、`QueryEngine.ts:217`
-
-### 6. 第五章：Feature Flag 系统的三个硬约束
-
-章节摘要：`feature()` 不是普通的运行时函数——它有 Bun 编译器强加的三个硬约束：(1) 只能出现在 `if` 条件或三元表达式（DCE 限制）；(2) 不能赋值给变量；(3) vite 插件必须在 transform 阶段替换为字面量，否则 bundler 会尝试解析不存在的 import。
-
-子章节：
-
-- 为什么 `feature()` 不是布尔变量：Bun 编译器 DCE 的 AST 模式匹配限制
-- `vite-plugin-feature-flags.ts` 的 transform 时机：import 解析之前的字面量替换
-- `REVIEW_ARTIFACT` 内的 `hunter.js` 根本不存在：为什么 `if(false)` 必须在 parse 阶段可见
-- Build 默认 65+ feature vs Dev 全开 vs 运行时 `FEATURE_<NAME>=1`：三层切换机制
-- 反编译产物的 stub 陷阱：明确区分反编译丢失的 stub（`CONTEXT_COLLAPSE` / `HISTORY_SNIP` / `FORK_SUBAGENT`，启用会破坏核心功能）vs 功能原本就 stubbed 的（`SKILL_LEARNING` / `TEAMMEM`）
-
-锚点：
-- `scripts/vite-plugin-feature-flags.ts:29`
-- `src/types/internal-modules.d.ts:10`
-
-### 7. 第六章：工具系统的延迟加载与 CORE_TOOLS 白名单
-
-章节摘要：60 个工具不会一次性全部加载——`CORE_TOOLS` 38 个白名单是"always-available"核心，其余通过 `SearchExtraToolsTool` 按需 TF-IDF 搜索。背后的设计：tool schema 本身会消耗 token，必须按对话需求动态展开。
-
-子章节：
-
-- `CORE_TOOLS` 白名单制：`isDeferredTool` 的判定逻辑
-- `SearchExtraToolsTool`：用 TF-IDF 语义搜索延迟工具（复用 `localSearch.ts` 的 `computeWeightedTf` / `computeIdf` / `cosineSimilarity`）
-- `toolIndex.ts` 的共享算法：为什么 skill prefetch 和 tool prefetch 用独立的去重 Set（`discoveredToolsThisSession` 互不影响）
-- feature-gated 工具：`feature()` 条件加载模式 `const x = feature('X') ? require('./x.js') : null`
-- `SyntheticOutput`：`CORE_TOOLS` 中用于延迟工具按需加载的特殊工具
-
-锚点：
-- `src/constants/tools.ts`
-- `src/tools.ts`
-- `src/services/searchExtraTools/toolIndex.ts`、`prefetch.ts`
-- `packages/builtin-tools/src/tools/`
-
-### 8. 第七章：7-Provider 抽象层的单一调度点
-
-章节摘要：`claude.ts:1344` 是整个 Provider 系统的心脏——在共享预处理（消息归一化、工具过滤、媒体剔除）之后、Anthropic 特定逻辑（betas/thinking/caching）之前动态导入 Provider 路径。兼容层因此自然跳过 Prompt 缓存/beta 功能，无需 feature flag。
-
-子章节：
-
-- Provider 路由优先级链：`modelType` 参数 > `CLAUDE_CODE_USE_*` 环境变量 > firstParty 默认
-- 为什么调度点位置这么精确：兼容层"结构性跳过"betas/thinking 的优雅
-- **调度点的不对称：给 OpenAI 路径传 `tools`（全池）但给 gemini/grok 传 `filteredTools`（裁剪后）**—— 因为 OpenAI 路径在内部模拟 Anthropic 延迟工具加载给 `SearchExtraToolsTool`，需要访问完整池。这恰恰是"调度点位置精确"论点的最强证据
-- `getAPIProvider()` 是单一真相源：`/provider` 命令、Langfuse 追踪、模型映射都依赖它
-- Provider 切换的原子性：`/provider` 命令同时清除所有 `CLAUDE_CODE_USE_*` 再 `applyConfigEnvironmentVariables`
-- Anthropic 内部 4 Provider 统一伪装成 `Anthropic` SDK 类型——代码注释承认的"类型谎言"
-- `isFirstPartyAnthropicBaseUrl()` 的 TODO 陷阱：firstParty 行为可能泄漏到兼容层
-
-锚点：
-- `src/utils/model/providers.ts:15`
-- `src/services/api/claude.ts:1344`（调度点 + tools/filteredTools 不对称）
-- `src/services/api/client.ts:84`
-- `src/services/api/claude.ts:2999`
-- `src/commands/provider.ts:39`
-
-### 9. 第八章：流适配器 —— 让 OpenAI/Gemini/Grok 假装自己是 Anthropic
-
-章节摘要：`adaptOpenAIStreamToAnthropic` / `adaptGeminiStreamToAnthropic` 是纯 async generator，把第三方流格式转换成 `BetaRawMessageStreamEvent`。下游 `claude.ts` 的 `contentBlocks` 累加器与原生 Anthropic 路径完全一致——零分支。这是整个多 API 兼容层最巧妙的设计。
-
-子章节：
-
-- 流适配器模式：async generator 作为格式翻译器
-- 为什么下游零分支：`contentBlocks` 累加器不知道上游是什么 Provider
-- **`message_stop` 后兜底：OpenAI/Grok 适配器在内存累积 `contentBlocks` 仅在 `message_stop` 时组装，网络中断时存在重复发射风险；post-loop 安全回退在 `partialMessage` 未重置时重发** —— 这是"下游零分支"叙事里少数有针对性修补的点
-- `@ant/model-provider` 作为无副作用转换器库 vs `src/services/api` 作为客户端实例化器
-- DeepSeek 思维模式的三层兼容：官方 `thinking` / 自托管 `enable_thinking` / 小米 `chat_template_kwargs`
-- 为什么 Grok 复用整个 OpenAI 适配器栈：只有 client 和 `resolveGrokModel` 是 Grok 特有
-- ChatGPT 订阅路径：Responses API 是 OpenAI 内部的第二个适配器（`input_text` / `input_image` / `role` messages 转换 + `adaptResponsesStreamToAnthropic` vs Chat Completions 流适配器）
-
-锚点：
-- `packages/@ant/model-provider/src/shared/openaiStreamAdapter.ts:35`
-- `packages/@ant/model-provider/src/shared/openaiConvertMessages.ts:32`
-- `src/services/api/openai/index.ts:214`
-- `src/services/api/openai/requestBody.ts:70`
-- `src/services/api/openai/responsesAdapter.ts:1`
-- `src/services/api/gemini/client.ts:26`
-- `src/services/api/grok/index.ts:51`
-
-### 10. 第九章：Usage 字段映射与模型映射的优先级链
-
-章节摘要：三个兼容层的模型映射都用四级优先级链：`PROVIDER_MODEL` 环境变量 > `PROVIDER_DEFAULT_{FAMILY}_MODEL` > `ANTHROPIC_DEFAULT_{FAMILY}_MODEL` > `DEFAULT_MODEL_MAP` 查找表。但 Gemini 是唯一在都缺失时抛异常的。Usage 字段映射则有镜像设计 + cache 字段保留策略，是"下游零分支"叙事里唯一一个有针对性修补的例外。
-
-子章节：
-
-- 正则 `/haiku|sonnet|opus/i` 推断模型系列的设计权衡
-- `GROK_MODEL_MAP` JSON：为什么 Grok 唯一支持用户自定义 JSON 映射
-- 防御性清理：`replace(/\[1m\]$/, '')` 剥离终端加粗 ANSI 后缀
-- `getOpenAIClient` / `getGrokClient` 的模块级缓存：会话中改 API key 必须 `clearOpenAIClientCache()`；对比 `getAnthropicClient()` 按 model/region 参数化的设计差异
-- **Usage 字段映射兼容性**：`updateOpenAIUsage` 与 `claude.ts:updateUsage` 的镜像设计；`cache_creation_input_tokens` / `cache_read_input_tokens` 在增量省略时保留，防止适配器差异导致缓存计数器被静默清零 —— 值得专门讲，因为它是"下游零分支"的唯一例外
-- BedrockClient 的针对性变通：剥离 `anthropic_beta` 体（SDK 0.26.4-0.28.1 漏洞）+ probe 脚本检测修复
-
-锚点：
-- `packages/@ant/model-provider/src/providers/openai/modelMapping.ts:36`
-- `packages/@ant/model-provider/src/providers/gemini/modelMapping.ts:8`
-- `packages/@ant/model-provider/src/providers/grok/modelMapping.ts:51`
-- `src/services/api/openai/shared.ts`（`updateOpenAIUsage`）
-- `src/services/api/claude.ts`（`updateUsage` 镜像）
-- `src/services/api/bedrockClient.ts:29`
-- `src/services/api/openai/client.ts:39`
-- `src/services/api/grok/client.ts:15`
-
-### 11. 第十章：自研 Fork 的 Ink 框架 —— 为什么不是 src/ink/
-
-章节摘要：`packages/@ant/ink/`（package.json name: `@anthropic/ink`）是基于 `react-reconciler` 自建的终端 React 渲染器。`core/` 目录有完整的 `reconciler.ts`、`dom.ts`、`yoga-layout/`、`render-node-to-output.ts`、`hit-test.ts`、`focus.ts`——这是一个完整的终端 DOM + 布局引擎，不是上游 Ink 库。
-
-子章节：
-
-- 为什么 fork 而非用上游 Ink：完整终端 DOM + Yoga 布局引擎的掌控需求
-- react-reconciler 自建渲染器：`reconciler.ts` / `dom.ts` / `yoga-layout` / `render-node-to-output` / `hit-test`
-- `vite.config.ts` 的 `dedupe: ['react', 'react-reconciler', 'react-compiler-runtime']` —— 为什么必须保证单副本
-- React Compiler 输出的 `_c()` memoization 模板 —— 为什么这是正常的
-- `global.d.ts` 的 `declare type T = unknown` —— 反编译产物特有的类型补丁（编译 JSX 丢失泛型）
-
-锚点：
-- `packages/@ant/ink/package.json:1`
-- `packages/@ant/ink/src/core/reconciler.ts:1`
-- `vite.config.ts:94`
-- `src/types/react-compiler-runtime.d.ts:1`
-- `src/types/global.d.ts:9`、`global.d.ts:59`
-
-### 12. 第十一章：三层状态管理 —— 为什么 bootstrap/state.ts 警告 "DO NOT ADD MORE"
-
-章节摘要：`src/bootstrap/state.ts` 是模块级 singleton（sessionId、cwd、projectRoot、token counters），文件顶部警告不要再加。`src/state/store.ts` 是手写 33 行 zustand-style store。`src/state/AppState.tsx` 用 React Context 包裹 store——三层各司其职，边界严格。
-
-子章节：
-
-- Bootstrap state：模块级 singleton 的诱惑与陷阱（"DO NOT ADD MORE STATE HERE"）
-- 手写 zustand-style store：33 行代码（`createStore` 返回 `getState` / `setState` / `subscribe`，`Object.is` 短路、`Set<Listener>`）
-- `AppState.tsx` 的 React Context 包裹：`useSyncExternalStore` 订阅 slice
-- `USER_TYPE==='ant'` 时返回根 state 会抛错：强制细粒度订阅避免全量 re-render
-- `HasAppStateContext` 主动 throw 防嵌套："AppStateProvider can not be nested"
-
-锚点：
-- `src/bootstrap/state.ts:31`、`state.ts:45`
-- `src/state/store.ts:1`
-- `src/state/AppState.tsx:59`、`AppState.tsx:129`
-- `src/state/AppStateStore.ts:42`
-
-### 13. 第十二章：ACP / Bridge / Daemon —— 三个长驻模式的接线
-
-章节摘要：ACP（Agent Client Protocol）、Bridge（Remote Control）、Daemon（supervisor）是三种长驻运行模式。共同特征：feature-gated、独立 entry、跨进程通信。这一章揭示它们如何共享底层 query loop 又各自增加编排层，并与产品大纲第十一章（CI / BYOC runner）形成交叉。
-
-子章节：
-
-- ACP agent 实现：`agent.ts` / `bridge.ts` / `permissions.ts` / `entry.ts` + `createAcpCanUseTool` 统一权限流水线
-- `acp-link` 包：WebSocket 客户端桥接到 ACP agent（REST 注册 + WS identify 两步流程）
-- Bridge 模式：JWT 认证、消息传输、权限回调（feature `BRIDGE_MODE`）
-- Daemon 模式：`workerRegistry.ts` 管 worker，`--daemon-worker=<kind>` 派生精简 worker（无 analytics sink）
-- 自托管 RCS：`packages/remote-control-server/` Docker 部署 + Web UI（React 19 + Vite + Radix UI）
-- **交叉点**：`claude environment-runner` / `self-hosted-runner` BYOC runner 正是 ACP/Bridge/CI 三条线的交汇点，产品大纲第十一章与此章应建立交叉引用
-
-锚点：
-- `src/services/acp/`
-- `packages/acp-link/`
-- `src/bridge/bridgeMain.ts`
-- `src/daemon/main.ts`、`workerRegistry.ts`
-- `packages/remote-control-server/`
-
-### 14. 第十三章：CLAUDE.md 四层层级与 @include 指令
-
-章节摘要：CLAUDE.md 不是单个文件，而是四层层级：Managed → User → Project → Local，后加载的优先级更高（模型更关注）。`@include` 指令支持 60+ 种文本扩展名，防循环、不存在静默忽略，`MAX_MEMORY_CHARACTER_COUNT=40000`。
-
-子章节：
-
-- 为什么逆序优先：离当前目录越近的文件越晚加载，模型关注度越高
-- `@include` 的四种路径形式：`@path` / `@./rel` / `@~/home` / `@/abs`
-- `@include` 的边界：仅限叶子文本节点（非代码块内），防循环，不存在静默忽略
-- 为什么支持 60+ 种扩展名（`.md` / `.ts` / `.py` / `.rs` / `.swift` / `.sql` / `.graphql` ...）
-- `context.ts` 如何把 git status / date / CLAUDE.md / memory files 组装成系统提示
-
-锚点：
-- `src/utils/claudemd.ts:1`、`claudemd.ts:88`、`claudemd.ts:95`
-- `src/context.ts:36`、`context.ts:116`
-
-### 15. 第十四章：测试策略 —— 为什么 mock 必须从底层 HTTP 开始
-
-章节摘要：Bun 的 `mock.module` 是 process-global 的（last-write-wins），不是 per-file 隔离。一个测试文件的 mock 会污染同进程所有 require/import。所以项目立下铁律：只 mock 有副作用的依赖链（log.ts / debug.ts / bun:bundle / axios），不 mock 纯函数。
-
-子章节：
-
-- Bun `mock.module` 的进程全局陷阱：last-write-wins，测试文件执行顺序不保证字母序
-- 为什么不能 mock 被测模块的上层业务模块：`launch*.test.ts` 必须 mock axios 而非 `triggersApi`
-- 共享 mock 文件 `tests/mocks/log.ts` 和 `tests/mocks/debug.ts`：源文件导出变更只需改一处
-- 集成测试 vs 回归测试的目录布局：`launch*.test.ts` 和 `api.test.ts` 同目录的判断标准
-- 排查 mock 污染的 4 步法：单独运行 / 同目录运行 / `console.error` milestone / specifier 解析
-
-锚点：
-- `tests/mocks/log.ts`、`debug.ts`、`axios.ts`
-- `tests/integration/`
-
-### 16. 第十五章：biome.json 的 42 条规则关闭 —— 反编译产物的指纹
-
-章节摘要：biome.json 关掉了 42 条 lint 规则——suspicious 关 `noExplicitAny` / `noConsole`，style 关 `useConst` / `useTemplate`，complexity 关 `noForEach` / `useArrowFunction`，correctness 关 `noUnusedVariables` / `useExhaustiveDependencies`。这不是偷懒，而是反编译产物的必然：decompiled 代码无法逐行重构，只能保留 recommended 基线。
-
-子章节：
-
-- 42 条规则关闭的分类与原因：suspicious / style / complexity / correctness
-- 为什么 `.tsx` 特殊：`lineWidth 120` + 强制分号（其他文件 80 + asNeeded）
-- tsc vs biome 的冲突：`noUnusedPrivateClassMembers` 与声明属性的两难，`biome-ignore` 注释保留类型
-- `@ts-expect-error` 的维护纪律：MACRO 永真比较保留，类型系统更新后 directive 变 unused 必须移除
-- CI 的 `biome ci .` 必须 zero warnings —— 42 条关闭之外仍守底线
-- Node.js v22 不支持 `using` 声明的脆弱 transpile：vite 插件把 `using _x =` 正则替换成 `const _x =`，安全前提是 `SLOW_OPERATION_LOGGING` 未启用 —— 一条脆弱的 transpile 依赖
-
-锚点：
-- `biome.json:24`、`biome.json:102`
-- `.editorconfig`
-
-### 17. 尾声：哪些坑我们没踩 —— 读者可以继续挖掘的方向
-
-章节摘要：本章列出探索过程中因模型过载未能深挖的子系统，邀请读者沿着锚点继续挖掘。同时也诚实交代反编译重建工作的边界。
-
-子章节：
-
-- 未深挖：`ConsoleOAuthFlow.tsx` 的 `china_provider_select` 表单 + `CHINA_LLM_PROVIDERS` 预设表
-- 未深挖：ChatGPT 订阅路径与 Codex CLI 跨工具凭证共享（`~/.codex/auth.json`）
-- 未深挖：`poorMode`（`/poor` 命令）持久化到 `settings.json` + 跨所有兼容层复用
-- 未深挖：`isFirstPartyAnthropicBaseUrl()` TODO 陷阱与 `clearOpenAIClientCache` 模块级缓存陷阱 —— 给读者可追踪的线索
-- 未深挖：`vendor/ripgrep/arm64-darwin` 二进制缺失的实际后果（Grep 工具 spawn 该路径 ENOENT，`distRoot.ts` vendor 复制逻辑就是为了解决这个）
-- 反编译工作的诚实边界：哪些 stub 是因为反编译丢失，哪些是因为功能原本就 stubbed
-- 邀请读者：带上编辑器，沿着锚点继续探索
-
-锚点：
-- `src/components/ConsoleOAuthFlow.tsx:1294`
-- `src/utils/chinaLlmProviders.ts:44`
-- `src/services/api/openai/chatgptAuth.ts:327`
-- `src/commands/poor/poorMode.ts`
-- `src/services/api/client.ts`（`isFirstPartyAnthropicBaseUrl`）
-- `src/services/api/openai/client.ts:39`（`clearOpenAIClientCache`）
-- `src/utils/distRoot.ts`、`src/utils/vendor/ripgrep/`
-
----
-
-## 第三部分：交叉主题（两个视角都需要覆盖）
-
-下列主题在产品与设计两个视角下都需要覆盖，但写法、深度、锚点指向各不相同。
-
-### 1. 排错与错误对照
-
-- 产品视角：作为第十章主体。给一张"Provider 报错对照表"（401 / 403 / 429 / `overloaded_error` 1305 / 模型不存在），配兼容层特有坑（DeepSeek `reasoning_content` 400、Bedrock `anthropic_beta` 400、Gemini 硬抛异常、OpenAI 限流头解析）。措辞用"我遇到了 X，怎么办？"
-- 设计视角：当前设计大纲**完全没有排错章**，是最大缺口。建议补一节"排错的工程化"：为什么 Bedrock 补丁必须配 probe 脚本（`scripts/probe-bedrock-beta-fix.ts`）、为什么 DeepSeek 必须回显空 `reasoning_content`、`isFirstPartyAnthropicBaseUrl` TODO 为什么泄漏。措辞用"这个错误的根因是 Y 设计决策"。
-
-### 2. 性能与内存
-
-- 产品视角：第十章一笔带过即可。给"长会话变卡怎么办"的解决路径：`/compact` → `/force-snip` → 重启。RSS 数据用一句话引用。
-- 设计视角：第一、三、四章是深水区。给完整数据链（17MB → 1GB vs 220MB；`--version` RSS 966MB → 35MB；6,889 `_debugStack` Error 12MB；`performanceShim` 兜底）。讲清 JSC C++ Vector 永不收缩的根因。
-
-### 3. 安全
-
-- 产品视角：新增第十三章（当前完全缺失）。措辞用"我的密钥去了哪里"。覆盖凭证存储路径清单、OAuth 刷新窗口、`/share` / `/export` 隐私边界、跨工具凭证共享的隐私影响。
-- 设计视角：作为"反编译重建的安全约束"穿插在相关章节。措辞用"为什么这么存"。讲 `bypassPermissions` 在非 root/sandbox 的可用性检测、JWT 在 Bridge 的设计、`HasAppStateContext` 主动 throw 防嵌套的安全含义。
-
-### 4. 升级与版本管理
-
-- 产品视角：第十章的 `claude doctor` 子章节展开。给"我该怎么升级"工作流：`claude doctor` 版本检查 → `bun run update` → 重启。
-- 设计视角：第二章的"版本号单一来源 `package.json`"展开。讲 MACRO 三层注入、`scripts/probe-bedrock-beta-fix.ts` 作为"SDK 漏洞 probe 模式"的工程实践示范（如何检测上游 SDK 修复后安全删除针对性补丁）。
-
-### 5. 与其他工具集成
-
-- 产品视角：第八章（ACP/Bridge/IDE）+ 第十一章（GitHub Actions）。给"我能在 X 里用 Claude 吗"的清单式回答。
-- 设计视角：当前设计大纲**完全没有跨工具集成视角**，是第二大缺口。建议在第十二章（ACP/Bridge/Daemon）补一节"集成边界"：acp-link 与 Codex CLI 凭证共享、`vscode-ide-bridge` 的协议设计、`install-github-app` / `subscribe-pr` / `commit-push-pr` 的工作流契约。
-
-### 6. 可观测性
-
-- 产品视角：第十章子章节。措辞用"我想知道 Claude 在做什么"。覆盖 Langfuse 追踪、`--dump-system-prompt`、`/debug-tool-call`、`BUN_INSPECT` 调试。
-- 设计视角：当前设计大纲仅第七章锚点提到 `claude.ts:2999`。建议补一节"观测的注入点"：`recordLLMObservation` 的 `provider` 字段如何从 `getAPIProvider()` 取值、为什么 Langfuse 追踪必须用单一真相源、`performanceShim` 与 OTel 的耦合关系。
-
-### 7. 凭证与认证生命周期
-
-- 产品视角：第二章 + 第十三章交叉。措辞用"我的令牌怎么刷新、什么时候过期"。覆盖 OAuth 设备码、ChatGPT 订阅 5 分钟刷新偏差、China LLM 表单写入流程、`/login` 与 `/logout` 副作用、`/provider unset` 只清 Provider 不清 key。
-- 设计视角：在第七、八章穿插。措辞用"为什么 token 这样存"。讲模块级 client cache 的设计权衡（`getAnthropicClient` 参数化 vs `getOpenAIClient` 模块级缓存）、ChatGPT 订阅路径为何读 `~/.codex/auth.json`（与 Codex CLI 复用凭证的设计决策）、5 分钟刷新偏差窗口的容错考量。
-
----
-
-## 下一步建议
-
-### 建议先写的章节（价值最高）
-
-1. **产品第二章 + 第十章排错对照表**（含"我改了 API key 但没生效"与"为什么切了 Provider 没生效"两个高频困惑）—— 这是用户最高频的痛点，写完立竿见影降低 issue 量。
-2. **设计第一章（Code Splitting 是生存需求）+ 第三章（performanceShim）**—— 这两章是全书的叙事引擎，"为什么这么设计"的最戏剧性证据，先写好它们能定调整本书的好奇心基调。
-3. **交叉主题"安全"章（产品第十三章）**—— 当前两份大纲都完全缺失，是最显眼的空白；凭证存储、权限模式、OAuth 刷新一旦写清楚，能避免大量误用。
-4. **设计第七章（单一调度点）补 tools/filteredTools 不对称段 + 第九章（Usage 字段映射）新增**—— 这两段是"下游零分支"叙事的核心证据与唯一例外，写好了能让设计大纲的 Provider 章节真正立住。
-5. **产品第四章（slash 命令速查）按场景分类表**—— 用户最常翻的一章，写好就是一张长期参考表，ROI 极高。
-
-### 会因图示或代码示例受益的章节
-
-1. **设计第一章 Code Splitting**——RSS 数据柱状图（17MB 单文件 1GB / 切分后 35MB / Node 220MB）一张图胜千言。
-2. **设计第七/八章 Provider 调度点 + 流适配器**——一张调度流程图：消息归一化 → 工具过滤（tools vs filteredTools 分叉）→ 调度点 → 三条 Provider 路径（Anthropic 原生 / OpenAI/Grok 流适配器 / Gemini 流适配器）→ 统一 `contentBlocks` 累加器。
-3. **产品第十章 Provider 报错对照表 + 产品第十三章凭证存储**——前者是表格，后者是 `~/.claude/` 与 `~/.codex/` 的目录树图，直观显示哪些文件含密钥。

docs.json

@@ -1,14 +1,152 @@
 {
   "$schema": "https://mintlify.com/docs.json",
   "theme": "mint",
-  "name": "Claude Code Best",
+  "name": "Claude Code Architecture",
-  "description": "Anthropic Claude Code 的开源复原版本 — 完整架构原理、功能文档与使用指南。",
   "colors": {
-    "primary": "#D77757",
+    "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"
@@ -26,7 +164,7 @@
     }
   },
   "search": {
-    "prompt": "搜索 CCB 文档..."
+    "prompt": "搜索 Claude Code 架构文档..."
   },
   "seo": {
     "metatags": {
@@ -38,90 +176,13 @@
   },
   "footer": {
     "socials": {
-      "github": "https://github.com/claude-code-best/claude-code",
+      "github": "https://github.com/anthropics/claude-code"
-      "discord": "https://discord.gg/uApuzJWGKX"
     }
   },
   "redirects": [
     {
-      "source": "/docs/features/agents/uds-inbox",
+      "source": "/docs/introduction",
-      "destination": "/docs/features/agents/pipes-and-lan"
+      "destination": "/docs/introduction/what-is-claude-code"
-    },
-    {
-      "source": "/docs/features/agents/lan-pipes",
-      "destination": "/docs/features/agents/pipes-and-lan"
-    },
-    {
-      "source": "/docs/features/agents/acp-link",
-      "destination": "/docs/features/agents/acp"
-    },
-    {
-      "source": "/docs/features/agents/acp-zed",
-      "destination": "/docs/features/agents/acp"
-    },
-    {
-      "source": "/docs/features/external/chrome-use-mcp",
-      "destination": "/docs/features/external/chrome-control"
-    },
-    {
-      "source": "/docs/features/external/claude-in-chrome-mcp",
-      "destination": "/docs/features/external/chrome-control"
-    },
-    {
-      "source": "/docs/features/external/computer-use-tools-reference",
-      "destination": "/docs/features/external/computer-use"
     }
-  ],
+  ]
-  "navigation": {
+}
-    "groups": [
-      {
-        "group": "开始",
-        "pages": [
-          "docs/getting-started/installation",
-          "docs/getting-started/quickstart",
-          "docs/getting-started/model-providers"
-        ]
-      },
-      {
-        "group": "核心功能",
-        "pages": [
-          {
-            "group": "协作与多 Agent",
-            "pages": [
-              "docs/features/agents/pipes-and-lan",
-              "docs/features/agents/acp"
-            ]
-          },
-          {
-            "group": "外部接入",
-            "pages": [
-              "docs/features/external/channels",
-              "docs/features/external/chrome-control",
-              "docs/features/external/computer-use",
-              "docs/features/external/voice-mode",
-              "docs/features/external/web-browser-tool"
-            ]
-          },
-          {
-            "group": "运行模式",
-            "pages": [
-              "docs/features/modes/auto-dream",
-              "docs/features/modes/remote-control-self-hosting"
-            ]
-          },
-          {
-            "group": "工具与体验",
-            "pages": ["docs/features/tools/langfuse-monitoring"]
-          }
-        ]
-      },
-      {
-        "group": "内部机制",
-        "pages": [
-          "docs/internals/growthbook-adapter",
-          "docs/internals/sentry-setup"
-        ]
-      }
-    ]
-  }
-}

docs.md

@@ -1,32 +0,0 @@
-# Claude Code Best 文档大纲
-
-> 自动生成自 docs.json 与各文档 frontmatter。共 3 个顶级分组。
-
-## 1. 开始
-
-- `getting-started/installation` — **安装 Claude Code Best** — 通过 NPM 一行命令安装 CCB，或从源码克隆构建。支持 macOS、Linux、Windows。
-- `getting-started/quickstart` — **快速上手** — 5 分钟掌握 CCB 的基本使用：启动会话、输入指令、审批工具调用、用斜杠命令管理状态。
-- `getting-started/model-providers` — **配置模型供应商** — 通过 /login 命令接入 OpenAI / Anthropic / Gemini / Grok 兼容协议，或直接用环境变量配置。支持 DeepSeek、GLM、OpenRouter、Bedrock 代理等任意兼容服务。
-
-## 2. 核心功能
-
-- ### 协作与多 Agent
-  - `features/agents/pipes-and-lan` — **群控：本机 + 局域网多实例协作** — 多台 CCB 实例零配置组网，同机用 UDS、跨机用 LAN，自动发现与消息路由。包含 /pipes 命令、心跳机制、消息路由详解。
-  - `features/agents/acp` — **ACP 协议：接入 Zed / Cursor 等 IDE** — 通过 ACP（Agent Client Protocol）把 CCB 接入支持 ACP 的 IDE。本文包含 acp-link CLI 用法、权限桥接、以及 Zed 集成案例。
-- ### 外部接入
-  - `features/external/channels` — **频道消息推送（Channels）** — MCP 服务器把飞书 / Slack / Discord / 微信等外部消息推到会话，`--channels plugin:name@marketplace` 启用。
-  - `features/external/chrome-control` — **Chrome 浏览器控制** — 让 AI 用自然语言操作 Chrome 浏览器：导航、表单、数据抓取。两种实现方案对比：自托管 MCP（chrome-use-mcp）与 Chrome 原生集成（claude-in-chrome-mcp）。
-  - `features/external/computer-use` — **屏幕控制（Computer Use）** — 截屏、键鼠控制，跨 macOS / Windows / Linux。本文包含快速上手、平台差异说明和工具参考。
-  - `features/external/voice-mode` — **语音输入（Voice Mode）** — Push-to-talk 语音输入，支持豆包语言模型。需 Anthropic OAuth 或本地语音后端。
-  - `features/external/web-browser-tool` — **浏览器操作工具** — 让 AI 控制 Chrome 完成网页操作：导航、点击、输入、抓取。
-- ### 运行模式
-  - `features/modes/auto-dream` — **后台记忆整理（Auto Dream）** — 会话间自动审查、组织和修剪持久化记忆，确保未来会话快速获得准确上下文。
-  - `features/modes/remote-control-self-hosting` — **Remote Control 私有化部署** — Docker 自托管 RCS，含 Web UI 控制面板、ACP agent 接入、JWT 认证。
-- ### 工具与体验
-  - `features/tools/langfuse-monitoring` — **Langfuse 监控集成** — Agent loop 实时监控，可视化每次 API 调用、token 消耗、工具执行链路，可一键转化为训练数据集。
-
-## 3. 内部机制
-
-- `internals/growthbook-adapter` — **GrowthBook 适配器 - 自定义 Feature Flag 服务器接入** — 通过环境变量连接自定义 GrowthBook 服务器，实现远程 feature flag 控制。无配置时自动回退到代码默认值。
-- `internals/sentry-setup` — **自定义 Sentry 错误上报配置** — 通过环境变量连接自托管或 Cloud Sentry，实现 CLI 运行时的错误捕获与上报。不配置则完全静默。
-

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

@@ -0,0 +1,101 @@
+---
+title: "协调者与蜂群"
+description: "两种多 Agent 协作模式：Coordinator 的星型编排和 Swarm 的竞争认领。理解各自的设计权衡和适用场景。"
+keywords: ["协调者模式", "蜂群模式", "Agent Swarm", "多 Agent 协作", "任务编排"]
+---
+
+## 核心问题
+
+单个 AI Agent 的上下文窗口有限。当任务复杂到需要同时理解多个模块、执行多个并行操作时，单个 Agent 会力不从心。
+
+多 Agent 协作的目标：让多个 AI Agent 分工合作，各自拥有独立的上下文窗口，协同完成复杂任务。
+
+## 两种协作模式
+
+| 维度 | Coordinator Mode | Agent Swarms |
+|------|-----------------|--------------|
+| **拓扑** | 星型：Coordinator 居中编排 | 星型 + P2P：Teammate 间可直接通信 |
+| **角色** | Coordinator 理解决策，Worker 执行 | Team Lead 协调，Teammate 自主认领 |
+| **适用** | 需要集中决策的复杂任务 | 并行度高、任务独立的场景 |
+
+两者不是互斥的——可以组合使用，但那属于高级用法。
+
+## Coordinator Mode：先理解，再分配
+
+### 设计哲学
+
+Coordinator Mode 最核心的约束：**Coordinator 必须先理解问题，再分配任务。**
+
+反模式（禁止）：
+> "Based on your findings, fix the auth bug" — 把理解的责任推给了 Worker
+
+正确做法：
+> "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 不理解问题就分配任务，Worker 会因为缺乏上下文而做出错误的决策。Coordinator 的理解质量直接决定了 Worker 的执行质量。
+
+### Coordinator 的工具限制
+
+Coordinator 被剥夺了所有"动手"工具——不写代码、不读文件、不执行命令。只保留编排能力：启动 Worker、发送指令、停止走错方向的 Worker。
+
+**设计洞察**：限制工具不是能力的削弱，而是职责的清晰化。Coordinator 专注于"想"，Worker 专注于"做"。如果 Coordinator 也能动手，它很容易跳过编排直接自己干，失去了多 Agent 的意义。
+
+### Scratchpad：跨 Worker 共享知识
+
+Workers 共享一个 Scratchpad 目录，可以自由读写。Worker A 的研究结果可以写入 Scratchpad，Worker B 直接读取，无需通过 Coordinator 中转。
+
+**设计考量**：不是所有知识都需要通过 Coordinator 中转。中间结果（如搜索结果、分析报告）适合 Worker 间直接共享，只有最终结论和决策才需要 Coordinator 参与。
+
+### 通信协议
+
+Worker 完成后，Coordinator 收到结构化通知，包含状态、结果摘要和 token 使用统计。Coordinator 可以向任何 Worker 发送后续指令，实现"分配 → 执行 → 反馈 → 追加"的循环。
+
+## Agent Teams (Swarm)：竞争认领
+
+### 设计哲学
+
+Swarm 基于一个简单的假设：**如果任务列表是共享的、可见的，多个 Agent 会自然地分工合作。**
+
+不需要一个中央调度器——每个 Teammate 看到任务列表，自己决定认领哪个任务。这和人类团队的工作方式一致：站会上大家看到看板，自己选择下一步做什么。
+
+### 核心机制
+
+| 机制 | 说明 |
+|------|------|
+| **共享任务列表** | 所有 Teammate 看到同一个任务池 |
+| **竞争认领** | 第一个锁定任务的 Teammate 获得执行权 |
+| **Mailbox 消息** | Teammate 间可直接通信，无需经过 Lead |
+| **异常恢复** | Teammate 崩溃后，其未完成任务被自动重置 |
+
+### 竞争认领的并发安全
+
+两个 Teammate 可能同时想认领同一个任务。文件锁保证原子性——第一个写入者获得锁定，第二个收到 `already_claimed` 错误后选择下一个任务。
+
+**设计考量**：竞争是特性而非缺陷。它确保任务自然地分配给最先空闲的 Agent，不需要中央调度。但需要防止"饿死"——如果某个 Agent 总是慢半拍，它可能永远抢不到任务。实践中这个问题不严重，因为 AI Agent 的执行速度差异不大。
+
+### Teammate 的生命周期
+
+Teammate 异常退出时，其未完成任务被自动重置为无主状态。Team Lead 通过共享任务列表或空闲通知感知到变化，可以重新分配或创建新 Teammate。
+
+**设计哲学**：单个 Agent 的崩溃不应该阻塞整个团队。任务系统保证工作不会因为个别 Agent 的失败而丢失。
+
+### 当前限制
+
+- 不支持嵌套团队（Teammate 不能创建子团队）
+- 每会话一个团队
+- Lead 固定不可更换
+
+## 模式选择指南
+
+| 场景 | 推荐模式 | 原因 |
+|------|---------|------|
+| "重构认证系统，需要多模块协调" | Coordinator | 需要集中决策，Worker 间有依赖 |
+| "修复 10 个独立的 lint 警告" | Swarm | 任务独立，Teammate 可完全并行 |
+| "研究方案 A 和方案 B，然后选一个实现" | Coordinator | 先并行研究，再集中决策 |
+| "在大仓库中搜索所有 TODO 并分类" | Swarm | 无依赖，各自领任务即可 |
+
+## 接下来
+
+- **子 Agent** — 理解单个子 Agent 的创建和生命周期
+- **Worktree 隔离** — 理解多 Agent 的文件系统隔离
+- **任务管理** — 理解支撑协作的任务系统

docs/agent/sub-agents.mdx

@@ -0,0 +1,110 @@
+---
+title: "子 Agent"
+description: "主 Agent 可以启动子 Agent 来并行工作或委派专业任务。理解三种子 Agent 路径、工具池隔离、Fork 的缓存优化和异步生命周期管理。"
+keywords: ["子 Agent", "AgentTool", "任务委派", "子进程隔离"]
+---
+
+## 核心问题
+
+单个 Agent 的上下文窗口是有限的。当需要同时研究多个方向、并行执行多个操作时，一个 Agent 做不过来。
+
+子 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 的模型选择遵循优先级链：
+
+```
+环境变量覆盖 > 每次调用参数 > Agent 定义的模型 > 继承父对话模型
+```
+
+`inherit` 不是简单的模型传递——它经过运行时解析，确保 plan mode 下的模型映射正确生效。
+
+## 工具池隔离
+
+子 Agent 不继承父 Agent 的工具限制——它的工具池完全独立组装。
+
+**设计考量**：父 Agent 可能处于受限模式（如 Plan Mode），但子 Agent 可能需要完整的工具集来执行任务。独立的工具池让子 Agent 的权限不受父 Agent 限制。
+
+Fork 子进程例外——它直接继承父 Agent 的工具池，以保持 Prompt Cache 中工具定义的字节一致性。
+
+### Agent 级 MCP 服务器
+
+子 Agent 可以额外连接专属的 MCP 服务器。如果 Agent 声明了 `requiredMcpServers`，系统会等待这些服务器连接完成（最长 30 秒），确保工具可用后才启动。
+
+## Worktree 隔离
+
+`isolation: "worktree"` 参数让子 Agent 在独立的 git worktree 中工作：
+
+```
+创建 worktree → 子 Agent 在独立副本中工作 → 完成
+  → 有变更：保留 worktree，返回路径
+  → 无变更：自动删除
+```
+
+**设计目的**：子 Agent 的实验性修改不应该影响主分支。Worktree 提供了文件系统级别的隔离，同时保持对完整代码库的访问。
+
+## 生命周期：同步 vs 异步
+
+### 异步 Agent（后台运行）
+
+异步 Agent 立即返回 `async_launched` 状态，主 Agent 可以继续工作。后台 Agent 完成后通过通知机制汇报结果。
+
+异步 Agent 获得独立的 AbortController——用户取消主线程不会杀掉后台 Agent。这确保长时间运行的构建/测试任务不会被意外中断。
+
+### 同步 Agent（前台运行）
+
+同步 Agent 有一个"可后台化"机制：如果执行超过阈值（默认 120 秒），系统自动将其转为后台运行。这防止了一个慢子 Agent 阻塞整个工作循环。
+
+## 适用场景
+
+<CardGroup cols={2}>
+  <Card title="并行研究" icon="magnifying-glass">
+    多个 fork 子进程并行搜索不同方向，共享 Prompt Cache 前缀
+  </Card>
+  <Card title="专业委派" icon="code-branch">
+    使用命名 Agent 执行专业任务，受限工具集 + 独立权限
+  </Card>
+  <Card title="隔离实验" icon="flask">
+    worktree 隔离中尝试方案，不影响主分支
+  </Card>
+  <Card title="后台构建" icon="layer-group">
+    异步启动长时间构建/测试，主 Agent 继续工作
+  </Card>
+</CardGroup>
+
+## 接下来
+
+- **协调者与蜂群** — 理解多 Agent 的高级编排模式
+- **Worktree 隔离** — 深入理解文件系统隔离机制
+- **任务管理** — 理解支撑多 Agent 的任务追踪

docs/agent/worktree-isolation.mdx

@@ -0,0 +1,99 @@
+---
+title: "Worktree 隔离"
+description: "多 Agent 并行工作时，共享同一目录会导致冲突。Git worktree 提供文件系统级隔离，让每个 Agent 拥有独立的工作空间。"
+keywords: ["Worktree", "git worktree", "文件隔离", "多 Agent 隔离", "并行安全"]
+---
+
+## 核心问题
+
+多 Agent 并行工作时，共享同一工作目录会导致三类冲突：
+
+1. **写入冲突**：两个 Agent 同时编辑同一个文件，后写的覆盖前写的
+2. **状态干扰**：Agent A 的测试依赖某个环境状态，Agent B 的修改破坏了它
+3. **不可区分**：半完成的修改混在一起，无法分辨哪些是哪个 Agent 的
+
+Git worktree 是 git 原生的解决方案——在同一个仓库中创建多个独立工作目录，每个在自己的分支上。
+
+## 目录结构
+
+```
+<repo-root>/
+├── .claude/
+│   └── worktrees/
+│       ├── fix-auth-bug/          ← Agent A 的独立工作空间
+│       │   └── .git               ← 指向主仓库的链接
+│       └── add-dark-mode/         ← Agent B 的独立工作空间
+│           └── ...
+├── src/                           ← 主工作目录（不受影响）
+└── .git/                          ← 主仓库
+```
+
+每个 worktree 是一个完整的文件系统视图，但共享同一个 git 历史。Agent 在自己的 worktree 中修改文件，不会影响主分支或其他 Agent。
+
+## 创建与恢复
+
+### 创建流程
+
+```
+检查是否已在 worktree 中（防嵌套） → 生成 slug → 创建 worktree → 切换进程工作目录
+```
+
+**设计细节**：
+- 分支名遵循 `worktree/<slug>` 格式，slug 有严格的字符限制
+- 创建后自动更新进程状态——所有后续文件操作自动在 worktree 中执行
+- 系统提示和 CLAUDE.md 被重新加载，确保 AI 看到 worktree 中的上下文
+
+### 快速恢复路径
+
+如果目标 worktree 已存在，直接读取指针文件获取 HEAD SHA——纯文件 I/O，无子进程。在大仓库中 `git fetch` 可能需要 6-8 秒，这个优化将恢复延迟降到接近 0。
+
+**设计洞察**：恢复（resume）是比创建更频繁的操作。用户可能中断后重新开始，或者 Agent 在之前的 worktree 上继续工作。优化恢复路径比优化创建路径更有价值。
+
+### Hook 优先架构
+
+如果用户配置了 `WorktreeCreate` hook，系统完全不调用 git，而是执行 hook 命令获取路径。这允许非 git 版本控制系统（如 Pijul、Mercurial）通过 hook 接入隔离机制。
+
+## 退出与清理
+
+退出支持两种策略：
+
+| 策略 | 行为 | 适用场景 |
+|------|------|---------|
+| **keep** | 保留 worktree 和分支 | 后续需要合并或审查 |
+| **remove** | 删除 worktree 和分支 | 确认不再需要 |
+
+### Fail-closed 安全防护
+
+删除操作有多层安全防护：
+
+1. 只允许删除通过 EnterWorktree 创建的 worktree（手动 `git worktree add` 的不会被删）
+2. 有未提交文件或新提交时，拒绝删除（除非显式 `discard_changes: true`）
+3. git 命令失败时，返回"未知"状态，拒绝删除
+
+**设计哲学**：宁可让用户手动处理废弃的 worktree，也不冒险丢失工作。磁盘空间比丢失代码便宜得多。
+
+### 重新计数
+
+validateInput 和实际执行之间可能有新的修改。删除前重新计数变更，确保不会误删。
+
+## 与子 Agent 的联动
+
+子 Agent 的 `isolation: "worktree"` 参数自动在独立 worktree 中运行。子 Agent 的 worktree 管理与用户会话略有不同：
+
+| 维度 | 用户会话 | 子 Agent |
+|------|---------|---------|
+| Session 状态 | 完整持久化 | 无 session 状态 |
+| 清理策略 | 手动退出 | 自动清理（无变更则删除） |
+| 有变更时 | 用户决定 | 保留 worktree，返回路径 |
+
+**设计考量**：子 Agent 的 worktree 不需要用户手动管理——如果 Agent 没有产生任何修改，worktree 被自动清理；如果有修改，保留下来供主 Agent 后续合并。
+
+## Sparse Checkout 优化
+
+大型 monorepo 中，完整检出可能需要数十秒。Sparse checkout 只检出特定目录，将创建时间降到几秒。
+
+## 接下来
+
+- **子 Agent** — 理解使用 worktree 隔离的子 Agent 创建
+- **协调者与蜂群** — 理解多 Agent 的高级编排
+- **权限模型** — 理解工具权限的安全体系

docs/auto-updater.md

@@ -0,0 +1,312 @@
+# 自动更新机制
+
+## 概述
+
+Claude Code 拥有一套复杂的多策略自动更新系统，支持三种安装方式、后台静默更新、手动 CLI 命令、服务端版本门控以及更新日志展示。系统设计目标是在最小用户干预下保持 CLI 最新，同时提供回滚和手动控制的兜底手段。
+
+---
+
+## 安装类型与更新策略
+
+更新策略由安装方式决定，通过 `src/utils/doctorDiagnostic.ts` 检测：
+
+| 安装类型 | 更新策略 | 自动安装？ |
+|---|---|---|
+| `native` | 从 GCS/Artifactory 下载二进制文件，通过符号链接激活 | 是（静默） |
+| `npm-global` | `npm install -g` / `bun install -g` | 是（静默） |
+| `npm-local` | `npm install` 到 `~/.claude/local/` | 是（静默） |
+| `package-manager` | 显示通知，附带对应操作系统的升级命令 | 否（仅通知） |
+| `development` | 不适用 — 执行 `claude update` 时报错 | 不适用 |
+
+### 策略路由
+
+`src/components/AutoUpdaterWrapper.tsx` — 挂载在 React/Ink UI 树中 — 检测安装类型并渲染对应的更新组件：
+
+- `native` → `NativeAutoUpdater`（二进制下载 + 符号链接）
+- `package-manager` → `PackageManagerAutoUpdater`（仅通知）
+- 其他 → `AutoUpdater`（基于 JS/npm）
+
+---
+
+## 后台自动更新循环
+
+三个更新组件共享相同的轮询模式：
+
+```typescript
+useInterval(checkForUpdates, 30 * 60 * 1000); // 每 30 分钟
+```
+
+组件挂载时（即启动时）也会执行一次检查。
+
+### 前置检查门控
+
+任何更新尝试之前，系统会依次检查：
+
+1. **自动更新是否被禁用？** — `getAutoUpdaterDisabledReason()`（`src/utils/config.ts:1737`）
+   - `NODE_ENV === 'development'`
+   - 设置了 `DISABLE_AUTOUPDATER` 环境变量
+   - 仅限必要流量模式
+   - `config.autoUpdates === false`（native 安装的保护模式除外）
+2. **最大版本上限？** — `getMaxVersion()`（`src/utils/autoUpdater.ts:108`）— 服务端熔断开关，防止更新到已知有问题的版本
+3. **是否跳过该版本？** — `shouldSkipVersion()`（`src/utils/autoUpdater.ts:145`）— 尊重用户的 `minimumVersion` 设置，防止切换到 stable 频道时发生意外的版本降级
+
+### Native 自动更新器（`src/components/NativeAutoUpdater.tsx`）
+
+1. 调用 `src/utils/nativeInstaller/installer.ts` 中的 `installLatest()`
+2. 通过 `src/utils/nativeInstaller/download.ts` 下载二进制文件（GCS 或 Artifactory）
+3. 验证 SHA256 校验和（3 次重试，60 秒卡顿检测）
+4. 将版本化二进制文件存储到 XDG 目录
+5. 更新符号链接（`~/.local/bin/claude` → 新版本二进制文件）
+6. 保留最近 2 个版本，清理旧版本
+7. 将错误分类上报分析（超时、校验和、权限、磁盘空间不足、npm、网络）
+
+### JS/npm 自动更新器（`src/components/AutoUpdater.tsx`）
+
+1. 调用 `getLatestVersion()` 获取当前 npm dist-tag
+2. 通过 semver `gte()` 比较版本
+3. 根据安装类型路由到本地或全局安装
+4. 使用文件锁（`acquireLock()` / `releaseLock()`）防止并发更新
+
+### 包管理器通知器（`src/components/PackageManagerAutoUpdater.tsx`）
+
+每 30 分钟通过 GCS 存储桶（非 npm）检查更新。**不会自动安装** — 仅显示对应操作系统的升级命令：
+
+- macOS: `brew upgrade claude-code`
+- Windows: `winget upgrade Anthropic.ClaudeCode`
+- Alpine: `apk upgrade claude-code`
+
+---
+
+## 启动版本门控
+
+`src/utils/autoUpdater.ts:70` — `assertMinVersion()`
+
+定义于 `src/utils/autoUpdater.ts:70`，设计上在启动时调用（当前未接入启动流程）：
+
+```typescript
+void assertMinVersion();
+```
+
+1. 从 GrowthBook 动态配置获取 `tengu_version_config`
+2. 如果 `MACRO.VERSION < minVersion`，打印错误信息并调用 `gracefulShutdownSync(1)` — 强制用户更新
+3. 这是一个**硬性门控** — 低于最低版本的 CLI 将无法启动
+
+---
+
+## 手动 CLI 命令
+
+### `claude update` / `claude upgrade`
+
+**文件**: `src/cli/update.ts`
+
+完整流程：
+1. 运行 `getDoctorDiagnostic()` 检查系统健康状态
+2. 检查是否存在多个安装及配置不一致
+3. 根据安装类型路由：
+   - `development` → 报错（"开发版本不支持自动更新"）
+   - `package-manager` → 打印对应操作系统的更新命令
+   - `native` → 使用原生安装器的 `updateLatest()`
+   - `npm-local` → 在 `~/.claude/local/` 执行 `npm install`
+   - `npm-global` → 执行 `npm install -g`（含权限检查）
+4. 报告当前版本、最新版本、成功/失败状态
+
+### `claude rollback [target]`（仅限内部）
+
+回滚到之前的版本。支持 `--list`、`--dry-run`、`--safe` 标志。
+
+### `claude install [target]`
+
+安装或重新安装原生构建版本。接受可选的版本目标参数。
+
+### `claude doctor`
+
+检查自动更新器的健康状态，报告状态、权限和配置信息。
+
+---
+
+## 原生安装器架构
+
+**文件**: `src/utils/nativeInstaller/installer.ts`
+
+### 二进制文件存储布局
+
+```
+~/.local/share/claude-code/
+├── versions/          # 版本化二进制文件 (claude-1.0.3, claude-1.0.4, ...)
+├── staging/           # 临时下载暂存区
+└── locks/             # 基于 PID 和 mtime 的锁文件
+
+~/.local/bin/claude    # 指向当前版本二进制文件的符号链接
+```
+
+Windows 系统使用文件复制而非符号链接。
+
+### 核心操作
+
+| 函数 | 说明 |
+|---|---|
+| `updateLatest()` | 核心更新流程：最大版本上限 → 跳过检查 → 加锁 → 下载 → 安装 → 更新符号链接 |
+| `installLatest()` | Singleflight 包装版本，防止重复的进行中安装 |
+| `cleanupOldVersions()` | 保留最近 2 个版本，清理过期的暂存区和临时文件 |
+| `lockCurrentVersion()` | 进程生命周期锁，防止正在运行的版本被删除 |
+| `cleanupNpmInstallations()` | 迁移到原生安装时清理旧的 npm 安装 |
+
+### 下载与校验
+
+**文件**: `src/utils/nativeInstaller/download.ts`
+
+1. 路由到 Artifactory（内部用户）或 GCS 存储桶（外部用户）
+2. 下载二进制文件并跟踪进度
+3. SHA256 校验和验证
+4. 60 秒卡顿检测（中止停滞的下载）
+5. 失败时自动重试 3 次
+
+---
+
+## 文件锁机制
+
+**文件**: `src/utils/autoUpdater.ts:176-268`
+
+防止并发更新进程破坏安装：
+
+- 锁文件：`~/.claude/update.lock`（或等效路径）
+- 5 分钟超时 — 超过 5 分钟的锁被视为过期，强制获取
+- 进程将其 PID 写入锁文件
+- `acquireLock()` 和 `releaseLock()` 同时被 JS/npm 和原生安装器使用
+
+---
+
+## 配置
+
+### 设置项
+
+**文件**: `src/utils/settings/types.ts`
+
+| 设置项 | 类型 | 说明 |
+|---|---|---|
+| `autoUpdatesChannel` | `'latest' \| 'stable'` | 自动更新的发布频道 |
+| `minimumVersion` | string | 最低版本要求，防止意外的版本降级 |
+
+### 全局配置
+
+**文件**: `src/utils/config.ts:191-193`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `autoUpdates` | boolean | 启用/禁用自动更新（旧版） |
+| `autoUpdatesProtectedForNative` | boolean | 原生安装始终自动更新 |
+
+### 配置迁移
+
+**文件**: `src/migrations/migrateAutoUpdatesToSettings.ts`
+
+一次性将旧版 `globalConfig.autoUpdates = false` 迁移为 settings 中的 `DISABLE_AUTOUPDATER=1` 环境变量。定义于 `src/migrations/migrateAutoUpdatesToSettings.ts`（当前未接入启动流程）。
+
+---
+
+## 更新通知去重
+
+**文件**: `src/hooks/useUpdateNotification.ts`
+
+React hook `useUpdateNotification(updatedVersion)` — 确保每次 semver 变更（major.minor.patch）只显示一次"重启以更新"消息，避免同一版本的重复通知。
+
+---
+
+## 更新日志
+
+**文件**: `src/utils/releaseNotes.ts`
+
+1. 从 `src/setup.ts:387` 在每次启动时调用
+2. 从 GitHub 获取 changelog
+3. 缓存到 `~/.claude/cache/changelog.md`
+4. 展示比 `lastReleaseNotesSeen` 更新的版本的更新日志
+5. 使用 semver 比较确定需要展示哪些日志
+
+---
+
+## 版本比较
+
+**文件**: `src/utils/semver.ts`
+
+- 提供 `gt()`、`gte()`、`lt()`、`lte()`、`satisfies()`、`order()`
+- 在 Bun 环境下使用 `Bun.semver.order()`（快 20 倍）
+- 在 Node.js 环境下回退到 npm `semver` 包
+
+---
+
+## 分析事件
+
+所有更新相关的遥测数据使用 `tengu_` 前缀的事件：
+
+| 类别 | 事件 |
+|---|---|
+| 版本检查 | `tengu_version_check_success`、`tengu_version_check_failure` |
+| JS 自动更新器 | `tengu_auto_updater_start/success/fail/up_to_date/lock_contention` |
+| 原生自动更新器 | `tengu_native_auto_updater_start/success/fail` |
+| 原生更新 | `tengu_native_update_complete/skipped_max_version/skipped_minimum_version` |
+| 锁机制 | `tengu_version_lock_acquired/failed`、`tengu_native_update_lock_failed` |
+| 二进制下载 | `tengu_binary_download_attempt/success/failure`、`tengu_binary_manifest_fetch_failure` |
+| 清理 | `tengu_native_version_cleanup`、`tengu_native_staging_cleanup`、`tengu_native_stale_locks_cleanup` |
+| 安装 | `tengu_native_install_package_success/failure`、`tengu_native_install_binary_success/failure` |
+| 手动更新 | `tengu_update_check` |
+| 迁移 | `tengu_migrate_autoupdates_to_settings`、`tengu_migrate_autoupdates_error` |
+
+---
+
+## 关键文件索引
+
+| 文件 | 职责 |
+|---|---|
+| `src/utils/autoUpdater.ts` | 核心逻辑：版本检查、npm 安装、文件锁、最低/最高版本门控 |
+| `src/cli/update.ts` | `claude update` 命令处理 |
+| `src/utils/nativeInstaller/installer.ts` | 原生二进制安装器：下载、版本管理、符号链接、清理 |
+| `src/utils/nativeInstaller/download.ts` | 从 GCS/Artifactory 下载二进制文件并校验 |
+| `src/utils/localInstaller.ts` | 本地安装器（`~/.claude/local/`）基于 npm |
+| `src/components/AutoUpdaterWrapper.tsx` | 基于安装类型的策略路由 |
+| `src/components/AutoUpdater.tsx` | JS/npm 后台自动更新器（30 分钟间隔） |
+| `src/components/NativeAutoUpdater.tsx` | 原生二进制后台自动更新器（30 分钟间隔） |
+| `src/components/PackageManagerAutoUpdater.tsx` | 包管理器通知（30 分钟，仅展示） |
+| `src/hooks/useUpdateNotification.ts` | 按 semver 去重更新通知 |
+| `src/utils/releaseNotes.ts` | Changelog 获取、缓存与展示 |
+| `src/utils/semver.ts` | Semver 版本比较（Bun 原生 + npm 回退） |
+| `src/utils/doctorDiagnostic.ts` | 安装类型检测与健康诊断 |
+| `src/utils/config.ts:1737` | `getAutoUpdaterDisabledReason()` — 禁用检查逻辑 |
+| `src/migrations/migrateAutoUpdatesToSettings.ts` | 旧版配置迁移 |
+| `src/screens/Doctor.tsx` | Doctor 命令 UI，展示自动更新状态 |
+
+---
+
+## 流程图
+
+```
+启动阶段
+  ├── assertMinVersion() → 版本过低时硬性拦截，拒绝启动
+  ├── migrateAutoUpdatesToSettings() → 一次性配置迁移
+  └── checkForReleaseNotes() → 展示新版本的更新日志
+
+REPL 运行中（每 30 分钟）
+  ├── AutoUpdaterWrapper 检测安装类型
+  │
+  ├── native → NativeAutoUpdater
+  │     ├── 从 GCS/Artifactory 获取版本
+  │     ├── 检查最大版本上限（服务端控制）
+  │     ├── 检查 minimumVersion 设置（跳过）
+  │     ├── acquireLock()
+  │     ├── downloadAndVerifyBinary()（SHA256 校验，3 次重试）
+  │     ├── 安装到 versions/ 目录
+  │     ├── 更新符号链接
+  │     └── cleanupOldVersions()（保留 2 个版本）
+  │
+  ├── npm-global/local → AutoUpdater
+  │     ├── 从 npm registry 获取最新版本
+  │     ├── semver 版本比较
+  │     ├── acquireLock()
+  │     └── npm install -g / 本地安装
+  │
+  └── package-manager → PackageManagerAutoUpdater
+        ├── 从 GCS 获取版本
+        └── 显示 "Run: brew upgrade ..."（不自动安装）
+
+手动操作
+  └── claude update → 完整诊断 + 安装编排
+```

docs/context/compaction.mdx

@@ -0,0 +1,131 @@
+---
+title: "上下文压缩"
+description: "对话历史不断增长，token 窗口有限。理解 Claude Code 的三层压缩策略、边界标记机制和紧急降级路径。"
+keywords: ["上下文压缩", "Compaction", "token 管理", "对话压缩"]
+---
+
+## 核心问题
+
+AI 没有真正的长期记忆——它只能看到当前 API 请求中的内容。随着对话增长，token 消耗持续上升，最终会触及模型的上下文窗口限制。
+
+压缩就是在"保留足够的语义信息"和"减少 token 占用"之间找平衡。
+
+## 三层递进策略
+
+系统不是用一种方法解决所有压缩需求，而是根据严重程度递进使用三种策略：
+
+| 层级 | 触发条件 | 是否需要 API 调用 | 成本 |
+|------|----------|:---:|------|
+| **微压缩** | 单个工具输出过长 | 否 | 几乎为零 |
+| **Session Memory 压缩** | 自动压缩触发时优先尝试 | 否 | 低（使用已提取的记忆） |
+| **AI 摘要压缩** | 上述方法不可用或用户手动触发 | 是 | 高（需要额外 API 调用） |
+
+### 设计哲学：从廉价到昂贵
+
+为什么不直接用 AI 摘要？因为 AI 摘要需要额外的 API 调用——既花钱又花时间。系统的策略是**先用确定性操作（廉价），不行再用 AI 生成（昂贵）**。
+
+这种分层设计意味着大部分情况下，系统可以在用户无感知的情况下释放足够的 token。
+
+## 第一层：微压缩（Micro-Compact）
+
+微压缩不生成摘要，只是清除旧的工具调用结果。
+
+### 工作原理
+
+AI 在工作过程中会产生大量工具输出：文件内容、命令结果、搜索匹配等。这些信息在产生时很重要，但随着对话推进，它们的价值迅速降低。
+
+微压缩识别这些"过期"的工具输出，将其替换为简短的占位符文本。原始内容仍保留在磁盘上的 transcript 文件中，只是不再发送给 API。
+
+### 时间衰减
+
+越旧的工具输出越容易被清除，最近操作的优先保留。这个策略基于一个经验观察：AI 通常只需要最近几步操作的上下文，更早的工具结果很少被再次引用。
+
+### 图片和文档的特殊处理
+
+图片和 PDF 文档的 token 占用远高于文本。微压缩会将大型图片和文档替换为文本标记（如 `[image]`），在保留"这里曾有一张图片"的语义的同时释放大量 token。
+
+## 第二层：Session Memory 压缩
+
+当微压缩释放的 token 不够时，系统优先尝试 Session Memory 压缩。
+
+### 设计思路
+
+系统在对话过程中会持续提取关键信息形成"Session Memory"。压缩时，直接使用这些已提取的记忆作为对话摘要，而不需要额外调用 AI 生成摘要。
+
+### 保留窗口
+
+压缩后保留的消息需要满足三个约束：
+
+- **最小深度**：至少保留 10K token 的最近对话（确保 AI 有足够的上下文）
+- **最小连续性**：至少保留 5 条包含文本的消息（确保对话连贯）
+- **最大上限**：不超过 40K token（避免保留太多又很快触发下一次压缩）
+
+这三个约束形成了"不要压缩太少（AI 会迷失），也不要保留太多（很快又需要压缩）"的平衡。
+
+### 工具对完整性
+
+这是一个关键的**正确性保证**：API 要求每个工具调用都有对应的工具结果，反之亦然。如果压缩恰好切在一个工具调用和它的结果之间，API 会报错。
+
+系统在计算压缩边界时，会自动向前或向后调整切分点，确保所有工具调用-结果对要么完整保留，要么一起被压缩。
+
+## 第三层：AI 摘要压缩
+
+当上述方法都不可用时（或用户手动触发 `/compact` 时），系统调用 AI 生成对话摘要。
+
+### 压缩前处理
+
+发送给摘要 AI 的消息会经过预处理：
+- 图片被替换为文本标记（防止摘要请求本身也超出 token 限制）
+- 会被重新注入的附件被剥离（避免重复）
+
+### 压缩后的重新注入
+
+压缩不是"砍掉旧对话就完了"。AI 在压缩后立即需要知道"现在正在做什么"。系统会在摘要后重新注入关键上下文：
+
+| 重新注入内容 | 预算 | 设计理由 |
+|-------------|------|----------|
+| 最近读取的文件（最多 5 个） | 每文件 5K token | AI 最可能需要的就是刚操作过的文件 |
+| 已激活的技能指令 | 每技能 5K，总计 25K | 保持 AI 的能力集不变 |
+| CLAUDE.md 内容 | 不限 | 用户的项目指令必须始终存在 |
+| MCP 工具发现结果 | 不限 | 保持工具可用性 |
+
+**设计洞察**：总共 50K token 的重新注入预算看起来是浪费——刚压缩释放的 token 立刻又被用掉了一部分。但这是必要的：没有这些重新注入，AI 在压缩后会"忘记"当前任务状态，导致糟糕的用户体验。
+
+## 边界标记：压缩的"墓碑"
+
+每次压缩后，系统在消息流中插入一条边界标记消息。这条消息不展示给用户，但记录了：
+- 压缩类型（自动/手动/微压缩）
+- 压缩前的 token 数
+- 哪些消息被保留
+
+后续所有操作只处理最后一条边界标记之后的消息。这防止了"重复压缩已经压缩过的内容"——每次压缩都是相对于上一次边界的新压缩。
+
+### 微压缩 vs 全量压缩的边界区别
+
+微压缩的边界标记更轻量——它只记录哪些工具结果被清除了，不生成摘要。原始消息仍然存在（只是内容被替换为占位符），而非被摘要替代。
+
+## 紧急降级：Prompt Too Long
+
+当压缩后仍然超出 token 限制时，系统进入紧急路径：
+
+1. **更激进的压缩**：尝试比正常压缩更激进的策略
+2. **直接截断**：从最早的对话开始删除，直到能塞进上下文窗口
+3. **放弃并报错**：如果以上都失败，向用户报告错误
+
+**设计哲学**：系统宁可丢失部分对话历史，也不让整个会话卡死。用户可以通过文件快照和 transcript 记录恢复丢失的信息。
+
+## Hook 机制
+
+压缩前后支持自定义 Hook：
+
+- **Pre-compact Hook**：压缩前执行，可以标记"必须保留"的内容
+- **Post-compact Hook**：压缩后执行，可以验证关键信息是否被保留
+- **Session Start Hook**：压缩后恢复 CLAUDE.md 等上下文
+
+这确保了用户的自定义逻辑在压缩过程中被尊重——例如，用户可以通过 Hook 确保某个关键文件的内容永远不会被压缩掉。
+
+## 接下来
+
+- **项目记忆** — 理解跨会话的记忆持久化设计
+- **令牌预算** — 了解 token 窗口的动态计算和阈值管理
+- **系统提示词** — 理解上下文组装的缓存优化策略

docs/context/project-memory.mdx

@@ -0,0 +1,137 @@
+---
+title: "项目记忆"
+description: "AI 没有真正的记忆。Claude Code 如何通过文件系统构建跨会话的记忆？理解存储架构、四类型分类法、智能召回和漂移防御设计。"
+keywords: ["项目记忆", "MEMORY.md", "AI 记忆", "跨对话", "自动记忆"]
+---
+
+## 核心问题
+
+AI 的每次 API 调用都是无状态的——模型只看到当前请求中的内容。这意味着每次新会话，AI 都从零开始，不知道你之前讨论过什么、你喜欢什么风格、项目有什么特殊约束。
+
+记忆系统的目标：**让 AI 在跨会话中保持连贯性**。
+
+## 存储架构：纯文件
+
+Claude Code 的记忆系统是**纯文件**的——没有数据库、没有向量存储，只有 Markdown 文件和目录结构。
+
+```
+~/.claude/projects/<项目目录>/memory/
+├── MEMORY.md                    ← 入口索引（每次对话加载）
+├── user_role.md                 ← 用户记忆
+├── feedback_testing.md          ← 反馈记忆
+├── project_mobile_release.md    ← 项目记忆
+└── reference_linear_ingest.md   ← 参考记忆
+```
+
+### 为什么选择文件而非数据库
+
+| 方案 | 优势 | 劣势 |
+|------|------|------|
+| **Markdown 文件** | 用户可直接编辑、git 友好、零依赖 | 查询需要扫描文件 |
+| SQLite 数据库 | 查询高效 | 用户无法直接编辑、需要额外依赖 |
+| 向量数据库 | 语义搜索强大 | 过度工程、引入复杂依赖 |
+
+选择文件的核心理由：**记忆应该是用户可以审查、编辑和删除的**。Markdown 文件让用户完全掌控 AI 记住了什么。如果 AI 记住了错误的信息，用户可以直接打开文件删除它。
+
+### MEMORY.md 索引
+
+`MEMORY.md` 是记忆系统的入口。每次对话开始时完整加载到上下文中。它不是记忆内容本身，而是一个链接索引：
+
+```markdown
+- [用户角色](user_role.md) — 深度 Go 开发者，React 新手
+- [测试反馈](feedback_testing.md) — 集成测试必须使用真实数据库
+```
+
+索引有双重上限（行数和字节数），防止索引本身占用过多 token。超过上限时自动截断——这确保记忆系统不会成为新的 token 负担。
+
+## 四类型分类法
+
+记忆被约束为一个封闭的四类型系统，每种类型有明确的用途和保存时机：
+
+| 类型 | 存储内容 | 设计目的 |
+|------|---------|----------|
+| **user** | 用户角色、偏好、技术背景 | 让 AI 理解"用户是谁" |
+| **feedback** | 用户对 AI 行为的纠正和确认 | 防止 AI 重复犯错或偏离已验证的工作方式 |
+| **project** | 无法从代码推导的项目上下文 | 记录"为什么这样决定"而非"代码长什么样" |
+| **reference** | 外部系统的指针 | 告诉 AI 去哪里找信息 |
+
+### 关键设计约束
+
+**只存储无法从当前项目状态推导的信息。** 代码架构、文件路径、git 历史都可以实时获取，不需要记忆。
+
+这条约束防止记忆系统变成冗余缓存。如果某个信息可以通过读代码获得，那就不应该记下来——因为代码是最新的，而记忆可能已经过时。
+
+### 反馈的双通道捕获
+
+反馈类型特别强调不仅要在用户纠正时保存（"不要这样做"），也要在用户确认时保存（"对，就是这样"）。
+
+**设计考量**：如果只记录纠正，AI 会避免过去的错误，但也会偏离用户已经验证过的工作方式，变得越来越保守。记录"成功路径"和记录"失败路径"同等重要。
+
+### 每条记忆的结构
+
+每条记忆文件都有 frontmatter 元数据：
+
+```markdown
+---
+name: 测试反馈
+description: 集成测试的数据库使用偏好
+type: feedback
+---
+
+集成测试必须使用真实数据库，不能 mock。
+**Why:** 上季度发生过 mock 通过但生产迁移失败的事故。
+**How to apply:** 所有涉及数据库的测试用真实实例。
+```
+
+`description` 字段不是给人读的摘要——它是给 AI 召回系统做相关性判断的搜索关键词。`Why` 和 `How to apply` 行帮助 AI 理解"为什么有这条规则"和"什么时候该应用它"。
+
+## 智能召回
+
+不是所有记忆都适合每次对话。用户可能在 50 个记忆文件中积累了大量信息，但一次对话通常只需要其中 3-5 条。
+
+### 召回架构
+
+系统使用一个轻量级的独立 AI 查询来筛选最相关的记忆：
+
+```
+用户消息
+  → 扫描所有记忆文件的元数据
+  → 独立 AI 查询：从所有记忆中选出最相关的 ≤5 条
+  → 只加载选中的记忆文件内容
+```
+
+**设计考量**：为什么不直接加载所有记忆？因为记忆文件会随时间增长，全部加载可能占用大量 token。使用独立查询筛选虽然多花一次 API 调用，但可以显著减少主对话的 token 消耗。
+
+### 去噪设计
+
+- **近期工具去噪**：当 AI 正在使用某个工具时，不召回该工具的使用文档（对话中已有工作上下文）。但仍召回关于这些工具的**警告和已知问题**——这正是使用时最关键的信息。
+- **已展示去重**：之前轮次已展示过的记忆不再重复召回，让有限的召回预算花在新的候选上。
+
+## 记忆漂移防御
+
+记忆可能过时。系统在 AI 的行为指令中设置了专门的防御：
+
+> 一条记忆提到某个函数或文件，只是声明它**在记忆被写入时**存在。它可能已被重命名、删除或从未合并。在推荐之前，先验证它是否还存在。
+
+这个指令从"行动导向"的角度设计——不是告诉 AI"记忆可能不准确"（太抽象），而是直接告诉它"在推荐之前先检查"（可操作）。
+
+### 忽略记忆的严格语义
+
+当用户说"忽略记忆"时，AI 必须做到真正的忽略——不应用、不引用、不比较、甚至不提及记忆内容。
+
+这解决了一个常见的 AI 反模式：用户说"忽略关于 X 的记忆"，AI 虽然正确识别了代码，但仍加上"不像记忆中说的 Y"——这不是"忽略"，而是"承认然后覆盖"。
+
+## 与上下文压缩的联动
+
+记忆系统与上下文压缩深度集成。当 Session Memory 功能启用时，压缩优先使用已提取的记忆作为摘要——不需要额外的 AI 调用生成摘要，更快、更便宜、且不会丢失信息。
+
+这形成了一个正向循环：
+1. 对话中积累信息 → 提取为记忆
+2. 上下文需要压缩时 → 使用记忆作为摘要
+3. 下次对话开始 → 通过智能召回加载相关记忆
+
+## 接下来
+
+- **自动记忆整理** — 了解 KAIROS 模式下的每日日志和蒸馏机制
+- **上下文压缩** — 理解记忆如何与压缩策略联动
+- **令牌预算** — 了解记忆加载的 token 开销管理

docs/context/system-prompt.mdx

@@ -0,0 +1,151 @@
+---
+title: "系统提示词"
+description: "系统提示词不是一段写死的文本，而是一个动态组装、分块缓存的数组。理解三阶段管道、缓存分界标记和多级优先级选择的设计。"
+keywords: ["系统提示词", "System Prompt", "动态组装", "Prompt Cache", "缓存策略"]
+---
+
+## 核心问题
+
+AI 的行为由系统提示词（System Prompt）决定。但一个编程助手的系统提示词远不止一句"你是一个有用的助手"——它需要包含工具使用规则、安全策略、项目上下文、用户偏好等大量动态内容。
+
+挑战在于：**这些内容每次请求都要发送，而且大部分是不变的。** 如何在保持动态性的同时最小化 token 成本？
+
+## 从文本到数组：缓存驱动的架构选择
+
+系统提示词不是单个字符串，而是一个 **字符串数组**。
+
+### 为什么是数组？
+
+Anthropic 的 Prompt Cache 以**内容块**为单位缓存。将提示词拆为多个块，不变的部分可以获得独立的缓存命中。如果是一个单字符串，任何一个字符变化（如日期更新）都会导致整个提示词的缓存失效。
+
+一个典型的系统提示词约 20K+ tokens，通过缓存分块可以节省 30-50% 的输入 token 费用。
+
+### 品牌类型保证
+
+系统使用品牌类型（branded type）防止普通字符串数组被意外传入 API 调用——只有通过显式转换才能获得系统提示词类型。这是零开销的编译时安全保证。
+
+## 三阶段组装管道
+
+```
+收集内容 → 选择优先级 → 分块 + 缓存标记
+```
+
+### 第一阶段：内容收集
+
+系统提示词的内容分为两个区域：
+
+| 区域 | 内容 | 特点 |
+|------|------|------|
+| **静态区** | 工具使用规则、安全策略、输出格式规范 | 所有用户相同 |
+| **动态区** | 记忆、MCP 指令、模型覆盖、语言偏好 | 因用户/会话而异 |
+
+两个区域之间用一个特殊的**分界标记**分隔。这个标记永远不会发送给 AI——它只是告诉缓存系统："到这里为止是静态的，从这里开始是动态的"。
+
+### 第二阶段：优先级选择
+
+最终使用哪个提示词取决于五级优先级：
+
+| 优先级 | 来源 | 场景 |
+|--------|------|------|
+| **Override** | 外部覆盖 | SDK 集成、自动化测试 |
+| **Coordinator** | 协调者模式 | 多 Agent 编排 |
+| **Agent** | Agent 定义 | 自定义 Agent |
+| **Custom** | 命令行参数 | 用户的自定义提示词 |
+| **Default** | 完整组装 | 正常使用 |
+
+**设计考量**：Override 级别完全替换默认提示词（包括安全规则），这是危险的但必要的——自动化测试和 SDK 集成需要完全控制。其他级别则在默认提示词基础上追加或替换。
+
+### 第三阶段：分块与缓存标记
+
+分块策略根据条件选择三种模式：
+
+**模式 1：全局缓存（1P 用户默认）**
+```
+[归属头]        → 不缓存
+[提示词前缀]    → 不缓存
+[静态内容]      → 全局缓存（跨组织共享）
+[动态内容]      → 不缓存
+```
+
+**模式 2：组织缓存（MCP 工具存在时）**
+```
+[归属头]        → 不缓存
+[提示词前缀]    → 组织缓存
+[其余内容]      → 组织缓存
+```
+
+**模式 3：组织缓存（3P 用户）**
+```
+[归属头]        → 不缓存
+[提示词前缀]    → 组织缓存
+[其余内容]      → 组织缓存
+```
+
+**为什么 MCP 工具会降级缓存**？MCP 工具列表在会话中可能变化（连接/断开），这会改变提示词内容，破坏跨组织缓存的基础。因此当 MCP 工具存在时，只能使用组织级缓存。
+
+### 缓存破坏的防御
+
+动态区的某些内容（如会话特定的工具集）必须严格放在分界标记之后。如果错误地放在静态区，每个运行时条件的组合会产生 2^N 种不同的哈希值（N = 条件数量），完全破坏缓存命中率。
+
+系统对"每轮都重新计算"的 Section 使用专门的危险标记——开发者必须给出破坏缓存的理由才能使用它。
+
+## 上下文注入：两条独立管道
+
+系统提示词本身不包含运行时上下文。上下文通过两条独立管道注入：
+
+### System Context（会话级不变）
+
+- Git 分支和状态
+- 最近的提交记录
+- 计算一次，整个会话期间缓存
+
+### User Context（动态变化）
+
+- 合并后的 CLAUDE.md 内容
+- 当前日期
+
+**为什么 User Context 不放在 System Prompt 中**？因为 User Context 作为用户消息发送，可以利用 Prompt Cache 的前缀共享——系统提示词是所有用户共享的前缀，User Context 是每个用户的变化部分。这种分层让缓存命中率最大化。
+
+## CLAUDE.md：项目级知识注入
+
+这是 Claude Code 最巧妙的设计之一。在项目目录中放一个 `CLAUDE.md` 文件，就能让 AI "理解"项目。
+
+### 多级合并
+
+```
+~/.claude/CLAUDE.md              ← 用户全局（个人偏好）
+  └── /project/CLAUDE.md         ← 项目根目录（团队共享）
+        └── /project/src/CLAUDE.md  ← 子目录（模块特定）
+```
+
+系统从当前工作目录向上遍历，合并所有匹配的 CLAUDE.md 文件。子目录的 CLAUDE.md 可以覆盖或补充父目录的规则。
+
+**设计哲学**：项目知识应该由团队成员维护、随代码演进、可通过 git 追踪。CLAUDE.md 本质上是"给人读的项目文档，恰好 AI 也能读"。
+
+### 安全考量
+
+项目级 CLAUDE.md 可以被仓库中的任何人修改（包括恶意贡献者）。系统因此限制了项目级 CLAUDE.md 的影响范围——它们不能覆盖安全关键设置，也不能修改权限模型。
+
+## Provider 差异与缓存
+
+不同的 API Provider 有不同的缓存能力：
+
+| Provider | 全局缓存 | 精确 Token 计数 | 特殊 Beta 功能 |
+|----------|:--------:|:---------------:|:--------------:|
+| Anthropic 直连 | ✓ | ✓ | ✓ |
+| AWS Bedrock | ✗ | ✓（独立端点） | 部分 |
+| Google Vertex | ✗ | ✗ | 部分 |
+| OpenAI 兼容 | ✗ | ✗ | ✗ |
+| Gemini | ✗ | ✗ | ✗ |
+
+3P 用户的系统提示词始终使用组织级缓存，因为没有全局缓存的 API 支持。这也意味着 token 计数依赖估算，影响自动压缩的触发时机。
+
+## 最小化模式
+
+环境变量 `CLAUDE_CODE_SIMPLE` 可以将整个系统提示词缩减为一行——跳过所有 Section 注册、缓存分块和动态组装。用于最小化 token 消耗的测试场景。
+
+## 接下来
+
+- **上下文压缩** — 理解当上下文增长超出限制时的压缩策略
+- **令牌预算** — 了解 token 窗口的动态计算
+- **Provider 系统** — 了解多 Provider 支持的架构设计

docs/context/token-budget.mdx

@@ -0,0 +1,128 @@
+---
+title: "令牌预算"
+description: "200K 上下文窗口不是全部。理解 Claude Code 如何管理 token 预算：动态计算、近似 vs 精确计数、分层压缩策略和缓存优化。"
+keywords: ["Token 预算", "上下文窗口", "token 计算", "压缩策略"]
+---
+
+## 核心约束：200K 不是全部
+
+Claude 的上下文窗口为 200K tokens（部分模型支持 1M），但实际可用于对话的空间远小于此：
+
+```
+上下文窗口（200K）
+├── 系统提示词（~15-25K）
+├── 工具定义（~10-20K，含 MCP 工具）
+├── 用户上下文（CLAUDE.md、git status 等）
+├── 输出预留（AI 响应的空间）
+└── 剩余：对话历史空间（随对话增长而缩小）
+```
+
+**设计挑战**：对话历史不断增长，可用空间持续缩小。系统必须在"保留足够的上下文让 AI 理解对话"和"不超出 token 限制"之间持续平衡。
+
+### 上下文窗口的动态解析
+
+上下文窗口大小不是硬编码的。系统按优先级从多个来源解析：
+
+1. 用户环境变量覆盖（强制指定）
+2. 模型名后缀标记（如 `[1m]` 表示 1M 窗口）
+3. 模型自身的能力声明
+4. 特定 beta 功能的支持情况
+5. 兜底值：200K
+
+这种分层解析意味着同一个系统可以适配不同模型和不同配置，而不需要为每种情况写特殊逻辑。
+
+## Token 计数：近似 vs 精确
+
+Token 计数是所有预算决策的基础。系统采用两级策略：
+
+### 近似估算（毫秒级）
+
+基于一个简单的经验公式：大约每 4 个字节 ≈ 1 个 token。对不同内容类型有调整：
+- **JSON/JSONL**：更密集，每 2 字节 ≈ 1 token
+- **图片/文档**：固定估算值（基于尺寸上限的保守估计）
+- **普通文本**：每 4 字节 ≈ 1 token
+
+### 精确计数（需要 API 调用）
+
+使用 Anthropic 的 token 计数端点。不同 Provider 的支持程度不同：
+
+| Provider 类别 | 精确计数支持 | 注意事项 |
+|---------------|-------------|----------|
+| Anthropic 直连 | 原生支持 | 最准确 |
+| 云平台（Bedrock/Vertex） | 各自的 SDK 接口 | 需要额外依赖 |
+| 第三方兼容（OpenAI/Gemini/Grok） | 不支持 | 退回近似估算 |
+
+### 为什么需要两级策略
+
+近似估算用于**热路径**——每轮 agentic loop 都需要判断"是否需要压缩"，这个检查必须足够快。精确计数用于**关键决策点**——压缩前后对比、费用计算等需要准确数字的场景。
+
+**设计权衡**：近似估算可能偏差 10-20%，这意味着自动压缩的触发时机可能略有提前或延后。但这个偏差是可以接受的——提前压缩只多花一点 token，延后压缩最多触发一次 API 错误然后紧急压缩。
+
+## 分层压缩策略
+
+系统不是等到"满了才压缩"，而是采用了由轻到重的分层策略：
+
+### 第一层：工具结果截断
+
+单个工具的输出有硬性上限（通常 100K 字符）。超长的命令输出、文件内容在写入消息前就被截断。
+
+这是最轻量的"压缩"——只是防止单个工具结果占用过多空间。
+
+### 第二层：微压缩（Micro-Compact）
+
+在触发全量压缩之前，系统先尝试只压缩旧的工具调用结果：
+
+- 超过一定时间的工具结果被替换为简短占位符
+- 图片/文档结果替换为 `[image]` / `[document]` 文本
+- 每次替换释放 token，可能推迟全量压缩的触发
+
+**设计考量**：为什么不直接全量压缩？因为全量压缩需要调用 AI 生成摘要，成本高且耗时。微压缩是确定性操作（简单替换），几乎零成本，可以频繁执行。
+
+### 第三层：自动压缩（Auto-Compact）
+
+当对话接近 token 上限时，系统用 AI 自身来总结之前的对话：
+
+1. **剥离非必要内容**：图片、文档附件被替换为文本标记
+2. **生成摘要**：通过一个独立的 agent 调用生成对话摘要
+3. **重建上下文**：用摘要替代原始对话，同时重新注入关键信息（最近操作的文件、活跃的计划等）
+
+**设计考量**：压缩后会重新读取最近操作的 5 个文件。这是因为在实际使用中，AI 最可能需要的就是刚刚操作过的文件——重新读取它们比让 AI 再次搜索更高效。
+
+### 压缩的安全阀
+
+- **连续失败上限**：连续 3 次压缩失败后停止尝试（断路器模式）
+- **压缩来源的查询不触发压缩**：防止压缩本身触发无限递归
+- **手动压缩**：用户可以随时通过 `/compact` 主动触发
+
+## 缓存感知的压缩设计
+
+压缩操作本身需要调用 API 生成摘要——这是整个会话中最昂贵的操作之一。系统通过**复用主线程的缓存前缀**来优化：
+
+系统 prompt + 工具定义 + 上下文消息通常不变，这部分可以通过 API 的 prompt cache 机制缓存。压缩时的摘要请求复用了这些缓存，使得缓存命中率从接近 0% 提升到接近 100%。
+
+**设计洞察**：这不是一个独立的优化——它是整个缓存策略的一部分。系统 prompt 的组装策略（"不变内容在前"）和压缩时的缓存复用，都是为了最大化 prompt cache 的命中率。
+
+## 输出 Token 的 Slot 优化
+
+一个容易被忽视但影响深远的优化：AI 输出的 token 上限默认只设为 8K，而不是模型支持的最大值（32K 或 64K）。
+
+**为什么**？因为 API 服务端按 `max_tokens` 参数预留推理容量（slot）。99% 的请求实际输出不到 5K tokens，但如果所有请求都预留 32K 的 slot，会导致严重的容量浪费。
+
+降到 8K 后，不到 1% 的请求会被截断——这些请求自动获得一次高上限的干净重试。
+
+**设计哲学**：用 1% 的请求多一次重试的代价，换取 99% 请求的更快响应。这是一个典型的"优化常见路径，用重试处理边缘情况"的设计模式。
+
+## 选择性压缩
+
+除了全量压缩，用户还可以选择只压缩对话的某一部分：
+
+- **压缩早期内容**（保留最近对话）：适用于"开头说了很多背景，但后面只需要关注最近操作"的场景
+- **压缩近期内容**（保留早期对话）：适用于"早期的架构决策很重要，但最近的工具调用结果不需要"的场景
+
+两种方向对缓存有不同的影响——保留前缀（早期内容）可以维持 prompt cache，修改前缀则破坏缓存。
+
+## 接下来
+
+- **上下文压缩** — 深入了解压缩的触发条件和摘要生成机制
+- **项目记忆** — 理解跨会话的记忆持久化设计
+- **穷鬼模式** — 了解如何减少 token 消耗

docs/conversation/multi-turn.mdx

@@ -0,0 +1,130 @@
+---
+title: "多轮对话"
+description: "理解 Claude Code 的会话编排设计：为什么需要 QueryEngine？会话如何持久化？成本如何追踪？模型如何热切换？"
+keywords: ["多轮对话", "会话管理", "QueryEngine", "transcript", "成本追踪"]
+---
+
+## 单轮 vs 多轮
+
+- **单轮**（一次 Agentic Loop）：用户说一句话，AI 可能执行多步工具调用后返回结果
+- **多轮**（一个会话）：用户和 AI 反复对话，持续数分钟到数小时
+
+单轮关注"AI 如何自主完成任务"，多轮关注"如何管理一个持续演进的会话"——这是完全不同的工程问题。
+
+## 为什么需要会话编排器
+
+单轮的 Agentic Loop 已经很复杂了（错误恢复、上下文压缩、流式处理）。多轮在此基础上还需要管理：
+
+- **对话历史的累积**：消息不断增长，需要压缩策略
+- **成本的持续追踪**：跨轮次的 token 用量累计
+- **模型的热切换**：用户可能中途换模型
+- **会话的持久化与恢复**：意外中断后能继续
+- **文件的快照与回滚**：AI 改了文件，用户想撤回
+
+这些职责与"执行一次 agentic loop"无关，所以系统引入了 **QueryEngine** 作为会话编排器——它在 Agentic Loop 之上管理会话级别的状态。
+
+### 设计原则：编排器不参与循环
+
+QueryEngine 只负责"准备好上下文，然后调用 agentic loop"。它不干预单轮循环的内部逻辑——循环中的错误恢复、工具执行、上下文压缩都是自治的。
+
+这种分层使得 agentic loop 可以独立测试和优化，而不受会话状态管理的影响。
+
+## 会话持久化
+
+### 为什么持久化很重要
+
+终端会话是脆弱的——网络断开、进程崩溃、意外关闭都可能丢失对话。持久化确保用户的工作不丢失。
+
+### 设计选择：JSONL 追加写入
+
+对话事件以 JSONL（每行一条 JSON）格式追加写入磁盘。
+
+为什么选择 JSONL 而不是数据库或 JSON 文件？
+
+| 方案 | 优势 | 劣势 |
+|------|------|------|
+| **JSONL 追加写入** | 写入快速、不需要读-改-写、崩溃安全 | 查询需要扫描整个文件 |
+| JSON 文件 | 结构清晰 | 每次写入需要读取整个文件、修改、写回——大文件很慢 |
+| SQLite 数据库 | 查询高效 | 引入额外依赖、事务管理复杂 |
+
+追加写入是关键设计：每次新消息只需要在文件末尾追加一行，不需要读取和修改已有内容。即使写入过程中崩溃，也只会丢失最后一条记录，不会损坏整个文件。
+
+### 存储结构
+
+```
+~/.claude/projects/<项目目录>/
+  ├── <session-1>.jsonl
+  ├── <session-2>.jsonl
+  └── ...
+```
+
+每个项目的会话归入同一目录。同一项目的对话可以跨会话积累上下文。
+
+### 大小防护
+
+读取上限为 50MB。超过这个大小的会话文件不会被完整加载——这是防止超大会话导致内存溢出的安全措施。
+
+### 会话恢复
+
+当用户使用 `--resume` 恢复会话时，系统：
+
+1. 从 JSONL 文件重建消息数组
+2. 恢复累计费用状态
+3. 恢复用户选择的模型和配置
+4. 从中断点继续对话
+
+整个过程对用户是透明的——恢复后的对话就像从来没有中断过。
+
+## 成本追踪
+
+### 为什么需要成本追踪
+
+AI API 按 token 计费，一次复杂任务可能消耗大量 token。没有成本追踪，用户无法判断"这次对话花了多少钱"，也无法在费用过高时及时终止。
+
+### 三层追踪架构
+
+| 层 | 职责 | 持久性 |
+|----|------|--------|
+| **记录层** | 从每个 API 响应中提取 token 用量 | 实时 |
+| **累计层** | 按模型汇总累计费用（切换模型时分别统计） | 会话内 |
+| **持久化层** | 会话结束时保存到项目配置 | 跨重启 |
+
+### 预算提醒
+
+系统提供会话级的预算上限。当累计费用超过阈值时弹出提醒——这不是硬性阻断，而是"软提醒"。设计上选择了提醒而非强制终止，因为用户可能正在进行关键操作（如修复生产 bug），强制终止可能造成更大损失。
+
+## 模型热切换
+
+### 设计挑战
+
+在一个持续对话中切换模型看似简单，实际上需要解决几个问题：
+
+1. **上下文窗口不同**：Sonnet 的 200K 和 Opus 的 1M 需要不同的压缩策略
+2. **对话历史兼容**：旧模型生成的内容新模型需要能理解
+3. **费用计算**：不同模型定价不同，需要分别统计
+
+### 设计决策：消息与模型解耦
+
+对话历史（消息数组）和模型选择是独立的。切换模型只改变"下一次 API 调用用什么模型"，不修改已有消息。系统会在下次调用前根据新模型的规格重新计算上下文窗口和输出限制。
+
+这意味着用户可以在对话中随时切换模型——例如用便宜的 Sonnet 做简单操作，遇到复杂问题时切换到 Opus——而不需要开始新的会话。
+
+## 文件快照与回滚
+
+### 比 git 更细粒度的追踪
+
+AI 每次修改文件前，系统自动保存当前文件内容的快照。快照绑定到具体的消息 ID，使得用户可以精确恢复到对话中任意时间点的文件状态。
+
+这比 `git checkout` 更细粒度——git 只追踪已提交的内容，而文件快照追踪的是 AI 每一次修改前的状态。
+
+### 使用场景
+
+- AI 改了代码但用户不满意 → 回滚到修改前的状态
+- AI 进行了多轮修改 → 选择性回滚到某个中间状态
+- 用户关闭终端后想撤销 → 通过会话恢复 + 文件回滚实现
+
+## 接下来
+
+- **系统提示词** — 理解每轮对话前的上下文组装策略
+- **上下文压缩** — 深入了解对话过长时的自动压缩机制
+- **令牌预算** — 理解 token 预算管理和成本控制

docs/conversation/streaming.mdx

@@ -0,0 +1,111 @@
+---
+title: "流式响应"
+description: "为什么流式是 Claude Code 的核心设计选择？理解流式传输的设计考量、错误处理策略和多 Provider 适配。"
+keywords: ["流式响应", "SSE", "streaming", "API streaming"]
+---
+
+## 为什么流式是核心设计
+
+想象 AI 需要 30 秒才能生成完整回答——如果等 30 秒后才一次性显示，用户体验是灾难性的。
+
+但流式不仅仅是为了"打字机效果"。在 Claude Code 中，流式是整个系统架构的基础假设：
+
+- **工具并行执行**：AI 在流式输出过程中就可能发出工具调用，系统可以立即开始执行，不必等整个响应结束。这使得"AI 边想边做"成为可能
+- **实时反馈**：用户看到 AI 的思考方向后可以提前判断是否正确，必要时提前中断
+- **可取消性**：流式架构天然支持用户中断——随时可以终止正在进行的流
+- **工具执行反馈**：不仅是 AI 输出是流式的，工具执行（如 shell 命令）的输出也是流式的——用户实时看到命令输出
+
+**代价**：流式架构比一次性响应复杂得多——需要处理连接中断、部分数据、乱序事件等边界情况。
+
+## 流式响应的概念模型
+
+一次流式响应不是"一个完整的回答"，而是一系列按顺序到达的事件流：
+
+```
+消息开始
+  ├── 内容块 1：文本 "我来帮你修复这个 bug。"
+  ├── 内容块 2：工具调用 { name: "Read", input: "..." }
+  ├── 内容块 3：文本 "我看到了问题..."
+  └── ...
+消息结束（包含停止原因和 token 用量）
+```
+
+关键设计点：
+
+### 内容块的增量累加
+
+每个内容块（文本、思考、工具调用）都是通过增量数据逐步构建的。文本逐字到达，工具调用的 JSON 参数逐段到达。系统需要在内存中持续累加这些片段，直到一个内容块完整后才传递给消费者。
+
+### 多消息产出
+
+因为一次 AI 响应可能包含多个内容块（文本和工具调用交替出现），每个完整的内容块都会触发一次消息传递。这意味着一个 API 响应会产生**多条消息**——文本消息和工具调用消息交替产出。
+
+### 停止原因的回写
+
+AI 最终是"回答完毕"还是"需要调用工具"，这个信息要到最后才知道。所以停止原因是在消息结束时**回写**到最后一条消息上的——消费者在收到中间消息时还不知道整轮对话是否结束。
+
+## 错误处理：三层防护
+
+流式连接比一次性请求脆弱得多——网络波动、服务器过载、连接超时都可能导致中断。系统设计了三层防护：
+
+### 第一层：被动停滞检测
+
+系统记录每个事件到达的时间间隔。当间隔超过 30 秒时，记录为一次"停滞"并写入遥测。这是被动检测——只在下一个事件到达时才能发现之前的停滞，不会主动中断流。
+
+**设计考量**：为什么不立即中断？因为 API 可能在做长时间的计算（如复杂推理），短暂的无响应不一定意味着故障。被动检测提供了观测能力，而不影响正常流程。
+
+### 第二层：主动空闲超时
+
+如果 90 秒内没有收到任何事件（可通过环境变量配置），系统主动终止流并进入重试流程。
+
+**设计考量**：这是兜底机制。真正的故障不能靠被动检测发现——因为被动检测依赖于"下一个事件到达"，而如果连接已经死了，下一个事件永远不会到达。
+
+### 第三层：非流式降级
+
+作为最后手段，系统可以回退到非流式请求——一次性获取完整响应。失去了实时性，但保证了功能可用性。
+
+### 降级策略对比
+
+| 策略 | 检测方式 | 响应时间 | 用户体验 |
+|------|----------|----------|----------|
+| 正常流式 | — | 最低延迟 | 逐字显示 |
+| 被动停滞检测 | 下一个事件到达时 | 不变 | 无感知 |
+| 主动超时中断 | 定时器触发 | 中断后重试延迟 | 短暂停顿后恢复 |
+| 非流式降级 | 重试失败后 | 等待完整响应 | 等待后一次性显示 |
+
+## Token 超限的两种场景
+
+两种不同的 token 超限需要不同的处理策略：
+
+| 场景 | 含义 | 处理方式 |
+|------|------|----------|
+| **输出超限** | AI 话说了一半被切断 | 提升输出上限重试，或提示 AI "接着说" |
+| **上下文窗口超限** | 整个对话历史太长，塞不进 API | 触发自动压缩，用 AI 摘要替代原始对话 |
+
+关键区别：输出超限是"AI 话太多"，可以通过调整上限解决；上下文超限是"给 AI 看的东西太多"，必须通过压缩或删除来减少。
+
+## 工具执行的流式反馈
+
+不仅是 API 响应是流式的，工具执行本身也是流式的。例如 BashTool 执行 shell 命令时，命令的标准输出会实时推送给 UI——用户不需要等命令完全结束才能看到结果。
+
+长时间运行的命令还支持**自动后台化**：如果命令执行超过一定时间，系统自动将其移到后台，AI 可以继续处理其他任务，命令完成后再回调结果。
+
+## 多 Provider 适配
+
+系统支持 7 种 API Provider，每种有不同的流式协议和认证方式：
+
+| Provider 类别 | 流式方式 | 设计挑战 |
+|---------------|----------|----------|
+| Anthropic 直连 | 原生 SSE | 基准实现，其他 Provider 对齐它 |
+| 云平台（Bedrock/Vertex） | SDK 封装的流式接口 | 需要适配认证、beta header、参数格式 |
+| 第三方兼容（OpenAI/Gemini/Grok） | 各自的流式协议 | 需要转换为 Anthropic 内部格式 |
+
+**设计策略**：所有 Provider 通过统一的流式抽象层屏蔽差异。上层代码（编排层、交互层）不需要关心底层用的是哪个 Provider——它们只看到统一的事件流。
+
+这意味着切换 Provider 不需要修改任何业务逻辑，只需要在通信层适配新的协议。这也是为什么"通信层"是独立的一层。
+
+## 接下来
+
+- **多轮对话** — 理解跨迭代的上下文管理
+- **上下文压缩** — 深入了解 token 超限时的自动压缩机制
+- **工具系统** — 了解工具执行的并行策略

docs/conversation/the-loop.mdx

@@ -0,0 +1,166 @@
+---
+title: "Agent Loop"
+description: "理解 Claude Code 的核心循环机制——AI 如何自主决定工具调用、处理错误、管理上下文，直到任务完成。"
+keywords: ["Agentic Loop", "tool_use", "状态机", "auto-compact", "streaming"]
+---
+
+## 什么是 Agentic Loop
+
+传统聊天机器人：你问一句，它答一句。
+Claude Code 不一样：你说一个需求，它可能连续执行十几步操作才给你最终结果。
+
+这背后的机制叫做 **Agentic Loop**（智能体循环）。它是一个"思考→行动→观察"的不断循环，直到任务完成或遇到终止条件。
+
+<Frame caption="Agentic Loop 循环示意">
+  <img src="/docs/images/agentic-loop.png" alt="Agentic Loop 循环图" />
+</Frame>
+
+### 为什么需要循环而非一次回答
+
+因为软件工程任务本质上是**探索性**的。AI 不可能在第一步就知道所有信息：
+
+- 它需要先读代码才能知道怎么改
+- 它需要先运行命令才能知道结果
+- 它需要先搜索才能找到相关文件
+- 它需要先修改才能验证是否正确
+
+每一步工具执行都产生**真实信息**——命令输出、文件内容、错误信息——这些是 AI 在执行前不可能预知的。因此，AI 必须在每一步后根据新信息重新决策。
+
+## 循环的四个阶段
+
+每次循环迭代包含四个阶段，形成一个完整的"感知→决策→执行→反馈"周期。
+
+### 阶段一：上下文预处理
+
+在调用 API 之前，系统会依次检查和处理上下文。这是一个串行管道，每一步的输出是下一步的输入：
+
+```
+原始消息
+  → 工具结果截断（单条输出过长时截断）
+  → 历史压缩（Snip 压缩旧消息）
+  → 微压缩（工具结果摘要化）
+  → 自动压缩（对话接近 token 上限时触发 AI 摘要）
+处理后的消息 → 发往 API
+```
+
+**设计考量**：为什么是串行管道而非一次性处理？因为每个步骤释放的 token 数会影响下一步的决策。例如，如果 Snip 压缩已经释放了足够的 token，自动压缩就不需要触发了。
+
+### 阶段二：流式 API 调用
+
+系统以流式方式调用 Claude API。流式传输不是"锦上添花"——它是核心设计决策：
+
+- **用户体验**：用户看到 AI 逐字输出，而非等待数秒后一次性显示
+- **工具并行执行**：AI 在流式输出过程中就可能发出工具调用，系统可以立即开始执行，不必等流结束
+- **可取消性**：用户随时可以中断正在进行的流式响应
+
+### 阶段三：工具执行
+
+如果 AI 请求了工具调用，系统执行工具并将结果回传。这里有两个关键设计：
+
+**并行执行**：当 AI 在一次响应中请求多个独立工具调用时（如同时读两个文件），系统并行执行它们。这直接减少了用户等待时间。
+
+**权限检查**：每个工具执行前都经过权限验证。危险操作（如执行 shell 命令）需要用户确认，安全操作（如读文件）可以自动放行。
+
+### 阶段四：终止或继续
+
+每次迭代结束时，系统判断是否需要继续：
+
+| 条件 | 结果 |
+|------|------|
+| AI 请求了工具调用 | 继续（下一轮迭代） |
+| AI 只返回文本，没有工具调用 | 终止（任务完成） |
+| 用户中断 | 终止（用户取消） |
+| 达到最大 turn 数 | 终止（安全限制） |
+| Token 预算耗尽 | 终止（成本控制） |
+
+## 错误恢复：自愈的状态机
+
+Agentic Loop 不是"正常路径走完就结束"的简单循环。它包含了多层错误恢复机制，使系统在各种异常情况下都能优雅处理。
+
+### 输出截断恢复
+
+当 AI 的响应被 token 上限截断时（AI 话说了一半被切断）：
+
+1. **首次截断**：静默提升输出 token 上限，重试
+2. **仍然截断**：注入提示消息让 AI "接着说"，最多重试 3 次
+3. **恢复耗尽**：将截断的响应作为最终结果返回
+
+### 上下文过长恢复
+
+当对话历史超过 API 的 token 限制时（413 错误）：
+
+1. **压缩重试**：即时压缩对话历史，生成摘要后重试
+2. **压缩后仍过长**：返回错误信息，让用户决定如何处理
+
+关键设计：系统通过标志位防止无限循环——每种恢复路径只尝试一次，不会在"压缩→失败→压缩"之间死循环。
+
+### 模型降级
+
+当主模型不可用时（过载、维护等）：
+
+1. 已收集的响应被保留为历史记录
+2. 自动切换到备用模型
+3. 通知用户发生了降级
+4. 从中断点继续，而不是从头开始
+
+## 状态管理
+
+每次迭代的状态是不可变更新的——系统创建新的状态对象而非就地修改。状态中包含：
+
+- **对话消息**：当前所有消息的数组
+- **压缩跟踪**：压缩操作的累计状态
+- **恢复计数**：各种错误恢复已尝试的次数
+- **继续原因**：上一轮为什么继续（用于检测和避免循环）
+
+**设计考量**：状态中记录"继续原因"是一个关键的防循环机制。系统可以在后续迭代中检查"上一轮是因为压缩重试而继续的"，从而避免在同一个恢复路径上反复尝试。
+
+## 为什么不是"一次规划，批量执行"
+
+一个自然的疑问是：为什么不先让 AI 规划好所有步骤，然后一次性批量执行？
+
+答案在于软件工程的**不确定性**：
+
+- **每步结果影响下一步**：搜索结果决定了要改哪些文件，修改后的编译结果决定了是否需要进一步调整
+- **错误需要即时修正**：如果某步失败，AI 需要立即调整策略，而非继续执行无效计划
+- **用户可能中途干预**：循环架构允许用户随时打断和修正方向
+
+这不是说 AI 不做规划——事实上系统内置了规划模式（Plan Mode）用于复杂任务。但规划的结果仍然是逐步执行的，每一步都有机会根据新信息调整。
+
+## 一个完整的迭代示例
+
+> 用户："帮我找到项目里所有未使用的导入语句，然后删掉它们"
+
+```
+迭代 1: 探索
+  AI: 先找到所有 TypeScript 文件
+  工具: Glob("**/*.ts") → 返回 42 个文件
+  决策: 需要进一步分析 → 继续
+
+迭代 2: 分析
+  AI: 搜索这些文件中的 import 语句
+  工具: Grep("import.*from") → 在 15 个文件中找到 120 条 import
+  决策: 结果太多，需要进一步筛选 → 继续
+
+迭代 3: 精确修改
+  AI: 分析哪些 import 未被使用，删除它们
+  上下文预处理: 120 条结果被微压缩为摘要
+  工具: FileEdit × 3 → 删除 5 条未使用导入
+  决策: 需要验证 → 继续
+
+迭代 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

@@ -0,0 +1,107 @@
+---
+title: "自定义 Agent"
+description: "用 Markdown 文件定义自己的 Agent。理解 Agent 定义的数据模型、工具过滤策略和与 AgentTool 的联动。"
+keywords: ["自定义 Agent", "Agent 定义", "Markdown Agent", "角色定制"]
+---
+
+## 核心概念
+
+自定义 Agent 是一个 Markdown 文件——frontmatter 定义配置，正文是 system prompt。不需要写代码。
+
+```markdown
+---
+name: "reviewer"
+description: "Code review specialist"
+tools: "Read,Glob,Grep"
+model: "haiku"
+---
+
+你是代码审查专家。你的职责是...
+```
+
+这个 Markdown 文件就定义了一个完整的 Agent：它使用什么工具、什么模型、什么行为规则。
+
+## Agent 的三种来源
+
+| 来源 | 位置 | 优先级 |
+|------|------|--------|
+| **Built-in** | 硬编码 | 最低（可被覆盖） |
+| **Plugin** | 插件系统注册 | 中 |
+| **User/Project** | `.claude/agents/*.md` | 最高 |
+
+合并时按 `agentType` 去重，后者覆盖前者。这意味着你可以在 `.claude/agents/` 中放一个 `Explore.md` 来完全替换内置的 Explore Agent。
+
+## 配置字段
+
+### 工具控制
+
+- `tools` — 允许的工具白名单（未指定 = 全部工具）
+- `disallowedTools` — 显式禁止的工具（即使 `tools` 未指定也生效）
+
+**设计考量**：`disallowedTools` 是比 `tools` 更安全的控制方式。如果只指定 `tools` 白名单，新增工具时需要更新白名单。`disallowedTools` 是黑名单思维——默认允许，只禁止危险的。
+
+### 模型配置
+
+- `model` — 指定模型（`haiku`/`sonnet`/`opus`/`inherit`）
+- `effort` — 推理努力程度（`low`/`medium`/`high`）
+
+`inherit` 使用主线程的模型——适合需要完整推理能力的任务。`haiku` 适合轻量任务（如搜索），更便宜更快。
+
+### 行为控制
+
+- `maxTurns` — 最大 agentic 轮次（防止无限循环）
+- `permissionMode` — 权限模式（`plan`/`bypassPermissions` 等）
+- `background` — 始终作为后台任务运行
+- `isolation` — 在独立 worktree 中运行
+
+### 持久化
+
+- `memory` — 启用跨会话的持久记忆（`user`/`project`/`local`）
+- `mcpServers` — 引用或内联定义 MCP 服务器
+- `hooks` — Agent 专属的 Hook 配置
+- `skills` — 预加载的技能
+
+## System Prompt 的注入方式
+
+Agent 的 Markdown 正文**完全替换**默认的 system prompt，而非追加。这意味着自定义 Agent 的行为完全由你定义——不受默认 prompt 的约束。
+
+如果启用了 `memory`，记忆指令自动追加到 system prompt 末尾。
+
+## 工具过滤流程
+
+```
+全部工具 → disallowedTools 移除 → tools 白名单过滤 → 可用工具
+```
+
+内置 Explore Agent 的工具限制是很好的例子：
+- 禁止 `Agent`（不能嵌套调用子 Agent）
+- 禁止 `FileEdit`/`FileWrite`（只读）
+- 禁止 `ExitPlanMode`（不需要 plan mode）
+
+这些限制让 Explore Agent 成为一个纯粹的搜索工具——它只能看，不能改。
+
+## 与 AgentTool 的联动
+
+当主 Agent 需要派生子 Agent 时：
+
+```
+查找 Agent 定义 → 检查 MCP 依赖 → 过滤工具 → 解析模型 → 构建隔离环境 → 注入 system prompt → 启动子 Agent
+```
+
+每一步都使用 Agent 定义中的配置——工具列表、模型选择、权限模式、隔离环境等。
+
+## 内置 Agent 参考
+
+| Agent | 角色 | 工具限制 | 模型 |
+|-------|------|---------|------|
+| General Purpose | 通用任务 | 全部工具 | 继承主线程 |
+| Explore | 代码搜索 | 只读 | haiku |
+| Plan | 规划研究 | 只读 + ExitPlanMode | 继承主线程 |
+| Verification | 结果验证 | 由 feature flag 控制 | — |
+| Code Guide | 使用指南 | 只读 | — |
+
+## 接下来
+
+- **子 Agent** — 理解子 Agent 的完整执行链路
+- **Skills** — 理解 Skill 中指定 Agent 定义
+- **MCP 配置** — 理解 Agent 中引用 MCP 服务器

docs/extensibility/hooks.mdx

@@ -0,0 +1,148 @@
+---
+title: "Hooks"
+description: "Hooks 是 Claude Code 的扩展机制——在工具调用前后注入自定义逻辑。理解四种 Hook 能力、匹配机制和安全防护。"
+keywords: ["Hooks", "生命周期钩子", "拦截器", "PreToolUse", "Hook 协议"]
+---
+
+## 核心问题
+
+Claude Code 提供了强大的内置功能，但每个团队和工作流都不同。Hooks 让你可以在关键节点注入自定义逻辑——不需要修改 Claude Code 本身。
+
+## Hook 事件
+
+Hooks 覆盖 Agent 生命周期的所有关键节点：
+
+| 阶段 | 典型事件 |
+|------|---------|
+| **会话** | 启动、结束、初始化 |
+| **用户交互** | 提交消息、停止响应 |
+| **工具执行** | 工具调用前、工具调用后（成功/失败） |
+| **权限** | 权限请求、权限被拒 |
+| **子 Agent** | 启动、停止 |
+| **压缩** | 压缩前、压缩后 |
+| **协作** | Teammate 空闲、任务创建/完成 |
+
+## 四种 Hook 能力
+
+Hook 不仅是"执行一个脚本"——它有四种不同的能力：
+
+### 1. 拦截操作（PreToolUse）
+
+在工具执行前拦截，可以阻止危险操作：
+
+```json
+{
+  "hookSpecificOutput": {
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "不允许在生产分支上强制推送"
+  }
+}
+```
+
+### 2. 修改行为
+
+修改工具的输入或输出：
+
+```json
+{
+  "hookSpecificOutput": {
+    "updatedInput": { "command": "npm test -- --bail" }
+  }
+}
+```
+
+PostToolUse 的 `updatedMCPToolOutput` 可以替换 MCP 工具的返回值——用于过滤敏感数据。
+
+### 3. 注入上下文
+
+向 AI 的对话中注入额外信息：
+- `additionalContext` — 注入为用户消息，AI 可以参考
+- `systemMessage` — 显示为系统警告
+
+### 4. 控制流程
+
+阻止 Agent 继续执行：
+
+```json
+{
+  "continue": false,
+  "stopReason": "构建失败，停止执行"
+}
+```
+
+**设计洞察**：四种能力从"被动观察"到"主动干预"递进。最简单的 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 可以注册 session Hook，绑定到特定的 session ID。Agent 结束时自动清理——Agent A 的 Hook 不会泄漏到 Agent B 的执行中。
+
+**设计考量**：如果不自动清理，Agent A 的 PreToolUse 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

@@ -0,0 +1,109 @@
+---
+title: "MCP 协议"
+description: "从配置到可用工具：MCP 连接管理、内置 vs 外部两种模式、工具发现和执行链路的设计。"
+keywords: ["MCP", "Model Context Protocol", "工具扩展", "MCP 客户端", "工具发现"]
+---
+
+## 核心问题
+
+MCP 让 Claude Code 使用外部工具。但连接外部服务有延迟、可能失败、工具列表可能变化。如何管理这些不确定性？
+
+## 架构总览
+
+```
+配置（多来源合并） → 连接管理（缓存） → 工具发现（MCP 协议） → 工具执行
+```
+
+## 两种 MCP 模式
+
+### 内置 MCP 服务器
+
+Computer Use、Chrome 控制等内置功能通过 MCP 协议暴露，但运行在**同进程内**——不启动子进程，无网络开销，无 IPC 序列化。
+
+**设计洞察**：内置服务器使用与外部服务器完全相同的 MCP 协议（`tools/list`、`tools/call`），但通过 `InProcessTransport` 在进程内通信。这意味着所有工具发现、权限检查、执行逻辑都是同一套代码——内置和外部工具的唯一区别是传输方式。
+
+### 外部 MCP 服务器
+
+用户配置的外部工具，通过子进程（stdio）或网络连接（SSE/HTTP/WS）运行。
+
+| 维度 | 内置 | 外部 |
+|------|------|------|
+| 进程模型 | 同进程 | 子进程或网络 |
+| 启动开销 | 零 | 子进程启动或网络握手 |
+| 权限 | 自动授权 | 需要用户确认 |
+| 配置来源 | 动态注册 | settings.json / .mcp.json |
+| 名称保护 | 保留名，不可覆盖 | 自由命名 |
+
+## 连接管理
+
+### 缓存机制
+
+连接使用 memoize 缓存——相同的配置不会重复建立连接。缓存 key 包含服务器名和配置内容，配置变化时自动失效。
+
+### 重连机制
+
+远程连接有连续错误计数器。遇到网络错误（ECONNRESET、ETIMEDOUT 等）连续 3 次后，主动关闭连接触发重连。
+
+**设计考量**：网络连接是脆弱的——临时故障不应该永久禁用一个 MCP 服务器。自动重连确保服务恢复后工具能继续使用。
+
+### 清理策略
+
+stdio 类型的子进程清理使用信号升级策略：
+
+```
+SIGINT (100ms) → SIGTERM (400ms) → SIGKILL
+```
+
+总清理时间上限 600ms。防止 MCP 服务器关闭阻塞 CLI 退出。
+
+### 并发控制
+
+| 类型 | 并发上限 | 原因 |
+|------|---------|------|
+| 本地（stdio） | 3 | 每个子进程是重量级资源 |
+| 远程（HTTP） | 20 | 轻量级 HTTP 请求 |
+
+## 工具发现
+
+### 从 MCP 到 Tool 接口
+
+MCP 服务器通过 `tools/list` 方法暴露工具列表。每个工具被包装为 Claude Code 统一的 Tool 接口，工具名格式为 `mcp__<serverName>__<toolName>`。
+
+### 工具描述截断
+
+MCP 工具描述上限 2048 字符。OpenAPI 生成的 MCP 服务器曾观察到 15-60KB 的描述文档——截断防止这些巨大描述占满 System Prompt。
+
+### 工具能力标注
+
+MCP 工具通过 `annotations` 声明自身特性：
+
+| 注解 | 含义 |
+|------|------|
+| `readOnlyHint` | 只读操作，可并行 |
+| `destructiveHint` | 破坏性操作 |
+| `openWorldHint` | 开放世界（不可枚举所有行为） |
+
+这些标注影响权限检查——只读工具在更多权限模式下被自动放行。
+
+### 权限检查
+
+MCP 工具默认进入权限确认流程（`passthrough`），通过 `mcp__` 前缀匹配权限规则。用户可以为特定 MCP 服务器配置 allow/deny 规则。
+
+内置 MCP 工具通过白名单自动授权，不触发权限提示。
+
+## 执行链路
+
+```
+AI 调用 MCP 工具 → 确保连接有效 → 通过 MCP 协议执行 → 处理结果
+  → Session 过期？自动重试一次
+  → 结果过大？截断 + 持久化到磁盘
+  → 包含图片？自动 resize + 持久化
+```
+
+**设计考量**：MCP 工具的执行结果可能很大（数据库查询结果、API 响应）。截断 + 持久化确保大型结果不会耗尽上下文窗口，同时 AI 仍然知道结果在哪里可以找到。
+
+## 接下来
+
+- **MCP 配置** — 理解多来源合并和企业管控
+- **工具系统** — 理解所有工具的统一接口
+- **权限模型** — 理解 MCP 工具的权限检查

docs/extensibility/skills.mdx

@@ -0,0 +1,123 @@
+---
+title: "Skills 技能系统"
+description: "Prompt 即能力。Skill 不是代码，而是高质量的 Prompt + 权限配置的声明式封装。理解加载链路、两条执行路径和条件激活机制。"
+keywords: ["Skills", "技能加载", "Prompt 即能力", "条件激活"]
+---
+
+## 核心洞见：Prompt 即能力
+
+Skill 的核心设计哲学：**复杂任务的关键不在代码逻辑，而在 Prompt 质量**。
+
+一个代码审查 Skill 不需要审查引擎，只需告诉 AI "审查什么、按什么顺序、输出什么格式"。Skill 把这种"经验"封装为可复用的 Markdown 文件。
+
+| | Tool | Skill |
+|---|---|---|
+| 粒度 | 单个原子操作（读文件、执行命令） | 完整工作流（代码审查、创建 PR） |
+| 本质 | TypeScript 执行逻辑 | Prompt + 权限配置的声明式封装 |
+| 创建 | 需要写代码 | 写 Markdown 文件即可 |
+
+## Skill 的来源
+
+| 来源 | 路径 | 特点 |
+|------|------|------|
+| **内置命令** | 硬编码 | `/commit`、`/compact` 等 70+ 命令 |
+| **Bundled Skills** | 编译时打包 | 延迟解压，享有不可截断特权 |
+| **磁盘 Skills** | `.claude/skills/` | 最重要的来源，支持多层级 |
+| **MCP Skills** | MCP Server 提供 | 远程内容，禁止内联 shell 命令 |
+| **Legacy Commands** | `.claude/commands/` | 向后兼容旧格式 |
+
+### 多层级磁盘加载
+
+```
+管理策略: $MANAGED_DIR/.claude/skills/     （企业管理）
+用户全局: ~/.claude/skills/                 （个人偏好）
+项目级:   .claude/skills/                   （团队共享）
+附加目录: --add-dir 指定的路径              （额外来源）
+```
+
+每个 Skill 是一个 `skill-name/SKILL.md` 目录。加载时解析 YAML frontmatter 提取配置。
+
+### 安全边界
+
+MCP Skills 的 Prompt 内容**禁止执行内联 shell 命令**。因为远程内容不可信——如果允许，恶意 MCP Server 就可以通过 Skill 注入执行任意命令。
+
+## Frontmatter 配置
+
+一个 SKILL.md 的完整配置：
+
+```yaml
+---
+name: code-review
+description: 系统性代码审查
+when_to_use: "用户说审查代码、找 bug"
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+context: fork              # 执行模式：inline | fork
+model: opus                # 模型覆盖
+effort: high               # 努力级别
+paths:                     # 条件激活
+  - "src/**/*.ts"
+---
+```
+
+- `when_to_use` — AI 根据此描述自动匹配用户意图
+- `allowed-tools` — 限制 Skill 可用的工具白名单
+- `context` — 控制执行模式（见下文）
+- `paths` — 条件激活，只在操作匹配文件时出现
+
+## 两条执行路径
+
+### Inline 模式（默认）
+
+Skill 的 Prompt 内容被注入为用户消息，在主对话流中继续执行。AI "穿上"了 Skill 的经验，但仍在同一个对话中。
+
+**优点**：共享主对话的完整上下文，可以引用之前的讨论。
+**缺点**：Skill 的中间过程会污染主对话的上下文。
+
+### Fork 模式（`context: fork`）
+
+Skill 在独立子 Agent 中执行，拥有独立的 token 预算和工具权限。执行完成后只返回最终结果，中间过程不保留。
+
+**优点**：不污染主对话，适合长时间运行的任务。
+**缺点**：子 Agent 看不到主对话的完整上下文。
+
+**设计考量**：大多数 Skill 使用 inline 模式就够了——它们需要主对话的上下文。Fork 模式适合"重型"任务（如完整的代码审查），这些任务的中间步骤很多，留在主对话中会浪费大量 token。
+
+## 权限模型
+
+Skill 有五层权限检查：
+
+```
+Deny 规则 → 远程 Skill 自动放行 → Allow 规则 → Safe Properties 白名单 → Ask 用户确认
+```
+
+**Safe Properties 白名单**是一个包含 30 个安全属性名的列表。任何不在白名单中的属性都会触发权限请求。这是**正向安全**设计——未来新增的属性默认需要权限，而非默认允许。
+
+## Prompt 预算
+
+Skill 列表注入 System Prompt 时有严格预算（约上下文窗口的 1%）：
+1. 优先保留 bundled Skills 的完整描述
+2. 非 bundled Skills 按剩余预算均分
+3. 预算不足时只保留名称
+
+**设计考量**：Skill 列表只是让 AI "知道有什么可用"。完整的 Skill Prompt 在 AI 选择后才加载，不需要全部塞进 System Prompt。
+
+## 条件激活
+
+带有 `paths` 模式的 Skill 在加载时不会立即可用。只有当被操作的文件路径匹配模式时，该 Skill 才被激活。
+
+一个只在 `*.test.ts` 上激活的测试 Skill，平时完全不可见，只有当 AI 读取或编辑测试文件时才会出现。
+
+**设计洞察**：这解决了"Skill 泛滥"问题——项目可能定义了几十个 Skill，但一次对话通常只需要其中几个。条件激活让 Skill 按需出现，而不是全部堆在 AI 面前让它选择。
+
+## 使用频率排名
+
+Skill 的排序使用指数衰减算法：一周前的使用权重减半。这确保常用的 Skill 排在前面，但偶尔用的老 Skill 也不会完全沉底。
+
+## 接下来
+
+- **Hooks** — 理解 Skill 中可以使用的 Hook 机制
+- **MCP 配置** — 理解 MCP Skills 的来源
+- **自定义 Agent** — 理解 Skill 中指定的 Agent 定义

docs/external-dependencies.md

@@ -0,0 +1,214 @@
+# Claude Code 远程服务器依赖
+
+> 只列出代码中实际发起网络请求的远程服务。本地服务、npm 包依赖、展示用 URL 不包含在内。
+
+## 总览表
+
+| # | 服务 | 远程端点 | 协议 | 状态 |
+|---|---|---|---|---|
+| 1 | Anthropic API | `api.anthropic.com` | HTTPS | 默认启用 |
+| 2 | AWS Bedrock | `bedrock-runtime.*.amazonaws.com` | HTTPS | 需 `CLAUDE_CODE_USE_BEDROCK=1` |
+| 3 | Google Vertex AI | `{region}-aiplatform.googleapis.com` | HTTPS | 需 `CLAUDE_CODE_USE_VERTEX=1` |
+| 4 | Azure Foundry | `{resource}.services.ai.azure.com` | HTTPS | 需 `CLAUDE_CODE_USE_FOUNDRY=1` |
+| 5 | OAuth (Anthropic) | `platform.claude.com`, `claude.com`, `claude.ai` | HTTPS | 用户登录时 |
+| 6 | GrowthBook | `api.anthropic.com` (remoteEval) | HTTPS | 默认启用 |
+| 7 | Sentry | 可配置 (`SENTRY_DSN`) | HTTPS | 需设环境变量 |
+| 8 | Datadog | 可配置 (`DATADOG_LOGS_ENDPOINT`) | HTTPS | 需设环境变量 |
+| 9 | OpenTelemetry Collector | 可配置 (`OTEL_EXPORTER_OTLP_ENDPOINT`) | gRPC/HTTP | 需设环境变量 |
+| 10 | 1P Event Logging | `api.anthropic.com/api/event_logging/batch` | HTTPS | 默认启用 |
+| 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 | 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 集成 |
+| 18 | CCR Upstream Proxy | `api.anthropic.com` | WS | CCR 远程会话 |
+| 19 | Voice STT | `api.anthropic.com/api/ws/...` | WSS | Voice Mode |
+| 20 | Desktop App Download | `claude.ai/api/desktop/...` | HTTPS | 下载引导 |
+
+---
+
+## 详细说明
+
+### 1. Anthropic Messages API
+
+核心 LLM 推理服务，发送对话消息、接收流式响应。
+
+- **端点**: `https://api.anthropic.com` (生产) / `https://api-staging.anthropic.com` (staging)
+- **覆盖**: `ANTHROPIC_BASE_URL` 环境变量
+- **认证**: API Key / OAuth Token
+- **文件**: `src/services/api/client.ts`, `src/services/api/claude.ts`
+
+### 2. AWS Bedrock
+
+- **端点**: `bedrock-runtime.{region}.amazonaws.com`
+- **认证**: AWS 凭证链 / `AWS_BEARER_TOKEN_BEDROCK`
+- **文件**: `src/services/api/client.ts:153-190`, `src/utils/aws.ts`
+
+### 3. Google Vertex AI
+
+- **端点**: `{region}-aiplatform.googleapis.com`
+- **认证**: `GoogleAuth` + `cloud-platform` scope
+- **文件**: `src/services/api/client.ts:221-298`
+
+### 4. Azure Foundry
+
+- **端点**: `https://{resource}.services.ai.azure.com/anthropic/v1/messages`
+- **认证**: API Key 或 Azure AD `DefaultAzureCredential`
+- **文件**: `src/services/api/client.ts:191-220`
+
+### 5. OAuth
+
+OAuth 2.0 + PKCE 授权码流程。
+
+- **端点**:
+  - `https://platform.claude.com/oauth/authorize` — 授权页
+  - `https://claude.com/cai/oauth/authorize` — Claude.ai 授权
+  - `https://platform.claude.com/v1/oauth/token` — Token 交换
+  - `https://api.anthropic.com/api/oauth/claude_cli/create_api_key` — 创建 API Key
+  - `https://api.anthropic.com/api/oauth/claude_cli/roles` — 获取角色
+  - `https://claude.ai/oauth/claude-code-client-metadata` — MCP 客户端元数据
+  - `https://claude.fedstart.com` — FedStart 政府部署
+- **文件**: `src/constants/oauth.ts`, `src/services/oauth/`
+
+### 6. GrowthBook (功能开关)
+
+- **端点**: `https://api.anthropic.com/` (remoteEval 模式) 或 `CLAUDE_GB_ADAPTER_URL`
+- **SDK Keys**: `sdk-zAZezfDKGoZuXXKe` (外部), `sdk-xRVcrliHIlrg4og4` (ant prod), `sdk-yZQvlplybuXjYh6L` (ant dev)
+- **文件**: `src/services/analytics/growthbook.ts`, `src/constants/keys.ts`
+
+### 7. Sentry (错误追踪)
+
+- **激活**: 设置 `SENTRY_DSN` (默认未配置)
+- **行为**: 仅错误上报，自动过滤敏感 header
+- **文件**: `src/utils/sentry.ts`
+
+### 8. Datadog (日志)
+
+- **激活**: 同时设 `DATADOG_LOGS_ENDPOINT` + `DATADOG_API_KEY` (默认未配置)
+- **文件**: `src/services/analytics/datadog.ts`
+
+### 9. OpenTelemetry Collector
+
+- **激活**: `CLAUDE_CODE_ENABLE_TELEMETRY=1` 或 `OTEL_*` 环境变量
+- **协议**: gRPC / HTTP / Protobuf，支持 OTLP 和 Prometheus 导出
+- **文件**: `src/utils/telemetry/instrumentation.ts`
+
+### 10. 1P Event Logging (内部事件)
+
+- **端点**: `https://api.anthropic.com/api/event_logging/batch`
+- **协议**: 批量导出 (10s 间隔, 每批 200 事件)
+- **文件**: `src/services/analytics/firstPartyEventLoggingExporter.ts`
+
+### 11. BigQuery Metrics
+
+- **端点**: `https://api.anthropic.com/api/claude_code/metrics`
+- **文件**: `src/utils/telemetry/bigqueryExporter.ts`
+
+### 12. MCP Proxy
+
+Anthropic 托管的 MCP 服务器代理。
+
+- **端点**: `https://mcp-proxy.anthropic.com/v1/mcp/{server_id}`
+- **认证**: Claude.ai OAuth tokens
+- **文件**: `src/services/mcp/client.ts`, `src/constants/oauth.ts`
+
+### 13. MCP Registry
+
+获取官方 MCP 服务器列表。
+
+- **端点**: `https://api.anthropic.com/mcp-registry/v0/servers?version=latest&visibility=commercial`
+- **文件**: `src/services/mcp/officialRegistry.ts`
+
+### 14. Web Search Pages
+
+WebSearch 工具支持直接抓取 Bing 搜索结果页面，也支持通过 Brave 的 LLM Context API
+获取搜索上下文；可通过 `WEB_SEARCH_ADAPTER=bing|brave` 显式切换后端。
+
+- **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}`
+- **文件**: `packages/builtin-tools/src/tools/WebFetchTool/utils.ts`
+
+### 15. Google Cloud Storage (自动更新)
+
+- **端点**: `https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases`
+- **文件**: `src/utils/autoUpdater.ts`
+
+### 16. GitHub Raw Content
+
+- **端点**: `https://raw.githubusercontent.com/anthropics/claude-code/refs/heads/main/CHANGELOG.md`
+- **端点**: `https://raw.githubusercontent.com/anthropics/claude-plugins-official/refs/heads/stats/stats/plugin-installs.json`
+- **文件**: `src/utils/releaseNotes.ts`, `src/utils/plugins/installCounts.ts`
+
+### 17. Claude in Chrome Bridge
+
+- **端点**: `wss://bridge.claudeusercontent.com` (生产) / `wss://bridge-staging.claudeusercontent.com` (staging)
+- **文件**: `src/utils/claudeInChrome/mcpServer.ts`
+
+### 18. CCR Upstream Proxy
+
+- **端点**: `ws://api.anthropic.com/v1/code/upstreamproxy/ws`
+- **激活**: `CLAUDE_CODE_REMOTE=1` + `CCR_UPSTREAM_PROXY_ENABLED=1`
+- **文件**: `src/upstreamproxy/upstreamproxy.ts`
+
+### 19. Voice STT
+
+- **端点**: `wss://api.anthropic.com/api/ws/...`
+- **文件**: `src/services/voiceStreamSTT.ts`
+
+### 20. Desktop App Download
+
+- **端点**: `https://claude.ai/api/desktop/win32/x64/exe/latest/redirect` (Windows)
+- **端点**: `https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect` (macOS)
+- **文件**: `src/components/DesktopHandoff.tsx`
+
+---
+
+## Anthropic API 辅助端点汇总
+
+以下端点都挂在 `api.anthropic.com` 上，按功能分类:
+
+| 端点路径 | 用途 | 文件 |
+|---|---|---|
+| `/api/event_logging/batch` | 事件批量上报 | `src/services/analytics/firstPartyEventLoggingExporter.ts` |
+| `/api/claude_code/metrics` | BigQuery 指标导出 | `src/utils/telemetry/bigqueryExporter.ts` |
+| `/api/oauth/claude_cli/create_api_key` | 创建 API Key | `src/constants/oauth.ts` |
+| `/api/oauth/claude_cli/roles` | 获取用户角色 | `src/constants/oauth.ts` |
+| `/api/oauth/accounts/grove` | 通知设置 | `src/services/api/grove.ts` |
+| `/api/oauth/organizations/{id}/referral/*` | 推荐活动 | `src/services/api/referral.ts` |
+| `/api/oauth/organizations/{id}/overage_credit_grant` | 超额信用 | `src/services/api/overageCreditGrant.ts` |
+| `/api/oauth/organizations/{id}/admin_requests` | 管理请求 | `src/services/api/adminRequests.ts` |
+| `/api/web/domain_info?domain={}` | 域名安全检查 | `src/tools/WebFetchTool/utils.ts` |
+| `/api/claude_code/settings` | 设置同步 | `src/services/settingsSync/index.ts` |
+| `/api/claude_code/managed_settings` | 企业托管设置 (1h 轮询) | `src/services/remoteManagedSettings/index.ts` |
+| `/api/claude_code/team_memory?repo={}` | 团队记忆同步 | `src/services/teamMemorySync/index.ts` |
+| `/api/auth/trusted_devices` | 可信设备注册 | `src/bridge/trustedDevice.ts` |
+| `/api/organizations/{id}/claude_code/buddy_react` | Companion 反应 | `src/buddy/companionReact.ts` |
+| `/mcp-registry/v0/servers` | MCP 服务器注册表 | `src/services/mcp/officialRegistry.ts` |
+| `/v1/files` | 文件上传/下载 | `src/services/api/filesApi.ts` |
+| `/v1/sessions/{id}/events` | 会话历史 | `src/assistant/sessionHistory.ts` |
+| `/v1/code/triggers` | 远程触发器 | `src/tools/RemoteTriggerTool/RemoteTriggerTool.ts` |
+| `/v1/organizations/{id}/mcp_servers` | 组织 MCP 配置 | `src/services/mcp/claudeai.ts` |
+
+## 非 Anthropic 远程域名汇总
+
+| 域名 | 服务 | 协议 |
+|---|---|---|
+| `bedrock-runtime.*.amazonaws.com` | AWS Bedrock | HTTPS |
+| `{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 |
+| `platform.claude.com` | OAuth 授权页 | HTTPS |
+| `claude.com` / `claude.ai` | OAuth / 下载 | HTTPS |
+| `claude.fedstart.com` | FedStart OAuth | HTTPS |

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/agents/acp.md

@@ -1,389 +0,0 @@
----
-title: "ACP 协议：接入 Zed / Cursor 等 IDE"
-description: "通过 ACP（Agent Client Protocol）把 CCB 接入支持 ACP 的 IDE。本文包含 acp-link CLI 用法、权限桥接、以及 Zed 集成案例。"
-keywords: ["ACP 协议", "Zed 编辑器", "acp-link", "权限桥接", "IDE 集成"]
----
-
-# ACP 协议：接入 Zed / Cursor 等 IDE
-
-## 概述
-
-ACP (Agent Client Protocol) 是一种标准化的 stdio 协议，允许 IDE 和编辑器通过 stdin/stdout 的 NDJSON 流驱动 AI Agent。CCB 实现了完整的 ACP agent 端，可以被 Zed、Cursor 等支持 ACP 的客户端直接调用。
-
-CCB 在 ACP 体系下提供两层能力：
-
-- **ACP Agent**（源码目录 `src/services/acp/`）：CCB 自身作为 ACP agent，通过 `ccb --acp` 暴露 stdio 接口，由 IDE 直接调用。
-- **acp-link 代理服务器**（源码目录 `packages/acp-link/`）：将 WebSocket 客户端桥接到 ACP agent 的 stdio 接口，让 ACP agent 可以通过 WebSocket 远程访问，而不仅限于本地 stdio。
-
-### 核心特性
-
-ACP Agent：
-
-- **会话管理**：新建 / 恢复 / 加载 / 分叉 / 关闭会话
-- **历史回放**：恢复会话时自动加载并回放对话历史
-- **权限桥接**：ACP 客户端的权限决策映射到 CCB 的工具权限系统
-- **斜杠命令 & Skills**：加载真实命令列表，支持 `/commit`、`/review` 等 prompt 型 skill
-- **Context Window 跟踪**：精确的 usage_update，含 model prefix matching
-- **Prompt 排队**：支持连续发送多条 prompt，自动排队处理
-- **模式切换**：auto / default / acceptEdits / plan / dontAsk / bypassPermissions
-- **模型切换**：运行时切换 AI 模型
-
-acp-link：
-
-- **WebSocket → stdio 桥接**：将浏览器/远程客户端的 WebSocket 连接转换为 ACP agent 的 stdin/stdout NDJSON 流
-- **会话管理**：创建、加载、恢复、列出、关闭会话
-- **权限审批流程**：客户端可远程审批 agent 的工具权限请求
-- **RCS 集成**：可与 Remote Control Server (RCS) 连接，将 ACP agent 注册到 RCS 并通过 Web UI 交互
-- **HTTPS 支持**：内置自签名证书生成，支持安全连接
-- **Token 认证**：自动生成或通过环境变量配置认证 token
-
-## 快速上手
-
-### 在 Zed 中接入 CCB
-
-1. 打开 Zed 的 `settings.json`（`Cmd+,` → Open Settings），添加 `agent_servers` 配置：
-
-   ```json
-   {
-     "agent_servers": {
-       "ccb": {
-         "type": "custom",
-         "command": "ccb",
-         "args": ["--acp"]
-       }
-     }
-   }
-   ```
-
-2. API 认证：CCB 的 ACP agent 在启动时会自动加载 `settings.json` 中的环境变量（`ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN` 等）。确保已通过 `/login` 配置好 API 供应商；也可在 `agent_servers` 中显式传入 `env`：
-
-   ```json
-   {
-     "agent_servers": {
-       "claude-code": {
-         "command": "ccb",
-         "args": ["--acp"],
-         "env": {
-           "ANTHROPIC_BASE_URL": "https://api.example.com/v1",
-           "ANTHROPIC_AUTH_TOKEN": "sk-xxx"
-         }
-       }
-     }
-   }
-   ```
-
-3. 重启 Zed，打开任意项目目录。
-4. 按 `Cmd+'`（macOS）或 `Ctrl+'`（Linux）打开 Agent Panel。
-5. 在 Agent Panel 顶部的下拉菜单中选择 **claude-code**。
-6. 开始对话。
-
-### Zed 中的功能操作
-
-| 功能 | 操作 |
-|------|------|
-| 对话 | 在 Agent Panel 中直接输入消息 |
-| 斜杠命令 | 输入 `/` 查看可用 skills 列表（如 `/commit`、`/review`） |
-| 工具权限 | 弹出权限请求时选择 Allow / Reject / Always Allow |
-| 模式切换 | 通过 Agent Panel 的设置菜单切换 auto/default/plan 等模式 |
-| 模型切换 | 通过 Agent Panel 的设置菜单切换 AI 模型 |
-| 会话恢复 | 关闭重开 Zed 后，之前的会话可自动恢复（含历史消息） |
-
-### 通过 acp-link 暴露到网络
-
-```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
-```
-
-## 详细说明
-
-### ACP Agent 架构
-
-```
-┌──────────────┐    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、路径显示 |
-
-### acp-link 架构
-
-#### 独立模式
-
-```
-┌──────────────────┐    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
-```
-
-### acp-link 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")
-```
-
-### 接入其他 ACP 客户端
-
-ACP 是开放协议，任何支持 ACP 的客户端都可以连接 CCB。通用配置模式：
-
-```
-命令: ccb --acp
-参数: ["--acp"]
-通信: stdin/stdout NDJSON
-协议版本: ACP v1
-```
-
-#### Cursor
-
-在 Cursor 的设置中配置 MCP / Agent Server，使用同样的 `ccb --acp` 命令。
-
-#### 自定义客户端
-
-使用 `@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-link 自动生成随机 token。客户端连接时不要把 token 放在 URL 中：
-
-```
-ws://localhost:9315/ws
-```
-
-无法发送 `Authorization` header 的 WebSocket 客户端需要使用
-`rcs.auth.<base64url-token>` 子协议传递 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`
-
-RCS 的 ACP WebSocket 连接不接受 URL query token。acp-link 会通过
-`rcs.auth.<base64url-token>` WebSocket 子协议发送 `ACP_RCS_TOKEN`。
-
-```
-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
-```
-
-#### 权限管道改进
-
-- **模式同步**：`applySessionMode` 在 agent 切换权限模式时同步 `appState.toolPermissionContext.mode`，确保内部权限上下文与 ACP 客户端状态一致。
-- **统一权限流水线**：`createAcpCanUseTool` 接入 `hasPermissionsToUseTool` 统一权限流水线，替代原来分散的处理逻辑。支持 `onModeChange` 回调，模式变更时实时同步。
-- **bypass 检测**：`bypassPermissions` 模式增加可用性检测 — 仅在非 root 或 sandbox 环境中允许启用，防止权限绕过的安全风险。
-
-### 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` | 支持 | 配置更新通知 |
-
-### 环境变量与功能开关
-
-#### 环境变量
-
-| 变量 | 说明 |
-|------|------|
-| `ACP_AUTH_TOKEN` | 固定认证 token（默认自动生成） |
-| `ACP_PERMISSION_MODE` | 默认权限模式 fallback |
-| `ACP_RCS_URL` | RCS 服务器地址（启用 RCS 集成） |
-| `ACP_RCS_TOKEN` | RCS API token |
-
-#### 功能开关
-
-ACP Agent 与 acp-link 受 `FEATURE_ACP` 控制，build 和 dev 模式默认启用。源码目录：
-
-- ACP Agent：`src/services/acp/`
-- acp-link：`packages/acp-link/`（相关 PR：#292，新增时间：2026-04-18）

docs/features/agents/pipes-and-lan.md

@@ -1,420 +0,0 @@
----
-title: "群控：本机 + 局域网多实例协作"
-description: "多台 CCB 实例零配置组网，同机用 UDS、跨机用 LAN，自动发现与消息路由。包含 /pipes 命令、心跳机制、消息路由详解。"
-keywords: ["群控", "局域网协作", "UDS", "多实例", "消息路由"]
----
-
-# 群控：本机 + 局域网多实例协作
-
-## 概述
-
-Pipes 系统提供 Claude Code CLI 实例之间的通讯能力，让你可以在一台机器（main）上操控其他实例（sub），发送 prompt、查看执行结果、审批权限请求——全程零配置。
-
-系统分两层，使用同一套协议（NDJSON）和同一套命令（`/pipes`、`/attach`、`/send` 等），对用户完全透明：
-
-1. **本机 Pipes（UDS）**：同一台机器上的多个 CLI 实例通过 Unix Domain Socket（Linux/macOS）或 Windows Named Pipe 协作
-2. **局域网 Pipes（LAN）**：不同机器上的 CLI 实例通过 TCP + UDP Multicast beacon 协作
-
-> 严格区分：`/peers` 解决"找到其他会话并发消息"（通用消息投递），`/pipes` 解决"把一个 REPL 变成另一个 REPL 的受控 worker"（主从 REPL 协调平面）。两者职责不同，不要混淆。
-
-### 两层职责拆解
-
-| 层 | 面向 | 传输方式 | 对外入口 |
-|------|------|----------|----------|
-| UDS peer messaging | 任意 CCB 进程 | 本机 Unix socket / Named pipe | `/peers`、`SendMessageTool` 的 `uds:<socket-path>` |
-| pipes control plane | 交互式 REPL 会话间的主从协作 | 本机 socket + LAN TCP | `/pipes`、`/attach`、`/detach`、`/send`、`/pipe-status`、`/claim-main` |
-
-两层都依赖本机 socket，但命名、角色模型、交互语义和 UI 集成都不同：peer 层按 socket 路径寻址，服务工具调用；pipes 层按 `cli-xxxxxxxx` 会话名和 `main/sub/master/slave` 角色工作，直接影响 REPL 提交路径和 PromptInput 页脚。
-
-## 快速上手
-
-### 场景一：本机多实例
-
-```bash
-# 终端 1
-bun run dev
-# 启动后自动注册为 main
-
-# 终端 2
-bun run dev
-# 自动注册为 sub-1，被 main 自动 attach
-```
-
-在终端 1 中输入 `/pipes`，可以看到两个实例。选中 sub-1 后，输入的消息会自动转发到 sub-1 执行。
-
-### 场景二：局域网多机器
-
-前置条件：
-
-- 两台或以上机器在同一局域网
-- 每台机器安装了 CCB 并能 `bun run dev`
-- 防火墙允许 UDP 7101 + TCP 动态端口（见下方配置）
-
-```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]` 的远端实例。
-
-## 防火墙配置
-
-**每台机器都需要执行。** 请先确认网络为局域网（非公共 WiFi），路由器未开启 AP 隔离，两台机器在同一子网（`ping` 能通）。
-
-### 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
-
-首次运行时系统弹出"允许接受传入连接"对话框，点击"允许"即可。如果使用 pf 防火墙：
-
-```bash
-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
-```
-
-## 交互面板与快捷键
-
-### 状态栏
-
-执行 `/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`） |
-
-### 完整操作流程示例
-
-```
-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
-```
-
-远端执行结果会流式回传到你的消息列表：
-
-```
-[main vmwin11/192.168.50.27 / cli-04d67950] 正在检查 git status...
-[main vmwin11/192.168.50.27 / cli-04d67950] Completed
-```
-
-## 消息路由
-
-### 路由模式
-
-通过 **M 键**（或 ← / →）切换，**无需展开面板**。切换路由模式**不会清空选择**——你可以在 `local main` 模式下保持选择，随时按 M 切回继续向远端发送。
-
-| 模式 | 状态栏显示 | 行为 |
-|------|-----------|------|
-| `selected pipes only` | 绿色高亮 | 输入的 prompt **仅**发送到选中的 pipe，本地不执行 |
-| `local main` | 灰色 | 输入的 prompt 在**本地 main** 执行，不转发到任何 pipe |
-
-### 选中 pipe 后的自动路由
-
-1. 通过 `/pipes select` 或 Shift+↓ 面板选中一个或多个 pipe
-2. 在输入框中正常输入消息
-3. 消息自动发送到所有选中的**已连接** pipe
-4. 每个 pipe 独立执行，结果流式回传到 main 的消息列表
-
-> 选中但未连接的 pipe 不会导致本地处理被错误跳过——只有已连接的 pipe 会收到广播。
-
-## 命令参考
-
-### /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 到一个实例（自动识别 LAN peer 并通过 TCP 连接），使其成为 slave |
-| `/detach <name>` | 断开与某个 slave 的连接 |
-| `/send <name> <msg>` | 向指定 pipe 发送消息（不依赖选择状态，直接指定目标） |
-| `/send tcp:host:port <msg>` | 直接通过 TCP 地址发送 |
-| `/claim-main` | 强制声明当前机器为 main（用于 main 意外退出后的恢复） |
-| `/pipe-status` | 显示详细状态 |
-| `/peers` | 列出所有已发现的 peer |
-
-通常不需要手动 attach——heartbeat 会自动发现并连接。attach 后对方变为 slave，你变为 master，可以向它发送 prompt。
-
-示例：
-
-```
-/attach cli-04d67950
-/send cli-04d67950 请帮我检查一下日志
-/send tcp:192.168.50.27:58853 hello
-```
-
-## 权限转发
-
-当远端 slave 执行需要权限的工具（如 BashTool）时：
-
-1. slave 发送 `permission_request` 到 main
-2. main 弹出权限确认对话框，显示来源标记 `[role hostname/ip / pipeName]`
-3. 用户确认/拒绝
-4. 结果发回 slave，继续或中断
-
-> AI 通过 `SendMessageTool` 发送 `tcp:` 消息时需用户显式确认。
-
-## 架构详解
-
-### 通信协议
-
-所有通讯使用 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 / Named Pipe**：本机实例间通讯，通过文件系统路径寻址（`~/.claude/pipes/cli-xxx.sock`）
-- **TCP**：LAN 实例间通讯，动态端口，通过 beacon 发现
-- **UDP Multicast**：peer 发现，组地址 `224.0.71.67`，端口 `7101`，TTL=1（不跨路由器），3 秒广播一次 announce 包
-
-### 角色模型
-
-| 角色 | 说明 |
-|------|------|
-| `main` | 首个启动的实例，管理 registry |
-| `sub` | 后续启动的同机实例（或被 attach 的 LAN 实例） |
-| `master` | attach 了至少一个 slave 的实例 |
-| `slave` | 被 master attach 控制的实例 |
-
-**角色转换规则：**
-
-- 首个启动 → `main`
-- 同机后续启动 → `sub`（自动被 main attach → `slave`）
-- LAN 发现 → 两边都是 `main`，heartbeat 自动互相 attach（跨机器 attach 时，两边都可以是 main——不要求对方必须是 sub）
-- 被 attach → 变为 `slave`（可通过 `/detach` 恢复）
-
-### 发现机制
-
-**本机**：通过 `~/.claude/pipes/registry.json` 文件（带文件锁），`machineId` 绑定主机身份。同机 peer 层读取 `~/.claude/sessions/*.json`，按 `messagingSocketPath` 寻址。
-
-**LAN**：通过 UDP multicast beacon：
-
-1. 每台机器启动时创建 UDP multicast beacon，每 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 角色，跨机则独立
-
-### 当前 REPL 行为
-
-当前线上行为由 `src/screens/REPL.tsx` 的内联实现负责（以该文件、`pipeTransport.ts`、`pipeRegistry.ts` 为事实来源）：
-
-1. 启动时创建当前 REPL 的 pipe server
-2. 通过 `pipeRegistry` 判定 `main` / `sub`
-3. 处理 `attach_request` / `detach` / `prompt`
-4. 主实例心跳探测并维护 `slaves`
-5. `/pipes` 打开状态栏并维护选择器
-6. 提交普通消息时，仅向**已连接**的 selected pipes 广播
-
-过去的未接线 hook 方案已收敛，选中但未连接的 pipe 不会导致本地处理被错误跳过。
-
-## 关键文件
-
-| 文件 | 职责 |
-|------|------|
-| `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/utils/udsMessaging.ts` | UDS peer messaging 服务端 |
-| `src/utils/udsClient.ts` | UDS peer messaging 客户端 |
-| `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: 支持） |
-
-## 常见问题
-
-### 看不到 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()` 返回值。
-
-## 配置
-
-### Feature Flag
-
-| Flag | 控制范围 | 默认 |
-|------|----------|------|
-| `UDS_INBOX` | 本机 Pipe IPC 全部功能（含 UDS peer messaging + pipes control plane） | dev/build 启用 |
-| `LAN_PIPES` | 局域网 TCP + UDP beacon 扩展 | dev/build 启用 |
-
-手动启用：
-
-```bash
-FEATURE_UDS_INBOX=1 FEATURE_LAN_PIPES=1 bun run dev
-```
-
-### 安全说明
-
-- TCP 连接当前**无认证**——同 LAN 内知道端口号即可连接
-- Multicast TTL=1，不跨路由器
-- 建议仅在信任的局域网中使用
-
-### 后续优化方向
-
-**安全（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/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/auto-dream.md

@@ -1,9 +1,3 @@
----
-title: "后台记忆整理（Auto Dream）"
-description: "会话间自动审查、组织和修剪持久化记忆，确保未来会话快速获得准确上下文。"
-keywords: ["Auto Dream", "记忆整合", "后台任务", "MEMORY.md", "/dream 命令"]
----
-
 # Auto Dream — 自动记忆整理
 
 ## 概述

docs/features/bash-classifier.md

@@ -0,0 +1,107 @@
+# BASH_CLASSIFIER — Bash 命令分类器
+
+> Feature Flag: `FEATURE_BASH_CLASSIFIER=1`
+> 实现状态：bashClassifier.ts 全部 Stub，yoloClassifier.ts 完整实现可参考
+> 引用数：45
+
+## 一、功能概述
+
+BASH_CLASSIFIER 使用 LLM 对 bash 命令进行意图分类（允许/拒绝/询问），实现自动权限决策。用户不需要逐个审批 bash 命令，分类器根据命令内容和上下文自动判断安全性。
+
+### 核心特性
+
+- **LLM 驱动分类**：使用 Opus 模型评估命令安全性
+- **两阶段分类**：快速阻止/允许 → 深度思考链
+- **自动审批**：分类器判定安全的命令自动通过
+- **UI 集成**：权限对话框显示分类器状态和审核选项
+
+## 二、实现架构
+
+### 2.1 模块状态
+
+| 模块 | 文件 | 状态 | 说明 |
+|------|------|------|------|
+| Bash 分类器 | `src/utils/permissions/bashClassifier.ts` | **Stub** | 所有函数返回空操作。注释："ANT-ONLY" |
+| YOLO 分类器 | `src/utils/permissions/yoloClassifier.ts` | **完整** | 1496 行，两阶段 XML 分类器 |
+| 审批信号 | `src/utils/classifierApprovals.ts` | **完整** | Map + 信号管理分类器决策 |
+| 权限 UI | `src/components/permissions/BashPermissionRequest.tsx` | **布线** | 分类器状态显示、审核选项 |
+| 权限管道 | `src/hooks/toolPermission/handlers/*.ts` | **布线** | 分类器结果路由到决策 |
+| API beta 标头 | `src/services/api/withRetry.ts` | **布线** | 启用时发送 `bash_classifier` beta |
+
+### 2.2 参考实现：yoloClassifier.ts
+
+文件：`src/utils/permissions/yoloClassifier.ts`（1496 行）
+
+这是已实现的完整分类器，可作为 bashClassifier.ts 的参考：
+
+```
+两阶段分类：
+1. 快速阶段：构建对话记录 → 调用 sideQuery（Opus）→ 快速阻止/允许
+2. 深度阶段：思考链分析 → 最终决策
+```
+
+特性：
+- 构建完整对话记录上下文
+- 调用安全系统提示的 sideQuery
+- GrowthBook 配置和指标
+- 错误处理和降级
+
+### 2.3 分类器在权限管道中的位置
+
+```
+bash 命令到达
+      │
+      ▼
+bashPermissions.ts 权限检查
+      │
+      ├── 传统规则匹配（字符串级别）
+      │
+      └── [BASH_CLASSIFIER] LLM 分类
+            │
+            ├── allow → 自动通过
+            ├── deny → 自动拒绝
+            └── ask → 显示权限对话框
+                  │
+                  ├── 分类器自动审批标记
+                  └── 审核选项（用户可覆盖）
+```
+
+## 三、需要补全的内容
+
+| 函数 | 需要实现 | 说明 |
+|------|---------|------|
+| `classifyBashCommand()` | LLM 调用评估安全性 | 参考 yoloClassifier.ts 的两阶段模式 |
+| `isClassifierPermissionsEnabled()` | GrowthBook/配置检查 | 控制分类器是否激活 |
+| `getBashPromptDenyDescriptions()` | 返回基于提示的拒绝规则 | 权限设置描述 |
+| `getBashPromptAskDescriptions()` | 返回询问规则 | 需要用户确认的命令 |
+| `getBashPromptAllowDescriptions()` | 返回允许规则 | 自动通过的命令 |
+| `generateGenericDescription()` | LLM 生成命令描述 | 为权限对话框提供说明 |
+| `extractPromptDescription()` | 解析规则内容 | 从规则中提取描述 |
+
+## 四、关键设计决策
+
+1. **ANT-ONLY 标记**：bashClassifier.ts 标注为 "ANT-ONLY"，可能是 Anthropic 内部服务端分类器的客户端适配
+2. **两阶段分类**：快速阶段处理明确情况（减少延迟），深度阶段处理模糊情况
+3. **分类器结果可审核**：权限 UI 显示分类器决策，用户可覆盖
+4. **YOLO 分类器参考**：yoloClassifier.ts 提供完整的分类器实现模式，可直接参考
+
+## 五、使用方式
+
+```bash
+# 启用 feature
+FEATURE_BASH_CLASSIFIER=1 bun run dev
+
+# 配合 TREE_SITTER_BASH 使用（AST + LLM 双重安全）
+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/BashPermissionRequest.tsx` | — | 分类器 UI |
+| `src/hooks/toolPermission/handlers/interactiveHandler.ts` | — | 交互式权限处理 |
+| `src/services/api/withRetry.ts` | — | API beta 标头 |

docs/features/bridge-mode.md

@@ -0,0 +1,158 @@
+# BRIDGE_MODE — 远程控制
+
+> Feature Flag: `FEATURE_BRIDGE_MODE=1`
+> 实现状态：完整可用（v1 + v2 实现）
+> 引用数：28
+
+## 一、功能概述
+
+BRIDGE_MODE 将本地 CLI 注册为"bridge 环境"，可从 claude.ai 或其他控制面远程驱动。本地终端变为一个"执行者"，接受远程指令并执行。
+
+### 核心特性
+
+- **环境注册**：本地 CLI 向 Anthropic 服务器注册为可用的 bridge 环境
+- **工作轮询**：长轮询（long-poll）等待远程任务分配
+- **会话管理**：创建、恢复、归档远程会话
+- **权限透传**：远程权限请求发送到控制面，用户在 claude.ai 上批准/拒绝
+- **心跳保活**：定期发送 heartbeat 延长任务租约
+- **可信设备**：v2 支持可信设备令牌增强安全性
+
+## 二、实现架构
+
+### 2.1 版本演进
+
+| 版本 | 实现 | 特点 |
+|------|------|------|
+| v1（env-based） | `src/bridge/replBridge.ts` | 基于环境变量的传统 bridge |
+| v2（env-less） | `src/bridge/remoteBridgeCore.ts` | 无需环境变量，更安全的 bridge |
+
+### 2.2 API 协议
+
+文件：`src/bridge/bridgeApi.ts`
+
+Bridge API Client 提供 9 个核心操作：
+
+| 操作 | HTTP | 说明 |
+|------|------|------|
+| `registerBridgeEnvironment` | POST `/v1/environments/bridge` | 注册本地环境，获取 `environment_id` + `environment_secret` |
+| `pollForWork` | GET `/v1/environments/{id}/work/poll` | 长轮询等待任务（10s 超时） |
+| `acknowledgeWork` | POST `/v1/environments/{id}/work/{workId}/ack` | 确认接收任务 |
+| `stopWork` | POST `/v1/environments/{id}/work/{workId}/stop` | 停止任务 |
+| `heartbeatWork` | POST `/v1/environments/{id}/work/{workId}/heartbeat` | 续约任务租约 |
+| `deregisterEnvironment` | DELETE `/v1/environments/bridge/{id}` | 注销环境 |
+| `archiveSession` | POST `/v1/sessions/{id}/archive` | 归档会话（409 = 已归档，幂等） |
+| `sendPermissionResponseEvent` | POST `/v1/sessions/{id}/events` | 发送权限审批结果 |
+| `reconnectSession` | POST `/v1/environments/{id}/bridge/reconnect` | 重连已存在的会话 |
+
+### 2.3 认证流程
+
+```
+注册: OAuth Bearer Token → 获取 environment_secret
+轮询: environment_secret 作为 Authorization
+  ├── 401 → 尝试 OAuth token 刷新（onAuth401）
+  └── 刷新成功 → 重试一次
+```
+
+**OAuth 刷新**：API client 内置 `withOAuthRetry` 机制。401 时调用 `handleOAuth401Error`（同 withRetry.ts 的 v1/messages 模式），刷新后重试一次。
+
+### 2.4 安全设计
+
+- **路径穿越防护**：`validateBridgeId()` 使用 `/^[a-zA-Z0-9_-]+$/` 白名单验证所有服务端 ID
+- **BridgeFatalError**：不可重试的错误（401/403/404/410）直接抛出，阻止重试循环
+- **可信设备令牌**：v2 通过 `X-Trusted-Device-Token` header 增强安全层级
+- **幂关注册**：支持 `reuseEnvironmentId` 实现会话恢复，避免重复创建环境
+
+### 2.5 数据流
+
+```
+claude.ai 用户选择远程环境
+         │
+         ▼
+POST /v1/environments/bridge (注册)
+         │
+         ◀── environment_id + environment_secret
+         │
+         ▼
+GET .../work/poll (长轮询)
+         │
+         ◀── WorkResponse { id, data: { type, sessionId } }
+         │
+         ▼
+POST .../work/{id}/ack (确认)
+         │
+         ▼
+sessionRunner 创建 REPL session
+         │
+         ├── 权限请求 → sendPermissionResponseEvent
+         ├── 心跳 → heartbeatWork (续约)
+         └── 任务完成 → 自动归档
+```
+
+### 2.6 模块结构
+
+| 模块 | 文件 | 职责 |
+|------|------|------|
+| API Client | `bridgeApi.ts` | HTTP 通信（注册/轮询/确认/心跳/注销） |
+| Session Runner | `sessionRunner.ts` | 创建/恢复 REPL 会话 |
+| Bridge Config | `bridgeConfig.ts` | 配置管理（machine name、max sessions 等） |
+| Transport | `replBridgeTransport.ts` | Bridge 传输层 |
+| Permission Callbacks | `bridgePermissionCallbacks.ts` | 权限请求处理 |
+| Pointer | `bridgePointer.ts` | 当前活跃 bridge 状态指针 |
+| Flush Gate | `flushGate.ts` | 刷新控制 |
+| JWT Utils | `jwtUtils.ts` | JWT 令牌工具 |
+| Trusted Device | `trustedDevice.ts` | 可信设备管理 |
+| Debug Utils | `debugUtils.ts` | 调试日志 |
+| Types | `types.ts` | 类型定义 |
+
+## 三、关键设计决策
+
+1. **长轮询而非 WebSocket**：`pollForWork` 使用 HTTP GET + 10s 超时。简单可靠，无需维护 WebSocket 连接
+2. **OAuth 刷新内嵌**：API client 自带 `withOAuthRetry`，无需外层重试逻辑
+3. **ETag 条件请求**：注册时支持 `reuseEnvironmentId` 实现幂等会话恢复
+4. **v1/v2 共存**：代码中同时存在两套实现，v2 是更安全的升级版
+5. **权限双向流动**：本地权限请求发送到 claude.ai，用户在 web 上审批
+
+## 四、使用方式
+
+```bash
+# 启用 bridge mode
+FEATURE_BRIDGE_MODE=1 bun run dev
+
+# 从 claude.ai/code 远程连接
+# 在 web 界面选择已注册的环境
+
+# 配合 DAEMON 使用（后台守护）
+FEATURE_BRIDGE_MODE=1 FEATURE_DAEMON=1 bun run dev
+```
+
+## 五、外部依赖
+
+| 依赖 | 说明 |
+|------|------|
+| Anthropic OAuth | claude.ai 订阅登录 |
+| GrowthBook | `tengu_ccr_bridge` 门控 |
+| Bridge API | `/v1/environments/bridge` 系列端点 |
+
+## 六、文件索引
+
+| 文件 | 行数 | 职责 |
+|------|------|------|
+| `src/bridge/bridgeApi.ts` | 541 | API Client（核心） |
+| `src/bridge/sessionRunner.ts` | — | 会话运行器 |
+| `src/bridge/bridgeConfig.ts` | — | 配置管理 |
+| `src/bridge/replBridgeTransport.ts` | — | 传输层 |
+| `src/bridge/bridgePermissionCallbacks.ts` | — | 权限回调 |
+| `src/bridge/bridgePointer.ts` | — | 状态指针 |
+| `src/bridge/flushGate.ts` | — | 刷新控制 |
+| `src/bridge/jwtUtils.ts` | — | JWT 工具 |
+| `src/bridge/trustedDevice.ts` | — | 可信设备 |
+| `src/bridge/remoteBridgeCore.ts` | — | v2 核心实现 |
+| `src/bridge/types.ts` | — | 类型定义 |
+| `src/bridge/debugUtils.ts` | — | 调试工具 |
+| `src/bridge/pollConfigDefaults.ts` | — | 轮询配置默认值 |
+| `src/bridge/bridgeUI.ts` | — | UI 组件 |
+| `src/bridge/codeSessionApi.ts` | — | 代码会话 API |
+| `src/bridge/peerSessions.ts` | — | 对等会话管理 |
+| `src/bridge/sessionIdCompat.ts` | — | Session ID 兼容层 |
+| `src/bridge/createSession.ts` | — | 会话创建 |
+| `src/bridge/replBridgeHandle.ts` | — | Bridge 句柄 |

docs/features/buddy.mdx

@@ -0,0 +1,90 @@
+---
+title: "Buddy 宠物系统"
+description: "Buddy 是 CLI 中的虚拟宠物伴侣，通过 /buddy 命令孵化、互动，会出现在输入框旁边陪伴你写代码。"
+keywords: ["buddy", "宠物", "companion", "伴侣", "虚拟宠物"]
+---
+
+## 概述
+
+Buddy 是 Claude Code 内置的虚拟宠物系统。在 REPL 中通过 `/buddy` 命令可以孵化一只随机生成的宠物伴侣，它会出现在输入框旁边，陪伴你的编码过程。
+
+> Feature Flag: `FEATURE_BUDDY=1`
+
+## 启用方式
+
+```bash
+FEATURE_BUDDY=1 bun run dev
+```
+
+孵化窗口：2026 年 4 月 1-7 日期间启动时，会在 REPL 顶部显示彩虹色的 `/buddy` 提示。4 月 7 日之后命令仍然可用，但不再自动提示。
+
+## 命令
+
+| 命令 | 说明 |
+|---|---|
+| `/buddy` | 查看当前宠物信息和属性 |
+| `/buddy hatch` | 孵化一只新宠物（首次使用） |
+| `/buddy rehatch` | 重新随机生成宠物（替换现有） |
+| `/buddy pet` | 撸宠物，触发爱心动画 |
+| `/buddy mute` | 静音宠物（隐藏） |
+| `/buddy unmute` | 取消静音 |
+
+## 宠物属性
+
+### 物种（18 种）
+
+| | | | |
+|---|---|---|---|
+| Duck | Goose | Blob | Cat |
+| Dragon | Octopus | Owl | Penguin |
+| Turtle | Snail | Ghost | Axolotl |
+| Capybara | Cactus | Robot | Rabbit |
+| Mushroom | Chonk | | |
+
+### 稀有度
+
+| 稀有度 | 星级 | 权重 |
+|---|---|---|
+| Common | ★ | 60% |
+| Uncommon | ★★ | 25% |
+| Rare | ★★★ | 10% |
+| Epic | ★★★★ | 4% |
+| Legendary | ★★★★★ | 1% |
+
+孵化时基于种子随机决定，存在极低概率出现 Shiny（闪光）变体。
+
+### 属性值
+
+每只宠物拥有 5 项属性（0-100）：
+
+- **DEBUGGING** — 调试能力
+- **PATIENCE** — 耐心程度
+- **CHAOS** — 混乱指数
+- **WISDOM** — 智慧值
+- **SNARK** — 毒舌度
+
+### 外观
+
+每只宠物还有随机的外观配件：
+
+- **眼睛**: `·` `✦` `×` `◉` `@` `°`
+- **帽子**: none, crown, tophat, propeller, halo, wizard, beanie, tinyduck
+
+## 数据存储
+
+宠物信息存储在 `~/.claude.json` 的 `companion` 字段中。宠物的外观属性（物种、稀有度、属性值等）基于用户 ID 的哈希确定性生成，不可通过编辑配置文件来篡改稀有度。
+
+## 相关源码
+
+| 文件 | 说明 |
+|---|---|
+| `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

@@ -1,9 +1,3 @@
----
-title: "频道消息推送（Channels）"
-description: "MCP 服务器把飞书 / Slack / Discord / 微信等外部消息推到会话，`--channels plugin:name@marketplace` 启用。"
-keywords: ["Channels", "频道消息", "微信 channel", "飞书 channel", "MCP 事件推送"]
----
-
 # Channels — 外部频道消息接入
 
 > 启动参数：`--channels` / `--dangerously-load-development-channels`

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/claude-in-chrome-mcp.md

@@ -0,0 +1,137 @@
+# Claude in Chrome — 用户操作指南
+
+## 1. 功能简介
+
+Claude in Chrome 让 Claude Code 直接控制你的 Chrome 浏览器。你可以用自然语言让 Claude 帮你：
+
+- 打开网页、导航、前进后退
+- 填写表单、上传图片
+- 截图、录制 GIF
+- 读取页面内容（DOM、纯文本）
+- 执行 JavaScript
+- 监控网络请求和控制台日志
+- 管理标签页
+
+## 2. 前置条件
+
+| 条件 | 说明 |
+|------|------|
+| Claude Code 订阅 | 需要 Claude Pro、Max 或 Team 订阅，浏览器插件功能不向免费用户开放 |
+| Chrome 浏览器 | 需已安装 Google Chrome |
+| Claude in Chrome 扩展 | 从 Chrome Web Store 安装（`claude.ai/chrome`） |
+| Claude Code CLI | 已通过 `bun run dev` 或构建产物运行 |
+
+## 3. 启用方式
+
+### Dev 模式
+
+```bash
+bun run dev -- --chrome
+```
+
+启动后 Claude 会自动检测 Chrome 扩展是否已安装，并注册浏览器控制工具。
+
+### 构建产物
+
+```bash
+node dist/cli.js --chrome
+```
+
+### 禁用
+
+```bash
+bun run dev -- --no-chrome
+```
+
+或在 REPL 中通过 `/chrome` 命令切换启用/禁用状态。
+
+### 通过配置默认启用
+
+在 Claude Code 设置中将 `claudeInChromeDefaultEnabled` 设为 `true`，以后启动无需加 `--chrome` 参数。
+
+## 4. 使用流程
+
+1. **启动 CLI** — 加 `--chrome` 参数启动 Claude Code
+2. **确认连接** — REPL 中输入 `/chrome`，查看扩展状态是否显示 "Installed / Connected"
+3. **开始对话** — 正常与 Claude 对话，当需要操作浏览器时直接说，例如：
+   - "打开 https://example.com 并截图"
+   - "在当前页面搜索关键词 xxx"
+   - "填写登录表单，用户名 admin"
+   - "帮我录制当前操作的 GIF"
+4. **权限审批** — 首次执行浏览器操作时，Claude 会请求你的确认
+5. **操作完成** — Claude 完成操作后会返回结果（截图、文本、执行结果等）
+
+## 5. 可用操作
+
+### 页面交互
+
+| 操作 | 说明 |
+|------|------|
+| `navigate` | 导航到指定 URL，或前进/后退 |
+| `computer` | 鼠标点击、移动、拖拽、键盘输入、截图等（13 种 action） |
+| `form_input` | 填写表单字段 |
+| `upload_image` | 上传图片到文件输入框或拖拽区域 |
+| `javascript_tool` | 在页面上下文执行 JavaScript |
+
+### 页面读取
+
+| 操作 | 说明 |
+|------|------|
+| `read_page` | 获取页面可访问性树（DOM 结构） |
+| `get_page_text` | 提取页面纯文本内容 |
+| `find` | 用自然语言搜索页面元素 |
+
+### 标签页管理
+
+| 操作 | 说明 |
+|------|------|
+| `tabs_context_mcp` | 获取当前标签组信息 |
+| `tabs_create_mcp` | 创建新标签页 |
+
+### 监控与调试
+
+| 操作 | 说明 |
+|------|------|
+| `read_console_messages` | 读取浏览器控制台日志 |
+| `read_network_requests` | 读取网络请求记录 |
+
+### 其他
+
+| 操作 | 说明 |
+|------|------|
+| `resize_window` | 调整浏览器窗口尺寸 |
+| `gif_creator` | 录制 GIF 并导出 |
+| `shortcuts_list` | 列出可用快捷方式 |
+| `shortcuts_execute` | 执行快捷方式 |
+| `update_plan` | 向你提交操作计划供审批 |
+| `switch_browser` | 切换到其他 Chrome 浏览器（仅 Bridge 模式） |
+
+## 6. 通信模式
+
+Claude in Chrome 支持两种与浏览器通信的方式：
+
+### 本地 Socket（默认）
+
+Chrome 扩展通过 Native Messaging Host 与 CLI 建立 Unix socket 连接。适用于本地开发，无需额外配置。
+
+### Bridge WebSocket
+
+通过 Anthropic 的 bridge 服务中转，支持远程操控浏览器。需要 claude.ai OAuth 登录。
+
+## 7. 常见问题
+
+### 扩展显示未安装
+
+确认已从 Chrome Web Store 安装 "Claude in Chrome" 扩展，安装后重启浏览器。
+
+### 工具未出现在工具列表
+
+检查启动时是否加了 `--chrome` 参数，或通过 `/chrome` 命令确认状态。
+
+### 连接超时
+
+确保 Chrome 浏览器正在运行且扩展已启用。Native Messaging Host 在扩展安装时自动注册，如果重装过扩展需要重启浏览器。
+
+### 不使用 Chrome 功能时
+
+不带 `--chrome` 参数正常启动即可，不会加载任何浏览器相关模块，不影响其他功能。

docs/features/computer-use-architecture-v2.md

@@ -0,0 +1,325 @@
+# Computer Use 架构修正方案 v2
+
+更新时间：2026-04-04
+
+## 1. 当前架构的问题
+
+### 问题 A：平台代码混在错误的包里
+
+`@ant/computer-use-swift` 是 macOS Swift 原生模块的包装器，但我们把 Windows（`backends/win32.ts`）和 Linux（`backends/linux.ts`）的截图/应用管理代码塞进了这个包。"swift" 在名字里就意味着 macOS，后期维护者无法区分。
+
+`@ant/computer-use-input` 同样——原本是 macOS enigo Rust 模块，我们也往里面塞了 win32/linux 后端。
+
+### 问题 B：输入方式不对
+
+当前 Windows 后端（`packages/@ant/computer-use-input/src/backends/win32.ts`）使用 `SetCursorPos` + `SendInput` + `keybd_event`——这是**全局输入**：
+
+- 鼠标真的会移动到屏幕上
+- 键盘真的打到当前前台窗口
+- **会影响用户当前的操作**
+
+绑定窗口句柄后，应该用 `SendMessage`/`PostMessage` 向目标 HWND 发送消息：
+
+- `WM_CHAR` — 发送字符，不移动光标
+- `WM_KEYDOWN`/`WM_KEYUP` — 发送按键
+- `WM_LBUTTONDOWN`/`WM_LBUTTONUP` — 发送鼠标点击（窗口客户区相对坐标）
+- `PrintWindow` — 截取窗口内容，不需要窗口在前台
+- **不抢焦点、不影响用户当前操作**
+
+已验证：向记事本 `SendMessage(WM_CHAR)` 成功写入文字，记事本在后台，终端保持前台。
+
+### 问题 C：截图是公共能力，不属于 swift
+
+截图（screenshot）、显示器枚举（display）、应用管理（apps）是所有平台都需要的公共能力，不应该放在 `@ant/computer-use-swift`（macOS 专属包名）里。
+
+## 2. 修正后的架构
+
+### 2.1 分层原则
+
+```
+packages/@ant/                     ← macOS 原生模块包装器（不放其他平台代码）
+├── computer-use-input/             ← macOS: enigo .node 键鼠（仅 darwin）
+├── computer-use-swift/             ← macOS: Swift .node 截图/应用（仅 darwin）
+└── computer-use-mcp/               ← 跨平台: MCP server + 工具定义（不改）
+
+src/utils/computerUse/
+├── platforms/                     ← 新增: 跨平台抽象层
+│   ├── types.ts                    ← 公共接口: InputPlatform, ScreenshotPlatform, AppsPlatform, DisplayPlatform
+│   ├── index.ts                    ← 平台分发器: 按 process.platform 加载后端
+│   ├── darwin.ts                   ← macOS: 委托给 @ant/computer-use-{input,swift}
+│   ├── win32.ts                    ← Windows: SendMessage 输入 + PrintWindow 截图 + EnumWindows + UIA + OCR
+│   └── linux.ts                    ← Linux: xdotool + scrot + xrandr + wmctrl
+│
+├── win32/                         ← Windows 专属增强能力（不在公共接口中）
+│   ├── windowCapture.ts            ← PrintWindow 窗口绑定截图
+│   ├── windowEnum.ts               ← EnumWindows 窗口枚举
+│   ├── windowMessage.ts            ← SendMessage/PostMessage 无焦点输入（新增）
+│   ├── uiAutomation.ts             ← IUIAutomation UI 元素操作
+│   └── ocr.ts                      ← Windows.Media.Ocr 文字识别
+│
+├── executor.ts                    ← 改: 通过 platforms/ 获取平台实现，不直接调 @ant 包
+├── swiftLoader.ts                 ← 改: 仅 darwin 使用
+├── inputLoader.ts                 ← 改: 仅 darwin 使用
+└── ...其他文件不动
+```
+
+### 2.2 公共接口（`platforms/types.ts`）
+
+```typescript
+/** 窗口标识 — 跨平台 */
+export interface WindowHandle {
+  id: string           // macOS: bundleId, Windows: HWND string, Linux: window ID
+  pid: number
+  title: string
+  exePath?: string     // Windows/Linux: 进程路径
+}
+
+/** 输入平台接口 — 两种模式 */
+export interface InputPlatform {
+  // 模式 A: 全局输入（macOS/Linux 默认，向前台窗口发送）
+  moveMouse(x: number, y: number): Promise<void>
+  click(x: number, y: number, button: 'left' | 'right' | 'middle'): Promise<void>
+  typeText(text: string): Promise<void>
+  key(name: string, action: 'press' | 'release'): Promise<void>
+  keys(combo: string[]): Promise<void>
+  scroll(amount: number, direction: 'vertical' | 'horizontal'): Promise<void>
+  mouseLocation(): Promise<{ x: number; y: number }>
+  
+  // 模式 B: 窗口绑定输入（Windows SendMessage，不抢焦点）
+  sendChar?(hwnd: string, char: string): Promise<void>
+  sendKey?(hwnd: string, vk: number, action: 'down' | 'up'): Promise<void>
+  sendClick?(hwnd: string, x: number, y: number, button: 'left' | 'right'): Promise<void>
+  sendText?(hwnd: string, text: string): Promise<void>
+}
+
+/** 截图平台接口 */
+export interface ScreenshotPlatform {
+  // 全屏截图
+  captureScreen(displayId?: number): Promise<ScreenshotResult>
+  // 区域截图
+  captureRegion(x: number, y: number, w: number, h: number): Promise<ScreenshotResult>
+  // 窗口截图（Windows: PrintWindow，macOS: SCContentFilter，Linux: xdotool+import）
+  captureWindow?(hwnd: string): Promise<ScreenshotResult | null>
+}
+
+/** 显示器平台接口 */
+export interface DisplayPlatform {
+  listAll(): DisplayInfo[]
+  getSize(displayId?: number): DisplayInfo
+}
+
+/** 应用管理平台接口 */
+export interface AppsPlatform {
+  listRunning(): WindowHandle[]
+  listInstalled(): Promise<InstalledApp[]>
+  open(name: string): Promise<void>
+  getFrontmostApp(): FrontmostAppInfo | null
+  findWindowByTitle(title: string): WindowHandle | null
+}
+
+export interface ScreenshotResult {
+  base64: string
+  width: number
+  height: number
+}
+
+export interface DisplayInfo {
+  width: number
+  height: number
+  scaleFactor: number
+  displayId: number
+}
+
+export interface InstalledApp {
+  id: string       // macOS: bundleId, Windows: exe path, Linux: .desktop name
+  displayName: string
+  path: string
+}
+
+export interface FrontmostAppInfo {
+  id: string
+  appName: string
+}
+```
+
+### 2.3 平台分发器（`platforms/index.ts`）
+
+```typescript
+import type { InputPlatform, ScreenshotPlatform, DisplayPlatform, AppsPlatform } from './types.js'
+
+export interface Platform {
+  input: InputPlatform
+  screenshot: ScreenshotPlatform
+  display: DisplayPlatform
+  apps: AppsPlatform
+}
+
+export function loadPlatform(): Platform {
+  switch (process.platform) {
+    case 'darwin':
+      return require('./darwin.js').platform
+    case 'win32':
+      return require('./win32.js').platform
+    case 'linux':
+      return require('./linux.js').platform
+    default:
+      throw new Error(`Computer Use not supported on ${process.platform}`)
+  }
+}
+```
+
+### 2.4 各平台实现
+
+**`platforms/darwin.ts`** — 委托给 @ant 包（保持兼容）：
+```typescript
+// macOS: 通过 @ant/computer-use-input 和 @ant/computer-use-swift
+// 这两个包的 darwin 后端保留不动
+import { requireComputerUseInput } from '../inputLoader.js'
+import { requireComputerUseSwift } from '../swiftLoader.js'
+
+export const platform = {
+  input: { /* 委托给 requireComputerUseInput() */ },
+  screenshot: { /* 委托给 requireComputerUseSwift().screenshot */ },
+  display: { /* 委托给 requireComputerUseSwift().display */ },
+  apps: { /* 委托给 requireComputerUseSwift().apps */ },
+}
+```
+
+**`platforms/win32.ts`** — 使用 `src/utils/computerUse/win32/` 模块：
+```typescript
+// Windows: SendMessage 输入 + PrintWindow 截图 + EnumWindows 应用
+import { sendChar, sendKey, sendClick, sendText } from '../win32/windowMessage.js'
+import { captureWindow } from '../win32/windowCapture.js'
+import { listWindows } from '../win32/windowEnum.js'
+// ... PowerShell P/Invoke 全局输入作为 fallback
+
+export const platform = {
+  input: {
+    // 全局模式: PowerShell SetCursorPos/SendInput（fallback）
+    // 窗口模式: SendMessage（首选）
+    sendChar, sendKey, sendClick, sendText,  // 窗口绑定
+    moveMouse, click, typeText, ...           // 全局 fallback
+  },
+  screenshot: {
+    captureScreen,     // CopyFromScreen
+    captureRegion,     // CopyFromScreen(rect)
+    captureWindow,     // PrintWindow（不抢焦点）
+  },
+  display: { /* Screen.AllScreens */ },
+  apps: { /* EnumWindows */ },
+}
+```
+
+**`platforms/linux.ts`** — 使用 xdotool/scrot：
+```typescript
+// Linux: xdotool + scrot + xrandr + wmctrl
+export const platform = {
+  input: { /* xdotool mousemove/click/key/type */ },
+  screenshot: { /* scrot */ },
+  display: { /* xrandr */ },
+  apps: { /* wmctrl + ps */ },
+}
+```
+
+### 2.5 executor.ts 改造
+
+```typescript
+// 之前: 直接调 requireComputerUseSwift() 和 requireComputerUseInput()
+// 之后: 通过 platforms/ 统一获取
+
+import { loadPlatform } from './platforms/index.js'
+
+const platform = loadPlatform()
+
+// 截图
+platform.screenshot.captureScreen()
+platform.screenshot.captureWindow(hwnd)  // 窗口绑定
+
+// 输入（窗口绑定模式，不抢焦点）
+platform.input.sendText?.(hwnd, 'Hello')
+platform.input.sendClick?.(hwnd, 100, 200, 'left')
+
+// 输入（全局模式，fallback）
+platform.input.moveMouse(500, 500)
+platform.input.click(500, 500, 'left')
+```
+
+## 3. Windows 输入模式对比
+
+| 方式 | API | 抢焦点 | 移鼠标 | 窗口可最小化 | 适用场景 |
+|------|-----|--------|--------|-------------|---------|
+| **全局输入** | `SetCursorPos` + `SendInput` | ✅ 抢 | ✅ 动 | ❌ 不行 | 需要坐标点击（fallback） |
+| **窗口消息** | `SendMessage(WM_CHAR/WM_KEYDOWN)` | ❌ 不抢 | ❌ 不动 | ✅ 可以 | 打字、按键（首选） |
+| **窗口消息** | `SendMessage(WM_LBUTTONDOWN)` | ❌ 不抢 | ❌ 不动 | ⚠️ 部分 | 窗口内点击 |
+| **窗口截图** | `PrintWindow(hwnd, PW_RENDERFULLCONTENT)` | ❌ 不抢 | ❌ 不动 | ✅ 可以 | 窗口截图 |
+| **UI 操作** | `UIAutomation InvokePattern` | ❌ 不抢 | ❌ 不动 | ✅ 可以 | 按钮点击、文本写入 |
+
+**策略**：优先用窗口消息 + UIAutomation（不干扰用户），全局输入作为 fallback。
+
+## 4. 需要新增的文件
+
+| 文件 | 说明 |
+|------|------|
+| `src/utils/computerUse/platforms/types.ts` | 公共接口定义 |
+| `src/utils/computerUse/platforms/index.ts` | 平台分发器 |
+| `src/utils/computerUse/platforms/darwin.ts` | macOS: 委托给 @ant 包 |
+| `src/utils/computerUse/platforms/win32.ts` | Windows: 组合 win32/ 下各模块 |
+| `src/utils/computerUse/platforms/linux.ts` | Linux: xdotool/scrot |
+| `src/utils/computerUse/win32/windowMessage.ts` | **新增**: SendMessage 无焦点输入 |
+
+## 5. 需要移除/清理的文件
+
+| 文件 | 操作 | 原因 |
+|------|------|------|
+| `packages/@ant/computer-use-input/src/backends/win32.ts` | 删除 | Windows 代码不应在 macOS 包里 |
+| `packages/@ant/computer-use-input/src/backends/linux.ts` | 删除 | Linux 代码不应在 macOS 包里 |
+| `packages/@ant/computer-use-swift/src/backends/win32.ts` | 删除 | 同上 |
+| `packages/@ant/computer-use-swift/src/backends/linux.ts` | 删除 | 同上 |
+| `packages/@ant/computer-use-input/src/types.ts` | 删除 | 移到 platforms/types.ts |
+| `packages/@ant/computer-use-swift/src/types.ts` | 删除 | 移到 platforms/types.ts |
+
+## 6. 需要修改的文件
+
+| 文件 | 改动 |
+|------|------|
+| `packages/@ant/computer-use-input/src/index.ts` | 恢复为仅 darwin dispatcher（去掉 win32/linux case） |
+| `packages/@ant/computer-use-swift/src/index.ts` | 恢复为仅 darwin dispatcher（去掉 win32/linux case） |
+| `src/utils/computerUse/executor.ts` | 通过 `platforms/` 获取平台实现，不直接调 @ant 包 |
+| `src/utils/computerUse/swiftLoader.ts` | 仅 darwin 加载 |
+| `src/utils/computerUse/inputLoader.ts` | 仅 darwin 加载 |
+
+## 7. @ant 包的定位（修正后）
+
+| 包 | 职责 | 平台 |
+|---|------|------|
+| `@ant/computer-use-input` | macOS enigo 键鼠原生模块包装 | **仅 darwin** |
+| `@ant/computer-use-swift` | macOS Swift 截图/应用原生模块包装 | **仅 darwin** |
+| `@ant/computer-use-mcp` | MCP Server + 工具定义 + 调用路由 | **跨平台**（不含平台代码） |
+
+Windows/Linux 的平台实现全部在 `src/utils/computerUse/platforms/` 和 `src/utils/computerUse/win32/` 中。
+
+## 8. 执行顺序
+
+```
+Phase 1: 创建 platforms/ 抽象层
+  ├── platforms/types.ts（公共接口）
+  ├── platforms/index.ts（分发器）
+  └── platforms/darwin.ts（委托 @ant 包）
+
+Phase 2: 创建 Windows 平台实现
+  ├── win32/windowMessage.ts（SendMessage 无焦点输入）
+  └── platforms/win32.ts（组合 win32/ 各模块）
+
+Phase 3: 创建 Linux 平台实现
+  └── platforms/linux.ts（xdotool/scrot）
+
+Phase 4: 改造 executor.ts
+  └── 通过 platforms/ 获取实现，不直接调 @ant
+
+Phase 5: 清理 @ant 包
+  ├── 删除 @ant/computer-use-input/src/backends/{win32,linux}.ts
+  ├── 删除 @ant/computer-use-swift/src/backends/{win32,linux}.ts
+  └── 恢复 index.ts 为 darwin-only
+
+Phase 6: 验证 + PR
+```

docs/features/computer-use-mcp-test-report.md

@@ -0,0 +1,277 @@
+# Computer Use MCP 工具测试报告
+
+> 测试日期: 2026-04-04
+> 测试环境: macOS Darwin 25.4.0, Cursor (IDE tier: click)
+> MCP Server: `@ant/computer-use-mcp`
+
+## 工具总览
+
+共 17 个工具（含 batch 复合操作），分为 5 大类：
+
+| 类别 | 工具 | 数量 |
+|------|------|------|
+| 截图/显示 | `screenshot`, `switch_display`, `zoom` | 3 |
+| 鼠标操作 | `left_click`, `right_click`, `double_click`, `triple_click`, `middle_click`, `left_click_drag`, `mouse_move` | 7 |
+| 键盘操作 | `key`, `type`, `hold_key` | 3 |
+| 状态查询 | `cursor_position`, `request_access` | 2 |
+| 复合/辅助 | `computer_batch`, `wait` | 2 |
+
+---
+
+## 测试结果
+
+### 1. 权限管理
+
+#### `request_access` — 请求应用访问权限
+
+| 项目 | 结果 |
+|------|------|
+| 状态 | ✅ 通过 |
+| 行为 | 弹出系统对话框请求用户授权，支持批量申请多个应用 |
+| 返回 | `{ granted: [...], denied: [...], tierGuidance: "..." }` |
+| 权限分级 | `click`（仅点击）, `full`（完整控制） |
+| 说明 | IDE 类应用（Cursor、VSCode、Terminal）默认授予 `click` tier，限制键盘输入和右键操作；系统应用（System Settings）授予 `full` tier |
+
+#### 已授权应用
+
+| 应用 | Tier | 能力 |
+|------|------|------|
+| Cursor | click | 可见 + 纯左键点击（无键盘输入、右键、修饰键点击、拖拽） |
+| Terminal | click | 同上 |
+| System Settings | full | 完整控制（键鼠、拖拽等） |
+| Finder | — | 已授权 |
+
+---
+
+### 2. 截图与显示
+
+#### `screenshot` — 截取屏幕截图
+
+| 项目 | 结果 |
+|------|------|
+| 状态 | ⚠️ 部分通过 |
+| 执行 | 工具成功执行，返回 `ok: true` |
+| 图片 | **未返回可视图片内容**（output 为空字符串） |
+| `save_to_disk` | 设置后仍无输出 |
+| 分析 | 可能原因：(1) macOS 屏幕录制权限未授予；(2) 当前前台应用未被过滤导致截图为空；(3) MCP 传输层未正确编码图片数据 |
+| 建议 | 检查 **系统设置 → 隐私与安全性 → 屏幕录制** 是否授权给运行 Claude Code 的应用 |
+
+#### `switch_display` — 切换显示器
+
+| 项目 | 结果 |
+|------|------|
+| 状态 | ✅ 通过 |
+| 行为 | 接受显示器名称或 `"auto"`（自动选择） |
+| 返回 | 确认消息 |
+
+#### `zoom` — 区域放大截图
+
+| 项目 | 结果 |
+|------|------|
+| 状态 | ⏭️ 跳过 |
+| 原因 | 依赖 `screenshot` 返回的图片坐标，截图未返回图片无法测试 |
+
+---
+
+### 3. 鼠标操作
+
+> 以下测试在 Cursor 窗口上执行（tier: click）
+
+#### `mouse_move` — 移动鼠标
+
+| 项目 | 结果 |
+|------|------|
+| 状态 | ✅ 通过 |
+| 输入 | `coordinate: [500, 500]` |
+| 返回 | `"Moved."` |
+
+#### `left_click` — 左键单击
+
+| 项目 | 结果 |
+|------|------|
+| 状态 | ✅ 通过 |
+| 输入 | `coordinate: [500, 500]` |
+| 返回 | `"Clicked."` |
+
+#### `double_click` — 双击
+
+| 项目 | 结果 |
+|------|------|
+| 状态 | ✅ 通过 |
+| 输入 | `coordinate: [500, 500]` |
+| 返回 | `"Clicked."` |
+
+#### `triple_click` — 三击
+
+| 项目 | 结果 |
+|------|------|
+| 状态 | ✅ 通过 |
+| 输入 | `coordinate: [500, 500]` |
+| 返回 | `"Clicked."` |
+
+#### `right_click` — 右键点击
+
+| 项目 | 结果 |
+|------|------|
+| 状态 | ⚠️ 受 tier 限制 |
+| Cursor (click tier) | ❌ 被拒绝 — `"Code" is granted at tier "click" — right-click, middle-click, and clicks with modifier keys require tier "full"` |
+| Finder (full tier) | ✅ 通过 — 返回 `"Clicked."` |
+| 结论 | 功能正常，IDE 安全限制符合预期 |
+
+#### `middle_click` — 中键点击
+
+| 项目 | 结果 |
+|------|------|
+| 状态 | ⚠️ 受 tier 限制 |
+| Cursor (click tier) | ❌ 被拒绝 — 同 `right_click`，需要 full tier |
+| Finder (full tier) | ✅ 通过 — 返回 `"Clicked."` |
+| 结论 | 功能正常，IDE 安全限制符合预期 |
+
+#### `left_click_drag` — 拖拽
+
+| 项目 | 结果 |
+|------|------|
+| 状态 | ⚠️ 受 tier 限制 |
+| Cursor (click tier) | ❌ 被拒绝 — 拖拽被视为修饰键点击，需要 full tier |
+| Finder (full tier) | ✅ 通过 — 返回 `"Dragged."` |
+| 结论 | 功能正常，IDE 安全限制符合预期 |
+
+#### `scroll` — 滚轮滚动
+
+| 项目 | 结果 |
+|------|------|
+| 状态 | ✅ 通过 |
+| 输入 | `coordinate: [500, 500]`, `scroll_direction: "down"`, `scroll_amount: 3` |
+| 返回 | `"Scrolled."` |
+| 反向 | ✅ `scroll_direction: "up"` 也通过 |
+
+---
+
+### 4. 键盘操作
+
+> 以下测试在 Cursor 窗口上执行（tier: click）— 所有键盘操作均被拒绝
+
+#### `key` — 按键/快捷键
+
+| 项目 | 结果 |
+|------|------|
+| 状态 | ⚠️ 受 tier 限制 |
+| Cursor (click tier) | ❌ 被拒绝 — IDE tier 限制键盘输入 |
+| Finder (full tier) | ✅ 通过 — `escape` 按键成功，返回 `"Key pressed."` |
+| 结论 | 功能正常，IDE 安全限制符合预期 |
+
+#### `type` — 输入文本
+
+| 项目 | 结果 |
+|------|------|
+| 状态 | ⚠️ 受 tier 限制 |
+| Cursor (click tier) | ❌ 被拒绝 — IDE tier 限制文本输入 |
+| Finder (full tier) | ✅ 通过 — 输入 `"hello"` 成功，返回 `"Typed 5 grapheme(s)."` |
+| 结论 | 功能正常，IDE 安全限制符合预期 |
+
+#### `hold_key` — 按住按键
+
+| 项目 | 结果 |
+|------|------|
+| 状态 | ⚠️ 受 tier 限制 |
+| Cursor (click tier) | ❌ 被拒绝 — IDE tier 限制键盘输入 |
+| Finder (full tier) | ✅ 通过 — 按住 `shift` 1 秒成功，返回 `"Key held."` |
+| 结论 | 功能正常，IDE 安全限制符合预期 |
+
+---
+
+### 5. 状态查询
+
+#### `cursor_position` — 获取鼠标位置
+
+| 项目 | 结果 |
+|------|------|
+| 状态 | ✅ 通过 |
+| 返回 | `{"x": null, "y": null, "coordinateSpace": "image_pixels"}` |
+| 说明 | 坐标为 null 是因为没有成功截图，无参考坐标系 |
+
+---
+
+### 6. 复合/辅助操作
+
+#### `computer_batch` — 批量执行操作
+
+| 项目 | 结果 |
+|------|------|
+| 状态 | ✅ 通过 |
+| 行为 | 按顺序执行操作列表，遇到失败则停止后续操作 |
+| 返回 | `{ completed: [...], failed: {...}, remaining: N }` |
+| 特点 | 单次 API 调用执行多个操作，减少往返延迟 |
+| 错误处理 | 失败的操作会中断后续操作，返回已完成和剩余数量 |
+
+#### `wait` — 等待
+
+| 项目 | 结果 |
+|------|------|
+| 状态 | ✅ 通过 |
+| 输入 | `duration: 1` (秒) |
+| 返回 | `"Waited 1s."` |
+| 最大值 | 100 秒 |
+
+---
+
+## 汇总统计
+
+| 状态 | 数量 | 工具 |
+|------|------|------|
+| ✅ 通过 | 10 | `request_access`, `switch_display`, `mouse_move`, `left_click`, `double_click`, `triple_click`, `scroll`, `cursor_position`, `computer_batch`, `wait` |
+| ⚠️ 部分通过 | 7 | `screenshot`（执行成功但无图片返回）, `right_click`, `middle_click`, `left_click_drag`, `key`, `type`, `hold_key`（均在 full tier 应用上通过，IDE click tier 限制是预期行为） |
+| ❌ 被拒绝 | 0 | — |
+| ⏭️ 跳过 | 1 | `zoom`（依赖截图） |
+
+---
+
+## 已知问题
+
+### P0: 截图无图片返回
+
+`screenshot` 工具执行成功但未返回图片内容，导致：
+- 无法获取屏幕坐标参考
+- `cursor_position` 返回 null 坐标
+- `zoom` 无法使用
+- 所有点击操作只能盲点（无截图验证）
+
+**可能原因**:
+1. macOS 屏幕录制权限未授予
+2. MCP 图片传输/编码问题
+3. 截图内容被安全过滤机制过滤
+
+**建议排查**: 检查 `系统设置 → 隐私与安全性 → 屏幕录制` 权限。
+
+### P1: IDE 应用键盘操作受限 — ✅ 已确认功能正常
+
+IDE 类应用（Cursor、VSCode、Terminal）被限制在 `click` tier，无法执行：
+- 键盘输入（`key`, `type`, `hold_key`）
+- 右键/中键点击（`right_click`, `middle_click`）
+- 拖拽操作（`left_click_drag`）
+
+这是安全设计，防止 AI 操控 IDE 终端。**在 full tier 应用（Finder、System Settings）上，以上 6 个操作均测试通过，功能完全正常。**
+
+---
+
+## 权限模型说明
+
+Computer Use MCP 采用分级权限模型：
+
+```
+┌─────────────────────────────────────────┐
+│  Tier: full                             │
+│  - 所有鼠标操作（左键、右键、中键、拖拽）  │
+│  - 键盘输入（type, key, hold_key）       │
+│  - 适用于: 系统应用、Finder 等           │
+├─────────────────────────────────────────┤
+│  Tier: click                            │
+│  - 仅纯左键点击                          │
+│  - 滚轮滚动                             │
+│  - 适用于: IDE、Terminal 等              │
+├─────────────────────────────────────────┤
+│  未授权                                  │
+│  - 所有操作被拒绝                        │
+│  - 需通过 request_access 申请            │
+└─────────────────────────────────────────┘
+```

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

@@ -1,170 +1,29 @@
----
+# Computer Use 工具参考文档
-title: "屏幕控制（Computer Use）"
-description: "截屏、键鼠控制，跨 macOS / Windows / Linux。本文包含快速上手、平台差异说明和工具参考。"
-keywords: [屏幕控制, 截屏, 键鼠模拟, 跨平台自动化, Computer Use]
----
 
-# 屏幕控制（Computer Use）
+## 概览
 
-Computer Use 提供截屏、键鼠控制和应用管理能力，支持 macOS / Windows / Linux 三大桌面平台。Windows 平台额外提供窗口绑定模式（不干扰真实键鼠），全平台共 38 个工具。
+Computer Use 提供 38 个工具，分为三类：
-
-本文包含三部分：
-
-- **快速上手** — 启用方式与典型操作流程
-- **平台差异说明** — 三平台的实现、依赖与能力差异
-- **工具参考** — 全部工具的参数、用法和进阶场景
-
-## 概述
-
-Computer Use 由三个 workspace 包组成：
-
-| 包 | 职责 |
-|----|------|
-| `@ant/computer-use-mcp` | MCP server 入口与工具注册（12 文件） |
-| `@ant/computer-use-input` | 键鼠模拟（dispatcher + 各平台 backend） |
-| `@ant/computer-use-swift` | 截图与应用管理（dispatcher + 各平台 backend） |
-
-工具共 38 个，分三类：
 
 | 分类 | 平台 | 工具数 | 说明 |
 |------|------|--------|------|
 | 通用工具 | 全平台 | 24 | 官方 Computer Use 标准能力 |
 | Windows 专属工具 | Win32 | 11 | 绑定窗口模式下的增强能力 |
-| 教学工具 | 全平台 | 3 | 分步引导模式（需 `teachMode` 开启） |
+| 教学工具 | 全平台 | 3 | 分步引导模式（需 teachMode 开启） |
 
-## 快速上手
+---
 
-### 启用方式
+## 一、通用工具（24 个）
-
-在启动 Claude Code 时附加 `--computer-use-mcp`，或在运行时通过 `feature("CHICAGO_MCP")` 控制入口初始化。
-
-```bash
-claude --computer-use-mcp
-```
-
-Linux 平台需要先安装依赖工具（详见下文「Linux 依赖工具」）。macOS / Windows 通常无需额外安装。
-
-### 典型操作流程
-
-#### 流程 1：全屏操作（未绑定窗口）
-
-```
-request_access(apps=["Notepad"])
-open_application(app="Notepad")          ← 自动绑定窗口
-screenshot                               ← PrintWindow 截图 + GUI 元素列表
-left_click(coordinate=[500, 300])        ← 全局 SendInput
-type(text="hello world")                 ← 全局 SendInput
-key(text="ctrl+s")                       ← 全局 SendInput
-```
-
-#### 流程 2：绑定窗口操作（Windows 推荐，不干扰用户）
-
-```
-request_access(apps=["Notepad"])
-bind_window(action="list")               ← 列出所有窗口
-bind_window(action="bind", title="记事本") ← 绑定 + 绿色边框 + 虚拟光标
-screenshot                               ← PrintWindow 截取绑定窗口
-virtual_mouse(action="click", coordinate=[500, 300])   ← SendMessageW，不动真实鼠标
-virtual_keyboard(action="type", text="hello world")    ← SendMessageW，不动物理键盘
-virtual_keyboard(action="combo", text="ctrl+s")        ← 保存
-mouse_wheel(coordinate=[500, 400], delta=-5)           ← 向下滚动
-bind_window(action="unbind")             ← 解除绑定
-```
-
-#### 流程 3：按元素名称操作
-
-```
-bind_window(action="bind", title="记事本")
-screenshot                               ← 返回截图 + GUI elements 列表
-click_element(name="保存", role="Button") ← UI Automation 查找并点击
-type_into_element(role="Edit", text="new content")
-```
-
-#### 流程 4：终端交互
-
-```
-bind_window(action="bind", title="PowerShell")
-screenshot
-prompt_respond(response_type="yes")      ← 回答 y + Enter
-prompt_respond(response_type="select", arrow_direction="down", arrow_count=2)  ← 选第3项
-```
-
-#### 流程 5：Excel/浏览器滚动
-
-```
-bind_window(action="bind", title="Excel")
-screenshot
-mouse_wheel(coordinate=[600, 400], delta=-10)            ← 向下滚动 10 格
-mouse_wheel(coordinate=[600, 400], delta=5, direction="horizontal")  ← 向右滚动
-```
-
-## 平台差异说明
-
-### 各平台能力依赖
-
-#### computer-use-input（键鼠）
-
-| 功能 | macOS | Windows | Linux |
-|------|-------|---------|-------|
-| 鼠标移动 | CGEvent JXA | SetCursorPos P/Invoke | xdotool mousemove |
-| 鼠标点击 | CGEvent JXA | SendInput P/Invoke | xdotool click |
-| 鼠标滚轮 | CGEvent JXA | SendInput MOUSEEVENTF_WHEEL | xdotool scroll |
-| 键盘按键 | System Events osascript | keybd_event P/Invoke | xdotool key |
-| 组合键 | System Events osascript | keybd_event 组合 | xdotool key combo |
-| 文本输入 | System Events keystroke | SendKeys.SendWait | xdotool type |
-| 前台应用 | System Events osascript | GetForegroundWindow P/Invoke | xdotool getactivewindow + /proc |
-| 工具依赖 | osascript（内置） | powershell（内置） | xdotool（需安装） |
-
-#### computer-use-swift（截图 + 应用管理）
-
-| 功能 | macOS | Windows | Linux |
-|------|-------|---------|-------|
-| 全屏截图 | screencapture | CopyFromScreen | gnome-screenshot / scrot / grim |
-| 区域截图 | screencapture -R | CopyFromScreen(rect) | gnome-screenshot -a / scrot -a / grim -g |
-| 显示器列表 | CGGetActiveDisplayList JXA | Screen.AllScreens | xrandr --query |
-| 运行中应用 | System Events JXA | Get-Process | wmctrl -l / ps |
-| 打开应用 | osascript activate | Start-Process | xdg-open / gtk-launch |
-| 隐藏/显示 | System Events visibility | ShowWindow/SetForegroundWindow | wmctrl -c / xdotool |
-| 工具依赖 | screencapture + osascript | powershell | xdotool + scrot/grim + wmctrl |
-
-#### executor 层
-
-| 功能 | macOS | Windows | Linux |
-|------|-------|---------|-------|
-| drainRunLoop | CFRunLoop pump | 不需要 | 不需要 |
-| ESC 热键 | CGEventTap | 跳过（Ctrl+C fallback） | 跳过（Ctrl+C fallback） |
-| 剪贴板读 | pbpaste | `powershell Get-Clipboard` | xclip -o / wl-paste |
-| 剪贴板写 | pbcopy | `powershell Set-Clipboard` | xclip / wl-copy |
-| 粘贴快捷键 | command+v | ctrl+v | ctrl+v |
-| 终端检测 | __CFBundleIdentifier | WT_SESSION / TERM_PROGRAM | TERM_PROGRAM |
-| 系统权限 | TCC check | 直接 granted | 检查 xdotool 安装 |
-
-### Linux 依赖工具
-
-| 工具 | 用途 | 安装命令（Ubuntu） |
-|------|------|-------------------|
-| `xdotool` | 键鼠模拟 + 窗口管理 | `sudo apt install xdotool` |
-| `scrot` 或 `gnome-screenshot` | 截图 | `sudo apt install scrot` |
-| `xrandr` | 显示器信息 | 通常已预装 |
-| `xclip` | 剪贴板 | `sudo apt install xclip` |
-| `wmctrl` | 窗口列表/切换 | `sudo apt install wmctrl` |
-
-Wayland 环境需要替代工具：`ydotool`（替代 xdotool）、`grim`（替代 scrot）、`wl-clipboard`（替代 xclip）。初期可先只支持 X11，Wayland 标记为 todo。
-
-## 工具参考
-
-### 通用工具（24 个）
 
 全平台可用。未绑定窗口时，操作对象是整个屏幕。
 
-#### 权限与会话
+### 权限与会话
 
 | 工具 | 参数 | 说明 |
 |------|------|------|
 | `request_access` | `apps[]`, `reason`, `clipboardRead?`, `clipboardWrite?`, `systemKeyCombos?` | 请求操作应用的权限。所有其他工具的前置条件 |
 | `list_granted_applications` | — | 列出当前会话已授权的应用 |
 
-#### 截图与显示
+### 截图与显示
 
 | 工具 | 参数 | 说明 |
 |------|------|------|
@@ -172,7 +31,7 @@ Wayland 环境需要替代工具：`ydotool`（替代 xdotool）、`grim`（替
 | `zoom` | `region: [x1,y1,x2,y2]` | 截取指定区域的高分辨率图片。坐标基于最近一次全屏截图 |
 | `switch_display` | `display` | 切换截图的目标显示器 |
 
-#### 鼠标操作
+### 鼠标操作
 
 | 工具 | 参数 | 说明 |
 |------|------|------|
@@ -187,7 +46,7 @@ Wayland 环境需要替代工具：`ydotool`（替代 xdotool）、`grim`（替
 | `left_mouse_up` | — | 松开左键 |
 | `cursor_position` | — | 获取当前鼠标位置 |
 
-#### 键盘操作
+### 键盘操作
 
 | 工具 | 参数 | 说明 |
 |------|------|------|
@@ -195,37 +54,39 @@ Wayland 环境需要替代工具：`ydotool`（替代 xdotool）、`grim`（替
 | `key` | `text` (如 "ctrl+s"), `repeat?` | 按键/组合键 |
 | `hold_key` | `text`, `duration` (秒) | 按住键指定时长 |
 
-#### 滚动
+### 滚动
 
 | 工具 | 参数 | 说明 |
 |------|------|------|
 | `scroll` | `coordinate`, `scroll_direction`, `scroll_amount` | 滚动。方向: up/down/left/right |
 
-#### 应用管理
+### 应用管理
 
 | 工具 | 参数 | 说明 |
 |------|------|------|
 | `open_application` | `app` | 打开应用。Windows 上自动绑定窗口 |
 
-#### 剪贴板
+### 剪贴板
 
 | 工具 | 参数 | 说明 |
 |------|------|------|
 | `read_clipboard` | — | 读取剪贴板文字 |
 | `write_clipboard` | `text` | 写入剪贴板 |
 
-#### 其他
+### 其他
 
 | 工具 | 参数 | 说明 |
 |------|------|------|
 | `wait` | `duration` (秒) | 等待 |
 | `computer_batch` | `actions[]` | 批量执行多个动作（减少 API 往返） |
 
-### Windows 专属工具（12 个）
+---
+
+## 二、Windows 专属工具（12 个）
 
 仅 Windows 平台可见。核心能力：**绑定窗口后的独立操作——不抢占用户鼠标键盘**。
 
-#### 工作模式
+### 工作模式
 
 ```
 ┌──────────────────────────────────────────────────┐
@@ -246,7 +107,7 @@ Wayland 环境需要替代工具：`ydotool`（替代 xdotool）、`grim`（替
 └──────────────────────────────────────────────────┘
 ```
 
-#### 窗口绑定
+### 窗口绑定
 
 | 工具 | 参数 | 说明 |
 |------|------|------|
@@ -261,7 +122,7 @@ Wayland 环境需要替代工具：`ydotool`（替代 xdotool）、`grim`（替
 | `unbind` | — | 解除绑定，恢复全屏模式 |
 | `status` | — | 查看当前绑定状态（hwnd、title、pid、窗口矩形） |
 
-#### 窗口管理
+### 窗口管理
 
 | 工具 | 参数 | 说明 |
 |------|------|------|
@@ -280,7 +141,7 @@ Wayland 环境需要替代工具：`ydotool`（替代 xdotool）、`grim`（替
 | `move_resize` | SetWindowPos — 移动/缩放到指定位置和大小 |
 | `get_rect` | GetWindowRect — 获取当前位置和大小 |
 
-#### 虚拟鼠标
+### 虚拟鼠标
 
 | 工具 | 参数 | 说明 |
 |------|------|------|
@@ -307,7 +168,7 @@ Wayland 环境需要替代工具：`ydotool`（替代 xdotool）、`grim`（替
 | 用户干扰 | 有 | **无** |
 | 适用场景 | 未绑定时 | **绑定后** |
 
-#### 虚拟键盘
+### 虚拟键盘
 
 | 工具 | 参数 | 说明 |
 |------|------|------|
@@ -333,14 +194,13 @@ Wayland 环境需要替代工具：`ydotool`（替代 xdotool）、`grim`（替
 
 **注意：** SendMessageW 对 Windows Terminal (ConPTY) 等现代应用无效。这些应用需要使用通用工具 + 窗口激活方式操作。
 
-#### 鼠标滚轮
+### 鼠标滚轮
 
 | 工具 | 参数 | 说明 |
 |------|------|------|
 | `mouse_wheel` | `coordinate: [x,y]`, `delta`, `direction?` | WM_MOUSEWHEEL 鼠标中键滚轮 |
 
 **参数说明：**
-
 - `delta`: 正值=向上，负值=向下。每 1 单位 ≈ 3 行
 - `direction`: "vertical"（默认）或 "horizontal"
 - `coordinate`: 滚轮作用点——决定哪个面板/区域接收滚动
@@ -350,11 +210,11 @@ Wayland 环境需要替代工具：`ydotool`（替代 xdotool）、`grim`（替
 | | `scroll` | `mouse_wheel` |
 |---|---|---|
 | 原理 | WM_VSCROLL/WM_HSCROLL | **WM_MOUSEWHEEL** |
-| Excel | 否 | 是 |
+| Excel | ❌ | ✅ |
-| 浏览器 | 否 | 是 |
+| 浏览器 | ❌ | ✅ |
-| 代码编辑器 | 否 | 是 |
+| 代码编辑器 | ❌ | ✅ |
 
-#### 元素级操作
+### 元素级操作
 
 | 工具 | 参数 | 说明 |
 |------|------|------|
@@ -362,18 +222,16 @@ Wayland 环境需要替代工具：`ydotool`（替代 xdotool）、`grim`（替
 | `type_into_element` | `name?`, `role?`, `automationId?`, `text` | 按名称向元素输入文字 |
 
 **工作原理：**
-
 1. 通过 UI Automation 在绑定窗口中查找匹配元素
 2. `click_element`: 先尝试 InvokePattern（按钮/菜单），失败则 SendMessage 点击 BoundingRect 中心
 3. `type_into_element`: 先尝试 ValuePattern 直接设值，失败则点击聚焦 + WM_CHAR 输入
 
 **适用场景：**
-
 - 截图中看到元素名称但坐标不精确时
 - Accessibility Snapshot 列出了元素的 name/automationId 时
 - 比坐标点击更可靠（不受窗口缩放/DPI 影响）
 
-#### 终端交互
+### 终端交互
 
 | 工具 | 参数 | 说明 |
 |------|------|------|
@@ -401,13 +259,15 @@ Wayland 环境需要替代工具：`ydotool`（替代 xdotool）、`grim`（替
 | `select` | ↑/↓ 箭头 × N + Enter | inquirer 选择菜单 |
 | `type` | 输入文字 + Enter | 文本输入提示 |
 
-#### 状态指示器
+### 状态指示器
 
 | 工具 | 参数 | 说明 |
 |------|------|------|
 | `status_indicator` | `action`: show/hide/status, `message?` | 控制绑定窗口底部的浮动状态标签 |
 
-### 教学工具（3 个）
+---
+
+## 三、教学工具（3 个）
 
 需要 `teachMode` 开启。
 
@@ -417,22 +277,80 @@ Wayland 环境需要替代工具：`ydotool`（替代 xdotool）、`grim`（替
 | `teach_step` | 显示一步引导提示，等用户点 Next |
 | `teach_batch` | 批量排队多步引导 |
 
-## 进阶
+---
 
-### 应用兼容性
+## 操作流程
+
+### 流程 1：全屏操作（未绑定）
+
+```
+request_access(apps=["Notepad"])
+open_application(app="Notepad")          ← 自动绑定窗口
+screenshot                               ← PrintWindow 截图 + GUI 元素列表
+left_click(coordinate=[500, 300])        ← 全局 SendInput
+type(text="hello world")                 ← 全局 SendInput
+key(text="ctrl+s")                       ← 全局 SendInput
+```
+
+### 流程 2：绑定窗口操作（推荐，不干扰用户）
+
+```
+request_access(apps=["Notepad"])
+bind_window(action="list")               ← 列出所有窗口
+bind_window(action="bind", title="记事本") ← 绑定 + 绿色边框 + 虚拟光标
+screenshot                               ← PrintWindow 截取绑定窗口
+virtual_mouse(action="click", coordinate=[500, 300])   ← SendMessageW，不动真实鼠标
+virtual_keyboard(action="type", text="hello world")    ← SendMessageW，不动物理键盘
+virtual_keyboard(action="combo", text="ctrl+s")        ← 保存
+mouse_wheel(coordinate=[500, 400], delta=-5)           ← 向下滚动
+bind_window(action="unbind")             ← 解除绑定
+```
+
+### 流程 3：按元素名称操作
+
+```
+bind_window(action="bind", title="记事本")
+screenshot                               ← 返回截图 + GUI elements 列表
+click_element(name="保存", role="Button") ← UI Automation 查找并点击
+type_into_element(role="Edit", text="new content")
+```
+
+### 流程 4：终端交互
+
+```
+bind_window(action="bind", title="PowerShell")
+screenshot
+prompt_respond(response_type="yes")      ← 回答 y + Enter
+prompt_respond(response_type="select", arrow_direction="down", arrow_count=2)  ← 选第3项
+```
+
+### 流程 5：Excel/浏览器滚动
+
+```
+bind_window(action="bind", title="Excel")
+screenshot
+mouse_wheel(coordinate=[600, 400], delta=-10)            ← 向下滚动 10 格
+mouse_wheel(coordinate=[600, 400], delta=5, direction="horizontal")  ← 向右滚动
+```
+
+---
+
+## 应用兼容性
 
 | 应用类型 | SendMessageW (virtual_*) | 元素操作 (click_element) | 注意 |
 |---------|--------------------------|------------------------|------|
-| 传统 Win32 (记事本/写字板) | 完美支持 | 完美支持 | 完美支持 |
+| 传统 Win32 (记事本/写字板) | ✅ | ✅ | 完美支持 |
-| Office (Excel/Word) | 支持（COM 自动化） | 支持 | 通过 COM API |
+| Office (Excel/Word) | ✅ (COM 自动化) | ✅ | 通过 COM API |
-| WPF 应用 | 支持 | 支持 | 标准 UIA 支持 |
+| WPF 应用 | ✅ | ✅ | 标准 UIA 支持 |
-| Electron/Chrome | 部分支持 | 部分支持 | 内部渲染不走 Win32 消息 |
+| Electron/Chrome | ⚠️ 部分 | ⚠️ 部分 | 内部渲染不走 Win32 消息 |
-| UWP/WinUI (Windows Terminal) | 不支持 | 不支持 | ConPTY 不接受 SendMessageW |
+| UWP/WinUI (Windows Terminal) | ❌ | ❌ | ConPTY 不接受 SendMessageW |
-| 浏览器网页内容 | 不支持 | 不支持 | 需要全局 SendInput |
+| 浏览器网页内容 | ❌ | ❌ | 需要全局 SendInput |
 
 **对于不支持 SendMessageW 的应用**，使用通用工具 (`left_click`/`type`/`key`) + `window_management(action="focus")` 先激活窗口。
 
-### 绑定窗口时的可视化
+---
+
+## 绑定窗口时的可视化
 
 绑定窗口后自动启动三层可视化：
 
@@ -440,7 +358,9 @@ Wayland 环境需要替代工具：`ydotool`（替代 xdotool）、`grim`（替
 2. **虚拟鼠标光标** — 红色箭头图标，跟随 virtual_mouse 操作移动，点击时闪烁
 3. **状态指示器** — 窗口底部浮动标签，显示当前操作（通过 status_indicator 控制）
 
-### Accessibility Snapshot
+---
+
+## Accessibility Snapshot
 
 每次 `screenshot` 时，如果窗口已绑定，会自动附带 GUI 元素列表：
 
@@ -454,32 +374,76 @@ GUI elements in this window:
 ```
 
 模型同时收到 **截图图片 + 结构化元素列表**，可以选择：
-
 - 用坐标操作：`virtual_mouse(action="click", coordinate=[120, 50])`
 - 用名称操作：`click_element(name="Save")`
 
-### UI Automation Control Patterns 参考
+---
+
+## UI Automation Control Patterns 参考
 
 `click_element` / `type_into_element` 底层使用 UI Automation Control Patterns。当前已实现的和可扩展的：
 
 | Pattern | 用途 | 当前状态 | 可用于 |
 |---------|------|---------|--------|
-| `InvokePattern` | 触发点击 | 已实现 (`click_element`) | 按钮、菜单项、链接 |
+| `InvokePattern` | 触发点击 | ✅ 已实现 (`click_element`) | 按钮、菜单项、链接 |
-| `ValuePattern` | 读写文本值 | 已实现 (`type_into_element`) | 文本框、组合框 |
+| `ValuePattern` | 读写文本值 | ✅ 已实现 (`type_into_element`) | 文本框、组合框 |
-| `TogglePattern` | 切换状态 | 未实现 | 复选框、开关 |
+| `TogglePattern` | 切换状态 | ❌ 未实现 | 复选框、开关 |
-| `SelectionPattern` | 选择项目 | 未实现 | 下拉菜单、列表 |
+| `SelectionPattern` | 选择项目 | ❌ 未实现 | 下拉菜单、列表 |
-| `ScrollPattern` | 编程滚动 | 未实现（用 `mouse_wheel` 替代） | 列表、树、面板 |
+| `ScrollPattern` | 编程滚动 | ❌ 未实现（用 `mouse_wheel` 替代） | 列表、树、面板 |
-| `ExpandCollapsePattern` | 展开/折叠 | 未实现 | 树节点、折叠面板 |
+| `ExpandCollapsePattern` | 展开/折叠 | ❌ 未实现 | 树节点、折叠面板 |
-| `WindowPattern` | 窗口操作 | 未实现（用 `window_management` 替代） | 窗口最大化/关闭 |
+| `WindowPattern` | 窗口操作 | ❌ 未实现（用 `window_management` 替代） | 窗口最大化/关闭 |
-| `TextPattern` | 读取文档文本 | 未实现 | 文档、富文本 |
+| `TextPattern` | 读取文档文本 | ❌ 未实现 | 文档、富文本 |
-| `GridPattern` | 表格操作 | 未实现 | Excel 单元格、数据网格 |
+| `GridPattern` | 表格操作 | ❌ 未实现 | Excel 单元格、数据网格 |
-| `TablePattern` | 表格结构 | 未实现 | 表头、行列关系 |
+| `TablePattern` | 表格结构 | ❌ 未实现 | 表头、行列关系 |
-| `RangeValuePattern` | 范围值操作 | 未实现 | 滑块、进度条 |
+| `RangeValuePattern` | 范围值操作 | ❌ 未实现 | 滑块、进度条 |
-| `TransformPattern` | 移动/缩放 | 未实现 | 可拖拽元素 |
+| `TransformPattern` | 移动/缩放 | ❌ 未实现 | 可拖拽元素 |
 
 **扩展路线：** 优先实现 `TogglePattern`（复选框）和 `SelectionPattern`（下拉菜单），这两个在表单自动化中最常用。
 
-### 输入方式技术矩阵
+---
+
+## 屏幕截取技术方案对比
+
+当前使用 Python Bridge (mss) 进行截图，底层是 GDI BitBlt。三种方案对比：
+
+| 方案 | API | 当前状态 | 性能 | 优势 | 限制 |
+|------|-----|---------|------|------|------|
+| **GDI BitBlt** | `BitBlt` / `PrintWindow` | ✅ 当前使用 (mss/bridge.py) | ~300ms | 简单稳定，支持后台窗口 (PrintWindow) | 不支持硬件加速内容、DPI 处理复杂 |
+| **DXGI Desktop Duplication** | `IDXGIOutputDuplication` | ❌ 未实现 | ~16ms (60fps) | 硬件加速，支持 HDR，GPU 直接读取 | 不支持单窗口截取，需 D3D11 |
+| **Windows.Graphics.Capture** | `GraphicsCaptureItem` | ❌ 未实现 | ~16ms | 最新 API，支持单窗口/单显示器，系统级权限管理 | Win10 1903+，首次需用户确认 |
+
+### 推荐升级路径
+
+```
+当前: GDI BitBlt (mss) ─── 全屏 ~300ms, 窗口 ~300ms (PrintWindow)
+  │
+  ├─ 近期: DXGI Desktop Duplication ─── 全屏 ~16ms, 但不支持单窗口
+  │
+  └─ 远期: Windows.Graphics.Capture ─── 全屏 + 单窗口都 ~16ms
+```
+
+### DXGI Desktop Duplication 实现要点
+
+```python
+# bridge.py 中可添加 DXGI 截图（通过 d3dshot 或 dxcam 库）
+import dxcam  # pip install dxcam
+
+camera = dxcam.create()
+frame = camera.grab()  # numpy array, ~5ms
+# 转为 JPEG base64 发送
+```
+
+### Windows.Graphics.Capture 实现要点
+
+```python
+# 需要 WinRT Python 绑定
+# pip install winrt-Windows.Graphics.Capture winrt-Windows.Graphics.DirectX
+# 限制：首次调用需要用户在系统弹窗中确认权限
+```
+
+---
+
+## 输入方式技术矩阵
 
 不同应用类型需要不同的输入方式：
 
@@ -492,7 +456,7 @@ GUI elements in this window:
 | **COM Automation** | Excel/Word COM | 完全编程控制 | 仅 Office 应用 | Excel / Word |
 | **剪贴板 + 粘贴** | `SetClipboardData` + `Ctrl+V` | 绕过输入限制 | 会覆盖用户剪贴板 | 通用后备 |
 
-**按应用类型的推荐输入策略：**
+### 按应用类型的推荐输入策略
 
 | 应用类型 | 首选 | 后备 | 说明 |
 |---------|------|------|------|
@@ -503,46 +467,9 @@ GUI elements in this window:
 | Windows Terminal (ConPTY) | SendInput (需前台) | 剪贴板粘贴 | ConPTY 不接受外部消息 |
 | UWP/WinUI 应用 | SendInput (需前台) | UIA | XAML 渲染不走 Win32 消息 |
 
-### 屏幕截取技术方案对比
+---
 
-当前使用 Python Bridge (mss) 进行截图，底层是 GDI BitBlt。三种方案对比：
+## 已知限制与待解决
-
-| 方案 | API | 当前状态 | 性能 | 优势 | 限制 |
-|------|-----|---------|------|------|------|
-| **GDI BitBlt** | `BitBlt` / `PrintWindow` | 当前使用 (mss/bridge.py) | ~300ms | 简单稳定，支持后台窗口 (PrintWindow) | 不支持硬件加速内容、DPI 处理复杂 |
-| **DXGI Desktop Duplication** | `IDXGIOutputDuplication` | 未实现 | ~16ms (60fps) | 硬件加速，支持 HDR，GPU 直接读取 | 不支持单窗口截取，需 D3D11 |
-| **Windows.Graphics.Capture** | `GraphicsCaptureItem` | 未实现 | ~16ms | 最新 API，支持单窗口/单显示器，系统级权限管理 | Win10 1903+，首次需用户确认 |
-
-**推荐升级路径：**
-
-```
-当前: GDI BitBlt (mss) ─── 全屏 ~300ms, 窗口 ~300ms (PrintWindow)
-  │
-  ├─ 近期: DXGI Desktop Duplication ─── 全屏 ~16ms, 但不支持单窗口
-  │
-  └─ 远期: Windows.Graphics.Capture ─── 全屏 + 单窗口都 ~16ms
-```
-
-**DXGI Desktop Duplication 实现要点：**
-
-```python
-# bridge.py 中可添加 DXGI 截图（通过 d3dshot 或 dxcam 库）
-import dxcam  # pip install dxcam
-
-camera = dxcam.create()
-frame = camera.grab()  # numpy array, ~5ms
-# 转为 JPEG base64 发送
-```
-
-**Windows.Graphics.Capture 实现要点：**
-
-```python
-# 需要 WinRT Python 绑定
-# pip install winrt-Windows.Graphics.Capture winrt-Windows.Graphics.DirectX
-# 限制：首次调用需要用户在系统弹窗中确认权限
-```
-
-### 已知限制与待解决
 
 | 限制 | 影响 | 计划 |
 |------|------|------|
@@ -552,70 +479,29 @@ frame = camera.grab()  # numpy array, ~5ms
 | DWM 边框对自定义标题栏应用可能无效 | 某些 Electron 应用看不到边框 | 检测并回退到叠加窗口方案 |
 | 虚拟光标是 PowerShell WinForms 进程 | 启动慢 (~1s)，资源占用 | 考虑用 Win32 原生窗口替代 |
 
-### 技术路线图
+---
 
-#### Phase 1（当前）— 基础功能
+## 技术路线图
 
-- SendMessageW 虚拟输入
+### Phase 1（当前）— 基础功能
-- PrintWindow/mss 截图
+- ✅ SendMessageW 虚拟输入
-- UI Automation (InvokePattern + ValuePattern)
+- ✅ PrintWindow/mss 截图
-- Accessibility Snapshot
+- ✅ UI Automation (InvokePattern + ValuePattern)
-- DWM 边框指示
+- ✅ Accessibility Snapshot
-- Python Bridge
+- ✅ DWM 边框指示
+- ✅ Python Bridge
 
-#### Phase 2（近期）— 兼容性增强
+### Phase 2（近期）— 兼容性增强
+- ⬜ 应用类型自动检测（Win32 vs Terminal vs UWP）
+- ⬜ 终端类应用自动切换 SendInput + 短暂激活
+- ⬜ TogglePattern / SelectionPattern 支持
+- ⬜ DXGI Desktop Duplication 高速截图
+- ⬜ Accessibility Snapshot 超时保护
 
-- 应用类型自动检测（Win32 vs Terminal vs UWP）
+### Phase 3（远期）— 高级能力
-- 终端类应用自动切换 SendInput + 短暂激活
+- ⬜ Windows.Graphics.Capture（单窗口实时截图）
-- TogglePattern / SelectionPattern 支持
+- ⬜ 截图元素标注（在截图上标记 ID 数字）
-- DXGI Desktop Duplication 高速截图
+- ⬜ 浏览器 DOM 提取（绑定浏览器时提取网页结构）
-- Accessibility Snapshot 超时保护
+- ⬜ GridPattern / TablePattern（Excel 单元格级操作）
-
+- ⬜ TextPattern（文档内容读取）
-#### Phase 3（远期）— 高级能力
+- ⬜ 多窗口协同操作
-
-- Windows.Graphics.Capture（单窗口实时截图）
-- 截图元素标注（在截图上标记 ID 数字）
-- 浏览器 DOM 提取（绑定浏览器时提取网页结构）
-- GridPattern / TablePattern（Excel 单元格级操作）
-- TextPattern（文档内容读取）
-- 多窗口协同操作
-
-## 配置
-
-### Feature Flag
-
-Computer Use 入口由 `CHICAGO_MCP` feature flag 控制。
-
-- **Dev mode**：默认启用（`scripts/dev.ts` 全部启用）
-- **Build mode**：默认启用（在 `DEFAULT_BUILD_FEATURES` 列表中）
-- **运行时**：通过环境变量 `FEATURE_CHICAGO_MCP=1` 启用
-
-入口位置：`src/main.tsx` 中 `feature("CHICAGO_MCP")` 门控，初始化 Computer Use MCP server。
-
-### 跨平台架构要点
-
-各平台由 dispatcher + backend 模式分发：
-
-| 层 | macOS | Windows | Linux |
-|----|-------|---------|-------|
-| `computer-use-input/backends/` | darwin.ts | win32.ts | linux.ts |
-| `computer-use-swift/backends/` | darwin.ts | win32.ts | linux.ts |
-| `src/utils/computerUse/executor.ts` | darwin 路径 | 跨平台 executor | 跨平台 executor |
-| `src/utils/computerUse/swiftLoader.ts` | darwin 加载 | platforms/ | platforms/ |
-
-非 darwin 平台的关键差异：
-
-- `drainRunLoop.ts` — 非 darwin 无需 CFRunLoop pump（直接执行 fn）
-- `escHotkey.ts` — 非 darwin 返回 false（已有 Ctrl+C fallback）
-- `hostAdapter.ts` — 非 darwin 权限检查逻辑：Windows 直接 granted，Linux 检查 xdotool 安装
-- `common.ts` — 平台标识按 `process.platform` 动态分发：darwin→'native'，其他→'none'
-- `gates.ts` — `hasRequiredSubscription()` 已按平台更新默认值
-
-### 新增 Linux 后端的要点
-
-| 步骤 | 文件 | 内容 |
-|------|------|------|
-| 1 | `packages/@ant/computer-use-input/src/backends/linux.ts` | xdotool 键鼠（mousemove/click/key/type/getactivewindow） |
-| 2 | `packages/@ant/computer-use-swift/src/backends/linux.ts` | scrot/grim 截图 + xrandr 显示器 + wmctrl 窗口管理 |
-| 3 | `packages/@ant/computer-use-input/src/index.ts` | dispatcher 加 `case 'linux'` |
-| 4 | `packages/@ant/computer-use-swift/src/index.ts` | dispatcher 加 `case 'linux'` |

docs/features/computer-use-windows-enhancement.md

@@ -0,0 +1,315 @@
+# Computer Use Windows 增强实施计划
+
+更新时间：2026-04-03
+依赖文档：`docs/features/windows-ai-desktop-control.md`、`docs/features/computer-use.md`
+
+## 1. 目标
+
+在已有的 PowerShell 子进程方案基础上，利用 Windows 原生 API 增强 Computer Use 的 Windows 实现，解决 3 个核心问题：
+
+1. **窗口绑定截图**：当前 `CopyFromScreen` 只能全屏截图，无法对指定窗口截图（尤其是被遮挡/最小化窗口）
+2. **UI 结构感知**：当前只能通过坐标点击，无法像 macOS Accessibility 那样理解 UI 元素树
+3. **性能**：每次 PowerShell 启动约 273ms，剪贴板/窗口枚举等高频操作需要更快的方式
+
+## 2. 已验证的 Windows API 能力
+
+以下 API 全部通过 PowerShell P/Invoke 实测通过：
+
+| 能力 | API | 验证结果 |
+|------|-----|---------|
+| 窗口绑定截图 | `PrintWindow(hwnd, hdc, PW_RENDERFULLCONTENT)` | ✅ VS Code 342KB, Chrome 273KB |
+| 枚举窗口+HWND | `EnumWindows` + `GetWindowText` + `GetWindowThreadProcessId` | ✅ 38 个窗口，含 HWND/PID/标题 |
+| UI 元素树 | `System.Windows.Automation.AutomationElement` | ✅ 记事本 39 个元素 |
+| UI 写值 | `ValuePattern.SetValue()` | ✅ 成功写入记事本文本 |
+| UI 点击 | `InvokePattern.Invoke()` | ✅ 按钮可程序化点击 |
+| 坐标元素识别 | `AutomationElement.FromPoint(x, y)` | ✅ 返回元素类型+名称 |
+| OCR | `Windows.Media.Ocr.OcrEngine` | ✅ 英语+中文引擎可用 |
+| 全局热键 | `RegisterHotKey` | ✅ API 可调 |
+| 剪贴板直接操作 | `System.Windows.Forms.Clipboard` | ✅ 读/写/图片检测 |
+| Shell 启动 | `ShellExecute` | ✅ 打开文件/URL/应用 |
+
+## 3. 架构设计
+
+### 3.1 文件结构
+
+在现有 `backends/win32.ts` 基础上新增 Windows 专属模块：
+
+```
+packages/@ant/computer-use-input/src/
+├── backends/
+│   ├── darwin.ts          ← 不动
+│   ├── win32.ts           ← 增强：直接 Win32 API 替代部分 PowerShell
+│   └── linux.ts           ← 不动
+
+packages/@ant/computer-use-swift/src/
+├── backends/
+│   ├── darwin.ts          ← 不动
+│   ├── win32.ts           ← 增强：PrintWindow 窗口截图 + EnumWindows
+│   └── linux.ts           ← 不动
+
+packages/@ant/computer-use-mcp/src/
+│   └── tools.ts           ← 增加 Windows 专属工具定义（UI Automation、OCR）
+
+src/utils/computerUse/
+│   └── win32/              ← 新增目录：Windows 专属能力
+│       ├── uiAutomation.ts  ← UI 元素树、点击、写值
+│       ├── ocr.ts           ← 截图 + OCR 文字识别
+│       ├── windowCapture.ts ← PrintWindow 窗口绑定截图
+│       └── windowEnum.ts    ← EnumWindows 窗口枚举
+```
+
+### 3.2 分层
+
+```
+┌──────────────────────────────────────────────┐
+│           Computer Use MCP Tools             │
+│  screenshot / click / type / request_access  │
+│  + Windows 专属: ui_tree / ocr / window_cap  │
+├──────────────────────────────────────────────┤
+│           src/utils/computerUse/             │
+│  executor.ts → 按平台 dispatch               │
+│  win32/ → Windows 专属能力模块               │
+├──────────────────────────────────────────────┤
+│     packages/@ant/computer-use-{input,swift}  │
+│  backends/win32.ts → PowerShell + Win32 API  │
+├──────────────────────────────────────────────┤
+│           Windows Native API                 │
+│  PrintWindow / EnumWindows / UI Automation   │
+│  SendInput / Clipboard / OCR / ShellExecute  │
+└──────────────────────────────────────────────┘
+```
+
+## 4. 实施计划
+
+### Phase A：窗口绑定截图（解决核心问题）
+
+**问题**：当前 `CopyFromScreen` 只能全屏截图，无法对指定窗口截图。
+**方案**：用 `PrintWindow` + `FindWindow` 实现窗口级截图。
+
+| 步骤 | 文件 | 改动 |
+|------|------|------|
+| A.1 | `src/utils/computerUse/win32/windowCapture.ts` | 新建：`captureWindow(title)` 用 PrintWindow 截取指定窗口 |
+| A.2 | `src/utils/computerUse/win32/windowEnum.ts` | 新建：`listWindows()` 用 EnumWindows 返回 {hwnd, pid, title}[] |
+| A.3 | `packages/@ant/computer-use-swift/src/backends/win32.ts` | `screenshot.captureExcluding` 增加按窗口截图能力 |
+| A.4 | `packages/@ant/computer-use-swift/src/backends/win32.ts` | `apps.listRunning` 用 EnumWindows 替代 Get-Process（返回 HWND） |
+
+**PowerShell 脚本核心**：
+
+```powershell
+# PrintWindow 截取指定窗口
+Add-Type -AssemblyName System.Drawing
+Add-Type -ReferencedAssemblies System.Drawing @'
+using System; using System.Runtime.InteropServices; using System.Drawing; using System.Drawing.Imaging;
+public class WinCap {
+    [DllImport("user32.dll", CharSet=CharSet.Unicode)]
+    public static extern IntPtr FindWindow(string c, string t);
+    [DllImport("user32.dll")]
+    public static extern bool GetWindowRect(IntPtr h, out RECT r);
+    [DllImport("user32.dll")]
+    public static extern bool PrintWindow(IntPtr h, IntPtr hdc, uint f);
+    [StructLayout(LayoutKind.Sequential)]
+    public struct RECT { public int L, T, R, B; }
+    // ... CaptureByTitle(string title) → base64
+}
+'@
+```
+
+**验证标准**：
+- 能按窗口标题截图
+- 被遮挡的窗口也能截图
+- 返回 base64 + width + height
+
+### Phase B：UI Automation（Windows 专属新能力）
+
+**问题**：macOS 有 Accessibility API 可以读取/操作 UI 元素，Windows 当前只能坐标点击。
+**方案**：用 `System.Windows.Automation` 实现 UI 树读取和元素操作。
+
+| 步骤 | 文件 | 改动 |
+|------|------|------|
+| B.1 | `src/utils/computerUse/win32/uiAutomation.ts` | 新建：核心 UIA 操作封装 |
+| B.2 | `packages/@ant/computer-use-mcp/src/tools.ts` | 增加 Windows 专属工具定义 |
+
+**uiAutomation.ts 导出函数**：
+
+```typescript
+// 获取窗口的 UI 元素树
+getUITree(windowTitle: string, depth: number): UIElement[]
+
+// 按名称/类型/AutomationId 查找元素
+findElement(windowTitle: string, query: {name?, controlType?, automationId?}): UIElement | null
+
+// 点击元素（InvokePattern）
+clickElement(windowTitle: string, automationId: string): boolean
+
+// 设置元素值（ValuePattern）
+setValue(windowTitle: string, automationId: string, value: string): boolean
+
+// 获取坐标处的元素
+elementAtPoint(x: number, y: number): UIElement | null
+```
+
+**UIElement 类型**：
+```typescript
+interface UIElement {
+  name: string
+  controlType: string    // Button, Edit, Text, List, etc.
+  automationId: string
+  boundingRect: { x: number, y: number, w: number, h: number }
+  isEnabled: boolean
+  value?: string         // ValuePattern 可用时
+  children?: UIElement[]
+}
+```
+
+**PowerShell 脚本核心**：
+```powershell
+Add-Type -AssemblyName UIAutomationClient
+Add-Type -AssemblyName UIAutomationTypes
+
+# 读取 UI 树
+$root = [AutomationElement]::RootElement
+$window = $root.FindFirst([TreeScope]::Children, 
+  [PropertyCondition]::new([AutomationElement]::NameProperty, $title))
+$elements = $window.FindAll([TreeScope]::Descendants, [Condition]::TrueCondition)
+
+# 写入文本
+$element.GetCurrentPattern([ValuePattern]::Pattern).SetValue($text)
+
+# 点击按钮
+$element.GetCurrentPattern([InvokePattern]::Pattern).Invoke()
+```
+
+**验证标准**：
+- 能读取记事本的 UI 树（按钮、文本框、菜单）
+- 能向文本框写入内容
+- 能点击按钮
+- 能识别坐标处的元素
+
+### Phase C：OCR 屏幕文字识别
+
+**问题**：截图后 AI 只能看到图片，无法直接读取文字。
+**方案**：用 `Windows.Media.Ocr` 对截图进行文字识别。
+
+| 步骤 | 文件 | 改动 |
+|------|------|------|
+| C.1 | `src/utils/computerUse/win32/ocr.ts` | 新建：截图 + OCR 识别 |
+| C.2 | `packages/@ant/computer-use-mcp/src/tools.ts` | 增加 `screen_ocr` 工具定义 |
+
+**ocr.ts 导出函数**：
+```typescript
+// 对屏幕区域 OCR
+ocrRegion(x: number, y: number, w: number, h: number, lang?: string): OcrResult
+
+// 对指定窗口 OCR
+ocrWindow(windowTitle: string, lang?: string): OcrResult
+
+interface OcrResult {
+  text: string
+  lines: { text: string, bounds: {x,y,w,h} }[]
+  language: string
+}
+```
+
+**已确认可用语言**：英语 (en-US) + 中文 (zh-Hans-CN)
+
+**验证标准**：
+- 能识别屏幕区域中的英文和中文
+- 返回文字内容 + 每行的位置信息
+
+### Phase D：高频操作性能优化
+
+**问题**：每次 PowerShell 启动 273ms，鼠标移动等高频操作太慢。
+**方案**：用 .NET `System.Windows.Forms.Clipboard` 等直接 API 替代 PowerShell 子进程。
+
+| 步骤 | 文件 | 改动 |
+|------|------|------|
+| D.1 | `src/utils/computerUse/executor.ts` | 剪贴板操作用直接 API 替代 PowerShell |
+| D.2 | 考虑驻留 PowerShell 进程 | 通过 stdin/stdout 交互，摊平启动成本 |
+
+**剪贴板直接 API**（不需要 PowerShell 子进程）：
+```powershell
+# 读：50ms → <1ms
+[System.Windows.Forms.Clipboard]::GetText()
+
+# 写：50ms → <1ms  
+[System.Windows.Forms.Clipboard]::SetText($text)
+
+# 图片检测
+[System.Windows.Forms.Clipboard]::ContainsImage()
+```
+
+### Phase E：`request_access` Windows 适配
+
+**问题**：`request_access` 依赖 macOS bundleId 识别应用，Windows 没有这个概念。
+**方案**：在 Windows 上用 exe 路径 + 窗口标题替代 bundleId。
+
+| 步骤 | 文件 | 改动 |
+|------|------|------|
+| E.1 | `packages/@ant/computer-use-mcp/src/toolCalls.ts` | `resolveRequestedApps` 在 Windows 上用 exe 路径匹配 |
+| E.2 | `packages/@ant/computer-use-mcp/src/sentinelApps.ts` | 增加 Windows 危险应用列表（cmd.exe, powershell.exe 等） |
+| E.3 | `packages/@ant/computer-use-mcp/src/deniedApps.ts` | 增加 Windows 浏览器/终端识别规则 |
+| E.4 | `src/utils/computerUse/hostAdapter.ts` | `ensureOsPermissions` Windows 上检查 UAC 状态 |
+
+**Windows 应用标识映射**：
+```
+macOS bundleId          →  Windows 等价
+com.apple.Safari        →  C:\Program Files\...\msedge.exe（或窗口标题匹配）
+com.google.Chrome       →  chrome.exe
+com.apple.Terminal      →  WindowsTerminal.exe / cmd.exe
+```
+
+### Phase F：全局热键（ESC 拦截）
+
+**问题**：当前非 darwin 直接跳过 ESC 热键，用 Ctrl+C 替代。
+**方案**：用 `RegisterHotKey` 或 `SetWindowsHookEx(WH_KEYBOARD_LL)` 实现。
+
+| 步骤 | 文件 | 改动 |
+|------|------|------|
+| F.1 | `src/utils/computerUse/escHotkey.ts` | Windows 分支：RegisterHotKey 注册 ESC |
+
+**优先级低**——当前 Ctrl+C fallback 可用，ESC 热键是体验优化。
+
+## 5. 执行优先级
+
+```
+Phase A: 窗口绑定截图          ← P0 核心需求，解决"操作其他界面"
+Phase B: UI Automation         ← P0 核心能力，AI 理解 UI 结构
+Phase C: OCR                   ← P1 增值能力，AI 读屏幕文字
+Phase D: 性能优化              ← P1 体验优化，高频操作提速
+Phase E: request_access 适配   ← P1 功能完整性，权限模型适配
+Phase F: ESC 热键              ← P2 体验优化，可后做
+```
+
+## 6. 每个 Phase 的改动量估算
+
+| Phase | 新增文件 | 修改文件 | 新增代码行 | 风险 |
+|-------|---------|---------|-----------|------|
+| A 窗口截图 | 2 | 1 | ~200 | 低 |
+| B UI Automation | 1 | 1 | ~300 | 中 |
+| C OCR | 1 | 1 | ~150 | 低 |
+| D 性能优化 | 0 | 2 | ~50 | 低 |
+| E request_access | 0 | 3 | ~100 | 中 |
+| F ESC 热键 | 0 | 1 | ~50 | 低 |
+| **总计** | **4** | **9** | **~850** | — |
+
+## 7. 不动的文件
+
+- `backends/darwin.ts`（两个包都不动）
+- `backends/linux.ts`（两个包都不动）
+- `src/utils/computerUse/` 中 macOS 相关代码路径不动
+- `packages/@ant/computer-use-mcp/src/` 中已复制的参考项目代码不动（只追加 Windows 工具）
+
+## 8. 与 macOS/Linux 方案的对比
+
+| 能力 | macOS | Windows (增强后) | Linux |
+|------|-------|-----------------|-------|
+| 截图方式 | SCContentFilter (per-app) | **PrintWindow (per-window)** | scrot (全屏/区域) |
+| UI 结构 | Accessibility API | **UI Automation** | 无 |
+| OCR | 无内置 | **Windows.Media.Ocr** | 无内置 |
+| 键鼠 | CGEvent + enigo | SendInput + keybd_event | xdotool |
+| 窗口管理 | NSWorkspace | **EnumWindows + Win32** | wmctrl |
+| 剪贴板 | pbcopy/pbpaste | **Clipboard 直接 API** | xclip |
+| ESC 热键 | CGEventTap | RegisterHotKey | 无 |
+| 应用标识 | bundleId | exe 路径 + 窗口标题 | /proc + wmctrl |
+
+**Windows 增强后将在 UI Automation 和 OCR 方面超过 macOS 方案**——这两项 macOS 原始实现也没有（Anthropic 用的是截图 + Claude 视觉理解，没有结构化 UI 数据）。

docs/features/computer-use.md

@@ -0,0 +1,197 @@
+# Computer Use — macOS / Windows / Linux 跨平台实施计划
+
+更新时间：2026-04-03
+参考项目：`E:\源码\claude-code-source-main\claude-code-source-main`
+
+## 1. 现状
+
+参考项目的 Computer Use **仅支持 macOS**——从入口到底层全部写死 darwin。我们的项目在 Phase 1-3 中已经完成了：
+
+- ✅ `@ant/computer-use-mcp` stub 替换为完整实现（12 文件）
+- ✅ `@ant/computer-use-input` 拆为 dispatcher + backends（darwin + win32）
+- ✅ `@ant/computer-use-swift` 拆为 dispatcher + backends（darwin + win32）
+- ✅ `CHICAGO_MCP` 编译开关已开
+- ✅ `src/` 层 macOS 硬编码已移除（Phase 2 已完成）
+
+## 2. 阻塞点全景
+
+### 2.1 入口层
+
+| # | 文件:行号 | 阻塞代码 | 影响 |
+|---|----------|---------|------|
+| 1 | `src/main.tsx:2366` | `feature("CHICAGO_MCP")` 门控 | CU 初始化入口 |
+
+### 2.2 加载层
+
+| # | 文件:行号 | 阻塞代码 | 影响 |
+|---|----------|---------|------|
+| 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: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 后端
+
+| 包 | macOS | Windows | Linux |
+|---|-------|---------|-------|
+| `computer-use-input/backends/` | ✅ darwin.ts | ✅ win32.ts | ❌ 需新建 linux.ts |
+| `computer-use-swift/backends/` | ✅ darwin.ts | ✅ win32.ts | ❌ 需新建 linux.ts |
+
+## 3. 每个平台的能力依赖
+
+### 3.1 computer-use-input（键鼠）
+
+| 功能 | macOS | Windows | Linux |
+|------|-------|---------|-------|
+| 鼠标移动 | CGEvent JXA | SetCursorPos P/Invoke | xdotool mousemove |
+| 鼠标点击 | CGEvent JXA | SendInput P/Invoke | xdotool click |
+| 鼠标滚轮 | CGEvent JXA | SendInput MOUSEEVENTF_WHEEL | xdotool scroll |
+| 键盘按键 | System Events osascript | keybd_event P/Invoke | xdotool key |
+| 组合键 | System Events osascript | keybd_event 组合 | xdotool key combo |
+| 文本输入 | System Events keystroke | SendKeys.SendWait | xdotool type |
+| 前台应用 | System Events osascript | GetForegroundWindow P/Invoke | xdotool getactivewindow + /proc |
+| 工具依赖 | osascript（内置） | powershell（内置） | xdotool（需安装） |
+
+### 3.2 computer-use-swift（截图 + 应用管理）
+
+| 功能 | macOS | Windows | Linux |
+|------|-------|---------|-------|
+| 全屏截图 | screencapture | CopyFromScreen | gnome-screenshot / scrot / grim |
+| 区域截图 | screencapture -R | CopyFromScreen(rect) | gnome-screenshot -a / scrot -a / grim -g |
+| 显示器列表 | CGGetActiveDisplayList JXA | Screen.AllScreens | xrandr --query |
+| 运行中应用 | System Events JXA | Get-Process | wmctrl -l / ps |
+| 打开应用 | osascript activate | Start-Process | xdg-open / gtk-launch |
+| 隐藏/显示 | System Events visibility | ShowWindow/SetForegroundWindow | wmctrl -c / xdotool |
+| 工具依赖 | screencapture + osascript | powershell | xdotool + scrot/grim + wmctrl |
+
+### 3.3 executor 层
+
+| 功能 | macOS | Windows | Linux |
+|------|-------|---------|-------|
+| drainRunLoop | CFRunLoop pump | 不需要 | 不需要 |
+| ESC 热键 | CGEventTap | 跳过（Ctrl+C fallback） | 跳过（Ctrl+C fallback） |
+| 剪贴板读 | pbpaste | `powershell Get-Clipboard` | xclip -o / wl-paste |
+| 剪贴板写 | pbcopy | `powershell Set-Clipboard` | xclip / wl-copy |
+| 粘贴快捷键 | command+v | ctrl+v | ctrl+v |
+| 终端检测 | __CFBundleIdentifier | WT_SESSION / TERM_PROGRAM | TERM_PROGRAM |
+| 系统权限 | TCC check | 直接 granted | 检查 xdotool 安装 |
+
+## 4. 执行步骤
+
+### Phase 1：已完成 ✅
+
+- [x] `@ant/computer-use-mcp` stub → 完整实现
+- [x] `@ant/computer-use-input` dispatcher + darwin/win32 backends
+- [x] `@ant/computer-use-swift` dispatcher + darwin/win32 backends
+- [x] `CHICAGO_MCP` 编译开关
+
+### Phase 2：移除 6 处 macOS 硬编码（解锁 macOS + Windows）
+
+**改动原则：macOS 代码路径不变，只在每处 darwin 守卫后加 win32/linux 分支。**
+
+| 步骤 | 文件 | 改动 |
+|------|------|------|
+| 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 后端
+
+| 步骤 | 文件 | 内容 |
+|------|------|------|
+| 3.1 | `packages/@ant/computer-use-input/src/backends/linux.ts` | xdotool 键鼠（mousemove/click/key/type/getactivewindow） |
+| 3.2 | `packages/@ant/computer-use-swift/src/backends/linux.ts` | scrot/grim 截图 + xrandr 显示器 + wmctrl 窗口管理 |
+| 3.3 | `packages/@ant/computer-use-input/src/index.ts` | dispatcher 加 `case 'linux'` |
+| 3.4 | `packages/@ant/computer-use-swift/src/index.ts` | dispatcher 加 `case 'linux'` |
+
+### Phase 4：验证
+
+| 测试项 | macOS | Windows | Linux |
+|--------|-------|---------|-------|
+| build 成功 | ✅ | 验证 | 验证 |
+| MCP 工具列表非空 | 验证 | 验证 | 验证 |
+| 鼠标移动 | 验证 | ✅ 已通过 | 验证 |
+| 截图 | 验证 | ✅ 已通过 | 验证 |
+| 键盘输入 | 验证 | 验证 | 验证 |
+| 前台窗口 | 验证 | ✅ 已通过 | 验证 |
+| 剪贴板 | 验证 | 验证 | 验证 |
+
+## 5. 文件改动总览
+
+### 不动的文件（14 个）
+
+`cleanup.ts`、`computerUseLock.ts`、`wrapper.tsx`、`toolRendering.tsx`、`mcpServer.ts`、`setup.ts`、`appNames.ts`、`inputLoader.ts`、`src/services/mcp/client.ts`、`@ant/computer-use-mcp/src/*`（Phase 1 已完成）、`backends/darwin.ts`（两个包都不动）
+
+### 改 src/ 的文件（8 个）
+
+| 文件 | 改动量 | 风险 |
+|------|--------|------|
+| `main.tsx` | 1 行 | 低 |
+| `swiftLoader.ts` | 2 行 | 低 |
+| `executor.ts` | ~40 行（剪贴板分发 + 平台守卫 + paste 快捷键） | **中** |
+| `drainRunLoop.ts` | 1 行 | 低 |
+| `escHotkey.ts` | 3 行 | 低 |
+| `hostAdapter.ts` | 5 行 | 低 |
+| `common.ts` | 3 行 | 低 |
+| `gates.ts` | 3 行 | 低 |
+
+### 新增文件（2 个）
+
+| 文件 | 行数估算 |
+|------|---------|
+| `packages/@ant/computer-use-input/src/backends/linux.ts` | ~150 行 |
+| `packages/@ant/computer-use-swift/src/backends/linux.ts` | ~200 行 |
+
+## 6. Linux 依赖工具
+
+| 工具 | 用途 | 安装命令（Ubuntu） |
+|------|------|-------------------|
+| `xdotool` | 键鼠模拟 + 窗口管理 | `sudo apt install xdotool` |
+| `scrot` 或 `gnome-screenshot` | 截图 | `sudo apt install scrot` |
+| `xrandr` | 显示器信息 | 通常已预装 |
+| `xclip` | 剪贴板 | `sudo apt install xclip` |
+| `wmctrl` | 窗口列表/切换 | `sudo apt install wmctrl` |
+
+Wayland 环境需要替代工具：`ydotool`（替代 xdotool）、`grim`（替代 scrot）、`wl-clipboard`（替代 xclip）。初期可先只支持 X11，Wayland 标记为 todo。
+
+## 7. 执行顺序建议
+
+```
+Phase 2（解锁 macOS + Windows）
+  ├── 2.1-2.3  移除 3 处硬编码 throw/skip
+  ├── 2.4-2.5  剪贴板 + 粘贴快捷键平台分发
+  ├── 2.6      swiftLoader → 直接实例化
+  ├── 2.7-2.9  drainRunLoop / escHotkey / permissions 平台分支
+  ├── 2.10-2.11 common.ts 平台标识动态化
+  ├── 2.12-2.13 gates.ts 默认值
+  └── 验证 Windows
+
+Phase 3（Linux 后端）
+  ├── 3.1  input/backends/linux.ts
+  ├── 3.2  swift/backends/linux.ts
+  ├── 3.3-3.4  dispatcher 加 linux case
+  └── 验证 Linux
+
+Phase 4（集成验证 + PR）
+```
+
+每个 Phase 可独立验证、独立提交。Phase 2 完成后 macOS + Windows 可用，Phase 3 完成后三平台全部可用。

docs/features/coordinator-mode.md

@@ -0,0 +1,151 @@
+# COORDINATOR_MODE — 多 Agent 编排
+
+> Feature Flag: `FEATURE_COORDINATOR_MODE=1` + 环境变量 `CLAUDE_CODE_COORDINATOR_MODE=1`
+> 实现状态：编排者完整可用，worker agent 为通用 AgentTool worker
+> 引用数：32
+
+## 一、功能概述
+
+COORDINATOR_MODE 将 CLI 变为"编排者"角色。编排者不直接操作文件，而是通过 AgentTool 派发任务给多个 worker 并行执行。适用于大型任务拆分、并行研究、实现+验证分离等场景。
+
+### 核心约束
+
+- 编排者只能使用：`Agent`（派发 worker）、`SendMessage`（继续 worker）、`TaskStop`（停止 worker）
+- Worker 可以使用所有标准工具（Bash、Read、Edit 等）+ MCP 工具 + Skill 工具
+- 编排者的每条消息都是给用户看的；worker 结果以 `<task-notification>` XML 形式到达
+
+## 二、用户交互
+
+### 启用方式
+
+```bash
+FEATURE_COORDINATOR_MODE=1 CLAUDE_CODE_COORDINATOR_MODE=1 bun run dev
+```
+
+需要同时设置 feature flag 和环境变量。`CLAUDE_CODE_COORDINATOR_MODE` 可在会话恢复时自动切换（`matchSessionMode`）。
+
+### 典型工作流
+
+```
+用户: "修复 auth 模块的 null pointer"
+
+编排者:
+  1. 并行派发两个 worker:
+     - Agent({ description: "调查 auth bug", prompt: "..." })
+     - Agent({ description: "研究 auth 测试", prompt: "..." })
+
+  2. 收到 <task-notification>:
+     - Worker A: "在 validate.ts:42 发现 null pointer"
+     - Worker B: "测试覆盖情况..."
+
+  3. 综合发现，继续 Worker A:
+     - SendMessage({ to: "agent-a1b", message: "修复 validate.ts:42..." })
+
+  4. 收到修复结果，派发验证:
+     - Agent({ description: "验证修复", prompt: "..." })
+```
+
+## 三、实现架构
+
+### 3.1 模式检测
+
+文件：`src/coordinator/coordinatorMode.ts:36-41`
+
+```ts
+export function isCoordinatorMode(): boolean {
+  return feature('COORDINATOR_MODE') &&
+    isEnvTruthy(process.env.CLAUDE_CODE_COORDINATOR_MODE)
+}
+```
+
+### 3.2 会话模式恢复
+
+`matchSessionMode(sessionMode)` 在恢复旧会话时检查存储的模式，如果当前环境变量与存储不一致，自动翻转环境变量。防止在普通模式下恢复编排会话（或反之）。
+
+### 3.3 Worker 工具集
+
+`getCoordinatorUserContext()` 告知编排者 worker 可用的工具列表：
+
+- **标准模式**：`ASYNC_AGENT_ALLOWED_TOOLS` 排除内部工具（TeamCreate、TeamDelete、SendMessage、SyntheticOutput）
+- **Simple 模式**（`CLAUDE_CODE_SIMPLE=1`）：仅 Bash、Read、Edit
+- **MCP 工具**：列出已连接的 MCP 服务器名称
+- **Scratchpad**：如果 GrowthBook `tengu_scratch` 启用，提供跨 worker 共享的 scratchpad 目录
+
+### 3.4 系统提示
+
+文件：`src/coordinator/coordinatorMode.ts:111-369`
+
+编排者系统提示（`getCoordinatorSystemPrompt()`）约 370 行，包含：
+
+| 章节 | 内容 |
+|------|------|
+| 1. Your Role | 编排者职责定义 |
+| 2. Your Tools | Agent/SendMessage/TaskStop 使用说明 |
+| 3. Workers | Worker 能力和限制 |
+| 4. Task Workflow | Research → Synthesis → Implementation → Verification 流程 |
+| 5. Writing Worker Prompts | 自包含 prompt 编写指南 + 好坏示例对比 |
+| 6. Example Session | 完整示例对话 |
+
+### 3.5 Worker Agent
+
+文件：`src/coordinator/workerAgent.ts`
+
+当前为 stub。Worker 实际使用通用 AgentTool 的 `worker` subagent_type。
+
+### 3.6 数据流
+
+```
+用户消息
+      │
+      ▼
+编排者 REPL（受限工具集）
+      │
+      ├──→ Agent({ subagent_type: "worker", prompt: "..." })
+      │         │
+      │         ▼
+      │    Worker Agent（完整工具集）
+      │    ├── 执行任务（Bash/Read/Edit/...）
+      │    └── 返回 <task-notification>
+      │
+      ├──→ SendMessage({ to: "agent-id", message: "..." })
+      │         │
+      │         ▼
+      │    继续已存在的 Worker
+      │
+      └──→ TaskStop({ task_id: "agent-id" })
+                │
+                ▼
+           停止运行中的 Worker
+```
+
+## 四、关键设计决策
+
+1. **双开关设计**：feature flag 控制代码可用性，环境变量控制实际激活。允许编译时包含但不默认启用
+2. **编排者受限**：只能用 Agent/SendMessage/TaskStop，确保编排者专注于派发而非执行
+3. **Worker 不可见编排者对话**：每个 worker 的 prompt 必须自包含（所有必要上下文）
+4. **并行优先**：系统提示强调"Parallelism is your superpower"，鼓励并行派发独立任务
+5. **综合而非转发**：编排者必须理解 worker 发现，再写出具体的实现指令。禁止 "based on your findings" 类懒惰委托
+6. **Scratchpad 可选共享**：通过 GrowthBook 门控的共享目录，让 worker 之间持久化共享知识
+
+## 五、使用方式
+
+```bash
+# 基本启用
+FEATURE_COORDINATOR_MODE=1 CLAUDE_CODE_COORDINATOR_MODE=1 bun run dev
+
+# 配合 Fork Subagent
+FEATURE_COORDINATOR_MODE=1 FEATURE_FORK_SUBAGENT=1 \
+CLAUDE_CODE_COORDINATOR_MODE=1 bun run dev
+
+# Simple 模式（worker 只有 Bash/Read/Edit）
+FEATURE_COORDINATOR_MODE=1 CLAUDE_CODE_COORDINATOR_MODE=1 \
+CLAUDE_CODE_SIMPLE=1 bun run dev
+```
+
+## 六、文件索引
+
+| 文件 | 行数 | 职责 |
+|------|------|------|
+| `src/coordinator/coordinatorMode.ts` | 370 | 模式检测 + 系统提示 + 用户上下文 |
+| `src/coordinator/workerAgent.ts` | — | Worker agent 定义（stub） |
+| `src/constants/tools.ts` | — | `ASYNC_AGENT_ALLOWED_TOOLS` 工具白名单 |

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

@@ -0,0 +1,117 @@
+# DAEMON — 后台守护进程
+
+> Feature Flag: `FEATURE_DAEMON=1`
+> 实现状态：Supervisor 和 remoteControl Worker 已实现
+> 引用数：3
+
+## 一、功能概述
+
+DAEMON 将 Claude Code 变为后台守护进程。主进程（supervisor）管理多个 worker 子进程的生命周期，通过文件系统状态文件进行通信。适用于持续运行的后台服务场景（如配合 BRIDGE_MODE 提供远程控制服务）。
+
+## 二、实现架构
+
+### 2.1 模块状态
+
+| 模块 | 文件 | 状态 |
+|------|------|------|
+| 守护主进程 | `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 门控 |
+
+### 2.2 CLI 入口
+
+```
+# 启动守护进程
+claude daemon start
+
+# 查看状态（默认子命令）
+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 架构
+
+```
+Supervisor (daemonMain)
+      │
+      ├── Worker: remoteControl
+      │   └── runBridgeHeadless() — 远程控制 headless 模式
+      │       接收远程会话、处理消息、权限审批
+      │
+      ▼
+文件系统状态文件 (daemon-state.json)
+  - PID、CWD、启动时间、Worker 类型
+  - queryDaemonStatus() / stopDaemonByPid()
+```
+
+### 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 常组合使用：
+
+```ts
+// src/commands.ts
+if (feature('DAEMON') && feature('BRIDGE_MODE')) {
+  // 加载 remoteControlServer 命令
+}
+```
+
+双重门控：两个 feature 都需要开启才能使用远程控制服务器。
+
+## 三、关键设计决策
+
+1. **多进程架构**：一个 supervisor + 多个 worker，进程隔离
+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 start
+
+# 查看状态
+claude daemon status
+
+# 停止守护进程
+claude daemon stop
+
+# 以特定 worker 启动（通常由 supervisor 自动调用）
+claude --daemon-worker=remoteControl
+```
+
+## 五、文件索引
+
+| 文件 | 职责 |
+|------|------|
+| `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

@@ -0,0 +1,50 @@
+---
+title: "Debug 模式"
+description: "通过 VS Code attach 模式调试 CLI 运行时，支持断点、单步执行和变量查看。"
+keywords: ["debug", "调试", "VS Code", "inspect", "断点"]
+---
+
+## 概述
+
+TUI (REPL) 模式需要真实终端，无法直接通过 VS Code launch 启动调试。使用 **attach 模式**连接到正在运行的 Bun 进程。
+
+## 步骤
+
+### 1. 终端启动 inspect 服务
+
+```bash
+bun run dev:inspect
+```
+
+会输出类似 `ws://localhost:8888/xxxxxxxx` 的地址。
+
+### 2. VS Code 附着调试器
+
+1. 在 `src/` 文件中打断点
+2. F5 → 选择 **"Attach to Bun (TUI debug)"**
+
+> **注意**：`dev:inspect` 和 `launch.json` 中的 WebSocket 地址会在每次启动时变化，需要同步更新两处。
+
+## 原理
+
+`dev:inspect` 脚本实际执行的是 `scripts/dev-debug.ts`：
+
+```typescript
+// scripts/dev-debug.ts
+process.env.BUN_INSPECT = "localhost:8888/<token>"
+await import("./dev")
+```
+
+通过设置 `BUN_INSPECT` 环境变量启动一个 Chrome DevTools Protocol 兼容的 inspect 服务，然后导入 dev 模式入口。VS Code 的 `bun` 扩展通过 WebSocket 连接到输出的地址实现 attach。
+
+## JetBrains IDE
+
+理论上 JetBrains 系列（WebStorm / IntelliJ 等）也支持 attach 到 Bun inspect 服务（Run → Attach to Process），但尚未实际验证过。如果你验证成功，欢迎补充文档。
+
+## 相关文件
+
+| 文件 | 说明 |
+|---|---|
+| `package.json` → `dev:inspect` | 启动 inspect 服务的 npm script |
+| `.vscode/launch.json` | VS Code attach 调试配置 |
+| `scripts/dev.ts` | dev 模式入口，注入 MACRO defines |

docs/features/experimental-skill-search.md

@@ -0,0 +1,99 @@
+# EXPERIMENTAL_SKILL_SEARCH — 技能语义搜索
+
+> Feature Flag: `FEATURE_EXPERIMENTAL_SKILL_SEARCH=1`
+> 实现状态：全部 Stub（8 个文件），布线完整
+> 引用数：21
+
+## 一、功能概述
+
+EXPERIMENTAL_SKILL_SEARCH 提供 DiscoverSkills 工具，根据当前任务语义搜索可用技能。目标是让模型在执行任务时自动发现和推荐相关的技能（包括本地和远程），无需用户手动查找。
+
+## 二、实现架构
+
+### 2.1 模块状态
+
+| 模块 | 文件 | 状态 | 说明 |
+|------|------|------|------|
+| DiscoverSkillsTool | `src/tools/DiscoverSkillsTool/prompt.ts` | **Stub** | 空工具名 |
+| 预取 | `src/services/skillSearch/prefetch.ts` | **Stub** | 3 个函数全部空操作 |
+| 远程加载 | `src/services/skillSearch/remoteSkillLoader.ts` | **Stub** | 返回空结果 |
+| 远程状态 | `src/services/skillSearch/remoteSkillState.ts` | **Stub** | 返回 null/undefined |
+| 信号 | `src/services/skillSearch/signals.ts` | **Stub** | `DiscoverySignal = any` |
+| 遥测 | `src/services/skillSearch/telemetry.ts` | **Stub** | 空操作日志 |
+| 本地搜索 | `src/services/skillSearch/localSearch.ts` | **Stub** | 空操作缓存 |
+| 功能检查 | `src/services/skillSearch/featureCheck.ts` | **Stub** | `isSkillSearchEnabled => false` |
+| SkillTool 集成 | `src/tools/SkillTool/SkillTool.ts` | **布线** | 动态加载所有远程技能模块 |
+| 提示集成 | `src/constants/prompts.ts` | **布线** | DiscoverSkills schema 注入 |
+
+### 2.2 预期数据流
+
+```
+模型处理用户任务
+      │
+      ▼
+DiscoverSkills 工具触发 [需要实现]
+      │
+      ├── 本地搜索：索引已安装技能元数据
+      │   └── localSearch.ts → 技能名称/描述/关键字匹配
+      │
+      └── 远程搜索：查询技能市场/注册表
+          └── remoteSkillLoader.ts → fetch + 解析
+      │
+      ▼
+结果排序和过滤
+      │
+      ▼
+返回推荐技能列表
+      │
+      ▼
+模型使用 SkillTool 调用推荐技能
+```
+
+### 2.3 预取机制
+
+`prefetch.ts` 预期在用户提交输入前分析消息内容，提前搜索相关技能：
+
+- `startSkillDiscoveryPrefetch()` — 开始预取
+- `collectSkillDiscoveryPrefetch()` — 收集预取结果
+- `getTurnZeroSkillDiscovery()` — 获取 turn 0 的技能发现结果
+
+## 三、需要补全的内容
+
+| 优先级 | 模块 | 工作量 | 说明 |
+|--------|------|--------|------|
+| 1 | `DiscoverSkillsTool` | 大 | 语义搜索工具 schema + 执行 |
+| 2 | `skillSearch/prefetch.ts` | 中 | 用户输入分析和预取逻辑 |
+| 3 | `skillSearch/remoteSkillLoader.ts` | 大 | 远程市场/注册表获取 |
+| 4 | `skillSearch/remoteSkillState.ts` | 小 | 已发现技能状态管理 |
+| 5 | `skillSearch/localSearch.ts` | 中 | 本地索引构建/查询 |
+| 6 | `skillSearch/featureCheck.ts` | 小 | GrowthBook/配置门控 |
+| 7 | `skillSearch/signals.ts` | 小 | `DiscoverySignal` 类型定义 |
+
+## 四、关键设计决策
+
+1. **预取优化**：在用户提交前就开始搜索，减少首次响应延迟
+2. **本地+远程双搜索**：本地索引快速匹配 + 远程市场深度搜索
+3. **SkillTool 集成**：发现的技能通过 SkillTool 调用，不需要新的调用机制
+4. **独立于 MCP_SKILLS**：MCP_SKILLS 从 MCP 服务器发现，EXPERIMENTAL_SKILL_SEARCH 从技能市场发现
+
+## 五、使用方式
+
+```bash
+# 启用 feature（需要补全后才能真正使用）
+FEATURE_EXPERIMENTAL_SKILL_SEARCH=1 bun run dev
+```
+
+## 六、文件索引
+
+| 文件 | 职责 |
+|------|------|
+| `src/tools/DiscoverSkillsTool/prompt.ts` | 工具 schema（stub） |
+| `src/services/skillSearch/prefetch.ts` | 预取逻辑（stub） |
+| `src/services/skillSearch/remoteSkillLoader.ts` | 远程加载（stub） |
+| `src/services/skillSearch/remoteSkillState.ts` | 远程状态（stub） |
+| `src/services/skillSearch/signals.ts` | 信号类型（stub） |
+| `src/services/skillSearch/telemetry.ts` | 遥测（stub） |
+| `src/services/skillSearch/localSearch.ts` | 本地搜索（stub） |
+| `src/services/skillSearch/featureCheck.ts` | 功能检查（stub） |
+| `src/tools/SkillTool/SkillTool.ts` | SkillTool 集成点 |
+| `src/constants/prompts.ts:95,335,778` | 提示增强 |

docs/features/external/chrome-control.md

@@ -1,189 +0,0 @@
----
-title: "Chrome 浏览器控制"
-description: "让 AI 用自然语言操作 Chrome 浏览器：导航、表单、数据抓取。两种实现方案对比：自托管 MCP（chrome-use-mcp）与 Chrome 原生集成（claude-in-chrome-mcp）。"
-keywords: ["Chrome 浏览器控制", "MCP", "浏览器自动化", "Claude in Chrome", "网页抓取"]
----
-
-# Chrome 浏览器控制
-
-让 Claude Code 用自然语言直接操作 Chrome 浏览器，完成网页导航、表单填写、数据抓取、截图录制等任务。
-
-Claude Code 提供两种浏览器控制方案：
-
-| 方案 | 简介 | 适用场景 |
-|------|------|---------|
-| **Chrome Use MCP**（自托管 MCP） | 通过社区开源 MCP 扩展（`mcp-chrome`）接入，Claude Code 以 MCP 客户端方式调用 | 想自托管、可定制、不依赖 Anthropic 订阅 |
-| **Claude in Chrome**（Chrome 原生集成） | Anthropic 官方扩展 + 内建工具集，通过 `--chrome` 启动参数加载 | 需要完整能力（截图/GIF/网络监控/JS 执行等），有 Claude Pro/Max/Team 订阅 |
-
-两种方案可以独立使用，也可按需切换。下面先讲快速上手，再分别给出详细说明。
-
-## 快速上手
-
-### 方案一：Chrome Use MCP（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 确认
-
-### 方案二：Claude in Chrome
-
-**前置条件**
-
-| 条件 | 说明 |
-|------|------|
-| Claude Code 订阅 | 需要 Claude Pro、Max 或 Team 订阅，浏览器插件功能不向免费用户开放 |
-| Chrome 浏览器 | 需已安装 Google Chrome |
-| Claude in Chrome 扩展 | 从 Chrome Web Store 安装（`claude.ai/chrome`） |
-| Claude Code CLI | 已通过 `bun run dev` 或构建产物运行 |
-
-**启动 CLI**
-
-```bash
-# Dev 模式
-bun run dev -- --chrome
-
-# 构建产物
-node dist/cli.js --chrome
-```
-
-启动后 Claude 会自动检测 Chrome 扩展是否已安装，并注册浏览器控制工具。
-
-**确认连接**：REPL 中输入 `/chrome`，查看扩展状态是否显示 "Installed / Connected"。
-
-**开始对话**：正常与 Claude 对话，当需要操作浏览器时直接说，例如：
-
-- "打开 https://example.com 并截图"
-- "在当前页面搜索关键词 xxx"
-- "填写登录表单，用户名 admin"
-- "帮我录制当前操作的 GIF"
-
-**权限审批**：首次执行浏览器操作时，Claude 会请求你的确认；操作完成后返回结果（截图、文本、执行结果等）。
-
-## 详细说明：Chrome Use MCP
-
-Chrome Use MCP 是基于社区开源项目 [`mcp-chrome`](https://github.com/hangwin/mcp-chrome) 的自托管方案。Claude Code 以标准 MCP 客户端身份接入，由扩展提供浏览器侧能力。
-
-特点：
-
-- 完全开源、可自托管，不依赖 Anthropic 账户体系
-- 在 MCP 面板里启用/禁用，不占用启动参数
-- 能力由扩展决定，适合做定制化浏览器自动化
-
-相关文档：
-
-- GitHub 仓库：https://github.com/hangwin/mcp-chrome
-
-## 详细说明：Claude in Chrome
-
-Claude in Chrome 是 Anthropic 官方扩展 + 内建工具集，提供更完整的浏览器操控能力。
-
-### 可用操作
-
-#### 页面交互
-
-| 操作 | 说明 |
-|------|------|
-| `navigate` | 导航到指定 URL，或前进/后退 |
-| `computer` | 鼠标点击、移动、拖拽、键盘输入、截图等（13 种 action） |
-| `form_input` | 填写表单字段 |
-| `upload_image` | 上传图片到文件输入框或拖拽区域 |
-| `javascript_tool` | 在页面上下文执行 JavaScript |
-
-#### 页面读取
-
-| 操作 | 说明 |
-|------|------|
-| `read_page` | 获取页面可访问性树（DOM 结构） |
-| `get_page_text` | 提取页面纯文本内容 |
-| `find` | 用自然语言搜索页面元素 |
-
-#### 标签页管理
-
-| 操作 | 说明 |
-|------|------|
-| `tabs_context_mcp` | 获取当前标签组信息 |
-| `tabs_create_mcp` | 创建新标签页 |
-
-#### 监控与调试
-
-| 操作 | 说明 |
-|------|------|
-| `read_console_messages` | 读取浏览器控制台日志 |
-| `read_network_requests` | 读取网络请求记录 |
-
-#### 其他
-
-| 操作 | 说明 |
-|------|------|
-| `resize_window` | 调整浏览器窗口尺寸 |
-| `gif_creator` | 录制 GIF 并导出 |
-| `shortcuts_list` | 列出可用快捷方式 |
-| `shortcuts_execute` | 执行快捷方式 |
-| `update_plan` | 向你提交操作计划供审批 |
-| `switch_browser` | 切换到其他 Chrome 浏览器（仅 Bridge 模式） |
-
-### 通信模式
-
-Claude in Chrome 支持两种与浏览器通信的方式：
-
-**本地 Socket（默认）**：Chrome 扩展通过 Native Messaging Host 与 CLI 建立 Unix socket 连接。适用于本地开发，无需额外配置。
-
-**Bridge WebSocket**：通过 Anthropic 的 bridge 服务中转，支持远程操控浏览器。需要 claude.ai OAuth 登录。
-
-## 进阶与参考
-
-### 配置
-
-#### 启用 / 禁用（Claude in Chrome）
-
-```bash
-# 显式禁用
-bun run dev -- --no-chrome
-```
-
-或在 REPL 中通过 `/chrome` 命令切换启用/禁用状态。
-
-#### 通过配置默认启用
-
-在 Claude Code 设置中将 `claudeInChromeDefaultEnabled` 设为 `true`，以后启动无需加 `--chrome` 参数。
-
-#### Feature Flag 提示
-
-- Chrome Use MCP：依赖标准 MCP 加载机制，通过 `/mcp` 面板启用。
-- Claude in Chrome：构建/运行时通过 `--chrome` 参数（对应内部 feature 开关）加载浏览器相关模块；不带该参数启动时不会加载任何浏览器相关模块，不影响其他功能。
-
-### 常见问题
-
-**扩展显示未安装**
-
-确认已从 Chrome Web Store 安装 "Claude in Chrome" 扩展，安装后重启浏览器。Chrome Use MCP 用户则需确认已按上面"加载已解压的扩展程序"步骤加载本地扩展。
-
-**工具未出现在工具列表**
-
-- Claude in Chrome：检查启动时是否加了 `--chrome` 参数，或通过 `/chrome` 命令确认状态。
-- Chrome Use MCP：在 `/mcp` 面板里确认 `mcp-chrome` 已启用。
-
-**连接超时**
-
-确保 Chrome 浏览器正在运行且扩展已启用。Native Messaging Host 在扩展安装时自动注册，如果重装过扩展需要重启浏览器。
-
-**不使用 Chrome 功能时**
-
-不带 `--chrome` 参数正常启动即可，不会加载任何浏览器相关模块，不影响其他功能。

docs/features/external/voice-mode.md

@@ -1,269 +0,0 @@
----
-title: "语音输入（Voice Mode）"
-description: "Push-to-talk 语音输入，支持豆包语言模型。需 Anthropic OAuth 或本地语音后端。"
-keywords: ["语音输入", "Push-to-Talk", "豆包 ASR", "STT", "语音转录"]
----
-
-# VOICE_MODE — 语音输入
-
-> Feature Flag: `FEATURE_VOICE_MODE=1`
-> 实现状态：完整可用（双后端：Anthropic OAuth / 豆包 ASR）
-> 引用数：46
-
-## 一、功能概述
-
-VOICE_MODE 实现"按键说话"（Push-to-Talk）语音输入。用户按住空格键录音，音频流式传输到 STT 后端，实时转录显示在终端中。支持两个后端：
-
-- **Anthropic STT（默认）**：通过 WebSocket 流式传输到 Nova 3 端点，需要 Anthropic OAuth
-- **豆包 ASR（Doubao）**：通过 `doubaoime-asr` 包的 AsyncGenerator 协议流式识别，使用独立凭证文件，无需 Anthropic OAuth
-
-### 核心特性
-
-- **Push-to-Talk**：长按空格键录音，释放后自动发送
-- **流式转录**：录音过程中实时显示中间转录结果
-- **无缝集成**：转录文本直接作为用户消息提交到对话
-- **双后端切换**：通过 `/voice` 命令参数选择 STT 后端，持久化到 settings.json
-
-## 二、用户交互
-
-| 操作 | 行为 |
-|------|------|
-| 长按空格 | 开始录音，显示录音状态 |
-| 释放空格 | 停止录音，转录结果自动提交 |
-| `/voice` | 切换语音模式开关（默认使用 Anthropic 后端） |
-| `/voice doubao` | 启用语音模式并使用豆包 ASR 后端 |
-| `/voice anthropic` | 切换回 Anthropic STT 后端 |
-
-### UI 反馈
-
-- **录音指示器**：录音时显示红色/脉冲动画
-- **中间转录**：录音过程中显示 STT 实时识别文本
-- **最终转录**：完成后替换中间结果
-
-## 三、实现架构
-
-### 3.1 门控逻辑
-
-文件：`src/voice/voiceModeEnabled.ts`
-
-两层检查函数：
-
-```ts
-// Anthropic 后端（需要 OAuth）
-isVoiceModeEnabled() = hasVoiceAuth() && isVoiceGrowthBookEnabled()
-
-// 豆包后端 / 通用可用性检查（不需要 OAuth）
-isVoiceAvailable() = isVoiceGrowthBookEnabled()
-```
-
-1. **Feature Flag**：`feature('VOICE_MODE')` — 编译时/运行时开关
-2. **GrowthBook Kill-Switch**：`!getFeatureValue_CACHED_MAY_BE_STALE('tengu_amber_quartz_disabled', false)` — 紧急关闭开关（默认 false = 未禁用）
-3. **Auth 检查（仅 Anthropic）**：`hasVoiceAuth()` — 需要 Anthropic OAuth token（非 API key）
-4. **Provider 检查**：`voiceProvider` 设置决定使用哪个后端，豆包后端跳过 OAuth 检查
-
-### 3.2 核心模块
-
-| 模块 | 职责 |
-|------|------|
-| `src/voice/voiceModeEnabled.ts` | Feature flag + GrowthBook + Auth 三层门控 |
-| `src/hooks/useVoice.ts` | React hook 管理录音状态和后端连接 |
-| `src/services/voiceStreamSTT.ts` | Anthropic WebSocket 流式 STT |
-| `src/services/doubaoSTT.ts` | 豆包 ASR 适配器（AsyncGenerator → VoiceStreamConnection） |
-| `src/commands/voice/voice.ts` | `/voice` 命令实现，处理后端选择和持久化 |
-| `src/hooks/useVoiceEnabled.ts` | 语音启用状态 hook，根据 provider 决定是否跳过 OAuth |
-| `src/utils/settings/types.ts` | `voiceProvider: 'anthropic' | 'doubao'` 设置类型定义 |
-
-### 3.3 数据流
-
-#### Anthropic 后端
-
-```
-用户按下空格键
-      │
-      ▼
-useVoice hook 激活
-      │
-      ▼
-macOS 原生音频 / SoX 开始录音
-      │
-      ▼
-WebSocket 连接到 Anthropic STT 端点
-      │
-      ├──→ 中间转录结果 → 实时显示
-      │
-      ▼
-用户释放空格键
-      │
-      ▼
-停止录音，等待最终转录
-      │
-      ▼
-转录文本 → 插入输入框 → 自动提交
-```
-
-#### 豆包 ASR 后端
-
-```
-用户按下空格键
-      │
-      ▼
-useVoice hook 激活（检测到 voiceProvider === 'doubao'）
-      │
-      ▼
-macOS 原生音频 / SoX 开始录音
-      │
-      ▼
-connectDoubaoStream() 创建 AudioChunkQueue + VoiceStreamConnection
-      │
-      ├──→ onReady 立即触发（无需等待握手）
-      │
-      ▼
-音频数据通过 AudioChunkQueue 传入 transcribeRealtime()
-      │
-      ├──→ INTERIM_RESULT → 实时显示中间转录
-      ├──→ FINAL_RESULT   → 显示最终转录
-      │
-      ▼
-用户释放空格键
-      │
-      ▼
-finalize() 立即返回（豆包在录音过程中已返回结果，无需等待）
-      │
-      ▼
-转录文本 → 插入输入框 → 自动提交
-```
-
-### 3.4 音频录制
-
-支持两种音频后端（两个 STT 后端共享）：
-- **macOS 原生音频**：优先使用，低延迟
-- **SoX（Sound eXchange）**：回退方案，跨平台
-
-### 3.5 豆包 ASR 适配器设计
-
-文件：`src/services/doubaoSTT.ts`
-
-豆包后端使用适配器模式，将 `doubaoime-asr` 的 AsyncGenerator 协议桥接到 `VoiceStreamConnection` 接口：
-
-**AudioChunkQueue** — push 式异步队列：
-- 实现 `AsyncIterable<Uint8Array>` 接口
-- `push(chunk)` 将音频数据入队，`push(null)` 发送结束信号
-- 内部维护等待者（waiting）和缓冲队列（chunks）两个状态
-
-**connectDoubaoStream()** — 连接入口：
-- 动态导入 `doubaoime-asr`（optionalDependencies）
-- 从 `~/.claude/tts/doubao/credentials.json` 加载凭证
-- 创建 AudioChunkQueue 和 VoiceStreamConnection
-- 立即触发 `onReady`（避免与 useVoice 的音频缓冲死锁）
-- `finalize()` 立即返回（豆包在录音过程中已返回结果）
-- 后台 async IIFE 消费 `transcribeRealtime` generator，映射响应类型到回调
-
-**响应类型映射**：
-
-| doubaoime-asr ResponseType | 回调映射 |
-|----------------------------|----------|
-| SESSION_STARTED | 日志记录 |
-| VAD_START | 日志记录 |
-| INTERIM_RESULT | `onTranscript(text, false)` |
-| FINAL_RESULT | `onTranscript(text, true)` |
-| ERROR | `onError(errorMsg)` |
-| SESSION_FINISHED | 日志记录 |
-
-### 3.6 后端选择逻辑
-
-文件：`src/hooks/useVoice.ts`
-
-```ts
-// 判断当前 provider
-isDoubaoProvider() → 读取 settings.voiceProvider
-
-// handleKeyEvent 中的可用性检查
-const sttAvailable = isDoubaoProvider()
-  ? isDoubaoAvailableSync()    // 乐观检查（首次返回 true）
-  : isVoiceStreamAvailable()   // Anthropic WebSocket 检查
-
-// attemptConnect 中的连接函数选择
-const connectFn = isDoubaoProvider()
-  ? connectDoubaoStream
-  : connectVoiceStream
-```
-
-豆包后端的特殊处理：
-- 跳过 `getVoiceKeyterms()` 调用（豆包无需关键词提示）
-- 跳过 Focus Mode（`if (!enabled || !focusMode || isDoubaoProvider())`）
-
-## 四、关键设计决策
-
-1. **双后端共存**：豆包后端作为独立适配器与 Anthropic 后端并存，不替换原有流程，通过 `voiceProvider` 设置切换
-2. **设置持久化**：`voiceProvider` 存储在 `settings.json`，通过 `/voice` 命令修改，跨会话生效
-3. **OAuth 独占（Anthropic）**：Anthropic 后端使用 `voice_stream` 端点（claude.ai），仅 OAuth 用户可用
-4. **豆包无需 OAuth**：豆包后端使用独立凭证文件，不依赖 Anthropic 认证，通过 `isVoiceAvailable()` 放宽门控
-5. **GrowthBook 负向门控**：`tengu_amber_quartz_disabled` 默认 `false`，新安装自动可用
-6. **onReady 立即触发**：豆包后端在连接建立后立即触发 `onReady`，避免与 useVoice 音频缓冲的时序死锁（Anthropic 需要等待 WebSocket 握手）
-7. **finalize() 立即返回**：豆包在录音过程中已返回所有结果，用户抬手时无需等待处理
-8. **乐观可用性检查**：`isDoubaoAvailableSync()` 在首次调用时返回 `true`，实际导入错误在 `connectDoubaoStream` 中处理
-9. **optionalDependencies**：`doubaoime-asr` 作为可选依赖，安装失败不影响 Anthropic 后端
-
-## 五、使用方式
-
-```bash
-# 启用 feature
-FEATURE_VOICE_MODE=1 bun run dev
-
-# 在 REPL 中使用 Anthropic 后端
-# 1. 确保已通过 OAuth 登录（claude.ai 订阅）
-# 2. 输入 /voice 启用
-# 3. 按住空格键说话
-# 4. 释放空格键等待转录
-
-# 在 REPL 中使用豆包 ASR 后端
-# 1. 确保 doubaoime-asr 已安装（bun add doubaoime-asr）
-# 2. 配置凭证文件：~/.claude/tts/doubao/credentials.json
-# 3. 输入 /voice doubao 启用
-# 4. 按住空格键说话
-# 5. 释放空格键，转录结果即刻显示
-
-# 切换后端
-/voice doubao      # 切换到豆包 ASR
-/voice anthropic   # 切换回 Anthropic STT
-/voice             # 关闭语音模式
-```
-
-### 豆包凭证配置
-
-凭证文件路径：`~/.claude/tts/doubao/credentials.json`
-
-```json
-{
-  "deviceId": "...",
-  "installId": "...",
-  "cdid": "...",
-  "openudid": "...",
-  "clientudid": "...",
-  "token": "..."
-}
-```
-
-## 六、外部依赖
-
-| 依赖 | 说明 | 适用后端 |
-|------|------|----------|
-| Anthropic OAuth | claude.ai 订阅登录，非 API key | Anthropic |
-| GrowthBook | `tengu_amber_quartz_disabled` 紧急关闭 | 通用 |
-| macOS 原生音频 或 SoX | 音频录制 | 通用 |
-| Nova 3 STT | Anthropic 语音转文本模型 | Anthropic |
-| doubaoime-asr | 豆包 ASR SDK（optionalDependencies） | 豆包 |
-| 凭证文件 | `~/.claude/tts/doubao/credentials.json` | 豆包 |
-
-## 七、文件索引
-
-| 文件 | 职责 |
-|------|------|
-| `src/voice/voiceModeEnabled.ts` | 三层门控逻辑 + `isVoiceAvailable()` |
-| `src/hooks/useVoice.ts` | React hook（录音状态 + 后端选择 + 连接管理） |
-| `src/hooks/useVoiceEnabled.ts` | 语音启用状态 hook（按 provider 决定 OAuth 检查） |
-| `src/services/voiceStreamSTT.ts` | Anthropic STT WebSocket 流式传输 |
-| `src/services/doubaoSTT.ts` | 豆包 ASR 适配器（AudioChunkQueue + connectDoubaoStream） |
-| `src/commands/voice/voice.ts` | `/voice` 命令（开关 + 后端选择） |
-| `src/commands/voice/index.ts` | 命令注册（去除 availability 限制） |
-| `src/utils/settings/types.ts` | `voiceProvider` 类型定义 |

docs/features/feature-flags-codex-review.md

@@ -0,0 +1,160 @@
+# Feature Flags 审查报告 — Codex 复核
+
+> 审查日期: 2026-04-05
+> 审查工具: Codex CLI v0.118.0 (本地, full-auto mode)
+> 消耗 tokens: 240,306
+> 审查范围: docs/feature-flags-audit-complete.md 中标记为 COMPLETE 的 22 个编译时 feature flag
+
+---
+
+## 审查背景
+
+原始审计报告 (`docs/feature-flags-audit-complete.md`) 声称 22 个 feature flag 被标记为 "COMPLETE"，只需在 `build.ts` / `scripts/dev.ts` 中启用即可工作。
+
+Claude Code 团队通过 6 个并行子代理实际读取源码后初步发现大量误判，随后将分析结果传递给 Codex CLI 进行独立二次验证。
+
+---
+
+## Codex 发现摘要
+
+### High 级发现
+
+1. **`CONTEXT_COLLAPSE` 不是 COMPLETE**
+   - `src/services/contextCollapse/index.ts:43` — `isContextCollapseEnabled()` 硬编码为 `false`
+   - `src/services/contextCollapse/index.ts:47` — `applyCollapsesIfNeeded()` 只是原样返回消息
+   - `src/services/contextCollapse/index.ts:59` — `recoverFromOverflow()` 也是 no-op
+   - `src/services/contextCollapse/operations.ts:3` 和 `persist.ts:3` 同样是 stub
+   - 审计报告把 UI/命令文件算进去了，但真正被查询循环消费的是 stub 后端
+
+2. **原分类"真正只需编译开关"的 7 个 flag，只有 3 个准确**
+   - ✅ `SHOT_STATS` — 零额外门控，compile-only
+   - ✅ `PROMPT_CACHE_BREAK_DETECTION` — 有 try-catch 兜底，compile-only
+   - ✅ `TOKEN_BUDGET` — 纯本地计算，compile-only
+   - ❌ `TEAMMEM` — 还要求 AutoMem + GrowthBook `tengu_herring_clock` + GitHub repo (`teamMemPaths.ts:73`, `watcher.ts:256`, `watcher.ts:259`)
+   - ❌ `AGENT_TRIGGERS` — 受 `isKairosCronEnabled()` GrowthBook 控制 (`useScheduledTasks.ts:61`, `useScheduledTasks.ts:119`)
+   - ❌ `EXTRACT_MEMORIES` — 受 `tengu_passport_quail` + AutoMem + 非 remote 限制 (`extractMemories.ts:536`, `:545`, `:550`)
+   - ❌ `KAIROS_BRIEF` — 受 `tengu_kairos_brief` + opt-in/kairosActive 限制 (`BriefTool.ts:95`, `:126`, `:132`)
+
+### Medium 级发现
+
+3. **`BG_SESSIONS` 和 `BASH_CLASSIFIER` 不适合简单归为"全 stub"**
+   - `BG_SESSIONS` — 会话注册/清理是真实现 (`concurrentSessions.ts:44`, `:55`)，但任务摘要核心是 stub (`taskSummary.ts:2`)
+   - `BASH_CLASSIFIER` — 权限编排很大一块是真实现 (`bashPermissions.ts` 2621行)，但分类后端 `bashClassifier.ts:24` 永远返回 disabled
+
+4. **审计口径问题**
+   - 把"代码量/周边 UI 很多"误当成"可独立启用"
+   - `PROACTIVE` — `index.ts:3` 只有 state stub，`commands.ts:64` 和 `REPL.tsx:415` 引用缺失文件
+   - `REACTIVE_COMPACT` — `reactiveCompact.ts:13` 整块是 stub
+   - `CACHED_MICROCOMPACT` — `cachedMicrocompact.ts:22` 全部 stub
+
+---
+
+## Codex 修正后的分类
+
+### 第一类：真正 compile-only（3 个）
+
+| Flag | 说明 | Crash 风险 |
+|------|------|-----------|
+| **SHOT_STATS** | 纯本地 shot 分布统计，ant-only 数据路径 | 低 |
+| **PROMPT_CACHE_BREAK_DETECTION** | 本地 cache key 变化检测，写 diff 有兜底 | 低 |
+| **TOKEN_BUDGET** | 本地 token 预算追踪，纯计算逻辑 | 低 |
+
+### 第二类：compile + 运行时条件（7 个）
+
+| Flag | 条件 | Crash 风险 |
+|------|------|-----------|
+| **TEAMMEM** | AutoMem + GrowthBook `tengu_herring_clock` + GitHub repo | 低 (clean no-op) |
+| **AGENT_TRIGGERS** | GrowthBook `isKairosCronEnabled()` | 低 (clean no-op) |
+| **EXTRACT_MEMORIES** | `tengu_passport_quail` + AutoMem + 非 remote | 低 (clean no-op) |
+| **KAIROS_BRIEF** | `tengu_kairos_brief` + opt-in/kairosActive，可用 `CLAUDE_CODE_BRIEF=1` 绕过 | 低 |
+| **COORDINATOR_MODE** | 需 `CLAUDE_CODE_COORDINATOR_MODE=1`，`workerAgent.ts` 是 stub 但不阻塞 | 低 |
+| **COMMIT_ATTRIBUTION** | 仅对 `isInternal=true` 的 repo 生效 | 低 |
+| **VERIFICATION_AGENT** | 受 GrowthBook `tengu_hive_evidence` 双重门控 | 低 |
+
+### 第三类：混合型 — 部分实现 + stub 核心（5 个）
+
+| Flag | 真实现部分 | Stub 核心 |
+|------|-----------|----------|
+| **BG_SESSIONS** | 会话注册/清理 (`concurrentSessions.ts`) | `bg.ts`/`taskSummary.ts`/`udsClient.ts` 全 stub + 依赖 tmux |
+| **BASH_CLASSIFIER** | 权限编排 (`bashPermissions.ts` 2621行) | `bashClassifier.ts` 分类后端 stub + 需 API beta |
+| **PROACTIVE** | REPL/命令注册框架 | `index.ts` stub + 3 文件缺失 |
+| **REACTIVE_COMPACT** | 调用点已在主查询环路 | `reactiveCompact.ts` 22行全 no-op |
+| **CACHED_MICROCOMPACT** | 调用点已布线 | `cachedMicrocompact.ts` 全 stub + 需未公开 API |
+
+### 第四类：纯 stub（1 个）
+
+| Flag | 问题 |
+|------|------|
+| **CONTEXT_COLLAPSE** | 3 核心文件全 stub + CtxInspectTool 目录不存在 |
+
+### 第五类：依赖远程服务（3 个）
+
+| Flag | 依赖 |
+|------|------|
+| **ULTRAPLAN** | CCR 远程 agent 基础设施 + OAuth |
+| **CCR_REMOTE_SETUP** | claude.ai OAuth + GitHub CLI + CCR 后端 |
+| **BRIDGE_MODE** (build端) | claude.ai 订阅 + GrowthBook + WebSocket 后端 |
+
+---
+
+## 第三类恢复优先级建议
+
+Codex 推荐的恢复顺序：
+
+1. **REACTIVE_COMPACT** — 收益最直接，调用点在主查询环路，改完最容易立刻见效
+2. **BG_SESSIONS** — 已有会话注册基础，补齐摘要和后台运行链路的 ROI 高
+3. **PROACTIVE** — 产品面大，但缺文件比 stub 更严重，范围比前两项大
+4. **CONTEXT_COLLAPSE** — collapse engine 全 stub，恢复成本和设计不确定性都高
+5. **BASH_CLASSIFIER** — 若无 API beta 能力不值得优先；若有则升到第 2
+6. **CACHED_MICROCOMPACT** — 受未公开 API 约束，最后做
+
+---
+
+## 审计报告分类标准修正建议
+
+Codex 建议将原来的单轴分类（COMPLETE/PARTIAL/STUB）改为**三轴**：
+
+| 轴 | 取值 | 说明 |
+|----|------|------|
+| **实现完整度** | `full` / `mixed` / `stub` | 活跃调用链上的核心模块是否有真实现 |
+| **激活条件** | `compile-only` / `compile+env` / `compile+GrowthBook` / `compile+remote` / `compile+private API` | 启用需要什么 |
+| **运行风险** | `safe no-op` / `background IO` / `startup critical` | 启用后条件不满足时的行为 |
+
+**COMPLETE 的最低标准应满足：**
+1. 活跃调用链上的核心模块不能是 stub
+2. "可启用"不能只看编译 flag，还要单列运行时 gate
+
+按此标准，`CONTEXT_COLLAPSE`、`BG_SESSIONS`、`BASH_CLASSIFIER`、`PROACTIVE`、`REACTIVE_COMPACT`、`CACHED_MICROCOMPACT` 都应从 COMPLETE 降级。
+
+---
+
+## 已采取的行动
+
+基于审查结果，已将以下 3 个确认安全的 flag 加入默认构建：
+
+**build.ts:**
+```typescript
+const DEFAULT_BUILD_FEATURES = [
+  "AGENT_TRIGGERS_REMOTE", "CHICAGO_MCP", "VOICE_MODE",
+  "SHOT_STATS", "PROMPT_CACHE_BREAK_DETECTION", "TOKEN_BUDGET"
+];
+```
+
+**scripts/dev.ts:**
+```typescript
+const DEFAULT_FEATURES = [
+  "BUDDY", "TRANSCRIPT_CLASSIFIER", "BRIDGE_MODE",
+  "AGENT_TRIGGERS_REMOTE", "CHICAGO_MCP", "VOICE_MODE",
+  "SHOT_STATS", "PROMPT_CACHE_BREAK_DETECTION", "TOKEN_BUDGET"
+];
+```
+
+### 验证结果
+
+| 项目 | 结果 |
+|------|------|
+| `bun run build` | ✅ 成功 (475 files) |
+| `bun test` | ✅ 无新增失败 (23 fail 为已有问题) |
+| SHOT_STATS 代码路径 | ✅ 完整 — stats 面板显示 shot 分布 |
+| TOKEN_BUDGET 代码路径 | ✅ 完整 — 支持 `+500k` 语法，带进度条 |
+| PROMPT_CACHE_BREAK_DETECTION 代码路径 | ✅ 完整 — 内部诊断，debug 模式可见 |

docs/features/fork-subagent.md

@@ -0,0 +1,195 @@
+# FORK_SUBAGENT — 上下文继承子 Agent
+
+> Feature Flag: `FEATURE_FORK_SUBAGENT=1`
+> 实现状态：完整可用
+> 引用数：4
+
+## 一、功能概述
+
+FORK_SUBAGENT 让 AgentTool 生成"fork 子 agent"，继承父级完整对话上下文。子 agent 看到父级的所有历史消息、工具集和系统提示，并且与父级共享 API 请求前缀以最大化 prompt cache 命中率。
+
+### 核心优势
+
+- **Prompt Cache 最大化**：多个并行 fork 共享相同的 API 请求前缀，只有最后的 directive 文本块不同
+- **上下文完整性**：子 agent 继承父级的完整对话历史（包括 thinking config）
+- **权限冒泡**：子 agent 的权限提示上浮到父级终端显示
+- **Worktree 隔离**：支持 git worktree 隔离，子 agent 在独立分支工作
+
+## 二、用户交互
+
+### 触发方式
+
+当 `FORK_SUBAGENT` 启用时，AgentTool 调用不指定 `subagent_type` 时自动走 fork 路径：
+
+```
+// Fork 路径（继承上下文）
+Agent({ prompt: "修复这个 bug" })  // 无 subagent_type
+
+// 普通 agent 路径（全新上下文）
+Agent({ subagent_type: "general-purpose", prompt: "..." })
+```
+
+### /fork 命令
+
+注册了 `/fork` 斜杠命令（当前为 stub）。当 FORK_SUBAGENT 开启时，`/branch` 命令失去 `fork` 别名，避免冲突。
+
+## 三、实现架构
+
+### 3.1 门控与互斥
+
+文件：`packages/builtin-tools/src/tools/AgentTool/forkSubagent.ts:32-39`
+
+```ts
+export function isForkSubagentEnabled(): boolean {
+  if (feature('FORK_SUBAGENT')) {
+    if (isCoordinatorMode()) return false   // Coordinator 有自己的委派模型
+    if (getIsNonInteractiveSession()) return false  // pipe/SDK 模式禁用
+    return true
+  }
+  return false
+}
+```
+
+### 3.2 FORK_AGENT 定义
+
+```ts
+export const FORK_AGENT = {
+  agentType: 'fork',
+  tools: ['*'],              // 通配符：使用父级完整工具集
+  maxTurns: 200,
+  model: 'inherit',          // 继承父级模型
+  permissionMode: 'bubble',  // 权限冒泡到父级终端
+  getSystemPrompt: () => '', // 不使用：直接传递父级已渲染 prompt
+}
+```
+
+### 3.3 核心调用流程
+
+```
+AgentTool.call({ prompt, name })
+      │
+      ▼
+isForkSubagentEnabled() && !subagent_type?
+      │
+      ├── No → 普通 agent 路径
+      │
+      └── Yes → Fork 路径
+            │
+            ▼
+      递归防护检查
+      ├── querySource === 'agent:builtin:fork' → 拒绝
+      └── isInForkChild(messages) → 拒绝
+            │
+            ▼
+      获取父级 system prompt
+      ├── toolUseContext.renderedSystemPrompt（首选）
+      └── buildEffectiveSystemPrompt（回退）
+            │
+            ▼
+      buildForkedMessages(prompt, assistantMessage)
+      ├── 克隆父级 assistant 消息
+      ├── 生成占位符 tool_result
+      └── 附加 directive 文本块
+            │
+            ▼
+      [可选] buildWorktreeNotice()
+            │
+            ▼
+      runAgent({
+        useExactTools: true,
+        override.systemPrompt: 父级,
+        forkContextMessages: 父级消息,
+        availableTools: 父级工具,
+      })
+```
+
+### 3.4 消息构建：buildForkedMessages
+
+文件：`packages/builtin-tools/src/tools/AgentTool/forkSubagent.ts:107-169`
+
+构建的消息结构：
+
+```
+[
+  ...history (filterIncompleteToolCalls),  // 父级完整历史
+  assistant(所有 tool_use 块),              // 父级当前 turn 的 assistant 消息
+  user(
+    占位符 tool_result × N +               // 相同占位符文本
+    <fork-boilerplate> directive           // 每个 fork 不同
+  )
+]
+```
+
+**所有 fork 使用相同的占位符文本**：`"Fork started — processing in background"`。这确保多个并行 fork 的 API 请求前缀完全一致，最大化 prompt cache 命中。
+
+### 3.5 递归防护
+
+两层检查防止 fork 嵌套：
+
+1. **querySource 检查**：`toolUseContext.options.querySource === 'agent:builtin:fork'`。在 `context.options` 上设置，抗自动压缩（autocompact 只重写消息不改 options）
+2. **消息扫描**：`isInForkChild()` 扫描消息历史中的 `<fork-boilerplate>` 标签
+
+### 3.6 Worktree 隔离通知
+
+当 fork + worktree 组合时，追加通知告知子 agent：
+
+> "你继承了父 agent 在 `{parentCwd}` 的对话上下文，但你在独立的 git worktree `{worktreeCwd}` 中操作。路径需要转换，编辑前重新读取。"
+
+### 3.7 强制异步
+
+当 `isForkSubagentEnabled()` 为 true 时，所有 agent 启动都强制异步。`run_in_background` 参数从 schema 中移除。统一通过 `<task-notification>` XML 消息交互。
+
+## 四、Prompt Cache 优化
+
+这是整个 fork 设计的核心优化目标：
+
+| 优化点 | 实现 |
+|--------|------|
+| **相同 system prompt** | 直传 `renderedSystemPrompt`，避免重新渲染（GrowthBook 状态可能不一致） |
+| **相同工具集** | `useExactTools: true` 直接使用父级工具，不经过 `resolveAgentTools` 过滤 |
+| **相同 thinking config** | 继承父级 thinking 配置（非 fork agent 默认禁用 thinking） |
+| **相同占位符结果** | 所有 fork 使用 `FORK_PLACEHOLDER_RESULT` 相同文本 |
+| **ContentReplacementState 克隆** | 默认克隆父级替换状态，保持 wire prefix 一致 |
+
+## 五、子 Agent 指令
+
+`buildChildMessage()` 生成 `<fork-boilerplate>` 包裹的指令：
+
+- 你是 fork worker，不是主 agent
+- 禁止再次 spawn sub-agent（直接执行）
+- 不要闲聊、不要元评论
+- 直接使用工具
+- 修改文件后要 commit，报告 commit hash
+- 报告格式：`Scope:` / `Result:` / `Key files:` / `Files changed:` / `Issues:`
+
+## 六、关键设计决策
+
+1. **Fork ≠ 普通 agent**：fork 继承完整上下文，普通 agent 从零开始。选择依据是 `subagent_type` 是否存在
+2. **renderedSystemPrompt 直传**：避免 fork 时重新调用 `getSystemPrompt()`。父级在 turn 开始时冻结 prompt 字节
+3. **占位符结果共享**：多个并行 fork 使用完全相同的占位符，只有 directive 不同
+4. **Coordinator 互斥**：Coordinator 模式下禁用 fork，两者有不兼容的委派模型
+5. **非交互式禁用**：pipe 模式和 SDK 模式下禁用，避免不可见的 fork 嵌套
+
+## 七、使用方式
+
+```bash
+# 启用 feature
+FEATURE_FORK_SUBAGENT=1 bun run dev
+
+# 在 REPL 中使用（不指定 subagent_type 即走 fork）
+# Agent({ prompt: "研究这个模块的结构" })
+# Agent({ prompt: "实现这个功能" })
+```
+
+## 八、文件索引
+
+| 文件 | 行数 | 职责 |
+|------|------|------|
+| `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/growthbook-enablement-plan.md

@@ -0,0 +1,334 @@
+# GrowthBook 功能启用计划
+
+> 编制日期: 2026-04-06
+> 基于: feature-flags-codex-review.md + 4 个并行研究代理的深度分析
+> 前提: 我们是付费订阅用户，拥有有效的 Anthropic API key
+
+---
+
+## 背景
+
+Claude Code 使用三层门控系统：
+1. **编译时 feature flag** — `feature('FLAG_NAME')` from `bun:bundle`
+2. **GrowthBook 远程开关** — `tengu_*` 前缀，通过 SDK 连接 Anthropic 服务端
+3. **运行时环境变量** — `USER_TYPE`、`CLAUDE_CODE_*` 等
+
+在我们的反编译版本中，GrowthBook 不启动（analytics 链空实现），导致所有 `tengu_*` 检查默认返回 `false`。
+
+**核心发现：所有被 GrowthBook 门控的功能代码都是真实现，没有 stub。**
+
+---
+
+## 启用方式说明
+
+### 方式 1：硬编码绕过（推荐先用）
+在 `src/services/analytics/growthbook.ts` 的 `getFeatureValueInternal()` 函数中添加默认值映射。
+
+### 方式 2：自建 GrowthBook 服务器
+```bash
+docker run -p 3100:3100 growthbook/growthbook
+# 设置环境变量
+CLAUDE_GB_ADAPTER_URL=http://localhost:3100
+CLAUDE_GB_ADAPTER_KEY=sdk-xxx
+```
+
+### 方式 3：恢复原生 1P 连接
+让 `is1PEventLoggingEnabled()` 返回 `true`，连接 Anthropic 的 GrowthBook 服务端。
+注意：会发送使用统计（不含代码/对话内容）。
+
+---
+
+## 优先级 P0：纯本地功能（零外部依赖，立即可用）
+
+这些功能不需要 API 调用，开启 gate 即可工作。
+
+### P0-1. 自定义快捷键
+- **Gate**: `tengu_keybinding_customization_release` → `true`
+- **编译 flag**: 无（已内置）
+- **代码量**: 473 行，完整实现
+- **功能**: 加载 `~/.claude/keybindings.json`，支持热重载、重复键检测、结构验证
+- **效果**: 用户可自定义所有快捷键
+- **风险**: 无
+
+### P0-2. 流式工具执行
+- **Gate**: `tengu_streaming_tool_execution2` → `true`
+- **编译 flag**: 无（已内置）
+- **代码量**: 577 行（StreamingToolExecutor），完整实现
+- **功能**: API 响应还在流式返回时就开始执行工具，减少等待时间
+- **效果**: 显著提升交互速度
+- **风险**: 低（生产级代码，有错误处理）
+
+### P0-3. 定时任务系统
+- **Gate**: `tengu_kairos_cron` → `true`（额外：`tengu_kairos_cron_durable` 默认 `true`）
+- **编译 flag**: `AGENT_TRIGGERS`（需新增）或 `AGENT_TRIGGERS_REMOTE`（已启用）
+- **代码量**: 1025 行（cronTasks + cronScheduler），完整实现
+- **功能**: 本地 cron 调度，支持一次性/周期性任务、防雷群效应 jitter、自动过期
+- **效果**: 可设置定时执行的 Claude 任务
+- **风险**: 低
+
+### P0-4. Agent 团队 / Swarm
+- **Gate**: `tengu_amber_flint` → `true`（这是 kill switch，默认已 `true`）
+- **编译 flag**: 无（已内置）
+- **代码量**: 45 行（gate 层），实际 swarm 实现在 teammate tools 中
+- **功能**: 多 agent 协作，需额外设置 `--agent-teams` 或 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
+- **效果**: 允许创建和管理 agent 团队
+- **风险**: 无（kill switch 默认就是 true）
+
+### P0-5. Token 高效 JSON 工具格式
+- **Gate**: `tengu_amber_json_tools` → `true`
+- **编译 flag**: 无（已内置）
+- **代码量**: betas.ts 中几行 gate 检查
+- **功能**: 启用 FC v3 格式，减少约 4.5% 的输出 token
+- **效果**: 省钱
+- **风险**: 低（需要模型支持该 beta header）
+
+### P0-6. Ultrathink 扩展思考
+- **Gate**: `tengu_turtle_carbon` → `true`（默认已 `true`，kill switch）
+- **编译 flag**: 无
+- **功能**: 通过关键词触发扩展思考模式
+- **效果**: 已默认启用，确保不被远程关闭即可
+- **风险**: 无
+
+### P0-7. 即时模型切换
+- **Gate**: `tengu_immediate_model_command` → `true`
+- **编译 flag**: 无
+- **功能**: 在 query 运行过程中即时执行 `/model`、`/fast`、`/effort` 命令
+- **效果**: 无需等当前任务完成就能切换
+- **风险**: 低
+
+---
+
+## 优先级 P1：需要 Claude API 的功能（有 API key 即可用）
+
+这些功能需要调用 Claude API（使用 forked subagent 或 queryModel），有订阅即可。
+
+### P1-1. 会话记忆
+- **Gate**: `tengu_session_memory` → `true`（配置：`tengu_sm_config` → `{}`）
+- **编译 flag**: 无（已内置）
+- **代码量**: 1127 行，完整实现
+- **功能**: 跨会话上下文持久化。用 forked agent 定期提取会话笔记到 markdown 文件
+- **效果**: Claude 记住跨会话的工作上下文
+- **依赖**: Claude API（forked subagent）
+- **风险**: 低（额外 API token 消耗）
+
+### P1-2. 自动记忆提取
+- **Gate**: `tengu_passport_quail` → `true`（相关：`tengu_moth_copse`、`tengu_coral_fern`）
+- **编译 flag**: `EXTRACT_MEMORIES`（需新增）
+- **代码量**: 616 行，完整实现
+- **功能**: 对话中自动提取持久记忆到 `~/.claude/projects/<path>/memory/`
+- **效果**: 自动构建项目知识库
+- **依赖**: Claude API（forked subagent）
+- **风险**: 低
+
+### P1-3. 提示建议
+- **Gate**: `tengu_chomp_inflection` → `true`
+- **编译 flag**: 无（已内置）
+- **代码量**: 525 行，完整实现
+- **功能**: 自动生成下一步操作建议，带投机预取（speculation prefetch）
+- **效果**: 更流畅的交互体验
+- **依赖**: Claude API（forked subagent）
+- **风险**: 低（额外 API 消耗，但有缓存感知）
+
+### P1-4. 验证代理
+- **Gate**: `tengu_hive_evidence` → `true`
+- **编译 flag**: `VERIFICATION_AGENT`（需新增）
+- **代码量**: 153 行（agent 定义），完整实现
+- **功能**: 对抗性验证 agent，主动尝试打破你的实现（只读模式）
+- **效果**: 自动化代码验证
+- **依赖**: Claude API（subagent）
+- **风险**: 低（只读，不修改代码）
+
+### P1-5. Brief 模式
+- **Gate**: `tengu_kairos_brief` → `true`
+- **编译 flag**: `KAIROS` 或 `KAIROS_BRIEF`（需新增）
+- **代码量**: 335 行，完整实现
+- **功能**: `/brief` 命令切换精简输出模式
+- **效果**: 减少冗余输出
+- **依赖**: Claude API
+- **风险**: 低
+
+### P1-6. 离开摘要
+- **Gate**: `tengu_sedge_lantern` → `true`
+- **编译 flag**: `AWAY_SUMMARY`（需新增）
+- **代码量**: 176 行，完整实现
+- **功能**: 离开终端 5 分钟后返回时自动总结期间发生了什么
+- **效果**: 快速恢复上下文
+- **依赖**: Claude API + 终端焦点事件支持
+- **风险**: 低
+
+### P1-7. 自动梦境
+- **Gate**: `tengu_onyx_plover` → `{"enabled": true}`
+- **编译 flag**: 无（已内置，但检查 auto-memory 是否启用）
+- **代码量**: 349 行，完整实现
+- **功能**: 后台自动整理/巩固记忆（等同于自动执行 `/dream`）
+- **效果**: 记忆自动保持整洁有序
+- **依赖**: Claude API（forked subagent）+ auto-memory 启用
+- **风险**: 低
+
+### P1-8. 空闲返回提示
+- **Gate**: `tengu_willow_mode` → `"dialog"` 或 `"hint"`
+- **编译 flag**: 无
+- **功能**: 对话太大且缓存过期时，提示用户开新会话
+- **效果**: 避免在过期缓存上浪费 token
+- **风险**: 无
+
+---
+
+## 优先级 P2：增强型功能（提升体验但非必须）
+
+### P2-1. MCP 指令增量传输
+- **Gate**: `tengu_basalt_3kr` → `true`
+- **功能**: 只发送变化的 MCP 指令而非全量
+- **效果**: 减少 token 消耗
+- **风险**: 低
+
+### P2-2. 叶剪枝优化
+- **Gate**: `tengu_pebble_leaf_prune` → `true`
+- **功能**: 会话存储中移除死胡同消息分支
+- **效果**: 减少存储和加载时间
+- **风险**: 低
+
+### P2-3. 消息合并
+- **Gate**: `tengu_chair_sermon` → `true`
+- **功能**: 合并相邻的 tool_result + text 块
+- **效果**: 减少 token 消耗
+- **风险**: 低
+
+### P2-4. 深度链接
+- **Gate**: `tengu_lodestone_enabled` → `true`
+- **功能**: 注册 `claude://` URL 协议处理器
+- **效果**: 可从浏览器直接打开 Claude Code
+- **风险**: 低
+
+### P2-5. Agent 自动转后台
+- **Gate**: `tengu_auto_background_agents` → `true`
+- **功能**: Agent 任务运行 120s 后自动转为后台
+- **效果**: 不再阻塞主交互
+- **风险**: 低
+
+### P2-6. 细粒度工具状态
+- **Gate**: `tengu_fgts` → `true`
+- **功能**: 系统提示中包含细粒度工具状态信息
+- **效果**: 模型更好地理解工具可用性
+- **风险**: 低
+
+### P2-7. 文件操作 git diff
+- **Gate**: `tengu_quartz_lantern` → `true`
+- **功能**: 文件写入/编辑时计算 git diff（仅远程会话）
+- **效果**: 更好的变更追踪
+- **风险**: 低
+
+---
+
+## 优先级 P3：需要自建服务或 Anthropic OAuth
+
+### P3-1. 团队记忆
+- **Gate**: `tengu_herring_clock` → `true`
+- **编译 flag**: `TEAMMEM`（需新增）
+- **代码量**: 1180+ 行，完整实现
+- **功能**: 跨 agent 共享记忆，同步到 Anthropic API
+- **依赖**: Anthropic OAuth + GitHub remote
+- **状态**: 需要 Anthropic 的 `/api/claude_code/team_memory` 端点
+- **可行性**: 除非自建兼容 API，否则无法使用
+
+### P3-2. 设置同步
+- **Gate**: `tengu_enable_settings_sync_push` + `tengu_strap_foyer` → `true`
+- **编译 flag**: `UPLOAD_USER_SETTINGS` / `DOWNLOAD_USER_SETTINGS`（需新增）
+- **代码量**: 582 行，完整实现
+- **功能**: 跨设备设置同步
+- **依赖**: Anthropic OAuth + `/api/claude_code/user_settings`
+- **可行性**: 同上
+
+### P3-3. Bridge 远程控制
+- **Gate**: `tengu_ccr_bridge` → `true`（已有编译 flag `BRIDGE_MODE` dev 模式启用）
+- **代码量**: 12,619 行，完整实现
+- **功能**: claude.ai 网页端远程控制 CLI
+- **依赖**: claude.ai 订阅 + WebSocket 后端
+- **可行性**: 需要 Anthropic 的 CCR 后端
+
+### P3-4. 远程定时 Agent
+- **Gate**: `tengu_surreal_dali` → `true`
+- **功能**: 创建在远程执行的定时 agent
+- **依赖**: Anthropic CCR 基础设施
+- **可行性**: 需要远程服务
+
+---
+
+## Kill Switch 清单（确保不被远程关闭）
+
+这些 gate 默认为 `true`，是 kill switch。应确保它们保持 `true`：
+
+| Gate | 默认 | 控制什么 |
+|---|---|---|
+| `tengu_turtle_carbon` | `true` | Ultrathink 扩展思考 |
+| `tengu_amber_stoat` | `true` | 内置 Explore/Plan agent |
+| `tengu_amber_flint` | `true` | Agent 团队/Swarm |
+| `tengu_slim_subagent_claudemd` | `true` | 子 agent 精简 CLAUDE.md |
+| `tengu_birch_trellis` | `true` | tree-sitter bash 安全分析 |
+| `tengu_collage_kaleidoscope` | `true` | macOS 剪贴板图片读取 |
+| `tengu_compact_cache_prefix` | `true` | 压缩时复用 prompt cache |
+| `tengu_kairos_cron_durable` | `true` | 持久化 cron 任务 |
+| `tengu_attribution_header` | `true` | API 请求署名 |
+| `tengu_slate_prism` | `true` | Agent 进度摘要 |
+
+---
+
+## 需要新增的编译 flag
+
+以下编译时 flag 尚未在 `build.ts` / `scripts/dev.ts` 中启用，但功能代码完整：
+
+| Flag | 用于 | 优先级 |
+|---|---|---|
+| `AGENT_TRIGGERS` | 定时任务系统（P0-3） | P0 |
+| `EXTRACT_MEMORIES` | 自动记忆提取（P1-2） | P1 |
+| `VERIFICATION_AGENT` | 验证代理（P1-4） | P1 |
+| `KAIROS` 或 `KAIROS_BRIEF` | Brief 模式（P1-5） | P1 |
+| `AWAY_SUMMARY` | 离开摘要（P1-6） | P1 |
+| `TEAMMEM` | 团队记忆（P3-1） | P3 |
+
+---
+
+## 实施路线图
+
+### Phase 1：硬编码 P0 纯本地 gate（最快见效）
+1. 在 growthbook.ts 添加默认值映射
+2. 在 build.ts / dev.ts 添加 `AGENT_TRIGGERS` 编译 flag
+3. 验证 7 个 P0 功能正常工作
+4. 预计工作量：1-2 小时
+
+### Phase 2：启用 P1 API 依赖功能
+1. 添加编译 flag：`EXTRACT_MEMORIES`、`VERIFICATION_AGENT`、`KAIROS_BRIEF`、`AWAY_SUMMARY`
+2. 添加 P1 gate 默认值
+3. 验证 8 个 P1 功能正常工作
+4. 预计工作量：2-3 小时
+
+### Phase 3：评估自建 GrowthBook（可选）
+1. Docker 部署 GrowthBook 服务器
+2. 迁移硬编码值到 GrowthBook 后台管理
+3. 获得 Web UI 管理所有 flag 的能力
+4. 预计工作量：半天
+
+### Phase 4：评估远程功能（可选）
+1. 研究是否可以使用 Anthropic OAuth
+2. 评估团队记忆、设置同步的自建可行性
+3. 预计工作量：待评估
+
+---
+
+## 隐私说明
+
+### 硬编码绕过（方案 A）
+- **零数据外发**
+- GrowthBook SDK 不启动
+- 完全离线运行
+
+### 自建 GrowthBook（方案 B）
+- 数据仅发送到你自己的服务器
+- Anthropic 无法获取任何数据
+- 可通过 Web UI 实时管理所有 flag
+
+### 恢复原生 1P（方案 C）
+- 会发送使用统计到 `api.anthropic.com`
+- **不发送**：代码、对话内容、API key
+- **会发送**：邮箱、设备 ID、机器指纹、仓库哈希、订阅类型
+- 可用 `DISABLE_TELEMETRY=1` 关闭遥测（但同时关闭 GrowthBook）

docs/features/kairos.md

@@ -0,0 +1,182 @@
+# KAIROS — 常驻助手模式
+
+> Feature Flag: `FEATURE_KAIROS=1`（及子 Feature）
+> 实现状态：核心框架完整，部分子模块为 stub；proactive/sleep 节奏控制已可用
+> 引用数：154（全库最大）
+
+## 一、功能概述
+
+KAIROS 将 Claude Code CLI 从"问答工具"转变为"常驻助手"。开启后，CLI 持续运行在后台，支持：
+
+- **持久化 bridge 会话**：跨终端重启复用 session，通过 Anthropic OAuth 连接 claude.ai
+- **后台执行任务**：用户离开终端时继续工作（配合 PROACTIVE feature）
+- **推送通知到移动端**：任务完成或需要输入时推送（配合 `KAIROS_PUSH_NOTIFICATION`）
+- **每日记忆日志**：自动记录和回顾工作内容（配合 `KAIROS_DREAM`）
+- **外部频道消息接入**：Slack/Discord/Telegram 消息转发到 CLI（配合 `KAIROS_CHANNELS`）
+- **结构化 Brief 输出**：通过 BriefTool 输出结构化消息（配合 `KAIROS_BRIEF`）
+
+### 子 Feature 依赖关系
+
+```
+KAIROS (主开关)
+├── KAIROS_BRIEF (BriefTool, 结构化输出)
+├── KAIROS_CHANNELS (外部频道消息)
+├── KAIROS_PUSH_NOTIFICATION (移动端推送)
+├── KAIROS_GITHUB_WEBHOOKS (GitHub PR webhook)
+└── KAIROS_DREAM (记忆蒸馏)
+```
+
+**注意**：PROACTIVE 与 KAIROS 强绑定。所有代码检查都是 `feature('PROACTIVE') || feature('KAIROS')`，即 KAIROS 开启时自动获得 proactive 能力。
+
+## 二、系统提示
+
+KAIROS 在系统提示中注入两大段落：
+
+### 2.1 Brief 段落 (`getBriefSection`)
+
+文件：`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:864-918`
+
+当 `feature('PROACTIVE') || feature('KAIROS')` 且 `isProactiveActive()` 时注入。核心行为指令：
+
+- **Tick 驱动**：通过 `<tick_tag>` prompt 保持存活，每个 tick 包含用户当前本地时间
+- **节奏控制**：使用 `SleepTool` 控制等待间隔（prompt cache 5 分钟过期）
+- **空操作时必须 Sleep**：禁止输出 "still waiting" 类文本（浪费 turn 和 token）
+- **偏向行动**：读文件、搜索代码、修改文件、commit — 都不需询问
+- **终端焦点感知**：`terminalFocus` 字段指示用户是否在看终端
+  - Unfocused → 高度自主行动
+  - Focused → 更协作，展示选择
+
+## 三、实现架构
+
+### 3.1 核心模块
+
+| 模块 | 文件 | 状态 | 职责 |
+|------|------|------|------|
+| Assistant 入口 | `src/assistant/index.ts` | Stub | `isAssistantMode()`、`initializeAssistantTeam()` |
+| Session 发现 | `src/assistant/sessionDiscovery.ts` | Stub | 发现可用 bridge session |
+| Session 历史 | `src/assistant/sessionHistory.ts` | Stub | 持久化 session 历史 |
+| Gate 控制 | `src/assistant/gate.ts` | Stub | GrowthBook 门控检查 |
+| Session 选择器 | `src/assistant/AssistantSessionChooser.ts` | Stub | UI 选择 session |
+| BriefTool | `src/tools/BriefTool/` | Stub | 结构化消息输出工具 |
+| Channel Notification | `src/services/mcp/channelNotification.ts` | Stub | 外部频道消息接入 |
+| Dream Task | `src/components/tasks/src/tasks/DreamTask/` | Stub | 记忆蒸馏任务 |
+| Memory Directory | `src/memdir/memdir.ts` | Stub | 记忆目录管理 |
+
+### 3.2 SleepTool（与 Proactive 共享）
+
+文件：`src/tools/SleepTool/prompt.ts`
+
+SleepTool 是 KAIROS/Proactive 的节奏控制核心。工具描述让模型理解"休眠"概念：
+- 工具名：`Sleep`
+- 功能：等待指定时间后响应 tick prompt；若队列出现新工作或 proactive 被关闭，会提前唤醒
+- 与 `<tick_tag>` 配合实现心跳式自主工作
+- 远程控制 surfaces 可通过 `automation_state` 看到 `standby` / `sleeping` 两种状态
+
+### 3.3 Bridge 集成
+
+KAIROS 通过 Bridge Mode（`src/bridge/`）连接到 claude.ai 服务器：
+
+```
+claude.ai web/app
+      │
+      ▼ (HTTPS long-poll)
+┌──────────────────────┐
+│  Bridge API Client   │  src/bridge/bridgeApi.ts
+│  (register/poll/     │
+│   acknowledge)       │
+└──────────┬───────────┘
+           │
+           ▼
+┌──────────────────────┐
+│  Session Runner      │  src/bridge/sessionRunner.ts
+│  (创建/恢复 REPL)     │
+└──────────┬───────────┘
+           │
+           ▼
+┌──────────────────────┐
+│  REPL + Proactive    │  Tick 驱动自主工作
+│  Tick Loop           │
+└──────────────────────┘
+```
+
+### 3.4 数据流
+
+```
+用户从 claude.ai 发送消息
+         │
+         ▼
+Bridge pollForWork() 收到 WorkResponse
+         │
+         ▼
+acknowledgeWork() 确认接收
+         │
+         ▼
+sessionRunner 创建/恢复 REPL session
+         │
+         ▼
+用户消息注入到 REPL 对话
+         │
+         ▼
+模型处理 → 工具调用 → BriefTool 结构化输出
+         │
+         ▼
+结果通过 Bridge API 回传到 claude.ai
+```
+
+## 四、关键设计决策
+
+1. **Tick 驱动而非事件驱动**：模型通过 SleepTool 自行控制唤醒频率，而非外部事件推送。简化架构但增加 API 调用开销
+2. **KAIROS ⊃ PROACTIVE**：所有 proactive 检查都包含 KAIROS，无需同时开启两个 flag
+3. **Brief 显示/行为分离**：`/brief` toggle 只控制 UI 过滤，模型始终可以使用 BriefTool
+4. **Terminal Focus 感知**：模型根据用户是否在看终端自动调节自主程度
+5. **GrowthBook 门控**：部分功能（如推送通知）即使 feature flag 开启还需要服务端 GrowthBook 开关
+
+## 五、使用方式
+
+```bash
+# 最小启用（常驻助手 + Brief）
+FEATURE_KAIROS=1 FEATURE_KAIROS_BRIEF=1 bun run dev
+
+# 全功能启用
+FEATURE_KAIROS=1 \
+FEATURE_KAIROS_BRIEF=1 \
+FEATURE_KAIROS_CHANNELS=1 \
+FEATURE_KAIROS_PUSH_NOTIFICATION=1 \
+FEATURE_KAIROS_GITHUB_WEBHOOKS=1 \
+FEATURE_PROACTIVE=1 \
+bun run dev
+
+# 配合 Token Budget 使用
+FEATURE_KAIROS=1 FEATURE_TOKEN_BUDGET=1 bun run dev
+```
+
+## 六、外部依赖
+
+- **Anthropic OAuth**：必须使用 claude.ai 订阅登录（非 API key）
+- **GrowthBook**：服务端特性门控（`tengu_ccr_bridge` 等）
+- **Bridge API**：`/v1/environments/bridge` 系列端点
+
+## 七、文件索引
+
+| 文件 | 行数 | 职责 |
+|------|------|------|
+| `src/assistant/index.ts` | 9 | Assistant 模块入口（stub） |
+| `src/assistant/gate.ts` | — | GrowthBook 门控（stub） |
+| `src/assistant/sessionDiscovery.ts` | — | Session 发现（stub） |
+| `src/assistant/sessionHistory.ts` | — | Session 历史（stub） |
+| `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:557,847-918` | 72 | 系统提示注入 |
+| `src/components/tasks/src/tasks/DreamTask/` | 3 | Dream 任务（stub） |
+| `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

@@ -1,9 +1,3 @@
----
-title: "Langfuse 监控集成"
-description: "Agent loop 实时监控，可视化每次 API 调用、token 消耗、工具执行链路，可一键转化为训练数据集。"
-keywords: ["Langfuse", "OpenTelemetry", "LLM 追踪", "可观测性", "数据脱敏"]
----
-
 # Langfuse 监控集成
 
 > 实现状态：已完成，通过环境变量启用

docs/features/mcp-skills.md

@@ -0,0 +1,118 @@
+# MCP_SKILLS — MCP 技能发现
+
+> Feature Flag: `FEATURE_MCP_SKILLS=1`
+> 实现状态：功能性实现（config 门控筛选器完整，核心 fetcher 为 stub）
+> 引用数：9
+
+## 一、功能概述
+
+MCP_SKILLS 将 MCP 服务器暴露的资源（`skill://` URI 方案）发现并转换为可调用的技能命令。MCP 服务器可以同时提供 tools、prompts 和 resources；启用此 feature 后，带有 `skill://` URI 的资源被识别为技能。
+
+### 核心特性
+
+- **自动发现**：MCP 服务器连接时自动获取 `skill://` 资源
+- **命令转换**：将 MCP 资源转换为 `prompt` 类型的 Command 对象
+- **实时刷新**：prompts/resources 列表变化时重新获取技能
+- **缓存一致性**：连接关闭时清除技能缓存
+
+## 二、实现架构
+
+### 2.1 数据流
+
+```
+MCP Server 连接
+      │
+      ▼
+client.ts: connectToServer / setupMcpClientConnections
+  ├── fetchToolsForClient     (MCP tools)
+  ├── fetchCommandsForClient   (MCP prompts → Command 对象)
+  ├── fetchMcpSkillsForClient  (MCP skill:// 资源 → Command 对象) [MCP_SKILLS]
+  └── fetchResourcesForClient  (MCP resources)
+      │
+      ▼
+commands = [...mcpPrompts, ...mcpSkills]
+      │
+      ▼
+AppState.mcp.commands 更新
+      │
+      ▼
+getMcpSkillCommands() 过滤 → SkillTool 调用
+```
+
+### 2.2 技能筛选
+
+文件：`src/commands.ts:604-616`
+
+`getMcpSkillCommands(mcpCommands)` 过滤条件：
+
+```ts
+cmd.type === 'prompt'                  // 必须是 prompt 类型
+cmd.loadedFrom === 'mcp'               // 必须来自 MCP 服务器
+!cmd.disableModelInvocation            // 必须可由模型调用
+feature('MCP_SKILLS')                  // feature flag 必须开启
+```
+
+### 2.3 条件加载
+
+文件：`src/services/mcp/client.ts:129-133`
+
+`fetchMcpSkillsForClient` 通过 `require()` 条件加载，feature flag 关闭时不加载任何模块：
+
+```ts
+const fetchMcpSkillsForClient = feature('MCP_SKILLS')
+  ? require('../../skills/mcpSkills.js').fetchMcpSkillsForClient
+  : null
+```
+
+### 2.4 缓存管理
+
+技能获取函数维护 `.cache`（Map），在以下时机清除：
+
+| 事件 | 行为 |
+|------|------|
+| 连接关闭 | 清除该 client 的技能缓存 |
+| `disconnectMcpServer()` | 清除技能缓存 |
+| `prompts/list_changed` 通知 | 刷新 prompts + 并行获取技能 |
+| `resources/list_changed` 通知 | 刷新 resources + prompts + 技能 |
+
+### 2.5 集成点
+
+| 文件 | 行 | 说明 |
+|------|------|------|
+| `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 变化） |
+
+## 三、关键设计决策
+
+1. **Feature gate 隔离**：`feature('MCP_SKILLS')` 守护条件 `require()` 和所有调用点。关闭时无模块加载、无获取操作
+2. **资源到技能映射**：技能从 MCP 服务器的 `skill://` URI 资源中发现。`fetchMcpSkillsForClient` 负责转换（当前为 stub）
+3. **循环依赖避免**：`mcpSkillBuilders.ts` 作为依赖图叶节点，避免 `client.ts ↔ mcpSkills.ts ↔ loadSkillsDir.ts` 循环
+4. **服务器能力检查**：技能获取还需要 MCP 服务器支持 resources (`!!client.capabilities?.resources`)
+
+## 四、使用方式
+
+```bash
+# 启用 feature
+FEATURE_MCP_SKILLS=1 bun run dev
+
+# 前提条件：
+# 1. 配置了支持 skill:// 资源的 MCP 服务器
+# 2. MCP 服务器声明了 resources 能力
+```
+
+## 五、需要补全的内容
+
+| 文件 | 状态 | 需要实现 |
+|------|------|---------|
+| `src/skills/mcpSkills.ts` | Stub | `fetchMcpSkillsForClient()` — 从 MCP 资源列表中筛选 `skill://` URI 并转换为 Command 对象 |
+| `src/skills/mcpSkillBuilders.ts` | Stub | 技能构建器注册（避免循环依赖） |
+
+## 六、文件索引
+
+| 文件 | 职责 |
+|------|------|
+| `src/commands.ts:547-608` | 技能命令过滤 |
+| `src/services/mcp/client.ts:117-2358` | 技能获取 + 缓存管理 |
+| `src/services/mcp/useManageMCPConnections.ts` | 实时刷新 |
+| `src/skills/mcpSkills.ts` | 核心转换逻辑（stub） |

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

@@ -0,0 +1,113 @@
+# PROACTIVE — 主动模式
+
+> Feature Flag: `FEATURE_PROACTIVE=1`（与 `FEATURE_KAIROS=1` 共享功能）
+> 实现状态：核心循环与 SleepTool 已落地，部分外围文档仍在补齐
+> 引用数：37
+
+## 一、功能概述
+
+PROACTIVE 实现 Tick 驱动的自主代理。CLI 在用户不输入时也能持续工作：定时唤醒执行任务，配合 SleepTool 控制节奏。适用于长时间运行的后台任务（等待 CI、监控文件变化、定时检查等）。
+
+### 与 KAIROS 的关系
+
+所有代码检查都是 `feature('PROACTIVE') || feature('KAIROS')`，即：
+- 单独开 `FEATURE_PROACTIVE=1` → 获得 proactive 能力
+- 单独开 `FEATURE_KAIROS=1` → 自动获得 proactive 能力
+- 两者都开 → 相同效果（不重复）
+
+## 二、实现架构
+
+### 2.1 模块状态
+
+| 模块 | 文件 | 状态 | 说明 |
+|------|------|------|------|
+| 核心逻辑 | `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 驱动、standby/sleeping 状态、页脚与 bridge automation metadata 上报 |
+| 系统提示 | `src/constants/prompts.ts:864-918` | **完整** | 自主工作行为指令（~55 行详细 prompt） |
+| 远控状态镜像 | `src/utils/sessionState.ts` | **已实现** | 向 remote-control/CCR 暴露 `automation_state` 元数据 |
+
+### 2.2 系统提示内容
+
+`getProactiveSection()` 注入的自主工作指令包含：
+
+| 章节 | 内容 |
+|------|------|
+| Tick 驱动 | `<tick_tag>` prompt 保持存活，包含用户本地时间 |
+| 节奏控制 | SleepTool 控制等待间隔，prompt cache 5 分钟过期 |
+| 空操作规则 | 无事可做时**必须**调用 Sleep，禁止输出 "still waiting" |
+| 首次唤醒 | 简短问候，等待方向（不主动探索） |
+| 后续唤醒 | 寻找有用工作：调查、验证、检查（不 spam 用户） |
+| 偏向行动 | 读文件、搜索代码、commit — 不需询问 |
+| 终端焦点 | `terminalFocus` 字段调节自主程度 |
+
+### 2.3 数据流
+
+```
+activateProactive()
+      │
+      ▼
+Tick 调度器启动
+      │
+      ├── 定时生成 <tick_tag> 消息
+      │   ├── 包含用户当前本地时间
+      │   └── 注入到对话流（sessionStorage）
+      │
+      ▼
+模型处理 tick
+      │
+      ├── 有事可做 → 使用工具执行 → 可能再次 Sleep
+      └── 无事可做 → 必须调用 SleepTool
+      │
+      ▼
+SleepTool 等待
+      │
+      ├── 用户插入新工作 / 队列中有命令 → 立即唤醒
+      ├── proactive 被关闭 → 立即中断
+      └── 进入休眠时向远端 surfaces 上报 `automation_state = sleeping`
+      │
+      ▼
+下一个 tick 到达
+```
+
+## 三、当前行为补充
+
+- `standby`：proactive 已开启，当前没有执行中的 turn，且已调度下一个 tick。
+- `sleeping`：模型显式调用 `SleepTool` 进入等待窗口。
+- remote-control/CCR 通过 `external_metadata.automation_state` 接收这两个状态，用于 Web UI 的 Autopilot 状态显示。
+- `SleepTool` 现在不是纯定时器；它会在共享命令队列出现新工作时提前醒来。
+
+## 四、关键设计决策
+
+1. **Tick 驱动**：模型通过 SleepTool 自行控制唤醒频率，不是外部事件推送
+2. **空操作必须 Sleep**：防止 "still waiting" 类空消息浪费 turn 和 token
+3. **Prompt cache 考量**：SleepTool 提示中提到 cache 5 分钟过期，建议平衡等待时间
+4. **Terminal Focus 感知**：模型根据用户是否在看终端调整自主程度
+
+## 五、使用方式
+
+```bash
+# 单独启用 proactive
+FEATURE_PROACTIVE=1 bun run dev
+
+# 通过 KAIROS 间接启用
+FEATURE_KAIROS=1 bun run dev
+
+# 组合使用
+FEATURE_PROACTIVE=1 FEATURE_KAIROS=1 FEATURE_KAIROS_BRIEF=1 bun run dev
+```
+
+## 六、文件索引
+
+| 文件 | 职责 |
+|------|------|
+| `src/proactive/index.ts` | 核心逻辑与 next-tick 状态 |
+| `src/tools/SleepTool/prompt.ts` | SleepTool 工具提示 |
+| `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

@@ -1,9 +1,3 @@
----
-title: "Remote Control 私有化部署"
-description: "Docker 自托管 RCS，含 Web UI 控制面板、ACP agent 接入、JWT 认证。"
-keywords: ["Remote Control Server", "Docker 部署", "ACP agent", "JWT 认证", "Web UI 控制面板"]
----
-
 # Remote Control Server 私有化部署指南
 
 本指南说明如何将 Remote Control Server (RCS) 部署到私有环境，并通过 Claude Code CLI 连接使用。
@@ -231,14 +225,9 @@ acp-link ◄──ACP relay──► RCS ◄──Web UI WS──► 浏览器
 | `src/transport/acp-relay-handler.ts` | 前端 WS → acp-link 透传 + EventBus inbound 转发 |
 | `src/transport/acp-sse-writer.ts` | SSE event stream 供外部消费者订阅 |
 
-ACP 的 agents、channel groups、relay 和 channel-group SSE 端点都要求有效
-API key。浏览器 `EventSource` 不能发送 `Authorization` header，外部订阅
-`/acp/channel-groups/:id/events` 时需要使用 `fetch` + `ReadableStream` 并带
-`Authorization: Bearer <api-key>`。
-
 ### acp-link 连接
 
-详见 [acp-link 文档](../agents/acp-link.md)。
+详见 [acp-link 文档](./acp-link.md)。
 
 ```bash
 # 在 RCS 环境中启动 acp-link

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/teammem.md

@@ -0,0 +1,167 @@
+# TEAMMEM — 团队共享记忆
+
+> Feature Flag: `FEATURE_TEAMMEM=1`
+> 实现状态：完整可用（需要 Anthropic OAuth + GitHub remote）
+> 引用数：51
+
+## 一、功能概述
+
+TEAMMEM 实现基于 GitHub 仓库的团队共享记忆系统。`memory/team/` 目录中的文件双向同步到 Anthropic 服务器，团队所有认证成员可共享项目知识。
+
+### 核心特性
+
+- **增量同步**：只上传内容哈希变化的文件（delta upload）
+- **冲突解决**：基于 ETag 的乐观锁 + 412 冲突重试
+- **密钥扫描**：上传前检测并跳过包含密钥的文件（PSR M22174）
+- **路径穿越防护**：所有写入路径验证在 `memory/team/` 边界内
+- **分批上传**：自动拆分超过 200KB 的 PUT 请求避免网关拒绝
+
+## 二、用户交互
+
+### 同步行为
+
+| 事件 | 行为 |
+|------|------|
+| 项目启动 | 自动 pull 团队记忆到 `memory/team/` |
+| 本地文件编辑 | watcher 检测变更，自动 push |
+| 服务端更新 | 下次 pull 时覆盖本地（server-wins） |
+| 密钥检测 | 跳过该文件，记录警告，不阻止其他文件同步 |
+
+### API 端点
+
+```
+GET  /api/claude_code/team_memory?repo={owner/repo}             → 完整数据 + entryChecksums
+GET  /api/claude_code/team_memory?repo={owner/repo}&view=hashes → 仅 checksums（冲突解决用）
+PUT  /api/claude_code/team_memory?repo={owner/repo}             → 上传 entries（upsert 语义）
+```
+
+## 三、实现架构
+
+### 3.1 同步状态
+
+```ts
+type SyncState = {
+  lastKnownChecksum: string | null    // ETag 条件请求
+  serverChecksums: Map<string, string> // sha256:<hex> 逐文件哈希
+  serverMaxEntries: number | null      // 从 413 学习的服务端容量
+}
+```
+
+### 3.2 Pull 流程（Server → Local）
+
+文件：`src/services/teamMemorySync/index.ts:770-867`
+
+```
+pullTeamMemory(state)
+      │
+      ▼
+检查 OAuth + GitHub remote
+      │
+      ▼
+fetchTeamMemory(state, repo, etag)
+  ├── 304 Not Modified → 返回（无变化）
+  ├── 404 → 返回（服务端无数据）
+  └── 200 → 解析 TeamMemoryData
+      │
+      ▼
+刷新 serverChecksums（per-key hashes）
+      │
+      ▼
+writeRemoteEntriesToLocal(entries)
+  ├── 路径穿越验证（validateTeamMemKey）
+  ├── 文件大小检查（> 250KB 跳过）
+  ├── 内容比较（相同则跳过写入）
+  └── 并行写入（Promise.all）
+```
+
+### 3.3 Push 流程（Local → Server）
+
+文件：`src/services/teamMemorySync/index.ts:889-1146`
+
+```
+pushTeamMemory(state)
+      │
+      ▼
+readLocalTeamMemory(maxEntries)
+  ├── 递归扫描 memory/team/ 目录
+  ├── 跳过超大文件（> 250KB）
+  ├── 密钥扫描（scanForSecrets，gitleaks 规则）
+  └── 按 serverMaxEntries 截断（如果已知）
+      │
+      ▼
+计算 delta = 本地文件 - serverChecksums
+  （只包含哈希不同的文件）
+      │
+      ▼
+batchDeltaByBytes(delta)
+  （拆分为 ≤200KB 的批次）
+      │
+      ▼
+逐批 uploadTeamMemory(state, repo, batch, etag)
+  ├── 200 成功 → 更新 serverChecksums
+  ├── 412 冲突 → fetchTeamMemoryHashes() 刷新 checksums
+  │              → 重试 delta 计算（最多 2 次）
+  └── 413 超容量 → 学习 serverMaxEntries
+```
+
+### 3.4 密钥扫描
+
+文件：`src/services/teamMemorySync/secretScanner.ts`
+
+使用 gitleaks 规则模式扫描文件内容。检测到密钥时：
+- 跳过该文件（不上传）
+- 记录 `tengu_team_mem_secret_skipped` 事件（仅记录规则 ID，不记录值）
+- 不阻止其他文件同步
+
+### 3.5 文件监视
+
+文件：`src/services/teamMemorySync/watcher.ts`
+
+监视 `memory/team/` 目录变更，触发自动 push。抑制由 pull 写入引起的假变更。
+
+### 3.6 路径安全
+
+文件：`src/memdir/teamMemPaths.ts`
+
+- `validateTeamMemKey(relPath)` — 验证相对路径不超出 `memory/team/` 边界
+- `getTeamMemPath()` — 返回 team memory 根目录路径
+
+## 四、关键设计决策
+
+1. **Server-wins on pull, Local-wins on push**：pull 时服务端内容覆盖本地；push 时本地编辑覆盖服务端。本地用户正在编辑，不应被静默丢弃
+2. **Delta upload**：只上传哈希变化的条目，节省带宽。首次 push 为全量，后续增量
+3. **分批 PUT**：单次 PUT ≤200KB，避免 API 网关（~256-512KB）拒绝。每批独立 upsert，部分失败不影响已提交批次
+4. **密钥扫描在上传前**：PSR M22174 要求密钥永不离开本机。扫描在 `readLocalTeamMemory` 中执行，密钥文件不进入上传集
+5. **ETag 乐观锁**：push 使用 `If-Match` header。412 时 probe `?view=hashes`（只获取 checksums，不下载内容），刷新后重试
+6. **服务端容量动态学习**：不假设客户端容量上限，从 413 的 `extra_details.max_entries` 学习
+
+## 五、使用方式
+
+```bash
+# 启用 feature
+FEATURE_TEAMMEM=1 bun run dev
+
+# 前提条件：
+# 1. 已通过 Anthropic OAuth 登录
+# 2. 项目有 GitHub remote（git remote -v 显示 origin）
+# 3. memory/team/ 目录自动创建
+```
+
+## 六、外部依赖
+
+| 依赖 | 说明 |
+|------|------|
+| Anthropic OAuth | first-party 认证 |
+| GitHub Remote | `getGithubRepo()` 获取 `owner/repo` 作为同步 scope |
+| Team Memory API | `/api/claude_code/team_memory` 端点 |
+
+## 七、文件索引
+
+| 文件 | 行数 | 职责 |
+|------|------|------|
+| `src/services/teamMemorySync/index.ts` | 1257 | 核心同步逻辑（pull/push/sync） |
+| `src/services/teamMemorySync/watcher.ts` | — | 文件监视 + 自动同步触发 |
+| `src/services/teamMemorySync/secretScanner.ts` | — | gitleaks 密钥扫描 |
+| `src/services/teamMemorySync/types.ts` | — | Zod schema + 类型定义 |
+| `src/services/teamMemorySync/teamMemSecretGuard.ts` | — | 密钥防护辅助 |
+| `src/memdir/teamMemPaths.ts` | — | 路径验证 + 目录管理 |

docs/features/tier3-stubs.md

@@ -0,0 +1,37 @@
+# Tier 3 — 纯 Stub / N/A 低优先级 Feature 概览
+
+> 本文档汇总所有 Tier 3 feature。这些功能要么是纯 Stub（所有函数返回空值），
+> 要么是 Anthropic 内部基础设施（N/A），要么是引用量极低的辅助功能。
+
+## 概览
+
+| Feature | 引用 | 状态 | 类别 | 简要说明 |
+|---------|------|------|------|---------|
+| 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+ 个）
+
+以下 feature 各只有 1 处引用，多为内部标记或实验性功能：
+
+UNATTENDED_RETRY, ULTRATHINK, TORCH, SLOW_OPERATION_LOGGING, SKILL_IMPROVEMENT,
+SELF_HOSTED_RUNNER, RUN_SKILL_GENERATOR, PERFETTO_TRACING, NATIVE_CLIENT_ATTESTATION,
+KAIROS_DREAM（见 kairos.md）, IS_LIBC_MUSL, IS_LIBC_GLIBC, DUMP_SYSTEM_PROMPT,
+COMPACTION_REMINDERS, CCR_REMOTE_SETUP, BYOC_ENVIRONMENT_RUNNER, BUILTIN_EXPLORE_PLAN_AGENTS,
+BUILDING_CLAUDE_APPS, ANTI_DISTILLATION_CC, AGENT_TRIGGERS, ABLATION_BASELINE
+
+## 优先级说明
+
+这些 feature 被列为 Tier 3 的原因：
+
+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

@@ -0,0 +1,198 @@
+# TOKEN_BUDGET — Token 预算自动持续模式
+
+> Feature Flag: `FEATURE_TOKEN_BUDGET=1`
+> 实现状态：完整可用
+
+## 一、功能概述
+
+TOKEN_BUDGET 让用户在 prompt 中指定一个 output token 预算目标（如 `+500k`、`spend 2M tokens`），Claude 会**自动持续工作**直到达到目标，无需用户反复按回车催促继续。
+
+适用于大型重构、批量修改、大规模代码生成等需要多轮工具调用的长任务。
+
+## 二、用户交互
+
+### 语法
+
+| 格式 | 示例 | 说明 |
+|------|------|------|
+| 简写（开头） | `+500k` | 输入开头直接写 |
+| 简写（结尾） | `帮我重构这个模块 +2m` | 输入末尾追加 |
+| 完整语法 | `spend 2M tokens` 或 `use 1B tokens` | 自然语言嵌入 |
+
+单位支持：`k`（千）、`m`（百万）、`b`（十亿），大小写不敏感。
+
+### UI 反馈
+
+- **输入框高亮**：输入包含预算语法时，对应文字会被高亮标记（`PromptInput.tsx` 通过 `findTokenBudgetPositions` 计算）
+- **Spinner 进度**：底部 spinner 显示实时进度，格式如：
+  - 未完成：`Target: 125,000 / 500,000 (25%) · ~2m 30s`
+  - 已完成：`Target: 510,000 used (500,000 min ✓)`
+  - 包含 ETA（基于当前 token 产出速率计算）
+
+## 三、实现架构
+
+### 数据流
+
+```
+用户输入 "+500k"
+     │
+     ▼
+┌─────────────────────────┐
+│  parseTokenBudget()     │  src/utils/tokenBudget.ts
+│  正则解析 → 500,000     │
+└────────┬────────────────┘
+         │
+         ▼
+┌─────────────────────────┐
+│  REPL.tsx               │  提交时调用
+│  snapshotOutputTokens   │  snapshotOutputTokensForTurn(500000)
+│  ForTurn(500000)        │  记录 turn 起始 token 数 + 预算
+└────────┬────────────────┘
+         │
+         ▼
+┌─────────────────────────┐
+│  query.ts 主循环        │  每轮结束后检查
+│  checkTokenBudget()     │  当前 output tokens vs 预算
+└────────┬────────────────┘
+         │
+    ┌────┴─────┐
+    │          │
+    ▼          ▼
+ continue    stop
+ (未达 90%)   (已达 90% 或收益递减)
+    │          │
+    ▼          ▼
+ 注入 nudge   正常结束
+ 消息继续     发送完成事件
+```
+
+### 核心模块
+
+#### 1. 解析层 — `src/utils/tokenBudget.ts`
+
+三个正则表达式解析用户输入：
+
+```
+SHORTHAND_START_RE = /^\s*\+(\d+(?:\.\d+)?)\s*(k|m|b)\b/i   // "+500k" 在开头
+SHORTHAND_END_RE   = /\s\+(\d+(?:\.\d+)?)\s*(k|m|b)\s*[.!?]?\s*$/i  // "+2m" 在结尾
+VERBOSE_RE         = /\b(?:use|spend)\s+(\d+(?:\.\d+)?)\s*(k|m|b)\s*tokens?\b/i  // "spend 2M tokens"
+```
+
+- `parseTokenBudget(text)` — 提取预算数值，返回 `number | null`
+- `findTokenBudgetPositions(text)` — 返回匹配位置数组，用于输入框高亮
+- `getBudgetContinuationMessage(pct, turnTokens, budget)` — 生成继续消息
+
+#### 2. 状态层 — `src/bootstrap/state.ts`
+
+模块级单例变量追踪当前 turn 的预算状态：
+
+```
+outputTokensAtTurnStart   — 本 turn 开始时的累计 output token 数
+currentTurnTokenBudget    — 本 turn 的预算目标（null 表示无预算）
+budgetContinuationCount   — 本 turn 已自动续接的次数
+```
+
+关键函数：
+- `getTotalOutputTokens()` — 从 `STATE.modelUsage` 汇总所有模型的 output tokens
+- `getTurnOutputTokens()` — `getTotalOutputTokens() - outputTokensAtTurnStart`
+- `snapshotOutputTokensForTurn(budget)` — 重置 turn 起点，设置新预算
+- `getCurrentTurnTokenBudget()` — 返回当前预算
+
+#### 3. 决策层 — `src/query/tokenBudget.ts`
+
+`checkTokenBudget(tracker, agentId, budget, globalTurnTokens)` 做出 continue/stop 决策：
+
+**继续条件**：
+- 不在子 agent 中（`agentId` 为空）
+- 预算存在且 > 0
+- 当前 token 未达预算的 **90%**
+- 非收益递减（连续 3 轮 nudge 后，每轮新增 < 500 tokens）
+
+**停止条件**：
+- 达到预算 90%
+- 收益递减（模型已经"做不动了"）
+- 子 agent 模式下直接跳过
+
+**收益递减检测**：`continuationCount >= 3` 且最近两次 nudge 的 delta 都 < 500 tokens。
+
+#### 4. 主循环集成 — `src/query.ts`
+
+```
+query() 函数内：
+  1. 创建 budgetTracker = createBudgetTracker()
+  2. 进入 while 循环
+  3. 每轮结束后调用 checkTokenBudget()
+  4. decision.action === 'continue' 时：
+     - 注入 meta user message（nudge）
+     - continue 回到循环顶部
+  5. decision.action === 'stop' 时：
+     - 记录完成事件（含 diminishingReturns 标记）
+     - 正常返回
+```
+
+#### 5. UI 层
+
+| 文件 | 职责 |
+|------|------|
+| `components/PromptInput/PromptInput.tsx:534` | 输入框中高亮预算语法 |
+| `components/Spinner.tsx:319-338` | spinner 显示进度百分比 + ETA |
+| `screens/REPL.tsx:2897` | 提交时解析预算并快照 |
+| `screens/REPL.tsx:2138` | 用户取消时清除预算 |
+| `screens/REPL.tsx:2963` | turn 结束时捕获预算信息用于显示 |
+
+#### 6. 系统提示 — `src/constants/prompts.ts:538-551`
+
+注入 `token_budget` section：
+
+> "When the user specifies a token target (e.g., '+500k', 'spend 2M tokens', 'use 1B tokens'), your output token count will be shown each turn. Keep working until you approach the target — plan your work to fill it productively. The target is a hard minimum, not a suggestion. If you stop early, the system will automatically continue you."
+
+注意：这段 prompt **无条件缓存**（不随预算开关变化），因为 "When the user specifies..." 的措辞在没有预算时是空操作。
+
+#### 7. API 附件 — `src/utils/attachments.ts:3830-3845`
+
+每轮 API 调用附带 `output_token_usage` attachment：
+
+```json
+{
+  "type": "output_token_usage",
+  "turn": 125000,     // 本 turn 产出
+  "session": 350000,  // 会话总产出
+  "budget": 500000    // 预算目标
+}
+```
+
+让模型能看到自己的进度。
+
+## 四、关键设计决策
+
+1. **90% 阈值而非 100%**：在 `COMPLETION_THRESHOLD = 0.9` 处停止，避免最后一轮 nudge 产生远超预算的 token
+2. **收益递减保护**：连续 3 轮 nudge 后如果每轮产出 < 500 tokens，判定模型已无实质进展，提前终止
+3. **子 agent 豁免**：AgentTool 内部的子任务不做预算检查，避免子任务重复触发续接
+4. **无条件缓存系统提示**：预算 prompt 始终注入（不随预算变化 toggle），避免每次切换预算导致 ~20K token 的 cache miss
+5. **用户取消清预算**：按 Escape 取消时调用 `snapshotOutputTokensForTurn(null)`，防止残留预算触发续接
+
+## 五、使用方式
+
+```bash
+# 启用 feature
+FEATURE_TOKEN_BUDGET=1 bun run dev
+
+# 在 prompt 中使用
+> +500k 重构所有测试文件
+> spend 2M tokens 把这个项目从 JS 迁移到 TS
+> 帮我写完整的 CRUD 模块 +1m
+```
+
+## 六、文件索引
+
+| 文件 | 行数 | 职责 |
+|------|------|------|
+| `src/utils/tokenBudget.ts` | 73 | 正则解析 + 位置查找 + 续接消息生成 |
+| `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: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 |
+| `src/components/PromptInput/PromptInput.tsx:534` | 1 | 输入高亮 |

docs/features/tree-sitter-bash.md

@@ -0,0 +1,161 @@
+# TREE_SITTER_BASH — Bash AST 解析
+
+> Feature Flag: `FEATURE_TREE_SITTER_BASH=1`
+> 实现状态：完整可用（纯 TypeScript 实现，~7000+ 行）
+> 引用数：3
+
+## 一、功能概述
+
+TREE_SITTER_BASH 启用一个完整的 Bash AST 解析器，用于安全验证 Bash 命令。它用完整的树遍历安全分析器取代了旧的基于正则表达式的 shell-quote 解析器。关键属性是 **fail-closed**：任何无法识别的内容都被归类为 `too-complex` 并需要用户批准。
+
+### 关联 Feature
+
+| Feature | 说明 |
+|---------|------|
+| `TREE_SITTER_BASH` | 激活用于权限检查的 AST 解析器 |
+| `TREE_SITTER_BASH_SHADOW` | Shadow/观测模式：运行解析器但丢弃结果，仅记录遥测 |
+
+## 二、安全架构
+
+### 2.1 Fail-Closed 设计
+
+核心设计使用 **allowlist** 遍历模式：
+
+- `walkArgument()` 只处理已知安全的节点类型（`word`、`number`、`raw_string`、`string`、`concatenation`、`arithmetic_expansion`、`simple_expansion`）
+- 任何未知节点类型 → `tooComplex()` → 需要用户批准
+- 解析器加载但失败（超时/节点预算/panic）→ 返回 `PARSE_ABORTED` 符号（区别于"模块未加载"）
+
+### 2.2 解析结果
+
+```ts
+parseForSecurity(cmd) 返回：
+  { kind: 'simple', commands: SimpleCommand[] }     // 可静态分析
+  { kind: 'too-complex', reason, nodeType }          // 需要用户批准
+  { kind: 'parse-unavailable' }                      // 解析器未加载
+```
+
+### 2.3 安全检查层次
+
+```
+parseForSecurity(cmd)
+      │
+      ▼
+parseCommandRaw(cmd) → AST root node
+      │
+      ▼
+预检查：控制字符、Unicode 空白、反斜杠+空白、
+        zsh ~[ ] 语法、zsh =cmd 展开、大括号+引号混淆
+      │
+      ▼
+walkProgram(root) → collectCommands(root, commands, varScope)
+      │
+      ├── 'command'         → walkCommand()
+      ├── 'pipeline'/'list' → 结构性，递归子节点
+      ├── 'for_statement'   → 跟踪循环变量为 VAR_PLACEHOLDER
+      ├── 'if/while'        → 作用域隔离的分支
+      ├── 'subshell'        → 作用域复制
+      ├── 'variable_assignment' → walkVariableAssignment()
+      ├── 'declaration_command' → 验证 declare/export flags
+      ├── 'test_command'    → walk test expressions
+      └── 其他              → tooComplex()
+      │
+      ▼
+checkSemantics(commands)
+  ├── EVAL_LIKE_BUILTINS（eval, source, exec, trap...）
+  ├── ZSH_DANGEROUS_BUILTINS（zmodload, emulate...）
+  ├── SUBSCRIPT_EVAL_FLAGS（test -v, printf -v, read -a）
+  ├── Shell keywords as argv[0]（误解析检测）
+  ├── /proc/*/environ 访问
+  ├── jq system() 和危险 flags
+  └── 包装器剥离（time, nohup, timeout, nice, env, stdbuf）
+```
+
+## 三、实现架构
+
+### 3.1 核心模块
+
+| 模块 | 文件 | 行数 | 职责 |
+|------|------|------|------|
+| 门控入口 | `src/utils/bash/parser.ts` | ~110 | `parseCommand()`、`parseCommandRaw()`、`ensureInitialized()` |
+| Bash 解析器 | `src/utils/bash/bashParser.ts` | 4437 | 纯 TS 词法分析 + 递归下降解析器 |
+| 安全分析器 | `src/utils/bash/ast.ts` | 2680 | 树遍历安全分析 + `parseForSecurity()` |
+| AST 分析辅助 | `src/utils/bash/treeSitterAnalysis.ts` | 507 | 引号上下文、复合结构、危险模式提取 |
+| 权限检查入口 | `src/tools/BashTool/bashPermissions.ts` | — | 集成 AST 结果到权限决策 |
+
+### 3.2 Bash 解析器
+
+文件：`src/utils/bash/bashParser.ts`（4437 行）
+
+- 纯 TypeScript 实现（无原生依赖）
+- 生成与 tree-sitter-bash 兼容的 AST
+- 关键类型：`TsNode`（type、text、startIndex、endIndex、children）
+- 安全限制：`PARSE_TIMEOUT_MS = 50`、`MAX_NODES = 50_000` — 防止对抗性输入导致 OOM
+
+### 3.3 安全分析器
+
+文件：`src/utils/bash/ast.ts`（2680 行）
+
+核心函数：
+
+| 函数 | 职责 |
+|------|------|
+| `parseForSecurity(cmd)` | 顶层入口，返回 `simple/too-complex/parse-unavailable` |
+| `parseForSecurityFromAst(cmd, root)` | 接受预解析 AST |
+| `checkSemantics(commands)` | 后解析语义检查 |
+| `walkCommand()` | 提取 argv、envVars、redirects |
+| `walkArgument()` | Allowlist 参数遍历 |
+| `collectCommands()` | 递归收集所有命令 |
+
+### 3.4 AST 分析辅助
+
+文件：`src/utils/bash/treeSitterAnalysis.ts`（507 行）
+
+| 函数 | 职责 |
+|------|------|
+| `extractQuoteContext()` | 识别单引号、双引号、ANSI-C 字符串、heredoc |
+| `extractCompoundStructure()` | 检测管道、子 shell、命令组 |
+| `hasActualOperatorNodes()` | 区分真实 `;`/`&&`/`||` 与转义形式 |
+| `extractDangerousPatterns()` | 检测命令替换、参数展开、heredocs |
+| `analyzeCommand()` | 单次遍历提取 |
+
+### 3.5 Shadow 模式
+
+`TREE_SITTER_BASH_SHADOW` 运行解析器但**从不影响权限决策**：
+
+```ts
+// Shadow 模式：记录遥测，然后强制使用旧版路径
+astResult = { kind: 'parse-unavailable' }
+astRoot = null
+// 记录: available, astTooComplex, astSemanticFail, subsDiffer, ...
+```
+
+记录 `tengu_tree_sitter_shadow` 事件，包含与旧版 `splitCommand()` 的对比数据。用于在不影响行为的情况下收集遥测。
+
+## 四、关键设计决策
+
+1. **Allowlist 遍历**：只处理已知安全的节点类型，未知类型直接 `tooComplex()`
+2. **PARSE_ABORTED 符号**：区分"解析器未加载"和"解析器加载但失败"。后者阻止回退旧版（旧版缺少 `EVAL_LIKE_BUILTINS` 检查）
+3. **变量作用域跟踪**：`VAR=value && cmd $VAR` 模式。静态值解析为真实字符串，`$()` 输出使用 `VAR_PLACEHOLDER`
+4. **PS4/IFS Allowlist**：PS4 赋值使用严格字符白名单 `[A-Za-z0-9 _+:.\/=\[\]-]`，只允许 `${VAR}` 引用
+5. **包装器剥离**：从 argv 前面剥离 `time/nohup/timeout/nice/env/stdbuf`，未知标志 → fail-closed
+6. **Shadow 安全性**：Shadow 模式**总是**强制 `astResult = { kind: 'parse-unavailable' }`，绝不影响权限
+
+## 五、使用方式
+
+```bash
+# 激活 AST 解析用于权限检查
+FEATURE_TREE_SITTER_BASH=1 bun run dev
+
+# Shadow 模式（仅遥测，不影响行为）
+FEATURE_TREE_SITTER_BASH_SHADOW=1 bun run dev
+```
+
+## 六、文件索引
+
+| 文件 | 行数 | 职责 |
+|------|------|------|
+| `src/utils/bash/parser.ts` | ~110 | 门控入口点 |
+| `src/utils/bash/bashParser.ts` | 4437 | 纯 TS bash 解析器 |
+| `src/utils/bash/ast.ts` | 2680 | 安全分析器（核心） |
+| `src/utils/bash/treeSitterAnalysis.ts` | 507 | AST 分析辅助 |
+| `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

@@ -0,0 +1,107 @@
+# ULTRAPLAN — 增强规划
+
+> Feature Flag: `FEATURE_ULTRAPLAN=1`
+> 实现状态：关键字检测完整，命令处理完整，CCR 远程会话完整
+> 引用数：10
+
+## 一、功能概述
+
+ULTRAPLAN 在用户输入中检测 "ultraplan" 关键字时，自动进入增强计划模式。相比普通 plan mode，ultraplan 提供更深入的规划能力，支持本地和远程（CCR）执行。
+
+### 触发方式
+
+| 方式 | 行为 |
+|------|------|
+| 输入含 "ultraplan" 的文本 | 自动重定向到 `/ultraplan` 命令 |
+| `/ultraplan` 斜杠命令 | 直接执行 |
+| 彩虹高亮 | 输入框中 "ultraplan" 关键字彩虹动画 |
+
+## 二、实现架构
+
+### 2.1 模块状态
+
+| 模块 | 文件 | 行数 | 状态 |
+|------|------|------|------|
+| 命令处理器 | `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`（127 行）
+
+`findUltraplanTriggerPositions(text)` 智能过滤：
+- 排除引号内的 "ultraplan"
+- 排除路径中的 "ultraplan"（如 `/path/to/ultraplan/`）
+- 排除斜杠命令以外的上下文
+- `replaceUltraplanKeyword(text)` 清理关键字
+
+### 2.3 CCR 远程会话
+
+文件：`src/utils/ultraplan/ccrSession.ts`（349 行）
+
+`ExitPlanModeScanner` 类实现完整的事件状态机：
+- `pollForApprovedExitPlanMode()` — 3 秒轮询间隔
+- 超时处理和重试
+- 支持远程（teleport）和本地执行
+
+### 2.4 数据流
+
+```
+用户输入 "帮我 ultraplan 重构这个模块"
+         │
+         ▼
+processUserInput 检测 "ultraplan"
+         │
+         ▼
+重定向到 /ultraplan 命令
+         │
+         ├── 本地执行 → EnterPlanMode
+         │
+         └── 远程执行 → teleportToRemote → CCR 会话
+                │
+                ▼
+         ExitPlanModeScanner 轮询
+                │
+                ▼
+         用户在远程审批 → 本地收到结果
+```
+
+## 三、需要补全的内容
+
+| 模块 | 说明 |
+|------|------|
+| `src/screens/REPL.tsx` 中的 UltraplanChoiceDialog / UltraplanLaunchDialog | 用户选择本地/远程执行的对话框组件 |
+| `src/commands/ultraplan/` | 空目录，可能是未合并的子命令结构 |
+
+## 四、关键设计决策
+
+1. **智能关键字过滤**：排除引号和路径中的 "ultraplan"，避免误触发
+2. **本地/远程双模式**：支持本地 plan mode 和 CCR 远程会话
+3. **彩虹高亮反馈**：输入框中 "ultraplan" 关键字使用彩虹动画，暗示这是特殊功能
+4. **processUserInput 集成**：在用户输入处理管道中拦截，无缝重定向
+
+## 五、使用方式
+
+```bash
+# 启用 feature
+FEATURE_ULTRAPLAN=1 bun run dev
+
+# 在 REPL 中使用
+# > ultraplan 重构认证模块
+# > /ultraplan
+```
+
+## 六、文件索引
+
+| 文件 | 行数 | 职责 |
+|------|------|------|
+| `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

@@ -0,0 +1,125 @@
+# VOICE_MODE — 语音输入
+
+> Feature Flag: `FEATURE_VOICE_MODE=1`
+> 实现状态：完整可用（需要 Anthropic OAuth）
+> 引用数：46
+
+## 一、功能概述
+
+VOICE_MODE 实现"按键说话"（Push-to-Talk）语音输入。用户按住空格键录音，音频通过 WebSocket 流式传输到 Anthropic STT 端点（Nova 3），实时转录显示在终端中。
+
+### 核心特性
+
+- **Push-to-Talk**：长按空格键录音，释放后自动发送
+- **流式转录**：录音过程中实时显示中间转录结果
+- **无缝集成**：转录文本直接作为用户消息提交到对话
+
+## 二、用户交互
+
+| 操作 | 行为 |
+|------|------|
+| 长按空格 | 开始录音，显示录音状态 |
+| 释放空格 | 停止录音，等待最终转录 |
+| 转录完成 | 自动插入到输入框并提交 |
+| `/voice` 命令 | 切换语音模式开关 |
+
+### UI 反馈
+
+- **录音指示器**：录音时显示红色/脉冲动画
+- **中间转录**：录音过程中显示 STT 实时识别文本
+- **最终转录**：完成后替换中间结果
+
+## 三、实现架构
+
+### 3.1 门控逻辑
+
+文件：`src/voice/voiceModeEnabled.ts`
+
+三层检查：
+
+```ts
+isVoiceModeEnabled() = hasVoiceAuth() && isVoiceGrowthBookEnabled()
+```
+
+1. **Feature Flag**：`feature('VOICE_MODE')` — 编译时/运行时开关
+2. **GrowthBook Kill-Switch**：`!getFeatureValue_CACHED_MAY_BE_STALE('tengu_amber_quartz_disabled', false)` — 紧急关闭开关（默认 false = 未禁用）
+3. **Auth 检查**：`hasVoiceAuth()` — 需要 Anthropic OAuth token（非 API key）
+
+### 3.2 核心模块
+
+| 模块 | 职责 |
+|------|------|
+| `src/voice/voiceModeEnabled.ts` | Feature flag + GrowthBook + Auth 三层门控 |
+| `src/hooks/useVoice.ts` | React hook 管理录音状态和 WebSocket 连接 |
+| `src/services/voiceStreamSTT.ts` | WebSocket 流式传输到 Anthropic STT |
+
+### 3.3 数据流
+
+```
+用户按下空格键
+      │
+      ▼
+useVoice hook 激活
+      │
+      ▼
+macOS 原生音频 / SoX 开始录音
+      │
+      ▼
+WebSocket 连接到 Anthropic STT 端点
+      │
+      ├──→ 中间转录结果 → 实时显示
+      │
+      ▼
+用户释放空格键
+      │
+      ▼
+停止录音，等待最终转录
+      │
+      ▼
+转录文本 → 插入输入框 → 自动提交
+```
+
+### 3.4 音频录制
+
+支持两种音频后端：
+- **macOS 原生音频**：优先使用，低延迟
+- **SoX（Sound eXchange）**：回退方案，跨平台
+
+音频流通过 WebSocket 发送到 Anthropic 的 Nova 3 STT 模型。
+
+## 四、关键设计决策
+
+1. **OAuth 独占**：语音模式使用 `voice_stream` 端点（claude.ai），仅 Anthropic OAuth 用户可用。API key、Bedrock、Vertex 用户无法使用
+2. **GrowthBook 负向门控**：`tengu_amber_quartz_disabled` 默认 `false`，新安装自动可用（无需等 GrowthBook 初始化）
+3. **Keychain 缓存**：`getClaudeAIOAuthTokens()` 首次调用访问 macOS keychain（~20-50ms），后续缓存命中
+4. **独立于主 feature flag**：`isVoiceGrowthBookEnabled()` 在 feature flag 关闭时短路返回 `false`，不触发任何模块加载
+
+## 五、使用方式
+
+```bash
+# 启用 feature
+FEATURE_VOICE_MODE=1 bun run dev
+
+# 在 REPL 中使用
+# 1. 确保已通过 OAuth 登录（claude.ai 订阅）
+# 2. 按住空格键说话
+# 3. 释放空格键等待转录
+# 4. 或使用 /voice 命令切换开关
+```
+
+## 六、外部依赖
+
+| 依赖 | 说明 |
+|------|------|
+| Anthropic OAuth | claude.ai 订阅登录，非 API key |
+| GrowthBook | `tengu_amber_quartz_disabled` 紧急关闭 |
+| macOS 原生音频 或 SoX | 音频录制 |
+| Nova 3 STT | 语音转文本模型 |
+
+## 七、文件索引
+
+| 文件 | 行数 | 职责 |
+|------|------|------|
+| `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,9 +1,3 @@
----
-title: "浏览器操作工具"
-description: "让 AI 控制 Chrome 完成网页操作：导航、点击、输入、抓取。"
-keywords: ["浏览器工具", "Chrome 控制", "网页操作", "Bun WebView", "WEB_BROWSER_TOOL"]
----
-
 # WEB_BROWSER_TOOL — 浏览器工具
 
 > Feature Flag: `FEATURE_WEB_BROWSER_TOOL=1`

docs/features/web-search-tool.md

@@ -0,0 +1,188 @@
+# WEB_SEARCH_TOOL — 网页搜索工具
+
+> 实现状态：适配器架构完成，支持 API / Bing / Brave 三种后端
+> 引用数：核心工具，无 feature flag 门控（始终启用）
+
+## 一、功能概述
+
+WebSearchTool 让模型可以搜索互联网获取最新信息。原始实现仅支持 Anthropic API 服务端搜索（`web_search_20250305` server tool），在第三方代理端点下不可用。现已重构为适配器架构，支持 API 服务端搜索，以及 Bing / Brave 两个 HTML 解析后端，确保任何 API 端点都能使用搜索功能。
+
+## 二、实现架构
+
+### 2.1 适配器模式
+
+```
+WebSearchTool.call()
+       │
+       ▼
+  createAdapter()  ← 适配器工厂
+       │
+       ├── ApiSearchAdapter  — Anthropic 官方 API 服务端搜索
+       │     └── 使用 web_search_20250305 server tool
+       │         通过 queryModelWithStreaming 二次调用 API
+       │
+       ├── BingSearchAdapter  — Bing HTML 抓取 + 正则提取
+       │     └── 直接抓取 Bing 搜索页 HTML
+       │         正则提取 b_algo 块中的标题/URL/摘要
+       │
+       └── BraveSearchAdapter — Brave LLM Context API
+             └── 调用 Brave HTTPS GET 接口
+                 将 grounding payload 映射为标题/URL/摘要
+```
+
+### 2.2 模块结构
+
+| 模块 | 文件 | 说明 |
+|------|------|------|
+| 工具入口 | `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 数据流
+
+```
+模型调用 WebSearchTool(query, allowed_domains, blocked_domains)
+       │
+       ▼
+  validateInput() — 校验 query 非空、allowed/block 不共存
+       │
+       ▼
+  createAdapter() → ApiSearchAdapter | BingSearchAdapter | BraveSearchAdapter
+       │
+       ▼
+  adapter.search(query, { allowedDomains, blockedDomains, signal, onProgress })
+       │
+       ├── onProgress({ type: 'query_update', query })
+       │
+       ├── axios.get(search-engine-url)
+       │     └── API 鉴权请求头
+       │
+       ├── extractResults(payload) — 按后端提取结果
+       │     └── grounding → SearchResult[] 映射
+       │
+       ├── 客户端域名过滤 (allowedDomains / blockedDomains)
+       │
+       ├── onProgress({ type: 'search_results_received', resultCount })
+       │
+       ▼
+  格式化为 markdown 链接列表返回给模型
+```
+
+## 三、Bing 适配器技术细节
+
+### 3.1 反爬绕过
+
+使用 13 个 Edge 浏览器请求头（含 `Sec-Ch-Ua`、`Sec-Fetch-*` 等），避免 Bing 返回 JS 渲染的空页面：
+
+```typescript
+const BROWSER_HEADERS = {
+  'User-Agent': '...Chrome/131.0.0.0 Safari/537.36 Edg/131.0.0.0',
+  'Sec-Ch-Ua': '"Microsoft Edge";v="131", "Chromium";v="131", ...',
+  'Sec-Fetch-Dest': 'document',
+  'Sec-Fetch-Mode': 'navigate',
+  'Sec-Fetch-Site': 'none',
+  'Sec-Fetch-User': '?1',
+  // ... 共 13 个标头
+}
+```
+
+`setmkt=en-US` 参数强制美式英语市场，避免 IP 地理定位导致区域化结果。
+
+### 3.2 URL 解码（`resolveBingUrl()`）
+
+Bing 返回的重定向 URL 格式：`bing.com/ck/a?...&u=a1aHR0cHM6Ly9...`
+
+- `u` 参数前 2 字符为协议前缀：`a1` = https，`a0` = http
+- 剩余部分为 base64url 编码的真实 URL
+- Bing 内部链接和相对路径被过滤返回 `undefined`
+
+### 3.3 摘要提取（`extractSnippet()`）
+
+三级降级策略：
+
+1. `<p class="b_lineclamp...">` — Bing 的搜索摘要段落
+2. `<div class="b_caption">` 内的 `<p>` — 备选摘要位置
+3. `<div class="b_caption">` 直接文本 — 最终 fallback
+
+### 3.4 域名过滤
+
+客户端侧实现，支持子域名匹配：
+- `allowedDomains`：白名单，结果域名必须匹配列表中的某项（含子域名）
+- `blockedDomains`：黑名单，匹配的结果被过滤
+- 两者不可同时使用（`validateInput` 校验）
+
+## 四、适配器选择逻辑
+
+`createAdapter()` 按以下优先级选择后端，并按选中的后端 key 缓存适配器实例：
+
+```typescript
+export function createAdapter(): WebSearchAdapter {
+  // 1. WEB_SEARCH_ADAPTER=api|bing|brave 显式指定
+  // 2. Anthropic 官方 API Base URL → ApiSearchAdapter
+  // 3. 第三方代理 / 非官方端点 → BingSearchAdapter
+}
+```
+
+显式指定 `WEB_SEARCH_ADAPTER=brave` 时，会改用 Brave LLM Context API 后端，并要求
+`BRAVE_SEARCH_API_KEY` 或 `BRAVE_API_KEY`。
+
+## 五、接口定义
+
+### WebSearchAdapter
+
+```typescript
+interface WebSearchAdapter {
+  search(query: string, options: SearchOptions): Promise<SearchResult[]>
+}
+
+interface SearchResult {
+  title: string
+  url: string
+  snippet?: string
+}
+
+interface SearchOptions {
+  allowedDomains?: string[]
+  blockedDomains?: string[]
+  signal?: AbortSignal
+  onProgress?: (progress: SearchProgress) => void
+}
+
+interface SearchProgress {
+  type: 'query_update' | 'search_results_received'
+  query?: string
+  resultCount?: number
+}
+```
+
+### 工具 Input Schema
+
+```typescript
+{
+  query: string              // 搜索关键词，最少 2 字符
+  allowed_domains?: string[] // 域名白名单
+  blocked_domains?: string[] // 域名黑名单
+}
+```
+
+## 六、文件索引
+
+| 文件 | 职责 |
+|------|------|
+| `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

@@ -0,0 +1,102 @@
+# WORKFLOW_SCRIPTS — 工作流自动化
+
+> Feature Flag: `FEATURE_WORKFLOW_SCRIPTS=1`
+> 实现状态：全部 Stub（7 个文件），布线完整
+> 引用数：10
+
+## 一、功能概述
+
+WORKFLOW_SCRIPTS 实现基于文件的多步自动化工作流。用户可以定义 YAML/JSON 格式的工作流描述文件，系统将其解析为可执行的多 agent 步骤序列。提供 `/workflows` 命令管理和触发工作流。
+
+## 二、实现架构
+
+### 2.1 模块状态
+
+| 模块 | 文件 | 状态 |
+|------|------|------|
+| 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 工作流初始化 (行 131-134,235) |
+| 命令注册 | `src/commands.ts` | **布线** — `/workflows` 命令 (行 93-95,395,460) |
+
+### 2.2 预期数据流
+
+```
+用户定义工作流（YAML/JSON 文件）
+         │
+         ▼
+/workflows 命令发现工作流文件
+         │
+         ▼
+createWorkflowCommand() 解析为 Command 对象 [需要实现]
+         │
+         ▼
+WorkflowTool 执行工作流 [需要实现]
+         │
+         ├── 步骤 1: Agent({ task: "..." })
+         ├── 步骤 2: Agent({ task: "..." })
+         └── 步骤 N: Agent({ task: "..." })
+         │
+         ▼
+LocalWorkflowTask 协调步骤执行 [需要实现]
+         │
+         ▼
+WorkflowDetailDialog 显示进度 [需要实现]
+```
+
+### 2.3 预期工作流 DSL
+
+```
+# workflow.yaml（预期格式，需要设计）
+name: "代码审查工作流"
+steps:
+  - name: "静态分析"
+    agent: { type: "general-purpose", prompt: "运行 lint 和类型检查" }
+  - name: "测试"
+    agent: { type: "general-purpose", prompt: "运行测试套件" }
+  - name: "综合报告"
+    agent: { type: "general-purpose", prompt: "综合分析结果写报告" }
+```
+
+## 三、需要补全的内容
+
+| 优先级 | 模块 | 工作量 | 说明 |
+|--------|------|--------|------|
+| 1 | `WorkflowTool.ts` call 方法 | 中 | 实际工作流执行逻辑（当前返回运行时缺失提示） |
+| 2 | `LocalWorkflowTask.ts` | 大 | 步骤协调、kill/skip/retry |
+| 3 | `WorkflowDetailDialog.ts` | 中 | 进度详情 UI |
+
+## 四、关键设计决策
+
+1. **基于文件的 DSL**：工作流定义为文件（YAML/JSON），版本控制友好
+2. **多 Agent 步骤**：每个步骤是独立的 agent 任务，支持并行/串行
+3. **内置工作流**：`bundled/` 目录提供开箱即用的常用工作流
+4. **/workflows 命令**：统一的发现和触发入口
+
+## 五、使用方式
+
+```bash
+# 启用 feature（需要补全后才能真正使用）
+FEATURE_WORKFLOW_SCRIPTS=1 bun run dev
+```
+
+## 六、文件索引
+
+| 文件 | 职责 |
+|------|------|
+| `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:131-134,235` | 工具注册 |
+| `src/commands.ts:93-95,395,460` | 命令注册 |

docs/getting-started/installation.mdx

@@ -1,125 +0,0 @@
----
-title: "安装 Claude Code Best"
-description: "通过 NPM 一行命令安装 CCB，或从源码克隆构建。支持 macOS、Linux、Windows。"
-keywords: ["安装", "CCB", "NPM", "源码构建", "Bun"]
-og:image: "https://ccb.agent-aura.top/docs/images/og-cover.png"
----
-
-CCB 提供两种安装方式：**NPM 安装**（推荐普通用户）和**源码构建**（推荐贡献者/二次开发者）。
-
-## 方式一：NPM 安装（推荐）
-
-无需克隆仓库，一行命令安装到全局：
-
-```sh
-npm i -g claude-code-best
-
-# 验证
-ccb --version
-```
-
-启动方式：
-
-```sh
-ccb              # 以 Node.js 形态运行
-ccb-bun          # 以 Bun 形态运行（启动更快）
-ccb update       # 更新到最新版本
-```
-
-> 💡 **不推荐** `bun i -g claude-code-best`：bun 全局安装在部分平台有路径冲突问题，建议用 npm。如果一定要用 bun，记得 `bun pm -g trust claude-code-best @claude-code-best/mcp-chrome-bridge` 解除信任限制。
-
-### 远程控制模式（可选）
-
-如果你有自己的 Remote Control Server，可以通过环境变量直连：
-
-```sh
-CLAUDE_BRIDGE_BASE_URL=https://your-rcs.example.com/ \
-CLAUDE_BRIDGE_OAUTH_TOKEN=your-token \
-ccb --remote-control
-```
-
-详情见 [Remote Control 自托管](../features/modes/remote-control-self-hosting)。
-
-### 安装失败排查
-
-| 症状 | 处理 |
-|------|------|
-| `command not found: ccb` | 重开终端，或手动把 npm global bin 加入 PATH |
-| 旧版本残留导致异常 | `npm rm -g claude-code-best && npm i -g claude-code-best@latest` |
-| 拉取特定版本 | `npm i -g claude-code-best@<版本号>` |
-| Windows 上启动报错 | 改用 `ccb-bun` 或安装 [Visual C++ Redistributable](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist) |
-
----
-
-## 方式二：源码构建（贡献者）
-
-源码运行需要 **Bun ≥ 1.3.11**。
-
-### 1. 安装 Bun
-
-```bash
-# Linux / macOS
-curl -fsSL https://bun.sh/install | bash
-
-# Windows (PowerShell)
-powershell -c "irm bun.sh/install.ps1 | iex"
-```
-
-安装后让当前 shell 识别 bun：
-
-```bash
-exec /bin/zsh        # macOS 默认 zsh
-# 或
-source ~/.bashrc     # Linux bash
-```
-
-> ⚠️ **一定要最新版 bun**：`bun upgrade`。低版本会触发各种奇怪的 BUG。
-
-### 2. 克隆并安装依赖
-
-```bash
-git clone https://github.com/claude-code-best/claude-code.git
-cd claude-code
-bun install
-```
-
-### 3. 开发模式运行
-
-```bash
-bun run dev                    # 默认开发模式（启用所有 feature）
-bun run dev:inspect            # 带调试器（BUN_INSPECT=9229 改端口）
-echo "say hello" | bun run src/entrypoints/cli.tsx -p   # Pipe 模式
-```
-
-### 4. 构建产物
-
-```bash
-bun run build        # 默认 Bun.build，输出 dist/cli.js + chunks/
-bun run build:vite   # 备选 Vite 构建（chunk 体积更小）
-```
-
-构建后可直接用 node 运行：
-
-```bash
-node dist/cli.js
-```
-
-> 🔍 **为什么 Vite 构建强制代码分割？** 单文件 17MB 产物会让 Bun/JSC 全量解析 bytecode，RSS 暴涨至 ~1GB；分割为 600+ 小 chunk 后按需加载，`--version` RSS 从 966MB 降至 35MB。详见 [architecture/](../architecture/what-is-claude-code)。
-
-### 5. 提交前检查
-
-每次修改后必须运行：
-
-```bash
-bun run precheck    # typecheck + lint fix + test
-```
-
-`precheck` 必须零错误通过，pre-commit hook 会自动拦截不合格的提交。
-
----
-
-## 下一步
-
-- [快速上手](./quickstart) — 5 分钟学会基本使用
-- [配置模型供应商](./model-providers) — 接入 DeepSeek、GLM、OpenAI 等第三方模型
-- [Feature Flags](../internals/feature-flags) — 了解运行时功能开关

docs/getting-started/model-providers.mdx

@@ -1,165 +0,0 @@
----
-title: "配置模型供应商"
-description: "通过 /login 命令接入 OpenAI / Anthropic / Gemini / Grok 兼容协议，或直接用环境变量配置。支持 DeepSeek、GLM、OpenRouter、Bedrock 代理等任意兼容服务。"
-keywords: ["模型供应商", "/login", "OpenAI", "Gemini", "Grok", "DeepSeek", "GLM"]
-og:image: "https://ccb.agent-aura.top/docs/images/og-cover.png"
----
-
-CCB 不绑定 Anthropic 官方账号，你可以接入任意**协议兼容**的第三方服务。两种配置方式：
-
-- **交互式**：REPL 里输入 `/login`，按引导填字段（推荐首次用户）
-- **环境变量**：写入 shell 配置或 `.envrc`（推荐 CI / 自动化场景）
-
-## 协议矩阵
-
-| 协议 | 启用方式 | 适用场景 |
-|------|---------|---------|
-| **Anthropic Compatible**（默认） | 无需额外开关 | Anthropic 官方 / OpenRouter / Bedrock 代理 / 任意 Messages API 兼容服务 |
-| **OpenAI 兼容** | `CLAUDE_CODE_USE_OPENAI=1` | DeepSeek、Ollama、vLLM、Moonshot、本地部署等 |
-| **Gemini 兼容** | `CLAUDE_CODE_USE_GEMINI=1` | Google Gemini 系列模型 |
-| **Grok 兼容** | `CLAUDE_CODE_USE_GROK=1` | xAI Grok 系列模型 |
-
-## 方式一：`/login` 交互配置（推荐）
-
-在 REPL 里输入 `/login`，进入引导界面，选择对应协议栏目：
-
-```
-┌─ Select Provider ───────────────────────┐
-│  ❯ Anthropic Compatible                 │
-│    OpenAI Compatible                     │
-│    Gemini Compatible                     │
-│    Grok Compatible                       │
-└──────────────────────────────────────────┘
-```
-
-### Anthropic Compatible 需要填写
-
-| 字段 | 说明 | 示例 |
-|------|------|------|
-| Base URL | API 服务地址 | `https://api.example.com/v1` |
-| API Key | 认证密钥 | `sk-xxx` |
-| Haiku Model | 快速模型 ID | `claude-haiku-4-5-20251001` |
-| Sonnet Model | 均衡模型 ID | `claude-sonnet-4-6` |
-| Opus Model | 高性能模型 ID | `claude-opus-4-6` |
-
-> ⌨️ **Tab / Shift+Tab** 切字段，**Enter** 确认并跳到下一个，最后一个字段按 Enter 保存。
-
-### OpenAI 兼容（DeepSeek / Ollama / vLLM 等）
-
-`CLAUDE_CODE_USE_OPENAI=1` 启用后，配置以下环境变量：
-
-```bash
-export CLAUDE_CODE_USE_OPENAI=1
-export OPENAI_API_KEY=sk-xxx
-export OPENAI_BASE_URL=https://api.deepseek.com/v1
-export OPENAI_MODEL=deepseek-chat        # 可选，默认让 CCB 选合适档位
-```
-
-DeepSeek 的 thinking mode 已自动适配，无需额外配置。
-
-### Gemini 兼容
-
-```bash
-export CLAUDE_CODE_USE_GEMINI=1
-export GEMINI_API_KEY=AIzaSy...          # 必填
-export GEMINI_MODEL=gemini-2.5-pro       # 直接指定模型（最高优先级）
-# 或按能力档位映射：
-export GEMINI_DEFAULT_SONNET_MODEL=gemini-2.5-flash
-export GEMINI_DEFAULT_OPUS_MODEL=gemini-2.5-pro
-```
-
-模型映射优先级：`GEMINI_MODEL` > `GEMINI_DEFAULT_*_MODEL`。
-
-### Grok 兼容
-
-```bash
-export CLAUDE_CODE_USE_GROK=1
-export XAI_API_KEY=xai-...
-export GROK_MODEL=grok-4                  # 可选
-```
-
-## 环境变量优先级
-
-CCB 选择 provider 的逻辑：
-
-```
-命令行参数 --provider  >  环境变量 CLAUDE_CODE_USE_*  >  默认 firstParty (Anthropic)
-```
-
-可以同时配置多个 provider，通过环境变量切换：
-
-```bash
-# 临时用 DeepSeek 跑一个会话
-CLAUDE_CODE_USE_OPENAI=1 OPENAI_MODEL=deepseek-reasoner ccb
-```
-
-## 国内服务接入示例
-
-### DeepSeek
-
-```bash
-export CLAUDE_CODE_USE_OPENAI=1
-export OPENAI_API_KEY=sk-xxx
-export OPENAI_BASE_URL=https://api.deepseek.com/v1
-export OPENAI_MODEL=deepseek-chat
-```
-
-### 智谱 GLM
-
-GLM 官方提供 OpenAI 兼容接口：
-
-```bash
-export CLAUDE_CODE_USE_OPENAI=1
-export OPENAI_API_KEY=xxx
-export OPENAI_BASE_URL=https://open.bigmodel.cn/api/paas/v4
-export OPENAI_MODEL=glm-4.6
-```
-
-### 通义千问
-
-```bash
-export CLAUDE_CODE_USE_OPENAI=1
-export OPENAI_API_KEY=sk-xxx
-export OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
-export OPENAI_MODEL=qwen-max
-```
-
-### OpenRouter（一站式多模型）
-
-```bash
-export ANTHROPIC_BASE_URL=https://openrouter.ai/api/v1
-export ANTHROPIC_API_KEY=sk-or-...
-# 然后用 /login 选择 Anthropic Compatible，模型 ID 填 OpenRouter 的 ID
-```
-
-## 穷鬼模式（Poor Mode）
-
-接入便宜的第三方模型后，建议开启 `/poor` 进一步降本：
-
-```
-/poor on
-```
-
-效果：
-
-- 关闭自动记忆提取（`extract_memories`）
-- 关闭输入提示建议（`prompt_suggestion`）
-- 关闭 verification agent
-
-通常能减少 30%-50% 的 token 消耗。设置写入 `~/.claude/settings.json`，重启后保留。
-
-## 排查
-
-| 症状 | 检查 |
-|------|------|
-| `401 Unauthorized` | API Key 错误或过期 |
-| `model not found` | 模型 ID 写错，或 provider 没有这个模型 |
-| 响应慢到超时 | 网络问题或 base URL 写错（注意有的 provider 需要去掉 `/v1` 后缀） |
-| 工具调用不工作 | 部分小厂兼容服务不支持 tool_use，换模型或换 provider |
-| 中文乱码 | 终端编码问题，检查 `LANG=zh_CN.UTF-8` 是否设置 |
-
-## 下一步
-
-- [快速上手](./quickstart) — 基本使用流程
-- [Token Budget](../features/tools/token-budget) — 给每个会话设定 token 上限
-- [Langfuse 监控](../features/tools/langfuse-monitoring) — 实时观察每次 agent loop 的 token 消耗

docs/getting-started/quickstart.mdx

@@ -1,128 +0,0 @@
----
-title: "快速上手"
-description: "5 分钟掌握 CCB 的基本使用：启动会话、输入指令、审批工具调用、用斜杠命令管理状态。"
-keywords: ["快速开始", "使用教程", "REPL", "斜杠命令"]
-og:image: "https://ccb.agent-aura.top/docs/images/og-cover.png"
----
-
-这篇指南假设你已经按 [安装文档](./installation) 装好了 `ccb` 命令。
-
-## 启动第一个会话
-
-在任意项目目录下运行：
-
-```bash
-cd my-project
-ccb
-```
-
-首次启动会经过简短的初始化：
-
-1. **信任确认** — 询问是否信任当前目录的文件读写权限
-2. **主题选择** — 浅色 / 深色 / 自动
-3. **登录配置**（首次）— 跳到 `/login`，配置 API（详见 [配置模型供应商](./model-providers)）
-
-进入 REPL 后会看到：
-
-```
-╭─────────────────────────────────────────────╮
-│  ✻ Welcome to Claude Code Best              │
-│  /help for commands, ctrl+c to exit         │
-╰─────────────────────────────────────────────╯
->
-```
-
-## 基本对话
-
-直接输入任何自然语言指令，回车发送：
-
-```
-> 看一下这个项目的目录结构，告诉我用的是什么技术栈
-```
-
-CCB 会：
-
-1. 调用 `Glob` / `Read` 工具扫描文件
-2. 把结果交给模型分析
-3. 在终端打印回答
-
-如果模型决定改文件或跑命令，会先弹出**权限确认**对话框：
-
-```
-┌─ File Edit ────────────────────────────────┐
-│  src/foo.ts                                 │
-│  - export const x = 1                       │
-│  + export const x = 2                       │
-│                                             │
-│  ❯ 1. Yes  2. Yes, and don't ask again     │
-│    3. No                                    │
-└─────────────────────────────────────────────┘
-```
-
-按数字键或方向键选择。`2` 会把这类操作加入白名单，后续不再询问。
-
-## 常用斜杠命令
-
-| 命令 | 作用 |
-|------|------|
-| `/help` | 列出所有可用命令 |
-| `/login` | 配置 / 切换模型供应商 |
-| `/clear` | 清空当前会话上下文 |
-| `/compact` | 手动压缩历史，节省 token |
-| `/poor` | 切换穷鬼模式（关闭记忆提取和提示建议，省 token） |
-| `/agents` | 管理自定义 agent |
-| `/mcp` | 管理 MCP 服务器 |
-| `/dream` | 手动触发记忆整理 |
-| `/exit` | 退出 |
-
-> 🔍 完整命令列表在 REPL 中输入 `/help` 查看。
-
-## 权限模式
-
-CCB 有 4 种权限模式，启动时按需选择：
-
-| 模式 | 行为 |
-|------|------|
-| **default** | 每个潜在危险操作都询问（最安全） |
-| **acceptEdits** | 自动批准文件编辑，其他仍询问 |
-| **plan** | 只规划不执行（读代码、列出步骤，但不改任何东西） |
-| **bypassPermissions** | 跳过所有权限检查（**危险**，仅在沙箱里用） |
-
-切换模式：在 REPL 里按 `Shift+Tab` 循环切换，或启动时 `ccb --permission-mode plan`。
-
-## 用 Plan 模式做需求分析
-
-复杂任务建议先用 plan 模式做规划：
-
-```
-> 想给这个项目加一个 CI workflow，跑 typecheck 和 test。先告诉我你打算怎么改
-```
-
-模型会列出实施计划，你审阅后输入 `/exit-plan-mode` 让它落地。
-
-详见 [安全与权限 - Plan 模式](../architecture/safety/plan-mode)。
-
-## 后台任务 / 多 Agent
-
-CCB 支持把长任务派给后台 agent，主对话不被阻塞：
-
-```
-> 帮我跑一遍全量测试，跑完告诉我结果
-> （自动用 Task tool 在后台执行）
-```
-
-后台 agent 状态会显示在底部状态条，用 ↑/↓ 切换查看。详见 [Background Agent Selector](../features/agents/background-agent-selector)。
-
-## 退出与会话恢复
-
-- `Ctrl+C` 两次 — 退出 REPL
-- `ccb --resume` — 恢复上次会话
-- `ccb --continue` — 继续上次会话并保留全部历史
-
-会话文件存在 `~/.claude/projects/<project-hash>/` 下。
-
-## 下一步
-
-- [配置模型供应商](./model-providers) — 接入第三方 API
-- [工具系统](../architecture/tools/what-are-tools) — 了解 CCB 有哪些内置工具
-- [使用指南](../guides/hooks) — 用 Hooks 在工具调用前后注入自定义逻辑

docs/internals/ant-only-world.mdx

@@ -0,0 +1,116 @@
+---
+title: "Ant 特权世界"
+description: "Anthropic 内部构建与公开发布版本的差异。理解身份门控机制、Ant-Only 工具/命令和 Beta Header 的分层设计。"
+keywords: ["Ant 特权", "USER_TYPE", "身份门控", "内部功能"]
+---
+
+## 什么是 Ant
+
+Claude Code 有两种构建：Anthropic 员工使用的内部构建（`USER_TYPE === 'ant'`）和公开发布的外部构建（`USER_TYPE === 'external'`）。
+
+`USER_TYPE` 是构建时常量，通过 Bun 的 `--define` 注入。外部构建中，所有 `process.env.USER_TYPE === 'ant'` 判断被编译器折叠为 `false`，后续代码被死代码消除（DCE）移除。
+
+这个门控在代码库中出现 410+ 处，控制着工具、命令、API、UI 等方方面面。
+
+## Ant-Only 工具
+
+| 工具 | 用途 |
+|------|------|
+| **REPLTool** | 高级 REPL 模式——在 VM 中包装其他工具 |
+| **ConfigTool** | 交互式配置编辑器，包含 Gates 标签页覆盖 feature flags |
+| **SuggestBackgroundPRTool** | 建议在后台创建 PR |
+| **TungstenTool** | 基于 tmux 的终端面板工具 |
+
+**设计考量**：这些工具要么涉及内部基础设施（如 GrowthBook flag 覆盖），要么需要 Anthropic 特有的 API 支持。对外部用户暴露它们没有意义——甚至可能引起混淆。
+
+## Ant-Only 命令
+
+内部构建注册了 24+ 个额外的斜杠命令，覆盖调试、实验、工作流和基础设施：
+
+<AccordionGroup>
+  <Accordion title="调试类">
+    - `breakCache` — 清除缓存
+    - `ctx_viz` — 可视化上下文窗口使用情况
+    - `debugToolCall` — 调试工具调用
+    - `env` — 显示环境变量
+    - `mockLimits` — 模拟速率限制
+  </Accordion>
+  <Accordion title="工作流类">
+    - `commit` — 快速提交
+    - `commitPushPr` — 一键提交+推送+创建 PR
+    - `issue` — 创建 GitHub Issue
+    - `autofixPr` — 自动修复 PR 中的问题
+    - `share` — 分享会话
+    - `summary` — 生成摘要
+  </Accordion>
+  <Accordion title="基础设施类">
+    - `backfillSessions` — 回填会话数据
+    - `bridgeKick` — 重启 Bridge 连接
+    - `oauthRefresh` — 刷新 OAuth Token
+  </Accordion>
+</AccordionGroup>
+
+这些命令在演示模式（`IS_DEMO`）下也被隐藏，防止在公开演示中暴露内部功能。
+
+## Beta API Headers 的分层
+
+Claude Code 向 API 发送的 beta headers 按可见性分为多层：
+
+### 公开 Headers（所有构建）
+
+| 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 功能 |
+| `token-efficient-tools-2026-03-28` | Token 高效工具 |
+
+**设计洞察**：`cli-internal` header 说明 Anthropic 的 API 服务端也维护着 ant-only 的行为——这不只是客户端门控，而是端到端的功能隔离。
+
+## 内部代号体系
+
+Anthropic 有"动物命名"文化：
+
+| 代号 | 身份 |
+|------|------|
+| **Tengu**（天狗） | Claude Code 项目代号（所有内部 flag 的 `tengu_` 前缀） |
+| **Capybara**（水豚） | 模型代号 |
+| **Fennec**（耳廓狐） | 已退役模型别名（已迁移到 Opus） |
+
+这些代号通过 Undercover Mode 在公开仓库的 commit 中被过滤。
+
+## 环境变量开关
+
+<AccordionGroup>
+  <Accordion title="功能禁用开关">
+    - `CLAUDE_CODE_SIMPLE` — 简化模式（禁用高级功能）
+    - `CLAUDE_CODE_DISABLE_THINKING` — 禁用 thinking
+    - `DISABLE_AUTO_COMPACT` — 禁用自动压缩
+    - `CLAUDE_CODE_DISABLE_AUTO_MEMORY` — 禁用自动记忆
+    - `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` — 禁用实验性 beta headers
+  </Accordion>
+  <Accordion title="功能启用开关">
+    - `CLAUDE_CODE_VERIFY_PLAN` — 启用 VerifyPlanExecutionTool
+    - `ENABLE_LSP_TOOL` — 启用 LSP 工具
+    - `CLAUDE_CODE_UNDERCOVER` — 强制启用 Undercover Mode
+  </Accordion>
+  <Accordion title="环境配置">
+    - `CLAUDE_CODE_REMOTE` — 远程执行模式
+    - `CLAUDE_CODE_COORDINATOR_MODE` — 启用 Coordinator 模式
+    - `IS_DEMO` — 演示模式（隐藏内部命令和敏感信息）
+  </Accordion>
+</AccordionGroup>
+
+`CLAUDE_CODE_ABLATION_BASELINE` 特别有趣——它同时关闭 thinking、compaction、auto-memory 和 background tasks，用于测量这些高级功能对 AI 表现的**因果影响**。这是一个严肃的"科学对照实验"工具。
+
+## 接下来
+
+- **Feature Flags** — 理解功能开关的设计
+- **权限模型** — 理解身份门控与权限的协作

docs/internals/feature-flags.mdx

@@ -0,0 +1,77 @@
+---
+title: "Feature Flags"
+description: "88+ 个构建时特性门控：理解 feature() 的编译时求值机制、死代码消除和 flags 的分类全景。"
+keywords: ["feature flags", "特性标志", "构建时门控", "条件编译"]
+---
+
+## 核心机制
+
+Claude Code 使用 Bun 打包器的编译时特性门控。代码中通过 `import { feature } from 'bun:bundle'` 导入 `feature()` 函数，在构建时被求值——返回 `true` 的代码保留，返回 `false` 的代码被**死代码消除（DCE）**彻底移除。
+
+**设计洞察**：这不是运行时的 if-else——feature flag 在构建时就已经决定了哪些代码存在。外部构建中不存在的功能不是"被禁用"，而是"从未编译进去"。这是一种零运行时开销的特性门控。
+
+## 三种使用模式
+
+### 1. 条件加载工具
+
+当 flag 为 `false` 时，`require()` 调用被 DCE 移除，工具不会出现在可用工具列表中。不增加打包体积。
+
+### 2. 条件注册命令
+
+斜杠命令只在对应 flag 启用时注册。用户不会看到不可用的命令。
+
+### 3. 条件启用 API 特性
+
+控制发送给 API 的 beta header。未启用的功能不会向服务端声明能力。
+
+## Flags 分类全景
+
+<CardGroup cols={2}>
+  <Card title="Agent / 自动化" icon="robot">
+    **15 个 flags** — 控制 AI 的自主能力边界
+
+    `KAIROS` · `KAIROS_BRIEF` · `KAIROS_CHANNELS` · `KAIROS_DREAM` · `KAIROS_GITHUB_WEBHOOKS` · `KAIROS_PUSH_NOTIFICATION` · `PROACTIVE` · `COORDINATOR_MODE` · `FORK_SUBAGENT` · `AGENT_MEMORY_SNAPSHOT` · `AGENT_TRIGGERS` · `AGENT_TRIGGERS_REMOTE` · `VERIFICATION_AGENT` · `BUILTIN_EXPLORE_PLAN_AGENTS` · `MONITOR_TOOL`
+  </Card>
+
+  <Card title="基础设施" icon="server">
+    **10 个 flags** — 控制运行环境和连接方式
+
+    `DAEMON` · `BG_SESSIONS` · `BRIDGE_MODE` · `CCR_AUTO_CONNECT` · `CCR_MIRROR` · `CCR_REMOTE_SETUP` · `DIRECT_CONNECT` · `SSH_REMOTE` · `SELF_HOSTED_RUNNER` · `BYOC_ENVIRONMENT_RUNNER`
+  </Card>
+
+  <Card title="安全 / 分类" icon="shield-halved">
+    **6 个 flags** — 增强权限判断的智能性
+
+    `TRANSCRIPT_CLASSIFIER` · `BASH_CLASSIFIER` · `TREE_SITTER_BASH` · `TREE_SITTER_BASH_SHADOW` · `NATIVE_CLIENT_ATTESTATION` · `ABLATION_BASELINE`
+  </Card>
+
+  <Card title="工具 / 能力" icon="toolbox">
+    **10 个 flags** — 新增的 AI 能力
+
+    `WEB_BROWSER_TOOL` · `TERMINAL_PANEL` · `CONTEXT_COLLAPSE` · `HISTORY_SNIP` · `OVERFLOW_TEST_TOOL` · `WORKFLOW_SCRIPTS` · `VOICE_MODE` · `MCP_RICH_OUTPUT` · `MCP_SKILLS` · `UDS_INBOX`
+  </Card>
+
+  <Card title="UI / 体验" icon="palette">
+    **8 个 flags** — 界面和交互改进
+
+    `MESSAGE_ACTIONS` · `QUICK_SEARCH` · `HISTORY_PICKER` · `AUTO_THEME` · `STREAMLINED_OUTPUT` · `COMPACTION_REMINDERS` · `TEMPLATES` · `BUDDY`
+  </Card>
+
+  <Card title="平台 / 实验" icon="flask-vial">
+    **10+ 个 flags** — 实验性和平台级功能
+
+    `DUMP_SYSTEM_PROMPT` · `UPLOAD_USER_SETTINGS` · `DOWNLOAD_USER_SETTINGS` · `EXPERIMENTAL_SKILL_SEARCH` · `ULTRAPLAN` · `ULTRATHINK` · `TORCH` · `LODESTONE` · `PERFETTO_TRACING` · `SLOW_OPERATION_LOGGING` · `HARD_FAIL` · `ALLOW_TEST_VERSIONS`
+  </Card>
+</CardGroup>
+
+## 有趣的发现
+
+- **KAIROS 家族**最庞大——6 个相关 flag 控制从核心功能到推送通知的方方面面
+- **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

@@ -0,0 +1,120 @@
+---
+title: "GrowthBook A/B 测试体系 - 运行时功能发布"
+description: "揭秘 Claude Code 如何通过 GrowthBook 实现运行时 A/B 测试：用户定向、tengu 命名文化和渐进式功能发布策略。"
+keywords: ["GrowthBook", "A/B 测试", "运行时门控", "tengu", "渐进式发布"]
+---
+
+{/* 本章目标：深入运行时 A/B 测试层——GrowthBook 的集成架构、用户定向、tengu 命名文化 */}
+
+## 为什么需要运行时 A/B 测试
+
+构建时 `feature()` 是"全有或全无"的——要么所有用户都有，要么所有用户都没有。但产品团队需要更精细的控制：
+
+- 只对 5% 的用户灰度发布新功能
+- 按订阅类型（Free / Pro / Team）差异化体验
+- 对特定组织静默开启实验性能力
+- 随时远程关闭出问题的功能，无需发版
+
+这就是 **GrowthBook** 的用武之地——一个运行时的、基于用户属性的功能门控和 A/B 测试系统。
+
+## 集成架构
+
+GrowthBook 的完整实现位于 `src/services/analytics/growthbook.ts`（1258 行），工作流程如下：
+
+<Steps>
+  <Step title="启动时获取远程配置">
+    CLI 启动时，GrowthBook SDK 通过 `https://api.anthropic.com/` 的 API 端点获取当前的功能配置和实验分组规则。使用 `remoteEval: true` 模式——在服务端计算分组，客户端只拿结果。
+  </Step>
+  <Step title="计算用户属性">
+    SDK 收集当前用户的属性（设备 ID、订阅类型、组织 UUID 等），用于决定该用户属于哪些实验的哪个分组。
+  </Step>
+  <Step title="缓存到本地">
+    计算结果缓存到 `~/.claude.json` 的 `cachedGrowthBookFeatures` 字段。刷新间隔：Anthropic 员工 20 分钟，外部用户 6 小时。
+  </Step>
+  <Step title="代码中查询 flag">
+    业务代码通过 `tengu_*` 前缀的 flag 名查询功能状态，GrowthBook SDK 返回当前用户的分组值。
+  </Step>
+</Steps>
+
+## 用户定向属性
+
+GrowthBook 根据以下用户属性决定实验分组：
+
+| 属性 | 类型 | 来源 | 用途 |
+|------|------|------|------|
+| `id` | string | 会话 ID | 按会话粒度分组 |
+| `deviceID` | string | 持久化设备标识 | 跨会话一致性 |
+| `sessionId` | string | 当前会话 ID | 会话级实验 |
+| `platform` | enum | `process.platform` | 按操作系统差异化 |
+| `organizationUUID` | string | API 认证信息 | 按组织灰度 |
+| `accountUUID` | string | API 认证信息 | 按个人账户灰度 |
+| `subscriptionType` | string | API 认证信息 | Free / Pro / Team 差异化 |
+| `rateLimitTier` | string | API 认证信息 | 按速率限制层级 |
+| `email` | string | API 认证信息 | 精确定向特定用户 |
+| `appVersion` | string | `MACRO.VERSION` | 按版本号灰度 |
+| `github` | object | GitHub Actions 元数据 | CI 环境特殊处理 |
+
+<Note>
+这套定向系统意味着 Anthropic 可以做非常精细的实验——比如"只对 Mac 上的 Pro 订阅用户的 10% 开启新功能"。
+</Note>
+
+## 代号文化：tengu_* 的世界
+
+所有运行时 flag 都以 `tengu_` 为前缀——"Tengu"（天狗）是 Claude Code 的内部项目代号。flag 名采用**动物/植物/矿物 + 形容词**的命名约定，刻意保持不透明。
+
+<AccordionGroup>
+  <Accordion title="tengu_kairos — Kairos 助手模式">
+    控制 KAIROS 功能的运行时开关。即使构建时 `feature('KAIROS')` 通过，仍需此 flag 命中才能激活。双重门控确保新功能可以分阶段发布。
+  </Accordion>
+  <Accordion title="tengu_amber_stoat — Explore Agent A/B 测试">
+    控制内置的 Explore 子 Agent 的行为变体。"amber stoat"（琥珀色白鼬）是随机生成的代号，与功能内容无关——这是为了防止通过 flag 名猜测功能。
+  </Accordion>
+  <Accordion title="tengu_auto_background_agents — 后台 Agent 自动化">
+    控制是否自动将某些任务分派给后台 Agent 执行，而不是在前台阻塞用户。
+  </Accordion>
+  <Accordion title="tengu_onyx_plover — Auto-Dream 后台记忆">
+    控制"自动做梦"功能——在空闲时后台整理和巩固 Agent 的记忆。"onyx plover"（玛瑙鸻）又是一个不透明代号。
+  </Accordion>
+  <Accordion title="tengu_glacier_2xr — 工具搜索行为">
+    控制 Tool Search 的行为变体，可能是搜索算法或排序策略的 A/B 测试。
+  </Accordion>
+  <Accordion title="tengu_birch_trellis — Bash 权限策略">
+    控制 BashTool 权限判断的策略变体——可能在测试更宽松或更严格的权限规则。
+  </Accordion>
+  <Accordion title="tengu_scratch — 草稿本功能">
+    控制一个实验性的"草稿本"功能，可能是让 AI 在处理复杂任务时使用中间暂存区。
+  </Accordion>
+  <Accordion title="tengu_quartz_lantern — Diff 计算策略">
+    控制文件写入和编辑时的 diff 计算方式。可能在 A/B 测试不同的 diff 算法对用户体验的影响。
+  </Accordion>
+</AccordionGroup>
+
+## Ant-Only 覆盖机制
+
+Anthropic 员工拥有两种方式绕过 GrowthBook 的远程求值：
+
+### 环境变量覆盖
+
+```bash
+# 仅在 USER_TYPE=ant 的构建中生效
+CLAUDE_INTERNAL_FC_OVERRIDES='{"tengu_kairos": true}' claude
+```
+
+通过 `CLAUDE_INTERNAL_FC_OVERRIDES` 环境变量传入 JSON 对象，直接覆盖任意 flag 的值。
+
+### Config 界面覆盖
+
+在内部构建中，`/config` 命令的 Gates 标签页提供了图形化的 flag 管理界面，可以实时切换任意 GrowthBook flag。
+
+## 实验追踪
+
+GrowthBook 集成了完整的实验曝光追踪：
+
+- 每次查询 flag 时记录实验曝光事件
+- 通过 protobuf 格式的 `GrowthbookExperimentEvent` 上报
+- 包含 `variation_id`（0=对照组，1+=实验组）和 `in_experiment` 标记
+- 数据用于分析功能对用户行为的因果影响
+
+<Note>
+GrowthBook 正在从 Statsig 迁移而来——代码中仍保留着 `checkStatsigFeatureGate_CACHED_MAY_BE_STALE()` 这样的迁移兼容层。
+</Note>

docs/internals/hidden-features.mdx

@@ -0,0 +1,133 @@
+---
+title: "未公开功能巡礼 - 8 个隐藏功能深度解析"
+description: "深度解析 Claude Code 中 8 个最令人兴奋的隐藏功能：从永不下线的 AI 助手到 AI 吉祥物，揭示 88+ flags 中最具代表性的未公开特性。"
+keywords: ["隐藏功能", "未公开功能", "秘密功能", "Claude Code 彩蛋", "AI 助手"]
+---
+
+{/* 本章目标：逐一展示 8 个最重要的隐藏功能，分析它们背后的产品方向 */}
+
+## 全景
+
+从 88+ 个构建时 flags 和 500+ 个运行时 flags 中，我们挑选了 8 个最具代表性的未公开功能。它们不仅展示了 Claude Code 当前的技术深度，更勾勒出 Anthropic 对"AI 编程助手"的未来愿景。
+
+<AccordionGroup>
+  <Accordion title="KAIROS：永不下线的 AI 助手">
+    **门控**: `feature('KAIROS')` + `tengu_kairos`
+
+    KAIROS 是 Claude Code 最庞大的隐藏功能群——6 个独立 flag 控制着一个完整的"持久化 AI 助手"系统：
+
+    | Flag | 能力 |
+    |------|------|
+    | `KAIROS` | 核心助手模式——AI 不再随对话结束而"消失" |
+    | `KAIROS_BRIEF` | 精简输出模式 |
+    | `KAIROS_CHANNELS` | 基于频道的消息系统 |
+    | `KAIROS_DREAM` | 后台"做梦"——自主整理记忆 |
+    | `KAIROS_GITHUB_WEBHOOKS` | 订阅 GitHub PR 事件，自动响应 |
+    | `KAIROS_PUSH_NOTIFICATION` | 向移动端推送通知 |
+
+    KAIROS 的工具集包括 `SleepTool`（让 AI 主动"休眠"等待事件）、`SendUserFileTool`（向用户发送文件）、`PushNotificationTool`（推送通知）和 `SubscribePRTool`（监听 PR）。
+
+    **推测方向**: 一个 7x24 在线的 AI 团队成员，能自主监控代码库、响应事件、管理任务。
+  </Accordion>
+
+  <Accordion title="PROACTIVE：自主行动模式">
+    **门控**: `feature('PROACTIVE')`
+
+    在标准模式中，Claude Code 是被动的——等待你输入，然后响应。PROACTIVE 模式颠覆了这一范式：
+
+    - AI 拥有 `SleepTool`，可以主动"打盹"一段时间
+    - 系统定期发送 `<tick>` 提示，触发 AI 检查是否有需要主动做的事
+    - AI 可以在没有用户输入的情况下自行决策和执行
+
+    **推测方向**: 从"问答式助手"进化为"自主式同事"——AI 在后台持续工作，偶尔需要你确认方向。
+  </Accordion>
+
+  <Accordion title="COORDINATOR_MODE：多 Agent 指挥官">
+    **门控**: `feature('COORDINATOR_MODE')`
+
+    当前的 Claude Code 已经支持子 Agent（`AgentTool`），但 Coordinator Mode 将其提升到新的层次：
+
+    - 一个"指挥官" Agent 分析任务并分解为子任务
+    - 多个"工人" Agent 并行执行子任务
+    - 指挥官协调结果、处理冲突、合并输出
+
+    完整实现位于 `src/coordinator/coordinatorMode.ts`。
+
+    **推测方向**: 大型编程任务的全自动并行处理——比如"重构整个认证系统"可以同时由多个 Agent 处理不同模块。
+  </Accordion>
+
+  <Accordion title="BRIDGE_MODE：远程遥控">
+    **门控**: `feature('BRIDGE_MODE')`
+
+    Bridge Mode 让 Claude Code 可以通过 WebSocket 被远程控制：
+
+    - `src/bridge/` 目录包含完整的 WebSocket 桥接实现
+    - 支持 IDE 扩展作为远程前端
+    - 包含 ant-only 的故障注入测试（`bridgeDebug.ts`）
+    - 配合 `DIRECT_CONNECT` flag 可通过 `cc://` URL 直连
+
+    **推测方向**: Claude Code 的 UI 前端与后端执行分离——你可以在 VS Code 中操作，但 AI 在远程服务器上执行。
+  </Accordion>
+
+  <Accordion title="WEB_BROWSER_TOOL：内置浏览器">
+    **门控**: `feature('WEB_BROWSER_TOOL')`
+
+    当前的 Claude Code 只有简化的 `WebFetchTool`（获取网页内容），但代码中存在更强大的浏览器工具：
+
+    - 基于 Bun 的 WebView 实现
+    - 可以渲染和交互网页，而不仅仅是抓取文本
+    - 与 Computer Use 的 `@ant/` 包配合使用
+
+    **推测方向**: AI 能像人一样浏览网页——点击、填表、截图，用于测试 Web 应用或收集信息。
+  </Accordion>
+
+  <Accordion title="VOICE_MODE：语音交互">
+    **门控**: `feature('VOICE_MODE')`
+
+    代码中存在语音输入模式的注册点，核心实现依赖 `audio-capture-napi` 包（已恢复）：
+
+    - 通过 `/voice` 命令激活
+    - "按住说话"（hold-to-talk）交互模式
+    - 需要系统级音频 API 支持
+
+    **推测方向**: 不用打字，直接和 AI 对话编程。
+  </Accordion>
+
+  <Accordion title="BUDDY：AI 吉祥物">
+    **门控**: `feature('BUDDY')`
+
+    `src/buddy/` 目录包含一个完整的"伙伴精灵"系统：
+
+    - 终端中的小型动画角色
+    - 可能根据 AI 的状态（思考中、执行中、完成）展示不同动画
+    - 纯 UI/趣味性功能
+
+    **推测方向**: 给冷冰冰的终端增加一点温度——让等待 AI 思考的过程不那么无聊。
+  </Accordion>
+
+  <Accordion title="Undercover Mode：隐身贡献">
+    **门控**: `USER_TYPE === 'ant'`（自动激活）
+
+    这不是一个功能，而是一个**安全机制**——当 Anthropic 员工向公开仓库贡献代码时自动激活：
+
+    - 剥除所有 AI 归属标记（`Co-Authored-By` 行）
+    - 禁止在 commit 消息中提及模型代号（Capybara、Tengu 等）
+    - 禁止暴露内部仓库名、Slack 频道、短链接
+    - 通过 `CLAUDE_CODE_UNDERCOVER=1` 强制开启，无法强制关闭
+    - 仅在仓库匹配内部白名单（~25 个私有仓库）时自动关闭
+
+    **意义**: 证实 Anthropic 员工确实在使用 Claude Code 进行日常开发，并且会向公开项目贡献代码。
+  </Accordion>
+</AccordionGroup>
+
+## 这些功能告诉我们什么
+
+纵观这 8 个隐藏功能，一个清晰的产品愿景浮现：
+
+1. **从被动到主动** — PROACTIVE、KAIROS 让 AI 不再只是等待指令
+2. **从短暂到持久** — KAIROS 的持久化模式让 AI 成为"常驻团队成员"
+3. **从单一到多感官** — VOICE_MODE、WEB_BROWSER_TOOL 拓展交互维度
+4. **从单兵到协同** — COORDINATOR_MODE 让多个 AI 并行协作
+5. **从本地到分布式** — BRIDGE_MODE、SSH_REMOTE 解耦前后端
+
+Claude Code 正在从一个"终端里的聊天机器人"进化为一个**自主、持久、多模态的 AI 编程同事**。