mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-15 21:05:51 +00:00
Compare commits
2 Commits
v1.2.0
...
version/i1
| Author | SHA1 | Date | |
|---|---|---|---|
|
0f6fe77eee | ||
|
|
a68e9637c0 |
@@ -1,17 +0,0 @@
|
||||
---
|
||||
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.
|
||||
@@ -1,12 +0,0 @@
|
||||
---
|
||||
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.
|
||||
@@ -1,325 +0,0 @@
|
||||
---
|
||||
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
|
||||
```
|
||||
|
||||
**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. 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)
|
||||
```
|
||||
|
||||
3. Give a brief text summary of what was covered, key insights, and areas for further study.
|
||||
|
||||
## 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
|
||||
@@ -1,235 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,11 +0,0 @@
|
||||
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
|
||||
0
.githooks/pre-commit
Normal file → Executable file
0
.githooks/pre-commit
Normal file → Executable file
5
.github/workflows/ci.yml
vendored
5
.github/workflows/ci.yml
vendored
@@ -8,7 +8,7 @@ on:
|
||||
|
||||
jobs:
|
||||
ci:
|
||||
runs-on: macos-latest
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
@@ -20,6 +20,9 @@ jobs:
|
||||
- name: Install dependencies
|
||||
run: bun install --frozen-lockfile
|
||||
|
||||
- name: Lint
|
||||
run: bun run lint
|
||||
|
||||
- name: Test
|
||||
run: bun test
|
||||
|
||||
|
||||
75
.github/workflows/release-rcs.yml
vendored
75
.github/workflows/release-rcs.yml
vendored
@@ -1,75 +0,0 @@
|
||||
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@v4
|
||||
|
||||
- name: Login to GHCR
|
||||
uses: docker/login-action@v3
|
||||
with:
|
||||
registry: ${{ env.REGISTRY }}
|
||||
username: ${{ github.actor }}
|
||||
password: ${{ secrets.GITHUB_TOKEN }}
|
||||
|
||||
- name: Set up Docker Buildx
|
||||
uses: docker/setup-buildx-action@v3
|
||||
|
||||
- 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@v5
|
||||
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
|
||||
31
.github/workflows/update-contributors.yml
vendored
31
.github/workflows/update-contributors.yml
vendored
@@ -1,31 +0,0 @@
|
||||
name: Update Contributors
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
schedule:
|
||||
- cron: '0 0 * * *' # 每天更新一次
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
jobs:
|
||||
update:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
token: ${{ secrets.GITHUB_TOKEN }}
|
||||
|
||||
- uses: jaywcjlove/github-action-contributors@main
|
||||
with:
|
||||
token: ${{ secrets.GITHUB_TOKEN }}
|
||||
output: "contributors.svg"
|
||||
repository: ${{ github.repository }}
|
||||
|
||||
- uses: stefanzweifel/git-auto-commit-action@v5
|
||||
with:
|
||||
commit_message: "docs: update contributors"
|
||||
file_pattern: "contributors.svg"
|
||||
branch: main
|
||||
27
.gitignore
vendored
27
.gitignore
vendored
@@ -8,24 +8,9 @@ coverage
|
||||
.vscode
|
||||
*.suo
|
||||
*.lock
|
||||
src/utils/vendor/
|
||||
|
||||
# AI tool runtime directories
|
||||
.agents/
|
||||
.codex/
|
||||
.omx/
|
||||
|
||||
# Binary / screenshot files (root only)
|
||||
/*.png
|
||||
*.bmp
|
||||
|
||||
# Agent / tool state dirs
|
||||
.swarm/
|
||||
.agents/__pycache__/
|
||||
|
||||
# Python bytecode
|
||||
__pycache__/
|
||||
*.pyc
|
||||
logs
|
||||
|
||||
data
|
||||
.gitignore
|
||||
*.code-workspace
|
||||
doc-prompt-eng.md
|
||||
claude.bat
|
||||
.claude
|
||||
chn_prompt_plan.md
|
||||
13
.vscode/launch.json
vendored
13
.vscode/launch.json
vendored
@@ -1,13 +0,0 @@
|
||||
{
|
||||
"version": "0.2.0",
|
||||
"configurations": [
|
||||
{
|
||||
"type": "bun",
|
||||
"request": "attach",
|
||||
"name": "Attach to Claude Code",
|
||||
"url": "ws://localhost:8888/2dc3gzl5xot",
|
||||
"stopOnEntry": false,
|
||||
"internalConsoleOptions": "neverOpen"
|
||||
}
|
||||
]
|
||||
}
|
||||
27
.vscode/tasks.json
vendored
27
.vscode/tasks.json
vendored
@@ -1,27 +0,0 @@
|
||||
{
|
||||
"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:.*"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
179
CLAUDE.md
179
CLAUDE.md
@@ -12,66 +12,36 @@ This is a **reverse-engineered / decompiled** version of Anthropic's official Cl
|
||||
# Install dependencies
|
||||
bun install
|
||||
|
||||
# Dev mode (runs cli.tsx with MACRO defines injected via -d flags)
|
||||
# Dev mode (direct execution via Bun)
|
||||
bun run dev
|
||||
|
||||
# Dev mode with debugger (set BUN_INSPECT=9229 to pick port)
|
||||
bun run dev:inspect
|
||||
# equivalent to: bun run src/entrypoints/cli.tsx
|
||||
|
||||
# Pipe mode
|
||||
echo "say hello" | bun run src/entrypoints/cli.tsx -p
|
||||
|
||||
# Build (code splitting, outputs dist/cli.js + ~450 chunk files)
|
||||
# Build (outputs dist/cli.js, ~25MB)
|
||||
bun run build
|
||||
|
||||
# Test
|
||||
bun test # run all tests
|
||||
bun test src/utils/__tests__/hash.test.ts # run single file
|
||||
bun test --coverage # with coverage report
|
||||
|
||||
# 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
|
||||
|
||||
# Docs dev server (Mintlify)
|
||||
bun run docs:dev
|
||||
```
|
||||
|
||||
详细的测试规范、覆盖状态和改进计划见 `docs/testing-spec.md`。
|
||||
No test runner is configured. No linter is configured.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Runtime & Build
|
||||
|
||||
- **Runtime**: Bun (not Node.js). All imports, builds, and execution use Bun APIs.
|
||||
- **Build**: `build.ts` 执行 `Bun.build()` with `splitting: true`，入口 `src/entrypoints/cli.tsx`，输出 `dist/cli.js` + chunk files。默认启用 `AGENT_TRIGGERS_REMOTE`、`CHICAGO_MCP`、`VOICE_MODE` feature。构建后自动替换 `import.meta.require` 为 Node.js 兼容版本（产物 bun/node 都可运行）。
|
||||
- **Dev mode**: `scripts/dev.ts` 通过 Bun `-d` flag 注入 `MACRO.*` defines，运行 `src/entrypoints/cli.tsx`。默认启用 `BUDDY`、`TRANSCRIPT_CLASSIFIER`、`BRIDGE_MODE`、`AGENT_TRIGGERS_REMOTE`、`CHICAGO_MCP`、`VOICE_MODE` 六个 feature。
|
||||
- **Build**: `bun build src/entrypoints/cli.tsx --outdir dist --target bun` — single-file bundle.
|
||||
- **Module system**: ESM (`"type": "module"`), TSX with `react-jsx` transform.
|
||||
- **Monorepo**: Bun workspaces — internal packages live in `packages/` resolved via `workspace:*`.
|
||||
- **Lint/Format**: Biome (`biome.json`)。`bun run lint` / `bun run lint:fix` / `bun run format`。
|
||||
- **Defines**: 集中管理在 `scripts/defines.ts`。当前版本 `2.1.888`。
|
||||
|
||||
### 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`
|
||||
- `--daemon-worker=<kind>` — feature-gated (DAEMON)
|
||||
- `remote-control` / `rc` / `bridge` — feature-gated (BRIDGE_MODE)
|
||||
- `daemon` — feature-gated (DAEMON)
|
||||
- `ps` / `logs` / `attach` / `kill` / `--bg` — feature-gated (BG_SESSIONS)
|
||||
- `--tmux` + `--worktree` 组合
|
||||
- 默认路径：加载 `main.tsx` 启动完整 CLI
|
||||
2. **`src/main.tsx`** (~4680 行) — Commander.js CLI definition。注册大量 subcommands：`mcp` (serve/add/remove/list...)、`server`、`ssh`、`open`、`auth`、`plugin`、`agents`、`auto-mode`、`doctor`、`update` 等。主 `.action()` 处理器负责权限、MCP、会话恢复、REPL/Headless 模式分发。
|
||||
3. **`src/entrypoints/init.ts`** — One-time initialization (telemetry, config, trust dialog)。
|
||||
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).
|
||||
|
||||
### Core Loop
|
||||
|
||||
@@ -89,37 +59,25 @@ bun run docs:dev
|
||||
|
||||
- **`src/Tool.ts`** — Tool interface definition (`Tool` type) and utilities (`findToolByName`, `toolMatchesName`).
|
||||
- **`src/tools.ts`** — Tool registry. Assembles the tool list; some tools are conditionally loaded via `feature()` flags or `process.env.USER_TYPE`.
|
||||
- **`src/tools/<ToolName>/`** — 61 个 tool 目录（如 BashTool, FileEditTool, GrepTool, AgentTool, WebFetchTool, LSPTool, MCPTool 等）。每个 tool 包含 `name`、`description`、`inputSchema`、`call()` 及可选的 React 渲染组件。
|
||||
- **`src/tools/shared/`** — Tool 共享工具函数。
|
||||
- **`src/tools/<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.
|
||||
|
||||
### UI Layer (Ink)
|
||||
|
||||
- **`src/ink.ts`** — Ink render wrapper with ThemeProvider injection.
|
||||
- **`src/ink/`** — Custom Ink framework (forked/internal): custom reconciler, hooks (`useInput`, `useTerminalSize`, `useSearchHighlight`), virtual list rendering.
|
||||
- **`src/components/`** — 大量 React 组件（170+ 项），渲染于终端 Ink 环境中。关键组件：
|
||||
- `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 等）
|
||||
- **`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.
|
||||
- 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).
|
||||
|
||||
### Bridge / Remote Control
|
||||
|
||||
- **`src/bridge/`** (~35 files) — Remote Control / Bridge 模式。feature-gated by `BRIDGE_MODE`。包含 bridge API、会话管理、JWT 认证、消息传输、权限回调等。Entry: `bridgeMain.ts`。
|
||||
- CLI 快速路径: `claude remote-control` / `claude rc` / `claude bridge`。
|
||||
|
||||
### Daemon Mode
|
||||
|
||||
- **`src/daemon/`** — Daemon 模式（长驻 supervisor）。feature-gated by `DAEMON`。包含 `main.ts`（entry）和 `workerRegistry.ts`（worker 管理）。
|
||||
- **`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).
|
||||
|
||||
### Context & System Prompt
|
||||
|
||||
@@ -128,91 +86,19 @@ bun run docs:dev
|
||||
|
||||
### Feature Flag System
|
||||
|
||||
Feature flags control which functionality is enabled at runtime:
|
||||
|
||||
- **在代码中使用**: 统一通过 `import { feature } from 'bun:bundle'` 导入，调用 `feature('FLAG_NAME')` 返回 `boolean`。**不要**在 `cli.tsx` 或其他文件里自己定义 `feature` 函数或覆盖这个 import。
|
||||
- **启用方式**: 通过环境变量 `FEATURE_<FLAG_NAME>=1`。例如 `FEATURE_BUDDY=1 bun run dev` 启用 BUDDY 功能。
|
||||
- **Dev 默认 features**: `BUDDY`、`TRANSCRIPT_CLASSIFIER`、`BRIDGE_MODE`、`AGENT_TRIGGERS_REMOTE`、`CHICAGO_MCP`、`VOICE_MODE`（见 `scripts/dev.ts`）。
|
||||
- **Build 默认 features**: `AGENT_TRIGGERS_REMOTE`、`CHICAGO_MCP`、`VOICE_MODE`（见 `build.ts`）。
|
||||
- **常见 flag**: `BUDDY`, `DAEMON`, `BRIDGE_MODE`, `BG_SESSIONS`, `PROACTIVE`, `KAIROS`, `VOICE_MODE`, `FORK_SUBAGENT`, `SSH_REMOTE`, `DIRECT_CONNECT`, `TEMPLATES`, `CHICAGO_MCP`, `BYOC_ENVIRONMENT_RUNNER`, `SELF_HOSTED_RUNNER`, `COORDINATOR_MODE`, `UDS_INBOX`, `LODESTONE`, `ABLATION_BASELINE` 等。
|
||||
- **类型声明**: `src/types/internal-modules.d.ts` 中声明了 `bun:bundle` 模块的 `feature` 函数签名。
|
||||
|
||||
**新增功能的正确做法**: 保留 `import { feature } from 'bun:bundle'` + `feature('FLAG_NAME')` 的标准模式，在运行时通过环境变量或配置控制，不要绕过 feature flag 直接 import。
|
||||
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.
|
||||
|
||||
### Stubbed/Deleted Modules
|
||||
|
||||
| Module | Status |
|
||||
|--------|--------|
|
||||
| Computer Use (`@ant/*`) | Restored — `computer-use-swift`, `computer-use-input`, `computer-use-mcp`, `claude-for-chrome-mcp` 均有完整实现，macOS + Windows 可用，Linux 后端待完成 |
|
||||
| `*-napi` packages | `audio-capture-napi`、`image-processor-napi` 已恢复实现；`color-diff-napi` 完整实现；`url-handler-napi`、`modifiers-napi` 仍为 stub |
|
||||
| Voice Mode | Restored — `src/voice/`、`src/hooks/useVoiceIntegration.tsx`、`src/services/voiceStreamSTT.ts` 等，Push-to-Talk 语音输入（需 Anthropic OAuth） |
|
||||
| OpenAI 兼容层 | Restored — `src/services/api/openai/`，支持 Ollama/DeepSeek/vLLM 等任意 OpenAI 协议端点，通过 `CLAUDE_CODE_USE_OPENAI=1` 启用 |
|
||||
| Computer Use (`@ant/*`) | Stub packages in `packages/@ant/` |
|
||||
| `*-napi` packages (audio, image, url, modifiers) | Stubs in `packages/` (except `color-diff-napi` which is fully implemented) |
|
||||
| Analytics / GrowthBook / Sentry | Empty implementations |
|
||||
| Magic Docs / LSP Server | Removed |
|
||||
| Magic Docs / Voice Mode / LSP Server | Removed |
|
||||
| Plugins / Marketplace | Removed |
|
||||
| MCP OAuth | Simplified |
|
||||
|
||||
### Computer Use
|
||||
|
||||
Feature flag `CHICAGO_MCP`，dev/build 默认启用。实现跨平台屏幕操控（macOS + Windows 可用，Linux 待完成）。
|
||||
|
||||
- **`packages/@ant/computer-use-mcp/`** — MCP server，注册截图/键鼠/剪贴板/应用管理工具
|
||||
- **`packages/@ant/computer-use-input/`** — 键鼠模拟，dispatcher + per-platform backend（`backends/darwin.ts`、`win32.ts`、`linux.ts`）
|
||||
- **`packages/@ant/computer-use-swift/`** — 截图 + 应用管理，同样 dispatcher + per-platform backend
|
||||
- **`packages/@ant/claude-for-chrome-mcp/`** — Chrome 浏览器控制（独立于 Computer Use，通过 `--chrome` CLI 参数启用）
|
||||
|
||||
详见 `docs/features/computer-use.md`。
|
||||
|
||||
### Voice Mode
|
||||
|
||||
Feature flag `VOICE_MODE`，dev/build 默认启用。Push-to-Talk 语音输入，音频通过 WebSocket 流式传输到 Anthropic STT（Nova 3）。需要 Anthropic OAuth（非 API key）。
|
||||
|
||||
- **`src/voice/voiceModeEnabled.ts`** — 三层门控（feature flag + GrowthBook + OAuth auth）
|
||||
- **`src/hooks/useVoice.ts`** — React hook 管理录音状态和 WebSocket 连接
|
||||
- **`src/services/voiceStreamSTT.ts`** — STT WebSocket 流式传输
|
||||
|
||||
详见 `docs/features/voice-mode.md`。
|
||||
|
||||
### OpenAI 兼容层
|
||||
|
||||
通过 `CLAUDE_CODE_USE_OPENAI=1` 环境变量启用，支持任意 OpenAI Chat Completions 协议端点（Ollama、DeepSeek、vLLM 等）。流适配器模式：在 `queryModel()` 中将 Anthropic 格式请求转为 OpenAI 格式，再将 SSE 流转换回 `BetaRawMessageStreamEvent`，下游代码完全不改。
|
||||
|
||||
- **`src/services/api/openai/`** — client、消息/工具转换、流适配、模型映射
|
||||
- **`src/utils/model/providers.ts`** — 添加 `'openai'` provider 类型（最高优先级）
|
||||
|
||||
关键环境变量：`CLAUDE_CODE_USE_OPENAI`、`OPENAI_API_KEY`、`OPENAI_BASE_URL`、`OPENAI_MODEL`、`OPENAI_DEFAULT_OPUS_MODEL`、`OPENAI_DEFAULT_SONNET_MODEL`、`OPENAI_DEFAULT_HAIKU_MODEL`。详见 `docs/plans/openai-compatibility.md`。
|
||||
|
||||
### Gemini 兼容层
|
||||
|
||||
通过 `CLAUDE_CODE_USE_GEMINI=1` 环境变量或 `modelType: "gemini"` 设置启用，支持 Google Gemini API。独立的环境变量体系，不与 OpenAI 或 Anthropic 配置混杂。
|
||||
|
||||
- **`src/services/api/gemini/`** — client、模型映射、类型定义
|
||||
- **`src/utils/model/providers.ts`** — 添加 `'gemini'` provider 类型
|
||||
- **`src/utils/managedEnvConstants.ts`** — Gemini 专用的 managed env vars
|
||||
|
||||
关键环境变量：
|
||||
- `CLAUDE_CODE_USE_GEMINI` - 启用 Gemini provider
|
||||
- `GEMINI_API_KEY` - API 密钥（必填）
|
||||
- `GEMINI_BASE_URL` - API 端点（可选，默认 `https://generativelanguage.googleapis.com/v1beta`）
|
||||
- `GEMINI_MODEL` - 直接指定模型（最高优先级）
|
||||
- `GEMINI_DEFAULT_HAIKU_MODEL` / `GEMINI_DEFAULT_SONNET_MODEL` / `GEMINI_DEFAULT_OPUS_MODEL` - 按能力级别映射
|
||||
- `GEMINI_DEFAULT_HAIKU_MODEL_NAME` / `DESCRIPTION` / `SUPPORTED_CAPABILITIES` - 显示名称和描述
|
||||
- `GEMINI_SMALL_FAST_MODEL` - 快速任务使用的模型（可选）
|
||||
|
||||
模型映射优先级（`src/services/api/gemini/modelMapping.ts`）：
|
||||
1. `GEMINI_MODEL` - 直接覆盖
|
||||
2. `GEMINI_DEFAULT_*_MODEL` - 独立配置（推荐）
|
||||
3. `ANTHROPIC_DEFAULT_*_MODEL` - 向后兼容 fallback（已废弃）
|
||||
4. 原样返回 Anthropic 模型名
|
||||
|
||||
使用示例：
|
||||
```bash
|
||||
export CLAUDE_CODE_USE_GEMINI=1
|
||||
export GEMINI_API_KEY="your-api-key"
|
||||
export GEMINI_DEFAULT_SONNET_MODEL="gemini-2.5-flash"
|
||||
export GEMINI_DEFAULT_OPUS_MODEL="gemini-2.5-pro"
|
||||
```
|
||||
|
||||
### Key Type Files
|
||||
|
||||
- **`src/types/global.d.ts`** — Declares `MACRO`, `BUILD_TARGET`, `BUILD_ENV` and internal Anthropic-only identifiers.
|
||||
@@ -220,23 +106,10 @@ export GEMINI_DEFAULT_OPUS_MODEL="gemini-2.5-pro"
|
||||
- **`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")`，英文
|
||||
- **Mock 模式**: 对重依赖模块使用 `mock.module()` + `await import()` 解锁（必须内联在测试文件中，不能从共享 helper 导入）
|
||||
- **当前状态**: ~1623 tests / 114 files (110 unit + 4 integration) / 0 fail（详见 `docs/testing-spec.md`）
|
||||
|
||||
## Working with This Codebase
|
||||
|
||||
- **Don't try to fix all tsc errors** — they're from decompilation and don't affect runtime.
|
||||
- **Feature flags** — 默认全部关闭（`feature()` 返回 `false`）。Dev/build 各有自己的默认启用列表。不要在 `cli.tsx` 中重定义 `feature` 函数。
|
||||
- **`feature()` is always `false`** — any code behind a feature flag is dead code in this build.
|
||||
- **React Compiler output** — Components have decompiled memoization boilerplate (`const $ = _c(N)`). This is normal.
|
||||
- **`bun:bundle` import** — `import { feature } from 'bun:bundle'` 是 Bun 内置模块，由运行时/构建器解析。不要用自定义函数替代它。
|
||||
- **`bun:bundle` import** — 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.
|
||||
- **`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 行宽 + 按需分号。
|
||||
|
||||
805
DEV-LOG.md
805
DEV-LOG.md
@@ -1,805 +0,0 @@
|
||||
# DEV-LOG
|
||||
|
||||
## 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 连接，双向消息正常
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 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 客户端）。
|
||||
|
||||
38
Friends.md
38
Friends.md
@@ -1,38 +0,0 @@
|
||||
# 社区项目 & 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 |
|
||||
510
README.md
510
README.md
@@ -1,66 +1,49 @@
|
||||
# Claude Code Best V5 (CCB)
|
||||
# Claude Code Best V3 (CCB)
|
||||
|
||||
[](https://github.com/claude-code-best/claude-code/stargazers)
|
||||
[](https://github.com/claude-code-best/claude-code/graphs/contributors)
|
||||
[](https://github.com/claude-code-best/claude-code/issues)
|
||||
[](https://github.com/claude-code-best/claude-code/blob/main/LICENSE)
|
||||
[](https://github.com/claude-code-best/claude-code/commits/main)
|
||||
[](https://bun.sh/)
|
||||
[](https://discord.gg/qZU6zS7Q)
|
||||
牢 A (Anthropic) 官方 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI 工具的源码反编译/逆向还原项目。目标是将 Claude Code 大部分功能及工程化能力复现。虽然很难绷, 但是它叫做 CCB(踩踩背)...
|
||||
|
||||
> Which Claude do you like? The open source one is the best.
|
||||
[文档在这里, 支持投稿 PR](https://ccb.agent-aura.top/)
|
||||
|
||||
牢 A (Anthropic) 官方 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI 工具的源码反编译/逆向还原项目。目标是将 Claude Code 大部分功能及工程化能力复现 (问就是老佛爷已经付过钱了)。虽然很难绷, 但是它叫做 CCB(踩踩背)...
|
||||
赞助商占位符
|
||||
|
||||
[文档在这里, 支持投稿 PR](https://ccb.agent-aura.top/) | [留影文档在这里](./Friends.md) | [Discord 群组](https://discord.gg/qZU6zS7Q)
|
||||
- [x] v1 会完成跑通及基本的类型检查通过;
|
||||
- [x] V2 会完整实现工程化配套设施;
|
||||
- [ ] Biome 格式化可能不会先实施, 避免代码冲突
|
||||
- [x] 构建流水线完成, 产物 Node/Bun 都可以运行
|
||||
- [x] V3 会写大量文档, 完善文档站点
|
||||
- [ ] V4 会完成大量的测试文件, 以提高稳定性
|
||||
|
||||
- ✅ [x] V4 — 测试补全、[Buddy](https://ccb.agent-aura.top/docs/features/buddy)、[Auto Mode](https://ccb.agent-aura.top/docs/safety/auto-mode)、环境变量 Feature 开关
|
||||
- ✅ [x] V5 — [Sentry](https://ccb.agent-aura.top/docs/internals/sentry-setup) / [GrowthBook](https://ccb.agent-aura.top/docs/internals/growthbook-adapter) 企业监控、[自定义 Login](https://ccb.agent-aura.top/docs/features/custom-platform-login)、[OpenAI 兼容](https://ccb.agent-aura.top/docs/plans/openai-compatibility)、[Web Search](https://ccb.agent-aura.top/docs/features/web-browser-tool)、[Computer Use](https://ccb.agent-aura.top/docs/features/computer-use) / [Chrome Use](https://ccb.agent-aura.top/docs/features/claude-in-chrome-mcp)、[Voice Mode](https://ccb.agent-aura.top/docs/features/voice-mode)、[Bridge Mode](https://ccb.agent-aura.top/docs/features/bridge-mode)、[/dream 记忆整理](https://ccb.agent-aura.top/docs/features/auto-dream)
|
||||
- 🔮 [ ] V6 — 大规模重构石山代码，全面模块分包（全新分支，main 封存为历史版本）
|
||||
> 我不知道这个项目还会存在多久, Star + Fork + git clone + .zip 包最稳健;
|
||||
>
|
||||
> 这个项目更新很快, 后台有 Opus 持续优化, 所以你可以提 issues, 但是 PR 暂时不会接受;
|
||||
>
|
||||
> Claude 已经烧了 800$ 以上, 如果你个人想赞助, 请随便找个机构捐款, 然后截图在 issues, 大家的力量是温暖的;
|
||||
>
|
||||
> 某些模型提供商想要赞助, 那么请私发一个 1w 额度以上的账号到 <claude-code-best@proton.me>; 我们会在赞助商栏直接给你最亮的位置
|
||||
|
||||
- 🚀 [想要启动项目](#快速开始源码版)
|
||||
- 🐛 [想要调试项目](#vs-code-调试)
|
||||
- 📖 [想要学习项目](#teach-me-学习项目)
|
||||
存活记录:
|
||||
|
||||
1. 开源后 24 小时: 突破 6k Star, 感谢各位支持. 完成 docs 文档的站点构建, 达到 v3 版本, 后续开始进行测试用例维护, 完成之后可以接受 PR; 看来牢 A 是不想理我们了;
|
||||
2. 开源后 15 小时: 完成了构建产物的 node 支持, 现在是完全体了; star 快到 3k 了; 等待牢 A 的邮件
|
||||
3. 开源后 12 小时: 愚人节, star 破 1k, 并且牢 A 没有发邮件搞这个项目
|
||||
4. 如果你想要私人咨询服务, 那么可以发送邮件到 <claude-code-best@proton.me>, 备注咨询与联系方式即可; 由于后续工作非常多, 可能会忽略邮件, 半天没回复, 可以多发;
|
||||
|
||||
## ⚡ 快速开始(安装版)
|
||||
## 快速开始
|
||||
|
||||
不用克隆仓库, 从 NPM 下载后, 直接使用
|
||||
|
||||
```sh
|
||||
bun i -g claude-code-best
|
||||
bun pm -g trust claude-code-best
|
||||
ccb # 直接打开 claude code
|
||||
```
|
||||
|
||||
⚠️ 国内对 github 网络较差的, 需要先设置这个环境变量
|
||||
|
||||
```bash
|
||||
DEFAULT_RELEASE_BASE=https://ghproxy.net/https://github.com/microsoft/ripgrep-prebuilt/releases/download/v15.0.1
|
||||
```
|
||||
|
||||
## ⚡ 快速开始(源码版)
|
||||
|
||||
### ⚙️ 环境要求
|
||||
### 环境要求
|
||||
|
||||
一定要最新版本的 bun 啊, 不然一堆奇奇怪怪的 BUG!!! bun upgrade!!!
|
||||
|
||||
- 📦 [Bun](https://bun.sh/) >= 1.3.11
|
||||
- ⚙️ 常规的配置 CC 的方式, 各大提供商都有自己的配置方式
|
||||
- [Bun](https://bun.sh/) >= 1.3.11
|
||||
- 常规的配置 CC 的方式, 各大提供商都有自己的配置方式
|
||||
|
||||
### 📥 安装
|
||||
### 安装
|
||||
|
||||
```bash
|
||||
bun install
|
||||
```
|
||||
|
||||
⚠️ 国内对 github 网络较差的,可以使用这个环境变量
|
||||
|
||||
```bash
|
||||
DEFAULT_RELEASE_BASE=https://ghproxy.net/https://github.com/microsoft/ripgrep-prebuilt/releases/download/v15.0.1
|
||||
```
|
||||
|
||||
### ▶️ 运行
|
||||
### 运行
|
||||
|
||||
```bash
|
||||
# 开发模式, 看到版本号 888 说明就是对了
|
||||
@@ -76,86 +59,9 @@ bun run build
|
||||
|
||||
如果遇到 bug 请直接提一个 issues, 我们优先解决
|
||||
|
||||
### 👤 新人配置 /login
|
||||
|
||||
首次运行后，在 REPL 中输入 `/login` 命令进入登录配置界面，选择 **Anthropic Compatible** 即可对接第三方 API 兼容服务（无需 Anthropic 官方账号）。
|
||||
选择 OpenAI 和 Gemini 对应的栏目都是支持相应协议的
|
||||
|
||||
需要填写的字段：
|
||||
|
||||
| 📌 字段 | 📝 说明 | 💡 示例 |
|
||||
|------|------|------|
|
||||
| Base URL | API 服务地址 | `https://api.example.com/v1` |
|
||||
| API Key | 认证密钥 | `sk-xxx` |
|
||||
| Haiku Model | 快速模型 ID | `claude-haiku-4-5-20251001` |
|
||||
| Sonnet Model | 均衡模型 ID | `claude-sonnet-4-6` |
|
||||
| Opus Model | 高性能模型 ID | `claude-opus-4-6` |
|
||||
|
||||
- ⌨️ **Tab / Shift+Tab** 切换字段，**Enter** 确认并跳到下一个，最后一个字段按 Enter 保存
|
||||
|
||||
|
||||
> ℹ️ 支持所有 Anthropic API 兼容服务（如 OpenRouter、AWS Bedrock 代理等），只要接口兼容 Messages API 即可。
|
||||
|
||||
## Feature Flags
|
||||
|
||||
所有功能开关通过 `FEATURE_<FLAG_NAME>=1` 环境变量启用，例如：
|
||||
|
||||
```bash
|
||||
FEATURE_BUDDY=1 FEATURE_FORK_SUBAGENT=1 bun run dev
|
||||
```
|
||||
|
||||
各 Feature 的详细说明见 [`docs/features/`](docs/features/) 目录，欢迎投稿补充。
|
||||
|
||||
## VS Code 调试
|
||||
|
||||
TUI (REPL) 模式需要真实终端，无法直接通过 VS Code launch 启动调试。使用 **attach 模式**：
|
||||
|
||||
### 步骤
|
||||
|
||||
1. **终端启动 inspect 服务**：
|
||||
```bash
|
||||
bun run dev:inspect
|
||||
```
|
||||
会输出类似 `ws://localhost:8888/xxxxxxxx` 的地址。
|
||||
|
||||
2. **VS Code 附着调试器**：
|
||||
- 在 `src/` 文件中打断点
|
||||
- F5 → 选择 **"Attach to Bun (TUI debug)"**
|
||||
|
||||
|
||||
## Teach Me 学习项目
|
||||
|
||||
我们新加了一个 teach-me skills, 通过问答式引导帮你理解这个项目的任何模块。(调整 [sigma skill 而来](https://github.com/sanyuan0704/sanyuan-skills))
|
||||
|
||||
```bash
|
||||
# 在 REPL 中直接输入
|
||||
/teach-me Claude Code 架构
|
||||
/teach-me React Ink 终端渲染 --level beginner
|
||||
/teach-me Tool 系统 --resume
|
||||
```
|
||||
|
||||
### 它能做什么
|
||||
|
||||
- **诊断水平** — 自动评估你对相关概念的掌握程度，跳过已知的、聚焦薄弱的
|
||||
- **构建学习路径** — 将主题拆解为 5-15 个原子概念，按依赖排序逐步推进
|
||||
- **苏格拉底式提问** — 用选项引导思考，而非直接给答案
|
||||
- **错误概念追踪** — 发现并纠正深层误解
|
||||
- **断点续学** — `--resume` 从上次进度继续
|
||||
|
||||
### 学习记录
|
||||
|
||||
学习进度保存在 `.claude/skills/teach-me/` 目录下，支持跨主题学习者档案。
|
||||
|
||||
## 相关文档及网站
|
||||
|
||||
- **在线文档（Mintlify）**: [ccb.agent-aura.top](https://ccb.agent-aura.top/) — 文档源码位于 [`docs/`](docs/) 目录，欢迎投稿 PR
|
||||
- **DeepWiki**: <https://deepwiki.com/claude-code-best/claude-code>
|
||||
|
||||
## Contributors
|
||||
|
||||
<a href="https://github.com/claude-code-best/claude-code/graphs/contributors">
|
||||
<img src="contributors.svg" alt="Contributors" />
|
||||
</a>
|
||||
<https://deepwiki.com/claude-code-best/claude-code>
|
||||
|
||||
## Star History
|
||||
|
||||
@@ -167,6 +73,364 @@ TUI (REPL) 模式需要真实终端，无法直接通过 VS Code launch 启动
|
||||
</picture>
|
||||
</a>
|
||||
|
||||
## 能力清单
|
||||
|
||||
> ✅ = 已实现 ⚠️ = 部分实现 / 条件启用 ❌ = stub / 移除 / feature flag 关闭
|
||||
|
||||
### 核心系统
|
||||
|
||||
| 能力 | 状态 | 说明 |
|
||||
|------|------|------|
|
||||
| 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 |
|
||||
|
||||
### 工具 — 始终可用
|
||||
|
||||
| 工具 | 状态 | 说明 |
|
||||
|------|------|------|
|
||||
| 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 资源列表（被 specialTools 过滤，特定条件下加入） |
|
||||
| ReadMcpResourceTool | ⚠️ | MCP 资源读取（同上） |
|
||||
| SyntheticOutputTool | ⚠️ | 仅在非交互会话（SDK/pipe 模式）下创建 |
|
||||
| CronCreateTool | ✅ | 定时任务创建（已移除 AGENT_TRIGGERS gate） |
|
||||
| CronDeleteTool | ✅ | 定时任务删除 |
|
||||
| CronListTool | ✅ | 定时任务列表 |
|
||||
| EnterWorktreeTool | ✅ | 进入 Git Worktree（`isWorktreeModeEnabled()` 已硬编码为 true） |
|
||||
| ExitWorktreeTool | ✅ | 退出 Git Worktree |
|
||||
|
||||
### 工具 — 条件启用
|
||||
|
||||
| 工具 | 状态 | 启用条件 |
|
||||
|------|------|----------|
|
||||
| GlobTool | ✅ | 未嵌入 bfs/ugrep 时启用（默认启用） |
|
||||
| GrepTool | ✅ | 同上 |
|
||||
| TaskCreateTool | ⚠️ | `isTodoV2Enabled()` 为 true 时 |
|
||||
| TaskGetTool | ⚠️ | 同上 |
|
||||
| TaskUpdateTool | ⚠️ | 同上 |
|
||||
| TaskListTool | ⚠️ | 同上 |
|
||||
| TeamCreateTool | ⚠️ | `isAgentSwarmsEnabled()` |
|
||||
| TeamDeleteTool | ⚠️ | 同上 |
|
||||
| ToolSearchTool | ⚠️ | `isToolSearchEnabledOptimistic()` |
|
||||
| PowerShellTool | ⚠️ | Windows 平台检测 |
|
||||
| LSPTool | ⚠️ | `ENABLE_LSP_TOOL` 环境变量 |
|
||||
| ConfigTool | ❌ | `USER_TYPE === 'ant'`（永远为 false） |
|
||||
|
||||
### 工具 — Feature Flag 关闭（全部不可用）
|
||||
|
||||
| 工具 | Feature Flag |
|
||||
|------|-------------|
|
||||
| SleepTool | `PROACTIVE` / `KAIROS` |
|
||||
| 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` / `KAIROS_PUSH_NOTIFICATION` |
|
||||
| SubscribePRTool | `KAIROS_GITHUB_WEBHOOKS` |
|
||||
| ListPeersTool | `UDS_INBOX` |
|
||||
| CtxInspectTool | `CONTEXT_COLLAPSE` |
|
||||
|
||||
### 工具 — 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` | ✅ | 反馈 |
|
||||
| `/loop` | ✅ | 定时循环执行（bundled skill，可通过 `CLAUDE_CODE_DISABLE_CRON` 关闭） |
|
||||
| `/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` |
|
||||
| `/remote-control` (alias `rc`) | `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（不可用）
|
||||
|
||||
`/files` `/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/`) | ✅ | 34 个文件，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` | ✅ | 1006 行完整 TypeScript 实现（语法高亮 diff） |
|
||||
| `audio-capture-napi` | ✅ | 151 行完整实现（跨平台音频录制，使用 SoX/arecord） |
|
||||
| `image-processor-napi` | ✅ | 125 行完整实现（macOS 剪贴板图片读取，使用 osascript + sharp） |
|
||||
| `modifiers-napi` | ✅ | 67 行完整实现（macOS 修饰键检测，bun:ffi + CoreGraphics） |
|
||||
| `url-handler-napi` | ❌ | stub，`waitForUrlEvent()` 返回 null |
|
||||
| `@ant/claude-for-chrome-mcp` | ❌ | stub，`createServer()` 返回 null |
|
||||
| `@ant/computer-use-mcp` | ⚠️ | 类型安全 stub（265 行，完整类型定义但函数返回空值） |
|
||||
| `@ant/computer-use-input` | ✅ | 183 行完整实现（macOS 键鼠模拟，AppleScript/JXA/CGEvent） |
|
||||
| `@ant/computer-use-swift` | ✅ | 388 行完整实现（macOS 显示器/应用管理/截图，JXA/screencapture） |
|
||||
|
||||
### Feature Flags（31 个，全部返回 `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 生成脚本
|
||||
├── build.ts # 构建脚本（Bun.build + code splitting + Node.js 兼容后处理）
|
||||
├── dist/ # 构建输出（入口 cli.js + ~450 chunk 文件）
|
||||
└── package.json # Bun workspaces monorepo 配置
|
||||
```
|
||||
|
||||
## 技术说明
|
||||
|
||||
### 运行时 Polyfill
|
||||
|
||||
入口文件 `src/entrypoints/cli.tsx` 顶部注入了必要的 polyfill：
|
||||
|
||||
- `feature()` — 所有 feature flag 返回 `false`，跳过未实现分支
|
||||
- `globalThis.MACRO` — 模拟构建时宏注入（VERSION 等）
|
||||
|
||||
### Monorepo
|
||||
|
||||
项目采用 Bun workspaces 管理内部包。原先手工放在 `node_modules/` 下的 stub 已统一迁入 `packages/`，通过 `workspace:*` 解析。
|
||||
|
||||
## Feature Flags 详解
|
||||
|
||||
原版 Claude Code 通过 `bun:bundle` 的 `feature()` 在构建时注入 feature flag，由 GrowthBook 等 A/B 实验平台控制灰度发布。本项目中 `feature()` 被 polyfill 为始终返回 `false`，因此以下 30 个 flag 全部关闭。
|
||||
|
||||
### 自主 Agent
|
||||
|
||||
| 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 子代理 — 从当前会话分叉出独立子代理 |
|
||||
|
||||
### 远程 / 分布式
|
||||
|
||||
| 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 镜像 — 会话状态同步/复制 |
|
||||
|
||||
### 通信
|
||||
|
||||
| Flag | 用途 |
|
||||
|------|------|
|
||||
| `UDS_INBOX` | Unix Domain Socket 收件箱 — Agent 间本地通信（`/peers`） |
|
||||
|
||||
### 增强工具
|
||||
|
||||
| Flag | 用途 |
|
||||
|------|------|
|
||||
| `CHICAGO_MCP` | Computer Use MCP — 计算机操作（屏幕截图、鼠标键盘控制） |
|
||||
| `WEB_BROWSER_TOOL` | 网页浏览器工具 — 在终端内嵌浏览器交互 |
|
||||
| `VOICE_MODE` | 语音模式 — 语音输入输出，麦克风 push-to-talk |
|
||||
| `WORKFLOW_SCRIPTS` | 工作流脚本 — 用户自定义自动化工作流 |
|
||||
| `MCP_SKILLS` | 基于 MCP 的 Skill 加载机制 |
|
||||
|
||||
### 对话管理
|
||||
|
||||
| Flag | 用途 |
|
||||
|------|------|
|
||||
| `HISTORY_SNIP` | 历史裁剪 — 手动裁剪对话历史中的片段（`/force-snip`） |
|
||||
| `ULTRAPLAN` | 超级计划 — 远程 Agent 协作的大规模规划功能 |
|
||||
| `AGENT_MEMORY_SNAPSHOT` | Agent 运行时的记忆快照功能 |
|
||||
|
||||
### 基础设施 / 实验
|
||||
|
||||
| Flag | 用途 |
|
||||
|------|------|
|
||||
| `ABLATION_BASELINE` | 科学实验 — 基线消融测试，用于 A/B 实验对照组 |
|
||||
| `HARD_FAIL` | 硬失败模式 — 遇错直接中断而非降级 |
|
||||
| `TRANSCRIPT_CLASSIFIER` | 对话分类器 — `auto-mode` 命令，自动分析和分类对话记录 |
|
||||
| `UPLOAD_USER_SETTINGS` | 设置同步上传 — 将本地配置同步到云端 |
|
||||
| `LODESTONE` | 深度链接协议处理器 — 从外部应用跳转到 Claude Code 指定位置 |
|
||||
| `EXPERIMENTAL_SKILL_SEARCH` | 实验性 Skill 搜索索引 |
|
||||
| `TORCH` | Torch 功能（具体用途未知，可能是某种高亮/追踪机制） |
|
||||
|
||||
## 许可证
|
||||
|
||||
本项目仅供学习研究用途。Claude Code 的所有权利归 [Anthropic](https://www.anthropic.com/) 所有。
|
||||
|
||||
158
README_EN.md
158
README_EN.md
@@ -1,158 +0,0 @@
|
||||
# Claude Code Best V5 (CCB)
|
||||
|
||||
[](https://github.com/claude-code-best/claude-code/stargazers)
|
||||
[](https://github.com/claude-code-best/claude-code/graphs/contributors)
|
||||
[](https://github.com/claude-code-best/claude-code/issues)
|
||||
[](https://github.com/claude-code-best/claude-code/blob/main/LICENSE)
|
||||
[](https://github.com/claude-code-best/claude-code/commits/main)
|
||||
[](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
|
||||
- Standard Claude Code configuration — each provider has its own setup method
|
||||
|
||||
### Install
|
||||
|
||||
```bash
|
||||
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/).
|
||||
26
TODO.md
Normal file
26
TODO.md
Normal file
@@ -0,0 +1,26 @@
|
||||
# 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)
|
||||
119
build.ts
119
build.ts
@@ -1,104 +1,47 @@
|
||||
import { readdir, readFile, writeFile, cp } from 'fs/promises'
|
||||
import { join } from 'path'
|
||||
import { getMacroDefines } from './scripts/defines.ts'
|
||||
import { readdir, readFile, writeFile } from "fs/promises";
|
||||
import { join } from "path";
|
||||
|
||||
const outdir = 'dist'
|
||||
const outdir = "dist";
|
||||
|
||||
// Step 1: Clean output directory
|
||||
const { rmSync } = await import('fs')
|
||||
rmSync(outdir, { recursive: true, force: true })
|
||||
|
||||
// Default features that match the official CLI build.
|
||||
// Additional features can be enabled via FEATURE_<NAME>=1 env vars.
|
||||
const DEFAULT_BUILD_FEATURES = [
|
||||
'BUDDY',
|
||||
'TRANSCRIPT_CLASSIFIER',
|
||||
'BRIDGE_MODE',
|
||||
'AGENT_TRIGGERS_REMOTE',
|
||||
'CHICAGO_MCP',
|
||||
'VOICE_MODE',
|
||||
'SHOT_STATS',
|
||||
'PROMPT_CACHE_BREAK_DETECTION',
|
||||
'TOKEN_BUDGET',
|
||||
// P0: local features
|
||||
'AGENT_TRIGGERS',
|
||||
'ULTRATHINK',
|
||||
'BUILTIN_EXPLORE_PLAN_AGENTS',
|
||||
'LODESTONE',
|
||||
// P1: API-dependent features
|
||||
'EXTRACT_MEMORIES',
|
||||
'VERIFICATION_AGENT',
|
||||
'KAIROS_BRIEF',
|
||||
'AWAY_SUMMARY',
|
||||
'ULTRAPLAN',
|
||||
// P2: daemon + remote control server
|
||||
'DAEMON',
|
||||
]
|
||||
|
||||
// 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])]
|
||||
const { rmSync } = await import("fs");
|
||||
rmSync(outdir, { recursive: true, force: true });
|
||||
|
||||
// Step 2: Bundle with splitting
|
||||
const result = await Bun.build({
|
||||
entrypoints: ['src/entrypoints/cli.tsx'],
|
||||
outdir,
|
||||
target: 'bun',
|
||||
splitting: true,
|
||||
define: getMacroDefines(),
|
||||
features,
|
||||
})
|
||||
entrypoints: ["src/entrypoints/cli.tsx"],
|
||||
outdir,
|
||||
target: "bun",
|
||||
splitting: true,
|
||||
});
|
||||
|
||||
if (!result.success) {
|
||||
console.error('Build failed:')
|
||||
for (const log of result.logs) {
|
||||
console.error(log)
|
||||
}
|
||||
process.exit(1)
|
||||
console.error("Build failed:");
|
||||
for (const log of result.logs) {
|
||||
console.error(log);
|
||||
}
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
// Step 3: Post-process — replace Bun-only `import.meta.require` with Node.js compatible version
|
||||
const files = await readdir(outdir)
|
||||
const IMPORT_META_REQUIRE = 'var __require = import.meta.require;'
|
||||
const COMPAT_REQUIRE = `var __require = typeof import.meta.require === "function" ? import.meta.require : (await import("module")).createRequire(import.meta.url);`
|
||||
const files = await readdir(outdir);
|
||||
const IMPORT_META_REQUIRE = "var __require = import.meta.require;";
|
||||
const COMPAT_REQUIRE = `var __require = typeof import.meta.require === "function" ? import.meta.require : (await import("module")).createRequire(import.meta.url);`;
|
||||
|
||||
let patched = 0
|
||||
let patched = 0;
|
||||
for (const file of files) {
|
||||
if (!file.endsWith('.js')) continue
|
||||
const filePath = join(outdir, file)
|
||||
const content = await readFile(filePath, 'utf-8')
|
||||
if (content.includes(IMPORT_META_REQUIRE)) {
|
||||
await writeFile(
|
||||
filePath,
|
||||
content.replace(IMPORT_META_REQUIRE, COMPAT_REQUIRE),
|
||||
)
|
||||
patched++
|
||||
}
|
||||
if (!file.endsWith(".js")) continue;
|
||||
const filePath = join(outdir, file);
|
||||
const content = await readFile(filePath, "utf-8");
|
||||
if (content.includes(IMPORT_META_REQUIRE)) {
|
||||
await writeFile(
|
||||
filePath,
|
||||
content.replace(IMPORT_META_REQUIRE, COMPAT_REQUIRE),
|
||||
);
|
||||
patched++;
|
||||
}
|
||||
}
|
||||
|
||||
console.log(
|
||||
`Bundled ${result.outputs.length} files to ${outdir}/ (patched ${patched} for Node.js compat)`,
|
||||
)
|
||||
|
||||
// Step 4: Copy native .node addon files (audio-capture)
|
||||
const vendorDir = join(outdir, 'vendor', 'audio-capture')
|
||||
await cp('vendor/audio-capture', vendorDir, { recursive: true })
|
||||
console.log(`Copied vendor/audio-capture/ → ${vendorDir}/`)
|
||||
|
||||
// Step 5: Bundle download-ripgrep script as standalone JS for postinstall
|
||||
const rgScript = await Bun.build({
|
||||
entrypoints: ['scripts/download-ripgrep.ts'],
|
||||
outdir,
|
||||
target: 'node',
|
||||
})
|
||||
if (!rgScript.success) {
|
||||
console.error('Failed to bundle download-ripgrep script:')
|
||||
for (const log of rgScript.logs) {
|
||||
console.error(log)
|
||||
}
|
||||
// Non-fatal — postinstall fallback to bun run scripts/download-ripgrep.ts
|
||||
} else {
|
||||
console.log(`Bundled download-ripgrep script to ${outdir}/`)
|
||||
}
|
||||
`Bundled ${result.outputs.length} files to ${outdir}/ (patched ${patched} for Node.js compat)`,
|
||||
);
|
||||
|
||||
471
bun.lock
471
bun.lock
@@ -17,7 +17,6 @@
|
||||
"@anthropic-ai/sandbox-runtime": "^0.0.44",
|
||||
"@anthropic-ai/sdk": "^0.80.0",
|
||||
"@anthropic-ai/vertex-sdk": "^0.14.4",
|
||||
"@anthropic/ink": "workspace:*",
|
||||
"@aws-sdk/client-bedrock": "^3.1020.0",
|
||||
"@aws-sdk/client-bedrock-runtime": "^3.1020.0",
|
||||
"@aws-sdk/client-sts": "^3.1020.0",
|
||||
@@ -46,7 +45,6 @@
|
||||
"@opentelemetry/sdk-metrics": "^2.6.1",
|
||||
"@opentelemetry/sdk-trace-base": "^2.6.1",
|
||||
"@opentelemetry/semantic-conventions": "^1.40.0",
|
||||
"@sentry/node": "^10.47.0",
|
||||
"@smithy/core": "^3.23.13",
|
||||
"@smithy/node-http-handler": "^4.5.1",
|
||||
"@types/bun": "^1.3.11",
|
||||
@@ -78,7 +76,6 @@
|
||||
"fuse.js": "^7.1.0",
|
||||
"get-east-asian-width": "^1.5.0",
|
||||
"google-auth-library": "^10.6.2",
|
||||
"he": "^1.2.0",
|
||||
"highlight.js": "^11.11.1",
|
||||
"https-proxy-agent": "^8.0.0",
|
||||
"ignore": "^7.0.5",
|
||||
@@ -90,7 +87,6 @@
|
||||
"lru-cache": "^11.2.7",
|
||||
"marked": "^17.0.5",
|
||||
"modifiers-napi": "workspace:*",
|
||||
"openai": "^6.33.0",
|
||||
"p-map": "^7.0.4",
|
||||
"picomatch": "^4.0.4",
|
||||
"plist": "^3.1.0",
|
||||
@@ -139,29 +135,6 @@
|
||||
"name": "@ant/computer-use-swift",
|
||||
"version": "1.0.0",
|
||||
},
|
||||
"packages/@ant/ink": {
|
||||
"name": "@anthropic/ink",
|
||||
"version": "1.0.0",
|
||||
"dependencies": {
|
||||
"auto-bind": "^5.0.1",
|
||||
"bidi-js": "^1.0.3",
|
||||
"chalk": "^5.6.2",
|
||||
"cli-boxes": "^4.0.1",
|
||||
"emoji-regex": "^10.6.0",
|
||||
"figures": "^6.1.0",
|
||||
"get-east-asian-width": "^1.5.0",
|
||||
"indent-string": "^5.0.0",
|
||||
"lodash-es": "^4.17.23",
|
||||
"react": "^19.2.4",
|
||||
"react-reconciler": "^0.33.0",
|
||||
"signal-exit": "^4.1.0",
|
||||
"strip-ansi": "^7.2.0",
|
||||
"supports-hyperlinks": "^4.4.0",
|
||||
"type-fest": "^5.5.0",
|
||||
"usehooks-ts": "^3.1.1",
|
||||
"wrap-ansi": "^10.0.0",
|
||||
},
|
||||
},
|
||||
"packages/audio-capture-napi": {
|
||||
"name": "audio-capture-napi",
|
||||
"version": "1.0.0",
|
||||
@@ -184,26 +157,6 @@
|
||||
"name": "modifiers-napi",
|
||||
"version": "1.0.0",
|
||||
},
|
||||
"packages/remote-control-server": {
|
||||
"name": "@anthropic/remote-control-server",
|
||||
"version": "0.1.0",
|
||||
"dependencies": {
|
||||
"hono": "^4.7.0",
|
||||
"uuid": "^11.0.0",
|
||||
},
|
||||
"devDependencies": {
|
||||
"@tailwindcss/vite": "^4.0.0",
|
||||
"@types/react": "^19.0.0",
|
||||
"@types/react-dom": "^19.0.0",
|
||||
"@types/uuid": "^10.0.0",
|
||||
"@vitejs/plugin-react": "^4.0.0",
|
||||
"react": "^19.0.0",
|
||||
"react-dom": "^19.0.0",
|
||||
"tailwindcss": "^4.0.0",
|
||||
"typescript": "^5.7.0",
|
||||
"vite": "^6.0.0",
|
||||
},
|
||||
},
|
||||
"packages/url-handler-napi": {
|
||||
"name": "url-handler-napi",
|
||||
"version": "1.0.0",
|
||||
@@ -234,10 +187,6 @@
|
||||
|
||||
"@anthropic-ai/vertex-sdk": ["@anthropic-ai/vertex-sdk@0.14.4", "https://registry.npmmirror.com/@anthropic-ai/vertex-sdk/-/vertex-sdk-0.14.4.tgz", { "dependencies": { "@anthropic-ai/sdk": ">=0.50.3 <1", "google-auth-library": "^9.4.2" } }, "sha512-BZUPRWghZxfSFtAxU563wH+jfWBPoedAwsVxG35FhmNsjeV8tyfN+lFriWhCpcZApxA4NdT6Soov+PzfnxxD5g=="],
|
||||
|
||||
"@anthropic/ink": ["@anthropic/ink@workspace:packages/@ant/ink"],
|
||||
|
||||
"@anthropic/remote-control-server": ["@anthropic/remote-control-server@workspace:packages/remote-control-server"],
|
||||
|
||||
"@aws-crypto/crc32": ["@aws-crypto/crc32@5.2.0", "https://registry.npmmirror.com/@aws-crypto/crc32/-/crc32-5.2.0.tgz", { "dependencies": { "@aws-crypto/util": "^5.2.0", "@aws-sdk/types": "^3.222.0", "tslib": "^2.6.2" } }, "sha512-nLbCWqQNgUiwwtFsen1AdzAtvuLRsQS8rYgMuxCrdKf9kOssamGLuPwyTY9wyYblNr9+1XM8v6zoDTPPSIeANg=="],
|
||||
|
||||
"@aws-crypto/sha256-browser": ["@aws-crypto/sha256-browser@5.2.0", "https://registry.npmmirror.com/@aws-crypto/sha256-browser/-/sha256-browser-5.2.0.tgz", { "dependencies": { "@aws-crypto/sha256-js": "^5.2.0", "@aws-crypto/supports-web-crypto": "^5.2.0", "@aws-crypto/util": "^5.2.0", "@aws-sdk/types": "^3.222.0", "@aws-sdk/util-locate-window": "^3.0.0", "@smithy/util-utf8": "^2.0.0", "tslib": "^2.6.2" } }, "sha512-AXfN/lGotSQwu6HNcEsIASo7kWXZ5HYWvfOmSNKDsEqC4OashTp8alTmaz+F7TC2L083SFv5RdB+qU3Vs1kZqw=="],
|
||||
@@ -338,46 +287,8 @@
|
||||
|
||||
"@azure/msal-node": ["@azure/msal-node@5.1.1", "https://registry.npmmirror.com/@azure/msal-node/-/msal-node-5.1.1.tgz", { "dependencies": { "@azure/msal-common": "16.4.0", "jsonwebtoken": "^9.0.0", "uuid": "^8.3.0" } }, "sha512-71grXU6+5hl+3CL3joOxlj/AW6rmhthuTlG0fRqsTrhPArQBpZuUFzCIlKOGdcafLUa/i1hBdV78ZxJdlvRA+g=="],
|
||||
|
||||
"@babel/code-frame": ["@babel/code-frame@7.29.0", "https://registry.npmmirror.com/@babel/code-frame/-/code-frame-7.29.0.tgz", { "dependencies": { "@babel/helper-validator-identifier": "^7.28.5", "js-tokens": "^4.0.0", "picocolors": "^1.1.1" } }, "sha512-9NhCeYjq9+3uxgdtp20LSiJXJvN0FeCtNGpJxuMFZ1Kv3cWUNb6DOhJwUvcVCzKGR66cw4njwM6hrJLqgOwbcw=="],
|
||||
|
||||
"@babel/compat-data": ["@babel/compat-data@7.29.0", "https://registry.npmmirror.com/@babel/compat-data/-/compat-data-7.29.0.tgz", {}, "sha512-T1NCJqT/j9+cn8fvkt7jtwbLBfLC/1y1c7NtCeXFRgzGTsafi68MRv8yzkYSapBnFA6L3U2VSc02ciDzoAJhJg=="],
|
||||
|
||||
"@babel/core": ["@babel/core@7.29.0", "https://registry.npmmirror.com/@babel/core/-/core-7.29.0.tgz", { "dependencies": { "@babel/code-frame": "^7.29.0", "@babel/generator": "^7.29.0", "@babel/helper-compilation-targets": "^7.28.6", "@babel/helper-module-transforms": "^7.28.6", "@babel/helpers": "^7.28.6", "@babel/parser": "^7.29.0", "@babel/template": "^7.28.6", "@babel/traverse": "^7.29.0", "@babel/types": "^7.29.0", "@jridgewell/remapping": "^2.3.5", "convert-source-map": "^2.0.0", "debug": "^4.1.0", "gensync": "^1.0.0-beta.2", "json5": "^2.2.3", "semver": "^6.3.1" } }, "sha512-CGOfOJqWjg2qW/Mb6zNsDm+u5vFQ8DxXfbM09z69p5Z6+mE1ikP2jUXw+j42Pf1XTYED2Rni5f95npYeuwMDQA=="],
|
||||
|
||||
"@babel/generator": ["@babel/generator@7.29.1", "https://registry.npmmirror.com/@babel/generator/-/generator-7.29.1.tgz", { "dependencies": { "@babel/parser": "^7.29.0", "@babel/types": "^7.29.0", "@jridgewell/gen-mapping": "^0.3.12", "@jridgewell/trace-mapping": "^0.3.28", "jsesc": "^3.0.2" } }, "sha512-qsaF+9Qcm2Qv8SRIMMscAvG4O3lJ0F1GuMo5HR/Bp02LopNgnZBC/EkbevHFeGs4ls/oPz9v+Bsmzbkbe+0dUw=="],
|
||||
|
||||
"@babel/helper-compilation-targets": ["@babel/helper-compilation-targets@7.28.6", "https://registry.npmmirror.com/@babel/helper-compilation-targets/-/helper-compilation-targets-7.28.6.tgz", { "dependencies": { "@babel/compat-data": "^7.28.6", "@babel/helper-validator-option": "^7.27.1", "browserslist": "^4.24.0", "lru-cache": "^5.1.1", "semver": "^6.3.1" } }, "sha512-JYtls3hqi15fcx5GaSNL7SCTJ2MNmjrkHXg4FSpOA/grxK8KwyZ5bubHsCq8FXCkua6xhuaaBit+3b7+VZRfcA=="],
|
||||
|
||||
"@babel/helper-globals": ["@babel/helper-globals@7.28.0", "https://registry.npmmirror.com/@babel/helper-globals/-/helper-globals-7.28.0.tgz", {}, "sha512-+W6cISkXFa1jXsDEdYA8HeevQT/FULhxzR99pxphltZcVaugps53THCeiWA8SguxxpSp3gKPiuYfSWopkLQ4hw=="],
|
||||
|
||||
"@babel/helper-module-imports": ["@babel/helper-module-imports@7.28.6", "https://registry.npmmirror.com/@babel/helper-module-imports/-/helper-module-imports-7.28.6.tgz", { "dependencies": { "@babel/traverse": "^7.28.6", "@babel/types": "^7.28.6" } }, "sha512-l5XkZK7r7wa9LucGw9LwZyyCUscb4x37JWTPz7swwFE/0FMQAGpiWUZn8u9DzkSBWEcK25jmvubfpw2dnAMdbw=="],
|
||||
|
||||
"@babel/helper-module-transforms": ["@babel/helper-module-transforms@7.28.6", "https://registry.npmmirror.com/@babel/helper-module-transforms/-/helper-module-transforms-7.28.6.tgz", { "dependencies": { "@babel/helper-module-imports": "^7.28.6", "@babel/helper-validator-identifier": "^7.28.5", "@babel/traverse": "^7.28.6" }, "peerDependencies": { "@babel/core": "^7.0.0" } }, "sha512-67oXFAYr2cDLDVGLXTEABjdBJZ6drElUSI7WKp70NrpyISso3plG9SAGEF6y7zbha/wOzUByWWTJvEDVNIUGcA=="],
|
||||
|
||||
"@babel/helper-plugin-utils": ["@babel/helper-plugin-utils@7.28.6", "https://registry.npmmirror.com/@babel/helper-plugin-utils/-/helper-plugin-utils-7.28.6.tgz", {}, "sha512-S9gzZ/bz83GRysI7gAD4wPT/AI3uCnY+9xn+Mx/KPs2JwHJIz1W8PZkg2cqyt3RNOBM8ejcXhV6y8Og7ly/Dug=="],
|
||||
|
||||
"@babel/helper-string-parser": ["@babel/helper-string-parser@7.27.1", "https://registry.npmmirror.com/@babel/helper-string-parser/-/helper-string-parser-7.27.1.tgz", {}, "sha512-qMlSxKbpRlAridDExk92nSobyDdpPijUq2DW6oDnUqd0iOGxmQjyqhMIihI9+zv4LPyZdRje2cavWPbCbWm3eA=="],
|
||||
|
||||
"@babel/helper-validator-identifier": ["@babel/helper-validator-identifier@7.28.5", "https://registry.npmmirror.com/@babel/helper-validator-identifier/-/helper-validator-identifier-7.28.5.tgz", {}, "sha512-qSs4ifwzKJSV39ucNjsvc6WVHs6b7S03sOh2OcHF9UHfVPqWWALUsNUVzhSBiItjRZoLHx7nIarVjqKVusUZ1Q=="],
|
||||
|
||||
"@babel/helper-validator-option": ["@babel/helper-validator-option@7.27.1", "https://registry.npmmirror.com/@babel/helper-validator-option/-/helper-validator-option-7.27.1.tgz", {}, "sha512-YvjJow9FxbhFFKDSuFnVCe2WxXk1zWc22fFePVNEaWJEu8IrZVlda6N0uHwzZrUM1il7NC9Mlp4MaJYbYd9JSg=="],
|
||||
|
||||
"@babel/helpers": ["@babel/helpers@7.29.2", "https://registry.npmmirror.com/@babel/helpers/-/helpers-7.29.2.tgz", { "dependencies": { "@babel/template": "^7.28.6", "@babel/types": "^7.29.0" } }, "sha512-HoGuUs4sCZNezVEKdVcwqmZN8GoHirLUcLaYVNBK2J0DadGtdcqgr3BCbvH8+XUo4NGjNl3VOtSjEKNzqfFgKw=="],
|
||||
|
||||
"@babel/parser": ["@babel/parser@7.29.2", "https://registry.npmmirror.com/@babel/parser/-/parser-7.29.2.tgz", { "dependencies": { "@babel/types": "^7.29.0" }, "bin": "./bin/babel-parser.js" }, "sha512-4GgRzy/+fsBa72/RZVJmGKPmZu9Byn8o4MoLpmNe1m8ZfYnz5emHLQz3U4gLud6Zwl0RZIcgiLD7Uq7ySFuDLA=="],
|
||||
|
||||
"@babel/plugin-transform-react-jsx-self": ["@babel/plugin-transform-react-jsx-self@7.27.1", "https://registry.npmmirror.com/@babel/plugin-transform-react-jsx-self/-/plugin-transform-react-jsx-self-7.27.1.tgz", { "dependencies": { "@babel/helper-plugin-utils": "^7.27.1" }, "peerDependencies": { "@babel/core": "^7.0.0-0" } }, "sha512-6UzkCs+ejGdZ5mFFC/OCUrv028ab2fp1znZmCZjAOBKiBK2jXD1O+BPSfX8X2qjJ75fZBMSnQn3Rq2mrBJK2mw=="],
|
||||
|
||||
"@babel/plugin-transform-react-jsx-source": ["@babel/plugin-transform-react-jsx-source@7.27.1", "https://registry.npmmirror.com/@babel/plugin-transform-react-jsx-source/-/plugin-transform-react-jsx-source-7.27.1.tgz", { "dependencies": { "@babel/helper-plugin-utils": "^7.27.1" }, "peerDependencies": { "@babel/core": "^7.0.0-0" } }, "sha512-zbwoTsBruTeKB9hSq73ha66iFeJHuaFkUbwvqElnygoNbj/jHRsSeokowZFN3CZ64IvEqcmmkVe89OPXc7ldAw=="],
|
||||
|
||||
"@babel/runtime": ["@babel/runtime@7.29.2", "https://registry.npmmirror.com/@babel/runtime/-/runtime-7.29.2.tgz", {}, "sha512-JiDShH45zKHWyGe4ZNVRrCjBz8Nh9TMmZG1kh4QTK8hCBTWBi8Da+i7s1fJw7/lYpM4ccepSNfqzZ/QvABBi5g=="],
|
||||
|
||||
"@babel/template": ["@babel/template@7.28.6", "https://registry.npmmirror.com/@babel/template/-/template-7.28.6.tgz", { "dependencies": { "@babel/code-frame": "^7.28.6", "@babel/parser": "^7.28.6", "@babel/types": "^7.28.6" } }, "sha512-YA6Ma2KsCdGb+WC6UpBVFJGXL58MDA6oyONbjyF/+5sBgxY/dwkhLogbMT2GXXyU84/IhRw/2D1Os1B/giz+BQ=="],
|
||||
|
||||
"@babel/traverse": ["@babel/traverse@7.29.0", "https://registry.npmmirror.com/@babel/traverse/-/traverse-7.29.0.tgz", { "dependencies": { "@babel/code-frame": "^7.29.0", "@babel/generator": "^7.29.0", "@babel/helper-globals": "^7.28.0", "@babel/parser": "^7.29.0", "@babel/template": "^7.28.6", "@babel/types": "^7.29.0", "debug": "^4.3.1" } }, "sha512-4HPiQr0X7+waHfyXPZpWPfWL/J7dcN1mx9gL6WdQVMbPnF3+ZhSMs8tCxN7oHddJE9fhNE7+lxdnlyemKfJRuA=="],
|
||||
|
||||
"@babel/types": ["@babel/types@7.29.0", "https://registry.npmmirror.com/@babel/types/-/types-7.29.0.tgz", { "dependencies": { "@babel/helper-string-parser": "^7.27.1", "@babel/helper-validator-identifier": "^7.28.5" } }, "sha512-LwdZHpScM4Qz8Xw2iKSzS+cfglZzJGvofQICy7W7v4caru4EaAmyUuO6BGrbyQ2mYV11W0U8j5mBhd14dd3B0A=="],
|
||||
|
||||
"@biomejs/biome": ["@biomejs/biome@2.4.10", "https://registry.npmmirror.com/@biomejs/biome/-/biome-2.4.10.tgz", { "optionalDependencies": { "@biomejs/cli-darwin-arm64": "2.4.10", "@biomejs/cli-darwin-x64": "2.4.10", "@biomejs/cli-linux-arm64": "2.4.10", "@biomejs/cli-linux-arm64-musl": "2.4.10", "@biomejs/cli-linux-x64": "2.4.10", "@biomejs/cli-linux-x64-musl": "2.4.10", "@biomejs/cli-win32-arm64": "2.4.10", "@biomejs/cli-win32-x64": "2.4.10" }, "bin": { "biome": "bin/biome" } }, "sha512-xxA3AphFQ1geij4JTHXv4EeSTda1IFn22ye9LdyVPoJU19fNVl0uzfEuhsfQ4Yue/0FaLs2/ccVi4UDiE7R30w=="],
|
||||
|
||||
"@biomejs/cli-darwin-arm64": ["@biomejs/cli-darwin-arm64@2.4.10", "https://registry.npmmirror.com/@biomejs/cli-darwin-arm64/-/cli-darwin-arm64-2.4.10.tgz", { "os": "darwin", "cpu": "arm64" }, "sha512-vuzzI1cWqDVzOMIkYyHbKqp+AkQq4K7k+UCXWpkYcY/HDn1UxdsbsfgtVpa40shem8Kax4TLDLlx8kMAecgqiw=="],
|
||||
@@ -404,60 +315,6 @@
|
||||
|
||||
"@emnapi/wasi-threads": ["@emnapi/wasi-threads@1.2.0", "https://registry.npmmirror.com/@emnapi/wasi-threads/-/wasi-threads-1.2.0.tgz", { "dependencies": { "tslib": "^2.4.0" } }, "sha512-N10dEJNSsUx41Z6pZsXU8FjPjpBEplgH24sfkmITrBED1/U2Esum9F3lfLrMjKHHjmi557zQn7kR9R+XWXu5Rg=="],
|
||||
|
||||
"@esbuild/aix-ppc64": ["@esbuild/aix-ppc64@0.25.12", "https://registry.npmmirror.com/@esbuild/aix-ppc64/-/aix-ppc64-0.25.12.tgz", { "os": "aix", "cpu": "ppc64" }, "sha512-Hhmwd6CInZ3dwpuGTF8fJG6yoWmsToE+vYgD4nytZVxcu1ulHpUQRAB1UJ8+N1Am3Mz4+xOByoQoSZf4D+CpkA=="],
|
||||
|
||||
"@esbuild/android-arm": ["@esbuild/android-arm@0.25.12", "https://registry.npmmirror.com/@esbuild/android-arm/-/android-arm-0.25.12.tgz", { "os": "android", "cpu": "arm" }, "sha512-VJ+sKvNA/GE7Ccacc9Cha7bpS8nyzVv0jdVgwNDaR4gDMC/2TTRc33Ip8qrNYUcpkOHUT5OZ0bUcNNVZQ9RLlg=="],
|
||||
|
||||
"@esbuild/android-arm64": ["@esbuild/android-arm64@0.25.12", "https://registry.npmmirror.com/@esbuild/android-arm64/-/android-arm64-0.25.12.tgz", { "os": "android", "cpu": "arm64" }, "sha512-6AAmLG7zwD1Z159jCKPvAxZd4y/VTO0VkprYy+3N2FtJ8+BQWFXU+OxARIwA46c5tdD9SsKGZ/1ocqBS/gAKHg=="],
|
||||
|
||||
"@esbuild/android-x64": ["@esbuild/android-x64@0.25.12", "https://registry.npmmirror.com/@esbuild/android-x64/-/android-x64-0.25.12.tgz", { "os": "android", "cpu": "x64" }, "sha512-5jbb+2hhDHx5phYR2By8GTWEzn6I9UqR11Kwf22iKbNpYrsmRB18aX/9ivc5cabcUiAT/wM+YIZ6SG9QO6a8kg=="],
|
||||
|
||||
"@esbuild/darwin-arm64": ["@esbuild/darwin-arm64@0.25.12", "https://registry.npmmirror.com/@esbuild/darwin-arm64/-/darwin-arm64-0.25.12.tgz", { "os": "darwin", "cpu": "arm64" }, "sha512-N3zl+lxHCifgIlcMUP5016ESkeQjLj/959RxxNYIthIg+CQHInujFuXeWbWMgnTo4cp5XVHqFPmpyu9J65C1Yg=="],
|
||||
|
||||
"@esbuild/darwin-x64": ["@esbuild/darwin-x64@0.25.12", "https://registry.npmmirror.com/@esbuild/darwin-x64/-/darwin-x64-0.25.12.tgz", { "os": "darwin", "cpu": "x64" }, "sha512-HQ9ka4Kx21qHXwtlTUVbKJOAnmG1ipXhdWTmNXiPzPfWKpXqASVcWdnf2bnL73wgjNrFXAa3yYvBSd9pzfEIpA=="],
|
||||
|
||||
"@esbuild/freebsd-arm64": ["@esbuild/freebsd-arm64@0.25.12", "https://registry.npmmirror.com/@esbuild/freebsd-arm64/-/freebsd-arm64-0.25.12.tgz", { "os": "freebsd", "cpu": "arm64" }, "sha512-gA0Bx759+7Jve03K1S0vkOu5Lg/85dou3EseOGUes8flVOGxbhDDh/iZaoek11Y8mtyKPGF3vP8XhnkDEAmzeg=="],
|
||||
|
||||
"@esbuild/freebsd-x64": ["@esbuild/freebsd-x64@0.25.12", "https://registry.npmmirror.com/@esbuild/freebsd-x64/-/freebsd-x64-0.25.12.tgz", { "os": "freebsd", "cpu": "x64" }, "sha512-TGbO26Yw2xsHzxtbVFGEXBFH0FRAP7gtcPE7P5yP7wGy7cXK2oO7RyOhL5NLiqTlBh47XhmIUXuGciXEqYFfBQ=="],
|
||||
|
||||
"@esbuild/linux-arm": ["@esbuild/linux-arm@0.25.12", "https://registry.npmmirror.com/@esbuild/linux-arm/-/linux-arm-0.25.12.tgz", { "os": "linux", "cpu": "arm" }, "sha512-lPDGyC1JPDou8kGcywY0YILzWlhhnRjdof3UlcoqYmS9El818LLfJJc3PXXgZHrHCAKs/Z2SeZtDJr5MrkxtOw=="],
|
||||
|
||||
"@esbuild/linux-arm64": ["@esbuild/linux-arm64@0.25.12", "https://registry.npmmirror.com/@esbuild/linux-arm64/-/linux-arm64-0.25.12.tgz", { "os": "linux", "cpu": "arm64" }, "sha512-8bwX7a8FghIgrupcxb4aUmYDLp8pX06rGh5HqDT7bB+8Rdells6mHvrFHHW2JAOPZUbnjUpKTLg6ECyzvas2AQ=="],
|
||||
|
||||
"@esbuild/linux-ia32": ["@esbuild/linux-ia32@0.25.12", "https://registry.npmmirror.com/@esbuild/linux-ia32/-/linux-ia32-0.25.12.tgz", { "os": "linux", "cpu": "ia32" }, "sha512-0y9KrdVnbMM2/vG8KfU0byhUN+EFCny9+8g202gYqSSVMonbsCfLjUO+rCci7pM0WBEtz+oK/PIwHkzxkyharA=="],
|
||||
|
||||
"@esbuild/linux-loong64": ["@esbuild/linux-loong64@0.25.12", "https://registry.npmmirror.com/@esbuild/linux-loong64/-/linux-loong64-0.25.12.tgz", { "os": "linux", "cpu": "none" }, "sha512-h///Lr5a9rib/v1GGqXVGzjL4TMvVTv+s1DPoxQdz7l/AYv6LDSxdIwzxkrPW438oUXiDtwM10o9PmwS/6Z0Ng=="],
|
||||
|
||||
"@esbuild/linux-mips64el": ["@esbuild/linux-mips64el@0.25.12", "https://registry.npmmirror.com/@esbuild/linux-mips64el/-/linux-mips64el-0.25.12.tgz", { "os": "linux", "cpu": "none" }, "sha512-iyRrM1Pzy9GFMDLsXn1iHUm18nhKnNMWscjmp4+hpafcZjrr2WbT//d20xaGljXDBYHqRcl8HnxbX6uaA/eGVw=="],
|
||||
|
||||
"@esbuild/linux-ppc64": ["@esbuild/linux-ppc64@0.25.12", "https://registry.npmmirror.com/@esbuild/linux-ppc64/-/linux-ppc64-0.25.12.tgz", { "os": "linux", "cpu": "ppc64" }, "sha512-9meM/lRXxMi5PSUqEXRCtVjEZBGwB7P/D4yT8UG/mwIdze2aV4Vo6U5gD3+RsoHXKkHCfSxZKzmDssVlRj1QQA=="],
|
||||
|
||||
"@esbuild/linux-riscv64": ["@esbuild/linux-riscv64@0.25.12", "https://registry.npmmirror.com/@esbuild/linux-riscv64/-/linux-riscv64-0.25.12.tgz", { "os": "linux", "cpu": "none" }, "sha512-Zr7KR4hgKUpWAwb1f3o5ygT04MzqVrGEGXGLnj15YQDJErYu/BGg+wmFlIDOdJp0PmB0lLvxFIOXZgFRrdjR0w=="],
|
||||
|
||||
"@esbuild/linux-s390x": ["@esbuild/linux-s390x@0.25.12", "https://registry.npmmirror.com/@esbuild/linux-s390x/-/linux-s390x-0.25.12.tgz", { "os": "linux", "cpu": "s390x" }, "sha512-MsKncOcgTNvdtiISc/jZs/Zf8d0cl/t3gYWX8J9ubBnVOwlk65UIEEvgBORTiljloIWnBzLs4qhzPkJcitIzIg=="],
|
||||
|
||||
"@esbuild/linux-x64": ["@esbuild/linux-x64@0.25.12", "https://registry.npmmirror.com/@esbuild/linux-x64/-/linux-x64-0.25.12.tgz", { "os": "linux", "cpu": "x64" }, "sha512-uqZMTLr/zR/ed4jIGnwSLkaHmPjOjJvnm6TVVitAa08SLS9Z0VM8wIRx7gWbJB5/J54YuIMInDquWyYvQLZkgw=="],
|
||||
|
||||
"@esbuild/netbsd-arm64": ["@esbuild/netbsd-arm64@0.25.12", "https://registry.npmmirror.com/@esbuild/netbsd-arm64/-/netbsd-arm64-0.25.12.tgz", { "os": "none", "cpu": "arm64" }, "sha512-xXwcTq4GhRM7J9A8Gv5boanHhRa/Q9KLVmcyXHCTaM4wKfIpWkdXiMog/KsnxzJ0A1+nD+zoecuzqPmCRyBGjg=="],
|
||||
|
||||
"@esbuild/netbsd-x64": ["@esbuild/netbsd-x64@0.25.12", "https://registry.npmmirror.com/@esbuild/netbsd-x64/-/netbsd-x64-0.25.12.tgz", { "os": "none", "cpu": "x64" }, "sha512-Ld5pTlzPy3YwGec4OuHh1aCVCRvOXdH8DgRjfDy/oumVovmuSzWfnSJg+VtakB9Cm0gxNO9BzWkj6mtO1FMXkQ=="],
|
||||
|
||||
"@esbuild/openbsd-arm64": ["@esbuild/openbsd-arm64@0.25.12", "https://registry.npmmirror.com/@esbuild/openbsd-arm64/-/openbsd-arm64-0.25.12.tgz", { "os": "openbsd", "cpu": "arm64" }, "sha512-fF96T6KsBo/pkQI950FARU9apGNTSlZGsv1jZBAlcLL1MLjLNIWPBkj5NlSz8aAzYKg+eNqknrUJ24QBybeR5A=="],
|
||||
|
||||
"@esbuild/openbsd-x64": ["@esbuild/openbsd-x64@0.25.12", "https://registry.npmmirror.com/@esbuild/openbsd-x64/-/openbsd-x64-0.25.12.tgz", { "os": "openbsd", "cpu": "x64" }, "sha512-MZyXUkZHjQxUvzK7rN8DJ3SRmrVrke8ZyRusHlP+kuwqTcfWLyqMOE3sScPPyeIXN/mDJIfGXvcMqCgYKekoQw=="],
|
||||
|
||||
"@esbuild/openharmony-arm64": ["@esbuild/openharmony-arm64@0.25.12", "https://registry.npmmirror.com/@esbuild/openharmony-arm64/-/openharmony-arm64-0.25.12.tgz", { "os": "none", "cpu": "arm64" }, "sha512-rm0YWsqUSRrjncSXGA7Zv78Nbnw4XL6/dzr20cyrQf7ZmRcsovpcRBdhD43Nuk3y7XIoW2OxMVvwuRvk9XdASg=="],
|
||||
|
||||
"@esbuild/sunos-x64": ["@esbuild/sunos-x64@0.25.12", "https://registry.npmmirror.com/@esbuild/sunos-x64/-/sunos-x64-0.25.12.tgz", { "os": "sunos", "cpu": "x64" }, "sha512-3wGSCDyuTHQUzt0nV7bocDy72r2lI33QL3gkDNGkod22EsYl04sMf0qLb8luNKTOmgF/eDEDP5BFNwoBKH441w=="],
|
||||
|
||||
"@esbuild/win32-arm64": ["@esbuild/win32-arm64@0.25.12", "https://registry.npmmirror.com/@esbuild/win32-arm64/-/win32-arm64-0.25.12.tgz", { "os": "win32", "cpu": "arm64" }, "sha512-rMmLrur64A7+DKlnSuwqUdRKyd3UE7oPJZmnljqEptesKM8wx9J8gx5u0+9Pq0fQQW8vqeKebwNXdfOyP+8Bsg=="],
|
||||
|
||||
"@esbuild/win32-ia32": ["@esbuild/win32-ia32@0.25.12", "https://registry.npmmirror.com/@esbuild/win32-ia32/-/win32-ia32-0.25.12.tgz", { "os": "win32", "cpu": "ia32" }, "sha512-HkqnmmBoCbCwxUKKNPBixiWDGCpQGVsrQfJoVGYLPT41XWF8lHuE5N6WhVia2n4o5QK5M4tYr21827fNhi4byQ=="],
|
||||
|
||||
"@esbuild/win32-x64": ["@esbuild/win32-x64@0.25.12", "https://registry.npmmirror.com/@esbuild/win32-x64/-/win32-x64-0.25.12.tgz", { "os": "win32", "cpu": "x64" }, "sha512-alJC0uCZpTFrSL0CCDjcgleBXPnCrEAhTBILpeAp7M/OFgoqtAetfBzX0xM00MUsVVPpVjlPuMbREqnZCXaTnA=="],
|
||||
|
||||
"@fastify/otel": ["@fastify/otel@0.18.0", "https://registry.npmmirror.com/@fastify/otel/-/otel-0.18.0.tgz", { "dependencies": { "@opentelemetry/core": "^2.0.0", "@opentelemetry/instrumentation": "^0.212.0", "@opentelemetry/semantic-conventions": "^1.28.0", "minimatch": "^10.2.4" }, "peerDependencies": { "@opentelemetry/api": "^1.9.0" } }, "sha512-3TASCATfw+ctICSb4ymrv7iCm0qJ0N9CarB+CZ7zIJ7KqNbwI5JjyDL1/sxoC0ccTO1Zyd1iQ+oqncPg5FJXaA=="],
|
||||
|
||||
"@growthbook/growthbook": ["@growthbook/growthbook@1.6.5", "https://registry.npmmirror.com/@growthbook/growthbook/-/growthbook-1.6.5.tgz", { "dependencies": { "dom-mutator": "^0.6.0" } }, "sha512-mUaMsgeUTpRIUOTn33EUXHRK6j7pxBjwqH4WpQyq+pukjd1AIzWlEa6w7i6bInJUcweGgP2beXZmaP6b6UPn7A=="],
|
||||
|
||||
"@grpc/grpc-js": ["@grpc/grpc-js@1.14.3", "https://registry.npmmirror.com/@grpc/grpc-js/-/grpc-js-1.14.3.tgz", { "dependencies": { "@grpc/proto-loader": "^0.8.0", "@js-sdsl/ordered-map": "^4.4.2" } }, "sha512-Iq8QQQ/7X3Sac15oB6p0FmUg/klxQvXLeileoqrTRGJYLV+/9tubbr9ipz0GKHjmXVsgFPo/+W+2cA8eNcR+XA=="],
|
||||
@@ -544,16 +401,6 @@
|
||||
|
||||
"@inquirer/type": ["@inquirer/type@2.0.0", "https://registry.npmmirror.com/@inquirer/type/-/type-2.0.0.tgz", { "dependencies": { "mute-stream": "^1.0.0" } }, "sha512-XvJRx+2KR3YXyYtPUUy+qd9i7p+GO9Ko6VIIpWlBrpWwXDv8WLFeHTxz35CfQFUiBMLXlGHhGzys7lqit9gWag=="],
|
||||
|
||||
"@jridgewell/gen-mapping": ["@jridgewell/gen-mapping@0.3.13", "https://registry.npmmirror.com/@jridgewell/gen-mapping/-/gen-mapping-0.3.13.tgz", { "dependencies": { "@jridgewell/sourcemap-codec": "^1.5.0", "@jridgewell/trace-mapping": "^0.3.24" } }, "sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA=="],
|
||||
|
||||
"@jridgewell/remapping": ["@jridgewell/remapping@2.3.5", "https://registry.npmmirror.com/@jridgewell/remapping/-/remapping-2.3.5.tgz", { "dependencies": { "@jridgewell/gen-mapping": "^0.3.5", "@jridgewell/trace-mapping": "^0.3.24" } }, "sha512-LI9u/+laYG4Ds1TDKSJW2YPrIlcVYOwi2fUC6xB43lueCjgxV4lffOCZCtYFiH6TNOX+tQKXx97T4IKHbhyHEQ=="],
|
||||
|
||||
"@jridgewell/resolve-uri": ["@jridgewell/resolve-uri@3.1.2", "https://registry.npmmirror.com/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz", {}, "sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw=="],
|
||||
|
||||
"@jridgewell/sourcemap-codec": ["@jridgewell/sourcemap-codec@1.5.5", "https://registry.npmmirror.com/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz", {}, "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og=="],
|
||||
|
||||
"@jridgewell/trace-mapping": ["@jridgewell/trace-mapping@0.3.31", "https://registry.npmmirror.com/@jridgewell/trace-mapping/-/trace-mapping-0.3.31.tgz", { "dependencies": { "@jridgewell/resolve-uri": "^3.1.0", "@jridgewell/sourcemap-codec": "^1.4.14" } }, "sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw=="],
|
||||
|
||||
"@js-sdsl/ordered-map": ["@js-sdsl/ordered-map@4.4.2", "https://registry.npmmirror.com/@js-sdsl/ordered-map/-/ordered-map-4.4.2.tgz", {}, "sha512-iUKgm52T8HOE/makSxjqoWhe95ZJA1/G1sYsGev2JDKUSS14KAgg1LHb+Ba+IPow0xflbnSkOsZcO08C7w1gYw=="],
|
||||
|
||||
"@mixmark-io/domino": ["@mixmark-io/domino@2.2.0", "https://registry.npmmirror.com/@mixmark-io/domino/-/domino-2.2.0.tgz", {}, "sha512-Y28PR25bHXUg88kCV7nivXrP2Nj2RueZ3/l/jdx6J9f8J4nsEGcgX0Qe6lt7Pa+J79+kPiJU3LguR6O/6zrLOw=="],
|
||||
@@ -574,8 +421,6 @@
|
||||
|
||||
"@opentelemetry/api-logs": ["@opentelemetry/api-logs@0.214.0", "https://registry.npmmirror.com/@opentelemetry/api-logs/-/api-logs-0.214.0.tgz", { "dependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-40lSJeqYO8Uz2Yj7u94/SJWE/wONa7rmMKjI1ZcIjgf3MHNHv1OZUCrCETGuaRF62d5pQD1wKIW+L4lmSMTzZA=="],
|
||||
|
||||
"@opentelemetry/context-async-hooks": ["@opentelemetry/context-async-hooks@2.6.1", "https://registry.npmmirror.com/@opentelemetry/context-async-hooks/-/context-async-hooks-2.6.1.tgz", { "peerDependencies": { "@opentelemetry/api": ">=1.0.0 <1.10.0" } }, "sha512-XHzhwRNkBpeP8Fs/qjGrAf9r9PRv67wkJQ/7ZPaBQQ68DYlTBBx5MF9LvPx7mhuXcDessKK2b+DcxqwpgkcivQ=="],
|
||||
|
||||
"@opentelemetry/core": ["@opentelemetry/core@2.6.1", "https://registry.npmmirror.com/@opentelemetry/core/-/core-2.6.1.tgz", { "dependencies": { "@opentelemetry/semantic-conventions": "^1.29.0" }, "peerDependencies": { "@opentelemetry/api": ">=1.0.0 <1.10.0" } }, "sha512-8xHSGWpJP9wBxgBpnqGL0R3PbdWQndL1Qp50qrg71+B28zK5OQmUgcDKLJgzyAAV38t4tOyLMGDD60LneR5W8g=="],
|
||||
|
||||
"@opentelemetry/exporter-logs-otlp-grpc": ["@opentelemetry/exporter-logs-otlp-grpc@0.214.0", "https://registry.npmmirror.com/@opentelemetry/exporter-logs-otlp-grpc/-/exporter-logs-otlp-grpc-0.214.0.tgz", { "dependencies": { "@grpc/grpc-js": "^1.14.3", "@opentelemetry/core": "2.6.1", "@opentelemetry/otlp-exporter-base": "0.214.0", "@opentelemetry/otlp-grpc-exporter-base": "0.214.0", "@opentelemetry/otlp-transformer": "0.214.0", "@opentelemetry/sdk-logs": "0.214.0" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-SwmFRwO8mi6nndzbsjPgSFg7qy1WeNHRFD+s6uCsdiUDUt3+yzI2qiHE3/ub2f37+/CbeGcG+Ugc8Gwr6nu2Aw=="],
|
||||
@@ -598,60 +443,12 @@
|
||||
|
||||
"@opentelemetry/exporter-trace-otlp-proto": ["@opentelemetry/exporter-trace-otlp-proto@0.214.0", "https://registry.npmmirror.com/@opentelemetry/exporter-trace-otlp-proto/-/exporter-trace-otlp-proto-0.214.0.tgz", { "dependencies": { "@opentelemetry/core": "2.6.1", "@opentelemetry/otlp-exporter-base": "0.214.0", "@opentelemetry/otlp-transformer": "0.214.0", "@opentelemetry/resources": "2.6.1", "@opentelemetry/sdk-trace-base": "2.6.1" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-ON0spYWb2yAdQ9b+ItNyK0c6qdtcs+0eVR4YFJkhJL7agfT8sHFg0e5EesauSRiTHPZHiDobI92k77q0lwAmqg=="],
|
||||
|
||||
"@opentelemetry/instrumentation": ["@opentelemetry/instrumentation@0.214.0", "https://registry.npmmirror.com/@opentelemetry/instrumentation/-/instrumentation-0.214.0.tgz", { "dependencies": { "@opentelemetry/api-logs": "0.214.0", "import-in-the-middle": "^3.0.0", "require-in-the-middle": "^8.0.0" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-MHqEX5Dk59cqVah5LiARMACku7jXSVk9iVDWOea4x3cr7VfdByeDCURK6o1lntT1JS/Tsovw01UJrBhN3/uC5w=="],
|
||||
|
||||
"@opentelemetry/instrumentation-amqplib": ["@opentelemetry/instrumentation-amqplib@0.61.0", "https://registry.npmmirror.com/@opentelemetry/instrumentation-amqplib/-/instrumentation-amqplib-0.61.0.tgz", { "dependencies": { "@opentelemetry/core": "^2.0.0", "@opentelemetry/instrumentation": "^0.214.0", "@opentelemetry/semantic-conventions": "^1.33.0" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-mCKoyTGfRNisge4br0NpOFSy2Z1NnEW8hbCJdUDdJFHrPqVzc4IIBPA/vX0U+LUcQqrQvJX+HMIU0dbDRe0i0Q=="],
|
||||
|
||||
"@opentelemetry/instrumentation-connect": ["@opentelemetry/instrumentation-connect@0.57.0", "https://registry.npmmirror.com/@opentelemetry/instrumentation-connect/-/instrumentation-connect-0.57.0.tgz", { "dependencies": { "@opentelemetry/core": "^2.0.0", "@opentelemetry/instrumentation": "^0.214.0", "@opentelemetry/semantic-conventions": "^1.27.0", "@types/connect": "3.4.38" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-FMEBChnI4FLN5TE9DHwfH7QpNir1JzXno1uz/TAucVdLCyrG0jTrKIcNHt/i30A0M2AunNBCkcd8Ei26dIPKdg=="],
|
||||
|
||||
"@opentelemetry/instrumentation-dataloader": ["@opentelemetry/instrumentation-dataloader@0.31.0", "https://registry.npmmirror.com/@opentelemetry/instrumentation-dataloader/-/instrumentation-dataloader-0.31.0.tgz", { "dependencies": { "@opentelemetry/instrumentation": "^0.214.0" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-f654tZFQXS5YeLDNb9KySrwtg7SnqZN119FauD7acBoTzuLduaiGTNz88ixcVSOOMGZ+EjJu/RFtx5klObC95g=="],
|
||||
|
||||
"@opentelemetry/instrumentation-express": ["@opentelemetry/instrumentation-express@0.62.0", "https://registry.npmmirror.com/@opentelemetry/instrumentation-express/-/instrumentation-express-0.62.0.tgz", { "dependencies": { "@opentelemetry/core": "^2.0.0", "@opentelemetry/instrumentation": "^0.214.0", "@opentelemetry/semantic-conventions": "^1.27.0" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-Tvx+vgAZKEQxU3Rx+xWLiR0mLxHwmk69/8ya04+VsV9WYh8w6Lhx5hm5yAMvo1wy0KqWgFKBLwSeo3sHCwdOww=="],
|
||||
|
||||
"@opentelemetry/instrumentation-fs": ["@opentelemetry/instrumentation-fs@0.33.0", "https://registry.npmmirror.com/@opentelemetry/instrumentation-fs/-/instrumentation-fs-0.33.0.tgz", { "dependencies": { "@opentelemetry/core": "^2.0.0", "@opentelemetry/instrumentation": "^0.214.0" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-sCZWXGalQ01wr3tAhSR9ucqFJ0phidpAle6/17HVjD6gN8FLmZMK/8sKxdXYHy3PbnlV1P4zeiSVFNKpbFMNLA=="],
|
||||
|
||||
"@opentelemetry/instrumentation-generic-pool": ["@opentelemetry/instrumentation-generic-pool@0.57.0", "https://registry.npmmirror.com/@opentelemetry/instrumentation-generic-pool/-/instrumentation-generic-pool-0.57.0.tgz", { "dependencies": { "@opentelemetry/instrumentation": "^0.214.0" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-orhmlaK+ZIW9hKU+nHTbXrCSXZcH83AescTqmpamHRobRmYSQwRbD0a1odc0yAzuzOtxYiHiXAnpnIpaSSY7Ow=="],
|
||||
|
||||
"@opentelemetry/instrumentation-graphql": ["@opentelemetry/instrumentation-graphql@0.62.0", "https://registry.npmmirror.com/@opentelemetry/instrumentation-graphql/-/instrumentation-graphql-0.62.0.tgz", { "dependencies": { "@opentelemetry/instrumentation": "^0.214.0" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-3YNuLVPUxafXkH1jBAbGsKNsP3XVzcFDhCDCE3OqBwCwShlqQbLMRMFh1T/d5jaVZiGVmSsfof+ICKD2iOV8xg=="],
|
||||
|
||||
"@opentelemetry/instrumentation-hapi": ["@opentelemetry/instrumentation-hapi@0.60.0", "https://registry.npmmirror.com/@opentelemetry/instrumentation-hapi/-/instrumentation-hapi-0.60.0.tgz", { "dependencies": { "@opentelemetry/core": "^2.0.0", "@opentelemetry/instrumentation": "^0.214.0", "@opentelemetry/semantic-conventions": "^1.27.0" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-aNljZKYrEa7obLAxd1bCEDxF7kzCLGXTuTJZ8lMR9rIVEjmuKBXN1gfqpm/OB//Zc2zP4iIve1jBp7sr3mQV6w=="],
|
||||
|
||||
"@opentelemetry/instrumentation-http": ["@opentelemetry/instrumentation-http@0.214.0", "https://registry.npmmirror.com/@opentelemetry/instrumentation-http/-/instrumentation-http-0.214.0.tgz", { "dependencies": { "@opentelemetry/core": "2.6.1", "@opentelemetry/instrumentation": "0.214.0", "@opentelemetry/semantic-conventions": "^1.29.0", "forwarded-parse": "2.1.2" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-FlkDhZDRjDJDcO2LcSCtjRpkal1NJ8y0fBqBhTvfAR3JSYY2jAIj1kSS5IjmEBt4c3aWv+u/lqLuoCDrrKCSKg=="],
|
||||
|
||||
"@opentelemetry/instrumentation-ioredis": ["@opentelemetry/instrumentation-ioredis@0.62.0", "https://registry.npmmirror.com/@opentelemetry/instrumentation-ioredis/-/instrumentation-ioredis-0.62.0.tgz", { "dependencies": { "@opentelemetry/instrumentation": "^0.214.0", "@opentelemetry/redis-common": "^0.38.2", "@opentelemetry/semantic-conventions": "^1.33.0" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-ZYt//zcPve8qklaZX+5Z4MkU7UpEkFRrxsf2cnaKYBitqDnsCN69CPAuuMOX6NYdW2rG9sFy7V/QWtBlP5XiNQ=="],
|
||||
|
||||
"@opentelemetry/instrumentation-kafkajs": ["@opentelemetry/instrumentation-kafkajs@0.23.0", "https://registry.npmmirror.com/@opentelemetry/instrumentation-kafkajs/-/instrumentation-kafkajs-0.23.0.tgz", { "dependencies": { "@opentelemetry/instrumentation": "^0.214.0", "@opentelemetry/semantic-conventions": "^1.30.0" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-4K+nVo+zI+aDz0Z85SObwbdixIbzS9moIuKJaYsdlzcHYnKOPtB7ya8r8Ezivy/GVIBHiKJVq4tv+BEkgOMLaQ=="],
|
||||
|
||||
"@opentelemetry/instrumentation-knex": ["@opentelemetry/instrumentation-knex@0.58.0", "https://registry.npmmirror.com/@opentelemetry/instrumentation-knex/-/instrumentation-knex-0.58.0.tgz", { "dependencies": { "@opentelemetry/instrumentation": "^0.214.0", "@opentelemetry/semantic-conventions": "^1.33.1" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-Hc/o8fSsaWxZ8r1Yw4rNDLwTpUopTf4X32y4W6UhlHmW8Wizz8wfhgOKIelSeqFVTKBBPIDUOsQWuIMxBmu8Bw=="],
|
||||
|
||||
"@opentelemetry/instrumentation-koa": ["@opentelemetry/instrumentation-koa@0.62.0", "https://registry.npmmirror.com/@opentelemetry/instrumentation-koa/-/instrumentation-koa-0.62.0.tgz", { "dependencies": { "@opentelemetry/core": "^2.0.0", "@opentelemetry/instrumentation": "^0.214.0", "@opentelemetry/semantic-conventions": "^1.36.0" }, "peerDependencies": { "@opentelemetry/api": "^1.9.0" } }, "sha512-uVip0VuGUQXZ+vFxkKxAUNq8qNl+VFlyHDh/U6IQ8COOEDfbEchdaHnpFrMYF3psZRUuoSIgb7xOeXj00RdwDA=="],
|
||||
|
||||
"@opentelemetry/instrumentation-lru-memoizer": ["@opentelemetry/instrumentation-lru-memoizer@0.58.0", "https://registry.npmmirror.com/@opentelemetry/instrumentation-lru-memoizer/-/instrumentation-lru-memoizer-0.58.0.tgz", { "dependencies": { "@opentelemetry/instrumentation": "^0.214.0" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-6grM3TdMyHzlGY1cUA+mwoPueB1F3dYKgKtZIH6jOFXqfHAByyLTc+6PFjGM9tKh52CFBJaDwodNlL/Td39z7Q=="],
|
||||
|
||||
"@opentelemetry/instrumentation-mongodb": ["@opentelemetry/instrumentation-mongodb@0.67.0", "https://registry.npmmirror.com/@opentelemetry/instrumentation-mongodb/-/instrumentation-mongodb-0.67.0.tgz", { "dependencies": { "@opentelemetry/instrumentation": "^0.214.0", "@opentelemetry/semantic-conventions": "^1.33.0" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-1WJp5N1lYfHq2IhECOTewFs5Tf2NfUOwQRqs/rZdXKTezArMlucxgzAaqcgp3A3YREXopXTpXHsxZTGHjNhMdQ=="],
|
||||
|
||||
"@opentelemetry/instrumentation-mongoose": ["@opentelemetry/instrumentation-mongoose@0.60.0", "https://registry.npmmirror.com/@opentelemetry/instrumentation-mongoose/-/instrumentation-mongoose-0.60.0.tgz", { "dependencies": { "@opentelemetry/core": "^2.0.0", "@opentelemetry/instrumentation": "^0.214.0", "@opentelemetry/semantic-conventions": "^1.33.0" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-8BahAZpKsOoc+lrZGb7Ofn4g3z8qtp5IxDfvAVpKXsEheQN7ONMH5djT5ihy6yf8yyeQJGS0gXFfpEAEeEHqQg=="],
|
||||
|
||||
"@opentelemetry/instrumentation-mysql": ["@opentelemetry/instrumentation-mysql@0.60.0", "https://registry.npmmirror.com/@opentelemetry/instrumentation-mysql/-/instrumentation-mysql-0.60.0.tgz", { "dependencies": { "@opentelemetry/instrumentation": "^0.214.0", "@opentelemetry/semantic-conventions": "^1.33.0", "@types/mysql": "2.15.27" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-08pO8GFPEIz2zquKDGteBZDNmwketdgH8hTe9rVYgW9kCJXq1Psj3wPQGx+VaX4ZJKCfPeoLMYup9+cxHvZyVQ=="],
|
||||
|
||||
"@opentelemetry/instrumentation-mysql2": ["@opentelemetry/instrumentation-mysql2@0.60.0", "https://registry.npmmirror.com/@opentelemetry/instrumentation-mysql2/-/instrumentation-mysql2-0.60.0.tgz", { "dependencies": { "@opentelemetry/instrumentation": "^0.214.0", "@opentelemetry/semantic-conventions": "^1.33.0", "@opentelemetry/sql-common": "^0.41.2" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-m/5d3bxQALllCzezYDk/6vajh0tj5OijMMvOZGr+qN1NMXm1dzMNwyJ0gNZW7Fo3YFRyj/jJMxIw+W7d525dlw=="],
|
||||
|
||||
"@opentelemetry/instrumentation-pg": ["@opentelemetry/instrumentation-pg@0.66.0", "https://registry.npmmirror.com/@opentelemetry/instrumentation-pg/-/instrumentation-pg-0.66.0.tgz", { "dependencies": { "@opentelemetry/core": "^2.0.0", "@opentelemetry/instrumentation": "^0.214.0", "@opentelemetry/semantic-conventions": "^1.34.0", "@opentelemetry/sql-common": "^0.41.2", "@types/pg": "8.15.6", "@types/pg-pool": "2.0.7" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-KxfLGXBb7k2ueaPJfq2GXBDXBly8P+SpR/4Mj410hhNgmQF3sCqwXvUBQxZQkDAmsdBAoenM+yV1LhtsMRamcA=="],
|
||||
|
||||
"@opentelemetry/instrumentation-redis": ["@opentelemetry/instrumentation-redis@0.62.0", "https://registry.npmmirror.com/@opentelemetry/instrumentation-redis/-/instrumentation-redis-0.62.0.tgz", { "dependencies": { "@opentelemetry/instrumentation": "^0.214.0", "@opentelemetry/redis-common": "^0.38.2", "@opentelemetry/semantic-conventions": "^1.27.0" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-y3pPpot7WzR/8JtHcYlTYsyY8g+pbFhAqbwAuG5bLPnR6v6pt1rQc0DpH0OlGP/9CZbWBP+Zhwp9yFoygf/ZXQ=="],
|
||||
|
||||
"@opentelemetry/instrumentation-tedious": ["@opentelemetry/instrumentation-tedious@0.33.0", "https://registry.npmmirror.com/@opentelemetry/instrumentation-tedious/-/instrumentation-tedious-0.33.0.tgz", { "dependencies": { "@opentelemetry/instrumentation": "^0.214.0", "@opentelemetry/semantic-conventions": "^1.33.0", "@types/tedious": "^4.0.14" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-Q6WQwAD01MMTub31GlejoiFACYNw26J426wyjvU7by7fDIr2nZXNW4vhTGs7i7F0TnXBO3xN688g1tdUgYwJ5w=="],
|
||||
|
||||
"@opentelemetry/instrumentation-undici": ["@opentelemetry/instrumentation-undici@0.24.0", "https://registry.npmmirror.com/@opentelemetry/instrumentation-undici/-/instrumentation-undici-0.24.0.tgz", { "dependencies": { "@opentelemetry/core": "^2.0.0", "@opentelemetry/instrumentation": "^0.214.0", "@opentelemetry/semantic-conventions": "^1.24.0" }, "peerDependencies": { "@opentelemetry/api": "^1.7.0" } }, "sha512-oKzZ3uvqP17sV0EsoQcJgjEfIp0kiZRbYu/eD8p13Cbahumf8lb/xpYeNr/hfAJ4owzEtIDcGIjprfLcYbIKBQ=="],
|
||||
|
||||
"@opentelemetry/otlp-exporter-base": ["@opentelemetry/otlp-exporter-base@0.214.0", "https://registry.npmmirror.com/@opentelemetry/otlp-exporter-base/-/otlp-exporter-base-0.214.0.tgz", { "dependencies": { "@opentelemetry/core": "2.6.1", "@opentelemetry/otlp-transformer": "0.214.0" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-u1Gdv0/E9wP+apqWf7Wv2npXmgJtxsW2XL0TEv9FZloTZRuMBKmu8cYVXwS4Hm3q/f/3FuCnPTgiwYvIqRSpRg=="],
|
||||
|
||||
"@opentelemetry/otlp-grpc-exporter-base": ["@opentelemetry/otlp-grpc-exporter-base@0.214.0", "https://registry.npmmirror.com/@opentelemetry/otlp-grpc-exporter-base/-/otlp-grpc-exporter-base-0.214.0.tgz", { "dependencies": { "@grpc/grpc-js": "^1.14.3", "@opentelemetry/core": "2.6.1", "@opentelemetry/otlp-exporter-base": "0.214.0", "@opentelemetry/otlp-transformer": "0.214.0" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-IDP6zcyA24RhNZ289MP6eToIZcinlmirHjX8v3zKCQ2ZhPpt5cGwkN91tCth337lqHIgWcTy90uKRiX/SzALDw=="],
|
||||
|
||||
"@opentelemetry/otlp-transformer": ["@opentelemetry/otlp-transformer@0.214.0", "https://registry.npmmirror.com/@opentelemetry/otlp-transformer/-/otlp-transformer-0.214.0.tgz", { "dependencies": { "@opentelemetry/api-logs": "0.214.0", "@opentelemetry/core": "2.6.1", "@opentelemetry/resources": "2.6.1", "@opentelemetry/sdk-logs": "0.214.0", "@opentelemetry/sdk-metrics": "2.6.1", "@opentelemetry/sdk-trace-base": "2.6.1", "protobufjs": "^7.0.0" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-DSaYcuBRh6uozfsWN3R8HsN0yDhCuWP7tOFdkUOVaWD1KVJg8m4qiLUsg/tNhTLS9HUYUcwNpwL2eroLtsZZ/w=="],
|
||||
|
||||
"@opentelemetry/redis-common": ["@opentelemetry/redis-common@0.38.2", "https://registry.npmmirror.com/@opentelemetry/redis-common/-/redis-common-0.38.2.tgz", {}, "sha512-1BCcU93iwSRZvDAgwUxC/DV4T/406SkMfxGqu5ojc3AvNI+I9GhV7v0J1HljsczuuhcnFLYqD5VmwVXfCGHzxA=="],
|
||||
|
||||
"@opentelemetry/resources": ["@opentelemetry/resources@2.6.1", "https://registry.npmmirror.com/@opentelemetry/resources/-/resources-2.6.1.tgz", { "dependencies": { "@opentelemetry/core": "2.6.1", "@opentelemetry/semantic-conventions": "^1.29.0" }, "peerDependencies": { "@opentelemetry/api": ">=1.3.0 <1.10.0" } }, "sha512-lID/vxSuKWXM55XhAKNoYXu9Cutoq5hFdkbTdI/zDKQktXzcWBVhNsOkiZFTMU9UtEWuGRNe0HUgmsFldIdxVA=="],
|
||||
|
||||
"@opentelemetry/sdk-logs": ["@opentelemetry/sdk-logs@0.214.0", "https://registry.npmmirror.com/@opentelemetry/sdk-logs/-/sdk-logs-0.214.0.tgz", { "dependencies": { "@opentelemetry/api-logs": "0.214.0", "@opentelemetry/core": "2.6.1", "@opentelemetry/resources": "2.6.1", "@opentelemetry/semantic-conventions": "^1.29.0" }, "peerDependencies": { "@opentelemetry/api": ">=1.4.0 <1.10.0" } }, "sha512-zf6acnScjhsaBUU22zXZ/sLWim1dfhUAbGXdMmHmNG3LfBnQ3DKsOCITb2IZwoUsNNMTogqFKBnlIPPftUgGwA=="],
|
||||
@@ -662,8 +459,6 @@
|
||||
|
||||
"@opentelemetry/semantic-conventions": ["@opentelemetry/semantic-conventions@1.40.0", "https://registry.npmmirror.com/@opentelemetry/semantic-conventions/-/semantic-conventions-1.40.0.tgz", {}, "sha512-cifvXDhcqMwwTlTK04GBNeIe7yyo28Mfby85QXFe1Yk8nmi36Ab/5UQwptOx84SsoGNRg+EVSjwzfSZMy6pmlw=="],
|
||||
|
||||
"@opentelemetry/sql-common": ["@opentelemetry/sql-common@0.41.2", "https://registry.npmmirror.com/@opentelemetry/sql-common/-/sql-common-0.41.2.tgz", { "dependencies": { "@opentelemetry/core": "^2.0.0" }, "peerDependencies": { "@opentelemetry/api": "^1.1.0" } }, "sha512-4mhWm3Z8z+i508zQJ7r6Xi7y4mmoJpdvH0fZPFRkWrdp5fq7hhZ2HhYokEOLkfqSMgPR4Z9EyB3DBkbKGOqZiQ=="],
|
||||
|
||||
"@oxc-parser/binding-android-arm-eabi": ["@oxc-parser/binding-android-arm-eabi@0.121.0", "https://registry.npmmirror.com/@oxc-parser/binding-android-arm-eabi/-/binding-android-arm-eabi-0.121.0.tgz", { "os": "android", "cpu": "arm" }, "sha512-n07FQcySwOlzap424/PLMtOkbS7xOu8nsJduKL8P3COGHKgKoDYXwoAHCbChfgFpHnviehrLWIPX0lKGtbEk/A=="],
|
||||
|
||||
"@oxc-parser/binding-android-arm64": ["@oxc-parser/binding-android-arm64@0.121.0", "https://registry.npmmirror.com/@oxc-parser/binding-android-arm64/-/binding-android-arm64-0.121.0.tgz", { "os": "android", "cpu": "arm64" }, "sha512-/Dd1xIXboYAicw+twT2utxPD7bL8qh7d3ej0qvaYIMj3/EgIrGR+tSnjCUkiCT6g6uTC0neSS4JY8LxhdSU/sA=="],
|
||||
@@ -748,8 +543,6 @@
|
||||
|
||||
"@pondwader/socks5-server": ["@pondwader/socks5-server@1.0.10", "https://registry.npmmirror.com/@pondwader/socks5-server/-/socks5-server-1.0.10.tgz", {}, "sha512-bQY06wzzR8D2+vVCUoBsr5QS2U6UgPUQRmErNwtsuI6vLcyRKkafjkr3KxbtGFf9aBBIV2mcvlsKD1UYaIV+sg=="],
|
||||
|
||||
"@prisma/instrumentation": ["@prisma/instrumentation@7.6.0", "https://registry.npmmirror.com/@prisma/instrumentation/-/instrumentation-7.6.0.tgz", { "dependencies": { "@opentelemetry/instrumentation": "^0.207.0" }, "peerDependencies": { "@opentelemetry/api": "^1.8" } }, "sha512-ZPW2gRiwpPzEfgeZgaekhqXrbW+Y2RJKHVqUmlhZhKzRNCcvR6DykzylDrynpArKKRQtLxoZy36fK7U0p3pdgQ=="],
|
||||
|
||||
"@protobufjs/aspromise": ["@protobufjs/aspromise@1.1.2", "https://registry.npmmirror.com/@protobufjs/aspromise/-/aspromise-1.1.2.tgz", {}, "sha512-j+gKExEuLmKwvz3OgROXtrJ2UG2x8Ch2YZUxahh+s1F2HZ+wAceUNLkvy6zKCPVRkU++ZWQrdxsUeQXmcg4uoQ=="],
|
||||
|
||||
"@protobufjs/base64": ["@protobufjs/base64@1.1.2", "https://registry.npmmirror.com/@protobufjs/base64/-/base64-1.1.2.tgz", {}, "sha512-AZkcAA5vnN/v4PDqKyMR5lx7hZttPDgClv83E//FMNhR2TMcLUhfRUBHCmSl0oi9zMgDDqRUJkSxO3wm85+XLg=="],
|
||||
@@ -770,68 +563,8 @@
|
||||
|
||||
"@protobufjs/utf8": ["@protobufjs/utf8@1.1.0", "https://registry.npmmirror.com/@protobufjs/utf8/-/utf8-1.1.0.tgz", {}, "sha512-Vvn3zZrhQZkkBE8LSuW3em98c0FwgO4nxzv6OdSxPKJIEKY2bGbHn+mhGIPerzI4twdxaP8/0+06HBpwf345Lw=="],
|
||||
|
||||
"@rolldown/pluginutils": ["@rolldown/pluginutils@1.0.0-beta.27", "https://registry.npmmirror.com/@rolldown/pluginutils/-/pluginutils-1.0.0-beta.27.tgz", {}, "sha512-+d0F4MKMCbeVUJwG96uQ4SgAznZNSq93I3V+9NHA4OpvqG8mRCpGdKmK8l/dl02h2CCDHwW2FqilnTyDcAnqjA=="],
|
||||
|
||||
"@rollup/rollup-android-arm-eabi": ["@rollup/rollup-android-arm-eabi@4.60.1", "https://registry.npmmirror.com/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.60.1.tgz", { "os": "android", "cpu": "arm" }, "sha512-d6FinEBLdIiK+1uACUttJKfgZREXrF0Qc2SmLII7W2AD8FfiZ9Wjd+rD/iRuf5s5dWrr1GgwXCvPqOuDquOowA=="],
|
||||
|
||||
"@rollup/rollup-android-arm64": ["@rollup/rollup-android-arm64@4.60.1", "https://registry.npmmirror.com/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.60.1.tgz", { "os": "android", "cpu": "arm64" }, "sha512-YjG/EwIDvvYI1YvYbHvDz/BYHtkY4ygUIXHnTdLhG+hKIQFBiosfWiACWortsKPKU/+dUwQQCKQM3qrDe8c9BA=="],
|
||||
|
||||
"@rollup/rollup-darwin-arm64": ["@rollup/rollup-darwin-arm64@4.60.1", "https://registry.npmmirror.com/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.60.1.tgz", { "os": "darwin", "cpu": "arm64" }, "sha512-mjCpF7GmkRtSJwon+Rq1N8+pI+8l7w5g9Z3vWj4T7abguC4Czwi3Yu/pFaLvA3TTeMVjnu3ctigusqWUfjZzvw=="],
|
||||
|
||||
"@rollup/rollup-darwin-x64": ["@rollup/rollup-darwin-x64@4.60.1", "https://registry.npmmirror.com/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.60.1.tgz", { "os": "darwin", "cpu": "x64" }, "sha512-haZ7hJ1JT4e9hqkoT9R/19XW2QKqjfJVv+i5AGg57S+nLk9lQnJ1F/eZloRO3o9Scy9CM3wQ9l+dkXtcBgN5Ew=="],
|
||||
|
||||
"@rollup/rollup-freebsd-arm64": ["@rollup/rollup-freebsd-arm64@4.60.1", "https://registry.npmmirror.com/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.60.1.tgz", { "os": "freebsd", "cpu": "arm64" }, "sha512-czw90wpQq3ZsAVBlinZjAYTKduOjTywlG7fEeWKUA7oCmpA8xdTkxZZlwNJKWqILlq0wehoZcJYfBvOyhPTQ6w=="],
|
||||
|
||||
"@rollup/rollup-freebsd-x64": ["@rollup/rollup-freebsd-x64@4.60.1", "https://registry.npmmirror.com/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.60.1.tgz", { "os": "freebsd", "cpu": "x64" }, "sha512-KVB2rqsxTHuBtfOeySEyzEOB7ltlB/ux38iu2rBQzkjbwRVlkhAGIEDiiYnO2kFOkJp+Z7pUXKyrRRFuFUKt+g=="],
|
||||
|
||||
"@rollup/rollup-linux-arm-gnueabihf": ["@rollup/rollup-linux-arm-gnueabihf@4.60.1", "https://registry.npmmirror.com/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.60.1.tgz", { "os": "linux", "cpu": "arm" }, "sha512-L+34Qqil+v5uC0zEubW7uByo78WOCIrBvci69E7sFASRl0X7b/MB6Cqd1lky/CtcSVTydWa2WZwFuWexjS5o6g=="],
|
||||
|
||||
"@rollup/rollup-linux-arm-musleabihf": ["@rollup/rollup-linux-arm-musleabihf@4.60.1", "https://registry.npmmirror.com/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.60.1.tgz", { "os": "linux", "cpu": "arm" }, "sha512-n83O8rt4v34hgFzlkb1ycniJh7IR5RCIqt6mz1VRJD6pmhRi0CXdmfnLu9dIUS6buzh60IvACM842Ffb3xd6Gg=="],
|
||||
|
||||
"@rollup/rollup-linux-arm64-gnu": ["@rollup/rollup-linux-arm64-gnu@4.60.1", "https://registry.npmmirror.com/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.60.1.tgz", { "os": "linux", "cpu": "arm64" }, "sha512-Nql7sTeAzhTAja3QXeAI48+/+GjBJ+QmAH13snn0AJSNL50JsDqotyudHyMbO2RbJkskbMbFJfIJKWA6R1LCJQ=="],
|
||||
|
||||
"@rollup/rollup-linux-arm64-musl": ["@rollup/rollup-linux-arm64-musl@4.60.1", "https://registry.npmmirror.com/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.60.1.tgz", { "os": "linux", "cpu": "arm64" }, "sha512-+pUymDhd0ys9GcKZPPWlFiZ67sTWV5UU6zOJat02M1+PiuSGDziyRuI/pPue3hoUwm2uGfxdL+trT6Z9rxnlMA=="],
|
||||
|
||||
"@rollup/rollup-linux-loong64-gnu": ["@rollup/rollup-linux-loong64-gnu@4.60.1", "https://registry.npmmirror.com/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.60.1.tgz", { "os": "linux", "cpu": "none" }, "sha512-VSvgvQeIcsEvY4bKDHEDWcpW4Yw7BtlKG1GUT4FzBUlEKQK0rWHYBqQt6Fm2taXS+1bXvJT6kICu5ZwqKCnvlQ=="],
|
||||
|
||||
"@rollup/rollup-linux-loong64-musl": ["@rollup/rollup-linux-loong64-musl@4.60.1", "https://registry.npmmirror.com/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.60.1.tgz", { "os": "linux", "cpu": "none" }, "sha512-4LqhUomJqwe641gsPp6xLfhqWMbQV04KtPp7/dIp0nzPxAkNY1AbwL5W0MQpcalLYk07vaW9Kp1PBhdpZYYcEw=="],
|
||||
|
||||
"@rollup/rollup-linux-ppc64-gnu": ["@rollup/rollup-linux-ppc64-gnu@4.60.1", "https://registry.npmmirror.com/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.60.1.tgz", { "os": "linux", "cpu": "ppc64" }, "sha512-tLQQ9aPvkBxOc/EUT6j3pyeMD6Hb8QF2BTBnCQWP/uu1lhc9AIrIjKnLYMEroIz/JvtGYgI9dF3AxHZNaEH0rw=="],
|
||||
|
||||
"@rollup/rollup-linux-ppc64-musl": ["@rollup/rollup-linux-ppc64-musl@4.60.1", "https://registry.npmmirror.com/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.60.1.tgz", { "os": "linux", "cpu": "ppc64" }, "sha512-RMxFhJwc9fSXP6PqmAz4cbv3kAyvD1etJFjTx4ONqFP9DkTkXsAMU4v3Vyc5BgzC+anz7nS/9tp4obsKfqkDHg=="],
|
||||
|
||||
"@rollup/rollup-linux-riscv64-gnu": ["@rollup/rollup-linux-riscv64-gnu@4.60.1", "https://registry.npmmirror.com/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.60.1.tgz", { "os": "linux", "cpu": "none" }, "sha512-QKgFl+Yc1eEk6MmOBfRHYF6lTxiiiV3/z/BRrbSiW2I7AFTXoBFvdMEyglohPj//2mZS4hDOqeB0H1ACh3sBbg=="],
|
||||
|
||||
"@rollup/rollup-linux-riscv64-musl": ["@rollup/rollup-linux-riscv64-musl@4.60.1", "https://registry.npmmirror.com/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.60.1.tgz", { "os": "linux", "cpu": "none" }, "sha512-RAjXjP/8c6ZtzatZcA1RaQr6O1TRhzC+adn8YZDnChliZHviqIjmvFwHcxi4JKPSDAt6Uhf/7vqcBzQJy0PDJg=="],
|
||||
|
||||
"@rollup/rollup-linux-s390x-gnu": ["@rollup/rollup-linux-s390x-gnu@4.60.1", "https://registry.npmmirror.com/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.60.1.tgz", { "os": "linux", "cpu": "s390x" }, "sha512-wcuocpaOlaL1COBYiA89O6yfjlp3RwKDeTIA0hM7OpmhR1Bjo9j31G1uQVpDlTvwxGn2nQs65fBFL5UFd76FcQ=="],
|
||||
|
||||
"@rollup/rollup-linux-x64-gnu": ["@rollup/rollup-linux-x64-gnu@4.60.1", "https://registry.npmmirror.com/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.60.1.tgz", { "os": "linux", "cpu": "x64" }, "sha512-77PpsFQUCOiZR9+LQEFg9GClyfkNXj1MP6wRnzYs0EeWbPcHs02AXu4xuUbM1zhwn3wqaizle3AEYg5aeoohhg=="],
|
||||
|
||||
"@rollup/rollup-linux-x64-musl": ["@rollup/rollup-linux-x64-musl@4.60.1", "https://registry.npmmirror.com/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.60.1.tgz", { "os": "linux", "cpu": "x64" }, "sha512-5cIATbk5vynAjqqmyBjlciMJl1+R/CwX9oLk/EyiFXDWd95KpHdrOJT//rnUl4cUcskrd0jCCw3wpZnhIHdD9w=="],
|
||||
|
||||
"@rollup/rollup-openbsd-x64": ["@rollup/rollup-openbsd-x64@4.60.1", "https://registry.npmmirror.com/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.60.1.tgz", { "os": "openbsd", "cpu": "x64" }, "sha512-cl0w09WsCi17mcmWqqglez9Gk8isgeWvoUZ3WiJFYSR3zjBQc2J5/ihSjpl+VLjPqjQ/1hJRcqBfLjssREQILw=="],
|
||||
|
||||
"@rollup/rollup-openharmony-arm64": ["@rollup/rollup-openharmony-arm64@4.60.1", "https://registry.npmmirror.com/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.60.1.tgz", { "os": "none", "cpu": "arm64" }, "sha512-4Cv23ZrONRbNtbZa37mLSueXUCtN7MXccChtKpUnQNgF010rjrjfHx3QxkS2PI7LqGT5xXyYs1a7LbzAwT0iCA=="],
|
||||
|
||||
"@rollup/rollup-win32-arm64-msvc": ["@rollup/rollup-win32-arm64-msvc@4.60.1", "https://registry.npmmirror.com/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.60.1.tgz", { "os": "win32", "cpu": "arm64" }, "sha512-i1okWYkA4FJICtr7KpYzFpRTHgy5jdDbZiWfvny21iIKky5YExiDXP+zbXzm3dUcFpkEeYNHgQ5fuG236JPq0g=="],
|
||||
|
||||
"@rollup/rollup-win32-ia32-msvc": ["@rollup/rollup-win32-ia32-msvc@4.60.1", "https://registry.npmmirror.com/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.60.1.tgz", { "os": "win32", "cpu": "ia32" }, "sha512-u09m3CuwLzShA0EYKMNiFgcjjzwqtUMLmuCJLeZWjjOYA3IT2Di09KaxGBTP9xVztWyIWjVdsB2E9goMjZvTQg=="],
|
||||
|
||||
"@rollup/rollup-win32-x64-gnu": ["@rollup/rollup-win32-x64-gnu@4.60.1", "https://registry.npmmirror.com/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.60.1.tgz", { "os": "win32", "cpu": "x64" }, "sha512-k+600V9Zl1CM7eZxJgMyTUzmrmhB/0XZnF4pRypKAlAgxmedUA+1v9R+XOFv56W4SlHEzfeMtzujLJD22Uz5zg=="],
|
||||
|
||||
"@rollup/rollup-win32-x64-msvc": ["@rollup/rollup-win32-x64-msvc@4.60.1", "https://registry.npmmirror.com/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.60.1.tgz", { "os": "win32", "cpu": "x64" }, "sha512-lWMnixq/QzxyhTV6NjQJ4SFo1J6PvOX8vUx5Wb4bBPsEb+8xZ89Bz6kOXpfXj9ak9AHTQVQzlgzBEc1SyM27xQ=="],
|
||||
|
||||
"@sec-ant/readable-stream": ["@sec-ant/readable-stream@0.4.1", "https://registry.npmmirror.com/@sec-ant/readable-stream/-/readable-stream-0.4.1.tgz", {}, "sha512-831qok9r2t8AlxLko40y2ebgSDhenenCatLVeW/uBtnHPyhHOvG0C7TvfgecV+wHzIm5KUICgzmVpWS+IMEAeg=="],
|
||||
|
||||
"@sentry/core": ["@sentry/core@10.47.0", "https://registry.npmmirror.com/@sentry/core/-/core-10.47.0.tgz", {}, "sha512-nsYRAx3EWezDut+Zl+UwwP07thh9uY7CfSAi2whTdcJl5hu1nSp2z8bba7Vq/MGbNLnazkd3A+GITBEML924JA=="],
|
||||
|
||||
"@sentry/node": ["@sentry/node@10.47.0", "https://registry.npmmirror.com/@sentry/node/-/node-10.47.0.tgz", { "dependencies": { "@fastify/otel": "0.18.0", "@opentelemetry/api": "^1.9.1", "@opentelemetry/context-async-hooks": "^2.6.1", "@opentelemetry/core": "^2.6.1", "@opentelemetry/instrumentation": "^0.214.0", "@opentelemetry/instrumentation-amqplib": "0.61.0", "@opentelemetry/instrumentation-connect": "0.57.0", "@opentelemetry/instrumentation-dataloader": "0.31.0", "@opentelemetry/instrumentation-express": "0.62.0", "@opentelemetry/instrumentation-fs": "0.33.0", "@opentelemetry/instrumentation-generic-pool": "0.57.0", "@opentelemetry/instrumentation-graphql": "0.62.0", "@opentelemetry/instrumentation-hapi": "0.60.0", "@opentelemetry/instrumentation-http": "0.214.0", "@opentelemetry/instrumentation-ioredis": "0.62.0", "@opentelemetry/instrumentation-kafkajs": "0.23.0", "@opentelemetry/instrumentation-knex": "0.58.0", "@opentelemetry/instrumentation-koa": "0.62.0", "@opentelemetry/instrumentation-lru-memoizer": "0.58.0", "@opentelemetry/instrumentation-mongodb": "0.67.0", "@opentelemetry/instrumentation-mongoose": "0.60.0", "@opentelemetry/instrumentation-mysql": "0.60.0", "@opentelemetry/instrumentation-mysql2": "0.60.0", "@opentelemetry/instrumentation-pg": "0.66.0", "@opentelemetry/instrumentation-redis": "0.62.0", "@opentelemetry/instrumentation-tedious": "0.33.0", "@opentelemetry/instrumentation-undici": "0.24.0", "@opentelemetry/resources": "^2.6.1", "@opentelemetry/sdk-trace-base": "^2.6.1", "@opentelemetry/semantic-conventions": "^1.40.0", "@prisma/instrumentation": "7.6.0", "@sentry/core": "10.47.0", "@sentry/node-core": "10.47.0", "@sentry/opentelemetry": "10.47.0", "import-in-the-middle": "^3.0.0" } }, "sha512-R+btqPepv88o635G6HtVewLjqCLUedBg5HBs7Nq1qbbKvyti01uArUF2f+3DsLenk5B9LUNiRlE+frZA44Ahmw=="],
|
||||
|
||||
"@sentry/node-core": ["@sentry/node-core@10.47.0", "https://registry.npmmirror.com/@sentry/node-core/-/node-core-10.47.0.tgz", { "dependencies": { "@sentry/core": "10.47.0", "@sentry/opentelemetry": "10.47.0", "import-in-the-middle": "^3.0.0" }, "peerDependencies": { "@opentelemetry/api": "^1.9.0", "@opentelemetry/context-async-hooks": "^1.30.1 || ^2.1.0", "@opentelemetry/core": "^1.30.1 || ^2.1.0", "@opentelemetry/exporter-trace-otlp-http": ">=0.57.0 <1", "@opentelemetry/instrumentation": ">=0.57.1 <1", "@opentelemetry/resources": "^1.30.1 || ^2.1.0", "@opentelemetry/sdk-trace-base": "^1.30.1 || ^2.1.0", "@opentelemetry/semantic-conventions": "^1.39.0" }, "optionalPeers": ["@opentelemetry/api", "@opentelemetry/context-async-hooks", "@opentelemetry/core", "@opentelemetry/exporter-trace-otlp-http", "@opentelemetry/instrumentation", "@opentelemetry/resources", "@opentelemetry/sdk-trace-base", "@opentelemetry/semantic-conventions"] }, "sha512-qv6LsqHbkQmd0aQEUox/svRSz26J+l4gGjFOUNEay2armZu9XLD+Ct89jpFgZD5oIPNAj2jraodTRqydXiwS5w=="],
|
||||
|
||||
"@sentry/opentelemetry": ["@sentry/opentelemetry@10.47.0", "https://registry.npmmirror.com/@sentry/opentelemetry/-/opentelemetry-10.47.0.tgz", { "dependencies": { "@sentry/core": "10.47.0" }, "peerDependencies": { "@opentelemetry/api": "^1.9.0", "@opentelemetry/context-async-hooks": "^1.30.1 || ^2.1.0", "@opentelemetry/core": "^1.30.1 || ^2.1.0", "@opentelemetry/sdk-trace-base": "^1.30.1 || ^2.1.0", "@opentelemetry/semantic-conventions": "^1.39.0" } }, "sha512-f6Hw2lrpCjlOksiosP0Z2jK/+l+21SIdoNglVeG/sttMyx8C8ywONKh0Ha50sFsvB1VaB8n94RKzzf3hkh9V3g=="],
|
||||
|
||||
"@sindresorhus/merge-streams": ["@sindresorhus/merge-streams@4.0.0", "https://registry.npmmirror.com/@sindresorhus/merge-streams/-/merge-streams-4.0.0.tgz", {}, "sha512-tlqY9xq5ukxTUZBmoOp+m61cqwQD5pHJtFY3Mn8CA8ps6yghLH/Hw8UPdqg4OLmFW3IFlcXnQNmo/dh8HzXYIQ=="],
|
||||
|
||||
"@smithy/abort-controller": ["@smithy/abort-controller@2.2.0", "https://registry.npmmirror.com/@smithy/abort-controller/-/abort-controller-2.2.0.tgz", { "dependencies": { "@smithy/types": "^2.12.0", "tslib": "^2.6.2" } }, "sha512-wRlta7GuLWpTqtFfGo+nZyOO1vEvewdNR1R4rTxpC8XU6vG/NDyrFBhwLZsqg1NUoR1noVaXJPC/7ZK47QCySw=="],
|
||||
@@ -924,98 +657,38 @@
|
||||
|
||||
"@smithy/uuid": ["@smithy/uuid@1.1.2", "https://registry.npmmirror.com/@smithy/uuid/-/uuid-1.1.2.tgz", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-O/IEdcCUKkubz60tFbGA7ceITTAJsty+lBjNoorP4Z6XRqaFb/OjQjZODophEcuq68nKm6/0r+6/lLQ+XVpk8g=="],
|
||||
|
||||
"@tailwindcss/node": ["@tailwindcss/node@4.2.2", "https://registry.npmmirror.com/@tailwindcss/node/-/node-4.2.2.tgz", { "dependencies": { "@jridgewell/remapping": "^2.3.5", "enhanced-resolve": "^5.19.0", "jiti": "^2.6.1", "lightningcss": "1.32.0", "magic-string": "^0.30.21", "source-map-js": "^1.2.1", "tailwindcss": "4.2.2" } }, "sha512-pXS+wJ2gZpVXqFaUEjojq7jzMpTGf8rU6ipJz5ovJV6PUGmlJ+jvIwGrzdHdQ80Sg+wmQxUFuoW1UAAwHNEdFA=="],
|
||||
|
||||
"@tailwindcss/oxide": ["@tailwindcss/oxide@4.2.2", "https://registry.npmmirror.com/@tailwindcss/oxide/-/oxide-4.2.2.tgz", { "optionalDependencies": { "@tailwindcss/oxide-android-arm64": "4.2.2", "@tailwindcss/oxide-darwin-arm64": "4.2.2", "@tailwindcss/oxide-darwin-x64": "4.2.2", "@tailwindcss/oxide-freebsd-x64": "4.2.2", "@tailwindcss/oxide-linux-arm-gnueabihf": "4.2.2", "@tailwindcss/oxide-linux-arm64-gnu": "4.2.2", "@tailwindcss/oxide-linux-arm64-musl": "4.2.2", "@tailwindcss/oxide-linux-x64-gnu": "4.2.2", "@tailwindcss/oxide-linux-x64-musl": "4.2.2", "@tailwindcss/oxide-wasm32-wasi": "4.2.2", "@tailwindcss/oxide-win32-arm64-msvc": "4.2.2", "@tailwindcss/oxide-win32-x64-msvc": "4.2.2" } }, "sha512-qEUA07+E5kehxYp9BVMpq9E8vnJuBHfJEC0vPC5e7iL/hw7HR61aDKoVoKzrG+QKp56vhNZe4qwkRmMC0zDLvg=="],
|
||||
|
||||
"@tailwindcss/oxide-android-arm64": ["@tailwindcss/oxide-android-arm64@4.2.2", "https://registry.npmmirror.com/@tailwindcss/oxide-android-arm64/-/oxide-android-arm64-4.2.2.tgz", { "os": "android", "cpu": "arm64" }, "sha512-dXGR1n+P3B6748jZO/SvHZq7qBOqqzQ+yFrXpoOWWALWndF9MoSKAT3Q0fYgAzYzGhxNYOoysRvYlpixRBBoDg=="],
|
||||
|
||||
"@tailwindcss/oxide-darwin-arm64": ["@tailwindcss/oxide-darwin-arm64@4.2.2", "https://registry.npmmirror.com/@tailwindcss/oxide-darwin-arm64/-/oxide-darwin-arm64-4.2.2.tgz", { "os": "darwin", "cpu": "arm64" }, "sha512-iq9Qjr6knfMpZHj55/37ouZeykwbDqF21gPFtfnhCCKGDcPI/21FKC9XdMO/XyBM7qKORx6UIhGgg6jLl7BZlg=="],
|
||||
|
||||
"@tailwindcss/oxide-darwin-x64": ["@tailwindcss/oxide-darwin-x64@4.2.2", "https://registry.npmmirror.com/@tailwindcss/oxide-darwin-x64/-/oxide-darwin-x64-4.2.2.tgz", { "os": "darwin", "cpu": "x64" }, "sha512-BlR+2c3nzc8f2G639LpL89YY4bdcIdUmiOOkv2GQv4/4M0vJlpXEa0JXNHhCHU7VWOKWT/CjqHdTP8aUuDJkuw=="],
|
||||
|
||||
"@tailwindcss/oxide-freebsd-x64": ["@tailwindcss/oxide-freebsd-x64@4.2.2", "https://registry.npmmirror.com/@tailwindcss/oxide-freebsd-x64/-/oxide-freebsd-x64-4.2.2.tgz", { "os": "freebsd", "cpu": "x64" }, "sha512-YUqUgrGMSu2CDO82hzlQ5qSb5xmx3RUrke/QgnoEx7KvmRJHQuZHZmZTLSuuHwFf0DJPybFMXMYf+WJdxHy/nQ=="],
|
||||
|
||||
"@tailwindcss/oxide-linux-arm-gnueabihf": ["@tailwindcss/oxide-linux-arm-gnueabihf@4.2.2", "https://registry.npmmirror.com/@tailwindcss/oxide-linux-arm-gnueabihf/-/oxide-linux-arm-gnueabihf-4.2.2.tgz", { "os": "linux", "cpu": "arm" }, "sha512-FPdhvsW6g06T9BWT0qTwiVZYE2WIFo2dY5aCSpjG/S/u1tby+wXoslXS0kl3/KXnULlLr1E3NPRRw0g7t2kgaQ=="],
|
||||
|
||||
"@tailwindcss/oxide-linux-arm64-gnu": ["@tailwindcss/oxide-linux-arm64-gnu@4.2.2", "https://registry.npmmirror.com/@tailwindcss/oxide-linux-arm64-gnu/-/oxide-linux-arm64-gnu-4.2.2.tgz", { "os": "linux", "cpu": "arm64" }, "sha512-4og1V+ftEPXGttOO7eCmW7VICmzzJWgMx+QXAJRAhjrSjumCwWqMfkDrNu1LXEQzNAwz28NCUpucgQPrR4S2yw=="],
|
||||
|
||||
"@tailwindcss/oxide-linux-arm64-musl": ["@tailwindcss/oxide-linux-arm64-musl@4.2.2", "https://registry.npmmirror.com/@tailwindcss/oxide-linux-arm64-musl/-/oxide-linux-arm64-musl-4.2.2.tgz", { "os": "linux", "cpu": "arm64" }, "sha512-oCfG/mS+/+XRlwNjnsNLVwnMWYH7tn/kYPsNPh+JSOMlnt93mYNCKHYzylRhI51X+TbR+ufNhhKKzm6QkqX8ag=="],
|
||||
|
||||
"@tailwindcss/oxide-linux-x64-gnu": ["@tailwindcss/oxide-linux-x64-gnu@4.2.2", "https://registry.npmmirror.com/@tailwindcss/oxide-linux-x64-gnu/-/oxide-linux-x64-gnu-4.2.2.tgz", { "os": "linux", "cpu": "x64" }, "sha512-rTAGAkDgqbXHNp/xW0iugLVmX62wOp2PoE39BTCGKjv3Iocf6AFbRP/wZT/kuCxC9QBh9Pu8XPkv/zCZB2mcMg=="],
|
||||
|
||||
"@tailwindcss/oxide-linux-x64-musl": ["@tailwindcss/oxide-linux-x64-musl@4.2.2", "https://registry.npmmirror.com/@tailwindcss/oxide-linux-x64-musl/-/oxide-linux-x64-musl-4.2.2.tgz", { "os": "linux", "cpu": "x64" }, "sha512-XW3t3qwbIwiSyRCggeO2zxe3KWaEbM0/kW9e8+0XpBgyKU4ATYzcVSMKteZJ1iukJ3HgHBjbg9P5YPRCVUxlnQ=="],
|
||||
|
||||
"@tailwindcss/oxide-wasm32-wasi": ["@tailwindcss/oxide-wasm32-wasi@4.2.2", "https://registry.npmmirror.com/@tailwindcss/oxide-wasm32-wasi/-/oxide-wasm32-wasi-4.2.2.tgz", { "dependencies": { "@emnapi/core": "^1.8.1", "@emnapi/runtime": "^1.8.1", "@emnapi/wasi-threads": "^1.1.0", "@napi-rs/wasm-runtime": "^1.1.1", "@tybys/wasm-util": "^0.10.1", "tslib": "^2.8.1" }, "cpu": "none" }, "sha512-eKSztKsmEsn1O5lJ4ZAfyn41NfG7vzCg496YiGtMDV86jz1q/irhms5O0VrY6ZwTUkFy/EKG3RfWgxSI3VbZ8Q=="],
|
||||
|
||||
"@tailwindcss/oxide-win32-arm64-msvc": ["@tailwindcss/oxide-win32-arm64-msvc@4.2.2", "https://registry.npmmirror.com/@tailwindcss/oxide-win32-arm64-msvc/-/oxide-win32-arm64-msvc-4.2.2.tgz", { "os": "win32", "cpu": "arm64" }, "sha512-qPmaQM4iKu5mxpsrWZMOZRgZv1tOZpUm+zdhhQP0VhJfyGGO3aUKdbh3gDZc/dPLQwW4eSqWGrrcWNBZWUWaXQ=="],
|
||||
|
||||
"@tailwindcss/oxide-win32-x64-msvc": ["@tailwindcss/oxide-win32-x64-msvc@4.2.2", "https://registry.npmmirror.com/@tailwindcss/oxide-win32-x64-msvc/-/oxide-win32-x64-msvc-4.2.2.tgz", { "os": "win32", "cpu": "x64" }, "sha512-1T/37VvI7WyH66b+vqHj/cLwnCxt7Qt3WFu5Q8hk65aOvlwAhs7rAp1VkulBJw/N4tMirXjVnylTR72uI0HGcA=="],
|
||||
|
||||
"@tailwindcss/vite": ["@tailwindcss/vite@4.2.2", "https://registry.npmmirror.com/@tailwindcss/vite/-/vite-4.2.2.tgz", { "dependencies": { "@tailwindcss/node": "4.2.2", "@tailwindcss/oxide": "4.2.2", "tailwindcss": "4.2.2" }, "peerDependencies": { "vite": "^5.2.0 || ^6 || ^7 || ^8" } }, "sha512-mEiF5HO1QqCLXoNEfXVA1Tzo+cYsrqV7w9Juj2wdUFyW07JRenqMG225MvPwr3ZD9N1bFQj46X7r33iHxLUW0w=="],
|
||||
|
||||
"@tybys/wasm-util": ["@tybys/wasm-util@0.10.1", "https://registry.npmmirror.com/@tybys/wasm-util/-/wasm-util-0.10.1.tgz", { "dependencies": { "tslib": "^2.4.0" } }, "sha512-9tTaPJLSiejZKx+Bmog4uSubteqTvFrVrURwkmHixBo0G4seD0zUxp98E1DzUBJxLQ3NPwXrGKDiVjwx/DpPsg=="],
|
||||
|
||||
"@types/babel__core": ["@types/babel__core@7.20.5", "https://registry.npmmirror.com/@types/babel__core/-/babel__core-7.20.5.tgz", { "dependencies": { "@babel/parser": "^7.20.7", "@babel/types": "^7.20.7", "@types/babel__generator": "*", "@types/babel__template": "*", "@types/babel__traverse": "*" } }, "sha512-qoQprZvz5wQFJwMDqeseRXWv3rqMvhgpbXFfVyWhbx9X47POIA6i/+dXefEmZKoAgOaTdaIgNSMqMIU61yRyzA=="],
|
||||
|
||||
"@types/babel__generator": ["@types/babel__generator@7.27.0", "https://registry.npmmirror.com/@types/babel__generator/-/babel__generator-7.27.0.tgz", { "dependencies": { "@babel/types": "^7.0.0" } }, "sha512-ufFd2Xi92OAVPYsy+P4n7/U7e68fex0+Ee8gSG9KX7eo084CWiQ4sdxktvdl0bOPupXtVJPY19zk6EwWqUQ8lg=="],
|
||||
|
||||
"@types/babel__template": ["@types/babel__template@7.4.4", "https://registry.npmmirror.com/@types/babel__template/-/babel__template-7.4.4.tgz", { "dependencies": { "@babel/parser": "^7.1.0", "@babel/types": "^7.0.0" } }, "sha512-h/NUaSyG5EyxBIp8YRxo4RMe2/qQgvyowRwVMzhYhBCONbW8PUsg4lkFMrhgZhUe5z3L3MiLDuvyJ/CaPa2A8A=="],
|
||||
|
||||
"@types/babel__traverse": ["@types/babel__traverse@7.28.0", "https://registry.npmmirror.com/@types/babel__traverse/-/babel__traverse-7.28.0.tgz", { "dependencies": { "@babel/types": "^7.28.2" } }, "sha512-8PvcXf70gTDZBgt9ptxJ8elBeBjcLOAcOtoO/mPJjtji1+CdGbHgm77om1GrsPxsiE+uXIpNSK64UYaIwQXd4Q=="],
|
||||
|
||||
"@types/bun": ["@types/bun@1.3.11", "https://registry.npmmirror.com/@types/bun/-/bun-1.3.11.tgz", { "dependencies": { "bun-types": "1.3.11" } }, "sha512-5vPne5QvtpjGpsGYXiFyycfpDF2ECyPcTSsFBMa0fraoxiQyMJ3SmuQIGhzPg2WJuWxVBoxWJ2kClYTcw/4fAg=="],
|
||||
|
||||
"@types/cacache": ["@types/cacache@20.0.1", "https://registry.npmmirror.com/@types/cacache/-/cacache-20.0.1.tgz", { "dependencies": { "@types/node": "*", "minipass": "*" } }, "sha512-QlKW3AFoFr/hvPHwFHMIVUH/ZCYeetBNou3PCmxu5LaNDvrtBlPJtIA6uhmU9JRt9oxj7IYoqoLcpxtzpPiTcw=="],
|
||||
|
||||
"@types/connect": ["@types/connect@3.4.38", "https://registry.npmmirror.com/@types/connect/-/connect-3.4.38.tgz", { "dependencies": { "@types/node": "*" } }, "sha512-K6uROf1LD88uDQqJCktA4yzL1YYAK6NgfsI0v/mTgyPKWsX1CnJ0XPSDhViejru1GcRkLWb8RlzFYJRqGUbaug=="],
|
||||
|
||||
"@types/estree": ["@types/estree@1.0.8", "https://registry.npmmirror.com/@types/estree/-/estree-1.0.8.tgz", {}, "sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w=="],
|
||||
|
||||
"@types/lodash": ["@types/lodash@4.17.24", "https://registry.npmmirror.com/@types/lodash/-/lodash-4.17.24.tgz", {}, "sha512-gIW7lQLZbue7lRSWEFql49QJJWThrTFFeIMJdp3eH4tKoxm1OvEPg02rm4wCCSHS0cL3/Fizimb35b7k8atwsQ=="],
|
||||
|
||||
"@types/lodash-es": ["@types/lodash-es@4.17.12", "https://registry.npmmirror.com/@types/lodash-es/-/lodash-es-4.17.12.tgz", { "dependencies": { "@types/lodash": "*" } }, "sha512-0NgftHUcV4v34VhXm8QBSftKVXtbkBG3ViCjs6+eJ5a6y6Mi/jiFGPc1sC7QK+9BFhWrURE3EOggmWaSxL9OzQ=="],
|
||||
|
||||
"@types/mute-stream": ["@types/mute-stream@0.0.4", "https://registry.npmmirror.com/@types/mute-stream/-/mute-stream-0.0.4.tgz", { "dependencies": { "@types/node": "*" } }, "sha512-CPM9nzrCPPJHQNA9keH9CVkVI+WR5kMa+7XEs5jcGQ0VoAGnLv242w8lIVgwAEfmE4oufJRaTc9PNLQl0ioAow=="],
|
||||
|
||||
"@types/mysql": ["@types/mysql@2.15.27", "https://registry.npmmirror.com/@types/mysql/-/mysql-2.15.27.tgz", { "dependencies": { "@types/node": "*" } }, "sha512-YfWiV16IY0OeBfBCk8+hXKmdTKrKlwKN1MNKAPBu5JYxLwBEZl7QzeEpGnlZb3VMGJrrGmB84gXiH+ofs/TezA=="],
|
||||
|
||||
"@types/node": ["@types/node@25.5.0", "https://registry.npmmirror.com/@types/node/-/node-25.5.0.tgz", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-jp2P3tQMSxWugkCUKLRPVUpGaL5MVFwF8RDuSRztfwgN1wmqJeMSbKlnEtQqU8UrhTmzEmZdu2I6v2dpp7XIxw=="],
|
||||
|
||||
"@types/pg": ["@types/pg@8.15.6", "https://registry.npmmirror.com/@types/pg/-/pg-8.15.6.tgz", { "dependencies": { "@types/node": "*", "pg-protocol": "*", "pg-types": "^2.2.0" } }, "sha512-NoaMtzhxOrubeL/7UZuNTrejB4MPAJ0RpxZqXQf2qXuVlTPuG6Y8p4u9dKRaue4yjmC7ZhzVO2/Yyyn25znrPQ=="],
|
||||
|
||||
"@types/pg-pool": ["@types/pg-pool@2.0.7", "https://registry.npmmirror.com/@types/pg-pool/-/pg-pool-2.0.7.tgz", { "dependencies": { "@types/pg": "*" } }, "sha512-U4CwmGVQcbEuqpyju8/ptOKg6gEC+Tqsvj2xS9o1g71bUh8twxnC6ZL5rZKCsGN0iyH0CwgUyc9VR5owNQF9Ng=="],
|
||||
|
||||
"@types/plist": ["@types/plist@3.0.5", "https://registry.npmmirror.com/@types/plist/-/plist-3.0.5.tgz", { "dependencies": { "@types/node": "*", "xmlbuilder": ">=11.0.1" } }, "sha512-E6OCaRmAe4WDmWNsL/9RMqdkkzDCY1etutkflWk4c+AcjDU07Pcz1fQwTX0TQz+Pxqn9i4L1TU3UFpjnrcDgxA=="],
|
||||
|
||||
"@types/react": ["@types/react@19.2.14", "https://registry.npmmirror.com/@types/react/-/react-19.2.14.tgz", { "dependencies": { "csstype": "^3.2.2" } }, "sha512-ilcTH/UniCkMdtexkoCN0bI7pMcJDvmQFPvuPvmEaYA/NSfFTAgdUSLAoVjaRJm7+6PvcM+q1zYOwS4wTYMF9w=="],
|
||||
|
||||
"@types/react-dom": ["@types/react-dom@19.2.3", "https://registry.npmmirror.com/@types/react-dom/-/react-dom-19.2.3.tgz", { "peerDependencies": { "@types/react": "^19.2.0" } }, "sha512-jp2L/eY6fn+KgVVQAOqYItbF0VY/YApe5Mz2F0aykSO8gx31bYCZyvSeYxCHKvzHG5eZjc+zyaS5BrBWya2+kQ=="],
|
||||
|
||||
"@types/react-reconciler": ["@types/react-reconciler@0.33.0", "https://registry.npmmirror.com/@types/react-reconciler/-/react-reconciler-0.33.0.tgz", { "peerDependencies": { "@types/react": "*" } }, "sha512-HZOXsKT0tGI9LlUw2LuedXsVeB88wFa536vVL0M6vE8zN63nI+sSr1ByxmPToP5K5bukaVscyeCJcF9guVNJ1g=="],
|
||||
|
||||
"@types/sharp": ["@types/sharp@0.32.0", "https://registry.npmmirror.com/@types/sharp/-/sharp-0.32.0.tgz", { "dependencies": { "sharp": "*" } }, "sha512-OOi3kL+FZDnPhVzsfD37J88FNeZh6gQsGcLc95NbeURRGvmSjeXiDcyWzF2o3yh/gQAUn2uhh/e+CPCa5nwAxw=="],
|
||||
|
||||
"@types/tedious": ["@types/tedious@4.0.14", "https://registry.npmmirror.com/@types/tedious/-/tedious-4.0.14.tgz", { "dependencies": { "@types/node": "*" } }, "sha512-KHPsfX/FoVbUGbyYvk1q9MMQHLPeRZhRJZdO45Q4YjvFkv4hMNghCWTvy7rdKessBsmtz4euWCWAB6/tVpI1Iw=="],
|
||||
|
||||
"@types/turndown": ["@types/turndown@5.0.6", "https://registry.npmmirror.com/@types/turndown/-/turndown-5.0.6.tgz", {}, "sha512-ru00MoyeeouE5BX4gRL+6m/BsDfbRayOskWqUvh7CLGW+UXxHQItqALa38kKnOiZPqJrtzJUgAC2+F0rL1S4Pg=="],
|
||||
|
||||
"@types/uuid": ["@types/uuid@10.0.0", "https://registry.npmmirror.com/@types/uuid/-/uuid-10.0.0.tgz", {}, "sha512-7gqG38EyHgyP1S+7+xomFtL+ZNHcKv6DwNaCZmJmo1vgMugyF3TCnXVg4t1uk89mLNwnLtnY3TpOpCOyp1/xHQ=="],
|
||||
|
||||
"@types/wrap-ansi": ["@types/wrap-ansi@3.0.0", "https://registry.npmmirror.com/@types/wrap-ansi/-/wrap-ansi-3.0.0.tgz", {}, "sha512-ltIpx+kM7g/MLRZfkbL7EsCEjfzCcScLpkg37eXEtx5kmrAKBkTJwd1GIAjDSL8wTpM6Hzn5YO4pSb91BEwu1g=="],
|
||||
|
||||
"@typespec/ts-http-runtime": ["@typespec/ts-http-runtime@0.3.4", "https://registry.npmmirror.com/@typespec/ts-http-runtime/-/ts-http-runtime-0.3.4.tgz", { "dependencies": { "http-proxy-agent": "^7.0.0", "https-proxy-agent": "^7.0.0", "tslib": "^2.6.2" } }, "sha512-CI0NhTrz4EBaa0U+HaaUZrJhPoso8sG7ZFya8uQoBA57fjzrjRSv87ekCjLZOFExN+gXE/z0xuN2QfH4H2HrLQ=="],
|
||||
|
||||
"@vitejs/plugin-react": ["@vitejs/plugin-react@4.7.0", "https://registry.npmmirror.com/@vitejs/plugin-react/-/plugin-react-4.7.0.tgz", { "dependencies": { "@babel/core": "^7.28.0", "@babel/plugin-transform-react-jsx-self": "^7.27.1", "@babel/plugin-transform-react-jsx-source": "^7.27.1", "@rolldown/pluginutils": "1.0.0-beta.27", "@types/babel__core": "^7.20.5", "react-refresh": "^0.17.0" }, "peerDependencies": { "vite": "^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0" } }, "sha512-gUu9hwfWvvEDBBmgtAowQCojwZmJ5mcLn3aufeCsitijs3+f2NsrPtlAWIR6OPiqljl96GVCUbLe0HyqIpVaoA=="],
|
||||
|
||||
"@xmldom/xmldom": ["@xmldom/xmldom@0.8.12", "https://registry.npmmirror.com/@xmldom/xmldom/-/xmldom-0.8.12.tgz", {}, "sha512-9k/gHF6n/pAi/9tqr3m3aqkuiNosYTurLLUtc7xQ9sxB/wm7WPygCv8GYa6mS0fLJEHhqMC1ATYhz++U/lRHqg=="],
|
||||
|
||||
"accepts": ["accepts@2.0.0", "https://registry.npmmirror.com/accepts/-/accepts-2.0.0.tgz", { "dependencies": { "mime-types": "^3.0.0", "negotiator": "^1.0.0" } }, "sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng=="],
|
||||
|
||||
"acorn": ["acorn@8.16.0", "https://registry.npmmirror.com/acorn/-/acorn-8.16.0.tgz", { "bin": { "acorn": "bin/acorn" } }, "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw=="],
|
||||
|
||||
"acorn-import-attributes": ["acorn-import-attributes@1.9.5", "https://registry.npmmirror.com/acorn-import-attributes/-/acorn-import-attributes-1.9.5.tgz", { "peerDependencies": { "acorn": "^8" } }, "sha512-n02Vykv5uA3eHGM/Z2dQrcD56kL8TyDb2p1+0P83PClMnC/nc+anbQRhIOWnSq4Ke/KvDPrY3C9hDtC/A3eHnQ=="],
|
||||
|
||||
"agent-base": ["agent-base@8.0.0", "https://registry.npmmirror.com/agent-base/-/agent-base-8.0.0.tgz", {}, "sha512-QT8i0hCz6C/KQ+KTAbSNwCHDGdmUJl2tp2ZpNlGSWCfhUNVbYG2WLE3MdZGBAgXPV4GAvjGMxo+C1hroyxmZEg=="],
|
||||
|
||||
"ajv": ["ajv@8.18.0", "https://registry.npmmirror.com/ajv/-/ajv-8.18.0.tgz", { "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", "json-schema-traverse": "^1.0.0", "require-from-string": "^2.0.2" } }, "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A=="],
|
||||
@@ -1044,8 +717,6 @@
|
||||
|
||||
"base64-js": ["base64-js@1.5.1", "https://registry.npmmirror.com/base64-js/-/base64-js-1.5.1.tgz", {}, "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA=="],
|
||||
|
||||
"baseline-browser-mapping": ["baseline-browser-mapping@2.10.15", "https://registry.npmmirror.com/baseline-browser-mapping/-/baseline-browser-mapping-2.10.15.tgz", { "bin": { "baseline-browser-mapping": "dist/cli.cjs" } }, "sha512-1nfKCq9wuAZFTkA2ey/3OXXx7GzFjLdkTiFVNwlJ9WqdI706CZRIhEqjuwanjMIja+84jDLa9rcyZDPDiVkASQ=="],
|
||||
|
||||
"bidi-js": ["bidi-js@1.0.3", "https://registry.npmmirror.com/bidi-js/-/bidi-js-1.0.3.tgz", { "dependencies": { "require-from-string": "^2.0.2" } }, "sha512-RKshQI1R3YQ+n9YJz2QQ147P66ELpa1FQEg20Dk8oW9t2KgLbpDLLp9aGZ7y8WHSshDknG0bknqGw5/tyCs5tw=="],
|
||||
|
||||
"bignumber.js": ["bignumber.js@9.3.1", "https://registry.npmmirror.com/bignumber.js/-/bignumber.js-9.3.1.tgz", {}, "sha512-Ko0uX15oIUS7wJ3Rb30Fs6SkVbLmPBAKdlm7q9+ak9bbIeFf0MwuBsQV6z7+X768/cHsfg+WlysDWJcmthjsjQ=="],
|
||||
@@ -1058,8 +729,6 @@
|
||||
|
||||
"braces": ["braces@3.0.3", "https://registry.npmmirror.com/braces/-/braces-3.0.3.tgz", { "dependencies": { "fill-range": "^7.1.1" } }, "sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA=="],
|
||||
|
||||
"browserslist": ["browserslist@4.28.2", "https://registry.npmmirror.com/browserslist/-/browserslist-4.28.2.tgz", { "dependencies": { "baseline-browser-mapping": "^2.10.12", "caniuse-lite": "^1.0.30001782", "electron-to-chromium": "^1.5.328", "node-releases": "^2.0.36", "update-browserslist-db": "^1.2.3" }, "bin": { "browserslist": "cli.js" } }, "sha512-48xSriZYYg+8qXna9kwqjIVzuQxi+KYWp2+5nCYnYKPTr0LvD89Jqk2Or5ogxz0NUMfIjhh2lIUX/LyX9B4oIg=="],
|
||||
|
||||
"buffer-equal-constant-time": ["buffer-equal-constant-time@1.0.1", "https://registry.npmmirror.com/buffer-equal-constant-time/-/buffer-equal-constant-time-1.0.1.tgz", {}, "sha512-zRpUiDwd/xk6ADqPMATG8vc9VPrkck7T07OIx0gnjmJAnHnTVXNQG3vfvWNuiZIkwu9KrKdA1iJKfsfTVxE6NA=="],
|
||||
|
||||
"bun-types": ["bun-types@1.3.11", "https://registry.npmmirror.com/bun-types/-/bun-types-1.3.11.tgz", { "dependencies": { "@types/node": "*" } }, "sha512-1KGPpoxQWl9f6wcZh57LvrPIInQMn2TQ7jsgxqpRzg+l0QPOFvJVH7HmvHo/AiPgwXy+/Thf6Ov3EdVn1vOabg=="],
|
||||
@@ -1076,16 +745,12 @@
|
||||
|
||||
"camelcase": ["camelcase@5.3.1", "https://registry.npmmirror.com/camelcase/-/camelcase-5.3.1.tgz", {}, "sha512-L28STB170nwWS63UjtlEOE3dldQApaJXZkOI1uMFfzf3rRuPegHaHesyee+YxQ+W6SvRDQV6UrdOdRiR153wJg=="],
|
||||
|
||||
"caniuse-lite": ["caniuse-lite@1.0.30001786", "https://registry.npmmirror.com/caniuse-lite/-/caniuse-lite-1.0.30001786.tgz", {}, "sha512-4oxTZEvqmLLrERwxO76yfKM7acZo310U+v4kqexI2TL1DkkUEMT8UijrxxcnVdxR3qkVf5awGRX+4Z6aPHVKrA=="],
|
||||
|
||||
"chalk": ["chalk@5.6.2", "https://registry.npmmirror.com/chalk/-/chalk-5.6.2.tgz", {}, "sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA=="],
|
||||
|
||||
"chardet": ["chardet@0.7.0", "https://registry.npmmirror.com/chardet/-/chardet-0.7.0.tgz", {}, "sha512-mT8iDcrh03qDGRRmoA2hmBJnxpllMR+0/0qlzjqZES6NdiWDcZkCNAk4rPFZ9Q85r27unkiNNg8ZOiwZXBHwcA=="],
|
||||
|
||||
"chokidar": ["chokidar@5.0.0", "https://registry.npmmirror.com/chokidar/-/chokidar-5.0.0.tgz", { "dependencies": { "readdirp": "^5.0.0" } }, "sha512-TQMmc3w+5AxjpL8iIiwebF73dRDF4fBIieAqGn9RGCWaEVwQ6Fb2cGe31Yns0RRIzii5goJ1Y7xbMwo1TxMplw=="],
|
||||
|
||||
"cjs-module-lexer": ["cjs-module-lexer@2.2.0", "https://registry.npmmirror.com/cjs-module-lexer/-/cjs-module-lexer-2.2.0.tgz", {}, "sha512-4bHTS2YuzUvtoLjdy+98ykbNB5jS0+07EvFNXerqZQJ89F7DI6ET7OQo/HJuW6K0aVsKA9hj9/RVb2kQVOrPDQ=="],
|
||||
|
||||
"cli-boxes": ["cli-boxes@4.0.1", "https://registry.npmmirror.com/cli-boxes/-/cli-boxes-4.0.1.tgz", {}, "sha512-5IOn+jcCEHEraYolBPs/sT4BxYCe2nHg374OPiItB1O96KZFseS2gthU4twyYzeDcFew4DaUM/xwc5BQf08JJw=="],
|
||||
|
||||
"cli-highlight": ["cli-highlight@2.1.11", "https://registry.npmmirror.com/cli-highlight/-/cli-highlight-2.1.11.tgz", { "dependencies": { "chalk": "^4.0.0", "highlight.js": "^10.7.1", "mz": "^2.4.0", "parse5": "^5.1.1", "parse5-htmlparser2-tree-adapter": "^6.0.0", "yargs": "^16.0.0" }, "bin": { "highlight": "bin/highlight" } }, "sha512-9KDcoEVwyUXrjcJNvHD0NFc/hiwe/WPVYIleQh2O1N2Zro5gWJZ/K+3DGn8w8P/F6FxOgzyC5bxDyHIgCSPhGg=="],
|
||||
@@ -1114,8 +779,6 @@
|
||||
|
||||
"content-type": ["content-type@1.0.5", "https://registry.npmmirror.com/content-type/-/content-type-1.0.5.tgz", {}, "sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA=="],
|
||||
|
||||
"convert-source-map": ["convert-source-map@2.0.0", "https://registry.npmmirror.com/convert-source-map/-/convert-source-map-2.0.0.tgz", {}, "sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg=="],
|
||||
|
||||
"convert-to-spaces": ["convert-to-spaces@2.0.1", "https://registry.npmmirror.com/convert-to-spaces/-/convert-to-spaces-2.0.1.tgz", {}, "sha512-rcQ1bsQO9799wq24uE5AM2tAILy4gXGIK/njFWcVQkGNZ96edlpY+A7bjwvzjYvLDyzmG1MmMLZhpcsb+klNMQ=="],
|
||||
|
||||
"cookie": ["cookie@0.7.2", "https://registry.npmmirror.com/cookie/-/cookie-0.7.2.tgz", {}, "sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w=="],
|
||||
@@ -1160,14 +823,10 @@
|
||||
|
||||
"ee-first": ["ee-first@1.1.1", "https://registry.npmmirror.com/ee-first/-/ee-first-1.1.1.tgz", {}, "sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow=="],
|
||||
|
||||
"electron-to-chromium": ["electron-to-chromium@1.5.331", "https://registry.npmmirror.com/electron-to-chromium/-/electron-to-chromium-1.5.331.tgz", {}, "sha512-IbxXrsTlD3hRodkLnbxAPP4OuJYdWCeM3IOdT+CpcMoIwIoDfCmRpEtSPfwBXxVkg9xmBeY7Lz2Eo2TDn/HC3Q=="],
|
||||
|
||||
"emoji-regex": ["emoji-regex@10.6.0", "https://registry.npmmirror.com/emoji-regex/-/emoji-regex-10.6.0.tgz", {}, "sha512-toUI84YS5YmxW219erniWD0CIVOo46xGKColeNQRgOzDorgBi1v4D71/OFzgD9GO2UGKIv1C3Sp8DAn0+j5w7A=="],
|
||||
|
||||
"encodeurl": ["encodeurl@2.0.0", "https://registry.npmmirror.com/encodeurl/-/encodeurl-2.0.0.tgz", {}, "sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg=="],
|
||||
|
||||
"enhanced-resolve": ["enhanced-resolve@5.20.1", "https://registry.npmmirror.com/enhanced-resolve/-/enhanced-resolve-5.20.1.tgz", { "dependencies": { "graceful-fs": "^4.2.4", "tapable": "^2.3.0" } }, "sha512-Qohcme7V1inbAfvjItgw0EaxVX5q2rdVEZHRBrEQdRZTssLDGsL8Lwrznl8oQ/6kuTJONLaDcGjkNP247XEhcA=="],
|
||||
|
||||
"env-paths": ["env-paths@4.0.0", "https://registry.npmmirror.com/env-paths/-/env-paths-4.0.0.tgz", { "dependencies": { "is-safe-filename": "^0.1.0" } }, "sha512-pxP8eL2SwwaTRi/KHYwLYXinDs7gL3jxFcBYmEdYfZmZXbaVDvdppd0XBU8qVz03rDfKZMXg1omHCbsJjZrMsw=="],
|
||||
|
||||
"es-define-property": ["es-define-property@1.0.1", "https://registry.npmmirror.com/es-define-property/-/es-define-property-1.0.1.tgz", {}, "sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g=="],
|
||||
@@ -1178,8 +837,6 @@
|
||||
|
||||
"es-set-tostringtag": ["es-set-tostringtag@2.1.0", "https://registry.npmmirror.com/es-set-tostringtag/-/es-set-tostringtag-2.1.0.tgz", { "dependencies": { "es-errors": "^1.3.0", "get-intrinsic": "^1.2.6", "has-tostringtag": "^1.0.2", "hasown": "^2.0.2" } }, "sha512-j6vWzfrGVfyXxge+O0x5sh6cvxAog0a/4Rdd2K36zCMV5eJ+/+tOAngRO8cODMNWbVRdVlmGZQL2YS3yR8bIUA=="],
|
||||
|
||||
"esbuild": ["esbuild@0.25.12", "https://registry.npmmirror.com/esbuild/-/esbuild-0.25.12.tgz", { "optionalDependencies": { "@esbuild/aix-ppc64": "0.25.12", "@esbuild/android-arm": "0.25.12", "@esbuild/android-arm64": "0.25.12", "@esbuild/android-x64": "0.25.12", "@esbuild/darwin-arm64": "0.25.12", "@esbuild/darwin-x64": "0.25.12", "@esbuild/freebsd-arm64": "0.25.12", "@esbuild/freebsd-x64": "0.25.12", "@esbuild/linux-arm": "0.25.12", "@esbuild/linux-arm64": "0.25.12", "@esbuild/linux-ia32": "0.25.12", "@esbuild/linux-loong64": "0.25.12", "@esbuild/linux-mips64el": "0.25.12", "@esbuild/linux-ppc64": "0.25.12", "@esbuild/linux-riscv64": "0.25.12", "@esbuild/linux-s390x": "0.25.12", "@esbuild/linux-x64": "0.25.12", "@esbuild/netbsd-arm64": "0.25.12", "@esbuild/netbsd-x64": "0.25.12", "@esbuild/openbsd-arm64": "0.25.12", "@esbuild/openbsd-x64": "0.25.12", "@esbuild/openharmony-arm64": "0.25.12", "@esbuild/sunos-x64": "0.25.12", "@esbuild/win32-arm64": "0.25.12", "@esbuild/win32-ia32": "0.25.12", "@esbuild/win32-x64": "0.25.12" }, "bin": { "esbuild": "bin/esbuild" } }, "sha512-bbPBYYrtZbkt6Os6FiTLCTFxvq4tt3JKall1vRwshA3fdVztsLAatFaZobhkBC8/BrPetoa0oksYoKXoG4ryJg=="],
|
||||
|
||||
"escalade": ["escalade@3.2.0", "https://registry.npmmirror.com/escalade/-/escalade-3.2.0.tgz", {}, "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA=="],
|
||||
|
||||
"escape-html": ["escape-html@1.0.3", "https://registry.npmmirror.com/escape-html/-/escape-html-1.0.3.tgz", {}, "sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow=="],
|
||||
@@ -1216,8 +873,6 @@
|
||||
|
||||
"fd-package-json": ["fd-package-json@2.0.0", "https://registry.npmmirror.com/fd-package-json/-/fd-package-json-2.0.0.tgz", { "dependencies": { "walk-up-path": "^4.0.0" } }, "sha512-jKmm9YtsNXN789RS/0mSzOC1NUq9mkVd65vbSSVsKdjGvYXBuE4oWe2QOEoFeRmJg+lPuZxpmrfFclNhoRMneQ=="],
|
||||
|
||||
"fdir": ["fdir@6.5.0", "https://registry.npmmirror.com/fdir/-/fdir-6.5.0.tgz", { "peerDependencies": { "picomatch": "^3 || ^4" }, "optionalPeers": ["picomatch"] }, "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg=="],
|
||||
|
||||
"fetch-blob": ["fetch-blob@3.2.0", "https://registry.npmmirror.com/fetch-blob/-/fetch-blob-3.2.0.tgz", { "dependencies": { "node-domexception": "^1.0.0", "web-streams-polyfill": "^3.0.3" } }, "sha512-7yAQpD2UMJzLi1Dqv7qFYnPbaPx7ZfFK6PiIxQ4PfkGPyNyl2Ugx+a/umUonmKqjhM4DnfbMvdX6otXq83soQQ=="],
|
||||
|
||||
"fflate": ["fflate@0.8.2", "https://registry.npmmirror.com/fflate/-/fflate-0.8.2.tgz", {}, "sha512-cPJU47OaAoCbg0pBvzsgpTPhmhqI5eJjh/JIu8tPj5q+T7iLvW/JAYUqmE7KOB4R1ZyEhzBaIQpQpardBF5z8A=="],
|
||||
@@ -1242,16 +897,12 @@
|
||||
|
||||
"forwarded": ["forwarded@0.2.0", "https://registry.npmmirror.com/forwarded/-/forwarded-0.2.0.tgz", {}, "sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow=="],
|
||||
|
||||
"forwarded-parse": ["forwarded-parse@2.1.2", "https://registry.npmmirror.com/forwarded-parse/-/forwarded-parse-2.1.2.tgz", {}, "sha512-alTFZZQDKMporBH77856pXgzhEzaUVmLCDk+egLgIgHst3Tpndzz8MnKe+GzRJRfvVdn69HhpW7cmXzvtLvJAw=="],
|
||||
|
||||
"fresh": ["fresh@2.0.0", "https://registry.npmmirror.com/fresh/-/fresh-2.0.0.tgz", {}, "sha512-Rx/WycZ60HOaqLKAi6cHRKKI7zxWbJ31MhntmtwMoaTeF7XFH9hhBp8vITaMidfljRQ6eYWCKkaTK+ykVJHP2A=="],
|
||||
|
||||
"fs-extra": ["fs-extra@10.1.0", "https://registry.npmmirror.com/fs-extra/-/fs-extra-10.1.0.tgz", { "dependencies": { "graceful-fs": "^4.2.0", "jsonfile": "^6.0.1", "universalify": "^2.0.0" } }, "sha512-oRXApq54ETRj4eMiFzGnHWGy+zo5raudjuxN0b8H7s/RU2oW0Wvsx9O0ACRN/kRq9E8Vu/ReskGB5o3ji+FzHQ=="],
|
||||
|
||||
"fs-minipass": ["fs-minipass@3.0.3", "https://registry.npmmirror.com/fs-minipass/-/fs-minipass-3.0.3.tgz", { "dependencies": { "minipass": "^7.0.3" } }, "sha512-XUBA9XClHbnJWSfBzjkm6RvPsyg3sryZt06BEQoXcF7EK/xpGaQYJgQKDJSUH5SGZ76Y7pFx1QBnXz09rU5Fbw=="],
|
||||
|
||||
"fsevents": ["fsevents@2.3.3", "https://registry.npmmirror.com/fsevents/-/fsevents-2.3.3.tgz", { "os": "darwin" }, "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw=="],
|
||||
|
||||
"function-bind": ["function-bind@1.1.2", "https://registry.npmmirror.com/function-bind/-/function-bind-1.1.2.tgz", {}, "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA=="],
|
||||
|
||||
"fuse.js": ["fuse.js@7.1.0", "https://registry.npmmirror.com/fuse.js/-/fuse.js-7.1.0.tgz", {}, "sha512-trLf4SzuuUxfusZADLINj+dE8clK1frKdmqiJNb1Es75fmI5oY6X2mxLVUciLLjxqw/xr72Dhy+lER6dGd02FQ=="],
|
||||
@@ -1262,8 +913,6 @@
|
||||
|
||||
"gcp-metadata": ["gcp-metadata@8.1.2", "https://registry.npmmirror.com/gcp-metadata/-/gcp-metadata-8.1.2.tgz", { "dependencies": { "gaxios": "^7.0.0", "google-logging-utils": "^1.0.0", "json-bigint": "^1.0.0" } }, "sha512-zV/5HKTfCeKWnxG0Dmrw51hEWFGfcF2xiXqcA3+J90WDuP0SvoiSO5ORvcBsifmx/FoIjgQN3oNOGaQ5PhLFkg=="],
|
||||
|
||||
"gensync": ["gensync@1.0.0-beta.2", "https://registry.npmmirror.com/gensync/-/gensync-1.0.0-beta.2.tgz", {}, "sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg=="],
|
||||
|
||||
"get-caller-file": ["get-caller-file@2.0.5", "https://registry.npmmirror.com/get-caller-file/-/get-caller-file-2.0.5.tgz", {}, "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg=="],
|
||||
|
||||
"get-east-asian-width": ["get-east-asian-width@1.5.0", "https://registry.npmmirror.com/get-east-asian-width/-/get-east-asian-width-1.5.0.tgz", {}, "sha512-CQ+bEO+Tva/qlmw24dCejulK5pMzVnUOFOijVogd3KQs07HnRIgp8TGipvCCRT06xeYEbpbgwaCxglFyiuIcmA=="],
|
||||
@@ -1298,8 +947,6 @@
|
||||
|
||||
"hasown": ["hasown@2.0.2", "https://registry.npmmirror.com/hasown/-/hasown-2.0.2.tgz", { "dependencies": { "function-bind": "^1.1.2" } }, "sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ=="],
|
||||
|
||||
"he": ["he@1.2.0", "https://registry.npmmirror.com/he/-/he-1.2.0.tgz", { "bin": { "he": "bin/he" } }, "sha512-F/1DnUGPopORZi0ni+CvrCgHQ5FyEAHRLSApuYWMmrbSwoN2Mn/7k+Gl38gJnR7yyDZk6WLXwiGod1JOWNDKGw=="],
|
||||
|
||||
"highlight.js": ["highlight.js@11.11.1", "https://registry.npmmirror.com/highlight.js/-/highlight.js-11.11.1.tgz", {}, "sha512-Xwwo44whKBVCYoliBQwaPvtd/2tYFkRQtXDWj1nackaV2JPXx3L0+Jvd8/qCJ2p+ML0/XVkJ2q+Mr+UVdpJK5w=="],
|
||||
|
||||
"hono": ["hono@4.12.9", "https://registry.npmmirror.com/hono/-/hono-4.12.9.tgz", {}, "sha512-wy3T8Zm2bsEvxKZM5w21VdHDDcwVS1yUFFY6i8UobSsKfFceT7TOwhbhfKsDyx7tYQlmRM5FLpIuYvNFyjctiA=="],
|
||||
@@ -1318,8 +965,6 @@
|
||||
|
||||
"image-processor-napi": ["image-processor-napi@workspace:packages/image-processor-napi"],
|
||||
|
||||
"import-in-the-middle": ["import-in-the-middle@3.0.0", "https://registry.npmmirror.com/import-in-the-middle/-/import-in-the-middle-3.0.0.tgz", { "dependencies": { "acorn": "^8.15.0", "acorn-import-attributes": "^1.9.5", "cjs-module-lexer": "^2.2.0", "module-details-from-path": "^1.0.4" } }, "sha512-OnGy+eYT7wVejH2XWgLRgbmzujhhVIATQH0ztIeRilwHBjTeG3pD+XnH3PKX0r9gJ0BuJmJ68q/oh9qgXnNDQg=="],
|
||||
|
||||
"indent-string": ["indent-string@5.0.0", "https://registry.npmmirror.com/indent-string/-/indent-string-5.0.0.tgz", {}, "sha512-m6FAo/spmsW2Ab2fU35JTYwtOKa2yAwXSwgjSv1TJzh4Mh7mC3lzAOVLBprb72XsTrgkEIsl7YrFNAiDiRhIGg=="],
|
||||
|
||||
"inherits": ["inherits@2.0.4", "https://registry.npmmirror.com/inherits/-/inherits-2.0.4.tgz", {}, "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ=="],
|
||||
@@ -1360,10 +1005,6 @@
|
||||
|
||||
"jose": ["jose@6.2.2", "https://registry.npmmirror.com/jose/-/jose-6.2.2.tgz", {}, "sha512-d7kPDd34KO/YnzaDOlikGpOurfF0ByC2sEV4cANCtdqLlTfBlw2p14O/5d/zv40gJPbIQxfES3nSx1/oYNyuZQ=="],
|
||||
|
||||
"js-tokens": ["js-tokens@4.0.0", "https://registry.npmmirror.com/js-tokens/-/js-tokens-4.0.0.tgz", {}, "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ=="],
|
||||
|
||||
"jsesc": ["jsesc@3.1.0", "https://registry.npmmirror.com/jsesc/-/jsesc-3.1.0.tgz", { "bin": { "jsesc": "bin/jsesc" } }, "sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA=="],
|
||||
|
||||
"json-bigint": ["json-bigint@1.0.0", "https://registry.npmmirror.com/json-bigint/-/json-bigint-1.0.0.tgz", { "dependencies": { "bignumber.js": "^9.0.0" } }, "sha512-SiPv/8VpZuWbvLSMtTDU8hEfrZWg/mH/nV/b4o0CYbSxu1UIQPLdwKOCIyLQX+VIPO5vrLX3i8qtqFyhdPSUSQ=="],
|
||||
|
||||
"json-schema-to-ts": ["json-schema-to-ts@3.1.1", "https://registry.npmmirror.com/json-schema-to-ts/-/json-schema-to-ts-3.1.1.tgz", { "dependencies": { "@babel/runtime": "^7.18.3", "ts-algebra": "^2.0.0" } }, "sha512-+DWg8jCJG2TEnpy7kOm/7/AxaYoaRbjVB4LFZLySZlWn8exGs3A4OLJR966cVvU26N7X9TWxl+Jsw7dzAqKT6g=="],
|
||||
@@ -1372,8 +1013,6 @@
|
||||
|
||||
"json-schema-typed": ["json-schema-typed@8.0.2", "https://registry.npmmirror.com/json-schema-typed/-/json-schema-typed-8.0.2.tgz", {}, "sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA=="],
|
||||
|
||||
"json5": ["json5@2.2.3", "https://registry.npmmirror.com/json5/-/json5-2.2.3.tgz", { "bin": { "json5": "lib/cli.js" } }, "sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg=="],
|
||||
|
||||
"jsonc-parser": ["jsonc-parser@3.3.1", "https://registry.npmmirror.com/jsonc-parser/-/jsonc-parser-3.3.1.tgz", {}, "sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ=="],
|
||||
|
||||
"jsonfile": ["jsonfile@6.2.0", "https://registry.npmmirror.com/jsonfile/-/jsonfile-6.2.0.tgz", { "dependencies": { "universalify": "^2.0.0" }, "optionalDependencies": { "graceful-fs": "^4.1.6" } }, "sha512-FGuPw30AdOIUTRMC2OMRtQV+jkVj2cfPqSeWXv1NEAJ1qZ5zb1X6z1mFhbfOB/iy3ssJCD+3KuZ8r8C3uVFlAg=="],
|
||||
@@ -1386,30 +1025,6 @@
|
||||
|
||||
"knip": ["knip@6.1.1", "https://registry.npmmirror.com/knip/-/knip-6.1.1.tgz", { "dependencies": { "@nodelib/fs.walk": "^1.2.3", "fast-glob": "^3.3.3", "formatly": "^0.3.0", "get-tsconfig": "4.13.7", "jiti": "^2.6.0", "minimist": "^1.2.8", "oxc-parser": "^0.121.0", "oxc-resolver": "^11.19.1", "picocolors": "^1.1.1", "picomatch": "^4.0.1", "smol-toml": "^1.6.1", "strip-json-comments": "5.0.3", "unbash": "^2.2.0", "yaml": "^2.8.2", "zod": "^4.1.11" }, "bin": { "knip": "bin/knip.js", "knip-bun": "bin/knip-bun.js" } }, "sha512-BC/kbdxwCgv+p/3YkGbtlLxbOXhQDuR+CeKKFEpJyKb3BFwG1gZa+CMWSqAnPi+kUexz74m327d3zWxyn2fMew=="],
|
||||
|
||||
"lightningcss": ["lightningcss@1.32.0", "https://registry.npmmirror.com/lightningcss/-/lightningcss-1.32.0.tgz", { "dependencies": { "detect-libc": "^2.0.3" }, "optionalDependencies": { "lightningcss-android-arm64": "1.32.0", "lightningcss-darwin-arm64": "1.32.0", "lightningcss-darwin-x64": "1.32.0", "lightningcss-freebsd-x64": "1.32.0", "lightningcss-linux-arm-gnueabihf": "1.32.0", "lightningcss-linux-arm64-gnu": "1.32.0", "lightningcss-linux-arm64-musl": "1.32.0", "lightningcss-linux-x64-gnu": "1.32.0", "lightningcss-linux-x64-musl": "1.32.0", "lightningcss-win32-arm64-msvc": "1.32.0", "lightningcss-win32-x64-msvc": "1.32.0" } }, "sha512-NXYBzinNrblfraPGyrbPoD19C1h9lfI/1mzgWYvXUTe414Gz/X1FD2XBZSZM7rRTrMA8JL3OtAaGifrIKhQ5yQ=="],
|
||||
|
||||
"lightningcss-android-arm64": ["lightningcss-android-arm64@1.32.0", "https://registry.npmmirror.com/lightningcss-android-arm64/-/lightningcss-android-arm64-1.32.0.tgz", { "os": "android", "cpu": "arm64" }, "sha512-YK7/ClTt4kAK0vo6w3X+Pnm0D2cf2vPHbhOXdoNti1Ga0al1P4TBZhwjATvjNwLEBCnKvjJc2jQgHXH0NEwlAg=="],
|
||||
|
||||
"lightningcss-darwin-arm64": ["lightningcss-darwin-arm64@1.32.0", "https://registry.npmmirror.com/lightningcss-darwin-arm64/-/lightningcss-darwin-arm64-1.32.0.tgz", { "os": "darwin", "cpu": "arm64" }, "sha512-RzeG9Ju5bag2Bv1/lwlVJvBE3q6TtXskdZLLCyfg5pt+HLz9BqlICO7LZM7VHNTTn/5PRhHFBSjk5lc4cmscPQ=="],
|
||||
|
||||
"lightningcss-darwin-x64": ["lightningcss-darwin-x64@1.32.0", "https://registry.npmmirror.com/lightningcss-darwin-x64/-/lightningcss-darwin-x64-1.32.0.tgz", { "os": "darwin", "cpu": "x64" }, "sha512-U+QsBp2m/s2wqpUYT/6wnlagdZbtZdndSmut/NJqlCcMLTWp5muCrID+K5UJ6jqD2BFshejCYXniPDbNh73V8w=="],
|
||||
|
||||
"lightningcss-freebsd-x64": ["lightningcss-freebsd-x64@1.32.0", "https://registry.npmmirror.com/lightningcss-freebsd-x64/-/lightningcss-freebsd-x64-1.32.0.tgz", { "os": "freebsd", "cpu": "x64" }, "sha512-JCTigedEksZk3tHTTthnMdVfGf61Fky8Ji2E4YjUTEQX14xiy/lTzXnu1vwiZe3bYe0q+SpsSH/CTeDXK6WHig=="],
|
||||
|
||||
"lightningcss-linux-arm-gnueabihf": ["lightningcss-linux-arm-gnueabihf@1.32.0", "https://registry.npmmirror.com/lightningcss-linux-arm-gnueabihf/-/lightningcss-linux-arm-gnueabihf-1.32.0.tgz", { "os": "linux", "cpu": "arm" }, "sha512-x6rnnpRa2GL0zQOkt6rts3YDPzduLpWvwAF6EMhXFVZXD4tPrBkEFqzGowzCsIWsPjqSK+tyNEODUBXeeVHSkw=="],
|
||||
|
||||
"lightningcss-linux-arm64-gnu": ["lightningcss-linux-arm64-gnu@1.32.0", "https://registry.npmmirror.com/lightningcss-linux-arm64-gnu/-/lightningcss-linux-arm64-gnu-1.32.0.tgz", { "os": "linux", "cpu": "arm64" }, "sha512-0nnMyoyOLRJXfbMOilaSRcLH3Jw5z9HDNGfT/gwCPgaDjnx0i8w7vBzFLFR1f6CMLKF8gVbebmkUN3fa/kQJpQ=="],
|
||||
|
||||
"lightningcss-linux-arm64-musl": ["lightningcss-linux-arm64-musl@1.32.0", "https://registry.npmmirror.com/lightningcss-linux-arm64-musl/-/lightningcss-linux-arm64-musl-1.32.0.tgz", { "os": "linux", "cpu": "arm64" }, "sha512-UpQkoenr4UJEzgVIYpI80lDFvRmPVg6oqboNHfoH4CQIfNA+HOrZ7Mo7KZP02dC6LjghPQJeBsvXhJod/wnIBg=="],
|
||||
|
||||
"lightningcss-linux-x64-gnu": ["lightningcss-linux-x64-gnu@1.32.0", "https://registry.npmmirror.com/lightningcss-linux-x64-gnu/-/lightningcss-linux-x64-gnu-1.32.0.tgz", { "os": "linux", "cpu": "x64" }, "sha512-V7Qr52IhZmdKPVr+Vtw8o+WLsQJYCTd8loIfpDaMRWGUZfBOYEJeyJIkqGIDMZPwPx24pUMfwSxxI8phr/MbOA=="],
|
||||
|
||||
"lightningcss-linux-x64-musl": ["lightningcss-linux-x64-musl@1.32.0", "https://registry.npmmirror.com/lightningcss-linux-x64-musl/-/lightningcss-linux-x64-musl-1.32.0.tgz", { "os": "linux", "cpu": "x64" }, "sha512-bYcLp+Vb0awsiXg/80uCRezCYHNg1/l3mt0gzHnWV9XP1W5sKa5/TCdGWaR/zBM2PeF/HbsQv/j2URNOiVuxWg=="],
|
||||
|
||||
"lightningcss-win32-arm64-msvc": ["lightningcss-win32-arm64-msvc@1.32.0", "https://registry.npmmirror.com/lightningcss-win32-arm64-msvc/-/lightningcss-win32-arm64-msvc-1.32.0.tgz", { "os": "win32", "cpu": "arm64" }, "sha512-8SbC8BR40pS6baCM8sbtYDSwEVQd4JlFTOlaD3gWGHfThTcABnNDBda6eTZeqbofalIJhFx0qKzgHJmcPTnGdw=="],
|
||||
|
||||
"lightningcss-win32-x64-msvc": ["lightningcss-win32-x64-msvc@1.32.0", "https://registry.npmmirror.com/lightningcss-win32-x64-msvc/-/lightningcss-win32-x64-msvc-1.32.0.tgz", { "os": "win32", "cpu": "x64" }, "sha512-Amq9B/SoZYdDi1kFrojnoqPLxYhQ4Wo5XiL8EVJrVsB8ARoC1PWW6VGtT0WKCemjy8aC+louJnjS7U18x3b06Q=="],
|
||||
|
||||
"locate-path": ["locate-path@5.0.0", "https://registry.npmmirror.com/locate-path/-/locate-path-5.0.0.tgz", { "dependencies": { "p-locate": "^4.1.0" } }, "sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g=="],
|
||||
|
||||
"lodash-es": ["lodash-es@4.17.23", "https://registry.npmmirror.com/lodash-es/-/lodash-es-4.17.23.tgz", {}, "sha512-kVI48u3PZr38HdYz98UmfPnXl2DXrpdctLrFLCd3kOx1xUkOmpFPx7gCWWM5MPkL/fD8zb+Ph0QzjGFs4+hHWg=="],
|
||||
@@ -1436,8 +1051,6 @@
|
||||
|
||||
"lru-cache": ["lru-cache@11.2.7", "https://registry.npmmirror.com/lru-cache/-/lru-cache-11.2.7.tgz", {}, "sha512-aY/R+aEsRelme17KGQa/1ZSIpLpNYYrhcrepKTZgE+W3WM16YMCaPwOHLHsmopZHELU0Ojin1lPVxKR0MihncA=="],
|
||||
|
||||
"magic-string": ["magic-string@0.30.21", "https://registry.npmmirror.com/magic-string/-/magic-string-0.30.21.tgz", { "dependencies": { "@jridgewell/sourcemap-codec": "^1.5.5" } }, "sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ=="],
|
||||
|
||||
"marked": ["marked@17.0.5", "https://registry.npmmirror.com/marked/-/marked-17.0.5.tgz", { "bin": { "marked": "bin/marked.js" } }, "sha512-6hLvc0/JEbRjRgzI6wnT2P1XuM1/RrrDEX0kPt0N7jGm1133g6X7DlxFasUIx+72aKAr904GTxhSLDrd5DIlZg=="],
|
||||
|
||||
"math-intrinsics": ["math-intrinsics@1.1.0", "https://registry.npmmirror.com/math-intrinsics/-/math-intrinsics-1.1.0.tgz", {}, "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g=="],
|
||||
@@ -1468,16 +1081,12 @@
|
||||
|
||||
"modifiers-napi": ["modifiers-napi@workspace:packages/modifiers-napi"],
|
||||
|
||||
"module-details-from-path": ["module-details-from-path@1.0.4", "https://registry.npmmirror.com/module-details-from-path/-/module-details-from-path-1.0.4.tgz", {}, "sha512-EGWKgxALGMgzvxYF1UyGTy0HXX/2vHLkw6+NvDKW2jypWbHpjQuj4UMcqQWXHERJhVGKikolT06G3bcKe4fi7w=="],
|
||||
|
||||
"ms": ["ms@2.1.3", "https://registry.npmmirror.com/ms/-/ms-2.1.3.tgz", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="],
|
||||
|
||||
"mute-stream": ["mute-stream@1.0.0", "https://registry.npmmirror.com/mute-stream/-/mute-stream-1.0.0.tgz", {}, "sha512-avsJQhyd+680gKXyG/sQc0nXaC6rBkPOfyHYcFb9+hdkqQkR9bdnkJ0AMZhke0oesPqIO+mFFJ+IdBc7mst4IA=="],
|
||||
|
||||
"mz": ["mz@2.7.0", "https://registry.npmmirror.com/mz/-/mz-2.7.0.tgz", { "dependencies": { "any-promise": "^1.0.0", "object-assign": "^4.0.1", "thenify-all": "^1.0.0" } }, "sha512-z81GNO7nnYMEhrGh9LeymoE4+Yr0Wn5McHIZMK5cfQCl+NDX08sCZgUc9/6MHni9IWuFLm1Z3HTCXu2z9fN62Q=="],
|
||||
|
||||
"nanoid": ["nanoid@3.3.11", "https://registry.npmmirror.com/nanoid/-/nanoid-3.3.11.tgz", { "bin": { "nanoid": "bin/nanoid.cjs" } }, "sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w=="],
|
||||
|
||||
"negotiator": ["negotiator@1.0.0", "https://registry.npmmirror.com/negotiator/-/negotiator-1.0.0.tgz", {}, "sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg=="],
|
||||
|
||||
"node-domexception": ["node-domexception@1.0.0", "https://registry.npmmirror.com/node-domexception/-/node-domexception-1.0.0.tgz", {}, "sha512-/jKZoMpw0F8GRwl4/eLROPA3cfcXtLApP0QzLmUT/HuPCZWyB7IY9ZrMeKw2O/nFIqPQB3PVM9aYm0F312AXDQ=="],
|
||||
@@ -1486,8 +1095,6 @@
|
||||
|
||||
"node-forge": ["node-forge@1.4.0", "https://registry.npmmirror.com/node-forge/-/node-forge-1.4.0.tgz", {}, "sha512-LarFH0+6VfriEhqMMcLX2F7SwSXeWwnEAJEsYm5QKWchiVYVvJyV9v7UDvUv+w5HO23ZpQTXDv/GxdDdMyOuoQ=="],
|
||||
|
||||
"node-releases": ["node-releases@2.0.37", "https://registry.npmmirror.com/node-releases/-/node-releases-2.0.37.tgz", {}, "sha512-1h5gKZCF+pO/o3Iqt5Jp7wc9rH3eJJ0+nh/CIoiRwjRxde/hAHyLPXYN4V3CqKAbiZPSeJFSWHmJsbkicta0Eg=="],
|
||||
|
||||
"npm-run-path": ["npm-run-path@6.0.0", "https://registry.npmmirror.com/npm-run-path/-/npm-run-path-6.0.0.tgz", { "dependencies": { "path-key": "^4.0.0", "unicorn-magic": "^0.3.0" } }, "sha512-9qny7Z9DsQU8Ou39ERsPU4OZQlSTP47ShQzuKZ6PRXpYLtIFgl/DEBYEXKlvcEa+9tHVcK8CF81Y2V72qaZhWA=="],
|
||||
|
||||
"object-assign": ["object-assign@4.1.1", "https://registry.npmmirror.com/object-assign/-/object-assign-4.1.1.tgz", {}, "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg=="],
|
||||
@@ -1500,8 +1107,6 @@
|
||||
|
||||
"open": ["open@10.2.0", "https://registry.npmmirror.com/open/-/open-10.2.0.tgz", { "dependencies": { "default-browser": "^5.2.1", "define-lazy-prop": "^3.0.0", "is-inside-container": "^1.0.0", "wsl-utils": "^0.1.0" } }, "sha512-YgBpdJHPyQ2UE5x+hlSXcnejzAvD0b22U2OuAP+8OnlJT+PjWPxtgmGqKKc+RgTM63U9gN0YzrYc71R2WT/hTA=="],
|
||||
|
||||
"openai": ["openai@6.33.0", "https://registry.npmmirror.com/openai/-/openai-6.33.0.tgz", { "peerDependencies": { "ws": "^8.18.0", "zod": "^3.25 || ^4.0" }, "optionalPeers": ["ws", "zod"], "bin": { "openai": "bin/cli" } }, "sha512-xAYN1W3YsDXJWA5F277135YfkEk6H7D3D6vWwRhJ3OEkzRgcyK8z/P5P9Gyi/wB4N8kK9kM5ZjprfvyHagKmpw=="],
|
||||
|
||||
"os-tmpdir": ["os-tmpdir@1.0.2", "https://registry.npmmirror.com/os-tmpdir/-/os-tmpdir-1.0.2.tgz", {}, "sha512-D2FR03Vir7FIu45XBY20mTb+/ZSWB00sjU9jdQXt83gDrI4Ztz5Fs7/yy74g2N5SVQY4xY1qDr4rNddwYRVX0g=="],
|
||||
|
||||
"oxc-parser": ["oxc-parser@0.121.0", "https://registry.npmmirror.com/oxc-parser/-/oxc-parser-0.121.0.tgz", { "dependencies": { "@oxc-project/types": "^0.121.0" }, "optionalDependencies": { "@oxc-parser/binding-android-arm-eabi": "0.121.0", "@oxc-parser/binding-android-arm64": "0.121.0", "@oxc-parser/binding-darwin-arm64": "0.121.0", "@oxc-parser/binding-darwin-x64": "0.121.0", "@oxc-parser/binding-freebsd-x64": "0.121.0", "@oxc-parser/binding-linux-arm-gnueabihf": "0.121.0", "@oxc-parser/binding-linux-arm-musleabihf": "0.121.0", "@oxc-parser/binding-linux-arm64-gnu": "0.121.0", "@oxc-parser/binding-linux-arm64-musl": "0.121.0", "@oxc-parser/binding-linux-ppc64-gnu": "0.121.0", "@oxc-parser/binding-linux-riscv64-gnu": "0.121.0", "@oxc-parser/binding-linux-riscv64-musl": "0.121.0", "@oxc-parser/binding-linux-s390x-gnu": "0.121.0", "@oxc-parser/binding-linux-x64-gnu": "0.121.0", "@oxc-parser/binding-linux-x64-musl": "0.121.0", "@oxc-parser/binding-openharmony-arm64": "0.121.0", "@oxc-parser/binding-wasm32-wasi": "0.121.0", "@oxc-parser/binding-win32-arm64-msvc": "0.121.0", "@oxc-parser/binding-win32-ia32-msvc": "0.121.0", "@oxc-parser/binding-win32-x64-msvc": "0.121.0" } }, "sha512-ek9o58+SCv6AV7nchiAcUJy1DNE2CC5WRdBcO0mF+W4oRjNQfPO7b3pLjTHSFECpHkKGOZSQxx3hk8viIL5YCg=="],
|
||||
@@ -1534,12 +1139,6 @@
|
||||
|
||||
"path-to-regexp": ["path-to-regexp@8.4.1", "https://registry.npmmirror.com/path-to-regexp/-/path-to-regexp-8.4.1.tgz", {}, "sha512-fvU78fIjZ+SBM9YwCknCvKOUKkLVqtWDVctl0s7xIqfmfb38t2TT4ZU2gHm+Z8xGwgW+QWEU3oQSAzIbo89Ggw=="],
|
||||
|
||||
"pg-int8": ["pg-int8@1.0.1", "https://registry.npmmirror.com/pg-int8/-/pg-int8-1.0.1.tgz", {}, "sha512-WCtabS6t3c8SkpDBUlb1kjOs7l66xsGdKpIPZsg4wR+B3+u9UAum2odSsF9tnvxg80h4ZxLWMy4pRjOsFIqQpw=="],
|
||||
|
||||
"pg-protocol": ["pg-protocol@1.13.0", "https://registry.npmmirror.com/pg-protocol/-/pg-protocol-1.13.0.tgz", {}, "sha512-zzdvXfS6v89r6v7OcFCHfHlyG/wvry1ALxZo4LqgUoy7W9xhBDMaqOuMiF3qEV45VqsN6rdlcehHrfDtlCPc8w=="],
|
||||
|
||||
"pg-types": ["pg-types@2.2.0", "https://registry.npmmirror.com/pg-types/-/pg-types-2.2.0.tgz", { "dependencies": { "pg-int8": "1.0.1", "postgres-array": "~2.0.0", "postgres-bytea": "~1.0.0", "postgres-date": "~1.0.4", "postgres-interval": "^1.1.0" } }, "sha512-qTAAlrEsl8s4OiEQY69wDvcMIdQN6wdz5ojQiOy6YRMuynxenON0O5oCpJI6lshc6scgAY8qvJ2On/p+CXY0GA=="],
|
||||
|
||||
"picocolors": ["picocolors@1.1.1", "https://registry.npmmirror.com/picocolors/-/picocolors-1.1.1.tgz", {}, "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA=="],
|
||||
|
||||
"picomatch": ["picomatch@4.0.4", "https://registry.npmmirror.com/picomatch/-/picomatch-4.0.4.tgz", {}, "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A=="],
|
||||
@@ -1550,16 +1149,6 @@
|
||||
|
||||
"pngjs": ["pngjs@5.0.0", "https://registry.npmmirror.com/pngjs/-/pngjs-5.0.0.tgz", {}, "sha512-40QW5YalBNfQo5yRYmiw7Yz6TKKVr3h6970B2YE+3fQpsWcrbj1PzJgxeJ19DRQjhMbKPIuMY8rFaXc8moolVw=="],
|
||||
|
||||
"postcss": ["postcss@8.5.8", "https://registry.npmmirror.com/postcss/-/postcss-8.5.8.tgz", { "dependencies": { "nanoid": "^3.3.11", "picocolors": "^1.1.1", "source-map-js": "^1.2.1" } }, "sha512-OW/rX8O/jXnm82Ey1k44pObPtdblfiuWnrd8X7GJ7emImCOstunGbXUpp7HdBrFQX6rJzn3sPT397Wp5aCwCHg=="],
|
||||
|
||||
"postgres-array": ["postgres-array@2.0.0", "https://registry.npmmirror.com/postgres-array/-/postgres-array-2.0.0.tgz", {}, "sha512-VpZrUqU5A69eQyW2c5CA1jtLecCsN2U/bD6VilrFDWq5+5UIEVO7nazS3TEcHf1zuPYO/sqGvUvW62g86RXZuA=="],
|
||||
|
||||
"postgres-bytea": ["postgres-bytea@1.0.1", "https://registry.npmmirror.com/postgres-bytea/-/postgres-bytea-1.0.1.tgz", {}, "sha512-5+5HqXnsZPE65IJZSMkZtURARZelel2oXUEO8rH83VS/hxH5vv1uHquPg5wZs8yMAfdv971IU+kcPUczi7NVBQ=="],
|
||||
|
||||
"postgres-date": ["postgres-date@1.0.7", "https://registry.npmmirror.com/postgres-date/-/postgres-date-1.0.7.tgz", {}, "sha512-suDmjLVQg78nMK2UZ454hAG+OAW+HQPZ6n++TNDUX+L0+uUlLywnoxJKDou51Zm+zTCjrCl0Nq6J9C5hP9vK/Q=="],
|
||||
|
||||
"postgres-interval": ["postgres-interval@1.2.0", "https://registry.npmmirror.com/postgres-interval/-/postgres-interval-1.2.0.tgz", { "dependencies": { "xtend": "^4.0.0" } }, "sha512-9ZhXKM/rw350N1ovuWHbGxnGh/SNJ4cnxHiM0rxE4VN41wsg8P8zWn9hv/buK00RP4WvlOyr/RBDiptyxVbkZQ=="],
|
||||
|
||||
"pretty-bytes": ["pretty-bytes@5.6.0", "https://registry.npmmirror.com/pretty-bytes/-/pretty-bytes-5.6.0.tgz", {}, "sha512-FFw039TmrBqFK8ma/7OL3sDz/VytdtJr044/QUJtH0wK9lb9jLq9tJyIxUwtQJHwar2BqtiA4iCWSwo9JLkzFg=="],
|
||||
|
||||
"pretty-ms": ["pretty-ms@9.3.0", "https://registry.npmmirror.com/pretty-ms/-/pretty-ms-9.3.0.tgz", { "dependencies": { "parse-ms": "^4.0.0" } }, "sha512-gjVS5hOP+M3wMm5nmNOucbIrqudzs9v/57bWRHQWLYklXqoXKrVfYW2W9+glfGsqtPgpiz5WwyEEB+ksXIx3gQ=="],
|
||||
@@ -1586,20 +1175,14 @@
|
||||
|
||||
"react-compiler-runtime": ["react-compiler-runtime@1.0.0", "https://registry.npmmirror.com/react-compiler-runtime/-/react-compiler-runtime-1.0.0.tgz", { "peerDependencies": { "react": "^17.0.0 || ^18.0.0 || ^19.0.0 || ^0.0.0-experimental" } }, "sha512-rRfjYv66HlG8896yPUDONgKzG5BxZD1nV9U6rkm+7VCuvQc903C4MjcoZR4zPw53IKSOX9wMQVpA1IAbRtzQ7w=="],
|
||||
|
||||
"react-dom": ["react-dom@19.2.4", "https://registry.npmmirror.com/react-dom/-/react-dom-19.2.4.tgz", { "dependencies": { "scheduler": "^0.27.0" }, "peerDependencies": { "react": "^19.2.4" } }, "sha512-AXJdLo8kgMbimY95O2aKQqsz2iWi9jMgKJhRBAxECE4IFxfcazB2LmzloIoibJI3C12IlY20+KFaLv+71bUJeQ=="],
|
||||
|
||||
"react-reconciler": ["react-reconciler@0.33.0", "https://registry.npmmirror.com/react-reconciler/-/react-reconciler-0.33.0.tgz", { "dependencies": { "scheduler": "^0.27.0" }, "peerDependencies": { "react": "^19.2.0" } }, "sha512-KetWRytFv1epdpJc3J4G75I4WrplZE5jOL7Yq0p34+OVOKF4Se7WrdIdVC45XsSSmUTlht2FM/fM1FZb1mfQeA=="],
|
||||
|
||||
"react-refresh": ["react-refresh@0.17.0", "https://registry.npmmirror.com/react-refresh/-/react-refresh-0.17.0.tgz", {}, "sha512-z6F7K9bV85EfseRCp2bzrpyQ0Gkw1uLoCel9XBVWPg/TjRj94SkJzUTGfOa4bs7iJvBWtQG0Wq7wnI0syw3EBQ=="],
|
||||
|
||||
"readdirp": ["readdirp@5.0.0", "https://registry.npmmirror.com/readdirp/-/readdirp-5.0.0.tgz", {}, "sha512-9u/XQ1pvrQtYyMpZe7DXKv2p5CNvyVwzUB6uhLAnQwHMSgKMBR62lc7AHljaeteeHXn11XTAaLLUVZYVZyuRBQ=="],
|
||||
|
||||
"require-directory": ["require-directory@2.1.1", "https://registry.npmmirror.com/require-directory/-/require-directory-2.1.1.tgz", {}, "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q=="],
|
||||
|
||||
"require-from-string": ["require-from-string@2.0.2", "https://registry.npmmirror.com/require-from-string/-/require-from-string-2.0.2.tgz", {}, "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw=="],
|
||||
|
||||
"require-in-the-middle": ["require-in-the-middle@8.0.1", "https://registry.npmmirror.com/require-in-the-middle/-/require-in-the-middle-8.0.1.tgz", { "dependencies": { "debug": "^4.3.5", "module-details-from-path": "^1.0.3" } }, "sha512-QT7FVMXfWOYFbeRBF6nu+I6tr2Tf3u0q8RIEjNob/heKY/nh7drD/k7eeMFmSQgnTtCzLDcCu/XEnpW2wk4xCQ=="],
|
||||
|
||||
"require-main-filename": ["require-main-filename@2.0.0", "https://registry.npmmirror.com/require-main-filename/-/require-main-filename-2.0.0.tgz", {}, "sha512-NKN5kMDylKuldxYLSUfrbo5Tuzh4hd+2E8NPPX02mZtn1VuREQToYe/ZdlJy+J3uCpfaiGF05e7B8W0iXbQHmg=="],
|
||||
|
||||
"resolve-pkg-maps": ["resolve-pkg-maps@1.0.0", "https://registry.npmmirror.com/resolve-pkg-maps/-/resolve-pkg-maps-1.0.0.tgz", {}, "sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw=="],
|
||||
@@ -1608,8 +1191,6 @@
|
||||
|
||||
"reusify": ["reusify@1.1.0", "https://registry.npmmirror.com/reusify/-/reusify-1.1.0.tgz", {}, "sha512-g6QUff04oZpHs0eG5p83rFLhHeV00ug/Yf9nZM6fLeUrPguBTkTQOdpAWWspMh55TZfVQDPaN3NQJfbVRAxdIw=="],
|
||||
|
||||
"rollup": ["rollup@4.60.1", "https://registry.npmmirror.com/rollup/-/rollup-4.60.1.tgz", { "dependencies": { "@types/estree": "1.0.8" }, "optionalDependencies": { "@rollup/rollup-android-arm-eabi": "4.60.1", "@rollup/rollup-android-arm64": "4.60.1", "@rollup/rollup-darwin-arm64": "4.60.1", "@rollup/rollup-darwin-x64": "4.60.1", "@rollup/rollup-freebsd-arm64": "4.60.1", "@rollup/rollup-freebsd-x64": "4.60.1", "@rollup/rollup-linux-arm-gnueabihf": "4.60.1", "@rollup/rollup-linux-arm-musleabihf": "4.60.1", "@rollup/rollup-linux-arm64-gnu": "4.60.1", "@rollup/rollup-linux-arm64-musl": "4.60.1", "@rollup/rollup-linux-loong64-gnu": "4.60.1", "@rollup/rollup-linux-loong64-musl": "4.60.1", "@rollup/rollup-linux-ppc64-gnu": "4.60.1", "@rollup/rollup-linux-ppc64-musl": "4.60.1", "@rollup/rollup-linux-riscv64-gnu": "4.60.1", "@rollup/rollup-linux-riscv64-musl": "4.60.1", "@rollup/rollup-linux-s390x-gnu": "4.60.1", "@rollup/rollup-linux-x64-gnu": "4.60.1", "@rollup/rollup-linux-x64-musl": "4.60.1", "@rollup/rollup-openbsd-x64": "4.60.1", "@rollup/rollup-openharmony-arm64": "4.60.1", "@rollup/rollup-win32-arm64-msvc": "4.60.1", "@rollup/rollup-win32-ia32-msvc": "4.60.1", "@rollup/rollup-win32-x64-gnu": "4.60.1", "@rollup/rollup-win32-x64-msvc": "4.60.1", "fsevents": "~2.3.2" }, "bin": { "rollup": "dist/bin/rollup" } }, "sha512-VmtB2rFU/GroZ4oL8+ZqXgSA38O6GR8KSIvWmEFv63pQ0G6KaBH9s07PO8XTXP4vI+3UJUEypOfjkGfmSBBR0w=="],
|
||||
|
||||
"router": ["router@2.2.0", "https://registry.npmmirror.com/router/-/router-2.2.0.tgz", { "dependencies": { "debug": "^4.4.0", "depd": "^2.0.0", "is-promise": "^4.0.0", "parseurl": "^1.3.3", "path-to-regexp": "^8.0.0" } }, "sha512-nLTrUKm2UyiL7rlhapu/Zl45FwNgkZGaCpZbIHajDYgwlJCOzLSk+cIPAnsEqV955GjILJnKbdQC1nVPz+gAYQ=="],
|
||||
|
||||
"run-applescript": ["run-applescript@7.1.0", "https://registry.npmmirror.com/run-applescript/-/run-applescript-7.1.0.tgz", {}, "sha512-DPe5pVFaAsinSaV6QjQ6gdiedWDcRCbUuiQfQa2wmWV7+xC9bGulGI8+TdRmoFkAPaBXk8CrAbnlY2ISniJ47Q=="],
|
||||
@@ -1654,8 +1235,6 @@
|
||||
|
||||
"smol-toml": ["smol-toml@1.6.1", "https://registry.npmmirror.com/smol-toml/-/smol-toml-1.6.1.tgz", {}, "sha512-dWUG8F5sIIARXih1DTaQAX4SsiTXhInKf1buxdY9DIg4ZYPZK5nGM1VRIYmEbDbsHt7USo99xSLFu5Q1IqTmsg=="],
|
||||
|
||||
"source-map-js": ["source-map-js@1.2.1", "https://registry.npmmirror.com/source-map-js/-/source-map-js-1.2.1.tgz", {}, "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA=="],
|
||||
|
||||
"ssri": ["ssri@13.0.1", "https://registry.npmmirror.com/ssri/-/ssri-13.0.1.tgz", { "dependencies": { "minipass": "^7.0.3" } }, "sha512-QUiRf1+u9wPTL/76GTYlKttDEBWV1ga9ZXW8BG6kfdeyyM8LGPix9gROyg9V2+P0xNyF3X2Go526xKFdMZrHSQ=="],
|
||||
|
||||
"stack-utils": ["stack-utils@2.0.6", "https://registry.npmmirror.com/stack-utils/-/stack-utils-2.0.6.tgz", { "dependencies": { "escape-string-regexp": "^2.0.0" } }, "sha512-XlkWvfIm6RmsWtNJx+uqtKLS8eqFbxUg0ZzLXqY0caEy9l7hruX8IpiDnjsLavoBgqCCR71TqWO8MaXYheJ3RQ=="],
|
||||
@@ -1678,16 +1257,10 @@
|
||||
|
||||
"tagged-tag": ["tagged-tag@1.0.0", "https://registry.npmmirror.com/tagged-tag/-/tagged-tag-1.0.0.tgz", {}, "sha512-yEFYrVhod+hdNyx7g5Bnkkb0G6si8HJurOoOEgC8B/O0uXLHlaey/65KRv6cuWBNhBgHKAROVpc7QyYqE5gFng=="],
|
||||
|
||||
"tailwindcss": ["tailwindcss@4.2.2", "https://registry.npmmirror.com/tailwindcss/-/tailwindcss-4.2.2.tgz", {}, "sha512-KWBIxs1Xb6NoLdMVqhbhgwZf2PGBpPEiwOqgI4pFIYbNTfBXiKYyWoTsXgBQ9WFg/OlhnvHaY+AEpW7wSmFo2Q=="],
|
||||
|
||||
"tapable": ["tapable@2.3.2", "https://registry.npmmirror.com/tapable/-/tapable-2.3.2.tgz", {}, "sha512-1MOpMXuhGzGL5TTCZFItxCc0AARf1EZFQkGqMm7ERKj8+Hgr5oLvJOVFcC+lRmR8hCe2S3jC4T5D7Vg/d7/fhA=="],
|
||||
|
||||
"thenify": ["thenify@3.3.1", "https://registry.npmmirror.com/thenify/-/thenify-3.3.1.tgz", { "dependencies": { "any-promise": "^1.0.0" } }, "sha512-RVZSIV5IG10Hk3enotrhvz0T9em6cyHBLkH/YAZuKqd8hRkKhSfCGIcP2KUY0EPxndzANBmNllzWPwak+bheSw=="],
|
||||
|
||||
"thenify-all": ["thenify-all@1.6.0", "https://registry.npmmirror.com/thenify-all/-/thenify-all-1.6.0.tgz", { "dependencies": { "thenify": ">= 3.1.0 < 4" } }, "sha512-RNxQH/qI8/t3thXJDwcstUO4zeqo64+Uy/+sNVRBx4Xn2OX+OZ9oP+iJnNFqplFra2ZUVeKCSa2oVWi3T4uVmA=="],
|
||||
|
||||
"tinyglobby": ["tinyglobby@0.2.15", "https://registry.npmmirror.com/tinyglobby/-/tinyglobby-0.2.15.tgz", { "dependencies": { "fdir": "^6.5.0", "picomatch": "^4.0.3" } }, "sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ=="],
|
||||
|
||||
"tmp": ["tmp@0.0.33", "https://registry.npmmirror.com/tmp/-/tmp-0.0.33.tgz", { "dependencies": { "os-tmpdir": "~1.0.2" } }, "sha512-jRCJlojKnZ3addtTOjdIqoRuPEKBvNXcGYqzO6zWZX8KfKEpnGY5jfggJQ3EjKuu8D4bJRr0y+cYJFmYbImXGw=="],
|
||||
|
||||
"to-regex-range": ["to-regex-range@5.0.1", "https://registry.npmmirror.com/to-regex-range/-/to-regex-range-5.0.1.tgz", { "dependencies": { "is-number": "^7.0.0" } }, "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ=="],
|
||||
@@ -1722,18 +1295,14 @@
|
||||
|
||||
"unpipe": ["unpipe@1.0.0", "https://registry.npmmirror.com/unpipe/-/unpipe-1.0.0.tgz", {}, "sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ=="],
|
||||
|
||||
"update-browserslist-db": ["update-browserslist-db@1.2.3", "https://registry.npmmirror.com/update-browserslist-db/-/update-browserslist-db-1.2.3.tgz", { "dependencies": { "escalade": "^3.2.0", "picocolors": "^1.1.1" }, "peerDependencies": { "browserslist": ">= 4.21.0" }, "bin": { "update-browserslist-db": "cli.js" } }, "sha512-Js0m9cx+qOgDxo0eMiFGEueWztz+d4+M3rGlmKPT+T4IS/jP4ylw3Nwpu6cpTTP8R1MAC1kF4VbdLt3ARf209w=="],
|
||||
|
||||
"url-handler-napi": ["url-handler-napi@workspace:packages/url-handler-napi"],
|
||||
|
||||
"usehooks-ts": ["usehooks-ts@3.1.1", "https://registry.npmmirror.com/usehooks-ts/-/usehooks-ts-3.1.1.tgz", { "dependencies": { "lodash.debounce": "^4.0.8" }, "peerDependencies": { "react": "^16.8.0 || ^17 || ^18 || ^19 || ^19.0.0-rc" } }, "sha512-I4diPp9Cq6ieSUH2wu+fDAVQO43xwtulo+fKEidHUwZPnYImbtkTjzIJYcDcJqxgmX31GVqNFURodvcgHcW0pA=="],
|
||||
|
||||
"uuid": ["uuid@11.1.0", "https://registry.npmmirror.com/uuid/-/uuid-11.1.0.tgz", { "bin": { "uuid": "dist/esm/bin/uuid" } }, "sha512-0/A9rDy9P7cJ+8w1c9WD9V//9Wj15Ce2MPz8Ri6032usz+NfePxx5AcN3bN+r6ZL6jEo066/yNYB3tn4pQEx+A=="],
|
||||
"uuid": ["uuid@8.3.2", "https://registry.npmmirror.com/uuid/-/uuid-8.3.2.tgz", { "bin": { "uuid": "dist/bin/uuid" } }, "sha512-+NYs2QeMWy+GWFOEm9xnn6HCDp0l7QBD7ml8zLUmJ+93Q5NF0NocErnwkTkXVFNiX3/fpC6afS8Dhb/gz7R7eg=="],
|
||||
|
||||
"vary": ["vary@1.1.2", "https://registry.npmmirror.com/vary/-/vary-1.1.2.tgz", {}, "sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg=="],
|
||||
|
||||
"vite": ["vite@6.4.2", "https://registry.npmmirror.com/vite/-/vite-6.4.2.tgz", { "dependencies": { "esbuild": "^0.25.0", "fdir": "^6.4.4", "picomatch": "^4.0.2", "postcss": "^8.5.3", "rollup": "^4.34.9", "tinyglobby": "^0.2.13" }, "optionalDependencies": { "fsevents": "~2.3.3" }, "peerDependencies": { "@types/node": "^18.0.0 || ^20.0.0 || >=22.0.0", "jiti": ">=1.21.0", "less": "*", "lightningcss": "^1.21.0", "sass": "*", "sass-embedded": "*", "stylus": "*", "sugarss": "*", "terser": "^5.16.0", "tsx": "^4.8.1", "yaml": "^2.4.2" }, "optionalPeers": ["@types/node", "jiti", "less", "lightningcss", "sass", "sass-embedded", "stylus", "sugarss", "terser", "tsx", "yaml"], "bin": { "vite": "bin/vite.js" } }, "sha512-2N/55r4JDJ4gdrCvGgINMy+HH3iRpNIz8K6SFwVsA+JbQScLiC+clmAxBgwiSPgcG9U15QmvqCGWzMbqda5zGQ=="],
|
||||
|
||||
"vscode-jsonrpc": ["vscode-jsonrpc@8.2.1", "https://registry.npmmirror.com/vscode-jsonrpc/-/vscode-jsonrpc-8.2.1.tgz", {}, "sha512-kdjOSJ2lLIn7r1rtrMbbNCHjyMPfRnowdKjBQ+mGq6NAW5QY2bEZC/khaC5OR8svbbjvLEaIXkOq45e2X9BIbQ=="],
|
||||
|
||||
"vscode-languageserver-protocol": ["vscode-languageserver-protocol@3.17.5", "https://registry.npmmirror.com/vscode-languageserver-protocol/-/vscode-languageserver-protocol-3.17.5.tgz", { "dependencies": { "vscode-jsonrpc": "8.2.0", "vscode-languageserver-types": "3.17.5" } }, "sha512-mb1bvRJN8SVznADSGWM9u/b07H7Ecg0I3OgXDuLdn307rl/J3A9YD6/eYOssqhecL27hK1IPZAsaqh00i/Jljg=="],
|
||||
@@ -1764,8 +1333,6 @@
|
||||
|
||||
"xss": ["xss@1.0.15", "https://registry.npmmirror.com/xss/-/xss-1.0.15.tgz", { "dependencies": { "commander": "^2.20.3", "cssfilter": "0.0.10" }, "bin": { "xss": "bin/xss" } }, "sha512-FVdlVVC67WOIPvfOwhoMETV72f6GbW7aOabBC3WxN/oUdoEMDyLz4OgRv5/gck2ZeNqEQu+Tb0kloovXOfpYVg=="],
|
||||
|
||||
"xtend": ["xtend@4.0.2", "https://registry.npmmirror.com/xtend/-/xtend-4.0.2.tgz", {}, "sha512-LKYU1iAXJXUgAXn9URjiu+MWhyUXHsvfp7mcuYm9dSUKK0/CjtrUwFAxD82/mCWbtLsGjFIad0wIsod4zrTAEQ=="],
|
||||
|
||||
"y18n": ["y18n@5.0.8", "https://registry.npmmirror.com/y18n/-/y18n-5.0.8.tgz", {}, "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA=="],
|
||||
|
||||
"yallist": ["yallist@4.0.0", "https://registry.npmmirror.com/yallist/-/yallist-4.0.0.tgz", {}, "sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A=="],
|
||||
@@ -1794,8 +1361,6 @@
|
||||
|
||||
"@anthropic-ai/vertex-sdk/google-auth-library": ["google-auth-library@9.15.1", "https://registry.npmmirror.com/google-auth-library/-/google-auth-library-9.15.1.tgz", { "dependencies": { "base64-js": "^1.3.0", "ecdsa-sig-formatter": "^1.0.11", "gaxios": "^6.1.1", "gcp-metadata": "^6.1.0", "gtoken": "^7.0.0", "jws": "^4.0.0" } }, "sha512-Jb6Z0+nvECVz+2lzSMt9u98UsoakXxA2HGHMCxh+so3n90XgYWkq5dur19JAJV7ONiJY22yBTyJB1TSkvPq9Ng=="],
|
||||
|
||||
"@anthropic/remote-control-server/typescript": ["typescript@5.9.3", "https://registry.npmmirror.com/typescript/-/typescript-5.9.3.tgz", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
|
||||
|
||||
"@aws-crypto/crc32/@aws-crypto/util": ["@aws-crypto/util@5.2.0", "https://registry.npmmirror.com/@aws-crypto/util/-/util-5.2.0.tgz", { "dependencies": { "@aws-sdk/types": "^3.222.0", "@smithy/util-utf8": "^2.0.0", "tslib": "^2.6.2" } }, "sha512-4RkU9EsI6ZpBve5fseQlGNUWKMa1RLPQ1dnjnQoe07ldfIzcsGb5hC5W0Dm7u423KWzawlrpbjXBrXCEv9zazQ=="],
|
||||
|
||||
"@aws-crypto/sha256-browser/@aws-crypto/sha256-js": ["@aws-crypto/sha256-js@5.2.0", "https://registry.npmmirror.com/@aws-crypto/sha256-js/-/sha256-js-5.2.0.tgz", { "dependencies": { "@aws-crypto/util": "^5.2.0", "@aws-sdk/types": "^3.222.0", "tslib": "^2.6.2" } }, "sha512-FFQQyu7edu4ufvIZ+OadFpHHOt+eSTBaYaki44c+akjg7qZg9oOQeLlk77F6tSYqjDAFClrHJk9tMf0HdVyOvA=="],
|
||||
@@ -1942,16 +1507,6 @@
|
||||
|
||||
"@aws-sdk/xml-builder/@smithy/types": ["@smithy/types@4.13.1", "https://registry.npmmirror.com/@smithy/types/-/types-4.13.1.tgz", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-787F3yzE2UiJIQ+wYW1CVg2odHjmaWLGksnKQHUrK/lYZSEcy1msuLVvxaR/sI2/aDe9U+TBuLsXnr3vod1g0g=="],
|
||||
|
||||
"@azure/msal-node/uuid": ["uuid@8.3.2", "https://registry.npmmirror.com/uuid/-/uuid-8.3.2.tgz", { "bin": { "uuid": "dist/bin/uuid" } }, "sha512-+NYs2QeMWy+GWFOEm9xnn6HCDp0l7QBD7ml8zLUmJ+93Q5NF0NocErnwkTkXVFNiX3/fpC6afS8Dhb/gz7R7eg=="],
|
||||
|
||||
"@babel/core/semver": ["semver@6.3.1", "https://registry.npmmirror.com/semver/-/semver-6.3.1.tgz", { "bin": { "semver": "bin/semver.js" } }, "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA=="],
|
||||
|
||||
"@babel/helper-compilation-targets/lru-cache": ["lru-cache@5.1.1", "https://registry.npmmirror.com/lru-cache/-/lru-cache-5.1.1.tgz", { "dependencies": { "yallist": "^3.0.2" } }, "sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w=="],
|
||||
|
||||
"@babel/helper-compilation-targets/semver": ["semver@6.3.1", "https://registry.npmmirror.com/semver/-/semver-6.3.1.tgz", { "bin": { "semver": "bin/semver.js" } }, "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA=="],
|
||||
|
||||
"@fastify/otel/@opentelemetry/instrumentation": ["@opentelemetry/instrumentation@0.212.0", "https://registry.npmmirror.com/@opentelemetry/instrumentation/-/instrumentation-0.212.0.tgz", { "dependencies": { "@opentelemetry/api-logs": "0.212.0", "import-in-the-middle": "^2.0.6", "require-in-the-middle": "^8.0.0" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-IyXmpNnifNouMOe0I/gX7ENfv2ZCNdYTF0FpCsoBcpbIHzk81Ww9rQTYTnvghszCg7qGrIhNvWC8dhEifgX9Jg=="],
|
||||
|
||||
"@grpc/proto-loader/yargs": ["yargs@17.7.2", "https://registry.npmmirror.com/yargs/-/yargs-17.7.2.tgz", { "dependencies": { "cliui": "^8.0.1", "escalade": "^3.1.1", "get-caller-file": "^2.0.5", "require-directory": "^2.1.1", "string-width": "^4.2.3", "y18n": "^5.0.5", "yargs-parser": "^21.1.1" } }, "sha512-7dSzzRQ++CKnNI/krKnYRV7JKKPUXMEh61soaHKg9mrWEhzFWhFnxPxGl+69cD1Ou63C13NUPCnmIcrvqCuM6w=="],
|
||||
|
||||
"@inquirer/core/@types/node": ["@types/node@22.19.15", "https://registry.npmmirror.com/@types/node/-/node-22.19.15.tgz", { "dependencies": { "undici-types": "~6.21.0" } }, "sha512-F0R/h2+dsy5wJAUe3tAU6oqa2qbWY5TpNfL/RGmo1y38hiyO1w3x2jPtt76wmuaJI4DQnOBu21cNXQ2STIUUWg=="],
|
||||
@@ -1960,8 +1515,6 @@
|
||||
|
||||
"@inquirer/core/wrap-ansi": ["wrap-ansi@6.2.0", "https://registry.npmmirror.com/wrap-ansi/-/wrap-ansi-6.2.0.tgz", { "dependencies": { "ansi-styles": "^4.0.0", "string-width": "^4.1.0", "strip-ansi": "^6.0.0" } }, "sha512-r6lPcBGxZXlIcymEu7InxDMhdW0KDxpLgoFLcguasxCaJ/SOIZwINatK9KY/tf+ZrlywOKU0UDj3ATXUBfxJXA=="],
|
||||
|
||||
"@prisma/instrumentation/@opentelemetry/instrumentation": ["@opentelemetry/instrumentation@0.207.0", "https://registry.npmmirror.com/@opentelemetry/instrumentation/-/instrumentation-0.207.0.tgz", { "dependencies": { "@opentelemetry/api-logs": "0.207.0", "import-in-the-middle": "^2.0.0", "require-in-the-middle": "^8.0.0" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-y6eeli9+TLKnznrR8AZlQMSJT7wILpXH+6EYq5Vf/4Ao+huI7EedxQHwRgVUOMLFbe7VFDvHJrX9/f4lcwnJsA=="],
|
||||
|
||||
"@smithy/config-resolver/@smithy/types": ["@smithy/types@4.13.1", "https://registry.npmmirror.com/@smithy/types/-/types-4.13.1.tgz", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-787F3yzE2UiJIQ+wYW1CVg2odHjmaWLGksnKQHUrK/lYZSEcy1msuLVvxaR/sI2/aDe9U+TBuLsXnr3vod1g0g=="],
|
||||
|
||||
"@smithy/core/@smithy/protocol-http": ["@smithy/protocol-http@5.3.12", "https://registry.npmmirror.com/@smithy/protocol-http/-/protocol-http-5.3.12.tgz", { "dependencies": { "@smithy/types": "^4.13.1", "tslib": "^2.6.2" } }, "sha512-fit0GZK9I1xoRlR4jXmbLhoN0OdEpa96ul8M65XdmXnxXkuMxM0Y8HDT0Fh0Xb4I85MBvBClOzgSrV1X2s1Hxw=="],
|
||||
@@ -2074,18 +1627,6 @@
|
||||
|
||||
"@smithy/util-utf8/@smithy/util-buffer-from": ["@smithy/util-buffer-from@4.2.2", "https://registry.npmmirror.com/@smithy/util-buffer-from/-/util-buffer-from-4.2.2.tgz", { "dependencies": { "@smithy/is-array-buffer": "^4.2.2", "tslib": "^2.6.2" } }, "sha512-FDXD7cvUoFWwN6vtQfEta540Y/YBe5JneK3SoZg9bThSoOAC/eGeYEua6RkBgKjGa/sz6Y+DuBZj3+YEY21y4Q=="],
|
||||
|
||||
"@tailwindcss/oxide-wasm32-wasi/@emnapi/core": ["@emnapi/core@1.9.1", "https://registry.npmmirror.com/@emnapi/core/-/core-1.9.1.tgz", { "dependencies": { "@emnapi/wasi-threads": "1.2.0", "tslib": "^2.4.0" }, "bundled": true }, "sha512-mukuNALVsoix/w1BJwFzwXBN/dHeejQtuVzcDsfOEsdpCumXb/E9j8w11h5S54tT1xhifGfbbSm/ICrObRb3KA=="],
|
||||
|
||||
"@tailwindcss/oxide-wasm32-wasi/@emnapi/runtime": ["@emnapi/runtime@1.9.1", "https://registry.npmmirror.com/@emnapi/runtime/-/runtime-1.9.1.tgz", { "dependencies": { "tslib": "^2.4.0" }, "bundled": true }, "sha512-VYi5+ZVLhpgK4hQ0TAjiQiZ6ol0oe4mBx7mVv7IflsiEp0OWoVsp/+f9Vc1hOhE0TtkORVrI1GvzyreqpgWtkA=="],
|
||||
|
||||
"@tailwindcss/oxide-wasm32-wasi/@emnapi/wasi-threads": ["@emnapi/wasi-threads@1.2.0", "https://registry.npmmirror.com/@emnapi/wasi-threads/-/wasi-threads-1.2.0.tgz", { "dependencies": { "tslib": "^2.4.0" }, "bundled": true }, "sha512-N10dEJNSsUx41Z6pZsXU8FjPjpBEplgH24sfkmITrBED1/U2Esum9F3lfLrMjKHHjmi557zQn7kR9R+XWXu5Rg=="],
|
||||
|
||||
"@tailwindcss/oxide-wasm32-wasi/@napi-rs/wasm-runtime": ["@napi-rs/wasm-runtime@1.1.2", "https://registry.npmmirror.com/@napi-rs/wasm-runtime/-/wasm-runtime-1.1.2.tgz", { "dependencies": { "@tybys/wasm-util": "^0.10.1" }, "peerDependencies": { "@emnapi/core": "^1.7.1", "@emnapi/runtime": "^1.7.1" }, "bundled": true }, "sha512-sNXv5oLJ7ob93xkZ1XnxisYhGYXfaG9f65/ZgYuAu3qt7b3NadcOEhLvx28hv31PgX8SZJRYrAIPQilQmFpLVw=="],
|
||||
|
||||
"@tailwindcss/oxide-wasm32-wasi/@tybys/wasm-util": ["@tybys/wasm-util@0.10.1", "https://registry.npmmirror.com/@tybys/wasm-util/-/wasm-util-0.10.1.tgz", { "dependencies": { "tslib": "^2.4.0" }, "bundled": true }, "sha512-9tTaPJLSiejZKx+Bmog4uSubteqTvFrVrURwkmHixBo0G4seD0zUxp98E1DzUBJxLQ3NPwXrGKDiVjwx/DpPsg=="],
|
||||
|
||||
"@tailwindcss/oxide-wasm32-wasi/tslib": ["tslib@2.8.1", "https://registry.npmmirror.com/tslib/-/tslib-2.8.1.tgz", { "bundled": true }, "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w=="],
|
||||
|
||||
"@typespec/ts-http-runtime/https-proxy-agent": ["https-proxy-agent@7.0.6", "https://registry.npmmirror.com/https-proxy-agent/-/https-proxy-agent-7.0.6.tgz", { "dependencies": { "agent-base": "^7.1.2", "debug": "4" } }, "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw=="],
|
||||
|
||||
"ansi-escapes/type-fest": ["type-fest@0.21.3", "https://registry.npmmirror.com/type-fest/-/type-fest-0.21.3.tgz", {}, "sha512-t0rzBq87m3fVcduHDUFhKmyyX+9eo6WQjZvf51Ea/M0Q7+T374Jp1aUiyUl0GKxp8M/OETVHSDvmkyPgvX+X2w=="],
|
||||
@@ -2174,12 +1715,6 @@
|
||||
|
||||
"@aws-sdk/nested-clients/@smithy/util-base64/@smithy/util-buffer-from": ["@smithy/util-buffer-from@4.2.2", "https://registry.npmmirror.com/@smithy/util-buffer-from/-/util-buffer-from-4.2.2.tgz", { "dependencies": { "@smithy/is-array-buffer": "^4.2.2", "tslib": "^2.6.2" } }, "sha512-FDXD7cvUoFWwN6vtQfEta540Y/YBe5JneK3SoZg9bThSoOAC/eGeYEua6RkBgKjGa/sz6Y+DuBZj3+YEY21y4Q=="],
|
||||
|
||||
"@babel/helper-compilation-targets/lru-cache/yallist": ["yallist@3.1.1", "https://registry.npmmirror.com/yallist/-/yallist-3.1.1.tgz", {}, "sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g=="],
|
||||
|
||||
"@fastify/otel/@opentelemetry/instrumentation/@opentelemetry/api-logs": ["@opentelemetry/api-logs@0.212.0", "https://registry.npmmirror.com/@opentelemetry/api-logs/-/api-logs-0.212.0.tgz", { "dependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-TEEVrLbNROUkYY51sBJGk7lO/OLjuepch8+hmpM6ffMJQ2z/KVCjdHuCFX6fJj8OkJP2zckPjrJzQtXU3IAsFg=="],
|
||||
|
||||
"@fastify/otel/@opentelemetry/instrumentation/import-in-the-middle": ["import-in-the-middle@2.0.6", "https://registry.npmmirror.com/import-in-the-middle/-/import-in-the-middle-2.0.6.tgz", { "dependencies": { "acorn": "^8.15.0", "acorn-import-attributes": "^1.9.5", "cjs-module-lexer": "^2.2.0", "module-details-from-path": "^1.0.4" } }, "sha512-3vZV3jX0XRFW3EJDTwzWoZa+RH1b8eTTx6YOCjglrLyPuepwoBti1k3L2dKwdCUrnVEfc5CuRuGstaC/uQJJaw=="],
|
||||
|
||||
"@grpc/proto-loader/yargs/cliui": ["cliui@8.0.1", "https://registry.npmmirror.com/cliui/-/cliui-8.0.1.tgz", { "dependencies": { "string-width": "^4.2.0", "strip-ansi": "^6.0.1", "wrap-ansi": "^7.0.0" } }, "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ=="],
|
||||
|
||||
"@grpc/proto-loader/yargs/string-width": ["string-width@4.2.3", "https://registry.npmmirror.com/string-width/-/string-width-4.2.3.tgz", { "dependencies": { "emoji-regex": "^8.0.0", "is-fullwidth-code-point": "^3.0.0", "strip-ansi": "^6.0.1" } }, "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g=="],
|
||||
@@ -2194,10 +1729,6 @@
|
||||
|
||||
"@inquirer/core/wrap-ansi/string-width": ["string-width@4.2.3", "https://registry.npmmirror.com/string-width/-/string-width-4.2.3.tgz", { "dependencies": { "emoji-regex": "^8.0.0", "is-fullwidth-code-point": "^3.0.0", "strip-ansi": "^6.0.1" } }, "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g=="],
|
||||
|
||||
"@prisma/instrumentation/@opentelemetry/instrumentation/@opentelemetry/api-logs": ["@opentelemetry/api-logs@0.207.0", "https://registry.npmmirror.com/@opentelemetry/api-logs/-/api-logs-0.207.0.tgz", { "dependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-lAb0jQRVyleQQGiuuvCOTDVspc14nx6XJjP4FspJ1sNARo3Regq4ZZbrc3rN4b1TYSuUCvgH+UXUPug4SLOqEQ=="],
|
||||
|
||||
"@prisma/instrumentation/@opentelemetry/instrumentation/import-in-the-middle": ["import-in-the-middle@2.0.6", "https://registry.npmmirror.com/import-in-the-middle/-/import-in-the-middle-2.0.6.tgz", { "dependencies": { "acorn": "^8.15.0", "acorn-import-attributes": "^1.9.5", "cjs-module-lexer": "^2.2.0", "module-details-from-path": "^1.0.4" } }, "sha512-3vZV3jX0XRFW3EJDTwzWoZa+RH1b8eTTx6YOCjglrLyPuepwoBti1k3L2dKwdCUrnVEfc5CuRuGstaC/uQJJaw=="],
|
||||
|
||||
"@smithy/core/@smithy/util-base64/@smithy/util-buffer-from": ["@smithy/util-buffer-from@4.2.2", "https://registry.npmmirror.com/@smithy/util-buffer-from/-/util-buffer-from-4.2.2.tgz", { "dependencies": { "@smithy/is-array-buffer": "^4.2.2", "tslib": "^2.6.2" } }, "sha512-FDXD7cvUoFWwN6vtQfEta540Y/YBe5JneK3SoZg9bThSoOAC/eGeYEua6RkBgKjGa/sz6Y+DuBZj3+YEY21y4Q=="],
|
||||
|
||||
"@smithy/eventstream-serde-universal/@smithy/eventstream-codec/@aws-crypto/crc32": ["@aws-crypto/crc32@3.0.0", "https://registry.npmmirror.com/@aws-crypto/crc32/-/crc32-3.0.0.tgz", { "dependencies": { "@aws-crypto/util": "^3.0.0", "@aws-sdk/types": "^3.222.0", "tslib": "^1.11.1" } }, "sha512-IzSgsrxUcsrejQbPVilIKy16kAT52EwB6zSaI+M3xxIhKh5+aldEyvI+z6erM7TCLB2BJsFrtHjp6/4/sr+3dA=="],
|
||||
|
||||
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 1.3 MiB |
@@ -1,312 +0,0 @@
|
||||
# 自动更新机制
|
||||
|
||||
## 概述
|
||||
|
||||
Claude Code 拥有一套复杂的多策略自动更新系统，支持三种安装方式、后台静默更新、手动 CLI 命令、服务端版本门控以及更新日志展示。系统设计目标是在最小用户干预下保持 CLI 最新，同时提供回滚和手动控制的兜底手段。
|
||||
|
||||
---
|
||||
|
||||
## 安装类型与更新策略
|
||||
|
||||
更新策略由安装方式决定，通过 `src/utils/doctorDiagnostic.ts` 检测：
|
||||
|
||||
| 安装类型 | 更新策略 | 自动安装？ |
|
||||
|---|---|---|
|
||||
| `native` | 从 GCS/Artifactory 下载二进制文件，通过符号链接激活 | 是（静默） |
|
||||
| `npm-global` | `npm install -g` / `bun install -g` | 是（静默） |
|
||||
| `npm-local` | `npm install` 到 `~/.claude/local/` | 是（静默） |
|
||||
| `package-manager` | 显示通知，附带对应操作系统的升级命令 | 否（仅通知） |
|
||||
| `development` | 不适用 — 执行 `claude update` 时报错 | 不适用 |
|
||||
|
||||
### 策略路由
|
||||
|
||||
`src/components/AutoUpdaterWrapper.tsx` — 挂载在 React/Ink UI 树中 — 检测安装类型并渲染对应的更新组件：
|
||||
|
||||
- `native` → `NativeAutoUpdater`（二进制下载 + 符号链接）
|
||||
- `package-manager` → `PackageManagerAutoUpdater`（仅通知）
|
||||
- 其他 → `AutoUpdater`（基于 JS/npm）
|
||||
|
||||
---
|
||||
|
||||
## 后台自动更新循环
|
||||
|
||||
三个更新组件共享相同的轮询模式：
|
||||
|
||||
```typescript
|
||||
useInterval(checkForUpdates, 30 * 60 * 1000); // 每 30 分钟
|
||||
```
|
||||
|
||||
组件挂载时（即启动时）也会执行一次检查。
|
||||
|
||||
### 前置检查门控
|
||||
|
||||
任何更新尝试之前，系统会依次检查：
|
||||
|
||||
1. **自动更新是否被禁用？** — `getAutoUpdaterDisabledReason()`（`src/utils/config.ts:1735`）
|
||||
- `NODE_ENV === 'development'`
|
||||
- 设置了 `DISABLE_AUTOUPDATER` 环境变量
|
||||
- 仅限必要流量模式
|
||||
- `config.autoUpdates === false`（native 安装的保护模式除外）
|
||||
2. **最大版本上限？** — `getMaxVersion()`（`src/utils/autoUpdater.ts:108`）— 服务端熔断开关，防止更新到已知有问题的版本
|
||||
3. **是否跳过该版本？** — `shouldSkipVersion()`（`src/utils/autoUpdater.ts:145`）— 尊重用户的 `minimumVersion` 设置，防止切换到 stable 频道时发生意外的版本降级
|
||||
|
||||
### Native 自动更新器（`src/components/NativeAutoUpdater.tsx`）
|
||||
|
||||
1. 调用 `src/utils/nativeInstaller/installer.ts` 中的 `installLatest()`
|
||||
2. 通过 `src/utils/nativeInstaller/download.ts` 下载二进制文件（GCS 或 Artifactory）
|
||||
3. 验证 SHA256 校验和（3 次重试，60 秒卡顿检测）
|
||||
4. 将版本化二进制文件存储到 XDG 目录
|
||||
5. 更新符号链接（`~/.local/bin/claude` → 新版本二进制文件）
|
||||
6. 保留最近 2 个版本，清理旧版本
|
||||
7. 将错误分类上报分析（超时、校验和、权限、磁盘空间不足、npm、网络）
|
||||
|
||||
### JS/npm 自动更新器（`src/components/AutoUpdater.tsx`）
|
||||
|
||||
1. 调用 `getLatestVersion()` 获取当前 npm dist-tag
|
||||
2. 通过 semver `gte()` 比较版本
|
||||
3. 根据安装类型路由到本地或全局安装
|
||||
4. 使用文件锁（`acquireLock()` / `releaseLock()`）防止并发更新
|
||||
|
||||
### 包管理器通知器（`src/components/PackageManagerAutoUpdater.tsx`）
|
||||
|
||||
每 30 分钟通过 GCS 存储桶（非 npm）检查更新。**不会自动安装** — 仅显示对应操作系统的升级命令：
|
||||
|
||||
- macOS: `brew upgrade claude-code`
|
||||
- Windows: `winget upgrade Anthropic.ClaudeCode`
|
||||
- Alpine: `apk upgrade claude-code`
|
||||
|
||||
---
|
||||
|
||||
## 启动版本门控
|
||||
|
||||
`src/utils/autoUpdater.ts:70` — `assertMinVersion()`
|
||||
|
||||
从 `src/main.tsx:1775` 在启动时调用：
|
||||
|
||||
```typescript
|
||||
void assertMinVersion();
|
||||
```
|
||||
|
||||
1. 从 GrowthBook 动态配置获取 `tengu_version_config`
|
||||
2. 如果 `MACRO.VERSION < minVersion`，打印错误信息并调用 `gracefulShutdownSync(1)` — 强制用户更新
|
||||
3. 这是一个**硬性门控** — 低于最低版本的 CLI 将无法启动
|
||||
|
||||
---
|
||||
|
||||
## 手动 CLI 命令
|
||||
|
||||
### `claude update` / `claude upgrade`
|
||||
|
||||
**文件**: `src/cli/update.ts`
|
||||
|
||||
完整流程：
|
||||
1. 运行 `getDoctorDiagnostic()` 检查系统健康状态
|
||||
2. 检查是否存在多个安装及配置不一致
|
||||
3. 根据安装类型路由：
|
||||
- `development` → 报错（"开发版本不支持自动更新"）
|
||||
- `package-manager` → 打印对应操作系统的更新命令
|
||||
- `native` → 使用原生安装器的 `updateLatest()`
|
||||
- `npm-local` → 在 `~/.claude/local/` 执行 `npm install`
|
||||
- `npm-global` → 执行 `npm install -g`（含权限检查）
|
||||
4. 报告当前版本、最新版本、成功/失败状态
|
||||
|
||||
### `claude rollback [target]`（仅限内部）
|
||||
|
||||
回滚到之前的版本。支持 `--list`、`--dry-run`、`--safe` 标志。
|
||||
|
||||
### `claude install [target]`
|
||||
|
||||
安装或重新安装原生构建版本。接受可选的版本目标参数。
|
||||
|
||||
### `claude doctor`
|
||||
|
||||
检查自动更新器的健康状态，报告状态、权限和配置信息。
|
||||
|
||||
---
|
||||
|
||||
## 原生安装器架构
|
||||
|
||||
**文件**: `src/utils/nativeInstaller/installer.ts`
|
||||
|
||||
### 二进制文件存储布局
|
||||
|
||||
```
|
||||
~/.local/share/claude-code/
|
||||
├── versions/ # 版本化二进制文件 (claude-1.0.3, claude-1.0.4, ...)
|
||||
├── staging/ # 临时下载暂存区
|
||||
└── locks/ # 基于 PID 和 mtime 的锁文件
|
||||
|
||||
~/.local/bin/claude # 指向当前版本二进制文件的符号链接
|
||||
```
|
||||
|
||||
Windows 系统使用文件复制而非符号链接。
|
||||
|
||||
### 核心操作
|
||||
|
||||
| 函数 | 说明 |
|
||||
|---|---|
|
||||
| `updateLatest()` | 核心更新流程：最大版本上限 → 跳过检查 → 加锁 → 下载 → 安装 → 更新符号链接 |
|
||||
| `installLatest()` | Singleflight 包装版本，防止重复的进行中安装 |
|
||||
| `cleanupOldVersions()` | 保留最近 2 个版本，清理过期的暂存区和临时文件 |
|
||||
| `lockCurrentVersion()` | 进程生命周期锁，防止正在运行的版本被删除 |
|
||||
| `cleanupNpmInstallations()` | 迁移到原生安装时清理旧的 npm 安装 |
|
||||
|
||||
### 下载与校验
|
||||
|
||||
**文件**: `src/utils/nativeInstaller/download.ts`
|
||||
|
||||
1. 路由到 Artifactory（内部用户）或 GCS 存储桶（外部用户）
|
||||
2. 下载二进制文件并跟踪进度
|
||||
3. SHA256 校验和验证
|
||||
4. 60 秒卡顿检测（中止停滞的下载）
|
||||
5. 失败时自动重试 3 次
|
||||
|
||||
---
|
||||
|
||||
## 文件锁机制
|
||||
|
||||
**文件**: `src/utils/autoUpdater.ts:176-268`
|
||||
|
||||
防止并发更新进程破坏安装：
|
||||
|
||||
- 锁文件：`~/.claude/update.lock`（或等效路径）
|
||||
- 5 分钟超时 — 超过 5 分钟的锁被视为过期，强制获取
|
||||
- 进程将其 PID 写入锁文件
|
||||
- `acquireLock()` 和 `releaseLock()` 同时被 JS/npm 和原生安装器使用
|
||||
|
||||
---
|
||||
|
||||
## 配置
|
||||
|
||||
### 设置项
|
||||
|
||||
**文件**: `src/utils/settings/types.ts`
|
||||
|
||||
| 设置项 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `autoUpdatesChannel` | `'latest' \| 'stable'` | 自动更新的发布频道 |
|
||||
| `minimumVersion` | string | 最低版本要求，防止意外的版本降级 |
|
||||
|
||||
### 全局配置
|
||||
|
||||
**文件**: `src/utils/config.ts:191-193`
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `autoUpdates` | boolean | 启用/禁用自动更新（旧版） |
|
||||
| `autoUpdatesProtectedForNative` | boolean | 原生安装始终自动更新 |
|
||||
|
||||
### 配置迁移
|
||||
|
||||
**文件**: `src/migrations/migrateAutoUpdatesToSettings.ts`
|
||||
|
||||
一次性将旧版 `globalConfig.autoUpdates = false` 迁移为 settings 中的 `DISABLE_AUTOUPDATER=1` 环境变量。从 `src/main.tsx:325` 在启动时调用。
|
||||
|
||||
---
|
||||
|
||||
## 更新通知去重
|
||||
|
||||
**文件**: `src/hooks/useUpdateNotification.ts`
|
||||
|
||||
React hook `useUpdateNotification(updatedVersion)` — 确保每次 semver 变更（major.minor.patch）只显示一次"重启以更新"消息，避免同一版本的重复通知。
|
||||
|
||||
---
|
||||
|
||||
## 更新日志
|
||||
|
||||
**文件**: `src/utils/releaseNotes.ts`
|
||||
|
||||
1. 从 `src/setup.ts:387` 在每次启动时调用
|
||||
2. 从 GitHub 获取 changelog
|
||||
3. 缓存到 `~/.claude/cache/changelog.md`
|
||||
4. 展示比 `lastReleaseNotesSeen` 更新的版本的更新日志
|
||||
5. 使用 semver 比较确定需要展示哪些日志
|
||||
|
||||
---
|
||||
|
||||
## 版本比较
|
||||
|
||||
**文件**: `src/utils/semver.ts`
|
||||
|
||||
- 提供 `gt()`、`gte()`、`lt()`、`lte()`、`satisfies()`、`order()`
|
||||
- 在 Bun 环境下使用 `Bun.semver.order()`（快 20 倍）
|
||||
- 在 Node.js 环境下回退到 npm `semver` 包
|
||||
|
||||
---
|
||||
|
||||
## 分析事件
|
||||
|
||||
所有更新相关的遥测数据使用 `tengu_` 前缀的事件：
|
||||
|
||||
| 类别 | 事件 |
|
||||
|---|---|
|
||||
| 版本检查 | `tengu_version_check_success`、`tengu_version_check_failure` |
|
||||
| JS 自动更新器 | `tengu_auto_updater_start/success/fail/up_to_date/lock_contention` |
|
||||
| 原生自动更新器 | `tengu_native_auto_updater_start/success/fail` |
|
||||
| 原生更新 | `tengu_native_update_complete/skipped_max_version/skipped_minimum_version` |
|
||||
| 锁机制 | `tengu_version_lock_acquired/failed`、`tengu_native_update_lock_failed` |
|
||||
| 二进制下载 | `tengu_binary_download_attempt/success/failure`、`tengu_binary_manifest_fetch_failure` |
|
||||
| 清理 | `tengu_native_version_cleanup`、`tengu_native_staging_cleanup`、`tengu_native_stale_locks_cleanup` |
|
||||
| 安装 | `tengu_native_install_package_success/failure`、`tengu_native_install_binary_success/failure` |
|
||||
| 手动更新 | `tengu_update_check` |
|
||||
| 迁移 | `tengu_migrate_autoupdates_to_settings`、`tengu_migrate_autoupdates_error` |
|
||||
|
||||
---
|
||||
|
||||
## 关键文件索引
|
||||
|
||||
| 文件 | 职责 |
|
||||
|---|---|
|
||||
| `src/utils/autoUpdater.ts` | 核心逻辑：版本检查、npm 安装、文件锁、最低/最高版本门控 |
|
||||
| `src/cli/update.ts` | `claude update` 命令处理 |
|
||||
| `src/utils/nativeInstaller/installer.ts` | 原生二进制安装器：下载、版本管理、符号链接、清理 |
|
||||
| `src/utils/nativeInstaller/download.ts` | 从 GCS/Artifactory 下载二进制文件并校验 |
|
||||
| `src/utils/localInstaller.ts` | 本地安装器（`~/.claude/local/`）基于 npm |
|
||||
| `src/components/AutoUpdaterWrapper.tsx` | 基于安装类型的策略路由 |
|
||||
| `src/components/AutoUpdater.tsx` | JS/npm 后台自动更新器（30 分钟间隔） |
|
||||
| `src/components/NativeAutoUpdater.tsx` | 原生二进制后台自动更新器（30 分钟间隔） |
|
||||
| `src/components/PackageManagerAutoUpdater.tsx` | 包管理器通知（30 分钟，仅展示） |
|
||||
| `src/hooks/useUpdateNotification.ts` | 按 semver 去重更新通知 |
|
||||
| `src/utils/releaseNotes.ts` | Changelog 获取、缓存与展示 |
|
||||
| `src/utils/semver.ts` | Semver 版本比较（Bun 原生 + npm 回退） |
|
||||
| `src/utils/doctorDiagnostic.ts` | 安装类型检测与健康诊断 |
|
||||
| `src/utils/config.ts:1735` | `getAutoUpdaterDisabledReason()` — 禁用检查逻辑 |
|
||||
| `src/migrations/migrateAutoUpdatesToSettings.ts` | 旧版配置迁移 |
|
||||
| `src/screens/Doctor.tsx` | Doctor 命令 UI，展示自动更新状态 |
|
||||
|
||||
---
|
||||
|
||||
## 流程图
|
||||
|
||||
```
|
||||
启动阶段
|
||||
├── assertMinVersion() → 版本过低时硬性拦截，拒绝启动
|
||||
├── migrateAutoUpdatesToSettings() → 一次性配置迁移
|
||||
└── checkForReleaseNotes() → 展示新版本的更新日志
|
||||
|
||||
REPL 运行中（每 30 分钟）
|
||||
├── AutoUpdaterWrapper 检测安装类型
|
||||
│
|
||||
├── native → NativeAutoUpdater
|
||||
│ ├── 从 GCS/Artifactory 获取版本
|
||||
│ ├── 检查最大版本上限（服务端控制）
|
||||
│ ├── 检查 minimumVersion 设置（跳过）
|
||||
│ ├── acquireLock()
|
||||
│ ├── downloadAndVerifyBinary()（SHA256 校验，3 次重试）
|
||||
│ ├── 安装到 versions/ 目录
|
||||
│ ├── 更新符号链接
|
||||
│ └── cleanupOldVersions()（保留 2 个版本）
|
||||
│
|
||||
├── npm-global/local → AutoUpdater
|
||||
│ ├── 从 npm registry 获取最新版本
|
||||
│ ├── semver 版本比较
|
||||
│ ├── acquireLock()
|
||||
│ └── npm install -g / 本地安装
|
||||
│
|
||||
└── package-manager → PackageManagerAutoUpdater
|
||||
├── 从 GCS 获取版本
|
||||
└── 显示 "Run: brew upgrade ..."（不自动安装）
|
||||
|
||||
手动操作
|
||||
└── claude update → 完整诊断 + 安装编排
|
||||
```
|
||||
@@ -48,16 +48,15 @@ const messagesForCompact = microcompactResult.messages
|
||||
MicroCompact 不压缩整个对话，而是**清除旧工具输出的内容**。它维护一个白名单：
|
||||
|
||||
```typescript
|
||||
// src/services/compact/microCompact.ts:41-48
|
||||
const COMPACTABLE_TOOLS = new Set([
|
||||
FILE_READ_TOOL_NAME, // 'Read' - 文件读取
|
||||
...SHELL_TOOL_NAMES, // 'Bash' - 命令输出
|
||||
GREP_TOOL_NAME, // 'Grep' - 搜索结果
|
||||
GLOB_TOOL_NAME, // 'Glob' - 文件列表
|
||||
WEB_SEARCH_TOOL_NAME, // 'WebSearch' - 搜索结果
|
||||
WEB_FETCH_TOOL_NAME, // 'WebFetch' - 网页内容
|
||||
FILE_EDIT_TOOL_NAME, // 'Edit' - 编辑输出
|
||||
FILE_WRITE_TOOL_NAME, // 'Write' - 写入输出
|
||||
'Read', // 文件读取
|
||||
'Bash', // 命令输出
|
||||
'Grep', // 搜索结果
|
||||
'Glob', // 文件列表
|
||||
'WebSearch', // 搜索结果
|
||||
'WebFetch', // 网页内容
|
||||
'Edit', // 编辑输出
|
||||
'Write', // 写入输出
|
||||
])
|
||||
```
|
||||
|
||||
@@ -202,31 +201,6 @@ boundaryMarker.compactMetadata.preservedSegment = {
|
||||
|
||||
这在会话恢复时帮助加载器正确重建消息链，避免重复压缩已保留的消息。
|
||||
|
||||
### Microcompact Boundary
|
||||
|
||||
Microcompact 操作使用单独的 boundary 类型，与全量压缩的 `compact_boundary` 不同：
|
||||
|
||||
```typescript
|
||||
// src/utils/messages.ts:4599-4614
|
||||
type SystemMicrocompactBoundaryMessage = {
|
||||
type: 'system'
|
||||
subtype: 'microcompact_boundary'
|
||||
content: 'Context microcompacted'
|
||||
compactMetadata: {
|
||||
trigger: 'auto' // Microcompact 只有自动触发
|
||||
preTokens: number // 压缩前 token 数
|
||||
tokensSaved: number // 节省的 token 数
|
||||
compactedToolIds: string[] // 被压缩的工具 ID 列表
|
||||
clearedAttachmentUUIDs: string[] // 被清除的附件 UUID
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
与 `compact_boundary` 的区别：
|
||||
- **保留原始消息**：Microcompact 仅清除工具输出内容，不删除消息本身
|
||||
- **可追溯性**：`compactedToolIds` 记录了哪些工具结果被清除
|
||||
- **轻量级**：不生成摘要，不调用 API
|
||||
|
||||
## PTL 紧急降级：Prompt Too Long
|
||||
|
||||
当压缩后仍然超出 token 限制（`PROMPT_TOO_LONG` 错误），系统会进入紧急降级路径：
|
||||
|
||||
@@ -43,11 +43,9 @@ export function asSystemPrompt(value: readonly string[]): SystemPrompt {
|
||||
| 阶段 | 内容 | 缓存策略 |
|
||||
|------|------|----------|
|
||||
| **静态区** | Intro Section、System Rules、Doing Tasks、Actions、Using Tools、Tone & Style、Output Efficiency | 可跨组织缓存（`scope: 'global'`） |
|
||||
| **BOUNDARY** | `SYSTEM_PROMPT_DYNAMIC_BOUNDARY = '__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__'` | 分界标记（不发送给 API，仅用于分割静态区与动态区以实现全局缓存） |
|
||||
| **BOUNDARY** | `SYSTEM_PROMPT_DYNAMIC_BOUNDARY = '__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__'` | 分界标记（不发送给 API） |
|
||||
| **动态区** | Session Guidance、Memory、Model Override、Env Info、Language、Output Style、MCP Instructions、Scratchpad、FRC、Summarize Tool Results、Token Budget、Brief | 每次会话不同（`scope: 'org'` 或无缓存） |
|
||||
|
||||
> **Boundary 是什么**：它把 System Prompt 分成"不变的静态区"和"因用户/会话而异的动态区"。静态区对所有用户相同，可获得 `scope: 'global'` 跨组织缓存；动态区每次不同，只能 `scope: 'org'` 或不缓存。它本身是一个特殊字符串，在发送给 API 前被移除，AI 永远看不到。
|
||||
|
||||
### 动态区的 Section 注册表
|
||||
|
||||
动态区通过 `systemPromptSection()` / `DANGEROUS_uncachedSystemPromptSection()` 注册，这两个工厂函数定义于 `src/constants/systemPromptSections.ts`：
|
||||
@@ -90,36 +88,6 @@ DANGEROUS_uncachedSystemPromptSection(
|
||||
|
||||
`appendSystemPrompt` 始终追加到末尾（Override 除外）。
|
||||
|
||||
## Provider 系统概述
|
||||
|
||||
Claude Code 支持多种 API 提供商，分为两大类：
|
||||
|
||||
| 类别 | Provider | 环境变量 | 说明 |
|
||||
|------|----------|---------|------|
|
||||
| **1P (First Party)** | `firstParty` | 默认 | Anthropic 官方 API 直连 |
|
||||
| **3P (Third Party)** | `bedrock` | `CLAUDE_CODE_USE_BEDROCK=1` | AWS Bedrock 托管服务 |
|
||||
| **3P** | `vertex` | `CLAUDE_CODE_USE_VERTEX=1` | Google Vertex AI |
|
||||
| **3P** | `openai` | `CLAUDE_CODE_USE_OPENAI=1` | OpenAI 兼容层（Ollama/DeepSeek/vLLM） |
|
||||
| **3P** | `gemini` | `CLAUDE_CODE_USE_GEMINI=1` | Google Gemini API |
|
||||
| **3P** | `grok` | `CLAUDE_CODE_USE_GROK=1` | xAI Grok |
|
||||
|
||||
Provider 决定了：
|
||||
- **可用的 beta headers**：部分 beta 功能仅限 1P 用户
|
||||
- **缓存策略**：全局缓存 `scope: 'global'` 仅 1P 可用
|
||||
- **Token 计数方式**：Bedrock 有独立的 countTokens 端点，OpenAI/Gemini 依赖估算
|
||||
|
||||
```typescript
|
||||
// src/utils/model/providers.ts:5-13
|
||||
export type APIProvider =
|
||||
| 'firstParty' // 1P - Anthropic 直连
|
||||
| 'bedrock' // 3P - AWS Bedrock
|
||||
| 'vertex' // 3P - Google Vertex
|
||||
| 'foundry' // 3P - Anthropic Foundry
|
||||
| 'openai' // 3P - OpenAI 兼容层
|
||||
| 'gemini' // 3P - Google Gemini
|
||||
| 'grok' // 3P - xAI Grok
|
||||
```
|
||||
|
||||
## 缓存策略：分块、标记、命中
|
||||
|
||||
这是 System Prompt 设计中最精密的部分。
|
||||
@@ -153,28 +121,6 @@ MCP 工具列表在会话中可能变化（连接/断开），破坏了跨组织
|
||||
|
||||
这是缓存效率最高的模式。`SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 之前的静态内容（Intro、Rules、Tone & Style 等）对所有用户相同，可跨组织缓存。
|
||||
|
||||
> **Boundary 插入条件**：`SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 标记**仅在特定条件**下插入：
|
||||
|
||||
```typescript
|
||||
// src/utils/betas.ts:226-229
|
||||
export function shouldUseGlobalCacheScope(): boolean {
|
||||
return (
|
||||
getAPIProvider() === 'firstParty' &&
|
||||
!isEnvTruthy(process.env.CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS)
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```typescript
|
||||
// src/constants/prompts.ts:574
|
||||
...(shouldUseGlobalCacheScope() ? [SYSTEM_PROMPT_DYNAMIC_BOUNDARY] : []),
|
||||
```
|
||||
|
||||
这意味着：
|
||||
- **3P 用户（Bedrock/Vertex/OpenAI/Gemini）**：Boundary 永远不存在，始终使用模式 3
|
||||
- **1P 用户禁用实验性功能**：设置 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`，Boundary 不插入
|
||||
- **1P 用户默认**：Boundary 存在，使用模式 2（最高缓存效率）
|
||||
|
||||
#### 模式 3：默认（3P 提供商 或 Boundary 缺失）
|
||||
|
||||
```
|
||||
@@ -304,65 +250,3 @@ Header 始终 `cacheScope: null`——它因版本和指纹不同而变化，不
|
||||
4. `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 标记允许 `splitSysPromptPrefix()` 精确地将静态区标记为 `scope: 'global'`，动态区不标记或标记为 `scope: 'org'`
|
||||
|
||||
这是 Claude Code 在 token 成本优化上的核心设计——一次典型的 System Prompt 约 20K+ tokens，通过缓存分块可以节省 30-50% 的输入 token 费用。
|
||||
|
||||
## 兼容层：OpenAI 与 Gemini
|
||||
|
||||
Claude Code 提供了 OpenAI 和 Gemini 协议的兼容层，允许使用非 Anthropic 端点。
|
||||
|
||||
### OpenAI 兼容层
|
||||
|
||||
通过 `CLAUDE_CODE_USE_OPENAI=1` 启用，支持任意 OpenAI Chat Completions 协议端点（Ollama、DeepSeek、vLLM 等）。
|
||||
|
||||
实现采用**流适配器模式**：
|
||||
1. 将 Anthropic 格式请求转换为 OpenAI 格式
|
||||
2. 调用 OpenAI 兼容端点
|
||||
3. 将 SSE 流转换回 `BetaRawMessageStreamEvent`
|
||||
4. 下游代码完全无感知
|
||||
|
||||
```
|
||||
src/services/api/openai/
|
||||
├── client.ts # OpenAI 客户端配置
|
||||
├── convertMessages.ts # 消息格式转换（Anthropic → OpenAI）
|
||||
├── convertTools.ts # 工具定义转换
|
||||
├── streamAdapter.ts # SSE 流适配（OpenAI → Anthropic）
|
||||
├── modelMapping.ts # 模型名称映射
|
||||
└── index.ts # 入口函数 queryModelOpenAI()
|
||||
```
|
||||
|
||||
关键环境变量：
|
||||
- `CLAUDE_CODE_USE_OPENAI=1` — 启用 OpenAI provider
|
||||
- `OPENAI_API_KEY` — API 密钥
|
||||
- `OPENAI_BASE_URL` — API 端点（默认 `https://api.openai.com/v1`）
|
||||
- `OPENAI_MODEL` — 直接指定模型名
|
||||
|
||||
### Gemini 兼容层
|
||||
|
||||
通过 `CLAUDE_CODE_USE_GEMINI=1` 启用，支持 Google Gemini API。
|
||||
|
||||
```
|
||||
src/services/api/gemini/
|
||||
├── client.ts # Gemini 客户端配置
|
||||
├── convertMessages.ts # 消息格式转换
|
||||
├── convertTools.ts # 工具定义转换
|
||||
├── streamAdapter.ts # 流适配
|
||||
├── modelMapping.ts # 模型名称映射
|
||||
├── types.ts # 类型定义
|
||||
└── index.ts # 入口函数
|
||||
```
|
||||
|
||||
关键环境变量：
|
||||
- `CLAUDE_CODE_USE_GEMINI=1` — 启用 Gemini provider
|
||||
- `GEMINI_API_KEY` — API 密钥
|
||||
- `GEMINI_BASE_URL` — API 端点（默认 `https://generativelanguage.googleapis.com/v1beta`）
|
||||
- `GEMINI_MODEL` — 直接指定模型名
|
||||
- `GEMINI_DEFAULT_SONNET_MODEL` / `GEMINI_DEFAULT_OPUS_MODEL` — 按能力级别映射
|
||||
|
||||
### 兼容层的限制
|
||||
|
||||
使用 3P 兼容层时，部分功能受限：
|
||||
- **无精确 token 计数**：系统退回到近似估算，影响自动压缩触发时机
|
||||
- **无全局缓存**：只能使用组织级缓存 `scope: 'org'`
|
||||
- **部分 beta 功能不可用**：依赖 Anthropic 特有 beta headers 的功能受限
|
||||
|
||||
详见 `docs/plans/openai-compatibility.md` 和 `CLAUDE.md` 中的相关章节。
|
||||
|
||||
|
||||
@@ -64,33 +64,6 @@ function roughTokenCountEstimation(content: string, bytesPerToken = 4): number {
|
||||
|
||||
精确计数在关键决策点使用（压缩前后对比、warning 判断），近似估算在热路径使用（每轮循环的 shouldAutoCompact 检查）。
|
||||
|
||||
### 3P Provider 的 Token 计数差异
|
||||
|
||||
不同 Provider 的精确 token 计数实现方式不同，部分 provider 甚至不支持精确计数：
|
||||
|
||||
| Provider | 计数方式 | 注意事项 |
|
||||
|----------|---------|---------|
|
||||
| **Anthropic 直连** | `anthropic.beta.messages.countTokens()` | 标准 API，最准确 |
|
||||
| **AWS Bedrock** | `CountTokensCommand` | 需要动态加载 279KB AWS SDK |
|
||||
| **Google Vertex** | Anthropic SDK + beta 过滤 | 需要特定 beta headers |
|
||||
| **OpenAI 兼容层** | 无精确计数 | **退回到近似估算** |
|
||||
| **Gemini 兼容层** | 无精确计数 | **退回到近似估算** |
|
||||
| **Bedrock 不支持时** | 用 Haiku 发送 `max_tokens=1` 请求 | 读取 `usage.input_tokens` |
|
||||
|
||||
OpenAI 和 Gemini 兼容层**不支持精确 token 计数**，系统会退回到近似估算。这会影响：
|
||||
- **自动压缩触发时机**：可能略有偏差
|
||||
- **压缩前后 token 对比**：仅为估算值，非精确
|
||||
- **Warning/Error 阈值判断**：基于估算而非精确计数
|
||||
|
||||
```typescript
|
||||
// src/services/tokenEstimation.ts - 近似估算函数
|
||||
function roughTokenCountEstimation(content: string, bytesPerToken = 4): number {
|
||||
return Math.round(content.length / bytesPerToken)
|
||||
}
|
||||
```
|
||||
|
||||
源码路径：`src/services/tokenEstimation.ts`
|
||||
|
||||
## 自动压缩的触发阈值
|
||||
|
||||
```
|
||||
|
||||
@@ -2,7 +2,6 @@
|
||||
title: "多轮对话管理 - QueryEngine 会话编排与持久化"
|
||||
description: "从源码角度解析 Claude Code 多轮对话管理：QueryEngine 的会话状态机、JSONL transcript 持久化、成本追踪模型和模型热切换机制。"
|
||||
keywords: ["多轮对话", "会话管理", "QueryEngine", "transcript", "成本追踪"]
|
||||
sourceRef: "3ec5675 (2026-04-08)"
|
||||
---
|
||||
|
||||
{/* 本章目标：从源码角度揭示会话编排、持久化存储、成本追踪和模型切换的完整链路 */}
|
||||
@@ -12,17 +11,15 @@ sourceRef: "3ec5675 (2026-04-08)"
|
||||
- **单轮**（一次 Agentic Loop）：`query()` 函数的一次完整执行——组装上下文 → 调 API → 处理工具调用 → 循环直到结束
|
||||
- **多轮**（一个 Session）：`QueryEngine` 类管理的一次会话——跨越数十轮 `submitMessage()` 调用，持续数小时
|
||||
|
||||
`QueryEngine`（`src/QueryEngine.ts`，类定义）是单轮 Agentic Loop 之上的**会话编排器**，它管理的状态远不止消息列表：
|
||||
`QueryEngine`（`src/QueryEngine.ts:186`）是单轮 Agentic Loop 之上的**会话编排器**，它管理的状态远不止消息列表：
|
||||
|
||||
```
|
||||
QueryEngine 内部状态（src/QueryEngine.ts 构造函数）
|
||||
QueryEngine 内部状态
|
||||
├── mutableMessages: Message[] ← 完整对话历史，跨 turn 累积
|
||||
├── readFileState: FileStateCache ← 已读文件内容缓存，避免重复读取
|
||||
├── totalUsage: NonNullableUsage ← 累计 token 消耗（input/output/cache）
|
||||
├── permissionDenials: SDKPermissionDenial[] ← 权限拒绝记录
|
||||
├── discoveredSkillNames: Set<string> ← 当前 turn 已发现的 skill
|
||||
├── loadedNestedMemoryPaths: Set<string> ← 已加载的嵌套 memory 路径（防重复）
|
||||
├── hasHandledOrphanedPermission: boolean ← 是否已处理孤立权限请求
|
||||
└── abortController: AbortController ← 会话级中断控制
|
||||
```
|
||||
|
||||
@@ -31,37 +28,29 @@ QueryEngine 内部状态（src/QueryEngine.ts 构造函数）
|
||||
每次用户输入一条消息，REPL 或 SDK 调用 `submitMessage()`，它会执行完整的 turn 初始化链路：
|
||||
|
||||
```typescript
|
||||
// src/QueryEngine.ts — QueryEngine.submitMessage() 简化流程
|
||||
async *submitMessage(
|
||||
prompt: string | ContentBlockParam[],
|
||||
options?: { uuid?: string; isMeta?: boolean },
|
||||
): AsyncGenerator<SDKMessage> {
|
||||
// src/QueryEngine.ts:211 — 简化的 submitMessage 流程
|
||||
async *submitMessage(prompt, options?): AsyncGenerator<SDKMessage> {
|
||||
// 1. 清除 turn 级追踪状态
|
||||
this.discoveredSkillNames.clear()
|
||||
|
||||
// 2. 解析模型（用户可能中途通过 setModel() 切换了模型）
|
||||
const mainLoopModel = this.config.userSpecifiedModel
|
||||
? parseUserSpecifiedModel(this.config.userSpecifiedModel)
|
||||
|
||||
// 2. 解析模型（用户可能中途切换了模型）
|
||||
const mainLoopModel = userSpecifiedModel
|
||||
? parseUserSpecifiedModel(userSpecifiedModel)
|
||||
: getMainLoopModel()
|
||||
|
||||
|
||||
// 3. 动态组装 System Prompt（每次 turn 都重新构建）
|
||||
const { defaultSystemPrompt, userContext, systemContext } =
|
||||
await fetchSystemPromptParts({ tools, mainLoopModel, mcpClients })
|
||||
|
||||
|
||||
// 4. 包装权限检查（追踪每次拒绝）
|
||||
const wrappedCanUseTool = async (tool, input, ...) => {
|
||||
const result = await canUseTool(tool, input, ...)
|
||||
if (result.behavior !== 'allow') {
|
||||
this.permissionDenials.push({
|
||||
type: 'permission_denial',
|
||||
tool_name: sdkCompatToolName(tool.name),
|
||||
tool_use_id: toolUseID,
|
||||
tool_input: input,
|
||||
})
|
||||
this.permissionDenials.push({ tool_name: tool.name, ... })
|
||||
}
|
||||
return result
|
||||
}
|
||||
|
||||
|
||||
// 5. 调用核心 query() 函数执行 agentic loop
|
||||
yield* query({
|
||||
systemPrompt, messages: this.mutableMessages,
|
||||
@@ -79,43 +68,36 @@ async *submitMessage(
|
||||
### 存储路径
|
||||
|
||||
```
|
||||
~/.claude/projects/<sanitized-cwd>/<session-uuid>.jsonl
|
||||
~/.claude/projects/<project-hash>/<session-id>.jsonl
|
||||
```
|
||||
|
||||
- 路径由 `getProjectDir(originalCwd)` 生成，使用 `sanitizePath()` 将项目目录路径转换为安全的目录名（非 hash），同一项目目录的会话归入同一子目录
|
||||
- `project-hash` 由 `getProjectDir(originalCwd)` 生成，同一项目目录的会话归入同一子目录
|
||||
- 每条记录是一行 JSON（JSONL 格式），支持追加写入而不需要读取-修改-写入整个文件
|
||||
- 读取上限为 50MB（`MAX_TRANSCRIPT_READ_BYTES` 常量，`src/utils/sessionStorage.ts`），防止超大会话导致 OOM
|
||||
- 读取上限为 50MB（`MAX_TRANSCRIPT_READ_BYTES`），防止超大会话导致 OOM
|
||||
|
||||
### Transcript 写入器
|
||||
|
||||
`Project` 类（`src/utils/sessionStorage.ts`，私有类）管理 transcript 的写入。它通过 `writeQueues`（按文件分组的写队列）和 `drainWriteQueue()`（定时批量刷写）确保并发消息追加不会互相覆盖：
|
||||
`TranscriptWriter`（`src/utils/sessionStorage.ts:1200+`）是一个写队列，确保并发的消息追加不会互相覆盖：
|
||||
|
||||
```
|
||||
写入流程（异步排队路径）：
|
||||
recordTranscript(sessionId, entry)
|
||||
写入流程：
|
||||
appendEntryToFile(sessionId, entry)
|
||||
↓
|
||||
project.enqueueWrite(filePath, entry) ← 入列到 writeQueues
|
||||
ensureCurrentSessionFile() ← 懒初始化：首次写入时才创建文件
|
||||
↓
|
||||
scheduleDrain() ← 设置定时器（FLUSH_INTERVAL_MS）
|
||||
序列化为 JSON + 换行符
|
||||
↓
|
||||
drainWriteQueue() ← 按 MAX_CHUNK_BYTES 分批
|
||||
↓ 写入每批
|
||||
appendToFile(path, batchContent) ← 批量追加
|
||||
appendFile(path, line) ← 原子追加
|
||||
↓
|
||||
如果配置了远程持久化：
|
||||
persistToRemote(sessionId, entry)
|
||||
├── CCR v2: internalEventWriter('transcript', entry)
|
||||
└── v1 Ingress: sessionIngress.appendSessionLog(...)
|
||||
|
||||
同步直写路径（用于元数据重写等场景）：
|
||||
appendEntryToFile(fullPath, entry) ← 同步 appendFileSync
|
||||
↓
|
||||
失败时 mkdir + 重试
|
||||
```
|
||||
|
||||
### 会话恢复链路
|
||||
|
||||
`--resume` 参数触发的恢复流程（`src/main.tsx` 中 `--resume` 分支）：
|
||||
`--resume` 参数触发的恢复流程（`src/main.tsx:3620+`）：
|
||||
|
||||
```
|
||||
1. 解析 resume 参数：
|
||||
@@ -148,7 +130,7 @@ async *submitMessage(
|
||||
### 累计层：cost-tracker.ts
|
||||
|
||||
```typescript
|
||||
// src/cost-tracker.ts — StoredCostState 类型定义
|
||||
// src/cost-tracker.ts — StoredCostState 数据模型
|
||||
type StoredCostState = {
|
||||
totalCostUSD: number // 累计美元花费
|
||||
totalAPIDuration: number // API 调用总时长（含重试）
|
||||
@@ -156,8 +138,7 @@ type StoredCostState = {
|
||||
totalToolDuration: number // 工具执行总时长
|
||||
totalLinesAdded: number // 代码增加行数
|
||||
totalLinesRemoved: number // 代码删除行数
|
||||
lastDuration: number | undefined // 最近一次会话时长
|
||||
modelUsage: { [modelName: string]: ModelUsage } | undefined // 按模型分拆的用量
|
||||
modelUsage: { [modelName: string]: ModelUsage } // 按模型分拆的用量
|
||||
}
|
||||
```
|
||||
|
||||
@@ -175,18 +156,18 @@ saveCurrentSessionCosts(sessionId)
|
||||
|
||||
### 预算熔断
|
||||
|
||||
`QueryEngineConfig.maxBudgetUsd` 提供了会话级的硬性预算上限。在 REPL 中，当累计费用超过 $5 时（`src/screens/REPL.tsx` 中费用阈值 `useEffect`），弹出费用提醒对话框——这不是硬性阻断，而是"软提醒"，且仅在 `hasConsoleBillingAccess()` 为 true 时显示。
|
||||
`QueryEngineConfig.maxBudgetUsd` 提供了会话级的硬性预算上限。在 REPL 中，当累计费用超过 $5 时（`src/screens/REPL.tsx:2208`），弹出费用提醒对话框——这不是硬性阻断，而是"软提醒"。
|
||||
|
||||
## 模型热切换
|
||||
|
||||
在一个会话中切换模型不会丢失对话历史——因为 `mutableMessages` 与模型选择是解耦的：
|
||||
|
||||
```
|
||||
/model sonnet → QueryEngine.setModel('claude-sonnet-4-20250514')
|
||||
↓ 实际操作：this.config.userSpecifiedModel = model（QueryEngine.setModel() 方法）
|
||||
/model sonnet → setMainLoopModelOverride('claude-sonnet-4-20250514')
|
||||
↓
|
||||
下一次 submitMessage() 开始时：
|
||||
↓
|
||||
parseUserSpecifiedModel(this.config.userSpecifiedModel)
|
||||
parseUserSpecifiedModel(userSpecifiedModel)
|
||||
→ 返回新的模型配置
|
||||
↓
|
||||
fetchSystemPromptParts({ mainLoopModel: newModel })
|
||||
|
||||
@@ -2,7 +2,6 @@
|
||||
title: "流式响应机制 - Claude Code 打字机效果原理"
|
||||
description: "解析 Claude Code 流式响应实现：如何通过 SSE 逐 token 接收 AI 输出，实现实时打字机效果，提升用户等待体验。"
|
||||
keywords: ["流式响应", "SSE", "streaming", "实时输出", "API streaming"]
|
||||
sourceRef: "3ec5675 (2026-04-08)"
|
||||
---
|
||||
|
||||
## 为什么需要流式
|
||||
@@ -32,7 +31,7 @@ message_stop ← 消息结束
|
||||
|
||||
### 事件处理状态机
|
||||
|
||||
`src/services/api/claude.ts` 中 `queryStreamRaw()` 函数的事件处理循环实现了一个基于 `switch(part.type)` 的状态机：
|
||||
`src/services/api/claude.ts:1980-2298` 实现了一个基于 `switch(part.type)` 的状态机：
|
||||
|
||||
| 事件类型 | 处理逻辑 | 状态变更 |
|
||||
|----------|----------|----------|
|
||||
@@ -77,7 +76,7 @@ content_block_stop (index=2)
|
||||
`stop_reason` 要等到 `message_delta` 才确定（可能是 `end_turn`、`tool_use`、`max_tokens` 等），所以最后一条消息的 `stop_reason` 是**回写**的：
|
||||
|
||||
```typescript
|
||||
// claude.ts — stop_reason 回写逻辑（直接属性修改，不用对象替换）
|
||||
// claude.ts:2246 — 直接属性修改，不用对象替换
|
||||
// 因为 transcript 写队列持有 message.message 的引用
|
||||
const lastMsg = newMessages.at(-1)
|
||||
if (lastMsg) {
|
||||
@@ -90,21 +89,16 @@ if (lastMsg) {
|
||||
|
||||
### 网络断开
|
||||
|
||||
流式连接依赖 SSE（Server-Sent Events）。当连接中断时，系统有两层检测机制：
|
||||
流式连接依赖 SSE（Server-Sent Events）。当连接中断时：
|
||||
|
||||
1. **被动停滞检测**（`src/services/api/claude.ts` 中 stall 检测逻辑）：当下一个事件到达时，计算与上一个事件的时间间隔。超过阈值（30 秒，`STALL_THRESHOLD_MS = 30_000`）记录为一次 stall，累积计数并写入遥测日志。这是被动检测——仅在下一个 chunk 到达时才触发，不会主动中断流。
|
||||
2. **主动空闲超时看门狗**（`src/services/api/claude.ts` 中 `STREAM_IDLE_TIMEOUT_MS` 看门狗逻辑）：使用 `setTimeout` 设置 90 秒（可通过 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 环境变量覆盖）的硬性超时。如果在此期间没有收到任何事件，主动终止流并抛出错误进入重试流程。
|
||||
3. **非流式降级**：作为最后手段，设置 `didFallBackToNonStreaming` 标志，通过 `executeNonStreamingRequest()` 回退到非流式请求（一次性获取完整响应）。
|
||||
1. **Stream idle watchdog**：定时检测事件间隔，超过阈值（stall）触发告警和重试
|
||||
2. **Stream abort**：如果 watchdog 检测到长时间无事件，抛出错误进入重试流程
|
||||
3. **非流式降级**：作为最后手段，回退到非流式请求（一次性获取完整响应）
|
||||
|
||||
```typescript
|
||||
// claude.ts — 被动停滞检测
|
||||
const STALL_THRESHOLD_MS = 30_000 // 30 秒无事件视为停滞
|
||||
let totalStallTime = 0
|
||||
let stallCount = 0
|
||||
|
||||
// claude.ts — 主动空闲超时
|
||||
const STREAM_IDLE_TIMEOUT_MS =
|
||||
parseInt(process.env.CLAUDE_STREAM_IDLE_TIMEOUT_MS || '', 10) || 90_000
|
||||
// claude.ts:2338-2355 — 检测空流
|
||||
// 1. 完全没有事件 → 代理返回了非 SSE 响应
|
||||
// 2. 有 message_start 但没有 content_block_stop → 流被截断
|
||||
```
|
||||
|
||||
### API 限流
|
||||
@@ -124,7 +118,7 @@ const STREAM_IDLE_TIMEOUT_MS =
|
||||
| **上下文窗口超限** | `model_context_window_exceeded` | 触发 compaction 压缩对话历史后重试 |
|
||||
|
||||
```typescript
|
||||
// claude.ts — stop_reason 处理
|
||||
// claude.ts:2267-2293
|
||||
if (stopReason === 'max_tokens') {
|
||||
yield createAssistantAPIErrorMessage({ error: 'max_output_tokens', ... })
|
||||
}
|
||||
@@ -139,8 +133,8 @@ if (stopReason === 'model_context_window_exceeded') {
|
||||
系统持续监控事件到达间隔，检测"停滞"（stall）：
|
||||
|
||||
```typescript
|
||||
// claude.ts — stall 检测逻辑
|
||||
const STALL_THRESHOLD_MS = 30_000 // 30 秒无事件视为停滞
|
||||
// claude.ts:1940-1966
|
||||
const STALL_THRESHOLD_MS = 10_000 // 10 秒无事件视为停滞
|
||||
if (timeSinceLastEvent > STALL_THRESHOLD_MS) {
|
||||
stallCount++
|
||||
totalStallTime += timeSinceLastEvent
|
||||
@@ -148,7 +142,7 @@ if (timeSinceLastEvent > STALL_THRESHOLD_MS) {
|
||||
}
|
||||
```
|
||||
|
||||
这是**被动检测**——仅在下一个 chunk 到达时才触发比较。与之互补的是 90 秒主动空闲超时看门狗（`STREAM_IDLE_TIMEOUT_MS`），会直接中断长时间无响应的流。
|
||||
多个 stall 累积后，watchdog 可能决定中断流并触发重试。
|
||||
|
||||
## 工具执行的流式反馈
|
||||
|
||||
|
||||
@@ -2,7 +2,6 @@
|
||||
title: "Agentic Loop：AI 自主循环的核心机制"
|
||||
description: "深入解析 Claude Code 的 query() 异步生成器循环——从流式 API 调用、工具并行执行、上下文压缩、错误恢复到终止条件的完整状态机，基于 src/query.ts 的源码级分析。"
|
||||
keywords: ["Agentic Loop", "query loop", "tool_use", "状态机", "auto-compact", "streaming", "recovery"]
|
||||
sourceRef: "3ec5675 (2026-04-08)"
|
||||
---
|
||||
|
||||
{/* 本章目标：基于 src/query.ts 揭示 Agentic Loop 的完整状态机 */}
|
||||
@@ -12,7 +11,7 @@ sourceRef: "3ec5675 (2026-04-08)"
|
||||
传统聊天机器人：你问一句，它答一句。
|
||||
Claude Code 不一样：你说一个需求，它可能连续执行十几步操作才给你最终结果。
|
||||
|
||||
这背后的机制叫做 **Agentic Loop**（智能体循环），核心实现在 `src/query.ts` 的 `queryLoop()` 异步生成器函数。它是一个 `while(true)` 无限循环，每次迭代代表一次"思考→行动→观察"周期。
|
||||
这背后的机制叫做 **Agentic Loop**（智能体循环），核心实现在 `src/query.ts` 的 `queryLoop()` 异步生成器函数（第 241 行）。它是一个 `while(true)` 无限循环，每次迭代代表一次"思考→行动→观察"周期。
|
||||
|
||||
<Frame caption="Agentic Loop 循环示意">
|
||||
<img src="/docs/images/agentic-loop.png" alt="Agentic Loop 循环图" />
|
||||
@@ -20,7 +19,7 @@ Claude Code 不一样：你说一个需求，它可能连续执行十几步操
|
||||
|
||||
## 循环的完整结构
|
||||
|
||||
`queryLoop()` 的每次迭代（`src/query.ts` 中 `while(true)` 主循环）包含以下阶段：
|
||||
`queryLoop()` 的每次迭代（`src/query.ts:307` `while(true)`）包含以下阶段：
|
||||
|
||||
### 阶段 1：上下文预处理（Pre-Processing Pipeline）
|
||||
|
||||
@@ -40,7 +39,7 @@ messagesForQuery（处理后的消息）→ 发往 API
|
||||
|
||||
### 阶段 2：流式 API 调用（Streaming Loop）
|
||||
|
||||
`deps.callModel()` 发起流式请求（`src/query.ts` 中 `attemptWithFallback` 循环内），返回一个 AsyncGenerator。在流式过程中：
|
||||
`deps.callModel()` 发起流式请求（第 659 行），返回一个 AsyncGenerator。在流式过程中：
|
||||
|
||||
- **AssistantMessage** 被收集到 `assistantMessages[]` 数组
|
||||
- **tool_use 块** 被提取到 `toolUseBlocks[]`，设置 `needsFollowUp = true`
|
||||
@@ -48,8 +47,8 @@ messagesForQuery（处理后的消息）→ 发往 API
|
||||
- 可恢复的错误（prompt-too-long、max-output-tokens）被**暂扣**（withheld），先尝试恢复
|
||||
|
||||
流式回调中的关键守卫：
|
||||
- `backfillObservableInput()` —— 为 tool_use 块回填可观察字段（如文件路径展开），但只在添加了新字段时才克隆消息，避免破坏 prompt cache 的字节一致性
|
||||
- 流式降级检测——如果 `streamingFallbackOccured`，已收集的消息被标记为 tombstone，清空后重试
|
||||
- `backfillObservableInput()`（第 763 行）—— 为 tool_use 块回填可观察字段（如文件路径展开），但只在添加了新字段时才克隆消息，避免破坏 prompt cache 的字节一致性
|
||||
- 流式降级检测——如果 `streamingFallbackOccured`，已收集的消息被标记为 tombstone（第 717 行），清空后重试
|
||||
|
||||
### 阶段 3：工具执行（Tool Execution）
|
||||
|
||||
@@ -68,50 +67,42 @@ const toolUpdates = streamingToolExecutor
|
||||
|
||||
每次迭代结束时，根据条件决定 `return`（终止）或 `continue`（继续）：
|
||||
|
||||
## 终止条件（源码级）
|
||||
|
||||
循环有多种终止路径，按触发时机排列：
|
||||
## 7 种终止条件（源码级）
|
||||
|
||||
| 终止原因 | 触发位置 | 机制 |
|
||||
|----------|---------|------|
|
||||
| **completed** | 第 1360 行 | AI 未发出 tool_use → `needsFollowUp = false` → 经过 stop hooks → 返回 |
|
||||
| **blocking_limit** | 第 646 行 | Token 计数超过硬限制（非 autocompact 模式）→ 生成 PTL 错误消息 → 返回 |
|
||||
| **image_error** | 第 980 行 | `ImageSizeError` / `ImageResizeError` 异常 → 直接返回 |
|
||||
| **model_error** | 第 999 行 | `callModel()` 抛出不可恢复异常 → 生成错误消息 → 返回 |
|
||||
| **aborted_streaming** | 第 1054 行 | `abortController.signal.aborted`（流式阶段）→ 为未完成的 tool_use 生成合成 tool_result → 返回 |
|
||||
| **prompt_too_long** | 第 1178/1185 行 | 413 错误且 reactive compact 无法恢复 → 暂扣的错误消息被释放 → 返回 |
|
||||
| **completed** | 第 1267 行 | API 错误（限流、认证失败等）导致无法继续 → 返回 |
|
||||
| **aborted_streaming** | 第 1054 行 | `abortController.signal.aborted` → 为未完成的 tool_use 生成合成 tool_result → 返回 |
|
||||
| **model_error** | 第 999 行 | `callModel()` 抛出异常 → 生成错误消息 → 返回 |
|
||||
| **prompt_too_long** | 第 1178 行 | 413 错误且 reactive compact 无法恢复 → 暂扣的错误消息被释放 → 返回 |
|
||||
| **image_error** | 第 980/1178 行 | 图片尺寸/大小错误 → 直接返回 |
|
||||
| **stop_hook_prevented** | 第 1282 行 | Stop hook 返回 `preventContinuation: true` → 返回 |
|
||||
| **completed** | 第 1360 行 | 正常完成：AI 未发出 tool_use → `needsFollowUp = false` → 经过 stop hooks → 返回 |
|
||||
| **aborted_tools** | 第 1518 行 | `abortController.signal.aborted`（工具执行阶段）→ 返回 |
|
||||
| **hook_stopped** | 第 1523 行 | 工具执行期间 hook 返回 `shouldPreventContinuation` → 返回 |
|
||||
| **max_turns** | 第 1714 行 | 轮次计数超过 `maxTurns` 限制 → 返回 |
|
||||
|
||||
## 继续条件（恢复路径）
|
||||
## 4 种继续条件（恢复路径）
|
||||
|
||||
循环不仅是一个简单的"有 tool_use 就继续"，它还包含多种恢复/重试路径：
|
||||
|
||||
### 1. 正常工具循环（`next_turn`）
|
||||
`needsFollowUp = true` → 执行工具 → 新消息追加到 `messagesForQuery` → state 重新赋值 → `continue`
|
||||
### 1. 正常工具循环
|
||||
`needsFollowUp = true` → 执行工具 → 新消息追加到 `messagesForQuery` → `continue`
|
||||
|
||||
### 2. max_output_tokens 恢复（`max_output_tokens_escalate` / `max_output_tokens_recovery`）
|
||||
当 AI 输出被截断时（`apiError === 'max_output_tokens'`），分两阶段恢复：
|
||||
- **提升阶段**（`max_output_tokens_escalate`）：首次截断时，将 `maxOutputTokens` 从默认值提升到 `ESCALATED_MAX_TOKENS`（64K）。静默重试，不注入 meta 消息。
|
||||
- **恢复阶段**（`max_output_tokens_recovery`）：提升后仍然截断时，注入恢复消息"Output token limit hit. Resume directly..."，最多重试 `MAX_OUTPUT_TOKENS_RECOVERY_LIMIT = 3` 次。恢复耗尽后，暂扣的错误消息被释放。
|
||||
### 2. max_output_tokens 恢复（第 1191-1255 行）
|
||||
当 AI 输出被截断时（`apiError === 'max_output_tokens'`）：
|
||||
- **首次**：尝试将 `maxOutputTokens` 从默认值提升到 `ESCALATED_MAX_TOKENS`（64K），无 meta 消息，静默重试
|
||||
- **后续**：注入恢复消息"Output token limit hit. Resume directly..."，最多重试 `MAX_OUTPUT_TOKENS_RECOVERY_LIMIT = 3` 次
|
||||
- 恢复耗尽后，暂扣的错误消息被释放
|
||||
|
||||
### 3. Prompt-Too-Long 恢复（`collapse_drain_retry` / `reactive_compact_retry`）
|
||||
当遇到 413 错误时，按优先级尝试两种压缩策略：
|
||||
- **Context Collapse Drain**（`collapse_drain_retry`）：提交所有已暂存的折叠（collapse），释放空间后重试。如果上一轮已经是 `collapse_drain_retry` 则跳过，避免无限循环。
|
||||
- **Reactive Compact**（`reactive_compact_retry`）：如果 collapse drain 无法恢复，触发即时压缩（reactive compact），生成摘要后重试。`hasAttemptedReactiveCompact` 标志防止无限循环。
|
||||
### 3. Prompt-Too-Long 恢复（第 1088-1186 行）
|
||||
当遇到 413 错误时，有两个恢复阶段：
|
||||
- **Context Collapse Drain**（第 1097 行）：提交所有已暂存的折叠，释放空间后重试。如果上一轮已经是 collapse_drain_retry 则跳过
|
||||
- **Reactive Compact**（第 1123 行）：触发即时压缩，生成摘要后重试。`hasAttemptedReactiveCompact` 防止无限循环
|
||||
|
||||
### 4. Stop Hook 阻塞重试（`stop_hook_blocking`）
|
||||
### 4. Stop Hook 阻塞重试（第 1285-1308 行）
|
||||
Stop hook 可以注入阻塞错误消息，强制 AI 重新思考。新的消息（包含阻塞错误）被追加到对话中，`stopHookActive = true`，进入下一轮迭代。
|
||||
|
||||
### 5. Token Budget 继续提示（`token_budget_continuation`）
|
||||
当 `TOKEN_BUDGET` feature 启用时，如果 token 消耗达到阈值但未超出预算，注入 nudge 消息让 AI 加速收尾，然后继续。
|
||||
|
||||
## 模型降级（Fallback）
|
||||
|
||||
当主模型不可用时（`FallbackTriggeredError`，`src/query.ts` 中 `attemptWithFallback` 循环的 catch 分支）：
|
||||
当主模型不可用时（`FallbackTriggeredError`，第 897 行）：
|
||||
|
||||
1. 已收集的 `assistantMessages` 被清空，tool_use 块收到合成 tool_result："Model fallback triggered"
|
||||
2. 思维签名块被移除（`stripSignatureBlocks`）—— 因为思维签名与模型绑定，跨模型回放会 400
|
||||
@@ -121,14 +112,13 @@ Stop hook 可以注入阻塞错误消息，强制 AI 重新思考。新的消息
|
||||
|
||||
## 状态机：State 对象
|
||||
|
||||
每次迭代的状态通过 `State` 类型（`src/query.ts`，类型定义）传递：
|
||||
每次迭代的状态通过 `State` 类型（第 204 行）传递：
|
||||
|
||||
```typescript
|
||||
// src/query.ts — State 类型定义
|
||||
type State = {
|
||||
messages: Message[] // 当前对话消息
|
||||
toolUseContext: ToolUseContext // 工具上下文（含权限）
|
||||
autoCompactTracking: AutoCompactTrackingState | undefined // 压缩跟踪
|
||||
autoCompactTracking: AutoCompactTrackingState // 压缩跟踪
|
||||
maxOutputTokensRecoveryCount: number // 输出截断恢复计数
|
||||
hasAttemptedReactiveCompact: boolean // 是否已尝试即时压缩
|
||||
maxOutputTokensOverride: number | undefined // 输出 token 上限覆盖
|
||||
@@ -143,7 +133,7 @@ type State = {
|
||||
|
||||
## Token Budget（实验性）
|
||||
|
||||
当 `TOKEN_BUDGET` feature 启用时（`src/query.ts` 中 `!needsFollowUp` 分支内的预算检查逻辑），循环在终止前会检查 token 消耗：
|
||||
当 `TOKEN_BUDGET` feature 启用时（第 1311 行），循环在终止前会检查 token 消耗：
|
||||
|
||||
- **continuation**：未达到预算但超过阈值 → 注入 nudge 消息，让 AI 加速收尾
|
||||
- **diminishing_returns**：检测到收益递减 → 提前终止
|
||||
@@ -167,31 +157,26 @@ type State = {
|
||||
|
||||
```
|
||||
迭代 1: 思考→行动
|
||||
预处理管道: applyToolResultBudget → snipCompact(HISTORY_SNIP feature) → microcompact → applyCollapses(CONTEXT_COLLAPSE feature) → autocompact
|
||||
→ 上下文很短，无需压缩
|
||||
预处理: 无需压缩（上下文很短）
|
||||
API 调用: 返回 tool_use(Glob, "**/*.ts")
|
||||
工具执行: 返回 42 个文件路径
|
||||
→ needsFollowUp = true
|
||||
→ transition: { reason: 'next_turn' }, continue
|
||||
→ needsFollowUp = true, continue
|
||||
|
||||
迭代 2: 思考→行动
|
||||
预处理管道: 42 个文件结果仍在预算内
|
||||
预处理: 42 个文件结果仍在预算内
|
||||
API 调用: 返回 tool_use(Grep, "import.*from")
|
||||
工具执行: 在 15 个文件中找到 120 条 import
|
||||
→ needsFollowUp = true
|
||||
→ transition: { reason: 'next_turn' }, continue
|
||||
→ needsFollowUp = true, continue
|
||||
|
||||
迭代 3: 思考→行动（多轮）
|
||||
预处理管道: 120 条 Grep 结果触发 microcompact → 摘要化
|
||||
预处理: 120 条 Grep 结果触发 microcompact → 摘要化
|
||||
API 调用: 返回 3 个 tool_use(FileEdit, ...)
|
||||
工具执行: 删除 5 条未使用导入
|
||||
→ needsFollowUp = true
|
||||
→ transition: { reason: 'next_turn' }, continue
|
||||
→ needsFollowUp = true, continue
|
||||
|
||||
迭代 4: 总结
|
||||
API 调用: 返回纯文本"已清理 3 个文件中的 5 条未使用导入"
|
||||
→ needsFollowUp = false
|
||||
→ Stop hooks 通过
|
||||
→ Token Budget 检查通过（如果启用）
|
||||
→ return { reason: 'completed' }
|
||||
```
|
||||
|
||||
@@ -1,14 +1,14 @@
|
||||
---
|
||||
title: "Hooks 生命周期钩子 - 执行引擎与拦截协议"
|
||||
description: "从源码角度解析 Claude Code Hooks 系统：27 种 Hook 事件、6 种 Hook 类型、同步/异步执行协议、JSON 输出 schema、if 条件匹配、以及 Hook 如何注入上下文和拦截工具调用。"
|
||||
description: "从源码角度解析 Claude Code Hooks 系统：22 种 Hook 事件、6 种 Hook 类型、同步/异步执行协议、JSON 输出 schema、if 条件匹配、以及 Hook 如何注入上下文和拦截工具调用。"
|
||||
keywords: ["Hooks", "生命周期钩子", "拦截器", "PreToolUse", "Hook 协议"]
|
||||
---
|
||||
|
||||
{/* 本章目标：从源码角度揭示 Hook 的执行引擎、匹配机制、返回值协议和生命周期管理 */}
|
||||
|
||||
## 27 种 Hook 事件
|
||||
## 22 种 Hook 事件
|
||||
|
||||
Claude Code 定义了 27 种 Hook 事件（`HOOK_EVENTS` 数组，`src/entrypoints/sdk/coreTypes.ts`），覆盖完整的 Agent 生命周期：
|
||||
Claude Code 定义了 22 种 Hook 事件（`coreTypes.ts:25-53`），覆盖完整的 Agent 生命周期：
|
||||
|
||||
| 阶段 | 事件 | 触发时机 | 匹配字段 |
|
||||
|------|------|---------|---------|
|
||||
@@ -32,7 +32,6 @@ Claude Code 定义了 27 种 Hook 事件（`HOOK_EVENTS` 数组，`src/entrypoin
|
||||
| | `TaskCompleted` | 任务完成 | — |
|
||||
| **MCP** | `Elicitation` | MCP 服务器请求用户输入 | `mcp_server_name` |
|
||||
| | `ElicitationResult` | Elicitation 结果返回 | `mcp_server_name` |
|
||||
| **通知** | `Notification` | 系统通知事件 | `notification_type` |
|
||||
| **环境** | `ConfigChange` | 配置变更 | `source` |
|
||||
| | `CwdChanged` | 工作目录变更 | — |
|
||||
| | `FileChanged` | 文件变更 | `file_path` |
|
||||
@@ -41,11 +40,7 @@ Claude Code 定义了 27 种 Hook 事件（`HOOK_EVENTS` 数组，`src/entrypoin
|
||||
|
||||
## 6 种 Hook 类型
|
||||
|
||||
Hooks 配置支持 6 种执行方式，类型定义分布在 3 个文件中：
|
||||
|
||||
- **可持久化类型**（`command`、`prompt`、`agent`、`http`）— Zod schema 定义在 `src/schemas/hooks.ts`，通过 `z.discriminatedUnion('type', [...])` 声明
|
||||
- **callback 类型** — TypeScript 接口定义在 `src/types/hooks.ts`，用于 SDK 注册的内部 JS 函数
|
||||
- **function 类型** — 定义在 `src/utils/hooks/sessionHooks.ts`，用于运行时动态注册的函数 Hook
|
||||
Hooks 配置支持 6 种执行方式（`src/types/hooks.ts`）：
|
||||
|
||||
| 类型 | 执行方式 | 适用场景 |
|
||||
|------|---------|---------|
|
||||
@@ -58,7 +53,7 @@ Hooks 配置支持 6 种执行方式，类型定义分布在 3 个文件中：
|
||||
|
||||
## 执行引擎：execCommandHook
|
||||
|
||||
`execCommandHook()`（`src/utils/hooks.ts`，`execCommandHook` 函数）是命令型 Hook 的执行核心：
|
||||
`execCommandHook()`（`src/utils/hooks.ts:829-1417`）是命令型 Hook 的执行核心：
|
||||
|
||||
```
|
||||
execCommandHook(hook, hookEvent, hookName, jsonInput, signal)
|
||||
@@ -80,7 +75,7 @@ execCommandHook(hook, hookEvent, hookName, jsonInput, signal)
|
||||
|
||||
### 异步 Hook 的检测协议
|
||||
|
||||
Hook 进程的 stdout 第一行如果是 `{"async":true}`，系统将其转为后台任务（`isAsyncHookJSONOutput` 检测 + `executeInBackground` 调用）：
|
||||
Hook 进程的 stdout 第一行如果是 `{"async":true}`，系统将其转为后台任务（`hooks.ts:1199-1246`）：
|
||||
|
||||
```typescript
|
||||
const firstLine = firstLineOf(stdout).trim()
|
||||
@@ -101,7 +96,7 @@ if (isAsyncHookJSONOutput(parsed)) {
|
||||
|
||||
## Hook 输出的 JSON Schema
|
||||
|
||||
同步 Hook 的输出遵循严格的 Zod schema（`syncHookResponseSchema`，定义在 `src/types/hooks.ts`，`hookJSONOutputSchema` 定义在 `src/schemas/hooks.ts`）：
|
||||
同步 Hook 的输出遵循严格的 Zod schema（`src/types/hooks.ts:49-567`）：
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -125,25 +120,16 @@ if (isAsyncHookJSONOutput(parsed)) {
|
||||
|
||||
| 事件 | 专有字段 | 作用 |
|
||||
|------|---------|------|
|
||||
| `PreToolUse` | `permissionDecision`, `permissionDecisionReason`, `updatedInput`, `additionalContext` | 拦截/修改工具输入 |
|
||||
| `PostToolUse` | `additionalContext`, `updatedMCPToolOutput` | 修改 MCP 工具输出 |
|
||||
| `PostToolUseFailure` | `additionalContext` | 失败后注入上下文 |
|
||||
| `PreToolUse` | `permissionDecision`, `updatedInput`, `additionalContext` | 拦截/修改工具输入 |
|
||||
| `UserPromptSubmit` | `additionalContext` | 注入额外上下文 |
|
||||
| `SessionStart` | `additionalContext`, `initialUserMessage`, `watchPaths` | 设置初始消息和文件监控 |
|
||||
| `PermissionRequest` | `decision`（含 `allow`/`deny` 子字段） | 权限请求的 Hook 决策 |
|
||||
| `PostToolUse` | `additionalContext`, `updatedMCPToolOutput` | 修改 MCP 工具输出 |
|
||||
| `SessionStart` | `initialUserMessage`, `watchPaths` | 设置初始消息和文件监控 |
|
||||
| `PermissionDenied` | `retry` | 指示是否重试 |
|
||||
| `SubagentStart` | `additionalContext` | 子 Agent 启动时注入上下文 |
|
||||
| `Elicitation` | `action`, `content` | 控制用户输入对话框 |
|
||||
| `ElicitationResult` | `action`, `content` | Elicitation 结果处理 |
|
||||
| `Notification` | `additionalContext` | 通知事件注入上下文 |
|
||||
| `Setup` | `additionalContext` | 初始化时注入上下文 |
|
||||
| `CwdChanged` | `watchPaths` | 目录变更后更新监控路径 |
|
||||
| `FileChanged` | `watchPaths` | 文件变更后更新监控路径 |
|
||||
| `WorktreeCreate` | `worktreePath` | Worktree 创建通知 |
|
||||
|
||||
## Hook 匹配机制：getMatchingHooks
|
||||
|
||||
`getMatchingHooks()`（`src/utils/hooks.ts`，`getMatchingHooks` 函数）负责从所有来源中查找匹配的 Hook：
|
||||
`getMatchingHooks()`（`hooks.ts:1685-1956`）负责从所有来源中查找匹配的 Hook：
|
||||
|
||||
### 多来源合并
|
||||
|
||||
@@ -157,7 +143,7 @@ getHooksConfig()
|
||||
|
||||
### 匹配规则
|
||||
|
||||
`matcher` 字段支持三种模式（`matchesPattern()` 函数，`src/utils/hooks.ts`）：
|
||||
`matcher` 字段支持三种模式（`matchesPattern()`, `hooks.ts:1428-1463`）：
|
||||
|
||||
```
|
||||
"Write" → 精确匹配
|
||||
@@ -168,7 +154,7 @@ getHooksConfig()
|
||||
|
||||
### if 条件过滤
|
||||
|
||||
Hook 可以指定 `if` 条件，只在特定输入时触发。`prepareIfConditionMatcher()`（`src/utils/hooks.ts`，`prepareIfConditionMatcher` 函数）预编译匹配器：
|
||||
Hook 可以指定 `if` 条件，只在特定输入时触发。`prepareIfConditionMatcher()`（`hooks.ts:1472-1503`）预编译匹配器：
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -183,11 +169,11 @@ Hook 可以指定 `if` 条件，只在特定输入时触发。`prepareIfConditio
|
||||
|
||||
### Hook 去重
|
||||
|
||||
同一个 Hook 命令在不同配置层级（user/project/local）可能重复。系统按四部分复合键做 Map 去重：`${pluginRoot}\0${shell}\0${command}\0${ifCondition}`（由 `hookDedupKey()` 函数构建），保留**最后合并的层级**。
|
||||
同一个 Hook 命令在不同配置层级（user/project/local）可能重复。系统按 `pluginRoot\0command` 做 Map 去重，保留**最后合并的层级**。
|
||||
|
||||
## 工作区信任检查
|
||||
|
||||
**所有 Hook 都要求工作区信任**（`shouldSkipHookDueToTrust()` 函数，`src/utils/hooks.ts`）。这是纵深防御措施——防止恶意仓库的 `.claude/settings.json` 在未信任的情况下执行任意命令。
|
||||
**所有 Hook 都要求工作区信任**（`shouldSkipHookDueToTrust()`, `hooks.ts:286-296`）。这是纵深防御措施——防止恶意仓库的 `.claude/settings.json` 在未信任的情况下执行任意命令。
|
||||
|
||||
```typescript
|
||||
// 交互模式下，所有 Hook 要求信任
|
||||
@@ -240,13 +226,13 @@ SDK 非交互模式下信任是隐式的（`getIsNonInteractiveSession()` 为 tr
|
||||
|
||||
## Session Hook 的生命周期
|
||||
|
||||
Agent 和 Skill 的前置 Hook 通过 `registerFrontmatterHooks()` 注册（调用位置：`src/tools/AgentTool/runAgent.ts`；定义位置：`src/utils/hooks/registerFrontmatterHooks.ts`），绑定到 agent 的 session ID。Agent 结束时通过 `clearSessionHooks()`（定义位置：`src/utils/hooks/sessionHooks.ts`）清理。
|
||||
Agent 和 Skill 的前置 Hook 通过 `registerFrontmatterHooks()` 注册（`runAgent.ts:567-575`），绑定到 agent 的 session ID。Agent 结束时通过 `clearSessionHooks()` 清理。
|
||||
|
||||
```typescript
|
||||
// runAgent.ts — 注册 agent 的前置 Hook
|
||||
// runAgent.ts:567 — 注册 agent 的前置 Hook
|
||||
registerFrontmatterHooks(rootSetAppState, agentId, agentDefinition.hooks, ...)
|
||||
|
||||
// runAgent.ts — finally 块清理
|
||||
// runAgent.ts:820 — finally 块清理
|
||||
clearSessionHooks(rootSetAppState, agentId)
|
||||
```
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@ keywords: ["MCP", "Model Context Protocol", "工具扩展", "MCP 客户端", "
|
||||
```
|
||||
settings.json: { mcpServers: { "my-db": { command: "npx", args: [...] } } }
|
||||
↓
|
||||
getAllMcpConfigs() ← enterprise 独占或合并 user/project/local + plugin + claude.ai
|
||||
getAllMcpConfigs() ← 合并 user/project/local 三级配置
|
||||
↓
|
||||
useManageMCPConnections() ← React Hook 管理连接生命周期
|
||||
↓
|
||||
|
||||
@@ -48,7 +48,7 @@ Skill 的核心洞见：**复杂任务的关键不在代码逻辑，而在 Promp
|
||||
1. `readdir` 扫描目录 → 仅保留 `isDirectory()` 或 `isSymbolicLink()` 的条目
|
||||
2. 在每个子目录中查找 `SKILL.md`，未找到则跳过
|
||||
3. `parseFrontmatter()` 解析 YAML 头部，提取 `whenToUse`、`allowedTools`、`context` 等字段
|
||||
4. `parseSkillFrontmatterFields()`（第 185 行）统一解析 16 个 frontmatter 字段
|
||||
4. `parseSkillFrontmatterFields()`（第 185 行）统一解析 17 个 frontmatter 字段
|
||||
5. `createSkillCommand()`（第 270 行）构造 `Command` 对象
|
||||
|
||||
**去重机制**：使用 `realpath()` 解析符号链接获得规范路径（`getFileIdentity`，第 118 行），避免通过符号链接或重叠父目录导致的重复加载。
|
||||
@@ -94,7 +94,7 @@ shell: ["bash"] # Shell 执行环境
|
||||
---
|
||||
```
|
||||
|
||||
解析后有 16 个字段被提取，其中 `allowedTools`、`model`、`effort` 在执行时动态修改 `toolPermissionContext`。
|
||||
解析后有 17 个字段被提取，其中 `allowedTools`、`model`、`effort` 在执行时动态修改 `toolPermissionContext`。
|
||||
|
||||
## 两条执行路径：Inline vs Fork
|
||||
|
||||
@@ -128,12 +128,12 @@ Fork 模式适用于需要强隔离的场景（如长时间运行的审查任务
|
||||
|
||||
## 权限模型：Safe Properties 白名单
|
||||
|
||||
`checkPermissions()`（第 433 行）实现了一个五层权限检查：
|
||||
`checkPermissions()`（第 433 行）实现了一个四层权限检查：
|
||||
|
||||
```
|
||||
1. Deny 规则匹配（支持精确匹配和 prefix:* 通配符）
|
||||
↓ 未命中
|
||||
2. 远程 canonical Skill 自动放行（EXPERIMENTAL_SKILL_SEARCH + USER_TYPE === 'ant'）
|
||||
2. 官方市场 Skill 自动放行（plugin + isOfficialMarketplaceName）
|
||||
↓ 未命中
|
||||
3. Allow 规则匹配
|
||||
↓ 未命中
|
||||
@@ -142,7 +142,7 @@ Fork 模式适用于需要强隔离的场景（如长时间运行的审查任务
|
||||
5. Ask 用户确认（附带精确匹配和前缀匹配两条建议规则）
|
||||
```
|
||||
|
||||
**Safe Properties**（`SAFE_SKILL_PROPERTIES`，第 876 行）是一个包含 30 个属性名的白名单（覆盖 `PromptCommand` 和 `CommandBase` 两个类型的所有安全属性）。任何不在白名单中的**有意义的属性值**（排除 `undefined`、`null`、空数组、空对象）都会触发权限请求。这是**正向安全**设计——未来新增的属性默认需要权限。
|
||||
**Safe Properties**（`SAFE_SKILL_PROPERTIES`，第 876 行）是一个包含 28 个属性名的白名单。任何不在白名单中的**有意义的属性值**（排除 `undefined`、`null`、空数组、空对象）都会触发权限请求。这是**正向安全**设计——未来新增的属性默认需要权限。
|
||||
|
||||
## Prompt 预算：1% 上下文窗口的截断策略
|
||||
|
||||
@@ -205,7 +205,7 @@ score = usageCount × max(0.5^(daysSinceUse / 7), 0.1)
|
||||
```
|
||||
磁盘 SKILL.md
|
||||
↓ parseFrontmatter()
|
||||
↓ parseSkillFrontmatterFields() → 16 个字段
|
||||
↓ parseSkillFrontmatterFields() → 17 个字段
|
||||
↓ createSkillCommand() → Command 对象
|
||||
↓ 去重（realpath + seenFileIds）
|
||||
↓ 条件 Skill → conditionalSkills Map（等待路径匹配激活）
|
||||
@@ -214,7 +214,7 @@ score = usageCount × max(0.5^(daysSinceUse / 7), 0.1)
|
||||
↓ formatCommandsWithinBudget() → 截断后的 Skill 列表注入 System Prompt
|
||||
↓ AI 选择匹配的 Skill
|
||||
↓ SkillTool.validateInput() → 名称校验 + 存在性检查
|
||||
↓ SkillTool.checkPermissions() → 五层权限检查
|
||||
↓ SkillTool.checkPermissions() → 四层权限检查
|
||||
↓ SkillTool.call() → inline 或 fork 执行
|
||||
↓ contextModifier() → 注入 allowedTools + model + effort
|
||||
↓ recordSkillUsage() → 更新使用频率排名
|
||||
|
||||
@@ -1,209 +0,0 @@
|
||||
# Claude Code 远程服务器依赖
|
||||
|
||||
> 只列出代码中实际发起网络请求的远程服务。本地服务、npm 包依赖、展示用 URL 不包含在内。
|
||||
|
||||
## 总览表
|
||||
|
||||
| # | 服务 | 远程端点 | 协议 | 状态 |
|
||||
|---|---|---|---|---|
|
||||
| 1 | Anthropic API | `api.anthropic.com` | HTTPS | 默认启用 |
|
||||
| 2 | AWS Bedrock | `bedrock-runtime.*.amazonaws.com` | HTTPS | 需 `CLAUDE_CODE_USE_BEDROCK=1` |
|
||||
| 3 | Google Vertex AI | `{region}-aiplatform.googleapis.com` | HTTPS | 需 `CLAUDE_CODE_USE_VERTEX=1` |
|
||||
| 4 | Azure Foundry | `{resource}.services.ai.azure.com` | HTTPS | 需 `CLAUDE_CODE_USE_FOUNDRY=1` |
|
||||
| 5 | OAuth (Anthropic) | `platform.claude.com`, `claude.com`, `claude.ai` | HTTPS | 用户登录时 |
|
||||
| 6 | GrowthBook | `api.anthropic.com` (remoteEval) | HTTPS | 默认启用 |
|
||||
| 7 | Sentry | 可配置 (`SENTRY_DSN`) | HTTPS | 需设环境变量 |
|
||||
| 8 | Datadog | 可配置 (`DATADOG_LOGS_ENDPOINT`) | HTTPS | 需设环境变量 |
|
||||
| 9 | OpenTelemetry Collector | 可配置 (`OTEL_EXPORTER_OTLP_ENDPOINT`) | gRPC/HTTP | 需设环境变量 |
|
||||
| 10 | 1P Event Logging | `api.anthropic.com/api/event_logging/batch` | HTTPS | 默认启用 |
|
||||
| 11 | BigQuery Metrics | `api.anthropic.com/api/claude_code/metrics` | HTTPS | 默认启用 |
|
||||
| 12 | MCP Proxy | `mcp-proxy.anthropic.com` | HTTPS+WS | 使用 MCP 工具时 |
|
||||
| 13 | MCP Registry | `api.anthropic.com/mcp-registry` | HTTPS | 查询 MCP 服务器时 |
|
||||
| 14 | Bing Search | `www.bing.com` | HTTPS | WebSearch 工具 |
|
||||
| 15 | Google Cloud Storage (更新) | `storage.googleapis.com` | HTTPS | 版本检查 |
|
||||
| 16 | GitHub Raw (Changelog/Stats) | `raw.githubusercontent.com` | HTTPS | 更新提示 |
|
||||
| 17 | Claude in Chrome Bridge | `bridge.claudeusercontent.com` | WSS | Chrome 集成 |
|
||||
| 18 | CCR Upstream Proxy | `api.anthropic.com` | WS | CCR 远程会话 |
|
||||
| 19 | Voice STT | `api.anthropic.com/api/ws/...` | WSS | Voice Mode |
|
||||
| 20 | Desktop App Download | `claude.ai/api/desktop/...` | HTTPS | 下载引导 |
|
||||
|
||||
---
|
||||
|
||||
## 详细说明
|
||||
|
||||
### 1. Anthropic Messages API
|
||||
|
||||
核心 LLM 推理服务，发送对话消息、接收流式响应。
|
||||
|
||||
- **端点**: `https://api.anthropic.com` (生产) / `https://api-staging.anthropic.com` (staging)
|
||||
- **覆盖**: `ANTHROPIC_BASE_URL` 环境变量
|
||||
- **认证**: API Key / OAuth Token
|
||||
- **文件**: `src/services/api/client.ts`, `src/services/api/claude.ts`
|
||||
|
||||
### 2. AWS Bedrock
|
||||
|
||||
- **端点**: `bedrock-runtime.{region}.amazonaws.com`
|
||||
- **认证**: AWS 凭证链 / `AWS_BEARER_TOKEN_BEDROCK`
|
||||
- **文件**: `src/services/api/client.ts:153-190`, `src/utils/aws.ts`
|
||||
|
||||
### 3. Google Vertex AI
|
||||
|
||||
- **端点**: `{region}-aiplatform.googleapis.com`
|
||||
- **认证**: `GoogleAuth` + `cloud-platform` scope
|
||||
- **文件**: `src/services/api/client.ts:228-298`
|
||||
|
||||
### 4. Azure Foundry
|
||||
|
||||
- **端点**: `https://{resource}.services.ai.azure.com/anthropic/v1/messages`
|
||||
- **认证**: API Key 或 Azure AD `DefaultAzureCredential`
|
||||
- **文件**: `src/services/api/client.ts:191-220`
|
||||
|
||||
### 5. OAuth
|
||||
|
||||
OAuth 2.0 + PKCE 授权码流程。
|
||||
|
||||
- **端点**:
|
||||
- `https://platform.claude.com/oauth/authorize` — 授权页
|
||||
- `https://claude.com/cai/oauth/authorize` — Claude.ai 授权
|
||||
- `https://platform.claude.com/v1/oauth/token` — Token 交换
|
||||
- `https://api.anthropic.com/api/oauth/claude_cli/create_api_key` — 创建 API Key
|
||||
- `https://api.anthropic.com/api/oauth/claude_cli/roles` — 获取角色
|
||||
- `https://claude.ai/oauth/claude-code-client-metadata` — MCP 客户端元数据
|
||||
- `https://claude.fedstart.com` — FedStart 政府部署
|
||||
- **文件**: `src/constants/oauth.ts`, `src/services/oauth/`
|
||||
|
||||
### 6. GrowthBook (功能开关)
|
||||
|
||||
- **端点**: `https://api.anthropic.com/` (remoteEval 模式) 或 `CLAUDE_GB_ADAPTER_URL`
|
||||
- **SDK Keys**: `sdk-zAZezfDKGoZuXXKe` (外部), `sdk-xRVcrliHIlrg4og4` (ant prod), `sdk-yZQvlplybuXjYh6L` (ant dev)
|
||||
- **文件**: `src/services/analytics/growthbook.ts`, `src/constants/keys.ts`
|
||||
|
||||
### 7. Sentry (错误追踪)
|
||||
|
||||
- **激活**: 设置 `SENTRY_DSN` (默认未配置)
|
||||
- **行为**: 仅错误上报，自动过滤敏感 header
|
||||
- **文件**: `src/utils/sentry.ts`
|
||||
|
||||
### 8. Datadog (日志)
|
||||
|
||||
- **激活**: 同时设 `DATADOG_LOGS_ENDPOINT` + `DATADOG_API_KEY` (默认未配置)
|
||||
- **文件**: `src/services/analytics/datadog.ts`
|
||||
|
||||
### 9. OpenTelemetry Collector
|
||||
|
||||
- **激活**: `CLAUDE_CODE_ENABLE_TELEMETRY=1` 或 `OTEL_*` 环境变量
|
||||
- **协议**: gRPC / HTTP / Protobuf，支持 OTLP 和 Prometheus 导出
|
||||
- **文件**: `src/utils/telemetry/instrumentation.ts`
|
||||
|
||||
### 10. 1P Event Logging (内部事件)
|
||||
|
||||
- **端点**: `https://api.anthropic.com/api/event_logging/batch`
|
||||
- **协议**: 批量导出 (10s 间隔, 每批 200 事件)
|
||||
- **文件**: `src/services/analytics/firstPartyEventLoggingExporter.ts`
|
||||
|
||||
### 11. BigQuery Metrics
|
||||
|
||||
- **端点**: `https://api.anthropic.com/api/claude_code/metrics`
|
||||
- **文件**: `src/utils/telemetry/bigqueryExporter.ts`
|
||||
|
||||
### 12. MCP Proxy
|
||||
|
||||
Anthropic 托管的 MCP 服务器代理。
|
||||
|
||||
- **端点**: `https://mcp-proxy.anthropic.com/v1/mcp/{server_id}`
|
||||
- **认证**: Claude.ai OAuth tokens
|
||||
- **文件**: `src/services/mcp/client.ts`, `src/constants/oauth.ts`
|
||||
|
||||
### 13. MCP Registry
|
||||
|
||||
获取官方 MCP 服务器列表。
|
||||
|
||||
- **端点**: `https://api.anthropic.com/mcp-registry/v0/servers?version=latest&visibility=commercial`
|
||||
- **文件**: `src/services/mcp/officialRegistry.ts`
|
||||
|
||||
### 14. Bing Search
|
||||
|
||||
WebSearch 工具的默认适配器，抓取 Bing 搜索结果。
|
||||
|
||||
- **端点**: `https://www.bing.com/search?q={query}&setmkt=en-US`
|
||||
- **文件**: `src/tools/WebSearchTool/adapters/bingAdapter.ts`
|
||||
|
||||
另外还有 Domain Blocklist 查询:
|
||||
- **端点**: `https://api.anthropic.com/api/web/domain_info?domain={domain}`
|
||||
- **文件**: `src/tools/WebFetchTool/utils.ts`
|
||||
|
||||
### 15. Google Cloud Storage (自动更新)
|
||||
|
||||
- **端点**: `https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases`
|
||||
- **文件**: `src/utils/autoUpdater.ts`
|
||||
|
||||
### 16. GitHub Raw Content
|
||||
|
||||
- **端点**: `https://raw.githubusercontent.com/anthropics/claude-code/refs/heads/main/CHANGELOG.md`
|
||||
- **端点**: `https://raw.githubusercontent.com/anthropics/claude-plugins-official/refs/heads/stats/stats/plugin-installs.json`
|
||||
- **文件**: `src/utils/releaseNotes.ts`, `src/utils/plugins/installCounts.ts`
|
||||
|
||||
### 17. Claude in Chrome Bridge
|
||||
|
||||
- **端点**: `wss://bridge.claudeusercontent.com` (生产) / `wss://bridge-staging.claudeusercontent.com` (staging)
|
||||
- **文件**: `src/utils/claudeInChrome/mcpServer.ts`
|
||||
|
||||
### 18. CCR Upstream Proxy
|
||||
|
||||
- **端点**: `ws://api.anthropic.com/v1/code/upstreamproxy/ws`
|
||||
- **激活**: `CLAUDE_CODE_REMOTE=1` + `CCR_UPSTREAM_PROXY_ENABLED=1`
|
||||
- **文件**: `src/upstreamproxy/upstreamproxy.ts`
|
||||
|
||||
### 19. Voice STT
|
||||
|
||||
- **端点**: `wss://api.anthropic.com/api/ws/...`
|
||||
- **文件**: `src/services/voiceStreamSTT.ts`
|
||||
|
||||
### 20. Desktop App Download
|
||||
|
||||
- **端点**: `https://claude.ai/api/desktop/win32/x64/exe/latest/redirect` (Windows)
|
||||
- **端点**: `https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect` (macOS)
|
||||
- **文件**: `src/components/DesktopHandoff.tsx`
|
||||
|
||||
---
|
||||
|
||||
## Anthropic API 辅助端点汇总
|
||||
|
||||
以下端点都挂在 `api.anthropic.com` 上，按功能分类:
|
||||
|
||||
| 端点路径 | 用途 | 文件 |
|
||||
|---|---|---|
|
||||
| `/api/event_logging/batch` | 事件批量上报 | `src/services/analytics/firstPartyEventLoggingExporter.ts` |
|
||||
| `/api/claude_code/metrics` | BigQuery 指标导出 | `src/utils/telemetry/bigqueryExporter.ts` |
|
||||
| `/api/oauth/claude_cli/create_api_key` | 创建 API Key | `src/constants/oauth.ts` |
|
||||
| `/api/oauth/claude_cli/roles` | 获取用户角色 | `src/constants/oauth.ts` |
|
||||
| `/api/oauth/accounts/grove` | 通知设置 | `src/services/api/grove.ts` |
|
||||
| `/api/oauth/organizations/{id}/referral/*` | 推荐活动 | `src/services/api/referral.ts` |
|
||||
| `/api/oauth/organizations/{id}/overage_credit_grant` | 超额信用 | `src/services/api/overageCreditGrant.ts` |
|
||||
| `/api/oauth/organizations/{id}/admin_requests` | 管理请求 | `src/services/api/adminRequests.ts` |
|
||||
| `/api/web/domain_info?domain={}` | 域名安全检查 | `src/tools/WebFetchTool/utils.ts` |
|
||||
| `/api/claude_code/settings` | 设置同步 | `src/services/settingsSync/index.ts` |
|
||||
| `/api/claude_code/managed_settings` | 企业托管设置 (1h 轮询) | `src/services/remoteManagedSettings/index.ts` |
|
||||
| `/api/claude_code/team_memory?repo={}` | 团队记忆同步 | `src/services/teamMemorySync/index.ts` |
|
||||
| `/api/auth/trusted_devices` | 可信设备注册 | `src/bridge/trustedDevice.ts` |
|
||||
| `/api/organizations/{id}/claude_code/buddy_react` | Companion 反应 | `src/buddy/companionReact.ts` |
|
||||
| `/mcp-registry/v0/servers` | MCP 服务器注册表 | `src/services/mcp/officialRegistry.ts` |
|
||||
| `/v1/files` | 文件上传/下载 | `src/services/api/filesApi.ts` |
|
||||
| `/v1/sessions/{id}/events` | 会话历史 | `src/assistant/sessionHistory.ts` |
|
||||
| `/v1/code/triggers` | 远程触发器 | `src/tools/RemoteTriggerTool/RemoteTriggerTool.ts` |
|
||||
| `/v1/organizations/{id}/mcp_servers` | 组织 MCP 配置 | `src/services/mcp/claudeai.ts` |
|
||||
|
||||
## 非 Anthropic 远程域名汇总
|
||||
|
||||
| 域名 | 服务 | 协议 |
|
||||
|---|---|---|
|
||||
| `bedrock-runtime.*.amazonaws.com` | AWS Bedrock | HTTPS |
|
||||
| `{region}-aiplatform.googleapis.com` | Google Vertex AI | HTTPS |
|
||||
| `{resource}.services.ai.azure.com` | Azure Foundry | HTTPS |
|
||||
| `www.bing.com` | Bing 搜索 | HTTPS |
|
||||
| `storage.googleapis.com` | 自动更新 | HTTPS |
|
||||
| `raw.githubusercontent.com` | Changelog / 插件统计 | HTTPS |
|
||||
| `bridge.claudeusercontent.com` | Chrome Bridge | WSS |
|
||||
| `platform.claude.com` | OAuth 授权页 | HTTPS |
|
||||
| `claude.com` / `claude.ai` | OAuth / 下载 | HTTPS |
|
||||
| `claude.fedstart.com` | FedStart OAuth | HTTPS |
|
||||
@@ -1,457 +0,0 @@
|
||||
# Feature 探索计划书
|
||||
|
||||
> 生成日期：2026-04-02
|
||||
> 代码库中已识别 89 个 feature flag，本文档按实现完整度和探索价值分级，制定探索优先级和路线图。
|
||||
>
|
||||
> **已完成**：BUDDY（✅ 2026-04-02）、TRANSCRIPT_CLASSIFIER / Auto Mode（✅ 2026-04-02）
|
||||
|
||||
---
|
||||
|
||||
## 一、总览
|
||||
|
||||
### 按实现状态分类
|
||||
|
||||
| 状态 | 数量 | 说明 |
|
||||
|------|------|------|
|
||||
| 已实现/可用 | 11 | 代码完整，开启 feature 后可运行（可能需要 OAuth 等外部依赖） |
|
||||
| 部分实现 | 8 | 核心逻辑存在但关键模块为 stub，需要补全 |
|
||||
| 纯 Stub | 15 | 所有函数/工具返回空值，需要从零实现 |
|
||||
| N/A | 55+ | 内部基础设施、低引用量辅助功能，或反编译丢失过多 |
|
||||
|
||||
### 启用方式
|
||||
|
||||
所有 feature 通过环境变量启用：
|
||||
|
||||
```bash
|
||||
# 单个 feature
|
||||
FEATURE_BUDDY=1 bun run dev
|
||||
|
||||
# 多个 feature 组合
|
||||
FEATURE_KAIROS=1 FEATURE_PROACTIVE=1 FEATURE_FORK_SUBAGENT=1 bun run dev
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二、Tier 1 — 已实现/可用（优先探索）
|
||||
|
||||
### 2.1 KAIROS（常驻助手模式）⭐ 最高优先级
|
||||
|
||||
- **引用数**：154（全库最大）
|
||||
- **功能**：将 CLI 变为常驻后台助手，支持：
|
||||
- 持久化 bridge 会话（跨重启复用 session）
|
||||
- 后台执行任务（用户离开终端时继续工作）
|
||||
- 推送通知到移动端（任务完成/需要输入时）
|
||||
- 每日记忆日志 + `/dream` 知识蒸馏
|
||||
- 外部频道消息接入（Slack/Discord/Telegram）
|
||||
- **子 Feature**：
|
||||
|
||||
| 子 Feature | 引用 | 功能 |
|
||||
|-----------|------|------|
|
||||
| `KAIROS_BRIEF` | 39 | Brief 工具（`SendUserMessage`），结构化消息输出 |
|
||||
| `KAIROS_CHANNELS` | 19 | 外部频道消息接入 |
|
||||
| `KAIROS_PUSH_NOTIFICATION` | 4 | 移动端推送通知 |
|
||||
| `KAIROS_GITHUB_WEBHOOKS` | 3 | GitHub PR webhook 订阅 |
|
||||
| `KAIROS_DREAM` | 1 | 夜间记忆蒸馏 |
|
||||
|
||||
- **关键文件**：`src/assistant/`、`src/tools/BriefTool/`、`src/services/mcp/channelNotification.ts`、`src/memdir/memdir.ts`
|
||||
- **外部依赖**：Anthropic OAuth（claude.ai 订阅）、GrowthBook 特性门控
|
||||
- **探索命令**：`FEATURE_KAIROS=1 FEATURE_KAIROS_BRIEF=1 FEATURE_PROACTIVE=1 bun run dev`
|
||||
|
||||
**探索步骤**：
|
||||
1. 开启 feature，观察启动行为变化
|
||||
2. 测试 `/assistant`、`/brief` 命令
|
||||
3. 验证 BriefTool 输出模式
|
||||
4. 尝试频道消息接入
|
||||
5. 测试 `/dream` 记忆蒸馏
|
||||
|
||||
---
|
||||
|
||||
### ~~2.2 TRANSCRIPT_CLASSIFIER（Auto Mode 分类器）~~ ✅ 已完成
|
||||
|
||||
- **引用数**：108
|
||||
- **功能**：使用 LLM 对用户意图进行分类，实现 auto mode（自动决定工具权限）
|
||||
- **状态**：✅ prompt 模板已重建，功能完整可用（2026-04-02 完成）
|
||||
|
||||
---
|
||||
|
||||
### 2.3 VOICE_MODE（语音输入）
|
||||
|
||||
- **引用数**：46
|
||||
- **功能**：按键说话（Push-to-Talk），音频流式传输到 Anthropic STT 端点（Nova 3），实时转录显示
|
||||
- **当前状态**：**完整实现**，包括录音、WebSocket 流、转录插入
|
||||
- **关键文件**：`src/voice/voiceModeEnabled.ts`、`src/hooks/useVoice.ts`、`src/services/voiceStreamSTT.ts`
|
||||
- **外部依赖**：Anthropic OAuth（非 API key）、macOS 原生音频或 SoX
|
||||
- **探索命令**：`FEATURE_VOICE_MODE=1 bun run dev`
|
||||
- **默认快捷键**：长按空格键录音
|
||||
|
||||
**探索步骤**：
|
||||
1. 确认 OAuth token 可用
|
||||
2. 测试按住空格录音 → 释放后转录
|
||||
3. 验证实时中间转录显示
|
||||
4. 测试 `/voice` 命令切换
|
||||
|
||||
---
|
||||
|
||||
### 2.4 TEAMMEM（团队共享记忆）
|
||||
|
||||
- **引用数**：51
|
||||
- **功能**：基于 GitHub 仓库的团队共享记忆系统，`memory/team/` 目录双向同步到 Anthropic 服务器
|
||||
- **当前状态**：**完整实现**，包括增量同步、冲突解决、密钥扫描、路径穿越防护
|
||||
- **关键文件**：`src/services/teamMemorySync/`（index、watcher、secretScanner）、`src/memdir/teamMemPaths.ts`
|
||||
- **外部依赖**：Anthropic OAuth + GitHub remote（`getGithubRepo()`）
|
||||
- **探索命令**：`FEATURE_TEAMMEM=1 bun run dev`
|
||||
|
||||
**探索步骤**：
|
||||
1. 确认项目有 GitHub remote
|
||||
2. 开启后观察 `memory/team/` 目录创建
|
||||
3. 测试团队记忆写入和同步
|
||||
4. 验证密钥扫描防护
|
||||
|
||||
---
|
||||
|
||||
### 2.5 COORDINATOR_MODE（多 Agent 编排）
|
||||
|
||||
- **引用数**：32
|
||||
- **功能**：CLI 变为编排者，通过 AgentTool 派发任务给多个 worker 并行执行
|
||||
- **当前状态**：核心逻辑实现，worker agent 模块为 stub
|
||||
- **关键文件**：`src/coordinator/coordinatorMode.ts`（系统 prompt 完整）、`src/coordinator/workerAgent.ts`（stub）
|
||||
- **限制**：编排者只能使用 AgentTool/TaskStop/SendMessage，不能直接操作文件
|
||||
- **探索命令**：`FEATURE_COORDINATOR_MODE=1 CLAUDE_CODE_COORDINATOR_MODE=1 bun run dev`
|
||||
|
||||
**探索步骤**：
|
||||
1. 补全 `workerAgent.ts` stub
|
||||
2. 测试多 worker 并行任务派发
|
||||
3. 验证 worker 结果汇总
|
||||
|
||||
---
|
||||
|
||||
### 2.6 BRIDGE_MODE（远程控制）
|
||||
|
||||
- **引用数**：28
|
||||
- **功能**：本地 CLI 注册为 bridge 环境，可从 claude.ai 或其他控制面远程驱动
|
||||
- **当前状态**：v1（env-based）和 v2（env-less）实现均存在
|
||||
- **关键文件**：`src/bridge/bridgeEnabled.ts`、`src/bridge/replBridge.ts`（v1）、`src/bridge/remoteBridgeCore.ts`（v2）
|
||||
- **外部依赖**：claude.ai OAuth、GrowthBook 门控 `tengu_ccr_bridge`
|
||||
- **探索命令**：`FEATURE_BRIDGE_MODE=1 bun run dev`
|
||||
|
||||
---
|
||||
|
||||
### 2.7 FORK_SUBAGENT（上下文继承子 Agent）
|
||||
|
||||
- **引用数**：4
|
||||
- **功能**：AgentTool 生成 fork 子 agent，继承父级完整对话上下文，优化 prompt cache
|
||||
- **当前状态**：**完整实现**（`forkSubagent.ts`），支持 worktree 隔离通知、递归防护
|
||||
- **关键文件**：`src/tools/AgentTool/forkSubagent.ts`
|
||||
- **探索命令**：`FEATURE_FORK_SUBAGENT=1 bun run dev`
|
||||
|
||||
---
|
||||
|
||||
### 2.8 TOKEN_BUDGET（Token 预算控制）
|
||||
|
||||
- **引用数**：9
|
||||
- **功能**：解析用户指定的 token 预算（如 "spend 2M tokens"），自动持续工作直到达到目标
|
||||
- **当前状态**：解析器**完整实现**，支持简写和详细语法；QueryEngine 中的周转逻辑已连接
|
||||
- **关键文件**：`src/utils/tokenBudget.ts`、`src/QueryEngine.ts`
|
||||
- **探索命令**：`FEATURE_TOKEN_BUDGET=1 bun run dev`
|
||||
|
||||
---
|
||||
|
||||
### 2.9 MCP_SKILLS（MCP 技能发现）
|
||||
|
||||
- **引用数**：9
|
||||
- **功能**：将 MCP 服务器提供的 prompt 类型命令筛选为可调用技能
|
||||
- **当前状态**：**功能性实现**（config 门控筛选器）
|
||||
- **关键文件**：`src/commands.ts`（`getMcpSkillCommands()`）
|
||||
- **探索命令**：`FEATURE_MCP_SKILLS=1 bun run dev`
|
||||
|
||||
---
|
||||
|
||||
### 2.10 TREE_SITTER_BASH（Bash AST 解析）
|
||||
|
||||
- **引用数**：3
|
||||
- **功能**：纯 TypeScript bash 命令 AST 解析器，用于 fail-closed 权限匹配
|
||||
- **当前状态**：**完整实现**（`bashParser.ts` ~2000行 + `ast.ts` ~400行）
|
||||
- **关键文件**：`src/utils/vendor/tree-sitter-bash/`
|
||||
- **探索命令**：`FEATURE_TREE_SITTER_BASH=1 bun run dev`
|
||||
|
||||
---
|
||||
|
||||
### ~~2.11 BUDDY（虚拟伙伴）~~ ✅ 已完成
|
||||
|
||||
- **引用数**：16
|
||||
- **功能**：`/buddy` 命令，支持 hatch/rehatch/pet/mute/unmute
|
||||
- **状态**：✅ 已合入，功能完整可用（2026-04-02 完成）
|
||||
|
||||
---
|
||||
|
||||
## 三、Tier 2 — 部分实现（需要补全）
|
||||
|
||||
### 3.1 PROACTIVE（主动模式）
|
||||
|
||||
- **引用数**：37
|
||||
- **功能**：Tick 驱动的自主代理，定时唤醒执行工作，配合 SleepTool 控制节奏
|
||||
- **当前状态**：核心模块 `src/proactive/index.ts` **全部 stub**（activate/deactivate/pause 返回 false 或空操作）
|
||||
- **依赖**：与 KAIROS 强绑定（所有检查都是 `feature('PROACTIVE') || feature('KAIROS')`）
|
||||
- **补全工作量**：中等 — 需要实现 tick 生成、SleepTool 集成、暂停/恢复逻辑
|
||||
|
||||
### 3.2 BASH_CLASSIFIER（Bash 命令分类器）
|
||||
|
||||
- **引用数**：45
|
||||
- **功能**：LLM 驱动的 bash 命令意图分类（允许/拒绝/询问）
|
||||
- **当前状态**：`bashClassifier.ts` **全部 stub**（`matches: false`）
|
||||
- **补全工作量**：大 — 需要 LLM 调用实现、prompt 设计
|
||||
|
||||
### 3.3 ULTRAPLAN（增强规划）
|
||||
|
||||
- **引用数**：10
|
||||
- **功能**：关键字触发增强计划模式，输入 "ultraplan" 自动转为 plan
|
||||
- **当前状态**：关键字检测**完整实现**，`/ultraplan` 命令**为 stub**
|
||||
- **补全工作量**：小 — 只需实现命令处理逻辑
|
||||
|
||||
### 3.4 EXPERIMENTAL_SKILL_SEARCH（技能语义搜索）
|
||||
|
||||
- **引用数**：21
|
||||
- **功能**：DiscoverSkills 工具，根据当前任务语义搜索可用技能
|
||||
- **当前状态**：布线完整，核心搜索逻辑 stub
|
||||
- **补全工作量**：中等 — 需要实现搜索引擎和索引
|
||||
|
||||
### 3.5 CONTEXT_COLLAPSE（上下文折叠）
|
||||
|
||||
- **引用数**：20
|
||||
- **功能**：CtxInspectTool 让模型内省上下文窗口大小，优化压缩决策
|
||||
- **当前状态**：工具 stub，HISTORY_SNIP 子功能也 stub
|
||||
- **补全工作量**：中等
|
||||
|
||||
### 3.6 WORKFLOW_SCRIPTS（工作流自动化）
|
||||
|
||||
- **引用数**：10
|
||||
- **功能**：基于文件的自动化工作流 + `/workflows` 命令
|
||||
- **当前状态**：WorkflowTool、命令、加载器全部 stub
|
||||
- **补全工作量**：大 — 需要从零设计工作流 DSL
|
||||
|
||||
### 3.7 WEB_BROWSER_TOOL（浏览器工具）
|
||||
|
||||
- **引用数**：4
|
||||
- **功能**：模型可调用浏览器工具导航和交互网页
|
||||
- **当前状态**：工具注册存在，实现 stub
|
||||
- **补全工作量**：大
|
||||
|
||||
### 3.8 DAEMON（后台守护进程）
|
||||
|
||||
- **引用数**：3
|
||||
- **功能**：后台守护进程 + 远程控制服务器
|
||||
- **当前状态**：只有条件导入布线，无实现
|
||||
- **补全工作量**：极大
|
||||
|
||||
---
|
||||
|
||||
## 四、Tier 3 — 纯 Stub / N/A（低优先级）
|
||||
|
||||
| Feature | 引用 | 状态 | 说明 |
|
||||
|---------|------|------|------|
|
||||
| CHICAGO_MCP | 16 | N/A | Anthropic 内部 MCP 基础设施 |
|
||||
| UDS_INBOX | 17 | Stub | Unix 域套接字对等消息 |
|
||||
| MONITOR_TOOL | 13 | Stub | 文件/进程监控工具 |
|
||||
| BG_SESSIONS | 11 | Stub | 后台会话管理 |
|
||||
| SHOT_STATS | 10 | 无实现 | 逐 prompt 统计 |
|
||||
| EXTRACT_MEMORIES | 7 | 无实现 | 自动记忆提取 |
|
||||
| TEMPLATES | 6 | Stub | 项目/提示模板 |
|
||||
| LODESTONE | 6 | N/A | 内部基础设施 |
|
||||
| STREAMLINED_OUTPUT | 1 | — | 精简输出模式 |
|
||||
| HOOK_PROMPTS | 1 | — | Hook 提示词 |
|
||||
| CCR_AUTO_CONNECT | 3 | — | CCR 自动连接 |
|
||||
| CCR_MIRROR | 4 | — | CCR 镜像模式 |
|
||||
| CCR_REMOTE_SETUP | 1 | — | CCR 远程设置 |
|
||||
| NATIVE_CLIPBOARD_IMAGE | 2 | — | 原生剪贴板图片 |
|
||||
| CONNECTOR_TEXT | 7 | — | 连接器文本 |
|
||||
|
||||
以及其余 40+ 个低引用量 feature。
|
||||
|
||||
---
|
||||
|
||||
## 五、探索路线图
|
||||
|
||||
### Phase 1：快速验证（无外部依赖）
|
||||
|
||||
> 目标：确认代码可以正常运行，体验基本功能
|
||||
|
||||
| 优先级 | Feature | 命令 | 预期效果 |
|
||||
|--------|---------|------|----------|
|
||||
| 1 | BUDDY | `FEATURE_BUDDY=1 bun run dev` | `/buddy hatch` 生成伙伴 |
|
||||
| 2 | FORK_SUBAGENT | `FEATURE_FORK_SUBAGENT=1 bun run dev` | Agent 可生成上下文继承的子任务 |
|
||||
| 3 | TOKEN_BUDGET | `FEATURE_TOKEN_BUDGET=1 bun run dev` | 输入 "spend 500k tokens" 测试自动持续 |
|
||||
| 4 | TREE_SITTER_BASH | `FEATURE_TREE_SITTER_BASH=1 bun run dev` | 更精确的 bash 权限匹配 |
|
||||
| 5 | MCP_SKILLS | `FEATURE_MCP_SKILLS=1 bun run dev` | MCP 服务器 prompt 提升为技能 |
|
||||
|
||||
### Phase 2：核心功能探索（需要 OAuth）
|
||||
|
||||
> 目标：体验 KAIROS 全套能力
|
||||
|
||||
| 优先级 | Feature | 命令 | 预期效果 |
|
||||
|--------|---------|------|----------|
|
||||
| 1 | TRANSCRIPT_CLASSIFIER | `FEATURE_TRANSCRIPT_CLASSIFIER=1 bun run dev` | Auto mode 自动激活 |
|
||||
| 2 | KAIROS 全套 | `FEATURE_KAIROS=1 FEATURE_KAIROS_BRIEF=1 FEATURE_KAIROS_CHANNELS=1 FEATURE_PROACTIVE=1 bun run dev` | 常驻助手 + Brief 输出 + 频道消息 |
|
||||
| 3 | VOICE_MODE | `FEATURE_VOICE_MODE=1 bun run dev` | 按空格说话 |
|
||||
| 4 | TEAMMEM | `FEATURE_TEAMMEM=1 bun run dev` | 团队记忆同步 |
|
||||
| 5 | COORDINATOR_MODE | `FEATURE_COORDINATOR_MODE=1 CLAUDE_CODE_COORDINATOR_MODE=1 bun run dev` | 多 agent 编排 |
|
||||
|
||||
### Phase 3：Stub 补全开发
|
||||
|
||||
> 目标：将高价值 stub 实现为可用功能
|
||||
|
||||
| 优先级 | Feature | 补全难度 | 价值 |
|
||||
|--------|---------|----------|------|
|
||||
| 1 | PROACTIVE | 中 | 自主工作能力 |
|
||||
| 2 | ULTRAPLAN | 小 | 增强规划 |
|
||||
| 3 | CONTEXT_COLLAPSE | 中 | 长对话优化 |
|
||||
| 4 | EXPERIMENTAL_SKILL_SEARCH | 中 | 技能发现 |
|
||||
| 5 | BASH_CLASSIFIER | 大 | 安全增强 |
|
||||
|
||||
---
|
||||
|
||||
## 六、推荐组合方案
|
||||
|
||||
### "全功能助手"组合
|
||||
|
||||
```bash
|
||||
FEATURE_KAIROS=1 \
|
||||
FEATURE_KAIROS_BRIEF=1 \
|
||||
FEATURE_KAIROS_CHANNELS=1 \
|
||||
FEATURE_KAIROS_PUSH_NOTIFICATION=1 \
|
||||
FEATURE_PROACTIVE=1 \
|
||||
FEATURE_FORK_SUBAGENT=1 \
|
||||
FEATURE_TOKEN_BUDGET=1 \
|
||||
FEATURE_TRANSCRIPT_CLASSIFIER=1 \
|
||||
FEATURE_BUDDY=1 \
|
||||
bun run dev
|
||||
```
|
||||
|
||||
### "多 Agent 协作"组合
|
||||
|
||||
```bash
|
||||
FEATURE_COORDINATOR_MODE=1 \
|
||||
FEATURE_FORK_SUBAGENT=1 \
|
||||
FEATURE_BRIDGE_MODE=1 \
|
||||
FEATURE_BG_SESSIONS=1 \
|
||||
CLAUDE_CODE_COORDINATOR_MODE=1 \
|
||||
bun run dev
|
||||
```
|
||||
|
||||
### "开发者增强"组合
|
||||
|
||||
```bash
|
||||
FEATURE_TRANSCRIPT_CLASSIFIER=1 \
|
||||
FEATURE_TREE_SITTER_BASH=1 \
|
||||
FEATURE_TOKEN_BUDGET=1 \
|
||||
FEATURE_MCP_SKILLS=1 \
|
||||
FEATURE_CONTEXT_COLLAPSE=1 \
|
||||
bun run dev
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 七、风险与注意事项
|
||||
|
||||
1. **OAuth 依赖**：KAIROS、VOICE_MODE、TEAMMEM、BRIDGE_MODE 需要 Anthropic OAuth 认证（claude.ai 订阅），API key 用户无法使用
|
||||
2. **GrowthBook 门控**：部分功能（VOICE_MODE 的 `tengu_cobalt_frost`、TEAMMEM 的 `tengu_herring_clock`）即使 feature flag 开启，还需要服务端 GrowthBook 开关
|
||||
3. **反编译不完整**：所有"已实现"功能均为反编译产物，可能存在运行时错误，需要逐个验证
|
||||
4. **Proactive stub**：KAIROS 的自主工作能力依赖 PROACTIVE，但 PROACTIVE 核心是 stub，需先补全
|
||||
5. **tsc 错误**：代码库有 ~1341 个 TypeScript 编译错误（来自反编译），不影响 Bun 运行时但在 IDE 中会有大量红线
|
||||
|
||||
---
|
||||
|
||||
## 附录：Feature Flag 完整列表
|
||||
|
||||
共 89 个 feature flag（按引用数降序）：
|
||||
|
||||
| Feature | 引用 | Tier |
|
||||
|---------|------|------|
|
||||
| KAIROS | 154 | 1 |
|
||||
| TRANSCRIPT_CLASSIFIER | 108 | 1 |
|
||||
| TEAMMEM | 51 | 1 |
|
||||
| VOICE_MODE | 46 | 1 |
|
||||
| BASH_CLASSIFIER | 45 | 2 |
|
||||
| KAIROS_BRIEF | 39 | 1 |
|
||||
| PROACTIVE | 37 | 2 |
|
||||
| COORDINATOR_MODE | 32 | 1 |
|
||||
| BRIDGE_MODE | 28 | 1 |
|
||||
| EXPERIMENTAL_SKILL_SEARCH | 21 | 2 |
|
||||
| CONTEXT_COLLAPSE | 20 | 2 |
|
||||
| KAIROS_CHANNELS | 19 | 1 |
|
||||
| UDS_INBOX | 17 | 3 |
|
||||
| CHICAGO_MCP | 16 | 3 |
|
||||
| BUDDY | 16 | 1 |
|
||||
| HISTORY_SNIP | 15 | 2 |
|
||||
| MONITOR_TOOL | 13 | 3 |
|
||||
| COMMIT_ATTRIBUTION | 12 | — |
|
||||
| CACHED_MICROCOMPACT | 12 | — |
|
||||
| BG_SESSIONS | 11 | 3 |
|
||||
| WORKFLOW_SCRIPTS | 10 | 2 |
|
||||
| ULTRAPLAN | 10 | 2 |
|
||||
| SHOT_STATS | 10 | 3 |
|
||||
| TOKEN_BUDGET | 9 | 1 |
|
||||
| PROMPT_CACHE_BREAK_DETECTION | 9 | — |
|
||||
| MCP_SKILLS | 9 | 1 |
|
||||
| EXTRACT_MEMORIES | 7 | 3 |
|
||||
| CONNECTOR_TEXT | 7 | — |
|
||||
| TEMPLATES | 6 | 3 |
|
||||
| LODESTONE | 6 | 3 |
|
||||
| TREE_SITTER_BASH_SHADOW | 5 | — |
|
||||
| QUICK_SEARCH | 5 | — |
|
||||
| MESSAGE_ACTIONS | 5 | — |
|
||||
| DOWNLOAD_USER_SETTINGS | 5 | — |
|
||||
| DIRECT_CONNECT | 5 | — |
|
||||
| WEB_BROWSER_TOOL | 4 | 2 |
|
||||
| VERIFICATION_AGENT | 4 | — |
|
||||
| TERMINAL_PANEL | 4 | — |
|
||||
| SSH_REMOTE | 4 | — |
|
||||
| REVIEW_ARTIFACT | 4 | — |
|
||||
| REACTIVE_COMPACT | 4 | — |
|
||||
| KAIROS_PUSH_NOTIFICATION | 4 | 1 |
|
||||
| HISTORY_PICKER | 4 | — |
|
||||
| FORK_SUBAGENT | 4 | 1 |
|
||||
| CCR_MIRROR | 4 | — |
|
||||
| TREE_SITTER_BASH | 3 | 1 |
|
||||
| MEMORY_SHAPE_TELEMETRY | 3 | — |
|
||||
| MCP_RICH_OUTPUT | 3 | — |
|
||||
| KAIROS_GITHUB_WEBHOOKS | 3 | 1 |
|
||||
| FILE_PERSISTENCE | 3 | — |
|
||||
| DAEMON | 3 | 2 |
|
||||
| CCR_AUTO_CONNECT | 3 | — |
|
||||
| UPLOAD_USER_SETTINGS | 2 | — |
|
||||
| POWERSHELL_AUTO_MODE | 2 | — |
|
||||
| OVERFLOW_TEST_TOOL | 2 | — |
|
||||
| NEW_INIT | 2 | — |
|
||||
| NATIVE_CLIPBOARD_IMAGE | 2 | — |
|
||||
| HARD_FAIL | 2 | — |
|
||||
| ENHANCED_TELEMETRY_BETA | 2 | — |
|
||||
| COWORKER_TYPE_TELEMETRY | 2 | — |
|
||||
| BREAK_CACHE_COMMAND | 2 | — |
|
||||
| AWAY_SUMMARY | 2 | — |
|
||||
| AUTO_THEME | 2 | — |
|
||||
| ALLOW_TEST_VERSIONS | 2 | — |
|
||||
| AGENT_TRIGGERS_REMOTE | 2 | — |
|
||||
| AGENT_MEMORY_SNAPSHOT | 2 | — |
|
||||
| UNATTENDED_RETRY | 1 | — |
|
||||
| ULTRATHINK | 1 | — |
|
||||
| TORCH | 1 | — |
|
||||
| STREAMLINED_OUTPUT | 1 | — |
|
||||
| SLOW_OPERATION_LOGGING | 1 | — |
|
||||
| SKILL_IMPROVEMENT | 1 | — |
|
||||
| SELF_HOSTED_RUNNER | 1 | — |
|
||||
| RUN_SKILL_GENERATOR | 1 | — |
|
||||
| PERFETTO_TRACING | 1 | — |
|
||||
| NATIVE_CLIENT_ATTESTATION | 1 | — |
|
||||
| KAIROS_DREAM | 1 | 1 |
|
||||
| IS_LIBC_MUSL | 1 | — |
|
||||
| IS_LIBC_GLIBC | 1 | — |
|
||||
| HOOK_PROMPTS | 1 | — |
|
||||
| DUMP_SYSTEM_PROMPT | 1 | — |
|
||||
| COMPACTION_REMINDERS | 1 | — |
|
||||
| CCR_REMOTE_SETUP | 1 | — |
|
||||
| BYOC_ENVIRONMENT_RUNNER | 1 | — |
|
||||
| BUILTIN_EXPLORE_PLAN_AGENTS | 1 | — |
|
||||
| BUILDING_CLAUDE_APPS | 1 | — |
|
||||
| ANTI_DISTILLATION_CC | 1 | — |
|
||||
| AGENT_TRIGGERS | 1 | — |
|
||||
| ABLATION_BASELINE | 1 | — |
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,182 +0,0 @@
|
||||
# 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 机制。
|
||||
@@ -1,107 +0,0 @@
|
||||
# BASH_CLASSIFIER — Bash 命令分类器
|
||||
|
||||
> Feature Flag: `FEATURE_BASH_CLASSIFIER=1`
|
||||
> 实现状态：bashClassifier.ts 全部 Stub，yoloClassifier.ts 完整实现可参考
|
||||
> 引用数：45
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
BASH_CLASSIFIER 使用 LLM 对 bash 命令进行意图分类（允许/拒绝/询问），实现自动权限决策。用户不需要逐个审批 bash 命令，分类器根据命令内容和上下文自动判断安全性。
|
||||
|
||||
### 核心特性
|
||||
|
||||
- **LLM 驱动分类**：使用 Opus 模型评估命令安全性
|
||||
- **两阶段分类**：快速阻止/允许 → 深度思考链
|
||||
- **自动审批**：分类器判定安全的命令自动通过
|
||||
- **UI 集成**：权限对话框显示分类器状态和审核选项
|
||||
|
||||
## 二、实现架构
|
||||
|
||||
### 2.1 模块状态
|
||||
|
||||
| 模块 | 文件 | 状态 | 说明 |
|
||||
|------|------|------|------|
|
||||
| Bash 分类器 | `src/utils/permissions/bashClassifier.ts` | **Stub** | 所有函数返回空操作。注释："ANT-ONLY" |
|
||||
| YOLO 分类器 | `src/utils/permissions/yoloClassifier.ts` | **完整** | 1496 行，两阶段 XML 分类器 |
|
||||
| 审批信号 | `src/utils/classifierApprovals.ts` | **完整** | Map + 信号管理分类器决策 |
|
||||
| 权限 UI | `src/components/permissions/BashPermissionRequest.tsx` | **布线** | 分类器状态显示、审核选项 |
|
||||
| 权限管道 | `src/hooks/toolPermission/handlers/*.ts` | **布线** | 分类器结果路由到决策 |
|
||||
| API beta 标头 | `src/services/api/withRetry.ts` | **布线** | 启用时发送 `bash_classifier` beta |
|
||||
|
||||
### 2.2 参考实现：yoloClassifier.ts
|
||||
|
||||
文件：`src/utils/permissions/yoloClassifier.ts`（1496 行）
|
||||
|
||||
这是已实现的完整分类器，可作为 bashClassifier.ts 的参考：
|
||||
|
||||
```
|
||||
两阶段分类：
|
||||
1. 快速阶段：构建对话记录 → 调用 sideQuery（Opus）→ 快速阻止/允许
|
||||
2. 深度阶段：思考链分析 → 最终决策
|
||||
```
|
||||
|
||||
特性：
|
||||
- 构建完整对话记录上下文
|
||||
- 调用安全系统提示的 sideQuery
|
||||
- GrowthBook 配置和指标
|
||||
- 错误处理和降级
|
||||
|
||||
### 2.3 分类器在权限管道中的位置
|
||||
|
||||
```
|
||||
bash 命令到达
|
||||
│
|
||||
▼
|
||||
bashPermissions.ts 权限检查
|
||||
│
|
||||
├── 传统规则匹配（字符串级别）
|
||||
│
|
||||
└── [BASH_CLASSIFIER] LLM 分类
|
||||
│
|
||||
├── allow → 自动通过
|
||||
├── deny → 自动拒绝
|
||||
└── ask → 显示权限对话框
|
||||
│
|
||||
├── 分类器自动审批标记
|
||||
└── 审核选项（用户可覆盖）
|
||||
```
|
||||
|
||||
## 三、需要补全的内容
|
||||
|
||||
| 函数 | 需要实现 | 说明 |
|
||||
|------|---------|------|
|
||||
| `classifyBashCommand()` | LLM 调用评估安全性 | 参考 yoloClassifier.ts 的两阶段模式 |
|
||||
| `isClassifierPermissionsEnabled()` | GrowthBook/配置检查 | 控制分类器是否激活 |
|
||||
| `getBashPromptDenyDescriptions()` | 返回基于提示的拒绝规则 | 权限设置描述 |
|
||||
| `getBashPromptAskDescriptions()` | 返回询问规则 | 需要用户确认的命令 |
|
||||
| `getBashPromptAllowDescriptions()` | 返回允许规则 | 自动通过的命令 |
|
||||
| `generateGenericDescription()` | LLM 生成命令描述 | 为权限对话框提供说明 |
|
||||
| `extractPromptDescription()` | 解析规则内容 | 从规则中提取描述 |
|
||||
|
||||
## 四、关键设计决策
|
||||
|
||||
1. **ANT-ONLY 标记**：bashClassifier.ts 标注为 "ANT-ONLY"，可能是 Anthropic 内部服务端分类器的客户端适配
|
||||
2. **两阶段分类**：快速阶段处理明确情况（减少延迟），深度阶段处理模糊情况
|
||||
3. **分类器结果可审核**：权限 UI 显示分类器决策，用户可覆盖
|
||||
4. **YOLO 分类器参考**：yoloClassifier.ts 提供完整的分类器实现模式，可直接参考
|
||||
|
||||
## 五、使用方式
|
||||
|
||||
```bash
|
||||
# 启用 feature
|
||||
FEATURE_BASH_CLASSIFIER=1 bun run dev
|
||||
|
||||
# 配合 TREE_SITTER_BASH 使用（AST + LLM 双重安全）
|
||||
FEATURE_BASH_CLASSIFIER=1 FEATURE_TREE_SITTER_BASH=1 bun run dev
|
||||
```
|
||||
|
||||
## 六、文件索引
|
||||
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
| `src/utils/permissions/bashClassifier.ts` | — | Bash 分类器（stub，ANT-ONLY） |
|
||||
| `src/utils/permissions/yoloClassifier.ts` | 1496 | YOLO 分类器（完整参考实现） |
|
||||
| `src/utils/classifierApprovals.ts` | — | 分类器审批信号管理 |
|
||||
| `src/components/permissions/BashPermissionRequest.tsx:261-469` | — | 分类器 UI |
|
||||
| `src/hooks/toolPermission/handlers/interactiveHandler.ts` | — | 交互式权限处理 |
|
||||
| `src/services/api/withRetry.ts:81` | — | API beta 标头 |
|
||||
@@ -1,158 +0,0 @@
|
||||
# BRIDGE_MODE — 远程控制
|
||||
|
||||
> Feature Flag: `FEATURE_BRIDGE_MODE=1`
|
||||
> 实现状态：完整可用（v1 + v2 实现）
|
||||
> 引用数：28
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
BRIDGE_MODE 将本地 CLI 注册为"bridge 环境"，可从 claude.ai 或其他控制面远程驱动。本地终端变为一个"执行者"，接受远程指令并执行。
|
||||
|
||||
### 核心特性
|
||||
|
||||
- **环境注册**：本地 CLI 向 Anthropic 服务器注册为可用的 bridge 环境
|
||||
- **工作轮询**：长轮询（long-poll）等待远程任务分配
|
||||
- **会话管理**：创建、恢复、归档远程会话
|
||||
- **权限透传**：远程权限请求发送到控制面，用户在 claude.ai 上批准/拒绝
|
||||
- **心跳保活**：定期发送 heartbeat 延长任务租约
|
||||
- **可信设备**：v2 支持可信设备令牌增强安全性
|
||||
|
||||
## 二、实现架构
|
||||
|
||||
### 2.1 版本演进
|
||||
|
||||
| 版本 | 实现 | 特点 |
|
||||
|------|------|------|
|
||||
| v1（env-based） | `src/bridge/replBridge.ts` | 基于环境变量的传统 bridge |
|
||||
| v2（env-less） | `src/bridge/remoteBridgeCore.ts` | 无需环境变量，更安全的 bridge |
|
||||
|
||||
### 2.2 API 协议
|
||||
|
||||
文件：`src/bridge/bridgeApi.ts`
|
||||
|
||||
Bridge API Client 提供 7 个核心操作：
|
||||
|
||||
| 操作 | HTTP | 说明 |
|
||||
|------|------|------|
|
||||
| `registerBridgeEnvironment` | POST `/v1/environments/bridge` | 注册本地环境，获取 `environment_id` + `environment_secret` |
|
||||
| `pollForWork` | GET `/v1/environments/{id}/work/poll` | 长轮询等待任务（10s 超时） |
|
||||
| `acknowledgeWork` | POST `/v1/environments/{id}/work/{workId}/ack` | 确认接收任务 |
|
||||
| `stopWork` | POST `/v1/environments/{id}/work/{workId}/stop` | 停止任务 |
|
||||
| `heartbeatWork` | POST `/v1/environments/{id}/work/{workId}/heartbeat` | 续约任务租约 |
|
||||
| `deregisterEnvironment` | DELETE `/v1/environments/bridge/{id}` | 注销环境 |
|
||||
| `archiveSession` | POST `/v1/sessions/{id}/archive` | 归档会话（409 = 已归档，幂等） |
|
||||
| `sendPermissionResponseEvent` | POST `/v1/sessions/{id}/events` | 发送权限审批结果 |
|
||||
| `reconnectSession` | POST `/v1/environments/{id}/bridge/reconnect` | 重连已存在的会话 |
|
||||
|
||||
### 2.3 认证流程
|
||||
|
||||
```
|
||||
注册: OAuth Bearer Token → 获取 environment_secret
|
||||
轮询: environment_secret 作为 Authorization
|
||||
├── 401 → 尝试 OAuth token 刷新（onAuth401）
|
||||
└── 刷新成功 → 重试一次
|
||||
```
|
||||
|
||||
**OAuth 刷新**：API client 内置 `withOAuthRetry` 机制。401 时调用 `handleOAuth401Error`（同 withRetry.ts 的 v1/messages 模式），刷新后重试一次。
|
||||
|
||||
### 2.4 安全设计
|
||||
|
||||
- **路径穿越防护**：`validateBridgeId()` 使用 `/^[a-zA-Z0-9_-]+$/` 白名单验证所有服务端 ID
|
||||
- **BridgeFatalError**：不可重试的错误（401/403/404/410）直接抛出，阻止重试循环
|
||||
- **可信设备令牌**：v2 通过 `X-Trusted-Device-Token` header 增强安全层级
|
||||
- **幂关注册**：支持 `reuseEnvironmentId` 实现会话恢复，避免重复创建环境
|
||||
|
||||
### 2.5 数据流
|
||||
|
||||
```
|
||||
claude.ai 用户选择远程环境
|
||||
│
|
||||
▼
|
||||
POST /v1/environments/bridge (注册)
|
||||
│
|
||||
◀── environment_id + environment_secret
|
||||
│
|
||||
▼
|
||||
GET .../work/poll (长轮询)
|
||||
│
|
||||
◀── WorkResponse { id, data: { type, sessionId } }
|
||||
│
|
||||
▼
|
||||
POST .../work/{id}/ack (确认)
|
||||
│
|
||||
▼
|
||||
sessionRunner 创建 REPL session
|
||||
│
|
||||
├── 权限请求 → sendPermissionResponseEvent
|
||||
├── 心跳 → heartbeatWork (续约)
|
||||
└── 任务完成 → 自动归档
|
||||
```
|
||||
|
||||
### 2.6 模块结构
|
||||
|
||||
| 模块 | 文件 | 职责 |
|
||||
|------|------|------|
|
||||
| API Client | `bridgeApi.ts` | HTTP 通信（注册/轮询/确认/心跳/注销） |
|
||||
| Session Runner | `sessionRunner.ts` | 创建/恢复 REPL 会话 |
|
||||
| Bridge Config | `bridgeConfig.ts` | 配置管理（machine name、max sessions 等） |
|
||||
| Transport | `replBridgeTransport.ts` | Bridge 传输层 |
|
||||
| Permission Callbacks | `bridgePermissionCallbacks.ts` | 权限请求处理 |
|
||||
| Pointer | `bridgePointer.ts` | 当前活跃 bridge 状态指针 |
|
||||
| Flush Gate | `flushGate.ts` | 刷新控制 |
|
||||
| JWT Utils | `jwtUtils.ts` | JWT 令牌工具 |
|
||||
| Trusted Device | `trustedDevice.ts` | 可信设备管理 |
|
||||
| Debug Utils | `debugUtils.ts` | 调试日志 |
|
||||
| Types | `types.ts` | 类型定义 |
|
||||
|
||||
## 三、关键设计决策
|
||||
|
||||
1. **长轮询而非 WebSocket**：`pollForWork` 使用 HTTP GET + 10s 超时。简单可靠，无需维护 WebSocket 连接
|
||||
2. **OAuth 刷新内嵌**：API client 自带 `withOAuthRetry`，无需外层重试逻辑
|
||||
3. **ETag 条件请求**：注册时支持 `reuseEnvironmentId` 实现幂等会话恢复
|
||||
4. **v1/v2 共存**：代码中同时存在两套实现，v2 是更安全的升级版
|
||||
5. **权限双向流动**：本地权限请求发送到 claude.ai，用户在 web 上审批
|
||||
|
||||
## 四、使用方式
|
||||
|
||||
```bash
|
||||
# 启用 bridge mode
|
||||
FEATURE_BRIDGE_MODE=1 bun run dev
|
||||
|
||||
# 从 claude.ai/code 远程连接
|
||||
# 在 web 界面选择已注册的环境
|
||||
|
||||
# 配合 DAEMON 使用（后台守护）
|
||||
FEATURE_BRIDGE_MODE=1 FEATURE_DAEMON=1 bun run dev
|
||||
```
|
||||
|
||||
## 五、外部依赖
|
||||
|
||||
| 依赖 | 说明 |
|
||||
|------|------|
|
||||
| Anthropic OAuth | claude.ai 订阅登录 |
|
||||
| GrowthBook | `tengu_ccr_bridge` 门控 |
|
||||
| Bridge API | `/v1/environments/bridge` 系列端点 |
|
||||
|
||||
## 六、文件索引
|
||||
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
| `src/bridge/bridgeApi.ts` | 540 | API Client（核心） |
|
||||
| `src/bridge/sessionRunner.ts` | — | 会话运行器 |
|
||||
| `src/bridge/bridgeConfig.ts` | — | 配置管理 |
|
||||
| `src/bridge/replBridgeTransport.ts` | — | 传输层 |
|
||||
| `src/bridge/bridgePermissionCallbacks.ts` | — | 权限回调 |
|
||||
| `src/bridge/bridgePointer.ts` | — | 状态指针 |
|
||||
| `src/bridge/flushGate.ts` | — | 刷新控制 |
|
||||
| `src/bridge/jwtUtils.ts` | — | JWT 工具 |
|
||||
| `src/bridge/trustedDevice.ts` | — | 可信设备 |
|
||||
| `src/bridge/remoteBridgeCore.ts` | — | v2 核心实现 |
|
||||
| `src/bridge/types.ts` | — | 类型定义 |
|
||||
| `src/bridge/debugUtils.ts` | — | 调试工具 |
|
||||
| `src/bridge/pollConfigDefaults.ts` | — | 轮询配置默认值 |
|
||||
| `src/bridge/bridgeUI.ts` | — | UI 组件 |
|
||||
| `src/bridge/codeSessionApi.ts` | — | 代码会话 API |
|
||||
| `src/bridge/peerSessions.ts` | — | 对等会话管理 |
|
||||
| `src/bridge/sessionIdCompat.ts` | — | Session ID 兼容层 |
|
||||
| `src/bridge/createSession.ts` | — | 会话创建 |
|
||||
| `src/bridge/replBridgeHandle.ts` | — | Bridge 句柄 |
|
||||
@@ -1,87 +0,0 @@
|
||||
---
|
||||
title: "Buddy 宠物系统"
|
||||
description: "Buddy 是 CLI 中的虚拟宠物伴侣，通过 /buddy 命令孵化、互动，会出现在输入框旁边陪伴你写代码。"
|
||||
keywords: ["buddy", "宠物", "companion", "伴侣", "虚拟宠物"]
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
Buddy 是 Claude Code 内置的虚拟宠物系统。在 REPL 中通过 `/buddy` 命令可以孵化一只随机生成的宠物伴侣，它会出现在输入框旁边，陪伴你的编码过程。
|
||||
|
||||
> Feature Flag: `FEATURE_BUDDY=1`
|
||||
|
||||
## 启用方式
|
||||
|
||||
```bash
|
||||
FEATURE_BUDDY=1 bun run dev
|
||||
```
|
||||
|
||||
孵化窗口：2026 年 4 月 1-7 日期间启动时，会在 REPL 顶部显示彩虹色的 `/buddy` 提示。4 月 7 日之后命令仍然可用，但不再自动提示。
|
||||
|
||||
## 命令
|
||||
|
||||
| 命令 | 说明 |
|
||||
|---|---|
|
||||
| `/buddy` | 查看当前宠物信息和属性 |
|
||||
| `/buddy hatch` | 孵化一只新宠物（首次使用） |
|
||||
| `/buddy rehatch` | 重新随机生成宠物（替换现有） |
|
||||
| `/buddy pet` | 撸宠物，触发爱心动画 |
|
||||
| `/buddy mute` | 静音宠物（隐藏） |
|
||||
| `/buddy unmute` | 取消静音 |
|
||||
|
||||
## 宠物属性
|
||||
|
||||
### 物种（18 种）
|
||||
|
||||
| | | | |
|
||||
|---|---|---|---|
|
||||
| Duck | Goose | Blob | Cat |
|
||||
| Dragon | Octopus | Owl | Penguin |
|
||||
| Turtle | Snail | Ghost | Axolotl |
|
||||
| Capybara | Cactus | Robot | Rabbit |
|
||||
| Mushroom | Chonk | | |
|
||||
|
||||
### 稀有度
|
||||
|
||||
| 稀有度 | 星级 | 权重 |
|
||||
|---|---|---|
|
||||
| Common | ★ | 60% |
|
||||
| Uncommon | ★★ | 25% |
|
||||
| Rare | ★★★ | 10% |
|
||||
| Epic | ★★★★ | 4% |
|
||||
| Legendary | ★★★★★ | 1% |
|
||||
|
||||
孵化时基于种子随机决定，存在极低概率出现 Shiny（闪光）变体。
|
||||
|
||||
### 属性值
|
||||
|
||||
每只宠物拥有 5 项属性（0-100）：
|
||||
|
||||
- **DEBUGGING** — 调试能力
|
||||
- **PATIENCE** — 耐心程度
|
||||
- **CHAOS** — 混乱指数
|
||||
- **WISDOM** — 智慧值
|
||||
- **SNARK** — 毒舌度
|
||||
|
||||
### 外观
|
||||
|
||||
每只宠物还有随机的外观配件：
|
||||
|
||||
- **眼睛**: `·` `✦` `×` `◉` `@` `°`
|
||||
- **帽子**: none, crown, tophat, propeller, halo, wizard, beanie, tinyduck
|
||||
|
||||
## 数据存储
|
||||
|
||||
宠物信息存储在 `~/.claude.json` 的 `companion` 字段中。宠物的外观属性（物种、稀有度、属性值等）基于用户 ID 的哈希确定性生成，不可通过编辑配置文件来篡改稀有度。
|
||||
|
||||
## 相关源码
|
||||
|
||||
| 文件 | 说明 |
|
||||
|---|---|
|
||||
| `src/commands/buddy/buddy.ts` | `/buddy` 命令处理 |
|
||||
| `src/buddy/companion.ts` | 宠物生成与加载 |
|
||||
| `src/buddy/types.ts` | 类型定义（物种、稀有度、属性） |
|
||||
| `src/buddy/sprites.ts` | 终端像素画渲染 |
|
||||
| `src/buddy/CompanionSprite.tsx` | React 组件（输入框旁显示） |
|
||||
| `src/buddy/useBuddyNotification.tsx` | 启动提示通知 |
|
||||
| `src/buddy/prompt.ts` | 宠物相关 prompt 模板 |
|
||||
@@ -1,137 +0,0 @@
|
||||
# Claude in Chrome — 用户操作指南
|
||||
|
||||
## 1. 功能简介
|
||||
|
||||
Claude in Chrome 让 Claude Code 直接控制你的 Chrome 浏览器。你可以用自然语言让 Claude 帮你：
|
||||
|
||||
- 打开网页、导航、前进后退
|
||||
- 填写表单、上传图片
|
||||
- 截图、录制 GIF
|
||||
- 读取页面内容（DOM、纯文本）
|
||||
- 执行 JavaScript
|
||||
- 监控网络请求和控制台日志
|
||||
- 管理标签页
|
||||
|
||||
## 2. 前置条件
|
||||
|
||||
| 条件 | 说明 |
|
||||
|------|------|
|
||||
| Claude Code 订阅 | 需要 Claude Pro、Max 或 Team 订阅，浏览器插件功能不向免费用户开放 |
|
||||
| Chrome 浏览器 | 需已安装 Google Chrome |
|
||||
| Claude in Chrome 扩展 | 从 Chrome Web Store 安装（`claude.ai/chrome`） |
|
||||
| Claude Code CLI | 已通过 `bun run dev` 或构建产物运行 |
|
||||
|
||||
## 3. 启用方式
|
||||
|
||||
### Dev 模式
|
||||
|
||||
```bash
|
||||
bun run dev -- --chrome
|
||||
```
|
||||
|
||||
启动后 Claude 会自动检测 Chrome 扩展是否已安装，并注册浏览器控制工具。
|
||||
|
||||
### 构建产物
|
||||
|
||||
```bash
|
||||
node dist/cli.js --chrome
|
||||
```
|
||||
|
||||
### 禁用
|
||||
|
||||
```bash
|
||||
bun run dev -- --no-chrome
|
||||
```
|
||||
|
||||
或在 REPL 中通过 `/chrome` 命令切换启用/禁用状态。
|
||||
|
||||
### 通过配置默认启用
|
||||
|
||||
在 Claude Code 设置中将 `claudeInChromeDefaultEnabled` 设为 `true`，以后启动无需加 `--chrome` 参数。
|
||||
|
||||
## 4. 使用流程
|
||||
|
||||
1. **启动 CLI** — 加 `--chrome` 参数启动 Claude Code
|
||||
2. **确认连接** — REPL 中输入 `/chrome`，查看扩展状态是否显示 "Installed / Connected"
|
||||
3. **开始对话** — 正常与 Claude 对话，当需要操作浏览器时直接说，例如：
|
||||
- "打开 https://example.com 并截图"
|
||||
- "在当前页面搜索关键词 xxx"
|
||||
- "填写登录表单，用户名 admin"
|
||||
- "帮我录制当前操作的 GIF"
|
||||
4. **权限审批** — 首次执行浏览器操作时，Claude 会请求你的确认
|
||||
5. **操作完成** — Claude 完成操作后会返回结果（截图、文本、执行结果等）
|
||||
|
||||
## 5. 可用操作
|
||||
|
||||
### 页面交互
|
||||
|
||||
| 操作 | 说明 |
|
||||
|------|------|
|
||||
| `navigate` | 导航到指定 URL，或前进/后退 |
|
||||
| `computer` | 鼠标点击、移动、拖拽、键盘输入、截图等（13 种 action） |
|
||||
| `form_input` | 填写表单字段 |
|
||||
| `upload_image` | 上传图片到文件输入框或拖拽区域 |
|
||||
| `javascript_tool` | 在页面上下文执行 JavaScript |
|
||||
|
||||
### 页面读取
|
||||
|
||||
| 操作 | 说明 |
|
||||
|------|------|
|
||||
| `read_page` | 获取页面可访问性树（DOM 结构） |
|
||||
| `get_page_text` | 提取页面纯文本内容 |
|
||||
| `find` | 用自然语言搜索页面元素 |
|
||||
|
||||
### 标签页管理
|
||||
|
||||
| 操作 | 说明 |
|
||||
|------|------|
|
||||
| `tabs_context_mcp` | 获取当前标签组信息 |
|
||||
| `tabs_create_mcp` | 创建新标签页 |
|
||||
|
||||
### 监控与调试
|
||||
|
||||
| 操作 | 说明 |
|
||||
|------|------|
|
||||
| `read_console_messages` | 读取浏览器控制台日志 |
|
||||
| `read_network_requests` | 读取网络请求记录 |
|
||||
|
||||
### 其他
|
||||
|
||||
| 操作 | 说明 |
|
||||
|------|------|
|
||||
| `resize_window` | 调整浏览器窗口尺寸 |
|
||||
| `gif_creator` | 录制 GIF 并导出 |
|
||||
| `shortcuts_list` | 列出可用快捷方式 |
|
||||
| `shortcuts_execute` | 执行快捷方式 |
|
||||
| `update_plan` | 向你提交操作计划供审批 |
|
||||
| `switch_browser` | 切换到其他 Chrome 浏览器（仅 Bridge 模式） |
|
||||
|
||||
## 6. 通信模式
|
||||
|
||||
Claude in Chrome 支持两种与浏览器通信的方式：
|
||||
|
||||
### 本地 Socket（默认）
|
||||
|
||||
Chrome 扩展通过 Native Messaging Host 与 CLI 建立 Unix socket 连接。适用于本地开发，无需额外配置。
|
||||
|
||||
### Bridge WebSocket
|
||||
|
||||
通过 Anthropic 的 bridge 服务中转，支持远程操控浏览器。需要 claude.ai OAuth 登录。
|
||||
|
||||
## 7. 常见问题
|
||||
|
||||
### 扩展显示未安装
|
||||
|
||||
确认已从 Chrome Web Store 安装 "Claude in Chrome" 扩展，安装后重启浏览器。
|
||||
|
||||
### 工具未出现在工具列表
|
||||
|
||||
检查启动时是否加了 `--chrome` 参数，或通过 `/chrome` 命令确认状态。
|
||||
|
||||
### 连接超时
|
||||
|
||||
确保 Chrome 浏览器正在运行且扩展已启用。Native Messaging Host 在扩展安装时自动注册，如果重装过扩展需要重启浏览器。
|
||||
|
||||
### 不使用 Chrome 功能时
|
||||
|
||||
不带 `--chrome` 参数正常启动即可，不会加载任何浏览器相关模块，不影响其他功能。
|
||||
@@ -1,325 +0,0 @@
|
||||
# Computer Use 架构修正方案 v2
|
||||
|
||||
更新时间：2026-04-04
|
||||
|
||||
## 1. 当前架构的问题
|
||||
|
||||
### 问题 A：平台代码混在错误的包里
|
||||
|
||||
`@ant/computer-use-swift` 是 macOS Swift 原生模块的包装器，但我们把 Windows（`backends/win32.ts`）和 Linux（`backends/linux.ts`）的截图/应用管理代码塞进了这个包。"swift" 在名字里就意味着 macOS，后期维护者无法区分。
|
||||
|
||||
`@ant/computer-use-input` 同样——原本是 macOS enigo Rust 模块，我们也往里面塞了 win32/linux 后端。
|
||||
|
||||
### 问题 B：输入方式不对
|
||||
|
||||
当前 Windows 后端（`packages/@ant/computer-use-input/src/backends/win32.ts`）使用 `SetCursorPos` + `SendInput` + `keybd_event`——这是**全局输入**：
|
||||
|
||||
- 鼠标真的会移动到屏幕上
|
||||
- 键盘真的打到当前前台窗口
|
||||
- **会影响用户当前的操作**
|
||||
|
||||
绑定窗口句柄后，应该用 `SendMessage`/`PostMessage` 向目标 HWND 发送消息：
|
||||
|
||||
- `WM_CHAR` — 发送字符，不移动光标
|
||||
- `WM_KEYDOWN`/`WM_KEYUP` — 发送按键
|
||||
- `WM_LBUTTONDOWN`/`WM_LBUTTONUP` — 发送鼠标点击（窗口客户区相对坐标）
|
||||
- `PrintWindow` — 截取窗口内容，不需要窗口在前台
|
||||
- **不抢焦点、不影响用户当前操作**
|
||||
|
||||
已验证：向记事本 `SendMessage(WM_CHAR)` 成功写入文字，记事本在后台，终端保持前台。
|
||||
|
||||
### 问题 C：截图是公共能力，不属于 swift
|
||||
|
||||
截图（screenshot）、显示器枚举（display）、应用管理（apps）是所有平台都需要的公共能力，不应该放在 `@ant/computer-use-swift`（macOS 专属包名）里。
|
||||
|
||||
## 2. 修正后的架构
|
||||
|
||||
### 2.1 分层原则
|
||||
|
||||
```
|
||||
packages/@ant/ ← macOS 原生模块包装器（不放其他平台代码）
|
||||
├── computer-use-input/ ← macOS: enigo .node 键鼠（仅 darwin）
|
||||
├── computer-use-swift/ ← macOS: Swift .node 截图/应用（仅 darwin）
|
||||
└── computer-use-mcp/ ← 跨平台: MCP server + 工具定义（不改）
|
||||
|
||||
src/utils/computerUse/
|
||||
├── platforms/ ← 新增: 跨平台抽象层
|
||||
│ ├── types.ts ← 公共接口: InputPlatform, ScreenshotPlatform, AppsPlatform, DisplayPlatform
|
||||
│ ├── index.ts ← 平台分发器: 按 process.platform 加载后端
|
||||
│ ├── darwin.ts ← macOS: 委托给 @ant/computer-use-{input,swift}
|
||||
│ ├── win32.ts ← Windows: SendMessage 输入 + PrintWindow 截图 + EnumWindows + UIA + OCR
|
||||
│ └── linux.ts ← Linux: xdotool + scrot + xrandr + wmctrl
|
||||
│
|
||||
├── win32/ ← Windows 专属增强能力（不在公共接口中）
|
||||
│ ├── windowCapture.ts ← PrintWindow 窗口绑定截图
|
||||
│ ├── windowEnum.ts ← EnumWindows 窗口枚举
|
||||
│ ├── windowMessage.ts ← SendMessage/PostMessage 无焦点输入（新增）
|
||||
│ ├── uiAutomation.ts ← IUIAutomation UI 元素操作
|
||||
│ └── ocr.ts ← Windows.Media.Ocr 文字识别
|
||||
│
|
||||
├── executor.ts ← 改: 通过 platforms/ 获取平台实现，不直接调 @ant 包
|
||||
├── swiftLoader.ts ← 改: 仅 darwin 使用
|
||||
├── inputLoader.ts ← 改: 仅 darwin 使用
|
||||
└── ...其他文件不动
|
||||
```
|
||||
|
||||
### 2.2 公共接口（`platforms/types.ts`）
|
||||
|
||||
```typescript
|
||||
/** 窗口标识 — 跨平台 */
|
||||
export interface WindowHandle {
|
||||
id: string // macOS: bundleId, Windows: HWND string, Linux: window ID
|
||||
pid: number
|
||||
title: string
|
||||
exePath?: string // Windows/Linux: 进程路径
|
||||
}
|
||||
|
||||
/** 输入平台接口 — 两种模式 */
|
||||
export interface InputPlatform {
|
||||
// 模式 A: 全局输入（macOS/Linux 默认，向前台窗口发送）
|
||||
moveMouse(x: number, y: number): Promise<void>
|
||||
click(x: number, y: number, button: 'left' | 'right' | 'middle'): Promise<void>
|
||||
typeText(text: string): Promise<void>
|
||||
key(name: string, action: 'press' | 'release'): Promise<void>
|
||||
keys(combo: string[]): Promise<void>
|
||||
scroll(amount: number, direction: 'vertical' | 'horizontal'): Promise<void>
|
||||
mouseLocation(): Promise<{ x: number; y: number }>
|
||||
|
||||
// 模式 B: 窗口绑定输入（Windows SendMessage，不抢焦点）
|
||||
sendChar?(hwnd: string, char: string): Promise<void>
|
||||
sendKey?(hwnd: string, vk: number, action: 'down' | 'up'): Promise<void>
|
||||
sendClick?(hwnd: string, x: number, y: number, button: 'left' | 'right'): Promise<void>
|
||||
sendText?(hwnd: string, text: string): Promise<void>
|
||||
}
|
||||
|
||||
/** 截图平台接口 */
|
||||
export interface ScreenshotPlatform {
|
||||
// 全屏截图
|
||||
captureScreen(displayId?: number): Promise<ScreenshotResult>
|
||||
// 区域截图
|
||||
captureRegion(x: number, y: number, w: number, h: number): Promise<ScreenshotResult>
|
||||
// 窗口截图（Windows: PrintWindow，macOS: SCContentFilter，Linux: xdotool+import）
|
||||
captureWindow?(hwnd: string): Promise<ScreenshotResult | null>
|
||||
}
|
||||
|
||||
/** 显示器平台接口 */
|
||||
export interface DisplayPlatform {
|
||||
listAll(): DisplayInfo[]
|
||||
getSize(displayId?: number): DisplayInfo
|
||||
}
|
||||
|
||||
/** 应用管理平台接口 */
|
||||
export interface AppsPlatform {
|
||||
listRunning(): WindowHandle[]
|
||||
listInstalled(): Promise<InstalledApp[]>
|
||||
open(name: string): Promise<void>
|
||||
getFrontmostApp(): FrontmostAppInfo | null
|
||||
findWindowByTitle(title: string): WindowHandle | null
|
||||
}
|
||||
|
||||
export interface ScreenshotResult {
|
||||
base64: string
|
||||
width: number
|
||||
height: number
|
||||
}
|
||||
|
||||
export interface DisplayInfo {
|
||||
width: number
|
||||
height: number
|
||||
scaleFactor: number
|
||||
displayId: number
|
||||
}
|
||||
|
||||
export interface InstalledApp {
|
||||
id: string // macOS: bundleId, Windows: exe path, Linux: .desktop name
|
||||
displayName: string
|
||||
path: string
|
||||
}
|
||||
|
||||
export interface FrontmostAppInfo {
|
||||
id: string
|
||||
appName: string
|
||||
}
|
||||
```
|
||||
|
||||
### 2.3 平台分发器（`platforms/index.ts`）
|
||||
|
||||
```typescript
|
||||
import type { InputPlatform, ScreenshotPlatform, DisplayPlatform, AppsPlatform } from './types.js'
|
||||
|
||||
export interface Platform {
|
||||
input: InputPlatform
|
||||
screenshot: ScreenshotPlatform
|
||||
display: DisplayPlatform
|
||||
apps: AppsPlatform
|
||||
}
|
||||
|
||||
export function loadPlatform(): Platform {
|
||||
switch (process.platform) {
|
||||
case 'darwin':
|
||||
return require('./darwin.js').platform
|
||||
case 'win32':
|
||||
return require('./win32.js').platform
|
||||
case 'linux':
|
||||
return require('./linux.js').platform
|
||||
default:
|
||||
throw new Error(`Computer Use not supported on ${process.platform}`)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2.4 各平台实现
|
||||
|
||||
**`platforms/darwin.ts`** — 委托给 @ant 包（保持兼容）：
|
||||
```typescript
|
||||
// macOS: 通过 @ant/computer-use-input 和 @ant/computer-use-swift
|
||||
// 这两个包的 darwin 后端保留不动
|
||||
import { requireComputerUseInput } from '../inputLoader.js'
|
||||
import { requireComputerUseSwift } from '../swiftLoader.js'
|
||||
|
||||
export const platform = {
|
||||
input: { /* 委托给 requireComputerUseInput() */ },
|
||||
screenshot: { /* 委托给 requireComputerUseSwift().screenshot */ },
|
||||
display: { /* 委托给 requireComputerUseSwift().display */ },
|
||||
apps: { /* 委托给 requireComputerUseSwift().apps */ },
|
||||
}
|
||||
```
|
||||
|
||||
**`platforms/win32.ts`** — 使用 `src/utils/computerUse/win32/` 模块：
|
||||
```typescript
|
||||
// Windows: SendMessage 输入 + PrintWindow 截图 + EnumWindows 应用
|
||||
import { sendChar, sendKey, sendClick, sendText } from '../win32/windowMessage.js'
|
||||
import { captureWindow } from '../win32/windowCapture.js'
|
||||
import { listWindows } from '../win32/windowEnum.js'
|
||||
// ... PowerShell P/Invoke 全局输入作为 fallback
|
||||
|
||||
export const platform = {
|
||||
input: {
|
||||
// 全局模式: PowerShell SetCursorPos/SendInput（fallback）
|
||||
// 窗口模式: SendMessage（首选）
|
||||
sendChar, sendKey, sendClick, sendText, // 窗口绑定
|
||||
moveMouse, click, typeText, ... // 全局 fallback
|
||||
},
|
||||
screenshot: {
|
||||
captureScreen, // CopyFromScreen
|
||||
captureRegion, // CopyFromScreen(rect)
|
||||
captureWindow, // PrintWindow（不抢焦点）
|
||||
},
|
||||
display: { /* Screen.AllScreens */ },
|
||||
apps: { /* EnumWindows */ },
|
||||
}
|
||||
```
|
||||
|
||||
**`platforms/linux.ts`** — 使用 xdotool/scrot：
|
||||
```typescript
|
||||
// Linux: xdotool + scrot + xrandr + wmctrl
|
||||
export const platform = {
|
||||
input: { /* xdotool mousemove/click/key/type */ },
|
||||
screenshot: { /* scrot */ },
|
||||
display: { /* xrandr */ },
|
||||
apps: { /* wmctrl + ps */ },
|
||||
}
|
||||
```
|
||||
|
||||
### 2.5 executor.ts 改造
|
||||
|
||||
```typescript
|
||||
// 之前: 直接调 requireComputerUseSwift() 和 requireComputerUseInput()
|
||||
// 之后: 通过 platforms/ 统一获取
|
||||
|
||||
import { loadPlatform } from './platforms/index.js'
|
||||
|
||||
const platform = loadPlatform()
|
||||
|
||||
// 截图
|
||||
platform.screenshot.captureScreen()
|
||||
platform.screenshot.captureWindow(hwnd) // 窗口绑定
|
||||
|
||||
// 输入（窗口绑定模式，不抢焦点）
|
||||
platform.input.sendText?.(hwnd, 'Hello')
|
||||
platform.input.sendClick?.(hwnd, 100, 200, 'left')
|
||||
|
||||
// 输入（全局模式，fallback）
|
||||
platform.input.moveMouse(500, 500)
|
||||
platform.input.click(500, 500, 'left')
|
||||
```
|
||||
|
||||
## 3. Windows 输入模式对比
|
||||
|
||||
| 方式 | API | 抢焦点 | 移鼠标 | 窗口可最小化 | 适用场景 |
|
||||
|------|-----|--------|--------|-------------|---------|
|
||||
| **全局输入** | `SetCursorPos` + `SendInput` | ✅ 抢 | ✅ 动 | ❌ 不行 | 需要坐标点击（fallback） |
|
||||
| **窗口消息** | `SendMessage(WM_CHAR/WM_KEYDOWN)` | ❌ 不抢 | ❌ 不动 | ✅ 可以 | 打字、按键（首选） |
|
||||
| **窗口消息** | `SendMessage(WM_LBUTTONDOWN)` | ❌ 不抢 | ❌ 不动 | ⚠️ 部分 | 窗口内点击 |
|
||||
| **窗口截图** | `PrintWindow(hwnd, PW_RENDERFULLCONTENT)` | ❌ 不抢 | ❌ 不动 | ✅ 可以 | 窗口截图 |
|
||||
| **UI 操作** | `UIAutomation InvokePattern` | ❌ 不抢 | ❌ 不动 | ✅ 可以 | 按钮点击、文本写入 |
|
||||
|
||||
**策略**：优先用窗口消息 + UIAutomation（不干扰用户），全局输入作为 fallback。
|
||||
|
||||
## 4. 需要新增的文件
|
||||
|
||||
| 文件 | 说明 |
|
||||
|------|------|
|
||||
| `src/utils/computerUse/platforms/types.ts` | 公共接口定义 |
|
||||
| `src/utils/computerUse/platforms/index.ts` | 平台分发器 |
|
||||
| `src/utils/computerUse/platforms/darwin.ts` | macOS: 委托给 @ant 包 |
|
||||
| `src/utils/computerUse/platforms/win32.ts` | Windows: 组合 win32/ 下各模块 |
|
||||
| `src/utils/computerUse/platforms/linux.ts` | Linux: xdotool/scrot |
|
||||
| `src/utils/computerUse/win32/windowMessage.ts` | **新增**: SendMessage 无焦点输入 |
|
||||
|
||||
## 5. 需要移除/清理的文件
|
||||
|
||||
| 文件 | 操作 | 原因 |
|
||||
|------|------|------|
|
||||
| `packages/@ant/computer-use-input/src/backends/win32.ts` | 删除 | Windows 代码不应在 macOS 包里 |
|
||||
| `packages/@ant/computer-use-input/src/backends/linux.ts` | 删除 | Linux 代码不应在 macOS 包里 |
|
||||
| `packages/@ant/computer-use-swift/src/backends/win32.ts` | 删除 | 同上 |
|
||||
| `packages/@ant/computer-use-swift/src/backends/linux.ts` | 删除 | 同上 |
|
||||
| `packages/@ant/computer-use-input/src/types.ts` | 删除 | 移到 platforms/types.ts |
|
||||
| `packages/@ant/computer-use-swift/src/types.ts` | 删除 | 移到 platforms/types.ts |
|
||||
|
||||
## 6. 需要修改的文件
|
||||
|
||||
| 文件 | 改动 |
|
||||
|------|------|
|
||||
| `packages/@ant/computer-use-input/src/index.ts` | 恢复为仅 darwin dispatcher（去掉 win32/linux case） |
|
||||
| `packages/@ant/computer-use-swift/src/index.ts` | 恢复为仅 darwin dispatcher（去掉 win32/linux case） |
|
||||
| `src/utils/computerUse/executor.ts` | 通过 `platforms/` 获取平台实现，不直接调 @ant 包 |
|
||||
| `src/utils/computerUse/swiftLoader.ts` | 仅 darwin 加载 |
|
||||
| `src/utils/computerUse/inputLoader.ts` | 仅 darwin 加载 |
|
||||
|
||||
## 7. @ant 包的定位（修正后）
|
||||
|
||||
| 包 | 职责 | 平台 |
|
||||
|---|------|------|
|
||||
| `@ant/computer-use-input` | macOS enigo 键鼠原生模块包装 | **仅 darwin** |
|
||||
| `@ant/computer-use-swift` | macOS Swift 截图/应用原生模块包装 | **仅 darwin** |
|
||||
| `@ant/computer-use-mcp` | MCP Server + 工具定义 + 调用路由 | **跨平台**（不含平台代码） |
|
||||
|
||||
Windows/Linux 的平台实现全部在 `src/utils/computerUse/platforms/` 和 `src/utils/computerUse/win32/` 中。
|
||||
|
||||
## 8. 执行顺序
|
||||
|
||||
```
|
||||
Phase 1: 创建 platforms/ 抽象层
|
||||
├── platforms/types.ts（公共接口）
|
||||
├── platforms/index.ts（分发器）
|
||||
└── platforms/darwin.ts（委托 @ant 包）
|
||||
|
||||
Phase 2: 创建 Windows 平台实现
|
||||
├── win32/windowMessage.ts（SendMessage 无焦点输入）
|
||||
└── platforms/win32.ts（组合 win32/ 各模块）
|
||||
|
||||
Phase 3: 创建 Linux 平台实现
|
||||
└── platforms/linux.ts（xdotool/scrot）
|
||||
|
||||
Phase 4: 改造 executor.ts
|
||||
└── 通过 platforms/ 获取实现，不直接调 @ant
|
||||
|
||||
Phase 5: 清理 @ant 包
|
||||
├── 删除 @ant/computer-use-input/src/backends/{win32,linux}.ts
|
||||
├── 删除 @ant/computer-use-swift/src/backends/{win32,linux}.ts
|
||||
└── 恢复 index.ts 为 darwin-only
|
||||
|
||||
Phase 6: 验证 + PR
|
||||
```
|
||||
@@ -1,277 +0,0 @@
|
||||
# Computer Use MCP 工具测试报告
|
||||
|
||||
> 测试日期: 2026-04-04
|
||||
> 测试环境: macOS Darwin 25.4.0, Cursor (IDE tier: click)
|
||||
> MCP Server: `@ant/computer-use-mcp`
|
||||
|
||||
## 工具总览
|
||||
|
||||
共 17 个工具（含 batch 复合操作），分为 5 大类：
|
||||
|
||||
| 类别 | 工具 | 数量 |
|
||||
|------|------|------|
|
||||
| 截图/显示 | `screenshot`, `switch_display`, `zoom` | 3 |
|
||||
| 鼠标操作 | `left_click`, `right_click`, `double_click`, `triple_click`, `middle_click`, `left_click_drag`, `mouse_move` | 7 |
|
||||
| 键盘操作 | `key`, `type`, `hold_key` | 3 |
|
||||
| 状态查询 | `cursor_position`, `request_access` | 2 |
|
||||
| 复合/辅助 | `computer_batch`, `wait` | 2 |
|
||||
|
||||
---
|
||||
|
||||
## 测试结果
|
||||
|
||||
### 1. 权限管理
|
||||
|
||||
#### `request_access` — 请求应用访问权限
|
||||
|
||||
| 项目 | 结果 |
|
||||
|------|------|
|
||||
| 状态 | ✅ 通过 |
|
||||
| 行为 | 弹出系统对话框请求用户授权，支持批量申请多个应用 |
|
||||
| 返回 | `{ granted: [...], denied: [...], tierGuidance: "..." }` |
|
||||
| 权限分级 | `click`（仅点击）, `full`（完整控制） |
|
||||
| 说明 | IDE 类应用（Cursor、VSCode、Terminal）默认授予 `click` tier，限制键盘输入和右键操作；系统应用（System Settings）授予 `full` tier |
|
||||
|
||||
#### 已授权应用
|
||||
|
||||
| 应用 | Tier | 能力 |
|
||||
|------|------|------|
|
||||
| Cursor | click | 可见 + 纯左键点击（无键盘输入、右键、修饰键点击、拖拽） |
|
||||
| Terminal | click | 同上 |
|
||||
| System Settings | full | 完整控制（键鼠、拖拽等） |
|
||||
| Finder | — | 已授权 |
|
||||
|
||||
---
|
||||
|
||||
### 2. 截图与显示
|
||||
|
||||
#### `screenshot` — 截取屏幕截图
|
||||
|
||||
| 项目 | 结果 |
|
||||
|------|------|
|
||||
| 状态 | ⚠️ 部分通过 |
|
||||
| 执行 | 工具成功执行，返回 `ok: true` |
|
||||
| 图片 | **未返回可视图片内容**（output 为空字符串） |
|
||||
| `save_to_disk` | 设置后仍无输出 |
|
||||
| 分析 | 可能原因：(1) macOS 屏幕录制权限未授予；(2) 当前前台应用未被过滤导致截图为空；(3) MCP 传输层未正确编码图片数据 |
|
||||
| 建议 | 检查 **系统设置 → 隐私与安全性 → 屏幕录制** 是否授权给运行 Claude Code 的应用 |
|
||||
|
||||
#### `switch_display` — 切换显示器
|
||||
|
||||
| 项目 | 结果 |
|
||||
|------|------|
|
||||
| 状态 | ✅ 通过 |
|
||||
| 行为 | 接受显示器名称或 `"auto"`（自动选择） |
|
||||
| 返回 | 确认消息 |
|
||||
|
||||
#### `zoom` — 区域放大截图
|
||||
|
||||
| 项目 | 结果 |
|
||||
|------|------|
|
||||
| 状态 | ⏭️ 跳过 |
|
||||
| 原因 | 依赖 `screenshot` 返回的图片坐标，截图未返回图片无法测试 |
|
||||
|
||||
---
|
||||
|
||||
### 3. 鼠标操作
|
||||
|
||||
> 以下测试在 Cursor 窗口上执行（tier: click）
|
||||
|
||||
#### `mouse_move` — 移动鼠标
|
||||
|
||||
| 项目 | 结果 |
|
||||
|------|------|
|
||||
| 状态 | ✅ 通过 |
|
||||
| 输入 | `coordinate: [500, 500]` |
|
||||
| 返回 | `"Moved."` |
|
||||
|
||||
#### `left_click` — 左键单击
|
||||
|
||||
| 项目 | 结果 |
|
||||
|------|------|
|
||||
| 状态 | ✅ 通过 |
|
||||
| 输入 | `coordinate: [500, 500]` |
|
||||
| 返回 | `"Clicked."` |
|
||||
|
||||
#### `double_click` — 双击
|
||||
|
||||
| 项目 | 结果 |
|
||||
|------|------|
|
||||
| 状态 | ✅ 通过 |
|
||||
| 输入 | `coordinate: [500, 500]` |
|
||||
| 返回 | `"Clicked."` |
|
||||
|
||||
#### `triple_click` — 三击
|
||||
|
||||
| 项目 | 结果 |
|
||||
|------|------|
|
||||
| 状态 | ✅ 通过 |
|
||||
| 输入 | `coordinate: [500, 500]` |
|
||||
| 返回 | `"Clicked."` |
|
||||
|
||||
#### `right_click` — 右键点击
|
||||
|
||||
| 项目 | 结果 |
|
||||
|------|------|
|
||||
| 状态 | ⚠️ 受 tier 限制 |
|
||||
| Cursor (click tier) | ❌ 被拒绝 — `"Code" is granted at tier "click" — right-click, middle-click, and clicks with modifier keys require tier "full"` |
|
||||
| Finder (full tier) | ✅ 通过 — 返回 `"Clicked."` |
|
||||
| 结论 | 功能正常，IDE 安全限制符合预期 |
|
||||
|
||||
#### `middle_click` — 中键点击
|
||||
|
||||
| 项目 | 结果 |
|
||||
|------|------|
|
||||
| 状态 | ⚠️ 受 tier 限制 |
|
||||
| Cursor (click tier) | ❌ 被拒绝 — 同 `right_click`，需要 full tier |
|
||||
| Finder (full tier) | ✅ 通过 — 返回 `"Clicked."` |
|
||||
| 结论 | 功能正常，IDE 安全限制符合预期 |
|
||||
|
||||
#### `left_click_drag` — 拖拽
|
||||
|
||||
| 项目 | 结果 |
|
||||
|------|------|
|
||||
| 状态 | ⚠️ 受 tier 限制 |
|
||||
| Cursor (click tier) | ❌ 被拒绝 — 拖拽被视为修饰键点击，需要 full tier |
|
||||
| Finder (full tier) | ✅ 通过 — 返回 `"Dragged."` |
|
||||
| 结论 | 功能正常，IDE 安全限制符合预期 |
|
||||
|
||||
#### `scroll` — 滚轮滚动
|
||||
|
||||
| 项目 | 结果 |
|
||||
|------|------|
|
||||
| 状态 | ✅ 通过 |
|
||||
| 输入 | `coordinate: [500, 500]`, `scroll_direction: "down"`, `scroll_amount: 3` |
|
||||
| 返回 | `"Scrolled."` |
|
||||
| 反向 | ✅ `scroll_direction: "up"` 也通过 |
|
||||
|
||||
---
|
||||
|
||||
### 4. 键盘操作
|
||||
|
||||
> 以下测试在 Cursor 窗口上执行（tier: click）— 所有键盘操作均被拒绝
|
||||
|
||||
#### `key` — 按键/快捷键
|
||||
|
||||
| 项目 | 结果 |
|
||||
|------|------|
|
||||
| 状态 | ⚠️ 受 tier 限制 |
|
||||
| Cursor (click tier) | ❌ 被拒绝 — IDE tier 限制键盘输入 |
|
||||
| Finder (full tier) | ✅ 通过 — `escape` 按键成功，返回 `"Key pressed."` |
|
||||
| 结论 | 功能正常，IDE 安全限制符合预期 |
|
||||
|
||||
#### `type` — 输入文本
|
||||
|
||||
| 项目 | 结果 |
|
||||
|------|------|
|
||||
| 状态 | ⚠️ 受 tier 限制 |
|
||||
| Cursor (click tier) | ❌ 被拒绝 — IDE tier 限制文本输入 |
|
||||
| Finder (full tier) | ✅ 通过 — 输入 `"hello"` 成功，返回 `"Typed 5 grapheme(s)."` |
|
||||
| 结论 | 功能正常，IDE 安全限制符合预期 |
|
||||
|
||||
#### `hold_key` — 按住按键
|
||||
|
||||
| 项目 | 结果 |
|
||||
|------|------|
|
||||
| 状态 | ⚠️ 受 tier 限制 |
|
||||
| Cursor (click tier) | ❌ 被拒绝 — IDE tier 限制键盘输入 |
|
||||
| Finder (full tier) | ✅ 通过 — 按住 `shift` 1 秒成功，返回 `"Key held."` |
|
||||
| 结论 | 功能正常，IDE 安全限制符合预期 |
|
||||
|
||||
---
|
||||
|
||||
### 5. 状态查询
|
||||
|
||||
#### `cursor_position` — 获取鼠标位置
|
||||
|
||||
| 项目 | 结果 |
|
||||
|------|------|
|
||||
| 状态 | ✅ 通过 |
|
||||
| 返回 | `{"x": null, "y": null, "coordinateSpace": "image_pixels"}` |
|
||||
| 说明 | 坐标为 null 是因为没有成功截图，无参考坐标系 |
|
||||
|
||||
---
|
||||
|
||||
### 6. 复合/辅助操作
|
||||
|
||||
#### `computer_batch` — 批量执行操作
|
||||
|
||||
| 项目 | 结果 |
|
||||
|------|------|
|
||||
| 状态 | ✅ 通过 |
|
||||
| 行为 | 按顺序执行操作列表，遇到失败则停止后续操作 |
|
||||
| 返回 | `{ completed: [...], failed: {...}, remaining: N }` |
|
||||
| 特点 | 单次 API 调用执行多个操作，减少往返延迟 |
|
||||
| 错误处理 | 失败的操作会中断后续操作，返回已完成和剩余数量 |
|
||||
|
||||
#### `wait` — 等待
|
||||
|
||||
| 项目 | 结果 |
|
||||
|------|------|
|
||||
| 状态 | ✅ 通过 |
|
||||
| 输入 | `duration: 1` (秒) |
|
||||
| 返回 | `"Waited 1s."` |
|
||||
| 最大值 | 100 秒 |
|
||||
|
||||
---
|
||||
|
||||
## 汇总统计
|
||||
|
||||
| 状态 | 数量 | 工具 |
|
||||
|------|------|------|
|
||||
| ✅ 通过 | 10 | `request_access`, `switch_display`, `mouse_move`, `left_click`, `double_click`, `triple_click`, `scroll`, `cursor_position`, `computer_batch`, `wait` |
|
||||
| ⚠️ 部分通过 | 7 | `screenshot`（执行成功但无图片返回）, `right_click`, `middle_click`, `left_click_drag`, `key`, `type`, `hold_key`（均在 full tier 应用上通过，IDE click tier 限制是预期行为） |
|
||||
| ❌ 被拒绝 | 0 | — |
|
||||
| ⏭️ 跳过 | 1 | `zoom`（依赖截图） |
|
||||
|
||||
---
|
||||
|
||||
## 已知问题
|
||||
|
||||
### P0: 截图无图片返回
|
||||
|
||||
`screenshot` 工具执行成功但未返回图片内容，导致：
|
||||
- 无法获取屏幕坐标参考
|
||||
- `cursor_position` 返回 null 坐标
|
||||
- `zoom` 无法使用
|
||||
- 所有点击操作只能盲点（无截图验证）
|
||||
|
||||
**可能原因**:
|
||||
1. macOS 屏幕录制权限未授予
|
||||
2. MCP 图片传输/编码问题
|
||||
3. 截图内容被安全过滤机制过滤
|
||||
|
||||
**建议排查**: 检查 `系统设置 → 隐私与安全性 → 屏幕录制` 权限。
|
||||
|
||||
### P1: IDE 应用键盘操作受限 — ✅ 已确认功能正常
|
||||
|
||||
IDE 类应用（Cursor、VSCode、Terminal）被限制在 `click` tier，无法执行：
|
||||
- 键盘输入（`key`, `type`, `hold_key`）
|
||||
- 右键/中键点击（`right_click`, `middle_click`）
|
||||
- 拖拽操作（`left_click_drag`）
|
||||
|
||||
这是安全设计，防止 AI 操控 IDE 终端。**在 full tier 应用（Finder、System Settings）上，以上 6 个操作均测试通过，功能完全正常。**
|
||||
|
||||
---
|
||||
|
||||
## 权限模型说明
|
||||
|
||||
Computer Use MCP 采用分级权限模型：
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ Tier: full │
|
||||
│ - 所有鼠标操作（左键、右键、中键、拖拽） │
|
||||
│ - 键盘输入（type, key, hold_key） │
|
||||
│ - 适用于: 系统应用、Finder 等 │
|
||||
├─────────────────────────────────────────┤
|
||||
│ Tier: click │
|
||||
│ - 仅纯左键点击 │
|
||||
│ - 滚轮滚动 │
|
||||
│ - 适用于: IDE、Terminal 等 │
|
||||
├─────────────────────────────────────────┤
|
||||
│ 未授权 │
|
||||
│ - 所有操作被拒绝 │
|
||||
│ - 需通过 request_access 申请 │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
@@ -1,496 +0,0 @@
|
||||
# Computer Use 工具参考文档
|
||||
|
||||
## 概览
|
||||
|
||||
Computer Use 提供 37 个工具，分为三类：
|
||||
|
||||
| 分类 | 平台 | 工具数 | 说明 |
|
||||
|------|------|--------|------|
|
||||
| 通用工具 | 全平台 | 24 | 官方 Computer Use 标准能力 |
|
||||
| Windows 专属工具 | Win32 | 10 | 绑定窗口模式下的增强能力 |
|
||||
| 教学工具 | 全平台 | 3 | 分步引导模式（需 teachMode 开启） |
|
||||
|
||||
---
|
||||
|
||||
## 一、通用工具（24 个）
|
||||
|
||||
全平台可用。未绑定窗口时，操作对象是整个屏幕。
|
||||
|
||||
### 权限与会话
|
||||
|
||||
| 工具 | 参数 | 说明 |
|
||||
|------|------|------|
|
||||
| `request_access` | `apps[]`, `reason`, `clipboardRead?`, `clipboardWrite?`, `systemKeyCombos?` | 请求操作应用的权限。所有其他工具的前置条件 |
|
||||
| `list_granted_applications` | — | 列出当前会话已授权的应用 |
|
||||
|
||||
### 截图与显示
|
||||
|
||||
| 工具 | 参数 | 说明 |
|
||||
|------|------|------|
|
||||
| `screenshot` | `save_to_disk?` | 截取当前屏幕。绑定窗口时截取绑定窗口（PrintWindow）。返回图片 + GUI 元素列表（Windows） |
|
||||
| `zoom` | `region: [x1,y1,x2,y2]` | 截取指定区域的高分辨率图片。坐标基于最近一次全屏截图 |
|
||||
| `switch_display` | `display` | 切换截图的目标显示器 |
|
||||
|
||||
### 鼠标操作
|
||||
|
||||
| 工具 | 参数 | 说明 |
|
||||
|------|------|------|
|
||||
| `left_click` | `coordinate: [x,y]`, `text?` (修饰键) | 左键点击。`text` 可传 "shift"/"ctrl"/"alt" 实现组合点击 |
|
||||
| `double_click` | `coordinate`, `text?` | 双击 |
|
||||
| `triple_click` | `coordinate`, `text?` | 三击（选整行） |
|
||||
| `right_click` | `coordinate`, `text?` | 右键点击 |
|
||||
| `middle_click` | `coordinate`, `text?` | 中键点击 |
|
||||
| `mouse_move` | `coordinate` | 移动鼠标（不点击） |
|
||||
| `left_click_drag` | `coordinate` (终点), `start_coordinate?` (起点) | 拖拽 |
|
||||
| `left_mouse_down` | — | 按下左键不松 |
|
||||
| `left_mouse_up` | — | 松开左键 |
|
||||
| `cursor_position` | — | 获取当前鼠标位置 |
|
||||
|
||||
### 键盘操作
|
||||
|
||||
| 工具 | 参数 | 说明 |
|
||||
|------|------|------|
|
||||
| `type` | `text` | 输入文字 |
|
||||
| `key` | `text` (如 "ctrl+s"), `repeat?` | 按键/组合键 |
|
||||
| `hold_key` | `text`, `duration` (秒) | 按住键指定时长 |
|
||||
|
||||
### 滚动
|
||||
|
||||
| 工具 | 参数 | 说明 |
|
||||
|------|------|------|
|
||||
| `scroll` | `coordinate`, `scroll_direction`, `scroll_amount` | 滚动。方向: up/down/left/right |
|
||||
|
||||
### 应用管理
|
||||
|
||||
| 工具 | 参数 | 说明 |
|
||||
|------|------|------|
|
||||
| `open_application` | `app` | 打开应用。Windows 上自动绑定窗口 |
|
||||
|
||||
### 剪贴板
|
||||
|
||||
| 工具 | 参数 | 说明 |
|
||||
|------|------|------|
|
||||
| `read_clipboard` | — | 读取剪贴板文字 |
|
||||
| `write_clipboard` | `text` | 写入剪贴板 |
|
||||
|
||||
### 其他
|
||||
|
||||
| 工具 | 参数 | 说明 |
|
||||
|------|------|------|
|
||||
| `wait` | `duration` (秒) | 等待 |
|
||||
| `computer_batch` | `actions[]` | 批量执行多个动作（减少 API 往返） |
|
||||
|
||||
---
|
||||
|
||||
## 二、Windows 专属工具（10 个）
|
||||
|
||||
仅 Windows 平台可见。核心能力：**绑定窗口后的独立操作——不抢占用户鼠标键盘**。
|
||||
|
||||
### 工作模式
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────┐
|
||||
│ 未绑定模式 │
|
||||
│ 使用通用工具 (left_click/type/key/scroll) │
|
||||
│ 操作对象：整个屏幕 │
|
||||
│ 输入方式：全局 SendInput（会移动真实鼠标） │
|
||||
└──────────────────────────────────────────────────┘
|
||||
│
|
||||
bind_window / open_application
|
||||
▼
|
||||
┌──────────────────────────────────────────────────┐
|
||||
│ 绑定窗口模式 │
|
||||
│ 使用 Win32 工具 (virtual_mouse/virtual_keyboard) │
|
||||
│ 操作对象：绑定的窗口 │
|
||||
│ 输入方式：SendMessageW（不动真实鼠标/键盘） │
|
||||
│ 可视化：DWM 绿色边框 + 虚拟光标 + 状态指示器 │
|
||||
└──────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 窗口绑定
|
||||
|
||||
| 工具 | 参数 | 说明 |
|
||||
|------|------|------|
|
||||
| `bind_window` | `action`: list/bind/unbind/status | 窗口绑定管理 |
|
||||
|
||||
**动作详情：**
|
||||
|
||||
| action | 参数 | 说明 |
|
||||
|--------|------|------|
|
||||
| `list` | — | 列出所有可见窗口（hwnd、pid、title） |
|
||||
| `bind` | `title?`, `hwnd?`, `pid?` | 绑定到指定窗口。设置 DWM 绿色边框 + 启动虚拟光标 + 启动状态指示器 + 短暂激活窗口确保可接收输入 |
|
||||
| `unbind` | — | 解除绑定，恢复全屏模式 |
|
||||
| `status` | — | 查看当前绑定状态（hwnd、title、pid、窗口矩形） |
|
||||
|
||||
### 窗口管理
|
||||
|
||||
| 工具 | 参数 | 说明 |
|
||||
|------|------|------|
|
||||
| `window_management` | `action`, `x?`, `y?`, `width?`, `height?` | 窗口操作（Win32 API，不走全局快捷键） |
|
||||
|
||||
**动作详情：**
|
||||
|
||||
| action | 说明 |
|
||||
|--------|------|
|
||||
| `minimize` | ShowWindow(SW_MINIMIZE) |
|
||||
| `maximize` | ShowWindow(SW_MAXIMIZE) |
|
||||
| `restore` | ShowWindow(SW_RESTORE) — 恢复最小化/最大化 |
|
||||
| `close` | SendMessage(WM_CLOSE) — 优雅关闭 |
|
||||
| `focus` | SetForegroundWindow + BringWindowToTop — 激活窗口 |
|
||||
| `move_offscreen` | SetWindowPos(-32000,-32000) — 移到屏幕外（仍可 SendMessage/PrintWindow） |
|
||||
| `move_resize` | SetWindowPos — 移动/缩放到指定位置和大小 |
|
||||
| `get_rect` | GetWindowRect — 获取当前位置和大小 |
|
||||
|
||||
### 虚拟鼠标
|
||||
|
||||
| 工具 | 参数 | 说明 |
|
||||
|------|------|------|
|
||||
| `virtual_mouse` | `action`, `coordinate: [x,y]`, `start_coordinate?` | 在绑定窗口内操作虚拟鼠标 |
|
||||
|
||||
**动作详情：**
|
||||
|
||||
| action | 说明 |
|
||||
|--------|------|
|
||||
| `click` | 左键点击。虚拟光标移动到坐标 + 闪烁动画 |
|
||||
| `double_click` | 双击 |
|
||||
| `right_click` | 右键点击 |
|
||||
| `move` | 移动虚拟光标（不点击） |
|
||||
| `drag` | 按住 → 移动 → 松开。需 `start_coordinate` 指定起点 |
|
||||
| `down` | 按下左键不松 |
|
||||
| `up` | 松开左键 |
|
||||
|
||||
**与通用鼠标工具的区别：**
|
||||
|
||||
| | 通用 (`left_click` 等) | `virtual_mouse` |
|
||||
|---|---|---|
|
||||
| 输入方式 | SendInput（全局） | SendMessageW（窗口级） |
|
||||
| 真实鼠标 | 会移动 | **不动** |
|
||||
| 用户干扰 | 有 | **无** |
|
||||
| 适用场景 | 未绑定时 | **绑定后** |
|
||||
|
||||
### 虚拟键盘
|
||||
|
||||
| 工具 | 参数 | 说明 |
|
||||
|------|------|------|
|
||||
| `virtual_keyboard` | `action`, `text`, `duration?`, `repeat?` | 在绑定窗口内操作虚拟键盘 |
|
||||
|
||||
**动作详情：**
|
||||
|
||||
| action | text 含义 | 说明 |
|
||||
|--------|----------|------|
|
||||
| `type` | 要输入的文字 | SendMessageW(WM_CHAR)，支持 Unicode 中文/emoji |
|
||||
| `combo` | 组合键 (如 "ctrl+s") | WM_KEYDOWN/UP 序列 |
|
||||
| `press` | 单个键名 | 按下不松（配合 release 使用） |
|
||||
| `release` | 单个键名 | 松开按键 |
|
||||
| `hold` | 键名或组合 | 按住指定秒数后松开 |
|
||||
|
||||
**与通用键盘工具的区别：**
|
||||
|
||||
| | 通用 (`type`/`key`) | `virtual_keyboard` |
|
||||
|---|---|---|
|
||||
| 输入方式 | SendInput（全局） | SendMessageW（窗口级） |
|
||||
| 物理键盘 | 会冲突 | **不冲突** |
|
||||
| 适用场景 | 未绑定时 | **绑定后** |
|
||||
|
||||
**注意：** SendMessageW 对 Windows Terminal (ConPTY) 等现代应用无效。这些应用需要使用通用工具 + 窗口激活方式操作。
|
||||
|
||||
### 鼠标滚轮
|
||||
|
||||
| 工具 | 参数 | 说明 |
|
||||
|------|------|------|
|
||||
| `mouse_wheel` | `coordinate: [x,y]`, `delta`, `direction?` | WM_MOUSEWHEEL 鼠标中键滚轮 |
|
||||
|
||||
**参数说明：**
|
||||
- `delta`: 正值=向上，负值=向下。每 1 单位 ≈ 3 行
|
||||
- `direction`: "vertical"（默认）或 "horizontal"
|
||||
- `coordinate`: 滚轮作用点——决定哪个面板/区域接收滚动
|
||||
|
||||
**与通用 `scroll` 的区别：**
|
||||
|
||||
| | `scroll` | `mouse_wheel` |
|
||||
|---|---|---|
|
||||
| 原理 | WM_VSCROLL/WM_HSCROLL | **WM_MOUSEWHEEL** |
|
||||
| Excel | ❌ | ✅ |
|
||||
| 浏览器 | ❌ | ✅ |
|
||||
| 代码编辑器 | ❌ | ✅ |
|
||||
|
||||
### 元素级操作
|
||||
|
||||
| 工具 | 参数 | 说明 |
|
||||
|------|------|------|
|
||||
| `click_element` | `name?`, `role?`, `automationId?` | 按无障碍名称/角色点击 GUI 元素 |
|
||||
| `type_into_element` | `name?`, `role?`, `automationId?`, `text` | 按名称向元素输入文字 |
|
||||
|
||||
**工作原理：**
|
||||
1. 通过 UI Automation 在绑定窗口中查找匹配元素
|
||||
2. `click_element`: 先尝试 InvokePattern（按钮/菜单），失败则 SendMessage 点击 BoundingRect 中心
|
||||
3. `type_into_element`: 先尝试 ValuePattern 直接设值，失败则点击聚焦 + WM_CHAR 输入
|
||||
|
||||
**适用场景：**
|
||||
- 截图中看到元素名称但坐标不精确时
|
||||
- Accessibility Snapshot 列出了元素的 name/automationId 时
|
||||
- 比坐标点击更可靠（不受窗口缩放/DPI 影响）
|
||||
|
||||
### 终端交互
|
||||
|
||||
| 工具 | 参数 | 说明 |
|
||||
|------|------|------|
|
||||
| `prompt_respond` | `response_type`, `arrow_direction?`, `arrow_count?`, `text?` | 处理终端 Yes/No/选择提示 |
|
||||
|
||||
**response_type 详情：**
|
||||
|
||||
| response_type | 操作 | 场景 |
|
||||
|---------------|------|------|
|
||||
| `yes` | 发送 'y' + Enter | npm "Continue? (y/n)" |
|
||||
| `no` | 发送 'n' + Enter | 拒绝确认 |
|
||||
| `enter` | 发送 Enter | 接受默认选项 |
|
||||
| `escape` | 发送 Escape | 取消操作 |
|
||||
| `select` | ↑/↓ 箭头 × N + Enter | inquirer 选择菜单 |
|
||||
| `type` | 输入文字 + Enter | 文本输入提示 |
|
||||
|
||||
### 状态指示器
|
||||
|
||||
| 工具 | 参数 | 说明 |
|
||||
|------|------|------|
|
||||
| `status_indicator` | `action`: show/hide/status, `message?` | 控制绑定窗口底部的浮动状态标签 |
|
||||
|
||||
---
|
||||
|
||||
## 三、教学工具（3 个）
|
||||
|
||||
需要 `teachMode` 开启。
|
||||
|
||||
| 工具 | 说明 |
|
||||
|------|------|
|
||||
| `request_teach_access` | 请求教学引导模式权限 |
|
||||
| `teach_step` | 显示一步引导提示，等用户点 Next |
|
||||
| `teach_batch` | 批量排队多步引导 |
|
||||
|
||||
---
|
||||
|
||||
## 操作流程
|
||||
|
||||
### 流程 1：全屏操作（未绑定）
|
||||
|
||||
```
|
||||
request_access(apps=["Notepad"])
|
||||
open_application(app="Notepad") ← 自动绑定窗口
|
||||
screenshot ← PrintWindow 截图 + GUI 元素列表
|
||||
left_click(coordinate=[500, 300]) ← 全局 SendInput
|
||||
type(text="hello world") ← 全局 SendInput
|
||||
key(text="ctrl+s") ← 全局 SendInput
|
||||
```
|
||||
|
||||
### 流程 2：绑定窗口操作（推荐，不干扰用户）
|
||||
|
||||
```
|
||||
request_access(apps=["Notepad"])
|
||||
bind_window(action="list") ← 列出所有窗口
|
||||
bind_window(action="bind", title="记事本") ← 绑定 + 绿色边框 + 虚拟光标
|
||||
screenshot ← PrintWindow 截取绑定窗口
|
||||
virtual_mouse(action="click", coordinate=[500, 300]) ← SendMessageW，不动真实鼠标
|
||||
virtual_keyboard(action="type", text="hello world") ← SendMessageW，不动物理键盘
|
||||
virtual_keyboard(action="combo", text="ctrl+s") ← 保存
|
||||
mouse_wheel(coordinate=[500, 400], delta=-5) ← 向下滚动
|
||||
bind_window(action="unbind") ← 解除绑定
|
||||
```
|
||||
|
||||
### 流程 3：按元素名称操作
|
||||
|
||||
```
|
||||
bind_window(action="bind", title="记事本")
|
||||
screenshot ← 返回截图 + GUI elements 列表
|
||||
click_element(name="保存", role="Button") ← UI Automation 查找并点击
|
||||
type_into_element(role="Edit", text="new content")
|
||||
```
|
||||
|
||||
### 流程 4：终端交互
|
||||
|
||||
```
|
||||
bind_window(action="bind", title="PowerShell")
|
||||
screenshot
|
||||
prompt_respond(response_type="yes") ← 回答 y + Enter
|
||||
prompt_respond(response_type="select", arrow_direction="down", arrow_count=2) ← 选第3项
|
||||
```
|
||||
|
||||
### 流程 5：Excel/浏览器滚动
|
||||
|
||||
```
|
||||
bind_window(action="bind", title="Excel")
|
||||
screenshot
|
||||
mouse_wheel(coordinate=[600, 400], delta=-10) ← 向下滚动 10 格
|
||||
mouse_wheel(coordinate=[600, 400], delta=5, direction="horizontal") ← 向右滚动
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 应用兼容性
|
||||
|
||||
| 应用类型 | SendMessageW (virtual_*) | 元素操作 (click_element) | 注意 |
|
||||
|---------|--------------------------|------------------------|------|
|
||||
| 传统 Win32 (记事本/写字板) | ✅ | ✅ | 完美支持 |
|
||||
| Office (Excel/Word) | ✅ (COM 自动化) | ✅ | 通过 COM API |
|
||||
| WPF 应用 | ✅ | ✅ | 标准 UIA 支持 |
|
||||
| Electron/Chrome | ⚠️ 部分 | ⚠️ 部分 | 内部渲染不走 Win32 消息 |
|
||||
| UWP/WinUI (Windows Terminal) | ❌ | ❌ | ConPTY 不接受 SendMessageW |
|
||||
| 浏览器网页内容 | ❌ | ❌ | 需要全局 SendInput |
|
||||
|
||||
**对于不支持 SendMessageW 的应用**，使用通用工具 (`left_click`/`type`/`key`) + `window_management(action="focus")` 先激活窗口。
|
||||
|
||||
---
|
||||
|
||||
## 绑定窗口时的可视化
|
||||
|
||||
绑定窗口后自动启动三层可视化：
|
||||
|
||||
1. **DWM 绿色边框** — 窗口自身的边框颜色变绿，零偏移
|
||||
2. **虚拟鼠标光标** — 红色箭头图标，跟随 virtual_mouse 操作移动，点击时闪烁
|
||||
3. **状态指示器** — 窗口底部浮动标签，显示当前操作（通过 status_indicator 控制）
|
||||
|
||||
---
|
||||
|
||||
## Accessibility Snapshot
|
||||
|
||||
每次 `screenshot` 时，如果窗口已绑定，会自动附带 GUI 元素列表：
|
||||
|
||||
```
|
||||
GUI elements in this window:
|
||||
[Button] "Save" (120,50 80x30) enabled
|
||||
[Edit] "" (200,80 400x25) enabled value="hello" id=textBox1
|
||||
[MenuItem] "File" (10,0 40x25) enabled
|
||||
[MenuItem] "Edit" (50,0 40x25) enabled
|
||||
[CheckBox] "Auto-save" (300,50 100x20) enabled id=chkAutoSave
|
||||
```
|
||||
|
||||
模型同时收到 **截图图片 + 结构化元素列表**，可以选择：
|
||||
- 用坐标操作：`virtual_mouse(action="click", coordinate=[120, 50])`
|
||||
- 用名称操作：`click_element(name="Save")`
|
||||
|
||||
---
|
||||
|
||||
## UI Automation Control Patterns 参考
|
||||
|
||||
`click_element` / `type_into_element` 底层使用 UI Automation Control Patterns。当前已实现的和可扩展的：
|
||||
|
||||
| Pattern | 用途 | 当前状态 | 可用于 |
|
||||
|---------|------|---------|--------|
|
||||
| `InvokePattern` | 触发点击 | ✅ 已实现 (`click_element`) | 按钮、菜单项、链接 |
|
||||
| `ValuePattern` | 读写文本值 | ✅ 已实现 (`type_into_element`) | 文本框、组合框 |
|
||||
| `TogglePattern` | 切换状态 | ❌ 未实现 | 复选框、开关 |
|
||||
| `SelectionPattern` | 选择项目 | ❌ 未实现 | 下拉菜单、列表 |
|
||||
| `ScrollPattern` | 编程滚动 | ❌ 未实现（用 `mouse_wheel` 替代） | 列表、树、面板 |
|
||||
| `ExpandCollapsePattern` | 展开/折叠 | ❌ 未实现 | 树节点、折叠面板 |
|
||||
| `WindowPattern` | 窗口操作 | ❌ 未实现（用 `window_management` 替代） | 窗口最大化/关闭 |
|
||||
| `TextPattern` | 读取文档文本 | ❌ 未实现 | 文档、富文本 |
|
||||
| `GridPattern` | 表格操作 | ❌ 未实现 | Excel 单元格、数据网格 |
|
||||
| `TablePattern` | 表格结构 | ❌ 未实现 | 表头、行列关系 |
|
||||
| `RangeValuePattern` | 范围值操作 | ❌ 未实现 | 滑块、进度条 |
|
||||
| `TransformPattern` | 移动/缩放 | ❌ 未实现 | 可拖拽元素 |
|
||||
|
||||
**扩展路线：** 优先实现 `TogglePattern`（复选框）和 `SelectionPattern`（下拉菜单），这两个在表单自动化中最常用。
|
||||
|
||||
---
|
||||
|
||||
## 屏幕截取技术方案对比
|
||||
|
||||
当前使用 Python Bridge (mss) 进行截图，底层是 GDI BitBlt。三种方案对比：
|
||||
|
||||
| 方案 | API | 当前状态 | 性能 | 优势 | 限制 |
|
||||
|------|-----|---------|------|------|------|
|
||||
| **GDI BitBlt** | `BitBlt` / `PrintWindow` | ✅ 当前使用 (mss/bridge.py) | ~300ms | 简单稳定，支持后台窗口 (PrintWindow) | 不支持硬件加速内容、DPI 处理复杂 |
|
||||
| **DXGI Desktop Duplication** | `IDXGIOutputDuplication` | ❌ 未实现 | ~16ms (60fps) | 硬件加速，支持 HDR，GPU 直接读取 | 不支持单窗口截取，需 D3D11 |
|
||||
| **Windows.Graphics.Capture** | `GraphicsCaptureItem` | ❌ 未实现 | ~16ms | 最新 API，支持单窗口/单显示器，系统级权限管理 | Win10 1903+，首次需用户确认 |
|
||||
|
||||
### 推荐升级路径
|
||||
|
||||
```
|
||||
当前: GDI BitBlt (mss) ─── 全屏 ~300ms, 窗口 ~300ms (PrintWindow)
|
||||
│
|
||||
├─ 近期: DXGI Desktop Duplication ─── 全屏 ~16ms, 但不支持单窗口
|
||||
│
|
||||
└─ 远期: Windows.Graphics.Capture ─── 全屏 + 单窗口都 ~16ms
|
||||
```
|
||||
|
||||
### DXGI Desktop Duplication 实现要点
|
||||
|
||||
```python
|
||||
# bridge.py 中可添加 DXGI 截图（通过 d3dshot 或 dxcam 库）
|
||||
import dxcam # pip install dxcam
|
||||
|
||||
camera = dxcam.create()
|
||||
frame = camera.grab() # numpy array, ~5ms
|
||||
# 转为 JPEG base64 发送
|
||||
```
|
||||
|
||||
### Windows.Graphics.Capture 实现要点
|
||||
|
||||
```python
|
||||
# 需要 WinRT Python 绑定
|
||||
# pip install winrt-Windows.Graphics.Capture winrt-Windows.Graphics.DirectX
|
||||
# 限制：首次调用需要用户在系统弹窗中确认权限
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 输入方式技术矩阵
|
||||
|
||||
不同应用类型需要不同的输入方式：
|
||||
|
||||
| 输入方式 | API | 优势 | 限制 | 适用应用 |
|
||||
|---------|-----|------|------|---------|
|
||||
| **SendMessageW** | `WM_CHAR` / `WM_KEYDOWN` | 不抢焦点，不动真实键鼠 | 现代应用不支持 | Win32 传统应用 (记事本/Office/WPF) |
|
||||
| **SendInput** | `INPUT` 结构体 | 所有应用都支持 | **必须前台焦点**，会干扰用户 | 所有应用（通用后备） |
|
||||
| **WriteConsoleInput** | 控制台 API | 直接写入控制台缓冲区 | 需要 AttachConsole（可能被拒绝） | cmd/PowerShell（非 Windows Terminal） |
|
||||
| **UI Automation** | `InvokePattern` / `ValuePattern` | 语义级操作，最可靠 | 部分应用不暴露 UIA 接口 | 支持 UIA 的应用 |
|
||||
| **COM Automation** | Excel/Word COM | 完全编程控制 | 仅 Office 应用 | Excel / Word |
|
||||
| **剪贴板 + 粘贴** | `SetClipboardData` + `Ctrl+V` | 绕过输入限制 | 会覆盖用户剪贴板 | 通用后备 |
|
||||
|
||||
### 按应用类型的推荐输入策略
|
||||
|
||||
| 应用类型 | 首选 | 后备 | 说明 |
|
||||
|---------|------|------|------|
|
||||
| 传统 Win32 (记事本/写字板) | SendMessageW | UIA ValuePattern | 虚拟输入完美工作 |
|
||||
| Office (Excel/Word) | COM Automation | SendMessageW | COM 提供结构化操作 |
|
||||
| WPF 应用 | SendMessageW | UIA | 标准 Win32 消息循环 |
|
||||
| Electron/Chrome 应用 | UIA | 剪贴板粘贴 | 内部渲染不走 Win32 |
|
||||
| Windows Terminal (ConPTY) | SendInput (需前台) | 剪贴板粘贴 | ConPTY 不接受外部消息 |
|
||||
| UWP/WinUI 应用 | SendInput (需前台) | UIA | XAML 渲染不走 Win32 消息 |
|
||||
|
||||
---
|
||||
|
||||
## 已知限制与待解决
|
||||
|
||||
| 限制 | 影响 | 计划 |
|
||||
|------|------|------|
|
||||
| Windows Terminal 不接受 SendMessageW | 虚拟键盘/鼠标对终端无效 | 自动检测应用类型，终端类切换到 SendInput + 短暂激活 |
|
||||
| PrintWindow 截不到 alternate screen buffer | Ink REPL 画面截不到 | 切换到 Windows.Graphics.Capture |
|
||||
| Accessibility Snapshot 对大应用慢 (>30s) | Excel 等复杂应用超时 | 限制遍历深度 + 超时保护 |
|
||||
| DWM 边框对自定义标题栏应用可能无效 | 某些 Electron 应用看不到边框 | 检测并回退到叠加窗口方案 |
|
||||
| 虚拟光标是 PowerShell WinForms 进程 | 启动慢 (~1s)，资源占用 | 考虑用 Win32 原生窗口替代 |
|
||||
|
||||
---
|
||||
|
||||
## 技术路线图
|
||||
|
||||
### Phase 1（当前）— 基础功能
|
||||
- ✅ SendMessageW 虚拟输入
|
||||
- ✅ PrintWindow/mss 截图
|
||||
- ✅ UI Automation (InvokePattern + ValuePattern)
|
||||
- ✅ Accessibility Snapshot
|
||||
- ✅ DWM 边框指示
|
||||
- ✅ Python Bridge
|
||||
|
||||
### Phase 2（近期）— 兼容性增强
|
||||
- ⬜ 应用类型自动检测（Win32 vs Terminal vs UWP）
|
||||
- ⬜ 终端类应用自动切换 SendInput + 短暂激活
|
||||
- ⬜ TogglePattern / SelectionPattern 支持
|
||||
- ⬜ DXGI Desktop Duplication 高速截图
|
||||
- ⬜ Accessibility Snapshot 超时保护
|
||||
|
||||
### Phase 3（远期）— 高级能力
|
||||
- ⬜ Windows.Graphics.Capture（单窗口实时截图）
|
||||
- ⬜ 截图元素标注（在截图上标记 ID 数字）
|
||||
- ⬜ 浏览器 DOM 提取（绑定浏览器时提取网页结构）
|
||||
- ⬜ GridPattern / TablePattern（Excel 单元格级操作）
|
||||
- ⬜ TextPattern（文档内容读取）
|
||||
- ⬜ 多窗口协同操作
|
||||
@@ -1,315 +0,0 @@
|
||||
# Computer Use Windows 增强实施计划
|
||||
|
||||
更新时间：2026-04-03
|
||||
依赖文档：`docs/features/windows-ai-desktop-control.md`、`docs/features/computer-use.md`
|
||||
|
||||
## 1. 目标
|
||||
|
||||
在已有的 PowerShell 子进程方案基础上，利用 Windows 原生 API 增强 Computer Use 的 Windows 实现，解决 3 个核心问题：
|
||||
|
||||
1. **窗口绑定截图**：当前 `CopyFromScreen` 只能全屏截图，无法对指定窗口截图（尤其是被遮挡/最小化窗口）
|
||||
2. **UI 结构感知**：当前只能通过坐标点击，无法像 macOS Accessibility 那样理解 UI 元素树
|
||||
3. **性能**：每次 PowerShell 启动约 273ms，剪贴板/窗口枚举等高频操作需要更快的方式
|
||||
|
||||
## 2. 已验证的 Windows API 能力
|
||||
|
||||
以下 API 全部通过 PowerShell P/Invoke 实测通过：
|
||||
|
||||
| 能力 | API | 验证结果 |
|
||||
|------|-----|---------|
|
||||
| 窗口绑定截图 | `PrintWindow(hwnd, hdc, PW_RENDERFULLCONTENT)` | ✅ VS Code 342KB, Chrome 273KB |
|
||||
| 枚举窗口+HWND | `EnumWindows` + `GetWindowText` + `GetWindowThreadProcessId` | ✅ 38 个窗口，含 HWND/PID/标题 |
|
||||
| UI 元素树 | `System.Windows.Automation.AutomationElement` | ✅ 记事本 39 个元素 |
|
||||
| UI 写值 | `ValuePattern.SetValue()` | ✅ 成功写入记事本文本 |
|
||||
| UI 点击 | `InvokePattern.Invoke()` | ✅ 按钮可程序化点击 |
|
||||
| 坐标元素识别 | `AutomationElement.FromPoint(x, y)` | ✅ 返回元素类型+名称 |
|
||||
| OCR | `Windows.Media.Ocr.OcrEngine` | ✅ 英语+中文引擎可用 |
|
||||
| 全局热键 | `RegisterHotKey` | ✅ API 可调 |
|
||||
| 剪贴板直接操作 | `System.Windows.Forms.Clipboard` | ✅ 读/写/图片检测 |
|
||||
| Shell 启动 | `ShellExecute` | ✅ 打开文件/URL/应用 |
|
||||
|
||||
## 3. 架构设计
|
||||
|
||||
### 3.1 文件结构
|
||||
|
||||
在现有 `backends/win32.ts` 基础上新增 Windows 专属模块：
|
||||
|
||||
```
|
||||
packages/@ant/computer-use-input/src/
|
||||
├── backends/
|
||||
│ ├── darwin.ts ← 不动
|
||||
│ ├── win32.ts ← 增强：直接 Win32 API 替代部分 PowerShell
|
||||
│ └── linux.ts ← 不动
|
||||
|
||||
packages/@ant/computer-use-swift/src/
|
||||
├── backends/
|
||||
│ ├── darwin.ts ← 不动
|
||||
│ ├── win32.ts ← 增强：PrintWindow 窗口截图 + EnumWindows
|
||||
│ └── linux.ts ← 不动
|
||||
|
||||
packages/@ant/computer-use-mcp/src/
|
||||
│ └── tools.ts ← 增加 Windows 专属工具定义（UI Automation、OCR）
|
||||
|
||||
src/utils/computerUse/
|
||||
│ └── win32/ ← 新增目录：Windows 专属能力
|
||||
│ ├── uiAutomation.ts ← UI 元素树、点击、写值
|
||||
│ ├── ocr.ts ← 截图 + OCR 文字识别
|
||||
│ ├── windowCapture.ts ← PrintWindow 窗口绑定截图
|
||||
│ └── windowEnum.ts ← EnumWindows 窗口枚举
|
||||
```
|
||||
|
||||
### 3.2 分层
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────┐
|
||||
│ Computer Use MCP Tools │
|
||||
│ screenshot / click / type / request_access │
|
||||
│ + Windows 专属: ui_tree / ocr / window_cap │
|
||||
├──────────────────────────────────────────────┤
|
||||
│ src/utils/computerUse/ │
|
||||
│ executor.ts → 按平台 dispatch │
|
||||
│ win32/ → Windows 专属能力模块 │
|
||||
├──────────────────────────────────────────────┤
|
||||
│ packages/@ant/computer-use-{input,swift} │
|
||||
│ backends/win32.ts → PowerShell + Win32 API │
|
||||
├──────────────────────────────────────────────┤
|
||||
│ Windows Native API │
|
||||
│ PrintWindow / EnumWindows / UI Automation │
|
||||
│ SendInput / Clipboard / OCR / ShellExecute │
|
||||
└──────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## 4. 实施计划
|
||||
|
||||
### Phase A：窗口绑定截图（解决核心问题）
|
||||
|
||||
**问题**：当前 `CopyFromScreen` 只能全屏截图，无法对指定窗口截图。
|
||||
**方案**：用 `PrintWindow` + `FindWindow` 实现窗口级截图。
|
||||
|
||||
| 步骤 | 文件 | 改动 |
|
||||
|------|------|------|
|
||||
| A.1 | `src/utils/computerUse/win32/windowCapture.ts` | 新建：`captureWindow(title)` 用 PrintWindow 截取指定窗口 |
|
||||
| A.2 | `src/utils/computerUse/win32/windowEnum.ts` | 新建：`listWindows()` 用 EnumWindows 返回 {hwnd, pid, title}[] |
|
||||
| A.3 | `packages/@ant/computer-use-swift/src/backends/win32.ts` | `screenshot.captureExcluding` 增加按窗口截图能力 |
|
||||
| A.4 | `packages/@ant/computer-use-swift/src/backends/win32.ts` | `apps.listRunning` 用 EnumWindows 替代 Get-Process（返回 HWND） |
|
||||
|
||||
**PowerShell 脚本核心**：
|
||||
|
||||
```powershell
|
||||
# PrintWindow 截取指定窗口
|
||||
Add-Type -AssemblyName System.Drawing
|
||||
Add-Type -ReferencedAssemblies System.Drawing @'
|
||||
using System; using System.Runtime.InteropServices; using System.Drawing; using System.Drawing.Imaging;
|
||||
public class WinCap {
|
||||
[DllImport("user32.dll", CharSet=CharSet.Unicode)]
|
||||
public static extern IntPtr FindWindow(string c, string t);
|
||||
[DllImport("user32.dll")]
|
||||
public static extern bool GetWindowRect(IntPtr h, out RECT r);
|
||||
[DllImport("user32.dll")]
|
||||
public static extern bool PrintWindow(IntPtr h, IntPtr hdc, uint f);
|
||||
[StructLayout(LayoutKind.Sequential)]
|
||||
public struct RECT { public int L, T, R, B; }
|
||||
// ... CaptureByTitle(string title) → base64
|
||||
}
|
||||
'@
|
||||
```
|
||||
|
||||
**验证标准**：
|
||||
- 能按窗口标题截图
|
||||
- 被遮挡的窗口也能截图
|
||||
- 返回 base64 + width + height
|
||||
|
||||
### Phase B：UI Automation（Windows 专属新能力）
|
||||
|
||||
**问题**：macOS 有 Accessibility API 可以读取/操作 UI 元素，Windows 当前只能坐标点击。
|
||||
**方案**：用 `System.Windows.Automation` 实现 UI 树读取和元素操作。
|
||||
|
||||
| 步骤 | 文件 | 改动 |
|
||||
|------|------|------|
|
||||
| B.1 | `src/utils/computerUse/win32/uiAutomation.ts` | 新建：核心 UIA 操作封装 |
|
||||
| B.2 | `packages/@ant/computer-use-mcp/src/tools.ts` | 增加 Windows 专属工具定义 |
|
||||
|
||||
**uiAutomation.ts 导出函数**：
|
||||
|
||||
```typescript
|
||||
// 获取窗口的 UI 元素树
|
||||
getUITree(windowTitle: string, depth: number): UIElement[]
|
||||
|
||||
// 按名称/类型/AutomationId 查找元素
|
||||
findElement(windowTitle: string, query: {name?, controlType?, automationId?}): UIElement | null
|
||||
|
||||
// 点击元素（InvokePattern）
|
||||
clickElement(windowTitle: string, automationId: string): boolean
|
||||
|
||||
// 设置元素值（ValuePattern）
|
||||
setValue(windowTitle: string, automationId: string, value: string): boolean
|
||||
|
||||
// 获取坐标处的元素
|
||||
elementAtPoint(x: number, y: number): UIElement | null
|
||||
```
|
||||
|
||||
**UIElement 类型**：
|
||||
```typescript
|
||||
interface UIElement {
|
||||
name: string
|
||||
controlType: string // Button, Edit, Text, List, etc.
|
||||
automationId: string
|
||||
boundingRect: { x: number, y: number, w: number, h: number }
|
||||
isEnabled: boolean
|
||||
value?: string // ValuePattern 可用时
|
||||
children?: UIElement[]
|
||||
}
|
||||
```
|
||||
|
||||
**PowerShell 脚本核心**：
|
||||
```powershell
|
||||
Add-Type -AssemblyName UIAutomationClient
|
||||
Add-Type -AssemblyName UIAutomationTypes
|
||||
|
||||
# 读取 UI 树
|
||||
$root = [AutomationElement]::RootElement
|
||||
$window = $root.FindFirst([TreeScope]::Children,
|
||||
[PropertyCondition]::new([AutomationElement]::NameProperty, $title))
|
||||
$elements = $window.FindAll([TreeScope]::Descendants, [Condition]::TrueCondition)
|
||||
|
||||
# 写入文本
|
||||
$element.GetCurrentPattern([ValuePattern]::Pattern).SetValue($text)
|
||||
|
||||
# 点击按钮
|
||||
$element.GetCurrentPattern([InvokePattern]::Pattern).Invoke()
|
||||
```
|
||||
|
||||
**验证标准**：
|
||||
- 能读取记事本的 UI 树（按钮、文本框、菜单）
|
||||
- 能向文本框写入内容
|
||||
- 能点击按钮
|
||||
- 能识别坐标处的元素
|
||||
|
||||
### Phase C：OCR 屏幕文字识别
|
||||
|
||||
**问题**：截图后 AI 只能看到图片，无法直接读取文字。
|
||||
**方案**：用 `Windows.Media.Ocr` 对截图进行文字识别。
|
||||
|
||||
| 步骤 | 文件 | 改动 |
|
||||
|------|------|------|
|
||||
| C.1 | `src/utils/computerUse/win32/ocr.ts` | 新建：截图 + OCR 识别 |
|
||||
| C.2 | `packages/@ant/computer-use-mcp/src/tools.ts` | 增加 `screen_ocr` 工具定义 |
|
||||
|
||||
**ocr.ts 导出函数**：
|
||||
```typescript
|
||||
// 对屏幕区域 OCR
|
||||
ocrRegion(x: number, y: number, w: number, h: number, lang?: string): OcrResult
|
||||
|
||||
// 对指定窗口 OCR
|
||||
ocrWindow(windowTitle: string, lang?: string): OcrResult
|
||||
|
||||
interface OcrResult {
|
||||
text: string
|
||||
lines: { text: string, bounds: {x,y,w,h} }[]
|
||||
language: string
|
||||
}
|
||||
```
|
||||
|
||||
**已确认可用语言**：英语 (en-US) + 中文 (zh-Hans-CN)
|
||||
|
||||
**验证标准**：
|
||||
- 能识别屏幕区域中的英文和中文
|
||||
- 返回文字内容 + 每行的位置信息
|
||||
|
||||
### Phase D：高频操作性能优化
|
||||
|
||||
**问题**：每次 PowerShell 启动 273ms，鼠标移动等高频操作太慢。
|
||||
**方案**：用 .NET `System.Windows.Forms.Clipboard` 等直接 API 替代 PowerShell 子进程。
|
||||
|
||||
| 步骤 | 文件 | 改动 |
|
||||
|------|------|------|
|
||||
| D.1 | `src/utils/computerUse/executor.ts` | 剪贴板操作用直接 API 替代 PowerShell |
|
||||
| D.2 | 考虑驻留 PowerShell 进程 | 通过 stdin/stdout 交互，摊平启动成本 |
|
||||
|
||||
**剪贴板直接 API**（不需要 PowerShell 子进程）：
|
||||
```powershell
|
||||
# 读：50ms → <1ms
|
||||
[System.Windows.Forms.Clipboard]::GetText()
|
||||
|
||||
# 写：50ms → <1ms
|
||||
[System.Windows.Forms.Clipboard]::SetText($text)
|
||||
|
||||
# 图片检测
|
||||
[System.Windows.Forms.Clipboard]::ContainsImage()
|
||||
```
|
||||
|
||||
### Phase E：`request_access` Windows 适配
|
||||
|
||||
**问题**：`request_access` 依赖 macOS bundleId 识别应用，Windows 没有这个概念。
|
||||
**方案**：在 Windows 上用 exe 路径 + 窗口标题替代 bundleId。
|
||||
|
||||
| 步骤 | 文件 | 改动 |
|
||||
|------|------|------|
|
||||
| E.1 | `packages/@ant/computer-use-mcp/src/toolCalls.ts` | `resolveRequestedApps` 在 Windows 上用 exe 路径匹配 |
|
||||
| E.2 | `packages/@ant/computer-use-mcp/src/sentinelApps.ts` | 增加 Windows 危险应用列表（cmd.exe, powershell.exe 等） |
|
||||
| E.3 | `packages/@ant/computer-use-mcp/src/deniedApps.ts` | 增加 Windows 浏览器/终端识别规则 |
|
||||
| E.4 | `src/utils/computerUse/hostAdapter.ts` | `ensureOsPermissions` Windows 上检查 UAC 状态 |
|
||||
|
||||
**Windows 应用标识映射**：
|
||||
```
|
||||
macOS bundleId → Windows 等价
|
||||
com.apple.Safari → C:\Program Files\...\msedge.exe（或窗口标题匹配）
|
||||
com.google.Chrome → chrome.exe
|
||||
com.apple.Terminal → WindowsTerminal.exe / cmd.exe
|
||||
```
|
||||
|
||||
### Phase F：全局热键（ESC 拦截）
|
||||
|
||||
**问题**：当前非 darwin 直接跳过 ESC 热键，用 Ctrl+C 替代。
|
||||
**方案**：用 `RegisterHotKey` 或 `SetWindowsHookEx(WH_KEYBOARD_LL)` 实现。
|
||||
|
||||
| 步骤 | 文件 | 改动 |
|
||||
|------|------|------|
|
||||
| F.1 | `src/utils/computerUse/escHotkey.ts` | Windows 分支：RegisterHotKey 注册 ESC |
|
||||
|
||||
**优先级低**——当前 Ctrl+C fallback 可用，ESC 热键是体验优化。
|
||||
|
||||
## 5. 执行优先级
|
||||
|
||||
```
|
||||
Phase A: 窗口绑定截图 ← P0 核心需求，解决"操作其他界面"
|
||||
Phase B: UI Automation ← P0 核心能力，AI 理解 UI 结构
|
||||
Phase C: OCR ← P1 增值能力，AI 读屏幕文字
|
||||
Phase D: 性能优化 ← P1 体验优化，高频操作提速
|
||||
Phase E: request_access 适配 ← P1 功能完整性，权限模型适配
|
||||
Phase F: ESC 热键 ← P2 体验优化，可后做
|
||||
```
|
||||
|
||||
## 6. 每个 Phase 的改动量估算
|
||||
|
||||
| Phase | 新增文件 | 修改文件 | 新增代码行 | 风险 |
|
||||
|-------|---------|---------|-----------|------|
|
||||
| A 窗口截图 | 2 | 1 | ~200 | 低 |
|
||||
| B UI Automation | 1 | 1 | ~300 | 中 |
|
||||
| C OCR | 1 | 1 | ~150 | 低 |
|
||||
| D 性能优化 | 0 | 2 | ~50 | 低 |
|
||||
| E request_access | 0 | 3 | ~100 | 中 |
|
||||
| F ESC 热键 | 0 | 1 | ~50 | 低 |
|
||||
| **总计** | **4** | **9** | **~850** | — |
|
||||
|
||||
## 7. 不动的文件
|
||||
|
||||
- `backends/darwin.ts`（两个包都不动）
|
||||
- `backends/linux.ts`（两个包都不动）
|
||||
- `src/utils/computerUse/` 中 macOS 相关代码路径不动
|
||||
- `packages/@ant/computer-use-mcp/src/` 中已复制的参考项目代码不动（只追加 Windows 工具）
|
||||
|
||||
## 8. 与 macOS/Linux 方案的对比
|
||||
|
||||
| 能力 | macOS | Windows (增强后) | Linux |
|
||||
|------|-------|-----------------|-------|
|
||||
| 截图方式 | SCContentFilter (per-app) | **PrintWindow (per-window)** | scrot (全屏/区域) |
|
||||
| UI 结构 | Accessibility API | **UI Automation** | 无 |
|
||||
| OCR | 无内置 | **Windows.Media.Ocr** | 无内置 |
|
||||
| 键鼠 | CGEvent + enigo | SendInput + keybd_event | xdotool |
|
||||
| 窗口管理 | NSWorkspace | **EnumWindows + Win32** | wmctrl |
|
||||
| 剪贴板 | pbcopy/pbpaste | **Clipboard 直接 API** | xclip |
|
||||
| ESC 热键 | CGEventTap | RegisterHotKey | 无 |
|
||||
| 应用标识 | bundleId | exe 路径 + 窗口标题 | /proc + wmctrl |
|
||||
|
||||
**Windows 增强后将在 UI Automation 和 OCR 方面超过 macOS 方案**——这两项 macOS 原始实现也没有（Anthropic 用的是截图 + Claude 视觉理解，没有结构化 UI 数据）。
|
||||
@@ -1,197 +0,0 @@
|
||||
# Computer Use — macOS / Windows / Linux 跨平台实施计划
|
||||
|
||||
更新时间：2026-04-03
|
||||
参考项目：`E:\源码\claude-code-source-main\claude-code-source-main`
|
||||
|
||||
## 1. 现状
|
||||
|
||||
参考项目的 Computer Use **仅支持 macOS**——从入口到底层全部写死 darwin。我们的项目在 Phase 1-3 中已经完成了：
|
||||
|
||||
- ✅ `@ant/computer-use-mcp` stub 替换为完整实现（12 文件）
|
||||
- ✅ `@ant/computer-use-input` 拆为 dispatcher + backends（darwin + win32）
|
||||
- ✅ `@ant/computer-use-swift` 拆为 dispatcher + backends（darwin + win32）
|
||||
- ✅ `CHICAGO_MCP` 编译开关已开
|
||||
- ❌ `src/` 层有 6 处 macOS 硬编码阻塞
|
||||
|
||||
## 2. 阻塞点全景
|
||||
|
||||
### 2.1 入口层
|
||||
|
||||
| # | 文件:行号 | 阻塞代码 | 影响 |
|
||||
|---|----------|---------|------|
|
||||
| 1 | `src/main.tsx:1605` | `getPlatform() === 'macos'` | 整个 CU 初始化被跳过 |
|
||||
|
||||
### 2.2 加载层
|
||||
|
||||
| # | 文件:行号 | 阻塞代码 | 影响 |
|
||||
|---|----------|---------|------|
|
||||
| 2 | `src/utils/computerUse/swiftLoader.ts:16` | `process.platform !== 'darwin'` → throw | 截图、应用管理全部不可用 |
|
||||
| 3 | `src/utils/computerUse/executor.ts:263` | `process.platform !== 'darwin'` → throw | 整个 executor 工厂函数不可用 |
|
||||
|
||||
### 2.3 macOS 特有依赖
|
||||
|
||||
| # | 文件:行号 | 依赖 | macOS 实现 | 需要替代方案 |
|
||||
|---|----------|------|-----------|------------|
|
||||
| 4 | `executor.ts:70-88` | 剪贴板 | `pbcopy`/`pbpaste` | Win: PowerShell `Get/Set-Clipboard`；Linux: `xclip`/`wl-copy` |
|
||||
| 5 | `drainRunLoop.ts:21` | CFRunLoop pump | `cu._drainMainRunLoop()` | 非 darwin：直接执行 fn()，不需要 pump |
|
||||
| 6 | `escHotkey.ts:28` | ESC 热键 | CGEventTap | 非 darwin：返回 false（已有 Ctrl+C fallback） |
|
||||
| 7 | `hostAdapter.ts:48-54` | 系统权限 | TCC accessibility + screenRecording | Win：直接 granted；Linux：检查 xdotool |
|
||||
| 8 | `common.ts:56` | 平台标识 | `platform: 'darwin'` 硬编码 | 动态获取 |
|
||||
| 9 | `executor.ts:180` | 粘贴快捷键 | `command+v` | Win/Linux：`ctrl+v` |
|
||||
|
||||
### 2.4 缺失的 Linux 后端
|
||||
|
||||
| 包 | macOS | Windows | Linux |
|
||||
|---|-------|---------|-------|
|
||||
| `computer-use-input/backends/` | ✅ darwin.ts | ✅ win32.ts | ❌ 需新建 linux.ts |
|
||||
| `computer-use-swift/backends/` | ✅ darwin.ts | ✅ win32.ts | ❌ 需新建 linux.ts |
|
||||
|
||||
## 3. 每个平台的能力依赖
|
||||
|
||||
### 3.1 computer-use-input（键鼠）
|
||||
|
||||
| 功能 | macOS | Windows | Linux |
|
||||
|------|-------|---------|-------|
|
||||
| 鼠标移动 | CGEvent JXA | SetCursorPos P/Invoke | xdotool mousemove |
|
||||
| 鼠标点击 | CGEvent JXA | SendInput P/Invoke | xdotool click |
|
||||
| 鼠标滚轮 | CGEvent JXA | SendInput MOUSEEVENTF_WHEEL | xdotool scroll |
|
||||
| 键盘按键 | System Events osascript | keybd_event P/Invoke | xdotool key |
|
||||
| 组合键 | System Events osascript | keybd_event 组合 | xdotool key combo |
|
||||
| 文本输入 | System Events keystroke | SendKeys.SendWait | xdotool type |
|
||||
| 前台应用 | System Events osascript | GetForegroundWindow P/Invoke | xdotool getactivewindow + /proc |
|
||||
| 工具依赖 | osascript（内置） | powershell（内置） | xdotool（需安装） |
|
||||
|
||||
### 3.2 computer-use-swift（截图 + 应用管理）
|
||||
|
||||
| 功能 | macOS | Windows | Linux |
|
||||
|------|-------|---------|-------|
|
||||
| 全屏截图 | screencapture | CopyFromScreen | gnome-screenshot / scrot / grim |
|
||||
| 区域截图 | screencapture -R | CopyFromScreen(rect) | gnome-screenshot -a / scrot -a / grim -g |
|
||||
| 显示器列表 | CGGetActiveDisplayList JXA | Screen.AllScreens | xrandr --query |
|
||||
| 运行中应用 | System Events JXA | Get-Process | wmctrl -l / ps |
|
||||
| 打开应用 | osascript activate | Start-Process | xdg-open / gtk-launch |
|
||||
| 隐藏/显示 | System Events visibility | ShowWindow/SetForegroundWindow | wmctrl -c / xdotool |
|
||||
| 工具依赖 | screencapture + osascript | powershell | xdotool + scrot/grim + wmctrl |
|
||||
|
||||
### 3.3 executor 层
|
||||
|
||||
| 功能 | macOS | Windows | Linux |
|
||||
|------|-------|---------|-------|
|
||||
| drainRunLoop | CFRunLoop pump | 不需要 | 不需要 |
|
||||
| ESC 热键 | CGEventTap | 跳过（Ctrl+C fallback） | 跳过（Ctrl+C fallback） |
|
||||
| 剪贴板读 | pbpaste | `powershell Get-Clipboard` | xclip -o / wl-paste |
|
||||
| 剪贴板写 | pbcopy | `powershell Set-Clipboard` | xclip / wl-copy |
|
||||
| 粘贴快捷键 | command+v | ctrl+v | ctrl+v |
|
||||
| 终端检测 | __CFBundleIdentifier | WT_SESSION / TERM_PROGRAM | TERM_PROGRAM |
|
||||
| 系统权限 | TCC check | 直接 granted | 检查 xdotool 安装 |
|
||||
|
||||
## 4. 执行步骤
|
||||
|
||||
### Phase 1：已完成 ✅
|
||||
|
||||
- [x] `@ant/computer-use-mcp` stub → 完整实现
|
||||
- [x] `@ant/computer-use-input` dispatcher + darwin/win32 backends
|
||||
- [x] `@ant/computer-use-swift` dispatcher + darwin/win32 backends
|
||||
- [x] `CHICAGO_MCP` 编译开关
|
||||
|
||||
### Phase 2：移除 6 处 macOS 硬编码（解锁 macOS + Windows）
|
||||
|
||||
**改动原则：macOS 代码路径不变，只在每处 darwin 守卫后加 win32/linux 分支。**
|
||||
|
||||
| 步骤 | 文件 | 改动 |
|
||||
|------|------|------|
|
||||
| 2.1 | `src/main.tsx:1605` | `getPlatform() === 'macos'` → 去掉平台限制，或改为 `!== 'unknown'` |
|
||||
| 2.2 | `src/utils/computerUse/swiftLoader.ts:16-18` | 移除 `process.platform !== 'darwin'` throw。`@ant/computer-use-swift/index.ts` 已有跨平台 dispatch |
|
||||
| 2.3 | `src/utils/computerUse/executor.ts:263-267` | 移除 `process.platform !== 'darwin'` throw。改为检查 input/swift isSupported |
|
||||
| 2.4 | `src/utils/computerUse/executor.ts:70-88` | 剪贴板函数按平台分发：darwin→pbcopy/pbpaste，win32→PowerShell Get/Set-Clipboard，linux→xclip |
|
||||
| 2.5 | `src/utils/computerUse/executor.ts:180` | `typeViaClipboard` 中 `command+v` → 非 darwin 时用 `ctrl+v` |
|
||||
| 2.6 | `src/utils/computerUse/executor.ts:273` | `const cu = requireComputerUseSwift()` → 改为 `new ComputerUseAPI()`（从 package 直接实例化，不走 swiftLoader throw） |
|
||||
| 2.7 | `src/utils/computerUse/drainRunLoop.ts` | 开头加 `if (process.platform !== 'darwin') return fn()` |
|
||||
| 2.8 | `src/utils/computerUse/escHotkey.ts` | `registerEscHotkey` 非 darwin 返回 false（已有 Ctrl+C fallback） |
|
||||
| 2.9 | `src/utils/computerUse/hostAdapter.ts:48-54` | `ensureOsPermissions` 非 darwin 返回 `{ granted: true }` |
|
||||
| 2.10 | `src/utils/computerUse/common.ts:56` | `platform: 'darwin'` → `platform: process.platform === 'win32' ? 'windows' : process.platform === 'linux' ? 'linux' : 'darwin'` |
|
||||
| 2.11 | `src/utils/computerUse/common.ts:55` | `screenshotFiltering: 'native'` → 非 darwin 时 `'none'`（Windows/Linux 截图不支持 per-app 过滤） |
|
||||
| 2.12 | `src/utils/computerUse/gates.ts:13` | `enabled: false` → `enabled: true`（无 GrowthBook 时默认可用） |
|
||||
| 2.13 | `src/utils/computerUse/gates.ts:39-43` | `hasRequiredSubscription()` → 直接返回 `true` |
|
||||
|
||||
### Phase 3：新增 Linux 后端
|
||||
|
||||
| 步骤 | 文件 | 内容 |
|
||||
|------|------|------|
|
||||
| 3.1 | `packages/@ant/computer-use-input/src/backends/linux.ts` | xdotool 键鼠（mousemove/click/key/type/getactivewindow） |
|
||||
| 3.2 | `packages/@ant/computer-use-swift/src/backends/linux.ts` | scrot/grim 截图 + xrandr 显示器 + wmctrl 窗口管理 |
|
||||
| 3.3 | `packages/@ant/computer-use-input/src/index.ts` | dispatcher 加 `case 'linux'` |
|
||||
| 3.4 | `packages/@ant/computer-use-swift/src/index.ts` | dispatcher 加 `case 'linux'` |
|
||||
|
||||
### Phase 4：验证
|
||||
|
||||
| 测试项 | macOS | Windows | Linux |
|
||||
|--------|-------|---------|-------|
|
||||
| build 成功 | ✅ | 验证 | 验证 |
|
||||
| MCP 工具列表非空 | 验证 | 验证 | 验证 |
|
||||
| 鼠标移动 | 验证 | ✅ 已通过 | 验证 |
|
||||
| 截图 | 验证 | ✅ 已通过 | 验证 |
|
||||
| 键盘输入 | 验证 | 验证 | 验证 |
|
||||
| 前台窗口 | 验证 | ✅ 已通过 | 验证 |
|
||||
| 剪贴板 | 验证 | 验证 | 验证 |
|
||||
|
||||
## 5. 文件改动总览
|
||||
|
||||
### 不动的文件（14 个）
|
||||
|
||||
`cleanup.ts`、`computerUseLock.ts`、`wrapper.tsx`、`toolRendering.tsx`、`mcpServer.ts`、`setup.ts`、`appNames.ts`、`inputLoader.ts`、`src/services/mcp/client.ts`、`@ant/computer-use-mcp/src/*`（Phase 1 已完成）、`backends/darwin.ts`（两个包都不动）
|
||||
|
||||
### 改 src/ 的文件（8 个）
|
||||
|
||||
| 文件 | 改动量 | 风险 |
|
||||
|------|--------|------|
|
||||
| `main.tsx` | 1 行 | 低 |
|
||||
| `swiftLoader.ts` | 2 行 | 低 |
|
||||
| `executor.ts` | ~40 行（剪贴板分发 + 平台守卫 + paste 快捷键） | **中** |
|
||||
| `drainRunLoop.ts` | 1 行 | 低 |
|
||||
| `escHotkey.ts` | 3 行 | 低 |
|
||||
| `hostAdapter.ts` | 5 行 | 低 |
|
||||
| `common.ts` | 3 行 | 低 |
|
||||
| `gates.ts` | 3 行 | 低 |
|
||||
|
||||
### 新增文件（2 个）
|
||||
|
||||
| 文件 | 行数估算 |
|
||||
|------|---------|
|
||||
| `packages/@ant/computer-use-input/src/backends/linux.ts` | ~150 行 |
|
||||
| `packages/@ant/computer-use-swift/src/backends/linux.ts` | ~200 行 |
|
||||
|
||||
## 6. Linux 依赖工具
|
||||
|
||||
| 工具 | 用途 | 安装命令（Ubuntu） |
|
||||
|------|------|-------------------|
|
||||
| `xdotool` | 键鼠模拟 + 窗口管理 | `sudo apt install xdotool` |
|
||||
| `scrot` 或 `gnome-screenshot` | 截图 | `sudo apt install scrot` |
|
||||
| `xrandr` | 显示器信息 | 通常已预装 |
|
||||
| `xclip` | 剪贴板 | `sudo apt install xclip` |
|
||||
| `wmctrl` | 窗口列表/切换 | `sudo apt install wmctrl` |
|
||||
|
||||
Wayland 环境需要替代工具：`ydotool`（替代 xdotool）、`grim`（替代 scrot）、`wl-clipboard`（替代 xclip）。初期可先只支持 X11，Wayland 标记为 todo。
|
||||
|
||||
## 7. 执行顺序建议
|
||||
|
||||
```
|
||||
Phase 2（解锁 macOS + Windows）
|
||||
├── 2.1-2.3 移除 3 处硬编码 throw/skip
|
||||
├── 2.4-2.5 剪贴板 + 粘贴快捷键平台分发
|
||||
├── 2.6 swiftLoader → 直接实例化
|
||||
├── 2.7-2.9 drainRunLoop / escHotkey / permissions 平台分支
|
||||
├── 2.10-2.11 common.ts 平台标识动态化
|
||||
├── 2.12-2.13 gates.ts 默认值
|
||||
└── 验证 Windows
|
||||
|
||||
Phase 3（Linux 后端）
|
||||
├── 3.1 input/backends/linux.ts
|
||||
├── 3.2 swift/backends/linux.ts
|
||||
├── 3.3-3.4 dispatcher 加 linux case
|
||||
└── 验证 Linux
|
||||
|
||||
Phase 4（集成验证 + PR）
|
||||
```
|
||||
|
||||
每个 Phase 可独立验证、独立提交。Phase 2 完成后 macOS + Windows 可用，Phase 3 完成后三平台全部可用。
|
||||
@@ -1,140 +0,0 @@
|
||||
# CONTEXT_COLLAPSE — 上下文折叠
|
||||
|
||||
> Feature Flag: `FEATURE_CONTEXT_COLLAPSE=1`
|
||||
> 子 Feature: `FEATURE_HISTORY_SNIP=1`
|
||||
> 实现状态：核心逻辑全部 Stub，布线完整
|
||||
> 引用数：CONTEXT_COLLAPSE 20 + HISTORY_SNIP 16 = 36
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
CONTEXT_COLLAPSE 让模型内省上下文窗口使用情况，并智能压缩旧消息。当对话接近上下文限制时，自动将旧消息折叠为压缩摘要，保留关键信息的同时释放 token 空间。
|
||||
|
||||
### 子 Feature
|
||||
|
||||
| Feature | 功能 |
|
||||
|---------|------|
|
||||
| `CONTEXT_COLLAPSE` | 上下文折叠引擎（后台 LLM 调用压缩旧消息） |
|
||||
| `HISTORY_SNIP` | SnipTool — 标记消息进行折叠/修剪 |
|
||||
|
||||
## 二、实现架构
|
||||
|
||||
### 2.1 模块状态
|
||||
|
||||
| 模块 | 文件 | 状态 |
|
||||
|------|------|------|
|
||||
| 折叠核心 | `src/services/contextCollapse/index.ts` | **Stub** — 接口完整（`ContextCollapseStats`、`CollapseResult`、`DrainResult`），函数全部空操作 |
|
||||
| 折叠操作 | `src/services/contextCollapse/operations.ts` | **Stub** — `projectView` 为恒等函数 |
|
||||
| 折叠持久化 | `src/services/contextCollapse/persist.ts` | **Stub** — `restoreFromEntries` 为空操作 |
|
||||
| CtxInspectTool | `src/tools/CtxInspectTool/` | **缺失** — 目录不存在 |
|
||||
| SnipTool 提示 | `src/tools/SnipTool/prompt.ts` | **Stub** — 空工具名 |
|
||||
| SnipTool 实现 | `src/tools/SnipTool/SnipTool.ts` | **缺失** |
|
||||
| force-snip 命令 | `src/commands/force-snip.js` | **缺失** |
|
||||
| 折叠读取搜索 | `src/utils/collapseReadSearch.ts` | **完整** — Snip 作为静默吸收操作 |
|
||||
| QueryEngine 集成 | `src/QueryEngine.ts` | **布线** — 导入并使用 snip 投影 |
|
||||
| Token 警告 UI | `src/components/TokenWarning.tsx` | **布线** — 折叠进度标签 |
|
||||
|
||||
### 2.2 核心接口（已定义，待实现）
|
||||
|
||||
```ts
|
||||
// contextCollapse/index.ts
|
||||
interface ContextCollapseStats {
|
||||
// 上下文使用统计
|
||||
}
|
||||
interface CollapseResult {
|
||||
// 折叠操作结果
|
||||
}
|
||||
interface DrainResult {
|
||||
// 紧急释放结果
|
||||
}
|
||||
|
||||
// 关键函数（全部 stub）：
|
||||
isContextCollapseEnabled() // → false
|
||||
applyCollapsesIfNeeded(messages) // 透传
|
||||
recoverFromOverflow(messages) // 透传（413 恢复）
|
||||
initContextCollapse() // 空操作
|
||||
```
|
||||
|
||||
### 2.3 预期数据流
|
||||
|
||||
```
|
||||
对话持续增长
|
||||
│
|
||||
▼
|
||||
上下文接近限制（由 query.ts 检测）
|
||||
│
|
||||
├── 溢出检测 (query.ts:440,616,802)
|
||||
│
|
||||
▼
|
||||
applyCollapsesIfNeeded(messages) [需要实现]
|
||||
│
|
||||
├── 后台 LLM 调用压缩旧消息
|
||||
├── 保留关键信息（决策、文件路径、错误）
|
||||
└── 替换旧消息为压缩摘要
|
||||
│
|
||||
├── 413 恢复 (query.ts:1093,1179)
|
||||
│ └── recoverFromOverflow() 紧急折叠
|
||||
│
|
||||
▼
|
||||
projectView() 过滤折叠后的消息视图
|
||||
│
|
||||
▼
|
||||
模型继续工作（在压缩后的上下文中）
|
||||
```
|
||||
|
||||
### 2.4 HISTORY_SNIP 子功能
|
||||
|
||||
SnipTool 提供手动折叠能力：
|
||||
|
||||
- `/force-snip` 命令 — 强制执行折叠
|
||||
- SnipTool — 标记特定消息进行折叠/修剪
|
||||
- `collapseReadSearch.ts` 已完整实现，将 Snip 作为静默吸收操作处理
|
||||
|
||||
### 2.5 集成点
|
||||
|
||||
| 文件 | 位置 | 说明 |
|
||||
|------|------|------|
|
||||
| `src/query.ts` | 18,440,616,802,1093,1179 | 溢出检测、413 恢复、折叠应用 |
|
||||
| `src/QueryEngine.ts` | 124,127,1301 | Snip 投影使用 |
|
||||
| `src/utils/analyzeContext.ts` | 1122 | 跳过保留缓冲区显示 |
|
||||
| `src/utils/sessionRestore.ts` | 127,494 | 恢复折叠状态 |
|
||||
| `src/services/compact/autoCompact.ts` | 179,215 | 自动压缩时考虑折叠 |
|
||||
|
||||
## 三、需要补全的内容
|
||||
|
||||
| 优先级 | 模块 | 工作量 | 说明 |
|
||||
|--------|------|--------|------|
|
||||
| 1 | `services/contextCollapse/index.ts` | 大 | 折叠状态机、LLM 调用、消息压缩 |
|
||||
| 2 | `services/contextCollapse/operations.ts` | 中 | `projectView()` 消息过滤 |
|
||||
| 3 | `services/contextCollapse/persist.ts` | 小 | `restoreFromEntries()` 磁盘持久化 |
|
||||
| 4 | `tools/CtxInspectTool/` | 中 | 上下文内省工具（token 计数、已折叠范围） |
|
||||
| 5 | `tools/SnipTool/SnipTool.ts` | 中 | Snip 工具实现 |
|
||||
| 6 | `commands/force-snip.js` | 小 | `/force-snip` 命令 |
|
||||
|
||||
## 四、关键设计决策
|
||||
|
||||
1. **后台 LLM 压缩**：折叠不是简单截断，而是用 LLM 生成压缩摘要保留关键信息
|
||||
2. **413 恢复**：当 API 返回 413（请求过大）时，紧急折叠是最重要的恢复手段
|
||||
3. **与 autoCompact 协作**：折叠和自动压缩（compact）是不同的机制，折叠在消息级别，压缩在对话级别
|
||||
4. **持久化**：折叠状态持久化到磁盘，会话恢复时重载
|
||||
|
||||
## 五、使用方式
|
||||
|
||||
```bash
|
||||
# 启用 context collapse
|
||||
FEATURE_CONTEXT_COLLAPSE=1 bun run dev
|
||||
|
||||
# 启用 snip 子功能
|
||||
FEATURE_CONTEXT_COLLAPSE=1 FEATURE_HISTORY_SNIP=1 bun run dev
|
||||
```
|
||||
|
||||
## 六、文件索引
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `src/services/contextCollapse/index.ts` | 折叠核心（stub，接口已定义） |
|
||||
| `src/services/contextCollapse/operations.ts` | 投影操作（stub） |
|
||||
| `src/services/contextCollapse/persist.ts` | 持久化（stub） |
|
||||
| `src/utils/collapseReadSearch.ts` | Snip 吸收操作（完整） |
|
||||
| `src/query.ts` | 溢出检测和 413 恢复集成 |
|
||||
| `src/QueryEngine.ts` | Snip 投影使用 |
|
||||
| `src/components/TokenWarning.tsx` | 折叠进度 UI |
|
||||
@@ -1,151 +0,0 @@
|
||||
# COORDINATOR_MODE — 多 Agent 编排
|
||||
|
||||
> Feature Flag: `FEATURE_COORDINATOR_MODE=1` + 环境变量 `CLAUDE_CODE_COORDINATOR_MODE=1`
|
||||
> 实现状态：编排者完整可用，worker agent 为通用 AgentTool worker
|
||||
> 引用数：32
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
COORDINATOR_MODE 将 CLI 变为"编排者"角色。编排者不直接操作文件，而是通过 AgentTool 派发任务给多个 worker 并行执行。适用于大型任务拆分、并行研究、实现+验证分离等场景。
|
||||
|
||||
### 核心约束
|
||||
|
||||
- 编排者只能使用：`Agent`（派发 worker）、`SendMessage`（继续 worker）、`TaskStop`（停止 worker）
|
||||
- Worker 可以使用所有标准工具（Bash、Read、Edit 等）+ MCP 工具 + Skill 工具
|
||||
- 编排者的每条消息都是给用户看的；worker 结果以 `<task-notification>` XML 形式到达
|
||||
|
||||
## 二、用户交互
|
||||
|
||||
### 启用方式
|
||||
|
||||
```bash
|
||||
FEATURE_COORDINATOR_MODE=1 CLAUDE_CODE_COORDINATOR_MODE=1 bun run dev
|
||||
```
|
||||
|
||||
需要同时设置 feature flag 和环境变量。`CLAUDE_CODE_COORDINATOR_MODE` 可在会话恢复时自动切换（`matchSessionMode`）。
|
||||
|
||||
### 典型工作流
|
||||
|
||||
```
|
||||
用户: "修复 auth 模块的 null pointer"
|
||||
|
||||
编排者:
|
||||
1. 并行派发两个 worker:
|
||||
- Agent({ description: "调查 auth bug", prompt: "..." })
|
||||
- Agent({ description: "研究 auth 测试", prompt: "..." })
|
||||
|
||||
2. 收到 <task-notification>:
|
||||
- Worker A: "在 validate.ts:42 发现 null pointer"
|
||||
- Worker B: "测试覆盖情况..."
|
||||
|
||||
3. 综合发现，继续 Worker A:
|
||||
- SendMessage({ to: "agent-a1b", message: "修复 validate.ts:42..." })
|
||||
|
||||
4. 收到修复结果，派发验证:
|
||||
- Agent({ description: "验证修复", prompt: "..." })
|
||||
```
|
||||
|
||||
## 三、实现架构
|
||||
|
||||
### 3.1 模式检测
|
||||
|
||||
文件：`src/coordinator/coordinatorMode.ts:36-41`
|
||||
|
||||
```ts
|
||||
export function isCoordinatorMode(): boolean {
|
||||
return feature('COORDINATOR_MODE') &&
|
||||
isEnvTruthy(process.env.CLAUDE_CODE_COORDINATOR_MODE)
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 会话模式恢复
|
||||
|
||||
`matchSessionMode(sessionMode)` 在恢复旧会话时检查存储的模式，如果当前环境变量与存储不一致，自动翻转环境变量。防止在普通模式下恢复编排会话（或反之）。
|
||||
|
||||
### 3.3 Worker 工具集
|
||||
|
||||
`getCoordinatorUserContext()` 告知编排者 worker 可用的工具列表：
|
||||
|
||||
- **标准模式**：`ASYNC_AGENT_ALLOWED_TOOLS` 排除内部工具（TeamCreate、TeamDelete、SendMessage、SyntheticOutput）
|
||||
- **Simple 模式**（`CLAUDE_CODE_SIMPLE=1`）：仅 Bash、Read、Edit
|
||||
- **MCP 工具**：列出已连接的 MCP 服务器名称
|
||||
- **Scratchpad**：如果 GrowthBook `tengu_scratch` 启用，提供跨 worker 共享的 scratchpad 目录
|
||||
|
||||
### 3.4 系统提示
|
||||
|
||||
文件：`src/coordinator/coordinatorMode.ts:111-369`
|
||||
|
||||
编排者系统提示（`getCoordinatorSystemPrompt()`）约 370 行，包含：
|
||||
|
||||
| 章节 | 内容 |
|
||||
|------|------|
|
||||
| 1. Your Role | 编排者职责定义 |
|
||||
| 2. Your Tools | Agent/SendMessage/TaskStop 使用说明 |
|
||||
| 3. Workers | Worker 能力和限制 |
|
||||
| 4. Task Workflow | Research → Synthesis → Implementation → Verification 流程 |
|
||||
| 5. Writing Worker Prompts | 自包含 prompt 编写指南 + 好坏示例对比 |
|
||||
| 6. Example Session | 完整示例对话 |
|
||||
|
||||
### 3.5 Worker Agent
|
||||
|
||||
文件：`src/coordinator/workerAgent.ts`
|
||||
|
||||
当前为 stub。Worker 实际使用通用 AgentTool 的 `worker` subagent_type。
|
||||
|
||||
### 3.6 数据流
|
||||
|
||||
```
|
||||
用户消息
|
||||
│
|
||||
▼
|
||||
编排者 REPL（受限工具集）
|
||||
│
|
||||
├──→ Agent({ subagent_type: "worker", prompt: "..." })
|
||||
│ │
|
||||
│ ▼
|
||||
│ Worker Agent（完整工具集）
|
||||
│ ├── 执行任务（Bash/Read/Edit/...）
|
||||
│ └── 返回 <task-notification>
|
||||
│
|
||||
├──→ SendMessage({ to: "agent-id", message: "..." })
|
||||
│ │
|
||||
│ ▼
|
||||
│ 继续已存在的 Worker
|
||||
│
|
||||
└──→ TaskStop({ task_id: "agent-id" })
|
||||
│
|
||||
▼
|
||||
停止运行中的 Worker
|
||||
```
|
||||
|
||||
## 四、关键设计决策
|
||||
|
||||
1. **双开关设计**：feature flag 控制代码可用性，环境变量控制实际激活。允许编译时包含但不默认启用
|
||||
2. **编排者受限**：只能用 Agent/SendMessage/TaskStop，确保编排者专注于派发而非执行
|
||||
3. **Worker 不可见编排者对话**：每个 worker 的 prompt 必须自包含（所有必要上下文）
|
||||
4. **并行优先**：系统提示强调"Parallelism is your superpower"，鼓励并行派发独立任务
|
||||
5. **综合而非转发**：编排者必须理解 worker 发现，再写出具体的实现指令。禁止 "based on your findings" 类懒惰委托
|
||||
6. **Scratchpad 可选共享**：通过 GrowthBook 门控的共享目录，让 worker 之间持久化共享知识
|
||||
|
||||
## 五、使用方式
|
||||
|
||||
```bash
|
||||
# 基本启用
|
||||
FEATURE_COORDINATOR_MODE=1 CLAUDE_CODE_COORDINATOR_MODE=1 bun run dev
|
||||
|
||||
# 配合 Fork Subagent
|
||||
FEATURE_COORDINATOR_MODE=1 FEATURE_FORK_SUBAGENT=1 \
|
||||
CLAUDE_CODE_COORDINATOR_MODE=1 bun run dev
|
||||
|
||||
# Simple 模式（worker 只有 Bash/Read/Edit）
|
||||
FEATURE_COORDINATOR_MODE=1 CLAUDE_CODE_COORDINATOR_MODE=1 \
|
||||
CLAUDE_CODE_SIMPLE=1 bun run dev
|
||||
```
|
||||
|
||||
## 六、文件索引
|
||||
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
| `src/coordinator/coordinatorMode.ts` | 370 | 模式检测 + 系统提示 + 用户上下文 |
|
||||
| `src/coordinator/workerAgent.ts` | — | Worker agent 定义（stub） |
|
||||
| `src/constants/tools.ts` | — | `ASYNC_AGENT_ALLOWED_TOOLS` 工具白名单 |
|
||||
@@ -1,102 +0,0 @@
|
||||
# DAEMON — 后台守护进程
|
||||
|
||||
> Feature Flag: `FEATURE_DAEMON=1`
|
||||
> 实现状态：主进程和 worker 注册为 Stub，CLI 路由完整
|
||||
> 引用数：3
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
DAEMON 将 Claude Code 变为后台守护进程。主进程（supervisor）管理多个 worker 进程的生命周期，通过 Unix 域套接字进行 IPC。适用于持续运行的后台服务场景（如配合 BRIDGE_MODE 提供远程控制服务）。
|
||||
|
||||
## 二、实现架构
|
||||
|
||||
### 2.1 模块状态
|
||||
|
||||
| 模块 | 文件 | 状态 |
|
||||
|------|------|------|
|
||||
| 守护主进程 | `src/daemon/main.ts` | **Stub** — `daemonMain: () => Promise.resolve()` |
|
||||
| Worker 注册 | `src/daemon/workerRegistry.ts` | **Stub** — `runDaemonWorker: () => Promise.resolve()` |
|
||||
| CLI 路由 | `src/entrypoints/cli.tsx` | **布线** — `--daemon-worker` 和 `daemon` 子命令 |
|
||||
| 命令注册 | `src/commands.ts` | **布线** — DAEMON + BRIDGE_MODE 门控 |
|
||||
|
||||
### 2.2 CLI 入口
|
||||
|
||||
```
|
||||
# 启动守护进程
|
||||
claude daemon
|
||||
|
||||
# 以 worker 身份启动
|
||||
claude --daemon-worker=<kind>
|
||||
```
|
||||
|
||||
### 2.3 预期架构
|
||||
|
||||
```
|
||||
Supervisor (daemonMain)
|
||||
│
|
||||
├── Worker 1: assistant-mode
|
||||
│ └── 接收和处理 assistant 会话
|
||||
│
|
||||
├── Worker 2: bridge-sync
|
||||
│ └── bridge 消息同步
|
||||
│
|
||||
└── Worker 3: proactive
|
||||
└── 主动任务执行
|
||||
│
|
||||
▼
|
||||
IPC via Unix Domain Sockets
|
||||
- 生命周期管理（启动、停止、重启）
|
||||
- 工作分发
|
||||
- 状态报告
|
||||
```
|
||||
|
||||
### 2.4 与 BRIDGE_MODE 的关系
|
||||
|
||||
DAEMON 和 BRIDGE_MODE 常组合使用：
|
||||
|
||||
```ts
|
||||
// src/commands.ts
|
||||
if (feature('DAEMON') && feature('BRIDGE_MODE')) {
|
||||
// 加载 remoteControlServer 命令
|
||||
}
|
||||
```
|
||||
|
||||
双重门控：两个 feature 都需要开启才能使用远程控制服务器。
|
||||
|
||||
## 三、需要补全的内容
|
||||
|
||||
| 模块 | 工作量 | 说明 |
|
||||
|------|--------|------|
|
||||
| `daemon/main.ts` | 大 | Supervisor 主进程：启动 worker、生命周期管理、IPC |
|
||||
| `daemon/workerRegistry.ts` | 中 | Worker 类型分发（assistant/bridge-sync/proactive） |
|
||||
| Worker 实现 | 大 | 各类型 worker 的具体实现 |
|
||||
| IPC 协议 | 中 | Supervisor-Worker 通信层 |
|
||||
|
||||
## 四、关键设计决策
|
||||
|
||||
1. **多进程架构**：一个 supervisor + 多个 worker，进程隔离
|
||||
2. **Unix 域套接字 IPC**：本地进程间通信，低延迟
|
||||
3. **与 BRIDGE_MODE 强绑定**：守护进程最常见的用途是提供远程控制服务
|
||||
4. **CLI 子命令路由**：`daemon` 子命令和 `--daemon-worker` 参数在 `cli.tsx` 中路由
|
||||
|
||||
## 五、使用方式
|
||||
|
||||
```bash
|
||||
# 启用守护进程模式
|
||||
FEATURE_DAEMON=1 FEATURE_BRIDGE_MODE=1 bun run dev
|
||||
|
||||
# 启动守护进程
|
||||
claude daemon
|
||||
|
||||
# 以特定 worker 启动
|
||||
claude --daemon-worker=assistant
|
||||
```
|
||||
|
||||
## 六、文件索引
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `src/daemon/main.ts` | Supervisor 主进程（stub） |
|
||||
| `src/daemon/workerRegistry.ts` | Worker 注册（stub） |
|
||||
| `src/entrypoints/cli.tsx:95,149` | CLI 路由 |
|
||||
| `src/commands.ts:77` | 命令注册（双重门控） |
|
||||
@@ -1,48 +0,0 @@
|
||||
---
|
||||
title: "Debug 模式"
|
||||
description: "通过 VS Code attach 模式调试 CLI 运行时，支持断点、单步执行和变量查看。"
|
||||
keywords: ["debug", "调试", "VS Code", "inspect", "断点"]
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
TUI (REPL) 模式需要真实终端，无法直接通过 VS Code launch 启动调试。使用 **attach 模式**连接到正在运行的 Bun 进程。
|
||||
|
||||
## 步骤
|
||||
|
||||
### 1. 终端启动 inspect 服务
|
||||
|
||||
```bash
|
||||
bun run dev:inspect
|
||||
```
|
||||
|
||||
会输出类似 `ws://localhost:8888/xxxxxxxx` 的地址。
|
||||
|
||||
### 2. VS Code 附着调试器
|
||||
|
||||
1. 在 `src/` 文件中打断点
|
||||
2. F5 → 选择 **"Attach to Bun (TUI debug)"**
|
||||
|
||||
> **注意**：`dev:inspect` 和 `launch.json` 中的 WebSocket 地址会在每次启动时变化，需要同步更新两处。
|
||||
|
||||
## 原理
|
||||
|
||||
`dev:inspect` 脚本实际执行的是：
|
||||
|
||||
```bash
|
||||
bun --inspect-wait=localhost:8888/<token> run scripts/dev.ts
|
||||
```
|
||||
|
||||
Bun 的 `--inspect-wait` 参数启动一个 Chrome DevTools Protocol 兼容的 inspect 服务，等待调试器连接后才开始执行。VS Code 的 `bun` 扩展通过 WebSocket 连接到这个地址实现 attach。
|
||||
|
||||
## JetBrains IDE
|
||||
|
||||
理论上 JetBrains 系列（WebStorm / IntelliJ 等）也支持 attach 到 Bun inspect 服务（Run → Attach to Process），但尚未实际验证过。如果你验证成功，欢迎补充文档。
|
||||
|
||||
## 相关文件
|
||||
|
||||
| 文件 | 说明 |
|
||||
|---|---|
|
||||
| `package.json` → `dev:inspect` | 启动 inspect 服务的 npm script |
|
||||
| `.vscode/launch.json` | VS Code attach 调试配置 |
|
||||
| `scripts/dev.ts` | dev 模式入口，注入 MACRO defines |
|
||||
@@ -1,99 +0,0 @@
|
||||
# EXPERIMENTAL_SKILL_SEARCH — 技能语义搜索
|
||||
|
||||
> Feature Flag: `FEATURE_EXPERIMENTAL_SKILL_SEARCH=1`
|
||||
> 实现状态：全部 Stub（8 个文件），布线完整
|
||||
> 引用数：21
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
EXPERIMENTAL_SKILL_SEARCH 提供 DiscoverSkills 工具，根据当前任务语义搜索可用技能。目标是让模型在执行任务时自动发现和推荐相关的技能（包括本地和远程），无需用户手动查找。
|
||||
|
||||
## 二、实现架构
|
||||
|
||||
### 2.1 模块状态
|
||||
|
||||
| 模块 | 文件 | 状态 | 说明 |
|
||||
|------|------|------|------|
|
||||
| DiscoverSkillsTool | `src/tools/DiscoverSkillsTool/prompt.ts` | **Stub** | 空工具名 |
|
||||
| 预取 | `src/services/skillSearch/prefetch.ts` | **Stub** | 3 个函数全部空操作 |
|
||||
| 远程加载 | `src/services/skillSearch/remoteSkillLoader.ts` | **Stub** | 返回空结果 |
|
||||
| 远程状态 | `src/services/skillSearch/remoteSkillState.ts` | **Stub** | 返回 null/undefined |
|
||||
| 信号 | `src/services/skillSearch/signals.ts` | **Stub** | `DiscoverySignal = any` |
|
||||
| 遥测 | `src/services/skillSearch/telemetry.ts` | **Stub** | 空操作日志 |
|
||||
| 本地搜索 | `src/services/skillSearch/localSearch.ts` | **Stub** | 空操作缓存 |
|
||||
| 功能检查 | `src/services/skillSearch/featureCheck.ts` | **Stub** | `isSkillSearchEnabled => false` |
|
||||
| SkillTool 集成 | `src/tools/SkillTool/SkillTool.ts` | **布线** | 动态加载所有远程技能模块 |
|
||||
| 提示集成 | `src/constants/prompts.ts` | **布线** | DiscoverSkills schema 注入 |
|
||||
|
||||
### 2.2 预期数据流
|
||||
|
||||
```
|
||||
模型处理用户任务
|
||||
│
|
||||
▼
|
||||
DiscoverSkills 工具触发 [需要实现]
|
||||
│
|
||||
├── 本地搜索：索引已安装技能元数据
|
||||
│ └── localSearch.ts → 技能名称/描述/关键字匹配
|
||||
│
|
||||
└── 远程搜索：查询技能市场/注册表
|
||||
└── remoteSkillLoader.ts → fetch + 解析
|
||||
│
|
||||
▼
|
||||
结果排序和过滤
|
||||
│
|
||||
▼
|
||||
返回推荐技能列表
|
||||
│
|
||||
▼
|
||||
模型使用 SkillTool 调用推荐技能
|
||||
```
|
||||
|
||||
### 2.3 预取机制
|
||||
|
||||
`prefetch.ts` 预期在用户提交输入前分析消息内容，提前搜索相关技能：
|
||||
|
||||
- `startSkillDiscoveryPrefetch()` — 开始预取
|
||||
- `collectSkillDiscoveryPrefetch()` — 收集预取结果
|
||||
- `getTurnZeroSkillDiscovery()` — 获取 turn 0 的技能发现结果
|
||||
|
||||
## 三、需要补全的内容
|
||||
|
||||
| 优先级 | 模块 | 工作量 | 说明 |
|
||||
|--------|------|--------|------|
|
||||
| 1 | `DiscoverSkillsTool` | 大 | 语义搜索工具 schema + 执行 |
|
||||
| 2 | `skillSearch/prefetch.ts` | 中 | 用户输入分析和预取逻辑 |
|
||||
| 3 | `skillSearch/remoteSkillLoader.ts` | 大 | 远程市场/注册表获取 |
|
||||
| 4 | `skillSearch/remoteSkillState.ts` | 小 | 已发现技能状态管理 |
|
||||
| 5 | `skillSearch/localSearch.ts` | 中 | 本地索引构建/查询 |
|
||||
| 6 | `skillSearch/featureCheck.ts` | 小 | GrowthBook/配置门控 |
|
||||
| 7 | `skillSearch/signals.ts` | 小 | `DiscoverySignal` 类型定义 |
|
||||
|
||||
## 四、关键设计决策
|
||||
|
||||
1. **预取优化**：在用户提交前就开始搜索，减少首次响应延迟
|
||||
2. **本地+远程双搜索**：本地索引快速匹配 + 远程市场深度搜索
|
||||
3. **SkillTool 集成**：发现的技能通过 SkillTool 调用，不需要新的调用机制
|
||||
4. **独立于 MCP_SKILLS**：MCP_SKILLS 从 MCP 服务器发现，EXPERIMENTAL_SKILL_SEARCH 从技能市场发现
|
||||
|
||||
## 五、使用方式
|
||||
|
||||
```bash
|
||||
# 启用 feature（需要补全后才能真正使用）
|
||||
FEATURE_EXPERIMENTAL_SKILL_SEARCH=1 bun run dev
|
||||
```
|
||||
|
||||
## 六、文件索引
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `src/tools/DiscoverSkillsTool/prompt.ts` | 工具 schema（stub） |
|
||||
| `src/services/skillSearch/prefetch.ts` | 预取逻辑（stub） |
|
||||
| `src/services/skillSearch/remoteSkillLoader.ts` | 远程加载（stub） |
|
||||
| `src/services/skillSearch/remoteSkillState.ts` | 远程状态（stub） |
|
||||
| `src/services/skillSearch/signals.ts` | 信号类型（stub） |
|
||||
| `src/services/skillSearch/telemetry.ts` | 遥测（stub） |
|
||||
| `src/services/skillSearch/localSearch.ts` | 本地搜索（stub） |
|
||||
| `src/services/skillSearch/featureCheck.ts` | 功能检查（stub） |
|
||||
| `src/tools/SkillTool/SkillTool.ts` | SkillTool 集成点 |
|
||||
| `src/constants/prompts.ts:95,335,778` | 提示增强 |
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,160 +0,0 @@
|
||||
# Feature Flags 审查报告 — Codex 复核
|
||||
|
||||
> 审查日期: 2026-04-05
|
||||
> 审查工具: Codex CLI v0.118.0 (本地, full-auto mode)
|
||||
> 消耗 tokens: 240,306
|
||||
> 审查范围: docs/feature-flags-audit-complete.md 中标记为 COMPLETE 的 22 个编译时 feature flag
|
||||
|
||||
---
|
||||
|
||||
## 审查背景
|
||||
|
||||
原始审计报告 (`docs/feature-flags-audit-complete.md`) 声称 22 个 feature flag 被标记为 "COMPLETE"，只需在 `build.ts` / `scripts/dev.ts` 中启用即可工作。
|
||||
|
||||
Claude Code 团队通过 6 个并行子代理实际读取源码后初步发现大量误判，随后将分析结果传递给 Codex CLI 进行独立二次验证。
|
||||
|
||||
---
|
||||
|
||||
## Codex 发现摘要
|
||||
|
||||
### High 级发现
|
||||
|
||||
1. **`CONTEXT_COLLAPSE` 不是 COMPLETE**
|
||||
- `src/services/contextCollapse/index.ts:43` — `isContextCollapseEnabled()` 硬编码为 `false`
|
||||
- `src/services/contextCollapse/index.ts:47` — `applyCollapsesIfNeeded()` 只是原样返回消息
|
||||
- `src/services/contextCollapse/index.ts:59` — `recoverFromOverflow()` 也是 no-op
|
||||
- `src/services/contextCollapse/operations.ts:3` 和 `persist.ts:3` 同样是 stub
|
||||
- 审计报告把 UI/命令文件算进去了，但真正被查询循环消费的是 stub 后端
|
||||
|
||||
2. **原分类"真正只需编译开关"的 7 个 flag，只有 3 个准确**
|
||||
- ✅ `SHOT_STATS` — 零额外门控，compile-only
|
||||
- ✅ `PROMPT_CACHE_BREAK_DETECTION` — 有 try-catch 兜底，compile-only
|
||||
- ✅ `TOKEN_BUDGET` — 纯本地计算，compile-only
|
||||
- ❌ `TEAMMEM` — 还要求 AutoMem + GrowthBook `tengu_herring_clock` + GitHub repo (`teamMemPaths.ts:73`, `watcher.ts:256`, `watcher.ts:259`)
|
||||
- ❌ `AGENT_TRIGGERS` — 受 `isKairosCronEnabled()` GrowthBook 控制 (`useScheduledTasks.ts:61`, `useScheduledTasks.ts:119`)
|
||||
- ❌ `EXTRACT_MEMORIES` — 受 `tengu_passport_quail` + AutoMem + 非 remote 限制 (`extractMemories.ts:536`, `:545`, `:550`)
|
||||
- ❌ `KAIROS_BRIEF` — 受 `tengu_kairos_brief` + opt-in/kairosActive 限制 (`BriefTool.ts:95`, `:126`, `:132`)
|
||||
|
||||
### Medium 级发现
|
||||
|
||||
3. **`BG_SESSIONS` 和 `BASH_CLASSIFIER` 不适合简单归为"全 stub"**
|
||||
- `BG_SESSIONS` — 会话注册/清理是真实现 (`concurrentSessions.ts:44`, `:55`)，但任务摘要核心是 stub (`taskSummary.ts:2`)
|
||||
- `BASH_CLASSIFIER` — 权限编排很大一块是真实现 (`bashPermissions.ts` 2621行)，但分类后端 `bashClassifier.ts:24` 永远返回 disabled
|
||||
|
||||
4. **审计口径问题**
|
||||
- 把"代码量/周边 UI 很多"误当成"可独立启用"
|
||||
- `PROACTIVE` — `index.ts:3` 只有 state stub，`commands.ts:64` 和 `REPL.tsx:415` 引用缺失文件
|
||||
- `REACTIVE_COMPACT` — `reactiveCompact.ts:13` 整块是 stub
|
||||
- `CACHED_MICROCOMPACT` — `cachedMicrocompact.ts:22` 全部 stub
|
||||
|
||||
---
|
||||
|
||||
## Codex 修正后的分类
|
||||
|
||||
### 第一类：真正 compile-only（3 个）
|
||||
|
||||
| Flag | 说明 | Crash 风险 |
|
||||
|------|------|-----------|
|
||||
| **SHOT_STATS** | 纯本地 shot 分布统计，ant-only 数据路径 | 低 |
|
||||
| **PROMPT_CACHE_BREAK_DETECTION** | 本地 cache key 变化检测，写 diff 有兜底 | 低 |
|
||||
| **TOKEN_BUDGET** | 本地 token 预算追踪，纯计算逻辑 | 低 |
|
||||
|
||||
### 第二类：compile + 运行时条件（7 个）
|
||||
|
||||
| Flag | 条件 | Crash 风险 |
|
||||
|------|------|-----------|
|
||||
| **TEAMMEM** | AutoMem + GrowthBook `tengu_herring_clock` + GitHub repo | 低 (clean no-op) |
|
||||
| **AGENT_TRIGGERS** | GrowthBook `isKairosCronEnabled()` | 低 (clean no-op) |
|
||||
| **EXTRACT_MEMORIES** | `tengu_passport_quail` + AutoMem + 非 remote | 低 (clean no-op) |
|
||||
| **KAIROS_BRIEF** | `tengu_kairos_brief` + opt-in/kairosActive，可用 `CLAUDE_CODE_BRIEF=1` 绕过 | 低 |
|
||||
| **COORDINATOR_MODE** | 需 `CLAUDE_CODE_COORDINATOR_MODE=1`，`workerAgent.ts` 是 stub 但不阻塞 | 低 |
|
||||
| **COMMIT_ATTRIBUTION** | 仅对 `isInternal=true` 的 repo 生效 | 低 |
|
||||
| **VERIFICATION_AGENT** | 受 GrowthBook `tengu_hive_evidence` 双重门控 | 低 |
|
||||
|
||||
### 第三类：混合型 — 部分实现 + stub 核心（5 个）
|
||||
|
||||
| Flag | 真实现部分 | Stub 核心 |
|
||||
|------|-----------|----------|
|
||||
| **BG_SESSIONS** | 会话注册/清理 (`concurrentSessions.ts`) | `bg.ts`/`taskSummary.ts`/`udsClient.ts` 全 stub + 依赖 tmux |
|
||||
| **BASH_CLASSIFIER** | 权限编排 (`bashPermissions.ts` 2621行) | `bashClassifier.ts` 分类后端 stub + 需 API beta |
|
||||
| **PROACTIVE** | REPL/命令注册框架 | `index.ts` stub + 3 文件缺失 |
|
||||
| **REACTIVE_COMPACT** | 调用点已在主查询环路 | `reactiveCompact.ts` 22行全 no-op |
|
||||
| **CACHED_MICROCOMPACT** | 调用点已布线 | `cachedMicrocompact.ts` 全 stub + 需未公开 API |
|
||||
|
||||
### 第四类：纯 stub（1 个）
|
||||
|
||||
| Flag | 问题 |
|
||||
|------|------|
|
||||
| **CONTEXT_COLLAPSE** | 3 核心文件全 stub + CtxInspectTool 目录不存在 |
|
||||
|
||||
### 第五类：依赖远程服务（3 个）
|
||||
|
||||
| Flag | 依赖 |
|
||||
|------|------|
|
||||
| **ULTRAPLAN** | CCR 远程 agent 基础设施 + OAuth |
|
||||
| **CCR_REMOTE_SETUP** | claude.ai OAuth + GitHub CLI + CCR 后端 |
|
||||
| **BRIDGE_MODE** (build端) | claude.ai 订阅 + GrowthBook + WebSocket 后端 |
|
||||
|
||||
---
|
||||
|
||||
## 第三类恢复优先级建议
|
||||
|
||||
Codex 推荐的恢复顺序：
|
||||
|
||||
1. **REACTIVE_COMPACT** — 收益最直接，调用点在主查询环路，改完最容易立刻见效
|
||||
2. **BG_SESSIONS** — 已有会话注册基础，补齐摘要和后台运行链路的 ROI 高
|
||||
3. **PROACTIVE** — 产品面大，但缺文件比 stub 更严重，范围比前两项大
|
||||
4. **CONTEXT_COLLAPSE** — collapse engine 全 stub，恢复成本和设计不确定性都高
|
||||
5. **BASH_CLASSIFIER** — 若无 API beta 能力不值得优先；若有则升到第 2
|
||||
6. **CACHED_MICROCOMPACT** — 受未公开 API 约束，最后做
|
||||
|
||||
---
|
||||
|
||||
## 审计报告分类标准修正建议
|
||||
|
||||
Codex 建议将原来的单轴分类（COMPLETE/PARTIAL/STUB）改为**三轴**：
|
||||
|
||||
| 轴 | 取值 | 说明 |
|
||||
|----|------|------|
|
||||
| **实现完整度** | `full` / `mixed` / `stub` | 活跃调用链上的核心模块是否有真实现 |
|
||||
| **激活条件** | `compile-only` / `compile+env` / `compile+GrowthBook` / `compile+remote` / `compile+private API` | 启用需要什么 |
|
||||
| **运行风险** | `safe no-op` / `background IO` / `startup critical` | 启用后条件不满足时的行为 |
|
||||
|
||||
**COMPLETE 的最低标准应满足：**
|
||||
1. 活跃调用链上的核心模块不能是 stub
|
||||
2. "可启用"不能只看编译 flag，还要单列运行时 gate
|
||||
|
||||
按此标准，`CONTEXT_COLLAPSE`、`BG_SESSIONS`、`BASH_CLASSIFIER`、`PROACTIVE`、`REACTIVE_COMPACT`、`CACHED_MICROCOMPACT` 都应从 COMPLETE 降级。
|
||||
|
||||
---
|
||||
|
||||
## 已采取的行动
|
||||
|
||||
基于审查结果，已将以下 3 个确认安全的 flag 加入默认构建：
|
||||
|
||||
**build.ts:**
|
||||
```typescript
|
||||
const DEFAULT_BUILD_FEATURES = [
|
||||
"AGENT_TRIGGERS_REMOTE", "CHICAGO_MCP", "VOICE_MODE",
|
||||
"SHOT_STATS", "PROMPT_CACHE_BREAK_DETECTION", "TOKEN_BUDGET"
|
||||
];
|
||||
```
|
||||
|
||||
**scripts/dev.ts:**
|
||||
```typescript
|
||||
const DEFAULT_FEATURES = [
|
||||
"BUDDY", "TRANSCRIPT_CLASSIFIER", "BRIDGE_MODE",
|
||||
"AGENT_TRIGGERS_REMOTE", "CHICAGO_MCP", "VOICE_MODE",
|
||||
"SHOT_STATS", "PROMPT_CACHE_BREAK_DETECTION", "TOKEN_BUDGET"
|
||||
];
|
||||
```
|
||||
|
||||
### 验证结果
|
||||
|
||||
| 项目 | 结果 |
|
||||
|------|------|
|
||||
| `bun run build` | ✅ 成功 (475 files) |
|
||||
| `bun test` | ✅ 无新增失败 (23 fail 为已有问题) |
|
||||
| SHOT_STATS 代码路径 | ✅ 完整 — stats 面板显示 shot 分布 |
|
||||
| TOKEN_BUDGET 代码路径 | ✅ 完整 — 支持 `+500k` 语法，带进度条 |
|
||||
| PROMPT_CACHE_BREAK_DETECTION 代码路径 | ✅ 完整 — 内部诊断，debug 模式可见 |
|
||||
@@ -1,195 +0,0 @@
|
||||
# FORK_SUBAGENT — 上下文继承子 Agent
|
||||
|
||||
> Feature Flag: `FEATURE_FORK_SUBAGENT=1`
|
||||
> 实现状态：完整可用
|
||||
> 引用数：4
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
FORK_SUBAGENT 让 AgentTool 生成"fork 子 agent"，继承父级完整对话上下文。子 agent 看到父级的所有历史消息、工具集和系统提示，并且与父级共享 API 请求前缀以最大化 prompt cache 命中率。
|
||||
|
||||
### 核心优势
|
||||
|
||||
- **Prompt Cache 最大化**：多个并行 fork 共享相同的 API 请求前缀，只有最后的 directive 文本块不同
|
||||
- **上下文完整性**：子 agent 继承父级的完整对话历史（包括 thinking config）
|
||||
- **权限冒泡**：子 agent 的权限提示上浮到父级终端显示
|
||||
- **Worktree 隔离**：支持 git worktree 隔离，子 agent 在独立分支工作
|
||||
|
||||
## 二、用户交互
|
||||
|
||||
### 触发方式
|
||||
|
||||
当 `FORK_SUBAGENT` 启用时，AgentTool 调用不指定 `subagent_type` 时自动走 fork 路径：
|
||||
|
||||
```
|
||||
// Fork 路径（继承上下文）
|
||||
Agent({ prompt: "修复这个 bug" }) // 无 subagent_type
|
||||
|
||||
// 普通 agent 路径（全新上下文）
|
||||
Agent({ subagent_type: "general-purpose", prompt: "..." })
|
||||
```
|
||||
|
||||
### /fork 命令
|
||||
|
||||
注册了 `/fork` 斜杠命令（当前为 stub）。当 FORK_SUBAGENT 开启时，`/branch` 命令失去 `fork` 别名，避免冲突。
|
||||
|
||||
## 三、实现架构
|
||||
|
||||
### 3.1 门控与互斥
|
||||
|
||||
文件：`src/tools/AgentTool/forkSubagent.ts:32-39`
|
||||
|
||||
```ts
|
||||
export function isForkSubagentEnabled(): boolean {
|
||||
if (feature('FORK_SUBAGENT')) {
|
||||
if (isCoordinatorMode()) return false // Coordinator 有自己的委派模型
|
||||
if (getIsNonInteractiveSession()) return false // pipe/SDK 模式禁用
|
||||
return true
|
||||
}
|
||||
return false
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 FORK_AGENT 定义
|
||||
|
||||
```ts
|
||||
export const FORK_AGENT = {
|
||||
agentType: 'fork',
|
||||
tools: ['*'], // 通配符：使用父级完整工具集
|
||||
maxTurns: 200,
|
||||
model: 'inherit', // 继承父级模型
|
||||
permissionMode: 'bubble', // 权限冒泡到父级终端
|
||||
getSystemPrompt: () => '', // 不使用：直接传递父级已渲染 prompt
|
||||
}
|
||||
```
|
||||
|
||||
### 3.3 核心调用流程
|
||||
|
||||
```
|
||||
AgentTool.call({ prompt, name })
|
||||
│
|
||||
▼
|
||||
isForkSubagentEnabled() && !subagent_type?
|
||||
│
|
||||
├── No → 普通 agent 路径
|
||||
│
|
||||
└── Yes → Fork 路径
|
||||
│
|
||||
▼
|
||||
递归防护检查
|
||||
├── querySource === 'agent:builtin:fork' → 拒绝
|
||||
└── isInForkChild(messages) → 拒绝
|
||||
│
|
||||
▼
|
||||
获取父级 system prompt
|
||||
├── toolUseContext.renderedSystemPrompt（首选）
|
||||
└── buildEffectiveSystemPrompt（回退）
|
||||
│
|
||||
▼
|
||||
buildForkedMessages(prompt, assistantMessage)
|
||||
├── 克隆父级 assistant 消息
|
||||
├── 生成占位符 tool_result
|
||||
└── 附加 directive 文本块
|
||||
│
|
||||
▼
|
||||
[可选] buildWorktreeNotice()
|
||||
│
|
||||
▼
|
||||
runAgent({
|
||||
useExactTools: true,
|
||||
override.systemPrompt: 父级,
|
||||
forkContextMessages: 父级消息,
|
||||
availableTools: 父级工具,
|
||||
})
|
||||
```
|
||||
|
||||
### 3.4 消息构建：buildForkedMessages
|
||||
|
||||
文件：`src/tools/AgentTool/forkSubagent.ts:107-169`
|
||||
|
||||
构建的消息结构：
|
||||
|
||||
```
|
||||
[
|
||||
...history (filterIncompleteToolCalls), // 父级完整历史
|
||||
assistant(所有 tool_use 块), // 父级当前 turn 的 assistant 消息
|
||||
user(
|
||||
占位符 tool_result × N + // 相同占位符文本
|
||||
<fork-boilerplate> directive // 每个 fork 不同
|
||||
)
|
||||
]
|
||||
```
|
||||
|
||||
**所有 fork 使用相同的占位符文本**：`"Fork started — processing in background"`。这确保多个并行 fork 的 API 请求前缀完全一致，最大化 prompt cache 命中。
|
||||
|
||||
### 3.5 递归防护
|
||||
|
||||
两层检查防止 fork 嵌套：
|
||||
|
||||
1. **querySource 检查**：`toolUseContext.options.querySource === 'agent:builtin:fork'`。在 `context.options` 上设置，抗自动压缩（autocompact 只重写消息不改 options）
|
||||
2. **消息扫描**：`isInForkChild()` 扫描消息历史中的 `<fork-boilerplate>` 标签
|
||||
|
||||
### 3.6 Worktree 隔离通知
|
||||
|
||||
当 fork + worktree 组合时，追加通知告知子 agent：
|
||||
|
||||
> "你继承了父 agent 在 `{parentCwd}` 的对话上下文，但你在独立的 git worktree `{worktreeCwd}` 中操作。路径需要转换，编辑前重新读取。"
|
||||
|
||||
### 3.7 强制异步
|
||||
|
||||
当 `isForkSubagentEnabled()` 为 true 时，所有 agent 启动都强制异步。`run_in_background` 参数从 schema 中移除。统一通过 `<task-notification>` XML 消息交互。
|
||||
|
||||
## 四、Prompt Cache 优化
|
||||
|
||||
这是整个 fork 设计的核心优化目标：
|
||||
|
||||
| 优化点 | 实现 |
|
||||
|--------|------|
|
||||
| **相同 system prompt** | 直传 `renderedSystemPrompt`，避免重新渲染（GrowthBook 状态可能不一致） |
|
||||
| **相同工具集** | `useExactTools: true` 直接使用父级工具，不经过 `resolveAgentTools` 过滤 |
|
||||
| **相同 thinking config** | 继承父级 thinking 配置（非 fork agent 默认禁用 thinking） |
|
||||
| **相同占位符结果** | 所有 fork 使用 `FORK_PLACEHOLDER_RESULT` 相同文本 |
|
||||
| **ContentReplacementState 克隆** | 默认克隆父级替换状态，保持 wire prefix 一致 |
|
||||
|
||||
## 五、子 Agent 指令
|
||||
|
||||
`buildChildMessage()` 生成 `<fork-boilerplate>` 包裹的指令：
|
||||
|
||||
- 你是 fork worker，不是主 agent
|
||||
- 禁止再次 spawn sub-agent（直接执行）
|
||||
- 不要闲聊、不要元评论
|
||||
- 直接使用工具
|
||||
- 修改文件后要 commit，报告 commit hash
|
||||
- 报告格式：`Scope:` / `Result:` / `Key files:` / `Files changed:` / `Issues:`
|
||||
|
||||
## 六、关键设计决策
|
||||
|
||||
1. **Fork ≠ 普通 agent**：fork 继承完整上下文，普通 agent 从零开始。选择依据是 `subagent_type` 是否存在
|
||||
2. **renderedSystemPrompt 直传**：避免 fork 时重新调用 `getSystemPrompt()`。父级在 turn 开始时冻结 prompt 字节
|
||||
3. **占位符结果共享**：多个并行 fork 使用完全相同的占位符，只有 directive 不同
|
||||
4. **Coordinator 互斥**：Coordinator 模式下禁用 fork，两者有不兼容的委派模型
|
||||
5. **非交互式禁用**：pipe 模式和 SDK 模式下禁用，避免不可见的 fork 嵌套
|
||||
|
||||
## 七、使用方式
|
||||
|
||||
```bash
|
||||
# 启用 feature
|
||||
FEATURE_FORK_SUBAGENT=1 bun run dev
|
||||
|
||||
# 在 REPL 中使用（不指定 subagent_type 即走 fork）
|
||||
# Agent({ prompt: "研究这个模块的结构" })
|
||||
# Agent({ prompt: "实现这个功能" })
|
||||
```
|
||||
|
||||
## 八、文件索引
|
||||
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
| `src/tools/AgentTool/forkSubagent.ts` | ~210 | 核心定义 + 消息构建 + 递归防护 |
|
||||
| `src/tools/AgentTool/AgentTool.tsx` | — | Fork 路由 + 强制异步 |
|
||||
| `src/tools/AgentTool/prompt.ts` | — | "When to Fork" 提示词段落 |
|
||||
| `src/tools/AgentTool/runAgent.ts` | — | useExactTools 路径 |
|
||||
| `src/tools/AgentTool/resumeAgent.ts` | — | Fork agent 恢复 |
|
||||
| `src/constants/xml.ts` | — | XML 标签常量 |
|
||||
| `src/utils/forkedAgent.ts` | — | CacheSafeParams + ContentReplacementState 克隆 |
|
||||
| `src/commands/fork/index.ts` | — | /fork 命令（stub） |
|
||||
@@ -1,334 +0,0 @@
|
||||
# GrowthBook 功能启用计划
|
||||
|
||||
> 编制日期: 2026-04-06
|
||||
> 基于: feature-flags-codex-review.md + 4 个并行研究代理的深度分析
|
||||
> 前提: 我们是付费订阅用户，拥有有效的 Anthropic API key
|
||||
|
||||
---
|
||||
|
||||
## 背景
|
||||
|
||||
Claude Code 使用三层门控系统：
|
||||
1. **编译时 feature flag** — `feature('FLAG_NAME')` from `bun:bundle`
|
||||
2. **GrowthBook 远程开关** — `tengu_*` 前缀，通过 SDK 连接 Anthropic 服务端
|
||||
3. **运行时环境变量** — `USER_TYPE`、`CLAUDE_CODE_*` 等
|
||||
|
||||
在我们的反编译版本中，GrowthBook 不启动（analytics 链空实现），导致所有 `tengu_*` 检查默认返回 `false`。
|
||||
|
||||
**核心发现：所有被 GrowthBook 门控的功能代码都是真实现，没有 stub。**
|
||||
|
||||
---
|
||||
|
||||
## 启用方式说明
|
||||
|
||||
### 方式 1：硬编码绕过（推荐先用）
|
||||
在 `src/services/analytics/growthbook.ts` 的 `getFeatureValueInternal()` 函数中添加默认值映射。
|
||||
|
||||
### 方式 2：自建 GrowthBook 服务器
|
||||
```bash
|
||||
docker run -p 3100:3100 growthbook/growthbook
|
||||
# 设置环境变量
|
||||
CLAUDE_GB_ADAPTER_URL=http://localhost:3100
|
||||
CLAUDE_GB_ADAPTER_KEY=sdk-xxx
|
||||
```
|
||||
|
||||
### 方式 3：恢复原生 1P 连接
|
||||
让 `is1PEventLoggingEnabled()` 返回 `true`，连接 Anthropic 的 GrowthBook 服务端。
|
||||
注意：会发送使用统计（不含代码/对话内容）。
|
||||
|
||||
---
|
||||
|
||||
## 优先级 P0：纯本地功能（零外部依赖，立即可用）
|
||||
|
||||
这些功能不需要 API 调用，开启 gate 即可工作。
|
||||
|
||||
### P0-1. 自定义快捷键
|
||||
- **Gate**: `tengu_keybinding_customization_release` → `true`
|
||||
- **编译 flag**: 无（已内置）
|
||||
- **代码量**: 473 行，完整实现
|
||||
- **功能**: 加载 `~/.claude/keybindings.json`，支持热重载、重复键检测、结构验证
|
||||
- **效果**: 用户可自定义所有快捷键
|
||||
- **风险**: 无
|
||||
|
||||
### P0-2. 流式工具执行
|
||||
- **Gate**: `tengu_streaming_tool_execution2` → `true`
|
||||
- **编译 flag**: 无（已内置）
|
||||
- **代码量**: 577 行（StreamingToolExecutor），完整实现
|
||||
- **功能**: API 响应还在流式返回时就开始执行工具，减少等待时间
|
||||
- **效果**: 显著提升交互速度
|
||||
- **风险**: 低（生产级代码，有错误处理）
|
||||
|
||||
### P0-3. 定时任务系统
|
||||
- **Gate**: `tengu_kairos_cron` → `true`（额外：`tengu_kairos_cron_durable` 默认 `true`）
|
||||
- **编译 flag**: `AGENT_TRIGGERS`（需新增）或 `AGENT_TRIGGERS_REMOTE`（已启用）
|
||||
- **代码量**: 1025 行（cronTasks + cronScheduler），完整实现
|
||||
- **功能**: 本地 cron 调度，支持一次性/周期性任务、防雷群效应 jitter、自动过期
|
||||
- **效果**: 可设置定时执行的 Claude 任务
|
||||
- **风险**: 低
|
||||
|
||||
### P0-4. Agent 团队 / Swarm
|
||||
- **Gate**: `tengu_amber_flint` → `true`（这是 kill switch，默认已 `true`）
|
||||
- **编译 flag**: 无（已内置）
|
||||
- **代码量**: 45 行（gate 层），实际 swarm 实现在 teammate tools 中
|
||||
- **功能**: 多 agent 协作，需额外设置 `--agent-teams` 或 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
|
||||
- **效果**: 允许创建和管理 agent 团队
|
||||
- **风险**: 无（kill switch 默认就是 true）
|
||||
|
||||
### P0-5. Token 高效 JSON 工具格式
|
||||
- **Gate**: `tengu_amber_json_tools` → `true`
|
||||
- **编译 flag**: 无（已内置）
|
||||
- **代码量**: betas.ts 中几行 gate 检查
|
||||
- **功能**: 启用 FC v3 格式，减少约 4.5% 的输出 token
|
||||
- **效果**: 省钱
|
||||
- **风险**: 低（需要模型支持该 beta header）
|
||||
|
||||
### P0-6. Ultrathink 扩展思考
|
||||
- **Gate**: `tengu_turtle_carbon` → `true`（默认已 `true`，kill switch）
|
||||
- **编译 flag**: 无
|
||||
- **功能**: 通过关键词触发扩展思考模式
|
||||
- **效果**: 已默认启用，确保不被远程关闭即可
|
||||
- **风险**: 无
|
||||
|
||||
### P0-7. 即时模型切换
|
||||
- **Gate**: `tengu_immediate_model_command` → `true`
|
||||
- **编译 flag**: 无
|
||||
- **功能**: 在 query 运行过程中即时执行 `/model`、`/fast`、`/effort` 命令
|
||||
- **效果**: 无需等当前任务完成就能切换
|
||||
- **风险**: 低
|
||||
|
||||
---
|
||||
|
||||
## 优先级 P1：需要 Claude API 的功能（有 API key 即可用）
|
||||
|
||||
这些功能需要调用 Claude API（使用 forked subagent 或 queryModel），有订阅即可。
|
||||
|
||||
### P1-1. 会话记忆
|
||||
- **Gate**: `tengu_session_memory` → `true`（配置：`tengu_sm_config` → `{}`）
|
||||
- **编译 flag**: 无（已内置）
|
||||
- **代码量**: 1127 行，完整实现
|
||||
- **功能**: 跨会话上下文持久化。用 forked agent 定期提取会话笔记到 markdown 文件
|
||||
- **效果**: Claude 记住跨会话的工作上下文
|
||||
- **依赖**: Claude API（forked subagent）
|
||||
- **风险**: 低（额外 API token 消耗）
|
||||
|
||||
### P1-2. 自动记忆提取
|
||||
- **Gate**: `tengu_passport_quail` → `true`（相关：`tengu_moth_copse`、`tengu_coral_fern`）
|
||||
- **编译 flag**: `EXTRACT_MEMORIES`（需新增）
|
||||
- **代码量**: 616 行，完整实现
|
||||
- **功能**: 对话中自动提取持久记忆到 `~/.claude/projects/<path>/memory/`
|
||||
- **效果**: 自动构建项目知识库
|
||||
- **依赖**: Claude API（forked subagent）
|
||||
- **风险**: 低
|
||||
|
||||
### P1-3. 提示建议
|
||||
- **Gate**: `tengu_chomp_inflection` → `true`
|
||||
- **编译 flag**: 无（已内置）
|
||||
- **代码量**: 525 行，完整实现
|
||||
- **功能**: 自动生成下一步操作建议，带投机预取（speculation prefetch）
|
||||
- **效果**: 更流畅的交互体验
|
||||
- **依赖**: Claude API（forked subagent）
|
||||
- **风险**: 低（额外 API 消耗，但有缓存感知）
|
||||
|
||||
### P1-4. 验证代理
|
||||
- **Gate**: `tengu_hive_evidence` → `true`
|
||||
- **编译 flag**: `VERIFICATION_AGENT`（需新增）
|
||||
- **代码量**: 153 行（agent 定义），完整实现
|
||||
- **功能**: 对抗性验证 agent，主动尝试打破你的实现（只读模式）
|
||||
- **效果**: 自动化代码验证
|
||||
- **依赖**: Claude API（subagent）
|
||||
- **风险**: 低（只读，不修改代码）
|
||||
|
||||
### P1-5. Brief 模式
|
||||
- **Gate**: `tengu_kairos_brief` → `true`
|
||||
- **编译 flag**: `KAIROS` 或 `KAIROS_BRIEF`（需新增）
|
||||
- **代码量**: 335 行，完整实现
|
||||
- **功能**: `/brief` 命令切换精简输出模式
|
||||
- **效果**: 减少冗余输出
|
||||
- **依赖**: Claude API
|
||||
- **风险**: 低
|
||||
|
||||
### P1-6. 离开摘要
|
||||
- **Gate**: `tengu_sedge_lantern` → `true`
|
||||
- **编译 flag**: `AWAY_SUMMARY`（需新增）
|
||||
- **代码量**: 176 行，完整实现
|
||||
- **功能**: 离开终端 5 分钟后返回时自动总结期间发生了什么
|
||||
- **效果**: 快速恢复上下文
|
||||
- **依赖**: Claude API + 终端焦点事件支持
|
||||
- **风险**: 低
|
||||
|
||||
### P1-7. 自动梦境
|
||||
- **Gate**: `tengu_onyx_plover` → `{"enabled": true}`
|
||||
- **编译 flag**: 无（已内置，但检查 auto-memory 是否启用）
|
||||
- **代码量**: 349 行，完整实现
|
||||
- **功能**: 后台自动整理/巩固记忆（等同于自动执行 `/dream`）
|
||||
- **效果**: 记忆自动保持整洁有序
|
||||
- **依赖**: Claude API（forked subagent）+ auto-memory 启用
|
||||
- **风险**: 低
|
||||
|
||||
### P1-8. 空闲返回提示
|
||||
- **Gate**: `tengu_willow_mode` → `"dialog"` 或 `"hint"`
|
||||
- **编译 flag**: 无
|
||||
- **功能**: 对话太大且缓存过期时，提示用户开新会话
|
||||
- **效果**: 避免在过期缓存上浪费 token
|
||||
- **风险**: 无
|
||||
|
||||
---
|
||||
|
||||
## 优先级 P2：增强型功能（提升体验但非必须）
|
||||
|
||||
### P2-1. MCP 指令增量传输
|
||||
- **Gate**: `tengu_basalt_3kr` → `true`
|
||||
- **功能**: 只发送变化的 MCP 指令而非全量
|
||||
- **效果**: 减少 token 消耗
|
||||
- **风险**: 低
|
||||
|
||||
### P2-2. 叶剪枝优化
|
||||
- **Gate**: `tengu_pebble_leaf_prune` → `true`
|
||||
- **功能**: 会话存储中移除死胡同消息分支
|
||||
- **效果**: 减少存储和加载时间
|
||||
- **风险**: 低
|
||||
|
||||
### P2-3. 消息合并
|
||||
- **Gate**: `tengu_chair_sermon` → `true`
|
||||
- **功能**: 合并相邻的 tool_result + text 块
|
||||
- **效果**: 减少 token 消耗
|
||||
- **风险**: 低
|
||||
|
||||
### P2-4. 深度链接
|
||||
- **Gate**: `tengu_lodestone_enabled` → `true`
|
||||
- **功能**: 注册 `claude://` URL 协议处理器
|
||||
- **效果**: 可从浏览器直接打开 Claude Code
|
||||
- **风险**: 低
|
||||
|
||||
### P2-5. Agent 自动转后台
|
||||
- **Gate**: `tengu_auto_background_agents` → `true`
|
||||
- **功能**: Agent 任务运行 120s 后自动转为后台
|
||||
- **效果**: 不再阻塞主交互
|
||||
- **风险**: 低
|
||||
|
||||
### P2-6. 细粒度工具状态
|
||||
- **Gate**: `tengu_fgts` → `true`
|
||||
- **功能**: 系统提示中包含细粒度工具状态信息
|
||||
- **效果**: 模型更好地理解工具可用性
|
||||
- **风险**: 低
|
||||
|
||||
### P2-7. 文件操作 git diff
|
||||
- **Gate**: `tengu_quartz_lantern` → `true`
|
||||
- **功能**: 文件写入/编辑时计算 git diff（仅远程会话）
|
||||
- **效果**: 更好的变更追踪
|
||||
- **风险**: 低
|
||||
|
||||
---
|
||||
|
||||
## 优先级 P3：需要自建服务或 Anthropic OAuth
|
||||
|
||||
### P3-1. 团队记忆
|
||||
- **Gate**: `tengu_herring_clock` → `true`
|
||||
- **编译 flag**: `TEAMMEM`（需新增）
|
||||
- **代码量**: 1180+ 行，完整实现
|
||||
- **功能**: 跨 agent 共享记忆，同步到 Anthropic API
|
||||
- **依赖**: Anthropic OAuth + GitHub remote
|
||||
- **状态**: 需要 Anthropic 的 `/api/claude_code/team_memory` 端点
|
||||
- **可行性**: 除非自建兼容 API，否则无法使用
|
||||
|
||||
### P3-2. 设置同步
|
||||
- **Gate**: `tengu_enable_settings_sync_push` + `tengu_strap_foyer` → `true`
|
||||
- **编译 flag**: `UPLOAD_USER_SETTINGS` / `DOWNLOAD_USER_SETTINGS`（需新增）
|
||||
- **代码量**: 582 行，完整实现
|
||||
- **功能**: 跨设备设置同步
|
||||
- **依赖**: Anthropic OAuth + `/api/claude_code/user_settings`
|
||||
- **可行性**: 同上
|
||||
|
||||
### P3-3. Bridge 远程控制
|
||||
- **Gate**: `tengu_ccr_bridge` → `true`（已有编译 flag `BRIDGE_MODE` dev 模式启用）
|
||||
- **代码量**: 12,619 行，完整实现
|
||||
- **功能**: claude.ai 网页端远程控制 CLI
|
||||
- **依赖**: claude.ai 订阅 + WebSocket 后端
|
||||
- **可行性**: 需要 Anthropic 的 CCR 后端
|
||||
|
||||
### P3-4. 远程定时 Agent
|
||||
- **Gate**: `tengu_surreal_dali` → `true`
|
||||
- **功能**: 创建在远程执行的定时 agent
|
||||
- **依赖**: Anthropic CCR 基础设施
|
||||
- **可行性**: 需要远程服务
|
||||
|
||||
---
|
||||
|
||||
## Kill Switch 清单（确保不被远程关闭）
|
||||
|
||||
这些 gate 默认为 `true`，是 kill switch。应确保它们保持 `true`：
|
||||
|
||||
| Gate | 默认 | 控制什么 |
|
||||
|---|---|---|
|
||||
| `tengu_turtle_carbon` | `true` | Ultrathink 扩展思考 |
|
||||
| `tengu_amber_stoat` | `true` | 内置 Explore/Plan agent |
|
||||
| `tengu_amber_flint` | `true` | Agent 团队/Swarm |
|
||||
| `tengu_slim_subagent_claudemd` | `true` | 子 agent 精简 CLAUDE.md |
|
||||
| `tengu_birch_trellis` | `true` | tree-sitter bash 安全分析 |
|
||||
| `tengu_collage_kaleidoscope` | `true` | macOS 剪贴板图片读取 |
|
||||
| `tengu_compact_cache_prefix` | `true` | 压缩时复用 prompt cache |
|
||||
| `tengu_kairos_cron_durable` | `true` | 持久化 cron 任务 |
|
||||
| `tengu_attribution_header` | `true` | API 请求署名 |
|
||||
| `tengu_slate_prism` | `true` | Agent 进度摘要 |
|
||||
|
||||
---
|
||||
|
||||
## 需要新增的编译 flag
|
||||
|
||||
以下编译时 flag 尚未在 `build.ts` / `scripts/dev.ts` 中启用，但功能代码完整：
|
||||
|
||||
| Flag | 用于 | 优先级 |
|
||||
|---|---|---|
|
||||
| `AGENT_TRIGGERS` | 定时任务系统（P0-3） | P0 |
|
||||
| `EXTRACT_MEMORIES` | 自动记忆提取（P1-2） | P1 |
|
||||
| `VERIFICATION_AGENT` | 验证代理（P1-4） | P1 |
|
||||
| `KAIROS` 或 `KAIROS_BRIEF` | Brief 模式（P1-5） | P1 |
|
||||
| `AWAY_SUMMARY` | 离开摘要（P1-6） | P1 |
|
||||
| `TEAMMEM` | 团队记忆（P3-1） | P3 |
|
||||
|
||||
---
|
||||
|
||||
## 实施路线图
|
||||
|
||||
### Phase 1：硬编码 P0 纯本地 gate（最快见效）
|
||||
1. 在 growthbook.ts 添加默认值映射
|
||||
2. 在 build.ts / dev.ts 添加 `AGENT_TRIGGERS` 编译 flag
|
||||
3. 验证 7 个 P0 功能正常工作
|
||||
4. 预计工作量：1-2 小时
|
||||
|
||||
### Phase 2：启用 P1 API 依赖功能
|
||||
1. 添加编译 flag：`EXTRACT_MEMORIES`、`VERIFICATION_AGENT`、`KAIROS_BRIEF`、`AWAY_SUMMARY`
|
||||
2. 添加 P1 gate 默认值
|
||||
3. 验证 8 个 P1 功能正常工作
|
||||
4. 预计工作量：2-3 小时
|
||||
|
||||
### Phase 3：评估自建 GrowthBook（可选）
|
||||
1. Docker 部署 GrowthBook 服务器
|
||||
2. 迁移硬编码值到 GrowthBook 后台管理
|
||||
3. 获得 Web UI 管理所有 flag 的能力
|
||||
4. 预计工作量：半天
|
||||
|
||||
### Phase 4：评估远程功能（可选）
|
||||
1. 研究是否可以使用 Anthropic OAuth
|
||||
2. 评估团队记忆、设置同步的自建可行性
|
||||
3. 预计工作量：待评估
|
||||
|
||||
---
|
||||
|
||||
## 隐私说明
|
||||
|
||||
### 硬编码绕过（方案 A）
|
||||
- **零数据外发**
|
||||
- GrowthBook SDK 不启动
|
||||
- 完全离线运行
|
||||
|
||||
### 自建 GrowthBook（方案 B）
|
||||
- 数据仅发送到你自己的服务器
|
||||
- Anthropic 无法获取任何数据
|
||||
- 可通过 Web UI 实时管理所有 flag
|
||||
|
||||
### 恢复原生 1P（方案 C）
|
||||
- 会发送使用统计到 `api.anthropic.com`
|
||||
- **不发送**：代码、对话内容、API key
|
||||
- **会发送**：邮箱、设备 ID、机器指纹、仓库哈希、订阅类型
|
||||
- 可用 `DISABLE_TELEMETRY=1` 关闭遥测（但同时关闭 GrowthBook）
|
||||
@@ -1,179 +0,0 @@
|
||||
# KAIROS — 常驻助手模式
|
||||
|
||||
> Feature Flag: `FEATURE_KAIROS=1`（及子 Feature）
|
||||
> 实现状态：核心框架完整，部分子模块为 stub
|
||||
> 引用数：154（全库最大）
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
KAIROS 将 Claude Code CLI 从"问答工具"转变为"常驻助手"。开启后，CLI 持续运行在后台，支持：
|
||||
|
||||
- **持久化 bridge 会话**：跨终端重启复用 session，通过 Anthropic OAuth 连接 claude.ai
|
||||
- **后台执行任务**：用户离开终端时继续工作（配合 PROACTIVE feature）
|
||||
- **推送通知到移动端**：任务完成或需要输入时推送（配合 `KAIROS_PUSH_NOTIFICATION`）
|
||||
- **每日记忆日志**：自动记录和回顾工作内容（配合 `KAIROS_DREAM`）
|
||||
- **外部频道消息接入**：Slack/Discord/Telegram 消息转发到 CLI（配合 `KAIROS_CHANNELS`）
|
||||
- **结构化 Brief 输出**：通过 BriefTool 输出结构化消息（配合 `KAIROS_BRIEF`）
|
||||
|
||||
### 子 Feature 依赖关系
|
||||
|
||||
```
|
||||
KAIROS (主开关)
|
||||
├── KAIROS_BRIEF (BriefTool, 结构化输出)
|
||||
├── KAIROS_CHANNELS (外部频道消息)
|
||||
├── KAIROS_PUSH_NOTIFICATION (移动端推送)
|
||||
├── KAIROS_GITHUB_WEBHOOKS (GitHub PR webhook)
|
||||
└── KAIROS_DREAM (记忆蒸馏)
|
||||
```
|
||||
|
||||
**注意**：PROACTIVE 与 KAIROS 强绑定。所有代码检查都是 `feature('PROACTIVE') || feature('KAIROS')`，即 KAIROS 开启时自动获得 proactive 能力。
|
||||
|
||||
## 二、系统提示
|
||||
|
||||
KAIROS 在系统提示中注入两大段落：
|
||||
|
||||
### 2.1 Brief 段落 (`getBriefSection`)
|
||||
|
||||
文件：`src/constants/prompts.ts:843-858`
|
||||
|
||||
当 `feature('KAIROS') || feature('KAIROS_BRIEF')` 时注入。Brief 工具（`SendUserMessage`）的结构化消息输出指令。`/brief` toggle 和 `--brief` flag 只控制显示过滤，不影响模型行为。
|
||||
|
||||
### 2.2 Proactive/Autonomous Work 段落 (`getProactiveSection`)
|
||||
|
||||
文件：`src/constants/prompts.ts:860-914`
|
||||
|
||||
当 `feature('PROACTIVE') || feature('KAIROS')` 且 `isProactiveActive()` 时注入。核心行为指令：
|
||||
|
||||
- **Tick 驱动**：通过 `<tick_tag>` prompt 保持存活，每个 tick 包含用户当前本地时间
|
||||
- **节奏控制**：使用 `SleepTool` 控制等待间隔（prompt cache 5 分钟过期）
|
||||
- **空操作时必须 Sleep**：禁止输出 "still waiting" 类文本（浪费 turn 和 token）
|
||||
- **偏向行动**：读文件、搜索代码、修改文件、commit — 都不需询问
|
||||
- **终端焦点感知**：`terminalFocus` 字段指示用户是否在看终端
|
||||
- Unfocused → 高度自主行动
|
||||
- Focused → 更协作，展示选择
|
||||
|
||||
## 三、实现架构
|
||||
|
||||
### 3.1 核心模块
|
||||
|
||||
| 模块 | 文件 | 状态 | 职责 |
|
||||
|------|------|------|------|
|
||||
| Assistant 入口 | `src/assistant/index.ts` | Stub | `isAssistantMode()`、`initializeAssistantTeam()` |
|
||||
| Session 发现 | `src/assistant/sessionDiscovery.ts` | Stub | 发现可用 bridge session |
|
||||
| Session 历史 | `src/assistant/sessionHistory.ts` | Stub | 持久化 session 历史 |
|
||||
| Gate 控制 | `src/assistant/gate.ts` | Stub | GrowthBook 门控检查 |
|
||||
| Session 选择器 | `src/assistant/AssistantSessionChooser.ts` | Stub | UI 选择 session |
|
||||
| BriefTool | `src/tools/BriefTool/` | Stub | 结构化消息输出工具 |
|
||||
| Channel Notification | `src/services/mcp/channelNotification.ts` | Stub | 外部频道消息接入 |
|
||||
| Dream Task | `src/components/tasks/src/tasks/DreamTask/` | Stub | 记忆蒸馏任务 |
|
||||
| Memory Directory | `src/memdir/memdir.ts` | Stub | 记忆目录管理 |
|
||||
|
||||
### 3.2 SleepTool（与 Proactive 共享）
|
||||
|
||||
文件：`src/tools/SleepTool/prompt.ts`
|
||||
|
||||
SleepTool 是 KAIROS/Proactive 的节奏控制核心。工具描述让模型理解"休眠"概念：
|
||||
- 工具名：`Sleep`
|
||||
- 功能：等待指定时间后响应 tick prompt
|
||||
- 与 `<tick_tag>` 配合实现心跳式自主工作
|
||||
|
||||
### 3.3 Bridge 集成
|
||||
|
||||
KAIROS 通过 Bridge Mode（`src/bridge/`）连接到 claude.ai 服务器：
|
||||
|
||||
```
|
||||
claude.ai web/app
|
||||
│
|
||||
▼ (HTTPS long-poll)
|
||||
┌──────────────────────┐
|
||||
│ Bridge API Client │ src/bridge/bridgeApi.ts
|
||||
│ (register/poll/ │
|
||||
│ acknowledge) │
|
||||
└──────────┬───────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────┐
|
||||
│ Session Runner │ src/bridge/sessionRunner.ts
|
||||
│ (创建/恢复 REPL) │
|
||||
└──────────┬───────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────┐
|
||||
│ REPL + Proactive │ Tick 驱动自主工作
|
||||
│ Tick Loop │
|
||||
└──────────────────────┘
|
||||
```
|
||||
|
||||
### 3.4 数据流
|
||||
|
||||
```
|
||||
用户从 claude.ai 发送消息
|
||||
│
|
||||
▼
|
||||
Bridge pollForWork() 收到 WorkResponse
|
||||
│
|
||||
▼
|
||||
acknowledgeWork() 确认接收
|
||||
│
|
||||
▼
|
||||
sessionRunner 创建/恢复 REPL session
|
||||
│
|
||||
▼
|
||||
用户消息注入到 REPL 对话
|
||||
│
|
||||
▼
|
||||
模型处理 → 工具调用 → BriefTool 结构化输出
|
||||
│
|
||||
▼
|
||||
结果通过 Bridge API 回传到 claude.ai
|
||||
```
|
||||
|
||||
## 四、关键设计决策
|
||||
|
||||
1. **Tick 驱动而非事件驱动**：模型通过 SleepTool 自行控制唤醒频率，而非外部事件推送。简化架构但增加 API 调用开销
|
||||
2. **KAIROS ⊃ PROACTIVE**：所有 proactive 检查都包含 KAIROS，无需同时开启两个 flag
|
||||
3. **Brief 显示/行为分离**：`/brief` toggle 只控制 UI 过滤，模型始终可以使用 BriefTool
|
||||
4. **Terminal Focus 感知**：模型根据用户是否在看终端自动调节自主程度
|
||||
5. **GrowthBook 门控**：部分功能（如推送通知）即使 feature flag 开启还需要服务端 GrowthBook 开关
|
||||
|
||||
## 五、使用方式
|
||||
|
||||
```bash
|
||||
# 最小启用（常驻助手 + Brief）
|
||||
FEATURE_KAIROS=1 FEATURE_KAIROS_BRIEF=1 bun run dev
|
||||
|
||||
# 全功能启用
|
||||
FEATURE_KAIROS=1 \
|
||||
FEATURE_KAIROS_BRIEF=1 \
|
||||
FEATURE_KAIROS_CHANNELS=1 \
|
||||
FEATURE_KAIROS_PUSH_NOTIFICATION=1 \
|
||||
FEATURE_KAIROS_GITHUB_WEBHOOKS=1 \
|
||||
FEATURE_PROACTIVE=1 \
|
||||
bun run dev
|
||||
|
||||
# 配合 Token Budget 使用
|
||||
FEATURE_KAIROS=1 FEATURE_TOKEN_BUDGET=1 bun run dev
|
||||
```
|
||||
|
||||
## 六、外部依赖
|
||||
|
||||
- **Anthropic OAuth**：必须使用 claude.ai 订阅登录（非 API key）
|
||||
- **GrowthBook**：服务端特性门控（`tengu_ccr_bridge` 等）
|
||||
- **Bridge API**：`/v1/environments/bridge` 系列端点
|
||||
|
||||
## 七、文件索引
|
||||
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
| `src/assistant/index.ts` | 9 | Assistant 模块入口（stub） |
|
||||
| `src/assistant/gate.ts` | — | GrowthBook 门控（stub） |
|
||||
| `src/assistant/sessionDiscovery.ts` | — | Session 发现（stub） |
|
||||
| `src/assistant/sessionHistory.ts` | — | Session 历史（stub） |
|
||||
| `src/assistant/AssistantSessionChooser.ts` | — | Session 选择 UI（stub） |
|
||||
| `src/tools/BriefTool/` | — | BriefTool 实现（stub） |
|
||||
| `src/tools/SleepTool/prompt.ts` | ~30 | SleepTool 工具提示 |
|
||||
| `src/services/mcp/channelNotification.ts` | 5 | 频道消息接入（stub） |
|
||||
| `src/memdir/memdir.ts` | — | 记忆目录管理（stub） |
|
||||
| `src/constants/prompts.ts:552-554,843-914` | 72 | 系统提示注入 |
|
||||
| `src/components/tasks/src/tasks/DreamTask/` | 3 | Dream 任务（stub） |
|
||||
| `src/proactive/index.ts` | — | Proactive 核心（stub，KAIROS 共享） |
|
||||
@@ -1,118 +0,0 @@
|
||||
# MCP_SKILLS — MCP 技能发现
|
||||
|
||||
> Feature Flag: `FEATURE_MCP_SKILLS=1`
|
||||
> 实现状态：功能性实现（config 门控筛选器完整，核心 fetcher 为 stub）
|
||||
> 引用数：9
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
MCP_SKILLS 将 MCP 服务器暴露的资源（`skill://` URI 方案）发现并转换为可调用的技能命令。MCP 服务器可以同时提供 tools、prompts 和 resources；启用此 feature 后，带有 `skill://` URI 的资源被识别为技能。
|
||||
|
||||
### 核心特性
|
||||
|
||||
- **自动发现**：MCP 服务器连接时自动获取 `skill://` 资源
|
||||
- **命令转换**：将 MCP 资源转换为 `prompt` 类型的 Command 对象
|
||||
- **实时刷新**：prompts/resources 列表变化时重新获取技能
|
||||
- **缓存一致性**：连接关闭时清除技能缓存
|
||||
|
||||
## 二、实现架构
|
||||
|
||||
### 2.1 数据流
|
||||
|
||||
```
|
||||
MCP Server 连接
|
||||
│
|
||||
▼
|
||||
client.ts: connectToServer / setupMcpClientConnections
|
||||
├── fetchToolsForClient (MCP tools)
|
||||
├── fetchCommandsForClient (MCP prompts → Command 对象)
|
||||
├── fetchMcpSkillsForClient (MCP skill:// 资源 → Command 对象) [MCP_SKILLS]
|
||||
└── fetchResourcesForClient (MCP resources)
|
||||
│
|
||||
▼
|
||||
commands = [...mcpPrompts, ...mcpSkills]
|
||||
│
|
||||
▼
|
||||
AppState.mcp.commands 更新
|
||||
│
|
||||
▼
|
||||
getMcpSkillCommands() 过滤 → SkillTool 调用
|
||||
```
|
||||
|
||||
### 2.2 技能筛选
|
||||
|
||||
文件：`src/commands.ts:547-558`
|
||||
|
||||
`getMcpSkillCommands(mcpCommands)` 过滤条件：
|
||||
|
||||
```ts
|
||||
cmd.type === 'prompt' // 必须是 prompt 类型
|
||||
cmd.loadedFrom === 'mcp' // 必须来自 MCP 服务器
|
||||
!cmd.disableModelInvocation // 必须可由模型调用
|
||||
feature('MCP_SKILLS') // feature flag 必须开启
|
||||
```
|
||||
|
||||
### 2.3 条件加载
|
||||
|
||||
文件：`src/services/mcp/client.ts:117-121`
|
||||
|
||||
`fetchMcpSkillsForClient` 通过 `require()` 条件加载，feature flag 关闭时不加载任何模块：
|
||||
|
||||
```ts
|
||||
const fetchMcpSkillsForClient = feature('MCP_SKILLS')
|
||||
? require('../../skills/mcpSkills.js').fetchMcpSkillsForClient
|
||||
: null
|
||||
```
|
||||
|
||||
### 2.4 缓存管理
|
||||
|
||||
技能获取函数维护 `.cache`（Map），在以下时机清除：
|
||||
|
||||
| 事件 | 行为 |
|
||||
|------|------|
|
||||
| 连接关闭 | 清除该 client 的技能缓存 |
|
||||
| `disconnectMcpServer()` | 清除技能缓存 |
|
||||
| `prompts/list_changed` 通知 | 刷新 prompts + 并行获取技能 |
|
||||
| `resources/list_changed` 通知 | 刷新 resources + prompts + 技能 |
|
||||
|
||||
### 2.5 集成点
|
||||
|
||||
| 文件 | 行 | 说明 |
|
||||
|------|------|------|
|
||||
| `src/commands.ts` | 547-558, 561-608 | 命令过滤和 SkillTool 命令收集 |
|
||||
| `src/services/mcp/client.ts` | 117-121, 1394, 1672, 2173-2181, 2346-2358 | 技能获取、缓存清除、连接时获取 |
|
||||
| `src/services/mcp/useManageMCPConnections.ts` | 22-26, 682-740 | 实时刷新（prompts/resources 变化） |
|
||||
|
||||
## 三、关键设计决策
|
||||
|
||||
1. **Feature gate 隔离**：`feature('MCP_SKILLS')` 守护条件 `require()` 和所有调用点。关闭时无模块加载、无获取操作
|
||||
2. **资源到技能映射**：技能从 MCP 服务器的 `skill://` URI 资源中发现。`fetchMcpSkillsForClient` 负责转换（当前为 stub）
|
||||
3. **循环依赖避免**：`mcpSkillBuilders.ts` 作为依赖图叶节点，避免 `client.ts ↔ mcpSkills.ts ↔ loadSkillsDir.ts` 循环
|
||||
4. **服务器能力检查**：技能获取还需要 MCP 服务器支持 resources (`!!client.capabilities?.resources`)
|
||||
|
||||
## 四、使用方式
|
||||
|
||||
```bash
|
||||
# 启用 feature
|
||||
FEATURE_MCP_SKILLS=1 bun run dev
|
||||
|
||||
# 前提条件：
|
||||
# 1. 配置了支持 skill:// 资源的 MCP 服务器
|
||||
# 2. MCP 服务器声明了 resources 能力
|
||||
```
|
||||
|
||||
## 五、需要补全的内容
|
||||
|
||||
| 文件 | 状态 | 需要实现 |
|
||||
|------|------|---------|
|
||||
| `src/skills/mcpSkills.ts` | Stub | `fetchMcpSkillsForClient()` — 从 MCP 资源列表中筛选 `skill://` URI 并转换为 Command 对象 |
|
||||
| `src/skills/mcpSkillBuilders.ts` | Stub | 技能构建器注册（避免循环依赖） |
|
||||
|
||||
## 六、文件索引
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `src/commands.ts:547-608` | 技能命令过滤 |
|
||||
| `src/services/mcp/client.ts:117-2358` | 技能获取 + 缓存管理 |
|
||||
| `src/services/mcp/useManageMCPConnections.ts` | 实时刷新 |
|
||||
| `src/skills/mcpSkills.ts` | 核心转换逻辑（stub） |
|
||||
@@ -1,109 +0,0 @@
|
||||
# PROACTIVE — 主动模式
|
||||
|
||||
> Feature Flag: `FEATURE_PROACTIVE=1`（与 `FEATURE_KAIROS=1` 共享功能）
|
||||
> 实现状态：核心模块全部 Stub，布线完整
|
||||
> 引用数：37
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
PROACTIVE 实现 Tick 驱动的自主代理。CLI 在用户不输入时也能持续工作：定时唤醒执行任务，配合 SleepTool 控制节奏。适用于长时间运行的后台任务（等待 CI、监控文件变化、定时检查等）。
|
||||
|
||||
### 与 KAIROS 的关系
|
||||
|
||||
所有代码检查都是 `feature('PROACTIVE') || feature('KAIROS')`，即：
|
||||
- 单独开 `FEATURE_PROACTIVE=1` → 获得 proactive 能力
|
||||
- 单独开 `FEATURE_KAIROS=1` → 自动获得 proactive 能力
|
||||
- 两者都开 → 相同效果（不重复）
|
||||
|
||||
## 二、实现架构
|
||||
|
||||
### 2.1 模块状态
|
||||
|
||||
| 模块 | 文件 | 状态 | 说明 |
|
||||
|------|------|------|------|
|
||||
| 核心逻辑 | `src/proactive/index.ts` | **Stub** | `activateProactive()`、`deactivateProactive()`、`isProactiveActive() => false` |
|
||||
| SleepTool 提示 | `src/tools/SleepTool/prompt.ts` | **完整** | 工具提示定义（工具名：`Sleep`） |
|
||||
| 命令注册 | `src/commands.ts:62-65` | **布线** | 动态加载 `./commands/proactive.js` |
|
||||
| 工具注册 | `src/tools.ts:26-28` | **布线** | SleepTool 动态加载 |
|
||||
| REPL 集成 | `src/screens/REPL.tsx` | **布线** | tick 驱动逻辑、占位符、页脚 UI |
|
||||
| 系统提示 | `src/constants/prompts.ts:860-914` | **完整** | 自主工作行为指令（~55 行详细 prompt） |
|
||||
| 会话存储 | `src/utils/sessionStorage.ts:4892-4912` | **布线** | tick 消息注入对话流 |
|
||||
|
||||
### 2.2 系统提示内容
|
||||
|
||||
`getProactiveSection()` 注入的自主工作指令包含：
|
||||
|
||||
| 章节 | 内容 |
|
||||
|------|------|
|
||||
| Tick 驱动 | `<tick_tag>` prompt 保持存活，包含用户本地时间 |
|
||||
| 节奏控制 | SleepTool 控制等待间隔，prompt cache 5 分钟过期 |
|
||||
| 空操作规则 | 无事可做时**必须**调用 Sleep，禁止输出 "still waiting" |
|
||||
| 首次唤醒 | 简短问候，等待方向（不主动探索） |
|
||||
| 后续唤醒 | 寻找有用工作：调查、验证、检查（不 spam 用户） |
|
||||
| 偏向行动 | 读文件、搜索代码、commit — 不需询问 |
|
||||
| 终端焦点 | `terminalFocus` 字段调节自主程度 |
|
||||
|
||||
### 2.3 数据流
|
||||
|
||||
```
|
||||
activateProactive() [需要实现]
|
||||
│
|
||||
▼
|
||||
Tick 调度器启动
|
||||
│
|
||||
├── 定时生成 <tick_tag> 消息
|
||||
│ ├── 包含用户当前本地时间
|
||||
│ └── 注入到对话流（sessionStorage）
|
||||
│
|
||||
▼
|
||||
模型处理 tick
|
||||
│
|
||||
├── 有事可做 → 使用工具执行 → 可能再次 Sleep
|
||||
└── 无事可做 → 必须调用 SleepTool
|
||||
│
|
||||
▼
|
||||
SleepTool 等待 [需要实现]
|
||||
│
|
||||
▼
|
||||
下一个 tick 到达
|
||||
```
|
||||
|
||||
## 三、需要补全的内容
|
||||
|
||||
| 优先级 | 模块 | 工作量 | 说明 |
|
||||
|--------|------|--------|------|
|
||||
| 1 | `src/proactive/index.ts` | 中 | Tick 调度器、activate/deactivate 状态机、pause/resume |
|
||||
| 2 | `src/tools/SleepTool/SleepTool.ts` | 小 | 工具执行（等待指定时间后触发 tick） |
|
||||
| 3 | `src/commands/proactive.js` | 小 | `/proactive` 斜杠命令处理器 |
|
||||
| 4 | `src/hooks/useProactive.ts` | 中 | React hook（REPL 引用但不存在） |
|
||||
|
||||
## 四、关键设计决策
|
||||
|
||||
1. **Tick 驱动**：模型通过 SleepTool 自行控制唤醒频率，不是外部事件推送
|
||||
2. **空操作必须 Sleep**：防止 "still waiting" 类空消息浪费 turn 和 token
|
||||
3. **Prompt cache 考量**：SleepTool 提示中提到 cache 5 分钟过期，建议平衡等待时间
|
||||
4. **Terminal Focus 感知**：模型根据用户是否在看终端调整自主程度
|
||||
|
||||
## 五、使用方式
|
||||
|
||||
```bash
|
||||
# 单独启用 proactive
|
||||
FEATURE_PROACTIVE=1 bun run dev
|
||||
|
||||
# 通过 KAIROS 间接启用
|
||||
FEATURE_KAIROS=1 bun run dev
|
||||
|
||||
# 组合使用
|
||||
FEATURE_PROACTIVE=1 FEATURE_KAIROS=1 FEATURE_KAIROS_BRIEF=1 bun run dev
|
||||
```
|
||||
|
||||
## 六、文件索引
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `src/proactive/index.ts` | 核心逻辑（stub） |
|
||||
| `src/tools/SleepTool/prompt.ts` | SleepTool 工具提示 |
|
||||
| `src/constants/prompts.ts:860-914` | 自主工作系统提示 |
|
||||
| `src/screens/REPL.tsx` | REPL tick 集成 |
|
||||
| `src/utils/sessionStorage.ts:4892-4912` | Tick 消息注入 |
|
||||
| `src/components/PromptInput/PromptInputFooterLeftSide.tsx` | 页脚 UI 状态 |
|
||||
@@ -1,167 +0,0 @@
|
||||
# TEAMMEM — 团队共享记忆
|
||||
|
||||
> Feature Flag: `FEATURE_TEAMMEM=1`
|
||||
> 实现状态：完整可用（需要 Anthropic OAuth + GitHub remote）
|
||||
> 引用数：51
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
TEAMMEM 实现基于 GitHub 仓库的团队共享记忆系统。`memory/team/` 目录中的文件双向同步到 Anthropic 服务器，团队所有认证成员可共享项目知识。
|
||||
|
||||
### 核心特性
|
||||
|
||||
- **增量同步**：只上传内容哈希变化的文件（delta upload）
|
||||
- **冲突解决**：基于 ETag 的乐观锁 + 412 冲突重试
|
||||
- **密钥扫描**：上传前检测并跳过包含密钥的文件（PSR M22174）
|
||||
- **路径穿越防护**：所有写入路径验证在 `memory/team/` 边界内
|
||||
- **分批上传**：自动拆分超过 200KB 的 PUT 请求避免网关拒绝
|
||||
|
||||
## 二、用户交互
|
||||
|
||||
### 同步行为
|
||||
|
||||
| 事件 | 行为 |
|
||||
|------|------|
|
||||
| 项目启动 | 自动 pull 团队记忆到 `memory/team/` |
|
||||
| 本地文件编辑 | watcher 检测变更，自动 push |
|
||||
| 服务端更新 | 下次 pull 时覆盖本地（server-wins） |
|
||||
| 密钥检测 | 跳过该文件，记录警告，不阻止其他文件同步 |
|
||||
|
||||
### API 端点
|
||||
|
||||
```
|
||||
GET /api/claude_code/team_memory?repo={owner/repo} → 完整数据 + entryChecksums
|
||||
GET /api/claude_code/team_memory?repo={owner/repo}&view=hashes → 仅 checksums（冲突解决用）
|
||||
PUT /api/claude_code/team_memory?repo={owner/repo} → 上传 entries（upsert 语义）
|
||||
```
|
||||
|
||||
## 三、实现架构
|
||||
|
||||
### 3.1 同步状态
|
||||
|
||||
```ts
|
||||
type SyncState = {
|
||||
lastKnownChecksum: string | null // ETag 条件请求
|
||||
serverChecksums: Map<string, string> // sha256:<hex> 逐文件哈希
|
||||
serverMaxEntries: number | null // 从 413 学习的服务端容量
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 Pull 流程（Server → Local）
|
||||
|
||||
文件：`src/services/teamMemorySync/index.ts:770-867`
|
||||
|
||||
```
|
||||
pullTeamMemory(state)
|
||||
│
|
||||
▼
|
||||
检查 OAuth + GitHub remote
|
||||
│
|
||||
▼
|
||||
fetchTeamMemory(state, repo, etag)
|
||||
├── 304 Not Modified → 返回（无变化）
|
||||
├── 404 → 返回（服务端无数据）
|
||||
└── 200 → 解析 TeamMemoryData
|
||||
│
|
||||
▼
|
||||
刷新 serverChecksums（per-key hashes）
|
||||
│
|
||||
▼
|
||||
writeRemoteEntriesToLocal(entries)
|
||||
├── 路径穿越验证（validateTeamMemKey）
|
||||
├── 文件大小检查（> 250KB 跳过）
|
||||
├── 内容比较（相同则跳过写入）
|
||||
└── 并行写入（Promise.all）
|
||||
```
|
||||
|
||||
### 3.3 Push 流程（Local → Server）
|
||||
|
||||
文件：`src/services/teamMemorySync/index.ts:889-1146`
|
||||
|
||||
```
|
||||
pushTeamMemory(state)
|
||||
│
|
||||
▼
|
||||
readLocalTeamMemory(maxEntries)
|
||||
├── 递归扫描 memory/team/ 目录
|
||||
├── 跳过超大文件（> 250KB）
|
||||
├── 密钥扫描（scanForSecrets，gitleaks 规则）
|
||||
└── 按 serverMaxEntries 截断（如果已知）
|
||||
│
|
||||
▼
|
||||
计算 delta = 本地文件 - serverChecksums
|
||||
（只包含哈希不同的文件）
|
||||
│
|
||||
▼
|
||||
batchDeltaByBytes(delta)
|
||||
（拆分为 ≤200KB 的批次）
|
||||
│
|
||||
▼
|
||||
逐批 uploadTeamMemory(state, repo, batch, etag)
|
||||
├── 200 成功 → 更新 serverChecksums
|
||||
├── 412 冲突 → fetchTeamMemoryHashes() 刷新 checksums
|
||||
│ → 重试 delta 计算（最多 2 次）
|
||||
└── 413 超容量 → 学习 serverMaxEntries
|
||||
```
|
||||
|
||||
### 3.4 密钥扫描
|
||||
|
||||
文件：`src/services/teamMemorySync/secretScanner.ts`
|
||||
|
||||
使用 gitleaks 规则模式扫描文件内容。检测到密钥时：
|
||||
- 跳过该文件（不上传）
|
||||
- 记录 `tengu_team_mem_secret_skipped` 事件（仅记录规则 ID，不记录值）
|
||||
- 不阻止其他文件同步
|
||||
|
||||
### 3.5 文件监视
|
||||
|
||||
文件：`src/services/teamMemorySync/watcher.ts`
|
||||
|
||||
监视 `memory/team/` 目录变更，触发自动 push。抑制由 pull 写入引起的假变更。
|
||||
|
||||
### 3.6 路径安全
|
||||
|
||||
文件：`src/memdir/teamMemPaths.ts`
|
||||
|
||||
- `validateTeamMemKey(relPath)` — 验证相对路径不超出 `memory/team/` 边界
|
||||
- `getTeamMemPath()` — 返回 team memory 根目录路径
|
||||
|
||||
## 四、关键设计决策
|
||||
|
||||
1. **Server-wins on pull, Local-wins on push**：pull 时服务端内容覆盖本地；push 时本地编辑覆盖服务端。本地用户正在编辑，不应被静默丢弃
|
||||
2. **Delta upload**：只上传哈希变化的条目，节省带宽。首次 push 为全量，后续增量
|
||||
3. **分批 PUT**：单次 PUT ≤200KB，避免 API 网关（~256-512KB）拒绝。每批独立 upsert，部分失败不影响已提交批次
|
||||
4. **密钥扫描在上传前**：PSR M22174 要求密钥永不离开本机。扫描在 `readLocalTeamMemory` 中执行，密钥文件不进入上传集
|
||||
5. **ETag 乐观锁**：push 使用 `If-Match` header。412 时 probe `?view=hashes`（只获取 checksums，不下载内容），刷新后重试
|
||||
6. **服务端容量动态学习**：不假设客户端容量上限，从 413 的 `extra_details.max_entries` 学习
|
||||
|
||||
## 五、使用方式
|
||||
|
||||
```bash
|
||||
# 启用 feature
|
||||
FEATURE_TEAMMEM=1 bun run dev
|
||||
|
||||
# 前提条件：
|
||||
# 1. 已通过 Anthropic OAuth 登录
|
||||
# 2. 项目有 GitHub remote（git remote -v 显示 origin）
|
||||
# 3. memory/team/ 目录自动创建
|
||||
```
|
||||
|
||||
## 六、外部依赖
|
||||
|
||||
| 依赖 | 说明 |
|
||||
|------|------|
|
||||
| Anthropic OAuth | first-party 认证 |
|
||||
| GitHub Remote | `getGithubRepo()` 获取 `owner/repo` 作为同步 scope |
|
||||
| Team Memory API | `/api/claude_code/team_memory` 端点 |
|
||||
|
||||
## 七、文件索引
|
||||
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
| `src/services/teamMemorySync/index.ts` | 1257 | 核心同步逻辑（pull/push/sync） |
|
||||
| `src/services/teamMemorySync/watcher.ts` | — | 文件监视 + 自动同步触发 |
|
||||
| `src/services/teamMemorySync/secretScanner.ts` | — | gitleaks 密钥扫描 |
|
||||
| `src/services/teamMemorySync/types.ts` | — | Zod schema + 类型定义 |
|
||||
| `src/services/teamMemorySync/teamMemSecretGuard.ts` | — | 密钥防护辅助 |
|
||||
| `src/memdir/teamMemPaths.ts` | — | 路径验证 + 目录管理 |
|
||||
@@ -1,76 +0,0 @@
|
||||
# Tier 3 — 纯 Stub / N/A 低优先级 Feature 概览
|
||||
|
||||
> 本文档汇总所有 Tier 3 feature。这些功能要么是纯 Stub（所有函数返回空值），
|
||||
> 要么是 Anthropic 内部基础设施（N/A），要么是引用量极低的辅助功能。
|
||||
|
||||
## 概览
|
||||
|
||||
| Feature | 引用 | 状态 | 类别 | 简要说明 |
|
||||
|---------|------|------|------|---------|
|
||||
| CHICAGO_MCP | 16 | N/A | 内部基础设施 | Anthropic 内部 MCP 基础设施，非外部可用 |
|
||||
| UDS_INBOX | 17 | Stub | 消息通信 | Unix 域套接字对等消息，进程间消息传递 |
|
||||
| MONITOR_TOOL | 13 | Stub | 工具 | 文件/进程监控工具，检测变更并通知 |
|
||||
| BG_SESSIONS | 11 | Stub | 会话管理 | 后台会话管理，支持多会话并行 |
|
||||
| SHOT_STATS | 10 | 无实现 | 统计 | 逐 prompt 统计信息收集 |
|
||||
| EXTRACT_MEMORIES | 7 | 无实现 | 记忆 | 自动从对话中提取重要信息作为记忆 |
|
||||
| TEMPLATES | 6 | Stub | 项目管理 | 项目/提示模板系统 |
|
||||
| LODESTONE | 6 | N/A | 内部基础设施 | 内部基础设施模块 |
|
||||
| STREAMLINED_OUTPUT | 1 | — | 输出 | 精简输出模式，减少终端输出量 |
|
||||
| HOOK_PROMPTS | 1 | — | 钩子 | Hook 提示词，自定义钩子的提示注入 |
|
||||
| CCR_AUTO_CONNECT | 3 | — | 远程控制 | CCR 自动连接，自动建立远程控制会话 |
|
||||
| CCR_MIRROR | 4 | — | 远程控制 | CCR 镜像模式，会话状态同步 |
|
||||
| CCR_REMOTE_SETUP | 1 | — | 远程控制 | CCR 远程设置，初始化远程控制配置 |
|
||||
| NATIVE_CLIPBOARD_IMAGE | 2 | — | 系统集成 | 原生剪贴板图片，从剪贴板读取图片 |
|
||||
| CONNECTOR_TEXT | 7 | — | 连接器 | 连接器文本，外部系统文本适配 |
|
||||
| COMMIT_ATTRIBUTION | 12 | — | Git | Commit 归因，标记 commit 来源 |
|
||||
| CACHED_MICROCOMPACT | 12 | — | 压缩 | 缓存微压缩，优化 compaction 性能 |
|
||||
| PROMPT_CACHE_BREAK_DETECTION | 9 | — | 性能 | Prompt cache 中断检测，监控 cache miss |
|
||||
| MEMORY_SHAPE_TELEMETRY | 3 | — | 遥测 | 记忆形态遥测，记忆使用模式追踪 |
|
||||
| MCP_RICH_OUTPUT | 3 | — | MCP | MCP 富输出，增强 MCP 工具输出格式 |
|
||||
| FILE_PERSISTENCE | 3 | — | 持久化 | 文件持久化，跨会话保持状态 |
|
||||
| TREE_SITTER_BASH_SHADOW | 5 | Shadow | 安全 | Bash AST Shadow 模式（见 tree-sitter-bash.md） |
|
||||
| QUICK_SEARCH | 5 | — | 搜索 | 快速搜索，优化的文件/内容搜索 |
|
||||
| MESSAGE_ACTIONS | 5 | — | UI | 消息操作，对消息执行后处理动作 |
|
||||
| DOWNLOAD_USER_SETTINGS | 5 | — | 配置 | 下载用户设置，从服务端同步配置 |
|
||||
| DIRECT_CONNECT | 5 | — | 网络 | 直连模式，绕过代理直接连接 API |
|
||||
| VERIFICATION_AGENT | 4 | — | Agent | 验证 Agent，专门用于验证代码变更 |
|
||||
| TERMINAL_PANEL | 4 | — | UI | 终端面板，嵌入式终端输出显示 |
|
||||
| SSH_REMOTE | 4 | — | 远程 | SSH 远程，通过 SSH 连接远程 Claude |
|
||||
| REVIEW_ARTIFACT | 4 | — | 审查 | Review Artifact，代码审查产出物 |
|
||||
| REACTIVE_COMPACT | 4 | — | 压缩 | 响应式压缩，基于上下文变化触发 compaction |
|
||||
| HISTORY_PICKER | 4 | — | UI | 历史选择器，浏览和选择历史对话 |
|
||||
| UPLOAD_USER_SETTINGS | 2 | — | 配置 | 上传用户设置，同步配置到服务端 |
|
||||
| POWERSHELL_AUTO_MODE | 2 | — | 平台 | PowerShell 自动模式，Windows 权限自动化 |
|
||||
| OVERFLOW_TEST_TOOL | 2 | — | 测试 | 溢出测试工具，测试上下文溢出处理 |
|
||||
| NEW_INIT | 2 | — | 初始化 | 新版初始化流程 |
|
||||
| HARD_FAIL | 2 | — | 错误处理 | 硬失败模式，不可恢复错误直接终止 |
|
||||
| ENHANCED_TELEMETRY_BETA | 2 | — | 遥测 | 增强遥测 Beta，详细的性能指标收集 |
|
||||
| COWORKER_TYPE_TELEMETRY | 2 | — | 遥测 | 协作者类型遥测，追踪协作模式 |
|
||||
| BREAK_CACHE_COMMAND | 2 | — | 缓存 | 中断缓存命令，强制刷新 prompt cache |
|
||||
| AWAY_SUMMARY | 2 | — | 摘要 | 离开摘要，用户返回时总结期间工作 |
|
||||
| AUTO_THEME | 2 | — | UI | 自动主题，根据终端设置切换主题 |
|
||||
| ALLOW_TEST_VERSIONS | 2 | — | 版本 | 允许测试版本，跳过版本检查 |
|
||||
| AGENT_TRIGGERS_REMOTE | 2 | — | Agent | Agent 远程触发，从远程触发 Agent 任务 |
|
||||
| AGENT_MEMORY_SNAPSHOT | 2 | — | Agent | Agent 记忆快照，保存/恢复 Agent 状态 |
|
||||
|
||||
## 单引用 Feature（40+ 个）
|
||||
|
||||
以下 feature 各只有 1 处引用，多为内部标记或实验性功能：
|
||||
|
||||
UNATTENDED_RETRY, ULTRATHINK, TORCH, SLOW_OPERATION_LOGGING, SKILL_IMPROVEMENT,
|
||||
SELF_HOSTED_RUNNER, RUN_SKILL_GENERATOR, PERFETTO_TRACING, NATIVE_CLIENT_ATTESTATION,
|
||||
KAIROS_DREAM（见 kairos.md）, IS_LIBC_MUSL, IS_LIBC_GLIBC, DUMP_SYSTEM_PROMPT,
|
||||
COMPACTION_REMINDERS, CCR_REMOTE_SETUP, BYOC_ENVIRONMENT_RUNNER, BUILTIN_EXPLORE_PLAN_AGENTS,
|
||||
BUILDING_CLAUDE_APPS, ANTI_DISTILLATION_CC, AGENT_TRIGGERS, ABLATION_BASELINE
|
||||
|
||||
## 优先级说明
|
||||
|
||||
这些 feature 被列为 Tier 3 的原因：
|
||||
|
||||
1. **内部基础设施**（CHICAGO_MCP, LODESTONE）：Anthropic 内部使用，外部无法运行
|
||||
2. **纯 Stub 且引用低**（UDS_INBOX, MONITOR_TOOL, BG_SESSIONS）：需要大量工作才能实现
|
||||
3. **实验性功能**（SHOT_STATS, EXTRACT_MEMORIES）：尚在概念阶段
|
||||
4. **辅助功能**（STREAMLINED_OUTPUT, HOOK_PROMPTS）：影响范围小
|
||||
5. **CCR 系列**：依赖远程控制基础设施，需要 BRIDGE_MODE 先完善
|
||||
|
||||
如需深入了解某个 Tier 3 feature，可以在代码库中搜索 `feature('FEATURE_NAME')` 查看具体使用场景。
|
||||
@@ -1,198 +0,0 @@
|
||||
# TOKEN_BUDGET — Token 预算自动持续模式
|
||||
|
||||
> Feature Flag: `FEATURE_TOKEN_BUDGET=1`
|
||||
> 实现状态：完整可用
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
TOKEN_BUDGET 让用户在 prompt 中指定一个 output token 预算目标（如 `+500k`、`spend 2M tokens`），Claude 会**自动持续工作**直到达到目标，无需用户反复按回车催促继续。
|
||||
|
||||
适用于大型重构、批量修改、大规模代码生成等需要多轮工具调用的长任务。
|
||||
|
||||
## 二、用户交互
|
||||
|
||||
### 语法
|
||||
|
||||
| 格式 | 示例 | 说明 |
|
||||
|------|------|------|
|
||||
| 简写（开头） | `+500k` | 输入开头直接写 |
|
||||
| 简写（结尾） | `帮我重构这个模块 +2m` | 输入末尾追加 |
|
||||
| 完整语法 | `spend 2M tokens` 或 `use 1B tokens` | 自然语言嵌入 |
|
||||
|
||||
单位支持：`k`（千）、`m`（百万）、`b`（十亿），大小写不敏感。
|
||||
|
||||
### UI 反馈
|
||||
|
||||
- **输入框高亮**：输入包含预算语法时，对应文字会被高亮标记（`PromptInput.tsx` 通过 `findTokenBudgetPositions` 计算）
|
||||
- **Spinner 进度**：底部 spinner 显示实时进度，格式如：
|
||||
- 未完成：`Target: 125,000 / 500,000 (25%) · ~2m 30s`
|
||||
- 已完成：`Target: 510,000 used (500,000 min ✓)`
|
||||
- 包含 ETA（基于当前 token 产出速率计算）
|
||||
|
||||
## 三、实现架构
|
||||
|
||||
### 数据流
|
||||
|
||||
```
|
||||
用户输入 "+500k"
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────┐
|
||||
│ parseTokenBudget() │ src/utils/tokenBudget.ts
|
||||
│ 正则解析 → 500,000 │
|
||||
└────────┬────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────┐
|
||||
│ REPL.tsx │ 提交时调用
|
||||
│ snapshotOutputTokens │ snapshotOutputTokensForTurn(500000)
|
||||
│ ForTurn(500000) │ 记录 turn 起始 token 数 + 预算
|
||||
└────────┬────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────┐
|
||||
│ query.ts 主循环 │ 每轮结束后检查
|
||||
│ checkTokenBudget() │ 当前 output tokens vs 预算
|
||||
└────────┬────────────────┘
|
||||
│
|
||||
┌────┴─────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
continue stop
|
||||
(未达 90%) (已达 90% 或收益递减)
|
||||
│ │
|
||||
▼ ▼
|
||||
注入 nudge 正常结束
|
||||
消息继续 发送完成事件
|
||||
```
|
||||
|
||||
### 核心模块
|
||||
|
||||
#### 1. 解析层 — `src/utils/tokenBudget.ts`
|
||||
|
||||
三个正则表达式解析用户输入：
|
||||
|
||||
```
|
||||
SHORTHAND_START_RE = /^\s*\+(\d+(?:\.\d+)?)\s*(k|m|b)\b/i // "+500k" 在开头
|
||||
SHORTHAND_END_RE = /\s\+(\d+(?:\.\d+)?)\s*(k|m|b)\s*[.!?]?\s*$/i // "+2m" 在结尾
|
||||
VERBOSE_RE = /\b(?:use|spend)\s+(\d+(?:\.\d+)?)\s*(k|m|b)\s*tokens?\b/i // "spend 2M tokens"
|
||||
```
|
||||
|
||||
- `parseTokenBudget(text)` — 提取预算数值，返回 `number | null`
|
||||
- `findTokenBudgetPositions(text)` — 返回匹配位置数组，用于输入框高亮
|
||||
- `getBudgetContinuationMessage(pct, turnTokens, budget)` — 生成继续消息
|
||||
|
||||
#### 2. 状态层 — `src/bootstrap/state.ts`
|
||||
|
||||
模块级单例变量追踪当前 turn 的预算状态：
|
||||
|
||||
```
|
||||
outputTokensAtTurnStart — 本 turn 开始时的累计 output token 数
|
||||
currentTurnTokenBudget — 本 turn 的预算目标（null 表示无预算）
|
||||
budgetContinuationCount — 本 turn 已自动续接的次数
|
||||
```
|
||||
|
||||
关键函数：
|
||||
- `getTotalOutputTokens()` — 从 `STATE.modelUsage` 汇总所有模型的 output tokens
|
||||
- `getTurnOutputTokens()` — `getTotalOutputTokens() - outputTokensAtTurnStart`
|
||||
- `snapshotOutputTokensForTurn(budget)` — 重置 turn 起点，设置新预算
|
||||
- `getCurrentTurnTokenBudget()` — 返回当前预算
|
||||
|
||||
#### 3. 决策层 — `src/query/tokenBudget.ts`
|
||||
|
||||
`checkTokenBudget(tracker, agentId, budget, globalTurnTokens)` 做出 continue/stop 决策：
|
||||
|
||||
**继续条件**：
|
||||
- 不在子 agent 中（`agentId` 为空）
|
||||
- 预算存在且 > 0
|
||||
- 当前 token 未达预算的 **90%**
|
||||
- 非收益递减（连续 3 轮 nudge 后，每轮新增 < 500 tokens）
|
||||
|
||||
**停止条件**：
|
||||
- 达到预算 90%
|
||||
- 收益递减（模型已经"做不动了"）
|
||||
- 子 agent 模式下直接跳过
|
||||
|
||||
**收益递减检测**：`continuationCount >= 3` 且最近两次 nudge 的 delta 都 < 500 tokens。
|
||||
|
||||
#### 4. 主循环集成 — `src/query.ts`
|
||||
|
||||
```
|
||||
query() 函数内：
|
||||
1. 创建 budgetTracker = createBudgetTracker()
|
||||
2. 进入 while 循环
|
||||
3. 每轮结束后调用 checkTokenBudget()
|
||||
4. decision.action === 'continue' 时：
|
||||
- 注入 meta user message（nudge）
|
||||
- continue 回到循环顶部
|
||||
5. decision.action === 'stop' 时：
|
||||
- 记录完成事件（含 diminishingReturns 标记）
|
||||
- 正常返回
|
||||
```
|
||||
|
||||
#### 5. UI 层
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `components/PromptInput/PromptInput.tsx:534` | 输入框中高亮预算语法 |
|
||||
| `components/Spinner.tsx:319-338` | spinner 显示进度百分比 + ETA |
|
||||
| `screens/REPL.tsx:2897` | 提交时解析预算并快照 |
|
||||
| `screens/REPL.tsx:2138` | 用户取消时清除预算 |
|
||||
| `screens/REPL.tsx:2963` | turn 结束时捕获预算信息用于显示 |
|
||||
|
||||
#### 6. 系统提示 — `src/constants/prompts.ts:538-551`
|
||||
|
||||
注入 `token_budget` section：
|
||||
|
||||
> "When the user specifies a token target (e.g., '+500k', 'spend 2M tokens', 'use 1B tokens'), your output token count will be shown each turn. Keep working until you approach the target — plan your work to fill it productively. The target is a hard minimum, not a suggestion. If you stop early, the system will automatically continue you."
|
||||
|
||||
注意：这段 prompt **无条件缓存**（不随预算开关变化），因为 "When the user specifies..." 的措辞在没有预算时是空操作。
|
||||
|
||||
#### 7. API 附件 — `src/utils/attachments.ts:3830-3845`
|
||||
|
||||
每轮 API 调用附带 `output_token_usage` attachment：
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "output_token_usage",
|
||||
"turn": 125000, // 本 turn 产出
|
||||
"session": 350000, // 会话总产出
|
||||
"budget": 500000 // 预算目标
|
||||
}
|
||||
```
|
||||
|
||||
让模型能看到自己的进度。
|
||||
|
||||
## 四、关键设计决策
|
||||
|
||||
1. **90% 阈值而非 100%**：在 `COMPLETION_THRESHOLD = 0.9` 处停止，避免最后一轮 nudge 产生远超预算的 token
|
||||
2. **收益递减保护**：连续 3 轮 nudge 后如果每轮产出 < 500 tokens，判定模型已无实质进展，提前终止
|
||||
3. **子 agent 豁免**：AgentTool 内部的子任务不做预算检查，避免子任务重复触发续接
|
||||
4. **无条件缓存系统提示**：预算 prompt 始终注入（不随预算变化 toggle），避免每次切换预算导致 ~20K token 的 cache miss
|
||||
5. **用户取消清预算**：按 Escape 取消时调用 `snapshotOutputTokensForTurn(null)`，防止残留预算触发续接
|
||||
|
||||
## 五、使用方式
|
||||
|
||||
```bash
|
||||
# 启用 feature
|
||||
FEATURE_TOKEN_BUDGET=1 bun run dev
|
||||
|
||||
# 在 prompt 中使用
|
||||
> +500k 重构所有测试文件
|
||||
> spend 2M tokens 把这个项目从 JS 迁移到 TS
|
||||
> 帮我写完整的 CRUD 模块 +1m
|
||||
```
|
||||
|
||||
## 六、文件索引
|
||||
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
| `src/utils/tokenBudget.ts` | 73 | 正则解析 + 位置查找 + 续接消息生成 |
|
||||
| `src/query/tokenBudget.ts` | 93 | 预算追踪器 + continue/stop 决策 |
|
||||
| `src/bootstrap/state.ts:724-743` | 20 | turn 级 token 快照状态 |
|
||||
| `src/constants/prompts.ts:538-551` | 14 | 系统提示注入 |
|
||||
| `src/utils/attachments.ts:3829-3845` | 17 | API attachment 附加 |
|
||||
| `src/query.ts:280,1311-1358` | 48 | 主循环集成 |
|
||||
| `src/screens/REPL.tsx:2897,2963,2138` | 20 | REPL 提交/完成/取消处理 |
|
||||
| `src/components/Spinner.tsx:319-338` | 20 | 进度条 UI |
|
||||
| `src/components/PromptInput/PromptInput.tsx:534` | 1 | 输入高亮 |
|
||||
@@ -1,161 +0,0 @@
|
||||
# TREE_SITTER_BASH — Bash AST 解析
|
||||
|
||||
> Feature Flag: `FEATURE_TREE_SITTER_BASH=1`
|
||||
> 实现状态：完整可用（纯 TypeScript 实现，~7000+ 行）
|
||||
> 引用数：3
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
TREE_SITTER_BASH 启用一个完整的 Bash AST 解析器，用于安全验证 Bash 命令。它用完整的树遍历安全分析器取代了旧的基于正则表达式的 shell-quote 解析器。关键属性是 **fail-closed**：任何无法识别的内容都被归类为 `too-complex` 并需要用户批准。
|
||||
|
||||
### 关联 Feature
|
||||
|
||||
| Feature | 说明 |
|
||||
|---------|------|
|
||||
| `TREE_SITTER_BASH` | 激活用于权限检查的 AST 解析器 |
|
||||
| `TREE_SITTER_BASH_SHADOW` | Shadow/观测模式：运行解析器但丢弃结果，仅记录遥测 |
|
||||
|
||||
## 二、安全架构
|
||||
|
||||
### 2.1 Fail-Closed 设计
|
||||
|
||||
核心设计使用 **allowlist** 遍历模式：
|
||||
|
||||
- `walkArgument()` 只处理已知安全的节点类型（`word`、`number`、`raw_string`、`string`、`concatenation`、`arithmetic_expansion`、`simple_expansion`）
|
||||
- 任何未知节点类型 → `tooComplex()` → 需要用户批准
|
||||
- 解析器加载但失败（超时/节点预算/panic）→ 返回 `PARSE_ABORTED` 符号（区别于"模块未加载"）
|
||||
|
||||
### 2.2 解析结果
|
||||
|
||||
```ts
|
||||
parseForSecurity(cmd) 返回：
|
||||
{ kind: 'simple', commands: SimpleCommand[] } // 可静态分析
|
||||
{ kind: 'too-complex', reason, nodeType } // 需要用户批准
|
||||
{ kind: 'parse-unavailable' } // 解析器未加载
|
||||
```
|
||||
|
||||
### 2.3 安全检查层次
|
||||
|
||||
```
|
||||
parseForSecurity(cmd)
|
||||
│
|
||||
▼
|
||||
parseCommandRaw(cmd) → AST root node
|
||||
│
|
||||
▼
|
||||
预检查：控制字符、Unicode 空白、反斜杠+空白、
|
||||
zsh ~[ ] 语法、zsh =cmd 展开、大括号+引号混淆
|
||||
│
|
||||
▼
|
||||
walkProgram(root) → collectCommands(root, commands, varScope)
|
||||
│
|
||||
├── 'command' → walkCommand()
|
||||
├── 'pipeline'/'list' → 结构性，递归子节点
|
||||
├── 'for_statement' → 跟踪循环变量为 VAR_PLACEHOLDER
|
||||
├── 'if/while' → 作用域隔离的分支
|
||||
├── 'subshell' → 作用域复制
|
||||
├── 'variable_assignment' → walkVariableAssignment()
|
||||
├── 'declaration_command' → 验证 declare/export flags
|
||||
├── 'test_command' → walk test expressions
|
||||
└── 其他 → tooComplex()
|
||||
│
|
||||
▼
|
||||
checkSemantics(commands)
|
||||
├── EVAL_LIKE_BUILTINS（eval, source, exec, trap...）
|
||||
├── ZSH_DANGEROUS_BUILTINS（zmodload, emulate...）
|
||||
├── SUBSCRIPT_EVAL_FLAGS（test -v, printf -v, read -a）
|
||||
├── Shell keywords as argv[0]（误解析检测）
|
||||
├── /proc/*/environ 访问
|
||||
├── jq system() 和危险 flags
|
||||
└── 包装器剥离（time, nohup, timeout, nice, env, stdbuf）
|
||||
```
|
||||
|
||||
## 三、实现架构
|
||||
|
||||
### 3.1 核心模块
|
||||
|
||||
| 模块 | 文件 | 行数 | 职责 |
|
||||
|------|------|------|------|
|
||||
| 门控入口 | `src/utils/bash/parser.ts` | ~110 | `parseCommand()`、`parseCommandRaw()`、`ensureInitialized()` |
|
||||
| Bash 解析器 | `src/utils/bash/bashParser.ts` | 4437 | 纯 TS 词法分析 + 递归下降解析器 |
|
||||
| 安全分析器 | `src/utils/bash/ast.ts` | 2680 | 树遍历安全分析 + `parseForSecurity()` |
|
||||
| AST 分析辅助 | `src/utils/bash/treeSitterAnalysis.ts` | 507 | 引号上下文、复合结构、危险模式提取 |
|
||||
| 权限检查入口 | `src/tools/BashTool/bashPermissions.ts` | — | 集成 AST 结果到权限决策 |
|
||||
|
||||
### 3.2 Bash 解析器
|
||||
|
||||
文件：`src/utils/bash/bashParser.ts`（4437 行）
|
||||
|
||||
- 纯 TypeScript 实现（无原生依赖）
|
||||
- 生成与 tree-sitter-bash 兼容的 AST
|
||||
- 关键类型：`TsNode`（type、text、startIndex、endIndex、children）
|
||||
- 安全限制：`PARSE_TIMEOUT_MS = 50`、`MAX_NODES = 50_000` — 防止对抗性输入导致 OOM
|
||||
|
||||
### 3.3 安全分析器
|
||||
|
||||
文件：`src/utils/bash/ast.ts`（2680 行）
|
||||
|
||||
核心函数：
|
||||
|
||||
| 函数 | 职责 |
|
||||
|------|------|
|
||||
| `parseForSecurity(cmd)` | 顶层入口，返回 `simple/too-complex/parse-unavailable` |
|
||||
| `parseForSecurityFromAst(cmd, root)` | 接受预解析 AST |
|
||||
| `checkSemantics(commands)` | 后解析语义检查 |
|
||||
| `walkCommand()` | 提取 argv、envVars、redirects |
|
||||
| `walkArgument()` | Allowlist 参数遍历 |
|
||||
| `collectCommands()` | 递归收集所有命令 |
|
||||
|
||||
### 3.4 AST 分析辅助
|
||||
|
||||
文件：`src/utils/bash/treeSitterAnalysis.ts`（507 行）
|
||||
|
||||
| 函数 | 职责 |
|
||||
|------|------|
|
||||
| `extractQuoteContext()` | 识别单引号、双引号、ANSI-C 字符串、heredoc |
|
||||
| `extractCompoundStructure()` | 检测管道、子 shell、命令组 |
|
||||
| `hasActualOperatorNodes()` | 区分真实 `;`/`&&`/`||` 与转义形式 |
|
||||
| `extractDangerousPatterns()` | 检测命令替换、参数展开、heredocs |
|
||||
| `analyzeCommand()` | 单次遍历提取 |
|
||||
|
||||
### 3.5 Shadow 模式
|
||||
|
||||
`TREE_SITTER_BASH_SHADOW` 运行解析器但**从不影响权限决策**：
|
||||
|
||||
```ts
|
||||
// Shadow 模式：记录遥测，然后强制使用旧版路径
|
||||
astResult = { kind: 'parse-unavailable' }
|
||||
astRoot = null
|
||||
// 记录: available, astTooComplex, astSemanticFail, subsDiffer, ...
|
||||
```
|
||||
|
||||
记录 `tengu_tree_sitter_shadow` 事件，包含与旧版 `splitCommand()` 的对比数据。用于在不影响行为的情况下收集遥测。
|
||||
|
||||
## 四、关键设计决策
|
||||
|
||||
1. **Allowlist 遍历**：只处理已知安全的节点类型，未知类型直接 `tooComplex()`
|
||||
2. **PARSE_ABORTED 符号**：区分"解析器未加载"和"解析器加载但失败"。后者阻止回退旧版（旧版缺少 `EVAL_LIKE_BUILTINS` 检查）
|
||||
3. **变量作用域跟踪**：`VAR=value && cmd $VAR` 模式。静态值解析为真实字符串，`$()` 输出使用 `VAR_PLACEHOLDER`
|
||||
4. **PS4/IFS Allowlist**：PS4 赋值使用严格字符白名单 `[A-Za-z0-9 _+:.\/=\[\]-]`，只允许 `${VAR}` 引用
|
||||
5. **包装器剥离**：从 argv 前面剥离 `time/nohup/timeout/nice/env/stdbuf`，未知标志 → fail-closed
|
||||
6. **Shadow 安全性**：Shadow 模式**总是**强制 `astResult = { kind: 'parse-unavailable' }`，绝不影响权限
|
||||
|
||||
## 五、使用方式
|
||||
|
||||
```bash
|
||||
# 激活 AST 解析用于权限检查
|
||||
FEATURE_TREE_SITTER_BASH=1 bun run dev
|
||||
|
||||
# Shadow 模式（仅遥测，不影响行为）
|
||||
FEATURE_TREE_SITTER_BASH_SHADOW=1 bun run dev
|
||||
```
|
||||
|
||||
## 六、文件索引
|
||||
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
| `src/utils/bash/parser.ts` | ~110 | 门控入口点 |
|
||||
| `src/utils/bash/bashParser.ts` | 4437 | 纯 TS bash 解析器 |
|
||||
| `src/utils/bash/ast.ts` | 2680 | 安全分析器（核心） |
|
||||
| `src/utils/bash/treeSitterAnalysis.ts` | 507 | AST 分析辅助 |
|
||||
| `src/tools/BashTool/bashPermissions.ts:1670-1810` | ~140 | 权限集成 + Shadow 遥测 |
|
||||
@@ -1,107 +0,0 @@
|
||||
# ULTRAPLAN — 增强规划
|
||||
|
||||
> Feature Flag: `FEATURE_ULTRAPLAN=1`
|
||||
> 实现状态：关键字检测完整，命令处理完整，CCR 远程会话完整
|
||||
> 引用数：10
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
ULTRAPLAN 在用户输入中检测 "ultraplan" 关键字时，自动进入增强计划模式。相比普通 plan mode，ultraplan 提供更深入的规划能力，支持本地和远程（CCR）执行。
|
||||
|
||||
### 触发方式
|
||||
|
||||
| 方式 | 行为 |
|
||||
|------|------|
|
||||
| 输入含 "ultraplan" 的文本 | 自动重定向到 `/ultraplan` 命令 |
|
||||
| `/ultraplan` 斜杠命令 | 直接执行 |
|
||||
| 彩虹高亮 | 输入框中 "ultraplan" 关键字彩虹动画 |
|
||||
|
||||
## 二、实现架构
|
||||
|
||||
### 2.1 模块状态
|
||||
|
||||
| 模块 | 文件 | 行数 | 状态 |
|
||||
|------|------|------|------|
|
||||
| 命令处理器 | `src/commands/ultraplan.tsx` | 472 | **完整** |
|
||||
| CCR 会话 | `src/utils/ultraplan/ccrSession.ts` | 350 | **完整** |
|
||||
| 关键字检测 | `src/utils/ultraplan/keyword.ts` | 128 | **完整** |
|
||||
| 嵌入式提示 | `src/utils/ultraplan/prompt.txt` | 1 | **完整** |
|
||||
| REPL 对话框 | `src/screens/REPL.tsx` | — | **布线** |
|
||||
| 关键字高亮 | `src/components/PromptInput/PromptInput.tsx` | — | **布线** |
|
||||
|
||||
### 2.2 关键字检测
|
||||
|
||||
文件：`src/utils/ultraplan/keyword.ts`（128 行）
|
||||
|
||||
`findUltraplanTriggerPositions(text)` 智能过滤：
|
||||
- 排除引号内的 "ultraplan"
|
||||
- 排除路径中的 "ultraplan"（如 `/path/to/ultraplan/`）
|
||||
- 排除斜杠命令以外的上下文
|
||||
- `replaceUltraplanKeyword(text)` 清理关键字
|
||||
|
||||
### 2.3 CCR 远程会话
|
||||
|
||||
文件：`src/utils/ultraplan/ccrSession.ts`（350 行）
|
||||
|
||||
`ExitPlanModeScanner` 类实现完整的事件状态机：
|
||||
- `pollForApprovedExitPlanMode()` — 3 秒轮询间隔
|
||||
- 超时处理和重试
|
||||
- 支持远程（teleport）和本地执行
|
||||
|
||||
### 2.4 数据流
|
||||
|
||||
```
|
||||
用户输入 "帮我 ultraplan 重构这个模块"
|
||||
│
|
||||
▼
|
||||
processUserInput 检测 "ultraplan"
|
||||
│
|
||||
▼
|
||||
重定向到 /ultraplan 命令
|
||||
│
|
||||
├── 本地执行 → EnterPlanMode
|
||||
│
|
||||
└── 远程执行 → teleportToRemote → CCR 会话
|
||||
│
|
||||
▼
|
||||
ExitPlanModeScanner 轮询
|
||||
│
|
||||
▼
|
||||
用户在远程审批 → 本地收到结果
|
||||
```
|
||||
|
||||
## 三、需要补全的内容
|
||||
|
||||
| 模块 | 说明 |
|
||||
|------|------|
|
||||
| `src/screens/REPL.tsx` 中的 UltraplanChoiceDialog / UltraplanLaunchDialog | 用户选择本地/远程执行的对话框组件 |
|
||||
| `src/commands/ultraplan/` | 空目录，可能是未合并的子命令结构 |
|
||||
|
||||
## 四、关键设计决策
|
||||
|
||||
1. **智能关键字过滤**：排除引号和路径中的 "ultraplan"，避免误触发
|
||||
2. **本地/远程双模式**：支持本地 plan mode 和 CCR 远程会话
|
||||
3. **彩虹高亮反馈**：输入框中 "ultraplan" 关键字使用彩虹动画，暗示这是特殊功能
|
||||
4. **processUserInput 集成**：在用户输入处理管道中拦截，无缝重定向
|
||||
|
||||
## 五、使用方式
|
||||
|
||||
```bash
|
||||
# 启用 feature
|
||||
FEATURE_ULTRAPLAN=1 bun run dev
|
||||
|
||||
# 在 REPL 中使用
|
||||
# > ultraplan 重构认证模块
|
||||
# > /ultraplan
|
||||
```
|
||||
|
||||
## 六、文件索引
|
||||
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
| `src/commands/ultraplan.tsx` | 472 | 斜杠命令处理器 |
|
||||
| `src/utils/ultraplan/ccrSession.ts` | 350 | CCR 远程会话管理 |
|
||||
| `src/utils/ultraplan/keyword.ts` | 128 | 关键字检测和替换 |
|
||||
| `src/utils/ultraplan/prompt.txt` | 1 | 嵌入式提示 |
|
||||
| `src/utils/processUserInput/processUserInput.ts:468` | — | 关键字重定向 |
|
||||
| `src/components/PromptInput/PromptInput.tsx` | — | 彩虹高亮 |
|
||||
@@ -1,125 +0,0 @@
|
||||
# VOICE_MODE — 语音输入
|
||||
|
||||
> Feature Flag: `FEATURE_VOICE_MODE=1`
|
||||
> 实现状态：完整可用（需要 Anthropic OAuth）
|
||||
> 引用数：46
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
VOICE_MODE 实现"按键说话"（Push-to-Talk）语音输入。用户按住空格键录音，音频通过 WebSocket 流式传输到 Anthropic STT 端点（Nova 3），实时转录显示在终端中。
|
||||
|
||||
### 核心特性
|
||||
|
||||
- **Push-to-Talk**：长按空格键录音，释放后自动发送
|
||||
- **流式转录**：录音过程中实时显示中间转录结果
|
||||
- **无缝集成**：转录文本直接作为用户消息提交到对话
|
||||
|
||||
## 二、用户交互
|
||||
|
||||
| 操作 | 行为 |
|
||||
|------|------|
|
||||
| 长按空格 | 开始录音，显示录音状态 |
|
||||
| 释放空格 | 停止录音，等待最终转录 |
|
||||
| 转录完成 | 自动插入到输入框并提交 |
|
||||
| `/voice` 命令 | 切换语音模式开关 |
|
||||
|
||||
### UI 反馈
|
||||
|
||||
- **录音指示器**：录音时显示红色/脉冲动画
|
||||
- **中间转录**：录音过程中显示 STT 实时识别文本
|
||||
- **最终转录**：完成后替换中间结果
|
||||
|
||||
## 三、实现架构
|
||||
|
||||
### 3.1 门控逻辑
|
||||
|
||||
文件：`src/voice/voiceModeEnabled.ts`
|
||||
|
||||
三层检查：
|
||||
|
||||
```ts
|
||||
isVoiceModeEnabled() = hasVoiceAuth() && isVoiceGrowthBookEnabled()
|
||||
```
|
||||
|
||||
1. **Feature Flag**：`feature('VOICE_MODE')` — 编译时/运行时开关
|
||||
2. **GrowthBook Kill-Switch**：`!getFeatureValue_CACHED_MAY_BE_STALE('tengu_amber_quartz_disabled', false)` — 紧急关闭开关（默认 false = 未禁用）
|
||||
3. **Auth 检查**：`hasVoiceAuth()` — 需要 Anthropic OAuth token（非 API key）
|
||||
|
||||
### 3.2 核心模块
|
||||
|
||||
| 模块 | 职责 |
|
||||
|------|------|
|
||||
| `src/voice/voiceModeEnabled.ts` | Feature flag + GrowthBook + Auth 三层门控 |
|
||||
| `src/hooks/useVoice.ts` | React hook 管理录音状态和 WebSocket 连接 |
|
||||
| `src/services/voiceStreamSTT.ts` | WebSocket 流式传输到 Anthropic STT |
|
||||
|
||||
### 3.3 数据流
|
||||
|
||||
```
|
||||
用户按下空格键
|
||||
│
|
||||
▼
|
||||
useVoice hook 激活
|
||||
│
|
||||
▼
|
||||
macOS 原生音频 / SoX 开始录音
|
||||
│
|
||||
▼
|
||||
WebSocket 连接到 Anthropic STT 端点
|
||||
│
|
||||
├──→ 中间转录结果 → 实时显示
|
||||
│
|
||||
▼
|
||||
用户释放空格键
|
||||
│
|
||||
▼
|
||||
停止录音，等待最终转录
|
||||
│
|
||||
▼
|
||||
转录文本 → 插入输入框 → 自动提交
|
||||
```
|
||||
|
||||
### 3.4 音频录制
|
||||
|
||||
支持两种音频后端：
|
||||
- **macOS 原生音频**：优先使用，低延迟
|
||||
- **SoX（Sound eXchange）**：回退方案，跨平台
|
||||
|
||||
音频流通过 WebSocket 发送到 Anthropic 的 Nova 3 STT 模型。
|
||||
|
||||
## 四、关键设计决策
|
||||
|
||||
1. **OAuth 独占**：语音模式使用 `voice_stream` 端点（claude.ai），仅 Anthropic OAuth 用户可用。API key、Bedrock、Vertex 用户无法使用
|
||||
2. **GrowthBook 负向门控**：`tengu_amber_quartz_disabled` 默认 `false`，新安装自动可用（无需等 GrowthBook 初始化）
|
||||
3. **Keychain 缓存**：`getClaudeAIOAuthTokens()` 首次调用访问 macOS keychain（~20-50ms），后续缓存命中
|
||||
4. **独立于主 feature flag**：`isVoiceGrowthBookEnabled()` 在 feature flag 关闭时短路返回 `false`，不触发任何模块加载
|
||||
|
||||
## 五、使用方式
|
||||
|
||||
```bash
|
||||
# 启用 feature
|
||||
FEATURE_VOICE_MODE=1 bun run dev
|
||||
|
||||
# 在 REPL 中使用
|
||||
# 1. 确保已通过 OAuth 登录（claude.ai 订阅）
|
||||
# 2. 按住空格键说话
|
||||
# 3. 释放空格键等待转录
|
||||
# 4. 或使用 /voice 命令切换开关
|
||||
```
|
||||
|
||||
## 六、外部依赖
|
||||
|
||||
| 依赖 | 说明 |
|
||||
|------|------|
|
||||
| Anthropic OAuth | claude.ai 订阅登录，非 API key |
|
||||
| GrowthBook | `tengu_amber_quartz_disabled` 紧急关闭 |
|
||||
| macOS 原生音频 或 SoX | 音频录制 |
|
||||
| Nova 3 STT | 语音转文本模型 |
|
||||
|
||||
## 七、文件索引
|
||||
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
| `src/voice/voiceModeEnabled.ts` | 55 | 三层门控逻辑 |
|
||||
| `src/hooks/useVoice.ts` | — | React hook（录音状态 + WebSocket） |
|
||||
| `src/services/voiceStreamSTT.ts` | — | STT WebSocket 流式传输 |
|
||||
@@ -1,69 +0,0 @@
|
||||
# WEB_BROWSER_TOOL — 浏览器工具
|
||||
|
||||
> Feature Flag: `FEATURE_WEB_BROWSER_TOOL=1`
|
||||
> 实现状态：核心实现缺失，面板为 Stub，布线完整
|
||||
> 引用数：4
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
WEB_BROWSER_TOOL 让模型可以启动浏览器实例、导航网页、与页面元素交互。使用 Bun 的内置 WebView API 提供无头/有头浏览器能力。
|
||||
|
||||
## 二、实现架构
|
||||
|
||||
### 2.1 模块状态
|
||||
|
||||
| 模块 | 文件 | 状态 |
|
||||
|------|------|------|
|
||||
| 浏览器面板 | `src/tools/WebBrowserTool/WebBrowserPanel.ts` | **Stub** — 返回 null |
|
||||
| 浏览器工具 | `src/tools/WebBrowserTool/WebBrowserTool.ts` | **缺失** |
|
||||
| REPL 集成 | `src/screens/REPL.tsx` | **布线** — 渲染 WebBrowserPanel |
|
||||
| 工具注册 | `src/tools.ts` | **布线** — 动态加载 |
|
||||
| WebView 检测 | `src/main.tsx` | **布线** — `'WebView' in Bun` 检测 |
|
||||
|
||||
### 2.2 预期数据流
|
||||
|
||||
```
|
||||
模型调用 WebBrowserTool
|
||||
│
|
||||
▼
|
||||
Bun WebView 创建浏览器实例
|
||||
│
|
||||
├── navigate(url) — 导航到 URL
|
||||
├── click(selector) — 点击元素
|
||||
├── screenshot() — 截取页面截图
|
||||
└── extract(selector) — 提取页面内容
|
||||
│
|
||||
▼
|
||||
结果返回给模型
|
||||
│
|
||||
▼
|
||||
WebBrowserPanel 在 REPL 侧边显示浏览器状态
|
||||
```
|
||||
|
||||
## 三、需要补全的内容
|
||||
|
||||
| 模块 | 工作量 | 说明 |
|
||||
|------|--------|------|
|
||||
| `WebBrowserTool.ts` | 大 | 工具 schema + Bun WebView API 执行 |
|
||||
| `WebBrowserPanel.tsx` | 中 | REPL 侧边栏浏览器状态面板 |
|
||||
|
||||
## 四、关键设计决策
|
||||
|
||||
1. **Bun WebView API**：使用 Bun 内置的 WebView 而非外部浏览器驱动（Puppeteer/Playwright）
|
||||
2. **REPL 侧边面板**：浏览器状态在 REPL 布局中独立渲染
|
||||
3. **Bun 特性检测**：`'WebView' in Bun` 检查运行时是否支持
|
||||
|
||||
## 五、使用方式
|
||||
|
||||
```bash
|
||||
FEATURE_WEB_BROWSER_TOOL=1 bun run dev
|
||||
```
|
||||
|
||||
## 六、文件索引
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `src/tools/WebBrowserTool/WebBrowserPanel.ts` | 面板组件（stub） |
|
||||
| `src/tools/WebBrowserTool/WebBrowserTool.ts` | 工具实现（缺失） |
|
||||
| `src/screens/REPL.tsx:273,4582` | 面板渲染 |
|
||||
| `src/tools.ts:115-116` | 工具注册 |
|
||||
@@ -1,186 +0,0 @@
|
||||
# WEB_SEARCH_TOOL — 网页搜索工具
|
||||
|
||||
> 实现状态：适配器架构完成，Bing 适配器为当前默认后端
|
||||
> 引用数：核心工具，无 feature flag 门控（始终启用）
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
WebSearchTool 让模型可以搜索互联网获取最新信息。原始实现仅支持 Anthropic API 服务端搜索（`web_search_20250305` server tool），在第三方代理端点下不可用。现已重构为适配器架构，新增 Bing 搜索页面解析作为 fallback，确保任何 API 端点都能使用搜索功能。
|
||||
|
||||
## 二、实现架构
|
||||
|
||||
### 2.1 适配器模式
|
||||
|
||||
```
|
||||
WebSearchTool.call()
|
||||
│
|
||||
▼
|
||||
createAdapter() ← 适配器工厂
|
||||
│
|
||||
├── ApiSearchAdapter — Anthropic 官方 API 服务端搜索
|
||||
│ └── 使用 web_search_20250305 server tool
|
||||
│ 通过 queryModelWithStreaming 二次调用 API
|
||||
│
|
||||
└── BingSearchAdapter — Bing HTML 抓取 + 正则提取（当前默认）
|
||||
└── 直接抓取 Bing 搜索页 HTML
|
||||
正则提取 b_algo 块中的标题/URL/摘要
|
||||
```
|
||||
|
||||
### 2.2 模块结构
|
||||
|
||||
| 模块 | 文件 | 说明 |
|
||||
|------|------|------|
|
||||
| 工具入口 | `src/tools/WebSearchTool/WebSearchTool.ts` | `buildTool()` 定义：schema、权限、执行、输出格式化 |
|
||||
| 工具 prompt | `src/tools/WebSearchTool/prompt.ts` | 搜索工具的系统提示词 |
|
||||
| UI 渲染 | `src/tools/WebSearchTool/UI.tsx` | 搜索结果的终端渲染组件 |
|
||||
| 适配器接口 | `src/tools/WebSearchTool/adapters/types.ts` | `WebSearchAdapter` 接口、`SearchResult`/`SearchOptions`/`SearchProgress` 类型 |
|
||||
| 适配器工厂 | `src/tools/WebSearchTool/adapters/index.ts` | `createAdapter()` 工厂函数，选择后端 |
|
||||
| API 适配器 | `src/tools/WebSearchTool/adapters/apiAdapter.ts` | 封装原有 `queryModelWithStreaming` 逻辑，使用 server tool |
|
||||
| Bing 适配器 | `src/tools/WebSearchTool/adapters/bingAdapter.ts` | Bing HTML 抓取 + 正则解析 |
|
||||
| 单元测试 | `src/tools/WebSearchTool/__tests__/bingAdapter.test.ts` | 32 个测试用例 |
|
||||
| 集成测试 | `src/tools/WebSearchTool/__tests__/bingAdapter.integration.ts` | 真实网络请求验证 |
|
||||
|
||||
### 2.3 数据流
|
||||
|
||||
```
|
||||
模型调用 WebSearchTool(query, allowed_domains, blocked_domains)
|
||||
│
|
||||
▼
|
||||
validateInput() — 校验 query 非空、allowed/block 不共存
|
||||
│
|
||||
▼
|
||||
createAdapter() → BingSearchAdapter（当前硬编码）
|
||||
│
|
||||
▼
|
||||
adapter.search(query, { allowedDomains, blockedDomains, signal, onProgress })
|
||||
│
|
||||
├── onProgress({ type: 'query_update', query })
|
||||
│
|
||||
├── axios.get(bing.com/search?q=...&setmkt=en-US)
|
||||
│ └── 13 个 Edge 浏览器请求头
|
||||
│
|
||||
├── extractBingResults(html) — 正则提取 <li class="b_algo"> 块
|
||||
│ ├── resolveBingUrl() — 解码 base64 重定向 URL
|
||||
│ ├── extractSnippet() — 三级降级摘要提取
|
||||
│ └── decodeHtmlEntities() — he.decode
|
||||
│
|
||||
├── 客户端域名过滤 (allowedDomains / blockedDomains)
|
||||
│
|
||||
├── onProgress({ type: 'search_results_received', resultCount })
|
||||
│
|
||||
▼
|
||||
格式化为 markdown 链接列表返回给模型
|
||||
```
|
||||
|
||||
## 三、Bing 适配器技术细节
|
||||
|
||||
### 3.1 反爬绕过
|
||||
|
||||
使用 13 个 Edge 浏览器请求头（含 `Sec-Ch-Ua`、`Sec-Fetch-*` 等），避免 Bing 返回 JS 渲染的空页面：
|
||||
|
||||
```typescript
|
||||
const BROWSER_HEADERS = {
|
||||
'User-Agent': '...Chrome/131.0.0.0 Safari/537.36 Edg/131.0.0.0',
|
||||
'Sec-Ch-Ua': '"Microsoft Edge";v="131", "Chromium";v="131", ...',
|
||||
'Sec-Fetch-Dest': 'document',
|
||||
'Sec-Fetch-Mode': 'navigate',
|
||||
'Sec-Fetch-Site': 'none',
|
||||
'Sec-Fetch-User': '?1',
|
||||
// ... 共 13 个标头
|
||||
}
|
||||
```
|
||||
|
||||
`setmkt=en-US` 参数强制美式英语市场，避免 IP 地理定位导致区域化结果。
|
||||
|
||||
### 3.2 URL 解码（`resolveBingUrl()`）
|
||||
|
||||
Bing 返回的重定向 URL 格式：`bing.com/ck/a?...&u=a1aHR0cHM6Ly9...`
|
||||
|
||||
- `u` 参数前 2 字符为协议前缀：`a1` = https，`a0` = http
|
||||
- 剩余部分为 base64url 编码的真实 URL
|
||||
- Bing 内部链接和相对路径被过滤返回 `undefined`
|
||||
|
||||
### 3.3 摘要提取（`extractSnippet()`）
|
||||
|
||||
三级降级策略：
|
||||
|
||||
1. `<p class="b_lineclamp...">` — Bing 的搜索摘要段落
|
||||
2. `<div class="b_caption">` 内的 `<p>` — 备选摘要位置
|
||||
3. `<div class="b_caption">` 直接文本 — 最终 fallback
|
||||
|
||||
### 3.4 域名过滤
|
||||
|
||||
客户端侧实现，支持子域名匹配：
|
||||
- `allowedDomains`：白名单，结果域名必须匹配列表中的某项（含子域名）
|
||||
- `blockedDomains`：黑名单，匹配的结果被过滤
|
||||
- 两者不可同时使用（`validateInput` 校验）
|
||||
|
||||
## 四、适配器选择逻辑
|
||||
|
||||
当前 `createAdapter()` 硬编码返回 `BingSearchAdapter`，原逻辑已注释保留：
|
||||
|
||||
```typescript
|
||||
export function createAdapter(): WebSearchAdapter {
|
||||
return new BingSearchAdapter()
|
||||
// 注释保留的选择逻辑：
|
||||
// 1. WEB_SEARCH_ADAPTER 环境变量强制指定 api|bing
|
||||
// 2. isFirstPartyAnthropicBaseUrl() → API 适配器
|
||||
// 3. 第三方端点 → Bing 适配器
|
||||
}
|
||||
```
|
||||
|
||||
恢复自动选择：取消 `index.ts` 中的注释即可。
|
||||
|
||||
## 五、接口定义
|
||||
|
||||
### WebSearchAdapter
|
||||
|
||||
```typescript
|
||||
interface WebSearchAdapter {
|
||||
search(query: string, options: SearchOptions): Promise<SearchResult[]>
|
||||
}
|
||||
|
||||
interface SearchResult {
|
||||
title: string
|
||||
url: string
|
||||
snippet?: string
|
||||
}
|
||||
|
||||
interface SearchOptions {
|
||||
allowedDomains?: string[]
|
||||
blockedDomains?: string[]
|
||||
signal?: AbortSignal
|
||||
onProgress?: (progress: SearchProgress) => void
|
||||
}
|
||||
|
||||
interface SearchProgress {
|
||||
type: 'query_update' | 'search_results_received'
|
||||
query?: string
|
||||
resultCount?: number
|
||||
}
|
||||
```
|
||||
|
||||
### 工具 Input Schema
|
||||
|
||||
```typescript
|
||||
{
|
||||
query: string // 搜索关键词，最少 2 字符
|
||||
allowed_domains?: string[] // 域名白名单
|
||||
blocked_domains?: string[] // 域名黑名单
|
||||
}
|
||||
```
|
||||
|
||||
## 六、文件索引
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `src/tools/WebSearchTool/WebSearchTool.ts` | 工具定义入口 |
|
||||
| `src/tools/WebSearchTool/prompt.ts` | 搜索工具 prompt |
|
||||
| `src/tools/WebSearchTool/UI.tsx` | 终端 UI 渲染 |
|
||||
| `src/tools/WebSearchTool/adapters/types.ts` | 适配器接口 |
|
||||
| `src/tools/WebSearchTool/adapters/index.ts` | 适配器工厂 |
|
||||
| `src/tools/WebSearchTool/adapters/apiAdapter.ts` | API 服务端搜索适配器 |
|
||||
| `src/tools/WebSearchTool/adapters/bingAdapter.ts` | Bing HTML 解析适配器 |
|
||||
| `src/tools/WebSearchTool/__tests__/bingAdapter.test.ts` | 单元测试 (32 cases) |
|
||||
| `src/tools/WebSearchTool/__tests__/bingAdapter.integration.ts` | 集成测试 |
|
||||
| `src/tools.ts` | 工具注册 |
|
||||
@@ -1,105 +0,0 @@
|
||||
# WORKFLOW_SCRIPTS — 工作流自动化
|
||||
|
||||
> Feature Flag: `FEATURE_WORKFLOW_SCRIPTS=1`
|
||||
> 实现状态：全部 Stub（7 个文件），布线完整
|
||||
> 引用数：10
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
WORKFLOW_SCRIPTS 实现基于文件的多步自动化工作流。用户可以定义 YAML/JSON 格式的工作流描述文件，系统将其解析为可执行的多 agent 步骤序列。提供 `/workflows` 命令管理和触发工作流。
|
||||
|
||||
## 二、实现架构
|
||||
|
||||
### 2.1 模块状态
|
||||
|
||||
| 模块 | 文件 | 状态 |
|
||||
|------|------|------|
|
||||
| WorkflowTool | `src/tools/WorkflowTool/WorkflowTool.ts` | **Stub** — 空对象 |
|
||||
| Workflow 权限 | `src/tools/WorkflowTool/WorkflowPermissionRequest.ts` | **Stub** — 返回 null |
|
||||
| 常量 | `src/tools/WorkflowTool/constants.ts` | **Stub** — 空工具名 |
|
||||
| 命令创建 | `src/tools/WorkflowTool/createWorkflowCommand.ts` | **Stub** — 空操作 |
|
||||
| 捆绑工作流 | `src/tools/WorkflowTool/bundled/` | **缺失** — 目录不存在 |
|
||||
| 本地工作流任务 | `src/tasks/LocalWorkflowTask/LocalWorkflowTask.ts` | **Stub** — 类型 + 空操作 |
|
||||
| UI 任务组件 | `src/components/tasks/src/tasks/LocalWorkflowTask/` | **Stub** — 空导出 |
|
||||
| 详情对话框 | `src/components/tasks/WorkflowDetailDialog.ts` | **Stub** — 返回 null |
|
||||
| 任务注册 | `src/tasks.ts` | **布线** — 动态加载 |
|
||||
| 工具注册 | `src/tools.ts` | **布线** — 包含 bundled 工作流初始化 |
|
||||
| 命令注册 | `src/commands.ts` | **布线** — `/workflows` 命令 |
|
||||
|
||||
### 2.2 预期数据流
|
||||
|
||||
```
|
||||
用户定义工作流（YAML/JSON 文件）
|
||||
│
|
||||
▼
|
||||
/workflows 命令发现工作流文件
|
||||
│
|
||||
▼
|
||||
createWorkflowCommand() 解析为 Command 对象 [需要实现]
|
||||
│
|
||||
▼
|
||||
WorkflowTool 执行工作流 [需要实现]
|
||||
│
|
||||
├── 步骤 1: Agent({ task: "..." })
|
||||
├── 步骤 2: Agent({ task: "..." })
|
||||
└── 步骤 N: Agent({ task: "..." })
|
||||
│
|
||||
▼
|
||||
LocalWorkflowTask 协调步骤执行 [需要实现]
|
||||
│
|
||||
▼
|
||||
WorkflowDetailDialog 显示进度 [需要实现]
|
||||
```
|
||||
|
||||
### 2.3 预期工作流 DSL
|
||||
|
||||
```
|
||||
# workflow.yaml（预期格式，需要设计）
|
||||
name: "代码审查工作流"
|
||||
steps:
|
||||
- name: "静态分析"
|
||||
agent: { type: "general-purpose", prompt: "运行 lint 和类型检查" }
|
||||
- name: "测试"
|
||||
agent: { type: "general-purpose", prompt: "运行测试套件" }
|
||||
- name: "综合报告"
|
||||
agent: { type: "general-purpose", prompt: "综合分析结果写报告" }
|
||||
```
|
||||
|
||||
## 三、需要补全的内容
|
||||
|
||||
| 优先级 | 模块 | 工作量 | 说明 |
|
||||
|--------|------|--------|------|
|
||||
| 1 | `WorkflowTool.ts` | 大 | Schema 定义 + 多步执行引擎 |
|
||||
| 2 | `bundled/index.js` | 中 | 内置工作流定义（initBundledWorkflows） |
|
||||
| 3 | `createWorkflowCommand.ts` | 中 | 从文件解析创建命令对象 |
|
||||
| 4 | `LocalWorkflowTask.ts` | 大 | 步骤协调、kill/skip/retry |
|
||||
| 5 | `WorkflowDetailDialog.ts` | 中 | 进度详情 UI |
|
||||
| 6 | `WorkflowPermissionRequest.ts` | 小 | 权限对话框 |
|
||||
| 7 | `constants.ts` | 小 | 工具名常量 |
|
||||
|
||||
## 四、关键设计决策
|
||||
|
||||
1. **基于文件的 DSL**：工作流定义为文件（YAML/JSON），版本控制友好
|
||||
2. **多 Agent 步骤**：每个步骤是独立的 agent 任务，支持并行/串行
|
||||
3. **内置工作流**：`bundled/` 目录提供开箱即用的常用工作流
|
||||
4. **/workflows 命令**：统一的发现和触发入口
|
||||
|
||||
## 五、使用方式
|
||||
|
||||
```bash
|
||||
# 启用 feature（需要补全后才能真正使用）
|
||||
FEATURE_WORKFLOW_SCRIPTS=1 bun run dev
|
||||
```
|
||||
|
||||
## 六、文件索引
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `src/tools/WorkflowTool/WorkflowTool.ts` | 工具定义（stub） |
|
||||
| `src/tools/WorkflowTool/WorkflowPermissionRequest.ts` | 权限对话框（stub） |
|
||||
| `src/tools/WorkflowTool/constants.ts` | 常量（stub） |
|
||||
| `src/tools/WorkflowTool/createWorkflowCommand.ts` | 命令创建（stub） |
|
||||
| `src/tasks/LocalWorkflowTask/LocalWorkflowTask.ts` | 任务协调（stub） |
|
||||
| `src/components/tasks/WorkflowDetailDialog.ts` | 详情对话框（stub） |
|
||||
| `src/tools.ts:127-132` | 工具注册 |
|
||||
| `src/commands.ts:86-89` | 命令注册 |
|
||||
@@ -11,13 +11,13 @@ keywords: ["Ant 特权", "USER_TYPE", "身份门控", "内部功能", "Anthropic
|
||||
`USER_TYPE` 是一个构建时常量，通过 Bun 打包器的 `--define` 注入。在 Anthropic 的内部构建中它被设为 `'ant'`，在公开发布的版本中是 `'external'`：
|
||||
|
||||
```typescript
|
||||
// 反编译版本（src/types/global.d.ts 第 63 行）
|
||||
// Build-time constants BUILD_TARGET/BUILD_ENV/INTERFACE_TYPE — removed (zero runtime usage)
|
||||
// 反编译版本（src/entrypoints/cli.tsx 第 16 行）
|
||||
(globalThis as any).BUILD_TARGET = "external";
|
||||
```
|
||||
|
||||
`BUILD_TARGET` 等构建时常量在反编译版本中已被移除。`USER_TYPE` 通过 Bun 的 `--define` 或环境变量注入，Bun 会进行**常量折叠**——所有 `process.env.USER_TYPE === 'ant'` 在外部构建中直接变为 `false`，后续代码被 DCE 移除。但在反编译版本中，这些代码保留完整。
|
||||
由于这是编译时常量，Bun 会进行**常量折叠**——所有 `process.env.USER_TYPE === 'ant'` 在外部构建中直接变为 `false`，后续代码被 DCE 移除。但在反编译版本中，这些代码保留完整。
|
||||
|
||||
`USER_TYPE === 'ant'` 在代码库中出现 **377+ 次**（含 `=== 'ant'` 291 次、`(process.env.USER_TYPE) === 'ant'` 86 次），另有 `!== 'ant'` 53 次、其他引用约 35 次，总计 **465 处引用**，控制着工具、命令、API、UI 等方方面面。
|
||||
`USER_TYPE === 'ant'` 出现在代码库的 **60+ 个位置**，控制着工具、命令、API、UI 等方方面面。
|
||||
|
||||
## Ant-Only 工具
|
||||
|
||||
@@ -31,9 +31,7 @@ keywords: ["Ant 特权", "USER_TYPE", "身份门控", "内部功能", "Anthropic
|
||||
| **TungstenTool** | `src/tools/TungstenTool/` | 基于 tmux 的终端面板工具（反编译版中已 stub） |
|
||||
|
||||
```typescript
|
||||
// src/tools.ts 第 14-24 行——条件导入 + Dead Code Elimination 标记
|
||||
// Dead code elimination: conditional import for ant-only tools
|
||||
/* eslint-disable custom-rules/no-process-env-top-level, @typescript-eslint/no-require-imports */
|
||||
// src/tools.ts 第 16-24 行
|
||||
const REPLTool =
|
||||
process.env.USER_TYPE === 'ant'
|
||||
? require('./tools/REPLTool/REPLTool.js').REPLTool
|
||||
@@ -47,7 +45,7 @@ const SuggestBackgroundPRTool =
|
||||
|
||||
## Ant-Only 命令
|
||||
|
||||
`src/commands.ts` 注册了 **28** 个仅在内部构建中可用的斜杠命令（`INTERNAL_ONLY_COMMANDS`，lines 225-254），在 `USER_TYPE === 'ant' && !IS_DEMO` 时才加载（line 343-345）：
|
||||
`src/commands.ts` 注册了 25+ 个仅在内部构建中可用的斜杠命令：
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="调试类">
|
||||
@@ -57,7 +55,6 @@ const SuggestBackgroundPRTool =
|
||||
- `env` — 显示环境变量
|
||||
- `mockLimits` — 模拟速率限制
|
||||
- `resetLimits` — 重置速率限制
|
||||
- `resetLimitsNonInteractive` — 重置速率限制（非交互式）
|
||||
</Accordion>
|
||||
<Accordion title="实验类">
|
||||
- `bughunter` — Bug 猎人模式
|
||||
@@ -72,9 +69,6 @@ const SuggestBackgroundPRTool =
|
||||
- `autofixPr` — 自动修复 PR 中的问题
|
||||
- `share` — 分享会话
|
||||
- `summary` — 生成摘要
|
||||
- `subscribePr` — 订阅 PR（需要 `KAIROS_GITHUB_WEBHOOKS` feature flag）
|
||||
- `forceSnip` — 强制截断历史（需要 `HISTORY_SNIP` feature flag）
|
||||
- `ultraplan` — 超级规划（需要 `ULTRAPLAN` feature flag）
|
||||
</Accordion>
|
||||
<Accordion title="基础设施类">
|
||||
- `backfillSessions` — 回填会话数据
|
||||
@@ -94,72 +88,30 @@ const SuggestBackgroundPRTool =
|
||||
|
||||
## Beta API Headers
|
||||
|
||||
Claude Code 向 API 发送的 beta headers 分布在 `src/constants/betas.ts`（主注册表）和其他文件中，按可见性分为以下几类：
|
||||
Claude Code 向 API 发送的 beta headers 也分为公开和内部两类：
|
||||
|
||||
### 公开 Headers（所有构建均发送）
|
||||
|
||||
| Header | 功能 | 额外条件 |
|
||||
|--------|------|----------|
|
||||
| `claude-code-20250219` | Claude Code 标识 | 非 Haiku 时始终发送；Haiku 在 agentic 模式下也发送 |
|
||||
| `effort-2025-11-24` | 推理强度控制 | 动态注入 |
|
||||
| `task-budgets-2026-03-13` | 任务预算 | 始终通过 `addAgenticBetas()` 注入 |
|
||||
| `fast-mode-2026-02-01` | 快速模式 | 通过 sticky-on latch 动态注入 |
|
||||
| `advisor-tool-2026-03-01` | 顾问工具 | 启用 advisor 时动态注入 |
|
||||
| `advanced-tool-use-2025-11-20` | 工具搜索（1P） | Claude API / Foundry |
|
||||
| `tool-search-tool-2025-10-19` | 工具搜索（3P） | Vertex / Bedrock |
|
||||
|
||||
### 模型能力相关（有条件发送）
|
||||
|
||||
| Header | 功能 | 条件 |
|
||||
|--------|------|------|
|
||||
| `interleaved-thinking-2025-05-14` | 交错思考模式 | 模型支持 ISP 且未禁用 |
|
||||
| `context-1m-2025-08-07` | 1M 上下文窗口 | 模型支持 1M context |
|
||||
| `context-management-2025-06-27` | 上下文管理 | Claude 4+ 或 ant 手动启用 |
|
||||
| `structured-outputs-2025-12-15` | 结构化输出 | Claude 4.5/4.6 + GrowthBook `tengu_tool_pear` |
|
||||
| `web-search-2025-03-05` | 网页搜索 | Vertex (Claude 4+) / Foundry |
|
||||
| `redact-thinking-2026-02-12` | 思维摘要/脱敏 | ISP 模型 + 非交互 + 未强制显示思维 |
|
||||
| `prompt-caching-scope-2026-01-05` | 提示缓存作用域 | firstParty/foundry + 全局缓存 |
|
||||
|
||||
### Ant-Only Headers
|
||||
|
||||
| Header | 功能 | 条件 |
|
||||
|--------|------|------|
|
||||
| **`cli-internal-2026-02-09`** | 内部 CLI 功能 | `USER_TYPE === 'ant'` + CLI 入口 |
|
||||
| **`token-efficient-tools-2026-03-28`** | Token 高效工具 | `USER_TYPE === 'ant'` + GrowthBook `tengu_amber_json_tools` |
|
||||
|
||||
### Feature Flag Gated
|
||||
|
||||
| Header | 功能 | 条件 |
|
||||
|--------|------|------|
|
||||
| **`afk-mode-2026-01-31`** | AFK 模式（离开键盘自动审批） | `feature('TRANSCRIPT_CLASSIFIER')` |
|
||||
|
||||
### 其他特殊 Headers
|
||||
|
||||
| Header | 功能 | 来源 |
|
||||
|--------|------|------|
|
||||
| `oauth-2025-04-20` | OAuth 订阅者标识 | `src/constants/oauth.ts`，Pro/Max/Team/Enterprise |
|
||||
| `environments-2025-11-01` | Bridge 环境 API | `src/bridge/bridgeApi.ts`，仅 Bridge 模式 |
|
||||
| Header | 功能 | 可见性 |
|
||||
|--------|------|--------|
|
||||
| `claude-code-20250219` | Claude Code 标识 | 公开 |
|
||||
| `interleaved-thinking-2025-05-14` | 交错思考模式 | 公开 |
|
||||
| `context-1m-2025-08-07` | 1M 上下文窗口 | 公开 |
|
||||
| `context-management-2025-06-27` | 上下文管理 | 公开 |
|
||||
| `web-search-2025-03-05` | 网页搜索 | 公开 |
|
||||
| `effort-2025-11-24` | 推理强度控制 | 公开 |
|
||||
| `fast-mode-2026-02-01` | 快速模式 | 公开 |
|
||||
| `token-efficient-tools-2026-03-28` | Token 高效工具 | 公开 |
|
||||
| `advisor-tool-2026-03-01` | 顾问工具 | 公开 |
|
||||
| **`cli-internal-2026-02-09`** | 内部 CLI 功能 | **Ant-Only** |
|
||||
| **`afk-mode-2026-01-31`** | AFK 模式（离开键盘自动审批） | **Feature Flag** |
|
||||
| **`summarize-connector-text-2026-03-13`** | 连接器文本摘要 | **Feature Flag** |
|
||||
|
||||
```typescript
|
||||
// src/constants/betas.ts — 常量定义
|
||||
export const TOKEN_EFFICIENT_TOOLS_BETA_HEADER =
|
||||
'token-efficient-tools-2026-03-28'
|
||||
// src/constants/betas.ts 第 29-30 行
|
||||
export const CLI_INTERNAL_BETA_HEADER =
|
||||
process.env.USER_TYPE === 'ant' ? 'cli-internal-2026-02-09' : ''
|
||||
```
|
||||
|
||||
```typescript
|
||||
// src/utils/betas.ts 第 315-321 行——TOKEN_EFFICIENT_TOOLS 的实际门控逻辑
|
||||
if (
|
||||
process.env.USER_TYPE === 'ant' &&
|
||||
includeFirstPartyOnlyBetas &&
|
||||
tokenEfficientToolsEnabled // GrowthBook 'tengu_amber_json_tools' flag
|
||||
) {
|
||||
betaHeaders.push(TOKEN_EFFICIENT_TOOLS_BETA_HEADER)
|
||||
}
|
||||
```
|
||||
|
||||
`cli-internal` header 意味着 Anthropic 的 API 服务端也维护着一套 ant-only 的服务端行为——这不仅仅是客户端的门控。`token-efficient-tools` 进一步需要 GrowthBook flag 开启，说明 Ant 员工内部也有分层灰度。
|
||||
`cli-internal` header 意味着 Anthropic 的 API 服务端也维护着一套 ant-only 的服务端行为——这不仅仅是客户端的门控。
|
||||
|
||||
## 内部代号体系
|
||||
|
||||
@@ -186,8 +138,6 @@ Anthropic 有浓厚的"动物命名"文化：
|
||||
- `DISABLE_AUTO_COMPACT` — 禁用自动压缩
|
||||
- `CLAUDE_CODE_DISABLE_AUTO_MEMORY` — 禁用自动记忆
|
||||
- `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` — 禁用后台任务
|
||||
- `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` — 禁用实验性 beta headers
|
||||
- `USE_API_CONTEXT_MANAGEMENT` — 上下文管理工具清除（需 ant）
|
||||
</Accordion>
|
||||
<Accordion title="功能启用开关">
|
||||
- `CLAUDE_CODE_VERIFY_PLAN` — 启用 VerifyPlanExecutionTool
|
||||
@@ -201,7 +151,6 @@ Anthropic 有浓厚的"动物命名"文化：
|
||||
- `CLAUDE_CODE_COORDINATOR_MODE` — 启用 Coordinator 模式
|
||||
- `CLAUDE_INTERNAL_FC_OVERRIDES` — GrowthBook flag 覆盖（ant-only）
|
||||
- `IS_DEMO` — 演示模式（隐藏内部命令和敏感信息）
|
||||
- `CLAUDE_CODE_ENTRYPOINT` — 入口类型标识（`cli` | 其他）
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
|
||||
@@ -1,169 +0,0 @@
|
||||
---
|
||||
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+ 个调用方文件无需修改。
|
||||
@@ -1,106 +0,0 @@
|
||||
---
|
||||
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()` |
|
||||
@@ -1,264 +0,0 @@
|
||||
# LSP Integration
|
||||
|
||||
Claude Code 内置了 Language Server Protocol (LSP) 集成，提供代码智能功能（跳转定义、查找引用、悬停信息、文档符号等）和被动的诊断反馈。
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 1. 安装 LSP 插件
|
||||
|
||||
在 Claude Code REPL 中使用 `/plugin` 命令搜索并安装 LSP 插件：
|
||||
|
||||
```
|
||||
/plugin
|
||||
```
|
||||
|
||||
搜索 `lsp`，找到对应语言的插件（如 `typescript-lsp`），选择安装。
|
||||
|
||||
安装后运行 `/reload-plugins` 使插件生效。
|
||||
|
||||
LSP 插件安装后，后台的 LSP Server Manager 会自动加载并启动对应的语言服务器，无需手动配置。
|
||||
|
||||
### 2. 启用 LSP Tool
|
||||
|
||||
LSP Tool 需要通过环境变量显式启用，Claude 才能主动发起代码智能查询：
|
||||
|
||||
```bash
|
||||
ENABLE_LSP_TOOL=1 bun run dev
|
||||
```
|
||||
|
||||
不启用时，LSP 服务器仍然在后台运行并推送被动的诊断反馈（类型错误等）。
|
||||
|
||||
## 自动推荐
|
||||
|
||||
除了手动 `/plugin` 搜索安装外，Claude Code 会在编辑文件时自动检测：
|
||||
|
||||
1. 监听 `fileHistory.trackedFiles`，发现有新文件被编辑
|
||||
2. 扫描已安装的 marketplace，找到声明支持该文件扩展名的 LSP 插件
|
||||
3. 检查系统上是否已安装对应的 LSP 二进制（如 `typescript-language-server`）
|
||||
4. 满足条件时弹出推荐对话框，可选择安装
|
||||
|
||||
```
|
||||
┌───── LSP Plugin Recommendation ─────────────┐
|
||||
│ │
|
||||
│ LSP provides code intelligence like │
|
||||
│ go-to-definition and error checking │
|
||||
│ │
|
||||
│ Plugin: typescript-lsp │
|
||||
│ Triggered by: .ts files │
|
||||
│ │
|
||||
│ Would you like to install this LSP plugin? │
|
||||
│ │
|
||||
│ > Yes, install typescript-lsp │
|
||||
│ No, not now │
|
||||
│ Never for typescript-lsp │
|
||||
│ Disable all LSP recommendations │
|
||||
└───────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
- 30 秒不操作自动关闭（算作 "No"）
|
||||
- 选 "Never" 不再推荐该插件
|
||||
- 选 "Disable" 关闭所有 LSP 推荐
|
||||
- 连续忽略 5 次后自动禁用推荐
|
||||
|
||||
## 架构概览
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ LSP Tool │
|
||||
│ src/tools/LSPTool/LSPTool.ts │
|
||||
│ (Claude 可调用的工具，9 种操作) │
|
||||
└──────────────────────┬──────────────────────────────┘
|
||||
│
|
||||
┌──────────────────────▼──────────────────────────────┐
|
||||
│ LSP Server Manager (Singleton) │
|
||||
│ src/services/lsp/manager.ts │
|
||||
│ - initializeLspServerManager() │
|
||||
│ - reinitializeLspServerManager() │
|
||||
│ - shutdownLspServerManager() │
|
||||
└──────────────────────┬──────────────────────────────┘
|
||||
│
|
||||
┌──────────────────────▼──────────────────────────────┐
|
||||
│ LSP Server Manager (实例) │
|
||||
│ src/services/lsp/LSPServerManager.ts │
|
||||
│ - 管理多个 LSPServerInstance │
|
||||
│ - 按文件扩展名路由请求 │
|
||||
│ - 文件同步 (didOpen/didChange/didSave/didClose) │
|
||||
└──────────────────────┬──────────────────────────────┘
|
||||
│
|
||||
┌─────────────┼─────────────┐
|
||||
▼ ▼ ▼
|
||||
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||||
│ LSPServer │ │ LSPServer │ │ LSPServer │
|
||||
│ Instance │ │ Instance │ │ Instance │
|
||||
│ (typescript) │ │ (python) │ │ (rust...) │
|
||||
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
|
||||
│ │ │
|
||||
┌──────▼───────┐ ┌──────▼───────┐ ┌──────▼───────┐
|
||||
│ LSPClient │ │ LSPClient │ │ LSPClient │
|
||||
│ (JSON-RPC) │ │ (JSON-RPC) │ │ (JSON-RPC) │
|
||||
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
|
||||
│ │ │
|
||||
子进程 (stdio) 子进程 (stdio) 子进程 (stdio)
|
||||
```
|
||||
|
||||
### 被动诊断反馈
|
||||
|
||||
```
|
||||
LSP Server ──publishDiagnostics──▶ passiveFeedback.ts
|
||||
│
|
||||
▼
|
||||
LSPDiagnosticRegistry
|
||||
(去重、容量限制)
|
||||
│
|
||||
▼
|
||||
Attachment System
|
||||
(异步注入到对话)
|
||||
```
|
||||
|
||||
LSP 服务器会异步推送 `textDocument/publishDiagnostics` 通知，经去重和容量限制后作为 attachment 注入到 Claude 的对话上下文中。
|
||||
|
||||
## 核心模块
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `src/services/lsp/manager.ts` | 全局单例，初始化/重初始化/关闭生命周期管理 |
|
||||
| `src/services/lsp/LSPServerManager.ts` | 多服务器管理，按文件扩展名路由，文件同步 |
|
||||
| `src/services/lsp/LSPServerInstance.ts` | 单个 LSP 服务器实例生命周期（启动/停止/重启/健康检查） |
|
||||
| `src/services/lsp/LSPClient.ts` | JSON-RPC 通信层（基于 `vscode-jsonrpc`），子进程管理 |
|
||||
| `src/services/lsp/config.ts` | 从插件加载 LSP 服务器配置 |
|
||||
| `src/services/lsp/LSPDiagnosticRegistry.ts` | 诊断信息注册、去重、容量限制 |
|
||||
| `src/services/lsp/passiveFeedback.ts` | 注册 `publishDiagnostics` 通知处理器 |
|
||||
| `src/tools/LSPTool/LSPTool.ts` | LSP Tool 实现（暴露给 Claude） |
|
||||
| `src/tools/LSPTool/schemas.ts` | 输入 schema（9 种操作的 discriminated union） |
|
||||
| `src/tools/LSPTool/formatters.ts` | 各操作结果的格式化 |
|
||||
| `src/tools/LSPTool/prompt.ts` | Tool 描述文本 |
|
||||
| `src/utils/plugins/lspPluginIntegration.ts` | 从插件加载、验证、环境变量解析、作用域管理 |
|
||||
|
||||
## LSP Tool 支持的操作
|
||||
|
||||
| 操作 | LSP Method | 说明 |
|
||||
|------|-----------|------|
|
||||
| `goToDefinition` | `textDocument/definition` | 跳转到符号定义 |
|
||||
| `findReferences` | `textDocument/references` | 查找所有引用 |
|
||||
| `hover` | `textDocument/hover` | 获取悬停信息（文档、类型） |
|
||||
| `documentSymbol` | `textDocument/documentSymbol` | 获取文档内所有符号 |
|
||||
| `workspaceSymbol` | `workspace/symbol` | 全工作区符号搜索 |
|
||||
| `goToImplementation` | `textDocument/implementation` | 查找接口/抽象方法的实现 |
|
||||
| `prepareCallHierarchy` | `textDocument/prepareCallHierarchy` | 获取位置处的调用层级项 |
|
||||
| `incomingCalls` | `callHierarchy/incomingCalls` | 查找调用此函数的所有函数 |
|
||||
| `outgoingCalls` | `callHierarchy/outgoingCalls` | 查找此函数调用的所有函数 |
|
||||
|
||||
所有操作需要 `filePath`、`line`（1-based）和 `character`（1-based）参数。
|
||||
|
||||
## 插件开发：LSP 服务器配置
|
||||
|
||||
LSP 服务器通过插件提供。插件的 `manifest.json` 中可以声明 LSP 服务器，支持三种格式：
|
||||
|
||||
**1. 内联配置（在 manifest 中直接定义）**
|
||||
|
||||
```json
|
||||
{
|
||||
"lspServers": {
|
||||
"typescript": {
|
||||
"command": "typescript-language-server",
|
||||
"args": ["--stdio"],
|
||||
"extensionToLanguage": {
|
||||
".ts": "typescript",
|
||||
".tsx": "typescriptreact"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**2. 引用外部 .lsp.json 文件**
|
||||
|
||||
```json
|
||||
{
|
||||
"lspServers": "path/to/.lsp.json"
|
||||
}
|
||||
```
|
||||
|
||||
**3. 数组混合格式**
|
||||
|
||||
```json
|
||||
{
|
||||
"lspServers": [
|
||||
"path/to/.lsp.json",
|
||||
{
|
||||
"another-server": { "command": "...", "extensionToLanguage": { "...": "..." } }
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
也可以在插件目录下直接放置 `.lsp.json` 文件，无需在 manifest 中声明。
|
||||
|
||||
### LSP 服务器配置 Schema
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `command` | string | 是 | LSP 服务器可执行命令（不含空格） |
|
||||
| `args` | string[] | 否 | 命令行参数 |
|
||||
| `extensionToLanguage` | Record<string, string> | 是 | 文件扩展名到语言 ID 的映射（至少一个） |
|
||||
| `transport` | `"stdio"` \| `"socket"` | 否 | 通信方式，默认 `stdio` |
|
||||
| `env` | Record<string, string> | 否 | 启动服务器时设置的环境变量 |
|
||||
| `initializationOptions` | unknown | 否 | 传给服务器的初始化选项 |
|
||||
| `settings` | unknown | 否 | 通过 `workspace/didChangeConfiguration` 传递的设置 |
|
||||
| `workspaceFolder` | string | 否 | 工作区目录路径 |
|
||||
| `startupTimeout` | number | 否 | 启动超时时间（毫秒） |
|
||||
| `maxRestarts` | number | 否 | 最大重启次数（默认 3） |
|
||||
|
||||
### 环境变量替换
|
||||
|
||||
配置中的 `command`、`args`、`env`、`workspaceFolder` 支持：
|
||||
|
||||
- `${CLAUDE_PLUGIN_ROOT}` — 插件根目录
|
||||
- `${CLAUDE_PLUGIN_DATA}` — 插件数据目录
|
||||
- `${user_config.KEY}` — 用户在插件启用时配置的值
|
||||
- `${VAR}` — 系统环境变量
|
||||
|
||||
## 生命周期管理
|
||||
|
||||
### 服务器状态机
|
||||
|
||||
```
|
||||
stopped → starting → running
|
||||
running → stopping → stopped
|
||||
any → error (失败时)
|
||||
error → starting (重试时)
|
||||
```
|
||||
|
||||
### 崩溃恢复
|
||||
|
||||
- LSP 服务器崩溃时状态设为 `error`
|
||||
- 下次请求时自动尝试重启（通过 `ensureServerStarted`）
|
||||
- 超过 `maxRestarts`（默认 3）次后放弃
|
||||
|
||||
### 瞬态错误重试
|
||||
|
||||
- `ContentModified` 错误（LSP 错误码 -32801）会自动重试，最多 3 次
|
||||
- 使用指数退避：500ms → 1000ms → 2000ms
|
||||
- 常见于 rust-analyzer 等仍在索引项目的服务器
|
||||
|
||||
### 诊断信息容量限制
|
||||
|
||||
- 每个文件最多 10 条诊断
|
||||
- 总计最多 30 条诊断
|
||||
- 超出部分按严重性排序后截断（Error > Warning > Info > Hint）
|
||||
- 跨 turn 去重：已发送过的相同诊断不会重复发送
|
||||
- 文件编辑后清除该文件的已发送记录，允许新诊断通过
|
||||
|
||||
### 插件刷新
|
||||
|
||||
安装/卸载插件后使用 `/reload-plugins`，会调用 `reinitializeLspServerManager()`：
|
||||
1. 异步关闭旧服务器实例
|
||||
2. 重置状态为 `not-started`
|
||||
3. 调用 `initializeLspServerManager()` 重新加载插件配置
|
||||
|
||||
## 依赖
|
||||
|
||||
- `vscode-jsonrpc` — JSON-RPC 通信（懒加载，仅在实际创建服务器实例时才 require）
|
||||
- `vscode-languageserver-protocol` — LSP 协议类型
|
||||
- `vscode-languageserver-types` — LSP 类型定义
|
||||
- `lru-cache` — 诊断去重缓存
|
||||
@@ -1,190 +0,0 @@
|
||||
# OpenAI兼容模型中task工具使用指南
|
||||
|
||||
## 问题描述
|
||||
|
||||
当使用OpenAI兼容模型（如DeepSeek、Ollama、vLLM等）时，调用task工具（TaskGet、TaskCreate、TaskUpdate、TaskList）可能会出现以下错误：
|
||||
|
||||
```
|
||||
Error: InputValidationError: TaskGet failed due to the following issues:
|
||||
The required parameter `taskId` is missing
|
||||
An unexpected parameter `task_id` was provided
|
||||
|
||||
This tool's schema was not sent to the API — it was not in the discovered-tool set derived from message history. Without the schema in your prompt, typed parameters (arrays, numbers, booleans) get emitted as strings and the client-side parser rejects them. Load the tool first: call ToolSearch with query "select:TaskGet", then retry this call.
|
||||
```
|
||||
|
||||
## 问题原因
|
||||
|
||||
### 1. 延迟加载工具（Deferred Tools）
|
||||
task工具都是延迟加载的（`shouldDefer: true`），这意味着：
|
||||
- 工具的模式（schema）不会在初始API调用中发送
|
||||
- 需要先通过`ToolSearch`工具发现
|
||||
- 只有在被发现后，工具模式才会被发送给API
|
||||
|
||||
### 2. 参数名转换问题
|
||||
- task工具使用驼峰命名：`taskId`
|
||||
- OpenAI兼容模型可能输出蛇形命名：`task_id`
|
||||
- 当工具模式没有被发送时，模型会猜测参数名，可能导致不匹配
|
||||
|
||||
## 解决方案
|
||||
|
||||
### 方案1：先使用ToolSearch（推荐）
|
||||
在使用task工具之前，先调用`ToolSearch`工具：
|
||||
|
||||
```javascript
|
||||
// 第一步：发现task工具
|
||||
ToolSearch("select:TaskGet,TaskCreate,TaskUpdate,TaskList")
|
||||
|
||||
// 第二步：正常使用task工具
|
||||
TaskCreate({ subject: "任务标题", description: "任务描述" })
|
||||
TaskGet({ taskId: "1" })
|
||||
TaskUpdate({ taskId: "1", status: "completed" })
|
||||
TaskList()
|
||||
```
|
||||
|
||||
### 方案2：批量发现所有task工具
|
||||
```javascript
|
||||
// 一次性发现所有task工具
|
||||
ToolSearch("select:TaskGet,TaskCreate,TaskUpdate,TaskList")
|
||||
|
||||
// 然后可以任意使用task工具
|
||||
const task = await TaskCreate({ subject: "新任务", description: "任务描述" })
|
||||
console.log(`创建的任务ID: ${task.id}`)
|
||||
|
||||
const taskList = await TaskList()
|
||||
console.log(`当前有 ${taskList.tasks.length} 个任务`)
|
||||
```
|
||||
|
||||
### 方案3：单独发现特定工具
|
||||
```javascript
|
||||
// 只发现需要的工具
|
||||
ToolSearch("select:TaskGet")
|
||||
|
||||
// 然后使用该工具
|
||||
TaskGet({ taskId: "1" })
|
||||
```
|
||||
|
||||
## 参数名注意事项
|
||||
|
||||
在使用OpenAI兼容模型时，请注意参数名格式：
|
||||
|
||||
### ✅ 正确（驼峰命名）
|
||||
```javascript
|
||||
TaskGet({ taskId: "1" })
|
||||
TaskCreate({ subject: "标题", description: "描述" })
|
||||
TaskUpdate({ taskId: "1", status: "completed" })
|
||||
```
|
||||
|
||||
### ❌ 错误（蛇形命名）
|
||||
```javascript
|
||||
TaskGet({ task_id: "1" }) // 错误：应该使用taskId
|
||||
TaskCreate({ subject: "标题", description: "描述" }) // 正确
|
||||
TaskUpdate({ task_id: "1", status: "completed" }) // 错误：应该使用taskId
|
||||
```
|
||||
|
||||
## 常见问题解答
|
||||
|
||||
### Q1: 为什么需要先使用ToolSearch？
|
||||
A: task工具是延迟加载的，它们的模式只有在被`ToolSearch`工具发现后才会发送给API。没有工具模式，模型无法知道正确的参数名和类型。
|
||||
|
||||
### Q2: 每次会话都需要使用ToolSearch吗？
|
||||
A: 是的，每次新的会话都需要先使用ToolSearch发现工具。工具发现状态不会在会话之间保留。
|
||||
|
||||
### Q3: 使用Anthropic官方模型也需要这样吗？
|
||||
A: 通常不需要。Anthropic官方模型对延迟加载工具的处理更智能，但为了兼容性，建议在使用task工具前都先使用ToolSearch。
|
||||
|
||||
### Q4: 可以一次性发现所有工具吗？
|
||||
A: 可以，使用`ToolSearch("select:TaskGet,TaskCreate,TaskUpdate,TaskList")`可以一次性发现所有task工具。
|
||||
|
||||
### Q5: 如果忘记使用ToolSearch会怎样？
|
||||
A: 会收到参数验证错误，提示需要先使用ToolSearch。按照错误信息的指导操作即可。
|
||||
|
||||
## 最佳实践
|
||||
|
||||
1. **会话开始时发现工具**：在开始使用task工具前，先调用ToolSearch
|
||||
2. **批量发现**：一次性发现所有需要的task工具
|
||||
3. **检查参数名**：确保使用正确的驼峰命名参数
|
||||
4. **查看错误信息**：如果遇到错误，仔细阅读错误信息中的指导
|
||||
|
||||
## 示例工作流
|
||||
|
||||
```javascript
|
||||
// 1. 开始新会话
|
||||
// 2. 发现task工具
|
||||
ToolSearch("select:TaskGet,TaskCreate,TaskUpdate,TaskList")
|
||||
|
||||
// 3. 创建任务
|
||||
const newTask = await TaskCreate({
|
||||
subject: "修复OpenAI兼容性问题",
|
||||
description: "解决task工具在OpenAI兼容模型下的参数名问题"
|
||||
})
|
||||
|
||||
// 4. 获取任务详情
|
||||
const taskDetails = await TaskGet({ taskId: newTask.id })
|
||||
|
||||
// 5. 更新任务状态
|
||||
await TaskUpdate({
|
||||
taskId: newTask.id,
|
||||
status: "in_progress",
|
||||
activeForm: "修复OpenAI兼容性问题"
|
||||
})
|
||||
|
||||
// 6. 查看所有任务
|
||||
const allTasks = await TaskList()
|
||||
console.log(`当前有 ${allTasks.tasks.length} 个任务`)
|
||||
|
||||
// 7. 完成任务
|
||||
await TaskUpdate({
|
||||
taskId: newTask.id,
|
||||
status: "completed"
|
||||
})
|
||||
```
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 错误：参数名不匹配
|
||||
**症状**：`taskId`参数缺失，发现`task_id`参数
|
||||
**解决**：确保使用驼峰命名的`taskId`，而不是蛇形命名的`task_id`
|
||||
|
||||
### 错误：工具模式未发送
|
||||
**症状**：`This tool's schema was not sent to the API`
|
||||
**解决**：先使用`ToolSearch("select:工具名")`发现工具
|
||||
|
||||
### 错误：工具不可用
|
||||
**症状**：工具调用失败，没有具体错误信息
|
||||
**解决**：检查工具是否启用（通过`isTodoV2Enabled()`），确保环境变量设置正确
|
||||
|
||||
## 相关配置
|
||||
|
||||
### 环境变量
|
||||
```bash
|
||||
# 启用OpenAI兼容模式
|
||||
export CLAUDE_CODE_USE_OPENAI=1
|
||||
export OPENAI_API_KEY=your-api-key
|
||||
export OPENAI_BASE_URL=https://api.deepseek.com
|
||||
|
||||
# 配置模型映射
|
||||
export OPENAI_DEFAULT_SONNET_MODEL=deepseek-chat
|
||||
export OPENAI_DEFAULT_OPUS_MODEL=deepseek-chat
|
||||
export OPENAI_DEFAULT_HAIKU_MODEL=deepseek-chat
|
||||
```
|
||||
|
||||
### 设置文件
|
||||
通过`/login`命令配置OpenAI兼容模式后，设置会保存在`~/.claude/settings.json`：
|
||||
```json
|
||||
{
|
||||
"modelType": "openai",
|
||||
"openai": {
|
||||
"baseURL": "https://api.deepseek.com",
|
||||
"apiKey": "your-api-key",
|
||||
"models": {
|
||||
"haiku": "deepseek-chat",
|
||||
"sonnet": "deepseek-chat",
|
||||
"opus": "deepseek-chat"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 总结
|
||||
|
||||
在使用OpenAI兼容模型时，task工具需要先通过`ToolSearch`发现才能正常使用。遵循"先发现，后使用"的原则，并注意参数名的正确格式（驼峰命名），可以确保task工具在OpenAI兼容模型下正常工作。
|
||||
@@ -1,425 +0,0 @@
|
||||
# OpenAI 协议兼容层
|
||||
|
||||
## 概述
|
||||
|
||||
claude-code 支持通过 OpenAI Chat Completions API（`/v1/chat/completions`）兼容任意 OpenAI 协议端点，包括 Ollama、DeepSeek、vLLM、One API、LiteLLM 等。
|
||||
|
||||
核心策略为**流适配器模式**：在 `queryModel()` 中插入提前返回分支，将 Anthropic 格式请求转为 OpenAI 格式，调用 OpenAI SDK，再将 SSE 流转换回 `BetaRawMessageStreamEvent` 格式。下游代码（流处理循环、query.ts、QueryEngine.ts、REPL）**完全不改**。
|
||||
|
||||
## 环境变量
|
||||
|
||||
| 变量 | 必需 | 说明 |
|
||||
|---|---|---|
|
||||
| `CLAUDE_CODE_USE_OPENAI` | 是 | 设为 `1` 启用 OpenAI 后端 |
|
||||
| `OPENAI_API_KEY` | 是 | API key（Ollama 等可设为任意值） |
|
||||
| `OPENAI_BASE_URL` | 推荐 | 端点 URL（如 `http://localhost:11434/v1`） |
|
||||
| `OPENAI_MODEL` | 可选 | 覆盖所有请求的模型名（跳过映射） |
|
||||
| `OPENAI_DEFAULT_OPUS_MODEL` | 可选 | 覆盖 opus 家族对应的模型（如 `o3`, `o3-mini`, `o1-pro`） |
|
||||
| `OPENAI_DEFAULT_SONNET_MODEL` | 可选 | 覆盖 sonnet 家族对应的模型（如 `gpt-4o`, `gpt-4.1`） |
|
||||
| `OPENAI_DEFAULT_HAIKU_MODEL` | 可选 | 覆盖 haiku 家族对应的模型（如 `gpt-4o-mini`, `gpt-4.0-mini`） |
|
||||
| `OPENAI_ORG_ID` | 可选 | Organization ID |
|
||||
| `OPENAI_PROJECT_ID` | 可选 | Project ID |
|
||||
|
||||
### 使用示例
|
||||
|
||||
```bash
|
||||
# Ollama
|
||||
CLAUDE_CODE_USE_OPENAI=1 \
|
||||
OPENAI_API_KEY=ollama \
|
||||
OPENAI_BASE_URL=http://localhost:11434/v1 \
|
||||
OPENAI_MODEL=qwen2.5-coder-32b \
|
||||
bun run dev
|
||||
|
||||
# DeepSeek（自动支持 Thinking）
|
||||
CLAUDE_CODE_USE_OPENAI=1 \
|
||||
OPENAI_API_KEY=sk-xxx \
|
||||
OPENAI_BASE_URL=https://api.deepseek.com/v1 \
|
||||
OPENAI_MODEL=deepseek-chat \
|
||||
bun run dev
|
||||
|
||||
# vLLM
|
||||
CLAUDE_CODE_USE_OPENAI=1 \
|
||||
OPENAI_API_KEY=token-abc123 \
|
||||
OPENAI_BASE_URL=http://localhost:8000/v1 \
|
||||
OPENAI_MODEL=Qwen/Qwen2.5-Coder-32B-Instruct \
|
||||
bun run dev
|
||||
|
||||
# One API / LiteLLM
|
||||
CLAUDE_CODE_USE_OPENAI=1 \
|
||||
OPENAI_API_KEY=sk-your-key \
|
||||
OPENAI_BASE_URL=https://your-one-api.example.com/v1 \
|
||||
OPENAI_MODEL=gpt-4o \
|
||||
bun run dev
|
||||
|
||||
# 自定义模型映射（使用家族变量）
|
||||
CLAUDE_CODE_USE_OPENAI=1 \
|
||||
OPENAI_API_KEY=sk-xxx \
|
||||
OPENAI_BASE_URL=https://my-gateway.example.com/v1 \
|
||||
OPENAI_DEFAULT_SONNET_MODEL="gpt-4o-2024-11-20" \
|
||||
OPENAI_DEFAULT_HAIKU_MODEL="gpt-4o-mini" \
|
||||
bun run dev
|
||||
```
|
||||
|
||||
## 架构
|
||||
|
||||
### 请求流程
|
||||
|
||||
```
|
||||
queryModel() [claude.ts]
|
||||
├── 共享预处理（消息归一化、工具过滤、媒体裁剪）
|
||||
└── if (getAPIProvider() === 'openai')
|
||||
└── queryModelOpenAI() [openai/index.ts]
|
||||
├── resolveOpenAIModel() → 解析模型名
|
||||
├── normalizeMessagesForAPI() → 共享消息预处理
|
||||
├── toolToAPISchema() → 构建工具 schema
|
||||
├── anthropicMessagesToOpenAI() → 消息格式转换
|
||||
├── anthropicToolsToOpenAI() → 工具格式转换
|
||||
├── openai.chat.completions.create({ stream: true })
|
||||
└── adaptOpenAIStreamToAnthropic() → 流格式转换
|
||||
├── delta.reasoning_content → thinking 块
|
||||
├── delta.content → text 块
|
||||
├── delta.tool_calls → tool_use 块
|
||||
├── usage.cached_tokens → cache_read_input_tokens
|
||||
└── yield BetaRawMessageStreamEvent
|
||||
```
|
||||
|
||||
### 模型名解析优先级
|
||||
|
||||
`resolveOpenAIModel()` 的解析顺序：
|
||||
|
||||
1. `OPENAI_MODEL` 环境变量 → 直接使用，覆盖所有
|
||||
2. `OPENAI_DEFAULT_{FAMILY}_MODEL` 变量（如 `OPENAI_DEFAULT_SONNET_MODEL`）→ 按模型家族覆盖
|
||||
3. `ANTHROPIC_DEFAULT_{FAMILY}_MODEL` 变量（向后兼容）
|
||||
4. 内置默认映射（见下表）
|
||||
5. 以上都不匹配 → 原名透传
|
||||
|
||||
### 内置模型映射
|
||||
|
||||
| Anthropic 模型 | OpenAI 映射 |
|
||||
|---|---|
|
||||
| `claude-sonnet-4-6` | `gpt-4o` |
|
||||
| `claude-sonnet-4-5-20250929` | `gpt-4o` |
|
||||
| `claude-sonnet-4-20250514` | `gpt-4o` |
|
||||
| `claude-3-7-sonnet-20250219` | `gpt-4o` |
|
||||
| `claude-3-5-sonnet-20241022` | `gpt-4o` |
|
||||
| `claude-opus-4-6` | `o3` |
|
||||
| `claude-opus-4-5-20251101` | `o3` |
|
||||
| `claude-opus-4-1-20250805` | `o3` |
|
||||
| `claude-opus-4-20250514` | `o3` |
|
||||
| `claude-haiku-4-5-20251001` | `gpt-4o-mini` |
|
||||
| `claude-3-5-haiku-20241022` | `gpt-4o-mini` |
|
||||
|
||||
同时会自动剥离 `[1m]` 后缀（Claude 特有的 modifier）。
|
||||
|
||||
## 文件结构
|
||||
|
||||
### 新增文件
|
||||
|
||||
```
|
||||
src/services/api/openai/
|
||||
├── client.ts # OpenAI SDK 客户端工厂（~50 行）
|
||||
├── convertMessages.ts # Anthropic → OpenAI 消息格式转换（~190 行）
|
||||
├── convertTools.ts # Anthropic → OpenAI 工具格式转换（~70 行）
|
||||
├── streamAdapter.ts # SSE 流转换核心，含 thinking + caching（~270 行）
|
||||
├── modelMapping.ts # 模型名解析（~60 行）
|
||||
├── index.ts # 公共入口 queryModelOpenAI()（~110 行）
|
||||
└── __tests__/
|
||||
├── convertMessages.test.ts # 10 个测试
|
||||
├── convertTools.test.ts # 7 个测试
|
||||
├── modelMapping.test.ts # 6 个测试
|
||||
└── streamAdapter.test.ts # 14 个测试（含 thinking + caching）
|
||||
```
|
||||
|
||||
### 修改文件
|
||||
|
||||
| 文件 | 改动 |
|
||||
|---|---|
|
||||
| `src/utils/model/providers.ts` | 添加 `'openai'` provider 类型 + `CLAUDE_CODE_USE_OPENAI` 检查（最高优先级） |
|
||||
| `src/utils/model/configs.ts` | 每个 ModelConfig 添加 `openai` 键 |
|
||||
| `src/services/api/claude.ts` | 在 `stripExcessMediaItems()` 后插入 OpenAI 提前返回分支（~8 行） |
|
||||
| `package.json` | 添加 `"openai": "^4.73.0"` 依赖 |
|
||||
|
||||
## 消息转换规则
|
||||
|
||||
### Anthropic → OpenAI
|
||||
|
||||
| Anthropic | OpenAI |
|
||||
|---|---|
|
||||
| `system` prompt（`string[]`） | `role: "system"` 消息（`\n\n` 拼接） |
|
||||
| `user` + `text` 块 | `role: "user"` 消息 |
|
||||
| `assistant` + `text` 块 | `role: "assistant"` + `content` |
|
||||
| `assistant` + `tool_use` 块 | `role: "assistant"` + `tool_calls[]` |
|
||||
| `user` + `tool_result` 块 | `role: "tool"` + `tool_call_id` |
|
||||
| `thinking` 块 | 静默丢弃（请求侧） |
|
||||
|
||||
### 工具转换
|
||||
|
||||
| Anthropic | OpenAI |
|
||||
|---|---|
|
||||
| `{ name, description, input_schema }` | `{ type: "function", function: { name, description, parameters } }` |
|
||||
| `cache_control`, `defer_loading` 等字段 | 剥离 |
|
||||
| `tool_choice: { type: "auto" }` | `"auto"` |
|
||||
| `tool_choice: { type: "any" }` | `"required"` |
|
||||
| `tool_choice: { type: "tool", name }` | `{ type: "function", function: { name } }` |
|
||||
|
||||
### 消息转换示例
|
||||
|
||||
```
|
||||
Anthropic: OpenAI:
|
||||
[
|
||||
system: ["You are helpful."], [
|
||||
{ role: "system",
|
||||
{ role: "user", content: "You are helpful." },
|
||||
content: [ { role: "user",
|
||||
{ type: "text", text: "Run ls" } content: "Run ls"
|
||||
] },
|
||||
}, { role: "assistant",
|
||||
{ role: "assistant", content: "I'll check.",
|
||||
content: [ tool_calls: [{
|
||||
{ type: "text", text: "I'll check."}, id: "tu_123",
|
||||
{ type: "tool_use", type: "function",
|
||||
id: "tu_123", name: "bash", function: {
|
||||
input: { command: "ls" } } name: "bash",
|
||||
] arguments: '{"command":"ls"}'
|
||||
}, }] }
|
||||
{ role: "user", { role: "tool",
|
||||
content: [ tool_call_id: "tu_123",
|
||||
{ type: "tool_result", content: "file1\nfile2"
|
||||
tool_use_id: "tu_123", }
|
||||
content: "file1\nfile2" ]
|
||||
]
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## 流转换规则
|
||||
|
||||
### SSE Chunk → Anthropic Event 映射
|
||||
|
||||
| OpenAI Chunk | Anthropic Event |
|
||||
|---|---|
|
||||
| 首个 chunk | `message_start`（含 usage） |
|
||||
| `delta.reasoning_content` | `content_block_start(thinking)` + `thinking_delta` |
|
||||
| `delta.content` | `content_block_start(text)` + `text_delta` |
|
||||
| `delta.tool_calls` | `content_block_start(tool_use)` + `input_json_delta` |
|
||||
| `finish_reason: "stop"` | `message_delta(stop_reason: "end_turn")` |
|
||||
| `finish_reason: "tool_calls"` | `message_delta(stop_reason: "tool_use")` |
|
||||
| `finish_reason: "length"` | `message_delta(stop_reason: "max_tokens")` |
|
||||
|
||||
### 块顺序
|
||||
|
||||
当模型返回 `reasoning_content` 时（如 DeepSeek），块顺序与 Anthropic 一致：
|
||||
|
||||
```
|
||||
thinking block (index 0) ← delta.reasoning_content
|
||||
text block (index 1) ← delta.content
|
||||
```
|
||||
|
||||
或：
|
||||
|
||||
```
|
||||
thinking block (index 0) ← delta.reasoning_content
|
||||
tool_use block (index 1) ← delta.tool_calls
|
||||
```
|
||||
|
||||
无 `reasoning_content` 时：
|
||||
|
||||
```
|
||||
text block (index 0) ← delta.content
|
||||
tool_use block (index 1) ← delta.tool_calls（如果有）
|
||||
```
|
||||
|
||||
### finish_reason 映射
|
||||
|
||||
| OpenAI | Anthropic |
|
||||
|---|---|
|
||||
| `stop` | `end_turn` |
|
||||
| `tool_calls` | `tool_use` |
|
||||
| `length` | `max_tokens` |
|
||||
| `content_filter` | `end_turn` |
|
||||
|
||||
### 事件序列示例
|
||||
|
||||
**纯文本响应**：
|
||||
```
|
||||
OpenAI chunks:
|
||||
delta.content = "Hello"
|
||||
delta.content = " world"
|
||||
finish_reason = "stop"
|
||||
|
||||
→ Anthropic events:
|
||||
message_start { message: { id, role: 'assistant', usage: {...} } }
|
||||
content_block_start { index: 0, content_block: { type: 'text' } }
|
||||
content_block_delta { index: 0, delta: { type: 'text_delta', text: 'Hello' } }
|
||||
content_block_delta { index: 0, delta: { type: 'text_delta', text: ' world' } }
|
||||
content_block_stop { index: 0 }
|
||||
message_delta { delta: { stop_reason: 'end_turn' } }
|
||||
message_stop
|
||||
```
|
||||
|
||||
**Thinking + 文本（DeepSeek 风格）**：
|
||||
```
|
||||
OpenAI chunks:
|
||||
delta.reasoning_content = "Let me think..."
|
||||
delta.reasoning_content = " step by step."
|
||||
delta.content = "The answer is 42."
|
||||
finish_reason = "stop"
|
||||
|
||||
→ Anthropic events:
|
||||
message_start { ... }
|
||||
content_block_start { index: 0, content_block: { type: 'thinking', signature: '' } }
|
||||
content_block_delta { index: 0, delta: { type: 'thinking_delta', thinking: 'Let me think...' } }
|
||||
content_block_delta { index: 0, delta: { type: 'thinking_delta', thinking: ' step by step.' } }
|
||||
content_block_stop { index: 0 }
|
||||
content_block_start { index: 1, content_block: { type: 'text' } }
|
||||
content_block_delta { index: 1, delta: { type: 'text_delta', text: 'The answer is 42.' } }
|
||||
content_block_stop { index: 1 }
|
||||
message_delta { delta: { stop_reason: 'end_turn' } }
|
||||
message_stop
|
||||
```
|
||||
|
||||
**工具调用**：
|
||||
```
|
||||
OpenAI chunks:
|
||||
delta.tool_calls[0] = { id: 'call_xxx', function: { name: 'bash', arguments: '' } }
|
||||
delta.tool_calls[0].function.arguments = '{"comm'
|
||||
delta.tool_calls[0].function.arguments = 'and":"ls"}'
|
||||
finish_reason = "tool_calls"
|
||||
|
||||
→ Anthropic events:
|
||||
message_start { ... }
|
||||
content_block_start { index: 0, content_block: { type: 'tool_use', id: 'call_xxx', name: 'bash' } }
|
||||
content_block_delta { index: 0, delta: { type: 'input_json_delta', partial_json: '{"comm' } }
|
||||
content_block_delta { index: 0, delta: { type: 'input_json_delta', partial_json: 'and":"ls"}' } }
|
||||
content_block_stop { index: 0 }
|
||||
message_delta { delta: { stop_reason: 'tool_use' } }
|
||||
message_stop
|
||||
```
|
||||
|
||||
## 功能支持
|
||||
|
||||
### Thinking（思维链）
|
||||
|
||||
**请求侧**：不需要显式配置。支持思维链的模型（DeepSeek 等）会自动返回 `delta.reasoning_content`。
|
||||
|
||||
**响应侧**：`delta.reasoning_content` 被转换为 Anthropic `thinking` content block：
|
||||
|
||||
```ts
|
||||
// content_block_start
|
||||
{ type: 'content_block_start', index: 0,
|
||||
content_block: { type: 'thinking', thinking: '', signature: '' } }
|
||||
|
||||
// content_block_delta
|
||||
{ type: 'content_block_delta', index: 0,
|
||||
delta: { type: 'thinking_delta', thinking: 'Let me analyze...' } }
|
||||
```
|
||||
|
||||
thinking block 在 text/tool_use block 之前自动关闭，保持 Anthropic 的块顺序。
|
||||
|
||||
### Prompt Caching
|
||||
|
||||
**请求侧**：OpenAI 端点使用自动缓存，无需显式设置 `cache_control`。
|
||||
|
||||
**响应侧**：OpenAI 的 `usage.prompt_tokens_details.cached_tokens` 被映射到 Anthropic 的 `cache_read_input_tokens`：
|
||||
|
||||
```
|
||||
OpenAI: usage.prompt_tokens_details.cached_tokens = 800
|
||||
↓
|
||||
Anthropic: message_start.message.usage.cache_read_input_tokens = 800
|
||||
```
|
||||
|
||||
在 `message_start` 的 usage 中报告缓存命中量。
|
||||
|
||||
### 工具调用（Tool Use）
|
||||
|
||||
完整支持 OpenAI function calling 格式。所有本地工具（Bash、FileEdit、Grep、Glob、Agent 等）透明工作——它们通过 JSON 输入输出通信，格式无关。
|
||||
|
||||
工具参数以 `input_json_delta` 形式流式传输，由下游代码拼接解析。
|
||||
|
||||
### 不支持的功能
|
||||
|
||||
| 功能 | 策略 |
|
||||
|---|---|
|
||||
| Beta Headers | 不发送 |
|
||||
| Server Tools (advisor) | 不发送 |
|
||||
| Structured Output | 不发送 |
|
||||
| Fast Mode / Effort | 不发送 |
|
||||
| Tool Search / defer_loading | 不启用，所有工具直接发送 |
|
||||
| Anthropic Signature | thinking block 的 `signature` 字段为空字符串 |
|
||||
| cache_creation_input_tokens | 始终为 0（OpenAI 不区分创建/读取） |
|
||||
|
||||
## 测试
|
||||
|
||||
```bash
|
||||
# 运行所有 OpenAI 适配层测试
|
||||
bun test src/services/api/openai/__tests__/
|
||||
|
||||
# 单独运行
|
||||
bun test src/services/api/openai/__tests__/streamAdapter.test.ts # 14 tests（含 thinking + caching）
|
||||
bun test src/services/api/openai/__tests__/convertMessages.test.ts # 10 tests
|
||||
bun test src/services/api/openai/__tests__/convertTools.test.ts # 7 tests
|
||||
bun test src/services/api/openai/__tests__/modelMapping.test.ts # 6 tests
|
||||
```
|
||||
|
||||
当前测试覆盖：**39 tests / 73 assertions / 0 fail**。
|
||||
|
||||
### 测试覆盖矩阵
|
||||
|
||||
| 功能 | convertMessages | convertTools | streamAdapter | modelMapping |
|
||||
|---|---|---|---|---|
|
||||
| 文本消息转换 | ✅ | | | |
|
||||
| tool_use 转换 | ✅ | | | |
|
||||
| tool_result 转换 | ✅ | | | |
|
||||
| thinking 剥离 | ✅ | | | |
|
||||
| 完整对话流程 | ✅ | | | |
|
||||
| 工具 schema 转换 | | ✅ | | |
|
||||
| tool_choice 映射 | | ✅ | | |
|
||||
| 纯文本流 | | | ✅ | |
|
||||
| 工具调用流 | | | ✅ | |
|
||||
| 混合文本+工具 | | | ✅ | |
|
||||
| finish_reason 映射 | | | ✅ | |
|
||||
| thinking 流 | | | ✅ | |
|
||||
| thinking+text 切换 | | | ✅ | |
|
||||
| thinking+tool_use 切换 | | | ✅ | |
|
||||
| 块索引正确性 | | | ✅ | |
|
||||
| cached_tokens 映射 | | | ✅ | |
|
||||
| OPENAI_MODEL 覆盖 | | | | ✅ |
|
||||
| 默认模型映射 | | | | ✅ |
|
||||
| 未知模型透传 | | | | ✅ |
|
||||
| [1m] 后缀剥离 | | | | ✅ |
|
||||
|
||||
## 端到端验证
|
||||
|
||||
```bash
|
||||
# 1. 安装依赖
|
||||
bun install
|
||||
|
||||
# 2. 运行单元测试
|
||||
bun test src/services/api/openai/__tests__/
|
||||
|
||||
# 3. 连接实际端点（以 Ollama 为例）
|
||||
CLAUDE_CODE_USE_OPENAI=1 \
|
||||
OPENAI_API_KEY=ollama \
|
||||
OPENAI_BASE_URL=http://localhost:11434/v1 \
|
||||
OPENAI_MODEL=qwen2.5-coder-32b \
|
||||
bun run dev
|
||||
|
||||
# 4. 连接 DeepSeek（测试 thinking 支持）
|
||||
CLAUDE_CODE_USE_OPENAI=1 \
|
||||
OPENAI_API_KEY=sk-xxx \
|
||||
OPENAI_BASE_URL=https://api.deepseek.com/v1 \
|
||||
OPENAI_MODEL=deepseek-reasoner \
|
||||
bun run dev
|
||||
|
||||
# 5. 确认现有测试不受影响
|
||||
bun test # 无 CLAUDE_CODE_USE_OPENAI 时走原有路径
|
||||
```
|
||||
|
||||
## 代码统计
|
||||
|
||||
| 类别 | 行数 |
|
||||
|---|---|
|
||||
| 新增源码 | ~620 行 |
|
||||
| 新增测试 | ~450 行 |
|
||||
| 改动现有代码 | ~25 行 |
|
||||
| **总计** | **~1100 行** |
|
||||
@@ -1,35 +0,0 @@
|
||||
# 社区项目 & 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 |
|
||||
|
||||
## Blog
|
||||
|
||||
| 链接 | 作者 |
|
||||
|------|------|
|
||||
| [blog.xiaohuangyu.space](https://blog.xiaohuangyu.space/) | @eatmoreduck |
|
||||
@@ -1,263 +0,0 @@
|
||||
---
|
||||
title: "Auto Mode - AI 分类器驱动的自主执行模式"
|
||||
description: "详解 Claude Code 的 auto mode：基于 transcript classifier 的自动权限决策、两阶段分类流水线、危险权限剥离机制、模式切换状态管理、以及与 plan mode 的协作方式。"
|
||||
keywords: ["auto mode", "yoloClassifier", "transcript classifier", "权限分类", "自动执行", "两阶段分类"]
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
Auto mode 是 Claude Code 的一种权限模式，让 AI 进入**连续自主执行**状态。与传统模式（每个敏感操作都弹出权限对话框等待用户审批）不同，auto mode 使用 AI 分类器（transcript classifier）自动判断每个工具调用是否安全，从而实现无中断的执行体验。
|
||||
|
||||
```
|
||||
权限模式层级：
|
||||
|
||||
default → auto → bypassPermissions
|
||||
（逐项确认） （AI 分类器审批） （全部放行）
|
||||
```
|
||||
|
||||
## 核心架构
|
||||
|
||||
### 1. AI 分类器（yoloClassifier）
|
||||
|
||||
分类器是 auto mode 的核心，位于 `src/utils/permissions/yoloClassifier.ts`。
|
||||
|
||||
每个工具调用经过分类器评估，返回三种裁决之一：
|
||||
|
||||
| 裁决 | 含义 | 处理方式 |
|
||||
|------|------|---------|
|
||||
| **allow** | 操作安全 | 直接执行，用户无感知 |
|
||||
| **deny** | 操作危险 | 拒绝执行，向 AI 返回拒绝消息 |
|
||||
| **ask** | 无法确定 | 回退到传统权限对话框 |
|
||||
|
||||
分类器的判断基于完整的对话上下文（transcript），而不仅仅看单条命令——它能理解操作的意图和上下文。
|
||||
|
||||
### 2. 两阶段分类流水线
|
||||
|
||||
分类器支持两阶段 XML 分类（`classifyYoloActionXml`）：
|
||||
|
||||
```
|
||||
Stage 1 — "fast"（快速判断）
|
||||
├── max_tokens=64，stop_sequences 触发即时 yes/no
|
||||
├── 如果 allow → 直接放行（最快路径）
|
||||
└── 如果 block → 进入 Stage 2
|
||||
|
||||
Stage 2 — "thinking"（深度思考）
|
||||
├── chain-of-thought 推理
|
||||
├── 减少误报（false positives）
|
||||
└── 最终决定 allow / deny / ask
|
||||
```
|
||||
|
||||
两个阶段共享相同的 system prompt 和 user content，利用 API 的 prompt caching（1 小时 TTL）优化性能。
|
||||
|
||||
可通过配置选择模式：
|
||||
- `'both'`（默认）— 两阶段都跑
|
||||
- `'fast'` — 只跑 Stage 1
|
||||
- `'thinking'` — 只跑 Stage 2
|
||||
|
||||
### 3. 分类器结果类型
|
||||
|
||||
```typescript
|
||||
// src/types/permissions.ts
|
||||
type YoloClassifierResult = {
|
||||
thinking?: string // 分类器的推理过程
|
||||
shouldBlock: boolean // 是否阻止
|
||||
reason: string // 决策原因
|
||||
unavailable?: boolean // 分类器是否不可用
|
||||
transcriptTooLong?: boolean // 对话是否超出上下文窗口
|
||||
model: string // 使用的分类器模型
|
||||
stage?: 'fast' | 'thinking' // 哪个阶段做出的决定
|
||||
// ... token 使用量、耗时等监控字段
|
||||
}
|
||||
```
|
||||
|
||||
## 安全机制
|
||||
|
||||
### 危险权限剥离
|
||||
|
||||
进入 auto mode 时，系统调用 `stripDangerousPermissionsForAutoMode()`（`permissionSetup.ts:510`），移除所有可能绕过分类器的 allow 规则。
|
||||
|
||||
被剥离的规则类型（`dangerousPatterns.ts`）：
|
||||
|
||||
| 规则类型 | 示例 | 剥离原因 |
|
||||
|---------|------|---------|
|
||||
| **Bash 代码执行** | `Bash(python:*)`, `Bash(node:*)` | 解释器可执行任意代码，绕过分类器审查 |
|
||||
| **Shell 入口** | `Bash(bash:*)`, `Bash(sh:*)` | 直接 shell 访问等同无限制 |
|
||||
| **Agent 规则** | `Agent(*)` | 任何 Agent allow 规则会绕过分类器审批子代理 |
|
||||
| **PowerShell 代码执行** | `PowerShell(node:*)` | 同 Bash 逻辑 |
|
||||
| **权限提升** | `Bash(sudo:*)`, `Bash(eval:*)` | 可执行任意命令 |
|
||||
|
||||
剥离的规则被暂存在 `strippedDangerousRules` 中，退出 auto mode 时通过 `restoreDangerousPermissions()` 恢复。
|
||||
|
||||
### 模型支持检测
|
||||
|
||||
不是所有模型都支持 auto mode。`modelSupportsAutoMode()`（`src/utils/betas.ts`）检查当前模型是否具备安全分类能力。不支持的模型无法进入 auto mode。
|
||||
|
||||
### Circuit Breaker 机制
|
||||
|
||||
`autoModeState.ts` 维护一个 circuit breaker 标志：
|
||||
|
||||
```typescript
|
||||
let autoModeCircuitBroken = false // 由远程配置控制
|
||||
```
|
||||
|
||||
当远程配置（GrowthBook `tengu_auto_mode_config.enabled`）设为 `'disabled'` 时，circuit breaker 触发，阻止 auto mode 的进入和继续使用。这为 Anthropic 提供了远程紧急关停能力。
|
||||
|
||||
## 模式切换状态管理
|
||||
|
||||
### 进入 Auto Mode
|
||||
|
||||
`transitionPermissionMode()`（`permissionSetup.ts:597`）处理所有模式切换：
|
||||
|
||||
```
|
||||
1. 检查 auto mode gate 是否开启（isAutoModeGateEnabled）
|
||||
2. 设置 autoModeActive = true
|
||||
3. 调用 stripDangerousPermissionsForAutoMode() 剥离危险规则
|
||||
4. 向对话注入 Auto Mode 系统提示
|
||||
```
|
||||
|
||||
### 退出 Auto Mode
|
||||
|
||||
```
|
||||
1. 设置 autoModeActive = false
|
||||
2. 设置 needsAutoModeExitAttachment = true（触发退出通知）
|
||||
3. 调用 restoreDangerousPermissions() 恢复被剥离的规则
|
||||
4. 向对话注入 "Exited Auto Mode" 提示
|
||||
```
|
||||
|
||||
### 触发路径
|
||||
|
||||
Auto mode 可通过以下方式激活：
|
||||
- CLI 参数 `--enable-auto-mode`
|
||||
- settings.json 中的 `autoMode` 配置
|
||||
- Plan mode 默认使用 auto mode 语义（`useAutoModeDuringPlan`，默认 true）
|
||||
- SDK 控制消息
|
||||
- REPL 中 Shift+Tab 切换
|
||||
|
||||
## 系统提示词
|
||||
|
||||
### 进入时（Full Instructions）
|
||||
|
||||
注入到对话中的指令（`messages.ts:3464`）：
|
||||
|
||||
> Auto mode is active. The user chose continuous, autonomous execution. You should:
|
||||
>
|
||||
> 1. **Execute immediately** — 直接实现，做合理假设
|
||||
> 2. **Minimize interruptions** — 常规决策自行判断，减少提问
|
||||
> 3. **Prefer action over planning** — 默认直接编码，不进 plan mode
|
||||
> 4. **Expect course corrections** — 用户可随时纠正
|
||||
> 5. **Do not take overly destructive actions** — 删除数据/修改生产系统仍需确认
|
||||
> 6. **Avoid data exfiltration** — 不主动分享密钥/内部文档
|
||||
|
||||
### 持续运行时（Sparse Instructions）
|
||||
|
||||
后续轮次注入简短提醒：
|
||||
|
||||
> Auto mode still active. Execute autonomously, minimize interruptions, prefer action over planning.
|
||||
|
||||
### 退出时（Exit Instructions）
|
||||
|
||||
> You have exited auto mode. Ask clarifying questions when the approach is ambiguous rather than making assumptions.
|
||||
|
||||
## 与 Plan Mode 的协作
|
||||
|
||||
Plan mode 默认使用 auto mode 语义（`getUseAutoModeDuringPlan()`，默认 true）。这意味着：
|
||||
|
||||
- Plan mode 进入时，如果 auto mode 可用，也会激活分类器
|
||||
- `isAutoModeActive()` 是权威信号（`prePlanMode`/`strippedDangerousRules` 不可靠）
|
||||
- 退出 plan mode 时会同时退出 auto mode
|
||||
|
||||
## 分类器不可用的降级策略
|
||||
|
||||
当分类器 API 不可用时（`unavailable: true` 或 `transcriptTooLong: true`）：
|
||||
|
||||
- 不会直接 allow — 回退到传统的权限对话框（ask）
|
||||
- 向 AI 发送消息："{model} is temporarily unavailable, so auto mode cannot determine the safety of {toolName} right now."
|
||||
- 确定性错误（如对话过长）不重试，直接降级
|
||||
|
||||
## 分类器 Prompt 模板
|
||||
|
||||
分类器的行为由三个 prompt 文件控制，位于 `src/utils/permissions/yolo-classifier-prompts/`。这些文件在构建时通过 `require()` 内联为字符串常量，运行时不可修改。
|
||||
|
||||
### auto_mode_system_prompt.txt
|
||||
|
||||
主系统提示词，定义分类器的角色、分类流程和决策类别。包含：
|
||||
|
||||
- **分类流程**：理解操作 → 检查用户意图 → 评估风险
|
||||
- **BLOCK 始终阻止**：外部代码执行、不可逆删除、未授权持久化、安全削弱、提权、网络服务
|
||||
- **BLOCK 除非明确意图**：CWD 外写入、系统包管理、git push、大规模变更
|
||||
- **ALLOW 安全操作**：读文件、搜索、git 只读命令、测试/lint/构建、CWD 内编辑
|
||||
- `<permissions_template>` 占位符 — 运行时替换为具体权限模板（external 或 anthropic）
|
||||
- 末尾 `Use the classify_result tool to report your classification.` — XML 模式下被替换为 `<block>` 标签格式说明
|
||||
|
||||
### permissions_external.txt
|
||||
|
||||
外部用户版本的权限模板。三个 `<user_*_to_replace>` 标签内包裹默认规则（bullet 格式），用户自定义规则**整体替换**默认值：
|
||||
|
||||
```
|
||||
<user_allow_rules_to_replace>
|
||||
- 默认 allow 规则 1
|
||||
- 默认 allow 规则 2
|
||||
</user_allow_rules_to_replace>
|
||||
```
|
||||
|
||||
- **allow**：9 条默认规则（只读命令、版本检查、git 只读、测试/lint/构建、包安装、CWD 内文件操作等）
|
||||
- **soft_deny**：10 条默认规则（外部代码执行、递归删除、shell 配置修改、提权、网络服务等）
|
||||
- **environment**：4 条环境描述（终端环境、auto mode 上下文、开发工具可用、语言/框架不限）
|
||||
|
||||
`getDefaultExternalAutoModeRules()` 从此文件提取 bullet 项，供 `claude auto-mode defaults` 命令输出。
|
||||
|
||||
### permissions_anthropic.txt
|
||||
|
||||
Anthropic 内部版本的权限模板。默认规则在标签**外部**，标签内为空，用户自定义规则以**追加**方式叠加：
|
||||
|
||||
```
|
||||
- 默认规则（在标签外，始终生效）
|
||||
<user_allow_rules_to_replace>
|
||||
</user_allow_rules_to_replace>
|
||||
```
|
||||
|
||||
相比 external 版本，额外包含：
|
||||
- 云 CLI 只读命令（aws describe, gcloud describe, kubectl get 等）
|
||||
- 基础设施即代码 plan 命令（terraform plan, pulumi preview 等）
|
||||
- 对应的 deny 规则（云资源创建/修改/删除、IaC apply、生产环境访问等）
|
||||
|
||||
### 模板替换流程
|
||||
|
||||
```
|
||||
buildYoloSystemPrompt()
|
||||
├── BASE_PROMPT.replace('<permissions_template>', EXTERNAL/ANTHROPIC_TEMPLATE)
|
||||
├── .replace(<user_allow_rules_to_replace>, userAllow ?? defaults)
|
||||
├── .replace(<user_deny_rules_to_replace>, userDeny ?? defaults)
|
||||
└── .replace(<user_environment_to_replace>, userEnvironment ?? defaults)
|
||||
```
|
||||
|
||||
- 外部模板：用户设置非空时**替换**对应标签内容，否则保留默认值
|
||||
- 内部模板：用户设置**追加**到默认值之后（标签在末尾为空）
|
||||
|
||||
## 当前状态说明
|
||||
|
||||
> **注意**：auto mode 的完整代码逻辑已存在于代码库中，但依赖 `feature('TRANSCRIPT_CLASSIFIER')` feature flag。
|
||||
> 在当前反编译版本中，`feature()` 始终返回 `false`，因此 auto mode 不可用。
|
||||
> 要启用需将 `feature('TRANSCRIPT_CLASSIFIER')` 改为 `true`，并确保 GrowthBook 配置源有合理的 fallback 默认值。
|
||||
|
||||
Prompt 模板文件为**重建产物**——原始文件在反编译过程中丢失，已根据代码逻辑和 `yoloClassifier.ts` 中的替换模式重新编写。
|
||||
|
||||
## 相关源码索引
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `src/utils/permissions/yoloClassifier.ts` | 分类器核心实现 |
|
||||
| `src/utils/permissions/autoModeState.ts` | Auto mode 状态管理 |
|
||||
| `src/utils/permissions/permissionSetup.ts` | 模式切换、危险权限剥离 |
|
||||
| `src/utils/permissions/dangerousPatterns.ts` | 危险命令模式列表 |
|
||||
| `src/utils/permissions/classifierDecision.ts` | 分类器决策处理 |
|
||||
| `src/utils/permissions/classifierShared.ts` | 分类器共享逻辑 |
|
||||
| `src/utils/permissions/bashClassifier.ts` | Bash 命令分类规则 |
|
||||
| `src/utils/permissions/bypassPermissionsKillswitch.ts` | bypass 权限熔断器 |
|
||||
| `src/utils/permissions/yolo-classifier-prompts/auto_mode_system_prompt.txt` | 分类器主系统提示词 |
|
||||
| `src/utils/permissions/yolo-classifier-prompts/permissions_external.txt` | 外部权限模板 |
|
||||
| `src/utils/permissions/yolo-classifier-prompts/permissions_anthropic.txt` | 内部权限模板 |
|
||||
| `src/cli/handlers/autoMode.ts` | CLI `auto-mode` 子命令处理 |
|
||||
| `src/utils/messages.ts` | Auto mode 系统提示词注入 |
|
||||
| `src/types/permissions.ts` | 权限类型定义 |
|
||||
| `src/utils/betas.ts` | 模型 auto mode 支持检测 |
|
||||
@@ -1,564 +1,215 @@
|
||||
---
|
||||
title: "沙箱机制 - 权限系统之外的第二道防线"
|
||||
description: "系统性梳理 Claude Code 的沙箱设计：什么时候会进沙箱、什么时候不会、如何与权限系统联动、默认限制了什么、不同平台下行为有什么差异，以及用户在被拦截时会看到什么。"
|
||||
keywords: ["沙箱", "sandbox", "权限", "Bash", "PowerShell", "bubblewrap", "sandbox-exec", "纵深防御"]
|
||||
title: "沙箱机制 - 权限之外的第二道防线"
|
||||
description: "深入 Claude Code 沙箱机制：文件系统隔离、网络限制和资源约束，即使命令通过权限审批，沙箱仍可限制其行为范围。"
|
||||
keywords: ["沙箱", "sandbox", "文件隔离", "安全沙箱", "命令隔离"]
|
||||
---
|
||||
|
||||
## 一句话结论
|
||||
## 权限之外的第二道防线
|
||||
|
||||
这个项目里的沙箱不是用来替代权限系统，而是用来给 **shell 命令** 再套一层 OS 级能力边界：
|
||||
权限系统决定"这条命令能不能执行"，沙箱决定"执行时能做到什么程度"。
|
||||
|
||||
- 权限系统决定：这次工具调用要不要执行
|
||||
- 沙箱决定：就算执行了，这个子进程最多能碰到哪些文件、哪些网络目标
|
||||
即使一条命令通过了权限审批，沙箱仍然可以限制它的行为。两者构成纵深防御的两层：
|
||||
- **权限层**（应用级）：在工具调用前检查，决定是否弹窗审批
|
||||
- **沙箱层**（OS 级）：在进程级别强制约束，即使 AI 生成了恶意命令也无法突破
|
||||
|
||||
两者组合起来，才构成真正的 Defense-in-Depth。
|
||||
## 执行链路：从用户输入到沙箱包裹
|
||||
|
||||
## 实现分层：仓库里的适配器，加底层运行时
|
||||
一条 Bash 命令的完整执行路径如下：
|
||||
|
||||
这个项目的“沙箱实现”其实分成两层：
|
||||
|
||||
- 这一层仓库自己负责：策略、配置转换、启停判断、命令包裹、清理和权限联动
|
||||
- 真正做 OS 级隔离的是外部运行时 `@anthropic-ai/sandbox-runtime`
|
||||
|
||||
在 `src/utils/sandbox/sandbox-adapter.ts` 里，可以很清楚地看到这条边界：项目导入 `SandboxManager as BaseSandboxManager`、`SandboxViolationStore` 等运行时对象，然后在外面再包一层符合 Claude Code 自身权限模型的适配器。
|
||||
|
||||
底层隔离在不同平台上的落地也不是同一套实现：
|
||||
|
||||
- macOS 走 `sandbox-exec`
|
||||
- Linux / WSL2 走 `bubblewrap + seccomp`
|
||||
- Windows 原生不支持这套 shell 沙箱
|
||||
|
||||
所以如果只看这个仓库，容易误以为“沙箱都是它自己做的”。更准确的说法是：这个仓库决定**该不该启、该怎么配、该怎么接进工具链**，真正的 OS 级约束由外部 runtime 执行。
|
||||
|
||||
## 它到底解决什么问题
|
||||
|
||||
如果只有应用层权限系统，Claude Code 需要在命令执行前尽量判断：
|
||||
|
||||
- 这条命令是不是只读
|
||||
- 会不会写危险路径
|
||||
- 会不会连到外网
|
||||
- 会不会通过复合命令、重定向、子进程、解释器脚本绕过检查
|
||||
|
||||
这些检查都很有价值，但它们本质上仍然是“执行前推断”。而 shell 命令的真实副作用经常取决于运行时行为：
|
||||
|
||||
- `bash script.sh`
|
||||
- `python -c "..."`
|
||||
- `make`
|
||||
- `npm install`
|
||||
- 某个命令再启动另一个子进程
|
||||
|
||||
沙箱的作用，就是把这些运行时行为的能力范围压缩到一个明确边界内。即使应用层检查漏了，命令也不能随意写系统目录或访问不允许的网络目标。
|
||||
|
||||
## 为什么“拦住它”本身就是价值
|
||||
|
||||
很多人第一次看到沙箱会直觉觉得：
|
||||
|
||||
> 如果连 `/etc/hosts` 这种文件都默认不让我改，那沙箱是不是没什么用？
|
||||
|
||||
这个项目的答案正好相反。沙箱不是为了让 `/etc/...` 这种系统路径也能随便改，而是为了把 shell 命令的能力压缩到一个可接受的安全边界里：
|
||||
|
||||
- 权限系统负责判断“要不要执行”
|
||||
- 沙箱负责限制“就算执行了，最多能做到什么”
|
||||
|
||||
`/etc/...` 被默认拦住，说明这条边界真的在生效，而不是说明沙箱没价值。更具体地说，沙箱至少补上了 4 件权限系统单独做不好的事。
|
||||
|
||||
### 1. 给 shell 一个 OS 级兜底
|
||||
|
||||
`src/utils/bash/ast.ts` 开头就写得很明确：Bash AST 分析不是沙箱，它只是在判断我们能不能可靠地理解命令结构，不能阻止危险命令真的运行。
|
||||
|
||||
这就是为什么应用层再聪明，也很难仅靠“执行前推断”覆盖完整风险面。像下面这些命令，真实副作用都要到运行时才完全展开：
|
||||
|
||||
- `bash script.sh`
|
||||
- `python -c "..."`
|
||||
- `make`
|
||||
- `npm install`
|
||||
- 一个命令再起新的子进程
|
||||
|
||||
沙箱的价值就在这里。即使前面的分析漏了，进程到了 OS 层以后，仍然只能写允许目录、访问允许域名，真正把 shell 的能力压缩进运行时边界。
|
||||
|
||||
### 2. 让“安全边界内”的命令可以少弹窗甚至自动放行
|
||||
|
||||
默认沙箱白名单里就包含当前工作目录和 Claude 临时目录，这也是为什么工作区内的大多数开发命令都能顺畅运行：
|
||||
|
||||
- `npm test`
|
||||
- `rg`
|
||||
- `git status`
|
||||
- 工作区内的构建、测试和生成文件
|
||||
|
||||
项目专门提供了 `autoAllowBashIfSandboxed`。它的核心思路不是“更大胆地信任模型”，而是“既然命令已经被 OS 级边界收紧，就没必要再让用户为大量低风险 Bash 命令反复点确认”。
|
||||
|
||||
换句话说，没有沙箱的话，系统通常只剩两种都不太理想的选择：
|
||||
|
||||
- 频繁弹窗，让工作流很碎
|
||||
- 更激进地信任应用层判断，把风险全压在静态分析上
|
||||
|
||||
### 3. 把“出错”的后果从系统级破坏，降成一次受限失败
|
||||
|
||||
这也是 Defense-in-Depth 最实际的一层收益。模型偶尔会出错，应用层规则也可能有漏判。沙箱的意义不是假设前面永远正确，而是即使前面偶尔判错，后果也尽量可控。
|
||||
|
||||
例如这类命令：
|
||||
|
||||
- `sudo tee /etc/hosts`
|
||||
- `mv ... ~/.ssh/...`
|
||||
- `curl 外网 | bash`
|
||||
|
||||
如果它们发生在没有运行时约束的环境里，可能就是直接修改系统、用户配置或把未知脚本落到机器上。放进沙箱之后，更常见的结果会变成：因为写权限或网络权限不满足而失败。它不是“什么都没发生”，而是把一次潜在的系统级破坏降成一次受限失败。
|
||||
|
||||
### 4. 拦截运行时绕过和逃逸路径
|
||||
|
||||
这个仓库在 `src/utils/sandbox/sandbox-adapter.ts` 里专门把一些高风险路径额外加入 `denyWrite`，例如：
|
||||
|
||||
- `settings.json`
|
||||
- `.claude/skills`
|
||||
- 一些 bare git repo 相关路径
|
||||
|
||||
它还专门处理 bare git repo 逃逸这一类攻击面。它们的意义不是“让更多命令通过”，而是“即使命令已经执行，也别让它顺手把护栏本身拆掉”，避免通过改配置、改技能、改 git 结构来扩大后续权限。
|
||||
|
||||
所以更准确的表述不是：
|
||||
|
||||
- “沙箱把 `/etc` 拦了，所以没用”
|
||||
|
||||
而是：
|
||||
|
||||
- “沙箱把 shell 的默认权限收缩到工作区和白名单里，因此系统级路径默认写不了；正因为这样，项目才敢把一大批工作区内命令自动放行。”
|
||||
|
||||
## 设计边界：它保护什么，不保护什么
|
||||
|
||||
### 保护对象
|
||||
|
||||
- Bash / shell 命令执行
|
||||
- 在支持平台上的 PowerShell 执行
|
||||
- shell 子进程的文件系统写入范围
|
||||
- shell 子进程的网络访问范围
|
||||
- 一些已知的高风险路径和沙箱逃逸向量
|
||||
|
||||
### 不直接保护的对象
|
||||
|
||||
- `FileEditTool` / `FileWriteTool` 这类直接文件工具
|
||||
- 纯应用层的权限弹窗和规则匹配
|
||||
- Bash AST 解析本身
|
||||
|
||||
尤其要注意一点：Bash AST 分析不是沙箱。源码自己写得很明确，它只回答“我们能不能可信地提取 argv 结构”，并不负责阻止危险命令真正运行。
|
||||
|
||||
## 哪些场景会走沙箱
|
||||
|
||||
### 1. 启动阶段先判断“沙箱能不能用”
|
||||
|
||||
沙箱不是等到第一条命令执行时才临时判断的。REPL / CLI 启动时，就会先检查当前环境是否真的具备沙箱条件。核心判断包括：
|
||||
|
||||
1. 当前平台是否受底层 runtime 支持
|
||||
2. 依赖是否齐全
|
||||
3. `sandbox.enabled` 是否打开
|
||||
4. 当前平台是否落在 `enabledPlatforms` 范围内
|
||||
|
||||
如果用户显式开启了沙箱，但当前环境不满足条件，启动期会先给出 warning；如果同时配置了 `sandbox.failIfUnavailable`，则会直接拒绝启动，而不是悄悄降级成无沙箱模式。
|
||||
|
||||
另外，启动时不只是“看一眼能不能用”，而是真的会调用初始化流程，把当前设置转换成 runtime 配置并交给底层 `BaseSandboxManager.initialize(...)`。后续如果设置变化，还会通过 `updateConfig(...)` 热更新，而不是要求重启整个会话。
|
||||
|
||||
### 2. BashTool 默认会走
|
||||
|
||||
只要满足下面条件，Bash 命令默认会进入沙箱：
|
||||
|
||||
1. 当前平台支持沙箱
|
||||
2. 沙箱依赖齐全
|
||||
3. `sandbox.enabled` 打开
|
||||
4. 当前平台在 `enabledPlatforms` 范围内
|
||||
5. 这条命令没有被显式排除
|
||||
6. 这次调用没有被允许以 `dangerouslyDisableSandbox` 绕过
|
||||
|
||||
对应入口在 `src/tools/BashTool/shouldUseSandbox.ts` 和 `src/utils/sandbox/sandbox-adapter.ts`。
|
||||
|
||||
### 3. PowerShell 只在支持平台上走
|
||||
|
||||
PowerShell 的处理要更细一点：
|
||||
|
||||
- Linux / macOS / WSL2：可以走沙箱
|
||||
- Windows 原生：不支持沙箱，直接返回 `shouldUseSandbox: false`
|
||||
|
||||
也就是说，Windows 原生上的 PowerShell 只能依赖权限系统，不会有 OS 级沙箱兜底。
|
||||
|
||||
### 4. Hook 命令会复用“网络专用沙箱”
|
||||
|
||||
Hook 不是完整复用 Bash 那套文件系统限制，而是额外套了一层 **network-only sandbox**：
|
||||
|
||||
- 重点拦网络访问
|
||||
- 文件系统不额外收紧到 Bash 那个程度
|
||||
|
||||
这是因为 Hook 往往不是模型直接下发的 Bash 工具调用，而是系统/插件的外部扩展点。
|
||||
|
||||
## 哪些场景不会走沙箱
|
||||
|
||||
### 1. FileEditTool / FileWriteTool
|
||||
|
||||
这类工具不是靠 shell 修改文件，而是直接在应用层做文件 I/O，所以它们不通过 `Shell.exec()`，自然也不会被 `wrapWithSandbox()` 包裹。
|
||||
|
||||
它们走的是另一条链路：
|
||||
|
||||
- `checkWritePermissionForTool()`
|
||||
- `checkPathSafetyForAutoEdit()`
|
||||
- 工作目录检查
|
||||
- allow/ask/deny 规则
|
||||
|
||||
因此：
|
||||
|
||||
- “shell 改 `/etc/hosts`”通常是沙箱在 OS 层拦
|
||||
- “FileEdit 改 `/etc/hosts`”通常是权限系统在应用层拦
|
||||
|
||||
### 2. 明确排除的命令
|
||||
|
||||
如果命中 `sandbox.excludedCommands`，这条命令会直接跳过沙箱。
|
||||
|
||||
支持三类模式：
|
||||
|
||||
- 精确匹配
|
||||
- 前缀匹配
|
||||
- 通配符匹配
|
||||
|
||||
### 3. 允许 unsandboxed fallback 的命令
|
||||
|
||||
如果：
|
||||
|
||||
- 这次调用显式设置了 `dangerouslyDisableSandbox: true`
|
||||
- 并且策略允许 `allowUnsandboxedCommands`
|
||||
|
||||
那它也可以不进沙箱。
|
||||
|
||||
这个设计是有意保留的，但命名也故意写得很重：`dangerouslyDisableSandbox`，提醒这是例外路径，不应当成为默认习惯。
|
||||
|
||||
## 完整执行链路
|
||||
|
||||
可以把整个过程拆成两段来看：启动期先把沙箱准备好，命令期再决定“这条命令要不要进去”。
|
||||
|
||||
### 启动期链路
|
||||
|
||||
```text
|
||||
REPL / CLI 启动
|
||||
-> isSandboxingEnabled()
|
||||
-> convertToSandboxRuntimeConfig(settings)
|
||||
-> BaseSandboxManager.initialize(runtimeConfig, callback)
|
||||
-> 设置变化时 BaseSandboxManager.updateConfig(newConfig)
|
||||
```
|
||||
用户输入 → BashTool.call()
|
||||
→ shouldUseSandbox(input) ─── 是否需要沙箱？
|
||||
→ Shell.exec(command, { shouldUseSandbox })
|
||||
→ SandboxManager.wrapWithSandbox(command)
|
||||
→ spawn(wrapped_command) ─── 实际进程创建
|
||||
```
|
||||
|
||||
这一段回答的是：当前会话里有没有一个可用、已初始化、能处理网络授权回调的沙箱 runtime。
|
||||
关键判定发生在 `shouldUseSandbox()`（`src/tools/BashTool/shouldUseSandbox.ts`），它执行以下检查：
|
||||
|
||||
### 命令期链路
|
||||
1. **全局开关**：`SandboxManager.isSandboxingEnabled()` — 检查平台支持 + 依赖完整性 + 用户设置
|
||||
2. **显式跳过**：如果 `dangerouslyDisableSandbox: true` 且策略允许（`allowUnsandboxedCommands`），则不走沙箱
|
||||
3. **排除列表**：用户可在 `settings.json` 中配置 `sandbox.excludedCommands`，匹配的命令跳过沙箱
|
||||
4. **默认行为**：以上条件都不满足时，**进入沙箱**
|
||||
|
||||
典型 Bash 执行链路如下：
|
||||
## `shouldUseSandbox()` 判定逻辑详解
|
||||
|
||||
```text
|
||||
用户请求
|
||||
-> BashTool.checkPermissions()
|
||||
-> shouldUseSandbox(input)
|
||||
-> Shell.exec(command, { shouldUseSandbox: true/false })
|
||||
-> SandboxManager.wrapWithSandbox(...)
|
||||
-> spawn(wrapped command)
|
||||
-> 运行结束后 cleanupAfterCommand()
|
||||
```typescript
|
||||
// src/tools/BashTool/shouldUseSandbox.ts
|
||||
function shouldUseSandbox(input: Partial<SandboxInput>): boolean {
|
||||
// 1. 全局未启用 → 直接跳过
|
||||
if (!SandboxManager.isSandboxingEnabled()) return false
|
||||
|
||||
// 2. 显式禁用 + 策略允许 → 跳过
|
||||
if (input.dangerouslyDisableSandbox &&
|
||||
SandboxManager.areUnsandboxedCommandsAllowed()) return false
|
||||
|
||||
// 3. 无命令 → 跳过
|
||||
if (!input.command) return false
|
||||
|
||||
// 4. 匹配排除列表 → 跳过
|
||||
if (containsExcludedCommand(input.command)) return false
|
||||
|
||||
// 5. 其他情况 → 必须沙箱化
|
||||
return true
|
||||
}
|
||||
```
|
||||
|
||||
这里真正把命令“包进沙箱”的关键点是 `Shell.exec()`。它会在真正 `spawn(...)` 之前调用 `SandboxManager.wrapWithSandbox(...)`，把原始命令改写成底层 runtime 可执行的沙箱命令串。命令结束后如果本次是 sandboxed execution，再调用 `cleanupAfterCommand()` 清理运行时残留。
|
||||
|
||||
其中有两个容易混淆的判定点：
|
||||
|
||||
### 判定点 A：要不要进沙箱
|
||||
|
||||
这是 `shouldUseSandbox()` 的职责。
|
||||
|
||||
它回答的是：
|
||||
|
||||
> 这条命令要不要被 OS 级沙箱包起来执行？
|
||||
|
||||
### 判定点 B：这条命令要不要弹权限确认
|
||||
|
||||
这是权限系统和 Bash 权限检查的职责。
|
||||
|
||||
它回答的是：
|
||||
|
||||
> 这条命令在应用层看来，是 `allow`、`ask` 还是 `deny`？
|
||||
|
||||
这两个判定点是并列协作的，不是互相替代的。
|
||||
|
||||
## 默认沙箱到底限制了什么
|
||||
|
||||
沙箱运行时配置最终由 `convertToSandboxRuntimeConfig()` 生成。它会把项目自己的设置、权限规则和安全加固逻辑，转换成底层运行时需要的配置。
|
||||
|
||||
这一步很关键，因为这个项目的沙箱配置不是一份静态表，而是从 Claude Code 自己的权限系统里“翻译”出来的。
|
||||
|
||||
### 这些限制是怎么从权限系统推导出来的
|
||||
|
||||
- `WebFetch(domain:...)` 和 `sandbox.network.allowedDomains` 会被合并成网络白名单
|
||||
- `Edit(...)` / `Read(...)` 这类权限规则会被翻译成文件系统读写限制
|
||||
- `sandbox.filesystem.allowWrite` / `allowRead` / `denyWrite` / `denyRead` 会继续叠加到最终 runtime 配置上
|
||||
|
||||
也就是说，沙箱不是独立维护另一套完全平行的安全策略，而是把“Claude 认为哪些路径或域名应该被允许”落地成 OS 级约束。
|
||||
|
||||
### 文件系统默认写入范围
|
||||
|
||||
默认 `allowWrite` 只有两类：
|
||||
|
||||
- 当前工作目录 `.`
|
||||
- Claude 的临时目录
|
||||
|
||||
这意味着：
|
||||
|
||||
- 工作区内的构建、测试、生成临时文件通常能正常运行
|
||||
- 根路径如 `/etc/...`、`/usr/...`、`/var/...` 默认不在写白名单里
|
||||
|
||||
### 文件系统额外写入来源
|
||||
|
||||
额外允许写入的路径，主要来自这些来源：
|
||||
|
||||
- `sandbox.filesystem.allowWrite`
|
||||
- `Edit(...)` 规则推导出的路径
|
||||
- `/add-dir` 或 `--add-dir` 增加的目录
|
||||
- git worktree 主仓库所需路径
|
||||
|
||||
这里还有一个很容易漏掉的细节：适配层会专门处理 worktree 主仓库和 bare git repo 这种仓库级特殊路径，避免在隔离后把正常开发流程误伤，或者反过来留下逃逸面。
|
||||
|
||||
### 强制 deny 的路径
|
||||
|
||||
即使有别的配置，项目还会额外加固一些高风险路径，例如：
|
||||
|
||||
- settings 文件
|
||||
- `.claude/skills`
|
||||
- 一些 bare git repo 相关路径
|
||||
|
||||
这样做的原因是：这些路径一旦可写，攻击者可能反过来修改 Claude Code 自己的配置、技能或 git 行为，从而扩大权限。
|
||||
|
||||
### 网络限制
|
||||
|
||||
网络白名单来自两部分：
|
||||
|
||||
- `sandbox.network.allowedDomains`
|
||||
- `WebFetch(domain:...)` 这类权限规则
|
||||
|
||||
被允许的域名会进入沙箱网络配置；不在白名单里的访问，在运行时会被拦截或触发额外的网络授权流程。
|
||||
|
||||
## `autoAllowBashIfSandboxed` 的真实意义
|
||||
|
||||
这是沙箱设计里最值得注意的开关之一。
|
||||
|
||||
它表达的是这样一个信任假设：
|
||||
|
||||
> 如果命令已经被 OS 级沙箱约束在安全边界内，那么应用层就没有必要再对大量低风险 Bash 命令逐条弹确认框。
|
||||
|
||||
因此，当这个开关开启时：
|
||||
|
||||
- 命令会先检查显式 `deny` / `ask` 规则
|
||||
- 如果没有命中这些硬规则
|
||||
- 且命令确实会在沙箱里执行
|
||||
- 那么 BashTool 可以直接自动允许它运行
|
||||
|
||||
这里还有一个边界条件特别值得写清楚：它只对“真正会进沙箱的命令”生效。像这些情况，仍然不能直接吃到这个 shortcut：
|
||||
|
||||
- 命中了 `excludedCommands`
|
||||
- 显式使用了 `dangerouslyDisableSandbox: true`
|
||||
- 当前平台根本不支持沙箱
|
||||
|
||||
这些命令依然要遵守正常的 `ask` 规则，因为它们没有拿到 OS 级约束带来的那层安全兜底。
|
||||
|
||||
这也是沙箱存在的一个核心产品价值：不是让更多危险操作通过，而是让更多**受限范围内的常规命令**可以无感运行。
|
||||
|
||||
## 为什么“沙箱把 `/etc` 拦了”反而说明它有用
|
||||
|
||||
前面的“四个核心价值”解释的是原理，这里把结论再落回最常见的直觉疑问上：为什么一个默认不让你写 `/etc` 的系统，反而更值得信任？
|
||||
|
||||
因为 Claude Code 日常最常跑的不是系统管理命令，而是开发命令。例如：
|
||||
|
||||
- `npm test`
|
||||
- `npm install`
|
||||
- `cargo build`
|
||||
- `pytest`
|
||||
- `rg`
|
||||
- `git status`
|
||||
|
||||
这些命令本来就应该只在工作区和少量临时目录里活动。沙箱把 shell 的默认能力收缩到这个范围后，项目才敢在应用层减少弹窗、启用 `autoAllowBashIfSandboxed`、提高自动化程度。
|
||||
|
||||
所以这个问题的正确落点不是“它为什么不帮我改 `/etc`”，而是“它能不能在不碰 `/etc` 的前提下，让大量正常开发命令更安全、更顺滑地运行”。从这个角度看，`/etc` 默认写不了并不是缺点，而是整个自动化体验成立的前提。
|
||||
|
||||
## 平台差异
|
||||
|
||||
### macOS
|
||||
|
||||
- 底层使用 `sandbox-exec`
|
||||
- 路径和网络规则通过 Seatbelt profile 落地
|
||||
- 属于原生 OS 级进程隔离
|
||||
|
||||
### Linux
|
||||
|
||||
- 底层使用 `bubblewrap + seccomp`
|
||||
- 会建立 mount / PID / network 等隔离
|
||||
- Linux 上对 glob 路径的支持比 macOS 弱一些
|
||||
- 某些运行后残留需要在 `cleanupAfterCommand()` 中清理
|
||||
|
||||
### WSL
|
||||
|
||||
- 只支持 WSL2
|
||||
- WSL1 视为不支持平台
|
||||
|
||||
### Windows 原生
|
||||
|
||||
- 原生 PowerShell/Bash 不支持这个沙箱体系
|
||||
- 因此只能依赖权限系统和工具级检查
|
||||
|
||||
这也是为什么你前面问“改 C 盘文件会不会走沙箱”时，答案会分成：
|
||||
|
||||
- Windows 原生：通常不走
|
||||
- Linux/macOS/WSL2：shell 才可能走
|
||||
|
||||
## 工作区内外：应用层与沙箱层如何配合
|
||||
|
||||
### 工作区内路径
|
||||
|
||||
工作区内路径通常有两层保护：
|
||||
|
||||
1. 应用层权限检查
|
||||
2. 沙箱默认允许写当前工作目录
|
||||
|
||||
这使得“工作区内构建/测试/格式化/生成文件”成为最顺滑的一条路径。
|
||||
|
||||
### 工作区外路径
|
||||
|
||||
工作区外路径则更严格：
|
||||
|
||||
- 应用层通常会视为高风险，要求确认或阻止
|
||||
- 即使应用层允许，如果不在沙箱白名单里，运行时也会失败
|
||||
|
||||
这就形成了双保险。
|
||||
|
||||
### Linux 根路径 `/etc/...`
|
||||
|
||||
对于 Linux 上的根路径文件，通常会出现两种情况：
|
||||
|
||||
- **shell 路径**：命令会进沙箱，但沙箱默认没有 `/etc` 写权限，所以运行时被拦
|
||||
- **文件工具路径**：不走沙箱，而是在应用层直接被文件权限检查拦住
|
||||
|
||||
## 用户真的会看到什么
|
||||
|
||||
被拦截并不是同一种体验，至少有三类。
|
||||
|
||||
### 1. 执行前的权限确认
|
||||
|
||||
如果应用层在执行前就判定为 `ask`，用户会看到标准权限对话框：
|
||||
|
||||
- Bash 权限确认
|
||||
- FileEdit / FileWrite 权限确认
|
||||
- 其他工具自己的权限确认 UI
|
||||
|
||||
这种提示发生在命令还没真正运行之前。
|
||||
|
||||
### 2. 执行中的沙箱违规
|
||||
|
||||
如果命令已经进入沙箱，运行时才触发违规：
|
||||
|
||||
- 命令会失败
|
||||
- stderr 会被附加 `<sandbox_violations>` 标签供模型理解
|
||||
- UI 会清理这些标签再显示给用户
|
||||
- 同时 `SandboxViolationStore` 会记录违规事件
|
||||
|
||||
这意味着用户通常能看到：
|
||||
|
||||
- 命令失败本身
|
||||
- 以及“最近有多少次 sandbox blocked”之类的界面提示
|
||||
|
||||
### 3. 网络越界请求
|
||||
|
||||
网络是个特例。
|
||||
|
||||
当沙箱外的 host 访问需要额外确认时，项目会弹出一个专门的网络授权对话框，例如：
|
||||
|
||||
- `Network request outside of sandbox`
|
||||
|
||||
这里和文件系统运行时拦截不同，它有明确的交互式授权 UI。
|
||||
|
||||
## 为什么文件系统越界通常不弹“再放行一次”
|
||||
|
||||
这是一个非常有意的设计选择。
|
||||
|
||||
对文件系统来说，项目更倾向于：
|
||||
|
||||
- 执行前在应用层 ask
|
||||
- 或者执行后让命令直接因沙箱失败
|
||||
|
||||
而不是在运行到一半时再弹出一个“是否允许写这个系统路径”的新对话框。
|
||||
|
||||
这样做的好处是：
|
||||
|
||||
- 边界更稳定
|
||||
- 用户心智更清晰
|
||||
- 不容易把 shell 运行时逐步升级成越来越宽松的环境
|
||||
|
||||
网络访问则更适合做按 host 的临时授权，因此单独做了授权对话框。
|
||||
|
||||
## 常见误区
|
||||
|
||||
### 误区 1：沙箱会保护所有文件修改
|
||||
|
||||
不是。它主要保护 **shell 子进程**。
|
||||
|
||||
直接文件编辑工具走的是应用层权限系统，不是 shell 沙箱。
|
||||
|
||||
### 误区 2：只要启用了沙箱，就不会再需要权限系统
|
||||
|
||||
不是。沙箱只限制进程能力，不负责解释用户意图、路径安全语义、工具模式、审批体验。
|
||||
|
||||
项目之所以还保留复杂的 `allow / ask / deny` 体系，就是因为两者职责不同。
|
||||
|
||||
### 误区 3：如果某个危险操作被沙箱拦住，就说明应用层检查没价值
|
||||
|
||||
不是。应用层检查的价值在于：
|
||||
|
||||
- 更早提示
|
||||
- 更好的用户体验
|
||||
- 更细的语义判断
|
||||
- 对不走 shell 的工具同样生效
|
||||
|
||||
而沙箱负责的是最终兜底。
|
||||
|
||||
## 推荐的阅读路径
|
||||
|
||||
如果你想继续顺着源码深入，推荐按下面顺序看：
|
||||
|
||||
1. `src/tools/BashTool/shouldUseSandbox.ts`
|
||||
2. `src/utils/Shell.ts`
|
||||
3. `src/utils/sandbox/sandbox-adapter.ts`
|
||||
4. `src/utils/permissions/permissions.ts`
|
||||
5. `src/tools/BashTool/bashPermissions.ts`
|
||||
6. `src/utils/permissions/pathValidation.ts`
|
||||
7. `src/utils/permissions/filesystem.ts`
|
||||
|
||||
按这条线读，会更容易把“权限系统”和“沙箱系统”在脑中拆开。
|
||||
|
||||
## FAQ
|
||||
|
||||
### Q1：Linux 下 `echo hi > /etc/hosts` 会怎样？
|
||||
|
||||
如果是 BashTool：
|
||||
|
||||
- 通常会进沙箱
|
||||
- 默认沙箱不允许写 `/etc`
|
||||
- 所以命令会在运行时失败
|
||||
|
||||
如果是 FileEditTool：
|
||||
|
||||
- 不进沙箱
|
||||
- 通常会在应用层文件权限检查里先被拦下
|
||||
|
||||
### Q2：Windows 下改 `C:\Windows\System32\drivers\etc\hosts` 会怎样？
|
||||
|
||||
在 Windows 原生环境里，通常没有这套 shell 沙箱兜底，所以主要依赖应用层权限系统和工具自己的检查逻辑。
|
||||
|
||||
### Q3：既然沙箱这么强，为什么还保留 `dangerouslyDisableSandbox`？
|
||||
|
||||
因为有些真实开发任务确实需要越过默认边界，例如：
|
||||
|
||||
- 访问未加入白名单的工具链目录
|
||||
- 调试系统级环境
|
||||
- 做管理员明确允许的例外操作
|
||||
|
||||
但项目把这个入口做得非常显眼，也允许管理员通过策略直接禁掉，避免它变成默认路径。
|
||||
|
||||
### Q4：什么时候最能感受到沙箱的价值？
|
||||
|
||||
当你开启 `autoAllowBashIfSandboxed` 时最明显。
|
||||
|
||||
这时大量工作区内命令可以少弹窗甚至不弹窗，但即使模型偶尔给出过界命令，系统级写入和网络能力仍然被边界限制住。
|
||||
`containsExcludedCommand()` 的匹配机制值得注意——它不只是简单的前缀匹配，而是支持三种模式：
|
||||
|
||||
| 模式 | 示例 | 匹配行为 |
|
||||
|------|------|----------|
|
||||
| **精确匹配** | `npm run lint` | 完全相等 |
|
||||
| **前缀匹配** | `npm run test:*` | 前缀 + 空格或完全相等 |
|
||||
| **通配符** | `docker*` | 使用 `matchWildcardPattern` |
|
||||
|
||||
对于复合命令（如 `docker ps && curl evil.com`），系统会先拆分为子命令，逐一检查。还会迭代剥离环境变量前缀（`FOO=bar bazel ...`）和包装命令（`timeout 30 bazel ...`），直到不动点——防止通过嵌套包装绕过。
|
||||
|
||||
## 沙箱的配置模型
|
||||
|
||||
沙箱配置来自 `settings.json` 中的 `sandbox` 字段（`src/entrypoints/sandboxTypes.ts`）：
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"sandbox": {
|
||||
"enabled": true, // 主开关
|
||||
"autoAllowBashIfSandboxed": true, // 沙箱中的命令自动允许（跳过审批）
|
||||
"allowUnsandboxedCommands": true, // 是否允许 dangerouslyDisableSandbox
|
||||
"failIfUnavailable": false, // 沙箱依赖缺失时是否报错退出
|
||||
|
||||
"network": {
|
||||
"allowedDomains": ["github.com"], // 网络白名单
|
||||
"deniedDomains": [], // 网络黑名单
|
||||
"allowLocalBinding": true, // 允许 localhost 绑定
|
||||
"httpProxyPort": 8888 // HTTP 代理端口（MITM）
|
||||
},
|
||||
|
||||
"filesystem": {
|
||||
"allowWrite": ["~/projects"], // 额外可写路径
|
||||
"denyWrite": ["~/.ssh"], // 禁止写入路径
|
||||
"denyRead": [], // 禁止读取路径
|
||||
"allowRead": [] // 在 denyRead 中重新放行
|
||||
},
|
||||
|
||||
"excludedCommands": ["docker", "npm:*"] // 不走沙箱的命令
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`SandboxSettingsSchema` 定义了完整的 Zod 验证规则，包含一些未公开的设置如 `enabledPlatforms`（限制沙箱只在特定平台生效）。
|
||||
|
||||
## 平台实现差异
|
||||
|
||||
### macOS：sandbox-exec（Seatbelt）
|
||||
|
||||
macOS 使用 Apple 的 Seatbelt 沙箱（`sandbox-exec` 命令），这是 macOS 原生的进程隔离机制。
|
||||
|
||||
执行流程：
|
||||
1. `SandboxManager.wrapWithSandbox()` 调用 `@anthropic-ai/sandbox-runtime` 的 `BaseSandboxManager`
|
||||
2. 运行时生成 Seatbelt profile（基于配置中的网络/文件系统规则）
|
||||
3. 通过 `sandbox-exec -p <profile> -- <command>` 包裹原始命令
|
||||
4. Seatbelt 在内核级别强制执行约束
|
||||
|
||||
网络隔离的实现方式：
|
||||
- 通过代理端口拦截 HTTP/HTTPS 请求
|
||||
- 域名白名单/黑名单在代理层过滤
|
||||
- Unix socket 可单独配置允许路径
|
||||
|
||||
### Linux：bubblewrap（bwrap）+ seccomp
|
||||
|
||||
Linux 使用 `bubblewrap`（bwrap）创建命名空间隔离，配合 seccomp 过滤系统调用：
|
||||
|
||||
依赖项（`apt install`）：
|
||||
| 包 | 作用 |
|
||||
|----|------|
|
||||
| `bubblewrap` | 创建 mount/PID/network 命名空间 |
|
||||
| `socat` | 网络代理（HTTP/SOCKS） |
|
||||
| `libseccomp` / seccomp filter | 过滤 Unix socket 系统调用 |
|
||||
|
||||
bwrap 的实现差异：
|
||||
- **不支持 glob 路径模式**（macOS 的 Seatbelt 支持）— Linux 上带 glob 的权限规则会触发警告
|
||||
- 执行后会在当前目录留下 0 字节的 mount-point 文件（如 `.bashrc`），需要 `cleanupAfterCommand()` 清理
|
||||
- seccomp 无法按路径过滤 Unix socket（只能全允许或全拒绝），与 macOS 的按路径放行形成差异
|
||||
|
||||
### 平台支持矩阵
|
||||
|
||||
| 特性 | macOS | Linux | WSL |
|
||||
|------|-------|-------|-----|
|
||||
| 沙箱引擎 | sandbox-exec (Seatbelt) | bubblewrap + seccomp | 仅 WSL2 |
|
||||
| 文件 glob | ✅ 完整支持 | ⚠️ 仅 `/**` 后缀 | 同 Linux |
|
||||
| 网络 Unix socket 按路径 | ✅ | ❌ | ❌ |
|
||||
| 依赖检查 | ripgrep | bwrap + socat + ripgrep + seccomp | 同 Linux |
|
||||
|
||||
## 沙箱初始化流程
|
||||
|
||||
```
|
||||
REPL/SDK 启动
|
||||
→ main.tsx → init.ts
|
||||
→ SandboxManager.initialize(sandboxAskCallback)
|
||||
→ detectWorktreeMainRepoPath() // 检测 git worktree，放行主仓库 .git
|
||||
→ convertToSandboxRuntimeConfig() // 构建 SandboxRuntimeConfig
|
||||
→ BaseSandboxManager.initialize() // 启动底层运行时
|
||||
→ settingsChangeDetector.subscribe() // 订阅设置变更，动态更新配置
|
||||
```
|
||||
|
||||
`convertToSandboxRuntimeConfig()`（`src/utils/sandbox/sandbox-adapter.ts`）完成从用户设置到运行时配置的转换：
|
||||
|
||||
1. **网络规则**：从 `WebFetch(domain:...)` 权限规则提取域名 → `allowedDomains`
|
||||
2. **文件系统规则**：从 `Edit(...)` / `Read(...)` 权限规则提取路径 → `allowWrite` / `denyWrite` / `denyRead`
|
||||
3. **安全加固**：
|
||||
- 自动将项目目录加入 `allowWrite`
|
||||
- 自动将 `settings.json` 路径加入 `denyWrite`（防止沙箱逃逸）
|
||||
- 自动将 `.claude/skills` 加入 `denyWrite`（防止技能注入）
|
||||
- 检测 bare git repo 攻击向量，对 `HEAD`/`objects`/`refs` 做保护
|
||||
|
||||
## `dangerouslyDisableSandbox` 的设计权衡
|
||||
|
||||
这个参数的命名本身就传达了设计意图——它不是"关闭沙箱"，而是"**危险地禁用沙箱**"。
|
||||
|
||||
双重保险机制：
|
||||
1. **调用侧**：模型在 BashTool 的 `inputSchema` 中可以设置 `dangerouslyDisableSandbox: true`
|
||||
2. **策略侧**：管理员可通过 `allowUnsandboxedCommands: false` 完全禁止此参数（企业部署场景）
|
||||
|
||||
```typescript
|
||||
// 即使 AI 请求了 dangerouslyDisableSandbox，策略层仍可覆盖
|
||||
if (input.dangerouslyDisableSandbox &&
|
||||
SandboxManager.areUnsandboxedCommandsAllowed()) {
|
||||
return false // 只有策略允许时才真正跳过沙箱
|
||||
}
|
||||
```
|
||||
|
||||
`autoAllowBashIfSandboxed` 进一步补充了这个模型：当启用时，**在沙箱中的命令自动获得执行许可**，无需逐条审批。这基于一个信任假设——如果 OS 级沙箱已经限制了命令的能力，那么应用层的逐条审批就变得多余。
|
||||
|
||||
## 沙箱违规处理
|
||||
|
||||
当命令尝试违反沙箱约束时：
|
||||
|
||||
1. 运行时捕获违规事件（文件/网络访问被拒绝）
|
||||
2. `SandboxManager.annotateStderrWithSandboxFailures()` 在输出中注入 `<sandbox_violations>` 标签
|
||||
3. UI 层通过 `removeSandboxViolationTags()` 清理显示
|
||||
4. 违规事件通过 `SandboxViolationStore` 持久化，可用于审计
|
||||
|
||||
## 完整执行链路示例
|
||||
|
||||
以 `npm install` 为例：
|
||||
|
||||
```
|
||||
1. 用户在 REPL 中输入 → Claude 决定调用 BashTool
|
||||
2. BashTool.validateInput() → 通过
|
||||
3. BashTool.checkPermissions() → 检查权限规则
|
||||
├── autoAllowBashIfSandboxed = true 且沙箱可用 → 自动允许
|
||||
└── 否则 → 弹窗请用户确认
|
||||
4. BashTool.call() → runShellCommand()
|
||||
5. shouldUseSandbox({ command: "npm install" })
|
||||
├── SandboxManager.isSandboxingEnabled() → true
|
||||
├── dangerouslyDisableSandbox → undefined
|
||||
└── containsExcludedCommand() → false（除非用户配置了排除 npm）
|
||||
→ 结果: true，需要沙箱
|
||||
6. Shell.exec() → SandboxManager.wrapWithSandbox("npm install")
|
||||
├── macOS: sandbox-exec -p <generated-profile> -- bash -c 'npm install'
|
||||
└── Linux: bwrap ... bash -c 'npm install'
|
||||
7. spawn(wrapped_command) → 子进程在沙箱内执行
|
||||
8. 执行完成 → SandboxManager.cleanupAfterCommand()
|
||||
├── 清理 bwrap 残留文件（Linux）
|
||||
└── scrubBareGitRepoFiles()（安全清理）
|
||||
9. 结果返回给 Claude → 展示给用户
|
||||
```
|
||||
|
||||
@@ -1,155 +0,0 @@
|
||||
# 遥测与远程配置下发系统审计（除 Sentry 外）
|
||||
|
||||
## 1. Datadog 日志
|
||||
|
||||
**文件**: `src/services/analytics/datadog.ts`
|
||||
|
||||
- **端点**: 通过环境变量 `DATADOG_LOGS_ENDPOINT` 配置（默认为空，即禁用）
|
||||
- **客户端 token**: 通过环境变量 `DATADOG_API_KEY` 配置（默认为空，即禁用）
|
||||
- **行为**: 批量发送日志（15s flush 间隔，100 条上限），仅限 1P（直连 Anthropic API）用户
|
||||
- **事件白名单**: `tengu_*` 系列事件（启动、错误、OAuth、工具调用等 ~35 种）
|
||||
- **基线数据**: 收集 model、platform、arch、version、userBucket（用户 hash 到 30 个桶）等
|
||||
- **仅限**: `NODE_ENV === 'production'`
|
||||
- **配置示例**: `DATADOG_LOGS_ENDPOINT=https://http-intake.logs.datadoghq.com/api/v2/logs DATADOG_API_KEY=xxx bun run dev`
|
||||
|
||||
## 2. 1P 事件日志（BigQuery）
|
||||
|
||||
**文件**: `src/services/analytics/firstPartyEventLogger.ts` + `firstPartyEventLoggingExporter.ts`
|
||||
|
||||
- **端点**: `https://api.anthropic.com/api/event_logging/batch`（staging 可切换）
|
||||
- **行为**: 使用 OpenTelemetry SDK 的 `BatchLogRecordProcessor`，批量导出到 Anthropic 自有的 BQ 管道
|
||||
- **数据**: 完整事件 metadata（session、model、env context、用户数据、subscription type 等）
|
||||
- **弹性**: 本地磁盘持久化失败事件（JSONL），二次退避重试，最多 8 次尝试
|
||||
- **Proto schema**: 事件序列化为 `ClaudeCodeInternalEvent` / `GrowthbookExperimentEvent` protobuf 格式
|
||||
- **Auth fallback**: 401 时自动去掉 auth header 重试
|
||||
|
||||
## 3. GrowthBook 远程 Feature Flags / 动态配置
|
||||
|
||||
**文件**: `src/services/analytics/growthbook.ts`
|
||||
|
||||
- **服务端**: `https://api.anthropic.com/`（remote eval 模式）
|
||||
- **行为**: 启动时拉取全量 feature flags，每 6h（外部用户）/ 20min（ant）定时刷新
|
||||
- **磁盘缓存**: feature values 写入 `~/.claude.json` 的 `cachedGrowthBookFeatures`
|
||||
- **用途**:
|
||||
- 控制 Datadog 开关（`tengu_log_datadog_events`）
|
||||
- 控制事件采样率（`tengu_event_sampling_config`）
|
||||
- 控制 sink killswitch（`tengu_frond_boric`）
|
||||
- 控制 BQ batch 配置（`tengu_1p_event_batch_config`）
|
||||
- 控制版本上限/自动更新 kill switch
|
||||
- 控制远程管理设置的安全检查 gate
|
||||
- **用户属性**: 发送 deviceId, sessionId, organizationUUID, accountUUID, email, subscriptionType 等
|
||||
|
||||
## 4. Remote Managed Settings（企业远程配置下发）
|
||||
|
||||
**文件**: `src/services/remoteManagedSettings/index.ts`
|
||||
|
||||
- **端点**: `{BASE_API_URL}/api/claude_code/settings`
|
||||
- **行为**: 企业用户配置下发，支持 ETag/304 缓存，每小时后台轮询
|
||||
- **安全**: 变更包含"危险设置"时弹窗让用户确认
|
||||
- **适用**: API key 用户全部可拉取；OAuth 用户仅 Enterprise/C4E/Team
|
||||
- **Fail-open**: 请求失败时使用本地缓存，无缓存则跳过
|
||||
|
||||
## 5. Settings Sync（设置同步）
|
||||
|
||||
**文件**: `src/services/settingsSync/index.ts`
|
||||
|
||||
- **端点**: `{BASE_API_URL}/api/claude_code/user_settings`
|
||||
- **行为**: CLI 上传本地设置/memory 到远程；CCR 模式从远程下载
|
||||
- **同步内容**: userSettings、userMemory、projectSettings、projectMemory
|
||||
- **Feature gate**: `UPLOAD_USER_SETTINGS` / `DOWNLOAD_USER_SETTINGS`
|
||||
- **文件大小限制**: 500KB/文件
|
||||
|
||||
## 6. OpenTelemetry 三方遥测
|
||||
|
||||
**文件**: `src/utils/telemetry/instrumentation.ts`
|
||||
|
||||
- **行为**: 完整的 OTEL SDK 初始化，支持 metrics / logs / traces 三种信号
|
||||
- **协议**: gRPC / http-json / http-protobuf（通过 `OTEL_EXPORTER_OTLP_PROTOCOL` 选择）
|
||||
- **exporter**: console / otlp / prometheus
|
||||
- **触发**: `CLAUDE_CODE_ENABLE_TELEMETRY=1` 环境变量
|
||||
- **增强 trace**: `feature('ENHANCED_TELEMETRY_BETA')` + GrowthBook gate `enhanced_telemetry_beta`
|
||||
|
||||
## 7. BigQuery Metrics Exporter（内部指标）
|
||||
|
||||
**文件**: `src/utils/telemetry/bigqueryExporter.ts`
|
||||
|
||||
- **端点**: `https://api.anthropic.com/api/claude_code/metrics`
|
||||
- **行为**: 定期（5min 间隔）导出 OTel metrics 到内部 BQ
|
||||
- **适用**: API 客户、C4E/Team 订阅者
|
||||
- **组织级 opt-out**: 通过 `checkMetricsEnabled()` API 查询（见下方第 8 项）
|
||||
|
||||
## 8. 组织级 Metrics Opt-out 查询
|
||||
|
||||
**文件**: `src/services/api/metricsOptOut.ts`
|
||||
|
||||
- **端点**: `https://api.anthropic.com/api/claude_code/organizations/metrics_enabled`
|
||||
- **行为**: 查询组织是否启用了 metrics，二级缓存（内存 1h + 磁盘 24h）
|
||||
- **作用**: 控制 BigQuery metrics exporter 是否导出
|
||||
|
||||
## 9. Startup Profiling
|
||||
|
||||
**文件**: `src/utils/startupProfiler.ts`
|
||||
|
||||
- **行为**: 采样启动性能数据（100% ant / 0.5% 外部），通过 `logEvent('tengu_startup_perf')` 上报
|
||||
- **详细模式**: `CLAUDE_CODE_PROFILE_STARTUP=1` 输出完整性能报告到文件
|
||||
|
||||
## 10. Beta Session Tracing
|
||||
|
||||
**文件**: `src/utils/telemetry/betaSessionTracing.ts`
|
||||
|
||||
- **行为**: 详细调试 trace，发送 system prompt、model output、tool schema 等
|
||||
- **触发**: `ENABLE_BETA_TRACING_DETAILED=1` + `BETA_TRACING_ENDPOINT`
|
||||
- **外部用户**: SDK/headless 模式自动启用，交互模式需要 GrowthBook gate `tengu_trace_lantern`
|
||||
|
||||
## 11. Bridge Poll Config（远程轮询间隔配置）
|
||||
|
||||
**文件**: `src/bridge/pollConfig.ts`
|
||||
|
||||
- **行为**: 从 GrowthBook 拉取 bridge 轮询间隔配置（`tengu_bridge_poll_interval_config`）
|
||||
- **控制**: 单会话和多会话的各种 poll interval
|
||||
|
||||
## 12. Plugin/MCP 遥测
|
||||
|
||||
**文件**: `src/utils/plugins/fetchTelemetry.ts`
|
||||
|
||||
- **行为**: 记录 plugin/marketplace 的网络请求（安装计数、marketplace clone/pull 等）
|
||||
- **事件**: `tengu_plugin_remote_fetch`，包含 host（已脱敏）、outcome、duration
|
||||
|
||||
---
|
||||
|
||||
## 全局禁用方式
|
||||
|
||||
```bash
|
||||
# 禁用所有遥测（Datadog + 1P + 调查问卷）
|
||||
DISABLE_TELEMETRY=1
|
||||
|
||||
# 更激进：禁用所有非必要网络（包括自动更新、grove、release notes 等）
|
||||
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
|
||||
|
||||
# 3P 提供商自动禁用
|
||||
CLAUDE_CODE_USE_BEDROCK=1 # 或 VERTEX/FOUNDRY
|
||||
```
|
||||
|
||||
`src/utils/privacyLevel.ts` 是集中控制点，三个级别：`default < no-telemetry < essential-traffic`。
|
||||
|
||||
---
|
||||
|
||||
## 数据流架构
|
||||
|
||||
```
|
||||
用户操作 → logEvent()
|
||||
↓
|
||||
sink.ts (路由层)
|
||||
↙ ↘
|
||||
trackDatadogEvent() logEventTo1P()
|
||||
↓ ↓
|
||||
Datadog HTTP API OTel BatchLogRecordProcessor
|
||||
(us5.datadoghq.com) ↓
|
||||
FirstPartyEventLoggingExporter
|
||||
↓
|
||||
api.anthropic.com/api/event_logging/batch
|
||||
↓
|
||||
BigQuery (ClaudeCodeInternalEvent proto)
|
||||
```
|
||||
|
||||
GrowthBook 作为独立通道，同时驱动上述两个 sink 的开关和配置。
|
||||
@@ -1,147 +0,0 @@
|
||||
# Tool 系统测试计划
|
||||
|
||||
## 概述
|
||||
|
||||
Tool 系统是 Claude Code 的核心，负责工具的定义、注册、发现和过滤。本计划覆盖 `src/Tool.ts` 中的工具接口与工具函数、`src/tools.ts` 中的注册/过滤逻辑，以及各工具目录下可独立测试的纯函数。
|
||||
|
||||
## 被测文件
|
||||
|
||||
| 文件 | 关键导出 |
|
||||
|------|----------|
|
||||
| `src/Tool.ts` | `buildTool`, `toolMatchesName`, `findToolByName`, `getEmptyToolPermissionContext`, `filterToolProgressMessages` |
|
||||
| `src/tools.ts` | `parseToolPreset`, `filterToolsByDenyRules`, `getAllBaseTools`, `getTools`, `assembleToolPool` |
|
||||
| `src/tools/shared/gitOperationTracking.ts` | `parseGitCommitId`, `detectGitOperation` |
|
||||
| `src/tools/shared/spawnMultiAgent.ts` | `resolveTeammateModel`, `generateUniqueTeammateName` |
|
||||
| `src/tools/GrepTool/GrepTool.ts` | `applyHeadLimit`, `formatLimitInfo`（内部辅助函数） |
|
||||
| `src/tools/FileEditTool/utils.ts` | 字符串匹配/补丁相关纯函数 |
|
||||
|
||||
---
|
||||
|
||||
## 测试用例
|
||||
|
||||
### src/Tool.ts
|
||||
|
||||
#### describe('buildTool')
|
||||
|
||||
- test('fills in default isEnabled as true') — 不传 isEnabled 时，构建的 tool.isEnabled() 应返回 true
|
||||
- test('fills in default isConcurrencySafe as false') — 默认值应为 false（fail-closed）
|
||||
- test('fills in default isReadOnly as false') — 默认假设有写操作
|
||||
- test('fills in default isDestructive as false') — 默认非破坏性
|
||||
- test('fills in default checkPermissions as allow') — 默认 checkPermissions 应返回 `{ behavior: 'allow', updatedInput }`
|
||||
- test('fills in default userFacingName from tool name') — userFacingName 默认应返回 tool.name
|
||||
- test('preserves explicitly provided methods') — 传入自定义 isEnabled 等方法时应覆盖默认值
|
||||
- test('preserves all non-defaultable properties') — name, inputSchema, call, description 等属性原样保留
|
||||
|
||||
#### describe('toolMatchesName')
|
||||
|
||||
- test('returns true for exact name match') — `{ name: 'Bash' }` 匹配 'Bash'
|
||||
- test('returns false for non-matching name') — `{ name: 'Bash' }` 不匹配 'Read'
|
||||
- test('returns true when name matches an alias') — `{ name: 'Bash', aliases: ['BashTool'] }` 匹配 'BashTool'
|
||||
- test('returns false when aliases is undefined') — `{ name: 'Bash' }` 不匹配 'BashTool'
|
||||
- test('returns false when aliases is empty') — `{ name: 'Bash', aliases: [] }` 不匹配 'BashTool'
|
||||
|
||||
#### describe('findToolByName')
|
||||
|
||||
- test('finds tool by primary name') — 从 tools 列表中按 name 找到工具
|
||||
- test('finds tool by alias') — 从 tools 列表中按 alias 找到工具
|
||||
- test('returns undefined when no match') — 找不到时返回 undefined
|
||||
- test('returns first match when duplicates exist') — 多个同名工具时返回第一个
|
||||
|
||||
#### describe('getEmptyToolPermissionContext')
|
||||
|
||||
- test('returns default permission mode') — mode 应为 'default'
|
||||
- test('returns empty maps and arrays') — additionalWorkingDirectories 为空 Map，rules 为空对象
|
||||
- test('returns isBypassPermissionsModeAvailable as false')
|
||||
|
||||
#### describe('filterToolProgressMessages')
|
||||
|
||||
- test('filters out hook_progress messages') — 移除 type 为 hook_progress 的消息
|
||||
- test('keeps tool progress messages') — 保留非 hook_progress 的消息
|
||||
- test('returns empty array for empty input')
|
||||
- test('handles messages without type field') — data 不含 type 时应保留
|
||||
|
||||
---
|
||||
|
||||
### src/tools.ts
|
||||
|
||||
#### describe('parseToolPreset')
|
||||
|
||||
- test('returns "default" for "default" input') — 精确匹配
|
||||
- test('returns "default" for "Default" input') — 大小写不敏感
|
||||
- test('returns null for unknown preset') — 未知字符串返回 null
|
||||
- test('returns null for empty string')
|
||||
|
||||
#### describe('filterToolsByDenyRules')
|
||||
|
||||
- test('returns all tools when no deny rules') — 空 deny 规则不过滤任何工具
|
||||
- test('filters out tools matching blanket deny rule') — deny rule `{ toolName: 'Bash' }` 应移除 Bash
|
||||
- test('does not filter tools with content-specific deny rules') — deny rule `{ toolName: 'Bash', ruleContent: 'rm -rf' }` 不移除 Bash（只在运行时阻止特定命令）
|
||||
- test('filters MCP tools by server name prefix') — deny rule `mcp__server` 应移除该 server 下所有工具
|
||||
- test('preserves tools not matching any deny rule')
|
||||
|
||||
#### describe('getAllBaseTools')
|
||||
|
||||
- test('returns a non-empty array of tools') — 至少包含核心工具
|
||||
- test('each tool has required properties') — 每个工具应有 name, inputSchema, call 等属性
|
||||
- test('includes BashTool, FileReadTool, FileEditTool') — 核心工具始终存在
|
||||
- test('includes TestingPermissionTool when NODE_ENV is test') — 需设置 env
|
||||
|
||||
#### describe('getTools')
|
||||
|
||||
- test('returns filtered tools based on permission context') — 根据 deny rules 过滤
|
||||
- test('returns simple tools in CLAUDE_CODE_SIMPLE mode') — 仅返回 Bash/Read/Edit
|
||||
- test('filters disabled tools via isEnabled') — isEnabled 返回 false 的工具被排除
|
||||
|
||||
---
|
||||
|
||||
### src/tools/shared/gitOperationTracking.ts
|
||||
|
||||
#### describe('parseGitCommitId')
|
||||
|
||||
- test('extracts commit hash from git commit output') — 从 `[main abc1234] message` 中提取 `abc1234`
|
||||
- test('returns null for non-commit output') — 无法解析时返回 null
|
||||
- test('handles various branch name formats') — `[feature/foo abc1234]` 等
|
||||
|
||||
#### describe('detectGitOperation')
|
||||
|
||||
- test('detects git commit operation') — 命令含 `git commit` 时识别为 commit
|
||||
- test('detects git push operation') — 命令含 `git push` 时识别
|
||||
- test('returns null for non-git commands') — 非 git 命令返回 null
|
||||
- test('detects git merge operation')
|
||||
- test('detects git rebase operation')
|
||||
|
||||
---
|
||||
|
||||
### src/tools/shared/spawnMultiAgent.ts
|
||||
|
||||
#### describe('resolveTeammateModel')
|
||||
|
||||
- test('returns specified model when provided')
|
||||
- test('falls back to default model when not specified')
|
||||
|
||||
#### describe('generateUniqueTeammateName')
|
||||
|
||||
- test('generates a name when no existing names') — 无冲突时返回基础名
|
||||
- test('appends suffix when name conflicts') — 与已有名称冲突时添加后缀
|
||||
- test('handles multiple conflicts') — 多次冲突时递增后缀
|
||||
|
||||
---
|
||||
|
||||
## Mock 需求
|
||||
|
||||
| 依赖 | Mock 方式 | 说明 |
|
||||
|------|-----------|------|
|
||||
| `bun:bundle` (feature) | 已 polyfill 为 `() => false` | 不需额外 mock |
|
||||
| `process.env` | `bun:test` mock | 测试 `USER_TYPE`、`NODE_ENV`、`CLAUDE_CODE_SIMPLE` |
|
||||
| `getDenyRuleForTool` | mock module | `filterToolsByDenyRules` 测试中需控制返回值 |
|
||||
| `isToolSearchEnabledOptimistic` | mock module | `getAllBaseTools` 中条件加载 |
|
||||
|
||||
## 集成测试场景
|
||||
|
||||
放在 `tests/integration/tool-chain.test.ts`：
|
||||
|
||||
### describe('Tool registration and discovery')
|
||||
|
||||
- test('getAllBaseTools returns tools that can be found by findToolByName') — 注册 → 查找完整链路
|
||||
- test('filterToolsByDenyRules + getTools produces consistent results') — 过滤管线一致性
|
||||
- test('assembleToolPool deduplicates built-in and MCP tools') — 合并去重逻辑
|
||||
@@ -1,416 +0,0 @@
|
||||
# 工具函数（纯函数）测试计划
|
||||
|
||||
## 概述
|
||||
|
||||
覆盖 `src/utils/` 下所有可独立单元测试的纯函数。这些函数无外部依赖，输入输出确定性强，是测试金字塔的底层基石。
|
||||
|
||||
## 被测文件
|
||||
|
||||
| 文件 | 状态 | 关键导出 |
|
||||
|------|------|----------|
|
||||
| `src/utils/array.ts` | **已有测试** | intersperse, count, uniq |
|
||||
| `src/utils/set.ts` | **已有测试** | difference, intersects, every, union |
|
||||
| `src/utils/xml.ts` | 待测 | escapeXml, escapeXmlAttr |
|
||||
| `src/utils/hash.ts` | 待测 | djb2Hash, hashContent, hashPair |
|
||||
| `src/utils/stringUtils.ts` | 待测 | escapeRegExp, capitalize, plural, firstLineOf, countCharInString, normalizeFullWidthDigits, normalizeFullWidthSpace, safeJoinLines, truncateToLines, EndTruncatingAccumulator |
|
||||
| `src/utils/semver.ts` | 待测 | gt, gte, lt, lte, satisfies, order |
|
||||
| `src/utils/uuid.ts` | 待测 | validateUuid, createAgentId |
|
||||
| `src/utils/format.ts` | 待测 | formatFileSize, formatSecondsShort, formatDuration, formatNumber, formatTokens, formatRelativeTime, formatRelativeTimeAgo |
|
||||
| `src/utils/json.ts` | 待测 | safeParseJSON, safeParseJSONC, parseJSONL, addItemToJSONCArray |
|
||||
| `src/utils/truncate.ts` | 待测 | truncatePathMiddle, truncateToWidth, truncateStartToWidth, truncateToWidthNoEllipsis, truncate, wrapText |
|
||||
| `src/utils/diff.ts` | 待测 | adjustHunkLineNumbers, getPatchFromContents |
|
||||
| `src/utils/frontmatterParser.ts` | 待测 | parseFrontmatter, splitPathInFrontmatter, parsePositiveIntFromFrontmatter, parseBooleanFrontmatter, parseShellFrontmatter |
|
||||
| `src/utils/file.ts` | 待测（纯函数部分） | convertLeadingTabsToSpaces, addLineNumbers, stripLineNumberPrefix, pathsEqual, normalizePathForComparison |
|
||||
| `src/utils/glob.ts` | 待测（纯函数部分） | extractGlobBaseDirectory |
|
||||
| `src/utils/tokens.ts` | 待测 | getTokenCountFromUsage |
|
||||
| `src/utils/path.ts` | 待测（纯函数部分） | containsPathTraversal, normalizePathForConfigKey |
|
||||
|
||||
---
|
||||
|
||||
## 测试用例
|
||||
|
||||
### src/utils/xml.ts — 测试文件: `src/utils/__tests__/xml.test.ts`
|
||||
|
||||
#### describe('escapeXml')
|
||||
|
||||
- test('escapes ampersand') — `&` → `&`
|
||||
- test('escapes less-than') — `<` → `<`
|
||||
- test('escapes greater-than') — `>` → `>`
|
||||
- test('does not escape quotes') — `"` 和 `'` 保持原样
|
||||
- test('handles empty string') — `""` → `""`
|
||||
- test('handles string with no special chars') — `"hello"` 原样返回
|
||||
- test('escapes multiple special chars in one string') — `<a & b>` → `<a & b>`
|
||||
|
||||
#### describe('escapeXmlAttr')
|
||||
|
||||
- test('escapes all xml chars plus quotes') — `"` → `"`, `'` → `'`
|
||||
- test('escapes double quotes') — `he said "hi"` 正确转义
|
||||
- test('escapes single quotes') — `it's` 正确转义
|
||||
|
||||
---
|
||||
|
||||
### src/utils/hash.ts — 测试文件: `src/utils/__tests__/hash.test.ts`
|
||||
|
||||
#### describe('djb2Hash')
|
||||
|
||||
- test('returns consistent hash for same input') — 相同输入返回相同结果
|
||||
- test('returns different hashes for different inputs') — 不同输入大概率不同
|
||||
- test('returns a 32-bit integer') — 结果在 int32 范围内
|
||||
- test('handles empty string') — 空字符串有确定的哈希值
|
||||
- test('handles unicode strings') — 中文/emoji 等正确处理
|
||||
|
||||
#### describe('hashContent')
|
||||
|
||||
- test('returns consistent hash for same content') — 确定性
|
||||
- test('returns string result') — 返回值为字符串
|
||||
|
||||
#### describe('hashPair')
|
||||
|
||||
- test('returns consistent hash for same pair') — 确定性
|
||||
- test('order matters') — hashPair(a, b) ≠ hashPair(b, a)
|
||||
- test('handles empty strings')
|
||||
|
||||
---
|
||||
|
||||
### src/utils/stringUtils.ts — 测试文件: `src/utils/__tests__/stringUtils.test.ts`
|
||||
|
||||
#### describe('escapeRegExp')
|
||||
|
||||
- test('escapes dots') — `.` → `\\.`
|
||||
- test('escapes asterisks') — `*` → `\\*`
|
||||
- test('escapes brackets') — `[` → `\\[`
|
||||
- test('escapes all special chars') — `.*+?^${}()|[]\` 全部转义
|
||||
- test('leaves normal chars unchanged') — `hello` 原样
|
||||
- test('escaped string works in RegExp') — `new RegExp(escapeRegExp('a.b'))` 精确匹配 `a.b`
|
||||
|
||||
#### describe('capitalize')
|
||||
|
||||
- test('uppercases first char') — `"foo"` → `"Foo"`
|
||||
- test('does NOT lowercase rest') — `"fooBar"` → `"FooBar"`（区别于 lodash capitalize）
|
||||
- test('handles single char') — `"a"` → `"A"`
|
||||
- test('handles empty string') — `""` → `""`
|
||||
- test('handles already capitalized') — `"Foo"` → `"Foo"`
|
||||
|
||||
#### describe('plural')
|
||||
|
||||
- test('returns singular for n=1') — `plural(1, 'file')` → `'file'`
|
||||
- test('returns plural for n=0') — `plural(0, 'file')` → `'files'`
|
||||
- test('returns plural for n>1') — `plural(3, 'file')` → `'files'`
|
||||
- test('uses custom plural form') — `plural(2, 'entry', 'entries')` → `'entries'`
|
||||
|
||||
#### describe('firstLineOf')
|
||||
|
||||
- test('returns first line of multi-line string') — `"a\nb\nc"` → `"a"`
|
||||
- test('returns full string when no newline') — `"hello"` → `"hello"`
|
||||
- test('handles empty string') — `""` → `""`
|
||||
- test('handles string starting with newline') — `"\nhello"` → `""`
|
||||
|
||||
#### describe('countCharInString')
|
||||
|
||||
- test('counts occurrences') — `countCharInString("aabac", "a")` → `3`
|
||||
- test('returns 0 when char not found') — `countCharInString("hello", "x")` → `0`
|
||||
- test('handles empty string') — `countCharInString("", "a")` → `0`
|
||||
- test('respects start position') — `countCharInString("aaba", "a", 2)` → `1`
|
||||
|
||||
#### describe('normalizeFullWidthDigits')
|
||||
|
||||
- test('converts full-width digits to half-width') — `"０１２３"` → `"0123"`
|
||||
- test('leaves half-width digits unchanged') — `"0123"` → `"0123"`
|
||||
- test('mixed content') — `"port ８０８０"` → `"port 8080"`
|
||||
|
||||
#### describe('normalizeFullWidthSpace')
|
||||
|
||||
- test('converts ideographic space to regular space') — `"\u3000"` → `" "`
|
||||
- test('converts multiple spaces') — `"a\u3000b\u3000c"` → `"a b c"`
|
||||
|
||||
#### describe('safeJoinLines')
|
||||
|
||||
- test('joins lines with default delimiter') — `["a","b"]` → `"a,b"`
|
||||
- test('truncates when exceeding maxSize') — 超限时截断并添加 `...[truncated]`
|
||||
- test('handles empty array') — `[]` → `""`
|
||||
- test('uses custom delimiter') — delimiter 为 `"\n"` 时按行连接
|
||||
|
||||
#### describe('truncateToLines')
|
||||
|
||||
- test('returns full text when within limit') — 行数不超限时原样返回
|
||||
- test('truncates and adds ellipsis') — 超限时截断并加 `…`
|
||||
- test('handles exact limit') — 刚好等于 maxLines 时不截断
|
||||
- test('handles single line') — 单行文本不截断
|
||||
|
||||
#### describe('EndTruncatingAccumulator')
|
||||
|
||||
- test('accumulates strings normally within limit')
|
||||
- test('truncates when exceeding maxSize')
|
||||
- test('reports truncated status correctly')
|
||||
- test('reports totalBytes including truncated content')
|
||||
- test('toString includes truncation marker')
|
||||
- test('clear resets all state')
|
||||
- test('append with Buffer works') — 接受 Buffer 类型
|
||||
|
||||
---
|
||||
|
||||
### src/utils/semver.ts — 测试文件: `src/utils/__tests__/semver.test.ts`
|
||||
|
||||
#### describe('gt / gte / lt / lte')
|
||||
|
||||
- test('gt: 2.0.0 > 1.0.0') → true
|
||||
- test('gt: 1.0.0 > 1.0.0') → false
|
||||
- test('gte: 1.0.0 >= 1.0.0') → true
|
||||
- test('lt: 1.0.0 < 2.0.0') → true
|
||||
- test('lte: 1.0.0 <= 1.0.0') → true
|
||||
- test('handles pre-release versions') — `1.0.0-beta < 1.0.0`
|
||||
|
||||
#### describe('satisfies')
|
||||
|
||||
- test('version satisfies caret range') — `satisfies('1.2.3', '^1.0.0')` → true
|
||||
- test('version does not satisfy range') — `satisfies('2.0.0', '^1.0.0')` → false
|
||||
- test('exact match') — `satisfies('1.0.0', '1.0.0')` → true
|
||||
|
||||
#### describe('order')
|
||||
|
||||
- test('returns -1 for lesser') — `order('1.0.0', '2.0.0')` → -1
|
||||
- test('returns 0 for equal') — `order('1.0.0', '1.0.0')` → 0
|
||||
- test('returns 1 for greater') — `order('2.0.0', '1.0.0')` → 1
|
||||
|
||||
---
|
||||
|
||||
### src/utils/uuid.ts — 测试文件: `src/utils/__tests__/uuid.test.ts`
|
||||
|
||||
#### describe('validateUuid')
|
||||
|
||||
- test('accepts valid v4 UUID') — `'550e8400-e29b-41d4-a716-446655440000'` → 返回 UUID
|
||||
- test('returns null for invalid format') — `'not-a-uuid'` → null
|
||||
- test('returns null for empty string') — `''` → null
|
||||
- test('returns null for null/undefined input')
|
||||
- test('accepts uppercase UUIDs') — 大写字母有效
|
||||
|
||||
#### describe('createAgentId')
|
||||
|
||||
- test('returns string starting with "a"') — 前缀为 `a`
|
||||
- test('has correct length') — 前缀 + 16 hex 字符
|
||||
- test('generates unique ids') — 连续两次调用结果不同
|
||||
|
||||
---
|
||||
|
||||
### src/utils/format.ts — 测试文件: `src/utils/__tests__/format.test.ts`
|
||||
|
||||
#### describe('formatFileSize')
|
||||
|
||||
- test('formats bytes') — `500` → `"500 bytes"`
|
||||
- test('formats kilobytes') — `1536` → `"1.5KB"`
|
||||
- test('formats megabytes') — `1572864` → `"1.5MB"`
|
||||
- test('formats gigabytes') — `1610612736` → `"1.5GB"`
|
||||
- test('removes trailing .0') — `1024` → `"1KB"` (不是 `"1.0KB"`)
|
||||
|
||||
#### describe('formatSecondsShort')
|
||||
|
||||
- test('formats milliseconds to seconds') — `1234` → `"1.2s"`
|
||||
- test('formats zero') — `0` → `"0.0s"`
|
||||
|
||||
#### describe('formatDuration')
|
||||
|
||||
- test('formats seconds') — `5000` → `"5s"`
|
||||
- test('formats minutes and seconds') — `65000` → `"1m 5s"`
|
||||
- test('formats hours') — `3661000` → `"1h 1m 1s"`
|
||||
- test('formats days') — `90061000` → `"1d 1h 1m"`
|
||||
- test('returns "0s" for zero') — `0` → `"0s"`
|
||||
- test('hideTrailingZeros omits zero components') — `3600000` + `hideTrailingZeros` → `"1h"`
|
||||
- test('mostSignificantOnly returns largest unit') — `3661000` + `mostSignificantOnly` → `"1h"`
|
||||
|
||||
#### describe('formatNumber')
|
||||
|
||||
- test('formats thousands') — `1321` → `"1.3k"`
|
||||
- test('formats small numbers as-is') — `900` → `"900"`
|
||||
- test('lowercase output') — `1500` → `"1.5k"` (不是 `"1.5K"`)
|
||||
|
||||
#### describe('formatTokens')
|
||||
|
||||
- test('strips .0 suffix') — `1000` → `"1k"` (不是 `"1.0k"`)
|
||||
- test('keeps non-zero decimal') — `1500` → `"1.5k"`
|
||||
|
||||
#### describe('formatRelativeTime')
|
||||
|
||||
- test('formats past time') — now - 3600s → `"1h ago"` (narrow style)
|
||||
- test('formats future time') — now + 3600s → `"in 1h"` (narrow style)
|
||||
- test('formats less than 1 second') — now → `"0s ago"`
|
||||
- test('uses custom now parameter for deterministic output')
|
||||
|
||||
---
|
||||
|
||||
### src/utils/json.ts — 测试文件: `src/utils/__tests__/json.test.ts`
|
||||
|
||||
#### describe('safeParseJSON')
|
||||
|
||||
- test('parses valid JSON') — `'{"a":1}'` → `{ a: 1 }`
|
||||
- test('returns null for invalid JSON') — `'not json'` → null
|
||||
- test('returns null for null input') — `null` → null
|
||||
- test('returns null for undefined input') — `undefined` → null
|
||||
- test('returns null for empty string') — `""` → null
|
||||
- test('handles JSON with BOM') — BOM 前缀不影响解析
|
||||
- test('caches results for repeated calls') — 同一输入不重复解析
|
||||
|
||||
#### describe('safeParseJSONC')
|
||||
|
||||
- test('parses JSON with comments') — 含 `//` 注释的 JSON 正确解析
|
||||
- test('parses JSON with trailing commas') — 宽松模式
|
||||
- test('returns null for invalid input')
|
||||
- test('returns null for null input')
|
||||
|
||||
#### describe('parseJSONL')
|
||||
|
||||
- test('parses multiple JSON lines') — `'{"a":1}\n{"b":2}'` → `[{a:1}, {b:2}]`
|
||||
- test('skips malformed lines') — 含错误行时跳过该行
|
||||
- test('handles empty input') — `""` → `[]`
|
||||
- test('handles trailing newline') — 尾部换行不产生空元素
|
||||
- test('accepts Buffer input') — Buffer 类型同样工作
|
||||
- test('handles BOM prefix')
|
||||
|
||||
#### describe('addItemToJSONCArray')
|
||||
|
||||
- test('adds item to existing array') — `[1, 2]` + 3 → `[1, 2, 3]`
|
||||
- test('creates new array for empty content') — `""` + item → `[item]`
|
||||
- test('creates new array for non-array content') — `'"hello"'` + item → `[item]`
|
||||
- test('preserves comments in JSONC') — 注释不被丢弃
|
||||
- test('handles empty array') — `"[]"` + item → `[item]`
|
||||
|
||||
---
|
||||
|
||||
### src/utils/diff.ts — 测试文件: `src/utils/__tests__/diff.test.ts`
|
||||
|
||||
#### describe('adjustHunkLineNumbers')
|
||||
|
||||
- test('shifts line numbers by positive offset') — 所有 hunk 的 oldStart/newStart 增加 offset
|
||||
- test('shifts by negative offset') — 负 offset 减少行号
|
||||
- test('handles empty hunk array') — `[]` → `[]`
|
||||
|
||||
#### describe('getPatchFromContents')
|
||||
|
||||
- test('returns empty array for identical content') — 相同内容无差异
|
||||
- test('detects added lines') — 新内容多出行
|
||||
- test('detects removed lines') — 旧内容缺少行
|
||||
- test('detects modified lines') — 行内容变化
|
||||
- test('handles empty old content') — 从空文件到有内容
|
||||
- test('handles empty new content') — 删除所有内容
|
||||
|
||||
---
|
||||
|
||||
### src/utils/frontmatterParser.ts — 测试文件: `src/utils/__tests__/frontmatterParser.test.ts`
|
||||
|
||||
#### describe('parseFrontmatter')
|
||||
|
||||
- test('extracts YAML frontmatter between --- delimiters') — 正确提取 frontmatter 并返回 body
|
||||
- test('returns empty frontmatter for content without ---') — 无 frontmatter 时 data 为空
|
||||
- test('handles empty content') — `""` 正确处理
|
||||
- test('handles frontmatter-only content') — 只有 frontmatter 无 body
|
||||
- test('falls back to quoting on YAML parse error') — 无效 YAML 不崩溃
|
||||
|
||||
#### describe('splitPathInFrontmatter')
|
||||
|
||||
- test('splits comma-separated paths') — `"a.ts, b.ts"` → `["a.ts", "b.ts"]`
|
||||
- test('expands brace patterns') — `"*.{ts,tsx}"` → `["*.ts", "*.tsx"]`
|
||||
- test('handles string array input') — `["a.ts", "b.ts"]` → `["a.ts", "b.ts"]`
|
||||
- test('respects braces in comma splitting') — 大括号内的逗号不作为分隔符
|
||||
|
||||
#### describe('parsePositiveIntFromFrontmatter')
|
||||
|
||||
- test('returns number for valid positive int') — `5` → `5`
|
||||
- test('returns undefined for negative') — `-1` → undefined
|
||||
- test('returns undefined for non-number') — `"abc"` → undefined
|
||||
- test('returns undefined for float') — `1.5` → undefined
|
||||
|
||||
#### describe('parseBooleanFrontmatter')
|
||||
|
||||
- test('returns true for true') — `true` → true
|
||||
- test('returns true for "true"') — `"true"` → true
|
||||
- test('returns false for false') — `false` → false
|
||||
- test('returns false for other values') — `"yes"`, `1` → false
|
||||
|
||||
#### describe('parseShellFrontmatter')
|
||||
|
||||
- test('returns bash for "bash"') — 正确识别
|
||||
- test('returns powershell for "powershell"')
|
||||
- test('returns undefined for invalid value') — `"zsh"` → undefined
|
||||
|
||||
---
|
||||
|
||||
### src/utils/file.ts（纯函数部分）— 测试文件: `src/utils/__tests__/file.test.ts`
|
||||
|
||||
#### describe('convertLeadingTabsToSpaces')
|
||||
|
||||
- test('converts single tab to 2 spaces') — `"\thello"` → `" hello"`
|
||||
- test('converts multiple leading tabs') — `"\t\thello"` → `" hello"`
|
||||
- test('does not convert tabs within line') — `"a\tb"` 保持原样
|
||||
- test('handles mixed content')
|
||||
|
||||
#### describe('addLineNumbers')
|
||||
|
||||
- test('adds line numbers starting from 1') — 每行添加 `N\t` 前缀
|
||||
- test('respects startLine parameter') — 从指定行号开始
|
||||
- test('handles empty content')
|
||||
|
||||
#### describe('stripLineNumberPrefix')
|
||||
|
||||
- test('strips tab-prefixed line number') — `"1\thello"` → `"hello"`
|
||||
- test('strips padded line number') — `" 1\thello"` → `"hello"`
|
||||
- test('returns line unchanged when no prefix')
|
||||
|
||||
#### describe('pathsEqual')
|
||||
|
||||
- test('returns true for identical paths')
|
||||
- test('handles trailing slashes') — 带/不带尾部斜杠视为相同
|
||||
- test('handles case sensitivity based on platform')
|
||||
|
||||
#### describe('normalizePathForComparison')
|
||||
|
||||
- test('normalizes forward slashes')
|
||||
- test('resolves path for comparison')
|
||||
|
||||
---
|
||||
|
||||
### src/utils/glob.ts（纯函数部分）— 测试文件: `src/utils/__tests__/glob.test.ts`
|
||||
|
||||
#### describe('extractGlobBaseDirectory')
|
||||
|
||||
- test('extracts static prefix from glob') — `"src/**/*.ts"` → `{ baseDir: "src", relativePattern: "**/*.ts" }`
|
||||
- test('handles root-level glob') — `"*.ts"` → `{ baseDir: ".", relativePattern: "*.ts" }`
|
||||
- test('handles deep static path') — `"src/utils/model/*.ts"` → baseDir 为 `"src/utils/model"`
|
||||
- test('handles Windows drive root') — `"C:\\Users\\**\\*.ts"` 正确分割
|
||||
|
||||
---
|
||||
|
||||
### src/utils/tokens.ts（纯函数部分）— 测试文件: `src/utils/__tests__/tokens.test.ts`
|
||||
|
||||
#### describe('getTokenCountFromUsage')
|
||||
|
||||
- test('sums input and output tokens') — `{ input_tokens: 100, output_tokens: 50 }` → 150
|
||||
- test('includes cache tokens') — cache_creation + cache_read 加入总数
|
||||
- test('handles zero values') — 全 0 时返回 0
|
||||
|
||||
---
|
||||
|
||||
### src/utils/path.ts（纯函数部分）— 测试文件: `src/utils/__tests__/path.test.ts`
|
||||
|
||||
#### describe('containsPathTraversal')
|
||||
|
||||
- test('detects ../ traversal') — `"../etc/passwd"` → true
|
||||
- test('detects mid-path traversal') — `"foo/../../bar"` → true
|
||||
- test('returns false for safe paths') — `"src/utils/file.ts"` → false
|
||||
- test('returns false for paths containing .. in names') — `"foo..bar"` → false
|
||||
|
||||
#### describe('normalizePathForConfigKey')
|
||||
|
||||
- test('converts backslashes to forward slashes') — `"src\\utils"` → `"src/utils"`
|
||||
- test('leaves forward slashes unchanged')
|
||||
|
||||
---
|
||||
|
||||
## Mock 需求
|
||||
|
||||
本计划中的函数大部分为纯函数，**不需要 mock**。少数例外：
|
||||
|
||||
| 函数 | 依赖 | 处理 |
|
||||
|------|------|------|
|
||||
| `hashContent` / `hashPair` | `Bun.hash` | Bun 运行时下自动可用 |
|
||||
| `formatRelativeTime` | `Date` | 使用 `now` 参数注入确定性时间 |
|
||||
| `safeParseJSON` | `logError` | 可通过 `shouldLogError: false` 跳过 |
|
||||
| `safeParseJSONC` | `logError` | mock `logError` 避免测试输出噪音 |
|
||||
@@ -1,134 +0,0 @@
|
||||
# Context 构建测试计划
|
||||
|
||||
## 概述
|
||||
|
||||
Context 构建系统负责组装发送给 Claude API 的系统提示和用户上下文。包括 git 状态获取、CLAUDE.md 文件发现与加载、系统提示拼装三部分。
|
||||
|
||||
## 被测文件
|
||||
|
||||
| 文件 | 关键导出 |
|
||||
|------|----------|
|
||||
| `src/context.ts` | `getSystemContext`, `getUserContext`, `getGitStatus`, `setSystemPromptInjection` |
|
||||
| `src/utils/claudemd.ts` | `stripHtmlComments`, `getClaudeMds`, `isMemoryFilePath`, `getLargeMemoryFiles`, `filterInjectedMemoryFiles`, `getExternalClaudeMdIncludes`, `hasExternalClaudeMdIncludes`, `processMemoryFile`, `getMemoryFiles` |
|
||||
| `src/utils/systemPrompt.ts` | `buildEffectiveSystemPrompt` |
|
||||
|
||||
---
|
||||
|
||||
## 测试用例
|
||||
|
||||
### src/utils/claudemd.ts — 纯函数部分
|
||||
|
||||
#### describe('stripHtmlComments')
|
||||
|
||||
- test('strips block-level HTML comments') — `"text <!-- comment --> more"` → content 不含注释
|
||||
- test('preserves inline content') — 行内文本保留
|
||||
- test('preserves code block content') — ` ```html\n<!-- not stripped -->\n``` ` 内的注释不移除
|
||||
- test('returns stripped: false when no comments') — 无注释时 stripped 为 false
|
||||
- test('returns stripped: true when comments exist')
|
||||
- test('handles empty string') — `""` → `{ content: "", stripped: false }`
|
||||
- test('handles multiple comments') — 多个注释全部移除
|
||||
|
||||
#### describe('getClaudeMds')
|
||||
|
||||
- test('assembles memory files with type descriptions') — 不同 type 的文件有不同前缀描述
|
||||
- test('includes instruction prompt prefix') — 输出包含指令前缀
|
||||
- test('handles empty memory files array') — 空数组返回空字符串或最小前缀
|
||||
- test('respects filter parameter') — filter 函数可过滤特定类型
|
||||
- test('concatenates multiple files with separators')
|
||||
|
||||
#### describe('isMemoryFilePath')
|
||||
|
||||
- test('returns true for CLAUDE.md path') — `"/project/CLAUDE.md"` → true
|
||||
- test('returns true for .claude/rules/ path') — `"/project/.claude/rules/foo.md"` → true
|
||||
- test('returns true for memory file path') — `"~/.claude/memory/foo.md"` → true
|
||||
- test('returns false for regular file') — `"/project/src/main.ts"` → false
|
||||
- test('returns false for unrelated .md file') — `"/project/README.md"` → false
|
||||
|
||||
#### describe('getLargeMemoryFiles')
|
||||
|
||||
- test('returns files exceeding 40K chars') — 内容 > MAX_MEMORY_CHARACTER_COUNT 的文件被返回
|
||||
- test('returns empty array when all files are small')
|
||||
- test('correctly identifies threshold boundary')
|
||||
|
||||
#### describe('filterInjectedMemoryFiles')
|
||||
|
||||
- test('filters out AutoMem type files') — feature flag 开启时移除自动记忆
|
||||
- test('filters out TeamMem type files')
|
||||
- test('preserves other types') — 非 AutoMem/TeamMem 的文件保留
|
||||
|
||||
#### describe('getExternalClaudeMdIncludes')
|
||||
|
||||
- test('returns includes from outside CWD') — 外部 @include 路径被识别
|
||||
- test('returns empty array when all includes are internal')
|
||||
|
||||
#### describe('hasExternalClaudeMdIncludes')
|
||||
|
||||
- test('returns true when external includes exist')
|
||||
- test('returns false when no external includes')
|
||||
|
||||
---
|
||||
|
||||
### src/utils/systemPrompt.ts
|
||||
|
||||
#### describe('buildEffectiveSystemPrompt')
|
||||
|
||||
- test('returns default system prompt when no overrides') — 无任何覆盖时使用默认提示
|
||||
- test('overrideSystemPrompt replaces everything') — override 模式替换全部内容
|
||||
- test('customSystemPrompt replaces default') — `--system-prompt` 参数替换默认
|
||||
- test('appendSystemPrompt is appended after main prompt') — append 在主提示之后
|
||||
- test('agent definition replaces default prompt') — agent 模式使用 agent prompt
|
||||
- test('agent definition with append combines both') — agent prompt + append
|
||||
- test('override takes precedence over agent and custom') — 优先级最高
|
||||
- test('returns array of strings') — 返回值为 SystemPrompt 类型（字符串数组）
|
||||
|
||||
---
|
||||
|
||||
### src/context.ts — 需 Mock 的部分
|
||||
|
||||
#### describe('getGitStatus')
|
||||
|
||||
- test('returns formatted git status string') — 包含 branch、status、log、user
|
||||
- test('truncates status at 2000 chars') — 超长 status 被截断
|
||||
- test('returns null in test environment') — `NODE_ENV=test` 时返回 null
|
||||
- test('returns null in non-git directory') — 非 git 仓库返回 null
|
||||
- test('runs git commands in parallel') — 多个 git 命令并行执行
|
||||
|
||||
#### describe('getSystemContext')
|
||||
|
||||
- test('includes gitStatus key') — 返回对象包含 gitStatus
|
||||
- test('returns memoized result on subsequent calls') — 多次调用返回同一结果
|
||||
- test('skips git when instructions disabled')
|
||||
|
||||
#### describe('getUserContext')
|
||||
|
||||
- test('includes currentDate key') — 返回对象包含当前日期
|
||||
- test('includes claudeMd key when CLAUDE.md exists') — 加载 CLAUDE.md 内容
|
||||
- test('respects CLAUDE_CODE_DISABLE_CLAUDE_MDS env') — 设置后不加载 CLAUDE.md
|
||||
- test('returns memoized result')
|
||||
|
||||
#### describe('setSystemPromptInjection')
|
||||
|
||||
- test('clears memoized context caches') — 调用后下次 getSystemContext/getUserContext 重新计算
|
||||
- test('injection value is accessible via getSystemPromptInjection')
|
||||
|
||||
---
|
||||
|
||||
## Mock 需求
|
||||
|
||||
| 依赖 | Mock 方式 | 用途 |
|
||||
|------|-----------|------|
|
||||
| `execFileNoThrow` | `mock.module` | `getGitStatus` 中的 git 命令 |
|
||||
| `getMemoryFiles` | `mock.module` | `getUserContext` 中的 CLAUDE.md 加载 |
|
||||
| `getCwd` | `mock.module` | 路径解析上下文 |
|
||||
| `process.env.NODE_ENV` | 直接设置 | 测试环境检测 |
|
||||
| `process.env.CLAUDE_CODE_DISABLE_CLAUDE_MDS` | 直接设置 | 禁用 CLAUDE.md |
|
||||
|
||||
## 集成测试场景
|
||||
|
||||
放在 `tests/integration/context-build.test.ts`：
|
||||
|
||||
### describe('Context assembly pipeline')
|
||||
|
||||
- test('getUserContext produces claudeMd containing CLAUDE.md content') — 端到端验证 CLAUDE.md 被正确加载到 context
|
||||
- test('buildEffectiveSystemPrompt + getUserContext produces complete prompt') — 系统提示 + 用户上下文完整性
|
||||
- test('setSystemPromptInjection invalidates and rebuilds context') — 注入后重新构建上下文
|
||||
@@ -1,104 +0,0 @@
|
||||
# 权限系统测试计划
|
||||
|
||||
## 概述
|
||||
|
||||
权限系统控制工具是否可以执行，包含规则解析器、权限检查管线和权限模式判断。测试重点是纯函数解析器和规则匹配逻辑。
|
||||
|
||||
## 被测文件
|
||||
|
||||
| 文件 | 关键导出 |
|
||||
|------|----------|
|
||||
| `src/utils/permissions/permissionRuleParser.ts` | `permissionRuleValueFromString`, `permissionRuleValueToString`, `escapeRuleContent`, `unescapeRuleContent`, `normalizeLegacyToolName`, `getLegacyToolNames` |
|
||||
| `src/utils/permissions/PermissionMode.ts` | 权限模式常量和辅助函数 |
|
||||
| `src/utils/permissions/permissions.ts` | `hasPermissionsToUseTool`, `getDenyRuleForTool`, `checkRuleBasedPermissions` |
|
||||
| `src/types/permissions.ts` | `PermissionMode`, `PermissionBehavior`, `PermissionRule` 类型定义 |
|
||||
|
||||
---
|
||||
|
||||
## 测试用例
|
||||
|
||||
### src/utils/permissions/permissionRuleParser.ts
|
||||
|
||||
#### describe('escapeRuleContent')
|
||||
|
||||
- test('escapes backslashes first') — `'test\\value'` → `'test\\\\value'`
|
||||
- test('escapes opening parentheses') — `'print(1)'` → `'print\\(1\\)'`
|
||||
- test('escapes closing parentheses') — `'func()'` → `'func\\(\\)'`
|
||||
- test('handles combined escape') — `'echo "test\\nvalue"'` 中的 `\\` 先转义
|
||||
- test('handles empty string') — `''` → `''`
|
||||
- test('no-op for string without special chars') — `'npm install'` 原样返回
|
||||
|
||||
#### describe('unescapeRuleContent')
|
||||
|
||||
- test('unescapes parentheses') — `'print\\(1\\)'` → `'print(1)'`
|
||||
- test('unescapes backslashes last') — `'test\\\\nvalue'` → `'test\\nvalue'`
|
||||
- test('handles empty string')
|
||||
- test('roundtrip: escape then unescape returns original') — `unescapeRuleContent(escapeRuleContent(x)) === x`
|
||||
|
||||
#### describe('permissionRuleValueFromString')
|
||||
|
||||
- test('parses tool name only') — `'Bash'` → `{ toolName: 'Bash' }`
|
||||
- test('parses tool name with content') — `'Bash(npm install)'` → `{ toolName: 'Bash', ruleContent: 'npm install' }`
|
||||
- test('parses content with escaped parentheses') — `'Bash(python -c "print\\(1\\)")'` → ruleContent 为 `'python -c "print(1)"'`
|
||||
- test('treats empty parens as tool-wide rule') — `'Bash()'` → `{ toolName: 'Bash' }`（无 ruleContent）
|
||||
- test('treats wildcard content as tool-wide rule') — `'Bash(*)'` → `{ toolName: 'Bash' }`
|
||||
- test('normalizes legacy tool names') — `'Task'` → `{ toolName: 'Agent' }`（或对应的 AGENT_TOOL_NAME）
|
||||
- test('handles malformed input: no closing paren') — `'Bash(npm'` → 整个字符串作为 toolName
|
||||
- test('handles malformed input: content after closing paren') — `'Bash(npm)extra'` → 整个字符串作为 toolName
|
||||
- test('handles missing tool name') — `'(foo)'` → 整个字符串作为 toolName
|
||||
|
||||
#### describe('permissionRuleValueToString')
|
||||
|
||||
- test('serializes tool name only') — `{ toolName: 'Bash' }` → `'Bash'`
|
||||
- test('serializes with content') — `{ toolName: 'Bash', ruleContent: 'npm install' }` → `'Bash(npm install)'`
|
||||
- test('escapes content with parentheses') — ruleContent 含 `()` 时正确转义
|
||||
- test('roundtrip: fromString then toString preserves value') — 往返一致
|
||||
|
||||
#### describe('normalizeLegacyToolName')
|
||||
|
||||
- test('maps Task to Agent tool name') — `'Task'` → AGENT_TOOL_NAME
|
||||
- test('maps KillShell to TaskStop tool name') — `'KillShell'` → TASK_STOP_TOOL_NAME
|
||||
- test('maps AgentOutputTool to TaskOutput tool name')
|
||||
- test('returns unknown names unchanged') — `'UnknownTool'` → `'UnknownTool'`
|
||||
|
||||
#### describe('getLegacyToolNames')
|
||||
|
||||
- test('returns legacy names for canonical name') — 给定 AGENT_TOOL_NAME 返回包含 `'Task'`
|
||||
- test('returns empty array for name with no legacy aliases')
|
||||
|
||||
---
|
||||
|
||||
### src/utils/permissions/permissions.ts — 需 Mock
|
||||
|
||||
#### describe('getDenyRuleForTool')
|
||||
|
||||
- test('returns deny rule matching tool name') — 匹配到 blanket deny 规则时返回
|
||||
- test('returns null when no deny rules match') — 无匹配时返回 null
|
||||
- test('matches MCP tools by server prefix') — `mcp__server` 规则匹配该 server 下的 MCP 工具
|
||||
- test('does not match content-specific deny rules') — 有 ruleContent 的 deny 规则不作为 blanket deny
|
||||
|
||||
#### describe('checkRuleBasedPermissions')（集成级别）
|
||||
|
||||
- test('deny rule takes precedence over allow') — 同时有 allow 和 deny 时 deny 优先
|
||||
- test('ask rule prompts user') — 匹配 ask 规则返回 `{ behavior: 'ask' }`
|
||||
- test('allow rule permits execution') — 匹配 allow 规则返回 `{ behavior: 'allow' }`
|
||||
- test('passthrough when no rules match') — 无匹配规则返回 passthrough
|
||||
|
||||
---
|
||||
|
||||
## Mock 需求
|
||||
|
||||
| 依赖 | Mock 方式 | 说明 |
|
||||
|------|-----------|------|
|
||||
| `bun:bundle` (feature) | 已 polyfill | BRIEF_TOOL_NAME 条件加载 |
|
||||
| Tool 常量导入 | 实际值 | AGENT_TOOL_NAME 等从常量文件导入 |
|
||||
| `appState` | mock object | `hasPermissionsToUseTool` 中的状态依赖 |
|
||||
| Tool 对象 | mock object | 模拟 tool 的 name, checkPermissions 等 |
|
||||
|
||||
## 集成测试场景
|
||||
|
||||
### describe('Permission pipeline end-to-end')
|
||||
|
||||
- test('deny rule blocks tool before it runs') — deny 规则在 call 前拦截
|
||||
- test('bypassPermissions mode allows all') — bypass 模式下 ask → allow
|
||||
- test('dontAsk mode converts ask to deny') — dontAsk 模式下 ask → deny
|
||||
@@ -1,113 +0,0 @@
|
||||
# 模型路由测试计划
|
||||
|
||||
## 概述
|
||||
|
||||
模型路由系统负责 API provider 选择、模型别名解析、模型名规范化和运行时模型决策。测试重点是纯函数和环境变量驱动的逻辑。
|
||||
|
||||
## 被测文件
|
||||
|
||||
| 文件 | 关键导出 |
|
||||
|------|----------|
|
||||
| `src/utils/model/aliases.ts` | `MODEL_ALIASES`, `MODEL_FAMILY_ALIASES`, `isModelAlias`, `isModelFamilyAlias` |
|
||||
| `src/utils/model/providers.ts` | `APIProvider`, `getAPIProvider`, `isFirstPartyAnthropicBaseUrl` |
|
||||
| `src/utils/model/model.ts` | `firstPartyNameToCanonical`, `getCanonicalName`, `parseUserSpecifiedModel`, `normalizeModelStringForAPI`, `getRuntimeMainLoopModel`, `getDefaultMainLoopModelSetting` |
|
||||
|
||||
---
|
||||
|
||||
## 测试用例
|
||||
|
||||
### src/utils/model/aliases.ts
|
||||
|
||||
#### describe('isModelAlias')
|
||||
|
||||
- test('returns true for "sonnet"') — 有效别名
|
||||
- test('returns true for "opus"')
|
||||
- test('returns true for "haiku"')
|
||||
- test('returns true for "best"')
|
||||
- test('returns true for "sonnet[1m]"')
|
||||
- test('returns true for "opus[1m]"')
|
||||
- test('returns true for "opusplan"')
|
||||
- test('returns false for full model ID') — `'claude-sonnet-4-6-20250514'` → false
|
||||
- test('returns false for unknown string') — `'gpt-4'` → false
|
||||
- test('is case-sensitive') — `'Sonnet'` → false（别名是小写）
|
||||
|
||||
#### describe('isModelFamilyAlias')
|
||||
|
||||
- test('returns true for "sonnet"')
|
||||
- test('returns true for "opus"')
|
||||
- test('returns true for "haiku"')
|
||||
- test('returns false for "best"') — best 不是 family alias
|
||||
- test('returns false for "opusplan"')
|
||||
- test('returns false for "sonnet[1m]"')
|
||||
|
||||
---
|
||||
|
||||
### src/utils/model/providers.ts
|
||||
|
||||
#### describe('getAPIProvider')
|
||||
|
||||
- test('returns "firstParty" by default') — 无相关 env 时返回 firstParty
|
||||
- test('returns "bedrock" when CLAUDE_CODE_USE_BEDROCK is set') — env 为 truthy 值
|
||||
- test('returns "vertex" when CLAUDE_CODE_USE_VERTEX is set')
|
||||
- test('returns "foundry" when CLAUDE_CODE_USE_FOUNDRY is set')
|
||||
- test('bedrock takes precedence over vertex') — 多个 env 同时设置时 bedrock 优先
|
||||
|
||||
#### describe('isFirstPartyAnthropicBaseUrl')
|
||||
|
||||
- test('returns true when ANTHROPIC_BASE_URL is not set') — 默认 API
|
||||
- test('returns true for api.anthropic.com') — `'https://api.anthropic.com'` → true
|
||||
- test('returns false for custom URL') — `'https://my-proxy.com'` → false
|
||||
- test('returns false for invalid URL') — 非法 URL → false
|
||||
- test('returns true for staging URL when USER_TYPE is ant') — `'https://api-staging.anthropic.com'` + ant → true
|
||||
|
||||
---
|
||||
|
||||
### src/utils/model/model.ts
|
||||
|
||||
#### describe('firstPartyNameToCanonical')
|
||||
|
||||
- test('maps opus-4-6 full name to canonical') — `'claude-opus-4-6-20250514'` → `'claude-opus-4-6'`
|
||||
- test('maps sonnet-4-6 full name') — `'claude-sonnet-4-6-20250514'` → `'claude-sonnet-4-6'`
|
||||
- test('maps haiku-4-5') — `'claude-haiku-4-5-20251001'` → `'claude-haiku-4-5'`
|
||||
- test('maps 3P provider format') — `'us.anthropic.claude-opus-4-6-v1:0'` → `'claude-opus-4-6'`
|
||||
- test('maps claude-3-7-sonnet') — `'claude-3-7-sonnet-20250219'` → `'claude-3-7-sonnet'`
|
||||
- test('maps claude-3-5-sonnet') → `'claude-3-5-sonnet'`
|
||||
- test('maps claude-3-5-haiku') → `'claude-3-5-haiku'`
|
||||
- test('maps claude-3-opus') → `'claude-3-opus'`
|
||||
- test('is case insensitive') — `'Claude-Opus-4-6'` → `'claude-opus-4-6'`
|
||||
- test('falls back to input for unknown model') — `'unknown-model'` → `'unknown-model'`
|
||||
- test('differentiates opus-4 vs opus-4-5 vs opus-4-6') — 更具体的版本优先匹配
|
||||
|
||||
#### describe('parseUserSpecifiedModel')
|
||||
|
||||
- test('resolves "sonnet" to default sonnet model')
|
||||
- test('resolves "opus" to default opus model')
|
||||
- test('resolves "haiku" to default haiku model')
|
||||
- test('resolves "best" to best model')
|
||||
- test('resolves "opusplan" to default sonnet model') — opusplan 默认用 sonnet
|
||||
- test('appends [1m] suffix when alias has [1m]') — `'sonnet[1m]'` → 模型名 + `'[1m]'`
|
||||
- test('preserves original case for custom model names') — `'my-Custom-Model'` 保留大小写
|
||||
- test('handles [1m] suffix on non-alias models') — `'custom-model[1m]'` → `'custom-model[1m]'`
|
||||
- test('trims whitespace') — `' sonnet '` → 正确解析
|
||||
|
||||
#### describe('getRuntimeMainLoopModel')
|
||||
|
||||
- test('returns mainLoopModel by default') — 无特殊条件时原样返回
|
||||
- test('returns opus in plan mode when opusplan is set') — opusplan + plan mode → opus
|
||||
- test('returns sonnet in plan mode when haiku is set') — haiku + plan mode → sonnet 升级
|
||||
- test('returns mainLoopModel in non-plan mode') — 非 plan 模式不做替换
|
||||
|
||||
---
|
||||
|
||||
## Mock 需求
|
||||
|
||||
| 依赖 | Mock 方式 | 说明 |
|
||||
|------|-----------|------|
|
||||
| `process.env.CLAUDE_CODE_USE_BEDROCK/VERTEX/FOUNDRY` | 直接设置/恢复 | provider 选择 |
|
||||
| `process.env.ANTHROPIC_BASE_URL` | 直接设置/恢复 | URL 检测 |
|
||||
| `process.env.USER_TYPE` | 直接设置/恢复 | staging URL 和 ant 功能 |
|
||||
| `getModelStrings()` | mock.module | 返回固定模型 ID |
|
||||
| `getMainLoopModelOverride` | mock.module | 会话中模型覆盖 |
|
||||
| `getSettings_DEPRECATED` | mock.module | 用户设置中的模型 |
|
||||
| `getUserSpecifiedModelSetting` | mock.module | `getRuntimeMainLoopModel` 依赖 |
|
||||
| `isModelAllowed` | mock.module | allowlist 检查 |
|
||||
@@ -1,165 +0,0 @@
|
||||
# 消息处理测试计划
|
||||
|
||||
## 概述
|
||||
|
||||
消息处理系统负责消息的创建、查询、规范化和文本提取。覆盖消息类型定义、消息工厂函数、消息过滤/查询工具和 API 规范化管线。
|
||||
|
||||
## 被测文件
|
||||
|
||||
| 文件 | 关键导出 |
|
||||
|------|----------|
|
||||
| `src/types/message.ts` | `MessageType`, `Message`, `AssistantMessage`, `UserMessage`, `SystemMessage` 等类型 |
|
||||
| `src/utils/messages.ts` | 消息创建、查询、规范化、文本提取等函数（~3100 行） |
|
||||
| `src/utils/messages/mappers.ts` | 消息映射工具 |
|
||||
|
||||
---
|
||||
|
||||
## 测试用例
|
||||
|
||||
### src/utils/messages.ts — 消息创建
|
||||
|
||||
#### describe('createAssistantMessage')
|
||||
|
||||
- test('creates message with type "assistant"') — type 字段正确
|
||||
- test('creates message with role "assistant"') — role 正确
|
||||
- test('creates message with empty content array') — 默认 content 为空
|
||||
- test('generates unique uuid') — 每次调用 uuid 不同
|
||||
- test('includes costUsd as 0')
|
||||
|
||||
#### describe('createUserMessage')
|
||||
|
||||
- test('creates message with type "user"') — type 字段正确
|
||||
- test('creates message with provided content') — content 正确传入
|
||||
- test('generates unique uuid')
|
||||
|
||||
#### describe('createSystemMessage')
|
||||
|
||||
- test('creates system message with correct type')
|
||||
- test('includes message content')
|
||||
|
||||
#### describe('createProgressMessage')
|
||||
|
||||
- test('creates progress message with data')
|
||||
- test('has correct type "progress"')
|
||||
|
||||
---
|
||||
|
||||
### src/utils/messages.ts — 消息查询
|
||||
|
||||
#### describe('getLastAssistantMessage')
|
||||
|
||||
- test('returns last assistant message from array') — 多条消息中返回最后一条 assistant
|
||||
- test('returns undefined for empty array')
|
||||
- test('returns undefined when no assistant messages exist')
|
||||
|
||||
#### describe('hasToolCallsInLastAssistantTurn')
|
||||
|
||||
- test('returns true when last assistant has tool_use content') — content 含 tool_use block
|
||||
- test('returns false when last assistant has only text')
|
||||
- test('returns false for empty messages')
|
||||
|
||||
#### describe('isSyntheticMessage')
|
||||
|
||||
- test('identifies interrupt message as synthetic') — INTERRUPT_MESSAGE 标记
|
||||
- test('identifies cancel message as synthetic')
|
||||
- test('returns false for normal user messages')
|
||||
|
||||
#### describe('isNotEmptyMessage')
|
||||
|
||||
- test('returns true for message with content')
|
||||
- test('returns false for message with empty content array')
|
||||
- test('returns false for message with empty text content')
|
||||
|
||||
---
|
||||
|
||||
### src/utils/messages.ts — 文本提取
|
||||
|
||||
#### describe('getAssistantMessageText')
|
||||
|
||||
- test('extracts text from text blocks') — content 含 `{ type: 'text', text: 'hello' }` 时提取
|
||||
- test('returns empty string for non-text content') — 仅含 tool_use 时返回空
|
||||
- test('concatenates multiple text blocks')
|
||||
|
||||
#### describe('getUserMessageText')
|
||||
|
||||
- test('extracts text from string content') — content 为纯字符串
|
||||
- test('extracts text from content array') — content 为数组时提取 text 块
|
||||
- test('handles empty content')
|
||||
|
||||
#### describe('extractTextContent')
|
||||
|
||||
- test('extracts text items from mixed content') — 过滤出 type: 'text' 的项
|
||||
- test('returns empty array for all non-text content')
|
||||
|
||||
---
|
||||
|
||||
### src/utils/messages.ts — 规范化
|
||||
|
||||
#### describe('normalizeMessages')
|
||||
|
||||
- test('converts raw messages to normalized format') — 消息数组规范化
|
||||
- test('handles empty array') — `[]` → `[]`
|
||||
- test('preserves message order')
|
||||
- test('handles mixed message types')
|
||||
|
||||
#### describe('normalizeMessagesForAPI')
|
||||
|
||||
- test('filters out system messages') — 系统消息不发送给 API
|
||||
- test('filters out progress messages')
|
||||
- test('filters out attachment messages')
|
||||
- test('preserves user and assistant messages')
|
||||
- test('reorders tool results to match API expectations')
|
||||
- test('handles empty array')
|
||||
|
||||
---
|
||||
|
||||
### src/utils/messages.ts — 合并
|
||||
|
||||
#### describe('mergeUserMessages')
|
||||
|
||||
- test('merges consecutive user messages') — 相邻用户消息合并
|
||||
- test('does not merge non-consecutive user messages')
|
||||
- test('preserves assistant messages between user messages')
|
||||
|
||||
#### describe('mergeAssistantMessages')
|
||||
|
||||
- test('merges consecutive assistant messages')
|
||||
- test('combines content arrays')
|
||||
|
||||
---
|
||||
|
||||
### src/utils/messages.ts — 辅助函数
|
||||
|
||||
#### describe('buildMessageLookups')
|
||||
|
||||
- test('builds index by message uuid') — 按 uuid 建立查找表
|
||||
- test('returns empty lookups for empty messages')
|
||||
- test('handles duplicate uuids gracefully')
|
||||
|
||||
---
|
||||
|
||||
## Mock 需求
|
||||
|
||||
| 依赖 | Mock 方式 | 说明 |
|
||||
|------|-----------|------|
|
||||
| `crypto.randomUUID` | `mock` 或 spy | 消息创建中的 uuid 生成 |
|
||||
| Message 对象 | 手动构造 | 创建符合类型的 mock 消息对象 |
|
||||
|
||||
### Mock 消息工厂（放在 `tests/mocks/messages.ts`）
|
||||
|
||||
```typescript
|
||||
// 通用 mock 消息构造器
|
||||
export function mockAssistantMessage(overrides?: Partial<AssistantMessage>): AssistantMessage
|
||||
export function mockUserMessage(content: string, overrides?: Partial<UserMessage>): UserMessage
|
||||
export function mockSystemMessage(overrides?: Partial<SystemMessage>): SystemMessage
|
||||
export function mockToolUseBlock(name: string, input: unknown): ToolUseBlock
|
||||
export function mockToolResultMessage(toolUseId: string, content: string): UserMessage
|
||||
```
|
||||
|
||||
## 集成测试场景
|
||||
|
||||
### describe('Message pipeline')
|
||||
|
||||
- test('create → normalize → API format produces valid request') — 创建消息 → normalizeMessagesForAPI → 验证输出结构
|
||||
- test('tool use and tool result pairing is preserved through normalization')
|
||||
- test('merge + normalize handles conversation with interruptions')
|
||||
@@ -1,112 +0,0 @@
|
||||
# Cron 调度测试计划
|
||||
|
||||
## 概述
|
||||
|
||||
Cron 模块提供 cron 表达式解析、下次运行时间计算和人类可读描述。全部为纯函数，无外部依赖，是最适合单元测试的模块之一。
|
||||
|
||||
## 被测文件
|
||||
|
||||
| 文件 | 关键导出 |
|
||||
|------|----------|
|
||||
| `src/utils/cron.ts` | `CronFields`, `parseCronExpression`, `computeNextCronRun`, `cronToHuman` |
|
||||
|
||||
---
|
||||
|
||||
## 测试用例
|
||||
|
||||
### describe('parseCronExpression')
|
||||
|
||||
#### 有效表达式
|
||||
|
||||
- test('parses wildcard fields') — `'* * * * *'` → 每个字段为完整范围
|
||||
- test('parses specific values') — `'30 14 1 6 3'` → minute=[30], hour=[14], dom=[1], month=[6], dow=[3]
|
||||
- test('parses step syntax') — `'*/5 * * * *'` → minute=[0,5,10,...,55]
|
||||
- test('parses range syntax') — `'1-5 * * * *'` → minute=[1,2,3,4,5]
|
||||
- test('parses range with step') — `'1-10/3 * * * *'` → minute=[1,4,7,10]
|
||||
- test('parses comma-separated list') — `'1,15,30 * * * *'` → minute=[1,15,30]
|
||||
- test('parses day-of-week 7 as Sunday alias') — `'0 0 * * 7'` → dow=[0]
|
||||
- test('parses range with day-of-week 7') — `'0 0 * * 5-7'` → dow=[0,5,6]
|
||||
- test('parses complex combined expression') — `'0,30 9-17 * * 1-5'` → 工作日 9-17 每半小时
|
||||
|
||||
#### 无效表达式
|
||||
|
||||
- test('returns null for wrong field count') — `'* * *'` → null
|
||||
- test('returns null for out-of-range values') — `'60 * * * *'` → null（minute max=59）
|
||||
- test('returns null for invalid step') — `'*/0 * * * *'` → null（step=0）
|
||||
- test('returns null for reversed range') — `'10-5 * * * *'` → null（lo>hi）
|
||||
- test('returns null for empty string') — `''` → null
|
||||
- test('returns null for non-numeric tokens') — `'abc * * * *'` → null
|
||||
|
||||
#### 字段范围验证
|
||||
|
||||
- test('minute: 0-59')
|
||||
- test('hour: 0-23')
|
||||
- test('dayOfMonth: 1-31')
|
||||
- test('month: 1-12')
|
||||
- test('dayOfWeek: 0-6 (plus 7 alias)')
|
||||
|
||||
---
|
||||
|
||||
### describe('computeNextCronRun')
|
||||
|
||||
#### 基本匹配
|
||||
|
||||
- test('finds next minute') — from 14:30:45, cron `'31 14 * * *'` → 14:31:00 同天
|
||||
- test('finds next hour') — from 14:30, cron `'0 15 * * *'` → 15:00 同天
|
||||
- test('rolls to next day') — from 14:30, cron `'0 10 * * *'` → 10:00 次日
|
||||
- test('rolls to next month') — from 1月31日, cron `'0 0 1 * *'` → 2月1日
|
||||
- test('is strictly after from date') — from 恰好匹配时应返回下一次而非当前时间
|
||||
|
||||
#### DOM/DOW 语义
|
||||
|
||||
- test('OR semantics when both dom and dow constrained') — dom=15, dow=3 → 匹配 15 号 OR 周三
|
||||
- test('only dom constrained uses dom') — dom=15, dow=* → 只匹配 15 号
|
||||
- test('only dow constrained uses dow') — dom=*, dow=3 → 只匹配周三
|
||||
- test('both wildcarded matches every day') — dom=*, dow=* → 每天
|
||||
|
||||
#### 边界情况
|
||||
|
||||
- test('handles month boundary') — 从 2 月 28 日寻找 2 月 29 日或 3 月 1 日
|
||||
- test('returns null after 366-day search') — 不可能匹配的表达式返回 null（理论上不会发生）
|
||||
- test('handles step across midnight') — `'0 0 * * *'` 从 23:59 → 次日 0:00
|
||||
|
||||
#### 每 N 分钟
|
||||
|
||||
- test('every 5 minutes from arbitrary time') — `'*/5 * * * *'` from 14:32 → 14:35
|
||||
- test('every minute') — `'* * * * *'` from 14:32:45 → 14:33:00
|
||||
|
||||
---
|
||||
|
||||
### describe('cronToHuman')
|
||||
|
||||
#### 常见模式
|
||||
|
||||
- test('every N minutes') — `'*/5 * * * *'` → `'Every 5 minutes'`
|
||||
- test('every minute') — `'*/1 * * * *'` → `'Every minute'`
|
||||
- test('every hour at :00') — `'0 * * * *'` → `'Every hour'`
|
||||
- test('every hour at :30') — `'30 * * * *'` → `'Every hour at :30'`
|
||||
- test('every N hours') — `'0 */2 * * *'` → `'Every 2 hours'`
|
||||
- test('daily at specific time') — `'30 9 * * *'` → `'Every day at 9:30 AM'`
|
||||
- test('specific day of week') — `'0 9 * * 3'` → `'Every Wednesday at 9:00 AM'`
|
||||
- test('weekdays') — `'0 9 * * 1-5'` → `'Weekdays at 9:00 AM'`
|
||||
|
||||
#### Fallback
|
||||
|
||||
- test('returns raw cron for complex patterns') — 非常见模式返回原始 cron 字符串
|
||||
- test('returns raw cron for wrong field count') — `'* * *'` → 原样返回
|
||||
|
||||
#### UTC 模式
|
||||
|
||||
- test('UTC option formats time in local timezone') — `{ utc: true }` 时 UTC 时间转本地显示
|
||||
- test('UTC midnight crossing adjusts day name') — UTC 时间跨天时本地星期名正确
|
||||
|
||||
---
|
||||
|
||||
## Mock 需求
|
||||
|
||||
**无需 Mock**。所有函数为纯函数，唯一的外部依赖是 `Date` 构造器和 `toLocaleTimeString`，可通过传入确定性的 `from` 参数控制。
|
||||
|
||||
## 注意事项
|
||||
|
||||
- `cronToHuman` 的时间格式化依赖系统 locale，测试中建议使用 `'en-US'` locale 或只验证部分输出
|
||||
- `computeNextCronRun` 使用本地时区，DST 相关测试需注意运行环境
|
||||
@@ -1,106 +0,0 @@
|
||||
# Git 工具测试计划
|
||||
|
||||
## 概述
|
||||
|
||||
Git 工具模块提供 git 远程 URL 规范化、仓库根目录查找、裸仓库安全检测等功能。测试重点是纯函数的 URL 规范化和需要文件系统 mock 的仓库发现逻辑。
|
||||
|
||||
## 被测文件
|
||||
|
||||
| 文件 | 关键导出 |
|
||||
|------|----------|
|
||||
| `src/utils/git.ts` | `normalizeGitRemoteUrl`, `findGitRoot`, `findCanonicalGitRoot`, `getIsGit`, `isAtGitRoot`, `getRepoRemoteHash`, `isCurrentDirectoryBareGitRepo`, `gitExe`, `getGitState`, `stashToCleanState`, `preserveGitStateForIssue` |
|
||||
|
||||
---
|
||||
|
||||
## 测试用例
|
||||
|
||||
### describe('normalizeGitRemoteUrl')（纯函数）
|
||||
|
||||
#### SSH 格式
|
||||
|
||||
- test('normalizes SSH URL') — `'git@github.com:owner/repo.git'` → `'github.com/owner/repo'`
|
||||
- test('normalizes SSH URL without .git suffix') — `'git@github.com:owner/repo'` → `'github.com/owner/repo'`
|
||||
- test('handles GitLab SSH') — `'git@gitlab.com:group/subgroup/repo.git'` → `'gitlab.com/group/subgroup/repo'`
|
||||
|
||||
#### HTTPS 格式
|
||||
|
||||
- test('normalizes HTTPS URL') — `'https://github.com/owner/repo.git'` → `'github.com/owner/repo'`
|
||||
- test('normalizes HTTPS URL without .git suffix') — `'https://github.com/owner/repo'` → `'github.com/owner/repo'`
|
||||
- test('normalizes HTTP URL') — `'http://github.com/owner/repo.git'` → `'github.com/owner/repo'`
|
||||
|
||||
#### SSH:// 协议格式
|
||||
|
||||
- test('normalizes ssh:// URL') — `'ssh://git@github.com/owner/repo'` → `'github.com/owner/repo'`
|
||||
- test('handles user prefix in ssh://') — `'ssh://user@host/path'` → `'host/path'`
|
||||
|
||||
#### 代理 URL（CCR git proxy）
|
||||
|
||||
- test('normalizes legacy proxy URL') — `'http://local_proxy@127.0.0.1:16583/git/owner/repo'` → `'github.com/owner/repo'`
|
||||
- test('normalizes GHE proxy URL') — `'http://user@127.0.0.1:8080/git/ghe.company.com/owner/repo'` → `'ghe.company.com/owner/repo'`
|
||||
|
||||
#### 边界情况
|
||||
|
||||
- test('returns null for empty string') — `''` → null
|
||||
- test('returns null for whitespace') — `' '` → null
|
||||
- test('returns null for unrecognized format') — `'not-a-url'` → null
|
||||
- test('output is lowercase') — `'git@GitHub.com:Owner/Repo.git'` → `'github.com/owner/repo'`
|
||||
- test('SSH and HTTPS for same repo produce same result') — 相同仓库不同协议 → 相同输出
|
||||
|
||||
---
|
||||
|
||||
### describe('findGitRoot')（需文件系统 Mock）
|
||||
|
||||
- test('finds git root from nested directory') — `/project/src/utils/` → `/project/`（假设 `/project/.git` 存在）
|
||||
- test('finds git root from root directory') — `/project/` → `/project/`
|
||||
- test('returns null for non-git directory') — 无 `.git` → null
|
||||
- test('handles worktree .git file') — `.git` 为文件时也识别
|
||||
- test('memoizes results') — 同一路径不重复查找
|
||||
|
||||
### describe('findCanonicalGitRoot')
|
||||
|
||||
- test('returns same as findGitRoot for regular repo')
|
||||
- test('resolves worktree to main repo root') — worktree 路径 → 主仓库根目录
|
||||
- test('returns null for non-git directory')
|
||||
|
||||
### describe('gitExe')
|
||||
|
||||
- test('returns git path string') — 返回字符串
|
||||
- test('memoizes the result') — 多次调用返回同一值
|
||||
|
||||
---
|
||||
|
||||
### describe('getRepoRemoteHash')（需 Mock）
|
||||
|
||||
- test('returns 16-char hex hash') — 返回值为 16 位十六进制字符串
|
||||
- test('returns null when no remote') — 无 remote URL 时返回 null
|
||||
- test('same repo SSH/HTTPS produce same hash') — 不同协议同一仓库 hash 相同
|
||||
|
||||
---
|
||||
|
||||
### describe('isCurrentDirectoryBareGitRepo')（需文件系统 Mock）
|
||||
|
||||
- test('detects bare git repo attack vector') — 目录含 HEAD + objects/ + refs/ 但无有效 .git/HEAD → true
|
||||
- test('returns false for normal directory') — 普通目录 → false
|
||||
- test('returns false for regular git repo') — 有效 .git 目录 → false
|
||||
|
||||
---
|
||||
|
||||
## Mock 需求
|
||||
|
||||
| 依赖 | Mock 方式 | 说明 |
|
||||
|------|-----------|------|
|
||||
| `statSync` | mock module | `findGitRoot` 中的 .git 检测 |
|
||||
| `readFileSync` | mock module | worktree .git 文件读取 |
|
||||
| `realpathSync` | mock module | 路径解析 |
|
||||
| `execFileNoThrow` | mock module | git 命令执行 |
|
||||
| `whichSync` | mock module | `gitExe` 中的 git 路径查找 |
|
||||
| `getCwd` | mock module | 当前工作目录 |
|
||||
| `getRemoteUrl` | mock module | `getRepoRemoteHash` 依赖 |
|
||||
| 临时目录 | `mkdtemp` | 集成测试中创建临时 git 仓库 |
|
||||
|
||||
## 集成测试场景
|
||||
|
||||
### describe('Git repo discovery')（放在 tests/integration/）
|
||||
|
||||
- test('findGitRoot works in actual git repo') — 在临时 git init 的目录中验证
|
||||
- test('normalizeGitRemoteUrl + getRepoRemoteHash produces stable hash') — URL → hash 端到端验证
|
||||
@@ -1,161 +0,0 @@
|
||||
# 配置系统测试计划
|
||||
|
||||
## 概述
|
||||
|
||||
配置系统包含全局配置（GlobalConfig）、项目配置（ProjectConfig）和设置（Settings）三层。测试重点是纯函数校验逻辑、Zod schema 验证和配置合并策略。
|
||||
|
||||
## 被测文件
|
||||
|
||||
| 文件 | 关键导出 |
|
||||
|------|----------|
|
||||
| `src/utils/config.ts` | `getGlobalConfig`, `saveGlobalConfig`, `getCurrentProjectConfig`, `checkHasTrustDialogAccepted`, `isPathTrusted`, `getOrCreateUserID`, `isAutoUpdaterDisabled` |
|
||||
| `src/utils/settings/settings.ts` | `getSettingsForSource`, `parseSettingsFile`, `getSettingsFilePathForSource`, `getInitialSettings` |
|
||||
| `src/utils/settings/types.ts` | `SettingsSchema`（Zod schema） |
|
||||
| `src/utils/settings/validation.ts` | 设置验证函数 |
|
||||
| `src/utils/settings/constants.ts` | 设置常量 |
|
||||
|
||||
---
|
||||
|
||||
## 测试用例
|
||||
|
||||
### src/utils/config.ts — 纯函数/常量
|
||||
|
||||
#### describe('DEFAULT_GLOBAL_CONFIG')
|
||||
|
||||
- test('has all required fields') — 默认配置对象包含所有必需字段
|
||||
- test('has null auth fields by default') — oauthAccount 等为 null
|
||||
|
||||
#### describe('DEFAULT_PROJECT_CONFIG')
|
||||
|
||||
- test('has empty allowedTools') — 默认为空数组
|
||||
- test('has empty mcpServers') — 默认为空对象
|
||||
|
||||
#### describe('isAutoUpdaterDisabled')
|
||||
|
||||
- test('returns true when CLAUDE_CODE_DISABLE_AUTOUPDATER is set') — env 设置时禁用
|
||||
- test('returns true when disableAutoUpdater config is true')
|
||||
- test('returns false by default')
|
||||
|
||||
---
|
||||
|
||||
### src/utils/config.ts — 需 Mock
|
||||
|
||||
#### describe('getGlobalConfig')
|
||||
|
||||
- test('returns cached config on subsequent calls') — 缓存机制
|
||||
- test('returns TEST_GLOBAL_CONFIG_FOR_TESTING in test mode')
|
||||
- test('reads config from ~/.claude.json')
|
||||
- test('returns default config when file does not exist')
|
||||
|
||||
#### describe('saveGlobalConfig')
|
||||
|
||||
- test('applies updater function to current config') — updater 修改被保存
|
||||
- test('creates backup before writing') — 写入前备份
|
||||
- test('prevents auth state loss') — `wouldLoseAuthState` 检查
|
||||
|
||||
#### describe('getCurrentProjectConfig')
|
||||
|
||||
- test('returns project config for current directory')
|
||||
- test('returns default config when no project config exists')
|
||||
|
||||
#### describe('checkHasTrustDialogAccepted')
|
||||
|
||||
- test('returns true when trust is accepted in current directory')
|
||||
- test('returns true when parent directory is trusted') — 父目录信任传递
|
||||
- test('returns false when no trust accepted')
|
||||
- test('caches positive results')
|
||||
|
||||
#### describe('isPathTrusted')
|
||||
|
||||
- test('returns true for trusted path')
|
||||
- test('returns false for untrusted path')
|
||||
|
||||
#### describe('getOrCreateUserID')
|
||||
|
||||
- test('returns existing user ID from config')
|
||||
- test('creates and persists new ID when none exists')
|
||||
- test('returns consistent ID across calls')
|
||||
|
||||
---
|
||||
|
||||
### src/utils/settings/settings.ts
|
||||
|
||||
#### describe('getSettingsFilePathForSource')
|
||||
|
||||
- test('returns ~/.claude/settings.json for userSettings') — 全局用户设置路径
|
||||
- test('returns .claude/settings.json for projectSettings') — 项目设置路径
|
||||
- test('returns .claude/settings.local.json for localSettings') — 本地设置路径
|
||||
|
||||
#### describe('parseSettingsFile')（需 Mock 文件读取）
|
||||
|
||||
- test('parses valid settings JSON') — 有效 JSON → `{ settings, errors: [] }`
|
||||
- test('returns errors for invalid fields') — 无效字段 → errors 非空
|
||||
- test('returns empty settings for non-existent file')
|
||||
- test('handles JSON with comments') — JSONC 格式支持
|
||||
|
||||
#### describe('getInitialSettings')
|
||||
|
||||
- test('merges settings from all sources') — user + project + local 合并
|
||||
- test('later sources override earlier ones') — 优先级：policy > user > project > local
|
||||
|
||||
---
|
||||
|
||||
### src/utils/settings/types.ts — Zod Schema 验证
|
||||
|
||||
#### describe('SettingsSchema validation')
|
||||
|
||||
- test('accepts valid minimal settings') — `{}` → 有效
|
||||
- test('accepts permissions block') — `{ permissions: { allow: ['Bash(*)'] } }` → 有效
|
||||
- test('accepts model setting') — `{ model: 'sonnet' }` → 有效
|
||||
- test('accepts hooks configuration') — 有效的 hooks 对象被接受
|
||||
- test('accepts env variables') — `{ env: { FOO: 'bar' } }` → 有效
|
||||
- test('rejects unknown top-level keys') — 未知字段被拒绝或忽略（取决于 schema 配置）
|
||||
- test('rejects invalid permission mode') — `{ permissions: { defaultMode: 'invalid' } }` → 错误
|
||||
- test('rejects non-string model') — `{ model: 123 }` → 错误
|
||||
- test('accepts mcpServers configuration') — MCP server 配置有效
|
||||
- test('accepts sandbox configuration')
|
||||
|
||||
---
|
||||
|
||||
### src/utils/settings/validation.ts
|
||||
|
||||
#### describe('settings validation')
|
||||
|
||||
- test('validates permission rules format') — `'Bash(npm install)'` 格式正确
|
||||
- test('rejects malformed permission rules')
|
||||
- test('validates hook configuration structure')
|
||||
- test('provides helpful error messages') — 错误信息包含字段路径
|
||||
|
||||
---
|
||||
|
||||
## Mock 需求
|
||||
|
||||
| 依赖 | Mock 方式 | 说明 |
|
||||
|------|-----------|------|
|
||||
| 文件系统 | 临时目录 + mock | config 文件读写 |
|
||||
| `lockfile` | mock module | 文件锁 |
|
||||
| `getCwd` | mock module | 项目路径判断 |
|
||||
| `findGitRoot` | mock module | 项目根目录 |
|
||||
| `process.env` | 直接设置/恢复 | `CLAUDE_CODE_DISABLE_AUTOUPDATER` 等 |
|
||||
|
||||
### 测试用临时文件结构
|
||||
|
||||
```
|
||||
/tmp/claude-test-xxx/
|
||||
├── .claude/
|
||||
│ ├── settings.json # projectSettings
|
||||
│ └── settings.local.json # localSettings
|
||||
├── home/
|
||||
│ └── .claude/
|
||||
│ └── settings.json # userSettings（mock HOME）
|
||||
└── project/
|
||||
└── .git/
|
||||
```
|
||||
|
||||
## 集成测试场景
|
||||
|
||||
### describe('Config + Settings merge pipeline')
|
||||
|
||||
- test('user settings + project settings merge correctly') — 验证合并优先级
|
||||
- test('deny rules from settings are reflected in tool permission context')
|
||||
- test('trust dialog state persists across config reads')
|
||||
@@ -1,361 +0,0 @@
|
||||
# Plan 10 — 修复 WEAK 评分测试文件
|
||||
|
||||
> 优先级：高 | 8 个文件 | 预估新增/修改 ~60 个测试用例
|
||||
|
||||
本计划修复 testing-spec.md 中评定为 WEAK 的 8 个测试文件的断言缺陷和覆盖缺口。
|
||||
|
||||
---
|
||||
|
||||
## 10.1 `src/utils/__tests__/format.test.ts`
|
||||
|
||||
**问题**：`formatNumber`、`formatTokens`、`formatRelativeTime` 使用 `toContain` 代替精确匹配，无法检测格式回归。
|
||||
|
||||
### 修改清单
|
||||
|
||||
#### formatNumber — toContain → toBe
|
||||
|
||||
```typescript
|
||||
// 当前（弱）
|
||||
expect(formatNumber(1321)).toContain("k");
|
||||
expect(formatNumber(1500000)).toContain("m");
|
||||
|
||||
// 修复为
|
||||
expect(formatNumber(1321)).toBe("1.3k");
|
||||
expect(formatNumber(1500000)).toBe("1.5m");
|
||||
```
|
||||
|
||||
> 注意：`Intl.NumberFormat` 输出可能因 locale 不同。若 CI locale 不一致，改用 `toMatch(/^\d+(\.\d)?[km]$/)` 正则匹配。
|
||||
|
||||
#### formatTokens — 补精确断言
|
||||
|
||||
```typescript
|
||||
expect(formatTokens(1000)).toBe("1k");
|
||||
expect(formatTokens(1500)).toBe("1.5k");
|
||||
```
|
||||
|
||||
#### formatRelativeTime — toContain → toBe
|
||||
|
||||
```typescript
|
||||
// 当前（弱）
|
||||
expect(formatRelativeTime(diff, now)).toContain("30");
|
||||
expect(formatRelativeTime(diff, now)).toContain("ago");
|
||||
|
||||
// 修复为
|
||||
expect(formatRelativeTime(diff, now)).toBe("30s ago");
|
||||
```
|
||||
|
||||
#### 新增：formatDuration 进位边界
|
||||
|
||||
| 用例 | 输入 | 期望 |
|
||||
|------|------|------|
|
||||
| 59.5s 进位 | 59500ms | 至少含 `1m` |
|
||||
| 59m59s 进位 | 3599000ms | 至少含 `1h` |
|
||||
| sub-millisecond | 0.5ms | `"<1ms"` 或 `"0ms"` |
|
||||
|
||||
#### 新增：未测试函数
|
||||
|
||||
| 函数 | 最少用例 |
|
||||
|------|---------|
|
||||
| `formatRelativeTimeAgo` | 2（过去 / 未来） |
|
||||
| `formatLogMetadata` | 1（基本调用不抛错） |
|
||||
| `formatResetTime` | 2（有值 / null） |
|
||||
| `formatResetText` | 1（基本调用） |
|
||||
|
||||
---
|
||||
|
||||
## 10.2 `src/tools/shared/__tests__/gitOperationTracking.test.ts`
|
||||
|
||||
**问题**：`detectGitOperation` 内部调用 `getCommitCounter()`、`getPrCounter()`、`logEvent()`，测试产生分析副作用。
|
||||
|
||||
### 修改清单
|
||||
|
||||
#### 添加 analytics mock
|
||||
|
||||
在文件顶部添加 `mock.module`：
|
||||
|
||||
```typescript
|
||||
import { mock, afterAll, afterEach, beforeEach } from "bun:test";
|
||||
|
||||
mock.module("src/services/analytics/index.ts", () => ({
|
||||
logEvent: mock(() => {}),
|
||||
}));
|
||||
|
||||
mock.module("src/bootstrap/state.ts", () => ({
|
||||
getCommitCounter: mock(() => ({ increment: mock(() => {}) })),
|
||||
getPrCounter: mock(() => ({ increment: mock(() => {}) })),
|
||||
}));
|
||||
```
|
||||
|
||||
> 需验证 `detectGitOperation` 的实际导入路径，按需调整 mock 目标。
|
||||
|
||||
#### 新增：缺失的 GH PR actions
|
||||
|
||||
| 用例 | 输入 | 期望 |
|
||||
|------|------|------|
|
||||
| gh pr edit | `'gh pr edit 123 --title "fix"'` | `result.pr.number === 123` |
|
||||
| gh pr close | `'gh pr close 456'` | `result.pr.number === 456` |
|
||||
| gh pr ready | `'gh pr ready 789'` | `result.pr.number === 789` |
|
||||
| gh pr comment | `'gh pr comment 123 --body "done"'` | `result.pr.number === 123` |
|
||||
|
||||
#### 新增：parseGitCommitId 边界
|
||||
|
||||
| 用例 | 输入 | 期望 |
|
||||
|------|------|------|
|
||||
| 完整 40 字符 SHA | `'[abcdef0123456789abcdef0123456789abcdef01] ...'` | 返回完整 40 字符 |
|
||||
| 畸形括号输出 | `'create mode 100644 file.txt'` | 返回 `null` |
|
||||
|
||||
---
|
||||
|
||||
## 10.3 `src/utils/permissions/__tests__/PermissionMode.test.ts`
|
||||
|
||||
**问题**：`isExternalPermissionMode` 在非 ant 环境永远返回 true，false 路径从未执行；mode 覆盖不完整。
|
||||
|
||||
### 修改清单
|
||||
|
||||
#### 补全 mode 覆盖
|
||||
|
||||
| 函数 | 缺失的 mode |
|
||||
|------|-------------|
|
||||
| `permissionModeTitle` | `bypassPermissions`, `dontAsk` |
|
||||
| `permissionModeShortTitle` | `dontAsk`, `acceptEdits` |
|
||||
| `getModeColor` | `dontAsk`, `acceptEdits`, `plan` |
|
||||
| `permissionModeFromString` | `acceptEdits`, `bypassPermissions` |
|
||||
| `toExternalPermissionMode` | `acceptEdits`, `bypassPermissions` |
|
||||
|
||||
#### 修复 isExternalPermissionMode
|
||||
|
||||
```typescript
|
||||
// 当前：只测了非 ant 环境（永远 true）
|
||||
// 需要新增 ant 环境测试
|
||||
describe("when USER_TYPE is 'ant'", () => {
|
||||
beforeEach(() => {
|
||||
process.env.USER_TYPE = "ant";
|
||||
});
|
||||
afterEach(() => {
|
||||
delete process.env.USER_TYPE;
|
||||
});
|
||||
|
||||
test("returns false for 'auto' in ant context", () => {
|
||||
expect(isExternalPermissionMode("auto")).toBe(false);
|
||||
});
|
||||
|
||||
test("returns false for 'bubble' in ant context", () => {
|
||||
expect(isExternalPermissionMode("bubble")).toBe(false);
|
||||
});
|
||||
|
||||
test("returns true for non-ant modes in ant context", () => {
|
||||
expect(isExternalPermissionMode("plan")).toBe(true);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
#### 新增：permissionModeSchema
|
||||
|
||||
| 用例 | 输入 | 期望 |
|
||||
|------|------|------|
|
||||
| 有效 mode | `'plan'` | `success: true` |
|
||||
| 无效 mode | `'invalid'` | `success: false` |
|
||||
|
||||
---
|
||||
|
||||
## 10.4 `src/utils/permissions/__tests__/dangerousPatterns.test.ts`
|
||||
|
||||
**问题**：纯数据 smoke test，无行为验证。
|
||||
|
||||
### 修改清单
|
||||
|
||||
#### 新增：重复值检查
|
||||
|
||||
```typescript
|
||||
test("CROSS_PLATFORM_CODE_EXEC has no duplicates", () => {
|
||||
const set = new Set(CROSS_PLATFORM_CODE_EXEC);
|
||||
expect(set.size).toBe(CROSS_PLATFORM_CODE_EXEC.length);
|
||||
});
|
||||
|
||||
test("DANGEROUS_BASH_PATTERNS has no duplicates", () => {
|
||||
const set = new Set(DANGEROUS_BASH_PATTERNS);
|
||||
expect(set.size).toBe(DANGEROUS_BASH_PATTERNS.length);
|
||||
});
|
||||
```
|
||||
|
||||
#### 新增：全量成员断言（用 Set 确保精确）
|
||||
|
||||
```typescript
|
||||
test("CROSS_PLATFORM_CODE_EXEC contains expected interpreters", () => {
|
||||
const expected = ["node", "python", "python3", "ruby", "perl", "php",
|
||||
"bun", "deno", "npx", "tsx"];
|
||||
const set = new Set(CROSS_PLATFORM_CODE_EXEC);
|
||||
for (const entry of expected) {
|
||||
expect(set.has(entry)).toBe(true);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
#### 新增：空字符串不匹配
|
||||
|
||||
```typescript
|
||||
test("empty string does not match any pattern", () => {
|
||||
for (const pattern of DANGEROUS_BASH_PATTERNS) {
|
||||
expect("".startsWith(pattern)).toBe(false);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10.5 `src/utils/__tests__/zodToJsonSchema.test.ts`
|
||||
|
||||
**问题**：object 属性仅 `toBeDefined` 未验证类型结构；optional 字段未验证 absence。
|
||||
|
||||
### 修改清单
|
||||
|
||||
#### 修复 object schema 测试
|
||||
|
||||
```typescript
|
||||
// 当前（弱）
|
||||
expect(schema.properties!.name).toBeDefined();
|
||||
expect(schema.properties!.age).toBeDefined();
|
||||
|
||||
// 修复为
|
||||
expect(schema.properties!.name).toEqual({ type: "string" });
|
||||
expect(schema.properties!.age).toEqual({ type: "number" });
|
||||
```
|
||||
|
||||
#### 修复 optional 字段测试
|
||||
|
||||
```typescript
|
||||
test("optional field is not in required array", () => {
|
||||
const schema = zodToJsonSchema(z.object({
|
||||
required: z.string(),
|
||||
optional: z.string().optional(),
|
||||
}));
|
||||
expect(schema.required).toEqual(["required"]);
|
||||
expect(schema.required).not.toContain("optional");
|
||||
});
|
||||
```
|
||||
|
||||
#### 新增：缺失的 schema 类型
|
||||
|
||||
| 用例 | 输入 | 期望 |
|
||||
|------|------|------|
|
||||
| `z.literal("foo")` | `z.literal("foo")` | `{ const: "foo" }` |
|
||||
| `z.null()` | `z.null()` | `{ type: "null" }` |
|
||||
| `z.union()` | `z.union([z.string(), z.number()])` | `{ anyOf: [...] }` |
|
||||
| `z.record()` | `z.record(z.string(), z.number())` | `{ type: "object", additionalProperties: { type: "number" } }` |
|
||||
| `z.tuple()` | `z.tuple([z.string(), z.number()])` | `{ type: "array", items: [...], additionalItems: false }` |
|
||||
| 嵌套 object | `z.object({ a: z.object({ b: z.string() }) })` | 验证嵌套属性结构 |
|
||||
|
||||
---
|
||||
|
||||
## 10.6 `src/utils/__tests__/envValidation.test.ts`
|
||||
|
||||
**问题**：`validateBoundedIntEnvVar` lower bound=100 时 value=1 返回 `status: "valid"`，疑似源码 bug。
|
||||
|
||||
### 修改清单
|
||||
|
||||
#### 验证 lower bound 行为
|
||||
|
||||
```typescript
|
||||
// 当前测试
|
||||
test("value of 1 with lower bound 100", () => {
|
||||
const result = validateBoundedIntEnvVar("1", { defaultValue: 100, upperLimit: 1000, lowerLimit: 100 });
|
||||
// 如果源码有 bug，这里应该暴露
|
||||
expect(result.effective).toBeGreaterThanOrEqual(100);
|
||||
expect(result.status).toBe(result.effective !== 100 ? "capped" : "valid");
|
||||
});
|
||||
```
|
||||
|
||||
#### 新增边界用例
|
||||
|
||||
| 用例 | value | lowerLimit | 期望 |
|
||||
|------|-------|------------|------|
|
||||
| 低于 lower bound | `"50"` | 100 | `effective: 100, status: "capped"` |
|
||||
| 等于 lower bound | `"100"` | 100 | `effective: 100, status: "valid"` |
|
||||
| 浮点截断 | `"50.7"` | 100 | `effective: 100`（parseInt 截断后 cap） |
|
||||
| 空白字符 | `" 500 "` | 1 | `effective: 500, status: "valid"` |
|
||||
| defaultValue 为 0 | `"0"` | 0 | 需确认 `parsed <= 0` 逻辑 |
|
||||
|
||||
> **行动**：先确认 `validateBoundedIntEnvVar` 源码中 lower bound 的实际执行路径。如果确实不生效，需先修源码再补测试。
|
||||
|
||||
---
|
||||
|
||||
## 10.7 `src/utils/__tests__/file.test.ts`
|
||||
|
||||
**问题**：`addLineNumbers` 仅 `toContain`，未验证完整格式。
|
||||
|
||||
### 修改清单
|
||||
|
||||
#### 修复 addLineNumbers 断言
|
||||
|
||||
```typescript
|
||||
// 当前（弱）
|
||||
expect(result).toContain("1");
|
||||
expect(result).toContain("hello");
|
||||
|
||||
// 修复为（需确定 isCompactLinePrefixEnabled 行为）
|
||||
// 假设 compact=false，格式为 " 1→hello"
|
||||
test("formats single line with tab prefix", () => {
|
||||
// 先确认环境，如果 compact 模式不确定，用正则
|
||||
expect(result).toMatch(/^\s*\d+[→\t]hello$/m);
|
||||
});
|
||||
```
|
||||
|
||||
#### 新增：stripLineNumberPrefix 边界
|
||||
|
||||
| 用例 | 输入 | 期望 |
|
||||
|------|------|------|
|
||||
| 纯数字行 | `"123"` | `""` |
|
||||
| 无内容前缀 | `"→"` | `""` |
|
||||
| compact 格式 `"1\thello"` | `"1\thello"` | `"hello"` |
|
||||
|
||||
#### 新增：pathsEqual 边界
|
||||
|
||||
| 用例 | a | b | 期望 |
|
||||
|------|---|---|------|
|
||||
| 尾部斜杠差异 | `"/a/b"` | `"/a/b/"` | `false` |
|
||||
| `..` 段 | `"/a/../b"` | `"/b"` | 视实现而定 |
|
||||
|
||||
---
|
||||
|
||||
## 10.8 `src/utils/__tests__/notebook.test.ts`
|
||||
|
||||
**问题**：`mapNotebookCellsToToolResult` 内容检查用 `toContain`，未验证 XML 格式。
|
||||
|
||||
### 修改清单
|
||||
|
||||
#### 修复 content 断言
|
||||
|
||||
```typescript
|
||||
// 当前（弱）
|
||||
expect(result).toContain("cell-0");
|
||||
expect(result).toContain("print('hello')");
|
||||
|
||||
// 修复为
|
||||
expect(result).toContain('<cell id="cell-0">');
|
||||
expect(result).toContain("</cell>");
|
||||
```
|
||||
|
||||
#### 新增：parseCellId 边界
|
||||
|
||||
| 用例 | 输入 | 期望 |
|
||||
|------|------|------|
|
||||
| 负数 | `"cell--1"` | `null` |
|
||||
| 前导零 | `"cell-007"` | `7` |
|
||||
| 极大数 | `"cell-999999999"` | `999999999` |
|
||||
|
||||
#### 新增：mapNotebookCellsToToolResult 边界
|
||||
|
||||
| 用例 | 输入 | 期望 |
|
||||
|------|------|------|
|
||||
| 空 data 数组 | `{ cells: [] }` | 空字符串或空结果 |
|
||||
| 无 cell_id | `{ cell_type: "code", source: "x" }` | fallback 到 `cell-${index}` |
|
||||
| error output | `{ output_type: "error", ename: "Error", evalue: "msg" }` | 包含 error 信息 |
|
||||
|
||||
---
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [ ] `bun test` 全部通过
|
||||
- [ ] 8 个文件评分从 WEAK 提升至 ACCEPTABLE 或 GOOD
|
||||
- [ ] `toContain` 仅用于警告文本等确实不确定精确值的场景
|
||||
- [ ] envValidation bug 确认并修复（或确认非 bug 并更新测试）
|
||||
@@ -1,177 +0,0 @@
|
||||
# Plan 11 — 加强 ACCEPTABLE 评分测试
|
||||
|
||||
> 优先级：中 | ~15 个文件 | 预估新增 ~80 个测试用例
|
||||
|
||||
本计划对 ACCEPTABLE 评分文件中的具体缺陷进行定向加强。每个条目只列出需要改动的部分，不做全量重写。
|
||||
|
||||
---
|
||||
|
||||
## 11.1 `src/utils/__tests__/diff.test.ts`
|
||||
|
||||
| 改动 | 当前 | 改为 |
|
||||
|------|------|------|
|
||||
| `getPatchFromContents` 断言 | `hunks.length > 0` | 验证具体 `+`/`-` 行内容 |
|
||||
| `$` 字符转义 | 未测试 | 新增含 `$` 的内容测试 |
|
||||
| `ignoreWhitespace` 选项 | 未测试 | 新增 `ignoreWhitespace: true` 用例 |
|
||||
| 删除全部内容 | 未测试 | `newContent: ""` |
|
||||
| 多 hunk 偏移 | `adjustHunkLineNumbers` 仅单 hunk | 新增多 hunk 同数组测试 |
|
||||
|
||||
---
|
||||
|
||||
## 11.2 `src/utils/__tests__/path.test.ts`
|
||||
|
||||
当前仅覆盖 2/5+ 导出函数。新增：
|
||||
|
||||
| 函数 | 最少用例 | 关键边界 |
|
||||
|------|---------|---------|
|
||||
| `expandPath` | 6 | `~/` 展开、绝对路径直通、相对路径、空串、含 null 字节、`~user` 格式 |
|
||||
| `toRelativePath` | 3 | 同级文件、子目录、父目录 |
|
||||
| `sanitizePath` | 3 | 正常路径、含 `..` 段、空串 |
|
||||
|
||||
`containsPathTraversal` 补充：
|
||||
- URL 编码 `%2e%2e%2f`（确认不匹配，记录为非需求）
|
||||
- 混合分隔符 `foo/..\bar`
|
||||
|
||||
`normalizePathForConfigKey` 补充：
|
||||
- 混合分隔符 `foo/bar\baz`
|
||||
- 冗余分隔符 `foo//bar`
|
||||
- Windows 盘符 `C:\foo\bar`
|
||||
|
||||
---
|
||||
|
||||
## 11.3 `src/utils/__tests__/uuid.test.ts`
|
||||
|
||||
| 改动 | 说明 |
|
||||
|------|------|
|
||||
| 大写测试断言强化 | `not.toBeNull()` → 验证标准化输出（小写+连字符格式） |
|
||||
| 新增 `createAgentId` | 3 用例：无 label / 有 label / 输出格式正则 `/^a[a-z]*-[a-f0-9]{16}$/` |
|
||||
| 前后空白 | `" 550e8400-... "` 期望 `null` |
|
||||
|
||||
---
|
||||
|
||||
## 11.4 `src/utils/__tests__/semver.test.ts`
|
||||
|
||||
| 用例 | 输入 | 期望 |
|
||||
|------|------|------|
|
||||
| pre-release 比较 | `gt("1.0.0", "1.0.0-alpha")` | `true` |
|
||||
| pre-release 间比较 | `order("1.0.0-alpha", "1.0.0-beta")` | `-1` |
|
||||
| tilde range | `satisfies("1.2.5", "~1.2.3")` | `true` |
|
||||
| `*` 通配符 | `satisfies("2.0.0", "*")` | `true` |
|
||||
| 畸形版本 | `order("abc", "1.0.0")` | 确认不抛错 |
|
||||
| `0.0.0` | `gt("0.0.0", "0.0.0")` | `false` |
|
||||
|
||||
---
|
||||
|
||||
## 11.5 `src/utils/__tests__/hash.test.ts`
|
||||
|
||||
| 改动 | 当前 | 改为 |
|
||||
|------|------|------|
|
||||
| djb2 32 位检查 | `hash \| 0`（恒 true） | `Number.isSafeInteger(hash) && Math.abs(hash) <= 0x7FFFFFFF` |
|
||||
| hashContent 空串 | 未测试 | 新增 |
|
||||
| hashContent 格式 | 未验证输出为数字串 | `toMatch(/^\d+$/)` |
|
||||
| hashPair 空串 | 未测试 | `hashPair("", "b")`, `hashPair("", "")` |
|
||||
| 已知答案 | 无 | 断言 `djb2Hash("hello")` 为特定值（需先在控制台运行一次确定） |
|
||||
|
||||
---
|
||||
|
||||
## 11.6 `src/utils/__tests__/claudemd.test.ts`
|
||||
|
||||
当前仅覆盖 3 个辅助函数。新增：
|
||||
|
||||
| 用例 | 函数 | 说明 |
|
||||
|------|------|------|
|
||||
| 未闭合注释 | `stripHtmlComments` | `"<!-- no close some text"` → 原样返回 |
|
||||
| 跨行注释 | `stripHtmlComments` | `"<!--\nmulti\nline\n-->text"` → `"text"` |
|
||||
| 同行注释+内容 | `stripHtmlComments` | `"<!-- note -->some text"` → `"some text"` |
|
||||
| 内联代码中的注释 | `stripHtmlComments` | `` `<!-- kept -->` `` → 保留 |
|
||||
| 大小写不敏感 | `isMemoryFilePath` | `"claude.md"`, `"CLAUDE.MD"` |
|
||||
| 非 .md 规则文件 | `isMemoryFilePath` | `.claude/rules/foo.txt` → `false` |
|
||||
| 空数组 | `getLargeMemoryFiles` | `[]` → `[]` |
|
||||
|
||||
---
|
||||
|
||||
## 11.7 `src/tools/FileEditTool/__tests__/utils.test.ts`
|
||||
|
||||
| 函数 | 新增用例 |
|
||||
|------|---------|
|
||||
| `normalizeQuotes` | 混合引号 `"`she said 'hello'"` |
|
||||
| `stripTrailingWhitespace` | CR-only `\r`、无尾部换行、全空白串 |
|
||||
| `findActualString` | 空 content、Unicode content |
|
||||
| `preserveQuoteStyle` | 单引号、缩写中的撇号（如 `it's`）、空串 |
|
||||
| `applyEditToFile` | `replaceAll=true` 零匹配、`oldString` 无尾部 `\n`、多行内容 |
|
||||
|
||||
---
|
||||
|
||||
## 11.8 `src/utils/model/__tests__/providers.test.ts`
|
||||
|
||||
| 改动 | 说明 |
|
||||
|------|------|
|
||||
| 删除 `originalEnv` | 未使用，消除死代码 |
|
||||
| env 恢复改为快照 | `beforeEach` 保存 `process.env`，`afterEach` 恢复 |
|
||||
| 新增三变量同时设置 | bedrock + vertex + foundry 全部为 `"1"`，验证优先级 |
|
||||
| 新增非 `"1"` 值 | `"true"`, `"0"`, `""` |
|
||||
| `isFirstPartyAnthropicBaseUrl` | URL 含路径 `/v1`、含尾斜杠、非 HTTPS |
|
||||
|
||||
---
|
||||
|
||||
## 11.9 `src/utils/__tests__/hyperlink.test.ts`
|
||||
|
||||
| 用例 | 说明 |
|
||||
|------|------|
|
||||
| 空 URL | `createHyperlink("http://x.com", "", { supported: true })` 不抛错 |
|
||||
| undefined supportsHyperlinks | 选项未传时走默认检测 |
|
||||
| 非 ant staging URL | `USER_TYPE !== "ant"` 时 staging 返回 `false` |
|
||||
|
||||
---
|
||||
|
||||
## 11.10 `src/utils/__tests__/objectGroupBy.test.ts`
|
||||
|
||||
| 用例 | 说明 |
|
||||
|------|------|
|
||||
| key 返回 undefined | `(_, i) => undefined` → 全部归入 `undefined` 组 |
|
||||
| key 为特殊字符 | `({ name }) => name` 含空格/中文 |
|
||||
|
||||
---
|
||||
|
||||
## 11.11 `src/utils/__tests__/CircularBuffer.test.ts`
|
||||
|
||||
| 用例 | 说明 |
|
||||
|------|------|
|
||||
| capacity=1 | 添加 2 个元素，仅保留最后一个 |
|
||||
| 空 buffer 调用 getRecent | 返回空数组 |
|
||||
| getRecent(0) | 返回空数组 |
|
||||
|
||||
---
|
||||
|
||||
## 11.12 `src/utils/__tests__/contentArray.test.ts`
|
||||
|
||||
| 用例 | 说明 |
|
||||
|------|------|
|
||||
| 混合交替 | `[tool_result, text, tool_result]` — 验证插入到正确位置 |
|
||||
|
||||
---
|
||||
|
||||
## 11.13 `src/utils/__tests__/argumentSubstitution.test.ts`
|
||||
|
||||
| 用例 | 说明 |
|
||||
|------|------|
|
||||
| 转义引号 | `"he said \"hello\""` |
|
||||
| 越界索引 | `$ARGUMENTS[99]`（参数不够时） |
|
||||
| 多占位符 | `"cmd $0 $1 $0"` |
|
||||
|
||||
---
|
||||
|
||||
## 11.14 `src/utils/__tests__/messages.test.ts`
|
||||
|
||||
| 改动 | 说明 |
|
||||
|------|------|
|
||||
| `normalizeMessages` 断言加强 | 验证拆分后的消息内容，不只是长度 |
|
||||
| `isNotEmptyMessage` 空白 | `[{ type: "text", text: " " }]` |
|
||||
|
||||
---
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [ ] `bun test` 全部通过
|
||||
- [ ] 目标文件评分从 ACCEPTABLE 提升至 GOOD
|
||||
- [ ] 无 `toContain` 用于精确值检查的场景
|
||||
@@ -1,145 +0,0 @@
|
||||
# Plan 12 — Mock 可靠性修复
|
||||
|
||||
> 优先级：高 | 影响 4 个测试文件 | 预估修改 ~15 处
|
||||
|
||||
本计划修复测试中 mock 相关的副作用、状态泄漏和虚假测试。
|
||||
|
||||
---
|
||||
|
||||
## 12.1 `gitOperationTracking.test.ts` — 消除分析副作用
|
||||
|
||||
**当前问题**：`detectGitOperation` 内部调用 `logEvent()`、`getCommitCounter().increment()`、`getPrCounter().increment()`，每次测试运行都触发真实分析代码。
|
||||
|
||||
**修复步骤**：
|
||||
|
||||
1. 读取 `src/tools/shared/gitOperationTracking.ts`，确认 analytics 导入路径
|
||||
2. 在测试文件顶部添加 `mock.module`：
|
||||
|
||||
```typescript
|
||||
import { mock } from "bun:test";
|
||||
|
||||
mock.module("src/services/analytics/index.ts", () => ({
|
||||
logEvent: mock(() => {}),
|
||||
// 按需补充其他导出
|
||||
}));
|
||||
```
|
||||
|
||||
3. 如果 `getCommitCounter` / `getPrCounter` 来自 `src/bootstrap/state.ts`：
|
||||
|
||||
```typescript
|
||||
mock.module("src/bootstrap/state.ts", () => ({
|
||||
getCommitCounter: mock(() => ({ increment: mock(() => {}) })),
|
||||
getPrCounter: mock(() => ({ increment: mock(() => {}) })),
|
||||
// 保留其他被测函数实际需要的导出
|
||||
}));
|
||||
```
|
||||
|
||||
4. 使用 `await import()` 模式加载被测模块
|
||||
5. 运行测试验证无副作用
|
||||
|
||||
**风险**：`mock.module` 会替换整个模块。如果 `detectGitOperation` 还需要其他来自这些模块的导出，需在 mock 工厂中提供。
|
||||
|
||||
---
|
||||
|
||||
## 12.2 `PermissionMode.test.ts` — 修复 `isExternalPermissionMode` 虚假测试
|
||||
|
||||
**当前问题**：`isExternalPermissionMode` 依赖 `process.env.USER_TYPE`。非 ant 环境下所有 mode 都返回 true，测试从未覆盖 false 分支。
|
||||
|
||||
**修复步骤**：
|
||||
|
||||
1. 新增 ant 环境测试组（见 Plan 10.3 详细用例）
|
||||
2. 使用 `beforeEach`/`afterEach` 管理 `process.env.USER_TYPE`
|
||||
|
||||
```typescript
|
||||
describe("when USER_TYPE is 'ant'", () => {
|
||||
const originalUserType = process.env.USER_TYPE;
|
||||
beforeEach(() => { process.env.USER_TYPE = "ant"; });
|
||||
afterEach(() => {
|
||||
if (originalUserType !== undefined) {
|
||||
process.env.USER_TYPE = originalUserType;
|
||||
} else {
|
||||
delete process.env.USER_TYPE;
|
||||
}
|
||||
});
|
||||
|
||||
test("returns false for 'auto'", () => {
|
||||
expect(isExternalPermissionMode("auto")).toBe(false);
|
||||
});
|
||||
test("returns false for 'bubble'", () => {
|
||||
expect(isExternalPermissionMode("bubble")).toBe(false);
|
||||
});
|
||||
test("returns true for 'plan'", () => {
|
||||
expect(isExternalPermissionMode("plan")).toBe(true);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
3. 验证新增测试确实执行 false 路径
|
||||
|
||||
---
|
||||
|
||||
## 12.3 `providers.test.ts` — 环境变量快照恢复
|
||||
|
||||
**当前问题**：
|
||||
- `originalEnv` 声明后未使用
|
||||
- `afterEach` 仅删除已知 3 个 key，如果源码新增 env var，测试间状态泄漏
|
||||
|
||||
**修复步骤**：
|
||||
|
||||
```typescript
|
||||
let savedEnv: Record<string, string | undefined>;
|
||||
|
||||
beforeEach(() => {
|
||||
savedEnv = {};
|
||||
for (const key of Object.keys(process.env)) {
|
||||
savedEnv[key] = process.env[key];
|
||||
}
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
// 删除所有当前 env，恢复快照
|
||||
for (const key of Object.keys(process.env)) {
|
||||
delete process.env[key];
|
||||
}
|
||||
for (const [key, value] of Object.entries(savedEnv)) {
|
||||
if (value !== undefined) {
|
||||
process.env[key] = value;
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
> 简化方案：只保存/恢复相关 key 列表 `["CLAUDE_CODE_USE_BEDROCK", "CLAUDE_CODE_USE_VERTEX", "CLAUDE_CODE_USE_FOUNDRY", "ANTHROPIC_BASE_URL", "USER_TYPE"]`，但需注释说明新增 env var 时需同步更新。
|
||||
|
||||
---
|
||||
|
||||
## 12.4 `envUtils.test.ts` — 验证环境变量恢复完整性
|
||||
|
||||
**当前状态**：已有 `afterEach` 恢复。需审查：
|
||||
|
||||
1. 确认所有 `describe` 块中的 `afterEach` 都完整恢复了修改的 env var
|
||||
2. 确认 `process.argv` 修改也被恢复（`getClaudeConfigHomeDir` 测试修改了 argv）
|
||||
3. 新增：`afterEach` 中断言无意外 env 泄漏（可选，CI-only）
|
||||
|
||||
---
|
||||
|
||||
## 12.5 `sleep.test.ts` / `memoize.test.ts` — 时间敏感测试加固
|
||||
|
||||
**当前状态**：已有合理 margin。可选加固：
|
||||
|
||||
| 文件 | 用例 | 当前 | 加固 |
|
||||
|------|------|------|------|
|
||||
| `sleep.test.ts` | `resolves after timeout` | `sleep(50)`, check `>= 40ms` | 增大 margin：`sleep(50)`, check `>= 30ms` |
|
||||
| `memoize.test.ts` | stale serve & refresh | TTL=1ms, wait 10ms | 增大 margin：TTL=5ms, wait 50ms |
|
||||
|
||||
> 仅在 CI 出现 flaky 时执行此加固。
|
||||
|
||||
---
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [ ] `gitOperationTracking.test.ts` 无分析副作用（可通过在 mock 中增加 `expect(logEvent).toHaveBeenCalledTimes(N)` 验证）
|
||||
- [ ] `PermissionMode.test.ts` 的 `isExternalPermissionMode` 覆盖 true + false 分支
|
||||
- [ ] `providers.test.ts` 的 `originalEnv` 死代码已删除
|
||||
- [ ] 所有修改 env 的测试文件恢复完整
|
||||
- [ ] `bun test` 全部通过
|
||||
@@ -1,71 +0,0 @@
|
||||
# Plan 13 — truncate CJK/Emoji 补充测试
|
||||
|
||||
> 优先级：中 | 1 个文件 | 预估新增 ~15 个测试用例
|
||||
|
||||
`truncate.ts` 使用 `stringWidth` 和 grapheme segmentation 实现宽度感知截断，但现有测试仅覆盖 ASCII。这是核心场景缺失。
|
||||
|
||||
---
|
||||
|
||||
## 被测函数
|
||||
|
||||
- `truncateToWidth(text, maxWidth)` — 尾部截断加 `…`
|
||||
- `truncateStartToWidth(text, maxWidth)` — 头部截断加 `…`
|
||||
- `truncateToWidthNoEllipsis(text, maxWidth)` — 尾部截断无省略号
|
||||
- `truncatePathMiddle(path, maxLength)` — 路径中间截断
|
||||
- `wrapText(text, maxWidth)` — 按宽度换行
|
||||
|
||||
---
|
||||
|
||||
## 新增用例
|
||||
|
||||
### CJK 全角字符
|
||||
|
||||
| 用例 | 函数 | 输入 | maxWidth | 期望行为 |
|
||||
|------|------|------|----------|----------|
|
||||
| 纯中文截断 | `truncateToWidth` | `"你好世界"` | 4 | `"你好…"` (每个中文字占 2 宽度) |
|
||||
| 中英混合 | `truncateToWidth` | `"hello你好"` | 8 | `"hello你…"` |
|
||||
| 全角不截断 | `truncateToWidth` | `"你好"` | 4 | `"你好"` (恰好 4) |
|
||||
| emoji 单字符 | `truncateToWidth` | `"👋"` | 2 | `"👋"` (emoji 通常 2 宽度) |
|
||||
| emoji 截断 | `truncateToWidth` | `"hello 👋 world"` | 8 | 确认宽度计算正确 |
|
||||
| 头部中文 | `truncateStartToWidth` | `"你好世界"` | 4 | `"…界"` |
|
||||
| 无省略中文 | `truncateToWidthNoEllipsis` | `"你好世界"` | 4 | `"你好"` |
|
||||
|
||||
> **注意**：`stringWidth` 对 CJK/emoji 的宽度计算取决于具体实现。先在 REPL 中运行确认实际宽度再写断言：
|
||||
> ```typescript
|
||||
> import { stringWidth } from "src/utils/truncate.ts";
|
||||
> console.log(stringWidth("你好")); // 确认是 4 还是 2
|
||||
> console.log(stringWidth("👋")); // 确认 emoji 宽度
|
||||
> ```
|
||||
|
||||
### 路径中间截断补充
|
||||
|
||||
| 用例 | 输入 | maxLength | 期望 |
|
||||
|------|------|-----------|------|
|
||||
| 文件名超长 | `"/very/long/path/to/MyComponent.tsx"` | 10 | 含 `…` 且以 `.tsx` 结尾 |
|
||||
| 无斜杠短串 | `"abc"` | 1 | 确认行为不抛错 |
|
||||
| maxLength 极小 | `"/a/b"` | 1 | 确认不抛错 |
|
||||
| maxLength=4 | `"/a/b/c.ts"` | 4 | 确认行为 |
|
||||
|
||||
### wrapText 补充
|
||||
|
||||
| 用例 | 输入 | maxWidth | 期望 |
|
||||
|------|------|----------|------|
|
||||
| 含换行符 | `"hello\nworld"` | 10 | 保留原有换行 |
|
||||
| 宽度=0 | `"hello"` | 0 | 空串或原串（确认不抛错） |
|
||||
|
||||
---
|
||||
|
||||
## 实施步骤
|
||||
|
||||
1. 在 REPL 中确认 `stringWidth` 对 CJK/emoji 的实际返回值
|
||||
2. 按实际值编写精确断言
|
||||
3. 如果 `stringWidth` 依赖 ICU 或平台特性，添加平台检查（`process.platform !== "win32"` 跳过条件）
|
||||
4. 运行测试
|
||||
|
||||
---
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [ ] 至少 5 个 CJK/emoji 相关测试通过
|
||||
- [ ] 断言基于实际 `stringWidth` 返回值，非猜测
|
||||
- [ ] `bun test` 全部通过
|
||||
@@ -1,191 +0,0 @@
|
||||
# Plan 14 — 集成测试搭建
|
||||
|
||||
> 优先级：中 | 新建 ~3 个测试文件 | 预估 ~30 个测试用例
|
||||
|
||||
当前 `tests/integration/` 目录为空，spec 设计的三个集成测试均未创建。本计划搭建 mock 基础设施并实现核心集成测试。
|
||||
|
||||
---
|
||||
|
||||
## 14.1 搭建 `tests/mocks/` 基础设施
|
||||
|
||||
### 文件结构
|
||||
|
||||
```
|
||||
tests/
|
||||
├── mocks/
|
||||
│ ├── api-responses.ts # Claude API mock 响应
|
||||
│ ├── file-system.ts # 临时文件系统工具
|
||||
│ └── fixtures/
|
||||
│ ├── sample-claudemd.md # CLAUDE.md 样本
|
||||
│ └── sample-messages.json # 消息样本
|
||||
├── integration/
|
||||
│ ├── tool-chain.test.ts
|
||||
│ ├── context-build.test.ts
|
||||
│ └── message-pipeline.test.ts
|
||||
└── helpers/
|
||||
└── setup.ts # 共享 beforeAll/afterAll
|
||||
```
|
||||
|
||||
### `tests/mocks/file-system.ts`
|
||||
|
||||
```typescript
|
||||
import { mkdtemp, rm, writeFile, mkdir } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
|
||||
export async function createTempDir(prefix = "claude-test-"): Promise<string> {
|
||||
const dir = await mkdtemp(join(tmpdir(), prefix));
|
||||
return dir;
|
||||
}
|
||||
|
||||
export async function cleanupTempDir(dir: string): Promise<void> {
|
||||
await rm(dir, { recursive: true, force: true });
|
||||
}
|
||||
|
||||
export async function writeTempFile(dir: string, name: string, content: string): Promise<string> {
|
||||
const path = join(dir, name);
|
||||
await writeFile(path, content, "utf-8");
|
||||
return path;
|
||||
}
|
||||
```
|
||||
|
||||
### `tests/mocks/fixtures/sample-claudemd.md`
|
||||
|
||||
```markdown
|
||||
# Project Instructions
|
||||
|
||||
This is a sample CLAUDE.md file for testing.
|
||||
```
|
||||
|
||||
### `tests/mocks/api-responses.ts`
|
||||
|
||||
```typescript
|
||||
export const mockStreamResponse = {
|
||||
type: "message_start" as const,
|
||||
message: {
|
||||
id: "msg_mock_001",
|
||||
type: "message" as const,
|
||||
role: "assistant",
|
||||
content: [],
|
||||
model: "claude-sonnet-4-20250514",
|
||||
stop_reason: null,
|
||||
stop_sequence: null,
|
||||
usage: { input_tokens: 100, output_tokens: 0 },
|
||||
},
|
||||
};
|
||||
|
||||
export const mockTextBlock = {
|
||||
type: "content_block_start" as const,
|
||||
index: 0,
|
||||
content_block: { type: "text" as const, text: "Mock response" },
|
||||
};
|
||||
|
||||
export const mockToolUseBlock = {
|
||||
type: "content_block_start" as const,
|
||||
index: 1,
|
||||
content_block: {
|
||||
type: "tool_use" as const,
|
||||
id: "toolu_mock_001",
|
||||
name: "Read",
|
||||
input: { file_path: "/tmp/test.txt" },
|
||||
},
|
||||
};
|
||||
|
||||
export const mockEndEvent = {
|
||||
type: "message_stop" as const,
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 14.2 `tests/integration/tool-chain.test.ts`
|
||||
|
||||
**目标**：验证 Tool 注册 → 发现 → 权限检查链路。
|
||||
|
||||
### 前置条件
|
||||
|
||||
`src/tools.ts` 的 `getAllBaseTools` / `getTools` 导入链过重。策略：
|
||||
- 尝试直接 import 并 mock 最重依赖
|
||||
- 若不可行，改为测试 `src/Tool.ts` 的 `findToolByName` + 手动构造 tool 列表
|
||||
|
||||
### 用例
|
||||
|
||||
| # | 用例 | 验证点 |
|
||||
|---|------|--------|
|
||||
| 1 | `findToolByName("Bash")` 在已注册列表中查找 | 返回正确的 tool 定义 |
|
||||
| 2 | `findToolByName("NonExistent")` | 返回 `undefined` |
|
||||
| 3 | `findToolByName` 大小写不敏感 | `"bash"` 也能找到 |
|
||||
| 4 | `filterToolsByDenyRules` 拒绝特定工具 | 被拒绝工具不在结果中 |
|
||||
| 5 | `parseToolPreset("default")` 返回已知列表 | 包含核心 tools |
|
||||
| 6 | `buildTool` 构建的 tool 可被 `findToolByName` 发现 | 端到端验证 |
|
||||
|
||||
> 如果 `getAllBaseTools` 确实不可导入，改用 mock tool list 替代。
|
||||
|
||||
---
|
||||
|
||||
## 14.3 `tests/integration/context-build.test.ts`
|
||||
|
||||
**目标**：验证系统提示组装流程（CLAUDE.md 加载 + git status + 日期注入）。
|
||||
|
||||
### 前置条件
|
||||
|
||||
`src/context.ts` 依赖链极重。策略：
|
||||
- Mock `src/bootstrap/state.ts`（提供 cwd、projectRoot）
|
||||
- Mock `src/utils/git.ts`（提供 git status）
|
||||
- 使用真实 `src/utils/claudemd.ts` + 临时文件
|
||||
|
||||
### 用例
|
||||
|
||||
| # | 用例 | 验证点 |
|
||||
|---|------|--------|
|
||||
| 1 | 基本 context 构建 | 返回值包含系统提示字符串 |
|
||||
| 2 | CLAUDE.md 内容出现在 context 中 | `stripHtmlComments` 后的内容被包含 |
|
||||
| 3 | 多层目录 CLAUDE.md 合并 | 父目录 + 子目录 CLAUDE.md 都被加载 |
|
||||
| 4 | 无 CLAUDE.md 时不报错 | context 正常返回，无 crash |
|
||||
| 5 | git status 为 null | context 正常构建（测试环境中 git 不可用时） |
|
||||
|
||||
> **风险评估**：如果 mock `context.ts` 的依赖链成本过高，退化为测试 `buildEffectiveSystemPrompt`（已在 systemPrompt.test.ts 中完成），记录为已知限制。
|
||||
|
||||
---
|
||||
|
||||
## 14.4 `tests/integration/message-pipeline.test.ts`
|
||||
|
||||
**目标**：验证用户输入 → 消息格式化 → API 请求构建。
|
||||
|
||||
### 前置条件
|
||||
|
||||
`src/services/api/claude.ts` 构建最终 API 请求。策略：
|
||||
- Mock Anthropic SDK 的 streaming endpoint
|
||||
- 验证请求参数结构
|
||||
|
||||
### 用例
|
||||
|
||||
| # | 用例 | 验证点 |
|
||||
|---|------|--------|
|
||||
| 1 | 文本消息格式化 | `createUserMessage` 生成正确 role+content |
|
||||
| 2 | tool_result 消息格式化 | 包含 tool_use_id 和 content |
|
||||
| 3 | 多轮消息序列化 | messages 数组保持顺序 |
|
||||
| 4 | 系统提示注入到请求 | API 请求的 system 字段非空 |
|
||||
| 5 | 消息 normalize 后格式一致 | `normalizeMessages` 输出结构正确 |
|
||||
|
||||
> **现实评估**：消息格式化的大部分已在 `messages.test.ts` 覆盖。API 请求构建需要 mock SDK，复杂度高。如果投入产出比低，仅实现用例 1-3 和 5，用例 4 标记为 stretch goal。
|
||||
|
||||
---
|
||||
|
||||
## 实施步骤
|
||||
|
||||
1. 创建 `tests/mocks/` 目录和基础文件
|
||||
2. 实现 `tool-chain.test.ts`（最低风险，最高价值）
|
||||
3. 评估 `context-build.test.ts` 可行性，决定是否实施
|
||||
4. 实现 `message-pipeline.test.ts`（可降级为单元测试）
|
||||
5. 更新 `testing-spec.md` 状态
|
||||
|
||||
---
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [ ] `tests/mocks/` 基础设施可用
|
||||
- [ ] 至少 `tool-chain.test.ts` 实现并通过
|
||||
- [ ] 集成测试独立于单元测试运行：`bun test tests/integration/`
|
||||
- [ ] 所有集成测试使用 `createTempDir` + `cleanupTempDir`，不留文件系统残留
|
||||
- [ ] `bun test` 全部通过
|
||||
@@ -1,67 +0,0 @@
|
||||
# Plan 15 — CLI 参数测试 + 覆盖率基线
|
||||
|
||||
> 优先级：低 | 预估 ~15 个测试用例
|
||||
|
||||
---
|
||||
|
||||
## 15.1 `src/main.tsx` CLI 参数测试
|
||||
|
||||
**目标**：覆盖 Commander.js 配置的参数解析和模式切换。
|
||||
|
||||
### 前置条件
|
||||
|
||||
`src/main.tsx` 的 Commander 实例通常在模块顶层创建。测试策略：
|
||||
- 直接构造 Commander 实例或 mock `main.tsx` 的 program 导出
|
||||
- 使用 `parseArgs` 而非 `parse`（不触发 `process.exit`）
|
||||
|
||||
### 用例
|
||||
|
||||
| # | 用例 | 输入 | 期望 |
|
||||
|---|------|------|------|
|
||||
| 1 | 默认模式 | `[]` | 模式为 REPL |
|
||||
| 2 | pipe 模式 | `["-p"]` | 模式为 pipe |
|
||||
| 3 | pipe 带输入 | `["-p", "say hello"]` | 输入为 `"say hello"` |
|
||||
| 4 | print 模式 | `["--print", "hello"]` | 等效于 pipe |
|
||||
| 5 | verbose | `["-v"]` | verbose 标志为 true |
|
||||
| 6 | model 选择 | `["--model", "claude-opus-4-6"]` | model 值正确传递 |
|
||||
| 7 | system prompt | `["--system-prompt", "custom"]` | system prompt 被设置 |
|
||||
| 8 | help | `["--help"]` | 显示帮助信息，不报错 |
|
||||
| 9 | version | `["--version"]` | 显示版本号 |
|
||||
| 10 | unknown flag | `["--nonexistent"]` | 不报错（Commander 允许未知参数时） |
|
||||
|
||||
> **风险**：`main.tsx` 可能执行初始化逻辑（auth、analytics），需要在 mock 环境中运行。如果复杂度过高，降级为只测试参数解析部分。
|
||||
|
||||
---
|
||||
|
||||
## 15.2 覆盖率基线
|
||||
|
||||
### 运行命令
|
||||
|
||||
```bash
|
||||
bun test --coverage 2>&1 | tail -50
|
||||
```
|
||||
|
||||
### 记录内容
|
||||
|
||||
| 模块 | 当前覆盖率 | 目标 |
|
||||
|------|-----------|------|
|
||||
| `src/utils/` | 待测量 | >= 80% |
|
||||
| `src/utils/permissions/` | 待测量 | >= 60% |
|
||||
| `src/utils/model/` | 待测量 | >= 60% |
|
||||
| `src/Tool.ts` + `src/tools.ts` | 待测量 | >= 80% |
|
||||
| `src/utils/claudemd.ts` | 待测量 | >= 40%（核心逻辑难测） |
|
||||
| 整体 | 待测量 | 不设强制指标 |
|
||||
|
||||
### 后续行动
|
||||
|
||||
- 将基线数据填入 `testing-spec.md` §4
|
||||
- 识别覆盖率最低的 10 个文件，排入后续测试计划
|
||||
- 如 `bun test --coverage` 输出不可用（Bun 版本限制），改用手动计算已测/总导出函数比
|
||||
|
||||
---
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [ ] CLI 参数至少覆盖 5 个核心 flag
|
||||
- [ ] 覆盖率基线数据记录到 testing-spec.md
|
||||
- [ ] `bun test` 全部通过
|
||||
@@ -1,188 +0,0 @@
|
||||
# Phase 16 — 零依赖纯函数测试
|
||||
|
||||
> 创建日期：2026-04-02
|
||||
> 预计：+120 tests / 8 files
|
||||
> 目标：覆盖所有零外部依赖的纯函数/类模块
|
||||
|
||||
所有模块均为纯函数或零外部依赖类，mock 成本为零，ROI 最高。
|
||||
|
||||
---
|
||||
|
||||
## 16.1 `src/utils/__tests__/stream.test.ts`（~15 tests）
|
||||
|
||||
**目标模块**: `src/utils/stream.ts`（76 行）
|
||||
**导出**: `Stream<T>` class — 手动异步队列，实现 `AsyncIterator<T>`
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| enqueue then read | 单条消息正确传递 |
|
||||
| enqueue multiple then drain | 多条消息顺序消费 |
|
||||
| done resolves pending readers | `done()` 后迭代结束 |
|
||||
| done with no pending readers | 无等待时安全关闭 |
|
||||
| error rejects pending readers | `error(e)` 传播异常 |
|
||||
| error after done | 后续操作安全处理 |
|
||||
| single-iteration guard | `return()` 后不可再迭代 |
|
||||
| empty stream done immediately | 无数据时 done 返回 `{ done: true }` |
|
||||
| concurrent enqueue | 多次 enqueue 不丢失 |
|
||||
| backpressure | reader 慢于 writer 时不丢数据 |
|
||||
|
||||
---
|
||||
|
||||
## 16.2 `src/utils/__tests__/abortController.test.ts`（~12 tests）
|
||||
|
||||
**目标模块**: `src/utils/abortController.ts`（99 行）
|
||||
**导出**: `createAbortController()`, `createChildAbortController()`
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| parent abort propagates to child | `parent.abort()` → child aborted |
|
||||
| child abort does NOT propagate to parent | `child.abort()` → parent still active |
|
||||
| already-aborted parent → child immediately aborted | 创建时即继承 abort 状态 |
|
||||
| child listener cleanup after parent abort | WeakRef 回收后无泄漏 |
|
||||
| multiple children of same parent | 独立 abort 传播 |
|
||||
| child abort then parent abort | 顺序无关 |
|
||||
| signal.maxListeners raised | MaxListenersExceededWarning 不触发 |
|
||||
|
||||
---
|
||||
|
||||
## 16.3 `src/utils/__tests__/bufferedWriter.test.ts`（~14 tests）
|
||||
|
||||
**目标模块**: `src/utils/bufferedWriter.ts`（100 行）
|
||||
**导出**: `createBufferedWriter()`
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| single write buffered | write → buffer 累积 |
|
||||
| flush on size threshold | 超过 maxSize 时自动 flush |
|
||||
| flush on timer | 定时器触发 flush |
|
||||
| immediate mode | `{ immediate: true }` 跳过缓冲 |
|
||||
| overflow coalescing | overflow 内容合并到下次 flush |
|
||||
| empty buffer flush | 无数据时 flush 无副作用 |
|
||||
| close flushes remaining | close 触发最终 flush |
|
||||
| multiple writes before flush | 批量写入合并 |
|
||||
| flush callback receives concatenated data | writeFn 参数正确 |
|
||||
|
||||
**Mock**: 注入 `writeFn` 回调，可选 fake timers
|
||||
|
||||
---
|
||||
|
||||
## 16.4 `src/utils/__tests__/gitDiff.test.ts`（~20 tests）
|
||||
|
||||
**目标模块**: `src/utils/gitDiff.ts`（532 行）
|
||||
**可测函数**: `parseGitNumstat()`, `parseGitDiff()`, `parseShortstat()`
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| parseGitNumstat — single file | `1\t2\tpath` → { added: 1, deleted: 2, file: "path" } |
|
||||
| parseGitNumstat — binary file | `-\t-\timage.png` → binary flag |
|
||||
| parseGitNumstat — rename | `{ old => new }` 格式解析 |
|
||||
| parseGitNumstat — empty diff | 空字符串 → [] |
|
||||
| parseGitNumstat — multiple files | 多行正确分割 |
|
||||
| parseGitDiff — added lines | `+` 开头行计数 |
|
||||
| parseGitDiff — deleted lines | `-` 开头行计数 |
|
||||
| parseGitDiff — hunk header | `@@ -a,b +c,d @@` 解析 |
|
||||
| parseGitDiff — new file mode | `new file mode 100644` 检测 |
|
||||
| parseGitDiff — deleted file mode | `deleted file mode` 检测 |
|
||||
| parseGitDiff — binary diff | Binary files differ 处理 |
|
||||
| parseShortstat — all components | `1 file changed, 5 insertions(+), 3 deletions(-)` |
|
||||
| parseShortstat — insertions only | 无 deletions |
|
||||
| parseShortstat — deletions only | 无 insertions |
|
||||
| parseShortstat — files only | 仅 file changed |
|
||||
| parseShortstat — empty | 空字符串 → 默认值 |
|
||||
| parseShortstat — rename | `1 file changed, ...` 重命名 |
|
||||
|
||||
**Mock**: 无需 mock — 全部是纯字符串解析
|
||||
|
||||
---
|
||||
|
||||
## 16.5 `src/__tests__/history.test.ts`（~18 tests）
|
||||
|
||||
**目标模块**: `src/history.ts`（464 行）
|
||||
**可测函数**: `parseReferences()`, `expandPastedTextRefs()`, `formatPastedTextRef()`, `formatImageRef()`, `getPastedTextRefNumLines()`
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| parseReferences — text ref | `#1` → [{ type: "text", ref: 1 }] |
|
||||
| parseReferences — image ref | `@1` → [{ type: "image", ref: 1 }] |
|
||||
| parseReferences — multiple refs | `#1 #2 @3` → 3 refs |
|
||||
| parseReferences — no refs | `"hello"` → [] |
|
||||
| parseReferences — duplicate refs | `#1 #1` → 去重或保留 |
|
||||
| parseReferences — zero ref | `#0` → 边界 |
|
||||
| parseReferences — large ref | `#999` → 正常 |
|
||||
| formatPastedTextRef — basic | 输出格式验证 |
|
||||
| formatPastedTextRef — multiline | 多行内容格式 |
|
||||
| getPastedTextRefNumLines — 1 line | 返回 1 |
|
||||
| getPastedTextRefNumLines — multiple lines | 换行计数 |
|
||||
| expandPastedTextRefs — single ref | 替换单个引用 |
|
||||
| expandPastedTextRefs — multiple refs | 替换多个引用 |
|
||||
| expandPastedTextRefs — no refs | 原样返回 |
|
||||
| expandPastedTextRefs — mixed content | 文本 + 引用混合 |
|
||||
| formatImageRef — basic | 输出格式 |
|
||||
|
||||
**Mock**: `mock.module("src/bootstrap/state.ts", ...)` 解锁模块
|
||||
|
||||
---
|
||||
|
||||
## 16.6 `src/utils/__tests__/sliceAnsi.test.ts`（~16 tests）
|
||||
|
||||
**目标模块**: `src/utils/sliceAnsi.ts`（91 行）
|
||||
**导出**: `sliceAnsi()` — ANSI 感知的字符串切片
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| plain text slice | `"hello".slice(1,3)` 等价 |
|
||||
| preserve ANSI codes | `\x1b[31mhello\x1b[0m` 切片后保留颜色 |
|
||||
| close opened styles | 切片点在 ANSI 样式中间时正确关闭 |
|
||||
| hyperlink handling | OSC 8 超链接不被切断 |
|
||||
| combining marks (diacritics) | `é` = `e\u0301` 不被切开 |
|
||||
| Devanagari matras | 零宽字符不被切断 |
|
||||
| full-width characters | CJK 字符宽度 = 2 |
|
||||
| empty slice | 返回空字符串 |
|
||||
| full slice | 返回完整字符串 |
|
||||
| boundary at ANSI code | 边界恰好在 escape 序列上 |
|
||||
| nested ANSI styles | 多层嵌套时正确处理 |
|
||||
| slice start > end | 空结果 |
|
||||
|
||||
**Mock**: `mock.module("@alcalzone/ansi-tokenize", ...)`, `mock.module("ink/stringWidth", ...)`
|
||||
|
||||
---
|
||||
|
||||
## 16.7 `src/utils/__tests__/treeify.test.ts`（~15 tests）
|
||||
|
||||
**目标模块**: `src/utils/treeify.ts`（170 行）
|
||||
**导出**: `treeify()` — 递归树渲染
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| simple flat tree | `{ a: {}, b: {} }` → 2 行 |
|
||||
| nested tree | `{ a: { b: { c: {} } } }` → 3 行缩进 |
|
||||
| array values | `[1, 2, 3]` 渲染为列表 |
|
||||
| circular reference | 不无限递归 |
|
||||
| empty object | `{}` 处理 |
|
||||
| single key | 布局适配 |
|
||||
| branch vs last-branch character | ├─ vs └─ |
|
||||
| custom prefix | options 前缀传递 |
|
||||
| deep nesting | 5+ 层缩进正确 |
|
||||
| mixed object/array | 混合结构 |
|
||||
|
||||
**Mock**: `mock.module("figures", ...)`, color 模块 mock
|
||||
|
||||
---
|
||||
|
||||
## 16.8 `src/utils/__tests__/words.test.ts`（~10 tests）
|
||||
|
||||
**目标模块**: `src/utils/words.ts`（800 行，大部分是词表数据）
|
||||
**导出**: `generateWordSlug()`, `generateShortWordSlug()`
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| generateWordSlug format | `adjective-verb-noun` 三段式 |
|
||||
| generateShortWordSlug format | `adjective-noun` 两段式 |
|
||||
| all parts non-empty | 无空段 |
|
||||
| hyphen separator | `-` 分隔 |
|
||||
| all parts from word lists | 成分来自预定义词表 |
|
||||
| multiple calls uniqueness | 连续调用不总是相同 |
|
||||
| no consecutive hyphens | 无 `--` |
|
||||
| lowercase only | 全小写 |
|
||||
|
||||
**Mock**: `mock.module("crypto", ...)` 控制 `randomBytes` 实现确定性测试
|
||||
@@ -1,203 +0,0 @@
|
||||
# Phase 17 — Tool 子模块纯逻辑测试
|
||||
|
||||
> 创建日期：2026-04-02
|
||||
> 预计：+150 tests / 11 files
|
||||
> 目标：覆盖 Tool 目录下有丰富纯逻辑但零测试的子模块
|
||||
|
||||
---
|
||||
|
||||
## 17.1 `src/tools/PowerShellTool/__tests__/powershellSecurity.test.ts`（~25 tests）
|
||||
|
||||
**目标模块**: `src/tools/PowerShellTool/powershellSecurity.ts`（1091 行）
|
||||
|
||||
**安全关键** — 检测 ~20 种攻击向量。
|
||||
|
||||
| 测试分组 | 测试数 | 验证点 |
|
||||
|---------|-------|--------|
|
||||
| Invoke-Expression 检测 | 3 | `IEX`, `Invoke-Expression`, 变形 |
|
||||
| Download cradle 检测 | 3 | `Net.WebClient`, `Invoke-WebRequest`, pipe |
|
||||
| Privilege escalation | 3 | `Start-Process -Verb RunAs`, `runas.exe` |
|
||||
| COM object | 2 | `New-Object -ComObject`, WScript.Shell |
|
||||
| Scheduled tasks | 2 | `schtasks`, `Register-ScheduledTask` |
|
||||
| WMI | 2 | `Invoke-WmiMethod`, `Get-WmiObject` |
|
||||
| Module loading | 2 | `Import-Module` 从网络路径 |
|
||||
| 安全命令通过 | 3 | `Get-Process`, `Get-ChildItem`, `Write-Host` |
|
||||
| 混淆绕过尝试 | 3 | base64, 字符串拼接, 空格变形 |
|
||||
| 组合命令 | 2 | `;` 分隔的多命令 |
|
||||
|
||||
**Mock**: 构造 `ParsedPowerShellCommand` 对象（不需要真实 AST）
|
||||
|
||||
---
|
||||
|
||||
## 17.2 `src/tools/PowerShellTool/__tests__/commandSemantics.test.ts`（~10 tests）
|
||||
|
||||
**目标模块**: `src/tools/PowerShellTool/commandSemantics.ts`（143 行）
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| grep exit 0/1/2 | 语义映射 |
|
||||
| robocopy exit codes | Windows 特殊退出码 |
|
||||
| findstr exit codes | Windows find 工具 |
|
||||
| unknown command | 默认语义 |
|
||||
| extractBaseCommand — basic | `grep "pattern" file` → `grep` |
|
||||
| extractBaseCommand — path | `C:\tools\rg.exe` → `rg` |
|
||||
| heuristicallyExtractBaseCommand | 模糊匹配 |
|
||||
|
||||
---
|
||||
|
||||
## 17.3 `src/tools/PowerShellTool/__tests__/destructiveCommandWarning.test.ts`（~15 tests）
|
||||
|
||||
**目标模块**: `src/tools/PowerShellTool/destructiveCommandWarning.ts`（110 行）
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| Remove-Item -Recurse -Force | 危险 |
|
||||
| Format-Volume | 危险 |
|
||||
| git reset --hard | 危险 |
|
||||
| DROP TABLE | 危险 |
|
||||
| Remove-Item (no -Force) | 安全 |
|
||||
| Get-ChildItem | 安全 |
|
||||
| 管道组合 | `rm -rf` + pipe |
|
||||
| 大小写混合 | `ReMoVe-ItEm` |
|
||||
|
||||
---
|
||||
|
||||
## 17.4 `src/tools/PowerShellTool/__tests__/gitSafety.test.ts`（~12 tests）
|
||||
|
||||
**目标模块**: `src/tools/PowerShellTool/gitSafety.ts`（177 行）
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| normalizeGitPathArg — forward slash | 规范化 |
|
||||
| normalizeGitPathArg — backslash | Windows 路径规范化 |
|
||||
| normalizeGitPathArg — NTFS short name | `GITFI~1` → `.git` |
|
||||
| isGitInternalPathPS — .git/config | true |
|
||||
| isGitInternalPathPS — normal file | false |
|
||||
| isDotGitPathPS — hidden git dir | true |
|
||||
| isDotGitPathPS — .gitignore | false |
|
||||
| bare repo attack | `.git` 路径遍历 |
|
||||
|
||||
---
|
||||
|
||||
## 17.5 `src/tools/LSPTool/__tests__/formatters.test.ts`（~20 tests）
|
||||
|
||||
**目标模块**: `src/tools/LSPTool/formatters.ts`（593 行）
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| formatGoToDefinitionResult — single | 单个定义 |
|
||||
| formatGoToDefinitionResult — multiple | 多个定义（分组） |
|
||||
| formatFindReferencesResult | 引用列表 |
|
||||
| formatHoverResult — markdown | markdown 内容 |
|
||||
| formatHoverResult — plaintext | 纯文本 |
|
||||
| formatDocumentSymbolResult — classes | 类符号 |
|
||||
| formatDocumentSymbolResult — functions | 函数符号 |
|
||||
| formatDocumentSymbolResult — nested | 嵌套符号 |
|
||||
| formatWorkspaceSymbolResult | 工作区符号 |
|
||||
| formatPrepareCallHierarchyResult | 调用层次 |
|
||||
| formatIncomingCallsResult | 入调用 |
|
||||
| formatOutgoingCallsResult | 出调用 |
|
||||
| empty results | 各函数空结果 |
|
||||
| groupByFile helper | 文件分组逻辑 |
|
||||
|
||||
---
|
||||
|
||||
## 17.6 `src/tools/GrepTool/__tests__/utils.test.ts`（~10 tests）
|
||||
|
||||
**目标模块**: `src/tools/GrepTool/GrepTool.ts`（577 行）
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| applyHeadLimit — within limit | 不截断 |
|
||||
| applyHeadLimit — exceeds limit | 正确截断 |
|
||||
| applyHeadLimit — offset + limit | 分页逻辑 |
|
||||
| applyHeadLimit — zero limit | 边界 |
|
||||
| formatLimitInfo — basic | 格式化输出 |
|
||||
|
||||
**Mock**: `mock.module("src/utils/log.ts", ...)` 解锁导入
|
||||
|
||||
---
|
||||
|
||||
## 17.7 `src/tools/WebFetchTool/__tests__/utils.test.ts`（~15 tests）
|
||||
|
||||
**目标模块**: `src/tools/WebFetchTool/utils.ts`（531 行）
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| validateURL — valid http | 通过 |
|
||||
| validateURL — valid https | 通过 |
|
||||
| validateURL — ftp | 拒绝 |
|
||||
| validateURL — no protocol | 拒绝 |
|
||||
| validateURL — localhost | 处理 |
|
||||
| isPermittedRedirect — same host | 允许 |
|
||||
| isPermittedRedirect — different host | 拒绝 |
|
||||
| isPermittedRedirect — subdomain | 处理 |
|
||||
| isRedirectInfo — valid object | true |
|
||||
| isRedirectInfo — invalid | false |
|
||||
|
||||
---
|
||||
|
||||
## 17.8 `src/tools/WebFetchTool/__tests__/preapproved.test.ts`（~10 tests）
|
||||
|
||||
**目标模块**: `src/tools/WebFetchTool/preapproved.ts`（167 行）
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| exact hostname match | 通过 |
|
||||
| subdomain match | 处理 |
|
||||
| path prefix match | `/docs/api` 匹配 |
|
||||
| path non-match | `/internal` 不匹配 |
|
||||
| unknown hostname | false |
|
||||
| empty pathname | 边界 |
|
||||
|
||||
---
|
||||
|
||||
## 17.9 `src/tools/FileReadTool/__tests__/utils.test.ts`（~15 tests）
|
||||
|
||||
**目标模块**: `src/tools/FileReadTool/FileReadTool.ts`（1184 行）
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| isBlockedDevicePath — /dev/sda | true |
|
||||
| isBlockedDevicePath — /dev/null | 处理 |
|
||||
| isBlockedDevicePath — normal file | false |
|
||||
| detectSessionFileType — .jsonl | 会话文件类型 |
|
||||
| detectSessionFileType — unknown | 未知类型 |
|
||||
| formatFileLines — basic | 行号格式 |
|
||||
| formatFileLines — empty | 空文件 |
|
||||
|
||||
---
|
||||
|
||||
## 17.10 `src/tools/AgentTool/__tests__/agentToolUtils.test.ts`（~18 tests）
|
||||
|
||||
**目标模块**: `src/tools/AgentTool/agentToolUtils.ts`（688 行）
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| filterToolsForAgent — builtin only | 只返回内置工具 |
|
||||
| filterToolsForAgent — exclude async | 排除异步工具 |
|
||||
| filterToolsForAgent — permission mode | 权限过滤 |
|
||||
| resolveAgentTools — wildcard | 通配符展开 |
|
||||
| resolveAgentTools — explicit list | 显式列表 |
|
||||
| countToolUses — multiple | 消息中工具调用计数 |
|
||||
| countToolUses — zero | 无工具调用 |
|
||||
| extractPartialResult — text only | 提取文本 |
|
||||
| extractPartialResult — mixed | 混合内容 |
|
||||
| getLastToolUseName — basic | 最后工具名 |
|
||||
| getLastToolUseName — no tool use | 无工具调用 |
|
||||
|
||||
**Mock**: `mock.module("src/bootstrap/state.ts", ...)`, `mock.module("src/utils/log.ts", ...)`
|
||||
|
||||
---
|
||||
|
||||
## 17.11 `src/tools/LSPTool/__tests__/schemas.test.ts`（~5 tests）
|
||||
|
||||
**目标模块**: `src/tools/LSPTool/schemas.ts`（216 行）
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| isValidLSPOperation — goToDefinition | true |
|
||||
| isValidLSPOperation — findReferences | true |
|
||||
| isValidLSPOperation — hover | true |
|
||||
| isValidLSPOperation — invalid | false |
|
||||
| isValidLSPOperation — empty string | false |
|
||||
@@ -1,110 +0,0 @@
|
||||
# Phase 18 — WEAK 修复 + ACCEPTABLE 加固
|
||||
|
||||
> 创建日期：2026-04-02
|
||||
> 预计：+30 tests / 4 files (修改现有)
|
||||
> 目标：修复所有 WEAK 评分测试文件，消除系统性问题
|
||||
|
||||
---
|
||||
|
||||
## 18.1 `src/utils/__tests__/format.test.ts` — 断言精确化（+5 tests）
|
||||
|
||||
**问题**: `formatNumber`/`formatTokens`/`formatRelativeTime` 使用 `toContain`
|
||||
**修复**: 改为 `toBe` 精确匹配
|
||||
|
||||
```diff
|
||||
- expect(formatNumber(1500000)).toContain("1.5")
|
||||
+ expect(formatNumber(1500000)).toBe("1.5m")
|
||||
```
|
||||
|
||||
新增测试：
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| formatNumber — 0 | `"0"` |
|
||||
| formatNumber — billions | `"1.5b"` |
|
||||
| formatTokens — thousands | 精确匹配 |
|
||||
| formatRelativeTime — hours ago | 精确匹配 |
|
||||
| formatRelativeTime — days ago | 精确匹配 |
|
||||
|
||||
---
|
||||
|
||||
## 18.2 `src/utils/__tests__/envValidation.test.ts` — Bug 确认（+3 tests）
|
||||
|
||||
**问题**: `value=1, lowerBound=100` 返回 `status: "valid"` — 函数名暗示有下界检查
|
||||
**计划**: 先读取源码确认 `defaultValue` 和 `lowerBound` 的语义关系，然后：
|
||||
- 如果是源码 bug → 在测试中注释标记，不修改源码
|
||||
- 如果是设计意图 → 更新测试描述明确语义
|
||||
|
||||
新增测试：
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| parseFloat truncation | `"50.9"` → 50 |
|
||||
| whitespace handling | `" 500 "` → 500 |
|
||||
| very large number | overflow 处理 |
|
||||
|
||||
---
|
||||
|
||||
## 18.3 `src/utils/permissions/__tests__/PermissionMode.test.ts` — false 路径（+8 tests）
|
||||
|
||||
**问题**: `isExternalPermissionMode` false 路径从未执行
|
||||
**修复**: 覆盖所有 5 种 mode 的 true/false 期望
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| isExternalPermissionMode — plan | false |
|
||||
| isExternalPermissionMode — auto | false |
|
||||
| isExternalPermissionMode — default | false |
|
||||
| permissionModeFromString — all modes | 5 种 mode 全覆盖 |
|
||||
| permissionModeFromString — invalid | 默认值 |
|
||||
| permissionModeFromString — case insensitive | 大小写 |
|
||||
| isPermissionMode — valid strings | true |
|
||||
| isPermissionMode — invalid strings | false |
|
||||
|
||||
---
|
||||
|
||||
## 18.4 `src/tools/shared/__tests__/gitOperationTracking.test.ts` — mock analytics（+4 tests）
|
||||
|
||||
**问题**: 未 mock analytics 依赖，测试产生副作用
|
||||
**修复**: 添加 `mock.module("src/services/analytics/...", ...)`
|
||||
|
||||
新增测试：
|
||||
|
||||
| 测试用例 | 验证点 |
|
||||
|---------|--------|
|
||||
| parseGitCommitId — all GH PR actions | 补齐 6 个 action |
|
||||
| detectGitOperation — no analytics call | mock 验证 |
|
||||
| detectGitCommitId — various formats | SHA/短 SHA/HEAD |
|
||||
| git operation tracking — edge cases | 空输入、畸形输入 |
|
||||
|
||||
---
|
||||
|
||||
## 排除清单
|
||||
|
||||
以下模块 **不纳入测试**，原因合理：
|
||||
|
||||
| 模块 | 行数 | 排除原因 |
|
||||
|------|------|---------|
|
||||
| `query.ts` | 1732 | 核心循环，40+ 依赖，需完整集成环境 |
|
||||
| `QueryEngine.ts` | 1320 | 编排器，30+ 依赖 |
|
||||
| `utils/hooks.ts` | 5121 | 51 exports，spawn 子进程 |
|
||||
| `utils/config.ts` | 1817 | 文件系统 + lockfile + 全局状态 |
|
||||
| `utils/auth.ts` | 2002 | 多 provider 认证，平台特定 |
|
||||
| `utils/fileHistory.ts` | 1115 | 重 I/O 文件备份 |
|
||||
| `utils/sessionRestore.ts` | 551 | 恢复状态涉及多个子系统 |
|
||||
| `utils/ripgrep.ts` | 679 | spawn 子进程 |
|
||||
| `utils/yaml.ts` | 15 | 两行 wrapper |
|
||||
| `utils/lockfile.ts` | 43 | trivial wrapper |
|
||||
| `screens/` / `components/` | — | Ink 渲染测试环境 |
|
||||
| `bridge/` / `remote/` / `ssh/` | — | 网络层 |
|
||||
| `daemon/` / `server/` | — | 进程管理 |
|
||||
|
||||
---
|
||||
|
||||
## 预期成果
|
||||
|
||||
| 指标 | Phase 16 后 | Phase 17 后 | Phase 18 后 |
|
||||
|------|-----------|-----------|-----------|
|
||||
| 测试数 | ~1417 | ~1567 | ~1597 |
|
||||
| 文件数 | 76 | 87 | 91 |
|
||||
| WEAK 文件 | 6 | 4 | **0** |
|
||||
@@ -1,435 +0,0 @@
|
||||
# Phase 19 - Batch 1: 零依赖微型 utils
|
||||
|
||||
> 预计 ~154 tests / 13 文件 | 全部纯函数，无需 mock
|
||||
|
||||
---
|
||||
|
||||
## 1. `src/utils/__tests__/semanticBoolean.test.ts` (~8 tests)
|
||||
|
||||
**源文件**: `src/utils/semanticBoolean.ts` (30 行)
|
||||
**依赖**: `zod/v4`
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("semanticBoolean", () => {
|
||||
// 基本 Zod 行为
|
||||
test("parses boolean true to true")
|
||||
test("parses boolean false to false")
|
||||
test("parses string 'true' to true")
|
||||
test("parses string 'false' to false")
|
||||
// 边界
|
||||
test("rejects string 'TRUE' (case-sensitive)")
|
||||
test("rejects string 'FALSE' (case-sensitive)")
|
||||
test("rejects number 1")
|
||||
test("rejects null")
|
||||
test("rejects undefined")
|
||||
// 自定义 inner schema
|
||||
test("works with custom inner schema (z.boolean().optional())")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
无
|
||||
|
||||
---
|
||||
|
||||
## 2. `src/utils/__tests__/semanticNumber.test.ts` (~10 tests)
|
||||
|
||||
**源文件**: `src/utils/semanticNumber.ts` (37 行)
|
||||
**依赖**: `zod/v4`
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("semanticNumber", () => {
|
||||
test("parses number 42")
|
||||
test("parses number 0")
|
||||
test("parses negative number -5")
|
||||
test("parses float 3.14")
|
||||
test("parses string '42' to 42")
|
||||
test("parses string '-7.5' to -7.5")
|
||||
test("rejects string 'abc'")
|
||||
test("rejects empty string ''")
|
||||
test("rejects null")
|
||||
test("rejects boolean true")
|
||||
test("works with custom inner schema (z.number().int().min(0))")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
无
|
||||
|
||||
---
|
||||
|
||||
## 3. `src/utils/__tests__/lazySchema.test.ts` (~6 tests)
|
||||
|
||||
**源文件**: `src/utils/lazySchema.ts` (9 行)
|
||||
**依赖**: 无
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("lazySchema", () => {
|
||||
test("returns a function")
|
||||
test("calls factory on first invocation")
|
||||
test("returns cached result on subsequent invocations")
|
||||
test("factory is called only once (call count verification)")
|
||||
test("works with different return types")
|
||||
test("each call to lazySchema returns independent cache")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
无
|
||||
|
||||
---
|
||||
|
||||
## 4. `src/utils/__tests__/withResolvers.test.ts` (~8 tests)
|
||||
|
||||
**源文件**: `src/utils/withResolvers.ts` (14 行)
|
||||
**依赖**: 无
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("withResolvers", () => {
|
||||
test("returns object with promise, resolve, reject")
|
||||
test("promise resolves when resolve is called")
|
||||
test("promise rejects when reject is called")
|
||||
test("resolve passes value through")
|
||||
test("reject passes error through")
|
||||
test("promise is instanceof Promise")
|
||||
test("works with generic type parameter")
|
||||
test("resolve/reject can be called asynchronously")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
无
|
||||
|
||||
---
|
||||
|
||||
## 5. `src/utils/__tests__/userPromptKeywords.test.ts` (~12 tests)
|
||||
|
||||
**源文件**: `src/utils/userPromptKeywords.ts` (28 行)
|
||||
**依赖**: 无
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("matchesNegativeKeyword", () => {
|
||||
test("matches 'wtf'")
|
||||
test("matches 'shit'")
|
||||
test("matches 'fucking broken'")
|
||||
test("does not match normal input like 'fix the bug'")
|
||||
test("is case-insensitive")
|
||||
test("matches partial word in sentence")
|
||||
})
|
||||
|
||||
describe("matchesKeepGoingKeyword", () => {
|
||||
test("matches exact 'continue'")
|
||||
test("matches 'keep going'")
|
||||
test("matches 'go on'")
|
||||
test("does not match 'cont'")
|
||||
test("does not match empty string")
|
||||
test("matches within larger sentence 'please continue'")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
无
|
||||
|
||||
---
|
||||
|
||||
## 6. `src/utils/__tests__/xdg.test.ts` (~15 tests)
|
||||
|
||||
**源文件**: `src/utils/xdg.ts` (66 行)
|
||||
**依赖**: 无（通过 options 参数注入）
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("getXDGStateHome", () => {
|
||||
test("returns ~/.local/state by default")
|
||||
test("respects XDG_STATE_HOME env var")
|
||||
test("uses custom homedir from options")
|
||||
})
|
||||
|
||||
describe("getXDGCacheHome", () => {
|
||||
test("returns ~/.cache by default")
|
||||
test("respects XDG_CACHE_HOME env var")
|
||||
})
|
||||
|
||||
describe("getXDGDataHome", () => {
|
||||
test("returns ~/.local/share by default")
|
||||
test("respects XDG_DATA_HOME env var")
|
||||
})
|
||||
|
||||
describe("getUserBinDir", () => {
|
||||
test("returns ~/.local/bin")
|
||||
test("uses custom homedir from options")
|
||||
})
|
||||
|
||||
describe("resolveOptions", () => {
|
||||
test("defaults env to process.env")
|
||||
test("defaults homedir to os.homedir()")
|
||||
test("merges partial options")
|
||||
})
|
||||
|
||||
describe("path construction", () => {
|
||||
test("all paths end with correct subdirectory")
|
||||
test("respects HOME env via homedir override")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
无（通过 options.env 和 options.homedir 注入）
|
||||
|
||||
---
|
||||
|
||||
## 7. `src/utils/__tests__/horizontalScroll.test.ts` (~20 tests)
|
||||
|
||||
**源文件**: `src/utils/horizontalScroll.ts` (138 行)
|
||||
**依赖**: 无
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("calculateHorizontalScrollWindow", () => {
|
||||
// 基本场景
|
||||
test("all items fit within available width")
|
||||
test("single item selected within view")
|
||||
test("selected item at beginning")
|
||||
test("selected item at end")
|
||||
test("selected item beyond visible range scrolls right")
|
||||
test("selected item before visible range scrolls left")
|
||||
|
||||
// 箭头指示器
|
||||
test("showLeftArrow when items hidden on left")
|
||||
test("showRightArrow when items hidden on right")
|
||||
test("no arrows when all items visible")
|
||||
test("both arrows when items hidden on both sides")
|
||||
|
||||
// 边界条件
|
||||
test("empty itemWidths array")
|
||||
test("single item")
|
||||
test("available width is 0")
|
||||
test("item wider than available width")
|
||||
test("all items same width")
|
||||
test("varying item widths")
|
||||
test("firstItemHasSeparator adds separator width to first item")
|
||||
test("selectedIdx in middle of overflow")
|
||||
test("scroll snaps to show selected at left edge")
|
||||
test("scroll snaps to show selected at right edge")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
无
|
||||
|
||||
---
|
||||
|
||||
## 8. `src/utils/__tests__/generators.test.ts` (~18 tests)
|
||||
|
||||
**源文件**: `src/utils/generators.ts` (89 行)
|
||||
**依赖**: 无
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("lastX", () => {
|
||||
test("returns last yielded value")
|
||||
test("returns only value from single-yield generator")
|
||||
test("throws on empty generator")
|
||||
})
|
||||
|
||||
describe("returnValue", () => {
|
||||
test("returns generator return value")
|
||||
test("returns undefined for void return")
|
||||
})
|
||||
|
||||
describe("toArray", () => {
|
||||
test("collects all yielded values")
|
||||
test("returns empty array for empty generator")
|
||||
test("preserves order")
|
||||
})
|
||||
|
||||
describe("fromArray", () => {
|
||||
test("yields all array elements")
|
||||
test("yields nothing for empty array")
|
||||
})
|
||||
|
||||
describe("all", () => {
|
||||
test("merges multiple generators preserving yield order")
|
||||
test("respects concurrency cap")
|
||||
test("handles empty generator array")
|
||||
test("handles single generator")
|
||||
test("handles generators of different lengths")
|
||||
test("yields all values from all generators")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
无（用 fromArray 构造测试数据）
|
||||
|
||||
---
|
||||
|
||||
## 9. `src/utils/__tests__/sequential.test.ts` (~12 tests)
|
||||
|
||||
**源文件**: `src/utils/sequential.ts` (57 行)
|
||||
**依赖**: 无
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("sequential", () => {
|
||||
test("wraps async function, returns same result")
|
||||
test("single call resolves normally")
|
||||
test("concurrent calls execute sequentially (FIFO order)")
|
||||
test("preserves arguments correctly")
|
||||
test("error in first call does not block subsequent calls")
|
||||
test("preserves rejection reason")
|
||||
test("multiple args passed correctly")
|
||||
test("returns different wrapper for each call to sequential")
|
||||
test("handles rapid concurrent calls")
|
||||
test("execution order matches call order")
|
||||
test("works with functions returning different types")
|
||||
test("wrapper has same arity expectations")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
无
|
||||
|
||||
---
|
||||
|
||||
## 10. `src/utils/__tests__/fingerprint.test.ts` (~15 tests)
|
||||
|
||||
**源文件**: `src/utils/fingerprint.ts` (77 行)
|
||||
**依赖**: `crypto` (内置)
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("FINGERPRINT_SALT", () => {
|
||||
test("has expected value '59cf53e54c78'")
|
||||
})
|
||||
|
||||
describe("extractFirstMessageText", () => {
|
||||
test("extracts text from first user message")
|
||||
test("extracts text from single user message with array content")
|
||||
test("returns empty string when no user messages")
|
||||
test("skips assistant messages")
|
||||
test("handles mixed content blocks (text + image)")
|
||||
})
|
||||
|
||||
describe("computeFingerprint", () => {
|
||||
test("returns deterministic 3-char hex string")
|
||||
test("same input produces same fingerprint")
|
||||
test("different message text produces different fingerprint")
|
||||
test("different version produces different fingerprint")
|
||||
test("handles short strings (length < 21)")
|
||||
test("handles empty string")
|
||||
test("fingerprint is valid hex")
|
||||
})
|
||||
|
||||
describe("computeFingerprintFromMessages", () => {
|
||||
test("end-to-end: messages -> fingerprint")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
需要 `mock.module` 处理 `UserMessage`/`AssistantMessage` 类型依赖（查看实际 import 情况）
|
||||
|
||||
---
|
||||
|
||||
## 11. `src/utils/__tests__/configConstants.test.ts` (~8 tests)
|
||||
|
||||
**源文件**: `src/utils/configConstants.ts` (22 行)
|
||||
**依赖**: 无
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("NOTIFICATION_CHANNELS", () => {
|
||||
test("contains expected channels")
|
||||
test("is readonly array")
|
||||
test("includes 'auto', 'iterm2', 'terminal_bell'")
|
||||
})
|
||||
|
||||
describe("EDITOR_MODES", () => {
|
||||
test("contains 'normal' and 'vim'")
|
||||
test("has exactly 2 entries")
|
||||
})
|
||||
|
||||
describe("TEAMMATE_MODES", () => {
|
||||
test("contains 'auto', 'tmux', 'in-process'")
|
||||
test("has exactly 3 entries")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
无
|
||||
|
||||
---
|
||||
|
||||
## 12. `src/utils/__tests__/directMemberMessage.test.ts` (~12 tests)
|
||||
|
||||
**源文件**: `src/utils/directMemberMessage.ts` (70 行)
|
||||
**依赖**: 仅类型（可 mock）
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("parseDirectMemberMessage", () => {
|
||||
test("parses '@agent-name hello world'")
|
||||
test("parses '@agent-name single-word'")
|
||||
test("returns null for non-matching input")
|
||||
test("returns null for empty string")
|
||||
test("returns null for '@name' without message")
|
||||
test("handles hyphenated agent names like '@my-agent msg'")
|
||||
test("handles multiline message content")
|
||||
test("extracts correct recipientName and message")
|
||||
})
|
||||
|
||||
// sendDirectMemberMessage 需要 mock teamContext/writeToMailbox
|
||||
describe("sendDirectMemberMessage", () => {
|
||||
test("returns error when no team context")
|
||||
test("returns error for unknown recipient")
|
||||
test("calls writeToMailbox with correct args for valid recipient")
|
||||
test("returns success for valid message")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
`sendDirectMemberMessage` 需要 mock `AppState['teamContext']` 和 `WriteToMailboxFn`
|
||||
|
||||
---
|
||||
|
||||
## 13. `src/utils/__tests__/collapseHookSummaries.test.ts` (~12 tests)
|
||||
|
||||
**源文件**: `src/utils/collapseHookSummaries.ts` (60 行)
|
||||
**依赖**: 仅类型
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("collapseHookSummaries", () => {
|
||||
test("returns same messages when no hook summaries")
|
||||
test("collapses consecutive messages with same hookLabel")
|
||||
test("does not collapse messages with different hookLabels")
|
||||
test("aggregates hookCount across collapsed messages")
|
||||
test("merges hookInfos arrays")
|
||||
test("merges hookErrors arrays")
|
||||
test("takes max totalDurationMs")
|
||||
test("takes any truthy preventContinuation")
|
||||
test("leaves single hook summary unchanged")
|
||||
test("handles three consecutive same-label summaries")
|
||||
test("preserves non-hook messages in between")
|
||||
test("returns empty array for empty input")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
需要构造 `RenderableMessage` mock 对象
|
||||
@@ -1,287 +0,0 @@
|
||||
# Phase 19 - Batch 2: 更多 utils + state + commands
|
||||
|
||||
> 预计 ~120 tests / 8 文件 | 部分需轻量 mock
|
||||
|
||||
---
|
||||
|
||||
## 1. `src/utils/__tests__/collapseTeammateShutdowns.test.ts` (~10 tests)
|
||||
|
||||
**源文件**: `src/utils/collapseTeammateShutdowns.ts` (56 行)
|
||||
**依赖**: 仅类型
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("collapseTeammateShutdowns", () => {
|
||||
test("returns same messages when no teammate shutdowns")
|
||||
test("leaves single shutdown message unchanged")
|
||||
test("collapses consecutive shutdown messages into batch")
|
||||
test("batch attachment has correct count")
|
||||
test("does not collapse non-consecutive shutdowns")
|
||||
test("preserves non-shutdown messages between shutdowns")
|
||||
test("handles empty array")
|
||||
test("handles mixed message types")
|
||||
test("collapses more than 2 consecutive shutdowns")
|
||||
test("non-teammate task_status messages are not collapsed")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
构造 `RenderableMessage` mock 对象（带 `task_status` attachment，`status=completed`，`taskType=in_process_teammate`）
|
||||
|
||||
---
|
||||
|
||||
## 2. `src/utils/__tests__/privacyLevel.test.ts` (~12 tests)
|
||||
|
||||
**源文件**: `src/utils/privacyLevel.ts` (56 行)
|
||||
**依赖**: `process.env`
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("getPrivacyLevel", () => {
|
||||
test("returns 'default' when no env vars set")
|
||||
test("returns 'essential-traffic' when CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC is set")
|
||||
test("returns 'no-telemetry' when DISABLE_TELEMETRY is set")
|
||||
test("'essential-traffic' takes priority over 'no-telemetry'")
|
||||
})
|
||||
|
||||
describe("isEssentialTrafficOnly", () => {
|
||||
test("returns true for 'essential-traffic' level")
|
||||
test("returns false for 'default' level")
|
||||
test("returns false for 'no-telemetry' level")
|
||||
})
|
||||
|
||||
describe("isTelemetryDisabled", () => {
|
||||
test("returns true for 'no-telemetry' level")
|
||||
test("returns true for 'essential-traffic' level")
|
||||
test("returns false for 'default' level")
|
||||
})
|
||||
|
||||
describe("getEssentialTrafficOnlyReason", () => {
|
||||
test("returns env var name when restricted")
|
||||
test("returns null when unrestricted")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
`process.env` 保存/恢复模式（参考现有 `envUtils.test.ts`）
|
||||
|
||||
---
|
||||
|
||||
## 3. `src/utils/__tests__/textHighlighting.test.ts` (~18 tests)
|
||||
|
||||
**源文件**: `src/utils/textHighlighting.ts` (167 行)
|
||||
**依赖**: `@alcalzone/ansi-tokenize`
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("segmentTextByHighlights", () => {
|
||||
// 基本
|
||||
test("returns single segment with no highlights")
|
||||
test("returns highlighted segment for single highlight")
|
||||
test("returns two segments for highlight covering middle portion")
|
||||
test("returns three segments for highlight in the middle")
|
||||
|
||||
// 多高亮
|
||||
test("handles non-overlapping highlights")
|
||||
test("handles overlapping highlights (priority-based)")
|
||||
test("handles adjacent highlights")
|
||||
|
||||
// 边界
|
||||
test("highlight starting at 0")
|
||||
test("highlight ending at text length")
|
||||
test("highlight covering entire text")
|
||||
test("empty text with highlights")
|
||||
test("empty highlights array returns single segment")
|
||||
|
||||
// ANSI 处理
|
||||
test("correctly segments text with ANSI escape codes")
|
||||
test("handles text with mixed ANSI and highlights")
|
||||
|
||||
// 属性
|
||||
test("preserves highlight color property")
|
||||
test("preserves highlight priority property")
|
||||
test("preserves dimColor and inverse flags")
|
||||
test("highlights with start > end are handled gracefully")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
可能需要 mock `@alcalzone/ansi-tokenize`，或直接使用（如果有安装）
|
||||
|
||||
---
|
||||
|
||||
## 4. `src/utils/__tests__/detectRepository.test.ts` (~15 tests)
|
||||
|
||||
**源文件**: `src/utils/detectRepository.ts` (179 行)
|
||||
**依赖**: git 命令（`getRemoteUrl`）
|
||||
|
||||
### 重点测试函数
|
||||
|
||||
**`parseGitRemote(input: string): ParsedRepository | null`** — 纯正则解析
|
||||
**`parseGitHubRepository(input: string): string | null`** — 纯函数
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("parseGitRemote", () => {
|
||||
// HTTPS
|
||||
test("parses HTTPS URL: https://github.com/owner/repo.git")
|
||||
test("parses HTTPS URL without .git suffix")
|
||||
test("parses HTTPS URL with subdirectory path (only takes first 2 segments)")
|
||||
|
||||
// SSH
|
||||
test("parses SSH URL: git@github.com:owner/repo.git")
|
||||
test("parses SSH URL without .git suffix")
|
||||
|
||||
// ssh://
|
||||
test("parses ssh:// URL: ssh://git@github.com/owner/repo.git")
|
||||
|
||||
// git://
|
||||
test("parses git:// URL")
|
||||
|
||||
// 边界
|
||||
test("returns null for invalid URL")
|
||||
test("returns null for empty string")
|
||||
test("handles GHE hostname")
|
||||
test("handles port number in URL")
|
||||
})
|
||||
|
||||
describe("parseGitHubRepository", () => {
|
||||
test("extracts 'owner/repo' from valid remote URL")
|
||||
test("handles plain 'owner/repo' string input")
|
||||
test("returns null for non-GitHub host (if restricted)")
|
||||
test("returns null for invalid input")
|
||||
test("is case-sensitive for owner/repo")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
仅测试 `parseGitRemote` 和 `parseGitHubRepository`（纯函数），不需要 mock git
|
||||
|
||||
---
|
||||
|
||||
## 5. `src/utils/__tests__/markdown.test.ts` (~20 tests)
|
||||
|
||||
**源文件**: `src/utils/markdown.ts` (382 行)
|
||||
**依赖**: `marked`, `cli-highlight`, theme types
|
||||
|
||||
### 重点测试函数
|
||||
|
||||
**`padAligned(content, displayWidth, targetWidth, align)`** — 纯函数
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("padAligned", () => {
|
||||
test("left-aligns: pads with spaces on right")
|
||||
test("right-aligns: pads with spaces on left")
|
||||
test("center-aligns: pads with spaces on both sides")
|
||||
test("no padding when displayWidth equals targetWidth")
|
||||
test("handles content wider than targetWidth")
|
||||
test("null/undefined align defaults to left")
|
||||
test("handles empty string content")
|
||||
test("handles zero displayWidth")
|
||||
test("handles zero targetWidth")
|
||||
test("center alignment with odd padding distribution")
|
||||
})
|
||||
```
|
||||
|
||||
注意：`numberToLetter`/`numberToRoman`/`getListNumber` 是私有函数，除非从模块导出否则无法直接测试。如果确实私有，则通过 `applyMarkdown` 间接测试列表渲染：
|
||||
|
||||
```typescript
|
||||
describe("list numbering (via applyMarkdown)", () => {
|
||||
test("numbered list renders with digits")
|
||||
test("nested ordered list uses letters (a, b, c)")
|
||||
test("deep nested list uses roman numerals")
|
||||
test("unordered list uses bullet markers")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
`padAligned` 无需 mock。`applyMarkdown` 可能需要 mock theme 依赖。
|
||||
|
||||
---
|
||||
|
||||
## 6. `src/state/__tests__/store.test.ts` (~15 tests)
|
||||
|
||||
**源文件**: `src/state/store.ts` (35 行)
|
||||
**依赖**: 无
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("createStore", () => {
|
||||
test("returns object with getState, setState, subscribe")
|
||||
test("getState returns initial state")
|
||||
test("setState updates state via updater function")
|
||||
test("setState does not notify when state unchanged (Object.is)")
|
||||
test("setState notifies subscribers on change")
|
||||
test("subscribe returns unsubscribe function")
|
||||
test("unsubscribe stops notifications")
|
||||
test("multiple subscribers all get notified")
|
||||
test("onChange callback is called on state change")
|
||||
test("onChange is not called when state unchanged")
|
||||
test("works with complex state objects")
|
||||
test("works with primitive state")
|
||||
test("updater receives previous state")
|
||||
test("sequential setState calls produce final state")
|
||||
test("subscriber called after all state changes in synchronous batch")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
无
|
||||
|
||||
---
|
||||
|
||||
## 7. `src/commands/plugin/__tests__/parseArgs.test.ts` (~18 tests)
|
||||
|
||||
**源文件**: `src/commands/plugin/parseArgs.ts` (104 行)
|
||||
**依赖**: 无
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("parsePluginArgs", () => {
|
||||
// 无参数
|
||||
test("returns { type: 'menu' } for undefined")
|
||||
test("returns { type: 'menu' } for empty string")
|
||||
test("returns { type: 'menu' } for whitespace only")
|
||||
|
||||
// help
|
||||
test("returns { type: 'help' } for 'help'")
|
||||
|
||||
// install
|
||||
test("parses 'install my-plugin' -> { type: 'install', name: 'my-plugin' }")
|
||||
test("parses 'install my-plugin@github' with marketplace")
|
||||
test("parses 'install https://github.com/...' as URL marketplace")
|
||||
|
||||
// uninstall
|
||||
test("returns { type: 'uninstall', name: '...' }")
|
||||
|
||||
// enable/disable
|
||||
test("returns { type: 'enable', name: '...' }")
|
||||
test("returns { type: 'disable', name: '...' }")
|
||||
|
||||
// validate
|
||||
test("returns { type: 'validate', name: '...' }")
|
||||
|
||||
// manage
|
||||
test("returns { type: 'manage' }")
|
||||
|
||||
// marketplace 子命令
|
||||
test("parses 'marketplace add ...'")
|
||||
test("parses 'marketplace remove ...'")
|
||||
test("parses 'marketplace list'")
|
||||
|
||||
// 边界
|
||||
test("handles extra whitespace")
|
||||
test("handles unknown subcommand gracefully")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
无
|
||||
@@ -1,258 +0,0 @@
|
||||
# Phase 19 - Batch 3: Tool 子模块纯逻辑
|
||||
|
||||
> 预计 ~113 tests / 6 文件 | 采用 `mock.module()` + `await import()` 模式
|
||||
|
||||
---
|
||||
|
||||
## 1. `src/tools/GrepTool/__tests__/headLimit.test.ts` (~20 tests)
|
||||
|
||||
**源文件**: `src/tools/GrepTool/GrepTool.ts` (578 行)
|
||||
**目标函数**: `applyHeadLimit<T>`, `formatLimitInfo` (非导出，需确认可测性)
|
||||
|
||||
### 测试策略
|
||||
如果函数是文件内导出的，直接 `await import()` 获取。如果私有，则通过 GrepTool 的输出间接测试，或提取到独立文件。
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("applyHeadLimit", () => {
|
||||
test("returns full array when limit is undefined (default 250)")
|
||||
test("applies limit correctly: limits to N items")
|
||||
test("limit=0 means no limit (returns all)")
|
||||
test("applies offset correctly")
|
||||
test("offset + limit combined")
|
||||
test("offset beyond array length returns empty")
|
||||
test("returns appliedLimit when truncation occurred")
|
||||
test("returns appliedLimit=undefined when no truncation")
|
||||
test("limit larger than array returns all items with appliedLimit=undefined")
|
||||
test("empty array returns empty with appliedLimit=undefined")
|
||||
test("offset=0 is default")
|
||||
test("negative limit behavior")
|
||||
})
|
||||
|
||||
describe("formatLimitInfo", () => {
|
||||
test("formats 'limit: N, offset: M' when both present")
|
||||
test("formats 'limit: N' when only limit")
|
||||
test("formats 'offset: M' when only offset")
|
||||
test("returns empty string when both undefined")
|
||||
test("handles limit=0 (no limit, should not appear)")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
需 mock 重依赖链（`log`, `slowOperations` 等），通过 `mock.module()` + `await import()` 只取目标函数
|
||||
|
||||
---
|
||||
|
||||
## 2. `src/tools/MCPTool/__tests__/classifyForCollapse.test.ts` (~25 tests)
|
||||
|
||||
**源文件**: `src/tools/MCPTool/classifyForCollapse.ts` (605 行)
|
||||
**目标函数**: `classifyMcpToolForCollapse`, `normalize`
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("normalize", () => {
|
||||
test("leaves snake_case unchanged: 'search_issues'")
|
||||
test("converts camelCase to snake_case: 'searchIssues' -> 'search_issues'")
|
||||
test("converts kebab-case to snake_case: 'search-issues' -> 'search_issues'")
|
||||
test("handles mixed: 'searchIssuesByStatus' -> 'search_issues_by_status'")
|
||||
test("handles already lowercase single word")
|
||||
test("handles empty string")
|
||||
test("handles PascalCase: 'SearchIssues' -> 'search_issues'")
|
||||
})
|
||||
|
||||
describe("classifyMcpToolForCollapse", () => {
|
||||
// 搜索工具
|
||||
test("classifies Slack search_messages as search")
|
||||
test("classifies GitHub search_code as search")
|
||||
test("classifies Linear search_issues as search")
|
||||
test("classifies Datadog search_logs as search")
|
||||
test("classifies Notion search as search")
|
||||
|
||||
// 读取工具
|
||||
test("classifies Slack get_message as read")
|
||||
test("classifies GitHub get_file_contents as read")
|
||||
test("classifies Linear get_issue as read")
|
||||
test("classifies Filesystem read_file as read")
|
||||
|
||||
// 双重分类
|
||||
test("some tools are both search and read")
|
||||
test("some tools are neither search nor read")
|
||||
|
||||
// 未知工具
|
||||
test("unknown tool returns { isSearch: false, isRead: false }")
|
||||
test("tool name with camelCase variant still matches")
|
||||
test("tool name with kebab-case variant still matches")
|
||||
|
||||
// server name 不影响分类
|
||||
test("server name parameter is accepted but unused in current logic")
|
||||
|
||||
// 边界
|
||||
test("empty tool name returns false/false")
|
||||
test("case sensitivity check (should match after normalize)")
|
||||
test("handles tool names with numbers")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
文件自包含（仅内部 Set + normalize 函数），需确认 `normalize` 是否导出
|
||||
|
||||
---
|
||||
|
||||
## 3. `src/tools/FileReadTool/__tests__/blockedPaths.test.ts` (~18 tests)
|
||||
|
||||
**源文件**: `src/tools/FileReadTool/FileReadTool.ts` (1184 行)
|
||||
**目标函数**: `isBlockedDevicePath`, `getAlternateScreenshotPath`
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("isBlockedDevicePath", () => {
|
||||
// 阻止的设备
|
||||
test("blocks /dev/zero")
|
||||
test("blocks /dev/random")
|
||||
test("blocks /dev/urandom")
|
||||
test("blocks /dev/full")
|
||||
test("blocks /dev/stdin")
|
||||
test("blocks /dev/tty")
|
||||
test("blocks /dev/console")
|
||||
test("blocks /dev/stdout")
|
||||
test("blocks /dev/stderr")
|
||||
test("blocks /dev/fd/0")
|
||||
test("blocks /dev/fd/1")
|
||||
test("blocks /dev/fd/2")
|
||||
|
||||
// 阻止 /proc
|
||||
test("blocks /proc/self/fd/0")
|
||||
test("blocks /proc/123/fd/2")
|
||||
|
||||
// 允许的路径
|
||||
test("allows /dev/null")
|
||||
test("allows regular file paths")
|
||||
test("allows /home/user/file.txt")
|
||||
})
|
||||
|
||||
describe("getAlternateScreenshotPath", () => {
|
||||
test("returns undefined for path without AM/PM")
|
||||
test("returns alternate path for macOS screenshot with regular space before AM")
|
||||
test("returns alternate path for macOS screenshot with U+202F before PM")
|
||||
test("handles path without time component")
|
||||
test("handles multiple AM/PM occurrences")
|
||||
test("returns undefined when no space variant difference")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
需 mock 重依赖链，通过 `await import()` 获取函数
|
||||
|
||||
---
|
||||
|
||||
## 4. `src/tools/AgentTool/__tests__/agentDisplay.test.ts` (~15 tests)
|
||||
|
||||
**源文件**: `src/tools/AgentTool/agentDisplay.ts` (105 行)
|
||||
**目标函数**: `resolveAgentOverrides`, `compareAgentsByName`
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("resolveAgentOverrides", () => {
|
||||
test("marks no overrides when all agents active")
|
||||
test("marks inactive agent as overridden")
|
||||
test("overriddenBy shows the overriding agent source")
|
||||
test("deduplicates agents by (agentType, source)")
|
||||
test("preserves agent definition properties")
|
||||
test("handles empty arrays")
|
||||
test("handles agent from git worktree (duplicate detection)")
|
||||
})
|
||||
|
||||
describe("compareAgentsByName", () => {
|
||||
test("sorts alphabetically ascending")
|
||||
test("returns negative when a.name < b.name")
|
||||
test("returns positive when a.name > b.name")
|
||||
test("returns 0 for same name")
|
||||
test("is case-sensitive")
|
||||
})
|
||||
|
||||
describe("AGENT_SOURCE_GROUPS", () => {
|
||||
test("contains expected source groups in order")
|
||||
test("has unique labels")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
需 mock `AgentDefinition`, `AgentSource` 类型依赖
|
||||
|
||||
---
|
||||
|
||||
## 5. `src/tools/AgentTool/__tests__/agentToolUtils.test.ts` (~20 tests)
|
||||
|
||||
**源文件**: `src/tools/AgentTool/agentToolUtils.ts` (688 行)
|
||||
**目标函数**: `countToolUses`, `getLastToolUseName`, `extractPartialResult`
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("countToolUses", () => {
|
||||
test("counts tool_use blocks in messages")
|
||||
test("returns 0 for messages without tool_use")
|
||||
test("returns 0 for empty array")
|
||||
test("counts multiple tool_use blocks across messages")
|
||||
test("counts tool_use in single message with multiple blocks")
|
||||
})
|
||||
|
||||
describe("getLastToolUseName", () => {
|
||||
test("returns last tool name from assistant message")
|
||||
test("returns undefined for message without tool_use")
|
||||
test("returns the last tool when multiple tool_uses present")
|
||||
test("handles message with non-array content")
|
||||
})
|
||||
|
||||
describe("extractPartialResult", () => {
|
||||
test("extracts text from last assistant message")
|
||||
test("returns undefined for messages without assistant content")
|
||||
test("handles interrupted agent with partial text")
|
||||
test("returns undefined for empty messages")
|
||||
test("concatenates multiple text blocks")
|
||||
test("skips non-text content blocks")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
需 mock 消息类型依赖
|
||||
|
||||
---
|
||||
|
||||
## 6. `src/tools/SkillTool/__tests__/skillSafety.test.ts` (~15 tests)
|
||||
|
||||
**源文件**: `src/tools/SkillTool/SkillTool.ts` (1110 行)
|
||||
**目标函数**: `skillHasOnlySafeProperties`, `extractUrlScheme`
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("skillHasOnlySafeProperties", () => {
|
||||
test("returns true for command with only safe properties")
|
||||
test("returns true for command with undefined extra properties")
|
||||
test("returns false for command with unsafe meaningful property")
|
||||
test("returns true for command with null extra properties")
|
||||
test("returns true for command with empty array extra property")
|
||||
test("returns true for command with empty object extra property")
|
||||
test("returns false for command with non-empty unsafe array")
|
||||
test("returns false for command with non-empty unsafe object")
|
||||
test("returns true for empty command object")
|
||||
})
|
||||
|
||||
describe("extractUrlScheme", () => {
|
||||
test("extracts 'gs' from 'gs://bucket/path'")
|
||||
test("extracts 'https' from 'https://example.com'")
|
||||
test("extracts 'http' from 'http://example.com'")
|
||||
test("extracts 's3' from 's3://bucket/path'")
|
||||
test("defaults to 'gs' for unknown scheme")
|
||||
test("defaults to 'gs' for path without scheme")
|
||||
test("defaults to 'gs' for empty string")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
需 mock 重依赖链，`await import()` 获取函数
|
||||
@@ -1,215 +0,0 @@
|
||||
# Phase 19 - Batch 4: Services 纯逻辑
|
||||
|
||||
> 预计 ~84 tests / 5 文件 | 部分需轻量 mock
|
||||
|
||||
---
|
||||
|
||||
## 1. `src/services/compact/__tests__/grouping.test.ts` (~15 tests)
|
||||
|
||||
**源文件**: `src/services/compact/grouping.ts` (64 行)
|
||||
**目标函数**: `groupMessagesByApiRound`
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("groupMessagesByApiRound", () => {
|
||||
test("returns single group for single API round")
|
||||
test("splits at new assistant message ID")
|
||||
test("keeps tool_result messages with their parent assistant message")
|
||||
test("handles streaming chunks (same assistant ID stays grouped)")
|
||||
test("returns empty array for empty input")
|
||||
test("handles all user messages (no assistant)")
|
||||
test("handles alternating assistant IDs")
|
||||
test("three API rounds produce three groups")
|
||||
test("user messages before first assistant go in first group")
|
||||
test("consecutive user messages stay in same group")
|
||||
test("does not produce empty groups")
|
||||
test("handles single message")
|
||||
test("preserves message order within groups")
|
||||
test("handles system messages")
|
||||
test("tool_result after assistant stays in same round")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
需构造 `Message` mock 对象（type: 'user'/'assistant', message: { id, content }）
|
||||
|
||||
---
|
||||
|
||||
## 2. `src/services/compact/__tests__/stripMessages.test.ts` (~20 tests)
|
||||
|
||||
**源文件**: `src/services/compact/compact.ts` (1709 行)
|
||||
**目标函数**: `stripImagesFromMessages`, `collectReadToolFilePaths` (私有)
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("stripImagesFromMessages", () => {
|
||||
// user 消息处理
|
||||
test("replaces image block with [image] text")
|
||||
test("replaces document block with [document] text")
|
||||
test("preserves text blocks unchanged")
|
||||
test("handles multiple image/document blocks in single message")
|
||||
test("returns original message when no media blocks")
|
||||
|
||||
// tool_result 内嵌套
|
||||
test("replaces image inside tool_result content")
|
||||
test("replaces document inside tool_result content")
|
||||
test("preserves non-media tool_result content")
|
||||
|
||||
// 非用户消息
|
||||
test("passes through assistant messages unchanged")
|
||||
test("passes through system messages unchanged")
|
||||
|
||||
// 边界
|
||||
test("handles empty message array")
|
||||
test("handles string content (non-array) in user message")
|
||||
test("does not mutate original messages")
|
||||
})
|
||||
|
||||
describe("collectReadToolFilePaths", () => {
|
||||
// 注意：这是私有函数，可能需要通过 stripImagesFromMessages 或其他导出间接测试
|
||||
// 如果不可直接测试，则跳过或通过集成测试覆盖
|
||||
test("collects file_path from Read tool_use blocks")
|
||||
test("skips tool_use with FILE_UNCHANGED_STUB result")
|
||||
test("returns empty set for messages without Read tool_use")
|
||||
test("handles multiple Read calls across messages")
|
||||
test("normalizes paths via expandPath")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
需 mock `expandPath`（如果 collectReadToolFilePaths 要测）
|
||||
需 mock `log`, `slowOperations` 等重依赖
|
||||
构造 `Message` mock 对象
|
||||
|
||||
---
|
||||
|
||||
## 3. `src/services/compact/__tests__/prompt.test.ts` (~12 tests)
|
||||
|
||||
**源文件**: `src/services/compact/prompt.ts` (375 行)
|
||||
**目标函数**: `formatCompactSummary`
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("formatCompactSummary", () => {
|
||||
test("strips <analysis>...</analysis> block")
|
||||
test("replaces <summary>...</summary> with 'Summary:\\n' prefix")
|
||||
test("handles analysis + summary together")
|
||||
test("handles summary without analysis")
|
||||
test("handles analysis without summary")
|
||||
test("collapses multiple newlines to double")
|
||||
test("trims leading/trailing whitespace")
|
||||
test("handles empty string")
|
||||
test("handles plain text without tags")
|
||||
test("handles multiline analysis content")
|
||||
test("preserves content between analysis and summary")
|
||||
test("handles nested-like tags gracefully")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
需 mock 重依赖链（`log`, feature flags 等）
|
||||
`formatCompactSummary` 是纯字符串处理，如果 import 链不太重则无需复杂 mock
|
||||
|
||||
---
|
||||
|
||||
## 4. `src/services/mcp/__tests__/channelPermissions.test.ts` (~25 tests)
|
||||
|
||||
**源文件**: `src/services/mcp/channelPermissions.ts` (241 行)
|
||||
**目标函数**: `hashToId`, `shortRequestId`, `truncateForPreview`, `filterPermissionRelayClients`
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("hashToId", () => {
|
||||
test("returns 5-char string")
|
||||
test("uses only letters a-z excluding 'l'")
|
||||
test("is deterministic (same input = same output)")
|
||||
test("different inputs produce different outputs (with high probability)")
|
||||
test("handles empty string")
|
||||
})
|
||||
|
||||
describe("shortRequestId", () => {
|
||||
test("returns 5-char string from tool use ID")
|
||||
test("is deterministic")
|
||||
test("avoids profanity substrings (retries with salt)")
|
||||
test("returns a valid ID even if all retries hit bad words (unlikely)")
|
||||
})
|
||||
|
||||
describe("truncateForPreview", () => {
|
||||
test("returns JSON string for object input")
|
||||
test("truncates to <=200 chars when input is long")
|
||||
test("adds ellipsis or truncation indicator")
|
||||
test("returns short input unchanged")
|
||||
test("handles string input")
|
||||
test("handles null/undefined input")
|
||||
})
|
||||
|
||||
describe("filterPermissionRelayClients", () => {
|
||||
test("keeps connected clients in allowlist with correct capabilities")
|
||||
test("filters out disconnected clients")
|
||||
test("filters out clients not in allowlist")
|
||||
test("filters out clients missing required capabilities")
|
||||
test("returns empty array for empty input")
|
||||
test("type predicate narrows correctly")
|
||||
})
|
||||
|
||||
describe("PERMISSION_REPLY_RE", () => {
|
||||
test("matches 'y abcde'")
|
||||
test("matches 'yes abcde'")
|
||||
test("matches 'n abcde'")
|
||||
test("matches 'no abcde'")
|
||||
test("is case-insensitive")
|
||||
test("does not match without ID")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
`hashToId` 可能需要确认导出状态
|
||||
`filterPermissionRelayClients` 需要 mock 客户端类型
|
||||
`truncateForPreview` 可能依赖 `jsonStringify`（需 mock `slowOperations`）
|
||||
|
||||
---
|
||||
|
||||
## 5. `src/services/mcp/__tests__/officialRegistry.test.ts` (~12 tests)
|
||||
|
||||
**源文件**: `src/services/mcp/officialRegistry.ts` (73 行)
|
||||
**目标函数**: `normalizeUrl` (私有), `isOfficialMcpUrl`, `resetOfficialMcpUrlsForTesting`
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("normalizeUrl", () => {
|
||||
// 注意：如果是私有的，通过 isOfficialMcpUrl 间接测试
|
||||
test("removes trailing slash")
|
||||
test("removes query parameters")
|
||||
test("preserves path")
|
||||
test("handles URL with port")
|
||||
test("handles URL with hash fragment")
|
||||
})
|
||||
|
||||
describe("isOfficialMcpUrl", () => {
|
||||
test("returns false when registry not loaded (initial state)")
|
||||
test("returns true for URL added to registry")
|
||||
test("returns false for non-registered URL")
|
||||
test("uses normalized URL for comparison")
|
||||
})
|
||||
|
||||
describe("resetOfficialMcpUrlsForTesting", () => {
|
||||
test("clears the cached URLs")
|
||||
test("allows fresh start after reset")
|
||||
})
|
||||
|
||||
describe("URL normalization + lookup integration", () => {
|
||||
test("URL with trailing slash matches normalized version")
|
||||
test("URL with query params matches normalized version")
|
||||
test("different URLs do not match")
|
||||
test("case sensitivity check")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
需 mock `axios`（避免网络请求）
|
||||
使用 `resetOfficialMcpUrlsForTesting` 做测试隔离
|
||||
@@ -1,200 +0,0 @@
|
||||
# Phase 19 - Batch 5: MCP 配置 + modelCost
|
||||
|
||||
> 预计 ~80 tests / 4 文件 | 需中等 mock
|
||||
|
||||
---
|
||||
|
||||
## 1. `src/services/mcp/__tests__/configUtils.test.ts` (~30 tests)
|
||||
|
||||
**源文件**: `src/services/mcp/config.ts` (1580 行)
|
||||
**目标函数**: `unwrapCcrProxyUrl`, `urlPatternToRegex` (私有), `commandArraysMatch` (私有), `toggleMembership` (私有), `addScopeToServers` (私有), `dedupPluginMcpServers`, `getMcpServerSignature` (如导出)
|
||||
|
||||
### 测试策略
|
||||
私有函数如不可直接测试，通过公开的 `dedupPluginMcpServers` 间接覆盖。导出函数直接测。
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("unwrapCcrProxyUrl", () => {
|
||||
test("returns original URL when no CCR proxy markers")
|
||||
test("extracts mcp_url from CCR proxy URL with /v2/session_ingress/shttp/mcp/")
|
||||
test("extracts mcp_url from CCR proxy URL with /v2/ccr-sessions/")
|
||||
test("returns original URL when mcp_url param is missing")
|
||||
test("handles malformed URL gracefully")
|
||||
test("handles URL with both proxy marker and mcp_url")
|
||||
test("preserves non-CCR URLs unchanged")
|
||||
})
|
||||
|
||||
describe("dedupPluginMcpServers", () => {
|
||||
test("keeps unique plugin servers")
|
||||
test("suppresses plugin server duplicated by manual config")
|
||||
test("suppresses plugin server duplicated by earlier plugin")
|
||||
test("keeps servers with null signature")
|
||||
test("returns empty for empty inputs")
|
||||
test("reports suppressed with correct duplicateOf name")
|
||||
test("handles multiple plugins with same config")
|
||||
})
|
||||
|
||||
describe("toggleMembership (via integration)", () => {
|
||||
test("adds item when shouldContain=true and not present")
|
||||
test("removes item when shouldContain=false and present")
|
||||
test("returns same array when already in desired state")
|
||||
})
|
||||
|
||||
describe("addScopeToServers (via integration)", () => {
|
||||
test("adds scope to each server config")
|
||||
test("returns empty object for undefined input")
|
||||
test("returns empty object for empty input")
|
||||
test("preserves all original config properties")
|
||||
})
|
||||
|
||||
describe("urlPatternToRegex (via integration)", () => {
|
||||
test("matches exact URL")
|
||||
test("matches wildcard pattern *.example.com")
|
||||
test("matches multiple wildcards")
|
||||
test("does not match non-matching URL")
|
||||
test("escapes regex special characters in pattern")
|
||||
})
|
||||
|
||||
describe("commandArraysMatch (via integration)", () => {
|
||||
test("returns true for identical arrays")
|
||||
test("returns false for different lengths")
|
||||
test("returns false for same length different elements")
|
||||
test("returns true for empty arrays")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
需 mock `feature()` (bun:bundle), `jsonStringify`, `safeParseJSON`, `log` 等
|
||||
通过 `mock.module()` + `await import()` 解锁
|
||||
|
||||
---
|
||||
|
||||
## 2. `src/services/mcp/__tests__/filterUtils.test.ts` (~20 tests)
|
||||
|
||||
**源文件**: `src/services/mcp/utils.ts` (576 行)
|
||||
**目标函数**: `filterToolsByServer`, `hashMcpConfig`, `isToolFromMcpServer`, `isMcpTool`, `parseHeaders`
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("filterToolsByServer", () => {
|
||||
test("filters tools matching server name prefix")
|
||||
test("returns empty for no matching tools")
|
||||
test("handles empty tools array")
|
||||
test("normalizes server name for matching")
|
||||
})
|
||||
|
||||
describe("hashMcpConfig", () => {
|
||||
test("returns 16-char hex string")
|
||||
test("is deterministic")
|
||||
test("excludes scope from hash")
|
||||
test("different configs produce different hashes")
|
||||
test("key order does not affect hash (sorted)")
|
||||
})
|
||||
|
||||
describe("isToolFromMcpServer", () => {
|
||||
test("returns true when tool belongs to specified server")
|
||||
test("returns false for different server")
|
||||
test("returns false for non-MCP tool name")
|
||||
test("handles empty tool name")
|
||||
})
|
||||
|
||||
describe("isMcpTool", () => {
|
||||
test("returns true for tool name starting with 'mcp__'")
|
||||
test("returns true when tool.isMcp is true")
|
||||
test("returns false for regular tool")
|
||||
test("returns false when neither condition met")
|
||||
})
|
||||
|
||||
describe("parseHeaders", () => {
|
||||
test("parses 'Key: Value' format")
|
||||
test("parses multiple headers")
|
||||
test("trims whitespace around key and value")
|
||||
test("throws on missing colon")
|
||||
test("throws on empty key")
|
||||
test("handles value with colons (like URLs)")
|
||||
test("returns empty object for empty array")
|
||||
test("handles duplicate keys (last wins)")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
需 mock `normalizeNameForMCP`, `mcpInfoFromString`, `jsonStringify`, `createHash` 等
|
||||
`parseHeaders` 是最独立的，可能不需要太多 mock
|
||||
|
||||
---
|
||||
|
||||
## 3. `src/services/mcp/__tests__/channelNotification.test.ts` (~15 tests)
|
||||
|
||||
**源文件**: `src/services/mcp/channelNotification.ts` (317 行)
|
||||
**目标函数**: `wrapChannelMessage`, `findChannelEntry`
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("wrapChannelMessage", () => {
|
||||
test("wraps content in <channel> tag with source attribute")
|
||||
test("escapes server name in attribute")
|
||||
test("includes meta attributes when provided")
|
||||
test("escapes meta values via escapeXmlAttr")
|
||||
test("filters out meta keys not matching SAFE_META_KEY pattern")
|
||||
test("handles empty meta")
|
||||
test("handles content with special characters")
|
||||
test("formats with newlines between tags and content")
|
||||
})
|
||||
|
||||
describe("findChannelEntry", () => {
|
||||
test("finds server entry by exact name match")
|
||||
test("finds plugin entry by matching second segment")
|
||||
test("returns undefined for no match")
|
||||
test("handles empty channels array")
|
||||
test("handles server name without colon")
|
||||
test("handles 'plugin:name' format correctly")
|
||||
test("prefers exact match over partial match")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
需 mock `escapeXmlAttr`（来自 xml.ts，已有测试）或直接使用
|
||||
`CHANNEL_TAG` 常量需确认导出
|
||||
|
||||
---
|
||||
|
||||
## 4. `src/utils/__tests__/modelCost.test.ts` (~15 tests)
|
||||
|
||||
**源文件**: `src/utils/modelCost.ts` (232 行)
|
||||
**目标函数**: `formatModelPricing`, `COST_TIER_*` 常量
|
||||
|
||||
### 测试用例
|
||||
|
||||
```typescript
|
||||
describe("COST_TIER constants", () => {
|
||||
test("COST_TIER_3_15 has inputTokens=3, outputTokens=15")
|
||||
test("COST_TIER_15_75 has inputTokens=15, outputTokens=75")
|
||||
test("COST_TIER_5_25 has inputTokens=5, outputTokens=25")
|
||||
test("COST_TIER_30_150 has inputTokens=30, outputTokens=150")
|
||||
test("COST_HAIKU_35 has inputTokens=0.8, outputTokens=4")
|
||||
test("COST_HAIKU_45 has inputTokens=1, outputTokens=5")
|
||||
})
|
||||
|
||||
describe("formatModelPricing", () => {
|
||||
test("formats integer prices without decimals: '$3/$15 per Mtok'")
|
||||
test("formats float prices with 2 decimals: '$0.80/$4.00 per Mtok'")
|
||||
test("formats mixed: '$5/$25 per Mtok'")
|
||||
test("formats large prices: '$30/$150 per Mtok'")
|
||||
test("formats $1/$5 correctly (integer but small)")
|
||||
test("handles zero prices: '$0/$0 per Mtok'")
|
||||
})
|
||||
|
||||
describe("MODEL_COSTS", () => {
|
||||
test("maps known model names to cost tiers")
|
||||
test("contains entries for claude-sonnet-4-6")
|
||||
test("contains entries for claude-opus-4-6")
|
||||
test("contains entries for claude-haiku-4-5")
|
||||
})
|
||||
```
|
||||
|
||||
### Mock 需求
|
||||
需 mock `log`, `slowOperations` 等重依赖（modelCost.ts 通常 import 链较重）
|
||||
`formatModelPricing` 和 `COST_TIER_*` 是纯数据/纯函数，mock 成功后直接测
|
||||
@@ -1,296 +0,0 @@
|
||||
# Testing Specification
|
||||
|
||||
本文档定义 claude-code 项目的测试规范、当前覆盖状态和改进计划。
|
||||
|
||||
## 1. 技术栈
|
||||
|
||||
| 项 | 选型 |
|
||||
|----|------|
|
||||
| 测试框架 | `bun:test` |
|
||||
| 断言/Mock | `bun:test` 内置 |
|
||||
| 覆盖率 | `bun test --coverage` |
|
||||
| CI | GitHub Actions，push/PR 到 main 自动运行 |
|
||||
|
||||
## 2. 测试层次
|
||||
|
||||
本项目采用 **单元测试 + 集成测试** 两层结构，不做 E2E 或快照测试。
|
||||
|
||||
- **单元测试** — 纯函数、工具类、解析器。文件就近放置于 `src/**/__tests__/`。
|
||||
- **集成测试** — 多模块协作流程。集中于 `tests/integration/`。
|
||||
|
||||
## 3. 文件结构与命名
|
||||
|
||||
```
|
||||
src/
|
||||
├── utils/__tests__/ # 纯函数单元测试
|
||||
├── tools/<Tool>/__tests__/ # Tool 单元测试
|
||||
├── services/mcp/__tests__/ # MCP 单元测试
|
||||
├── utils/permissions/__tests__/
|
||||
├── utils/model/__tests__/
|
||||
├── utils/settings/__tests__/
|
||||
├── utils/shell/__tests__/
|
||||
├── utils/git/__tests__/
|
||||
└── __tests__/ # 顶层模块测试 (Tool.ts, tools.ts)
|
||||
tests/
|
||||
├── integration/ # 集成测试（尚未创建）
|
||||
├── mocks/ # 共享 mock/fixture（尚未创建）
|
||||
└── helpers/ # 测试辅助函数
|
||||
```
|
||||
|
||||
- 测试文件：`<module>.test.ts`
|
||||
- 命名风格：`describe("functionName")` + `test("行为描述")`，英文
|
||||
- 编写原则：Arrange-Act-Assert、单一职责、独立性、边界覆盖
|
||||
|
||||
## 4. 当前覆盖状态
|
||||
|
||||
> 更新日期：2026-04-02 | **1623 tests, 84 files, 0 fail, 851ms**
|
||||
|
||||
### 4.1 可靠度评分
|
||||
|
||||
每个测试文件按断言深度、边界覆盖、mock 质量、测试独立性综合评定：
|
||||
|
||||
| 等级 | 含义 |
|
||||
|------|------|
|
||||
| **GOOD** | 断言精确（exact match），边界充分，结构清晰 |
|
||||
| **ACCEPTABLE** | 正常路径覆盖完整，部分边界或断言可加强 |
|
||||
| **WEAK** | 存在明显缺陷：断言过弱、重要边界缺失、或有脆弱性风险 |
|
||||
|
||||
### 4.2 按模块分布
|
||||
|
||||
#### P0 — 核心模块
|
||||
|
||||
| 文件 | Tests | 评分 | 覆盖范围 | 主要不足 |
|
||||
|------|-------|------|----------|----------|
|
||||
| `src/__tests__/Tool.test.ts` | 20 | GOOD | buildTool, toolMatchesName, findToolByName, filterToolProgressMessages | — |
|
||||
| `src/__tests__/tools.test.ts` | 9 | ACCEPTABLE | parseToolPreset, filterToolsByDenyRules | 预设覆盖仅测 "default"；有冗余用例 |
|
||||
| `src/tools/FileEditTool/__tests__/utils.test.ts` | 22 | ACCEPTABLE | normalizeQuotes, applyEditToFile, preserveQuoteStyle | `findActualString` 断言过弱（`not.toBeNull`）；`preserveQuoteStyle` 仅 2 用例 |
|
||||
| `src/tools/shared/__tests__/gitOperationTracking.test.ts` | 20 | ACCEPTABLE | parseGitCommitId, detectGitOperation | 6 个 GH PR action 全覆盖；缺 `trackGitOperations` 测试（需 mock analytics） |
|
||||
| `src/tools/BashTool/__tests__/destructiveCommandWarning.test.ts` | 21 | ACCEPTABLE | git/rm/SQL/k8s/terraform 危险模式 | safe commands 4 断言合一；缺少 `rm -rf /`、`DROP DATABASE`、管道命令 |
|
||||
| `src/tools/BashTool/__tests__/commandSemantics.test.ts` | 10 | ACCEPTABLE | grep/diff/test/rg/find 退出码语义 | mock `splitCommand_DEPRECATED` 与实现可能分歧；覆盖可更全面 |
|
||||
|
||||
**Utils 纯函数（19 文件）：**
|
||||
|
||||
| 文件 | Tests | 评分 | 覆盖范围 | 主要不足 |
|
||||
|------|-------|------|----------|----------|
|
||||
| `utils/__tests__/array.test.ts` | 12 | GOOD | intersperse, count, uniq | — |
|
||||
| `utils/__tests__/set.test.ts` | 11 | GOOD | difference, intersects, every, union | — |
|
||||
| `utils/__tests__/xml.test.ts` | 9 | GOOD | escapeXml, escapeXmlAttr | 缺 null/undefined 输入测试 |
|
||||
| `utils/__tests__/hash.test.ts` | 12 | ACCEPTABLE | djb2Hash, hashContent, hashPair | `hashContent`/`hashPair` 无已知答案断言（仅测确定性） |
|
||||
| `utils/__tests__/stringUtils.test.ts` | 30 | GOOD | 10 个函数全覆盖，含 Unicode 边界 | — |
|
||||
| `utils/__tests__/semver.test.ts` | 16 | ACCEPTABLE | gt/gte/lt/lte/satisfies/order | 缺 pre-release、tilde range、畸形版本串 |
|
||||
| `utils/__tests__/uuid.test.ts` | 6 | ACCEPTABLE | validateUuid | 大写测试仅 `not.toBeNull`，未验证标准化输出 |
|
||||
| `utils/__tests__/format.test.ts` | 27 | GOOD | formatFileSize, formatDuration, formatNumber, formatTokens, formatRelativeTime | 全部 `toBe` 精确匹配，含 billions/weeks/days 边界 |
|
||||
| `utils/__tests__/frontmatterParser.test.ts` | 22 | GOOD | parseFrontmatter, splitPathInFrontmatter, parsePositiveIntFromFrontmatter | — |
|
||||
| `utils/__tests__/file.test.ts` | 13 | ACCEPTABLE | convertLeadingTabsToSpaces, addLineNumbers, stripLineNumberPrefix | `addLineNumbers` 仅 `toContain`；缺 Windows 路径分隔符测试 |
|
||||
| `utils/__tests__/glob.test.ts` | 6 | ACCEPTABLE | extractGlobBaseDirectory | 缺绝对路径、根 `/`、Windows 路径 |
|
||||
| `utils/__tests__/diff.test.ts` | 8 | ACCEPTABLE | adjustHunkLineNumbers, getPatchFromContents | `getPatchFromContents` 仅检查结构，未验证 diff 内容正确性 |
|
||||
| `utils/__tests__/json.test.ts` | 15 | GOOD | safeParseJSON, parseJSONL, addItemToJSONCArray | — |
|
||||
| `utils/__tests__/truncate.test.ts` | 18 | ACCEPTABLE | truncateToWidth, wrapText, truncatePathMiddle | **缺 CJK/emoji/wide-char 测试**（这是宽度感知实现的核心场景） |
|
||||
| `utils/__tests__/path.test.ts` | 15 | ACCEPTABLE | containsPathTraversal, normalizePathForConfigKey | 仅覆盖 2/5+ 导出函数 |
|
||||
| `utils/__tests__/tokens.test.ts` | 18 | GOOD | getTokenCountFromUsage, doesMostRecentAssistantMessageExceed200k 等 | — |
|
||||
| `utils/__tests__/stream.test.ts` | 15 | GOOD | Stream\<T\> enqueue/read/drain/next/done/error/for-await | — |
|
||||
| `utils/__tests__/abortController.test.ts` | 13 | GOOD | createAbortController/createChildAbortController 父子传播 | — |
|
||||
| `utils/__tests__/bufferedWriter.test.ts` | 10 | GOOD | createBufferedWriter 立即/缓冲/flush/overflow | — |
|
||||
| `utils/__tests__/gitDiff.test.ts` | 25 | GOOD | parseGitNumstat/parseGitDiff/parseShortstat 纯解析 | — |
|
||||
| `utils/__tests__/sliceAnsi.test.ts` | 13 | GOOD | sliceAnsi ANSI 感知切片 + undoAnsiCodes | — |
|
||||
| `utils/__tests__/treeify.test.ts` | 13 | ACCEPTABLE | treeify 扁平/嵌套/循环引用 | 缺深度嵌套性能测试 |
|
||||
| `utils/__tests__/words.test.ts` | 11 | GOOD | slug 格式 (adjective-verb-noun)、唯一性 | — |
|
||||
|
||||
**Context 构建（3 文件）：**
|
||||
|
||||
| 文件 | Tests | 评分 | 覆盖范围 | 主要不足 |
|
||||
|------|-------|------|----------|----------|
|
||||
| `utils/__tests__/claudemd.test.ts` | 14 | ACCEPTABLE | stripHtmlComments, isMemoryFilePath, getLargeMemoryFiles | **仅测 3 个辅助函数**，核心发现/加载/`@include` 指令/memoization 未覆盖 |
|
||||
| `utils/__tests__/systemPrompt.test.ts` | 8 | GOOD | buildEffectiveSystemPrompt | — |
|
||||
| `__tests__/history.test.ts` | 26 | GOOD | parseReferences/expandPastedTextRefs/formatPastedTextRef 等 5 个函数 | — |
|
||||
|
||||
#### P1 — 重要模块
|
||||
|
||||
| 文件 | Tests | 评分 | 覆盖范围 | 主要不足 |
|
||||
|------|-------|------|----------|----------|
|
||||
| `permissions/__tests__/permissionRuleParser.test.ts` | 16 | GOOD | escape/unescape 规则，roundtrip 完整性 | — |
|
||||
| `permissions/__tests__/permissions.test.ts` | 12 | ACCEPTABLE | getDenyRuleForTool, getAskRuleForTool, filterDeniedAgents | `as any` cast；缺 MCP tool deny 测试 |
|
||||
| `permissions/__tests__/shellRuleMatching.test.ts` | 19 | GOOD | 通配符、转义、正则特殊字符 | — |
|
||||
| `permissions/__tests__/PermissionMode.test.ts` | 22 | ACCEPTABLE | permissionModeFromString, isExternalPermissionMode 等 | isExternalPermissionMode ant false 路径已覆盖；缺 `bubble` 模式独立测试 |
|
||||
| `permissions/__tests__/dangerousPatterns.test.ts` | 7 | WEAK | CROSS_PLATFORM_CODE_EXEC, DANGEROUS_BASH_PATTERNS | 纯数据 smoke test，无行为测试；不验证数组无重复 |
|
||||
| `model/__tests__/aliases.test.ts` | 15 | ACCEPTABLE | isModelAlias, isModelFamilyAlias | 缺 null/undefined/空串输入 |
|
||||
| `model/__tests__/model.test.ts` | 13 | ACCEPTABLE | firstPartyNameToCanonical | 缺空串、非标准日期后缀 |
|
||||
| `model/__tests__/providers.test.ts` | 9 | ACCEPTABLE | getAPIProvider, isFirstPartyAnthropicBaseUrl | `originalEnv` 声明未使用；env 恢复不完整 |
|
||||
| `utils/__tests__/messages.test.ts` | 36 | GOOD | createAssistantMessage, createUserMessage, extractTag 等 16 个 describe | `normalizeMessages` 仅检查长度未验证内容 |
|
||||
|
||||
**Tool 子模块（8 文件）：**
|
||||
|
||||
| 文件 | Tests | 评分 | 覆盖范围 | 主要不足 |
|
||||
|------|-------|------|----------|----------|
|
||||
| `tools/PowerShellTool/__tests__/powershellSecurity.test.ts` | 24 | GOOD | AST 安全检测：Invoke-Expression/iex/encoded/dynamic/download/COM | — |
|
||||
| `tools/PowerShellTool/__tests__/commandSemantics.test.ts` | 21 | GOOD | grep/rg/findstr/robocopy 退出码、pipeline last-segment | — |
|
||||
| `tools/PowerShellTool/__tests__/destructiveCommandWarning.test.ts` | 38 | GOOD | Remove-Item/Format-Volume/Clear-Disk/git/SQL/COMPUTER/alias 全覆盖 | — |
|
||||
| `tools/PowerShellTool/__tests__/gitSafety.test.ts` | 29 | GOOD | .git 路径检测/NTFS 短名/反斜杠/引号/反引号转义 | — |
|
||||
| `tools/LSPTool/__tests__/formatters.test.ts` | 18 | GOOD | 全部 8 个 format 函数 null/empty/valid 输入 | — |
|
||||
| `tools/LSPTool/__tests__/schemas.test.ts` | 13 | GOOD | isValidLSPOperation 类型守卫 9 种操作 + 无效/空/大小写 | — |
|
||||
| `tools/WebFetchTool/__tests__/preapproved.test.ts` | 18 | GOOD | isPreapprovedHost 精确/路径作用域/子路径/大小写/子域名 | — |
|
||||
| `tools/WebFetchTool/__tests__/urlValidation.test.ts` | 18 | GOOD | validateURL/isPermittedRedirect 本地重实现（避免重依赖链） | — |
|
||||
|
||||
#### P2 — 补充模块
|
||||
|
||||
| 文件 | Tests | 评分 | 覆盖范围 | 主要不足 |
|
||||
|------|-------|------|----------|----------|
|
||||
| `utils/__tests__/cron.test.ts` | 31 | GOOD | parseCronExpression, computeNextCronRun, cronToHuman | 缺月边界、闰年 |
|
||||
| `utils/__tests__/git.test.ts` | 15 | ACCEPTABLE | normalizeGitRemoteUrl (SSH/HTTPS/ssh://) | 缺 git://、file://、端口号 |
|
||||
| `settings/__tests__/config.test.ts` | 38 | GOOD | SettingsSchema, type guards, validateSettingsFileContent, formatZodError | 缺 DeniedMcpServerEntrySchema |
|
||||
|
||||
#### P3-P6 — 扩展覆盖（27 文件）
|
||||
|
||||
| 文件 | Tests | 评分 | 备注 |
|
||||
|------|-------|------|------|
|
||||
| `utils/__tests__/errors.test.ts` | 33 | GOOD | — |
|
||||
| `utils/__tests__/envUtils.test.ts` | 33 | GOOD | env 保存/恢复规范 |
|
||||
| `utils/__tests__/effort.test.ts` | 30 | GOOD | 5 个 mock 模块，边界完整 |
|
||||
| `utils/__tests__/argumentSubstitution.test.ts` | 22 | ACCEPTABLE | 缺转义引号、越界索引 |
|
||||
| `utils/__tests__/sanitization.test.ts` | 14 | ACCEPTABLE | — |
|
||||
| `utils/__tests__/sleep.test.ts` | 14 | GOOD | 时间相关测试，margin 充足 |
|
||||
| `utils/__tests__/CircularBuffer.test.ts` | 11 | ACCEPTABLE | 缺 capacity=1、空 buffer getRecent |
|
||||
| `utils/__tests__/memoize.test.ts` | 18 | GOOD | 缓存 hit/stale/LRU 全覆盖 |
|
||||
| `utils/__tests__/tokenBudget.test.ts` | 21 | GOOD | — |
|
||||
| `utils/__tests__/displayTags.test.ts` | 17 | GOOD | — |
|
||||
| `utils/__tests__/taggedId.test.ts` | 10 | GOOD | — |
|
||||
| `utils/__tests__/controlMessageCompat.test.ts` | 15 | GOOD | — |
|
||||
| `utils/__tests__/gitConfigParser.test.ts` | 21 | GOOD | — |
|
||||
| `utils/__tests__/windowsPaths.test.ts` | 19 | GOOD | 双向 round-trip 测试 |
|
||||
| `utils/__tests__/envExpansion.test.ts` | 15 | GOOD | — |
|
||||
| `utils/__tests__/formatBriefTimestamp.test.ts` | 10 | GOOD | 固定 now 时间戳，确定性 |
|
||||
| `utils/__tests__/notebook.test.ts` | 9 | ACCEPTABLE | 合并断言偏弱 |
|
||||
| `utils/__tests__/hyperlink.test.ts` | 10 | ACCEPTABLE | 空串测试行为注释混乱 |
|
||||
| `utils/__tests__/zodToJsonSchema.test.ts` | 9 | WEAK | **object 属性仅 `toBeDefined` 未验证类型**；optional 字段未验证 absence |
|
||||
| `utils/__tests__/objectGroupBy.test.ts` | 5 | ACCEPTABLE | 极简，缺 undefined key 测试 |
|
||||
| `utils/__tests__/contentArray.test.ts` | 6 | ACCEPTABLE | 缺混合 tool_result+text 交替 |
|
||||
| `utils/__tests__/slashCommandParsing.test.ts` | 8 | GOOD | — |
|
||||
| `utils/__tests__/groupToolUses.test.ts` | 10 | GOOD | — |
|
||||
| `utils/__tests__/shell/__tests__/outputLimits.test.ts` | 7 | ACCEPTABLE | — |
|
||||
| `utils/__tests__/envValidation.test.ts` | 12 | GOOD | validateBoundedIntEnvVar | value=1 无下界确认为设计意图（函数仅校验 >0 和 <=upperLimit） |
|
||||
| `utils/git/__tests__/gitConfigParser.test.ts` | 20 | GOOD | — |
|
||||
| `services/mcp/__tests__/mcpStringUtils.test.ts` | 16 | GOOD | — |
|
||||
| `services/mcp/__tests__/normalization.test.ts` | 10 | GOOD | — |
|
||||
|
||||
### 4.3 评分汇总
|
||||
|
||||
| 等级 | 文件数 | 占比 |
|
||||
|------|--------|------|
|
||||
| **GOOD** | 46 | 55% |
|
||||
| **ACCEPTABLE** | 32 | 38% |
|
||||
| **WEAK** | 6 | 7% |
|
||||
|
||||
## 5. 系统性问题
|
||||
|
||||
### 5.1 断言过弱（Smell: `toContain` 代替精确匹配）
|
||||
|
||||
以下文件的部分测试使用 `toContain` 或 `not.toBeNull` 检查结果，当实现返回包含目标子串的任何字符串时测试仍通过，无法检测格式错误：
|
||||
|
||||
| 文件 | 受影响函数 | 建议 |
|
||||
|------|-----------|------|
|
||||
| `file.test.ts` | addLineNumbers | 断言完整输出格式 |
|
||||
| `diff.test.ts` | getPatchFromContents | 验证 hunk 内容正确性 |
|
||||
| `notebook.test.ts` | mapNotebookCellsToToolResult | 验证合并后内容 |
|
||||
| `uuid.test.ts` | validateUuid (uppercase) | 断言标准化后的精确值 |
|
||||
|
||||
### 5.2 集成测试空白
|
||||
|
||||
Spec 定义的三个集成测试均未创建：
|
||||
|
||||
| 计划 | 状态 | 依赖 |
|
||||
|------|------|------|
|
||||
| `tests/integration/tool-chain.test.ts` | 未创建 | 需 mock tools.ts 完整注册链 |
|
||||
| `tests/integration/context-build.test.ts` | 未创建 | 需 mock context.ts 重依赖链 |
|
||||
| `tests/integration/message-pipeline.test.ts` | 未创建 | 需 mock API 层 |
|
||||
|
||||
`tests/mocks/` 目录也不存在，无共享 mock/fixture 基础设施。
|
||||
|
||||
### 5.3 Mock 相关
|
||||
|
||||
| 问题 | 影响文件 | 说明 |
|
||||
|------|----------|------|
|
||||
| 未 mock 重依赖 | `gitOperationTracking.test.ts` | `trackGitOperations` 调用 analytics/bootstrap，测试仅覆盖 `detectGitOperation`（无副作用） |
|
||||
| env 恢复不完整 | `providers.test.ts` | 仅删除已知 key，新增 env var 会导致测试泄漏 |
|
||||
|
||||
### 5.4 潜在 Bug
|
||||
|
||||
| 文件 | 函数 | 问题 |
|
||||
|------|------|------|
|
||||
| ~~`envValidation.test.ts`~~ | ~~validateBoundedIntEnvVar~~ | ~~value=1 无下界检查~~ — **已确认**：函数仅校验 `parsed > 0` 和 `parsed <= upperLimit`，不强制 `parsed >= defaultValue`，为设计意图 |
|
||||
|
||||
### 5.5 已知限制
|
||||
|
||||
| 模块 | 问题 |
|
||||
|------|------|
|
||||
| `Bun.JSONL.parseChunk` | 畸形行时无限挂起（Bun 1.3.10 bug） |
|
||||
| `context.ts` 核心逻辑 | 依赖 bootstrap/state + git + 50+ 模块，mock 不可行 |
|
||||
| `tools.ts` (getAllBaseTools) | 导入链过重 |
|
||||
| `spawnMultiAgent.ts` | 50+ 依赖 |
|
||||
| `messages.ts` 部分函数 | 依赖 `getFeatureValue_CACHED_MAY_BE_STALE` |
|
||||
| UI 组件 (`screens/`, `components/`) | 需 Ink 渲染测试环境 |
|
||||
|
||||
### 5.6 Mock 模式
|
||||
|
||||
通过 `mock.module()` + `await import()` 解锁重依赖模块：
|
||||
|
||||
| 被 Mock 模块 | 解锁的测试 |
|
||||
|-------------|-----------|
|
||||
| `src/utils/log.ts` | json, tokens, FileEditTool/utils, permissions, memoize, PermissionMode |
|
||||
| `src/services/tokenEstimation.ts` | tokens |
|
||||
| `src/utils/slowOperations.ts` | tokens, permissions, memoize, PermissionMode |
|
||||
| `src/utils/debug.ts` | envValidation, outputLimits |
|
||||
| `src/utils/bash/commands.ts` | commandSemantics |
|
||||
| `src/utils/thinking.js` | effort |
|
||||
| `src/utils/settings/settings.js` | effort |
|
||||
| `src/utils/auth.js` | effort |
|
||||
| `src/services/analytics/growthbook.js` | effort, tokenBudget |
|
||||
| `src/utils/powershell/dangerousCmdlets.js` | powershellSecurity |
|
||||
| `src/utils/cwd.js` | gitSafety |
|
||||
| `src/utils/powershell/parser.js` | gitSafety |
|
||||
| `src/utils/stringUtils.js` | LSP formatters |
|
||||
| `figures` | treeify |
|
||||
|
||||
**约束**：`mock.module()` 必须在每个测试文件内联调用，不能从共享 helper 导入。
|
||||
|
||||
## 6. 完成状态
|
||||
|
||||
> 更新日期：2026-04-02 | **1623 tests, 84 files, 0 fail, 851ms**
|
||||
|
||||
### 已完成
|
||||
|
||||
| 计划 | 状态 | 新增测试 | 说明 |
|
||||
|------|------|---------|------|
|
||||
| Plan 12 — Mock 可靠性 | **已完成** | +9 | PermissionMode ant false 路径、providers env 快照恢复 |
|
||||
| Plan 10 — WEAK 修复 | **已完成** | +15 | format 断言精确化、envValidation 修正、zodToJsonSchema/destructors/notebook 加固 |
|
||||
| Plan 13 — CJK/Emoji | **已完成** | +17 | truncate CJK/emoji 宽度感知测试 |
|
||||
| Plan 11 — ACCEPTABLE 加强 | **已完成** | +62 | diff/uuid/hash/semver/path/claudemd/fileEdit/providers/messages 等 15 文件 |
|
||||
| Plan 14 — 集成测试 | **已完成** | +43 | 搭建 tests/mocks/ + tool-chain/context-build/message-pipeline/cli-arguments |
|
||||
| Plan 15 — CLI + 覆盖率 | **已完成** | +11 | Commander.js 参数解析、覆盖率基线 |
|
||||
| Phase 16 — 零依赖纯函数 | **已完成** | +126 | stream/abortController/bufferedWriter/gitDiff/history/sliceAnsi/treeify/words 8 文件 |
|
||||
| Phase 17 — 工具子模块 | **已完成** | +179 | PowerShell 安全/语义/破坏性/gitSafety + LSP 格式化/schema + WebFetch 预批准/URL 8 文件 |
|
||||
| Phase 18 — WEAK 修复 | **已完成** | +20 | format 精确匹配、envValidation 边界、PermissionMode 补强、gitOperationTracking PR actions |
|
||||
|
||||
### 覆盖率基线
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| 总测试数 | 1623 |
|
||||
| 测试文件数 | 84 |
|
||||
| 失败数 | 0 |
|
||||
| 断言数 | 2516 |
|
||||
| 运行耗时 | ~851ms |
|
||||
| Tool.ts 行覆盖率 | 100% |
|
||||
| 整体行覆盖率 | ~33%（Bun coverage 限制：`mock.module` 模式下的模块不报告） |
|
||||
|
||||
> **注意**：Bun `--coverage` 仅报告测试 import 链中直接加载的文件。使用 `mock.module()` + `await import()` 模式的源文件（大多数 `src/utils/` 纯函数）不显示在覆盖率报告中。实际测试覆盖率高于报告值。
|
||||
|
||||
### 不纳入计划
|
||||
|
||||
| 模块 | 原因 |
|
||||
|------|------|
|
||||
| `query.ts` / `QueryEngine.ts` | 核心循环，需完整集成环境 |
|
||||
| `services/api/claude.ts` | 需 mock SDK 流式响应 |
|
||||
| `spawnMultiAgent.ts` | 50+ 依赖 |
|
||||
| `modelCost.ts` | 依赖 bootstrap/state + analytics |
|
||||
| `mcp/dateTimeParser.ts` | 调用 Haiku API |
|
||||
| `screens/` / `components/` | 需 Ink 渲染测试 |
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user