Files
lpt-meta/.agents/notes/implemented/process/2026-11-18-shared-skills-single-source.md
T
cat-shark 84ce312e4b docs: 明确 agent 只在 meta 运行,并登记跨仓库笔记
- AGENTS.md 首页新增「Agent 只在 meta 仓库根目录运行」及三条支撑事实
- 规则与技能位置区分「共有技能唯一来源」与「子项目独有内容」
- 补笔记校验入口与其他技能的调用方式
- .agents/notes/ 收录两篇跨仓库决策笔记;.gitignore 放行 .rgignore
2026-11-18 14:59:56 +08:00

67 lines
8.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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),这正是「死链不过夜」的机械保障。