zclaw_openfang/docs/features/SYSTEM_ARCHITECTURE.md

ZCLAW 多端系统架构文档

版本: 1.0 | 日期: 2026-03-29 | 状态: 待审核

---

目录

1. 系统总览
2. 端口与协议分配
3. 技术栈选型
4. 数据流向
5. SaaS 后端 API 接口清单
6. 桌面端内部通信
7. 权限体系
8. 各端交互逻辑
9. 部署与启动
10. 接口设计背景与业务价值

---

1. 系统总览

ZCLAW 是面向中文用户的 AI Agent 桌面客户端，由 4 个独立服务/端 组成：

┌─────────────────────────────────────────────────────────────────┐
│                        ZCLAW 系统架构                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │  Desktop App  │  │  Admin Web   │  │  SaaS Backend        │  │
│  │  (Tauri+React)│  │  (Next.js)   │  │  (Axum + PostgreSQL) │  │
│  │  Port: 1420   │  │  Port: 3000  │  │  Port: 8080          │  │
│  │               │  │              │  │                      │  │
│  │  内核模式:     │  │  管理后台     │  │  REST API            │  │
│  │  Tauri IPC    │  │  JWT 鉴权     │  │  JWT + API Token     │  │
│  │               │  │              │  │  RBAC 权限            │  │
│  │  网关模式:     │  │              │  │                      │  │
│  │  WS :50051    │  │              │  │  ┌────────────────┐  │  │
│  │  WS :4200     │  │              │  │  │  PostgreSQL     │  │  │
│  │               │  │              │  │  │  Port: 5432    │  │  │
│  │  SaaS 模式:   │  │              │  │  └────────────────┘  │  │
│  │  HTTPS REST   │  │              │  │                      │  │
│  └──────────────┘  └──────────────┘  └──────────────────────┘  │
│                                                                 │
│  ┌──────────────┐  ┌──────────────┐                             │
│  │  ZCLAW 网关   │  │  LLM 服务商  │                             │
│  │  (独立二进制) │  │  (外部)      │                             │
│  │  Port: 4200   │  │  OpenAI 等   │                             │
│  │  Port: 50051  │  │              │                             │
│  └──────────────┘  └──────────────┘                             │
└─────────────────────────────────────────────────────────────────┘

核心设计理念

• 双模式架构: 桌面端支持「本地内核」(离线/低延迟) 和「远程网关」(团队协作) 两种运行模式
• 统一 LLM 接入: 4 条 LLM 路径 (直连 OpenAI、直连火山引擎、SaaS 中转、网关透传)
• 集中管控: SaaS 后端统一管理账号、模型、服务商、Prompt 模板、配置同步
• 安全审计: 完整的操作日志 + TOTP 2FA + JWT + RBAC

---

2. 端口与协议分配

端口	服务	协议	用途	启动方式
1420	Vite Dev Server	HTTP	桌面端前端开发服务 (仅 dev)	pnpm tauri dev
3000	Next.js Dev Server	HTTP	Admin 管理后台开发服务	pnpm dev (admin/)
4200	ZCLAW Gateway/Kernel	WebSocket + REST	网关备用端口	ZCLAW 二进制
50051	ZCLAW Gateway	WebSocket + REST	网关主端口	ZCLAW 二进制
5432	PostgreSQL	PostgreSQL Wire	SaaS 后端数据库	Docker/start-all.ps1
8080	SaaS Backend	HTTP REST	管理后台 API + 中转代理	start-saas.ps1
4444	ChromeDriver	WebDriver HTTP	浏览器 Hand 自动化	start-all.ps1
N/A	Tauri IPC	invoke()	桌面端内部进程通信	内嵌

---

3. 技术栈选型

3.1 桌面端 (Desktop)

层级	技术	选型理由
桌面框架	Tauri 2.x	Rust 原生性能，小体积，安全 IPC
前端框架	React 18 + TypeScript	生态丰富，类型安全
状态管理	Zustand	轻量、灵活、无 boilerplate
样式方案	Tailwind CSS	原子化 CSS，暗色主题友好
数据存储	SQLite (本地)	离线优先，FTS5 全文搜索

3.2 Admin 管理后台

层级	技术	选型理由
框架	Next.js 14 (App Router)	SSR/CSR 灵活切换，API 代理
数据获取	SWR 2.x	缓存+去重+自动重验证，stale-while-revalidate
UI 组件	shadcn/ui	暗色主题原生支持，可定制
图表	Recharts	React 原生集成，轻量

