# 灵台插件化运行时

> 状态：重写目标态（rewrite/1.0 基线）
> 职责：定义灵台认知运行时的结构——极小硬核 Kernel、插件体系、事件溯源会话、上下文投影、提示词与记忆注入管线、压缩、并发与命台控制。
> 设计理念参考 deepseek-harness 的"一切皆插件"与 pi 的会话/压缩模型，均只借设计不引依赖。

## 1. 设计理念与硬核例外

运行时遵循三条理念：

1. **一切皆插件**：模型适配、工具、记忆、人格调节、压缩、世界认知……全部以插件装配，无特权核心，可从配置替换。
2. **事件溯源**：Run 的一切输入输出进入 append-only 事件日志（一炁），模型可见上下文从事件日志投影派生；铁律 **"模型可见即可重建"**——到达模型的任何输入必须能从日志重建，运行时以断言强制。
3. **监听器可否决**：关键节点（请求前、工具执行前、结果接纳前）是瀑布事件，插件监听器可改写或否决；注入、审计、安全都在事件层做，不改循环骨架。

**硬核例外（不可插拔）**：Kernel 固化以下内容，任何插件不可卸载、降权或绕过——

- 镜树不变量：重新生成不覆盖旧候答、未归真旁枝不自动入忆、归真不因切换候答回滚、编辑已发送内容必分叉；
- 命台不变量：同一人物同一时刻只有一条前台意识流，多分支前台请求排队；
- 司命禁域裁决点：高风险能力、数据、后果、情境四维裁决中标记为禁域的规则在请求前强制执行；
- 事件日志写入：状态变更与事件一致提交（事务内或 Outbox）。

这套例外的依据是产品宪章"禁域不能被 Prompt、人物、模型、扩展、管理员或普通部署配置关闭"。插件体系的自由度止步于禁域。

## 2. 分层结构

```mermaid
flowchart TD
    subgraph Kernel[极小硬核 Kernel · 不可插拔]
        INV[不变量裁决器]
        SEAT[命台并发控制]
        LOG[事件日志读写]
        LOOP[Run 循环骨架]
    end
    subgraph Bus[事件总线 · 瀑布节点]
        N1[run.requested]
        N2[turn.started]
        N3[llm.pre_request]
        N4[tool.pre_execute]
        N5[result.pre_accept]
        N6[turn.finished]
    end
    subgraph Plugins[插件层 · Profile 装配]
        P1[灵核 · 人格调节]
        P2[太一 · 目标]
        P3[司命 · 常驻裁决]
        P4[烛照 · 观察反思]
        P5[河图 · 世界认知]
        P6[洛书 · 计划]
        P7[息壤 · 记忆]
        P8[百工 · 能力注册]
        P9[天工阁 · 功能 Agent]
    end
    LOOP --> Bus
    Plugins --> Bus
    Kernel --> Plugins
```

## 3. 事件溯源会话

### 3.1 事件模型

Run 是一次人物认知运行（一次前台回答、一次后台受托任务、一次应感）。Run 事件序列是一炁事件流的一个分区：

```mermaid
flowchart LR
    E1[run.started] --> E2[turn.started]
    E2 --> E3[context.projected<br/>投影快照引用]
    E3 --> E4[llm.requested]
    E4 --> E5[llm.delta ...]
    E5 --> E6[llm.completed]
    E6 --> E7{工具调用?}
    E7 -- 是 --> E8[tool.pre_execute]
    E8 --> E9[tool.executed]
    E9 --> E4
    E7 -- 否 --> E10[turn.finished]
    E10 --> E11[result.pre_accept]
    E11 --> E12[run.finished]
```

- 事件带单调序号、`run_id`、`character_id`、`trace_id` 与时间戳；事件类型与取值以[契约词典](../contracts/contract-glossary.md)为单一事实源。
- SSE 输出是事件流的可发布投影：`visibility=public` 的事件可推送前端，`internal`/`audit` 不出灵台。
- 中断（取消、网络失败、超时）写入 `run.interrupted`，芽体封存为残答，不伪装完成。

### 3.2 上下文投影

`derive_context()` 从事件日志 + 镜树状态 + 记忆状态投影出本次模型可见上下文，来源只有三类（镜树 PRD 不变量 6）：

1. **祖先路径**：当前工作入口的问节-候答祖先链；
2. **获准长期记忆**：经息壤检索且通过敏感与权限过滤的明忆/重忆；
3. **显式引文**：用户建立的引文锚及其快照。

未采用旁枝默认不进入投影。投影结果写入 `context.projected` 事件（引用而非全文，可从日志重建），这是"模型可见即可重建"的落点。

## 4. 插件体系

### 4.1 插件契约

