工程化 / 大模型应用工程化

1. 从 Vibe Coding 到可验证的开发——一次任务到底怎样才算完成

本篇目录 · 8 节

来源：大模型应用工程化

你让AI“给页面加一个统计”，它很快回复“已完成”。打开页面，确实多了一行数字。但这个数字算的是所有资料，还是马上要发给模型的片段？刷新时会不会重新读取文件？它为了做这个小功能，有没有顺手换掉模型接入或数据库代码？

这些问题并不要求你先成为资深程序员。你需要的是一个能跟得上的工作过程：说清要改什么，知道它打算改哪里，查看真实变化，再用独立检查确认结果。

第四部分就从这样一个小任务开始。我们继续使用第三部分的个人笔记助手，让Kimi Code协助它增加“已选证据”的片段数和字符数展示。本篇结束时，你应当能够说明一次修改为什么可以接受，而不只是转述Agent的“完成”消息。

下载本篇练习包 · 独立运行说明 · 完整任务文本 · 第三部分目录

核实日期：2026年10月4日。本机只对Kimi Code CLI执行了版本和帮助检查，版本为2.0.2；没有使用用户账号发起真实Kimi开发请求。包中的reference是作者提供并离线验证的参考实现，不是伪造的Kimi会话产物。应用依赖沿用Python 3.11+、openai 3.24.0与Flask 3.1.3。

一、先分清开发工具和应用本身

第三部分的笔记助手是一个Python应用。它负责读取资料、检索片段、调用DeepSeek、检查回答，并保存问答和复习计划。第四部分增加的是开发方式：让Kimi Code帮助我们理解代码、提出修改和运行验证。

两条路径要分开看：

开发时：你 → Kimi Code → 阅读和修改项目 → 本地验证
使用时：你 → 笔记助手网页 → Python后端 → DeepSeek API（真实模式）

Kimi Code协助修改项目，不会因此成为笔记助手运行时的新后端。改完代码后退出Kimi Code，仍然可以单独启动笔记助手。应用的DeepSeek配置与开发工具的登录配置，也不是同一份东西。

本篇默认使用笔记助手的离线模式，因此验证页面不会调用DeepSeek。不过，向Kimi Code发送开发任务本身可能消耗你的Kimi服务额度。不能把“应用离线”理解成“开发Agent也完全不联网”。

方法是通用的。你可以用其他Code Agent完成同一个任务，只是具体操作不同；本课程以Kimi Code作为贯穿实践的工具，不在这里重写一整套产品说明书。

二、准备一份可以放心练习的项目

下载并解压本篇练习包，进入lesson-01目录。它包含：

文件或目录	用途
starter	第三部分最终版的干净源码，供你实际修改
reference	作者的完成版，供对照；不是练习的工作目录
TASK.md	可交给Agent的任务与边界
verify_preview.py	从应用外部检查新功能的脚本
README.md	不依赖本文也能运行的简要说明

starter的38个文件与第三部分最终快照一致，没有复制你的运行历史、密钥、虚拟环境或个人配置。没读第三部分也可以从这里开始。暂时不要覆盖你以前实际使用过的项目，也不要把自己的私密笔记搬进练习目录。

在lesson-01目录打开终端，先建立Python环境。macOS/Linux：

python3 -m venv .venv
.venv/bin/python -m pip install -r starter/requirements.txt
.venv/bin/python -m pip check
.venv/bin/python starter/acceptance.py

Windows PowerShell：

py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r starter/requirements.txt
.\.venv\Scripts\python.exe -m pip check
.\.venv\Scripts\python.exe starter/acceptance.py

需要Python 3.11或以上版本。安装依赖会访问软件包服务；最后的验收在临时目录运行，不需要API Key或config.json，应看到Ran 10 tests和OK。这是修改前的基线：你先确认原项目正常，之后才知道新增失败是否由这次修改引入。

这些检查使用Flask测试客户端，没有真的打开浏览器。它们能检查后端请求、状态和记录，不能证明页面在你的浏览器中看起来合适。稍后还会手工验证页面。Flask测试文档

三、让Kimi Code进入正确的工作目录

已经装好Kimi Code的读者，先执行kimi --version确认命令可用。本文核实的是2.0.2；未来版本变化时应结合官方文档和kimi --help，不要照搬旧版kimi-cli的安装方式。

尚未安装的读者，可按官方入门说明安装。当前npm路线需要Node.js 22.19.0或以上，先用node --version检查，再执行：

npm install -g @moonshot-ai/kimi-code
kimi --version

上述npm命令在安装好Node/npm的终端执行，不是在Python解释器里执行。Windows还需按官方要求安装Git for Windows，供Kimi Code的命令执行环境使用。没有Node的读者可以选择官方页面提供的独立安装路线；不要在这里混用几套安装方式。

回到lesson-01目录后：

cd starter
kimi

