9e6f1c4481
- src/muse 新版全模块（装配/共享/上下文/任务运行/作品规划/故事世界/正文写作/审校修订/知识方法/作者经验/效果评测/交付连载/资料研究/正式变更/元数据/接入/基础设施/编排）+ 测试树（单元/契约/集成/架构/迁移/端到端/夹具） - 129 项功能全部实现与自动验证（功能覆盖.json/矩阵），含 W31 补齐的规则与代价/节奏安排/伏笔与承诺 - 旧实现按处置清单退出（702 条中 324 删，保护合同与未迁移条目留存有据）；web/app.py 旧工作台退役，新工作台为唯一写入口 - 数据库/旧库迁移：真实旧库内容批次迁移链（端点守卫/PG作品正文映射/质量资产缺省投影） - 运行手册 docs/运行手册.md；W30 本机服务阶段一已运行（infra PG 为正式内容权威） - R2 执行证据与私有运行材料在 .agents.local/改造/R2-20260909/（不入库）
109 lines
11 KiB
Markdown
109 lines
11 KiB
Markdown
# AGENTS.md —— agent-example 项目工作入口
|
||
|
||
> 适用范围：本文件只约束 `agent-example/`。父仓 `../AGENTS.md`（原路径 ../AGENTS.md，已随旧实现退出，见固定基线） 的通用工程、证据和协作规则继续生效；本文件只补充本地创作仓的规则，不重复父仓规范。
|
||
> **技能发现入口（必读）**：读完本文件后必须读 [`.agent/skills/目录.md`](.agent/skills/目录.md)（方法技能目录）与 [`muse/技能目录.md`](.agent/skills/目录.md)（编排技能目录）；需要某项能力时，按方法目录的“相对地址”或编排目录的“技能文件”读取对应 `SKILL.md`。发现只靠 AGENTS.md → 技能目录 → SKILL.md 的渐进披露，不依赖任何宿主的技能自动发现。
|
||
> **作者创作入口（按需）**：作者用自然中文提出定故事、排故事、塑人物、续写、修改或诊断请求时，先读 [`.agent/作者/指令.md`](.agent/作者/指令.md)，再只打开命中的一个场景文件；作者层负责路由，不替代正式技能、角色合同或用户确认。
|
||
|
||
---
|
||
|
||
## 1. 项目定位与物理事实
|
||
|
||
`agent-example` 的目标定位是物理位于 `oh-my-muse` 内、拥有独立 `.git/` 的单用户缩小版 Muse，以 PostgreSQL 为正式内容权威。
|
||
|
||
- **正式内容权威**：PostgreSQL（`muse-example` 库）是系统正式内容的唯一权威。作品、章、正文、实体、范式、用户决策、运行回执和 raw 都在库里。判断“系统里有没有这个东西”，以库里能不能查到为准；严禁把库外临时文件或快照当作正式内容。
|
||
- **运行态账本**：本地 SQLite（`data/muse.db`，gitignore）是默认派发与单机工作面的运行态账本（2026-08-28 存储裁决）：运行留痕（runs/events）、本地人审（reviews/revisions）、卡片与向量镜像、lesson 本地状态机和外部反馈数据落在其中；它不产生 Canonical，与 PG 冲突时以 PG 为准。表清单见 [`muse/authority/db/表映射.md`](docs/系统架构/新版设计/数据模型/存储与对象关系.md)。
|
||
- **代码与配置权威**：Git 是代码、技能、智能体提示词、`muse/content/meta/schemas/`、文档和 DDL 的权威，并对作品信息和文本留痕备份；但 Git 留痕不是正式内容权威，正式内容以数据库为准，只读看板只读库，两者冲突时以库为准。
|
||
- **能力边界**：由主会话派发角色智能体、技能和确定性工具协作完成创作与治理；不实现管理员、多用户、租户、市场、计费或资产交易。
|
||
|
||
---
|
||
|
||
## 2. 目录导航
|
||
|
||
```text
|
||
agent-example/
|
||
├── .git/ # 独立 Git 仓元数据
|
||
├── src/muse/ # 新版模块化单体（装配、共享基础；业务模块随改造包落地）
|
||
├── tests/ # 新版测试（单元/契约/集成/架构 + 夹具；旧测试树由旧环境运行）
|
||
├── 工具/ # 工程生成与检查入口（资源打包、接口生成、索引检查）
|
||
├── 配置/ # 无凭据配置模板
|
||
├── web/ # 前端：新版 React/TS 工作台（随包建设）+ 旧本地人审工作台 app.py
|
||
├── 数据库/ # 新版迁移与旧库迁移资料（随 W03 起）
|
||
├── framework/ # 旧：FrameworkPort 通用协议与宿主适配器（Pi / DSH 对照）
|
||
├── runtime/ # 旧：宿主无关执行底座（agent_executor / runs）
|
||
├── .agent/ # 智能体能力中枢（作者入口、角色提示词、方法技能、规则、约束与规范）
|
||
├── muse/ # 旧：Muse 业务实现（验收后逐步退出）
|
||
├── docs/ # 设计 SSOT、单次任务探索、计划、评测资料与历史执行记录
|
||
├── .venv/ # 新版仓内解释器（uv 管理）
|
||
├── .venv-旧/ # 旧代码运行环境（requirements.txt 可重建）
|
||
├── requirements.txt # 旧实现 Python 依赖清单
|
||
├── pyproject.toml # 新版应用包、命令、依赖与检查配置
|
||
├── Makefile # 新版安装、生成、检查、测试与构建入口
|
||
├── CLAUDE.md # Claude Code 兼容入口，只引用 AGENTS.md
|
||
└── README.md # 安装、启动与日常使用入口
|
||
```
|
||
|
||
---
|
||
|
||
## 3. SoT 与事实源导航
|
||
|
||
SoT 按主题分域，不做跨主题的全局排序。可执行脚本与书面合同不一致时视为缺陷，不得自行拼接两套口径。
|
||
|
||
| 类别 | 载体 / 路径 | 权威职责 |
|
||
|---|---|---|
|
||
| 总体设计 | `../design-docs/`（原路径 ../design-docs，已随旧实现退出，见固定基线） | Muse 的概念、产品、业务和总体架构 SoT（设计 SSOT）。 |
|
||
| 新版重写目标 | [docs/系统架构/新版设计/目录.md](docs/系统架构/新版设计/目录.md) | 新版主体完整目标设计、元数据、文件职责及研究依据；不据此宣称现有实现已完成。 |
|
||
| 领域 SoT | [`muse/sot/domains/`](docs/系统架构/新版设计/阅读指南.md) | 本仓各业务领域边界、数据权威、落库合同与领域协作 SoT（01-08 域）。 |
|
||
| 边界合同 | [`muse/sot/边界合同.md`](docs/系统架构/新版设计/总体架构.md) | 组件职责边界与约束归属唯一事实源：智能体/技能/工具 server/主代理职责划分。 |
|
||
| 角色合同 | [`muse/sot/角色合同.md`](muse/sot/角色合同.md) | 5 个角色（写手/规划/抽取/检测/裁判）的稳定输入边界、模型策略、工具权限与派发合同。 |
|
||
| 结构契约 | `muse/content/meta/schemas/`（原路径 muse/content/meta/schemas，已随旧实现退出，见固定基线） | 23 型结构本体与规划产物的字段合同；库内 payload 结构以此为准。 |
|
||
| 创作导读 | [`muse/sot/创作周期与Skill导读.md`](docs/系统架构/新版设计/调用链路/关键旅程.md) | 创作生命周期各阶段流转、门禁、人机分界与技能责任方导读地图。 |
|
||
| 技能目录 | [`.agent/skills/目录.md`](.agent/skills/目录.md) / [`muse/技能目录.md`](.agent/skills/目录.md) | 59 个技能的方法目录与编排目录（物理清单以 `skills.json` 为准）。 |
|
||
| 创作链条 | `muse/lifecycle/flow/chains/`（原路径 muse/lifecycle/flow/chains，已随旧实现退出，见固定基线） | scenario、purpose、功能 skill、角色槽位和保护节点的链路登记。 |
|
||
| 红线约束 | [`.agent/约束/红线约束.md`](.agent/约束/作者主权.md) | 数据权威、探索边界、模型治理与代码提交的不可逾越红线。 |
|
||
| 执行流程 | [`.agent/rules/执行流程.md`](.agent/rules/模块依赖.md) | 按条件适用的研发职责、分层验证与批次收尾；任务与依赖编排见[计划与提交](.agent/rules/计划与提交.md)。 |
|
||
| 审查标准 | [`.agent/规范/审查标准.md`](.agent/rules/文档与资源生成.md) | 智能体提示词 4 问、技能质量 7 问 + D8 复利审查规程与严重度定义。 |
|
||
| 工程规范 | [`.agent/规范/`](.agent/规范/) | [`去AI味道工程规范.md`](.agent/rules/审校与修订.md)、[`指令集规范.md`](.agent/规范/命名.md)、[`术语规范.md`](.agent/规范/术语.md)。 |
|
||
| 任务与沉淀 | [`docs/`](docs) | 单次任务探索、计划、评测资料与历史执行证据；稳定结论回填 SoT。 |
|
||
|
||
---
|
||
|
||
## 4. 工作协议（硬约束）
|
||
|
||
1. **读后动手与渐进发现**：复杂任务开工前必须先读 SoT、角色合同与技能索引；技能发现遵循 `AGENTS.md → 索引 → SKILL.md` 渐进展开，不依赖宿主私有文件投影或猜测。
|
||
2. **机械验证优先与完成=验证**：遵循父仓反假绿规则，新版工程统一使用仓内解释器 `.venv`（uv 管理；旧代码用 `.venv-旧`）；日常入口 `make 检查`（格式+类型+模块边界+索引）、`make 测试`（默认离线进程隔离）、`make 数据库测试`（需 `MUSE_TEST_DATABASE_URL`）；必须通过相关单元测试、门禁与 `git diff --check`，无自动化证据严禁声称“完成/修复/通过”。
|
||
3. **数据权威与先审后入**：数据库为唯一正式权威，严禁裸连操作；正文、规划与知识抽取默认生成 Shadow 候选，经用户明确确认后方可写入 Canonical 正典事实。
|
||
4. **模型治理与受控探索**：模型调用严格遵守 5 小时额度窗口与受控治理链，角色严格锁定[角色合同](muse/sot/角色合同.md)指定模型（写手/规划固定顶级推理模型，裁判使用独立精确白名单）；确定性逻辑、门禁与报告组装由脚本完成，严禁调用模型；智能体探索仅限圈定只读工具并留痕。
|
||
5. **会话交互与汇报纪律**：全程使用简体中文白话，坚决去除 AI 味（直陈事实、动作与后果，禁止清嗓子套话与空转缓冲词）；需要用户决策时，必须交代清楚前因后果及各选项对下游的影响。
|
||
6. **提交授权与形而上审查**：严禁未经用户明确授权执行 `git add` 或 `git commit`；按[计划与提交](.agent/rules/计划与提交.md)预先确定交付批次，每批门禁通过后由独立只读子代理完成四维整体审查，通过前不得宣布该批完成；不逐笔提交叠加审查，必要的事前方案评审、修复重审和最终集成验收仍保留；框架与创作内容分开审查、分开提交。
|
||
7. **计划边界与提交节奏**：以可独立验收的完整结果拆任务，明确边界、依赖、维护者与验证方式；前置满足且有收益的独立任务分工并发，依赖任务按已验证能力衔接；验证不过不收尾，获授权后每个完整任务单独提交。具体编排、隔离和批次收尾以[计划与提交](.agent/rules/计划与提交.md)为准。
|
||
|
||
---
|
||
|
||
## 5. 知识与经验复利机制
|
||
|
||
系统的核心价值在于复利：每一次创作与开发任务后，系统必须比上一次更强。
|
||
- **创作复利**：创作过程中提炼的技法沉淀为范式卡、AI 味规则、声音账与 `example_lesson` 登记入库，走 [06-质量与复利领域 §6](docs/系统架构/新版设计/模块设计/B06-审校修订.md) 升格链。
|
||
- **工程复利**：开发交付后，将稳定设计与规则回写对应 SoT、`.agent/规范/`、`.agent/约束/` 或技能，过时内容及时清理，控制长期熵增。
|
||
|
||
---
|
||
|
||
<!-- my-skills-cli:begin -->
|
||
## 项目 harness
|
||
|
||
先读本表，再打开对应目录的 `目录.md`，按其中清单读取具体文件。
|
||
不要按宿主框架另建一套规则，也不依赖宿主的 skill 自动发现。
|
||
|
||
| 类别 | 读 | 说明 |
|
||
|------|-----|------|
|
||
| 项目设计与实施 | `docs/目录.md` | 架构、方案、实施计划/Runbook、模块概要与回顾（人机共读） |
|
||
| 团队规则与技能 | `.agent/目录.md` | 团队长期生效的硬规则、约束、代码规范与专属 Skill（<名>/SKILL.md 格式） |
|
||
| 个人配置 | `.agents.local/AGENTS.md` | 存在则先读：个人指令集、skill、草稿、便签（默认不提交） |
|
||
|
||
### 维护纪律
|
||
|
||
处理任何代码变更时，以项目已有架构、领域模型、ADR、编码规范和测试为准，优先保持代码可读、简单、局部且可维护，禁止无证据叠加抽象；新方案完成后必须清理被替代的实现、重复路径、旧配置、旧测试和文档残留，控制长期熵增。
|
||
|
||
提交：`AGENTS.md`、`docs/`、`.agent/` 全部内容。
|
||
不提交：`.agents.local/`、`.claude/`、`.codex/`、`.pi/`、`.opencode/`、`.cursor/`。
|
||
<!-- my-skills-cli:end -->
|