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

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

.claude/skills/interview/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: interview
+description: "Interview me about my requirements"
+---
+
+Analyze these requirements "$ARGUMENTS" and interview me in detail using the AskUserQuestionTool about literally anything: technical implementation, UI & UX, concerns, tradeoffs, etc. but make sure the questions are not obvious.
+Be very in-depth and continue interviewing me continually until it's complete, then proceed in plan mode.
+
+Rules:
+
+- Every question MUST have a recommended option: place it first in options, append "(推荐)" to its label, and start its description with the recommendation reason.
+- All user-facing text (question, header, label, description) MUST be in Chinese.

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

@@ -0,0 +1,368 @@
+---
+name: teach-me
+description: "Personalized 1-on-1 AI tutor. Diagnoses level, builds learning path, teaches via guided questions, tracks misconceptions. Use when user wants to learn/study/understand a topic, says 'teach me', 'help me understand', or invokes /teach-me."
+---
+
+# Teach Me
+
+Personalized mastery tutor. Diagnose, question, advance on understanding.
+
+## Usage
+
+```bash
+/teach-me Python decorators
+/teach-me 量子力学 --level beginner
+/teach-me React hooks --resume
+```
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `<topic>` | Subject to learn (required, or prompted) |
+| `--level <level>` | Starting level: beginner, intermediate, advanced (default: diagnose) |
+| `--resume` | Resume previous session from `.claude/skills/teach-me/records/{topic-slug}/` |
+
+## Core Rules
+
+1. **Minimize lecturing, but don't be dogmatic.** Prefer questions that lead to discovery. For complete beginners with zero context, a brief 1-2 sentence framing is acceptable before asking.
+2. **Diagnose first.** Always probe current understanding before teaching.
+3. **Mastery gate.** Advance to next concept only when the learner can explain it clearly and apply it.
+4. **1-2 questions per round.** No more.
+5. **Patience + rigor.** Encouraging tone, but never hand-wave past gaps.
+6. **Language follows user.** Match the user's language. Technical terms can stay in English.
+7. **Always use AskUserQuestion.** Every question to the learner MUST use AskUserQuestion with predefined options. Never ask open-ended plain-text questions — users need options to anchor their thinking. Even conceptual/deep questions should offer 3-4 options plus let the user pick "Other" for free-form input. Options serve as scaffolding, not just convenience.
+
+## Output Directory
+
+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)
+```
+
+**Slug**: Topic in kebab-case, 2-5 words. Example: "Python decorators" → `python-decorators`
+
+## Workflow
+
+```
+Input → [Load Profile] → [Diagnose] → [Build Concept List] → [Tutor Loop] → [Session End]
+```
+
+### Step 0: Parse Input
+
+1. Extract topic. If none, use AskUserQuestion to ask what they want to learn (provide common categories as options).
+2. Detect language from user input.
+3. Load learner profile if `.claude/skills/teach-me/records/learner-profile.md` exists.
+4. Check for existing session:
+   - If `--resume`: read `session.md`, restore state, continue.
+   - If exists without `--resume`: use AskUserQuestion to ask whether to resume or start fresh.
+5. Create output directory: `.claude/skills/teach-me/records/{topic-slug}/`
+
+### Step 1: Diagnose Level
+
+Ask 2-3 questions to calibrate understanding, all via AskUserQuestion with predefined options.
+
+If learner profile exists, use it to skip known strengths and probe known weak areas.
+
+If `--level` provided, use as hint but still ask 1-2 probing questions.
+
+**Example for "Python decorators"**:
+
+Round 1 (AskUserQuestion):
+```
+header: "Level check"
+question: "Which of these Python concepts are you comfortable with?"
+multiSelect: true
+options:
+  - label: "Functions as values"
+  - label: "Closures"
+  - label: "The @ syntax"
+  - label: "Writing custom decorators"
+```
+
+Round 2 (AskUserQuestion — conceptual question with options as scaffolding):
+```
+header: "Understanding"
+question: "When Python sees @my_decorator above a function, what do you think happens?"
+multiSelect: false
+options:
+  - label: "It replaces the function with a new one"
+    description: "The decorator wraps or replaces the original function"
+  - label: "It's just syntax sugar for calling the decorator"
+    description: "@decorator is equivalent to func = decorator(func)"
+  - label: "It modifies the function in-place"
+    description: "The original function object is changed directly"
+  - label: "I'm not sure"
+    description: "No worries, we'll figure it out together"
+```
+
+### Step 2: Build Concept List
+
+Decompose topic into 5-15 atomic concepts, ordered by dependency. Save to `session.md`:
+
+```markdown
+# Session: {topic}
+- Level: {diagnosed}
+- Started: {timestamp}
+
+## Concepts
+1. ✅ Functions as first-class objects (mastered)
+2. 🔵 Higher-order functions (in progress)
+3. ⬜ Closures
+4. ⬜ Decorator basics
+...
+
+## Misconceptions
+- [concept]: "{what learner said}" → likely root cause: {analysis}
+
+## Log
+- [timestamp] Diagnosed: intermediate
+- [timestamp] Concept 1: pre-existing knowledge, skipped
+- [timestamp] Concept 2: started
+```
+
+Use simple status: ✅ mastered | 🔵 in progress | ⬜ not started | ❌ needs review
+
+Present the concept list to the learner as a brief text outline so they see the path ahead.
+
+### Step 3: Tutor Loop
+
+For each concept:
+
+#### 3a. Introduce (Brief)
+
+Set context with 1-2 sentences max, then ask an opening question via AskUserQuestion. Options serve as thinking scaffolds:
+
+Example for "closures":
+```
+header: "Closures"
+question: "A closure is a function that remembers variables from where it was created. Why might that be useful?"
+multiSelect: false
+options:
+  - label: "To create private state"
+    description: "Keep variables hidden from outside code"
+  - label: "To pass data between functions"
+    description: "Share information without global variables"
+  - label: "To cache expensive computations"
+    description: "Remember results for reuse"
+  - label: "I'm not sure yet"
+    description: "We'll explore this together"
+```
+
+#### 3b. Question Cycle
+
+ALL questions use AskUserQuestion. Design options that probe understanding — include a mix of correct, partially correct, and common-wrong-answer distractors. The user can always use "Other" for free-form input when they have a specific idea.
+
+**Option design tips**:
+- Include 1-2 correct answers (split nuance into separate options)
+- Include 1 distractor based on a common misconception
+- Include "I'm not sure" or "Let me think about it" as a safe option
+- Use descriptions to add hints or context to each option
+
+**Interleaving** (every 3-4 questions): Mix a previously mastered concept into the current question's options naturally. Don't announce it as review.
+
+Example (learning closures, already mastered higher-order functions):
+```
+header: "Prediction"
+question: "Here's a function that takes a callback and returns a new function. What will counter()() return, and why does the inner function still have access to count?"
+multiSelect: false
+options:
+  - label: "0, because count starts at 0"
+    description: "The inner function reads the initial value"
+  - label: "1, because count was incremented before returning"
+    description: "Closure captures the live variable, not a copy"
+  - label: "Error, because count is out of scope"
+    description: "The outer function already returned, so count is gone"
+  - label: "Undefined behavior"
+    description: "Depends on how the function was defined"
+```
+
+#### 3c. Respond to Answers
+
+| Answer Quality | Response |
+|----------------|----------|
+| Correct + good explanation | Brief acknowledgment, harder follow-up via AskUserQuestion |
+| Correct but shallow | "Good. Can you explain *why*?" — as AskUserQuestion with why-options |
+| Partially correct | "On the right track with [part]." — follow up with a more targeted AskUserQuestion |
+| Incorrect | "Interesting. Let's step back." — simpler AskUserQuestion to re-anchor |
+| "I don't know" / "Not sure" | "That's fine." — give a concrete example, then ask via AskUserQuestion with simpler options |
+
+**Hint escalation**: rephrase → simpler question → concrete example → point to principle → walk through minimal example together.
+
+#### 3d. Misconception Tracking
+
+On incorrect or partially correct answers, diagnose the underlying wrong mental model:
+
+1. Present a counter-example via AskUserQuestion — ask the learner to predict what happens, where the wrong mental model leads to a clearly wrong answer:
+```
+header: "Check this"
+question: "Given [counter-example], what do you think the output will be?"
+multiSelect: false
+options:
+  - label: "[wrong prediction from their mental model]"
+    description: "Based on what we discussed earlier"
+  - label: "[correct prediction]"
+    description: "A different perspective"
+  - label: "[another wrong prediction]"
+    description: "Yet another possibility"
+  - label: "I need to think more"
+    description: "Take your time"
+```
+2. Record in session.md under `## Misconceptions`
+3. When the learner sees the contradiction (their model predicts the wrong thing), guide them to articulate why.
+4. A misconception is resolved when the learner articulates why their old thinking was wrong AND handles a new scenario correctly.
+
+Never say "that's a misconception." Let them discover it.
+
+#### 3e. Mastery Check
+
+After 3-5 question rounds, assess qualitatively. The learner demonstrates mastery when they can:
+
+- Explain the concept in their own words
+- Apply it to a new scenario
+- Distinguish it from similar concepts
+- Find errors in incorrect usage
+
+If not ready: identify the specific gap and cycle back with targeted questions.
+
+#### 3f. Practice Phase
+
+Before marking mastered, give a small hands-on task via AskUserQuestion. Present the task as a code/output prediction or scenario choice:
+
+- **Programming**: Show a small code snippet and ask what it outputs or which fix is correct:
+```
+header: "Practice"
+question: "Here's a buggy decorator. What's wrong with it?"
+multiSelect: false
+options:
+  - label: "Missing return wrapper"
+    description: "The decorator doesn't return the inner function"
+  - label: "Wrong function signature"
+    description: "The wrapper doesn't accept *args, **kwargs"
+  - label: "Missing @functools.wraps"
+    description: "Metadata from the original function is lost"
+  - label: "I'd like to try writing one from scratch"
+    description: "Use 'Other' to write your own code"
+```
+- **Non-programming**: Ask to identify which scenario best applies the concept:
+```
+header: "Apply it"
+question: "Which real-world scenario best demonstrates [concept]?"
+multiSelect: false
+options:
+  - label: "[scenario A]"
+  - label: "[scenario B]"
+  - label: "[scenario C]"
+  - label: "I have my own example"
+    description: "Use 'Other' to share your own"
+```
+
+Keep it 2-5 minutes. Pass = mastered. Fail = diagnose gap, cycle back.
+
+#### 3g. Sync Progress (Every Round)
+
+Update `session.md` after each round:
+- Change concept status if applicable
+- Add new misconceptions or resolve existing ones
+- Append to log
+
+### Step 4: Session End
+
+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):
+
+```markdown
+# Learner Profile
+Updated: {timestamp}
+
+## Style
+- Learns best with: {concrete examples / abstract principles / visual ...}
+- Pace: {fast / moderate / needs-time}
+
+## Patterns
+- Tends to confuse X with Y
+- Recurring difficulty with: {area}
+
+## Topics
+- 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.
+
+## Resuming Sessions
+
+On `--resume`:
+
+1. Read `session.md` and `learner-profile.md`
+2. Quick check on 1-2 previously mastered concepts via AskUserQuestion:
+```
+header: "Quick review"
+question: "Last time you mastered [concept X]. Can you recall which of these is true about it?"
+multiSelect: false
+options:
+  - label: "[correct statement]"
+  - label: "[plausible distractor]"
+  - label: "[plausible distractor]"
+  - label: "I forgot this one"
+    description: "No worries, we'll revisit it"
+```
+3. If forgotten, mark as ❌ needs review and revisit before continuing
+4. Recap: "Last time you mastered [X]. You were working on [Y]."
+5. Continue from first in-progress or not-started concept
+
+## Notes
+
+- Keep it conversational, not mechanical
+- Vary question types: predict, compare, debug, extend, teach-back, connect
+- Slow down when struggling, speed up when flying
+- Interleaving should feel natural, not like a pop quiz
+- Wrong answers are more informative than right ones — never rush past them

.claude/skills/teach-me/references/pedagogy.md

@@ -0,0 +1,235 @@
+# Pedagogy Guide
+
+## Bloom's 2-Sigma Effect
+
+Benjamin Bloom (1984) found that students tutored 1-on-1 with mastery learning performed 2 standard deviations above conventional classroom students. The two key ingredients:
+
+1. **Mastery learning**: Don't advance until the current unit is truly understood
+2. **1-on-1 tutoring**: Adapt pace, style, and content to the individual learner
+
+## Socratic Method Integration
+
+Never lecture. Instead:
+- Ask questions that lead the learner to discover the answer
+- When they're stuck, don't explain — ask a simpler question
+- When they answer correctly, don't just confirm — ask them to explain why
+
+## Question Design Patterns
+
+### Diagnostic Questions (Step 1)
+
+Purpose: Quickly map what the learner knows and doesn't know.
+
+| Type | Example | Probes |
+|------|---------|--------|
+| Vocabulary check | "What does [term] mean to you?" | Do they know the words? |
+| Concept sorting | "Which of these are examples of X?" (AskUserQuestion) | Can they categorize? |
+| Prediction | "What do you think happens when...?" | Intuition level |
+| Explain-back | "Explain [concept] as if to a 10-year-old" | Depth of understanding |
+
+### Teaching Questions (Step 3)
+
+| Pattern | When | Example |
+|---------|------|---------|
+| **Predict** | Introducing new behavior | "What will this code print?" |
+| **Compare** | Distinguishing similar concepts | "How is X different from Y?" |
+| **Debug** | Testing careful reading | "This code has a bug. Can you find it?" |
+| **Extend** | Testing transfer | "Now how would you modify this to also handle...?" |
+| **Teach-back** | Confirming mastery | "Explain to me how [concept] works" |
+| **Connect** | Building knowledge graph | "How does [new concept] relate to [previous concept]?" |
+
+### Mastery Check Questions (Step 3g)
+
+These should be synthesis-level:
+- Combine the current concept with 1-2 previous concepts
+- Require application, not just recall
+- Include at least one novel scenario not seen during teaching
+
+### Interleaving Questions (Step 3b)
+
+Interleaving means mixing questions about old concepts into the current learning flow. Research (Rohrer & Taylor 2007, Dunlosky et al. 2013) shows interleaved practice improves long-term retention by ~43% compared to blocked practice.
+
+**Why it works**: Interleaving forces the learner to discriminate between concepts ("which tool applies here?"), which is a higher cognitive demand than applying a known concept. This discrimination practice is what builds durable, flexible knowledge.
+
+**How to design interleaving questions**:
+- The question must require BOTH the old concept and the current concept
+- Don't announce it as review — embed it naturally
+- Prioritize concepts that are easily confused with the current one
+- If the learner fails the old-concept part, it's a signal the old concept is decaying — note it for spaced repetition
+
+| Interleaving Pattern | Example |
+|---------------------|---------|
+| **Combine** | "Use both [old concept] and [new concept] to solve this" |
+| **Discriminate** | "Would you use [old concept] or [new concept] here? Why?" |
+| **Contrast** | "This looks similar to [old concept]. What's different?" |
+| **Layer** | "We used [old concept] to do X. Now add [new concept] on top." |
+
+## Mastery Scoring (Calibrated)
+
+### Rubric-Based Assessment
+
+Do NOT score based on vague impression. Use these 4 criteria for each mastery check question:
+
+| Criterion | Weight | What to look for |
+|-----------|--------|------------------|
+| **Accurate** | 1 point | Factually/logically correct answer |
+| **Explained** | 1 point | Learner articulates the WHY, not just the WHAT |
+| **Novel application** | 1 point | Can apply to a scenario not seen during teaching |
+| **Discrimination** | 1 point | Can distinguish from similar/related concepts |
+
+Score per question = criteria met / 4. Concept mastery requires >= 3/4 on each mastery check question AND >= 80% overall concept score.
+
+### Self-Assessment Calibration
+
+Ask the learner to self-assess BEFORE revealing your evaluation. Compare:
+
+| Self vs Rubric | What it means | Action |
+|----------------|---------------|--------|
+| Both high | Good metacognition, true mastery | Proceed to practice phase |
+| Self HIGH, rubric LOW | **Fluency illusion** — most dangerous | Flag explicitly, show evidence of gaps |
+| Self LOW, rubric HIGH | Under-confidence | Reassure with specific evidence |
+| Both low | Honest awareness of gaps | Cycle back, adjust approach |
+
+**Fluency illusion** (Bjork, 1994): The feeling of understanding that comes from familiarity rather than actual comprehension. Common triggers: seeing a worked example and thinking "I could do that", recognizing terminology without being able to apply it, confusing passive exposure with active mastery.
+
+### Qualitative Signals
+
+Beyond the rubric, these signals indicate genuine mastery:
+- Learner can explain concept in their own words
+- Learner can give novel examples
+- Learner can identify errors in incorrect examples
+- Learner can connect concept to broader context
+
+## Misconception Handling
+
+### Why Misconceptions Matter More Than Gaps
+
+A gap in knowledge ("I don't know X") is easy to fill — just teach X. A misconception ("I know X, but my version of X is wrong") is far harder because the wrong model must be dismantled before the correct one can take hold. Research (Vosniadou 2013, Chi 2005) shows that misconceptions are the #1 barrier to learning in most domains.
+
+### Types of Misconceptions
+
+| Type | Example | Why it's sticky |
+|------|---------|----------------|
+| **Overgeneralization** | "All functions return values" | Correct in many cases, fails in edge cases |
+| **False analogy** | "Electricity flows like water" | Useful at first, breaks down at depth |
+| **Vocabulary confusion** | "Parameter and argument are the same" | Language reinforces the error daily |
+| **Causal reversal** | "Practice makes talent" (vs talent enables practice) | Correlation mistaken for causation |
+| **Incomplete model** | "Closures copy variables" (actually capture references) | Partially correct, fails under mutation |
+
+### The Counter-Example Method
+
+The most effective way to dislodge a misconception is NOT to say "that's wrong." It's to construct a scenario where the wrong model makes a clear, testable prediction — and then show reality contradicts it.
+
+Steps:
+1. **Identify** the wrong model from the learner's answer
+2. **Construct** a scenario where the wrong model predicts outcome A
+3. **Ask** the learner to predict the outcome (they'll predict A)
+4. **Reveal** that the actual outcome is B
+5. **Ask** the learner to explain the discrepancy
+6. **Wait** — let the learner wrestle with the contradiction. Do NOT explain immediately.
+7. **Guide** toward the correct model only after they've engaged with the contradiction
+
+### Misconception Resolution Criteria
+
+A misconception is resolved ONLY when BOTH conditions are met:
+1. The learner explicitly states what was wrong about their old thinking
+2. The learner correctly handles a new scenario that would have triggered the old misconception
+
+Getting the right answer once is NOT enough — they must also articulate why the old answer was wrong.
+
+## Spaced Repetition
+
+### The Forgetting Curve
+
+Ebbinghaus (1885) demonstrated that without review, memory decays exponentially:
+- After 1 hour: ~50% forgotten
+- After 1 day: ~70% forgotten
+- After 1 week: ~90% forgotten
+
+The only way to counteract this is **spaced review** — re-testing at increasing intervals.
+
+### Interval Schedule
+
+Sigma uses a simplified SM-2 inspired schedule:
+
+| Event | Next Review Interval |
+|-------|---------------------|
+| Concept first mastered | 1 day |
+| Review: correct | Double the interval (1d → 2d → 4d → 8d → 16d → 32d) |
+| Review: incorrect | Reset to 1 day |
+| Maximum interval | 32 days |
+
+### Review Question Design
+
+Review questions should be:
+- **Brief**: 1 question per concept, not a full mastery check
+- **Application-level**: Not "what is X?" but "use X to solve this small problem"
+- **Connected**: Where possible, connect the review concept to the current concept being learned (this also serves as interleaving)
+
+### Session Review Protocol
+
+On `--resume`, before continuing new content:
+1. Identify all mastered concepts where `days_since_review >= review_interval`
+2. Sort by most overdue first
+3. Review max 5 concepts per session (don't turn the session into all review)
+4. Adjust intervals based on results
+5. If a concept drops back to `in-progress`, address it before continuing forward
+
+## Deliberate Practice
+
+### Understanding ≠ Ability
+
+Ericsson's research on expert performance (1993) established that knowing how something works is fundamentally different from being able to do it. The gap between declarative knowledge ("I can explain decorators") and procedural knowledge ("I can write a decorator") requires practice to bridge.
+
+### Practice Task Design
+
+Good practice tasks for Sigma:
+
+| Property | Good | Bad |
+|----------|------|-----|
+| **Size** | 2-5 minutes | 30-minute project |
+| **Scope** | Tests one concept | Tests everything at once |
+| **Novelty** | New scenario, same concept | Repeat of a teaching example |
+| **Output** | Learner produces something | Learner answers more questions |
+| **Feedback** | Clear right/wrong signal | Ambiguous quality |
+
+### Practice vs More Questions
+
+Practice is NOT more Q&A. The key differences:
+
+| Dimension | Questions (3b) | Practice (3h) |
+|-----------|----------------|---------------|
+| Mode | Reactive (answer what's asked) | Generative (produce something new) |
+| Cognitive load | Recognition + recall | Planning + execution + self-monitoring |
+| Output | Words | Artifact (code, design, example, explanation) |
+| Feedback | Immediate from tutor | Self-discovered through doing |
+
+### The Generation Effect
+
+Slamecka & Graf (1978) showed that information the learner generates themselves is remembered 2-3x better than information they read. Practice tasks leverage this effect — the learner constructs knowledge through the act of doing.
+
+## Adaptive Pacing
+
+| Signal | Action |
+|--------|--------|
+| Answers quickly and correctly | Skip to harder questions, consider merging concepts |
+| Answers correctly but slowly | Proceed normally, give time |
+| Partially correct | Ask follow-up probing questions before moving on |
+| Consistently wrong | Break down into sub-concepts, use more concrete examples |
+| Frustrated | Switch to a visual aid, use analogy, acknowledge difficulty |
+| Bored | Increase difficulty, introduce real-world application |
+
+## Visual Aid Selection
+
+Use the right format for the right purpose:
+
+| Need | Format | When |
+|------|--------|------|
+| Show relationships | Excalidraw concept map | Concepts have dependencies or hierarchy |
+| Walk through process | HTML step-by-step | Code execution, algorithm steps |
+| Abstract idea | Generated image (nano-banana-pro) | Metaphors, mental models |
+| Compare options | HTML table/grid | Feature comparison, trade-offs |
+| Show flow/logic | Excalidraw flowchart | Decision trees, control flow |
+| Summarize progress | HTML dashboard | Milestones, session end |
+
+Don't generate visuals for every round — use them when they genuinely help understanding or when the learner seems stuck.

.dockerignore

@@ -0,0 +1,11 @@
+node_modules
+dist
+.git
+.githooks
+.github
+docs
+*.md
+packages/remote-control-server/data/*.db
+packages/remote-control-server/data/*.db-wal
+packages/remote-control-server/data/*.db-shm
+.claude

.editorconfig

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

.githooks/pre-commit

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

.github/ISSUE_TEMPLATE/bug_report.md

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

.github/ISSUE_TEMPLATE/config.yml

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

.github/ISSUE_TEMPLATE/feature_request.md

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

.github/workflows/ci.yml

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

.github/workflows/publish-npm.yml

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

.github/workflows/release-rcs.yml

@@ -0,0 +1,75 @@
+name: Release RCS Docker Image
+
+on:
+  push:
+    tags:
+      - 'rcs-v*'
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository_owner }}/remote-control-server
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2, 2026-04-25
+
+      - name: Login to GHCR
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3, 2026-04-25
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3, 2026-04-25
+
+      - name: Extract version
+        id: version
+        run: echo "VERSION=${GITHUB_REF_NAME#rcs-v}" >> "$GITHUB_OUTPUT"
+
+      - name: Generate tags
+        id: tags
+        run: |
+          VERSION="${{ steps.version.outputs.VERSION }}"
+          IMAGE="${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}"
+          TAGS="${IMAGE}:${VERSION}"
+          IFS='.' read -r MAJOR MINOR PATCH <<< "$VERSION"
+          if [ -n "$MAJOR" ] && [ -n "$MINOR" ]; then
+            TAGS="${TAGS},${IMAGE}:${MAJOR}.${MINOR}"
+          fi
+          TAGS="${TAGS},${IMAGE}:latest"
+          echo "tags=$TAGS" >> "$GITHUB_OUTPUT"
+
+      - name: Build Docker image
+        uses: docker/build-push-action@ca052bb54ab0790a636c9b5f226502c73d547a25 # v5, 2026-04-25
+        with:
+          context: .
+          file: packages/remote-control-server/Dockerfile
+          push: false
+          load: true
+          tags: ${{ steps.tags.outputs.tags }}
+          build-args: VERSION=${{ steps.version.outputs.VERSION }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Verify image
+        run: |
+          IMAGE_TAG=$(echo "${{ steps.tags.outputs.tags }}" | cut -d',' -f1)
+          docker run -d --name rcs-test -p 3000:3000 "$IMAGE_TAG"
+          sleep 5
+          curl -sf http://localhost:3000/health || { docker logs rcs-test; exit 1; }
+          docker stop rcs-test
+          docker rm rcs-test
+
+      - name: Push Docker image
+        run: |
+          IFS=',' read -ra TAGS <<< "${{ steps.tags.outputs.tags }}"
+          for TAG in "${TAGS[@]}"; do
+            docker push "$TAG"
+          done

.github/workflows/update-contributors.yml

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

.gitignore

@@ -5,7 +5,54 @@ coverage
 .env
 *.log
 .idea
-.vscode
+.vscode/*
+!.vscode/extensions.json
 *.suo
 *.lock
-src/utils/vendor/
+src/utils/vendor/
+
+# AI tool runtime directories
+.agents/
+.claude/
+.omx/
+.docs/task/
+# Binary / screenshot files (root only)
+/*.png
+*.bmp
+
+# Internal system prompt documents
+Claude-Opus-*.txt
+Claude-Sonnet-*.txt
+Claude-Haiku-*.txt
+
+# Agent / tool state dirs
+.swarm/
+.agents/__pycache__/
+
+# Python bytecode
+__pycache__/
+*.pyc
+logs
+
+data
+.omc
+.codex/*
+!.codex/agents/
+!.codex/agents/**
+!.codex/skills/
+!.codex/skills/**
+.codex/skills/.system/**
+!.codex/prompts/
+!.codex/prompts/**
+teach-me
+credentials.json
+
+# Session-scoped progress / state files written by agents and skills
+# (autofix-pr persistence, test-progress checkpoint, recovery notes).
+# Transient, never meant to enter the repo.
+.claude-impl-state.md
+.claude-progress.md
+.claude-recovery.md
+.test-progress.md
+.squash-tmp/
+.git.*-backup

.husky/pre-commit

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

.impeccable.md

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

.mintignore

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

.npmrc

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

.tool-versions

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

.vscode/extensions.json

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

.vscode/launch.json

@@ -1,13 +1,13 @@
 {
-    "version": "0.2.0",
-    "configurations": [
-        {
-            "type": "bun",
-            "request": "attach",
-            "name": "Attach to Bun (TUI debug)",
-            "url": "ws://localhost:8888/2dc3gzl5xot",
-            "stopOnEntry": false,
-            "internalConsoleOptions": "neverOpen"
-        }
-    ]
+	"version": "0.2.0",
+	"configurations": [
+		{
+			"type": "bun",
+			"request": "attach",
+			"name": "Attach to Claude Code",
+			"url": "ws://localhost:8888/2dc3gzl5xot",
+			"stopOnEntry": false,
+			"internalConsoleOptions": "neverOpen"
+		}
+	]
 }

.vscode/tasks.json

@@ -0,0 +1,27 @@
+{
+	"version": "2.0.0",
+	"tasks": [
+		{
+			"label": "Start Claude Code TUI",
+			"type": "shell",
+			"command": "bun run dev:inspect",
+			"isBackground": true,
+			"presentation": {
+				"reveal": "always",
+				"focus": true,
+				"panel": "dedicated",
+				"clear": true
+			},
+			"problemMatcher": {
+				"pattern": {
+					"regexp": "^$"
+				},
+				"background": {
+					"activeOnStart": true,
+					"beginsPattern": ".*Bun Inspector.*",
+					"endsPattern": ".*Listening:.*"
+				}
+			}
+		}
+	]
+}

AGENTS.md

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

CLAUDE.md

@@ -1,10 +1,25 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+This file provides guidance to Claude Code (claude.ai/code) and other AI coding agents when working with code in this repository.
 
 ## Project Overview
 
-This is a **reverse-engineered / decompiled** version of Anthropic's official Claude Code CLI tool. The goal is to restore core functionality while trimming secondary capabilities. Many modules are stubbed or feature-flagged off. The codebase has ~1341 tsc errors from decompilation (mostly `unknown`/`never`/`{}` types) — these do **not** block Bun runtime execution.
+This is a **reverse-engineered / decompiled** version of Anthropic's official Claude Code CLI tool. The goal is to restore core functionality while trimming secondary capabilities. Many modules are stubbed or feature-flagged off. TypeScript strict mode is enforced — **`bun run precheck` 必须零错误通过**（包含 typecheck + lint fix + test）。
+
+## Git Commit Message Convention
+
+使用 **Conventional Commits** 规范：
+
+```
+<type>: <描述>
+```
+
+常见 type：`feat`、`fix`、`docs`、`chore`、`refactor`
+
+示例：
+- `feat: 添加模型 1M 上下文切换`
+- `fix: 修复初次登陆的校验问题`
+- `chore: remove prefetchOfficialMcpUrls call on startup`
 
 ## Commands
 
@@ -21,18 +36,23 @@ bun run dev:inspect
 # Pipe mode
 echo "say hello" | bun run src/entrypoints/cli.tsx -p
 
-# Build (code splitting, outputs dist/cli.js + ~450 chunk files)
+# Build (code splitting, outputs dist/cli.js + chunk files)
 bun run build
 
-# Test
-bun test                  # run all tests
-bun test src/utils/__tests__/hash.test.ts   # run single file
-bun test --coverage       # with coverage report
+# Build with Vite (alternative build pipeline)
+bun run build:vite
 
-# Lint & Format (Biome)
-bun run lint              # check only
-bun run lint:fix          # auto-fix
-bun run format            # format all src/
+# Test
+bun test                                    # run all tests
+bun test src/utils/__tests__/hash.test.ts   # run single file
+bun test --coverage                         # with coverage report
+
+# Lint & Format (Biome) — 日常开发用 precheck 代替单独调用
+bun run lint              # lint check (全项目)
+bun run lint:fix          # auto-fix lint issues
+bun run format            # format all (全项目)
+bun run check             # lint + format check (全项目)
+bun run check:fix         # lint + format auto-fix
 
 # Health check
 bun run health
@@ -40,23 +60,35 @@ bun run health
 # Check unused exports
 bun run check:unused
 
+# Full check (typecheck + lint fix + test) — 任务完成后必须运行
+bun run precheck
+
+# Remote Control Server
+bun run rcs
+
 # Docs dev server (Mintlify)
 bun run docs:dev
 ```
 
