b0bc7a8745
一、技能重组（动作-对象命名） - 旧目录 clean/confirm/continuation/db/detect/embed/… 重组为 clean-book-text/decide-candidate/write-next-chapter/access-database/ check-content-consistency/embed-knowledge/…（git 识别为 rename，内容保持） - agents/*.md、AGENTS.md/CLAUDE.md 收编、example_skill 登记表同步新名 二、先审后入创作闭环（本次核心） 正文接受从"机械门一过就写正典"改为"机械门+语义审查双通过+用户批准+单事务原子提交"， DB 级兜底，编排层跳步即被硬拒。 - candidate_cas.py + example_candidate_cas(109)：持久化 CAS 状态链 - fact_delta.py + example_fact_delta/example_fact_ledger(106)：结构化事实增量， 模型只提六型闭集增量+正文证据引文，仅用户批准的增量随正文同事务入账本 - projection_registry.py + example_projection_run(107)：投影登记与恢复 - acceptance_state.py：接受前置实时状态重读 - lesson_registry.py + example_lesson(108)：经验升格链，禁止自动升格 - DDL 105：example_candidate 增 semantic_status/semantic_report_sha256 - write_canonical.accept：语义兜底+同事务合并增量+登记投影； run_writer_pipeline/persist_writer_run/run_writer_semantic_detector/step2 接入全链 - claude_runtime：兼容新 CLI modelUsage 信息字段 三、审查修复（独立子代理四维审查后） - 事实增量 propose→approve 翻态正道，不撞唯一键 - 冻结配置探针重刷（CLI 2.1.211→2.1.231 漂移），profileSha256/adapterVersion 再登记 - 可视化合同悬空路径/五六空间矛盾、 SoT 旧技能名漂移、行尾空白清理 测试：离线 65 套 + 真实库集成 5 套（CAS/接受故障注入/事实增量/投影/经验升格）+ 回放 79 项全绿。 创作内容（docs/design、生成正文 artifacts）按"框架与创作分开"未入本提交。
8.3 KiB
8.3 KiB
agent-example 领域设计索引
SoT 状态：本目录是
agent-example领域边界、数据权威和领域协作合同的唯一事实来源。父仓design-docs/继续拥有完整 Muse 产品、业务和总体架构；本目录只定义单用户缩小版 Muse 的实现边界。 本版把数据权威从“Git 文件”改订为“PostgreSQL”，以对齐已经建成的实现：正式内容都在库里，Git 退回代码与文档的家，另有一个只读看板随时把库里的一切渲染给人看。
1. 项目目的
agent-example 是一个由 ReAct Agent 驱动的单用户长篇小说创作系统。它依靠 PostgreSQL、Git、Agent、Skill、确定性工具和一个只读可视化看板完成：
- 创建和维护作品。
- 管理作品实体与叙事状态。
- 沉淀、验证和复用写作范式。
- 规划、生成、审核、接受和修订正文。
- 从作品证据中持续升级 Agent、Skill、规则与范式。
2. 数据权威（本次重订的核心）
- PostgreSQL（
muse-example库）= 正式内容权威（SoT）。作品、章、正文、实体、范式、用户决策、运行回执，以及完整原文、完整问答、标准答案、供应商响应这类 raw，都记录在库里。 - Git = 代码、Skill、Agent 提示词、
meta/（schema 与 chains）、文档、DDL 的权威，以及这些的版本历史与备份。Git 不再是“正式内容”的权威。 - 库内向量索引（pgvector）= 数据库一侧的检索加速，不是独立权威，可从库重建。
- 数据库是权威，意味着可恢复性靠数据库备份、快照或可重建脚本，加上 Git 里的代码与 DDL 从零重建库结构。不再承诺“删掉数据库零丢失”，也不再要求“本地文件模式”为必选。
3. 横切合同：一切输入产出必须落库可见
这是全系统硬纪律，本索引是唯一 owner，各领域文档只引用、不重复定义：
- 每个输入都要落库：用户意图、规划、细纲、冻结的上下文、范式选择、模型调用的提示词与执行配置。
- 每个产出都要落库：AI 候选正文、检测与评分结果、用户的接受/合并/丢弃决策、每次运行的回执、补证与重写记录、实体与范式草稿、完整原文与完整问答。
- 没落库的，等于系统视角里不存在。只读看板看不到，就是没记录。
- 落库由现有管线和 Skill 负责；只读可视化模块只查库、只渲染，不写任何数据。
- 单一基底、分层权威、分区治理：库是唯一存放处（基底统一），但正式内容与评测区是不同治理区。评测的独立性由
run_type+ 四层隔离 + oracle + 盲评 + 人审承载，不由物料位置承载。“一切落库”是基底主张，不是“库是无差别统一体”。（harness 改造原则，见 docs/2026-08-01-评测harness改造设计）
4. 只读可视化模块
- 一个纯 Python 标准库的本地 web 看板（web 层零框架、零新增依赖；psycopg 复用
.venv现成的，非标准库），内网或 Tailscale 访问，形态参照 open-wenmo。 - 只对数据库做只读查询并渲染，不触发任何写操作；接受、丢弃等写操作仍由
decide-candidateSkill 和主会话走，看板只展示结果。 - 它看到的内容等于库里的内容，因此它倒逼第 3 条“一切落库”。
- 合同细节见 08-数据权威与可视化领域。
5. 三条正交轴
领域采用三条互不替代的观察轴。同一对象可以同时出现在三条轴上，但每份正式数据只能有一个写入 owner。
| 轴 | 回答的问题 | 构成 |
|---|---|---|
| 内容轴 | 系统长期保存什么 | 作品、实体、范式 |
| 生命周期轴 | 内容如何产生并进入正式事实 | 初始化、规划、组装、生成、检查、审核、用户决策、复利 |
| 能力轴 | 谁执行、如何复用、如何被看见 | Agent、Skill、确定性工具、数据库存储、只读看板 |
6. 领域清单
| 领域 | 唯一 owner | SoT |
|---|---|---|
| 作品 | 作品身份、规划、正式正文、生命周期、用户决策记录及其他领域产物在作品内的归档关系 | 01-作品领域 |
| 实体 | 单作品内人物、关系、事件、地点、物品、组织、世界规则、叙事状态事实，以及拆书与作品面实体入库管线 | 02-实体领域 |
| 范式 | 跨作品或限定范围复用的写作方法、适用条件、证据与生命周期 | 03-范式领域 |
| 上下文 | 从作品、实体、范式选择并冻结角色可见输入 | 04-上下文领域 |
| 创作流程 | 从用户意图到待审候选，再到用户决策和正式正文的正向链路；含正文生成前的前期创作五阶段（定盘 → 大纲/卷纲 → 设定拆条 → 范式与文风 → 细纲）及其进入/退出与门禁 | 05-创作流程领域 |
| 质量与复利 | 机械门、语义审查、审核/实验结果合同、场景评分、验证终态和经验升格规则 | 06-质量与复利领域 |
| Agent 与 Skill | 角色职责、能力合同、确定性工具及复用标准 | 07-Agent与Skill领域 |
| 数据权威与可视化 | 数据库权威层级、输入产出落库机制、raw 进库与访问控制、只读看板、可恢复性 | 08-数据权威与可视化领域 |
7. 总体协作
用户意图
-> 创作流程域前期阶段：定盘 -> 大纲/卷纲 -> 设定拆条 -> 范式与文风 -> 细纲
（各阶段候选先 shadow、用户确认翻 confirmed 才进生成上下文；详见 05 §1A）
-> 作品域提供目标、规划与最新正式正文
-> 实体域提供正式事实和叙事状态
-> 范式域提供经验证的写法参考
-> 上下文域从库里选择、裁剪、冻结并投影
-> Agent/Skill 域执行规划、写作、检测和审核
-> 创作流程域维护候选、用户决策与正式正文边界
-> 质量与复利域产出检查、审核、实验和升格结论
-> 数据权威域把上述一切输入产出落库
-> 只读看板随时把库里的状态渲染给人看
模型运行失败可以阻断当次 AI 任务，但不能损坏库里已有的作品、实体、范式。库内检索加速失败只影响速度，不改变内容语义、不跳过审核。
8. raw 边界（已翻转）
- 完整 Prompt/Response、未接受候选正文、标准答案、原书全文、供应商原始响应：进库（单独表 + 访问控制），只读看板可看全文。
- 不再要求 raw 留仓外；仓外 vault 降级为可选备份，不是合同要求。
- 密钥、token 和外部凭据仍不得写进内容表或运行报告；连接凭据按内网授权方案放在 Git 侧的受控文档里。
9. 明确不做
- 不实现管理员控制台、租户、角色权限、市场、计费、资产交易或多用户协作。
- 不复制父仓完整业务有界上下文。
- 可视化模块不写库。
- 不做多租户参考书授权机制：
db/ddl/96授权快照表不启用（单用户本地，授权人/使用者/机器是同一人，重型授权合规是从父仓过度继承）；参考书出处与导入信息用example_reference_work/muse_knowledge_document即可（2026-07-30 拍板）。 - 不再声称 Git 是正式内容权威，也不再承诺“删库零丢失”或“本地文件模式必选”。