muse-agent-example/docs/系统架构/新版设计/文件设计/后端-B02-故事世界.md

后端-B02-故事世界：文件合同

本页从目标文件清单投影，共 12 个目标条目。测试身份与行为合同在现行用例清单；文件和目标合同不代表实现或验收已完成。

返回目录 · 完整项目树 · 现行用例清单

本部分文件树

agent-example/
└── src/
    └── muse/
        └── 故事世界/
            ├── __init__.py  # Python 包身份
            ├── 世界设定.py  # 地点、物品、组织、规则及代价
            ├── 事实提案.py  # 抽取增量、真实引用校验及确认参与者
            ├── 人物关系.py  # 人物、关系、弧线、视角与说话特征
            ├── 存储.py  # 故事世界所属记录的 SQL 与版本读写
            ├── 接口.py  # 故事世界公开用例和可导入合同
            ├── 提示词/
            │   └── 抽取章节事实.md  # 按有效结构抽取事实提案
            ├── 时点查询.py  # 叙事时点、读者和角色知情范围
            ├── 来源有效性.py  # 当前证据有效性与复核需求
            ├── 模型.py  # 故事世界稳定对象、外壳及内部状态
            ├── 设定修订.py  # 动态实例保存、版本与影响
            └── 连续性.py  # 事件、动态状态、因果、伏笔与承诺

逐文件合同

src/muse/故事世界/接口.py

• 归属与种类：B02；源码。
• 意图：让调用方通过稳定用例操作故事世界，隐藏模块内部组织。
• 职责：故事世界公开用例和可导入合同。
• 边界：唯一跨模块表面；导出输入输出合同，不暴露私有 SQL 或任意处理器。
• 目标：HTTP、CLI 和编排对相同用例得到一致验证、失败与结果。
• 合同依据：业务公开接口。

src/muse/故事世界/模型.py

• 归属与种类：B02；源码。
• 意图：把故事世界的稳定数据骨架与执行实现分开。
• 职责：故事世界稳定对象、外壳及内部状态。
• 边界：纯模型和状态合同；不联网或写库，不把题材属性写死为类字段。
• 目标：稳定外壳可校验，动态内容携带结构绑定并在所属校验链验证。
• 合同依据：稳定模型。

src/muse/故事世界/存储.py

• 归属与种类：B02；源码。
• 意图：将故事世界的数据访问与版本写入局限在本模块。
• 职责：故事世界所属记录的 SQL 与版本读写。
• 边界：只操作本模块记录并使用调用方事务；不跨 owner 写表或调用模型。
• 目标：版本读写及回滚可验证，不产生第二个独立事务结果。
• 合同依据：模块存储。

src/muse/故事世界/世界设定.py

• 归属与种类：B02；源码。
• 意图：统一世界实体的维护，容纳不同题材。
• 职责：地点、物品、组织、规则及代价。
• 边界：只维护本书世界实例；不把资料和公共方法直接转为事实。
• 目标：沿用已登记生命周期的新类型可编辑、校验、确认和引用。
• 合同依据：专属业务职责。

src/muse/故事世界/人物关系.py

• 归属与种类：B02；源码。
• 意图：维护可演进的人物、关系、视角与弧线。
• 职责：人物、关系、弧线、视角与说话特征。
• 边界：人物属于故事世界；角色智能体配置归 S02，声音样张基线归 B06。
• 目标：人物与关系可按来源和版本追查，人物计划与已发生状态分开。
• 合同依据：专属业务职责。

src/muse/故事世界/事实提案.py

• 归属与种类：B02；源码。
• 意图：把抽取结果与作者确认的事实分开。
• 职责：抽取增量、真实引用校验及确认参与者。
• 边界：只按允许结构形成增量；真实引用由 B02 检查，批准包使用共同事务。
• 目标：无批准不转正，任何已批准关联增量失败都使整包回滚。
• 合同依据：专属业务职责。

src/muse/故事世界/时点查询.py

• 归属与种类：B02；源码。
• 意图：防止未来资料和后来确认的知识倒灌历史任务。
• 职责：叙事时点、读者和角色知情范围。
• 边界：只读指定叙事位置和系统版本内可用事实；不改变确认状态。
• 目标：读者、角色和规划的知情集合可区分并有来源。
• 合同依据：专属业务职责。

src/muse/故事世界/连续性.py

• 归属与种类：B02；源码。
• 意图：让状态、事件、因果和伏笔具有可追查关系。
• 职责：事件、动态状态、因果、伏笔与承诺。
• 边界：维护故事语义及其版本；不把模型评分当事实、不直接写正文。
• 目标：状态变化有依据，承诺的提出、推进和兑现不会混淆。
• 合同依据：专属业务职责。

src/muse/故事世界/来源有效性.py

• 归属与种类：B02；源码。
• 意图：在读取时阻断已失去依据的现行事实。
• 职责：当前证据有效性与复核需求。
• 边界：只判断当前依据与用途；不删除历史，不等待异步标签才失效。
• 目标：唯一依据变化立即停止当前消费，独立或其他有效依据保留。
• 合同依据：专属业务职责。

src/muse/故事世界/设定修订.py

• 归属与种类：B02；源码。
• 意图：让作者修改设定时能评估传播影响。
• 职责：动态实例保存、版本与影响。
• 边界：只修改 B02 实例；动态值经 S04，正式变更经 S01。
• 目标：结构、数据和来源冲突可拒绝，已使用位置可定位。
• 合同依据：专属业务职责。

src/muse/故事世界/提示词/抽取章节事实.md

• 归属与种类：B02；源码。
• 意图：为故事世界的“抽取章节事实”任务提供可版本化表达。
• 职责：按有效结构抽取事实提案。
• 边界：仅定义本任务提示；角色身份、字段结构、权限和预算从各自权威装配。
• 目标：模板可随发布包加载且记录哈希，不含固定作品内容或测试答案。
• 合同依据：业务提示资源。

src/muse/故事世界/__init__.py

• 归属与种类：工程；源码。
• 意图：明确安装包和模块的导入身份。
• 职责：Python 包身份。
• 边界：只声明包及必要公开导出；不读取运行数据、连接网络或启动任务。
• 目标：正常安装后可从任意 cwd 导入，导入无运行副作用。
• 合同依据：Python 包身份。