analysis_claude_code/articles/v2文章.md

mini Claude Code v2：让模型自我约束的 Todo 工具

v1 版本的 mini Claude Code 已经证明：只要把大模型嵌入一个简洁的工具循环，它就能像“代码工人”一样在本地仓库里读写文件、执行命令。但我们也遇到一个老问题——模型是否真的在有计划地推进任务？

顺便推荐一下我们维护的 Kode 项目：这是面向生产的开源版 Claude Code，收录了 Bash 扩展、WebSearch / WebFetch、Docker 适配等高级能力，适合直接落地企业级场景。若你在寻找更多资料，也可以参考我们先前整理的一系列开源实现与逆向分析，它们共同构成了如今 mini Claude Code 的"孵化器"。

在 v2 中，我们引入了一个看似朴素、却改变工作流体验的核心能力：Todo 工具链。它把“规划—执行—复盘”的节奏落在了代码级别，迫使模型对复杂任务进行显式拆解，从而让用户和模型都能清楚地看到每一步发生了什么。

1. 具体做了什么？

• 新增 TodoWrite 工具与 TodoManager：在工具列表中加入 TodoWrite，由 TodoManager 维护一个至多 20 条的任务列表，约束只允许一个条目处于 in_progress，并在每次更新时返回彩色状态视图与统计数据。
• 消息循环挂钩待办状态：在每轮模型输出后，如果出现对 Todo 的调用，就把更新结果作为工具反馈写回对话历史，让模型看到自己刚刚操作的“计划板”，形成自监督闭环。
• 系统提醒机制：在会话伊始植入 system reminder，如果连续 10 轮交互未触发 Todo，再次注入温和提醒，让模型持续感知“规划要求”；每次真正更新 Todo 后则重置计数器。
• 严格输入校验：对 Todo 输入的 id、status、activeForm 等字段进行检查，防止模型写入空任务、重复条目或异常状态，引导它遵循清晰的规范。

2. 背后的思想

模型依旧是核心，但要用规则把它“拴”在结构化工作流里。

1. 结构化约束代替自由生成：单纯的文本指令很容易让模型忘记计划，Todo 工具则把“计划”实体化为数据结构，模型只有维护好它才能继续执行。
2. 显式反馈增强自我监督：每次 Todo 更新都会立即显示当前状态，模型能在下一轮读到这段文本，相当于用环境反馈提醒它“你现在在做哪一步”。
3. 系统提示形成软约束：提醒块不是条件语句，而是上下文资料；它们用最小侵入的方式告诉模型“别忘记 Todo”，既保留灵活性，又能降低跑偏概率。

3. 能应用到哪些场景？

• 多步骤代码任务：例如“写接口 → 补测试 → 更新文档”，模型必须先把步骤写进 Todo，然后逐项勾选，用户可以随时检查进度。
• 长周期对话：在需要几十轮推演的需求中，system reminder 会周期性提醒模型遵守规划流程，避免它在自由文本里迷失。
• 团队协同与审计：把 Todo 输出存档，就能追踪模型在每次会话里的计划与执行痕迹，为回顾和复盘提供依据。

v1 的意义在于验证“模型 as agent”这一底层设计；v2 则进一步证明：只要给模型配备合适的结构化工具，它不仅能执行，更能规划、记忆和自我纠错。后续我们还会继续叠加 Task 子代理与更丰富的 system reminder 组合，并把 Kode 里的成熟特性不断反馈到 mini Claude Code，让它逐步靠近真实产品级 Agent 的形态。