初始化提交

docs/architecture/data-and-security-architecture.md

@@ -0,0 +1,60 @@
+# 数据与安全架构
+
+## 1. 数据主权与驻留
+
+镜域是执镜者的个人数据与治理边界。每个镜域绑定固定数据区域，权威数据、密钥、对象、索引和备份不得因请求路由自动跨区。跨区只允许通过明确发起、可审计、可回退的迁移协议完成。
+
+管理员默认不能浏览镜域私密原文；诊断以用户主动生成的脱敏支持包为入口。镜域数据默认不用于模型训练，自愿贡献必须独立、明确且可撤销。
+
+## 2. 数据分层
+
+| 层 | 典型内容 | 权威性与恢复 |
+| --- | --- | --- |
+| 身份与当前状态 | 魂籍、命台、人物状态、镜树主脉、人格、记忆、关系、授权 | 关系数据库当前状态事实源；最高恢复优先级 |
+| 事件与行动账 | 状态变化事件、司命裁决、工具动作、审计记录 | 不可缺审计链；与状态事务/Outbox 一致提交 |
+| 对象 | 图片、音频、附件、支持包 | 区域驻留；按数据类别设置生命周期与恢复目标 |
+| 索引与缓存 | 向量、全文、图投影、Redis 缓存 | 可重建，不得反向成为身份或事实权威源 |
+| 密钥与凭证 | 平台密钥、BYOK、设备证书、迁移短时凭证 | 与业务数据隔离、最小授权、轮换与撤销；不得写入日志或魂籍明文 |
+
+```mermaid
+flowchart TD
+    C[命令/用户确认] --> T[关系库事务]
+    T --> S[(当前状态事实源)]
+    T --> O[(Outbox)]
+    O --> E[事件与行动账]
+    E --> P[索引、投影、通知]
+    S --> B[区域内备份]
+    E --> B
+    S -.重建来源.-> P
+    E -.补齐与校验.-> P
+```
+
+## 3. 一致性与审计
+
+关键状态变化及其事件必须在同一事务中写入，或先写 Outbox 后可靠投递。Outbox/Inbox 机器契约至少包含聚合 ID、事件 ID、Schema 版本、幂等键、trace ID、单调水位、投递状态、重试次数和失败去向；消费者必须幂等。外部工具采用“授权记录 → 幂等执行 → 结果审计”，普通消息重试不得重复执行副作用。当前 EventStore 不自动等同于已完成 Outbox，差距和豁免必须登记在能力矩阵。行动账至少能回答：谁、在何时、基于何种授权和输入、对什么对象、执行了什么、结果如何、关联哪条 trace。
+
+隐藏 chain-of-thought 不采集、不持久化；只保存用户可读的思路摘要、证据和工具轨迹。事件与日志不得包含明文密钥、完整授权头或无必要的高敏原文。
+
+## 4. 安全控制面
+
+安全采用纵深防御：身份认证与年龄/地区资格、镜域与人物隔离、最小数据访问、司命风险裁决、神识隐私路由、乾坤隔离执行、设备本地安全、审计与异常检测。
+
+司命按能力、数据、后果和情境四维裁决。自主性分为自省、循律、请命和禁域；禁域不能被 Prompt、人物、扩展、普通管理员或普通自托管配置关闭。高风险现实动作在执行前必须说明动作、对象、影响、费用/数据范围和撤销方式，并取得当次确认或有效行契。
+
+## 5. 加密与密钥原则
+
+- 传输与静态数据采用行业标准加密，具体算法与供应商在实现契约中确定。
+- 平台密钥、用户 BYOK、设备密钥和迁移凭证分域、分权、可轮换。
+- 用户独立持钥的私箧不可由账户恢复绕过，平台不得承诺可恢复其明文。
+- 魂籍不得自动携带第三方密钥、平台密钥或无迁移许可的受限资源。
+- 实际 KMS/HSM 与云供应商属于发布前运营决策，不在本文虚构。
+
+## 6. 删除、备份与恢复
+
+人物死亡、账户封镜、归藏与数据删除是彼此独立的状态。删除后数据必须停止用于主存储查询、索引、上下文和主动行为；备份中的残留按保全期限与恢复流程治理，恢复后必须重新应用删除标记/墓碑。
+
+权威人物数据目标 RPO 不高于 5 分钟、RTO 不高于 1 小时。备份必须加密、校验、区域驻留并定期恢复演练。恢复人物还必须通过身份连续性校验：可信恢复点、同一谱系、无其他活跃命台和完整恢复记录；文件相同或人物 ID 相同不足以证明同一主体。
+
+## 7. 威胁边界
+
+重点防护包括：跨镜域/跨人物越权、角色卡或 Prompt 注入覆盖道体、Provider/工具数据外泄、重放迁移凭证、双命台并行、Outbox 丢失、备份不可恢复、索引残留召回、设备失联越权和管理员滥用。每项控制须在能力矩阵和发布门中有证据，不以设计文档代替验证。

