mirror of
https://github.com/shareAI-lab/learn-claude-code.git
synced 2026-04-28 06:19:32 +00:00
commit
e4edd82c8c
15 changed files with 112 additions and 112 deletions
38
README-zh.md
38
README-zh.md
|
|
@ -162,13 +162,13 @@ Claude Code = 一个 agent loop
|
||||||
**12 个递进式课程, 从简单循环到隔离化的自治执行。**
|
**12 个递进式课程, 从简单循环到隔离化的自治执行。**
|
||||||
**每个课程添加一个 harness 机制。每个机制有一句格言。**
|
**每个课程添加一个 harness 机制。每个机制有一句格言。**
|
||||||
|
|
||||||
> **s01** *"One loop & Bash is all you need"* — 一个工具 + 一个循环 = 一个智能体
|
> **s01** *"One loop & Bash is all you need"* — 一个工具 + 一个循环 = 一个 Agent
|
||||||
>
|
>
|
||||||
> **s02** *"加一个工具, 只加一个 handler"* — 循环不用动, 新工具注册进 dispatch map 就行
|
> **s02** *"加一个工具, 只加一个 handler"* — 循环不用动, 新工具注册进 dispatch map 就行
|
||||||
>
|
>
|
||||||
> **s03** *"没有计划的 agent 走哪算哪"* — 先列步骤再动手, 完成率翻倍
|
> **s03** *"没有计划的 agent 走哪算哪"* — 先列步骤再动手, 完成率翻倍
|
||||||
>
|
>
|
||||||
> **s04** *"大任务拆小, 每个小任务干净的上下文"* — 子智能体用独立 messages[], 不污染主对话
|
> **s04** *"大任务拆小, 每个小任务干净的上下文"* — Subagent 用独立 messages[], 不污染主对话
|
||||||
>
|
>
|
||||||
> **s05** *"用到什么知识, 临时加载什么知识"* — 通过 tool_result 注入, 不塞 system prompt
|
> **s05** *"用到什么知识, 临时加载什么知识"* — 通过 tool_result 注入, 不塞 system prompt
|
||||||
>
|
>
|
||||||
|
|
@ -256,31 +256,31 @@ cd web && npm install && npm run dev # http://localhost:3000
|
||||||
```
|
```
|
||||||
第一阶段: 循环 第二阶段: 规划与知识
|
第一阶段: 循环 第二阶段: 规划与知识
|
||||||
================== ==============================
|
================== ==============================
|
||||||
s01 Agent 循环 [1] s03 TodoWrite [5]
|
s01 Agent Loop [1] s03 TodoWrite [5]
|
||||||
while + stop_reason TodoManager + nag 提醒
|
while + stop_reason TodoManager + nag 提醒
|
||||||
| |
|
| |
|
||||||
+-> s02 Tool Use [4] s04 子智能体 [5]
|
+-> s02 Tool Use [4] s04 Subagent [5]
|
||||||
dispatch map: name->handler 每个子智能体独立 messages[]
|
dispatch map: name->handler 每个 Subagent 独立 messages[]
|
||||||
|
|
|
|
||||||
s05 Skills [5]
|
s05 Skills [5]
|
||||||
SKILL.md 通过 tool_result 注入
|
SKILL.md 通过 tool_result 注入
|
||||||
|
|
|
|
||||||
s06 Context Compact [5]
|
s06 Context Compact [5]
|
||||||
三层上下文压缩
|
三层 Context Compact
|
||||||
|
|
||||||
第三阶段: 持久化 第四阶段: 团队
|
第三阶段: 持久化 第四阶段: 团队
|
||||||
================== =====================
|
================== =====================
|
||||||
s07 任务系统 [8] s09 智能体团队 [9]
|
s07 Task System [8] s09 Agent Teams [9]
|
||||||
文件持久化 CRUD + 依赖图 队友 + JSONL 邮箱
|
文件持久化 CRUD + 依赖图 队友 + JSONL 邮箱
|
||||||
| |
|
| |
|
||||||
s08 后台任务 [6] s10 团队协议 [12]
|
s08 Background Tasks [6] s10 Team Protocols [12]
|
||||||
守护线程 + 通知队列 关机 + 计划审批 FSM
|
守护线程 + 通知队列 关机 + 计划审批 FSM
|
||||||
|
|
|
|
||||||
s11 自治智能体 [14]
|
s11 Autonomous Agents [14]
|
||||||
空闲轮询 + 自动认领
|
空闲轮询 + 自动认领
|
||||||
|
|
|
|
||||||
s12 Worktree 隔离 [16]
|
s12 Worktree Isolation [16]
|
||||||
任务协调 + 按需隔离执行通道
|
Task 协调 + 按需隔离执行通道
|
||||||
|
|
||||||
[N] = 工具数量
|
[N] = 工具数量
|
||||||
```
|
```
|
||||||
|
|
@ -304,18 +304,18 @@ learn-claude-code/
|
||||||
|
|
||||||
| 课程 | 主题 | 格言 |
|
| 课程 | 主题 | 格言 |
|
||||||
|------|------|------|
|
|------|------|------|
|
||||||
| [s01](./docs/zh/s01-the-agent-loop.md) | Agent 循环 | *One loop & Bash is all you need* |
|
| [s01](./docs/zh/s01-the-agent-loop.md) | Agent Loop | *One loop & Bash is all you need* |
|
||||||
| [s02](./docs/zh/s02-tool-use.md) | Tool Use | *加一个工具, 只加一个 handler* |
|
| [s02](./docs/zh/s02-tool-use.md) | Tool Use | *加一个工具, 只加一个 handler* |
|
||||||
| [s03](./docs/zh/s03-todo-write.md) | TodoWrite | *没有计划的 agent 走哪算哪* |
|
| [s03](./docs/zh/s03-todo-write.md) | TodoWrite | *没有计划的 agent 走哪算哪* |
|
||||||
| [s04](./docs/zh/s04-subagent.md) | 子智能体 | *大任务拆小, 每个小任务干净的上下文* |
|
| [s04](./docs/zh/s04-subagent.md) | Subagent | *大任务拆小, 每个小任务干净的上下文* |
|
||||||
| [s05](./docs/zh/s05-skill-loading.md) | Skills | *用到什么知识, 临时加载什么知识* |
|
| [s05](./docs/zh/s05-skill-loading.md) | Skills | *用到什么知识, 临时加载什么知识* |
|
||||||
| [s06](./docs/zh/s06-context-compact.md) | Context Compact | *上下文总会满, 要有办法腾地方* |
|
| [s06](./docs/zh/s06-context-compact.md) | Context Compact | *上下文总会满, 要有办法腾地方* |
|
||||||
| [s07](./docs/zh/s07-task-system.md) | 任务系统 | *大目标要拆成小任务, 排好序, 记在磁盘上* |
|
| [s07](./docs/zh/s07-task-system.md) | Task System | *大目标要拆成小任务, 排好序, 记在磁盘上* |
|
||||||
| [s08](./docs/zh/s08-background-tasks.md) | 后台任务 | *慢操作丢后台, agent 继续想下一步* |
|
| [s08](./docs/zh/s08-background-tasks.md) | Background Tasks | *慢操作丢后台, agent 继续想下一步* |
|
||||||
| [s09](./docs/zh/s09-agent-teams.md) | 智能体团队 | *任务太大一个人干不完, 要能分给队友* |
|
| [s09](./docs/zh/s09-agent-teams.md) | Agent Teams | *任务太大一个人干不完, 要能分给队友* |
|
||||||
| [s10](./docs/zh/s10-team-protocols.md) | 团队协议 | *队友之间要有统一的沟通规矩* |
|
| [s10](./docs/zh/s10-team-protocols.md) | Team Protocols | *队友之间要有统一的沟通规矩* |
|
||||||
| [s11](./docs/zh/s11-autonomous-agents.md) | 自治智能体 | *队友自己看看板, 有活就认领* |
|
| [s11](./docs/zh/s11-autonomous-agents.md) | Autonomous Agents | *队友自己看看板, 有活就认领* |
|
||||||
| [s12](./docs/zh/s12-worktree-task-isolation.md) | Worktree + 任务隔离 | *各干各的目录, 互不干扰* |
|
| [s12](./docs/zh/s12-worktree-task-isolation.md) | Worktree + Task Isolation | *各干各的目录, 互不干扰* |
|
||||||
|
|
||||||
## 学完之后 -- 从理解到落地
|
## 学完之后 -- 从理解到落地
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,8 +1,8 @@
|
||||||
# s01: The Agent Loop (智能体循环)
|
# s01: The Agent Loop (Agent 循环)
|
||||||
|
|
||||||
`[ s01 ] s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
|
`[ s01 ] s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
|
||||||
|
|
||||||
> *"One loop & Bash is all you need"* -- 一个工具 + 一个循环 = 一个智能体。
|
> *"One loop & Bash is all you need"* -- 一个工具 + 一个循环 = 一个 Agent。
|
||||||
>
|
>
|
||||||
> **Harness 层**: 循环 -- 模型与真实世界的第一道连接。
|
> **Harness 层**: 循环 -- 模型与真实世界的第一道连接。
|
||||||
|
|
||||||
|
|
@ -92,7 +92,7 @@ def agent_loop(query):
|
||||||
messages.append({"role": "user", "content": results})
|
messages.append({"role": "user", "content": results})
|
||||||
```
|
```
|
||||||
|
|
||||||
不到 30 行, 这就是整个智能体。后面 11 个章节都在这个循环上叠加机制 -- 循环本身始终不变。
|
不到 30 行, 这就是整个 Agent。后面 11 个章节都在这个循环上叠加机制 -- 循环本身始终不变。
|
||||||
|
|
||||||
## 变更内容
|
## 变更内容
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,14 +1,14 @@
|
||||||
# s04: Subagents (子智能体)
|
# s04: Subagents (Subagent)
|
||||||
|
|
||||||
`s01 > s02 > s03 > [ s04 ] s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
|
`s01 > s02 > s03 > [ s04 ] s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
|
||||||
|
|
||||||
> *"大任务拆小, 每个小任务干净的上下文"* -- 子智能体用独立 messages[], 不污染主对话。
|
> *"大任务拆小, 每个小任务干净的上下文"* -- Subagent 用独立 messages[], 不污染主对话。
|
||||||
>
|
>
|
||||||
> **Harness 层**: 上下文隔离 -- 守护模型的思维清晰度。
|
> **Harness 层**: 上下文隔离 -- 守护模型的思维清晰度。
|
||||||
|
|
||||||
## 问题
|
## 问题
|
||||||
|
|
||||||
智能体工作越久, messages 数组越胖。每次读文件、跑命令的输出都永久留在上下文里。"这个项目用什么测试框架?" 可能要读 5 个文件, 但父智能体只需要一个词: "pytest。"
|
Agent 工作越久, messages 数组越胖。每次读文件、跑命令的输出都永久留在上下文里。"这个项目用什么测试框架?" 可能要读 5 个文件, 但父 Agent 只需要一个词: "pytest。"
|
||||||
|
|
||||||
## 解决方案
|
## 解决方案
|
||||||
|
|
||||||
|
|
@ -28,7 +28,7 @@ Parent context stays clean. Subagent context is discarded.
|
||||||
|
|
||||||
## 工作原理
|
## 工作原理
|
||||||
|
|
||||||
1. 父智能体有一个 `task` 工具。子智能体拥有除 `task` 外的所有基础工具 (禁止递归生成)。
|
1. 父 Agent 有一个 `task` 工具。Subagent 拥有除 `task` 外的所有基础工具 (禁止递归生成)。
|
||||||
|
|
||||||
```python
|
```python
|
||||||
PARENT_TOOLS = CHILD_TOOLS + [
|
PARENT_TOOLS = CHILD_TOOLS + [
|
||||||
|
|
@ -42,7 +42,7 @@ PARENT_TOOLS = CHILD_TOOLS + [
|
||||||
]
|
]
|
||||||
```
|
```
|
||||||
|
|
||||||
2. 子智能体以 `messages=[]` 启动, 运行自己的循环。只有最终文本返回给父智能体。
|
2. Subagent 以 `messages=[]` 启动, 运行自己的循环。只有最终文本返回给父 Agent。
|
||||||
|
|
||||||
```python
|
```python
|
||||||
def run_subagent(prompt: str) -> str:
|
def run_subagent(prompt: str) -> str:
|
||||||
|
|
@ -71,7 +71,7 @@ def run_subagent(prompt: str) -> str:
|
||||||
) or "(no summary)"
|
) or "(no summary)"
|
||||||
```
|
```
|
||||||
|
|
||||||
子智能体可能跑了 30+ 次工具调用, 但整个消息历史直接丢弃。父智能体收到的只是一段摘要文本, 作为普通 `tool_result` 返回。
|
Subagent 可能跑了 30+ 次工具调用, 但整个消息历史直接丢弃。父 Agent 收到的只是一段摘要文本, 作为普通 `tool_result` 返回。
|
||||||
|
|
||||||
## 相对 s03 的变更
|
## 相对 s03 的变更
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,4 +1,4 @@
|
||||||
# s05: Skills (技能加载)
|
# s05: Skills (Skill 加载)
|
||||||
|
|
||||||
`s01 > s02 > s03 > s04 > [ s05 ] s06 | s07 > s08 > s09 > s10 > s11 > s12`
|
`s01 > s02 > s03 > s04 > [ s05 ] s06 | s07 > s08 > s09 > s10 > s11 > s12`
|
||||||
|
|
||||||
|
|
@ -8,7 +8,7 @@
|
||||||
|
|
||||||
## 问题
|
## 问题
|
||||||
|
|
||||||
你希望智能体遵循特定领域的工作流: git 约定、测试模式、代码审查清单。全塞进系统提示太浪费 -- 10 个技能, 每个 2000 token, 就是 20,000 token, 大部分跟当前任务毫无关系。
|
你希望 Agent 遵循特定领域的工作流: git 约定、测试模式、代码审查清单。全塞进系统提示太浪费 -- 10 个 Skill, 每个 2000 token, 就是 20,000 token, 大部分跟当前任务毫无关系。
|
||||||
|
|
||||||
## 解决方案
|
## 解决方案
|
||||||
|
|
||||||
|
|
@ -31,11 +31,11 @@ When model calls load_skill("git"):
|
||||||
+--------------------------------------+
|
+--------------------------------------+
|
||||||
```
|
```
|
||||||
|
|
||||||
第一层: 系统提示中放技能名称 (低成本)。第二层: tool_result 中按需放完整内容。
|
第一层: 系统提示中放 Skill 名称 (低成本)。第二层: tool_result 中按需放完整内容。
|
||||||
|
|
||||||
## 工作原理
|
## 工作原理
|
||||||
|
|
||||||
1. 每个技能是一个目录, 包含 `SKILL.md` 文件和 YAML frontmatter。
|
1. 每个 Skill 是一个目录, 包含 `SKILL.md` 文件和 YAML frontmatter。
|
||||||
|
|
||||||
```
|
```
|
||||||
skills/
|
skills/
|
||||||
|
|
@ -45,7 +45,7 @@ skills/
|
||||||
SKILL.md # ---\n name: code-review\n description: Review code\n ---\n ...
|
SKILL.md # ---\n name: code-review\n description: Review code\n ---\n ...
|
||||||
```
|
```
|
||||||
|
|
||||||
2. SkillLoader 递归扫描 `SKILL.md` 文件, 用目录名作为技能标识。
|
2. SkillLoader 递归扫描 `SKILL.md` 文件, 用目录名作为 Skill 标识。
|
||||||
|
|
||||||
```python
|
```python
|
||||||
class SkillLoader:
|
class SkillLoader:
|
||||||
|
|
@ -84,14 +84,14 @@ TOOL_HANDLERS = {
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
模型知道有哪些技能 (便宜), 需要时再加载完整内容 (贵)。
|
模型知道有哪些 Skill (便宜), 需要时再加载完整内容 (贵)。
|
||||||
|
|
||||||
## 相对 s04 的变更
|
## 相对 s04 的变更
|
||||||
|
|
||||||
| 组件 | 之前 (s04) | 之后 (s05) |
|
| 组件 | 之前 (s04) | 之后 (s05) |
|
||||||
|----------------|------------------|--------------------------------|
|
|----------------|------------------|--------------------------------|
|
||||||
| Tools | 5 (基础 + task) | 5 (基础 + load_skill) |
|
| Tools | 5 (基础 + task) | 5 (基础 + load_skill) |
|
||||||
| 系统提示 | 静态字符串 | + 技能描述列表 |
|
| 系统提示 | 静态字符串 | + Skill 描述列表 |
|
||||||
| 知识库 | 无 | skills/\*/SKILL.md 文件 |
|
| 知识库 | 无 | skills/\*/SKILL.md 文件 |
|
||||||
| 注入方式 | 无 | 两层 (系统提示 + result) |
|
| 注入方式 | 无 | 两层 (系统提示 + result) |
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -8,7 +8,7 @@
|
||||||
|
|
||||||
## 问题
|
## 问题
|
||||||
|
|
||||||
上下文窗口是有限的。读一个 1000 行的文件就吃掉 ~4000 token; 读 30 个文件、跑 20 条命令, 轻松突破 100k token。不压缩, 智能体根本没法在大项目里干活。
|
上下文窗口是有限的。读一个 1000 行的文件就吃掉 ~4000 token; 读 30 个文件、跑 20 条命令, 轻松突破 100k token。不压缩, Agent 根本没法在大项目里干活。
|
||||||
|
|
||||||
## 解决方案
|
## 解决方案
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -10,7 +10,7 @@
|
||||||
|
|
||||||
s03 的 TodoManager 只是内存中的扁平清单: 没有顺序、没有依赖、状态只有做完没做完。真实目标是有结构的 -- 任务 B 依赖任务 A, 任务 C 和 D 可以并行, 任务 E 要等 C 和 D 都完成。
|
s03 的 TodoManager 只是内存中的扁平清单: 没有顺序、没有依赖、状态只有做完没做完。真实目标是有结构的 -- 任务 B 依赖任务 A, 任务 C 和 D 可以并行, 任务 E 要等 C 和 D 都完成。
|
||||||
|
|
||||||
没有显式的关系, 智能体分不清什么能做、什么被卡住、什么能同时跑。而且清单只活在内存里, 上下文压缩 (s06) 一跑就没了。
|
没有显式的关系, Agent 分不清什么能做、什么被卡住、什么能同时跑。而且清单只活在内存里, 上下文压缩 (s06) 一跑就没了。
|
||||||
|
|
||||||
## 解决方案
|
## 解决方案
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -8,7 +8,7 @@
|
||||||
|
|
||||||
## 问题
|
## 问题
|
||||||
|
|
||||||
有些命令要跑好几分钟: `npm install`、`pytest`、`docker build`。阻塞式循环下模型只能干等。用户说 "装依赖, 顺便建个配置文件", 智能体却只能一个一个来。
|
有些命令要跑好几分钟: `npm install`、`pytest`、`docker build`。阻塞式循环下模型只能干等。用户说 "装依赖, 顺便建个配置文件", Agent 却只能一个一个来。
|
||||||
|
|
||||||
## 解决方案
|
## 解决方案
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,4 +1,4 @@
|
||||||
# s09: Agent Teams (智能体团队)
|
# s09: Agent Teams (Agent 团队)
|
||||||
|
|
||||||
`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > [ s09 ] s10 > s11 > s12`
|
`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > [ s09 ] s10 > s11 > s12`
|
||||||
|
|
||||||
|
|
@ -8,9 +8,9 @@
|
||||||
|
|
||||||
## 问题
|
## 问题
|
||||||
|
|
||||||
子智能体 (s04) 是一次性的: 生成、干活、返回摘要、消亡。没有身份, 没有跨调用的记忆。后台任务 (s08) 能跑 shell 命令, 但做不了 LLM 引导的决策。
|
Subagent (s04) 是一次性的: 生成、干活、返回摘要、消亡。没有身份, 没有跨调用的记忆。Background Tasks (s08) 能跑 shell 命令, 但做不了 LLM 引导的决策。
|
||||||
|
|
||||||
真正的团队协作需要三样东西: (1) 能跨多轮对话存活的持久智能体, (2) 身份和生命周期管理, (3) 智能体之间的通信通道。
|
真正的团队协作需要三样东西: (1) 能跨多轮对话存活的持久 Agent, (2) 身份和生命周期管理, (3) Agent 之间的通信通道。
|
||||||
|
|
||||||
## 解决方案
|
## 解决方案
|
||||||
|
|
||||||
|
|
@ -105,7 +105,7 @@ def _teammate_loop(self, name, role, prompt):
|
||||||
| 组件 | 之前 (s08) | 之后 (s09) |
|
| 组件 | 之前 (s08) | 之后 (s09) |
|
||||||
|----------------|------------------|------------------------------------|
|
|----------------|------------------|------------------------------------|
|
||||||
| Tools | 6 | 9 (+spawn/send/read_inbox) |
|
| Tools | 6 | 9 (+spawn/send/read_inbox) |
|
||||||
| 智能体数量 | 单一 | 领导 + N 个队友 |
|
| Agent 数量 | 单一 | 领导 + N 个队友 |
|
||||||
| 持久化 | 无 | config.json + JSONL 收件箱 |
|
| 持久化 | 无 | config.json + JSONL 收件箱 |
|
||||||
| 线程 | 后台命令 | 每线程完整 agent loop |
|
| 线程 | 后台命令 | 每线程完整 agent loop |
|
||||||
| 生命周期 | 一次性 | idle -> working -> idle |
|
| 生命周期 | 一次性 | idle -> working -> idle |
|
||||||
|
|
|
||||||
|
|
@ -1,4 +1,4 @@
|
||||||
# s11: Autonomous Agents (自治智能体)
|
# s11: Autonomous Agents (Autonomous Agent)
|
||||||
|
|
||||||
`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > [ s11 ] s12`
|
`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > [ s11 ] s12`
|
||||||
|
|
||||||
|
|
@ -12,7 +12,7 @@ s09-s10 中, 队友只在被明确指派时才动。领导得给每个队友写
|
||||||
|
|
||||||
真正的自治: 队友自己扫描任务看板, 认领没人做的任务, 做完再找下一个。
|
真正的自治: 队友自己扫描任务看板, 认领没人做的任务, 做完再找下一个。
|
||||||
|
|
||||||
一个细节: 上下文压缩 (s06) 后智能体可能忘了自己是谁。身份重注入解决这个问题。
|
一个细节: Context Compact (s06) 后 Agent 可能忘了自己是谁。身份重注入解决这个问题。
|
||||||
|
|
||||||
## 解决方案
|
## 解决方案
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -8,7 +8,7 @@
|
||||||
|
|
||||||
## 问题
|
## 问题
|
||||||
|
|
||||||
到 s11, 智能体已经能自主认领和完成任务。但所有任务共享一个目录。两个智能体同时重构不同模块 -- A 改 `config.py`, B 也改 `config.py`, 未提交的改动互相污染, 谁也没法干净回滚。
|
到 s11, Agent 已经能自主认领和完成任务。但所有任务共享一个目录。两个 Agent 同时重构不同模块 -- A 改 `config.py`, B 也改 `config.py`, 未提交的改动互相污染, 谁也没法干净回滚。
|
||||||
|
|
||||||
任务板管 "做什么" 但不管 "在哪做"。解法: 给每个任务一个独立的 git worktree 目录, 用任务 ID 把两边关联起来。
|
任务板管 "做什么" 但不管 "在哪做"。解法: 给每个任务一个独立的 git worktree 目录, 用任务 ID 把两边关联起来。
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -7,8 +7,8 @@
|
||||||
"description": "When the agent invokes the Skill tool, the skill's content (a SKILL.md file) is returned as a tool_result in a user message, not injected into the system prompt. This is a deliberate caching optimization: the system prompt remains static across turns, which means API providers can cache it (Anthropic's prompt caching, OpenAI's system message caching). If skill content were in the system prompt, it would change every time a new skill is loaded, invalidating the cache. By putting dynamic content in tool_result, we keep the expensive system prompt cacheable while still getting skill knowledge into context.",
|
"description": "When the agent invokes the Skill tool, the skill's content (a SKILL.md file) is returned as a tool_result in a user message, not injected into the system prompt. This is a deliberate caching optimization: the system prompt remains static across turns, which means API providers can cache it (Anthropic's prompt caching, OpenAI's system message caching). If skill content were in the system prompt, it would change every time a new skill is loaded, invalidating the cache. By putting dynamic content in tool_result, we keep the expensive system prompt cacheable while still getting skill knowledge into context.",
|
||||||
"alternatives": "Injecting skills into the system prompt is simpler and gives skills higher priority in the model's attention. But it breaks prompt caching (every skill load creates a new system prompt variant) and bloats the system prompt over time as skills accumulate. The tool_result approach keeps things cache-friendly at the cost of slightly lower attention priority.",
|
"alternatives": "Injecting skills into the system prompt is simpler and gives skills higher priority in the model's attention. But it breaks prompt caching (every skill load creates a new system prompt variant) and bloats the system prompt over time as skills accumulate. The tool_result approach keeps things cache-friendly at the cost of slightly lower attention priority.",
|
||||||
"zh": {
|
"zh": {
|
||||||
"title": "技能通过 tool_result 注入,而非系统提示词",
|
"title": "Skill 通过 tool_result 注入,而非系统提示词",
|
||||||
"description": "当 agent 调用 Skill 工具时,技能内容(SKILL.md 文件)作为 tool_result 在用户消息中返回,而非注入系统提示词。这是一个刻意的缓存优化:系统提示词在各轮次间保持静态,API 提供商可以缓存它(Anthropic 的 prompt caching、OpenAI 的 system message caching)。如果技能内容在系统提示词中,每次加载新技能都会使缓存失效。将动态内容放在 tool_result 中,既保持了昂贵的系统提示词可缓存,又让技能知识进入了上下文。"
|
"description": "当 agent 调用 Skill 工具时,Skill 内容(SKILL.md 文件)作为 tool_result 在用户消息中返回,而非注入系统提示词。这是一个刻意的缓存优化:系统提示词在各轮次间保持静态,API 提供商可以缓存它(Anthropic 的 prompt caching、OpenAI 的 system message caching)。如果 Skill 内容在系统提示词中,每次加载新 Skill 都会使缓存失效。将动态内容放在 tool_result 中,既保持了昂贵的系统提示词可缓存,又让 Skill 知识进入了上下文。"
|
||||||
},
|
},
|
||||||
"ja": {
|
"ja": {
|
||||||
"title": "スキルはシステムプロンプトではなく tool_result で注入",
|
"title": "スキルはシステムプロンプトではなく tool_result で注入",
|
||||||
|
|
@ -21,8 +21,8 @@
|
||||||
"description": "Skills are not loaded at startup. The agent starts with only the skill names and descriptions (from frontmatter). When the agent decides it needs a specific skill, it calls the Skill tool, which loads the full SKILL.md body into context. This keeps the initial prompt small and focused. An agent solving a Python bug doesn't need the Kubernetes deployment skill loaded -- that would waste context window space and potentially confuse the model with irrelevant instructions.",
|
"description": "Skills are not loaded at startup. The agent starts with only the skill names and descriptions (from frontmatter). When the agent decides it needs a specific skill, it calls the Skill tool, which loads the full SKILL.md body into context. This keeps the initial prompt small and focused. An agent solving a Python bug doesn't need the Kubernetes deployment skill loaded -- that would waste context window space and potentially confuse the model with irrelevant instructions.",
|
||||||
"alternatives": "Loading all skills upfront guarantees the model always has all knowledge available, but wastes tokens on irrelevant skills and may hit context limits. A recommendation system (model suggests skills, human approves) adds latency. Lazy loading lets the model self-serve the knowledge it needs, when it needs it.",
|
"alternatives": "Loading all skills upfront guarantees the model always has all knowledge available, but wastes tokens on irrelevant skills and may hit context limits. A recommendation system (model suggests skills, human approves) adds latency. Lazy loading lets the model self-serve the knowledge it needs, when it needs it.",
|
||||||
"zh": {
|
"zh": {
|
||||||
"title": "按需加载技能而非预加载",
|
"title": "按需加载 Skill 而非预加载",
|
||||||
"description": "技能不会在启动时加载。Agent 初始只拥有技能名称和描述(来自 frontmatter)。当 agent 判断需要特定技能时,调用 Skill 工具将完整的 SKILL.md 内容加载到上下文中。这保持了初始提示词的精简。一个正在修复 Python bug 的 agent 不需要加载 Kubernetes 部署技能——那会浪费上下文窗口空间,还可能用无关指令干扰模型。"
|
"description": "Skill 不会在启动时加载。Agent 初始只拥有 Skill 名称和描述(来自 frontmatter)。当 agent 判断需要特定 Skill 时,调用 Skill 工具将完整的 SKILL.md 内容加载到上下文中。这保持了初始提示词的精简。一个正在修复 Python bug 的 agent 不需要加载 Kubernetes 部署 Skill——那会浪费上下文窗口空间,还可能用无关指令干扰模型。"
|
||||||
},
|
},
|
||||||
"ja": {
|
"ja": {
|
||||||
"title": "起動時ではなくオンデマンドでスキルを読み込み",
|
"title": "起動時ではなくオンデマンドでスキルを読み込み",
|
||||||
|
|
@ -36,7 +36,7 @@
|
||||||
"alternatives": "A separate metadata file (skill.yaml + skill.md) would work but doubles the number of files. Embedding metadata in the markdown (as headings or comments) requires parsing the full file to extract metadata. Frontmatter is a well-established convention (Jekyll, Hugo, Astro) that keeps metadata and content co-located but separately parseable.",
|
"alternatives": "A separate metadata file (skill.yaml + skill.md) would work but doubles the number of files. Embedding metadata in the markdown (as headings or comments) requires parsing the full file to extract metadata. Frontmatter is a well-established convention (Jekyll, Hugo, Astro) that keeps metadata and content co-located but separately parseable.",
|
||||||
"zh": {
|
"zh": {
|
||||||
"title": "SKILL.md 采用 YAML Frontmatter + Markdown 正文",
|
"title": "SKILL.md 采用 YAML Frontmatter + Markdown 正文",
|
||||||
"description": "每个 SKILL.md 文件有两部分:YAML frontmatter(名称、描述、globs)和 markdown 正文(实际指令)。Frontmatter 作为技能注册表的元数据——当 agent 问'有哪些可用技能'时,展示的就是这些信息。正文是按需加载的有效负载。这种分离意味着可以列出 100 个技能(每个只读几字节的 frontmatter)而不必加载 100 套完整指令集(每套可能数千 token)。"
|
"description": "每个 SKILL.md 文件有两部分:YAML frontmatter(名称、描述、globs)和 markdown 正文(实际指令)。Frontmatter 作为 Skill 注册表的元数据——当 agent 问'有哪些可用 Skill'时,展示的就是这些信息。正文是按需加载的有效负载。这种分离意味着可以列出 100 个 Skill(每个只读几字节的 frontmatter)而不必加载 100 套完整指令集(每套可能数千 token)。"
|
||||||
},
|
},
|
||||||
"ja": {
|
"ja": {
|
||||||
"title": "SKILL.md で YAML フロントマター + Markdown 本文",
|
"title": "SKILL.md で YAML フロントマター + Markdown 本文",
|
||||||
|
|
|
||||||
|
|
@ -7,8 +7,8 @@
|
||||||
"description": "In s04, subagents are ephemeral: spawn, do one task, return result, die. Their knowledge dies with them. In s09, teammates are persistent threads with identity (name, role) and config files. A teammate can complete task A, then be assigned task B, carrying forward everything it learned. Persistent teammates accumulate project knowledge, understand established patterns, and don't need to re-read the same files for every task.",
|
"description": "In s04, subagents are ephemeral: spawn, do one task, return result, die. Their knowledge dies with them. In s09, teammates are persistent threads with identity (name, role) and config files. A teammate can complete task A, then be assigned task B, carrying forward everything it learned. Persistent teammates accumulate project knowledge, understand established patterns, and don't need to re-read the same files for every task.",
|
||||||
"alternatives": "One-shot subagents (s04 style) are simpler and provide perfect context isolation -- no risk of one task's context polluting another. But the re-learning cost is high: every new task starts from zero. A middle ground (subagents with shared memory/knowledge base) was considered but adds complexity without the full benefit of persistent identity and state.",
|
"alternatives": "One-shot subagents (s04 style) are simpler and provide perfect context isolation -- no risk of one task's context polluting another. But the re-learning cost is high: every new task starts from zero. A middle ground (subagents with shared memory/knowledge base) was considered but adds complexity without the full benefit of persistent identity and state.",
|
||||||
"zh": {
|
"zh": {
|
||||||
"title": "持久化队友 vs 一次性子智能体",
|
"title": "持久化队友 vs 一次性 Subagent",
|
||||||
"description": "在 s04 中,子智能体是临时的:创建、执行一个任务、返回结果、销毁。它们的知识随之消亡。在 s09 中,队友是具有身份(名称、角色)和配置文件的持久化线程。队友可以完成任务 A,然后被分配任务 B,并携带之前学到的所有知识。持久化队友积累项目知识,理解已建立的模式,不需要为每个任务重新阅读相同的文件。"
|
"description": "在 s04 中,Subagent 是临时的:创建、执行一个任务、返回结果、销毁。它们的知识随之消亡。在 s09 中,队友是具有身份(名称、角色)和配置文件的持久化线程。队友可以完成任务 A,然后被分配任务 B,并携带之前学到的所有知识。持久化队友积累项目知识,理解已建立的模式,不需要为每个任务重新阅读相同的文件。"
|
||||||
},
|
},
|
||||||
"ja": {
|
"ja": {
|
||||||
"title": "永続的なチームメイト vs 使い捨てサブエージェント",
|
"title": "永続的なチームメイト vs 使い捨てサブエージェント",
|
||||||
|
|
|
||||||
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
|
|
@ -39,18 +39,18 @@
|
||||||
"loc_delta": "代码量差异"
|
"loc_delta": "代码量差异"
|
||||||
},
|
},
|
||||||
"sessions": {
|
"sessions": {
|
||||||
"s01": "Agent 循环",
|
"s01": "Agent Loop",
|
||||||
"s02": "工具",
|
"s02": "Tool Use",
|
||||||
"s03": "TodoWrite",
|
"s03": "TodoWrite",
|
||||||
"s04": "子 Agent",
|
"s04": "Subagent",
|
||||||
"s05": "技能",
|
"s05": "Skills",
|
||||||
"s06": "上下文压缩",
|
"s06": "Context Compact",
|
||||||
"s07": "任务系统",
|
"s07": "Task System",
|
||||||
"s08": "后台任务",
|
"s08": "Background Tasks",
|
||||||
"s09": "Agent 团队",
|
"s09": "Agent Teams",
|
||||||
"s10": "团队协议",
|
"s10": "Team Protocols",
|
||||||
"s11": "自主 Agent",
|
"s11": "Autonomous Agents",
|
||||||
"s12": "Worktree + 任务隔离"
|
"s12": "Worktree + Task Isolation"
|
||||||
},
|
},
|
||||||
"layer_labels": {
|
"layer_labels": {
|
||||||
"tools": "工具与执行",
|
"tools": "工具与执行",
|
||||||
|
|
@ -60,17 +60,17 @@
|
||||||
"collaboration": "协作"
|
"collaboration": "协作"
|
||||||
},
|
},
|
||||||
"viz": {
|
"viz": {
|
||||||
"s01": "Agent While 循环",
|
"s01": "Agent While-Loop",
|
||||||
"s02": "工具分发映射",
|
"s02": "Tool Dispatch Map",
|
||||||
"s03": "TodoWrite 提醒系统",
|
"s03": "TodoWrite Nag System",
|
||||||
"s04": "子 Agent 上下文隔离",
|
"s04": "Subagent Context Isolation",
|
||||||
"s05": "按需技能加载",
|
"s05": "On-Demand Skill Loading",
|
||||||
"s06": "三层上下文压缩",
|
"s06": "Three-Layer Context Compact",
|
||||||
"s07": "任务依赖图",
|
"s07": "Task Dependency Graph",
|
||||||
"s08": "后台任务通道",
|
"s08": "Background Task Lanes",
|
||||||
"s09": "Agent 团队邮箱",
|
"s09": "Agent Team Mailboxes",
|
||||||
"s10": "FSM 团队协议",
|
"s10": "FSM Team Protocols",
|
||||||
"s11": "自主 Agent 循环",
|
"s11": "Autonomous Agent Cycle",
|
||||||
"s12": "Worktree 任务隔离"
|
"s12": "Worktree Task Isolation"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue