muse-agent-example/docs/系统架构/新版设计/文件设计/后端-S04-元数据.md

后端-S04-元数据：文件合同

本页从目标文件清单投影，共 36 个目标条目。测试用例的具体规格在独立用例清单；文件和目标合同不代表实现或验收已完成。

返回目录 · 完整项目树 · 用例重写

本部分文件树

agent-example/
└── src/
    └── muse/
        └── 元数据/
            ├── __init__.py  # Python 包身份
            ├── 内置导入.py  # 内置种子幂等登记，保护已存在绑定和扩展
            ├── 内置结构/
            │   ├── chapter.yaml  # chapter 内置结构种子与用途声明
            │   ├── character.yaml  # character 内置结构种子与用途声明
            │   ├── character_relation.yaml  # character_relation 内置结构种子与用途声明
            │   ├── combat.yaml  # combat 内置结构种子与用途声明
            │   ├── craft.yaml  # craft 内置结构种子与用途声明
            │   ├── emotion.yaml  # emotion 内置结构种子与用途声明
            │   ├── event.yaml  # event 内置结构种子与用途声明
            │   ├── faction.yaml  # faction 内置结构种子与用途声明
            │   ├── fine_outline.yaml  # fine_outline 内置结构种子与用途声明
            │   ├── generation_context.yaml  # generation_context 内置结构种子与用途声明
            │   ├── item.yaml  # item 内置结构种子与用途声明
            │   ├── location.yaml  # location 内置结构种子与用途声明
            │   ├── narrative_state.yaml  # narrative_state 内置结构种子与用途声明
            │   ├── novel_work.yaml  # novel_work 内置结构种子与用途声明
            │   ├── outline.yaml  # outline 内置结构种子与用途声明
            │   ├── pacing.yaml  # pacing 内置结构种子与用途声明
            │   ├── power_system.yaml  # power_system 内置结构种子与用途声明
            │   ├── reference_work.yaml  # reference_work 内置结构种子与用途声明
            │   ├── scene.yaml  # scene 内置结构种子与用途声明
            │   ├── scene_pattern.yaml  # scene_pattern 内置结构种子与用途声明
            │   ├── style.yaml  # style 内置结构种子与用途声明
            │   ├── trope.yaml  # trope 内置结构种子与用途声明
            │   ├── work_core.yaml  # work_core 内置结构种子与用途声明
            │   ├── world.yaml  # world 内置结构种子与用途声明
            │   └── 公共字段.yaml  # 共享内容属性及受保护骨架的元描述
            ├── 变更影响.py  # 兼容分类、受影响实例及升级要求
            ├── 字段投影.py  # 展示、编辑、检索、导出和 AI 用途
            ├── 字段校验.py  # 类型、必填、枚举、嵌套和引用结构
            ├── 存储.py  # 元数据所属记录的 SQL 与版本读写
            ├── 扩展合成.py  # 基础结构和只增不改的作品扩展
            ├── 接口.py  # 元数据公开用例和可导入合同
            ├── 模型.py  # 元数据稳定对象、外壳及内部状态
            ├── 类型登记.py  # 类型、粒度、业务归属和生命周期族
            └── 结构版本.py  # 不可变结构发布、启用及固定读取

逐文件合同

src/muse/元数据/接口.py

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

src/muse/元数据/模型.py

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

src/muse/元数据/存储.py

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

src/muse/元数据/类型登记.py

• 归属与种类：S04；源码。
• 意图：支持新内容类型而不复制生命周期实现。
• 职责：类型、粒度、业务归属和生命周期族。
• 边界：只选择已登记实例族；类型不能指定任意模块、表或执行代码。
• 目标：新类型可进入同一编辑、抽取、确认、查询和导出链。
• 合同依据：专属业务职责。

src/muse/元数据/结构版本.py

