- write-notes-like-deepseek 从三个子仓库的重复副本改为 meta 唯一副本 - 新增 .agents/scripts/verify-notes.ts,从 meta 视角一次校验四个笔记根 - workspace-layout 补「共有技能单一来源」的落位与理由 - .rgignore 排除 archived 历史快照
4.3 KiB
4.3 KiB
按需阅读:校验脚本
SKILL §6 的展开。接入 CI 时对照;本地轻量使用时跳过。
检查脚本(均为 tsx,零新增依赖,可直接用 node 独立运行;Node 22.6+ 原生支持,无需 tsx 依赖)
-
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 链接有效性。
- 校验 lifecycle 封闭集
-
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 自动归一。
- 头部:第 1 行
-
verify-archived(scripts/verify-archived-agent-notes.ts,标配)- 每篇归档:头部布局逐行校验(L3
Status: implemented/ L4Archived: 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:先证明既有封印未变,再为未封印文件追加封印(历史语料补齐用这个)。
- 每篇归档:头部布局逐行校验(L3
-
check-note-anchors(scripts/check-note-anchors.ts,软报告,退出码恒 0,不进 CI)- 扫描源码(env
AGENT_NOTE_CODE_ROOT指定根,默认 cwd;自动跳过 node_modules/.git/dist 等)里的// Note:/# Note:物理锚点:报告悬空锚点、没有锚点指向的 implemented 笔记、缺路径的锚点行。宿主没用锚点就不必跑。
- 扫描源码(env
接入建议
- 轻量(个人/无 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 # 只查有改动的