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

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

.claude/agents/hello-agent.md

@@ -0,0 +1,17 @@
+---
+name: hello-agent
+description: A friendly greeting agent that introduces the project
+---
+
+You are a friendly greeting agent. Your job is to greet the user and provide helpful information about the current project.
+
+Instructions:
+1. Read the project's CLAUDE.md to understand the project context.
+2. Greet the user warmly.
+3. Provide a brief summary of the project based on what you learned from CLAUDE.md.
+4. Offer to help with any questions about the project.
+
+Style:
+- Be concise and friendly.
+- Respond in 简体中文.
+- Keep responses short — no more than a few sentences.

.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,29 +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: 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: Lint
-        run: bun run lint
+      - name: Lint and format check
+        run: bunx biome ci .
 
-      - name: Test
-        run: bun test
+      - 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,6 +5,54 @@ coverage
 .env
 *.log
 .idea
-.vscode
+.vscode/*
+!.vscode/extensions.json
 *.suo
-*.lock
+*.lock
+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

@@ -0,0 +1,13 @@
+{
+	"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
 
@@ -12,36 +27,86 @@ This is a **reverse-engineered / decompiled** version of Anthropic's official Cl
 # Install dependencies
 bun install
 
-# Dev mode (direct execution via Bun)
+# Dev mode (runs cli.tsx with MACRO defines injected via -d flags)
 bun run dev
-# equivalent to: bun run src/entrypoints/cli.tsx
+
+# 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 (outputs dist/cli.js, ~25MB)
+# 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) — 日常开发用 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
+
+# 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
 ```
 
-No test runner is configured. No linter is configured.
+详细的测试规范、覆盖状态和改进计划见 `src/**/__tests__/` 与 `tests/integration/`。
 
 ## Architecture
 
 ### Runtime & Build
 
 - **Runtime**: Bun (not Node.js). All imports, builds, and execution use Bun APIs.
-- **Build**: `bun build src/entrypoints/cli.tsx --outdir dist --target bun` — single-file bundle.
+- **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:*`.
+- **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
 
-1. **`src/entrypoints/cli.tsx`** — True entrypoint. Injects runtime polyfills at the top:
-   - `feature()` always returns `false` (all feature flags disabled, skipping unimplemented branches).
-   - `globalThis.MACRO` — simulates build-time macro injection (VERSION, BUILD_TIME, etc.).
-   - `BUILD_TARGET`, `BUILD_ENV`, `INTERFACE_TYPE` globals.
-2. **`src/main.tsx`** — Commander.js CLI definition. Parses args, initializes services (auth, analytics, policy), then launches the REPL or runs in pipe mode.
-3. **`src/entrypoints/init.ts`** — One-time initialization (telemetry, config, trust dialog).
+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`** (~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
 
@@ -52,32 +117,87 @@ No test runner is configured. No linter is configured.
 ### 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>/`** — Each tool in its own directory (e.g., `BashTool`, `FileEditTool`, `GrepTool`, `AgentTool`).
-- Tools define: `name`, `description`, `inputSchema` (JSON Schema), `call()` (execution), and optionally a React component for rendering results.
+- **`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 components rendered in terminal via Ink. Key ones:
-  - `App.tsx` — Root provider (AppState, Stats, FpsMetrics).
-  - `Messages.tsx` / `MessageRow.tsx` — Conversation message rendering.
-  - `PromptInput/` — User input handling.
-  - `permissions/` — Tool permission approval UI.
+- **`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/store.ts`** — Zustand-style store for AppState.
-- **`src/bootstrap/state.ts`** — Module-level singletons for session-global state (session ID, CWD, project root, token counts).
+- **`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/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/`** — 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
+
+- **`src/daemon/`** — Daemon 模式（长驻 supervisor）。feature-gated by `DAEMON`。包含 `main.ts`（entry）和 `workerRegistry.ts`（worker 管理）。
 
 ### Context & System Prompt
 
@@ -86,17 +206,75 @@ No test runner is configured. No linter is configured.
 
 ### Feature Flag System
 
-All `feature('FLAG_NAME')` calls come from `bun:bundle` (a build-time API). In this decompiled version, `feature()` is polyfilled to always return `false` in `cli.tsx`. This means all Anthropic-internal features (COORDINATOR_MODE, KAIROS, PROACTIVE, etc.) are disabled.
+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**（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
@@ -106,10 +284,132 @@ All `feature('FLAG_NAME')` calls come from `bun:bundle` (a build-time API). In t
 - **`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/` — 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")`，英文
+- **包测试**: `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.
-- **`feature()` is always `false`** — any code behind a feature flag is dead code in this build.
+- **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** — In `src/main.tsx` and other files, `import { feature } from 'bun:bundle'` works at build time. At dev-time, the polyfill in `cli.tsx` provides it.
+- **`bun:bundle` import** — `import { feature } from 'bun:bundle'` 是 Bun 内置模块，由运行时/构建器解析。不要用自定义函数替代它。**`feature()` 只能直接用在 `if` 语句或三元表达式的条件位置**（Bun 编译器限制），不能赋值给变量、不能放在箭头函数体里、不能作为 `&&` 链的一部分。正确：`if (feature('X')) {}` 或 `feature('X') ? a : b`。
 - **`src/` path alias** — tsconfig maps `src/*` to `./src/*`. Imports like `import { ... } from 'src/utils/...'` are valid.
+- **MACRO defines** — 集中管理在 `scripts/defines.ts`。Dev mode 通过 `bun -d` 注入，build 通过 `Bun.build({ define })` 注入。修改版本号等常量只改这个文件。
+- **构建产物兼容 Node.js** — `build.ts` 会自动后处理 `import.meta.require`，产物可直接用 `node dist/cli.js` 运行。
+- **Biome 配置** — 42 条 lint 规则因 decompiled 代码被关闭，仅保留 `recommended` 基线。格式化覆盖全项目（`src/`、`scripts/`、`packages/`，含 `packages/@ant/`）。`.tsx` 文件用 120 行宽 + 强制分号；其他文件 80 行宽 + 按需分号。JSON 格式化已启用。`.editorconfig` 与 Biome 配置对齐（2-space 缩进）。修改任何代码后应运行 `bun run precheck` 确认无类型/lint/格式/测试问题，pre-commit hook 会自动拦截不合格提交。
+- **tsc 与 Biome 冲突处理** — 当 tsc 要求声明属性（赋值使用）但 biome 报 `noUnusedPrivateClassMembers`（只写不读）时，用 `// biome-ignore lint/correctness/noUnusedPrivateClassMembers: <原因>` 抑制 lint 警告，保留类型声明。`biome ci` 必须零 warnings。
+- **`@ts-expect-error` 维护** — 只在下方代码确实有类型错误时保留 `@ts-expect-error`。如果类型系统已更新导致 directive 变为 unused（TS2578），直接移除注释。MACRO 替换产生的永假比较（如 `'production' === 'development'`）仍需保留 `@ts-expect-error`。
+- **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

@@ -0,0 +1,994 @@
+# 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`
+
+在 `/login` 流程中新增 "OpenAI Compatible" 选项，支持 Ollama、DeepSeek、vLLM、One API 等兼容 OpenAI Chat Completions API 的第三方服务。用户通过 `/login` 配置后，所有 API 请求自动走 OpenAI 路径。
+
+**改动文件（10 个，+384 / -134）：**
+
+| 文件 | 变更 |
+|------|------|
+| `.github/workflows/ci.yml` | CI runner 从 `ubuntu-latest` 改为 `macos-latest` |
+| `README.md` | TODO 列表新增 "OpenAI 接口兼容" 条目 |
+| `src/components/ConsoleOAuthFlow.tsx` | 新增 `openai_chat_api` OAuth state（含 Base URL / API Key / 3 个模型映射字段）；idle 选择列表新增 "OpenAI Compatible" 选项；完整表单 UI（Tab 切换、Enter 保存）；保存时写入 `modelType: 'openai'` + env 到 settings.json；OAuth 登录时重置 `modelType` 为 `anthropic` |
+| `src/services/api/openai/index.ts` | 从直接 `yield* adaptOpenAIStreamToAnthropic()` 改为完整流处理循环：累积 content blocks（text/tool_use/thinking）、按 `content_block_stop` yield `AssistantMessage`、同时 yield `StreamEvent` 用于实时显示；错误处理改用新签名 `createAssistantAPIErrorMessage({ content, apiError, error })` |
+| `src/services/api/openai/convertMessages.ts` | 输入类型从 Anthropic SDK `BetaMessageParam[]` 改为内部 `(UserMessage \| AssistantMessage)[]`；通过 `msg.type` 而非 `msg.role` 判断角色；从 `msg.message.content` 读取内容；跳过 `cache_edits` / `server_tool_use` 等内部 block 类型 |
+| `src/services/api/openai/modelMapping.ts` | 移除 `OPENAI_MODEL_MAP` JSON 环境变量 + 缓存机制；新增 `getModelFamily()` 按 haiku/sonnet/opus 分类；解析优先级改为：`OPENAI_MODEL` → `ANTHROPIC_DEFAULT_{FAMILY}_MODEL` → `DEFAULT_MODEL_MAP` → 原名透传 |
+| `src/services/api/openai/__tests__/convertMessages.test.ts` | 测试输入从裸 `{ role, content }` 改为 `makeUserMsg()` / `makeAssistantMsg()` 包装的内部格式 |
+| `src/services/api/openai/__tests__/modelMapping.test.ts` | 测试从 `OPENAI_MODEL_MAP` 改为 `ANTHROPIC_DEFAULT_{HAIKU,SONNET,OPUS}_MODEL`；新增 3 个 env var override 测试 |
+| `src/utils/model/providers.ts` | `getAPIProvider()` 新增最高优先级：从 settings.json `modelType` 字段判断；环境变量 `CLAUDE_CODE_USE_OPENAI` 降为次优先 |
+| `src/utils/settings/types.ts` | `SettingsSchema` 新增 `modelType` 字段：`z.enum(['anthropic', 'openai']).optional()` |
+
+**关键设计决策：**
+
+1. **`modelType` 存入 settings.json** — 而非纯环境变量，使 `/login` 配置持久化，重启后仍然生效
+2. **复用 `ANTHROPIC_DEFAULT_*_MODEL` 环境变量** — 而非新增 `OPENAI_MODEL_MAP`，与 Custom Platform 共用同一套模型映射配置，减少用户认知负担
+3. **流处理双 yield** — 同时 yield `AssistantMessage`（给消费方处理工具调用）和 `StreamEvent`（给 REPL 实时渲染），与 Anthropic 路径行为对齐
+4. **OAuth 登录重置 modelType** — 用户切换回官方 Anthropic 登录时自动重置为 `anthropic`，避免残留配置导致请求走错误路径
+
+**配置方式：**
+
+```
+/login → 选择 "OpenAI Compatible" → 填写 Base URL / API Key / 模型名称
+```
+
+或手动编辑 `~/.claude/settings.json`：
+
+```json
+{
+  "modelType": "openai",
+  "env": {
+    "OPENAI_BASE_URL": "http://localhost:11434/v1",
+    "OPENAI_API_KEY": "ollama",
+    "ANTHROPIC_DEFAULT_SONNET_MODEL": "qwen3:32b"
+  }
+}
+```
+
+---
+
+## Enable Remote Control / BRIDGE_MODE (2026-04-03)
+
+**PR**: [claude-code-best/claude-code#60](https://github.com/claude-code-best/claude-code/pull/60)
+
+Remote Control 功能将本地 CLI 注册为 bridge 环境，生成可分享的 URL（`https://claude.ai/code/session_xxx`），允许从浏览器、手机或其他设备远程查看输出、发送消息、审批工具调用。
+
+**改动文件：**
+
+| 文件 | 变更 |
+|------|------|
+| `scripts/dev.ts` | `DEFAULT_FEATURES` 加入 `"BRIDGE_MODE"`，dev 模式默认启用 |
+| `src/bridge/peerSessions.ts` | stub → 完整实现：通过 bridge API 发送跨会话消息，含三层安全防护（trim + validateBridgeId 白名单 + encodeURIComponent） |
+| `src/bridge/webhookSanitizer.ts` | stub → 完整实现：正则 redact 8 类 secret（GitHub/Anthropic/AWS/npm/Slack token），先 redact 再截断，失败返回安全占位符 |
+| `src/entrypoints/sdk/controlTypes.ts` | 12 个 `any` stub → `z.infer<ReturnType<typeof XxxSchema>>` 从现有 Zod schema 推导类型 |
+| `src/hooks/useReplBridge.tsx` | `tengu_bridge_system_init` 默认值 `false` → `true`，使 app 端显示 "active" 而非卡在 "connecting" |
+
+**关键设计决策：**
+
+1. **不改现有代码逻辑** — 只补全 stub、修正默认值、开启编译开关
+2. **`tengu_bridge_system_init`** — Anthropic 通过 GrowthBook 给订阅用户推送 `true`，但我们的 build 收不到推送；改默认值是唯一不侵入其他代码的方案
+3. **`peerSessions.ts` 认证** — 使用 `getBridgeAccessToken()` 获取 OAuth Bearer token，与 `bridgeApi.ts`/`codeSessionApi.ts` 认证模式一致
+4. **`webhookSanitizer.ts` 安全** — fail-closed（出错返回 `[webhook content redacted due to sanitization error]`），不泄露原始内容
+
+**验证结果：**
+
+- `/remote-control` 命令可见且可用
+- CLI 连接 Anthropic CCR，生成可分享 URL
+- App 端（claude.ai/code）显示 "Remote Control active"
+- 手机端（Claude iOS app）通过 URL 连接，双向消息正常
+
+![Remote Control on Mobile](docs/images/remote-control-mobile.png)
+
+---
+
+## GrowthBook 自定义服务器适配器 (2026-04-03)
+
+GrowthBook 功能开关系统原为 Anthropic 内部构建设计，硬编码 SDK key 和 API 地址，外部构建因 `is1PEventLoggingEnabled()` 门控始终禁用。新增适配器模式，通过环境变量连接自定义 GrowthBook 服务器，无配置时所有 feature 读取返回代码默认值。
+
+**修改文件：**
+
+| 文件 | 变更 |
+|------|------|
+| `src/constants/keys.ts` | `getGrowthBookClientKey()` 优先读取 `CLAUDE_GB_ADAPTER_KEY` 环境变量 |
+| `src/services/analytics/growthbook.ts` | `isGrowthBookEnabled()` 适配器模式下直接返回 `true`，绕过 1P event logging 门控 |
+| `src/services/analytics/growthbook.ts` | `getGrowthBookClient()` base URL 优先使用 `CLAUDE_GB_ADAPTER_URL` |
+| `docs/internals/growthbook-adapter.mdx` | 新增适配器配置文档，含全部 ~58 个 feature key 列表 |
+
+**用法：** `CLAUDE_GB_ADAPTER_URL=https://gb.example.com/ CLAUDE_GB_ADAPTER_KEY=sdk-xxx bun run dev`
+
+---
+
+## Datadog 日志端点可配置化 (2026-04-03)
+
+将 Datadog 硬编码的 Anthropic 内部端点改为环境变量驱动，默认禁用。
+
+**修改文件：**
+
+| 文件 | 变更 |
+|------|------|
+| `src/services/analytics/datadog.ts` | `DATADOG_LOGS_ENDPOINT` 和 `DATADOG_CLIENT_TOKEN` 从硬编码常量改为读取 `process.env.DATADOG_LOGS_ENDPOINT` / `process.env.DATADOG_API_KEY`，默认空字符串；`initializeDatadog()` 增加守卫：端点或 Token 未配置时直接返回 `false` |
+| `docs/telemetry-remote-config-audit.md` | 更新第 1 节，反映新的环境变量配置方式 |
+
+**效果：** 默认不向任何外部发送数据；设置两个环境变量即可接入自己的 Datadog 实例。原有 `DISABLE_TELEMETRY`、privacy level、sink killswitch 等防线保留。
+
+**用法：** `DATADOG_LOGS_ENDPOINT=https://http-intake.logs.datadoghq.com/api/v2/logs DATADOG_API_KEY=xxx bun run dev`
+
+---
+
+## Sentry 错误上报集成 (2026-04-03)
+
+恢复反编译过程中被移除的 Sentry 集成。通过 `SENTRY_DSN` 环境变量控制，未设置时所有函数为 no-op，不影响正常运行。
+
+**新增文件：**
+
+| 文件 | 说明 |
+|------|------|
+| `src/utils/sentry.ts` | 核心模块：`initSentry()`、`captureException()`、`setTag()`、`setUser()`、`closeSentry()`；`beforeSend` 过滤 auth headers 等敏感信息；忽略 ECONNREFUSED/AbortError 等非 actionable 错误 |
+
+**修改文件：**
+
+| 文件 | 变更 |
+|------|------|
+| `src/utils/errorLogSink.ts` | `logErrorImpl` 末尾调用 `captureException()`，所有经 `logError()` 的错误自动上报 |
+| `src/components/SentryErrorBoundary.ts` | 添加 `componentDidCatch`，React 组件渲染错误上报到 Sentry（含 componentStack） |
+| `src/entrypoints/init.ts` | 网络配置后调用 `initSentry()` |
+| `src/utils/gracefulShutdown.ts` | 优雅关闭时 flush Sentry 事件 |
+| `src/screens/REPL.tsx:2809` | `fireCompanionObserver` 调用增加 `typeof` 防护，BUDDY feature 启用时不报错（TODO: 待实现） |
+| `package.json` | devDependencies 新增 `@sentry/node` |
+
+**用法：** `SENTRY_DSN=https://xxx@xxx.ingest.sentry.io/xxx bun run dev`
+
+---
+
+## 默认关闭自动更新 (2026-04-03)
+
+修改 `src/utils/config.ts` — `getAutoUpdaterDisabledReason()`，在原有检查逻辑前插入默认关闭逻辑。未设置 `ENABLE_AUTOUPDATER=1` 时，自动更新始终返回 `{ type: 'config' }` 被禁用。
+
+**启用方式：** `ENABLE_AUTOUPDATER=1 bun run dev`
+
+**原因：** 本项目为逆向工程/反编译版本，自动更新会覆盖本地修改的代码。
+
+**同时新增文档：** `docs/auto-updater.md` — 自动更新机制完整审计，涵盖三种安装类型的更新策略、后台轮询、版本门控、原生安装器架构、文件锁、配置项等。
+
+---
+
+## WebSearch Bing 适配器补全 (2026-04-03)
+
+原始 `WebSearchTool` 仅支持 Anthropic API 服务端搜索（`web_search_20250305` server tool），在非官方 API 端点（第三方代理）下搜索功能不可用。本次改动引入适配器架构，新增 Bing 搜索页面解析作为 fallback。
+
+**新增文件：**
+
+| 文件 | 说明 |
+|------|------|
+| `src/tools/WebSearchTool/adapters/types.ts` | 适配器接口定义：`WebSearchAdapter`、`SearchResult`、`SearchOptions`、`SearchProgress` |
+| `src/tools/WebSearchTool/adapters/apiAdapter.ts` | API 适配器 — 将原有 `queryModelWithStreaming` 逻辑封装为 `ApiSearchAdapter` |
+| `src/tools/WebSearchTool/adapters/bingAdapter.ts` | Bing 适配器 — 直接抓取 Bing HTML，正则提取搜索结果 |
+| `src/tools/WebSearchTool/adapters/index.ts` | 适配器工厂 — 根据环境变量 / API Base URL 选择后端 |
+| `src/tools/WebSearchTool/__tests__/bingAdapter.test.ts` | Bing 适配器单元测试（32 cases：decodeHtmlEntities、extractBingResults、search mock） |
+| `src/tools/WebSearchTool/__tests__/bingAdapter.integration.ts` | Bing 适配器集成测试 — 真实网络请求验证 |
+
+**重构文件：**
+
+| 文件 | 变更 |
+|------|------|
+| `src/tools/WebSearchTool/WebSearchTool.ts` | 从直接调用 API 改为 `createAdapter()` 工厂模式；`isEnabled()` 始终返回 true；删除 ~200 行内联 API 调用逻辑 |
+| `src/tools/WebFetchTool/utils.ts` | `skipWebFetchPreflight` 默认值从 `!undefined`（即 true）改为显式 `=== false`，使域名预检默认启用 |
+
+**Bing 适配器关键技术细节：**
+
+1. **反爬绕过**：使用完整 Edge 浏览器请求头（含 `Sec-Ch-Ua`、`Sec-Fetch-*` 等 13 个标头），避免 Bing 返回 JS 渲染的空页面；`setmkt=en-US` 参数强制美式英语市场，避免 IP 地理定位导致的区域化结果（德语论坛、新加坡金价等不相关内容）
+2. **URL 解码**（`resolveBingUrl()`）：Bing 返回的重定向 URL（`bing.com/ck/a?...&u=a1aHR0cHM6Ly9...`）中 `u` 参数为 base64 编码的真实 URL，需解码后使用
+3. **摘要提取**（`extractSnippet()`）：三级降级策略 — `b_lineclamp` → `b_caption <p>` → `b_caption` 直接文本
+4. **HTML 实体解码**（`decodeHtmlEntities()`）：处理 7 种常见 HTML 实体
+5. **域过滤**：客户端侧 `allowedDomains` / `blockedDomains` 过滤，支持子域名匹配
+
+**当前状态**：`adapters/index.ts` 中 `createAdapter()` 硬编码返回 `BingSearchAdapter`，跳过了 API/Bing 自动选择逻辑（原逻辑被注释保留）。未来可通过取消注释恢复自动选择。
+
+---
+
+## 移除反蒸馏机制 (2026-04-02)
+
+项目中发现三处 anti-distillation 相关代码，全部移除。
+
+**移除内容：**
+- `src/services/api/claude.ts` — 删除 fake_tools 注入逻辑（原第 302-314 行），该代码通过 `ANTI_DISTILLATION_CC` feature flag 在 API 请求中注入 `anti_distillation: ['fake_tools']`，使服务端在响应中混入虚假工具调用以污染蒸馏数据
+- `src/utils/betas.ts` — 删除 connector-text summarization beta 注入块及 `SUMMARIZE_CONNECTOR_TEXT_BETA_HEADER` 导入，该机制让服务端缓冲工具调用间的 assistant 文本并摘要化返回
+- `src/constants/betas.ts` — 删除 `SUMMARIZE_CONNECTOR_TEXT_BETA_HEADER` 常量定义（原第 23-25 行）
+- `src/utils/streamlinedTransform.ts` — 注释从 "distillation-resistant" 改为 "compact"，streamlined 模式本身是有效的输出压缩功能，仅修正描述
+
+---
+
+## Buddy 命令合入 + Feature Flag 规范修正 (2026-04-02)
+
+合入 `pr/smallflyingpig/36` 分支（支持 buddy 命令 + 修复 rehatch），并修正 feature flag 使用方式。
+
+**合入内容（来自 PR）：**
+- `src/commands/buddy/buddy.ts` — 新增 `/buddy` 命令，支持 hatch / rehatch / pet / mute / unmute 子命令
+- `src/commands/buddy/index.ts` — 从 stub 改为正确的 `Command` 类型导出
+- `src/buddy/companion.ts` — 新增 `generateSeed()`，`getCompanion()` 支持 seed 驱动的可复现 rolling
+- `src/buddy/types.ts` — `CompanionSoul` 增加 `seed?` 字段
+
+**合并后修正：**
+- `src/entrypoints/cli.tsx` — PR 硬编码了 `const feature = (name) => name === "BUDDY"`，违反 feature flag 规范，恢复为标准 `import { feature } from 'bun:bundle'`
+- `src/commands.ts` — PR 用静态 `import buddy` 绕过了 feature gate，恢复为 `feature('BUDDY') ? require(...) : null` + 条件展开
+- `src/commands/buddy/buddy.ts` — 删除未使用的 `companionInfoText` 函数和多余的 `Roll`/`SPECIES` import
+- `CLAUDE.md` — 重写 Feature Flag System 章节，明确规范：代码中统一用 `import { feature } from 'bun:bundle'`，启用走环境变量 `FEATURE_<NAME>=1`
+
+**用法：** `FEATURE_BUDDY=1 bun run dev`
+
+---
+
+## Auto Mode 补全 (2026-04-02)
+
+反编译丢失了 auto mode 分类器的三个 prompt 模板文件，代码逻辑完整但无法运行。
+
+**新增：**
+- `yolo-classifier-prompts/auto_mode_system_prompt.txt` — 主系统提示词
+- `yolo-classifier-prompts/permissions_external.txt` — 外部权限模板（用户规则替换默认值）
+- `yolo-classifier-prompts/permissions_anthropic.txt` — 内部权限模板（用户规则追加）
+
+**改动：**
+- `scripts/dev.ts` + `build.ts` — 扫描 `FEATURE_*` 环境变量注入 Bun `--feature`
+- `cli.tsx` — 启动时打印已启用的 feature
+- `permissionSetup.ts` — `AUTO_MODE_ENABLED_DEFAULT` 由 `feature('TRANSCRIPT_CLASSIFIER')` 决定，开 feature 即开 auto mode
+- `docs/safety/auto-mode.mdx` — 补充 prompt 模板章节
+
+**用法：** `FEATURE_TRANSCRIPT_CLASSIFIER=1 bun run dev`
+
+**注意：** prompt 模板为重建产物。
+
+---
+
+## USER_TYPE=ant TUI 修复 (2026-04-02)
+
+`global.d.ts` 声明的全局函数在反编译版本运行时未定义，导致 `USER_TYPE=ant` 时 TUI 崩溃。
+
+修复方式：显式 import / 本地 stub / 全局 stub / 新建 stub 文件。涉及文件：
+`cli.tsx`, `model.ts`, `context.ts`, `effort.ts`, `thinking.ts`, `undercover.ts`, `Spinner.tsx`, `AntModelSwitchCallout.tsx`(新建), `UndercoverAutoCallout.tsx`(新建)
+
+注意：
+- `USER_TYPE=ant` 启用 alt-screen 全屏模式，中心区域满屏是预期行为
+- `global.d.ts` 中剩余未 stub 的全局函数（`getAntModels` 等）遇到 `X is not defined` 时按同样模式处理
+
+---
+
+## /login 添加 Custom Platform 选项 (2026-04-03)
+
+在 `/login` 命令的登录方式选择列表中新增 "Custom Platform" 选项（位于第一位），允许用户直接在终端配置第三方 API 兼容服务的 Base URL、API Key 和三种模型映射，保存到 `~/.claude/settings.json`。
+
+**修改文件：**
+
+| 文件 | 变更 |
+|------|------|
+| `src/components/ConsoleOAuthFlow.tsx` | `OAuthStatus` 类型新增 `custom_platform` state（含 `baseUrl`、`apiKey`、`haikuModel`、`sonnetModel`、`opusModel`、`activeField`）；`idle` case Select 选项新增 Custom Platform 并排第一位；新增 `custom_platform` case 渲染 5 字段表单（Tab/Shift+Tab 切换、focus 高亮、Enter 跳转/保存）；Select onChange 处理 `custom_platform` 初始状态（从 `process.env` 预填当前值）；`OAuthStatusMessageProps` 类型及调用处新增 `onDone` prop |
+| `src/components/ConsoleOAuthFlow.tsx` | 新增 `updateSettingsForSource` import |
+
+**UI 交互：**
+- 5 个字段同屏：Base URL、API Key、Haiku Model、Sonnet Model、Opus Model
+- 当前活动字段的标签用 `suggestion` 背景色 + `inverseText` 反色高亮
+- Tab / Shift+Tab 在字段间切换，各自保留输入值
+- 每个字段按 Enter 跳到下一个，最后一个字段 (Opus) 按 Enter 保存
+- 模型字段自动从 `process.env` 读取当前配置作为预填值，无值则空
+- 保存时调用 `updateSettingsForSource('userSettings', { env })` 写入 settings.json，同时更新 `process.env`
+
+**保存的 settings.json env 字段：**
+```json
+{
+  "ANTHROPIC_BASE_URL": "...",
+  "ANTHROPIC_AUTH_TOKEN": "...",
+  "ANTHROPIC_DEFAULT_HAIKU_MODEL": "...",
+  "ANTHROPIC_DEFAULT_SONNET_MODEL": "...",
+  "ANTHROPIC_DEFAULT_OPUS_MODEL": "..."
+}
+```
+
+非空字段才写入，保存后立即生效（`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

@@ -1,407 +1,241 @@
-# Claude Code V1
+# Claude Code Best V5 (CCB)
 
-Anthropic 官方 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI 工具的源码反编译/逆向还原项目。目标是将 Claude Code 大部分功能及工程化能力复现。
+[![GitHub Stars](https://img.shields.io/github/stars/claude-code-best/claude-code?style=flat-square&logo=github&color=yellow)](https://github.com/claude-code-best/claude-code/stargazers)
+[![GitHub Contributors](https://img.shields.io/github/contributors/claude-code-best/claude-code?style=flat-square&color=green)](https://github.com/claude-code-best/claude-code/graphs/contributors)
+[![GitHub Issues](https://img.shields.io/github/issues/claude-code-best/claude-code?style=flat-square&color=orange)](https://github.com/claude-code-best/claude-code/issues)
+[![GitHub License](https://img.shields.io/github/license/claude-code-best/claude-code?style=flat-square)](https://github.com/claude-code-best/claude-code/blob/main/LICENSE)
+[![Last Commit](https://img.shields.io/github/last-commit/claude-code-best/claude-code?style=flat-square&color=blue)](https://github.com/claude-code-best/claude-code/commits/main)
+[![Bun](https://img.shields.io/badge/runtime-Bun-black?style=flat-square&logo=bun)](https://bun.sh/)
+[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?style=flat-square&logo=discord)](https://discord.gg/uApuzJWGKX)
 
-> V1 会完成跑通及基本的类型检查通过; 
-> V2 会完整实现工程化配套设施; 
-> V3 会实现多层级解耦, 很多比如 UI 包, Agent 包都可以独立优化; 
-> V4 会完成大量的测试文件, 以提高稳定性
->
-> 我不知道这个项目还会存在多久, fork 不好使, git clone 或者下载 .zip 包才稳健;
-> 
-> 这个项目更新很快, 后台有 Opus 持续优化, 所以你可以提 issues, 但是 PR 暂时不会接受;
->
-> 如果你想要私人咨询服务, 那么可以发送邮件到 claude-code-best@proton.me, 备注咨询与联系方式即可; 由于后续工作非常多, 可能会忽略邮件, 半天没回复, 可以多发;
+> Which Claude do you like? The open source one is the best.
 
-## 快速开始
+牢 A (Anthropic) 官方 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 完整复原的工程化项目。虽然很难绷, 但是它叫做 CCB(踩踩背)... 而且, 我们实现了企业版或者需要登陆 Claude 账号才能使用的特性, 并在此基础上扩展了更多好玩的特性。
 
-### 环境要求
+[Peri Code](https://github.com/KonghaYao/peri)：Claude Code 兼容的 Rust Agent，多年大模型经验匠心制作，国内大模型（DeepSeek/GLM）精调，CPU/内存极致优化，在开发版/树莓派上也能跑 CC 一样的体验。
+
+[文档在这里](https://ccb.agent-aura.top/) | [留影文档在这里](./Friends.md) | [Discord 群组，群主在线答疑](https://discord.gg/uApuzJWGKX)
+
+| 特性                        | 说明                                                                                                                         | 文档                                                                                                                                      |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| **Claude 群控技术**         | Pipe IPC 多实例协作：同机 main/sub 自动编排 + LAN 跨机器零配置发现与通讯，`/pipes` 选择面板 + `Shift+↓` 交互 + 消息广播路由 | [Pipe IPC](https://ccb.agent-aura.top/docs/features/agents/uds-inbox) / [LAN](https://ccb.agent-aura.top/docs/features/agents/lan-pipes)                |
+| **ACP 协议一等一支持**      | 支持接入 Zed、Cursor 等 IDE，支持会话恢复、Skills、权限桥接                                                                  | [文档](https://ccb.agent-aura.top/docs/features/agents/acp-zed)                                                                                  |
+| **Remote Control 私有部署** | Docker 自托管远程界面, 可以手机上看 CC                                                                                       | [文档](https://ccb.agent-aura.top/docs/features/modes/remote-control-self-hosting)                                                              |
+| **Langfuse 监控**           | 企业级 Agent 监控, 可以清晰看到每次 agent loop 细节, 可以一键转化为数据集                                                    | [文档](https://ccb.agent-aura.top/docs/features/tools/langfuse-monitoring)                                                                      |
+| **Web Search**              | 内置网页搜索工具, 支持 bing 和 brave 搜索                                                                                    | [文档](https://ccb.agent-aura.top/docs/features/external/web-browser-tool)                                                                         |
+| **Poor Mode**               | 穷鬼模式，关闭记忆提取和键入建议,大幅度减少并发请求                                                                          | /poor 可以开关                                                                                                                            |
+| **Channels 频道通知**       | MCP 服务器推送外部消息到会话（飞书/Slack/Discord/微信等），`--channels plugin:name@marketplace` 启用                         | [文档](https://ccb.agent-aura.top/docs/features/external/channels)                                                                                 |
+| **自定义模型供应商**        | OpenAI/Anthropic/Gemini/Grok 兼容  (`/login`)                                                                                          | [文档](https://ccb.agent-aura.top/docs/getting-started/model-providers)                                                                        |
+| Voice Mode                  | 语音输入，支持豆包语言输入（`/voice doubao`）                                                                   | [文档](https://ccb.agent-aura.top/docs/features/external/voice-mode)                                                                               |
+| Computer Use                | 屏幕截图、键鼠控制                                                                                                           | [文档](https://ccb.agent-aura.top/docs/features/external/computer-use)                                                                             |
+| Chrome Use                  | 浏览器自动化、表单填写、数据抓取                                                                                             | [自托管](https://ccb.agent-aura.top/docs/features/external/chrome-use-mcp) [原生版](https://ccb.agent-aura.top/docs/features/external/claude-in-chrome-mcp) |
+| Sentry                      | 企业级错误追踪                                                                                                               | [文档](https://ccb.agent-aura.top/docs/internals/sentry-setup)                                                                            |
+| GrowthBook                  | 企业级特性开关                                                                                                               | [文档](https://ccb.agent-aura.top/docs/internals/growthbook-adapter)                                                                      |
+| /dream 记忆整理             | 自动整理和优化记忆文件                                                                                                       | [文档](https://ccb.agent-aura.top/docs/features/modes/auto-dream)                                                                               |
+
+- 🚀 [想要启动项目](#-快速开始源码版)
+- 🐛 [想要调试项目](#vs-code-调试)
+- 📖 [想要学习项目](#teach-me-学习项目)
+
+## ⚡ 快速开始(安装版)
+
+不用克隆仓库, 从 NPM 下载后, 直接使用
+
+```sh
+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
-- Node.js >= 18（部分依赖需要）
-- 有效的 Anthropic API Key（或 Bedrock / Vertex 凭据）
+- 📦 [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 说明就是对了
 bun run dev
 
-# 直接运行
-bun run src/entrypoints/cli.tsx
-
-# 管道模式（-p）
-echo "say hello" | bun run src/entrypoints/cli.tsx -p
-
 # 构建
 bun run build
 ```
 
-构建产物输出到 `dist/cli.js`（~25.75 MB，5326 模块）。
+构建采用 code splitting 多文件打包（`build.ts`），产物输出到 `dist/` 目录（入口 `dist/cli.js` + 约 450 个 chunk 文件）。
 
-## 能力清单
+构建出的版本 bun 和 node 都可以启动, 你 publish 到私有源可以直接启动
 
-> ✅ = 已实现  ⚠️ = 部分实现 / 条件启用  ❌ = stub / 移除 / feature flag 关闭
+如果遇到 bug 请直接提一个 issues, 我们优先解决
 
-### 核心系统
+### 👤 新人配置 /login
 
-| 能力 | 状态 | 说明 |
-|------|------|------|
-| REPL 交互界面（Ink 终端渲染） | ✅ | 主屏幕 5000+ 行，完整交互 |
-| API 通信 — Anthropic Direct | ✅ | 支持 API Key + OAuth |
-| API 通信 — AWS Bedrock | ✅ | 支持凭据刷新、Bearer Token |
-| API 通信 — Google Vertex | ✅ | 支持 GCP 凭据刷新 |
-| API 通信 — Azure Foundry | ✅ | 支持 API Key + Azure AD |
-| 流式对话与工具调用循环 (`query.ts`) | ✅ | 1700+ 行，含自动压缩、token 追踪 |
-| 会话引擎 (`QueryEngine.ts`) | ✅ | 1300+ 行，管理对话状态与归因 |
-| 上下文构建（git status / CLAUDE.md / memory） | ✅ | `context.ts` 完整实现 |
-| 权限系统（plan/auto/manual 模式） | ✅ | 6300+ 行，含 YOLO 分类器、路径验证、规则匹配 |
-| Hook 系统（pre/post tool use） | ✅ | 支持 settings.json 配置 |
-| 会话恢复 (`/resume`) | ✅ | 独立 ResumeConversation 屏幕 |
-| Doctor 诊断 (`/doctor`) | ✅ | 版本、API、插件、沙箱检查 |
-| 自动压缩 (compaction) | ✅ | auto-compact / micro-compact / API compact |
+首次运行后，在 REPL 中输入 `/login` 命令进入登录配置界面，选择 **Anthropic Compatible** 即可对接第三方 API 兼容服务（无需 Anthropic 官方账号）。
+选择 OpenAI 和 Gemini 对应的栏目都是支持相应协议的
 
-### 工具 — 始终可用
+需要填写的字段：
 
-| 工具 | 状态 | 说明 |
-|------|------|------|
-| BashTool | ✅ | Shell 执行，沙箱，权限检查 |
-| FileReadTool | ✅ | 文件 / PDF / 图片 / Notebook 读取 |
-| FileEditTool | ✅ | 字符串替换式编辑 + diff 追踪 |
-| FileWriteTool | ✅ | 文件创建 / 覆写 + diff 生成 |
-| NotebookEditTool | ✅ | Jupyter Notebook 单元格编辑 |
-| AgentTool | ✅ | 子代理派生（fork / async / background / remote） |
-| WebFetchTool | ✅ | URL 抓取 → Markdown → AI 摘要 |
-| WebSearchTool | ✅ | 网页搜索 + 域名过滤 |
-| AskUserQuestionTool | ✅ | 多问题交互提示 + 预览 |
-| SendMessageTool | ✅ | 消息发送（peers / teammates / mailbox） |
-| SkillTool | ✅ | 斜杠命令 / Skill 调用 |
-| EnterPlanModeTool | ✅ | 进入计划模式 |
-| ExitPlanModeTool (V2) | ✅ | 退出计划模式 |
-| TodoWriteTool | ✅ | Todo 列表 v1 |
-| BriefTool | ✅ | 简短消息 + 附件发送 |
-| TaskOutputTool | ✅ | 后台任务输出读取 |
-| TaskStopTool | ✅ | 后台任务停止 |
-| ListMcpResourcesTool | ✅ | MCP 资源列表 |
-| ReadMcpResourceTool | ✅ | MCP 资源读取 |
-| SyntheticOutputTool | ✅ | 非交互会话结构化输出 |
+| 📌 字段      | 📝 说明       | 💡 示例                      |
+| ------------ | ------------- | ---------------------------- |
+| 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 保存
 
-| 工具 | 状态 | 启用条件 |
-|------|------|----------|
-| GlobTool | ✅ | 未嵌入 bfs/ugrep 时启用（默认启用） |
-| GrepTool | ✅ | 同上 |
-| TaskCreateTool | ⚠️ | `isTodoV2Enabled()` 为 true 时 |
-| TaskGetTool | ⚠️ | 同上 |
-| TaskUpdateTool | ⚠️ | 同上 |
-| TaskListTool | ⚠️ | 同上 |
-| EnterWorktreeTool | ⚠️ | `isWorktreeModeEnabled()` |
-| ExitWorktreeTool | ⚠️ | 同上 |
-| TeamCreateTool | ⚠️ | `isAgentSwarmsEnabled()` |
-| TeamDeleteTool | ⚠️ | 同上 |
-| ToolSearchTool | ⚠️ | `isToolSearchEnabledOptimistic()` |
-| PowerShellTool | ⚠️ | Windows 平台检测 |
-| LSPTool | ⚠️ | `ENABLE_LSP_TOOL` 环境变量 |
-| ConfigTool | ❌ | `USER_TYPE === 'ant'`（永远为 false） |
+> ℹ️ 支持所有 Anthropic API 兼容服务（如 OpenRouter、AWS Bedrock 代理等），只要接口兼容 Messages API 即可。
 
-### 工具 — Feature Flag 关闭（全部不可用）
+## Feature Flags
 
-| 工具 | Feature Flag |
-|------|-------------|
-| SleepTool | `PROACTIVE` / `KAIROS` |
-| CronCreate/Delete/ListTool | `AGENT_TRIGGERS` |
-| RemoteTriggerTool | `AGENT_TRIGGERS_REMOTE` |
-| MonitorTool | `MONITOR_TOOL` |
-| SendUserFileTool | `KAIROS` |
-| OverflowTestTool | `OVERFLOW_TEST_TOOL` |
-| TerminalCaptureTool | `TERMINAL_PANEL` |
-| WebBrowserTool | `WEB_BROWSER_TOOL` |
-| SnipTool | `HISTORY_SNIP` |
-| WorkflowTool | `WORKFLOW_SCRIPTS` |
-| PushNotificationTool | `KAIROS` |
-| SubscribePRTool | `KAIROS_GITHUB_WEBHOOKS` |
-| ListPeersTool | `UDS_INBOX` |
-| CtxInspectTool | `CONTEXT_COLLAPSE` |
+所有功能开关通过 `FEATURE_<FLAG_NAME>=1` 环境变量启用，例如：
 
-### 工具 — Stub / 不可用
-
-| 工具 | 说明 |
-|------|------|
-| TungstenTool | ANT-ONLY stub |
-| REPLTool | ANT-ONLY，`isEnabled: () => false` |
-| SuggestBackgroundPRTool | ANT-ONLY，`isEnabled: () => false` |
-| VerifyPlanExecutionTool | 需 `CLAUDE_CODE_VERIFY_PLAN=true` 环境变量，且为 stub |
-| ReviewArtifactTool | stub，未注册到 tools.ts |
-| DiscoverSkillsTool | stub，未注册到 tools.ts |
-
-### 斜杠命令 — 可用
-
-| 命令 | 状态 | 说明 |
-|------|------|------|
-| `/add-dir` | ✅ | 添加目录 |
-| `/advisor` | ✅ | Advisor 配置 |
-| `/agents` | ✅ | 代理列表/管理 |
-| `/branch` | ✅ | 分支管理 |
-| `/btw` | ✅ | 快速备注 |
-| `/chrome` | ✅ | Chrome 集成 |
-| `/clear` | ✅ | 清屏 |
-| `/color` | ✅ | Agent 颜色 |
-| `/compact` | ✅ | 压缩对话 |
-| `/config` (`/settings`) | ✅ | 配置管理 |
-| `/context` | ✅ | 上下文信息 |
-| `/copy` | ✅ | 复制最后消息 |
-| `/cost` | ✅ | 会话费用 |
-| `/desktop` | ✅ | Claude Desktop 集成 |
-| `/diff` | ✅ | 显示 diff |
-| `/doctor` | ✅ | 健康检查 |
-| `/effort` | ✅ | 设置 effort 等级 |
-| `/exit` | ✅ | 退出 |
-| `/export` | ✅ | 导出对话 |
-| `/extra-usage` | ✅ | 额外用量信息 |
-| `/fast` | ✅ | 切换 fast 模式 |
-| `/feedback` | ✅ | 反馈 |
-| `/files` | ✅ | 已跟踪文件 |
-| `/heapdump` | ✅ | Heap dump（调试） |
-| `/help` | ✅ | 帮助 |
-| `/hooks` | ✅ | Hook 管理 |
-| `/ide` | ✅ | IDE 连接 |
-| `/init` | ✅ | 初始化项目 |
-| `/install-github-app` | ✅ | 安装 GitHub App |
-| `/install-slack-app` | ✅ | 安装 Slack App |
-| `/keybindings` | ✅ | 快捷键管理 |
-| `/login` / `/logout` | ✅ | 登录 / 登出 |
-| `/mcp` | ✅ | MCP 服务管理 |
-| `/memory` | ✅ | Memory / CLAUDE.md 管理 |
-| `/mobile` | ✅ | 移动端 QR 码 |
-| `/model` | ✅ | 模型选择 |
-| `/output-style` | ✅ | 输出风格 |
-| `/passes` | ✅ | 推荐码 |
-| `/permissions` | ✅ | 权限管理 |
-| `/plan` | ✅ | 计划模式 |
-| `/plugin` | ✅ | 插件管理 |
-| `/pr-comments` | ✅ | PR 评论 |
-| `/privacy-settings` | ✅ | 隐私设置 |
-| `/rate-limit-options` | ✅ | 限速选项 |
-| `/release-notes` | ✅ | 更新日志 |
-| `/reload-plugins` | ✅ | 重载插件 |
-| `/remote-env` | ✅ | 远程环境配置 |
-| `/rename` | ✅ | 重命名会话 |
-| `/resume` | ✅ | 恢复会话 |
-| `/review` | ✅ | 代码审查（本地） |
-| `/ultrareview` | ✅ | 云端审查 |
-| `/rewind` | ✅ | 回退对话 |
-| `/sandbox-toggle` | ✅ | 切换沙箱 |
-| `/security-review` | ✅ | 安全审查 |
-| `/session` | ✅ | 会话信息 |
-| `/skills` | ✅ | Skill 管理 |
-| `/stats` | ✅ | 会话统计 |
-| `/status` | ✅ | 状态信息 |
-| `/statusline` | ✅ | 状态栏 UI |
-| `/stickers` | ✅ | 贴纸 |
-| `/tasks` | ✅ | 任务管理 |
-| `/theme` | ✅ | 终端主题 |
-| `/think-back` | ✅ | 年度回顾 |
-| `/upgrade` | ✅ | 升级 CLI |
-| `/usage` | ✅ | 用量信息 |
-| `/insights` | ✅ | 使用分析报告 |
-| `/vim` | ✅ | Vim 模式 |
-
-### 斜杠命令 — Feature Flag 关闭
-
-| 命令 | Feature Flag |
-|------|-------------|
-| `/voice` | `VOICE_MODE` |
-| `/proactive` | `PROACTIVE` / `KAIROS` |
-| `/brief` | `KAIROS` / `KAIROS_BRIEF` |
-| `/assistant` | `KAIROS` |
-| `/bridge` | `BRIDGE_MODE` |
-| `/remote-control-server` | `DAEMON` + `BRIDGE_MODE` |
-| `/force-snip` | `HISTORY_SNIP` |
-| `/workflows` | `WORKFLOW_SCRIPTS` |
-| `/web-setup` | `CCR_REMOTE_SETUP` |
-| `/subscribe-pr` | `KAIROS_GITHUB_WEBHOOKS` |
-| `/ultraplan` | `ULTRAPLAN` |
-| `/torch` | `TORCH` |
-| `/peers` | `UDS_INBOX` |
-| `/fork` | `FORK_SUBAGENT` |
-| `/buddy` | `BUDDY` |
-
-### 斜杠命令 — ANT-ONLY（不可用）
-
-`/tag` `/backfill-sessions` `/break-cache` `/bughunter` `/commit` `/commit-push-pr` `/ctx_viz` `/good-claude` `/issue` `/init-verifiers` `/mock-limits` `/bridge-kick` `/version` `/reset-limits` `/onboarding` `/share` `/summary` `/teleport` `/ant-trace` `/perf-issue` `/env` `/oauth-refresh` `/debug-tool-call` `/agents-platform` `/autofix-pr`
-
-### CLI 子命令
-
-| 子命令 | 状态 | 说明 |
-|--------|------|------|
-| `claude`（默认） | ✅ | 主 REPL / 交互 / print 模式 |
-| `claude mcp serve/add/remove/list/get/...` | ✅ | MCP 服务管理（7 个子命令） |
-| `claude auth login/status/logout` | ✅ | 认证管理 |
-| `claude plugin validate/list/install/...` | ✅ | 插件管理（7 个子命令） |
-| `claude setup-token` | ✅ | 长效 Token 配置 |
-| `claude agents` | ✅ | 代理列表 |
-| `claude doctor` | ✅ | 健康检查 |
-| `claude update` / `upgrade` | ✅ | 自动更新 |
-| `claude install [target]` | ✅ | Native 安装 |
-| `claude server` | ❌ | `DIRECT_CONNECT` flag |
-| `claude ssh <host>` | ❌ | `SSH_REMOTE` flag |
-| `claude open <cc-url>` | ❌ | `DIRECT_CONNECT` flag |
-| `claude auto-mode` | ❌ | `TRANSCRIPT_CLASSIFIER` flag |
-| `claude remote-control` | ❌ | `BRIDGE_MODE` + `DAEMON` flag |
-| `claude assistant` | ❌ | `KAIROS` flag |
-| `claude up/rollback/log/error/export/task/completion` | ❌ | ANT-ONLY |
-
-### 服务层
-
-| 服务 | 状态 | 说明 |
-|------|------|------|
-| API 客户端 (`services/api/`) | ✅ | 3400+ 行，4 个 provider |
-| MCP (`services/mcp/`) | ✅ | 24 个文件，12000+ 行 |
-| OAuth (`services/oauth/`) | ✅ | 完整 OAuth 流程 |
-| 插件 (`services/plugins/`) | ✅ | 基础设施完整，无内置插件 |
-| LSP (`services/lsp/`) | ⚠️ | 实现存在，默认关闭 |
-| 压缩 (`services/compact/`) | ✅ | auto / micro / API 压缩 |
-| Hook 系统 (`services/tools/toolHooks.ts`) | ✅ | pre/post tool use hooks |
-| 会话记忆 (`services/SessionMemory/`) | ✅ | 会话记忆管理 |
-| 记忆提取 (`services/extractMemories/`) | ✅ | 自动记忆提取 |
-| Skill 搜索 (`services/skillSearch/`) | ✅ | 本地/远程 skill 搜索 |
-| 策略限制 (`services/policyLimits/`) | ✅ | 策略限制执行 |
-| 分析 / GrowthBook / Sentry | ⚠️ | 框架存在，实际 sink 为空 |
-| Voice (`services/voice.ts`) | ❌ | `VOICE_MODE` flag 关闭 |
-
-### 内部包 (`packages/`)
-
-| 包 | 状态 | 说明 |
-|------|------|------|
-| `color-diff-napi` | ✅ | 997 行完整 TypeScript 实现（语法高亮 diff） |
-| `audio-capture-napi` | ❌ | stub，`isNativeAudioAvailable()` 返回 false |
-| `image-processor-napi` | ❌ | stub，`getNativeModule()` 返回 null |
-| `modifiers-napi` | ❌ | stub，`isModifierPressed()` 返回 false |
-| `url-handler-napi` | ❌ | stub，`waitForUrlEvent()` 返回 null |
-| `@ant/claude-for-chrome-mcp` | ❌ | stub，`createServer()` 返回 null |
-| `@ant/computer-use-mcp` | ❌ | stub，`buildTools()` 返回 [] |
-| `@ant/computer-use-input` | ❌ | stub，仅类型声明 |
-| `@ant/computer-use-swift` | ❌ | stub，仅类型声明 |
-
-### Feature Flags（30 个，全部返回 `false`）
-
-`ABLATION_BASELINE` `AGENT_MEMORY_SNAPSHOT` `BG_SESSIONS` `BRIDGE_MODE` `BUDDY` `CCR_MIRROR` `CCR_REMOTE_SETUP` `CHICAGO_MCP` `COORDINATOR_MODE` `DAEMON` `DIRECT_CONNECT` `EXPERIMENTAL_SKILL_SEARCH` `FORK_SUBAGENT` `HARD_FAIL` `HISTORY_SNIP` `KAIROS` `KAIROS_BRIEF` `KAIROS_CHANNELS` `KAIROS_GITHUB_WEBHOOKS` `LODESTONE` `MCP_SKILLS` `PROACTIVE` `SSH_REMOTE` `TORCH` `TRANSCRIPT_CLASSIFIER` `UDS_INBOX` `ULTRAPLAN` `UPLOAD_USER_SETTINGS` `VOICE_MODE` `WEB_BROWSER_TOOL` `WORKFLOW_SCRIPTS`
-
-
-## 项目结构
-
-```
-claude-code/
-├── src/
-│   ├── entrypoints/
-│   │   ├── cli.tsx          # 入口文件（含 MACRO/feature polyfill）
-│   │   └── sdk/             # SDK 子模块 stub
-│   ├── main.tsx             # 主 CLI 逻辑（Commander 定义）
-│   └── types/
-│       ├── global.d.ts      # 全局变量/宏声明
-│       └── internal-modules.d.ts  # 内部 npm 包类型声明
-├── packages/                # Monorepo workspace 包
-│   ├── color-diff-napi/     # 完整实现（终端 color diff）
-│   ├── modifiers-napi/      # stub（macOS 修饰键检测）
-│   ├── audio-capture-napi/  # stub
-│   ├── image-processor-napi/# stub
-│   ├── url-handler-napi/    # stub
-│   └── @ant/               # Anthropic 内部包 stub
-│       ├── claude-for-chrome-mcp/
-│       ├── computer-use-mcp/
-│       ├── computer-use-input/
-│       └── computer-use-swift/
-├── scripts/                 # 自动化 stub 生成脚本
-├── dist/                    # 构建输出
-└── package.json             # Bun workspaces monorepo 配置
+```bash
+FEATURE_BUDDY=1 FEATURE_FORK_SUBAGENT=1 bun run dev
 ```
 
-## 技术说明
+各 Feature 的详细说明见 [`docs/features/`](docs/features/) 目录，欢迎投稿补充。
 
-### 运行时 Polyfill
+## VS Code 调试
 
-入口文件 `src/entrypoints/cli.tsx` 顶部注入了必要的 polyfill：
+TUI (REPL) 模式需要真实终端，无法直接通过 VS Code launch 启动调试。使用 **attach 模式**：
 
-- `feature()` — 所有 feature flag 返回 `false`，跳过未实现分支
-- `globalThis.MACRO` — 模拟构建时宏注入（VERSION 等）
+### 步骤
 
-### Monorepo
+1. **终端启动 inspect 服务**：
 
-项目采用 Bun workspaces 管理内部包。原先手工放在 `node_modules/` 下的 stub 已统一迁入 `packages/`，通过 `workspace:*` 解析。
+   ```bash
+   bun run dev:inspect
+   ```
 
-## Feature Flags 详解
+   会输出类似 `ws://localhost:8888/xxxxxxxx` 的地址。
+2. **VS Code 附着调试器**：
 
-原版 Claude Code 通过 `bun:bundle` 的 `feature()` 在构建时注入 feature flag，由 GrowthBook 等 A/B 实验平台控制灰度发布。本项目中 `feature()` 被 polyfill 为始终返回 `false`，因此以下 30 个 flag 全部关闭。
+   - 在 `src/` 文件中打断点
+   - F5 → 选择 **"Attach to Bun (TUI debug)"**
 
-### 自主 Agent
+## Teach Me 学习项目
 
-| Flag | 用途 |
-|------|------|
-| `KAIROS` | Assistant 模式 — 长期运行的自主 Agent（含 brief、push 通知、文件发送） |
-| `KAIROS_BRIEF` | Kairos Brief — 向用户发送简报摘要 |
-| `KAIROS_CHANNELS` | Kairos 频道 — 多频道通信 |
-| `KAIROS_GITHUB_WEBHOOKS` | GitHub Webhook 订阅 — PR 事件实时推送给 Agent |
-| `PROACTIVE` | 主动模式 — Agent 主动执行任务，含 SleepTool 定时唤醒 |
-| `COORDINATOR_MODE` | 协调器模式 — 多 Agent 编排调度 |
-| `BUDDY` | Buddy 配对编程功能 |
-| `FORK_SUBAGENT` | Fork 子代理 — 从当前会话分叉出独立子代理 |
+我们新加了一个 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
+```
 
-| Flag | 用途 |
-|------|------|
-| `BRIDGE_MODE` | 远程控制桥接 — 允许外部客户端远程操控 Claude Code |
-| `DAEMON` | 守护进程 — 后台常驻服务，支持 worker 和 supervisor |
-| `BG_SESSIONS` | 后台会话 — `ps`/`logs`/`attach`/`kill`/`--bg` 等后台进程管理 |
-| `SSH_REMOTE` | SSH 远程 — `claude ssh <host>` 连接远程主机 |
-| `DIRECT_CONNECT` | 直连模式 — `cc://` URL 协议、server 命令、`open` 命令 |
-| `CCR_REMOTE_SETUP` | 网页端远程配置 — 通过浏览器配置 Claude Code |
-| `CCR_MIRROR` | Claude Code Runtime 镜像 — 会话状态同步/复制 |
+### 它能做什么
 
-### 通信
+- **诊断水平** — 自动评估你对相关概念的掌握程度，跳过已知的、聚焦薄弱的
+- **构建学习路径** — 将主题拆解为 5-15 个原子概念，按依赖排序逐步推进
+- **苏格拉底式提问** — 用选项引导思考，而非直接给答案
+- **错误概念追踪** — 发现并纠正深层误解
+- **断点续学** — `--resume` 从上次进度继续
 
-| Flag | 用途 |
-|------|------|
-| `UDS_INBOX` | Unix Domain Socket 收件箱 — Agent 间本地通信（`/peers`） |
+### 学习记录
 
-### 增强工具
+学习进度保存在 `.claude/skills/teach-me/` 目录下，支持跨主题学习者档案。
 
-| Flag | 用途 |
-|------|------|
-| `CHICAGO_MCP` | Computer Use MCP — 计算机操作（屏幕截图、鼠标键盘控制） |
-| `WEB_BROWSER_TOOL` | 网页浏览器工具 — 在终端内嵌浏览器交互 |
-| `VOICE_MODE` | 语音模式 — 语音输入输出，麦克风 push-to-talk |
-| `WORKFLOW_SCRIPTS` | 工作流脚本 — 用户自定义自动化工作流 |
-| `MCP_SKILLS` | 基于 MCP 的 Skill 加载机制 |
+## 相关文档及网站
 
-### 对话管理
+- **在线文档（Mintlify）**: [ccb.agent-aura.top](https://ccb.agent-aura.top/) — 文档源码位于 [`docs/`](docs/) 目录，欢迎投稿 PR
+- **DeepWiki**: [https://deepwiki.com/claude-code-best/claude-code](https://deepwiki.com/claude-code-best/claude-code)
 
-| Flag | 用途 |
-|------|------|
-| `HISTORY_SNIP` | 历史裁剪 — 手动裁剪对话历史中的片段（`/force-snip`） |
-| `ULTRAPLAN` | 超级计划 — 远程 Agent 协作的大规模规划功能 |
-| `AGENT_MEMORY_SNAPSHOT` | Agent 运行时的记忆快照功能 |
+## Contributors
 
-### 基础设施 / 实验
+<a href="https://github.com/claude-code-best/claude-code/graphs/contributors">
+  <img src="contributors.svg" alt="Contributors" />
+</a>
 
-| Flag | 用途 |
-|------|------|
-| `ABLATION_BASELINE` | 科学实验 — 基线消融测试，用于 A/B 实验对照组 |
-| `HARD_FAIL` | 硬失败模式 — 遇错直接中断而非降级 |
-| `TRANSCRIPT_CLASSIFIER` | 对话分类器 — `auto-mode` 命令，自动分析和分类对话记录 |
-| `UPLOAD_USER_SETTINGS` | 设置同步上传 — 将本地配置同步到云端 |
-| `LODESTONE` | 深度链接协议处理器 — 从外部应用跳转到 Claude Code 指定位置 |
-| `EXPERIMENTAL_SKILL_SEARCH` | 实验性 Skill 搜索索引 |
-| `TORCH` | Torch 功能（具体用途未知，可能是某种高亮/追踪机制） |
+## Star History
+
+<a href="https://www.star-history.com/?repos=claude-code-best%2Fclaude-code&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=claude-code-best/claude-code&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=claude-code-best/claude-code&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/image?repos=claude-code-best/claude-code&type=date&legend=top-left" />
+ </picture>
+</a>
+
+## 致谢
+
+- [doubaoime-asr](https://github.com/starccy/doubaoime-asr) — 豆包 ASR 语音识别 SDK，为 Voice Mode 提供无需 Anthropic OAuth 的语音输入方案
 
 ## 许可证
 

README_EN.md

@@ -0,0 +1,211 @@
+# Claude Code Best V5 (CCB)
+
+[![GitHub Stars](https://img.shields.io/github/stars/claude-code-best/claude-code?style=flat-square&logo=github&color=yellow)](https://github.com/claude-code-best/claude-code/stargazers)
+[![GitHub Contributors](https://img.shields.io/github/contributors/claude-code-best/claude-code?style=flat-square&color=green)](https://github.com/claude-code-best/claude-code/graphs/contributors)
+[![GitHub Issues](https://img.shields.io/github/issues/claude-code-best/claude-code?style=flat-square&color=orange)](https://github.com/claude-code-best/claude-code/issues)
+[![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/)
+
+> Which Claude do you like? The open source one is the best.
+
+A reverse-engineered / decompiled source restoration of Anthropic's official [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI tool. The goal is to reproduce most of Claude Code's functionality and engineering capabilities. It's abbreviated as CCB.
+
+[Documentation (Chinese)](https://ccb.agent-aura.top/) — PR contributions welcome.
+
+Sponsor placeholder.
+
+- [x] v1: Basic runability and type checking pass
+- [x] V2: Complete engineering infrastructure
+  - [ ] Biome formatting may not be implemented first to avoid code conflicts
+  - [x] Build pipeline complete, output runnable on both Node.js and Bun
+- [x] V3: Extensive documentation and documentation site improvements
+- [x] V4: Large-scale test suite for improved stability
+  - [x] Buddy pet feature restored [Docs](https://ccb.agent-aura.top/docs/features/buddy)
+  - [x] Auto Mode restored [Docs](https://ccb.agent-aura.top/docs/safety/auto-mode)
+  - [x] All features now configurable via environment variables instead of `bun --feature`
+- [x] V5: Enterprise-grade monitoring/reporting, missing tools补全, restrictions removed
+  - [x] Removed anti-distillation code
+  - [x] Web search capability (using Bing) [Docs](https://ccb.agent-aura.top/docs/features/web-browser-tool)
+  - [x] Debug mode support [Docs](https://ccb.agent-aura.top/docs/features/debug-mode)
+  - [x] Disabled auto-updates
+  - [x] Custom Sentry error reporting support [Docs](https://ccb.agent-aura.top/docs/internals/sentry-setup)
+  - [x] Custom GrowthBook support (GB is open source — configure your own feature flag platform) [Docs](https://ccb.agent-aura.top/docs/internals/growthbook-adapter)
+  - [x] Custom login mode — configure Claude models your way
+- [ ] V6: Large-scale refactoring, full modular packaging
+  - [ ] V6 will be a new branch; main branch will be archived as a historical version
+
+> I don't know how long this project will survive. Star + Fork + git clone + .zip is the safest bet.
+>
+> This project updates rapidly — Opus continuously optimizes in the background, with new changes almost every few hours.
+>
+> Claude has burned over $1000, out of budget, switching to GLM to continue; @zai-org GLM 5.1 is quite capable.
+
+## Quick Start
+
+### Prerequisites
+
+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
+```
+
+### Run
+
+```bash
+# Dev mode — if you see version 888, it's working
+bun run dev
+
+# Build
+bun run build
+```
+
+The build uses code splitting (`build.ts`), outputting to `dist/` (entry `dist/cli.js` + ~450 chunk files).
+
+The build output runs on both Bun and Node.js — you can publish to a private registry and run directly.
+
+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 **Anthropic Compatible** to connect to third-party API-compatible services (no Anthropic account required).
+
+Fields to fill in:
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| Base URL | API service URL | `https://api.example.com/v1` |
+| API Key | Authentication key | `sk-xxx` |
+| Haiku Model | Fast model ID | `claude-haiku-4-5-20251001` |
+| Sonnet Model | Balanced model ID | `claude-sonnet-4-6` |
+| Opus Model | High-performance model ID | `claude-opus-4-6` |
+
+- **Tab / Shift+Tab** to switch fields, **Enter** to confirm and move to the next, press Enter on the last field to save
+- Model fields auto-fill from current environment variables
+- Configuration saves to `~/.claude/settings.json` under the `env` key, effective immediately
+
+You can also edit `~/.claude/settings.json` directly:
+
+```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"
+  }
+}
+```
+
+> Supports all Anthropic API-compatible services (e.g., OpenRouter, AWS Bedrock proxies, etc.) as long as the interface is compatible with the Messages API.
+
+## Feature Flags
+
+All feature toggles are enabled via `FEATURE_<FLAG_NAME>=1` environment variables, for example:
+
+```bash
+FEATURE_BUDDY=1 FEATURE_FORK_SUBAGENT=1 bun run dev
+```
+
+See [`docs/features/`](docs/features/) for detailed descriptions of each feature. Contributions welcome.
+
+## VS Code Debugging
+
+The TUI (REPL) mode requires a real terminal and cannot be launched directly via VS Code's launch config. Use **attach mode**:
+
+### Steps
+
+1. **Start inspect server in terminal**:
+   ```bash
+   bun run dev:inspect
+   ```
+   This outputs an address like `ws://localhost:8888/xxxxxxxx`.
+
+2. **Attach debugger from VS Code**:
+   - Set breakpoints in `src/` files
+   - Press F5 → select **"Attach to Bun (TUI debug)"**
+
+## 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
+
+## 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" />
+</a>
+
+## Star History
+
+<a href="https://www.star-history.com/?repos=claude-code-best%2Fclaude-code&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=claude-code-best%2Fclaude-code&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=claude-code-best%2Fclaude-code&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/image?repos=claude-code-best%2Fclaude-code&type=date&legend=top-left" />
+ </picture>
+</a>
+
+## License
+
+This project is for educational and research purposes only. All rights to Claude Code belong to [Anthropic](https://www.anthropic.com/).

RECORD.md

@@ -1,218 +0,0 @@
-# Claude Code 项目运行记录
-
-> 项目: `/Users/konghayao/code/ai/claude-code`
-> 日期: 2026-03-31
-> 包管理器: bun
-
----
-
-## 一、项目目标
-
-**将 claude-code 项目运行起来，必要时可以删减次级能力。**
-
-这是 Anthropic 官方 Claude Code CLI 工具的源码反编译/逆向还原项目。
-
-### 核心保留能力
-
-- API 通信（Anthropic SDK / Bedrock / Vertex）
-- Bash/FileRead/FileWrite/FileEdit 等核心工具
-- REPL 交互界面（ink 终端渲染）
-- 对话历史与会话管理
-- 权限系统（基础）
-- Agent/子代理系统
-
-### 已删减的次级能力
-
-| 模块 | 处理方式 |
-|------|----------|
-| Computer Use (`@ant/computer-use-*`) | stub |
-| Claude for Chrome (`@ant/claude-for-chrome-mcp`) | stub |
-| Magic Docs / Voice Mode / LSP Server | 移除 |
-| Analytics / GrowthBook / Sentry | 空实现 |
-| Plugins/Marketplace / Desktop Upsell | 移除 |
-| Ultraplan / Tungsten / Auto Dream | 移除 |
-| MCP OAuth/IDP | 简化 |
-| DAEMON / BRIDGE / BG_SESSIONS / TEMPLATES 等 | feature flag 关闭 |
-
----
-
-## 二、当前状态：Dev 模式已可运行
-
-```bash
-# dev 运行
-bun run dev
-# 直接运行
-bun run src/entrypoints/cli.tsx
-# 测试 -p 模式
-echo "say hello" | bun run src/entrypoints/cli.tsx -p
-# 构建
-bun run build
-```
-
-| 测试 | 结果 |
-|------|------|
-| `--version` | `2.1.87 (Claude Code)` |
-| `--help` | 完整帮助信息输出 |
-| `-p` 模式 | 成功调用 API 返回响应 |
-
-### TS 类型错误说明
-
-~~仍有 ~1341 个 tsc 错误~~ → 经过系统性类型修复，已降至 **~294 个**（减少 78%）。剩余错误分散在小文件中，均为反编译产生的源码级类型问题（`unknown`/`never`/`{}`），**不影响 Bun 运行时**。
-
----
-
-## 三、关键修复记录
-
-### 3.1 自动化 stub 生成
-
-通过 3 个脚本自动处理了缺失模块问题：
-- `scripts/create-type-stubs.mjs` — 生成 1206 个 stub 文件
-- `scripts/fix-default-stubs.mjs` — 修复 120 个默认导出 stub
-- `scripts/fix-missing-exports.mjs` — 补全 81 个模块的 161 个缺失导出
-
-### 3.2 手动类型修复
-
-- `src/types/global.d.ts` — MACRO 宏、内部函数声明
-- `src/types/internal-modules.d.ts` — `@ant/*` 等私有包类型声明
-- `src/entrypoints/sdk/` — 6 个 SDK 子模块 stub
-- 泛型类型修复（DeepImmutable、AttachmentMessage 等）
-- 4 个 `export const default` 非法语法修复
-
-### 3.3 运行时修复
-
-**Commander 非法短标志**：`-d2e, --debug-to-stderr` → `--debug-to-stderr`（反编译错误）
-
-**`bun:bundle` 运行时 Polyfill**（`src/entrypoints/cli.tsx` 顶部）：
-```typescript
-const feature = (_name: string) => false;  // 所有 feature flag 分支被跳过
-(globalThis as any).MACRO = { VERSION: "2.1.87", ... };  // 绕过版本检查
-```
-
----
-
-## 四、关键文件清单
-
-| 文件 | 用途 |
-|------|------|
-| `src/entrypoints/cli.tsx` | 入口文件（含 MACRO/feature polyfill） |
-| `src/main.tsx` | 主 CLI 逻辑（Commander 定义） |
-| `src/types/global.d.ts` | 全局变量/宏声明 |
-| `src/types/internal-modules.d.ts` | 内部 npm 包类型声明 |
-| `src/entrypoints/sdk/*.ts` | SDK 类型 stub |
-| `src/types/message.ts` | Message 系列类型 stub |
-| `scripts/create-type-stubs.mjs` | 自动 stub 生成脚本 |
-| `scripts/fix-default-stubs.mjs` | 修复默认导出 stub |
-| `scripts/fix-missing-exports.mjs` | 补全缺失导出 |
-
----
-
-## 五、Monorepo 改造（2026-03-31）
-
-### 5.1 背景
-
-`color-diff-napi` 原先是手工放在 `node_modules/` 下的 stub 文件，导出的是普通对象而非 class，导致 `new ColorDiff(...)` 报错：
-```
-ERROR Object is not a constructor (evaluating 'new ColorDiff(patch, firstLine, filePath, fileContent)')
-```
-同时 `@ant/*`、其他 `*-napi` 包也只有 `declare module` 类型声明，无运行时实现。
-
-### 5.2 方案
-
-将项目改造为 **Bun workspaces monorepo**，所有内部包统一放在 `packages/` 下，通过 `workspace:*` 依赖解析。
-
-### 5.3 创建的 workspace 包
-
-| 包名 | 路径 | 类型 |
-|------|------|------|
-| `color-diff-napi` | `packages/color-diff-napi/` | 完整实现（~1000行 TS，从 `src/native-ts/color-diff/` 移入） |
-| `modifiers-napi` | `packages/modifiers-napi/` | stub（macOS 修饰键检测） |
-| `audio-capture-napi` | `packages/audio-capture-napi/` | stub |
-| `image-processor-napi` | `packages/image-processor-napi/` | stub |
-| `url-handler-napi` | `packages/url-handler-napi/` | stub |
-| `@ant/claude-for-chrome-mcp` | `packages/@ant/claude-for-chrome-mcp/` | stub |
-| `@ant/computer-use-mcp` | `packages/@ant/computer-use-mcp/` | stub（含 subpath exports: sentinelApps, types） |
-| `@ant/computer-use-input` | `packages/@ant/computer-use-input/` | stub |
-| `@ant/computer-use-swift` | `packages/@ant/computer-use-swift/` | stub |
-
-### 5.4 新增的 npm 依赖
-
-| 包名 | 原因 |
-|------|------|
-| `@opentelemetry/semantic-conventions` | 构建报错缺失 |
-| `fflate` | `src/utils/dxt/zip.ts` 动态 import |
-| `vscode-jsonrpc` | `src/services/lsp/LSPClient.ts` import |
-| `@aws-sdk/credential-provider-node` | `src/utils/proxy.ts` 动态 import |
-
-### 5.5 关键变更
-
-- `package.json`：添加 `workspaces`，添加所有 workspace 包和缺失 npm 依赖
-- `src/types/internal-modules.d.ts`：删除已移入 monorepo 的 `declare module` 块，仅保留 `bun:bundle`、`bun:ffi`、`@anthropic-ai/mcpb`
-- `src/native-ts/color-diff/` → `packages/color-diff-napi/src/`：移动并内联了对 `stringWidth` 和 `logError` 的依赖
-- 删除 `node_modules/color-diff-napi/` 手工 stub
-
-### 5.6 构建验证
-
-```
-$ bun run build
-Bundled 5326 modules in 491ms
-  cli.js  25.74 MB  (entry point)
-```
-
----
-
-## 六、系统性类型修复（2026-03-31）
-
-### 6.1 背景
-
-反编译产生的源码存在 ~1341 个 tsc 类型错误，主要成因：
-- `unknown` 类型上的属性访问（714 个，占 54%）
-- 类型赋值不兼容（212 个）
-- 参数类型不匹配（140 个）
-- 不可能的字面量比较（106 个，如 `"external" === 'ant'`）
-
-### 6.2 修复策略
-
-通过 4 轮并行 agent（每轮 7 个）系统性修复，**从 1341 降至 ~294**（减少 78%）。
-
-#### 根因修复（影响面最大）
-
-| 修复 | 影响 |
-|------|------|
-| `useAppState<R>` 添加泛型签名 (`AppState.tsx`) | 消除全局大量 `unknown` 返回值 |
-| `Message` 类型重构 (`message.ts`) | content 改为 `string \| ContentBlockParam[] \| ContentBlock[]`；添加 `MessageType` 扩展联合；`GroupedToolUseMessage`/`CollapsedReadSearchGroup` 结构化 |
-| `SDKAssistantMessageError` 命名冲突修复 (`coreTypes.generated.ts`) | 解决 37 个 errors.ts 类型错误 |
-| SDK 消息类型增强 (`coreTypes.generated.ts`) | `SDKAssistantMessage`/`SDKUserMessage` 等添加具体字段声明 |
-| `NonNullableUsage` 扩展 (`sdkUtilityTypes.ts`) | 添加 snake_case 属性声明 |
-
-#### 批量模式修复
-
-| 模式 | 修复方式 | 数量 |
-|------|----------|------|
-| `"external" === 'ant'` 编译常量比较 | `("external" as string) === 'ant'` | ~60 处 |
-| `unknown` 属性访问 | 精确类型断言（`as SomeType`） | ~400 处 |
-| `message.content` union 无法调用数组方法 | `Array.isArray()` 守卫 | ~80 处 |
-| stub 包缺失方法/类型 | 补全 stub 类型声明 | ~15 个包 |
-
-#### Stub 包类型补全
-
-| 包 | 补全内容 |
-|----|----------|
-| `@ant/computer-use-swift` | `ComputerUseAPI` 完整接口（apps/display/screenshot） |
-| `@ant/computer-use-input` | `ComputerUseInputAPI` 完整接口 |
-| `audio-capture-napi` | 4 个函数签名 |
-
-### 6.3 修复的关键文件
-
-| 文件 | 修复错误数 |
-|------|-----------|
-| `src/screens/REPL.tsx` | ~100 |
-| `src/utils/hooks.ts` | ~81 |
-| `src/utils/sessionStorage.ts` | ~58 |
-| `src/components/PromptInput/` | ~45 |
-| `src/services/api/errors.ts` | ~37 |
-| `src/utils/computerUse/executor.ts` | ~36 |
-| `src/utils/messages.ts` | ~83 |
-| `src/QueryEngine.ts` | ~39 |
-| `src/services/api/claude.ts` | ~35 |
-| `src/cli/print.ts` + `structuredIO.ts` | ~46 |
-| 其他 ~50 个文件 | ~487 |

SECURITY.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## Supported Versions
+
+Use this section to tell people about which versions of your project are
+currently being supported with security updates.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 5.1.x   | :white_check_mark: |
+| 5.0.x   | :x:                |
+| 4.0.x   | :white_check_mark: |
+| < 4.0   | :x:                |
+
+## Reporting a Vulnerability
+
+Use this section to tell people how to report a vulnerability.
+
+Tell them where to go, how often they can expect to get an update on a
+reported vulnerability, what to expect if the vulnerability is accepted or
+declined, etc.

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

@@ -0,0 +1,108 @@
+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'
+
+// Step 1: Clean output directory
+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])]
+
+// Step 2: Bundle with splitting
+const result = await Bun.build({
+  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)
+}
+
+// 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);`
+
+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++
+  }
+}
+
+// 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 import.meta.require, ${bunPatched} for Bun destructure)`,
+)
+
+// Step 4: Copy native .node addon files (audio-capture) and vendored binaries (ripgrep)
+const audioCaptureDir = join(outdir, 'vendor', 'audio-capture')
+await cp('vendor/audio-capture', audioCaptureDir, { recursive: true })
+console.log(`Copied vendor/audio-capture/ → ${audioCaptureDir}/`)
+
+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/agent/coordinator-and-swarm.mdx

@@ -1,58 +0,0 @@
----
-title: "协调者与蜂群"
-description: "从单兵作战到团队协作——多 Agent 的高级编排模式"
----
-
-{/* 本章目标：介绍 Coordinator Mode 和 Agent Swarms */}
-
-## 两种协作模式
-
-子 Agent 是"临时帮手"——主 Agent 派出去做一件事就回来。对于更复杂的协作需求，Claude Code 提供了两种高级模式：
-
-## Coordinator Mode：一个指挥，多个执行
-
-就像一个团队 leader 带着几个开发者：
-
-- **Coordinator**（协调者）：负责理解需求、拆解任务、分配工作、汇总结果
-- **Workers**（执行者）：各自领取任务独立执行，通过邮箱向 Coordinator 汇报
-
-```
-        ┌─── Worker A (重构 API)
-        │
-Coordinator ──┼─── Worker B (更新测试)
-        │
-        └─── Worker C (更新文档)
-```
-
-Coordinator 不自己写代码，它的职责是**编排**——确保所有 Worker 的工作能拼合在一起。
-
-## Agent Swarms：蜂群式协作
-
-比 Coordinator 更松散的协作模式：
-
-- 多个 Agent 以对等身份同时工作
-- 没有中心化的指挥者
-- 通过消息邮箱互相通信和协调
-- 适合"各自负责一块、偶尔需要沟通"的场景
-
-## Teammate 机制
-
-进程内的"队友"——一种更轻量的协作方式：
-
-- 在同一个进程内运行，共享部分基础设施状态
-- 有独立的对话上下文和工具权限
-- 适合"我需要一个搭档帮忙看看这段代码"的场景
-
-## 任务类型
-
-支撑多 Agent 协作的是丰富的任务类型：
-
-| 任务类型 | 用途 |
-|----------|------|
-| **LocalAgentTask** | 本地子 Agent 任务 |
-| **LocalShellTask** | 后台 shell 命令 |
-| **InProcessTeammateTask** | 进程内队友 |
-| **RemoteAgentTask** | 远程 Agent |
-| **DreamTask** | 后台自主任务 |
-
-每种任务类型都有自己的生命周期管理、状态追踪和通信方式。

docs/agent/sub-agents.mdx

@@ -1,69 +0,0 @@
----
-title: "子 Agent：分身术"
-description: "当一个 AI 不够用时，它会召唤更多的自己"
----
-
-{/* 本章目标：解释子 Agent 机制的设计和应用场景 */}
-
-## 为什么需要子 Agent
-
-有些任务太大，一个 AI 实例忙不过来：
-
-- "在 5 个不同的文件中分别找到并修复同类 bug"
-- "一边重构后端 API，一边更新前端调用"
-- "研究这个库的用法，同时修改我们的代码"
-
-## 分身术的运作方式
-
-Claude Code 中的 Agent 工具让 AI 能够**启动另一个 AI 实例**来处理子任务：
-
-<Steps>
-  <Step title="主 Agent 分析任务">
-    主 Agent 判断任务可以被拆解为独立的子任务
-  </Step>
-  <Step title="启动子 Agent">
-    通过 Agent 工具创建一个或多个子 Agent，每个子 Agent 收到一个清晰的子任务描述
-  </Step>
-  <Step title="并行执行">
-    多个子 Agent 可以同时工作，互不干扰
-  </Step>
-  <Step title="结果汇总">
-    子 Agent 完成后，结果返回给主 Agent，主 Agent 汇总并呈现给用户
-  </Step>
-</Steps>
-
-## 子 Agent 的边界
-
-子 Agent 不是和主 Agent 完全一样的——它有明确的能力边界：
-
-| 特性 | 主 Agent | 子 Agent |
-|------|---------|---------|
-| 可用工具 | 全部工具 | 受限子集（不能再启动子 Agent 等） |
-| 上下文 | 完整的会话历史 | 只有主 Agent 给的任务描述 |
-| 权限 | 用户设定 | 继承主 Agent 的权限，或更严格 |
-| 状态 | 可修改全局状态 | 隔离的状态空间 |
-
-## 通信方式
-
-主 Agent 和子 Agent 之间通过**消息邮箱**通信：
-
-- 主 Agent 通过 `Agent` 工具启动子 Agent
-- 子 Agent 通过 `SendMessage` 工具向主 Agent 报告进度
-- 这种松耦合的通信方式让 Agent 可以异步协作
-
-## 适用场景
-
-<CardGroup cols={2}>
-  <Card title="并行研究" icon="magnifying-glass">
-    多个子 Agent 同时搜索不同方向的信息
-  </Card>
-  <Card title="分治修改" icon="code-branch">
-    把大规模修改拆分到多个子 Agent 并行执行
-  </Card>
-  <Card title="前后台配合" icon="layer-group">
-    一个子 Agent 在后台运行测试，主 Agent 继续写代码
-  </Card>
-  <Card title="隔离实验" icon="flask">
-    在 worktree 中启动子 Agent 尝试一个方案，不影响主分支
-  </Card>
-</CardGroup>

docs/agent/worktree-isolation.mdx

@@ -1,55 +0,0 @@
----
-title: "Worktree 隔离"
-description: "给子 Agent 一个独立的工作空间，互不污染"
----
-
-{/* 本章目标：解释 git worktree 在多 Agent 协作中的作用 */}
-
-## 问题：多个 Agent 改同一份代码
-
-当多个 Agent 同时修改项目文件时，冲突在所难免：
-
-- Agent A 修改了 `config.ts`，Agent B 也在改同一个文件
-- Agent A 的测试需要某个状态，Agent B 的修改破坏了它
-- 半完成的修改混在一起，无法分辨哪些是哪个 Agent 做的
-
-## 解决方案：Git Worktree
-
-Git 原生支持 **worktree**（工作树）——在同一个仓库中创建多个独立的工作目录，每个目录在自己的分支上独立工作。
-
-Claude Code 利用这个特性为子 Agent 提供隔离的工作空间：
-
-| | 共享工作目录 | Worktree 隔离 |
-|---|---|---|
-| 文件冲突 | 多个 Agent 可能互相覆盖 | 每个 Agent 在自己的目录中工作 |
-| 分支 | 都在同一个分支上 | 每个 Agent 有自己的分支 |
-| 测试 | 互相干扰 | 完全独立 |
-| 合并 | 需要手动处理冲突 | 通过 git merge 有序合并 |
-
-## 工作流程
-
-<Steps>
-  <Step title="创建 Worktree">
-    AI 启动带隔离模式的子 Agent，系统自动在 `.claude/worktrees/` 下创建新的工作目录
-  </Step>
-  <Step title="独立工作">
-    子 Agent 在自己的 worktree 中自由修改文件、执行命令
-  </Step>
-  <Step title="完成任务">
-    子 Agent 完成后，变更留在 worktree 的分支上
-  </Step>
-  <Step title="合并或丢弃">
-    主 Agent（或用户）决定：合并这些变更到主分支，还是丢弃
-  </Step>
-  <Step title="清理">
-    不再需要的 worktree 会被自动清理
-  </Step>
-</Steps>
-
-## 安全网
-
-Worktree 还充当了一个安全网：
-
-- 子 Agent 的实验性修改不会影响主分支
-- 如果方案不可行，整个 worktree 可以直接丢弃
-- 多个方案可以在不同 worktree 中并行尝试，最后选最好的

docs/context/compaction.mdx

@@ -1,63 +0,0 @@
----
-title: "上下文压缩"
-description: "对话太长怎么办——优雅地'遗忘'不重要的信息"
----
-
-{/* 本章目标：解释 Compaction 机制的设计和策略 */}
-
-## 为什么需要压缩
-
-每次 API 调用的 token 有上限（通常 200K）。一场长时间的编程对话可能产生：
-
-- 大量的文件内容（AI 读了几十个文件）
-- 长篇的命令输出（构建日志、测试结果）
-- 往返的对话历史
-
-不压缩的话，很快就会撞到 token 上限，对话被迫终止。
-
-## 压缩的策略
-
-Claude Code 提供了多层压缩机制：
-
-<AccordionGroup>
-  <Accordion title="自动压缩">
-    当 token 接近上限时，系统自动触发压缩。AI 生成一份当前对话的**摘要**，替换掉早期的详细消息。效果就像人类的"记忆"——记住要点，忘记细节。
-  </Accordion>
-  <Accordion title="手动压缩">
-    用户可以随时通过 `/compact` 命令主动触发压缩。可以附带提示语（如 `/compact 聚焦在认证模块的修改上`），引导 AI 保留特定信息。
-  </Accordion>
-  <Accordion title="Micro Compact">
-    更细粒度的局部压缩——不是压缩整个对话，而是压缩某些特别长的工具输出（比如一个 5000 行的测试日志）。
-  </Accordion>
-</AccordionGroup>
-
-## 压缩边界
-
-压缩后，系统在消息历史中插入一个"边界标记"。后续的 API 调用只发送边界之后的消息：
-
-```
-[早期的 50 条消息] ← 被压缩
-[压缩摘要边界] ← 一段浓缩的摘要
-[后续的 10 条消息] ← 正常发送
-```
-
-这个设计保证了：
-- 压缩后的摘要为 AI 提供了历史上下文
-- 新的对话不受旧消息的 token 负担
-- 用户无感知——对话继续自然进行
-
-## 压缩前后的 Hooks
-
-压缩是一个可能丢失信息的操作，因此系统允许用户在压缩前后执行自定义脚本：
-
-- **Pre-compact Hook**：压缩前执行，可以标记"这些信息不能丢"
-- **Post-compact Hook**：压缩后执行，可以验证关键信息是否保留
-
-## 什么信息会被保留
-
-压缩不是简单的截断，AI 会智能地决定保留什么：
-
-- 用户的核心需求和目标
-- 重要的决策和原因
-- 当前工作的状态（改了哪些文件、做到哪一步）
-- 之前犯过的错误（避免重蹈覆辙）

docs/context/project-memory.mdx

@@ -1,58 +0,0 @@
----
-title: "项目记忆"
-description: "让 AI 跨对话记住你的偏好和项目上下文"
----
-
-{/* 本章目标：解释记忆系统如何让 AI 变得'有记忆' */}
-
-## AI 的记忆困境
-
-大语言模型没有真正的记忆。每次新对话，它都是一张白纸。用户不得不反复解释"我的项目用 Bun 不用 Node"、"commit 消息用中文"。
-
-## 记忆系统的解决方案
-
-Claude Code 通过一个基于文件的持久化记忆系统来模拟"跨会话记忆"：
-
-<CardGroup cols={2}>
-  <Card title="用户记忆" icon="user">
-    关于用户的信息：角色、偏好、技术背景
-  </Card>
-  <Card title="反馈记忆" icon="message">
-    用户对 AI 行为的纠正和肯定
-  </Card>
-  <Card title="项目记忆" icon="folder">
-    项目中的非代码信息：谁负责什么、截止日期
-  </Card>
-  <Card title="参考记忆" icon="link">
-    外部资源的位置：Issue tracker、Dashboard URL
-  </Card>
-</CardGroup>
-
-## 记忆的读写时机
-
-| 时机 | 动作 |
-|------|------|
-| 每次对话开始 | 加载记忆索引（MEMORY.md），相关记忆注入 System Prompt |
-| 用户纠正 AI | AI 自动判断是否值得记住，写入反馈记忆 |
-| 用户说"记住这个" | 立即保存到对应类型的记忆文件 |
-| 用户说"忘掉这个" | 找到并删除对应的记忆条目 |
-| 记忆可能过期时 | 使用前先验证（文件还在？函数还存在？），过期则更新或删除 |
-
-## 记忆 vs 代码注释 vs CLAUDE.md
-
-| | 记忆 | 代码注释 | CLAUDE.md |
-|---|---|---|---|
-| 存储位置 | `~/.claude/` 目录 | 代码文件中 | 项目目录中 |
-| 谁能看到 | 只有当前用户 | 所有开发者 | 所有使用 Claude Code 的人 |
-| 适合存什么 | 个人偏好、非公开的上下文 | 代码逻辑解释 | 项目约定、开发指南 |
-| 跨项目 | 是 | 否 | 否 |
-
-## 不该存什么
-
-记忆系统明确规定了不应存储的内容：
-
-- 代码结构和架构（读代码就知道）
-- git 历史（`git log` 就能查）
-- 调试方案（修复已在代码中）
-- CLAUDE.md 里已有的内容（避免重复）
-- 临时性任务状态（用任务系统）

docs/context/system-prompt.mdx

@@ -1,53 +0,0 @@
----
-title: "System Prompt 的动态组装"
-description: "AI 的'工作记忆'是如何在每次对话前被精心拼装的"
----
-
-{/* 本章目标：解释 System Prompt 的组装过程和设计思想 */}
-
-## 什么是 System Prompt
-
-每次调用 AI API 时，都需要发送一个 System Prompt——它是 AI 的"人设说明书"，告诉 AI：
-
-- 你是谁（Claude Code，一个编程助手）
-- 你能做什么（可用工具列表）
-- 你在什么环境（操作系统、当前目录、git 状态）
-- 你需要遵守什么规则（安全规范、输出格式）
-
-## 不是静态模板，而是动态组装
-
-Claude Code 的 System Prompt 不是一段写死的文本，而是根据当前环境**实时组装**的：
-
-| 组成部分 | 内容 | 来源 |
-|----------|------|------|
-| 基础人设 | 角色定义、行为准则 | 内置模板 |
-| 环境信息 | 操作系统、shell 类型、当前日期 | 运行时检测 |
-| Git 状态 | 当前分支、最近提交、工作区状态 | `git` 命令输出 |
-| 项目知识 | CLAUDE.md 文件内容 | 项目目录层级扫描 |
-| 记忆文件 | 用户偏好、项目约定 | 持久化记忆系统 |
-| 工具说明 | 每个可用工具的描述和参数 | 工具注册表 |
-
-## CLAUDE.md：项目级知识注入
-
-这是 Claude Code 最巧妙的设计之一。在项目根目录放一个 `CLAUDE.md` 文件，就能让 AI "理解" 你的项目：
-
-- **项目概述**：这个项目做什么、用了什么技术栈
-- **开发约定**：代码风格、命名规范、分支策略
-- **常用命令**：怎么构建、怎么测试、怎么部署
-- **注意事项**：已知的坑、特殊的配置
-
-系统会自动发现并合并多级 CLAUDE.md：
-
-```
-~/.claude/CLAUDE.md              ← 用户全局（个人偏好）
-  └── /project/CLAUDE.md         ← 项目根目录（团队共享）
-        └── /project/src/CLAUDE.md  ← 子目录（模块特定）
-```
-
-## 缓存策略
-
-System Prompt 的 token 消耗不小（可能占总量的 30%+）。为了降低成本，系统使用了缓存机制：
-
-- 不变的部分（基础人设、工具说明）可以跨请求复用
-- 变化的部分（git 状态、记忆文件）每次重新生成
-- 缓存节点的位置经过精心设计，最大化缓存命中率

docs/context/token-budget.mdx

@@ -1,55 +0,0 @@
----
-title: "Token 预算管理"
-description: "精打细算每一个 token——AI 的'注意力'是有限资源"
----
-
-{/* 本章目标：解释 token 预算管理的思路 */}
-
-## Token 是什么
-
-简单理解：token 约等于一个英文单词或半个中文字。AI 处理的所有输入和输出都按 token 计费。
-
-| 类型 | 说明 | 谁付费 |
-|------|------|--------|
-| 输入 token | 发给 AI 的所有内容（System Prompt + 对话历史 + 工具结果） | 用户 |
-| 输出 token | AI 生成的回复和工具调用 | 用户 |
-| 缓存 token | 重复发送的内容如果命中缓存，价格更低 | 部分用户 |
-
-## 预算控制的三个层面
-
-<CardGroup cols={3}>
-  <Card title="单次请求" icon="1">
-    每次 API 调用的最大输入/输出 token
-  </Card>
-  <Card title="单轮对话" icon="arrows-rotate">
-    一个 Agentic Loop 内的累计 token 消耗
-  </Card>
-  <Card title="整个会话" icon="clock">
-    全部对话轮次的累计花费（美元）
-  </Card>
-</CardGroup>
-
-## 工具输出的预算控制
-
-工具返回的内容可能非常长（一个大文件、一段长日志），直接全部塞给 AI 会浪费大量 token。系统对此有专门的控制：
-
-- **结果截断**：超过长度限制的工具输出自动截断
-- **结果替换**：已经被 AI"消化"过的旧工具结果，可以被替换为简短的摘要
-- **按需读取**：大文件不一次性读完，AI 可以指定读取范围
-
-## 缓存的经济学
-
-System Prompt 每次都要发送，但大部分内容不变。缓存机制让这部分"免费"（或大幅降价）：
-
-- 首次发送：全价
-- 后续请求命中缓存：约 1/10 的价格
-- 这就是为什么 System Prompt 的结构被精心设计——不变的部分放前面，变化的部分放后面
-
-## token 警告与自动压缩
-
-| token 使用率 | 系统行为 |
-|-------------|---------|
-| < 70% | 正常运行 |
-| 70% ~ 90% | 显示警告，提示用户可以手动压缩 |
-| > 90% | 自动触发压缩 |
-| 接近 100% | 强制压缩或终止当前轮次 |

docs/conversation/multi-turn.mdx

@@ -1,59 +0,0 @@
----
-title: "多轮对话管理"
-description: "一场跨越数小时的编程对话是如何被管理的"
----
-
-{/* 本章目标：解释会话编排、持久化、成本追踪 */}
-
-## 单轮 vs 多轮
-
-- **单轮**（一次 Agentic Loop）：用户说一句 → AI 执行一系列操作 → 回答
-- **多轮**（一个 Session）：用户和 AI 来回对话几十轮，持续数小时
-
-多轮对话带来的挑战远超单轮：消息越来越多、token 不断累积、上下文逐渐模糊。
-
-## 会话编排器的职责
-
-在单轮 Agentic Loop 之上，有一个编排器负责管理整个会话生命周期：
-
-<CardGroup cols={2}>
-  <Card title="对话状态管理" icon="database">
-    维护完整的消息历史，包括用户消息、AI 回复、工具调用结果
-  </Card>
-  <Card title="会话持久化" icon="floppy-disk">
-    自动保存对话记录到磁盘，支持断线重连、历史回顾
-  </Card>
-  <Card title="文件快照" icon="camera">
-    在 AI 修改文件前自动保存快照，支持回滚
-  </Card>
-  <Card title="成本追踪" icon="calculator">
-    精确记录每轮的 token 消耗和 API 费用
-  </Card>
-</CardGroup>
-
-## 会话恢复
-
-意外退出？网络断了？没关系：
-
-- 每轮对话结束后，完整的 transcript 会被写入磁盘
-- 下次启动时，可以选择恢复之前的对话
-- 恢复时，系统重建消息历史和上下文状态
-
-## 成本感知
-
-AI 编程助手的一个现实问题是**费用可能失控**。Claude Code 内建了多层成本控制：
-
-| 机制 | 作用 |
-|------|------|
-| Token 计数器 | 实时显示本次会话已消耗的输入/输出 token |
-| 费用估算 | 根据模型定价计算累计美元花费 |
-| 预算上限 | 用户可设定最大花费，到达后自动停止 |
-| 压缩提醒 | Token 接近上限时提示用户触发压缩 |
-
-## 模型切换
-
-在一个会话中，用户可以随时切换模型或调整参数：
-
-- `/model` 切换到不同的模型（Sonnet / Opus / Haiku）
-- `/fast` 切换快速模式
-- 模型切换不会丢失对话历史

docs/conversation/streaming.mdx

@@ -1,50 +0,0 @@
----
-title: "流式响应：逐字呈现"
-description: "为什么 Claude Code 的回答是'打字机效果'而不是一整块弹出"
----
-
-{/* 本章目标：解释流式通信的意义和它如何与工具执行交织 */}
-
-## 为什么需要流式
-
-想象 AI 需要 30 秒才能生成完整回答——如果等 30 秒后才一次性显示，用户体验是灾难性的。
-
-流式响应让用户**实时看到 AI 的思考过程**：
-- 文字逐字出现，用户能提前判断方向是否正确
-- 工具调用的参数在生成过程中就能预览
-- 长时间任务不会让用户觉得"卡死了"
-
-## 流式与工具调用的交织
-
-一次 AI 响应中可能同时包含文字和工具调用。流式系统需要处理这种交织：
-
-```
-AI 开始输出文字 → "我来看看这个文件的内容..."
-AI 发出工具调用 → [FileRead: src/main.ts]
-           ↓ 暂停流式输出
-     工具执行中... 
-     结果返回给 AI
-           ↓ 恢复流式输出
-AI 继续输出 → "这个文件里有一个 bug，第 42 行..."
-AI 发出下一个工具调用 → [FileEdit: src/main.ts]
-```
-
-## 流式工具执行
-
-更进阶的是，**工具本身的执行也可以是流式的**：
-
-- 运行一个长命令（比如 `npm install`），输出逐行显示
-- 搜索大型项目时，匹配结果逐条呈现
-- AI 在等待工具结果的同时，已经开始规划下一步
-
-## 多 Provider 适配
-
-Claude Code 支持多个 AI 服务提供商，每个提供商的流式协议略有不同：
-
-| Provider | 特点 |
-|----------|------|
-| Anthropic Direct | 原生 SSE 流，延迟最低 |
-| AWS Bedrock | 通过 AWS SDK 包装的流式接口 |
-| Google Vertex | gRPC 流转换为事件流 |
-
-系统通过统一的事件抽象层屏蔽这些差异——上层代码不需要关心底层用的是哪个 Provider。

docs/conversation/the-loop.mdx

@@ -1,66 +0,0 @@
----
-title: "Agentic Loop：对话的心跳"
-description: "AI 不只回答问题，它会反复思考-行动-观察，直到任务完成"
----
-
-{/* 本章目标：解释 Agentic Loop 这个核心机制 */}
-
-## 什么是 Agentic Loop
-
-传统聊天机器人：你问一句，它答一句。  
-Claude Code 不一样：你说一个需求，它可能连续执行十几步操作才给你最终结果。
-
-这背后的机制叫做 **Agentic Loop**（智能体循环）：
-
-{/* TODO: 插入 Loop 示意图 */}
-
-<Steps>
-  <Step title="思考">
-    AI 分析当前上下文，决定下一步该做什么
-  </Step>
-  <Step title="行动">
-    AI 发出工具调用请求（比如"读取这个文件"、"执行这条命令"）
-  </Step>
-  <Step title="观察">
-    工具执行完毕，结果回传给 AI
-  </Step>
-  <Step title="循环或结束">
-    AI 根据观察结果决定：继续下一步操作，还是任务已完成、直接回答用户
-  </Step>
-</Steps>
-
-## 一个真实的例子
-
-> 用户："帮我找到项目里所有未使用的导入语句，然后删掉它们"
-
-AI 的内部过程：
-
-1. **思考**：我需要先了解项目结构 → **行动**：调用 Glob 工具扫描所有源文件
-2. **观察**：拿到文件列表 → **思考**：逐个检查 → **行动**：调用 Grep 搜索 import 语句
-3. **观察**：发现 3 个文件有未使用导入 → **行动**：调用 FileEdit 逐个删除
-4. **观察**：编辑成功 → **结束**：告诉用户"已清理 3 个文件中的 5 条未使用导入"
-
-整个过程可能涉及 10+ 次工具调用，但用户只需要说一句话。
-
-## 为什么不是"一次规划，批量执行"
-
-<Note>
-一个常见的替代方案是：AI 先生成一个完整的计划，然后一次性执行所有步骤。Claude Code 选择了逐步循环，原因是：
-</Note>
-
-- **每一步都能看到真实结果**：文件内容、命令输出、错误信息——这些只有执行后才知道
-- **动态调整**：如果第 3 步发现了意外情况，AI 可以立刻改变策略
-- **错误恢复**：某步失败了，AI 可以当场诊断和修复，不需要推倒重来
-- **用户可控**：用户可以在任何一步中断，AI 的循环不会失控
-
-## 循环的终止条件
-
-Agentic Loop 不会无限运行，以下情况会让循环停止：
-
-| 条件 | 说明 |
-|------|------|
-| AI 主动结束 | AI 判断任务完成，返回纯文本回答（不再调用工具） |
-| 用户中断 | 用户按 Ctrl+C 或 ESC 打断当前操作 |
-| Token 预算耗尽 | 单轮对话的 token 用量达到上限 |
-| 输出过长自动续写 | AI 回复被截断时，系统自动发起续写请求（有次数上限） |
-| 成本上限 | 累计 API 花费超过用户设定的预算 |

docs/extensibility/custom-agents.mdx

@@ -1,56 +0,0 @@
----
-title: "自定义 Agent"
-description: "定义你自己的 AI 角色——不同的人格、能力和边界"
----
-
-{/* 本章目标：解释自定义 Agent 定义的设计 */}
-
-## 为什么需要自定义 Agent
-
-默认的 Claude Code 是一个"全能型"助手。但有些场景需要更专门化的角色：
-
-- 一个只负责代码审查、不会修改代码的 Agent
-- 一个专门处理 DevOps 任务的 Agent
-- 一个面向初学者、回答更详细的 Agent
-
-## Agent 定义
-
-自定义 Agent 通过 Markdown 文件定义，放在 `.claude/agents/` 目录：
-
-| 配置项 | 说明 |
-|--------|------|
-| **名称** | Agent 的标识和显示名 |
-| **描述** | 这个 Agent 的职责说明 |
-| **System Prompt** | 自定义的角色指令——替换或追加到默认 System Prompt |
-| **允许的工具** | 这个 Agent 可以使用哪些工具 |
-| **模型** | 使用哪个 AI 模型 |
-
-## 与子 Agent 的关系
-
-自定义 Agent 可以作为子 Agent 被启动：
-
-- 主 Agent 说"这个任务需要安全审查"
-- 系统启动一个自定义的"安全审查 Agent"
-- 该 Agent 只有阅读权限，使用专门的安全审查 Prompt
-
-这实现了**角色分离**——不同的任务由不同"人格"的 Agent 处理。
-
-## 复用与共享
-
-<CardGroup cols={2}>
-  <Card title="项目级" icon="folder">
-    放在项目的 `.claude/agents/` 目录，团队所有人可用
-  </Card>
-  <Card title="用户级" icon="user">
-    放在 `~/.claude/agents/` 目录，跨项目可用
-  </Card>
-</CardGroup>
-
-## 实际应用
-
-| Agent | 角色 | 工具限制 |
-|-------|------|---------|
-| `reviewer` | 代码审查员 | 只允许 Read、Glob、Grep |
-| `devops` | DevOps 工程师 | 允许 Bash，限制在 infra/ 目录 |
-| `tutor` | 编程导师 | 全部工具，但 Prompt 强调教学 |
-| `security` | 安全审计员 | 只允许搜索和阅读，输出安全报告 |

docs/extensibility/hooks.mdx

@@ -1,72 +0,0 @@
----
-title: "Hooks：生命周期钩子"
-description: "在 AI 的关键行为节点插入你自己的逻辑"
----
-
-{/* 本章目标：解释 Hooks 系统的设计和应用场景 */}
-
-## 什么是 Hooks
-
-Hooks 是用户定义的 shell 命令，在 Claude Code 生命周期的特定时刻自动执行。
-
-类比：React 的 `useEffect` 让你在组件渲染后执行自定义逻辑。Claude Code 的 Hooks 让你在 AI 的关键行为前后执行自定义脚本。
-
-## 可用的 Hook 事件
-
-| 事件 | 触发时机 | 典型用途 |
-|------|---------|---------|
-| **PreToolUse** | 工具调用前 | 拦截危险操作、自定义审批逻辑 |
-| **PostToolUse** | 工具调用后 | 记录日志、触发通知、自动格式化 |
-| **PreCompact** | 上下文压缩前 | 标记不可丢失的信息 |
-| **PostCompact** | 上下文压缩后 | 验证关键信息是否保留 |
-| **Notification** | AI 发出通知时 | 自定义通知渠道（Slack、邮件等） |
-| **StopFailure** | AI 循环异常停止时 | 自定义错误处理 |
-
-## Hook 的能力
-
-Hook 脚本不仅能"观察"，还能"干预"：
-
-<CardGroup cols={2}>
-  <Card title="拦截操作" icon="hand">
-    返回特定信号可以阻止工具调用执行
-  </Card>
-  <Card title="修改行为" icon="pen">
-    返回结构化的 JSON 输出，影响 Claude Code 的后续行为
-  </Card>
-  <Card title="注入上下文" icon="syringe">
-    向 AI 的对话中注入额外信息
-  </Card>
-  <Card title="触发外部流程" icon="bolt">
-    调用 CI/CD、发送通知、更新 Issue tracker
-  </Card>
-</CardGroup>
-
-## 配置方式
-
-Hooks 在 `settings.json` 中配置：
-
-```json
-{
-  "hooks": {
-    "PostToolUse": [
-      {
-        "matcher": { "tool_name": "Write" },
-        "hooks": [
-          {
-            "type": "command",
-            "command": "npx prettier --write $CLAUDE_FILE_PATH"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-这个例子：每当 AI 写入一个文件后，自动用 Prettier 格式化。
-
-## 安全控制
-
-- 托管设置（企业管理员）的 Hooks 优先级最高，用户不能覆盖
-- Hook 执行有超时限制
-- Hook 的输出会被解析和验证，防止注入攻击

docs/extensibility/mcp-protocol.mdx

@@ -1,75 +0,0 @@
----
-title: "MCP：开放的工具生态"
-description: "通过标准协议对接任何外部能力——数据库、API、自定义服务"
----
-
-{/* 本章目标：解释 MCP 协议如何扩展 AI 的能力边界 */}
-
-## 内置工具的局限
-
-Claude Code 内置了 50+ 工具，覆盖了通用的软件开发需求。但每个团队都有特殊需求：
-
-- 连接内部数据库查询数据
-- 调用公司内部 API
-- 操作特定的 DevOps 工具
-- 访问私有的知识库
-
-不可能把所有人的需求都内置进去。
-
-## MCP：一个标准的"插头"
-
-**Model Context Protocol**（模型上下文协议）是 Anthropic 提出的开放标准，定义了 AI 与外部工具之间的通信方式。
-
-类比：USB 是电脑连接外设的标准接口。MCP 是 AI 连接外部能力的标准接口。
-
-## 工作原理
-
-<Steps>
-  <Step title="启动 MCP Server">
-    开发者编写一个 MCP Server，暴露自定义工具（比如"查询数据库"、"发送 Slack 消息"）
-  </Step>
-  <Step title="Claude Code 连接">
-    在配置文件中声明要连接的 MCP Server
-  </Step>
-  <Step title="工具自动发现">
-    连接后，MCP Server 提供的工具自动出现在 AI 的可用工具列表中
-  </Step>
-  <Step title="透明调用">
-    AI 像使用内置工具一样使用 MCP 工具——无需知道底层实现
-  </Step>
-</Steps>
-
-## 三种连接方式
-
-| 方式 | 适用场景 |
-|------|---------|
-| **stdio** | MCP Server 作为子进程运行，通过标准输入/输出通信。最简单 |
-| **SSE** | 通过 HTTP Server-Sent Events 通信。适合远程服务 |
-| **StreamableHTTP** | 基于 HTTP 流的双向通信。适合复杂的交互场景 |
-
-## 权限一视同仁
-
-MCP 提供的工具和内置工具一样受权限系统管控：
-
-- 需要用户确认才能调用
-- 可以设置 allow/deny 规则
-- 支持沙箱限制
-
-这确保了第三方工具不会绕过安全边界。
-
-## 实际例子
-
-```json
-// settings.json 中的 MCP 配置
-{
-  "mcpServers": {
-    "my-database": {
-      "command": "npx",
-      "args": ["@my-org/db-mcp-server"],
-      "env": { "DB_URL": "postgres://..." }
-    }
-  }
-}
-```
-
-配置后，AI 就多了"查询数据库"这个能力——用自然语言描述需求，AI 自动生成查询并执行。

docs/extensibility/skills.mdx

@@ -1,60 +0,0 @@
----
-title: "Skills：预制的能力包"
-description: "把常用的工作流封装成可复用的技能"
----
-
-{/* 本章目标：解释 Skills 系统的设计思想 */}
-
-## Tool vs Skill
-
-| | Tool | Skill |
-|---|---|---|
-| 粒度 | 单个原子操作（读文件、执行命令） | 一套完整的工作流（代码审查、创建 PR） |
-| 触发方式 | AI 自主选择 | 用户主动调用（`/skill-name`）或 AI 根据场景推荐 |
-| 本质 | 执行逻辑 | 预制的 Prompt + 工具权限配置 |
-
-## Skill 的三个来源
-
-<CardGroup cols={3}>
-  <Card title="内置 Skill" icon="box">
-    编译进 CLI 的技能包。如 `/commit`、`/review`、`/debug`
-  </Card>
-  <Card title="项目 Skill" icon="folder-open">
-    项目 `.claude/skills/` 目录中的 Markdown 文件。团队共享
-  </Card>
-  <Card title="MCP Skill" icon="plug">
-    通过 MCP Server 提供的技能。动态发现
-  </Card>
-</CardGroup>
-
-## 一个 Skill 包含什么
-
-每个 Skill 本质上是一个"AI 行为的预设"：
-
-| 组成部分 | 作用 |
-|----------|------|
-| **名称和描述** | 告诉 AI 和用户这个技能做什么 |
-| **whenToUse** | 什么场景下应该使用这个技能（AI 据此自动推荐） |
-| **Prompt 模板** | 注入给 AI 的详细指令——相当于"操作手册" |
-| **allowedTools** | 这个技能允许使用哪些工具（能力边界） |
-| **model** | 可选指定使用的模型 |
-
-## 设计精妙之处
-
-Skill 的核心洞见是：**很多复杂任务的关键不在于代码逻辑，而在于 Prompt 的质量**。
-
-一个好的代码审查，不是写了什么代码来审查，而是：
-- 告诉 AI 审查的标准是什么
-- 告诉 AI 按什么顺序审查
-- 告诉 AI 输出什么格式的报告
-- 限制 AI 只能用读取类工具（不要边审查边改代码）
-
-Skill 把这些"经验"封装起来，任何人都能一键调用。
-
-## 技能发现
-
-当可用技能很多时，AI 可以通过 **SkillTool** 搜索匹配的技能：
-
-- 用户说"帮我做代码审查"
-- AI 搜索已注册的技能，发现 `code-review` 匹配
-- AI 调用该技能，按预设的流程执行

docs/favicon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" fill="none">
+  <circle cx="16" cy="16" r="14" fill="#D97706"/>
+  <path d="M12 10l10 6-10 6V10z" fill="#FFFFFF"/>
+</svg>

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/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/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/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/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/growthbook-adapter.mdx

@@ -0,0 +1,169 @@
+---
+title: "GrowthBook 适配器 - 自定义 Feature Flag 服务器接入"
+description: "通过环境变量连接自定义 GrowthBook 服务器，实现远程 feature flag 控制。无配置时自动回退到代码默认值。"
+keywords: ["growthbook", "feature flags", "远程配置", "适配器", "环境变量"]
+---
+
+## 概述
+
+Claude Code 的 GrowthBook 系统支持通过环境变量连接自定义 GrowthBook 服务器，实现远程 feature flag 控制。
+
+- **有配置时**：连接你的 GrowthBook 实例，拉取并缓存 feature 值
+- **无配置时**：所有 feature 读取直接返回代码中的默认值，零网络请求
+
+## 环境变量
+
+| 变量 | 必填 | 说明 |
+|---|---|---|
+| `CLAUDE_GB_ADAPTER_URL` | 是 | GrowthBook API 地址，如 `https://gb.example.com/` |
+| `CLAUDE_GB_ADAPTER_KEY` | 是 | GrowthBook SDK Client Key，如 `sdk-xxxxx` |
+
+两个变量都设置时启用适配器模式，否则完全跳过 GrowthBook。
+
+## 使用方式
+
+### 基本用法
+
+```bash
+CLAUDE_GB_ADAPTER_URL=https://gb.example.com/ \
+CLAUDE_GB_ADAPTER_KEY=sdk-abc123 \
+bun run dev
+```
+
+### 不使用 GrowthBook（默认行为）
+
+```bash
+bun run dev
+# 所有 getFeatureValue_CACHED_MAY_BE_STALE("xxx", defaultValue) 直接返回 defaultValue
+```
+
+## GrowthBook 服务端配置
+
+### 步骤
+
+1. **部署 GrowthBook 服务端**（Docker 自托管或 Cloud 版）
+2. **创建 Environment**（如 `production`）
+3. **创建 SDK Connection**，获得 SDK Key（即 `CLAUDE_GB_ADAPTER_KEY`）
+4. **按需添加 Feature**，key 和类型见下方列表
+
+### 核心原则
+
+- **不配置任何 feature 也能正常运行**——代码中每个调用都提供了默认值
+- 只创建你想远程控制的 feature，其余走代码默认
+- GrowthBook 上配了某个 feature 后，其值会覆盖代码中的默认值
+
+## Feature Key 列表
+
+### 高频使用
+
+| Feature Key | 类型 | 代码默认值 | 用途 |
+|---|---|---|---|
+| `tengu_hive_evidence` | boolean | `false` | 任务证据系统 |
+| `tengu_quartz_lantern` | boolean | `false` | 文件写入/编辑保护 |
+| `tengu_auto_background_agents` | boolean | `false` | 自动后台 Agent |
+| `tengu_agent_list_attach` | boolean | `false` | Agent 列表附件 |
+| `tengu_amber_stoat` | boolean | `true` | 内置 Agents |
+| `tengu_slim_subagent_claudemd` | boolean | `true` | 子 Agent CLAUDE.md |
+| `tengu_attribution_header` | boolean | `true` | API 归因 Header |
+| `tengu_cobalt_harbor` | boolean | `false` | Bridge 模式 |
+| `tengu_ccr_bridge` | boolean | `false` | CCR Bridge |
+| `tengu_cicada_nap_ms` | number | `0` | 后台刷新节流（毫秒） |
+| `tengu_miraculo_the_bard` | boolean | `false` | 启动欢迎信息 |
+
+### Agent / 工具控制
+
+| Feature Key | 类型 | 代码默认值 | 用途 |
+|---|---|---|---|
+| `tengu_surreal_dali` | boolean | `false` | 远程触发工具 |
+| `tengu_glacier_2xr` | boolean | `false` | 工具搜索增强 |
+| `tengu_plum_vx3` | boolean | `false` | Web Search 使用 Haiku |
+| `tengu_destructive_command_warning` | boolean | `false` | 危险命令警告 |
+| `tengu_birch_trellis` | boolean | `true` | Bash 权限控制 |
+| `tengu_harbor_permissions` | boolean | `false` | Harbor 权限模式 |
+
+### Bridge / 远程连接
+
+| Feature Key | 类型 | 代码默认值 | 用途 |
+|---|---|---|---|
+| `tengu_bridge_repl_v2` | boolean | `false` | Bridge REPL v2 |
+| `tengu_copper_bridge` | boolean | `false` | Copper Bridge |
+| `tengu_ccr_mirror` | boolean | `false` | CCR Mirror |
+
+### 内存 / 上下文
+
+| Feature Key | 类型 | 代码默认值 | 用途 |
+|---|---|---|---|
+| `tengu_coral_fern` | boolean | `false` | 内存目录功能 |
+| `tengu_passport_quail` | boolean | `false` | 内存路径配置 |
+| `tengu_slate_thimble` | boolean | `false` | Slate Thimble |
+| `tengu_herring_clock` | boolean | `false` | 跳过索引 |
+| `tengu_session_memory` | boolean | `false` | 会话内存 |
+| `tengu_pebble_leaf_prune` | boolean | `false` | 内存修剪 |
+
+### UI / 体验
+
+| Feature Key | 类型 | 代码默认值 | 用途 |
+|---|---|---|---|
+| `tengu_terminal_sidebar` | boolean | `false` | 终端侧边栏 |
+| `tengu_terminal_panel` | boolean | `false` | 终端面板 |
+| `tengu_willow_mode` | boolean | `false` | Willow 模式 |
+| `tengu_collage_kaleidoscope` | boolean | `false` | UI 效果 |
+| `tengu_chrome_auto_enable` | boolean | `false` | Chrome 自动启用 |
+| `tengu_immediate_model_command` | boolean | `false` | 即时模型切换 |
+| `tengu_remote_backend` | boolean | `false` | 远程后端 |
+
+### 配置对象（动态配置）
+
+| Feature Key | 类型 | 代码默认值 | 用途 |
+|---|---|---|---|
+| `tengu_file_read_limits` | object | `null` | 文件读取限制配置 |
+| `tengu_cobalt_raccoon` | object | `null` | Cobalt 配置 |
+| `tengu_cobalt_lantern` | object | `null` | Lantern 配置 |
+| `tengu_desktop_upsell` | object | `null` | 桌面版引导 |
+| `tengu_marble_sandcastle` | object | `null` | Marble 配置 |
+| `tengu_marble_fox` | object | `null` | Marble Fox 配置 |
+| `tengu_ultraplan_model` | string | `null` | Ultraplan 模型名 |
+
+### Gate（布尔门控）
+
+| Gate Key | 代码默认值 | 用途 |
+|---|---|---|
+| `tengu_chair_sermon` | `false` | 功能门控 |
+| `tengu_scratch` | `false` | Scratch 功能 |
+| `tengu_thinkback` | `false` | Thinkback 功能 |
+| `tengu_tool_pear` | `false` | Tool Pear 功能 |
+
+## 读取优先级链
+
+每个 feature 的值按以下顺序解析，第一个命中即返回：
+
+```
+1. CLAUDE_INTERNAL_FC_OVERRIDES 环境变量（JSON 对象覆盖）
+   ↓ 未命中
+2. growthBookOverrides 配置（~/.claude.json，仅 ant 构建）
+   ↓ 未命中
+3. 内存缓存（remoteEvalFeatureValues，本次进程从服务器拉取）
+   ↓ 未命中
+4. 磁盘缓存（~/.claude.json 的 cachedGrowthBookFeatures）
+   ↓ 未命中
+5. 代码中的 defaultValue 参数
+```
+
+## 缓存与刷新机制
+
+| 机制 | 说明 |
+|---|---|
+| **磁盘缓存** | `~/.claude.json` 的 `cachedGrowthBookFeatures` 字段，跨进程持久化 |
+| **周期刷新** | 每 6 小时自动从服务器拉取最新值（`setInterval` + `unref`） |
+| **初始化超时** | 首次连接超时 5 秒，超时后使用磁盘缓存或默认值 |
+| **Auth 变更** | 登录/登出时自动销毁并重建客户端 |
+
+## 实现细节
+
+修改了 2 个文件共 3 处：
+
+1. **`src/constants/keys.ts`** — `getGrowthBookClientKey()` 优先读取 `CLAUDE_GB_ADAPTER_KEY`
+2. **`src/services/analytics/growthbook.ts`** — `isGrowthBookEnabled()` 适配器模式下直接启用
+3. **`src/services/analytics/growthbook.ts`** — base URL 优先使用 `CLAUDE_GB_ADAPTER_URL`
+
+所有 130+ 个调用方文件无需修改。

docs/internals/sentry-setup.mdx

@@ -0,0 +1,106 @@
+---
+title: "自定义 Sentry 错误上报配置"
+description: "通过环境变量连接自托管或 Cloud Sentry，实现 CLI 运行时的错误捕获与上报。不配置则完全静默。"
+keywords: ["sentry", "错误上报", "监控", "DSN", "自托管"]
+---
+
+## 概述
+
+Claude Code 支持通过 Sentry 捕获运行时异常并上报到你自己指定的 Sentry 实例。
+
+- **配置了 `SENTRY_DSN`**：自动初始化 Sentry SDK，捕获未处理异常和关键错误
+- **未配置**：所有 Sentry 调用均为 no-op，零开销
+
+## 环境变量
+
+| 变量 | 必填 | 说明 |
+|---|---|---|
+| `SENTRY_DSN` | 是 | Sentry 项目 DSN，如 `https://xxx@o123456.ingest.sentry.io/789` |
+
+只需要这一个变量，设置后即启用。
+
+## 使用方式
+
+### 自托管 Sentry
+
+```bash
+SENTRY_DSN=https://public_key@your-sentry.example.com/123 \
+bun run dev
+```
+
+### Sentry Cloud (SaaS)
+
+```bash
+SENTRY_DSN=https://public_key@o123456.ingest.sentry.io/789 \
+bun run dev
+```
+
+### 不使用 Sentry（默认行为）
+
+```bash
+bun run dev
+# SENTRY_DSN 未设置，所有 sentry 函数为 no-op
+```
+
+## Sentry 服务端配置
+
+### 步骤
+
+1. **部署 Sentry 实例**（Docker 自托管 或 使用 [sentry.io](https://sentry.io) Cloud）
+2. **创建 Project**，选择 **Node.js** 平台
+3. 获取项目的 **DSN**（Settings → Projects → Client Keys → DSN）
+4. 将 DSN 设置为 `SENTRY_DSN` 环境变量
+
+## 功能详情
+
+### 错误捕获
+
+- **自动捕获**：`SentryErrorBoundary` 包裹关键 React 组件，捕获渲染错误
+- **手动上报**：`errorLogSink` 在写入错误日志时同步上报到 Sentry
+- **优雅关闭**：进程退出时 `closeSentry()` 确保事件发送完毕（2s 超时）
+
+### 安全过滤
+
+`beforeSend` 钩子会自动剥离以下敏感 header：
+
+- `authorization`
+- `x-api-key`
+- `cookie`
+- `set-cookie`
+
+### 忽略的错误类型
+
+以下错误模式会被忽略，不会上报：
+
+| 错误 | 原因 |
+|---|---|
+| `ECONNREFUSED` / `ECONNRESET` / `ENOTFOUND` / `ETIMEDOUT` | 网络不可达，不可操作 |
+| `AbortError` / `The user aborted a request` | 用户主动取消 |
+| `CancelError` | 交互式取消信号 |
+
+### 其他配置
+
+- **采样率**：`sampleRate: 1.0`（捕获全部错误事件）
+- **面包屑上限**：`maxBreadcrumbs: 20`（控制 payload 体积）
+- **性能事务**：已关闭（`beforeSendTransaction` 返回 `null`），仅上报错误
+
+## API
+
+| 函数 | 说明 |
+|---|---|
+| `initSentry()` | 初始化 SDK，在 `src/entrypoints/init.ts` 中自动调用 |
+| `captureException(error, context?)` | 手动上报异常，可附加额外上下文 |
+| `setTag(key, value)` | 设置标签，用于 Sentry 面板分组过滤 |
+| `setUser({ id, email, username })` | 设置用户上下文，用于错误归因 |
+| `closeSentry(timeoutMs?)` | 刷出队列并关闭客户端，进程退出时调用 |
+| `isSentryInitialized()` | 检查是否已初始化 |
+
+## 实现文件
+
+| 文件 | 说明 |
+|---|---|
+| `src/utils/sentry.ts` | 核心 SDK 初始化与封装 |
+| `src/components/SentryErrorBoundary.ts` | React Error Boundary 组件 |
+| `src/utils/errorLogSink.ts` | 错误日志 sink，集成 `captureException` |
+| `src/utils/gracefulShutdown.ts` | 优雅退出，调用 `closeSentry()` |
+| `src/entrypoints/init.ts` | 启动时调用 `initSentry()` |

docs/introduction/architecture-overview.mdx

@@ -1,59 +0,0 @@
----
-title: "架构全景"
-description: "五层架构，一条数据流"
----
-
-{/* 本章目标：一张图讲清楚整体架构，为后续章节建立坐标系 */}
-
-## 五层架构
-
-Claude Code 从上到下分为五个层次，每一层职责清晰、边界分明：
-
-| 层次 | 职责 | 关键词 |
-|------|------|--------|
-| **交互层** | 终端 UI、用户输入、消息展示 | React/Ink、REPL |
-| **编排层** | 管理多轮对话、会话生命周期、成本追踪 | QueryEngine、会话持久化 |
-| **核心循环层** | 单轮对话：发请求 → 拿响应 → 执行工具 → 再发请求 | Agentic Loop |
-| **工具层** | AI 的"双手"——读写文件、执行命令、搜索代码 | Tool System、MCP |
-| **通信层** | 与 Claude API 的流式通信、多云 Provider 适配 | Streaming、Bedrock/Vertex |
-
-## 一条主数据流
-
-{/* TODO: 插入数据流序列图 */}
-
-整个系统的运转可以浓缩为一条核心数据流：
-
-<Steps>
-  <Step title="用户输入">
-    用户在终端键入自然语言需求
-  </Step>
-  <Step title="上下文组装">
-    系统自动拼接项目信息、git 状态、配置文件、记忆，形成完整的 System Prompt
-  </Step>
-  <Step title="API 调用">
-    将 System Prompt + 对话历史发送给 Claude API，流式接收响应
-  </Step>
-  <Step title="工具调用循环">
-    若 AI 返回工具调用请求 → 权限检查 → 执行工具 → 结果回传 → AI 继续思考 → 循环
-  </Step>
-  <Step title="任务完成">
-    AI 不再调用工具，输出最终回答，等待用户下一条输入
-  </Step>
-</Steps>
-
-## 四个核心设计原则
-
-<AccordionGroup>
-  <Accordion title="流式优先 (Streaming-first)">
-    所有 API 通信都是流式的——用户看到 AI "逐字打出"回答，而不是等待完整响应。工具执行结果也实时反馈。这不仅提升体验，更是处理长时间任务的工程必需。
-  </Accordion>
-  <Accordion title="工具即能力 (Tool as Capability)">
-    AI 的每一项"动手能力"都被抽象为一个 Tool。想让 AI 能做新事情？注册一个新 Tool 就好。统一的接口让能力可插拔、可组合。
-  </Accordion>
-  <Accordion title="权限即边界 (Permission as Boundary)">
-    AI 能操作真实环境是强大的，也是危险的。每个工具调用都经过权限系统的裁决——该放行的自动放行，该拦截的坚决拦截。
-  </Accordion>
-  <Accordion title="上下文即记忆 (Context as Memory)">
-    AI 没有真正的记忆，但通过精心的 System Prompt 组装、对话压缩、持久化记忆文件，系统营造出"AI 理解你的项目"的效果。这是上下文工程的核心。
-  </Accordion>
-</AccordionGroup>

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

@@ -1,37 +0,0 @@
----
-title: "什么是 Claude Code"
-description: "一个住在终端里的 AI 编程搭档"
----
-
-{/* 本章目标：让完全不了解 Claude Code 的读者在 3 分钟内建立直觉 */}
-
-## 一句话定义
-
-Claude Code 是一个运行在命令行终端里的 AI 编程助手。你用自然语言描述需求，它直接帮你读代码、改文件、跑命令、搜索项目——全部在你的本地环境中完成。
-
-## 它能做什么
-
-- **对话式编程**：像和同事聊天一样描述需求，AI 直接动手实现
-- **理解整个项目**：自动读取项目结构、git 历史、配置文件，建立项目全景认知
-- **操作你的电脑**：读写文件、执行 shell 命令、搜索代码——不只是给建议，而是真正动手
-- **保护你的安全**：每个敏感操作都需要你确认，有沙箱、有权限管控
-
-## 它和 ChatGPT / 普通聊天机器人的区别
-
-| | 普通聊天 AI | Claude Code |
-|---|---|---|
-| 运行环境 | 云端网页 | 你的本地终端 |
-| 能做什么 | 回答问题、生成文本 | 直接操作你的项目文件和命令行 |
-| 项目理解 | 你需要手动粘贴代码 | 自动读取整个项目上下文 |
-| 安全性 | 无需考虑 | 多层权限保护 |
-
-## 一次典型的交互流程
-
-{/* TODO: 插入一张交互流程示意图 */}
-
-1. 你在终端输入自然语言需求
-2. Claude Code 分析你的项目上下文
-3. 它决定使用哪些工具（读文件？执行命令？）
-4. 每个操作请求你确认（或根据规则自动放行）
-5. 执行完成后，把结果反馈给 AI，AI 决定下一步
-6. 循环，直到任务完成

docs/introduction/why-this-whitepaper.mdx

@@ -1,40 +0,0 @@
----
-title: "为什么写这份白皮书"
-description: "将 LLM 能力落地到真实工作流的工程范本"
----
-
-{/* 本章目标：解释为什么这个项目的架构值得深入研究 */}
-
-## 不只是一个聊天工具
-
-Claude Code 解决的核心问题是：**如何让大语言模型从"能说会道"变成"能说会做"**。
-
-这不是简单地给 AI 套一个 shell。它涉及一系列精巧的工程决策：
-
-- AI 说"我要编辑这个文件"时，如何确保安全？
-- 对话越来越长，token 快爆了怎么办？
-- AI 需要并行处理多个子任务时，如何隔离和协调？
-- 用户想扩展 AI 的能力（接数据库、连 API），如何设计插拔机制？
-
-## 这份白皮书关注什么
-
-<CardGroup cols={2}>
-  <Card title="功能视角" icon="eye">
-    不堆代码，从"用户能做什么、AI 如何决策"出发
-  </Card>
-  <Card title="设计决策" icon="lightbulb">
-    每个功能背后的"为什么这样设计"
-  </Card>
-  <Card title="架构模式" icon="sitemap">
-    可复用的模式：Agentic Loop、工具抽象、上下文工程
-  </Card>
-  <Card title="安全哲学" icon="shield">
-    AI 操作真实环境时的信任与控制平衡
-  </Card>
-</CardGroup>
-
-## 适合谁读
-
-- 想理解 AI Agent 产品架构的开发者
-- 正在构建类似工具的团队
-- 对 LLM 应用工程化感兴趣的任何人

docs/logo/dark.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 80 28" fill="none">
+  <circle cx="14" cy="14" r="11" stroke="#F59E0B" stroke-width="2" fill="none"/>
+  <path d="M11 10l6 4-6 4V10z" fill="#F59E0B"/>
+  <text x="30" y="19.5" font-family="system-ui, -apple-system, sans-serif" font-size="15" font-weight="700" letter-spacing="1" fill="#F1F5F9">CCB</text>
+</svg>

docs/logo/light.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 80 28" fill="none">
+  <circle cx="14" cy="14" r="11" stroke="#D97706" stroke-width="2" fill="none"/>
+  <path d="M11 10l6 4-6 4V10z" fill="#D97706"/>
+  <text x="30" y="19.5" font-family="system-ui, -apple-system, sans-serif" font-size="15" font-weight="700" letter-spacing="1" fill="#0F172A">CCB</text>
+</svg>

docs/mint.json

@@ -1,84 +0,0 @@
-{
-  "$schema": "https://mintlify.com/schema.json",
-  "name": "Claude Code Architecture",
-  "logo": {
-    "dark": "/logo/dark.svg",
-    "light": "/logo/light.svg"
-  },
-  "favicon": "/favicon.svg",
-  "colors": {
-    "primary": "#D97706",
-    "light": "#F59E0B",
-    "dark": "#B45309",
-    "background": {
-      "dark": "#0F172A",
-      "light": "#FFFFFF"
-    }
-  },
-  "navigation": [
-    {
-      "group": "开始",
-      "pages": [
-        "introduction/what-is-claude-code",
-        "introduction/why-this-whitepaper",
-        "introduction/architecture-overview"
-      ]
-    },
-    {
-      "group": "对话是如何运转的",
-      "pages": [
-        "conversation/the-loop",
-        "conversation/streaming",
-        "conversation/multi-turn"
-      ]
-    },
-    {
-      "group": "工具：AI 的双手",
-      "pages": [
-        "tools/what-are-tools",
-        "tools/file-operations",
-        "tools/shell-execution",
-        "tools/search-and-navigation",
-        "tools/task-management"
-      ]
-    },
-    {
-      "group": "安全与权限",
-      "pages": [
-        "safety/why-safety-matters",
-        "safety/permission-model",
-        "safety/sandbox",
-        "safety/plan-mode"
-      ]
-    },
-    {
-      "group": "上下文工程",
-      "pages": [
-        "context/system-prompt",
-        "context/project-memory",
-        "context/compaction",
-        "context/token-budget"
-      ]
-    },
-    {
-      "group": "多 Agent 协作",
-      "pages": [
-        "agent/sub-agents",
-        "agent/worktree-isolation",
-        "agent/coordinator-and-swarm"
-      ]
-    },
-    {
-      "group": "可扩展性",
-      "pages": [
-        "extensibility/mcp-protocol",
-        "extensibility/hooks",
-        "extensibility/skills",
-        "extensibility/custom-agents"
-      ]
-    }
-  ],
-  "footerSocials": {
-    "github": "https://github.com/anthropics/claude-code"
-  }
-}

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() 取"**（设计视角）——单一真相源是统计正确性的前提。
+
+这种呼应关系是排错章必须双视角覆盖的核心原因：用户视角告诉你**遇到这个错误怎么办**，设计视角告诉你**为什么会有这个错误**。两个视角合在一起，才能让使用者和维护者用同一套词汇对话。

docs/outline-output/cross/02-performance-memory.md

@@ -0,0 +1,207 @@
+# 性能与内存
+
+> 同一个"长会话越用越卡"在使用者眼里是"我该怎么压上下文"，在开发者眼里是"JavaScriptCore 的 C++ Vector 为什么永不收缩"。性能与内存是双视角主题里因果链最长的一个：用户能观察到的每一个 RSS 数字、每一次"重启就好"，背后都对应着一条具体的运行时约束或一段反编译留下的工程妥协。
+
+## 产品视角（写给使用者）
+
+这一节回答两个问题：**日常用着用着变卡了怎么办**，以及**怎么从一开始就把内存预算控制住**。读完之后你不需要去看源码，就能把九成长会话性能问题处理掉。
+
+### 先分清两类"卡"
+
+长会话变慢几乎总是下面两类原因之一，处理方式完全不同：
+
+- **上下文太长** —— 每一轮对话都把历史消息塞进 prompt，模型推理时间和 token 账单随上下文线性增长。这种"卡"是**可逆的**：压一下上下文，立刻就快。
+- **进程内存累积** —— 即使上下文压缩了，进程的 RSS（常驻内存）也可能不下降。这种"卡"是**渐进的**：压缩上下文救不了，最快的解法是退出 CLI 重开。
+
+判断方式：跑 `/compact` 之后看响应速度。如果明显变快，说明是上下文问题；如果还是慢、状态栏或 `ps aux | grep claude` 看到的 RSS 数字还在涨，就是内存累积问题。
+
+### 上下文变长的三条解法，从轻到重
+
+按下面顺序试，越往下越彻底：
+
+1. **`/compact`** —— 让 Claude 用一个小模型把历史对话总结成一段摘要，再用摘要替换原始消息。源码在 `src/commands/compact/compact.ts`。它会先尝试 session memory 压缩（保留结构化记忆），失败再走通用压缩模型。带自定义指令也行：`/compact 只保留与测试相关的部分`。
+2. **`/force-snip`** —— 直接在消息数组里插一条 `snip_boundary` 系统消息，把当前位置之前的历史标记为"已剪裁"。下一次 query 时 `snipCompactIfNeeded` 会把这些消息从模型视角下移除，但 REPL 里依然能看到完整滚动历史。源码在 `src/commands/force-snip.ts:18`。比 `/compact` 更暴力：不总结、直接砍。
+3. **`/clear`** —— 整个会话清空重开。源码在 `src/commands/clear/`。
+
+日常推荐顺序是 `/compact` → `/force-snip` → `/clear`。`/force-snip` 适合"前面那段讨论已经跑偏了，我想从干净状态继续"的场景。
+
+### 自动 compact 什么时候触发
+
+系统会在上下文接近模型窗口上限时自动触发 compact，不需要你手动盯。如果你发现自动触发太频繁（每次刚聊几句就被压缩），说明你的 CLAUDE.md 或工具调用本身就在贡献大量上下文——可以跑 `/context` 或 `/ctx_viz` 看看上下文都被什么占满了。
+
+### 长跑场景特别留意：daemon、/loop、容器
+
+短会话几乎不会撞上内存累积问题，但下面这些长跑场景会：
+
+- **`/loop`** —— 每 N 分钟自动跑一次任务，进程常驻。
+- **daemon 模式** —— `claude daemon start` 启动的长驻 supervisor + worker。
+- **容器 / CI** —— `CLAUDE_CODE_REMOTE=true` 时，`cli.tsx:44-49` 会自动给子进程注入 `--max-old-space-size=8192`（前提是容器有 16GB）。这是项目对容器环境的硬编码假设：你的容器至少要有 8GB 余量给 Node.js 堆。
+
+在长跑场景下，建议每隔几小时主动重启一次进程，或者把任务拆成多次独立会话而不是一条无限循环。
+
+### 我想知道 Claude 现在吃了多少内存
+
+- macOS / Linux：`ps aux | grep claude`，看 RSS 列（单位 KB）。
+- daemon / background session：`claude ps` 看进程列表，`claude logs` 看输出。
+- 性能问题专用反馈通道：`/perf-issue`（源码 `src/commands/perf-issue/`）。
+
+### 为什么有时候重启 CLI 是唯一解
+
+如果压缩了上下文、清了消息，进程 RSS 还是下不去，这是 JavaScriptCore（Bun 的 JS 引擎）的已知特性：某些内部缓冲区一旦分配就不再收缩。详细原因见下面的设计视角。**用户侧能做的就是退出重开**——这不是 bug，是运行时的硬约束。
+
+## 设计视角（写给开发者）
+
+设计大纲里性能主题分布在第一、三、四章，是全书最深的几章。这一节把数据链串起来讲：从 17MB 单文件的灾难，到 `performanceShim` 的运行时补丁，到 6,889 个 `_debugStack` 的"看不见的内存"，再到 `cli.tsx:48` 那条看似随意的 `--max-old-space-size` 注入。
+
+### JSC 的贪婪解析：17MB 单文件为什么能让 RSS 涨到 1GB
+
+这是全书最戏剧性的设计动机。打开 `vite.config.ts:94-102`：
+
+```ts
+output: {
+  format: 'es',
+  // Code splitting: Bun/JSC parses the entire single-file bundle eagerly,
+  // consuming ~1 GB RSS for a 17 MB output (vs ~220 MB on Node/V8 which
+  // lazy-parses). Splitting into chunks allows Bun to load modules on demand,
+  // bringing RSS down to ~300 MB.
+  entryFileNames: 'cli.js',
+  chunkFileNames: 'chunks/[name]-[hash].js',
+},
+```
+
+JavaScriptCore（Bun 用的 JS 引擎）和 V8（Node.js 用的）在解析策略上有根本差异：**JSC 全量解析 + 全量 JIT**，V8 懒解析。同样一份 17MB 的单文件 bundle，JSC 会把整份 bytecode 和 JIT 编译结果一次性吃进内存，RSS 直接冲到 ~1GB；V8 只在函数被调用时才解析，RSS 只要 ~220MB。
+
+CLAUDE.md 里记录的实测数据更细：单文件 17MB 产物导致 RSS 暴涨至 ~1GB；切成 600+ chunks 后，Bun 按需加载，`--version` 的 RSS 从 966MB 骤降到 35MB，完整加载从 1GB+ 降到 ~500MB。
+
+**为什么 Vite 必须代码分割而不是单文件**——这不是性能优化，是**生存需求**。Bun.build（`build.ts:23` 的 `splitting: true`）和 Vite（`vite.config.ts:94` 的 `chunkFileNames: 'chunks/[name]-[hash].js'`）两条构建管线都默认走代码分割，原因就是这条。
+
+`scripts/post-build.ts` 还要在分割后做两件事：(1) 把 `import.meta.require` 替换成 Node.js 兼容的 `createRequire` 探测，让产物同时能在 bun 和 node 上跑；(2) patch 掉第三方依赖（`@anthropic-ai/sandbox-runtime`）里未受保护的 `var { ... } = globalThis.Bun` 解构——否则在 Node.js 启动会崩。这两步都是"代码分割 + 双运行时兼容"的下游工程代价。
+
+### performanceShim：JSC 原生 Performance 的 C++ Vector 永不收缩
+
+打开 `src/utils/performanceShim.ts:1-17`，文件头注释直接写明了根因：
+
+> In Bun, globalThis.performance is JSC's native Performance object. It stores marks, measures, and resource timings in a C++ Vector that never shrinks even after clearMarks(). Long-running sessions (daemon, /loop) accumulate hundreds of MB of dead capacity.
+
+JSC 的原生 `performance` 对象把 `mark()` / `measure()` / resource timings 存进一个 C++ Vector，这个 Vector **只增不减**——即使你调 `clearMarks()`，C++ 那头的容量也不会释放。React reconciler 和 OpenTelemetry / Langfuse 客户端都会反复调用 `mark` / `measure` 做时间打点，长会话里这些死容量能累积几百 MB。
+
+shim 做的事（`performanceShim.ts:19-155`）很克制：
+
+- **`performance.now()` 继续走原生**（`performanceShim.ts:28-30`）—— 高频调用、不占内存，没必要劫持。
+- **`mark` / `measure` / `getEntries*` 重定向到 GC 可回收的 JS Map**（`performanceShim.ts:22-26` 的 `marks` / `measures`）—— Map 是普通 JS 对象，GC 能正常回收。
+- **不继承 Performance.prototype**（`performanceShim.ts:124-126`）—— 因为原生 getter（`timeOrigin` / `onresourcetimingbufferfull` / `toJSON`）会检查 `this` 是不是真正的 JSC Performance 实例，继承就抛错。
+- **提供 `markResourceTiming` 空函数**（`performanceShim.ts:140`）—— Node.js v22 的 undici 内部每次 fetch 后都会调这个方法，不存在就 TypeError。
+
+**为什么必须最先 import**——这是整段代码里最脆弱的顺序依赖。打开 `src/entrypoints/cli.tsx:1-5`：
+
+```ts
+#!/usr/bin/env bun
+// Performance shim MUST be the first import — it replaces globalThis.performance
+// with a JS-backed implementation before React/OTel capture the native reference.
+// Without this, JSC's C++ Vector grows without bound in long-running sessions.
+import '../utils/performanceShim.js';
+```
+
+原因（`performanceShim.ts:14-16`）：React reconciler 和 OTel / Langfuse 在 import 时会**捕获 `globalThis.performance` 的引用**。一旦它们拿到原生引用，shim 再装上也没用——它们调用的是自己缓存的原生对象。所以 shim 必须在 React / OTel 加载**之前**就把 `globalThis.performance` 换掉。`installPerformanceShim()`（`performanceShim.ts:162-166`）用 `globalThis.__performanceShimInstalled` 守护幂等性，并且文件末尾（`:169`）自动调用一次，保证"import 即安装"。
+
+### query.ts:367 的兜底：防 sub-agent 绕过 shim
+
+`src/query.ts:367-380` 在每次 query 的收尾位置写了这段：
+
+```ts
+const gPerf = globalThis.performance
+if (gPerf && typeof gPerf.clearMarks === 'function') {
+  try {
+    gPerf.clearMarks()
+    gPerf.clearMeasures?.()
+    gPerf.clearResourceTimings?.()
+  } catch {
+    // Non-critical — some environments may not support all methods
+  }
+}
+```
+
+注释（`query.ts:367-370`）解释了为什么需要兜底："OTel references globalThis.performance which stores marks/measures/resource timings in a C++ Vector that never shrinks. Long-running sessions accumulate hundreds of MB of dead capacity even after spans are flushed and nullified."
+
+**为什么有了 shim 还要兜底**：某些 sub-agent 路径会**直接 `import query`**，而不经过 `cli.tsx` 的入口。如果那个进程的 shim 没装上（比如测试环境、嵌入式调用），原生的 `performance` 还在，每次 query 累积的 marks 就会泄漏。这段兜底调的是 `globalThis.performance`（已经被 shim 替换过的话就是 shim 的 `clearMarks`，没有的话就是原生的），作为"shim 没生效时的保险栓"。
+
+注意这个兜底是**尽力而为**：原生 `clearMarks()` 在 JSC 上即使能调，C++ Vector 也不收缩（见上面 shim 注释）。所以兜底主要救的是 shim 已装但 Map 需要清空的场景，以及"sub-agent 没装 shim 但又想尽力"的场景。
+
+### 6,889 个 _debugStack Error 对象：开发模式下看不见的 12MB
+
+打开 `build.ts:26-31`：
+
+```ts
+define: {
+  ...getMacroDefines(),
+  // React production mode — eliminates _debugStack Error objects
+  // (6,889 objects × ~1.7KB = 12MB in dev builds) and removes
+  // prop-type / key warnings not useful in a production CLI tool.
+  'process.env.NODE_ENV': JSON.stringify('production'),
+},
+```
+
+React 在开发模式下（`process.env.NODE_ENV !== 'production'`）会为每次组件渲染构造一个 `Error` 对象，用于捕获调用栈、生成 `_debugStack` 字段。这在浏览器开发工具里有用，但在 CLI 工具里就是纯内存浪费：6,889 个 `Error` 对象，每个约 1.7KB，合计约 12MB。
+
+`vite.config.ts:124` 的对应位置注释（"6,889 objects × ~1.7KB = 12MB in dev builds"）和 `build.ts` 的注释互相印证。这就是为什么 build 强制 `NODE_ENV='production'`——不是审美，是实打实的 12MB。
+
+### cli.tsx:44 的 CLAUDE_CODE_REMOTE 内存注入
+
+打开 `src/entrypoints/cli.tsx:42-49`：
+
+```ts
+// Set max heap size for child processes in CCR environments (containers have 16GB)
+if (process.env.CLAUDE_CODE_REMOTE === 'true') {
+  const existing = process.env.NODE_OPTIONS || '';
+  process.env.NODE_OPTIONS = existing
+    ? `${existing} --max-old-space-size=8192`
+    : '--max-old-space-size=8192';
+}
+```
+
+注释写得很直白："containers have 16GB"。这是项目对容器环境（Claude Code Remote / CCR）的**硬编码假设**：容器至少有 16GB 内存，所以子进程堆上限可以放心设到 8GB。
+
+**为什么硬编码 8GB 而不是按容器实际内存动态算**：因为 `NODE_OPTIONS` 必须在子进程启动前设置，而那时还没有可靠的"当前容器内存上限"查询方式（cgroup 接口在不同运行时下行为不一）。8GB 是一个保守的"16GB 容器的一半给堆"的工程经验值。
+
+**为什么这段代码在 cli.tsx 顶层而不是 init.ts**：和 `CLAUDE_CODE_ABLATION_BASELINE`（`cli.tsx:56`）是同一个原因——子进程一启动就要读 `NODE_OPTIONS`，`init()` 跑得太晚。这是入口文件的"副作用顶层化"模式。
+
+### distRoot.ts：vendor 二进制路径解析
+
+打开 `src/utils/distRoot.ts:15-27`：
+
+```ts
+const distRoot = (() => {
+  const parts = __dirname.split(path.sep)
+  const distIdx = parts.lastIndexOf('dist')
+  if (distIdx !== -1) {
+    return parts.slice(0, distIdx + 1).join(path.sep)
+  }
+  // Dev mode: from src/utils/ → project root
+  const srcIdx = parts.lastIndexOf('src')
+  if (srcIdx !== -1) {
+    return parts.slice(0, srcIdx).join(path.sep)
+  }
+  return __dirname
+})()
+```
+
+代码分割之后，chunk 文件散落在 `dist/` 或 `dist/chunks/` 下，但 vendor 二进制（ripgrep、audio-capture）在 `dist/vendor/`。chunk 文件需要能在运行时定位到 vendor 目录。`distRoot` 用 `lastIndexOf('dist')` 或 `lastIndexOf('src')`（dev 模式）反向定位根目录。
+
+**为什么不用 `import.meta.url` 的相对路径推算**：因为 chunk 文件名带 hash（`chunks/[name]-[hash].js`），嵌套层级不固定；`ripgrep.ts` / `computerUse/setup.ts` / `claudeInChrome/setup.ts` / `updateCCB.ts` 都依赖这个共享函数。CLAUDE.md 的"尾声"章节提到一个相关坑：`vendor/ripgrep/arm64-darwin` 二进制如果缺失，Grep 工具会 spawn 该路径并 ENOENT——`distRoot` 的 vendor 复制逻辑（`build.ts:91-93`）就是为了保证构建产物里 vendor 二进制存在。
+
+### 性能预算与 token 预算的耦合
+
+内存预算之外还有 token 预算：`TOKEN_BUDGET` feature 与 `/cost` / `/usage` 联动。token 预算直接影响单轮 API 调用的延迟和费用，但它和内存预算是**正交**的——压缩上下文（省 token）不一定释放内存（JSC Vector 不收缩），释放内存（重启进程）也不一定省 token（上下文还在持久化存储里）。
+
+用户看到"卡"时，往往分不清是哪一类预算耗尽。这正是性能主题必须双视角覆盖的原因：产品视角教用户**按症状分流**（上下文卡 vs 内存卡），设计视角解释**为什么分流之后内存卡还是救不回来**。
+
+## 两视角如何呼应
+
+用户视角的痛点几乎都能在设计视角找到对应的运行时约束：
+
+- **"长会话越用越卡，重启就好"**（产品视角）对应 **"JSC 的 C++ Vector 永不收缩 + performanceShim 必须最先 import"**（设计视角）——用户看到的是 RSS 上涨，根因在 JSC 原生 Performance 对象的内存模型。设计视角的 shim 把大部分 `mark` / `measure` 重定向到 GC 可回收的 JS Map，但兜底代码（`query.ts:367`）承认 shim 可能被 sub-agent 绕过，所以用户侧的"重启就好"是最诚实的解法。
+- **"`/compact` 之后还是慢"**（产品视角）对应 **"token 预算与内存预算正交"**（设计视角）——`/compact` 压的是模型视角的上下文（省 token、省推理时间），但 REPL 里的消息对象、JSC Vector 里的 marks 都还在内存里。这是为什么产品视角必须教用户区分"上下文卡"和"内存卡"。
+- **"容器里跑 Claude 会不会 OOM"**（产品视角）对应 **"cli.tsx:44 的 CLAUDE_CODE_REMOTE 内存注入硬编码 8GB"**（设计视角）——产品视角告诉用户"容器至少给 16GB"，设计视角解释为什么是 8GB 而不是动态算。
+- **"启动 `--version` 为什么也要几百 MB"**（隐含的工程好奇）对应 **"17MB 单文件让 RSS 涨到 1GB，必须代码分割"**（设计视角）——`--version` RSS 从 966MB 降到 35MB 是代码分割的直接收益，用户感知到的是"CLI 启动飞快"，背后是 JSC 全量解析 vs V8 懒解析的根本差异。
+
+这种呼应关系是性能章必须双视角覆盖的核心原因：产品视角告诉用户**遇到卡顿怎么办**，设计视角告诉用户**为什么有些卡顿只能重启**。两个视角合在一起，才能让使用者在"压缩、剪裁、清空、重启"之间做出正确选择，也让维护者在改性能相关代码时知道哪些约束是硬的、不能碰。

docs/outline-output/cross/03-security.md

@@ -0,0 +1,221 @@
+# 安全
+
+> 同一份 `sk-ant-...` 在使用者眼里是"我的密钥去了哪里、谁能看到"，在开发者眼里是"为什么用 0o600 写文件、为什么 ChatGPT 订阅要复用 `~/.codex/auth.json`、为什么 `bypassPermissions` 必须先检测是不是 root 或 sandbox"。安全天生是双视角主题——用户担心泄漏，开发者负责把每一处存储、刷新、传输、共享都设计成"即使被泄漏也尽量不致命"。
+
+## 产品视角（写给使用者）
+
+这一节回答三个问题：**我的密钥和令牌存在哪里**、**它们什么时候会被刷新或销毁**、**我把对话分享出去时哪些东西会跟着泄漏**。读完之后，你应该能判断"我能不能把这台机器借给同事"、"我能不能把这份 transcript 发到群里"。
+
+### 凭证存储位置清单
+
+Claude Code 把不同来源的凭证分散存在几个地方，不要把它们当成一个文件。下面这张表覆盖最常见的几类：
+
+| 凭证类型 | 存储位置 | 谁能读到 | 备注 |
+| --- | --- | --- | --- |
+| Anthropic OAuth 令牌 / 自定义 API key | `~/.claude/` 下的 secure storage（macOS Keychain / Windows Credential Manager / Linux libsecret） | 只有当前用户的操作系统账户 | `/logout` 会清掉它（见 `src/commands/logout/logout.tsx:24` 调 `removeApiKey()`） |
+| ChatGPT 订阅凭证（`OPENAI_AUTH_MODE=chatgpt`） | `~/.claude/openai-chatgpt-auth.json` | 任何能读这个文件的进程 | 文件用 `mode: 0o600` 写入（见 `src/services/api/openai/chatgptAuth.ts:162`），但仍然是明文 JSON |
+| Codex CLI 共享凭证 | `~/.codex/auth.json`（即 `CODEX_HOME/auth.json`） | 任何能读这个文件的进程 | Claude Code **只读不写**这个文件（`chatgptAuth.ts:342`）；如果 `~/.claude/openai-chatgpt-auth.json` 不存在，会回退去读它 |
+| Provider 环境变量（`OPENAI_API_KEY` 等） | 写进 `settings.json` 的 `env` 字段或 shell rc 文件 | 任何能读 settings 的进程 | `/provider` 命令切换 Provider 不清这些 key（见下文） |
+| 团队共享设置 | `<项目>/.claude/settings.json` | 仓库的所有 collaborator | **不要**把 key 写进团队 settings.json，写到 `settings.local.json` 或环境变量里 |
+| 个人覆盖设置 | `<项目>/.claude/settings.local.json` | 当前用户 | 默认被 git ignore，适合放本地 API key 之类 |
+
+一个高频误用：把 `OPENAI_API_KEY` 提交到了项目根目录的 `.claude/settings.json`，结果 push 到团队仓库所有人都看到了。**正确做法**是放到 `.claude/settings.local.json`（git ignored）或者用 `apiKeyHelper`（`src/utils/settings/types.ts:255`，指向一个能输出 key 的本地脚本）。
+
+### 权限模式：让 Claude 在沙箱里干活
+
+权限模式控制 Claude 在执行工具调用之前是否需要按一次回车。用 `/permissions` 命令（`src/commands/permissions/permissions.tsx`）或 `settings.json` 的 `permissions.defaultMode` 字段切换：
+
+- `default` —— 文件写入、shell 命令等危险操作按规则匹配后**问你**（最常见）。
+- `acceptEdits` —— 文件编辑直接放行，shell 仍然问。
+- `plan` —— 只读分析，不允许任何写操作。
+- `auto` —— 自动分类器判定（需要 `TRANSCRIPT_CLASSIFIER` feature）。
+- `bypassPermissions` —— 全部放行，**不要在普通环境用**。
+
+`bypassPermissions` 是这条链上最危险的模式，所以代码里有专门的"环境硬性检测"（`src/setup.ts:391-435`）：在你以 root/sudo 身份启动它、或者环境既不是 Docker 也不是 Bubblewrap 也不是 `IS_SANDBOX=1`、还连着外网的情况下，CLI 会**直接退出**并报错 `--dangerously-skip-permissions cannot be used in Docker/sandbox containers with no internet access`。换句话说，bypass 只允许在"无网 + 沙箱容器"的组合里用。这是有意把滥用路径堵死。
+
+权限规则本身写在 `settings.json` 的 `permissions.allow` / `deny` / `ask` 里（schema 在 `src/utils/settings/types.ts:42-55`），用 `/permissions` 命令可视化编辑。规则按"工具名 + glob 路径"匹配，比如 `Bash(npm install:*)` 表示允许所有 `npm install ...` 命令；`Read(~/.ssh/**)` 表示禁止读 ssh 目录。**deny 永远赢过 allow**，这是优先级铁律（详见 `src/utils/permissions/permissions.ts`）。
+
+### OAuth 令牌什么时候刷新、什么时候过期
+
+两种 OAuth 路径，各自有自己的刷新窗口：
+
+- **ChatGPT 订阅路径** —— `chatgptAuth.ts:9` 定义了 `REFRESH_SKEW_MS = 5 * 60 * 1000`，意思是"令牌距离过期不到 5 分钟时就主动刷新"。每次调用 `getValidChatGPTAuth()`（`chatgptAuth.ts:339`）都会先 `getTokenExpiryMs` 检查，到点就 `refreshTokens` + `saveStoredAuth`。**用户侧含义**：只要你的网络能通到 `auth.openai.com`，令牌永远不会过期；如果断网超过令牌寿命（通常 1 小时），下一次调用会失败，需要重新 `/login`。
+- **Bridge 模式的会话 JWT** —— `src/bridge/jwtUtils.ts:52` 同样定义了 `TOKEN_REFRESH_BUFFER_MS = 5 * 60 * 1000`，加上 `FALLBACK_REFRESH_INTERVAL_MS = 30 * 60 * 1000` 和 `MAX_REFRESH_FAILURES = 3`。`createTokenRefreshScheduler` 会"在令牌过期前 5 分钟排一个 setTimeout"，失败 3 次后放弃。**用户侧含义**：Bridge 长会话（自托管 RCS、远程控制）理论上一周不掉线，但如果你看到 `bridge_token_refresh_no_oauth` 这种 diagnostic log，说明刷新链断了。
+
+**`/logout` 会做什么**：不止删 key。它会 `flushTelemetry()` 先把还没上报的埋点冲掉（防止组织数据泄漏，见 `logout.tsx:21` 的注释），然后 `removeApiKey()` + `removeChatGPTAuth()` + 清掉 secure storage + 清一堆缓存（betas、toolSchema、Grove、policyLimits），最后 `gracefulShutdownSync(0, 'logout')` 让进程退出。所以 `/logout` 是"重置到初次安装状态"的快捷方式。
+
+### `/share` 与 `/export` 的隐私边界
+
+这两个命令都把会话内容写到外部，但隐私处理完全不同：
+
+- **`/export`**（`src/commands/export/export.tsx`）—— 把会话渲染成纯文本**写到本地文件**。**没有任何脱敏**——你说了什么、Claude 回了什么、API key 是不是出现在消息里，全部原样写出去。这个命令的隐私边界就是"你自己机器上的文件系统"，把它交给同事之前请自己检查一遍。
+- **`/share`**（`src/commands/share/index.ts`）—— 把会话日志**上传到 GitHub Gist**（或 `0x0.st` 兜底）。默认 `--private`（私有 Gist），但 GitHub 的 private Gist 对**任何知道 URL 的人**都可读，所以本质上还是"URL 即权限"。`--mask-secrets` 旗标会触发 `maskSecrets()`（`share/index.ts:98`），用一组正则把 `sk-ant-*` / `sk-*` / `Bearer xxx` / `AKIA*`（AWS）/ `ghp_*` / `xoxb-*`（Slack）等常见 token 替换成 `[REDACTED_*]`（模式表在 `share/index.ts:53-92`）。
+
+**关键提醒**：`/share --mask-secrets` **不是银弹**。源码里那条 NOTE 写得很明确（`share/index.ts:89-91`）：
+
+> We intentionally do NOT redact generic ≥32-char hex strings because they match legitimate git commit SHAs and base64 content, producing garbled share output.
+
+也就是说，如果你的 token 长得像 32 位以上的 hex（比如某些自建服务的 token），它**不会被脱敏**。私有信息（内部文档片段、同事姓名、内部 URL）也完全不在脱敏范围里。**最稳的做法**：分享前用 `/export` 导到本地，自己过一遍再决定怎么发。
+
+### 跨工具凭证共享：和 Codex CLI 复用 auth
+
+如果你机器上同时装了 Codex CLI（OpenAI 官方 CLI），你会发现 ChatGPT 订阅登录会在两边都生效。这是因为 `getValidChatGPTAuth()`（`chatgptAuth.ts:339-346`）在 `~/.claude/openai-chatgpt-auth.json` 不存在时会**回退去读 `~/.codex/auth.json`**（`codexAuthFilePath()`，`chatgptAuth.ts:52`）。注释里写得很坦诚（`:344`）：`Using ChatGPT auth from Codex auth.json`。
+
+**隐私含义**：
+
+- 你在 Codex CLI 登录 ChatGPT，Claude Code 也能直接用，不需要再登一次。
+- 反过来不成立：Claude Code 的 `saveStoredAuth` 只写 `~/.claude/openai-chatgpt-auth.json`，不写 `~/.codex/auth.json`。
+- 如果你想完全隔离两个工具的凭证，设 `CODEX_HOME` 环境变量把 Codex 的目录指到别处（`chatgptAuth.ts:54`）。
+
+### `/provider unset` 只清 Provider 不清 key
+
+一个高频困惑：跑了 `/provider unset`，以为已经把 OpenAI 凭证清干净了。看 `src/commands/provider.ts:49-62`，它做的事是：清 `modelType` 设置 + 删 `CLAUDE_CODE_USE_*` 环境变量。**它不动**：
+
+- `OPENAI_API_KEY` / `GEMINI_API_KEY` / `GROK_API_KEY` 这些 key 环境变量（仍在 shell 或 settings.json 里）。
+- `~/.claude/openai-chatgpt-auth.json`（仍在磁盘上）。
+- OpenAI/Grok 客户端的模块级缓存（见设计视角）。
+
+要彻底清，必须跑 `/logout`（清凭证文件 + secure storage）+ 手动从 settings.json 删 key 环境变量 + 重启 CLI（清缓存）。
+
+## 设计视角（写给开发者）
+
+设计大纲原本没有"安全"章节，相关决策散落在 Provider、Bridge、权限系统各处。这一节把它们串起来，按"为什么这么存、为什么这么检、为什么这么共享"展开。每个决策背后都有一个具体的威胁模型或约束。
+
+### 为什么 ChatGPT 凭证用明文 JSON + 0o600，而不是 secure storage
+
+打开 `src/services/api/openai/chatgptAuth.ts:148-164`：
+
+```ts
+async function saveStoredAuth(tokens: ChatGPTAuthTokens): Promise<void> {
+  const path = authFilePath()
+  await mkdir(getClaudeConfigHomeDirLocal(), { recursive: true })
+  const body: StoredAuthFile = { auth_mode: 'chatgpt', tokens: { ... }, last_refresh: ... }
+  await writeFile(path, `${JSON.stringify(body, null, 2)}\n`, { mode: 0o600 })
+  await chmod(path, 0o600).catch(() => undefined)
+}
+```
+
+明文 JSON，文件权限 `0o600`（只有文件 owner 能读写）。**为什么不像 Anthropic OAuth 那样走 secure storage**？因为这套凭证要和 **Codex CLI 互操作**——Codex CLI 的存储格式就是 `~/.codex/auth.json` 明文 JSON（见 OpenAI 官方设计）。如果 Claude Code 把凭证塞进 macOS Keychain，Codex CLI 读不到，跨工具共享就做不到。
+
+`chmod 0o600` 是这个权衡下的最大补偿：文件本身明文（互操作需求），但 OS 层面把读权限收紧到当前用户。注意 `chmod` 那行有 `.catch(() => undefined)`——某些文件系统（比如 FAT32 挂载点）不支持 chmod，这种情况会静默失败但文件还是会被写出来。这是一个**优先可用性而非绝对安全**的设计选择。
+
+**根因**：跨工具互操作和强凭证存储在本地文件系统层面是冲突的。OpenAI 选择了明文 JSON，Claude Code 跟随这个选择才能复用凭证。
+
+### 为什么 `bypassPermissions` 必须先检测 root 和 sandbox
+
+`src/setup.ts:391-435` 是一段看起来啰嗦的检测代码，但它精确对应一个威胁模型："用户图省事用 `sudo claude --dangerously-skip-permissions` 启动"。在这种情况下，Claude 拿到的是 root 权限，所有文件（包括 `/etc/passwd`、其它用户的 home）都可读写可执行——bypass 模式就变成了"任意代码执行 root"。
+
+检测逻辑按"威胁递进"排：
+
+1. **第一道（`:397-408`）**：`process.getuid() === 0` 且不是 sandbox（`IS_SANDBOX !== '1'` 且 `CLAUDE_CODE_BUBBLEWRAP` 未设）——直接 `process.exit(1)`。这是"绝对禁止"层。注释里特意提到"TPU devspaces 要求 root"，所以留了 `IS_SANDBOX=1` 的逃生口。
+2. **第二道（`:410-434`，仅 `USER_TYPE === 'ant'`）**：进一步要求"必须是 Docker / Bubblewrap / IS_SANDBOX 容器"**且** "无外网"。`hasInternet` 这一条特别严：即使你套了 Docker，只要还能 ping 通外网，bypass 就被拒。
+
+**为什么对 `USER_TYPE === 'ant'` 特别严格**：Anthropic 内部用户的默认部署环境更复杂，代码里特意为内部用户加了"容器 + 无网"的双重要求（`:411` 那行 `process.env.USER_TYPE === 'ant'` 判断）。外部用户的判断只走第一道。
+
+**根因**：bypassPermissions 模式下整个权限管线被跳过，所以必须在它生效**之前**做环境断言。一旦放进去，再想限制就晚了——Claude 已经能跑任意 shell 命令了。这是一个"防御必须在威胁生效前完成"的典型例子。
+
+### 为什么 ACP 权限走"本地管线 + 远端委托"两段式
+
+`src/services/acp/permissions.ts:32-173` 的 `createAcpCanUseTool` 是 ACP 模式下所有工具调用的权限闸门。它不直接把每个调用都甩给远端客户端，而是分两段：
+
+1. **本地管线（`:79-106`）**：先跑 `hasPermissionsToUseTool`，让 deny / allow / bypassPermissions / acceptEdits 这些本地规则自己消化。如果本地已经能决定 allow 或 deny，**直接返回，不打扰远端**。
+2. **远端委托（`:108-172`）**：本地规则判定为 `ask` 时，才通过 `conn.requestPermission()` 把 `allow_always` / `allow_once` / `reject_once` 三个选项发给 ACP 客户端（VS Code、Cursor 等）。
+
+**为什么这么设计**：ACP 客户端可能是 IDE、Web UI、自研工具，它们不一定都有良好的权限 UI，而且每次 round-trip 都有延迟。如果连"用户已经 deny 的工具"都要去远端问一遍，体验会很糟。本地管线是"快速短路"，远端委托只在"真的需要人决策"时才触发。
+
+注意 `forceDecision !== undefined` 那一段（`:71-73`）：coordinator / swarm worker 场景会预绑定一个决策，跳过本地管线直接返回。这是"信任父进程已经做了决策"的快捷路径，避免子 worker 重复打断用户。
+
+### 为什么 `HasAppStateContext` 主动 throw 防嵌套
+
+打开 `src/state/AppState.tsx:57-64`：
+
+```ts
+const HasAppStateContext = React.createContext<boolean>(false);
+
+export function AppStateProvider({ children, ... }: Props): React.ReactNode {
+  const hasAppStateContext = useContext(HasAppStateContext);
+  if (hasAppStateContext) {
+    throw new Error('AppStateProvider can not be nested within another AppStateProvider');
+  }
+  // ...
+}
+```
+
+第一眼看起来像"开发者警告"，但它其实有**安全含义**。AppState 是整个应用的单一 store，包含 messages、tools、permissions、MCP 连接等敏感字段。如果允许嵌套，外层 Provider 的 children 里某个子组件 mount 了一个内层 Provider，内层的 store 就和外层**脱钩**——内层的 useAppState 拿到的是内层 store，permission 决策、消息历史、凭证状态全部错乱。
+
+具体的安全风险场景：一个恶意 MCP 工具或者插件组件如果不小心（或故意）渲染了一个 AppStateProvider，就有可能让一部分 UI 用着"被隔离的、权限被偷偷放宽"的 store。React Context 本身没有"防重复嵌套"机制，所以项目用 `HasAppStateContext` 这个布尔 context 主动 throw——**第一次 mount 时它从 false 变 true，第二次 mount 时读到 true 就抛错**。
+
+**根因**：单一 store 是"权限决策单一真相源"的前提。一旦允许多 store 嵌套，权限规则、bypass 状态、secure storage 引用都可能错配。这是"防御性编程"在 React Context 层的落地。
+
+### 为什么 Bridge 的 JWT 不验签
+
+`src/bridge/jwtUtils.ts:21-32` 的 `decodeJwtPayload` 函数注释里写得很坦诚：
+
+```ts
+/**
+ * Decode a JWT's payload segment without verifying the signature.
+ * Strips the `sk-ant-si-` session-ingress prefix if present.
+ */
+```
+
+只解码 payload，不验签。**为什么**？因为 Bridge 模式（自托管 RCS、远程控制）用的是"会话级 JWT"，签发和验证都在**同一进程**里完成（Anthropic 服务端签发，Bridge 进程消费）。签名校验在 TLS 层已经做了——Bridge 客户端到服务端的 WebSocket 是 `wss://`，传输层防了 MITM。在这个信任模型下，再做一次 JWT 验签只是徒增 CPU 开销。
+
+但这套设计的**前提**是"Bridge 进程本身没被入侵"。如果攻击者拿到了 Bridge 进程的内存，他们可以直接调 `getAccessToken()`（`jwtUtils.ts:168`）拿到 OAuth 令牌，根本不用伪造 JWT。所以威胁模型是"防网络层攻击，不防进程被入侵"。
+
+`createTokenRefreshScheduler`（`:72-256`）那 200 行的"失败重试 + generation counter + 30 分钟兜底 + 3 次失败放弃"逻辑，本质上是在防"刷新链断裂后会话静默掉线"——这是**可用性**防御，不是机密性防御。
+
+### 为什么 share 的脱敏用正则而不是结构化扫描
+
+`src/commands/share/index.ts:53-92` 的 `SECRET_PATTERNS` 表是一组正则，按"前缀 + 长度"匹配各类 token。**为什么不用 AST 解析 JSON、扫所有字符串字段**？
+
+因为 transcript 的内容**不是结构化的**——它是用户和 Claude 的自由对话，token 可能出现在 markdown 代码块里、可能出现在错误消息里、可能被 Claude 引用又转述了一遍。结构化扫描要么扫不到（被文本包裹），要么扫到太多（合法的长字符串被误判）。
+
+正则方案的优势是**精准按已知前缀匹配**：`sk-ant-` 是 Anthropic key 的固定前缀，`ghp_` 是 GitHub PAT 的固定前缀，`AKIA` 是 AWS key 的固定前缀。这些前缀是上游服务设计的"防误识别"机制，复用它们比自创规则更可靠。
+
+但代价就是 `share/index.ts:89-91` 那条 NOTE 承认的局限：**没有固定前缀的 token（hex、base64）无法脱敏**，因为它们和合法的 git SHA、文件 hash 无法区分。这是"宁可漏过，不可误杀"的设计选择——误杀会把 transcript 弄成 `[REDACTED]` 满屏飞，比漏掉少数 token 还糟。
+
+**根因**：在自由文本上做凭证脱敏是一个"召回率 vs 精确率"的权衡。share 选择了高精确率（固定前缀匹配），牺牲召回率（无前缀 token 漏过）。如果需要更强的脱敏，应该在源头（写入 transcript 之前）做，而不是在导出时亡羊补牢。
+
+### 为什么 `/logout` 必须先 flushTelemetry
+
+`src/commands/logout/logout.tsx:19-22` 的顺序看起来很奇怪：
+
+```ts
+export async function performLogout({ clearOnboarding = false }): Promise<void> {
+  // Flush telemetry BEFORE clearing credentials to prevent org data leakage
+  const { flushTelemetry } = await import('../../utils/telemetry/instrumentation.js');
+  await flushTelemetry();
+  await removeApiKey();
+  // ...
+}
+```
+
+注释里的"prevent org data leakage"是关键。OpenTelemetry 的 instrumentation 在用户登录状态下会带上"当前组织 ID、用户 ID"等元数据，这些数据要发到 Anthropic 的 telemetry 后端。如果你先 `removeApiKey()` 再 flush，flush 出去的 telemetry 是"未登录状态"的，但这些事件实际上发生在"登录状态"下——属性不匹配。
+
+更严重的场景：用户从 Org A 切到 Org B。如果先 clear 再 flush，A 状态下的事件可能被错误归因到 B 组织，泄漏 A 的活动给 B 管理员。先 flush 保证 A 状态下的事件还带着 A 的身份信息发出去，再 clear 切换身份。
+
+**根因**：telemetry 的"身份绑定"必须和"事件发生时机"一致。`/logout` 不是单纯的"删 key"，而是一次"身份切换的状态机迁移"，必须按正确顺序：flush（保留旧身份） → clear（切换到匿名） → reset caches（清旧身份相关的缓存） → shutdown（进程退出）。
+
+### 为什么 OpenAI 客户端是模块级缓存（设计取舍回顾）
+
+这个点在 cross/01-troubleshooting.md 已经详细讲过，这里只补充**安全含义**。`getOpenAIClient`（`src/services/api/openai/client.ts:39`）把首次创建的客户端缓存到模块级 `cachedClient`，整个会话不重建。
+
+**安全副作用**：会话中改 `OPENAI_API_KEY` 环境变量，**新 key 不会生效**，旧 key 仍在用。这听起来是 bug，但在另一个角度是**安全特性**：如果某个恶意脚本在会话中途改了 `OPENAI_API_KEY` 想劫持流量，它做不到——客户端已经被缓存，绑定的是原始 key。
+
+代价是"用户合法换 key"也得重启 CLI，这是性能优化（避免每次调用都重建 axios 实例）和安全性（绑定首次凭证）的共同产物。`clearOpenAIClientCache()`（`openai/client.ts:76`）是逃生口，但只在 SDK 嵌入场景（用户自己写脚本）才可见——普通 CLI 用户根本不知道这个函数存在，只能通过重启来清缓存。
+
+对比 `getAnthropicClient`（`client.ts:84`）：每次按 model/region 参数化新建，因为 AWS / GCP / Azure 凭证刷新、region 选择、header 注入都是**会话过程中可能变化的参数**。Anthropic 路径必须每次重新构造，所以它的"换 key 立即生效"行为是被动得到的，不是有意设计的。
+
+## 两视角如何呼应
+
+用户视角的每一个安全焦虑，几乎都能在设计视角找到对应的设计决策：
+
+- **"我的密钥存在哪里"**（产品视角）对应 **"ChatGPT 凭证为什么用明文 JSON + 0o600"**（设计视角）——明文是为了和 Codex CLI 互操作，0o600 是这个权衡下的补偿。用户看到的是"明文 JSON"，开发者看到的是"互操作和强存储的冲突"。
+- **"bypassPermissions 为什么被拒了"**（产品视角）对应 **"为什么 bypass 必须先检测 root 和 sandbox"**（设计视角）——用户看到的是"启动失败报错"，开发者看到的是"防御必须在威胁生效前完成"。
+- **"令牌什么时候过期"**（产品视角）对应 **"为什么 OAuth 用 5 分钟刷新窗口"**（设计视角）——用户看到的是"自动续期"，开发者看到的是"刷新链断裂后的 3 次重试 + 30 分钟兜底"。
+- **"`/share --mask-secrets` 会不会泄漏"**（产品视角）对应 **"为什么脱敏用正则而不是结构化扫描"**（设计视角）——用户看到的是"已脱敏"标签，开发者看到的是"召回率 vs 精确率权衡 + 无前缀 token 漏过的诚实交代"。
+- **"`/logout` 真的清干净了吗"**（产品视角）对应 **"为什么必须先 flushTelemetry 再清凭证"**（设计视角）——用户看到的是"重置到初次安装"，开发者看到的是"telemetry 身份绑定的状态机迁移"。
+- **"我把项目 settings.json push 到团队仓库会怎样"**（产品视角）对应 **"settings.json vs settings.local.json 的分层"**（设计视角）——用户看到的是"哪些文件会被共享"，开发者看到的是"团队设置和个人覆盖的优先级"。
+- **"Codex CLI 登录的 ChatGPT 凭证 Claude 能用吗"**（产品视角）对应 **"为什么 chatgptAuth 回退读 `~/.codex/auth.json`"**（设计视角）——用户看到的是"两边都生效"，开发者看到的是"跨工具凭证互操作的有意设计"。
+
+这种呼应关系是安全章必须双视角覆盖的核心原因：用户视角告诉你**怎么用才安全**，设计视角告诉你**这个安全机制覆盖了什么、没覆盖什么**。两个视角合在一起，才能让使用者正确评估"我能把这台机器借给同事吗"、"我能把这份 transcript 发到群里吗"这类问题——不会盲目信任某个"已脱敏"标签，也不会因为某个明文 JSON 就以为整套凭证管理都不安全。

docs/outline-output/cross/04-upgrade-versioning.md

@@ -0,0 +1,187 @@
+# 升级与版本管理
+
+> 同一个 `2.7.0` 在使用者眼里是"该不该 `claude update`、`claude doctor` 里那个 latest 是不是真的比我新"，在开发者眼里是"为什么 `MACRO.VERSION` 必须从 `package.json` 反推、为什么 `--version` 走零模块加载 fast-path、为什么 Bedrock 那段针对性补丁必须留一段写着 probe 文件路径的注释"。升级和版本管理天生是双视角主题——用户想知道"怎么升、升完会不会坏"，开发者想知道"版本号从哪里来、补丁什么时候才能拆"。
+
+## 产品视角（写给使用者）
+
+这一节回答三个问题：**我怎么知道该不该升级**、**怎么升**、**升完之后老的行为会不会变**。读完之后，你应该能判断"我现在跑的版本是不是最新的"、"这次升级会不会把我正在用的 Provider 弄坏"。
+
+### 我怎么知道该不该升级
+
+两条路，任选其一：
+
+- **跑 `claude doctor`**。这是最稳的诊断入口，对应 `src/commands/doctor/doctor.tsx`（命令本身在 `src/commands/doctor/index.ts` 注册）。它会渲染一个 `Doctor` 屏幕（`src/screens/Doctor.tsx`），里面分三段对你最有用的信息：
+  - **Diagnostics** 段：`Currently running: <type> (<version>)`、安装路径、被哪个二进制调用、ripgrep 是否可用（`Doctor.tsx:218-232`）。如果你装了多个版本（npm-global + native + package-manager 混着装），这里会显式 warn `Multiple installations found` 并把每个安装的 type 和 path 列出来（`Doctor.tsx:244-254`）。多安装是升级后行为飘移最常见的根因——你 `claude update` 升的是某一个，shell 里 `claude` 还指向另一个。
+  - **Updates** 段：`Auto-updates` 的开关、`Update permissions: Yes/No (requires sudo)`、`Auto-update channel`（`latest` 或 `stable`），以及从远端拉下来的 `Stable version` / `Latest version`（`Doctor.tsx:279-289`，远端版本走 `getGcsDistTags` 或 `getNpmDistTags`，见 `Doctor.tsx:91-98`）。
+  - **Version Locks** 段（仅当 PID-based locking 启用时）：列出当前被锁住的版本和持有它的 PID（`Doctor.tsx:311-328`）。如果你看到某个 lock 标了 `(stale)`，说明上次升级被中断了，残留了一个进程没清掉的锁。
+- **直接跑 `claude --version`**（或 `claude -v` / `claude -V`）。这是最快的路径，只打印一行 `<version> (Claude Code)` 就退出（`src/entrypoints/cli.tsx:80-84`）。**注意**：它只告诉你"当前跑的是几"，不会告诉你"远端最新是几"——要对比必须用 `claude doctor`。
+
+`claude doctor` 还会顺带帮你把一堆"升级之后可能出问题"的信号检查一遍：env 变量是否超上限（`BASH_MAX_OUTPUT_LENGTH` / `TASK_MAX_OUTPUT_LENGTH` / `CLAUDE_CODE_MAX_OUTPUT_TOKENS`，见 `Doctor.tsx:103-128`）、settings 有没有 schema 错误、agent 文件有没有解析失败、MCP server 有没有 parsing warning、keybindings 有没有冲突。升级前先跑一次 `claude doctor`、升级后再跑一次对比，是排错最高效的姿势。
+
+### 怎么升
+
+跑 `claude update`（注册在 `src/main.tsx:5346-5353`，实现是 `src/cli/updateCCB.ts` 的 `updateCCB()`）。它会做这几件事：
+
+1. 读当前版本：先尝试从 `distRoot` 上层的 `package.json` 读 `version`，读不到就退回 `MACRO.VERSION`（`updateCCB.ts:18-29`）。这一步保证"全局装的 ccb"和"开发模式下跑的 cli.tsx"看到的是同一个版本号。
+2. 探测包管理器：先看当前进程是不是从 bun 起的（`process.execPath` 含 `bun`，或者 `~/.bun/install/global/node_modules/claude-code-best` 存在），是就用 bun；否则用 npm（`updateCCB.ts:56-77`）。
+3. 从 npm registry 拉 latest 版本号：`npm view claude-code-best@latest version --prefer-online`（`updateCCB.ts:79-90`），10 秒超时。
+4. 比较：如果 `current >= latest`，直接打印 `ccb is up to date (<version>)` 退出；否则继续（`updateCCB.ts:113-122`）。
+5. 实际装：`bun install -g claude-code-best@latest` 或 `npm install -g claude-code-best@latest`，120 秒超时（`updateCCB.ts:131-152`）。
+
+升级完成之后**必须重启 `claude`**。原因有两条：
+
+- `claude update` 只动磁盘上的文件，不动当前正在运行的进程内存。你的 REPL 还跑着旧代码。
+- 多个兼容层的客户端（OpenAI / Grok）走的是模块级缓存（见 cross/03-security.md 的"为什么 OpenAI 客户端是模块级缓存"），重启之外没有任何方式让它们重新读 key 和 endpoint。
+
+如果 `claude update` 失败，错误信息会直接建议你手动跑对应的 `bun install -g claude-code-best@latest` 或 `npm install -g claude-code-best@latest`（`updateCCB.ts:155-173`）。这两个命令本质上和 `claude update` 跑的是同一条 shell，区别只是 `claude update` 多了一层"探测包管理器 + 比较版本"的逻辑——失败时跳过这层逻辑直接装 latest 是最快的恢复方式。
+
+### 升级之后老的行为会不会变
+
+会，但只有两种情况值得你担心：
+
+- **版本号最小限制**。`assertMinVersion()`（`src/utils/autoUpdater.ts:79-111`）会在启动时从远端 Statsig config `tengu_version_config` 读 `minVersion`，如果你跑的版本低于这个值，CLI 会**直接退出**并打印 `It looks like your version of Claude Code (<version>) needs to update`。这是服务端 kill switch——某些重大变更（API schema 不兼容、安全修复）上线时，官方会把这个值推高，强制所有人升级。**用户侧含义**：如果你某天打开 `claude` 发现它拒绝启动并提示要 update，先 `claude update` 再说。
+- **最大版本回退**。`getMaxVersion()`（`autoUpdater.ts:125-141`）从同一个远端 config 读 `external` / `ant` 字段，作为"当前允许的最高版本"。这是 incident 时的紧急刹车——如果新版本被发现有严重 bug，官方会把 max 版本设到上一个稳定版，auto-updater 就不会把用户升到坏版本。**用户侧含义**：你手动 `claude update` 后看到的版本可能比 npm registry 上的 `latest` 旧，这是有意的回退，不是你装错了。
+
+注意 `assertMinVersion` 的注释（`autoUpdater.ts:46-60`）专门讲了一处容易混淆的设计：版本号格式 `X.X.X+SHA`（continuous deployment 用的带 build metadata 的 semver）里，**比较版本大小**（`assertMinVersion`）会忽略 `+SHA`，**检测是否有更新**（`claude update`）会用精确字符串比较不忽略。所以你可能看到 `claude --version` 显示 `2.7.0+abc123`、npm 上 latest 也是 `2.7.0`，但 `claude update` 还是会重新装一遍——因为它在比 SHA，发现你本地的 SHA 不是最新的。这不是 bug，是为了让 continuous deployment 的每次 commit 都能推到用户。
+
+### 升级前自检清单
+
+- `claude doctor` 看一下 `Auto-update channel`、`Update permissions`、有没有 `Multiple installations found` 警告。多安装的情况下先想清楚 shell 里 `which claude` 指向哪一个。
+- 如果你在用 OpenAI / Gemini / Grok 兼容层，记录一下当前 `OPENAI_API_KEY` / `GEMINI_API_KEY` / `GROK_API_KEY` 的值（升级本身不动 key，但万一升级过程中断了重装，可能要重设）。
+- 如果你在 Bridge / Daemon / 后台 session 模式下长跑，升级前先 `claude daemon stop` / `claude kill` 把它们停掉——升级会替换二进制，但不会通知正在跑的进程。
+
+## 设计视角（写给开发者）
+
+设计大纲原本只在第二章入口链里点了一句"版本号单一来源 `package.json`"。这一节把版本号怎么流到运行时、针对性补丁什么时候该拆、双构建管线的版本一致性这三件事讲透。每个决策背后都有一个具体的约束（漂移、SDK 漏洞、bun/node 双运行时）。
+
+### 为什么版本号必须从 `package.json` 反推，而不是 hardcoded
+
+打开 `scripts/defines.ts:7-24`：
+
+```ts
+const pkgPath = resolve(__dirname, '..', 'package.json')
+const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+
+export function getMacroDefines(): Record<string, string> {
+  return {
+    'MACRO.VERSION': JSON.stringify(pkg.version),
+    'MACRO.BUILD_TIME': JSON.stringify(new Date().toISOString()),
+    // ...
+  }
+}
+```
+
+注释里写得很直白：`VERSION is read from package.json to avoid version drift`。版本号如果既写在 `package.json`、又写在 `defines.ts`、又出现在某处字符串字面量，发版时一定有人忘了同步其中一个，用户看到的 `claude --version` 就会和 npm 上的版本对不上。
+
+但"单一来源"的实现路径很有意思——它必须穿过三层 MACRO 注入才能到达运行时：
+
+1. **dev 模式**：`scripts/dev.ts:18-29` 把 `getMacroDefines()` 的返回值用 `-d` flag 一条条传给 `bun run`。注释（`dev.ts:5-9`）专门解释了为什么不用 `bunfig.toml` 的 `[define]`——因为它不会传播到 dynamically imported modules。
+2. **build 模式**：`build.ts` 把同样的 defines 喂给 `Bun.build({ define })`，由 Bun 编译器在 transpile 阶段做字面量替换。
+3. **运行时兜底**：如果有人直接跑 `bun src/entrypoints/cli.tsx`（既不走 `bun run dev` 也不走 dist/），`cli.tsx:9-21` 会检测 `globalThis.MACRO === undefined` 并填一个 fallback，`VERSION` 从 `process.env.CLAUDE_CODE_VERSION || '2.1.888'` 取。这个 `'2.1.888'` 是写死的 fallback——它只在"完全脱离工具链直接跑源码"时才出现，正常使用路径上永远不会看到这个版本号。
+
+**为什么 `--version` fast-path 必须零模块加载**：`cli.tsx:79-84` 的逻辑只有一行 `console.log(\`${MACRO.VERSION} (Claude Code)\`)`。这之所以能做到"零模块加载"，恰恰是因为 `MACRO.VERSION` 在 transpile 阶段就已经被替换成了字面量字符串——运行时不需要 import 任何东西就能拿到版本号。如果版本号是从某个模块的 `getVersion()` 函数读出来的，`--version` 就必须 import 那个模块，fast-path 就破了。**版本号的单一来源约束反过来塑造了 fast-path 的实现方式**——这是约束驱动设计的一个干净例子。
+
+### `claude update` 为什么自己重新发明了版本比较，而不是用现成的 semver 库
+
+看 `src/cli/updateCCB.ts:124-134`：
+
+```ts
+function gte(a: string, b: string): boolean {
+  const parseVer = (v: string) => v.replace(/^\D/, '').split('.').map(Number)
+  const pa = parseVer(a)
+  const pb = parseVer(b)
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] ?? 0) > (pb[i] ?? 0)) return true
+    if ((pa[i] ?? 0) < (pb[i] ?? 0)) return false
+  }
+  return true
+}
+```
+
+一个手写的、只有 8 行的 `gte`。**为什么不复用 `src/utils/semver.ts`**？因为 `updateCCB.ts` 是一个**必须能独立运行的子命令**——它从 `getCurrentVersion()` 开始就要能在"用户刚装好 ccb、还没装依赖"的极简环境下工作。它 import 的全是 `node:child_process` / `node:fs` / `node:os` 这种 zero-dependency 标准库，加上项目内部的 `distRoot` / `execFileNoThrowWithCwd` / `gracefulShutdown` / `process` / `debug` / `chalk`。`semver.ts` 依赖的图更大，引入它会让 updateCCB 的启动时间变长、潜在故障面变大。
+
+代价是这个 `gte` **不处理 build metadata**：`2.7.0+abc` 和 `2.7.0+def` 在这个比较里是相等的。`updateCCB.ts:120` 那条 `latestVersion === currentVersion || gte(currentVersion, latestVersion)` 的 `||` 短路就是补偿——先用精确字符串比较（能区分 SHA），相等了再退到手写 semver 比较（防 latest 比当前旧这种边界情况）。这个组合策略和 `autoUpdater.ts:46-60` 那段注释承认的"两套比较逻辑并存"是同一个权衡的延伸。
+
+### Bedrock 补丁为什么必须留一段写着 probe 文件路径的注释
+
+这是整个项目里最有"工程纪律"感的一段代码。打开 `src/services/api/bedrockClient.ts:1-35`：
+
+```ts
+/**
+ * Extends AnthropicBedrock to work around an upstream bug where the SDK
+ * re-plants the `anthropic-beta` HTTP header value into the request body
+ * as `anthropic_beta`. Bedrock's Opus 4.7 endpoint rejects any request with
+ * `anthropic_beta` in the body with a 400 "invalid beta flag" error.
+ *
+ * Source of the bug (SDK 0.26.4, still present through 0.28.1):
+ *   node_modules/@anthropic-ai/bedrock-sdk/client.js lines 122-127
+ *
+ * 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.
+ */
+```
+
+这段注释干了两件不寻常的事：
+
+1. **精确锁定漏洞的范围**：SDK 版本（0.26.4-0.28.1）、出问题的源码行号（`client.js` 122-127）、错误现象（body 里多了 `anthropic_beta` 字段、Opus 4.7 返回 400）、上游 issue 编号（`anthropics/claude-code#49238`）。所有信息都精确到能在 5 秒内验证。
+2. **指明补丁的拆除条件**：当上游修复后，跑某个 probe 脚本确认 bug 不再复现，就可以**删掉整个 `BedrockClient` 类**，把 `services/api/client.ts` 改回直接 `new AnthropicBedrock(...)`。
+
+**值得注意的事实**：注释里提到的 `scripts/probe-bedrock-beta-fix.ts` **目前并不存在于仓库里**（`find scripts -name '*probe*'` 只能找到 `probe-local-wiring.ts` 和 `probe-subscription-endpoints.ts`）。这不是文档错——这是注释作者留下的**意图标记**：补丁本身写了，但配套的"自动检测修复后能否拆除"的 probe 脚本还没补。读者看到这段注释时，应该理解成"这个补丁是临时的，未来某天上游修了就要拆，但目前没人持续监控上游 SDK 的变化"。
+
+这正是 probe 模式的**价值与代价**：
+
+- **价值**：每个针对性补丁都明确标注"我为什么存在、什么时候可以消失"。两年后某个新人接手代码，看到 `BedrockClient` 不会一脸懵——他能从注释里立刻判断"这个补丁还要不要留"。
+- **代价**：probe 脚本必须有人维护。注释里写的那个文件不存在，意味着拆除条件目前**没有自动验证**——上游 SDK 升级到修复版之后，没有人会被自动通知"现在可以删 BedrockClient 了"。补丁会一直留着，直到某次 code review 有人手动翻到这段注释、手动验证、手动拆。
+
+**根因**：针对性补丁是技术债的一种特殊形态——它承认"我在等上游修"。probe 模式是把这种"等"变得**可追踪**：每段补丁都自带拆除说明书。但说明书本身不会自动执行，所以 probe 模式的实际效果取决于团队是否真的定期跑 probe。这个项目目前的状态是"说明书有了，自动化还没跟上"。
+
+### 为什么 MACRO 必须用编译期字面量替换，而不是运行时函数
+
+版本号和构建时间这种常量，理论上完全可以写成一个普通的 `export const VERSION = pkg.version`。为什么非要走 MACRO 编译期替换？
+
+答案藏在 `--version` 的 fast-path 设计里。如果 VERSION 是普通 export，`cli.tsx:80-84` 那段代码就必须 `import { VERSION } from '...constants...'`，这次 import 会触发常量模块所在依赖图的解析——`constants/` 里如果还有别的导出、还有别的副作用，fast-path 就不再是"零模块加载"。
+
+MACRO 替换绕开了这个问题：`MACRO.VERSION` 在 transpile 阶段被替换成字符串字面量 `'2.7.0'`，运行时 `cli.tsx` 里那行就是 `console.log(\`2.7.0 (Claude Code)\`)`——没有任何 import、没有任何模块解析、没有任何副作用。`--version` 的 RSS 因此能从"加载整个 CLI"降到几十 MB（见 cross/02-performance-memory.md）。
+
+这个选择还顺手解决了**dev 和 build 的版本号一致性**：`dev.ts` 和 `build.ts` 都从同一个 `getMacroDefines()` 读 defines（`defines.ts:14`），所以 dev 模式跑出来的 `--version` 和 build 出来的 dist 跑出来的 `--version` 一定是同一个值。如果走 `export const VERSION`，dev 模式读源码 `package.json`、build 模式读 build 时打包进去的 `package.json`，两边就有漂移风险。
+
+**根因**：MACRO 不是"为了语义清晰而引入的抽象"，而是"为了让 fast-path 真的快、为了让 dev/build 版本一致而被迫引入的编译期机制"。它是性能和一致性约束的共同产物。
+
+### 双构建管线（Bun.build vs Vite）的版本号一致性
+
+项目有两套构建管线（详见设计大纲第一章）：`build.ts` 跑 `Bun.build()`、`vite.config.ts` 跑 Vite。两者都从 `scripts/defines.ts` 读 MACRO defines：
+
+- **Bun.build 路径**：`build.ts` 直接调 `getMacroDefines()` 喂给 `Bun.build({ define })`。
+- **Vite 路径**：`scripts/vite-plugin-feature-flags.ts` 在 transform 阶段做字面量替换。
+
+两条路径用的是同一个 defines 函数，所以产物的版本号一致。这看起来是显然的，但它是**有意设计**——如果两条路径各自硬编码版本号、或各自从不同地方读，就会有"Vite 构建的 `--version` 和 Bun 构建的 `--version` 不一致"这种诡异 bug。`defines.ts` 既是单一来源，也是两条管线的契约。
+
+构建后还有一道独立的 post-process（`build.ts:43-46`）：把 `import.meta.require` 替换成 `typeof import.meta.require === "function" ? import.meta.require : (await import("module")).createRequire(import.meta.url)`。这道 patch 让产物**同时兼容 bun 和 node**——同一份 dist 文件，bun 跑用 `import.meta.require`（Bun 原生支持），node 跑用 `createRequire`（Node 标准 API）。这是双入口 `cli-bun.js` / `cli-node.js` 能共用同一份 chunk 的前提。
+
+### 升级流程为什么不走"热替换"
+
+`claude update` 装完新版本后，**当前进程不会被替换**。REPL 还跑着旧代码，直到用户手动退出重开。为什么不像浏览器那样做热替换？
+
+打开 `cli/updateCCB.ts:131-152` 看实际逻辑：它跑的是 `execSync('bun install -g ...@latest')` 或 `execSync('npm install -g ...@latest')`。这是**子进程同步执行**，完成后新文件就位，但**父进程（当前 REPL）的 require 缓存、模块级 const、模块级 client 缓存全部不动**。
+
+热替换需要解决三个难题：
+
+1. **模块级缓存的失效**。`getOpenAIClient` / `getGrokClient`（见 cross/03-security.md）把客户端实例缓存到模块级变量，热替换要遍历所有这些模块、清掉缓存。
+2. **模块级 const 的重捕获**。`cli.tsx:56-69` 那段 ablation 逻辑，`BashTool` / `AgentTool` / `PowerShellTool` 在 import 时就把环境变量捕获进模块级 `const`。热替换要重新 import 这些模块，让 const 重新捕获——但这意味着工具实例全部重建，正在跑的 agent / 后台 task 全部丢失。
+3. **React 状态树的保留**。REPL 是 Ink 渲染的 React 树，messages / tools / MCP 连接全是 state。热替换要保证 state 不丢——但新版代码的 state shape 可能变了（schema migration）。
+
+三个难题都没好解。所以项目选择了一个朴素但鲁棒的方案：**升级只动磁盘，重启靠用户**。代价是多了一次手动重启，收益是绝对不会出现"半新半旧"的不一致状态。这个权衡和 `/logout` 必须先 flushTelemetry 再清凭证（见 cross/03-security.md）是同一种风格——**宁可让用户多做一步，也不接受状态不一致**。
+
+## 两视角如何呼应
+
+用户视角的每一个升级困惑，几乎都能在设计视角找到对应的设计决策：
+
+- **"我怎么知道该不该升"**（产品视角）对应 **"`--version` 为什么是零模块加载 fast-path"**（设计视角）——用户看到的是"一行命令秒出"，开发者看到的是"MACRO 编译期替换让版本号成为字面量、绕开 import 触发的模块解析"。
+- **"`claude update` 装的是哪个版本"**（产品视角）对应 **"为什么版本号必须从 `package.json` 反推"**（设计视角）——用户看到的是"升级提示很准"，开发者看到的是"`scripts/defines.ts` 的单一来源约束 + dev/build 双管线共用同一个 defines 函数"。
+- **"为什么 `claude update` 之后还要手动重启"**（产品视角）对应 **"为什么升级不走热替换"**（设计视角）——用户看到的是"多一步操作"，开发者看到的是"模块级缓存 + 模块级 const + React state 三重难题的工程权衡"。
+- **"为什么我的版本号带 `+SHA` 后缀，npm 上的 latest 看起来一样却还是要重装"**（产品视角）对应 **"`assertMinVersion` 的两套比较逻辑"**（设计视角）——用户看到的是"莫名其妙的重复升级"，开发者看到的是"continuous deployment 的 SHA 比较与 semver 比较并存的诚实设计"。
+- **"Bedrock 报 400 invalid beta flag 怎么办"**（产品视角，详见 cross/01-troubleshooting.md）对应 **"BedrockClient 为什么必须留 probe 注释"**（设计视角）——用户看到的是"升级 SDK 之后某个错误消失了或出现了"，开发者看到的是"针对性补丁的拆除条件被写成注释、probe 脚本作为意图标记但当前仓库里还没建"。
+- **"升级之后 key 还在不在"**（产品视角）对应 **"升级为什么只动磁盘不动进程"**（设计视角）——用户看到的是"key 不变、设置不变"，开发者看到的是"`updateCCB.ts` 只跑 npm/bun install、完全不碰 ~/.claude/ 下的凭证文件"。
+
+这种呼应关系是升级与版本管理章必须双视角覆盖的核心原因：用户视角告诉你**怎么升才安全**，设计视角告诉你**这个升级机制覆盖了什么、没覆盖什么**。两个视角合在一起，才能让使用者正确评估"我现在该不该升、升完之后哪些东西会变、哪些不会变"——不会盲目相信"升级就是好的"，也不会因为某次升级出过 bug 就永远不敢再升。

docs/outline-output/cross/05-tool-integration.md

@@ -0,0 +1,170 @@
+# 与其他工具集成
+
+> 同一个"接入外部工具"的动作，在使用者眼里是"我能在 VS Code / Zed / Cursor / GitHub Actions / Codex CLI 里用 Claude 吗、要装什么、凭证怎么走"，在开发者眼里是"为什么 IDE 走 MCP 的 `sse-ide` / `ws-ide` 子类型、为什么 ACP agent 用 stdio NDJSON、为什么 ChatGPT 订阅凭证要 fallback 读 `~/.codex/auth.json`、为什么 `install-github-app` 是 React 多步表单而不是一行 shell"。集成天然是双视角主题——用户想知道"能不能接、怎么接"，开发者想知道"边界在哪、契约长什么样、为什么这样切"。
+
+## 产品视角（写给使用者）
+
+这一节回答一个最高频的问题：**我能在 X 里用 Claude 吗？** 答案按"接入形态"分成五类，每类给一个清单式的"做什么 → 怎么做"。
+
+### 第一类：把 Claude 接进 IDE（VS Code / Cursor / Windsurf / JetBrains / Zed）
+
+你能在主流 IDE 里得到一个能看见当前工作区、能开 diff、能跑工具的 Claude。两条路径，按 IDE 选：
+
+- **VS Code 家族（VS Code / Cursor / Windsurf）+ JetBrains 家族**：装官方扩展或插件，然后在 `claude` REPL 里跑 `/ide`（命令在 `src/commands/ide/index.ts` 注册，实现在 `src/commands/ide/ide.tsx`）。它会扫描当前在跑的 IDE、列出带扩展的实例、让你选一个连过去。`/ide open`（`ide.tsx:277-329`）还会把当前 worktree 或 cwd 在选中的 IDE 里打开。注意 VS Code 系列有一条限制：同一时刻只能有一个 Claude 实例连过去（`ide.tsx:127-131` 的告警）。
+- **Zed / Cursor 等 ACP 客户端**：ACP（Agent Client Protocol）是 stdio NDJSON 协议。Claude 自身就是一个 ACP agent，跑 `claude --acp`（`src/entrypoints/cli.tsx:123-124` 的 fast-path，受 `feature('ACP')` 门控）就会进入 stdio 模式，由 IDE 直接 spawn。Zed 侧的配置方式见 `docs/features/agents/acp.md`：在 Zed 的 `settings.json` 里加 `agent_servers`，`command` 指向 `claude`，`args` 写 `["--acp"]`。
+
+**这两条路径的区别**：`/ide` 是 Claude 主动连过去（Claude 作为 MCP client 反向连 IDE 的 MCP server），适合在终端 REPL 里把 IDE 当作"上下文源"；`--acp` 是 IDE 把 Claude 当 agent 调起来（Claude 作为 ACP server），适合 IDE 内置的 Agent Panel。两种方向都支持，挑你顺手的。
+
+**自动连接**：`/ide` 第一次手动选完之后，会在 `IdeAutoConnectDialog`（`src/components/IdeAutoConnectDialog.js`）里问你要不要"以后自动连"。开了之后下次启动 REPL 会自动连上同一台 IDE，不用每次 `/ide`。要关掉就再跑 `/ide` 选 `None`，会弹 `IdeDisableAutoConnectDialog`。
+
+### 第二类：把 Claude 暴露成可以被远程调用的服务（ACP / Bridge / RCS）
+
+"我有一台跑 Claude 的机器、想让另一台机器（或浏览器、或团队同事）调用它"——三类方案：
+
+- **ACP agent 远程化**：`claude --acp` 默认是本地 stdio。要让 WebSocket 客户端也能调，跑 `acp-link`（`packages/acp-link/`，README 在 `packages/acp-link/README.md`）。它把 WebSocket 连接桥接到 ACP agent 的 stdin/stdout。默认端口 9315，默认会自动生成一个 token；要固定 token 用 `ACP_AUTH_TOKEN` 环境变量，要禁用认证（不推荐）用 `--no-auth`。详细 CLI 选项见 README。
+- **Bridge / Remote Control 快速路径**：`claude remote-control` / `claude rc` / `claude remote` / `claude sync` / `claude bridge`（`cli.tsx:178-188`，五个别名都进同一条 fast-path，受 `feature('BRIDGE_MODE')` 门控）。这条路径把当前进程接到一个 Remote Control 后端，让你的 REPL 能被远端控制。
+- **自托管 RCS（Remote Control Server）**：如果你要给一个团队或长期跑的后端，用 `packages/remote-control-server/`（Docker 部署 + Web UI 控制面板，启动用 `bun run rcs`）。它的 README（`packages/remote-control-server/README.md`）列了五项能力：会话管理、实时消息流（WebSocket / SSE 双向）、权限审批（在 Web UI 里点同意/拒绝）、多环境管理（注册多台运行环境、心跳和断线重连）、API Key + JWT 双层认证。acp-link 也能注册到 RCS：设 `ACP_RCS_URL` / `ACP_RCS_TOKEN` / `ACP_RCS_GROUP`（或 `--group <id>` flag），就能在 RCS Web UI 里看到这个 ACP agent。
+
+**这三类的取舍**：acp-link 适合"我有一台机器、想让外部 WebSocket 调一下"；`claude remote-control` 适合"我正在 REPL 里干活、临时让远端接入"；自托管 RCS 适合"团队级长期跑"。同一个底（query loop + 工具系统）三种接入形态，见设计视角的"集成边界"一节。
+
+### 第三类：把 Claude 嵌进 GitHub 工作流（issue / PR review / 自动修复）
+
+两条入口：
+
+- **手动一键装**：`claude install-github-app`（实现在 `src/commands/install-github-app/install-github-app.tsx`，命令注册在 `src/commands/install-github-app/index.ts`）。它是一个多步 React 表单（不是 shell 命令），会带你走完：检测 `gh` 是否装了、选 repo、检测现有 workflow、装 GitHub App、写 API key 到 GitHub Secret、装 workflow 文件。装完之后，在你的 GitHub repo 里 `@claude` 提一句，就会触发 `claude-code-action` 跑一轮。具体能触发什么事件、workflow 模板长什么样，看 `src/constants/github-app.ts`——`WORKFLOW_CONTENT` 是写进你 repo 的 workflow 文件内容，`GITHUB_ACTION_SETUP_DOCS_URL` 指向 `anthropics/claude-code-action` 仓库的 setup 文档。
+- **直接 commit + push + 开 PR**：`/commit-push-pr`（`src/commands/commit-push-pr.ts`）。这不是 GitHub App，是你本地 `claude` 直接用 `gh` CLI 帮你开 PR。它内部有一个 `ALLOWED_TOOLS` 白名单（`commit-push-pr.ts:11-23`），只允许 `Bash(git ...)` / `Bash(gh pr ...)` / `SearchExtraTools` 和两个 Slack 工具。如果你的 CLAUDE.md 提到要往 Slack 发 PR 链接，它还会用 `SearchExtraTools` 找 Slack 工具问你要不要发（`commit-push-pr.ts` 的 `slackStep`）。
+- **PR 自动修复**：`/autofix-pr`（`src/commands/autofix-pr/`，入口 `launchAutofixPr.ts`）。这是给 CI 上跑的——PR 触发后 Claude 看一遍、发现明显问题就自动提交一个修复 commit。
+
+### 第四类：和 Codex CLI 共享 ChatGPT 订阅凭证
+
+如果你同时在用 Codex CLI 和 Claude，并且想用 ChatGPT 订阅当后端（`OPENAI_AUTH_MODE=chatgpt`），你**不需要在两边各登录一次**。Claude 会先读自己的 `~/.claude/openai-chatgpt-auth.json`；如果不存在，会 fallback 读 Codex CLI 的 `~/.codex/auth.json`（`src/services/api/openai/chatgptAuth.ts:339-344`）。所以你在 Codex CLI 里登录过、Claude 这边就能直接复用。
+
+反过来不成立：Codex CLI 不会读 Claude 的凭证文件。如果你只想在 Claude 里用，就只在 Claude 这边 `/login` 走 ChatGPT 设备码流程；如果你想在两边都用，去 Codex CLI 登录一次更省事。
+
+凭证刷新有 5 分钟的偏差窗口（`REFRESH_SKEW_MS = 5 * 60 * 1000`，`chatgptAuth.ts:7`）——令牌过期前 5 分钟内任意一次请求都会触发刷新，避免边界 race。详见 cross/03-security.md 的凭证章节。
+
+### 第五类：跨工具凭证共享（其他 Provider）
+
+**只有 ChatGPT 订阅路径**会跨工具读 Codex 的凭证文件。其他 Provider（Anthropic / 普通 OpenAI API key / Gemini / Grok / Bedrock / Vertex / Foundry）的 key 都存在 Claude 自己的 `~/.claude/` 下或 `settings.json` 里，不与任何外部工具共享。
+
+如果你同时在别的工具（比如 Aider、Continue）里用 Anthropic API，那些工具各自读自己的配置——你需要在每个工具里都配一遍 `ANTHROPIC_API_KEY` 或对应的环境变量。这不是 bug，是有意的隔离：一个工具的凭证泄露不应该顺带把另一个工具的也带出去。
+
+## 设计视角（写给开发者）
+
+设计大纲原本完全没有"跨工具集成视角"。这一节补上"集成边界"——每一类集成背后都有一组明确的契约和决策：协议形态、凭证流向、feature 门控、命令路径。读完之后你应该能回答："如果我要加一个新的 IDE 集成、或一个新的 CI 平台，边界在哪、哪些约束是必须遵守的"。
+
+### 为什么 IDE 集成走 MCP 的 `sse-ide` / `ws-ide` 子类型，而不是普通 MCP
+
+打开 `src/commands/ide/ide.tsx:463-472`，看连接 IDE 时写入 `dynamicMcpConfig` 的逻辑：
+
+```ts
+const url = selectedIDE.url
+newConfig.ide = {
+  type: url.startsWith('ws:') ? 'ws-ide' : 'sse-ide',
+  url: url,
+  ideName: selectedIDE.name,
+  authToken: selectedIDE.authToken,
+  ideRunningInWindows: selectedIDE.ideRunningInWindows,
+  scope: 'dynamic' as const,
+} as ScopedMcpServerConfig
+```
+
+IDE 在 MCP config 里是一个特殊的 `ide` key，type 是 `sse-ide` 或 `ws-ide`——不是普通的 `sse` / `websocket`。这两个子类型在 `src/services/mcp/` 里有专门的处理路径。**为什么不给 IDE 用普通 MCP？** 因为 IDE 提供的不只是工具（`mcp__ide__*` 工具前缀，见 `ide.tsx:455-456` 的 `filter` 清理逻辑），还有 diff 显示、当前选中文件、diagnostics 推送这些"非工具形态"的能力。给 IDE 单独留一个 type，让 MCP client 知道"这个连接除了普通工具调用，还有 IDE 专有的副作用通道"。
+
+**另一个有意思的设计**：`dynamicMcpConfig` 的 scope 是 `'dynamic'`。这意味着 IDE 配置不写进 `settings.json`，而是活在 React state 里——下次启动 REPL 不会自动恢复。自动恢复靠 `IdeAutoConnectDialog` 单独存的标志位（"以后自动连"），连接动作本身每次都要重新走一遍。这个设计的代价是：用户换一台机器、或者把 settings 同步到另一台，IDE 自动连不会跨机器带过去。收益是：IDE 的端口和 token 是会话期会变的（IDE 重启端口就变），写进持久化 settings 反而会读到过期值。
+
+**disconnect 的细节**（`ide.tsx:446-460`）：断开连接时除了清 config，还主动 `ideClient.client.onclose = () => {}` 把 onclose 置空。**为什么？** MCP client 有自动重连机制，正常关闭会触发重连。置空 onclose 是"我说了要断、别再自己连回来"的信号——这是 RPC 类连接很容易踩的坑，`/ide` 选 None 的时候必须做这一步，否则用户会看到"我明明断了它又自己连上"。
+
+### 为什么 ACP agent 是 stdio NDJSON，而 acp-link 要做 WebSocket → stdio 桥接
+
+ACP 的协议形态选择写在 `docs/features/agents/acp.md`：stdin/stdout 的 NDJSON 流。**为什么是 stdio？** 因为 stdio 是 IDE 调子进程最简单的形态——IDE spawn `claude --acp`，往 stdin 写 NDJSON，从 stdout 读 NDJSON。不需要开端口、不需要握手、不需要网络配置。代价是"只能本地调用"——IDE 和 agent 必须在同一台机器上同一个进程树里。
+
+acp-link（`packages/acp-link/`）就是为突破这个限制存在的。看 README 的 "How It Works"：它监听 WebSocket、收到 `connect` 消息就 spawn 配置好的 ACP agent 子进程、把 WebSocket 帧和 agent 的 stdin/stdout 双向桥接。**为什么不直接给 ACP agent 加一个 WebSocket 模式？** 因为 stdio 和 WebSocket 是两种完全不同的 I/O 模型——stdio 是阻塞 read、WebSocket 是事件回调。把它们塞进同一个 agent 进程会让 agent 的代码复杂度爆炸。acp-link 作为独立进程承担"协议翻译"，agent 自己保持纯 stdio，**单一职责**。
+
+**这个设计的代价**：多了一层进程。acp-link 进程崩了，agent 和 WebSocket 客户端都会失联。RCS 的多环境管理（README 提到"心跳和断线重连"）部分就是为了缓解这个——acp-link 进程挂了 RCS 能检测到、能重启。`packages/acp-link/src/manager/`（README 的 "Manager UI" 段）进一步提供了"一台机器跑多个 acp-link 子进程、统一管理"的形态，这是为团队场景设计的。
+
+**凭证透传**：ACP agent 启动时会读 `settings.json` 里的环境变量（见 `docs/features/agents/acp.md` 第 58 行，`ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN` 等）。Zed 这种 IDE 还能在 `agent_servers` 配置里显式传 `env`。**为什么不让 ACP 协议自己带凭证？** 因为 ACP 是协议、凭证是部署期决策——协议只规定"怎么对话"，凭证由调用方（IDE 的 `agent_servers.env` / RCS 的环境变量 / acp-link 启动时的环境）决定。这种分离让同一个 ACP agent 能在不同 IDE、不同部署形态下复用，不需要改 agent 代码。
+
+### 为什么 ChatGPT 订阅凭证要 fallback 读 `~/.codex/auth.json`
+
+打开 `src/services/api/openai/chatgptAuth.ts:42-57`：
+
+```ts
+function authFilePath(): string {
+  return join(getClaudeConfigHomeDirLocal(), AUTH_FILE)
+}
+
+function codexAuthFilePath(): string {
+  return join(
+    process.env.CODEX_HOME ?? join(process.env.HOME ?? '', '.codex'),
+    'auth.json',
+  )
+}
+```
+
+两个路径函数。`getValidChatGPTAuth`（`chatgptAuth.ts:339-344`）的读取顺序是：**先读 Claude 自己的 `~/.claude/openai-chatgpt-auth.json`，读不到再 fallback 读 Codex CLI 的 `~/.codex/auth.json`**，并打一条 debug 日志 `[OpenAI] Using ChatGPT auth from Codex auth.json`。
+
+**为什么这么设计？** ChatGPT 订阅的 OAuth 设备码流程是 OpenAI 自己发的（`ISSUER = 'https://auth.openai.com'`，`CLIENT_ID = 'app_EMoamEEZ73f0CkXaXp7hrann'`，`chatgptAuth.ts:5-6`）。Codex CLI 用的是同一个 issuer 同一个 client_id（验证：`verificationUrl` 用 `${ISSUER}/codex/device`，`chatgptAuth.ts:217`）。两边走的是同一套令牌体系，令牌可以互换——所以让 Claude 复用 Codex 的凭证是合法的、不是"借用"。
+
+**为什么不强制让用户在 Claude 这边也登录一次？** 因为 ChatGPT 订阅用户已经为这个 token 付过费、已经走完设备码握手了。让他在每个工具里都重做一次设备码登录（打开浏览器、输 userCode、等待授权）是明显的体验灾难。fallback 读 Codex 凭证把"一次登录、多个工具复用"变成可能。
+
+**反向不成立**：Codex CLI 不会读 Claude 的凭证文件。这是有意的非对称——Claude 这边承认"我是后来的、我读你的"，但 Codex CLI 作为 OpenAI 自家工具不知道 Claude 的存在。这种非对称在跨工具凭证共享里很常见：后入场的一方做兼容，先入场的一方保持简单。
+
+**风险**：这个 fallback 假设 Codex CLI 的凭证文件格式稳定。如果某天 Codex CLI 改了 `auth.json` 的 schema（加字段、改字段名、嵌套层级变化），Claude 这边的 `readStoredAuth`（`chatgptAuth.ts:123`）就要跟着改。这是跨工具集成的固有脆弱性——**两边的格式没有契约约束，只靠"碰巧一致"维持**。如果 Codex CLI 那边改了，Claude 这边不会自动收到通知，要靠用户报"我用 ChatGPT 模式登录不了了"才会被发现。
+
+### `install-github-app` 为什么是 React 多步表单，而不是一行 shell
+
+打开 `src/commands/install-github-app/install-github-app.tsx`，它 import 了 11 个 Step 组件：`ApiKeyStep` / `CheckExistingSecretStep` / `CheckGitHubStep` / `ChooseRepoStep` / `CreatingStep` / `ErrorStep` / `ExistingWorkflowStep` / `InstallAppStep` / `OAuthFlowStep` / `SuccessStep` / `WarningsStep`。一个简单的"装 GitHub App"为什么要拆这么多步？
+
+因为"装一个 GitHub App"在生产环境里至少有 11 个分支：
+
+- `gh` 装了吗？没装怎么办？（`CheckGitHubStep`）
+- 用户想装到当前 repo 还是别的 repo？当前 repo 探测到了吗？（`ChooseRepoStep`）
+- API key 用现有的还是新建？用 OAuth 还是 API key？（`ApiKeyStep`，`selectedApiKeyOption: 'new' | 'existing' | 'oauth'`，见 `install-github-app.tsx:36`）
+- repo 里已经有同名 secret 了吗？要覆盖还是保留？（`CheckExistingSecretStep`）
+- repo 里已经有 workflow 文件了吗？要装哪几个？（`ExistingWorkflowStep`，默认 `['claude', 'claude-review']`，见 `install-github-app.tsx:35`）
+- 创建过程中出错了？错误长什么样、能不能重试？（`ErrorStep`、`CreatingStep`）
+- 装完了有哪些警告？比如权限不够、repo 是 fork、org policy 限制？（`WarningsStep`）
+
+每一个分支都需要用户决策、都要展示状态。**用一行 shell 解决不了**——shell 是"我已知所有参数、一次性执行"，而 GitHub App 安装是"边探测边问边装"。React 多步表单是这种"探测-决策-执行-反馈"循环的自然形态。
+
+**契约**：`install-github-app` 写进用户 repo 的 workflow 文件内容是写死在 `src/constants/github-app.ts` 的 `WORKFLOW_CONTENT` 常量里——这是一个 GitHub Actions YAML 字符串，定义了 `issue_comment` / `pull_request_review_comment` / `issues` / `pull_request_review` 四类事件的触发条件（都是 `@claude` mention），跑在 `ubuntu-latest` 上，permissions 是 `contents: read` / `pull-requests: read` / `issues: read` / `id-token: write`。PR 标题也是常量 `PR_TITLE = 'Add Claude Code GitHub Workflow'`。**这些常量就是 Claude ↔ GitHub 的契约**——改 `WORKFLOW_CONTENT` 等于改所有未来用户装上去的 workflow 模板，要非常小心向后兼容。
+
+### `/commit-push-pr` 的 `ALLOWED_TOOLS` 白名单为什么这么窄
+
+看 `src/commands/commit-push-pr.ts:11-23`：只允许 `Bash(git ...)` 几条、`Bash(gh pr ...)` 几条、`SearchExtraTools`、两个 Slack 工具。**为什么不给它 `FileEdit` / `FileWrite`？** 因为 `/commit-push-pr` 的语义是"把已经做好的改动提交、推送、开 PR"——它不应该再修改代码。如果允许 `FileEdit`，这个命令就会从"提交工具"退化成"提交 + 顺手再改点代码"的工具，权限边界就乱了。
+
+**为什么 Slack 工具要单列？** 看 `commit-push-pr.ts` 后面的 `slackStep` 逻辑：如果你的 CLAUDE.md 里写了"开完 PR 往 Slack 发链接"，这个命令会尝试用 `SearchExtraTools` 找 Slack 工具，问你要不要发。这是一条**条件性集成**——不是所有用户都装了 Slack MCP，所以不能硬编码 `mcp__slack__send_message`，要走延迟工具搜索。如果没找到，silent skip，不打扰用户。
+
+**`getPromptContent` 里的 `process.env.USER_TYPE === 'ant' && isUndercover()`**（`commit-push-pr.ts:33-40` 附近）是一个有意思的边界：Anthropic 内部用户跑这个命令时，会切到 "undercover" 模式——不暴露自己在用 Claude。这是 dogfooding 的产物：内部用户用自家工具时，对外（比如在公开的开源 repo 里开 PR）不能露出"这是 AI 写的"的痕迹。这个分支只在 `USER_TYPE === 'ant'` 时生效，普通用户看不到。
+
+### 三种长驻模式（ACP / Bridge / Daemon）共享底层 query loop 但各有独立 entry
+
+这是设计大纲第十二章的核心论点在集成视角下的具体化。三者的关系：
+
+- **ACP**（`src/services/acp/`）：`cli.tsx:123-124` 的 `--acp` fast-path，受 `feature('ACP')` 门控。进入 `src/services/acp/entry.ts`，spawn 一个 `AcpAgent`（`agent.ts`）。agent 把 ACP 客户端的请求桥接到内部的 query loop（`src/services/acp/bridge.ts`），权限决策走 `createAcpCanUseTool`（`src/services/acp/permissions.ts`）。
+- **Bridge**（`src/bridge/`）：`cli.tsx:178-188` 的 `remote-control` / `rc` / `remote` / `sync` / `bridge` 五个别名 fast-path，受 `feature('BRIDGE_MODE')` 门控。进入 `src/bridge/bridgeMain.ts`，JWT 认证（`jwtUtils.ts`）、消息传输（`bridgeMessaging.ts`）、权限回调（`bridgePermissionCallbacks.ts`）。
+- **Daemon**（`src/daemon/`）：`cli.tsx` 的 `daemon` 子命令，受 `feature('DAEMON')` 门控。`src/daemon/main.ts` 是 entry，`workerRegistry.ts` 管 worker，`--daemon-worker=<kind>` 派生精简 worker。
+
+**共享的部分**：三者都最终调用 `src/query.ts` 的 `query()` async generator（见设计大纲第五章）。工具系统、Provider 路由、流式响应——这些都是共用的。**各自增加的编排层**：ACP 加了"会话管理 + 权限桥接 + prompt 排队"，Bridge 加了"JWT 认证 + 远端消息传输 + 权限远程审批"，Daemon 加了"worker 注册表 + 心跳 + 精简 worker 派生"。
+
+**为什么三个要分开**：因为它们的**调用方不同**。ACP 的调用方是 IDE（同机 stdio），Bridge 的调用方是 RCS 后端（远端 JWT），Daemon 的调用方是 CI 或 supervisor（进程级 spawn）。三种调用方对认证、传输、生命周期的要求完全不同——IDE 不需要认证（已经在用户机器上）、RCS 必须认证（暴露在网络上）、Daemon 必须支持后台 + 心跳（长跑）。把这些塞进同一个 entry 会让代码变成"if (acp) {...} else if (bridge) {...} else if (daemon) {...}"的分支地狱。分开三个 entry、各自 feature-gated，是**用 entry 数量换 entry 简单度**的权衡。
+
+**BYOC runner 是三条线的交汇点**：`claude environment-runner` / `claude self-hosted-runner`（见设计大纲第十二章）是这三条线和 CI（产品大纲第十一章）的交汇——它能让外部 CI 系统以 Bring-Your-Own-Compute 的方式调用 Claude，背后可能用 ACP（同机）、Bridge（远端）、或 Daemon（长跑）任意一种。这是"集成边界"最抽象的一层：用户不直接选 ACP/Bridge/Daemon，他选的是 environment-runner，由 runner 决定底下用哪种长驻模式。
+
+### VS Code 桥接（`vscode-ide-bridge/`）的现状
+
+CLAUDE.md 提到 `vscode-ide-bridge/` 是"VS Code 桥接"辅助目录。**但这个目录在当前仓库里实际不存在**（`ls` 返回空）。VS Code 集成实际走的是 `/ide` 命令 + VS Code 扩展（扩展是独立分发的，不在本仓库里），不是通过这个目录里的代码。`vscode-ide-bridge/` 在仓库的某个历史版本里存在过、后来被移除或合并到 `src/commands/ide/`——`CLAUDE.md` 的描述滞后了。**这是反编译重建工作的典型痕迹**：文档描述的是"原本应该有什么"，代码里实际是"重建后剩下了什么"。
+
+## 两视角如何呼应
+
+用户视角的每一个"我能接什么"的清单，几乎都能在设计视角找到对应的契约和决策：
+
+- **"我能在 VS Code / Zed / Cursor 里用 Claude 吗"**（产品视角）对应 **"为什么 IDE 走 MCP 的 `sse-ide` / `ws-ide` 子类型、为什么 ACP agent 用 stdio NDJSON"**（设计视角）——用户看到的是"装个扩展、`/ide` 一连就行"，开发者看到的是"`dynamicMcpConfig` 的 `ide` key 用了专门的 type、ACP 协议形态选择 stdio 是为了 IDE spawn 子进程最简单"。
+- **"我能不能让远端调用我机器上的 Claude"**（产品视角）对应 **"acp-link 为什么是 WebSocket → stdio 桥接、自托管 RCS 为什么是 Docker + Web UI"**（设计视角）——用户看到的是"`claude remote-control` 一跑、Web UI 一开就能用"，开发者看到的是"三种长驻模式（ACP / Bridge / Daemon）共享 query loop 但各有独立 entry、用 entry 数量换 entry 简单度"。
+- **"我在 Codex CLI 登录过、Claude 这边能复用吗"**（产品视角）对应 **"为什么 ChatGPT 订阅凭证要 fallback 读 `~/.codex/auth.json`"**（设计视角）——用户看到的是"不用再登录一次"，开发者看到的是"两边用同一 issuer 同一 client_id、令牌可互换、但 schema 没有契约约束只靠碰巧一致"。
+- **"我能在 GitHub Actions 里用 Claude 吗"**（产品视角）对应 **"`install-github-app` 为什么是 React 多步表单、`/commit-push-pr` 的 `ALLOWED_TOOLS` 白名单为什么这么窄"**（设计视角）——用户看到的是"`claude install-github-app` 一键装、`@claude` 一 at 就触发"，开发者看到的是"11 个 Step 组件对应 11 个分支、`WORKFLOW_CONTENT` 常量是 Claude ↔ GitHub 的契约、白名单用'允许什么'定义命令的语义边界"。
+- **"我的 key 会不会被别的工具读到"**（产品视角）对应 **"跨工具凭证共享为什么只有 ChatGPT 订阅路径、为什么反向不成立"**（设计视角）——用户看到的是"除了 ChatGPT 订阅路径、其他 key 都不共享"，开发者看到的是"后入场的一方做兼容、先入场的一方保持简单的非对称设计"。
+- **"`vscode-ide-bridge/` 是什么"**（产品视角用户翻 CLAUDE.md 看到的）对应 **"反编译重建工作的典型痕迹——文档描述原本应该有什么、代码里实际剩下了什么"**（设计视角）——用户看到的是"文档里提到了一个目录"，开发者看到的是"那个目录在当前仓库里实际不存在、VS Code 集成走的是 `/ide` + 独立扩展"。
+
+这种呼应关系是"与其他工具集成"必须双视角覆盖的核心原因：用户视角告诉你**怎么接**，设计视角告诉你**接的边界在哪、契约长什么样、哪些描述滞后于代码**。两个视角合在一起，才能让使用者正确判断"我现在的接法是不是最优、要不要换一种"，也让开发者在加新集成时知道"哪些约束（凭证隔离、协议形态、feature 门控、entry 分离）是必须遵守的"——而不是把每个集成都重新发明一遍。

docs/outline-output/cross/06-observability.md

@@ -0,0 +1,157 @@
+# 可观测性
+
+> 同一个"我想知道 Claude 在做什么"的诉求，在使用者眼里是"它现在到底卡在哪一步、这次回答烧了多少 token、能不能把这次对话导出来给同事看"，在开发者眼里是"为什么 Langfuse 追踪必须从 `getAPIProvider()` 取单一真相源、为什么 `performanceShim` 必须抢在 React/OTel 之前装上、为什么 `--dump-system-prompt` 要被 feature flag 锁死"。可观测性天然是双视角主题——用户想知道"我能不能看见、怎么看"，开发者想知道"探针插在哪、插这个位置要付出什么代价、会不会反过来把会话拖垮"。
+
+## 产品视角（写给使用者）
+
+这一节回答一个高频但被低估的问题：**Claude 在帮我跑任务的时候，我自己怎么知道它正在干什么、干得对不对、花了多少？** 答案按"你想看什么"分四类工具，从轻到重排列。
+
+### 第一类：我想看它现在在做什么（实时观测）
+
+你在 REPL 里发完一条消息，最直接的观测就是屏幕本身——流式回复、工具调用、权限弹窗、token 状态栏，这些都是"被动观测"：你不主动做什么，它们自己会显示。但当会话变长、工具链变深（比如一个 Agent 派了三个子代理、每个子代理又跑了若干次 Bash + FileEdit），光靠屏幕就不够了。这时候有两条主动路径：
+
+- **`/debug-tool-call [N]`**：列出本会话最后 N 次工具调用（默认 5）的输入与输出。源码在 `src/commands/debug-tool-call/index.ts`，它不依赖任何远程服务，直接读会话日志（JSONL transcript，路径由 `getTranscriptPath()` 在 `index.ts:33` 决定，位于 `~/.claude/projects/<sanitize(cwd)>/<sessionId>.jsonl`）。用法场景很具体——"刚才那次 FileEdit 把哪一行改错了"、"Agent 派的子代理到底跑了什么命令"，不用翻整个 transcript 文件。注意它只显示 tool_use + tool_result 配对，纯文本回复不在这张表里。
+- **状态栏的 token 数字**：每次 API 调用结束，REPL 状态栏会刷新 input/output/cache token。想看历史累积、单次费用估算，用 `/cost`（本次会话总费用）、`/usage`（按模型拆分的用量）、`/stats`（更细的统计）。这三个命令读的都是同一份 usage 累加器，区别只是聚合粒度。
+
+### 第二类：我想把每次 API 调用、每个工具调用都记下来（Langfuse 追踪）
+
+如果你在做长任务、调试 prompt、或者想把 Claude 的行为变成可回放的训练数据，屏幕不够用——你需要结构化的请求链路。这就是 Langfuse 集成的用途。打开 `docs/features/tools/langfuse-monitoring.md`，它是一个开源 LLM 可观测性平台，CCB 通过 OpenTelemetry 桥接进去。**核心只需要三个环境变量**：
+
+| 环境变量 | 说明 |
+|---------|------|
+| `LANGFUSE_PUBLIC_KEY` | Langfuse 公钥（必填） |
+| `LANGFUSE_SECRET_KEY` | Langfuse 密钥（必填） |
+| `LANGFUSE_BASE_URL` | 服务地址，默认 `https://cloud.langfuse.com`；自部署时改成你的地址 |
+
+推荐写进 `.claude/settings.json` 的 `env` 字段，每次启动自动生效。**没配这三个变量时所有追踪函数都是 no-op、零开销**——不用担心开了它拖慢响应。配齐之后，每次 API 请求、每次工具调用都会被打成 span 发到 Langfuse，你在面板里能看到：
+
+- **LLM 调用**：模型名、Provider、输入/输出消息、token 用量（含 cache_creation / cache_read）、首 token 耗时（TTFT）、总耗时
+- **工具执行**：工具名、输入、输出、耗时、错误
+- **多 Agent 链路**：主 Agent 和子 Agent 各有独立 trace，能在面板里看到父子关系
+- **自动脱敏**：API key、文件内容片段、shell 输出里的敏感字段会被遮蔽（实现见 `src/services/langfuse/sanitize.ts`）
+
+其他可选参数（`LANGFUSE_TRACING_ENVIRONMENT` / `LANGFUSE_FLUSH_AT` / `LANGFUSE_FLUSH_INTERVAL` / `LANGFUSE_EXPORT_MODE` / `LANGFUSE_TIMEOUT`）见 `docs/features/tools/langfuse-monitoring.md:49-57` 的表格，按需调。
+
+### 第三类：我想知道系统提示长什么样（`--dump-system-prompt`）
+
+一个常见疑问："Claude 每次开头那长长一串系统提示到底是什么？CLAUDE.md 真的被读进去了吗？" `claude --dump-system-prompt` 会渲染并打印当前模型对应的系统提示，然后直接退出——不进入 REPL、不发任何 API 请求。可选 `--model <name>` 指定模型。用法：
+
+```bash
+claude --dump-system-prompt
+claude --dump-system-prompt --model claude-sonnet-4-5
+```
+
+**注意**：这条 fast-path 受 `feature('DUMP_SYSTEM_PROMPT')` 门控（`src/entrypoints/cli.tsx:93`），主要用于 prompt sensitivity eval 在特定 commit 上提取系统提示。**外部构建产物里这条路径会被编译期剔除**，dev 模式默认开启。如果你跑 `claude --dump-system-prompt` 没有任何输出，多半是当前构建禁用了这个 feature。
+
+### 第四类：我想用调试器接进去（`BUN_INSPECT` + `dev:inspect`）
+
+当 Claude 行为异常、你想看运行时变量值或断点单步，用 Bun 内置的 V8 inspector。两条路径：
+
+- **开发模式**：`bun run dev:inspect`（实际跑 `scripts/dev-debug.ts`）。它读 `BUN_INSPECT` 环境变量作为端口，默认会 await inspector 连上再继续执行，适合断在启动早期。
+- **指定端口**：`BUN_INSPECT=9229 bun run dev:inspect`。然后用 Chrome `chrome://inspect` 或 VS Code 的 Bun 调试器连 `ws://localhost:9229`。
+
+注意这是开发自检工具，不是给最终用户的——它要求你能在仓库里 `bun install` 后跑 dev 模式。普通使用者想看"它在做什么"，用前两类的命令就够了。
+
+### 一句话总结这四类
+
+| 我想看 | 用什么 | 代价 |
+|--------|--------|------|
+| 当前会话的工具调用 | `/debug-tool-call` | 零（读本地 transcript） |
+| 历次 API 调用 + token 用量 | `/cost` `/usage` `/stats` | 零（读本地累加器） |
+| 完整请求链路（可回放） | Langfuse（`LANGFUSE_*` 环境变量） | 配齐才启用，未配零开销 |
+| 系统提示长什么样 | `claude --dump-system-prompt` | feature-gated，外部构建可能被剔除 |
+| 运行时变量 / 断点 | `BUN_INSPECT=9229 bun run dev:inspect` | 需要开发环境 |
+
+## 设计视角（写给开发者）
+
+设计大纲原本几乎没有"观测的注入点"这一节——只有第七章锚点提到 `claude.ts:2999`。这一节补上：探针插在哪、为什么插在那里、插这个位置要付出什么代价。读完之后你应该能回答："如果我要加一个新的观测维度（比如工具执行的 p99 latency），应该挂在哪一行、为什么不能挂在那行之前"。
+
+### 为什么 Langfuse 追踪的 `provider` 字段必须从 `getAPIProvider()` 取单一真相源
+
+打开 `src/services/api/claude.ts:2997-2999`：
+
+```ts
+// Record LLM observation in Langfuse (no-op if not configured)
+recordLLMObservation(options.langfuseTrace ?? null, {
+  model: resolvedModel,
+  provider: getAPIProvider(),
+```
+
+`provider` 字段的值直接来自 `getAPIProvider()`——整个项目里唯一一个"当前用哪个 Provider"的真相源。`getAPIProvider()`（`src/utils/model/providers.ts:15`）按 `modelType` 参数 > `CLAUDE_CODE_USE_*` 环境变量 > firstParty 默认 这条优先级链返回字符串。
+
+**为什么不另起一个变量、不读 `process.env.CLAUDE_CODE_USE_OPENAI` 这种直接环境变量？** 因为 Provider 选择有运行时动态性。`/provider openai` 命令会清掉所有 `CLAUDE_CODE_USE_*` 然后写新的配置（`src/commands/provider.ts:39`），这一步走 `applyConfigEnvironmentVariables` 把配置反推回 `process.env`。如果在 Langfuse 这边直接读 `process.env.CLAUDE_CODE_USE_OPENAI`，就有两个风险：一是和 `/provider` 命令的写入时机产生 race，二是兼容层（OpenAI / Gemini / Grok）各自有不同的 env var 名，硬编码会漏。
+
+**`getAPIProvider()` 作为单一真相源的设计红利**：`/provider` 命令、模型映射（`resolveOpenAIModel` / `resolveGeminiModel` / `resolveGrokModel`）、Langfuse 追踪——三个看似不相关的子系统都从同一个函数取值。只要 `getAPIProvider()` 正确，这三个地方的 Provider 字段必然一致。这是"单一真相源"原则的教科书例子：观测数据天然就应该和决策数据同源，否则面板上看到的 Provider 和实际跑的不一致，追踪就失去了意义。
+
+**代价**：`getAPIProvider()` 不是纯函数，它每次调用都要走一遍优先级链解析。在 `claude.ts:2997` 这个位置（每次 API 响应结束后调用一次）是可接受的——一次 turn 调一次，不在热路径里。但如果你想把 provider 字段加到更高频的观测点（比如每个流式 chunk），就不能再调 `getAPIProvider()` 了，得缓存结果。
+
+### 为什么 `recordLLMObservation` 是 fire-and-forget，不是 await
+
+看 `claude.ts:2997` 的调用——它没有 `await`。`recordLLMObservation` 在 `src/services/langfuse/tracing.ts:85` 是 async function，但调用方不等它。
+
+**为什么？** 观测不该阻塞主路径。Langfuse 走 OTel exporter，批量异步发到远端（`LANGFUSE_FLUSH_AT=20` 默认 20 条 span 攒一批）。如果 `await recordLLMObservation(...)`，每次 API 响应都要等网络 round-trip，用户看到的 TTFT 会暴涨。fire-and-forget 让观测在后台跑，主路径零延迟。
+
+**代价**：观测失败用户感知不到。`tracing.ts:178` 里有一行 `logForDebugging('[langfuse] recordLLMObservation failed: ...')`——失败只打 debug 日志，不抛、不告警。这是有意的：观测是辅助、不是必需。如果 Langfuse 挂了，Claude 本身必须照常工作。`isLangfuseEnabled()`（`src/services/langfuse/client.ts:13`）只检查 `LANGFUSE_PUBLIC_KEY` 和 `LANGFUSE_SECRET_KEY` 是否存在——未配置时整条链路是 no-op，连 fire-and-forget 的开销都没有。
+
+### 为什么 `performanceShim` 必须最先 import，OTel 才能正常工作又不会撑爆内存
+
+打开 `src/utils/performanceShim.ts:1-17` 的文件头注释——这是整个项目最强烈的"必须最先 import"约束（在 `src/entrypoints/cli.tsx` 的第一行 import）。背景：Bun 的 `globalThis.performance` 是 JSC 原生 Performance 对象，它的 marks / measures / resource timings 存在一个**永不收缩的 C++ Vector**。长会话（daemon / `/loop`）持续累积，能撑出几百 MB 死容量。
+
+**这跟可观测性有什么关系？** 因为 Langfuse 走 OTel，OTel 的 performance exporter（`otperformance`）会大量调用 `performance.mark()` 和 `performance.measure()` 来打 span 计时。**如果没有 shim**，每个 OTel span 都会在 C++ Vector 里留一条永不释放的 entry——观测越勤，内存爆得越快。这是"观测反向拖垮被观测对象"的经典反例。
+
+`performanceShim` 的解决方案（`performanceShim.ts:127-155`）：保留 `performance.now()` 走原生（快、零内存成本——OTel 用它打时间戳），劫持 `mark` / `measure` / `getEntries` / `clearMarks` 走 JS Map（GC 能回收）。**必须在 React reconciler 和 OTel import 之前装上**，否则它们会捕获原生 Performance 的引用，shim 装了也劫持不到。
+
+**这条约束的代价**：`performanceShim` 永远是 `cli.tsx` 的第一行。如果你写了一个新模块、它在 import 阶段就碰 performance（比如模块顶层 `performance.mark('foo')`），你必须保证它 import 在 shim 之后。这就是为什么 `cli.tsx` 的 import 顺序不能随便调。
+
+### 为什么 query.ts 的 finally 块要兜底 clearMarks
+
+打开 `src/query.ts:367-379`：
+
+```ts
+// Clear JSC's native Performance buffers. OTel (otperformance) references
+// globalThis.performance which stores marks/measures/resource timings in a
+// C++ Vector that never shrinks. Long-running sessions accumulate hundreds
+// of MB of dead capacity even after spans are flushed and nullified.
+const gPerf = globalThis.performance
+if (gPerf && typeof gPerf.clearMarks === 'function') {
+  try {
+    gPerf.clearMarks()
+    gPerf.clearMeasures?.()
+    gPerf.clearResourceTimings?.()
+  } catch { ... }
+```
+
+这是 performanceShim 的第二道防线。**为什么有了 shim 还要在这里兜底？** 因为 sub-agent 会直接 `import query from 'src/query.ts'`，不走 `cli.tsx` 的入口。如果某个 sub-agent 启动路径上 shim 没装上（比如测试环境、或某种奇怪的 import 顺序），原生的 C++ Vector 就会开始累积。`query()` 是所有 turn 的共同出口，在它的 finally 块兜底一次 `clearMarks`，是"shim 万一没装上"的最后保险。
+
+**注释里有意思的一句话**："even after spans are flushed and nullified"——OTel 自己 flush span 之后会把自己持有的引用置空，但**原生 Performance 的 Vector 不会被 OTel 清**。OTel 和 Performance 是两个独立的累积源，OTel 的清理不覆盖 Performance。这是 JSC 实现的细节，也是 shim 必须劫持 mark/measure 而不是依赖 OTel 自己清理的根因。
+
+### 为什么 `--dump-system-prompt` 必须 feature-gated
+
+看 `cli.tsx:90-104` 的 fast-path：`feature('DUMP_SYSTEM_PROMPT') && args[0] === '--dump-system-prompt'`。注释说得很清楚："Used by prompt sensitivity evals to extract the system prompt at a specific commit. Ant-only: eliminated from external builds via feature flag."
+
+**为什么这么谨慎？** 系统提示是产品的核心 IP——它定义了 Claude 的行为、约束、工具使用风格。`--dump-system-prompt` 把它原样 stdout 出来，等于把 IP 暴露给任何能跑这个命令的人。feature flag 让这条路径在内部 eval 场景（CI 跑 prompt 回归）可用、在外部构建产物里编译期剔除——DCE 直接把整段 if 删掉，连字符串"`--dump-system-prompt`"都不出现在外部产物里。
+
+**这条路径本身的设计也很克制**：它不发任何 API 请求，只渲染系统提示然后 exit（`cli.tsx:102-103`）。`getSystemPrompt([], model)` 传空 messages 数组——因为系统提示不依赖对话内容，只依赖模型（不同模型的 prompt 略有差异）。如果你想 debug "我的 CLAUDE.md 到底有没有被读进去"，`--dump-system-prompt` 是最直接的工具，但前提是你跑的构建启用了这个 feature。
+
+### 为什么 `/debug-tool-call` 不走远程服务、只读本地 transcript
+
+打开 `src/commands/debug-tool-call/index.ts`——整个命令没有任何网络调用。`getTranscriptPath()`（`index.ts:33-43`）返回本会话的 JSONL 路径，`parseToolCallsFromLog()`（`index.ts:85-119`）逐行 parse JSON、按 `tool_use_id` 配对 use 和 result。
+
+**为什么不走 Langfuse？** 两个原因：
+
+1. **零依赖原则**：`/debug-tool-call` 是诊断工具，诊断工具不能依赖被诊断的东西。如果 Langfuse 挂了、网络断了、配置错了，用户跑 `/debug-tool-call` 还得能看到工具调用——这是排错最后一道防线，必须本地可用。
+2. **新鲜度**：transcript 是本会话刚写下去的，Langfuse 是批量异步发的（`LANGFUSE_FLUSH_AT=20`），有延迟。"`/debug-tool-call` 显示的就是刚才那一次"和"显示的是 20 个 span 之前那一次"，对排错体验差别巨大。
+
+**代价**：transcript 文件格式是会话私有的 JSONL schema，没有跨工具兼容承诺。如果未来 transcript 格式改了，`parseToolCallsFromLog` 的字段访问（`block.type === 'tool_use'` / `block.tool_use_id` 等）要同步改。这是"零依赖"换"零网络"的固有成本。
+
+## 两视角如何呼应
+
+用户视角的每一个"我想看什么"，在设计视角都能找到对应的注入点决策：
+
+- **"我想看这次 API 调用烧了多少 token、用的哪个 Provider"**（产品视角的 `/cost` `/usage` + Langfuse 面板）对应 **"`provider` 字段为什么必须从 `getAPIProvider()` 取、`recordLLMObservation` 为什么是 fire-and-forget"**（设计视角）——用户看到的是面板里一行清晰的 `provider: openai`，开发者看到的是"单一真相源 + 异步不阻塞主路径"的双重决策，否则要么面板字段和实际跑的不一致，要么 TTFT 被观测拖慢。
+- **"我想看 Claude 的完整请求链路，可回放"**（产品视角的 Langfuse）对应 **"performanceShim 为什么必须最先 import、query.ts 的 finally 块为什么兜底 clearMarks"**（设计视角）——用户看到的是"开了 Langfuse 长跑也不卡"，开发者看到的是"OTel 越勤、JSC 原生 Performance 的 C++ Vector 撑得越快，shim + finally 双保险把累积源掐死在 GC 能回收的 JS 内存里"。如果这个决策做错了，观测本身会把会话拖崩——这是可观测性章节必须双视角覆盖的最强理由。
+- **"我想知道系统提示到底长什么样"**（产品视角的 `--dump-system-prompt`）对应 **"为什么这条 fast-path 必须 feature-gated、为什么外部构建编译期剔除"**（设计视角）——用户看到的是"`claude --dump-system-prompt` 一跑就有"，开发者看到的是"系统提示是核心 IP、DCE 在编译期把整段 if 删掉、外部产物连这个字符串都不出现"。
+- **"我想看刚才那次工具调用的输入输出"**（产品视角的 `/debug-tool-call`）对应 **"为什么它只读本地 transcript、不走 Langfuse"**（设计视角）——用户看到的是"零延迟、零配置就能用"，开发者看到的是"诊断工具不能依赖被诊断的东西 + 新鲜度优先于跨工具兼容性"的双重原则。
+- **"我想断点单步看运行时变量"**（产品视角的 `BUN_INSPECT=9229 bun run dev:inspect`）对应 **"`bun run dev:inspect` 走 `scripts/dev-debug.ts`、读 `BUN_INSPECT` 环境变量决定端口"**（设计视角）——用户看到的是"端口一连、断点就生效"，开发者看到的是"开发自检工具要求仓库可 `bun install`、普通使用者用前几类命令就够了"。
+
+这种呼应关系是"可观测性"必须双视角覆盖的核心原因：用户视角告诉你**怎么看**，设计视角告诉你**探针插在哪里、这个位置会不会反过来把会话拖垮、哪些观测路径受 feature 门控**。两个视角合在一起，才能让使用者正确选择观测工具的层级（被动看屏幕 → `/debug-tool-call` → Langfuse → `--dump-system-prompt` → `dev:inspect`，按介入深度递增），也让开发者在加新观测维度时知道"挂在 `getAPIProvider()` 同源、走 fire-and-forget、注意 performanceShim 已经装好"——而不是把每个探针都重新设计一遍、甚至不小心把观测路径变成新的内存泄漏源。

docs/outline-output/cross/07-credentials-auth.md

@@ -0,0 +1,260 @@
+# 凭证与认证生命周期
+
+> 同一份"我的令牌存在哪、什么时候过期、改了 key 为什么没生效"的困惑，在使用者眼里是"我刚才输的那串 sk-... 到底被写到了哪个文件、能不能给同事看、明天还会不会自动登录"，在开发者眼里是"为什么 `getOpenAIClient` 要做模块级缓存、为什么 ChatGPT 订阅路径要去读 Codex CLI 的 `~/.codex/auth.json`、为什么 OAuth 刷新要留 5 分钟偏差窗口、为什么 `/provider unset` 只清 Provider 不清 key"。凭证生命周期天然是双视角主题——用户想知道"我的密钥去了哪里、安不安全"，开发者想知道"为什么 token 这么存、这个缓存策略逼出了哪些权衡、跨工具复用凭证是怎么落到代码里的"。
+
+## 产品视角（写给使用者）
+
+这一节回答一个几乎每个新用户都会撞上的问题：**我的密钥和登录令牌，到底去了哪里？什么时候会过期？我改了 key 为什么有时候不生效？** 我们按"凭证存哪 → 怎么登录 → 怎么刷新 → 怎么排错"四段走，每段都给你能直接照做的步骤。
+
+### 第一件事：搞清楚你的凭证存在哪个文件
+
+Claude Code 的凭证不是一个统一的地方，而是**按 Provider 分散在好几个文件**。下面这张清单是你需要知道的全部位置（默认 `CLAUDE_CONFIG_DIR` 没被改写时，它等于 `~/.claude`）：
+
+| 凭证类型 | 存储位置 | 谁会写它 | 谁会读它 |
+|---------|---------|---------|---------|
+| Anthropic OAuth 令牌（claude.ai 订阅） | `~/.claude/.credentials.json` | `/login` OAuth 流程、自动刷新 | `getAnthropicClient` 每次 API 调用前 |
+| 自定义 Anthropic API Key（workspace key） | `~/.claude.json`（userSettings 的 `workspaceApiKey` 字段） | `/login` 里按 W 输入 | `getAuthStatus` / `getAnthropicApiKey` |
+| `ANTHROPIC_API_KEY` 环境变量 | 你的 shell 配置（`.zshrc` / `.bashrc` / CI secrets） | 你自己 | 优先级低于 settings 里的 `workspaceApiKey` |
+| ChatGPT 订阅令牌（用 ChatGPT 订阅当后端） | `~/.claude/openai-chatgpt-auth.json` | `/login` 选 "ChatGPT account" 后写 | `getValidChatGPTAuth` 每次 OpenAI 请求前 |
+| Codex CLI 共享令牌（跨工具复用） | `~/.codex/auth.json` | OpenAI 官方 Codex CLI | Claude Code 找不到自己的 chatgpt 凭证时会回退读它 |
+| OpenAI / Gemini / Grok 兼容层 API Key | `~/.claude/settings.json` 的 `env` 字段（`OPENAI_API_KEY` / `GEMINI_API_KEY` / `GROK_API_KEY` 或 `XAI_API_KEY`） | `/login` 表单填写 | 各 Provider 的 client 实例化时读 `process.env` |
+| Bridge 模式的会话 JWT | 运行时签发，`sk-ant-si-` 前缀 | Remote Control 服务端 | Bridge 每次请求带在 Authorization 头 |
+| 个人覆盖配置（`settings.local.json`） | `~/.claude/settings.local.json` | 你手动编辑 | 不进 git，覆盖 `settings.json` |
+
+**怎么自查**：跑 `/login` 命令，第一屏的 `AuthPlaneSummary`（`src/commands/login/AuthPlaneSummary.tsx`）会把当前生效的凭证来源摘要给你看——是 env var 还是 settings、有没有 workspace key、是不是 claude.ai 订阅。**这个摘要永远不会回显密钥原文**（`getAuthStatus` 的注释明确写了 "ANTHROPIC_API_KEY / workspaceApiKey values are NEVER returned raw; only their presence and source"），所以你截图给同事看是安全的。
+
+### 第二件事：用 `/login` 还是手动改配置？四种登录方式怎么选
+
+Claude Code 支持四种登录路径，选择哪一种取决于你有什么：
+
+1. **claude.ai 订阅账号（Anthropic OAuth）**：在 `/login` 的 ConsoleOAuthFlow 里走 OAuth 设备码流程——它会给你一个 URL 和一个 code，浏览器打开、授权、回来。成功后令牌写进 `~/.claude/.credentials.json`。这是推荐路径，因为它走 Anthropic 官方 OAuth，token 自动刷新、不需要你管过期。
+
+2. **Anthropic API Key（直连 API）**：两种方式。一是 `export ANTHROPIC_API_KEY=sk-ant-...` 写进 shell；二是在 `/login` 里按 W，输入 key，它会存到 `~/.claude.json` 的 `workspaceApiKey`（"workspace" 是因为按工作目录可覆盖）。**settings 里的 key 优先级高于 env var**——如果你两个都设了，settings 赢。
+
+3. **ChatGPT 订阅当后端（复用 OpenAI 订阅）**：`OPENAI_AUTH_MODE=chatgpt` 打开后，`/login` 会走 OpenAI 的设备码流程（`https://auth.openai.com/codex/device`），成功后令牌写进 `~/.claude/openai-chatgpt-auth.json`。**这条路径最大的彩蛋是跨工具共享**：如果你之前装过 OpenAI 官方的 Codex CLI，它的令牌存在 `~/.codex/auth.json`，Claude Code 在自己的文件找不到时会自动回退读 Codex 的（`getValidChatGPTAuth` 的第二段，`src/services/api/openai/chatgptAuth.ts:339-346`）。换句话说：**你在 Codex CLI 登录过，Claude Code 直接就能用，不用重复登录**。
+
+4. **OpenAI 兼容 / Gemini / Grok / 中国 LLM**：全部走 `/login` 的表单填写流程。选 Provider、填 Base URL（OpenAI 兼容层必填）、填 Key、选模型。提交后写入 `~/.claude/settings.json` 的 `env` 字段，同时把 `modelType` 改成对应的 Provider。**中国 LLM 是这条路径的一个精巧分支**：在 ConsoleOAuthFlow 里选 "China LLM Provider"（`src/components/ConsoleOAuthFlow.tsx:1294` 的 `china_provider_select` 表单），会给你一个预设列表，目前包含 DeepSeek、智谱 GLM、通义千问、小米 MiMo 四家（`src/utils/chinaLlmProviders.ts:44` 的 `CHINA_LLM_PROVIDERS`），每家还分"按量计费 API"和"包月 Coding Plan"两档 base URL。选完之后它自动填好 base URL、你只需要填 key，不用记地址。
+
+**一个重要差别**：前三种（claude.ai 订阅 / API Key / ChatGPT 订阅）属于"认证"，后一种（OpenAI 兼容层 / Gemini / Grok）属于"换 Provider"。`/login` 命令同时处理两件事，但 `/provider` 只处理后者——见下文排错段。
+
+### 第三件事：令牌什么时候过期、怎么自动刷新
+
+如果你用 claude.ai 订阅或 ChatGPT 订阅，**你不需要手动刷新令牌**。Claude Code 在每次 API 调用前会检查令牌是否快过期，快过期就自动刷新。
+
+**关键的时间窗口是 5 分钟偏差**。无论是 Anthropic OAuth 还是 ChatGPT OAuth，代码都用同一个常量：
+
+- Anthropic OAuth：`isOAuthTokenExpired`（`src/services/oauth/client.ts:344`）用 `bufferTime = 5 * 60 * 1000`（5 分钟）。当前时间 + 5 分钟 ≥ 过期时间就认为"快过期"，触发刷新。
+- ChatGPT OAuth：`REFRESH_SKEW_MS = 5 * 60 * 1000`（`src/services/api/openai/chatgptAuth.ts:9`），同样的 5 分钟窗口。
+
+**为什么是 5 分钟不是 1 分钟？** 这是容错设计：API 请求的端到端延迟（包括网络、排队、模型推理）可能就有几秒到几十秒。如果你卡在"过期前 10 秒才刷新"，刷新完成时令牌可能已经过期了，请求被拒。5 分钟窗口给整个请求链路留出足够余量——刷新完拿到新令牌，再用它发请求，时间上稳稳的。
+
+**多进程场景**：如果你同时开了几个 Claude Code 终端，它们都会发现令牌过期、都想去刷新。`checkAndRefreshOAuthTokenIfNeededImpl`（`src/utils/auth.ts:1443`）用了 `lockfile.lock(claudeDir)` 文件锁——谁先抢到锁谁刷新，其他进程等锁、拿到锁后再检查一次令牌是否已被刷新（"double-checked locking"），是的话直接用新令牌、不重复刷新。**还有一个跨进程失效机制**（`invalidateOAuthCacheIfDiskChanged`，`auth.ts:1316`）：进程 A 的 `/login` 写了新令牌到 `.credentials.json`，进程 B 通过 mtime 检测到文件变了，清掉自己的内存缓存、重读——避免"B 用 A 早就 revoke 掉的旧令牌反复 401"的死循环。
+
+### 第四件事：我改了 API key 但没生效？三个最常见的"为什么"
+
+这是排错章节里最高频的三个困惑，全部跟凭证生命周期有关。
+
+**困惑 A：我在 `/login` 输了新 key，为什么下一个请求还在用旧的？**
+
+如果你切的是 claude.ai 订阅或 Anthropic API Key（`workspaceApiKey`），`/login` 的 `onDone` 回调（`src/commands/login/login.tsx:33-65`）会做一连串副作用：`stripSignatureBlocks`（清掉绑旧 key 的签名块）、`resetCostState`（重置费用统计）、`authVersion++`（强制 hook 重新拉取 auth 相关数据）。这些做完之后下一次请求就是新 key。
+
+但如果你切的是 **OpenAI 兼容层 / Grok**，就要小心了：`getOpenAIClient`（`src/services/api/openai/client.ts:39`）和 `getGrokClient`（`src/services/api/grok/client.ts:15`）都是**模块级缓存客户端实例**——首次调用读 `process.env.OPENAI_API_KEY` 创建 OpenAI SDK 实例，之后整个会话直接返回这个缓存的实例。你在会话中途改了 `process.env.OPENAI_API_KEY`，缓存里的 client 还握着旧 key。
+
+**解决办法**：要么重启 Claude Code（最简单），要么代码层面调一次 `clearOpenAIClientCache()`（`client.ts:76`）或 `clearGrokClientCache()`（`grok/client.ts:42`）。**注意**：`/login` 表单改 key 的流程会同步更新 `process.env`（`ConsoleOAuthFlow.tsx:1464-1470` 的 `process.env[k] = v` 循环），但**不会自动 clear client cache**——这是已知的"改 key 必须重启"陷阱，尤其影响 dev 模式下的迭代调试。
+
+**困惑 B：我跑了 `/provider unset`，为什么 key 还在？**
+
+`/provider unset`（`src/commands/provider.ts:49-62`）只清 Provider 选择本身——它 `delete` 的是 `CLAUDE_CODE_USE_BEDROCK` / `CLAUDE_CODE_USE_VERTEX` / `CLAUDE_CODE_USE_FOUNDRY` / `CLAUDE_CODE_USE_OPENAI` / `CLAUDE_CODE_USE_GEMINI` / `CLAUDE_CODE_USE_GROK` 这一组 Provider 触发变量，并把 `settings.json` 的 `modelType` 清空。**它不会清 `OPENAI_API_KEY` / `GEMINI_API_KEY` / `GROK_API_KEY` 这些 key 本身**。
+
+这是有意为之——`unset` 的语义是"回到默认 Provider（firstParty）"，不是"清空所有认证"。如果你想彻底清掉某个 Provider 的 key，要手动编辑 `~/.claude/settings.json` 的 `env` 字段，或者 `/logout`（见下文）。
+
+**例外**：如果你切到的是 bedrock / vertex / foundry 这三个云 Provider（`provider.ts:147-161` 的 else 分支），代码会顺手 `delete process.env.OPENAI_API_KEY` 和 `delete process.env.OPENAI_BASE_URL`——因为这些云 Provider 不应该带着 OpenAI 的 key 跑。但 gemini 和 grok 的 key 不会被清。
+
+**困惑 C：我设了 `OPENAI_BASE_URL` 指向自己的端点，为什么有些行为还像在调官方 API？**
+
+这是 `isFirstPartyAnthropicBaseUrl()` 的 TODO 陷阱（`src/utils/model/providers.ts:43-58`）。代码注释直白地写着："这里会有问题, 只配置了 openai 协议的用户, 按理说会为 true 导致问题"。
+
+具体症状：`buildFetch`（`src/services/api/client.ts:366-367`）会在 `getAPIProvider() === 'firstParty' && isFirstPartyAnthropicBaseUrl()` 都为真时，给每个请求注入一个 `x-client-request-id` header（用于服务端日志关联）。但 `isFirstPartyAnthropicBaseUrl()` 只看 `ANTHROPIC_BASE_URL`，不看 `OPENAI_BASE_URL`。如果你只设了 `OPENAI_BASE_URL` 指向自托管端点、没设 `ANTHROPIC_BASE_URL`，`isFirstPartyAnthropicBaseUrl()` 会因为 `ANTHROPIC_BASE_URL` 不存在而返回 `true`，然后这个注入逻辑就被错误地激活了。**目前没有完美绕过**，只能同时设 `ANTHROPIC_BASE_URL` 显式指向你的端点（哪怕你不调 Anthropic 协议）来让判断走 host 比较分支。
+
+### 第五件事：`/logout` 到底清掉了什么
+
+`/logout`（`src/commands/logout/logout.tsx`）是"全部清空"按钮。`performLogout` 会做这一串：
+
+1. `flushTelemetry`（**先** flush 再清凭证，避免清了之后还拿着旧 org 的 telemetry 数据往外发）
+2. `removeApiKey`（清 Anthropic API Key）
+3. `removeChatGPTAuth`（删 `~/.claude/openai-chatgpt-auth.json`）
+4. `clearChatGPTSettingsAuthMode`（清 `OPENAI_AUTH_MODE` env 和 settings）
+5. `secureStorage.delete()`（清安全存储——macOS keychain 或 fallback）
+6. `clearAuthRelatedCaches`（清 OAuth token 缓存、betas 缓存、tool schema 缓存、user cache、Grove 配置缓存、远程管理 settings 缓存、policy limits 缓存）
+7. `saveGlobalConfig` 改 `oauthAccount: undefined`（清账号关联）
+8. **2 秒后 `gracefulShutdownSync(0, 'logout')`**——logout 之后进程会退出
+
+**所以 `/logout` 之后你必须重新 `/login`**。它不像 `/provider unset` 那样保留 key、只切 Provider。
+
+### 给同事分享对话前要注意什么
+
+`/share` 和 `/export` 的产物**默认不包含凭证原文**，但有几个隐私边界要注意：
+
+- `/share`（`src/commands/share/index.ts`）会把错误信息里的 home 目录路径替换成 `~`、把长 stack trace 截断到 200 字符（`sanitizeErrorMessage`，`share/index.ts:31-39`）。这是为了避免在分享链接里泄漏你的本地路径结构。但它**不会**扫描对话内容里的 key——如果你在对话里粘贴过密钥（"帮我调试一下，我的 key 是 sk-..."），那段文本会被原样分享出去。分享前自己搜一下 `sk-` 之类的敏感前缀。
+- `/export` 导出的是 transcript 的子集（消息、工具调用、结果），同样**不主动扫密钥**。导出的 JSON 里不会有 `~/.claude/.credentials.json` 的内容，但会有你在对话里手动输入过的任何东西。
+
+**最稳的做法**：分享前 `/clear` 开一个干净会话复现问题，避免把历史对话里可能含的敏感信息带出去。
+
+## 设计视角（写给开发者）
+
+这一节回答一组环环相扣的设计问题：**为什么 Claude Code 的凭证存储是分散的而不是统一的？为什么 `getOpenAIClient` 做模块级缓存、`getAnthropicClient` 不做？为什么 ChatGPT 订阅路径要去读 Codex CLI 的凭证文件？为什么 OAuth 刷新的偏差窗口两边都是 5 分钟？为什么 `/provider unset` 的清理边界画在"Provider 触发变量"而不是"全部凭证"？** 每个决策都不是随手做的——它们各自回应一个具体的约束或权衡。
+
+### 为什么凭证存储是按 Provider 分散的，而不是统一一个文件
+
+打开凭证文件清单你会发现：Anthropic OAuth 在 `~/.claude/.credentials.json`、ChatGPT OAuth 在 `~/.claude/openai-chatgpt-auth.json`、Codex CLI 共享在 `~/.codex/auth.json`、各兼容层 key 在 `~/.claude/settings.json` 的 `env`、workspace key 在 `~/.claude.json`。**为什么不收敛到一个 `~/.claude/credentials.json`？**
+
+三个理由，重要性递减：
+
+1. **凭证生命周期不一样**。Anthropic OAuth 令牌会自动刷新、文件会被多进程并发写（`auth.ts:1443` 的 lockfile 锁），它需要独立的文件做 mtime 检测（`invalidateOAuthCacheIfDiskChanged`，`auth.ts:1316`）。ChatGPT OAuth 也会刷新但走完全不同的 OAuth 端点（`auth.openai.com` vs Anthropic 的 OAuth 服务器），它有自己的刷新逻辑（`refreshTokens`，`chatgptAuth.ts:289`）。如果塞同一个文件，两种刷新逻辑要协调文件锁、mtime、原子写——复杂度爆炸。**按 Provider 分文件，让每个 Provider 自己管自己的生命周期**，是最干净的切分。
+
+2. **跨工具复用要求路径兼容**。ChatGPT 订阅路径回退读 `~/.codex/auth.json`（`chatgptAuth.ts:339-346`）是为了**复用 Codex CLI 已登录的凭证**——用户在 Codex 登过，Claude Code 就能用，不用重复登录。这个设计的前提是"不修改 Codex 的文件"——Claude Code 只读它，写还是写自己的 `~/.claude/openai-chatgpt-auth.json`。如果两个工具共用一个文件，谁刷新令牌、谁负责写、文件锁怎么共享都会变成跨工具协调问题。**只读对方、写自己**是最低耦合的复用方式。
+
+3. **环境变量与 settings 的分层**。OpenAI / Gemini / Grok 的 key 是通过 `process.env` 读的（`getOpenAIClient` 的 `process.env.OPENAI_API_KEY`，`client.ts:46`），但 `/login` 把它们写到 `settings.json` 的 `env` 字段是为了**持久化 + 跨会话生效**。`applyConfigEnvironmentVariables`（在 `/provider` 命令末尾调用，`provider.ts:145`）负责把 settings.json 的 `env` 字段反推回 `process.env`，这样 client 实例化时就能读到。**为什么不直接写 shell rc 文件？** 因为 Claude Code 不应该改你的 shell 环境——那会把它的配置泄漏到所有终端会话。settings.json 的 `env` 字段是"只在 Claude Code 进程内生效的 env var"，作用域正确。
+
+**这条分散设计的代价**：用户（和文档）需要记住五个不同的文件位置。这是清晰的复杂度——集中式存储看似简洁，但要把五种不同的刷新策略、并发安全、跨工具兼容塞进一个文件，复杂度只会更高、更难调试。
+
+### 为什么 `getOpenAIClient` 做模块级缓存，`getAnthropicClient` 不做
+
+打开两个 client 工厂对比：
+
+- `getOpenAIClient`（`src/services/api/openai/client.ts:39`）：`let cachedClient: OpenAI | null = null`，首次调用创建实例后赋给 `cachedClient`，之后直接 return。需要清空时调 `clearOpenAIClientCache()`（`client.ts:76`）把 `cachedClient = null`。
+- `getGrokClient`（`src/services/api/grok/client.ts:15`）：完全相同的模式，`cachedClient` + `clearGrokClientCache()`。
+- `getAnthropicClient`（`src/services/api/client.ts:84`）：**没有模块级缓存**。每次调用都走完整的 client 构造流程——读 env、检查 OAuth、动态 import Bedrock/Foundry/Vertex SDK、构造 `new Anthropic(...)` 或 `new BedrockClient(...)` 等。
+
+**为什么这种不对称？** 因为两个家族的 client 构造代价完全不同。
+
+OpenAI / Grok 的 client 构造很便宜——读三个 env var、`new OpenAI({ apiKey, baseURL, ... })` 就完了。但每次 API 请求都重新构造一个 OpenAI SDK 实例会有隐性开销：SDK 内部会建立 HTTP agent、连接池、重试策略。**缓存这个实例让连接池能复用**，是合理的性能优化。
+
+Anthropic 路径的 client 构造代价高且动态：它要根据 `CLAUDE_CODE_USE_BEDROCK` / `CLAUDE_CODE_USE_VERTEX` / `CLAUDE_CODE_USE_FOUNDRY` 动态 import 不同的 SDK（`client.ts:153-298`），还要 `await checkAndRefreshOAuthTokenIfNeeded()`、`await refreshAndGetAwsCredentials()`、`await refreshGcpCredentialsIfNeeded()`——**这些都是异步、有副作用的**。每次调用都走一遍这套流程，相当于每次 API 请求都触发一次凭证刷新检查。**关键在于 Anthropic 路径的 client 实例按参数化构造**——`getAnthropicClient({ apiKey, model, ... })` 接收 model/region 参数，不同 model（比如 Haiku vs Sonnet）可能要走不同的 AWS region（`ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION`，`client.ts:157-160`）。模块级单例缓存根本对不上这种参数化需求。
+
+**这条不对称的代价**就是产品视角提到的"困惑 A"——会话中途改 OpenAI/Grok key，缓存里的 client 握着旧 key。`clearOpenAIClientCache` 是逃生口，但 `/login` 表单流程没调它。这是"性能优化 vs 配置变更"的固有张力：缓存越激进，改配置越要手动清缓存。
+
+**为什么 `clearOpenAIClientCache` 还存在？** 因为它服务于 dev/调试场景——开发者在 REPL 里 `process.env.OPENAI_API_KEY = '...'` 手动改环境变量做实验，调一次 clear 就能强制重建 client。生产用户的等价操作是重启进程。
+
+### 为什么 OAuth 刷新偏差窗口两边都是 5 分钟
+
+打开两处刷新判断的代码：
+
+```ts
+// Anthropic OAuth —— src/services/oauth/client.ts:344
+export function isOAuthTokenExpired(expiresAt: number | null): boolean {
+  if (expiresAt === null) return false;
+  const bufferTime = 5 * 60 * 1000;  // 5 分钟
+  const now = Date.now();
+  const expiresWithBuffer = now + bufferTime;
+  return expiresWithBuffer >= expiresAt;
+}
+
+// ChatGPT OAuth —— src/services/api/openai/chatgptAuth.ts:9
+const REFRESH_SKEW_MS = 5 * 60 * 1000;  // 同样 5 分钟
+// ...
+if (expiresAt !== null && expiresAt <= Date.now() + REFRESH_SKEW_MS) {
+  tokens = await refreshTokens(tokens);
+  await saveStoredAuth(tokens);
+}
+```
+
+**两边都是 5 分钟，不是巧合**。这个数字回应一个共同的约束：**API 请求的端到端延迟不可忽略**。
+
+考虑这条时间线：`getValidChatGPTAuth` 判断"快过期"→ 触发 `refreshTokens`（一次 OAuth 端点的网络 round-trip，可能 200ms-2s）→ 拿到新 access_token → 用它发 API 请求（排队 + 模型推理，几秒到几十秒）。如果偏差窗口留得太短（比如 10 秒），就会出现：判断"还没过期"→ 用旧 token 发请求 → 请求到达服务端时 token 已经过期 → 401。5 分钟窗口给整个请求链路（刷新 + 排队 + 推理）留出了充足余量。
+
+**为什么不更长，比如 30 分钟？** 因为偏差窗口越长，刷新越频繁，OAuth 服务端承受的 refresh 请求越多。对 Anthropic 这种用户量级，每个用户每 25 分钟刷一次 vs 每 55 分钟刷一次，服务端负载差一倍。5 分钟是"请求链路延迟的上界估计 + 余量"的工程取舍——它不会卡到过期边界，也不会刷新得太勤。
+
+**ChatGPT 路径的额外复杂度**：`getValidChatGPTAuth`（`chatgptAuth.ts:339-361`）还有一条**读 Codex 文件的回退逻辑**。先读 `~/.claude/openai-chatgpt-auth.json`，读不到再读 `~/.codex/auth.json`。**为什么这么做？** 因为 OpenAI 官方 Codex CLI 用的是同一个 OAuth client_id（`CLIENT_ID = 'app_EMoamEEZ73f0CkXaXp7hrann'`，`chatgptAuth.ts:7`）——也就是说 Codex CLI 和 Claude Code 在 OpenAI 那边注册的是**同一个应用**。用户在 Codex 登录拿到的令牌，Claude Code 拿来直接能用，因为对 OpenAI 服务端来说是同一个 client。这是一个相当大胆的跨工具复用决策——它把"Codex 装了 → Claude Code 免登录"做成了零配置体验，代价是两个工具的 OAuth client_id 必须永远保持一致。
+
+### 为什么 `/provider unset` 的清理边界画在 Provider 触发变量，而不清 key
+
+打开 `src/commands/provider.ts:49-62` 的 `unset` 分支：
+
+```ts
+if (arg === 'unset') {
+  updateSettingsForSource('userSettings', { modelType: undefined });
+  // Also clear all provider-specific env vars to prevent conflicts
+  delete process.env.CLAUDE_CODE_USE_BEDROCK;
+  delete process.env.CLAUDE_CODE_USE_VERTEX;
+  delete process.env.CLAUDE_CODE_USE_FOUNDRY;
+  delete process.env.CLAUDE_CODE_USE_OPENAI;
+  delete process.env.CLAUDE_CODE_USE_GEMINI;
+  delete process.env.CLAUDE_CODE_USE_GROK;
+  return {
+    type: 'text',
+    value: 'API provider cleared (will use environment variables).',
+  };
+}
+```
+
+它清的是 `modelType` 和六个 `CLAUDE_CODE_USE_*`——**全部是"Provider 选择"层**。它不清 `OPENAI_API_KEY` / `GEMINI_API_KEY` / `GROK_API_KEY` / `OPENAI_BASE_URL` / 任何 settings.json `env` 字段里实际存的 key。
+
+**为什么这么画边界？** 因为"切换 Provider"和"清空凭证"是两个独立的用户意图。`/provider unset` 的返回文案说得很清楚："API provider cleared (will use environment variables)"——它的语义是"回到 firstParty 默认，接下来按 env var 决定行为"，**不是"把我所有的 key 都删了"**。如果 unset 顺手清了 key，用户切个 Provider 试一下、再切回来，key 就没了——这是不可接受的数据丢失。
+
+**真正"清凭证"的命令是 `/logout`**（见产品视角）——它做完整的清空 + 进程退出。`unset` 和 `logout` 的分工是：`unset` 改 Provider 选择（可逆，不动凭证），`logout` 清认证身份（不可逆，进程退出）。
+
+**有意思的对比**：`/provider` 切换到 bedrock / vertex / foundry（云 Provider）时（`provider.ts:147-161`），代码会顺手 `delete process.env.OPENAI_API_KEY` 和 `delete process.env.OPENAI_BASE_URL`。**为什么这三个 Provider 特殊？** 因为云 Provider 走的是 Anthropic 协议（Bedrock / Vertex / Foundry 都是 Anthropic 模型在云厂商的托管），不应该带着 OpenAI 协议的 key 跑——带了反而可能让 SDK 误判走错路径。Gemini / Grok 的 key 不被清，是因为它们和 firstParty 之间不存在协议混淆风险（Provider 选择本身就是排他的）。
+
+### 为什么 `/login` 的 `onDone` 要做那么多副作用
+
+打开 `src/commands/login/login.tsx:33-65`——`onDone` 回调在登录成功后会做这一串：
+
+```ts
+context.onChangeAPIKey();
+context.setMessages(stripSignatureBlocks);  // 清掉绑旧 key 的签名块
+resetCostState();                            // 重置费用统计
+void refreshRemoteManagedSettings();         // 拉新的远程管理 settings
+void refreshPolicyLimits();                  // 拉新的 policy limits
+resetUserCache();                            // 清 user 数据缓存
+refreshGrowthBookAfterAuthChange();          // 刷 GrowthBook feature flags
+clearTrustedDeviceToken();                   // 清旧的 trusted device token
+void enrollTrustedDevice();                  // 重新注册 trusted device
+resetAutoModeGateCheck();                    // 重置 auto mode 检查
+context.setAppState(prev => ({ ...prev, authVersion: prev.authVersion + 1 }));
+```
+
+**为什么这么多副作用？** 因为登录本质上是"切换身份"——身份变了，所有跟身份绑定的状态都得跟着刷新，否则就会出现"用 A 身份登录、UI 上显示的还是 B 身份的数据"的撕裂。
+
+逐条看：
+
+- `stripSignatureBlocks`：thinking blocks 和 connector_text 这些字段在 API 响应里是带签名的（绑 API key）。新 key 不能验证旧 key 的签名，所以必须清掉，否则下一次请求会被服务端拒。
+- `resetCostState`：费用统计是按账号累计的，换账号必须清零。
+- `refreshRemoteManagedSettings` / `refreshPolicyLimits`：远程管理的 settings 和 policy limits 是按 org/account 下发的，换账号要重新拉。
+- `resetUserCache` + `refreshGrowthBookAfterAuthChange`：**顺序很重要**——必须先清 user cache 再刷 GrowthBook，否则 GrowthBook 会拿到旧账号的 user 数据去判 feature flag。注释（`login.tsx:46-48`）专门写了这一点。
+- `clearTrustedDeviceToken` + `enrollTrustedDevice`：**也必须先清再注册**（`login.tsx:51-54` 注释）——否则异步的 `enrollTrustedDevice` 还在飞行中时，bridge 调用可能拿着旧账号的 trusted device token 发出去。
+- `authVersion++`：这是一个"脏检查"版本号。`useAppState` 的 hook 订阅这个字段，它变了就触发重新拉取 auth 相关数据（比如 MCP server 列表是按账号不同的）。
+
+**这条设计的核心原则**：登录不是"换一个字符串"，而是"切换一整套绑身份的状态"。`onDone` 这串副作用是在明确枚举所有跟身份绑定的子系统，确保它们同步更新。**代价**是这条回调很长、修改时要小心——加一个新的"绑身份"子系统，必须在这里加对应的刷新调用，否则就会出现状态撕裂。这是"集中式身份切换"的维护成本。
+
+### 为什么凭证文件要 `chmod 0o600`，settings.json 不要
+
+打开 `saveStoredAuth`（`chatgptAuth.ts:148-165`）——写 `openai-chatgpt-auth.json` 时显式 `mode: 0o600`，然后 `chmod(path, 0o600)` 兜底（`chatgptAuth.ts:164`）。**为什么这么严格？**
+
+因为这个文件包含 `access_token` / `refresh_token` / `id_token`——任何能读这个文件的人都能冒用你的 ChatGPT 订阅。0600（owner 读写，其他人无权限）是文件系统层面的最低保护。兜底的 `chmod` 是为了应付 umask 没生效或跨平台差异——某些系统 `writeFile({ mode: 0o600 })` 会被 umask 削成 0644，显式 `chmod` 把权限补回去。
+
+**对比**：`settings.json` 里的 `OPENAI_API_KEY` 没有这种保护——它就是普通 JSON 文件，按你的 umask 走。**为什么差别对待？** 因为 API key 是可以撤销的（去服务商面板 revoke），泄露后的止损路径清晰。OAuth refresh_token 撤销要复杂得多（要走 OAuth revocation endpoint、还可能影响其他用同一 OAuth 应用的工具）。**敏感度越高，文件权限越严**——这是一个朴素但被严格执行的原则。
+
+### 为什么 Anthropic 的 workspace key 走 macOS keychain，OpenAI 兼容层的 key 走明文 settings
+
+打开 `src/utils/secureStorage/`——有 `macOsKeychainStorage.ts` / `plainTextStorage.ts` / `fallbackStorage.ts`。`workspaceApiKey`（Anthropic 的自定义 API Key）在 macOS 上会优先走 keychain（`src/utils/auth.ts` 的 `getApiKeyFromApiKeyHelper` 流程）。但 OpenAI / Gemini / Grok 的 key 直接写在 settings.json 的 `env` 字段、明文存储。
+
+**为什么不对称？** 两个原因：
+
+1. **历史路径依赖**。Anthropic 的 API Key 存储从早期就走 keychain（因为 Anthropic 是默认 Provider，它的 key 是核心凭证）。OpenAI 兼容层是后加的（反编译重建时恢复的），它复用了 `settings.json` 的 `env` 字段——这个字段本来就是"明文环境变量配置"，加 key 进去是最低改造成本。
+2. **跨平台**。macOS keychain 是平台特性，Linux / Windows 没有等价物（`fallbackStorage.ts` 是降级方案）。OpenAI 兼容层要在所有平台一致工作，最简单就是不用 keychain。Anthropic 路径在非 macOS 平台也会降级到 fallback 存储。
+
+**这条不对称的安全含义**：你的 `OPENAI_API_KEY` / `GEMINI_API_KEY` / `GROK_API_KEY` 是**明文存在 `~/.claude/settings.json` 里的**。任何能读这个文件的进程（包括你运行的任何脚本、任何被攻破的进程）都能拿到这些 key。**实践建议**：如果你在共享机器上用，把 key 放 shell env var（`export OPENAI_API_KEY=...`）而不是 `/login` 表单——shell 配置文件至少权限是 0600 默认、不进 git。
+
+## 两视角如何呼应
+
+用户视角的每一个"凭证相关的痛点"，在设计视角都能找到对应的边界决策：
+
+- **"我的密钥去了哪里"**（产品视角的凭证文件清单）对应 **"为什么凭证存储按 Provider 分散、为什么不收敛到一个文件"**（设计视角）——用户要记五个文件位置，是因为三种凭证生命周期（OAuth 自动刷新 / API Key 手动管理 / 兼容层 env 配置）的并发安全和跨工具复用要求不同的存储策略，强行合并只会让复杂度从"五个文件"变成"一个文件里的五种锁"。
+- **"我改了 key 为什么没生效"**（产品视角困惑 A）对应 **"`getOpenAIClient` 为什么做模块级缓存、`getAnthropicClient` 为什么不做"**（设计视角）——用户遇到的是"改了 key 还在用旧的"，开发者看到的是"连接池复用的性能优化 vs 配置变更的缓存失效"的固有张力。`clearOpenAIClientCache` 是逃生口，但 `/login` 表单没调它——这是已知的设计缺口，不是 bug。
+- **"令牌什么时候过期、怎么自动刷新"**（产品视角第三段）对应 **"为什么两边偏差窗口都是 5 分钟、为什么有跨进程 lockfile"**（设计视角）——用户看到的是"不用手动刷新，自动续期"，开发者看到的是"API 请求端到端延迟的工程余量 + 多进程并发刷新的 double-checked locking + 跨进程 mtime 失效"的三重设计。
+- **"`/provider unset` 为什么 key 还在"**（产品视角困惑 B）对应 **"为什么 unset 的清理边界画在 Provider 触发变量、不清 key 本身"**（设计视角）——用户期望 unset 是"全部清空"，开发者把它定位成"可逆的 Provider 切换"，把"不可逆的凭证清空"留给 `/logout`。两个命令的分工是明确且有意的。
+- **"用 Codex CLI 登过，Claude Code 为什么不用再登"**（产品视角第三种登录路径）对应 **"ChatGPT 路径为什么读 `~/.codex/auth.json`、为什么两个工具共用一个 OAuth client_id"**（设计视角）——用户看到的是"零配置跨工具体验"，开发者看到的是"两个工具注册为同一个 OAuth 应用、只读对方凭证、写自己凭证"的最低耦合复用，代价是 client_id 永远不能改。
+- **"分享对话前要注意什么"**（产品视角末段）对应 **"`sanitizeErrorMessage` 为什么只清路径不清 key、为什么 `/share` 和 `/export` 不主动扫密钥"**（设计视角）——用户被告知"分享前自己搜一下 `sk-`"，开发者看到的是"自动扫密钥的误报风险（误伤合法的 sk- 前缀 demo key）和实现成本（要支持几十种 Provider 的 key 格式识别），所以只做路径清理这种零误报的操作，把 key 识别留给用户"。
+
+这种呼应关系是"凭证与认证生命周期"必须双视角覆盖的核心原因：用户视角告诉你**密钥去哪了、怎么管理、出了问题怎么自救**，设计视角告诉你**为什么 token 这么存、这个缓存策略逼出了什么权衡、跨工具复用是怎么落到代码里的**。两个视角合在一起，才能让使用者正确选择登录方式（订阅 OAuth / API Key / 兼容层表单 / 跨工具复用）并知道每种方式的凭证文件位置和过期行为，也让开发者在改 Provider 系统时知道"为什么不能把所有 key 塞一个文件、为什么 client 缓存策略要按 Provider 家族区分、为什么 OAuth 偏差窗口改了会出问题"——而不是把每个决策都重新走一遍、甚至不小心破坏跨工具凭证复用或多进程刷新安全。

docs/outline-output/design/00-prologue.md

@@ -0,0 +1,155 @@
+# 序章：一份被反编译重建的 CLI，为什么处处是"约束的印记"
+
+> 这不是原版代码，而是反编译产物在 Bun/JSC 约束下重建出来的东西——每一个奇怪的设计都有具体的根因。
+
+## 反编译的语义：stub、feature gate、_c() 都是正常的
+
+打开 `src/types/global.d.ts:1`，你会看到这份代码开宗明义的声明：
+
+```ts
+/**
+ * Global declarations for compile-time macros and internal-only identifiers
+ * that are eliminated via Bun's MACRO/bundle feature system.
+ */
+```
+
+这不是普通的 TypeScript 项目。这份代码的源头是编译后的产物，而不是人类手写的源码。类型声明文件里塞满了"只在编译期存在、运行时会被消除"的标识符：`MACRO.VERSION`、`MACRO.BUILD_TIME`、`resolveAntModel()`、`Gates`、`TungstenPill()`。这些东西在原版 Anthropic 内部构建链里是真实的函数和对象，但在反编译产物里，它们只剩下一个类型签名——一个空壳。
+
+再往下看 `global.d.ts:59`：
+
+```ts
+// T — Generic type parameter leaked from React compiler output
+// (react/compiler-runtime emits compiled JSX that loses generic type params)
+declare type T = unknown
+```
+
+`T = unknown`。这不是谁偷懒写了无意义的类型别名。React Compiler（react-compiler-runtime）在编译 JSX 时会把泛型参数丢掉，反编译产物于是到处出现裸露的 `T`。为了让 TypeScript 编译器不报错，只能声明 `type T = unknown`。这是一个典型的"反编译痕迹"——它不是设计决策，而是信息丢失后的补救。
+
+打开 `src/types/react-compiler-runtime.d.ts:1`，类型声明更简洁：
+
+```ts
+declare module 'react/compiler-runtime' {
+  export function c(size: number): unknown[]
+}
+```
+
+一个函数 `c`，接受一个数字参数，返回 `unknown[]`。这个函数在原版 Anthropic 代码库里是 React Compiler 的运行时 memoization 辅助函数，用于生成 `$` 变量（你在反编译的 React 组件里会看到 `const $ = _c(N)` 这样的模式）。但在反编译产物里，编译器把它内联了，原始模块不复存在。为了不破坏下游 import，只能声明一个 `unknown[]` 返回值——类型系统在说"我知道这里有东西，但我不知道它是什么"。
+
+## 全书的叙事主线：约束驱动架构
+
+这本书的组织逻辑不是"这个项目有什么功能"，而是"哪些约束逼出了哪些设计决策"。这个区别很重要。
+
+你将要读到的每一章，都在追问同一个问题：**如果不这么做会怎样？**
+
+- 第一章讲 Code Splitting——答案是"RSS 暴涨到 1GB，CLI 启动就要吃掉你一整 GB 内存"。这不是优化，是生存需求。
+- 第三章讲 performanceShim——答案是"JSC 的 Performance 实现有个永不收缩的 C++ Vector，长会话累积数百 MB 死容量"。
+- 第五章讲 Feature Flag 的三个硬约束——答案是"Bun 编译器 DCE 的 AST 模式匹配限制，`feature()` 只能出现在 `if` 条件位置"。
+
+这本书里几乎每一个看似奇怪的设计——`feature()` 不能赋值给变量、`--version` 必须零模块加载、构建产物要正则替换 `globalThis.Bun`——都指向同一个主题：**你面对的不是一张白纸，而是 JSC 内存模型、Bun 编译器限制、反编译信息丢失这三重约束的交叉压力。**
+
+## 如何阅读本书：打开编辑器，对照锚点
+
+每个章节末尾的"锚点"不是装饰，而是邀请。每一条锚点都是 `文件:行号` 格式，指向代码库中真实存在的代码。
+
+比如本章提到 `src/types/global.d.ts:59` 的 `T = unknown`。你可以现在就打开那个文件，跳到第 59 行，亲眼看到那行代码和它上方的注释。再比如本章开头引用了 `CLAUDE.md`（项目根目录下的那份），第一句话就是：
+
+> This is a **reverse-engineered / decompiled** version of Anthropic's official Claude Code CLI tool.
+
+这不是隐喻。这份代码库的每一个角落都带着反编译的指纹。有些指纹很明显——`declare type T = unknown`、`export function c(size: number): unknown[]`；有些指纹很隐蔽——feature flag 系统的硬约束、模块级单例状态、"42 条 lint 规则关闭"（那是第十五章的内容）。
+
+建议你用 VS Code 或任何编辑器打开这个项目的根目录。每次看到锚点引用时，花十秒钟跳过去看一下。你会发现文档描述和实际代码之间的对应关系非常精确——这比任何架构图都直观。
+
+## 两类禁用 feature：丢失的 stub vs 原本就 stubbed 的
+
+`scripts/defines.ts:39` 的 `DEFAULT_BUILD_FEATURES` 列表里有 65+ 个 feature flag。其中有 8 个被注释掉了：
+
+```ts
+// 'HISTORY_SNIP', // 已禁用：snip 功能暂时关闭
+// 'CONTEXT_COLLAPSE', // 已禁用：实现是空壳 stub，启用后会抑制 auto compact 导致上下文管理完全失效
+// 'FORK_SUBAGENT', // 已禁用：通过 Agent tool 的特殊方式实现了等效功能，无需再开
+// 'UDS_INBOX', // 进程间通信管道（inbox/pipe/peers 等命令）构建后 nodejs 环境卡住
+// 'LAN_PIPES', // 局域网管道，依赖 UDS_INBOX 构建后 nodejs 环境卡住
+// 'REVIEW_ARTIFACT', // 代码审查产物（API 请求无响应，待排查 schema 兼容性）
+// 'SKILL_LEARNING',
+// 'TEAMMEM', // 已禁用：依赖 COORDINATOR_MODE，邮箱文件无限增长
+```
+
+表面上看它们都是"被禁用的"，但禁用的原因截然不同。混淆这两类会导致严重误判。
+
+**第一类：反编译丢失导致的 stub。** `CONTEXT_COLLAPSE`、`HISTORY_SNIP`、`FORK_SUBAGENT`、`UDS_INBOX`、`LAN_PIPES`、`REVIEW_ARTIFACT` 属于这一类。
+
+打开 `src/setup.ts:290` 你会看到：
+
+```ts
+if (feature('CONTEXT_COLLAPSE')) {
+  require('./services/contextCollapse/index.js').initContextCollapse()
+}
+```
+
+`src/services/contextCollapse/` 目录确实存在，里面有 `index.ts`、`operations.ts`、`persist.ts` 三个文件。但注释明确说"实现是空壳 stub，启用后会抑制 auto compact 导致上下文管理完全失效"。反编译过程保留了文件结构和函数签名，但丢失了核心逻辑。如果你强行启用 `FEATURE_CONTEXT_COLLAPSE=1`，init 函数会跑起来，但它做的事情是错误的——它会抑制自动压缩，导致长对话的上下文管理彻底崩溃。
+
+`HISTORY_SNIP` 的情况类似。打开 `src/commands.ts:92`：
+
+```ts
+const forceSnip = feature('HISTORY_SNIP')
+  ? require('./commands/force-snip.js').default
+  : null
+```
+
+但 `src/commands/force-snip/` 目录根本不存在。如果你启用这个 feature，运行时会直接 `MODULE_NOT_FOUND`。这个 feature 在原版里指向一个完整的消息历史裁剪子系统（`src/utils/messages.ts:2652` 里有它的运行时检查逻辑），但反编译过程丢失了 `force-snip` 命令模块。
+
+**第二类：功能原本就 stubbed 的。** `SKILL_LEARNING` 和 `TEAMMEM` 属于这一类。
+
+打开 `src/services/skillLearning/featureCheck.ts:11`：
+
+```ts
+export function isSkillLearningCompiledIn(): boolean {
+  if (feature('SKILL_LEARNING')) return true
+  return false
+}
+```
+
+这个目录下有 20+ 个文件（`agentGenerator.ts`、`evolution.ts`、`instinctParser.ts`、`skillLifecycle.ts` 等），结构完整。这不是反编译丢失——这是 Anthropic 原版里本身就 stubbed 的功能。feature flag 注释写的也很清楚：`SKILL_LEARNING` 的 slash command 被编译进 build，但运行时默认 OFF，需要 operator 主动 `/skill-learning start` 开启。这不是"丢了"，而是"还没开放"。
+
+`TEAMMEM` 也是类似情况。`src/memdir/memdir.ts:7`、`src/utils/memoryFileDetection.ts:17` 等多处引用了 `feature('TEAMMEM')` 的分支逻辑，相关代码路径是完整的。禁用的原因是"依赖 COORDINATOR_MODE，邮箱文件无限增长"——这是一个产品决策，不是反编译事故。
+
+**区分这两类的实用方法**：看被注释掉的那行注释。如果注释说"实现是空壳 stub"或"构建后环境卡住"，那是反编译丢失（第一类）。如果注释说"依赖某 feature"或"待排查"，那是功能本身的问题（第二类）。第一类强行启用会破坏核心功能；第二类启用后可能有 bug 但不会让系统崩溃。
+
+## bun:bundle 的幽灵模块
+
+`src/types/internal-modules.d.ts:10` 声明了一个不存在的模块：
+
+```ts
+declare module 'bun:bundle' {
+  export function feature(name: string): boolean
+}
+```
+
+`bun:bundle` 是 Bun 运行时的内置模块，由 Bun 编译器在构建时解析。你在 Bun 以外的环境里跑 `import { feature } from 'bun:bundle'` 会报错——这个模块只存在于 Bun 的编译管道里。类型声明文件把它写出来，纯粹是为了让 TypeScript 不报 `Cannot find module 'bun:bundle'` 错误。
+
+这个幽灵模块贯穿整个代码库。`scripts/vite-plugin-feature-flags.ts:29` 里有一个 Rollup 插件，专门在 Vite 构建时把 `bun:bundle` 虚拟化为一个始终返回 `false` 的 stub：
+
+```ts
+load(id) {
+  if (id === resolvedVirtualModuleId) {
+    return 'export function feature(name) { return false; }'
+  }
+}
+```
+
+同一个 `feature()` 函数，在 Bun 构建里是编译器的 DCE（dead code elimination）钩子，在 Vite 构建里被插件替换为字面量。两种构建管道对同一个函数的理解完全不同，但产出的行为一致。这种"双管道、单语义"的设计是反编译重建工作的典型特征——你不需要理解原版为什么这么做，你只需要在两条路径上复现相同的行为。
+
+## 反编译产物的类型补丁成本
+
+`bun:bundle` 不是唯一的幽灵模块。同一个文件里还声明了 `bun:ffi`（`internal-modules.d.ts:14`），以及 `bidi-js`、`asciichart`、`@napi-rs/keyring` 等没有 `@types` 包的第三方模块。所有导出都被类型化为 `any` 或最小接口。
+
+这意味着什么？意味着你在阅读代码时看到的类型签名，有很多是"人为补丁"而非"原始设计"。`T = unknown` 是最极端的例子，但更常见的模式是 `Record<string, unknown>`——当反编译丢掉了结构信息时，退化为字典类型是唯一安全的选项。
+
+如果你在代码里看到某个函数接收 `Record<string, unknown>` 参数，或者在某个地方有 `as unknown as SomeType` 的双重断言，那大概率是反编译信息丢失的痕迹。这不是代码质量问题，而是信息损失的必然结果——就像你把一栋建筑拆成零件再重建，总有些螺丝的规格对不上，只能用万能件替代。
+
+## 延伸阅读
+
+- 想了解 Feature Flag 系统为什么有"三个硬约束"，见 [第五章：Feature Flag 系统的三个硬约束](./05-feature-flags.md)
+- 想看 Code Splitting 是怎么被 JSC 内存压力逼出来的，见 [第一章：Code Splitting 不是优化，是生存需求](./01-code-splitting.md)
+- 想了解 biome.json 关掉 42 条规则的反编译指纹，见 [第十五章：biome.json 的 42 条规则关闭](./15-biome-42-rules.md)
+- 想看 performanceShim 如何修补 JSC 内存泄漏，见 [第三章：performanceShim —— JSC 内存泄漏的运行时补丁](./03-performance-shim.md)

docs/outline-output/design/01-code-splitting.md

@@ -0,0 +1,189 @@
+# 第一章：Code Splitting 不是优化，是生存需求
+
+> 17MB 单文件让 Bun/JSC 暴食 1GB 内存，分割成 600+ chunks 才降到 35MB。
+
+## JSC 的贪婪解析 vs V8 懒解析：一场 5 倍的内存鸿沟
+
+打开 `vite.config.ts:94`，你会看到一段与代码看起来无关、却写满血泪的注释：
+
+```
+// Code splitting: Bun/JSC parses the entire single-file bundle eagerly,
+// consuming ~1 GB RSS for a 17 MB output (vs ~220 MB on Node/V8 which
+// lazy-parses). Splitting into chunks allows Bun to load modules on demand,
+// bringing RSS down to ~300 MB.
+```
+
+这段注释不是工程美学，而是测出来的生存数据。把同一个项目两种构建方式分别跑一次 `claude --version`：
+
+- 单文件 17MB 产物 + Bun/JSC：RSS 暴涨到约 1GB
+- 同样 17MB 产物 + Node/V8：RSS 只有约 220MB
+- 切成 600+ chunks + Bun/JSC：`--version` 的 RSS 从 966MB 骤降到 35MB
+
+为什么差这么多？因为 JavaScriptCore（Bun 的 JS 引擎）和 V8（Node 的引擎）对"一个函数被 import 但还没被调用"的假设完全相反：
+
+- **V8 假设你大概率不会立刻执行它**，所以只做懒解析（lazy parsing）—— 函数体在第一次被调用时才完整解析、编译成字节码。17MB 的 bundle 里 90% 的函数是死代码（启动路径根本不会走到），V8 几乎不为它们付钱。
+- **JSC 假设你大概率会立刻执行它**，于是对整个 bundle 做 eager parsing + bytecode 编译 + JIT。17MB 里每一个函数、每一个闭包、每一个 `_c()` 调用都被即时编译成机器码塞进 RSS。死代码和活代码付同样的代价。
+
+反事实推演：如果项目坚持单文件输出会怎样？`claude --version` 会消耗近 1GB 内存——一个本该 50ms 返回版本号的命令，会让用户怀疑 CLI 在偷偷挖矿。这种启动代价直接杀死了工具。
+
+所以"为什么必须 code splitting"的答案不是"分包更优雅"，而是"JSC 的内存模型逼我们切割"。一旦切到 chunks 级别，JSC 的按需加载优势就回来了：Bun 只解析 `cli.js` 入口真正 import 的那些 chunk，其他 chunk 在被 import 之前完全不进内存。
+
+## 双构建管线：Bun.build vs Vite，为什么不能合并
+
+项目里同时存在 `build.ts`（用 `Bun.build()`）和 `vite.config.ts`（用 Rollup），两条链路做的事情高度重叠：都接收 `src/entrypoints/cli.tsx` 作为入口、都启用代码分割、都把 chunks 输出到 `dist/`。
+
+打开 `build.ts:23`，你会看到 Bun 原生构建的全部代码分割配置只有一行：
+
+```ts
+const result = await Bun.build({
+  entrypoints: ['src/entrypoints/cli.tsx'],
+  outdir,
+  target: 'bun',
+  splitting: true,
+  sourcemap: 'linked',
+  define: {
+    ...getMacroDefines(),
+    'process.env.NODE_ENV': JSON.stringify('production'),
+  },
+  features,
+})
+```
+
+`splitting: true` 是 Bun 的原生 code splitting 开关。产物落在 `dist/` 根目录下，每个 chunk 是平铺的 `.js` 文件。
+
+而 Vite 那条链路（`vite.config.ts:91` 的 `rollupOptions`）输出布局完全不同：
+
+```ts
+output: {
+  format: 'es',
+  entryFileNames: 'cli.js',
+  chunkFileNames: 'chunks/[name]-[hash].js',
+},
+```
+
+入口固定是 `dist/cli.js`，所有 chunk 被集中扔进 `dist/chunks/` 子目录。这种布局差异不是审美分歧，而是两条链路要服务不同目的：
+
+- **Bun.build** 是默认开发链路，产物给 Bun 运行时执行。
+- **Vite 链路** 服务于更深度的场景——它需要 `featureFlagsPlugin()`（feature flag 在 transform 阶段替换为字面量，见第五章）、`importMetaRequirePlugin()`（Node.js 兼容补丁）、`.md`/`.txt`/`.html`/`.css` 作为 raw 字符串加载（模拟 Bun 的 text loader 行为，对应 `vite.config.ts:43` 的 `rawAssetPlugin`），以及 `dedupe: ['react', 'react-reconciler', 'react-compiler-runtime']`（保证工作区里只有一份 React，否则两份 reconciler 会让 Ink 渲染器崩掉）。
+
+为什么不直接弃用 Bun.build？因为 Bun 原生构建是最快的开发回路，开发者每次 `bun run build` 不想等 Vite + Rollup 全套 transpile。两条链路在工程上分工明确：Bun.build 是 quick path，Vite 是 production-grade path。
+
+## post-build 阶段：为什么必须 patch `globalThis.Bun` 解构
+
+打开 `build.ts:62`，你会看到构建完成后还要跑一段第二轮补丁：
+
+```ts
+// 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++
+  }
+}
+```
+
+这段正则补丁把 `var {x, y} = globalThis.Bun;` 改写成 `var {x, y} = typeof globalThis.Bun !== "undefined" ? globalThis.Bun : {};`。
+
+为什么要这么做？因为 `@anthropic-ai/sandbox-runtime` 这类第三方依赖在源码里直接 `var {...} = globalThis.Bun;` 解构 Bun 全局对象。在 Bun 运行时下这没事，`globalThis.Bun` 永远存在。但如果用户用 `node dist/cli.js` 启动同一个产物，`globalThis.Bun` 是 `undefined`，对 `undefined` 做解构会立刻抛 `TypeError: Cannot destructure property 'x' of 'globalThis.Bun' as it is undefined`，整个 CLI 启动失败。
+
+补丁的策略是后处理：扫描所有产物文件（包括 `dist/` 平铺文件 + `dist/chunks/` 子目录文件——Vite 链路对应 `scripts/post-build.ts:38` 的第二步扫描），把无保护的解构全部转成带 `typeof` 守卫的版本。这是一种"产物级兼容"——上游源码不改一行，靠后处理把跨运行时兼容性焊死在产物里。
+
+反事实推演：如果不打这个补丁，产物就只能用 `bun` 跑、不能用 `node` 跑，"双入口"承诺（见下一节）直接作废。这恰恰解释了为什么 `build.ts:43` 处理完 `import.meta.require` 之后，紧接着在 `build.ts:62` 处理 `globalThis.Bun` 解构——这两段都是为了让同一份产物同时活在两个运行时里。
+
+## 构建产物同时兼容 bun/node：双入口与 `import.meta.require` 探测
+
+打开 `build.ts:43`，你会看到第一轮补丁：
+
+```ts
+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);`
+```
+
+Bun 把 `import.meta.require` 当作一等公民——它是 Bun 内置的同步 `require`。但 Node.js 不认这个 API。所以补丁把无脑访问替换成运行时探测：在 Bun 下走 `import.meta.require`，在 Node 下退到 `(await import("module")).createRequire(import.meta.url)`，靠 `createRequire` 桥接 CommonJS。
+
+补丁完成后，`build.ts:95` 会生成两个可执行入口：
+
+```ts
+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')
+
+const { chmodSync } = await import('fs')
+chmodSync(cliBun, 0o755)
+chmodSync(cliNode, 0o755)
+```
+
+两个文件的唯一区别是 shebang——一个声明 `#!/usr/bin/env bun`、一个声明 `#!/usr/bin/env node`。两者都 `import "./cli.js"`，加载同一份主产物。
+
+为什么必须保留双入口？因为部署环境五花八门：
+
+- 一些 CI 容器只装了 Node.js
+- 一些用户的开发机偏好 Bun 的启动速度
+- 一些 Docker 镜像为了体积只装 Node.js
+
+如果只发一个 `bun` 入口，Node 用户就用不了；如果只发 `node` 入口，Bun 用户拿不到 `import.meta.require` 的性能优势。双入口让同一份 `dist/cli.js` 适配两种部署，唯一的代价是 96 字节的额外文件。
+
+注意 `build.ts:95` 这段写入的产物是 Bun.build 链路的；Vite 链路对应 `scripts/post-build.ts:71`，逻辑完全镜像——同样的 shebang 写入、同样的 chmod 0o755、同样的 `import "./cli.js"`。两条链路都必须各自生成双入口，因为它们各自产出的 `dist/cli.js` 不能交叉引用。
+
+## distRoot.ts：让 chunk 文件在任何深度都能找到 vendor 二进制
+
+打开 `src/utils/distRoot.ts:15`，你会看到一个被反复使用的 `distRoot` 函数：
+
+```ts
+const distRoot = (() => {
+  const parts = __dirname.split(path.sep)
+  const distIdx = parts.lastIndexOf('dist')
+  if (distIdx !== -1) {
+    return parts.slice(0, distIdx + 1).join(path.sep)
+  }
+  // Dev mode: from src/utils/ → project root
+  const srcIdx = parts.lastIndexOf('src')
+  if (srcIdx !== -1) {
+    return parts.slice(0, srcIdx).join(path.sep)
+  }
+  return __dirname
+})()
+```
+
+这段代码用 `lastIndexOf('dist')` 在 `__dirname` 里倒着找 `dist` 目录，找到就返回那个目录的绝对路径；找不到再找 `src`（dev 模式 fallback）；都找不到就回退到 `__dirname` 本身。
+
+为什么需要这个函数？因为 code splitting 之后，chunk 文件可能躺在三个不同的深度：
+
+- 单文件构建：`dist/cli.js`，深度 = `dist/`
+- 代码分割 Bun.build：`dist/chunk-xxx.js`，深度 = `dist/`
+- 代码分割 Vite：`dist/chunks/chunk-xxx.js`，深度 = `dist/`（多了一层 `chunks/`）
+
+而 vendor 二进制（`dist/vendor/audio-capture/`、`dist/vendor/ripgrep/`）永远在 `dist/vendor/` 下。`ripgrep.ts`、`computerUse/setup.ts`、`claudeInChrome/setup.ts`、`updateCCB.ts` 都需要从各自的位置反推 `dist/` 根目录才能拼出正确的 vendor 路径。
+
+如果用 `import.meta.url` 内联推算，每个调用点都得自己写一遍 `lastIndexOf('dist')` 逻辑——而且一旦 Vite 链路改动 `chunks/` 子目录的深度，所有调用点全部失效。`distRoot.ts` 把这个脆弱推算收敛到一处，让上层调用方写 `path.join(distRoot(), 'vendor/ripgrep/ripgrep-' + process.platform + '-' + process.arch)` 就够了。
+
+反事实推演：如果直接用 `path.resolve(__dirname, '../vendor/ripgrep/...')`，在 Bun.build 平铺布局下能跑、在 Vite `chunks/` 子目录布局下就会拼出 `dist/chunks/vendor/ripgrep/...`——一个根本不存在的路径，Grep 工具一调用就 spawn ENOENT。这就是为什么 `CLAUDE.md` 特意点名 `distRoot` 函数被多个文件复用：vendor 路径解析的脆弱性必须集中收口。
+
+## 锚点的诚实：为什么 Vite 注释说 "~300MB" 而本章说 "35MB"
+
+最后留一个诚实的核对：`vite.config.ts:94` 的注释说 code splitting 后 RSS "bringing RSS down to ~300 MB"，而本章开篇引用的数据是 `--version` 的 35MB。
+
+这两个数字都对，但测量的是不同的东西：
+
+- **35MB** 是 `claude --version` 这种零模块加载的 fast-path（见第二章）——CLI 在加载完入口判断完参数就直接退出，几乎所有 chunk 都没被 import。
+- **300MB** 是 CLI 完整启动、加载完 REPL、初始化完 Ink 渲染器之后的稳态 RSS——大量 chunk 已经按需加载进来了。
+
+这两个数字一起讲完整的故事：code splitting 让 fast-path 极致轻量（35MB），让 full-session 也能控制在合理范围（300MB vs 单文件的 1GB）。如果只引用其中一个数字会误导——前者让人以为 Bun 已经轻如鸿毛，后者让人以为它仍然吃内存。完整的对照表才是这条设计决策的全部证据。
+
+## 延伸阅读
+- 想理解 `--version` 为什么能做到 35MB RSS，见 [第二章：入口的 Fast-Path 优先级链](./02-fast-path.md)
+- 想看 JSC 在长会话里继续作妖的另一个证据（`performanceShim` 兜底 C++ Vector 永不收缩），见 [第三章：performanceShim](./03-performance-shim.md)
+- 想了解 MACRO 编译期注入的另一面（`process.env.NODE_ENV='production'` 顺手干掉 6,889 个 `_debugStack` Error 对象、省下 12MB），见 [第五章：Feature Flag 系统的三个硬约束](./05-feature-flags.md)

docs/outline-output/design/02-fast-path.md

@@ -0,0 +1,156 @@
+# 第二章：入口的 Fast-Path 优先级链 —— 为什么 --version 必须零模块加载
+
+> 十几条快速路径按优先级串接，--version 的代码路径上没有任何 import。
+
+## 从 main() 的第一条分支说起
+
+打开 `src/entrypoints/cli.tsx:76`，你会看到整个 CLI 的入口函数 `main()`。它做的第一件事是 `process.argv.slice(2)`，然后立刻检查是不是 `--version` 或 `-v`：
+
+```typescript
+// src/entrypoints/cli.tsx:80
+if (args.length === 1 && (args[0] === '--version' || args[0] === '-v' || args[0] === '-V')) {
+  console.log(`${MACRO.VERSION} (Claude Code)`);
+  return;
+}
+```
+
+这看起来平淡无奇。但注意注释里写的：**"Fast-path for --version/-v: zero module loading needed"**。整条代码路径不需要任何 `import`。`MACRO.VERSION` 不是运行时变量 -- 它是编译期字面量替换的结果，在产物中会被直接内联为字符串 `"2.7.0"`。打开 `scripts/defines.ts:18`，你会看到它的来源：
+
+```typescript
+// scripts/defines.ts:20
+'MACRO.VERSION': JSON.stringify(pkg.version),
+```
+
+其中 `pkg.version` 读取自 `package.json`。版本号的单一来源是 `package.json`，不是散落在代码各处的 hardcoded 字符串。这是一个看似显而易见、但反编译产物特别容易弄丢的属性 -- 反编译不保留构建元信息，`MACRO.VERSION` 在重建时必须重新接回 `package.json`，否则每次升级都要改两处，版本号漂移就只是时间问题。
+
+**如果不这么做会怎样？** 如果版本号 hardcoded 在 `cli.tsx` 里，`bun run dev` 和 `bun run build` 走两条注入路径（`-d` flag vs `Bun.build define`），两者必须各自维护一份版本号，迟早会漂移。`package.json` 是 npm 生态的约定真相源，所有工具都认它，CI、发布、changelog 生成都从这里读。
+
+## 完整的优先级链
+
+`--version` 之后是 `--dump-system-prompt`（feature-gated，`src/entrypoints/cli.tsx:93`）。这条路径稍微重一点 -- 需要 import `config.js`、`model.js`、`prompts.js`，但仍然是动态 import，不会在 `--version` 被执行时付出任何代价。
+
+然后是 Chrome MCP（`src/entrypoints/cli.tsx:106`）、Computer Use MCP（`src/entrypoints/cli.tsx:116`）、ACP agent（`src/entrypoints/cli.tsx:124`）、weixin（`src/entrypoints/cli.tsx:131`）等独立服务模式的快速路径。
+
+再往下是 `--daemon-worker`（`src/entrypoints/cli.tsx:164`），Bridge/Remote Control（`src/entrypoints/cli.tsx:183`），daemon 子命令（`src/entrypoints/cli.tsx:231`），background sessions 的 `--bg` 快捷方式（`src/entrypoints/cli.tsx:266`），向后兼容的 `ps/logs/attach/kill` 映射（`src/entrypoints/cli.tsx:278`），模板 jobs（`src/entrypoints/cli.tsx:297`），BYOC runners（`src/entrypoints/cli.tsx:319`），tmux worktree（`src/entrypoints/cli.tsx:338`）。
+
+所有路径都满足同一个约束：**只在自身真正需要的模块上做动态 import，然后 return**。没有哪条路径会把无关代码拉进来。
+
+最后，如果没有命中任何快速路径，`src/entrypoints/cli.tsx:375` 才会 `import('../main.jsx')`，加载完整的 Commander.js CLI 定义和 REPL 启动逻辑。
+
+**如果不这么做会怎样？** 如果所有路径都走 `import('../main.jsx')`，那 `claude --version` 的启动延迟就和 `claude` 完整启动一样长。`main.jsx` 有 5674 行，注册了上百个 subcommand，pull 了一整棵依赖树。在一个 code-split 的 600+ chunk 产物中，这意味着 dozens of chunks 要被解析和执行。JSC 又不是 V8 -- 它没有懒解析，每个 chunk 一加载就开始全量编译。
+
+## 一条脆弱但必要的初始化顺序依赖
+
+`src/entrypoints/cli.tsx:52` 到 `cli.tsx:69` 有一段看起来很不寻常的代码：
+
+```typescript
+// src/entrypoints/cli.tsx:55
+// Harness-science L0 ablation baseline. Inlined here (not init.ts) because
+// BashTool/AgentTool/PowerShellTool capture DISABLE_BACKGROUND_TASKS into
+// module-level consts at import time — init() runs too late.
+if (feature('ABLATION_BASELINE') && process.env.CLAUDE_CODE_ABLATION_BASELINE) {
+  for (const k of [
+    'CLAUDE_CODE_SIMPLE',
+    'CLAUDE_CODE_DISABLE_THINKING',
+    'DISABLE_INTERLEAVED_THINKING',
+    'DISABLE_COMPACT',
+    'DISABLE_AUTO_COMPACT',
+    'CLAUDE_CODE_DISABLE_AUTO_MEMORY',
+    'CLAUDE_CODE_DISABLE_BACKGROUND_TASKS',
+  ]) {
+    process.env[k] ??= '1';
+  }
+}
+```
+
+注释说的很直白：这段代码必须 **inline 在 `cli.tsx` 顶层**，不能放在 `init.ts` 或其他任何晚于工具 import 的地方。原因是什么？打开 `packages/builtin-tools/src/tools/BashTool/BashTool.tsx:296`：
+
+```typescript
+// BashTool.tsx:296
+const isBackgroundTasksDisabled =
+  isEnvTruthy(process.env.CLAUDE_CODE_DISABLE_BACKGROUND_TASKS);
+```
+
+这是一个 **模块级 const**。它在 `BashTool.tsx` 被 import 的那一刻求值，之后不再更新。`AgentTool.tsx:118` 和 `PowerShellTool.tsx:254` 也有同样的模式。如果 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 的设置发生在这些工具被 import **之后**，工具会读到 `undefined`，背景任务就不会被禁用。
+
+这就是为什么 ablation baseline 的环境变量注入必须在 `cli.tsx` 顶层 -- 在 `main()` 被调用之前、在任何工具模块被 import 之前。`init.ts` 跑得太晚了，它会被 `main.jsx` 的某处 import 时才执行。
+
+**如果不这么做会怎样？** ablation baseline 的实验数据会失效 -- 某些禁用项会被漏掉，研究者得到的不是真正的 "L0 精简" 基线，而是一个混杂了部分功能的半吊子配置。这在 harness-science 实验里是致命的。
+
+这是一个典型的 **模块求值顺序** 陷阱。在 ESM 中，模块级代码在 import 时执行，而且只执行一次。你不能 "事后补" 一个模块级 const 的值。这不是 bug，这是 ESM 的设计语义 -- 但它在大型工具链中制造了隐式的时序耦合。
+
+`feature('ABLATION_BASELINE')` 的 gate 在外部构建中会被 DCE（Dead Code Elimination）消除。打开 `scripts/defines.ts` 的 `DEFAULT_BUILD_FEATURES` 列表（`scripts/defines.ts:39`），你会发现里面根本没有 `ABLATION_BASELINE`。也就是说，在标准构建产物中，这段代码完全不存在。
+
+## MACRO 编译期注入的三层防线
+
+版本号和构建时间这些常量不是运行时读的。它们有三层注入机制：
+
+**第一层：dev 模式的 `-d` flag**。打开 `scripts/dev.ts:17`，你会看到 `getMacroDefines()` 返回的值被展开为 `-d MACRO.VERSION:"2.7.0"` 之类的命令行参数，传递给 `bun run`。Bun 的 `-d` flag 做的是编译期文本替换，效果等同于 `#define`。
+
+**第二层：build 的 `Bun.build({ define })`**。打开 `build.ts:25`，同样的 `getMacroDefines()` 被传入 `Bun.build` 的 `define` 选项。产物中的 `MACRO.VERSION` 在构建时就变成了字面字符串。
+
+**第三层：运行时 fallback**。打开 `src/entrypoints/cli.tsx:11`，如果 `globalThis.MACRO` 未定义（说明既没有走 dev 也没有走 build，而是直接 `bun src/entrypoints/cli.tsx`），会用环境变量 `CLAUDE_CODE_VERSION` 或 hardcoded 的 fallback 值 `'2.1.888'` 初始化。
+
+为什么需要三层？因为 `cli.tsx` 有三种运行方式：`bun run dev`（dev 脚本注入）、`bun dist/cli.js`（build 注入）、`bun src/entrypoints/cli.tsx`（裸跑，什么注入都没有）。三层防线保证无论哪种方式，`MACRO.VERSION` 都不会是 `undefined`。
+
+**如果不这么做会怎样？** 直接 `bun src/entrypoints/cli.tsx` 时 `MACRO.VERSION` 会抛 `ReferenceError`，因为编译期注入没发生，运行时 fallback 也没装。三层防线确保开发调试时不会被构建系统的遗漏卡住。
+
+## 双入口 cli-bun.js / cli-node.js
+
+`package.json` 的 `bin` 字段注册了两个入口：
+
+```json
+"bin": {
+  "ccb": "dist/cli-node.js",
+  "ccb-bun": "dist/cli-bun.js",
+  "claude-code-best": "dist/cli-node.js"
+}
+```
+
+打开 `dist/cli-bun.js` 和 `dist/cli-node.js`，内容各只有两行：
+
+```javascript
+// dist/cli-bun.js
+#!/usr/bin/env bun
+import "./cli.js"
+
+// dist/cli-node.js
+#!/usr/bin/env node
+import "./cli.js"
+```
+
+同一份 `dist/cli.js` 产物被两个 shebang 不同的 wrapper 引用。`cli-bun.js` 走 Bun 运行时，`cli-node.js` 走 Node.js 运行时。这之所以可行，是因为 `build.ts` 的 post-build 阶段做了两个兼容性修补（`build.ts:43` 和 `build.ts:62`）：把 `import.meta.require` 替换为 Node.js 兼容的 `createRequire`，把 `globalThis.Bun` 解构改为带 fallback 的安全写法。
+
+**如果不这么做会怎样？** 如果只有 `#!/usr/bin/env node` 一个入口，Bun 专属的 `bun:bundle` 模块（`feature()` 函数的来源）在 Node.js 里根本不存在。Node.js 用户会得到 `ERR_MODULE_NOT_FOUND`。反过来，如果只有 bun 入口，就无法在 CI 环境中利用预装的 Node.js 而不必额外安装 Bun。
+
+## 每条快速路径的 feature() gate 都在 parse 阶段可见
+
+整条优先级链里，除了 `--version` 之外，每条快速路径都被 `feature()` 保护。打开 `src/entrypoints/cli.tsx:93`：
+
+```typescript
+if (feature('DUMP_SYSTEM_PROMPT') && args[0] === '--dump-system-prompt') {
+```
+
+以及 `cli.tsx:116`：
+
+```typescript
+} else if (feature('CHICAGO_MCP') && process.argv[2] === '--computer-use-mcp') {
+```
+
+这些 `feature()` 调用不是运行时布尔值查询。打开 `src/types/internal-modules.d.ts:10`，你会看到 `bun:bundle` 模块声明的 `feature` 函数签名。在 Bun 构建时，`feature('FLAG_NAME')` 会被编译器替换为字面量 `true` 或 `false`。如果 flag 未启用，`if (feature('DUMP_SYSTEM_PROMPT') && ...)` 整个分支会在 DCE 阶段被删除，连里面的动态 import 都不会被 Bun 打包进 chunk。
+
+这就是为什么 `feature()` 只能出现在 `if` 条件或三元表达式的直接位置（Bun 编译器的 AST 模式匹配限制），不能赋值给变量、不能放在回调里、不能做 `&&` 链的一部分。它必须在 parse 阶段就可见为可以被静态分析的布尔分支。
+
+**如果不这么做会怎样？** 如果 feature gate 是运行时函数调用，DCE 无法工作，所有快速路径的代码都会被 Bun 打包进产物。即使某个 feature 在目标构建中完全不需要，它的依赖树（import 的模块、那些模块的依赖）仍然会被打包。产物体积膨胀，启动时间变长。在 code-split 的架构下，这意味着更多 chunks 要被解析，RSS 随之上涨。
+
+## startupProfiler: 快速路径的时间戳
+
+非 `--version` 的路径会第一个 import `startupProfiler.js`（`src/entrypoints/cli.tsx:87`），调用 `profileCheckpoint('cli_entry')`。之后每条快速路径都有自己的 checkpoint 名称：`cli_dump_system_prompt_path`、`cli_claude_in_chrome_mcp_path`、`cli_bridge_path` 等等。这形成了一条完整的启动时间线，可以精确测量每个阶段的耗时。
+
+`startupProfiler` 本身有采样控制（`src/utils/startupProfiler.ts:30`）：0.5% 的外部用户和 100% 的内部用户会被采样，其余用户不付出任何性能代价。这个模块不是快速路径本身，但它衡量了快速路径的效果 -- 如果 `--version` 的 checkpoint 和进程退出的时间差大于 10ms，说明有什么东西不该被加载。
+
+## 延伸阅读
+
+- 想看为什么 `performanceShim` 必须是 `cli.tsx` 的第一行 import，见 [第三章](./03-performance-shim.md)
+- 想看 `feature()` 的三个硬约束为什么决定了整个构建管线的设计，见 [第五章](./05-feature-flags.md)
+- 想看 code splitting 如何让快速路径的 chunk 加载成本趋近于零，见 [第一章](./01-code-splitting.md)

docs/outline-output/design/03-performance-shim.md

@@ -0,0 +1,223 @@
+# 第三章：performanceShim —— JSC 内存泄漏的运行时补丁
+
+> 170 行纯 JS 替换全局对象，拦住 JSC C++ Vector 那条永不收缩的内存黑洞。
+
+## 一行 import，必须放在最前面
+
+打开 `src/entrypoints/cli.tsx:1`，整个文件的第一个有效行不是 `#!/usr/bin/env bun`（那是注释），而是：
+
+```typescript
+// src/entrypoints/cli.tsx:2
+// Performance shim MUST be the first import — it replaces globalThis.performance
+// with a JS-backed implementation before React/OTel capture the native reference.
+// Without this, JSC's C++ Vector grows without bound in long-running sessions.
+import '../utils/performanceShim.js';
+```
+
+注意：这一行甚至排在 `import { feature } from 'bun:bundle'` 之前（`cli.tsx:6`），也排在所有业务逻辑 import 之前。`cli.tsx` 是整个程序的真正入口，任何东西都不会比它更早执行。
+
+为什么必须这么早？答案藏在两个消费者的 import 时序里。
+
+## JSC 原生 Performance 的陷阱：C++ Vector 永不收缩
+
+JavaScriptCore（Bun 的 JS 引擎）内置的 `globalThis.performance` 对象把所有 marks、measures 和 resource timings 存储在一个 C++ 层的 `Vector` 里。这个 Vector 的关键问题不是"慢"，而是"只增不减"——即使你调用了 `performance.clearMarks()`，C++ Vector 的 capacity（已分配内存）不会缩小。`clear` 操作只是把逻辑长度归零，底层 buffer 的 capacity 一直挂在那里，被 GC 完全忽略，因为 GC 管不到 C++ 堆。
+
+在短命脚本里这不是问题：进程一退出，操作系统回收一切。但 Claude Code 是一个长驻进程——一次 `claude` 会话可能运行几十分钟甚至更长，`/loop` 模式下更是无限制。每一轮 API 调用，OpenTelemetry 的 `SpanImpl` 都会在 `performance.mark()` 上创建条目（用来记录 span 的 startTime）。一轮对话下来可能积累几千个 marks，但 span 数据在 flush 之后就已经没用了——只是 C++ Vector 还记得它们。
+
+打开 `src/query.ts:359`，你会看到注释里提到了具体的数字：
+
+```typescript
+// src/query.ts:358-360
+// Break the closure chain: toolUseContext captures langfuseTrace which
+// holds SpanImpl → otperformance (the 571MB Performance object). Nulling
+// these after endTrace allows GC to reclaim the span tree.
+```
+
+571MB。这是一个 Performance 对象在长会话里膨胀到的体量。注释里甚至画了一条引用链：`toolUseContext -> langfuseTrace -> SpanImpl -> otperformance`。只要这条链上任何一个节点还活着，那个 571MB 的 Performance 对象就无法被 GC。
+
+反事实推演：如果没有这个 shim，一个运行 30 分钟的 daemon 会话，光是 Performance 对象的 C++ Vector 残留就可能吃掉数百 MB。内存不会随对话轮次增长——它会**阶梯式跳跃**，每次大量 span 被创建又 flush 之后留下一截不可回收的 C++ capacity。这不是 OOM 崩溃，而是那种让系统越来越慢、越来越卡的"温水煮青蛙"式泄漏。
+
+## 为什么保留 `performance.now()` 走原生，只劫持 mark/measure/getEntries
+
+打开 `src/utils/performanceShim.ts:19`，整个文件的第一行实际代码是：
+
+```typescript
+// src/utils/performanceShim.ts:19
+const original = globalThis.performance
+```
+
+然后 `performanceShim.ts:28-30` 实现的 `now()` 函数直接委托给了原生的 `original.now()`：
+
+```typescript
+// src/utils/performanceShim.ts:28-30
+function now(): number {
+  return original.now()
+}
+```
+
+这是一个刻意的性能决策。`performance.now()` 返回的是高精度时间戳（微秒级），底层是一个单调递增的计数器，不涉及任何数据存储，所以零内存开销。Bun/JSC 的原生实现利用了 `clock_gettime(CLOCK_MONOTONIC)` 系统调用，精度和性能都最优。
+
+但 `mark()`、`measure()`、`getEntriesByType()` 是另一回事——它们会在 C++ Vector 里插入和存储条目。shim 把这些操作全部重定向到一个 JS `Map`（`performanceShim.ts:22-26`）：
+
+```typescript
+// src/utils/performanceShim.ts:22-26
+// JS-backed storage — fully GC-able
+const marks = new Map<string, number>()
+const measures = new Map<
+  string,
+  { name: string; startTime: number; duration: number }
+>()
+```
+
+`Map` 是 JS 堆上的普通对象。当 `marks.clear()` 被调用时（`performanceShim.ts:112`），Map 的内部 buffer 会被 V8/Bun 的 GC 正常回收。没有 C++ Vector 的 capacity 残留问题。
+
+反事实推演：如果把 `now()` 也用 JS 实现（比如用 `Date.now()` 或 `process.hrtime()`），精度会降低到毫秒级，而且 OTel 的 span 时间计算依赖 `performance.now()` 与 `performance.timeOrigin` 之间的差值来得到单调递增的相对时间——换成其他时间源会破坏 OTel 的计时语义。
+
+## 为什么不能继承 Performance.prototype
+
+`performanceShim.ts:124-126` 有一个容易被忽略的注释：
+
+```typescript
+// src/utils/performanceShim.ts:124-126
+// Plain object shim — must NOT inherit from Performance.prototype because
+// native getters (onresourcetimingbufferfull, timeOrigin, toJSON) check
+// that `this` is an actual JSC Performance instance and throw otherwise.
+```
+
+如果 shim 用 `Object.create(Performance.prototype)` 来创建，JSC 的原生 getter（比如 `timeOrigin`）会检查 `this instanceof Performance`——当 `this` 是一个 JS 平面对象时，这些原生 getter 会直接抛出 TypeError。所以 shim 必须用纯平面对象（plain object literal），然后手动覆盖需要的属性。
+
+但 `timeOrigin` 是只读属性，shim 需要把它代理回原生对象（`performanceShim.ts:142-144`）：
+
+```typescript
+// src/utils/performanceShim.ts:142-144
+get timeOrigin() {
+  return original.timeOrigin
+},
+```
+
+还有一个细节——`onresourcetimingbufferfull` 的 setter 被故意设成了 no-op（`performanceShim.ts:149-151`）：
+
+```typescript
+// src/utils/performanceShim.ts:149-151
+set onresourcetimingbufferfull(_v: any) {
+  // no-op — prevent accumulation
+},
+```
+
+这是因为 JSC 的 `Performance` 在 resource timing buffer 满时会触发这个回调——但既然 shim 已经把 resource timing 的写入变成了空操作（`clearResourceTimings` 和 `setResourceTimingBufferSize` 都是 `() => {}`），这个回调永远不该被触发，所以 setter 什么都不做。
+
+## "未定义的必备方法"：undici 的 markResourceTiming
+
+`performanceShim.ts:138-140` 里有一行看起来很奇怪——一个永远不做事的空函数，但注释说"必须存在"：
+
+```typescript
+// src/utils/performanceShim.ts:138-140
+// Node.js v22 undici internal calls this after every fetch — must exist to
+// avoid TypeError: markResourceTiming is not a function
+markResourceTiming: (() => {}) as () => void,
+```
+
+Node.js v22 内部使用的 HTTP 客户端 undici，在每次 fetch 完成后都会调用 `performance.markResourceTiming()` 来记录网络请求的时间。构建产物是 Node.js 兼容的（`build.ts` 会后处理 `import.meta.require`），所以当用户用 `node dist/cli.js` 运行时，undici 会期望这个方法存在。如果 shim 不提供它，每次 fetch 都会抛 `TypeError: markResourceTiming is not a function`，整个 HTTP 请求链就断了。
+
+这跟 OpenTelemetry 无关，跟 React 无关——纯粹是 Node.js 运行时的内部约定。shim 的角色不仅是拦截 JSC 的泄漏，还得兼容 Node.js 运行时的接口预期。
+
+## 为什么必须最先 import：原生引用的"快照"语义
+
+`cli.tsx` 把 `performanceShim` 放在第一个 import 的位置，不是风格偏好，而是 JS 模块系统的硬约束。
+
+OpenTelemetry 的 `@opentelemetry/core` 包导出了一个 `otperformance` 对象，它在模块初始化时读取 `globalThis.performance` 并缓存到一个模块级变量里。这个变量在模块的整个生命周期内都不会变——它是一个"快照"，记录的是模块被 import 那一瞬间 `globalThis.performance` 指向什么。
+
+类似的，React 的 reconciler 在初始化时也会读取 `globalThis.performance`。一旦它们捕获了原生 Performance 的引用，后续你再替换 `globalThis.performance` 也无济于事——那些模块仍然持有一条指向原生对象的引用链，mark/measure 继续往那个永不收缩的 C++ Vector 里塞东西。
+
+所以 `performanceShim` 必须在 OTel 和 React 之前安装。`cli.tsx:2` 的 import 保证了这一点——ESM 规范要求 import 按书写顺序深度优先执行，`performanceShim.js` 的顶层代码（`performanceShim.ts:169` 的 `installPerformanceShim()`）会在其他任何模块被加载之前执行完毕。
+
+反事实推演：如果把 `performanceShim` 的 import 放到第 10 行甚至第 50 行，OTel 或 React 很可能在它之前就被某个间接依赖链拉进来了（ESM 的 import 图是深度优先的）。一旦错过窗口，shim 就完全失效，而你还不知道——因为 `performance.now()` 仍然正常工作，只有 `mark/measure` 在偷偷泄漏。
+
+## installPerformanceShim 的幂等保护
+
+`performanceShim.ts:162-165`：
+
+```typescript
+// src/utils/performanceShim.ts:162-165
+export function installPerformanceShim(): void {
+  if ((globalThis as Record<string, unknown>).__performanceShimInstalled) return
+  ;(globalThis as Record<string, unknown>).__performanceShimInstalled = true
+  globalThis.performance = shim
+}
+```
+
+用 `__performanceShimInstalled` 做幂等检查。这个看起来是多余的——shim 不是只在 `cli.tsx` 里 import 一次吗？实际上不是。`performanceShim.ts:169` 的 `installPerformanceShim()` 在模块顶层调用，而 ESM 模块在同一个进程内只执行一次顶层代码，所以正常情况下确实只运行一次。
+
+但这个保护是为 sub-agent 场景预留的——如果 sub-agent 进程（比如 `spawn` 出的子进程）独立加载了 `performanceShim`，幂等检查确保不会创建多层代理。`installPerformanceShim` 是 `export` 的，意味着它也可以被手动调用——这在测试环境或嵌套场景里有用。
+
+## query.ts 的 finally 块：shim 的第二道防线
+
+`cli.tsx` 的第一行 import 是第一道防线。但防线可能被突破——比如 sub-agent 直接 import `src/query.ts` 而不经过 `cli.tsx` 入口。这种情况下 shim 可能还没装上，OTel 的 span marks 就直接写进了原生 Performance。
+
+打开 `src/query.ts:367-380`，在 `yield* queryLoop()` 的 finally 块里，你会看到一段兜底代码：
+
+```typescript
+// src/query.ts:367-380
+// Clear JSC's native Performance buffers. OTel (otperformance) references
+// globalThis.performance which stores marks/measures/resource timings in a
+// C++ Vector that never shrinks. Long-running sessions accumulate hundreds
+// of MB of dead capacity even after spans are flushed and nullified.
+const gPerf = globalThis.performance
+if (gPerf && typeof gPerf.clearMarks === 'function') {
+  try {
+    gPerf.clearMarks()
+    gPerf.clearMeasures?.()
+    gPerf.clearResourceTimings?.()
+  } catch {
+    // Non-critical — some environments may not support all methods
+  }
+}
+```
+
+注意这段代码的防御性写法：先检查 `typeof gPerf.clearMarks === 'function'`，再用 `try/catch` 包裹。如果 shim 已经装上，`clearMarks()` 清空的是 JS Map——无害但也没必要（Map 本来就在每一轮 turn 之后由业务代码正常管理）。如果 shim 没装上，`clearMarks()` 清空的是原生 C++ Vector——逻辑长度归零，但 capacity 不缩小，只能算是"止血"而非"治愈"。
+
+这就是为什么这段 finally 块只是"兜底"：它能阻止情况恶化，但不能根治 C++ Vector 不收缩的问题。真正的修复是 shim 本身——把数据存储从 C++ Vector 转移到 JS Map。
+
+注释里还提到了一个细节（`query.ts:358-360`）：在调用 `clearMarks` 之前，代码先断开了引用链——把 `langfuseTrace`、`langfuseRootTrace`、`langfuseBatchSpan` 全部设为 `null`。这是因为 Langfuse 的 `SpanImpl` 对象持有 `otperformance` 的引用，而 `otperformance` 指向原生 Performance 对象。只有把整条引用链上的指针都断开，GC 才能回收 span 树。
+
+## 为什么 dev 模式把 NODE_ENV 设成 'production'
+
+`scripts/dev.ts:17-22`：
+
+```typescript
+// scripts/dev.ts:17-22
+const defines = {
+  ...getMacroDefines(),
+  // React production mode — prevents 6,889+ _debugStack Error objects
+  // (12MB) from accumulating during long-running sessions.
+  // dev 模式使用 development 模式
+  'process.env.NODE_ENV': JSON.stringify('production'),
+}
+```
+
+这是一个反直觉的决策：开发模式为什么要把 `NODE_ENV` 设成 `production`？React 在 `development` 模式下会为每个组件实例创建一个 `_debugStack` 属性——这是一个完整的 `Error` 对象，用来在 DevTools 里显示组件的调用栈。每个 `Error` 对象携带 stack trace 字符串，大约 1.7KB。
+
+Claude Code 的 UI 层有 149 个组件目录，在一个活跃的 REPL 会话里组件创建/销毁极其频繁。注释里给出了实测数据：6,889 个 `_debugStack` Error 对象，累计 12MB。这不是一次性的——组件在每次渲染周期都会重新创建，这些 Error 对象在 development 模式下会不断累积。
+
+`process.env.NODE_ENV` 在这里是通过 Bun 的 `-d` flag（`scripts/dev.ts:25-28`）做编译期替换的——它不是运行时的 `process.env` 读取，而是在编译时被字面量 `'production'` 替换。这意味着 React 的条件分支（`if (process.env.NODE_ENV !== 'production')`）会在编译期被 DCE（Dead Code Elimination）完全移除，零运行时开销。
+
+注释里有一处中文"dev 模式使用 development 模式"跟实际代码矛盾——代码确实设成了 `production`。这是反编译产物里残留的原始注释与实际行为不一致的痕迹之一：原始代码可能在某个迭代中从 `development` 改成了 `production`，但注释没有同步更新。
+
+反事实推演：如果 dev 模式保留 `development`，每次启动 REPL 后几分钟就会积累 12MB 的 `_debugStack` 对象。对一个本来就因为 JSC eager parsing 而内存紧张的运行时来说，这是雪上加霜。
+
+## 两个防御层次的设计哲学
+
+`performanceShim` 和 `NODE_ENV='production'` 解决的是同一个类问题：JSC 运行时在长会话场景下的内存管理缺陷。但它们用了完全不同的策略：
+
+- `performanceShim` 是**替换策略**：在消费者看到原生对象之前，用一个可控的替代品换掉它。这需要精确的时序控制（必须第一个 import）。
+- `NODE_ENV='production'` 是**消除策略**：通过编译期 DCE 让问题代码根本不存在于产物中。不需要时序控制，因为代码已经被删除了。
+
+`query.ts:367` 的 `clearMarks` 兜底是第三种策略——**缓解策略**：问题已经发生了，但至少不让它继续恶化。它承认 shim 可能没装上，而 C++ Vector 已经在泄漏了。
+
+三层防御，从"预防"到"消除"到"缓解"，覆盖了不同场景下的内存泄漏路径。这种分层不是过度工程——每一层对应的失败模式都不一样，而且每一层的失败概率都不为零。
+
+## 延伸阅读
+- 想看 JSC 的另一个内存陷阱（eager parsing 导致 17MB 单文件暴食 1GB），见 [第一章：Code Splitting 不是优化，是生存需求](./01-code-splitting.md)
+- 想理解 `process.env.NODE_ENV` 编译期替换背后的 Bun 编译器 DCE 机制，见 [第五章：Feature Flag 系统的三个硬约束](./05-feature-flags.md)
+- 想看 `query.ts` 的 finally 块在更大上下文中的作用（async generator 的生命周期管理），见 [第四章：核心 Query Loop —— 为什么 query() 是 async generator](./04-query-loop.md)
+- 想了解 Langfuse span 引用链如何与 OTel 的 `otperformance` 串联，见 [第十一章：状态管理](./11-state-management.md)

docs/outline-output/design/04-query-loop.md

@@ -0,0 +1,261 @@
+# 第四章：核心 Query Loop -- 为什么 query() 是 async generator
+
+> 流式响应把"结果"与"副作用"解耦，调用方选择性消费——这是 async generator 而不是回调或事件发射器的根本原因。
+
+## async generator vs 回调：为什么用 yield 而不是 EventEmitter
+
+打开 `src/query.ts:276`，你会看到整个 query loop 的核心签名：
+
+```ts
+export async function* query(
+  params: QueryParams,
+): AsyncGenerator<
+  | StreamEvent
+  | RequestStartEvent
+  | Message
+  | TombstoneMessage
+  | ToolUseSummaryMessage,
+  Terminal
+>
+```
+
+返回类型是 `AsyncGenerator<YieldedType, ReturnType>`。每次 `yield` 产出一个消息，最终 `return` 一个 `Terminal` 对象。这个设计不是风格偏好——它解决了一个具体的架构问题：**谁控制消息的流向**。
+
+如果用 EventEmitter，调用方需要注册多个 listener（`on('message')`, `on('error')`, `on('end')`），然后在一个外部数组里手动拼装消息流。事件的消费者和 query loop 的执行是解耦的——你不知道 loop 在 yield 消息的时候自己处于什么状态。
+
+如果用 callback，调用方需要在 callback 里处理分支逻辑：这是 tool_use 还是 thinking block？是否需要 withhold？这些分支本质上属于 query loop 的内部状态机，但 callback 把它们推给了调用方。
+
+async generator 把状态机留在 loop 内部，只把"我现在有一个消息给你"这个事实暴露出去。调用方写一个简单的 `for await`，里面只关心"拿到消息后做什么"，不需要知道 loop 有几条 continue 路径、是否在 withhold 错误、是否正在重试 fallback 模型。
+
+反事实推演：如果用 EventEmitter，`QueryEngine` 在 `src/QueryEngine.ts:688` 的消费循环会变成一个散落着 `if` 分支的事件处理器，而不是一个线性的 `switch (message.type)` 结构。更关键的是，`yield` 天然支持背压——调用方没消费完，loop 就不继续。EventEmitter 没有这个能力，消息会在内存里堆积。
+
+## queryLoop() 的委托模式：两层 generator 的分离
+
+`query()` 本身并不直接包含 `while (true)` 循环。它做的是三件事：初始化 Langfuse trace、委托给 `queryLoop()`、在 finally 块里清理资源和通知命令生命周期。
+
+打开 `src/query.ts:393`，你会看到 `queryLoop()`：
+
+```ts
+async function* queryLoop(
+  params: QueryParams,
+  consumedCommandUuids: string[],
+  consumedAutonomyCommands: QueuedCommand[],
+): AsyncGenerator<...> {
+```
+
+`query()` 用 `yield*` 把自己变成 `queryLoop()` 的透明管道。`yield*` 委托意味着 `query()` 产出的每一条消息都来自 `queryLoop()`，但 `query()` 的 finally 块在 `queryLoop()` 结束（无论是正常 return 还是 throw）后一定会执行。
+
+为什么要把清理逻辑放在外层 generator 的 finally 里？因为 `queryLoop()` 内部有 7 个 `state = next; continue` 跳转点（打开 `src/query.ts:1372`、`src/query.ts:1437`、`src/query.ts:1524`、`src/query.ts:1581`、`src/query.ts:1616` 等处），每个跳转都可能因为新状态而触发不同路径。如果把清理分散在每个 return 之前，任何一个遗漏都会泄漏。`yield*` 的保证是：无论内层 generator 怎么退出，外层 finally 一定跑。
+
+打开 `src/query.ts:367` 看那个 finally 块在做什么：
+
+```ts
+const gPerf = globalThis.performance
+if (gPerf && typeof gPerf.clearMarks === 'function') {
+  try {
+    gPerf.clearMarks()
+    gPerf.clearMeasures?.()
+    gPerf.clearResourceTimings?.()
+  } catch { }
+}
+```
+
+这是上一章讲过的 `performanceShim` 的兜底防线。如果 sub-agent 直接 import `query.ts` 而没经过 `cli.tsx` 的 shim 注入，JSC 原生 Performance 的 C++ Vector 仍然会在每轮循环中膨胀。finally 块在这里做了最后一道清理。
+
+## thinking 块的三条硬约束
+
+打开 `src/query.ts:181`，你会看到一段罕见的、用中世纪英语风格写的注释：
+
+```ts
+/**
+ * The rules of thinking are lengthy and fortuitous. ...
+ *
+ * The rules follow:
+ * 1. A message that contains a thinking or redacted_thinking block must be part of a query whose max_thinking_length > 0
+ * 2. A thinking block may not be the last message in a block
+ * 3. Thinking blocks must be preserved for the duration of an assistant trajectory
+ *     (a single turn, or if that turn includes a tool_use block then also its
+ *      subsequent tool_result and the following assistant message)
+ *
+ * Heed these rules well, young wizard. For they are the rules of thinking, and
+ * the rules of thinking are the rules of the universe. If ye does not heed these
+ * rules, ye will be punished with an entire day of debugging and hair pulling.
+ */
+```
+
+这三条规则是 Anthropic API 的硬性约束。违反任何一条都会得到 400 错误。反编译者在这里留下了这段风格化的注释，因为他们在调试时确实被这些规则惩罚过。
+
+规则 1 意味着：如果启用了 thinking，`max_thinking_length` 参数必须大于 0。否则 API 拒绝带 thinking block 的请求。
+
+规则 2 意味着：thinking block 后面必须有内容（text 或 tool_use）。不能以 thinking 结束一条消息。在恢复循环（下文讲）中，这决定了 recovery message 的构造方式——你不能只发一个 thinking block，必须在后面跟一个续写指令。
+
+规则 3 意味着：thinking block 的生命周期是整个"assistant 轨迹"——一次单轮，或者如果那次调用了工具，还包括工具结果和下一轮 assistant 回复。这意味着在工具执行的中间步骤里，thinking block 必须原封不动地保留在消息历史中。不能因为压缩或 compact 而把 thinking block 从轨迹中摘出去。
+
+反事实推演：如果没有规则 3，compact 算法可以把 thinking block 当作普通内容摘要掉。但 API 校验会 400，所以 compact 逻辑必须特别处理 thinking block——要么保留，要么在 compact 前把它从轨迹里剥离。这增加了 compact 的复杂性，但无法绕过。
+
+## MAX_OUTPUT_TOKENS_RECOVERY_LIMIT=3：扣留错误的恢复博弈
+
+打开 `src/query.ts:194`：
+
+```ts
+const MAX_OUTPUT_TOKENS_RECOVERY_LIMIT = 3
+```
+
+这个数字后面藏着一个精巧的设计决策。当 Claude 的输出触及 `max_output_tokens` 上限时，API 返回一个带 `apiError: 'max_output_tokens'` 的 assistant message。正常情况下，这个错误应该直接 yield 给调用方。但问题在于：SDK 调用方（比如 cowork、desktop 客户端）会在收到任何带 `error` 字段的消息时**立即终止会话**。
+
+打开 `src/query.ts:196` 的注释：
+
+```ts
+/**
+ * Is this a max_output_tokens error message? If so, the streaming loop should
+ * withhold it from SDK callers until we know whether the recovery loop can
+ * continue. Yielding early leaks an intermediate error to SDK callers (e.g.
+ * cowork/desktop) that terminate the session on any `error` field — the
+ * recovery loop keeps running but nobody is listening.
+ */
+```
+
+这就是为什么有 `isWithheldMaxOutputTokens` 函数（`src/query.ts:205`）。在流式循环中（`src/query.ts:1059`），如果消息是 `max_output_tokens` 错误，它不会被 yield，而是被扣留。
+
+恢复机制分两个阶段：
+
+**阶段 1：升级重试。** 如果从未设置过 `maxOutputTokensOverride`（意味着使用了默认的 8k 上限），把上限提升到 `ESCALATED_MAX_TOKENS`（`src/query.ts:1472`），然后用 `continue` 重试同一个请求。不需要插入 recovery message——模型拿到更大的上限后能自己续写。这个阶段只触发一次。
+
+**阶段 2：多轮恢复。** 如果升级后仍然触及上限（或者一开始就用了自定义上限），插入一条 `isMeta: true` 的 user message（`src/query.ts:1497`），内容是 `"Output token limit hit. Resume directly — no apology, no recap of what you were doing. Pick up mid-thought if that is where the cut happened."`，然后 `continue` 重试。这个阶段最多触发 3 次（`MAX_OUTPUT_TOKENS_RECOVERY_LIMIT`）。
+
+3 次是个工程折中：太少会导致长代码生成任务频繁失败，太多会导致无限循环。在极端情况下（模型陷入重复输出），3 次重试足以检测到问题并 surface 错误。
+
+打开 `src/query/transitions.ts` 可以看到所有 continue 原因的类型定义：
+
+```ts
+export type Continue =
+  | { reason: 'collapse_drain_retry'; committed: number }
+  | { reason: 'reactive_compact_retry' }
+  | { reason: 'max_output_tokens_escalate' }
+  | { reason: 'max_output_tokens_recovery'; attempt: number }
+  | { reason: 'stop_hook_blocking' }
+  | { reason: 'token_budget_continuation' }
+  | { reason: 'next_turn' }
+```
+
+每个 `continue` 站点都构造一个新的 `State` 对象（`src/query.ts:261`），包含完整的 9 个字段。这不是偷懒——用解构 + 单一赋值 `state = next` 代替 9 个独立赋值，让每个 continue 站点只改它关心的字段，其余字段从解构的旧值自动继承。如果用 9 个独立赋值，任何一个遗漏都会导致状态不一致。
+
+反事实推演：如果 `max_output_tokens` 错误不被扣留而是直接 yield，SDK 调用方会在 recovery loop 还在跑的时候就断开连接。recovery loop 可能成功续写了剩余内容，但没有人听。用户看到的是一个截断的回答和"出错了"的提示，而实际上再等几秒就能拿到完整结果。
+
+## QueryEngine：跨 turn 的会话编排器
+
+`query()` 处理的是单次用户输入到完成（或失败）的完整过程。但一个对话有多个 turn。`QueryEngine`（`src/QueryEngine.ts:192`）就是这个跨 turn 的编排器。
+
+打开 `src/QueryEngine.ts:192` 的类定义：
+
+```ts
+export class QueryEngine {
+  private config: QueryEngineConfig
+  private mutableMessages: Message[]
+  private abortController: AbortController
+  private permissionDenials: SDKPermissionDenial[]
+  private totalUsage: NonNullableUsage
+  private hasHandledOrphanedPermission = false
+  private readFileState: FileStateCache
+  private discoveredSkillNames = new Set<string>()
+  private loadedNestedMemoryPaths = new Set<string>()
+```
+
+每个字段都有明确的跨 turn 生命周期：
+
+- `mutableMessages`：消息历史，跨 turn 不断增长（除非 compact/snip）
+- `totalUsage`：token 消耗累计，跨 turn 叠加
+- `readFileState`：文件内容缓存，避免跨 turn 重复读取同一个文件
+- `discoveredSkillNames`：turn 内发现的新 skill 名称，每个 turn 开始时清空（`src/QueryEngine.ts:246`），防止无限增长
+
+`submitMessage()` 本身也是 async generator（`src/QueryEngine.ts:217`）：
+
+```ts
+async *submitMessage(
+  prompt: string | ContentBlockParam[],
+  options?: { uuid?: string; isMeta?: boolean },
+): AsyncGenerator<SDKMessage, void, unknown>
+```
+
+它在内部调用 `query()`（`src/QueryEngine.ts:688`），但做了三件 `query()` 不管的事：
+
+1. **消息持久化**：在进入 query loop 之前就把用户消息写入 transcript（`src/QueryEngine.ts:460`），确保即使进程在 API 响应到达前被杀死，`--resume` 也能恢复到发送点。
+
+2. **SDK 消息转换**：把内部 `Message` 类型转换为 `SDKMessage` 格式，通过 `normalizeMessage` 做字段映射（`src/QueryEngine.ts:789`）。
+
+3. **权限拒绝追踪**：通过 `wrappedCanUseTool`（`src/QueryEngine.ts:253`）包装每个工具调用的权限检查，记录拒绝事件到 `permissionDenials`，最终随 `result` 消息返回给 SDK 调用方。
+
+为什么不把这些逻辑放进 `query()` 里？因为 `query()` 需要保持与 UI 路径（REPL screen）的通用性。REPL 不做 transcript 持久化（它有自己的会话管理），不需要 SDK 消息转换。`QueryEngine` 是 SDK/Headless 路径特有的编排层。
+
+反事实推演：如果把 transcript 持久化放进 `query()`，REPL 路径也必须处理 transcript 逻辑，要么做条件分支（污染 `query()` 的纯净性），要么 REPlay 模式也写 transcript（造成重复写入）。分离后，`query()` 保持通用，`QueryEngine` 专注 SDK 语义。
+
+## snipReplay 回调：feature gate 的依赖注入技巧
+
+打开 `src/QueryEngine.ts:166`，你会看到 `snipReplay` 字段的注释：
+
+```ts
+/**
+ * Snip-boundary handler: receives each yielded system message plus the
+ * current mutableMessages store. Returns undefined if the message is not a
+ * snip boundary; otherwise returns the replayed snip result. Injected by
+ * ask() when HISTORY_SNIP is enabled so feature-gated strings stay inside
+ * the gated module (keeps QueryEngine free of excluded strings and testable
+ * despite feature() returning false under bun test).
+ */
+```
+
+这是一个精心设计的依赖注入模式。`QueryEngine` 本身不 import `snipCompact.js`——它只定义了一个回调接口。实际的 snip 逻辑在 `src/QueryEngine.ts:1346` 处，由工厂函数有条件地注入：
+
+```ts
+...(feature('HISTORY_SNIP')
+  ? {
+      snipReplay: (yielded: Message, store: Message[]) => {
+        if (!snipProjection!.isSnipBoundaryMessage(yielded))
+          return undefined
+        return snipModule!.snipCompactIfNeeded(store, { force: true })
+      },
+    }
+  : {}),
+```
+
+当 `HISTORY_SNIP` 关闭时（包括 `bun test` 环境下 `feature()` 返回 `false`），`snipReplay` 就是 `undefined`。`QueryEngine` 在 `src/QueryEngine.ts:948` 用可选链调用它：
+
+```ts
+const snipResult = this.config.snipReplay?.(msg, this.mutableMessages)
+```
+
+这样做解决了两个问题：
+
+**问题 1：excluded-strings 检查。** `snipCompact.js` 里包含 snip 特有的字符串（边界消息文本等）。如果 `QueryEngine` 直接 import 它，即使在 feature 关闭时，这些字符串也会被 bundle 进产物，触发内部的 excluded-strings 安全检查。通过回调注入，feature 关闭时 `snipCompact.js` 根本不会被 import。
+
+**问题 2：测试隔离。** `bun test` 下 `feature()` 永远返回 `false`。如果 `QueryEngine` 直接依赖 `feature('HISTORY_SNIP')` 的结果来决定控制流，测试时所有 snip 分支都是死代码。通过回调注入，测试时 `snipReplay` 是 `undefined`，所有 snip 逻辑被跳过，`QueryEngine` 的主路径仍然可测。想要测试 snip 行为的测试可以手动注入一个 mock 回调。
+
+反事实推演：如果不用回调注入而是直接在 `QueryEngine` 里写 `if (feature('HISTORY_SNIP')) { snipModule.snipCompactIfNeeded(...) }`，`bun test` 下这个分支永远不执行。测试无法覆盖 snip 的边界情况。更糟的是，每次有人改了 `snipCompact.js` 的导出签名，`QueryEngine` 的类型检查也会报错——即使 feature 关闭时这段代码根本不会运行。
+
+## 无限循环的 `while(true)` 和它 7 个出口
+
+回到 `queryLoop()` 的 `src/query.ts:460`：
+
+```ts
+// eslint-disable-next-line no-constant-condition
+while (true) {
+```
+
+这不是失控的循环。它是一个有限状态机，每个 `continue` 都带着一个明确的 `transition` 原因（记录在 `src/query/transitions.ts:13` 的 `Continue` 类型中）。循环出口有三类：
+
+**正常退出（return Terminal）：** `completed`（`src/query.ts:1633`）、`blocking_limit`（`src/query.ts:830`）、`image_error`（`src/query.ts:1224`）、`model_error`（`src/query.ts:1243`）、`aborted_streaming`（`src/query.ts:1324`）、`stop_hook_prevented`（`src/query.ts:1555`）、`prompt_too_long`（`src/query.ts:1448`）、`max_turns`。
+
+**异常退出（throw）：** 任何未被内层 try/catch 捕获的异常会向上传播，`query()` 的外层 finally 块负责清理。
+
+**continue 跳转（state = next; continue）：** 7 个跳转点覆盖恢复场景：context collapse drain retry、reactive compact retry、max_output_tokens 升级、max_output_tokens 多轮恢复、stop hook blocking、token budget continuation、next turn（工具调用后的下一轮）。
+
+每个 continue 站点构造一个完整的新 `State` 对象。这不是冗余——`State` 类型有 9 个字段，其中 `transition` 字段记录了"为什么继续"。测试可以断言 `state.transition?.reason === 'max_output_tokens_recovery'` 来验证恢复路径是否被触发，而不需要检查消息内容。
+
+反事实推演：如果不用统一的 `State` 对象而是用散落的变量赋值（`messages = newMessages; toolUseContext = newCtx; maxOutputTokensRecoveryCount++`），任何一个 continue 站点漏了一个变量都会导致后续迭代读到过期的状态。`state = { ...state, messages, toolUseContext, ... }` 的模式虽然看起来啰嗦，但保证了每次跳转都是原子替换。
+
+## 延伸阅读
+
+- 想看 query loop 的内存防线（performanceShim），见 [第三章](./03-performance-shim.md)
+- 想看 feature flag 为什么让 `query()` 顶部的 conditional require 成为必须，见 [第五章](./05-feature-flags.md)
+- 想看 QueryEngine 的上层状态管理（bootstrap/state.ts 的 singleton 限制），见 [第十一章](./11-state-management.md)
+- 想看 query loop 里的 compact 子系统如何被触发，见产品大纲第三章"上下文管理与自动压缩"

docs/outline-output/design/05-feature-flags.md

@@ -0,0 +1,265 @@
+# 第五章：Feature Flag 系统的三个硬约束
+
+> `feature()` 不是普通函数，它是 Bun 编译器用来做死代码消除的语法标记。
+
+打开 `src/types/internal-modules.d.ts:10`，你会看到这样一行声明：
+
+```ts
+declare module 'bun:bundle' {
+  export function feature(name: string): boolean
+}
+```
+
+这是一个虚假的模块声明 -- `bun:bundle` 不存在于文件系统上，也不是 npm 包。它是 Bun 编译器在打包（`Bun.build()`）时内建的编译期原语。当 `Bun.build()` 看到 `feature('X')` 时，它会根据构建配置中的 `features` 列表决定把调用点替换为 `true` 或 `false`，然后对所有不可达分支执行死代码消除（Dead Code Elimination，DCE）。
+
+反编译重建之后，这个原语不再由编译器直接提供，必须通过类型声明 + 双构建管线各自模拟。这带来了三个硬约束，贯穿了整个代码库的每一个 feature-gated 代码块。
+
+## 约束一：`feature()` 只能出现在 `if` 条件或三元表达式的位置
+
+CLAUDE.md 里有一条铁律：
+
+> `feature()` 只能直接用在 `if` 语句或三元表达式的条件位置，不能赋值给变量、不能放在箭头函数体里、不能作为 `&&` 链的一部分。
+
+打开 `src/hooks/useReplBridge.tsx:117`，你能看到一段注释精确解释了为什么：
+
+```ts
+// feature() check must use positive pattern for dead code elimination —
+// negative pattern (if (!feature(...)) return) does NOT eliminate
+// dynamic imports below.
+if (feature('BRIDGE_MODE')) {
+```
+
+这个约束的根源是 Bun 编译器 AST 模式匹配的局限性。编译器只识别两种模式：
+
+1. `if (feature('X')) { ... }` -- 把 `feature('X')` 替换为 `false` 后，整个代码块变成 `if (false) { ... }`，DCE 可以整块删除。
+2. `feature('X') ? a : b` -- 替换后变成 `false ? a : b` 或 `true ? a : b`，DCE 可以删掉不会走的分支。
+
+如果你写成 `const enabled = feature('X'); if (enabled) { ... }`，编译器看到的是对变量 `enabled` 的判断，无法确定其值为常量，整个 feature-gated 代码块都会保留在产物里。
+
+**反事实推演**：如果 `feature()` 能赋值给变量，整个 `tools.ts` 的条件导入模式就不需要那么别扭的 `feature('X') ? require(...) : null` 三元表达式了。你可以写 `const enabled = feature('X'); const tool = enabled ? require(...) : null;`，代码可读性会好很多。但代价是：所有被 gate 的代码（包括 `require()` 引用不存在的文件）都会被打进产物，运行时可能触发 `MODULE_NOT_FOUND` 崩溃。
+
+### 正面模式与负面模式的陷阱
+
+`src/hooks/useReplBridge.tsx:117` 提到了另一个细微之处：**正面模式**（`if (feature('X'))`）才能触发 DCE，**负面模式**（`if (!feature('X')) return`）不行。
+
+打开 `src/entrypoints/cli.tsx:165` 看一个正面模式的例子：
+
+```ts
+if (!feature('DAEMON')) {
+  console.error('Error: --daemon-worker requires DAEMON feature...');
+  process.exitCode = 1;
+  return;
+}
+```
+
+这里用了 `!feature('DAEMON')`，但注意后面的 `return` 是从 `main()` 函数退出的，不是 return 从一个 require 块。DCE 只需要把 `feature('DAEMON')` 替换为 `false` 后变成 `if (!false)` 即 `if (true)`，保留这个检查分支没问题。真正的问题是当 feature 为 true 时，Bun 需要把 `require('../daemon/workerRegistry.js')` 打进产物 -- 这要求文件存在。如果 DAEMON 在构建 features 列表里，一切正常；如果不在，那 `require()` 所在的分支因为 `!feature()` 为 `false` 会被 DCE 删掉。
+
+关键区别在于：**`if (feature('X'))` 包裹的 `require()` 路径在 `X=false` 时被 DCE 删除**，所以文件可以不存在。但 **`if (!feature('X'))` 包裹的 `require()` 路径在 `X=true` 时必须存在**，因为 DCE 保留的是 `else` 分支。
+
+## 约束二：`if (false)` 必须在 parse 阶段可见，否则 bundler 会崩溃
+
+这是 Vite/Rollup 构建管线独有的约束。打开 `scripts/vite-plugin-feature-flags.ts:29`，你会看到注释：
+
+```ts
+/**
+ * Vite/Rollup plugin that replaces `feature('X')` calls with boolean literals
+ * at the transform stage, BEFORE the bundler resolves imports.
+ *
+ * This approach is necessary because some feature-gated code blocks contain
+ * require() calls to files that don't exist (e.g. hunter.js inside
+ * feature('REVIEW_ARTIFACT')). The bundler must see these as dead code
+ * (`if (false) { ... }`) before attempting import resolution.
+ */
+```
+
+打开 `src/skills/bundled/index.ts:44`，看这个致命的模式：
+
+```ts
+if (feature('REVIEW_ARTIFACT')) {
+  /* eslint-disable @typescript-eslint/no-require-imports */
+  const { registerHunterSkill } = require('./hunter.js')
+  /* eslint-enable @typescript-eslint/no-require-imports */
+  registerHunterSkill()
+}
+```
+
+文件 `src/skills/bundled/hunter.js` **不存在**。你可以在终端里验证：`ls src/skills/bundled/hunter.js` 返回 "No such file or directory"。代码库中完全找不到任何名为 `hunter*` 的文件。
+
+这在 `Bun.build()` 管线下不是问题 -- Bun 的打包器知道 `feature('REVIEW_ARTIFACT')` 返回 `false`（因为它不在 `DEFAULT_BUILD_FEATURES` 列表里，见 `scripts/defines.ts:72` 的注释），直接 DCE 掉整个 `if` 块，从来不会尝试解析 `./hunter.js`。
+
+但 Vite/Rollup 不同。Rollup 的处理管线是：resolve imports -> transform -> bundle。如果 Vite 在 transform 之前尝试 resolve imports，它会看到 `require('./hunter.js')` 然后 `MODULE_NOT_FOUND` 崩溃。
+
+这就是为什么 `vite-plugin-feature-flags.ts` 必须在 `transform` 阶段（而非 `load` 或 `resolveId` 阶段）替换 `feature('X')` 调用。打开 `scripts/vite-plugin-feature-flags.ts:54`，`transform` 函数用正则匹配替换：
+
+```ts
+transform(code, id) {
+  if (id.includes('node_modules')) return null
+  let transformed = code.replace(FEATURE_CALL_RE, (match, flagName) => {
+    return features.has(flagName) ? 'true' : 'false'
+  })
+  // ...
+}
+```
+
+替换发生在 `resolveId` 之后、bundle 之前。这样 Rollup 看到 `if (false) { require('./hunter.js') }` 就知道整个分支不可达，不会尝试解析 `./hunter.js`。
+
+插件还提供了一个虚拟模块解决 `import { feature } from 'bun:bundle'` 的 "module not found" 错误（`scripts/vite-plugin-feature-flags.ts:47`）：
+
+```ts
+load(id) {
+  if (id === resolvedVirtualModuleId) {
+    return 'export function feature(name) { return false; }'
+  }
+}
+```
+
+这个 stub 的 `return false` 在运行时永远不会被调用，因为所有 `feature()` 调用都在 `transform` 阶段被替换成了字面量。它存在的唯一意义是让 Rollup 不报 unresolved import 错误。
+
+**反事实推演**：如果 `transform` 替换不够早，Vite 构建管线在遇到任何引用不存在文件的 feature-gated `require()` 时都会崩溃。这意味着所有被注释掉的 feature（`CONTEXT_COLLAPSE`、`UDS_INBOX`、`REVIEW_ARTIFACT` 等）在 Vite 管线下都是"定时炸弹" -- 只要它们的代码块里有 `require()` 指向不存在的文件，替换时机不对就会炸。
+
+## 约束三：Vite 的 `using` 声明必须 transpile，否则 Node.js 崩溃
+
+`vite-plugin-feature-flags.ts` 在 feature flag 替换之外还承担了一项额外职责。打开 `scripts/vite-plugin-feature-flags.ts:68`：
+
+```ts
+// 2. Transpile `using _ = expr;` to `const _ = expr;` for Node.js compat.
+//    Node.js v22 does not support `using` declarations (Explicit Resource Management).
+//    Safe because: SLOW_OPERATION_LOGGING is not enabled, so slowLogging returns
+//    a no-op disposable whose [Symbol.dispose]() is empty.
+if (transformed.includes('using _')) {
+  transformed = transformed.replace(/\busing\s+(_\w*)\s*=/g, 'const $1 =')
+  modified = true
+}
+```
+
+这段正则把所有 `using _x = expr` 替换成 `const _x = expr`。注释解释了安全性前提：`SLOW_OPERATION_LOGGING` 未启用时，`slowLogging` 返回的 disposable 的 `[Symbol.dispose]()` 是空操作，所以 `using` 和 `const` 行为等价。
+
+但这里有一条脆弱的依赖链：如果有人启用了 `SLOW_OPERATION_LOGGING` 并在 Vite 构建产物上用 Node.js 运行，资源清理就不会执行 -- `using` 的 `Symbol.dispose` 语义被丢弃了。
+
+**反事实推演**：如果不做这个 transpile，Vite 构建的产物在 Node.js v22 上会直接 `SyntaxError: Unexpected token 'using'`。这意味着整个 "产物兼容 bun/node" 的承诺（`build.ts` 的 post-build `import.meta.require` 补丁）在 Vite 管线上多了一个前提条件。
+
+## 三层切换机制：Build 默认、Dev 全开、运行时环境变量
+
+打开 `scripts/defines.ts:39`，你会看到 `DEFAULT_BUILD_FEATURES` 列表，65+ 个 feature flag 中大约有 40 个默认启用，其余被注释掉。打开 `scripts/dev.ts:39`，dev 模式使用同一个列表：
+
+```ts
+const allFeatures = [...new Set([...DEFAULT_BUILD_FEATURES, ...envFeatures])]
+const featureArgs = allFeatures.flatMap(name => ['--feature', name])
+```
+
+但 dev 模式可以通过 `FEATURE_<NAME>=1` 环境变量额外启用。例如 `FEATURE_REVIEW_ARTIFACT=1 bun run dev` 会尝试启用 `REVIEW_ARTIFACT`，然后代码会尝试 `require('./hunter.js')`，由于文件不存在而崩溃。
+
+三层机制的行为差异：
+
+| 层级 | 何时生效 | feature() 的值 | DCE 是否生效 |
+|------|----------|---------------|-------------|
+| `Bun.build()` | 构建时 | 编译期常量 | 是 -- 不可达代码被删除 |
+| `vite build` | 构建时（通过 transform 插件） | transform 后的字面量 | 是 -- Rollup 删除不可达分支 |
+| `bun run dev` | 运行时（通过 `--feature` flag） | 运行时布尔值 | 否 -- 所有分支都在内存中 |
+
+这意味着 dev 模式下所有 feature-gated 的 `require()` 路径都必须实际存在，否则运行时会崩溃。对 Bun 原生 dev 来说 `--feature` flag 是 Bun 运行时提供的；对 Vite dev 来说 `feature()` 被 transform 插件替换为字面量，运行时不存在 `bun:bundle` 模块。
+
+## 反编译产物的 stub 陷阱：两类禁用，一个混淆
+
+`DEFAULT_BUILD_FEATURES` 中被注释掉的 feature 可以分为两类。打开 `scripts/defines.ts:62-72`，看注释中的措辞差异：
+
+**第一类：反编译丢失导致的空壳 stub**：
+
+```ts
+// 'CONTEXT_COLLAPSE', // 已禁用：实现是空壳 stub，启用后会抑制 auto compact 导致上下文管理完全失效
+// 'HISTORY_SNIP',     // 已禁用：snip 功能暂时关闭
+```
+
+这些 feature 在原始 Claude Code 中是完整功能，反编译过程中逻辑丢失，留下的实现要么是空壳（`CONTEXT_COLLAPSE`），要么会破坏核心功能（`HISTORY_SNIP` 启用后 `SnipTool` 出现但上下文管理不正常）。启用它们不是"多了一个功能"，而是"引入了一个损坏的功能"。
+
+**第二类：功能原本就 stubbed 或已废弃**：
+
+```ts
+// 'SKILL_LEARNING',  // 已禁用
+// 'TEAMMEM',         // 已禁用：依赖 COORDINATOR_MODE，邮箱文件无限增长
+// 'REVIEW_ARTIFACT', // 已禁用：代码审查产物（API 请求无响应，待排查 schema 兼容性）
+```
+
+`SKILL_LEARNING` 和 `TEAMMEM` 在原始版本中也是 stubbed 或内部工具，并非完整的对外功能。`REVIEW_ARTIFACT` 更有趣 -- 它的 `hunter.js` 根本不存在于反编译产物中，说明要么原始代码中也是动态加载的（但反编译时丢失了），要么是整个 hunter 子系统在某个版本中被删除但 feature gate 的引用没清理干净。
+
+打开 `src/tools.ts:148`，`ReviewArtifactTool` 的条件加载用的是标准的三元模式：
+
+```ts
+const ReviewArtifactTool = feature('REVIEW_ARTIFACT')
+  ? require('@claude-code-best/builtin-tools/tools/ReviewArtifactTool/ReviewArtifactTool.js')
+      .ReviewArtifactTool
+  : null
+```
+
+打开 `packages/builtin-tools/src/tools/ReviewArtifactTool/` 验证一下 -- 这个目录是存在的，工具实现也完整。但 `hunter.js`（注册 hunter skill 的模块）不存在。这意味着 `REVIEW_ARTIFACT` 是"工具存在但 skill 不存在"的半死状态。
+
+**如果不区分这两类**，有人可能觉得"注释掉的 feature 只要改一行配置就能启用"。对第二类也许可以，但对第一类，启用 `CONTEXT_COLLAPSE` 会让 auto compact 失效、启用 `UDS_INBOX` 会让 Node.js 构建卡住（`scripts/defines.ts:68` 的注释明确说了）。
+
+## `const x = feature()` 为什么到处存在
+
+CLAUDE.md 说 "不能赋值给变量"，但你打开 `src/main.tsx:119` 就能看到违反这条规则的代码：
+
+```ts
+const coordinatorModeModule = feature('COORDINATOR_MODE')
+  ? (require('./coordinator/coordinatorMode.js') as typeof import('./coordinator/coordinatorMode.js'))
+  : null;
+```
+
+这不矛盾。CLAUDE.md 说的"不能赋值给变量"指的是你不能把 `feature()` 的返回值单独赋给变量然后在 `if` 里用那个变量。但 `feature() ? a : null` 是三元表达式 -- `feature()` 在条件位置。Bun 编译器的 DCE 看到的是 `feature('X')` 这个 AST 节点在三元条件的根，它知道可以替换。
+
+同样的模式在 `src/tools.ts:140-158` 中大量出现：
+
+```ts
+const SnipTool = feature('HISTORY_SNIP')
+  ? require('@claude-code-best/builtin-tools/tools/SnipTool/SnipTool.js').SnipTool
+  : null
+const ReviewArtifactTool = feature('REVIEW_ARTIFACT')
+  ? require('@claude-code-best/builtin-tools/tools/ReviewArtifactTool/ReviewArtifactTool.js').ReviewArtifactTool
+  : null
+```
+
+这是 "feature gate + 条件 require + null fallback" 三合一模式。如果 `feature()` 在条件位置，DCE 生效，`require()` 路径在 false 时不会被解析。如果写成 `const enabled = feature('X'); const tool = enabled ? require(...) : null;`，第二行的 require 不在 `feature()` 的 AST 子树里，DCE 无法保证它在 false 时被消除。
+
+打开 `src/main.tsx:703`，看一个更微妙的三元用法：
+
+```ts
+const _pendingConnect: PendingConnect | undefined = feature('DIRECT_CONNECT')
+  ? {
+      url: undefined,
+      authToken: undefined,
+      dangerouslySkipPermissions: false,
+    }
+  : undefined;
+```
+
+这里不是 require，而是一个对象字面量。`feature('DIRECT_CONNECT')` 在三元条件位置，DCE 可以把 false 分支（对象字面量）消除。如果不这么做，`PendingConnect` 类型可能引用的内部模块会被全量引入。
+
+## feature 字符串本身的 DCE
+
+还有一个容易被忽略的 DCE 细节。打开 `src/components/TokenWarning.tsx:87`：
+
+```ts
+// Each feature() block stands alone so the flag strings DCE from
+// external builds independently.
+if (feature('REACTIVE_COMPACT')) {
+  if (getFeatureValue_CACHED_MAY_BE_STALE('tengu_cobalt_raccoon', false)) {
+    reactiveOnlyMode = true;
+  }
+}
+if (feature('CONTEXT_COLLAPSE')) {
+  const { isContextCollapseEnabled } =
+    require('../services/contextCollapse/index.js');
+  // ...
+}
+```
+
+注释说 "each feature() block stands alone"。为什么不合并成一个 `if (feature('A') || feature('B'))` 块？因为合并后，即使 `A` 和 `B` 都为 false，`else` 分支中的 feature flag 字符串 `'REACTIVE_COMPACT'` 和 `'CONTEXT_COLLAPSE'` 可能不会从产物中消除。独立的 `if` 块让每个 flag 字符串在自己的 DCE 作用域里 -- `feature('X')` 替换为 `false` 后，整个 `if (false) { ... }` 块包括其中的字符串字面量都会被删除。
+
+这对内部工具来说很重要：feature flag 的名称（如 `CONTEXT_COLLAPSE`）本身可能泄露内部项目代号或功能名称。独立 DCE 确保外部构建的产物里找不到任何被注释掉的 feature 名称。
+
+## 延伸阅读
+
+- 想看 feature flag 如何与代码分割交互（为什么 600+ chunks 中的某些 chunks 只在特定 feature 启用时加载），见 [第一章：Code Splitting 不是优化，是生存需求](./01-code-splitting.md)
+- 想看入口函数如何用 feature gate 实现零模块加载的快速路径，见 [第二章：入口的 Fast-Path 优先级链](./02-fast-path.md)
+- 想看工具系统如何用 feature gate 实现延迟加载与白名单过滤，见 [第六章：工具系统的延迟加载与 CORE_TOOLS 白名单](./06-tools-deferred.md)
+- 想看 biome.json 关闭 42 条规则背后的反编译痕迹，见 [第十五章：biome.json 的 42 条规则关闭](./15-biome-42-rules.md)

docs/outline-output/design/06-tools-deferred.md

@@ -0,0 +1,414 @@
+# 第六章：工具系统的延迟加载与 CORE_TOOLS 白名单
+
+> 60 个工具不塞进同一条 prompt，按需搜索才能活下来。
+
+## 为什么工具不能一股脑全塞给模型
+
+Claude Code 有 62 个工具目录（打开 `/Users/konghayao/code/ai/claude-code/packages/builtin-tools/src/tools/` 你能数到），但每次 API 请求不可能把它们全部放进 `tools` 数组。原因很直接：每个工具的 JSON Schema 定义都要消耗 token。一个 MCP server 提供 20 个工具，每个工具的 `input_schema` 加起来可能吃掉几千 token。如果用户同时接入了 5 个 MCP server，光是工具描述就能占掉 context window 的 10% 以上。
+
+这不是理论推测——代码里有一个自动检测机制。打开 `src/utils/searchExtraTools.ts:45`，你会看到：
+
+```typescript
+const DEFAULT_AUTO_SEARCH_EXTRA_TOOLS_PERCENTAGE = 10 // 10%
+```
+
+当延迟工具的 schema 总量超过 context window 的 10%，系统自动启用延迟加载。`checkAutoThreshold` 函数（同文件 `:676`）会先用精确的 token 计数 API 衡量延迟工具总量，API 不可用时回退到字符数启发式（每 token 约 2.5 字符，同文件 `:95`）。
+
+如果不做延迟加载，每次请求都携带全部工具 schema，后果是：prompt cache 频繁失效（工具列表一变，缓存键全部作废），模型在几十个工具中注意力稀释，token 账单膨胀。延迟加载让 tools 数组保持稳定——只有核心工具在里面，新工具按需发现。
+
+## CORE_TOOLS：38 个"永远在线"的核心工具
+
+`CORE_TOOLS` 定义在 `src/constants/tools.ts:137`。打开那个文件，你会看到一个 `Set<string>`，注释写得很清楚：
+
+```typescript
+/**
+ * Core tools that are always loaded with full schema at initialization.
+ * These tools are never deferred — they appear in the initial prompt.
+ * All other tools (non-core built-in + all MCP tools) are deferred
+ * and must be discovered via SearchExtraToolsTool / ExecuteExtraTool.
+ */
+export const CORE_TOOLS = new Set([
+  // File operations
+  ...SHELL_TOOL_NAMES, // 'Bash', 'Shell'
+  FILE_READ_TOOL_NAME, // 'Read'
+  FILE_EDIT_TOOL_NAME, // 'Edit'
+  FILE_WRITE_TOOL_NAME, // 'Write'
+  GLOB_TOOL_NAME, // 'Glob'
+  GREP_TOOL_NAME, // 'Grep'
+  NOTEBOOK_EDIT_TOOL_NAME, // 'NotebookEdit'
+  // Agent & interaction
+  AGENT_TOOL_NAME, // 'Agent'
+  ASK_USER_QUESTION_TOOL_NAME, // 'AskUserQuestion'
+  // Task management
+  TASK_OUTPUT_TOOL_NAME, TASK_STOP_TOOL_NAME,
+  TASK_CREATE_TOOL_NAME, TASK_GET_TOOL_NAME,
+  TASK_LIST_TOOL_NAME, TASK_UPDATE_TOOL_NAME,
+  TODO_WRITE_TOOL_NAME, // 'TodoWrite'
+  // Planning
+  ENTER_PLAN_MODE_TOOL_NAME, EXIT_PLAN_MODE_V2_TOOL_NAME,
+  VERIFY_PLAN_EXECUTION_TOOL_NAME,
+  // Web
+  WEB_FETCH_TOOL_NAME, WEB_SEARCH_TOOL_NAME,
+  // Code intelligence
+  LSP_TOOL_NAME,
+  // Skills
+  SKILL_TOOL_NAME,
+  // Workflow orchestration
+  WORKFLOW_TOOL_NAME,
+  // Scheduling & monitoring
+  SLEEP_TOOL_NAME,
+  // Tool discovery (always loaded)
+  SEARCH_EXTRA_TOOLS_TOOL_NAME, EXECUTE_TOOL_NAME,
+  SYNTHETIC_OUTPUT_TOOL_NAME,
+])
+```
+
+这个白名单的设计哲学是：模型完成日常编程任务所需的最小工具集。文件读写编辑搜索、shell 执行、agent 派发、任务管理、计划模式、web 获取、skill 调用——这些是"95% 的对话只需要这些"的工具。
+
+注意最后三个：`SearchExtraTools`、`ExecuteExtraTool`、`SyntheticOutput`。它们本身是延迟加载机制的入口，所以必须放在核心集里，否则模型就无法发现和使用任何延迟工具——一个自举悖论。
+
+### 反事实推演：如果把所有工具都放进 CORE_TOOLS
+
+假设 `CORE_TOOLS` 包含全部 62 个工具。最直接的后果是每次 API 请求的 `tools` 数组体积翻倍甚至翻三倍。对 prompt cache 的影响是致命的：prompt cache 依赖 tools 列表的稳定性。`claude.ts:393` 的 `assembleToolPool` 注释里明确提到：
+
+> The server's claude_code_system_cache_policy places a global cache breakpoint after the last prefix-matched built-in tool; a flat sort would interleave MCP tools into built-ins and invalidate all downstream cache keys whenever an MCP tool sorts between existing built-ins.
+
+如果所有 MCP 工具都在核心集里，任何一次 MCP server 的连接/断开都会让下游所有缓存键失效。延迟加载把 MCP 工具完全排除在初始 tools 数组之外（`claude.ts:1188-1200`），保持了缓存稳定性。
+
+## isDeferredTool 的判定逻辑
+
+`isDeferredTool` 定义在 `packages/builtin-tools/src/tools/SearchExtraToolsTool/prompt.ts:69`。逻辑出奇地简单：
+
+```typescript
+export function isDeferredTool(tool: Tool): boolean {
+  // Explicit opt-out via _meta['anthropic/alwaysLoad']
+  if (tool.alwaysLoad === true) return false
+
+  // Core tools are always loaded — never deferred
+  if (CORE_TOOLS.has(tool.name)) return false
+
+  // Everything else (non-core built-in + all MCP tools) is deferred
+  return true
+}
+```
+
+三条规则，没有灰色地带。要么你在 `CORE_TOOLS` 里，要么你设置了 `alwaysLoad: true`（一种 opt-out 机制，给需要特殊处理的工具留了口子），否则你就是延迟工具。所有 MCP 工具天然是延迟工具——MCP 工具的 `name` 以 `mcp__` 开头，永远不会出现在 `CORE_TOOLS` 里。
+
+这个函数在 `claude.ts:1160-1166` 被调用时有一个性能注释：
+
+```typescript
+// Precompute once — isDeferredTool does 2 GrowthBook lookups per call
+const deferredToolNames = new Set<string>()
+if (useSearchExtraTools) {
+  for (const t of tools) {
+    if (isDeferredTool(t)) deferredToolNames.add(t.name)
+  }
+}
+```
+
+每次 `isDeferredTool` 调用内部会触发 GrowthBook（feature flag 平台）的远程配置查询，所以对整个工具列表遍历时必须预计算一次，缓存到 Set 里。这是反编译产物的一个典型痕迹——原版 Anthropic 代码依赖的 GrowthBook 实例在这个 fork 里被替换为空实现，但查询调用的结构保留了下来。
+
+## SearchExtraToolsTool：两步发现协议
+
+延迟工具的发现不是一次性完成的——它是一个两步协议，写死在 `SearchExtraToolsTool` 的 prompt 里（`prompt.ts:26-60`）。
+
+第一步：模型调用 `SearchExtraTools`，传入查询字符串。系统搜索延迟工具池，返回匹配的工具名列表。
+
+第二步：模型调用 `ExecuteExtraTool`，传入目标工具名和参数。系统从全局工具注册表中找到该工具，直接执行。
+
+打开 `packages/builtin-tools/src/tools/SearchExtraToolsTool/SearchExtraToolsTool.ts:380`，你会看到第一步中 `select:` 前缀的处理：
+
+```typescript
+const selectMatch = query.match(/^select:(.+)$/i)
+if (selectMatch) {
+  const requested = selectMatch[1]!
+    .split(',')
+    .map(s => s.trim())
+    .filter(Boolean)
+
+  const found: string[] = []
+  const alreadyLoaded: string[] = []
+  const missing: string[] = []
+  for (const toolName of requested) {
+    const deferredMatch = findToolByName(deferredTools, toolName)
+    const fullMatch = deferredMatch ?? findToolByName(tools, toolName)
+    if (fullMatch) {
+      if (!found.includes(fullMatch.name)) {
+        found.push(fullMatch.name)
+        if (!deferredMatch) {
+          alreadyLoaded.push(fullMatch.name)
+        }
+      }
+    } else {
+      missing.push(toolName)
+    }
+  }
+```
+
+一个值得注意的细节：如果模型尝试 `select:` 一个已经是核心工具的名字，系统不会报错，而是把它放进 `alreadyLoaded` 列表返回。`mapToolResultToToolResultBlockParam` 方法（同文件 `:542`）会明确告诉模型：
+
+```
+Already loaded as core tool(s): Read. Call these directly using your normal tool interface — do NOT use ExecuteExtraTool for them.
+```
+
+这不是防御性编程的冗余——它防止了模型在压缩（compact）后丢失上下文时，对已知工具发起无意义的搜索-执行循环。反编译产物中这种"防止模型犯蠢"的引导文本随处可见，说明原版代码在生产环境中确实遇到了模型行为退化的问题。
+
+### 查询语法：四种子模式
+
+`SearchExtraToolsTool` 支持四种查询格式，定义在 `prompt.ts:53-56`：
+
+- `"select:CronCreate"` — 精确选择，支持逗号分隔多选
+- `"select:CronCreate,CronList"` — 多工具一次发现
+- `"discover:schedule cron job"` — 纯发现模式，返回工具名 + 描述 + schema，不触发加载
+- `"notebook jupyter"` — 关键词搜索，TF-IDF 语义匹配
+- `"+slack send"` — 前缀 `+` 表示必须包含的词，类似搜索引擎的强制匹配
+
+`discover:` 模式的设计意图很巧妙：模型可以先了解一个延迟工具的 schema 结构，再决定是否执行。打开 `SearchExtraToolsTool.ts:444`，discover 分支会返回 TF-IDF 搜索结果，包含每个工具的名字、描述和完整 JSON Schema——模型读完这些信息后再构建正确的参数调用 `ExecuteExtraTool`。
+
+## TF-IDF 索引：复用 skill 搜索的算法引擎
+
+工具搜索和 skill 搜索共享同一套 TF-IDF 算法。打开 `src/services/searchExtraTools/toolIndex.ts:1`，导入语句直接指向 skill 搜索模块：
+
+```typescript
+import {
+  tokenizeAndStem,
+  computeWeightedTf,
+  computeIdf,
+  cosineSimilarity,
+} from '../skillSearch/localSearch.js'
+```
+
+这不是代码复用——这是两个子系统在同一算法上的独立实例化。`toolIndex.ts` 的 `buildToolIndex` 函数（`:80`）对每个延迟工具提取三组 token：工具名（权重 3.0）、searchHint（权重 2.5）、描述文本（权重 1.0），然后用 TF-IDF 计算向量：
+
+```typescript
+const TOOL_FIELD_WEIGHT = {
+  name: 3.0,
+  searchHint: 2.5,
+  description: 1.0,
+} as const
+```
+
+工具名权重最高是合理的——模型通常知道它要找什么工具（比如 "CronCreate"），问题在于工具名不在核心集里。searchHint 是工具开发者手写的简短能力描述，信号密度比完整描述高得多，所以权重也高于 description。
+
+### 为什么 skill prefetch 和 tool prefetch 用独立的去重集合
+
+打开 `src/services/searchExtraTools/prefetch.ts:24`：
+
+```typescript
+const discoveredToolsThisSession = new Set<string>()
+```
+
+这个 Set 跟踪当前会话中已经发现的延迟工具，防止重复推荐。它有容量上限（`SESSION_TRACKING_MAX = 500`，超过后裁剪到 `SESSION_TRACKING_TRIM_TO = 400`，同文件 `:22-23`），防止长会话内存泄漏。
+
+CLAUDE.md 里明确指出这个 Set 与 skill prefetch 的去重集合互不影响。为什么？因为两个子系统的生命周期和业务语义不同。工具发现是 per-turn 的——模型每次调用 `SearchExtraTools` 都应该能看到全量延迟工具池，只是已经发现的不会重复推荐。Skill 发现是 per-session 的——一个 skill 一旦推荐过，整会话内都不应该再弹。如果共用一个 Set，工具发现可能会意外吞掉 skill 推荐，或者反过来。两个 Set 各管各的，互不干扰。
+
+### CJK 大字符集的特殊处理
+
+`toolIndex.ts:182-188` 有一个针对中日韩文字的特殊处理：
+
+```typescript
+if (queryCjkTokens.length > 0 && score > 0) {
+  const matchingCjk = queryCjkTokens.filter(t => entry.tfVector.has(t))
+  if (matchingCjk.length < CJK_MIN_BIGRAM_MATCHES) {
+    const hasAsciiMatch = queryAsciiTokens.some(t => entry.tfVector.has(t))
+    if (!hasAsciiMatch) score = 0
+  }
+}
+```
+
+CJK 文字的特征是单字匹配噪音极大（一个 "发" 字可能匹配到 "开发"、"发现"、"发明" 等完全不同的概念），所以要求至少 2 个 CJK token 同时匹配（`CJK_MIN_BIGRAM_MATCHES = 2`）才认可搜索结果。这是一个从生产经验中总结出来的启发式——纯粹基于拉丁文字设计的 TF-IDF 算法在 CJK 环境下会产生大量误匹配。
+
+## claude.ts 的过滤点：延迟工具如何被排除在 API 请求之外
+
+实际的延迟加载执行点在 `src/services/api/claude.ts:1188-1205`：
+
+```typescript
+if (useSearchExtraTools) {
+  // Never include deferred tools in the API tools array — they are invoked
+  // via ExecuteExtraTool which looks them up from the global tool registry
+  // at runtime. Keeping the tools array stable preserves the prompt cache
+  // across turns (discovered tools no longer bloat the tools JSON).
+  filteredTools = tools.filter(tool => {
+    // Always include non-deferred tools (core tools)
+    if (!deferredToolNames.has(tool.name)) return true
+    // Always include SearchExtraToolsTool (so it can discover more tools)
+    if (toolMatchesName(tool, SEARCH_EXTRA_TOOLS_TOOL_NAME)) return true
+    // All other deferred tools are excluded — use ExecuteExtraTool instead
+    return false
+  })
+} else {
+  filteredTools = tools.filter(
+    t => !toolMatchesName(t, SEARCH_EXTRA_TOOLS_TOOL_NAME),
+  )
+}
+```
+
+这段代码揭示了延迟加载的核心权衡：延迟工具的 schema 完全不发送给模型，模型只能通过 `SearchExtraTools` 获取工具名，通过 `ExecuteExtraTool` 间接调用。这意味着模型在第一次使用某个延迟工具时，没有该工具的参数 schema 作为参考——它必须依赖 `SearchExtraTools` 返回的文本描述来猜测参数结构。
+
+这就是为什么 `discover:` 查询模式存在：它让模型在执行前先看 schema。也是为什么 `SearchExtraToolsTool.ts:542-600` 的 `mapToolResultToToolResultBlockParam` 方法会返回结构化的引导文本，而不是让模型自由发挥。
+
+## feature-gated 工具：另一种"延迟"
+
+延迟加载和 feature flag 是两个独立的机制，但它们在 `tools.ts` 中产生了有趣的交汇。打开 `src/tools.ts:16-60`，你会看到大量这样的模式：
+
+```typescript
+const SleepTool =
+  feature('PROACTIVE') || feature('KAIROS')
+    ? require('@claude-code-best/builtin-tools/tools/SleepTool/SleepTool.js')
+        .SleepTool
+    : null
+
+const RemoteTriggerTool = feature('AGENT_TRIGGERS_REMOTE')
+  ? require('@claude-code-best/builtin-tools/tools/RemoteTriggerTool/RemoteTriggerTool.js')
+      .RemoteTriggerTool
+  : null
+```
+
+这是 feature flag 的条件导入模式：`feature('X')` 为真时 require 模块，否则为 null。在 `getAllBaseTools()`（同文件 `:217`）中，这些 null 值通过展开运算符被过滤掉：
+
+```typescript
+...(SleepTool ? [SleepTool] : []),
+...(RemoteTriggerTool ? [RemoteTriggerTool] : []),
+```
+
+注意这里用了 `require()` 而不是 ESM `import`。原因是 `feature()` 只能在 `if` 条件中直接使用（Bun 编译器的 DCE 限制，详见第五章），而 ESM import 是静态的，无法放在条件分支里。`require()` 是动态的，可以被条件包裹。这种反编译产物特有的模式在整个 `tools.ts` 中反复出现——原始代码可能用了其他方式实现条件加载，但反编译后只能还原为 `require()` + null 检查。
+
+### 如果不用 require() 而用静态 import
+
+假设把所有工具改为顶层静态 import：
+
+```typescript
+import { SleepTool } from '@claude-code-best/builtin-tools/tools/SleepTool/SleepTool.js'
+import { RemoteTriggerTool } from '@claude-code-best/builtin-tools/tools/RemoteTriggerTool/RemoteTriggerTool.js'
+```
+
+即使 `feature()` 返回 false，这些模块仍然会被加载和初始化。对于大部分工具来说这不是问题，但某些工具在 import 时就会执行副作用（比如注册全局事件监听器或读取环境变量）。`require()` + null 检查确保了 feature 关闭时这些模块的代码完全不会执行。
+
+此外，Bun 的 DCE（Dead Code Elimination）依赖 `feature()` 在 AST 层面被识别。静态 import 无法被 DCE 裁剪，意味着所有工具代码都会打包进产物——即使永远不会被调用。对于目标是按需加载 600+ chunk 的项目来说，这是不可接受的。
+
+## SyntheticOutputTool：延迟加载体系中的特殊角色
+
+`SyntheticOutputTool`（`packages/builtin-tools/src/tools/SyntheticOutputTool/SyntheticOutputTool.ts`）是一个看起来很奇怪的工具。它的名字叫 "StructuredOutput"，功能是"接受任意 JSON 输入并原样返回"。
+
+打开 `SyntheticOutputTool.ts:28`：
+
+```typescript
+export const SyntheticOutputTool = buildTool({
+  isMcp: false,
+  isEnabled() {
+    return true
+  },
+  isReadOnly() {
+    return true
+  },
+  name: SYNTHETIC_OUTPUT_TOOL_NAME,
+  searchHint: 'return the final response as structured JSON',
+  async call(input) {
+    return {
+      data: 'Structured output provided successfully',
+      structured_output: input,
+    }
+  },
+})
+```
+
+它之所以在 `CORE_TOOLS` 中，是因为它服务于非交互式场景（pipe mode、SDK 调用）。当外部调用者通过 `agent({schema: ...})` 传入一个 JSON schema 时，系统会用 `createSyntheticOutputTool`（同文件 `:116`）创建一个带有 Ajv 验证的版本：
+
+```typescript
+export function createSyntheticOutputTool(
+  jsonSchema: Record<string, unknown>,
+): CreateResult {
+  const cached = toolCache.get(jsonSchema)
+  if (cached) return cached
+
+  const result = buildSyntheticOutputTool(jsonSchema)
+  toolCache.set(jsonSchema, result)
+  return result
+}
+```
+
+注意这里的 `WeakMap` 缓存（同文件 `:109`）——同一个 schema 对象的重复创建会被跳过。注释说明了原因：Workflow 脚本在一次运行中可能调用 `agent({schema: ...})` 30-80 次，没有缓存的话每次都要做 `new Ajv() + validateSchema() + compile()`（约 1.4ms 的 JIT 编译），80 次调用就是 ~110ms 的 Ajv 开销；有缓存后降到 ~4ms。
+
+这个工具在延迟加载体系中的角色是：它是唯一一个在核心集中但"按需配置"的工具。其他核心工具的 schema 是固定的，`SyntheticOutputTool` 的 schema 可以动态注入。
+
+## 三种工具搜索模式的切换
+
+`src/utils/searchExtraTools.ts:159-192` 定义了三种工具搜索模式：
+
+| 模式 | 触发条件 | 行为 |
+|------|----------|------|
+| `tst` | `ENABLE_SEARCH_EXTRA_TOOLS=true` 或默认 | 始终延迟加载非核心工具 |
+| `tst-auto` | `ENABLE_SEARCH_EXTRA_TOOLS=auto` 或 `auto:N` | 当延迟工具 schema 超过 context window N% 时才启用 |
+| `standard` | `ENABLE_SEARCH_EXTRA_TOOLS=false` | 不延迟加载，所有工具直接暴露 |
+
+默认行为是 `tst`——始终延迟加载。这意味着即使只有 2 个延迟工具，它们的 schema 也不会出现在初始请求中。`tst-auto` 模式给了用户一个折中选择：延迟工具少的时候全量加载（省去 SearchExtraTools 的额外一轮调用），多了才启用延迟。
+
+`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` 环境变量仍然作为延迟加载的终极开关——即使 `ENABLE_SEARCH_EXTRA_TOOLS` 未设置，只要这个变量为 true，就强制进入 `standard` 模式。这是历史遗留：早期版本依赖 Anthropic API 的 `tool_reference` beta header 实现延迟加载，禁用 beta 就等于禁用延迟。现在 beta header 已经移除（统一使用自建的 TF-IDF + keyword 搜索），但这个开关被保留了下来。
+
+## prefetch：提前预测模型需要什么工具
+
+`prefetch.ts` 实现了一个"预取"机制：在模型的 assistant turn 开始之前，系统就会根据消息历史预测模型可能需要哪些延迟工具。
+
+打开 `src/services/searchExtraTools/prefetch.ts:94`：
+
+```typescript
+export async function startSearchExtraToolsPrefetch(
+  tools: Tools,
+  messages: Message[],
+): Promise<Attachment[]> {
+  const startedAt = Date.now()
+  const queryText = extractQueryFromMessages(null, messages)
+  if (!queryText.trim()) return []
+
+  try {
+    const index = await getToolIndex(tools)
+    const results = searchTools(queryText, index, 3)
+
+    const newResults = results.filter(
+      r => !discoveredToolsThisSession.has(r.name),
+    )
+    if (newResults.length === 0) return []
+```
+
+注意 `extractQueryFromMessages`（从 `skillSearch/prefetch.ts` 导入的共享函数）从消息历史中提取查询文本，然后对延迟工具索引做搜索。预取结果最多返回 3 个匹配（`searchTools(queryText, index, 3)`），过滤掉已发现的工具，然后以 `tool_discovery` attachment 形式注入对话。
+
+这个预取机制有一个被有意禁用的功能——turn-zero 预取（同文件 `:138-146`）：
+
+```typescript
+export async function getTurnZeroSearchExtraToolsPrefetch(
+  _input: string,
+  _tools: Tools,
+): Promise<Attachment | null> {
+  // Disabled: turn-zero user-input tool recommendations caused frequent
+  // popups. Inter-turn discovery (startSearchExtraToolsPrefetch) is still
+  // active and provides non-intrusive suggestions during assistant turns.
+  return null
+}
+```
+
+注释很直白：用户输入第一条消息时就弹出工具推荐太烦了。这说明团队在"信息前置"和"用户打扰"之间做过权衡——预取可以保留在 assistant turn 之间（模型正在思考时悄悄准备），但不能在用户刚打字时就弹出来。
+
+## 工具池的排序与缓存稳定性
+
+`src/tools.ts:376-398` 的 `assembleToolPool` 函数有一个精心设计的排序策略：
+
+```typescript
+const byName = (a: Tool, b: Tool) => a.name.localeCompare(b.name)
+return uniqBy(
+  [...builtInTools].sort(byName).concat(allowedMcpTools.sort(byName)),
+  'name',
+)
+```
+
+内置工具排在前面，MCP 工具排在后面，各自按名称排序。`uniqBy` 保证同名工具以内置优先。注释解释了原因：
+
+> The server's claude_code_system_cache_policy places a global cache breakpoint after the last prefix-matched built-in tool; a flat sort would interleave MCP tools into built-ins and invalidate all downstream cache keys whenever an MCP tool sorts between existing built-ins.
+
+如果用一个扁平的全局排序，MCP 工具可能插在内置工具之间（比如 `mcp__github__create_issue` 排在 `FileEdit` 和 `FileRead` 之间）。每增加或删除一个 MCP 工具，所有排在它后面的工具的缓存键都会变。分区排序让内置工具的缓存完全不受 MCP 工具变动的影响。
+
+## 延伸阅读
+
+- 想看 feature flag 系统如何约束 `require()` 条件导入的写法，见 [第五章：Feature Flag 系统的三个硬约束](./05-feature-flags.md)
+- 想看 prompt cache 如何依赖工具列表的稳定性，见 [第七章：7-Provider 抽象层的单一调度点](./07-provider-dispatch.md)
+- 想看 skill prefetch 与 tool prefetch 共享 `extractQueryFromMessages` 的设计，见 [第十二章：ACP / Bridge / Daemon](./12-long-running-modes.md) 中的 ACP 权限管道段
+- 想看 `performanceShim` 如何在 JSC 内存约束下保护长会话的 tools 处理，见 [第三章：performanceShim](./03-performance-shim.md)