diff --git a/docs/architecture/bff-and-desktop.md b/docs/architecture/bff-and-desktop.md new file mode 100644 index 0000000..7334400 --- /dev/null +++ b/docs/architecture/bff-and-desktop.md @@ -0,0 +1,85 @@ +# 照壁 BFF 与镜匣桌面壳 + +> 状态：重写目标态（rewrite/1.0 基线） +> 两项均为新增工程：照壁（Fastify BFF）进入 Compose 应用层；镜匣（Tauri 最小桌面壳）为桌面构建产物。 + +## 一、照壁（BFF，Node.js 22 + Fastify） + +### 1. 定位 + +照壁是琉璃镜/镜匣与灵台之间的唯一通道：鉴权透传、SSE/WebSocket 代理、响应裁剪、类型桥接。**无状态、无业务规则、无权威数据**——"能否看到"的语义一律来自灵台，照壁只做传输与形状处理。 + +### 2. 职责清单 + +| 职责 | 说明 | +| --- | --- | +| 鉴权透传 | JWT Cookie（httpOnly）原样转发灵台；刷新流程代理；不做本地权限判断 | +| SSE 代理 | 透传灵台 SSE：禁缓冲（`X-Accel-Buffering: no`）、透传 `Last-Event-ID` 断线续传、心跳保活、客户端断开即向上游取消 | +| WebSocket 代理 | 双向协同场景（预留，P0 不启用） | +| 响应裁剪 | 按端点白名单裁剪字段（移动端轻量视图）；不裁剪治理与审计字段 | +| 轻量聚合 | 跨灵台端点的合并请求（如镜树页一次取树+入口+待确认）；只合并不改写语义 | +| 类型桥接 | 灵台 OpenAPI 3.1 生成 TypeScript 类型，openapi-fetch 类型安全调用；BFF 自身入参用 Zod 校验 | +| 日志 | pino 结构化日志：request_id、用户 ID、耗时、上游状态；不含请求体敏感原文 | + +### 3. 请求链路 + +```mermaid +flowchart LR + A[琉璃镜 / 镜匣] -->|HTTPS + JWT Cookie| B[天门 Nginx] + B --> C[照壁 Fastify] + C -->|鉴权透传 + Idempotency-Key| D[灵台] + D -->|SSE / JSON| C + C -->|裁剪 + 保活| A +``` + +### 4. 工程约定 + +- 目录 `bff/`（Node 22 LTS、TypeScript、Fastify、Zod、openapi-fetch、pino）； +- 测试：Vitest + supertest（代理行为、断线续传、裁剪白名单）； +- 部署：`docker/bff/Dockerfile`，容器 `hunjing-bff`，挂 `hunjing-net`；天门将 `/api/*` 指向照壁； +- 性能红线：SSE 代理链路不引入整帧缓冲；代理自身超时大于灵台同类超时，避免 BFF 先于后端掐断流。 + +## 二、镜匣（桌面壳，Rust + Tauri v2） + +### 1. 定位与范围（最小壳） + +镜匣在 1.0 只交付最小桌面壳： + +1. **WebView 承载琉璃镜**：加载本地打包的前端或指向自托管部署地址；登录与全部功能即 Web 功能； +2. **本地能力桥**：文件对话框、系统通知、托盘常驻、开机自启（可选）； +3. **乾坤本地执行通道**：桌面端可连接本地/局域乾坤沙箱，作为该镜域器谱中的一台设备（须在器谱登记并经人物授契后才可用）； +4. **tantivy 本地检索（预留）**：为本地文件索引预留接口与能力声明，1.0 不实现索引构建； +5. **自动更新**：tauri-plugin-updater；本地配置 tauri-plugin-store。 + +**不做**：本地人物副本、离线人格运行、绕过照壁直连灵台、本地保存平台密钥。设备失联只做安全自治与输入暂存。 + +### 2. 能力与授权映射 + +```mermaid +flowchart TD + T[Tauri capabilities
壳内声明] --> M[器谱登记
镜域设备] + M --> G[人物授契
逐项授权] + G --> S[司命裁决
云端] + S --> Q[乾坤本地执行
双裁决] + Q --> H[本地硬急停
最高优先] +``` + +- Tauri capability（窗口、文件、通知等）映射为器谱设备能力项；未经人物授契的能力，Web 层不可调用； +- 实体动作执行走"云端司命 + 设备本地安全控制"双裁决；本地硬急停优先级最高； +- 镜匣身份：安装时生成设备密钥并登记器谱，可撤销证书。 + +### 3. 工程约定 + +- 目录 `desktop/`（cargo + Tauri v2 + specta 类型导出）； +- 与前端共享：加载同一份琉璃镜构建产物，不维护第二套 UI； +- 分发：签名安装包 + updater 清单；开发档允许 `devUrl` 指向本地 `next dev`； +- 交付时点：主链路（M0–M5）完成后的收口阶段（见[重写执行计划](../operations/rewrite-plan.md) M9）。 + +## 三、验收要点 + +| 项 | 验收 | +| --- | --- | +| SSE 端到端 | 断网重连后从 `Last-Event-ID` 续流，无丢帧、无重复固化为候答 | +| 裁剪安全 | 白名单外字段不出现在响应；治理/审计字段不被裁剪 | +| 镜匣授权 | 未授契能力调用被拒并留痕；硬急停可中断本地执行 | +| 密钥边界 | 桌面壳与前端零平台密钥；所有请求经照壁 | diff --git a/docs/architecture/data-model.md b/docs/architecture/data-model.md new file mode 100644 index 0000000..54cf4da --- /dev/null +++ b/docs/architecture/data-model.md @@ -0,0 +1,177 @@ +# 魂镜数据模型 + +> 状态：重写目标态（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` | 当前生效版本：多维关系维度（`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. 灵台域（运行、能力与安全） + +```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 与回放的数据源 | +| `tools` / `skills` | 百工注册表：稳定标识、参数 Schema、执行类型（HTTP/MCP/乾坤/内置）、四维风险标注 | +| `mandates` | 授契（单次范围）与行契（重复执行：能力/参数/数据/目标/预算/时间窗）；可撤销，撤销立即生效 | +| `confirmations` | 请命：待确认动作、风险说明、超时策略（超时=拒绝执行）；含死亡、重忆、铸魂等高影响确认 | +| `tool_calls` / `evidence` | 调用记录与证据链：输入输出摘要（净化后）、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 个迁移，以本模型为新基线 `0001`；迁移与退役的执行顺序见[重写执行计划](../operations/rewrite-plan.md)。 + +## 10. 隐私与删除的落库规则 + +- 敏感字段（重忆内容、克隆授权、私箧类）列级标注敏感等级；默认查询路径不得返回高敏原文（摘要或脱敏）。 +- 删除传播：人物死亡≠数据删除；数据删除按"权威存储→向量索引→缓存→派生视图→主动对话候选"顺序停用，墓碑只留行为证据。 +- 跨人物共享（本相授权）以授权记录为查询前提，缘识与心痕默认人物私有，不做任何跨人物隐式 JOIN。 diff --git a/docs/architecture/lingtai-runtime.md b/docs/architecture/lingtai-runtime.md new file mode 100644 index 0000000..aa78724 --- /dev/null +++ b/docs/architecture/lingtai-runtime.md @@ -0,0 +1,245 @@ +# 灵台插件化运行时 + +> 状态：重写目标态（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
投影快照引用] + 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[平台硬边界
禁域与全局上限] --> E[最终 Profile] + B[平台目录
默认插件与参数] --> E + C[用户偏好 / BYOK] --> E + D[人物覆写
道体·人格·能力授契] --> E + F[镜树临时选择
模型·火候·指引] --> 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 入口验证。 diff --git a/docs/architecture/service-boundaries.md b/docs/architecture/service-boundaries.md index 94989e9..a79ad09 100644 --- a/docs/architecture/service-boundaries.md +++ b/docs/architecture/service-boundaries.md @@ -1,78 +1,93 @@ -# 四服务边界 +# 服务边界 + +> 状态：重写目标态（rewrite/1.0 基线） +> 文化名与工程对象登记见[契约词典 §2](../contracts/contract-glossary.md)；本文只定义职责边界与协作规则。 ## 1. 边界原则 1. 人物状态只由灵台业务规则解释和改变。 -2. 神识通模型协议，不拥有数字人物。 -3. 百工在灵台统一注册能力，乾坤只负责隔离执行与设备安全。 -4. 琉璃镜只经公开契约调用服务，不成为安全或数据旁路。 +2. 神识通模型协议，不拥有数字人物；博闻通外部检索，不解释观察结果。 +3. 百工在灵台统一注册能力，乾坤只负责隔离执行与资源约束。 +4. 琉璃镜与镜匣只经公开契约经照壁调用服务，不成为安全或数据旁路。 5. 跨服务只传稳定标识、版本化 Schema 和可追踪上下文；不得共享内部数据库表作为接口。 +6. 能力可按部署档位关闭，服务职责与禁域不因档位消失。 -## 2. 灵台（Python） +## 2. 琉璃镜（前端，Next.js） -**拥有：**人物身份与命台业务、镜树与归真、人格/记忆/关系/世界认知、九枢认知运行、能力授权与司命裁决、百工能力目录、行动账业务语义。 +**拥有**：全部 Web 体验、镜树当前路径阅读与局部树图、候答切换/采用/归真交互、治理与确认界面、运行轨迹展示、Live2D 与浏览器通感呈现、设计体系（Lucide 图标、无表情符号、Awwwards 级视觉标准）。 -**不拥有：**Provider 方言与 Endpoint 连接池、不可信代码执行环境、Web 展现状态。 +**不拥有**：平台密钥、权威人物状态、风险最终裁决、不可信执行、绕过照壁的后端直连。 -灵台向神识发送最小必要的模型请求，向乾坤发送已裁决且范围明确的执行请求；返回结果先作为观察净化和标证，不自动成为事实、答复或记忆。 +前端服务端状态使用 TanStack Query，请求经 openapi-fetch 以灵台 OpenAPI 生成的类型发出；组件状态 Zustand。页面信息架构遵循主 PRD §12：镜庭、人物、镜树、天工阁、神识阁、设置。 -## 3. 神识（Go，目标服务） +## 3. 照壁（BFF，Fastify） -当前独立 Go 神识尚未落地；Python `ai_provider` 暂时承担下述职责。现有 Go 玄关只负责 MCP 服务与工具管理，不能与神识混同。 +**拥有**：鉴权透传（JWT Cookie 与刷新）、SSE/WebSocket 双向代理（禁缓冲、断线续传透传）、响应裁剪与字段白名单、openapi-fetch 类型桥接、跨灵台接口的轻量聚合、请求日志（pino）。 -**拥有：**Provider/Endpoint 目录、模型能力槽位、协议转换、路由、流式、故障切换、BYOK 接入、配额和成本计量。 +**不拥有**：业务规则、人物状态、模型协议、权限裁决、任何权威数据存储。照壁可以做响应裁剪，但不得替灵台决定"用户能否看到"——鉴权语义一律来自灵台。 -**不拥有：**人物 ID 的身份解释、道体、记忆、关系、缘契、长期状态和工具授权决策。 +**约束**：照壁是无状态服务，水平扩展不依赖会话粘滞；SSE 代理必须设置 `X-Accel-Buffering: no` 并透传 `Last-Event-ID`。 -神识可以按隐私与能力约束选择端点，但不得把模型差异写成人格变化。其架构与功能可参考 aiway，但不 Fork、不复制源码、不把 aiway 作为运行依赖。 +## 4. 灵台（后端核心，Python FastAPI） -## 4. 玄关（Go，当前辅助服务） +**拥有**：六域业务（镜生/缘契/三界/形仪/灵台域/天宰）、插件化认知运行时与九枢装配、镜树与归真、三级记忆管线、缘契版本、司命裁决与行动账、百工能力目录、MCP Client（stdio/SSE）、工具注册表、事件溯源（一炁）、魂籍导出。 -**拥有：**MCP 服务登记、工具发现、管理接口和调用入口治理。 +**不拥有**：Provider 方言与 Endpoint 连接池（神识职责）、不可信代码执行环境（乾坤职责）、Web 展现状态（琉璃镜职责）。 -**不拥有：**模型 Provider 路由、人物状态、工具授权裁决或不可信执行。玄关注册出的工具仍须进入灵台百工目录并接受司命裁决；玄关不能因当前独立部署而被视为第五个产品领域。 +灵台向神识发送最小必要的版本化模型请求，向乾坤发送已裁决且范围明确的执行请求；返回结果先作为观察净化标证。运行时结构见[灵台运行时](lingtai-runtime.md)。 -## 5. 乾坤（Rust） +**基础设施复用边界**：现有 auth/RBAC/审计/事件存储/幂等/SSE 网关代码保留改造接入新领域层；旧领域模块（personality/drive/evolution/wuxing/time_sense/knocking/big_cycle 等）按[重写执行计划](../operations/rewrite-plan.md)退役删除。 -**拥有：**不可信执行隔离、资源约束、执行取消、设备可信状态、本地安全控制器和硬急停。 +## 5. 神识（模型网关，Go） -**不拥有：**人物目标、长期状态、模型路由、关系语义或许可扩张。 +**拥有**：Provider/Endpoint 目录、模型能力槽位、入站协议转换（内部 IR → 各厂商方言）、路由与故障切换、流式转发、BYOK 密钥保管、配额与成本计量、用量日志。 -现实动作须同时通过云端司命裁决与设备本地安全控制；本地硬急停优先级最高。设备失联只允许安全自治和输入暂存，不允许产生可独立成长的完整人物副本。 +**不拥有**：人物 ID 的身份解释、道体、记忆、关系、缘契、长期状态和工具授权决策。神识可以按隐私与能力约束选择端点，但不得把模型差异写成人格变化。 -## 6. 琉璃镜（Next.js） +设计详见[神识模型网关](shenshi-gateway.md)。元炁作为 `type=local` 的 Endpoint 接入神识，不与灵台直接对话。 -**拥有：**全部 Web 体验、镜树阅读与局部树图、候答采用/归真交互、授权与确认界面、运行轨迹和治理呈现。 +## 6. 博闻（MCP 搜索，Go） -**不拥有：**密钥、权威人物状态、风险最终裁决、不可信执行以及绕开后端的 Provider/数据库直连。 +**拥有**：多搜索引擎接入、密钥池轮询（EWMA 权重）、两级缓存、熔断、stdio/SSE/HTTP 三种 MCP 传输。 -## 7. 交互边界 +**不拥有**：模型路由、人物状态、工具授权裁决。博闻产出的一切搜索结果经灵台百工调用获得，先作为有来源的观察，不自动成为事实。 -```mermaid -sequenceDiagram - participant UI as 琉璃镜 - participant LT as 灵台 - participant SS as 神识 - participant QK as 乾坤 +其余 MCP 服务同理：由灵台百工登记与调用，不存在独立"网关服务"层（旧玄关退役）。 - UI->>LT: 用户意图、镜树上下文、授权范围 - LT->>LT: 司命裁决与最小能力选择 - alt 模型推理 - LT->>SS: 版本化模型请求 + trace - SS-->>LT: 标准化流与用量 - else 外部行动 - LT->>QK: 已授权执行请求 + 限制 + trace - QK-->>LT: 执行观察、状态与审计证据 - end - LT->>LT: 净化、标证、形成候答/状态事务与 Outbox - LT-->>UI: 可解释结果、证据、确认或错误 -``` +## 7. 乾坤（沙箱，Rust） -## 8. 禁止的耦合 +**拥有**：不可信执行隔离、进程组与资源上限、执行取消、HMAC 短期凭证验签、执行审计证据。 -- 琉璃镜直接持有 Provider 密钥或调用高风险工具。 +**不拥有**：人物目标、长期状态、模型路由、关系语义、权限扩张。乾坤只执行已授权任务，不做风险判定（由司命负责）。 + +现实动作须同时通过云端司命裁决与设备本地安全控制；本地硬急停优先级最高。 + +## 8. 天目 / 元炁（辅助服务，Python） + +**天目**：本地 OCR（RapidOCR / PaddleOCR-VL），为通感与文档导入提供文字提取；输出是观察，不是事实。 +**元炁**：本地推理（llama-cpp / BGE-M3 / Rerank / 多模态），仅作为神识的本地 Endpoint 与灵台的 embedding 服务接入；不独立做路由决策。 + +## 9. 镜匣（桌面壳，Tauri） + +**拥有**：桌面 WebView 承载琉璃镜、本地能力桥（文件对话框、通知、托盘）、与乾坤本地执行的通道、tantivy 本地检索（预留）、自动更新。 + +**不拥有**：平台密钥、独立的人物状态副本。设备失联只允许安全自治与输入暂存，不产生可独立成长的人物副本。详见[BFF 与桌面壳](bff-and-desktop.md)。 + +## 10. 禁止的耦合 + +- 琉璃镜/镜匣直接持有 Provider 密钥、直连神识或调用高风险工具。 +- 照壁内嵌业务规则或权威状态，成为第二个"小后端"。 - 神识直接读写人物记忆、人格或关系表。 - 乾坤根据 Prompt 自行扩大权限或目标。 -- 灵台把 Provider SDK 细节扩散到领域模块。 +- 灵台把 Provider SDK 细节扩散到领域模块（模型出口只经神识客户端边界）。 - 服务共享可写数据库账户，以共享表替代 API/事件契约。 -- 为轻量部署把神识、乾坤职责重新实现进灵台；能力可关闭，边界不能消失。 +- 为轻量部署把神识、乾坤职责重新实现进灵台。 +- 任何服务绕过一炁事件日志改变人物相关状态（"模型可见即可重建"铁律的反向适用：状态变更必须留痕）。 + +## 11. 跨服务契约 + +- 灵台 ↔ 神识：REST + SSE，版本化模型请求 Schema、用量回传、错误码段见[契约词典](../contracts/contract-glossary.md)；请求携带 `run_id`/`trace_id`，神识响应回传 `X-Request-Id` 用于关联。 +- 灵台 ↔ 乾坤：HMAC 签名执行请求，超时与取消语义以乾坤 API 为准。 +- 灵台 ↔ 博闻：MCP 协议（HTTP 传输优先）。 +- 照壁 ↔ 灵台：HTTP/SSE 透传，契约即灵台 OpenAPI。 +- 客户端 ↔ 照壁：HTTPS + JWT Cookie；SSE 事件契约见[API 契约](../contracts/api-contracts.md)。 diff --git a/docs/architecture/shenshi-gateway.md b/docs/architecture/shenshi-gateway.md new file mode 100644 index 0000000..3ec255e --- /dev/null +++ b/docs/architecture/shenshi-gateway.md @@ -0,0 +1,110 @@ +# 神识模型网关 + +> 状态：重写目标态（rewrite/1.0 基线），重写期间新建，一次性替换灵台 Python `ai_provider` +> 参考项目只借设计不复制源码：octopus（IR 双向转换、首字超时切道）、new-api（计费不变量、渠道 adaptor 分层）、lens（模型组与冷却粒度）、metapi（路由可解释）、axonhub（协议集成测试矩阵）。 + +## 1. 定位与边界 + +神识是魂镜唯一的模型出口（Go 1.25+ 单服务）： + +**拥有**：Provider/Endpoint 目录、模型能力槽位、协议转换（内部 IR ↔ 各厂商方言）、路由与故障切换、流式转发、BYOK 密钥保管、配额与成本计量、用量日志。 + +**不拥有**：人物身份解释、道体、记忆、关系、缘契、长期状态、工具授权决策。神识不因模型差异产生"人格变化"语义；模型与人格的解耦由灵台保证。 + +## 2. 模块划分 + +```mermaid +flowchart LR + IG[ingress
入站协议] --> TF[transform
IR 双向转换] + TF --> RT[route
候选生成+健康+冷却] + RT --> RL[relay
流式转发] + RL --> MT[metering
用量与成本] + MT --> QT[quota
配额三段式] + RG[registry
目录管理] + KV[keyvault
密钥与 BYOK] + RT --> KV + IG --> QT +``` + +- `transform` 做成独立 Go module（内无业务依赖，可独立构建与测试）； +- 其余模块按包组织在单服务内，不拆进程。 + +## 3. 数据模型（神识自有库） + +| 表 | 要点 | +| --- | --- | +| `providers` | 厂商协议类型（openai/anthropic/gemini/local 等） | +| `endpoints` | 多 BaseUrl + 多凭证 + 权重/优先级 + 健康状态；`type=local` 的 Endpoint 指向元炁 | +| `model_slots` | 能力槽位：chat/vision/asr/tts/image/embedding/rerank/safety；逻辑模型 → 槽位声明 | +| `routes` | 逻辑模型名 → 候选 Endpoint×上游模型 绑定列表 + 路由策略（优先级/加权/故障切换） | +| `byok_keys` | 用户自带密钥：归属 `user_id`，加密存储，API 永远脱敏返回；使用范围与用途受限 | +| `usage_logs` | 每次尝试一条：请求级终态 + 尝试链 + 流时序（首字/总时长）+ token 三段（输入/输出/缓存）+ 成本明细 | + +逻辑模型与物理模型解耦：灵台只请求逻辑模型名与槽位，神识负责落到具体 Endpoint。 + +## 4. 路由与故障切换 + +1. **候选迭代器**：按策略（优先级排序 / 加权随机）生成候选序列，逐个尝试； +2. **首字超时**：流式请求在首 token 超时内无响应即切下一候选；已写出字节后不换道（`Written` 判断），失败如实上报； +3. **冷却粒度**（避免整渠道误杀）：401/403 只冷却凭证；404/429/5xx/超时只冷却"该渠道上的具体模型绑定"，同渠道其他模型不受影响； +4. **熔断**：滑动窗口健康评分作轮询权重； +5. **粘性会话**：同一 Run 的连续请求优先成功通道（模型输出风格稳定）； +6. **路由可解释**：每次选择记录决策摘要（候选、健康、冷却状态），可审计； +7. **配对保护**：tool_call 与 tool_result 在转换、重试、压缩中永不拆散。 + +## 5. 协议与流式 + +- **入站（灵台 → 神识）**：单一内部 IR（版本化 Schema）；灵台 `shenshi_client` 是唯一调用方； +- **出站（神识 → Provider）**：各厂商 adaptor（每 Provider 一个包：adaptor + dto + relay），SSE 逐事件转换透传； +- 流式响应统一 SSE；`X-Accel-Buffering: no`；校验上游 Content-Type 防"假流"； +- **DTO 细节纪律**：可选标量一律指针 + `omitempty`，防显式零值被静默丢弃； +- 响应回传 `X-Request-Id`、用量头，与灵台 `run_id`/`trace_id` 关联（usage_logs 双向可查）。 + +## 6. BYOK 与密钥 + +- 密钥分层：平台密钥（神识 keyvault）与用户 BYOK（`byok_keys`，用户级加密）； +- 配置继承顺序（产品 PRD §9.2）：平台硬边界 → 平台目录 → 用户偏好/BYOK → 人物覆写 → 镜树临时选择；该层叠在灵台 Profile 计算，神识只接收最终解析结果中的密钥引用； +- 神识对 BYOK 的使用范围（可用槽位、地区限制）受平台硬边界约束；高敏数据可配置"仅本地 Endpoint"。 + +## 7. 配额与计量 + +计费不变量（借鉴 new-api 教训）： + +1. 任何计费乘数（图片张数、时长、max_tokens）在请求校验期设上限； +2. 配额换算集中单一函数，饱和截断（防溢出变负）； +3. 钳位与截断事件写审计日志； +4. 三段式：预扣（按上限）→ 结算（实际-预扣差额）→ 退款（失败幂等退款）； +5. 透传字段与 multipart 是校验绕过高危路径，adaptor 层显式白名单。 + +1.0 官方云计费属 P2；P0/P1 只做计量（usage_logs 完整）与用户级软配额（预算提醒与熔断）。 + +## 8. API 形态 + +| 面 | 端点 | 说明 | +| --- | --- | --- | +| 数据面 | `POST /v1/chat/completions`（IR 入站 + SSE） | 灵台唯一推理入口；附 embeddings/rerank/images/audio 端点按槽位启用 | +| 健康面 | `GET /healthz`、`GET /readyz` | 供 Compose 与天门探活 | +| 管理面 | `/admin/providers` `/admin/endpoints` `/admin/routes` `/admin/slots` | 目录 CRUD、健康探测、定价表（平台管理员） | +| 计量面 | `/admin/usage`、`/me/usage` | 用量查询（按用户/模型/时间） | + +错误码段与事件名见[契约词典](../contracts/contract-glossary.md)；服务间鉴权：灵台 ↔ 神识用服务令牌 + 请求签名，管理面走 RBAC。 + +## 9. 与元炁的关系 + +元炁是 `type=local` 的 Endpoint：神识按普通候选路由到它（本地零成本、隐私友好）。embedding/rerank 槽位默认路由元炁（BGE-M3），无本地模型时回退云厂商。天目 OCR 不经神识（非生成模型），由灵台直接调用。 + +## 10. 迁移与退役 + +1. 神识上线并接入元炁 + 至少一个云 Provider（OpenAI 兼容）； +2. 灵台 `shenshi_client` 切换流量，双写用量对比一个验证周期； +3. 删除 Python `ai_provider` 模块及其配置（`config/models.yaml`、`config/providers.yaml`、`config/pricing.yaml` 移交神识目录）； +4. 能力矩阵更新"神识网关"行证据。 + +**禁止**：把玄关改名冒充神识；灵台领域模块直接 import 任何 Provider SDK；神识读写灵台库表。 + +## 11. 测试策略 + +- adaptor 单元测试：IR ↔ 方言的往返（round-trip）一致性；可选标量零值用例； +- 集成测试矩阵：入站协议 × Provider 面板（最小集合：OpenAI 兼容、Anthropic、本地元炁）； +- 故障注入：首字超时切道、凭证冷却粒度、熔断恢复、流中断如实上报； +- 计量一致性：预扣-结算-退款幂等；usage_logs 与 Provider 用量对账抽样。 diff --git a/docs/architecture/system-architecture.md b/docs/architecture/system-architecture.md index 615309b..c9fb3b4 100644 --- a/docs/architecture/system-architecture.md +++ b/docs/architecture/system-architecture.md @@ -1,88 +1,176 @@ # 魂镜系统总架构 -> 本文同时说明当前过渡拓扑与目标架构。目标职责不表示能力已落地；当前实现和迁移差距必须由能力矩阵单独确认。 +> 状态：重写目标态（rewrite/1.0 基线） +> 上位约束：[产品宪章](../product/constitution.md)、[全产品主 PRD](../product/master-prd.md)、根目录 `AGENTS.md` 完整技术栈 +> 实现进度以[能力矩阵](../operations/capability-matrix.md)为准，本文不声明任何能力已落地。 -## 1. 架构目标 +## 1. 架构基准 -魂镜以人物连续性、用户主权、区域驻留、可审计行动和可恢复运行为首要约束。目标形态由四个清晰解耦的服务组成；轻量部署可以关闭高风险能力，但不得把职责混回其他服务。 +魂镜产品定义（六域、镜树、三级记忆、司命禁域等）保持产品与领域文档权威不变；工程架构以根目录 `AGENTS.md` 的完整技术栈为基准，按五层组织： -## 2. 当前过渡拓扑 - -当前代码尚未完成四服务物理拆分： - -- Python 灵台仍直接承载模型 Provider 配置、Endpoint 池和路由实现；这是待迁移的现状，不是目标边界； -- 现有 Go 网关是**玄关（MCP Gateway）**，负责 MCP 服务和工具管理，不是目标神识模型网关；前端 `/api/gateway/*` 代理指向玄关； -- 当前应用 Compose 未部署独立 Go 神识；依赖该能力的条目在能力矩阵中必须标为未实现或过渡实现； -- Rust 乾坤与 Next.js 琉璃镜已经有独立工程，但其生产安全与发布证据仍以能力矩阵为准。 - -过渡期新增模型接入仍应封装在 Python `ai_provider` 边界内，不向领域模块扩散 Provider SDK。迁移到 Go 神识前必须先确定模型请求/流式响应、鉴权、BYOK 密钥归属、用量、错误、回滚和并存期限；不得把现有玄关直接改名后冒充神识。 - -## 3. 目标四服务 - -| 服务 | 技术 | 核心职责 | 明确边界 | +| 层 | 技术 | 文化名 | 核心职责 | | --- | --- | --- | --- | -| 灵台 | Python | 人物身份与认知业务、镜树运行、九枢编排、记忆与关系状态、司命裁决、百工注册 | 不承担通用模型协议网关；不直接执行不可信代码 | -| 神识 | Go | Provider/Endpoint 接入、能力槽位、协议转换、路由、流式、BYOK、配额与成本 | 不拥有人物人格、记忆、关系或身份状态；参考 aiway 架构与功能，但不 Fork、不复制源码、不作为运行依赖 | -| 乾坤 | Rust | 隔离执行、设备安全、本地安全控制与硬急停边界 | 不决定人物目标，不保存可独立成长的人物副本 | -| 琉璃镜 | TypeScript / Next.js | 全部 Web 界面、响应式交互、治理与可解释呈现 | 不保存平台密钥，不绕过灵台和司命直连高风险能力 | +| 前端 | 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 - U[执镜者与互动者] --> W[琉璃镜
Next.js Web] - W --> L[灵台
Python 生命与认知业务] - L --> G[神识
Go 模型网关] - G --> P[模型 Provider / BYOK Endpoint] - L --> K[乾坤
Rust 隔离执行与设备安全] - K --> E[工具、设备与本地执行环境] - L --> D[(区域内权威数据)] - L --> A[(事件审计与行动账)] + subgraph Clients[客户端] + Browser[浏览器] + Desktop[镜匣 · Tauri 壳] + end + subgraph Edge[边缘层] + Nginx[天门 · Nginx 统一入口] + BFF[照壁 · Fastify BFF] + end + subgraph Core[核心层] + LT[灵台 · Python 后端核心
六域业务 + 插件化运行时] + 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 ``` -## 4. 区域云 +要点： -官方云面向全球开放，但能力按地区分级。每个镜域在创建或迁移时绑定一个固定数据区域：权威数据、密钥、对象、索引和备份均在该区域驻留，不因流量路由、故障转移或用户旅行自动跨区漂移。 +1. 所有客户端请求经照壁进入灵台；琉璃镜与镜匣不持有平台密钥、不直连神识或乾坤。 +2. 神识是唯一模型出口：灵台向神识发送版本化模型请求，神识负责协议转换、路由、流式与计量；元炁作为神识的一种本地 Endpoint 接入，不走独立通道。 +3. 博闻等 MCP 服务由灵台百工注册与调用；玄关（旧 Go MCP 管理网关）退役，MCP 服务登记并入灵台百工。 +4. 乾坤只执行经司命裁决且范围明确的请求；乾坤不判断风险、不拥有人物状态。 -架构须支持多区域；1.0 只在少量已验证区域实际运营。实际首发区域、运营主体、隐私控制者、支付税务和正式法律文本属于发布决策门，本文不指定。 +## 3. 交互总链路 ```mermaid -flowchart TB - R[全球入口与地区能力判定] - R --> RegionAEntry[区域 A 入口] - R --> RegionBEntry[区域 B 入口] - R --> N[后续已验证区域] - subgraph RegionA[镜域固定驻留区域 A] - RegionAEntry --> A1[四服务实例] - A1 --> A2[(权威数据、密钥、对象、索引、备份)] +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 - subgraph RegionB[镜域固定驻留区域 B] - RegionBEntry --> B1[四服务实例] - B1 --> B2[(权威数据、密钥、对象、索引、备份)] - end - A2 -.仅经正式迁移协议.-> B2 + LT->>LT: 净化标证 + 状态事务 + Outbox 事件 + LT-->>ZB: SSE 事件流 / JSON + ZB-->>UI: 透传流 + 响应裁剪 ``` +灵台返回的工具与模型结果先作为带来源的观察进入事件日志，不自动成为事实、人物答复或长期记忆；该铁律的运行时保障见[灵台运行时](lingtai-runtime.md)。 + +## 4. 灵台内部分层 + +```mermaid +flowchart TD + API[API 层 · api/v1 + SSE] + Domain[六域领域层
镜生 / 缘契 / 三界 / 形仪 / 灵台域 / 天宰] + Kernel[极小硬核 Kernel
不变量裁决 + 命台并发 + 事件溯源 + 循环骨架] + Plugins[插件层 · 九枢装配
灵核 / 太一 / 司命 / 烛照 / 河图 / 洛书 / 息壤 / 百工 / 天工阁] + Infra[基础设施复用层
auth / RBAC / 审计 / 事件存储 / 幂等 / SSE 网关] + API --> Domain + Domain --> Kernel + Kernel --> Plugins + Domain --> Infra +``` + +- 领域层按六域建模，拥有业务规则与状态；运行时详细设计见[灵台运行时](lingtai-runtime.md)，数据模型见[数据模型](data-model.md)。 +- Kernel 是不可插拔的最小核心：镜树不变量（重新生成不覆盖、未归真不入忆、归真不静默回滚）、命台唯一前台意识流、司命禁域裁决点、"模型可见即可重建"断言。 +- 九枢全部以插件装配；司命插件常驻，其禁域规则挂载点不可卸载、不可降权。 + ## 5. 数据总架构 -- 关系数据库是当前状态事实源。 -- 关键事件、治理裁决与外部行动形成不可缺失的审计链。 -- 状态变更与事件通过同一事务或 Outbox 一致提交，避免“状态已变但事件缺失”。 -- 轻量自托管采用 SQLite、可选 Chroma/向量层、本地对象存储和内存协调。 -- 标准服务采用 PostgreSQL、pgvector、S3/MinIO 与 Redis；Milvus 和图库只在真实规模需要时引入。 -- 可重建索引不是权威事实源；任何恢复均须从权威数据重建并校验。 +- 关系数据库（本地 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 小时**；媒体和可重建索引可以采用更宽目标，但不得阻碍权威状态恢复。 +- 核心文字相伴官方云 1.0 目标 SLO 99.9%；权威人物数据 RPO ≤ 5 分钟、RTO ≤ 1 小时；媒体与可重建索引可采用更宽目标。 +- 手段：健康检查、超时与限流、神识端点故障切换（首字超时切道）、幂等键、事务/Outbox、可验证备份与恢复演练。 +- SSE 断线续传：事件带单调序号，客户端以 `Last-Event-ID` 重连，中间状态可在 Redis 缓存恢复；恢复不得违反"未完成芽体不伪装为完整候答"。 +- 模型、工具与区域故障下安全降级：降级只影响能力可用性，不破坏人物连续性与已归真经历。 -可靠性手段包括：健康检查、超时与限流、模型端点故障切换、幂等、事务/Outbox、可验证备份、恢复演练、区域内高可用，以及对降级能力的显式说明。跨区域灾备不得突破镜域固定驻留约束；若需要跨区迁移，必须走正式身份与数据迁移协议。 - -## 7. 部署档位 +## 7. 部署分档 | 档位 | 目标 | 基础设施 | | --- | --- | --- | -| 本地开发 | 单机开发与测试，不可用于生产 | SQLite、本地对象、内存协调；允许宿主端口和示例凭证 | -| 轻量单机 | 私人闭环、低运维、自托管 | SQLite、本地对象、内存协调，可选本地向量层 | -| 标准服务器 | 稳定多人/多人物服务 | PostgreSQL、pgvector、S3/MinIO、Redis | -| 官方区域云 | 区域驻留、可运营、满足发布门 | 四服务区域化部署、区域内高可用、备份与灾备体系 | +| 本地开发 | 单机开发测试，不可用于生产 | SQLite、本地对象、进程内协调；允许示例凭证与宿主端口 | +| 轻量单机 | 私人闭环、低运维自托管 | SQLite、本地对象，可选本地向量层与 Redis | +| 标准服务器 | 稳定多人/多人物服务 | PostgreSQL + pgvector、Redis、MinIO；按需 Milvus / Neo4j | +| 官方区域云 | 区域驻留、可运营 | 五层服务区域化部署、区域内高可用、备份与灾备体系 | -自托管以 Docker Compose 为主、源码开发为辅，遥测默认关闭。部署档位改变基础设施规模，不改变四服务的逻辑职责或禁域。`change-me`、无认证管理端口、宿主机全量端口暴露和 `STORAGE_PROVIDER=local` 只允许本地开发；标准服务器和官方云必须在启动/发布检查中拒绝这些配置。 +- 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 需要 |