oh-my-muse/docs/agent-specs/2026-06-14-agent基建六砖交付.md

Agent 开发基建六砖交付说明(2026-06-14)

项	值
版本	v1.0
日期	2026-06-14
读者	决策者 / 后续 Agent
性质	点状交付说明(本轮做了什么、为何、证据);进度活账见 docs/mvp/进度总账.md
用途	留痕与验收;后续同类工作据此复用,避免重复探索
边界	只记本轮 agent 开发基建交付;模块真实现状权威见 现状基线

---

一、结论(TL;DR)

1. 按机械门禁优先建成 oh-my-muse 的 agent 开发基建:P0 + 六砖全部交付。
2. 承重的两道机械门禁有真实绿证据(JDK21 实跑,CI 同款 surefire):
   • BC 边界门 BcBoundaryArchTest 1/0F、契约先行门 ContractFirstGateTest 2/0F;
   • 合并运行 Tests run: 3, Failures: 0, BUILD SUCCESS。
3. 治理层(knowledge/skills/workflow/总账/per-module .agent)以交叉引用零缺失验收,其约束力来自所指向的真门禁。
4. 直面失控根因"假绿"(完成信号靠人工拨动 + CI 跳过测试 + 自填标签 + mock 假绿):本轮把约束从"自觉文档"升级为"机械阻断",坏代码进 PR 即红。

---

二、为什么这样建(根因 → 取舍)

• 失控根因(见 对抗复盘)不是缺文档,而是软约束被绕过:CI 曾 -Dmaven.test.skip、门禁断言硬编码、completed 台账人工对账、前端只对 MSW mock 通过。
• 取舍:机械门禁优先于软约束。.agents/rules/ 的每条红线必须配套机械门禁(CI/ArchUnit/契约校验),否则只是会被绕过的文档。
• 同源于你的边界原则:权限/安全/数据约束必须落在可信边界——类比之,agent 约束必须落在 CI 这道机械边界,而非 prompt 或文档自觉。

---

三、交付全景

flowchart TD
    A[AGENTS.md\n项目唯一入口] --> B[.agents/ 能力中枢]
    B --> K[knowledge/\n定位·架构·现状指针·决策]
    B --> R[rules/\n硬约束 + 必配门禁]
    B --> S[skills/\n黄金旅程·加BC模块]
    B --> W[workflows/\nAI开发协议:承接→…→沉淀]

    R --> G1[BcBoundaryArchTest\nBC不碰他域 DAL]
    R --> G2[ContractFirstGateTest\nFlyway卫生 + OpenAPI结构]
    R --> G3[CI maven.yml\n真跑测试·JDK21·不跳过]

    G1 & G2 & G3 -.PR/push 机械阻断.-> IMPL[(muse-cloud / muse-admin / muse-studio\n实现代码)]

    W -- 第六步 沉淀(复利) --> B
    LED[docs/mvp/进度总账\n单一进度源] --- AG[muse-module-*/.agent\n模块跨会话记忆]
    A --> LED

要点:入口唯一(AGENTS.md)→ 中枢四层(.agents)→ 三道机械门禁实在地卡在 PR/push → workflow 的"沉淀"把每次成果写回中枢形成复利 → 进度只进总账 + .agent,杜绝过程文档 churn。

---

四、逐砖交付与验证证据

砖	交付物	验证方式	证据
P0	CI 真跑测试(JDK21、去 -Dmaven.test.skip)+ 覆盖台账去硬编码 + 冻结令	机械	既有,绿
①	BcBoundaryArchTest + bc-boundaries.md	JDK21 实跑	1/0F,clean 全 reactor BUILD SUCCESS
②	ContractFirstGateTest + contract-first.md	JDK21 实跑	2/0F(Flyway 唯一/连续/命名 + OpenAPI 7 域结构)
③	.agents/knowledge/ 3 份蒸馏	链接完整性	13/13 引用存在
④	.agents/skills/ 2 份手册	锚点完整性	13/13 路径/锚点存在
⑤	ai-development-protocol.md	链接完整性	全绿
⑥	进度总账 + 7 个 BC .agent	链接完整性	16/16 路径存在
合并	两门禁同一 surefire 运行	JDK21 实跑	Tests run: 3, Failures: 0, BUILD SUCCESS

---

五、三目标达成映射

原始目标	落点
建 agent 开发基建	AGENTS.md 入口 + .agents 四层中枢 + 总账 + per-module .agent
约束 agent 编码	机械门禁:CI 真跑测试、BC 边界 ArchUnit、契约/迁移卫生——违例=红=阻断(非靠自觉)
持续改进开发环境	workflow"沉淀" + README"新 rule 必配门禁" + 单一进度源 → 复利写回闭环

---

六、诚实边界与未做(非阻塞,已如实标 ⏳)

• ③④⑤⑥ 验收是链接完整性而非机械执行;约束力来自其指向的真门禁。
• 模块现状为 2026-06-13 只读判断;.agent/总账指向基线、不复制数字,降漂移。
• 明确未做:
  1. openapi-diff 破坏性变更 CI(就绪片段见 contract-first §四,未接入即不宣称已拦截破坏性变更);
  2. docs/dev-baseline/global/* 收敛进 engineering-conventions / security-and-reliability 两条带门禁 rule;
  3. BC 边界门扩到其它方向(当前只守"AI→他域 DAL"这条已实证违反的方向);
  4. muse-module-ai-contract-server 孤儿空壳清理。

---

七、建议下一步

1. 接入并跑一次 openapi-diff CI,把契约门从"存在/结构"升到"破坏性变更"拦截。
2. 收敛 dev-baseline,补齐两条带门禁的 rule(工程约定 / 安全可靠)。
3. 用 golden-journey-vertical-slice 真跑一条旅程(如 content Accept Suggestion 前端断链),把基建从"约束"带到"产出可用功能"。

---

附:关键文件索引

• 入口 / 中枢:AGENTS.md · .agents/README.md
• 脊柱规则:verification-and-anti-false-green.md
• 进度活账:docs/mvp/进度总账.md
• 现状基线 / 复盘:基线 · 复盘