- write-notes-like-deepseek 从三个子仓库的重复副本改为 meta 唯一副本 - 新增 .agents/scripts/verify-notes.ts,从 meta 视角一次校验四个笔记根 - workspace-layout 补「共有技能单一来源」的落位与理由 - .rgignore 排除 archived 历史快照
110 lines
7.1 KiB
Markdown
110 lines
7.1 KiB
Markdown
# 按需阅读:归档、生命周期治理与冻结机制
|
||
|
||
> 提炼自 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的 notes 治理实践。收尾、复盘或大版本跃迁时对照;日常改动零负担,仅顺手就近替代。
|
||
|
||
**目录**:§0 执行频次(日常顺手 vs 大扫除)|§1 过时判定与保留红线(1.1 免检保留 / 1.2 归档标准 / 1.3 垃圾清理 / 1.4 校准示例)|§2 归档的标准操作流(CLI)|§3 永久冻结契约
|
||
|
||
---
|
||
|
||
## 0. 执行频次:日常顺手 vs 里程碑大扫除
|
||
|
||
无需每次修改代码都全量扫描,根据场景分级执行:
|
||
|
||
1. **日常提交(90% 场景:零全量心智负担)**:
|
||
- **就地修改(80%)**:改了某模块,顺手更新持有该决定的现成 Note 事实。
|
||
- **当场审计(10%)**:新增 Note 时,按模块名/关键词搜活跃笔记,当场分类(无关 / 部分重叠互链 / 完全吸收后删或归档 / 过时提案 reject 或删)。禁止把已知匹配推迟到大扫除。
|
||
2. **里程碑大扫除(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**):
|
||
|
||
```bash
|
||
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 依次完成:
|
||
|
||
1. **写头部标记**:`Archived: YYYY-MM-DD` **紧邻** `Status: implemented` 插入(L3/L4 之间不留空行——这是与 DSH 原版对齐的硬契约,封印校验器逐行核对):
|
||
```markdown
|
||
# Agent Note: xxx
|
||
|
||
Status: implemented
|
||
Archived: 2026-08-31
|
||
|
||
## Problem
|
||
...
|
||
```
|
||
2. **物理移动**:`implemented/<class>/...` → `archived/<class>/...`(git 场景建议用 `git mv` 保留历史,CLI 用文件移动实现,无 git 同样工作)。
|
||
3. **封印入 `archived/manifest.json`**:记录该文件的 SHA-256。封印后任何对归档内容的篡改都会被 `verify-archived` 报警。
|
||
4. **入站死链报告**:扫描活跃笔记里指向该笔记的 Markdown 相对链接(精确链接解析,非文本子串),列出需人工修复的清单。
|
||
5. **可选 `--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` 为实际路径。
|