- AGENTS.md 首页新增「Agent 只在 meta 仓库根目录运行」及三条支撑事实 - 规则与技能位置区分「共有技能唯一来源」与「子项目独有内容」 - 补笔记校验入口与其他技能的调用方式 - .agents/notes/ 收录两篇跨仓库决策笔记;.gitignore 放行 .rgignore
8.6 KiB
Agent Note: 共有技能收归 meta 单一份,agent 只在 meta 运行
Status: implemented
Problem
write-notes-like-deepseek 被分别复制进 lpt-be、lpt-fe、lpt-ai 三个仓库各一份(三份 SKILL.md 的 sha1 完全一致,均为 cdd7570a…)。这套复制在接入时就留下了三个具体问题:
- 补丁要手改三处。 三份副本都已经对上游做过同一处偏离:
SKILL.md与references/note-format.md要求「标题也用简体中文」,而上游只要求正文。下次再改技能,就得记得三处同步,漏一处就出现「后端校验按新规则、前端按旧规则」的分裂。 - 路径引用是自指的。 三个仓库的
AGENTS.md都写着npx tsx .agents/skills/write-notes-like-deepseek/scripts/…——这条命令只在本仓 cwd 下成立。而实际工作方式是 agent 在 meta 根目录启动,跨仓库改动时切 cwd 反而更少见,于是这些命令在最常用的场景里根本跑不通。 - 子项目
.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
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.jsonSHA-256 封印、列出入站死链,并在新笔记末尾补相对链接;之后verify-archived报1 archive(s), 1 seal,篡改归档内容则 seal mismatch 且 exit 1。归档后未修的入站链接会被 tree 门禁当作死链拓下(exit 1),这正是「死链不过夜」的机械保障。