-详细的测试规范、覆盖状态和改进计划见 `docs/testing-spec.md`。
+详细的测试规范、覆盖状态和改进计划见 `src/**/__tests__/` 与 `tests/integration/`。
 
 ## Architecture
 
 ### Runtime & Build
 
 - **Runtime**: Bun (not Node.js). All imports, builds, and execution use Bun APIs.
-- **Build**: `build.ts` 执行 `Bun.build()` with `splitting: true`，入口 `src/entrypoints/cli.tsx`，输出 `dist/cli.js` + chunk files。默认启用 `AGENT_TRIGGERS_REMOTE` feature。构建后自动替换 `import.meta.require` 为 Node.js 兼容版本（产物 bun/node 都可运行）。
-- **Dev mode**: `scripts/dev.ts` 通过 Bun `-d` flag 注入 `MACRO.*` defines，运行 `src/entrypoints/cli.tsx`。默认启用 `BUDDY`、`TRANSCRIPT_CLASSIFIER`、`BRIDGE_MODE`、`AGENT_TRIGGERS_REMOTE` 四个 feature。
+- **Build**: `build.ts` 执行 `Bun.build()` with `splitting: true`，入口 `src/entrypoints/cli.tsx`，输出 `dist/cli.js` + chunk files。Build 默认启用 19 个 feature（见下方 Feature Flag 段）。构建后自动替换 `import.meta.require` 为 Node.js 兼容版本（产物 bun/node 都可运行）。构建时会将 `vendor/audio-capture/` 和 `src/utils/vendor/ripgrep/` 复制到 `dist/vendor/` 下。
+- **Build (Vite)**: `vite.config.ts` + `scripts/post-build.ts`，代码分割模式，chunk 输出到 `dist/chunks/`。post-build 遍历 `dist/` 和 `dist/chunks/` 下所有 `.js` 文件做 `globalThis.Bun` 解构 patch，复制 vendor 文件到 `dist/vendor/`。
+- **Vendor 路径解析**: 构建后 chunk 文件位于 `dist/` 或 `dist/chunks/` 下，vendor 二进制在 `dist/vendor/`。`src/utils/distRoot.ts` 提供共享的 `distRoot` 函数，通过 `import.meta.url` 路径中 `lastIndexOf('dist')` 或 `lastIndexOf('src')` 定位根目录。`ripgrep.ts`、`computerUse/setup.ts`、`claudeInChrome/setup.ts`、`updateCCB.ts` 均使用 `distRoot` 而非内联 `import.meta.url` 路径推算。`packages/audio-capture-napi/src/index.ts` 有独立的 `lastIndexOf('dist')` 逻辑，功能等价。
+- **为什么 Vite 必须代码分割**: Bun/JSC 会全量解析单个大 JS 文件的 bytecode 和 JIT，单文件 17MB 产物导致 RSS 暴涨至 ~1GB（Node/V8 懒解析仅需 ~220MB）。代码分割为 600+ 小 chunk 后 Bun 按需加载，`--version` RSS 从 966MB 降至 35MB，完整加载从 1GB+ 降至 ~500MB。
+- **Dev mode**: `scripts/dev.ts` 通过 Bun `-d` flag 注入 `MACRO.*` defines，运行 `src/entrypoints/cli.tsx`。默认启用全部 feature。
 - **Module system**: ESM (`"type": "module"`), TSX with `react-jsx` transform.
-- **Monorepo**: Bun workspaces — internal packages live in `packages/` resolved via `workspace:*`.
-- **Lint/Format**: Biome (`biome.json`)。`bun run lint` / `bun run lint:fix` / `bun run format`。
-- **Defines**: 集中管理在 `scripts/defines.ts`。当前版本 `2.1.888`。
+- **Monorepo**: Bun workspaces — 17 个 workspace packages + 若干辅助目录 in `packages/` resolved via `workspace:*`。
+- **Lint/Format**: Biome (`biome.json`)。覆盖 `src/`、`scripts/`、`packages/` 全项目（含 `packages/@ant/`）。`bun run lint` / `bun run lint:fix` / `bun run format` / `bun run check` / `bun run check:fix`。42 条规则因 decompiled 代码被关闭，仅保留 `recommended` 基线。
+- **Pre-commit**: husky + lint-staged。提交时自动对暂存文件执行 `biome check --fix`（TS/JS）和 `biome format --write`（JSON）。
+- **CI Lint**: `ci.yml` 在依赖安装后、类型检查前执行 `bunx biome ci .`，lint 或格式化不达标则 CI 失败。
+- **Defines**: 集中管理在 `scripts/defines.ts`。当前版本 `2.2.1`。
+- **CI**: GitHub Actions — `ci.yml`（lint + 构建 + 测试）、`release-rcs.yml`（RCS 发布）、`update-contributors.yml`（自动更新贡献者）。
 
 ### Entry & Bootstrap
 
@@ -64,13 +96,16 @@ bun run docs:dev
    - `--version` / `-v` — 零模块加载
    - `--dump-system-prompt` — feature-gated (DUMP_SYSTEM_PROMPT)
    - `--claude-in-chrome-mcp` / `--chrome-native-host`
+   - `--computer-use-mcp` — 独立 MCP server 模式
    - `--daemon-worker=<kind>` — feature-gated (DAEMON)
-   - `remote-control` / `rc` / `bridge` — feature-gated (BRIDGE_MODE)
-   - `daemon` — feature-gated (DAEMON)
+   - `remote-control` / `rc` / `remote` / `sync` / `bridge` — feature-gated (BRIDGE_MODE)
+   - `daemon` [subcommand] — feature-gated (DAEMON)
    - `ps` / `logs` / `attach` / `kill` / `--bg` — feature-gated (BG_SESSIONS)
+   - `new` / `list` / `reply` — Template job commands
+   - `environment-runner` / `self-hosted-runner` — BYOC runner
    - `--tmux` + `--worktree` 组合
    - 默认路径：加载 `main.tsx` 启动完整 CLI
-2. **`src/main.tsx`** (~4680 行) — Commander.js CLI definition。注册大量 subcommands：`mcp` (serve/add/remove/list...)、`server`、`ssh`、`open`、`auth`、`plugin`、`agents`、`auto-mode`、`doctor`、`update` 等。主 `.action()` 处理器负责权限、MCP、会话恢复、REPL/Headless 模式分发。
+2. **`src/main.tsx`** (~5674 行) — Commander.js CLI definition。注册大量 subcommands：`mcp` (serve/add/remove/list...)、`server`、`ssh`、`open`、`auth`、`plugin`、`agents`、`auto-mode`、`doctor`、`update` 等。主 `.action()` 处理器负责权限、MCP、会话恢复、REPL/Headless 模式分发。
 3. **`src/entrypoints/init.ts`** — One-time initialization (telemetry, config, trust dialog)。
 
 ### Core Loop
@@ -82,21 +117,31 @@ bun run docs:dev
 ### API Layer
 
 - **`src/services/api/claude.ts`** — Core API client. Builds request params (system prompt, messages, tools, betas), calls the Anthropic SDK streaming endpoint, and processes `BetaRawMessageStreamEvent` events.
-- Supports multiple providers: Anthropic direct, AWS Bedrock, Google Vertex, Azure.
-- Provider selection in `src/utils/model/providers.ts`.
+- **7 providers**: `firstParty` (Anthropic direct), `bedrock` (AWS), `vertex` (Google Cloud), `foundry`, `openai`, `gemini`, `grok` (xAI)。
+- Provider selection in `src/utils/model/providers.ts`。优先级：modelType 参数 > 环境变量 > 默认 firstParty。
 
 ### Tool System
 
 - **`src/Tool.ts`** — Tool interface definition (`Tool` type) and utilities (`findToolByName`, `toolMatchesName`).
-- **`src/tools.ts`** — Tool registry. Assembles the tool list; some tools are conditionally loaded via `feature()` flags or `process.env.USER_TYPE`.
-- **`src/tools/<ToolName>/`** — 61 个 tool 目录（如 BashTool, FileEditTool, GrepTool, AgentTool, WebFetchTool, LSPTool, MCPTool 等）。每个 tool 包含 `name`、`description`、`inputSchema`、`call()` 及可选的 React 渲染组件。
-- **`src/tools/shared/`** — Tool 共享工具函数。
+- **`src/tools.ts`** — Tool registry. Assembles the tool list; tools are imported from `@claude-code-best/builtin-tools` package. Some tools are conditionally loaded via `feature()` flags or `process.env.USER_TYPE`.
+- **`src/constants/tools.ts`** — `CORE_TOOLS` 白名单常量（38 个核心工具名），用于 `isDeferredTool` 白名单制判定。
+- **`packages/builtin-tools/src/tools/`** — 60 个工具目录（含 shared/testing 等工具目录），通过 `@claude-code-best/builtin-tools` 包导出。主要分类：
+  - **文件操作**: FileEditTool, FileReadTool, FileWriteTool, GlobTool, GrepTool
+  - **Shell/执行**: BashTool, PowerShellTool, REPLTool
+  - **Agent 系统**: AgentTool, TaskCreateTool, TaskUpdateTool, TaskListTool, TaskGetTool
+  - **规划**: EnterPlanModeTool, ExitPlanModeV2Tool, VerifyPlanExecutionTool
+  - **Web/MCP**: WebFetchTool, WebSearchTool, MCPTool, McpAuthTool
+  - **调度**: CronCreateTool, CronDeleteTool, CronListTool
+  - **工具发现**: SearchExtraToolsTool, ExecuteExtraTool, SyntheticOutput（CORE_TOOLS，用于延迟工具按需加载）
+  - **其他**: LSPTool, ConfigTool, SkillTool, EnterWorktreeTool, ExitWorktreeTool 等
+- **`src/tools/shared/`** / **`packages/builtin-tools/src/tools/shared/`** — Tool 共享工具函数。
+- **`src/services/searchExtraTools/`** — TF-IDF 工具索引模块（`toolIndex.ts`），为延迟工具提供语义搜索能力。复用 `localSearch.ts` 的 TF-IDF 算法函数（`computeWeightedTf`、`computeIdf`、`cosineSimilarity` 已导出）。修改这些函数时需同步检查工具索引测试。`prefetch.ts` 的 `extractQueryFromMessages` 复用了 `skillSearch/prefetch.ts` 的同名导出函数，修改 skill prefetch 的该函数时需同步检查工具预取行为。工具预取使用独立的 `discoveredToolsThisSession` Set，与 skill prefetch 的去重集合互不影响。
 
 ### UI Layer (Ink)
 
 - **`src/ink.ts`** — Ink render wrapper with ThemeProvider injection.
-- **`src/ink/`** — Custom Ink framework (forked/internal): custom reconciler, hooks (`useInput`, `useTerminalSize`, `useSearchHighlight`), virtual list rendering.
-- **`src/components/`** — 大量 React 组件（170+ 项），渲染于终端 Ink 环境中。关键组件：
+- **`packages/@ant/ink/`** — Custom Ink framework（forked/internal），包含 components、core、hooks、keybindings、theme、utils。注意：不是 `src/ink/`。
+- **`src/components/`** — 149 个组件目录/文件，渲染于终端 Ink 环境中。关键组件：
   - `App.tsx` — Root provider (AppState, Stats, FpsMetrics)
   - `Messages.tsx` / `MessageRow.tsx` — Conversation message rendering
   - `PromptInput/` — User input handling
@@ -112,10 +157,43 @@ bun run docs:dev
 - **`src/state/selectors.ts`** — State selectors.
 - **`src/bootstrap/state.ts`** — Module-level singletons for session-global state (session ID, CWD, project root, token counts, model overrides, client type, permission mode).
 
+### Workspace Packages
+
+| Package | 说明 |
+|---------|------|
+| `packages/@ant/ink/` | Forked Ink 框架（components、hooks、keybindings、theme） |
+| `packages/@ant/computer-use-mcp/` | Computer Use MCP server（截图/键鼠/剪贴板/应用管理） |
+| `packages/@ant/computer-use-input/` | 键鼠模拟（dispatcher + darwin/win32/linux backend） |
+| `packages/@ant/computer-use-swift/` | 截图 + 应用管理（dispatcher + per-platform backend） |
+| `packages/@ant/claude-for-chrome-mcp/` | Chrome 浏览器控制（通过 `--chrome` 启用） |
+| `packages/@ant/model-provider/` | Model provider 抽象层 |
+| `packages/builtin-tools/` | 内置工具集（60 个 tool 实现，通过 `@claude-code-best/builtin-tools` 导出） |
+| `packages/agent-tools/` | Agent 工具集 |
+| `packages/acp-link/` | ACP 代理服务器（WebSocket → ACP agent 桥接） |
+| `packages/mcp-client/` | MCP 客户端库 |
+| `packages/remote-control-server/` | 自托管 Remote Control Server（Docker 部署，含 Web UI）— Web UI 已重构为 React + Vite + Radix UI，支持 ACP agent 接入 |
+| `packages/audio-capture-napi/` | 原生音频捕获（已恢复） |
+| `packages/color-diff-napi/` | 颜色差异计算（完整实现，11 tests） |
+| `packages/image-processor-napi/` | 图像处理（已恢复） |
+| `packages/modifiers-napi/` | 键盘修饰键检测（macOS FFI 实现） |
+| `packages/url-handler-napi/` | URL scheme 处理（环境变量 + CLI 参数读取） |
+| `packages/weixin/` | 微信集成（非 workspace 包） |
+
+辅助目录（无 package.json，非 workspace 包）: `langfuse-dashboard`（Langfuse 面板）、`shared-web-ui`（共享 Web UI 组件）、`highlight-code`（代码高亮）、`claude-pencil`（编辑器）、`vscode-ide-bridge`（VS Code 桥接）、`pokemon`（示例/测试）。
+
 ### Bridge / Remote Control
 
-- **`src/bridge/`** (~35 files) — Remote Control / Bridge 模式。feature-gated by `BRIDGE_MODE`。包含 bridge API、会话管理、JWT 认证、消息传输、权限回调等。Entry: `bridgeMain.ts`。
+- **`src/bridge/`** — Remote Control / Bridge 模式。feature-gated by `BRIDGE_MODE`。包含 bridge API、会话管理、JWT 认证、消息传输、权限回调等。Entry: `bridgeMain.ts`。
+- **`packages/remote-control-server/`** — 自托管 RCS，支持 Docker 部署，含 Web UI 控制面板（React 19 + Vite + Radix UI）。支持 ACP agent 通过 acp-link 接入（ACP WebSocket handler、relay handler、SSE event stream）。通过 `bun run rcs` 启动。
 - CLI 快速路径: `claude remote-control` / `claude rc` / `claude bridge`。
+- 详见 `docs/features/modes/remote-control-self-hosting.md`。
+
+### ACP Protocol (Agent Client Protocol)
+
+- **`src/services/acp/`** — ACP agent 实现，包含 `agent.ts`（AcpAgent 类）、`bridge.ts`（Claude Code ↔ ACP 桥接）、`permissions.ts`（权限处理）、`entry.ts`（入口）。
+- **`packages/acp-link/`** — ACP 代理服务器，将 WebSocket 客户端桥接到 ACP agent。提供 `acp-link` CLI 命令，支持自定义端口/HTTPS/认证/会话管理、RCS 集成（REST 注册 + WS identify 两步流程）、权限模式透传（fallback: 客户端传值 > config > `ACP_PERMISSION_MODE` 环境变量）。
+- ACP 权限管道改进：`createAcpCanUseTool` 统一权限流水线，`applySessionMode` 模式同步，`bypassPermissions` 可用性检测（非 root/sandbox 环境）。
+- ACP Plan 可视化已支持 `session/update plan` 类型的消息展示（PlanView 组件，含进度条/状态图标/优先级标签）。
 
 ### Daemon Mode
 
@@ -128,26 +206,75 @@ bun run docs:dev
 
 ### Feature Flag System
 
-Feature flags control which functionality is enabled at runtime:
+Feature flags control which functionality is enabled at runtime. 代码中统一通过 `import { feature } from 'bun:bundle'` 导入，调用 `feature('FLAG_NAME')` 返回 `boolean`。
 
-- **在代码中使用**: 统一通过 `import { feature } from 'bun:bundle'` 导入，调用 `feature('FLAG_NAME')` 返回 `boolean`。**不要**在 `cli.tsx` 或其他文件里自己定义 `feature` 函数或覆盖这个 import。
-- **启用方式**: 通过环境变量 `FEATURE_<FLAG_NAME>=1`。例如 `FEATURE_BUDDY=1 bun run dev` 启用 BUDDY 功能。
-- **Dev 默认 features**: `BUDDY`、`TRANSCRIPT_CLASSIFIER`、`BRIDGE_MODE`、`AGENT_TRIGGERS_REMOTE`（见 `scripts/dev.ts`）。
-- **Build 默认 features**: `AGENT_TRIGGERS_REMOTE`（见 `build.ts`）。
-- **常见 flag**: `BUDDY`, `DAEMON`, `BRIDGE_MODE`, `BG_SESSIONS`, `PROACTIVE`, `KAIROS`, `VOICE_MODE`, `FORK_SUBAGENT`, `SSH_REMOTE`, `DIRECT_CONNECT`, `TEMPLATES`, `CHICAGO_MCP`, `BYOC_ENVIRONMENT_RUNNER`, `SELF_HOSTED_RUNNER`, `COORDINATOR_MODE`, `UDS_INBOX`, `LODESTONE`, `ABLATION_BASELINE` 等。
-- **类型声明**: `src/types/internal-modules.d.ts` 中声明了 `bun:bundle` 模块的 `feature` 函数签名。
+**启用方式**: 环境变量 `FEATURE_<FLAG_NAME>=1`。例如 `FEATURE_BUDDY=1 bun run dev`。
+
+**Build 默认 features**（65+ 个，见 `build.ts` 中 `DEFAULT_BUILD_FEATURES`）:
+- 基础: `BUDDY`, `TRANSCRIPT_CLASSIFIER`, `BRIDGE_MODE`, `AGENT_TRIGGERS_REMOTE`, `CHICAGO_MCP`, `VOICE_MODE`
+- 统计/缓存: `SHOT_STATS`, `PROMPT_CACHE_BREAK_DETECTION`, `TOKEN_BUDGET`
+- P0 本地: `AGENT_TRIGGERS`, `ULTRATHINK`, `BUILTIN_EXPLORE_PLAN_AGENTS`, `LODESTONE`
+- P1 API 依赖: `EXTRACT_MEMORIES`, `VERIFICATION_AGENT`, `KAIROS_BRIEF`, `AWAY_SUMMARY`, `ULTRAPLAN`
+- P2: `DAEMON`, `ACP`
+- 工作流: `WORKFLOW_SCRIPTS`, `HISTORY_SNIP`, `MONITOR_TOOL`, `KAIROS`
+- 多 worker: `COORDINATOR_MODE`, `BG_SESSIONS`, `TEMPLATES`
+- 连接器: `CONNECTOR_TEXT`, `COMMIT_ATTRIBUTION`, `DIRECT_CONNECT`
+- 实验性: `EXPERIMENTAL_SKILL_SEARCH`, `EXPERIMENTAL_SEARCH_EXTRA_TOOLS`
+- 模式: `POOR`, `SSH_REMOTE`
+- 已禁用: `CONTEXT_COLLAPSE`, `FORK_SUBAGENT`, `UDS_INBOX`, `LAN_PIPES`, `REVIEW_ARTIFACT`, `TEAMMEM`, `SKILL_LEARNING`
+
+**Dev mode 默认**: 全部启用（见 `scripts/dev.ts`）。
+
+**类型声明**: `src/types/internal-modules.d.ts` 中声明了 `bun:bundle` 模块的 `feature` 函数签名。
 
 **新增功能的正确做法**: 保留 `import { feature } from 'bun:bundle'` + `feature('FLAG_NAME')` 的标准模式，在运行时通过环境变量或配置控制，不要绕过 feature flag 直接 import。
 
+### Multi-API 兼容层
+
+所有兼容层均采用流适配器模式：将第三方 API 格式转为 Anthropic 内部格式，下游代码完全不改。通过 `/login` 命令配置。
+
+#### OpenAI 兼容层
+
+通过 `CLAUDE_CODE_USE_OPENAI=1` 启用，支持 Ollama/DeepSeek/vLLM 等任意 OpenAI Chat Completions 协议端点。含 DeepSeek thinking mode 支持。
+
+- **`src/services/api/openai/`** — client、消息/工具转换、流适配、模型映射
+- 关键环境变量：`CLAUDE_CODE_USE_OPENAI`、`OPENAI_API_KEY`、`OPENAI_BASE_URL`、`OPENAI_MODEL`
+
+#### Gemini 兼容层
+
+通过 `CLAUDE_CODE_USE_GEMINI=1` 启用。独立环境变量体系。
+
+- **`src/services/api/gemini/`** — client、模型映射、类型定义
+- 关键环境变量：`GEMINI_API_KEY`（必填）、`GEMINI_MODEL`（直接指定）、`GEMINI_DEFAULT_SONNET_MODEL`/`GEMINI_DEFAULT_OPUS_MODEL`（按能力映射）
+- 模型映射优先级：`GEMINI_MODEL` > `GEMINI_DEFAULT_*_MODEL` > `ANTHROPIC_DEFAULT_*_MODEL`(已废弃) > 原样返回
+
+#### Grok 兼容层
+
+通过 `CLAUDE_CODE_USE_GROK=1` 启用。自定义模型映射支持 xAI Grok API。
+
+- **`src/services/api/grok/`** — client、模型映射
+
+详见各兼容层的 docs 文档。
+
+### 穷鬼模式（Budget Mode）
+
+- 通过 `/poor` 命令切换，持久化到 `settings.json`。
+- 启用后跳过 `extract_memories`、`prompt_suggestion` 和 `verification_agent`，显著减少 token 消耗。
+- 实现在 `src/commands/poor/poorMode.ts`。
+
 ### Stubbed/Deleted Modules
 
 | Module | Status |
 |--------|--------|
-| Computer Use (`@ant/*`) | Stub packages in `packages/@ant/` |
-| `*-napi` packages (audio, image, url, modifiers) | Stubs in `packages/` (except `color-diff-napi` which is fully implemented) |
+| Computer Use (`@ant/*`) | Restored — macOS + Windows + Linux（后端完整度不一） |
+| `*-napi` packages | 全部已恢复/实现：`audio-capture-napi`、`image-processor-napi` 已恢复；`color-diff-napi` 完整；`modifiers-napi`（macOS FFI）；`url-handler-napi`（环境变量+CLI） |
+| Voice Mode | Restored — Push-to-Talk 语音输入（需 Anthropic OAuth） |
+| OpenAI/Gemini/Grok 兼容层 | Restored |
+| Remote Control Server | Restored — 自托管 RCS + Web UI |
+| `packages/shell/`, `packages/swarm/`, `packages/mcp-server/`, `packages/cc-knowledge/` | Removed — 功能合并或废弃 |
 | Analytics / GrowthBook / Sentry | Empty implementations |
