docs: 明确 agent 只在 meta 运行,并登记跨仓库笔记

- AGENTS.md 首页新增「Agent 只在 meta 仓库根目录运行」及三条支撑事实
- 规则与技能位置区分「共有技能唯一来源」与「子项目独有内容」
- 补笔记校验入口与其他技能的调用方式
- .agents/notes/ 收录两篇跨仓库决策笔记;.gitignore 放行 .rgignore
This commit is contained in:
cat-shark
2026-11-18 14:59:56 +08:00
parent f99e1e156d
commit 84ce312e4b
4 changed files with 191 additions and 5 deletions
+74 -5
View File
@@ -2,19 +2,88 @@
本仓库不是产品项目,不包含前后端业务代码。它只作为本地工作区协调仓库,用于让 agent 一次性了解多个独立项目,并在缺失子项目时自动拉取。
## Agent 只在 meta 仓库根目录运行
**工作区里所有 agent 会话都从 meta 仓库根目录启动。** 除 `subagent` 之外,不存在「进入某个子项目目录单独起一个 agent」的正常用法。子项目目录是数据和代码的落点,不是工作目录的入口。
这条不是偏好,是几个硬约束推出来的结论:
- **上下文只向上读**:harness 只加载工作目录及其父目录的 `AGENTS.md`。从 meta 启动读得到全部子项目规则索引;从 `lpt-be/` 启动读不到另外四个仓库的约定,跨仓库改动就会各写一套。
- **技能只在一处**:共有技能集中在 meta 的 `.agents/skills/`(见下节)。子项目里没有副本,从子目录启动就发现不了这些技能。
- **笔记要一起校验**:笔记分散在各仓 `.agents/notes/`,但门禁由 `.agents/scripts/verify-notes.ts` 从 meta 视角一次跑完;在子目录里单跑只能看见一个仓库。
需要并行或分批处理多个子项目时,**用 `subagent` 派发,`cwd` 指向目标子项目**,子代理在其中读写文件、跑命令;主会话仍然留在 meta。
```text
✅ meta 根目录(主会话)── subagent(cwd=lpt-be) → 改后端
└─ subagent(cwd=lpt-fe) → 改前端
❌ cd lpt-be && 起 agent(看不到其他仓库,也没有共有技能)
```
## 规则与技能位置
- **通用规则(跨仓库)**:`.agents/roles/`
- `todo-discipline.md` 待办收口 · `parallel-and-delegation.md` 并行与委派 · `commit-convention.md` 提交规范
- `research-and-reporting.md` 调研与问题定位 · `shell-environment.md` Windows/PowerShell · `workspace-layout.md` 资产归属 · `repo-operations.md` 跨仓库 Git 操作
- `dev-unblock-and-escalation.md` 开发环境自解锁与求助阈值
- **各子项目专属规则**:该仓库自己的 `roles/`(如 `lpt-be/roles/`、`lpt-fe/roles/`)
- **工作区级技能**:`.agents/skills/<技能名>/`
- **子项目专属技能**:该仓库自己的 `skills/`(如 `lpt-be/skills/`)
- `subagent-execution.md` 多部分改动交给子代理、主代理只复核 · `research-and-reporting.md` 调研与问题定位 · `shell-environment.md` Windows/PowerShell · `workspace-layout.md` 资产归属 · `repo-operations.md` 跨仓库 Git 操作
- `dev-unblock-and-escalation.md` 开发环境自解锁与求助阈值 · `service-boundaries-and-validation.md` 校验写在哪一层、拒绝重复防御
- `business-terminology.md` 业务名词收敛(**强制**:agent 之间交流系统概念只用 `lpt-docs/docs/concepts/README.md` 术语表里的名称,不自造同义词;表里没有的词先补表再用。代码标识符也由术语表的英文名派生,不为具体位置另起名字)
- **共有技能(唯一来源,只在 meta)**:`.agents/skills/<技能名>/`
- `write-notes-like-deepseek/` 非平凡改动留决策笔记(笔记契约 + 三条校验脚本)
- `mermaid-diagram/` 图表评审
- **子项目里不放共有技能的副本。** 重复副本会各自漂移,校验路径也会指回不同版本。
- **子项目 `.agents/` 只存该仓库独有的内容**:`<repo>/.agents/roles/`(该仓专属规则)与 `<repo>/.agents/skills/`(该仓专属技能)与 `<repo>/.agents/notes/`(该仓的决策笔记)。换到另一个仓库不成立的东西才放这里。
- **跨仓库决策笔记**:`.agents/notes/`(无法归属到单一仓库的决定)
> 规则文件开头必须是三段:名称(一级标题)→ 功能简述 → 关键字/情况(何时用,要简短,正文放后面)。
> 规则与技能的存放边界见 `.agents/roles/workspace-layout.md`。
### 笔记校验入口
笔记分散在四个仓库,用一条命令从 meta 视角统一校验(不需要切 cwd):
```bash
node .agents/scripts/verify-notes.ts # meta + lpt-be + lpt-fe + lpt-ai 全部跑一遍
node .agents/scripts/verify-notes.ts lpt-be # 只查指定仓库
node .agents/scripts/verify-notes.ts --changed # 只查工作区有未提交改动的仓库
```
三条门禁(目录结构、头部骨架、归档封印)任一失败即非零退出。写完或改完任何笔记后跑一次,红了先修再交。
需要单条门禁或一键归档时(`AGENT_NOTE_ROOT` 指定笔记根,不设时默认 `cwd/.agents/notes`):
```bash
# 单条门禁
AGENT_NOTE_ROOT=$PWD/lpt-be/.agents/notes node .agents/skills/write-notes-like-deepseek/scripts/verify-agent-note-format.ts
# 归档:只插 Archived: 一行 + 封印 + 列出谁还链着它
AGENT_NOTE_ROOT=$PWD/lpt-be/.agents/notes node .agents/skills/write-notes-like-deepseek/scripts/archive-agent-note.ts \
lpt-be/.agents/notes/implemented/<类别>/<文件名>.md \
--superseded-by lpt-be/.agents/notes/implemented/<类别>/<新笔记>.md
```
归档后未修的入站链接会被 tree 门禁当作死链报出(exit 1),所以死链不过夜。
### 子仓库规则与技能索引
> 子仓库的 `AGENTS.md` 不会在 meta 会话自动加载(只有工作目录及父目录的 `AGENTS.md` 会被读)。
> 改动某个子仓库前:先读它的 `AGENTS.md`,再按任务读下面匹配的规则文件;不匹配的不读。
> 本索引只列**子项目独有**的规则与技能;共有技能在 meta `.agents/skills/`,全仓通用,见上节。
- **lpt-fe**(`lpt-fe/AGENTS.md`)
- 规则(`lpt-fe/.agents/roles/`):`design-principles.md` 新增或重构页面 · `design-system.md` 取值与调性 · `code-standards.md` 写组件与请求层 · `ui-review-checklist.md` 交付自检 · `testing.md` 写测试 · `style-conventions.md` 样式与交互
- 技能(`lpt-fe/.agents/skills/`):`ui-review` 新页面或大范围 UI 改动
- **lpt-be**(`lpt-be/AGENTS.md`)
- 规则(`lpt-be/.agents/roles/`):`database-migration.md` 数据库迁移 · `data-access.md` 数据访问层 · `api-response.md` 响应与 DTO · `ownership-and-markers.md` 内容归属与标记 · `ai-integration.md` AI 异步链路
- 技能(`lpt-be/.agents/skills/`):`comment-cleanup` 注释清理
- **lpt-ai**(`lpt-ai/AGENTS.md`)
- 规则(`lpt-ai/.agents/roles/`):`task-queue.md` 队列契约 · `security-and-degradation.md` 安全边界与降级
- **lpt-docs**(`lpt-docs/AGENTS.md`):规则(`lpt-docs/.agents/roles/`):`documentation-scope.md` 文档边界
- 业务名词的唯一权威是 `lpt-docs/docs/concepts/README.md` 术语表;交流用词约束见 `business-terminology.md`
- **lpt-android / lpt-infra / lpt-companion**:暂无专属规则与技能,按各自 `AGENTS.md` 执行
> 索引只写路径与触发场景,不复制正文。新增或删除子仓库规则/技能时同步本节,约束见 `.agents/roles/workspace-layout.md`。
> 共有技能不进本节:它们只在 `.agents/skills/`,所有仓库通用,不需要逐仓登记。
## 本仓库
| 项目 | SSH 地址 | 默认拉取分支 |