hunjing/docs/architecture/data-model.md

魂镜数据模型

状态：重写目标态（rewrite/1.0 基线） 职责：定义六域核心数据模型、关系与不变量的落库方式。枚举取值、ID 前缀、事件名以契约词典为单一事实源，本文不复制取值列表。 存储分档：本地开发 SQLite（向量能力降级为关键词检索），标准档 PostgreSQL + pgvector；向量索引可重建，不是权威事实源。

0. 通用约定

• 主键：带业务前缀的 ULID（见契约词典 §3 ID 前缀表）。
• JSON 列以 _json 结尾，API/DTO 层去掉后缀（契约词典 §4）。
• 时间戳一律 UTC 存储，展示层本地化。
• 不可变表（append-only）：run_events、audit_events、factual_records、canonizations、identity_record_versions、covenant_events。禁止 UPDATE/DELETE，修正走新版本或正影。
• 状态变更与关键事件经同一事务或 Outbox 一致提交。

1. 镜生域

erDiagram
    users ||--o{ embryo_drafts : "创建/领养/导入"
    embryo_drafts ||--o| characters : "启镜签发"
    users ||--|| custodianships : "执镜"
    characters ||--|| custodianships : "被执镜"
    characters ||--o| runtime_seats : "唯一命台"
    characters ||--o{ identity_records : "魂籍"
    identity_records ||--o{ identity_record_versions : "版本"
    characters ||--o{ form_anchors : "真形锚点"
    characters ||--o{ forms : "主仪/化仪"
    characters ||--o{ voice_profiles : "声音"

表	要点
characters	正式人物（仅启镜后）。status、来源、道体（identity_baseline_json，最小锚点+禁域，不可被运行时覆盖）、死亡与冷静期字段。灵胚不是人物，不入本表
embryo_drafts	灵胚草稿：预备身份、来源（原创/领养/导入/随缘）、照心试演记录、启镜前确认清单。放弃灵胚=删除草稿
custodianships	执镜关系（治理关系，1.0 一对一）。与缘契（covenants）严格分离
runtime_seats	命台：UNIQUE(character_id)，租约持有者、租约到期、epoch（迁移/交接递增）。同一人物同一时刻最多一行有效租约
identity_records + identity_record_versions	魂籍：可验证、版本化的身份与状态包。版本含签名摘要；导出物含身份/数据/运行状态三段分离声明
form_anchors / forms / voice_profiles	形仪：真形锚点（稳定辨识特征、许可、禁忌、可变范围）；主仪/化仪（生成内容先为 candidate，用户定相才转正）；声音来源与克隆授权字段

死亡流程：characters.status 迁移 + 确认记录（confirmations）+ 冷静期撤销窗；默认死亡后转只读档案，数据清除是独立操作。

2. 镜树域

erDiagram
    characters ||--o{ mirror_trees : "主题镜树"
    mirror_trees ||--o{ tree_nodes : "节点"
    tree_nodes ||--o{ tree_nodes : "parent_node_id"
    tree_nodes ||--o{ citations : "引文锚"
    mirror_trees ||--o{ canonizations : "归真记录"
    canonizations ||--o{ memories : "归真触发候选"
    mirror_trees ||--o{ tree_transplants : "移栽谱系"

表	要点
mirror_trees	主题、当前界域默认值、工作入口 working_entry_node_id（"采用"的落点，可反复改变）、归档状态、移栽来源引用
tree_nodes	统一节点表：node_type（问节/候答/续思）、parent_node_id（问节的父是候答，候答的父是问节）、status（芽体/残答/已固化）、内容版本（编辑已发送内容=新建分叉节点，原文保留）、界域、生成元数据（模型、trace）、supersedes_node_id（正影后继链）
citations	引文锚：目标类型（文本区间/图片区域/PDF 页区/附件/音视频时间段）+ 原文快照 + 来源标识与版本；来源正影时旧锚不静默替换，只提示后继
canonizations	归真记录（不可变）：scope（真界/境界/幻境）、world_id（境界归真时必填）、路径端点与长度、快照摘要、确认者与时间。归真主脉=同作用域内 canonization 的路径并集
tree_transplants	移栽谱系：新树保留原树/原节点/来源版本引用；树间只引用不合流

落库不变量：

1. 候答重生成=插入新 tree_nodes 行，永不 UPDATE 旧行（应用层禁止 + 测试强制）；
2. 后代节点 parent_node_id 绑定用户实际采用的候答（采用变更后新问节挂新入口）；
3. working_entry_node_id 变更不触碰 canonizations（采用与归真解耦）；
4. canonizations 不可变，正影=新版本节点 + 新 canonization 记录，旧记录保留。

3. 记忆域（息壤）

erDiagram
    canonizations ||--o{ memories : "归真触发候选"
    memories ||--o{ memories : "prev_version_id 正影链"
    memories ||--o{ memory_triggers : "触发条件"
    memories ||--o{ memory_embeddings : "向量"
    characters ||--o{ memories : "人物私有"
    canonizations ||--o{ factual_records : "实录"

表	要点
memories	统一记忆表：tier（微痕/明忆/重忆）、type（含心痕 relationship_view，主观非事实）、status（候选/待确认/生效/被取代/删除墓碑）、source（用户明说/人物推断）、source_refs_json（指向节点/事件，可解释性与撤销的依据）、敏感等级、优先级、置信度、活力值（衰减 2^(−Δdays/半衰期)，命中强化）、界域（境界记忆不进真界上下文）、有效期（微痕）
memory_triggers	触发条件：关键词（微痕/世谱共用激活管线）与 disclosure（"当提到 X 时"，单一触发）
memory_embeddings	pgvector 向量列 + 来源类型；标准档启用，开发档降级
factual_records	实录（不可变，append-only）：发生了什么 + 证据引用（节点/引文锚/工具观察）。与心痕（memories 内 relationship_view）严格分离

落库不变量：

1. 只有 canonizations（或用户手动入忆，带类型标注）能产生长期记忆候选——微痕不自动升级；
2. 重忆候选 status=pending 直到用户确认；deny 两次自动退出检索；
3. 正影=新行 prev_version_id 指旧行，旧行 status=superseded 停止普通召回，内容不改写；
4. 删除=墓碑行（不承载原文）+ 主存储/向量索引/上下文/主动对话同步停用。

4. 缘契域

erDiagram
    characters ||--o{ covenants : "缘契"
    users ||--o{ covenants : "互动者"
    covenants ||--o{ covenant_events : "提议/问心/铭契/撤回"

表	要点
covenants	当前生效版本：多维关系维度（dimensions_json，不以单一好感度表达）、边界、成人内容授契（按会话临时开启）、版本号
covenant_events	不可变历史：提议、问心（人物自陈候选）、铭契确认、撤回与边界变更。即时停止与撤回立即生效并留痕

5. 三界域

表	要点
persistent_worlds	境界：世界背景、规则、实体索引、正史版本
world_entities / world_relations	河图世界认知：实体与关系（图查询走 PG 递归 CTE；Neo4j/NebulaGraph 只在规模需要时作为投影库引入，不是事实源）
lorebooks / lorebook_entries	世谱（ST 世界信息兼容）：关键词/次级键/常驻/位置/深度/顺序/概率/时序效果/递归与预算参数；导入导出兼容 ST 格式

界域本身是 tree_nodes.realm + canonizations.scope 字段，不建独立表；入境/出境是事件与节点属性。境界正史=该 world 下 canonizations 集合；幻境试演=scope=simulation 的 canonization 记录。

6. 灵台域（运行、能力与安全）

erDiagram
    characters ||--o{ runs : "运行"
    runs ||--o{ run_events : "一炁事件"
    characters ||--o{ mandates : "授契/行契"
    mandates }o--|| tools : "能力"
    runs ||--o{ confirmations : "请命确认"
    tools ||--o{ tool_calls : "调用记录"
    tool_calls ||--o{ evidence : "证据"

表	要点
runs	运行：种类（前台/后台受托）、状态、命台 epoch、Profile 快照引用
run_events	一炁事件流（现有 event_store 改造）：单调序号、类型、可见性、载荷；SSE 与回放的数据源
capabilities	百工能力注册表（M5 落地单表统一契约）：稳定标识、参数 Schema、执行类型（builtin/qiankun/mcp/http）、四维风险标注、来源与版本
mandates	授契（单次范围）与行契（重复执行：能力/参数/数据/目标/预算/时间窗）；可撤销，撤销立即生效
confirmations（pending_confirmations）	请命：六要素说明（brief_json）、超时策略（超时=拒绝执行 HJ-1302）；含死亡、重忆、铸魂等高影响确认
tool_calls	调用记录与证据链（evidence_json 内嵌）：净化后输入输出摘要、观察标证、裁决与授契关联、trace 关联
audit_events / 行动账	现有审计表改造：所有工具调用（用户+时间+工具+参数+结果）与外部行动
mcp_servers	MCP 服务登记（博闻等）；玄关退役后由百工持有
ST 兼容层	user_personas（本相）、generation_presets（火候）、instruct_templates（科仪）、quick_replies（锦囊）、author_notes（眉批）、macros（符文引擎，无独立表，组装期展开）

7. 天宰域

表	要点
users / credentials	账户与多凭证（邮箱/Passkey/受信第三方）；年龄分层核验骨架字段
domains	镜域：数据与治理边界，区域驻留字段
RBAC 相关	现有 rbac 表保留改造；管理员默认不可见私密原文
preferences	用户偏好（含神识路由偏好，联动神识 BYOK）

神识侧数据模型（providers/endpoints/byok_keys/usage_logs 等）在神识网关定义，不与灵台共库共表。

8. 导入域

表	要点
import_jobs / import_items	现有导入表改造：角色卡（ST V2/V3：PNG tEXt ccv3/chara 双块、JSON/CharX）、世谱、聊天记录；静态隔离解析，任何能力逐项授契
对接	导入产物默认生成 embryo_drafts + 待审 lorebook_entries；外部聊天仅作外部前史，不产生真界实录

9. 表处置清单

保留改造（现有基础设施）：users/credentials/rbac、audit_events、event_store（→run_events）、idempotency、mcp_servers、import_jobs/import_items、lorebooks/lorebook_entries、settings/preferences 类。

新建：characters（重建）、embryo_drafts、custodianships、runtime_seats、identity_records(+versions)、mirror_trees、tree_nodes、citations、canonizations、tree_transplants、memories（重建）、memory_triggers、memory_embeddings、factual_records、covenants(+events)、persistent_worlds、world_entities/relations、form_anchors/forms/voice_profiles、devices/device_grants、tools/skills（重建）、mandates、confirmations（改造）、runs（重建）。

退役删除（旧模型，开发数据随 db 丢弃）：personality、personality_emotion、personality_versions/proposals、mood_events、character_emotion_states、drive、evolution、wuxing 相关、big_cycle、goals、plans、time_anniversaries、idle_window、suspension、uncertainty_states、curiosity_questions、exploratory_subgoals、chat_sessions/chat_messages（被镜树取代）、memory_timelines/timeline_events、knowledge_documents/memory_chunks/embedding_refs（并入记忆域新表）、candidates（并入灵胚审核）、character_situational_entries、avatar 旧表（并入形仪）。

Alembic 基线重建：丢弃现有 4 个迁移，以本模型为新基线 000；迁移编号使用三位顺序号（000、001、002…），生成统一经根目录 make db-revision m="说明"（自动编号，不手写哈希 id）；迁移与退役的执行顺序见重写执行计划。

10. 隐私与删除的落库规则

• 敏感字段（重忆内容、克隆授权、私箧类）列级标注敏感等级；默认查询路径不得返回高敏原文（摘要或脱敏）。
• 删除传播：人物死亡≠数据删除；数据删除按"权威存储→向量索引→缓存→派生视图→主动对话候选"顺序停用，墓碑只留行为证据。
• 跨人物共享（本相授权）以授权记录为查询前提，缘识与心痕默认人物私有，不做任何跨人物隐式 JOIN。