首次使用时，在Kimi交互界面输入/login，选择官方Kimi Code登录路径，按提示在浏览器完成授权。自己的开发账户与应用的DeepSeek Key分开管理，不要把DeepSeek Key粘进这一步。登录失败先解决账户、网络或额度问题，不要改笔记助手源码来“修好登录”。

这里不启用跳过确认的参数。具体修改和命令出现时，阅读它要操作的路径与内容，再决定是否允许。kimi以当前项目目录开始工作；命令参数和运行模式以官方命令参考及本机帮助为准。

如果暂时没有可用Kimi账户，你仍可阅读任务，查看reference并运行全部本地验证。这样学到的是修改与验收方法，但不能把这条替代路线记成“已经真实操作过Kimi”。

四、这个小功能，怎样描述才没有歧义

我们的需求是：在“检查将使用的证据”页面，显示本次已选中片段的数量，以及这些片段文本的字符数之和。

为什么值得显示？页面上既有已选中，也有未选中的候选片段。用户需要知道真正进入生成请求的资料规模。这个数字用于理解输入，不用来计算账单。

先明确四条验收条件：

默认样例选择两个片段，应显示“2个片段、67个字符”。
把最多片段改成1，应显示“1个片段、43个字符”，不能把未选中的候选资料算进去。
关键词改成“查找”，无命中时显示0/0，仍然不允许生成。
已建立的预览使用保存的快照；之后修改源文件并刷新旧预览，不应悄悄改变数字。

字符口径也要写清：使用Python的len(text)，保留片段文本中的标点、空格和换行；不额外插入片段之间的分隔符，不计算问题和提示词。这不是Token数，更不是费用。对于包含组合字符的文本，Python字符串长度也不一定等于人眼看到的字形数量，界面必须说明采用的口径。Python字符串说明

默认数据中的两个片段各保留一个末尾换行，因此统计不是简单数完屏幕上的汉字。数字差一点，也可能是需求和测试对换行的理解不一致，不一定是模型“算术差”。

将下面内容发给Kimi Code；完整版本也在TASK.md中：

请给当前笔记助手的证据预览页增加一行统计。
先阅读web_app.py、templates/web.html和必要的rag.py，说明预览如何保存、如何展示，以及建议修改哪些文件。先给方案，等我确认后再改。

显示：已选证据：X 个片段，共 Y 个字符（不等于 Token 数，不含问题与提示词）。
X是本次保存快照snapshot.notes的数量；Y是其中每个note.text的Python len之和，包含原有换行，不增加片段间分隔符。
没有命中显示0/0，仍不生成。首页不显示统计。刷新旧预览使用旧快照，不重新读取资料或调用模型。

保留DeepSeek接入、数据库结构、生成与计划流程，不换依赖、不重写项目。
不要读取个人凭据、不要调用真实API，不修改外部验收脚本，也不要读取reference答案。
请说明你需要运行哪些本地验证命令，以及需要我补充的解释器路径。

这不是追求一段“神奇提示词”。我们正在把任务转成双方都能检查的约定。下一篇会进一步讨论，怎样从更模糊的想法写出这样的要求。

五、先看方案，再让它修改

一个合理方案应能指出：预览资料已经由后端存入操作快照；显示旧预览时从该快照取出选中资料，计算数量和长度；模板把两个数字展示出来。因此，这次通常只需要改web_app.py和templates/web.html。

Agent不必与参考实现逐字一样。例如，它可能选择一个小辅助函数来组织统计。但如果它提出更换模型、增加数据库表、安装Token计算库、重新检索全部文件，就应该让它解释这些变化是否真的为当前需求所必需。

你可以这样确认方案：

按上述小范围方案实施。请保留原生成路径与模型配置。
先报告准备修改的文件，修改后列出实际变化。
验证时使用我给出的本机Python路径；如果命令失败，请先解释原因，不要自行安装依赖或修改验收预期。

还要补充解释器位置。我们把.venv建在lesson-01目录，而Agent当前在starter里。macOS/Linux的相对解释器路径是../.venv/bin/python。Windows的虚拟环境位于父目录.venv/Scripts/python.exe；Kimi的命令Shell可能是Git Bash，不能把PowerShell语法原样当成它的执行语法。把操作系统、解释器实际路径告诉它，并检查它生成的命令。也可以让它只改代码，你在另一个PowerShell终端运行下面的验证。

权限确认只是允许某项操作发生，不是确认修改已经正确。看到“运行命令”时，要看命令是否只在练习范围内工作，有没有额外下载、删除或真实API调用。本篇不会因为Agent要求更大权限，就把整个电脑交给它处理。

六、用独立检查决定是否接受结果

另开终端并进入lesson-01目录。这里与Agent的starter工作目录不同，不要漏掉这一步。

macOS/Linux：

.venv/bin/python verify_preview.py starter
.venv/bin/python starter/acceptance.py

Windows PowerShell：

