编程智能体工程化：多文件真项目

把上下文、任务分解、测试与人工审阅接成工作流。

阅读约 12–15 分钟实践另需 30–45 分钟讲 · 例 · 做 · 卡编号 ba-make-19

学习证据学完后，怎么核对？如何核对 · 适用边界 · 最后复核

把学习结果留在一个可以回看、可以复做的动作里；这一区只写学生能自己检查的证据。

如何核对

完成一次合格工作流与一次被门禁阻断的失败路径
提交任务分解、上下文边界、测试记录和人工复核说明

适用边界

案例中的文件、命令、工具调用和测试均为本地内置模拟：不联网、不调用模型、不执行命令、不读写磁盘，也不代表任何具体编程智能体的真实权限。

最后复核

2026 年 7 月 16 日

这是内容复核日期，不是学习截止日期。

讲

定义编程智能体扩大执行半径，也扩大审阅责任

在多文件项目里，智能体可能提出修改建议，也可能在获准后读取文件、编辑代码和运行命令。前者仍是候选方案；后者会改变项目状态。工程化的重点不是让它“多做一点”，而是让每一步都回答四个问题：它看了什么、准备做什么、实际做了什么、凭什么可以交付。

模型建议

任务理解、风险猜测、计划草案。可以启发，但还不是项目事实。

工具执行

读取了哪些文件、运行了哪条命令、改了哪些行。必须受授权边界约束。

测试证据

命令、环境、用例与结果。它支持“已检验”，不自动等于“需求正确”。

人工判断

审 diff、核需求、判断风险并批准或退回。最终交付责任留在人手里。

例子把“一句话修好”拆成七个可停靠节点

本课使用一个小型课程日历前端：日期筛选把显示用日期当成可比较数据，筛选按钮又没有清楚宣布选中状态。看似只要“修两个 bug”，实际仍要先勘察依赖、收窄上下文，再用测试和人工审阅把修改封口。

需求可复现现象、验收标准、非目标

勘察文件树、入口、依赖、敏感边界

计划拆小任务，标风险与停止点

小范围编辑只改必要文件，保持 diff 可读

测试先定命令，再看失败与通过证据

人工审阅核范围、语义、回归与安全

交付变更、证据、边界、待办

失败信号	为什么危险	具体恢复动作
上下文过宽	无关文件增加噪声，也可能越过隐私、许可证或密钥边界。	退回文件树，只选入口、依赖与对应测试；记录为什么需要每个文件。
跳过测试	“代码看起来对”无法证明日期边界、键盘路径或回归没有破坏。	阻断批准；先跑与修改对应的最小测试，再补完整相关测试。
未授权命令	网络、安装、删除或环境修改可能产生项目外影响。	不执行；说明命令意图与影响，换成白名单命令或请求明确授权。
密钥进入上下文	即使“只为调试”，敏感值也不该进入提示、日志、diff 或提交。	立即移出上下文并作废暴露值；只保留字段名或占位符，再检查历史记录。
一次改太多文件	问题定位、审阅与回滚成本一起上升，顺手重构会掩盖真实修复。	把计划切成可独立验证的小补丁；本任务先限于逻辑与无障碍两个文件。

最小权限不是“什么都不让做”。它是让读取范围、可运行命令和可写文件与当前子任务匹配；需要扩大时，先解释原因，再由人批准。不同编程智能体、组织政策与项目脚本会变化，授权界面不是通用安全保证。

核心句：智能体可以提出计划并执行获准动作；工具记录说明发生了什么，测试提供可复做证据，而是否满足需求、是否值得交付仍由人判断。

例

先读静态项目切片，再进入离线工作台。脚本关闭时，这里的文件关系、差异片段与验收日志仍足以完成纸笔复盘。

课程日历 · 文件树

README.md
package.json
src/
1. index.html
2. styles.css
3. calendar.js
4. a11y.js
tests/
1. calendar.test.js
2. a11y.test.js
.env.example
.env.local（敏感边界，不选）