3.3 SaaS 后端

层级	技术	选型理由
Web 框架	Axum	Rust 高性能异步 Web 框架
数据库	PostgreSQL	关系型，复杂查询支持好
ORM	sqlx	编译时 SQL 检查，零开销
认证	JWT + TOTP	无状态鉴权 + 双因素认证
加密	AES-256-GCM	API Key 加密存储

3.4 核心运行时 (Rust Workspace)

zclaw-types        → 基础类型 (AgentId, Message, Error)
zclaw-memory       → 存储层 (SQLite, FTS5, TF-IDF, Embeddings)
zclaw-runtime      → 运行时 (LLM 驱动, 工具, Agent 循环)
zclaw-kernel       → 核心协调 (注册, 调度, 事件, 工作流)
zclaw-skills       → 技能系统 (SKILL.md 解析, WASM 执行器)
zclaw-hands        → 自主能力 (Hand/Trigger 注册管理)
zclaw-protocols    → 协议支持 (MCP, A2A)
zclaw-saas         → SaaS 后端 (独立服务, 8080 端口)

---

4. 数据流向

4.1 Admin 管理后台数据流

用户操作 → React UI → SWR Hook → api-client.ts → Next.js Rewrites → SaaS 后端 (:8080)
                ↑                                                          ↓
                └── SWR Cache ←── JSON Response ←── PostgreSQL (:5432) ←─┘

关键路径:

