docs: 共有技能收归 meta 单一份并加工作区级笔记校验入口
- write-notes-like-deepseek 从三个子仓库的重复副本改为 meta 唯一副本 - 新增 .agents/scripts/verify-notes.ts,从 meta 视角一次校验四个笔记根 - workspace-layout 补「共有技能单一来源」的落位与理由 - .rgignore 排除 archived 历史快照
This commit is contained in:
@@ -0,0 +1,109 @@
|
||||
# 按需阅读:归档、生命周期治理与冻结机制
|
||||
|
||||
> 提炼自 [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` 为实际路径。
|
||||
@@ -0,0 +1,33 @@
|
||||
# 按需阅读:Class 分类
|
||||
|
||||
> SKILL §1 的展开。新建 Note 选 class 时对照。
|
||||
|
||||
## 封闭集(6 个,再加要改检查脚本)
|
||||
|
||||
| Class | 覆盖范围 |
|
||||
|---|---|
|
||||
| `feature` | 新增面向用户或模型的能力 |
|
||||
| `bug-fix` | 修缺陷或补 postmortem 暴露的缺口 |
|
||||
| `simplification` | 不新增能力的前提下删代码/行为/表面 |
|
||||
| `architecture` | 已发布源码的结构性决定——包如何关联、运行时词汇是什么 |
|
||||
| `process` | 代码之外的工具/策略/流程——门禁、包管理、vendoring 等 |
|
||||
| `testing` | 测试 infra 与策略 |
|
||||
|
||||
判定技巧:
|
||||
|
||||
- `architecture` vs `process`:前者是"发出去的源码长什么样",后者是"围绕源码的工具链与工作流"。
|
||||
- `refactor` 不单列——用 `simplification` 的判据"可观察行为变了吗"区分;行为不变即 simplification,行为变了归对应 feature/bug-fix/architecture。
|
||||
- `feature` 不只在"新增能力"时用——**用户/模型可见、不显然的行为或产品选择,changes 够不上架构,也归 `feature`**。判据是"行为是否可被用户或下游观察",而不是"改动了多少代码"。只有局部实现细节、普通重构、行为不变的依赖补丁才不写任何 Note。
|
||||
- 拿不准时看这条 Note 以后会被谁检索:找能力演进看 `feature`,找结构决策看 `architecture`,找门禁/发布看 `process`。
|
||||
|
||||
每条 Note 必带的语义要求(检查脚本管不了的):
|
||||
|
||||
- **Alternatives 只记录真实考虑过的对手方案**:先写它最强的论据再否——只写弱处的拒绝是稻草人。「不做/复用」仅当当时真的权衡过才写,不要编。
|
||||
- **简化必写代价上限**:`simplification` 的 `## Consequences` 要写明"这个取舍的已知上限是什么、什么信号发生时该重访"。没有升级触发条件的简化会悄悄变永久。
|
||||
- **验证要可确认**:写"改对了"时落到可被检查的表面(记"哪条路径、什么量级、跑什么命令确认"),没有基线就不要用相对量词——"提升了/更快了"在没有对比基线时是未验证断言,比不写更糟。
|
||||
|
||||
## 检查脚本
|
||||
|
||||
`scripts/agent-note-tree.ts` 定义 `AGENT_NOTE_CLASSES` 常量;未知 class 文件夹、lifecycle 根下的散落 `.md` 都会报错。新增 class 必须同时改常量和本文档,否则检查直接红。
|
||||
|
||||
分类封闭集与判据对齐 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的 notes 分类实践。
|
||||
@@ -0,0 +1,69 @@
|
||||
# 按需阅读:Note 文件格式
|
||||
|
||||
> SKILL §2 的展开。写/改 Note 时对照;只改代码不动 Note 时跳过。
|
||||
|
||||
## 头块(前三行,检查脚本会核对)
|
||||
|
||||
```markdown
|
||||
# Agent Note: <标题>
|
||||
|
||||
Status: <状态>
|
||||
```
|
||||
|
||||
- `proposed` → `Status: proposed`
|
||||
- `implemented` → `Status: implemented`
|
||||
- `rejected` → `Status: rejected — <一句话原因>`
|
||||
|
||||
标题前必须带 `Agent Note: ` 前缀,标题本身用简体中文;状态不含日期与括号;必须与所在 lifecycle 文件夹一致(脚本会交叉核对)。文件名日期是首次提出日,git 承载其余时间信息。
|
||||
|
||||
## Body 骨架
|
||||
|
||||
每篇 Note 都以 `## Problem` 开头——动机要能脱离方案独立成立。之后按 lifecycle区分:
|
||||
|
||||
**`proposed/`**
|
||||
|
||||
```markdown
|
||||
## Problem
|
||||
## Proposal
|
||||
…自由节…
|
||||
## Alternatives considered
|
||||
## Acceptance criteria
|
||||
## Risks
|
||||
```
|
||||
|
||||
`Proposal` 可用将来时;`Acceptance criteria` 说清什么可观察状态算完成;`Risks` 同时写风险与已知取舍。
|
||||
|
||||
**`implemented/`**
|
||||
|
||||
```markdown
|
||||
## Problem
|
||||
## Decision
|
||||
…自由节…
|
||||
## Alternatives considered
|
||||
## Consequences
|
||||
```
|
||||
|
||||
`Decision` 用现在时描述已落地事实;门禁只拒提案标题(`## Proposal` / `## Plan` / `## Migration plan` / `## Acceptance criteria` 及其中文别名);用 `## Consequences` 同时记录代价与收益;可按需加 `## Testing` / `## Verification` 等现在时事实节。现在时靠人写,不靠词法扫描。
|
||||
|
||||
**`rejected/`**
|
||||
|
||||
冻结的 proposal 形态,verdict 在 `Status:` 行;保留提案时的 `Alternatives` 等节,不改写为对立面。
|
||||
|
||||
## Alternatives considered(必写)
|
||||
|
||||
每篇 Note 必含 `## Alternatives considered`:每个**真考虑过**的备选为何没选,一段一备选(可用 `### Why not <X>?` 子节)。没有过的选项不要编。「不做 / 复用现状」仅当当时真的权衡过才写。脚本只检查这一节在不在。
|
||||
|
||||
## 时态与禁止改写
|
||||
|
||||
- `proposed` 可用将来时;`implemented` 一律现在时,描述已落地事实。
|
||||
- 一条 Note 永远不被改写成另一个决定;被取代用新 Note 接管,旧 Note 按归档/合并规则处理。
|
||||
|
||||
头块标题兼容全角冒号(`# Agent Note:标题`,中文输入法常打出全角);新笔记建议半角。
|
||||
|
||||
## 自由节与文风
|
||||
|
||||
- 自由节(package 拓扑、wire 契约、schema 等)放在 `Decision` 与 `Alternatives` 之间。
|
||||
- 保留可检索的机制名与 `must`/`may`/`never` 时序强调;一个事实只在一处讲透,其余链过去。
|
||||
- 跨 Note 引用用相对 Markdown 链接 `[topic](../../implemented/architecture/2026-…-….md)`,不要裸数字。
|
||||
|
||||
格式与别名表对齐 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的 notes 规范;本项目为中文单语:标题、节标题与正文用简体中文,头块 `Agent Note:` 与 `Status:` 保持英文原文以便脚本核对。
|
||||
@@ -0,0 +1,51 @@
|
||||
# 按需阅读:Notes 行文与去泄露自检
|
||||
|
||||
> 提炼自 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 仓库内 `dsh-prose-standard` 与 `dsh-trim-cot-leakage` 两个 skill 的可搬运部分。写/改 Note 时对照此清单;只改代码不动 Note 时跳过。
|
||||
|
||||
## 原则
|
||||
|
||||
- 只写代码说不清的:行为、失败、时序、所有权、后果与取舍。别复述代码或推导过程。
|
||||
- 不变量能编进类型、可见性或 API 报错的,别只写在笔记里。
|
||||
- 说人话,点名谁做了什么、在什么条件下、会怎样;少用“契约/边界/形态”等抽象词,除非指的就是该技术主体。
|
||||
- 一个事实只在一处讲透,其余链过去;别把同一规则抄得到处都是。
|
||||
- 写完自问:这段话不看实现能独立成立吗?不看当时聊天,现在的读者能验证吗?
|
||||
|
||||
## 写前自检(来自 prose-standard)
|
||||
|
||||
- 每段保留完整命题:主体/动作、条件/时序、must/may/never、否定保证与例外、所有权/副作用/失败与后果——缺一不可。
|
||||
- `implemented` 用现在时,描述已落地事实;去掉计划口吻与 checklist。
|
||||
- 保留可检索的机制名与关键 must/may/never、时序与否定强调;装饰性加粗和感叹少用。
|
||||
- 一个改动内批量套用刚学到的规则到相似段落,别只改一处。
|
||||
|
||||
## 按位置查
|
||||
|
||||
- **Decision/Consequences**:区分、抛错/拒绝、副作用、所有权、时序、取消、持久化是否说清。
|
||||
- **自由节**(拓扑/契约/schema):讲清职责、依赖与非显而易见的选择及指向。
|
||||
- **Alternatives/Consequences**:同时写代价与收益,点名放弃的能力与重引入条件。
|
||||
- **Testing/Verification**:只解释“为何这样验证”(fixture/断言/真实入口的必要性),不写走读。
|
||||
|
||||
## 去泄露自检(来自 trim-cot-leakage)
|
||||
|
||||
对每段可疑文字问:**只有当时的会话/PR/草稿可见吗?HEAD 的读者能独立验证吗?** 不能则重述为仓库视角,删去会话痕迹。能解析也≠安全——可验证只代表过了去泄露这一关,README/文档等当前状态面上,可解析的变更叙事仍是变更叙事,按第 3 类路由。
|
||||
|
||||
常见泄露(命中即改):
|
||||
|
||||
1. 死引用:`(decision 7)`/`(audit C2)`/`§N`/`plan §1.4` — 改为对已提交 Note/文档的具名路径引用,无主则删引用、重述事实。
|
||||
2. 栈/PR 视角:`后续 PR`/`本 PR 新增`/`上一 commit` — 改为已落地的机制或扩展点;未做事项用 `TODO` 或 issue 引用,或收进 `## Deferred` 小节。
|
||||
3. 变更叙事:`used to`/`不再`/`旧 X`/`this cut`/`now` — 改为现在时;回归用现在时反事实“若无 X 则 Y”。
|
||||
4. 评审编排:`评审时否掉`/`reviewer 确认`/`v5` — 只留决定与理由,删谁说的、何时说的。
|
||||
5. 自证正确:`这样转是安全的,因为…` — 改为使之安全的 invariant,或直接删(代码已自明)。
|
||||
6. 过程复述:`先 X 再 Y`/`测试走读` — 删,只留非显然契约。
|
||||
7. 含糊与占位:`应该够了`/`probably fine` — 升为 `TODO/FIXME` 或明确边界。
|
||||
8. 语言串台:中英混杂的工作语言片段 — 翻译或删除。
|
||||
|
||||
**不算泄露(保留):** issue 引用 `#1470`/`TODO(name):`(裸 `TODO` 注意正文扫描,见上条豁免)、Agent Note 与 postmortem 内的已合并 PR 引用、suppression 理由、现在时反事实、带实测值的边界、运行时 old/new 状态、已提交文档的 `§` 编号。
|
||||
|
||||
## 删过头警示(overcorrection traps,来自 trim-cot-leakage)
|
||||
|
||||
删之前先把段落里的命题列全,再对照四个"删过头"的坑:
|
||||
|
||||
- 把必须/禁止的义务删成"可以这样"的背书——约束变可选。
|
||||
- 把"计划中/考虑过"的假设删成已落地事实——proposed 当 implemented。
|
||||
- 删掉一句真事实,只因为它读起来像过程叙述。
|
||||
- 丢掉承重溯源:`实测:512 嵌套 ≈ 0.15s` 里的 `实测`、来源标注与编号删掉,结论就没根了。
|
||||
@@ -0,0 +1,58 @@
|
||||
# 按需阅读:语义自检(写完笔记后过一遍)
|
||||
|
||||
> 脚本管结构,这张清单管意思。写完后自检,只向用户报缺口和写得好的地方,不逐条背诵。
|
||||
> 定位:这是给 Agent 的自检,不是给脚本的规则——下列检查点全部是语义判断,永不进 verify 脚本。
|
||||
|
||||
## 动手前:先自己查,再问用户
|
||||
|
||||
- [ ] 这个"问题"真的是决策吗?——能用 §3 检索四法(入口注释若有 / 分类树 / rg / 模块文档)自己查到的事实,不要抛给用户。Finding facts is your job; 只有取舍和拍板才占用用户时间。
|
||||
|
||||
## Problem
|
||||
|
||||
- [ ] 动机脱离方案也能独立成立——删掉 Decision 再读一遍,还是同一个问题吗?
|
||||
- [ ] 触发清楚:什么破了、什么要变、不做会怎样。
|
||||
|
||||
## Decision / Proposal
|
||||
|
||||
- [ ] 具体到能行动,不是"用更好的数据库"而是"为会话存储用 SQLite"。
|
||||
- [ ] 理由是被"vs"逼出来的——写"决定用 X"就补一句"X vs Y 为何选 X"。
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
- [ ] ≥2 个真备选;不要编没权衡过的选项。「不做/复用」仅当当时真的考虑过才算一档,不是必填档。
|
||||
- [ ] 每个被否项先写它最强的论据,再写为何否——只写弱处的拒绝是稻草人。
|
||||
- [ ] 否掉的理由落到具体驱动条件,不是"经验上不行"。
|
||||
|
||||
## Consequences
|
||||
|
||||
- [ ] 代价和收益都写。自问"什么变难了?维护成本是什么?"——只有收益的后果是挑选过的。
|
||||
- [ ] 简化注明已知上限与何时该重访。没有升级触发条件的简化会悄悄变永久。
|
||||
- [ ] 没有基线就不写相对量词——"提升了/更快了"说不清基线时,降级为事实陈述。
|
||||
|
||||
## Verification / Testing(implemented)
|
||||
|
||||
- [ ] 落到可确认表面:哪条路径、什么量级、跑什么命令。
|
||||
- [ ] 不写"看起来能用"——验收标准要么可勾选,要么明确留给后续。
|
||||
|
||||
## 汇报形态
|
||||
|
||||
写完自检后,这样汇报(一行一缺口,没缺口就收口):
|
||||
|
||||
```markdown
|
||||
**语义自检:<filename>**
|
||||
✅ 稳定:动机独立成立 / 有 2 个真备选 / 后果代价收益兼备
|
||||
⚠️ 缺口:
|
||||
- Alternatives — 有"做了 vs 不做"稻草人,补一个与现行方案平行的真实选项
|
||||
- Consequences — "性能提升"要落到哪条路径、什么量级
|
||||
建议:修以上 2 处后落盘 / 可接受缺口,直接放行
|
||||
```
|
||||
|
||||
用户接受缺口即放行;不接受就修再落盘。意思上的判断不是脚本,别把它撑成另一道检查。
|
||||
|
||||
## 这套自检生效了吗(观测判据)
|
||||
|
||||
每隔一段时间回看,以下信号说明自检在起作用;信号消失说明它在空转:
|
||||
|
||||
- 你向用户提的问题里,**不再出现**翻一下笔记树或 rg 一下就能答的事实性问题。
|
||||
- 汇报里的每条缺口都带着**具体修法**(改哪节、补什么),而不是"建议再完善"。
|
||||
- `rejected/` 和 Alternatives 里被否掉的路线,**不再被新会话重新提出**——这正是整套系统存在的理由。
|
||||
@@ -0,0 +1,26 @@
|
||||
# 按需阅读:简化机会自检
|
||||
|
||||
> 提炼自 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的 `dsh-find-simplifications` skill。收尾或重构时扫一遍;别在功能改动里硬塞无关简化。
|
||||
|
||||
## 值得删/合/降级的信号
|
||||
|
||||
- 公开方法、事件、配置项、包、持久化事件或测试产物没有生产消费方(测试/文档是唯一消费方且行为非关键)。
|
||||
- 两处表示同一事实(尤其是持久化事件与瞬态事件各存一份)。
|
||||
- 某个能力的所有实现都必须实现某方法,但没有消费方在用它。
|
||||
- 包只为测试/demo/支撑而存在,增加发布与依赖成本。
|
||||
- 为“以后可能要”做的通用性:多会话、后台任务台账、年中转向、工具自带 UI 等,无当前归属。
|
||||
- 为不存在的 API 准备的不变式、回滚、快照或特判。
|
||||
- 手写了业界已有包或同版本 Node 已提供的能力,换掉能净删除实现与对应测试。
|
||||
|
||||
## 怎么证实
|
||||
|
||||
- 用 `rg` 搜符号/事件/配置键/包名,看生产代码(`packages/*/src`、`examples` 运行时、`loader/config` 路径)是否真在用。
|
||||
- 区分生产/非生产/模糊语料——测试与文档里的出现不算生产证据;`knip` 可辅助但不能替代读调用点。
|
||||
- 小而确定的清理用 `TODO/FIXME/XXX` 记下,别为此开一条 Note;只有 durable 的取舍才值得一条 proposed Note。
|
||||
- Hand-rolled vs 依赖:看净删除(实现+测试+文档)、健康度、边界贴合度;能真删才换,包一层同样复杂度不算赢。
|
||||
|
||||
## 与 Notes 的衔接
|
||||
|
||||
- 符合信号且这个取舍需要留下来 → 写 `proposed/simplification` Note(Problem/Proposal/Alternatives/Acceptance/Risks)。
|
||||
- 已落地的 simplification → `implemented/simplification`,Consequences 同时写删掉的成本与省下的负担。
|
||||
- 触发 Note 树膨胀时,用 `archiving.md` 的“未来参考价值”判定是否归档,而非字数/年龄。
|
||||
@@ -0,0 +1,44 @@
|
||||
# 按需阅读:校验脚本
|
||||
|
||||
> SKILL §6 的展开。接入 CI 时对照;本地轻量使用时跳过。
|
||||
|
||||
## 检查脚本(均为 tsx,零新增依赖,可直接用 `node` 独立运行;Node 22.6+ 原生支持,无需 tsx 依赖)
|
||||
|
||||
1. **`verify-agent-note-tree`**(`scripts/agent-note-tree.ts` + `scripts/verify-agent-note-tree.ts`)
|
||||
- 校验 lifecycle 封闭集 `proposed/implemented/rejected` + `archived`、class 封闭集 6 个、路径深度 `{lifecycle}/{class}/file.md`、文件名 `yyyy-mm-dd-topic.md`、禁止 `INDEX.md`、活跃笔记内部相对 Markdown 链接有效性。
|
||||
|
||||
2. **`verify-agent-note-format`**(`scripts/verify-agent-note-format.ts`)
|
||||
- 头部:第 1 行 `# Agent Note:` 标题(半角/全角冒号都收,中文输入法常打出全角)、第 2/4 行空行、第 3 行 `Status:` 与 lifecycle 一致且全篇唯一。
|
||||
- 骨架:首节必须 `## Problem`/`## 问题`;per-lifecycle 必需节匹配中英别名(`## Decision`/`## 决策`、`## Consequences`/`## 后果` 等;`## Decision(说明)` 这类括号后缀会先剥掉再匹配);`implemented` 禁用提案式标题(`## Proposal`/`## Plan`/`## Migration plan`/`## Acceptance criteria` 及其中文别名)。现在时是散文纪律,不扫正文。
|
||||
- 备选方案:`## Alternatives considered` / `## 备选方案` / `## 已考虑的替代方案` 等别名必写。脚本不检查「不做/复用」档,也不接受占位注释豁免。
|
||||
- 兼容:CRLF/BOM 自动归一。
|
||||
|
||||
3. **`verify-archived`**(`scripts/verify-archived-agent-notes.ts`,标配)
|
||||
- 每篇归档:头部布局逐行校验(L3 `Status: implemented` / L4 `Archived: YYYY-MM-DD` 紧邻 / L5 空行)。不承认 `Superseded-by:` 字段。
|
||||
- `archived/manifest.json`:每个文件有封印条目、每条目有对应文件、sha256 与磁盘内容一致(冻结 = 不可篡改的机械含义)。
|
||||
- append-only:有 git 时与基线 ref 的 manifest 逐条对比(env `AGENT_NOTE_ARCHIVE_BASE_REF`,本地默认 HEAD)。CI 必须指向变更前的 commit(本仓库 workflow:PR 用 `pull_request.base.sha`,push 用 `github.event.before`),用 HEAD 等于没查。已封印条目被改/删即报错;**无 git 自动降级**为哈希自校验并打印提示——不用 git 一样能跑,只是少了版本基线对照。
|
||||
- `--write`:先证明既有封印未变,再为未封印文件追加封印(历史语料补齐用这个)。
|
||||
|
||||
4. **`check-note-anchors`**(`scripts/check-note-anchors.ts`,软报告,退出码恒 0,**不进 CI**)
|
||||
- 扫描源码(env `AGENT_NOTE_CODE_ROOT` 指定根,默认 cwd;自动跳过 node_modules/.git/dist 等)里的 `// Note:` / `# Note:` 物理锚点:报告悬空锚点、没有锚点指向的 implemented 笔记、缺路径的锚点行。宿主没用锚点就不必跑。
|
||||
|
||||
## 接入建议
|
||||
|
||||
- 轻量(个人/无 git):前两个脚本即可,归档封印在第一次归档后自然生效。
|
||||
- 完整(团队):三条门禁串进 CI,失败即红(本 Skill 的 `templates/verify-notes.yml` 可作模板;Gitea 下改到 `.gitea/workflows/` 并把 `github.*` 变量换成 `gitea.*`)。
|
||||
|
||||
三个校验脚本方法上来自 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness),按通用中文单语宿主裁过:无双语三件套、无 DSH 迁仓豁免。锚点体检是可选软报告,不是 DSH 门禁。
|
||||
|
||||
## 脚本路径与笔记根
|
||||
|
||||
脚本本身不看它自己被放在哪,只看**笔记根**:环境变量 `AGENT_NOTE_ROOT`,未设置时回落到 `cwd/.agents/notes`。
|
||||
|
||||
单仓库安装(技能就在同一个仓里):保持当前目录为仓库根,直接 `node .agents/skills/write-notes-like-deepseek/scripts/verify-*.ts`。安装本身不会创建 npm scripts。
|
||||
|
||||
多仓库工作区(本工作区):技能在 meta 的 `.agents/skills/`,笔记却分散在各子仓库,所以**必须显式给 `AGENT_NOTE_ROOT`**,否则在 meta 根目录跑只会校验 meta 自己的跨仓库笔记,子仓库一篇都不会被检查(而且空目录会报 0 篇「通过」,制造假绿)。日常请直接用:
|
||||
|
||||
```sh
|
||||
node .agents/scripts/verify-notes.ts # 自动遍历所有含 .agents/notes 的仓库
|
||||
node .agents/scripts/verify-notes.ts lpt-be # 只查一个
|
||||
node .agents/scripts/verify-notes.ts --changed # 只查有改动的
|
||||
```
|
||||
@@ -0,0 +1,83 @@
|
||||
# 按需阅读:何时写、何时改与决策流转
|
||||
|
||||
> SKILL §4 的深度展开。每个重要改动或评审时对照一次。
|
||||
|
||||
## 核心心智:更新既有归属,严禁重复新建(Update the owning note)
|
||||
|
||||
DeepSeek 的公开演进历史(deepseek-ai/deepseek-harness 的 git 记录)里能看到同样的形态:Note 的新增很少,现有 Note 的**就地事实修正**占了绝大多数。
|
||||
**不要把 Note 当做一次性发表的博客或流水账。它是与代码共存亡的「现行法律」。**
|
||||
|
||||
一篇 Note 永远不被改写成另一个决定:事实(路径、符号、默认值)就地改;决定或理由翻转 → 新开一篇并互链。禁止把 `## Decision` 改写成反面,禁止只靠 git 当旧理由的唯一副本。
|
||||
|
||||
---
|
||||
|
||||
## 1. 场景判定矩阵
|
||||
|
||||
| 场景 | 操作动作 | 典型范式 |
|
||||
|---|---|---|
|
||||
| **代码重构、改名、移包、改默认参数** | **原地更新现有 Note 事实** | Decision 核心理由不变;直接改路径、类名、默认值(不追加变更流水账)。理由变了就走新建,不走原地 |
|
||||
| **写新 Note 之前** | **当场审计活跃笔记** | 按模块名/关键词搜 proposed + implemented + rejected;每篇命中当场分类(无关 / 部分重叠 / 完全吸收 / 过时提案),和这篇新 Note 一起落盘。禁止推迟到大扫除 |
|
||||
| **提出全新的架构尝试或技术选型** | **新建 `proposed/`** | 动手编码前写清动机、真实考虑过的备选与验收指标 |
|
||||
| **完成开发并准备合入主干** | **转为 `implemented/`** | 见 §3 改写清单;与代码同批落盘(git 场景即同一 commit/PR) |
|
||||
| **方案被新决策部分取代** | **两篇都留、互链** | 只更新仍成立的事实。禁止归档 |
|
||||
| **方案在评审中被否决** | **移入 `rejected/` 或删除** | 仅当其理由能避免未来重蹈覆辙时保留并写清原因;否则彻底删除 |
|
||||
| **新架构完全取代了旧架构** | **先吸收,能删则删,否则归档** | 见 §4。指针写在新笔记里,不写进归档篇 |
|
||||
| **版本封版打标、依赖小补丁、排版** | **免除(Not Applicable)** | 直接提交代码,无需任何 Note |
|
||||
|
||||
---
|
||||
|
||||
## 2. 原地同步法则(In-place Fact Sync)
|
||||
|
||||
当现有 Note 所守护的模块发生演进,但核心决策并未被推翻时:
|
||||
|
||||
1. **直接修改,不记流水账**:
|
||||
- ❌ 错误:在文末追加 `### 2026-09-02 更新:类名重命名为 X`
|
||||
- ✅ 正确:直接在正文中将旧类名替换为新类名,保证任何时候打开这篇 Note,它反映的都是 HEAD 分支的绝对事实。
|
||||
2. **时态永保现在时**:
|
||||
- 始终使用现在时(`系统使用 SQLite 作为持久化引擎`),严禁使用变更叙事(`系统不再使用 JSONL,现在使用 SQLite`)。门禁只拒提案标题,现在时靠这条纪律,不靠词法扫描。
|
||||
|
||||
---
|
||||
|
||||
## 3. proposed → implemented 改写清单
|
||||
|
||||
同一次改动里做完:
|
||||
|
||||
1. 移到 `implemented/<class>/`,文件名日期不动(首次提出日)
|
||||
2. `Status: proposed` → `Status: implemented`
|
||||
3. `## Proposal` → `## Decision`,改成现在时(已落地的事实)
|
||||
4. `## Acceptance criteria` / `## Risks` 折进 `## Consequences`(或现在时 `## Testing` / `## Verification`)
|
||||
5. 删计划段(`## Plan` / 迁移步骤 / 开放问题)
|
||||
|
||||
门禁靠骨架变化卡住:implemented 里残留 `## Proposal` 会失败。
|
||||
|
||||
---
|
||||
|
||||
## 4. 取代:部分重叠 vs 完全吸收
|
||||
|
||||
**部分重叠**:新方案只覆盖旧方案一部分 → 两篇都留,双方加相对链接;只更新仍成立的事实。禁止归档、禁止推迟。
|
||||
|
||||
**完全吸收**(旧方案被彻底淘汰):
|
||||
|
||||
1. **审计旧 Note 资产**:独有的安全边界、否定性保证、失败场景、重新引入条件、验证缺口。
|
||||
2. **搬迁与吸收**:写入新 Note 的 `## Decision` / `## Alternatives considered` / `## Consequences`。
|
||||
3. **旧 Note 二选一**:
|
||||
- **删除**:新篇已写入旧篇全部独特内容,且入站链接已改完 → 物理删除,不进 `archived/`。
|
||||
- **归档**:旧篇还有独立杠杆(否定性保证、所有权边界、重新引入条件)→ `archive-agent-note.ts`。只插 `Archived:` 一行;互链写在新笔记。
|
||||
4. **修复入站链接**:把仍指向旧路径的相对链接改到新 Note(引历史快照时才指向 `archived/`)。
|
||||
|
||||
`--superseded-by` 只校验新笔记存在,并在新笔记末尾补一条指向归档路径的相对链接。
|
||||
|
||||
---
|
||||
|
||||
## 5. 可选:源码入口反向注释
|
||||
|
||||
宿主若已有此惯例,可在核心入口留一行:
|
||||
|
||||
```typescript
|
||||
// Note: 会话持久化采用文件句柄管理,避免并发写冲突 — 见 .agents/notes/implemented/architecture/2026-08-27-handle-based-session-persistence.md
|
||||
export class SessionFileHandlePool {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
不是门禁。`check-note-anchors` 只做软报告,不进 CI。
|
||||
Reference in New Issue
Block a user