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

4.3 KiB
Raw Blame History

按需阅读:校验脚本

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,按通用中文单语宿主裁过:无双语三件套、无 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 篇「通过」,制造假绿)。日常请直接用:

node .agents/scripts/verify-notes.ts            # 自动遍历所有含 .agents/notes 的仓库
node .agents/scripts/verify-notes.ts lpt-be     # 只查一个
node .agents/scripts/verify-notes.ts --changed  # 只查有改动的