# 魂镜数据模型

> 状态：重写目标态（rewrite/1.0 基线）
> 职责：定义六域核心数据模型、关系与不变量的落库方式。枚举取值、ID 前缀、事件名以[契约词典](../contracts/contract-glossary.md)为单一事实源，本文不复制取值列表。
> 存储分档：本地开发 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. 镜生域

```mermaid
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. 镜树域

```mermaid
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. 记忆域（息壤）

```mermaid
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. 缘契域

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

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

## 5. 三界域

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

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

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

```mermaid
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 等）在[神识网关](shenshi-gateway.md)定义，不与灵台共库共表。

## 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。