18. 综合实践：让 Kimi Code 完成一次可验收的项目迭代

来源：大模型应用工程化

打开前面导出的复习资料，第三张卡片写着“笔记未提供，无法判断”。这句话没有编造答案，是正确的边界处理，但读者接下来该做什么？

这一次，我们给资料不足的卡片增加一句明确的下一步提示。需求很小，却足够走完一次完整迭代：理解问题、写规格、建立基线、让 Kimi 修改、根据失败反馈修正、留下接手记录，最后把真正修改过的工具交付出来。

这也是第四部分的最后一篇。目标不是把前17篇的工具全部调用一遍，而是能够按任务需要选择方法，并说明为什么这次改动可以接受。

先确定改的究竟是什么

本次目标是导出的 Markdown 资料，而不是模型接口、数据库或网页。

对于 status=missing 的卡片，在状态之后、依据之前增加：

下一步：

    补充与该问题直接相关的笔记，再重新生成。

原答案仍然是“笔记未提供，无法判断”；提示作为单独的呈现内容，不写进模型的 answer，不伪装成引用，也不自动触发新请求。supported 卡片不显示这段提示。

这个区分很重要。若把答案替换成建议，原来“资料不足时使用固定答案”的数据契约就被改掉了；若自动点击式重新生成，还会引入新的请求与费用。本轮只改善读者看见资料不足后的操作方向。

应用仍使用 DeepSeek 官方 API，Kimi Code 只是开发助手。作者提供的参考实现由作者编写并离线验证，没有冒称来自一次真实 Kimi 生成。

准备一个可以验收的起点

下载完整练习包，解压到新的目录。Python 3.11或更高版本即可，离线主路径不需要 SDK、Key或依赖安装。

在外层 lesson-18 中，你会看到：

workspace/                    本次允许修改的工作区
  export_review.py            起始版本，尚无下一步提示
  verify_export.py            已有导出验证器
  project/                    前17篇的正确应用，38文件
  docs/capstone/TASK.md        本轮需求与范围
reference/
  export_review.py            作者参考答案，单个替换文件
  change.diff                 参考差异
verify_capstone.py            新的独立行为检查
package_capstone.py           本次工具专用打包器
docs/                        接手、交付和迁移模板

reference 不是可独立运行的项目。其导出脚本需要与 project 放在相应工作目录中，不能直接在 reference 下运行后，再把缺文件当成代码错误。

workspace 的业务项目沿用第17篇正确版本，外层导出器保留起始行为。我们刻意让初始交付不是“已经做完的答案”，这样你能先看到新需求尚未满足的证据。

第一步，在外层执行：

macOS/Linux：

python3 -B verify_capstone.py workspace

PowerShell：

py -3 -B verify_capstone.py workspace

预期是执行7项检查，其中2项失败、5项通过，退出码为1。末尾会出现：

Ran 7 tests in ...s

FAILED (failures=2)

耗时随机器变化。两项失败分别说明：资料不足卡片缺少提示；多张资料不足卡片也没有逐张展示提示。这是新增需求尚未实现，不是原来的导出能力突然坏了。

其余检查保留已有能力：有依据的卡片不加提示、正常CLI导出仍通过旧验证、坏引用仍被拒绝、旧输出不被覆盖、输入文本仍按普通文本呈现。检查直接使用 Python 的 unittest，失败会形成明确的断言与退出状态。官方测试文档解释了这一机制。

给 Kimi 的任务，比“优化一下”更具体

先读任务卡。它规定只修改 export_review.py，其余应用代码、验证器、题集、依赖和模型请求保持原样。

如果你已经有可用的 Kimi Code，在外层进入工作区：

cd workspace
kimi --version
kimi --plan

作者核实的本机版本为2.0.2。--plan 用于从计划模式开始，--continue 则可继续当前目录最近的会话；具体行为以当前官方命令参考和本机帮助为准。计划模式不替代路径和权限审查。

真实 Kimi 开发请求可能消耗服务额度。此次练习先限制为一次计划、最多两轮针对失败的修改反馈；没有证据支撑继续修改时就停下来记录问题。轮数是工作范围，不是金额硬上限，实际额度由你在服务端确认。

在会话中提供：

请先读AGENTS.md、docs/capstone/TASK.md、export_review.py和verify_export.py。
新增验收在父目录../verify_capstone.py；你可以读取它，但不能修改它。

目标：每张missing卡片增加独立的下一步提示，supported不增加。
只改export_review.py，不改模型答案、引用规则、project、依赖或数据库。
先解释改动位置、需要保留的行为和验证方法，不立即修改。
请指出当前资料是否足够；不要调用模型API、安装工具或读取私人配置。
本轮不需要多Agent、MCP或新的自动循环。

