chenxin/hunjing
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
rewrite/1.0
hunjing/docs/architecture/system-architecture.md
T

10 KiB
Raw Permalink Blame History

魂镜系统总架构

状态：重写目标态（rewrite/1.0 基线） 上位约束：产品宪章、全产品主 PRD、根目录 AGENTS.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 为单一事实源。

2. 服务拓扑

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. 交互总链路

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: 透传流 + 响应裁剪

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

4. 灵台内部分层

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
  • 领域层按六域建模，拥有业务规则与状态；运行时详细设计见灵台运行时，数据模型见数据模型。
  • 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 与桌面壳。
  • 部署档位改变基础设施规模，不改变各服务逻辑职责或禁域；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 需要
Reference in new issue View Git Blame Copy Permalink