第 0 章 · 走进 mini Claude Code
第 0 章 · 走进 mini Claude Code
- 0.1 亲手造一个编程 Agent(非Toy可入简历的项目)
- 0.2 编程 Agent 的核心技术在哪里?harness 是什么
- 0.3 一次会话长什么样(一):任务执行、权限确认、待办清单
- 0.4 一次会话长什么样(二):主动提问、Plan Mode、中途取消
- 0.5 一次会话长什么样(三):上下文压缩、中断恢复
- 0.6 一次会话长什么样(四):长期记忆、Skills可复用技能
- 0.7 能力全景:工具集、交互模式与权限安全概览
- 0.8 里程碑地图:学习路径、扩展点原则与开发规范
- 0.9 Mini Claude Code 项目构建和运行 README
0.1 亲手造一个编程 Agent(非Toy可入简历的项目)
欢迎来到《大模型应用开发》的项目实战篇。
这门实战课只有一个目标:带你从零开始,亲手写出一个能在命令行里运行的编程 Agent。它参照 Claude Code 来做,名字叫 mini Claude Code,命令行工具名是 mcc。
写完之后,你会得到一个真的能用的编程 Agent。
你在一个项目目录下输入 mcc 把它启动起来,再用自然语言告诉它"给下单接口加上参数校验",或者"这个测试为什么失败了"。它会自己去读代码、改文件、跑测试,一步步把任务做完。
通过这个项目,你会把编程 Agent (特别是Claude Code)的底层实现原理弄得清清楚楚、明明白白!毕竟代码之下,没有秘密!
为什么我们选这个项目
做实战项目可以选的方向有很多。我们为什么选一个编程 Agent?
因为 Agent 在编程领域,是目前落地最成功的场景。
Claude Code 里面有不少 harness 上的工程做法,学习价值很高。你以后做别的 Agent 项目时,完全可以把这些做法借鉴过去。
其实,市面上有很多Agent开发框架或者说harness 框架,比如 Pi、AgentScope等,大多是同一套 harness 理论的不同实现,彼此差别不大。你学透我们这个项目,基本上也就学透了所有这类框架的底层原理。
除此之外,mini Claude Code 里用到的理论知识,和《大模型应用开发进阶》课里讲的 Agent 开发技术,绝大部分是一一对应的。
如果你在学《大模型应用开发进阶》的时候,有哪个知识点没有弄得特别清楚,你就可以在 mini Claude Code 里去找对应的代码,前面也讲到,代码之下,没有秘密,通过阅读代码,消灭任何知识盲点!这比你查资料强百倍,毕竟代码才是一手知识来源。
反过来,你把 mini Claude Code 做一遍,也会把《大模型应用开发进阶》里的那些理论理解得更透彻、更细节。
如果要用一句话来说这个项目的价值,那就是:
学完它,Agent 开发的核心技术你就掌握了、Harness工程你也搞得清清楚楚了。Claude Code 这一类工具底层是怎么实现的,你也能够比任何人都清楚。
非Toy项目,可写入简历
我也多方对比研究了市面上的一些大模型项目课、Agent项目课,做得非常Toy(玩具),究其原因还是因为场景的局限性。
前面提到编程才是Agent落地的最成功的场景,实现一个编程Agent也就意味着会涉及到非常多的技术。
而且,我们实现了Claude Code大多数功能,分析代码、实现复杂功能、修改bug、测试等等,都不在话下。
甚至mini Claude Code的本身的一些代码,都是mini Claude Code自己开发的!!!
可见它并不是一个只会修改一两行代码的Toy项目!
当年,我上大学的时候,自己手搓了一个搜索引擎,靠对搜索引擎的无盲点了解,收获了N多大厂Offer。
我相信,这个项目也可以让你对编程Agent、甚至通用Agent开发对技术有一个无盲点的了解,也可以写入到简历里,成为你的项目亮点!
关于项目的一些补充说明
这里我们说明一下:RAG、MCP、多 Agent 协作,mini Claude Code 里没有做。这部分内容,我们会放到另一个项目里讲。
除此之外,我们的项目是使用Java + Spring AI开发的。Spring AI 只负责最底层的模型调用。Agent 的控制循环、工具分发、权限审批、上下文组装与压缩,这些核心逻辑全部由我们自己来写。
为什么我们不把这些都交给框架?因为一旦交出去,你就看不见框架到底替你做了什么,也就学不到东西。你自己写一遍,才能真正弄懂 Agent 开发里那些容易被框架盖住的细节。
虽然这是一个Java项目,但是,编程语言完全不是障碍,你不需要对Java有深入的了解,只需要能读懂就可以了。对于大多数程序员,这都不是一个问题!
而且,我们配有70+篇项目讲解文章,你光看文章都会有很多收获。
当然,你也可以参照文章和代码,把Java实现的min Claude Code 翻译成其他语言,在这个过程中,也会有很多收获。
这门课适合谁学
这门课适合已经读过我们另外两门前置课的同学,也就是《大模型应用开发基础》和《大模型应用开发进阶》。
0.2 编程 Agent 的核心技术在哪里?harness 是什么
这门课要回答的核心问题其实是:
一个像 Claude Code 这样的编程 Agent,内部到底是怎么运转的?
这一节,我们来看这个大问题是由哪些部分组成的。拆开之后你会发现,它其实是一组具体的小问题。每一个小问题,都对应大模型应用开发进阶课里的一块知识,也对应我们这个项目里的一部分代码。
我们把这些小问题一个一个用代码回答清楚,就是整门课的全部内容。
一组小问题,就是整张学习地图
一般的产品,往往从用户的痛点出发。这个项目不一样,它是一个学习型项目,推动我们做下去的是好奇心。
下面这些问题,建议你先停下来想一想,自己能不能答上来。答不上来很正常,这些正是我们要学的内容:
- 模型只能输出文本,它是怎么调用工具,去读文件、改代码、运行命令的?
- 一次任务往往要很多步。这个"决策—行动—观察"的循环是怎么转起来的,又在什么时候停下来?
- 多步任务怎么拆成待办,一步一步跟踪进度,做到不跑偏?
- 整个代码库放不进上下文窗口。它是怎么决定,每一步只读取需要的那一部分?
- 会话越来越长,上下文快满了。它是怎么分层压缩,又不丢掉关键信息的?
- 改文件、运行命令这类有风险的操作,怎么保证安全,什么时候该停下来问人?
- 需求不清楚的时候,它怎么先把问题问清楚,而不是自己猜一个答案?
- 风险比较大的任务,怎么先给出计划让人确认,确认之后再执行?
- 任务跑偏了,用户怎么在中途把它停下来?
- 项目的约定,以及跨会话要记住的事情,分别由谁来写、存在哪里、什么时候读回来?
你会注意到,这些问题几乎没有一个是模型本身的问题。
真正让模型能去做事情、能把一件事连续做完、做的时候守住安全边界、并且记得住之前发生过什么的,是模型之外的那部分代码。这部分代码,就是我们这门课的主角:harness。
harness 是什么
harness 直译是"马具"。
它是把模型、工具、上下文和记忆串成一个循环的那部分代码。在我们这个项目里,你最终要亲手写出来的,主要就是它。
为什么需要它?因为模型本身只会输出文本。你给它一段对话,它回你一段文字,仅此而已。
它不会真的去打开一个文件,也不会真的在你的机器上执行一条命令。
那么,从"模型说它想读 OrderController.java",到"这个文件的内容真的被读出来,又交回给模型继续思考",这中间的所有事情,都得有人来做。负责做这些事情的,就是 harness。
具体来说,harness 承担下面这几件事。建议你记住这张清单。后面每个里程碑,基本上都是在这张清单上逐步补充内容:
- 驱动循环:它拿到模型的输出,判断模型是要调用工具,还是已经给出最终回答。如果模型要调用工具,它就去执行,再把结果作为"观察"返回给模型,进入下一轮。这就是"决策—行动—观察"循环。
- 分发工具:它解析模型到底要调用哪个工具、参数是什么,校验之后交给对应的工具实现去执行。
- 把关权限与模式:它在执行有副作用的工具之前做权限判断。该审批的,它会停下来等你确认。在 Plan Mode 下,它会拦住所有写操作,只允许调研。
- 响应用户介入:它处理你发出的中途取消信号。当 Agent 向你发起提问时,它会暂停循环,等你回答之后再继续。
- 组装上下文:每一轮,它按固定顺序,把系统指令、工具描述、项目约定与记忆、Skills、会话历史等,拼成这一次调用的完整输入。
- 分层压缩上下文:每一轮请求发出之前,它按从便宜到贵的顺序过一遍压缩链,保证会话能一直进行下去。
为什么我们要自己写 harness
你可能会问:现在框架已经很多了,这些事情交给框架不就可以了?
这个项目的价值,就在于我们偏偏要自己写一遍,不把这些事情交给框架。因为一旦你把这些逻辑交给框架,它们就变成了一个黑盒。
你知道它能跑,但你不知道它为什么能跑。这门课要你弄清楚的,正是它为什么能跑。
所以,在这个项目里,Spring AI 只做一件最底层的事:把我们组装好的上下文发给模型,再拿回模型的文本输出。上面那张清单里的每一件事,全部由我们自己来写。
你写完之后,会得到两样东西。第一,你会真正理解 harness 到底是什么。第二,你再回头看任何 Agent 开发框架 或者Harness 框架的时候,你能很容易看懂它们底层的实现原理。
接下来
概念我们就讲到这里。如果只看定义,你会觉得很抽象。更好的理解方式,是看它跑起来是什么样。
所以接下来的 0.3、0.4、0.5 三节,我们会用几段真实的终端会话,带你看一看:当你给 mini Claude Code 下一个任务时,上面说的这些事情,在屏幕上分别是什么样子。
0.3 一次会话长什么样(一):任务执行、权限确认、待办清单
上一节我们讲了 harness 要做哪些事,那些描述还比较抽象。这一节我们换个角度看:直接看它跑起来是什么样。
我们用几段真实的终端会话,带你感受一下,用 mini Claude Code 是什么体验。
我们先约定一下这些会话里的符号,后面几节都会用到:
- 行首的
⏺表示 Agent 的一步动作; ⎿表示这一步的结果;- 工具调用写成
工具名(参数)的形式,比如Read(OrderController.java); - 审批和提问都是编号卡片,你输入编号,回车作答。
这里要提醒你一点:真实的编程 Agent 通常不会把内部每一步都显示得这么细。我们为了教学,刻意让运行时的动作尽量可见,方便你对照原理来看。
启动:进入一个持续的会话
你在项目目录下输入 mcc,它会打印一行欢迎信息,然后给你一个 > 提示符,等你输入需求:
$ mcc
mini Claude Code v0.1 · 模型:deepseek-flash · 项目:~/projects/codecrush
输入你的需求,/help 查看命令,/exit 退出。
>请你注意这里的"持续"。它不是执行完一条命令就结束,而是进入一个会话。你可以一轮一轮地和它对话。
执行一个任务,并逐步确认
我们给它一个典型的编程任务:给下单接口加上参数校验。下面我们来看它是怎么一步步推进的:
> 给 OrderController 的下单接口加上参数校验
⏺ 先看一下 OrderController 的现状
⏺ Read(OrderController.java)
⎿ 读取 120 行
⏺ 检索项目里已有的校验写法,保持一致
⏺ Grep("Validator")
⎿ 找到 6 处
⏺ Read(OrderValidator.java)
⎿ 读取 40 行
⏺ 复用已有的 OrderValidator,在 placeOrder 入口做校验,先改 Controller:
⏺ Edit(OrderController.java)
⎿ 变更预览
50 public void placeOrder(@RequestBody OrderRequest req) {
+ 51 orderValidator.validate(req); // 校验 quantity / amount
52 orderService.placeOrder(req.toOrder());
53 }
对 OrderController.java 应用此修改?
1. 允许
2. 允许,本会话内的所有文件修改不再询问
3. 拒绝,并说明原因
请选择 [1-3]:
⎿ 已写入 (+1 -0)
⏺ Bash(mvn -q test)
⎿ 运行测试验证改动
执行该命令?
1. 允许
2. 允许,本会话内的所有 mvn 命令不再询问
3. 拒绝,并说明原因
请选择 [1-3]:
⎿ 16 passed
⏺ 已完成。下单接口现在会校验 quantity > 0 和 amount > 0,非法入参返回 400,
并新增了一条"非法数量返回 400"的测试用例。这一小段里有好几个行为,对应的就是上一节那张 harness 清单。我们分开来看。
它先读,再查,后改。 Agent 没有一开始就修改文件,而是先用 Read 看了现状,又用 Grep 检索项目里已有的校验写法,然后再去读 OrderValidator。
这就是按需获取上下文。代码库放不进上下文窗口,所以它不会一次性加载全部代码,而是根据当前这一步的需要,用检索和读取,逐步拿到需要的那一部分。
你也可以从这里看出,它为什么要先查已有写法:它希望改动和项目现有的风格保持一致。
它在修改之前会先给出预览。 真正修改文件之前,它先打印一段 diff 预览,让你看清楚它到底要改哪几行。
危险操作会停下来等你放行。 改文件(Edit)和运行命令(Bash)都会弹出一张审批卡片。
这张卡片不是模型自己判断之后弹出来的,而是运行时强制弹出来的。只要是有副作用的操作,harness 就一定会拦下来问你。
卡片上的三个选项分别是:只放行这一次,本会话内同类操作都放行,以及拒绝并说明原因。这套机制我们在后面的里程碑会专门来讲。这里你先有一个印象就可以:改文件、运行命令,默认都要你确认。
多步任务:用待办清单跟踪进度
上面那个任务,步骤不多。很多真实任务要改好几个地方,需要分成好几步来做。这种时候,Agent 会维护一份待办清单,一边做一边更新,你在终端里能实时看到当前进度:
> 把下单流程改造成支持幂等
⏺ 这个任务分几步,先建待办跟踪进度
⏺ TodoWrite
⎿ ☑ 阅读 OrderService / OrderController 现状
▶ 为 placeOrder 增加 dedupKey 并做去重
☐ 同步更新 CheckoutJob 的调用
☐ 新建"重复请求不产生重复订单"的测试
⏺ Write(OrderIdempotencyTest.java)
⎿ 新建文件
新建 OrderIdempotencyTest.java?
1. 允许
2. 允许,本会话内的所有文件修改不再询问
3. 拒绝,并说明原因
请选择 [1-3]:☑ 表示已经完成,▶ 标出当前正在进行的那一步,☐ 表示还没有开始。
这份清单要保证的是,多步任务不会漏掉某一步,也不会做到一半跑偏。它既帮模型自己盯住进度,也让你一眼看清它进行到了哪一步。
小结
这一节你看到了一次典型任务是怎么进行的。Agent 先读取再修改,修改前给出预览,危险操作会逐步请你确认。任务步骤一多,它还会用待办清单跟踪进度。
下一节(0.4),我们继续看会话里另外几种互动。它会主动向你提问,会先给出计划再执行,也能被你中途打断。
0.4 一次会话长什么样(二):主动提问、Plan Mode、中途取消
上一节我们看了任务执行、逐步确认和待办清单。这一节我们继续看会话里另外几种互动。
符号约定和上一节一样。⏺ 是一步动作,⎿ 是这一步的结果。审批和提问都是编号卡片,你输入编号之后回车作答。
需求不清楚时,它主动提问
有时候一个需求有好几种做法都说得通,Agent 不应该擅自替你做决定。这时它会调用一个叫 AskUserQuestion 的工具,弹出一张选择卡片,把问题和候选项列给你:
> 给用户密码加上加密存储
⏺ 这个改动有几种常见做法,想先跟你确认一下
⏺ AskUserQuestion
用哪种加密方案?
1. BCrypt(推荐,Spring Security 自带)
2. Argon2(更强,但需要额外依赖)
3. PBKDF2
4. 其他(我来补充说明)
请选择 [1-4]:1
⏺ 好的,使用 BCrypt。继续…我们是把"选择卡片"做成了一个模型可以主动调用的工具。Agent 判断这件事需要你来决定时,就调用这个工具提出问题。你选定之后,答案会作为"观察"回到模型,循环再继续。
请你注意,卡片里总会留一个"其他",让你可以补充说明,不会被几个预设选项限制住。
这里我们要和上一节的审批卡片对比一下。这两种卡片看起来很像,但发起的人和要解决的问题不一样,后面学的时候很容易混在一起。
- AskUserQuestion 是模型主动发起的澄清,它要解决的是"要不要这么做"。
- 审批卡片是运行时强制发起的放行确认,它要解决的是"准不准这么做"。
前一种来自模型自己的判断,后一种是 harness 强制做的。你后面读代码的时候,不要把这两种卡片当成同一种。
Plan Mode:先出计划,确认后再执行
如果任务改动比较大,你可能希望它先不要修改文件,而是先把思路展示给你看。这就是 Plan Mode。
进入 Plan Mode 有两种方式。一种是你自己输入 /plan。另一种是 Agent 判断这是一个改动大、步骤多、而且有多种做法的任务时,主动提议进入,弹出卡片请你决定。
进入之后,harness 会拦住所有写操作。Agent 只能用只读工具做调研,然后给出一份计划:
> /plan
⏸ 已进入 Plan Mode:只调研与规划,不做任何修改。
> 把下单流程改成支持幂等
⏺ Read(OrderService.java)
⏺ Read(OrderController.java)
⏺ Grep(placeOrder)
⎿ 定位到 2 条调用路径
⏺ 调研完成,这是我的计划(尚未执行):
目标
同一笔下单请求被重放时,只产生一笔订单,并返回已有的那笔。
现状
OrderController.placeOrder 直接调用 OrderService.placeOrder(req),请求里没有幂等键。
placeOrder 还有第二条调用路径:CheckoutJob 会在定时重试时再调一次。
Order 表目前也没有可以用来去重的字段。
只在内存里记下「处理过的请求」挡不住多实例,进程重启之后也会失效,所以去重要落在数据库上。
方案
请求增加必填的 dedupKey,由调用方生成。orders 表增加 dedup_key,并建唯一约束。
下单时先按 dedupKey 查已有订单,命中就直接返回;并发插入撞上唯一约束时,再查一次,同样返回已有订单。
不采用「先插入一条 PENDING、再更新成已下单」:现有下单是一次写完的,多一个中间状态会牵动支付和库存,这次用不上。
改动
1. PlaceOrderRequest 增加 dedupKey,OrderController 在入口校验它非空。
2. orders 表增加 dedup_key 并建唯一索引,Order 实体补上这个字段。
3. OrderService.placeOrder 按「先查、再插、冲突再查」处理。
4. CheckoutJob 用 jobId 派生 dedupKey,重跑时复用同一个键。
5. 补测试:同一 key 连续两次返回同一订单;不同 key 产生两笔;并发双写只落一笔。
本次不做
支付回调和库存扣减的幂等。这次只保证「下单」这一步不重复建单。
⏺ ExitPlanMode
是否按此计划开始?
1. 接受计划并执行
2. 不执行,继续完善计划
请选择 [1-2]:1
⏺ 已退出 Plan Mode,开始执行第 1 步…Plan Mode 把"规划"和"执行"分成了两个阶段。你可以在它开始修改之前,先把思路审一遍,避免它一开始就做大范围修改。这里有几个细节,我们分开说。
- 你选择选项 1(接受并执行)之后,它会退出 Plan Mode,开始执行。执行阶段该弹出的审批卡片,仍然会弹出来。Plan Mode 只负责把规划和执行分开,不会改变执行阶段的放行规则。
- 你选择选项 2 之后,控制权会回到你这里,模型不会自己默默把计划改好。你直接在输入框里写修改意见,比如"不要修改 CheckoutJob,去重改用一张单独的表"。它会根据你的意见重新调研,给出新的计划,再弹出卡片请你确认。
- 这个来回可以进行好几轮。这几轮里,它始终只用只读工具,不会去修改文件。直到你选择了选项 1,它才真正开始执行。
- 计划本身直接显示在终端里,并保留在上下文中。默认情况下,它不会把计划写成磁盘上的 markdown 文件。
中途取消:随时打断
Agent 执行过程中,你随时可以按 Ctrl-C 打断它:
⏺ 正在重构 PaymentService…
⏺ Read(PaymentService.java)
⎿ 读取 300 行
⏺ Edit(PaymentService.java)
⎿ 已写入 (+40 -15)
[按下 Ctrl-C]
⎿ Interrupted by user(已中断)
>终端里只会简短地提示"已中断",然后回到 >,等你的下一条指令。程序本身不会退出。
终端上只显示了这一行,但 harness 在这个时候做的事情并不少。取消是一个协作式信号,不是把进程直接杀掉。
只读操作可以马上停下。正在进行的写操作,会先把当前这一步做完,或者回退到一个安全的状态,不会留下写到一半的文件。
在此之前,每一次修改都是你确认过的。已经应用的改动会留在工作区里,你可以用 git 查看,也可以回退。
工作状态和待办也会保留。你可以调整需求之后,让它继续执行。
小提示:Ctrl-C 的含义,和你当前所处的状态有关。任务正在执行时,你按它,是取消当前任务。任务已经结束、程序正在
>等你输入下一条消息时,你按它,则是退出程序,效果和/exit一样。
小结
这一节我们看了三种 HTIL 方式。它会主动问你,会先给出计划再开始修改,也能被你随时打断。
加上上一节的任务执行、逐步确认和待办清单,你对 mini Claude Code 的使用体验,应该已经有一个比较完整的印象。
还有一种重要的能力,我们放到下一篇单独来讲:会话变长、上下文快要满的时候,它是怎么自己做压缩的。
0.5 一次会话长什么样(三):上下文压缩、中断恢复
前面 0.3、0.4 两节,我们把一次会话里常见的几种互动都走了一遍。还有两件事没有细说:会话越来越长的时候,mini Claude Code 会自己给上下文做压缩;而会话一旦中断,它又能在下次恢复。这一节我们把这两件事讲清楚,顺带介绍一个你随时能用到的命令 /context。
符号约定和前两节一样。⏺ 是一步动作,⎿ 是这一步的结果。
为什么会话长了就需要压缩
每发起一次请求,mini Claude Code 都要把这一轮的上下文打包发给模型。这个包里有系统提示词、项目约定与记忆,还有到目前为止的整段会话历史。会话进行得越久,这个包就越大。
模型的上下文窗口是有上限的,比如 20 万 Token。历史一旦把窗口占满,轻一点的结果是多消耗 Token、响应变慢,重一点的结果是直接触发模型的"上下文过长"报错,任务会在中途失败。更重要的是导致模型注意力分散,任务不能高质量顺利完成!
mini Claude Code 是一个编程 Agent。一个真实任务常常要读十几个文件、跑好几轮测试、来回改几版代码,会话历史会增长得非常快。
所以,当上下文接近上限时,它必须能主动把上下文压缩下来。这就是上下文压缩要解决的问题。
/context:先看看上下文有多满
在讲它怎么压缩之前,我们先给你一个查看占用的办法,也就是 /context 命令。它只做一件事:把当前上下文各部分的占用列出来给你看。它本身不会压缩,也不会改动任何内容。
> /context
上下文占用(估算):18.2k / 200k Token(9%)
系统指令与工具描述 4.1k (系统提示词 + 工具定义 schema)
项目约定与记忆索引 1.3k (AGENT.md + 记忆说明 + MEMORY.md)
会话历史(含待办/工具结果) 12.8k它按上下文的组装顺序分成三段。最上面是系统指令与工具描述,中间是项目约定与记忆索引,最下面是会话历史。会话历史通常是增长最快的那一段,你的待办和工具结果也都算在里面。
这里的数字都是估算值。mini Claude Code 没有接入真实的分词器,而是用字符数做了一个粗略的折算。这个估算在数量级上是对的,用来判断上下文有多满,已经够用了。
什么时候你会用到它?当你觉得会话已经很长,或者想知道到底是哪一部分占得最多的时候,输入 /context 就能看到。这个命令是只读的,你看多少次都不会影响会话。
自动压缩与 /compact:一层一层地压缩
大多数时候,压缩是在上下文接近窗口上限时自动发生的,你不需要自己去触发。如果你想主动压缩一次,可以输入 /compact。
> /compact
⏺ 正在压缩上下文…
⎿ Snip:清理空结果 / 被拒绝的调用(182000 → 170000 Token)
⎿ 微压缩:清理较早、可再取的工具结果(170000 → 150000 Token)
⎿ 上下文折叠:把较早的对话折叠成结构化摘要(150000 → 120000 Token)
⎿ 自动压缩:对其余历史做一次模型摘要(120000 → 96000 Token)
⎿ 压缩后:182.0k → 96.0k Token(估算)你会发现,压缩不是把历史一下子全部处理掉,而是分成好几层,从便宜到贵依次尝试。这里的便宜和贵,指的是这一层要不要调用模型、会不会额外消耗 Token。前面的层一旦腾出了足够的空间,后面更贵的层就不会再触发。
- 最便宜的几层只做清理。它会把没有匹配到的检索、被你拒绝的操作,以及较早那些随时可以重新取回来的工具结果,清掉,或者换成占位符。
- 再贵一点的是折叠。它把较早几轮对话里的工具往返,用代码抽取成一份结构化摘要,省掉大段原始结果。这一步不调用模型。
- 最贵的一层才是自动压缩。这一步会真的调用一次模型,把更早的历史总结成一段摘要。
这里我们说明一下:上面这个把每一层都打印出来的过程,真实的编程 Agent 通常不会展示出来。我们是为了教学,才刻意让它可见。
压缩是整个项目里工程上最难的一块。它既要腾出空间,又不能把后面还要用到的信息弄丢。
你在这里先有一个直观的印象就可以。完整的分层压缩链,我们留到上下文管理里程碑(M6)里再展开来讲。
大工具结果:一产生就落盘
上面 /compact 列出的那几层,都是在压缩那一刻才跑的。但还有一层比它们都早:单条工具结果太大时,它在结果刚产生的那一刻就落盘。
什么叫"单条结果太大"?比如你让它跑一次完整测试,或者做一次大范围检索,一条 Bash 或 Grep 的输出,可能就有几万、十几万字符。
这种结果如果原样塞进上下文,一条就能占掉窗口的一大块。所以 mini Claude Code 在它即将写进历史的那一刻就判断:超过阈值的,把完整内容写到磁盘上,上下文里只留一段"引用"。
⏺ Bash(command="mvn -q test")
⎿ <工具结果过大,完整内容已落盘:~/.mcc/projects/-Users-wangzheng-codecrush/tool-results/call_8f3a.txt
(共 86320 字符,可用 Read 读取)。前 2KB 预览:>
[INFO] Scanning for projects...
[INFO] BUILD SUCCESS
Tests run: 16, Failures: 0, Errors: 0, Skipped: 0
……你看,上下文里只剩下文件路径、总字符数,和开头 2KB 的预览。模型后面如果还要看完整输出,直接用 Read 读那个文件就行。
这是整条压缩链里最便宜的一层:它不调用模型,只写一次盘,而且一产生就做,后面每一轮都不用再处理它。
这里有一个例外要记住:Read 自己的结果永远不落盘。否则模型拿到路径又去 Read,读回来又太大又落盘,就会绕成一个死循环。
压缩会不会把历史弄丢
看到"摘要""清理""折叠"这些词,你可能会担心:历史被压缩掉以后,之后还找得回来吗?
找得回来。这里要分清两件事。压缩只精简每一轮发给模型的那个窗口,会话的原始历史会被完整地保存到磁盘上。
也就是说,压缩改的是每一轮递给模型的那段上下文,不是磁盘上的原始记录。哪怕某一轮把历史总结成了一段摘要,磁盘上的原始记录仍然是全量的。
所以,无论压缩到什么程度,原文都不会丢失。磁盘上这份完整记录,还顺带带来了另一个很实用的能力:中断恢复。
中断恢复:关掉终端,下次接着上次继续
既然每一步都完整写在了磁盘上,那你哪怕中途把终端关了,也不会丢进度。下次启动用 /resume 就能接着上次继续。
这里先说明一点:落盘是全自动的。你正常对话、让它改文件,每一步都已经写进了会话日志,你不需要做任何"保存"动作。
我们用一个跨越两次启动的例子来看。先看第一次,你让它做一个多步任务,它建好待办、开始执行,做到一半你把终端关了:
> 给 OrderService 的 placeOrder 加去重,避免同一请求重复下单
⏺ 先理清现状,我建一个待办清单
⏺ TodoWrite(todos=[...])
⎿ ☐ 阅读 OrderService / OrderController 现状
☐ 为 placeOrder 增加 dedupKey 并做去重
☐ 同步更新 CheckoutJob 的调用
☐ 新建"重复请求不产生重复订单"的测试
⏺ Read(file_path=/Users/wangzheng/codecrush/src/main/java/OrderService.java)
⎿ 1 package com.example;
…(共 180 行)
[这时你直接关掉了终端]过程中的每一条消息,都已经写进了磁盘上的会话日志,待办也存了一份快照。所以你这一关,什么都没丢。
第二天你重新启动 mcc,输入 /resume,它把上次这段会话读回来,并打印出恢复结果:
> /resume
⎿ 已恢复会话(24 条消息) · 待办 4 项:
☑ 阅读 OrderService / OrderController 现状
▶ 为 placeOrder 增加 dedupKey 并做去重
☐ 同步更新 CheckoutJob 的调用
☐ 新建"重复请求不产生重复订单"的测试待办的渲染和前面一样:已完成的划掉,进行中的高亮。你一眼就能看出上次做到哪、接下来该做什么。
此时整段历史已经重新放回上下文,所以你可以直接追问上次的细节,它能根据这段历史回答。你回一句"继续",它就接着上次的进度往下做。
这里还有一个和 /resume 正好相反的命令 /clear。/clear 是"清空当前会话、从头开始",它会切到一个全新的会话文件,但旧日志仍然留在磁盘上,以后照样能用 /resume 恢复。一个是续旧账本,一个是开新账本。
小结
这一节我们把上下文压缩和中断恢复都讲清楚了。会话变长、接近窗口上限时,mini Claude Code 会从便宜到贵,一层一层地把上下文压缩下来,尽量保留关键信息,也避免触到上限之后任务失败。而因为原始历史始终完整落盘,你关掉终端之后,还能用 /resume 接着上次继续。
你可以用 /context 随时查看占用,用 /compact 手动触发一次压缩,用 /resume 恢复上一次的会话。
接下来进入 0.6,我们再补上两种能力:长期记忆和可复用技能。它们让 Agent 换一个会话也记得你的约定,还能按需调用你准备好的操作手册。
0.6 一次会话长什么样(四):长期记忆、Skills可复用技能
前面 0.3 到 0.5,我们把一次会话里常见的几种互动都走了一遍:任务执行、权限确认、待办、主动提问、Plan Mode、中途取消,上下文压缩,还有中断恢复。
还有两种能力我们一直没有展示,这一节我们补上。一种是长期记忆,让它换一个会话也记得你的约定;另一种是可复用技能(Skills),让它按需调用你预先准备好的操作手册。
我们先给你一个整体的判断:这两种能力,底子上是同一种思路。它们都只在会话开始时加载一份很小的"索引",真正的内容等用到的时候才去读。这个思路有一个名字,叫渐进式披露。下面我们分开来看。
长期记忆:换一个会话也记得你的纠正
前面几节里的会话,不管进行得多久,它记住的都只是"这一次会话的过程"。你关掉终端,明天重开一个新会话,昨天纠正过它的事情,它就不记得了,你得把同样的话再说一遍。
长期记忆要解决的就是这件事。它把"跨会话都该记住的知识"单独沉淀下来,每次会话开始时自动带上。
这里的记忆分两路。一路是 AGENT.md,由人来写,放在项目目录下的 .mcc/AGENT.md,随仓库一起提交。构建命令、代码风格、接口约定这类东西写在里面,每次会话开头整份读进上下文。
另一路是 auto memory,由模型自己写。它是模型在和你协作的过程中,把你纠正过的做法、确认过的偏好,记成自己的笔记。
我们用一个跨越两次会话的例子来看第二路。先看第一次会话,你让它改一处持久层的代码,顺手纠正了它一次做法:
> 给 OrderRepository 补一个按手机号查订单的集成测试
⏺ 我先写一个连接内存库的测试,用 mock 替换 DataSource……
> 别 mock 数据库。上个季度我们因此出过问题:mock 的测试通过了,真实迁移在生产环境却失败了
⏺ 明白了,我改成连真实的测试库来写。这一条我记下来,以后涉及持久层的测试都这样处理
⏺ Write(file_path=~/.mcc/projects/-Users-wangzheng-codecrush/memory/feedback_testing.md)
⎿ · 已保存记忆:feedback_testing.md
⏺ Edit(file_path=~/.mcc/projects/-Users-wangzheng-codecrush/memory/MEMORY.md)
⎿ · 已保存记忆:MEMORY.md第二天你重开 mcc,开一个全新的会话,再让它做一个涉及集成测试的任务:
> 再给 OrderRepository 加一个按状态查询的集成测试
⏺ 我先看一下记忆里相关的约定
⏺ Read(file_path=~/.mcc/projects/-Users-wangzheng-codecrush/memory/feedback_testing.md)
⎿ 集成测试必须连真实数据库,不要 mock……
⏺ 按你之前确定的约定,这个测试我直接连测试库来写,不使用 mock你不用再纠正第二遍。这里的关键,是它为什么知道去读 feedback_testing.md 这个文件。
因为会话一开始,它只加载了一份 MEMORY.md 索引。这份索引很小,里面一条一行,记的是"有哪些记忆、分别讲什么"。它看到有一条和当前任务相关,才自己用 Read 去读那个主题文件。
你看,这就是我们开头说的渐进式披露:索引常驻在上下文里,所以可以做得很小;真正的内容拆在一个个主题文件里,模型判断相关时才读进来。
这些文件人也能打开查看和修改。你在会话里输入 /memory,它会弹出一张编号卡片,列出当前能编辑的记忆文件,你选一个编号,就用 $VISUAL 或 $EDITOR 指定的编辑器打开:
> /memory
选择要查看/编辑的记忆文件:
1. 项目约定 AGENT.md(尚未创建)
2. 记忆索引 MEMORY.md
3. 主题 feedback_testing.md
请选择 [1-3]:3
已用 vim 编辑:~/.mcc/projects/-Users-wangzheng-codecrush/memory/feedback_testing.mdSkills 可复用技能:按需调用预先准备好的操作手册
我们在实际使用 Agent 的时候,有一类需求会反复出现。比如"怎么写一条规范的 git 提交信息""发布之前要跑哪几步检查"。
这类能力有一个共同点:它们可以复用,但又不必每一次都带在上下文里。你今天要提交代码,才用得上"怎么写提交信息";你今天只是改样式,这条知识就完全用不上。
一个很直接的想法,是把这些能力全部写进系统提示词。但这样一来,每一轮对话都要为那些根本用不上的内容白白占用上下文,很不划算。
所以我们换一个做法。我们把每一项可复用能力写成一个独立的技能文件 SKILL.md,放在技能目录里。每个文件分两部分:一段文件头(名字、描述、何时用)和一段正文(详细步骤)。
会话开始时,我们只把所有技能的清单加载进上下文,也就是每个技能一行的文件头摘要。模型判断某个技能和当前任务相关时,才用 Read 工具把那个 SKILL.md 的完整正文读进来,再按正文执行。
我们来看一个命中的例子。假设我们在技能目录下放了一个生成提交信息的技能 commit-helper,你让它帮你提交改动:
> 帮我把刚才的改动提交一下
⏺ 我先读一下 commit-helper 技能,按它的规范来提交
⏺ Read(file_path=/Users/wangzheng/.mcc/skills/commit-helper/SKILL.md)
⎿ (SKILL.md 正文:先看 git diff --staged、按 Conventional Commits 写 message……)
⏺ Bash(command="git diff --staged")
⎿ (已暂存的改动)…
⏺ Bash(command="git commit -m \"feat(order): 新增订单取消接口\"")
⎿ [main a1b2c3d] feat(order): 新增订单取消接口这里最关键的一步,是模型没有凭清单里那句简短的描述就直接动手,而是先 Read 了那个 SKILL.md,再严格按正文里的步骤执行。
如果你问的问题和任何技能都不相关,它这一轮就不会去读任何 SKILL.md,按平常的方式正常处理,不会勉强套用技能。
同样,你想看看当前有哪些技能,可以输入 /skills:
> /skills
可用技能(2 个):
commit-helper:规范化生成 git 提交信息(当用户要创建 git 提交时)
/Users/wangzheng/.mcc/skills/commit-helper/SKILL.md
release-checklist:发布前检查清单(当用户准备发布、打 tag 时)
/Users/wangzheng/codecrush/.mcc/skills/release-checklist/SKILL.md它把当前能用的技能都列出来,包括名字、描述、何时使用,以及每个 SKILL.md 的文件路径。
这两种能力,其实是同一种思路
读到这里你应该发现了,长期记忆和技能,机制上几乎是一回事。
记忆是 MEMORY.md 索引常驻、主题文件按需 Read;技能是技能清单常驻、SKILL.md 正文按需 Read。两者都是渐进式披露:一份很小的入口留在上下文里,真正的内容等用到时才读进来。
它们的区别只在来源不同。记忆是模型自己写、跨会话慢慢积累的笔记;技能是人预先准备好、可以反复复用的操作手册。
小结
这一节我们补上了会话里的最后两种能力。长期记忆让它换一个会话也记得你的约定和纠正,可复用技能让它按需调用你预先准备好的操作手册。
更重要的是,你记住了它们背后那个共同的思路:渐进式披露,索引常驻、正文按需。这个思路后面在长期记忆(M5)和 Skills(M7)两个里程碑里,我们都会专门展开来讲。
加上 0.3 到 0.5 的内容,你对 mini Claude Code 的使用体验,到这里就有了一个完整的印象。接下来进入 0.7,我们会把这些体验背后的能力做一次系统梳理,包括工具集、交互模式和权限安全。
0.7 能力全景:工具集、交互模式与权限安全概览
前面三节,我们从使用的角度看了几段会话。这一节我们换成设计的角度,把 mini Claude Code 的能力梳理一遍。
我们分三部分来看:它有哪些工具,它和人怎么协作,以及安全是怎么保证的。这三部分合在一起,就是这个产品的能力全景。
一、工具集:Agent 操作环境的方式
模型只能输出文字。它要真正去读文件、改代码、运行命令,靠的是工具。第一阶段我们故意把工具集做得比较少,每个工具只做一件事,方便你一个一个实现,也方便你理解。
这些工具按对环境有没有副作用分成三类。一个工具属于哪一类,直接决定了它要不要经过人工审批。
只读工具(直接执行,不需要审批):
- Read:读取指定文件的内容,可以指定行范围。
- Grep:按关键字或正则,在代码库里检索。
- Glob:按文件名模式查找文件。
写操作工具(有副作用,需要人工审批):
- Edit:修改已有文件。
- Write:新建文件,或覆盖写入。
- Bash:在沙箱里运行命令,比如编译和测试。
状态与交互工具(不碰代码和环境,不需要审批):
- TodoWrite:维护这一次任务的待办清单。它只更新内部的工作状态,不碰文件。
- AskUserQuestion:向你弹出选择卡片来提问,用来澄清需求,或者请你在多个方案里选择。它会暂停循环,直到你作出回答。
- EnterPlanMode:模型判断当前是改动大、步骤多的任务时,用它主动提议进入 Plan Mode。它会弹出一张两选项卡片,由你拍板要不要进入。
- ExitPlanMode:在 Plan Mode 里,计划写好之后,模型用它请你审阅并批准。你确认之后,它才退出计划态、开始执行。
后面这两个是 Plan Mode 的一对工具,一个负责提议进入,一个负责请求退出。它们都只弹确认卡片、不修改文件和环境,所以也归在这一类,不需要审批。
这里有一个和前面课程连在一起的设计,希望你记住:代码的检索用 Read、Grep、Glob,不用向量检索。
这是编程 Agent 的真实做法,也是它和第一门课里 RAG 的区别所在。向量检索适合语义比较模糊的知识问答。在代码库里,按名字和结构精确查找更可靠。
你要找 placeOrder 这个方法,用 grep 就能准确命中,没有必要去算语义相似度。
二、交互模式与人工介入:四个协作设计
编程 Agent 会真的修改你的文件、运行你的命令,所以人怎么介入,是这个产品必须设计清楚的部分。这里有四个设计。前面你已经在会话里见过它们的样子,这里我们把它们归到一起说明:
Plan Mode(先计划后执行):你可以用
/plan主动进入,Agent 遇到步骤多、改动大的任务时,也可以主动提议进入。进入之后,它只做调研、只给出计划,你确认之后才执行。它把风险大、步骤多的任务,先展示出来给人看。中途取消任务:任务正在执行时,你按 Ctrl-C,就是发出取消信号;卡片正等你输入时,你按 Ctrl-C,同样是取消整个任务。harness 收到信号之后,会在安全的位置停下来,不留下损坏的中间状态。工作状态会保留,然后回到
>,等你的下一条指令。AskUserQuestion(主动提问澄清):这是模型主动调用的工具。需求不明确,或者有多个合理做法时,它弹出卡片向你提问。你的答案传回去之后,循环继续。
审批选择卡片:harness 在执行 Edit、Write、Bash 之前,会强制弹出这张卡片。三个选项的含义是:
- 允许:只放行当前这一次。下次遇到同类操作,还会再问你。
- 允许本会话内的同类操作:这一次放行,并且在当前会话内自动放行同类操作。卡片会把范围写清楚:Edit 和 Write 对应的是"本会话内所有文件修改",Bash 对应的是"本会话内某一类命令",比如所有
mvn。它只在本会话有效,你退出之后就失效。 - 拒绝,并说明原因:这一次不执行,并让你告诉 Agent 换一种做法。
三、权限与安全:几条明确的规则
在安全方面,mini Claude Code 遵守下面几条规则:
- 按副作用分级:只读操作(Read、Grep、Glob)直接执行。写操作(Edit、Write、Bash)需要人工审批。工具属于哪一类,上面第一部分已经分好了。
- 权限由 harness 强制执行:是否需要审批、是否允许执行,由运行时统一判断,不依赖模型自觉。哪怕模型在文本里表示它想跳过审批,运行时也不会放行。
- 命令在沙箱里执行:Bash 在受控环境里运行,它能访问的范围是受限制的。
- 只读操作可以并行,写操作必须串行:只读操作并行,是为了加快速度。写操作串行,是为了避免它们互相干扰。
- 防止失控:我们会设置最大步数,一旦出现异常,循环就停下来,避免 Agent 无限制地转下去。
小结
这一节你看到的是一张能力全景。工具有三类:只读、写操作、状态与交互。人和 Agent 的协作有四种:Plan Mode、取消、主动提问、审批卡片。
安全上有几条硬规则:按副作用分级,由运行时强制执行,命令放进沙箱,只读可以并行而写操作必须串行,以及防止循环失控。
这些能力不是一次做完的,而是分散在一个个里程碑里,逐步构建起来。下一节 0.8,我们来看里程碑地图:学习路径怎么走,扩展点原则是什么,开发时又遵守哪些规范。
0.8 里程碑地图:学习路径、扩展点原则与开发规范
这一节我们把整条学习路径梳理一遍,并讲清楚两件会贯穿全课的事情。
第一件是扩展点原则,也就是后面的里程碑为什么大多只新增代码,很少修改已经有的代码。第二件是开发规范。你把这两件事理解了,再往后学每个里程碑,就知道这一章在整条路径里处在什么位置。
一、里程碑地图:学习路径
整个项目分成若干个里程碑,逐步完善。这里有一条贯穿始终的原则:每个里程碑都是一个完整的、可以运行的版本。
里程碑按构建顺序排列。每一个都在前一个的基础上,增加一组完整的能力。
本课正是按里程碑组织成"章"的。下面是从 M1 到 M8 的路线。M9 SubAgent、M10 评测,我们暂时不实现,留在后面再弄,你知道有这个规划就可以:
- M1 · 能问答的编程 Agent:我们接入模型,跑通"决策—行动—观察"控制循环,带上只读工具 Read、Grep、Glob。它能按需读代码,回答关于项目的问题。到这一步,它已经是一个能用的代码问答助手。
- M2 · 能改代码的编程 Agent:我们加入 Edit、Write、Bash(在沙箱里执行)和 TodoWrite,实现只读并行、写操作串行。配合 Bash 跑测试,模型能根据测试结果自己修正。到这一步,它能真正完成编程任务。
- M3 · 人工介入:我们给 Agent 加上控制机制,包括写操作前弹出审批卡片、用 Ctrl-C 中途取消、用 AskUserQuestion 主动提问。到这一步,危险操作都要你放行。你也可以随时打断它,或者在它向你提问时作出回答。
- M4 · 会话持久化与中断恢复:我们把会话落到磁盘上,使用只追加的 JSONL 消息日志,再加上待办快照。你关掉终端,或者程序意外退出之后,可以用
/resume接着上一次继续。这一步同时为后面的压缩留好完整原文。 - M5 · 长期记忆:我们做两路长期记忆。一路是人写的
AGENT.md,另一路是模型自动维护的 auto memory,也就是MEMORY.md索引,加上按需加载的主题文件。到这一步,它能跨会话记住项目约定,以及它学到的事实。 - M6 · 上下文压缩:我们确定固定的上下文组装顺序,加上五层压缩链和紧急兜底。到这一步,长任务、长会话不会因为上下文超出上限而失败。
- M7 · Skills:我们用渐进式披露来加载可以复用的能力。会话开始时只加载技能清单。模型判断某个技能和当前任务相关时,再去读取这个技能的完整内容。
- M8 · Plan Mode:我们实现先计划、后执行。你可以输入
/plan主动进入,Agent 也可以主动提议进入。进入之后,它只做调研、只给出计划,你确认之后再执行。
二、扩展点原则:为什么后面大多只新增,很少修改
你可能会担心:一个里程碑一个里程碑往上加能力,到后面代码会不会越改越乱,改动一个地方就影响很多地方?
这个项目在设计上专门考虑了这个问题。我们遵循的原则是:先把扩展点搭好,后续的代码遵从开闭原则。 具体做法是,三个会被反复用到的核心结构,在 M1 和 M2 一次性搭好,并且预留出扩展点:
- 工具接口与注册表:你要新增一个工具,只需要注册一个实现,不需要修改分发逻辑。
- 工具分发循环,里面有"执行前钩子":审批(M3)和 Plan Mode 的放行判断(M8),都挂在这个钩子上,不需要修改执行本身。
- 上下文组装器(一条有序、可插入 Stage 的管线):长期记忆的加载(M5)、压缩(M6)、Skills 的技能清单(M7),都作为新增 Stage 挂进这条管线,不需要重写已经有的组装过程。
有了这三个扩展点,后面的里程碑大多可以归成三种动作里的一种:新增一个工具,新增一个钩子实现,或者新增一个 Stage。 对已经有的代码,改动都很小。
所以,每个里程碑的文档都会附一行"改动边界",说明它主要新增什么,有没有碰到前面的代码。你会发现,绝大多数时候的情况是:只新增代码,基本不需要修改旧代码。这样,每个功能都可以放在一个独立的package里,package之间天然解耦。
这样做,项目比较好维护,学起来也比较清楚。你每学一个里程碑,只需要关注它新增加的那一小块,不必把整个系统重新理解一遍。
三、开发规范:我们写代码时遵守的约定
最后,我们讲几条贯穿全课的开发约定。
- 技术栈保持克制:我们用 Java 17 和 Gradle 来构建。我们会用 Spring AI,但只让它做最底层的模型调用。我们刻意少用框架里比较复杂的特性,保证你能逐行读懂代码,也能看清框架到底替我们做了哪些事情。
- 和具体模型无关:默认模型只是一个开箱就能用的选择。我们采用 OpenAI 兼容接口这一事实标准,你可以随时换成任意一个 OpenAI 兼容的服务。API Key 这类凭证通过环境变量提供,不写进配置文件。
- 配置分成两层:一层是全局的
~/.mcc/mcc.yml,一层是项目级的<项目>/.mcc/mcc.yml,项目级可以覆盖全局。你什么都不配置,程序也能跑。程序第一次启动时,会自动生成一份带注释的默认全局配置。
0.9 Mini Claude Code 项目构建和运行 README
前面几节,我们从整体上看了 mini Claude Code 是什么、一次会话长什么样,以及后面按什么顺序来学。这一节我们把它构建出来,并在终端里跑起来。
仓库里的代码已经写到 M8。你如果想先把它跑起来,按下面的 Quickstart 做即可。构建、配置和命令的细节,放在 Quickstart 后面。
Quickstart
按这四步做完,你就可以在任意项目里启动 mcc。
1. 安装 JDK 17
本机需要 JDK 17。在 macOS 上可以用 Homebrew 安装:
brew install openjdk@17装好之后,你确认系统能找到这个版本,并把 JAVA_HOME 指过去:
java -versionjava -version 里应能看到 17。
2. 在 mini Claude Code 项目里生成启动脚本
你进入仓库目录,执行安装:
cd /Users/wangzheng/projects/mini-claude-code
./gradlew installDist这条命令会在 build/install/mcc/bin/mcc 生成启动脚本。
3. 生成软链接
你把启动脚本链接到 /usr/local/bin。之后在任意目录输入 mcc,系统都能找到它。
ln -sf "/Users/wangzheng/projects/mini-claude-code/build/install/mcc/bin/mcc" /usr/local/bin/mcc4. 进入一个项目,运行 mcc
你先设置模型的 API Key,再进入要操作的项目目录:
export OPENAI_API_KEY=sk-xxxx
cd ~/your-project
mcc程序会把当前目录当作工作目录。你输入自然语言需求,它就在这个项目里读代码、改文件。
技术栈
项目用 Java 17 和 Gradle 构建。
模型调用我们用了 Spring AI,而且只让它做最底层的请求和响应。控制循环、工具分发、权限审批、上下文组装,这些逻辑都写在项目自己的代码里。
它不绑定某一个模型厂商。只要服务提供 OpenAI 兼容接口,就可以接进来。默认模型是 deepseek-flash,默认服务地址是 https://api.deepseek.com。这两项都只是开箱就能用的选择,你可以随时换成别的模型和服务。
构建与测试
构建之前,本机需要安装 JDK 17。build.gradle 里配置了 Java 工具链,Gradle 会在已经安装的 JDK 里挑选 17 来编译。
如果你的机器上有多个 JDK,建议先把 JAVA_HOME 指到 JDK 17。这样,编译和后面的启动脚本就会用同一个版本。
export JAVA_HOME=/path/to/jdk-17
./gradlew build
./gradlew test./gradlew build 会编译项目,并运行单元测试。你如果只想跑测试,执行 ./gradlew test 即可。
配置
API Key 不写进配置文件。程序从环境变量 OPENAI_API_KEY 读取。你用哪一家 OpenAI 兼容服务,就填哪一家的 Key。
export OPENAI_API_KEY=sk-xxxx
# 可选。不设置时,默认使用 https://api.deepseek.com
export OPENAI_BASE_URL=https://api.deepseek.com如果启动时没有检测到 Key,程序仍会进入会话,并提示你先设置 OPENAI_API_KEY 再对话。这时会话能打开,但还不能正常向模型提问。
常用设置写在全局配置 ~/.mcc/mcc.yml。这个文件配一次,所有项目都能用。你不需要在每个项目里再单独建一份。
程序第一次启动时,如果这个文件还不存在,会自动把内置模板拷贝到 ~/.mcc/mcc.yml,并在终端里打印生成路径。模板里带注释,你可以直接打开修改。最常改的三项是:
model: deepseek-flash
maxSteps: 40
contextLimit: 200000maxSteps 是单次任务最多走多少步,用来防止循环停不下来。contextLimit 是上下文窗口上限,单位是 Token。后面讲压缩的时候,各个阈值都拿它当分母。
配置按三层覆盖,后面的配置会覆盖前面的配置。顺序是:内置默认值,然后是全局的 ~/.mcc/mcc.yml,最后是项目级的 <项目目录>/.mcc/mcc.yml。
项目级文件只有在某一个项目需要不同设置时才去建。你什么都不写,程序也能跑。
环境变量 OPENAI_BASE_URL 的优先级高于配置文件里的 baseUrl。API Key 只认 OPENAI_API_KEY,配置文件里不要写它。
自动生成的全局配置里,除了上面三项,还有沙箱、压缩、技能这些后面里程碑才会用到的字段。你现在先不用逐项去改。
运行
在本仓库里生成启动脚本:
./gradlew installDist脚本位于 build/install/mcc/bin/mcc。然后进入你要操作的项目目录,用完整路径启动:
cd /Users/wangzheng/projects/codecrush
/Users/wangzheng/projects/mini-claude-code/build/install/mcc/bin/mcc工作目录默认是你执行命令时所在的目录。你也可以把目录作为第一个参数传进去,例如 mcc /Users/wangzheng/projects/codecrush。程序会在这个目录里读代码、改文件。
你也可以先不安装脚本,直接在本仓库里试跑:
./gradlew run这时工作目录就是本仓库自己。你想让它去操作别的项目时,用上面的启动脚本,到目标目录里执行。
把 mcc 装成全局命令
每次写完整路径比较长。installDist 生成的脚本会顺着软链接找到自己的位置。
构建一次之后,下面两种方式选一种即可。
方式一,软链接到 /usr/local/bin:
./gradlew installDist
ln -sf /Users/wangzheng/projects/codecrush/mini-claude-code/build/install/mcc/bin/mcc /usr/local/bin/mcc方式二,把脚本所在目录加进 PATH。如果你用的是 zsh,可以这样写:
echo 'export PATH="/绝对路径/mini-claude-code/build/install/mcc/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc之后在任意项目目录里直接输入 mcc 即可:
cd /Users/wangzheng/projects/codecrush
mcc这里有一个前提:PATH 上的 java 已经是 17 或更高版本。你可以用 java -version 确认。
如果系统默认的 Java 不是 17,可以再包一层脚本,在 macOS 上用 java_home 锁定 JDK 17:
cat > /usr/local/bin/mcc <<'EOF'
#!/bin/sh
export JAVA_HOME="$(/usr/libexec/java_home -v 17)"
exec "/Users/wangzheng/projects/codecrush/mini-claude-code/build/install/mcc/bin/mcc" "$@"
EOF
chmod +x /usr/local/bin/mcc另外要注意,./gradlew clean 会删掉 build/install。你执行过 clean 之后,需要再跑一次 ./gradlew installDist,软链接才能继续用。
启动之后就进入交互式会话。你直接输入自然语言需求即可。以 / 开头的是会话命令。它们控制的是会话本身,不会被当成交给模型的任务。
会话命令
在会话里输入 /help,会按注册顺序列出当前命令。目前可以直接用的有这些:
/help:查看可用命令。/tools:列出当前已注册的工具,并标明只读还是写操作。/skills:列出当前可用的技能。/context:查看上下文各部分的 Token 占用。/clear:清空当前会话,重新开始。旧的会话日志仍留在磁盘上。/resume:恢复本项目最近一次会话。写成/resume <sessionId>可以恢复指定会话。/memory:查看或编辑记忆,包括AGENT.md、MEMORY.md和主题文件。/compact:手动触发一次上下文压缩。/plan:进入 Plan Mode。进入之后,它只做调研和规划,不做修改。/exit:退出会话。
这些命令分别在后面的里程碑里实现。你现在先知道它们能用、各自做什么即可。具体怎么写,我们放到对应的章节里讲。
代码结构
源码都在 com.minicc 包下面。程序入口是 MccApplication。它不使用 Spring Boot 的自动装配,而是把各个组件创建出来,再启动会话。你从这里往下读,能看见各部分是怎么串起来的。
com.minicc
├─ MccApplication 程序入口,装配组件并启动会话
├─ cli/ 交互式会话:Repl、斜杠命令、终端渲染
├─ agent/ 控制循环、工具调度、取消
├─ tool/ 工具接口、注册表、内置工具、执行前钩子
├─ context/ 上下文组装器与系统提示词
├─ model/ 模型调用边界 ModelClient
├─ session/ 会话状态与待办
├─ config/ 配置加载
├─ permission/ 写操作审批
├─ persistence/ 会话日志与待办快照
├─ memory/ 项目约定与自动记忆
├─ compact/ 上下文压缩
├─ skill/ 技能加载
├─ plan/ Plan Mode
└─ ask/ 向用户提问每个类的注释里写了它负责什么。你对照这个目录去读,比较容易找到入口。
开篇到这里
第 0 章到这里就结束了。我们要构建什么、harness 是什么、会话长什么样、能力有哪些、学习路径和开发规范,前面几节已经讲过。这一节则是把仓库里的程序构建出来并跑起来。