一份可接受的计划应该找到 render 的逐卡片循环，并说明按卡片状态判断，在呈现层增加段落；验证仍保留原来的导出流程。若计划要修改 validation.py 的固定答案规则，或者换一个“更聪明”的模型，它已经偏离本轮问题。

核对方案符合任务后，再明确让它实施，例如：“按这个方案完成最小修改，运行新增验证，报告实际差异和退出码。”你允许它修改的是有边界的工作项，不是在这里替它确认代码已经正确。

用失败反馈推动下一步，而不是继续猜

完成修改后，从工作区回到外层：

cd ..
python3 -B verify_capstone.py workspace

Windows使用 py -3 -B。预期变成7项通过，末尾为 OK，退出码为0。

如果仍有失败，不要只把整份日志交回去说“继续修”。先辨认它对应哪条要求，再提供一条可定位的反馈：

test_supported_cards_do_not_get_action 失败。当前代码把提示加到了所有卡片，但任务只允许 missing。请检查分支条件，只改导出呈现，不修改测试或答案。

这是有证据的修复请求。相反，如果只是觉得措辞还不够热情，就要求它反复重写整个导出器，反而会扩大无关变化。

还要注意测试的边界。多张 missing 的测试数据由作者构造，用来验证逐张呈现，不是模型实测回答，更不能据此计算模型准确率。固定文字通过也不意味着“建议永远适合所有用户”；这里只验收本次明确的产品规则。

若两轮反馈以后还未定位，保留日志和差异，说明哪条要求未满足。停止条件应在开始前确定，不能因为快到结尾，就降低断言来获得一个绿色结果。

查看差异，再看真正的导出结果

参考实现只在卡片循环中增加两行：

if card['status'] == 'missing':
    lines += ['下一步：', '', literal('补充与该问题直接相关的笔记，再重新生成。'), '']

这里先依据已经存在的 status 决定是否显示，再复用 literal 保持普通文本呈现。它没有改答案、证据或模型调用。

实际由 Kimi 完成的代码不必逐字符等于参考实现，但你应能解释每一处差异，并检查它没有越过任务范围。如果已经使用Git，用第3篇的方法检查自己的修改；也可以直接在编辑器中比较工作文件和参考差异。不要拿“修改行数少”代替行为验证。

现在进入 workspace，使用新的输出名：

cd workspace
python3 -B export_review.py --fixture valid --out capstone-review-01
python3 -B verify_export.py capstone-review-01

导出应报告3张卡片，原验证器应报告 pass，两者的语义状态仍是 pending。打开 capstone-review-01/review.md，逐项检查：

• Q1、Q2仍然展示原答案与引文，不出现新的提示段落。
• Q3保留固定的资料不足答案，单独展示“下一步”，然后仍写“依据：无；资料不足”。
• 文件继续标明作者构造样例和待人工语义核对。

如果你发现提示出现在所有卡片上，即使它看起来很友好，也不符合本次规格。如果固定答案被建议替换了，也应退回修正。

已有输出名会被拒绝覆盖。下一次用 capstone-review-02，保留旧文件用于比较；不要把清理证据当成修复的一部分。

没有 Kimi，也能验证完整参考路径

不想调用开发服务的读者可以先走离线对照。回到外层 lesson-18，使用一个不存在的新目录名：

python3 -c "import shutil; shutil.copytree('workspace', 'offline-workspace'); shutil.copyfile('reference/export_review.py', 'offline-workspace/export_review.py')"
python3 -B verify_capstone.py offline-workspace
python3 -B offline-workspace/export_review.py --fixture valid --out offline-review-01
python3 -B offline-workspace/verify_export.py offline-review-01

PowerShell同样将 python3 换成 py -3。第一条命令复制工作区并替换副本中的一个文件；copytree 会拒绝覆盖已有目录。原 workspace 保留，不会因为参考版通过就自动变成完成状态。

这条路线让你检查作者方案，不能将其记录成“我已经让 Kimi 完成了开发”。如果之后练习真实 Agent，仍要记录它实际改了什么和实际执行的验证。

有意留一次接手，而不是把任务重做一遍

为了练习第15篇的方法，可以在“代码已经修改、独立验证尚未运行”的时点暂停。先确认当前没有未结束的命令或写入；不必杀进程来模拟事故。

复制并填写接手模板，保存为工作区的 docs/capstone/HANDOFF.md。写清实际目录、变更文件、已完成和未完成的检查、输出位置及已使用的反馈轮数。没有执行的测试就写“未执行”，不要猜结果。

