- write-notes-like-deepseek 从三个子仓库的重复副本改为 meta 唯一副本 - 新增 .agents/scripts/verify-notes.ts,从 meta 视角一次校验四个笔记根 - workspace-layout 补「共有技能单一来源」的落位与理由 - .rgignore 排除 archived 历史快照
7.1 KiB
按需阅读:归档、生命周期治理与冻结机制
提炼自 DeepSeek Harness 的 notes 治理实践。收尾、复盘或大版本跃迁时对照;日常改动零负担,仅顺手就近替代。
目录:§0 执行频次(日常顺手 vs 大扫除)|§1 过时判定与保留红线(1.1 免检保留 / 1.2 归档标准 / 1.3 垃圾清理 / 1.4 校准示例)|§2 归档的标准操作流(CLI)|§3 永久冻结契约
0. 执行频次:日常顺手 vs 里程碑大扫除
无需每次修改代码都全量扫描,根据场景分级执行:
- 日常提交(90% 场景:零全量心智负担):
- 就地修改(80%):改了某模块,顺手更新持有该决定的现成 Note 事实。
- 当场审计(10%):新增 Note 时,按模块名/关键词搜活跃笔记,当场分类(无关 / 部分重叠互链 / 完全吸收后删或归档 / 过时提案 reject 或删)。禁止把已知匹配推迟到大扫除。
- 里程碑大扫除(10% 场景:按需治理):
- 仅处理当时搜不到的漏网:季度复盘、大版本发布、或活跃 Note 累积过多影响检索时,集中扫一次。
1. 过时判定与保留红线
判断是否过时不看字数多少,也不看存续时间长短,严格依据「未来防撞护栏价值」:
1.1 活跃区免检保留红线(即使年代久远也必须保留在 implemented/)
只要符合以下任一特征,绝对不过时,严禁归档:
- 所有权边界:明确界定了模块调用权限与架构职责划分(如"UI 层严禁直接直连 DB")。
- 否定性保证(Negative Guarantees):明确承诺"绝不提供某项能力"或"永不向后兼容某旧协议"。
- 安全与合规底线:防止注入、鉴权绕过或数据泄露的刚性约束。
- 易复踩的被否决方案(Alternatives considered):记录了极具诱惑力但在实践中已被证明会导致死锁/崩溃的错误路线。
1.2 归档标准(移入 archived/)
仅对 implemented/ 中满足以下条件的记录执行归档:
- 被新架构完全取代但仍有独立杠杆:后续 Note 已吸收核心逻辑,旧篇还留着否定性保证 / 所有权边界 / 重新引入条件——归档,互链写在新笔记。能删则删,见
references/when-to-write.md§4。 - 一次性设计与窄细节:一次性 UI 边距调整、已废弃平台的狭窄单点适配器、已彻底闭环的简单 bug 修补。
1.3 垃圾清理规则(不进归档树)
proposed/绝不归档:前提消失(如依赖升级自带该能力)或不再推进的提案,直接转为Status: rejected — <一句话原因>;已在其他方案中吸收的直接关闭。- 无价值
rejected/物理删除:若被否决方案所依赖的旧技术/API 已被彻底移除,未来 Agent 绝无可能再提出该错误路线,直接将文件物理删除,不留冗余。
1.4 校准示例(立标用;词数证明篇幅不是标准)
移植自 DeepSeek Harness 的归档 skill。判断时对标示例的理由结构,别对标词数。
该归档的 implemented(决定已完成、理由 unlikely 再指导未来工作):
- 折叠侧边栏控制栏(~530 词)——已闭环的次要 UI 行为;
- 某 CLI 参数适配器(~1,500 词)——实现细节很重,但对未来设计几乎没有杠杆;
- 文档生成管线(~920 词)——机器已完成使命,现行生成器本身就是权威。
该保留的 implemented(理由仍 owning 或 constraining 什么):
- 事件溯源会话存储(~250 词)——基础性权威与持久化边界;
- 跨产品所有权解析规则(~600 词)——一条所有权边界立法;
- 项目会话目录策略(~630 词)—— durable 存储与身份策略;
- 并行 pre-push 门禁(~400 词)——边界案例,但仍指导门禁排程;
- 已下线的图片内容块(~330 词)——保留,直到多模态落地:它写着协调好的重引入条件。
rejected 的存与删:
- 保留「合并压缩包拆分」(~430 词)——合并的诱惑仍在,防重犯价值还在;
- 删除「经工具调用推送流式进度」(~970 词)——其 ACP/UI 前提已过时;
- 删除「去掉 ACP 终端元数据」(~360 词)——后来的自动化决策已经回答了这个问题。
2. 归档的标准操作流
推荐直接用 CLI(物理移动 + 封印 + 入站死链报告一次完成,不依赖 git):
node .agents/skills/write-notes-like-deepseek/scripts/archive-agent-note.ts \
.agents/notes/implemented/<class>/<filename>.md \
[--superseded-by .agents/notes/implemented/<class>/<新笔记>.md]
CLI 依次完成:
- 写头部标记:
Archived: YYYY-MM-DD紧邻Status: implemented插入(L3/L4 之间不留空行——这是与 DSH 原版对齐的硬契约,封印校验器逐行核对):# Agent Note: xxx Status: implemented Archived: 2026-08-31 ## Problem ... - 物理移动:
implemented/<class>/...→archived/<class>/...(git 场景建议用git mv保留历史,CLI 用文件移动实现,无 git 同样工作)。 - 封印入
archived/manifest.json:记录该文件的 SHA-256。封印后任何对归档内容的篡改都会被verify-archived报警。 - 入站死链报告:扫描活跃笔记里指向该笔记的 Markdown 相对链接(精确链接解析,非文本子串),列出需人工修复的清单。
- 可选
--superseded-by:校验新笔记存在,并在新笔记末尾补一条指向归档路径的相对链接。不改归档篇。
除头部 Archived: 一行外,禁止修改归档正文的任何其他字符。
历史包袱补齐:若
archived/已有笔记但还没有 manifest(例如从 DSH 导入的语料),运行node .agents/skills/write-notes-like-deepseek/scripts/verify-archived-agent-notes.ts --write一次性补封印——它会先校验既有封印未被改动,再追加缺失条目,绝不重写历史。
3. 永久冻结契约(Frozen Immutable Contract)
一旦进入 archived/:
- 永久只读:严禁编辑、翻译、重排版、更新、移动或删除。
- 机械强制:
verify-archived校验头部布局、manifest 哈希、以及封印的 append-only(有 git 时与基线 ref 对比,AGENT_NOTE_ARCHIVE_BASE_REF可指定基线,默认 HEAD;无 git 自动降级为哈希自校验并提示)。封印只增不改,已封印条目被改动或删除即报错。 - 免除日常扫描:
verify-agent-note-tree和verify-agent-note-format默认跳过archived/目录,归档文件的出站链接失效不会阻塞日常构建。 - 不可作为当前行为依据:代码冲突或架构评审时,以
implemented/为准,archived/仅作为历史考据参考;取代关系以新笔记互链和入站改写为准。
上述命令从宿主项目根目录执行;若 Skill 安装在其他位置,请替换 .agents/skills/write-notes-like-deepseek 为实际路径。