# 系统架构

## 1. 逻辑架构

完整 1.0 由多端客户端、统一 API、领域模块、Agent/Plugin Runtime、媒体与实时处理、生态与交易模块以及隔离执行边界组成。逻辑边界是强约束，物理部署可按规模合并或拆分。

```mermaid
flowchart LR
  subgraph Clients
    WEB[Web]
    DESK[Tauri Desktop]
    MOB[Tauri Mobile]
  end

  WEB & DESK & MOB --> EDGE[API and Realtime Edge]
  EDGE --> CORE[Core Application]
  CORE --> AGENT[Agent Runtime]
  CORE --> SOCIAL[Community and Collaboration]
  CORE --> MARKET[Marketplace and Ledger]
  CORE --> MEDIA[Media and Avatar Runtime]
  AGENT --> PLUGIN[Plugin Runtime]
  PLUGIN --> MODELS[Model Providers]
  PLUGIN --> TOOLS[Tools and MCP]
  CORE --> DATA[(Primary Data)]
  MEDIA --> OBJECTS[(Media Objects)]
  AGENT --> SANDBOX[Sandbox Workers]
```

## 2. 模块职责

| 模块 | 职责 | 禁止承担 |
| --- | --- | --- |
| Identity & Domain | 登录、用户、设备、数据域、会话 | 角色人格和模型路由 |
| Character | 角色、设定版本、关系、谱系、导入导出 | Provider 凭据和交易账 |
| Conversation | 多模态消息、分支、引用、流式和压缩 | 决定长期记忆写入 |
| Memory & Knowledge | 候选、版本、召回、纠正、删除、索引 | 覆盖角色基线 |
| Agent Runtime | Agent/Run/Turn、计划、并行、暂停、取消、验收 | 绕过 Policy 执行工具 |
| Model Gateway | Provider、逻辑模型、路由、流式、usage、成本 | 角色和社区业务 |
| Plugin Runtime | Manifest、生命周期、Snapshot、Registry、SDK | 身份根策略和交易账 |
| Tool & Sandbox | Schema、审批、幂等、隔离执行、结果净化 | 自行扩大能力范围 |
| Media Pipeline | ASR/TTS、图像、Live2D、3D 资产处理 | 授予设备采集权限 |
| Avatar Runtime | Live2D/3D 渲染、动作、表情、场景同步 | 修改权威角色数据 |
| Device Capability | 文件、相机、麦克风、屏幕、位置和设备授权 | 后台常开采集 |
| Community | 社交图、内容、互动、搜索、推荐、治理 | 支付结算和私密记忆 |
| Collaboration | Workspace、RBAC、邀请、评审、版本、协同 | 跨 Workspace 隐式共享 |
| Marketplace | 商品、许可、交付和版本可售性 | 直接改写支付账 |
| Payment & Ledger | 订单、支付、退款、分成、余额、结算、对账 | 浮点金额和可变历史账 |
| Policy & Moderation | 工具、插件、设备、内容、交易和年龄策略 | 执行业务副作用 |
| Observability | Trace、Run 诊断、审计、成本、支持包 | 普通接口泄露敏感正文 |

## 3. 物理部署原则

开发期可在模块化单体中合并多数业务模块，但以下边界必须独立：

- Sandbox Worker：执行不可信代码；
- Media Worker：处理重型媒体任务；
- Realtime Gateway：SSE/WebSocket/语音会话；
- Payment Webhook Consumer：验签、幂等和账务入账；
- Object Storage：媒体和市场交付物；
- Search/Index Worker：全文、向量和社区索引。

```mermaid
flowchart TD
  C[Clients] --> E[Edge and Realtime]
  E --> A[Application API]
  A --> DB[(PostgreSQL)]
  A --> R[(Redis)]
  A --> S3[(S3-compatible Storage)]
  A --> W[Job Workers]
  W --> SB[Sandbox Pool]
  W --> GPU[Media or GPU Workers]
  W --> IDX[Search and Vector Index]
  A --> PAY[Payment Providers]
  PAY --> WH[Webhook Consumer]
  WH --> DB
```

PersonalDomain 创建或迁移时绑定一个固定数据区域：权威数据、密钥、对象、索引和备份在该区域驻留，不因流量路由、故障转移或用户旅行自动跨区漂移；跨区只能走正式迁移协议。跨区模型处理按地区规则、数据敏感度和用户授权单独治理，且必须经用户明确披露与授权；高敏数据（含私箧）可完全禁止跨区模型处理。

自托管遥测默认关闭。本地开发可用 SQLite、本地对象和单 Worker；完整 1.0 正式云与社区/交易部署使用 PostgreSQL、Redis、对象存储和异步 Worker。向量库、图数据库与独立 Go 网关按量化规模选择，不因技术清单强制引入。灵台引擎默认进程内嵌入；满足独立扩缩容、故障域或资源隔离标准时可启用 `hunjing-lingtai-server` 独立服务形态（见[灵台引擎架构](lingtai-engine.md)）。

## 4. 客户端边界

- Web：完整社区、市场、创作、对话和管理体验。
- Tauri Desktop：Web 能力加本地文件、屏幕、相机、麦克风、系统通知和沙箱桥接。
- Tauri Mobile：iOS/Android 的相机、麦克风、文件、位置、通知和 Avatar 运行。
- 客户端权限由平台权限和 Hunjing `device_grant` 双重约束。
- 客户端不保存平台 Provider 密钥；离线缓存按用户和设备加密。

## 5. 数据与信任边界

1. 每次资源访问验证数据域、Workspace、角色、内容可见性和交易主体。
2. Provider Header deny-by-default，仅 Adapter 白名单透传。
3. 插件贡献能力；Core 决定加载、权限、审批、数据和审计。
4. 未可信插件不进入主进程；没有可用隔离后端时拒绝执行。
5. 支付 Provider Webhook 先验签和幂等，再写不可变账务记录。
6. 社区公开内容、协作私有内容、角色私密数据和诊断数据使用不同访问策略。
7. 设备采集默认关闭，逐能力展示状态并可即时撤回。
8. 市场许可不自动授予插件执行权限、角色私密数据或设备能力。

## 6. 可靠性目标

1.0 目标值：核心文字相伴官方云 SLO 99.9%；权威数据 RPO 不高于 5 分钟、RTO 不高于 1 小时，以恢复演练而非配置声明证明；媒体与可重建索引可采用更宽目标但不阻塞权威恢复。SLI 口径、窗口与排除规则在发布门前定义并验证（见[发布门](../product/complete-1.0-scope.md#44-可靠性门)）。

## 7. 服务拆分标准

模块只有满足独立扩缩容、故障域、数据/密钥边界、团队发布节奏或量化瓶颈时才拆服务。拆分保持端口、事件和账务契约；不因语言偏好拆分。