Files
lpt-meta/.agents/skills/write-notes-like-deepseek/scripts/archive-agent-note.ts
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

168 lines
6.7 KiB
TypeScript
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.
/**
* 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})`);
}
}