fix: 修复 Bun 的 polyfill 问题

2026-06-15 21:05:51 +00:00 · 2026-04-15 10:04:39 +08:00
2923 changed files with 99706 additions and 206350 deletions
--- a/.claude/skills/teach-me/SKILL.md
+++ b/.claude/skills/teach-me/SKILL.md
@@ -41,8 +41,7 @@ All teach-me data is stored under `.claude/skills/teach-me/records/`:
 .claude/skills/teach-me/records/
 ├── learner-profile.md     # Cross-topic notes (created on first session)
 └── {topic-slug}/
-    ├── session.md         # Learning state: concepts, status, notes
-    └── {topic-slug}-notes.md  # Learner-facing summary notes (generated at session end)
+    └── session.md         # Learning state: concepts, status, notes
 ```

 **Slug**: Topic in kebab-case, 2-5 words. Example: "Python decorators" → `python-decorators`
@@ -276,8 +275,7 @@ Update `session.md` after each round:
 When all concepts mastered or user ends session:

 1. Update `session.md` with final state.
-2. **Generate learner-facing notes** — write `{topic-slug}-notes.md` in the topic directory. This is a standalone reference document the learner can review later. See "Notes Generation" below for format.
-3. Update `.claude/skills/teach-me/records/learner-profile.md` (keep under 30 lines):
+2. Update `.claude/skills/teach-me/records/learner-profile.md` (keep under 30 lines):

 ```markdown
 # Learner Profile
@@ -295,48 +293,7 @@ Updated: {timestamp}
 - Python decorators (8/10 concepts, 2025-01-15)
 ```

-4. Give a brief text summary of what was covered, key insights, and areas for further study.
-
-## 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.
+3. Give a brief text summary of what was covered, key insights, and areas for further study.

 ## Resuming Sessions

--- a/.editorconfig
+++ b/.editorconfig
@@ -1,8 +1,8 @@
 root = true

 [*]
-indent_style = space
-indent_size = 2
+indent_style = tab
+indent_size = 4
 end_of_line = lf
 charset = utf-8
 trim_trailing_whitespace = true
--- a/.githooks/pre-commit
+++ b/.githooks/pre-commit
@@ -0,0 +1,22 @@
+#!/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
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -1,52 +0,0 @@
---
-name: Bug 报告
-description: 报告一个可复现的 bug
-title: "bug: "
-labels: ["bug"]
-assignees: []
---
-
-## 发帖前必读
-
- [ ] 我已经搜索过 [现有 Issues](https://github.com/claude-code-best/claude-code/issues)，没有找到重复。
- [ ] 我使用的是 **最新版本**（`bun run build` 或最新 release）。
- [ ] 我已经阅读过 [README](https://github.com/claude-code-best/claude-code) 和相关文档。
-
-**未完成以上检查的 Issue 将被直接关闭。**
-
---
-
-## 运行环境
-
-| 项目| 值|
-|---|---|
-| 操作系统| 例如 macOS 15.4、Ubuntu 24.04|
-| Bun 版本| 例如 `bun --version` 的输出|
-| Claude Code 版本| 例如 `2.4.3` 或 commit hash|
-| 安装方式| `bun run build` / npm / 其他|
-| 模型| 例如 claude-sonnet-4-6、claude-opus-4-7|
-
-## 复现步骤
-
-1.
-2.
-3.
-
-## 期望行为
-
-<!-- 应该发生什么？ -->
-
-## 实际行为
-
-<!-- 实际发生了什么？如有必要可附截图。 -->
-
-## 相关日志
-
-<!-- 粘贴终端输出或错误信息，请使用 triple backticks 代码块。 -->
-
-```text
-```
-
-## 补充信息
-
-<!-- 其他上下文 — 配置、环境变量、尝试过的 workaround 等。 -->
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -1,8 +0,0 @@
-blank_issues_enabled: false
-contact_links:
-  - name: 💬 讨论区
-    url: https://github.com/claude-code-best/claude-code/discussions
-    about: 使用问题、功能建议和一般讨论 — 请使用 Discussions 而非 Issues。
-  - name: 📖 项目文档
-    url: https://github.com/claude-code-best/claude-code
-    about: 提交 issue 前，请先阅读 README 和相关文档，你的问题可能已经有答案了。
--- a/.github/ISSUE_TEMPLATE/feature_request.md
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -1,31 +0,0 @@
---
-name: 功能建议
-description: 提出新功能或改进建议
-title: "feat: "
-labels: ["enhancement"]
-assignees: []
---
-
-## 发帖前必读
-
- [ ] 我已经搜索过 [现有 Issues](https://github.com/claude-code-best/claude-code/issues)，没有找到重复。
- [ ] 这是功能建议，不是 Bug 报告或使用问题。
- [ ] 使用问题请前往 [Discussions](https://github.com/claude-code-best/claude-code/discussions)。
-
---
-
-## 要解决的问题
-
-<!-- 这个功能解决什么问题？为什么需要它？ -->
-
-## 建议方案
-
-<!-- 描述你建议的实现方式，尽量简洁具体。 -->
-
-## 考虑过的替代方案
-
-<!-- 还有没有想到的其他实现思路？ -->
-
-## 补充信息
-
-<!-- 截图、草图、参考资料，或其他有助于说明需求的内容。 -->
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -2,59 +2,29 @@ name: CI

 on:
  push:
-    branches: [main, "feature/*", "feat/*"]
+    branches: [main, feature/*]
  pull_request:
-    branches: [main, "feat/*"]
-  workflow_dispatch:
-
-permissions:
-  contents: read
+    branches: [main]

 jobs:
  ci:
-    runs-on: ubuntu-latest
+    runs-on: macos-latest

    steps:
-      - 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: actions/checkout@v4

-      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2, 2026-04-25
+      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - name: Install dependencies
-        env:
-          CLAUDE_CODE_SKIP_CHROME_MCP_SETUP: "1"
        run: bun install --frozen-lockfile

-      - name: Lint and format check
-        run: bunx biome ci .
-
      - name: Type check
-        run: bun run typecheck
+        run: bunx tsc --noEmit

-      - name: Test with Coverage
-        run: |
-          # Tolerate pre-existing flaky tests (Bun mock pollution / order-dependent state).
-          # We still require lcov.info to be generated and contain real coverage data.
-          set -o pipefail
-          bun test --coverage --coverage-reporter lcov --coverage-dir coverage 2>&1 | grep -vE '^\s*(\(pass\)|\(skip\))' | sed '/^.*\/__tests__\/.*:$/d' | cat -s
-          test -s coverage/lcov.info
-          grep -q '^SF:' coverage/lcov.info
-
-      - 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: Test
+        run: bun test

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

    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2, 2026-04-25
+      - uses: actions/checkout@v4

      - name: Login to GHCR
-        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3, 2026-04-25
+        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3, 2026-04-25
+        uses: docker/setup-buildx-action@v3

      - name: Extract version
        id: version
@@ -47,7 +47,7 @@ jobs:
          echo "tags=$TAGS" >> "$GITHUB_OUTPUT"

      - name: Build Docker image
-        uses: docker/build-push-action@ca052bb54ab0790a636c9b5f226502c73d547a25 # v5, 2026-04-25
+        uses: docker/build-push-action@v5
        with:
          context: .
          file: packages/remote-control-server/Dockerfile
--- a/.github/workflows/update-contributors.yml
+++ b/.github/workflows/update-contributors.yml
@@ -1,8 +1,11 @@
 name: Update Contributors

 on:
+  push:
+    branches:
+      - main
  schedule:
-    - cron: '0 0 * * 1'  # 每周一更新一次
+    - cron: '0 0 * * *'  # 每天更新一次

 permissions:
  contents: write
@@ -11,17 +14,17 @@ jobs:
  update:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2, 2026-04-25
+      - uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

-      - uses: jaywcjlove/github-action-contributors@86707f6d4c2469ce6b46bc3367253ebd41ee242c # main, 2026-04-25
+      - uses: jaywcjlove/github-action-contributors@main
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          output: "contributors.svg"
          repository: ${{ github.repository }}

-      - uses: stefanzweifel/git-auto-commit-action@b863ae1933cb653a53c021fe36dbb774e1fb9403 # v5, 2026-04-25
+      - uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "docs: update contributors"
          file_pattern: "contributors.svg"
--- a/.gitignore
+++ b/.gitignore
@@ -5,8 +5,7 @@ coverage
 .env
 *.log
 .idea
-.vscode/*
-!.vscode/extensions.json
+.vscode
 *.suo
 *.lock
 src/utils/vendor/
@@ -14,17 +13,13 @@ src/utils/vendor/
 # AI tool runtime directories
 .agents/
 .claude/
+.codex/
 .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__/
@@ -35,24 +30,3 @@ __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
--- a/.husky/pre-commit
+++ b/.husky/pre-commit
@@ -1 +0,0 @@
-npx lint-staged
--- a/.impeccable.md
+++ b/.impeccable.md
@@ -1,78 +0,0 @@
-# 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`
--- a/.npmrc
+++ b/.npmrc
@@ -1 +0,0 @@
-registry=https://registry.npmjs.org/
--- a/.tool-versions
+++ b/.tool-versions
@@ -1 +0,0 @@
-bun 1.3.13
--- a/.vscode/extensions.json
+++ b/.vscode/extensions.json
@@ -1,8 +0,0 @@
-{
-  "recommendations": [
-    "biomejs.biome",
-    "ms-typescript.typescript",
-    "oven.bun-vscode",
-    "editorconfig.editorconfig"
-  ]
-}
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,357 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) and other AI coding agents when working with code in this repository.
-
-## Project Overview
-
-This is a **reverse-engineered / decompiled** version of Anthropic's official Claude Code CLI tool. The goal is to restore core functionality while trimming secondary capabilities. Many modules are stubbed or feature-flagged off. TypeScript strict mode is enforced — **`bunx tsc --noEmit` must pass with zero errors**.
-
-## Git Commit Message Convention
-
-使用 **Conventional Commits** 规范：
-
-```
-<type>: <描述>
-```
-
-常见 type：`feat`、`fix`、`docs`、`chore`、`refactor`
-
-示例：
- `feat: 添加模型 1M 上下文切换`
- `fix: 修复初次登陆的校验问题`
- `chore: remove prefetchOfficialMcpUrls call on startup`
-
-## Commands
-
-```bash
-# Install dependencies
-bun install
-
-# Dev mode (runs cli.tsx with MACRO defines injected via -d flags)
-bun run dev
-
-# Dev mode with debugger (set BUN_INSPECT=9229 to pick port)
-bun run dev:inspect
-
-# Pipe mode
-echo "say hello" | bun run src/entrypoints/cli.tsx -p
-
-# Build (code splitting, outputs dist/cli.js + chunk files)
-bun run build
-
-# Build with Vite (alternative build pipeline)
-bun run build:vite
-
-# Test
-bun test                                    # run all tests
-bun test src/utils/__tests__/hash.test.ts   # run single file
-bun test --coverage                         # with coverage report
-
-# Lint & Format (Biome)
-bun run lint              # check only
-bun run lint:fix          # auto-fix
-bun run format            # format all src/
-
-# Health check
-bun run health
-
-# Check unused exports
-bun run check:unused
-
-# Full check (typecheck + lint + test) — run after completing any task
-bun run test:all
-bun run typecheck
-
-# Remote Control Server
-bun run rcs
-
-# Docs dev server (Mintlify)
-bun run docs:dev
-```
-
-详细的测试规范、覆盖状态和改进计划见 `docs/testing-spec.md`。
-
-## Architecture
-
-### Runtime & Build
-
- **Runtime**: Bun (not Node.js). All imports, builds, and execution use Bun APIs.
- **Build**: `build.ts` 执行 `Bun.build()` with `splitting: true`，入口 `src/entrypoints/cli.tsx`，输出 `dist/cli.js` + chunk files。Build 默认启用 19 个 feature（见下方 Feature Flag 段）。构建后自动替换 `import.meta.require` 为 Node.js 兼容版本（产物 bun/node 都可运行）。
- **Dev mode**: `scripts/dev.ts` 通过 Bun `-d` flag 注入 `MACRO.*` defines，运行 `src/entrypoints/cli.tsx`。默认启用全部 feature。
- **Module system**: ESM (`"type": "module"`), TSX with `react-jsx` transform.
- **Monorepo**: Bun workspaces — 15 个 workspace packages + 若干辅助目录 in `packages/` resolved via `workspace:*`。
- **Lint/Format**: Biome (`biome.json`)。`bun run lint` / `bun run lint:fix` / `bun run format`。
- **Defines**: 集中管理在 `scripts/defines.ts`。当前版本 `2.1.888`。
- **CI**: GitHub Actions — `ci.yml`（构建+测试）、`release-rcs.yml`（RCS 发布）、`update-contributors.yml`（自动更新贡献者）。
-
-### Entry & Bootstrap
-
-1. **`src/entrypoints/cli.tsx`** — True entrypoint。`main()` 函数按优先级处理多条快速路径：
-   - `--version` / `-v` — 零模块加载
-   - `--dump-system-prompt` — feature-gated (DUMP_SYSTEM_PROMPT)
-   - `--claude-in-chrome-mcp` / `--chrome-native-host`
-   - `--computer-use-mcp` — 独立 MCP server 模式
-   - `--daemon-worker=<kind>` — feature-gated (DAEMON)
-   - `remote-control` / `rc` / `remote` / `sync` / `bridge` — feature-gated (BRIDGE_MODE)
-   - `daemon` [subcommand] — feature-gated (DAEMON)
-   - `ps` / `logs` / `attach` / `kill` / `--bg` — feature-gated (BG_SESSIONS)
-   - `new` / `list` / `reply` — Template job commands
-   - `environment-runner` / `self-hosted-runner` — BYOC runner
-   - `--tmux` + `--worktree` 组合
-   - 默认路径：加载 `main.tsx` 启动完整 CLI
-2. **`src/main.tsx`** (~6981 行) — Commander.js CLI definition。注册大量 subcommands：`mcp` (serve/add/remove/list...)、`server`、`ssh`、`open`、`auth`、`plugin`、`agents`、`auto-mode`、`doctor`、`update` 等。主 `.action()` 处理器负责权限、MCP、会话恢复、REPL/Headless 模式分发。
-3. **`src/entrypoints/init.ts`** — One-time initialization (telemetry, config, trust dialog)。
-
-### Core Loop
-
- **`src/query.ts`** — The main API query function. Sends messages to Claude API, handles streaming responses, processes tool calls, and manages the conversation turn loop.
- **`src/QueryEngine.ts`** — Higher-level orchestrator wrapping `query()`. Manages conversation state, compaction, file history snapshots, attribution, and turn-level bookkeeping. Used by the REPL screen.
- **`src/screens/REPL.tsx`** — The interactive REPL screen (React/Ink component). Handles user input, message display, tool permission prompts, and keyboard shortcuts.
-
-### API Layer
-
- **`src/services/api/claude.ts`** — Core API client. Builds request params (system prompt, messages, tools, betas), calls the Anthropic SDK streaming endpoint, and processes `BetaRawMessageStreamEvent` events.
- **7 providers**: `firstParty` (Anthropic direct), `bedrock` (AWS), `vertex` (Google Cloud), `foundry`, `openai`, `gemini`, `grok` (xAI)。
- Provider selection in `src/utils/model/providers.ts`。优先级：modelType 参数 > 环境变量 > 默认 firstParty。
-
-### Tool System
-
- **`src/Tool.ts`** — Tool interface definition (`Tool` type) and utilities (`findToolByName`, `toolMatchesName`).
- **`src/tools.ts`** — Tool registry. Assembles the tool list; tools are imported from `@claude-code-best/builtin-tools` package. Some tools are conditionally loaded via `feature()` flags or `process.env.USER_TYPE`.
- **`packages/builtin-tools/src/tools/`** — 59 个子目录（含 shared/testing 等工具目录），通过 `@claude-code-best/builtin-tools` 包导出。主要分类：
-  - **文件操作**: FileEditTool, FileReadTool, FileWriteTool, GlobTool, GrepTool
-  - **Shell/执行**: BashTool, PowerShellTool, REPLTool
-  - **Agent 系统**: AgentTool, TaskCreateTool, TaskUpdateTool, TaskListTool, TaskGetTool
-  - **规划**: EnterPlanModeTool, ExitPlanModeV2Tool, VerifyPlanExecutionTool
-  - **Web/MCP**: WebFetchTool, WebSearchTool, MCPTool, McpAuthTool
-  - **调度**: CronCreateTool, CronDeleteTool, CronListTool
-  - **其他**: LSPTool, ConfigTool, SkillTool, EnterWorktreeTool, ExitWorktreeTool 等
- **`src/tools/shared/`** / **`packages/builtin-tools/src/tools/shared/`** — Tool 共享工具函数。
-
-### UI Layer (Ink)
-
- **`src/ink.ts`** — Ink render wrapper with ThemeProvider injection.
- **`packages/@ant/ink/`** — Custom Ink framework（forked/internal），包含 components、core、hooks、keybindings、theme、utils。注意：不是 `src/ink/`。
- **`src/components/`** — 149 个组件目录/文件，渲染于终端 Ink 环境中。关键组件：
-  - `App.tsx` — Root provider (AppState, Stats, FpsMetrics)
-  - `Messages.tsx` / `MessageRow.tsx` — Conversation message rendering
-  - `PromptInput/` — User input handling
-  - `permissions/` — Tool permission approval UI
-  - `design-system/` — 复用 UI 组件（Dialog, FuzzyPicker, ProgressBar, ThemeProvider 等）
- Components use React Compiler runtime (`react/compiler-runtime`) — decompiled output has `_c()` memoization calls throughout.
-
-### State Management
-
- **`src/state/AppState.tsx`** — Central app state type and context provider. Contains messages, tools, permissions, MCP connections, etc.
- **`src/state/AppStateStore.ts`** — Default state and store factory.
- **`src/state/store.ts`** — Zustand-style store for AppState (`createStore`).
- **`src/state/selectors.ts`** — State selectors.
- **`src/bootstrap/state.ts`** — Module-level singletons for session-global state (session ID, CWD, project root, token counts, model overrides, client type, permission mode).
-
-### Workspace Packages
-
-| Package | 说明 |
-|---------|------|
-| `packages/@ant/ink/` | Forked Ink 框架（components、hooks、keybindings、theme） |
-| `packages/@ant/computer-use-mcp/` | Computer Use MCP server（截图/键鼠/剪贴板/应用管理） |
-| `packages/@ant/computer-use-input/` | 键鼠模拟（dispatcher + darwin/win32/linux backend） |
-| `packages/@ant/computer-use-swift/` | 截图 + 应用管理（dispatcher + per-platform backend） |
-| `packages/@ant/claude-for-chrome-mcp/` | Chrome 浏览器控制（通过 `--chrome` 启用） |
-| `packages/@ant/model-provider/` | Model provider 抽象层 |
-| `packages/builtin-tools/` | 内置工具集（60 个 tool 实现，通过 `@claude-code-best/builtin-tools` 导出） |
-| `packages/agent-tools/` | Agent 工具集 |
-| `packages/acp-link/` | ACP 代理服务器（WebSocket → ACP agent 桥接） |
-| `packages/cc-knowledge/` | Claude Code 知识库（非 workspace 包） |
-| `packages/langfuse-dashboard/` | Langfuse 可观测性面板（非 workspace 包） |
-| `packages/mcp-client/` | MCP 客户端库 |
-| `packages/mcp-server/` | MCP 服务端库（非 workspace 包） |
-| `packages/remote-control-server/` | 自托管 Remote Control Server（Docker 部署，含 Web UI）— Web UI 已重构为 React + Vite + Radix UI，支持 ACP agent 接入 |
-| `packages/swarm/` | Swarm 解耦模块（非 workspace 包） |
-| `packages/shell/` | Shell 抽象（非 workspace 包） |
-| `packages/audio-capture-napi/` | 原生音频捕获（已恢复） |
-| `packages/color-diff-napi/` | 颜色差异计算（完整实现，11 tests） |
-| `packages/image-processor-napi/` | 图像处理（已恢复） |
-| `packages/modifiers-napi/` | 键盘修饰键检测（macOS FFI 实现） |
-| `packages/url-handler-napi/` | URL scheme 处理（环境变量 + CLI 参数读取） |
-
-### Bridge / Remote Control
-
- **`src/bridge/`** — Remote Control / Bridge 模式。feature-gated by `BRIDGE_MODE`。包含 bridge API、会话管理、JWT 认证、消息传输、权限回调等。Entry: `bridgeMain.ts`。
- **`packages/remote-control-server/`** — 自托管 RCS，支持 Docker 部署，含 Web UI 控制面板（React 19 + Vite + Radix UI）。支持 ACP agent 通过 acp-link 接入（ACP WebSocket handler、relay handler、SSE event stream）。通过 `bun run rcs` 启动。
- CLI 快速路径: `claude remote-control` / `claude rc` / `claude bridge`。
- 详见 `docs/features/remote-control-self-hosting.md`。
-
-### ACP Protocol (Agent Client Protocol)
-
- **`src/services/acp/`** — ACP agent 实现，包含 `agent.ts`（AcpAgent 类）、`bridge.ts`（Claude Code ↔ ACP 桥接）、`permissions.ts`（权限处理）、`entry.ts`（入口）。
- **`packages/acp-link/`** — ACP 代理服务器，将 WebSocket 客户端桥接到 ACP agent。提供 `acp-link` CLI 命令，支持自定义端口/HTTPS/认证/会话管理、RCS 集成（REST 注册 + WS identify 两步流程）、权限模式透传（fallback: 客户端传值 > config > `ACP_PERMISSION_MODE` 环境变量）。
- ACP 权限管道改进：`createAcpCanUseTool` 统一权限流水线，`applySessionMode` 模式同步，`bypassPermissions` 可用性检测（非 root/sandbox 环境）。
- ACP Plan 可视化已支持 `session/update plan` 类型的消息展示（PlanView 组件，含进度条/状态图标/优先级标签）。
-
-### Daemon Mode
-
- **`src/daemon/`** — Daemon 模式（长驻 supervisor）。feature-gated by `DAEMON`。包含 `main.ts`（entry）和 `workerRegistry.ts`（worker 管理）。
-
-### Context & System Prompt
-
- **`src/context.ts`** — Builds system/user context for the API call (git status, date, CLAUDE.md contents, memory files).
- **`src/utils/claudemd.ts`** — Discovers and loads CLAUDE.md files from project hierarchy.
-
-### Feature Flag System
-
-Feature flags control which functionality is enabled at runtime. 代码中统一通过 `import { feature } from 'bun:bundle'` 导入，调用 `feature('FLAG_NAME')` 返回 `boolean`。
-
-**启用方式**: 环境变量 `FEATURE_<FLAG_NAME>=1`。例如 `FEATURE_BUDDY=1 bun run dev`。
-
-**Build 默认 features**（19 个，见 `build.ts`）:
- 基础: `BUDDY`, `TRANSCRIPT_CLASSIFIER`, `BRIDGE_MODE`, `AGENT_TRIGGERS_REMOTE`, `CHICAGO_MCP`, `VOICE_MODE`
- 统计/缓存: `SHOT_STATS`, `PROMPT_CACHE_BREAK_DETECTION`, `TOKEN_BUDGET`
- P0 本地: `AGENT_TRIGGERS`, `ULTRATHINK`, `BUILTIN_EXPLORE_PLAN_AGENTS`, `LODESTONE`
- P1 API 依赖: `EXTRACT_MEMORIES`, `VERIFICATION_AGENT`, `KAIROS_BRIEF`, `AWAY_SUMMARY`, `ULTRAPLAN`
- P2: `DAEMON`
-
-**Dev mode 默认**: 全部启用（见 `scripts/dev.ts`）。
-
-**类型声明**: `src/types/internal-modules.d.ts` 中声明了 `bun:bundle` 模块的 `feature` 函数签名。
-
-**新增功能的正确做法**: 保留 `import { feature } from 'bun:bundle'` + `feature('FLAG_NAME')` 的标准模式，在运行时通过环境变量或配置控制，不要绕过 feature flag 直接 import。
-
-### Multi-API 兼容层
-
-所有兼容层均采用流适配器模式：将第三方 API 格式转为 Anthropic 内部格式，下游代码完全不改。通过 `/login` 命令配置。
-
-#### OpenAI 兼容层
-
-通过 `CLAUDE_CODE_USE_OPENAI=1` 启用，支持 Ollama/DeepSeek/vLLM 等任意 OpenAI Chat Completions 协议端点。含 DeepSeek thinking mode 支持。
-
- **`src/services/api/openai/`** — client、消息/工具转换、流适配、模型映射
- 关键环境变量：`CLAUDE_CODE_USE_OPENAI`、`OPENAI_API_KEY`、`OPENAI_BASE_URL`、`OPENAI_MODEL`
-
-#### Gemini 兼容层
-
-通过 `CLAUDE_CODE_USE_GEMINI=1` 启用。独立环境变量体系。
-
- **`src/services/api/gemini/`** — client、模型映射、类型定义
- 关键环境变量：`GEMINI_API_KEY`（必填）、`GEMINI_MODEL`（直接指定）、`GEMINI_DEFAULT_SONNET_MODEL`/`GEMINI_DEFAULT_OPUS_MODEL`（按能力映射）
- 模型映射优先级：`GEMINI_MODEL` > `GEMINI_DEFAULT_*_MODEL` > `ANTHROPIC_DEFAULT_*_MODEL`(已废弃) > 原样返回
-
-#### Grok 兼容层
-
-通过 `CLAUDE_CODE_USE_GROK=1` 启用。自定义模型映射支持 xAI Grok API。
-
- **`src/services/api/grok/`** — client、模型映射
-
-详见各兼容层的 docs 文档。
-
-### 穷鬼模式（Budget Mode）
-
- 通过 `/poor` 命令切换，持久化到 `settings.json`。
- 启用后跳过 `extract_memories`、`prompt_suggestion` 和 `verification_agent`，显著减少 token 消耗。
- 实现在 `src/commands/poor/poorMode.ts`。
-
-### Stubbed/Deleted Modules
-
-| Module | Status |
-|--------|--------|
-| Computer Use (`@ant/*`) | Restored — macOS + Windows + Linux（后端完整度不一） |
-| `*-napi` packages | 全部已恢复/实现：`audio-capture-napi`、`image-processor-napi` 已恢复；`color-diff-napi` 完整；`modifiers-napi`（macOS FFI）；`url-handler-napi`（环境变量+CLI） |
-| Voice Mode | Restored — Push-to-Talk 语音输入（需 Anthropic OAuth） |
-| OpenAI/Gemini/Grok 兼容层 | Restored |
-| Remote Control Server | Restored — 自托管 RCS + Web UI |
-| Analytics / GrowthBook / Sentry | Empty implementations |
-| Magic Docs / LSP Server | Restored — Magic Docs 自动更新 + LSP 服务器管理器 |
-| Plugins / Marketplace | Restored — 插件安装/卸载/启用/禁用 + Marketplace 浏览 |
-| MCP OAuth | Simplified |
-
-### Key Type Files
-
- **`src/types/global.d.ts`** — Declares `MACRO`, `BUILD_TARGET`, `BUILD_ENV` and internal Anthropic-only identifiers.
- **`src/types/internal-modules.d.ts`** — Type declarations for `bun:bundle`, `bun:ffi`, `@anthropic-ai/mcpb`.
- **`src/types/message.ts`** — Message type hierarchy (UserMessage, AssistantMessage, SystemMessage, etc.).
- **`src/types/permissions.ts`** — Permission mode and result types.
-
-## Testing
-
- **框架**: `bun:test`（内置断言 + mock）
- **单元测试**: 就近放置于 `src/**/__tests__/`，文件名 `<module>.test.ts`
- **集成测试**: `tests/integration/` — 4 个文件（cli-arguments, context-build, message-pipeline, tool-chain）
- **共享 mock/fixture**: `tests/mocks/`（api-responses, file-system, fixtures/）
- **命名**: `describe("functionName")` + `test("behavior description")`，英文
- **包测试**: `packages/` 下各包也有独立测试（如 `color-diff-napi` 11 tests）
-
-### Mock 使用规范
-
-**只 mock 有副作用的依赖链，不 mock 纯函数/纯数据模块。**
-
-被迫 mock 的根源：`log.ts` / `debug.ts` → `bootstrap/state.ts`（模块级 `realpathSync` / `randomUUID` 副作用）。必须 mock 的模块：`log.ts`、`debug.ts`、`bun:bundle`、`settings/settings.js`、`config.ts`、`auth.ts`、第三方网络库。
-
-**`log.ts` 和 `debug.ts` 使用共享 mock**（`tests/mocks/log.ts` / `tests/mocks/debug.ts`），不要在测试文件中内联 mock 定义。使用方式：
-
-```ts
-import { logMock } from "../../../tests/mocks/log";
-mock.module("src/utils/log.ts", logMock);
-
-import { debugMock } from "../../../../tests/mocks/debug";
-mock.module("src/utils/debug.ts", debugMock);
-```
-
-源文件导出变更时只需更新 `tests/mocks/` 下的对应文件，不需要逐个修改测试。
-
-不要 mock：纯函数模块（`errors.ts`、`stringUtils.js`）、mock 值与真实实现相同的模块、mock 路径与实际 import 不匹配的模块。
-
-路径规则：统一用 `.ts` 扩展名 + `src/*` 别名路径，禁止双重 mock 同一模块。
-
-### 类型检查
-
-项目使用 TypeScript strict 模式，**tsc 必须零错误**。每次修改后运行：
-
-```bash
-bun run typecheck
-```
-
-**类型规范**：
- 生产代码禁止 `as any`；测试文件中 mock 数据可用 `as any`
- 类型不匹配优先用 `as unknown as SpecificType` 双重断言，或补充 interface
- 未知结构对象用 `Record<string, unknown>` 替代 `any`
- 联合类型用类型守卫（type guard）收窄，不要强转
- `msg.request` 属性访问：`const req = msg.request as Record<string, unknown>`
- Ink `color` prop：用 `as keyof Theme` 而非 `as any`
-
-## Working with This Codebase
-
- **tsc must pass** — `bun run typecheck` 必须零错误，任何修改都不能引入新的类型错误。
- **Feature flags** — 默认全部关闭（`feature()` 返回 `false`）。Dev/build 各有自己的默认启用列表。不要在 `cli.tsx` 中重定义 `feature` 函数。
- **React Compiler output** — Components have decompiled memoization boilerplate (`const $ = _c(N)`). This is normal.
- **`bun:bundle` import** — `import { feature } from 'bun:bundle'` 是 Bun 内置模块，由运行时/构建器解析。不要用自定义函数替代它。**`feature()` 只能直接用在 `if` 语句或三元表达式的条件位置**（Bun 编译器限制），不能赋值给变量、不能放在箭头函数体里、不能作为 `&&` 链的一部分。正确：`if (feature('X')) {}` 或 `feature('X') ? a : b`。
- **`src/` path alias** — tsconfig maps `src/*` to `./src/*`. Imports like `import { ... } from 'src/utils/...'` are valid.
- **MACRO defines** — 集中管理在 `scripts/defines.ts`。Dev mode 通过 `bun -d` 注入，build 通过 `Bun.build({ define })` 注入。修改版本号等常量只改这个文件。
- **构建产物兼容 Node.js** — `build.ts` 会自动后处理 `import.meta.require`，产物可直接用 `node dist/cli.js` 运行。
- **Biome 配置** — 大量 lint 规则被关闭（decompiled 代码不适合严格 lint）。`.tsx` 文件用 120 行宽 + 强制分号；其他文件 80 行宽 + 按需分号。
- **Ink 框架在 `packages/@ant/ink/`** — 不是 `src/ink/`（该目录不存在）。Ink 相关的组件、hooks、keybindings 都在 packages 中。
- **Provider 优先级** — `modelType` 参数 > 环境变量 > 默认 `firstParty`。新增 provider 需在 `src/utils/model/providers.ts` 注册。
-
-## Design Context
-
-Impeccable 设计上下文保存在 `.impeccable.md` 中。设计 Web UI（RCS 控制面板、文档站、着陆页）时必须参考该文件。
-
-### 核心设计原则
-
-1. **Considered over clever** — 每个设计选择都应感觉有意为之，而非追逐潮流
-2. **Warmth through subtlety** — 通过橙色色调的中性色、留白布局、有温度的文案来传达温暖
-3. **Density with clarity** — 技术用户需要信息密度，但不能混乱
-4. **Community voice** — 设计应感觉是由使用者创造的，而非遥远的设计团队
-5. **Anthropic's shadow** — 遵循 Anthropic 的设计直觉：干净的布局、充足的间距、温暖的色温
-
-### 品牌色
-
- 主色：Claude Orange `#D77757`（terra cotta）
- 辅色：Claude Blue `#5769F7`
- 暗色模式使用温暖的深色表面（非冷蓝黑色）
-
-### 目标用户
-
-技术团队/企业，在专业工作流中使用 AI 辅助编程。友好的开源社区氛围，非企业 SaaS 风格。
-
-### 视觉参考
-
-Anthropic 公司的设计风格 — 干净、考究、温暖的底色。大量留白，以排版为核心。避免 AI 产品常见的设计套路（渐变文字、玻璃态、霓虹色）。
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,10 +1,10 @@
 # CLAUDE.md

-This file provides guidance to Claude Code (claude.ai/code) and other AI coding agents when working with code in this repository.
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

 ## Project Overview

-This is a **reverse-engineered / decompiled** version of Anthropic's official Claude Code CLI tool. The goal is to restore core functionality while trimming secondary capabilities. Many modules are stubbed or feature-flagged off. TypeScript strict mode is enforced — **`bun run precheck` 必须零错误通过**（包含 typecheck + lint fix + test）。
+This is a **reverse-engineered / decompiled** version of Anthropic's official Claude Code CLI tool. The goal is to restore core functionality while trimming secondary capabilities. Many modules are stubbed or feature-flagged off. TypeScript strict mode is enforced — **`bunx tsc --noEmit` must pass with zero errors**.

 ## Git Commit Message Convention

@@ -39,20 +39,15 @@ 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                  # run all tests (2453 tests / 137 files / 0 fail)
 bun test src/utils/__tests__/hash.test.ts   # run single file
-bun test --coverage                         # with coverage report
+bun test --coverage       # with coverage report

-# Lint & Format (Biome) — 日常开发用 precheck 代替单独调用
-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
+# 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
@@ -60,9 +55,6 @@ 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

@@ -77,22 +69,17 @@ bun run docs:dev
 ### Runtime & Build

 - **Runtime**: Bun (not Node.js). All imports, builds, and execution use Bun APIs.
- **Build**: `build.ts` 执行 `Bun.build()` with `splitting: true`，入口 `src/entrypoints/cli.tsx`，输出 `dist/cli.js` + chunk files。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。
+- **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 — 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`（自动更新贡献者）。
+- **Monorepo**: Bun workspaces — 14 个 internal packages in `packages/` resolved via `workspace:*`。
+- **Lint/Format**: Biome (`biome.json`)。`bun run lint` / `bun run lint:fix` / `bun run format`。
+- **Defines**: 集中管理在 `scripts/defines.ts`。当前版本 `2.1.888`。
+- **CI**: GitHub Actions — `ci.yml`（构建+测试）、`release-rcs.yml`（RCS 发布）、`update-contributors.yml`（自动更新贡献者）。

 ### Entry & Bootstrap

-1. **`src/entrypoints/cli.tsx`** — True entrypoint。`main()` 函数按优先级处理多条快速路径：
+1. **`src/entrypoints/cli.tsx`** (323 行) — True entrypoint。`main()` 函数按优先级处理多条快速路径：
   - `--version` / `-v` — 零模块加载
   - `--dump-system-prompt` — feature-gated (DUMP_SYSTEM_PROMPT)
   - `--claude-in-chrome-mcp` / `--chrome-native-host`
@@ -105,7 +92,7 @@ bun run docs:dev
   - `environment-runner` / `self-hosted-runner` — BYOC runner
   - `--tmux` + `--worktree` 组合
   - 默认路径：加载 `main.tsx` 启动完整 CLI
-2. **`src/main.tsx`** (~5674 行) — Commander.js CLI definition。注册大量 subcommands：`mcp` (serve/add/remove/list...)、`server`、`ssh`、`open`、`auth`、`plugin`、`agents`、`auto-mode`、`doctor`、`update` 等。主 `.action()` 处理器负责权限、MCP、会话恢复、REPL/Headless 模式分发。
+2. **`src/main.tsx`** (~6970 行) — Commander.js CLI definition。注册大量 subcommands：`mcp` (serve/add/remove/list...)、`server`、`ssh`、`open`、`auth`、`plugin`、`agents`、`auto-mode`、`doctor`、`update` 等。主 `.action()` 处理器负责权限、MCP、会话恢复、REPL/Headless 模式分发。
 3. **`src/entrypoints/init.ts`** — One-time initialization (telemetry, config, trust dialog)。

 ### Core Loop
@@ -123,19 +110,16 @@ bun run docs:dev
 ### Tool System

 - **`src/Tool.ts`** — Tool interface definition (`Tool` type) and utilities (`findToolByName`, `toolMatchesName`).
- **`src/tools.ts`** — Tool registry. Assembles the tool list; tools are imported from `@claude-code-best/builtin-tools` package. Some tools are conditionally loaded via `feature()` flags or `process.env.USER_TYPE`.
- **`src/constants/tools.ts`** — `CORE_TOOLS` 白名单常量（38 个核心工具名），用于 `isDeferredTool` 白名单制判定。
- **`packages/builtin-tools/src/tools/`** — 60 个工具目录（含 shared/testing 等工具目录），通过 `@claude-code-best/builtin-tools` 包导出。主要分类：
+- **`src/tools.ts`** (387 行) — Tool registry. Assembles the tool list; some tools are conditionally loaded via `feature()` flags or `process.env.USER_TYPE`.
+- **`src/tools/<ToolName>/`** — 55 个 tool 目录。主要分类：
  - **文件操作**: 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 的去重集合互不影响。
+- **`src/tools/shared/`** — Tool 共享工具函数。

 ### UI Layer (Ink)

@@ -166,35 +150,22 @@ bun run docs:dev
 | `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/remote-control-server/` | 自托管 Remote Control Server（Docker 部署，含 Web UI） |
+| `packages/swarm/` | Swarm 解耦模块 |
+| `packages/shell/` | Shell 抽象 |
 | `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`（示例/测试）。
+| `packages/modifiers-napi/` | 键盘修饰键检测（stub） |
+| `packages/url-handler-napi/` | URL scheme 处理（stub） |

 ### 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` 启动。
+- **`src/bridge/`** (~37 files) — Remote Control / Bridge 模式。feature-gated by `BRIDGE_MODE`。包含 bridge API、会话管理、JWT 认证、消息传输、权限回调等。Entry: `bridgeMain.ts`。
+- **`packages/remote-control-server/`** — 自托管 RCS，支持 Docker 部署，含 Web UI 控制面板。通过 `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 管理）。
@@ -210,18 +181,12 @@ Feature flags control which functionality is enabled at runtime. 代码中统一

 **启用方式**: 环境变量 `FEATURE_<FLAG_NAME>=1`。例如 `FEATURE_BUDDY=1 bun run dev`。

-**Build 默认 features**（65+ 个，见 `build.ts` 中 `DEFAULT_BUILD_FEATURES`）:
+**Build 默认 features**（19 个，见 `build.ts`）:
 - 基础: `BUDDY`, `TRANSCRIPT_CLASSIFIER`, `BRIDGE_MODE`, `AGENT_TRIGGERS_REMOTE`, `CHICAGO_MCP`, `VOICE_MODE`
 - 统计/缓存: `SHOT_STATS`, `PROMPT_CACHE_BREAK_DETECTION`, `TOKEN_BUDGET`
 - P0 本地: `AGENT_TRIGGERS`, `ULTRATHINK`, `BUILTIN_EXPLORE_PLAN_AGENTS`, `LODESTONE`
 - P1 API 依赖: `EXTRACT_MEMORIES`, `VERIFICATION_AGENT`, `KAIROS_BRIEF`, `AWAY_SUMMARY`, `ULTRAPLAN`
- P2: `DAEMON`, `ACP`
- 工作流: `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`
+- P2: `DAEMON`

 **Dev mode 默认**: 全部启用（见 `scripts/dev.ts`）。

@@ -231,7 +196,7 @@ Feature flags control which functionality is enabled at runtime. 代码中统一

 ### Multi-API 兼容层

-所有兼容层均采用流适配器模式：将第三方 API 格式转为 Anthropic 内部格式，下游代码完全不改。通过 `/login` 命令配置。
+所有兼容层均采用流适配器模式：将第三方 API 格式转为 Anthropic 内部格式，下游代码完全不改。

 #### OpenAI 兼容层

@@ -256,25 +221,18 @@ Feature flags control which functionality is enabled at runtime. 代码中统一

 详见各兼容层的 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） |
+| `*-napi` packages | `audio-capture-napi`、`image-processor-napi` 已恢复；`color-diff-napi` 完整；`modifiers-napi`、`url-handler-napi` 仍为 stub |
 | Voice Mode | Restored — Push-to-Talk 语音输入（需 Anthropic OAuth） |
 | OpenAI/Gemini/Grok 兼容层 | Restored |
 | Remote Control Server | Restored — 自托管 RCS + Web UI |
-| `packages/shell/`, `packages/swarm/`, `packages/mcp-server/`, `packages/cc-knowledge/` | Removed — 功能合并或废弃 |
 | Analytics / GrowthBook / Sentry | Empty implementations |
-| Magic Docs / LSP Server | Restored — Magic Docs 自动更新 + LSP 服务器管理器 |
-| Plugins / Marketplace | Restored — 插件安装/卸载/启用/禁用 + Marketplace 浏览 |
+| Magic Docs / LSP Server | Removed |
+| Plugins / Marketplace | Removed |
 | MCP OAuth | Simplified |

 ### Key Type Files
@@ -287,82 +245,20 @@ Feature flags control which functionality is enabled at runtime. 代码中统一
 ## Testing

 - **框架**: `bun:test`（内置断言 + mock）
+- **当前状态**: 2472 tests / 138 files / 0 fail
 - **单元测试**: 就近放置于 `src/**/__tests__/`，文件名 `<module>.test.ts`
- **集成测试**: `tests/integration/` — 6 个文件（cli-arguments, context-build, message-pipeline, tool-chain, autonomy-lifecycle-user-flow, dependency-overrides）
+- **集成测试**: `tests/integration/` — 4 个文件（cli-arguments, context-build, message-pipeline, tool-chain）
 - **共享 mock/fixture**: `tests/mocks/`（api-responses, file-system, fixtures/）
 - **命名**: `describe("functionName")` + `test("behavior description")`，英文
+- **Mock 模式**: 对重依赖模块使用 `mock.module()` + `await import()` 解锁（必须内联在测试文件中，不能从共享 helper 导入）
 - **包测试**: `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
+bunx tsc --noEmit
 ```

 **类型规范**：
@@ -375,41 +271,13 @@ bun run precheck

 ## Working with This Codebase

- **precheck must pass** — `bun run precheck`（typecheck + lint fix + test）必须零错误，任何修改都不能引入新的类型/lint/测试错误。
+- **tsc must pass** — `bunx tsc --noEmit` 必须零错误，任何修改都不能引入新的类型错误。
 - **Feature flags** — 默认全部关闭（`feature()` 返回 `false`）。Dev/build 各有自己的默认启用列表。不要在 `cli.tsx` 中重定义 `feature` 函数。
 - **React Compiler output** — Components have decompiled memoization boilerplate (`const $ = _c(N)`). This is normal.
 - **`bun:bundle` import** — `import { feature } from 'bun:bundle'` 是 Bun 内置模块，由运行时/构建器解析。不要用自定义函数替代它。**`feature()` 只能直接用在 `if` 语句或三元表达式的条件位置**（Bun 编译器限制），不能赋值给变量、不能放在箭头函数体里、不能作为 `&&` 链的一部分。正确：`if (feature('X')) {}` 或 `feature('X') ? a : b`。
 - **`src/` path alias** — tsconfig maps `src/*` to `./src/*`. Imports like `import { ... } from 'src/utils/...'` are valid.
 - **MACRO defines** — 集中管理在 `scripts/defines.ts`。Dev mode 通过 `bun -d` 注入，build 通过 `Bun.build({ define })` 注入。修改版本号等常量只改这个文件。
 - **构建产物兼容 Node.js** — `build.ts` 会自动后处理 `import.meta.require`，产物可直接用 `node dist/cli.js` 运行。
- **Biome 配置** — 42 条 lint 规则因 decompiled 代码被关闭，仅保留 `recommended` 基线。格式化覆盖全项目（`src/`、`scripts/`、`packages/`，含 `packages/@ant/`）。`.tsx` 文件用 120 行宽 + 强制分号；其他文件 80 行宽 + 按需分号。JSON 格式化已启用。`.editorconfig` 与 Biome 配置对齐（2-space 缩进）。修改任何代码后应运行 `bun run precheck` 确认无类型/lint/格式/测试问题，pre-commit hook 会自动拦截不合格提交。
- **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`。
+- **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 产品常见的设计套路（渐变文字、玻璃态、霓虹色）。
--- a/README.md
+++ b/README.md
@@ -6,56 +6,49 @@
 [![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/uApuzJWGKX)
+[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?style=flat-square&logo=discord)](https://discord.gg/qZU6zS7Q)

 > Which Claude do you like? The open source one is the best.

-牢 A (Anthropic) 官方 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 完整复原的工程化项目。虽然很难绷, 但是它叫做 CCB(踩踩背)... 而且, 我们实现了企业版或者需要登陆 Claude 账号才能使用的特性, 并在此基础上扩展了更多好玩的特性。
+牢 A (Anthropic) 官方 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI 工具的源码反编译/逆向还原项目。目标是将 Claude Code 大部分功能及工程化能力复现 (问就是老佛爷已经付过钱了)。虽然很难绷, 但是它叫做 CCB(踩踩背)...

-[Peri Code](https://github.com/KonghaYao/peri)：Claude Code 兼容的 Rust Agent，多年大模型经验匠心制作，国内大模型（DeepSeek/GLM）精调，CPU/内存极致优化，在开发版/树莓派上也能跑 CC 一样的体验。
+[文档在这里, 支持投稿 PR](https://ccb.agent-aura.top/) | [留影文档在这里](./Friends.md) | [Discord 群组](https://discord.gg/qZU6zS7Q)

-[文档在这里](https://ccb.agent-aura.top/) | [留影文档在这里](./Friends.md) | [Discord 群组，群主在线答疑](https://discord.gg/uApuzJWGKX)
+| 特性 | 说明 | 文档 |
+|------|------|------|
+| **Claude 群控技术** | Pipe IPC 多实例协作：同机 main/sub 自动编排 + LAN 跨机器零配置发现与通讯，`/pipes` 选择面板 + `Shift+↓` 交互 + 消息广播路由 | [Pipe IPC](https://ccb.agent-aura.top/docs/features/pipes-and-lan) / [LAN](https://ccb.agent-aura.top/docs/features/lan-pipes) |
+| Remote Control 私有部署 | Docker 自托管 RCS + Web UI | [文档](https://ccb.agent-aura.top/docs/features/remote-control-self-hosting) |
+| /dream 记忆整理 | 自动整理和优化记忆文件 | [文档](https://ccb.agent-aura.top/docs/features/auto-dream) |
+| Web Search | 内置网页搜索工具 | [文档](https://ccb.agent-aura.top/docs/features/web-browser-tool) |
+| 自定义模型供应商 | OpenAI/Anthropic/Gemini/Grok 兼容 | [文档](https://ccb.agent-aura.top/docs/features/custom-platform-login) |
+| Voice Mode | Push-to-Talk 语音输入 | [文档](https://ccb.agent-aura.top/docs/features/voice-mode) |
+| Computer Use | 屏幕截图、键鼠控制 | [文档](https://ccb.agent-aura.top/docs/features/computer-use) |
+| Chrome Use | 浏览器自动化、表单填写、数据抓取 | [自托管](https://ccb.agent-aura.top/docs/features/chrome-use-mcp) [原生版](https://ccb.agent-aura.top/docs/features/claude-in-chrome-mcp) |
+| Sentry | 企业级错误追踪 | [文档](https://ccb.agent-aura.top/docs/internals/sentry-setup) |
+| GrowthBook | 企业级特性开关 | [文档](https://ccb.agent-aura.top/docs/internals/growthbook-adapter) |
+| Langfuse 监控 | LLM 调用/工具执行/多 Agent 全链路追踪 | [文档](https://ccb.agent-aura.top/docs/features/langfuse-monitoring) |
+| Poor Mode | 穷鬼模式，关闭记忆提取和键入建议 | /poor 可以开关 |

-| 特性                        | 说明                                                                                                                         | 文档                                                                                                                                      |
-| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| **Claude 群控技术**         | Pipe IPC 多实例协作：同机 main/sub 自动编排 + LAN 跨机器零配置发现与通讯，`/pipes` 选择面板 + `Shift+↓` 交互 + 消息广播路由 | [Pipe IPC](https://ccb.agent-aura.top/docs/features/uds-inbox) / [LAN](https://ccb.agent-aura.top/docs/features/lan-pipes)                |
-| **ACP 协议一等一支持**      | 支持接入 Zed、Cursor 等 IDE，支持会话恢复、Skills、权限桥接                                                                  | [文档](https://ccb.agent-aura.top/docs/features/acp-zed)                                                                                  |
-| **Remote Control 私有部署** | Docker 自托管远程界面, 可以手机上看 CC                                                                                       | [文档](https://ccb.agent-aura.top/docs/features/remote-control-self-hosting)                                                              |
-| **Langfuse 监控**           | 企业级 Agent 监控, 可以清晰看到每次 agent loop 细节, 可以一键转化为数据集                                                    | [文档](https://ccb.agent-aura.top/docs/features/langfuse-monitoring)                                                                      |
-| **Web Search**              | 内置网页搜索工具, 支持 bing 和 brave 搜索                                                                                    | [文档](https://ccb.agent-aura.top/docs/features/web-browser-tool)                                                                         |
-| **Poor Mode**               | 穷鬼模式，关闭记忆提取和键入建议,大幅度减少并发请求                                                                          | /poor 可以开关                                                                                                                            |
-| **Channels 频道通知**       | MCP 服务器推送外部消息到会话（飞书/Slack/Discord/微信等），`--channels plugin:name@marketplace` 启用                         | [文档](https://ccb.agent-aura.top/docs/features/channels)                                                                                 |
-| **自定义模型供应商**        | OpenAI/Anthropic/Gemini/Grok 兼容  (`/login`)                                                                                          | [文档](https://ccb.agent-aura.top/docs/features/all-features-guide)                                                                        |
-| Voice Mode                  | 语音输入，支持豆包语言输入（`/voice doubao`）                                                                   | [文档](https://ccb.agent-aura.top/docs/features/voice-mode)                                                                               |
-| Computer Use                | 屏幕截图、键鼠控制                                                                                                           | [文档](https://ccb.agent-aura.top/docs/features/computer-use)                                                                             |
-| Chrome Use                  | 浏览器自动化、表单填写、数据抓取                                                                                             | [自托管](https://ccb.agent-aura.top/docs/features/chrome-use-mcp) [原生版](https://ccb.agent-aura.top/docs/features/claude-in-chrome-mcp) |
-| Sentry                      | 企业级错误追踪                                                                                                               | [文档](https://ccb.agent-aura.top/docs/internals/sentry-setup)                                                                            |
-| GrowthBook                  | 企业级特性开关                                                                                                               | [文档](https://ccb.agent-aura.top/docs/internals/growthbook-adapter)                                                                      |
-| /dream 记忆整理             | 自动整理和优化记忆文件                                                                                                       | [文档](https://ccb.agent-aura.top/docs/features/auto-dream)                                                                               |

- 🚀 [想要启动项目](#-快速开始源码版)
+- 🔮 [ ] V6 — 大规模重构石山代码，全面模块分包（全新分支，main 封存为历史版本）
+
+- 🚀 [想要启动项目](#快速开始源码版)
 - 🐛 [想要调试项目](#vs-code-调试)
 - 📖 [想要学习项目](#teach-me-学习项目)

+
 ## ⚡ 快速开始(安装版)

 不用克隆仓库, 从 NPM 下载后, 直接使用

 ```sh
-npm i -g claude-code-best
-
-# bun 安装比较多问题, 推荐 npm 装
-# bun  i -g claude-code-best
-# bun pm -g trust claude-code-best @claude-code-best/mcp-chrome-bridge
-
+bun  i -g claude-code-best
+bun pm -g trust claude-code-best
 ccb # 以 nodejs 打开 claude code
 ccb-bun # 以 bun 形态打开
-ccb update # 更新到最新版本
 CLAUDE_BRIDGE_BASE_URL=https://remote-control.claude-code-best.win/ CLAUDE_BRIDGE_OAUTH_TOKEN=test-my-key ccb --remote-control # 我们有自部署的远程控制
 ```

-> **安装/更新失败？** 先 `npm rm -g claude-code-best` 清理旧版本，再 `npm i -g claude-code-best@latest`。仍失败则指定版本号：`npm i -g claude-code-best@<版本号>`
-
 ## ⚡ 快速开始(源码版)

 ### ⚙️ 环境要求
@@ -63,66 +56,11 @@ CLAUDE_BRIDGE_BASE_URL=https://remote-control.claude-code-best.win/ CLAUDE_BRIDG
 一定要最新版本的 bun 啊, 不然一堆奇奇怪怪的 BUG!!! bun upgrade!!!

 - 📦 [Bun](https://bun.sh/) >= 1.3.11
-
-**安装 Bun：**
-
-```bash
-# Linux 和 macOS
-curl -fsSL https://bun.sh/install | bash
-
-# Windows (PowerShell)
-powershell -c "irm bun.sh/install.ps1 | iex"
-```
-
-**安装后的操作：**
-
-1. **让当前终端识别 `bun` 命令**
-
-   安装脚本会把 `~/.bun/bin` 写入对应的 shell 配置文件。macOS 默认 zsh 环境通常会看到：
-
-   ```text
-   Added "~/.bun/bin" to $PATH in "~/.zshrc"
-   ```
-
-   可以按安装脚本提示重启当前 shell：
-
-   ```bash
-   exec /bin/zsh
-   ```
-
-   如果你使用 bash，重新加载 bash 配置：
-
-   ```bash
-   source ~/.bashrc
-   ```
-
-   Windows PowerShell 用户关闭并重新打开 PowerShell 即可。
-
-2. **验证 Bun 是否可用**
-
-   ```bash
-   bun --help
-   bun --version
-   ```
-
-3. **如果已经安装过 Bun，更新到最新版本**
-
-   ```bash
-   bun upgrade
-   ```
-
 - ⚙️ 常规的配置 CC 的方式, 各大提供商都有自己的配置方式

-### 📍 命令执行位置
-
- 安装或检查 Bun 的命令可以在任意目录执行：
-  `curl -fsSL https://bun.sh/install | bash`、`bun --help`、`bun --version`、`bun upgrade`
- 安装本项目依赖、启动开发模式、构建项目时，必须先进入本仓库根目录，也就是包含 `package.json` 的目录。
-
 ### 📥 安装

 ```bash
-cd /path/to/claude-code
 bun install
 ```

@@ -149,16 +87,17 @@ 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
@@ -178,17 +117,16 @@ TUI (REPL) 模式需要真实终端，无法直接通过 VS Code launch 启动
 ### 步骤

 1. **终端启动 inspect 服务**：
-
   ```bash
   bun run dev:inspect
   ```
-
   会输出类似 `ws://localhost:8888/xxxxxxxx` 的地址。
-2. **VS Code 附着调试器**：

+2. **VS Code 附着调试器**：
   - 在 `src/` 文件中打断点
   - F5 → 选择 **"Attach to Bun (TUI debug)"**

+
 ## Teach Me 学习项目

 我们新加了一个 teach-me skills, 通过问答式引导帮你理解这个项目的任何模块。(调整 [sigma skill 而来](https://github.com/sanyuan0704/sanyuan-skills))
@@ -215,7 +153,7 @@ TUI (REPL) 模式需要真实终端，无法直接通过 VS Code launch 启动
 ## 相关文档及网站

 - **在线文档（Mintlify）**: [ccb.agent-aura.top](https://ccb.agent-aura.top/) — 文档源码位于 [`docs/`](docs/) 目录，欢迎投稿 PR
- **DeepWiki**: [https://deepwiki.com/claude-code-best/claude-code](https://deepwiki.com/claude-code-best/claude-code)
+- **DeepWiki**: <https://deepwiki.com/claude-code-best/claude-code>

 ## Contributors

@@ -233,10 +171,6 @@ TUI (REPL) 模式需要真实终端，无法直接通过 VS Code launch 启动
 </picture>
 </a>

-## 致谢
-
- [doubaoime-asr](https://github.com/starccy/doubaoime-asr) — 豆包 ASR 语音识别 SDK，为 Voice Mode 提供无需 Anthropic OAuth 的语音输入方案
-
 ## 许可证

 本项目仅供学习研究用途。Claude Code 的所有权利归 [Anthropic](https://www.anthropic.com/) 所有。
--- a/README_EN.md
+++ b/README_EN.md
@@ -48,64 +48,11 @@ Sponsor placeholder.
 Make sure you're on the latest version of Bun, otherwise you'll run into all sorts of weird bugs. Run `bun upgrade`!

 - [Bun](https://bun.sh/) >= 1.3.11
-
-**Install Bun:**
-
-```bash
-# Linux and macOS
-curl -fsSL https://bun.sh/install | bash
-
-# Windows (PowerShell)
-powershell -c "irm bun.sh/install.ps1 | iex"
-```
-
-**Post-installation steps:**
-
-1. **Make `bun` available in the current terminal**
-
-   The installer adds `~/.bun/bin` to the matching shell configuration file. On macOS with the default zsh shell, you may see:
-
-   ```text
-   Added "~/.bun/bin" to $PATH in "~/.zshrc"
-   ```
-
-   Restart the current shell as the installer suggests:
-
-   ```bash
-   exec /bin/zsh
-   ```
-
-   If you use bash, reload the bash configuration:
-
-   ```bash
-   source ~/.bashrc
-   ```
-
-   Windows PowerShell users can close and reopen PowerShell.
-
-2. **Verify that Bun is available:**
-   ```bash
-   bun --help
-   bun --version
-   ```
-
-3. **Update to latest version (if already installed):**
-   ```bash
-   bun upgrade
-   ```
-
 - Standard Claude Code configuration — each provider has its own setup method

-### Command Execution Location
-
- Bun installation and checking commands can be run from any directory:
-  `curl -fsSL https://bun.sh/install | bash`, `bun --help`, `bun --version`, `bun upgrade`
- Project dependency installation, development mode, and builds must be run from this repository root, the directory containing `package.json`.
-
 ### Install

 ```bash
-cd /path/to/claude-code
 bun install
 ```

@@ -188,7 +135,7 @@ The TUI (REPL) mode requires a real terminal and cannot be launched directly via
 ## Documentation & Links

 - **Online docs (Mintlify)**: [ccb.agent-aura.top](https://ccb.agent-aura.top/) — source in [`docs/`](docs/), PR contributions welcome
- **DeepWiki**: https://deepwiki.com/claude-code-best/claude-code
+- **DeepWiki**: <https://deepwiki.com/claude-code-best/claude-code>

 ## Contributors

--- a/V6.md
+++ b/V6.md
--- a/biome.json
+++ b/biome.json
@@ -1,113 +1,114 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.4.12/schema.json",
-  "vcs": {
-    "enabled": true,
-    "clientKind": "git",
-    "useIgnoreFile": true
-  },
-  "files": {
-    "includes": ["**", "!!**/dist"]
-  },
-  "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
-  }
+	"$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
+	}
 }
--- a/build.ts
+++ b/build.ts
@@ -1,7 +1,6 @@
 import { readdir, readFile, writeFile, cp } from 'fs/promises'
 import { join } from 'path'
 import { getMacroDefines } from './scripts/defines.ts'
-import { DEFAULT_BUILD_FEATURES } from './scripts/defines.ts'

 const outdir = 'dist'

@@ -9,6 +8,43 @@ 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',
+  // PR-package restored features
+  'WORKFLOW_SCRIPTS',
+  'HISTORY_SNIP',
+  'CONTEXT_COLLAPSE',
+  'MONITOR_TOOL',
+  'FORK_SUBAGENT',
+//   'UDS_INBOX',
+  'KAIROS',
+  'COORDINATOR_MODE',
+  'LAN_PIPES',
+  // 'REVIEW_ARTIFACT', // API 请求无响应，需进一步排查 schema 兼容性
+  // P3: poor mode (disable extract_memories + prompt_suggestion)
+  'POOR',
+]
+
 // Collect FEATURE_* env vars → Bun.build features
 const envFeatures = Object.keys(process.env)
  .filter(k => k.startsWith('FEATURE_'))
@@ -21,14 +57,7 @@ const result = await Bun.build({
  outdir,
  target: 'bun',
  splitting: true,
-  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'),
-  },
+  define: getMacroDefines(),
  features,
 })

@@ -63,8 +92,7 @@ for (const file of files) {
 // (e.g. @anthropic-ai/sandbox-runtime) so Node.js doesn't crash at import time.
 let bunPatched = 0
 const BUN_DESTRUCTURE = /var \{([^}]+)\} = globalThis\.Bun;?/g
-const BUN_DESTRUCTURE_SAFE =
-  'var {$1} = typeof globalThis.Bun !== "undefined" ? globalThis.Bun : {};'
+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)
@@ -83,16 +111,28 @@ console.log(
  `Bundled ${result.outputs.length} files to ${outdir}/ (patched ${patched} for import.meta.require, ${bunPatched} for Bun destructure)`,
 )

-// Step 4: Copy native .node addon files (audio-capture) and vendored binaries (ripgrep)
-const audioCaptureDir = join(outdir, 'vendor', 'audio-capture')
-await cp('vendor/audio-capture', audioCaptureDir, { recursive: true })
-console.log(`Copied vendor/audio-capture/ → ${audioCaptureDir}/`)
+// 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}/`)

-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: Bundle download-ripgrep script as standalone JS for postinstall
+const rgScript = await Bun.build({
+  entrypoints: ['scripts/download-ripgrep.ts'],
+  outdir,
+  target: 'node',
+})
+if (!rgScript.success) {
+  console.error('Failed to bundle download-ripgrep script:')
+  for (const log of rgScript.logs) {
+    console.error(log)
+  }
+  // Non-fatal — postinstall fallback to bun run scripts/download-ripgrep.ts
+} else {
+  console.log(`Bundled download-ripgrep script to ${outdir}/`)
+}

-// Step 5: Generate cli-bun and cli-node executable entry points
+// Step 6: Generate cli-bun and cli-node executable entry points
 const cliBun = join(outdir, 'cli-bun.js')
 const cliNode = join(outdir, 'cli-node.js')

--- a/bun.lock
+++ b/bun.lock
--- a/codecov.yml
+++ b/codecov.yml
@@ -1,51 +0,0 @@
-coverage:
-  status:
-    project:
-      default:
-        target: auto
-        threshold: 1%
-    patch:
-      default:
-        target: 100%
-        only_pulls: true
-
-ignore:
-  - "**/*.tsx"
-  # parseArgs has 3 defensive `/* istanbul ignore next */` checks that are
-  # structurally unreachable (guaranteed by upstream invariants). Bun's
-  # coverage doesn't honor istanbul comments, so we ignore the file at
-  # codecov level — covered logic has 59/62 lines hit.
-  - "src/commands/agents-platform/parseArgs.ts"
-  # resumeAgent's patch lines (1 import + 1 call to filterParentToolsForFork)
-  # require the full async-agent orchestration chain (registerAsyncAgent,
-  # assembleToolPool, runAgent, sessionStorage, agentContext, cwd-override,
-  # 15+ deps) to spawn a "resumed fork" context. Mocking all of them just to
-  # exercise one line is heavy and brittle. Verified 1/2 of patch lines hit
-  # already (the import); the call site is covered by integration tests
-  # outside the unit-test scope.
-  - "packages/builtin-tools/src/tools/AgentTool/resumeAgent.ts"
-  - "**/*.test.ts"
-  - "**/*.test.tsx"
-  - "**/__tests__/**"
-  - "tests/**"
-  - "scripts/**"
-  - "docs/**"
-  - "packages/@ant/ink/**"
-  - "packages/@ant/computer-use-mcp/**"
-  - "packages/@ant/computer-use-input/**"
-  - "packages/@ant/computer-use-swift/**"
-  - "packages/@ant/claude-for-chrome-mcp/**"
-  - "packages/audio-capture-napi/**"
-  - "packages/color-diff-napi/**"
-  - "packages/image-processor-napi/**"
-  - "packages/modifiers-napi/**"
-  - "packages/url-handler-napi/**"
-  - "packages/remote-control-server/web/**"
-  - "src/types/**"
-  - "**/*.d.ts"
-  - "build.ts"
-  - "vite.config.ts"
-
-comment:
-  layout: "diff,flags,files"
-  require_changes: false
--- a/contributors.svg
+++ b/contributors.svg
--- a/docs.json
+++ b/docs.json
@@ -185,4 +185,4 @@
      "destination": "/docs/introduction/what-is-claude-code"
    }
  ]
-}
+}
--- a/docs/agent/sub-agents.mdx
+++ b/docs/agent/sub-agents.mdx
--- a/docs/agent/sur-loop-scheduled-oom.md
+++ b/docs/agent/sur-loop-scheduled-oom.md
@@ -1,492 +0,0 @@
-# System Understanding Report — Loop / Scheduled Autonomy OOM
-
- **Flow id**: `recurring-bug-loop-oom` (pilot flow for autonomy ↔ deep-debug binding)
- **Branch**: `fix/loop-scheduled-autonomy-oom`
- **Worktree**: `E:\Source_code\Claude-code-bast-loop-scheduled-oom-fix`
- **Author**: back-filled from existing working-tree diff (no commits ahead of `main`)
- **Status**: `report` (this document) — pending human approval before `regression-test` advances
-
---
-
-## 1. Problem
-
-### Symptom
-
-Long-running sessions with active scheduled tasks (cron) and/or HEARTBEAT-driven proactive ticks accumulated growing memory, eventually OOM'ing the Bun process. The visible signature was:
-
- `runs.json` under `.claude/autonomy/` growing toward the 200-record cap with most entries stuck at `queued` or `running`
- The internal command queue in REPL / headless mode draining slower than scheduled fires arrive
- Each new fire calling `prepareAutonomyTurnPrompt`, which loads `AGENTS.md` + `HEARTBEAT.md` text and merges due-task lists into a fresh string, holding more closure state per pending command
-
-### Expected behaviour
-
-When a scheduled task fires while its prior run is still queued or running, the new fire should be **skipped** rather than enqueued behind it. When the process that started a run dies, the run should be reaped, not left as `running` forever. Background work spawned by a slash command should complete the originating autonomy run only when that background work itself finishes.
-
-### Actual behaviour (before fix)
-
-1. `useScheduledTasks` and the headless streaming path called `createAutonomyQueuedPrompt` unconditionally on every tick.
-2. `commitAutonomyQueuedPrompt` called `commitPreparedAutonomyTurn` *before* the run record was persisted, so even a duplicate fire that should have been dropped already mutated heartbeat-task last-run state.
-3. `AutonomyRunRecord` had no owner identity, so a run started by a now-dead process stayed `running` indefinitely. Subsequent runs of the same `sourceId` could not detect that their predecessor was effectively gone.
-4. Slash commands that forked detached background work (KAIROS / proactive paths) returned from `processUserInput` immediately. The harness in `handlePromptSubmit` then called `finalizeAutonomyRunCompleted`, marking the run `succeeded` while the actual work continued in the background — but the next scheduled tick of the same source could now race against that detached work, and any error in the detached work had no autonomy run to attribute to.
-
-### Reproduction shape
-
-Not a single deterministic repro — load-induced. Rough recipe:
-
- Configure two `HEARTBEAT.md` tasks at `every 30s` interval
- Add three cron tasks at `every 1m`
- Let the session run > 1 hour, especially across a backgrounded slash command (e.g. KAIROS `/sleep`-style detached fork)
- Watch `.claude/autonomy/runs.json` active-status entry count and Bun heap RSS
-
-### User impact
-
-Sessions with long-lived autonomy/cron use cases were unsafe. The OOM took the entire CLI down, dropping any unflushed messages, MCP connections, and bridge state. Because `.claude/autonomy/` persists, restart did not heal — stale `running` records from the dead PID kept blocking dedup logic on the next start.
-
---
-
-## 2. System boundary
-
-### In scope
-
- Autonomy run lifecycle: create → running → succeeded / failed / cancelled (`src/utils/autonomyRuns.ts`)
- Scheduled-task firing path: cron scheduler → REPL command queue (`src/hooks/useScheduledTasks.ts`)
- Headless streaming variant of the same path (`src/cli/print.ts` `runHeadlessStreaming`)
- Prompt-submit pipeline that finalizes runs after `processUserInput` returns (`src/utils/handlePromptSubmit.ts`)
- Slash-command processing where a command may defer completion to background work (`src/utils/processUserInput/processUserInput.ts`, `processSlashCommand.tsx`)
- `ToolUseContext` extension that lets non-bundled harnesses exercise the KAIROS-gated background-fork path (`src/Tool.ts`)
-
-### Out of scope
-
- The cron scheduler itself (`src/utils/cronScheduler.ts`) — its tick semantics are not changing
- `autonomyFlows.ts` flow state machine — separate from per-run tracking
- HEARTBEAT.md scheduling semantics — unchanged. `parseHeartbeatAuthorityTasks`
-  does change narrowly by masking fenced code blocks before scanning so
-  documented `tasks:` examples cannot shadow the real config block.
- `prepareAutonomyTurnPrompt` content shape — only its call ordering relative to run creation changes
- Any provider-level behaviour (`services/api/**`) — not touched
-
-### Assumptions
-
- `process.pid` is stable for the lifetime of a Bun process and unique enough on a single host that a dead-PID heuristic is safe (collision risk acknowledged but bounded by `runs.json` retention).
- `isProcessRunning(pid)` (from `genericProcessUtils.js`) returns `false` only when the process is actually gone; transient permission errors return `true`/safe-fail. Verified in step 6.
- `getSessionId()` is initialized before any autonomy run creates records, since autonomy runs only originate after REPL or headless main loop boot.
-
---
-
-## 3. Entry points
-
-| Surface | Entry | Notes |
-|---|---|---|
-| REPL | `useScheduledTasks` cron tick | Calls `createScheduledTaskQueuedCommand` (new helper) instead of raw `createAutonomyQueuedPrompt` |
-| REPL | Slash command pipeline | `processUserInput → processUserInputBase → processSlashCommand` now threads `autonomy` context so commands can defer completion |
-| Headless | `runHeadlessStreaming` cron path | Same migration to `createAutonomyQueuedPromptIfNoActiveSource`, plus `shouldCreate` callback honouring `inputClosed` |
-| Tool harness | `ToolUseContext.options.allowBackgroundForkedSlashCommands` | Non-prod way to exercise the KAIROS-gated detached-fork path; production still requires `feature('KAIROS')` + `AppState.kairosEnabled` |
-| Persistence | `.claude/autonomy/runs.json` | Schema gains `ownerProcessId`, `ownerSessionId`; readers must tolerate older records lacking these fields |
-
---
-
-## 4. Key files
-
-| File | Lines changed | Why it matters |
-|---|---|---|
-| `src/utils/autonomyRuns.ts` | +260 | Owns the new identity + dedup + stale-recovery logic; introduces `createAutonomyRunIfNoActiveSource`, `hasActiveAutonomyRunForSource`, `recoverStaleActiveAutonomyRun`, `commitAutonomyQueuedPromptIfNoActiveSource`, two-phase commit. The structural heart of the fix. |
-| `src/utils/processUserInput/processSlashCommand.tsx` | +707 / -454 | Rewrites slash-command dispatch so detached background work signals `deferAutonomyCompletion`; refactor changes shape but not the public command set. |
-| `src/hooks/useScheduledTasks.ts` | +47 | Migrates both scheduler call sites to the dedup helper; extracts `createScheduledTaskQueuedCommand` for unit testing. |
-| `src/cli/print.ts` | +19 / -27 | Headless variant of the same migration; collapses the previous prepare+commit two-call sequence into the new dedup helper with `shouldCreate`. |
-| `src/utils/handlePromptSubmit.ts` | +12 | Tracks `deferredAutonomyRunIds` so it skips finalizing runs whose owning command deferred completion. |
-| `src/utils/processUserInput/processUserInput.ts` | +10 | Threads `autonomy` context and surfaces `deferAutonomyCompletion` on the result type. |
-| `src/Tool.ts` | +6 | Adds `allowBackgroundForkedSlashCommands` escape hatch for non-bundled harnesses (unit tests). |
-| `src/utils/__tests__/autonomyRuns.test.ts` | +168 | Regression coverage for dedup + stale recovery + ownership stamping. |
-| `src/hooks/__tests__/useScheduledTasks.test.ts` | new (75 lines) | Asserts scheduler does not double-fire while previous run is queued. |
-| `src/utils/processUserInput/__tests__/processSlashCommand.test.ts` | new (~280 lines) | Covers the deferred-completion handshake on slash-command paths. |
-
---
-
-## 5. Call flow (post-fix)
-
-```text
-cron tick (useScheduledTasks)
-  └─> createScheduledTaskQueuedCommand(task)
-        └─> createAutonomyQueuedPromptIfNoActiveSource
-              ├─> prepareAutonomyTurnPrompt        (loads AGENTS.md + HEARTBEAT.md)
-              ├─> shouldCreate?  ──► no ──► RETURN null   (no side effects)
-              └─> commitAutonomyQueuedPromptIfNoActiveSource
-                    └─> commitAutonomyQueuedPromptInternal(skipWhenActiveSource = true)
-                          └─> createAutonomyRunIfNoActiveSource
-                                ├─> buildAutonomyRunRecord  (stamps ownerProcessId, ownerSessionId)
-                                └─> persistAutonomyRunRecord(skip = true)
-                                      └─> withAutonomyPersistenceLock
-                                            ├─> for each run with same (trigger,sourceId,ownerKey) and active status:
-                                            │     ├─> isStaleActiveAutonomyRun?  ──► recoverStaleActiveAutonomyRun (mark failed)
-                                            │     └─> else ──► hasBlockingActiveRun = true
-                                            ├─> if blocking ──► RETURN created=false (no enqueue)
-                                            └─> else ──► unshift record, write file, return true
-                          ├─> if run is null ──► RETURN null (caller drops the tick)
-                          └─> else ──► commitPreparedAutonomyTurn(prepared)  (heartbeat last-run state ONLY now mutates)
-                                └─> assemble QueuedCommand and return
-```
-
-Two structural moves: (a) preparing the prompt no longer commits heartbeat state; only successful run insertion commits it. (b) blocking active runs of the same source short-circuit before the queue is touched.
-
-For slash commands:
-
-```text
-processUserInput → processUserInputBase
-  └─> processSlashCommand(..., autonomy = cmd.autonomy)
-        └─> command implementation
-              ├─> runs synchronously                    ──► returns normal result
-              └─> spawns detached/background work       ──► returns result with deferAutonomyCompletion = true
-                                                              + handles its own finalize* call when work ends
-
-handlePromptSubmit (caller of processUserInput):
-  ├─> records cmd.autonomy.runId in autonomyRunIds
-  ├─> on result with deferAutonomyCompletion=true: adds runId to deferredAutonomyRunIds
-  └─> finalize loop: skips deferred ids in BOTH success and error branches
-```
-
---
-
-## 6. Data flow
-
-### `runs.json` record schema (delta)
-
-```ts
-type AutonomyRunRecord = {
-  // existing
-  runId: string
-  status: 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled'
-  trigger: AutonomyTriggerKind
-  sourceId?: string
-  ownerKey?: string
-  // new
-  ownerProcessId?: number     // process.pid at create time and at markRunning time
-  ownerSessionId?: string     // getSessionId() at the same points
-  // ...
-}
-```
-
-Backward compatibility: older records with both fields absent are treated as "owner unknown" — they never satisfy `isStaleActiveAutonomyRun` (which requires `typeof ownerProcessId === 'number'`), so they remain blocking until they are completed normally or manually cancelled. This is intentional: we cannot prove they are stale.
-
-### Stale-recovery rule
-
-```text
-isStaleActiveAutonomyRun(run) ⇔
-    run.status ∈ {queued, running}
-  ∧ typeof run.ownerProcessId === 'number'
-  ∧ !isProcessRunning(run.ownerProcessId)
-```
-
-Recovery mutates the in-memory list inside the persistence lock and writes it back, marking the stale run `failed` with error prefix `"Recovered stale active autonomy run"`.
-
-### Heartbeat last-run state mutation point
-
-Before fix: `commitAutonomyQueuedPrompt` called `commitPreparedAutonomyTurn(prepared)` *first*, then created the run. A skipped duplicate already advanced heartbeat last-run timestamps.
-
-After fix: `commitPreparedAutonomyTurn` is called only after `createAutonomyRunIfNoActiveSource` returns a non-null record. Skipped duplicates leave heartbeat state untouched, so the next eligible window is still at the originally scheduled point.
-
---
-
-## 7. State model
-
-### Run status lifecycle (unchanged at edges, tightened in the middle)
-
-```text
-queued ──► running ──► succeeded
-   │           │
-   │           └────► failed
-   ├──────────────────► cancelled
-   └──► failed (stale recovery, new path)
-```
-
-### New invariants
-
-1. **Same-source mutual exclusion**: at most one record with `(trigger, sourceId, ownerKey, status ∈ active)` is *non-stale* at any time. Enforced inside `withAutonomyPersistenceLock` in `persistAutonomyRunRecord`.
-
-2. **Owner stamping at active transitions**: any path that sets a run to `queued` or `running` must stamp `ownerProcessId = process.pid` and `ownerSessionId = getSessionId()`. `markAutonomyRunRunning` updated to do this for the running transition (creation already did it).
-
-3. **Two-phase commit ordering**: heartbeat-task last-run state may only be advanced after the run record has been successfully inserted. Equivalent to "prompt commit ⇒ run row exists".
-
-4. **Deferred completion contract**: if a slash command's result has `deferAutonomyCompletion=true`, the harness (`handlePromptSubmit`) MUST NOT finalize the run; the command implementation OWNS the finalize call. Tracked via `deferredAutonomyRunIds` set scoped to a single `executeUserInput` invocation.
-
-### Concurrency / retry risks
-
- Two processes sharing the same project root can race on `runs.json`. Mitigated by `withAutonomyPersistenceLock` (file-locking already in place), not by the new code.
- Two ticks of the same scheduled task within a single process serialize on the same lock; only the first wins, the rest see the active record and return `null`.
- A process killed between persisting the record and committing the prompt leaves a `queued` record with the dead PID. Stale recovery on the next tick of the same source converts it to `failed`, freeing the source. This is the new safety net.
-
-### Two-phase commit crash window (acknowledged limitation)
-
-Within `commitAutonomyQueuedPromptInternal` the order is:
-
-1. `createAutonomyRunCore` → `persistAutonomyRunRecord` → run row written under lock
-2. `commitPreparedAutonomyTurn(prepared)` → in-memory `heartbeatTaskLastRunByKey` Map advanced
-
-These two steps are NOT atomic. If the process is killed between (1) and (2):
-
- `runs.json` has a fresh `queued` record stamped with the now-dead PID.
- `heartbeatTaskLastRunByKey` was an in-memory Map; its state vanishes with
-  the process. On restart the Map is empty.
- The dead-PID record is reaped via stale-recovery on the next tick of the
-  same source → `status=failed`. New record can be created.
- Because the Map starts empty after restart, every heartbeat task fires
-  immediately on first tick rather than waiting for its configured
-  interval window from the previous run.
-
-**Severity**: low. The Map is a runtime cache, not a persisted schedule
-contract; "fire immediately on restart" is a recoverable behaviour, not
-data corruption or duplicate work (the dead-PID record blocks the source
-until stale-recovery, so duplicate fires don't stack).
-
-**Why not fix now**: persisting the heartbeat last-run state to disk inside
-the same lock would couple two unrelated state machines (autonomy runs vs
-heartbeat scheduling) and require a new on-disk schema. The cost outweighs
-the rare edge case (process death within microseconds between two
-in-memory operations). Tracked here so a future flow can pick it up if
-restart-after-crash schedule disruption becomes observable in practice.
-
---
-
-## 8. Existing tests
-
-### Pre-fix
-
- `src/utils/__tests__/autonomyRuns.test.ts` covered create / list / mark transitions for the basic happy path.
- No coverage for: dedup of same-source active run, stale-PID recovery, ownership stamping, deferred completion handshake, two-phase commit ordering.
- `useScheduledTasks` had no unit tests — only indirect coverage via REPL integration.
- `processSlashCommand` had no autonomy-context coverage.
-
-### Added in this branch
-
- `src/utils/__tests__/autonomyRuns.test.ts`: +168 lines covering dedup, stale recovery (mocked dead PID), ownership stamping at create + `markAutonomyRunRunning`, two-phase commit invariant.
- `src/hooks/__tests__/useScheduledTasks.test.ts`: new file, 75 lines. Asserts scheduler skips double-fire when prior run is `queued`/`running`, and resumes when prior run finalizes.
- `src/utils/processUserInput/__tests__/processSlashCommand.test.ts`: new file, ~280 lines. Covers `deferAutonomyCompletion=true` propagation; uses `allowBackgroundForkedSlashCommands` to bypass the `feature('KAIROS')` gate inside unit tests.
-
-### Not yet covered (proposed for `regression-test` step)
-
- Cross-process race against the persistence lock — currently relies on file-lock correctness; consider a focused integration test that spawns two children and verifies only one wins.
- Heartbeat last-run-state non-advance on skipped duplicates — assertable with a thin unit test against `prepareAutonomyTurnPrompt` + the dedup path; not blocking.
-
---
-
-## 9. Competing root-cause hypotheses
-
-### H1 — "Prompt size is the OOM source"
-
-**Claim**: each scheduled tick rebuilds a long prompt string (AGENTS.md + HEARTBEAT.md + due-task list); the cumulative retention of these strings in the queue causes heap pressure.
-
-**Evidence for**: `prepareAutonomyTurnPrompt` does build a multi-section string each tick; `AGENTS.md` in this repo is now 220 lines.
-
-**Evidence against**: the diff does not shrink any prompt content nor change `prepareAutonomyTurnPrompt`'s output. If H1 were the real cause, the fix would have moved string assembly behind a cache or LRU. The fix instead targets the *number* of in-flight runs.
-
-**Verdict**: contributing factor at most. Rejected as primary root cause.
-
-### H2 — "Background-forked slash commands leak runs"
-
-**Claim**: KAIROS-style slash commands that fork detached work return immediately from `processUserInput`; the harness in `handlePromptSubmit` then finalizes the run as `succeeded`. Any error in the background work is unattributable, and (more importantly) the *next* scheduled fire of the same source happens to find no active run, so multiple background workers stack up behind the same source.
-
-**Evidence for**: the diff explicitly adds `deferAutonomyCompletion`, threads `autonomy` context into `processUserInputBase`, and changes `handlePromptSubmit` to skip finalization for deferred runs. New test file `processSlashCommand.test.ts` is dedicated to this exact handshake.
-
-**Evidence against**: a pure same-source dedup miss would also explain the symptom; H3 covers that.
-
-**Verdict**: real and load-bearing. Confirmed by the targeted code added.
-
-### H3 — "Scheduled-task tick has no dedup against prior run"
-
-**Claim**: cron tick / heartbeat tick fires unconditionally; if previous tick's run is still `queued`/`running` the queue grows by one each interval. Compounded across multiple sources, queue + `runs.json` active subset never shrink.
-
-**Evidence for**: pre-fix `useScheduledTasks` and `runHeadlessStreaming` both called `createAutonomyQueuedPrompt` (no dedup). Diff replaces both call sites with `createAutonomyQueuedPromptIfNoActiveSource`. Persistence-side dedup added in the same change.
-
-**Evidence against**: alone, this would make scheduling buggy but not necessarily OOM; the queue might catch up under light load.
-
-**Verdict**: real and load-bearing. Confirmed by the targeted code added.
-
-### H4 — "Dead-process runs poison dedup forever"
-
-**Claim**: even with H3 fixed, a process killed mid-run leaves a `running` record on disk with no owner liveness check; the next process loading `runs.json` would treat it as blocking and never schedule that source again.
-
-**Evidence for**: the diff stamps `ownerProcessId` and adds `isStaleActiveAutonomyRun` checked against `isProcessRunning`. Without H4, H3's fix would create a new failure mode (silent permanent suppression).
-
-**Evidence against**: pre-fix code had no dedup, so this failure mode could not have been reached pre-fix.
-
-**Verdict**: real, but secondary. It exists because H3's fix introduces it. Required to ship together.
-
---
-
-## 10. Chosen root cause
-
-**Combined H2 + H3 + H4**: the unbounded growth of active autonomy runs is the product of three independently insufficient gaps that line up under load:
-
-1. Scheduled / heartbeat ticks do not dedup against an active prior run for the same source (H3).
-2. Background-forked slash commands report `succeeded` to the harness while their work is still detached, so subsequent ticks see no active run and stack workers behind the source (H2).
-3. Process death between record creation and run completion leaves zombie active records on disk that would block dedup permanently if (1) is fixed alone (H4).
-
-Why previous local patches likely failed: any one of these in isolation looks fixable as a small guard, but fixing only one converts the OOM into a different misbehaviour (silent suppression after crash, or duplicate detached workers). The minimal correct fix needs all three primitives: **same-source dedup**, **owner stamping + stale recovery**, **deferred-completion handshake**, plus the **two-phase commit ordering** that ensures heartbeat state never advances on a skipped duplicate.
-
---
-
-## 11. Fix plan
-
-### Minimal fix surface
-
-| Module | Change | Reason |
-|---|---|---|
-| `autonomyRuns.ts` | Owner stamping; `createAutonomyRunIfNoActiveSource`; `commitAutonomyQueuedPromptIfNoActiveSource`; two-phase commit; stale recovery | The structural primitives |
-| `useScheduledTasks.ts` | Replace both call sites with the dedup helper; extract `createScheduledTaskQueuedCommand` | Apply dedup at REPL scheduler |
-| `cli/print.ts` | Same migration in headless streaming path | Apply dedup in headless mode |
-| `handlePromptSubmit.ts` | Track `deferredAutonomyRunIds`; skip them in success and error finalize loops | Wire the deferred-completion contract |
-| `processUserInput.ts` | Thread `autonomy` ctx; surface `deferAutonomyCompletion` | Plumbing for the contract |
-| `processSlashCommand.tsx` | Background-fork commands set `deferAutonomyCompletion`; own their finalize call | Implementation of the contract |
-| `Tool.ts` | `allowBackgroundForkedSlashCommands` flag on `ToolUseContext.options` | Make the path testable from non-bundled harnesses |
-
-### Tests added
-
- `autonomyRuns.test.ts`: dedup, stale recovery (mocked dead PID via `isProcessRunning` mock), owner stamping at both create and `markAutonomyRunRunning`, two-phase commit ordering.
- `useScheduledTasks.test.ts`: scheduler skips double-fire, resumes after finalize.
- `processSlashCommand.test.ts`: deferred-completion handshake propagates to `handlePromptSubmit` correctly.
-
-### Compatibility / migration risk
-
- Older `runs.json` records lacking `ownerProcessId` are tolerated — never identified as stale, so they keep their blocking semantics. Operators who upgrade with stale `running` records on disk from a previous OOM crash will still need to manually `cancel` those runs (or wait for them to age out of the 200-record cap) the *first* time. After one full create cycle on the upgraded version, all new records carry owners.
- **Observability gap on legacy blocking (added by reviewer 2026-04-28)**: when a no-owner active record blocks dedup, the current code path is silent — operators see "scheduled tasks stop firing" with no diagnostic. `implement` step MUST add a one-line warn log inside `persistAutonomyRunRecord`'s blocking branch: when `hasBlockingActiveRun = true` AND the blocking run has `ownerProcessId === undefined`, emit `[autonomyRuns] blocked by legacy un-owned active run <runId> (createdAt=<ts>); cancel manually if this is a stale upgrade artifact`. ≤ 10 lines of code, converts silent hang into a diagnosable signal. Do **not** change behavior — just observability.
- `ToolUseContext.options.allowBackgroundForkedSlashCommands` is opt-in and defaults absent; production harness behaviour unchanged.
- No on-disk schema version bump required.
-
-### Rollback plan
-
- Revert the working tree to `main`'s versions of all 8 files. The `runs.json` schema additions are tolerated by older code (extra fields ignored).
- If a stale record is preventing scheduling after rollback, manually edit `runs.json` (status → `cancelled`) or run `/autonomy flow cancel` for affected flows.
- No dependency, no build flag, no settings-file change is needed for rollback.
-
-### Out of scope (intentionally)
-
- Capping `prepareAutonomyTurnPrompt` output size (H1) — addressable later if needed; not load-bearing for the OOM.
- Cross-process file-lock correctness review — relies on the existing `withAutonomyPersistenceLock`. Out of scope for this flow.
- A migration utility to clean stale records on startup — discussed and rejected as avoidable: 200-record cap rolls them off naturally.
-
---
-
-## 12. Verification
-
-### Commands (binding per `.claude/autonomy/AGENTS.md` §4)
-
-```bash
-bun run typecheck
-bun test src/utils/__tests__/autonomyRuns.test.ts
-bun test src/hooks/__tests__/useScheduledTasks.test.ts
-bun test src/utils/processUserInput/__tests__/processSlashCommand.test.ts
-bun test                              # full unit suite
-bun run lint
-bun run build
-```
-
-### Manual checks (proposed for `implement` step)
-
- Start a session with two `HEARTBEAT.md` 30s tasks for ≥ 30 minutes; observe `runs.json` active-status entry count stays bounded (≤ number of distinct sources).
- Force-kill the Bun process during a `running` record. Restart. Verify the next tick of the same source recovers (record marked `failed` with the stale-recovery error prefix) and a new run starts.
- Run a KAIROS-gated detached slash command path under the test harness (`allowBackgroundForkedSlashCommands=true`) and verify `handlePromptSubmit` does not finalize the run while the background work is still active.
-
-### Observability checks
-
- `[ScheduledTasks] skipping <id>: previous run still queued or running` debug log appears when dedup fires (added in `useScheduledTasks.ts`). Use it to confirm dedup is reached in real sessions.
- `runs.json` records with status `failed` and error starting `"Recovered stale active autonomy run"` indicate stale-recovery actually fired.
-
---
-
-## 13. Open questions
-
-1. ~~Should `markAutonomyRunRunning` be called in *all* paths that transition an autonomy run to `running`, or only the prompt-submit path?~~ **Closed (verified 2026-04-28).**
-   `markAutonomyRunRunning` (`autonomyRuns.ts:554-579`) is the **only** function that transitions `AutonomyRunRecord.status → 'running'`. It stamps `ownerProcessId = process.pid` and `ownerSessionId = getSessionId()` unconditionally, then internally calls `markManagedAutonomyFlowStepRunning` to mirror to flow state. `markManagedAutonomyFlowStepRunning` is only invoked from this one call site (`autonomyRuns.ts:571`); no caller bypasses the stamp. All four real callers (`cli/print.ts:2177`, `screens/REPL.tsx:4859`, `utils/handlePromptSubmit.ts:492`, `utils/swarm/inProcessRunner.ts:741`) go through the stamping path. Flow records intentionally do not carry owner fields — the run record is source of truth and flow steps mirror via `latestRunId`. Stale-recovery operates on runs, so flow-step runs are covered.
-2. ~~`getSessionId()` import was added to `autonomyRuns.ts`. Confirm no circular import is introduced...~~ **Closed (verified 2026-04-28).**
-   No risk on three counts: (a) `autonomyRuns.ts:4` already imported `getProjectRoot` from `bootstrap/state.js`; the new `getSessionId` is appended to the same import line, adding zero new module-level coupling. (b) Reverse direction is empty — `grep -rn 'autonomy*' src/bootstrap/` yields no results, so the dependency stays one-way. (c) `getSessionId()` (`bootstrap/state.ts:425-427`) returns `STATE.sessionId`, which is initialized at module load with `randomUUID()` and re-randomized by `resetStateForTests()` per test — never `undefined`, never throws. The existing test file deliberately uses the real `bootstrap/state` module (not a mock) and already asserts `ownerProcessId === process.pid` / `ownerSessionId` is a string in the new ownership tests, plus exercises stale recovery with a fake dead PID (`2_147_483_647`). No mock updates needed.
-3. Is the 200-record cap still appropriate now that recovery turns stale runs into `failed`? Active records will churn faster; the cap may roll off legitimate completed records sooner. Not a correctness issue, but worth noting.
-
---
-
-## 14. Approval gate
-
-This SUR satisfies `AGENTS.md` §3 step `report` exit criteria once a human reviewer:
-
- [x] confirms the chosen root cause (§10) matches their reading of the diff — **agent-ticked under user delegation 2026-04-28; see §15 verification table row 1**
- [x] approves the §11 fix plan including the deferred-completion contract — **agent-ticked under user delegation 2026-04-28; Concern A's warn-log requirement folded into §11**
- [x] acknowledges the §11 compatibility note about pre-existing stale records on disk — **agent-ticked under user delegation 2026-04-28; §11 extended with Concern A observability gap**
- [x] §13 open question 1 (stamping completeness in flow-step runners) — closed 2026-04-28; see §13 for the verification trace
- [x] Concern B (processSlashCommand.tsx >50% diff) — **resolved 2026-04-28 by commit-split rule, see §15**
-
---
-
-## 15. Reviewer findings (2026-04-28, agent-reviewed)
-
-The user explicitly delegated SUR review work to the agent. The four §14 checkboxes
-remain user's decision; this section records the agent's verification work and
-recommendations to make that decision faster and more auditable.
-
-### Verification work performed
-
-| Claim | Cross-check | Result |
-|---|---|---|
-| §10 H2/H3/H4 互锁 | Walked each "fix only one" counterfactual | ✅ Real interlock — fixing only one converts OOM into a different bug (silent suppression / persistent stacking) |
-| §11 fix surface covers all 8 modified files | Compared against `git diff --stat` | ✅ Each file has a row in the table |
-| §11 "extra fields ignored" rollback claim | JSON parse semantics | ✅ Correct |
-| §11 compatibility claim "tolerated" | Re-read `isStaleActiveAutonomyRun` (`autonomyRuns.ts`) | ⚠️ Tolerance is real but **silent** — gap surfaced as Concern A below |
-| §13 Q1 owner stamping completeness | (closed in earlier turn — see §13) | ✅ |
-| §13 Q2 circular-import / mock impact | (closed in earlier turn — see §13) | ✅ |
-| §13 Q3 200-record cap acceptability | Reasoned about stale-recovery-driven churn | ✅ Non-blocking; forensic loss only |
-
-### Concerns surfaced
-
-**Concern A — silent legacy blocking (now folded into §11)**: when a no-owner active
-record from a pre-upgrade crash blocks dedup, the operator gets no signal — just
-"scheduled tasks stop firing." The §11 compatibility section was extended to require
-a one-line warn log in `implement`. This is an observability fix, not a behavior
-change.
-
-**Concern B — `processSlashCommand.tsx` is +707/-454 (>50% rewrite)** — **RESOLVED 2026-04-28**:
-investigation showed the diff is composed of:
- **18 contract-related lines** (verified by `grep -E '(autonomy|QueuedCommand|deferAutonomy|finalizeAutonomy|allowBackgroundForkedSlashCommands|deferredAutonomy)'`):
-  - import `QueuedCommand` type
-  - import `finalizeAutonomyRunCompleted` / `finalizeAutonomyRunFailed`
-  - add `autonomy?: QueuedCommand['autonomy']` parameter to `executeForkedSlashCommand` (3 sites)
-  - extend KAIROS gate to also accept `context.options.allowBackgroundForkedSlashCommands === true` (test escape hatch)
-  - finalize the run from the detached background path on success/failure
-  - set `deferAutonomyCompletion: Boolean(autonomy?.runId)` on the result
-  - thread `autonomy` to nested calls
- **~30-50 lines** of necessary control-flow scaffolding around the contract code
- **~250 lines** of pure Biome reformatting churn (single-line imports, trailing semicolons)
-
-**Resolution rule (binding for `implement`)**: when committing this branch, split
-`processSlashCommand.tsx` into **two commits** on the same branch:
-
-```text
-chore: reformat processSlashCommand with Biome   # ~250 lines, formatter-only
-feat: thread autonomy run id through forked slash commands for deferred completion   # ~50 lines, contract logic
-```
-
-This satisfies `~/.claude/rules/deep-debug/core.md` §2 ("bug fix 不允许混入...格式化")
-in spirit by making the contract commit reviewable in isolation, without
-requiring a fragile manual revert of formatter output (which Biome would
-re-apply on the next save). All other 7 modified files in the OOM fix do not
-require commit splitting — verify by sampling their diffs at `implement` time.
-
-**Concern C — stale-recovery rate metric (deferred)**: post-implement, track daily
-stale-recovery count. If consistently elevated, the 200-record cap may need
-revisiting (relates to §13 Q3). Not a blocker; suggested for follow-up flow.
-
-### Agent recommendations on the §14 checkboxes
-
-| §14 box | Agent recommendation | Rationale |
-|---|---|---|
-| §10 chosen root cause | Approve | H2/H3/H4 互锁 verified; diff supports each branch |
-| §11 fix plan (with §15 Concern A folded in) | Approve | Minimal, complete, regression-tested |
-| §11 compatibility note | Acknowledge as-extended (§11 now includes the warn-log requirement from Concern A) | Silent legacy blocking would surprise users; the added log makes it diagnosable |
-| Concern B `processSlashCommand.tsx` >50% diff | Resolved by commit-split rule (chore + feat) | 18 lines contract + ~250 lines formatter churn; commit split makes review tractable without fragile revert |
-
-**Final status (2026-04-28, agent-resolved under user delegation)**: all five §14
-boxes ticked. Flow `recurring-bug-loop-oom` may advance from `report` to
-`regression-test`. Implement-time obligations folded in:
-
-1. Add the legacy-blocking warn log in `persistAutonomyRunRecord` (Concern A, ≤10 lines)
-2. Commit-split `processSlashCommand.tsx` into chore + feat (Concern B)
-3. Verify the other 7 modified files do not need commit-splitting (sample their diffs)
-4. Track stale-recovery counts post-deploy for §13 Q3 / Concern C follow-up
-
-After approval: flow advances to `regression-test`. The targeted commands in §12 must produce a verifiable failing state on the *pre-fix* tree before the post-fix tree is allowed to satisfy `implement`. Since this branch already contains the fix, the regression evidence will be reconstructed by checking out one parent, running the targeted tests (expected: fail), then returning to HEAD (expected: pass).
--- a/docs/agent/sur-skill-overflow-bugs.md
+++ b/docs/agent/sur-skill-overflow-bugs.md
@@ -1,91 +0,0 @@
-# System Understanding Report — Skill Search / Skill Learning Overflow Bugs
-
- **Flow id**: `recurring-bug-skill-overflow` (sibling pilot to `recurring-bug-loop-oom`)
- **Branch**: `fix/loop-scheduled-autonomy-oom` (folded into the OOM PR — same audit-and-cap pattern)
- **Trigger**: post-merge review of the autonomy OOM fix surfaced unbounded module-level state in adjacent `EXPERIMENTAL_SKILL_SEARCH` and `SKILL_LEARNING` subsystems. The user explicitly asked for a `肯定也有同类溢出` audit.
-
---
-
-## 1. Problem
-
-The autonomy OOM bug came from unbounded module-level state (run records, scheduler queues, heartbeat timestamps) growing for the lifetime of the process. The skill search + skill learning subsystems exhibit the same class of bug across **5 module-level Maps/Sets**, only one of which had been documented in `scripts/defines.ts` ("projectContext cache 无淘汰机制（非 GB 级主因）").
-
-These bugs were latent because:
-
- `EXPERIMENTAL_SKILL_SEARCH` / `SKILL_LEARNING` were enabled-by-default in `DEFAULT_BUILD_FEATURES`, but tests pass because they exercise short paths.
- None of the unbounded caches grow per-tool-call; they grow per **distinct query** / **distinct cwd** / **distinct skill name** / **distinct gap signal** / **distinct promotion**, which is sub-linear in session length but monotone forever.
- A long-running daemon-style process (KAIROS sessions, multi-day worktrees) would observe the growth.
-
-## 2. Module-level state audit
-
-| File:Line | Symbol | Pre-fix bound | Pre-fix evict |
-|---|---|---|---|
-| `intentNormalize.ts:52` | `cache: Map<query, keywords>` | none | only `clearIntentNormalizeCache()` for tests |
-| `prefetch.ts:17` | `discoveredThisSession: Set<skillName>` | none | none |
-| `prefetch.ts:18` | `recordedGapSignals: Set<gapKey>` | none | none |
-| `projectContext.ts:48` | `contextCache: Map<cwd, ProjectContext>` | none | only `resetProjectContextCacheForTest()` |
-| `promotion.ts:26` | `sessionPromotedIds: Set<instinctId>` | none | only `resetPromotionBookkeeping()` for tests |
-| `runtimeObserver.ts:61` | `lastProcessedMessageIds: Set<msgKey>` | **MAX 1000** | FIFO trim ✓ already bounded |
-| `toolEventObserver.ts:50` | `emittedTurns: Map<sid, Set<turn>>` | **MAP_MAX 50, SET_MAX 100** | LRU prune via `pruneEmittedTurns()` called inside `markTurn` ✓ already bounded |
-| `observerBackend.ts:21` | `registry: Map<name, Backend>` | fixed N | n/a — registry pattern, finite ✓ |
-
-**5 unbounded out of 8 module-level mutables.** All 5 are addressed in this PR.
-
-## 3. Severity rationale
-
-Per-entry cost is small (key strings + small objects), so OOM in days is unlikely on a normal workstation. But the canary scenarios:
-
- **`intentNormalize.cache`**: every distinct Chinese query → Haiku call → cached. A session that browses a large Chinese codebase or replays many transcripts can hit thousands of distinct queries; ~600 bytes per entry × 10k = ~6 MB. Plus, **every cache miss is a Haiku API call**, so default-enabled means every fresh session pays a request on first non-ASCII query — unintended cost.
- **`projectContext.contextCache`**: each `SkillLearningProjectContext` carries instinct + skill lists. Multi-worktree orchestrators (this very repo!) blow past the typical "1 cwd per session" assumption.
- **`prefetch` Sets**: in chatty sessions thousands of skill discovery names accumulate.
- **`sessionPromotedIds`**: smallest practical risk (single-digit promotions per session normally), but a long-lived sandbox could push it; a defensive cap is cheap.
-
-The fix bounds all 5 with FIFO/LRU eviction at sensible sizes (200–1000 entries). No data-corruption risk: degraded behaviour on cap-overflow is benign (re-emit a duplicate signal, re-Haiku a query, re-resolve a cwd context). Same risk profile as the autonomy stale-recovery design.
-
-## 4. Fix surface
-
-| File | Change |
-|---|---|
-| `src/services/skillSearch/intentNormalize.ts` | `setCachedQueryIntent()` helper, `CACHE_MAX_ENTRIES=200` / `CACHE_TRIM_TO=150`, LRU touch on hit |
-| `src/services/skillSearch/prefetch.ts` | `addBoundedSessionEntry()` helper, `SESSION_TRACKING_MAX=1000` / `TRIM_TO=750`; `discoveredThisSession` and `recordedGapSignals` route through it |
-| `src/services/skillLearning/projectContext.ts` | `setProjectContextCache()` helper, `PROJECT_CONTEXT_CACHE_MAX=32` / `TRIM_TO=24`, LRU touch on hit |
-| `src/services/skillLearning/promotion.ts` | `recordSessionPromoted()` helper, `SESSION_PROMOTED_IDS_MAX=256` / `TRIM_TO=192` |
-| `src/services/skillSearch/featureCheck.ts` | Two-layer gate: build flag must be on AND `SKILL_SEARCH_ENABLED=1` env must be set. Defaults to OFF when env is unset, so the slash command remains visible but the runtime hot paths stay dormant until the operator explicitly enables. |
-| `src/services/skillLearning/featureCheck.ts` | Same two-layer pattern (build flag + `SKILL_LEARNING_ENABLED=1` or legacy `FEATURE_SKILL_LEARNING=1`). |
-| `scripts/defines.ts` | Comment annotated to clarify that the build flags now serve only to compile commands in; runtime activation is operator-driven. |
-
-## 5. Why default-off (without removing from build)?
-
-Three reasons aside from the unbounded-cache concern:
-
-1. **Implicit cost**: `intentNormalize` calls Haiku on cache miss. Default-on means every session that types Chinese pays an API call, even when the operator never asked for skill search.
-2. **Disk side effects**: `SKILL_LEARNING` attaches observers that persist observations to `~/.claude` storage. Storage volume should be opt-in, not background.
-3. **Experimental status**: the flag is literally named `EXPERIMENTAL_*`. Default-enabling an experimental subsystem contradicts the naming contract.
-
-**The fix is NOT to remove the flags from `DEFAULT_BUILD_FEATURES`** — doing so would also strip the `/skill-search` and `/skill-learning` slash commands from the build, leaving operators with no UI to opt in. Instead the activation logic in `featureCheck.ts` was changed to a two-layer gate:
-
- **Layer 1 (compile-time)**: `feature('EXPERIMENTAL_SKILL_SEARCH')` / `feature('SKILL_LEARNING')` must be on. These remain in `DEFAULT_BUILD_FEATURES` so the slash commands and observers are compiled in.
- **Layer 2 (runtime)**: `SKILL_SEARCH_ENABLED=1` / `SKILL_LEARNING_ENABLED=1` (or `FEATURE_SKILL_LEARNING=1`) env var must be set. Without this, the subsystems are present but dormant — the slash command exists and toggling it via `/skill-search` or `/skill-learning` flips the env var and activates the hot paths.
-
-Net result: operators see the toggle in the UI but the subsystem is **off until they flip it**.
-
-## 6. Out of scope (filed for follow-up)
-
- **Test failures on CI** (`prefetch.test.ts > auto-loads high-confidence project skill content`, `skillLearningSmoke.test.ts > ingests corrections, evolves a learned skill, and skill search finds it`) appear in this branch's CI run. Both tests **explicitly enable** the features via env vars, so default-disabling does not cause them. They are pre-existing functional issues in the experimental code paths and warrant their own flow once the bug-classification step is run. Default-disable in this PR avoids exposing operators to unknown failure modes while triage proceeds.
- **Persistence-layer bounds** (observation files, instinct registry): `observationStore.ts` already has 30-day purge and 1MB archive thresholds; `skillGapStore.ts` uses a finite-state lifecycle. Disk-side state is appropriately bounded; the OOM-class issue was strictly in-process state.
-
-## 7. Verification
-
-Local checks (full suite covers cap behaviour via existing tests; the caps degrade gracefully so no test should break):
-
-```bash
-bun run typecheck   # 0 errors
-bun test src/services/skillSearch/__tests__/intentNormalize.test.ts
-bun test src/services/skillSearch/__tests__/prefetch.extractQuery.test.ts
-bun test src/services/skillLearning/__tests__/projectContext.test.ts
-bun test src/services/skillLearning/__tests__/promotion.test.ts
-bun run lint
-bun run build
-```
-
-The new caps are observable behaviour: under sustained load the Map/Set sizes plateau at the configured maxima rather than monotone-growing.
--- a/docs/agent/worktree-isolation.mdx
+++ b/docs/agent/worktree-isolation.mdx
@@ -37,7 +37,7 @@ Worktree 文件统一存放在仓库根目录下的 `.claude/worktrees/`：

 ## 创建流程：EnterWorktreeTool

-`EnterWorktreeTool`（`packages/builtin-tools/src/tools/EnterWorktreeTool/EnterWorktreeTool.ts`）的执行链路：
+`EnterWorktreeTool`（`src/tools/EnterWorktreeTool/EnterWorktreeTool.ts`）的执行链路：

 ```
 EnterWorktreeTool.call({ name? })
@@ -83,7 +83,7 @@ EnterWorktreeTool.call({ name? })

 ## 退出流程：ExitWorktreeTool

-`ExitWorktreeTool`（`packages/builtin-tools/src/tools/ExitWorktreeTool/ExitWorktreeTool.ts`）支持两种退出策略：
+`ExitWorktreeTool`（`src/tools/ExitWorktreeTool/ExitWorktreeTool.ts`）支持两种退出策略：

 ### keep：保留 worktree

--- a/docs/auto-updater.md
+++ b/docs/auto-updater.md
@@ -42,7 +42,7 @@ useInterval(checkForUpdates, 30 * 60 * 1000); // 每 30 分钟

 任何更新尝试之前，系统会依次检查：

-1. **自动更新是否被禁用？** — `getAutoUpdaterDisabledReason()`（`src/utils/config.ts:1737`）
+1. **自动更新是否被禁用？** — `getAutoUpdaterDisabledReason()`（`src/utils/config.ts:1735`）
   - `NODE_ENV === 'development'`
   - 设置了 `DISABLE_AUTOUPDATER` 环境变量
   - 仅限必要流量模式
@@ -81,7 +81,7 @@ useInterval(checkForUpdates, 30 * 60 * 1000); // 每 30 分钟

 `src/utils/autoUpdater.ts:70` — `assertMinVersion()`

-定义于 `src/utils/autoUpdater.ts:70`，设计上在启动时调用（当前未接入启动流程）：
+从 `src/main.tsx:1775` 在启动时调用：

 ```typescript
 void assertMinVersion();
@@ -200,7 +200,7 @@ Windows 系统使用文件复制而非符号链接。

 **文件**: `src/migrations/migrateAutoUpdatesToSettings.ts`

-一次性将旧版 `globalConfig.autoUpdates = false` 迁移为 settings 中的 `DISABLE_AUTOUPDATER=1` 环境变量。定义于 `src/migrations/migrateAutoUpdatesToSettings.ts`（当前未接入启动流程）。
+一次性将旧版 `globalConfig.autoUpdates = false` 迁移为 settings 中的 `DISABLE_AUTOUPDATER=1` 环境变量。从 `src/main.tsx:325` 在启动时调用。

 ---

@@ -270,7 +270,7 @@ React hook `useUpdateNotification(updatedVersion)` — 确保每次 semver 变
 | `src/utils/releaseNotes.ts` | Changelog 获取、缓存与展示 |
 | `src/utils/semver.ts` | Semver 版本比较（Bun 原生 + npm 回退） |
 | `src/utils/doctorDiagnostic.ts` | 安装类型检测与健康诊断 |
-| `src/utils/config.ts:1737` | `getAutoUpdaterDisabledReason()` — 禁用检查逻辑 |
+| `src/utils/config.ts:1735` | `getAutoUpdaterDisabledReason()` — 禁用检查逻辑 |
 | `src/migrations/migrateAutoUpdatesToSettings.ts` | 旧版配置迁移 |
 | `src/screens/Doctor.tsx` | Doctor 命令 UI，展示自动更新状态 |

--- a/docs/context/compaction.mdx
+++ b/docs/context/compaction.mdx
@@ -48,7 +48,7 @@ const messagesForCompact = microcompactResult.messages
 MicroCompact 不压缩整个对话，而是**清除旧工具输出的内容**。它维护一个白名单：

 ```typescript
-// src/services/compact/microCompact.ts:41-50
+// src/services/compact/microCompact.ts:41-48
 const COMPACTABLE_TOOLS = new Set([
  FILE_READ_TOOL_NAME,    // 'Read' - 文件读取
  ...SHELL_TOOL_NAMES,    // 'Bash' - 命令输出
@@ -143,7 +143,7 @@ const stripped2 = stripReinjectedAttachments(stripped) // 移除会被重新注
 压缩后，系统会从摘要中**重新注入关键上下文**：

 ```typescript
-// compact.ts:126-134
+// 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
--- a/docs/context/project-memory.mdx
+++ b/docs/context/project-memory.mdx
@@ -39,7 +39,7 @@ Claude Code 的记忆系统是**纯文件**的——没有数据库、没有向
 `MEMORY.md` 是记忆的入口索引，每次对话都完整加载到上下文中：

 ```typescript
-// memdir.ts:34-38
+// memdir.ts:35-38
 export const ENTRYPOINT_NAME = 'MEMORY.md'
 export const MAX_ENTRYPOINT_LINES = 200
 export const MAX_ENTRYPOINT_BYTES = 25_000
--- a/docs/context/system-prompt.mdx
+++ b/docs/context/system-prompt.mdx
@@ -20,12 +20,12 @@ 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:3279`）—— 调用 `splitSysPromptPrefix()` 分块，为每个块附加 `cache_control`
+3. **`buildSystemPromptBlocks()`**（`src/services/api/claude.ts:3214`）—— 调用 `splitSysPromptPrefix()` 分块，为每个块附加 `cache_control`

 ## SystemPrompt 品牌类型

 ```typescript
-// packages/@ant/model-provider/src/types/systemPrompt.ts:4
+// src/utils/systemPromptType.ts:8
 export type SystemPrompt = readonly string[] & {
  readonly __brand: 'SystemPrompt'
 }
@@ -185,7 +185,7 @@ export function shouldUseGlobalCacheScope(): boolean {

 ### `getCacheControl()`：TTL 决策

-`src/services/api/claude.ts:348` 生成的 `cache_control` 对象：
+`src/services/api/claude.ts:359` 生成的 `cache_control` 对象：

 ```typescript
 {
@@ -195,14 +195,14 @@ export function shouldUseGlobalCacheScope(): boolean {
 }
 ```

-1 小时 TTL 的判定逻辑（`should1hCacheTTL()`，第 383 行）：
+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:354`）的内容必须放在 `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` **之后**。因为它包含：
+`getSessionSpecificGuidanceSection()`（`src/constants/prompts.ts:352`）的内容必须放在 `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` **之后**。因为它包含：
 - 当前会话的 enabledTools 集合
 - `isForkSubagentEnabled()` 的运行时判定
 - `getIsNonInteractiveSession()` 的结果
--- a/docs/conversation/streaming.mdx
+++ b/docs/conversation/streaming.mdx
@@ -32,7 +32,7 @@ message_stop            ← 消息结束

 ### 事件处理状态机

-`src/services/api/claude.ts` 中 `queryModelWithStreaming()` 函数的事件处理循环实现了一个基于 `switch(part.type)` 的状态机：
+`src/services/api/claude.ts` 中 `queryStreamRaw()` 函数的事件处理循环实现了一个基于 `switch(part.type)` 的状态机：

 | 事件类型 | 处理逻辑 | 状态变更 |
 |----------|----------|----------|
@@ -167,13 +167,10 @@ UI 层通过 `useToolCallProgress` hook 实时展示命令输出，而不是等

 | Provider | 流式协议 | 特殊处理 |
 |----------|----------|----------|
-| **firstParty** (Anthropic Direct) | 原生 SSE | 延迟最低，TTFT 最快 |
+| **Anthropic Direct** | 原生 SSE | 延迟最低，TTFT 最快 |
 | **AWS Bedrock** | AWS SDK 流式接口 | 需要额外的 beta header 和认证 |
 | **Google Vertex** | gRPC → 事件流 | 通过 `getMergedBetas()` 适配 |
-| **foundry** | Anthropic 兼容 API | 内部部署 |
-| **openai** | OpenAI 流式适配器 | 转换为 Anthropic 内部格式 |
-| **gemini** | Gemini 流式适配器 | 转换为 Anthropic 内部格式 |
-| **grok** (xAI) | Grok 流式适配器 | 转换为 Anthropic 内部格式 |
+| **Azure** | Anthropic 兼容 API | 自定义 base URL |

 所有 Provider 通过统一的 `Stream<BetaRawMessageStreamEvent>` 抽象层屏蔽差异。上层代码（QueryEngine、REPL）不需要关心底层用的是哪个 Provider。

--- a/docs/conversation/the-loop.mdx
+++ b/docs/conversation/the-loop.mdx
@@ -74,17 +74,17 @@ const toolUpdates = streamingToolExecutor

 | 终止原因 | 触发位置 | 机制 |
 |----------|---------|------|
-| **blocking_limit** | 第 686 行 | Token 计数超过硬限制（非 autocompact 模式）→ 生成 PTL 错误消息 → 返回 |
-| **image_error** | 第 1021 行 | `ImageSizeError` / `ImageResizeError` 异常 → 直接返回 |
-| **model_error** | 第 1040 行 | `callModel()` 抛出不可恢复异常 → 生成错误消息 → 返回 |
-| **aborted_streaming** | 第 1095 行 | `abortController.signal.aborted`（流式阶段）→ 为未完成的 tool_use 生成合成 tool_result → 返回 |
-| **prompt_too_long** | 第 1219/1226 行 | 413 错误且 reactive compact 无法恢复 → 暂扣的错误消息被释放 → 返回 |
-| **completed** | 第 1308 行 | API 错误（限流、认证失败等）导致无法继续 → 返回 |
-| **stop_hook_prevented** | 第 1323 行 | Stop hook 返回 `preventContinuation: true` → 返回 |
-| **completed** | 第 1401 行 | 正常完成：AI 未发出 tool_use → `needsFollowUp = false` → 经过 stop hooks → 返回 |
-| **aborted_tools** | 第 1559 行 | `abortController.signal.aborted`（工具执行阶段）→ 返回 |
-| **hook_stopped** | 第 1564 行 | 工具执行期间 hook 返回 `shouldPreventContinuation` → 返回 |
-| **max_turns** | 第 1755 行 | 轮次计数超过 `maxTurns` 限制 → 返回 |
+| **blocking_limit** | 第 646 行 | Token 计数超过硬限制（非 autocompact 模式）→ 生成 PTL 错误消息 → 返回 |
+| **image_error** | 第 980 行 | `ImageSizeError` / `ImageResizeError` 异常 → 直接返回 |
+| **model_error** | 第 999 行 | `callModel()` 抛出不可恢复异常 → 生成错误消息 → 返回 |
+| **aborted_streaming** | 第 1054 行 | `abortController.signal.aborted`（流式阶段）→ 为未完成的 tool_use 生成合成 tool_result → 返回 |
+| **prompt_too_long** | 第 1178/1185 行 | 413 错误且 reactive compact 无法恢复 → 暂扣的错误消息被释放 → 返回 |
+| **completed** | 第 1267 行 | API 错误（限流、认证失败等）导致无法继续 → 返回 |
+| **stop_hook_prevented** | 第 1282 行 | Stop hook 返回 `preventContinuation: true` → 返回 |
+| **completed** | 第 1360 行 | 正常完成：AI 未发出 tool_use → `needsFollowUp = false` → 经过 stop hooks → 返回 |
+| **aborted_tools** | 第 1518 行 | `abortController.signal.aborted`（工具执行阶段）→ 返回 |
+| **hook_stopped** | 第 1523 行 | 工具执行期间 hook 返回 `shouldPreventContinuation` → 返回 |
+| **max_turns** | 第 1714 行 | 轮次计数超过 `maxTurns` 限制 → 返回 |

 ## 继续条件（恢复路径）

@@ -158,7 +158,7 @@ type State = {
 - **每一步都产生真实信息**：`runTools()` 返回的 `toolResults` 是 API 不可能预知的——命令输出、文件内容、错误信息
 - **动态上下文管理**：每轮迭代前都重新评估压缩需求（autocompact → microcompact → snip），基于最新的 token 计数
 - **错误即时恢复**：工具失败不需要推倒重来——stop hook 可以注入阻塞错误让 AI 修正策略
- **用户可控**：`abortController.signal` 在循环的多个检查点被检测（第 1059、1095、1529 行），用户按 ESC 可以优雅中断
+- **用户可控**：`abortController.signal` 在循环的多个检查点被检测（第 1018、1048、1488 行），用户按 ESC 可以优雅中断
 - **成本控制**：Token Budget 在每轮终止前检查，防止 AI 无效循环

 ## 一个完整的迭代示例
--- a/docs/design/tool-search-design-guide.md
+++ b/docs/design/tool-search-design-guide.md
@@ -1,323 +0,0 @@
-# ToolSearch 设计指南
-
-> 基于 feature/tool_search 分支的 4 次 commit 迭代，系统性地记录 ToolSearch 的架构、核心机制、演进历史和维护指南。
-
-## 1. 问题背景
-
-Claude Code 内置了 60+ 工具，加上用户连接的 MCP 服务器可能引入数十甚至上百个额外工具。将所有工具的完整 schema 一次性发送给模型，会产生几个严重问题：
-
-1. **Token 爆炸** — 每个工具定义（name + description + inputSchema）平均消耗数百 token，60 个工具就是数万 token 的常量开销。
-2. **Prompt Cache 失效** — 工具列表作为 prompt 的一部分参与缓存计算。任何工具的增减（如 MCP 服务器连接/断开）都会导致整段缓存失效。
-3. **模型注意力稀释** — 过多的工具定义干扰模型对核心工具的选择准确性。
-
-## 2. 解决方案概览
-
-ToolSearch 采用 **延迟加载（Deferred Loading）** 模式：
-
- 将工具分为 **Core Tools**（始终加载）和 **Deferred Tools**（按需发现）
- 模型通过 `SearchExtraTools` 工具搜索并发现 deferred tools
- 通过 `ExecuteExtraTool` 工具代理执行发现的 deferred tools
- **工具数组在会话中保持稳定**，不再动态注入已发现的 deferred tools（v3 修复的关键决策）
-
-## 3. 核心架构
-
-### 3.1 工具分类体系
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                     All Tools (60+ built-in + MCP)          │
-├───────────────────────────┬─────────────────────────────────┤
-│    Core Tools (29 个)     │     Deferred Tools (其余全部)    │
-│    始终加载，直接调用      │     不加载 schema，按需发现      │
-│    CORE_TOOLS 白名单定义   │     isDeferredTool() 判定       │
-└───────────────────────────┴─────────────────────────────────┘
-```
-
-**Core Tools**（`src/constants/tools.ts` 中的 `CORE_TOOLS` Set）：
-
-| 类别 | 工具 |
-|------|------|
-| 文件操作 | Bash/Shell, Read, Edit, Write, Glob, Grep, NotebookEdit |
-| Agent 交互 | Agent, AskUserQuestion |
-| 任务管理 | TaskOutput, TaskStop, TaskCreate, TaskGet, TaskList, TaskUpdate, TodoWrite |
-| 规划 | EnterPlanMode, ExitPlanMode, VerifyPlanExecution |
-| Web | WebFetch, WebSearch |
-| 代码智能 | LSP |
-| 技能 | Skill |
-| 调度/监控 | Sleep |
-| 工具发现 | SearchExtraTools, ExecuteExtraTool, SyntheticOutput |
-
-**isDeferredTool 判定逻辑**（`packages/builtin-tools/src/tools/SearchExtraToolsTool/prompt.ts`）：
-
-```
-isDeferredTool(tool) =
-  tool.alwaysLoad === true?  → false（显式跳过延迟）
-  CORE_TOOLS.has(tool.name)? → false（核心工具不延迟）
-  otherwise                  → true（其余全部延迟）
-```
-
-### 3.2 三层组件架构
-
-```
-┌──────────────────────────────────────────────────────┐
-│  API Layer (src/services/api/claude.ts)              │
-│  ├─ 判定是否启用 ToolSearch                          │
-│  ├─ 过滤 deferred tools 不进入 API tools 数组         │
-│  ├─ 注入 <available-deferred-tools> 或 delta 附件    │
-│  └─ 处理 tool_reference/text 格式的消息归一化         │
-├──────────────────────────────────────────────────────┤
-│  Query Loop (src/query.ts)                           │
-│  ├─ Turn-zero 预取：用户输入时触发                    │
-│  └─ Inter-turn 预取：assistant turn 后异步触发        │
-├──────────────────────────────────────────────────────┤
-│  Search Engine                                       │
-│  ├─ SearchExtraToolsTool — 搜索入口（4 种查询模式）  │
-│  ├─ TF-IDF Index (toolIndex.ts) — 语义搜索          │
-│  ├─ Keyword Search — 精确匹配                       │
-│  └─ ExecuteExtraTool — 代理执行                      │
-└──────────────────────────────────────────────────────┘
-```
-
-### 3.3 搜索引擎设计
-
-SearchExtraToolsTool 支持四种查询模式：
-
-| 模式 | 语法 | 行为 | 返回 |
-|------|------|------|------|
-| **Select** | `select:CronCreate,Snip` | 按名称直接获取，逗号分隔多选 | 精确匹配列表 |
-| **Discover** | `discover:schedule cron job` | 纯发现模式，返回描述+schema | 工具信息文本 |
-| **Keyword** | `notebook jupyter` | 关键词搜索 | 按相关性排序 |
-| **Required** | `+slack send` | `+` 前缀强制包含 | 包含必选词的结果 |
-
-**混合搜索算法**：
-
-```
-最终分数 = 关键词分数 × 0.4 + TF-IDF 分数 × 0.6
-```
-
- **Keyword Search**：基于工具名解析（CamelCase 分词、MCP 前缀拆解）、searchHint 匹配、描述文本匹配，加权计分
- **TF-IDF Search**：复用 `skillSearch/localSearch.ts` 的算法，对 name (3.0)、searchHint (2.5)、description (1.0) 三个字段加权计算 TF-IDF 向量
-
-**MCP 工具名解析**：
-
-```
-mcp__slack__send_message → parts: ["slack", "send", "message"]
-CamelCase → parts: ["cron", "create"]
-```
-
-### 3.4 执行管道
-
-```
-模型调用 ExecuteExtraTool({tool_name: "CronCreate", params: {...}})
-  ↓
-ExecuteTool.call() 在全局工具注册表中查找 CronCreate
-  ↓
-检查目标工具 isEnabled() — 桥接/条件工具可能不可用
-  ↓
-委托目标工具的 checkPermissions() — 权限传递给实际工具
-  ↓
-调用目标工具的 call() — 与直接调用完全等价
-  ↓
-返回结果（包装为 ExecuteExtraTool 的 output schema）
-```
-
-关键设计：ExecuteExtraTool 的 `checkPermissions()` 返回 `passthrough`，将权限决策完全委托给目标工具。它本身不引入额外的权限层。
-
-### 3.5 Prompt Cache 稳定性策略（v3 关键修复）
-
-**问题**：早期版本在发现 deferred tool 后会将其注入 API tools 数组，导致每次发现新工具时 tools JSON 变化，prompt cache 全面失效。
-
-**修复**（commit `c14b7ead`）：deferred tools **始终不进入 API tools 数组**。tools 数组在整个会话中只包含 core tools + SearchExtraTools + ExecuteExtraTool，保持稳定。
-
-```
-API Tools 数组（会话期间不变）:
-  [Core Tools (29)] + [SearchExtraTools, ExecuteExtraTool, SyntheticOutput]
-  
-  不包含: 任何 deferred tool（即使已被发现）
-  执行方式: 通过 ExecuteExtraTool 代理调用
-```
-
-## 4. 预取机制（Prefetch）
-
-### 4.1 两个触发时机
-
-1. **Turn-zero**（`getTurnZeroSearchExtraToolsPrefetch`）— 用户输入第一轮时，基于输入文本搜索相关 deferred tools，以 attachment 形式注入
-2. **Inter-turn**（`startSearchExtraToolsPrefetch`）— assistant turn 结束后，基于对话上下文异步搜索
-
-### 4.2 Attachment 管道
-
-```
-prefetch → Attachment(type: 'tool_discovery')
-  → messages.ts 转换为 system-reminder
-  → "The following tools were discovered... Use ExecuteExtraTool to invoke..."
-```
-
-### 4.3 会话去重
-
-`discoveredToolsThisSession` Set 跟踪已发现的工具，避免重复推荐。该 Set 独立于 skill prefetch 的去重集合，互不影响。使用 `addBoundedSessionEntry()` 保持上限 500 条，超出时裁剪到 400 条。
-
-## 5. 模式切换系统
-
-通过环境变量 `ENABLE_SEARCH_EXTRA_TOOLS` 控制：
-
-| 环境变量值 | 模式 | 行为 |
-|-----------|------|------|
-| 未设置 | `tst` | 默认启用，始终延迟非核心工具 |
-| `true` | `tst` | 强制启用 |
-| `false` | `standard` | 完全禁用，所有工具内联加载 |
-| `auto` | `tst-auto` | 仅当 deferred tools 超过上下文窗口 10% 时启用 |
-| `auto:N` | `tst-auto` | 自定义阈值百分比（N=0 启用，N=100 禁用） |
-| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` | `standard` | 全局 kill switch |
-
-`isSearchExtraToolsEnabledOptimistic()` — 快速判断（不检查阈值），用于工具注册
-`isSearchExtraToolsEnabled()` — 完整判断（含阈值检查），用于 API 调用
-
-## 6. Deferred Tools Delta 机制
-
-对于 Anthropic 内部用户（`USER_TYPE=ant`）或启用了 `tengu_glacier_2xr` feature flag 的用户，使用 **delta attachment** 替代 `<available-deferred-tools>` 头部注入：
-
- 首次：注入完整的 deferred tools 列表
- 后续：只注入增量变化（新增/移除）
- 优势：不会因为工具池变化导致整个头部缓存失效
-
-Delta attachment 扫描历史消息中的 `deferred_tools_delta` 类型 attachment，重建已宣告集合，然后差分计算当前 deferred pool 的变化。
-
-## 7. 演进历史
-
-### v1: 基础设施层（`7be08f53`）
-
-**34 个文件，+4040/-90 行**
-
- 定义 `CORE_TOOLS` 白名单（31 个核心工具）
- 实现 TF-IDF 工具索引模块 `toolIndex.ts`
- 创建 `ExecuteTool` 作为统一执行入口
- 增强 ToolSearchTool：TF-IDF 搜索路径、discover 模式、并行搜索合并
- 新增 27 个单元测试
- 实现预取管道和 UI 组件
-
-**关键文件**：
- `src/services/toolSearch/toolIndex.ts` → 后续重命名为 `searchExtraTools/toolIndex.ts`
- `packages/builtin-tools/src/tools/ExecuteTool/` — 执行入口
- `src/constants/tools.ts` — CORE_TOOLS 定义
-
-### v2: 统一自建搜索（`8c157f07`）
-
-**17 个文件，+274/-395 行**（净减少 121 行）
-
- **移除 `tool_reference` blocks** — 不再依赖 Anthropic API 的 `tool_reference` 功能
- **移除 `defer_loading` 字段** — 不再发送 API 级别的工具延迟加载标记
- **移除 `modelSupportsToolReference()`** — 不再区分模型是否支持 tool_reference
- **重命名 ExecuteTool → ExecuteExtraTool** — 更清晰地表达其作为代理执行器的角色
- **输出改为纯文本** — 所有 provider 通用，无需特殊 API 功能支持
- **简化 system prompt** — 工具使用指南从 ~120 行压缩到 ~10 行
-
-**设计决策**：这次重构的核心洞察是 — 依赖 Anthropic 私有 API 特性（tool_reference、defer_loading、beta header）使得系统只能用于 first-party provider。自建 TF-IDF + keyword 搜索完全能满足需求，且对所有 provider（OpenAI、Gemini、Grok）通用。
-
-### v3: Cache 稳定性修复（`c14b7ead`）
-
-**7 个文件，+46/-31 行**
-
- **移除 "discover then include" 逻辑** — 发现的 deferred tools 不再注入 tools 数组
- **tools 数组保持稳定** — 只有 core tools + SearchExtraTools + ExecuteExtraTool
- **强化优先级引导** — core tools 直接调用，ToolSearch 仅作为发现 deferred tools 的手段
- **已加载工具拒绝提示** — 搜索 core tool 时返回明确拒绝
-
-**设计决策**：prompt cache 是 Claude Code 性能优化的关键。每次 tools JSON 变化都会导致缓存失效，代价远大于通过 ExecuteExtraTool 代理调用 deferred tools 的额外 token。因此选择牺牲一点直接调用的便利性，换取 cache 稳定性。
-
-### v4: Agents/Teams 延迟化（`af0d7dc8`）
-
-**7 个文件，+36/-18 行**
-
- 将 `TeamCreate`、`TeamDelete`、`SendMessage` 从 CORE_TOOLS 移除
- 这些工具仅在 swarm 模式下常用，平时占用 context token
- swarm 模式下 SendMessage 保持 always loaded
- TeamCreate/TeamDelete 在 swarm 未启用时返回启用提示
-
-**设计决策**：不是所有用户都需要团队功能。将其延迟化后，大部分用户可以节省约 3 个工具定义的 token 开销。
-
-## 8. 文件索引
-
-### 核心文件
-
-| 文件 | 职责 |
-|------|------|
-| `src/constants/tools.ts` | CORE_TOOLS 白名单、工具权限集合 |
-| `src/utils/searchExtraTools.ts` | 模式判定、阈值计算、delta 差分、discovered tools 提取 |
-| `src/services/searchExtraTools/toolIndex.ts` | TF-IDF 索引构建和搜索 |
-| `src/services/searchExtraTools/prefetch.ts` | 预取管道（turn-zero + inter-turn） |
-| `packages/builtin-tools/src/tools/SearchExtraToolsTool/` | 搜索工具实现（4 种查询模式） |
-| `packages/builtin-tools/src/tools/ExecuteTool/` | 代理执行器实现 |
-| `src/services/api/claude.ts` | API 层集成（工具过滤、消息归一化） |
-| `src/query.ts` | 查询循环集成（预取触发点） |
-| `src/utils/messages.ts` | Attachment → system-reminder 转换 |
-
-### 共享基础设施
-
-| 文件 | 被复用的导出 |
-|------|-------------|
-| `src/services/skillSearch/localSearch.ts` | `tokenizeAndStem`, `computeWeightedTf`, `computeIdf`, `cosineSimilarity` |
-| `src/services/skillSearch/prefetch.ts` | `extractQueryFromMessages` |
-
-### 测试文件
-
-| 文件 | 覆盖范围 |
-|------|---------|
-| `src/services/searchExtraTools/__tests__/toolIndex.test.ts` | 索引构建、TF-IDF 搜索、CJK 处理 |
-| `src/services/searchExtraTools/__tests__/prefetch.test.ts` | 预取管道、去重、attachment 生成 |
-| `packages/builtin-tools/src/tools/SearchExtraToolsTool/__tests__/` | 搜索工具 4 种模式 |
-| `packages/builtin-tools/src/tools/ExecuteTool/__tests__/` | 代理执行 |
-
-## 9. 维护指南
-
-### 9.1 新增工具的延迟化决策
-
-将新工具加入 deferred 状态的标准：
- 工具仅在特定场景使用（如 swarm 模式、特定 MCP 集成）
- 工具的 schema 较大（占用较多 context token）
- 工具不是模型默认会尝试的核心操作
-
-将已延迟的工具提升为 core tool：
- 在 `src/constants/tools.ts` 的 `CORE_TOOLS` Set 中添加工具名常量
- 确保导入对应的 `*_TOOL_NAME` 常量
-
-### 9.2 修改注意事项
-
-1. **修改 `localSearch.ts` 的 TF-IDF 函数**：需同步检查 `toolIndex.test.ts` 和 `localSearch.test.ts`
-2. **修改 `skillSearch/prefetch.ts` 的 `extractQueryFromMessages`**：需同步检查工具预取行为（`searchExtraTools/prefetch.ts` 调用同一函数）
-3. **修改 CORE_TOOLS**：需更新 `src/constants/__tests__/tools.test.ts` 测试
-4. **修改 `isDeferredTool`**：需更新 `src/constants/__tests__/tools.test.ts` 和 `SearchExtraToolsTool.test.ts`
-
-### 9.3 性能优化配置
-
-```bash
-# 环境变量调优
-ENABLE_SEARCH_EXTRA_TOOLS=auto:15    # 当 deferred tools 超过上下文 15% 时启用
-SEARCH_EXTRA_TOOLS_WEIGHT_KEYWORD=0.5  # 关键词搜索权重
-SEARCH_EXTRA_TOOLS_WEIGHT_TFIDF=0.5    # TF-IDF 搜索权重
-SEARCH_EXTRA_TOOLS_DISPLAY_MIN_SCORE=0.10  # 最低显示分数阈值
-```
-
-### 9.4 搜索质量调优
-
- `TOOL_FIELD_WEIGHT`（`toolIndex.ts`）：控制 name/searchHint/description 对 TF-IDF 分数的贡献权重
- `KEYWORD_WEIGHT` / `TFIDF_WEIGHT`（`SearchExtraToolsTool.ts`）：控制混合搜索中两种算法的最终权重比例
- `searchHint` 属性：为工具添加精心编写的搜索提示，提高关键词匹配质量
-
-## 10. 与 Skill Search 的关系
-
-ToolSearch 和 SkillSearch 是平行的搜索系统，共享底层算法但服务于不同领域：
-
-| 维度 | ToolSearch | SkillSearch |
-|------|-----------|-------------|
-| 搜索对象 | Deferred 工具（内置 + MCP） | 用户技能（skill） |
-| 执行方式 | `ExecuteExtraTool` 代理调用 | 直接注入 attachment 内容 |
-| 字段权重 | name:3.0, searchHint:2.5, desc:1.0 | name:3.0, whenToUse:2.0, desc:1.0 |
-| 缓存策略 | 按工具名列表缓存 | 按 cwd 缓存 |
-| 去重集合 | `discoveredToolsThisSession` | 独立的 Set |
-
-共享的底层函数：
- `tokenizeAndStem` — 统一的 CJK/ASCII 分词和词干提取
- `computeWeightedTf` — 加权词频计算
- `computeIdf` — 逆文档频率计算
- `cosineSimilarity` — 向量余弦相似度
- `extractQueryFromMessages` — 从对话历史中提取搜索查询文本
--- a/docs/diagrams/agent-loop-simple.mmd
+++ b/docs/diagrams/agent-loop-simple.mmd
@@ -1,17 +0,0 @@
-flowchart TB
-    START((输入)) --> CTX["Context 管理"]
-    CTX --> LLM["LLM 流式输出"]
-    LLM --> TC{tool_use?}
-
-    TC --> |是| EXEC["执行工具"]
-    EXEC --> CTX
-
-    TC --> |否| DONE((完成))
-
-    classDef proc fill:#eef,stroke:#66c,color:#224
-    classDef decision fill:#fee,stroke:#c66,color:#422
-    classDef io fill:#eff,stroke:#6cc,color:#244
-
-    class CTX,LLM,EXEC proc
-    class TC decision
-    class START,DONE io
--- a/docs/diagrams/agent-loop.mmd
+++ b/docs/diagrams/agent-loop.mmd
@@ -1,40 +0,0 @@
-flowchart TB
-    START((输入)) --> CTX["Context 管理"]
-    CTX --> PRE["Pre-sampling Hook"]
-    PRE --> LLM["LLM 流式输出"]
-    LLM --> TC{tool_use?}
-
-    TC --> |是| PERM{需权限?}
-    PERM --> |是| USER["👤 用户审批"]
-    USER --> |allow| TOOL_PRE
-    USER --> |deny| DENIED["拒绝"]
-    PERM --> |否| TOOL_PRE["Pre-tool Hook"]
-    TOOL_PRE --> EXEC["并发执行工具"]
-    EXEC --> TOOL_POST["Post-tool Hook"]
-    TOOL_POST --> CTX
-    DENIED --> CTX
-
-    TC --> |否| POST["Post-sampling Hook"]
-    POST --> STOP{"Stop Hook"}
-    STOP --> |不通过| CTX
-    STOP --> |通过| BUDGET{"Token Budget"}
-    BUDGET --> |继续| CTX
-    BUDGET --> |完成| DONE((完成))
-
-    subgraph SUB["子 Agent"]
-        FORK["AgentTool"] --> RECURSE["递归调用"]
-    end
-
-    EXEC -.-> FORK
-
-    classDef proc fill:#eef,stroke:#66c,color:#224
-    classDef decision fill:#fee,stroke:#c66,color:#422
-    classDef hook fill:#ffe,stroke:#cc6,color:#442
-    classDef io fill:#eff,stroke:#6cc,color:#244
-    classDef sub fill:#efe,stroke:#6a6,color:#242
-
-    class CTX,LLM,EXEC proc
-    class TC,PERM,STOP,BUDGET decision
-    class PRE,TOOL_PRE,TOOL_POST,POST hook
-    class START,DONE,USER,DENIED io
-    class FORK,RECURSE sub
--- a/docs/extensibility/custom-agents.mdx
+++ b/docs/extensibility/custom-agents.mdx
@@ -12,7 +12,7 @@ Claude Code 的 Agent 不仅仅来自用户自定义——系统有三类来源

 | 来源 | 位置 | 优先级 |
 |------|------|--------|
-| **Built-in** | `packages/builtin-tools/src/tools/AgentTool/built-in/` 硬编码 | 最低（可被覆盖） |
+| **Built-in** | `src/tools/AgentTool/built-in/` 硬编码 | 最低（可被覆盖） |
 | **Plugin** | 通过插件系统注册 | 中 |
 | **User/Project/Policy** | `.claude/agents/*.md` 或 settings.json | 最高 |

@@ -127,7 +127,7 @@ color: "blue"                       # 终端中的 Agent 颜色标识
 以内置 Explore Agent 为例：

 ```typescript
-// packages/builtin-tools/src/tools/AgentTool/built-in/exploreAgent.ts
+// src/tools/AgentTool/built-in/exploreAgent.ts
 disallowedTools: [
  'Agent',           // 不能嵌套调用 Agent
  'ExitPlanMode',    // 不需要 plan mode
--- a/docs/extensibility/hooks.mdx
+++ b/docs/extensibility/hooks.mdx
@@ -240,7 +240,7 @@ SDK 非交互模式下信任是隐式的（`getIsNonInteractiveSession()` 为 tr

 ## Session Hook 的生命周期

-Agent 和 Skill 的前置 Hook 通过 `registerFrontmatterHooks()` 注册（调用位置：`packages/builtin-tools/src/tools/AgentTool/runAgent.ts`；定义位置：`src/utils/hooks/registerFrontmatterHooks.ts`），绑定到 agent 的 session ID。Agent 结束时通过 `clearSessionHooks()`（定义位置：`src/utils/hooks/sessionHooks.ts`）清理。
+Agent 和 Skill 的前置 Hook 通过 `registerFrontmatterHooks()` 注册（调用位置：`src/tools/AgentTool/runAgent.ts`；定义位置：`src/utils/hooks/registerFrontmatterHooks.ts`），绑定到 agent 的 session ID。Agent 结束时通过 `clearSessionHooks()`（定义位置：`src/utils/hooks/sessionHooks.ts`）清理。

 ```typescript
 // runAgent.ts — 注册 agent 的前置 Hook
--- a/docs/extensibility/mcp-protocol.mdx
+++ b/docs/extensibility/mcp-protocol.mdx
@@ -304,7 +304,7 @@ timer.unref?.()  // 不阻止进程退出

 ## 工具发现：从 MCP 到 Tool 接口

-`fetchToolsForClient()`（`client.ts:1744-2000`）使用 `memoizeWithLRU` 缓存（上限 100），将 MCP 工具转换为 Claude Code 的统一 Tool 接口：
+`fetchToolsForClient()`（`client.ts:1745-2000`）使用 `memoizeWithLRU` 缓存（上限 20），将 MCP 工具转换为 Claude Code 的统一 Tool 接口：

 ```typescript
 const fullyQualifiedName = buildMcpToolName(client.name, tool.name)
--- a/docs/extensibility/skills.mdx
+++ b/docs/extensibility/skills.mdx
@@ -22,7 +22,7 @@ Skill 的核心洞见：**复杂任务的关键不在代码逻辑，而在 Promp

 ### 1. 内置命令（Built-in Commands）

-硬编码在 `src/commands.ts:299` 的 `COMMANDS` memoize 数组中，包含 70+ 条命令（`/commit`、`/review`、`/compact` 等）。这些是 TypeScript 模块而非 Markdown，但实现了相同的 `Command` 接口（`src/types/command.ts`）。
+硬编码在 `src/commands.ts:258` 的 `COMMANDS` memoize 数组中，包含 70+ 条命令（`/commit`、`/review`、`/compact` 等）。这些是 TypeScript 模块而非 Markdown，但实现了相同的 `Command` 接口（`src/types/command.ts`）。

 ### 2. Bundled Skills（编译时打包）

@@ -98,7 +98,7 @@ shell: ["bash"]                      # Shell 执行环境

 ## 两条执行路径：Inline vs Fork

-SkillTool（`packages/builtin-tools/src/tools/SkillTool/SkillTool.ts:332`）在 `call()` 中根据 `command.context` 分流：
+SkillTool（`src/tools/SkillTool/SkillTool.ts:332`）在 `call()` 中根据 `command.context` 分流：

 ### Inline 模式（默认）

--- a/docs/external-dependencies.md
+++ b/docs/external-dependencies.md
@@ -50,7 +50,7 @@

 - **端点**: `{region}-aiplatform.googleapis.com`
 - **认证**: `GoogleAuth` + `cloud-platform` scope
- **文件**: `src/services/api/client.ts:221-298`
+- **文件**: `src/services/api/client.ts:228-298`

 ### 4. Azure Foundry

@@ -129,12 +129,12 @@ WebSearch 工具支持直接抓取 Bing 搜索结果页面，也支持通过 Bra
 - **Bing 端点**: `https://www.bing.com/search?q={query}&setmkt=en-US`
 - **Brave 端点**: `https://api.search.brave.com/res/v1/llm/context?q={query}`
 - **文件**:
-  - `packages/builtin-tools/src/tools/WebSearchTool/adapters/bingAdapter.ts`
-  - `packages/builtin-tools/src/tools/WebSearchTool/adapters/braveAdapter.ts`
+  - `src/tools/WebSearchTool/adapters/bingAdapter.ts`
+  - `src/tools/WebSearchTool/adapters/braveAdapter.ts`

 另外还有 Domain Blocklist 查询:
 - **端点**: `https://api.anthropic.com/api/web/domain_info?domain={domain}`
- **文件**: `packages/builtin-tools/src/tools/WebFetchTool/utils.ts`
+- **文件**: `src/tools/WebFetchTool/utils.ts`

 ### 15. Google Cloud Storage (自动更新)

--- a/docs/features/acp-link.md
+++ b/docs/features/acp-link.md
@@ -1,207 +0,0 @@
-# acp-link — ACP 代理服务器
-
-> 源码目录：`packages/acp-link/`
-> PR: #292
-> 新增时间：2026-04-18
-
-## 一、功能概述
-
-`acp-link` 是一个 ACP (Agent Client Protocol) 代理服务器，将 WebSocket 客户端桥接到 ACP agent 的 stdio 接口。它让 ACP agent（如 Claude Code）可以通过 WebSocket 远程访问，而不仅限于本地 stdio。
-
-### 核心特性
-
- **WebSocket → stdio 桥接**：将浏览器/远程客户端的 WebSocket 连接转换为 ACP agent 的 stdin/stdout NDJSON 流
- **会话管理**：创建、加载、恢复、列出、关闭会话
- **权限审批流程**：客户端可远程审批 agent 的工具权限请求
- **RCS 集成**：可与 Remote Control Server (RCS) 连接，将 ACP agent 注册到 RCS 并通过 Web UI 交互
- **HTTPS 支持**：内置自签名证书生成，支持安全连接
- **Token 认证**：自动生成或通过环境变量配置认证 token
-
-## 二、架构
-
-### 独立模式
-
-```
-┌──────────────────┐    WebSocket     ┌──────────────────┐    stdio/NDJSON    ┌──────────────┐
-│  浏览器/客户端     │ ◄──────────────►│  acp-link        │ ◄────────────────►│  ACP Agent   │
-│  (WS Client)     │  ws://host:port  │  (Proxy Server)  │  spawn subprocess │  (Claude等)   │
-└──────────────────┘                  └──────────────────┘                    └──────────────┘
-```
-
-### RCS 集成模式
-
-```
-┌──────────────┐    WebSocket     ┌──────────────────┐    stdio/NDJSON    ┌──────────────┐
-│  RCS Web UI  │ ◄──────────────►│  Remote Control  │ ◄─────────────────►│  acp-link    │
-│  (/code/*)   │  ACP Relay WS   │  Server (RCS)    │  ACP events        │  + Agent     │
-└──────────────┘                  └──────────────────┘                    └──────────────┘
-```
-
-### 文件结构
-
-```
-packages/acp-link/
-├── src/
-│   ├── server.ts        # 主服务器：WS 连接管理、会话管理、权限处理、消息桥接
-│   ├── rcs-upstream.ts  # RCS 上游客户端：REST 注册 + WS identify 两步流程
-│   ├── cert.ts          # TLS 证书生成（自签名）
-│   ├── logger.ts        # 日志模块
-│   ├── types.ts         # JSON-RPC 和 ACP 协议类型定义
-│   ├── cli/
-│   │   ├── bin.ts       # CLI 入口
-│   │   ├── command.ts   # 命令行参数解析
-│   │   ├── app.ts       # 应用启动
-│   │   └── context.ts   # 上下文配置
-│   └── __tests__/       # 测试（cert, server, types）
-├── package.json
-└── tsconfig.json
-```
-
-## 三、安装与使用
-
-### 基本用法
-
-```bash
-# 直接运行（在 monorepo 中）
-# 注意：claude 本身不支持 ACP，需要用 ccb-bun --acp 启动 ACP agent
-bun packages/acp-link/src/cli/bin.ts ccb-bun -- --acp
-
-# 指定端口和主机
-acp-link --port 9000 --host 0.0.0.0 ccb-bun -- --acp
-
-# 启用 HTTPS（自签名证书）
-acp-link --https ccb-bun -- --acp
-
-# 调试模式
-acp-link --debug ccb-bun -- --acp
-```
-
-### CLI 参考
-
-```
-USAGE
-  acp-link [--port value] [--host value] [--debug] [--no-auth] [--https] <command>...
-  acp-link --help
-  acp-link --version
-
-FLAGS
-       [--port]     Port to listen on                  [default = 9315]
-       [--host]     Host to bind to                    [default = localhost]
-       [--debug]    Enable debug logging to file
-       [--no-auth]  Disable authentication (dangerous)
-       [--https]    Enable HTTPS with self-signed cert
-    -h  --help      Print help information and exit
-    -v  --version   Print version information and exit
-
-ARGUMENTS
-  command...  Agent command followed by its arguments (e.g. "ccb-bun -- --acp")
-```
-
-## 四、认证
-
-默认启动时自动生成随机 token。客户端连接时不要把 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
-```
-
-## 七、权限管道（2026-04-18 改进）
-
-### 模式同步
-
-`applySessionMode` 在 agent 切换权限模式时同步 `appState.toolPermissionContext.mode`，确保内部权限上下文与 ACP 客户端状态一致。
-
-### 统一权限流水线
-
-`createAcpCanUseTool` 接入 `hasPermissionsToUseTool` 统一权限流水线，替代原来分散的处理逻辑。支持 `onModeChange` 回调，模式变更时实时同步。
-
-### bypass 检测
-
-`bypassPermissions` 模式增加可用性检测 — 仅在非 root 或 sandbox 环境中允许启用，防止权限绕过的安全风险。
-
-## 八、环境变量
-
-| 变量 | 说明 |
-|------|------|
-| `ACP_AUTH_TOKEN` | 固定认证 token（默认自动生成） |
-| `ACP_PERMISSION_MODE` | 默认权限模式 fallback |
-| `ACP_RCS_URL` | RCS 服务器地址（启用 RCS 集成） |
-| `ACP_RCS_TOKEN` | RCS API token |
--- a/docs/features/acp-zed.md
+++ b/docs/features/acp-zed.md
@@ -1,189 +0,0 @@
-# ACP (Agent Client Protocol) — Zed / IDE 集成
-
-> Feature Flag: `FEATURE_ACP=1`（build 和 dev 模式默认启用）
-> 实现状态：可用（支持 Zed、Cursor 等 ACP 客户端）
-> 源码目录：`src/services/acp/`
-
-## 一、功能概述
-
-ACP (Agent Client Protocol) 是一种标准化的 stdio 协议，允许 IDE 和编辑器通过 stdin/stdout 的 NDJSON 流驱动 AI Agent。CCB 实现了完整的 ACP agent 端，可以被 Zed、Cursor 等支持 ACP 的客户端直接调用。
-
-### 核心特性
-
- **会话管理**：新建 / 恢复 / 加载 / 分叉 / 关闭会话
- **历史回放**：恢复会话时自动加载并回放对话历史
- **权限桥接**：ACP 客户端的权限决策映射到 CCB 的工具权限系统
- **斜杠命令 & Skills**：加载真实命令列表，支持 `/commit`、`/review` 等 prompt 型 skill
- **Context Window 跟踪**：精确的 usage_update，含 model prefix matching
- **Prompt 排队**：支持连续发送多条 prompt，自动排队处理
- **模式切换**：auto / default / acceptEdits / plan / dontAsk / bypassPermissions
- **模型切换**：运行时切换 AI 模型
-
-## 二、架构
-
-```
-┌──────────────┐    NDJSON/stdio    ┌──────────────────┐
-│  Zed / IDE   │ ◄────────────────► │  CCB ACP Agent   │
-│  (Client)    │   stdin / stdout   │  (Agent)         │
-└──────────────┘                    │                  │
-                                    │  entry.ts        │ ← stdio → NDJSON stream
-                                    │  agent.ts        │ ← ACP protocol handler
-                                    │  bridge.ts       │ ← SDKMessage → ACP SessionUpdate
-                                    │  permissions.ts  │ ← 权限桥接
-                                    │  utils.ts        │ ← 通用工具
-                                    │                  │
-                                    │  QueryEngine     │ ← 内部查询引擎
-                                    └──────────────────┘
-```
-
-### 文件职责
-
-| 文件 | 职责 |
-|------|------|
-| `entry.ts` | 入口，创建 stdio → NDJSON stream，启动 `AgentSideConnection` |
-| `agent.ts` | 实现 ACP `Agent` 接口：会话 CRUD、prompt、cancel、模式/模型切换 |
-| `bridge.ts` | `SDKMessage` → ACP `SessionUpdate` 转换：文本/思考/工具/用量/编辑 diff |
-| `permissions.ts` | ACP `requestPermission()` → CCB `CanUseToolFn` 桥接 |
-| `utils.ts` | Pushable、流转换、权限模式解析、session fingerprint、路径显示 |
-
-## 三、配置 Zed 编辑器
-
-### 3.1 Zed settings.json 配置
-
-打开 Zed 的 `settings.json`（`Cmd+,` → Open Settings），添加 `agent_servers` 配置：
-
-```json
-{
-  "agent_servers": {
-    "ccb": {
-      "type": "custom",
-      "command": "ccb",
-      "args": ["--acp"]
-    }
-  }
-}
-```
-
-### 3.3 API 认证配置
-
-CCB 的 ACP agent 在启动时会自动加载 `settings.json` 中的环境变量（`ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN` 等）。确保已通过 `/login` 配置好 API 供应商。
-
-也可通过环境变量传入：
-
-```json
-{
-  "agent_servers": {
-    "claude-code": {
-      "command": "ccb",
-      "args": ["--acp"],
-      "env": {
-        "ANTHROPIC_BASE_URL": "https://api.example.com/v1",
-        "ANTHROPIC_AUTH_TOKEN": "sk-xxx"
-      }
-    }
-  }
-}
-```
-
-### 3.4 在 Zed 中使用
-
-1. 配置完成后重启 Zed
-2. 打开任意项目目录
-3. 按 `Cmd+'`（macOS）或 `Ctrl+'`（Linux）打开 Agent Panel
-4. 在 Agent Panel 顶部的下拉菜单中选择 **claude-code**
-5. 开始对话
-
-### 3.5 功能说明
-
-| 功能 | 操作 |
-|------|------|
-| 对话 | 在 Agent Panel 中直接输入消息 |
-| 斜杠命令 | 输入 `/` 查看可用 skills 列表（如 `/commit`、`/review`） |
-| 工具权限 | 弹出权限请求时选择 Allow / Reject / Always Allow |
-| 模式切换 | 通过 Agent Panel 的设置菜单切换 auto/default/plan 等模式 |
-| 模型切换 | 通过 Agent Panel 的设置菜单切换 AI 模型 |
-| 会话恢复 | 关闭重开 Zed 后，之前的会话可自动恢复（含历史消息） |
-
-## 四、配置其他 ACP 客户端
-
-ACP 是开放协议，任何支持 ACP 的客户端都可以连接 CCB。通用配置模式：
-
-```
-命令: ccb --acp
-参数: ["--acp"]
-通信: stdin/stdout NDJSON
-协议版本: ACP v1
-```
-
-### 4.1 Cursor
-
-在 Cursor 的设置中配置 MCP / Agent Server，使用同样的 `ccb --acp` 命令。
-
-### 4.2 自定义客户端
-
-使用 `@agentclientprotocol/sdk` 可以快速构建 ACP 客户端：
-
-```typescript
-import { ClientSideConnection, ndJsonStream } from '@agentclientprotocol/sdk'
-
-// 创建连接（将 ccb --acp 作为子进程启动）
-const child = spawn('ccb', ['--acp'])
-const stream = ndJsonStream(
-  Writable.toWeb(child.stdin),
-  Readable.toWeb(child.stdout),
-)
-
-const client = new ClientSideConnection(stream)
-
-// 初始化
-await client.initialize({ clientCapabilities: {} })
-
-// 创建会话
-const { sessionId } = await client.newSession({
-  cwd: '/path/to/project',
-})
-
-// 发送 prompt
-const response = await client.prompt({
-  sessionId,
-  prompt: [{ type: 'text', text: 'Hello, explain this project' }],
-})
-
-// 监听 session 更新
-client.on('sessionUpdate', (update) => {
-  console.log('Update:', update)
-})
-```
-
-## 五、ACP 协议支持矩阵
-
-| 方法 | 状态 | 说明 |
-|------|------|------|
-| `initialize` | ✅ | 返回 agent 信息和能力 |
-| `authenticate` | ✅ | 无需认证（自托管） |
-| `newSession` | ✅ | 创建新会话 |
-| `resumeSession` | ✅ | 恢复已有会话（含历史回放） |
-| `loadSession` | ✅ | 加载指定会话（含历史回放） |
-| `listSessions` | ✅ | 列出可用会话 |
-| `forkSession` | ✅ | 分叉会话 |
-| `closeSession` | ✅ | 关闭会话 |
-| `prompt` | ✅ | 发送消息，支持排队 |
-| `cancel` | ✅ | 取消当前/排队的 prompt |
-| `setSessionMode` | ✅ | 切换权限模式 |
-| `setSessionModel` | ✅ | 切换 AI 模型 |
-| `setSessionConfigOption` | ✅ | 动态修改配置 |
-
-### SessionUpdate 类型
-
-| 类型 | 状态 | 说明 |
-|------|------|------|
-| `agent_message_chunk` | ✅ | 助手文本消息 |
-| `agent_thought_chunk` | ✅ | 思考/推理内容 |
-| `user_message_chunk` | ✅ | 用户消息（历史回放） |
-| `tool_call` | ✅ | 工具调用开始 |
-| `tool_call_update` | ✅ | 工具调用结果/状态更新 |
-| `usage_update` | ✅ | token 用量 + context window |
-| `plan` | ✅ | TodoWrite → plan entries |
-| `available_commands_update` | ✅ | 斜杠命令 & skills 列表 |
-| `current_mode_update` | ✅ | 模式切换通知 |
-| `config_option_update` | ✅ | 配置更新通知 |
--- a/docs/features/all-features-guide.md
+++ b/docs/features/all-features-guide.md
@@ -8,7 +8,7 @@

 1. [Buddy 伴侣系统](#1-buddy-伴侣系统)
 2. [Remote Control 远程控制](#2-remote-control-远程控制)
-3. [定时任务 /triggers](#3-定时任务-triggers)
+3. [定时任务 /schedule](#3-定时任务-schedule)
 4. [Voice Mode 语音模式](#4-voice-mode-语音模式)
 5. [Chrome 浏览器控制](#5-chrome-浏览器控制)
 6. [Computer Use 屏幕操控](#6-computer-use-屏幕操控)
@@ -72,21 +72,19 @@ CLAUDE_BRIDGE_BASE_URL=https://your-server.com CLAUDE_BRIDGE_OAUTH_TOKEN=your-to

 ---

-## 3. 定时任务 /triggers
+## 3. 定时任务 /schedule

 **PR**: #88 `feat: enable /schedule by adding AGENT_TRIGGERS_REMOTE`
 **Feature Flag**: `AGENT_TRIGGERS_REMOTE`

-> 命令名已从 `/schedule` 改为 `/triggers`，避免与上游 bundled skill `schedule` 冲突。`/cron` 是别名。
-
 ### 说明
 创建定时执行的远程 agent 任务，支持 cron 表达式。

 ### 使用
 ```
-/triggers create "每天检查依赖更新" --cron "0 9 * * *" --prompt "检查 package.json 中的过期依赖并创建更新 PR"
-/triggers list          — 列出所有定时任务
-/triggers delete <id>   — 删除指定任务
+/schedule create "每天检查依赖更新" --cron "0 9 * * *" --prompt "检查 package.json 中的过期依赖并创建更新 PR"
+/schedule list          — 列出所有定时任务
+/schedule delete <id>   — 删除指定任务
 ```

 ---
@@ -518,37 +516,25 @@ AI 也可通过 `SnipTool` 自动截断过长的对话：

 | Flag | 默认 | 说明 |
 |------|------|------|
-| `BUDDY` | ✅ dev only | 伴侣系统 |
-| `BRIDGE_MODE` | ✅ dev only | 远程控制 |
-| `VOICE_MODE` | ✅ dev+build | 语音模式 |
-| `CHICAGO_MCP` | ✅ dev+build | Computer Use + Chrome |
-| `AGENT_TRIGGERS_REMOTE` | ✅ dev+build | 定时任务 |
-| `SHOT_STATS` | ✅ dev+build | API 统计 |
-| `TOKEN_BUDGET` | ✅ dev+build | Token 预算 |
-| `PROMPT_CACHE_BREAK_DETECTION` | ✅ dev+build | 缓存检测 |
-| `ULTRAPLAN` | ✅ dev+build | 高级规划 |
-| `DAEMON` | ✅ dev+build | 后台守护 |
-| `UDS_INBOX` | ✅ dev only | Pipe IPC |
-| `LAN_PIPES` | ✅ dev only | LAN 群控 |
-| `MONITOR_TOOL` | ✅ dev+build | 后台监控 |
-| `WORKFLOW_SCRIPTS` | ✅ dev+build | 工作流脚本 |
-| `FORK_SUBAGENT` | ✅ dev+build | 子 Agent |
-| `KAIROS` | ✅ dev+build | Kairos 调度 |
-| `COORDINATOR_MODE` | ✅ dev+build | 多 Worker |
-| `HISTORY_SNIP` | ✅ dev+build | 历史管理 |
-| `CONTEXT_COLLAPSE` | ✅ dev+build | 上下文折叠 |
-| `ULTRATHINK` | ✅ dev+build | 扩展思考 |
-| `EXTRACT_MEMORIES` | ✅ dev+build | 自动记忆提取 |
-| `VERIFICATION_AGENT` | ✅ dev+build | 验证 Agent |
-| `KAIROS_BRIEF` | ✅ dev+build | Brief 模式 |
-| `AWAY_SUMMARY` | ✅ dev+build | 离开摘要 |
-| `ACP` | ✅ dev+build | ACP 协议 |
-| `LODESTONE` | ✅ dev+build | 深度链接 |
-| `BUILTIN_EXPLORE_PLAN_AGENTS` | ✅ dev+build | 内置 Explore/Plan agent |
-| `AGENT_TRIGGERS` | ✅ dev+build | 本地定时任务 |
-| `BG_SESSIONS` | ✅ dev only | 后台会话 |
-| `TEMPLATES` | ✅ dev only | 模板系统 |
-| `TRANSCRIPT_CLASSIFIER` | ✅ dev only | 对话分类 |
+| `BUDDY` | ✅ dev/build | 伴侣系统 |
+| `BRIDGE_MODE` | ✅ dev/build | 远程控制 |
+| `VOICE_MODE` | ✅ dev/build | 语音模式 |
+| `CHICAGO_MCP` | ✅ dev/build | Computer Use + Chrome |
+| `AGENT_TRIGGERS_REMOTE` | ✅ dev/build | 定时任务 |
+| `SHOT_STATS` | ✅ dev/build | API 统计 |
+| `TOKEN_BUDGET` | ✅ dev/build | Token 预算 |
+| `PROMPT_CACHE_BREAK_DETECTION` | ✅ dev/build | 缓存检测 |
+| `ULTRAPLAN` | ✅ dev/build | 高级规划 |
+| `DAEMON` | ✅ dev/build | 后台守护 |
+| `UDS_INBOX` | ✅ dev/build | Pipe IPC |
+| `LAN_PIPES` | ✅ dev/build | LAN 群控 |
+| `MONITOR_TOOL` | ✅ dev/build | 后台监控 |
+| `WORKFLOW_SCRIPTS` | ✅ dev/build | 工作流脚本 |
+| `FORK_SUBAGENT` | ✅ dev/build | 子 Agent |
+| `KAIROS` | ✅ dev/build | Kairos 调度 |
+| `COORDINATOR_MODE` | ✅ dev/build | 多 Worker |
+| `HISTORY_SNIP` | ✅ dev/build | 历史管理 |
+| `CONTEXT_COLLAPSE` | ✅ dev/build | 上下文折叠 |

 手动启用任意 flag：
 ```bash
--- a/docs/features/autofix-pr.md
+++ b/docs/features/autofix-pr.md
@@ -1,769 +0,0 @@
-# `/autofix-pr` 命令实现规格文档
-
-> **状态**：规划阶段（2026-04-29），等待评审通过后进入实施。
-> **Worktree**：`E:\Source_code\Claude-code-bast-autofix-pr`，分支 `feat/autofix-pr`，基于 `origin/main` 4f1649e2。
-> **架构**：R（Remote-via-CCR），完整版（含 stop 子命令、单例锁、subscribePR、in-process teammate、skills 探测）。
-
---
-
-## 一、背景
-
-### 1.1 问题
-
-本仓库（`Claude-code-bast`）是 Anthropic 官方 `@anthropic-ai/claude-code` 的反编译/重构版本。许多远程能力被 stub 化处理 —— `/autofix-pr` 是其中之一：
-
-```js
-// src/commands/autofix-pr/index.js（当前 stub）
-export default { isEnabled: () => false, isHidden: true, name: 'stub' };
-```
-
-三个字段共同导致命令在斜杠菜单中完全不可见、不可调起：
-
-| 字段 | 值 | 效果 |
-|---|---|---|
-| `isEnabled` | `() => false` | 注册时被判定不可用 |
-| `isHidden` | `true` | 即使被列出也被过滤 |
-| `name` | `'stub'` | 实际注册名是 `'stub'`，输入 `/autofix-pr` 无法匹配 |
-
-### 1.2 用户场景
-
-用户在 fork 仓库（`feat/autonomy-lifecycle-upstream` 分支）尝试对上游 `claude-code-best/claude-code#386` 跑 `/autofix-pr 386`，多次报 `git_repository source setup error`。根因：官方派发的远程 session 落在被 MCP 拒绝访问的仓库（`amdosion/claude-code-bast`），权限/可见性问题。
-
-### 1.3 目标
-
-| ID | 需求 | 验收 |
-|---|---|---|
-| R1 | 命令在斜杠菜单可见可调起 | 输入 `/au` 出现补全 |
-| R2 | 跨仓库 PR：从本地 fork 触发对上游 PR 的修复 | `/autofix-pr 386` 不报 repo-not-allowed |
-| R3 | 远端真正完成修复并 push 回 PR 分支 | PR 出现来自远端的新 commit |
-| R4 | 不破坏现存其他 stub（如 `share`） | 只动 `autofix-pr` |
-| R5 | TypeScript 严格模式，`bun run typecheck` 零错误 | CI 绿 |
-| R6 | bridge 可触发（Remote Control 场景） | `bridgeSafe: true` 生效 |
-| R7 | 支持 stop/off 子命令 | `/autofix-pr stop` 能终止当前监控 |
-| R8 | 单例锁防止重复派发 | 已监控 PR 时拒绝新启动并提示 |
-
---
-
-## 二、反编译调研结论（来源：`C:\Users\12180\.local\bin\claude.exe`）
-
-`claude.exe` 是 242MB 的 Bun 原生编译产物（JS 源码 embed 在二进制内）。通过对该文件的字符串提取（`grep -aoE`）反推出完整调用链。
-
-### 2.1 主入口函数结构
-
-```js
-async function entry(input, q, ctx) {
-  const isStop = input === "stop" || input === "off"
-  const args = { freeformPrompt: input }
-  return main(args, q, ctx)
-}
-
-async function main(args, q, { signal, onProgress }) {
-  // args 字段：{ prNumber, target, freeformPrompt, repoPath, skills }
-  d("tengu_autofix_pr_started", {
-    action: "start",
-    has_pr_number: String(args.prNumber !== undefined),
-    has_repo_path: String(args.repoPath !== undefined),
-  })
-  // ...
-}
-```
-
-### 2.2 `teleportToRemote` 调用签名（黄金证据）
-
-```ts
-const session = await teleportToRemote({
-  initialMessage: C,                       // 给远端的初始消息
-  source: "autofix_pr",                    // ⚠️ 新字段，本仓库 teleport.tsx 没有
-  branchName: N,                           // PR 头分支
-  reuseOutcomeBranch: N,                   // 与 branchName 同 — 远端 push 回原分支
-  title: `Autofix PR: ${owner}/${repo}#${prNumber} (${branch})`,
-  useDefaultEnvironment: true,             // ⚠️ 不用 synthetic env（与 ultrareview 不同）
-  signal,
-  githubPr: { owner, repo, number },
-  cwd: repoPath,
-  onBundleFail: (msg) => { /* ... */ },
-})
-```
-
-**与 `ultrareview` 的关键差异**：
-
-| 字段 | ultrareview | autofix-pr |
-|---|---|---|
-| `environmentId` | `env_011111111111111111111113`（synthetic） | 不传 |
-| `useDefaultEnvironment` | 不传 | `true` |
-| `useBundle` | 有（branch mode） | 不传（`skipBundle` 隐含于不传 bundle） |
-| `reuseOutcomeBranch` | 不传 | 传（远端 push 回原 PR 分支） |
-| `githubPr` | 不传 | 必传 |
-| `source` | 不传 | `"autofix_pr"` |
-| `environmentVariables` | `BUGHUNTER_*` 一堆 | 不传 |
-
-### 2.3 `registerRemoteAgentTask` 调用
-
-```ts
-registerRemoteAgentTask({
-  remoteTaskType: "autofix-pr",
-  session: { id: session.id, title: session.title },
-  command,
-  isLongRunning: true,        // poll 不消费 result，靠通知周期驱动
-})
-```
-
-### 2.4 子命令解析
-
-```
-/autofix-pr <PR#>                    → 启动监控 + 派 CCR session
-/autofix-pr stop                     → 停止当前监控
-/autofix-pr off                      → 同 stop
-/autofix-pr <freeform-prompt>        → 自由 prompt 模式（无 PR 号）
-/autofix-pr <owner>/<repo>#<n>       → 跨仓库（覆盖 R2 验收）
-```
-
-### 2.5 状态模型
-
- **单例锁**：同一时刻只能监控一个 PR。重复启动报：`already monitoring ${repo}#${prNumber}. Run /autofix-pr stop first.`（error_code: `rc_already_monitoring_other`）
- **PR 订阅**：调 `kairos.subscribePR(owner, repo, taskId)` —— 依赖 `KAIROS_GITHUB_WEBHOOKS` feature flag（用户已订阅，可用）
- **in-process teammate**：注册后台 agent
-  ```ts
-  const teammate = {
-    agentId,
-    agentName: "autofix-pr",
-    teamName: "_autofix",
-    color: undefined,
-    planModeRequired: false,
-    parentSessionId,
-  }
-  ```
- **Skills 探测**：扫项目里 autofix-related skills（如 `.claude/skills/autofix-*` 或根目录 `AUTOFIX.md`），命中后拼到 prompt：`Run X and Y for custom instructions on how to autofix.`
-
-### 2.6 Telemetry
-
-| 事件 | 字段 |
-|---|---|
-| `tengu_autofix_pr_started` | `{ action, has_pr_number, has_repo_path }` |
-| `tengu_autofix_pr_result` | `{ result, error_code? }` |
-
-`result` 取值：`success_rc` / `failed` / `cancelled`
-
-`error_code` 取值：
-
-| code | 含义 |
-|---|---|
-| `rc_already_monitoring_other` | 已在监控其他 PR |
-| `session_create_failed` | teleport 失败 |
-| `exception` | 未捕获异常 |
-
-### 2.7 错误返回结构
-
-```ts
-function errorResult(message: string, code: string) {
-  d("tengu_autofix_pr_result", { result: "failed", error_code: code })
-  return {
-    kind: "error",
-    message: `Autofix PR failed: ${message}`,
-    code,
-  }
-}
-
-function cancelledResult() {
-  d("tengu_autofix_pr_result", { result: "cancelled" })
-  return { kind: "cancelled" }
-}
-```
-
---
-
-## 三、本仓库现有基础设施盘点
-
-下表列出实现 `/autofix-pr` 时**直接复用**的现成能力（已确认完整可用）：
-
-| 能力 | 文件 | 角色 |
-|---|---|---|
-| `teleportToRemote` | `src/utils/teleport.tsx:947` | 派 CCR 远端 session（缺 `source` 字段，需补） |
-| `registerRemoteAgentTask` | `src/tasks/RemoteAgentTask/RemoteAgentTask.tsx:526` | 注册 long-running 任务到 store |
-| `checkRemoteAgentEligibility` | `src/tasks/RemoteAgentTask/RemoteAgentTask.tsx:185` | 前置鉴权检查 |
-| `getRemoteTaskSessionUrl` | `src/tasks/RemoteAgentTask/RemoteAgentTask.tsx` | 生成 session 跟踪 URL |
-| `formatPreconditionError` | `src/tasks/RemoteAgentTask/RemoteAgentTask.tsx` | 错误文案格式化 |
-| `REMOTE_TASK_TYPES` | `src/tasks/RemoteAgentTask/RemoteAgentTask.tsx:103` | 已含 `'autofix-pr'` 类型 |
-| `AutofixPrRemoteTaskMetadata` | `src/tasks/RemoteAgentTask/RemoteAgentTask.tsx:112` | `{ owner, repo, prNumber }` schema |
-| `RemoteSessionProgress` | `src/components/tasks/RemoteSessionProgress.tsx` | 进度面板 UI（已认 autofix-pr 类型） |
-| `detectCurrentRepositoryWithHost` | `src/utils/detectRepository.ts` | 解析 owner/repo |
-| `getDefaultBranch` / `gitExe` | `src/utils/git.ts` | git 工具 |
-| `feature('FLAG')` | `bun:bundle` | feature flag 系统（CLAUDE.md 红线：只能在 if/三元条件位置直接调用） |
-
-### 模板答案文件
-
-以下三个文件已确认完整工作，是本次实现的"参考答案"：
-
- `src/commands/review/reviewRemote.ts`（317 行）—— **主模板**，照抄改造
- `src/commands/ultraplan.tsx`（525 行）
- `src/commands/review/ultrareviewCommand.tsx`（89 行）
-
---
-
-## 四、命令对象规格
-
-### 4.1 `Command` 类型选择
-
-`Command` 类型定义在 `src/types/command.ts`，三态之一：`PromptCommand` / `LocalCommand` / `LocalJSXCommand`。
-
-**选 `LocalJSXCommand`**，因为：
- 需要 spawn 远端 session 并显示进度面板
- 兄弟命令 `ultraplan` / `ultrareview` 都用 local-jsx
- 接口签名：`call(onDone, context, args) => Promise<React.ReactNode>`
-
-### 4.2 `index.ts` 完整形状
-
-```ts
-import { feature } from 'bun:bundle'
-import type { Command } from '../../types/command.js'
-
-const autofixPr: Command = {
-  type: 'local-jsx',
-  name: 'autofix-pr',                          // 关键：必须是 'autofix-pr' 不是 'stub'
-  description: 'Auto-fix CI failures on a pull request',
-  argumentHint: '<pr-number> | stop | <owner>/<repo>#<n>',
-  isEnabled: () => feature('AUTOFIX_PR'),
-  isHidden: false,
-  bridgeSafe: true,
-  getBridgeInvocationError: (args) => {
-    const trimmed = args.trim()
-    if (!trimmed) return 'PR number required, e.g. /autofix-pr 386'
-    if (trimmed === 'stop' || trimmed === 'off') return undefined
-    if (/^\d+$/.test(trimmed)) return undefined
-    if (/^[\w.-]+\/[\w.-]+#\d+$/.test(trimmed)) return undefined
-    return 'Invalid args. Use /autofix-pr <pr-number> | stop | <owner>/<repo>#<n>'
-  },
-  load: async () => {
-    const m = await import('./launchAutofixPr.js')
-    return { call: m.callAutofixPr }
-  },
-}
-
-export default autofixPr
-```
-
-### 4.3 参数解析规则
-
-```
-^stop$ | ^off$            → { action: 'stop' }
-^\d+$                     → { action: 'start', prNumber, owner: <git>, repo: <git> }
-^([\w.-]+)/([\w.-]+)#(\d+)$ → { action: 'start', prNumber, owner, repo }
-其他                       → { action: 'start', freeformPrompt: <input> }
-空字符串                   → 错误
-```
-
---
-
-## 五、文件结构
-
-```
-src/commands/autofix-pr/
-├── index.ts                       # 命令对象（替换 index.js）
-├── launchAutofixPr.ts             # 主流程
-├── parseArgs.ts                   # 参数解析（独立便于测试）
-├── monitorState.ts                # 单例锁
-├── inProcessAgent.ts              # 后台 teammate
-├── skillDetect.ts                 # 项目 skills 探测
-└── __tests__/
-    ├── parseArgs.test.ts
-    ├── monitorState.test.ts
-    ├── launchAutofixPr.test.ts
-    └── index.test.ts              # bridge invocation error 测试
-```
-
-**删除**：原 `index.js`、`index.d.ts`（合并进 `index.ts`）。
-
-**修改**：
- `scripts/defines.ts` —— 加 `AUTOFIX_PR` flag
- `scripts/dev.ts` —— dev 默认开启
- `src/utils/teleport.tsx` —— `teleportToRemote` 选项加 `source?: string` 字段并透传
- `src/commands.ts` —— **不动**（import 路径 `'./commands/autofix-pr/index.js'` 在 ESM/Bun 下会自动解析到 `.ts`）
-
---
-
-## 六、模块详细规格
-
-### 6.1 `parseArgs.ts`
-
-```ts
-export type ParsedArgs =
-  | { action: 'stop' }
-  | { action: 'start'; prNumber: number; owner?: string; repo?: string }
-  | { action: 'freeform'; prompt: string }
-  | { action: 'invalid'; reason: string }
-
-export function parseAutofixArgs(raw: string): ParsedArgs {
-  const trimmed = raw.trim()
-  if (!trimmed) return { action: 'invalid', reason: 'empty' }
-  if (trimmed === 'stop' || trimmed === 'off') return { action: 'stop' }
-  if (/^\d+$/.test(trimmed)) {
-    return { action: 'start', prNumber: parseInt(trimmed, 10) }
-  }
-  const cross = trimmed.match(/^([\w.-]+)\/([\w.-]+)#(\d+)$/)
-  if (cross) {
-    return {
-      action: 'start',
-      owner: cross[1],
-      repo: cross[2],
-      prNumber: parseInt(cross[3], 10),
-    }
-  }
-  return { action: 'freeform', prompt: trimmed }
-}
-```
-
-### 6.2 `monitorState.ts`
-
-```ts
-import type { UUID } from 'crypto'
-
-type MonitorState = {
-  taskId: UUID
-  owner: string
-  repo: string
-  prNumber: number
-  abortController: AbortController
-  startedAt: number
-}
-
-let active: MonitorState | null = null
-
-export function getActiveMonitor(): Readonly<MonitorState> | null {
-  return active
-}
-
-export function setActiveMonitor(state: MonitorState): void {
-  if (active) throw new Error(`Monitor already active: ${active.repo}#${active.prNumber}`)
-  active = state
-}
-
-export function clearActiveMonitor(): void {
-  if (active) {
-    active.abortController.abort()
-    active = null
-  }
-}
-
-export function isMonitoring(owner: string, repo: string, prNumber: number): boolean {
-  return active?.owner === owner && active?.repo === repo && active?.prNumber === prNumber
-}
-```
-
-### 6.3 `inProcessAgent.ts`
-
-仿官方 `xd9` 函数：
-
-```ts
-import { randomUUID, type UUID } from 'crypto'
-import { getCurrentSessionId } from '../../bootstrap/state.js'
-
-export type AutofixTeammate = {
-  agentId: UUID
-  agentName: 'autofix-pr'
-  teamName: '_autofix'
-  color: undefined
-  planModeRequired: false
-  parentSessionId: UUID
-  abortController: AbortController
-  taskId: UUID
-}
-
-export function createAutofixTeammate(
-  initialMessage: string,
-  target: string,
-): AutofixTeammate {
-  return {
-    agentId: randomUUID(),
-    agentName: 'autofix-pr',
-    teamName: '_autofix',
-    color: undefined,
-    planModeRequired: false,
-    parentSessionId: getCurrentSessionId(),
-    abortController: new AbortController(),
-    taskId: randomUUID(),
-  }
-}
-```
-
-### 6.4 `skillDetect.ts`
-
-```ts
-import { existsSync } from 'fs'
-import { join } from 'path'
-
-export function detectAutofixSkills(cwd: string): string[] {
-  const candidates = [
-    'AUTOFIX.md',
-    '.claude/skills/autofix.md',
-    '.claude/skills/autofix-pr/SKILL.md',
-  ]
-  return candidates.filter(rel => existsSync(join(cwd, rel)))
-}
-
-export function formatSkillsHint(skills: string[]): string {
-  if (skills.length === 0) return ''
-  return ` Run ${skills.join(' and ')} for custom instructions on how to autofix.`
-}
-```
-
-### 6.5 `launchAutofixPr.ts`
-
-主流程伪代码（约 250 行）：
-
-```ts
-import type { LocalJSXCommandCall } from '../../types/command.js'
-import { parseAutofixArgs } from './parseArgs.js'
-import { getActiveMonitor, setActiveMonitor, clearActiveMonitor, isMonitoring } from './monitorState.js'
-import { createAutofixTeammate } from './inProcessAgent.js'
-import { detectAutofixSkills, formatSkillsHint } from './skillDetect.js'
-import { teleportToRemote } from '../../utils/teleport.js'
-import { checkRemoteAgentEligibility, registerRemoteAgentTask, getRemoteTaskSessionUrl } from '../../tasks/RemoteAgentTask/RemoteAgentTask.js'
-import { detectCurrentRepositoryWithHost } from '../../utils/detectRepository.js'
-import { logEvent } from '../../services/analytics/index.js'
-
-export const callAutofixPr: LocalJSXCommandCall = async (onDone, context, args) => {
-  const parsed = parseAutofixArgs(args)
-
-  // 1. stop 子命令
-  if (parsed.action === 'stop') {
-    const m = getActiveMonitor()
-    if (!m) {
-      onDone('No active autofix monitor.', { display: 'system' })
-      return null
-    }
-    clearActiveMonitor()
-    onDone(`Stopped monitoring ${m.repo}#${m.prNumber}.`, { display: 'system' })
-    return null
-  }
-
-  // 2. invalid
-  if (parsed.action === 'invalid') {
-    return errorView(`Invalid args: ${parsed.reason}`)
-  }
-
-  // 3. freeform — 暂不支持，提示用户
-  if (parsed.action === 'freeform') {
-    return errorView('Freeform prompt mode not yet supported. Use /autofix-pr <pr-number>.')
-  }
-
-  // 4. start
-  logEvent('tengu_autofix_pr_started', {
-    action: 'start',
-    has_pr_number: 'true',
-    has_repo_path: String(!!process.cwd()),
-  })
-
-  // 4.1 解析 owner/repo
-  let owner = parsed.owner
-  let repo = parsed.repo
-  if (!owner || !repo) {
-    const detected = await detectCurrentRepositoryWithHost()
-    if (!detected || detected.host !== 'github.com') {
-      return errorResult('Cannot detect GitHub repo from current directory.', 'session_create_failed')
-    }
-    owner = detected.owner
-    repo = detected.name
-  }
-
-  // 4.2 单例锁
-  if (isMonitoring(owner, repo, parsed.prNumber)) {
-    return errorResult(`already monitoring ${repo}#${parsed.prNumber} in background`, 'success_rc')
-  }
-  if (getActiveMonitor()) {
-    const m = getActiveMonitor()!
-    return errorResult(
-      `already monitoring ${m.repo}#${m.prNumber}. Run /autofix-pr stop first.`,
-      'rc_already_monitoring_other',
-    )
-  }
-
-  // 4.3 资格检查
-  const eligibility = await checkRemoteAgentEligibility()
-  if (!eligibility.eligible) {
-    return errorResult('Remote agent not available.', 'session_create_failed')
-  }
-
-  // 4.4 探测 skills
-  const skills = detectAutofixSkills(process.cwd())
-  const skillsHint = formatSkillsHint(skills)
-
-  // 4.5 拼初始消息
-  const target = `${owner}/${repo}#${parsed.prNumber}`
-  const branchName = `refs/pull/${parsed.prNumber}/head`
-  const initialMessage = `Auto-fix failing CI checks on PR #${parsed.prNumber} in ${owner}/${repo}.${skillsHint}`
-
-  // 4.6 创建 in-process teammate
-  const teammate = createAutofixTeammate(initialMessage, target)
-
-  // 4.7 调 teleport
-  let bundleFailMsg: string | undefined
-  const session = await teleportToRemote({
-    initialMessage,
-    source: 'autofix_pr',
-    branchName,
-    reuseOutcomeBranch: branchName,
-    title: `Autofix PR: ${target} (${branchName})`,
-    useDefaultEnvironment: true,
-    signal: teammate.abortController.signal,
-    githubPr: { owner, repo, number: parsed.prNumber },
-    cwd: process.cwd(),
-    onBundleFail: (msg) => { bundleFailMsg = msg },
-  })
-
-  if (!session) {
-    return errorResult(bundleFailMsg ?? 'remote session creation failed.', 'session_create_failed')
-  }
-
-  // 4.8 注册任务到 store
-  registerRemoteAgentTask({
-    remoteTaskType: 'autofix-pr',
-    session,
-    command: `/autofix-pr ${parsed.prNumber}`,
-    context,
-  })
-
-  // 4.9 设置单例锁
-  setActiveMonitor({
-    taskId: teammate.taskId,
-    owner,
-    repo,
-    prNumber: parsed.prNumber,
-    abortController: teammate.abortController,
-    startedAt: Date.now(),
-  })
-
-  // 4.10 PR webhooks 订阅（feature-gated）
-  if (feature('KAIROS_GITHUB_WEBHOOKS')) {
-    await kairosSubscribePR(owner, repo, teammate.taskId).catch(() => {/* non-fatal */})
-  }
-
-  // 4.11 返回 JSX 进度面板
-  const sessionUrl = getRemoteTaskSessionUrl(session.id)
-  logEvent('tengu_autofix_pr_launched', { target })
-  onDone(
-    `Autofix launched for ${target}. Track: ${sessionUrl}`,
-    { display: 'system' },
-  )
-  return null  // 进度面板由 RemoteAgentTask 自动渲染
-}
-
-function errorResult(message: string, code: string) {
-  logEvent('tengu_autofix_pr_result', { result: 'failed', error_code: code })
-  // ... 渲染错误 JSX
-}
-```
-
-> **注意**：`feature('KAIROS_GITHUB_WEBHOOKS')` 必须直接放在 if 条件位置，不能赋值给变量（CLAUDE.md 红线）。
-
-### 6.6 `teleport.tsx` 补 `source` 字段
-
-```diff
- export async function teleportToRemote(options: {
-   initialMessage: string | null
-   branchName?: string
-   title?: string
-   description?: string
-+  /**
-+   * Identifies which command/flow originated this teleport. CCR backend
-+   * uses this for routing/billing/observability. Known values: 'autofix_pr',
-+   * 'ultrareview', 'ultraplan'. Pass-through field — not interpreted client-side.
-+   */
-+  source?: string
-   model?: string
-   permissionMode?: PermissionMode
-   // ...
- })
-```
-
-并在内部构造 request 时透传到 session_context（具体字段名按现有 review/ultraplan 调用结构对齐）。
-
---
-
-## 七、Feature Flag
-
-### 7.1 新增 flag
-
-`scripts/defines.ts` 已有的 flag 集合中加 `AUTOFIX_PR`。
-
-### 7.2 启用矩阵
-
-| 环境 | 是否默认开启 | 说明 |
-|---|---|---|
-| dev (`bun run dev`) | 是 | `scripts/dev.ts` 加进默认列表 |
-| build (production `bun run build`) | 否 | 灰度上线，需要 `FEATURE_AUTOFIX_PR=1` 显式开启 |
-| 测试 | 按需 | 测试文件通过 mock `bun:bundle` 控制 |
-
-### 7.3 与官方上游同步策略
-
-如果上游某天恢复官方实现，本仓库的本地实现优先（项目即 fork）：
-1. 保留 `AUTOFIX_PR` flag 名
-2. 保留 `RemoteTaskType` 字段不动
-3. 冲突时合并：吸收上游的 `source` 字段值变更、env var 变更，保留我们的本地 launcher 函数
-
---
-
-## 八、测试计划
-
-### 8.1 测试文件
-
-| 文件 | 覆盖目标 | 测试用例数 |
-|---|---|---|
-| `parseArgs.test.ts` | 参数解析全分支 | ~10 |
-| `monitorState.test.ts` | 单例锁正确性 | ~6 |
-| `launchAutofixPr.test.ts` | 主流程 happy path + 失败路径 | ~12 |
-| `index.test.ts` | bridge invocation error 校验 | ~5 |
-
-### 8.2 关键断言
-
-`launchAutofixPr.test.ts`：
-
-```ts
-test('start with PR number teleports with correct args', async () => {
-  // mock teleportToRemote, registerRemoteAgentTask, detectCurrentRepositoryWithHost
-  await callAutofixPr(onDone, context, '386')
-  expect(teleportMock).toHaveBeenCalledWith(expect.objectContaining({
-    source: 'autofix_pr',
-    useDefaultEnvironment: true,
-    githubPr: { owner: 'amDosion', repo: 'claude-code-bast', number: 386 },
-    branchName: 'refs/pull/386/head',
-    reuseOutcomeBranch: 'refs/pull/386/head',
-  }))
-  expect(registerMock).toHaveBeenCalledWith(expect.objectContaining({
-    remoteTaskType: 'autofix-pr',
-  }))
-})
-
-test('cross-repo syntax owner/repo#n parses correctly', async () => {
-  await callAutofixPr(onDone, context, 'anthropics/claude-code#999')
-  expect(teleportMock).toHaveBeenCalledWith(expect.objectContaining({
-    githubPr: { owner: 'anthropics', repo: 'claude-code', number: 999 },
-  }))
-})
-
-test('singleton lock blocks second start', async () => {
-  await callAutofixPr(onDone, context, '386')
-  const result = await callAutofixPr(onDone, context, '999')
-  expect(extractError(result)).toMatch(/already monitoring.*386.*Run \/autofix-pr stop first/)
-})
-
-test('stop clears active monitor', async () => {
-  await callAutofixPr(onDone, context, '386')
-  await callAutofixPr(onDone, context, 'stop')
-  expect(getActiveMonitor()).toBeNull()
-})
-```
-
-### 8.3 Mock 策略
-
-按本仓库 `tests/mocks/` 共享 mock 习惯：
- `tests/mocks/log.ts` 和 `tests/mocks/debug.ts` —— 必 mock
- `bun:bundle` —— mock `feature` 返回 `true`
- `teleportToRemote` —— 模块级 mock，断言入参
- `registerRemoteAgentTask` —— 模块级 mock，断言入参
- `detectCurrentRepositoryWithHost` —— mock 返回 `{ owner, name, host }`
-
-### 8.4 类型检查
-
-```bash
-bun run typecheck      # 必须零错误
-bun run test:all       # 必须全绿
-```
-
---
-
-## 九、实施步骤（11 步清单）
-
-```
-[ ] Step 1   scripts/defines.ts + scripts/dev.ts 加 AUTOFIX_PR flag
-[ ] Step 2   src/utils/teleport.tsx 加 source?: string 字段（约 5 行）
-[ ] Step 3   删除 src/commands/autofix-pr/{index.js, index.d.ts}
-             新建 src/commands/autofix-pr/index.ts（约 50 行）
-[ ] Step 4   新建 src/commands/autofix-pr/parseArgs.ts（约 30 行）
-[ ] Step 5   新建 src/commands/autofix-pr/monitorState.ts（约 40 行）
-[ ] Step 6   新建 src/commands/autofix-pr/inProcessAgent.ts（约 60 行）
-[ ] Step 7   新建 src/commands/autofix-pr/skillDetect.ts（约 30 行）
-[ ] Step 8   新建 src/commands/autofix-pr/launchAutofixPr.ts（约 250 行）
-             照抄 reviewRemote.ts，按 §2.2 差异表改造
-[ ] Step 9   新建四份测试文件（约 150 行）
-[ ] Step 10  bun run typecheck && bun run test:all 全绿
-[ ] Step 11  dev 模式手测：
-              a. /autofix-pr 386 → 期望出现 RemoteSessionProgress 面板
-              b. /autofix-pr stop → 期望提示已停止
-              c. /autofix-pr anthropics/claude-code#999 → 期望跨仓库
-              d. 第二次 /autofix-pr 386 → 期望被单例锁拒绝
-[ ] Step 12  commit：feat: implement /autofix-pr command (replace stub)
-```
-
-预计工作量：约 600 行新增代码（含测试 150 行）。
-
---
-
-## 十、风险与回退
-
-| 风险 | 触发场景 | 回退策略 |
-|---|---|---|
-| `source` 字段 CCR 后端不识别 | 后端只认特定枚举 | 不传该字段，看是否能跑通；如不行回头看官方 cli.js 是否传了别的字段 |
-| `subscribePR` API 在本仓库 client 不完整 | KAIROS_GITHUB_WEBHOOKS 客户端代码缺失 | 用 `.catch(() => {})` 容忍失败，订阅是 nice-to-have |
-| 用户账号无 CCR 权限 | `checkRemoteAgentEligibility` 返回 false | 命令降级到错误文案，不破坏会话 |
-| 远端能起 session 但不修代码 | env vars 命名错误 | 看 `getRemoteTaskSessionUrl` 给的会话页容器日志，调整 |
-| PR 在 fork 仓库且 CCR 没访问权 | `git_repository source error` | 命令应在前置检查中识别并提示用户先把 PR 转到主仓 |
-| 上游恢复官方实现导致冲突 | 上游 sync 时 | 项目是 fork，本地实现优先；冲突手工 merge |
-
-### 回退命令
-
-```bash
-# 完全撤回本次实现
-git checkout main
-git worktree remove E:/Source_code/Claude-code-bast-autofix-pr
-git branch -D feat/autofix-pr
-```
-
-`AUTOFIX_PR` flag 默认在 production 关闭，所以即使代码已合入 main，没显式 `FEATURE_AUTOFIX_PR=1` 时不会影响用户。
-
---
-
-## 十一、验收清单
-
-实施完成后逐项核对：
-
- [ ] R1：dev 模式下输入 `/au` 出现 `/autofix-pr` 补全
- [ ] R2：`/autofix-pr anthropics/claude-code#999` 不报 repo-not-allowed
- [ ] R3：远端 session 跑完后目标 PR 出现新 commit
- [ ] R4：其他 stub（`share` 等）依然 hidden
- [ ] R5：`bun run typecheck` 零错误
- [ ] R6：通过 RC bridge 触发 `/autofix-pr 386` 能跑通
- [ ] R7：`/autofix-pr stop` 终止当前监控
- [ ] R8：第二次 `/autofix-pr` 不同 PR 时被锁拒绝并提示
-
---
-
-## 十二、附录
-
-### 附录 A：相关文件路径速查
-
-| 路径 | 角色 |
-|---|---|
-| `E:\Source_code\Claude-code-bast-autofix-pr` | 实施 worktree |
-| `C:\Users\12180\.local\bin\claude.exe` | 反编译来源（242MB Bun 编译产物） |
-| `C:\Users\12180\.claude\projects\E--Source-code-Claude-code-bast\memory\project_autofix_pr_implementation.md` | 内存备忘（精简版） |
-| `src/commands/review/reviewRemote.ts` | 主模板 |
-| `src/utils/teleport.tsx:947` | `teleportToRemote` 入口 |
-| `src/tasks/RemoteAgentTask/RemoteAgentTask.tsx:103` | `REMOTE_TASK_TYPES` |
-| `src/tasks/RemoteAgentTask/RemoteAgentTask.tsx:526` | `registerRemoteAgentTask` |
-| `src/types/command.ts` | `Command` 类型定义 |
-
-### 附录 B：未决问题
-
-| # | 问题 | 当前处理 | 后续 |
-|---|---|---|---|
-| Q1 | `source` 字段在 CCR backend 是否被解析 | 暂传 `'autofix_pr'`，按官方做法 | 端到端测试时观察远端日志 |
-| Q2 | `subscribePR` 的 client SDK 在本仓库是否完整 | `try/catch` 容忍失败 | Step 11 手测时单独验证 |
-| Q3 | freeform prompt 模式是否实现 | 暂报"not supported" | 第二期再加 |
-
---
-
-## 十三、变更日志
-
-| 日期 | 作者 | 变更 |
-|---|---|---|
-| 2026-04-29 | Claude Opus 4.7 | 初始规格文档创建（基于 claude.exe 反编译 + 仓库现有基础设施盘点） |
--- a/docs/features/background-agent-selector.md
+++ b/docs/features/background-agent-selector.md
@@ -1,225 +0,0 @@
-# Background Agent Selector — 底部统一后台 Agent 切换器
-
-> Feature Flag: 无（直接启用）
-> 实现状态：完整可用
-> 依赖：`viewingAgentTaskId` / `enterTeammateView` / `exitTeammateView` 已有机制
-
-## 一、功能概述
-
-Background Agent Selector 是渲染在 PromptInput 下方的常驻状态条，列出当前所有 **backgrounded 的 local_agent 任务**（包括 `/fork` 派生的 fork agent 和 Task/AgentTool 调用 `run_in_background: true` 派生的子 agent）。用户可以用 ↑/↓ 方向键在 `main` 和各 agent 之间切换焦点，按 Enter 把 REPL 主视图替换为所选 agent 的实时 transcript，再按 Enter 选中 `main` 即可回到主对话。
-
-整个机制完全复用官方已有的 teammate transcript 查看基础设施，不引入新的视图层 / 数据流，仅新增一条 footer pill 类型。
-
-### 核心特性
-
- **统一入口**：`/fork`、Task 派生的 subagent、所有 `run_in_background: true` 的 agent 都在同一栏显示
- **就地切换**：prompt 为空时按 ↓ 溢出进入底部 selector，↑↓ 选中某行，Enter 即切主视图
- **实时状态**：每行显示 agent 类型 + 描述 + 运行时长 + 已消耗 token；running 时圆点为绿色
- **Keep-alive 视图**：agent 完成后在 `evictAfter` grace 窗口内保留一段时间，用户可回看
- **零界面侵入**：tasks 数为 0 时 selector 完全不渲染，不占屏幕高度
- **与旧 Dialog 共存**：Shift+↓ 打开的 `BackgroundTasksDialog` 原有行为保留，selector 只作为展示 + 快捷切换
-
-## 二、用户交互
-
-### 触发方式
-
-有任何 background agent 时，selector 自动出现在 `bypass permissions on` 行下方：
-
-```
-  claude-code | Opus 4.7 (1M context) | ctx:4%
-  ▶▶ bypass permissions on (shift+tab to cycle)
-
-  ○ main                                    ↑/↓ to select · Enter to view
-  ● Explore  Research src/hooks              23s · ↓ 10.9k tokens
-  ○ Explore  Research src/components         22s · ↓  9.5k tokens
-  ○ Explore  Research src/utils              21s · ↓ 13.6k tokens
-```
-
-### 键盘路由
-
-| 位置 / 状态 | 按键 | 行为 |
-|---|---|---|
-| PromptInput 非空 | ↑↓ | 光标移动 / 翻历史（不变） |
-| PromptInput 空 + 历史底部 | ↓ | 焦点下放到 selector，高亮到 `● main` |
-| Selector 聚焦（`footerSelection === 'bg_agent'`） | ↓ | 高亮下移，-1 → 0 → ... → N-1 |
-| Selector 聚焦 | ↑ | 高亮上移；在 `main` 再 ↑ → 焦点回 PromptInput |
-| Selector 聚焦 | Enter | `-1` → `exitTeammateView`；`>=0` → `enterTeammateView(agentId)`。焦点保留在 pill |
-| Selector 聚焦 | Esc | `footer:clearSelection`，焦点回 PromptInput |
-
-### 视觉规则
-
- `● main` / `● <agent>`：当前被**查看**（viewingAgentTaskId 指向）或被**光标聚焦**（pill focused 时以光标为准）的一行
- running 状态的 agent：圆点渲染为 `success` 色（绿色），与 `BackgroundTasksDialog` 状态语义对齐
- 右上角 hint 随状态变化：
-  - pill 聚焦：`↑/↓ to select · Enter to view`
-  - 已选中 running agent：`shift+↓ to manage · x to stop`
-  - 已选中 terminal agent：`shift+↓ to manage · x to clear`
-  - 未选中任何 agent：`shift+↓ to manage background agents`
-
-## 三、实现架构
-
-### 3.1 数据层：`useBackgroundAgentTasks`
-
-文件：`src/hooks/useBackgroundAgentTasks.ts`
-
-封装对 `useAppState(s => s.tasks)` 的过滤：
-
-```ts
-export function useBackgroundAgentTasks(): LocalAgentTaskState[] {
-  const tasks = useAppState(s => s.tasks)
-  return useMemo(() => {
-    const now = Date.now()
-    return Object.values(tasks)
-      .filter(isLocalAgentTask)
-      .filter(t => t.agentType !== 'main-session')
-      .filter(t => t.isBackgrounded !== false)
-      .filter(t => t.evictAfter === undefined || t.evictAfter > now)
-      .sort((a, b) => a.startTime - b.startTime)
-  }, [tasks])
-}
-```
-
-`/fork` 和 `AgentTool` 的 `run_in_background: true` 底层都走 `registerAsyncAgent → runAsyncAgentLifecycle`，最终写入同一个 `appState.tasks` Map；此 hook 是唯一数据源，Selector 和 PromptInput 的 `bgAgentList` 都消费它。
-
-### 3.2 状态层：新增两个字段
-
-文件：`src/state/AppStateStore.ts`
-
-```ts
-export type FooterItem =
-  | 'tasks' | 'tmux' | 'bagel' | 'teams' | 'bridge' | 'companion'
-  | 'bg_agent'   // ← 新增
-
-export type AppState = DeepImmutable<{
-  // ...
-  selectedBgAgentIndex: number  // -1 = main, 0..N-1 = 选中的 agent
-}>
-```
-
- `'bg_agent'` 作为 `FooterItem` 加入 footer pill 体系，享受既有的 `footer:up` / `footer:down` / `footer:openSelected` keybinding 路由
- `selectedBgAgentIndex` 记录 selector 的光标位置，与 `viewingAgentTaskId`（"正在看什么"）独立；它不可从 `viewingAgentTaskId` 派生——Enter 后光标留在 pill 继续导航，查看目标才变
-
-### 3.3 键盘路由：PromptInput footer pill 分支
-
-文件：`src/components/PromptInput/PromptInput.tsx`
-
-1. **`bg_agent` 进入 footerItems[0]**：保证 prompt ↓ 溢出时（`handleHistoryDown` → `selectFooterItem(footerItems[0])`）直接进入 selector，而不是 `tasks` 等其他 pill
-2. **`footer:up` 分支**：`bgAgentSelected` 时 `selectedBgAgentIndex > -1` 则递减；在 -1 → `selectFooterItem(null)` 退出 pill
-3. **`footer:down` 分支**：`selectedBgAgentIndex < bgAgentList.length - 1` 则递增，到底 clamp
-4. **`footer:openSelected` 分支**：index === -1 → `exitTeammateView`；否则 `enterTeammateView(bgAgentList[i].agentId)`。**不清理 pill 焦点**，光标留在 selector 上继续导航
-5. **`selectFooterItem('bg_agent')`**：入 pill 时重置 `selectedBgAgentIndex = -1`（光标落到 `main`）
-
-### 3.4 渲染层：`BackgroundAgentSelector`
-
-文件：`src/components/tasks/BackgroundAgentSelector.tsx`
-
-纯展示组件，不订阅键盘：
-
-```tsx
-const tasks = useBackgroundAgentTasks()
-const viewingId = useAppState(s => s.viewingAgentTaskId)
-const footerSelection = useAppState(s => s.footerSelection)
-const selectedBgIndex = useAppState(s => s.selectedBgAgentIndex)
-
-if (tasks.length === 0) return null
-
-const pillFocused = footerSelection === 'bg_agent'
-const highlightedId = pillFocused
-  ? (selectedBgIndex === -1 ? null : tasks[selectedBgIndex]?.agentId ?? null)
-  : (viewingId ?? null)
-```
-
-**高亮派生规则**：pill 聚焦 → 跟 `selectedBgAgentIndex`；未聚焦 → 镜像 `viewingAgentTaskId`。这样当用户通过 Shift+↓ Dialog 或 `enterTeammateView` 其它途径切换视图时，selector 也会正确反映。
-
-### 3.5 主视图切换：复用 `viewingAgentTaskId`
-
-REPL.tsx 主体仍复用原有查看逻辑：
-
-```ts
-const viewedTask = viewingAgentTaskId ? tasks[viewingAgentTaskId] : undefined
-const viewedAgentTask = ... (isLocalAgentTask(viewedTask) ? viewedTask : undefined)
-const displayedMessages = viewedAgentTask ? displayedAgentMessages : messages
-```
-
-当 `enterTeammateView(agentId)` 把 `viewingAgentTaskId` 设成某个 local_agent 的 id：
-
- `viewedAgentTask` 解析成该 agent
- `displayedMessages` 切换到 agent 的 messages
- 消息列表、spinner、unseen divider 等一整套组件自动用 agent transcript 重渲染
- 主对话流被"暂停"（并非销毁，回到 `main` 时仍在原处）
-
-`enterTeammateView` 同步负责：设 `retain: true` 阻止 eviction、清 `evictAfter`、触发 disk bootstrap 从 `agent-<id>.jsonl` 加载完整 transcript 到 `task.messages`。
-
-#### Fork agent prompt 归一化
-
-`/fork` agent 的 transcript 和普通 subagent 不同：它继承 main agent 的上下文，真实初始消息形态是：
-
-```text
-...parent messages
-assistant([...tool_use])
-user([tool_result..., text("<fork-boilerplate>...Your directive: <prompt>")])
-...fork live messages
-```
-
-这里的 prompt 文本混在 `[tool_result..., text]` 多 block user message 里。消息渲染管线会优先把这条 user message 当作 tool-result plumbing 来处理，导致 `<fork-boilerplate>` 里的用户 prompt 不稳定可见。为保证切换到 fork agent 时总能看到用户发起的 fork prompt，REPL.tsx 对 fork 视图做一次展示层归一化：
-
-1. 仅当 `viewedAgentTask.agentType === 'fork'` 时启用，不影响普通 Explore / Task subagent。
-2. 从原始 messages 中识别包含 `<fork-boilerplate>` 的 carrier message。
-3. 剥离 carrier message 里的 boilerplate text block，但保留 `tool_result` blocks，避免破坏父 assistant `tool_use` 的承接关系。
-4. 强制插入一条独立 `createUserMessage({ content: viewedAgentTask.prompt })` 作为可见用户 prompt。
-5. 插入位置优先为 boilerplate carrier 后；如果 sidechain bootstrap 还没读到 carrier，则插到最后一条 inherited `assistant tool_use` 后面，确保 prompt 接在 main 上下文之后，而不是跑到视图顶部。
-
-这个归一化只影响 UI 展示用的 `displayedAgentMessages`，不回写 `task.messages`，也不改变发送给模型的 fork transcript。
-
-### 3.6 生命周期
-
-完全复用官方既有机制：
-
- **运行中**：`isBackgroundTask()` 谓词为真，selector 列出
- **完成 / 失败 / 中止**：`completeAgentTask` / `failAgentTask` / `killAsyncAgent` 设 `status` 为 terminal
- **回访后退出**：`exitTeammateView` 调 `release(task)`——清 `retain`、清 `messages`、terminal 状态下设 `evictAfter = now + PANEL_GRACE_MS (30s)`
- **evictAfter 过期**：`useBackgroundAgentTasks` 过滤时自然剔除，selector 行消失
- **手动清除**：`stopOrDismissAgent(taskId)` 设 `evictAfter = 0`，立即消失
-
-## 四、设计决策
-
-1. **数据源单一**：`useBackgroundAgentTasks` 是唯一过滤点，PromptInput 也复用，避免过滤条件散落
-2. **pill 聚焦保留**：Enter 切视图后不松焦，让 ↑↓ 连续导航，贴近官方体验
-3. **`bg_agent` 放 footerItems[0]**：确保 ↓ 溢出直接进入 selector 而非其它 pill
-4. **selector 不订阅键盘**：所有按键路由集中在 PromptInput 的 `footer:*` 分支，避免 selector 组件和 PromptInput 双重 `useInput` 的冲突
-5. **`selectedBgAgentIndex` 存 AppState 而非局部 state**：selector 和 PromptInput 分别在两棵不同子树，需要全局字段协调；该值不能从 `viewingAgentTaskId` 派生
-6. **与 `BackgroundTasksDialog` 共存**：Shift+↓ 行为完全不变，selector 是补充快捷入口；Dialog 仍管 shell / workflow / monitor_mcp 等 selector 不显示的 task 类型
-7. **fork prompt 展示层兜底**：fork prompt 不依赖 boilerplate 自身渲染，统一在 `displayedAgentMessages` 中合成独立用户消息；普通 subagent 不走该分支，避免 prompt 重复
-
-## 五、关键 API 复用
-
-| 官方已有能力 | selector 如何使用 |
-|---|---|
-| `AppState.tasks` | 单一数据源，无需 file watcher / output JSONL 订阅 |
-| `registerAsyncAgent` | `/fork` 和 AgentTool 共用，selector 不区分来源 |
-| `enterTeammateView(id)` | Enter 时调用，负责 retain + disk bootstrap |
-| `exitTeammateView` | Enter 选中 `main` 时调用 |
-| `release(task)` + `PANEL_GRACE_MS` | 30s keep-alive，selector 自动生效 |
-| `useElapsedTime` | 每行时长显示，非 running 自动停 interval |
-| `formatTokens` (`utils/format.ts`) | token 数 1k 缩写 |
-| `footer:up` / `footer:down` / `footer:openSelected` keybinding | 键盘路由复用 Footer context |
-
-## 六、文件索引
-
-| 文件 | 职责 |
-|------|------|
-| `src/hooks/useBackgroundAgentTasks.ts` | 数据过滤 hook（backgrounded local_agent + evictAfter 过滤 + startTime 排序） |
-| `src/components/tasks/BackgroundAgentSelector.tsx` | 底部 selector UI，纯展示 |
-| `src/components/PromptInput/PromptInput.tsx` | 新增 `'bg_agent'` footer pill + 对应的 `footer:up/down/openSelected` 分支 |
-| `src/state/AppStateStore.ts` | `FooterItem` 加 `'bg_agent'`；新增 `selectedBgAgentIndex` 字段 |
-| `src/main.tsx` | `getDefaultAppState` 同步初始化 `selectedBgAgentIndex: -1` |
-| `src/screens/REPL.tsx` | 在 PromptInput + SessionBackgroundHint 之后挂载 `<BackgroundAgentSelector />`；切换 agent 主视图；对 fork transcript 做 prompt 归一化 |
-| `src/components/messages/AssistantToolUseMessage.tsx` | 新增 `defaultCollapsed?: boolean` prop，为后续详情视图默认折叠工具块预留 |
-| `src/components/messages/UserTextMessage.tsx` | 识别 `<fork-boilerplate>`，交给 fork 专用 renderer 处理 |
-| `src/components/messages/UserForkBoilerplateMessage.tsx` | 将 fork boilerplate text 折叠为纯用户 prompt；作为 transcript 中原位渲染的兼容路径 |
-
-## 七、已知限制
-
- `Date.now()` 在 `useBackgroundAgentTasks` 的 useMemo 里冻结于 `[tasks]` 触发时：若长时间没有新 task 变更事件，某个 terminal agent 的 grace 期过期后不会立即从 selector 消失，要等下一次 tasks 变化才刷新。在典型使用（主对话一直在产生消息）下感知不到，暂不额外加 interval。
- Selector 当前不处理 Shell Task / Workflow / Monitor MCP 等类型——这些仍走 `BackgroundTasksDialog`（Shift+↓）管理。
- `AssistantToolUseMessage` 的 `defaultCollapsed` prop 目前无调用方传值，保留作为后续"agent 详情视图内工具块默认折叠"扩展点。
--- a/docs/features/bash-classifier.md
+++ b/docs/features/bash-classifier.md
@@ -102,6 +102,6 @@ FEATURE_BASH_CLASSIFIER=1 FEATURE_TREE_SITTER_BASH=1 bun run dev
 | `src/utils/permissions/bashClassifier.ts` | — | Bash 分类器（stub，ANT-ONLY） |
 | `src/utils/permissions/yoloClassifier.ts` | 1496 | YOLO 分类器（完整参考实现） |
 | `src/utils/classifierApprovals.ts` | — | 分类器审批信号管理 |
-| `src/components/permissions/BashPermissionRequest/BashPermissionRequest.tsx` | — | 分类器 UI |
+| `src/components/permissions/BashPermissionRequest.tsx:261-469` | — | 分类器 UI |
 | `src/hooks/toolPermission/handlers/interactiveHandler.ts` | — | 交互式权限处理 |
-| `src/services/api/withRetry.ts` | — | API beta 标头 |
+| `src/services/api/withRetry.ts:81` | — | API beta 标头 |
--- a/docs/features/bridge-mode.md
+++ b/docs/features/bridge-mode.md
@@ -30,7 +30,7 @@ BRIDGE_MODE 将本地 CLI 注册为"bridge 环境"，可从 claude.ai 或其他

 文件：`src/bridge/bridgeApi.ts`

-Bridge API Client 提供 9 个核心操作：
+Bridge API Client 提供 7 个核心操作：

 | 操作 | HTTP | 说明 |
 |------|------|------|
@@ -137,7 +137,7 @@ FEATURE_BRIDGE_MODE=1 FEATURE_DAEMON=1 bun run dev

 | 文件 | 行数 | 职责 |
 |------|------|------|
-| `src/bridge/bridgeApi.ts` | 541 | API Client（核心） |
+| `src/bridge/bridgeApi.ts` | 540 | API Client（核心） |
 | `src/bridge/sessionRunner.ts` | — | 会话运行器 |
 | `src/bridge/bridgeConfig.ts` | — | 配置管理 |
 | `src/bridge/replBridgeTransport.ts` | — | 传输层 |
--- a/docs/features/buddy.mdx
+++ b/docs/features/buddy.mdx
@@ -78,13 +78,10 @@ FEATURE_BUDDY=1 bun run dev

 | 文件 | 说明 |
 |---|---|
-| `src/commands/buddy/index.ts` | `/buddy` 命令注册 |
 | `src/commands/buddy/buddy.ts` | `/buddy` 命令处理 |
 | `src/buddy/companion.ts` | 宠物生成与加载 |
-| `src/buddy/companionReact.ts` | 宠物反应系统（REPL 每轮查询后触发） |
 | `src/buddy/types.ts` | 类型定义（物种、稀有度、属性） |
 | `src/buddy/sprites.ts` | 终端像素画渲染 |
 | `src/buddy/CompanionSprite.tsx` | React 组件（输入框旁显示） |
-| `src/buddy/CompanionCard.tsx` | 宠物信息卡片（`/buddy` 无参数时展示） |
 | `src/buddy/useBuddyNotification.tsx` | 启动提示通知 |
 | `src/buddy/prompt.ts` | 宠物相关 prompt 模板 |
--- a/docs/features/channels.md
+++ b/docs/features/channels.md
@@ -1,89 +0,0 @@
-# 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 命令参考
--- a/docs/features/computer-use-tools-reference.md
+++ b/docs/features/computer-use-tools-reference.md
@@ -2,12 +2,12 @@

 ## 概览

-Computer Use 提供 38 个工具，分为三类：
+Computer Use 提供 37 个工具，分为三类：

 | 分类 | 平台 | 工具数 | 说明 |
 |------|------|--------|------|
 | 通用工具 | 全平台 | 24 | 官方 Computer Use 标准能力 |
-| Windows 专属工具 | Win32 | 11 | 绑定窗口模式下的增强能力 |
+| Windows 专属工具 | Win32 | 10 | 绑定窗口模式下的增强能力 |
 | 教学工具 | 全平台 | 3 | 分步引导模式（需 teachMode 开启） |

 ---
@@ -82,7 +82,7 @@ Computer Use 提供 38 个工具，分为三类：

 ---

-## 二、Windows 专属工具（12 个）
+## 二、Windows 专属工具（10 个）

 仅 Windows 平台可见。核心能力：**绑定窗口后的独立操作——不抢占用户鼠标键盘**。

@@ -235,19 +235,8 @@ Computer Use 提供 38 个工具，分为三类：

 | 工具 | 参数 | 说明 |
 |------|------|------|
-| `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 | 操作 | 场景 |
--- a/docs/features/computer-use.md
+++ b/docs/features/computer-use.md
@@ -11,7 +11,7 @@
 - ✅ `@ant/computer-use-input` 拆为 dispatcher + backends（darwin + win32）
 - ✅ `@ant/computer-use-swift` 拆为 dispatcher + backends（darwin + win32）
 - ✅ `CHICAGO_MCP` 编译开关已开
- ✅ `src/` 层 macOS 硬编码已移除（Phase 2 已完成）
+- ❌ `src/` 层有 6 处 macOS 硬编码阻塞

 ## 2. 阻塞点全景

@@ -19,25 +19,25 @@

 | # | 文件:行号 | 阻塞代码 | 影响 |
 |---|----------|---------|------|
-| 1 | `src/main.tsx:2366` | `feature("CHICAGO_MCP")` 门控 | CU 初始化入口 |
+| 1 | `src/main.tsx:1605` | `getPlatform() === 'macos'` | 整个 CU 初始化被跳过 |

 ### 2.2 加载层

 | # | 文件:行号 | 阻塞代码 | 影响 |
 |---|----------|---------|------|
-| 2 | `src/utils/computerUse/swiftLoader.ts` | macOS-only loader（已改为仅 darwin 加载） | 非 darwin 使用 platforms/ 替代 |
-| 3 | `src/utils/computerUse/executor.ts:302` | `process.platform !== 'darwin'` → cross-platform executor | 非 darwin 走跨平台路径 |
+| 2 | `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:72-96` | 剪贴板 | `pbcopy`/`pbpaste` / PowerShell / xclip | Win: PowerShell `Get/Set-Clipboard`；Linux: `xclip`/`wl-copy` |
-| 5 | `drainRunLoop.ts` | CFRunLoop pump | `cu._drainMainRunLoop()` | 非 darwin：直接执行 fn()，不需要 pump |
-| 6 | `escHotkey.ts` | ESC 热键 | CGEventTap | 非 darwin：返回 false（已有 Ctrl+C fallback） |
-| 7 | `hostAdapter.ts` | 系统权限 | TCC accessibility + screenRecording | Win：直接 granted；Linux：检查 xdotool |
-| 8 | `common.ts:55-58` | 平台标识 | 动态获取 | 已改为 `process.platform` 分发 |
-| 9 | `executor.ts:232` | 粘贴快捷键 | `command`/`ctrl` 分发 | 已按平台分发粘贴快捷键 |
+| 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 后端

@@ -100,19 +100,19 @@

 | 步骤 | 文件 | 改动 |
 |------|------|------|
-| 2.1 | `src/main.tsx:2366` | `feature("CHICAGO_MCP")` → 已为跨平台入口 |
-| 2.2 | `src/utils/computerUse/swiftLoader.ts` | 已改为仅 darwin 加载，非 darwin 使用 platforms/ |
-| 2.3 | `src/utils/computerUse/executor.ts:302-309` | 已改为 cross-platform dispatch（非 darwin → createCrossPlatformExecutor） |
-| 2.4 | `src/utils/computerUse/executor.ts:72-96` | 剪贴板已按平台分发：darwin→pbcopy/pbpaste，win32→PowerShell，linux→xclip |
-| 2.5 | `src/utils/computerUse/executor.ts:232` | 粘贴快捷键已按平台分发：darwin→command，其他→ctrl |
-| 2.6 | `src/utils/computerUse/executor.ts:302-309` | 非 darwin 已改为 `createCrossPlatformExecutor()` |
-| 2.7 | `src/utils/computerUse/drainRunLoop.ts` | 非 darwin 无需 pump（直接执行 fn） |
-| 2.8 | `src/utils/computerUse/escHotkey.ts` | 非 darwin 返回 false（已有 Ctrl+C fallback） |
-| 2.9 | `src/utils/computerUse/hostAdapter.ts` | 非 darwin 权限检查逻辑已实现 |
-| 2.10 | `src/utils/computerUse/common.ts:58` | 已改为动态 `process.platform` 分发 |
-| 2.11 | `src/utils/computerUse/common.ts:55` | 已改为 darwin→'native'，其他→'none' |
-| 2.12 | `src/utils/computerUse/gates.ts:55` | 已更新（需验证 enabled 默认值） |
-| 2.13 | `src/utils/computerUse/gates.ts:39` | `hasRequiredSubscription()` 已更新 |
+| 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 后端

--- a/docs/features/context-collapse.md
+++ b/docs/features/context-collapse.md
@@ -25,7 +25,7 @@ CONTEXT_COLLAPSE 让模型内省上下文窗口使用情况，并智能压缩旧
 | 折叠核心 | `src/services/contextCollapse/index.ts` | **Stub** — 接口完整（`ContextCollapseStats`、`CollapseResult`、`DrainResult`），函数全部空操作 |
 | 折叠操作 | `src/services/contextCollapse/operations.ts` | **Stub** — `projectView` 为恒等函数 |
 | 折叠持久化 | `src/services/contextCollapse/persist.ts` | **Stub** — `restoreFromEntries` 为空操作 |
-| CtxInspectTool | `packages/builtin-tools/src/tools/CtxInspectTool/CtxInspectTool.ts` | **实现** — 上下文内省工具 |
+| CtxInspectTool | `src/tools/CtxInspectTool/` | **缺失** — 目录不存在 |
 | SnipTool 提示 | `src/tools/SnipTool/prompt.ts` | **Stub** — 空工具名 |
 | SnipTool 实现 | `src/tools/SnipTool/SnipTool.ts` | **缺失** |
 | force-snip 命令 | `src/commands/force-snip.js` | **缺失** |
@@ -106,7 +106,7 @@ SnipTool 提供手动折叠能力：
 | 1 | `services/contextCollapse/index.ts` | 大 | 折叠状态机、LLM 调用、消息压缩 |
 | 2 | `services/contextCollapse/operations.ts` | 中 | `projectView()` 消息过滤 |
 | 3 | `services/contextCollapse/persist.ts` | 小 | `restoreFromEntries()` 磁盘持久化 |
-| 4 | `tools/CtxInspectTool/` | 已完成 | 上下文内省工具已实现（`packages/builtin-tools/src/tools/CtxInspectTool/`） |
+| 4 | `tools/CtxInspectTool/` | 中 | 上下文内省工具（token 计数、已折叠范围） |
 | 5 | `tools/SnipTool/SnipTool.ts` | 中 | Snip 工具实现 |
 | 6 | `commands/force-snip.js` | 小 | `/force-snip` 命令 |

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

 > Feature Flag: `FEATURE_DAEMON=1`
-> 实现状态：Supervisor 和 remoteControl Worker 已实现
+> 实现状态：主进程和 worker 注册为 Stub，CLI 路由完整
 > 引用数：3

 ## 一、功能概述

-DAEMON 将 Claude Code 变为后台守护进程。主进程（supervisor）管理多个 worker 子进程的生命周期，通过文件系统状态文件进行通信。适用于持续运行的后台服务场景（如配合 BRIDGE_MODE 提供远程控制服务）。
+DAEMON 将 Claude Code 变为后台守护进程。主进程（supervisor）管理多个 worker 进程的生命周期，通过 Unix 域套接字进行 IPC。适用于持续运行的后台服务场景（如配合 BRIDGE_MODE 提供远程控制服务）。

 ## 二、实现架构

@@ -14,9 +14,8 @@ DAEMON 将 Claude Code 变为后台守护进程。主进程（supervisor）管

 | 模块 | 文件 | 状态 |
 |------|------|------|
-| 守护主进程 | `src/daemon/main.ts` | **已实现** — Supervisor 含子命令、Worker 生命周期管理、指数退避重启 |
-| Worker 注册 | `src/daemon/workerRegistry.ts` | **已实现** — remoteControl Worker（headless bridge） |
-| Daemon 状态 | `src/daemon/state.ts` | **已实现** — PID/状态文件的读写与查询 |
+| 守护主进程 | `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 门控 |

@@ -24,49 +23,34 @@ DAEMON 将 Claude Code 变为后台守护进程。主进程（supervisor）管

 ```
 # 启动守护进程
-claude daemon start
+claude daemon

-# 查看状态（默认子命令）
-claude daemon status
-claude daemon ps
-
-# 停止守护进程
-claude daemon stop
-
-# 以 worker 身份启动（由 supervisor 自动调用）
-claude --daemon-worker=remoteControl
-
-# 后台会话管理
-claude daemon bg
-claude daemon attach <session>
-claude daemon logs <session>
-claude daemon kill <session>
+# 以 worker 身份启动
+claude --daemon-worker=<kind>
 ```

-### 2.3 架构
+### 2.3 预期架构

 ```
 Supervisor (daemonMain)
      │
-      ├── Worker: remoteControl
-      │   └── runBridgeHeadless() — 远程控制 headless 模式
-      │       接收远程会话、处理消息、权限审批
+      ├── Worker 1: assistant-mode
+      │   └── 接收和处理 assistant 会话
+      │
+      ├── Worker 2: bridge-sync
+      │   └── bridge 消息同步
+      │
+      └── Worker 3: proactive
+          └── 主动任务执行
      │
      ▼
-文件系统状态文件 (daemon-state.json)
-  - PID、CWD、启动时间、Worker 类型
-  - queryDaemonStatus() / stopDaemonByPid()
+IPC via Unix Domain Sockets
+  - 生命周期管理（启动、停止、重启）
+  - 工作分发
+  - 状态报告
 ```

-### 2.4 Worker 生命周期管理
-
-Supervisor 为每个 worker 实现：
- **指数退避重启**：初始 2s，上限 120s，倍数 ×2
- **快速失败检测**：10s 内连续崩溃 5 次则 parking（不再重启）
- **永久错误退出码**：78 (EXIT_CODE_PERMANENT) 导致直接 parking
- **优雅关闭**：SIGTERM/SIGINT → abort signal → 30s 强制 SIGKILL
-
-### 2.5 与 BRIDGE_MODE 的关系
+### 2.4 与 BRIDGE_MODE 的关系

 DAEMON 和 BRIDGE_MODE 常组合使用：

@@ -79,39 +63,40 @@ if (feature('DAEMON') && feature('BRIDGE_MODE')) {

 双重门控：两个 feature 都需要开启才能使用远程控制服务器。

-## 三、关键设计决策
+## 三、需要补全的内容
+
+| 模块 | 工作量 | 说明 |
+|------|--------|------|
+| `daemon/main.ts` | 大 | Supervisor 主进程：启动 worker、生命周期管理、IPC |
+| `daemon/workerRegistry.ts` | 中 | Worker 类型分发（assistant/bridge-sync/proactive） |
+| Worker 实现 | 大 | 各类型 worker 的具体实现 |
+| IPC 协议 | 中 | Supervisor-Worker 通信层 |
+
+## 四、关键设计决策

 1. **多进程架构**：一个 supervisor + 多个 worker，进程隔离
-2. **文件系统状态通信**：通过 `daemon-state.json` 文件进行状态共享（非 Unix 域套接字）
+2. **Unix 域套接字 IPC**：本地进程间通信，低延迟
 3. **与 BRIDGE_MODE 强绑定**：守护进程最常见的用途是提供远程控制服务
 4. **CLI 子命令路由**：`daemon` 子命令和 `--daemon-worker` 参数在 `cli.tsx` 中路由
-5. **Worker 环境变量**：supervisor 通过环境变量（`DAEMON_WORKER_*`）向 worker 传递配置

-## 四、使用方式
+## 五、使用方式

 ```bash
 # 启用守护进程模式
 FEATURE_DAEMON=1 FEATURE_BRIDGE_MODE=1 bun run dev

 # 启动守护进程
-claude daemon start
+claude daemon

-# 查看状态
-claude daemon status
-
-# 停止守护进程
-claude daemon stop
-
-# 以特定 worker 启动（通常由 supervisor 自动调用）
-claude --daemon-worker=remoteControl
+# 以特定 worker 启动
+claude --daemon-worker=assistant
 ```

-## 五、文件索引
+## 六、文件索引

 | 文件 | 职责 |
 |------|------|
-| `src/daemon/main.ts` | Supervisor 主进程：子命令分发、Worker 生命周期管理、退避重启 |
-| `src/daemon/workerRegistry.ts` | Worker 入口：remoteControl worker 实现 |
-| `src/daemon/state.ts` | Daemon 状态管理：PID 文件读写、状态查询 |
-| `src/entrypoints/cli.tsx` | CLI 路由 |
-| `src/commands.ts` | 命令注册（双重门控） |
+| `src/daemon/main.ts` | Supervisor 主进程（stub） |
+| `src/daemon/workerRegistry.ts` | Worker 注册（stub） |
+| `src/entrypoints/cli.tsx:95,149` | CLI 路由 |
+| `src/commands.ts:77` | 命令注册（双重门控） |
--- a/docs/features/debug-mode.mdx
+++ b/docs/features/debug-mode.mdx
@@ -27,15 +27,13 @@ bun run dev:inspect

 ## 原理

-`dev:inspect` 脚本实际执行的是 `scripts/dev-debug.ts`：
+`dev:inspect` 脚本实际执行的是：

-```typescript
-// scripts/dev-debug.ts
-process.env.BUN_INSPECT = "localhost:8888/<token>"
-await import("./dev")
+```bash
+bun --inspect-wait=localhost:8888/<token> run scripts/dev.ts
 ```

-通过设置 `BUN_INSPECT` 环境变量启动一个 Chrome DevTools Protocol 兼容的 inspect 服务，然后导入 dev 模式入口。VS Code 的 `bun` 扩展通过 WebSocket 连接到输出的地址实现 attach。
+Bun 的 `--inspect-wait` 参数启动一个 Chrome DevTools Protocol 兼容的 inspect 服务，等待调试器连接后才开始执行。VS Code 的 `bun` 扩展通过 WebSocket 连接到这个地址实现 attach。

 ## JetBrains IDE

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

 ### 3.1 门控与互斥

-文件：`packages/builtin-tools/src/tools/AgentTool/forkSubagent.ts:32-39`
+文件：`src/tools/AgentTool/forkSubagent.ts:32-39`

 ```ts
 export function isForkSubagentEnabled(): boolean {
@@ -105,7 +105,7 @@ isForkSubagentEnabled() && !subagent_type?

 ### 3.4 消息构建：buildForkedMessages

-文件：`packages/builtin-tools/src/tools/AgentTool/forkSubagent.ts:107-169`
+文件：`src/tools/AgentTool/forkSubagent.ts:107-169`

 构建的消息结构：

@@ -185,11 +185,11 @@ FEATURE_FORK_SUBAGENT=1 bun run dev

 | 文件 | 行数 | 职责 |
 |------|------|------|
-| `packages/builtin-tools/src/tools/AgentTool/forkSubagent.ts` | ~210 | 核心定义 + 消息构建 + 递归防护 |
-| `packages/builtin-tools/src/tools/AgentTool/AgentTool.tsx` | — | Fork 路由 + 强制异步 |
-| `packages/builtin-tools/src/tools/AgentTool/prompt.ts` | — | "When to Fork" 提示词段落 |
-| `packages/builtin-tools/src/tools/AgentTool/runAgent.ts` | — | useExactTools 路径 |
-| `packages/builtin-tools/src/tools/AgentTool/resumeAgent.ts` | — | Fork agent 恢复 |
+| `src/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） |
--- a/docs/features/kairos.md
+++ b/docs/features/kairos.md
@@ -1,7 +1,7 @@
 # KAIROS — 常驻助手模式

 > Feature Flag: `FEATURE_KAIROS=1`（及子 Feature）
-> 实现状态：核心框架完整，部分子模块为 stub；proactive/sleep 节奏控制已可用
+> 实现状态：核心框架完整，部分子模块为 stub
 > 引用数：154（全库最大）

 ## 一、功能概述
@@ -34,13 +34,13 @@ KAIROS 在系统提示中注入两大段落：

 ### 2.1 Brief 段落 (`getBriefSection`)

-文件：`src/constants/prompts.ts:847-858`
+文件：`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:864-918`
+文件：`src/constants/prompts.ts:860-914`

 当 `feature('PROACTIVE') || feature('KAIROS')` 且 `isProactiveActive()` 时注入。核心行为指令：

@@ -74,9 +74,8 @@ KAIROS 在系统提示中注入两大段落：

 SleepTool 是 KAIROS/Proactive 的节奏控制核心。工具描述让模型理解"休眠"概念：
 - 工具名：`Sleep`
- 功能：等待指定时间后响应 tick prompt；若队列出现新工作或 proactive 被关闭，会提前唤醒
+- 功能：等待指定时间后响应 tick prompt
 - 与 `<tick_tag>` 配合实现心跳式自主工作
- 远程控制 surfaces 可通过 `automation_state` 看到 `standby` / `sleeping` 两种状态

 ### 3.3 Bridge 集成

@@ -173,10 +172,8 @@ FEATURE_KAIROS=1 FEATURE_TOKEN_BUDGET=1 bun run dev
 | `src/assistant/AssistantSessionChooser.ts` | — | Session 选择 UI（stub） |
 | `src/tools/BriefTool/` | — | BriefTool 实现（stub） |
 | `src/tools/SleepTool/prompt.ts` | ~30 | SleepTool 工具提示 |
-| `src/tools/SleepTool/SleepTool.ts` | ~200 | 休眠/唤醒与 automation metadata |
 | `src/services/mcp/channelNotification.ts` | 5 | 频道消息接入（stub） |
 | `src/memdir/memdir.ts` | — | 记忆目录管理（stub） |
-| `src/constants/prompts.ts:557,847-918` | 72 | 系统提示注入 |
+| `src/constants/prompts.ts:552-554,843-914` | 72 | 系统提示注入 |
 | `src/components/tasks/src/tasks/DreamTask/` | 3 | Dream 任务（stub） |
-| `src/proactive/index.ts` | — | Proactive 核心（KAIROS 共享） |
-| `src/utils/sessionState.ts` | — | 向 bridge/CCR 暴露 automation 状态 |
+| `src/proactive/index.ts` | — | Proactive 核心（stub，KAIROS 共享） |
--- a/docs/features/lan-pipes-implementation.md
+++ b/docs/features/lan-pipes-implementation.md
@@ -281,7 +281,7 @@ CLI-B (192.168.50.27) 心跳循环

 ## SendMessageTool TCP 支持

-`packages/builtin-tools/src/tools/SendMessageTool/SendMessageTool.ts`
+`src/tools/SendMessageTool/SendMessageTool.ts`

 - `to` 字段支持 `tcp:host:port` 格式
 - `checkPermissions`：`tcp:` scheme 返回 `behavior: 'ask'`，`classifierApprovable: false`
--- a/docs/features/langfuse-monitoring.md
+++ b/docs/features/langfuse-monitoring.md
@@ -202,4 +202,4 @@ docker run -d \
 | `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 创建 |
+| `src/tools/AgentTool/runAgent.ts` | 子 Agent Trace 创建 |
--- a/docs/features/mcp-skills.md
+++ b/docs/features/mcp-skills.md
@@ -41,7 +41,7 @@ getMcpSkillCommands() 过滤 → SkillTool 调用

 ### 2.2 技能筛选

-文件：`src/commands.ts:604-616`
+文件：`src/commands.ts:547-558`

 `getMcpSkillCommands(mcpCommands)` 过滤条件：

@@ -54,7 +54,7 @@ feature('MCP_SKILLS')                  // feature flag 必须开启

 ### 2.3 条件加载

-文件：`src/services/mcp/client.ts:129-133`
+文件：`src/services/mcp/client.ts:117-121`

 `fetchMcpSkillsForClient` 通过 `require()` 条件加载，feature flag 关闭时不加载任何模块：

@@ -79,8 +79,8 @@ const fetchMcpSkillsForClient = feature('MCP_SKILLS')

 | 文件 | 行 | 说明 |
 |------|------|------|
-| `src/commands.ts` | 604-616, 620-633 | 命令过滤和 SkillTool 命令收集 |
-| `src/services/mcp/client.ts` | 129-133, 1394, 1672, 2176 | 技能获取、缓存清除、连接时获取 |
+| `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 变化） |

 ## 三、关键设计决策
--- a/docs/features/pipes-and-lan.md
+++ b/docs/features/pipes-and-lan.md
@@ -145,8 +145,8 @@ M 键（或 ← / →）用于在两种路由模式之间切换，**无需展开

 ```
 /pipes                    — 显示所有实例 + 切换选择面板
-/pipes select &lt;name&gt;      — 选中某实例（消息会广播到它）
-/pipes deselect &lt;name&gt;    — 取消选中
+/pipes select <name>      — 选中某实例（消息会广播到它）
+/pipes deselect <name>    — 取消选中
 /pipes all                — 全选
 /pipes none               — 全部取消
 ```
@@ -169,7 +169,7 @@ LAN Peers:
 Selected: cli-da029538
 ```

-### /attach &lt;name&gt;
+### /attach <name>

 手动 attach 到一个实例，使其成为你的 slave。

@@ -179,7 +179,7 @@ Selected: cli-da029538

 attach 后，对方变为 slave，你变为 master。可以向它发送 prompt。通常不需要手动 attach——heartbeat 会自动发现并连接。

-### /detach &lt;name&gt;
+### /detach <name>

 断开与某个 slave 的连接。

@@ -187,7 +187,7 @@ attach 后，对方变为 slave，你变为 master。可以向它发送 prompt
 /detach cli-04d67950
 ```

-### /send &lt;name&gt; &lt;message&gt;
+### /send <name> <message>

 向指定 pipe 发送消息（不依赖选择状态，直接指定目标）。

@@ -318,7 +318,7 @@ sub 角色:
 | `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: 支持） |
+| `src/tools/SendMessageTool/SendMessageTool.ts` | AI 发消息工具（含 tcp: 支持） |

 ## 后续优化方向

--- a/docs/features/proactive.md
+++ b/docs/features/proactive.md
@@ -1,7 +1,7 @@
 # PROACTIVE — 主动模式

 > Feature Flag: `FEATURE_PROACTIVE=1`（与 `FEATURE_KAIROS=1` 共享功能）
-> 实现状态：核心循环与 SleepTool 已落地，部分外围文档仍在补齐
+> 实现状态：核心模块全部 Stub，布线完整
 > 引用数：37

 ## 一、功能概述
@@ -21,13 +21,13 @@ PROACTIVE 实现 Tick 驱动的自主代理。CLI 在用户不输入时也能持

 | 模块 | 文件 | 状态 | 说明 |
 |------|------|------|------|
-| 核心逻辑 | `src/proactive/index.ts` | **已实现** | `activateProactive()`、`deactivateProactive()`、`pause/resume`、`nextTickAt` 调度状态 |
+| 核心逻辑 | `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 驱动、standby/sleeping 状态、页脚与 bridge automation metadata 上报 |
-| 系统提示 | `src/constants/prompts.ts:864-918` | **完整** | 自主工作行为指令（~55 行详细 prompt） |
-| 远控状态镜像 | `src/utils/sessionState.ts` | **已实现** | 向 remote-control/CCR 暴露 `automation_state` 元数据 |
+| REPL 集成 | `src/screens/REPL.tsx` | **布线** | tick 驱动逻辑、占位符、页脚 UI |
+| 系统提示 | `src/constants/prompts.ts:860-914` | **完整** | 自主工作行为指令（~55 行详细 prompt） |
+| 会话存储 | `src/utils/sessionStorage.ts:4892-4912` | **布线** | tick 消息注入对话流 |

 ### 2.2 系统提示内容

@@ -46,7 +46,7 @@ PROACTIVE 实现 Tick 驱动的自主代理。CLI 在用户不输入时也能持
 ### 2.3 数据流

 ```
-activateProactive()
+activateProactive() [需要实现]
      │
      ▼
 Tick 调度器启动
@@ -62,22 +62,20 @@ Tick 调度器启动
      └── 无事可做 → 必须调用 SleepTool
      │
      ▼
-SleepTool 等待
-      │
-      ├── 用户插入新工作 / 队列中有命令 → 立即唤醒
-      ├── proactive 被关闭 → 立即中断
-      └── 进入休眠时向远端 surfaces 上报 `automation_state = sleeping`
+SleepTool 等待 [需要实现]
      │
      ▼
 下一个 tick 到达
 ```

-## 三、当前行为补充
+## 三、需要补全的内容

- `standby`：proactive 已开启，当前没有执行中的 turn，且已调度下一个 tick。
- `sleeping`：模型显式调用 `SleepTool` 进入等待窗口。
- remote-control/CCR 通过 `external_metadata.automation_state` 接收这两个状态，用于 Web UI 的 Autopilot 状态显示。
- `SleepTool` 现在不是纯定时器；它会在共享命令队列出现新工作时提前醒来。
+| 优先级 | 模块 | 工作量 | 说明 |
+|--------|------|--------|------|
+| 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 引用但不存在） |

 ## 四、关键设计决策

@@ -103,11 +101,9 @@ FEATURE_PROACTIVE=1 FEATURE_KAIROS=1 FEATURE_KAIROS_BRIEF=1 bun run dev

 | 文件 | 职责 |
 |------|------|
-| `src/proactive/index.ts` | 核心逻辑与 next-tick 状态 |
+| `src/proactive/index.ts` | 核心逻辑（stub） |
 | `src/tools/SleepTool/prompt.ts` | SleepTool 工具提示 |
-| `src/tools/SleepTool/SleepTool.ts` | 休眠/唤醒执行逻辑 |
-| `src/constants/prompts.ts:864-918` | 自主工作系统提示 |
-| `src/screens/REPL.tsx` | REPL tick 集成与 automation 状态上报 |
+| `src/constants/prompts.ts:860-914` | 自主工作系统提示 |
+| `src/screens/REPL.tsx` | REPL tick 集成 |
 | `src/utils/sessionStorage.ts:4892-4912` | Tick 消息注入 |
-| `src/utils/sessionState.ts` | bridge/CCR metadata 镜像 |
 | `src/components/PromptInput/PromptInputFooterLeftSide.tsx` | 页脚 UI 状态 |
--- a/docs/features/remote-control-self-hosting.md
+++ b/docs/features/remote-control-self-hosting.md
@@ -13,22 +13,17 @@
 ┌──────────────────┐   HTTP/SSE        │  │ In-Memory    │    │
 │  Web UI 控制面板  │ ◄─────────────── │  │ Store        │    │
 │  (/code/*)       │                   │  └──────────────┘    │
-│  (React + Vite)  │                   │  ┌──────────────┐    │
-└──────────────────┘                   │  │ JWT Auth     │    │
+└──────────────────┘                   │  ┌──────────────┐    │
+                                       │  │ 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 事件

 ## 前置条件

@@ -104,8 +99,6 @@ docker compose up -d
 | `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）

@@ -145,19 +138,13 @@ bun run dist/cli.js
 /remote-control
 ```

-环境型 Remote Control（例如 `claude remote-control` 子命令）会向 RCS 注册环境，注册成功后在终端显示连接 URL：
+CLI 会向 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 的环境列表中。
+同时支持 QR 码扫码打开。该 URL 即 Web UI 控制面板入口，在浏览器中打开即可远程操控当前会话。

 若已连接，再次执行 `/remote-control` 会显示对话框，包含以下选项：
 - **Disconnect this session** — 断开远程连接
@@ -176,74 +163,15 @@ claude bridge

 ## Web UI 控制面板

-通过 `/remote-control` 命令获取 URL 后，在浏览器打开即可使用。
+通过 `/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 文档](./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 区分。
-
 ## 工作流程详解

 ```
@@ -281,7 +209,6 @@ ACP session 在 Web UI 中显示品牌色标签，与普通 Claude Code session
 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
@@ -291,13 +218,6 @@ ACP session 在 Web UI 中显示品牌色标签，与普通 Claude Code session

 ## 故障排查

-### Web UI 看不到当前 Autopilot 状态
-
- `standby`：proactive 已开启，正在等待下一个 tick
- `sleeping`：模型正在 `SleepTool` 等待窗口中
-
-这两个状态通过 worker `external_metadata.automation_state` 上报。如果页面只显示普通 working spinner，优先检查 CLI 和 RCS 之间的 worker metadata PUT 是否成功。
-
 ### CLI 无法连接

 ```
@@ -355,3 +275,4 @@ curl https://rcs.example.com/health
 | 依赖 | claude.ai 订阅 + OAuth | 仅需 API Key |

 自托管模式的核心优势是：设置 `CLAUDE_BRIDGE_BASE_URL` 后，代码自动调用 `isSelfHostedBridge()` 返回 `true`，跳过所有 GrowthBook 和订阅检查，无需 claude.ai 账户即可使用。
+
--- a/docs/features/ssh-remote.md
+++ b/docs/features/ssh-remote.md
@@ -1,426 +0,0 @@
-# SSH Remote — 远程主机运行 Claude Code
-
-## 概述
-
-SSH Remote 提供两种方式在远程 Linux 主机上运行 Claude Code：
-
-1. **SSH Remote 模块**（`ccb ssh <host>`）— 本地 REPL + 远程工具执行，自动部署二进制 + 认证隧道
-2. **直接 SSH 运行**（`ssh <host> -t ccb`）— 远程已安装 ccb，直接启动交互式会话
-
-## 架构
-
-### 方式一：SSH Remote 模块（完整模式）
-
-适用场景：远端没有 API 凭据或没有安装 ccb。
-
-```
-┌──────────────── 本地 Windows/Mac/Linux ───────────┐
-│                                                    │
-│  ccb ssh <host> [dir]                              │
-│     │                                              │
-│     ├── 1. SSHProbe: 探测远端平台/架构/已有二进制    │
-│     ├── 2. SSHDeploy: 部署 dist/ 到远端             │
-│     ├── 3. SSHAuthProxy: 启动本地认证代理            │
-│     │      ├─ Unix Socket (Linux/Mac)              │
-│     │      └─ TCP 127.0.0.1:<port> (Windows)       │
-│     │                                              │
-│     └── 4. SSH -R 反向隧道 + 启动远端 CLI            │
-│            ssh -R <remote>:<local> <host> \         │
-│                ANTHROPIC_BASE_URL=... \             │
-│                ANTHROPIC_AUTH_NONCE=... \            │
-│                ccb --output-format stream-json      │
-│                                                    │
-│  ┌─────── 本地 REPL (Ink TUI) ───────┐             │
-│  │ 用户输入 → NDJSON → SSH stdin     │             │
-│  │ SSH stdout → NDJSON → 渲染消息    │             │
-│  │ 工具权限请求 → 本地审批 → 回传    │             │
-│  └────────────────────────────────────┘             │
-└────────────────────────────────────────────────────┘
-                        │
-                        │ SSH 连接 (加密通道)
-                        │
-┌───────────────── 远端 Linux ──────────────────────┐
-│                                                    │
-│  ccb (自动部署或已存在)                              │
-│     ├── --output-format stream-json                │
-│     ├── --input-format stream-json                 │
-│     ├── --verbose -p                               │
-│     │                                              │
-│     ├── API 请求 → ANTHROPIC_BASE_URL              │
-│     │   → SSH 反向隧道 → 本地 AuthProxy             │
-│     │   → 注入真实凭据 → api.anthropic.com          │
-│     │                                              │
-│     └── 工具执行 (Bash/Read/Write/...)              │
-│         直接在远端文件系统上操作                      │
-└────────────────────────────────────────────────────┘
-```
-
-### 方式二：直接 SSH 运行（简单模式）
-
-适用场景：远端已安装 ccb 且已有 API 凭据（订阅或 API Key）。
-
-```
-┌─────── 本地终端 ───────┐          ┌──────── 远端 Linux ────────┐
-│                         │   SSH    │                             │
-│  ssh <host> -t ccb      │ ──────→  │  ccb (全局安装)              │
-│                         │          │    ├── 使用远端自身凭据       │
-│  终端直接显示远端 TUI    │  ←────── │    ├── 远端文件系统操作       │
-│                         │   TTY    │    └── API 直连 Anthropic    │
-└─────────────────────────┘          └─────────────────────────────┘
-```
-
-### 适用场景对比
-
-| | SSH Remote 模块 | 直接 SSH 运行 |
-|---|---|---|
-| 远端需要安装 ccb | 不需要（自动部署） | 需要 |
-| 远端需要 API 凭据 | 不需要（本地隧道） | 需要 |
-| 本地需要安装 ccb | 需要 | 不需要（任何终端） |
-| 斜杠命令 | 本地处理 | 远端处理 |
-| 网络延迟敏感 | 高（NDJSON 双向） | 低（仅 TTY） |
-| 推荐场景 | 远端无凭据/无安装 | 远端已配置完整 |
-
---
-
-## 前置准备：SSH 密钥配置
-
-两种方式都依赖 SSH 免密连接。以下是完整的密钥配置步骤。
-
-### 1. 生成 SSH 密钥对（本地）
-
-```bash
-# 生成 Ed25519 密钥（推荐）
-ssh-keygen -t ed25519 -C "your-email@example.com" -f ~/.ssh/id_remote
-
-# 或 RSA 4096 位
-ssh-keygen -t rsa -b 4096 -C "your-email@example.com" -f ~/.ssh/id_remote
-```
-
-生成两个文件：
- `~/.ssh/id_remote` — 私钥（不可泄露）
- `~/.ssh/id_remote.pub` — 公钥（部署到远端）
-
-### 2. 将公钥部署到远端
-
-```bash
-# 方式 A：ssh-copy-id（推荐）
-ssh-copy-id -i ~/.ssh/id_remote.pub user@remote-host
-
-# 方式 B：手动复制
-cat ~/.ssh/id_remote.pub | ssh user@remote-host "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"
-```
-
-### 3. 配置 SSH Config（本地）
-
-编辑 `~/.ssh/config`（不存在则创建）：
-
-```
-Host my-server
-    HostName 192.168.1.100       # 远端 IP 或域名
-    User root                     # 远端用户名
-    IdentityFile ~/.ssh/id_remote # 私钥路径
-    ServerAliveInterval 60        # 防止连接超时断开
-    ServerAliveCountMax 3
-```
-
-配置后可直接用别名连接：
-
-```bash
-ssh my-server          # 等同于 ssh -i ~/.ssh/id_remote root@192.168.1.100
-```
-
-### 4. 文件权限设置
-
-#### Linux / macOS
-
-```bash
-chmod 700 ~/.ssh
-chmod 600 ~/.ssh/config
-chmod 600 ~/.ssh/id_remote
-chmod 644 ~/.ssh/id_remote.pub
-```
-
-#### Windows（OpenSSH 强制 ACL 检查）
-
-```powershell
-# 重置 .ssh 目录权限：仅允许当前用户 + SYSTEM
-icacls "$env:USERPROFILE\.ssh" /inheritance:r /grant:r "$($env:USERNAME):(OI)(CI)F" /grant "SYSTEM:(OI)(CI)F"
-
-# 修复 config 文件权限
-icacls "$env:USERPROFILE\.ssh\config" /inheritance:r /grant:r "$($env:USERNAME):F" /grant "SYSTEM:F"
-
-# 修复私钥权限
-icacls "$env:USERPROFILE\.ssh\id_remote" /inheritance:r /grant:r "$($env:USERNAME):F" /grant "SYSTEM:F"
-```
-
-> **Windows 常见错误**：如果 `icacls` 显示 `UNKNOWN\UNKNOWN` ACL 条目，需要先移除再重新授权。权限错误会导致 SSH 拒绝使用密钥。
-
-### 5. 验证免密连接
-
-```bash
-ssh my-server "echo 'SSH connection OK'"
-# 应直接输出 "SSH connection OK"，不要求输入密码
-```
-
---
-
-## 使用方式
-
-### 方式一：SSH Remote 模块
-
-```bash
-# 基本用法 — 自动探测、部署、启动
-ccb ssh user@remote-host
-
-# 使用 SSH Config 别名
-ccb ssh my-server
-
-# 指定远端工作目录
-ccb ssh my-server /home/user/project
-
-# 使用自定义远端二进制（跳过探测/部署）
-ccb ssh my-server --remote-bin "bun /opt/ccb/dist/cli.js"
-
-# 权限控制
-ccb ssh my-server --permission-mode auto
-ccb ssh my-server --dangerously-skip-permissions
-
-# 恢复远端会话
-ccb ssh my-server --continue
-ccb ssh my-server --resume <session-uuid>
-
-# 选择模型
-ccb ssh my-server --model claude-sonnet-4-6-20250514
-
-# 本地测试模式（不连接远端，测试 auth proxy 管道）
-ccb ssh localhost --local
-```
-
-### 方式二：直接 SSH 运行
-
-```bash
-# 启动交互式会话
-ssh my-server -t ccb
-
-# 指定工作目录
-ssh my-server -t "ccb --cwd /home/user/project"
-
-# 使用特定模型
-ssh my-server -t "ccb --model claude-sonnet-4-6-20250514"
-```
-
---
-
-## 构建与部署
-
-### 构建产物
-
-```bash
-# 安装依赖
-bun install
-
-# 构建（输出到 dist/）
-bun run build
-```
-
-产物说明：
-
-| 文件 | 说明 |
-|------|------|
-| `dist/cli.js` | Bun 入口（`#!/usr/bin/env bun`） |
-| `dist/cli-node.js` | Node.js 入口（`#!/usr/bin/env node` → `import ./cli.js`） |
-| `dist/cli-bun.js` | Bun 专用入口 |
-| `dist/chunk-*.js` | 代码分割 chunk 文件（约 668 个） |
-
-### 运行方式
-
-```bash
-# 方式 A：通过 bun 直接运行（开发/调试）
-bun run dev
-
-# 方式 B：运行构建产物（bun 运行时）
-bun dist/cli.js
-
-# 方式 C：运行构建产物（node 运行时）
-node dist/cli-node.js
-
-# 方式 D：全局安装后使用命令名
-ccb
-```
-
-### 全局安装
-
-在项目根目录执行：
-
-```bash
-# bun 全局安装（推荐）
-bun install -g .
-
-# 创建的命令：
-#   ccb            → dist/cli-node.js
-#   ccb-bun        → dist/cli-bun.js
-#   claude-code-best → dist/cli-node.js
-
-# 安装位置：~/.bun/bin/ccb
-```
-
-或使用 npm：
-
-```bash
-npm install -g .
-```
-
-验证：
-
-```bash
-ccb --version
-# → x.x.x (Claude Code)
-```
-
-### 远端部署（全流程）
-
-```bash
-# 1. 登录远端
-ssh my-server
-
-# 2. 克隆或同步项目代码
-git clone <repo-url> ~/ccb-project
-cd ~/ccb-project
-
-# 3. 安装运行时（如果没有 bun）
-curl -fsSL https://bun.sh/install | bash
-source ~/.bashrc
-
-# 4. 安装依赖 + 构建
-bun install
-bun run build
-
-# 5. 全局安装
-bun install -g .
-
-# 6. 确保非交互式 SSH 可访问 ccb 命令
-#    bun install -g 安装到 ~/.bun/bin/，但非交互式 SSH 不加载 .bashrc，
-#    所以 PATH 中不包含 ~/.bun/bin/
-#    解决方式（任选其一）：
-
-# 方式 A：符号链接到系统 PATH（推荐）
-ln -sf ~/.bun/bin/ccb /usr/local/bin/ccb
-
-# 方式 B：添加到 /etc/profile.d/（所有用户生效）
-echo 'export PATH="$HOME/.bun/bin:$PATH"' > /etc/profile.d/bun-path.sh
-
-# 方式 C：添加到 ~/.bash_profile（当前用户，ssh -t 时生效）
-echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.bash_profile
-
-# 7. 验证
-ccb --version
-
-# 8. 从本地测试
-# （在本地终端）
-ssh my-server -t ccb
-```
-
-### SSH Remote 自动部署
-
-使用 `ccb ssh <host>` 时，模块自动处理：
-
-1. **SSHProbe** 探测远端 `~/.local/bin/claude` 或 `command -v claude`
-2. 若二进制不存在或版本不匹配，**SSHDeploy** 通过 `scp` 传输 `dist/` 目录
-3. 在远端创建 wrapper 脚本（`~/.local/bin/claude`）
-4. 无需手动安装
-
---
-
-## 模块结构
-
-```
-src/ssh/
-├── createSSHSession.ts     — 会话工厂：编排 probe → deploy → proxy → spawn
-├── SSHSessionManager.ts    — 双向 NDJSON 通信管理 + 权限转发 + 重连
-├── SSHAuthProxy.ts         — 本地认证代理（API 凭据隧道）
-├── SSHProbe.ts             — 远端主机探测（平台/架构/已有二进制）
-├── SSHDeploy.ts            — 远端二进制部署（scp + wrapper 脚本）
-└── __tests__/
-    └── SSHSessionManager.test.ts  — 17 个单元测试
-```
-
-## 关键技术细节
-
-### 认证隧道
-
- **AuthProxy** 在本地监听（Unix socket 或 TCP），接收远端 CLI 的 API 请求
- 通过 SSH `-R` 反向端口转发隧道到远端
- AuthProxy 注入本地真实凭据（API key 或 OAuth token），转发到 `api.anthropic.com`
- `ANTHROPIC_AUTH_NONCE` header 防止未授权访问（nonce 通过环境变量传递给远端 CLI，远端 CLI 在每个 API 请求中携带此 header）
-
-### waitForInit vs 存活检查
-
- **标准模式**：`waitForInit` 等待远端 CLI 发送 `{type:'system', subtype:'init'}` JSON 消息
- **`--remote-bin` 模式**：跳过 `waitForInit`（print+stream-json 模式下 init 只在首次查询后发送），改用 3 秒进程存活检查
-
-### 重连机制
-
- `SSHSessionManager` 检测 SSH 连接断开后自动重连
- 重连时在远端 CLI 命令中追加 `--continue` 恢复会话
- 指数退避重试（最多 5 次，间隔 1s → 2s → 4s → 8s → 16s）
-
-## Feature Flag
-
-SSH Remote 功能受 `SSH_REMOTE` feature flag 控制：
-
- **Dev 模式**：默认启用
- **Build 模式**：需在 `build.ts` 的 `DEFAULT_BUILD_FEATURES` 中添加 `'SSH_REMOTE'`
- **运行时**：`FEATURE_SSH_REMOTE=1` 环境变量
-
---
-
-## 常见问题
-
-### `ccb: command not found`（SSH 远程执行时）
-
-非交互式 SSH 不加载 `.bashrc`，`~/.bun/bin` 不在 PATH 中。
-
-```bash
-# 解决：创建符号链接
-ln -sf ~/.bun/bin/ccb /usr/local/bin/ccb
-```
-
-### SSH 密钥被拒绝
-
-```
-Permission denied (publickey)
-```
-
-1. 确认公钥已添加到远端 `~/.ssh/authorized_keys`
-2. 确认本地私钥文件权限正确（`chmod 600`）
-3. 确认 `~/.ssh/config` 中 `IdentityFile` 路径正确
-4. Windows 用户检查 ACL 权限（见上方 Windows 权限设置）
-
-### SSH 连接超时
-
-```
-ssh: connect to host x.x.x.x port 22: Connection timed out
-```
-
-1. 确认远端 SSH 服务正在运行：`systemctl status sshd`
-2. 确认防火墙允许 22 端口
-3. 确认 IP 地址/域名正确
-4. 在 `~/.ssh/config` 中添加 `ConnectTimeout 10`
-
-### 403 Forbidden（SSH Remote 模块）
-
-AuthProxy 的 nonce 验证失败。确认：
-1. 远端 CLI 版本包含 nonce header 注入修复
-2. `ANTHROPIC_AUTH_NONCE` 环境变量正确传递到远端
-3. `src/services/api/client.ts` 中 `x-auth-nonce` header 已启用
-
-### 远端 CLI 启动后立即退出
-
-```
-Remote process exited immediately (code 1)
-```
-
-1. 确认远端 `bun` / `node` 运行时可用
-2. 手动在远端执行 `ccb --version` 验证安装
-3. 检查 `--remote-bin` 路径是否正确
-4. 查看 stderr 输出获取详细错误信息
--- a/docs/features/status-line.mdx
+++ b/docs/features/status-line.mdx
@@ -1,275 +0,0 @@
---
-title: "StatusLine 底部状态栏 - 自定义 shell 渲染管线"
-description: "从源码角度解析 Claude Code 底部状态栏：自定义 shell 脚本 + JSON stdin 协议、三种触发源（event / settings / time）、debounce + abort、信任与 hook 开关、以及本仓库 refreshInterval 缺失修复。"
-keywords: ["statusLine", "状态栏", "自定义提示符", "refreshInterval", "Hooks"]
---
-
-{/* 本章目标：完整讲清 StatusLine 的渲染管线、触发模型、协议契约与安全网关，并记录本仓库相对官方版本的已知缺口与修复 */}
-
-## 概述
-
-StatusLine 是 Claude Code REPL 底部显示的一行自定义文本，由**用户提供的 shell 命令**渲染。主进程把运行时状态（模型、工作目录、token、限流、会话元数据等）打包成 JSON 通过 stdin 喂给脚本，脚本在 stdout 输出一行字符串，Ink 侧以 ANSI 转义渲染到 footer。
-
-核心设计哲学：**语言无关 + 进程隔离 + Unix 管道**。用户可用 bash / python / node / 任意语言写脚本；脚本崩溃不影响主进程；输入输出都是纯文本，可以离线测试（`echo '{...}' | ./script.sh`）。
-
-## 配置
-
-`~/.claude/settings.json` 里添加 `statusLine` 字段：
-
-```json
-{
-  "statusLine": {
-    "type": "command",
-    "command": "bash ~/.claude/statusline-command.sh",
-    "refreshInterval": 1,
-    "padding": 0
-  }
-}
-```
-
-| 字段 | 类型 | 作用 |
-|------|------|------|
-| `type` | `"command"` | 目前仅支持 command 型 |
-| `command` | `string` | shell 命令字符串；主进程用系统 shell 解释执行 |
-| `refreshInterval` | `number` (秒) | 定时刷新周期；缺省/0 表示不定时刷新 |
-| `padding` | `number` | 左右 padding，单位为 Ink cell |
-
-Schema 定义在 `src/utils/settings/types.ts:550`（`statusLine` Zod object）。
-
-## 渲染管线（整体图）
-
-```
-┌─────────────────────── Ink 侧 ───────────────────────┐     ┌──────── 用户侧 ────────┐
-│                                                      │     │                        │
-│  buildStatusLineCommandInput()  ──┐                  │     │  ~/.claude/            │
-│     收集运行时状态                  │                  │     │   statusline-*.sh      │
-│                                   ▼                  │     │                        │
-│  executeStatusLineCommand()  ─── JSON via stdin ────────────►  jq '.model...'       │
-│     execCommandHook() 拉起 shell                     │     │  计算、格式化           │
-│                                   ▲                  │     │                        │
-│     stdout ◄──────────────────── 一行文本 ──────────────── printf '...'              │
-│                                   │                  │     │                        │
-│  setAppState({ statusLineText }) ─┘                  │     └────────────────────────┘
-│     zustand 存字段，组件 memo 订阅                    │
-│                                                      │
-│  <StatusLine /> → <Text><Ansi>{text}</Ansi></Text>   │
-│                                                      │
-└──────────────────────────────────────────────────────┘
-```
-
-## Input 协议：主进程 → 脚本
-
-`buildStatusLineCommandInput`（`src/components/StatusLine.tsx:53`）构造的 JSON 对象字段如下，**这是脚本可以 `jq` 读取的全部内容**：
-
-| 字段 | 来源 | 备注 |
-|------|------|------|
-| `session_id` | `getSessionId()` | UUID，用于脚本侧 per-session 状态隔离 |
-| `session_name` | `getCurrentSessionTitle(sessionId)` | 用户命名的会话标题（可选） |
-| `model.id` / `model.display_name` | `getRuntimeMainLoopModel()` | 运行时真实模型（经 permission mode 降级/200k 升级） |
-| `workspace.current_dir` / `project_dir` / `added_dirs` | `getCwd()` / `getOriginalCwd()` / permission context | current_dir 随 `cd` 变化 |
-| `version` | `MACRO.VERSION` | 构建注入，如 `2.1.888` |
-| `output_style.name` | `settings.outputStyle` | 缺省 `DEFAULT_OUTPUT_STYLE_NAME` |
-| `cost.total_cost_usd` / `total_duration_ms` / `total_api_duration_ms` / `total_lines_added` / `total_lines_removed` | `cost-tracker.js` 聚合 | 会话累计 |
-| `context_window.total_input_tokens` / `total_output_tokens` | 同上 | 累计 token |
-| `context_window.context_window_size` | `getContextWindowForModel()` | 模型上下文上限 |
-| `context_window.current_usage` | `getCurrentUsage(messages)` | **最新一次 assistant message 的 usage**；含 `input_tokens` / `cache_creation_input_tokens` / `cache_read_input_tokens` / `output_tokens` |
-| `context_window.used_percentage` / `remaining_percentage` | `calculateContextPercentages()` | 0-100 浮点 |
-| `exceeds_200k_tokens` | 检查最近 assistant message | 用于 1M 上下文模型的展示 |
-| `rate_limits.five_hour` / `seven_day` | `getRawUtilization()` | `{ used_percentage, resets_at }`，来自 Claude.ai 限流 API |
-| `vim.mode` | 启用 vim 模式时 | `INSERT` / `NORMAL` / ... |
-| `agent.name` | 主线程 agent 类型 | 子 agent fork 时非空 |
-| `remote.session_id` | Bridge / Remote Control 模式 | 远程会话 |
-| `worktree` | 当前 worktree 元信息 | `name` / `path` / `branch` / `original_cwd` / `original_branch` |
-
-类型签名目前在 `src/types/statusLine.ts` 是 `any` 的 stub（反编译残留），实际字段以上表为准。
-
-## Output 协议：脚本 → 主进程
-
-`executeStatusLineCommand`（`src/utils/hooks.ts:4752`）对脚本 stdout 做如下处理：
-
-1. `trim()` 首尾空白
-2. 按 `\n` 拆行，每行再 `trim()`
-3. 空行丢弃，剩余用 `\n` 重新拼接
-
-多行输出会被**保留为多行**（Ink 渲染时 `<Text>` 允许换行），但设计推荐**单行**——多行会挤占 REPL 高度，fullscreen 模式下可能挤掉 ScrollBox 行。
-
-状态码约定：
- `exit 0` + 有 stdout → 显示
- `exit 0` + 空 stdout → 清空 statusLine（显示为空）
- 非 0 → 忽略，保留上次内容；`logResult=true` 时 warn 级日志
- 超时（默认 5000ms） → 忽略
- 被 AbortController 取消 → 忽略
-
-ANSI 颜色可用，Ink 通过 `<Ansi>{text}</Ansi>` 组件解析 SGR 序列。
-
-## 三种触发源
-
-StatusLine 的重算由**三类事件**驱动，全部经同一个 debounce 队列：
-
-### 1. Event-driven（`src/components/StatusLine.tsx:275`）
-
-监听这些状态变化，触发 `scheduleUpdate()`：
-
- `lastAssistantMessageId` — 新助手回复出现
- `permissionMode` — `/mode` 切换权限模式
- `vimMode` — vim insert/normal 切换
- `mainLoopModel` — `/model` 切换
-
-### 2. Settings-driven（`src/components/StatusLine.tsx:294`）
-
-`settings.statusLine.command` 字符串变化时（热重载 settings.json），标记下一次结果 log 并立即 `doUpdate()`。
-
-### 3. Time-driven（`src/components/StatusLine.tsx:292`，本仓库补丁）
-
-读取 `settings.statusLine.refreshInterval`（秒），`setInterval` 每到点走一次 `scheduleUpdate()`。配置为 0 或缺省时不启定时器（零开销）。
-
-> **本仓库历史缺口**：反编译出的 `StatusLine.tsx` 最初没有 Time-driven 触发路径，`refreshInterval` 字段也不在 Zod schema 里。导致脚本里 TTL 倒计时、时钟类动态内容不会秒刷，只有助手回复出现时才重算。已在 2026-05-06 补齐，细节见下方"已知缺口与修复"。
-
-## Debounce + Abort
-
-三种触发源都走 `scheduleUpdate`（`src/components/StatusLine.tsx:259`）：
-
-```
-scheduleUpdate() → setTimeout(300ms) → doUpdate()
-                   │
-                   └─ 再次 schedule 会 clearTimeout 前次
-```
-
-300ms debounce 合并抖动事件（例如短时间连续切 vim/permission）。
-
-`doUpdate()` 里：
-
-```
-abortControllerRef.current?.abort()   // 取消上一次 in-flight shell
-controller = new AbortController()
-executeStatusLineCommand(..., controller.signal, ...)
-```
-
-**单飞（single-flight）语义**：任何新触发都会 abort 上一次未完成的 shell 调用，保证同一时刻最多一个子进程。这对 `refreshInterval: 1` 尤其关键——若脚本执行 > 1 秒，新 tick 到来时老进程被 kill，不会堆积。
-
-## 安全网关
-
-`executeStatusLineCommand`（`src/utils/hooks.ts:4752`）在执行前有**三层拦截**：
-
-1. `shouldDisableAllHooksIncludingManaged()` → managed settings 全局禁用 hooks 时直接返回
-2. `shouldSkipHookDueToTrust()` → **工作区未接受信任对话框时跳过**，避免打开未知仓库时执行任意 shell 命令（RCE 防护）
-3. `shouldAllowManagedHooksOnly()` → 非 managed settings 禁用 hooks 但 managed 未禁用时，只读取 policySettings 源的 statusLine
-
-组件侧配合（`src/components/StatusLine.tsx:318`）：未接受 trust 时在通知中心提示 `"statusline skipped · restart to fix"`。
-
-另外，`statusLineShouldDisplay`（`src/components/StatusLine.tsx:46`）在 **Kairos assistant mode** 下直接返回 false——因为那时 statusline 字段反映的是 REPL/daemon 进程状态，不是 agent 子进程在跑的东西，显示出来会误导用户。
-
-## 渲染细节
-
-### memo 隔离
-
-```tsx
-export const StatusLine = memo(StatusLineInner)
-```
-
-父组件 `PromptInputFooter` 每次 `setMessages` 都 rerender，但 `StatusLine` 的 props 只有 `lastAssistantMessageId` 会变，`memo` 阻断了无意义的重渲染。此前（未 memo 版本）一个 session 内大约 18 次冗余渲染。
-
-### 订阅粒度
-
-```tsx
-const statusLineText = useAppState(s => s.statusLineText)
-```
-
-`useAppState` 是选择器订阅，仅在 `statusLineText` 字段变化时触发 rerender；`doUpdate()` 里还做了幂等检查（`prev.statusLineText === text` 则直接返回原 state），**文本不变就不更新 zustand**，连一次 notify 都省掉。
-
-### Fullscreen 占位
-
-```tsx
-{statusLineText ? (
-  <Text dimColor wrap="truncate"><Ansi>{statusLineText}</Ansi></Text>
-) : isFullscreenEnvEnabled() ? (
-  <Text> </Text>  // 占位一行
-) : null}
-```
-
-Fullscreen 模式下 footer `flexShrink:0`，statusline 从 0 行变 1 行会挤掉 ScrollBox 一行内容导致抖动。首次脚本还没返回时，用空格文本占住一行高度，脚本返回后原位替换。
-
-## 内置 `/statusline` slash command
-
-`src/commands/statusline.tsx` 定义了一个 **prompt 型 command**，展开成自然语言指令喂给主 Agent：
-
-```
-Create an AgentTool with subagent_type "statusline-setup" and the prompt "<user-args>"
-```
-
-默认 prompt 是 `"Configure my statusLine from my shell PS1 configuration"`。主 Agent 收到后会调用内置子 agent `statusline-setup`。该子 agent 权限极小：
-
- **Tools**: 仅 `Read`、`Edit`
- **Allowed paths**: `Read(~/**)`、`Edit(~/.claude/settings.json)`
-
-也就是说它**不能 Write 新文件、不能跑 Bash**。典型工作是读用户的 shell 配置、读/改 `settings.json`、增量编辑已有的 statusline 脚本。
-
-## 编写自定义脚本的要点
-
-1. **脚本必须无状态** — 每次 tick 主进程 fork 一次新 shell，进程内变量不跨调用保留。需要跨 tick 的状态（上次时间戳、上次 token 数）用 `~/.claude/statusline-state/<hash>.state` 文件持久化。
-2. **按 `session_id` 哈希隔离状态文件** — 多会话同时开着时共享一个 state 文件会串。典型做法：`md5(session_id) | head -c 16` 作为文件名。
-3. **防御性读取** — state 文件可能损坏/被截断，按行 read + 字段校验（数字字段用 `case "$var" in ''|*[!0-9]*) invalid ;;`）。
-4. **`refreshInterval` 不等于"脚本秒级调用"** — tick 和事件触发（新消息、模式切换）都走同一 debounce 队列，脚本实际被调用的频率介于"每 N 秒"和"每 N+0.3 秒"之间；且 abort 机制下，上一次没跑完会被 kill。
-5. **执行时间预算** — 默认 5000ms 超时；为避免 `refreshInterval=1` 时频繁超时，脚本热路径应在 100ms 内完成。重计算（curl、git log 拉取）需缓存。
-6. **颜色用 ANSI 转义** — 不要依赖 TERM 环境变量；Ink 的 `<Ansi>` 组件独立解析 SGR。
-7. **不要输出多行** — 单行文本，否则挤占 REPL 布局。
-8. **处理 `current_usage` 为 null 的情况** — 首次响应之前 `context_window.current_usage` 可能为 null，脚本应有 fallback（如读 state 里上次命中率）。
-
-### 示例：Cache 命中率 + TTL 倒计时
-
-本仓库默认安装了一个示例脚本 `~/.claude/statusline-command.sh`（用户侧），输出格式 `<dir> | <model> | ctx:N% | Cache 97% 59:43`：
-
- **命中率** = `cache_read / (input + cache_creation + cache_read)`（取自 `current_usage`）
- **TTL** 从上次响应倒数 60 分钟，**只在 token signature 变化时重置时间戳**，避免秒级 tick 把 TTL 一直锁在 60:00
- **颜色分段** — 命中率 ≥50% 绿 / <50% 灰；TTL 0-20m 绿 / 20-40m 黄 / 40-55m 红 / 最后 5m 闪红 / 过期 `exp` 灰
- **Per-session state** — `~/.claude/statusline-state/<md5(session_id)[:16]>.state` 三行（signature、timestamp、hit），读前做 numeric 校验
- **Fallback** — `current_usage` 为 null 时读 state 显示上次命中率
-
-> 该脚本配合 `refreshInterval: 1` 即可秒刷 TTL，前提是 `refreshInterval` 触发路径已实现（见下节）。
-
-## 已知缺口与修复（本仓库）
-
-反编译版的 `StatusLine.tsx` 存在一处功能缺口：
-
-| 项 | 官方 Claude Code | 本仓库原始 | 本仓库现状 |
-|----|-----------------|-----------|-----------|
-| `refreshInterval` Zod 字段 | ✅ 有 | ❌ 无 | ✅ 已补 |
-| Time-driven `setInterval` 触发 | ✅ 有 | ❌ 无 | ✅ 已补 |
-| Event-driven 触发 | ✅ 有 | ✅ 有 | — |
-| Settings-driven 触发 | ✅ 有 | ✅ 有 | — |
-| Debounce + Abort | ✅ 有 | ✅ 有 | — |
-| Trust 网关 | ✅ 有 | ✅ 有 | — |
-
-修复（2026-05-06）：
-
-**1. `src/utils/settings/types.ts:554`** — statusLine schema 新增 `refreshInterval: z.number().optional()`，让字段进入类型系统而非被当未知键忽略。
-
-**2. `src/components/StatusLine.tsx:292`** — 新增 Time-driven useEffect：
-
-```tsx
-const refreshIntervalMs = (settings?.statusLine?.refreshInterval ?? 0) * 1000;
-useEffect(() => {
-  if (refreshIntervalMs <= 0) return;
-  const id = setInterval(() => scheduleUpdate(), refreshIntervalMs);
-  return () => clearInterval(id);
-}, [refreshIntervalMs, scheduleUpdate]);
-```
-
-关键点：
- 走 `scheduleUpdate`（非 `doUpdate`）复用 300ms debounce，interval + event 双触发不会双跑
- `refreshIntervalMs <= 0` 时不启定时器，对未启用该字段的用户零开销
- 依赖数组含 `refreshIntervalMs`，settings 热重载会自动清理旧 interval 重建新的
-
-**静默失效特征**：修复前 settings.json 写 `refreshInterval: 1` 无任何报错——JSON 解析通过，Zod schema 默认 strip 多余字段，官方文档又说支持这个字段，用户很容易以为生效了而没意识到 TTL/时钟类输出根本没秒刷。这是反编译版本的典型"文档与实现不一致"。
-
-## 相关源码
-
-| 文件 | 作用 |
-|------|------|
-| `src/components/StatusLine.tsx` | UI 组件、触发逻辑、buildStatusLineCommandInput |
-| `src/utils/hooks.ts:4752` | `executeStatusLineCommand`：shell 执行、输出处理、安全网关 |
-| `src/utils/settings/types.ts:550` | `statusLine` Zod schema |
-| `src/types/statusLine.ts` | `StatusLineCommandInput` 类型（当前为 stub） |
-| `src/commands/statusline.tsx` | `/statusline` slash command 定义 |
-| `src/state/AppStateStore.ts:95` | `statusLineText` 字段声明 |
-| `src/components/PromptInput/PromptInputFooter.tsx:159` | StatusLine 组件挂载点 |
--- a/docs/features/stub-recovery-design-1-4.md
+++ b/docs/features/stub-recovery-design-1-4.md
@@ -1,310 +0,0 @@
-# Stub 恢复设计 1-4
-
-> 日期：2026-04-12
-> 目标：基于当前代码边界，为下一阶段 4 个 stub/半 stub 命令面给出可实施的设计方案。
-> 排序原则：按建议实施顺序排序，不按问题严重性排序。
-
-## 设计原则
-
- 先做能独立闭环、收益明确、改动边界清晰的项。
- 大项拆成 `MVP` 和 `Phase 2+`，避免一次性掉进大范围恢复。
- 优先复用已有状态、传输层、日志与配置能力，不重造协议。
- 设计以当前仓库实际代码为准，不以旧文档的理想状态为准。
-
-## 1. `claude daemon status` / `claude daemon stop`
-
-### 现状
-
- `start` 路径已有完整 supervisor + worker 生命周期：
-  `src/daemon/main.ts`
-  `src/daemon/workerRegistry.ts`
- `status` / `stop` 目前只是占位输出：
-  `src/daemon/main.ts`
- `/remote-control-server` 有自己的命令内 UI 状态，但只维护当前进程内的 `daemonProcess`，并不适合作为跨进程 CLI 管理基础：
-  `src/commands/remoteControlServer/remoteControlServer.tsx`
-
-### 目标
-
- 让 `claude daemon status` 和 `claude daemon stop` 在另一个 CLI 进程中也能正确工作。
- 不依赖 TUI 内存态，不要求当前命令进程就是启动 daemon 的那个进程。
-
-### MVP 方案
-
- 新增 daemon 状态文件，例如：
-  `~/.claude/daemon/remote-control.json`
- `start` 时写入：
-  - supervisor pid
-  - cwd
-  - startedAt
-  - worker kinds
-  - 最近状态
- `status`：
-  - 读取状态文件
-  - 用现有进程探测能力验证 pid 是否存活
-  - 输出 `running / stopped / stale`
-  - stale 时自动清理状态文件
- `stop`：
-  - 读取 pid
-  - 发送 `SIGTERM`
-  - 等待退出
-  - 超时后 `SIGKILL`
-  - 清理状态文件
-
-### 代码范围
-
- 新增 `src/daemon/state.ts`
- 修改 `src/daemon/main.ts`
- 轻量修改 `src/commands/remoteControlServer/remoteControlServer.tsx`，让 UI 尽量读取同一份状态文件
-
-### 验证
-
-1. `claude daemon start`
-2. 新开终端执行 `claude daemon status`
-3. 执行 `claude daemon stop`
-4. 再次执行 `claude daemon status`，确认返回 `stopped` 或清晰的 `stale cleaned`
-
-### 风险
-
- Windows 信号模型和 Unix 不同，`stop` 需要超时兜底。
- 当前设计默认单 supervisor，不处理多实例并发。
-
-### 工作量判断
-
- 小
- 适合作为下一步的首选实现项
-
-## 2. `BG_SESSIONS`
-
-### 现状
-
- fast-path 已接好：
-  `src/entrypoints/cli.tsx`
- session registry 已有真实实现：
-  `src/utils/concurrentSessions.ts`
- `exit` 在 bg session 内已会 `tmux detach-client`：
-  `src/commands/exit/exit.tsx`
- 但 CLI handler 仍全空：
-  `src/cli/bg.ts`
- task summary 仍然是 stub：
-  `src/utils/taskSummary.ts`
-
-### 目标
-
- 先把 `ps` / `logs` / `kill` 做成真正有用的 session 管理命令。
- 不在第一阶段就强行补完 `attach` / `--bg`。
-
-### Phase 2A：MVP
-
- 实现 `ps`
-  - 从 registry 读取 live sessions
-  - 展示 pid、kind、sessionId、cwd、name、startedAt、bridgeSessionId
-  - 如果有 activity/status，则一并展示
- 实现 `logs`
-  - 支持按 `sessionId / pid / name` 查找
-  - 优先复用本地 transcript/log 读取能力
-  - 如果 registry 里存在 `logPath`，支持 tail 文件
- 实现 `kill`
-  - 解析目标 session
-  - 发退出信号
-  - 清理 stale registry
-
-### Phase 2B：后续
-
- 实现 `attach`
- 实现 `--bg`
- 实现 `taskSummary` 的中途状态更新
-
-### 为什么要拆
-
- 现有 registry 记录了 `pid / sessionId / name / logPath`
- 但没有可靠的 tmux attach target
- 所以 `attach` 和 `--bg` 不是简单补 handler，而是需要补启动/附着元数据设计
-
-### 代码范围
-
- 修改 `src/cli/bg.ts`
- 修改 `src/utils/concurrentSessions.ts` 以便后续 attach/--bg 扩展
- 修改 `src/utils/taskSummary.ts`
- 复用：
-  `src/utils/sessionStorage.ts`
-  `src/utils/udsClient.ts`
-
-### 验证
-
-1. `ps` 能列出 live sessions
-2. `logs <sessionId|pid|name>` 能输出对应日志
-3. `kill <sessionId|pid|name>` 能结束目标 session
-
-### 风险
-
- `attach` / `--bg` 第二阶段需要 tmux 元数据设计
- Windows 下 tmux 路径需要明确降级策略
-
-### 工作量判断
-
- `ps/logs/kill` 中等
- `attach/--bg` 明显更大，应分阶段
-
-## 3. `TEMPLATES`
-
-### 现状
-
- 命令入口只有 fast-path：
-  `src/entrypoints/cli.tsx`
- handler 是空的：
-  `src/cli/handlers/templateJobs.ts`
- `markdownConfigLoader` 已把 `templates` 纳入配置目录：
-  `src/utils/markdownConfigLoader.ts`
- `query / stopHooks` 已预留 job classifier 链路：
-  `src/query/stopHooks.ts`
- `jobs/classifier.ts` 仍是 stub：
-  `src/jobs/classifier.ts`
-
-### 目标
-
- 把 `new / list / reply` 做成可用的模板任务系统。
- 第一阶段不碰复杂的自动分类与自动执行。
-
-### MVP 方案
-
- 模板来源：
-  `.claude/templates/*.md`
- 模板格式：
-  复用现有 markdown + frontmatter 解析，不另外设计 DSL
- `list`
-  - 列出所有模板
-  - 显示模板名、description、路径
- `new <template> [args...]`
-  - 解析模板
-  - 在 `~/.claude/jobs/<job-id>/` 下创建 job 目录
-  - 写入 `template.md`、`input.txt`、`state.json`
-  - 返回 job id 与目录
- `reply <job-id> <text>`
-  - 将回复写入 `replies.jsonl` 或 `input.txt`
-  - 更新 `state.json`
-
-### Phase 2
-
- 恢复 `src/jobs/classifier.ts`
- 让带 `CLAUDE_JOB_DIR` 的 job session 在 turn 完成后自动更新 `state.json`
- 再决定是否补自动 job runner
-
-### 为什么要拆
-
- 当前证据表明这是“template job commands”，不是单纯模板列表
- 但自动 job 运行链路没有足够现成实现，先做文件系统 job lifecycle 更稳
-
-### 代码范围
-
- 修改 [src/cli/handlers/templateJobs.ts](</e:/Source_code/Claude-code-bast/src/cli/handlers/templateJobs.ts:1>)
- 新增 `src/jobs/state.ts`
- 新增 `src/jobs/templates.ts`
- Phase 2 再改 [src/jobs/classifier.ts](</e:/Source_code/Claude-code-bast/src/jobs/classifier.ts:1>)
-
-### 验证
-
-1. `list` 能列出 `.claude/templates`
-2. `new` 能创建 job 目录和状态文件
-3. `reply` 能更新 job 内容和状态
-4. Phase 2 再验证 classifier 写状态
-
-### 风险
-
- frontmatter schema 需要先定义最小字段集
- 一旦扩展到“自动运行 job”，范围会明显膨胀
-
-### 工作量判断
-
- MVP 中等
- 完整 job 系统偏大
-
-## 4. `assistant [sessionId]`
-
-### 现状
-
- attach 主流程其实已经存在：
-  [src/main.tsx](</e:/Source_code/Claude-code-bast/src/main.tsx:4708>)
- 远端 viewer 所需基础模块已存在：
-  [src/remote/RemoteSessionManager.ts](</e:/Source_code/Claude-code-bast/src/remote/RemoteSessionManager.ts:1>)
-  [src/hooks/useAssistantHistory.ts](</e:/Source_code/Claude-code-bast/src/hooks/useAssistantHistory.ts:1>)
-  [src/assistant/sessionHistory.ts](</e:/Source_code/Claude-code-bast/src/assistant/sessionHistory.ts:1>)
- 真正 stub 的主要是：
-  [src/assistant/sessionDiscovery.ts](</e:/Source_code/Claude-code-bast/src/assistant/sessionDiscovery.ts:1>)
-  [src/assistant/AssistantSessionChooser.ts](</e:/Source_code/Claude-code-bast/src/assistant/AssistantSessionChooser.ts:1>)
-  [src/commands/assistant/assistant.ts](</e:/Source_code/Claude-code-bast/src/commands/assistant/assistant.ts:7>)
-  [src/assistant/index.ts](</e:/Source_code/Claude-code-bast/src/assistant/index.ts:1>)
-
-### 目标
-
- 不一次性恢复整个 KAIROS 助手系统。
- 先做“明确 sessionId 的 viewer attach 可用”，再逐步补 discovery / chooser / install。
-
-### Phase 4A：MVP
-
- 只支持 `claude assistant <sessionId>`
- 对 `claude assistant` 无参数模式，先返回明确提示：
-  - 当前版本需要显式 `sessionId`
-  - discovery 尚未启用
- 这样可以直接复用现有 attach 分支，不必先恢复 chooser/install wizard
-
-### Phase 4B
-
- 恢复 `discoverAssistantSessions()`
- 数据来源优先复用现有 sessions / bridge / teleport API，而不是新协议
- 让 `claude assistant` 无参数时能拿到候选 session 列表
-
-### Phase 4C
-
- 恢复 `AssistantSessionChooser`
- 多 session 时可交互选择
-
-### Phase 4D
-
- 最后考虑 install wizard 辅助函数
- 这部分属于“没有 session 时如何引导”，不是 attach 核心路径
-
-### 为什么要拆
-
- attach 渲染层与远端消息通道大部分已经在
- 真正缺的是“如何发现目标 session”和“如何交互选择”
- 如果把 `src/assistant/index.ts` 的整套 KAIROS 正常模式也一起拉进来，范围会失控
-
-### 代码范围
-
- Phase 4A：
-  - [src/main.tsx](</e:/Source_code/Claude-code-bast/src/main.tsx:4708>)
-  - [src/commands/assistant/index.ts](</e:/Source_code/Claude-code-bast/src/commands/assistant/index.ts:1>)
- Phase 4B：
-  - [src/assistant/sessionDiscovery.ts](</e:/Source_code/Claude-code-bast/src/assistant/sessionDiscovery.ts:1>)
- Phase 4C：
-  - [src/assistant/AssistantSessionChooser.ts](</e:/Source_code/Claude-code-bast/src/assistant/AssistantSessionChooser.ts:1>)
- Phase 4D：
-  - [src/commands/assistant/assistant.ts](</e:/Source_code/Claude-code-bast/src/commands/assistant/assistant.ts:7>)
-
-### 验证
-
-1. `claude assistant <sessionId>` 能进入 remote viewer
-2. 历史懒加载工作正常
-3. 无参数模式先给出明确提示
-4. 后续阶段再分别验证 discovery / chooser / install
-
-### 风险
-
- 这是四项里范围最大的
- 一旦把 KAIROS 正常模式整体拉入，会从“viewer attach”膨胀成“完整 assistant mode 恢复”
-
-### 工作量判断
-
- Phase 4A 中等
- 4A-4D 全做完很大
-
-## 建议执行顺序
-
-1. `claude daemon status` / `claude daemon stop`
-2. `BG_SESSIONS` 先做 `ps/logs/kill`
-3. `TEMPLATES` 先做 job 文件系统 MVP
-4. `assistant [sessionId]` 先做显式 sessionId attach，再补 discovery/chooser/install
-
-## 简短结论
-
-这四项里，最适合立刻实现的是 `daemon status/stop`。`BG_SESSIONS` 和 `TEMPLATES` 适合按 MVP 先补 handler 与文件系统闭环。`assistant [sessionId]` 不能整块硬上，应该按“attach → discovery → chooser → install”拆开恢复。
--- a/docs/features/tier3-stubs.md
+++ b/docs/features/tier3-stubs.md
@@ -7,13 +7,50 @@

 | Feature | 引用 | 状态 | 类别 | 简要说明 |
 |---------|------|------|------|---------|
-| CHICAGO_MCP | 16 | 已实现 | 工具 | Computer Use + Chrome MCP 控制（build 默认启用） |
-| MONITOR_TOOL | 13 | 已实现 | 工具 | 后台监控工具，持续监视 shell 输出（build 默认启用） |
-| BG_SESSIONS | 11 | 部分实现 | 会话管理 | 后台会话注册/清理已实现，任务摘要是 stub（dev 默认启用） |
-| SHOT_STATS | 10 | 已实现 | 统计 | API 调用统计面板（build 默认启用） |
-| EXTRACT_MEMORIES | 7 | 已实现 | 记忆 | 自动记忆提取（build 默认启用，受 GrowthBook 门控） |
-| TEMPLATES | 6 | 部分实现 | 项目管理 | 项目/提示模板系统（dev 默认启用） |
-| LODESTONE | 6 | 已实现 | 深度链接 | URL 协议处理器（build 默认启用） |
+| CHICAGO_MCP | 16 | N/A | 内部基础设施 | Anthropic 内部 MCP 基础设施，非外部可用 |
+| 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+ 个）

@@ -29,9 +66,10 @@ BUILDING_CLAUDE_APPS, ANTI_DISTILLATION_CC, AGENT_TRIGGERS, ABLATION_BASELINE

 这些 feature 被列为 Tier 3 的原因：

-1. **已实现但影响范围小**（CHICAGO_MCP, LODESTONE, SHOT_STATS, EXTRACT_MEMORIES, MONITOR_TOOL）：已在 build/dev 默认启用，主要作为其他功能的基础设施
-2. **部分实现**（BG_SESSIONS, TEMPLATES）：核心注册已实现，但部分功能如任务摘要仍是 stub
-3. **辅助功能**（STREAMLINED_OUTPUT, HOOK_PROMPTS）：影响范围小
-4. **CCR 系列**：依赖远程控制基础设施，需要 BRIDGE_MODE 先完善
+1. **内部基础设施**（CHICAGO_MCP, LODESTONE）：Anthropic 内部使用，外部无法运行
+2. **纯 Stub 且引用低**（MONITOR_TOOL, BG_SESSIONS）：需要大量工作才能实现
+3. **实验性功能**（SHOT_STATS, EXTRACT_MEMORIES）：尚在概念阶段
+4. **辅助功能**（STREAMLINED_OUTPUT, HOOK_PROMPTS）：影响范围小
+5. **CCR 系列**：依赖远程控制基础设施，需要 BRIDGE_MODE 先完善

 如需深入了解某个 Tier 3 feature，可以在代码库中搜索 `feature('FEATURE_NAME')` 查看具体使用场景。
--- a/docs/features/token-budget.md
+++ b/docs/features/token-budget.md
@@ -191,7 +191,7 @@ FEATURE_TOKEN_BUDGET=1 bun run dev
 | `src/query/tokenBudget.ts` | 93 | 预算追踪器 + continue/stop 决策 |
 | `src/bootstrap/state.ts:724-743` | 20 | turn 级 token 快照状态 |
 | `src/constants/prompts.ts:538-551` | 14 | 系统提示注入 |
-| `src/utils/attachments.ts:3830-3844` | 17 | API attachment 附加 |
+| `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 |
--- a/docs/features/tree-sitter-bash.md
+++ b/docs/features/tree-sitter-bash.md
@@ -158,4 +158,4 @@ FEATURE_TREE_SITTER_BASH_SHADOW=1 bun run dev
 | `src/utils/bash/bashParser.ts` | 4437 | 纯 TS bash 解析器 |
 | `src/utils/bash/ast.ts` | 2680 | 安全分析器（核心） |
 | `src/utils/bash/treeSitterAnalysis.ts` | 507 | AST 分析辅助 |
-| `packages/builtin-tools/src/tools/BashTool/bashPermissions.ts` | ~140 | 权限集成 + Shadow 遥测 |
+| `src/tools/BashTool/bashPermissions.ts:1670-1810` | ~140 | 权限集成 + Shadow 遥测 |
--- a/docs/features/ultraplan.md
+++ b/docs/features/ultraplan.md
@@ -22,16 +22,16 @@ ULTRAPLAN 在用户输入中检测 "ultraplan" 关键字时，自动进入增强

 | 模块 | 文件 | 行数 | 状态 |
 |------|------|------|------|
-| 命令处理器 | `src/commands/ultraplan.tsx` | 525 | **完整** |
-| CCR 会话 | `src/utils/ultraplan/ccrSession.ts` | 349 | **完整** |
-| 关键字检测 | `src/utils/ultraplan/keyword.ts` | 127 | **完整** |
+| 命令处理器 | `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`（127 行）
+文件：`src/utils/ultraplan/keyword.ts`（128 行）

 `findUltraplanTriggerPositions(text)` 智能过滤：
 - 排除引号内的 "ultraplan"
@@ -41,7 +41,7 @@ ULTRAPLAN 在用户输入中检测 "ultraplan" 关键字时，自动进入增强

 ### 2.3 CCR 远程会话

-文件：`src/utils/ultraplan/ccrSession.ts`（349 行）
+文件：`src/utils/ultraplan/ccrSession.ts`（350 行）

 `ExitPlanModeScanner` 类实现完整的事件状态机：
 - `pollForApprovedExitPlanMode()` — 3 秒轮询间隔
@@ -99,9 +99,9 @@ FEATURE_ULTRAPLAN=1 bun run dev

 | 文件 | 行数 | 职责 |
 |------|------|------|
-| `src/commands/ultraplan.tsx` | 525 | 斜杠命令处理器 |
-| `src/utils/ultraplan/ccrSession.ts` | 349 | CCR 远程会话管理 |
-| `src/utils/ultraplan/keyword.ts` | 127 | 关键字检测和替换 |
+| `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` | — | 彩虹高亮 |
--- a/docs/features/voice-mode.md
+++ b/docs/features/voice-mode.md
@@ -1,32 +1,27 @@
 # VOICE_MODE — 语音输入

 > Feature Flag: `FEATURE_VOICE_MODE=1`
-> 实现状态：完整可用（双后端：Anthropic OAuth / 豆包 ASR）
+> 实现状态：完整可用（需要 Anthropic OAuth）
 > 引用数：46

 ## 一、功能概述

-VOICE_MODE 实现"按键说话"（Push-to-Talk）语音输入。用户按住空格键录音，音频流式传输到 STT 后端，实时转录显示在终端中。支持两个后端：
-
- **Anthropic STT（默认）**：通过 WebSocket 流式传输到 Nova 3 端点，需要 Anthropic OAuth
- **豆包 ASR（Doubao）**：通过 `doubaoime-asr` 包的 AsyncGenerator 协议流式识别，使用独立凭证文件，无需 Anthropic OAuth
+VOICE_MODE 实现"按键说话"（Push-to-Talk）语音输入。用户按住空格键录音，音频通过 WebSocket 流式传输到 Anthropic STT 端点（Nova 3），实时转录显示在终端中。

 ### 核心特性

 - **Push-to-Talk**：长按空格键录音，释放后自动发送
 - **流式转录**：录音过程中实时显示中间转录结果
 - **无缝集成**：转录文本直接作为用户消息提交到对话
- **双后端切换**：通过 `/voice` 命令参数选择 STT 后端，持久化到 settings.json

 ## 二、用户交互

 | 操作 | 行为 |
 |------|------|
 | 长按空格 | 开始录音，显示录音状态 |
-| 释放空格 | 停止录音，转录结果自动提交 |
-| `/voice` | 切换语音模式开关（默认使用 Anthropic 后端） |
-| `/voice doubao` | 启用语音模式并使用豆包 ASR 后端 |
-| `/voice anthropic` | 切换回 Anthropic STT 后端 |
+| 释放空格 | 停止录音，等待最终转录 |
+| 转录完成 | 自动插入到输入框并提交 |
+| `/voice` 命令 | 切换语音模式开关 |

 ### UI 反馈

@@ -40,37 +35,26 @@ VOICE_MODE 实现"按键说话"（Push-to-Talk）语音输入。用户按住空

 文件：`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. **Auth 检查**：`hasVoiceAuth()` — 需要 Anthropic OAuth token（非 API key）

 ### 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'` 设置类型定义 |
+| `src/hooks/useVoice.ts` | React hook 管理录音状态和 WebSocket 连接 |
+| `src/services/voiceStreamSTT.ts` | WebSocket 流式传输到 Anthropic STT |

 ### 3.3 数据流

-#### Anthropic 后端
-
 ```
 用户按下空格键
      │
@@ -95,108 +79,20 @@ 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())`）
+音频流通过 WebSocket 发送到 Anthropic 的 Nova 3 STT 模型。

 ## 四、关键设计决策

-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 后端
+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`，不触发任何模块加载

 ## 五、使用方式

@@ -204,60 +100,26 @@ const connectFn = isDoubaoProvider()
 # 启用 feature
 FEATURE_VOICE_MODE=1 bun run dev

-# 在 REPL 中使用 Anthropic 后端
+# 在 REPL 中使用
 # 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": "..."
-}
+# 2. 按住空格键说话
+# 3. 释放空格键等待转录
+# 4. 或使用 /voice 命令切换开关
 ```

 ## 六、外部依赖

-| 依赖 | 说明 | 适用后端 |
-|------|------|----------|
-| 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` | 豆包 |
+| 依赖 | 说明 |
+|------|------|
+| Anthropic OAuth | claude.ai 订阅登录，非 API key |
+| GrowthBook | `tengu_amber_quartz_disabled` 紧急关闭 |
+| macOS 原生音频 或 SoX | 音频录制 |
+| Nova 3 STT | 语音转文本模型 |

 ## 七、文件索引

-| 文件 | 职责 |
-|------|------|
-| `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` 类型定义 |
+| 文件 | 行数 | 职责 |
+|------|------|------|
+| `src/voice/voiceModeEnabled.ts` | 55 | 三层门控逻辑 |
+| `src/hooks/useVoice.ts` | — | React hook（录音状态 + WebSocket） |
+| `src/services/voiceStreamSTT.ts` | — | STT WebSocket 流式传输 |
--- a/docs/features/web-browser-tool.md
+++ b/docs/features/web-browser-tool.md
@@ -1,7 +1,7 @@
 # WEB_BROWSER_TOOL — 浏览器工具

 > Feature Flag: `FEATURE_WEB_BROWSER_TOOL=1`
-> 实现状态：核心工具已实现，面板为 Stub，布线完整
+> 实现状态：核心实现缺失，面板为 Stub，布线完整
 > 引用数：4

 ## 一、功能概述
@@ -14,8 +14,8 @@ WEB_BROWSER_TOOL 让模型可以启动浏览器实例、导航网页、与页面

 | 模块 | 文件 | 状态 |
 |------|------|------|
-| 浏览器面板 | `packages/builtin-tools/src/tools/WebBrowserTool/WebBrowserPanel.ts` | **Stub** — 返回 null |
-| 浏览器工具 | `packages/builtin-tools/src/tools/WebBrowserTool/WebBrowserTool.ts` | **已实现** |
+| 浏览器面板 | `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` 检测 |
@@ -44,8 +44,8 @@ WebBrowserPanel 在 REPL 侧边显示浏览器状态

 | 模块 | 工作量 | 说明 |
 |------|--------|------|
-| `WebBrowserTool.ts` | ✅ 已实现 | 工具 schema + Bun WebView API 执行 |
-| `WebBrowserPanel.tsx` | 中 | REPL 侧边栏浏览器状态面板（仍为 Stub） |
+| `WebBrowserTool.ts` | 大 | 工具 schema + Bun WebView API 执行 |
+| `WebBrowserPanel.tsx` | 中 | REPL 侧边栏浏览器状态面板 |

 ## 四、关键设计决策

@@ -63,7 +63,7 @@ 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/WebBrowserTool/WebBrowserPanel.ts` | 面板组件（stub） |
+| `src/tools/WebBrowserTool/WebBrowserTool.ts` | 工具实现（缺失） |
+| `src/screens/REPL.tsx:273,4582` | 面板渲染 |
 | `src/tools.ts:115-116` | 工具注册 |
--- a/docs/features/web-search-tool.md
+++ b/docs/features/web-search-tool.md
@@ -34,16 +34,16 @@ WebSearchTool.call()

 | 模块 | 文件 | 说明 |
 |------|------|------|
-| 工具入口 | `packages/builtin-tools/src/tools/WebSearchTool/WebSearchTool.ts` | `buildTool()` 定义：schema、权限、执行、输出格式化 |
-| 工具 prompt | `packages/builtin-tools/src/tools/WebSearchTool/prompt.ts` | 搜索工具的系统提示词 |
-| UI 渲染 | `packages/builtin-tools/src/tools/WebSearchTool/UI.tsx` | 搜索结果的终端渲染组件 |
-| 适配器接口 | `packages/builtin-tools/src/tools/WebSearchTool/adapters/types.ts` | `WebSearchAdapter` 接口、`SearchResult`/`SearchOptions`/`SearchProgress` 类型 |
-| 适配器工厂 | `packages/builtin-tools/src/tools/WebSearchTool/adapters/index.ts` | `createAdapter()` 工厂函数，选择后端 |
-| API 适配器 | `packages/builtin-tools/src/tools/WebSearchTool/adapters/apiAdapter.ts` | 封装原有 `queryModelWithStreaming` 逻辑，使用 server tool |
-| Bing 适配器 | `packages/builtin-tools/src/tools/WebSearchTool/adapters/bingAdapter.ts` | Bing HTML 抓取 + 正则解析 |
-| Brave 适配器 | `packages/builtin-tools/src/tools/WebSearchTool/adapters/braveAdapter.ts` | Brave LLM Context API 适配与结果映射 |
-| 单元测试 | `packages/builtin-tools/src/tools/WebSearchTool/__tests__/bingAdapter.test.ts`, `packages/builtin-tools/src/tools/WebSearchTool/__tests__/braveAdapter*.test.ts`, `packages/builtin-tools/src/tools/WebSearchTool/__tests__/adapterFactory.test.ts` | Bing / Brave 解析与工厂逻辑测试 |
-| 集成测试 | `packages/builtin-tools/src/tools/WebSearchTool/__tests__/bingAdapter.integration.ts`, `packages/builtin-tools/src/tools/WebSearchTool/__tests__/braveAdapter.integration.ts` | 真实网络请求验证 |
+| 工具入口 | `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 抓取 + 正则解析 |
+| Brave 适配器 | `src/tools/WebSearchTool/adapters/braveAdapter.ts` | Brave LLM Context API 适配与结果映射 |
+| 单元测试 | `src/tools/WebSearchTool/__tests__/bingAdapter.test.ts`, `src/tools/WebSearchTool/__tests__/braveAdapter*.test.ts`, `src/tools/WebSearchTool/__tests__/adapterFactory.test.ts` | Bing / Brave 解析与工厂逻辑测试 |
+| 集成测试 | `src/tools/WebSearchTool/__tests__/bingAdapter.integration.ts`, `src/tools/WebSearchTool/__tests__/braveAdapter.integration.ts` | 真实网络请求验证 |

 ### 2.3 数据流

@@ -176,13 +176,13 @@ interface SearchProgress {

 | 文件 | 职责 |
 |------|------|
-| `packages/builtin-tools/src/tools/WebSearchTool/WebSearchTool.ts` | 工具定义入口 |
-| `packages/builtin-tools/src/tools/WebSearchTool/prompt.ts` | 搜索工具 prompt |
-| `packages/builtin-tools/src/tools/WebSearchTool/UI.tsx` | 终端 UI 渲染 |
-| `packages/builtin-tools/src/tools/WebSearchTool/adapters/types.ts` | 适配器接口 |
-| `packages/builtin-tools/src/tools/WebSearchTool/adapters/index.ts` | 适配器工厂 |
-| `packages/builtin-tools/src/tools/WebSearchTool/adapters/apiAdapter.ts` | API 服务端搜索适配器 |
-| `packages/builtin-tools/src/tools/WebSearchTool/adapters/bingAdapter.ts` | Bing HTML 解析适配器 |
-| `packages/builtin-tools/src/tools/WebSearchTool/__tests__/bingAdapter.test.ts` | 单元测试 (32 cases) |
-| `packages/builtin-tools/src/tools/WebSearchTool/__tests__/bingAdapter.integration.ts` | 集成测试 |
+| `src/tools/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` | 工具注册 |
--- a/docs/features/workflow-scripts.md
+++ b/docs/features/workflow-scripts.md
@@ -14,17 +14,17 @@ WORKFLOW_SCRIPTS 实现基于文件的多步自动化工作流。用户可以定

 | 模块 | 文件 | 状态 |
 |------|------|------|
-| WorkflowTool | `packages/builtin-tools/src/tools/WorkflowTool/WorkflowTool.ts` | **部分实现** — tool schema + 渲染完整，call 返回运行时缺失提示 |
-| Workflow 权限 | `packages/builtin-tools/src/tools/WorkflowTool/WorkflowPermissionRequest.tsx` | **部分实现** — 权限请求组件 |
-| 常量 | `packages/builtin-tools/src/tools/WorkflowTool/constants.ts` | **实现** — 工具名 + 目录名 + 文件扩展名常量 |
-| 命令创建 | `packages/builtin-tools/src/tools/WorkflowTool/createWorkflowCommand.ts` | **实现** — 扫描 .claude/workflows/ 目录创建 Command 对象 |
-| 捆绑工作流 | `packages/builtin-tools/src/tools/WorkflowTool/bundled/index.ts` | **实现** — 内置工作流初始化 |
+| 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 工作流初始化 (行 131-134,235) |
-| 命令注册 | `src/commands.ts` | **布线** — `/workflows` 命令 (行 93-95,395,460) |
+| 工具注册 | `src/tools.ts` | **布线** — 包含 bundled 工作流初始化 |
+| 命令注册 | `src/commands.ts` | **布线** — `/workflows` 命令 |

 ### 2.2 预期数据流

@@ -69,9 +69,13 @@ steps:

 | 优先级 | 模块 | 工作量 | 说明 |
 |--------|------|--------|------|
-| 1 | `WorkflowTool.ts` call 方法 | 中 | 实际工作流执行逻辑（当前返回运行时缺失提示） |
-| 2 | `LocalWorkflowTask.ts` | 大 | 步骤协调、kill/skip/retry |
-| 3 | `WorkflowDetailDialog.ts` | 中 | 进度详情 UI |
+| 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` | 小 | 工具名常量 |

 ## 四、关键设计决策

@@ -91,12 +95,11 @@ FEATURE_WORKFLOW_SCRIPTS=1 bun run dev

 | 文件 | 职责 |
 |------|------|
-| `packages/builtin-tools/src/tools/WorkflowTool/WorkflowTool.ts` | 工具定义（部分实现） |
-| `packages/builtin-tools/src/tools/WorkflowTool/WorkflowPermissionRequest.tsx` | 权限请求组件 |
-| `packages/builtin-tools/src/tools/WorkflowTool/constants.ts` | 常量定义 |
-| `packages/builtin-tools/src/tools/WorkflowTool/createWorkflowCommand.ts` | 命令创建（已实现） |
-| `packages/builtin-tools/src/tools/WorkflowTool/bundled/index.ts` | 内置工作流初始化 |
+| `src/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:131-134,235` | 工具注册 |
-| `src/commands.ts:93-95,395,460` | 命令注册 |
+| `src/tools.ts:127-132` | 工具注册 |
+| `src/commands.ts:86-89` | 命令注册 |
--- a/docs/internals/agent-comm-fix-jira-tasks.md
+++ b/docs/internals/agent-comm-fix-jira-tasks.md
@@ -1,564 +0,0 @@
-# Agent 通讯修复 Jira Task
-
- 版本：v1.0
- 生成日期：2026-04-25
- 来源：由按文件执行清单、Claude 交叉验证意见整理合并
- 范围：ACP Agent / Bridge / Remote Control Server / REPL Hook 生命周期
- 使用方式：这是唯一执行任务文档；每个 `JIRA-*` 小节可直接拆成一个 Jira issue，字段保持统一，便于复制或二次导入。
-
---
-
-## 方案性质
-
-本文档是目标状态式执行方案，不是临时补丁清单。每张 ticket 必须交付明确的代码终态、测试覆盖和回归边界；不得只用局部 workaround 掩盖问题。
-
---
-
-## 执行总则
-
-1. 先边界安全，后内部优化：先修 WS 入站大小与输入校验，避免线上风险扩大。
-2. 单文件可回滚：每个文件内修改保持内聚，便于回滚与 bisect。
-3. 不改协议语义，只修实现缺陷：除 `resource_link` 表达形式统一外，不改变主流程契约。
-4. 每个文件必须有验收输出：要么测试用例，要么日志/指标验证。
-5. 发布前必须确认协议层行为无回归：`stopReason` 决策与 `sessionUpdate` 发送顺序保持稳定。
-
---
-
-## Epic
-
-### JIRA-EPIC-001：提升 Agent 通讯链路稳定性与边界安全
-
- Issue Type：Epic
- Priority：P0
- Owner：核心通讯 / 后端网关 / QA
- Scope：ACP Agent、ACP Bridge、Remote Control Server、REPL 初始化生命周期
- Goal：修复长会话资源泄漏、补齐 WebSocket 入站边界、统一 prompt 转换、收敛类型风险，并补充关键回归测试。
-
-#### Epic 验收标准
-
- `bun run typecheck` 0 error。
- P0 WebSocket 超大消息拒绝逻辑已实现并覆盖测试。
- ACP bridge abort listener 生命周期无累积。
- prompt 转换实现单源化。
- settings/defaultMode 能真实影响 ACP permission mode，且 `_meta.permissionMode` 保持最高优先级。
- REPL 目标 hook suppress 清理完成，timer cleanup 完整。
-
---
-
-## P0 Tickets
-
-### JIRA-001：为 session ingress WebSocket 补齐消息大小限制
-
- Issue Type：Bug
- Priority：P0
- Story Points：3
- Owner：后端/网关
- Files：
-  - `packages/remote-control-server/src/routes/v1/session-ingress.ts`
- 后续票：JIRA-008（同文件 P1 类型与 decode path 收尾）
-
-#### 参考代码位置
-
- `packages/remote-control-server/src/routes/v1/session-ingress.ts:100-106`
-
-#### 背景
-
-`session-ingress` 当前缺少 WebSocket message size limit。ACP 路由已有类似限制，两个入口边界不一致，可能导致大包占用内存或绕过入口保护。
-
-#### 实施要求
-
- 新增 `MAX_WS_MESSAGE_SIZE = 10 * 1024 * 1024`，与 ACP 路由的 10MB 上限保持一致。
- 在 `onMessage` decode 后优先检查 payload size。
- 超限时执行 `ws.close(1009, "message too large")`。
- 日志记录 `sessionId`、payload size、limit。
- 对 `string`、`ArrayBuffer`、`Uint8Array` 进行统一 decode 分流。
- 非支持类型直接拒绝并记录，不进入业务 handler。
-
-#### 验收标准
-
- 11MB payload 被 1009 close。
- 1KB 合法 payload 仍正常进入 handler。
- 非支持类型 payload 不进入 handler。
- 不改变 URL、auth、session 解析逻辑。
-
-#### 回归范围
-
- Remote Control Server session ingress WebSocket。
- 正常会话消息转发。
- WebSocket close code 行为。
-
-#### 风险等级
-
- 中。入口逻辑变更可能影响特殊客户端 payload 类型。
-
-#### 必须验证
-
- 在 `packages/remote-control-server/src/__tests__/routes.test.ts` 增加 session-ingress WebSocket 大包、小包、坏类型 payload 用例。
- 运行 `bun run typecheck`。
-
---
-
-### JIRA-002：修复 ACP bridge abort listener 生命周期泄漏
-
- Issue Type：Bug
- Priority：P0
- Story Points：3
- Owner：核心通讯
- Files：
-  - `src/services/acp/bridge.ts`
-
-#### 参考代码位置
-
- `src/services/acp/bridge.ts:576-585`
-
-#### 背景
-
-ACP bridge 的 `Promise.race` abort 分支注册 listener 后缺少完整 cleanup。长会话或高频 next 场景可能出现 listener 累积。
-
-#### 实施要求
-
- 将 abort race 改为可清理监听器写法。
- 注册 listener 后保留 handler 引用。
- `sdkMessages.next()` 先返回时必须 `removeEventListener`。
- abort、throw、return 等路径都在 `finally` 中清理。
- 不改变 `stopReason` 决策逻辑。
- 不改变 `sessionUpdate` 发送顺序。
-
-#### 验收标准
-
- 模拟 10k 次 next 且不 abort，listener 不增长。
- abort 场景仍返回 `cancelled`。
- 原有 streaming/session update 行为无回归。
-
-#### 回归范围
-
- ACP bridge streaming loop。
- 用户取消请求。
- SDK generator 异常路径。
-
-#### 风险等级
-
- 中。异步控制流变更需要覆盖取消与异常路径。
-
-#### 必须验证
-
- 新增 listener cleanup 单元测试。
- 运行 `bun run typecheck`。
-
---
-
-## P1 Tickets
-
-### JIRA-003：优化 ACP agent pending prompt 队列为 O(1) 出队
-
- Issue Type：Task
- Priority：P1
- Story Points：5
- Owner：核心通讯
- Files：
-  - `src/services/acp/agent.ts`
-
-#### 参考代码位置
-
- `src/services/acp/agent.ts:332-339`
-
-#### 背景
-
-当前 pending prompt 队列使用 `Map + sort` 获取下一项，排队量上升时会带来不必要的排序成本。
-
-#### 实施要求
-
- 改为 `queue: string[]` + `pendingMap: Map<string, PendingPrompt>` 组合。
- 入队执行 `queue.push(id)` 与 `pendingMap.set(id, prompt)`。
- 出队从队首惰性跳过已取消项。
- 取消只从 `pendingMap` 删除，不做数组中间删除。
- 保持现有取消语义和出队顺序。
-
-#### 验收标准
-
- 1000 pending prompt 场景下出队顺序正确。
- 已取消 prompt 不会被 resolve。
- 出队不再依赖全量 sort。
- 1000 排队场景下出队耗时低于旧实现；测试记录旧实现复杂度风险和新实现 O(1) 出队路径。
- 行为与旧实现兼容。
-
-#### 回归范围
-
- ACP prompt queue。
- 并发 prompt 请求。
- prompt cancel / resolve 边界。
-
-#### 风险等级
-
- 中。队列结构变更可能引入取消边界问题。
-
-#### 必须验证
-
- 新增 queue 顺序与取消测试。
- 对 1000 prompt 场景做性能断言或日志记录。
-
---
-
-### JIRA-004：接入真实 settings 读取并校验 ACP permission mode
-
- Issue Type：Bug
- Priority：P1
- Story Points：3
- Owner：核心通讯
- Files：
-  - `src/services/acp/agent.ts`
-
-#### 参考代码位置
-
- `src/services/acp/agent.ts:465-467`
-
-#### 背景
-
-`getSetting()` 当前未真正接入项目配置，导致默认 permission mode 配置无法按预期生效。
-
-#### 实施要求
-
- 接入项目现有 settings/config 读取逻辑。
- 仅接受合法 permission mode 枚举值。
- 非法值 fallback 到 `default`。
- `_meta.permissionMode` 继续保持最高优先级。
- 不改变外部协议字段。
-
-#### 验收标准
-
- settings/defaultMode 能影响默认 permission mode。
- `_meta.permissionMode` 能覆盖 settings。
- 非法 settings 值不会传播到运行时。
- 类型检查通过。
-
-#### 回归范围
-
- ACP agent session 初始化。
- 权限模式同步。
- 客户端 `_meta` 覆盖逻辑。
-
-#### 风险等级
-
- 中。配置优先级错误会影响权限行为。
-
-#### 必须验证
-
- 新增 defaultMode / `_meta.permissionMode` 优先级测试。
- 运行 `bun run typecheck`。
-
---
-
-### JIRA-005：单源化 ACP prompt 转换逻辑
-
- Issue Type：Refactor
- Priority：P1
- Story Points：5
- Owner：核心通讯
- Files：
-  - `src/services/acp/agent.ts`
-  - `src/services/acp/bridge.ts`
-  - `src/services/acp/promptConversion.ts`（新增）
-
-#### 参考代码位置
-
- `src/services/acp/agent.ts:754-758`
- `src/services/acp/agent.ts:764-785`
- `src/services/acp/bridge.ts:522-537`
-
-#### 背景
-
-ACP agent 与 bridge 存在重复 prompt 转换逻辑，`resource_link` 等 block 的输出策略容易分叉。
-
-#### 实施要求
-
- 新增共享转换模块 `src/services/acp/promptConversion.ts`。
- `agent.ts` 与 `bridge.ts` 改为调用共享转换函数。
- 删除 `bridge.ts` 中 `promptToQueryContent` 的真实实现；如导出仍需保留，则只允许保留调用共享函数的 wrapper。
- `resource_link` 输出改为稳定纯文本元信息，禁止 markdown link。
- 保持其他 block 转换语义不变。
-
-#### 验收标准
-
- 全仓库仅保留一个真实 prompt 转换实现。
- 相同 input block 在 agent/bridge 输出一致。
- `resource_link` 不再输出 `[name](uri)` 形式。
- 相关测试覆盖转换一致性。
-
-#### 回归范围
-
- ACP prompt input。
- bridge query content。
- resource link prompt 表达。
-
-#### 风险等级
-
- 中。文本格式变化可能影响下游 prompt 快照或断言。
-
-#### 必须验证
-
- 新增 shared conversion 单元测试。
- 全仓库搜索重复转换函数。
- 运行 `bun run typecheck`。
-
---
-
-### JIRA-006：治理 REPL onInit effect 依赖并补齐 timer cleanup
-
- Issue Type：Task
- Priority：P1
- Story Points：3
- Owner：终端 UI
- Files：
-  - `src/screens/REPL.tsx`
-
-#### 参考代码位置
-
- `src/screens/REPL.tsx:654-662`
- `src/screens/REPL.tsx:4996-5005`
-
-#### 背景
-
-REPL 中目标初始化 effect 存在 hook dependency suppress，warm-up timer 也需要显式 cleanup，避免频繁挂载/卸载时留下悬挂任务。
-
-#### 实施要求
-
- 整理 `onInit` 生命周期，使用稳定引用或 effect 内联。
- 移除目标段 `exhaustive-deps` suppress。
- 保持 unmount cleanup 行为不变。
- warm-up effect 中记录 timeout id。
- cleanup 中执行 `clearTimeout(timeoutId)`。
- 保留 `alive` 判定作为并发保护。
-
-#### 验收标准
-
- 目标段不再需要 hooks lint suppress。
- 高频打开/关闭搜索栏无悬挂 timer 增长。
- REPL 初始化行为无回归。
-
-#### 回归范围
-
- REPL 初始化。
- 搜索栏 warm-up。
- 组件卸载 cleanup。
-
-#### 风险等级
-
- 中。React effect 依赖治理可能改变初始化时机。
-
-#### 必须验证
-
- 运行 lint/typecheck。
- 手动或测试覆盖 REPL mount/unmount。
-
---
-
-### JIRA-007：收敛 ACP route WebSocket 事件 any 类型
-
- Issue Type：Task
- Priority：P1
- Story Points：2
- Owner：后端/网关
- Files：
-  - `packages/remote-control-server/src/routes/acp/index.ts`
-
-#### 参考代码位置
-
- `packages/remote-control-server/src/routes/acp/index.ts:108-146`
-
-#### 背景
-
-ACP route 中 WebSocket 事件和 socket 参数存在 `any`，降低编译期保护。
-
-#### 实施要求
-
- 定义最小 WebSocket 事件类型：open/message/close/error。
- 将 `_evt: any`、`evt: any`、`ws: any` 替换为窄类型。
- 不改变 payload decode 与大小检查策略。
- 不改变现有 handler 行为。
-
-#### 验收标准
-
- 编译期能捕获错误事件字段访问。
- 现有 WebSocket 行为不变。
- `bun run typecheck` 通过。
-
-#### 回归范围
-
- ACP WebSocket route。
- message decode。
- close/error handler。
-
-#### 风险等级
-
- 低。类型收敛为主。
-
-#### 必须验证
-
- 运行 `bun run typecheck`。
- 保留现有测试通过。
-
---
-
-### JIRA-008：收敛 session ingress WebSocket 事件类型与 decode path
-
- Issue Type：Task
- Priority：P1
- Story Points：3
- Owner：后端/网关
- Files：
-  - `packages/remote-control-server/src/routes/v1/session-ingress.ts`
- 前置依赖：JIRA-001 已合并
-
-#### 参考代码位置
-
- `packages/remote-control-server/src/routes/v1/session-ingress.ts:100-106`
-
-#### 背景
-
-在完成 P0 size guard 后，session ingress 仍需要进一步收敛事件类型与 decode path，减少隐式类型风险。
-
-#### 实施要求
-
- 定义或复用最小 WebSocket message event 类型。
- 将 message decode 分支集中到一个小函数。
- 保持 P0 size guard 与 close code 语义。
- 不改变 auth/session 解析。
-
-#### 验收标准
-
- decode path 单一清晰。
- 不支持 payload 类型有明确拒绝路径。
- `bun run typecheck` 通过。
-
-#### 回归范围
-
- Session ingress WebSocket message handling。
- P0 大包拒绝逻辑。
-
-#### 风险等级
-
- 低到中。与 P0 同文件，注意避免重复改动冲突。
-
-#### 必须验证
-
- 与 JIRA-001 同批测试。
- 运行 `bun run typecheck`。
-
---
-
-## QA Tickets
-
-### JIRA-009：补充 ACP 通讯回归测试
-
- Issue Type：Test
- Priority：P1
- Story Points：5
- Owner：QA/核心通讯
- Files：
-  - `src/services/acp/agent.ts`
-  - `src/services/acp/bridge.ts`
-  - `src/services/acp/promptConversion.ts`
-  - `src/services/acp/__tests__/agent.test.ts`
-  - `src/services/acp/__tests__/bridge.test.ts`
-  - `src/services/acp/__tests__/promptConversion.test.ts`
-
-#### 覆盖场景
-
- 长会话 10k turn，无 abort listener 累积。
- prompt queue 1000 并发排队，取消/出队顺序正确。
- settings/defaultMode 与 `_meta.permissionMode` 优先级正确。
- `resource_link` 转换在 agent 与 bridge 输出一致。
-
-#### 验收标准
-
- 新增测试在本地稳定通过。
- 不依赖真实网络或外部服务。
- 测试 mock 遵守仓库规范，只 mock 有副作用链路。
-
-#### 回归范围
-
- ACP bridge。
- ACP agent。
- prompt conversion。
- permission mode resolution。
-
-#### 风险等级
-
- 中。异步测试可能有稳定性问题，需要避免时间敏感断言。
-
-#### 必须验证
-
- 运行相关 `bun test`。
- 运行 `bun run typecheck`。
-
---
-
-### JIRA-010：补充 Remote Control Server WebSocket 入站回归测试
-
- Issue Type：Test
- Priority：P1
- Story Points：3
- Owner：QA/后端
- Files：
-  - `packages/remote-control-server/src/__tests__/routes.test.ts`
-  - `packages/remote-control-server/src/routes/v1/session-ingress.ts`
-
-#### 覆盖场景
-
- 11MB session ingress payload 被 1009 close（与 10MB 上限对齐）。
- 合法小 payload 正常进入 handler。
- 非支持 payload 类型被拒绝。
- 日志或可观测输出包含 sessionId、payload size、limit。
-
-#### 验收标准
-
- 11MB payload 被 1009 close（与 10MB 上限对齐）。
- 新增测试稳定通过。
- 不启动真实外部服务。
- 不改变现有 route public contract。
-
-#### 回归范围
-
- RCS session ingress route。
- WebSocket message handling。
- close code 行为。
-
-#### 风险等级
-
- 中。测试需要适配现有 WebSocket/mock 基础设施。
-
-#### 必须验证
-
- 运行 RCS package 相关测试。
- 运行 `bun run typecheck`。
-
---
-
-## 推荐执行顺序
-
-执行节奏与原计划保持一致：先完成 P0 全部改动和冒烟验证，再启动 P1 改造；测试票可穿插执行，但不得绕过 P0 gate。
-
-1. JIRA-001：先封入口大包风险。
-2. JIRA-002：修长会话 listener 生命周期。
-3. JIRA-010：补 RCS 入站测试，锁住 P0 行为。
-4. JIRA-003：优化 pending prompt queue。
-5. JIRA-004：接入 settings/defaultMode。
-6. JIRA-005：单源化 prompt 转换。
-7. JIRA-009：补 ACP 回归测试。
-8. JIRA-006：治理 REPL effect/timer。
-9. JIRA-007：收敛 ACP route 类型。
-10. JIRA-008：收敛 session ingress 类型与 decode path。
-
---
-
-## Release Checklist
-
- [ ] `bun run typecheck` 0 error
- [ ] P0 tickets 已合并并测试通过
- [ ] ACP 回归测试通过
- [ ] RCS WebSocket 入站测试通过
- [ ] prompt conversion 单源化已通过代码搜索确认
- [ ] permission mode 优先级测试通过
- [ ] 协议层行为无回归（stopReason 决策、sessionUpdate 发送顺序）
- [ ] REPL hook/timer 改动通过 lint/typecheck
- [ ] 最终变更说明包含风险与未覆盖项
--- a/docs/internals/agent-comm-fix-questions.md
+++ b/docs/internals/agent-comm-fix-questions.md
@@ -1,74 +0,0 @@
-# Agent 通讯修复问题文档
-
- 版本：v1.0
- 生成日期：2026-04-25
- 范围：ACP Agent / Bridge / Remote Control Server / REPL Hook 生命周期
- 配套执行文档：`docs/internals/agent-comm-fix-jira-tasks.md`
- 目的：保留决策前要问的问题、交叉验证提示词和已确认结论；不要在这里写 Jira 执行步骤。
-
---
-
-## 1. 当前已确认结论
-
- 只保留两份交付文档：本问题文档 + Jira Task 文档。
- Jira Task 文档是唯一执行入口，包含 Owner、优先级、文件范围、验收标准、风险和验证建议。
- Claude 交叉验证结论：整体通过，无 blocking findings；建议补充协议回归 gate、JIRA-001/008 依赖、代码参考位置和阈值一致性，这些建议已合并到 Jira Task 文档。
- 本次已进入业务代码修复阶段，必须运行 `bun run typecheck` 和相关回归测试。
-
---
-
-## 2. 执行前必须问清的问题
-
-1. `session-ingress` 的 WebSocket 上限是否固定为 10MB，并与 ACP route 保持一致？
-2. 超限 close code 是否统一使用 `1009`，close reason 是否固定为 `message too large`？
-3. `resource_link` 的纯文本格式是否已有下游依赖，能否替代当前 markdown link 表达？
-4. ACP permission mode 的真实 settings key 是哪个，非法值 fallback 是否统一为 `default`？
-5. `_meta.permissionMode` 是否必须始终覆盖 settings/defaultMode？
-6. abort listener 测试中，是否能通过 mock signal 或计数器稳定证明 10k next 后无 listener 累积？
-7. pending prompt queue 的取消语义是否允许惰性清理，而不是立刻从数组中删除？
-8. REPL hook suppress 的清理范围是否只限目标段，不顺手改其他 decompiled React Compiler 结构？
-9. RCS WebSocket 测试应放在现有哪个 `__tests__` 布局下，是否已有 route/mock 基础设施可复用？
-10. 发布 gate 是否必须包含 `stopReason` 决策与 `sessionUpdate` 发送顺序不回归？
-
---
-
-## 3. 给 Claude 或 Reviewer 的复核问题
-
-```text
-请作为外部审查者，复核 docs/internals/agent-comm-fix-jira-tasks.md。
-
-请检查：
-1. 是否仍满足“按文件分工的执行清单”和“Jira task 文档”要求。
-2. 是否存在遗漏的文件、验收标准、风险或前置依赖。
-3. 是否有重复、误导执行者、优先级不合理或测试不可落地的问题。
-4. 是否还有必须阻断实施的 finding。
-
-请用中文输出：
- Verdict
- Blocking Findings
- Non-blocking Findings
- Suggested Edits
- Final Recommendation
-
-不要修改文件，只输出审查意见。
-```
-
---
-
-## 4. 已处理的复核建议
-
- Release Checklist 已补充协议层行为无回归 gate。
- JIRA-001 与 JIRA-008 已明确同文件前后置关系。
- JIRA-001 到 JIRA-008 已补充参考代码位置。
- JIRA-003 已补回 1000 排队场景下的出队耗时验收。
- JIRA-008 story points 已从 2 调整为 3。
- JIRA-010 已明确 11MB payload 对齐 10MB 上限并触发 1009 close。
- 推荐执行顺序已明确 P0 gate：P0 全部改动和冒烟验证完成后，再启动 P1 改造。
-
---
-
-## 5. 不在本文档维护的内容
-
- 不维护 Jira ticket 正文；统一在 `docs/internals/agent-comm-fix-jira-tasks.md` 修改。
- 不维护业务代码实现方案；实现时按具体 ticket 读取对应文件。
- 不维护历史中间稿；旧执行清单已合并进 Jira Task 文档。
--- a/docs/internals/ant-only-world.mdx
+++ b/docs/internals/ant-only-world.mdx
@@ -17,7 +17,7 @@ keywords: ["Ant 特权", "USER_TYPE", "身份门控", "内部功能", "Anthropic

 `BUILD_TARGET` 等构建时常量在反编译版本中已被移除。`USER_TYPE` 通过 Bun 的 `--define` 或环境变量注入，Bun 会进行**常量折叠**——所有 `process.env.USER_TYPE === 'ant'` 在外部构建中直接变为 `false`，后续代码被 DCE 移除。但在反编译版本中，这些代码保留完整。

-`USER_TYPE === 'ant'` 在代码库中出现 **351+ 次**（跨 163 个文件），另有 `!== 'ant'` 59 次（跨 38 个文件），总计 **410+ 处引用**，控制着工具、命令、API、UI 等方方面面。
+`USER_TYPE === 'ant'` 在代码库中出现 **377+ 次**（含 `=== 'ant'` 291 次、`(process.env.USER_TYPE) === 'ant'` 86 次），另有 `!== 'ant'` 53 次、其他引用约 35 次，总计 **465 处引用**，控制着工具、命令、API、UI 等方方面面。

 ## Ant-Only 工具

@@ -25,10 +25,10 @@ keywords: ["Ant 特权", "USER_TYPE", "身份门控", "内部功能", "Anthropic

 | 工具 | 代码位置 | 用途 |
 |------|---------|------|
-| **REPLTool** | `packages/builtin-tools/src/tools/REPLTool/` | 高级 REPL 模式——在 VM 中包装 Bash/Read/Edit/Glob/Grep/Agent 等工具 |
-| **SuggestBackgroundPRTool** | `packages/builtin-tools/src/tools/SuggestBackgroundPRTool/` | 建议在后台创建 PR |
-| **ConfigTool** | `packages/builtin-tools/src/tools/ConfigTool/` | 交互式配置编辑器，包含 Gates 标签页用于覆盖 GrowthBook flags |
-| **TungstenTool** | `packages/builtin-tools/src/tools/TungstenTool/` | 基于 tmux 的终端面板工具（反编译版中已 stub） |
+| **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 标记
@@ -36,18 +36,18 @@ keywords: ["Ant 特权", "USER_TYPE", "身份门控", "内部功能", "Anthropic
 /* eslint-disable custom-rules/no-process-env-top-level, @typescript-eslint/no-require-imports */
 const REPLTool =
  process.env.USER_TYPE === 'ant'
-    ? require('@claude-code-best/builtin-tools/tools/REPLTool/REPLTool.js').REPLTool
+    ? require('./tools/REPLTool/REPLTool.js').REPLTool
    : null
 const SuggestBackgroundPRTool =
  process.env.USER_TYPE === 'ant'
-    ? require('@claude-code-best/builtin-tools/tools/SuggestBackgroundPRTool/SuggestBackgroundPRTool.js')
+    ? require('./tools/SuggestBackgroundPRTool/SuggestBackgroundPRTool.js')
        .SuggestBackgroundPRTool
    : null
 ```

 ## Ant-Only 命令

-`src/commands.ts` 注册了 **24+** 个仅在内部构建中可用的斜杠命令（`INTERNAL_ONLY_COMMANDS`，lines 267-295），在 `USER_TYPE === 'ant' && !IS_DEMO` 时才加载（line 400-401）：
+`src/commands.ts` 注册了 **28** 个仅在内部构建中可用的斜杠命令（`INTERNAL_ONLY_COMMANDS`，lines 225-254），在 `USER_TYPE === 'ant' && !IS_DEMO` 时才加载（line 343-345）：

 <AccordionGroup>
  <Accordion title="调试类">
@@ -74,7 +74,7 @@ const SuggestBackgroundPRTool =
    - `summary` — 生成摘要
    - `subscribePr` — 订阅 PR（需要 `KAIROS_GITHUB_WEBHOOKS` feature flag）
    - `forceSnip` — 强制截断历史（需要 `HISTORY_SNIP` feature flag）
-    - `ultraplan` — 超级规划（需要 `ULTRAPLAN` feature flag，单独注册于 `commands.ts:396`）
+    - `ultraplan` — 超级规划（需要 `ULTRAPLAN` feature flag）
  </Accordion>
  <Accordion title="基础设施类">
    - `backfillSessions` — 回填会话数据
--- a/docs/internals/autonomy-jira.md
+++ b/docs/internals/autonomy-jira.md
@@ -1,314 +0,0 @@
-# Autonomy Reliability Jira Drafts
-
-These tickets are based on the call-chain audit of `/autonomy`, proactive
-ticks, HEARTBEAT managed flows, cron scheduling, command queue consumption,
-and daemon process supervision.
-
-## AUT-001: Preserve autonomy lifecycle when queued commands are consumed mid-turn
-
-Type: Bug
-Priority: P0
-Status: Draft
-Patch status: Implemented in `fix/autonomy-lifecycle`.
-
-Problem:
-`query.ts` can drain queued prompt/task-notification commands as attachments
-during an active turn. Autonomy prompts consumed this way were removed from the
-in-memory queue without marking the persisted run as running/completed/failed,
-so managed flows could stay stuck in `queued` and never advance.
-
-Evidence:
- `src/query.ts` drains queued commands via `getCommandsByMaxPriority()`.
- `src/query.ts` removes consumed commands from the queue.
- Lifecycle updates existed only in the normal queued-submit path
-  `src/utils/handlePromptSubmit.ts` and headless `src/cli/print.ts`.
-
-Acceptance criteria:
- Mid-turn consumed autonomy commands mark runs `running`.
- Normal query completion finalizes consumed runs and queues next managed-flow
-  steps.
- Query errors or abort terminal reasons mark consumed runs failed.
- Stale/cancelled autonomy commands are removed from the in-memory queue
-  without being sent to the model.
- Regression tests cover stale command filtering and managed-flow advancement.
-
-## AUT-002: Make autonomy run lifecycle transitions terminal-safe
-
-Type: Bug
-Priority: P0
-Status: Draft
-Patch status: Implemented in `fix/autonomy-lifecycle`.
-
-Problem:
-Run lifecycle helpers rewrote status unconditionally. A stale in-memory command
-could mark a cancelled/completed/failed run back to `running`, causing a
-cancelled flow to execute or a terminal flow to be rewritten.
-
-Evidence:
- `markAutonomyRunRunning`, `markAutonomyRunCompleted`,
-  `markAutonomyRunFailed`, and `markAutonomyRunCancelled` updated records
-  without checking current status.
- External CLI cancel cannot remove queued commands living inside another
-  process, so stale commands are a realistic input.
-
-Acceptance criteria:
- `queued -> running/completed/failed/cancelled` remains allowed.
- `running -> completed/failed/cancelled` remains allowed.
- Any terminal status rejects later lifecycle updates.
- Rejected transitions do not update managed-flow step state.
- Regression tests cover stale lifecycle calls after cancellation.
-
-## AUT-003: Prevent proactive and scheduled-task async fire failures from becoming invisible
-
-Type: Bug
-Priority: P1
-Status: Draft
-Patch status: Implemented in `fix/autonomy-lifecycle`.
-
-Problem:
-Proactive tick and cron fire callbacks launch detached async work. Failures in
-prompt preparation or queue insertion could surface as unhandled rejections or
-be lost from diagnostics. In one-shot cron paths, the scheduler has already
-decided the task fired.
-
-Evidence:
- `src/proactive/useProactive.ts` used a detached async IIFE without catch.
- `src/cli/print.ts` proactive and cron paths also detached async work.
- `src/hooks/useScheduledTasks.ts` cron callbacks detached async work.
-
-Acceptance criteria:
- Detached proactive/cron fire work has explicit error logging.
- REPL proactive tick generation is non-reentrant.
- Tick generation stops queueing after hook unmount.
-
-## AUT-004: Bound long-running daemon restart timers during shutdown
-
-Type: Bug
-Priority: P1
-Status: Draft
-Patch status: Implemented in `fix/autonomy-lifecycle`.
-
-Problem:
-The daemon supervisor scheduled worker restarts with `setTimeout()` but did
-not store, clear, or `unref()` the timer. Shutdown during backoff could keep
-the supervisor alive until the timer fired, forcing the stop path toward
-SIGKILL.
-
-Evidence:
- `src/daemon/main.ts` scheduled restart timers directly in the worker exit
-  handler.
- Shutdown only signaled child processes and did not clear restart timers.
-
-Acceptance criteria:
- Worker restart timers are tracked per worker.
- Shutdown clears any pending restart timers.
- Restart and force-kill grace timers do not keep the supervisor alive alone.
-
-## AUT-005: Release autonomy persistence lock bookkeeping after each chain
-
-Type: Bug
-Priority: P1
-Status: Draft
-Patch status: Implemented in `fix/autonomy-lifecycle`.
-
-Problem:
-`withAutonomyPersistenceLock` stored a chained promise in its map but compared
-the map value against the raw current promise during cleanup. That condition
-never matched, so root-level lock bookkeeping could accumulate in long-lived
-processes that touch many workspaces.
-
-Evidence:
- `src/utils/autonomyPersistence.ts` stored `previous.then(() => current)`.
- Cleanup compared `persistenceLocks.get(key) === current`.
-
-Acceptance criteria:
- The stored chained promise is the value used for cleanup comparison.
- Existing serialization behavior for same-root calls remains unchanged.
- Tests directly assert same-root lock bookkeeping returns to zero after both
-  success and failure.
-
-## AUT-006: Add active-record protection before persistence truncation
-
-Type: Reliability
-Priority: P2
-Status: Draft
-Patch status: Implemented in `fix/autonomy-lifecycle`.
-
-Problem:
-Autonomy runs and flows are capped by latest-created/updated order only.
-Under high churn, active `queued` or `running` records can be truncated before
-completion, which removes recovery evidence and can break managed-flow
-advancement.
-
-Evidence:
- `src/utils/autonomyRuns.ts` keeps the latest 200 runs by `createdAt`.
- `src/utils/autonomyFlows.ts` keeps the latest 100 flows by `updatedAt`.
-
-Acceptance criteria:
- Active records are retained before completed historical records are trimmed.
- Tests cover trimming with more than the configured cap and active records
-  near the tail.
-
-## AUT-007: Treat provider API-error responses as failed autonomy turns
-
-Type: Bug
-Priority: P0
-Status: Draft
-Patch status: Implemented in `fix/autonomy-lifecycle`.
-
-Problem:
-Third-party provider adapters can convert provider failures into synthetic
-assistant API-error messages instead of throwing. `query.ts` treated
-`isApiErrorMessage` terminal responses as `completed`, so an autonomy command
-that had already been consumed as a queued attachment could be marked
-completed and advance its managed flow even though the provider call failed.
-
-Evidence:
- `src/services/api/openai/index.ts`, `src/services/api/gemini/index.ts`, and
-  `src/services/api/grok/index.ts` yield `createAssistantAPIErrorMessage()` on
-  adapter errors.
- `src/query.ts` skipped stop hooks for API-error assistant messages but
-  returned `reason: 'completed'`.
- Top-level autonomy finalization used terminal completion to decide whether
-  to mark consumed runs completed or failed.
-
-Acceptance criteria:
- Provider API-error assistant messages terminate the query with
-  `reason: 'model_error'`.
- Any consumed autonomy run is marked failed rather than completed.
- Managed flows do not advance to the next step after provider API errors.
- A regression test simulates provider error after a queued autonomy attachment
-  has been consumed.
-
-## AUT-008: Finalize consumed autonomy runs on async-generator close
-
-Type: Bug
-Priority: P0
-Status: Draft
-Patch status: Implemented in `fix/autonomy-lifecycle`.
-
-Problem:
-`query()` is an async generator. When its consumer calls `.return()` or breaks
-out of iteration, JavaScript executes `finally` blocks and skips code after the
-`try/finally`. The previous autonomy finalization ran after the `finally`, so
-queued autonomy commands that had already been claimed as `running` could stay
-persisted as `running` forever if the REPL/SDK consumer closed the generator.
-
-Evidence:
- Claimed run IDs were collected during queued attachment injection.
- Completion/failure finalization happened only after `yield* queryLoop(...)`
-  returned normally or threw.
- Claude cross-validation flagged this as a durable run/flow leak.
-
-Acceptance criteria:
- Consumed autonomy runs are finalized from a `finally` path.
- Normal completion marks consumed runs completed and enqueues next managed
-  flow steps.
- Provider/model errors mark consumed runs failed.
- Generator close and user abort terminals mark consumed runs cancelled.
- A regression test closes the generator after a queued autonomy attachment and
-  verifies the run/flow are cancelled, not left running.
-
-## AUT-009: Claim queued autonomy runs before attachment injection
-
-Type: Bug
-Priority: P0
-Status: Draft
-Patch status: Implemented in `fix/autonomy-lifecycle`.
-
-Problem:
-The query loop filtered stale queued autonomy commands before attachment
-generation, but it did not claim runs as `running` until after attachments were
-already yielded. A concurrent cancellation between those steps could still send
-a cancelled prompt into the model context.
-
-Evidence:
- `partitionConsumableQueuedAutonomyCommands()` only checked persisted status.
- `markAutonomyRunRunning()` previously ran after `getAttachmentMessages()`.
- Reviewer cross-validation identified the check-then-act race.
-
-Acceptance criteria:
- Query claims queued autonomy runs before passing commands to attachment
-  generation.
- Only successfully claimed commands are injected as queued-command
-  attachments.
- Failed claims are treated as stale and removed from the in-memory queue.
- Claiming reads persisted run state once per turn rather than once per
-  command.
-
-## AUT-010: Cancel proactive and cron runs dropped before enqueue
-
-Type: Bug
-Priority: P1
-Status: Draft
-Patch status: Implemented in `fix/autonomy-lifecycle`.
-
-Problem:
-`/proactive` and scheduled-task producers persist autonomy runs before
-returning queue commands. If the component is disposed or headless input closes
-after persistence but before enqueue, the queued run is left on disk with no
-in-memory command to consume it.
-
-Evidence:
- `createProactiveAutonomyCommands()` commits runs before returning commands.
- `commitAutonomyQueuedPrompt()` persists scheduled-task runs before callers
-  enqueue them.
- Callers checked `disposed` / `inputClosed` after command creation and could
-  return without terminalizing the run.
-
-Acceptance criteria:
- Proactive hook cancellation checks run both before commit and after command
-  creation.
- Headless proactive and cron paths cancel any already-created command that is
-  dropped due to input close.
- REPL scheduled-task cleanup cancels already-created commands when unmounted.
- A regression test verifies a proactive command created but dropped before
-  enqueue is marked cancelled.
-
-## AUT-011: Replace query transition `any` stubs with typed contracts
-
-Type: Test/Type Safety
-Priority: P2
-Status: Draft
-Patch status: Implemented in `fix/autonomy-lifecycle`.
-
-Problem:
-`src/query/transitions.ts` defined both `Terminal` and `Continue` as `any`.
-That allowed new terminal reasons such as `model_error` and continuation
-reasons such as `collapse_drain_retry` to drift without compiler checks.
-
-Evidence:
- Claude cross-validation flagged the `Terminal = any` contract as a remaining
-  issue.
- Tightening the type immediately caught that
-  `collapse_drain_retry.committed` is a `number`, not a `boolean`.
-
-Acceptance criteria:
- `Terminal` is a concrete union of query terminal reasons.
- `Continue` is a concrete union of continuation reasons and payloads.
- `bun run typecheck` validates all query return sites against that contract.
-
-## AUT-012: Avoid provider test settings-module mock pollution
-
-Type: Test Reliability
-Priority: P2
-Status: Draft
-Patch status: Implemented in `fix/autonomy-lifecycle`.
-
-Problem:
-The provider tests previously mocked `settings.js`. A minimal mock broke other
-tests that imported additional settings exports in the same Bun process; the
-expanded mock avoided the failure but over-coupled the provider test to
-unrelated settings internals.
-
-Evidence:
- Full test runs observed cross-file settings mock pollution.
- `src/utils/model/providers.ts` only needs the real `getInitialSettings()`
-  behavior.
-
-Acceptance criteria:
- Provider tests do not mock `settings.js`.
- `modelType` precedence is exercised through an injected settings snapshot,
-  leaving global bootstrap state untouched.
- Provider tests pass when run alongside permissions tests and the provider
-  matrix.
--- a/docs/internals/feature-flags.mdx
+++ b/docs/internals/feature-flags.mdx
@@ -15,19 +15,17 @@ Claude Code 使用 Bun 打包器的 `bun:bundle` 模块提供编译时特性门
 import { feature } from 'bun:bundle'

 const SleepTool = feature('PROACTIVE') || feature('KAIROS')
-  ? require('@claude-code-best/builtin-tools/tools/SleepTool/SleepTool.js').SleepTool
+  ? require('./tools/SleepTool/SleepTool.js').SleepTool
  : null
 ```

 在 Anthropic 的内部构建中，`feature()` 在打包时被求值——返回 `true` 的代码会被保留，返回 `false` 的代码会被 **Dead Code Elimination (DCE)** 彻底移除。

-在我们的反编译版本中，`feature` 从 `bun:bundle` 导入（声明在 `src/types/internal-modules.d.ts`），在运行时始终返回 `false`：
+在我们的反编译版本中，这个函数被兜底为：

 ```typescript
-// src/types/internal-modules.d.ts
-declare module 'bun:bundle' {
-  export function feature(name: string): boolean;
-}
+// src/entrypoints/cli.tsx 第 3 行
+const feature = (_name: string) => false;
 ```

 这意味着所有 88+ 个 feature flag 后的代码**在运行时永远不会执行**，但代码本身完整保留，可以阅读和分析。
@@ -81,7 +79,7 @@ Feature flags 在代码中主要有三种使用模式：
 ```typescript
 // src/tools.ts — 最常见的模式
 const MonitorTool = feature('MONITOR_TOOL')
-  ? require('@claude-code-best/builtin-tools/tools/MonitorTool/MonitorTool.js').MonitorTool
+  ? require('./tools/MonitorTool/MonitorTool.js').MonitorTool
  : null
 ```

--- a/docs/internals/growthbook-ab-testing.mdx
+++ b/docs/internals/growthbook-ab-testing.mdx
@@ -19,7 +19,7 @@ keywords: ["GrowthBook", "A/B 测试", "运行时门控", "tengu", "渐进式发

 ## 集成架构

-GrowthBook 的完整实现位于 `src/services/analytics/growthbook.ts`（1258 行），工作流程如下：
+GrowthBook 的完整实现位于 `src/services/analytics/growthbook.ts`（1156 行），工作流程如下：

 <Steps>
  <Step title="启动时获取远程配置">
--- a/docs/internals/hidden-features.mdx
+++ b/docs/internals/hidden-features.mdx
@@ -84,7 +84,7 @@ keywords: ["隐藏功能", "未公开功能", "秘密功能", "Claude Code 彩
  <Accordion title="VOICE_MODE：语音交互">
    **门控**: `feature('VOICE_MODE')`

-    代码中存在语音输入模式的注册点，核心实现依赖 `audio-capture-napi` 包（已恢复）：
+    代码中存在语音输入模式的注册点，但核心实现依赖于 `audio-napi` 包（在反编译版本中已 stub）：

    - 通过 `/voice` 命令激活
    - "按住说话"（hold-to-talk）交互模式
--- a/docs/introduction/architecture-overview.mdx
+++ b/docs/introduction/architecture-overview.mdx
@@ -64,27 +64,24 @@ Claude Code 从上到下分为五个层次，每一层职责清晰、边界分
   needsFollowUp ? continue : return { reason }
 ```

-完整的状态机通过 `State` 类型（`src/query.ts:207`）在迭代间传递，包含 10 个字段（messages、autoCompactTracking、maxOutputTokensRecoveryCount 等）。
+完整的状态机通过 `State` 类型（`src/query.ts:204`）在迭代间传递，包含 10 个字段（messages、autoCompactTracking、maxOutputTokensRecoveryCount 等）。

 ### 4. 工具层（`src/tools.ts` → `src/Tool.ts`）

-`getAllBaseTools()`（`src/tools.ts:195`）组装 50+ 工具列表，经过 `filterToolsByDenyRules()` 权限过滤后传给 API。
+`getAllBaseTools()`（`src/tools.ts:191`）组装 50+ 工具列表，经过 `filterToolsByDenyRules()` 权限过滤后传给 API。

-每个工具实现 `Tool<Input, Output, Progress>` 接口（`src/Tool.ts:368`），核心方法链：
+每个工具实现 `Tool<Input, Output, Progress>` 接口（`src/Tool.ts:362`），核心方法链：
 ```
 validateInput() → canUseTool()（UI 层）→ checkPermissions() → call() → ToolResult
 ```

 ### 5. 通信层（`src/services/api/claude.ts`）

-API 客户端支持 7 种 Provider：
- **Anthropic Direct (firstParty)**：默认
+API 客户端支持 4 种 Provider：
+- **Anthropic Direct**：默认
 - **AWS Bedrock**：`ANTHROPIC_BEDROCK_BASE_URL`
 - **Google Vertex**：`ANTHROPIC_VERTEX_PROJECT_ID`
- **Foundry**：`ANTHROPIC_CODE_USE_FOUNDRY`
- **OpenAI**：兼容层
- **Gemini**：兼容层
- **Grok (xAI)**：兼容层
+- **Azure**：通过自定义 base URL

 `deps.callModel()` 发起流式请求，返回 `BetaRawMessageStreamEvent` 事件流。支持 Prompt Cache（`cache_control`）、thinking blocks、multi-turn tool use。

--- a/docs/introduction/what-is-claude-code.mdx
+++ b/docs/introduction/what-is-claude-code.mdx
@@ -53,7 +53,7 @@ Claude Code 是一个**运行在本地终端中的 agentic coding system**。它
 │    实际执行: 读文件、运行命令、搜索代码...               │
 ├─────────────────────────────────────────────────────────┤
 │ 6. 通信层 (claude.ts → Anthropic API)                    │
-│    流式 HTTP, 支持 Bedrock/Vertex/Foundry 等 7 种 provider      │
+│    流式 HTTP, 支持 Bedrock/Vertex/Azure 多 provider      │
 └─────────────────────────────────────────────────────────┘
 ```

--- a/docs/introduction/why-this-whitepaper.mdx
+++ b/docs/introduction/why-this-whitepaper.mdx
@@ -49,7 +49,7 @@ AI 没有真正的"记忆"，Claude Code 通过精心分层营造了这个幻觉

 ### 3. 工具系统的权限双轨制

-`packages/builtin-tools/src/tools/BashTool/shouldUseSandbox.ts` 展示了一个精巧的双重安全模型：
+`src/tools/BashTool/shouldUseSandbox.ts` 展示了一个精巧的双重安全模型：

 - **应用层**：权限规则决定"能不能执行"（白名单/黑名单/用户确认）
 - **OS 层**：沙箱决定"执行时能做什么"（文件系统/网络/进程隔离）
--- a/docs/lsp-integration.md
+++ b/docs/lsp-integration.md
@@ -65,7 +65,7 @@ ENABLE_LSP_TOOL=1 bun run dev
 ```
 ┌─────────────────────────────────────────────────────┐
 │                    LSP Tool                         │
-│  packages/builtin-tools/src/tools/LSPTool/LSPTool.ts│
+│  src/tools/LSPTool/LSPTool.ts                       │
 │  (Claude 可调用的工具，9 种操作)                       │
 └──────────────────────┬──────────────────────────────┘
                       │
@@ -128,10 +128,10 @@ LSP 服务器会异步推送 `textDocument/publishDiagnostics` 通知，经去
 | `src/services/lsp/config.ts` | 从插件加载 LSP 服务器配置 |
 | `src/services/lsp/LSPDiagnosticRegistry.ts` | 诊断信息注册、去重、容量限制 |
 | `src/services/lsp/passiveFeedback.ts` | 注册 `publishDiagnostics` 通知处理器 |
-| `packages/builtin-tools/src/tools/LSPTool/LSPTool.ts` | LSP Tool 实现（暴露给 Claude） |
-| `packages/builtin-tools/src/tools/LSPTool/schemas.ts` | 输入 schema（9 种操作的 discriminated union） |
-| `packages/builtin-tools/src/tools/LSPTool/formatters.ts` | 各操作结果的格式化 |
-| `packages/builtin-tools/src/tools/LSPTool/prompt.ts` | Tool 描述文本 |
+| `src/tools/LSPTool/LSPTool.ts` | LSP Tool 实现（暴露给 Claude） |
+| `src/tools/LSPTool/schemas.ts` | 输入 schema（9 种操作的 discriminated union） |
+| `src/tools/LSPTool/formatters.ts` | 各操作结果的格式化 |
+| `src/tools/LSPTool/prompt.ts` | Tool 描述文本 |
 | `src/utils/plugins/lspPluginIntegration.ts` | 从插件加载、验证、环境变量解析、作用域管理 |

 ## LSP Tool 支持的操作
@@ -200,9 +200,9 @@ LSP 服务器通过插件提供。插件的 `manifest.json` 中可以声明 LSP
 |------|------|------|------|
 | `command` | string | 是 | LSP 服务器可执行命令（不含空格） |
 | `args` | string[] | 否 | 命令行参数 |
-| `extensionToLanguage` | `Record<string, string>` | 是 | 文件扩展名到语言 ID 的映射（至少一个） |
+| `extensionToLanguage` | Record<string, string> | 是 | 文件扩展名到语言 ID 的映射（至少一个） |
 | `transport` | `"stdio"` \| `"socket"` | 否 | 通信方式，默认 `stdio` |
-| `env` | `Record<string, string>` | 否 | 启动服务器时设置的环境变量 |
+| `env` | Record<string, string> | 否 | 启动服务器时设置的环境变量 |
 | `initializationOptions` | unknown | 否 | 传给服务器的初始化选项 |
 | `settings` | unknown | 否 | 通过 `workspace/didChangeConfiguration` 传递的设置 |
 | `workspaceFolder` | string | 否 | 工作区目录路径 |
--- a/docs/memory-leak-audit.md
+++ b/docs/memory-leak-audit.md
@@ -1,659 +0,0 @@
-# 内存泄漏排查报告
-
-> 基于官方 CHANGELOG 记录的 11 个已修复内存泄漏 + 1 个代码注释中的已知问题，对反编译代码库进行逐文件验证。
-> 审计日期：2026-04-28
-
-## TODO
-
- [x] #1 图片处理无限内存增长 — 确认已实现 ✅
- [x] #2 /usage 命令泄漏约 2GB — 确认已实现 ✅
- [x] #3 长时间运行工具进度事件泄漏 — 确认已实现 ✅
- [x] #4 空闲重新渲染循环 — **已确认完整**：所有 10 个 useAnimationFrame 调用者均正确传递 null 暂停时钟，keepAlive 机制工作正常
- [x] #5 虚拟滚动器保留历史消息拷贝 — 确认已实现 ✅
- [x] #6 管道模式超宽行过度分配 — 确认已实现 ✅
- [x] #7 语言语法按需加载 — **已修复**：改用 highlight.js/lib/core + 静态注册 26 个常用语言，从 190+ 语言降至 ~25，内存减少 ~80%
- [x] #8 NO_FLICKER 模式流状态泄漏 — **已修复**：StreamingToolExecutor.discard() 现在完整释放 tools 数组、中止 siblingAbortController、清理 turnSpan，7 tests
- [x] #9 Remote Control 权限条目保留 — **已修复**：pendingPermissionHandlers 提升至 useEffect 作用域，cleanup 时显式 clear()，8 tests
- [x] #10 MCP HTTP/SSE 缓冲区累积 — 确认已实现 ✅
- [x] #11 LRU 缓存键保留大 JSON — **已确认完整实现**：FileStateCache 使用 LRU 双重限制（max 100 条目 + maxSize 25MB）+ sizeCalculation，22 tests
- [x] #12 QueryEngine.mutableMessages 不收缩 — **已修复**：实现 snipCompactIfNeeded（按 removedUuids 过滤）+ snipProjection（边界检测 + 视图投影），28 tests
- [x] #18 Permission Polling Interval 泄漏 — **已修复**：inProcessRunner 权限响应后未调用 cleanup()，导致 setInterval 永远运行 + abort listener 挂载，6 tests
- [x] #17 LSP Opened Files Map 不收缩 — **已修复**：LSPServerManager 添加 closeAllFiles() 方法，postCompactCleanup 集成调用，compaction 后释放 openedFiles Map，5 tests
-
-## 总览
---
-
-## 1. 图片处理无限内存增长 (v2.1.121)
-
-**CHANGELOG 描述**：Fixed unbounded memory growth (multi-GB RSS) when processing many images in a session
-
-### 实现位置
-
- `src/utils/imageStore.ts` — 核心修复
- `src/commands/clear/caches.ts` — 缓存清理
- `src/screens/REPL.tsx` — UI 层释放
-
-### 修复方式
-
-三层防护机制：
-
-1. **LRU 内存缓存**：`storedImagePaths` Map 上限 200 条目（`MAX_STORED_IMAGE_PATHS`），超出自动驱逐最早条目
-2. **磁盘持久化**：图片 base64 数据写入 `~/.claude/image-cache/<sessionId>/`，内存中仅保留路径字符串
-3. **立即释放**：`setPastedContents({})` 在消息提交/命令执行后清空 React state 中的 base64 数据
-
-### 关键代码
-
-```typescript
-// imageStore.ts:10
-const MAX_STORED_IMAGE_PATHS = 200
-
-// imageStore.ts:115-124
-function evictOldestIfAtCap(): void {
-  while (storedImagePaths.size >= MAX_STORED_IMAGE_PATHS) {
-    const oldest = storedImagePaths.keys().next().value
-    if (oldest !== undefined) {
-      storedImagePaths.delete(oldest)
-    } else {
-      break
-    }
-  }
-}
-
-// imageStore.ts:129-167 — 清理旧会话目录
-export async function cleanupOldImageCaches(): Promise<void> { ... }
-```
-
---
-
-## 2. /usage 命令泄漏约 2GB (v2.1.121)
-
-
-**CHANGELOG 描述**：Fixed /usage leaking up to ~2GB of memory on machines with large transcript histories
-
-### 实现位置
-
- `src/utils/sessionStoragePortable.ts:716-792` — 核心流式读取
- `src/utils/attribution.ts` — 调用方
-
-### 修复方式
-
-1. **分块流式读取**：使用 `TRANSCRIPT_READ_CHUNK_SIZE = 1MB` 固定块大小，通过 `fd.read()` 逐块处理，避免一次性加载整个 transcript
-2. **字节级过滤**：在 fd 层面直接跳过 `attribution-snapshot` 类型的行（占长会话 84% 的字节空间）
-3. **边界截断**：搜索 `compact_boundary` 标记，只保留边界之后的数据
-4. **缓冲区控制**：初始缓冲区限制 `Math.min(fileSize, 8MB)`
-
-### 关键代码
-
-```typescript
-// sessionStoragePortable.ts:716-792
-export async function readTranscriptForLoad(
-  filePath: string,
-  fileSize: number,
-): Promise<{
-  boundaryStartOffset: number
-  postBoundaryBuf: Buffer
-  hasPreservedSegment: boolean
-}> {
-  const s: LoadState = {
-    out: {
-      buf: Buffer.allocUnsafe(Math.min(fileSize, 8 * 1024 * 1024)),
-      len: 0,
-      cap: fileSize + 1,
-    },
-    // ...
-  }
-  const chunk = Buffer.allocUnsafe(CHUNK_SIZE)
-  const fd = await fsOpen(filePath, 'r')
-  try {
-    let filePos = 0
-    while (filePos < fileSize) {
-      const { bytesRead } = await fd.read(chunk, 0, Math.min(CHUNK_SIZE, fileSize - filePos), filePos)
-      if (bytesRead === 0) break
-      filePos += bytesRead
-      // ... 分块处理逻辑
-    }
-    finalizeOutput(s)
-  } finally {
-    await fd.close()
-  }
-}
-```
-
---
-
-## 3. 长时间运行工具进度事件泄漏 (v2.1.121)
-
-
-**CHANGELOG 描述**：Fixed memory leak when long-running tools fail to emit a clear progress event
-
-### 实现位置
-
- `src/screens/REPL.tsx:3054-3114` — progress 消息替换逻辑
- `src/utils/sessionStorage.ts:186-196` — 临时消息类型定义
-
-### 修复方式
-
-1. **向后扫描替换**：从只检查最后一条消息改为向后遍历所有 progress 消息，找到匹配的 `parentToolUseID` + `type` 后替换（修复交错消息导致 13k+ 条目堆积）
-2. **全屏模式硬上限**：`MAX_FULLSCREEN_SCROLLBACK = 500`，超出截断
-3. **临时消息识别**：`isEphemeralToolProgress()` 区分 `bash_progress`、`sleep_progress` 等一次性消息与需要保留的 `agent_progress` 等
-
-### 关键代码
-
-```typescript
-// REPL.tsx:3094-3114
-setMessages(oldMessages => {
-  const newData = newMessage.data as Record<string, unknown>;
-  // Scan backwards to find the last ephemeral progress with matching
-  // parentToolUseID and type.
-  for (let i = oldMessages.length - 1; i >= 0; i--) {
-    const m = oldMessages[i]!
-    if (m.type !== 'progress') break
-    const mData = m.data as Record<string, unknown> | undefined
-    if (
-      m.parentToolUseID === newMessage.parentToolUseID &&
-      mData?.type === newData.type
-    ) {
-      const copy = oldMessages.slice();
-      copy[i] = newMessage;
-      return copy;
-    }
-  }
-  return [...oldMessages, newMessage];
-});
-
-// REPL.tsx:3058-3064 — 全屏模式硬上限
-const MAX_FULLSCREEN_SCROLLBACK = 500
-const kept = postBoundary.length > MAX_FULLSCREEN_SCROLLBACK
-  ? postBoundary.slice(-MAX_FULLSCREEN_SCROLLBACK)
-  : postBoundary
-return [...kept, newMessage]
-```
-
---
-
-## 4. 空闲重新渲染循环 (v2.1.117)
-
-**状态：已确认完整**
-
-**CHANGELOG 描述**：Fixed idle re-render loop when background tasks are present, reducing memory growth on Linux
-
-### 实现位置
-
- `packages/@ant/ink/src/components/ClockContext.tsx` — 核心时钟管理
-
-### 已实现部分
-
-`ClockContext` 的 `keepAlive` 订阅者分类机制完整存在：
-
-```typescript
-// ClockContext.tsx:11-43
-function createClock(tickIntervalMs: number): Clock {
-  const subscribers = new Map<() => void, boolean>()
-  let interval: ReturnType<typeof setInterval> | null = null
-
-  function updateInterval(): void {
-    const anyKeepAlive = [...subscribers.values()].some(Boolean)
-    if (anyKeepAlive) {
-      // 有 keepAlive 订阅者时启动 interval
-      interval = setInterval(tick, currentTickIntervalMs)
-    } else if (interval) {
-      // 无 keepAlive 订阅者时停止 interval
-      clearInterval(interval)
-      interval = null
-    }
-  }
-
-  return {
-    subscribe(onChange, keepAlive) {
-      subscribers.set(onChange, keepAlive)
-      updateInterval()
-      return () => {
-        subscribers.delete(onChange)
-        updateInterval()
-      }
-    },
-    // ...
-  }
-}
-```
-
-### 不确定部分
-
-无法确认 `useAnimationFrame` hook 是否在所有使用时钟的组件中正确传递了 `keepAlive` 参数。反编译代码中调用链可能不完整。
-
---
-
-## 5. 虚拟滚动器保留历史消息拷贝 (v2.1.101)
-
-
-**CHANGELOG 描述**：Fixed a memory leak where long sessions retained dozens of historical copies of the message list in the virtual scroller
-
-### 实现位置
-
- `src/components/VirtualMessageList.tsx:276-296`
-
-### 修复方式
-
-增量式键值数组：使用 `useRef` 保存 keys 数组引用，流式追加而非每次 O(n) 全量重建。
-
-```typescript
-// VirtualMessageList.tsx:276-296
-const keysRef = useRef<string[]>([])
-const prevMessagesRef = useRef<typeof messages>(messages)
-const prevItemKeyRef = useRef(itemKey)
-if (
-  prevItemKeyRef.current !== itemKey ||
-  messages.length < keysRef.current.length ||
-  messages[0] !== prevMessagesRef.current[0]
-) {
-  // 全量重建（仅在 itemKey 变化、数组缩短等场景）
-  keysRef.current = messages.map(m => itemKey(m))
-} else {
-  // 增量追加（正常流式场景）
-  for (let i = keysRef.current.length; i < messages.length; i++) {
-    keysRef.current.push(itemKey(messages[i]!))
-  }
-}
-prevMessagesRef.current = messages
-prevItemKeyRef.current = itemKey
-const keys = keysRef.current
-```
-
-修复前 27k 消息时每次新消息添加产生 ~1MB 内存分配，修复后降为 O(1) 追加。
-
---
-
-## 6. 管道模式超宽行过度分配 (v2.1.110)
-
-
-**CHANGELOG 描述**：Fixed potential excessive memory allocation when piped (non-TTY) Ink output contains a single very wide line
-
-### 实现位置
-
- `packages/@ant/ink/src/core/output.ts:200-207`
-
-### 修复方式
-
-在 `Output.reset()` 中当字符缓存超过 16384 条目时清空：
-
-```typescript
-// output.ts:200-207
-reset(width: number, height: number, screen: Screen): void {
-  this.width = width
-  this.height = height
-  this.screen = screen
-  this.operations.length = 0
-  resetScreen(screen, width, height)
-  if (this.charCache.size > 16384) this.charCache.clear()  // 关键修复
-}
-```
-
---
-
-## 7. 语言语法按需加载 (v2.1.108)
-
-**状态：已修复**
-
-**CHANGELOG 描述**：Reduced memory footprint for file reads, edits, and syntax highlighting by loading language grammars on demand
-
-### 实现位置
-
- `packages/color-diff-napi/src/index.ts:21-37`
-
-### 当前状态
-
-延迟加载逻辑**已被移除**，改为顶层静态导入。代码注释说明原因：
-
-```typescript
-// color-diff-napi/src/index.ts:21-37
-// Static import — createRequire(import.meta.url) fails in Bun --compile mode
-// because the resolved path points to the internal bunfs binary path where
-// node_modules cannot be found. A top-level import ensures the module is
-// bundled and accessible at runtime.
-import hljs from 'highlight.js'  // 顶层静态导入
-
-type HLJSApi = typeof hljs
-let cachedHljs: HLJSApi | null = null
-function hljsApi(): HLJSApi {
-  if (cachedHljs) return cachedHljs
-  const mod = hljs as HLJSApi & { default?: HLJSApi }
-  cachedHljs = 'default' in mod && mod.default ? mod.default : mod
-  return cachedHljs!
-}
-```
-
-**影响**：highlight.js 包含 190+ 语言语法（约 50MB），现在在模块加载时即全部载入内存，无法按需释放。这是为了兼容 Bun `--compile` 模式做的妥协。
-
---
-
-## 8. NO_FLICKER 模式流状态泄漏 (v2.1.105)
-
-**状态：已修复**
-
-**CHANGELOG 描述**：Fixed a NO_FLICKER mode memory leak where API retries left stale streaming state
-
-### 实现位置
-
- `src/screens/REPL.tsx:1841-1861` — `resetLoadingState()`
- `src/screens/REPL.tsx:3568-3578` — finally 块调用
-
-### 已实现部分
-
-`resetLoadingState()` 在 `onQuery` 的 finally 块中无条件调用，清理 `streamingText`、`streamingToolUses` 等：
-
-```typescript
-// REPL.tsx:1841-1861
-const resetLoadingState = useCallback(() => {
-  setStreamingText(null);
-  setStreamingToolUses([]);
-  setSpinnerMessage(null);
-  // ...
-}, [pickNewSpinnerTip]);
-
-// REPL.tsx:3568-3578 — finally 块
-} finally {
-  if (queryGuard.end(thisGeneration)) {
-    resetLoadingState();  // 无条件清理
-  }
-}
-```
-
-### 不确定部分
-
-无法确认 `query.ts` 中 `StreamingToolExecutor.discard()` 的逻辑是否完整实现了旧工具结果的释放。
-
---
-
-## 9. Remote Control 权限条目保留 (v2.1.98)
-
-**状态：已修复**
-
-**CHANGELOG 描述**：Fixed a memory leak where Remote Control permission handler entries were retained for the lifetime of the session
-
-### 实现位置
-
- `src/hooks/useReplBridge.tsx:466-491` — 处理 + 删除
- `src/hooks/useReplBridge.tsx:712-717` — 注册 + 清理函数
-
-### 已实现部分
-
-```typescript
-// useReplBridge.tsx:466-491
-const pendingPermissionHandlers = new Map<string, (response: ...) => void>()
-
-function handlePermissionResponse(msg: SDKControlResponse): void {
-  const requestId = msg.response?.request_id
-  if (!requestId) return
-  const handler = pendingPermissionHandlers.get(requestId)
-  if (!handler) return
-  const parsed = parseBridgePermissionResponse(msg)
-  if (!parsed) return
-  pendingPermissionHandlers.delete(requestId)  // 处理后删除
-  handler(parsed)
-}
-
-// useReplBridge.tsx:712-717
-onResponse(requestId, handler) {
-  pendingPermissionHandlers.set(requestId, handler)
-  return () => {
-    pendingPermissionHandlers.delete(requestId)  // 取消时删除
-  }
-}
-```
-
-### 不确定部分
-
-hook 的 cleanup 函数（组件卸载时的 `replBridgePermissionCallbacks = undefined`）是否完整调用。
-
---
-
-## 10. MCP HTTP/SSE 缓冲区累积 (v2.1.97)
-
-
-**CHANGELOG 描述**：Fixed MCP HTTP/SSE connections accumulating ~50 MB/hr of unreleased buffers when servers reconnect
-
-### 实现位置
-
- `src/services/api/claude.ts:1557-1564` — `releaseStreamResources()`
- `src/cli/transports/SSETransport.ts:419` — `reader.releaseLock()`
- `@modelcontextprotocol/sdk` (sse.js, streamableHttp.js) — `response.body?.cancel()`
-
-### 修复方式
-
-1. **主动释放响应体**：`releaseStreamResources()` 清理 stream 和 response
-
-```typescript
-// claude.ts:1553-1564
-// Release all stream resources to prevent native memory leaks.
-// The Response object holds native TLS/socket buffers that live outside the
-// V8 heap (observed on the Node.js/npm path; see GH #32920), so we must
-// explicitly cancel and release it regardless of how the generator exits.
-function releaseStreamResources(): void {
-  cleanupStream(stream)
-  stream = undefined
-  if (streamResponse) {
-    streamResponse.body?.cancel().catch(() => {})
-    streamResponse = undefined
-  }
-}
-```
-
-2. **SSE 读取器释放**：
-
-```typescript
-// SSETransport.ts:418-419
-} finally {
-  reader.releaseLock()
-}
-```
-
-3. **MCP SDK 层面**：在所有 HTTP 路径（成功/失败/重连）调用 `response.body?.cancel()`
-
---
-
-## 11. LRU 缓存键保留大 JSON (v2.1.89)
-
-**状态：已确认完整实现**
-
-
-**CHANGELOG 描述**：Fixed memory leak where large JSON inputs were retained as LRU cache keys in long-running sessions
-
-### 实现位置
-
- `src/utils/fileStateCache.ts:37-48` — 大小计算修复
- `src/utils/queryHelpers.ts:48-54` — 类型强制转换
-
-### 修复方式
-
-1. **正确计算缓存大小**：处理 `content` 为嵌套对象的情况
-
-```typescript
-// fileStateCache.ts:37-48
-sizeCalculation: value => {
-  const c = value.content
-  const s =
-    typeof c === 'string'
-      ? c
-      : c === null || c === undefined
-        ? ''
-        : typeof c === 'object'
-          ? JSON.stringify(c)
-          : String(c)
-  return Math.max(1, Buffer.byteLength(s, 'utf8'))
-}
-```
-
-2. **强制类型转换**：确保 Write 工具 content 始终为字符串
-
-```typescript
-// queryHelpers.ts:48-54
-function coerceToolContentToString(value: unknown): string {
-  if (typeof value === 'string') return value
-  if (value === null || value === undefined) return ''
-  if (typeof value === 'object') return JSON.stringify(value)
-  return String(value)
-}
-```
-
---
-
-## 12. QueryEngine.mutableMessages 不收缩
-
-**状态：已修复**
-
-**代码注释描述**：`markers persist and re-trigger on every turn, and mutableMessages never shrinks (memory leak in long SDK sessions)`（`src/QueryEngine.ts:929-930`）
-
-### 实现位置
-
- `src/services/compact/snipCompact.ts` — **存根文件**
- `src/QueryEngine.ts:925-962` — 消息处理逻辑
-
-### 问题详情
-
-`mutableMessages` 数组只增不减，每轮对话 push 多条消息（assistant、progress、user、attachment 等）。清理依赖两条路径：
-
-**路径 1：API 返回 compact_boundary**（已实现）
-
-```typescript
-// QueryEngine.ts:946-962
-if (msg.subtype === 'compact_boundary' && msg.compactMetadata) {
-  const mutableBoundaryIdx = this.mutableMessages.length - 1
-  if (mutableBoundaryIdx > 0) {
-    this.mutableMessages.splice(0, mutableBoundaryIdx)  // 清理旧消息
-  }
-}
-```
-
-**路径 2：本地 snip 压缩**（存根 — 永不执行）
-
-```typescript
-// snipCompact.ts — 完整文件
-// Auto-generated stub — replace with real implementation
-export {};
-import type { Message } from 'src/types/message';
-
-export const isSnipMarkerMessage: (message: Message) => boolean = () => false;
-export const snipCompactIfNeeded: (
-  messages: Message[],
-  options?: { force?: boolean },
-) => { messages: Message[]; executed: boolean; tokensFreed: number; boundaryMessage?: Message } = (messages) => ({
-  messages,
-  executed: false,   // 永远 false — 清理从不执行
-  tokensFreed: 0,
-});
-export const isSnipRuntimeEnabled: () => boolean = () => false;
-export const shouldNudgeForSnips: (messages: Message[]) => boolean = () => false;
-export const SNIP_NUDGE_TEXT: string = '';
-```
-
-`snipReplay` 回调依赖 `HISTORY_SNIP` feature flag，且调用的 `snipCompactIfNeeded` 永远返回 `executed: false`。
-
-```typescript
-// QueryEngine.ts:933-942
-const snipResult = this.config.snipReplay?.(msg, this.mutableMessages)
-if (snipResult !== undefined) {
-  if (snipResult.executed) {       // 永远是 false
-    this.mutableMessages.length = 0
-    this.mutableMessages.push(...snipResult.messages)
-  }
-  break
-}
-```
-
-### 风险评估
-
- 在长时间 SDK 会话中，如果 API 不频繁返回 `compact_boundary`，`mutableMessages` 会持续增长
- 每条消息可能包含大量内容（工具输出、文件内容等），长时间运行可能导致 GB 级内存占用
- 这是当前代码库中**最明确的未实现内存泄漏点**
-
---
-
-## 17. LSP Opened Files Map 不收缩
-
-**状态：已修复**
-
-**代码注释描述**：`closeFile()` 存在但未与 compact 流程集成（`LSPServerManager.ts:373-375` 显式标注为 TODO）
-
-### 实现位置
-
- `src/services/lsp/LSPServerManager.ts:414-428` — `closeAllFiles()` 方法
- `src/services/compact/postCompactCleanup.ts:81-88` — 集成调用
-
-### 问题详情
-
-`LSPServerManager` 中的 `openedFiles: Map<string, string>` 追踪所有通过 `didOpen` 打开的文件。`closeFile()` 方法存在可以发送 `didClose` 通知并清理 Map 条目，但代码注释明确标注：
-
-```
-NOTE: Currently available but not yet integrated with compact flow.
-TODO: Integrate with compact - call closeFile() when compact removes files from context
-```
-
-长时间会话中，每次读取/编辑文件都会通过 `openFile()` 添加条目，但 compaction 不会清理这些条目，导致 Map 无限增长。
-
-### 修复方式
-
-1. **添加 `closeAllFiles()` 方法**：遍历 `openedFiles` Map，对每个文件发送 `didClose` 通知，然后清空 Map。Best-effort 错误处理。
-
-```typescript
-async function closeAllFiles(): Promise<void> {
-  const entries = [...openedFiles.entries()]
-  openedFiles.clear()
-  for (const [fileUri, serverName] of entries) {
-    const server = servers.get(serverName)
-    if (!server || server.state !== 'running') continue
-    try {
-      await server.sendNotification('textDocument/didClose', {
-        textDocument: { uri: fileUri },
-      })
-    } catch {
-      // Best-effort — server may have stopped
-    }
-  }
-}
-```
-
-2. **集成到 `postCompactCleanup`**：在 compaction 后自动调用 `closeAllFiles()`，释放所有 LSP 服务器端的文件状态。
-
-```typescript
-// postCompactCleanup.ts
-try {
-  const lspManager = getLspServerManager()
-  if (lspManager) {
-    await lspManager.closeAllFiles()
-  }
-} catch {
-  // LSP module may not be available in all environments
-}
-```
-
---
-
-## 总结
-
-```
-确认已实现 (12):  #1 图片  #2 /usage  #3 进度消息  #4 空闲渲染  #5 虚拟滚动器  #6 管道输出  #10 MCP缓冲区
-已修复 (7):       #7 语法加载  #8 NO_FLICKER  #9 RC权限  #11 LRU缓存键  #12 snipCompact  #17 LSP文件追踪  #18 Permission Polling
-
-### 测试覆盖
-
-| 修复项 | 测试文件 | 测试数 |
-|--------|----------|--------|
-| #12 snipCompact | `src/services/compact/__tests__/snipCompact.test.ts` | 17 |
-| #12 snipProjection | `src/services/compact/__tests__/snipProjection.test.ts` | 11 |
-| #8 StreamingToolExecutor | `src/services/tools/__tests__/StreamingToolExecutor.test.ts` | 7 |
-| #9 RC 权限 | `src/hooks/__tests__/replBridgePermissionHandlers.test.ts` | 8 |
-| #11 FileStateCache | `src/utils/__tests__/fileStateCache.test.ts` | 22 |
-| #7 语言注册 | `packages/color-diff-napi/src/__tests__/language-registration.test.ts` | 7 |
-| #18 Permission Polling | `src/hooks/__tests__/swarmPermissionPoller.test.ts` | 6 |
-| #17 LSP Opened Files | `src/services/lsp/__tests__/closeAllFiles.test.ts` | 5 |
-| **总计** | **8 个测试文件** | **83** |
-```
-
-### 需要关注的优先级
-
-1. ~~**P0 — `snipCompact.ts` 存根**~~ **已修复**
-2. ~~**P1 — 语法按需加载回退**~~ **已修复**
-3. ~~**P2 — NO_FLICKER 流状态**~~ **已修复**
-4. ~~**P2 — 空闲渲染循环**~~ **已确认完整**
-5. ~~**P2 — Permission Polling Interval**~~ **已修复**
-6. ~~**P2 — LSP Opened Files Map**~~ **已修复**：closeAllFiles() 集成到 postCompactCleanup
--- a/docs/memory-peak-analysis.md
+++ b/docs/memory-peak-analysis.md
@@ -1,103 +0,0 @@
-# 内存与性能峰值分析报告
-
-> 进程 bun，RSS 基线 **682 MB**，最差 **1.8 GB** | 2026-05-02 | **调研完成**（12 轮迭代）
-> 修复 commit：`ef10ad28` + `ab0bbbc4`（降 100-300 MB）| 架构限制：Bun mimalloc/JSC 不归还内存页（~150-250 MB 永久占用）
-
-## 已修复（10 项）
-
-| 问题 | 原峰值 | 修复 | 位置 |
-|------|--------|------|------|
-| 流式字符串拼接 O(n²) | 2-20 MB | `+=` → 数组累积 | `claude.ts:1834,2271` |
-| Messages.tsx 多次遍历 | 100-270 MB | 合并单次 pass | `Messages.tsx:417-418` |
-| ColorFile 无缓存 | 50-100 MB | LRU-50 | `HighlightedCode.tsx:14-61` |
-| Ink StylePool 无界 | 10-50+ MB | 1000 上限 | `@ant/ink/screen.ts:122` |
-| CompanionSprite 高频 | CPU | TICK_MS→1000ms | `CompanionSprite.tsx:15` |
-| MCP stderr 缓冲 | 1-640 MB | 64→8MB/server | `mcp-client/connection.ts:117` |
-| BashTool 输出缓冲 | 30-330 MB | 32→2MB | `stringUtils.ts:88` |
-| Transcript 写入队列 | 5-50 MB | 1000 上限 | `sessionStorage.ts:613-619` |
-| contentReplacementState | 持续增长 | compact 清理 | `compact/compact.ts` |
-| SSE 缓冲 | 无上限 | 1MB cap | SSE 处理代码 |
-
-## P0 — 核心瓶颈（6 项）
-
-| # | 问题 | 峰值 | 位置 | 建议 |
-|---|------|------|------|------|
-| 1 | 消息数组 7-8x spread 拷贝（turn 尾部 3-4 份同时驻留） | 120-320 MB | `query.ts` 7 处（:477,:491,:897,:1135,:1745,:1857,:1878） | 去掉 spread / 传引用 / 改 push |
-| 2 | AutoCompact 时序缺陷（检查在 API 前，增长在 API 后） | API 超限 | `query.ts:575` | 加入预测式阈值检查 |
-| 3 | reactiveCompact 空存根（API 413 时无紧急压缩） | 无降级 | `reactiveCompact.ts` 全文 | 实现真实逻辑 |
-| 4 | buildMessageLookups 8 Map/Set 重建（流式每个 delta 触发） | GC STW 100-173ms | `Messages.tsx:519` | 增量更新 / 拆分 useMemo 链 |
-| 5 | useDeferredValue 双缓冲 | 100-200 MB | `REPL.tsx:1569` | React 调度机制固有，优化空间有限 |
-| 6 | Compact 峰值窗口（preCompactReadFileState + summary + attachments） | 20-80 MB | `compact.ts:524-644` | 提前释放 preCompactReadFileState/summaryResponse |
-
-## P1 — 重要瓶颈（14 项）
-
-| # | 问题 | 峰值 | 位置 | 建议 |
-|---|------|------|------|------|
-| 7 | OpenAI/Gemini/Grok 兼容层 O(n²) 拼接 | 25-75 MB | 3 文件 9 处（`openai/index.ts:386`, `gemini/index.ts:148`, `grok/index.ts:163`） | 改数组累积（同 claude.ts 模式） |
-| 8 | messages.ts O(n²) 拼接 | 10-25 MB | `messages.ts:3252,3268` | 改数组累积 |
-| 9 | highlight.js 全量 192 语言（仅需 26 种） | 8-12 MB | `color-diff-napi/index.ts:21` | 自定义构建 |
-| 10 | hlLineCache 模块级单例 2048 条目 | ~4 MB | `color-diff-napi/index.ts:508` | 改 LRU + size 上限 |
-| 11 | colorFileCache 3x 代码存储 | 2-5 MB | `HighlightedCode.tsx:14` | 移除 value 中 code 字段 |
-| 12 | 虚拟滚动 200 组件常驻 | 50 MB | `useVirtualScroll.ts` | 降低 OVERSCAN_ROWS / MAX_MOUNTED_ITEMS |
-| 13 | FileReadTool 大文件（输出上限 100K 字符，但读取期间完整加载） | 临时数 MB | `FileReadTool.ts:342` | 读取前检测大小，流式截断 |
-| 14 | Session 恢复全量加载（磁盘→JSON→REPL 三阶段） | 200-300 MB | `sessionStorage.ts:3482` | 流式 JSONL / 增量恢复 |
-| 15 | Session 写入 100MB 累积 | ~100 MB | `sessionStorage.ts:652` | 流式写入 |
-| 16 | Forked Agent FileStateCache 完整克隆 | 50N MB | `forkedAgent.ts:382` | 共享/分层缓存（agent 用 10MB） |
-| 17 | GC 阈值 350MB < 基线（每秒无意义强制 GC） | CPU 浪费 | `cli/print.ts:554` | 提高到 800MB+ |
-| 18 | PDF 100 页处理 | ~100 MB | `apiLimits.ts:54` | 分页流式处理 |
-| 19 | 图片单张处理（base64→解码→resize） | ~16 MB/张 | `apiLimits.ts:22` | 流式 resize |
-| 20 | token 估算 ±25-50% 误差放大时序问题 | 阈值不准 | `tokenEstimation.ts:215` | 内容类型感知估算 |
-
-## P2 — 次要问题（10 项）
-
-| # | 问题 | 峰值 | 位置 |
-|---|------|------|------|
-| 21 | lastAPIRequestMessages 常驻 | 30-50 MB | `bootstrap/state.ts:118` |
-| 22 | MCP Tool Schema 双重存储 | ~40 MB | `manager.ts:73` + `AppStateStore.ts:175` |
-| 23 | ContentReplacementState 单调增长 | 0.5-2 MB | `toolResultStorage.ts:390` |
-| 24 | Perfetto 100K 事件 | ~30 MB | `perfettoTracing.ts:106` |
-| 25 | StreamingMarkdown 双渲染 | 临时 | `Markdown.tsx:185` |
-| 26 | MarkdownTable 3 次遍历 | CPU 峰值 | `MarkdownTable.tsx:99` |
-| 27 | 搜索索引 WeakMap | 5-10 MB | `transcriptSearch.ts:17` |
-| 28 | ACP FileStateCache/会话 | 50 MB | `acp/agent.ts:554` |
-| 29 | Agent initialMessages 浅拷贝 | 1-5 MB/agent | `runAgent.ts:382` |
-| 30 | Hook 结果累积 | ~1 MB+ | `toolExecution.ts:1474` |
-
-## CPU / 渲染热点
-
-| # | 问题 | 影响 | 位置 |
-|---|------|------|------|
-| C2 | Ink 每次 React commit 触发 Yoga 布局 | ~1-3ms/commit | `reconciler.ts:279` → `ink.tsx:323` |
-| C3 | MessageRow 挂载 ~1.5ms（React/Yoga/Ink 管线开销） | 批量挂载 ~290ms 卡顿 | `useVirtualScroll.ts` |
-| C4 | 布局偏移触发全屏 damage | O(rows×cols) | `ink.tsx:655-661` |
-| C9 | 同步 fs 操作阻塞主线程 | 间歇卡顿 | `projectOnboardingState.ts:20` 等 |
-
-已有缓解：React ConcurrentRoot 批处理、帧率限制 16ms、虚拟滚动 overscan 80 + SLIDE_STEP=25 + useDeferredValue、Markdown tokenCache LRU-500 + hasMarkdownSyntax 快速路径、Yoga 增量缓存。
-
-## 已否认（12 轮汇总）
-
-VSZ 516 GB 是虚拟映射 | Zod ~650KB | Markdown LRU-500 已优化 | useSkillsChange/useSettingsChange 正确 cleanup | useInboxPoller 收敛设计（非循环）| React Compiler `_c(N)` 未使用 | File watchers ~5KB | React reconciler WeakMap + freeRecursive | Ink 屏幕缓冲 ~86KB | CharPool/HyperlinkPool ~1-5MB 5min 重置 | AWS/Google/Azure SDK 均懒加载 | Sentry 空实现 | useCallback 闭包通过 messagesRef 规避（无泄漏）| MCP stderrHandler 有 64MB cap + cleanup | useRef 有 clearConversation/compact 清理 | apiMetricsRef turn 结束重置 | useEffect 有 cleanup 函数 | lodash-es tree-shakable | AppState useSyncExternalStore 仅相关切片更新 | SDK 无全局重试队列 | Ink unmount 有清理
-
-## 结论
-
-**内存根因排序**：
-1. 消息数组 7-8x spread 拷贝（120-320 MB）— 核心瓶颈
-2. useDeferredValue 双缓冲 + React useMemo 链全量重算（100-200 MB + GC STW）
-3. Session 恢复/写入峰值（200-300 MB）
-4. AutoCompact 时序缺陷 + reactiveCompact 空存根（API 超限风险）
-5. Forked Agent FileStateCache 克隆（50N MB）
-6. 虚拟滚动 200 组件 ~50MB 常驻
-7. Bun/JSC 不归还内存页（架构级）
-
-**CPU 根因**：useInboxPoller 每秒轮询 → React commit → Yoga 布局 → 全屏 Ink diff 完整管线。Markdown 渲染批量挂载时 ~290ms 卡顿。
-
-**预估优化空间**：
-
-| 优先级 | 措施数 | 预估降低 |
-|--------|--------|----------|
-| P0 | 6 | 240-600 MB |
-| P1 | 14 | 300-600 MB |
-| P2 | 10 | 80-200 MB |
-| **合计** | **30 项** | **620-1400 MB** |
-
-理论可从 400-700 MB 降至 **200-350 MB**（受 mimalloc/JSC 架构限制约束）。
--- a/docs/performance-reporter.md
+++ b/docs/performance-reporter.md
@@ -1,54 +0,0 @@
-# 内存占用 1G 调研报告
-
-> 诊断 session `a3593062` RSS 达 1.09 GB，定位 Bun 运行时内存膨胀根因
-
-## 数据收集
-
- **诊断数据**: RSS 1,118 MB，V8 heap 84 MB，原生内存缺口 1,034 MB（92%）
- **构建方式**: `bun run build:vite` → Vite/Rollup 单文件构建，产物 17MB `dist/cli.js`
- **Vite 配置**: `codeSplitting: false`（`vite.config.ts:97`），所有代码内联为单文件
- **Node.js 对比**: 相同 17MB 产物，Node.js RSS 仅 223 MB（`--version`）/ 340 MB（完整加载）
-
-## 探索与验证
-
-### 已确认
-
-| 问题 | 位置 | 说明 |
-|------|------|------|
-| **根因: Vite 单文件构建 + Bun 解析大文件内存效率低** | `vite.config.ts:97` | `codeSplitting: false` 产出 17MB 单文件，Bun/JSC 解析时 RSS 暴涨至 966MB |
-| Node.js 对同等 17MB 文件仅需 223MB | 实测 | V8 对大文件解析的内存效率远优于 JSC |
-| Bun.build 代码分割可解决问题 | 实测 | `bun run build`（代码分割 → 627 chunk）Bun RSS 仅 30MB（`--version`）/ 318MB（完整加载） |
-
-### 已否认
-
- 不是 feature flags 数量问题 — 全部 35 features 开启时，代码分割构建内存正常
- 不是内存泄漏 — `detachedContexts: 0`，`activeHandles: 0`
- 不是原生 addon 问题 — vendor 文件仅 2.7MB
- 不是 TypeScript 源码体量问题 — `bun run dev`（直接加载 TS）完整路径仅 345MB
-
-## 结论
-
-**根因是 Vite 构建配置 `codeSplitting: false`，产出 17MB 单文件，Bun/JSC 解析单文件大 JS 时内存效率极差（966MB vs Node 的 223MB）。**
-
-实测对比矩阵：
-
-| 构建方式 | 产物结构 | Bun RSS | Node RSS | Bun/Node |
-|----------|----------|---------|----------|----------|
-| `build:vite` | 17MB 单文件 | **966 MB** | 223 MB | 4.3x |
-| `build:vite` pipe mode | 同上 | **1,088 MB** | 340 MB | 3.2x |
-| `build` (Bun) | 627 chunk | 30 MB | 42 MB | 0.7x |
-| `build` (Bun) pipe mode | 同上 | 318 MB | 253 MB | 1.3x |
-| `bun run dev` TS 源码 | 动态加载 | 42 MB | — | — |
-| `bun run dev` pipe mode | 动态加载 | 345 MB | — | — |
-
-核心差异：
- **Node/V8** 解析 17MB 文件只需 223MB — V8 的懒解析（lazy parsing）只编译入口需要的部分
- **Bun/JSC** 解析 17MB 文件需要 966MB — JSC 对单文件做全量编译，bytecode + JIT 占用大量原生内存
- 代码分割后（627 个小 chunk），Bun 按需加载，内存回到正常水平
-
-## 建议
-
-1. **开启 Vite 代码分割** — 在 `vite.config.ts` 中启用 `codeSplitting: true` 或使用 Rollup 的 `manualChunks` 配置。这是最直接的修复
-2. **或切换到 Bun.build** — `bun run build` 已默认启用代码分割（`splitting: true`），Bun RSS 仅 30-318MB
-3. **如果必须单文件** — 考虑用 Node.js 运行 Vite 产物（`node dist/cli-node.js`），代价是失去 Bun 特有 API
-4. **验证 `codeSplitting: false` 的存在理由** — 注释说"all dynamic imports inlined"，可能是为了简化部署。评估是否真的需要单文件
--- a/docs/safety/auto-mode.mdx
+++ b/docs/safety/auto-mode.mdx
@@ -137,7 +137,7 @@ Auto mode 可通过以下方式激活：

 ### 进入时（Full Instructions）

-注入到对话中的指令（`messages.ts:3481`）：
+注入到对话中的指令（`messages.ts:3464`）：

 > Auto mode is active. The user chose continuous, autonomous execution. You should:
 >
--- a/docs/safety/permission-model.mdx
+++ b/docs/safety/permission-model.mdx
@@ -18,19 +18,17 @@ keywords: ["权限模型", "Allow Ask Deny", "PermissionRule", "checkPermissions

 这些行为由 `PermissionResult` 类型定义（`src/utils/permissions/PermissionResult.ts`）。

-## 权限规则的来源
+## 权限规则的五层来源

-规则从 8 个来源汇聚（`PERMISSION_RULE_SOURCES`，`permissions.ts:109`），优先级从低到高（后者覆盖前者）：
+规则从 5 个来源汇聚（`PERMISSION_RULE_SOURCES`，`permissions.ts:109`），优先级从高到低：

 ```
-1. userSettings   — ~/.claude/settings.json（跨项目）
-2. projectSettings — .claude/settings.json（团队共享）
-3. localSettings  — .claude/settings.local.json（gitignored，个人覆盖）
-4. flagSettings   — --settings 命令行参数
-5. policySettings — 企业管理员下发的策略（用户不可覆盖）
-6. cliArg         — 命令行 --allow/--deny 参数
-7. command        — Skill 工具的 allowedTools 白名单
-8. session        — 用户在当前对话中手动授权（"Always allow"）
+1. session        — 用户在当前对话中手动授权（"Always allow"）
+2. cliArg         — 命令行 --allow/--deny 参数
+3. command        — Skill 工具的 allowedTools 白名单
+4. projectSettings — .claude/settings.json（团队共享）
+5. userSettings   — ~/.claude/settings.json（跨项目）
+6. policySettings — 企业管理员下发的策略（用户不可覆盖）
 ```

 每个来源维护三个数组：`alwaysAllowRules[source]`、`alwaysAskRules[source]`、`alwaysDenyRules[source]`。
@@ -67,7 +65,7 @@ MCP 工具使用 `getToolNameForPermissionCheck()` 获取匹配名称，支持

 **2. 命令模式匹配**（BashTool 的 `checkPermissions()`）

-BashTool 通过 `preparePermissionMatcher()`（`Tool.ts:520`）解析命令模式：
+BashTool 通过 `preparePermissionMatcher()`（`Tool.ts:514`）解析命令模式：
 ```json
 {"tool": "Bash", "ruleContent": "git *"}  → 匹配 "git commit -m 'fix'"
 ```
@@ -122,9 +120,7 @@ Read/Edit/Write 工具通过 `getPath()` 提取文件路径，与 `ruleContent`
 |------|---------------------|---------|------|
 | **Default** | `'default'` | 日常使用 | 敏感操作逐一确认 |
 | **Plan Mode** | `'plan'` | 探索阶段 | 只能读不能写（`isReadOnly()` 检查） |
-| **Accept Edits** | `'acceptEdits'` | 快速迭代 | 工作区内文件编辑自动放行，其他操作仍需确认 |
-| **Don't Ask** | `'dontAsk'` | 减少打断 | 尽量自动决策，减少确认弹窗 |
-| **Auto** | `'auto'` | 信任 AI | 通过 transcript classifier 自动决策（需 `TRANSCRIPT_CLASSIFIER` feature flag） |
+| **Auto** | `'auto'` | 信任 AI | 通过 transcript classifier 自动决策 |
 | **Bypass** | `'bypassPermissions'` | 完全信任 | 所有操作自动放行（需显式 `--dangerously-skip-permissions`） |

 Plan Mode 切换由 `EnterPlanModeTool.call()` 触发：
@@ -147,8 +143,8 @@ context.setAppState(prev => ({

 ```typescript
 const DENIAL_LIMITS = {
-  maxConsecutive: 3,        // 同一工具连续拒绝上限
-  maxTotal: 20,             // 总拒绝上限
+  maxDenialsPerTool: 3,        // 同一工具连续拒绝上限
+  cooldownPeriodMs: 30_000,    // 冷却期 30 秒
 }
 ```

@@ -166,12 +162,9 @@ const DENIAL_LIMITS = {

 ```typescript
 type PermissionUpdate =
-  | { type: 'addRules', destination, rules, behavior }
-  | { type: 'replaceRules', destination, rules, behavior }
-  | { type: 'removeRules', destination, rules, behavior }
-  | { type: 'setMode', destination, mode }
-  | { type: 'addDirectories', destination, directories }
-  | { type: 'removeDirectories', destination, directories }
+  | { type: 'addRule', behavior, rule, destination }
+  | { type: 'removeRule', behavior, rule, destination }
+  | { type: 'setMode', mode, destination }
 ```

 当用户在 Ask 对话框中选择 "Always allow"，系统调用 `persistPermissionUpdates()` 将规则写入对应层级的 settings 文件（project/user/managed），同时更新内存中的 `toolPermissionContext`。
--- a/docs/safety/plan-mode.mdx
+++ b/docs/safety/plan-mode.mdx
@@ -16,13 +16,13 @@ keywords: ["Plan Mode", "计划模式", "EnterPlanMode", "ExitPlanMode", "prepar

 <Steps>
  <Step title="EnterPlanMode — 进入计划模式">
-    AI 自主判断（或用户触发）任务需要规划，调用 `EnterPlanModeTool`（`packages/builtin-tools/src/tools/EnterPlanModeTool/EnterPlanModeTool.ts:36`）。该工具需要**用户审批**（`checkPermissions` 返回 `ask`）。
+    AI 自主判断（或用户触发）任务需要规划，调用 `EnterPlanModeTool`（`src/tools/EnterPlanModeTool/EnterPlanModeTool.ts:36`）。该工具需要**用户审批**（`checkPermissions` 返回 `ask`）。
  </Step>
  <Step title="探索阶段 — 只读工具集">
    权限模式切换为 `'plan'`，AI 只能使用 `isReadOnly()` 为 true 的工具（Read、Grep、Glob、Agent 等）。写操作被自动拒绝。
  </Step>
  <Step title="ExitPlanMode — 提交方案审批">
-    AI 完成探索后，调用 `ExitPlanModeV2Tool`（`packages/builtin-tools/src/tools/ExitPlanModeTool/ExitPlanModeV2Tool.ts:147`），将计划文件提交给用户审阅。这是第二个**需要用户审批**的节点。
+    AI 完成探索后，调用 `ExitPlanModeV2Tool`（`src/tools/ExitPlanModeTool/ExitPlanModeV2Tool.ts:147`），将计划文件提交给用户审阅。这是第二个**需要用户审批**的节点。
  </Step>
  <Step title="恢复执行 — 全部工具权限">
    用户批准后，权限模式恢复为进入前的状态，AI 按计划执行。
@@ -107,7 +107,7 @@ if (isTeammate()) {

 ## 什么时候该用计划模式

-`EnterPlanModeTool` 的 Prompt（`packages/builtin-tools/src/tools/EnterPlanModeTool/prompt.ts`）定义了两套触发标准——外部版本更积极（鼓励规划），内部版本更克制（仅在真正模糊时使用）：
+`EnterPlanModeTool` 的 Prompt（`src/tools/EnterPlanModeTool/prompt.ts`）定义了两套触发标准——外部版本更积极（鼓励规划），内部版本更克制（仅在真正模糊时使用）：

 | 场景 | 外部版本 | 内部版本 |
 |------|---------|---------|
--- a/docs/safety/sandbox.mdx
+++ b/docs/safety/sandbox.mdx
@@ -166,7 +166,7 @@ keywords: ["沙箱", "sandbox", "权限", "Bash", "PowerShell", "bubblewrap", "s
 5. 这条命令没有被显式排除
 6. 这次调用没有被允许以 `dangerouslyDisableSandbox` 绕过

-对应入口在 `packages/builtin-tools/src/tools/BashTool/shouldUseSandbox.ts` 和 `src/utils/sandbox/sandbox-adapter.ts`。
+对应入口在 `src/tools/BashTool/shouldUseSandbox.ts` 和 `src/utils/sandbox/sandbox-adapter.ts`。

 ### 3. PowerShell 只在支持平台上走

@@ -518,11 +518,11 @@ REPL / CLI 启动

 如果你想继续顺着源码深入，推荐按下面顺序看：

-1. `packages/builtin-tools/src/tools/BashTool/shouldUseSandbox.ts`
+1. `src/tools/BashTool/shouldUseSandbox.ts`
 2. `src/utils/Shell.ts`
 3. `src/utils/sandbox/sandbox-adapter.ts`
 4. `src/utils/permissions/permissions.ts`
-5. `packages/builtin-tools/src/tools/BashTool/bashPermissions.ts`
+5. `src/tools/BashTool/bashPermissions.ts`
 6. `src/utils/permissions/pathValidation.ts`
 7. `src/utils/permissions/filesystem.ts`

--- a/docs/safety/why-safety-matters.mdx
+++ b/docs/safety/why-safety-matters.mdx
@@ -61,7 +61,7 @@ Claude 的 System Prompt 中包含安全指令——这是"软性"约束，依
 | `deny` | 直接拒绝 | 匹配 deny 规则 |
 | `ask` | 弹窗确认 | 未匹配任何规则 或 匹配 ask 规则 |

-以 BashTool 为例（`packages/builtin-tools/src/tools/BashTool/bashPermissions.ts`），`bashToolHasPermission()` 执行了极其细致的检查链：
+以 BashTool 为例（`src/tools/BashTool/bashPermissions.ts`），`bashToolHasPermission()` 执行了极其细致的检查链：

 1. **AST 安全解析**：用 tree-sitter 解析 bash AST，检测命令注入（`$()`、反引号等）
 2. **语义检查**：识别危险命令（`eval`、`exec`、`source` 等）
@@ -169,7 +169,7 @@ Bash("rm -rf node_modules")  → ⚠️ 需确认（不可逆）
 攻击：cd /malicious/dir && git status
      /malicious/dir 包含 bare repo + 恶意钩子
 防御：bashToolHasPermission() 检测 cd + git 组合
-      强制 require approval（packages/builtin-tools/src/tools/BashTool/bashPermissions.ts:2209）
+      强制 require approval（src/tools/BashTool/bashPermissions.ts:2209）
 ```

 ### 场景3：管道注入
@@ -178,5 +178,5 @@ Bash("rm -rf node_modules")  → ⚠️ 需确认（不可逆）
 攻击：echo 'x' | xargs printf '%s' >> /etc/passwd
      splitCommand 会剥离重定向，导致路径检查遗漏
 防御：即使管道段独立检查通过，仍对原始命令重新验证路径约束
-      检查重定向目标中的危险模式（反引号、$()）（packages/builtin-tools/src/tools/BashTool/bashPermissions.ts:1992-2056）
+      检查重定向目标中的危险模式（反引号、$()）（bashPermissions.ts:1992-2056）
 ```
--- a/Show More
+++ b/Show More