• Admin 前端所有请求通过 next.config.js rewrites 代理到 localhost:8080
• API 基路径: /api/v1/* (前端) → http://localhost:8080/api/v1/* (后端)
• SWR 缓存: 页面切换后缓存 5s 去重，stale-while-revalidate 模式

4.2 桌面端数据流 (Tauri 模式)

React UI → Zustand Store → invoke() IPC → Rust Tauri Commands → Kernel → LLM/Tools/Skills/Hands
                                                       ↓
                                                  SQLite (~/.zclaw/data.db)

4.3 桌面端数据流 (网关模式)

React UI → gateway-client.ts → WebSocket (:50051) → ZCLAW Gateway → Kernel
                              → REST API (/api/*) →

4.4 桌面端数据流 (SaaS 模式)

React UI → saas-client.ts → HTTPS REST → SaaS 后端 (:8080)
          llm-service.ts  → relay/chat/completions → Provider → LLM API

4.5 LLM 请求路由 (4 条路径)

┌─────────────┐    ┌─ Direct OpenAI ────→ api.openai.com
│             │    ├─ Direct Volcengine ─→ volcengine endpoint
│  llm-service│────┤
│             │    ├─ SaaS Relay ────────→ saas.zclaw.com/relay → Provider
│             │    └─ Gateway ───────────→ invoke('agent_chat') or REST
└─────────────┘

---

5. SaaS 后端 API 接口清单

5.0 通用规范

• Base URL: http://localhost:8080/api/v1
• 认证方式: Authorization: Bearer <JWT_TOKEN> 或 Authorization: Bearer zclaw_<API_KEY>
• Content-Type: application/json
• 分页响应格式: { items: T[], total: number, page: number, page_size: number }
• 错误响应格式: { error: string, message: string }
• HTTP 状态码: 200 OK, 201 Created, 204 No Content, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 500 Internal Error

5.1 公开接口 (无需认证)

#	方法	路径	用途	业务价值
1	GET	/api/health	健康检查	运维监控探针，检测 DB 连通性
2	POST	/api/v1/auth/register	用户注册	自助开户，降低运营成本
3	POST	/api/v1/auth/login	用户登录	身份验证入口，支持 TOTP 2FA
4	POST	/api/v1/auth/refresh	Token 刷新	无感续期，单次使用 refresh_token

POST /api/v1/auth/login

请求:

{
  username: string      // 接受用户名或邮箱
  password: string      // 8-128 字符
  totp_code?: string    // 6 位数字，启用 TOTP 时必填
}

响应:

{
  token: string         // JWT access token
  refresh_token: string // 单次使用 refresh token
  account: AccountPublic
}

5.2 认证自服务接口 (需登录)

#	方法	路径	用途
5	GET	/api/v1/auth/me	获取当前用户信息
6	PUT	/api/v1/auth/password	修改密码
7	POST	/api/v1/auth/totp/setup	生成 TOTP 密钥
8	POST	/api/v1/auth/totp/verify	激活 TOTP 2FA
9	POST	/api/v1/auth/totp/disable	关闭 TOTP 2FA

5.3 账号管理接口 (Admin)

#	方法	路径	用途	权限
10	GET	/api/v1/accounts	账号列表 (支持搜索/筛选/分页)	account:admin
11	GET	/api/v1/accounts/:id	账号详情	account:admin
12	PATCH	/api/v1/accounts/:id	更新账号信息	account:admin
13	PATCH	/api/v1/accounts/:id/status	变更账号状态	account:admin
14	GET	/api/v1/logs/operations	操作日志列表	account:admin
15	GET	/api/v1/stats/dashboard	仪表盘统计聚合	account:admin
16	GET	/api/v1/devices	用户设备列表	认证用户
17	POST	/api/v1/devices/register	注册/更新设备	认证用户
18	POST	/api/v1/devices/heartbeat	设备心跳	认证用户

GET /api/v1/accounts 查询参数:

{
  page?: number          // 页码，默认 1
  page_size?: number     // 每页条数，默认 20
  search?: string        // 搜索用户名/邮箱/显示名
  role?: string          // 按角色筛选: super_admin | admin | user
  status?: string        // 按状态筛选: active | disabled | suspended
}

GET /api/v1/stats/dashboard 响应:

{
  total_accounts: number
  active_accounts: number
  tasks_today: number
  active_providers: number
  active_models: number
  tokens_today_input: number
  tokens_today_output: number
}

5.4 服务商管理接口

#	方法	路径	用途	权限
19	GET	/api/v1/providers	服务商列表	认证用户
20	GET	/api/v1/providers/:id	服务商详情	认证用户
21	POST	/api/v1/providers	创建服务商	provider:manage
22	PATCH	/api/v1/providers/:id	更新服务商	provider:manage
23	DELETE	/api/v1/providers/:id	删除服务商	provider:manage
24	GET	/api/v1/providers/:id/models	服务商下的模型列表	认证用户

Provider 数据结构:

{
  id: string
  name: string               // 唯一标识名，如 "openai"
  display_name: string       // 显示名，如 "OpenAI"
  base_url: string           // API 基地址
  api_protocol: 'openai' | 'anthropic'
  enabled: boolean
  rate_limit_rpm?: number    // 每分钟请求限制
  rate_limit_tpm?: number    // 每分钟 Token 限制
  created_at: string
  updated_at: string
}

5.5 模型管理接口

#	方法	路径	用途	权限
25	GET	/api/v1/models	模型列表	认证用户
26	GET	/api/v1/models/:id	模型详情	认证用户
27	POST	/api/v1/models	创建模型	model:manage
28	PATCH	/api/v1/models/:id	更新模型	model:manage
29	DELETE	/api/v1/models/:id	删除模型	model:manage

Model 数据结构:

{
  id: string
  provider_id: string
  model_id: string           // 如 "gpt-4o"
  alias: string              // 显示别名
  context_window: number     // 上下文窗口大小
  max_output_tokens: number  // 最大输出 Token
  supports_streaming: boolean
  supports_vision: boolean
  enabled: boolean
  pricing_input: number      // $/1M tokens
  pricing_output: number     // $/1M tokens
}

5.6 API Key 管理接口

#	方法	路径	用途	权限
30	GET	/api/v1/keys	当前用户的 API Key 列表	认证用户
31	POST	/api/v1/keys	创建 API Key	认证用户
32	POST	/api/v1/keys/:id/rotate	轮换 API Key	认证用户
33	DELETE	/api/v1/keys/:id	撤销 API Key	认证用户

5.7 Key Pool 管理接口 (Admin)

#	方法	路径	用途	权限
34	GET	/api/v1/providers/:id/keys	服务商 Key Pool 列表	provider:manage
35	POST	/api/v1/providers/:id/keys	添加 Key 到 Pool	provider:manage
36	PUT	/api/v1/providers/:id/keys/:keyId/toggle	启用/禁用 Key	provider:manage
37	DELETE	/api/v1/providers/:id/keys/:keyId	删除 Key	provider:manage

业务价值: Key Pool 实现多 API Key 智能轮转，自动绕过 429 限流，提升整体吞吐量。

5.8 中转代理接口 (Relay)

#	方法	路径	用途	权限
38	POST	/api/v1/relay/chat/completions	LLM 中转请求	relay:use
39	GET	/api/v1/relay/tasks	中转任务列表	认证用户
40	GET	/api/v1/relay/tasks/:id	任务详情	认证用户
41	POST	/api/v1/relay/tasks/:id/retry	重试失败任务	relay:admin
42	GET	/api/v1/relay/models	可用模型列表	认证用户

POST /api/v1/relay/chat/completions — 核心中转接口

请求: OpenAI 兼容格式

{
  model: string
  messages: Array<{ role: string, content: string }>
  temperature?: number
  max_tokens?: number
  stream?: boolean         // 支持 SSE 流式响应
  // ... 其他字段透传给服务商
}

响应:

• 非流式: application/json — 原始服务商响应
• 流式: text/event-stream — SSE 事件流

业务价值: 统一入口代理多家 LLM 服务商，自动 Key Pool 轮转、429 处理、用量计费。

5.9 用量统计接口

#	方法	路径	用途
43	GET	/api/v1/usage	用量统计 (按天/按模型)

查询参数:

{
  from?: string          // ISO 8601 开始日期
  to?: string            // ISO 8601 结束日期
  provider_id?: string   // 按服务商筛选
  model_id?: string      // 按模型筛选
  group_by?: 'day' | 'model'
  days?: number          // 最近 N 天
}

响应:

{
  total_requests: number
  total_input_tokens: number
  total_output_tokens: number
  by_model: Array<{ model_id, count, input_tokens, output_tokens }>
  by_day: Array<{ day, count, input_tokens, output_tokens }>
}

5.10 配置管理接口

#	方法	路径	用途	权限
44	GET	/api/v1/config/items	配置项列表	认证用户
45	GET	/api/v1/config/items/:id	配置项详情	认证用户
46	POST	/api/v1/config/items	创建配置项	config:write
47	PATCH	/api/v1/config/items/:id	更新配置项	config:write
48	DELETE	/api/v1/config/items/:id	删除配置项	config:write
49	GET	/api/v1/config/analysis	配置分析	认证用户
50	POST	/api/v1/config/seed	种子配置	config:write
51	POST	/api/v1/config/sync	双向配置同步	config:write
52	POST	/api/v1/config/diff	配置差异比较	认证用户
53	GET	/api/v1/config/sync-logs	同步日志	认证用户
54	GET	/api/v1/config/pull	批量拉取配置	认证用户

业务价值: 集中管理所有运行参数（服务器、Agent、记忆、LLM、安全策略），支持桌面端双向同步，推送/拉取/合并三种模式。

5.11 角色与权限接口

#	方法	路径	用途	权限
55	GET	/api/v1/roles	角色列表	account:read
56	GET	/api/v1/roles/:id	角色详情	account:read
57	POST	/api/v1/roles	创建角色	account:admin
58	PUT	/api/v1/roles/:id	更新角色	account:admin
59	DELETE	/api/v1/roles/:id	删除角色	account:admin
60	GET	/api/v1/roles/:id/permissions	角色权限列表	account:read
61	GET	/api/v1/permission-templates	权限模板列表	account:read
62	GET	/api/v1/permission-templates/:id	权限模板详情	account:read
63	POST	/api/v1/permission-templates	创建权限模板	account:admin
64	DELETE	/api/v1/permission-templates/:id	删除权限模板	account:admin
65	POST	/api/v1/permission-templates/:id/apply	批量应用权限模板	account:admin

5.12 Prompt 模板管理接口

#	方法	路径	用途	权限
66	GET	/api/v1/prompts	模板列表	prompt:read
67	POST	/api/v1/prompts	创建模板	prompt:write
68	GET	/api/v1/prompts/:name	模板详情	prompt:read
69	PUT	/api/v1/prompts/:name	更新模板元数据	prompt:write
70	DELETE	/api/v1/prompts/:name	归档模板	prompt:admin
71	GET	/api/v1/prompts/:name/versions	版本历史	prompt:read
72	GET	/api/v1/prompts/:name/versions/:v	特定版本	prompt:read
73	POST	/api/v1/prompts/:name/versions	发布新版本	prompt:write
74	POST	/api/v1/prompts/:name/rollback/:v	回滚版本	prompt:admin
75	POST	/api/v1/prompts/check	OTA 更新检查	认证用户

POST /api/v1/prompts/check — OTA 更新检查

请求:

{
  device_id: string
  versions: Record<string, number>  // { "reflection": 3, "compaction": 2 }
}

响应:

{
  updates: Array<{
    name: string
    version: number
    system_prompt: string
    user_prompt_template?: string
    variables: PromptVariable[]
    source: string
    min_app_version?: string
  }>
  server_time: string
}

业务价值: 集中管理 Prompt 模板，桌面端每 30 分钟检查更新，无需发版即可优化提示词。

5.13 Agent 模板管理接口

#	方法	路径	用途	权限
76	GET	/api/v1/agent-templates	Agent 模板列表	model:read
77	POST	/api/v1/agent-templates	创建 Agent 模板	model:manage
78	GET	/api/v1/agent-templates/:id	模板详情	model:read
79	POST	/api/v1/agent-templates/:id	更新模板	model:manage
80	DELETE	/api/v1/agent-templates/:id	归档模板	model:manage

AgentTemplate 数据结构:

{
  id: string
  name: string
  description?: string
  category: string
  source: 'builtin' | 'custom'
  model?: string
  system_prompt?: string
  tools: string[]
  capabilities: string[]
  temperature?: number
  max_tokens?: number
  visibility: 'public' | 'team' | 'private'
  status: 'active' | 'archived'
  current_version: number
}

5.14 遥测接口

#	方法	路径	用途	权限
81	POST	/api/v1/telemetry/report	上报遥测数据	认证用户
82	GET	/api/v1/telemetry/stats	按模型统计	认证用户
83	GET	/api/v1/telemetry/daily	按天统计	认证用户
84	POST	/api/v1/telemetry/audit	上报审计摘要	认证用户

POST /api/v1/telemetry/report 请求:

{
  device_id: string
  app_version: string
  entries: Array<{
    model_id: string
    input_tokens: number
    output_tokens: number
    latency_ms?: number
    success: boolean
    error_type?: string
    timestamp: string
    connection_mode: 'tauri' | 'saas'
  }>  // 最多 500 条/请求
}

业务价值: 桌面端批量上报本地 LLM 用量，管理员可在后台查看所有设备的 Token 消耗、延迟、成功率。

---

6. 桌面端内部通信

6.1 Tauri Commands 清单

桌面端通过 invoke() IPC 暴露以下命令组：

命令组	文件	命令数	用途
进程管理	lib.rs	10	zclaw_start/stop/restart, doctor, health_check
内核操作	kernel_commands.rs	20+	agent_create/chat_stream, skill_execute, hand_execute
工作流	pipeline_commands.rs	9	pipeline_run/progress/cancel, route_intent
持久记忆	memory_commands.rs	12	memory_store/get/search/export
Viking 存储	viking_commands.rs	9	viking_add/find/grep/read
智能钩子	intelligence_hooks.rs	2	pre/post_conversation_hook

6.2 WebSocket 事件类型

方向	事件	说明
Server→Client	text_delta	流式文本片段
Server→Client	phase	阶段切换 (thinking/tool)
Server→Client	tool_call / tool_result	工具调用与结果
Server→Client	hand	Hand 自主能力触发
Server→Client	error	错误通知
Client→Server	message	发送消息
Client→Server	auth_challenge / auth_response	Ed25519 握手
双向	ping / pong	心跳 (30s 间隔)

---

7. 权限体系

7.1 角色定义

角色	权限范围
super_admin	全部权限 (admin:full)
admin	账号管理、服务商/模型管理、中转管理、配置读写、Prompt 读写发布
user	模型读取、中转使用、配置读取、Prompt 读取

7.2 权限清单

权限	说明
admin:full	超级权限，绕过所有检查
account:admin	账号管理 (列表、状态变更、角色分配)
account:read	读取账号、角色、权限模板
provider:manage	创建/更新/删除服务商、管理 Key Pool
model:manage	创建/更新/删除模型、Agent 模板
model:read	读取模型、Agent 模板
relay:use	使用中转 (chat completions)
relay:admin	查看任意中转任务、重试失败任务
config:write	创建/更新/删除配置项、同步、种子
prompt:read	读取 Prompt 模板和版本
prompt:write	创建/更新 Prompt 模板和版本
prompt:admin	归档 Prompt、回滚版本

---

8. 各端交互逻辑

8.1 Admin 管理后台 ↔ SaaS 后端

┌───────────────────────────────────────────────────────────┐
│  Admin 浏览器 (localhost:3000)                             │
│                                                           │
│  ┌──────────┐  SWR Cache  ┌──────────────┐               │
│  │ React UI │◄────────────►│ api-client   │               │
│  │ 11 页面   │             │ JWT 鉴权      │               │
│  └──────────┘             └──────┬───────┘               │
│                                  │ fetch()                │
└──────────────────────────────────┼────────────────────────┘
                                   │
                    Next.js Rewrite│ /api/* → localhost:8080/api/*
                                   │
┌──────────────────────────────────┼────────────────────────┐
│  SaaS Backend (:8080)            │                        │
│                           ┌──────▼───────┐               │
│                           │  Axum Router  │               │
│                           │  中间件栈:     │               │
│                           │  1. Auth      │               │
│                           │  2. RateLimit │               │
│                           │  3. RequestID │               │
│                           │  4. Version   │               │
│                           └──────┬───────┘               │
│                                  │                        │
│                    ┌─────────────▼──────────────┐        │
│                    │  Handlers (72 个端点)       │        │
│                    │  auth/account/model/relay/  │        │
│                    │  config/prompt/telemetry/   │        │
│                    └─────────────┬──────────────┘        │
│                                  │                        │
│                    ┌─────────────▼──────────────┐        │
│                    │  PostgreSQL (:5432)          │        │
│                    └─────────────────────────────┘        │
└───────────────────────────────────────────────────────────┘

8.2 桌面端交互矩阵

场景	通信方式	目标	数据
本地对话	Tauri IPC invoke()	Kernel	消息、Agent、Skills
流式响应	Tauri Event listen()	Kernel	stream:chunk 事件
远程对话	WebSocket :50051	ZCLAW Gateway	消息、事件流
SaaS 登录	HTTPS REST	SaaS :8080	JWT 认证
LLM 中转	HTTPS REST	SaaS :8080/relay	OpenAI 兼容请求
Prompt OTA	HTTPS REST	SaaS :8080/prompts/check	版本号 → 更新
配置同步	HTTPS REST	SaaS :8080/config/sync	双向键值对
遥测上报	HTTPS REST	SaaS :8080/telemetry/report	批量用量数据

---

9. 部署与启动

9.1 完整启动顺序

# start-all.ps1 启动顺序:
1. PostgreSQL    → :5432 (Docker 或本地服务)
2. SaaS Backend  → :8080 (zclaw-saas.exe)
3. ChromeDriver  → :4444 (可选, 用于 Browser Hand)
4. Desktop Dev   → :1420 (Tauri dev)

9.2 SaaS 后端配置

# saas-config.toml
[server]
host = "0.0.0.0"
port = 8080

[database]
url = "postgres://postgres:123123@localhost:5432/zclaw"

[auth]
jwt_expiration_hours = 24
totp_issuer = "ZCLAW SaaS"

[relay]
max_queue_size = 1000
max_concurrent_per_provider = 5
batch_window_ms = 50
retry_delay_ms = 1000
max_attempts = 3

[rate_limit]
requests_per_minute = 60
burst = 10

---

10. 接口设计背景与业务价值

10.1 中转代理 (Relay) — 核心收入引擎

背景: 多家 LLM 服务商 API 各不相同，用户需统一入口。

设计价值:

• OpenAI 兼容接口降低接入成本
• Key Pool 智能轮转绕过限流
• 自动 429 处理 + 冷却恢复
• 按账号精确计费 (input/output tokens)

10.2 Prompt OTA — 无感更新

背景: Prompt 工程需要频繁迭代，但桌面端发版周期长。

设计价值:

• 集中管理 reflection/compaction/extraction 等核心 Prompt
• 桌面端每 30 分钟自动检查更新
• 版本化 + 回滚能力
• min_app_version 兼容性控制

10.3 配置同步 — 多设备一致

背景: 用户多台设备需保持配置一致。

设计价值:

• push/pull/merge 三种同步模式
• 乐观锁 (client_timestamps) 冲突检测
• 只读 diff 不修改数据
• 同步日志可追溯

10.4 Key Pool — 高可用保障

背景: 单个 API Key 容易触发限流 (429)。

设计价值:

• 多 Key 按优先级智能选择
• 429 自动冷却 + 切换
• RPM/TPM 限额独立配置
• 配额重置周期支持

10.5 遥测上报 — 数据驱动优化

背景: 桌面端本地 LLM 用量无法直接观测。

设计价值:

• 批量上报 (500 条/次) 减少请求
• 按模型聚合: Token 消耗、延迟、成功率
• 按天聚合: 请求量、设备活跃度
• 审计摘要: 操作类型 + 结果

---

文档统计: 84 个 API 端点 | 5 个通信通道 | 12 种权限 | 4 个独立服务