Skip to content

Commit ce2f19c

Browse files
claude-code-bestclaude-code-best
authored
Merge pull request #5 from claude-code-best/feature/prod
docs: mintlify 文档撰写
2 parents c57f5a2 + f6fe944 commit ce2f19c

27 files changed

+1542
-0
lines changed

‎docs/agent/coordinator-and-swarm.mdx‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
title: "协调者与蜂群"
3+
description: "从单兵作战到团队协作——多 Agent 的高级编排模式"
4+
---
5+
6+
{/* 本章目标：介绍 Coordinator Mode 和 Agent Swarms */}
7+
8+
## 两种协作模式
9+
10+
子 Agent 是"临时帮手"——主 Agent 派出去做一件事就回来。对于更复杂的协作需求，Claude Code 提供了两种高级模式：
11+
12+
## Coordinator Mode：一个指挥，多个执行
13+
14+
就像一个团队 leader 带着几个开发者：
15+
16+
- **Coordinator**（协调者）：负责理解需求、拆解任务、分配工作、汇总结果
17+
- **Workers**（执行者）：各自领取任务独立执行，通过邮箱向 Coordinator 汇报
18+
19+
```
20+
┌─── Worker A (重构 API)
21+
│
22+
Coordinator ──┼─── Worker B (更新测试)
23+
│
24+
└─── Worker C (更新文档)
25+
```
26+
27+
Coordinator 不自己写代码，它的职责是**编排**——确保所有 Worker 的工作能拼合在一起。
28+
29+
## Agent Swarms：蜂群式协作
30+
31+
比 Coordinator 更松散的协作模式：
32+
33+
- 多个 Agent 以对等身份同时工作
34+
- 没有中心化的指挥者
35+
- 通过消息邮箱互相通信和协调
36+
- 适合"各自负责一块、偶尔需要沟通"的场景
37+
38+
## Teammate 机制
39+
40+
进程内的"队友"——一种更轻量的协作方式：
41+
42+
- 在同一个进程内运行，共享部分基础设施状态
43+
- 有独立的对话上下文和工具权限
44+
- 适合"我需要一个搭档帮忙看看这段代码"的场景
45+
46+
## 任务类型
47+
48+
支撑多 Agent 协作的是丰富的任务类型：
49+
50+
| 任务类型 | 用途 |
51+
|----------|------|
52+
| **LocalAgentTask** | 本地子 Agent 任务 |
53+
| **LocalShellTask** | 后台 shell 命令 |
54+
| **InProcessTeammateTask** | 进程内队友 |
55+
| **RemoteAgentTask** | 远程 Agent |
56+
| **DreamTask** | 后台自主任务 |
57+
58+
每种任务类型都有自己的生命周期管理、状态追踪和通信方式。