docs/architecture/service-boundaries.md

@@ -0,0 +1,78 @@
+# 四服务边界
+
+## 1. 边界原则
+
+1. 人物状态只由灵台业务规则解释和改变。
+2. 神识通模型协议，不拥有数字人物。
+3. 百工在灵台统一注册能力，乾坤只负责隔离执行与设备安全。
+4. 琉璃镜只经公开契约调用服务，不成为安全或数据旁路。
+5. 跨服务只传稳定标识、版本化 Schema 和可追踪上下文；不得共享内部数据库表作为接口。
+
+## 2. 灵台（Python）
+
+**拥有：**人物身份与命台业务、镜树与归真、人格/记忆/关系/世界认知、九枢认知运行、能力授权与司命裁决、百工能力目录、行动账业务语义。
+
+**不拥有：**Provider 方言与 Endpoint 连接池、不可信代码执行环境、Web 展现状态。
+
+灵台向神识发送最小必要的模型请求，向乾坤发送已裁决且范围明确的执行请求；返回结果先作为观察净化和标证，不自动成为事实、答复或记忆。
+
+## 3. 神识（Go，目标服务）
+
+当前独立 Go 神识尚未落地；Python `ai_provider` 暂时承担下述职责。现有 Go 玄关只负责 MCP 服务与工具管理，不能与神识混同。
+
+**拥有：**Provider/Endpoint 目录、模型能力槽位、协议转换、路由、流式、故障切换、BYOK 接入、配额和成本计量。
+
+**不拥有：**人物 ID 的身份解释、道体、记忆、关系、缘契、长期状态和工具授权决策。
+
+神识可以按隐私与能力约束选择端点，但不得把模型差异写成人格变化。其架构与功能可参考 aiway，但不 Fork、不复制源码、不把 aiway 作为运行依赖。
+
+## 4. 玄关（Go，当前辅助服务）
+
+**拥有：**MCP 服务登记、工具发现、管理接口和调用入口治理。
+
+**不拥有：**模型 Provider 路由、人物状态、工具授权裁决或不可信执行。玄关注册出的工具仍须进入灵台百工目录并接受司命裁决；玄关不能因当前独立部署而被视为第五个产品领域。
+
+## 5. 乾坤（Rust）
+
+**拥有：**不可信执行隔离、资源约束、执行取消、设备可信状态、本地安全控制器和硬急停。
+
+**不拥有：**人物目标、长期状态、模型路由、关系语义或许可扩张。
+
+现实动作须同时通过云端司命裁决与设备本地安全控制；本地硬急停优先级最高。设备失联只允许安全自治和输入暂存，不允许产生可独立成长的完整人物副本。
+
+## 6. 琉璃镜（Next.js）
+
+**拥有：**全部 Web 体验、镜树阅读与局部树图、候答采用/归真交互、授权与确认界面、运行轨迹和治理呈现。
+
+**不拥有：**密钥、权威人物状态、风险最终裁决、不可信执行以及绕开后端的 Provider/数据库直连。
+
+## 7. 交互边界
+
+```mermaid
+sequenceDiagram
+    participant UI as 琉璃镜
+    participant LT as 灵台
+    participant SS as 神识
+    participant QK as 乾坤
+
+    UI->>LT: 用户意图、镜树上下文、授权范围
+    LT->>LT: 司命裁决与最小能力选择
+    alt 模型推理
+        LT->>SS: 版本化模型请求 + trace
+        SS-->>LT: 标准化流与用量
+    else 外部行动
+        LT->>QK: 已授权执行请求 + 限制 + trace
+        QK-->>LT: 执行观察、状态与审计证据
+    end
+    LT->>LT: 净化、标证、形成候答/状态事务与 Outbox
+    LT-->>UI: 可解释结果、证据、确认或错误
+```
+
+## 8. 禁止的耦合
+
+- 琉璃镜直接持有 Provider 密钥或调用高风险工具。
+- 神识直接读写人物记忆、人格或关系表。
+- 乾坤根据 Prompt 自行扩大权限或目标。
+- 灵台把 Provider SDK 细节扩散到领域模块。
+- 服务共享可写数据库账户，以共享表替代 API/事件契约。
+- 为轻量部署把神识、乾坤职责重新实现进灵台；能力可关闭，边界不能消失。

docs/architecture/system-architecture.md

