v3.0 · 人读协议层。机读契约(.agent/contract.yaml)标 deferred,由 agent 行为漂移拉动上线。
真正的强制力在 scripts/check.py,本文件是建议层(L1),不是强制层(L3)。
📌 仓库根目录 AGENTS.md 是精简入口(供 agent 工具自动发现),本文件是完整契约详解。
- 读取顺序:先读本文件路由表 → 再定位真相源文件。优先读
.meta.md(若存在)缓存,回源才扫全文件。
- 写入前:确认目标文件唯一归属,避免双写。agent 写入先出稿(
.draft/),PM 直写不经草稿区。
- 引用优于复制:跨文件用编号引用,不复述内容。
- 只追加:记忆层新增条目,推翻只改状态字段(
已作废(误)→DEC-XXXX / 已作废(PM拒绝))。
- 节点自给自足:每个文件、每个阶段都可独立存在。agent 可串联("要帮你补 REQ 吗?"),但不强制。
| 信息类型 |
唯一归属 |
引用 |
| 需求主线 |
项目管理/需求登记册.md |
REQ- |
| 里程碑 |
项目管理/路线图.md |
— |
| 风险 |
项目管理/风险登记册.md |
RSK- |
| 依赖 |
项目管理/依赖登记册.md |
DEP- |
| 干系人 |
项目管理/干系人矩阵.md |
姓名/角色 |
| 成功指标 |
项目管理/项目章程.md |
— |
| 决策 |
记忆/决策记录.md |
DEC- |
| 沟通 |
记忆/沟通记录.md |
COM- |
| 进度 |
记忆/进度日志.md |
PRG- |
| 本地知识 |
记忆/知识库.md |
KB- |
| 通用知识 |
_共享/知识库/全局知识库.md |
GKB- |
| 会议纪要 |
文档库/06-会议 |
按日期 |
| 周报/报告 |
文档库/07-报告 |
按日期 |
| 短时记忆 |
记忆/agent会话.md |
SESSION- |
| 原型 |
原型/REQ-XXXX-vN/ |
路线图/现状 引用 |
| 项目内归档 |
归档/ |
月度分片旧月滚入 |
| 跨类全景索引 |
INDEX.md |
derived: true,按需生成 |
- 会议纪要正文 →
06-会议;沟通事件 → COM-(只记对齐/表态、带结论、反空壳)。
- PRD →
01-需求;方案 → 03-方案;需求总账 → 需求登记册。
- 草稿区
.draft/ 不享受只追加保护,PM 拒绝后直接删。
- 跨项目引用
REQ-0007@PROJ-灯塔;check.py 默认不校验跨项目。
scripts/check.py 校验层(唯一强制力,编号唯一/悬空/枚举/老化)scripts/pm.py CLI 门面(pm new-req/check/commit/brief/doctor/finalize).draft/ 草稿区(幂等键从意图派生)记忆/agent会话.md 短时记忆(跨会话延续,月度分片)- 条目 frontmatter schema(详见 写入协议.md)
| 场景 |
步骤 |
| 新建需求 |
扫登记册取最大 REQ → 提议编号 → PM 确认 → 写登记册 + 起 PRD 草稿 → 等 PM 审 |
| 周报生成 |
(L1)扫本周 PRG- → 关联 DEC-/RSK-/DEP- → 出稿 .draft/ → (L2)PM 确认 → 落 07-报告(真相源,非派生) |
| 重聚简报 |
会话开始 → pm brief → 三级回退锚点(SESSION→git log→mtime) → 扫到期项 |
| 需求验收 |
扫 05-验收/REQ-XXXX.md → 比对验收标准 → 更新登记册 status 字段 |
| 级别 |
操作 |
agent 行为 |
| L0 只读 |
读真相源 |
直接做 |
| L1 起草 |
草稿(.draft/)+ 派生文件刷新(现状.md §2-§4,可重建) |
直接做,事后告知 PM |
| L2 写真相源 |
写条目(含周报落 07-报告) |
PM 确认编号 + 内容后落盘 + commit(带 Approved-by) |
| L3 改基线 |
改章程/范围/里程碑 |
PM 显式授权 + 走 DEC- |
- 所有真相源写入经 main_agent 串行化。
- prd_agent / ops_agent / checker_agent 是逻辑角色(deferred),不是并发实例。
- 共享层(_共享/)写入 PM 手动串行(GKB 晋升、宪章修改),agent 不自主写。