• 归属与种类：S04；源码。
• 意图：让字段定义变化可追溯而不重解释旧值。
• 职责：不可变结构发布、启用及固定读取。
• 边界：不可变发布与显式启用；不因 global active 改动自动升级旧实例。
• 目标：旧版本可回读，不兼容升级有转换和影响要求。
• 合同依据：专属业务职责。
• 非测试旧文件承接：muse/authority/evidence/skills/访问数据库/scripts/seed_schemas.py；muse/content/entity/skills/ingest/抽取作品知识/scripts/upgrade.py。

src/muse/元数据/扩展合成.py

• 归属与种类：S04；源码。
• 意图：让作品增加题材属性而不破坏基础结构。
• 职责：基础结构和只增不改的作品扩展。
• 边界：按固定版本只增不改；不覆盖系统字段和基础权限。
• 目标：有效结构与哈希可重复生成，冲突扩展被拒绝。
• 合同依据：专属业务职责。

src/muse/元数据/字段校验.py

• 归属与种类：S04；源码。
• 意图：使表单、模型和保存使用同一字段合同。
• 职责：类型、必填、枚举、嵌套和引用结构。
• 边界：执行受支持结构约束；不写实例值，真实引用由 owner 检查。
• 目标：未知字段、类型或枚举错误不能经自由 JSON 放行。
• 合同依据：专属业务职责。
• 非测试旧文件承接：muse/content/entity/skills/ingest/抽取作品知识/scripts/upgrade.py；muse/content/entity/skills/ingest/拆解书稿/scripts/parse_llm.py。

src/muse/元数据/字段投影.py

• 归属与种类：S04；源码。
• 意图：将同一内容按作者和模型用途安全裁剪。
• 职责：展示、编辑、检索、导出和 AI 用途。
• 边界：只计算允许字段；不读取他模块私有表，不扩大来源授权。
• 目标：显示、编辑、检索、导出与 AI 用途分别生效并可解释。
• 合同依据：专属业务职责。
• 非测试旧文件承接：muse/lifecycle/context/skills/准备任务上下文/scripts/assemble_writer_context.py；muse/lifecycle/context/skills/检索知识/scripts/search.py。

src/muse/元数据/变更影响.py

• 归属与种类：S04；源码。
• 意图：在结构升级前识别不兼容数据和消费方。
• 职责：兼容分类、受影响实例及升级要求。
• 边界：分析结构与实例引用的影响；不自动填造新事实或改值。
• 目标：新增必填、更改类型和撤回用途有明确受影响对象。
• 合同依据：专属业务职责。

src/muse/元数据/内置导入.py

• 归属与种类：S04；源码。
• 意图：提供可重复安装的结构种子而不覆盖作者配置。
• 职责：内置种子幂等登记，保护已存在绑定和扩展。
• 边界：幂等登记固定种子版本；不在启动时自动激活新定义。
• 目标：重复导入不重复版本，已有绑定和扩展保持可核对。
• 合同依据：专属业务职责。
• 非测试旧文件承接：muse/authority/evidence/skills/访问数据库/scripts/seed_schemas.py。

src/muse/元数据/内置结构/novel_work.yaml

• 归属与种类：S04；运行资源。
• 意图：保存 novel_work 结构的可审发布输入。
• 职责：novel_work 内置结构种子与用途声明。
• 边界：种子不是当前库内生效定义；不覆盖作者扩展，不用元数据改系统身份。
• 目标：字段、别名、用途与结构版本可导入核对，旧实例仍可解释。
• 合同依据：结构种子。
• 非测试旧文件承接：muse/content/meta/schemas/novel_work.yaml。

src/muse/元数据/内置结构/chapter.yaml

• 归属与种类：S04；运行资源。
• 意图：保存 chapter 结构的可审发布输入。
• 职责：chapter 内置结构种子与用途声明。
• 边界：种子不是当前库内生效定义；不覆盖作者扩展，不用元数据改系统身份。
• 目标：字段、别名、用途与结构版本可导入核对，旧实例仍可解释。
• 合同依据：结构种子。
• 非测试旧文件承接：muse/content/meta/schemas/chapter.yaml。