-| Magic Docs / Voice Mode / LSP Server | Removed |
-| Plugins / Marketplace | Removed |
+| Magic Docs / LSP Server | Restored — Magic Docs 自动更新 + LSP 服务器管理器 |
+| Plugins / Marketplace | Restored — 插件安装/卸载/启用/禁用 + Marketplace 浏览 |
 | MCP OAuth | Simplified |
 
 ### Key Type Files
@@ -161,19 +288,128 @@ Feature flags control which functionality is enabled at runtime:
 
 - **框架**: `bun:test`（内置断言 + mock）
 - **单元测试**: 就近放置于 `src/**/__tests__/`，文件名 `<module>.test.ts`
-- **集成测试**: `tests/integration/` — 4 个文件（cli-arguments, context-build, message-pipeline, tool-chain）
+- **集成测试**: `tests/integration/` — 6 个文件（cli-arguments, context-build, message-pipeline, tool-chain, autonomy-lifecycle-user-flow, dependency-overrides）
 - **共享 mock/fixture**: `tests/mocks/`（api-responses, file-system, fixtures/）
 - **命名**: `describe("functionName")` + `test("behavior description")`，英文
-- **Mock 模式**: 对重依赖模块使用 `mock.module()` + `await import()` 解锁（必须内联在测试文件中，不能从共享 helper 导入）
-- **当前状态**: ~1623 tests / 114 files (110 unit + 4 integration) / 0 fail（详见 `docs/testing-spec.md`）
+- **包测试**: `packages/` 下各包也有独立测试（如 `color-diff-napi` 11 tests）
+
+### Mock 使用规范
+
+**只 mock 有副作用的依赖链，不 mock 纯函数/纯数据模块。**
+
+被迫 mock 的根源：`log.ts` / `debug.ts` → `bootstrap/state.ts`（模块级 `realpathSync` / `randomUUID` 副作用）。必须 mock 的模块：`log.ts`、`debug.ts`、`bun:bundle`、`settings/settings.js`、`config.ts`、`auth.ts`、第三方网络库。
+
+**`log.ts` 和 `debug.ts` 使用共享 mock**（`tests/mocks/log.ts` / `tests/mocks/debug.ts`），不要在测试文件中内联 mock 定义。使用方式：
+
+```ts
+import { logMock } from "../../../tests/mocks/log";
+mock.module("src/utils/log.ts", logMock);
+
+import { debugMock } from "../../../../tests/mocks/debug";
+mock.module("src/utils/debug.ts", debugMock);
+```
+
+源文件导出变更时只需更新 `tests/mocks/` 下的对应文件，不需要逐个修改测试。
+
+不要 mock：纯函数模块（`errors.ts`、`stringUtils.js`）、mock 值与真实实现相同的模块、mock 路径与实际 import 不匹配的模块。
+
+路径规则：统一用 `.ts` 扩展名 + `src/*` 别名路径，禁止双重 mock 同一模块。
+
+#### 跨文件 mock 污染（process-global `mock.module`）
+
+**Bun 的 `mock.module` 是进程全局的（last-write-wins），不是 per-file 隔离的。** 一个测试文件的 `mock.module` 会污染同一进程中所有其他测试文件的 `require`/`import`。
+
+**关键事实（Bun 1.x 实测验证）：**
+- 测试文件执行顺序**不是严格字母序**，不要假设文件 A 一定在文件 B 之前执行。
+- `mock.module` 在 `beforeAll` 内部调用时**不会被提升**（hoist），但仍会污染后续加载的文件。
+- `require()` 和 `import()` 共享同一模块注册表，`mock.module` 对两者都生效。
+- 一个模块一旦被某个文件的 `mock.module` 替换，同一进程中所有后续 `require`/`import` 都会返回 mock 值，即使调用方使用不同的 specifier 路径。
+
+**核心规则：不要 mock 被测模块的上层业务模块。**
+
+错误做法（会污染同目录的 `api.test.ts`）：
+```ts
+// launchSchedule.test.ts — 直接 mock 源 API 模块 ❌
+mock.module('src/commands/schedule/triggersApi.js', () => ({
+  listTriggers: listTriggersMock,
+  // ...
+}))
+```
+
+正确做法（mock 底层 HTTP 层，不污染业务模块）：参考 `launchSkillStore.test.ts`、`launchVault.test.ts` 的模式。
+```ts
+// launchSchedule.test.ts — mock axios 而非 triggersApi ✅
+import { setupAxiosMock } from '../../../../tests/mocks/axios.js'
+
+const axiosHandle = setupAxiosMock()
+axiosHandle.stubs.get = axiosGetMock
+axiosHandle.stubs.post = axiosPostMock
+
+beforeAll(() => { axiosHandle.useStubs = true })
+afterAll(() => { axiosHandle.useStubs = false })
+```
+
+**判断标准：** 如果目录下同时有 `launch*.test.ts`（集成测试）和 `api.test.ts`（回归测试），`launch*.test.ts` 必须 mock axios 而非源 API 模块。`api.test.ts` 需要测试真实 API 模块的 HTTP 方法/URL/错误处理逻辑，被 mock 后就无法测试。
+
+**排查 mock 污染的方法：**
+1. 单独运行可疑文件确认其通过：`bun test path/to/suspect.test.ts`
+2. 与同目录其他文件一起运行定位污染源：`bun test path/to/__tests__/`
+3. 在两个文件中各加 `console.error('[file] milestone')` 追踪实际执行顺序
+4. 检查 `mock.module` 的 specifier 是否与同目录其他测试的 `require`/`import` 路径解析到同一模块
+
+### 类型检查
+
+项目使用 TypeScript strict 模式，**tsc 必须零错误**。每次修改后运行：
+
+```bash
+bun run precheck
+```
+
+**类型规范**：
+- 生产代码禁止 `as any`；测试文件中 mock 数据可用 `as any`
+- 类型不匹配优先用 `as unknown as SpecificType` 双重断言，或补充 interface
+- 未知结构对象用 `Record<string, unknown>` 替代 `any`
+- 联合类型用类型守卫（type guard）收窄，不要强转
+- `msg.request` 属性访问：`const req = msg.request as Record<string, unknown>`
+- Ink `color` prop：用 `as keyof Theme` 而非 `as any`
 
 ## Working with This Codebase
 
-- **Don't try to fix all tsc errors** — they're from decompilation and don't affect runtime.
+- **precheck must pass** — `bun run precheck`（typecheck + lint fix + test）必须零错误，任何修改都不能引入新的类型/lint/测试错误。
 - **Feature flags** — 默认全部关闭（`feature()` 返回 `false`）。Dev/build 各有自己的默认启用列表。不要在 `cli.tsx` 中重定义 `feature` 函数。
 - **React Compiler output** — Components have decompiled memoization boilerplate (`const $ = _c(N)`). This is normal.
-- **`bun:bundle` import** — `import { feature } from 'bun:bundle'` 是 Bun 内置模块，由运行时/构建器解析。不要用自定义函数替代它。
+- **`bun:bundle` import** — `import { feature } from 'bun:bundle'` 是 Bun 内置模块，由运行时/构建器解析。不要用自定义函数替代它。**`feature()` 只能直接用在 `if` 语句或三元表达式的条件位置**（Bun 编译器限制），不能赋值给变量、不能放在箭头函数体里、不能作为 `&&` 链的一部分。正确：`if (feature('X')) {}` 或 `feature('X') ? a : b`。
 - **`src/` path alias** — tsconfig maps `src/*` to `./src/*`. Imports like `import { ... } from 'src/utils/...'` are valid.
 - **MACRO defines** — 集中管理在 `scripts/defines.ts`。Dev mode 通过 `bun -d` 注入，build 通过 `Bun.build({ define })` 注入。修改版本号等常量只改这个文件。
 - **构建产物兼容 Node.js** — `build.ts` 会自动后处理 `import.meta.require`，产物可直接用 `node dist/cli.js` 运行。
-- **Biome 配置** — 大量 lint 规则被关闭（decompiled 代码不适合严格 lint）。`.tsx` 文件用 120 行宽 + 强制分号；其他文件 80 行宽 + 按需分号。
+- **Biome 配置** — 42 条 lint 规则因 decompiled 代码被关闭，仅保留 `recommended` 基线。格式化覆盖全项目（`src/`、`scripts/`、`packages/`，含 `packages/@ant/`）。`.tsx` 文件用 120 行宽 + 强制分号；其他文件 80 行宽 + 按需分号。JSON 格式化已启用。`.editorconfig` 与 Biome 配置对齐（2-space 缩进）。修改任何代码后应运行 `bun run precheck` 确认无类型/lint/格式/测试问题，pre-commit hook 会自动拦截不合格提交。
+- **tsc 与 Biome 冲突处理** — 当 tsc 要求声明属性（赋值使用）但 biome 报 `noUnusedPrivateClassMembers`（只写不读）时，用 `// biome-ignore lint/correctness/noUnusedPrivateClassMembers: <原因>` 抑制 lint 警告，保留类型声明。`biome ci` 必须零 warnings。
+- **`@ts-expect-error` 维护** — 只在下方代码确实有类型错误时保留 `@ts-expect-error`。如果类型系统已更新导致 directive 变为 unused（TS2578），直接移除注释。MACRO 替换产生的永假比较（如 `'production' === 'development'`）仍需保留 `@ts-expect-error`。
+- **Ink 框架在 `packages/@ant/ink/`** — 不是 `src/ink/`（该目录不存在）。Ink 相关的组件、hooks、keybindings 都在 packages 中。
+- **Provider 优先级** — `modelType` 参数 > 环境变量 > 默认 `firstParty`。新增 provider 需在 `src/utils/model/providers.ts` 注册。
+
+## Design Context
+
+Impeccable 设计上下文保存在 `.impeccable.md` 中。设计 Web UI（RCS 控制面板、文档站、着陆页）时必须参考该文件。
+
+### 核心设计原则
+
+1. **Considered over clever** — 每个设计选择都应感觉有意为之，而非追逐潮流
+2. **Warmth through subtlety** — 通过橙色色调的中性色、留白布局、有温度的文案来传达温暖
+3. **Density with clarity** — 技术用户需要信息密度，但不能混乱
+4. **Community voice** — 设计应感觉是由使用者创造的，而非遥远的设计团队
+5. **Anthropic's shadow** — 遵循 Anthropic 的设计直觉：干净的布局、充足的间距、温暖的色温
+
+### 品牌色
+
+- 主色：Claude Orange `#D77757`（terra cotta）
+- 辅色：Claude Blue `#5769F7`
+- 暗色模式使用温暖的深色表面（非冷蓝黑色）
+
+### 目标用户
+
+技术团队/企业，在专业工作流中使用 AI 辅助编程。友好的开源社区氛围，非企业 SaaS 风格。
+
+### 视觉参考
+
+Anthropic 公司的设计风格 — 干净、考究、温暖的底色。大量留白，以排版为核心。避免 AI 产品常见的设计套路（渐变文字、玻璃态、霓虹色）。

DEV-LOG.md

@@ -1,5 +1,711 @@
 # DEV-LOG
 
