- write-notes-like-deepseek 从三个子仓库的重复副本改为 meta 唯一副本 - 新增 .agents/scripts/verify-notes.ts,从 meta 视角一次校验四个笔记根 - workspace-layout 补「共有技能单一来源」的落位与理由 - .rgignore 排除 archived 历史快照
45 lines
4.3 KiB
Markdown
45 lines
4.3 KiB
Markdown
# 按需阅读:校验脚本
|
||
|
||
> 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 # 只查有改动的
|
||
```
|