Files
lpt-meta/.agents/skills/write-notes-like-deepseek/references/verification.md
T
cat-shark f99e1e156d docs: 共有技能收归 meta 单一份并加工作区级笔记校验入口
- write-notes-like-deepseek 从三个子仓库的重复副本改为 meta 唯一副本
- 新增 .agents/scripts/verify-notes.ts,从 meta 视角一次校验四个笔记根
- workspace-layout 补「共有技能单一来源」的落位与理由
- .rgignore 排除 archived 历史快照
2026-11-18 14:59:45 +08:00

45 lines
4.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 按需阅读:校验脚本
> 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 # 只查有改动的
```