[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-82140":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":14,"stars7d":16,"stars30d":17,"stars90d":15,"forks30d":15,"starsTrendScore":18,"compositeScore":19,"rankGlobal":10,"rankLanguage":10,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":23,"hasPages":21,"topics":24,"createdAt":10,"pushedAt":10,"updatedAt":25,"readmeContent":26,"aiSummary":27,"trendingCount":15,"starSnapshotCount":15,"syncStatus":28,"lastSyncTime":29,"discoverSource":30},82140,"14days-build-claude-code-cli","bozhouDev\u002F14days-build-claude-code-cli","bozhouDev","网页版教程，看起来会舒服一点","https:\u002F\u002Fbuildcc.dev",null,"Python",218,20,1,0,11,115,4,61.47,"MIT License",false,"main",true,[],"2026-06-12 04:01:37","# 14 天手搓 Claude Code CLI\n\n[English](.\u002FREADME.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` \u002F `tool_result`\n- 搜索、读取和总结项目文件\n- 在写文件前做安全检查和 diff preview\n- 执行 bash 命令，并通过权限系统保护危险操作\n- 保存会话，读取项目记忆，压缩上下文\n- 支持 slash commands、hooks、skills 和 subagents\n- 用 worktree 隔离任务，并通过 MCP \u002F 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:\u002F\u002Fapi.deepseek.com\u002Fanthropic\"\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` \u002F `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 `\u002Floop` |\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\u002Fday-01-hello-agent.md\n```\n\n如果只想运行仓库里的完成版参考快照：\n\n```bash\ncd packages\u002Fday-01-hello-agent\nuv sync\nuv run agent-code \"用 echo 工具说 hi\"\nuv run pytest\n```\n\n测试某一天时，建议进入对应目录再跑，避免 pytest 从仓库根目录收集到多个 day 的同名测试文件：\n\n```bash\ncd packages\u002Fday-02-real-model-tool-calling\nuv run pytest\n```\n\n## 网页版\n\n这个项目还有一个网页教程版本，源码在 `agent-code-learn\u002F`。本地预览：\n\n```bash\ncd agent-code-learn\nnpm install\nnpm run dev\n```\n\n然后打开 `http:\u002F\u002Flocalhost:3000`。线上站点按当前网页项目元信息使用 `buildcc.dev`，如果你访问时还没部署好，可以先用本地预览。\n\n## 教学版项目架构\n\n```mermaid\nflowchart TD\n  User[\"用户输入\"] --> CLI[\"Typer CLI \u002F REPL \u002F Slash Router\"]\n  CLI --> Agent[\"Agent Loop\"]\n  Agent --> Provider[\"ModelProvider\u003Cbr\u002F>Mock \u002F Anthropic\"]\n  Provider --> Model[\"Claude 或 Anthropic-compatible API\"]\n\n  Agent --> Tools[\"Tool Registry\"]\n  Tools --> FileTools[\"File \u002F Web \u002F Safe Edit\"]\n  Tools --> Bash[\"Bash Tool\"]\n  Tools --> Memory[\"Session \u002F Memory\"]\n  Tools --> Ext[\"Hooks \u002F Skills \u002F Subagents \u002F MCP Lite\"]\n\n  FileTools --> Safety[\"cwd 边界 \u002F diff preview \u002F read-before-edit\"]\n  Bash --> Permission[\"Permission Engine\"]\n  Safety --> Workspace[\"学习者的 agent-code 项目\"]\n  Permission --> Workspace\n```\n\n## Claude Code 源码架构参考图\n\n`reference\u002Fclaude-code-official\u002F` 是公开可见源码快照的本地研究副本。我们只用它确认架构边界，不把官方 TypeScript 源码、prompt 或内部协议原样翻译进教程。\n\n```mermaid\nflowchart TD\n  Main[\"src\u002Fmain.tsx\u003Cbr\u002F>CLI 入口\"] --> Commands[\"src\u002Fcommands\u002F*\u003Cbr\u002F>Slash Commands\"]\n  Main --> UI[\"React + Ink\u003Cbr\u002F>Terminal UI\"]\n  Main --> Query[\"QueryEngine\u003Cbr\u002F>模型调用与工具循环\"]\n\n  Query --> Tools[\"src\u002Ftools\u002F*\u003Cbr\u002F>Bash \u002F Read \u002F Edit \u002F MCP \u002F Agent \u002F Skill\"]\n  Query --> Context[\"context \u002F state \u002F memdir\u003Cbr\u002F>上下文与记忆\"]\n  Tools --> Permission[\"hooks\u002FtoolPermission\u003Cbr\u002F>权限检查\"]\n  Tools --> Services[\"services\u002F*\u003Cbr\u002F>API \u002F MCP \u002F Compact \u002F LSP \u002F Analytics\"]\n\n  Main --> Bridge[\"bridge \u002F remote \u002F server\u003Cbr\u002F>IDE 与远程会话\"]\n  Main --> Plugins[\"plugins \u002F skills\u003Cbr\u002F>扩展系统\"]\n  Query --> Coordinator[\"coordinator \u002F tasks\u003Cbr\u002F>多 Agent 与任务系统\"]\n```\n\n## 项目结构\n\n```txt\ndocs\u002F                          14 天教程文档\npackages\u002Fday-*\u002F                每一天独立可运行的教学快照\ndemo\u002F                          当前综合 demo 项目\nagent-code-learn\u002F              网页版教程\n```\n\n注意：教程读者不是每天新建一个 `packages\u002Fday-*`。这些目录是参考答案快照。真正学习时，我们是在自己的 `agent-code` 项目里从 Day 1 持续改到 Day 14。\n\n## 欢迎反馈\n\n欢迎提 issue、discussion 或 PR，尤其是这几类：\n\n- 某一步命令跑不通，或者输出和文档对不上\n- 教程里某段解释不清楚\n- Claude Code 架构理解有偏差\n- DeepSeek \u002F Claude \u002F 兼容 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\u002Fclaude-code-official\u002F` 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","这个项目是一个教学版的Code Agent CLI，旨在通过14天教程从零开始用Python实现一个类似于Claude Code风格的代码代理工具。其核心功能包括CLI运行时、Agent Loop、工具调用、权限管理、文件编辑与命令执行等，并且支持会话记忆和上下文压缩等功能。特别适合希望深入理解AI辅助编程工具内部机制的学习者或开发者使用。通过跟随该项目提供的逐步指南，参与者能够构建出一个可以读取代码、修改文件、执行命令以及管理上下文状态的完整代码代理应用。此外，该项目还强调了利用AI协作进行开发的过程，鼓励社区贡献以不断完善内容。",2,"2026-06-11 04:07:51","CREATED_QUERY"]