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
+161
View File
@@ -0,0 +1,161 @@
/**
* 工作区统一笔记校验:对所有含 .agents/notes/ 的仓库跑三条门禁。
*
* 用法(在 meta 仓库根目录):
* node .agents/scripts/verify-notes.ts # 全部仓库
* node .agents/scripts/verify-notes.ts lpt-be # 只查指定仓库
* node .agents/scripts/verify-notes.ts --changed # 只查工作区里有未提交改动的仓库
*
* 为什么需要它:agent 只在 meta 启动,笔记却分散在各子仓库。逐个仓库切 cwd
* 手敲长命令既容易漏仓,也容易在错误目录下静默通过(AGENT_NOTE_ROOT 缺省指向
* cwd/.agents/notes,目录不存在时脚本会报 0 篇通过)。这里统一由 meta 视角驱动。
*/
import { execFileSync } from "node:child_process";
import { existsSync, readdirSync, statSync } from "node:fs";
import { join, resolve } from "node:path";
const workspaceRoot = resolve(import.meta.dirname, "../..");
const skillDir = join(workspaceRoot, ".agents/skills/write-notes-like-deepseek/scripts");
/** 三条硬门禁:目录结构、头部骨架、归档封印。锚点体检是软报告,不进门禁。 */
const CHECKS = [
{ script: "verify-agent-note-tree.ts", label: "tree" },
{ script: "verify-agent-note-format.ts", label: "format" },
{ script: "verify-archived-agent-notes.ts", label: "archive" },
];
const argv = process.argv.slice(2);
const changedOnly = argv.includes("--changed");
const explicitRepos = argv.filter((a) => !a.startsWith("--"));
interface Target {
name: string;
root: string;
}
/** meta 自身 + 各子仓库。没有 .agents/notes 的仓库不参与,避免凭空造结构。 */
function discoverTargets(): { targets: Target[]; broken: string[] } {
const targets: Target[] = [];
const broken: string[] = [];
const add = (name: string, dir: string) => {
const agentsDir = join(dir, ".agents");
const notes = join(agentsDir, "notes");
if (existsSync(notes) && statSync(notes).isDirectory()) {
targets.push({ name, root: notes });
return;
}
// 有 .agents/ 但没 notes/:只有「git 记录里曾经有过 notes」才是误删;
// 从未有过的仓库(如只放 roles 的 lpt-docs)属正常状态,静默跳过。
if (existsSync(agentsDir) && hadNotesInGit(dir)) {
broken.push(`${name}: git 记录里有 .agents/notes/,但工作区已不存在(疑似误删)`);
}
};
add("meta", workspaceRoot);
for (const entry of readdirSync(workspaceRoot, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
const dir = join(workspaceRoot, entry.name);
// 子项目是独立 git 仓库;没有 .git 的目录(如 node_modules 之外的空壳)不算
if (!existsSync(join(dir, ".git"))) continue;
add(entry.name, dir);
}
return { targets, broken };
}
/** 该仓库 git 索引里是否出现过 .agents/notes/ 下的文件。 */
function hadNotesInGit(dir: string): boolean {
try {
const out = execFileSync("git", ["ls-files", ".agents/notes"], { cwd: dir, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
return out.trim().length > 0;
} catch {
return false;
}
}
/** --changed:用 git status 判断该仓库工作区是否有改动(含未跟踪),跳过干净的仓库。 */
function hasLocalChanges(dir: string): boolean {
try {
const out = execFileSync("git", ["status", "--porcelain"], { cwd: dir, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
return out.trim().length > 0;
} catch {
return true; // 判断不了就照常校验,宁多勿漏
}
}
const discovered = discoverTargets();
let targets = discovered.targets;
if (discovered.broken.length > 0) {
for (const b of discovered.broken) console.error(`✗ ${b}`);
console.error("误删笔记目录不应静默跳过门禁;用 git checkout 恢复后再跑。");
process.exit(1);
}
if (explicitRepos.length > 0) {
const known = new Set(targets.map((t) => t.name));
const unknown = explicitRepos.filter((r) => !known.has(r));
if (unknown.length > 0) {
console.error(`未知仓库:${unknown.join(", ")}(有 .agents/notes 的仓库:${[...known].join(", ")})`);
process.exit(1);
}
targets = targets.filter((t) => explicitRepos.includes(t.name));
}
if (changedOnly) {
targets = targets.filter((t) => hasLocalChanges(t.root === join(workspaceRoot, ".agents/notes") ? workspaceRoot : resolve(t.root, "../..")));
if (targets.length === 0) {
console.log("ok: 工作区无改动,跳过笔记校验");
process.exit(0);
}
}
if (targets.length === 0) {
console.log("ok: 没有仓库包含 .agents/notes,无需校验");
process.exit(0);
}
interface Failure {
repo: string;
check: string;
output: string;
}
const failures: Failure[] = [];
for (const target of targets) {
for (const check of CHECKS) {
const scriptPath = join(skillDir, check.script);
if (!existsSync(scriptPath)) {
failures.push({ repo: target.name, check: check.label, output: `脚本缺失:${scriptPath}` });
continue;
}
try {
// AGENT_NOTE_ROOT 显式指定,避免脚本回落到 cwd 而校验错仓库
execFileSync(process.execPath, [scriptPath], {
cwd: workspaceRoot,
env: { ...process.env, AGENT_NOTE_ROOT: target.root },
encoding: "utf8",
stdio: ["pipe", "pipe", "pipe"],
});
} catch (error) {
const err = error as { stdout?: string; stderr?: string };
failures.push({
repo: target.name,
check: check.label,
output: `${err.stdout ?? ""}${err.stderr ?? ""}`.trim(),
});
}
}
}
if (failures.length > 0) {
for (const f of failures) {
console.error(`\n✗ ${f.repo} [${f.check}]`);
for (const line of f.output.split("\n")) console.error(` ${line}`);
}
console.error(`\n${failures.length} 项校验失败,修完再交。`);
process.exit(1);
}
console.log(`ok: ${targets.map((t) => t.name).join(", ")} — 三条门禁全部通过`);