用途
该技能用有界、可产出证据的修复流程替代“打补丁—重试”的循环行为。只有当可观测量发生变化时,才把补丁变更视为进展。适用于 AI 编码代理反复应用相似补丁但观测到的故障未改变,或聚焦测试通过而安装、部署、UI、API、持久化等真实执行路径仍失败的情况,也适用于修复声明需要一个能拒绝已知错误状态的验证器、以及一个已在一次性副本上实际恢复基线的回滚。不适用于一次性、已理解清楚且验收检查直接覆盖完整行为的编辑。
主要能力
- 修复契约:首次编辑前记录确切缺陷及可反驳它的行为、被测修订与配置/输入/执行路径、基线命令与字面结果及退出状态、直接观测声明行为的最强检查、回滚命令及必须恢复的状态。无法复现缺陷时停止编辑并报告 INCONCLUSIVE。
- 三次尝试预算:一个验收声明最多三次修复尝试;代码、配置、依赖、生成产物或测试预期变化即开始一次尝试,只读探测不消耗尝试。代理重启、新会话、重写同一补丁、换模型、清缓存或重命名假设都不重置预算。
- 证据台账字段:每次尝试记录假设(单一因果机制)、预测(可区分观察)、变更(确切路径与补丁或前后哈希)、聚焦检查(命令、输入、字面输出、退出状态)、真实路径检查(直接观测或 NOT_RUN 及原因)、症状指纹、决策(ADVANCE、SHIFT_CAUSE、PROVEN、STOP)。
- 症状指纹:对系统行为而非代理解释做规范化记录,包含 schema_version、command、input_digest、exit_code、failure_class、stable_excerpt、real_path_state。去除不影响缺陷的时间戳、运行 ID、ANSI 码、随机端口和临时路径,但不抹去可能区分两种原因的值。补丁哈希单独记录,不进入症状指纹。
- 根因策略切换:出现指纹重复、补丁变化而决定性状态不变、聚焦测试通过但真实路径失败、重试未产生新的区分性证据时设为 SHIFT_CAUSE:列出尝试过的机制及证伪观察,定位下一个未观测的归属边界(输入、调度、配置、依赖、生成产物、进程、持久化、网络、呈现),在该边界收集一项新观察,形成能预测不同观察的替代假设,不能区分则返回 BLOCKED。不得扩大编辑同一机制、弱化断言、跳过失败路径、加静默回退或改预期输出来换绿。
- 真实路径取证:按声明匹配证明——CLI 行为需以用户方式调用已安装或构建的入口;API 或集成需发送真实请求并观察响应与负责的服务边界;UI 需真实交互并观察 UI 状态及相关网络或控制台证据;持久化需写入后在新读取路径或进程中重载并观察存储值;部署需执行已部署修订并证明是哪一版修订提供了结果;代理或工具动作需观察实际工具调用及外部状态变化。单元测试、mock、类型检查、构建、端口开放、进程存活检查或模型总结仅在声明跨越其未覆盖的边界时作为辅助证据。
- 验证器可证伪:修改路径通过后,在一次性副本中重新引入原始缺陷或已知错误输入,用相同主验证命令与相关配置要求退出码非零且由预期断言导致;无关崩溃、缺依赖、超时、语法错误或测试发现失败不算有效反向对照。已知错误状态退出零即验证器假绿,返回 INCONCLUSIVE 并修复验证器。之后回到未改动的主修改树重跑主验证。
- 回滚测试:在另一份一次性副本上运行文档化回滚命令,验证变更路径与哈希匹配记录的基线,运行基线命令确认先前行为恢复,主修改树保持不变。仅能解析、打印帮助或零退出而未恢复行为的回滚脚本视为未测试。
- 证据状态:PROVEN 需基线缺陷已观测、责任变更已识别、聚焦与真实路径检查通过、已知错误反向对照因预期原因非零退出、回滚在另一副本成功、主树保持修改且通过;INCONCLUSIVE 表示有关键门缺失、假绿或模糊;BLOCKED 表示预算耗尽、重复指纹无新区分或指定外部条件阻碍下一次观察。报告需给出精确命令、输入、字面结果、退出状态、指纹、变更路径、修订与剩余缺口。
使用方式
使用可复制的证据台账记录每次尝试;可选地在本技能目录运行 python3 scripts/fingerprint.py evidence/attempt-1.json 计算规范 SHA-256 指纹。该辅助脚本校验记录、拒绝未知字段并打印指纹,不执行命令、不脱敏。修改脚本后运行 bundled 回归测试:PYTHONDONTWRITEBYTECODE=1 python3 -m unittest scripts/test_fingerprint.py -v。工具仅使用 Python 3.9+ 标准库。
适用场景
AI 代理反复打补丁但故障指纹不变;聚焦测试通过而安装、部署或真实路径失败;修复声明需要可拒绝已知错误状态的验证器;需要证明回滚可恢复基线;需要区分“补丁变化”与“观测状态变化”。
限制
缺陷不可复现、真实执行路径不可访问或主验证器无法观测验收声明时无法证明修复。三次尝试预算只能暴露停滞,不识别正确架构,也不替代领域专业能力。已知错误对照只证明一个验证器捕获一类缺陷,不等于完整测试覆盖。回滚验证只覆盖记录的路径与基线行为,外部系统需自行进行提供方侧读回。
安全与安全说明
该技能可指导对代码、配置、依赖、生成产物与文件的更改,风险等级为 critical。修改状态前确认仓库、目标环境、可接受路径与审批边界;破坏性、不可逆、生产、财务、凭据或外部消息动作前先询问。反向对照与回滚试验只在一次性副本上做,绝不向主工作树或线上环境注入已知缺陷。原始证据可能含凭据、个人数据、内部 URL 或客户内容时保持私有,仅提交经脱敏的记录。scripts/fingerprint.py 是 Python 标准库辅助脚本,只读取一个本地 JSON 记录并打印摘要,不执行命令、不访问网络、不脱敏、不修改记录。