docs: 添加文档大纲及 superpowers/outline 目录

Co-Authored-By: deepseek-v4-pro <deepseek-ai@claude-code-best.win>

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

@@ -41,7 +41,8 @@ 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`
@@ -275,7 +276,8 @@ Update `session.md` after each round:
 When all concepts mastered or user ends session:
 
 1. Update `session.md` with final state.
-2. Update `.claude/skills/teach-me/records/learner-profile.md` (keep under 30 lines):
+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.
+3. Update `.claude/skills/teach-me/records/learner-profile.md` (keep under 30 lines):
 
 ```markdown
 # Learner Profile
@@ -293,7 +295,48 @@ Updated: {timestamp}
 - Python decorators (8/10 concepts, 2025-01-15)
 ```
 
-3. Give a brief text summary of what was covered, key insights, and areas for further study.
+4. 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 = tab
-indent_size = 4
+indent_style = space
+indent_size = 2
 end_of_line = lf
 charset = utf-8
 trim_trailing_whitespace = true

.githooks/pre-commit

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

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,52 @@
+---
+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

@@ -0,0 +1,8 @@
+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

@@ -0,0 +1,31 @@
+---
+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,26 +2,60 @@ name: CI
 
 on:
   push:
-    branches: [main, feature/*]
+    branches: [main, "feature/*", "feat/*"]
   pull_request:
-    branches: [main]
+    branches: [main, "feat/*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
 
 jobs:
   ci:
-    runs-on: macos-latest
+    runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2, 2026-04-25
+        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@v2
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2, 2026-04-25
         with:
           bun-version: latest
 
       - name: Install dependencies
+        env:
+          CLAUDE_CODE_SKIP_CHROME_MCP_SETUP: "1"
         run: bun install --frozen-lockfile
 
-      - name: Test
-        run: bun test
+      - name: Lint and format check
+        run: bunx biome ci .
+
+      - name: Type check
+        run: bun run typecheck
+
+      - 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
+          test -s coverage/lcov.info
+          grep -q '^SF:' coverage/lcov.info
+
+      # codecov 坏了，老是失败，先注释掉
+      # - name: Upload coverage to Codecov
+      #   if: ${{ github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository }}
+      #   uses: codecov/codecov-action@75cd11691c0faa626561e295848008c8a7dddffe # v5, 2026-04-25
+      #   with:
+      #     fail_ci_if_error: true
+      #     files: ./coverage/lcov.info
+      #     disable_search: true
+      #     token: ${{ secrets.CODECOV_TOKEN }}
 
       - name: Build
-        run: bun run build
+        run: bun run build:vite

.github/workflows/publish-npm.yml

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

.github/workflows/update-contributors.yml

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

.gitignore

@@ -5,20 +5,26 @@ coverage
 .env
 *.log
 .idea
-.vscode
+.vscode/*
+!.vscode/extensions.json
 *.suo
 *.lock
 src/utils/vendor/
 
 # AI tool runtime directories
 .agents/
-.codex/
+.claude/
 .omx/
-
+.docs/task/
 # Binary / screenshot files (root only)
 /*.png
 *.bmp
 
+# Internal system prompt documents
+Claude-Opus-*.txt
+Claude-Sonnet-*.txt
+Claude-Haiku-*.txt
+
 # Agent / tool state dirs
 .swarm/
 .agents/__pycache__/
@@ -29,3 +35,24 @@ __pycache__/
 logs
 
 data
+.omc
+.codex/*
+!.codex/agents/
+!.codex/agents/**
+!.codex/skills/
+!.codex/skills/**
+.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

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

.impeccable.md

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

.mintignore

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

.npmrc

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

.tool-versions

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

.vscode/extensions.json

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

AGENTS.md

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

DEV-LOG.md

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

README.md

@@ -6,38 +6,55 @@
 [![GitHub License](https://img.shields.io/github/license/claude-code-best/claude-code?style=flat-square)](https://github.com/claude-code-best/claude-code/blob/main/LICENSE)
 [![Last Commit](https://img.shields.io/github/last-commit/claude-code-best/claude-code?style=flat-square&color=blue)](https://github.com/claude-code-best/claude-code/commits/main)
 [![Bun](https://img.shields.io/badge/runtime-Bun-black?style=flat-square&logo=bun)](https://bun.sh/)
-[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?style=flat-square&logo=discord)](https://discord.gg/qZU6zS7Q)
+[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?style=flat-square&logo=discord)](https://discord.gg/uApuzJWGKX)
 
 > Which Claude do you like? The open source one is the best.
 
-牢 A (Anthropic) 官方 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI 工具的源码反编译/逆向还原项目。目标是将 Claude Code 大部分功能及工程化能力复现 (问就是老佛爷已经付过钱了)。虽然很难绷, 但是它叫做 CCB(踩踩背)...
+牢 A (Anthropic) 官方 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 完整复原的工程化项目。虽然很难绷, 但是它叫做 CCB(踩踩背)... 而且, 我们实现了企业版或者需要登陆 Claude 账号才能使用的特性, 并在此基础上扩展了更多好玩的特性。
 
-[文档在这里, 支持投稿 PR](https://ccb.agent-aura.top/) | [留影文档在这里](./Friends.md) | [Discord 群组](https://discord.gg/qZU6zS7Q)
+[Peri Code](https://github.com/KonghaYao/peri)：Claude Code 兼容的 Rust Agent，多年大模型经验匠心制作，国内大模型（DeepSeek/GLM）精调，CPU/内存极致优化，在开发版/树莓派上也能跑 CC 一样的体验。
 
-- ✅ [x] V4 — 测试补全、[Buddy](https://ccb.agent-aura.top/docs/features/buddy)、[Auto Mode](https://ccb.agent-aura.top/docs/safety/auto-mode)、环境变量 Feature 开关
-- ✅ [x] V5 — [Sentry](https://ccb.agent-aura.top/docs/internals/sentry-setup) / [GrowthBook](https://ccb.agent-aura.top/docs/internals/growthbook-adapter) 企业监控、[自定义 Login](https://ccb.agent-aura.top/docs/features/custom-platform-login)、[OpenAI 兼容](https://ccb.agent-aura.top/docs/plans/openai-compatibility)、[Web Search](https://ccb.agent-aura.top/docs/features/web-browser-tool)、[Computer Use](https://ccb.agent-aura.top/docs/features/computer-use) / [Chrome Use](https://ccb.agent-aura.top/docs/features/claude-in-chrome-mcp)、[Voice Mode](https://ccb.agent-aura.top/docs/features/voice-mode)、[Bridge Mode](https://ccb.agent-aura.top/docs/features/bridge-mode)、[/dream 记忆整理](https://ccb.agent-aura.top/docs/features/auto-dream)
-- 🔮 [ ] V6 — 大规模重构石山代码，全面模块分包（全新分支，main 封存为历史版本）
+[文档在这里](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/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 下载后, 直接使用
 
 ```sh
-bun  i -g claude-code-best
-bun pm -g trust claude-code-best
-ccb # 直接打开 claude code
+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
+
+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 # 我们有自部署的远程控制
 ```
 
-⚠️ 国内对 github 网络较差的, 需要先设置这个环境变量
-
-```bash
-DEFAULT_RELEASE_BASE=https://ghproxy.net/https://github.com/microsoft/ripgrep-prebuilt/releases/download/v15.0.1
-```
+> **安装/更新失败？** 先 `npm rm -g claude-code-best` 清理旧版本，再 `npm i -g claude-code-best@latest`。仍失败则指定版本号：`npm i -g claude-code-best@<版本号>`
 
 ## ⚡ 快速开始(源码版)
 
@@ -46,20 +63,69 @@ DEFAULT_RELEASE_BASE=https://ghproxy.net/https://github.com/microsoft/ripgrep-pr
 一定要最新版本的 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
 ```
 
-⚠️ 国内对 github 网络较差的,可以使用这个环境变量
-
-```bash
-DEFAULT_RELEASE_BASE=https://ghproxy.net/https://github.com/microsoft/ripgrep-prebuilt/releases/download/v15.0.1
-```
-
 ### ▶️ 运行
 
 ```bash
@@ -83,17 +149,16 @@ bun run build
 
 需要填写的字段：
 
-| 📌 字段 | 📝 说明 | 💡 示例 |
-|------|------|------|
-| 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` |
+| 📌 字段      | 📝 说明       | 💡 示例                      |
+| ------------ | ------------- | ---------------------------- |
+| 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 保存
 
-
 > ℹ️ 支持所有 Anthropic API 兼容服务（如 OpenRouter、AWS Bedrock 代理等），只要接口兼容 Messages API 即可。
 
 ## Feature Flags
@@ -113,16 +178,17 @@ TUI (REPL) 模式需要真实终端，无法直接通过 VS Code launch 启动
 ### 步骤
 
 1. **终端启动 inspect 服务**：
+
    ```bash
    bun run dev:inspect
    ```
-   会输出类似 `ws://localhost:8888/xxxxxxxx` 的地址。
 
+   会输出类似 `ws://localhost:8888/xxxxxxxx` 的地址。
 2. **VS Code 附着调试器**：
+
    - 在 `src/` 文件中打断点
    - F5 → 选择 **"Attach to Bun (TUI debug)"**
 
