zizi-al/muse-agent-example
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
muse-agent-example/AGENTS.md
zizi a7d2746d67 文档: 权威分层登记与合同收敛（含前会话治理文档工作） 
- 登记 SQLite 运行态账本：AGENTS/红线/08域/表映射 四处同口径
  （不产生 Canonical，冲突以 PG 为准）；表映射补 muse.db 八表清单
- web/app.py 按裁决登记为本地人审留痕通道（08域 §6.1，写面闭集）
- rubric 回写四项无条件阻断（_BLOCKING_ADVISORY_CODES 对齐）
- 红线措辞校准：额度窗口真实语义（跨窗续跑/降级/末窗 4h）、
  MUSE_LLM_ALLOW_UNGOVERNED 逃生口登记、抽取角色改治理链口径
- 角色合同登记 blind_judge/semantic_detector 别名与两阶段写手形态
- 文档失实修复：导读旧路径、细纲必填表补 3 字段、schemas/README
  改库内权威世界观、framework/README 登记 claude 适配器、
  harness README 对齐新布局、59 技能计数
- 迁移对账改关联计数（不再写死 reviews=6）
- 四维形而上审查报告（verdict PASS，含独立性局限声明）
- 含前一会话未提交的治理文档工作：AGENTS 重构、审查标准迁移、
  rubric 引用更新、.agent 目录索引更新
- .gitignore 补 muse.db 备份文件规则
2026-08-30 23:06:39 +08:00

