108 lines
11 KiB
Markdown
108 lines
11 KiB
Markdown
# AGENTS.md —— agent-example 项目工作入口
|
||
|
||
> 适用范围：本文件只约束 `agent-example/`。用户及上级提供的通用工程规则继续生效；本仓所需的批次、验证与交付约定见[计划与提交](.agent/rules/计划与提交.md)，不依赖检出目录外的规则文件。
|
||
> **技能发现入口（必读）**：读完本文件后必须读 [`.agent/skills/目录.md`](.agent/skills/目录.md)（技能目录）；需要某项能力时，按目录的“相对地址”读取对应 `SKILL.md`。发现只靠 AGENTS.md → 技能目录 → SKILL.md 的渐进披露，不依赖任何宿主的技能自动发现。
|
||
> **作者创作入口（按需）**：作者用自然中文提出定故事、排故事、塑人物、续写、修改或诊断请求时，先读 [`.agent/作者/指令.md`](.agent/作者/指令.md)，再只打开命中的一个场景文件；作者层负责路由，不替代正式技能、角色合同或用户确认。
|
||
|
||
---
|
||
|
||
## 1. 项目定位与物理事实
|
||
|
||
`agent-example` 的目标定位是物理位于 `oh-my-muse` 内、拥有独立 `.git/` 的单用户缩小版 Muse，以 PostgreSQL 为正式内容权威。
|
||
|
||
- **正式内容权威**：PostgreSQL（连接目标由当前运行配置明确选择，见[运行手册](docs/运行手册.md)）是系统正式内容的唯一权威。作品、章、正文、实体、方法、用户决策及运行回执在库里。raw暂存文件受租约管理，归档后以PG归档及回执为准；私人探索文件不作为正式内容。判断“系统里有没有这个东西”，以库里能不能查到为准；严禁把库外临时文件或快照当作正式内容。
|
||
- **运行态账本**：任务、步骤、调用、预算、事件与回执由 PostgreSQL 维护；旧 SQLite 账本只属于历史实现。对象归属见[存储与对象关系](docs/系统架构/新版设计/数据模型/存储与对象关系.md)。
|
||
- **代码与配置权威**：Git 维护代码、技能、角色提示词、内置结构种子、文档和 DDL。`src/muse/元数据/内置结构/` 的 YAML 是发布输入；运行结构以 PostgreSQL 已发布版本为准。Git 不承担创作数据备份。
|
||
- **能力边界**：由主会话派发角色智能体、技能和确定性工具协作完成创作与治理；不实现管理员、多用户、租户、市场、计费或资产交易。
|
||
|
||
---
|
||
|
||
## 2. 目录导航
|
||
|
||
```text
|
||
agent-example/
|
||
├── .git/ # 独立 Git 仓元数据
|
||
├── src/muse/ # 模块化单体（装配、共享基础与全部业务域）
|
||
├── tests/ # 自动化测试（单元/契约/集成/架构/迁移/端到端 + 夹具）
|
||
├── 工具/ # 工程生成与检查入口（资源打包、接口生成、索引检查）
|
||
├── 配置/ # 无凭据配置模板
|
||
├── web/ # 前端：React/TS 用户工作台
|
||
├── 数据库/ # 数据库迁移脚本与旧库迁移工具链
|
||
├── 部署/ # 部署模板与进程配置
|
||
├── upstream/ # 固定版本的上游协议资料
|
||
├── .github/ # CI 工作流
|
||
├── data/ # 运行文件（不跟踪，不作为源码）
|
||
├── .agent/ # 智能体能力中枢（作者入口、角色提示词、角色合同、方法技能、规则、约束与规范）
|
||
├── docs/ # 设计 SSOT、系统架构、运行手册与历史执行记录
|
||
├── .venv/ # 仓内解释器（uv 管理）
|
||
├── pyproject.toml # 应用包、命令、依赖与检查配置
|
||
├── Makefile # 安装、生成、检查、测试与构建入口
|
||
├── CLAUDE.md # Claude Code 兼容入口，只引用 AGENTS.md
|
||
└── README.md # 安装、启动与日常使用入口
|
||
```
|
||
|
||
---
|
||
|
||
## 3. SoT 与事实源导航
|
||
|
||
SoT 按主题分域，不做跨主题的全局排序。可执行脚本与书面合同不一致时视为缺陷，不得自行拼接两套口径。
|
||
|
||
| 类别 | 载体 / 路径 | 权威职责 |
|
||
|---|---|---|
|
||
| 总体设计 | [总体架构](docs/系统架构/新版设计/总体架构.md) | 本仓模块、对象归属、依赖和运行边界；外部历史设计不充当当前实现。 |
|
||
| 新版重写目标 | [docs/系统架构/新版设计/目录.md](docs/系统架构/新版设计/目录.md) | 新版主体完整目标设计、元数据、文件职责及研究依据；不据此宣称现有实现已完成。 |
|
||
| 领域 SoT | [阅读指南](docs/系统架构/新版设计/阅读指南.md) | 按主题定位现行业务领域、数据权威与协作合同。 |
|
||
| 边界合同 | [总体架构](docs/系统架构/新版设计/总体架构.md) | 组件职责边界、跨域公开接口与约束归属。 |
|
||
| 角色合同 | [`.agent/角色/角色合同.md`](.agent/角色/角色合同.md) | 5 个角色（写手/规划/抽取/检测/裁判）的稳定输入边界、模型策略、工具权限与派发合同。 |
|
||
| 结构契约 | [内置结构](src/muse/元数据/内置结构/) | 24 型的内置种子与发布输入；公共字段不是独立类型。运行实例遵守库内已发布结构版本。 |
|
||
| 创作导读 | [关键旅程](docs/系统架构/新版设计/调用链路/关键旅程.md) | 创作流转、门禁、人机边界及正式内容的确认路径。 |
|
||
| 技能目录 | [技能目录](.agent/skills/目录.md) | 方法和操作入口；以各组实际 SKILL.md 及目录发现，不维护另一份虚构清单。 |
|
||
| 创作链条 | [流程登记](src/muse/编排/流程登记.py)、[流程版本](src/muse/编排/流程版本.py)、[槽位约束](src/muse/编排/槽位约束.py) | 当前流程模板、冻结版本和角色槽位约束；旧 muse/lifecycle/flow/chains 已退出。 |
|
||
| 红线约束 | [作者主权](.agent/约束/作者主权.md)、[约束目录](.agent/约束/目录.md) | 数据权威、作者确认、读取范围与外部调用边界。 |
|
||
| 执行流程 | [模块依赖](.agent/rules/模块依赖.md)、[计划与提交](.agent/rules/计划与提交.md) | 模块边界、任务依赖、分层验证和批次收尾。 |
|
||
| 子代理交付 | [`.agent/rules/子代理交付.md`](.agent/rules/子代理交付.md) | 派发子代理的交付物形状：三要素交付、证据指针、仅阻断级汇报、最小必读。 |
|
||
| 审查标准 | [审查标准](.agent/规范/审查标准.md) | 由专项检查附录确认的提示词四问、技能七问和严重度；不冒称恢复缺失的旧 D8 原文。 |
|
||
| 工程规范 | [规范目录](.agent/规范/目录.md)、[审校与修订](.agent/rules/审校与修订.md) | 命名、术语、中文正文及受控修订的现行规范。 |
|
||
| 任务与沉淀 | [`docs/`](docs) | 单次任务探索、计划、评测资料与历史执行证据；稳定结论回填 SoT。 |
|
||
|
||
---
|
||
|
||
## 4. 工作协议（硬约束）
|
||
|
||
1. **读后动手与渐进发现**：复杂任务先读对应 SoT；涉及角色时读角色合同。技能发现遵守本文件开头的唯一入口，按当前任务展开，不预载无关资料。
|
||
2. **机械验证优先与完成=验证**：工程统一使用仓内解释器 `.venv`（uv 管理）；日常唯一入口为 `make 快检 范围=<受影响路径>`（秒级，开发期）；离线全套 `make 测试`（~70秒）；仅改动存储/迁移/触发器时跑对应模块的库测试。**全量数据库测试高耗时高耗盘，严禁未经用户明确请求擅自执行**：`make 验收数据库` 与全量 `make 数据库测试` 必须由用户显式触发（需传入 `MUSE_RUN_FULL_DB=1` 确认）；浏览器层走 `make 浏览器测试`。日常以模块快检或模块局部数据库测试为完成证据，无证据严禁声称“完成/修复/通过”。
|
||
3. **数据权威与先审后入**：数据库为唯一正式权威，严禁裸连操作；正文、规划与知识抽取默认生成 Shadow 候选，经用户明确确认后方可写入 Canonical 正典事实。
|
||
4. **模型治理与受控探索**：模型调用遵守[预算管理](src/muse/任务运行/预算管理.py)的固定日界窗口（默认 Asia/Shanghai，每日00/05/10/15/20开始，末窗20至24为4小时）与受控治理链；角色允许模型与策略版本以[角色策略](配置/角色策略.yaml)为准，并遵守[角色合同](.agent/角色/角色合同.md)（写手/规划固定顶级推理模型，裁判使用独立精确白名单）；确定性逻辑、门禁与报告组装由脚本完成，严禁调用模型；智能体探索仅限圈定只读工具并留痕。
|
||
5. **会话交互与汇报纪律**：全程使用简体中文白话，坚决去除 AI 味（直陈事实、动作与后果，禁止清嗓子套话与空转缓冲词）；需要用户决策时，必须交代清楚前因后果及各选项对下游的影响。
|
||
6. **提交授权与整体审查**：严禁未经用户明确授权执行 `git add` 或 `git commit`；按[计划与提交](.agent/rules/计划与提交.md)预先确定交付批次，L3 重任务批次（判据及验证分层见同一规则）门禁通过后由独立只读子代理完成四维整体审查，通过前不得宣布该批完成，L1/L2 批次以门禁绿加抽查代替；不逐笔提交叠加审查，必要的事前方案评审、修复重审和最终集成验收仍保留；框架与创作内容分开审查、分开提交。
|
||
7. **计划边界与提交节奏**：以可独立验收的完整结果拆任务，明确边界、依赖、维护者与验证方式；前置满足且有收益的独立任务分工并发，依赖任务按已验证能力衔接；验证不过不收尾，获授权后每个完整任务单独提交。具体编排、隔离和批次收尾以[计划与提交](.agent/rules/计划与提交.md)为准。
|
||
|
||
---
|
||
|
||
## 5. 交付与经验沉淀
|
||
|
||
- 创作方法和规则沿[审校修订](docs/系统架构/新版设计/模块设计/B06-审校修订.md)、[作者经验](docs/系统架构/新版设计/模块设计/B07-作者经验.md)的候选、评测与批准链承接，不自动写入正式内容或沿用旧豁免。
|
||
- 工程交付按[计划与提交](.agent/rules/计划与提交.md)同步所属权威合同，按[文档与资源生成](.agent/rules/文档与资源生成.md)维护受影响索引并验证，清理被替代实现、重复路径、旧配置与无用途测试；有兼容、迁移、回滚或追溯用途的内容保留并注明用途。
|
||
|
||
---
|
||
|
||
<!-- my-skills-cli:begin -->
|
||
## 项目 harness
|
||
|
||
先读本表，再打开对应目录的 `目录.md`，按其中清单读取具体文件。
|
||
不要按宿主框架另建一套规则，也不依赖宿主的 skill 自动发现。
|
||
|
||
| 类别 | 读 | 说明 |
|
||
|------|-----|------|
|
||
| 项目设计与实施 | `docs/目录.md` | 架构、方案、实施计划/Runbook、模块概要与回顾（人机共读） |
|
||
| 团队规则与技能 | `.agent/目录.md` | 团队长期生效的硬规则、约束、代码规范与专属 Skill（<名>/SKILL.md 格式） |
|
||
| 个人配置 | `.agents.local/AGENTS.md` | 存在则先读：个人指令集、skill、草稿、便签（默认不提交） |
|
||
|
||
### 维护纪律
|
||
|
||
代码变更以现行架构、领域模型、ADR、规范与测试为准，保持可读、简单、局部，不凭空叠加抽象；清理和沉淀按本文件§5执行。
|
||
|
||
纳入版本控制：`AGENTS.md`、`docs/`、`.agent/`；实际暂存和提交仍须明确授权。
|
||
不提交：`.agents.local/`、`.claude/`、`.codex/`、`.pi/`、`.opencode/`、`.cursor/`。
|
||
<!-- my-skills-cli:end -->
|