docs: 明确 agent 只在 meta 运行,并登记跨仓库笔记

- AGENTS.md 首页新增「Agent 只在 meta 仓库根目录运行」及三条支撑事实
- 规则与技能位置区分「共有技能唯一来源」与「子项目独有内容」
- 补笔记校验入口与其他技能的调用方式
- .agents/notes/ 收录两篇跨仓库决策笔记;.gitignore 放行 .rgignore
This commit is contained in:
cat-shark
2026-11-18 14:59:56 +08:00
parent f99e1e156d
commit 84ce312e4b
4 changed files with 191 additions and 5 deletions
@@ -0,0 +1,66 @@
# Agent Note: 共有技能收归 meta 单一份,agent 只在 meta 运行
Status: implemented
## Problem
`write-notes-like-deepseek` 被分别复制进 `lpt-be`、`lpt-fe`、`lpt-ai` 三个仓库各一份(三份 `SKILL.md` 的 sha1 完全一致,均为 `cdd7570a…`)。这套复制在接入时就留下了三个具体问题:
1. **补丁要手改三处。** 三份副本都已经对上游做过同一处偏离:`SKILL.md` 与 `references/note-format.md` 要求「标题也用简体中文」,而上游只要求正文。下次再改技能,就得记得三处同步,漏一处就出现「后端校验按新规则、前端按旧规则」的分裂。
2. **路径引用是自指的。** 三个仓库的 `AGENTS.md` 都写着 `npx tsx .agents/skills/write-notes-like-deepseek/scripts/…`——这条命令只在本仓 cwd 下成立。而实际工作方式是 agent 在 meta 根目录启动,跨仓库改动时切 cwd 反而更少见,于是这些命令在最常用的场景里根本跑不通。
3. **子项目 `.agents/` 的职责被稀释。** 它本该只放「换到别的仓库就不成立」的东西(后端迁移规范、前端设计系统、`comment-cleanup`、本仓笔记)。塞进一份全仓通用的技能副本后,「这一仓的 `.agents/` 里什么该有什么不该有」没有判断标准,新增内容只会继续往错的方向长。
更深一层的根因是运行位置没被写下来:如果不明确「agent 只在 meta 启动,子项目靠 `subagent` 进入」,那么把技能复制到每个仓库看起来才是稳妥做法——反正每个仓都可能是入口。
## Decision
**agent 只在 meta 仓库根目录运行。** 除 `subagent`(`cwd` 指向目标子项目)之外,不存在「进入子项目目录单独起一个 agent」的正常用法。这条写进 meta `AGENTS.md` 首页第一节,并给出三条支撑事实:上下文只向上读、共有技能只在一处、笔记门禁要跨仓一次跑完。
**共有技能以 meta 的 `.agents/skills/` 为唯一真实副本。** `write-notes-like-deepseek/` 与 `mermaid-diagram/` 都在这里,子项目内不建副本、不建符号链接。子项目 `.agents/` 此后只承载该仓独有内容:`roles/`(专属规则)、`skills/`(专属技能,现存 `lpt-be/comment-cleanup` 与 `lpt-fe/ui-review`)、`notes/`(本仓决策笔记)。
**笔记仍留在各自仓库。** 笔记跟着它所描述的代码走,与该仓代码同一次提交;只有无法归属到单一仓库的决定(如分支↔环境口径)才写进 meta 的 `.agents/notes/`。技能集中与笔记分散是两条独立的决定:技能是工具,工具要唯一;笔记是证据,证据要贴着证据的对象。
**校验入口改为工作区级一次跑完。** 新增 `.agents/scripts/verify-notes.ts`,从 meta 视角遍历所有含 `.agents/notes/` 的仓库,对每个仓库依次跑 tree / format / archived 三条门禁,并用 `AGENT_NOTE_ROOT` 显式指定笔记根。三个仓的 `AGENTS.md` 里那三行 `npx tsx` 长命令替换为一行 `node .agents/scripts/verify-notes.ts <repo>`。
**脚本改用 `node` 直跑。** 技能内所有命令从 `npx tsx …` 改为 `node …`,并在技能目录放一份 `{"type":"module"}` 的 `package.json` 消除 `MODULE_TYPELESS_PACKAGE_JSON` 警告。这是实测结论,不是猜测:Node 22.23 原生跑 `.ts` 时,上述五个校验/归档/看板脚本全部 exit 0,输出与 tsx 一致。
### 四个仓库的落地形态
| 位置 | 承载内容 |
|------|----------|
| `meta/.agents/skills/` | 共有技能唯一副本(`write-notes-like-deepseek`、`mermaid-diagram`) |
| `meta/.agents/roles/` | 跨仓库通用规则 |
| `meta/.agents/scripts/` | `verify-notes.ts` 工作区级校验入口 |
| `meta/.agents/notes/` | 跨仓库决策笔记 |
| `<repo>/.agents/roles/` | 该仓专属规则 |
| `<repo>/.agents/skills/` | 该仓专属技能(有则建,无则空) |
| `<repo>/.agents/notes/` | 该仓决策笔记 |
## Alternatives considered
- **保持三个仓库各自一份副本(接入时的现状)** — 最直接的好处是自包含:单独 clone 任何一个子仓库,技能都在里面,CI 或别人的机器上不依赖 meta 存在。对「笔记要贴着代码」这个目标,副本也不构成障碍。但这份自包含是假的:单独 clone 时读不到 meta 的 `AGENTS.md`,也没有 agent 在室内运行,技能目录本身就是死文件。同时它确实会漂移——本工作区已经出现过需要手改三处的补丁,而三份文件内容一致性只能靠人眼和一次性 `diff` 维持。
- **meta 放一份、各仓放符号链接** — 单一来源与「子仓库内可直接引用路径」兼得,理论上最优雅。实测否决:本工作区所有仓库 `core.symlinks=false`,在该配置下 checkout 会把目录符号链接退化成普通文本文件(内容就是那一行路径),`node linkdir/SKILL.md` 直接报 `Not a directory`;此外 `lpt-fe/Dockerfile` 是 `COPY . .`,指向构建上下文之外的链接会让 `docker build` 报 forbidden path。两个故障都在本机复现过,不是理论风险。
- **用 `npx skills add czm15053/write-notes-like-deepseek` 从上游安装到各仓** — 升级路径最省事,不需要自己维护副本。但本地已经对上游做了中文标题这一处有意偏离,重新安装会把它覆盖掉;而且安装器与联网状态绑定,工作区离线时技能就不可用。上游版本可追踪,但代价是每次升级都要重新打补丁。
- **干脆不做单一来源,只在各仓 `SKILL.md` 里写「改技能时记得同步三处」** — 零改动成本。但这条纪律没有任何机械牙齿,而本技能自身的主张就是「写在散文里的规矩等于没有规矩」;用它来维护它自己显然不成立。
## Consequences
- **收益**:技能改一处、四仓同时生效;子项目 `.agents/` 有了明确判断标准(换仓库还成立吗);`verify-notes.ts` 一次跑完全部仓库,不会再因为「在错误 cwd 里跑出 0 篇通过」而假绿;不再有 Windows / `core.symlinks=false` / `docker build` 上的符号链接坑。
- **收益**:命令从 `npx tsx` 变 `node`,去掉对 npx 缓存的隐式依赖(网络不可用时不再可能失败)。
- **代价与已知上限**:单独 clone 某个子仓库时没有技能可用——这是刻意的取舍,此时 `AGENTS.md` 里的五条接入约定就是降级形态。**信号**:若将来出现「必须在无人值守环境里从单个子仓库跑校验」的需求(例如给某仓单独接 CI),就要重新评估,让 `AGENT_NOTE_ROOT` 指向的笔记根与技能副本解耦,或者退回单仓安装。
- **代价**:`verify-notes.ts` 是一份需要自己维护的胶水代码(约 160 行),它依赖「子项目目录是一个含 `.git` 的独立仓库」这个约定来发现仓库。**信号**:如果新增不含 `.git` 的子项目,或笔记根不再叫 `.agents/notes`,这份脚本要跟着改。
- **代价**:本工作区仍未接 CI 门禁,所有仓库的 workflow 都是 `workflow_dispatch`,纪律靠本地入口 + 自觉。**信号**:漏检开始实际发生(改完笔记没跑校验就提交),就该启用 `.gitea/workflows/verify-notes.yml`——技能 `templates/` 里的模板已经改成 `node` 直跑,只需把 `github.*` 换成 `gitea.*`。
## Verification
```sh
node .agents/scripts/verify-notes.ts
# → ok: meta, lpt-ai, lpt-be, lpt-fe — 三条门禁全部通过
```
- 四个笔记根(meta 1 篇、lpt-be 8 篇、lpt-fe 5 篇、lpt-ai 2 篇)全部通过 tree / format / archived 三条门禁。
- 三仓已无 `write-notes-like-deepseek` 目录:`find lpt-be lpt-fe lpt-ai -name write-notes-like-deepseek` 无输出;`lpt-be/.agents/skills/` 仅剩 `comment-cleanup`,`lpt-fe/.agents/skills/` 仅剩 `ui-review`。
- 破坏性验证:删掉某一篇的 `## Alternatives considered` 后 exit 1,恢复后 exit 0。
- 假绿防护:把某仓 `.agents/notes/` 整体移走(git 记录里曾有过)后,脚本报「疑似误删」并 exit 1,不再静默跳过。
- `.rgignore` 在 meta 与三个有笔记的仓库里均排除 `.agents/notes/archived/`;实测加一个 archived 文件后 `rg` 不再命中它。
- 归档闭环在临时仓里跑通(当前四个仓尚无一篇归档笔记):`archive-agent-note.ts --superseded-by` 会插 `Archived:` 行、写 `manifest.json` SHA-256 封印、列出入站死链,并在新笔记末尾补相对链接;之后 `verify-archived` 报 `1 archive(s), 1 seal`,篡改归档内容则 seal mismatch 且 exit 1。归档后未修的入站链接会被 tree 门禁当作死链拓下(exit 1),这正是「死链不过夜」的机械保障。