Go 版迷你 Claude Code 优化复盘与扩展路线图

mini-claude-code 是一个用 Go 手写的命令行编码 Agent，目标是把 Claude Code 的核心工作方式浓缩进千余行可读代码：REPL 交互、Agent 循环、流式输出、文件读写与命令执行工具、会话持久化、危险命令人工确认，以及思考过程折叠。本文是对这份代码的一次系统复盘，分四部分：已修复的 Bug、刻意保留的设计边界、值得扩展的功能，以及代码质量补课。

mini-claude-code 架构与 Agent 循环

一、两个已修复的 Bug

流式工具调用 index 断档会 panic。 模型流式返回 tool_calls 时，代码先用 map 按 index 收集分片，再整理成完整列表。原实现假设 index 从 0 开始连续递增，一旦模型跳过某个 index（罕见但存在），取到的值是 nil，解引用直接 panic。修复方式是不做任何连续性假设：收集 map 里全部 key，排序后逐个遍历。

空 content 的 assistant 消息触发 API 400。 接 glm-5.2 这类模型时，带 tool_calls 的 assistant 消息 content 是空字符串。把这条消息原样回喂给 API，服务端直接拒绝，报 data did not match any variant。修复是在回喂前检查：content 为空且携带工具调用的消息，补一个空格占位。

这两个 Bug 都很典型：前者是对流式协议过于信任，后者是各家模型对消息格式的细节要求不一致，接多模型时尤其容易踩。

二、六处设计边界，不是 Bug

MVP 为了控制复杂度，刻意做了这些简化。理解边界在哪里，才知道上生产环境要补什么。

1. run_command 不受 safeJoin 限制。 路径防护只覆盖 read_file 和 edit_file，而 run_command 通过 sh -c 执行，命令里出现的路径不受约束，cat /etc/passwd 照样能跑。这不是疏忽：shell 命令本质上是任意的，强行做路径过滤会破坏正常命令，go test 要访问 GOPATH，git 要访问 .git。生产环境的思路是组合拳：人工审批、用容器沙箱执行命令，或者用 Go 的 os.Root 限定文件操作的根目录。

2. edit_file 只替换第一处匹配。 底层是 strings.Replace 的单次替换。模型想批量替换时改不动。改进方向是提供 replace_all 参数，或者在发现多处匹配时直接报错，提示模型给出更长的上下文做精确匹配。

3. 没有优雅取消。 循环跑起来后按 Ctrl+C 是进程级默认行为，直接退出。更合理的做法是捕获 SIGINT 后取消 context，让循环在下一轮检查 ctx.Err() 再退出，长任务能停下来看中间结果。

4. Session 没有压缩。 对话历史无限追加，长对话的 token 消耗会失控。可以只回喂最近 N 条，或者把老历史总结成摘要再继续。目前靠单次会话最多 15 轮的上限兜底，跨会话的累积没有限制。

5. run_command 的启动错误被忽略。 命令退出码非 0 是正常情况，代码写错了而已；但进程根本没起来，比如 sh 不存在，也被一并吞掉。应当区分这两种情况：进程跑过就走正常回喂，没跑起来就是基础设施错误，应当上抛。

6. 思考折叠的摘要处理偏粗糙。 摘要里把换行统一替换成空格，遇到 markdown 表格会破坏排版。纯显示层问题，不影响功能，优先级最低。

三、七个扩展方向，按价值排序

CLAUDE.md 项目记忆。 启动时读取工作目录的 CLAUDE.md 或 AGENTS.md，内容拼进 system 指令，让 Agent 记住项目的技术栈、代码规范和禁区。十几行代码，换来的是 Agent 不必每次重新理解项目，性价比最高。

多行输入。 目前一次只读一行，粘贴多行代码会断。可以识别行尾续行符或未闭合的引号括号，继续读下一行。

list_files 与 grep 原生工具。 现在 Agent 找文件、搜内容只能借道 run_command 执行 ls 和 grep，等于绕回了 shell 的安全坑里。做成独立工具后可以用目录遍历加正则扫描实现，权限边界收紧在工作目录内，比走 shell 可控得多。

diff 审查模式。 edit_file 执行后用红删绿增展示改动，让用户确认每一处修改，也可以直接集成 git diff。

成本统计。 累加 API 返回的 usage，按模型单价折算，会话退出时给出本次账单。

MCP 接入。 实现 MCP 客户端后，工具集从内置的三个扩展到整个外部生态，数据库、GitHub 都能接。参考现成的 Go 语言 MCP 客户端实现可以省不少力气。复杂度高，价值也高。

多会话管理。 会话列表、命名、切换。MVP 阶段单会话够用，优先级最低。

四、代码质量补课

错误处理语义值得统一：现在有的工具把错误文本当结果回喂，有的直接上抛 error。建议明确一条规则，工具逻辑错误回喂给模型，基础设施错误上抛给调用方。此外，流式响应里的深层匿名嵌套结构体可以拆成命名类型；safeJoin、Session 读写、危险命令确认这些纯函数目前是零测试，是最该先补的单元测试；配置全靠环境变量，补上 -model、-work-dir 这类命令行 flag 会友好很多。