粗体是本任务可能需要检查的节点；敏感文件即使存在，也不等于应进入上下文。

依赖关系 · 为什么读这几个文件

index.htmlcalendar.js + a11y.js
calendar.jsfilterUpcoming(events, todayISO)
a11y.jssetFilterState(buttons, active)
calendar.test.js同日 / 跨月 / 空列表
a11y.test.jsaria-pressed / 状态播报

合格上下文不是“越多越稳”，而是能覆盖调用链、约束与测试的最小闭包。

合格路径 · 两个小补丁，共用一条证据链

先读 calendar.js、a11y.js 与两份相关测试；计划明确“不改 HTML、不换库、不重构样式”。第一个补丁把用于比较的日期改成 ISO 值，第二个补丁同步 aria-pressed 与状态区文本。相关测试 4/4 通过后，人再核对 diff 是否只触及两文件、同日事件是否保留、无障碍状态是否可读，最后才批准交付。

失败路径 · “为省事”选全仓并跳过测试

智能体建议“顺手统一日期库并整理样式”，操作者允许读取全部文件、执行联网安装，再依据“修改完成”直接批准。这里同时丢失了上下文边界、命令授权、最小 diff 与测试证据。恢复不是继续补解释，而是撤回到最近的安全门：移除敏感与无关文件，拒绝网络命令，把任务重新拆成两个可测的小补丁。

静态差异片段 · 证据样张（内置示例，不写磁盘）

- return events.filter(e => e.displayDate >= todayISO);
 return events.filter(e => e.startISO >= todayISO);

 buttons.forEach(btn => btn.setAttribute(
   "aria-pressed", String(btn.dataset.filter === active)
 ));

互动案例

多文件真项目 · 课程日历修复台

观察 → 选上下文 → 拆小任务 → 模拟编辑 → 测试门 → 人工批准：用一条可复查日志区分建议、执行、证据与判断。

互动版需要运行脚本（本地 HTTP 预览）；不运行脚本时，上面的静态例子已包含同样的内容。

做

智能体已经给出一份看起来合理的两文件 diff。下一步哪项最符合工程责任？

工程交接包 · 学生产出

从你手边一个小型多文件项目选一个真实、可复现的问题；没有可用项目时，可沿用课程日历情境做纸笔版本。提交四部分：

1 · 任务分解

列出 2–4 个可独立验证的子任务，每项写停止点和失败后的回退位置。

2 · 上下文边界

列出允许读、允许改、明确不读的文件，并说明每个入选文件与任务的关系。

3 · 测试证据

记录命令、环境、预期、实际结果；至少保留一次失败与恢复，不只写“已测试”。

4 · 人工复核

说明你审了哪些差异、发现什么风险、为何批准或退回，以及仍未覆盖什么。

怎么算过关：同伴只看交接包，就能复做一次合格路径，指出一个会被门禁阻断的失败路径，并分清建议、执行、测试与人工判断。不要提交真实密钥、个人数据或未经许可的项目内容。

迁移任务 · 换一个项目仍能成立吗

把课程日历换成“修复实验室预约表重复提交”或“修复研究资料页键盘焦点丢失”。不写代码，先各写一版：最小上下文包、两个子任务、允许命令、测试门与人工批准门。比较两版哪些门禁保持不变，哪些必须随项目风险调整。

卡

复习卡 · 点一下翻面

智能体说“任务完成，测试通过”，为什么还不能直接交付？

答案

这句话混合了建议、执行、证据与判断。你仍要看实际工具记录与 diff，确认测试命令和结果覆盖需求，排除越权、敏感数据和无关改动，最后由人判断是否满足任务与风险标准。

上下文包应覆盖当前调用链与测试，不应默认等于整个仓库。
把任务拆到可单独编辑、测试和回退；一次改太多会削弱审阅与定位。
建议不是执行，执行不是测试，测试也不是最终批准；可追溯交付需要四者分栏。
遇到过宽、越权、泄密或跳测时，退回最近安全门，修正后重走，不用一句道歉掩盖状态。