From f99e1e156d6ed924a88191189a6834fc30eac83d Mon Sep 17 00:00:00 2001 From: cat-shark Date: Wed, 18 Nov 2026 14:59:45 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=85=B1=E6=9C=89=E6=8A=80=E8=83=BD?= =?UTF-8?q?=E6=94=B6=E5=BD=92=20meta=20=E5=8D=95=E4=B8=80=E4=BB=BD?= =?UTF-8?q?=E5=B9=B6=E5=8A=A0=E5=B7=A5=E4=BD=9C=E5=8C=BA=E7=BA=A7=E7=AC=94?= =?UTF-8?q?=E8=AE=B0=E6=A0=A1=E9=AA=8C=E5=85=A5=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - write-notes-like-deepseek 从三个子仓库的重复副本改为 meta 唯一副本 - 新增 .agents/scripts/verify-notes.ts,从 meta 视角一次校验四个笔记根 - workspace-layout 补「共有技能单一来源」的落位与理由 - .rgignore 排除 archived 历史快照 --- .agents/roles/README.md | 18 +- .agents/roles/workspace-layout.md | 52 +- .agents/scripts/package.json | 4 + .agents/scripts/verify-notes.ts | 161 ++ .../skills/write-notes-like-deepseek/SKILL.md | 227 +++ .../assets/agent-notes-board.html | 1779 +++++++++++++++++ .../write-notes-like-deepseek/package.json | 4 + .../references/archiving.md | 109 + .../references/classification.md | 33 + .../references/note-format.md | 69 + .../references/prose-checklist.md | 51 + .../references/quality-gate.md | 58 + .../references/simplification-checklist.md | 26 + .../references/verification.md | 44 + .../references/when-to-write.md | 83 + .../scripts/agent-note-tree.ts | 75 + .../scripts/archive-agent-note.ts | 167 ++ .../scripts/build-board.ts | 235 +++ .../scripts/check-note-anchors.ts | 103 + .../scripts/verify-agent-note-format.ts | 158 ++ .../scripts/verify-agent-note-tree.ts | 56 + .../scripts/verify-archived-agent-notes.ts | 127 ++ .../templates/implemented.md | 32 + .../templates/proposed.md | 38 + .../templates/rejected.md | 27 + .../templates/verify-notes.yml | 40 + .rgignore | 2 + 27 files changed, 3767 insertions(+), 11 deletions(-) create mode 100644 .agents/scripts/package.json create mode 100644 .agents/scripts/verify-notes.ts create mode 100644 .agents/skills/write-notes-like-deepseek/SKILL.md create mode 100644 .agents/skills/write-notes-like-deepseek/assets/agent-notes-board.html create mode 100644 .agents/skills/write-notes-like-deepseek/package.json create mode 100644 .agents/skills/write-notes-like-deepseek/references/archiving.md create mode 100644 .agents/skills/write-notes-like-deepseek/references/classification.md create mode 100644 .agents/skills/write-notes-like-deepseek/references/note-format.md create mode 100644 .agents/skills/write-notes-like-deepseek/references/prose-checklist.md create mode 100644 .agents/skills/write-notes-like-deepseek/references/quality-gate.md create mode 100644 .agents/skills/write-notes-like-deepseek/references/simplification-checklist.md create mode 100644 .agents/skills/write-notes-like-deepseek/references/verification.md create mode 100644 .agents/skills/write-notes-like-deepseek/references/when-to-write.md create mode 100644 .agents/skills/write-notes-like-deepseek/scripts/agent-note-tree.ts create mode 100644 .agents/skills/write-notes-like-deepseek/scripts/archive-agent-note.ts create mode 100644 .agents/skills/write-notes-like-deepseek/scripts/build-board.ts create mode 100644 .agents/skills/write-notes-like-deepseek/scripts/check-note-anchors.ts create mode 100644 .agents/skills/write-notes-like-deepseek/scripts/verify-agent-note-format.ts create mode 100644 .agents/skills/write-notes-like-deepseek/scripts/verify-agent-note-tree.ts create mode 100644 .agents/skills/write-notes-like-deepseek/scripts/verify-archived-agent-notes.ts create mode 100644 .agents/skills/write-notes-like-deepseek/templates/implemented.md create mode 100644 .agents/skills/write-notes-like-deepseek/templates/proposed.md create mode 100644 .agents/skills/write-notes-like-deepseek/templates/rejected.md create mode 100644 .agents/skills/write-notes-like-deepseek/templates/verify-notes.yml create mode 100644 .rgignore diff --git a/.agents/roles/README.md b/.agents/roles/README.md index 9aa6dff..9100cb6 100644 --- a/.agents/roles/README.md +++ b/.agents/roles/README.md @@ -15,18 +15,22 @@ | 项目专属规则 | 各仓库自己的 `.agents/roles/` | 后端的迁移规范、前端的代码标准 | | 项目知识与架构约定 | 各仓库 `AGENTS.md` | 端口、调用关系、命名约定 | | 跨仓库待办与验收标准 | `OPTIMIZATION_BACKLOG.md` | 优化条目 | -| 工作区级技能 | `.agents/skills/` | `mermaid-diagram` | +| 工作区级技能(共有技能唯一来源) | meta `.agents/skills/` | `mermaid-diagram`、`write-notes-like-deepseek` | | 项目专属技能 | 各仓库自己的 `.agents/skills/` | `lpt-be/.agents/skills/comment-cleanup` | +> 共有技能**只在 meta 放一份**,子项目内不建副本、不建符号链接;理由与验收见 `.agents/roles/workspace-layout.md`。 + ## 生效方式(重要) -**`.agents/roles/` 不是自动加载入口。** 规则要真正约束行为,必须在 `AGENTS.md` 里被引用—— -`AGENTS.md` 是每次会话自动加载的项目指令入口,只有它(和按描述触发的 skills)会被读到。 -所以:新增规则时,务必同时在 `AGENTS.md` 对应章节挂上入口。 +**`.agents/roles/` 不是自动加载入口,任何 harness 都不会扫描它。** 规则要真正约束行为,必须在 `AGENTS.md` 里被引用—— +`AGENTS.md` 是各 harness 通用的项目指令入口(Claude 体系另有 `CLAUDE.md`),只有它会被读到。 +所以:新增规则时,务必同时在该仓库 `AGENTS.md` 挂上入口,并在 meta `AGENTS.md` 的子仓库索引里登记路径与触发场景。 -配套事实:pi 加载 `AGENTS.md` 时会同时读**工作目录及其父目录**。 -因此在 `lpt-be` 这类子目录里干活时,meta 的 `AGENTS.md` 仍会被读到—— -这正是各子项目不再重复通用规则的前提。 +配套事实: + +- **agent 会话从 meta 根目录启动**,子项目靠 `subagent(cwd=)` 进入(见 meta `AGENTS.md` 首页)。因此共有技能放在 meta 就能被发现,不需要往子仓库复制。 +- 在子目录里启动 agent 时,父目录的 `AGENTS.md` 也会被读到(各 harness 大体一致),但**这不是默认工作方式**,不要依赖它:在 `lpt-be` 里启动看不到另外四个仓库的约定,也看不见 meta 的共有技能。 +- 反过来,在 meta 根目录干活时子仓库 `AGENTS.md` 不会自动加载,靠 meta 的子仓库索引带出。 ## 规则文件的写法(强制) diff --git a/.agents/roles/workspace-layout.md b/.agents/roles/workspace-layout.md index 860d563..824b397 100644 --- a/.agents/roles/workspace-layout.md +++ b/.agents/roles/workspace-layout.md @@ -14,11 +14,55 @@ ### meta 仓库的维护边界 -- 本 meta 仓库只维护 `AGENTS.md`、`.gitignore`、`.agents/`(代理技能与通用规则)和 `docs/diagrams/`(图表评审产物),不要在本仓库根目录创建业务代码或系统文档。 +- 本 meta 仓库只维护 `AGENTS.md`、`.gitignore`、`.agents/`(代理技能、通用规则、校验脚本、跨仓库笔记)和 `docs/diagrams/`(图表评审产物),不要在本仓库根目录创建业务代码或系统文档。 - `.gitignore` 忽略所有子项目目录,只放行上述根级条目,避免把独立 Git 仓库提交进本 meta 仓库。 +### 业务决策笔记的归属 + +业务决策写在**各自的业务仓库**里,不集中到 meta,也不放进 `lpt-docs`。 + +- `lpt-be` / `lpt-fe` / `lpt-ai` / `lpt-android` 的决策笔记 → 该仓库自己的 `.agents/notes/`,与该仓库的代码同一次提交。 +- 为什么:决策要被读到,前提是改这段代码的 agent 必然翻到它。放在同仓库同一次改动里,读代码就会撞见;集中到别的仓库,等于写给人看而不是写给下一个人用。 +- `lpt-docs` 只维护概念定义与设计思路,**不承接决策流水账与开发过程记录**(见下节「文档归属」)。 +- 只有在跨仓库口径(如分支↔环境对应、服务间字段耦合)无法归属到单一仓库时,才写进 meta 的 `.agents/notes/`,并在 `AGENTS.md` 里列出路径。 +- 所有记录内容的标题与正文一律用简体中文(`Agent Note:` / `Status:` 头块、代码、命令、路径、专有名词除外);笔记格式与校验沿用 meta 仓库 `.agents/skills/write-notes-like-deepseek/`。 + ### 规则与技能的落位 -- 通用规则(跨仓库)→ meta 仓库 `.agents/roles/`。 -- 项目专属规则 → 该仓库自己的 `roles/`。 -- 工作区级技能 → `.agents/skills/<技能名>/`;子项目专属技能 → 该仓库 `skills/`。 +规则和技能都收在 `.agents/` 下,不要放在仓库根目录的 `roles/`、`skills/`。 + +**先回答「这东西换个仓库还成立吗?」** + +| 内容 | 位置 | 例子 | +|------|------|------| +| 通用规则(不限仓库) | meta `.agents/roles/` | 提交规范、调研汇报、并行委派 | +| 项目专属规则 | 该仓库 `.agents/roles/` | 后端的迁移规范、前端的代码标准 | +| **共有技能(单一来源)** | **只在 meta `.agents/skills/`** | `write-notes-like-deepseek`、`mermaid-diagram` | +| 项目专属技能 | 该仓库 `.agents/skills/` | `lpt-be` 的 `comment-cleanup`、`lpt-fe` 的 `ui-review` | +| 决策笔记 | 该仓库 `.agents/notes/` | 能归属到单一仓库的决定 | +| 跨仓库决策笔记 | meta `.agents/notes/` | 分支↔环境口径这类无法归属的决定 | + +### 共有技能只在 meta,子项目不放副本 + +跨仓库通用的技能一律以 meta 的 `.agents/skills/<技能名>/` 为**唯一真实副本**,子项目里不建副本、不建符号链接。 + +理由(每条都可验证): + +- **agent 只在 meta 运行**(见 meta `AGENTS.md`),工作目录向上扫描技能目录时能发现 meta 的 `.agents/skills/`;子项目里的副本对 agent 没有任何额外作用。 +- **副本必漂移。** 本工作区曾把 `write-notes-like-deepseek` 分别复制进三个仓库(三份 sha1 完全一致),之后对上游的中文标题补丁就得手改三处;一旦漏改一处,各仓校验行为就不一致。 +- **符号链接在 Windows / `core.symlinks=false` 下会退化成普通文本文件**(内容是一行路径字符串),`node path/SKILL.md` 直接 `Not a directory`;而 `lpt-fe/Dockerfile` 是 `COPY . .`,指向构建上下文之外的链接会让 `docker build` 报 forbidden path。两个坑都在本工作区实测过。 +- **单独 clone 子仓库时(CI、别的机器)不依赖 meta**,技能本来就读不到,所以「副本能自包含」这个好处并不成立。 + +新增共有技能的步骤:在 meta `.agents/skills/<技能名>/` 建好 → 在 meta `AGENTS.md` 的「共有技能」段登记一行(路径 + 触发场景)→ 子项目里什么都不用做。 + +需要项目专属技能时,才在该仓 `.agents/skills/` 下建,并登记到 meta `AGENTS.md` 的子仓库索引。 + +### 生效方式的事实 + +三条事实决定了上述落位,写错位置等于写了没人读: + +- **`.agents/roles/` 不会被任何 harness 自动加载。** 规则要生效,必须在该仓库 `AGENTS.md` 的「规则与技能位置」段列出路径,并在 meta `AGENTS.md` 的「子仓库规则与技能索引」里能找到;否则只是一堆没人读的文件。 +- **技能发现机制因 harness 而异。** Pi 递归扫描用户级与项目技能目录(`.pi/skills/`、`.agents/skills/`,后者从工作目录向上,遇到 git 仓库根或工作区根停止);Claude 体系读 `.claude/skills/`;codex / dsh 等未必扫描技能目录。所以 meta `AGENTS.md` 里给出技能路径,让模型按需 `read`,不把「自动发现」当前提。 +- **meta 会话只自动加载工作目录及父目录的 `AGENTS.md`。** 子仓库的 `AGENTS.md` 靠 meta `AGENTS.md` 的索引与读取协议带出来。不要依赖 `.pi/` 扩展、`.pi/settings.json` 或任何 harness 私有机制做自动注入,换一个入口就失效。 + +**维护纪律**:新增或删除子仓库规则/技能时,同一次提交里同步 meta `AGENTS.md` 的子仓库索引(只写路径 + 触发场景,不复制正文);索引里的路径必须真实存在。共有技能不登记进子仓库索引。 diff --git a/.agents/scripts/package.json b/.agents/scripts/package.json new file mode 100644 index 0000000..094aa89 --- /dev/null +++ b/.agents/scripts/package.json @@ -0,0 +1,4 @@ +{ + "type": "module", + "private": true +} diff --git a/.agents/scripts/verify-notes.ts b/.agents/scripts/verify-notes.ts new file mode 100644 index 0000000..878e560 --- /dev/null +++ b/.agents/scripts/verify-notes.ts @@ -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(", ")} — 三条门禁全部通过`); diff --git a/.agents/skills/write-notes-like-deepseek/SKILL.md b/.agents/skills/write-notes-like-deepseek/SKILL.md new file mode 100644 index 0000000..d13272a --- /dev/null +++ b/.agents/skills/write-notes-like-deepseek/SKILL.md @@ -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//`,文件名日期不动;② `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 -- [--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 /scripts/verify-*.ts`——不得以「未配置校验入口」为由跳过。 + +看板打包参数为 `--bundle <输出.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` — 校验脚本说明 diff --git a/.agents/skills/write-notes-like-deepseek/assets/agent-notes-board.html b/.agents/skills/write-notes-like-deepseek/assets/agent-notes-board.html new file mode 100644 index 0000000..7cf3390 --- /dev/null +++ b/.agents/skills/write-notes-like-deepseek/assets/agent-notes-board.html @@ -0,0 +1,1779 @@ + + + + + + +工程决策看板 + + + + + + + + +
+
+ +
+ 工程决策看板 + 0 项 +
+
+ + + +
+ + + +
+ + 连接本地目录 +
+
+ +
+ + + + + +
+
+ +
+
+ + 🏛️ + 系统承重墙 + + 基于交叉引用入度权重萃取的系统关键协议 +
+
+
+ +
+
+ + 🧩 + 领域架构分类阵列 + + 现行生效的生产事实全景清单 +
+
+
+
+ + +
+
+
+ + ⏱️ + 技术演进时间线 + + 记录架构突破与代码裁撤里程碑 +
+ +
+
+ 📅 月份切片: +
+
+
+ 🏷️ 分类切片: +
+
+
+ + +
+
+ +
+
+
+ + +
+
+
+ + 🛡️ + 避坑与反思智库 + + 记录「为什么放弃了方案 B」与被否决的提案,防止重复踩坑 +
+
+ +
+
+
+
+ + +
+
+ + + + + +
+ +
+
+ 编号 + 分类 + 标题 + 状态 + 日期 + 引用 +
+
+
+
+ +
+
Agent Notes · 工程决策看板 · 遵循 MIT 协议开源
+
+ 友情链接: + LinuxDo +
+
+ +
+ + +
+ + + + + + + + \ No newline at end of file diff --git a/.agents/skills/write-notes-like-deepseek/package.json b/.agents/skills/write-notes-like-deepseek/package.json new file mode 100644 index 0000000..094aa89 --- /dev/null +++ b/.agents/skills/write-notes-like-deepseek/package.json @@ -0,0 +1,4 @@ +{ + "type": "module", + "private": true +} diff --git a/.agents/skills/write-notes-like-deepseek/references/archiving.md b/.agents/skills/write-notes-like-deepseek/references/archiving.md new file mode 100644 index 0000000..8a63ef5 --- /dev/null +++ b/.agents/skills/write-notes-like-deepseek/references/archiving.md @@ -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//.md \ + [--superseded-by .agents/notes/implemented//<新笔记>.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//...` → `archived//...`(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` 为实际路径。 diff --git a/.agents/skills/write-notes-like-deepseek/references/classification.md b/.agents/skills/write-notes-like-deepseek/references/classification.md new file mode 100644 index 0000000..7dc0b5b --- /dev/null +++ b/.agents/skills/write-notes-like-deepseek/references/classification.md @@ -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 分类实践。 diff --git a/.agents/skills/write-notes-like-deepseek/references/note-format.md b/.agents/skills/write-notes-like-deepseek/references/note-format.md new file mode 100644 index 0000000..3cb856e --- /dev/null +++ b/.agents/skills/write-notes-like-deepseek/references/note-format.md @@ -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 ?` 子节)。没有过的选项不要编。「不做 / 复用现状」仅当当时真的权衡过才写。脚本只检查这一节在不在。 + +## 时态与禁止改写 + +- `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:` 保持英文原文以便脚本核对。 diff --git a/.agents/skills/write-notes-like-deepseek/references/prose-checklist.md b/.agents/skills/write-notes-like-deepseek/references/prose-checklist.md new file mode 100644 index 0000000..3cc87e6 --- /dev/null +++ b/.agents/skills/write-notes-like-deepseek/references/prose-checklist.md @@ -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` 里的 `实测`、来源标注与编号删掉,结论就没根了。 diff --git a/.agents/skills/write-notes-like-deepseek/references/quality-gate.md b/.agents/skills/write-notes-like-deepseek/references/quality-gate.md new file mode 100644 index 0000000..0369b5e --- /dev/null +++ b/.agents/skills/write-notes-like-deepseek/references/quality-gate.md @@ -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 +**语义自检:** +✅ 稳定:动机独立成立 / 有 2 个真备选 / 后果代价收益兼备 +⚠️ 缺口: +- Alternatives — 有"做了 vs 不做"稻草人,补一个与现行方案平行的真实选项 +- Consequences — "性能提升"要落到哪条路径、什么量级 +建议:修以上 2 处后落盘 / 可接受缺口,直接放行 +``` + +用户接受缺口即放行;不接受就修再落盘。意思上的判断不是脚本,别把它撑成另一道检查。 + +## 这套自检生效了吗(观测判据) + +每隔一段时间回看,以下信号说明自检在起作用;信号消失说明它在空转: + +- 你向用户提的问题里,**不再出现**翻一下笔记树或 rg 一下就能答的事实性问题。 +- 汇报里的每条缺口都带着**具体修法**(改哪节、补什么),而不是"建议再完善"。 +- `rejected/` 和 Alternatives 里被否掉的路线,**不再被新会话重新提出**——这正是整套系统存在的理由。 \ No newline at end of file diff --git a/.agents/skills/write-notes-like-deepseek/references/simplification-checklist.md b/.agents/skills/write-notes-like-deepseek/references/simplification-checklist.md new file mode 100644 index 0000000..e447df4 --- /dev/null +++ b/.agents/skills/write-notes-like-deepseek/references/simplification-checklist.md @@ -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` 的“未来参考价值”判定是否归档,而非字数/年龄。 diff --git a/.agents/skills/write-notes-like-deepseek/references/verification.md b/.agents/skills/write-notes-like-deepseek/references/verification.md new file mode 100644 index 0000000..3c73873 --- /dev/null +++ b/.agents/skills/write-notes-like-deepseek/references/verification.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 # 只查有改动的 +``` diff --git a/.agents/skills/write-notes-like-deepseek/references/when-to-write.md b/.agents/skills/write-notes-like-deepseek/references/when-to-write.md new file mode 100644 index 0000000..1346da5 --- /dev/null +++ b/.agents/skills/write-notes-like-deepseek/references/when-to-write.md @@ -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//`,文件名日期不动(首次提出日) +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。 diff --git a/.agents/skills/write-notes-like-deepseek/scripts/agent-note-tree.ts b/.agents/skills/write-notes-like-deepseek/scripts/agent-note-tree.ts new file mode 100644 index 0000000..538b9f1 --- /dev/null +++ b/.agents/skills/write-notes-like-deepseek/scripts/agent-note-tree.ts @@ -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 } +} diff --git a/.agents/skills/write-notes-like-deepseek/scripts/archive-agent-note.ts b/.agents/skills/write-notes-like-deepseek/scripts/archive-agent-note.ts new file mode 100644 index 0000000..9555810 --- /dev/null +++ b/.agents/skills/write-notes-like-deepseek/scripts/archive-agent-note.ts @@ -0,0 +1,167 @@ +/** + * CLI tool to archive an implemented Agent Note with frozen manifest sealing. + * Usage: node /scripts/archive-agent-note.ts .agents/notes/implemented//.md [--superseded-by ] + * --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 /scripts/archive-agent-note.ts [--superseded-by ]"); + 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// 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; +} +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})`); + } +} diff --git a/.agents/skills/write-notes-like-deepseek/scripts/build-board.ts b/.agents/skills/write-notes-like-deepseek/scripts/build-board.ts new file mode 100644 index 0000000..63f7ae6 --- /dev/null +++ b/.agents/skills/write-notes-like-deepseek/scripts/build-board.ts @@ -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) { + 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(); // 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(); + 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`; + } +} 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(/ `window.__INLINE_DATA__ = ${jsonSafe};` +); + +writeFileSync(outputPath, template, 'utf8'); +console.log(`🎉 [打包完成] 看板已生成: ${outputPath}`); +console.log(`💡 该文件内置了 ${notes.length} 篇笔记数据,可脱机分发、离线演示或部署至 GitHub Pages。`); diff --git a/.agents/skills/write-notes-like-deepseek/scripts/check-note-anchors.ts b/.agents/skills/write-notes-like-deepseek/scripts/check-note-anchors.ts new file mode 100644 index 0000000..c2c05f2 --- /dev/null +++ b/.agents/skills/write-notes-like-deepseek/scripts/check-note-anchors.ts @@ -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 /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*|"; + +/** 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(lines.length).fill(false); + const commented = new Array(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 `"); + 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: `"); + 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`); diff --git a/.agents/skills/write-notes-like-deepseek/scripts/verify-agent-note-tree.ts b/.agents/skills/write-notes-like-deepseek/scripts/verify-agent-note-tree.ts new file mode 100644 index 0000000..59d1853 --- /dev/null +++ b/.agents/skills/write-notes-like-deepseek/scripts/verify-agent-note-tree.ts @@ -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`); diff --git a/.agents/skills/write-notes-like-deepseek/scripts/verify-archived-agent-notes.ts b/.agents/skills/write-notes-like-deepseek/scripts/verify-archived-agent-notes.ts new file mode 100644 index 0000000..0f9adc9 --- /dev/null +++ b/.agents/skills/write-notes-like-deepseek/scripts/verify-archived-agent-notes.ts @@ -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`); diff --git a/.agents/skills/write-notes-like-deepseek/templates/implemented.md b/.agents/skills/write-notes-like-deepseek/templates/implemented.md new file mode 100644 index 0000000..635afd3 --- /dev/null +++ b/.agents/skills/write-notes-like-deepseek/templates/implemented.md @@ -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 + +<可选,现在时事实:如何证明该决定在当前代码库中依然生效。落到可确认表面——路径、量级、执行命令> diff --git a/.agents/skills/write-notes-like-deepseek/templates/proposed.md b/.agents/skills/write-notes-like-deepseek/templates/proposed.md new file mode 100644 index 0000000..ef53b96 --- /dev/null +++ b/.agents/skills/write-notes-like-deepseek/templates/proposed.md @@ -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 + +<可能出什么问题、已知取舍与回滚条件> diff --git a/.agents/skills/write-notes-like-deepseek/templates/rejected.md b/.agents/skills/write-notes-like-deepseek/templates/rejected.md new file mode 100644 index 0000000..6c5f177 --- /dev/null +++ b/.agents/skills/write-notes-like-deepseek/templates/rejected.md @@ -0,0 +1,27 @@ +# Agent Note: <标题> + +Status: rejected — <一句话原因> + +<!-- + 【维护提醒】 + 1. 冻结不动:不改写为对立面,不随代码演进更新事实;结论就在 Status 行。 + 2. 仅在"防止重犯"期间保留:被否方案依赖的旧技术/API 已彻底移除、后人绝无可能 + 再提时,把这一篇删掉。 + 3. 价值被新笔记吸收时,按 references/archiving.md 的合并删除流程处理。 +--> + +## Problem + +<动机> + +## Proposal + +<曾拟议的方案,冻结保留> + +## Alternatives considered + +- **<备选>** — <为何当时考虑/为何最终否掉> + +## Risks + +<为何否掉、若重提需满足什么条件> diff --git a/.agents/skills/write-notes-like-deepseek/templates/verify-notes.yml b/.agents/skills/write-notes-like-deepseek/templates/verify-notes.yml new file mode 100644 index 0000000..6d6ef8b --- /dev/null +++ b/.agents/skills/write-notes-like-deepseek/templates/verify-notes.yml @@ -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 diff --git a/.rgignore b/.rgignore new file mode 100644 index 0000000..6bffdc1 --- /dev/null +++ b/.rgignore @@ -0,0 +1,2 @@ +# Frozen Agent Notes are historical snapshots, not current search authority. +/.agents/notes/archived/