- AGENTS.md 首页新增「Agent 只在 meta 仓库根目录运行」及三条支撑事实 - 规则与技能位置区分「共有技能唯一来源」与「子项目独有内容」 - 补笔记校验入口与其他技能的调用方式 - .agents/notes/ 收录两篇跨仓库决策笔记;.gitignore 放行 .rgignore
5.3 KiB
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
- 子仓库专属规则统一放在各仓库的
.agents/roles/。lpt-fe(6 份)、lpt-be(5 份)、lpt-ai(2 份)、lpt-docs(1 份)已完成迁移,AGENTS.md、ui-review技能与规则间的相互引用同步改为.agents/roles/。 - meta
AGENTS.md维护「子仓库规则与技能索引」:每个仓库列出AGENTS.md路径、规则目录与每份规则的触发场景、技能目录与每个技能的触发场景,只写路径与场景,不复制正文。 - 读取协议写在索引上方:改哪个仓库先读它的
AGENTS.md,再按任务读匹配的规则文件;技能只在描述命中时读SKILL.md;不匹配的不读,禁止一次性读入多家仓库的全部规则。 - 不引入
.pi/extensions、.pi/settings.json或任何 harness 私有机制。索引与协议对 Pi、codex、dsh 等入口同样成立,代价是「自动」只到指令级,不强制。 - 维护纪律:新增或删除子仓库规则/技能时,同一次提交里同步 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 反向即可。