| name | context-reset-protocol |
| type | workflow-step |
| description | 清窗/重启协议:定义何时清窗、清窗前落盘 PROGRESS、恢复后第一动作,防止 AI 代理在长会话中重复失败路径 |
| version | 1.0.0 |
| author | specforge |
清窗 / 重启协议(Context Reset Protocol)
本 skill 定义 AI 代理在长会话中遭遇上下文压力时的标准操作流程。核心目标:防止清窗后重复尝试已排除方案。
Iron Law
清窗前必须落盘 PROGRESS;恢复后第一动作必须读 PROGRESS 的「已排除方案」段。
若新尝试与已排除方案近似,AI 代理必须书面回答「本次尝试与第 N 次失败的差异是 X」;
若无法回答差异,必须停下反问用户。违反本协议触发 E010_repeatedFailurePattern。
§ 1 触发信号
当以下任一信号出现时,AI 代理应启动清窗协议:
| # | 信号类型 | 判定条件 | 紧急度 |
|---|
| 1 | Token 估算超限 | 当前会话 token 估算 > 50k | 高 |
| 2 | 连续失败 | 同一任务连续失败 ≥ 2 次(同类错误消息/同一堆栈顶) | 高 |
| 3 | 复读迹象 | AI 输出与前次高度相似(方案/代码/措辞重复率 > 70%) | 中 |
| 4 | 用户感觉打转 | 用户明确表达"打转"/"没进展"/"换个思路" | 中 |
详细信号说明与判定规则见 references/trigger-signals.md。
§ 2 清窗前必做:落盘 PROGRESS
当触发信号命中时,AI 代理在清窗/重启前必须完成以下动作:
2.1 创建 PROGRESS 文件
路径契约:
specforge/changes/<change-id>/progress/<task-id>-PROGRESS.md
- 同一任务允许多份 PROGRESS(按时间戳递增),最新一份为权威
- 随 change 归档到
specforge/archive/ 时整体带走
2.2 填写五段必填内容
| 段落 | 说明 |
|---|
| 目标 | 一句话描述本任务当前要达成的目标 |
| 已排除方案 | 列出所有已尝试但失败的方案(含时间 + 失败原因摘要) |
| 当前假设 | 本次恢复后拟采用的根因假设(必须与已排除方案有明确差异) |
| 下一动作 | 具体到单步,含预期验证方式 |
| 反重复契约 | P9 落地执行声明 |
完整模板字段说明与填写指南见 references/progress-template.md。
2.3 落盘时机
- 触发信号命中后、清窗动作执行前
- 若 AI 代理判断当前会话即将结束(用户离开 / 超时),也应主动落盘
- 落盘失败(如文件系统异常)时,AI 代理应在会话最后一条消息中以纯文本输出 PROGRESS 内容
§ 3 恢复后第一动作
会话从清窗中恢复后,AI 代理的第一动作(在任何其他操作之前):
- 定位最新 PROGRESS:读取
specforge/changes/<change-id>/progress/ 目录下当前任务的最新 PROGRESS 文件
- 阅读「已排除方案」段:逐条确认已排除的方案
- 输出恢复声明:在第一条回复中明确声明:
- 已读取哪份 PROGRESS 文件
- 已排除方案有哪些
- 本次拟采用的方案与已排除方案的差异
3.1 恢复声明模板
[恢复声明]
- 已读取:specforge/changes/<change-id>/progress/<task-id>-PROGRESS.md
- 已排除方案:方案 A(原因)、方案 B(原因)
- 本次方案:<描述>
- 与已排除方案的差异:<具体差异点>
§ 4 反重复契约(P9 落地执行)
本节是 Constitution P9「反重复与验证前置」原则在清窗场景的具体执行规则。
4.1 差异声明义务
当 AI 代理恢复后的新尝试与 PROGRESS「已排除方案」中任一方案近似时:
- 必须书面回答:「本次尝试与第 N 次失败的差异是 X」
- 差异声明必须具体到技术层面(不接受"换个角度"等模糊措辞)
- 差异声明应包含:改变了什么 / 为什么这次会不同 / 如何验证
4.2 无法回答差异时
若 AI 代理无法给出具体差异声明:
- 必须停下反问用户
- 反问内容应包含:当前困境描述 / 已排除方案列表 / 请求用户提供新方向或约束
4.3 近似判定
以下情况视为「与已排除方案近似」:
- 使用相同的库/工具/API 且调用方式相同
- 修改相同文件的相同区域
- 基于相同的根因假设
- 错误消息/堆栈与已排除方案的失败记录匹配
§ 5 与 P9 / E010 的关系
Constitution P9(反重复与验证前置):对同一根因的重试必须书面声明差异;
无法声明差异则停下反问用户。验证前置 Iron Law 适用所有阶段。
详见:.specforge/constitution.md P9 章节。
5.1 P9 宪法原则
本 skill 是 Constitution P9「反重复与验证前置(antiRepetitionAndEvidence)」的操作手册:
- P9 定义了原则(对同根因重试必须声明差异)
- 本 skill 定义了执行流程(何时触发 / 如何落盘 / 如何恢复 / 如何声明)
5.2 E010 触发条件
当以下条件同时满足时,触发 E010_repeatedFailurePattern:
- 同一任务上对同根因连续失败 ≥ 2 次
- 下一次尝试方案与 PROGRESS「已排除方案」近似
- AI 代理未书面声明与已排除方案的差异
5.3 E010 触发后动作
§ 6 引用 L3 资源
本 skill 的 L3 参考资源(首轮加载总行数 ≤ 150):
按需加载时机:
progress-template.md:当 AI 代理需要创建 PROGRESS 文件时加载
trigger-signals.md:当 AI 代理需要判定是否触发清窗时加载