‎docs/agent/sub-agents.mdx‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
title: "子 Agent：分身术"
3+
description: "当一个 AI 不够用时，它会召唤更多的自己"
4+
---
5+
6+
{/* 本章目标：解释子 Agent 机制的设计和应用场景 */}
7+
8+
## 为什么需要子 Agent
9+
10+
有些任务太大，一个 AI 实例忙不过来：
11+
12+
- "在 5 个不同的文件中分别找到并修复同类 bug"
13+
- "一边重构后端 API，一边更新前端调用"
14+
- "研究这个库的用法，同时修改我们的代码"
15+
16+
## 分身术的运作方式
17+
18+
Claude Code 中的 Agent 工具让 AI 能够**启动另一个 AI 实例**来处理子任务：
19+
20+
<Steps>
21+
<Step title="主 Agent 分析任务">
22+
主 Agent 判断任务可以被拆解为独立的子任务
23+
</Step>
24+
<Step title="启动子 Agent">
25+
通过 Agent 工具创建一个或多个子 Agent，每个子 Agent 收到一个清晰的子任务描述
26+
</Step>
27+
<Step title="并行执行">
28+
多个子 Agent 可以同时工作，互不干扰
29+
</Step>
30+
<Step title="结果汇总">
31+
子 Agent 完成后，结果返回给主 Agent，主 Agent 汇总并呈现给用户
32+
</Step>
33+
</Steps>
34+
35+
## 子 Agent 的边界
36+
37+
子 Agent 不是和主 Agent 完全一样的——它有明确的能力边界：
38+
39+
| 特性 | 主 Agent | 子 Agent |
40+
|------|---------|---------|
41+
| 可用工具 | 全部工具 | 受限子集（不能再启动子 Agent 等） |
42+
| 上下文 | 完整的会话历史 | 只有主 Agent 给的任务描述 |
43+
| 权限 | 用户设定 | 继承主 Agent 的权限，或更严格 |
44+
| 状态 | 可修改全局状态 | 隔离的状态空间 |
45+
46+
## 通信方式
47+
48+
主 Agent 和子 Agent 之间通过**消息邮箱**通信：
49+
50+
- 主 Agent 通过 `Agent` 工具启动子 Agent
51+
- 子 Agent 通过 `SendMessage` 工具向主 Agent 报告进度
52+
- 这种松耦合的通信方式让 Agent 可以异步协作
53+
54+
## 适用场景
55+
56+
<CardGroup cols={2}>
57+
<Card title="并行研究" icon="magnifying-glass">
58+
多个子 Agent 同时搜索不同方向的信息
59+
</Card>
60+
<Card title="分治修改" icon="code-branch">
61+
把大规模修改拆分到多个子 Agent 并行执行
62+
</Card>
63+
<Card title="前后台配合" icon="layer-group">
64+
一个子 Agent 在后台运行测试，主 Agent 继续写代码
65+
</Card>
66+
<Card title="隔离实验" icon="flask">
67+
在 worktree 中启动子 Agent 尝试一个方案，不影响主分支
68+
</Card>
69+
</CardGroup>

‎docs/agent/worktree-isolation.mdx‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
title: "Worktree 隔离"
3+
description: "给子 Agent 一个独立的工作空间，互不污染"
4+
---
5+
6+
{/* 本章目标：解释 git worktree 在多 Agent 协作中的作用 */}
7+
8+
## 问题：多个 Agent 改同一份代码
9+
10+
当多个 Agent 同时修改项目文件时，冲突在所难免：
11+
12+
- Agent A 修改了 `config.ts`，Agent B 也在改同一个文件
13+
- Agent A 的测试需要某个状态，Agent B 的修改破坏了它
14+
- 半完成的修改混在一起，无法分辨哪些是哪个 Agent 做的
15+
16+
## 解决方案：Git Worktree
17+
18+
Git 原生支持 **worktree**（工作树）——在同一个仓库中创建多个独立的工作目录，每个目录在自己的分支上独立工作。
19+
20+
Claude Code 利用这个特性为子 Agent 提供隔离的工作空间：
21+
22+
| | 共享工作目录 | Worktree 隔离 |
23+
|---|---|---|
24+
| 文件冲突 | 多个 Agent 可能互相覆盖 | 每个 Agent 在自己的目录中工作 |
25+
| 分支 | 都在同一个分支上 | 每个 Agent 有自己的分支 |
26+
| 测试 | 互相干扰 | 完全独立 |
27+
| 合并 | 需要手动处理冲突 | 通过 git merge 有序合并 |
28+
29+
## 工作流程
30+
31+
<Steps>
32+
<Step title="创建 Worktree">
33+
AI 启动带隔离模式的子 Agent，系统自动在 `.claude/worktrees/` 下创建新的工作目录
34+
</Step>
35+
<Step title="独立工作">
36+
子 Agent 在自己的 worktree 中自由修改文件、执行命令
37+
</Step>
38+
<Step title="完成任务">
39+
子 Agent 完成后，变更留在 worktree 的分支上
40+
</Step>
41+
<Step title="合并或丢弃">
42+
主 Agent（或用户）决定：合并这些变更到主分支，还是丢弃
43+
</Step>
44+
<Step title="清理">
45+
不再需要的 worktree 会被自动清理
46+
</Step>
47+
</Steps>
48+
49+
## 安全网
50+
51+
Worktree 还充当了一个安全网：
52+
53+
- 子 Agent 的实验性修改不会影响主分支
54+
- 如果方案不可行，整个 worktree 可以直接丢弃
55+
- 多个方案可以在不同 worktree 中并行尝试，最后选最好的

‎docs/context/compaction.mdx‎

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

‎docs/context/project-memory.mdx‎

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

‎docs/context/system-prompt.mdx‎

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

0 commit comments

Comments
 (0)