lili e181669197 chore(agent-infra): 建立 agent 开发基建、清理历史 churn 并以 BC 违例整改验证

本会话三部分交付,均经 JDK21 真实构建验证(非退出码,读 BUILD SUCCESS + Tests run):

1) Agent 开发基建(机械门禁优先)
- 入口与中枢:AGENTS.md、.agents/{knowledge,rules,skills,workflows}、CLAUDE.md 订正
- 订正 .gitignore:移除对 .agent/.agents 的忽略——它们是版本化 agent 基建,须入库(此前被忽略致克隆即缺)
- 机械门禁:CI 真跑测试(maven.yml JDK21、去 -Dmaven.test.skip)、覆盖台账去硬编码、
  BC 边界 ArchUnit 门(BcBoundaryArchTest)、契约先行门(ContractFirstGateTest:Flyway 卫生 + OpenAPI 结构)
- 单一进度源 docs/mvp/进度总账.md + 7 个 BC per-module .agent + mise.toml(锁 JDK21)
- P1 增量:AiSuggestionMergeProjectionFacade(Gap A)、ContentSourceServiceImpl 事务化 outbox 回流(Gap B)

2) 过期历史文档清理(97 份 churn,git 可恢复)
- 删 docs/memorys(34)、agent-specs 审阅/执行版+迁移review(34)、superpowers/plans+specs(25)、
  design-docs/临时+memorys(4);保留 superpowers/reports/coverage(门禁依赖)
- 唯一干货蒸馏入 .agents/knowledge/external-deps-and-gotchas.md;订正大纲/映射表/基线悬空引用

3) P1 harness 验证:消除已登记 BC 违例 ContentMuseWorkOwnerFacade
- content-api 新增只读端口 MuseContentWorkOwnerApi + content-server 实现(读自有 DAL);
  AI 适配器改消费该端口、移除全部 content.dal 依赖,AI 业务规则与 4 消费者不变
- 删除 ArchUnit 豁免 → 门禁收紧(反向红 31 例 / 正向绿;适配器单测 13/0F、端口实现 7/0F)

注:muse-studio/src(SSE 相关 4 文件)与 muse-module-ai/pom.xml(移除孤儿 contract-server)
为本会话之前已存在的未提交改动,非本次工作,未纳入本提交。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-14 04:38:07 -07:00

5.5 KiB

Raw Blame History

CLAUDE.md — oh-my-muse (muse-design-docs)

项目全貌

Muse 是一个 AI 驱动的长篇创作工具，采用四仓架构：

仓库	技术栈	职责
muse-cloud	Java 21 + Spring Boot 3 + PostgreSQL + Yudao Cloud	后端主仓
muse-admin	Vue 3 + Vben Admin + TypeScript	管理端前端
muse-studio	React + Vite + TypeScript	用户端前端
muse-design-docs（本仓）	Markdown + SQL	设计文档 SSOT

本仓职责与项目入口（2026-06-14 订正）

项目级工作入口 = 根 AGENTS.md。本文件聚焦 design-docs（设计文档 SSOT）的写作规范；项目定位/目录/工作协议以 AGENTS.md 为准。 ⚠️ 订正（对抗复盘 A1/R6）：本仓不是“纯设计文档仓”。它是 monorepo，同一 git 工作树内物理承载 muse-cloud/、muse-admin/、muse-studio/ 实现代码（git ls-files muse-cloud 4468 文件、无 submodule）+ CI（muse-cloud/.github/workflows/）。此前“本仓不承载代码/CI”与磁盘事实矛盾，会让 agent 误判可改动边界、绕路产生文档 churn，故订正。

design-docs/ 与 docs/：产品、架构、流程、前端、后端、专题设计的单一事实源（SSOT）；实现代码须反向对齐这些正式文档。
muse-cloud/、muse-admin/、muse-studio/：实现仓代码，可被 agent 修改（遵循各自规范 + .agents/rules/）。
设计文档的 owner 归属与写作规范见下文各节。

开发模式

AI agent 驱动开发：