```python
class Plugin(Protocol):
    name: str                      # 稳定标识，登记于契约词典 pivot 枚举
    version: str

    def register(self, bus: EventBus, profile: Profile) -> None: ...
```

- 插件通过订阅瀑布节点与提供能力（工具、检索器、调节器、压缩器）参与运行。
- 插件之间不直接调用，只经事件总线与能力注册表交互。
- 插件加载顺序由 Profile 决定；同节点多个监听器按注册序执行，任一否决即中断并记录。

### 4.2 Profile（运行档案）

Profile 是一次 Run 的插件装配清单与参数包，来源于配置层叠：

```mermaid
flowchart LR
    A[平台硬边界<br/>禁域与全局上限] --> E[最终 Profile]
    B[平台目录<br/>默认插件与参数] --> E
    C[用户偏好 / BYOK] --> E
    D[人物覆写<br/>道体·人格·能力授契] --> E
    F[镜树临时选择<br/>模型·火候·指引] --> E
```

层叠顺序与产品 PRD"神识配置继承"一致；镜树临时选择只作用于该节点及用户明确继承的后继。Profile 本身写入事件日志，保证可审计、可回放。

### 4.3 九枢落位

| 枢 | 插件职责 | 关键机制 |
| --- | --- | --- |
| 灵核 | 人格调节：道体锚点 + 调节层参数注入 | 道体不可运行时覆盖；调节层按证据渐进演进，重大变化走铸魂流程 |
| 太一 | 目标：人物长期目标的维护与冲突检测 | 目标层级与状态见契约词典 |
| 司命 | 安全裁决：能力/数据/后果/情境四维 | 自省/循律/请命/禁域四级自主性；禁域挂载点在 Kernel |
| 烛照 | 观察与反思：对工具观察、用户反馈做理解候选 | 产出心痕候选与正影建议，不直接写状态 |
| 河图 | 世界认知：世界实体、世谱（Lorebook）激活 | 世谱激活管线见 §6.1 |
| 洛书 | 计划：多步任务的计划生成与跟踪 | 计划状态机见契约词典 |
| 息壤 | 记忆：三级记忆的写入候选、检索、注入 | 管线见 §6.2 |
| 百工 | 能力注册：工具/MCP/Skill/感官的唯一目录 | 每个 Run 只暴露最小获准 Schema |
| 天工阁 | 功能 Agent 编排：受托任务分解与并行 | 功能 Agent 无魂籍与身份；不构成第二意识 |

## 5. 提示词组装管线

采纳 SillyTavern PromptManager 的"实体化提示词 + 审计覆盖"模式：

- 每个注入片段是实体：`identifier / role / source / position / depth / order / forbid_override`；
- `source` 区分：系统契约、道体、人格调节、世界认知（河图）、记忆（息壤）、引文、用户指令、镜树对话；
- `position`：相对排序或绝对深度（atDepth 注入对话流内），`depth` 从消息尾部计数；
- 组装结果与每个片段的来源一起写入 `context.projected` 事件，前端"可解释轨迹"直接读该事件；
- `forbid_override=true` 的片段（系统契约、禁域声明）不可被人物层与镜树层覆盖，只可被平台更新替换。

## 6. 记忆注入与检索

### 6.1 微痕激活（借世界信息激活管线）

微痕与会谱条目共用激活管线：

1. **时序效果**：`sticky`（激活后置顶 N 轮）、`cooldown`（冷却轮数）、`delay`（延迟轮数）；
2. **关键词扫描**：对最近 N 条消息做关键词/正则匹配（全字边界、大小写选项）；
3. **次级键逻辑**：AND ANY / NOT ALL / NOT ANY / AND ALL；
4. **递归扫描**：已激活条目内容回流再扫描，限最大步数；
5. **预算控制**：激活条目按 `order` 排序，超出 token 预算（上下文的百分比上限）从尾部淘汰；
6. **向量补充**：预算内对未命中关键词的微痕做相似度召回。

激活结果作为 `source=trace` 的提示词实体进入组装管线。

### 6.2 长期记忆检索（明忆/重忆）

1. 双路召回：pgvector 向量 + PG 全文检索，RRF 融合；
2. 过滤：敏感等级、界域（境界记忆不进真界上下文）、撤回与删除状态、授权范围；
3. 时间衰减与优先级加权：活力值 `2^(−Δdays/半衰期)`，命中强化，重忆优先展示来源与版本；
4. 召回预算：条数与字符上限；
5. 每次召回写入轻量审计（召回了什么、用于哪个 Run），支撑"召回透明"。

### 6.3 写入管线（归真后提取）

只有带 `canonical_scope` 的归真结果触发长期记忆提取（异步任务）：

