Files
Agent-Workbench/docs/CHANGE-SETS.md
2026-10-29 19:33:24 +08:00

3.2 KiB

多文件变更集与恢复契约

1.4.0的M2切片。变更集把同Task的1–32份文本提案封存为一次审查;总原文和建议内容最多4MB。每个实际路径只能出现一次,拒绝文件/目录重叠、链接及Windows路径别名。源码文件的原字节和建议字节分别核对SHA256,保留文件格式和普通权限。

准备操作保存Task/Run、项目真实根目录、只读Git HEAD/分支、原/新文件哈希及内容快照工件;不写项目。界面按实际差异审核后,将同一个封存指纹提交给应用接口。模型只有准备工具,没有应用或回退工具。已封存的提案不能绕过批次单独应用;撤销未执行批次后可重新准备或逐项审查。

应用前再次核对全部提案、快照、Git HEAD/分支及全部目标文件,任一基线变化则整批不写入。逐文件写入意图先保存到SQLite,临时文件同步到磁盘后在同目录替换,再持久保存实际结果。普通执行失败或取消时尝试恢复本次已进入写入的文件;只在当前字节仍等于本次建议时回退,外部修改保留。已创建的空目录可保留,恢复不递归删除项目目录。

文件系统不提供跨文件原子事务;检查与替换之间也没有外部编辑器的通用文件锁。对外区分prepared、applying、completed、rolled_back、unknown/partial和cancelled,不能把半批结果写成成功。

真实进程中断后,宿主把尚未完成的批次标记为需核对,启动时不执行文件写入。显式核对校验封存快照并读取每个目标的实际哈希,记录原文、建议内容、外部修改或不可读取。完整建议内容且每项有写入意图才记为completed;全部原文则结束为interrupted/rolled_back;混合结果保持partial。用户可以显式回退本批次已写入文件;不自动续写或重放,新的修改从新提案开始。遗留的本批次回退临时文件只有类型/大小/SHA均匹配时才复用;内容不匹配则保留并提示核对。

其余目标均回到原文、外部修改已读取且当前观察指纹未变时,用户可明确「保留外部改动并结束恢复」,批次结束为resolved_external。该操作不写项目文件,也不记为成功应用;外部字节与原文状态保存在记录中,后续新任务可以继续。无法读取或仍有本次已写入内容时不能使用这个入口。

结果未核对时阻止同项目新运行、文件应用、检查和Git提交,恢复入口保留所属会话/Task。完成或回退都会使旧检查过期;交付报告引用批次身份、指纹和实际状态。历史批次可查看与核对,普通已完成批次回退仅作用于当前Task且核对封存指纹和当前文件哈希。

验收包含:整批预检冲突零写入、BOM/CRLF及权限保留、新文件、重复路径/祖先路径/链接、快照损坏、重复请求、同项目隔离、失败回退、owner修改保护,以及准备/写入意图/替换/逐项保存/回退/最终保存的真实进程退出。轮次上限后应用整批文件可继续原Task实际检查,其他暂停和未知工具结果不能借此继续。实际结果见QA-1.4,本文定义契约,不代替测试证据。