docs: 共有技能收归 meta 单一份并加工作区级笔记校验入口
- write-notes-like-deepseek 从三个子仓库的重复副本改为 meta 唯一副本 - 新增 .agents/scripts/verify-notes.ts,从 meta 视角一次校验四个笔记根 - workspace-layout 补「共有技能单一来源」的落位与理由 - .rgignore 排除 archived 历史快照
This commit is contained in:
+11
-7
@@ -15,18 +15,22 @@
|
|||||||
| 项目专属规则 | 各仓库自己的 `.agents/roles/` | 后端的迁移规范、前端的代码标准 |
|
| 项目专属规则 | 各仓库自己的 `.agents/roles/` | 后端的迁移规范、前端的代码标准 |
|
||||||
| 项目知识与架构约定 | 各仓库 `AGENTS.md` | 端口、调用关系、命名约定 |
|
| 项目知识与架构约定 | 各仓库 `AGENTS.md` | 端口、调用关系、命名约定 |
|
||||||
| 跨仓库待办与验收标准 | `OPTIMIZATION_BACKLOG.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` |
|
| 项目专属技能 | 各仓库自己的 `.agents/skills/` | `lpt-be/.agents/skills/comment-cleanup` |
|
||||||
|
|
||||||
|
> 共有技能**只在 meta 放一份**,子项目内不建副本、不建符号链接;理由与验收见 `.agents/roles/workspace-layout.md`。
|
||||||
|
|
||||||
## 生效方式(重要)
|
## 生效方式(重要)
|
||||||
|
|
||||||
**`.agents/roles/` 不是自动加载入口。** 规则要真正约束行为,必须在 `AGENTS.md` 里被引用——
|
**`.agents/roles/` 不是自动加载入口,任何 harness 都不会扫描它。** 规则要真正约束行为,必须在 `AGENTS.md` 里被引用——
|
||||||
`AGENTS.md` 是每次会话自动加载的项目指令入口,只有它(和按描述触发的 skills)会被读到。
|
`AGENTS.md` 是各 harness 通用的项目指令入口(Claude 体系另有 `CLAUDE.md`),只有它会被读到。
|
||||||
所以:新增规则时,务必同时在 `AGENTS.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 的子仓库索引带出。
|
||||||
|
|
||||||
## 规则文件的写法(强制)
|
## 规则文件的写法(强制)
|
||||||
|
|
||||||
|
|||||||
@@ -14,11 +14,55 @@
|
|||||||
|
|
||||||
### meta 仓库的维护边界
|
### meta 仓库的维护边界
|
||||||
|
|
||||||
- 本 meta 仓库只维护 `AGENTS.md`、`.gitignore`、`.agents/`(代理技能与通用规则)和 `docs/diagrams/`(图表评审产物),不要在本仓库根目录创建业务代码或系统文档。
|
- 本 meta 仓库只维护 `AGENTS.md`、`.gitignore`、`.agents/`(代理技能、通用规则、校验脚本、跨仓库笔记)和 `docs/diagrams/`(图表评审产物),不要在本仓库根目录创建业务代码或系统文档。
|
||||||
- `.gitignore` 忽略所有子项目目录,只放行上述根级条目,避免把独立 Git 仓库提交进本 meta 仓库。
|
- `.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/`。
|
规则和技能都收在 `.agents/` 下,不要放在仓库根目录的 `roles/`、`skills/`。
|
||||||
- 项目专属规则 → 该仓库自己的 `roles/`。
|
|
||||||
- 工作区级技能 → `.agents/skills/<技能名>/`;子项目专属技能 → 该仓库 `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` 的子仓库索引(只写路径 + 触发场景,不复制正文);索引里的路径必须真实存在。共有技能不登记进子仓库索引。
|
||||||
|
|||||||
@@ -0,0 +1,4 @@
|
|||||||
|
{
|
||||||
|
"type": "module",
|
||||||
|
"private": true
|
||||||
|
}
|
||||||
@@ -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
|
||||||
Reference in New Issue
Block a user