abc/analysis_claude_code
1
0
Fork 0
mirror of https://github.com/shareAI-lab/analysis_claude_code.git synced 2026-03-22 10:25:41 +08:00
Code Issues Packages Projects Releases Wiki Activity
analysis_claude_code/README-zh.md
CrazyBoyM 4f39ee4512 fix session doc
2026-02-27 02:19:54 +08:00

233 lines
10 KiB
Markdown
Raw Blame History

# Learn Claude Code -- 从 0 到 1 构建 nano Claude Code-like agent
[English](./README.md) | [中文](./README-zh.md) | [日本語](./README-ja.md)
```
THE AGENT PATTERN
=================
User --> messages[] --> LLM --> response
|
stop_reason == "tool_use"?
/ \
yes no
| |
execute tools return text
append results
loop back -----------------> messages[]
这是最小循环。每个 AI 编程 Agent 都需要这个循环。
生产级 Agent 还会叠加策略、权限与生命周期层。
```
**12 个递进式课程, 从简单循环到隔离化的自治执行。**
**每个课程添加一个机制。每个机制有一句格言。**
> **s01**   *"One loop & Bash is all you need"* — 一个工具 + 一个循环 = 一个智能体
>
> **s02**   *"加一个工具, 只加一个 handler"* — 循环不用动, 新工具注册进 dispatch map 就行
>
> **s03**   *"没有计划的 agent 走哪算哪"* — 先列步骤再动手, 完成率翻倍
>
> **s04**   *"大任务拆小, 每个小任务干净的上下文"* — 子智能体用独立 messages[], 不污染主对话
>
> **s05**   *"用到什么知识, 临时加载什么知识"* — 通过 tool_result 注入, 不塞 system prompt
>
> **s06**   *"上下文总会满, 要有办法腾地方"* — 三层压缩策略, 换来无限会话
>
> **s07**   *"大目标要拆成小任务, 排好序, 记在磁盘上"* — 文件持久化的任务图, 为多 agent 协作打基础
>
> **s08**   *"慢操作丢后台, agent 继续想下一步"* — 后台线程跑命令, 完成后注入通知
>
> **s09**   *"任务太大一个人干不完, 要能分给队友"* — 持久化队友 + 异步邮箱
>
> **s10**   *"队友之间要有统一的沟通规矩"* — 一个 request-response 模式驱动所有协商
>
> **s11**   *"队友自己看看板, 有活就认领"* — 不需要领导逐个分配, 自组织
>
> **s12**   *"各干各的目录, 互不干扰"* — 任务管目标, worktree 管目录, 按 ID 绑定
---
## 核心模式
```python
def agent_loop(messages):
while True:
response = client.messages.create(
model=MODEL, system=SYSTEM,
messages=messages, tools=TOOLS,
)
messages.append({"role": "assistant",
"content": response.content})
if response.stop_reason != "tool_use":
return
results = []
for block in response.content:
if block.type == "tool_use":
output = TOOL_HANDLERS[block.name](**block.input)
results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": output,
})
messages.append({"role": "user", "content": results})
```
每个课程在这个循环之上叠加一个机制 -- 循环本身始终不变。
## 范围说明 (重要)
本仓库是一个 0->1 的学习型项目，用于从零构建 nano Claude Code-like agent。
为保证学习路径清晰，仓库有意简化或省略了部分生产机制：
- 完整事件 / Hook 总线 (例如 PreToolUse、SessionStart/End、ConfigChange)。
s12 仅提供教学用途的最小 append-only 生命周期事件流。
- 基于规则的权限治理与信任流程
- 会话生命周期控制 (resume/fork) 与更完整的 worktree 生命周期控制
- 完整 MCP 运行时细节 (transport/OAuth/资源订阅/轮询)
仓库中的团队 JSONL 邮箱协议是教学实现，不是对任何特定生产内部实现的声明。
## 快速开始
```sh
git clone https://github.com/shareAI-lab/learn-claude-code
cd learn-claude-code
pip install -r requirements.txt
cp .env.example .env # 编辑 .env 填入你的 ANTHROPIC_API_KEY
python agents/s01_agent_loop.py # 从这里开始
python agents/s12_worktree_task_isolation.py # 完整递进终点
python agents/s_full.py # 总纲: 全部机制合一
```
### Web 平台
交互式可视化、分步动画、源码查看器, 以及每个课程的文档。
```sh
cd web && npm install && npm run dev # http://localhost:3000
```
## 学习路径
```
第一阶段: 循环 第二阶段: 规划与知识
================== ==============================
s01 Agent 循环 [1] s03 TodoWrite [5]
while + stop_reason TodoManager + nag 提醒
| |
+-> s02 Tool Use [4] s04 子智能体 [5]
dispatch map: name->handler 每个子智能体独立 messages[]
|
s05 Skills [5]
SKILL.md 通过 tool_result 注入
|
s06 Context Compact [5]
三层上下文压缩
第三阶段: 持久化 第四阶段: 团队
================== =====================
s07 任务系统 [8] s09 智能体团队 [9]
文件持久化 CRUD + 依赖图 队友 + JSONL 邮箱
| |
s08 后台任务 [6] s10 团队协议 [12]
守护线程 + 通知队列 关机 + 计划审批 FSM
|
s11 自治智能体 [14]
空闲轮询 + 自动认领
|
s12 Worktree 隔离 [16]
任务协调 + 按需隔离执行通道
[N] = 工具数量
```
## 项目结构
```
learn-claude-code/
|
|-- agents/ # Python 参考实现 (s01-s12 + s_full 总纲)
|-- docs/{en,zh,ja}/ # 心智模型优先的文档 (3 种语言)
|-- web/ # 交互式学习平台 (Next.js)
|-- skills/ # s05 的 Skill 文件
+-- .github/workflows/ci.yml # CI: 类型检查 + 构建
```
## 文档
心智模型优先: 问题、方案、ASCII 图、最小化代码。
[English](./docs/en/) | [中文](./docs/zh/) | [日本語](./docs/ja/)
| 课程 | 主题 | 格言 |
|------|------|------|
| [s01](./docs/zh/s01-the-agent-loop.md) | Agent 循环 | *One loop & Bash is all you need* |
| [s02](./docs/zh/s02-tool-use.md) | Tool Use | *加一个工具, 只加一个 handler* |
| [s03](./docs/zh/s03-todo-write.md) | TodoWrite | *没有计划的 agent 走哪算哪* |
| [s04](./docs/zh/s04-subagent.md) | 子智能体 | *大任务拆小, 每个小任务干净的上下文* |
| [s05](./docs/zh/s05-skill-loading.md) | Skills | *用到什么知识, 临时加载什么知识* |
| [s06](./docs/zh/s06-context-compact.md) | Context Compact | *上下文总会满, 要有办法腾地方* |
| [s07](./docs/zh/s07-task-system.md) | 任务系统 | *大目标要拆成小任务, 排好序, 记在磁盘上* |
| [s08](./docs/zh/s08-background-tasks.md) | 后台任务 | *慢操作丢后台, agent 继续想下一步* |
| [s09](./docs/zh/s09-agent-teams.md) | 智能体团队 | *任务太大一个人干不完, 要能分给队友* |
| [s10](./docs/zh/s10-team-protocols.md) | 团队协议 | *队友之间要有统一的沟通规矩* |
| [s11](./docs/zh/s11-autonomous-agents.md) | 自治智能体 | *队友自己看看板, 有活就认领* |
| [s12](./docs/zh/s12-worktree-task-isolation.md) | Worktree + 任务隔离 | *各干各的目录, 互不干扰* |
## 学完之后 -- 从理解到落地
12 个课程走完, 你已经从内到外理解了 agent 的工作原理。两种方式把知识变成产品:
### Kode Agent CLI -- 开源 Coding Agent CLI
> `npm i -g @shareai-lab/kode`
支持 Skill & LSP, 适配 Windows, 可接 GLM / MiniMax / DeepSeek 等开放模型。装完即用。
GitHub: **[shareAI-lab/Kode-cli](https://github.com/shareAI-lab/Kode-cli)**
### Kode Agent SDK -- 把 Agent 能力嵌入你的应用
官方 Claude Code Agent SDK 底层与完整 CLI 进程通信 -- 每个并发用户 = 一个终端进程。Kode SDK 是独立库, 无 per-user 进程开销, 可嵌入后端、浏览器插件、嵌入式设备等任意运行时。
GitHub: **[shareAI-lab/Kode-agent-sdk](https://github.com/shareAI-lab/Kode-agent-sdk)**
---
## 姊妹教程: 从*被动临时会话*到*主动常驻助手*
本仓库教的 agent 属于 **用完即走** 型 -- 开终端、给任务、做完关掉, 下次重开是全新会话。Claude Code 就是这种模式。
但 [OpenClaw](https://github.com/openclaw/openclaw) (小龙虾) 证明了另一种可能: 在同样的 agent core 之上, 加两个机制就能让 agent 从"踹一下动一下"变成"自己隔 30 秒醒一次找活干":
- **心跳 (Heartbeat)** -- 每 30 秒系统给 agent 发一条消息, 让它检查有没有事可做。没事就继续睡, 有事立刻行动。
- **定时任务 (Cron)** -- agent 可以给自己安排未来要做的事, 到点自动执行。
再加上 IM 多通道路由 (WhatsApp/Telegram/Slack/Discord 等 13+ 平台)、不清空的上下文记忆、Soul 人格系统, agent 就从一个临时工具变成了始终在线的个人 AI 助手。
**[claw0](https://github.com/shareAI-lab/claw0)** 是我们的姊妹教学仓库, 从零拆解这些机制:
```
claw agent = agent core + heartbeat + cron + IM chat + memory + soul
```
```
learn-claude-code claw0
(agent 运行时内核: (主动式常驻 AI 助手:
循环、工具、规划、 心跳、定时任务、IM 通道、
团队、worktree 隔离) 记忆、Soul 人格)
```
## 许可证
MIT
---
**模型就是智能体。我们的工作就是给它工具, 然后让开。**
Reference in New Issue View Git Blame Copy Permalink