一个可运行的、教学级的 Claude Code 精简复刻在终端里运行的 AI 编程助手CLI Agent。用 TypeScript Bun 编写不依赖任何模型 SDK直接用fetch调 HTTP / SSE。它对照 Claude Code 的分层结构从零实现了一个 Agent 的核心骨架流式对话循环、工具调用、权限闸门、上下文压缩、会话持久化、子助手、MCP 接入、容错重试。目标是让你读完代码就能理解Claude Code 这类工具到底是怎么转起来的。命令名wonder-cc数据目录.wonder-cc/项目资料文件AGENTS.md自动注入系统提示类似 CLAUDE.md特性多模型适配内置 Anthropic 与 OpenAI 兼容两套适配器。DeepSeek、OpenAI 官方、以及任意 OpenAI 兼容网关都可用通过环境变量切换自动探测。流式对话SSE 逐字输出带思考转圈、工具过程、底部状态栏。工具系统read_file/write_file/edit_text/bash/TodoWrite/Task外加 MCP 外部工具。三级权限闸门只读命令直接放行写操作征求同意rm -rf /、sudo、curl|bash等危险命令任何模式都拦截。支持这次允许 / 永远允许 / 拒绝规则可跨会话记忆。上下文工程粗估 token、三档水位正常 / 偏满 / 危险危险水位自动把旧对话压缩成摘要保留最近几轮原文。会话持久化JSONL 转录逐条追加崩溃不丢历史/resume从压缩快照恢复命令历史、用量记账、全局偏好都落盘。子助手Task主助手可派活给独立上下文的子助手三工种explore只读探索/plan方案规划/code动手实现中间过程不占主对话。MCP 客户端通过 stdio JSON-RPC 接入外部工具生态工具名统一为mcp__server__tool。斜杠命令/init自动扫描项目生成 AGENTS.md、/resume、/compact、/usage、权限切换等。提及文件输入里写src/foo.ts自动读取文件内容附进消息。容错重试429 / 5xx / 网络抖动按指数退避自动重试401 / 400 等立即报错流式开始后不重试避免文字重复打印。技术栈项选择运行时 / 包管理 / 测试Bunbun run/bun test自动加载.env语言TypeScriptESM模型接入原生fetch SSE无 SDK终端交互node:readline/promises ANSI 转义码自绘 spinner / 状态栏子进程node:child_processspawnbash 工具、MCP server持久化JSONL 追加写 JSON 档案架构分层目录结构对照 Claude Code 布局src/ ├── entrypoints/cli.ts # 薄入口终端 REPL只做显示与提问 ├── main.ts # 启动编排装配 config → adapter → tools → 系统提示 → 权限 ├── query.ts # 核心对话循环async generator产出事件不碰界面 ├── context.ts # 系统提示拼装身份/环境/工具清单/规矩 AGENTS.md ├── Tool.ts # Tool 接口定义说明书 execute ├── config/environment.ts # 环境变量读取与服务商自动探测 ├── constants/product.ts # 产品级常量 ├── services/ │ ├── api/ │ │ ├── adapter.ts # 模型适配器Anthropic / OpenAI 兼容 SSE 解析 │ │ ├── types.ts # 内部统一普通话类型Message / ContentBlock │ │ ├── errors.ts # ApiError 指数退避重试 │ │ └── usage.ts # 用量记账与成本估算 │ ├── mcp/ │ │ ├── client.ts # MCP stdio 客户端JSON-RPC 2.0 │ │ └── loader.ts # MCP 工具加载与包装 │ ├── session.ts # JSONL 会话转录meta/message/snapshot │ └── task.ts # 子助手sub-agent ├── tools/ # 内置工具 权限闸门 路径防护 │ ├── permission.ts # 命令分级safe/write/danger与闸门 │ ├── paths.ts # safePath防 ../ 越界与符号链接逃逸 │ ├── readFile.ts / writeFile.ts / editText.ts / bash.ts / todoWrite.ts / task.ts ├── query/ │ ├── tokens.ts # token 粗估 │ ├── tokenBudget.ts # 三档水位 │ └── compression.ts # 上下文压缩 ├── bootstrap/ │ ├── paths.ts # 数据目录约定 │ ├── state.ts # 全局档案 state.json │ └── history.ts # 命令历史 history.log ├── commands/ │ ├── registry.ts # 斜杠命令登记 │ ├── init.ts # /init 生成 AGENTS.md │ └── mentions.ts # 提及文件展开 └── ui/ ├── display.ts # 终端渲染颜色/工具过程/状态栏 └── spinner.ts # 思考转圈核心设计内核与界面解耦。query()是一个 async generator只yield事件assistant_text_delta/tool_start/tool_result/usage/compressing/done不打印任何东西CLI 层消费事件来渲染。权限闸门也不直接提问而是通过ToolContext.ask回调把问题抛给上层终端弹窗 / 子助手场景自动拒绝。安装与运行需要 Bun ≥ 1.0。# 1. 安装依赖本项目零运行时依赖这步主要是建 Bun 环境buninstall# 2. 配置模型密钥二选一或多选cp.env.example .env# 编辑 .env 填入 DEEPSEEK_API_KEY 等# 3. 直接运行bun start# 或bun run src/entrypoints/cli.ts想在任意目录用wonder-cc启动可加一个 shell 别名入口是.ts需由 Bun 执行aliaswonder-ccbun run /绝对路径/wonder-claude-code/src/entrypoints/cli.ts模型配置所有配置通过环境变量写进.env或export到 shell 均可。服务商与密钥环境变量说明默认值DEEPSEEK_API_KEYDeepSeek 密钥—DEEPSEEK_BASE_URLDeepSeek 地址https://api.deepseek.comDEEPSEEK_MODEL模型名deepseek-chat推理模型可用deepseek-reasonerOPENAI_API_KEYOpenAI 官方 / 兼容网关密钥—OPENAI_BASE_URLOpenAI 地址https://api.openai.com/v1OPENAI_MODEL模型名gpt-4o-miniANTHROPIC_API_KEYAnthropic 密钥—ANTHROPIC_BASE_URLAnthropic 地址https://api.anthropic.comANTHROPIC_MODEL模型名claude-sonnet-4-20250514自动探测规则未显式指定时若设置了OPENAI_API_KEY→ 优先用 OpenAI否则若有DEEPSEEK_API_KEY→ 用 DeepSeek否则若有ANTHROPIC_API_KEY→ 用 Anthropic。DeepSeek 与 OpenAI 走同一套 OpenAI 兼容协议baseURL支持裸域名、以/v1结尾、或已含/chat/completions三种写法会自动补齐路径。其他环境变量环境变量说明WONDER_PROVIDER强制指定服务商deepseek/openai/anthropicWONDER_CONTEXT_WINDOW覆盖上下文窗口大小token 数教学/测试用WONDER_PERMISSION_MODE启动时的权限模式default/acceptEdits/bypassPermissionsWONDER_MCP_SERVERSMCP server 列表格式见下使用启动后直接输入问题即可。模型会自己决定是否调用工具读文件、跑命令、改代码等。斜杠命令命令作用/init派探索子助手扫描项目生成AGENTS.md已存在会先确认覆盖/resume列出历史会话选号恢复从压缩快照继续/compact手动压缩当前上下文/usage查看上下文占用水位与累计 token / 估算成本/mode查看当前权限模式/default切换到默认模式写 / 危险操作征求同意/acceptEdits自动允许文件编辑bash 写命令仍会问/bypass跳过所有权限确认谨慎使用/help显示帮助/exit或/quit、exit、quit退出自动保存命令历史内置工具工具能力权限read_file读文本文件超 4 万字符截断只读免确认write_file新建 / 覆盖 / 追加文件自动建父目录write 级edit_text精确小改replace要求原文唯一匹配或insert按行号插入write 级bash执行 shell 命令30s 超时输出截断 2 万字符按命令分级TodoWrite维护多步骤待办清单落盘.wonder-cc/todos.json纯记录免确认Task派活给子助手子助手内部再走闸门权限模式与命令分级safels/cat/grep/git status等只读命令直接执行。writerm/mv/ 安装依赖 /git commit/push/ 输出重定向等默认征求同意。dangerrm -rf /、sudo、mkfs、curl ... | bash、fork 炸弹等任何模式都拦截确认。询问时可选y这次允许/a以后同类都允许规则落盘记忆/n拒绝默认。子助手Task主助手可调用Task工具把活儿外包给独立上下文的子助手explore代码探索只给只读工具绝不改文件plan方案规划只读 待办清单产出分步计划code动手实现给全套工具继承主会话权限闸门。子助手的中间读文件 / 搜索过程通过进度行汇报、不刷爆主对话最终只回传一份结论。提及文件在输入里写相对路径程序会自动读取该文件并把内容包成file path...块附在消息末尾帮我看看 src/query.ts 这个循环有没有问题路径必须在工作目录内../越界会被拒绝单个文件超 2 万字符截断读不到会提示而不报错。MCP 外部工具通过环境变量配置 stdio 类型的 MCP server逗号分隔多台等号左边是名字、右边是启动命令exportWONDER_MCP_SERVERSmockbun scripts/mock-mcp-server.ts, fsnpx -y modelcontextprotocol/server-filesystem .启动时会自动握手initialize→tools/list把外部工具包装成mcp__server__tool。MCP 工具一律按 write 级过权限闸门某台 server 连不上只跳过并提示不影响启动。数据目录所有落盘数据都在工作目录下的.wonder-cc/.wonder-cc/ ├── state.json # 全局档案权限模式、永远允许规则、最近会话 id ├── history.log # 命令历史每行一条上下箭头翻阅 ├── usage.jsonl # 用量记账每次模型请求一行含估算成本 ├── todos.json # TodoWrite 待办清单 └── projects/工作目录编码/ └── session-id.jsonl # 会话转录meta / message / snapshot 三种行会话转录采用追加写每条消息、每次压缩快照写一行 JSON写到一半崩溃也不丢历史。压缩后会写一个snapshot作为恢复点/resume时从最后一个快照起叠加后续消息跳过冗长旧历史。成本单价是教学用的粗略参考价人民币 / 百万 token会随官方调价过时真实计费以厂商账单为准。测试与脚本buntest# 运行单元测试适配器翻译 / 权限分级 / token 预算 / 重试 / 提及 / 会话转录bun run smoke# 冒烟脚本scripts/下还有端到端验证脚本需要配置真实密钥e2e-stage1/2/3-*.ts最小闭环、真实 DeepSeek 流式工具调用、上下文压缩e2e-stage5-persistence.ts持久化与重启记忆验证e2e-stage6-extensions.tsMCP 全链路 子助手mock-mcp-server.ts最小 MCP server提供 echo / add 两个工具供测试接入。与真实 Claude Code 的差距教学简化点这是一个骨架级教学实现刻意省略了大量工程文件编辑是字符串替换edit_text非 AST / unified diff 补丁无图片 / 多模态、无 plan-mode、hooks、自定义斜杠命令文件、设置 UIMCP 只实现 stdio 传输与 tools 能力无 resources / prompts / SSE 传输权限是正则黑名单非静态分析token 为经验公式粗估非官方分词器无流式中断 / 编辑、无多会话并行、无命令自动补全。源码地址https://github.com/yzsunlei/wonder-claude-code配套学习文档guides/目录下有按主题分章的学习笔记part-01 ~ part-12 术语表 / 源码地图 / 阅读指南对照本项目的实现讲解 Claude Code 的各个子系统。第一部分 · 认识它篇内容第 1 篇 · 先认识它它是什么、四种露面方式、靠什么跑起来、代码仓库导览第 2 篇 · 启动的秘密敲下命令后的一瞬间、快速通道、命令参数管理、全局小本本第二部分 · 核心机制篇内容第 3 篇 · 一问一答怎么转起来对话循环、流式输出、长对话编排、聊天记录格式、任务中断第 4 篇 · 工具AI 的手工具是什么、随身工具箱、为什么不一次给全、危险操作把关、排队与打断第 5 篇 · 每次提问都塞了什么资料十几份背景资料、省钱的缓存、字数预算、自动划重点、记忆、图片语音第三部分 · 界面与连接篇内容第 6 篇 · 终端里的图形界面终端怎么画图、用做网页的思路做界面、自动排版、只改变化的地方、键鼠事件第 7 篇 · 连接外面的世界人脑、出错自救、外接能力、编辑器指挥、手机远程控制第四部分 · 数据与扩展篇内容第 8 篇 · 数据放哪、钱怎么算两个记事本、对话找回、后悔药、记账第 9 篇 · 怎么给它加功能斜杠命令、关键时刻插一脚、插件、派小弟并行干活第五部分 · 高级与工程篇内容第 10 篇 · 高级能力后台常驻、放手让它自己干、几种工作模式、语音与看屏幕第 11 篇 · 工程上的讲究一份代码变多个版本、打包拆分、性能优化、怎么测试第 12 篇 · 串起来完整走一遍修 bug 全过程、十五个关键设计选择、出问题怎么查、和同类工具的思路差异