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 b9af240b68 R2 收尾：W30 唯一写入观察与最终验收（C08 章后接通 / 构建身份重建 / 最终备份与恢复演练） 
- 章后处理：事实提案命令身份加入类型、批内去重改为先校验后去重（REPEAT_OBJECT_TYPE 记跳过、不再静默丢重复）；查询章后状态回传事实跳过；可按需发布/核对可登记任务与 config_not_declared 语义收紧
- 模型治理：推理字符数计量（ChatCompletions/Messages/执行合同）、探针在声明关闭推理却仍有推理时拒绝、计价支持缓存协议与未知模型兜底
- 运行态：资源包重建（发布身份 21d850f7…），三处配置同步，post-extract v5 代次 5 启用，服务 PID 96675（health/ready 通过）
- 门禁：make 检查通过；离线 1008 passed；定点数据库 101 passed；最终完整备份 bkp-1f5591d8… 与空库恢复演练 verified（152 表/158 关系/迁移 45，演练库已 DROP）
- 文档与证据：运行手册、功能覆盖、工作包清单 W30 证据、测试用例清单（17 条 execution_evidence 回填 + 历史死指针说明）、目标文件清单
- 旧实现与旧库直连材料退出（含明文凭据文件移除）；新配置 配置/本机正式.toml、配置/本机维护.toml、配置/计费/、配置/运行配置/ 入库，均只含受控引用
- R2 执行证据在 .agents.local/改造/R2-20260909/（不入库）
2026-09-16 08:23:39 +08:00

11 KiB
Raw Blame History

AGENTS.md —— agent-example 项目工作入口

适用范围：本文件只约束 agent-example/。父仓 ../AGENTS.md（原路径 ../AGENTS.md，已随旧实现退出，见固定基线） 的通用工程、证据和协作规则继续生效；本文件只补充本地创作仓的规则，不重复父仓规范。 技能发现入口（必读）：读完本文件后必须读 .agent/skills/目录.md（技能目录）；需要某项能力时，按目录的“相对地址”读取对应 SKILL.md。发现只靠 AGENTS.md → 技能目录 → SKILL.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。
  • 代码与配置权威：Git 是代码、技能、智能体提示词、muse/content/meta/schemas/、文档和 DDL 的权威，并对作品信息和文本留痕备份；但 Git 留痕不是正式内容权威，正式内容以数据库为准，只读看板只读库，两者冲突时以库为准。
  • 能力边界：由主会话派发角色智能体、技能和确定性工具协作完成创作与治理；不实现管理员、多用户、租户、市场、计费或资产交易。

2. 目录导航

agent-example/
├── .git/                   # 独立 Git 仓元数据
├── src/muse/               # 模块化单体（装配、共享基础与全部业务域）
├── tests/                  # 自动化测试（单元/契约/集成/架构/迁移/端到端 + 夹具）
├── 工具/                   # 工程生成与检查入口（资源打包、接口生成、索引检查）
├── 配置/                   # 无凭据配置模板
├── web/                    # 前端：React/TS 用户工作台
├── 数据库/                 # 数据库迁移脚本与旧库迁移工具链
├── .agent/                 # 智能体能力中枢（作者入口、角色提示词、角色合同、方法技能、规则、约束与规范）
├── docs/                   # 设计 SSOT、系统架构、运行手册与历史执行记录
├── .venv/                  # 仓内解释器（uv 管理）
├── pyproject.toml          # 应用包、命令、依赖与检查配置
├── Makefile                # 安装、生成、检查、测试与构建入口
├── CLAUDE.md               # Claude Code 兼容入口，只引用 AGENTS.md
└── README.md               # 安装、启动与日常使用入口

3. SoT 与事实源导航

SoT 按主题分域，不做跨主题的全局排序。可执行脚本与书面合同不一致时视为缺陷，不得自行拼接两套口径。

类别 载体 / 路径 权威职责
总体设计 ../design-docs/（原路径 ../design-docs，已随旧实现退出，见固定基线） Muse 的概念、产品、业务和总体架构 SoT（设计 SSOT）。
新版重写目标 docs/系统架构/新版设计/目录.md 新版主体完整目标设计、元数据、文件职责及研究依据；不据此宣称现有实现已完成。
领域 SoT muse/sot/domains/ 本仓各业务领域边界、数据权威、落库合同与领域协作 SoT（01-08 域）。
边界合同 muse/sot/边界合同.md 组件职责边界与约束归属唯一事实源：智能体/技能/工具 server/主代理职责划分。
角色合同 .agent/角色/角色合同.md 5 个角色（写手/规划/抽取/检测/裁判）的稳定输入边界、模型策略、工具权限与派发合同。
结构契约 muse/content/meta/schemas/（原路径 muse/content/meta/schemas，已随旧实现退出，见固定基线） 23 型结构本体与规划产物的字段合同；库内 payload 结构以此为准。
创作导读 muse/sot/创作周期与Skill导读.md 创作生命周期各阶段流转、门禁、人机分界与技能责任方导读地图。
技能目录 .agent/skills/目录.md / muse/技能目录.md 59 个技能的方法目录与编排目录（物理清单以 skills.json 为准）。
创作链条 muse/lifecycle/flow/chains/（原路径 muse/lifecycle/flow/chains，已随旧实现退出，见固定基线） scenario、purpose、功能 skill、角色槽位和保护节点的链路登记。
红线约束 .agent/约束/红线约束.md 数据权威、探索边界、模型治理与代码提交的不可逾越红线。
执行流程 .agent/rules/执行流程.md 按条件适用的研发职责、分层验证与批次收尾；任务与依赖编排见计划与提交。
审查标准 .agent/规范/审查标准.md 智能体提示词 4 问、技能质量 7 问 + D8 复利审查规程与严重度定义。
工程规范 .agent/规范/ 去AI味道工程规范.md、指令集规范.md、术语规范.md。
任务与沉淀 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 小时额度窗口与受控治理链，角色严格锁定角色合同指定模型（写手/规划固定顶级推理模型，裁判使用独立精确白名单）；确定性逻辑、门禁与报告组装由脚本完成，严禁调用模型；智能体探索仅限圈定只读工具并留痕。
  5. 会话交互与汇报纪律：全程使用简体中文白话，坚决去除 AI 味（直陈事实、动作与后果，禁止清嗓子套话与空转缓冲词）；需要用户决策时，必须交代清楚前因后果及各选项对下游的影响。
  6. 提交授权与形而上审查：严禁未经用户明确授权执行 git add 或 git commit；按计划与提交预先确定交付批次，每批门禁通过后由独立只读子代理完成四维整体审查，通过前不得宣布该批完成；不逐笔提交叠加审查，必要的事前方案评审、修复重审和最终集成验收仍保留；框架与创作内容分开审查、分开提交。
  7. 计划边界与提交节奏：以可独立验收的完整结果拆任务，明确边界、依赖、维护者与验证方式；前置满足且有收益的独立任务分工并发，依赖任务按已验证能力衔接；验证不过不收尾，获授权后每个完整任务单独提交。具体编排、隔离和批次收尾以计划与提交为准。

5. 知识与经验复利机制

系统的核心价值在于复利：每一次创作与开发任务后，系统必须比上一次更强。

  • 创作复利：创作过程中提炼的技法沉淀为范式卡、AI 味规则、声音账与 example_lesson 登记入库，走 06-质量与复利领域 §6 升格链。
  • 工程复利：开发交付后，将稳定设计与规则回写对应 SoT、.agent/规范/、.agent/约束/ 或技能，过时内容及时清理，控制长期熵增。

项目 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/。