-
 ## Teach Me 学习项目
 
 我们新加了一个 teach-me skills, 通过问答式引导帮你理解这个项目的任何模块。(调整 [sigma skill 而来](https://github.com/sanyuan0704/sanyuan-skills))
@@ -149,7 +215,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>
+- **DeepWiki**: [https://deepwiki.com/claude-code-best/claude-code](https://deepwiki.com/claude-code-best/claude-code)
 
 ## Contributors
 
@@ -167,6 +233,10 @@ 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,11 +48,64 @@ 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
 ```
 
@@ -135,7 +188,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,114 +1,118 @@
 {
-	"$schema": "https://biomejs.dev/schemas/2.4.10/schema.json",
-	"vcs": {
-		"enabled": true,
-		"clientKind": "git",
-		"useIgnoreFile": true
-	},
-	"files": {
-		"includes": ["**", "!!**/dist", "!!**/packages/@ant"]
-	},
-	"formatter": {
-		"enabled": true,
-		"indentStyle": "space",
-		"indentWidth": 2,
-		"lineWidth": 80
-	},
-	"linter": {
-		"enabled": true,
-		"rules": {
-			"recommended": true,
-			"suspicious": {
-				"noExplicitAny": "off",
-				"noAssignInExpressions": "off",
-				"noDoubleEquals": "off",
-				"noRedeclare": "off",
-				"noImplicitAnyLet": "off",
-				"noGlobalIsNan": "off",
-				"noFallthroughSwitchClause": "off",
-				"noShadowRestrictedNames": "off",
-				"noArrayIndexKey": "off",
-				"noConsole": "off",
-				"noConfusingLabels": "off",
-				"useIterableCallbackReturn": "off"
-			},
-			"style": {
-				"useConst": "off",
-				"noNonNullAssertion": "off",
-				"noParameterAssign": "off",
-				"useDefaultParameterLast": "off",
-				"noUnusedTemplateLiteral": "off",
-				"useTemplate": "off",
-				"useNumberNamespace": "off",
-				"useNodejsImportProtocol": "off",
-				"useImportType": "off"
-			},
-			"complexity": {
-				"noForEach": "off",
-				"noBannedTypes": "off",
-				"noUselessConstructor": "off",
-				"noStaticOnlyClass": "off",
-				"useOptionalChain": "off",
-				"noUselessSwitchCase": "off",
-				"noUselessFragments": "off",
-				"noUselessTernary": "off",
-				"noUselessLoneBlockStatements": "off",
-				"noUselessEmptyExport": "off",
-				"useArrowFunction": "off",
-				"useLiteralKeys": "off"
-			},
-			"correctness": {
-				"noUnusedVariables": "off",
-				"noUnusedImports": "off",
-				"useExhaustiveDependencies": "off",
-				"noSwitchDeclarations": "off",
-				"noUnreachable": "off",
-				"useHookAtTopLevel": "off",
-				"noVoidTypeReturn": "off",
-				"noConstantCondition": "off",
-				"noUnusedFunctionParameters": "off"
-			},
-			"a11y": {
-				"recommended": false
-			},
-			"nursery": {
-				"recommended": false
-			}
-		}
-	},
-	"json": {
-		"formatter": {
-			"enabled": false
-		}
-	},
-	"javascript": {
-		"formatter": {
-			"quoteStyle": "single",
-			"semicolons": "asNeeded",
-			"arrowParentheses": "asNeeded",
-			"trailingCommas": "all"
-		}
-	},
-	"overrides": [
-		{
-			"includes": ["**/*.tsx"],
-			"javascript": {
-				"formatter": {
-					"semicolons": "always"
-				}
-			},
-			"formatter": {
-				"lineWidth": 120
-			}
-		},
-		{
-			"includes": ["scripts/**", "packages/**", "**/*.js", "**/*.mjs", "**/*.jsx"],
-			"formatter": {
-				"enabled": false
-			}
-		}
-	],
-	"assist": {
-		"enabled": false
-	}
+  "$schema": "https://biomejs.dev/schemas/2.4.12/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "includes": [
+      "**",
+      "!!**/dist",
+      "!!**/.claude/workflows",
+      "!!**/*.workflow.mjs"
+    ]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 80
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "suspicious": {
+        "noExplicitAny": "off",
+        "noAssignInExpressions": "off",
+        "noDoubleEquals": "off",
+        "noRedeclare": "off",
+        "noImplicitAnyLet": "off",
+        "noGlobalIsNan": "off",
+        "noFallthroughSwitchClause": "off",
+        "noShadowRestrictedNames": "off",
+        "noArrayIndexKey": "off",
+        "noConsole": "off",
+        "noConfusingLabels": "off",
+        "useIterableCallbackReturn": "off"
+      },
+      "style": {
+        "useConst": "off",
+        "noNonNullAssertion": "off",
+        "noParameterAssign": "off",
+        "useDefaultParameterLast": "off",
+        "noUnusedTemplateLiteral": "off",
+        "useTemplate": "off",
+        "useNumberNamespace": "off",
+        "useNodejsImportProtocol": "off",
+        "useImportType": "off"
+      },
+      "complexity": {
+        "noForEach": "off",
+        "noBannedTypes": "off",
+        "noUselessConstructor": "off",
+        "noStaticOnlyClass": "off",
+        "useOptionalChain": "off",
+        "noUselessSwitchCase": "off",
+        "noUselessFragments": "off",
+        "noUselessTernary": "off",
+        "noUselessLoneBlockStatements": "off",
+        "noUselessEmptyExport": "off",
+        "useArrowFunction": "off",
+        "useLiteralKeys": "off"
+      },
+      "correctness": {
+        "noUnusedVariables": "off",
+        "noUnusedImports": "off",
+        "useExhaustiveDependencies": "off",
+        "noSwitchDeclarations": "off",
+        "noUnreachable": "off",
+        "useHookAtTopLevel": "off",
+        "noVoidTypeReturn": "off",
+        "noConstantCondition": "off",
+        "noUnusedFunctionParameters": "off"
+      },
+      "a11y": {
+        "recommended": false
+      },
+      "nursery": {
+        "recommended": false
+      }
+    }
+  },
+  "json": {
+    "formatter": {
+      "enabled": true
+    }
+  },
+  "css": {
+    "parser": {
+      "tailwindDirectives": true
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "semicolons": "asNeeded",
+      "arrowParentheses": "asNeeded",
+      "trailingCommas": "all"
+    }
+  },
+  "overrides": [
+    {
+      "includes": ["**/*.tsx"],
+      "javascript": {
+        "formatter": {
+          "semicolons": "always"
+        }
+      },
+      "formatter": {
+        "lineWidth": 120
+      }
+    }
+  ],
+  "assist": {
+    "enabled": false
+  }
 }

build.ts

@@ -1,6 +1,7 @@
 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'
 
@@ -8,30 +9,6 @@ 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 = [
-  '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',
-]
-
 // Collect FEATURE_* env vars → Bun.build features
 const envFeatures = Object.keys(process.env)
   .filter(k => k.startsWith('FEATURE_'))
@@ -44,7 +21,14 @@ const result = await Bun.build({
   outdir,
   target: 'bun',
   splitting: true,
-  define: getMacroDefines(),
+  sourcemap: 'linked',
+  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,
 })
 
@@ -75,27 +59,50 @@ for (const file of files) {
   }
 }
 
+// Also patch unguarded globalThis.Bun destructuring from third-party deps
+// (e.g. @anthropic-ai/sandbox-runtime) so Node.js doesn't crash at import time.
+let bunPatched = 0
+const BUN_DESTRUCTURE = /var \{([^}]+)\} = globalThis\.Bun;?/g
+const BUN_DESTRUCTURE_SAFE =
+  'var {$1} = typeof globalThis.Bun !== "undefined" ? globalThis.Bun : {};'
+for (const file of files) {
+  if (!file.endsWith('.js')) continue
+  const filePath = join(outdir, file)
+  const content = await readFile(filePath, 'utf-8')
+  if (BUN_DESTRUCTURE.test(content)) {
+    await writeFile(
+      filePath,
+      content.replace(BUN_DESTRUCTURE, BUN_DESTRUCTURE_SAFE),
+    )
+    bunPatched++
+  }
+}
+BUN_DESTRUCTURE.lastIndex = 0
+
 console.log(
-  `Bundled ${result.outputs.length} files to ${outdir}/ (patched ${patched} for Node.js compat)`,
+  `Bundled ${result.outputs.length} files to ${outdir}/ (patched ${patched} for import.meta.require, ${bunPatched} for Bun destructure)`,
 )
 
-// Step 4: Copy native .node addon files (audio-capture)
-const vendorDir = join(outdir, 'vendor', 'audio-capture')
-await cp('vendor/audio-capture', vendorDir, { recursive: true })
-console.log(`Copied vendor/audio-capture/ → ${vendorDir}/`)
+// Step 4: Copy native .node addon files (audio-capture) and vendored binaries (ripgrep)
+const audioCaptureDir = join(outdir, 'vendor', 'audio-capture')
+await cp('vendor/audio-capture', audioCaptureDir, { recursive: true })
+console.log(`Copied vendor/audio-capture/ → ${audioCaptureDir}/`)
 
-// Step 5: Bundle download-ripgrep script as standalone JS for postinstall
-const rgScript = await Bun.build({
-  entrypoints: ['scripts/download-ripgrep.ts'],
-  outdir,
-  target: 'node',
-})
-if (!rgScript.success) {
-  console.error('Failed to bundle download-ripgrep script:')
-  for (const log of rgScript.logs) {
-    console.error(log)
-  }
-  // Non-fatal — postinstall fallback to bun run scripts/download-ripgrep.ts
-} else {
-  console.log(`Bundled download-ripgrep script to ${outdir}/`)
-}
+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')
+const cliNode = join(outdir, 'cli-node.js')
+
+await writeFile(cliBun, '#!/usr/bin/env bun\nimport "./cli.js"\n')
+
+await writeFile(cliNode, '#!/usr/bin/env node\nimport "./cli.js"\n')
+
+// Make both executable
+const { chmodSync } = await import('fs')
+chmodSync(cliBun, 0o755)
+chmodSync(cliNode, 0o755)
+
+console.log(`Generated ${cliBun} (shebang: bun) and ${cliNode} (shebang: node)`)

codecov.yml

@@ -0,0 +1,51 @@
+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

@@ -0,0 +1,688 @@
+# 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

@@ -0,0 +1,127 @@
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "theme": "mint",
+  "name": "Claude Code Best",
+  "description": "Anthropic Claude Code 的开源复原版本 — 完整架构原理、功能文档与使用指南。",
+  "colors": {
+    "primary": "#D77757",
+    "light": "#F59E0B",
+    "dark": "#B45309"
+  },
+  "favicon": "/docs/favicon.svg",
+  "logo": {
+    "light": "/docs/logo/light.svg",
+    "dark": "/docs/logo/dark.svg"
+  },
+  "background": {
+    "color": {
+      "light": "#FFFFFF",
+      "dark": "#0F172A"
+    }
+  },
+  "navbar": {
+    "primary": {
+      "type": "github",
+      "href": "https://github.com/claude-code-best/claude-code"
+    }
+  },
+  "search": {
+    "prompt": "搜索 CCB 文档..."
+  },
+  "seo": {
+    "metatags": {
+      "og:image": "https://ccb.agent-aura.top/docs/images/og-cover.png",
+      "twitter:image": "https://ccb.agent-aura.top/docs/images/og-cover.png",
+      "twitter:card": "summary_large_image"
+    },
+    "indexing": "navigable"
+  },
+  "footer": {
+    "socials": {
+      "github": "https://github.com/claude-code-best/claude-code",
+      "discord": "https://discord.gg/uApuzJWGKX"
+    }
+  },
+  "redirects": [
+    {
+      "source": "/docs/features/agents/uds-inbox",
+      "destination": "/docs/features/agents/pipes-and-lan"
+    },
+    {
+      "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

@@ -0,0 +1,32 @@
+# 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/REVISION-PLAN.md

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

docs/agent/coordinator-and-swarm.mdx

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

docs/agent/sub-agents.mdx

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

docs/agent/worktree-isolation.mdx

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

docs/auto-updater.md

@@ -1,312 +0,0 @@
-# 自动更新机制
-
-## 概述
-
-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:1735`）
-   - `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/main.tsx:1775` 在启动时调用：
-
-```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/main.tsx:325` 在启动时调用。
-
----
-
-## 更新通知去重
-
-**文件**: `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:1735` | `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

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

docs/context/project-memory.mdx

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

docs/context/system-prompt.mdx

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

docs/context/token-budget.mdx

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

docs/conversation/multi-turn.mdx

@@ -1,184 +0,0 @@
----
-title: "多轮对话管理 - QueryEngine 会话编排与持久化"
-description: "从源码角度解析 Claude Code 多轮对话管理：QueryEngine 的会话状态机、JSONL transcript 持久化、成本追踪模型和模型热切换机制。"
-keywords: ["多轮对话", "会话管理", "QueryEngine", "transcript", "成本追踪"]
----
-
-{/* 本章目标：从源码角度揭示会话编排、持久化存储、成本追踪和模型切换的完整链路 */}
-
-## 单轮 vs 多轮：架构层面的差异
-
-- **单轮**（一次 Agentic Loop）：`query()` 函数的一次完整执行——组装上下文 → 调 API → 处理工具调用 → 循环直到结束
-- **多轮**（一个 Session）：`QueryEngine` 类管理的一次会话——跨越数十轮 `submitMessage()` 调用，持续数小时
-
-`QueryEngine`（`src/QueryEngine.ts:186`）是单轮 Agentic Loop 之上的**会话编排器**，它管理的状态远不止消息列表：
-
-```
-QueryEngine 内部状态
-├── mutableMessages: Message[]         ← 完整对话历史，跨 turn 累积
-├── readFileState: FileStateCache      ← 已读文件内容缓存，避免重复读取
-├── totalUsage: NonNullableUsage       ← 累计 token 消耗（input/output/cache）
-├── permissionDenials: SDKPermissionDenial[]  ← 权限拒绝记录
-├── discoveredSkillNames: Set<string>  ← 当前 turn 已发现的 skill
-└── abortController: AbortController   ← 会话级中断控制
-```
-
-## QueryEngine 的核心方法：submitMessage()
-
-每次用户输入一条消息，REPL 或 SDK 调用 `submitMessage()`，它会执行完整的 turn 初始化链路：
-
-```typescript
-// src/QueryEngine.ts:211 — 简化的 submitMessage 流程
-async *submitMessage(prompt, options?): AsyncGenerator<SDKMessage> {
-  // 1. 清除 turn 级追踪状态
-  this.discoveredSkillNames.clear()
-  
-  // 2. 解析模型（用户可能中途切换了模型）
-  const mainLoopModel = userSpecifiedModel
-    ? parseUserSpecifiedModel(userSpecifiedModel)
-    : getMainLoopModel()
-  
-  // 3. 动态组装 System Prompt（每次 turn 都重新构建）
-  const { defaultSystemPrompt, userContext, systemContext } =
-    await fetchSystemPromptParts({ tools, mainLoopModel, mcpClients })
-  
-  // 4. 包装权限检查（追踪每次拒绝）
-  const wrappedCanUseTool = async (tool, input, ...) => {
-    const result = await canUseTool(tool, input, ...)
-    if (result.behavior !== 'allow') {
-      this.permissionDenials.push({ tool_name: tool.name, ... })
-    }
-    return result
-  }
-  
-  // 5. 调用核心 query() 函数执行 agentic loop
-  yield* query({
-    systemPrompt, messages: this.mutableMessages,
-    tools, model: mainLoopModel, ...
-  })
-}
-```
-
-关键设计：`submitMessage()` 是 `async *Generator`——它逐步 yield `SDKMessage`，让调用方（REPL/SDK）能实时展示进度，而不是等整个 turn 结束。
-
-## 会话持久化：JSONL Transcript
-
-每次对话事件都被追加写入 transcript 文件（`src/utils/sessionStorage.ts`）：
-
-### 存储路径
-
-```
-~/.claude/projects/<project-hash>/<session-id>.jsonl
-```
-
-- `project-hash` 由 `getProjectDir(originalCwd)` 生成，同一项目目录的会话归入同一子目录
-- 每条记录是一行 JSON（JSONL 格式），支持追加写入而不需要读取-修改-写入整个文件
-- 读取上限为 50MB（`MAX_TRANSCRIPT_READ_BYTES`），防止超大会话导致 OOM
-
-### Transcript 写入器
-
-`TranscriptWriter`（`src/utils/sessionStorage.ts:1200+`）是一个写队列，确保并发的消息追加不会互相覆盖：
-
-```
-写入流程：
-  appendEntryToFile(sessionId, entry)
-    ↓
-  ensureCurrentSessionFile()   ← 懒初始化：首次写入时才创建文件
-    ↓
-  序列化为 JSON + 换行符
-    ↓
-  appendFile(path, line)       ← 原子追加
-    ↓
-  如果配置了远程持久化：
-    persistToRemote(sessionId, entry)
-      ├── CCR v2: internalEventWriter('transcript', entry)
-      └── v1 Ingress: sessionIngress.appendSessionLog(...)
-```
-
-### 会话恢复链路
-
-`--resume` 参数触发的恢复流程（`src/main.tsx:3620+`）：
-
-```
-1. 解析 resume 参数：
-   ├── UUID 格式 → getTranscriptPathForSession(uuid)
-   ├── .jsonl 文件路径 → 直接使用
-   └── boolean → 最近一次会话的 picker
-   
-2. loadTranscriptFromFile(path)
-   ├── 按 JSONL 行解析
-   ├── 过滤出消息类型记录
-   └── 重建 Message[] 数组
-
-3. 恢复上下文状态：
-   ├── restoreCostStateForSession(sessionId)  ← 恢复累计费用
-   ├── 恢复 agentSetting（用户选择的 Agent 类型）
-   └── 如果有 --rewind-files，恢复文件到指定消息时的快照
-
-4. 创建 QueryEngine({ initialMessages: restoredMessages })
-   └── 从恢复的消息继续对话
-```
-
-## 成本追踪：从 API Usage 到美元
-
-成本追踪贯穿三个模块，形成完整的记录→累计→展示链路：
-
-### 记录层：API 响应中的 Usage
-
-每个 `message_delta` 事件携带 `usage` 字段（`input_tokens`、`output_tokens`、`cache_creation_input_tokens`、`cache_read_input_tokens`）。`accumulateUsage()` 将增量 usage 累加到会话总量。
-
-### 累计层：cost-tracker.ts
-
-```typescript
-// src/cost-tracker.ts — StoredCostState 数据模型
-type StoredCostState = {
-  totalCostUSD: number                       // 累计美元花费
-  totalAPIDuration: number                   // API 调用总时长（含重试）
-  totalAPIDurationWithoutRetries: number     // 不含重试的纯推理时间
-  totalToolDuration: number                  // 工具执行总时长
-  totalLinesAdded: number                    // 代码增加行数
-  totalLinesRemoved: number                  // 代码删除行数
-  modelUsage: { [modelName: string]: ModelUsage }  // 按模型分拆的用量
-}
-```
-
-`addToTotalSessionCost()` 根据模型定价计算每次 API 调用的费用，累计到 `totalCostUSD`。按模型的 `ModelUsage` 支持在同一会话中切换模型后分别统计。
-
-### 持久化：跨重启保留
-
-```typescript
-// 每次会话结束时保存到项目配置
-saveCurrentSessionCosts(sessionId)
-  → projectConfig.lastCost = totalCostUSD
-  → projectConfig.lastSessionId = sessionId
-  → projectConfig.lastModelUsage = modelUsage
-```
-
-### 预算熔断
-
-`QueryEngineConfig.maxBudgetUsd` 提供了会话级的硬性预算上限。在 REPL 中，当累计费用超过 $5 时（`src/screens/REPL.tsx:2208`），弹出费用提醒对话框——这不是硬性阻断，而是"软提醒"。
-
-## 模型热切换
-
-在一个会话中切换模型不会丢失对话历史——因为 `mutableMessages` 与模型选择是解耦的：
-
-```
-/model sonnet → setMainLoopModelOverride('claude-sonnet-4-20250514')
-  ↓
-下一次 submitMessage() 开始时：
-  ↓
-parseUserSpecifiedModel(userSpecifiedModel)
-  → 返回新的模型配置
-  ↓
-fetchSystemPromptParts({ mainLoopModel: newModel })
-  → System Prompt 根据新模型能力重新组装
-  ↓
-query({ model: newModel, messages: this.mutableMessages })
-  → 使用完整历史 + 新模型继续对话
-```
-
-切换模型时，`contextWindowTokens` 和 `maxOutputTokens` 也会根据新模型的规格重新计算——例如从 Sonnet 切换到 Opus 时，上下文窗口可能从 200K 变为 1M。
-
-## 文件快照与回滚
-
-`fileHistoryMakeSnapshot()`（`src/utils/fileHistory.ts`）在 AI 每次修改文件前自动保存当前内容。快照绑定到具体的 `message.id`，使得 `--rewind-files <user-message-id>` 可以精确恢复到对话中任意时间点的文件状态——这比 git 更细粒度（git 只追踪已提交的内容）。

docs/conversation/streaming.mdx

@@ -1,183 +0,0 @@
----
-title: "流式响应机制 - Claude Code 打字机效果原理"
-description: "解析 Claude Code 流式响应实现：如何通过 SSE 逐 token 接收 AI 输出，实现实时打字机效果，提升用户等待体验。"
-keywords: ["流式响应", "SSE", "streaming", "实时输出", "API streaming"]
----
-
-## 为什么需要流式
-
-想象 AI 需要 30 秒才能生成完整回答——如果等 30 秒后才一次性显示，用户体验是灾难性的。
-
-流式响应让用户**实时看到 AI 的思考过程**：
-- 文字逐字出现，用户能提前判断方向是否正确
-- 工具调用的参数在生成过程中就能预览
-- 长时间任务不会让用户觉得"卡死了"
-
-## `BetaRawMessageStreamEvent` 核心事件类型
-
-流式 API 返回的是一系列 `BetaRawMessageStreamEvent`，每种事件类型对应流式响应的不同阶段（`src/services/api/claude.ts`）：
-
-```
-message_start           ← 消息开始，包含 model、usage 初始值
-  ├── content_block_start   ← 内容块开始（text / tool_use / thinking）
-  │   ├── content_block_delta  ← 增量数据（text_delta / input_json_delta / thinking_delta）
-  │   ├── content_block_delta  ← ... 持续到达
-  │   └── content_block_stop   ← 内容块结束，yield AssistantMessage
-  ├── content_block_start   ← 下一个内容块...
-  │   └── ...
-  └── message_delta       ← stop_reason + 最终 usage
-message_stop            ← 消息结束
-```
-
-### 事件处理状态机
-
-`src/services/api/claude.ts:1980-2298` 实现了一个基于 `switch(part.type)` 的状态机：
-
-| 事件类型 | 处理逻辑 | 状态变更 |
-|----------|----------|----------|
-| `message_start` | 初始化 `partialMessage`，记录 TTFT（首字节延迟） | `usage` 初始化 |
-| `content_block_start` | 按 `part.index` 创建对应类型的内容块 | `contentBlocks[index]` 初始化 |
-| `content_block_delta` | 按子类型增量追加数据 | text / thinking / input 累加 |
-| `content_block_stop` | 构建完整 `AssistantMessage` 并 yield | 消息推入 `newMessages` |
-| `message_delta` | 更新 stop_reason 和最终 usage | 写回最后一条消息 |
-| `message_stop` | 无操作（流结束标记） | — |
-
-### 内容块类型及其增量数据
-
-`content_block_start` 中的 `content_block.type` 决定了如何处理后续 delta：
-
-| 内容块类型 | Delta 类型 | 累加逻辑 |
-|-----------|-----------|----------|
-| `text` | `text_delta` | `text += delta.text` |
-| `thinking` | `thinking_delta` + `signature_delta` | `thinking += delta.thinking`，`signature = delta.signature` |
-| `tool_use` | `input_json_delta` | `input += delta.partial_json`（JSON 字符串增量拼接） |
-| `server_tool_use` | `input_json_delta` | 同 tool_use |
-| `connector_text` | `connector_text_delta` | 特殊连接器文本（feature flag 控制） |
-
-关键设计：`content_block_start` 时所有文本字段初始化为空字符串，只通过 `content_block_delta` 累加。这是因为 SDK 有时在 start 和 delta 中重复发送相同文本。
-
-## 文本 chunk 和 tool_use block 的交织
-
-一次 AI 响应可能包含多个内容块，交替出现：
-
-```
-content_block_start (text, index=0)     "我来帮你修复这个 bug。"
-content_block_delta  (text_delta)       "首先..."
-content_block_stop  (index=0)
-content_block_start (tool_use, index=1) { name: "Read", input: "..." }
-content_block_delta  (input_json_delta) '{"file_p' → 'ath":' → '"src/foo.ts"}'
-content_block_stop  (index=1)
-content_block_start (text, index=2)     "我已经看到了问题所在..."
-content_block_stop  (index=2)
-```
-
-每个 `content_block_stop` 触发一次 `yield`，将完整的 AssistantMessage 推送给消费者。这意味着一个 AI 响应会产生**多条** `AssistantMessage`——文本消息和工具调用消息交替产出。
-
-`stop_reason` 要等到 `message_delta` 才确定（可能是 `end_turn`、`tool_use`、`max_tokens` 等），所以最后一条消息的 `stop_reason` 是**回写**的：
-
-```typescript
-// claude.ts:2246 — 直接属性修改，不用对象替换
-// 因为 transcript 写队列持有 message.message 的引用
-const lastMsg = newMessages.at(-1)
-if (lastMsg) {
-  lastMsg.message.usage = usage
-  lastMsg.message.stop_reason = stopReason
-}
-```
-
-## 流式中的错误处理
-
-### 网络断开
-
-流式连接依赖 SSE（Server-Sent Events）。当连接中断时：
-
-1. **Stream idle watchdog**：定时检测事件间隔，超过阈值（stall）触发告警和重试
-2. **Stream abort**：如果 watchdog 检测到长时间无事件，抛出错误进入重试流程
-3. **非流式降级**：作为最后手段，回退到非流式请求（一次性获取完整响应）
-
-```typescript
-// claude.ts:2338-2355 — 检测空流
-// 1. 完全没有事件 → 代理返回了非 SSE 响应
-// 2. 有 message_start 但没有 content_block_stop → 流被截断
-```
-
-### API 限流
-
-当 API 返回限流错误时，系统使用 `withRetry` 包装器进行指数退避重试。重试逻辑考虑了：
-- 错误类型（429 限流 vs 500 服务器错误）
-- 重试次数上限
-- 退避间隔
-
-### Token 超限
-
-两种 token 超限场景有不同的处理：
-
-| 场景 | stop_reason | 处理方式 |
-|------|------------|----------|
-| **输出超限** | `max_tokens` | 生成错误消息，建议设置 `CLAUDE_CODE_MAX_OUTPUT_TOKENS` |
-| **上下文窗口超限** | `model_context_window_exceeded` | 触发 compaction 压缩对话历史后重试 |
-
-```typescript
-// claude.ts:2267-2293
-if (stopReason === 'max_tokens') {
-  yield createAssistantAPIErrorMessage({ error: 'max_output_tokens', ... })
-}
-if (stopReason === 'model_context_window_exceeded') {
-  // 复用 max_output_tokens 的恢复路径
-  yield createAssistantAPIErrorMessage({ error: 'max_output_tokens', ... })
-}
-```
-
-### 流式停滞检测
-
-系统持续监控事件到达间隔，检测"停滞"（stall）：
-
-```typescript
-// claude.ts:1940-1966
-const STALL_THRESHOLD_MS = 10_000  // 10 秒无事件视为停滞
-if (timeSinceLastEvent > STALL_THRESHOLD_MS) {
-  stallCount++
-  totalStallTime += timeSinceLastEvent
-  logEvent('tengu_streaming_stall', { stall_duration_ms, stall_count, ... })
-}
-```
-
-多个 stall 累积后，watchdog 可能决定中断流并触发重试。
-
-## 工具执行的流式反馈
-
-BashTool 的命令执行也是流式的——通过 `onProgress` 回调逐行推送输出：
-
-```
-BashTool.call() → runShellCommand() → AsyncGenerator
-  ├── 每秒轮询输出文件 → onProgress(lastLines, allLines, ...)
-  ├── yield { type: 'progress', output, fullOutput, elapsedTimeSeconds }
-  └── return { code, stdout, interrupted, ... }
-```
-
-UI 层通过 `useToolCallProgress` hook 实时展示命令输出，而不是等命令完全结束。长时间运行的命令还支持自动后台化（`shouldAutoBackground`）。
-
-## 多 Provider 适配
-
-| Provider | 流式协议 | 特殊处理 |
-|----------|----------|----------|
-| **Anthropic Direct** | 原生 SSE | 延迟最低，TTFT 最快 |
-| **AWS Bedrock** | AWS SDK 流式接口 | 需要额外的 beta header 和认证 |
-| **Google Vertex** | gRPC → 事件流 | 通过 `getMergedBetas()` 适配 |
-| **Azure** | Anthropic 兼容 API | 自定义 base URL |
-
-所有 Provider 通过统一的 `Stream<BetaRawMessageStreamEvent>` 抽象层屏蔽差异。上层代码（QueryEngine、REPL）不需要关心底层用的是哪个 Provider。
-
-### Provider 选择
-
-`src/utils/model/providers.ts` 中的 `getAPIProvider()` 根据配置决定使用哪个 Provider：
-
-```typescript
-// 根据 api_provider 配置选择：
-// "anthropic" → 直连
-// "bedrock"   → AWS SDK
-// "vertex"    → Google SDK
-// 第三方 base URL → 自动检测
-```
-
-每个 Provider 需要适配的细节包括：认证方式、beta header、请求参数格式、错误码映射——但这些差异在 `claude.ts` 的 `queryStream()` 函数中被统一处理。

docs/conversation/the-loop.mdx

@@ -1,182 +0,0 @@
----
-title: "Agentic Loop：AI 自主循环的核心机制"
-description: "深入解析 Claude Code 的 query() 异步生成器循环——从流式 API 调用、工具并行执行、上下文压缩、错误恢复到终止条件的完整状态机，基于 src/query.ts 的源码级分析。"
-keywords: ["Agentic Loop", "query loop", "tool_use", "状态机", "auto-compact", "streaming", "recovery"]
----
-
-{/* 本章目标：基于 src/query.ts 揭示 Agentic Loop 的完整状态机 */}
-
-## 什么是 Agentic Loop
-
-传统聊天机器人：你问一句，它答一句。  
-Claude Code 不一样：你说一个需求，它可能连续执行十几步操作才给你最终结果。
-
-这背后的机制叫做 **Agentic Loop**（智能体循环），核心实现在 `src/query.ts` 的 `queryLoop()` 异步生成器函数（第 241 行）。它是一个 `while(true)` 无限循环，每次迭代代表一次"思考→行动→观察"周期。
-
-<Frame caption="Agentic Loop 循环示意">
-  <img src="/docs/images/agentic-loop.png" alt="Agentic Loop 循环图" />
-</Frame>
-
-## 循环的完整结构
-
-`queryLoop()` 的每次迭代（`src/query.ts:307` `while(true)`）包含以下阶段：
-
-### 阶段 1：上下文预处理（Pre-Processing Pipeline）
-
-在调用 API 之前，依次执行 5 个压缩/优化步骤：
-
-```
-messagesForQuery（原始消息）
-  ↓ applyToolResultBudget()    — 工具结果预算截断（按 maxResultSizeChars）
-  ↓ snipCompactIfNeeded()      — 历史 Snip 压缩（HISTORY_SNIP feature）
-  ↓ microcompact()             — 微压缩（工具结果摘要）
-  ↓ applyCollapsesIfNeeded()   — 上下文折叠（CONTEXT_COLLAPSE feature）
-  ↓ autocompact()              — 自动压缩（超出阈值时触发）
-messagesForQuery（处理后的消息）→ 发往 API
-```
-
-每个步骤的输出是下一步的输入，形成串行管道。Snip 和 Microcompact 的释放 token 数会传递给 autocompact 的阈值计算（`snipTokensFreed`），避免重复压缩。
-
-### 阶段 2：流式 API 调用（Streaming Loop）
-
-`deps.callModel()` 发起流式请求（第 659 行），返回一个 AsyncGenerator。在流式过程中：
-
-- **AssistantMessage** 被收集到 `assistantMessages[]` 数组
-- **tool_use 块** 被提取到 `toolUseBlocks[]`，设置 `needsFollowUp = true`
-- **StreamingToolExecutor** 在流式过程中就开始并行执行工具（不等流结束）
-- 可恢复的错误（prompt-too-long、max-output-tokens）被**暂扣**（withheld），先尝试恢复
-
-流式回调中的关键守卫：
-- `backfillObservableInput()`（第 763 行）—— 为 tool_use 块回填可观察字段（如文件路径展开），但只在添加了新字段时才克隆消息，避免破坏 prompt cache 的字节一致性
-- 流式降级检测——如果 `streamingFallbackOccured`，已收集的消息被标记为 tombstone（第 717 行），清空后重试
-
-### 阶段 3：工具执行（Tool Execution）
-
-如果 `needsFollowUp` 为 true，循环不会终止，而是执行工具：
-
-```typescript
-// 两种工具执行器（互斥）
-const toolUpdates = streamingToolExecutor
-  ? streamingToolExecutor.getRemainingResults()  // 流式：获取已完成的+等待中的
-  : runTools(toolUseBlocks, assistantMessages, canUseTool, toolUseContext)
-```
-
-工具结果通过 `normalizeMessagesForAPI()` 标准化后，与原始消息合并，进入**下一轮循环迭代**。
-
-### 阶段 4：终止或继续
-
-每次迭代结束时，根据条件决定 `return`（终止）或 `continue`（继续）：
-
-## 7 种终止条件（源码级）
-
-| 终止原因 | 触发位置 | 机制 |
-|----------|---------|------|
-| **completed** | 第 1360 行 | AI 未发出 tool_use → `needsFollowUp = false` → 经过 stop hooks → 返回 |
-| **blocking_limit** | 第 646 行 | Token 计数超过硬限制（非 autocompact 模式）→ 生成 PTL 错误消息 → 返回 |
-| **aborted_streaming** | 第 1054 行 | `abortController.signal.aborted` → 为未完成的 tool_use 生成合成 tool_result → 返回 |
-| **model_error** | 第 999 行 | `callModel()` 抛出异常 → 生成错误消息 → 返回 |
-| **prompt_too_long** | 第 1178 行 | 413 错误且 reactive compact 无法恢复 → 暂扣的错误消息被释放 → 返回 |
-| **image_error** | 第 980/1178 行 | 图片尺寸/大小错误 → 直接返回 |
-| **stop_hook_prevented** | 第 1282 行 | Stop hook 返回 `preventContinuation: true` → 返回 |
-
-## 4 种继续条件（恢复路径）
-
-循环不仅是一个简单的"有 tool_use 就继续"，它还包含多种恢复/重试路径：
-
-### 1. 正常工具循环
-`needsFollowUp = true` → 执行工具 → 新消息追加到 `messagesForQuery` → `continue`
-
-### 2. max_output_tokens 恢复（第 1191-1255 行）
-当 AI 输出被截断时（`apiError === 'max_output_tokens'`）：
-- **首次**：尝试将 `maxOutputTokens` 从默认值提升到 `ESCALATED_MAX_TOKENS`（64K），无 meta 消息，静默重试
-- **后续**：注入恢复消息"Output token limit hit. Resume directly..."，最多重试 `MAX_OUTPUT_TOKENS_RECOVERY_LIMIT = 3` 次
-- 恢复耗尽后，暂扣的错误消息被释放
-
-### 3. Prompt-Too-Long 恢复（第 1088-1186 行）
-当遇到 413 错误时，有两个恢复阶段：
-- **Context Collapse Drain**（第 1097 行）：提交所有已暂存的折叠，释放空间后重试。如果上一轮已经是 collapse_drain_retry 则跳过
-- **Reactive Compact**（第 1123 行）：触发即时压缩，生成摘要后重试。`hasAttemptedReactiveCompact` 防止无限循环
-
-### 4. Stop Hook 阻塞重试（第 1285-1308 行）
-Stop hook 可以注入阻塞错误消息，强制 AI 重新思考。新的消息（包含阻塞错误）被追加到对话中，`stopHookActive = true`，进入下一轮迭代。
-
-## 模型降级（Fallback）
-
-当主模型不可用时（`FallbackTriggeredError`，第 897 行）：
-
-1. 已收集的 `assistantMessages` 被清空，tool_use 块收到合成 tool_result："Model fallback triggered"
-2. 思维签名块被移除（`stripSignatureBlocks`）—— 因为思维签名与模型绑定，跨模型回放会 400
-3. 切换到 `fallbackModel`，更新 `toolUseContext.options.mainLoopModel`
-4. 生成系统消息："Switched to {fallback} due to high demand for {original}"
-5. 重新发起流式请求
-
-## 状态机：State 对象
-
-每次迭代的状态通过 `State` 类型（第 204 行）传递：
-
-```typescript
-type State = {
-  messages: Message[]                        // 当前对话消息
-  toolUseContext: ToolUseContext              // 工具上下文（含权限）
-  autoCompactTracking: AutoCompactTrackingState  // 压缩跟踪
-  maxOutputTokensRecoveryCount: number       // 输出截断恢复计数
-  hasAttemptedReactiveCompact: boolean       // 是否已尝试即时压缩
-  maxOutputTokensOverride: number | undefined // 输出 token 上限覆盖
-  pendingToolUseSummary: Promise<...> | undefined  // 异步工具摘要
-  stopHookActive: boolean | undefined        // Stop hook 是否激活
-  turnCount: number                          // 轮次计数
-  transition: Continue | undefined           // 上一次继续的原因
-}
-```
-
-每次 `continue` 都创建新的 State 对象（不可变更新），而非就地修改。`transition` 字段记录了为什么继续——让后续迭代能检测特定恢复路径（如 `collapse_drain_retry`）避免循环。
-
-## Token Budget（实验性）
-
-当 `TOKEN_BUDGET` feature 启用时（第 1311 行），循环在终止前会检查 token 消耗：
-
-- **continuation**：未达到预算但超过阈值 → 注入 nudge 消息，让 AI 加速收尾
-- **diminishing_returns**：检测到收益递减 → 提前终止
-- 预算数据来自 `createBudgetTracker()`，跨迭代累计
-
-## 为什么不是"一次规划，批量执行"
-
-<Note>
-源码揭示了为什么 Claude Code 选择逐步循环：
-</Note>
-
-- **每一步都产生真实信息**：`runTools()` 返回的 `toolResults` 是 API 不可能预知的——命令输出、文件内容、错误信息
-- **动态上下文管理**：每轮迭代前都重新评估压缩需求（autocompact → microcompact → snip），基于最新的 token 计数
-- **错误即时恢复**：工具失败不需要推倒重来——stop hook 可以注入阻塞错误让 AI 修正策略
-- **用户可控**：`abortController.signal` 在循环的多个检查点被检测（第 1018、1048、1488 行），用户按 ESC 可以优雅中断
-- **成本控制**：Token Budget 在每轮终止前检查，防止 AI 无效循环
-
-## 一个完整的迭代示例
-
-> 用户："帮我找到项目里所有未使用的导入语句，然后删掉它们"
-
-```
-迭代 1: 思考→行动
-  预处理: 无需压缩（上下文很短）
-  API 调用: 返回 tool_use(Glob, "**/*.ts")
-  工具执行: 返回 42 个文件路径
-  → needsFollowUp = true, continue
-
-迭代 2: 思考→行动
-  预处理: 42 个文件结果仍在预算内
-  API 调用: 返回 tool_use(Grep, "import.*from")
-  工具执行: 在 15 个文件中找到 120 条 import
-  → needsFollowUp = true, continue
-
-迭代 3: 思考→行动（多轮）
-  预处理: 120 条 Grep 结果触发 microcompact → 摘要化
-  API 调用: 返回 3 个 tool_use(FileEdit, ...)
-  工具执行: 删除 5 条未使用导入
-  → needsFollowUp = true, continue
-
-迭代 4: 总结
-  API 调用: 返回纯文本"已清理 3 个文件中的 5 条未使用导入"
-  → needsFollowUp = false
-  → Stop hooks 通过
-  → return { reason: 'completed' }
-```

docs/extensibility/custom-agents.mdx

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

docs/extensibility/hooks.mdx

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

docs/extensibility/mcp-protocol.mdx

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

docs/extensibility/skills.mdx

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

docs/external-dependencies.md

@@ -1,209 +0,0 @@
-# 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 | Bing Search | `www.bing.com` | HTTPS | WebSearch 工具 |
-| 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:228-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. Bing Search
-
-WebSearch 工具的默认适配器，抓取 Bing 搜索结果。
-
-- **端点**: `https://www.bing.com/search?q={query}&setmkt=en-US`
-- **文件**: `src/tools/WebSearchTool/adapters/bingAdapter.ts`
-
-另外还有 Domain Blocklist 查询:
-- **端点**: `https://api.anthropic.com/api/web/domain_info?domain={domain}`
-- **文件**: `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 |
-| `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/feature-exploration-plan.md

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

docs/features/agents/acp.md

@@ -0,0 +1,389 @@
+---
+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

@@ -0,0 +1,420 @@
+---
+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/bash-classifier.md

@@ -1,107 +0,0 @@
-# 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.tsx:261-469` | — | 分类器 UI |
-| `src/hooks/toolPermission/handlers/interactiveHandler.ts` | — | 交互式权限处理 |
-| `src/services/api/withRetry.ts:81` | — | API beta 标头 |

docs/features/bridge-mode.md

@@ -1,158 +0,0 @@
-# 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 提供 7 个核心操作：
-
-| 操作 | 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` | 540 | 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

@@ -1,87 +0,0 @@
----
-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/buddy.ts` | `/buddy` 命令处理 |
-| `src/buddy/companion.ts` | 宠物生成与加载 |
-| `src/buddy/types.ts` | 类型定义（物种、稀有度、属性） |
-| `src/buddy/sprites.ts` | 终端像素画渲染 |
-| `src/buddy/CompanionSprite.tsx` | React 组件（输入框旁显示） |
-| `src/buddy/useBuddyNotification.tsx` | 启动提示通知 |
-| `src/buddy/prompt.ts` | 宠物相关 prompt 模板 |

docs/features/claude-in-chrome-mcp.md

@@ -1,137 +0,0 @@
-# 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

@@ -1,325 +0,0 @@
-# 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

@@ -1,277 +0,0 @@
-# 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,496 +0,0 @@
-# Computer Use 工具参考文档
-
-## 概览
-
-Computer Use 提供 37 个工具，分为三类：
-
-| 分类 | 平台 | 工具数 | 说明 |
-|------|------|--------|------|
-| 通用工具 | 全平台 | 24 | 官方 Computer Use 标准能力 |
-| Windows 专属工具 | Win32 | 10 | 绑定窗口模式下的增强能力 |
-| 教学工具 | 全平台 | 3 | 分步引导模式（需 teachMode 开启） |
-
----
-
-## 一、通用工具（24 个）
-
-全平台可用。未绑定窗口时，操作对象是整个屏幕。
-
-### 权限与会话
-
-| 工具 | 参数 | 说明 |
-|------|------|------|
-| `request_access` | `apps[]`, `reason`, `clipboardRead?`, `clipboardWrite?`, `systemKeyCombos?` | 请求操作应用的权限。所有其他工具的前置条件 |
-| `list_granted_applications` | — | 列出当前会话已授权的应用 |
-
-### 截图与显示
-
-| 工具 | 参数 | 说明 |
-|------|------|------|
-| `screenshot` | `save_to_disk?` | 截取当前屏幕。绑定窗口时截取绑定窗口（PrintWindow）。返回图片 + GUI 元素列表（Windows） |
-| `zoom` | `region: [x1,y1,x2,y2]` | 截取指定区域的高分辨率图片。坐标基于最近一次全屏截图 |
-| `switch_display` | `display` | 切换截图的目标显示器 |
-
-### 鼠标操作
-
-| 工具 | 参数 | 说明 |
-|------|------|------|
-| `left_click` | `coordinate: [x,y]`, `text?` (修饰键) | 左键点击。`text` 可传 "shift"/"ctrl"/"alt" 实现组合点击 |
-| `double_click` | `coordinate`, `text?` | 双击 |
-| `triple_click` | `coordinate`, `text?` | 三击（选整行） |
-| `right_click` | `coordinate`, `text?` | 右键点击 |
-| `middle_click` | `coordinate`, `text?` | 中键点击 |
-| `mouse_move` | `coordinate` | 移动鼠标（不点击） |
-| `left_click_drag` | `coordinate` (终点), `start_coordinate?` (起点) | 拖拽 |
-| `left_mouse_down` | — | 按下左键不松 |
-| `left_mouse_up` | — | 松开左键 |
-| `cursor_position` | — | 获取当前鼠标位置 |
-
-### 键盘操作
-
-| 工具 | 参数 | 说明 |
-|------|------|------|
-| `type` | `text` | 输入文字 |
-| `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 专属工具（10 个）
-
-仅 Windows 平台可见。核心能力：**绑定窗口后的独立操作——不抢占用户鼠标键盘**。
-
-### 工作模式
-
-```
-┌──────────────────────────────────────────────────┐
-│                  未绑定模式                        │
-│  使用通用工具 (left_click/type/key/scroll)          │
-│  操作对象：整个屏幕                                 │
-│  输入方式：全局 SendInput（会移动真实鼠标）           │
-└──────────────────────────────────────────────────┘
-                        │
-                  bind_window / open_application
-                        ▼
-┌──────────────────────────────────────────────────┐
-│                  绑定窗口模式                      │
-│  使用 Win32 工具 (virtual_mouse/virtual_keyboard)  │
-│  操作对象：绑定的窗口                               │
-│  输入方式：SendMessageW（不动真实鼠标/键盘）          │
-│  可视化：DWM 绿色边框 + 虚拟光标 + 状态指示器        │
-└──────────────────────────────────────────────────┘
-```
-
-### 窗口绑定
-
-| 工具 | 参数 | 说明 |
-|------|------|------|
-| `bind_window` | `action`: list/bind/unbind/status | 窗口绑定管理 |
-
-**动作详情：**
-
-| action | 参数 | 说明 |
-|--------|------|------|
-| `list` | — | 列出所有可见窗口（hwnd、pid、title） |
-| `bind` | `title?`, `hwnd?`, `pid?` | 绑定到指定窗口。设置 DWM 绿色边框 + 启动虚拟光标 + 启动状态指示器 + 短暂激活窗口确保可接收输入 |
-| `unbind` | — | 解除绑定，恢复全屏模式 |
-| `status` | — | 查看当前绑定状态（hwnd、title、pid、窗口矩形） |
-
-### 窗口管理
-
-| 工具 | 参数 | 说明 |
-|------|------|------|
-| `window_management` | `action`, `x?`, `y?`, `width?`, `height?` | 窗口操作（Win32 API，不走全局快捷键） |
-
-**动作详情：**
-
-| action | 说明 |
-|--------|------|
-| `minimize` | ShowWindow(SW_MINIMIZE) |
-| `maximize` | ShowWindow(SW_MAXIMIZE) |
-| `restore` | ShowWindow(SW_RESTORE) — 恢复最小化/最大化 |
-| `close` | SendMessage(WM_CLOSE) — 优雅关闭 |
-| `focus` | SetForegroundWindow + BringWindowToTop — 激活窗口 |
-| `move_offscreen` | SetWindowPos(-32000,-32000) — 移到屏幕外（仍可 SendMessage/PrintWindow） |
-| `move_resize` | SetWindowPos — 移动/缩放到指定位置和大小 |
-| `get_rect` | GetWindowRect — 获取当前位置和大小 |
-
-### 虚拟鼠标
-
-| 工具 | 参数 | 说明 |
-|------|------|------|
-| `virtual_mouse` | `action`, `coordinate: [x,y]`, `start_coordinate?` | 在绑定窗口内操作虚拟鼠标 |
-
-**动作详情：**
-
-| action | 说明 |
-|--------|------|
-| `click` | 左键点击。虚拟光标移动到坐标 + 闪烁动画 |
-| `double_click` | 双击 |
-| `right_click` | 右键点击 |
-| `move` | 移动虚拟光标（不点击） |
-| `drag` | 按住 → 移动 → 松开。需 `start_coordinate` 指定起点 |
-| `down` | 按下左键不松 |
-| `up` | 松开左键 |
-
-**与通用鼠标工具的区别：**
-
-| | 通用 (`left_click` 等) | `virtual_mouse` |
-|---|---|---|
-| 输入方式 | SendInput（全局） | SendMessageW（窗口级） |
-| 真实鼠标 | 会移动 | **不动** |
-| 用户干扰 | 有 | **无** |
-| 适用场景 | 未绑定时 | **绑定后** |
-
-### 虚拟键盘
-
-| 工具 | 参数 | 说明 |
-|------|------|------|
-| `virtual_keyboard` | `action`, `text`, `duration?`, `repeat?` | 在绑定窗口内操作虚拟键盘 |
-
-**动作详情：**
-
-| action | text 含义 | 说明 |
-|--------|----------|------|
-| `type` | 要输入的文字 | SendMessageW(WM_CHAR)，支持 Unicode 中文/emoji |
-| `combo` | 组合键 (如 "ctrl+s") | WM_KEYDOWN/UP 序列 |
-| `press` | 单个键名 | 按下不松（配合 release 使用） |
-| `release` | 单个键名 | 松开按键 |
-| `hold` | 键名或组合 | 按住指定秒数后松开 |
-
-**与通用键盘工具的区别：**
-
-| | 通用 (`type`/`key`) | `virtual_keyboard` |
-|---|---|---|
-| 输入方式 | SendInput（全局） | SendMessageW（窗口级） |
-| 物理键盘 | 会冲突 | **不冲突** |
-| 适用场景 | 未绑定时 | **绑定后** |
-
-**注意：** SendMessageW 对 Windows Terminal (ConPTY) 等现代应用无效。这些应用需要使用通用工具 + 窗口激活方式操作。
-
-### 鼠标滚轮
-
-| 工具 | 参数 | 说明 |
-|------|------|------|
-| `mouse_wheel` | `coordinate: [x,y]`, `delta`, `direction?` | WM_MOUSEWHEEL 鼠标中键滚轮 |
-
-**参数说明：**
-- `delta`: 正值=向上，负值=向下。每 1 单位 ≈ 3 行
-- `direction`: "vertical"（默认）或 "horizontal"
-- `coordinate`: 滚轮作用点——决定哪个面板/区域接收滚动
-
-**与通用 `scroll` 的区别：**
-
-| | `scroll` | `mouse_wheel` |
-|---|---|---|
-| 原理 | WM_VSCROLL/WM_HSCROLL | **WM_MOUSEWHEEL** |
-| Excel | ❌ | ✅ |
-| 浏览器 | ❌ | ✅ |
-| 代码编辑器 | ❌ | ✅ |
-
-### 元素级操作
-
-| 工具 | 参数 | 说明 |
-|------|------|------|
-| `click_element` | `name?`, `role?`, `automationId?` | 按无障碍名称/角色点击 GUI 元素 |
-| `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 影响）
-
-### 终端交互
-
-| 工具 | 参数 | 说明 |
-|------|------|------|
-| `prompt_respond` | `response_type`, `arrow_direction?`, `arrow_count?`, `text?` | 处理终端 Yes/No/选择提示 |
-
-**response_type 详情：**
-
-| response_type | 操作 | 场景 |
-|---------------|------|------|
-| `yes` | 发送 'y' + Enter | npm "Continue? (y/n)" |
-| `no` | 发送 'n' + Enter | 拒绝确认 |
-| `enter` | 发送 Enter | 接受默认选项 |
-| `escape` | 发送 Escape | 取消操作 |
-| `select` | ↑/↓ 箭头 × N + Enter | inquirer 选择菜单 |
-| `type` | 输入文字 + Enter | 文本输入提示 |
-
-### 状态指示器
-
-| 工具 | 参数 | 说明 |
-|------|------|------|
-| `status_indicator` | `action`: show/hide/status, `message?` | 控制绑定窗口底部的浮动状态标签 |
-
----
-
-## 三、教学工具（3 个）
-
-需要 `teachMode` 开启。
-
-| 工具 | 说明 |
-|------|------|
-| `request_teach_access` | 请求教学引导模式权限 |
-| `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 (记事本/写字板) | ✅ | ✅ | 完美支持 |
-| Office (Excel/Word) | ✅ (COM 自动化) | ✅ | 通过 COM API |
-| WPF 应用 | ✅ | ✅ | 标准 UIA 支持 |
-| Electron/Chrome | ⚠️ 部分 | ⚠️ 部分 | 内部渲染不走 Win32 消息 |
-| UWP/WinUI (Windows Terminal) | ❌ | ❌ | ConPTY 不接受 SendMessageW |
-| 浏览器网页内容 | ❌ | ❌ | 需要全局 SendInput |
-
-**对于不支持 SendMessageW 的应用**，使用通用工具 (`left_click`/`type`/`key`) + `window_management(action="focus")` 先激活窗口。
-
----
-
-## 绑定窗口时的可视化
-
-绑定窗口后自动启动三层可视化：
-
-1. **DWM 绿色边框** — 窗口自身的边框颜色变绿，零偏移
-2. **虚拟鼠标光标** — 红色箭头图标，跟随 virtual_mouse 操作移动，点击时闪烁
-3. **状态指示器** — 窗口底部浮动标签，显示当前操作（通过 status_indicator 控制）
-
----
-
-## Accessibility Snapshot
-
-每次 `screenshot` 时，如果窗口已绑定，会自动附带 GUI 元素列表：
-
-```
-GUI elements in this window:
-[Button] "Save" (120,50 80x30) enabled
-[Edit] "" (200,80 400x25) enabled value="hello" id=textBox1
-[MenuItem] "File" (10,0 40x25) enabled
-[MenuItem] "Edit" (50,0 40x25) enabled
-[CheckBox] "Auto-save" (300,50 100x20) enabled id=chkAutoSave
-```
-
-模型同时收到 **截图图片 + 结构化元素列表**，可以选择：
-- 用坐标操作：`virtual_mouse(action="click", coordinate=[120, 50])`
-- 用名称操作：`click_element(name="Save")`
-
----
-
-## UI Automation Control Patterns 参考
-
-`click_element` / `type_into_element` 底层使用 UI Automation Control Patterns。当前已实现的和可扩展的：
-
-| Pattern | 用途 | 当前状态 | 可用于 |
-|---------|------|---------|--------|
-| `InvokePattern` | 触发点击 | ✅ 已实现 (`click_element`) | 按钮、菜单项、链接 |
-| `ValuePattern` | 读写文本值 | ✅ 已实现 (`type_into_element`) | 文本框、组合框 |
-| `TogglePattern` | 切换状态 | ❌ 未实现 | 复选框、开关 |
-| `SelectionPattern` | 选择项目 | ❌ 未实现 | 下拉菜单、列表 |
-| `ScrollPattern` | 编程滚动 | ❌ 未实现（用 `mouse_wheel` 替代） | 列表、树、面板 |
-| `ExpandCollapsePattern` | 展开/折叠 | ❌ 未实现 | 树节点、折叠面板 |
-| `WindowPattern` | 窗口操作 | ❌ 未实现（用 `window_management` 替代） | 窗口最大化/关闭 |
-| `TextPattern` | 读取文档文本 | ❌ 未实现 | 文档、富文本 |
-| `GridPattern` | 表格操作 | ❌ 未实现 | Excel 单元格、数据网格 |
-| `TablePattern` | 表格结构 | ❌ 未实现 | 表头、行列关系 |
-| `RangeValuePattern` | 范围值操作 | ❌ 未实现 | 滑块、进度条 |
-| `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
-# 限制：首次调用需要用户在系统弹窗中确认权限
-```
-
----
-
-## 输入方式技术矩阵
-
-不同应用类型需要不同的输入方式：
-
-| 输入方式 | API | 优势 | 限制 | 适用应用 |
-|---------|-----|------|------|---------|
-| **SendMessageW** | `WM_CHAR` / `WM_KEYDOWN` | 不抢焦点，不动真实键鼠 | 现代应用不支持 | Win32 传统应用 (记事本/Office/WPF) |
-| **SendInput** | `INPUT` 结构体 | 所有应用都支持 | **必须前台焦点**，会干扰用户 | 所有应用（通用后备） |
-| **WriteConsoleInput** | 控制台 API | 直接写入控制台缓冲区 | 需要 AttachConsole（可能被拒绝） | cmd/PowerShell（非 Windows Terminal） |
-| **UI Automation** | `InvokePattern` / `ValuePattern` | 语义级操作，最可靠 | 部分应用不暴露 UIA 接口 | 支持 UIA 的应用 |
-| **COM Automation** | Excel/Word COM | 完全编程控制 | 仅 Office 应用 | Excel / Word |
-| **剪贴板 + 粘贴** | `SetClipboardData` + `Ctrl+V` | 绕过输入限制 | 会覆盖用户剪贴板 | 通用后备 |
-
-### 按应用类型的推荐输入策略
-
-| 应用类型 | 首选 | 后备 | 说明 |
-|---------|------|------|------|
-| 传统 Win32 (记事本/写字板) | SendMessageW | UIA ValuePattern | 虚拟输入完美工作 |
-| Office (Excel/Word) | COM Automation | SendMessageW | COM 提供结构化操作 |
-| WPF 应用 | SendMessageW | UIA | 标准 Win32 消息循环 |
-| Electron/Chrome 应用 | UIA | 剪贴板粘贴 | 内部渲染不走 Win32 |
-| Windows Terminal (ConPTY) | SendInput (需前台) | 剪贴板粘贴 | ConPTY 不接受外部消息 |
-| UWP/WinUI 应用 | SendInput (需前台) | UIA | XAML 渲染不走 Win32 消息 |
-
----
-
-## 已知限制与待解决
-
-| 限制 | 影响 | 计划 |
-|------|------|------|
-| Windows Terminal 不接受 SendMessageW | 虚拟键盘/鼠标对终端无效 | 自动检测应用类型，终端类切换到 SendInput + 短暂激活 |
-| PrintWindow 截不到 alternate screen buffer | Ink REPL 画面截不到 | 切换到 Windows.Graphics.Capture |
-| Accessibility Snapshot 对大应用慢 (>30s) | Excel 等复杂应用超时 | 限制遍历深度 + 超时保护 |
-| DWM 边框对自定义标题栏应用可能无效 | 某些 Electron 应用看不到边框 | 检测并回退到叠加窗口方案 |
-| 虚拟光标是 PowerShell WinForms 进程 | 启动慢 (~1s)，资源占用 | 考虑用 Win32 原生窗口替代 |
-
----
-
-## 技术路线图
-
-### Phase 1（当前）— 基础功能
-- ✅ SendMessageW 虚拟输入
-- ✅ PrintWindow/mss 截图
-- ✅ UI Automation (InvokePattern + ValuePattern)
-- ✅ Accessibility Snapshot
-- ✅ DWM 边框指示
-- ✅ Python Bridge
-
-### Phase 2（近期）— 兼容性增强
-- ⬜ 应用类型自动检测（Win32 vs Terminal vs UWP）
-- ⬜ 终端类应用自动切换 SendInput + 短暂激活
-- ⬜ TogglePattern / SelectionPattern 支持
-- ⬜ DXGI Desktop Duplication 高速截图
-- ⬜ Accessibility Snapshot 超时保护
-
-### Phase 3（远期）— 高级能力
-- ⬜ Windows.Graphics.Capture（单窗口实时截图）
-- ⬜ 截图元素标注（在截图上标记 ID 数字）
-- ⬜ 浏览器 DOM 提取（绑定浏览器时提取网页结构）
-- ⬜ GridPattern / TablePattern（Excel 单元格级操作）
-- ⬜ TextPattern（文档内容读取）
-- ⬜ 多窗口协同操作

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

@@ -1,315 +0,0 @@
-# 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

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

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

docs/features/coordinator-mode.md

@@ -1,151 +0,0 @@
-# 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.md

@@ -1,102 +0,0 @@
-# DAEMON — 后台守护进程
-
-> Feature Flag: `FEATURE_DAEMON=1`
-> 实现状态：主进程和 worker 注册为 Stub，CLI 路由完整
-> 引用数：3
-
-## 一、功能概述
-
-DAEMON 将 Claude Code 变为后台守护进程。主进程（supervisor）管理多个 worker 进程的生命周期，通过 Unix 域套接字进行 IPC。适用于持续运行的后台服务场景（如配合 BRIDGE_MODE 提供远程控制服务）。
-
-## 二、实现架构
-
-### 2.1 模块状态
-
-| 模块 | 文件 | 状态 |
-|------|------|------|
-| 守护主进程 | `src/daemon/main.ts` | **Stub** — `daemonMain: () => Promise.resolve()` |
-| Worker 注册 | `src/daemon/workerRegistry.ts` | **Stub** — `runDaemonWorker: () => Promise.resolve()` |
-| CLI 路由 | `src/entrypoints/cli.tsx` | **布线** — `--daemon-worker` 和 `daemon` 子命令 |
-| 命令注册 | `src/commands.ts` | **布线** — DAEMON + BRIDGE_MODE 门控 |
-
-### 2.2 CLI 入口
-
-```
-# 启动守护进程
-claude daemon
-
-# 以 worker 身份启动
-claude --daemon-worker=<kind>
-```
-
-### 2.3 预期架构
-
-```
-Supervisor (daemonMain)
-      │
-      ├── Worker 1: assistant-mode
-      │   └── 接收和处理 assistant 会话
-      │
-      ├── Worker 2: bridge-sync
-      │   └── bridge 消息同步
-      │
-      └── Worker 3: proactive
-          └── 主动任务执行
-      │
-      ▼
-IPC via Unix Domain Sockets
-  - 生命周期管理（启动、停止、重启）
-  - 工作分发
-  - 状态报告
-```
-
-### 2.4 与 BRIDGE_MODE 的关系
-
-DAEMON 和 BRIDGE_MODE 常组合使用：
-
-```ts
-// src/commands.ts
-if (feature('DAEMON') && feature('BRIDGE_MODE')) {
-  // 加载 remoteControlServer 命令
-}
-```
-
-双重门控：两个 feature 都需要开启才能使用远程控制服务器。
-
-## 三、需要补全的内容
-
-| 模块 | 工作量 | 说明 |
-|------|--------|------|
-| `daemon/main.ts` | 大 | Supervisor 主进程：启动 worker、生命周期管理、IPC |
-| `daemon/workerRegistry.ts` | 中 | Worker 类型分发（assistant/bridge-sync/proactive） |
-| Worker 实现 | 大 | 各类型 worker 的具体实现 |
-| IPC 协议 | 中 | Supervisor-Worker 通信层 |
-
-## 四、关键设计决策
-
-1. **多进程架构**：一个 supervisor + 多个 worker，进程隔离
-2. **Unix 域套接字 IPC**：本地进程间通信，低延迟
-3. **与 BRIDGE_MODE 强绑定**：守护进程最常见的用途是提供远程控制服务
-4. **CLI 子命令路由**：`daemon` 子命令和 `--daemon-worker` 参数在 `cli.tsx` 中路由
-
-## 五、使用方式
-
-```bash
-# 启用守护进程模式
-FEATURE_DAEMON=1 FEATURE_BRIDGE_MODE=1 bun run dev
-
-# 启动守护进程
-claude daemon
-
-# 以特定 worker 启动
-claude --daemon-worker=assistant
-```
-
-## 六、文件索引
-
-| 文件 | 职责 |
-|------|------|
-| `src/daemon/main.ts` | Supervisor 主进程（stub） |
-| `src/daemon/workerRegistry.ts` | Worker 注册（stub） |
-| `src/entrypoints/cli.tsx:95,149` | CLI 路由 |
-| `src/commands.ts:77` | 命令注册（双重门控） |

docs/features/debug-mode.mdx

@@ -1,48 +0,0 @@
----
-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` 脚本实际执行的是：
-
-```bash
-bun --inspect-wait=localhost:8888/<token> run scripts/dev.ts
-```
-
-Bun 的 `--inspect-wait` 参数启动一个 Chrome DevTools Protocol 兼容的 inspect 服务，等待调试器连接后才开始执行。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

@@ -1,99 +0,0 @@
-# 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/channels.md

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

docs/features/external/chrome-control.md

@@ -0,0 +1,189 @@
+---
+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/computer-use.md

@@ -0,0 +1,621 @@
+---
+title: "屏幕控制（Computer Use）"
+description: "截屏、键鼠控制，跨 macOS / Windows / Linux。本文包含快速上手、平台差异说明和工具参考。"
+keywords: [屏幕控制, 截屏, 键鼠模拟, 跨平台自动化, Computer Use]
+---
+
+# 屏幕控制（Computer Use）
+
+Computer Use 提供截屏、键鼠控制和应用管理能力，支持 macOS / Windows / Linux 三大桌面平台。Windows 平台额外提供窗口绑定模式（不干扰真实键鼠），全平台共 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` 开启） |
+
+## 快速上手
+
+### 启用方式
+
+在启动 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` | — | 列出当前会话已授权的应用 |
+
+#### 截图与显示
+
+| 工具 | 参数 | 说明 |
+|------|------|------|
+| `screenshot` | `save_to_disk?` | 截取当前屏幕。绑定窗口时截取绑定窗口（PrintWindow）。返回图片 + GUI 元素列表（Windows） |
+| `zoom` | `region: [x1,y1,x2,y2]` | 截取指定区域的高分辨率图片。坐标基于最近一次全屏截图 |
+| `switch_display` | `display` | 切换截图的目标显示器 |
+
+#### 鼠标操作
+
+| 工具 | 参数 | 说明 |
+|------|------|------|
+| `left_click` | `coordinate: [x,y]`, `text?` (修饰键) | 左键点击。`text` 可传 "shift"/"ctrl"/"alt" 实现组合点击 |
+| `double_click` | `coordinate`, `text?` | 双击 |
+| `triple_click` | `coordinate`, `text?` | 三击（选整行） |
+| `right_click` | `coordinate`, `text?` | 右键点击 |
+| `middle_click` | `coordinate`, `text?` | 中键点击 |
+| `mouse_move` | `coordinate` | 移动鼠标（不点击） |
+| `left_click_drag` | `coordinate` (终点), `start_coordinate?` (起点) | 拖拽 |
+| `left_mouse_down` | — | 按下左键不松 |
+| `left_mouse_up` | — | 松开左键 |
+| `cursor_position` | — | 获取当前鼠标位置 |
+
+#### 键盘操作
+
+| 工具 | 参数 | 说明 |
+|------|------|------|
+| `type` | `text` | 输入文字 |
+| `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 平台可见。核心能力：**绑定窗口后的独立操作——不抢占用户鼠标键盘**。
+
+#### 工作模式
+
+```
+┌──────────────────────────────────────────────────┐
+│                  未绑定模式                        │
+│  使用通用工具 (left_click/type/key/scroll)          │
+│  操作对象：整个屏幕                                 │
+│  输入方式：全局 SendInput（会移动真实鼠标）           │
+└──────────────────────────────────────────────────┘
+                        │
+                  bind_window / open_application
+                        ▼
+┌──────────────────────────────────────────────────┐
+│                  绑定窗口模式                      │
+│  使用 Win32 工具 (virtual_mouse/virtual_keyboard)  │
+│  操作对象：绑定的窗口                               │
+│  输入方式：SendMessageW（不动真实鼠标/键盘）          │
+│  可视化：DWM 绿色边框 + 虚拟光标 + 状态指示器        │
+└──────────────────────────────────────────────────┘
+```
+
+#### 窗口绑定
+
+| 工具 | 参数 | 说明 |
+|------|------|------|
+| `bind_window` | `action`: list/bind/unbind/status | 窗口绑定管理 |
+
+**动作详情：**
+
+| action | 参数 | 说明 |
+|--------|------|------|
+| `list` | — | 列出所有可见窗口（hwnd、pid、title） |
+| `bind` | `title?`, `hwnd?`, `pid?` | 绑定到指定窗口。设置 DWM 绿色边框 + 启动虚拟光标 + 启动状态指示器 + 短暂激活窗口确保可接收输入 |
+| `unbind` | — | 解除绑定，恢复全屏模式 |
+| `status` | — | 查看当前绑定状态（hwnd、title、pid、窗口矩形） |
+
+#### 窗口管理
+
+| 工具 | 参数 | 说明 |
+|------|------|------|
+| `window_management` | `action`, `x?`, `y?`, `width?`, `height?` | 窗口操作（Win32 API，不走全局快捷键） |
+
+**动作详情：**
+
+| action | 说明 |
+|--------|------|
+| `minimize` | ShowWindow(SW_MINIMIZE) |
+| `maximize` | ShowWindow(SW_MAXIMIZE) |
+| `restore` | ShowWindow(SW_RESTORE) — 恢复最小化/最大化 |
+| `close` | SendMessage(WM_CLOSE) — 优雅关闭 |
+| `focus` | SetForegroundWindow + BringWindowToTop — 激活窗口 |
+| `move_offscreen` | SetWindowPos(-32000,-32000) — 移到屏幕外（仍可 SendMessage/PrintWindow） |
+| `move_resize` | SetWindowPos — 移动/缩放到指定位置和大小 |
+| `get_rect` | GetWindowRect — 获取当前位置和大小 |
+
+#### 虚拟鼠标
+
+| 工具 | 参数 | 说明 |
+|------|------|------|
+| `virtual_mouse` | `action`, `coordinate: [x,y]`, `start_coordinate?` | 在绑定窗口内操作虚拟鼠标 |
+
+**动作详情：**
+
+| action | 说明 |
+|--------|------|
+| `click` | 左键点击。虚拟光标移动到坐标 + 闪烁动画 |
+| `double_click` | 双击 |
+| `right_click` | 右键点击 |
+| `move` | 移动虚拟光标（不点击） |
+| `drag` | 按住 → 移动 → 松开。需 `start_coordinate` 指定起点 |
+| `down` | 按下左键不松 |
+| `up` | 松开左键 |
+
+**与通用鼠标工具的区别：**
+
+| | 通用 (`left_click` 等) | `virtual_mouse` |
+|---|---|---|
+| 输入方式 | SendInput（全局） | SendMessageW（窗口级） |
+| 真实鼠标 | 会移动 | **不动** |
+| 用户干扰 | 有 | **无** |
+| 适用场景 | 未绑定时 | **绑定后** |
+
+#### 虚拟键盘
+
+| 工具 | 参数 | 说明 |
+|------|------|------|
+| `virtual_keyboard` | `action`, `text`, `duration?`, `repeat?` | 在绑定窗口内操作虚拟键盘 |
+
+**动作详情：**
+
+| action | text 含义 | 说明 |
+|--------|----------|------|
+| `type` | 要输入的文字 | SendMessageW(WM_CHAR)，支持 Unicode 中文/emoji |
+| `combo` | 组合键 (如 "ctrl+s") | WM_KEYDOWN/UP 序列 |
+| `press` | 单个键名 | 按下不松（配合 release 使用） |
+| `release` | 单个键名 | 松开按键 |
+| `hold` | 键名或组合 | 按住指定秒数后松开 |
+
+**与通用键盘工具的区别：**
+
+| | 通用 (`type`/`key`) | `virtual_keyboard` |
+|---|---|---|
+| 输入方式 | SendInput（全局） | SendMessageW（窗口级） |
+| 物理键盘 | 会冲突 | **不冲突** |
+| 适用场景 | 未绑定时 | **绑定后** |
+
+**注意：** SendMessageW 对 Windows Terminal (ConPTY) 等现代应用无效。这些应用需要使用通用工具 + 窗口激活方式操作。
+
+#### 鼠标滚轮
+
+| 工具 | 参数 | 说明 |
+|------|------|------|
+| `mouse_wheel` | `coordinate: [x,y]`, `delta`, `direction?` | WM_MOUSEWHEEL 鼠标中键滚轮 |
+
+**参数说明：**
+
+- `delta`: 正值=向上，负值=向下。每 1 单位 ≈ 3 行
+- `direction`: "vertical"（默认）或 "horizontal"
+- `coordinate`: 滚轮作用点——决定哪个面板/区域接收滚动
+
+**与通用 `scroll` 的区别：**
+
+| | `scroll` | `mouse_wheel` |
+|---|---|---|
+| 原理 | WM_VSCROLL/WM_HSCROLL | **WM_MOUSEWHEEL** |
+| Excel | 否 | 是 |
+| 浏览器 | 否 | 是 |
+| 代码编辑器 | 否 | 是 |
+
+#### 元素级操作
+
+| 工具 | 参数 | 说明 |
+|------|------|------|
+| `click_element` | `name?`, `role?`, `automationId?` | 按无障碍名称/角色点击 GUI 元素 |
+| `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 影响）
+
+#### 终端交互
+
+| 工具 | 参数 | 说明 |
+|------|------|------|
+| `open_terminal` | `agent`, `command?` | 打开新终端窗口并启动 AI agent（claude/codex/gemini/custom）。自动绑定窗口并截图验证 |
+| `activate_window` | `click_x?`, `click_y?` | 激活绑定窗口：SetForegroundWindow + BringWindowToTop + 点击确保焦点 |
+| `prompt_respond` | `response_type`, `arrow_direction?`, `arrow_count?`, `text?` | 处理终端 Yes/No/选择提示 |
+
+**open_terminal agent 类型：**
+
+| agent | 命令 | 说明 |
+|-------|------|------|
+| `claude` | `claude` | 启动 Claude Code |
+| `codex` | `codex` | 启动 Codex |
+| `gemini` | `gemini` | 启动 Gemini |
+| `custom` | 用户指定 | 自定义命令 |
+
+**response_type 详情：**
+
+| response_type | 操作 | 场景 |
+|---------------|------|------|
+| `yes` | 发送 'y' + Enter | npm "Continue? (y/n)" |
+| `no` | 发送 'n' + Enter | 拒绝确认 |
+| `enter` | 发送 Enter | 接受默认选项 |
+| `escape` | 发送 Escape | 取消操作 |
+| `select` | ↑/↓ 箭头 × N + Enter | inquirer 选择菜单 |
+| `type` | 输入文字 + Enter | 文本输入提示 |
+
+#### 状态指示器
+
+| 工具 | 参数 | 说明 |
+|------|------|------|
+| `status_indicator` | `action`: show/hide/status, `message?` | 控制绑定窗口底部的浮动状态标签 |
+
+### 教学工具（3 个）
+
+需要 `teachMode` 开启。
+
+| 工具 | 说明 |
+|------|------|
+| `request_teach_access` | 请求教学引导模式权限 |
+| `teach_step` | 显示一步引导提示，等用户点 Next |
+| `teach_batch` | 批量排队多步引导 |
+
+## 进阶
+
+### 应用兼容性
+
+| 应用类型 | SendMessageW (virtual_*) | 元素操作 (click_element) | 注意 |
+|---------|--------------------------|------------------------|------|
+| 传统 Win32 (记事本/写字板) | 完美支持 | 完美支持 | 完美支持 |
+| Office (Excel/Word) | 支持（COM 自动化） | 支持 | 通过 COM API |
+| WPF 应用 | 支持 | 支持 | 标准 UIA 支持 |
+| Electron/Chrome | 部分支持 | 部分支持 | 内部渲染不走 Win32 消息 |
+| UWP/WinUI (Windows Terminal) | 不支持 | 不支持 | ConPTY 不接受 SendMessageW |
+| 浏览器网页内容 | 不支持 | 不支持 | 需要全局 SendInput |
+
+**对于不支持 SendMessageW 的应用**，使用通用工具 (`left_click`/`type`/`key`) + `window_management(action="focus")` 先激活窗口。
+
+### 绑定窗口时的可视化
+
+绑定窗口后自动启动三层可视化：
+
+1. **DWM 绿色边框** — 窗口自身的边框颜色变绿，零偏移
+2. **虚拟鼠标光标** — 红色箭头图标，跟随 virtual_mouse 操作移动，点击时闪烁
+3. **状态指示器** — 窗口底部浮动标签，显示当前操作（通过 status_indicator 控制）
+
+### Accessibility Snapshot
+
+每次 `screenshot` 时，如果窗口已绑定，会自动附带 GUI 元素列表：
+
+```
+GUI elements in this window:
+[Button] "Save" (120,50 80x30) enabled
+[Edit] "" (200,80 400x25) enabled value="hello" id=textBox1
+[MenuItem] "File" (10,0 40x25) enabled
+[MenuItem] "Edit" (50,0 40x25) enabled
+[CheckBox] "Auto-save" (300,50 100x20) enabled id=chkAutoSave
+```
+
+模型同时收到 **截图图片 + 结构化元素列表**，可以选择：
+
+- 用坐标操作：`virtual_mouse(action="click", coordinate=[120, 50])`
+- 用名称操作：`click_element(name="Save")`
+
+### UI Automation Control Patterns 参考
+
+`click_element` / `type_into_element` 底层使用 UI Automation Control Patterns。当前已实现的和可扩展的：
+
+| Pattern | 用途 | 当前状态 | 可用于 |
+|---------|------|---------|--------|
+| `InvokePattern` | 触发点击 | 已实现 (`click_element`) | 按钮、菜单项、链接 |
+| `ValuePattern` | 读写文本值 | 已实现 (`type_into_element`) | 文本框、组合框 |
+| `TogglePattern` | 切换状态 | 未实现 | 复选框、开关 |
+| `SelectionPattern` | 选择项目 | 未实现 | 下拉菜单、列表 |
+| `ScrollPattern` | 编程滚动 | 未实现（用 `mouse_wheel` 替代） | 列表、树、面板 |
+| `ExpandCollapsePattern` | 展开/折叠 | 未实现 | 树节点、折叠面板 |
+| `WindowPattern` | 窗口操作 | 未实现（用 `window_management` 替代） | 窗口最大化/关闭 |
+| `TextPattern` | 读取文档文本 | 未实现 | 文档、富文本 |
+| `GridPattern` | 表格操作 | 未实现 | Excel 单元格、数据网格 |
+| `TablePattern` | 表格结构 | 未实现 | 表头、行列关系 |
+| `RangeValuePattern` | 范围值操作 | 未实现 | 滑块、进度条 |
+| `TransformPattern` | 移动/缩放 | 未实现 | 可拖拽元素 |
+
+**扩展路线：** 优先实现 `TogglePattern`（复选框）和 `SelectionPattern`（下拉菜单），这两个在表单自动化中最常用。
+
+### 输入方式技术矩阵
+
+不同应用类型需要不同的输入方式：
+
+| 输入方式 | API | 优势 | 限制 | 适用应用 |
+|---------|-----|------|------|---------|
+| **SendMessageW** | `WM_CHAR` / `WM_KEYDOWN` | 不抢焦点，不动真实键鼠 | 现代应用不支持 | Win32 传统应用 (记事本/Office/WPF) |
+| **SendInput** | `INPUT` 结构体 | 所有应用都支持 | **必须前台焦点**，会干扰用户 | 所有应用（通用后备） |
+| **WriteConsoleInput** | 控制台 API | 直接写入控制台缓冲区 | 需要 AttachConsole（可能被拒绝） | cmd/PowerShell（非 Windows Terminal） |
+| **UI Automation** | `InvokePattern` / `ValuePattern` | 语义级操作，最可靠 | 部分应用不暴露 UIA 接口 | 支持 UIA 的应用 |
+| **COM Automation** | Excel/Word COM | 完全编程控制 | 仅 Office 应用 | Excel / Word |
+| **剪贴板 + 粘贴** | `SetClipboardData` + `Ctrl+V` | 绕过输入限制 | 会覆盖用户剪贴板 | 通用后备 |
+
+**按应用类型的推荐输入策略：**
+
+| 应用类型 | 首选 | 后备 | 说明 |
+|---------|------|------|------|
+| 传统 Win32 (记事本/写字板) | SendMessageW | UIA ValuePattern | 虚拟输入完美工作 |
+| Office (Excel/Word) | COM Automation | SendMessageW | COM 提供结构化操作 |
+| WPF 应用 | SendMessageW | UIA | 标准 Win32 消息循环 |
+| Electron/Chrome 应用 | UIA | 剪贴板粘贴 | 内部渲染不走 Win32 |
+| 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
+# 限制：首次调用需要用户在系统弹窗中确认权限
+```
+
+### 已知限制与待解决
+
+| 限制 | 影响 | 计划 |
+|------|------|------|
+| Windows Terminal 不接受 SendMessageW | 虚拟键盘/鼠标对终端无效 | 自动检测应用类型，终端类切换到 SendInput + 短暂激活 |
+| PrintWindow 截不到 alternate screen buffer | Ink REPL 画面截不到 | 切换到 Windows.Graphics.Capture |
+| Accessibility Snapshot 对大应用慢 (>30s) | Excel 等复杂应用超时 | 限制遍历深度 + 超时保护 |
+| DWM 边框对自定义标题栏应用可能无效 | 某些 Electron 应用看不到边框 | 检测并回退到叠加窗口方案 |
+| 虚拟光标是 PowerShell WinForms 进程 | 启动慢 (~1s)，资源占用 | 考虑用 Win32 原生窗口替代 |
+
+### 技术路线图
+
+#### Phase 1（当前）— 基础功能
+
+- SendMessageW 虚拟输入
+- PrintWindow/mss 截图
+- UI Automation (InvokePattern + ValuePattern)
+- Accessibility Snapshot
+- DWM 边框指示
+- Python Bridge
+
+#### Phase 2（近期）— 兼容性增强
+
+- 应用类型自动检测（Win32 vs Terminal vs UWP）
+- 终端类应用自动切换 SendInput + 短暂激活
+- TogglePattern / SelectionPattern 支持
+- DXGI Desktop Duplication 高速截图
+- Accessibility Snapshot 超时保护
+
+#### 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/external/voice-mode.md

@@ -0,0 +1,269 @@
+---
+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/external/web-browser-tool.md

@@ -0,0 +1,75 @@
+---
+title: "浏览器操作工具"
+description: "让 AI 控制 Chrome 完成网页操作：导航、点击、输入、抓取。"
+keywords: ["浏览器工具", "Chrome 控制", "网页操作", "Bun WebView", "WEB_BROWSER_TOOL"]
+---
+
+# WEB_BROWSER_TOOL — 浏览器工具
+
+> Feature Flag: `FEATURE_WEB_BROWSER_TOOL=1`
+> 实现状态：核心工具已实现，面板为 Stub，布线完整
+> 引用数：4
+
+## 一、功能概述
+
+WEB_BROWSER_TOOL 让模型可以启动浏览器实例、导航网页、与页面元素交互。使用 Bun 的内置 WebView API 提供无头/有头浏览器能力。
+
+## 二、实现架构
+
+### 2.1 模块状态
+
+| 模块 | 文件 | 状态 |
+|------|------|------|
+| 浏览器面板 | `packages/builtin-tools/src/tools/WebBrowserTool/WebBrowserPanel.ts` | **Stub** — 返回 null |
+| 浏览器工具 | `packages/builtin-tools/src/tools/WebBrowserTool/WebBrowserTool.ts` | **已实现** |
+| REPL 集成 | `src/screens/REPL.tsx` | **布线** — 渲染 WebBrowserPanel |
+| 工具注册 | `src/tools.ts` | **布线** — 动态加载 |
+| WebView 检测 | `src/main.tsx` | **布线** — `'WebView' in Bun` 检测 |
+
+### 2.2 预期数据流
+
+```
+模型调用 WebBrowserTool
+         │
+         ▼
+Bun WebView 创建浏览器实例
+         │
+         ├── navigate(url) — 导航到 URL
+         ├── click(selector) — 点击元素
+         ├── screenshot() — 截取页面截图
+         └── extract(selector) — 提取页面内容
+         │
+         ▼
+结果返回给模型
+         │
+         ▼
+WebBrowserPanel 在 REPL 侧边显示浏览器状态
+```
+
+## 三、需要补全的内容
+
+| 模块 | 工作量 | 说明 |
+|------|--------|------|
+| `WebBrowserTool.ts` | ✅ 已实现 | 工具 schema + Bun WebView API 执行 |
+| `WebBrowserPanel.tsx` | 中 | REPL 侧边栏浏览器状态面板（仍为 Stub） |
+
+## 四、关键设计决策
+
+1. **Bun WebView API**：使用 Bun 内置的 WebView 而非外部浏览器驱动（Puppeteer/Playwright）
+2. **REPL 侧边面板**：浏览器状态在 REPL 布局中独立渲染
+3. **Bun 特性检测**：`'WebView' in Bun` 检查运行时是否支持
+
+## 五、使用方式
+
+```bash
+FEATURE_WEB_BROWSER_TOOL=1 bun run dev
+```
+
+## 六、文件索引
+
+| 文件 | 职责 |
+|------|------|
+| `packages/builtin-tools/src/tools/WebBrowserTool/WebBrowserPanel.ts` | 面板组件（stub） |
+| `packages/builtin-tools/src/tools/WebBrowserTool/WebBrowserTool.ts` | 工具实现（已实现） |
+| `src/screens/REPL.tsx:471,5676` | 面板渲染 |
+| `src/tools.ts:115-116` | 工具注册 |

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

@@ -1,160 +0,0 @@
-# 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

@@ -1,195 +0,0 @@
-# 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 门控与互斥
-
-文件：`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
-
-文件：`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: "实现这个功能" })
-```
-
-## 八、文件索引
-
-| 文件 | 行数 | 职责 |
-|------|------|------|
-| `src/tools/AgentTool/forkSubagent.ts` | ~210 | 核心定义 + 消息构建 + 递归防护 |
-| `src/tools/AgentTool/AgentTool.tsx` | — | Fork 路由 + 强制异步 |
-| `src/tools/AgentTool/prompt.ts` | — | "When to Fork" 提示词段落 |
-| `src/tools/AgentTool/runAgent.ts` | — | useExactTools 路径 |
-| `src/tools/AgentTool/resumeAgent.ts` | — | Fork agent 恢复 |
-| `src/constants/xml.ts` | — | XML 标签常量 |
-| `src/utils/forkedAgent.ts` | — | CacheSafeParams + ContentReplacementState 克隆 |
-| `src/commands/fork/index.ts` | — | /fork 命令（stub） |

docs/features/growthbook-enablement-plan.md

@@ -1,334 +0,0 @@
-# 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

@@ -1,179 +0,0 @@
-# KAIROS — 常驻助手模式
-
-> Feature Flag: `FEATURE_KAIROS=1`（及子 Feature）
-> 实现状态：核心框架完整，部分子模块为 stub
-> 引用数：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:843-858`
-
-当 `feature('KAIROS') || feature('KAIROS_BRIEF')` 时注入。Brief 工具（`SendUserMessage`）的结构化消息输出指令。`/brief` toggle 和 `--brief` flag 只控制显示过滤，不影响模型行为。
-
-### 2.2 Proactive/Autonomous Work 段落 (`getProactiveSection`)
-
-文件：`src/constants/prompts.ts:860-914`
-
-当 `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
-- 与 `<tick_tag>` 配合实现心跳式自主工作
-
-### 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/services/mcp/channelNotification.ts` | 5 | 频道消息接入（stub） |
-| `src/memdir/memdir.ts` | — | 记忆目录管理（stub） |
-| `src/constants/prompts.ts:552-554,843-914` | 72 | 系统提示注入 |
-| `src/components/tasks/src/tasks/DreamTask/` | 3 | Dream 任务（stub） |
-| `src/proactive/index.ts` | — | Proactive 核心（stub，KAIROS 共享） |

docs/features/mcp-skills.md

@@ -1,118 +0,0 @@
-# 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:547-558`
-
-`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:117-121`
-
-`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` | 547-558, 561-608 | 命令过滤和 SkillTool 命令收集 |
-| `src/services/mcp/client.ts` | 117-121, 1394, 1672, 2173-2181, 2346-2358 | 技能获取、缓存清除、连接时获取 |
-| `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/modes/auto-dream.md

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

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

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

docs/features/proactive.md

@@ -1,109 +0,0 @@
-# PROACTIVE — 主动模式
-
-> Feature Flag: `FEATURE_PROACTIVE=1`（与 `FEATURE_KAIROS=1` 共享功能）
-> 实现状态：核心模块全部 Stub，布线完整
-> 引用数：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` | **Stub** | `activateProactive()`、`deactivateProactive()`、`isProactiveActive() => false` |
-| SleepTool 提示 | `src/tools/SleepTool/prompt.ts` | **完整** | 工具提示定义（工具名：`Sleep`） |
-| 命令注册 | `src/commands.ts:62-65` | **布线** | 动态加载 `./commands/proactive.js` |
-| 工具注册 | `src/tools.ts:26-28` | **布线** | SleepTool 动态加载 |
-| REPL 集成 | `src/screens/REPL.tsx` | **布线** | tick 驱动逻辑、占位符、页脚 UI |
-| 系统提示 | `src/constants/prompts.ts:860-914` | **完整** | 自主工作行为指令（~55 行详细 prompt） |
-| 会话存储 | `src/utils/sessionStorage.ts:4892-4912` | **布线** | tick 消息注入对话流 |
-
-### 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 等待 [需要实现]
-      │
-      ▼
-下一个 tick 到达
-```
-
-## 三、需要补全的内容
-
-| 优先级 | 模块 | 工作量 | 说明 |
-|--------|------|--------|------|
-| 1 | `src/proactive/index.ts` | 中 | Tick 调度器、activate/deactivate 状态机、pause/resume |
-| 2 | `src/tools/SleepTool/SleepTool.ts` | 小 | 工具执行（等待指定时间后触发 tick） |
-| 3 | `src/commands/proactive.js` | 小 | `/proactive` 斜杠命令处理器 |
-| 4 | `src/hooks/useProactive.ts` | 中 | React hook（REPL 引用但不存在） |
-
-## 四、关键设计决策
-
-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` | 核心逻辑（stub） |
-| `src/tools/SleepTool/prompt.ts` | SleepTool 工具提示 |
-| `src/constants/prompts.ts:860-914` | 自主工作系统提示 |
-| `src/screens/REPL.tsx` | REPL tick 集成 |
-| `src/utils/sessionStorage.ts:4892-4912` | Tick 消息注入 |
-| `src/components/PromptInput/PromptInputFooterLeftSide.tsx` | 页脚 UI 状态 |

docs/features/teammem.md

@@ -1,167 +0,0 @@
-# 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

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

docs/features/token-budget.md

@@ -1,198 +0,0 @@
-# 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:3829-3845` | 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/tools/langfuse-monitoring.md

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

docs/features/tree-sitter-bash.md

@@ -1,161 +0,0 @@
-# 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 分析辅助 |
-| `src/tools/BashTool/bashPermissions.ts:1670-1810` | ~140 | 权限集成 + Shadow 遥测 |

docs/features/ultraplan.md

@@ -1,107 +0,0 @@
-# ULTRAPLAN — 增强规划
-
-> Feature Flag: `FEATURE_ULTRAPLAN=1`
-> 实现状态：关键字检测完整，命令处理完整，CCR 远程会话完整
-> 引用数：10
-
-## 一、功能概述
-
-ULTRAPLAN 在用户输入中检测 "ultraplan" 关键字时，自动进入增强计划模式。相比普通 plan mode，ultraplan 提供更深入的规划能力，支持本地和远程（CCR）执行。
-
-### 触发方式
-
-| 方式 | 行为 |
-|------|------|
-| 输入含 "ultraplan" 的文本 | 自动重定向到 `/ultraplan` 命令 |
-| `/ultraplan` 斜杠命令 | 直接执行 |
-| 彩虹高亮 | 输入框中 "ultraplan" 关键字彩虹动画 |
-
-## 二、实现架构
-
-### 2.1 模块状态
-
-| 模块 | 文件 | 行数 | 状态 |
-|------|------|------|------|
-| 命令处理器 | `src/commands/ultraplan.tsx` | 472 | **完整** |
-| CCR 会话 | `src/utils/ultraplan/ccrSession.ts` | 350 | **完整** |
-| 关键字检测 | `src/utils/ultraplan/keyword.ts` | 128 | **完整** |
-| 嵌入式提示 | `src/utils/ultraplan/prompt.txt` | 1 | **完整** |
-| REPL 对话框 | `src/screens/REPL.tsx` | — | **布线** |
-| 关键字高亮 | `src/components/PromptInput/PromptInput.tsx` | — | **布线** |
-
-### 2.2 关键字检测
-
-文件：`src/utils/ultraplan/keyword.ts`（128 行）
-
-`findUltraplanTriggerPositions(text)` 智能过滤：
-- 排除引号内的 "ultraplan"
-- 排除路径中的 "ultraplan"（如 `/path/to/ultraplan/`）
-- 排除斜杠命令以外的上下文
-- `replaceUltraplanKeyword(text)` 清理关键字
-
-### 2.3 CCR 远程会话
-
-文件：`src/utils/ultraplan/ccrSession.ts`（350 行）
-
-`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` | 472 | 斜杠命令处理器 |
-| `src/utils/ultraplan/ccrSession.ts` | 350 | CCR 远程会话管理 |
-| `src/utils/ultraplan/keyword.ts` | 128 | 关键字检测和替换 |
-| `src/utils/ultraplan/prompt.txt` | 1 | 嵌入式提示 |
-| `src/utils/processUserInput/processUserInput.ts:468` | — | 关键字重定向 |
-| `src/components/PromptInput/PromptInput.tsx` | — | 彩虹高亮 |

docs/features/voice-mode.md

@@ -1,125 +0,0 @@
-# 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` | 55 | 三层门控逻辑 |
-| `src/hooks/useVoice.ts` | — | React hook（录音状态 + WebSocket） |
-| `src/services/voiceStreamSTT.ts` | — | STT WebSocket 流式传输 |

docs/features/web-browser-tool.md

@@ -1,69 +0,0 @@
-# WEB_BROWSER_TOOL — 浏览器工具
-
-> Feature Flag: `FEATURE_WEB_BROWSER_TOOL=1`
-> 实现状态：核心实现缺失，面板为 Stub，布线完整
-> 引用数：4
-
-## 一、功能概述
-
-WEB_BROWSER_TOOL 让模型可以启动浏览器实例、导航网页、与页面元素交互。使用 Bun 的内置 WebView API 提供无头/有头浏览器能力。
-
-## 二、实现架构
-
-### 2.1 模块状态
-
-| 模块 | 文件 | 状态 |
-|------|------|------|
-| 浏览器面板 | `src/tools/WebBrowserTool/WebBrowserPanel.ts` | **Stub** — 返回 null |
-| 浏览器工具 | `src/tools/WebBrowserTool/WebBrowserTool.ts` | **缺失** |
-| REPL 集成 | `src/screens/REPL.tsx` | **布线** — 渲染 WebBrowserPanel |
-| 工具注册 | `src/tools.ts` | **布线** — 动态加载 |
-| WebView 检测 | `src/main.tsx` | **布线** — `'WebView' in Bun` 检测 |
-
-### 2.2 预期数据流
-
-```
-模型调用 WebBrowserTool
-         │
-         ▼
-Bun WebView 创建浏览器实例
-         │
-         ├── navigate(url) — 导航到 URL
-         ├── click(selector) — 点击元素
-         ├── screenshot() — 截取页面截图
-         └── extract(selector) — 提取页面内容
-         │
-         ▼
-结果返回给模型
-         │
-         ▼
-WebBrowserPanel 在 REPL 侧边显示浏览器状态
-```
-
-## 三、需要补全的内容
-
-| 模块 | 工作量 | 说明 |
-|------|--------|------|
-| `WebBrowserTool.ts` | 大 | 工具 schema + Bun WebView API 执行 |
-| `WebBrowserPanel.tsx` | 中 | REPL 侧边栏浏览器状态面板 |
-
-## 四、关键设计决策
-
-1. **Bun WebView API**：使用 Bun 内置的 WebView 而非外部浏览器驱动（Puppeteer/Playwright）
-2. **REPL 侧边面板**：浏览器状态在 REPL 布局中独立渲染
-3. **Bun 特性检测**：`'WebView' in Bun` 检查运行时是否支持
-
-## 五、使用方式
-
-```bash
-FEATURE_WEB_BROWSER_TOOL=1 bun run dev
-```
-
-## 六、文件索引
-
-| 文件 | 职责 |
-|------|------|
-| `src/tools/WebBrowserTool/WebBrowserPanel.ts` | 面板组件（stub） |
-| `src/tools/WebBrowserTool/WebBrowserTool.ts` | 工具实现（缺失） |
-| `src/screens/REPL.tsx:273,4582` | 面板渲染 |
-| `src/tools.ts:115-116` | 工具注册 |

docs/features/web-search-tool.md

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

docs/features/workflow-scripts.md

@@ -1,105 +0,0 @@
-# WORKFLOW_SCRIPTS — 工作流自动化
-
-> Feature Flag: `FEATURE_WORKFLOW_SCRIPTS=1`
-> 实现状态：全部 Stub（7 个文件），布线完整
-> 引用数：10
-
-## 一、功能概述
-
-WORKFLOW_SCRIPTS 实现基于文件的多步自动化工作流。用户可以定义 YAML/JSON 格式的工作流描述文件，系统将其解析为可执行的多 agent 步骤序列。提供 `/workflows` 命令管理和触发工作流。
-
-## 二、实现架构
-
-### 2.1 模块状态
-
-| 模块 | 文件 | 状态 |
-|------|------|------|
-| WorkflowTool | `src/tools/WorkflowTool/WorkflowTool.ts` | **Stub** — 空对象 |
-| Workflow 权限 | `src/tools/WorkflowTool/WorkflowPermissionRequest.ts` | **Stub** — 返回 null |
-| 常量 | `src/tools/WorkflowTool/constants.ts` | **Stub** — 空工具名 |
-| 命令创建 | `src/tools/WorkflowTool/createWorkflowCommand.ts` | **Stub** — 空操作 |
-| 捆绑工作流 | `src/tools/WorkflowTool/bundled/` | **缺失** — 目录不存在 |
-| 本地工作流任务 | `src/tasks/LocalWorkflowTask/LocalWorkflowTask.ts` | **Stub** — 类型 + 空操作 |
-| UI 任务组件 | `src/components/tasks/src/tasks/LocalWorkflowTask/` | **Stub** — 空导出 |
-| 详情对话框 | `src/components/tasks/WorkflowDetailDialog.ts` | **Stub** — 返回 null |
-| 任务注册 | `src/tasks.ts` | **布线** — 动态加载 |
-| 工具注册 | `src/tools.ts` | **布线** — 包含 bundled 工作流初始化 |
-| 命令注册 | `src/commands.ts` | **布线** — `/workflows` 命令 |
-
-### 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` | 大 | Schema 定义 + 多步执行引擎 |
-| 2 | `bundled/index.js` | 中 | 内置工作流定义（initBundledWorkflows） |
-| 3 | `createWorkflowCommand.ts` | 中 | 从文件解析创建命令对象 |
-| 4 | `LocalWorkflowTask.ts` | 大 | 步骤协调、kill/skip/retry |
-| 5 | `WorkflowDetailDialog.ts` | 中 | 进度详情 UI |
-| 6 | `WorkflowPermissionRequest.ts` | 小 | 权限对话框 |
-| 7 | `constants.ts` | 小 | 工具名常量 |
-
-## 四、关键设计决策
-
-1. **基于文件的 DSL**：工作流定义为文件（YAML/JSON），版本控制友好
-2. **多 Agent 步骤**：每个步骤是独立的 agent 任务，支持并行/串行
-3. **内置工作流**：`bundled/` 目录提供开箱即用的常用工作流
-4. **/workflows 命令**：统一的发现和触发入口
-
-## 五、使用方式
-
-```bash
-# 启用 feature（需要补全后才能真正使用）
-FEATURE_WORKFLOW_SCRIPTS=1 bun run dev
-```
-
-## 六、文件索引
-
-| 文件 | 职责 |
-|------|------|
-| `src/tools/WorkflowTool/WorkflowTool.ts` | 工具定义（stub） |
-| `src/tools/WorkflowTool/WorkflowPermissionRequest.ts` | 权限对话框（stub） |
-| `src/tools/WorkflowTool/constants.ts` | 常量（stub） |
-| `src/tools/WorkflowTool/createWorkflowCommand.ts` | 命令创建（stub） |
-| `src/tasks/LocalWorkflowTask/LocalWorkflowTask.ts` | 任务协调（stub） |
-| `src/components/tasks/WorkflowDetailDialog.ts` | 详情对话框（stub） |
-| `src/tools.ts:127-132` | 工具注册 |
-| `src/commands.ts:86-89` | 命令注册 |

docs/getting-started/installation.mdx

@@ -0,0 +1,125 @@
+---
+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

@@ -0,0 +1,165 @@
+---
+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

@@ -0,0 +1,128 @@
+---
+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

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

docs/internals/feature-flags.mdx

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

docs/internals/growthbook-ab-testing.mdx

@@ -1,120 +0,0 @@
----
-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`（1156 行），工作流程如下：
-
-<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

@@ -1,133 +0,0 @@
----
-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-napi` 包（在反编译版本中已 stub）：
-
-    - 通过 `/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 编程同事**。

docs/internals/three-tier-gating.mdx

@@ -1,87 +0,0 @@
----
-title: "三层门禁系统 - 功能可见性控制架构"
-description: "详解 Claude Code 三层门禁系统：构建时 feature()、运行时 GrowthBook 和身份层 USER_TYPE，如何控制功能的可见性和灰度发布。"
-keywords: ["门禁系统", "功能门控", "feature flag", "灰度发布", "可见性控制"]
----
-
-{/* 本章目标：建立对三层门禁系统的全局认知，为后续四篇深入文章奠定坐标系 */}
-
-## 冰山一角
-
-你日常使用的 Claude Code，只是完整代码库的冰山一角。
-
-逆向工程揭示了一个事实：大量功能被精心"藏"在三层独立的门禁系统之后。有些是正在 A/B 测试的实验性功能，有些是仅限 Anthropic 员工使用的内部工具，还有些是尚未对外发布的下一代能力。
-
-> 我们在 `src/` 中发现了 88+ 个构建时 feature flags、500+ 个运行时 A/B 测试标记，以及一整套身份门控机制。
-
-## 三层门禁全景
-
-| 维度 | 第一层：构建时 `feature()` | 第二层：运行时 GrowthBook | 第三层：身份 `USER_TYPE` |
-|------|---------------------------|--------------------------|-------------------------|
-| **控制方式** | `bun:bundle` 编译时宏 | GrowthBook SDK 远程求值 | 构建时 `--define` 常量 |
-| **决策时机** | 打包时（代码直接被删除） | 启动时 + 定期刷新 | 打包时（常量折叠） |
-| **粒度** | 全有或全无 | 按用户/设备/组织定向 | 按构建版本（ant / external） |
-| **标记数量** | 88+ | 500+ (`tengu_*` 前缀) | 1（`ant` vs `external`） |
-| **逆向可见性** | 代码残留，但永远走 `false` 分支 | 完整 SDK 代码可读 | 条件分支清晰可见 |
-
-## 决策流程
-
-当一个功能请求进入 Claude Code，它会依次经过三层门禁的检查：
-
-```
-功能请求
-  │
-  ▼
-┌─────────────────────────┐
-│  第一层：feature('X')    │ ──── 编译时已决定 ──→ false → 代码被 DCE 移除
-│  (构建时 Feature Flag)   │
-└─────────┬───────────────┘
-          │ true (仅内部构建)
-          ▼
-┌─────────────────────────┐
-│  第二层：tengu_xxx       │ ──── 运行时按用户属性 ──→ 不在实验组 → 功能关闭
-│  (GrowthBook A/B 测试)   │
-└─────────┬───────────────┘
-          │ 在实验组
-          ▼
-┌─────────────────────────┐
-│  第三层：USER_TYPE       │ ──── ant? external? ──→ external → 功能不可用
-│  (身份门控)              │
-└─────────┬───────────────┘
-          │ ant
-          ▼
-      功能可用 ✓
-```
-
-三层门禁**相互独立**，一个功能可能同时受多层控制。例如，KAIROS 助手模式同时需要 `feature('KAIROS')` 构建时开启 **和** `tengu_kairos` 运行时实验命中。
-
-## 逆向工程揭示了什么
-
-在这个反编译版本中：
-
-- **第一层**完全透明——`feature()` 被兜底为 `() => false`，所有 88+ 个 flag 的代码路径都可以阅读，只是永远不会执行
-- **第二层**完整保留——GrowthBook SDK 的 1156 行代码完整可读，包括用户定向属性、缓存策略、覆盖机制
-- **第三层**清晰可见——`process.env.USER_TYPE === 'ant'` 出现在 60+ 个位置，每一处都标记着"仅限内部"的功能边界
-
-<Note>
-这三层门禁不是安全机制——它们是产品发布策略。目的是让 Anthropic 能够在不同用户群体中渐进式地测试和发布功能，而不是阻止逆向工程。
-</Note>
-
-## 接下来
-
-后续四篇文章将分别深入每一层门禁的细节：
-
-<CardGroup cols={2}>
-  <Card title="88 面旗帜" icon="flag" href="/docs/internals/feature-flags">
-    构建时 Feature Flags 的完整分类与解读
-  </Card>
-  <Card title="千面千人" icon="flask" href="/docs/internals/growthbook-ab-testing">
-    GrowthBook A/B 测试体系的运作机制
-  </Card>
-  <Card title="未公开功能巡礼" icon="eye" href="/docs/internals/hidden-features">
-    KAIROS、PROACTIVE 等 8 大隐藏功能深度解析
-  </Card>
-  <Card title="Ant 的特权世界" icon="shield" href="/docs/internals/ant-only-world">
-    Anthropic 员工专属的工具、命令与 API
-  </Card>
-</CardGroup>

docs/introduction/architecture-overview.mdx

@@ -1,112 +0,0 @@
----
-title: "架构全景 - Claude Code 五层架构详解"
-description: "从交互层到基础设施层，详解 Claude Code 的五层架构设计。基于 src/main.tsx、src/QueryEngine.ts、src/query.ts、src/tools.ts、src/services/api/claude.ts 的源码级数据流分析。"
-keywords: ["Claude Code 架构", "五层架构", "QueryEngine", "Agentic Loop", "数据流"]
----
-
-{/* 本章目标：一张图讲清楚整体架构，为后续章节建立坐标系 */}
-
-## 五层架构
-
-Claude Code 从上到下分为五个层次，每一层职责清晰、边界分明：
-
-<Frame caption="Claude Code 五层架构">
-  <img src="/docs/images/architecture-layers.png" alt="Claude Code 五层架构图" />
-</Frame>
-
-| 层次 | 职责 | 入口源码 | 关键词 |
-|------|------|---------|--------|
-| **交互层** | 终端 UI、用户输入、消息展示 | `src/screens/REPL.tsx` | React/Ink、PromptInput |
-| **编排层** | 多轮对话、会话持久化、成本追踪 | `src/QueryEngine.ts` | QueryEngine、transcript |
-| **核心循环层** | 单轮：发请求 → 拿响应 → 执行工具 → 循环 | `src/query.ts` | Agentic Loop、State |
-| **工具层** | AI 的"双手"——读写文件、执行命令 | `src/tools.ts` → `src/Tool.ts` | Tool 接口、MCP |
-| **通信层** | 与 Claude API 的流式通信 | `src/services/api/claude.ts` | Streaming、Provider |
-
-## 一条主数据流的源码追踪
-
-<Frame caption="核心数据流">
-  <img src="/docs/images/data-flow.png" alt="Claude Code 核心数据流" />
-</Frame>
-
-整个系统的运转可以浓缩为一条核心数据流，以下是每一步对应的源码路径：
-
-### 1. 用户输入 → REPL
-
-`src/screens/REPL.tsx` 是基于 React/Ink 的终端 UI 组件。用户输入经 `processUserInput()`（`src/utils/processUserInput/processUserInput.ts`）处理，支持斜杠命令、文件附件、图片等。
-
-### 2. QueryEngine 编排
-
-`src/QueryEngine.ts` 是 REPL 与 `query()` 之间的中间层，管理：
-- **会话状态**：消息数组、工具权限上下文（`ToolPermissionContext`）、文件历史快照
-- **成本追踪**：`accumulateUsage()` / `getTotalCost()` 累计 token 用量
-- **Transcript 持久化**：`recordTranscript()` 将对话序列化到磁盘，支持 `--resume`
-- **文件历史**：`fileHistoryMakeSnapshot()` 在修改前创建快照，支持 undo
-
-关键方法：`queryEngine.query()` 构造 `QueryParams`，调用 `query()` 异步生成器。
-
-### 3. Agentic Loop（`src/query.ts`）
-
-`query()` 是一个 `AsyncGenerator`，`while(true)` 循环的每次迭代包含：
-
-```
-① 上下文预处理管道：
-   applyToolResultBudget → snipCompact → microcompact → contextCollapse → autocompact
-
-② 流式 API 调用：
-   deps.callModel() → AsyncGenerator<StreamEvent | Message>
-   收集 assistantMessages[]、toolUseBlocks[]
-
-③ 工具执行：
-   StreamingToolExecutor（并行） 或 runTools（串行）
-   → toolResults[]
-
-④ 终止/继续判定：
-   needsFollowUp ? continue : return { reason }
-```
-
-完整的状态机通过 `State` 类型（`src/query.ts:204`）在迭代间传递，包含 10 个字段（messages、autoCompactTracking、maxOutputTokensRecoveryCount 等）。
-
-### 4. 工具层（`src/tools.ts` → `src/Tool.ts`）
-
-`getAllBaseTools()`（`src/tools.ts:191`）组装 50+ 工具列表，经过 `filterToolsByDenyRules()` 权限过滤后传给 API。
-
-每个工具实现 `Tool<Input, Output, Progress>` 接口（`src/Tool.ts:362`），核心方法链：
-```
-validateInput() → canUseTool()（UI 层）→ checkPermissions() → call() → ToolResult
-```
-
-### 5. 通信层（`src/services/api/claude.ts`）
-
-API 客户端支持 4 种 Provider：
-- **Anthropic Direct**：默认
-- **AWS Bedrock**：`ANTHROPIC_BEDROCK_BASE_URL`
-- **Google Vertex**：`ANTHROPIC_VERTEX_PROJECT_ID`
-- **Azure**：通过自定义 base URL
-
-`deps.callModel()` 发起流式请求，返回 `BetaRawMessageStreamEvent` 事件流。支持 Prompt Cache（`cache_control`）、thinking blocks、multi-turn tool use。
-
-## 四个核心设计原则
-
-<AccordionGroup>
-  <Accordion title="流式优先 (Streaming-first)">
-    所有 API 通信都是流式的——`deps.callModel()` 返回 AsyncGenerator，用户看到 AI "逐字打出"回答。StreamingToolExecutor 在流式过程中就开始并行执行工具，不等流结束。模型降级（Fallback）时，已收集的 assistantMessages 被标记为 tombstone 并清空，重试整个流式请求。
-  </Accordion>
-  <Accordion title="工具即能力 (Tool as Capability)">
-    每个工具是 `Tool<Input, Output, Progress>` 结构化类型，通过 `buildTool()` 工厂创建。`getTools()` 在每次 API 调用时组装（非全局缓存），因为 `isEnabled()` 可能随运行时状态变化。MCP 工具通过 `mcpInfo` 字段标记来源，支持 server 级别的 blanket deny。
-  </Accordion>
-  <Accordion title="权限即边界 (Permission as Boundary)">
-    每次工具调用经过 `validateInput() → checkPermissions()` 双重检查。权限规则从 5 个来源汇聚（session → project → user → managed → default），支持工具名、命令模式、路径前缀等匹配方式。Plan Mode 通过 `prepareContextForPlanMode()` 切换为只读模式，退出时自动恢复。
-  </Accordion>
-  <Accordion title="上下文即记忆 (Context as Memory)">
-    System Prompt 由 `fetchSystemPromptParts()` 动态组装，包含 CLAUDE.md、git 状态、日期、MCP 服务器列表。Auto-compact 在每轮迭代前评估 token 阈值，超出时触发压缩。压缩后的摘要通过 `buildPostCompactMessages()` 替换原始消息，`taskBudgetRemaining` 跨压缩边界累计。
-  </Accordion>
-</AccordionGroup>
-
-## 入口与引导
-
-| 入口 | 文件 | 说明 |
-|------|------|------|
-| CLI 启动 | `src/entrypoints/cli.tsx` | 注入 `feature()` polyfill（始终返回 false）、MACRO 全局变量 |
-| 命令定义 | `src/main.tsx` | Commander.js 解析参数，初始化 auth/analytics/policy |
-| 一次性初始化 | `src/entrypoints/init.ts` | 遥测配置、信任对话框 |
-| 管道模式 | `src/main.tsx` `-p` flag | `echo "say hello" \| bun run dev -p` |

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

@@ -1,111 +0,0 @@
----
-title: "什么是 Claude Code - Terminal Native Agentic Coding System"
-description: "Claude Code 是运行在终端中的 agentic coding system，直接在你的项目目录中读代码、改文件、跑命令、调试程序。了解它的技术定位、架构差异和核心能力。"
-keywords: ["Claude Code", "AI 编程助手", "Agentic Coding", "终端 AI", "CLI AI"]
-og:image: "https://ccb.agent-aura.top/docs/images/og-cover.png"
----
-
-## 一句话定义
-
-Claude Code 是一个**运行在本地终端中的 agentic coding system**。它不是给建议的聊天机器人——它直接在你的项目目录中读代码、改文件、跑命令、调试程序，拥有完整的 shell 能力。
-
-## 技术定位：terminal-native agentic system
-
-理解 Claude Code 的关键在于三个词：
-
-| 定位关键词 | 含义 |
-|-----------|------|
-| **Terminal-native** | 原生 CLI 应用，不是 IDE 插件、不是 Web 界面、不是 API wrapper |
-| **Agentic** | AI 自主决策工具调用链，不是"一问一答"的聊天模式 |
-| **Coding system** | 面向软件工程全流程，不是通用问答工具 |
-
-与同类工具的**架构层面**差异（不是功能清单）：
-
-| 工具 | 架构模式 | 运行位置 | 工具执行 |
-|------|----------|----------|----------|
-| **Claude Code** | Terminal-native agentic loop | 本地进程 | 直接 shell 执行 |
-| Cursor / Copilot | IDE-integrated autocomplete + chat | IDE 进程内 | LSP / IDE API |
-| Aider | CLI chat → git patch | 本地进程 | 文件操作为主 |
-| ChatGPT / Claude.ai | Cloud chat + artifacts | 浏览器/云端 | 沙箱容器 |
-
-核心差异：Claude Code 拥有**完整的 shell 访问权**——这意味着它可以做任何你在终端里能做的事，但也需要对应的安全机制来约束这个能力。
-
-## 端到端示例：从输入到输出
-
-当你在终端中输入 `bun run dev 有个 TypeScript 报错，帮我修一下` 时，系统发生了什么？
-
-```
-┌─────────────────────────────────────────────────────────┐
-│ 1. 入口层 (cli.tsx → main.tsx)                          │
-│    feature() = false, MACRO 注入, 启动 Commander.js CLI  │
-├─────────────────────────────────────────────────────────┤
-│ 2. 交互层 (REPL.tsx — React/Ink)                        │
-│    PromptInput 捕获用户输入 → UserMessage 加入会话       │
-├─────────────────────────────────────────────────────────┤
-│ 3. 编排层 (QueryEngine.ts)                               │
-│    管理 turn 生命周期、token 预算、compaction 触发       │
-├─────────────────────────────────────────────────────────┤
-│ 4. 核心循环 (query.ts — Agentic Loop)                    │
-│    组装上下文 → 调 API → 收流式响应 → 解析工具调用      │
-│    → 权限检查 → 执行工具 → 结果回传 → 再次调 API → 循环 │
-├─────────────────────────────────────────────────────────┤
-│ 5. 工具执行 (BashTool.call / FileEditTool.call / ...)    │
-│    实际执行: 读文件、运行命令、搜索代码...               │
-├─────────────────────────────────────────────────────────┤
-│ 6. 通信层 (claude.ts → Anthropic API)                    │
-│    流式 HTTP, 支持 Bedrock/Vertex/Azure 多 provider      │
-└─────────────────────────────────────────────────────────┘
-```
-
-具体到这个报错修复场景，一次典型的 agentic loop 可能包含多轮工具调用：
-
-| Turn | AI 决策 | 工具调用 | 结果 |
-|------|---------|----------|------|
-| 1 | 先看报错信息 | `Bash("bun run dev 2>&1 | head -30")` | TypeScript 错误输出 |
-| 2 | 定位到文件 | `Read("src/utils/foo.ts")` | 源代码内容 |
-| 3 | 搜索相关类型定义 | `Grep("interface Foo", "src/")` | 类型定义位置 |
-| 4 | 修复代码 | `FileEdit(old, new)` | 代码已修改 |
-| 5 | 验证修复 | `Bash("bun run dev 2>&1 | head -10")` | 编译通过 |
-
-每一步都是 AI 自主决策的——它决定用哪个工具、传什么参数、何时停止。这就是 "agentic" 的含义。
-
-## 它不是什么
-
-- **不是 IDE 插件**：没有图形界面，不依赖 VS Code 或任何 IDE
-- **不是 API wrapper**：它有自己的工具系统、权限模型、上下文工程、会话管理
-- **不是聊天机器人**：输出不是纯文本，而是实际的文件修改、命令执行
-- **不是无脑执行器**：每个敏感操作都有权限检查和用户确认环节
-
-## 启动入口解剖
-
-真正的代码入口是 `src/entrypoints/cli.tsx`，它做了三件关键的事：
-
-```typescript
-// 1. 注入运行时 polyfill —— feature() 永远返回 false
-const feature = (_name: string) => false;
-
-// 2. 注入构建时宏
-globalThis.MACRO = { VERSION: "2.1.888", BUILD_TIME: ..., };
-
-// 3. 声明构建目标
-globalThis.BUILD_TARGET = "external";  // 外部构建（非 Anthropic 内部）
-globalThis.BUILD_ENV = "production";
-globalThis.INTERFACE_TYPE = "stdio";   // 标准 I/O 交互
-```
-
-然后控制流传递到 `src/main.tsx`：
-1. Commander.js 解析命令行参数
-2. 初始化认证、遥测、策略限制
-3. 加载工具列表（`getTools()`）
-4. 启动 REPL（`launchRepl()`）或管道模式（`-p`）
-
-## 为什么选择终端
-
-终端不是限制，而是选择。它带来了独特的能力：
-
-- **完整的 shell 访问**：可以运行任何命令行工具，无需为每个能力写插件
-- **项目原生**：直接在项目目录工作，理解文件系统结构、git 状态
-- **可组合性**：管道模式（`echo "..." | claude -p`）允许嵌入 CI/CD 和自动化流程
-- **低延迟**：没有 Electron 开销，React/Ink 渲染的 TUI 响应极快
-
-代价是用户需要适应命令行界面——但也正因如此，它吸引的是需要**真正掌控开发环境**的开发者。