docs: 明确 agent 只在 meta 运行,并登记跨仓库笔记
- AGENTS.md 首页新增「Agent 只在 meta 仓库根目录运行」及三条支撑事实 - 规则与技能位置区分「共有技能唯一来源」与「子项目独有内容」 - 补笔记校验入口与其他技能的调用方式 - .agents/notes/ 收录两篇跨仓库决策笔记;.gitignore 放行 .rgignore
This commit is contained in:
@@ -0,0 +1,50 @@
|
||||
# Agent Note: meta 会话按索引读取子仓库规则与技能
|
||||
|
||||
Status: implemented
|
||||
|
||||
## Problem
|
||||
|
||||
在 meta 仓库根目录启动 agent 时,只有 `LPT/AGENTS.md` 会被自动读取。子仓库的 `AGENTS.md`、`.agents/roles/`、`.agents/skills/` 都不在加载范围内,模型只能靠 meta 里一句「改子仓库前先读它的 AGENTS.md」,不知道各仓库具体有哪些规则和技能,也不知道该在什么时候读哪一份。共有技能此后已收归 meta 单一份(见 [2026-11-18](2026-11-18-shared-skills-single-source.md)),本节索引只负责各仓**独有**的规则与技能。
|
||||
|
||||
同时,各子仓库把专属规则放在仓库根 `roles/`,与 `.agents/roles/workspace-layout.md` 的落位规则(规则和技能都收在 `.agents/` 下)冲突,而 meta `AGENTS.md` 与 `.agents/roles/README.md` 又都把错误位置写成了规范。规则放在哪都不会被任何 harness 自动加载,位置不统一只会增加引用成本和失效引用。
|
||||
|
||||
## Decision
|
||||
|
||||
1. 子仓库专属规则统一放在各仓库的 `.agents/roles/`。`lpt-fe`(6 份)、`lpt-be`(5 份)、`lpt-ai`(2 份)、`lpt-docs`(1 份)已完成迁移,`AGENTS.md`、`ui-review` 技能与规则间的相互引用同步改为 `.agents/roles/`。
|
||||
2. meta `AGENTS.md` 维护「子仓库规则与技能索引」:每个仓库列出 `AGENTS.md` 路径、规则目录与每份规则的触发场景、技能目录与每个技能的触发场景,只写路径与场景,不复制正文。
|
||||
3. 读取协议写在索引上方:改哪个仓库先读它的 `AGENTS.md`,再按任务读匹配的规则文件;技能只在描述命中时读 `SKILL.md`;不匹配的不读,禁止一次性读入多家仓库的全部规则。
|
||||
4. 不引入 `.pi/extensions`、`.pi/settings.json` 或任何 harness 私有机制。索引与协议对 Pi、codex、dsh 等入口同样成立,代价是「自动」只到指令级,不强制。
|
||||
5. 维护纪律:新增或删除子仓库规则/技能时,同一次提交里同步 meta `AGENTS.md` 索引;索引路径必须真实存在。约束写入 `.agents/roles/workspace-layout.md`。
|
||||
|
||||
### 各 harness 的加载事实
|
||||
|
||||
- 上下文指令:只读工作目录及父目录的 `AGENTS.md`(Claude 体系另有 `CLAUDE.md`)。因此 meta 会话看得到 `LPT/AGENTS.md`,看不到 `lpt-fe/AGENTS.md`;反过来在 `lpt-fe` 里启动时两份都读得到。
|
||||
- 技能:Pi 扫描 `<agent-dir>/skills`、`.pi/skills`、`.agents/skills`(从工作目录向上、遇 git 仓库根停止);Claude 体系读 `.claude/skills/`;codex / dsh 等未必扫描技能目录。因此索引必须给出技能路径,让模型按需 `read`。
|
||||
- `roles/` 在任何 harness 里都不是加载入口,只能靠 `AGENTS.md` 引用。
|
||||
|
||||
### 索引与校验
|
||||
|
||||
索引条目形如:
|
||||
|
||||
```markdown
|
||||
- **lpt-fe**(`lpt-fe/AGENTS.md`)
|
||||
- 规则(`lpt-fe/.agents/roles/`):`design-principles.md` 新增或重构页面 · `design-system.md` 取值与调性 · …
|
||||
- 技能(`lpt-fe/.agents/skills/`):`ui-review` 新页面或大范围 UI 改动 · …
|
||||
```
|
||||
|
||||
本次用一次性脚本核对过:每个 `.agents/roles/*.md` 与 `.agents/skills/*/SKILL.md` 都出现在 meta 索引和所属仓库 `AGENTS.md` 里,索引中的 `lpt-*/` 路径没有死链。
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
- **用 `.pi/extensions` 按文件路径动态注入规则(最接近「自动」)**:能监听 `tool_call` 的 `path`,在首次触达某仓库时通过 `sendMessage` 注入该仓库 `AGENTS.md` 与规则索引,必要时还能 `block` 首个 `edit` 等规则到位。但它只在 Pi 生效,换 codex / dsh 立刻失效;同时要自己维护一份扩展代码并跟随 Pi 扩展 API 变更,与「不绑定入口」的目标冲突。
|
||||
- **用 `.pi/settings.json` 登记子仓库 `.agents/skills`**:零代码,启动时自动广播技能名与描述,比索引更接近「自动发现」。但同样是 harness 私有配置;当时三个仓库各有一份同名的 `write-notes-like-deepseek`,整目录登记会触发同名冲突警告(该重复已按 [共有技能收归 meta 单一份](2026-11-18-shared-skills-single-source.md) 消除,但 harness 私有配置这条不成立的理由不变);新增技能还要手工登记,维护面并未减少。
|
||||
- **把 `roles/*.md` 改写成 `SKILL.md`**:能让规则进入技能广播列表,按描述触发。但 9 份政策文档会占满技能列表,规则正文照样要读;codex / dsh 未必支持技能;改写和后续维护成本都高于一份索引。
|
||||
- **保持现状(只在 meta `AGENTS.md` 写一句「先读子仓库 `AGENTS.md`」)**:成本最低。但模型不知道各仓库有哪些规则与技能,只能边做边发现;本次会话能读到 `lpt-fe` 规则属于偶然遵守,不是机制。
|
||||
|
||||
## Consequences
|
||||
|
||||
收益:跨 harness 通用,不依赖任何入口的私有能力;子仓库规则位置统一,索引与文件可机械校验;新增仓库时有明确登记点,读取顺序也写清楚了。
|
||||
|
||||
代价:「自动加载」只到指令级,模型仍可能跳过索引;索引与实际文件会漂移,只能靠维护纪律和一次性校验兜底;索引本身占 meta `AGENTS.md` 约 20 行,每次会话都进上下文。
|
||||
|
||||
回滚:删除索引段与这篇笔记不影响代码;`roles/` 到 `.agents/roles/` 是纯 rename,按 `git mv` 反向即可。
|
||||
@@ -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),这正是「死链不过夜」的机械保障。
|
||||
Reference in New Issue
Block a user