1 line
30 KiB
JSON
1 line
30 KiB
JSON
{"repo": "bozhoudev/14days-build-claude-code-cli", "files": {"README.md": {"15a4b74143ec6f54057739289b4f889a5fddcae7": {"t": 1785674032.636771, "n": 4353, "h": "7a056333cef36d4b", "c": "# 14 天手搓 Claude Code CLI\n\n[English](./README.en.md)\n\n这个项目是一个教学版 Code Agent CLI。我们用 Python 从零实现一个 Claude Code 风格的 `agent-code`，重点学习模型外层那套 harness：CLI 运行时、Agent Loop、工具调用、权限、文件编辑、命令执行、会话记忆、hooks、skills、subagents、worktree 和 MCP 工具生态。\n\n它不是 Claude Code 的完整复刻，也不追求产品级能力。目标更简单：跟着 14 天教程，把一个能读代码、改文件、跑命令、管理上下文的代码 Agent 一步步手写出来。\n\n## 为什么做这个项目\n\n我一直想系统学 Agent Harness，但一开始不知道从哪里下手。后来有人跟我说，与其泛泛看文章，不如直接研究 Claude Code 这种真实产品是怎么设计的。\n\n正好前段时间有一份 Claude Code 源码快照公开可见，我就先让 AI 带着自己读了一遍，看看官方把哪些能力当成一等工具，哪些逻辑放在 CLI runtime，哪些逻辑放在模型外层的 harness 里。\n\n读完以后，我决定把这条学习路径重新整理成教程：不用 TypeScript 复刻官方实现，而是用学习者更容易跑起来的 Python，把核心机制拆成 14 天。每一天都能运行，每一天都能看见一个新的 harness 边界。\n\n整个过程也大量使用了 AI 协作。如果你觉得某些文案、翻译或者解释有一点 AI 味，欢迎直接提 issue 或 PR。这个项目本来就是边学边改出来的。\n\n## 你会做出什么\n\n最后的 CLI 叫 `agent-code`。它会逐步具备这些能力：\n\n- 接收一次性 prompt 或进入终端 REPL\n- 调用真实模型，并处理 `tool_use` / `tool_result`\n- 搜索、读取和总结项目文件\n- 在写文件前做安全检查和 diff preview\n- 执行 bash 命令，并通过权限系统保护危险操作\n- 保存会话，读取项目记忆，压缩上下文\n- 支持 slash commands、hooks、skills 和 subagents\n- 用 worktree 隔离任务，并通过 MCP / ToolSearch 扩展工具\n\n一句话：模型负责推理，harness 负责上下文、工具、权限、执行、状态和反馈循环。\n\n## 默认测试模型\n\n教程主线使用 Anthropic Messages API 的消息形状，也就是 `tool_use`、`tool_result` 和 `input_schema`。为了降低测试成本、让更多人能跑起来，项目默认用 DeepSeek 的 Anthropic-compatible endpoint 做真实模型测试：\n\n```bash\nexport ANTHROPIC_AUTH_TOKEN=\"sk-...\"\nexport ANTHROPIC_BASE_URL=\"https://api.deepseek.com/anthropic\"\n```\n\n教程示例默认模型以当天文档和快照代码为准，主线常用 `deepseek-v4-flash`。如果你想换成官方 Claude 或其他兼容服务，只要保留 Anthropic Messages API 的协议形状，改 token、base URL 和 `--model` 即可。\n\n## 14 天路线\n\n前 7 天先做出一个能用的单 Agent CLI，后 7 天把它升级成更完整的 Claude Code 风格 harness。\n\n| Day | 主题 | 学到的 harness 能力 |\n|---|---|---|\n| 1 | Hello Agent | CLI、REPL、MockProvider、最小 Agent Loop |\n| 2 | Real Model + Tool Calling | AnthropicProvider、`tool_use` / `tool_result` |\n| 3 | File + Web Tools | cwd 边界、文件读取、搜索、网页工具 |\n| 4 | Safe Edit | read-before-edit、字符串替换、diff preview |\n| 5 | Bash + Permission | 命令执行、权限请求、后台任务 |\n| 6 | Session + Memory | 会话 JSONL、项目记忆、memdir |\n| 7 | Slash + Hooks | slash command、hooks、cron `/loop` |\n| 8 | Interactive Shell + Plan Mode | 交互式 shell、TodoWrite、Plan Mode 审批闭环 |\n| 9 | Skills | 按需加载知识和工作流 |\n| 10 | Subagents | 子 Agent 派发和结果回填 |\n| 11 | Context Compact | 长上下文压缩、成本追踪 |\n| 12 | Agent Coordinator | 极简多 Agent 协作 |\n| 13 | Worktree + Final Demo | worktree 隔离、端到端代码任务 |\n| 14 | MCP + ToolSearch | MCP 客户端、工具发现、工具扩展 |\n\n当前仓库已经包含前 9 天的教程和参考快照。后续内容会继续在同一条路线里补齐。\n\n## 怎么开始\n\n如果你是跟教程学习，从 Day 1 文档开始，在自己的 `agent-code` 项目里持续修改：\n\n```bash\nopen docs/day-01-hello-agent.md\n```\n\n如果只想运行仓库里的完成版参考快照：\n\n```bash\ncd packages/day-01-hello-agent\nuv sync\nuv run agent-code \"用 echo 工具说 hi\"\nuv run pytest\n```\n\n测试某一天时，建议进入对应目录再跑，避免 pytest 从仓库根目录收集到多个 day 的同名测试文件：\n\n```bash\ncd packages/day-02-real-model-tool-calling\nuv run pytest\n```\n\n## 网页版\n\n这个项目还有一个网页教程版本，源码在 `agent-code-learn/`。本地预览：\n\n```bash\ncd agent-code-learn\nnpm install\nnpm run dev\n```\n\n然后打开 `http://localhost:3000`。线上站点按当前网页项目元信息使用 `buildcc.dev`，如果你访问时还没部署好，可以先用本地预览。\n\n## 教学版项目架构\n\n```mermaid\nflowchart TD\n User[\"用户输入\"] --> CLI[\"Typer CLI / REPL / Slash Router\"]\n CLI --> Agent[\"Agent Loop\"]\n Agent --> Provider[\"ModelProvider<br/>Mock / Anthropic\"]\n Provider --> Model[\"Claude 或 Anthropic-compatible API\"]\n\n Agent --> Tools[\"Tool Registry\"]\n Tools --> FileTools[\"File / Web / Safe Edit\"]\n Tools --> Bash[\"Bash Tool\"]\n Tools --> Memory[\"Session / Memory\"]\n Tools --> Ext[\"Hooks / Skills / Subagents / MCP Lite\"]\n\n FileTools --> Safety[\"cwd 边界 / diff preview / read-before-edit\"]\n Bash --> Permission[\"Permission Engine\"]\n Safety --> Workspace[\"学习者的 agent-code 项目\"]\n Permission --> Workspace\n```\n\n## 项目结构\n\n```txt\ndocs/ 14 天教程文档\npackages/day-*/ 每一天独立可运行的教学快照\ndemo/ 当前综合 demo 项目\nagent-code-learn/ 网页版教程\n\n```\n\n注意：教程读者不是每天新建一个 `packages/day-*`。这些目录是参考答案快照。真正学习时，我们是在自己的 `agent-code` 项目里从 Day 1 持续改到 Day 14。\n\n## 欢迎反馈\n\n欢迎提 issue、discussion 或 PR，尤其是这几类：\n\n- 某一步命令跑不通，或者输出和文档对不上\n- 教程里某段解释不清楚\n- Claude Code 架构理解有偏差\n- DeepSeek / Claude / 兼容 endpoint 的运行差异\n- 英文翻译不自然\n- 网页版排版、交互或代码 diff 有问题\n\n如果你也在研究 Agent Harness，欢迎把你的问题、踩坑记录和改进建议一起丢过来。这个项目最有价值的部分，不是“我写完了一个教程”，而是大家能把一个真实代码 Agent 的外层工程系统拆开看懂。\n\n## 声明\n\nThis is an educational implementation. We reference the publicly visible Claude Code source snapshot to understand its architecture, but rewrite everything in Python with teaching-friendly simplifications. It is not affiliated with Anthropic.\n\n## License\n\nMIT\n"}, "08231674cfcb59387ced02375341ef01ea65e98f": {"t": 1785763859.432778, "n": 4353, "h": "a5e1df42ce04ddea", "c": "# 14 天手搓 Claude Code CLI\n\n[English](./README.en.md)\n\n这个项目是一个教学版 Code Agent CLI。我们用 Python 从零实现一个 Claude Code 风格的 `agent-code`，重点学习模型外层那套 harness：CLI 运行时、Agent Loop、工具调用、权限、文件编辑、命令执行、会话记忆、hooks、skills、subagents、worktree 和 MCP 工具生态。\n\n它不是 Claude Code 的完整复刻，也不追求产品级能力。目标更简单：跟着 14 天教程，把一个能读代码、改文件、跑命令、管理上下文的代码 Agent 一步步手写出来。\n\n## 为什么做这个项目\n\n我一直想系统学 Agent Harness，但一开始不知道从哪里下手。后来有人跟我说，与其泛泛看文章，不如直接研究 Claude Code 这种真实产品是怎么设计的。\n\n正好前段时间有一份 Claude Code 源码快照公开可见，我就先让 AI 带着自己读了一遍，看看官方把哪些能力当成一等工具，哪些逻辑放在 CLI runtime，哪些逻辑放在模型外层的 harness 里。\n\n读完以后，我决定把这条学习路径重新整理成教程：不用 TypeScript 复刻官方实现，而是用学习者更容易跑起来的 Python，把核心机制拆成 14 天。每一天都能运行，每一天都能看见一个新的 harness 边界。\n\n整个过程也大量使用了 AI 协作。如果你觉得某些文案、翻译或者解释有一点 AI 味，欢迎直接提 issue 或 PR。这个项目本来就是边学边改出来的。\n\n## 你会做出什么\n\n最后的 CLI 叫 `agent-code`。它会逐步具备这些能力：\n\n- 接收一次性 prompt 或进入终端 REPL\n- 调用真实模型，并处理 `tool_use` / `tool_result`\n- 搜索、读取和总结项目文件\n- 在写文件前做安全检查和 diff preview\n- 执行 bash 命令，并通过权限系统保护危险操作\n- 保存会话，读取项目记忆，压缩上下文\n- 支持 slash commands、hooks、skills 和 subagents\n- 用 worktree 隔离任务，并通过 MCP / ToolSearch 扩展工具\n\n一句话：模型负责推理，harness 负责上下文、工具、权限、执行、状态和反馈循环。\n\n## 默认测试模型\n\n教程主线使用 Anthropic Messages API 的消息形状，也就是 `tool_use`、`tool_result` 和 `input_schema`。为了降低测试成本、让更多人能跑起来，项目默认用 DeepSeek 的 Anthropic-compatible endpoint 做真实模型测试：\n\n```bash\nexport ANTHROPIC_AUTH_TOKEN=\"sk-...\"\nexport ANTHROPIC_BASE_URL=\"https://api.deepseek.com/anthropic\"\n```\n\n教程示例默认模型以当天文档和快照代码为准，主线常用 `deepseek-v4-flash`。如果你想换成官方 Claude 或其他兼容服务，只要保留 Anthropic Messages API 的协议形状，改 token、base URL 和 `--model` 即可。\n\n## 14 天路线\n\n前 7 天先做出一个能用的单 Agent CLI，后 7 天把它升级成更完整的 Claude Code 风格 harness。\n\n| Day | 主题 | 学到的 harness 能力 |\n|---|---|---|\n| 1 | Hello Agent | CLI、REPL、MockProvider、最小 Agent Loop |\n| 2 | Real Model + Tool Calling | AnthropicProvider、`tool_use` / `tool_result` |\n| 3 | File + Web Tools | cwd 边界、文件读取、搜索、网页工具 |\n| 4 | Safe Edit | read-before-edit、字符串替换、diff preview |\n| 5 | Bash + Permission | 命令执行、权限请求、后台任务 |\n| 6 | Session + Memory | 会话 JSONL、项目记忆、memdir |\n| 7 | Slash + Hooks | slash command、hooks、cron `/loop` |\n| 8 | Interactive Shell + Plan Mode | 交互式 shell、TodoWrite、Plan Mode 审批闭环 |\n| 9 | Skills | 按需加载知识和工作流 |\n| 10 | Subagents | 子 Agent 派发和结果回填 |\n| 11 | Context Compact | 长上下文压缩、成本追踪 |\n| 12 | Agent Coordinator | 极简多 Agent 协作 |\n| 13 | Worktree + Final Demo | worktree 隔离、端到端代码任务 |\n| 14 | MCP + ToolSearch | MCP 客户端、工具发现、工具扩展 |\n\n当前仓库已经包含前 8 天的教程和参考快照。后续内容会继续在同一条路线里补齐。\n\n## 怎么开始\n\n如果你是跟教程学习，从 Day 1 文档开始，在自己的 `agent-code` 项目里持续修改：\n\n```bash\nopen docs/day-01-hello-agent.md\n```\n\n如果只想运行仓库里的完成版参考快照：\n\n```bash\ncd packages/day-01-hello-agent\nuv sync\nuv run agent-code \"用 echo 工具说 hi\"\nuv run pytest\n```\n\n测试某一天时，建议进入对应目录再跑，避免 pytest 从仓库根目录收集到多个 day 的同名测试文件：\n\n```bash\ncd packages/day-02-real-model-tool-calling\nuv run pytest\n```\n\n## 网页版\n\n这个项目还有一个网页教程版本，源码在 `agent-code-learn/`。本地预览：\n\n```bash\ncd agent-code-learn\nnpm install\nnpm run dev\n```\n\n然后打开 `http://localhost:3000`。线上站点按当前网页项目元信息使用 `buildcc.dev`，如果你访问时还没部署好，可以先用本地预览。\n\n## 教学版项目架构\n\n```mermaid\nflowchart TD\n User[\"用户输入\"] --> CLI[\"Typer CLI / REPL / Slash Router\"]\n CLI --> Agent[\"Agent Loop\"]\n Agent --> Provider[\"ModelProvider<br/>Mock / Anthropic\"]\n Provider --> Model[\"Claude 或 Anthropic-compatible API\"]\n\n Agent --> Tools[\"Tool Registry\"]\n Tools --> FileTools[\"File / Web / Safe Edit\"]\n Tools --> Bash[\"Bash Tool\"]\n Tools --> Memory[\"Session / Memory\"]\n Tools --> Ext[\"Hooks / Skills / Subagents / MCP Lite\"]\n\n FileTools --> Safety[\"cwd 边界 / diff preview / read-before-edit\"]\n Bash --> Permission[\"Permission Engine\"]\n Safety --> Workspace[\"学习者的 agent-code 项目\"]\n Permission --> Workspace\n```\n\n## 项目结构\n\n```txt\ndocs/ 14 天教程文档\npackages/day-*/ 每一天独立可运行的教学快照\ndemo/ 当前综合 demo 项目\nagent-code-learn/ 网页版教程\n\n```\n\n注意：教程读者不是每天新建一个 `packages/day-*`。这些目录是参考答案快照。真正学习时，我们是在自己的 `agent-code` 项目里从 Day 1 持续改到 Day 14。\n\n## 欢迎反馈\n\n欢迎提 issue、discussion 或 PR，尤其是这几类：\n\n- 某一步命令跑不通，或者输出和文档对不上\n- 教程里某段解释不清楚\n- Claude Code 架构理解有偏差\n- DeepSeek / Claude / 兼容 endpoint 的运行差异\n- 英文翻译不自然\n- 网页版排版、交互或代码 diff 有问题\n\n如果你也在研究 Agent Harness，欢迎把你的问题、踩坑记录和改进建议一起丢过来。这个项目最有价值的部分，不是“我写完了一个教程”，而是大家能把一个真实代码 Agent 的外层工程系统拆开看懂。\n\n## 声明\n\nThis is an educational implementation. We reference the publicly visible Claude Code source snapshot to understand its architecture, but rewrite everything in Python with teaching-friendly simplifications. It is not affiliated with Anthropic.\n\n## License\n\nMIT\n"}, "95e5b18fe00c0059c0a7c5d43ad4d349cd2cde49": {"t": 1785763861.119154, "n": 5132, "h": "adebccc60c624ef2", "c": "# 14 天手搓 Claude Code CLI\n\n[English](./README.en.md)\n\n这个项目是一个教学版 Code Agent CLI。我们用 Python 从零实现一个 Claude Code 风格的 `agent-code`，重点学习模型外层那套 harness：CLI 运行时、Agent Loop、工具调用、权限、文件编辑、命令执行、会话记忆、hooks、skills、subagents、worktree 和 MCP 工具生态。\n\n它不是 Claude Code 的完整复刻，也不追求产品级能力。目标更简单：跟着 14 天教程，把一个能读代码、改文件、跑命令、管理上下文的代码 Agent 一步步手写出来。\n\n## 为什么做这个项目\n\n我一直想系统学 Agent Harness，但一开始不知道从哪里下手。后来有人跟我说，与其泛泛看文章，不如直接研究 Claude Code 这种真实产品是怎么设计的。\n\n正好前段时间有一份 Claude Code 源码快照公开可见，我就先让 AI 带着自己读了一遍，看看官方把哪些能力当成一等工具，哪些逻辑放在 CLI runtime，哪些逻辑放在模型外层的 harness 里。\n\n读完以后，我决定把这条学习路径重新整理成教程：不用 TypeScript 复刻官方实现，而是用学习者更容易跑起来的 Python，把核心机制拆成 14 天。每一天都能运行，每一天都能看见一个新的 harness 边界。\n\n整个过程也大量使用了 AI 协作。如果你觉得某些文案、翻译或者解释有一点 AI 味，欢迎直接提 issue 或 PR。这个项目本来就是边学边改出来的。\n\n## 你会做出什么\n\n最后的 CLI 叫 `agent-code`。它会逐步具备这些能力：\n\n- 接收一次性 prompt 或进入终端 REPL\n- 调用真实模型，并处理 `tool_use` / `tool_result`\n- 搜索、读取和总结项目文件\n- 在写文件前做安全检查和 diff preview\n- 执行 bash 命令，并通过权限系统保护危险操作\n- 保存会话，读取项目记忆，压缩上下文\n- 支持 slash commands、hooks、skills 和 subagents\n- 用 worktree 隔离任务，并通过 MCP / ToolSearch 扩展工具\n\n一句话：模型负责推理，harness 负责上下文、工具、权限、执行、状态和反馈循环。\n\n## 默认测试模型\n\n教程主线使用 Anthropic Messages API 的消息形状，也就是 `tool_use`、`tool_result` 和 `input_schema`。为了降低测试成本、让更多人能跑起来，项目默认用 DeepSeek 的 Anthropic-compatible endpoint 做真实模型测试：\n\n```bash\nexport ANTHROPIC_AUTH_TOKEN=\"sk-...\"\nexport ANTHROPIC_BASE_URL=\"https://api.deepseek.com/anthropic\"\n```\n\n教程示例默认模型以当天文档和快照代码为准，主线常用 `deepseek-v4-flash`。如果你想换成官方 Claude 或其他兼容服务，只要保留 Anthropic Messages API 的协议形状，改 token、base URL 和 `--model` 即可。\n\n## 14 天路线\n\n前 7 天先做出一个能用的单 Agent CLI，后 7 天把它升级成更完整的 Claude Code 风格 harness。\n\n| Day | 主题 | 学到的 harness 能力 |\n|---|---|---|\n| 1 | Hello Agent | CLI、REPL、MockProvider、最小 Agent Loop |\n| 2 | Real Model + Tool Calling | AnthropicProvider、`tool_use` / `tool_result` |\n| 3 | File + Web Tools | cwd 边界、文件读取、搜索、网页工具 |\n| 4 | Safe Edit | read-before-edit、字符串替换、diff preview |\n| 5 | Bash + Permission | 命令执行、权限请求、后台任务 |\n| 6 | Session + Memory | 会话 JSONL、项目记忆、memdir |\n| 7 | Slash + Hooks | slash command、hooks、cron `/loop` |\n| 8 | TodoWrite + Plan Mode | 计划模式、任务列表、执行约束 |\n| 9 | Skills | 按需加载知识和工作流 |\n| 10 | Subagents | 子 Agent 派发和结果回填 |\n| 11 | Context Compact | 长上下文压缩、成本追踪 |\n| 12 | Agent Coordinator | 极简多 Agent 协作 |\n| 13 | Worktree + Final Demo | worktree 隔离、端到端代码任务 |\n| 14 | MCP + ToolSearch | MCP 客户端、工具发现、工具扩展 |\n\n当前仓库已经包含前 7 天的教程和参考快照。后 7 天会继续在同一条路线里补齐。\n\n## 怎么开始\n\n如果你是跟教程学习，从 Day 1 文档开始，在自己的 `agent-code` 项目里持续修改：\n\n```bash\nopen docs/day-01-hello-agent.md\n```\n\n如果只想运行仓库里的完成版参考快照：\n\n```bash\ncd packages/day-01-hello-agent\nuv sync\nuv run agent-code \"用 echo 工具说 hi\"\nuv run pytest\n```\n\n测试某一天时，建议进入对应目录再跑，避免 pytest 从仓库根目录收集到多个 day 的同名测试文件：\n\n```bash\ncd packages/day-02-real-model-tool-calling\nuv run pytest\n```\n\n## 网页版\n\n这个项目还有一个网页教程版本，源码在 `agent-code-learn/`。本地预览：\n\n```bash\ncd agent-code-learn\nnpm install\nnpm run dev\n```\n\n然后打开 `http://localhost:3000`。线上站点按当前网页项目元信息使用 `buildcc.dev`，如果你访问时还没部署好，可以先用本地预览。\n\n## 教学版项目架构\n\n```mermaid\nflowchart TD\n User[\"用户输入\"] --> CLI[\"Typer CLI / REPL / Slash Router\"]\n CLI --> Agent[\"Agent Loop\"]\n Agent --> Provider[\"ModelProvider<br/>Mock / Anthropic\"]\n Provider --> Model[\"Claude 或 Anthropic-compatible API\"]\n\n Agent --> Tools[\"Tool Registry\"]\n Tools --> FileTools[\"File / Web / Safe Edit\"]\n Tools --> Bash[\"Bash Tool\"]\n Tools --> Memory[\"Session / Memory\"]\n Tools --> Ext[\"Hooks / Skills / Subagents / MCP Lite\"]\n\n FileTools --> Safety[\"cwd 边界 / diff preview / read-before-edit\"]\n Bash --> Permission[\"Permission Engine\"]\n Safety --> Workspace[\"学习者的 agent-code 项目\"]\n Permission --> Workspace\n```\n\n## Claude Code 源码架构参考图\n\n`reference/claude-code-official/` 是公开可见源码快照的本地研究副本。我们只用它确认架构边界，不把官方 TypeScript 源码、prompt 或内部协议原样翻译进教程。\n\n```mermaid\nflowchart TD\n Main[\"src/main.tsx<br/>CLI 入口\"] --> Commands[\"src/commands/*<br/>Slash Commands\"]\n Main --> UI[\"React + Ink<br/>Terminal UI\"]\n Main --> Query[\"QueryEngine<br/>模型调用与工具循环\"]\n\n Query --> Tools[\"src/tools/*<br/>Bash / Read / Edit / MCP / Agent / Skill\"]\n Query --> Context[\"context / state / memdir<br/>上下文与记忆\"]\n Tools --> Permission[\"hooks/toolPermission<br/>权限检查\"]\n Tools --> Services[\"services/*<br/>API / MCP / Compact / LSP / Analytics\"]\n\n Main --> Bridge[\"bridge / remote / server<br/>IDE 与远程会话\"]\n Main --> Plugins[\"plugins / skills<br/>扩展系统\"]\n Query --> Coordinator[\"coordinator / tasks<br/>多 Agent 与任务系统\"]\n```\n\n## 项目结构\n\n```txt\ndocs/ 14 天教程文档\npackages/day-*/ 每一天独立可运行的教学快照\ndemo/ 当前综合 demo 项目\nagent-code-learn/ 网页版教程\n```\n\n注意：教程读者不是每天新建一个 `packages/day-*`。这些目录是参考答案快照。真正学习时，我们是在自己的 `agent-code` 项目里从 Day 1 持续改到 Day 14。\n\n## 欢迎反馈\n\n欢迎提 issue、discussion 或 PR，尤其是这几类：\n\n- 某一步命令跑不通，或者输出和文档对不上\n- 教程里某段解释不清楚\n- Claude Code 架构理解有偏差\n- DeepSeek / Claude / 兼容 endpoint 的运行差异\n- 英文翻译不自然\n- 网页版排版、交互或代码 diff 有问题\n\n如果你也在研究 Agent Harness，欢迎把你的问题、踩坑记录和改进建议一起丢过来。这个项目最有价值的部分，不是“我写完了一个教程”，而是大家能把一个真实代码 Agent 的外层工程系统拆开看懂。\n\n## 声明\n\nThis is an educational implementation. We reference the public Claude Code source snapshot under `reference/claude-code-official/` to understand its architecture, but rewrite everything in Python with teaching-friendly simplifications. It is not affiliated with Anthropic.\n\n## License\n\nMIT\n"}, "1ebe86e4bd8a5c06c315bbe28c64e5cbdfdbf017": {"t": 1785763862.71475, "n": 5199, "h": "1634bf02d4011317", "c": "# 14 天手搓 Claude Code CLI\n\n[English](./README.en.md)\n\n这个项目是一个教学版 Code Agent CLI。我们用 Python 从零实现一个 Claude Code 风格的 `agent-code`，重点学习模型外层那套 harness：CLI 运行时、Agent Loop、工具调用、权限、文件编辑、命令执行、会话记忆、hooks、skills、subagents、worktree 和 MCP 工具生态。\n\n它不是 Claude Code 的完整复刻，也不追求产品级能力。目标更简单：跟着 14 天教程，把一个能读代码、改文件、跑命令、管理上下文的代码 Agent 一步步手写出来。\n\n## 为什么做这个项目\n\n我一直想系统学 Agent Harness，但一开始不知道从哪里下手。后来有人跟我说，与其泛泛看文章，不如直接研究 Claude Code 这种真实产品是怎么设计的。\n\n正好前段时间有一份 Claude Code 源码快照公开可见，我就先让 AI 带着自己读了一遍，看看官方把哪些能力当成一等工具，哪些逻辑放在 CLI runtime，哪些逻辑放在模型外层的 harness 里。\n\n读完以后，我决定把这条学习路径重新整理成教程：不用 TypeScript 复刻官方实现，而是用学习者更容易跑起来的 Python，把核心机制拆成 14 天。每一天都能运行，每一天都能看见一个新的 harness 边界。\n\n整个过程也大量使用了 AI 协作。如果你觉得某些文案、翻译或者解释有一点 AI 味，欢迎直接提 issue 或 PR。这个项目本来就是边学边改出来的。\n\n## 你会做出什么\n\n最后的 CLI 叫 `agent-code`。它会逐步具备这些能力：\n\n- 接收一次性 prompt 或进入终端 REPL\n- 调用真实模型，并处理 `tool_use` / `tool_result`\n- 搜索、读取和总结项目文件\n- 在写文件前做安全检查和 diff preview\n- 执行 bash 命令，并通过权限系统保护危险操作\n- 保存会话，读取项目记忆，压缩上下文\n- 支持 slash commands、hooks、skills 和 subagents\n- 用 worktree 隔离任务，并通过 MCP / ToolSearch 扩展工具\n\n一句话：模型负责推理，harness 负责上下文、工具、权限、执行、状态和反馈循环。\n\n## 默认测试模型\n\n教程主线使用 Anthropic Messages API 的消息形状，也就是 `tool_use`、`tool_result` 和 `input_schema`。为了降低测试成本、让更多人能跑起来，项目默认用 DeepSeek 的 Anthropic-compatible endpoint 做真实模型测试：\n\n```bash\nexport ANTHROPIC_AUTH_TOKEN=\"sk-...\"\nexport ANTHROPIC_BASE_URL=\"https://api.deepseek.com/anthropic\"\n```\n\n教程示例默认模型以当天文档和快照代码为准，主线常用 `deepseek-v4-flash`。如果你想换成官方 Claude 或其他兼容服务，只要保留 Anthropic Messages API 的协议形状，改 token、base URL 和 `--model` 即可。\n\n## 14 天路线\n\n前 7 天先做出一个能用的单 Agent CLI，后 7 天把它升级成更完整的 Claude Code 风格 harness。\n\n| Day | 主题 | 学到的 harness 能力 |\n|---|---|---|\n| 1 | Hello Agent | CLI、REPL、MockProvider、最小 Agent Loop |\n| 2 | Real Model + Tool Calling | AnthropicProvider、`tool_use` / `tool_result` |\n| 3 | File + Web Tools | cwd 边界、文件读取、搜索、网页工具 |\n| 4 | Safe Edit | read-before-edit、字符串替换、diff preview |\n| 5 | Bash + Permission | 命令执行、权限请求、后台任务 |\n| 6 | Session + Memory | 会话 JSONL、项目记忆、memdir |\n| 7 | Slash + Hooks | slash command、hooks、cron `/loop` |\n| 8 | TodoWrite + Plan Mode | 计划模式、任务列表、执行约束 |\n| 9 | Skills | 按需加载知识和工作流 |\n| 10 | Subagents | 子 Agent 派发和结果回填 |\n| 11 | Context Compact | 长上下文压缩、成本追踪 |\n| 12 | Agent Coordinator | 极简多 Agent 协作 |\n| 13 | Worktree + Final Demo | worktree 隔离、端到端代码任务 |\n| 14 | MCP + ToolSearch | MCP 客户端、工具发现、工具扩展 |\n\n当前仓库已经包含前 7 天的教程和参考快照。后 7 天会继续在同一条路线里补齐。\n\n## 怎么开始\n\n如果你是跟教程学习，从 Day 1 文档开始，在自己的 `agent-code` 项目里持续修改：\n\n```bash\nopen docs/day-01-hello-agent.md\n```\n\n如果只想运行仓库里的完成版参考快照：\n\n```bash\ncd packages/day-01-hello-agent\nuv sync\nuv run agent-code \"用 echo 工具说 hi\"\nuv run pytest\n```\n\n测试某一天时，建议进入对应目录再跑，避免 pytest 从仓库根目录收集到多个 day 的同名测试文件：\n\n```bash\ncd packages/day-02-real-model-tool-calling\nuv run pytest\n```\n\n## 网页版\n\n这个项目还有一个网页教程版本，源码在 `agent-code-learn/`。本地预览：\n\n```bash\ncd agent-code-learn\nnpm install\nnpm run dev\n```\n\n然后打开 `http://localhost:3000`。线上站点按当前网页项目元信息使用 `buildcc.dev`，如果你访问时还没部署好，可以先用本地预览。\n\n## 教学版项目架构\n\n```mermaid\nflowchart TD\n User[\"用户输入\"] --> CLI[\"Typer CLI / REPL / Slash Router\"]\n CLI --> Agent[\"Agent Loop\"]\n Agent --> Provider[\"ModelProvider<br/>Mock / Anthropic\"]\n Provider --> Model[\"Claude 或 Anthropic-compatible API\"]\n\n Agent --> Tools[\"Tool Registry\"]\n Tools --> FileTools[\"File / Web / Safe Edit\"]\n Tools --> Bash[\"Bash Tool\"]\n Tools --> Memory[\"Session / Memory\"]\n Tools --> Ext[\"Hooks / Skills / Subagents / MCP Lite\"]\n\n FileTools --> Safety[\"cwd 边界 / diff preview / read-before-edit\"]\n Bash --> Permission[\"Permission Engine\"]\n Safety --> Workspace[\"学习者的 agent-code 项目\"]\n Permission --> Workspace\n```\n\n## Claude Code 源码架构参考图\n\n`reference/claude-code-official/` 是公开可见源码快照的本地研究副本。我们只用它确认架构边界，不把官方 TypeScript 源码、prompt 或内部协议原样翻译进教程。\n\n```mermaid\nflowchart TD\n Main[\"src/main.tsx<br/>CLI 入口\"] --> Commands[\"src/commands/*<br/>Slash Commands\"]\n Main --> UI[\"React + Ink<br/>Terminal UI\"]\n Main --> Query[\"QueryEngine<br/>模型调用与工具循环\"]\n\n Query --> Tools[\"src/tools/*<br/>Bash / Read / Edit / MCP / Agent / Skill\"]\n Query --> Context[\"context / state / memdir<br/>上下文与记忆\"]\n Tools --> Permission[\"hooks/toolPermission<br/>权限检查\"]\n Tools --> Services[\"services/*<br/>API / MCP / Compact / LSP / Analytics\"]\n\n Main --> Bridge[\"bridge / remote / server<br/>IDE 与远程会话\"]\n Main --> Plugins[\"plugins / skills<br/>扩展系统\"]\n Query --> Coordinator[\"coordinator / tasks<br/>多 Agent 与任务系统\"]\n```\n\n## 项目结构\n\n```txt\ndocs/ 14 天教程文档\npackages/day-*/ 每一天独立可运行的教学快照\ndemo/ 当前综合 demo 项目\nagent-code-learn/ 网页版教程\nreference/claude-code-official/ Claude Code 源码快照，架构参考用（需要自己 clone）\n```\n\n注意：教程读者不是每天新建一个 `packages/day-*`。这些目录是参考答案快照。真正学习时，我们是在自己的 `agent-code` 项目里从 Day 1 持续改到 Day 14。\n\n## 欢迎反馈\n\n欢迎提 issue、discussion 或 PR，尤其是这几类：\n\n- 某一步命令跑不通，或者输出和文档对不上\n- 教程里某段解释不清楚\n- Claude Code 架构理解有偏差\n- DeepSeek / Claude / 兼容 endpoint 的运行差异\n- 英文翻译不自然\n- 网页版排版、交互或代码 diff 有问题\n\n如果你也在研究 Agent Harness，欢迎把你的问题、踩坑记录和改进建议一起丢过来。这个项目最有价值的部分，不是“我写完了一个教程”，而是大家能把一个真实代码 Agent 的外层工程系统拆开看懂。\n\n## 声明\n\nThis is an educational implementation. We reference the public Claude Code source snapshot under `reference/claude-code-official/` to understand its architecture, but rewrite everything in Python with teaching-friendly simplifications. It is not affiliated with Anthropic.\n\n## License\n\nMIT\n"}}}} |