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

5.3 KiB
Raw Blame History

Agent Note: meta 会话按索引读取子仓库规则与技能

Status: implemented

Problem

在 meta 仓库根目录启动 agent 时,只有 LPT/AGENTS.md 会被自动读取。子仓库的 AGENTS.md、.agents/roles/、.agents/skills/ 都不在加载范围内,模型只能靠 meta 里一句「改子仓库前先读它的 AGENTS.md」,不知道各仓库具体有哪些规则和技能,也不知道该在什么时候读哪一份。共有技能此后已收归 meta 单一份(见 2026-11-18),本节索引只负责各仓独有的规则与技能。

同时,各子仓库把专属规则放在仓库根 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 引用。

索引与校验

索引条目形如:

- **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 单一份 消除,但 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 反向即可。