恢复同一个目录的最近会话可以使用 kimi --continue；也可以在新计划会话中提供以下要求：

先读docs/capstone/HANDOFF.md和当前TASK。
核对工作区实际代码与交接描述，不要直接按摘要重新实现。
如果修改已存在但尚未验证，先运行父目录的verify_capstone检查。
不要覆盖旧导出，不重置已使用的反馈轮数。
发现事实与交接不一致时，说明差异和最小核对动作。

这次是控制好的人工暂停，不是自动崩溃恢复系统。换会话以后还要接着核实文件，因为聊天历史本身不能证明磁盘上的状态。

本轮出现测试失败时，也用同一张工作卡记录：哪条要求失败、什么修改已经尝试、目前证据在哪里。接手的价值，是让下一次行动更小、更明确，而不是再消耗一轮从头探索。

最后交付哪个包：这里容易选错

第17篇的应用源码包包含38个 project 文件，却不含外层的 export_review.py。如果仍然只交付那个包，本次修改根本没有交出去。

因此，本课提供专用打包器：包含应用输入38文件，加上 export_review.py 和 verify_export.py，共40文件。用途明确为离线固定样例导出工具，不把它称作完整的新网页功能。

回到外层执行：

cd ..
python3 -B package_capstone.py --target workspace --out delivery-01

这里的 cd .. 适用于你仍停留在前面的 workspace 时；已经在外层就不要再执行它。离线参考路线改用 --target offline-workspace --out offline-delivery-01。

正常结果应为：

{"status": "candidate", "files": 40, "verification_exit": 0, "published": false}

打包器会将实际 ZIP 展开到临时目录，对展开内容重新运行同样的7项检查。它还核对源文件在打包期间没有最终变化，并保存 manifest.json 和检查日志。起始未实现版本会得到 blocked，不能当作合格交付。

打开新交付目录，应有 review-tool.zip、manifest.json、checks.stdout.log 和 checks.stderr.log。查看 ZIP 的成员，确认实际包含修改后的导出器；查看日志，确认7项通过，而不是只看到打包程序返回了0。

收件人解压后在 review-tool 中，可以运行 python3 -B export_review.py --fixture valid --out review-01 生成固定样例。应用配置、真实数据与凭据都不属于这个包；这仍不是备份，也没有被上传或发布。

最后填写交付说明：问题、差异、验证命令及日志、手工观察、未验证范围、包位置、恢复方法。这个呈现变更可以通过恢复原导出器撤销；不涉及数据库回退。已经生成的文件分别保留，不因撤回代码就假装旧产物不存在。

哪些方法用上了，哪些暂时不需要

这次任务里，规格决定了显示条件，上下文限定了阅读文件，独立测试提供反馈，差异审查控制修改范围，接手记录支持换会话，包核验确认真正交出去的内容。所有方法都对应一个实际问题。

我们没有为了综合实践强行增加多 Agent：两行呈现修改通常不值得额外分工；没有引入 MCP，因为本地文件足够；没有自动不断重试，因为预算和停止条件已经清楚。这些工具仍然有用，只是要在需求出现时使用。

把方法迁移到自己的项目，可以从最小迭代卡开始。尝试将“让我这个项目更好用”缩小成一个可观察变化，写出正例、反例和不能改变的行为，再决定需要哪些上下文和验证。

完成前的最后检查

问题	合格的回答
初始失败是否有解释？	两个新增呈现要求未满足，原有检查继续通过
谁修改了什么？	据实写Kimi或自己；业务改动只在导出器
是否通过独立验证？	有实际7项结果，未修改断言求绿
用户能看见什么变化？	missing卡片有下一步，有依据卡片无此提示
中断后如何接手？	有事实记录，先查差异和未完成验证，不盲目重做
包里是否包含新功能？	40文件专用包包含修改后的导出器，展开后再次验证
哪些结论还不能声称？	未证明真实模型准确率、未做线上发布，语义审核仍有范围

作者实际验证了：起始7项中2失败；参考版本7项通过；CLI导出仍通过旧验证；错误地给所有卡片加提示、改写missing答案的变体会被拒绝；未实现版本打包被阻塞，参考包展开后通过。应用38文件保持不变。上述均为本地离线结果，没有真实 Kimi/DeepSeek 调用或Windows实机测试。

第四部分到这里结束。你已经能把一个需求推进到可检查的修改、可解释的证据和可交付的结果，也能在失败或中断时说明下一步该做什么。以后更换开发助手时，这套工作方法仍然可以保留；工具负责协助完成步骤，是否满足需求则由具体事实来判断。