Agent 负责：编码、测试编写、重构、文档更新
人类负责：架构决策、需求确认、PR review、发布决策
协作模式：人类提出任务 → agent 规划 → 人类确认 → agent 执行 → 人类 review

核心架构决策（已确认）

决策	结论
Governance	按消费者归属拆散，MetaSchema 独立模块
AI 授权隔离	包级隔离 + ArchUnit
Source 传播	事件驱动 + 各模块自治
Candidate Envelope	去掉，简化为来源版本实时对比
needs_recheck	去掉，直接决策 active/disabled
图查询	依赖 RAGFlow GraphRAG
数据库	PostgreSQL
API 版本	X-API-Version Header
实时通信	SSE（AI stream 独立 + 事件统一）
正文保护	自动保存 + IndexedDB 安全网
Block 粒度	场景/小节级
知识确认	默认自动 + 冲突时人工
Entitlement	可变表 + 审计日志
Archive	先同表，后续按量分离

文档编写规范

文件命名

格式：{角色前缀}-{编号}-{主题}.md

角色前缀：产品 / 架构 / 后端 / 前端 / 流程 / 专题 / 临时

规则：

扁平结构，不建子目录（prototypes / memorys 除外）
编号连续，子编号用大写字母后缀（02A、02B）

版本管理

每个文档头部必须包含版本号、更新日期、目标读者、边界说明。每次实质性修改递增版本号。

交叉引用

只允许"链接 + 一句话摘要"，禁止大段复制粘贴。

术语统一

所有术语以 架构-02-核心数据结构与双轨模型.md 为权威定义。

单一归属

每个概念只有一个 owner 文档。归属清单见 design-docs/内容映射表.md 和 design-docs/00-文档大纲.md。

Agent 行为约束

修改文档前

读取 design-docs/内容映射表.md 确认概念 owner
非 owner 文档只能添加引用链接，不能重复定义
检查 design-docs/00-文档大纲.md 了解文档间关系

禁止行为

不在非 owner 文档中重复定义概念
不大段复制其他文档内容
不创建与现有文档职责重叠的新文档
不用临时文档内容反向覆盖正式分册
不在文档中硬编码实现细节（代码路径、类名属于实现仓）

修改后验证

交叉引用完整性：被引用的文档和章节是否存在
术语一致性：与 架构-02 是否一致
版本号和更新日期是否已递增

新增 ADR 规范

新增架构决策记录必须包含：背景、选项（表格）、结论、后果。

新增文档规范

新增前确认：无现有文档覆盖该主题、owner 边界不冲突、在大纲和映射表中注册。

代码质量基线（适用于所有实现仓）

所有代码必须有合理的中文注释
关键业务逻辑（状态转换、事务边界、安全校验）必须有大量中文注释
注释说明 WHY 而非 WHAT
各仓遵循各自的 CLAUDE.md 规范

测试自动化

目标：自动化率 > 90%，人工只复核非标准场景
每次业务代码变更必须评估测试用例的增删改
CI 中测试失败阻断合入

长任务持续性保障

大功能拆为可独立验证的子任务
每个子任务完成后更新 design-docs/memorys/ 留痕
Agent 可从 memorys 和 git log 恢复上下文

关键文件索引

文件	用途
`design-docs/00-文档大纲.md`	文档集导航入口
`design-docs/内容映射表.md`	概念归属和 owner 清单
`docs/dev-baseline/global/01-AI开发管理总则.md`	AI 开发全局规则
`docs/dev-baseline/global/02-跨仓库协作规范.md`	四仓协作规则
`docs/dev-baseline/muse-cloud/CLAUDE.md`	后端开发规范
`docs/dev-baseline/muse-studio/CLAUDE.md`	用户端前端规范
`docs/dev-baseline/muse-admin/CLAUDE.md`	管理端前端规范

Git 工作流

main：稳定基线
feature/*：功能开发
fix/*：缺陷修复
中文提交信息，格式：{类型}({模块}): {描述}

5.5 KiB Raw Blame History Unescape Escape