.\.venv\Scripts\python.exe verify_preview.py starter
.\.venv\Scripts\python.exe starter/acceptance.py

第一条检查新功能的五个场景：默认两个片段、只选一个、无命中、旧快照不变、首页不显示统计。第二条重新检查原来10个验收场景，包括引用、重复操作、会话和计划等。

未修改starter时，第一条应有4项失败、1项通过，因为新功能还不存在，首页本来就没有统计。修改完成后，两条都应为OK。这是“基线正常—新要求尚未实现—实现后通过—旧行为继续通过”的过程。

脚本使用Python标准库unittest，失败信息包含实际结果与断言。不要因为最后出现FAILED，就把所有断言都改成能通过；应该回到任务判断失败来自代码、测试还是需求口径。Python unittest文档

本篇的验证脚本位于应用目录之外，是为了给你保留一份独立检查。它不是访问控制机制，Agent仍可能有能力读取或修改父目录。因此你仍应检查它有没有动测试文件，必要时从原下载包取回验证脚本。

再用编辑器查看修改后的两个文件，对照初始版本或参考实现。确认没有更换model、API地址、依赖和数据库结构。下一篇之后会逐步引入Git，让这种检查更清楚；本篇不要求你先掌握Git才能完成第一次任务。

参考实现中，后端在show_preview里新增两个模板参数：

        return page(preview=item, ticket=ticket, selected=selected,
                    evidence_count=len(item["snapshot"]["notes"]),
                    evidence_chars=sum(len(note["text"]) for note in item["snapshot"]["notes"]))

它统计的是已保存的notes，没有再次调用检索函数，也没有访问模型。模板只显示计算结果。对于这个需求，这样的改动足以完成任务。

七、打开页面，亲自走一遍

保持终端位于lesson-01目录，运行：

.venv/bin/python starter/run_local.py init
.venv/bin/python starter/run_local.py serve

Windows分别使用.\.venv\Scripts\python.exe starter/run_local.py init和.\.venv\Scripts\python.exe starter/run_local.py serve。初始化只创建缺失的配置；已有配置保留。打开http://127.0.0.1:8765，页面应显示离线演示。

使用默认资料、问题、关键词“检索片段”和最多2片段，点击“预览检索证据”。在证据区域应看到：

已选证据：2 个片段，共 67 个字符（不等于 Token 数，不含问题与提示词）。

再返回首页，新建一次预览，把最多片段改成1，结果应为1/43。再返回首页把关键词改成“查找”，结果应为0/0，并保留“没有命中片段，不调用模型”的提示。

K=1属于自定义预览，离线固定答案只支持默认配置，所以没有演示生成按钮是原有行为，不是新增统计弄坏了程序。要检查旧生成流程，回到默认配置再生成演示卡片即可。

页面暂时仍保留第三部分的原篇号，我们没有为了这次统计需求修改无关标题。停止服务回到终端按Ctrl+C。不要同时启动starter与reference两套服务；端口和浏览器Cookie都可能干扰你的观察。

如果没有进行真实Agent练习，也可以将上述命令中的starter换成reference，验证作者实现。两条路径的学习记录要分开：一条是你完成了Agent协作，一条是你理解并运行了已给出的代码。

八、遇到失败时，先确定哪一步出了问题

现象	先检查
找不到kimi命令	是否安装成功、是否重新打开终端、PATH是否正确；别改应用源码
Kimi登录或额度失败	开发工具自己的账户状态；与DeepSeek应用配置分开
Python找不到Flask	是否使用lesson-01里的虚拟环境，依赖是否装在同一个解释器
修改后测试仍显示缺统计	Agent改的是不是starter，是否只改了reference，是否保存了文件
字符数相差1或2	是否保留片段末尾换行，是否额外插入分隔符，是否算入未选片段
页面数字正确，但旧验收失败	是否连带修改生成、计划或打包规则；检查实际差异
端口被占用或看到旧页面	停止旧副本，确认启动路径；必要时明确换端口
Agent说测试通过，但没有命令结果	自己重跑，不把叙述当作执行证据

本篇作者验证了：原starter的10项验收通过；新增脚本在未修改版本按预期失败；参考实现的5项新检查和10项原验收通过；原第三部分源码保留，参考实现只有两个文件发生变化。全部为本地离线检查，没有真实Kimi任务输出、DeepSeek调用或Windows实机验证，也没有把测试客户端说成真实浏览器验收。

最后问自己：如果页面多了统计、但统计的是全部候选片段，任务完成了吗？没有，输出符合外观，却违反了统计范围。如果新测试通过、但Agent把DeepSeek替换成另一服务呢？也不能直接接受，因为它做了需求之外的重要改变。

这就是本篇要建立的判断：一次任务完成，需要结果符合约定、修改范围可解释、验证证据可复查。 下一篇从更模糊的“帮我加一个历史搜索”开始，学习怎样把想法整理成清楚的需求和规格。