1. **提取**：单次 LLM 调用完成情境切分 + 记忆候选抽取；三原则：宁缺毋滥（滤闲聊与一次性指令）、独立完整（脱离对话仍成立）、归纳合并；输出 `{content, type, priority, confidence, sensitive, source_message_ids}`；
2. **双源标记**：`user_explicit`（用户明说）与 `self_inferred`（人物推断）；
3. **分级落位**：白名单内低敏 → 明忆候选（自动生效 + 撤销窗）；敏感或高影响 → 重忆候选（必须用户确认）；类型含心痕（`relationship_view`，主观非事实）；
4. **去重合并**：向量召回统一候选池 → 批量判定 store/skip/update/merge（跨类型合并、时间戳并集）；
5. **版本链**：更新产生新版本指向旧版本，旧版停止普通召回（正影语义）；
6. **删除**：墓碑只证明删除行为发生，不承载原文；主存储、索引、上下文、主动对话同步停止使用。

## 7. 压缩管线

长对话压缩是可插拔能力（息壤插件的子模块），非循环骨架：

- **触发**：投影 token 超过窗口减预留阈值；
- **切点规则**（pi 模型）：从尾部保留近段消息累计到保留额度，向前寻找合法切点；**工具结果永不作切点**，工具调用与结果必须配对保留或一同进入压缩区；
- **分区摘要**：旧摘要 + 新消息增量续写，分区为背景/事实/关系/未决事项/关键决定；
- **内容路由**（headroom 思想）：工具结果按内容类型分治——JSON/结构化裁剪、代码保关键段、纯文本摘要；对话历史走摘要压缩；
- **缓存友好**：注入片段位置固定（固定 depth 注入点），前缀字节稳定，避免打爆 Provider KV 缓存；
- **可逆引用**：被压缩掉的原文保留在事件日志，人物可经"回溯"能力按引用取回；
- 压缩边界事件（start/end）入日志，崩溃可检测（孤儿压缩标记）。

## 8. 并发与命台控制

```mermaid
sequenceDiagram
    participant U1 as 设备 A
    participant U2 as 设备 B
    participant K as Kernel 命台控制
    participant R as Run

    U1->>K: 前台生成请求（树 1）
    K->>R: 获得前台槽位，Run 启动
    U2->>K: 前台生成请求（树 2）
    K-->>U2: 排队（返回队列位置）
    U1->>K: steer（运行中插话）
    K->>R: 注入 steering 消息队列（下一 turn 生效）
    U1->>K: 取消
    K->>R: 取消 → 芽体封存残答 → run.interrupted
    K->>R: 出队树 2 请求
```

- 前台槽位以人物为粒度，Redis 持锁（轻量档进程内锁），带租约与心跳；崩溃后租约到期自动释放，进行中的芽体标记中断。
- 后台受托 Run（天工阁）可并发，标记为功能任务，不进入前台槽位。
- steering 消息进入队列并在事件日志留痕，插话不静默（下一 turn 前端可见"已插话"）。

## 9. 工具执行（百工 ↔ 乾坤）

1. `tool.pre_execute`：司命按四维裁决；请命级暂停等待用户确认（confirmations 表，超时即拒绝执行）；
2. 获准后由执行器分派：HTTP 工具、MCP（博闻等）、乾坤沙箱（本地/代码执行）、内置工具；
3. `tool.executed`：结果先净化（敏感词/隐私脱敏）与标证（来源、时间、许可），作为观察写入事件日志；
4. 观察被接纳（`result.pre_accept`）后才有资格形成记忆候选；任何插件不得把工具结果直接写成事实或人物答复。

## 10. 目录与代码组织

```text
backend/app/
  kernel/          # 极小硬核：不变量、命台、事件日志接口、循环骨架
  runtime/         # 事件总线、Profile、插件加载、投影、压缩调度
  pivots/          # 九枢插件实现（每枢一个包）
  domains/         # 六域领域层（镜生/缘契/三界/形仪/灵台域/天宰）
  infra/           # 复用基础设施：auth/RBAC/审计/事件存储/幂等/SSE
  shenshi_client/  # 神识客户端边界（唯一模型出口）
  api/             # v1 路由与 DTO
```

## 11. 测试策略

- **不变量测试**：Kernel 不变量逐条有失败用例（重生成覆盖、旁枝入忆、归真回滚、并行前台、禁域绕过——全部必须被拒绝并留痕）；
- **回放测试**：随机抽样历史 Run，从事件日志重放投影，与当时 `context.projected` 比对一致（"模型可见即可重建"的验证）；
- **插件契约测试**：每个插件用统一 harness 验证注册、订阅、否决语义；
- **管线性质测试**：世谱激活（时序/递归/预算）、记忆提取（三原则）、压缩（切点配对、缓存前缀稳定）各有单元与性质测试；
- 端到端：创建→首聊→分叉→归真→记忆候选→确认→召回 的完整链路走 BFF 入口验证。