src/muse/元数据/内置结构/scene.yaml

• 归属与种类：S04；运行资源。
• 意图：保存 scene 结构的可审发布输入。
• 职责：scene 内置结构种子与用途声明。
• 边界：种子不是当前库内生效定义；不覆盖作者扩展，不用元数据改系统身份。
• 目标：字段、别名、用途与结构版本可导入核对，旧实例仍可解释。
• 合同依据：结构种子。
• 非测试旧文件承接：muse/content/meta/schemas/scene.yaml。

src/muse/元数据/内置结构/work_core.yaml

• 归属与种类：S04；运行资源。
• 意图：保存 work_core 结构的可审发布输入。
• 职责：work_core 内置结构种子与用途声明。
• 边界：种子不是当前库内生效定义；不覆盖作者扩展，不用元数据改系统身份。
• 目标：字段、别名、用途与结构版本可导入核对，旧实例仍可解释。
• 合同依据：结构种子。
• 非测试旧文件承接：muse/content/meta/schemas/work_core.yaml。

src/muse/元数据/内置结构/outline.yaml

• 归属与种类：S04；运行资源。
• 意图：保存 outline 结构的可审发布输入。
• 职责：outline 内置结构种子与用途声明。
• 边界：种子不是当前库内生效定义；不覆盖作者扩展，不用元数据改系统身份。
• 目标：字段、别名、用途与结构版本可导入核对，旧实例仍可解释。
• 合同依据：结构种子。
• 非测试旧文件承接：muse/content/meta/schemas/outline.yaml。

src/muse/元数据/内置结构/narrative_state.yaml

• 归属与种类：S04；运行资源。
• 意图：保存 narrative_state 结构的可审发布输入。
• 职责：narrative_state 内置结构种子与用途声明。
• 边界：种子不是当前库内生效定义；不覆盖作者扩展，不用元数据改系统身份。
• 目标：字段、别名、用途与结构版本可导入核对，旧实例仍可解释。
• 合同依据：结构种子。
• 非测试旧文件承接：muse/content/meta/schemas/narrative_state.yaml。

src/muse/元数据/内置结构/world.yaml

• 归属与种类：S04；运行资源。
• 意图：保存 world 结构的可审发布输入。
• 职责：world 内置结构种子与用途声明。
• 边界：种子不是当前库内生效定义；不覆盖作者扩展，不用元数据改系统身份。
• 目标：字段、别名、用途与结构版本可导入核对，旧实例仍可解释。
• 合同依据：结构种子。
• 非测试旧文件承接：muse/content/meta/schemas/world.yaml。

src/muse/元数据/内置结构/location.yaml

• 归属与种类：S04；运行资源。
• 意图：保存 location 结构的可审发布输入。
• 职责：location 内置结构种子与用途声明。
• 边界：种子不是当前库内生效定义；不覆盖作者扩展，不用元数据改系统身份。
• 目标：字段、别名、用途与结构版本可导入核对，旧实例仍可解释。
• 合同依据：结构种子。
• 非测试旧文件承接：muse/content/meta/schemas/location.yaml。

src/muse/元数据/内置结构/faction.yaml

• 归属与种类：S04；运行资源。
• 意图：保存 faction 结构的可审发布输入。
• 职责：faction 内置结构种子与用途声明。
• 边界：种子不是当前库内生效定义；不覆盖作者扩展，不用元数据改系统身份。
• 目标：字段、别名、用途与结构版本可导入核对，旧实例仍可解释。
• 合同依据：结构种子。
• 非测试旧文件承接：muse/content/meta/schemas/faction.yaml。

src/muse/元数据/内置结构/power_system.yaml

• 归属与种类：S04；运行资源。
• 意图：保存 power_system 结构的可审发布输入。
• 职责：power_system 内置结构种子与用途声明。
• 边界：种子不是当前库内生效定义；不覆盖作者扩展，不用元数据改系统身份。
• 目标：字段、别名、用途与结构版本可导入核对，旧实例仍可解释。
• 合同依据：结构种子。
• 非测试旧文件承接：muse/content/meta/schemas/power_system.yaml。