+## /poor 省流模式 (2026-04-11)
+
+新增 `/poor` 命令，toggle 关闭 `extract_memories` 和 `prompt_suggestion`，省 token。
+
+- 新增 `POOR` feature flag（build.ts + dev.ts）
+- `src/commands/poor/` — 命令定义 + toggle 实现 + 状态管理
+- `src/query/stopHooks.ts` — POOR 模式激活时跳过 extract_memories 和 prompt_suggestion
+
+---
+
+## Pipe IPC + LAN Pipes + Monitor Tool + 工具恢复 (2026-04-08 ~ 2026-04-11)
+
+**分支**: `feat/pr-package-adapt`
+
+### 背景
+
+从 decompiled 代码恢复大量 stub 为完整实现，同时新增 LAN 跨机器通讯能力。本次 PR 覆盖：Pipe IPC 系统、LAN Pipes、Monitor Tool、20+ 工具/组件<E7BB84><E4BBB6><EFBFBD>复、REPL hook 架构重构。
+
+### 实现
+
+#### 1. PipeServer TCP 双模式（`src/utils/pipeTransport.ts`）
+
+从原始的纯 UDS 服务器扩展为 UDS + TCP 双模式：
+
+- 提取 `setupSocket()` 共享方法，UDS 和 TCP 的 socket 处理逻辑完全一致
+- `start(options?: PipeServerOptions)` 新增可选参数 `{ enableTcp, tcpPort }`
+- 内部维护两个 `net.Server`（UDS + TCP），共享同一组 `clients: Set<Socket>` 和 `handlers`
+- TCP server 绑定 `0.0.0.0` + 动态端口（port=0 由 OS 分配）
+- `tcpAddress` getter 暴露 TCP 端口信息
+- `close()` 同时关闭两个 server
+- 新增类型：`PipeTransportMode`、`TcpEndpoint`、`PipeServerOptions`
+
+PipeClient 对应扩展：
+- 构造函数新增可选 `TcpEndpoint` 参数
+- `connect()` 根据是否有 TCP endpoint 分派到 `connectTcp()` 或 `connectUds()`
+- TCP 连接不需要文件存在轮询，直接建立连接
+
+#### 2. LAN Beacon — UDP Multicast 发现（`src/utils/lanBeacon.ts`，新文件）
+
+零配置局域网 peer 发现：
+
+- **协议**：UDP multicast 组 `224.0.71.67`（"CC" ASCII），端口 `7101`，TTL=1
+- **Announce 包**：JSON `{ proto, pipeName, machineId, hostname, ip, tcpPort, role, ts }`
+- **广播间隔**：3 秒，首次在 socket bind 完成后立即发送
+- **Peer 超时**：15 秒无 announce 视为 lost
+- **事件**：`peer-discovered`、`peer-lost`
+- **存储**：module-level singleton `getLanBeacon()`/`setLanBeacon()`，不挂在 Zustand state 上
+
+关键修复：
+- `addMembership(group, localIp)` + `setMulticastInterface(localIp)` 指定 LAN 网卡，解决 Windows 上 WSL/Docker 虚拟网卡劫持 multicast 的问题
+- announce/cleanup 定时器移入 `bind()` 回调内，修复 socket 未就绪时发送的竞态
+
+#### 3. Registry 扩展（`src/utils/pipeRegistry.ts`）
+
+- `PipeRegistryEntry` 新增 `tcpPort?` 和 `lanVisible?` 字段
+- `mergeWithLanPeers(registry, lanPeers)` 合并本地 registry 和 LAN beacon peers，本地优先
+
+#### 4. Peer Address 扩展（`src/utils/peerAddress.ts`）
+
+- `parseAddress()` 新增 `tcp` scheme：`tcp:192.168.1.20:7100`
+- 新增 `parseTcpTarget()` 解析 `host:port` 字符串
+
+#### 5. REPL 集成（`src/screens/REPL.tsx`）
+
+三个阶段的改动：
+
+**Bootstrap**：`createPipeServer()` 时根据 `feature('LAN_PIPES')` 传入 TCP 选项 → 启动 `LanBeacon` → 注册 entry 携带 tcpPort
+
+**Heartbeat**（每 5 秒）：
+- `refreshDiscoveredPipes()` 同时包含本地 subs 和 LAN beacon peers，防止 LAN peer 状态被覆盖
+- auto-attach 循环统一遍历本地 subs + LAN peers，LAN peers 通过 TCP endpoint 连接
+- cleanup 检查 LAN beacon peers 列表，避免误删存活的 LAN 连接
+- attach 请求携带 `machineId`，接收方区分 LAN peer（不要求 sub 角色）
+
+**Cleanup**：通过 `getLanBeacon()` 获取并 `stop()`，`setLanBeacon(null)` 清除
+
+#### 6. 命令更新
+
+- `/pipes`（`src/commands/pipes/pipes.ts`）：显示 `[LAN]` 标记的远端实例
+- `/attach`（`src/commands/attach/attach.ts`）：自动查找 LAN beacon 获取 TCP endpoint
+- `SendMessageTool`（`src/tools/SendMessageTool/SendMessageTool.ts`）：支持 `tcp:` scheme，权限检查要求用户确认
+
+#### 7. Feature Flag
+
+`LAN_PIPES` — 在 `scripts/dev.ts` 和 `build.ts` 的默认 features 列表中启用。所有 LAN 代码路径均通过 `feature('LAN_PIPES')` 门控。
+
+#### 8. Pipe IPC 基础系统（`UDS_INBOX` feature）
+
+- `PipeServer`/`PipeClient`：UDS 传输，NDJSON 协议（共享 `ndjsonFramer.ts`）
+- `PipeRegistry`：machineId 绑定的角色分配（main/sub），文件锁，并行探测
+- Master/slave attach 流程、prompt 转发、permission 转发
+- Heartbeat 生命周期（5s 间隔，stale entry 清理，busy flag 防重叠）
+- 命令：`/pipes`、`/attach`、`/detach`、`/send`、`/claim-main`、`/pipe-status`
+
+#### 9. Monitor Tool（`MONITOR_TOOL` feature）
+
+- `MonitorTool`：AI 可调用的后台 shell 监控工具
+- `/monitor` 命令：用户快捷入口，Windows 兼容（watch → PowerShell 循环）
+- `MonitorMcpTask`：从 stub 恢复完整生命周期（register/complete/fail/kill）
+- `MonitorPermissionRequest`：React 权限确认 UI
+- `MonitorMcpDetailDialog`：Shift+Down 详情面板
+
+#### 10. 工具恢复（stub → 实现）
+
+- SnipTool、SleepTool、ListPeersTool、SendUserFileTool
+- WebBrowserTool、SubscribePRTool、PushNotificationTool
+- CtxInspectTool、TerminalCaptureTool、WorkflowTool
+- REPLTool (.js → .ts)、VerifyPlanExecutionTool (.js → .ts)、SuggestBackgroundPRTool (.js → .ts)
+- 组件 .ts → .tsx 重写：MonitorPermissionRequest、ReviewArtifactPermissionRequest、MonitorMcpDetailDialog、WorkflowDetailDialog、WorkflowPermissionRequest
+
+#### 11. REPL Hook 架构重构
+
+从 REPL.tsx 提取 ~830 行 Pipe IPC 内联代码为 4 个独立 hook：
+
+| Hook | 行数 | 职责 |
+|------|------|------|
+| `usePipeIpc` | 623 | 生命周期：bootstrap、handlers、heartbeat、cleanup |
+| `usePipeRelay` | 38 | slave→master 消息回传（通过 `setPipeRelay` singleton） |
+| `usePipePermissionForward` | 159 | 权限请求转发 + 流式通知显示 |
+| `usePipeRouter` | 130 | selected pipe 输入路由 + role/IP 标签显示 |
+
+共享工具：`ndjsonFramer.ts` 替换 3 份重复的 NDJSON 解析。
+
+#### 12. Feature Flags 新增启用
+
+UDS_INBOX、LAN_PIPES、MONITOR_TOOL、FORK_SUBAGENT、KAIROS、COORDINATOR_MODE、WORKFLOW_SCRIPTS、HISTORY_SNIP、CONTEXT_COLLAPSE
+
+### 踩坑记录
+
+1. **Multicast 绑错网卡**：Windows 上 `addMembership(group)` 不指定本地接口时，默认绑到 WSL/Docker 虚拟网卡（`172.19.112.1`），LAN 上的真实机器收不到。必须 `addMembership(group, localIp)` + `setMulticastInterface(localIp)`。
+
+2. **Beacon ref 丢失**：最初用 `(store.getState() as any)._lanBeacon` 挂载 beacon 引用，但 Zustand `setState` 展开 `prev` 时不包含 `_lanBeacon` 属性，下次读取就是 `undefined`。改为 module-level singleton 解决。
+
+3. **Heartbeat 清洗 LAN 连接**：`refreshDiscoveredPipes()` 每 5 秒用仅含本地 registry subs 的列表完全覆盖 `discoveredPipes` + `selectedPipes`，LAN peer 的发现和选择状态被持续清空。必须在 refresh 中同时包含 beacon peers。
+
+4. **Heartbeat cleanup 误删**：`!aliveSubNames.has(slaveName)` 导致 LAN peer（不在本地 registry）被判定为死连接每 5 秒清除一次。需要同时检查 beacon peers 列表。
+
+5. **跨机器 attach 被拒**：两台机器各自为 `main`，attach handler 硬编码 `role !== 'sub'` 拒绝。通过 attach_request 携带 `machineId`，接收方对不同 machineId 的请求放行。
+
+6. **`feature()` 使用约束**：Bun 的 `feature()` 是编译时常量，只能在 `if` 语句或三元条件中直接使用，不能赋值给变量（如 `const x = feature('...')`），否则构建报错。
+
+### 已知限制
+
+- TCP 无认证：同 LAN 内任何设备知道端口号即可连接
+- JSON.parse 无 schema 验证：code review 建议增加 Zod 校验
+- Beacon 明文广播 IP/hostname/machineId：建议后续 hash 处理
+- `getLocalIp()` 可能返回 VPN 地址：多网卡环境需更精确的接口选择
+
+### 测试
+
+- `src/utils/__tests__/lanBeacon.test.ts`：7 个测试（mock dgram）
+- `src/utils/__tests__/peerAddress.test.ts`：8 个测试（纯函数）
+- 全量：2190 pass / 0 fail
+
+### 防火墙配置
+
+**Windows**（管理员 PowerShell）：
+```powershell
+New-NetFirewallRule -DisplayName "Claude Code LAN Beacon (UDP)" -Direction Inbound -Protocol UDP -LocalPort 7101 -Action Allow -Profile Private
+New-NetFirewallRule -DisplayName "Claude Code LAN Pipes (TCP)" -Direction Inbound -Protocol TCP -LocalPort 1024-65535 -Program (Get-Command bun).Source -Action Allow -Profile Private
+New-NetFirewallRule -DisplayName "Claude Code LAN Beacon Out (UDP)" -Direction Outbound -Protocol UDP -RemotePort 7101 -Action Allow -Profile Private
+```
+
+**macOS**（首次运行时系统会弹出"允许接受传入连接"对话框，点击允许即可。手动放行）：
+```bash
+# 如果使用 pf <20><><EFBFBD>火墙，添加规则：
+echo "pass in proto udp from any to any port 7101" | sudo pfctl -ef -
+# 或<><E68896>接在 System Settings → Network → Firewall 中允许 bun 进程
+```
+
+**Linux**（firewalld）：
+```bash
+sudo firewall-cmd --zone=trusted --add-port=7101/udp --permanent
+sudo firewall-cmd --zone=trusted --add-port=1024-65535/tcp --permanent
+sudo firewall-cmd --reload
+```
+
+**Linux**（iptables）：
+```bash
+sudo iptables -A INPUT -p udp --dport 7101 -j ACCEPT
+sudo iptables -A INPUT -p tcp --dport 1024:65535 -m owner --uid-owner $(id -u) -j ACCEPT
+sudo iptables-save | sudo tee /etc/iptables/rules.v4
+```
+
+**通用验证**：确认网络为局域网（非公共 WiFi），路<EFBC8C><E8B7AF><EFBFBD>器未开启 AP 隔离。
+
+---
+
+
+## Daemon + Remote Control Server 还原 (2026-04-07)
+
+**分支**: `feat/daemon-remote-control-server`
+
+### 背景
+
+`src/commands.ts` 注册了 `remoteControlServer` 命令（双重门控 `feature('DAEMON') && feature('BRIDGE_MODE')`），但 `src/commands/remoteControlServer/` 目录缺失，`src/daemon/main.ts` 和 `src/daemon/workerRegistry.ts` 均为 stub。官方 CLI 2.1.92 中情况一致——Anthropic 已预留注册点和底层 `runBridgeHeadless()` 实现，但中间层（daemon supervisor + command 入口）未发布。
+
+通过逐级反向追踪调用链还原完整实现：
+```
+/remote-control-server (slash command)
+  → spawn: claude daemon start
+    → daemonMain() (supervisor，管理 worker 生命周期)
+      → spawn: claude --daemon-worker=remoteControl
+        → runDaemonWorker('remoteControl')
+          → runBridgeHeadless(opts, signal)  ← 已有完整实现
+            → runBridgeLoop() → 接受远程会话
+```
+
+### 实现
+
+#### 1. Worker Registry（`src/daemon/workerRegistry.ts`）
+
+从 stub 还原为 worker 分发器：
+- `runDaemonWorker(kind)` 按 `kind` 分发到不同 worker 实现
+- `runRemoteControlWorker()` 从环境变量（`DAEMON_WORKER_*`）读取配置，构造 `HeadlessBridgeOpts`，调用 `runBridgeHeadless()`
+- 区分 permanent（`EXIT_CODE_PERMANENT = 78`）和 transient 错误，supervisor 据此决定重试或 park
+- SIGTERM/SIGINT 信号处理，通过 `AbortController` 传递给 bridge loop
+
+#### 2. Daemon Supervisor（`src/daemon/main.ts`）
+
+从 stub 还原为完整 supervisor 进程：
+- `daemonMain(args)` 支持子命令：`start`（启动）、`status`、`stop`、`--help`
+- `runSupervisor()` spawn `remoteControl` worker 子进程，通过环境变量传递配置
+- 指数退避重启（2s → 120s），10s 内连续崩溃 5 次则 park worker
+- permanent exit code（78）直接 park，不重试
+- graceful shutdown：SIGTERM → 转发给 worker → 30s grace → SIGKILL
+- CLI 参数支持：`--dir`、`--spawn-mode`、`--capacity`、`--permission-mode`、`--sandbox`、`--name`
+
+#### 3. Remote Control Server 命令（`src/commands/remoteControlServer/`）
+
+**`index.ts`** — Command 注册：
+- 类型 `local-jsx`，名称 `/remote-control-server`，别名 `/rcs`
+- 双 feature 门控：`feature('DAEMON') && feature('BRIDGE_MODE')` + `isBridgeEnabled()`
+- lazy load `remoteControlServer.tsx`
+
+**`remoteControlServer.tsx`** — REPL 内 UI：
+- 首次调用：前置检查（bridge 可用性 + OAuth token）→ spawn daemon 子进程
+- 再次调用：弹出管理对话框（停止/重启/继续），显示 PID 和最近 5 行日志
+- 模块级 state 跨调用保持 daemon 进程引用
+- graceful stop：SIGTERM → 10s grace → SIGKILL
+
+#### 4. Feature Flag 启用
+
+`build.ts` / `scripts/dev.ts`：`DEFAULT_BUILD_FEATURES` / `DEFAULT_FEATURES` 新增 `DAEMON`
+
+DAEMON 仅有编译时 feature flag 门控，无 GrowthBook gate。
+
+### 与 `/remote-control` 的区别
+
+| | `/remote-control` | `/remote-control-server` (daemon) |
+|---|---|---|
+| 模式 | 单会话，REPL 内交互式 bridge | 多会话，daemon 持久化服务器 |
+| 生命周期 | 跟 REPL 会话绑定 | 独立后台进程，崩溃自动重启 |
+| 并发 | 1 个远程连接 | 默认 4 个，可配置 `--capacity` |
+| 隔离 | 共享当前目录 | 支持 `worktree` 模式隔离 |
+| 底层 | `initReplBridge()` | `runBridgeHeadless()` → `runBridgeLoop()` |
+
+### 修改文件
+
+| 文件 | 变更 |
+|------|------|
+| `build.ts` | `DEFAULT_BUILD_FEATURES` 新增 `DAEMON` |
+| `scripts/dev.ts` | `DEFAULT_FEATURES` 新增 `DAEMON` |
+| `src/daemon/main.ts` | 从 stub 还原为 supervisor 实现 |
+| `src/daemon/workerRegistry.ts` | 从 stub 还原为 worker 分发器 |
+| `src/commands/remoteControlServer/index.ts` | **新增** command 注册 |
+| `src/commands/remoteControlServer/remoteControlServer.tsx` | **新增** REPL UI |
+
+### 验证
+
+| 项目 | 结果 |
+|------|------|
+| `bun run build` | ✅ 成功 (490 files) |
+| tsc 新文件检查 | ✅ 无新增类型错误 |
+
+### 使用方式
+
+```bash
+# CLI 直接启动 daemon
+bun run dev daemon start
+bun run dev daemon start --spawn-mode=worktree --capacity=8
+
+# REPL 内
+/remote-control-server   # 或 /rcs
+```
+
+前提：需要 Anthropic OAuth 登录（`claude login`）。
+
+---
+
+## /ultraplan 启用 + GrowthBook Fallback 加固 + Away Summary 改进 (2026-04-06)
+
+**分支**: `feat/ultraplan-enablement`
+**Commit**: `feat: enable /ultraplan and harden GrowthBook fallback chain`
+
+### 背景
+
+`/ultraplan` 是 Claude Code 的高级多代理规划功能：将任务发送到 Claude Code on the web（CCR），由 Opus 进行深度规划，计划完成后返回终端供用户审批和执行。此功能被 3 层门控锁定：`feature('ULTRAPLAN')` 编译 flag + `isEnabled: () => USER_TYPE === 'ant'` + `INTERNAL_ONLY_COMMANDS` 列表。
+
+另外发现 GrowthBook fallback 链在 config 未初始化时会抛异常跳过 `LOCAL_GATE_DEFAULTS`，以及 Away Summary 在不支持 DECSET 1004 focus 事件的终端（CMD/PowerShell）上不工作。
+
+### 实现
+
+#### 1. Ultraplan 启用
+
+- `build.ts` / `scripts/dev.ts`: 添加 `ULTRAPLAN` 到默认编译 flag
+- `src/commands.ts`: 将 ultraplan 从 `INTERNAL_ONLY_COMMANDS` 移入公开 `COMMANDS` 列表
+- `src/commands/ultraplan.tsx`: `isEnabled` 改为 `() => true`
+- `src/screens/REPL.tsx`: 添加 `UltraplanChoiceDialog`、`UltraplanLaunchDialog`、`launchUltraplan` 的 import（HEAD 版使用但未 import，构建报 `not defined`）
+
+#### 2. 反编译 UltraplanChoiceDialog / UltraplanLaunchDialog
+
+REPL.tsx 引用这两个组件但代码库中不存在。从官方 CLI 2.1.92 的 `cli.js` 中定位 minified 函数 `M15`（UltraplanChoiceDialog）和 `P15`（UltraplanLaunchDialog），通过符号映射表反编译为可读 TSX。
+
+**`src/components/ultraplan/UltraplanChoiceDialog.tsx`** — 远程计划批准后的选择对话框：
+- 3 个选项：Implement here（注入当前会话）/ Start new session（清空会话重开）/ Cancel（保存到 .md 文件）
+- 可滚动计划预览（ctrl+u/d 翻页，鼠标滚轮），自适应终端高度
+- 选择后标记远程 task 完成、清除 `ultraplanPendingChoice` 状态、归档远程 CCR session
+
+**`src/components/ultraplan/UltraplanLaunchDialog.tsx`** — 启动确认对话框：
+- 显示功能说明、时间估计（~10–30 min）、服务条款链接
+- 处理 Remote Control bridge 冲突（选择 run 时自动断开 bridge）
+- 首次使用时持久化 `hasSeenUltraplanTerms` 到全局配置
+
+反编译要点：剥离 React Compiler `_c(N)` 缓存数组，还原为标准 `useMemo`/`useCallback`；`useFocusedInputDialog()` 注册 hook 省略（REPL 内部计算 `focusedInputDialog`）；GrowthBook 配置查询替换为本地默认值。
+
+#### 3. GrowthBook Fallback 加固
+
+`src/services/analytics/growthbook.ts`:
+- `getFeatureValue_CACHED_MAY_BE_STALE`: 将 `getLocalGateDefault()` 查找移到 try/catch 外层
+- `checkStatsigFeatureGate_CACHED_MAY_BE_STALE`: 同上，config 读取包裹在 try/catch 中
+
+修复前：config 未初始化 → `getGlobalConfig()` 抛异常 → catch 直接返回 `defaultValue` → 跳过 `LOCAL_GATE_DEFAULTS`
+修复后：config 未初始化 → catch 静默 → 继续查 `LOCAL_GATE_DEFAULTS` → 有默认值就用，没有才 fallback
+
+#### 4. Away Summary 改进（Windows 终端兼容）
+
+**问题**：Away Summary（`feature('AWAY_SUMMARY')` + `tengu_sedge_lantern` gate，上一轮已启用）依赖 DECSET 1004 终端 focus 事件检测用户是否离开。但 Windows 的 CMD 和 PowerShell 不支持此协议，`getTerminalFocusState()` 始终返回 `'unknown'`，原逻辑对 `'unknown'` 状态执行 no-op，导致 Windows 用户永远无法触发离开摘要。
+
+**修改**：`src/hooks/useAwaySummary.ts`
+
+1. **focus 状态处理**：`'unknown'` 现在视同 `'blurred'`（可能已离开），订阅时即启动 idle timer（5 分钟）
+2. **idle-based 在场检测**：新增 `isLoading` 转换监听作为用户活跃信号替代 focus 事件：
+   - 用户发起新 turn（`isLoading` → `true`）→ 说明在场，取消 idle timer + abort 进行中的生成
+   - turn 结束（`isLoading` → `false`）→ 重启 idle timer
+   - timer 到期且无进行中 turn → 触发 away summary 生成
+3. **兼容性**：仅在 `getTerminalFocusState() === 'unknown'` 时激活 idle 逻辑，支持 DECSET 1004 的终端（iTerm2、Windows Terminal、kitty 等）仍走原有 blur/focus 路径
+
+**效果**：Windows CMD/PowerShell 用户离开终端 5 分钟后，系统自动调用 API 生成摘要并作为 `away_summary` 类型的系统消息追加到对话流中，用户回来时直接在 UI 中看到，无需执行任何命令
+
+#### 5. Cron 定时任务管理技能
+
+`src/skills/bundled/cronManage.ts`（**新增**）+ `src/skills/bundled/index.ts`：
+
+KAIROS 定时任务系统（`tengu_kairos_cron` gate，已在上一轮 GrowthBook 启用中开启）提供了 `ScheduleCronTool` 来创建定时任务，但缺少用户可调用的 list/delete 技能。新增两个 bundled skill 补全管理闭环：
+
+| 技能 | 用法 | 功能 |
+|------|------|------|
+| `/cron-list` | `/cron-list` | 调用 `CronListTool` 列出所有定时任务，表格显示 ID、Schedule、Prompt、Recurring、Durable |
+| `/cron-delete` | `/cron-delete <job-id>` | 调用 `CronDeleteTool` 按 ID 取消指定定时任务 |
+
+两个技能均受 `isKairosCronEnabled()` 门控（`feature('AGENT_TRIGGERS') && tengu_kairos_cron` gate），与 `ScheduleCronTool` 保持一致。
+
+#### 6. Fullscreen 门控修复
+
+- `src/utils/fullscreen.ts`: `isFullscreenEnvEnabled()` 从无条件返回 `true` 改为 `process.env.USER_TYPE === 'ant'`，避免非 ant 用户意外触发全屏模式
+
+### 修改文件
+
+| 文件 | 变更 |
+|------|------|
+| `build.ts` | `DEFAULT_BUILD_FEATURES` 新增 `ULTRAPLAN` |
+| `scripts/dev.ts` | `DEFAULT_FEATURES` 新增 `ULTRAPLAN` |
+| `src/commands.ts` | ultraplan 移入公开命令列表 |
+| `src/commands/ultraplan.tsx` | `isEnabled` 移除 ant-only 限制 |
+| `src/components/ultraplan/UltraplanChoiceDialog.tsx` | **新增** 从 2.1.92 反编译 |
+| `src/components/ultraplan/UltraplanLaunchDialog.tsx` | **新增** 从 2.1.92 反编译 |
+| `src/screens/REPL.tsx` | 添加 3 个 import |
+| `src/services/analytics/growthbook.ts` | fallback 链加固 |
+| `src/hooks/useAwaySummary.ts` | idle-based 离开检测 |
+| `src/skills/bundled/index.ts` | 注册 cron 技能 |
+| `src/skills/bundled/cronManage.ts` | **新增** cron list/delete 技能 |
+| `src/utils/fullscreen.ts` | fullscreen 门控修复 |
+
+### 验证
+
+| 项目 | 结果 |
+|------|------|
+| `bun run build` | ✅ 成功 (480 files) |
+| `bun run lint` | ✅ 仅已有 biome-ignore 警告 |
+| `/ultraplan` 手动测试 | ✅ 命令注册可见、能启动远程会话、能接收回传计划并显示 ChoiceDialog |
+
+### Ultraplan 工作流
+
+```
+/ultraplan <prompt>
+  → UltraplanLaunchDialog 确认
+  → teleportToRemote 创建 CCR 远程会话
+  → pollForApprovedExitPlanMode 轮询（3s 间隔，30min 超时）
+  → ExitPlanModeScanner 解析事件流
+  → 计划 approved → UltraplanChoiceDialog 显示选择
+  → Implement here / Start new session / Cancel
+```
+
+需要 Anthropic OAuth（`/login`）。远程会话在 claude.ai/code 上运行。
+
+---
+
+## GrowthBook Local Gate Defaults + P0/P1 Feature Enablement (2026-04-06)
+
+**分支**: `feat/growthbook-enablement`
+
+### 背景
+
+Claude Code 使用 GrowthBook（Anthropic 自建 proxy at api.anthropic.com）进行远程功能开关控制，代码中使用 `tengu_*` 前缀命名。在反编译版本中 GrowthBook 不启动（analytics 空实现），导致 70+ 个功能被 gate 拦截。
+
+经 4 个并行研究代理深度分析，确认**所有被 gate 控制的功能代码都是真实现**（非 stub）。
+
+### 实现方案
+
+**Commit 1** (`feat`): 在 `growthbook.ts` 中添加 `LOCAL_GATE_DEFAULTS` 映射表（25+ boolean gates + 2 object config gates），修改 4 个 getter 函数在 `isGrowthBookEnabled() === false` 时查找本地默认值。
+
+**Commit 2** (`fix`): 发现 `LOCAL_GATE_DEFAULTS` 在有 API key 的用户环境下无效——因为 `isGrowthBookEnabled()` 返回 `true`（analytics 未禁用），代码走 GrowthBook 路径但缓存为空，直接返回 `defaultValue` 跳过了本地默认值。修复：在 3 个 getter 函数的缓存 miss 路径中插入 `LOCAL_GATE_DEFAULTS` 查找。同时修复 `tengu_onyx_plover` 值类型（`JSON.stringify` → 直接对象）和新增 `tengu_kairos_brief_config` 对象型 gate。
+
+修复后的 fallback 链：
+```
+env overrides → config overrides → [GrowthBook 启用?]
+  → 内存缓存 → 磁盘缓存 → LOCAL_GATE_DEFAULTS → defaultValue
+```
+
+可通过 `CLAUDE_CODE_DISABLE_LOCAL_GATES=1` 环境变量一键禁用。
+
+### 启用的功能
+
+**P0 — 纯本地功能（7 个 gate）：**
+
+| Gate | 功能 |
+|------|------|
+| `tengu_keybinding_customization_release` | 自定义快捷键（~/.claude/keybindings.json） |
+| `tengu_streaming_tool_execution2` | 流式工具执行（边收边执行） |
+| `tengu_kairos_cron` | 定时任务系统 |
+| `tengu_amber_json_tools` | Token 高效 JSON 工具格式（省 ~4.5%） |
+| `tengu_immediate_model_command` | 运行中即时切换模型 |
+| `tengu_basalt_3kr` | MCP 指令增量传输 |
+| `tengu_pebble_leaf_prune` | 会话存储叶剪枝优化 |
+
+**P1 — API 依赖功能（8 个 gate）：**
+
+| Gate | 功能 |
+|------|------|
+| `tengu_session_memory` | 会话记忆（跨会话上下文持久化） |
+| `tengu_passport_quail` | 自动记忆提取 |
+| `tengu_chomp_inflection` | 提示建议 |
+| `tengu_hive_evidence` | 验证代理（对抗性验证） |
+| `tengu_kairos_brief` | Brief 精简输出模式 |
+| `tengu_sedge_lantern` | 离开摘要 |
+| `tengu_onyx_plover` | 自动梦境（记忆巩固） |
+| `tengu_willow_mode` | 空闲返回提示 |
+
+**Kill Switch（10 个 gate 保持 true）：**
+
+`tengu_turtle_carbon`、`tengu_amber_stoat`、`tengu_amber_flint`、`tengu_slim_subagent_claudemd`、`tengu_birch_trellis`、`tengu_collage_kaleidoscope`、`tengu_compact_cache_prefix`、`tengu_kairos_cron_durable`、`tengu_attribution_header`、`tengu_slate_prism`
+
+**新增编译 flag：**
+
+| Flag | build.ts | dev.ts | 用途 |
+|------|:--------:|:------:|------|
+| `AGENT_TRIGGERS` | ON | ON | 定时任务系统 |
+| `EXTRACT_MEMORIES` | ON | ON | 自动记忆提取 |
+| `VERIFICATION_AGENT` | ON | ON | 对抗性验证代理 |
+| `KAIROS_BRIEF` | ON | ON | Brief 精简模式 |
+| `AWAY_SUMMARY` | ON | ON | 离开摘要 |
+| `ULTRATHINK` | ON | ON | Ultrathink 扩展思考（双重门控修复） |
+| `BUILTIN_EXPLORE_PLAN_AGENTS` | ON | ON | 内置 Explore/Plan agents（双重门控修复） |
+| `LODESTONE` | ON | ON | Deep link 协议注册（双重门控修复） |
+
+**排除的编译 flag：**
+- `KAIROS` — 拉入 `useProactive.js`（缺失文件），`KAIROS_BRIEF` 足够
+- `TERMINAL_PANEL` — 拉入 `TerminalCaptureTool`（缺失文件）
+
+**双重门控修复说明：**
+部分功能同时被编译 flag 和 GrowthBook gate 控制（双重门控），仅开 GrowthBook gate 不够。
+审计发现 3 个被卡住的：`ULTRATHINK`、`BUILTIN_EXPLORE_PLAN_AGENTS`、`LODESTONE`。
+
+### 修改文件
+
+| 文件 | 变更 |
+|------|------|
+| `build.ts` | `DEFAULT_BUILD_FEATURES` 新增 8 个编译 flag |
+| `scripts/dev.ts` | `DEFAULT_FEATURES` 新增 8 个编译 flag |
+| `src/services/analytics/growthbook.ts` | 新增 `LOCAL_GATE_DEFAULTS` 映射（27 gates）+ `getLocalGateDefault()` + 修改 4 个 getter 的 fallback 链 |
+| `scripts/verify-gates.ts` | 新增 gate 验证脚本（30 gates） |
+| `docs/features/growthbook-enablement-plan.md` | 完整研究报告和启用计划 |
+| `docs/features/feature-flags-audit-complete.md` | 更新启用状态表 |
+
+### 验证
+
+| 项目 | 结果 |
+|------|------|
+| `bun run build` | ✅ 成功 (481 files) |
+| `bun test` | ✅ 2106 pass / 23 fail（均为已有问题）/ 0 新增失败 |
+| `verify-gates.ts` | ✅ 30/30 PASS |
+| `/brief` 手动测试 | ✅ 可用（fallback 修复后） |
+
+---
+
+## Enable SHOT_STATS, TOKEN_BUDGET, PROMPT_CACHE_BREAK_DETECTION (2026-04-05)
+
+**PR**: [claude-code-best/claude-code#140](https://github.com/claude-code-best/claude-code/pull/140)
+**分支**: `feat/enable-safe-feature-flags`
+
+对 22 个被标记为 "COMPLETE" 的编译时 feature flag 进行实际源码验证（6 个并行子代理 + Codex CLI 独立复核），发现审计报告存在大量误判。最终确认仅 3 个 flag 为真正 compile-only，安全启用。
+
+**验证流程：**
+
+1. 6 个并行子代理分别检查每个 flag 的 `feature('FLAG_NAME')` 引用点、依赖模块完整性、外部服务依赖
+2. Codex CLI (v0.118.0, 240K tokens) 独立复核，将原 7 个 "compile-only" 进一步缩减为 3 个
+3. 3 个专项代理逐一验证代码路径完整性和运行时安全性
+
+**新启用的 3 个 flag：**
+
+| Flag | 功能 | 用户可感知效果 |
+|------|------|---------------|
+| `SHOT_STATS` | shot 分布统计 | `/stats` 面板显示 shot 分布和 one-shot rate |
+| `TOKEN_BUDGET` | token 预算目标 | 支持 `+500k` / `spend 2M tokens` 语法，自动续写直到达标，带进度条 |
+| `PROMPT_CACHE_BREAK_DETECTION` | cache key 变化检测 | 内部诊断，`--debug` 模式可见，写 diff 到临时目录 |
+
+**修改文件：**
+
+| 文件 | 变更 |
+|------|------|
+| `build.ts` | `DEFAULT_BUILD_FEATURES` 新增 3 个 flag |
+| `scripts/dev.ts` | `DEFAULT_FEATURES` 新增 3 个 flag |
+| `package.json` / `bun.lock` | 新增 `openai` 依赖（OpenAI 兼容层需要） |
+
+**新增文档：**
+
+| 文件 | 说明 |
+|------|------|
+| `docs/features/feature-flags-codex-review.md` | Codex 独立复核报告：修正后的 5 类分类、恢复优先级、三轴分类标准建议 |
+| `docs/features/feature-flags-audit-complete.md` | 标记所有已启用 flag 的状态（`[build: ON]` / `[dev: ON]`） |
+
+**Codex 复核关键发现：**
+
+- 原 22 个 "COMPLETE" flag 中，8 个核心模块是 stub，3 个依赖远程服务
+- `TEAMMEM`、`AGENT_TRIGGERS`、`EXTRACT_MEMORIES`、`KAIROS_BRIEF` 被降级为"有条件可用"（受 GrowthBook 门控）
+- 建议审计分类标准改为三轴：实现完整度 × 激活条件 × 运行风险
+- 恢复优先级：REACTIVE_COMPACT > BG_SESSIONS > PROACTIVE > CONTEXT_COLLAPSE
+
+**验证结果：**
+
+- `bun run build` → 475 files ✅
+- `bun test` → 零新增失败 ✅
+- 3 个 flag 代码路径全部完整，无缺失依赖，无 crash 风险 ✅
+
+---
+
+## /dream 手动触发 + DreamTask 类型补全 (2026-04-04)
+
+将 `/dream` 命令从 KAIROS feature gate 中解耦，作为 bundled skill 无条件注册；补全 DreamTask 类型存根。
+
+**新增文件：**
+
+| 文件 | 说明 |
+|------|------|
+| `src/skills/bundled/dream.ts` | `/dream` skill 注册，调用 `buildConsolidationPrompt()` 生成整理提示词 |
+
+**修改文件：**
+
+| 文件 | 变更 |
+|------|------|
+| `src/skills/bundled/index.ts` | 导入并注册 `registerDreamSkill()` |
+| `src/components/tasks/src/tasks/DreamTask/DreamTask.ts` | `any` 存根 → 从 `src/tasks/DreamTask/DreamTask.js` 重新导出完整类型 |
+
+**新增文档：**
+
+| 文件 | 说明 |
+|------|------|
+| `docs/features/auto-dream.md` | Auto Dream 原理、触发机制、使用场景完整说明 |
+
+---
+
+## Computer Use macOS 适配修复 (2026-04-04)
+
+**分支**: `feature/computer-use/mac-support`
+
+- **darwin.ts** — 应用枚举改用 Spotlight `mdfind` + `mdls`，获取真实 bundleId（旧方案合成 `com.app.xxx`），覆盖 `/Applications` + `/System/Applications` + CoreServices
+- **index.ts** — 新增 `hotkey` backend fallback，非原生模块不崩溃
+- **toolCalls.ts** — `resolveRequestedApps()` 新增子串模糊匹配（`"Chrome"` → `"Google Chrome"`）
+- **hostAdapter.ts** — `ensureOsPermissions()` 检查 `cu.tcc` 存在性，跨平台 JS backend 安全降级
+- **测试**: 17 个 MCP 工具中 10 个完全通过，6 个在 full tier 应用上通过（IDE click tier 受限为预期行为），`screenshot` 未返回图片（疑似屏幕录制权限问题）
+
+---
+
+## Computer Use Windows 增强：窗口绑定截图 + UI Automation + OCR (2026-04-03)
+
+
+在三平台基础实现之上，利用 Windows 原生 API 增强 Computer Use 的 Windows 专属能力。
+
+**新增文件：**
+
+| 文件 | 行数 | 说明 |
+|------|------|------|
+| `src/utils/computerUse/win32/windowCapture.ts` | — | `PrintWindow` 窗口绑定截图，支持被遮挡/后台窗口 |
+| `src/utils/computerUse/win32/windowEnum.ts` | — | `EnumWindows` 精确窗口枚举（HWND + PID + 标题） |
+| `src/utils/computerUse/win32/uiAutomation.ts` | — | `IUIAutomation` UI 元素树读取、按钮点击、文本写入、坐标识别 |
+| `src/utils/computerUse/win32/ocr.ts` | — | `Windows.Media.Ocr` 截图+文字识别（英语+中文） |
+
+**修改文件：**
+
+| 文件 | 变更 |
+|------|------|
+| `packages/@ant/computer-use-swift/src/backends/win32.ts` | `listRunning` 改用 EnumWindows；新增 `captureWindowTarget` 窗口级截图 |
+
+**验证结果（Windows x64）：**
+- 窗口枚举：38 个可见窗口 ✅
+- 窗口截图：VS Code 2575x1415, 444KB ✅（PrintWindow, 即使被遮挡）
+- UI Automation：坐标元素识别 ✅
+- OCR：识别 VS Code 界面文字，34 行 ✅
+
+---
+
+## Enable Computer Use — macOS + Windows + Linux (2026-04-03)
+
+恢复 Computer Use 屏幕操控功能。参考项目仅 macOS，本次扩展为三平台支持。
+
+**Phase 1 — MCP server stub 替换：**
+从参考项目复制 `@ant/computer-use-mcp` 完整实现（12 文件，6517 行）。
+
+**Phase 2 — 移除 src/ 中 8 处 macOS 硬编码：**
+
+| 文件 | 改动 |
+|------|------|
+| `src/main.tsx:1605` | 去掉 `getPlatform() === 'macos'` |
+| `src/utils/computerUse/swiftLoader.ts` | 移除 darwin-only throw |
+| `src/utils/computerUse/executor.ts` | 平台守卫扩展为 darwin+win32+linux；剪贴板按平台分发（pbcopy→PowerShell→xclip）；paste 快捷键 command→ctrl |
+| `src/utils/computerUse/drainRunLoop.ts` | 非 darwin 直接执行 fn() |
+| `src/utils/computerUse/escHotkey.ts` | 非 darwin 返回 false（Ctrl+C fallback） |
+| `src/utils/computerUse/hostAdapter.ts` | 非 darwin 权限检查返回 granted |
+| `src/utils/computerUse/common.ts` | platform + screenshotFiltering 动态化 |
+| `src/utils/computerUse/gates.ts` | enabled:true + hasRequiredSubscription→true |
+
+**Phase 3 — input/swift 包 dispatcher + backends 三平台架构：**
+
+```
+packages/@ant/computer-use-{input,swift}/src/
+├── index.ts          ← dispatcher
+├── types.ts          ← 共享接口
+└── backends/
+    ├── darwin.ts      ← macOS AppleScript（原样拆出，不改逻辑）
+    ├── win32.ts       ← Windows PowerShell
+    └── linux.ts       ← Linux xdotool/scrot/xrandr/wmctrl
+```
+
+**编译开关：** `CHICAGO_MCP` 加入 DEFAULT_FEATURES + DEFAULT_BUILD_FEATURES
+
+**验证结果（Windows x64）：**
+- `isSupported: true` ✅
+- 鼠标定位 + 前台窗口信息 ✅
+- 双显示器检测 2560x1440 × 2 ✅
+- 全屏截图 3MB base64 ✅
+- `bun run build` 463 files ✅
+
+---
+
+## Enable Voice Mode / VOICE_MODE (2026-04-03)
+
+恢复 `/voice` 语音输入功能。`src/` 下所有 voice 相关源码已与官方一致（0 行差异），问题出在：① `VOICE_MODE` 编译开关未开，命令不显示；② `audio-capture-napi` 是 SoX 子进程 stub（Windows 不支持），缺少官方原生 `.node` 二进制。
+
+**新增文件：**
+
+| 文件 | 说明 |
+|------|------|
+| `vendor/audio-capture/{platform}/audio-capture.node` | 6 个平台的原生音频二进制（cpal，来自参考项目） |
+| `vendor/audio-capture-src/index.ts` | 原生模块加载器（按 `${arch}-${platform}` 动态 require `.node`） |
+
+---
+
+## Enable Claude in Chrome MCP (2026-04-03)
+
+恢复 Chrome 浏览器控制功能。`src/` 下所有 claudeInChrome 相关源码已与官方一致（0 行差异），问题出在 `@ant/claude-for-chrome-mcp` 包是 6 行 stub（返回空工具列表和 null server）。
+
+**替换文件：**
+
+| 文件 | 变更 |
+|------|------|
+| `packages/@ant/claude-for-chrome-mcp/src/index.ts` | 6 行 stub → 15 行完整导出 |
+
+**新增文件：**
+
+| 文件 | 行数 | 说明 |
+|------|------|------|
+| `packages/@ant/claude-for-chrome-mcp/src/types.ts` | 134 | 类型定义 |
+| `packages/@ant/claude-for-chrome-mcp/src/browserTools.ts` | 546 | 17 个浏览器工具定义 |
+| `packages/@ant/claude-for-chrome-mcp/src/mcpServer.ts` | 96 | MCP Server |
+| `packages/@ant/claude-for-chrome-mcp/src/mcpSocketClient.ts` | 493 | Unix Socket 客户端 |
+| `packages/@ant/claude-for-chrome-mcp/src/mcpSocketPool.ts` | 327 | 多 Profile 连接池 |
+| `packages/@ant/claude-for-chrome-mcp/src/bridgeClient.ts` | 1126 | Bridge WebSocket 客户端 |
+| `packages/@ant/claude-for-chrome-mcp/src/toolCalls.ts` | 301 | 工具调用路由 |
+
+**不需要 feature flag，不需要改 dev.ts/build.ts，不改 src/ 下任何文件。**
+
+**运行时依赖：** Chrome 浏览器 + Claude in Chrome 扩展（https://claude.ai/chrome）
+
+---
+
 ## OpenAI 接口兼容 (2026-04-03)
 
 **分支**: `feature/openai`
@@ -285,3 +991,4 @@ GrowthBook 功能开关系统原为 Anthropic 内部构建设计，硬编码 SDK
 ```
 
 非空字段才写入，保存后立即生效（`onDone()` 触发 `onChangeAPIKey()` 刷新 API 客户端）。
+

Friends.md

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

README.md

@@ -6,63 +6,127 @@
 [![GitHub License](https://img.shields.io/github/license/claude-code-best/claude-code?style=flat-square)](https://github.com/claude-code-best/claude-code/blob/main/LICENSE)
 [![Last Commit](https://img.shields.io/github/last-commit/claude-code-best/claude-code?style=flat-square&color=blue)](https://github.com/claude-code-best/claude-code/commits/main)
 [![Bun](https://img.shields.io/badge/runtime-Bun-black?style=flat-square&logo=bun)](https://bun.sh/)
-[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?style=flat-square&logo=discord)](https://discord.gg/qZU6zS7Q)
+[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?style=flat-square&logo=discord)](https://discord.gg/uApuzJWGKX)
 
 > Which Claude do you like? The open source one is the best.
 
-牢 A (Anthropic) 官方 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI 工具的源码反编译/逆向还原项目。目标是将 Claude Code 大部分功能及工程化能力复现 (问就是老佛爷已经付过钱了)。虽然很难绷, 但是它叫做 CCB(踩踩背)...
+牢 A (Anthropic) 官方 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 完整复原的工程化项目。虽然很难绷, 但是它叫做 CCB(踩踩背)... 而且, 我们实现了企业版或者需要登陆 Claude 账号才能使用的特性, 并在此基础上扩展了更多好玩的特性。
 
-[文档在这里, 支持投稿 PR](https://ccb.agent-aura.top/)
+[Peri Code](https://github.com/KonghaYao/peri)：Claude Code 兼容的 Rust Agent，多年大模型经验匠心制作，国内大模型（DeepSeek/GLM）精调，CPU/内存极致优化，在开发版/树莓派上也能跑 CC 一样的体验。
 
-[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/agents/uds-inbox) / [LAN](https://ccb.agent-aura.top/docs/features/agents/lan-pipes)                |
+| **ACP 协议一等一支持**      | 支持接入 Zed、Cursor 等 IDE，支持会话恢复、Skills、权限桥接                                                                  | [文档](https://ccb.agent-aura.top/docs/features/agents/acp-zed)                                                                                  |
+| **Remote Control 私有部署** | Docker 自托管远程界面, 可以手机上看 CC                                                                                       | [文档](https://ccb.agent-aura.top/docs/features/modes/remote-control-self-hosting)                                                              |
+| **Langfuse 监控**           | 企业级 Agent 监控, 可以清晰看到每次 agent loop 细节, 可以一键转化为数据集                                                    | [文档](https://ccb.agent-aura.top/docs/features/tools/langfuse-monitoring)                                                                      |
+| **Web Search**              | 内置网页搜索工具, 支持 bing 和 brave 搜索                                                                                    | [文档](https://ccb.agent-aura.top/docs/features/external/web-browser-tool)                                                                         |
+| **Poor Mode**               | 穷鬼模式，关闭记忆提取和键入建议,大幅度减少并发请求                                                                          | /poor 可以开关                                                                                                                            |
+| **Channels 频道通知**       | MCP 服务器推送外部消息到会话（飞书/Slack/Discord/微信等），`--channels plugin:name@marketplace` 启用                         | [文档](https://ccb.agent-aura.top/docs/features/external/channels)                                                                                 |
+| **自定义模型供应商**        | OpenAI/Anthropic/Gemini/Grok 兼容  (`/login`)                                                                                          | [文档](https://ccb.agent-aura.top/docs/getting-started/model-providers)                                                                        |
+| Voice Mode                  | 语音输入，支持豆包语言输入（`/voice doubao`）                                                                   | [文档](https://ccb.agent-aura.top/docs/features/external/voice-mode)                                                                               |
+| Computer Use                | 屏幕截图、键鼠控制                                                                                                           | [文档](https://ccb.agent-aura.top/docs/features/external/computer-use)                                                                             |
+| Chrome Use                  | 浏览器自动化、表单填写、数据抓取                                                                                             | [自托管](https://ccb.agent-aura.top/docs/features/external/chrome-use-mcp) [原生版](https://ccb.agent-aura.top/docs/features/external/claude-in-chrome-mcp) |
+| Sentry                      | 企业级错误追踪                                                                                                               | [文档](https://ccb.agent-aura.top/docs/internals/sentry-setup)                                                                            |
+| GrowthBook                  | 企业级特性开关                                                                                                               | [文档](https://ccb.agent-aura.top/docs/internals/growthbook-adapter)                                                                      |
+| /dream 记忆整理             | 自动整理和优化记忆文件                                                                                                       | [文档](https://ccb.agent-aura.top/docs/features/modes/auto-dream)                                                                               |
 
-- [x] v1 会完成跑通及基本的类型检查通过;
-- [x] V2 会完整实现工程化配套设施;
-  - [ ] Biome 格式化可能不会先实施, 避免代码冲突
-  - [x] 构建流水线完成, 产物 Node/Bun 都可以运行
-- [x] V3 会写大量文档, 完善文档站点
-- [x] V4 会完成大量的测试文件, 以提高稳定性
-  - [x] Buddy 小宠物回来啦 [文档](https://ccb.agent-aura.top/docs/features/buddy)
-  - [x] Auto Mode 回归 [文档](https://ccb.agent-aura.top/docs/safety/auto-mode)
-  - [x] 所有 Feature 现在可以通过环境变量配置, 而不是垃圾的 bun --feature
-- [x] V5 支持企业级的监控上报功能, 补全缺失的工具, 解除限制
-  - [x] 移除牢 A 的反蒸馏代码!!!
-  - [x] 补全 web search 能力(用的 Bing 搜索)!!! [文档](https://ccb.agent-aura.top/docs/features/web-browser-tool)
-  - [x] 支持 Debug [文档](https://ccb.agent-aura.top/docs/features/debug-mode)
-  - [x] 关闭自动更新;
-  - [x] 添加自定义 sentry 错误上报支持 [文档](https://ccb.agent-aura.top/docs/internals/sentry-setup)
-  - [x] 添加自定义 GrowthBook 支持 (GB 也是开源的, 现在你可以配置一个自定义的遥控平台) [文档](https://ccb.agent-aura.top/docs/internals/growthbook-adapter)
-  - [x] 自定义 login 模式, 大家可以用这个配置 Claude 的模型!
-  - [x] 修复搜索工具的 rg 缺失问题(需要重新 bun i)
-  - [ ] OpenAI 接口兼容! /login 然后配置 OpenAI 平台即可!
-- [ ] V6 大规模重构石山代码, 全面模块分包
-  - [ ] V6 将会为全新分支, 届时 main 分支将会封存为历史版本
+- 🚀 [想要启动项目](#-快速开始源码版)
+- 🐛 [想要调试项目](#vs-code-调试)
+- 📖 [想要学习项目](#teach-me-学习项目)
 
-> 我不知道这个项目还会存在多久, Star + Fork + git clone + .zip 包最稳健; 说白了就是扛旗项目, 看看能走多远
->
-> 这个项目更新很快, 后台有 Opus 持续优化, 几乎几个小时就有新变化;
->
-> Claude 已经烧了 1000$ 以上, 没钱了, 换成 GLM 继续玩; @zai-org GLM 5.1 非常可以;
->
+## ⚡ 快速开始(安装版)
 
-## 快速开始
+不用克隆仓库, 从 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
+
+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@<版本号>`
+
+## ⚡ 快速开始(源码版)
+
+### ⚙️ 环境要求
 
 一定要最新版本的 bun 啊, 不然一堆奇奇怪怪的 BUG!!! bun upgrade!!!
 
-- [Bun](https://bun.sh/) >= 1.3.11
-- 常规的配置 CC 的方式, 各大提供商都有自己的配置方式
+- 📦 [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
 ```
 
-### 运行
+### ▶️ 运行
 
 ```bash
 # 开发模式, 看到版本号 888 说明就是对了
@@ -78,39 +142,24 @@ bun run build
 
 如果遇到 bug 请直接提一个 issues, 我们优先解决
 
-### 新人配置 /login
+### 👤 新人配置 /login
 
-首次运行后，在 REPL 中输入 `/login` 命令进入登录配置界面，选择 **Custom Platform** 即可对接第三方 API 兼容服务（无需 Anthropic 官方账号）。
+首次运行后，在 REPL 中输入 `/login` 命令进入登录配置界面，选择 **Anthropic Compatible** 即可对接第三方 API 兼容服务（无需 Anthropic 官方账号）。
+选择 OpenAI 和 Gemini 对应的栏目都是支持相应协议的
 
 需要填写的字段：
 
-| 字段 | 说明 | 示例 |
-|------|------|------|
-| 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 保存
-- 模型字段会自动读取当前环境变量预填
-- 配置保存到 `~/.claude/settings.json` 的 `env` 字段，保存后立即生效
+- ⌨️ **Tab / Shift+Tab** 切换字段，**Enter** 确认并跳到下一个，最后一个字段按 Enter 保存
 
-也可以直接编辑 `~/.claude/settings.json`：
-
-```json
-{
-  "env": {
-    "ANTHROPIC_BASE_URL": "https://api.example.com/v1",
-    "ANTHROPIC_AUTH_TOKEN": "sk-xxx",
-    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5-20251001",
-    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6",
-    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-6"
-  }
-}
-```
-
-> 支持所有 Anthropic API 兼容服务（如 OpenRouter、AWS Bedrock 代理等），只要接口兼容 Messages API 即可。
+> ℹ️ 支持所有 Anthropic API 兼容服务（如 OpenRouter、AWS Bedrock 代理等），只要接口兼容 Messages API 即可。
 
 ## Feature Flags
 
@@ -129,25 +178,49 @@ TUI (REPL) 模式需要真实终端，无法直接通过 VS Code launch 启动
 ### 步骤
 
 1. **终端启动 inspect 服务**：
+
    ```bash
    bun run dev:inspect
    ```
-   会输出类似 `ws://localhost:8888/xxxxxxxx` 的地址。
 
+   会输出类似 `ws://localhost:8888/xxxxxxxx` 的地址。
 2. **VS Code 附着调试器**：
+
    - 在 `src/` 文件中打断点
    - F5 → 选择 **"Attach to Bun (TUI debug)"**
 
+## Teach Me 学习项目
+
+我们新加了一个 teach-me skills, 通过问答式引导帮你理解这个项目的任何模块。(调整 [sigma skill 而来](https://github.com/sanyuan0704/sanyuan-skills))
+
+```bash
+# 在 REPL 中直接输入
+/teach-me Claude Code 架构
+/teach-me React Ink 终端渲染 --level beginner
+/teach-me Tool 系统 --resume
+```
+
+### 它能做什么
+
+- **诊断水平** — 自动评估你对相关概念的掌握程度，跳过已知的、聚焦薄弱的
+- **构建学习路径** — 将主题拆解为 5-15 个原子概念，按依赖排序逐步推进
+- **苏格拉底式提问** — 用选项引导思考，而非直接给答案
+- **错误概念追踪** — 发现并纠正深层误解
+- **断点续学** — `--resume` 从上次进度继续
+
+### 学习记录
+
+学习进度保存在 `.claude/skills/teach-me/` 目录下，支持跨主题学习者档案。
 
 ## 相关文档及网站
 
 - **在线文档（Mintlify）**: [ccb.agent-aura.top](https://ccb.agent-aura.top/) — 文档源码位于 [`docs/`](docs/) 目录，欢迎投稿 PR
-- **DeepWiki**: <https://deepwiki.com/claude-code-best/claude-code>
+- **DeepWiki**: [https://deepwiki.com/claude-code-best/claude-code](https://deepwiki.com/claude-code-best/claude-code)
 
 ## Contributors
 
 <a href="https://github.com/claude-code-best/claude-code/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=claude-code-best/claude-code" />
+  <img src="contributors.svg" alt="Contributors" />
 </a>
 
 ## Star History
@@ -160,6 +233,10 @@ TUI (REPL) 模式需要真实终端，无法直接通过 VS Code launch 启动
  </picture>
 </a>
 
+## 致谢
+
+- [doubaoime-asr](https://github.com/starccy/doubaoime-asr) — 豆包 ASR 语音识别 SDK，为 Voice Mode 提供无需 Anthropic OAuth 的语音输入方案
+
 ## 许可证
 
 本项目仅供学习研究用途。Claude Code 的所有权利归 [Anthropic](https://www.anthropic.com/) 所有。

README_EN.md

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

TODO.md

@@ -1,26 +0,0 @@
-# TODO
-
-尽可能实现下面的包, 使得与主包的关系完全吻合
-
-## Packages
-
-- [x] `url-handler-napi` — URL 处理 NAPI 模块 (签名修正，保持 null fallback)
-- [x] `modifiers-napi` — 修饰键检测 NAPI 模块 (Bun FFI + Carbon)
-- [x] `audio-capture-napi` — 音频捕获 NAPI 模块 (SoX/arecord)
-- [x] `color-diff-napi` — 颜色差异计算 NAPI 模块 (纯 TS 实现)
-- [x] `image-processor-napi` — 图像处理 NAPI 模块 (sharp + osascript 剪贴板)
-
-- [x] `@ant/computer-use-swift` — Computer Use Swift 原生模块 (macOS JXA/screencapture 实现)
-- [x] `@ant/computer-use-mcp` — Computer Use MCP 服务 (类型安全 stub + sentinel apps + targetImageSize)
-- [x] `@ant/computer-use-input` — Computer Use 输入模块 (macOS AppleScript/JXA 实现)
-<!-- - [ ] `@ant/claude-for-chrome-mcp` — Chrome MCP 扩展 -->
-
-## 工程化能力
-
-- [x] 代码格式化与校验
-- [x] 冗余代码检查
-- [x] git hook 的配置
-- [x] 代码健康度检查
-- [x] Biome lint 规则调优（适配反编译代码，关闭格式化避免大规模 diff）
-- [x] 单元测试基础设施搭建 (test runner 配置)
-- [x] CI/CD 流水线 (GitHub Actions)

biome.json

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

build.ts

@@ -1,76 +1,108 @@
-import { readdir, readFile, writeFile } from "fs/promises";
-import { join } from "path";
-import { getMacroDefines } from "./scripts/defines.ts";
+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";
+const outdir = 'dist'
 
 // Step 1: Clean output directory
-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"];
+const { rmSync } = await import('fs')
+rmSync(outdir, { recursive: true, force: true })
 
 // Collect FEATURE_* env vars → Bun.build features
 const envFeatures = Object.keys(process.env)
-    .filter(k => k.startsWith("FEATURE_"))
-    .map(k => k.replace("FEATURE_", ""));
-const features = [...new Set([...DEFAULT_BUILD_FEATURES, ...envFeatures])];
+  .filter(k => k.startsWith('FEATURE_'))
+  .map(k => k.replace('FEATURE_', ''))
+const features = [...new Set([...DEFAULT_BUILD_FEATURES, ...envFeatures])]
 
 // Step 2: Bundle with splitting
 const result = await Bun.build({
-    entrypoints: ["src/entrypoints/cli.tsx"],
-    outdir,
-    target: "bun",
-    splitting: true,
-    define: getMacroDefines(),
-    features,
-});
+  entrypoints: ['src/entrypoints/cli.tsx'],
+  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'),
+  },
+  features,
+})
 
 if (!result.success) {
-    console.error("Build failed:");
-    for (const log of result.logs) {
-        console.error(log);
-    }
-    process.exit(1);
+  console.error('Build failed:')
+  for (const log of result.logs) {
+    console.error(log)
+  }
+  process.exit(1)
 }
 
 // Step 3: Post-process — replace Bun-only `import.meta.require` with Node.js compatible version
-const files = await readdir(outdir);
-const IMPORT_META_REQUIRE = "var __require = import.meta.require;";
-const COMPAT_REQUIRE = `var __require = typeof import.meta.require === "function" ? import.meta.require : (await import("module")).createRequire(import.meta.url);`;
+const files = await readdir(outdir)
+const IMPORT_META_REQUIRE = 'var __require = import.meta.require;'
+const COMPAT_REQUIRE = `var __require = typeof import.meta.require === "function" ? import.meta.require : (await import("module")).createRequire(import.meta.url);`
 
-let patched = 0;
+let patched = 0
 for (const file of files) {
-    if (!file.endsWith(".js")) continue;
-    const filePath = join(outdir, file);
-    const content = await readFile(filePath, "utf-8");
-    if (content.includes(IMPORT_META_REQUIRE)) {
-        await writeFile(
-            filePath,
-            content.replace(IMPORT_META_REQUIRE, COMPAT_REQUIRE),
-        );
-        patched++;
-    }
+  if (!file.endsWith('.js')) continue
+  const filePath = join(outdir, file)
+  const content = await readFile(filePath, 'utf-8')
+  if (content.includes(IMPORT_META_REQUIRE)) {
+    await writeFile(
+      filePath,
+      content.replace(IMPORT_META_REQUIRE, COMPAT_REQUIRE),
+    )
+    patched++
+  }
 }
 
+// Also patch unguarded globalThis.Bun destructuring from third-party deps
+// (e.g. @anthropic-ai/sandbox-runtime) so Node.js doesn't crash at import time.
+let bunPatched = 0
+const BUN_DESTRUCTURE = /var \{([^}]+)\} = globalThis\.Bun;?/g
+const BUN_DESTRUCTURE_SAFE =
+  'var {$1} = typeof globalThis.Bun !== "undefined" ? globalThis.Bun : {};'
+for (const file of files) {
+  if (!file.endsWith('.js')) continue
+  const filePath = join(outdir, file)
+  const content = await readFile(filePath, 'utf-8')
+  if (BUN_DESTRUCTURE.test(content)) {
+    await writeFile(
+      filePath,
+      content.replace(BUN_DESTRUCTURE, BUN_DESTRUCTURE_SAFE),
+    )
+    bunPatched++
+  }
+}
+BUN_DESTRUCTURE.lastIndex = 0
+
 console.log(
-    `Bundled ${result.outputs.length} files to ${outdir}/ (patched ${patched} for Node.js compat)`,
-);
+  `Bundled ${result.outputs.length} files to ${outdir}/ (patched ${patched} for import.meta.require, ${bunPatched} for Bun destructure)`,
+)
 
-// Step 4: 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 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}/`)
+
+const ripgrepDir = join(outdir, 'vendor', 'ripgrep')
+await cp('src/utils/vendor/ripgrep', ripgrepDir, { recursive: true })
+console.log(`Copied src/utils/vendor/ripgrep/ → ${ripgrepDir}/`)
+
+// Step 5: Generate cli-bun and cli-node executable entry points
+const cliBun = join(outdir, 'cli-bun.js')
+const cliNode = join(outdir, 'cli-node.js')
+
+await writeFile(cliBun, '#!/usr/bin/env bun\nimport "./cli.js"\n')
+
+await writeFile(cliNode, '#!/usr/bin/env node\nimport "./cli.js"\n')
+
+// Make both executable
+const { chmodSync } = await import('fs')
+chmodSync(cliBun, 0o755)
+chmodSync(cliNode, 0o755)
+
+console.log(`Generated ${cliBun} (shebang: bun) and ${cliNode} (shebang: node)`)

codecov.yml

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

docs-outline-draft.md

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

docs.json

@@ -0,0 +1,127 @@
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "theme": "mint",
+  "name": "Claude Code Best",
+  "description": "Anthropic Claude Code 的开源复原版本 — 完整架构原理、功能文档与使用指南。",
+  "colors": {
+    "primary": "#D77757",
+    "light": "#F59E0B",
+    "dark": "#B45309"
+  },
+  "favicon": "/docs/favicon.svg",
+  "logo": {
+    "light": "/docs/logo/light.svg",
+    "dark": "/docs/logo/dark.svg"
+  },
+  "background": {
+    "color": {
+      "light": "#FFFFFF",
+      "dark": "#0F172A"
+    }
+  },
+  "navbar": {
+    "primary": {
+      "type": "github",
+      "href": "https://github.com/claude-code-best/claude-code"
+    }
+  },
+  "search": {
+    "prompt": "搜索 CCB 文档..."
+  },
+  "seo": {
+    "metatags": {
+      "og:image": "https://ccb.agent-aura.top/docs/images/og-cover.png",
+      "twitter:image": "https://ccb.agent-aura.top/docs/images/og-cover.png",
+      "twitter:card": "summary_large_image"
+    },
+    "indexing": "navigable"
+  },
+  "footer": {
+    "socials": {
+      "github": "https://github.com/claude-code-best/claude-code",
+      "discord": "https://discord.gg/uApuzJWGKX"
+    }
+  },
+  "redirects": [
+    {
+      "source": "/docs/features/agents/uds-inbox",
+      "destination": "/docs/features/agents/pipes-and-lan"
+    },
+    {
+      "source": "/docs/features/agents/lan-pipes",
+      "destination": "/docs/features/agents/pipes-and-lan"
+    },
+    {
+      "source": "/docs/features/agents/acp-link",
+      "destination": "/docs/features/agents/acp"
+    },
+    {
+      "source": "/docs/features/agents/acp-zed",
+      "destination": "/docs/features/agents/acp"
+    },
+    {
+      "source": "/docs/features/external/chrome-use-mcp",
+      "destination": "/docs/features/external/chrome-control"
+    },
+    {
+      "source": "/docs/features/external/claude-in-chrome-mcp",
+      "destination": "/docs/features/external/chrome-control"
+    },
+    {
+      "source": "/docs/features/external/computer-use-tools-reference",
+      "destination": "/docs/features/external/computer-use"
+    }
+  ],
+  "navigation": {
+    "groups": [
+      {
+        "group": "开始",
+        "pages": [
+          "docs/getting-started/installation",
+          "docs/getting-started/quickstart",
+          "docs/getting-started/model-providers"
+        ]
+      },
+      {
+        "group": "核心功能",
+        "pages": [
+          {
+            "group": "协作与多 Agent",
+            "pages": [
+              "docs/features/agents/pipes-and-lan",
+              "docs/features/agents/acp"
+            ]
+          },
+          {
+            "group": "外部接入",
+            "pages": [
+              "docs/features/external/channels",
+              "docs/features/external/chrome-control",
+              "docs/features/external/computer-use",
+              "docs/features/external/voice-mode",
+              "docs/features/external/web-browser-tool"
+            ]
+          },
+          {
+            "group": "运行模式",
+            "pages": [
+              "docs/features/modes/auto-dream",
+              "docs/features/modes/remote-control-self-hosting"
+            ]
+          },
+          {
+            "group": "工具与体验",
+            "pages": ["docs/features/tools/langfuse-monitoring"]
+          }
+        ]
+      },
+      {
+        "group": "内部机制",
+        "pages": [
+          "docs/internals/growthbook-adapter",
+          "docs/internals/sentry-setup"
+        ]
+      }
+    ]
+  }
+}

docs.md

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

docs/REVISION-PLAN.md

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

docs/agent/coordinator-and-swarm.mdx

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

docs/agent/sub-agents.mdx

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

docs/agent/worktree-isolation.mdx

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

docs/auto-updater.md

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

docs/context/compaction.mdx

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

docs/context/project-memory.mdx

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

docs/context/system-prompt.mdx

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

docs/context/token-budget.mdx

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

docs/conversation/multi-turn.mdx

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

docs/conversation/streaming.mdx

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

docs/conversation/the-loop.mdx

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

docs/extensibility/custom-agents.mdx

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

docs/extensibility/hooks.mdx

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

docs/extensibility/mcp-protocol.mdx

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

docs/extensibility/skills.mdx

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

docs/external-dependencies.md

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

docs/feature-exploration-plan.md

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

docs/features/agents/acp.md

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

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

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

docs/features/bash-classifier.md

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

docs/features/bridge-mode.md

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

docs/features/buddy.mdx

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

docs/features/context-collapse.md

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

docs/features/coordinator-mode.md

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

docs/features/daemon.md

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

docs/features/debug-mode.mdx

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

docs/features/experimental-skill-search.md

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

docs/features/external/channels.md

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

docs/features/external/chrome-control.md

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

docs/features/external/computer-use.md

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

docs/features/external/voice-mode.md

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

docs/features/external/web-browser-tool.md

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

docs/features/fork-subagent.md

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

docs/features/kairos.md

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

docs/features/mcp-skills.md

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

docs/features/modes/auto-dream.md

@@ -0,0 +1,188 @@
+---
+title: "后台记忆整理（Auto Dream）"
+description: "会话间自动审查、组织和修剪持久化记忆，确保未来会话快速获得准确上下文。"
+keywords: ["Auto Dream", "记忆整合", "后台任务", "MEMORY.md", "/dream 命令"]
+---
+
+# Auto Dream — 自动记忆整理
+
+## 概述
+
+Auto Dream 是 Claude Code 的后台记忆整合机制。它在会话间自动审查、组织和修剪持久化记忆文件，确保未来会话能快速获得准确的上下文。
+
+记忆系统存储在文件系统中（默认 `~/.claude/projects/<project-slug>/memory/`），由 `MEMORY.md` 索引文件和若干主题文件（如 `user_language.md`、`project_overview.md`）组成。随着会话积累，记忆会变得过时、冗余或矛盾——Dream 负责清理这些堆积。
+
+## 架构
+
+### 核心模块
+
+| 模块 | 路径 | 职责 |
+|------|------|------|
+| 调度器 | `src/services/autoDream/autoDream.ts` | 时间/会话/锁三重门控，触发 forked agent |
+| 配置 | `src/services/autoDream/config.ts` | 读取 `isAutoDreamEnabled()` 开关 |
+| 提示词 | `src/services/autoDream/consolidationPrompt.ts` | 构建 4 阶段整理提示词 |
+| 锁文件 | `src/services/autoDream/consolidationLock.ts` | PID 锁 + mtime 作为 `lastConsolidatedAt` |
+| 任务 UI | `src/tasks/DreamTask/DreamTask.ts` | 后台任务注册，footer pill + Shift+Down 可见 |
+| 手动入口 | `src/skills/bundled/dream.ts` | `/dream` 命令，无条件可用 |
+
+### 记忆路径解析
+
+优先级（`src/memdir/paths.ts`）：
+
+1. `CLAUDE_COWORK_MEMORY_PATH_OVERRIDE` 环境变量（完整路径覆盖）
+2. `autoMemoryDirectory` 设置项（`settings.json`，支持 `~/` 展开）
+3. 默认：`<memoryBase>/projects/<sanitized-git-root>/memory/`
+
+其中 `memoryBase` = `CLAUDE_CODE_REMOTE_MEMORY_DIR` 或 `~/.claude`。
+
+## 触发机制
+
+### 自动触发（Auto Dream）
+
+每个对话轮次结束后，`executeAutoDream()` 按顺序检查三重门控：
+
+```
+┌─────────────────────────────────────────────────────┐
+│  Gate 1: 全局开关                                     │
+│  isAutoMemoryEnabled() && isAutoDreamEnabled()       │
+│  排除: KAIROS 模式 / Remote 模式                      │
+├─────────────────────────────────────────────────────┤
+│  Gate 2: 时间门控                                     │
+│  hoursSince(lastConsolidatedAt) >= minHours          │
+│  默认: 24 小时                                        │
+├─────────────────────────────────────────────────────┤
+│  Gate 3: 会话门控                                     │
+│  sessionsTouchedSince(lastConsolidatedAt) >= minSessions │
+│  默认: 5 个会话（排除当前会话）                         │
+├─────────────────────────────────────────────────────┤
+│  Lock: PID 锁文件                                     │
+│  .consolidate-lock (mtime = lastConsolidatedAt)      │
+│  死进程检测 + 1 小时过期                               │
+└─────────────────────────────────────────────────────┘
+```
+
+全部通过后，以 **forked agent**（受限子代理）方式运行整理任务：
+
+- Bash 工具限制为只读命令（`ls`、`grep`、`cat` 等）
+- 只能读写记忆目录内的文件
+- 用户可在 Shift+Down 后台任务面板中查看进度或终止
+
+### 手动触发（`/dream` 命令）
+
+通过 `/dream` 命令随时触发，无门控限制：
+
+- 在主循环中运行（非 forked agent），拥有完整工具权限
+- 用户可实时观察操作过程
+- 执行前自动更新锁文件 mtime
+
+### 配置开关
+
+| 开关 | 位置 | 作用 |
+|------|------|------|
+| `autoDreamEnabled` | `settings.json` | `true`/`false` 显式开关 |
+| `autoMemoryEnabled` | `settings.json` | 总开关，关闭后所有记忆功能禁用 |
+| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 环境变量 | `1`/`true` 关闭所有记忆功能 |
+| `tengu_onyx_plover` | GrowthBook | 官方远程配置，控制 `enabled`/`minHours`/`minSessions` |
+
+默认值（无 GrowthBook 连接时）：
+
+```typescript
+minHours: 24      // 距上次整理至少 24 小时
+minSessions: 5    // 至少有 5 个新会话
+```
+
+## 整理流程（4 阶段）
+
+Dream agent 执行的提示词包含 4 个阶段：
+
+### Phase 1 — 定位（Orient）
+
+- `ls` 记忆目录，查看现有文件
+- 读取 `MEMORY.md` 索引
+- 浏览现有主题文件，避免重复创建
+
+### Phase 2 — 采集信号（Gather）
+
+按优先级收集新信息：
+
+1. **日志文件**（`logs/YYYY/MM/YYYY-MM-DD.md`，KAIROS 模式下的追加式日志）
+2. **过时记忆** — 与当前代码库状态矛盾的事实
+3. **会话记录** — 窄关键词 grep JSONL 文件（不全文读取）
+
+### Phase 3 — 整合（Consolidate）
+
+- 合并新信号到现有主题文件，而非创建近似重复
+- 将相对日期（"昨天"、"上周"）转为绝对日期
+- 删除被推翻的事实
+
+### Phase 4 — 修剪与索引（Prune）
+
+- `MEMORY.md` 保持在 200 行以内、25KB 以内
+- 每条索引项一行，不超过 150 字符
+- 移除过时/错误/被取代的指针
+
+## 记忆类型
+
+记忆系统使用 4 种类型（`src/memdir/memoryTypes.ts`）：
+
+| 类型 | 用途 | 示例 |
+|------|------|------|
+| `user` | 用户角色、偏好、知识 | 用户是高级后端工程师，偏好中文交流 |
+| `feedback` | 工作方式指导 | 不要 mock 数据库测试；代码审查用 bundled PR |
+| `project` | 项目上下文（非代码可推导的） | 合并冻结从 3 月 5 日开始；认证重写是合规需求 |
+| `reference` | 外部系统指针 | Linear INGEST 项目跟踪 pipeline bugs |
+
+**不保存的内容**：代码模式、架构、文件路径（可从代码推导）；Git 历史（`git log` 权威）；调试方案（代码中已有）。
+
+## 锁文件机制
+
+`.consolidate-lock` 文件位于记忆目录内：
+
+- **文件内容**：持有者 PID
+- **mtime**：即 `lastConsolidatedAt` 时间戳
+- **过期**：1 小时（防 PID 复用）
+- **竞态处理**：双进程同时写入时，后读验证 PID，失败者退出
+- **回滚**：forked agent 失败或被用户终止时，mtime 回退到获取前的值
+
+## 使用场景
+
+### 场景 1：日常开发中的自动整理
+
+开发者连续多天使用 Claude Code 处理不同任务。Auto Dream 在积累 5+ 个会话且距上次整理 24 小时后自动触发，整合分散在多次会话中的用户偏好和项目决策。
+
+### 场景 2：手动整理记忆
+
+用户发现 Claude 重复犯相同错误或遗忘之前的决策。输入 `/dream` 立即触发整理，无需等待自动触发周期。
+
+### 场景 3：新会话快速上下文
+
+新会话启动时，`MEMORY.md` 被加载到上下文中。经过 Dream 整理的记忆文件结构清晰、信息准确，让 Claude 快速了解用户和项目。
+
+### 场景 4：KAIROS 模式下的日志蒸馏
+
+KAIROS（长驻助手模式）中，agent 以追加方式写入日期日志文件。Dream 负责将这些日志蒸馏为主题文件和 `MEMORY.md` 索引。
+
+## 与其他系统的关系
+
+```
+┌─────────────┐     ┌──────────────┐     ┌───────────────┐
+│ 会话交互     │────▶│ 记忆写入      │────▶│ MEMORY.md     │
+│ (主 agent)  │     │ (即时保存)    │     │ + 主题文件     │
+└─────────────┘     └──────────────┘     └───────┬───────┘
+                                               │
+       ┌───────────────────────────────────────┘
+       ▼
+┌──────────────┐     ┌──────────────┐
+│ Auto Dream   │────▶│ 整理/修剪    │
+│ (后台触发)   │     │ 去重/纠错    │
+└──────────────┘     └──────────────┘
+       ▲
+┌──────────────┐
+│ /dream 命令  │
+│ (手动触发)   │
+└──────────────┘
+```
+
+- **extractMemories**（`src/services/extractMemories/`）：每轮次结束时从对话中提取新记忆并写入。Dream 不负责提取，只负责整理。
+- **CLAUDE.md**：项目级指令文件，加载到上下文中但不属于记忆系统。
+- **Team Memory**（`TEAMMEM` feature）：团队共享记忆目录，与个人记忆使用相同的 Dream 机制。

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

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

docs/features/proactive.md

@@ -1,109 +0,0 @@
-# PROACTIVE — 主动模式
-
-> Feature Flag: `FEATURE_PROACTIVE=1`（与 `FEATURE_KAIROS=1` 共享功能）
-> 实现状态：核心模块全部 Stub，布线完整
-> 引用数：37
-
-## 一、功能概述
-
-PROACTIVE 实现 Tick 驱动的自主代理。CLI 在用户不输入时也能持续工作：定时唤醒执行任务，配合 SleepTool 控制节奏。适用于长时间运行的后台任务（等待 CI、监控文件变化、定时检查等）。
-
-### 与 KAIROS 的关系
-
-所有代码检查都是 `feature('PROACTIVE') || feature('KAIROS')`，即：
-- 单独开 `FEATURE_PROACTIVE=1` → 获得 proactive 能力
-- 单独开 `FEATURE_KAIROS=1` → 自动获得 proactive 能力
-- 两者都开 → 相同效果（不重复）
-
-## 二、实现架构
-
-### 2.1 模块状态
-
-| 模块 | 文件 | 状态 | 说明 |
-|------|------|------|------|
-| 核心逻辑 | `src/proactive/index.ts` | **Stub** | `activateProactive()`、`deactivateProactive()`、`isProactiveActive() => false` |
-| SleepTool 提示 | `src/tools/SleepTool/prompt.ts` | **完整** | 工具提示定义（工具名：`Sleep`） |
-| 命令注册 | `src/commands.ts:62-65` | **布线** | 动态加载 `./commands/proactive.js` |
-| 工具注册 | `src/tools.ts:26-28` | **布线** | SleepTool 动态加载 |
-| REPL 集成 | `src/screens/REPL.tsx` | **布线** | tick 驱动逻辑、占位符、页脚 UI |
-| 系统提示 | `src/constants/prompts.ts:860-914` | **完整** | 自主工作行为指令（~55 行详细 prompt） |
-| 会话存储 | `src/utils/sessionStorage.ts:4892-4912` | **布线** | tick 消息注入对话流 |
-
-### 2.2 系统提示内容
-
-`getProactiveSection()` 注入的自主工作指令包含：
-
-| 章节 | 内容 |
-|------|------|
-| Tick 驱动 | `<tick_tag>` prompt 保持存活，包含用户本地时间 |
-| 节奏控制 | SleepTool 控制等待间隔，prompt cache 5 分钟过期 |
-| 空操作规则 | 无事可做时**必须**调用 Sleep，禁止输出 "still waiting" |
-| 首次唤醒 | 简短问候，等待方向（不主动探索） |
-| 后续唤醒 | 寻找有用工作：调查、验证、检查（不 spam 用户） |
-| 偏向行动 | 读文件、搜索代码、commit — 不需询问 |
-| 终端焦点 | `terminalFocus` 字段调节自主程度 |
-
-### 2.3 数据流
-
-```
-activateProactive() [需要实现]
-      │
-      ▼
-Tick 调度器启动
-      │
-      ├── 定时生成 <tick_tag> 消息
-      │   ├── 包含用户当前本地时间
-      │   └── 注入到对话流（sessionStorage）
-      │
-      ▼
-模型处理 tick
-      │
-      ├── 有事可做 → 使用工具执行 → 可能再次 Sleep
-      └── 无事可做 → 必须调用 SleepTool
-      │
-      ▼
-SleepTool 等待 [需要实现]
-      │
-      ▼
-下一个 tick 到达
-```
-
-## 三、需要补全的内容
-
-| 优先级 | 模块 | 工作量 | 说明 |
-|--------|------|--------|------|
-| 1 | `src/proactive/index.ts` | 中 | Tick 调度器、activate/deactivate 状态机、pause/resume |
-| 2 | `src/tools/SleepTool/SleepTool.ts` | 小 | 工具执行（等待指定时间后触发 tick） |
-| 3 | `src/commands/proactive.js` | 小 | `/proactive` 斜杠命令处理器 |
-| 4 | `src/hooks/useProactive.ts` | 中 | React hook（REPL 引用但不存在） |
-
-## 四、关键设计决策
-
-1. **Tick 驱动**：模型通过 SleepTool 自行控制唤醒频率，不是外部事件推送
-2. **空操作必须 Sleep**：防止 "still waiting" 类空消息浪费 turn 和 token
-3. **Prompt cache 考量**：SleepTool 提示中提到 cache 5 分钟过期，建议平衡等待时间
-4. **Terminal Focus 感知**：模型根据用户是否在看终端调整自主程度
-
-## 五、使用方式
-
-```bash
-# 单独启用 proactive
-FEATURE_PROACTIVE=1 bun run dev
-
-# 通过 KAIROS 间接启用
-FEATURE_KAIROS=1 bun run dev
-
-# 组合使用
-FEATURE_PROACTIVE=1 FEATURE_KAIROS=1 FEATURE_KAIROS_BRIEF=1 bun run dev
-```
-
-## 六、文件索引
-
-| 文件 | 职责 |
-|------|------|
-| `src/proactive/index.ts` | 核心逻辑（stub） |
-| `src/tools/SleepTool/prompt.ts` | SleepTool 工具提示 |
-| `src/constants/prompts.ts:860-914` | 自主工作系统提示 |
-| `src/screens/REPL.tsx` | REPL tick 集成 |
-| `src/utils/sessionStorage.ts:4892-4912` | Tick 消息注入 |
-| `src/components/PromptInput/PromptInputFooterLeftSide.tsx` | 页脚 UI 状态 |

docs/features/teammem.md

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

docs/features/tier3-stubs.md

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

docs/features/token-budget.md

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

docs/features/tools/langfuse-monitoring.md

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

docs/features/tree-sitter-bash.md

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

docs/features/ultraplan.md

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

docs/features/voice-mode.md

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

docs/features/web-browser-tool.md

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

docs/features/web-search-tool.md

@@ -1,186 +0,0 @@
-# WEB_SEARCH_TOOL — 网页搜索工具
-
-> 实现状态：适配器架构完成，Bing 适配器为当前默认后端
-> 引用数：核心工具，无 feature flag 门控（始终启用）
-
-## 一、功能概述
-
-WebSearchTool 让模型可以搜索互联网获取最新信息。原始实现仅支持 Anthropic API 服务端搜索（`web_search_20250305` server tool），在第三方代理端点下不可用。现已重构为适配器架构，新增 Bing 搜索页面解析作为 fallback，确保任何 API 端点都能使用搜索功能。
-
-## 二、实现架构
-
-### 2.1 适配器模式
-
-```
-WebSearchTool.call()
-       │
-       ▼
-  createAdapter()  ← 适配器工厂
-       │
-       ├── ApiSearchAdapter  — Anthropic 官方 API 服务端搜索
-       │     └── 使用 web_search_20250305 server tool
-       │         通过 queryModelWithStreaming 二次调用 API
-       │
-       └── BingSearchAdapter — Bing HTML 抓取 + 正则提取（当前默认）
-             └── 直接抓取 Bing 搜索页 HTML
-                 正则提取 b_algo 块中的标题/URL/摘要
-```
-
-### 2.2 模块结构
-
-| 模块 | 文件 | 说明 |
-|------|------|------|
-| 工具入口 | `src/tools/WebSearchTool/WebSearchTool.ts` | `buildTool()` 定义：schema、权限、执行、输出格式化 |
-| 工具 prompt | `src/tools/WebSearchTool/prompt.ts` | 搜索工具的系统提示词 |
-| UI 渲染 | `src/tools/WebSearchTool/UI.tsx` | 搜索结果的终端渲染组件 |
-| 适配器接口 | `src/tools/WebSearchTool/adapters/types.ts` | `WebSearchAdapter` 接口、`SearchResult`/`SearchOptions`/`SearchProgress` 类型 |
-| 适配器工厂 | `src/tools/WebSearchTool/adapters/index.ts` | `createAdapter()` 工厂函数，选择后端 |
-| API 适配器 | `src/tools/WebSearchTool/adapters/apiAdapter.ts` | 封装原有 `queryModelWithStreaming` 逻辑，使用 server tool |
-| Bing 适配器 | `src/tools/WebSearchTool/adapters/bingAdapter.ts` | Bing HTML 抓取 + 正则解析 |
-| 单元测试 | `src/tools/WebSearchTool/__tests__/bingAdapter.test.ts` | 32 个测试用例 |
-| 集成测试 | `src/tools/WebSearchTool/__tests__/bingAdapter.integration.ts` | 真实网络请求验证 |
-
-### 2.3 数据流
-
-```
-模型调用 WebSearchTool(query, allowed_domains, blocked_domains)
-       │
-       ▼
-  validateInput() — 校验 query 非空、allowed/block 不共存
-       │
-       ▼
-  createAdapter() → BingSearchAdapter（当前硬编码）
-       │
-       ▼
-  adapter.search(query, { allowedDomains, blockedDomains, signal, onProgress })
-       │
-       ├── onProgress({ type: 'query_update', query })
-       │
-       ├── axios.get(bing.com/search?q=...&setmkt=en-US)
-       │     └── 13 个 Edge 浏览器请求头
-       │
-       ├── extractBingResults(html) — 正则提取 <li class="b_algo"> 块
-       │     ├── resolveBingUrl() — 解码 base64 重定向 URL
-       │     ├── extractSnippet() — 三级降级摘要提取
-       │     └── decodeHtmlEntities() — he.decode
-       │
-       ├── 客户端域名过滤 (allowedDomains / blockedDomains)
-       │
-       ├── onProgress({ type: 'search_results_received', resultCount })
-       │
-       ▼
-  格式化为 markdown 链接列表返回给模型
-```
-
-## 三、Bing 适配器技术细节
-
-### 3.1 反爬绕过
-
-使用 13 个 Edge 浏览器请求头（含 `Sec-Ch-Ua`、`Sec-Fetch-*` 等），避免 Bing 返回 JS 渲染的空页面：
-
-```typescript
-const BROWSER_HEADERS = {
-  'User-Agent': '...Chrome/131.0.0.0 Safari/537.36 Edg/131.0.0.0',
-  'Sec-Ch-Ua': '"Microsoft Edge";v="131", "Chromium";v="131", ...',
-  'Sec-Fetch-Dest': 'document',
-  'Sec-Fetch-Mode': 'navigate',
-  'Sec-Fetch-Site': 'none',
-  'Sec-Fetch-User': '?1',
-  // ... 共 13 个标头
-}
-```
-
-`setmkt=en-US` 参数强制美式英语市场，避免 IP 地理定位导致区域化结果。
-
-### 3.2 URL 解码（`resolveBingUrl()`）
-
-Bing 返回的重定向 URL 格式：`bing.com/ck/a?...&u=a1aHR0cHM6Ly9...`
-
-- `u` 参数前 2 字符为协议前缀：`a1` = https，`a0` = http
-- 剩余部分为 base64url 编码的真实 URL
-- Bing 内部链接和相对路径被过滤返回 `undefined`
-
-### 3.3 摘要提取（`extractSnippet()`）
-
-三级降级策略：
-
-1. `<p class="b_lineclamp...">` — Bing 的搜索摘要段落
-2. `<div class="b_caption">` 内的 `<p>` — 备选摘要位置
-3. `<div class="b_caption">` 直接文本 — 最终 fallback
-
-### 3.4 域名过滤
-
-客户端侧实现，支持子域名匹配：
-- `allowedDomains`：白名单，结果域名必须匹配列表中的某项（含子域名）
-- `blockedDomains`：黑名单，匹配的结果被过滤
-- 两者不可同时使用（`validateInput` 校验）
-
-## 四、适配器选择逻辑
-
-当前 `createAdapter()` 硬编码返回 `BingSearchAdapter`，原逻辑已注释保留：
-
-```typescript
-export function createAdapter(): WebSearchAdapter {
-  return new BingSearchAdapter()
-  // 注释保留的选择逻辑：
-  // 1. WEB_SEARCH_ADAPTER 环境变量强制指定 api|bing
-  // 2. isFirstPartyAnthropicBaseUrl() → API 适配器
-  // 3. 第三方端点 → Bing 适配器
-}
-```
-
-恢复自动选择：取消 `index.ts` 中的注释即可。
-
-## 五、接口定义
-
-### WebSearchAdapter
-
-```typescript
-interface WebSearchAdapter {
-  search(query: string, options: SearchOptions): Promise<SearchResult[]>
-}
-
-interface SearchResult {
-  title: string
-  url: string
-  snippet?: string
-}
-
-interface SearchOptions {
-  allowedDomains?: string[]
-  blockedDomains?: string[]
-  signal?: AbortSignal
-  onProgress?: (progress: SearchProgress) => void
-}
-
-interface SearchProgress {
-  type: 'query_update' | 'search_results_received'
-  query?: string
-  resultCount?: number
-}
-```
-
-### 工具 Input Schema
-
-```typescript
-{
-  query: string              // 搜索关键词，最少 2 字符
-  allowed_domains?: string[] // 域名白名单
-  blocked_domains?: string[] // 域名黑名单
-}
-```
-
-## 六、文件索引
-
-| 文件 | 职责 |
-|------|------|
-| `src/tools/WebSearchTool/WebSearchTool.ts` | 工具定义入口 |
-| `src/tools/WebSearchTool/prompt.ts` | 搜索工具 prompt |
-| `src/tools/WebSearchTool/UI.tsx` | 终端 UI 渲染 |
-| `src/tools/WebSearchTool/adapters/types.ts` | 适配器接口 |
-| `src/tools/WebSearchTool/adapters/index.ts` | 适配器工厂 |
-| `src/tools/WebSearchTool/adapters/apiAdapter.ts` | API 服务端搜索适配器 |
-| `src/tools/WebSearchTool/adapters/bingAdapter.ts` | Bing HTML 解析适配器 |
-| `src/tools/WebSearchTool/__tests__/bingAdapter.test.ts` | 单元测试 (32 cases) |
-| `src/tools/WebSearchTool/__tests__/bingAdapter.integration.ts` | 集成测试 |
-| `src/tools.ts` | 工具注册 |

docs/features/workflow-scripts.md

@@ -1,105 +0,0 @@
-# WORKFLOW_SCRIPTS — 工作流自动化
-
-> Feature Flag: `FEATURE_WORKFLOW_SCRIPTS=1`
-> 实现状态：全部 Stub（7 个文件），布线完整
-> 引用数：10
-
-## 一、功能概述
-
-WORKFLOW_SCRIPTS 实现基于文件的多步自动化工作流。用户可以定义 YAML/JSON 格式的工作流描述文件，系统将其解析为可执行的多 agent 步骤序列。提供 `/workflows` 命令管理和触发工作流。
-
-## 二、实现架构
-
-### 2.1 模块状态
-
-| 模块 | 文件 | 状态 |
-|------|------|------|
-| WorkflowTool | `src/tools/WorkflowTool/WorkflowTool.ts` | **Stub** — 空对象 |
-| Workflow 权限 | `src/tools/WorkflowTool/WorkflowPermissionRequest.ts` | **Stub** — 返回 null |
-| 常量 | `src/tools/WorkflowTool/constants.ts` | **Stub** — 空工具名 |
-| 命令创建 | `src/tools/WorkflowTool/createWorkflowCommand.ts` | **Stub** — 空操作 |
-| 捆绑工作流 | `src/tools/WorkflowTool/bundled/` | **缺失** — 目录不存在 |
-| 本地工作流任务 | `src/tasks/LocalWorkflowTask/LocalWorkflowTask.ts` | **Stub** — 类型 + 空操作 |
-| UI 任务组件 | `src/components/tasks/src/tasks/LocalWorkflowTask/` | **Stub** — 空导出 |
-| 详情对话框 | `src/components/tasks/WorkflowDetailDialog.ts` | **Stub** — 返回 null |
-| 任务注册 | `src/tasks.ts` | **布线** — 动态加载 |
-| 工具注册 | `src/tools.ts` | **布线** — 包含 bundled 工作流初始化 |
-| 命令注册 | `src/commands.ts` | **布线** — `/workflows` 命令 |
-
-### 2.2 预期数据流
-
-```
-用户定义工作流（YAML/JSON 文件）
-         │
-         ▼
-/workflows 命令发现工作流文件
-         │
-         ▼
-createWorkflowCommand() 解析为 Command 对象 [需要实现]
-         │
-         ▼
-WorkflowTool 执行工作流 [需要实现]
-         │
-         ├── 步骤 1: Agent({ task: "..." })
-         ├── 步骤 2: Agent({ task: "..." })
-         └── 步骤 N: Agent({ task: "..." })
-         │
-         ▼
-LocalWorkflowTask 协调步骤执行 [需要实现]
-         │
-         ▼
-WorkflowDetailDialog 显示进度 [需要实现]
-```
-
-### 2.3 预期工作流 DSL
-
-```
-# workflow.yaml（预期格式，需要设计）
-name: "代码审查工作流"
-steps:
-  - name: "静态分析"
-    agent: { type: "general-purpose", prompt: "运行 lint 和类型检查" }
-  - name: "测试"
-    agent: { type: "general-purpose", prompt: "运行测试套件" }
-  - name: "综合报告"
-    agent: { type: "general-purpose", prompt: "综合分析结果写报告" }
-```
-
-## 三、需要补全的内容
-
-| 优先级 | 模块 | 工作量 | 说明 |
-|--------|------|--------|------|
-| 1 | `WorkflowTool.ts` | 大 | Schema 定义 + 多步执行引擎 |
-| 2 | `bundled/index.js` | 中 | 内置工作流定义（initBundledWorkflows） |
-| 3 | `createWorkflowCommand.ts` | 中 | 从文件解析创建命令对象 |
-| 4 | `LocalWorkflowTask.ts` | 大 | 步骤协调、kill/skip/retry |
-| 5 | `WorkflowDetailDialog.ts` | 中 | 进度详情 UI |
-| 6 | `WorkflowPermissionRequest.ts` | 小 | 权限对话框 |
-| 7 | `constants.ts` | 小 | 工具名常量 |
-
-## 四、关键设计决策
-
-1. **基于文件的 DSL**：工作流定义为文件（YAML/JSON），版本控制友好
-2. **多 Agent 步骤**：每个步骤是独立的 agent 任务，支持并行/串行
-3. **内置工作流**：`bundled/` 目录提供开箱即用的常用工作流
-4. **/workflows 命令**：统一的发现和触发入口
-
-## 五、使用方式
-
-```bash
-# 启用 feature（需要补全后才能真正使用）
-FEATURE_WORKFLOW_SCRIPTS=1 bun run dev
-```
-
-## 六、文件索引
-
-| 文件 | 职责 |
-|------|------|
-| `src/tools/WorkflowTool/WorkflowTool.ts` | 工具定义（stub） |
-| `src/tools/WorkflowTool/WorkflowPermissionRequest.ts` | 权限对话框（stub） |
-| `src/tools/WorkflowTool/constants.ts` | 常量（stub） |
-| `src/tools/WorkflowTool/createWorkflowCommand.ts` | 命令创建（stub） |
-| `src/tasks/LocalWorkflowTask/LocalWorkflowTask.ts` | 任务协调（stub） |
-| `src/components/tasks/WorkflowDetailDialog.ts` | 详情对话框（stub） |
-| `src/tools.ts:127-132` | 工具注册 |
-| `src/commands.ts:86-89` | 命令注册 |

docs/getting-started/installation.mdx

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

docs/getting-started/model-providers.mdx

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

docs/getting-started/quickstart.mdx

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

docs/internals/ant-only-world.mdx

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

docs/internals/feature-flags.mdx

@@ -1,115 +0,0 @@
----
-title: "88 个 Feature Flags - 构建时特性门控全解"
-description: "深入剖析 Claude Code 的 88+ 个构建时 feature flags：bun:bundle 编译时门控机制，揭示被编译器删除的隐藏功能模块。"
-keywords: ["feature flags", "特性标志", "构建时门控", "bun:bundle", "条件编译"]
----
-
-{/* 本章目标：完整梳理构建时 feature flag 系统的机制和所有 flag 的分类 */}
-
-## feature() 是什么
-
-Claude Code 使用 Bun 打包器的 `bun:bundle` 模块提供编译时特性门控：
-
-```typescript
-// 源码中的用法（src/tools.ts 等）
-import { feature } from 'bun:bundle'
-
-const SleepTool = feature('PROACTIVE') || feature('KAIROS')
-  ? require('./tools/SleepTool/SleepTool.js').SleepTool
-  : null
-```
-
-在 Anthropic 的内部构建中，`feature()` 在打包时被求值——返回 `true` 的代码会被保留，返回 `false` 的代码会被 **Dead Code Elimination (DCE)** 彻底移除。
-
-在我们的反编译版本中，这个函数被兜底为：
-
-```typescript
-// src/entrypoints/cli.tsx 第 3 行
-const feature = (_name: string) => false;
-```
-
-这意味着所有 88+ 个 feature flag 后的代码**在运行时永远不会执行**，但代码本身完整保留，可以阅读和分析。
-
-## Flags 分类全景
-
-<CardGroup cols={2}>
-  <Card title="Agent / 自动化" icon="robot">
-    **15 个 flags** — 控制 AI 的自主能力边界
-
-    `KAIROS` · `KAIROS_BRIEF` · `KAIROS_CHANNELS` · `KAIROS_DREAM` · `KAIROS_GITHUB_WEBHOOKS` · `KAIROS_PUSH_NOTIFICATION` · `PROACTIVE` · `COORDINATOR_MODE` · `FORK_SUBAGENT` · `AGENT_MEMORY_SNAPSHOT` · `AGENT_TRIGGERS` · `AGENT_TRIGGERS_REMOTE` · `VERIFICATION_AGENT` · `BUILTIN_EXPLORE_PLAN_AGENTS` · `MONITOR_TOOL`
-  </Card>
-
-  <Card title="基础设施" icon="server">
-    **10 个 flags** — 控制运行环境和连接方式
-
-    `DAEMON` · `BG_SESSIONS` · `BRIDGE_MODE` · `CCR_AUTO_CONNECT` · `CCR_MIRROR` · `CCR_REMOTE_SETUP` · `DIRECT_CONNECT` · `SSH_REMOTE` · `SELF_HOSTED_RUNNER` · `BYOC_ENVIRONMENT_RUNNER`
-  </Card>
-
-  <Card title="安全 / 分类" icon="shield-halved">
-    **6 个 flags** — 增强权限判断的智能性
-
-    `TRANSCRIPT_CLASSIFIER` · `BASH_CLASSIFIER` · `TREE_SITTER_BASH` · `TREE_SITTER_BASH_SHADOW` · `NATIVE_CLIENT_ATTESTATION` · `ABLATION_BASELINE`
-  </Card>
-
-  <Card title="工具 / 能力" icon="toolbox">
-    **10 个 flags** — 新增的 AI 能力
-
-    `WEB_BROWSER_TOOL` · `TERMINAL_PANEL` · `CONTEXT_COLLAPSE` · `HISTORY_SNIP` · `OVERFLOW_TEST_TOOL` · `WORKFLOW_SCRIPTS` · `VOICE_MODE` · `MCP_RICH_OUTPUT` · `MCP_SKILLS` · `UDS_INBOX`
-  </Card>
-
-  <Card title="UI / 体验" icon="palette">
-    **8 个 flags** — 界面和交互改进
-
-    `MESSAGE_ACTIONS` · `QUICK_SEARCH` · `HISTORY_PICKER` · `AUTO_THEME` · `STREAMLINED_OUTPUT` · `COMPACTION_REMINDERS` · `TEMPLATES` · `BUDDY`
-  </Card>
-
-  <Card title="平台 / 实验" icon="flask-vial">
-    **10+ 个 flags** — 实验性和平台级功能
-
-    `DUMP_SYSTEM_PROMPT` · `UPLOAD_USER_SETTINGS` · `DOWNLOAD_USER_SETTINGS` · `EXPERIMENTAL_SKILL_SEARCH` · `ULTRAPLAN` · `ULTRATHINK` · `TORCH` · `LODESTONE` · `PERFETTO_TRACING` · `SLOW_OPERATION_LOGGING` · `HARD_FAIL` · `ALLOW_TEST_VERSIONS`
-  </Card>
-</CardGroup>
-
-## 代码中的典型模式
-
-Feature flags 在代码中主要有三种使用模式：
-
-### 模式一：条件加载工具
-
-```typescript
-// src/tools.ts — 最常见的模式
-const MonitorTool = feature('MONITOR_TOOL')
-  ? require('./tools/MonitorTool/MonitorTool.js').MonitorTool
-  : null
-```
-
-当 flag 为 `false` 时，`require()` 调用被 DCE 移除，工具不会出现在可用工具列表中。
-
-### 模式二：条件注册命令
-
-```typescript
-// src/commands.ts — 注册斜杠命令
-if (feature('VOICE_MODE')) {
-  commands.push({ name: 'voice', description: '...' })
-}
-```
-
-### 模式三：条件启用 API 特性
-
-```typescript
-// src/constants/betas.ts — 控制发送给 API 的 beta header
-export const AFK_MODE_BETA_HEADER = feature('TRANSCRIPT_CLASSIFIER')
-  ? 'afk-mode-2026-01-31'
-  : ''
-```
-
-<Note>
-由于 `feature()` 在构建时求值，被 DCE 移除的代码不会增加最终打包体积。但在反编译版本中，这些代码全部保留——这正是我们能够进行完整分析的原因。
-</Note>
-
-## 有趣的发现
-
-- **KAIROS 家族**最庞大——6 个相关 flag 控制从核心功能到推送通知的方方面面
-- **ABLATION_BASELINE** 是用于"科学对照实验"的——它会关闭 thinking、compaction、auto-memory 等高级功能，测量裸 API 调用的基线性能
-- **BUDDY** 是一个 AI 吉祥物/精灵系统——在 `src/buddy/` 目录下有完整实现
-- **ULTRAPLAN** 和 **ULTRATHINK** 暗示着比当前 extended thinking 更高级的推理模式

docs/internals/growthbook-ab-testing.mdx

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

docs/internals/hidden-features.mdx

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

docs/internals/three-tier-gating.mdx

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

docs/introduction/architecture-overview.mdx

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

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

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

docs/introduction/why-this-whitepaper.mdx

@@ -1,121 +0,0 @@
----
-title: "为什么写这份白皮书 - Claude Code 逆向工程分析"
-description: "对 Anthropic 官方 Claude Code CLI 的逆向工程分析白皮书。通过反编译 TypeScript 单文件 bundle，深入解析运行时行为与源码结构。"
-keywords: ["Claude Code", "逆向工程", "白皮书", "反编译", "TypeScript"]
----
-
-## 这份白皮书是什么
-
-这是对 Anthropic 官方发布的 **Claude Code CLI** 的**逆向工程分析**。
-
-源码经过反编译处理（TypeScript 单文件 bundle 逆向），保留了核心功能模块，但包含大量 `unknown`/`never`/`{}` 类型错误——这些不影响 Bun 运行时执行，但意味着我们的分析基于运行时行为 + 残留源码结构，而非原始源码。
-
-**这不是：**
-- 官方文档或使用教程
-- API 参考手册
-- Claude Code 的功能推销
-
-**这是：**
-- 一个生产级 agentic system 的架构解构
-- 每个设计决策背后的"为什么"
-- 可复用的工程模式：agentic loop、工具抽象、上下文工程、安全纵深防御
-
-## 逆向过程中最精妙的设计决策
-
-### 1. Agentic Loop 的自愈能力
-
-`src/query.ts` 实现的核心循环不是简单的"发请求→收响应"。它是一个**自愈的状态机**：
-
-- API 返回错误（限流、token 超限）→ 自动重试/降级
-- 工具执行超时 → 后台化 + 通知机制
-- 对话过长触发 compaction → 压缩历史后无缝继续
-- 用户中断 → 生成 `UserInterruptionMessage` 让 AI 理解发生了什么
-
-这不是"if-else 堆叠"，而是让 AI 自己根据上下文决定下一步——即使发生了意外。
-
-### 2. 上下文工程的分层策略
-
-AI 没有真正的"记忆"，Claude Code 通过精心分层营造了这个幻觉：
-
-| 层 | 机制 | 持久性 |
-|----|------|--------|
-| **System Prompt** | 项目结构、git 状态、CLAUDE.md | 每轮重建 |
-| **对话历史** | 完整的 User/Assistant/Tool 消息 | 会话内 |
-| **Compaction** | 自动压缩过长对话为摘要 | 压缩后替代原始消息 |
-| **Memory 文件** | 跨会话持久化的笔记 | 永久（用户可控） |
-| **File History** | 文件修改时间戳快照 | 会话内 |
-
-`src/context.ts` 组装 System Prompt 时的策略是：**不变内容在前、变化内容在后**——这利用了 API 的缓存机制，前缀不变时可以复用缓存 token。
-
-### 3. 工具系统的权限双轨制
-
-`src/tools/BashTool/shouldUseSandbox.ts` 展示了一个精巧的双重安全模型：
-
-- **应用层**：权限规则决定"能不能执行"（白名单/黑名单/用户确认）
-- **OS 层**：沙箱决定"执行时能做什么"（文件系统/网络/进程隔离）
-
-两层的信任假设不同：应用层信任用户配置，OS 层不信任任何东西。即使 AI 绕过了应用层权限（理论上不可能，但纵深防御），OS 层沙箱仍然限制实际危害。
-
-### 4. Feature Flag 的全局开关
-
-`src/entrypoints/cli.tsx` 中一行代码决定了整个系统的行为：
-
-```typescript
-const feature = (_name: string) => false;
-```
-
-所有 `feature('FLAG_NAME')` 调用返回 `false`——这意味着 Anthropic 内部的实验功能（COORDINATOR_MODE、KAIROS、PROACTIVE 等）全部禁用。在官方构建中，这些 flag 通过 Bun 的 `bun:bundle` 在编译时注入，不同用户群体看到不同功能。
-
-这是一个**渐进式发布架构**：同一个代码库，通过 feature flag 控制功能可见性，而不需要维护多个分支。
-
-### 5. Compaction 的分档策略
-
-`src/services/compact/` 实现了三种压缩策略：
-
-- **Micro-compact**：单次工具输出过长时，截断结果
-- **Auto-compact**：对话 token 接近上限时，自动压缩历史
-- **Reactive-compact**：API 返回 token 超限错误时，紧急压缩后重试
-
-这不是简单的"砍掉旧消息"——而是用 AI 自身来总结之前的对话，保留语义信息。压缩后插入一条 `TombstoneMessage` 标记边界。
-
-## 阅读路线图
-
-推荐的阅读顺序，每章解决一个核心问题：
-
-```
-什么是 Claude Code (你在读的)          ← 建立直觉
-    │
-    ├── 架构全景                       ← 五层架构 + 数据流
-    │
-    ├── 安全体系                       ← 信任与控制
-    │   ├── 权限模型                   ← 应用层安全
-    │   ├── 沙箱机制                   ← OS 层安全
-    │   └── Plan Mode                  ← 用户主导模式
-    │
-    ├── 对话引擎                       ← AI 如何思考
-    │   ├── Agentic Loop               ← 核心循环
-    │   ├── 流式响应                   ← 实时通信
-    │   └── 多轮对话                   ← 上下文管理
-    │
-    ├── 上下文工程                     ← 记忆与预算
-    │   ├── System Prompt              ← 上下文组装
-    │   ├── Token 预算                 ← 预算管理
-    │   └── 项目记忆                   ← 跨会话持久化
-    │
-    ├── 工具系统                       ← AI 的双手
-    │   ├── 工具概览                   ← 统一接口
-    │   ├── Shell 执行                 ← Bash 工具
-    │   └── 搜索与导航                 ← Glob/Grep
-    │
-    └── Agent 与扩展                   ← 能力扩展
-        ├── 子 Agent                   ← 并行任务
-        ├── 自定义 Agent               ← 用户定义
-        └── MCP 协议                   ← 外部工具接入
-```
-
-## 适合谁读
-
-- **AI Agent 开发者**：想理解生产级 agentic system 的架构模式
-- **安全工程师**：对 AI 操作真实环境时的信任模型感兴趣
-- **工具构建者**：正在构建类似的 coding assistant 或 CLI 工具
-- **好奇心驱动的开发者**：想知道"AI 编程助手到底怎么工作的"

docs/lsp-integration.md

@@ -1,264 +0,0 @@
-# LSP Integration
-
-Claude Code 内置了 Language Server Protocol (LSP) 集成，提供代码智能功能（跳转定义、查找引用、悬停信息、文档符号等）和被动的诊断反馈。
-
-## 快速开始
-
-### 1. 安装 LSP 插件
-
-在 Claude Code REPL 中使用 `/plugin` 命令搜索并安装 LSP 插件：
-
-```
-/plugin
-```
-
-搜索 `lsp`，找到对应语言的插件（如 `typescript-lsp`），选择安装。
-
-安装后运行 `/reload-plugins` 使插件生效。
-
-LSP 插件安装后，后台的 LSP Server Manager 会自动加载并启动对应的语言服务器，无需手动配置。
-
-### 2. 启用 LSP Tool
-
-LSP Tool 需要通过环境变量显式启用，Claude 才能主动发起代码智能查询：
-
-```bash
-ENABLE_LSP_TOOL=1 bun run dev
-```
-
-不启用时，LSP 服务器仍然在后台运行并推送被动的诊断反馈（类型错误等）。
-
-## 自动推荐
-
-除了手动 `/plugin` 搜索安装外，Claude Code 会在编辑文件时自动检测：
-
-1. 监听 `fileHistory.trackedFiles`，发现有新文件被编辑
-2. 扫描已安装的 marketplace，找到声明支持该文件扩展名的 LSP 插件
-3. 检查系统上是否已安装对应的 LSP 二进制（如 `typescript-language-server`）
-4. 满足条件时弹出推荐对话框，可选择安装
-
-```
-┌───── LSP Plugin Recommendation ─────────────┐
-│                                               │
-│  LSP provides code intelligence like          │
-│  go-to-definition and error checking          │
-│                                               │
-│  Plugin: typescript-lsp                       │
-│  Triggered by: .ts files                     │
-│                                               │
-│  Would you like to install this LSP plugin?   │
-│                                               │
-│  > Yes, install typescript-lsp               │
-│    No, not now                                │
-│    Never for typescript-lsp                   │
-│    Disable all LSP recommendations            │
-└───────────────────────────────────────────────┘
-```
-
-- 30 秒不操作自动关闭（算作 "No"）
-- 选 "Never" 不再推荐该插件
-- 选 "Disable" 关闭所有 LSP 推荐
-- 连续忽略 5 次后自动禁用推荐
-
-## 架构概览
-
-```
-┌─────────────────────────────────────────────────────┐
-│                    LSP Tool                         │
-│  src/tools/LSPTool/LSPTool.ts                       │
-│  (Claude 可调用的工具，9 种操作)                       │
-└──────────────────────┬──────────────────────────────┘
-                       │
-┌──────────────────────▼──────────────────────────────┐
-│              LSP Server Manager (Singleton)          │
-│  src/services/lsp/manager.ts                        │
-│  - initializeLspServerManager()                     │
-│  - reinitializeLspServerManager()                   │
-│  - shutdownLspServerManager()                       │
-└──────────────────────┬──────────────────────────────┘
-                       │
-┌──────────────────────▼──────────────────────────────┐
-│           LSP Server Manager (实例)                   │
-│  src/services/lsp/LSPServerManager.ts               │
-│  - 管理多个 LSPServerInstance                        │
-│  - 按文件扩展名路由请求                               │
-│  - 文件同步 (didOpen/didChange/didSave/didClose)     │
-└──────────────────────┬──────────────────────────────┘
-                       │
-         ┌─────────────┼─────────────┐
-         ▼             ▼             ▼
-┌──────────────┐ ┌──────────────┐ ┌──────────────┐
-│ LSPServer    │ │ LSPServer    │ │ LSPServer    │
-│ Instance     │ │ Instance     │ │ Instance     │
-│ (typescript) │ │ (python)     │ │ (rust...)    │
-└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
-       │                │                │
-┌──────▼───────┐ ┌──────▼───────┐ ┌──────▼───────┐
-│ LSPClient    │ │ LSPClient    │ │ LSPClient    │
-│ (JSON-RPC)   │ │ (JSON-RPC)   │ │ (JSON-RPC)   │
-└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
-       │                │                │
-  子进程 (stdio)    子进程 (stdio)    子进程 (stdio)
-```
-
-### 被动诊断反馈
-
-```
-LSP Server ──publishDiagnostics──▶ passiveFeedback.ts
-                                          │
-                                          ▼
-                                   LSPDiagnosticRegistry
-                                   (去重、容量限制)
-                                          │
-                                          ▼
-                                   Attachment System
-                                   (异步注入到对话)
-```
-
-LSP 服务器会异步推送 `textDocument/publishDiagnostics` 通知，经去重和容量限制后作为 attachment 注入到 Claude 的对话上下文中。
-
-## 核心模块
-
-| 文件 | 职责 |
-|------|------|
-| `src/services/lsp/manager.ts` | 全局单例，初始化/重初始化/关闭生命周期管理 |
-| `src/services/lsp/LSPServerManager.ts` | 多服务器管理，按文件扩展名路由，文件同步 |
-| `src/services/lsp/LSPServerInstance.ts` | 单个 LSP 服务器实例生命周期（启动/停止/重启/健康检查） |
-| `src/services/lsp/LSPClient.ts` | JSON-RPC 通信层（基于 `vscode-jsonrpc`），子进程管理 |
-| `src/services/lsp/config.ts` | 从插件加载 LSP 服务器配置 |
-| `src/services/lsp/LSPDiagnosticRegistry.ts` | 诊断信息注册、去重、容量限制 |
-| `src/services/lsp/passiveFeedback.ts` | 注册 `publishDiagnostics` 通知处理器 |
-| `src/tools/LSPTool/LSPTool.ts` | LSP Tool 实现（暴露给 Claude） |
-| `src/tools/LSPTool/schemas.ts` | 输入 schema（9 种操作的 discriminated union） |
-| `src/tools/LSPTool/formatters.ts` | 各操作结果的格式化 |
-| `src/tools/LSPTool/prompt.ts` | Tool 描述文本 |
-| `src/utils/plugins/lspPluginIntegration.ts` | 从插件加载、验证、环境变量解析、作用域管理 |
-
-## LSP Tool 支持的操作
-
-| 操作 | LSP Method | 说明 |
-|------|-----------|------|
-| `goToDefinition` | `textDocument/definition` | 跳转到符号定义 |
-| `findReferences` | `textDocument/references` | 查找所有引用 |
-| `hover` | `textDocument/hover` | 获取悬停信息（文档、类型） |
-| `documentSymbol` | `textDocument/documentSymbol` | 获取文档内所有符号 |
-| `workspaceSymbol` | `workspace/symbol` | 全工作区符号搜索 |
-| `goToImplementation` | `textDocument/implementation` | 查找接口/抽象方法的实现 |
-| `prepareCallHierarchy` | `textDocument/prepareCallHierarchy` | 获取位置处的调用层级项 |
-| `incomingCalls` | `callHierarchy/incomingCalls` | 查找调用此函数的所有函数 |
-| `outgoingCalls` | `callHierarchy/outgoingCalls` | 查找此函数调用的所有函数 |
-
-所有操作需要 `filePath`、`line`（1-based）和 `character`（1-based）参数。
-
-## 插件开发：LSP 服务器配置
-
-LSP 服务器通过插件提供。插件的 `manifest.json` 中可以声明 LSP 服务器，支持三种格式：
-
-**1. 内联配置（在 manifest 中直接定义）**
-
-```json
-{
-  "lspServers": {
-    "typescript": {
-      "command": "typescript-language-server",
-      "args": ["--stdio"],
-      "extensionToLanguage": {
-        ".ts": "typescript",
-        ".tsx": "typescriptreact"
-      }
-    }
-  }
-}
-```
-
-**2. 引用外部 .lsp.json 文件**
-
-```json
-{
-  "lspServers": "path/to/.lsp.json"
-}
-```
-
-**3. 数组混合格式**
-
-```json
-{
-  "lspServers": [
-    "path/to/.lsp.json",
-    {
-      "another-server": { "command": "...", "extensionToLanguage": { "...": "..." } }
-    }
-  ]
-}
-```
-
-也可以在插件目录下直接放置 `.lsp.json` 文件，无需在 manifest 中声明。
-
-### LSP 服务器配置 Schema
-
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `command` | string | 是 | LSP 服务器可执行命令（不含空格） |
-| `args` | string[] | 否 | 命令行参数 |
-| `extensionToLanguage` | Record<string, string> | 是 | 文件扩展名到语言 ID 的映射（至少一个） |
-| `transport` | `"stdio"` \| `"socket"` | 否 | 通信方式，默认 `stdio` |
-| `env` | Record<string, string> | 否 | 启动服务器时设置的环境变量 |
-| `initializationOptions` | unknown | 否 | 传给服务器的初始化选项 |
-| `settings` | unknown | 否 | 通过 `workspace/didChangeConfiguration` 传递的设置 |
-| `workspaceFolder` | string | 否 | 工作区目录路径 |
-| `startupTimeout` | number | 否 | 启动超时时间（毫秒） |
-| `maxRestarts` | number | 否 | 最大重启次数（默认 3） |
-
-### 环境变量替换
-
-配置中的 `command`、`args`、`env`、`workspaceFolder` 支持：
-
-- `${CLAUDE_PLUGIN_ROOT}` — 插件根目录
-- `${CLAUDE_PLUGIN_DATA}` — 插件数据目录
-- `${user_config.KEY}` — 用户在插件启用时配置的值
-- `${VAR}` — 系统环境变量
-
-## 生命周期管理
-
-### 服务器状态机
-
-```
-stopped → starting → running
-running → stopping → stopped
-any     → error (失败时)
-error   → starting (重试时)
-```
-
-### 崩溃恢复
-
-- LSP 服务器崩溃时状态设为 `error`
-- 下次请求时自动尝试重启（通过 `ensureServerStarted`）
-- 超过 `maxRestarts`（默认 3）次后放弃
-
-### 瞬态错误重试
-
-- `ContentModified` 错误（LSP 错误码 -32801）会自动重试，最多 3 次
-- 使用指数退避：500ms → 1000ms → 2000ms
-- 常见于 rust-analyzer 等仍在索引项目的服务器
-
-### 诊断信息容量限制
-
-- 每个文件最多 10 条诊断
-- 总计最多 30 条诊断
-- 超出部分按严重性排序后截断（Error > Warning > Info > Hint）
-- 跨 turn 去重：已发送过的相同诊断不会重复发送
-- 文件编辑后清除该文件的已发送记录，允许新诊断通过
-
-### 插件刷新
-
-安装/卸载插件后使用 `/reload-plugins`，会调用 `reinitializeLspServerManager()`：
-1. 异步关闭旧服务器实例
-2. 重置状态为 `not-started`
-3. 调用 `initializeLspServerManager()` 重新加载插件配置
-
-## 依赖
-
-- `vscode-jsonrpc` — JSON-RPC 通信（懒加载，仅在实际创建服务器实例时才 require）
-- `vscode-languageserver-protocol` — LSP 协议类型
-- `vscode-languageserver-types` — LSP 类型定义
-- `lru-cache` — 诊断去重缓存

docs/outline-output/README.md

@@ -0,0 +1,69 @@
+# Claude Code（反编译重建版）文档
+
+本目录是基于 [`docs-outline-draft.md`](../../docs-outline-draft.md) 大纲生成的完整文档，分三个视角：
+
+- **[user/](./user/)** — 产品文档（使用者视角）：按"安装 → 配置 → 日常 → 进阶 → 排错"用户旅程组织
+- **[design/](./design/)** — 开发者设计探秘：按"被约束逼出的决策链"组织，每章回答"为什么这么设计"
+- **[cross/](./cross/)** — 交叉主题：两个视角都需要覆盖的横切主题
+
+---
+
+## 第一部分：产品文档（user/）
+
+| # | 章节 | 文件 |
+|---|------|------|
+| 1 | 从零开始 —— 安装、首次启动与环境要求 | [01-installation.md](./user/01-installation.md) |
+| 2 | 让 Claude 听你的 —— 配置 Provider 与模型 | [02-providers.md](./user/02-providers.md) |
+| 3 | 日常对话 —— 交互式 REPL 怎么用 | [03-repl-daily.md](./user/03-repl-daily.md) |
+| 4 | slash 命令速查 —— 按场景找 | [04-slash-commands.md](./user/04-slash-commands.md) |
+| 5 | 扩展 Claude 的能力 —— MCP、插件、Skill | [05-mcp-plugins-skills.md](./user/05-mcp-plugins-skills.md) |
+| 6 | 让 Claude 跑大任务 —— 子代理、Plan、Task | [06-agents-plan-tasks.md](./user/06-agents-plan-tasks.md) |
+| 7 | 让 Claude 长时间干活 —— Daemon、BG、Schedule | [07-daemon-bg-schedule.md](./user/07-daemon-bg-schedule.md) |
+| 8 | 跨机器与团队协作 —— Bridge、RCS、ACP | [08-bridge-rcs-acp.md](./user/08-bridge-rcs-acp.md) |
+| 9 | 省钱、提速、定制 —— 穷鬼模式、Hooks、配置 | [09-budget-hooks-config.md](./user/09-budget-hooks-config.md) |
+| 10 | 可观测性与排错 —— 卡住了怎么办 | [10-observability-troubleshooting.md](./user/10-observability-troubleshooting.md) |
+| 11 | 自动化与 CI 集成 —— 嵌入流水线 | [11-ci-integration.md](./user/11-ci-integration.md) |
+| 12 | 进阶实验性能力与社区生态 | [12-experimental-community.md](./user/12-experimental-community.md) |
+| 13 | 安全 —— 凭证、权限、刷新、共享 | [13-security.md](./user/13-security.md) |
+
+## 第二部分：开发者设计探秘（design/）
+
+| # | 章节 | 文件 |
+|---|------|------|
+| 0 | 序章：被反编译重建的 CLI 处处是"约束的印记" | [00-prologue.md](./design/00-prologue.md) |
+| 1 | Code Splitting 不是优化，是生存需求 | [01-code-splitting.md](./design/01-code-splitting.md) |
+| 2 | 入口 Fast-Path 优先级链 —— --version 零模块加载 | [02-fast-path.md](./design/02-fast-path.md) |
+| 3 | performanceShim —— JSC 内存泄漏的运行时补丁 | [03-performance-shim.md](./design/03-performance-shim.md) |
+| 4 | 核心 Query Loop —— 为什么 query() 是 async generator | [04-query-loop.md](./design/04-query-loop.md) |
+| 5 | Feature Flag 系统的三个硬约束 | [05-feature-flags.md](./design/05-feature-flags.md) |
+| 6 | 工具系统的延迟加载与 CORE_TOOLS 白名单 | [06-tools-deferred.md](./design/06-tools-deferred.md) |
+| 7 | 7-Provider 抽象层的单一调度点 | [07-provider-dispatch.md](./design/07-provider-dispatch.md) |
+| 8 | 流适配器 —— OpenAI/Gemini/Grok 假装是 Anthropic | [08-stream-adapters.md](./design/08-stream-adapters.md) |
+| 9 | Usage 字段映射与模型映射的优先级链 | [09-usage-mapping.md](./design/09-usage-mapping.md) |
+| 10 | 自研 Fork 的 Ink 框架 —— 为什么不是 src/ink/ | [10-ink-framework.md](./design/10-ink-framework.md) |
+| 11 | 三层状态管理 —— bootstrap/state.ts 警告 "DO NOT ADD MORE" | [11-state-management.md](./design/11-state-management.md) |
+| 12 | ACP / Bridge / Daemon —— 三个长驻模式的接线 | [12-acp-bridge-daemon.md](./design/12-acp-bridge-daemon.md) |
+| 13 | CLAUDE.md 四层层级与 @include 指令 | [13-claudemd.md](./design/13-claudemd.md) |
+| 14 | 测试策略 —— 为什么 mock 必须从底层 HTTP 开始 | [14-testing-strategy.md](./design/14-testing-strategy.md) |
+| 15 | biome.json 的 42 条规则关闭 —— 反编译产物的指纹 | [15-biome-config.md](./design/15-biome-config.md) |
+| 16 | 尾声：哪些坑我们没踩 —— 读者可继续挖掘的方向 | [16-epilogue.md](./design/16-epilogue.md) |
+
+## 第三部分：交叉主题（cross/）
+
+| # | 主题 | 文件 |
+|---|------|------|
+| 1 | 排错与错误对照 | [01-troubleshooting.md](./cross/01-troubleshooting.md) |
+| 2 | 性能与内存 | [02-performance-memory.md](./cross/02-performance-memory.md) |
+| 3 | 安全 | [03-security.md](./cross/03-security.md) |
+| 4 | 升级与版本管理 | [04-upgrade-versioning.md](./cross/04-upgrade-versioning.md) |
+| 5 | 与其他工具集成 | [05-tool-integration.md](./cross/05-tool-integration.md) |
+| 6 | 可观测性 | [06-observability.md](./cross/06-observability.md) |
+| 7 | 凭证与认证生命周期 | [07-credentials-auth.md](./cross/07-credentials-auth.md) |
+
+---
+
+## 阅读建议
+
+- **想用工具**：直接看 [user/](./user/)，从 [01-installation.md](./user/01-installation.md) 开始
+- **想理解架构**：从 [design/00-prologue.md](./design/00-prologue.md) 序章开始
+- **遇到问题**：先看 [cross/01-troubleshooting.md](./cross/01-troubleshooting.md) 排错对照表

docs/outline-output/cross/01-troubleshooting.md

@@ -0,0 +1,230 @@
+# 排错与错误对照
+
+> 同一条 429 在使用者眼里是"我流量打太多了吗？"，在开发者眼里是"响应头里那串 `x-ratelimit-*` 该被哪个适配器解析"；同一份 Bedrock 400 在使用者眼里是"为什么 Opus 4.7 调不通"，在开发者眼里是"SDK 0.28.1 那个 `anthropic_beta` 体重植漏洞还要打补丁打多久"。排错天生是双视角主题，所以单独成章。
+
+## 产品视角（写给使用者）
+
+这一节回答两个问题：**当 Claude 报错时第一步该做什么**，以及**看到具体错误码该怎么自救**。读完之后，你不需要去翻源码，就能把九成的常见问题处理掉。
+
+### 第一步永远先跑两条命令
+
+当 Claude 报错、卡住、行为异常时，按下面顺序排查。两条命令分工很明确：
+
+- `claude doctor` —— 一张屏幕显示版本信息（含远端 npm/GCS 上的 stable 与 latest 版本号）、配置文件路径、settings 校验错误、keybindings 警告、MCP 解析警告、沙箱状态、安装锁文件状态。它的源码在 `src/screens/Doctor.tsx`（命令注册在 `src/commands/doctor/doctor.tsx`），相当于一次"全身体检"。
+- `bun run health` —— 跑 `scripts/health-check.ts`，更偏工程化自检（依赖完整性、构建产物完整性等）。开发模式下比 `claude doctor` 更底层，适合"刚 clone 下来跑不起来"的场景。
+
+90% 的"莫名其妙不工作"在这两条命令的输出里都能看到线索——版本落后、settings.json 写错字段、keybindings 语法错、MCP 配置文件 JSON 解析失败。**先看这两条输出再问别人**，能省掉一大半来回。
+
+### Provider 报错对照表
+
+下面这张表覆盖最常见的 API 报错。Provider 切换方式详见产品第二章；这里只讲"切完之后出错了怎么办"。
+
+| HTTP 状态 / 错误类型 | 含义 | 用户侧怎么办 |
+| --- | --- | --- |
+| **401**（`authentication_error`） | API key 无效或已过期 | 跑 `/login` 重新登录；OpenAI 兼容层检查 `OPENAI_API_KEY`，Anthropic 直连检查 OAuth 令牌或 `ANTHROPIC_API_KEY`。**注意**：OpenAI/Grok 客户端是会话级缓存的（详见下文"我改了 key 但没生效"） |
+| **403** | 地区限制 / 权限不足 | 中国大陆直连 Anthropic 通常会 403；用 OpenAI 兼容层（DeepSeek / 智谱 / 通义 / Moonshot 等）或 Bedrock / Vertex 中转 |
+| **429** | 限流 | 看状态栏的限流指示；如果用 Claude.ai 订阅，可跑 `/rate-limit-options` 看升级 / 加包选项；OpenAI 兼容层会自动解析 `x-ratelimit-*` 响应头展示在 `/usage` 里 |
+| **529 / `"type":"overloaded_error"`** | 上游服务过载 | 稍等几秒重试。如果开了 fast mode（`/fast`），系统会自动切回标准模型并进入冷却期，状态栏会写 "Fast mode overloaded and is temporarily unavailable · resets in N" |
+| **模型不存在** | Provider 不认识你传的模型名 | 检查环境变量：OpenAI 看 `OPENAI_MODEL`，Gemini 看 `GEMINI_MODEL` 或 `GEMINI_DEFAULT_{HAIKU|SONNET|OPUS}_MODEL`，Grok 看 `XAI_API_KEY` / `GROK_*`。Gemini 缺配置时会**直接抛异常**，不会静默回退 |
+| **`max_output_tokens` 扣留** | 单轮输出超过模型上限 | 系统会自动最多重试 3 次（源码常量 `MAX_OUTPUT_TOKENS_RECOVERY_LIMIT = 3`，见 `src/query.ts:194`）；如果三轮还没收敛，本轮会以 `apiError === 'max_output_tokens'` 的 assistant 消息结束 |
+
+`claude.ts` 把 `error.status === 529` 和消息体里包含 `"type":"overloaded_error"` 的情况都归到 `server_overload`（见 `src/services/api/errors.ts:1004-1011`），所以同一个上游过载事件，不管是用 HTTP 状态码表达还是用错误体表达，对用户而言是同一件事——稍等重试。
+
+### 兼容层特有坑（OpenAI / Gemini / Grok）
+
+下面这些是兼容层才会遇到的，Anthropic 直连不会出现：
+
+- **我改了 API key 但没生效** —— 这是兼容层最高频的坑。`getOpenAIClient()`（`src/services/api/openai/client.ts:39`）和 Grok 客户端（`src/services/api/grok/client.ts`）都会把首次创建的客户端实例缓存到模块级变量（`cachedClient`，见 `openai/client.ts:15`）。中途改 `OPENAI_API_KEY` 环境变量不会让客户端重建。**解决办法**：重启 CLI；如果你在自己写脚本嵌入 Claude，必须显式调用 `clearOpenAIClientCache()`（`openai/client.ts:76`）清缓存。
+- **DeepSeek / 自托管模型报 400** —— DeepSeek 思维模式（`deepseek-reasoner`）会返回 `reasoning_content` 字段。把它原样回传给非思维模型变体会被服务端拒绝。系统在 `src/services/providerRegistry/providerCompatMatrix.ts` 里维护了一张兼容矩阵：`strip` 模式（Cerebras / Groq / strict-openai）总是剥掉 `reasoning_content`；`drop-on-non-thinking`（permissive）只在模型名匹配 `/reason|think/i` 时才保留；只有 DeepSeek 自己走 `always-preserve`。如果你用的是 DeepSeek 自托管端点且模型名不含 `reason` / `think` 字样，要么改模型名让正则命中，要么用 `permissive` 兼容规则。
+- **Bedrock Opus 4.7 报 400 `invalid beta flag`** —— 这是 `@anthropic-ai/bedrock-sdk` 0.26.4–0.28.1 的已知漏洞：SDK 把 `anthropic-beta` HTTP 头的值重植到请求体里成为 `anthropic_beta`，Bedrock 的 Opus 4.7 端点会拒绝任何带 `anthropic_beta` 体的请求。Claude Code 通过自定义 `BedrockClient` 类（`src/services/api/bedrockClient.ts`）在签名前剥离 `body.anthropic_beta` 解决。**普通用户不需要做什么**——这个补丁默认就生效。
+- **Gemini 报"requires GEMINI_MODEL"** —— Gemini 是唯一在模型映射全失败时**硬抛异常**的 Provider（`packages/@ant/model-provider/src/providers/gemini/modelMapping.ts:32`）。其它 Provider 找不到映射就原样返回模型名，Gemini 不行。看到这条报错就设一下 `GEMINI_MODEL` 或 `GEMINI_DEFAULT_SONNET_MODEL`（取决于你的家族）。
+- **限流信息看不到** —— OpenAI 兼容层的限流是从响应头 `x-ratelimit-remaining-requests` / `x-ratelimit-remaining-tokens` / `x-ratelimit-reset-*` 解析出来的（`src/services/providerUsage/adapters/openai.ts:62`）。如果你用的自托管端点不返回这些头，状态栏就拿不到限流信息——这不是 bug，是端点没实现。`/usage` 命令会展示已知 bucket。
+
+### MCP 连不上的排查清单
+
+MCP server 报"连接失败"时按下面顺序查：
+
+1. **stdio 类型**：命令路径对不对、参数对不对、本地能否手动跑起来。
+2. **SSE / HTTP 类型**：URL 能否 curl 通、是否需要 token、是否在 `claude mcp list` 里显示为已连接。
+3. **OAuth 失败**：跑 `/mcp-auth` 重新走授权流程。
+4. **MCP 配置文件 JSON 解析错误**：`claude doctor` 会显示 `MCP parsing warnings`，直接定位到具体文件和行号。
+5. **权限被拒**：检查 `/permissions` 里是否把工具 deny 掉了；deferred tool（不在 `CORE_TOOLS` 白名单里）需要通过 `SearchExtraTools` 按需加载。
+
+### 长会话变卡怎么办
+
+长会话内存膨胀有两类来源，处理方式不同：
+
+- **上下文太长** —— 跑 `/compact` 自动压缩；还不行就 `/force-snip` 强制剪裁历史；最彻底的是 `/clear` 重开。
+- **JSC 内存累积** —— 即使上下文压缩了，进程 RSS 也可能不下降。这是 JavaScriptCore 的已知特性（详见下文设计视角与设计第三章）。最快的解法是退出 CLI 重开。后台长跑场景（`/loop` / daemon）这个坑会更明显。
+
+### 我想看看 Claude 到底在做什么
+
+下面这几条命令按"侵入性"从低到高排：
+
+- `claude --dump-system-prompt` —— 把当前会话渲染出的完整 system prompt 打到 stdout（需要 build 时启用 `DUMP_SYSTEM_PROMPT` feature，见 `src/entrypoints/cli.tsx:90`）。排查"为什么 Claude 不按 CLAUDE.md 行事"时最有用。
+- `/debug-tool-call` —— 读取最近一次工具调用的请求 / 响应明细，源码在 `src/commands/debug-tool-call/index.ts`。
+- `BUN_INSPECT=9229 bun run dev:inspect` —— 把 Bun 调试器挂在 9229 端口，用 Chrome DevTools 连进去打断点。这是最重的手段，但对"卡死但没报错"类问题非常有效。
+- Langfuse 追踪 —— 如果你的部署启用了 Langfuse（详见 `docs/features/tools/langfuse-monitoring.md`），每次 API 调用都会被记录为一个 observation，包含模型名、Provider、token 用量、输入输出消息。
+
+### 反馈与上报 bug
+
+- `/feedback` —— 弹出反馈表单，源码 `src/commands/feedback/feedback.tsx`。
+- `/perf-issue` —— 性能问题专用通道，源码 `src/commands/perf-issue/index.ts`。
+- `/bughunter` —— 实验性 bug 自动归因工具（隐藏命令）。
+
+## 设计视角（写给开发者）
+
+设计大纲原本没有排错章——这是最大的缺口。补这一节是因为排错本身就是"被约束逼出来的工程化"的最好案例：每一个看似奇怪的兼容代码、每一条 TODO、每一个 probe 脚本，背后都对应着一个用户会碰到的具体错误。这一节按"这个错误的根因是 Y 设计决策"的思路展开。
+
+### 为什么 Bedrock 补丁必须配 probe 脚本
+
+打开 `src/services/api/bedrockClient.ts`，你会看到一个看起来有点啰嗦的类继承：
+
+```ts
+export class BedrockClient extends AnthropicBedrock {
+  async buildRequest(options: BuildRequestArg): Promise<BuildRequestRet> {
+    const req = await super.buildRequest(options)
+    // ... 解析 inner.body，删掉 parsed.anthropic_beta，重写 content-length
+    return req
+  }
+}
+```
+
+这个类的唯一作用是：**让 SDK 把请求构造完，然后在它签名之前把 `anthropic_beta` 从请求体里删掉**。注释（`bedrockClient.ts:1-25`）写得极其详尽——直接点名了 SDK 的具体文件和行号（`packages/bedrock-sdk/src/client.ts:193-198`）、相关 issue（`anthropics/claude-code#49238`，2026-04-16 提出）、漏洞版本范围（0.26.4 至少到 0.28.1）。
+
+为什么不直接给上游提 PR？因为上游修了之后，这段兼容代码也必须能被安全删除。注释最后一段写明了删除流程：
+
+> When upstream ships a fix, verify the probe in scripts/probe-bedrock-beta-fix.ts shows "bug reproduced: false", then delete this class and change services/api/client.ts to instantiate AnthropicBedrock directly.
+
+`scripts/probe-bedrock-beta-fix.ts` 这个文件在源码注释里被点名引用，目的是"装个探针，等上游修了就跑一下，确认 false 就删类"。这是一种"针对性补丁 + 自动退役"的工程范式——和一般补丁的区别在于它**自带退役机制**：probe 脚本本身就是"这个补丁该不该继续存在"的判据。
+
+> **诚实核对**：注释里点名的 `scripts/probe-bedrock-beta-fix.ts` 目前在仓库里**找不到**（仓库里现存的 probe 脚本是 `scripts/probe-local-wiring.ts` 和 `scripts/probe-subscription-endpoints.ts`）。这意味着这个"自动退役机制"目前只是注释里的口头约定，并没有真的自动化。这是反编译重建工作的一个典型痕迹：原版可能有这个脚本，重建时没还原。
+
+### 为什么 DeepSeek 必须把 reasoning_content 分三种模式处理
+
+DeepSeek 的思维模型（`deepseek-reasoner`）会在 assistant 消息里返回 `reasoning_content` 字段。但同样一个字段，对三个不同的接收端会触发完全不同的行为：
+
+- **DeepSeek 自己**：期望被原样回传（`always-preserve`）。
+- **Cerebras / Groq / 标准 OpenAI 协议端点**：拒绝任何非标准字段（`strip`）。
+- **permissive 端点（非 DeepSeek）**：思维模型变体可以保留，非思维变体会拒绝（`drop-on-non-thinking`，靠模型名正则 `/reason|think/i` 判断）。
+
+这套规则定义在 `src/services/providerRegistry/providerCompatMatrix.ts:43-76` 的 `COMPAT_PROFILES` 表里，由 `applyCompatRule`（同文件 `:104`）实施。打开 `getDeepSeekReasoningMode`（`:86`）你能看到三种模式的判定：`thinking-only`（有 reasoning_content 无 tool_calls）、`thinking+tools`（两者都有）、`normal`（都没有）。
+
+**根因**：DeepSeek 的 API 把"模型上一轮想了什么"塞回 `reasoning_content` 字段，期望客户端在下一次请求里回传。但标准 OpenAI 协议没有这个字段，严格端点（Cerebras / Qwen）会直接 400。所以兼容矩阵本质上是一张"哪些端点容忍哪些非标准字段"的合约表——这是"多 Provider 兼容"工程化的必然产物。
+
+反事实推演：如果只写一种策略（比如永远 strip），DeepSeek 思维模式就彻底用不了；如果只写 always-preserve，严格端点全炸。三种模式是兼容性 / 功能性的最小必要切分。
+
+### 为什么 isFirstPartyAnthropicBaseUrl 的 TODO 是个真陷阱
+
+打开 `src/utils/model/providers.ts:43`：
+
+```ts
+export function isFirstPartyAnthropicBaseUrl(): boolean {
+  const baseUrl = process.env.ANTHROPIC_BASE_URL
+  // TODO: 这里会有问题, 只配置了 openai 协议的用户, 按理说会为 true 导致问题
+  if (!baseUrl) {
+    return true
+  }
+  // ... 检查 host 是否为 api.anthropic.com
+}
+```
+
+这条 TODO 的含义是：**如果用户只配了 OpenAI 兼容层（`CLAUDE_CODE_USE_OPENAI=1` + `OPENAI_BASE_URL=...`），但没有配 `ANTHROPIC_BASE_URL`，那么这个函数返回 `true`**。也就是说系统会误以为"现在是 Anthropic 直连模式"，从而触发一些只该在 firstParty 模式下才生效的行为。
+
+这个函数在 `src/services/api/client.ts:367`（`buildFetch`）被用来决定是否注入 `x-client-request-id` 头。注释（`client.ts:365`）写得很谨慎："Only send to the first-party API — Bedrock/Vertex/Foundry don't log it and unknown headers risk rejection by strict proxies (inc-4029 class)."
+
+**根因**：函数判定的输入只有 `ANTHROPIC_BASE_URL` 一个变量，但"用户在用哪家 Provider"实际上由 `getAPIProvider()`（同文件 `:15`）综合 `modelType` / `CLAUDE_CODE_USE_*` 环境变量决定。两个判定来源脱节就会导致 firstParty 行为泄漏到兼容层场景。
+
+修复方向（TODO 没明说，但隐含）是把判定改成"先看 `getAPIProvider()` 是不是 `firstParty`，再看 base URL 是不是 anthropic 域"。但这是一个**有副作用的改动**——会改变 firstParty 路径下注入 header 的行为，需要回归测试，所以至今挂在 TODO 上。
+
+### 为什么 OpenAI 客户端是模块级缓存，而 Anthropic 客户端不是
+
+对比两个客户端工厂函数：
+
+| | Anthropic | OpenAI | Grok |
+| --- | --- | --- | --- |
+| 入口 | `getAnthropicClient`（`client.ts:84`） | `getOpenAIClient`（`openai/client.ts:39`） | `getGrokClient`（`grok/client.ts`） |
+| 缓存 | 不缓存，每次按 model / region 参数化新建 | 模块级 `cachedClient` 单例 | 模块级单例 |
+| 改 key 后果 | 下次调用立刻生效 | 必须重启或 `clearOpenAIClientCache()` | 必须重启 |
+
+为什么设计不一致？看 `client.ts:153-298` 就明白了：Anthropic 路径每次构造客户端时要做 AWS / GCP / Azure 凭证刷新、按模型选 region、注入几十个 header——这些都是**会话过程中可能变化的参数**，所以必须每次重新构造。OpenAI / Grok 路径简单得多：一个 key、一个 base URL，理论上整个会话都不变，所以缓存能省掉重复初始化的开销。
+
+代价就是"改 key 不生效"这个高频用户困惑。`clearOpenAIClientCache`（`openai/client.ts:76`）是项目给用户留的逃生口——但这要求用户**知道这个函数存在**，对一般使用者完全不可见。这是"性能 vs 可调试性"的典型权衡。
+
+### 为什么错误归类要绕一圈通过错误消息字符串匹配
+
+打开 `src/services/api/errors.ts:1004-1011`，你会看到这种判定：
+
+```ts
+if (
+  error instanceof APIError &&
+  (error.status === 529 ||
+    error.message?.includes('"type":"overloaded_error"'))
+) {
+  return 'server_overload'
+}
+```
+
+为什么不光看 `status === 529`，还要扫消息文本？因为 Anthropic API 在某些路径下会用其它状态码（比如 503）配 `"type":"overloaded_error"` 错误体表达同一个"上游过载"事件。SDK 的 `APIError` 不一定把错误类型暴露成结构化字段，错误体只能从 `message` 里捞。
+
+`withRetry.ts:612-616` 和 `:716-720` 用同样的字符串匹配判定 529 / overloaded。这种基于字符串的错误匹配**天然脆弱**——上游改一个字段名整个判定就失效。但目前没有更好的方案：上游 SDK 的错误类型抽象不够细，自己重写又会让兼容层耦合到具体 SDK 版本。这是"用 SDK 但 SDK 抽象不到位"的典型代价。
+
+### 为什么 performanceShim 必须最先 import
+
+打开 `src/entrypoints/cli.tsx:5`：
+
+```ts
+// Performance shim MUST be the first import — it replaces globalThis.performance
+// with a JS-backed implementation before React/OTel capture the native reference.
+import '../utils/performanceShim.js';
+```
+
+注释里的"MUST be the first import"不是审美，而是**顺序依赖**。`src/utils/performanceShim.ts:1-17` 解释了原因：JSC 原生的 `performance` 对象把 marks / measures / resource timings 存进一个永不收缩的 C++ Vector。长会话（daemon、`/loop`）会累积几百 MB 的死容量。
+
+shim 做的事是：保留 `performance.now()` 走原生（快、不占内存），但把 `mark` / `measure` / `getEntries` 重定向到 GC 可回收的 JS Map。**为什么必须最先 import**：因为 React reconciler 和 OTel / Langfuse 客户端会**捕获 `globalThis.performance` 的引用**。一旦它们拿到原生引用，shim 再装上也没用——它们调用的是自己缓存的原生对象。
+
+`src/query.ts:367-380` 在每次 query 的 finally 块里调用 `gPerf.clearMarks()` / `clearMeasures()` / `clearResourceTimings()`，作为兜底——防止某些 sub-agent 路径直接 `import query` 而 shim 没装上的情况。这是一个"shim 没生效时的保险栓"。
+
+**这条和排错的交集**：用户报告"长会话越用越卡，RSS 涨到 1GB"时，根因往往就是某个 import 路径绕过了 shim、或者某个第三方库缓存了原生 performance 引用。排查方向是去看最近一次新增的依赖有没有在顶层捕获 performance。
+
+### 为什么 Langfuse 追踪必须从 getAPIProvider() 取 provider
+
+打开 `src/services/api/claude.ts:2997`：
+
+```ts
+recordLLMObservation(options.langfuseTrace ?? null, {
+  model: resolvedModel,
+  provider: getAPIProvider(),
+  // ...
+})
+```
+
+`provider` 字段直接调 `getAPIProvider()`（`src/utils/model/providers.ts:15`）取值——不读缓存、不信变量、单一真相源。**为什么这么严格**：Langfuse 上游的报表按 Provider 分组聚合（openai / gemini / grok / firstParty / bedrock / vertex / foundry）。如果不同代码路径用了不同的 Provider 判定（比如有的读 `CLAUDE_CODE_USE_OPENAI`、有的读 `settings.modelType`），同一类请求会被分到不同桶，统计就废了。
+
+`getAPIProvider()` 把判定逻辑收敛到一处：先看 `modelType`，再看 `CLAUDE_CODE_USE_*` 环境变量，最后默认 `firstParty`。**任何**想读"当前在用哪家 Provider"的代码——`/provider` 命令、Langfuse 观测、模型映射——都必须走这个函数。这是"单一真相源"原则的硬执行。
+
+### 为什么 errors.ts 要写 1000+ 行
+
+`src/services/api/errors.ts` 是一个超过 1000 行的文件，里面几乎全是错误归类逻辑（`return 'rate_limit'` / `return 'server_overload'` / `return 'prompt_too_long'` ...）。为什么错误归类要写这么多？
+
+因为每一个归类结果都对应**不同的用户提示 / 不同的重试策略 / 不同的 UI 反馈**：
+
+- `rate_limit` → 展示剩余配额、提示升级
+- `server_overload` → 静默重试 + cooldown
+- `prompt_too_long` → 提示用户 `/compact`
+- `pdf_too_large` → 提示用户拆分 PDF
+
+而归类的输入五花八门：HTTP 状态码、错误消息字符串、SDK 错误类型、自定义 off-switch 消息（见 `errors.ts:991-997`）。同一个"上游过载"语义可以用 `status === 529`、`status === 503 + overloaded_error`、甚至 emergency off-switch 消息表达。把所有这些判定集中到一个文件，是**避免错误处理碎片化**的工程实践——否则每个调用点都得自己写一遍字符串匹配，必然漂移。
+
+## 两视角如何呼应
+
+用户视角的痛点几乎都能在设计视角找到对应的设计决策：
+
+- **"我改了 API key 但没生效"**（产品视角）对应**"OpenAI/Grok 客户端为什么是模块级缓存"**（设计视角）——这是性能优化带来的副作用。设计视角给出逃生口 `clearOpenAIClientCache`，但这个逃生口对一般用户不可见，所以产品视角必须明说"重启 CLI"。
+- **"Bedrock Opus 4.7 报 400"**（产品视角）对应**"为什么 Bedrock 补丁必须配 probe 脚本"**（设计视角）——补丁默认就生效，用户什么都不用做；但 probe 脚本的缺失是反编译重建的诚实边界。
+- **"Gemini 报 requires GEMINI_MODEL"**（产品视角）对应**"Gemini 为什么在映射全失败时硬抛异常"**（设计视角）——这是 Gemini Provider 唯一不静默回退的设计选择，产品视角必须把"必须配置环境变量"讲清楚。
+- **"长会话越用越卡"**（产品视角）对应**"performanceShim 必须最先 import"**（设计视角）——用户看到的是 RSS 上涨，根因在 JSC C++ Vector 永不收缩。
+- **"529 / overloaded 怎么处理"**（产品视角）对应**"为什么错误归类要绕一圈通过字符串匹配"**（设计视角）——用户只需要知道"稍等重试"，开发者必须理解字符串匹配的脆弱性。
+- **"Langfuse 里 Provider 分桶不对"**（产品视角）对应**"为什么 provider 字段必须从 getAPIProvider() 取"**（设计视角）——单一真相源是统计正确性的前提。
+
+这种呼应关系是排错章必须双视角覆盖的核心原因：用户视角告诉你**遇到这个错误怎么办**，设计视角告诉你**为什么会有这个错误**。两个视角合在一起，才能让使用者和维护者用同一套词汇对话。