- 新版设计各域 SoT 按本轮实现同步：总体架构、模块设计、接口契约、数据模型、功能规格、文件设计与决策记录。
- 接口契约生成物重新导出（openapi 与前端客户端随契约一致）。
- 实现回顾与专项检查台账保留历史结论；本轮收尾发现另见 .agents.local 下的收尾报告与审查处置。

2026-09-18 01:15:18 +08:00

4.0 KiB

Raw Blame History

S04 元数据

职责与对象

类型和结构定义、版本、扩展与投影，不拥有业务实例值。

实例归属以总体架构为准；结构、状态和公开外壳分别引用数据模型与接口契约。

公开接口

用例	输入责任	输出与后果
register_type	类型身份、粒度和已登记生命周期族	类型候选
publish_schema	字段结构及兼容检查	不可变结构版本
compose_schema	基础和作品扩展的明确版本	有效结构与哈希
validate_value	有效结构、用途和候选值	结构问题与引用校验需求
project_fields	结构、用途和受控授权摘要	允许字段与剔除原因
activate_binding	被审结构、预期绑定和影响处理	结构绑定回执

所有接口在本模块的接口.py 暴露。输入输出类型由同一公开表面导出，外部不导入私有模型或 SQL。

内部职责

文件	职责
接口.py	元数据公开用例和可导入合同
模型.py	元数据稳定对象、外壳及内部状态
存储.py	元数据所属记录的 SQL 与版本读写
类型登记.py	类型、粒度、业务归属和生命周期族
结构版本.py	不可变结构发布、启用及固定读取
扩展合成.py	基础结构和只增不改的作品扩展
字段校验.py	类型、必填、枚举、嵌套和引用结构
字段投影.py	展示、编辑、检索、导出和 AI 用途
变更影响.py	兼容分类、受影响实例及升级要求
内置导入.py	内置种子幂等登记，保护已存在绑定和扩展

完整路径及运行模板见目标文件清单。逐文件意图、边界与目标见文件合同。

实现约束

保留基础字段、开放内容字段和同生命周期新类型；系统身份与原生绑定由代码登记。
基础版本与作品扩展合成可重复，不能随 active 指针变化重新解释历史数据。
结构校验与真实引用校验分工，后者由实例所属模块执行。
内置种子是发布输入；PG 保存生效版本，启动不覆盖作者扩展。
字段消费与结构/策略变更经同一类型级事务锁排序：消费持共享咨询锁，变更持排他咨询锁并保护实际更新行。评测账号只拥有元数据读取权限，不能为消费锁授予表写权限；多个类型按统一顺序保护，锁不跨模型网络调用。

协作与失败

业务模块和 B09 消费；前端通过 owner 投影得到结构和值；结构变更使用 S01 保护。

不兼容变更返回转换要求；结构、投影和实例版本不同步时拒绝；未知处理器和越权字段拒绝。

验收行为

M01 新字段贯通。
M02 新类型贯通。
M03 扩展不能绕过保护。
M04—M08 版本、用途、迁移与并发。

验收入口和替换条件见迁移与验收；这些条目是目标行为，不是已通过测试的声明。

当前公开范围

当前接入只开放登记候选、发布结构版本、兼容检查，以及业务owner对既有绑定的读写。发布v2不会自动升级固定绑定v1的实例。已有对象在线升级、作品扩展发布及在线策略更新单独立项，本期不提供公共启用工作流；既有低层API保留内部兼容。当前projection_version和类型锁协议保持不变；未来升级需独立转换、审阅、当前绑定CAS和恢复验收。

已发布种子的字段说明也参与结构内容哈希。power_system、narrative_state v1中的历史尾注是冻结说明，不是当前开发待办；本期保留原YAML字节。说明修订须发布新结构版本，既有实例是否升级另按在线升级项目处理，不以清理注释名义重写同版本身份。

4.0 KiB Raw Blame History Unescape Escape