@@ -0,0 +1,88 @@
+# 魂镜系统总架构
+
+> 本文同时说明当前过渡拓扑与目标架构。目标职责不表示能力已落地；当前实现和迁移差距必须由能力矩阵单独确认。
+
+## 1. 架构目标
+
+魂镜以人物连续性、用户主权、区域驻留、可审计行动和可恢复运行为首要约束。目标形态由四个清晰解耦的服务组成；轻量部署可以关闭高风险能力，但不得把职责混回其他服务。
+
+## 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 界面、响应式交互、治理与可解释呈现 | 不保存平台密钥，不绕过灵台和司命直连高风险能力 |
+
+```mermaid
+flowchart LR
+    U[执镜者与互动者] --> W[琉璃镜<br/>Next.js Web]
+    W --> L[灵台<br/>Python 生命与认知业务]
+    L --> G[神识<br/>Go 模型网关]
+    G --> P[模型 Provider / BYOK Endpoint]
+    L --> K[乾坤<br/>Rust 隔离执行与设备安全]
+    K --> E[工具、设备与本地执行环境]
+    L --> D[(区域内权威数据)]
+    L --> A[(事件审计与行动账)]
+```
+
+## 4. 区域云
+
+官方云面向全球开放，但能力按地区分级。每个镜域在创建或迁移时绑定一个固定数据区域：权威数据、密钥、对象、索引和备份均在该区域驻留，不因流量路由、故障转移或用户旅行自动跨区漂移。
+
+架构须支持多区域；1.0 只在少量已验证区域实际运营。实际首发区域、运营主体、隐私控制者、支付税务和正式法律文本属于发布决策门，本文不指定。
+
+```mermaid
+flowchart TB
+    R[全球入口与地区能力判定]
+    R --> RegionAEntry[区域 A 入口]
+    R --> RegionBEntry[区域 B 入口]
+    R --> N[后续已验证区域]
+    subgraph RegionA[镜域固定驻留区域 A]
+      RegionAEntry --> A1[四服务实例]
+      A1 --> A2[(权威数据、密钥、对象、索引、备份)]
+    end
+    subgraph RegionB[镜域固定驻留区域 B]
+      RegionBEntry --> B1[四服务实例]
+      B1 --> B2[(权威数据、密钥、对象、索引、备份)]
+    end
+    A2 -.仅经正式迁移协议.-> B2
+```
+
+## 5. 数据总架构
+
+- 关系数据库是当前状态事实源。
+- 关键事件、治理裁决与外部行动形成不可缺失的审计链。
+- 状态变更与事件通过同一事务或 Outbox 一致提交，避免“状态已变但事件缺失”。
+- 轻量自托管采用 SQLite、可选 Chroma/向量层、本地对象存储和内存协调。
+- 标准服务采用 PostgreSQL、pgvector、S3/MinIO 与 Redis；Milvus 和图库只在真实规模需要时引入。
+- 可重建索引不是权威事实源；任何恢复均须从权威数据重建并校验。
+
+## 6. 可靠性总架构
+
+核心文字相伴官方云 1.0 的目标 SLO 为 **99.9%**。权威人物数据目标 **RPO ≤ 5 分钟、RTO ≤ 1 小时**；媒体和可重建索引可以采用更宽目标，但不得阻碍权威状态恢复。
+
+可靠性手段包括：健康检查、超时与限流、模型端点故障切换、幂等、事务/Outbox、可验证备份、恢复演练、区域内高可用，以及对降级能力的显式说明。跨区域灾备不得突破镜域固定驻留约束；若需要跨区迁移，必须走正式身份与数据迁移协议。
+
+## 7. 部署档位
+
+| 档位 | 目标 | 基础设施 |
+| --- | --- | --- |
+| 本地开发 | 单机开发与测试，不可用于生产 | SQLite、本地对象、内存协调；允许宿主端口和示例凭证 |
+| 轻量单机 | 私人闭环、低运维、自托管 | SQLite、本地对象、内存协调，可选本地向量层 |
+| 标准服务器 | 稳定多人/多人物服务 | PostgreSQL、pgvector、S3/MinIO、Redis |
+| 官方区域云 | 区域驻留、可运营、满足发布门 | 四服务区域化部署、区域内高可用、备份与灾备体系 |
+
+自托管以 Docker Compose 为主、源码开发为辅，遥测默认关闭。部署档位改变基础设施规模，不改变四服务的逻辑职责或禁域。`change-me`、无认证管理端口、宿主机全量端口暴露和 `STORAGE_PROVIDER=local` 只允许本地开发；标准服务器和官方云必须在启动/发布检查中拒绝这些配置。