# 魂镜系统总架构

> 状态：重写目标态（rewrite/1.0 基线）
> 上位约束：[产品宪章](../product/constitution.md)、[全产品主 PRD](../product/master-prd.md)、根目录 `AGENTS.md` 完整技术栈
> 实现进度以[能力矩阵](../operations/capability-matrix.md)为准，本文不声明任何能力已落地。

## 1. 架构基准

魂镜产品定义（六域、镜树、三级记忆、司命禁域等）保持产品与领域文档权威不变；工程架构以根目录 `AGENTS.md` 的完整技术栈为基准，按五层组织：

| 层 | 技术 | 文化名 | 核心职责 |
| --- | --- | --- | --- |
| 前端 | Next.js 16 + React 19 + TypeScript | 琉璃镜 | 全部 Web 界面、镜树阅读与局部树图、治理与可解释呈现、Live2D 与浏览器通感 |
| BFF | Node.js 22 + Fastify + Zod | 照壁 | 鉴权透传、SSE/WebSocket 代理、响应裁剪、openapi-fetch 类型桥接 |
| 后端核心 | Python 3.12+ + FastAPI + SQLAlchemy 2.0 | 灵台 | 六域业务、插件化认知运行时（九枢）、事件溯源、司命裁决、百工注册 |
| 高并发 I/O 层 | Go 1.25+ | 神识 / 博闻 | 神识：模型网关（Provider/路由/流式/BYOK/计量）；博闻：MCP 联网搜索 |
| 桌面端 | Rust + Tauri v2 | 镜匣 | 最小桌面壳：承载琉璃镜、本地能力桥、乾坤本地执行通道 |
| 隔离执行 | Rust + axum（独立 HTTP 服务） | 乾坤 | 不可信代码隔离执行、资源上限、进程组清理、HMAC 授权 |
| 感知/本地推理辅助 | Python | 天目 / 元炁 | 天目：本地 OCR；元炁：本地 LLM / Embedding / Rerank / 多模态推理 |

文化名与工程对象的登记、新增与退役以[契约词典 §2](../contracts/contract-glossary.md) 为单一事实源。

## 2. 服务拓扑

```mermaid
flowchart LR
    subgraph Clients[客户端]
        Browser[浏览器]
        Desktop[镜匣 · Tauri 壳]
    end
    subgraph Edge[边缘层]
        Nginx[天门 · Nginx 统一入口]
        BFF[照壁 · Fastify BFF]
    end
    subgraph Core[核心层]
        LT[灵台 · Python 后端核心<br/>六域业务 + 插件化运行时]
    end
    subgraph GoIO[高并发 I/O 层]
        SS[神识 · Go 模型网关]
        BW[博闻 · Go MCP 搜索]
    end
    subgraph Aux[辅助服务]
        QK[乾坤 · Rust 沙箱]
        TM[天目 · OCR]
        YQ[元炁 · 本地推理]
    end
    subgraph Data[数据层]
        PG[(金匮 · PostgreSQL / SQLite)]
        RD[(灵泉 · Redis)]
        OS[(玉函 · MinIO / 本地对象)]
        VEC[(灵犀 · pgvector / Milvus)]
    end
    Browser --> Nginx
    Desktop --> Nginx
    Nginx --> BFF
    BFF --> LT
    LT --> SS
    SS --> Provider[模型 Provider / BYOK Endpoint]
    SS --> YQ
    LT --> BW
    LT --> QK
    LT --> TM
    LT --> PG
    LT --> RD
    LT --> OS
    LT --> VEC
    SS --> RD
```

要点：

1. 所有客户端请求经照壁进入灵台；琉璃镜与镜匣不持有平台密钥、不直连神识或乾坤。
2. 神识是唯一模型出口：灵台向神识发送版本化模型请求，神识负责协议转换、路由、流式与计量；元炁作为神识的一种本地 Endpoint 接入，不走独立通道。
3. 博闻等 MCP 服务由灵台百工注册与调用；玄关（旧 Go MCP 管理网关）退役，MCP 服务登记并入灵台百工。
4. 乾坤只执行经司命裁决且范围明确的请求；乾坤不判断风险、不拥有人物状态。

