docs: 共有技能收归 meta 单一份并加工作区级笔记校验入口

- write-notes-like-deepseek 从三个子仓库的重复副本改为 meta 唯一副本
- 新增 .agents/scripts/verify-notes.ts,从 meta 视角一次校验四个笔记根
- workspace-layout 补「共有技能单一来源」的落位与理由
- .rgignore 排除 archived 历史快照
This commit is contained in:
cat-shark
2026-11-18 14:59:45 +08:00
parent a194477b65
commit f99e1e156d
27 changed files with 3767 additions and 11 deletions
@@ -0,0 +1,158 @@
/**
* Enforce Agent Note headers, lifecycle-specific sections, alternatives.
* Implemented notes may not carry proposal-era H2s; present tense in the
* body is a prose rule, not a lexical scan.
* Run: node <skill-dir>/scripts/verify-agent-note-format.ts
*/
import { readFileSync } from "node:fs";
import { resolve } from "node:path";
import { agentNoteRoot, walkAgentNoteTree } from "./agent-note-tree.ts";
const STATUS: Record<string, RegExp> = {
proposed: /^Status: proposed$|^状态[::] ?(?:proposed|已提议)$/,
implemented: /^Status: implemented$|^状态[::] ?(?:implemented|已实现)$/,
rejected: /^Status: rejected — .+$|^状态[::] ?(?:rejected|已否决) — .+$/,
};
const PROBLEM_FIRST = ["## Problem", "## 问题"];
const REQUIRED: Record<string, string[][]> = {
proposed: [
["## Proposal", "## 提议", "## 方案", "## 提案"],
["## Acceptance criteria", "## 验收标准", "## 验收条件", "## 接受标准"],
["## Risks", "## 风险"],
],
implemented: [
["## Decision", "## 决定", "## 决策"],
["## Consequences", "## 后果", "## 影响", "## 结果", "## 结果与代价", "## 影响与验证", "## 后果与边界"],
],
rejected: [
["## Proposal", "## 提议", "## 方案", "## 提案"],
],
};
const BANNED_IMPLEMENTED = new Set([
"## proposal", "## plan", "## migration plan", "## acceptance criteria",
"## 提议", "## 方案", "## 提案",
"## 计划", "## 规划", "## 迁移计划",
"## 验收标准", "## 验收条件", "## 接受标准",
]);
const ALTERNATIVES_RE = /^## (?:Alternatives considered|.{0,8}?(?:替代方案|备选(?:方案)?|其他做法))$/;
const FORMAT_ADOPTED = "2026-07-05";
const GRANDFATHER = "<!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->";
/** Strip trailing parenthetical: `## Decision(说明)` → `## Decision`. */
function headingBase(h: string): string {
return h.replace(/[((].*$/, "").trimEnd();
}
interface MaskedSource {
lines: string[];
/** line indexes inside fenced code blocks */
fenced: boolean[];
/** line indexes inside HTML comments */
commented: boolean[];
}
/** Normalize BOM/CRLF, then mask fenced code and HTML comment regions. */
function maskSource(raw: string): MaskedSource {
const normalized = raw.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n");
const lines = normalized.split("\n");
const fenced = new Array<boolean>(lines.length).fill(false);
const commented = new Array<boolean>(lines.length).fill(false);
let inFence = false;
let inComment = false;
for (let i = 0; i < lines.length; i++) {
const l = lines[i];
fenced[i] = inFence;
commented[i] = inComment;
// A fence opens/closes only on its own line (≤3 leading spaces); fence
// mentions inside inline code or prose never toggle state.
if (!inComment && /^\s{0,3}```/.test(l)) {
fenced[i] = true;
inFence = !inFence;
} else if (inFence) {
fenced[i] = true;
}
// Fence interiors are opaque: a `<!--` in a HTML/JSX sample must not
// leak the comment mask past the closing fence.
if (inFence) continue;
const openIdx = inComment ? -1 : l.indexOf("<!--");
const closeIdx = l.indexOf("-->");
if (inComment) {
commented[i] = true;
if (closeIdx !== -1) inComment = false;
} else if (openIdx !== -1) {
commented[i] = true;
if (closeIdx === -1 || closeIdx < openIdx) inComment = true;
}
}
return { lines, fenced, commented };
}
function isProseLine(src: MaskedSource, i: number): boolean {
if (src.fenced[i] || src.commented[i]) return false;
return !/^\s*>/.test(src.lines[i]);
}
const { notes, errors } = walkAgentNoteTree();
for (const note of notes) {
const fail = (msg: string) => { errors.push(`format: ${note.rel} — ${msg}`); };
const src = maskSource(readFileSync(resolve(agentNoteRoot, note.rel), "utf8"));
const { lines } = src;
const proseIdx: number[] = [];
for (let i = 0; i < lines.length; i++) if (isProseLine(src, i)) proseIdx.push(i);
const prose = proseIdx.map((i) => lines[i]);
// Halfwidth or fullwidth colon (IME often inserts :)
if (!/^# Agent Note[::] ?\S/.test(lines[0] ?? "")) fail("line 1 must be `# Agent Note: <title>`");
if (lines[1] !== "") fail("line 2 must be blank");
const re = STATUS[note.lifecycle];
if (re && !re.test(lines[2] ?? "")) fail(`line 3 must match ${note.lifecycle} status grammar (${String(re)})`);
if (lines[3] !== "") fail("line 4 must be blank");
// single Status line (fences, quotes and comments immune). Match strict
// status-shaped lines only — body prose like "Status: 200 means OK" must
// not be miscounted as a duplicate status header.
const looksLikeStatusLine = (l: string) => {
const t = l.trim();
return Object.values(STATUS).some((re) => re.test(t));
};
const statusCount = prose.filter(looksLikeStatusLine).length;
if (statusCount !== 1) fail("Status: line must appear exactly once");
const h2s = prose.filter((l: string) => l.startsWith("## ")).map((l: string) => l.trimEnd());
const bases = h2s.map(headingBase);
if (!PROBLEM_FIRST.includes(headingBase(h2s[0] ?? ""))) {
fail(`first section must be ## Problem or ## 问题 (got ${JSON.stringify(h2s[0] ?? "<none>")})`);
}
for (const group of REQUIRED[note.lifecycle] ?? []) {
if (!group.some((h: string) => bases.includes(h))) fail(`missing one of ${JSON.stringify(group)}`);
}
if (note.lifecycle === "implemented") {
for (const h of bases.filter((x: string) => BANNED_IMPLEMENTED.has(x.toLowerCase()))) {
fail(`banned in implemented: ${h}`);
}
}
const hasSection = bases.some((h: string) => ALTERNATIVES_RE.test(h));
const rawText = readFileSync(resolve(agentNoteRoot, note.rel), "utf8");
const hasGrandfather = rawText.includes(GRANDFATHER);
if (hasSection && hasGrandfather) fail("carries both ## Alternatives considered and grandfather comment — drop the comment");
if (!hasSection && !hasGrandfather) {
fail("missing ## Alternatives considered / ## 备选方案");
}
if (hasGrandfather && note.date >= FORMAT_ADOPTED) fail(`grandfather comment only valid before ${FORMAT_ADOPTED}`);
}
if (errors.length) {
for (const e of errors) console.error(e);
process.exit(1);
}
console.log(`ok: ${notes.length} note(s) verified`);