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
+11 -7
View File
@@ -15,18 +15,22 @@
| 项目专属规则 | 各仓库自己的 `.agents/roles/` | 后端的迁移规范、前端的代码标准 |
| 项目知识与架构约定 | 各仓库 `AGENTS.md` | 端口、调用关系、命名约定 |
| 跨仓库待办与验收标准 | `OPTIMIZATION_BACKLOG.md` | 优化条目 |
| 工作区级技能 | `.agents/skills/` | `mermaid-diagram` |
| 工作区级技能(共有技能唯一来源) | meta `.agents/skills/` | `mermaid-diagram`、`write-notes-like-deepseek` |
| 项目专属技能 | 各仓库自己的 `.agents/skills/` | `lpt-be/.agents/skills/comment-cleanup` |
> 共有技能**只在 meta 放一份**,子项目内不建副本、不建符号链接;理由与验收见 `.agents/roles/workspace-layout.md`。
## 生效方式(重要)
**`.agents/roles/` 不是自动加载入口。** 规则要真正约束行为,必须在 `AGENTS.md` 里被引用——
`AGENTS.md` 是每次会话自动加载的项目指令入口,只有它(和按描述触发的 skills)会被读到。
所以:新增规则时,务必同时在 `AGENTS.md` 对应章节挂上入口。
**`.agents/roles/` 不是自动加载入口,任何 harness 都不会扫描它。** 规则要真正约束行为,必须在 `AGENTS.md` 里被引用——
`AGENTS.md` 是各 harness 通用的项目指令入口(Claude 体系另有 `CLAUDE.md`),只有它会被读到。
所以:新增规则时,务必同时在该仓库 `AGENTS.md` 挂上入口,并在 meta `AGENTS.md` 的子仓库索引里登记路径与触发场景。
配套事实:pi 加载 `AGENTS.md` 时会同时读**工作目录及其父目录**。
因此在 `lpt-be` 这类子目录里干活时,meta 的 `AGENTS.md` 仍会被读到——
这正是各子项目不再重复通用规则的前提。
配套事实:
- **agent 会话从 meta 根目录启动**,子项目靠 `subagent(cwd=<repo>)` 进入(见 meta `AGENTS.md` 首页)。因此共有技能放在 meta 就能被发现,不需要往子仓库复制。
- 在子目录里启动 agent 时,父目录的 `AGENTS.md` 也会被读到(各 harness 大体一致),但**这不是默认工作方式**,不要依赖它:在 `lpt-be` 里启动看不到另外四个仓库的约定,也看不见 meta 的共有技能。
- 反过来,在 meta 根目录干活时子仓库 `AGENTS.md` 不会自动加载,靠 meta 的子仓库索引带出。
## 规则文件的写法(强制)
+48 -4
View File
@@ -14,11 +14,55 @@
### meta 仓库的维护边界
- 本 meta 仓库只维护 `AGENTS.md`、`.gitignore`、`.agents/`(代理技能与通用规则)和 `docs/diagrams/`(图表评审产物),不要在本仓库根目录创建业务代码或系统文档。
- 本 meta 仓库只维护 `AGENTS.md`、`.gitignore`、`.agents/`(代理技能、通用规则、校验脚本、跨仓库笔记)和 `docs/diagrams/`(图表评审产物),不要在本仓库根目录创建业务代码或系统文档。
- `.gitignore` 忽略所有子项目目录,只放行上述根级条目,避免把独立 Git 仓库提交进本 meta 仓库。
### 业务决策笔记的归属
业务决策写在**各自的业务仓库**里,不集中到 meta,也不放进 `lpt-docs`。
- `lpt-be` / `lpt-fe` / `lpt-ai` / `lpt-android` 的决策笔记 → 该仓库自己的 `.agents/notes/`,与该仓库的代码同一次提交。
- 为什么:决策要被读到,前提是改这段代码的 agent 必然翻到它。放在同仓库同一次改动里,读代码就会撞见;集中到别的仓库,等于写给人看而不是写给下一个人用。
- `lpt-docs` 只维护概念定义与设计思路,**不承接决策流水账与开发过程记录**(见下节「文档归属」)。
- 只有在跨仓库口径(如分支↔环境对应、服务间字段耦合)无法归属到单一仓库时,才写进 meta 的 `.agents/notes/`,并在 `AGENTS.md` 里列出路径。
- 所有记录内容的标题与正文一律用简体中文(`Agent Note:` / `Status:` 头块、代码、命令、路径、专有名词除外);笔记格式与校验沿用 meta 仓库 `.agents/skills/write-notes-like-deepseek/`。
### 规则与技能的落位
- 通用规则(跨仓库)→ meta 仓库 `.agents/roles/`。
- 项目专属规则 → 该仓库自己的 `roles/`。
- 工作区级技能 → `.agents/skills/<技能名>/`;子项目专属技能 → 该仓库 `skills/`。
规则和技能都收在 `.agents/` 下,不要放在仓库根目录的 `roles/`、`skills/`。
**先回答「这东西换个仓库还成立吗?」**
| 内容 | 位置 | 例子 |
|------|------|------|
| 通用规则(不限仓库) | meta `.agents/roles/` | 提交规范、调研汇报、并行委派 |
| 项目专属规则 | 该仓库 `.agents/roles/` | 后端的迁移规范、前端的代码标准 |
| **共有技能(单一来源)** | **只在 meta `.agents/skills/`** | `write-notes-like-deepseek`、`mermaid-diagram` |
| 项目专属技能 | 该仓库 `.agents/skills/` | `lpt-be` 的 `comment-cleanup`、`lpt-fe` 的 `ui-review` |
| 决策笔记 | 该仓库 `.agents/notes/` | 能归属到单一仓库的决定 |
| 跨仓库决策笔记 | meta `.agents/notes/` | 分支↔环境口径这类无法归属的决定 |
### 共有技能只在 meta,子项目不放副本
跨仓库通用的技能一律以 meta 的 `.agents/skills/<技能名>/` 为**唯一真实副本**,子项目里不建副本、不建符号链接。
理由(每条都可验证):
- **agent 只在 meta 运行**(见 meta `AGENTS.md`),工作目录向上扫描技能目录时能发现 meta 的 `.agents/skills/`;子项目里的副本对 agent 没有任何额外作用。
- **副本必漂移。** 本工作区曾把 `write-notes-like-deepseek` 分别复制进三个仓库(三份 sha1 完全一致),之后对上游的中文标题补丁就得手改三处;一旦漏改一处,各仓校验行为就不一致。
- **符号链接在 Windows / `core.symlinks=false` 下会退化成普通文本文件**(内容是一行路径字符串),`node path/SKILL.md` 直接 `Not a directory`;而 `lpt-fe/Dockerfile` 是 `COPY . .`,指向构建上下文之外的链接会让 `docker build` 报 forbidden path。两个坑都在本工作区实测过。
- **单独 clone 子仓库时(CI、别的机器)不依赖 meta**,技能本来就读不到,所以「副本能自包含」这个好处并不成立。
新增共有技能的步骤:在 meta `.agents/skills/<技能名>/` 建好 → 在 meta `AGENTS.md` 的「共有技能」段登记一行(路径 + 触发场景)→ 子项目里什么都不用做。
需要项目专属技能时,才在该仓 `.agents/skills/` 下建,并登记到 meta `AGENTS.md` 的子仓库索引。
### 生效方式的事实
三条事实决定了上述落位,写错位置等于写了没人读:
- **`.agents/roles/` 不会被任何 harness 自动加载。** 规则要生效,必须在该仓库 `AGENTS.md` 的「规则与技能位置」段列出路径,并在 meta `AGENTS.md` 的「子仓库规则与技能索引」里能找到;否则只是一堆没人读的文件。
- **技能发现机制因 harness 而异。** Pi 递归扫描用户级与项目技能目录(`.pi/skills/`、`.agents/skills/`,后者从工作目录向上,遇到 git 仓库根或工作区根停止);Claude 体系读 `.claude/skills/`;codex / dsh 等未必扫描技能目录。所以 meta `AGENTS.md` 里给出技能路径,让模型按需 `read`,不把「自动发现」当前提。
- **meta 会话只自动加载工作目录及父目录的 `AGENTS.md`。** 子仓库的 `AGENTS.md` 靠 meta `AGENTS.md` 的索引与读取协议带出来。不要依赖 `.pi/` 扩展、`.pi/settings.json` 或任何 harness 私有机制做自动注入,换一个入口就失效。
**维护纪律**:新增或删除子仓库规则/技能时,同一次提交里同步 meta `AGENTS.md` 的子仓库索引(只写路径 + 触发场景,不复制正文);索引里的路径必须真实存在。共有技能不登记进子仓库索引。
+4
View File
@@ -0,0 +1,4 @@
{
"type": "module",
"private": true
}
+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(", ")} — 三条门禁全部通过`);
@@ -0,0 +1,227 @@
---
name: write-notes-like-deepseek
description: Use when a change is non-trivial by DSH standards (behavior, architecture, cross-file contracts, process/tooling, testing strategy, or on-disk/wire/config formats), when choosing between technical alternatives, superseding a decision, or writing a postmortem. Records the why and rejected options in .agents/notes/ with script-enforced gates; skips purely mechanical edits (CRUD, styling, patches, tagging, formatting).
---
# Write Notes Like DeepSeek
> 方法提炼自 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的工程实践。聊天里的 Agent 负责拆任务、排计划;本 Skill 只做一件事:为什么这样改、放弃了什么、怎么证明改对了,都留在一处,给下一个改这段代码的人用。
## 红线:先判要不要写,再谈怎么写
模型有迎合强迫症,动不动就想立 Note。先过这道闸:
**快速返回——以下属于 DSH 定义的"纯机械或局部改动",严禁立 Note,直接改代码:**
- 纯排版格式化、错别字、无歧义重命名
- 样式调整(不改行为)
- 依赖补丁(不改行为)、版本发布打标(RC/Release tag)
- 常规 CRUD、单模块内看 diff 即懂的显式逻辑修复(无跨文件影响)
**判定对齐 DSH:非平凡改动必须写。** 命中以下任何一项即非平凡——改了**行为**、改了**架构**、改了**跨文件契约**、改了**流程与工具链**、改了**测试策略**、改了**落盘 / 网络 / 配置格式**——或其他维护者日后可能重访的决定。
**写之前,对照三个方向想清楚这篇笔记守住什么:**
1. **往前看(立新规)**——新建的跨模块通信契约、状态流转规则、访问边界、运行时不变量。不记,后来的 Agent 各写一套、随意击穿模块。
2. **往回看(记妥协)**——为看不见的约束放弃了业界主流或直觉的解法。不记,被否掉的老路会被重走一遍。
3. **做减法(收窄)**——破坏性重构、代码裁剪、API 暴露面收窄。不记,没人知道退出条件和迁移边界,减法做不下去——或者做过了头。
一句话记住:**代码和单测说不出来的意图、边界、取舍,就是非平凡。** 判不准时,从严。
> 对 AI 来说,写在散文里的规矩等于没有规矩——能机械检查的纪律都有脚本兜底(见 §6);决定翻转、当场审计、现在时正文靠操作流,不靠词法扫描。
> 优先级:宿主项目的 `AGENTS.md` / `CLAUDE.md` 与用户的直接指令**高于本 Skill**;本 Skill 是默认契约,不是更高法律。
| 内心的借口 | 现实 |
|---|---|
| "只是改个默认值/重命名" | 默认值和命名都是决策事实;原地更新老笔记只要 30 秒 |
| "先合并,以后再补" | 以后 = 永远不会;腐化从每一篇"以后补"开始 |
| "代码即文档" | 代码只说**是什么**,说不出**为什么**和**放弃了什么** |
| "改动很小,犯不着" | 规模小 ≠ 不用记;一个重试参数曾引发全网故障 |
| "不确定要不要写" | 对照上面的非平凡清单:命中就写,不命中就不写。别拿这句话当挡箭牌 |
- **优先就地同步,非必要不新建**:在 DeepSeek 的公开演进历史里,Note 的变更大头是原地修改现有 Note 的事实(路径、类名、默认参数),而不是开新文件。已有归属的改动直接更新那篇!
- **禁止把一篇 Note 改成另一个决定**:事实(路径、符号、默认值)就地改;决定或理由翻转 → 新开一篇并互链。禁止把 `## Decision` 改写成反面,禁止只靠 git 当旧理由的唯一副本。
- **写新篇当场审计,不准推迟**:按模块名/关键词搜 proposed + implemented + rejected;每篇命中当场分类:无关 / 部分重叠(互链)/ 完全吸收(删或归档)/ 过时提案(reject 或删)。分类结果和这篇新 Note 一起落盘。
- **垃圾不进归档**:过时提案转 `Status: rejected — <原因>`(严禁归档);无防坑价值的被否记录直接物理删除。
> 「决定」不重——个人项目里就是「为什么选 A 没选 B」。选型、取舍、踩过的坑,都值得写下。
## 0. 先探测,再落地
别一上来建全套目录。按这个仓库现在的样子选:
1. 有 `AGENTS.md` / `CLAUDE.md` / 贡献指南 → 读它;有 `docs/adr/`、`docs/decisions/`、Issue 模板等现成的决定记录 → 沿用,状态和种类按本 Skill 的文件夹来即可。
2. 没有现成的决定记录 → 按标准结构建:`.agents/notes/{proposed,implemented,rejected,archived} × 6 class`,用到哪个目录就建哪个,空目录不必预建——个人写、不用 git 也照此建全套结构,别精简成单目录。
3. 团队长期仓库 → 在相同结构上叠加流程:`CONTRIBUTING.md` / PR 模板加一句「重要改动必带一篇笔记」,并把校验脚本接进 CI。
> **多仓库工作区(如本工作区):笔记跟着它所描述的代码走,技能只留一份。**
> 每条笔记写进它所属子仓库的 `.agents/notes/`,与该仓代码同一次提交;只有无法归属到单一仓库的决定才写进工作区根(meta)的 `.agents/notes/`。
> 技能本身不往子仓库里复制副本,否则三处各自漂移。校验用工作区级的统一入口一次跑完全部仓库(见 §6)。
## 1. 路径即分类
每条 Note 的路径就是身份:`{lifecycle}/{class}/yyyy-mm-dd-topic.md`
**Lifecycle(一层文件夹,这篇走到哪一步):**
- `proposed` — 想法阶段,有了方案但还没落地
- `implemented` — 已落地,与代码同批改动保持同步
- `rejected` — 审慎否掉的提案,仅当能防止重犯时保留,否则删整组
- `archived` — 已完成且未来参考价值低的 implemented 记录,冻结不可改
**Class(二层文件夹,就这 6 个;再加要改检查脚本):**
- `feature` 新能力 — 用户或模型看得见的选择(不显然的行为也算)
- `bug-fix` 修缺陷 — 修好了什么,或补上复盘里暴露的缺口
- `simplification` 只删不增 — 不增加能力,只删代码、行为或表面
- `architecture` 结构怎么搭 — 发出去的源码怎么组织、包怎么连
- `process` 工具和流程 — 检查、发布、怎么协作(围着代码转,不是运行时行为)
- `testing` 测试怎么写 — 测试策略和基建
> `refactor` 不单列:能看见的行为变了,归到对应类;没变就是 `simplification`。不建 `INDEX.md`。细判据见 `references/classification.md`。
## 2. 文件格式(检查脚本会核对)
标题与正文一律用简体中文撰写:`# Agent Note:` 之后的标题、所有 `##` 节标题与正文都用中文;`Agent Note:` / `Status:` 头块关键字、代码、命令、路径、专有名词保持原样。与触发任务的输入语言无关。
前三行固定:
```markdown
# Agent Note: <标题>
Status: <状态>
```
状态必须与所在 lifecycle 文件夹一致(`rejected` 带一句话原因);文件名日期是**首次提出日**。Body 骨架:
- `proposed`:`## Problem` → `## Proposal` → …自由节… → `## Alternatives considered` → `## Acceptance criteria` → `## Risks`
- `implemented`:`## Problem` → `## Decision`(现在时) → …自由节… → `## Alternatives considered` → `## Consequences`
- `rejected`:冻结的 proposal 形态,结论在 `Status:` 行
> 备选方案必填:只记录真实考虑过的对手方案,先写它最强的理由再否定。没有过的选项不要编。「不做 / 复用现状」仅当当时真的权衡过才写。脚本只检查有没有 `## Alternatives considered`。确实没有真实备选时,保留节标题、正文写「无」即可过检,不要为凑数编造。
> `implemented` 的 `## Decision` 用现在时;门禁只拒提案标题(`## Proposal` / `## Plan` / `## Migration plan` / `## Acceptance criteria` 及其中文别名)。展开见 `references/note-format.md`。
模板见 `templates/`。
## 3. 动手前检索历史决策(去中心化 4 法)
动手重构或选型前,先查历史约束,防止重复踩坑或破坏前人妥协:
1. **入口注释(若有)**:代码入口若已有 `// Note: ... 见 .agents/notes/...`,顺着它读。没有就走下面三法,不要为了检索去补锚点。
2. **分类树物理切片**:不扫全库,按意图直切目录(架构看 `implemented/architecture/`,避坑看 `rejected/`)。
3. **精准全局检索**:使用 ripgrep 搜关键词或机制名,**必带 `--hidden` 并排除 `archived/`**:
```bash
rg --hidden --glob '!.agents/notes/archived/**' "<机制名或关键词>" .agents/notes/
```
4. **模块文档下钻**:子模块 README 涉及设计依据时,顺着相对 Markdown 链接直达对应 Note。
**问用户之前,先自己查。** 以上四法能答的事实,不要抛给用户;只有真正的决策才占用用户时间。
## 4. 什么时候写、什么时候改
**对话里的触发信号**——用户或自己说出这类话,就该动笔(文首红线清单里的机械改动除外,别拿这些短语当过度记录的理由):
- 拍板新路线:"就选 X"、"决定用 X"、"我们先用 X 顶着" → 触发 Note
- 比较中:"X 和 Y 怎么选"、"为什么倾向 X" → 触发备选记录
- 同一段理由被解释了第二遍 → 该写下来了
判定与操作流:
- **既有架构重构 / 路径迁移 / 参数改动** → **【首选原地同步】**:直接在持有该决定的老 Note 里修正事实(代码路径、方法签名、默认值),不另起新篇,也不要在正文追加流水账历史。`## Decision` 核心理由不变;理由变了就走新建。
- **写新 Note 之前** → 按模块名/关键词搜活跃笔记,当场分类(见文首「当场审计」),禁止留到以后大扫除。
- **新想法、还没动手** → 先写 `proposed`(为什么想这么做、考虑过哪几条路),评审完再动手。交互纪律见下。
- **施工完(proposed → implemented)**,同一次改动里做完:① 移到 `implemented/<class>/`,文件名日期不动;② `Status: proposed` → `Status: implemented`;③ `## Proposal` → 现在时 `## Decision`;④ `## Acceptance criteria` / `## Risks` 折进 `## Consequences`(或现在时 `## Testing`);⑤ 删计划段。与代码同批落盘——**git 场景即同一 commit/PR**。
- **方案被新决策部分取代** → 两篇都留,双方加相对链接;只更新仍成立的事实。禁止归档。
- **方案被新决策完全取代** → 新 Note 接管并写入旧篇全部独特理由/备选/后果/验证缺口;入站链接改完后,能删则删,不能删(旧篇仍有独立杠杆)再 `archive-agent-note.ts`。指针写在新笔记里,不写进归档篇。
- **免写场景**:见文首红线——快速返回清单里的,直接提交代码。
**交互协议(向用户提问时):**
1. **先分 facts 和 decisions**:环境里查得到的事实(代码、笔记树、rg)自己查完再问;只有真正要拍板的取舍才占用用户时间。
2. **一轮全抛**:所有待拍板的问题编号列出,每题独立一行给推荐答案 `➡️ <推荐>`;用户按编号批量应答("1 yes,2 第二个选项"),不挤牙膏、不来回试探。
3. **收敛靠确认门,不靠题数上限**:落笔/动手前复述全部决定,用户确认达成共识后再执行——复述中被默认掉的任何一点,用户在确认时纠偏;没确认不动手。
4. **开放决策超过五个是信号,不是配额**:说明这次改动太大——拆成多篇笔记,或先交 proposed 草稿走评审,别在一次对话里硬塞。
> 判定细则见 `references/when-to-write.md`,归档与删除见 `references/archiving.md`。
## 5. 怎么写好
- `## Consequences` 同时写**代价和收益**,不是只写"放弃了什么"。
- 自由节(package 拓扑、wire 契约、schema 等)放在 `Decision` 与 `Alternatives` 之间,保持可检索的机制名与 `must / may / never` 时序强调。
- 跨 Note 引用用相对 Markdown 链接 `[topic](../../implemented/architecture/2026-…-….md)`,不要裸数字,以便机械可校验。
- 宿主若已有此惯例,可在核心入口留一行 `// Note: ... 见 .agents/notes/...`;不是门禁。决定被取代时,这些注释是要同步的代码清单。
- 文风与去推导痕迹见 `references/prose-checklist.md`;简化机会见 `references/simplification-checklist.md`。
- 写完后过一遍 `references/quality-gate.md` 的语义自检,只向用户报**缺口和写得好的地方**(≤5 行),缺口给具体修法。结构靠脚本,意思靠人点头。
## 6. 校验与运维命令
> **本工作区的接入形态:技能只有一份,位于 meta 仓库 `.agents/skills/write-notes-like-deepseek/`。**
> agent 在 meta 根目录运行,笔记则分散在各子仓库(`lpt-be/.agents/notes/` 等)。
> 因此本节以下的「宿主根目录 + npm script」是上游通用形态;在本工作区请优先用下面的统一入口。
### 本工作区的统一入口(首选)
在 meta 仓库根目录执行:
```sh
node .agents/scripts/verify-notes.ts # meta + lpt-be + lpt-fe + lpt-ai 全部跑一遍
node .agents/scripts/verify-notes.ts lpt-be # 只查指定仓库
node .agents/scripts/verify-notes.ts --changed # 只查工作区有未提交改动的仓库
```
它内部对每个仓库依次跑 tree / format / archived 三条门禁,用 `AGENT_NOTE_ROOT` 显式指定笔记根,所以**不需要切到子仓库目录,也不会因 cwd 不对而假绿**。写完或改完任何笔记后跑一次,出口非零就是没交。
### 单条门禁(需要定位具体问题时)
```sh
AGENT_NOTE_ROOT=$PWD/lpt-be/.agents/notes node .agents/skills/write-notes-like-deepseek/scripts/verify-agent-note-tree.ts
AGENT_NOTE_ROOT=$PWD/lpt-be/.agents/notes node .agents/skills/write-notes-like-deepseek/scripts/verify-agent-note-format.ts
AGENT_NOTE_ROOT=$PWD/lpt-be/.agents/notes node .agents/skills/write-notes-like-deepseek/scripts/verify-archived-agent-notes.ts
```
不设 `AGENT_NOTE_ROOT` 时默认检查 `cwd/.agents/notes`——在 meta 根目录下那是**跨仓库笔记**的目录,不是子仓库的。
### 一键归档
```sh
AGENT_NOTE_ROOT=$PWD/lpt-be/.agents/notes node .agents/skills/write-notes-like-deepseek/scripts/archive-agent-note.ts \
lpt-be/.agents/notes/implemented/<类别>/<文件名>.md --superseded-by lpt-be/.agents/notes/implemented/<类别>/<新笔记>.md
```
### 上游通用形态(与本工作区不同)
若该技能被安装进单个仓库(本工作区不用这种方式):「宿主根目录」即含有 `.agents/notes/` 的那个仓库,且可由宿主配置 npm script:
```sh
npm run verify-agent-note-tree # 目录合法性、分类、文件名、笔记间相对链接
npm run verify-agent-note-format # 头块、状态、必备节、备选方案、implemented 禁用提案标题
npm run verify-archived # 归档封印:头部布局、manifest 哈希、只增不改(无 git 自动降级)
npm run verify-notes # 以上三线串跑(CI 用这个)
npm run archive-agent-note -- <path> [--superseded-by <新笔记>] # 一键归档;可选在新笔记插入互链 + 入站死链报告
npm run check-anchors # 软报告:若代码里有 // Note: 锚点,做双向体检;不当 CI 门
npm run init-board # 生成 ~69KB 轻量看板 board.html(日常开发推荐)
npm run bundle-board # 打包内嵌全量数据的自包含 demo.html
```
脚本位于本 Skill 的 `scripts/`,从**宿主项目根目录**调用,默认检查当前目录下的 `.agents/notes/`。先根据已加载的 `SKILL.md` 路径确定 Skill 位置,不要假定宿主根目录存在 `scripts/`,也不要切换到 Skill 目录执行。安装不会自动配置宿主的 npm scripts。
写完或改完任何笔记后必须运行验证:本工作区用 `node .agents/scripts/verify-notes.ts`;单仓安装用 `npm run verify-notes`;都没有时用 `node <skill>/scripts/verify-*.ts`——不得以「未配置校验入口」为由跳过。
看板打包参数为 `--bundle <notes目录> <输出.html> "名字"`;参数与免疫规则见 `references/verification.md`。
团队接入 CI 时,可将本 Skill 的 `templates/verify-notes.yml` 复制为宿主仓库的 `.github/workflows/verify-notes.yml`(Gitea 下需改成 `.gitea/workflows/` 并把 `github.*` 变量换成 `gitea.*`),调整为实际安装路径,并将 Skill 文件一起提交;模板在 Skill 目录内不会执行。可在 `CONTRIBUTING.md` / PR 模板加一句「重要改动必带一篇笔记」。
> 本工作区目前**未接 CI 门禁**(所有仓库的 workflow 都是 `workflow_dispatch`),靠本地入口 + 自觉执行。
## References
按需加载:
- `references/note-format.md` — 头块与 body 骨架展开
- `references/classification.md` — 6 class 判定与边界
- `references/when-to-write.md` — 何时新建 / 更新 / 流转(含与 DSH 判定对齐关系的说明)
- `references/archiving.md` — 归档与合并删除(含"未来参考价值"判定)
- `references/prose-checklist.md` — 行文与去泄露自检
- `references/simplification-checklist.md` — 简化机会自检
- `references/quality-gate.md` — 写后语义自检:Problem / Alternatives / Consequences / Verification 判定 + 汇报形态
- `references/verification.md` — 校验脚本说明
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,4 @@
{
"type": "module",
"private": true
}
@@ -0,0 +1,109 @@
# 按需阅读:归档、生命周期治理与冻结机制
> 提炼自 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的 notes 治理实践。收尾、复盘或大版本跃迁时对照;日常改动零负担,仅顺手就近替代。
**目录**:§0 执行频次(日常顺手 vs 大扫除)|§1 过时判定与保留红线(1.1 免检保留 / 1.2 归档标准 / 1.3 垃圾清理 / 1.4 校准示例)|§2 归档的标准操作流(CLI)|§3 永久冻结契约
---
## 0. 执行频次:日常顺手 vs 里程碑大扫除
无需每次修改代码都全量扫描,根据场景分级执行:
1. **日常提交(90% 场景:零全量心智负担)**:
- **就地修改(80%)**:改了某模块,顺手更新持有该决定的现成 Note 事实。
- **当场审计(10%)**:新增 Note 时,按模块名/关键词搜活跃笔记,当场分类(无关 / 部分重叠互链 / 完全吸收后删或归档 / 过时提案 reject 或删)。禁止把已知匹配推迟到大扫除。
2. **里程碑大扫除(10% 场景:按需治理)**:
- 仅处理当时搜不到的漏网:季度复盘、大版本发布、或活跃 Note 累积过多影响检索时,集中扫一次。
---
## 1. 过时判定与保留红线
判断是否过时**不看字数多少,也不看存续时间长短**,严格依据「未来防撞护栏价值」:
### 1.1 活跃区免检保留红线(即使年代久远也必须保留在 `implemented/`)
只要符合以下任一特征,绝对不过时,严禁归档:
- **所有权边界**:明确界定了模块调用权限与架构职责划分(如"UI 层严禁直接直连 DB")。
- **否定性保证(Negative Guarantees)**:明确承诺"绝不提供某项能力"或"永不向后兼容某旧协议"。
- **安全与合规底线**:防止注入、鉴权绕过或数据泄露的刚性约束。
- **易复踩的被否决方案(Alternatives considered)**:记录了极具诱惑力但在实践中已被证明会导致死锁/崩溃的错误路线。
### 1.2 归档标准(移入 `archived/`)
仅对 `implemented/` 中满足以下条件的记录执行归档:
- **被新架构完全取代但仍有独立杠杆**:后续 Note 已吸收核心逻辑,旧篇还留着否定性保证 / 所有权边界 / 重新引入条件——归档,互链写在新笔记。能删则删,见 `references/when-to-write.md` §4。
- **一次性设计与窄细节**:一次性 UI 边距调整、已废弃平台的狭窄单点适配器、已彻底闭环的简单 bug 修补。
### 1.3 垃圾清理规则(不进归档树)
- **`proposed/` 绝不归档**:前提消失(如依赖升级自带该能力)或不再推进的提案,直接转为 `Status: rejected — <一句话原因>`;已在其他方案中吸收的直接关闭。
- **无价值 `rejected/` 物理删除**:若被否决方案所依赖的旧技术/API 已被彻底移除,未来 Agent 绝无可能再提出该错误路线,直接将文件物理删除,不留冗余。
### 1.4 校准示例(立标用;词数证明篇幅不是标准)
移植自 DeepSeek Harness 的归档 skill。判断时对标示例的**理由结构**,别对标词数。
**该归档的 implemented(决定已完成、理由 unlikely 再指导未来工作):**
- 折叠侧边栏控制栏(~530 词)——已闭环的次要 UI 行为;
- 某 CLI 参数适配器(~1,500 词)——实现细节很重,但对未来设计几乎没有杠杆;
- 文档生成管线(~920 词)——机器已完成使命,现行生成器本身就是权威。
**该保留的 implemented(理由仍 owning 或 constraining 什么):**
- 事件溯源会话存储(~250 词)——基础性权威与持久化边界;
- 跨产品所有权解析规则(~600 词)——一条所有权边界立法;
- 项目会话目录策略(~630 词)—— durable 存储与身份策略;
- 并行 pre-push 门禁(~400 词)——边界案例,但仍指导门禁排程;
- 已下线的图片内容块(~330 词)——保留,直到多模态落地:它写着协调好的重引入条件。
**rejected 的存与删:**
- 保留「合并压缩包拆分」(~430 词)——合并的诱惑仍在,防重犯价值还在;
- 删除「经工具调用推送流式进度」(~970 词)——其 ACP/UI 前提已过时;
- 删除「去掉 ACP 终端元数据」(~360 词)——后来的自动化决策已经回答了这个问题。
---
## 2. 归档的标准操作流
推荐直接用 CLI(物理移动 + 封印 + 入站死链报告一次完成,**不依赖 git**):
```bash
node .agents/skills/write-notes-like-deepseek/scripts/archive-agent-note.ts \
.agents/notes/implemented/<class>/<filename>.md \
[--superseded-by .agents/notes/implemented/<class>/<新笔记>.md]
```
CLI 依次完成:
1. **写头部标记**:`Archived: YYYY-MM-DD` **紧邻** `Status: implemented` 插入(L3/L4 之间不留空行——这是与 DSH 原版对齐的硬契约,封印校验器逐行核对):
```markdown
# Agent Note: xxx
Status: implemented
Archived: 2026-08-31
## Problem
...
```
2. **物理移动**:`implemented/<class>/...` → `archived/<class>/...`(git 场景建议用 `git mv` 保留历史,CLI 用文件移动实现,无 git 同样工作)。
3. **封印入 `archived/manifest.json`**:记录该文件的 SHA-256。封印后任何对归档内容的篡改都会被 `verify-archived` 报警。
4. **入站死链报告**:扫描活跃笔记里指向该笔记的 Markdown 相对链接(精确链接解析,非文本子串),列出需人工修复的清单。
5. **可选 `--superseded-by`**:校验新笔记存在,并在**新笔记**末尾补一条指向归档路径的相对链接。不改归档篇。
除头部 `Archived:` 一行外,**禁止修改归档正文的任何其他字符**。
> 历史包袱补齐:若 `archived/` 已有笔记但还没有 manifest(例如从 DSH 导入的语料),运行
> `node .agents/skills/write-notes-like-deepseek/scripts/verify-archived-agent-notes.ts --write` 一次性补封印——它会先校验既有封印未被改动,再追加缺失条目,绝不重写历史。
---
## 3. 永久冻结契约(Frozen Immutable Contract)
一旦进入 `archived/`:
- **永久只读**:严禁编辑、翻译、重排版、更新、移动或删除。
- **机械强制**:`verify-archived` 校验头部布局、manifest 哈希、以及封印的 append-only(有 git 时与基线 ref 对比,`AGENT_NOTE_ARCHIVE_BASE_REF` 可指定基线,默认 HEAD;无 git 自动降级为哈希自校验并提示)。封印只增不改,已封印条目被改动或删除即报错。
- **免除日常扫描**:`verify-agent-note-tree` 和 `verify-agent-note-format` 默认跳过 `archived/` 目录,归档文件的出站链接失效不会阻塞日常构建。
- **不可作为当前行为依据**:代码冲突或架构评审时,以 `implemented/` 为准,`archived/` 仅作为历史考据参考;取代关系以新笔记互链和入站改写为准。
上述命令从宿主项目根目录执行;若 Skill 安装在其他位置,请替换 `.agents/skills/write-notes-like-deepseek` 为实际路径。
@@ -0,0 +1,33 @@
# 按需阅读:Class 分类
> SKILL §1 的展开。新建 Note 选 class 时对照。
## 封闭集(6 个,再加要改检查脚本)
| Class | 覆盖范围 |
|---|---|
| `feature` | 新增面向用户或模型的能力 |
| `bug-fix` | 修缺陷或补 postmortem 暴露的缺口 |
| `simplification` | 不新增能力的前提下删代码/行为/表面 |
| `architecture` | 已发布源码的结构性决定——包如何关联、运行时词汇是什么 |
| `process` | 代码之外的工具/策略/流程——门禁、包管理、vendoring 等 |
| `testing` | 测试 infra 与策略 |
判定技巧:
- `architecture` vs `process`:前者是"发出去的源码长什么样",后者是"围绕源码的工具链与工作流"。
- `refactor` 不单列——用 `simplification` 的判据"可观察行为变了吗"区分;行为不变即 simplification,行为变了归对应 feature/bug-fix/architecture。
- `feature` 不只在"新增能力"时用——**用户/模型可见、不显然的行为或产品选择,changes 够不上架构,也归 `feature`**。判据是"行为是否可被用户或下游观察",而不是"改动了多少代码"。只有局部实现细节、普通重构、行为不变的依赖补丁才不写任何 Note。
- 拿不准时看这条 Note 以后会被谁检索:找能力演进看 `feature`,找结构决策看 `architecture`,找门禁/发布看 `process`。
每条 Note 必带的语义要求(检查脚本管不了的):
- **Alternatives 只记录真实考虑过的对手方案**:先写它最强的论据再否——只写弱处的拒绝是稻草人。「不做/复用」仅当当时真的权衡过才写,不要编。
- **简化必写代价上限**:`simplification` 的 `## Consequences` 要写明"这个取舍的已知上限是什么、什么信号发生时该重访"。没有升级触发条件的简化会悄悄变永久。
- **验证要可确认**:写"改对了"时落到可被检查的表面(记"哪条路径、什么量级、跑什么命令确认"),没有基线就不要用相对量词——"提升了/更快了"在没有对比基线时是未验证断言,比不写更糟。
## 检查脚本
`scripts/agent-note-tree.ts` 定义 `AGENT_NOTE_CLASSES` 常量;未知 class 文件夹、lifecycle 根下的散落 `.md` 都会报错。新增 class 必须同时改常量和本文档,否则检查直接红。
分类封闭集与判据对齐 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的 notes 分类实践。
@@ -0,0 +1,69 @@
# 按需阅读:Note 文件格式
> SKILL §2 的展开。写/改 Note 时对照;只改代码不动 Note 时跳过。
## 头块(前三行,检查脚本会核对)
```markdown
# Agent Note: <标题>
Status: <状态>
```
- `proposed` → `Status: proposed`
- `implemented` → `Status: implemented`
- `rejected` → `Status: rejected — <一句话原因>`
标题前必须带 `Agent Note: ` 前缀,标题本身用简体中文;状态不含日期与括号;必须与所在 lifecycle 文件夹一致(脚本会交叉核对)。文件名日期是首次提出日,git 承载其余时间信息。
## Body 骨架
每篇 Note 都以 `## Problem` 开头——动机要能脱离方案独立成立。之后按 lifecycle区分:
**`proposed/`**
```markdown
## Problem
## Proposal
…自由节…
## Alternatives considered
## Acceptance criteria
## Risks
```
`Proposal` 可用将来时;`Acceptance criteria` 说清什么可观察状态算完成;`Risks` 同时写风险与已知取舍。
**`implemented/`**
```markdown
## Problem
## Decision
…自由节…
## Alternatives considered
## Consequences
```
`Decision` 用现在时描述已落地事实;门禁只拒提案标题(`## Proposal` / `## Plan` / `## Migration plan` / `## Acceptance criteria` 及其中文别名);用 `## Consequences` 同时记录代价与收益;可按需加 `## Testing` / `## Verification` 等现在时事实节。现在时靠人写,不靠词法扫描。
**`rejected/`**
冻结的 proposal 形态,verdict 在 `Status:` 行;保留提案时的 `Alternatives` 等节,不改写为对立面。
## Alternatives considered(必写)
每篇 Note 必含 `## Alternatives considered`:每个**真考虑过**的备选为何没选,一段一备选(可用 `### Why not <X>?` 子节)。没有过的选项不要编。「不做 / 复用现状」仅当当时真的权衡过才写。脚本只检查这一节在不在。
## 时态与禁止改写
- `proposed` 可用将来时;`implemented` 一律现在时,描述已落地事实。
- 一条 Note 永远不被改写成另一个决定;被取代用新 Note 接管,旧 Note 按归档/合并规则处理。
头块标题兼容全角冒号(`# Agent Note:标题`,中文输入法常打出全角);新笔记建议半角。
## 自由节与文风
- 自由节(package 拓扑、wire 契约、schema 等)放在 `Decision` 与 `Alternatives` 之间。
- 保留可检索的机制名与 `must`/`may`/`never` 时序强调;一个事实只在一处讲透,其余链过去。
- 跨 Note 引用用相对 Markdown 链接 `[topic](../../implemented/architecture/2026-…-….md)`,不要裸数字。
格式与别名表对齐 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的 notes 规范;本项目为中文单语:标题、节标题与正文用简体中文,头块 `Agent Note:` 与 `Status:` 保持英文原文以便脚本核对。
@@ -0,0 +1,51 @@
# 按需阅读:Notes 行文与去泄露自检
> 提炼自 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 仓库内 `dsh-prose-standard` 与 `dsh-trim-cot-leakage` 两个 skill 的可搬运部分。写/改 Note 时对照此清单;只改代码不动 Note 时跳过。
## 原则
- 只写代码说不清的:行为、失败、时序、所有权、后果与取舍。别复述代码或推导过程。
- 不变量能编进类型、可见性或 API 报错的,别只写在笔记里。
- 说人话,点名谁做了什么、在什么条件下、会怎样;少用“契约/边界/形态”等抽象词,除非指的就是该技术主体。
- 一个事实只在一处讲透,其余链过去;别把同一规则抄得到处都是。
- 写完自问:这段话不看实现能独立成立吗?不看当时聊天,现在的读者能验证吗?
## 写前自检(来自 prose-standard)
- 每段保留完整命题:主体/动作、条件/时序、must/may/never、否定保证与例外、所有权/副作用/失败与后果——缺一不可。
- `implemented` 用现在时,描述已落地事实;去掉计划口吻与 checklist。
- 保留可检索的机制名与关键 must/may/never、时序与否定强调;装饰性加粗和感叹少用。
- 一个改动内批量套用刚学到的规则到相似段落,别只改一处。
## 按位置查
- **Decision/Consequences**:区分、抛错/拒绝、副作用、所有权、时序、取消、持久化是否说清。
- **自由节**(拓扑/契约/schema):讲清职责、依赖与非显而易见的选择及指向。
- **Alternatives/Consequences**:同时写代价与收益,点名放弃的能力与重引入条件。
- **Testing/Verification**:只解释“为何这样验证”(fixture/断言/真实入口的必要性),不写走读。
## 去泄露自检(来自 trim-cot-leakage)
对每段可疑文字问:**只有当时的会话/PR/草稿可见吗?HEAD 的读者能独立验证吗?** 不能则重述为仓库视角,删去会话痕迹。能解析也≠安全——可验证只代表过了去泄露这一关,README/文档等当前状态面上,可解析的变更叙事仍是变更叙事,按第 3 类路由。
常见泄露(命中即改):
1. 死引用:`(decision 7)`/`(audit C2)`/`§N`/`plan §1.4` — 改为对已提交 Note/文档的具名路径引用,无主则删引用、重述事实。
2. 栈/PR 视角:`后续 PR`/`本 PR 新增`/`上一 commit` — 改为已落地的机制或扩展点;未做事项用 `TODO` 或 issue 引用,或收进 `## Deferred` 小节。
3. 变更叙事:`used to`/`不再`/`旧 X`/`this cut`/`now` — 改为现在时;回归用现在时反事实“若无 X 则 Y”。
4. 评审编排:`评审时否掉`/`reviewer 确认`/`v5` — 只留决定与理由,删谁说的、何时说的。
5. 自证正确:`这样转是安全的,因为…` — 改为使之安全的 invariant,或直接删(代码已自明)。
6. 过程复述:`先 X 再 Y`/`测试走读` — 删,只留非显然契约。
7. 含糊与占位:`应该够了`/`probably fine` — 升为 `TODO/FIXME` 或明确边界。
8. 语言串台:中英混杂的工作语言片段 — 翻译或删除。
**不算泄露(保留):** issue 引用 `#1470`/`TODO(name):`(裸 `TODO` 注意正文扫描,见上条豁免)、Agent Note 与 postmortem 内的已合并 PR 引用、suppression 理由、现在时反事实、带实测值的边界、运行时 old/new 状态、已提交文档的 `§` 编号。
## 删过头警示(overcorrection traps,来自 trim-cot-leakage)
删之前先把段落里的命题列全,再对照四个"删过头"的坑:
- 把必须/禁止的义务删成"可以这样"的背书——约束变可选。
- 把"计划中/考虑过"的假设删成已落地事实——proposed 当 implemented。
- 删掉一句真事实,只因为它读起来像过程叙述。
- 丢掉承重溯源:`实测:512 嵌套 ≈ 0.15s` 里的 `实测`、来源标注与编号删掉,结论就没根了。
@@ -0,0 +1,58 @@
# 按需阅读:语义自检(写完笔记后过一遍)
> 脚本管结构,这张清单管意思。写完后自检,只向用户报缺口和写得好的地方,不逐条背诵。
> 定位:这是给 Agent 的自检,不是给脚本的规则——下列检查点全部是语义判断,永不进 verify 脚本。
## 动手前:先自己查,再问用户
- [ ] 这个"问题"真的是决策吗?——能用 §3 检索四法(入口注释若有 / 分类树 / rg / 模块文档)自己查到的事实,不要抛给用户。Finding facts is your job; 只有取舍和拍板才占用用户时间。
## Problem
- [ ] 动机脱离方案也能独立成立——删掉 Decision 再读一遍,还是同一个问题吗?
- [ ] 触发清楚:什么破了、什么要变、不做会怎样。
## Decision / Proposal
- [ ] 具体到能行动,不是"用更好的数据库"而是"为会话存储用 SQLite"。
- [ ] 理由是被"vs"逼出来的——写"决定用 X"就补一句"X vs Y 为何选 X"。
## Alternatives considered
- [ ] ≥2 个真备选;不要编没权衡过的选项。「不做/复用」仅当当时真的考虑过才算一档,不是必填档。
- [ ] 每个被否项先写它最强的论据,再写为何否——只写弱处的拒绝是稻草人。
- [ ] 否掉的理由落到具体驱动条件,不是"经验上不行"。
## Consequences
- [ ] 代价和收益都写。自问"什么变难了?维护成本是什么?"——只有收益的后果是挑选过的。
- [ ] 简化注明已知上限与何时该重访。没有升级触发条件的简化会悄悄变永久。
- [ ] 没有基线就不写相对量词——"提升了/更快了"说不清基线时,降级为事实陈述。
## Verification / Testing(implemented)
- [ ] 落到可确认表面:哪条路径、什么量级、跑什么命令。
- [ ] 不写"看起来能用"——验收标准要么可勾选,要么明确留给后续。
## 汇报形态
写完自检后,这样汇报(一行一缺口,没缺口就收口):
```markdown
**语义自检:<filename>**
✅ 稳定:动机独立成立 / 有 2 个真备选 / 后果代价收益兼备
⚠️ 缺口:
- Alternatives — 有"做了 vs 不做"稻草人,补一个与现行方案平行的真实选项
- Consequences — "性能提升"要落到哪条路径、什么量级
建议:修以上 2 处后落盘 / 可接受缺口,直接放行
```
用户接受缺口即放行;不接受就修再落盘。意思上的判断不是脚本,别把它撑成另一道检查。
## 这套自检生效了吗(观测判据)
每隔一段时间回看,以下信号说明自检在起作用;信号消失说明它在空转:
- 你向用户提的问题里,**不再出现**翻一下笔记树或 rg 一下就能答的事实性问题。
- 汇报里的每条缺口都带着**具体修法**(改哪节、补什么),而不是"建议再完善"。
- `rejected/` 和 Alternatives 里被否掉的路线,**不再被新会话重新提出**——这正是整套系统存在的理由。
@@ -0,0 +1,26 @@
# 按需阅读:简化机会自检
> 提炼自 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的 `dsh-find-simplifications` skill。收尾或重构时扫一遍;别在功能改动里硬塞无关简化。
## 值得删/合/降级的信号
- 公开方法、事件、配置项、包、持久化事件或测试产物没有生产消费方(测试/文档是唯一消费方且行为非关键)。
- 两处表示同一事实(尤其是持久化事件与瞬态事件各存一份)。
- 某个能力的所有实现都必须实现某方法,但没有消费方在用它。
- 包只为测试/demo/支撑而存在,增加发布与依赖成本。
- 为“以后可能要”做的通用性:多会话、后台任务台账、年中转向、工具自带 UI 等,无当前归属。
- 为不存在的 API 准备的不变式、回滚、快照或特判。
- 手写了业界已有包或同版本 Node 已提供的能力,换掉能净删除实现与对应测试。
## 怎么证实
- 用 `rg` 搜符号/事件/配置键/包名,看生产代码(`packages/*/src`、`examples` 运行时、`loader/config` 路径)是否真在用。
- 区分生产/非生产/模糊语料——测试与文档里的出现不算生产证据;`knip` 可辅助但不能替代读调用点。
- 小而确定的清理用 `TODO/FIXME/XXX` 记下,别为此开一条 Note;只有 durable 的取舍才值得一条 proposed Note。
- Hand-rolled vs 依赖:看净删除(实现+测试+文档)、健康度、边界贴合度;能真删才换,包一层同样复杂度不算赢。
## 与 Notes 的衔接
- 符合信号且这个取舍需要留下来 → 写 `proposed/simplification` Note(Problem/Proposal/Alternatives/Acceptance/Risks)。
- 已落地的 simplification → `implemented/simplification`,Consequences 同时写删掉的成本与省下的负担。
- 触发 Note 树膨胀时,用 `archiving.md` 的“未来参考价值”判定是否归档,而非字数/年龄。
@@ -0,0 +1,44 @@
# 按需阅读:校验脚本
> SKILL §6 的展开。接入 CI 时对照;本地轻量使用时跳过。
## 检查脚本(均为 tsx,零新增依赖,可直接用 `node` 独立运行;Node 22.6+ 原生支持,无需 tsx 依赖)
1. **`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 链接有效性。
2. **`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 自动归一。
3. **`verify-archived`**(`scripts/verify-archived-agent-notes.ts`,标配)
- 每篇归档:头部布局逐行校验(L3 `Status: implemented` / L4 `Archived: 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`:先证明既有封印未变,再为未封印文件追加封印(历史语料补齐用这个)。
4. **`check-note-anchors`**(`scripts/check-note-anchors.ts`,软报告,退出码恒 0,**不进 CI**)
- 扫描源码(env `AGENT_NOTE_CODE_ROOT` 指定根,默认 cwd;自动跳过 node_modules/.git/dist 等)里的 `// Note:` / `# Note:` 物理锚点:报告悬空锚点、没有锚点指向的 implemented 笔记、缺路径的锚点行。宿主没用锚点就不必跑。
## 接入建议
- 轻量(个人/无 git):前两个脚本即可,归档封印在第一次归档后自然生效。
- 完整(团队):三条门禁串进 CI,失败即红(本 Skill 的 `templates/verify-notes.yml` 可作模板;Gitea 下改到 `.gitea/workflows/` 并把 `github.*` 变量换成 `gitea.*`)。
三个校验脚本方法上来自 [DeepSeek Harness](https://github.com/deepseek-ai/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 篇「通过」,制造假绿)。日常请直接用:
```sh
node .agents/scripts/verify-notes.ts # 自动遍历所有含 .agents/notes 的仓库
node .agents/scripts/verify-notes.ts lpt-be # 只查一个
node .agents/scripts/verify-notes.ts --changed # 只查有改动的
```
@@ -0,0 +1,83 @@
# 按需阅读:何时写、何时改与决策流转
> SKILL §4 的深度展开。每个重要改动或评审时对照一次。
## 核心心智:更新既有归属,严禁重复新建(Update the owning note)
DeepSeek 的公开演进历史(deepseek-ai/deepseek-harness 的 git 记录)里能看到同样的形态:Note 的新增很少,现有 Note 的**就地事实修正**占了绝大多数。
**不要把 Note 当做一次性发表的博客或流水账。它是与代码共存亡的「现行法律」。**
一篇 Note 永远不被改写成另一个决定:事实(路径、符号、默认值)就地改;决定或理由翻转 → 新开一篇并互链。禁止把 `## Decision` 改写成反面,禁止只靠 git 当旧理由的唯一副本。
---
## 1. 场景判定矩阵
| 场景 | 操作动作 | 典型范式 |
|---|---|---|
| **代码重构、改名、移包、改默认参数** | **原地更新现有 Note 事实** | Decision 核心理由不变;直接改路径、类名、默认值(不追加变更流水账)。理由变了就走新建,不走原地 |
| **写新 Note 之前** | **当场审计活跃笔记** | 按模块名/关键词搜 proposed + implemented + rejected;每篇命中当场分类(无关 / 部分重叠 / 完全吸收 / 过时提案),和这篇新 Note 一起落盘。禁止推迟到大扫除 |
| **提出全新的架构尝试或技术选型** | **新建 `proposed/`** | 动手编码前写清动机、真实考虑过的备选与验收指标 |
| **完成开发并准备合入主干** | **转为 `implemented/`** | 见 §3 改写清单;与代码同批落盘(git 场景即同一 commit/PR) |
| **方案被新决策部分取代** | **两篇都留、互链** | 只更新仍成立的事实。禁止归档 |
| **方案在评审中被否决** | **移入 `rejected/` 或删除** | 仅当其理由能避免未来重蹈覆辙时保留并写清原因;否则彻底删除 |
| **新架构完全取代了旧架构** | **先吸收,能删则删,否则归档** | 见 §4。指针写在新笔记里,不写进归档篇 |
| **版本封版打标、依赖小补丁、排版** | **免除(Not Applicable)** | 直接提交代码,无需任何 Note |
---
## 2. 原地同步法则(In-place Fact Sync)
当现有 Note 所守护的模块发生演进,但核心决策并未被推翻时:
1. **直接修改,不记流水账**:
- ❌ 错误:在文末追加 `### 2026-09-02 更新:类名重命名为 X`
- ✅ 正确:直接在正文中将旧类名替换为新类名,保证任何时候打开这篇 Note,它反映的都是 HEAD 分支的绝对事实。
2. **时态永保现在时**:
- 始终使用现在时(`系统使用 SQLite 作为持久化引擎`),严禁使用变更叙事(`系统不再使用 JSONL,现在使用 SQLite`)。门禁只拒提案标题,现在时靠这条纪律,不靠词法扫描。
---
## 3. proposed → implemented 改写清单
同一次改动里做完:
1. 移到 `implemented/<class>/`,文件名日期不动(首次提出日)
2. `Status: proposed` → `Status: implemented`
3. `## Proposal` → `## Decision`,改成现在时(已落地的事实)
4. `## Acceptance criteria` / `## Risks` 折进 `## Consequences`(或现在时 `## Testing` / `## Verification`)
5. 删计划段(`## Plan` / 迁移步骤 / 开放问题)
门禁靠骨架变化卡住:implemented 里残留 `## Proposal` 会失败。
---
## 4. 取代:部分重叠 vs 完全吸收
**部分重叠**:新方案只覆盖旧方案一部分 → 两篇都留,双方加相对链接;只更新仍成立的事实。禁止归档、禁止推迟。
**完全吸收**(旧方案被彻底淘汰):
1. **审计旧 Note 资产**:独有的安全边界、否定性保证、失败场景、重新引入条件、验证缺口。
2. **搬迁与吸收**:写入新 Note 的 `## Decision` / `## Alternatives considered` / `## Consequences`。
3. **旧 Note 二选一**:
- **删除**:新篇已写入旧篇全部独特内容,且入站链接已改完 → 物理删除,不进 `archived/`。
- **归档**:旧篇还有独立杠杆(否定性保证、所有权边界、重新引入条件)→ `archive-agent-note.ts`。只插 `Archived:` 一行;互链写在新笔记。
4. **修复入站链接**:把仍指向旧路径的相对链接改到新 Note(引历史快照时才指向 `archived/`)。
`--superseded-by` 只校验新笔记存在,并在新笔记末尾补一条指向归档路径的相对链接。
---
## 5. 可选:源码入口反向注释
宿主若已有此惯例,可在核心入口留一行:
```typescript
// Note: 会话持久化采用文件句柄管理,避免并发写冲突 — 见 .agents/notes/implemented/architecture/2026-08-27-handle-based-session-persistence.md
export class SessionFileHandlePool {
// ...
}
```
不是门禁。`check-note-anchors` 只做软报告,不进 CI。
@@ -0,0 +1,75 @@
/**
* Shared structural source of truth for the Agent Note tree.
* Portable: resolves .agents/notes from cwd (or AGENT_NOTE_ROOT env).
*/
import { readdirSync, existsSync } from 'node:fs'
import { resolve } from 'node:path'
/** Recurse `dir` and return posix-relative `.md` paths prefixed with `prefix`. Node 18 compatible (no fs.globSync). */
function listMd(dir: string, prefix: string): string[] {
if (!existsSync(dir)) return []
const out: string[] = []
for (const entry of readdirSync(dir, { withFileTypes: true })) {
if (entry.name.startsWith('.')) continue
const rel = prefix ? `${prefix}/${entry.name}` : entry.name
if (entry.isDirectory()) out.push(...listMd(resolve(dir, entry.name), rel))
else if (entry.isFile() && entry.name.endsWith('.md')) out.push(rel)
}
return out
}
function resolveAgentNoteRoot(): string {
if (process.env.AGENT_NOTE_ROOT) return resolve(process.env.AGENT_NOTE_ROOT)
return resolve(process.cwd(), '.agents/notes')
}
export const agentNoteRoot = resolveAgentNoteRoot()
const AGENT_NOTE_LIFECYCLES = ['proposed', 'implemented', 'rejected'] as const
export const AGENT_NOTE_CLASSES = ['feature', 'bug-fix', 'simplification', 'architecture', 'process', 'testing'] as const
const AGENT_NOTE_ARCHIVE = 'archived'
const ROOT_ALLOWLIST = new Set(['AGENTS.md', 'CLAUDE.md'])
export interface AgentNote {
lifecycle: string
rel: string
date: string
}
export function walkAgentNoteTree(): { notes: AgentNote[]; errors: string[] } {
const notes: AgentNote[] = []
const errors: string[] = []
if (!existsSync(agentNoteRoot)) return { notes, errors }
for (const entry of readdirSync(agentNoteRoot, { withFileTypes: true })) {
if (entry.name === 'INDEX.md') {
errors.push('structure: INDEX.md — centralized Agent Note indexes are forbidden; browse the lifecycle/class tree or search the repository')
continue
}
if (entry.isDirectory() && entry.name !== AGENT_NOTE_ARCHIVE && !(AGENT_NOTE_LIFECYCLES as readonly string[]).includes(entry.name)) {
errors.push(`structure: ${entry.name}/ — unknown lifecycle folder (allowed: ${AGENT_NOTE_LIFECYCLES.join(', ')}, plus ${AGENT_NOTE_ARCHIVE}/)`)
}
}
for (const lifecycle of AGENT_NOTE_LIFECYCLES) {
for (const match of listMd(resolve(agentNoteRoot, lifecycle), lifecycle).sort()) {
const segs = match.split('/')
if (segs.length === 2 && ROOT_ALLOWLIST.has(segs[1] ?? '')) continue
if (match.endsWith('.zh.md')) continue
const cls = segs[1]
const base = segs[2]
if (segs.length !== 3 || cls === undefined || base === undefined) {
errors.push(`structure: ${match} — expected {lifecycle}/{class}/file.md (got depth ${segs.length})`)
continue
}
if (!(AGENT_NOTE_CLASSES as readonly string[]).includes(cls)) {
errors.push(`structure: ${match} — unknown class folder "${cls}" (allowed: ${AGENT_NOTE_CLASSES.join(', ')})`)
continue
}
if (!/^\d{4}-\d{2}-\d{2}-.+\.md$/.test(base)) {
errors.push(`structure: ${match} — filename must be yyyy-mm-dd-topic.md`)
continue
}
notes.push({ lifecycle, rel: match, date: base.slice(0, 10) })
}
}
return { notes, errors }
}
@@ -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})`);
}
}
@@ -0,0 +1,235 @@
#!/usr/bin/env node
import { readFileSync, writeFileSync, readdirSync, existsSync } from 'node:fs';
import { join, resolve, relative, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
const templatePath = resolve(__dirname, '../assets/agent-notes-board.html');
const args = process.argv.slice(2);
if (!existsSync(templatePath)) {
console.error(`❌ Template not found at: ${templatePath}`);
process.exit(1);
}
// 检查参数
const isInitMode = args.includes('--init');
const isForce = args.includes('--force') || args.includes('-f');
const isMetadataOnly = args.includes('--metadata-only');
const cleanArgs = args.filter((a: string) => !a.startsWith('--') && !a.startsWith('-'));
function checkTargetSafety(targetPath: string) {
if (existsSync(targetPath) && !isForce) {
try {
const existing = readFileSync(targetPath, 'utf8');
const isBoard = existing.includes('generator" content="agent-notes-board"') || existing.includes('id="brand-project-title"');
if (!isBoard) {
console.error(`❌ 错误:目标文件已存在 (${targetPath}) 且并非看板生成文件!`);
console.error(`💡 为防止意外覆盖已有项目页面(如 Vite/React/Vue 项目的 index.html),请指定其他输出路径或传入 --force 确认覆盖。`);
process.exit(1);
}
} catch {}
}
}
if (isInitMode) {
const targetPath = cleanArgs[0] ? resolve(cleanArgs[0]) : resolve(process.cwd(), 'board.html');
const projectName = cleanArgs[1] || '工程决策看板';
checkTargetSafety(targetPath);
let template = readFileSync(templatePath, 'utf8');
template = template.replace('id="brand-project-title">工程决策看板<', () => `id="brand-project-title">${projectName}<`);
writeFileSync(targetPath, template, 'utf8');
console.log(`✅ [日常开发模式] 轻量看板已生成 (仅 ~69KB): ${targetPath}`);
console.log(`💡 用浏览器打开后,点击右上角「连接本地目录」选择 .agents/notes,后续新建/修改笔记切回浏览器即可自动热刷新!`);
process.exit(0);
}
// 打包模式(生成内联完整数据的单文件,如 demo.html)
const notesDir = cleanArgs[0] ? resolve(cleanArgs[0]) : resolve(process.cwd(), '.agents/notes');
const outputPath = cleanArgs[1] ? resolve(cleanArgs[1]) : resolve(process.cwd(), 'demo.html');
const projectName = cleanArgs[2] || '工程决策看板';
checkTargetSafety(outputPath);
const LIFECYCLES = ['implemented', 'proposed', 'rejected', 'archived'];
if (!existsSync(notesDir)) {
console.error(`❌ Notes directory not found at: ${notesDir}`);
process.exit(1);
}
/** Blank out fenced code-block lines so `## ` headings and [](.md) links inside them are never parsed as note structure. */
function stripFencedBlocks(raw: string): string {
let inFence = false;
return raw
.replace(/\r\n?/g, "\n")
.split("\n")
.map((l) => {
if (/^\s{0,3}```/.test(l)) {
inFence = !inFence;
return "";
}
return inFence ? "" : l;
})
.join("\n");
}
function parseNoteContent(raw: string, relPath: string, slugToId: Map<string, string>) {
const parseable = stripFencedBlocks(raw);
const slug = relPath.split('/').pop()!.replace(/\.md$/, '');
const parts = relPath.split('/');
const lifecycle = parts[0];
const cls = parts[1] || 'architecture';
let title = slug;
let status = lifecycle;
let date = '';
const dMatch = /^(\d{4}-\d{2}-\d{2})/.exec(slug);
if (dMatch) date = dMatch[1];
const h1Match = /^# Agent Note[^::]*[::]\s*(.*)$/m.exec(parseable);
if (h1Match) title = h1Match[1].trim();
function extractSection(secNamePattern: string) {
const re = new RegExp(`^## (?:${secNamePattern})\\s*\\n+([\\s\\S]*?)(?=^## |(?![\\s\\S]))`, 'm');
const m = re.exec(parseable);
return m ? m[1].trim() : '';
}
const problem = extractSection('Problem|问题');
const decision = extractSection('Decision|Proposal|决策|提案');
const alternatives = extractSection('Alternatives considered|曾考虑的替代方案|曾考虑的备选');
const consequences = extractSection('Consequences|后果');
const links: string[] = [];
for (const m of parseable.matchAll(/\]\(([^)]+\.md)\)/g)) {
let targetHref = m[1].split('#')[0].trim();
if (targetHref.includes('://')) continue;
targetHref = targetHref.replace(/\.zh\.md$/, '.md');
const segs = `${lifecycle}/${cls}/${targetHref}`.split('/');
const resolved: string[] = [];
for (const s of segs) {
if (!s || s === '.') continue;
if (s === '..') resolved.pop();
else resolved.push(s);
}
const cleanTarget = resolved.join('/');
let finalTarget = '';
if (slugToId.has(cleanTarget)) {
finalTarget = slugToId.get(cleanTarget)!;
} else {
const targetSlug = targetHref.split('/').pop()!.replace(/\.md$/, '');
if (slugToId.has(targetSlug)) {
finalTarget = slugToId.get(targetSlug)!;
}
}
if (finalTarget && finalTarget !== relPath) {
links.push(finalTarget);
}
}
return {
id: relPath,
slug,
lifecycle,
cls,
date,
title,
status,
problem,
decision,
alternatives,
consequences,
outLinks: [...new Set(links)],
rawBody: raw,
};
}
function walk(dir: string, baseDir: string = dir): any[] {
const noteFiles = new Map<string, string>(); // relPath -> fullPath
function scan(currentDir: string) {
const items = readdirSync(currentDir, { withFileTypes: true });
for (const entry of items) {
if (entry.name.startsWith('.')) continue;
const fullPath = join(currentDir, entry.name);
if (entry.isDirectory()) {
scan(fullPath);
} else if (entry.isFile() && entry.name.endsWith('.md')) {
const isZh = entry.name.endsWith('.zh.md');
const relPath = relative(baseDir, fullPath).replace(/\\/g, '/');
const cleanRel = isZh ? relPath.replace(/\.zh\.md$/, '.md') : relPath;
const parts = cleanRel.split('/');
if (parts.length >= 3 && LIFECYCLES.includes(parts[0])) {
if (!noteFiles.has(cleanRel) || isZh) {
noteFiles.set(cleanRel, fullPath);
}
}
}
}
}
scan(dir);
const slugToId = new Map<string, string>();
for (const relPath of noteFiles.keys()) {
const slug = relPath.split('/').pop()!.replace(/\.md$/, '');
slugToId.set(slug, relPath);
slugToId.set(relPath, relPath);
}
const results: any[] = [];
for (const [relPath, fullPath] of noteFiles.entries()) {
try {
const raw = readFileSync(fullPath, 'utf8');
results.push(parseNoteContent(raw, relPath, slugToId));
} catch (err) {
console.warn(`⚠️ Error reading ${relPath}:`, err);
}
}
return results;
}
console.log(`🔍 [打包模式] 正在扫描笔记目录: ${notesDir}`);
const notes = walk(notesDir);
console.log(`✅ 解析完成,共发现 ${notes.length} 篇有效 Agent Notes。`);
if (isMetadataOnly) {
console.log('🔒 [安全脱敏] 启用 --metadata-only 模式,已剥离所有笔记的具体正文和详细论证,仅保留决策元数据与关联拓扑。');
for (const n of notes) {
n.problem = '[正文已脱敏]';
n.decision = '[正文已脱敏]';
n.alternatives = '';
n.consequences = '';
n.rawBody = `# Agent Note: ${n.title}\n\nStatus: ${n.status}\n\n<!-- content redacted for public demo -->`;
}
} else {
console.log('⚠️ [安全提示] 正在生成包含完整正文的数据包。如需对外公开发布且避免泄露内部决策细节,请添加 --metadata-only 参数。');
}
let template = readFileSync(templatePath, 'utf8');
// 注入项目名
template = template.replace('id="brand-project-title">工程决策看板<', () => `id="brand-project-title">${projectName}<`);
// 注入数据
const jsonSafe = JSON.stringify(notes).replace(/</g, '\\u003c');
template = template.replace(
'window.__INLINE_DATA__ = null;',
() => `window.__INLINE_DATA__ = ${jsonSafe};`
);
writeFileSync(outputPath, template, 'utf8');
console.log(`🎉 [打包完成] 看板已生成: ${outputPath}`);
console.log(`💡 该文件内置了 ${notes.length} 篇笔记数据,可脱机分发、离线演示或部署至 GitHub Pages。`);
@@ -0,0 +1,103 @@
/**
* Soft report: physical reverse anchors (`// Note: ... 见 .agents/notes/...`).
* A. anchors in source code pointing at notes that do not exist (dangling)
* B. implemented notes with zero inbound code anchors (suspected missing anchor)
* Exit code is always 0 — this is an advisory report, not a gate.
* Env: AGENT_NOTE_CODE_ROOT (default: cwd) — source root to scan.
* Run: node <skill-dir>/scripts/check-note-anchors.ts
*/
import { existsSync, readFileSync, readdirSync } from "node:fs";
import { join, resolve } from "node:path";
import { agentNoteRoot, walkAgentNoteTree } from "./agent-note-tree.ts";
const codeRoot = resolve(process.env.AGENT_NOTE_CODE_ROOT || process.cwd());
const CODE_EXT = new Set([
".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
".py", ".go", ".rs", ".java", ".kt", ".c", ".cc", ".cpp", ".h", ".hpp",
".cs", ".rb", ".swift", ".vue", ".svelte", ".php",
]);
const SKIP_DIR = new Set([
"node_modules", ".git", "dist", "build", "out", "coverage", ".next",
".cache", ".agents", "vendor", "target",
]);
const ANCHOR_RE = /(?:\/\/|#|\/\*|\*\s*|<!--\s*)\s*Note[::]/;
const PATH_RE = /\.agents\/notes\/([^\s'"`)>]+?\.md)/;
const anchorHits = new Map<string, string[]>(); // note rel (from notes root, lowercased basename fallback) -> [code rel:line]
const dangling: string[] = [];
const notePathRefs: string[] = [];
function walk(dir: string, depth: number) {
if (depth > 12) return;
let entries;
try {
entries = readdirSync(dir, { withFileTypes: true });
} catch {
return;
}
for (const entry of entries) {
if (entry.name.startsWith(".") && entry.name !== ".agents") continue;
const full = join(dir, entry.name);
if (entry.isDirectory()) {
if (!SKIP_DIR.has(entry.name)) walk(full, depth + 1);
continue;
}
const dot = entry.name.lastIndexOf(".");
if (dot === -1 || !CODE_EXT.has(entry.name.slice(dot))) continue;
const rel = full.slice(codeRoot.length + 1);
const lines = readFileSync(full, "utf8").replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n").split("\n");
for (let i = 0; i < lines.length; i++) {
const l = lines[i];
if (!ANCHOR_RE.test(l)) continue;
const m = PATH_RE.exec(l);
if (!m) {
notePathRefs.push(`${rel}:${i + 1} — Note anchor without a .agents/notes path`);
continue;
}
const noteRel = m[1].split("#")[0].replace(/^\.\//, "");
const key = noteRel.replace(/\\/g, "/");
const list = anchorHits.get(key) ?? [];
list.push(`${rel}:${i + 1}`);
anchorHits.set(key, list);
if (!existsSync(join(agentNoteRoot, key))) {
dangling.push(`${rel}:${i + 1} — .agents/notes/${key} does not exist`);
}
}
}
}
walk(codeRoot, 0);
// implemented notes with zero inbound anchors
const { notes } = walkAgentNoteTree();
const implemented = notes.filter((n) => n.lifecycle === "implemented");
// basename -> note count: a slug shared by several notes is ambiguous and
// must not let one note's anchor count for another.
const slugCount = new Map<string, number>();
for (const n of notes) {
const slug = n.rel.split("/").pop()!;
slugCount.set(slug, (slugCount.get(slug) ?? 0) + 1);
}
const unanchored: string[] = [];
for (const n of implemented) {
const slug = n.rel.split("/").pop()!;
const direct = anchorHits.get(n.rel) ?? anchorHits.get(n.rel.replace(/\\/g, "/"));
const bySlug = [...anchorHits.keys()].filter((k) => k === slug || k.endsWith("/" + slug));
if (!direct && (bySlug.length === 0 || (slugCount.get(slug) ?? 0) > 1)) unanchored.push(n.rel);
}
console.log(`scanned: ${codeRoot}`);
console.log(`anchors found: ${[...anchorHits.values()].reduce((a, b) => a + b.length, 0)} across ${anchorHits.size} note(s)`);
if (notePathRefs.length) {
console.log(`\n[anchors without note path] ${notePathRefs.length}`);
for (const r of notePathRefs.slice(0, 20)) console.log(` - ${r}`);
}
if (dangling.length) {
console.log(`\n[dangling anchors] ${dangling.length}`);
for (const d of dangling.slice(0, 20)) console.log(` - ${d}`);
} else {
console.log("\n[dangling anchors] none");
}
console.log(`\n[implemented notes without any code anchor] ${unanchored.length} of ${implemented.length}`);
for (const u of unanchored.slice(0, 20)) console.log(` - ${u}`);
if (unanchored.length > 20) console.log(` ... and ${unanchored.length - 20} more`);
@@ -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`);
@@ -0,0 +1,56 @@
/**
* Verify tree: lifecycle/class/filename/INDEX and internal relative markdown links.
* Run: node <skill-dir>/scripts/verify-agent-note-tree.ts
*/
import { existsSync, readFileSync } from "node:fs";
import { dirname, resolve, sep } from "node:path";
import { agentNoteRoot, walkAgentNoteTree } from "./agent-note-tree.ts";
const { notes, errors } = walkAgentNoteTree();
// Check relative markdown links inside active notes
const LINK_REGEX = /\[([^\]]+)\]\(([^)]+)\)/g;
for (const note of notes) {
const noteFullPath = resolve(agentNoteRoot, note.rel);
const content = readFileSync(noteFullPath, "utf8");
let match: RegExpExecArray | null;
while ((match = LINK_REGEX.exec(content)) !== null) {
let rawTarget = match[2]?.trim();
if (!rawTarget) continue;
// Support CommonMark angle bracket destinations: [text](<path>)
if (rawTarget.startsWith("<") && rawTarget.endsWith(">")) {
rawTarget = rawTarget.slice(1, -1).trim();
}
// Ignore web links, intra-page anchors and ellipsis placeholders
if (rawTarget.startsWith("http://") || rawTarget.startsWith("https://") || rawTarget.startsWith("#") || rawTarget.startsWith("mailto:") || rawTarget.includes("…")) {
continue;
}
// Strip anchor fragment if present
const fileTarget = rawTarget.split("#")[0];
if (!fileTarget) continue;
const resolvedTarget = resolve(dirname(noteFullPath), fileTarget);
// Only verify internal links within agentNoteRoot (boundary-aware: a
// sibling like .agents/notes-backup/ must not prefix-match)
if (!resolvedTarget.startsWith(agentNoteRoot + sep)) {
continue;
}
if (!existsSync(resolvedTarget)) {
errors.push(`link: ${note.rel} -> "${rawTarget}" target file does not exist`);
}
}
}
if (errors.length) {
for (const e of errors) console.error(e);
process.exit(1);
}
console.log(`ok: ${notes.length} note(s) tree and relative links verified`);
@@ -0,0 +1,127 @@
/**
* Verify frozen archived Agent Notes: exact head layout, manifest.json seals,
* append-only extension vs a git baseline (skipped gracefully without git).
* Usage:
* node <skill-dir>/scripts/verify-archived-agent-notes.ts # verify only
* node <skill-dir>/scripts/verify-archived-agent-notes.ts --write # verify, then seal unsealed files
* Env: AGENT_NOTE_ARCHIVE_BASE_REF (default HEAD) — git ref the manifest is compared against.
*/
import { createHash } from "node:crypto";
import { execFileSync } from "node:child_process";
import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
import { join, relative } from "node:path";
import { agentNoteRoot } from "./agent-note-tree.ts";
const isWrite = process.argv.includes("--write");
const errors: string[] = [];
const warnings: string[] = [];
const fail = (msg: string) => { errors.push(msg); };
// --- collect archived files (skip accidental .zh.md)
const archivedDir = join(agentNoteRoot, "archived");
const files: string[] = [];
function scan(dir: string) {
for (const entry of readdirSync(dir, { withFileTypes: true })) {
if (entry.name.startsWith(".")) continue;
const full = join(dir, entry.name);
if (entry.isDirectory()) scan(full);
else if (entry.isFile() && entry.name.endsWith(".md") && !entry.name.endsWith(".zh.md")) {
const rel = relative(archivedDir, full).split("\\").join("/");
if (rel === "AGENTS.md" || rel === "manifest.json") continue;
files.push(rel);
}
}
}
if (existsSync(archivedDir)) scan(archivedDir);
// --- head layout: L1 title / L2 blank / L3 Status / L4 Archived / L5 blank
const TITLE_RE = /^# Agent Note[::] ?\S/;
const ARCHIVED_RE = /^Archived: \d{4}-\d{2}-\d{2}$/;
for (const rel of files) {
const lines = readFileSync(join(archivedDir, rel), "utf8").replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n").split("\n");
if (!TITLE_RE.test(lines[0] ?? "")) fail(`${rel} — line 1 must be \`# Agent Note: <title>\``);
if (lines[1] !== "") fail(`${rel} — line 2 must be blank`);
if (lines[2] !== "Status: implemented") fail(`${rel} — line 3 must be \`Status: implemented\``);
if (!ARCHIVED_RE.test(lines[3] ?? "")) fail(`${rel} — line 4 must be \`Archived: YYYY-MM-DD\` immediately below Status`);
if (lines[4] !== "") fail(`${rel} — line 5 must be blank after Archived`);
}
// --- manifest seals
const manifestPath = join(archivedDir, "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 {
fail("archived/manifest.json exists but is not valid JSON");
}
} else if (files.length > 0 && !isWrite) {
fail("archived/manifest.json missing — run with --write to seal existing archived notes");
}
const sealOf = (relFromRoot: string) =>
`sha256:${createHash("sha256").update(readFileSync(join(agentNoteRoot, relFromRoot))).digest("hex")}`;
for (const rel of files) {
const key = `archived/${rel}`;
const entry = manifest.files[key];
if (!entry) {
if (isWrite) {
manifest.files[key] = sealOf(key);
} else {
fail(`${key} — missing seal in manifest.json (run with --write)`);
}
} else if (entry !== sealOf(key)) {
fail(`${key} — seal mismatch: archived note was modified after sealing (frozen notes must never change)`);
}
}
for (const key of Object.keys(manifest.files)) {
if (!existsSync(join(agentNoteRoot, key))) fail(`${key} — sealed entry has no file on disk`);
}
// --- append-only vs git baseline (skipped without git)
const repoRoot = (() => {
try {
return execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd: agentNoteRoot, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
} catch {
return null;
}
})();
if (repoRoot) {
const baseRef = process.env.AGENT_NOTE_ARCHIVE_BASE_REF || "HEAD";
const manifestRel = relative(repoRoot, manifestPath).split("\\").join("/");
let baselineRaw: string | null = null;
try {
baselineRaw = execFileSync("git", ["show", `${baseRef}:${manifestRel}`], { cwd: repoRoot, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
} catch {
// manifest absent at baseline — nothing to compare
}
if (baselineRaw !== null) {
try {
const baseline = JSON.parse(baselineRaw) as Manifest;
for (const [key, seal] of Object.entries(baseline.files ?? {})) {
if (manifest.files[key] !== seal) {
fail(`${key} — seal added/changed/removed relative to ${baseRef}; archived seals are append-only`);
}
}
} catch {
fail(`archived/manifest.json at ${baseRef} was not valid JSON`);
}
}
} else {
warnings.push("not a git repository — append-only check skipped (seal hashes still verified against disk)");
}
if (errors.length) {
for (const e of errors) console.error(`archived: ${e}`);
process.exit(1);
}
if (isWrite) {
const sorted = Object.fromEntries(Object.entries(manifest.files).sort(([a], [b]) => a.localeCompare(b)));
writeFileSync(manifestPath, JSON.stringify({ version: 1, files: sorted }, null, 2) + "\n", "utf8");
}
for (const w of warnings) console.warn(`warning: ${w}`);
console.log(`ok: ${files.length} archived note(s) verified, ${Object.keys(manifest.files).length} seal(s) in manifest`);
@@ -0,0 +1,32 @@
# Agent Note: <标题>
Status: implemented
<!--
【维护提醒】
1. 现行法律契约:代码重构、改名或路径变更时,同批就地更新事实。禁止把 Decision 改写成另一个决定。
2. 时态纪律:严禁 ## Proposal / ## Plan / ## Acceptance criteria 等计划态标题;Decision 用现在时(门禁只拒标题)。
3. 归档契约:只插 Archived: YYYY-MM-DD 紧邻 Status: implemented。互链写在新笔记,不写进归档篇。
-->
## Problem
<动机:脱离方案也能独立成立。说明触发原因:什么破了、什么要变、不做会怎样>
## Decision
<已落地事实,全篇使用现在时描述。可插入 Package 拓扑 / 契约 / Schema 等业务自由小节>
## Alternatives considered
- **<备选 A>** — <先写其最强论据,再写为何被否>
- **<备选 B>** — <先写其最强论据,再写为何被否。不做/复用仅当当时真的权衡过才写,不要编>
## Consequences
- **收益**:<带来了什么确定性提升,无基线不写相对量词>
- **代价与已知上限**:<牺牲了什么,什么信号发生时必须重访该决定>
## Verification
<可选,现在时事实:如何证明该决定在当前代码库中依然生效。落到可确认表面——路径、量级、执行命令>
@@ -0,0 +1,38 @@
# Agent Note: <标题>
Status: proposed
<!--
【维护提醒】
1. 落地转 implemented 时的重写契约:## Proposal 改为现在时的 ## Decision;
## Acceptance criteria / ## Risks 折进 ## Consequences(或现在时的 ## Testing / ## Verification)。
2. 前提消失或不再推进 → 转 Status: rejected — <原因>,严禁归档 proposed。
3. Alternatives 必填:只记录真实考虑过的对手方案;「不做/复用」仅当当时真的权衡过才写。
-->
## Problem
<动机,脱离方案也能独立成立;写清背景、约束与失败条件>
## Proposal
<拟议改动,可用将来时;含关键设计、迁移步骤与开放问题>
## Alternatives considered
必填。只写当时真的权衡过的选项(没有过的不要编)。「不做 / 复用现状」可以是其中一档,但不是必填档。
每档一个候选,或 `### Why not <X>?` 子节:
- **<备选 A>** — <为何没选,先写它的最强论据再写否掉理由,一段一备选>
- **<备选 B>** — <同上>
需要结构化对比多个选项时,用标准 × 选项矩阵(Fit / 运维复杂度 / 团队技能 / 成本 / 锁定风险 / 实施时间)逐格打 ✓/⚠️/✗。被否项必带"为何否"。
## Acceptance criteria
<什么可观察状态算完成;含验证表面与门禁>
## Risks
<可能出什么问题、已知取舍与回滚条件>
@@ -0,0 +1,27 @@
# Agent Note: <标题>
Status: rejected — <一句话原因>
<!--
【维护提醒】
1. 冻结不动:不改写为对立面,不随代码演进更新事实;结论就在 Status 行。
2. 仅在"防止重犯"期间保留:被否方案依赖的旧技术/API 已彻底移除、后人绝无可能
再提时,把这一篇删掉。
3. 价值被新笔记吸收时,按 references/archiving.md 的合并删除流程处理。
-->
## Problem
<动机>
## Proposal
<曾拟议的方案,冻结保留>
## Alternatives considered
- **<备选>** — <为何当时考虑/为何最终否掉>
## Risks
<为何否掉、若重提需满足什么条件>
@@ -0,0 +1,40 @@
# 复制到宿主仓库的 workflow 目录后启用:
# GitHub → .github/workflows/verify-notes.yml
# Gitea → .gitea/workflows/verify-notes.yml(并把 github.* 换成 gitea.*)
# 默认项目级安装路径;使用其他路径时请同步修改下方命令。
name: Verify Agent Notes
on:
push:
branches:
- main
pull_request:
permissions:
contents: read
jobs:
verify:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: 24
- name: Verify note tree, format, and archive seals
env:
# HEAD is a no-op on a clean checkout. Compare against the pre-change
# commit: PR base, or the previous tip of the pushed branch.
# A new-branch push sends before=0000…; git show fails and the script
# skips append-only (seal-vs-disk still runs).
AGENT_NOTE_ARCHIVE_BASE_REF: ${{ github.event.pull_request.base.sha || github.event.before }}
run: |
node .agents/skills/write-notes-like-deepseek/scripts/verify-agent-note-tree.ts
node .agents/skills/write-notes-like-deepseek/scripts/verify-agent-note-format.ts
node .agents/skills/write-notes-like-deepseek/scripts/verify-archived-agent-notes.ts