## 3. 交互总链路

```mermaid
sequenceDiagram
    participant UI as 琉璃镜/镜匣
    participant ZB as 照壁 BFF
    participant LT as 灵台
    participant SS as 神识
    participant QK as 乾坤
    participant BW as 博闻

    UI->>ZB: HTTPS + JWT Cookie + Idempotency-Key
    ZB->>LT: 鉴权透传 + 裁剪后请求
    LT->>LT: 命台排队 + 司命裁决 + 上下文投影
    alt 模型推理
        LT->>SS: 版本化模型请求 + run_id/trace_id
        SS-->>LT: 标准化流（SSE）+ 用量
    else 工具执行
        LT->>BW: 百工工具调用（如联网搜索）
        BW-->>LT: 观察结果
        LT->>QK: 已授权执行请求 + 限制 + trace
        QK-->>LT: 执行观察与审计证据
    end
    LT->>LT: 净化标证 + 状态事务 + Outbox 事件
    LT-->>ZB: SSE 事件流 / JSON
    ZB-->>UI: 透传流 + 响应裁剪
```

灵台返回的工具与模型结果先作为带来源的观察进入事件日志，不自动成为事实、人物答复或长期记忆；该铁律的运行时保障见[灵台运行时](lingtai-runtime.md)。

## 4. 灵台内部分层

```mermaid
flowchart TD
    API[API 层 · api/v1 + SSE]
    Domain[六域领域层<br/>镜生 / 缘契 / 三界 / 形仪 / 灵台域 / 天宰]
    Kernel[极小硬核 Kernel<br/>不变量裁决 + 命台并发 + 事件溯源 + 循环骨架]
    Plugins[插件层 · 九枢装配<br/>灵核 / 太一 / 司命 / 烛照 / 河图 / 洛书 / 息壤 / 百工 / 天工阁]
    Infra[基础设施复用层<br/>auth / RBAC / 审计 / 事件存储 / 幂等 / SSE 网关]
    API --> Domain
    Domain --> Kernel
    Kernel --> Plugins
    Domain --> Infra
```

- 领域层按六域建模，拥有业务规则与状态；运行时详细设计见[灵台运行时](lingtai-runtime.md)，数据模型见[数据模型](data-model.md)。
- Kernel 是不可插拔的最小核心：镜树不变量（重新生成不覆盖、未归真不入忆、归真不静默回滚）、命台唯一前台意识流、司命禁域裁决点、"模型可见即可重建"断言。
- 九枢全部以插件装配；司命插件常驻，其禁域规则挂载点不可卸载、不可降权。

## 5. 数据总架构

- 关系数据库（本地 SQLite / 生产 PostgreSQL）是当前状态唯一事实源；本地开发默认 SQLite 文件，正式环境 PostgreSQL，按需启用 Redis、Milvus、Neo4j/NebulaGraph 与对象存储。
- 关键事件、治理裁决与外部行动写入 append-only 事件日志（一炁），与状态变更经同一事务或 Outbox 一致提交。
- 向量检索：PostgreSQL + pgvector 为标准档；Milvus（灵犀）只在真实规模需要时引入；开发档可用 SQLite + 本地向量层。向量索引可重建，不是权威事实源。
- 对象存储：本地文件系统（开发）→ MinIO（自建）→ S3 兼容（云）。
- 可重建索引、缓存与派生视图在任何恢复流程中都从权威数据重建并校验。

## 6. 可靠性总架构

- 核心文字相伴官方云 1.0 目标 SLO 99.9%；权威人物数据 RPO ≤ 5 分钟、RTO ≤ 1 小时；媒体与可重建索引可采用更宽目标。
- 手段：健康检查、超时与限流、神识端点故障切换（首字超时切道）、幂等键、事务/Outbox、可验证备份与恢复演练。
- SSE 断线续传：事件带单调序号，客户端以 `Last-Event-ID` 重连，中间状态可在 Redis 缓存恢复；恢复不得违反"未完成芽体不伪装为完整候答"。
- 模型、工具与区域故障下安全降级：降级只影响能力可用性，不破坏人物连续性与已归真经历。