src/muse/元数据/内置结构/item.yaml

• 归属与种类：S04；运行资源。
• 意图：保存 item 结构的可审发布输入。
• 职责：item 内置结构种子与用途声明。
• 边界：种子不是当前库内生效定义；不覆盖作者扩展，不用元数据改系统身份。
• 目标：字段、别名、用途与结构版本可导入核对，旧实例仍可解释。
• 合同依据：结构种子。
• 非测试旧文件承接：muse/content/meta/schemas/item.yaml。

src/muse/元数据/内置结构/event.yaml

• 归属与种类：S04；运行资源。
• 意图：保存 event 结构的可审发布输入。
• 职责：event 内置结构种子与用途声明。
• 边界：种子不是当前库内生效定义；不覆盖作者扩展，不用元数据改系统身份。
• 目标：字段、别名、用途与结构版本可导入核对，旧实例仍可解释。
• 合同依据：结构种子。
• 非测试旧文件承接：muse/content/meta/schemas/event.yaml。

src/muse/元数据/内置结构/character.yaml

• 归属与种类：S04；运行资源。
• 意图：保存 character 结构的可审发布输入。
• 职责：character 内置结构种子与用途声明。
• 边界：种子不是当前库内生效定义；不覆盖作者扩展，不用元数据改系统身份。
• 目标：字段、别名、用途与结构版本可导入核对，旧实例仍可解释。
• 合同依据：结构种子。
• 非测试旧文件承接：muse/content/meta/schemas/character.yaml。

src/muse/元数据/内置结构/character_relation.yaml

• 归属与种类：S04；运行资源。
• 意图：保存 character_relation 结构的可审发布输入。
• 职责：character_relation 内置结构种子与用途声明。
• 边界：种子不是当前库内生效定义；不覆盖作者扩展，不用元数据改系统身份。
• 目标：字段、别名、用途与结构版本可导入核对，旧实例仍可解释。
• 合同依据：结构种子。
• 非测试旧文件承接：muse/content/meta/schemas/character_relation.yaml。

src/muse/元数据/内置结构/style.yaml

• 归属与种类：S04；运行资源。
• 意图：保存 style 结构的可审发布输入。
• 职责：style 内置结构种子与用途声明。
• 边界：种子不是当前库内生效定义；不覆盖作者扩展，不用元数据改系统身份。
• 目标：字段、别名、用途与结构版本可导入核对，旧实例仍可解释。
• 合同依据：结构种子。
• 非测试旧文件承接：muse/content/meta/schemas/style.yaml。

src/muse/元数据/内置结构/pacing.yaml

• 归属与种类：S04；运行资源。
• 意图：保存 pacing 结构的可审发布输入。
• 职责：pacing 内置结构种子与用途声明。
• 边界：种子不是当前库内生效定义；不覆盖作者扩展，不用元数据改系统身份。
• 目标：字段、别名、用途与结构版本可导入核对，旧实例仍可解释。
• 合同依据：结构种子。
• 非测试旧文件承接：muse/content/meta/schemas/pacing.yaml。

src/muse/元数据/内置结构/craft.yaml

• 归属与种类：S04；运行资源。
• 意图：保存 craft 结构的可审发布输入。
• 职责：craft 内置结构种子与用途声明。
• 边界：种子不是当前库内生效定义；不覆盖作者扩展，不用元数据改系统身份。
• 目标：字段、别名、用途与结构版本可导入核对，旧实例仍可解释。
• 合同依据：结构种子。
• 非测试旧文件承接：muse/content/meta/schemas/craft.yaml。

src/muse/元数据/内置结构/combat.yaml

