329db944ff
排查发现进度数字三套互相矛盾:总览/现状基线/主台账历史段=147/86、agent-specs=100/127、module-reality=233/0。核机械真值:覆盖 JSON summary=233/233 completed/0 needs(每 op 带 testFiles 证据 + P1rApiCoverageReportTest 校验 summary 自算防手工拨)。⚠️ JSON generatedAt=2026-05-25 未随内容刷新(手工维护痕迹),已在文档标注以 summary+testFiles 为准。
修正:① 总览(我上轮新建,误抄过时台账)147/233→233/233、各域 full、接口门≠端到端两口径分清、定位为人读封面(权威以台账/JSON为准);② 主台账 头部加机械源口径声明(233/0)+门禁中→满+验收债标已清零;③ 现状基线降级为 2026-06-13 历史快照(顶部时效横幅+性质去SSOT);④ AGENTS序2/module-reality 改引用;⑤ agent-specs/.agent 注记历史数字;⑥ meta-schema review 回指 execution v0.2 已证伪地基(待决策提案);⑦ design-docs/00 加'设计≠进度';⑧ dev-baseline 申明旧 SSOT 自称失效。
确立单一真实源:设计=design-docs;进度=进度总账(叙述)+覆盖JSON(机械);人读=项目功能与进度总览(封面)。
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
101 lines
7.4 KiB
Markdown
101 lines
7.4 KiB
Markdown
# AGENTS.md —— oh-my-muse(Muse)· Agent 工作入口
|
|
|
|
> **本项目以 AI 驱动开发。** 无论你是 AI agent 还是工程师,**每个任务都从这里开始**。
|
|
> 本文件是**项目唯一事实源**:既答"这是什么项目"(定位/目录),也答"怎么在这里干活"(先读什么、守什么规则、怎么把经验沉淀回去)。
|
|
> 能力细节在 [`.agents/`](.agents/);`CLAUDE.md` 是 design-docs(设计 SSOT)的写作规范,从属本文件。
|
|
|
|
---
|
|
|
|
## 1. 项目定位
|
|
|
|
**Muse = AI 驱动的长篇创作工具**(Shadow→Canonical 主权:AI 产出经"先审后入"才进入正式正文)。四仓协作,采用 monorepo 承载。
|
|
|
|
| 仓 | 技术栈 | 职责 |
|
|
|---|---|---|
|
|
| muse-cloud | Java 21 + Spring Boot 3 + PostgreSQL + Yudao 框架 | 后端(9 业务域 muse-module-*) |
|
|
| muse-admin | Vue 3 + Vben Admin + TS | 管理端前端 |
|
|
| muse-studio | React + Vite + TS | 用户端前端 |
|
|
| design-docs / docs | Markdown + SQL | 设计 SSOT / agent 规格与基建 |
|
|
|
|
业务域:`account(member)` / `ai` / `content` / `knowledge` / `market` / `meta` / `events` + 平台底座。
|
|
|
|
---
|
|
|
|
## 2. ⚠️ 仓库物理事实(2026-06-14 订正,对抗复盘 A1/R6)
|
|
|
|
**本仓是 monorepo,物理承载实现代码,不是"纯设计文档仓"。**
|
|
|
|
- `git ls-files muse-cloud` = 4468 文件、无 `.gitmodules` → `muse-cloud/`、`muse-admin/`、`muse-studio/` 三个实现仓代码**就在本工作树里、被本仓版本控制**;既有 Maven CI 在 `muse-cloud/.github/workflows/`,OpenAPI diff 因自建 Gitea Actions 扫描规则已接到仓库根 `.github/workflows/`。
|
|
- 因此:**agent 可以也应当修改这些实现代码**(遵循各自规范 + [`.agents/rules/`](.agents/rules/))。此前"本仓不承载代码/CI"的描述与磁盘矛盾,会让 agent 误判改动边界、绕路产生文档 churn,已订正。
|
|
- `design-docs/`、`docs/` 是设计/规格 SSOT;实现代码须反向对齐其正式文档。
|
|
|
|
---
|
|
|
|
## 3. 目录导航
|
|
|
|
```
|
|
oh-my-muse/
|
|
├── AGENTS.md # 本文件:项目入口(唯一事实源)
|
|
├── CLAUDE.md # design-docs 写作规范(从属本文件)
|
|
├── .agents/ # Agent 能力中枢(knowledge/rules/skills/workflows;见 .agents/README.md)
|
|
├── muse-cloud/ muse-admin/ muse-studio/ # 三实现仓代码(可改)
|
|
├── design-docs/ # 产品/架构/前后端/流程/专题 设计 SSOT + 内容映射表/大纲
|
|
└── docs/
|
|
├── agent-specs/ # 现状基线 + 对抗复盘 + P0 冻结令 + 六砖交付(过程 churn 已清理)
|
|
├── mvp/进度总账.md # 进度单一事实源(+ 历史交付时间线)
|
|
├── api-contracts/ # 各域 OpenAPI = API 契约 SSOT(原地;见 .agents/rules/contract-first.md)
|
|
├── dev-baseline/ # 早期规范历史归档(已收敛进 .agents/rules;见 README)
|
|
└── memorys/ # 已归档清理(见 README);进度改用 mvp/进度总账.md
|
|
```
|
|
|
|
---
|
|
|
|
## 4. 任务前必读
|
|
|
|
| 序 | 文档 | 作用 |
|
|
|---|---|---|
|
|
| 0 | [`docs/项目功能与进度总览.md`](docs/项目功能与进度总览.md) | **人读全局**:功能清单 + 进度表 + 待办表(一眼看全局;详细流水仍在 `mvp/进度总账.md`) |
|
|
| 1 | [`.agents/rules/verification-and-anti-false-green.md`](.agents/rules/verification-and-anti-false-green.md) | **脊柱规则**:完成=机械验证、机械门禁优先、反假绿 |
|
|
| 2 | `docs/agent-specs/2026-06-13-项目目标与模块现状基线.md` | 项目目标 + 模块现状(**2026-06-13 历史快照**;当前现状以序0总览 / 主台账 / 覆盖 JSON 为准) |
|
|
| 3 | `docs/agent-specs/2026-06-13-目标达成对抗复盘.md` | 失控根因(假绿)与重定路径 |
|
|
| 4 | [`.agents/README.md`](.agents/README.md) | 能力中枢导航 |
|
|
| 5 | design-docs(`00-文档大纲.md` 入口 + `架构-01/02`、`后端-01`) | 设计事实 |
|
|
|
|
---
|
|
|
|
## 5. 工作协议(硬约束)
|
|
|
|
1. **读后动手**:复杂任务先读 [`.agents/`](.agents/) 与相关 `docs/`,对齐事实再开工。
|
|
2. **机械门禁优先 / 完成=验证**:遵守 [`verification-and-anti-false-green`](.agents/rules/verification-and-anti-false-green.md)——无自动化绿证据不得声称完成;新规则必配机械门禁,不靠自觉。
|
|
3. **复杂/高危先评审**:跨模块 / 改用户可见行为 / 触外部服务·支付·数据 → 评审版 → 两轮评审 → 执行版,再写代码。
|
|
4. **契约先行**:改接口/数据结构先改契约(API=`docs/api-contracts/*`、DB=新增 `sql/muse/V*.sql`,均为原地 SSOT)再实现;遵守 [`contract-first`](.agents/rules/contract-first.md),已有 Flyway 卫生 + OpenAPI 结构机械门禁(openapi-diff 已接 root workflow,远端首跑待确认)。
|
|
5. **最小改动 + 中文注释**:只动相关代码,复用既有模式,不顺手重构;代码全简体中文注释,关键路径可追溯日志。
|
|
6. **无孤儿/拼接设计**:任何新结构/接口/模型须带入口、使用路径、失败路径、验收标准。
|
|
7. **证据规则**:区分已验证事实/推断/假设;无证据不声称"完成/修复/通过"。
|
|
|
|
---
|
|
|
|
## 6. 知识沉淀机制(也是硬约束 —— 复利的来源)
|
|
|
|
`.agents/` 的价值在于**复利**:让"越往后开发越快越准"。因此:
|
|
|
|
- **每次有价值的交付后,把可复用产出回写对应层**:新事实→`knowledge/`;新硬约束(必配门禁)→`rules/`;新操作手册→`skills/`;流程改进→`workflows/`。
|
|
- **先查重再新增**;过时即修正/删除;结构性变更**同步 [`.agents/README.md`](.agents/README.md) 索引与本文导航**。
|
|
- **进度只进 [`总账`](docs/mvp/进度总账.md) + per-module `.agent`,不再新增“状态推进”过程文档**(过程文档 churn 是失控来源之一)。
|
|
|
|
> 无沉淀的任务是"一次性消耗";有沉淀,下一个同类任务在已有成果上更快更准地推进。
|
|
|
|
---
|
|
|
|
## 7. 当前基建建设状态(随建随更)
|
|
|
|
- ✅ 机械门禁地基:CI 真跑测试(JDK21、触发分支已修为 `main`——此前误配 `master` 致 CI 从不运行)、门禁去硬编码(含分域计数派生化)、P0 冻结令。
|
|
- ✅ 入口与中枢骨架:本文件 + `.agents/README.md` + 脊柱规则。
|
|
- ✅ BC 边界 ArchUnit 门([`bc-boundaries`](.agents/rules/bc-boundaries.md)):**通用覆盖全业务 BC 间方向**;AI/knowledge 直连 content、market 直写 member 三处违例**均已整改消除**,豁免清单 `KNOWN_VIOLATION_EXEMPTIONS` **清空 → 全绿**(0 Architecture Violation;遗留:market-server pom 仍依赖 member-server,仅消除了 .dal 代码 import,见该规则 §三)。
|
|
- ✅ 契约先行门([`contract-first`](.agents/rules/contract-first.md)):Flyway 迁移卫生 + OpenAPI **存在性/结构**(注:挡不住语义破坏;openapi-diff root workflow 已接线,需远端首次 PR 运行验证)。
|
|
- ✅ loop 机械牙([`AgentsInfraIntegrityTest`](muse-cloud/muse-server/src/test/java/cn/iocoder/muse/server/framework/arch/AgentsInfraIntegrityTest.java)):每业务 BC 有 `.agent`、README 索引每篇 `.agents` 文档、总账在——把写回/索引同步从自觉变机械。
|
|
- ✅ knowledge 蒸馏 / skills / workflow(AI 开发协议)/ 进度总账 + 7 BC `.agent`。
|
|
- ⏳ 后续:openapi-diff 远端 CI 首跑验证、Meta/schema 投影真实化、前端深页继续关 MSW 活体验收。`dev-baseline` 收敛进 rules、`completed=测试证据`兜底(testFiles)、跨域 `.application` 边界、market-server→member-server pom 坐标收口、ai/平台预存红测试整改均已完成。
|
|
|
|
> 进度只进 [`docs/mvp/进度总账.md`](docs/mvp/进度总账.md) + 各模块 `.agent`,不新增状态过程文档。
|