## 7. 部署分档

| 档位 | 目标 | 基础设施 |
| --- | --- | --- |
| 本地开发 | 单机开发测试，不可用于生产 | SQLite、本地对象、进程内协调；允许示例凭证与宿主端口 |
| 轻量单机 | 私人闭环、低运维自托管 | SQLite、本地对象，可选本地向量层与 Redis |
| 标准服务器 | 稳定多人/多人物服务 | PostgreSQL + pgvector、Redis、MinIO；按需 Milvus / Neo4j |
| 官方区域云 | 区域驻留、可运营 | 五层服务区域化部署、区域内高可用、备份与灾备体系 |

- Docker 编排位于根目录 `docker/`：`docker-compose.infra.yml`（数据库/缓存/向量/图库/对象存储）与 `docker-compose.app.yml`（照壁、灵台、神识、琉璃镜、乾坤、天目、元炁、博闻、天门 Nginx），容器名以 `hunjing-` 开头，共享网络 `hunjing-net`。
- 镜匣（Tauri 壳）为桌面构建产物，不进 Compose；其本地能力桥与乾坤的对接见[BFF 与桌面壳](bff-and-desktop.md)。
- 部署档位改变基础设施规模，不改变各服务逻辑职责或禁域；`change-me` 凭证、无认证管理端口与 `STORAGE_PROVIDER=local` 只允许本地开发档。

## 8. 阶段启用矩阵

| 服务 | P0 | P1 | P2 |
| --- | --- | --- | --- |
| 琉璃镜 | 镜树核心界面、人物、记忆治理、设置 | 形仪工坊、Live2D、语音、通感 | 天工阁、叩心、神识阁完整治理 |
| 照壁 | 鉴权透传 + SSE 代理 + 类型桥接 | 媒体裁剪与聚合 | 多区域入口 |
| 灵台 | 六域核心 + 插件运行时 + 司命 + 百工基础 | 形仪/语音/通感域扩展 | 天工阁、叩心、区域与计费 |
| 神识 | chat 槽位、平台目录、BYOK、计量 | vision/ASR/TTS/image/embedding/rerank 槽位 | 配额与成本治理 |
| 博闻 | 百工注册的联网搜索 | — | 搜索配额 |
| 乾坤 | 基础隔离执行 | 设备安全扩展 | 双裁决与硬急停 |
| 天目/元炁 | 元炁作为本地 Endpoint 可选 | 天目 OCR 接入通感 | — |
| 镜匣 | — | 设计预留 | 最小桌面壳交付 |

## 9. 架构决策记录

| 决策 | 结论 | 备选与后果 |
| --- | --- | --- |
| 架构基准 | 以 AGENTS.md 完整技术栈为准，docs/architecture 按其重写 | 备选为四服务目标态文档；后果是 BFF/桌面端进入范围，旧"灵台承载 ai_provider"过渡态终止 |
| BFF 选型 | Fastify | NestJS 结构更强但体量重；SSE 代理场景 Fastify 负担最小 |
| 神识时序 | 重写期间新建 Go 神识，一次性替换 Python `ai_provider` | 先契约后迁移可降低风险，但会保留两套模型出口；已选择避免二次迁移 |
| 运行时理念 | 采纳"一切皆插件"（deepseek-harness），司命禁域与身份不变量为不可插拔硬核 | 纯插件化会使禁域可被卸载，违反宪章；硬核例外是宪章级约束 |
| 玄关处置 | 退役，MCP 服务登记并入灵台百工 | 保留独立 MCP 网关会多一个服务与鉴权面；百工本就是唯一能力注册中心 |
| 桌面端 | 实现最小镜匣壳（Tauri），加载琉璃镜 + 本地能力桥 | 仅设计预留会推迟桌面验证；完全桌面化超出 1.0 需要 |