99 lines
9.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# AGENTS.md —— agent-example 项目工作入口
> 适用范围：本文件只约束 `agent-example/`。父仓 [`../AGENTS.md`](../AGENTS.md) 的通用工程、证据和协作规则继续生效；本文件只补充本地创作仓的规则，不重复父仓规范。
> **技能发现入口（必读）**：读完本文件后必须读 [`.agent/skills/_index.md`](.agent/skills/_index.md)（方法技能总索引）与 [`muse/_skills_index.md`](muse/_skills_index.md)（编排技能总索引）；需要某项能力时按索引中的 `skill_file` 读对应 `SKILL.md`。发现只靠 AGENTS.md → 总索引 → SKILL.md 的渐进披露，不依赖任何 coding agent 的 skill 自动发现。
---
## 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`](muse/authority/db/表映射.md)。
- **代码与配置权威**：Git 是代码、技能、智能体提示词、`muse/content/meta/schemas/`、文档和 DDL 的权威，并对作品信息和文本留痕备份；但 Git 留痕不是正式内容权威，正式内容以数据库为准，只读看板只读库，两者冲突时以库为准。
- **能力边界**：由主会话派发角色智能体、技能和确定性工具协作完成创作与治理；不实现管理员、多用户、租户、市场、计费或资产交易。
---
## 2. 目录导航
```text
agent-example/
├── .git/ # 独立 Git 仓元数据
├── framework/ # FrameworkPort 通用协议与宿主适配器（Pi / DSH 对照）
├── runtime/ # 宿主无关执行底座（agent_executor / runs）
├── web/ # 本地人审工作台（只读 data/muse.db + 三个受控写端点）
├── .agent/ # 智能体能力中枢（角色提示词、方法技能、规则、约束与规范）
├── muse/ # Muse 业务核心（SoT、内容本体、创作生命周期、权威数据与平台共享库）
├── tests/ # 技能实现测试、架构门禁与回归验证
├── docs/ # 单次任务探索、计划、评测资料、样张与历史执行记录
├── .venv/ # 本地 Python 运行环境
├── requirements.txt # Python 依赖清单
├── CLAUDE.md # Claude Code 兼容入口，只引用 AGENTS.md
└── README.md # 历史概览，不是当前运行态 SoT
```
---
## 3. SoT 与事实源导航
SoT 按主题分域，不做跨主题的全局排序。可执行脚本与书面合同不一致时视为缺陷，不得自行拼接两套口径。
| 类别 | 载体 / 路径 | 权威职责 |
|---|---|---|
| 总体设计 | [`../design-docs/`](../design-docs) | Muse 的概念、产品、业务和总体架构 SoT（设计 SSOT）。 |
| 领域 SoT | [`muse/sot/domains/`](muse/sot/domains/_index.md) | 本仓各业务领域边界、数据权威、落库合同与领域协作 SoT（01-08 域）。 |
| 边界合同 | [`muse/sot/边界合同.md`](muse/sot/边界合同.md) | 组件职责边界与约束归属唯一事实源：智能体/技能/工具 server/主代理职责划分。 |
| 角色合同 | [`muse/sot/角色合同.md`](muse/sot/角色合同.md) | 5 个角色（写手/规划/抽取/检测/裁判）的稳定输入边界、模型策略、工具权限与派发合同。 |
| 结构契约 | [`muse/content/meta/schemas/`](muse/content/meta/schemas) | 23 型结构本体与规划产物的字段合同；库内 payload 结构以此为准。 |
| 创作导读 | [`muse/sot/创作周期与Skill导读.md`](muse/sot/创作周期与Skill导读.md) | 创作生命周期各阶段流转、门禁、人机分界与技能责任方导读地图。 |
| 技能索引 | [`.agent/skills/_index.md`](.agent/skills/_index.md) / [`muse/_skills_index.md`](muse/_skills_index.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/规范/审查标准.md`](.agent/规范/审查标准.md) | 智能体提示词 4 问、技能质量 7 问 + D8 复利审查规程与严重度定义。 |
| 工程规范 | [`.agent/规范/`](.agent/规范/) | [`去AI味道工程规范.md`](.agent/规范/去AI味道工程规范.md)、[`指令集规范.md`](.agent/规范/指令集规范.md)、[`术语规范.md`](.agent/规范/术语规范.md)。 |
| 任务与沉淀 | [`docs/`](docs) | 单次任务探索、计划、评测资料与历史执行证据；稳定结论回填 SoT。 |
---
## 4. 工作协议（硬约束）
1. **读后动手与渐进发现**：复杂任务开工前必须先读 SoT、角色合同与技能索引；技能发现遵循 `AGENTS.md → 索引 → SKILL.md` 渐进展开，不依赖宿主私有文件投影或猜测。
2. **机械验证优先与完成=验证**：遵循父仓反假绿规则，Python 统一使用仓内解释器 `.venv/bin/python`；必须通过相关单元测试、门禁与 `git diff --check`，无自动化证据严禁声称“完成/修复/通过”。
3. **数据权威与先审后入**：数据库为唯一正式权威，严禁裸连操作；正文、规划与知识抽取默认生成 Shadow 候选，经用户明确确认后方可写入 Canonical 正典事实。
4. **模型治理与受控探索**：模型调用严格遵守 5 小时额度窗口与受控治理链，角色严格锁定合同指定模型（写手/规划/裁判固定顶级推理模型）；确定性逻辑、门禁与报告组装由脚本完成，严禁调用模型；智能体探索仅限圈定只读工具并留痕。
5. **会话交互与汇报纪律**：全程使用简体中文白话，坚决去除 AI 味（直陈事实、动作与后果，禁止清嗓子套话与空转缓冲词）；需要用户决策时，必须交代清楚前因后果及各选项对下游的影响。
6. **提交授权与形而上审查**：严禁未经用户明确授权执行 `git add` 或 `git commit`；取得授权后、提交前，必须起独立子代理对真实 `git diff` 进行 4 维形而上审查（**逻辑完整性**、**一致性**、**合理性**、**可行性**），通过后方可提交；框架改动与创作内容分开审查、分开提交。
---
## 5. 知识与经验复利机制
系统的核心价值在于复利：每一次创作与开发任务后，系统必须比上一次更强。
- **创作复利**：创作过程中提炼的技法沉淀为范式卡、AI 味规则、声音账与 `example_lesson` 登记入库，走 [06-质量与复利领域 §6](muse/sot/domains/06-质量与复利领域.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 -->
Reference in New Issue View Git Blame Copy Permalink