docs: 共有技能收归 meta 单一份并加工作区级笔记校验入口
- write-notes-like-deepseek 从三个子仓库的重复副本改为 meta 唯一副本 - 新增 .agents/scripts/verify-notes.ts,从 meta 视角一次校验四个笔记根 - workspace-layout 补「共有技能单一来源」的落位与理由 - .rgignore 排除 archived 历史快照
This commit is contained in:
@@ -0,0 +1,167 @@
|
||||
/**
|
||||
* CLI tool to archive an implemented Agent Note with frozen manifest sealing.
|
||||
* Usage: node <skill-dir>/scripts/archive-agent-note.ts .agents/notes/implemented/<class>/<filename>.md [--superseded-by <new-note-path>]
|
||||
* --superseded-by writes a relative link into the NEW note, never into the archived file.
|
||||
*/
|
||||
import { createHash } from "node:crypto";
|
||||
import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
|
||||
import { basename, dirname, join, relative, resolve } from "node:path";
|
||||
import { agentNoteRoot, AGENT_NOTE_CLASSES, walkAgentNoteTree } from "./agent-note-tree.ts";
|
||||
|
||||
const args = process.argv.slice(2);
|
||||
const targetArg = args[0];
|
||||
const supersededByArgIdx = args.indexOf("--superseded-by");
|
||||
const supersededByArg = supersededByArgIdx !== -1 ? args[supersededByArgIdx + 1] : undefined;
|
||||
if (supersededByArgIdx !== -1 && !supersededByArg) {
|
||||
console.error("Error: --superseded-by requires a note path");
|
||||
process.exit(1);
|
||||
}
|
||||
if (!targetArg) {
|
||||
console.error("Usage: node <skill-dir>/scripts/archive-agent-note.ts <path-to-note> [--superseded-by <new-note-path>]");
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
let successorPath: string | undefined;
|
||||
let successorRel: string | undefined;
|
||||
if (supersededByArg) {
|
||||
successorPath = resolve(process.cwd(), supersededByArg);
|
||||
if (!existsSync(successorPath)) {
|
||||
console.error(`Error: --superseded-by target not found at ${successorPath}`);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
const targetPath = resolve(process.cwd(), targetArg);
|
||||
if (!existsSync(targetPath)) {
|
||||
console.error(`Error: target note not found at ${targetPath}`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const relToRoot = relative(agentNoteRoot, targetPath).replace(/\\/g, "/");
|
||||
const segs = relToRoot.split("/");
|
||||
|
||||
if (segs[0] !== "implemented" || segs.length !== 3) {
|
||||
console.error(`Error: only notes in .agents/notes/implemented/<class>/ can be archived (got: ${relToRoot})`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const [, cls, filename] = segs;
|
||||
if (!AGENT_NOTE_CLASSES.includes(cls as any)) {
|
||||
console.error(`Error: unknown class "${cls}"`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
// 1. Read and update content with Archived line
|
||||
const raw = readFileSync(targetPath, "utf8");
|
||||
const lines = raw.split("\n");
|
||||
const statusIdx = lines.findIndex((l) => l === "Status: implemented");
|
||||
if (statusIdx === -1) {
|
||||
console.error("Error: note must contain `Status: implemented` to be archived");
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
// Local calendar date, not UTC — toISOString() would roll the archived stamp
|
||||
// back one day for evening runs east of the prime meridian.
|
||||
const nowLocal = new Date();
|
||||
const pad2 = (n: number) => String(n).padStart(2, "0");
|
||||
const today = `${nowLocal.getFullYear()}-${pad2(nowLocal.getMonth() + 1)}-${pad2(nowLocal.getDate())}`;
|
||||
// DSH contract: `Archived:` sits immediately below `Status:` (L3/L4).
|
||||
if (!lines.some((l) => l.startsWith("Archived:"))) {
|
||||
lines.splice(statusIdx + 1, 0, `Archived: ${today}`);
|
||||
}
|
||||
|
||||
if (successorPath) {
|
||||
const rel = relative(agentNoteRoot, successorPath).replace(/\\/g, "/");
|
||||
successorRel = rel;
|
||||
const successorSegs = rel.split("/");
|
||||
if (successorSegs.length !== 3 || !["proposed", "implemented", "rejected"].includes(successorSegs[0] ?? "")) {
|
||||
console.error(`Error: --superseded-by target must be an active note in {lifecycle}/{class}/ (got: ${rel})`);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
const oldTitle = (lines[0] ?? "").replace(/^# Agent Note[::] ?/, "").trim() || basename(filename, ".md");
|
||||
const updatedContent = lines.join("\n");
|
||||
|
||||
// 2. Determine archived destination
|
||||
const archivedDir = join(agentNoteRoot, "archived", cls);
|
||||
mkdirSync(archivedDir, { recursive: true });
|
||||
const archivedPath = join(archivedDir, filename);
|
||||
|
||||
if (existsSync(archivedPath)) {
|
||||
console.error(`Error: target archived note already exists at ${archivedPath}`);
|
||||
console.error("Refusing to overwrite existing archived note. Please inspect and resolve name collision manually.");
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
writeFileSync(targetPath, updatedContent, "utf8");
|
||||
renameSync(targetPath, archivedPath);
|
||||
console.log(`Moved: ${relToRoot} -> archived/${cls}/${filename}`);
|
||||
|
||||
// 3. Update archived/manifest.json with SHA-256 seal
|
||||
const manifestPath = join(agentNoteRoot, "archived", "manifest.json");
|
||||
interface Manifest {
|
||||
version: 1;
|
||||
files: Record<string, string>;
|
||||
}
|
||||
let manifest: Manifest = { version: 1, files: {} };
|
||||
if (existsSync(manifestPath)) {
|
||||
try {
|
||||
manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
|
||||
} catch (e) {
|
||||
console.warn("Warning: existing manifest.json was invalid, creating fresh");
|
||||
}
|
||||
}
|
||||
|
||||
const newArchivedRel = `archived/${cls}/${filename}`;
|
||||
const sha256 = `sha256:${createHash("sha256").update(readFileSync(archivedPath)).digest("hex")}`;
|
||||
manifest.files[newArchivedRel] = sha256;
|
||||
|
||||
// Deterministic sort keys
|
||||
const sortedFiles = Object.fromEntries(
|
||||
Object.entries(manifest.files).sort(([a], [b]) => a.localeCompare(b))
|
||||
);
|
||||
writeFileSync(manifestPath, JSON.stringify({ version: 1, files: sortedFiles }, null, 2) + "\n", "utf8");
|
||||
console.log(`Sealed in archived/manifest.json with hash ${sha256.slice(0, 16)}...`);
|
||||
|
||||
// 4. Scan inbound links in active notes (precise markdown-link resolution)
|
||||
const { notes } = walkAgentNoteTree();
|
||||
const inboundFound: string[] = [];
|
||||
const LINK_REGEX = /\[([^\]]+)\]\(([^)]+)\)/g;
|
||||
for (const note of notes) {
|
||||
const noteFullPath = resolve(agentNoteRoot, note.rel);
|
||||
const content = readFileSync(noteFullPath, "utf8");
|
||||
let match: RegExpExecArray | null;
|
||||
LINK_REGEX.lastIndex = 0;
|
||||
while ((match = LINK_REGEX.exec(content)) !== null) {
|
||||
const rawTarget = match[2]?.trim();
|
||||
if (!rawTarget || rawTarget.startsWith("http://") || rawTarget.startsWith("https://") || rawTarget.startsWith("#") || rawTarget.startsWith("mailto:")) continue;
|
||||
const fileTarget = rawTarget.split("#")[0];
|
||||
if (!fileTarget) continue;
|
||||
// resolve the link relative to the linking note, then compare with the archived note's original location
|
||||
const resolvedTarget = resolve(dirname(noteFullPath), fileTarget);
|
||||
if (resolvedTarget === targetPath) {
|
||||
inboundFound.push(note.rel);
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (inboundFound.length > 0) {
|
||||
console.log("\n[Notice] The following active notes link to the archived note:");
|
||||
for (const rel of inboundFound) {
|
||||
console.log(` - ${rel}`);
|
||||
}
|
||||
console.log("Please review and update their relative markdown links if necessary.");
|
||||
} else {
|
||||
console.log("\nNo active notes link to this archived note.");
|
||||
}
|
||||
|
||||
if (successorPath && successorRel) {
|
||||
const relLink = relative(dirname(successorPath), archivedPath).replace(/\\/g, "/");
|
||||
const newRaw = readFileSync(successorPath, "utf8");
|
||||
if (!newRaw.includes(`archived/${cls}/${filename}`) && !newRaw.includes(relLink)) {
|
||||
writeFileSync(successorPath, `${newRaw.replace(/\s*$/, "")}\n\n[历史快照:${oldTitle}](${relLink})\n`, "utf8");
|
||||
console.log(`Linked from ${successorRel}: [历史快照:${oldTitle}](${relLink})`);
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user