• 归属与种类：S04；运行资源。
• 意图：保存 combat 结构的可审发布输入。
• 职责：combat 内置结构种子与用途声明。
• 边界：种子不是当前库内生效定义；不覆盖作者扩展，不用元数据改系统身份。
• 目标：字段、别名、用途与结构版本可导入核对，旧实例仍可解释。
• 合同依据：结构种子。
• 非测试旧文件承接：muse/content/meta/schemas/combat.yaml。

src/muse/元数据/内置结构/emotion.yaml

• 归属与种类：S04；运行资源。
• 意图：保存 emotion 结构的可审发布输入。
• 职责：emotion 内置结构种子与用途声明。
• 边界：种子不是当前库内生效定义；不覆盖作者扩展，不用元数据改系统身份。
• 目标：字段、别名、用途与结构版本可导入核对，旧实例仍可解释。
• 合同依据：结构种子。
• 非测试旧文件承接：muse/content/meta/schemas/emotion.yaml。

src/muse/元数据/内置结构/scene_pattern.yaml

• 归属与种类：S04；运行资源。
• 意图：保存 scene_pattern 结构的可审发布输入。
• 职责：scene_pattern 内置结构种子与用途声明。
• 边界：种子不是当前库内生效定义；不覆盖作者扩展，不用元数据改系统身份。
• 目标：字段、别名、用途与结构版本可导入核对，旧实例仍可解释。
• 合同依据：结构种子。
• 非测试旧文件承接：muse/content/meta/schemas/scene_pattern.yaml。

src/muse/元数据/内置结构/trope.yaml

• 归属与种类：S04；运行资源。
• 意图：保存 trope 结构的可审发布输入。
• 职责：trope 内置结构种子与用途声明。
• 边界：种子不是当前库内生效定义；不覆盖作者扩展，不用元数据改系统身份。
• 目标：字段、别名、用途与结构版本可导入核对，旧实例仍可解释。
• 合同依据：结构种子。
• 非测试旧文件承接：muse/content/meta/schemas/trope.yaml。

src/muse/元数据/内置结构/reference_work.yaml

• 归属与种类：S04；运行资源。
• 意图：保存 reference_work 结构的可审发布输入。
• 职责：reference_work 内置结构种子与用途声明。
• 边界：种子不是当前库内生效定义；不覆盖作者扩展，不用元数据改系统身份。
• 目标：字段、别名、用途与结构版本可导入核对，旧实例仍可解释。
• 合同依据：结构种子。
• 非测试旧文件承接：muse/content/meta/schemas/reference_work.yaml。

src/muse/元数据/内置结构/generation_context.yaml

• 归属与种类：S04；运行资源。
• 意图：保存 generation_context 结构的可审发布输入。
• 职责：generation_context 内置结构种子与用途声明。
• 边界：种子不是当前库内生效定义；不覆盖作者扩展，不用元数据改系统身份。
• 目标：字段、别名、用途与结构版本可导入核对，旧实例仍可解释。
• 合同依据：结构种子。
• 非测试旧文件承接：muse/content/meta/schemas/generation_context.yaml。

src/muse/元数据/内置结构/fine_outline.yaml

• 归属与种类：S04；运行资源。
• 意图：保存 fine_outline 结构的可审发布输入。
• 职责：fine_outline 内置结构种子与用途声明。
• 边界：种子不是当前库内生效定义；不覆盖作者扩展，不用元数据改系统身份。
• 目标：字段、别名、用途与结构版本可导入核对，旧实例仍可解释。
• 合同依据：结构种子。
• 非测试旧文件承接：muse/content/meta/schemas/fine_outline.yaml。

src/muse/元数据/内置结构/公共字段.yaml

• 归属与种类：S04；运行资源。
• 意图：保存 公共字段 结构的可审发布输入。
• 职责：共享内容属性及受保护骨架的元描述。
• 边界：种子不是当前库内生效定义；不覆盖作者扩展，不用元数据改系统身份。
• 目标：字段、别名、用途与结构版本可导入核对，旧实例仍可解释。
• 合同依据：结构种子。

src/muse/元数据/__init__.py

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