chore: initialize qiming workspace repository

qimingclaw/crates/agent-electron-client/docs/v2/01-ARCHITECTURE.md

@@ -0,0 +1,954 @@
+---
+version: 2.0
+last-updated: 2026-03-09
+status: design
+---
+
+# 01 — 总体架构
+
+## 一、产品定位
+
+**启明智能体 OS (Qiming Agent OS)** 是全球首个开源通用智能体操作系统，支持用户完整私有化部署。
+用户部署后即拥有一个完整的 Agent 服务（如 `https://testagent.xspaceagi.com`），
+具备 Agent 配置、模型管理、技能管理、MCP、知识库、工作流、插件、会话等全套能力。
+
+**QimingClaw（Electron 客户端）** 是 Qiming Agent OS 的**桌面增强体**：
+
+- 运行在**用户电脑**或**云电脑**上（如云桌面、远程 VM）
+- **侧重使用和便捷配置**——不是复制服务器全部功能，而是提供一体化的 Agent 使用体验
+- 提供本地代码执行、引擎管理、IM Channel 网关等服务器不具备的桌面级能力
+- 与 Qiming Agent OS 服务深度同步，是 Agent 服务在终端计算节点的延伸
+- 未来支持**手机端操控**——通过服务器 Web API 实现跨设备管理
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│  Qiming Agent OS（用户私有部署）                                        │
+│  https://testagent.xspaceagi.com                                     │
+│                                                                      │
+│  • Agent 配置 & 组件管理       • 模型管理                              │
+│  • 技能管理 & MCP 管理          • 会话 & 消息                          │
+│  • 知识库 (RAG) & 工作流        • 插件管理                             │
+│  • 沙箱环境 & 计算资源          • 用户权限 & 审计                      │
+│                                                                      │
+│            ↕  API 同步 (/api/model/*, /api/skill/*, ...)             │
+│                                                                      │
+│  ┌────────────────────────────────────────────────────────────────┐  │
+│  │  QimingClaw Client — 桌面增强体（用户电脑 / 云电脑）              │  │
+│  │                                                                │  │
+│  │  • 引擎管理 (ACP 子进程)      • 本地代码执行                    │  │
+│  │  • MCP Server 本地运行        • IM Channel 网关                │  │
+│  │  • 离线缓存 & 离线使用         • Agent 自我进化 (本地记忆)       │  │
+│  │  • 系统级权限 (文件/网络)      • 与服务器双向同步               │  │
+│  │  • 知识库/工作流/插件便捷配置  • 一体化使用 + 手机可操控         │  │
+│  └────────────────────────────────────────────────────────────────┘  │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 二、分层架构
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                        UI 层 (Renderer Process)                          │
+│  React + Ant Design · 会话界面 · 设置面板 · 技能市场 · Agent 仪表盘       │
+└──────────────────────────────────────────────────────────────────────────┘
+                                     ↕ IPC
+┌──────────────────────────────────────────────────────────────────────────┐
+│                     服务网关层 (Main Process)                              │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
+│  │ ModelGateway │  │ ChatEngine   │  │ ToolEngine   │  │ ChannelGW    │ │
+│  │ 多模型路由    │  │ 会话引擎      │  │ Skill+MCP    │  │ IM 网关      │ │
+│  │              │  │              │  │ +Plugin+WF   │  │              │ │
+│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘ │
+│         │                 │                 │                 │         │
+│  ┌──────▼─────────────────▼─────────────────▼─────────────────▼───────┐ │
+│  │                  ServiceOrchestrator (编排层)                        │ │
+│  │   统一生命周期管理 · 依赖注入 · 健康检查 · 可观测性                     │ │
+│  └────────────────────────────────────────────────────────────────────┘ │
+│                                     ↕                                   │
+│  ┌──────────────────────┐  ┌──────────────────────────────────────────┐ │
+│  │  Qiming Sync Layer    │  │  本地存储层 (Persistence)                  │ │
+│  │  QimingApiClient      │  │  SQLite · Markdown · KeyStore            │ │
+│  │  + 各领域 Adapter    │  │                                          │ │
+│  └──────────────────────┘  └──────────────────────────────────────────┘ │
+└──────────────────────────────────────────────────────────────────────────┘
+                                     ↕ HTTP/WS
+┌──────────────────────────────────────────────────────────────────────────┐
+│                     Agent 引擎层 (子进程 / ACP)                           │
+│  claude-code · qimingcode · 本地 LLM                                      │
+└──────────────────────────────────────────────────────────────────────────┘
+                                     ↕ HTTP
+┌──────────────────────────────────────────────────────────────────────────┐
+│                  Qiming Agent OS (用户私有部署服务)                         │
+│  https://testagent.xspaceagi.com                                         │
+│  /api/model/* · /api/skill/* · /api/mcp/* · /api/agent/* ·               │
+│  /api/knowledge/* · /api/workflow/* · /api/plugin/* · ...                 │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 三、核心组件
+
+### 3.1 QimingApiClient（API 客户端）
+
+所有 Sync Adapter 的底层 HTTP 客户端，负责认证、请求/响应处理和错误重试：
+
+```typescript
+class QimingApiClient {
+  private baseUrl: string;
+  private authToken: string;
+  private spaceId: number;
+
+  constructor(config: {
+    baseUrl: string; // https://testagent.xspaceagi.com
+    spaceId: number;
+  }) {}
+
+  /** 认证登录，获取 token */
+  async authenticate(credentials: {
+    username: string;
+    password: string;
+  }): Promise<void>;
+
+  /** 使用 API Token 认证 */
+  async authenticateWithToken(token: string): Promise<void>;
+
+  /** 通用请求方法，自动携带 auth 头 + 错误重试 */
+  async request<T>(
+    method: "GET" | "POST",
+    path: string,
+    data?: unknown,
+    options?: {
+      retries?: number;
+      timeout?: number;
+    },
+  ): Promise<T>;
+
+  /** 上传文件 */
+  async upload(path: string, file: Buffer, filename: string): Promise<unknown>;
+
+  /** 建立 SSE 连接 */
+  createSSE(path: string): EventSource;
+
+  /** 连接状态 */
+  isConnected(): boolean;
+
+  /** Token 过期自动刷新 */
+  private refreshTokenIfNeeded(): Promise<void>;
+}
+```
+
+### 3.2 QimingSyncService（同步层）
+
+与用户部署的 Qiming Agent OS 服务进行双向同步的协调服务：
+
+```typescript
+interface QimingSyncService {
+  /** 配置服务端点 */
+  configure(endpoint: {
+    baseUrl: string; // https://testagent.xspaceagi.com
+    authToken?: string;
+    spaceId: number;
+  }): void;
+
+  /** 同步模型配置（从服务器拉 + 本地推） */
+  syncModels(): Promise<SyncResult>;
+
+  /** 同步技能/MCP 配置 */
+  syncSkillsAndMcp(): Promise<SyncResult>;
+
+  /** 同步知识库配置 */
+  syncKnowledge(): Promise<SyncResult>;
+
+  /** 同步工作流定义 */
+  syncWorkflows(): Promise<SyncResult>;
+
+  /** 同步插件配置 */
+  syncPlugins(): Promise<SyncResult>;
+
+  /** 同步会话和消息 */
+  syncConversations(): Promise<SyncResult>;
+
+  /** 同步 Agent 完整配置（含所有组件） */
+  syncAgentConfig(agentId: number): Promise<AgentConfigInfo>;
+
+  /** 测试连接 */
+  testConnection(): Promise<{
+    success: boolean;
+    version?: string;
+    error?: string;
+  }>;
+
+  /** 获取同步状态 */
+  getSyncStatus(): SyncStatus;
+
+  /** 设置自动同步 */
+  setAutoSync(enabled: boolean, intervalMs?: number): void;
+}
+
+interface SyncResult {
+  success: boolean;
+  pulled: number;
+  pushed: number;
+  conflicts: SyncConflict[];
+  errors?: string[];
+}
+
+interface SyncConflict {
+  type:
+    | "model"
+    | "skill"
+    | "mcp"
+    | "conversation"
+    | "knowledge"
+    | "workflow"
+    | "plugin";
+  localItem: unknown;
+  serverItem: unknown;
+  resolution?: "use-server" | "use-local" | "merge";
+}
+
+interface SyncStatus {
+  lastSyncAt: number;
+  connected: boolean;
+  pendingChanges: number;
+  syncInProgress: boolean;
+  /** 分模块同步时间 */
+  moduleSyncStatus: Record<
+    string,
+    { lastSyncAt: number; status: "ok" | "error" | "pending" }
+  >;
+}
+```
+
+### 3.3 ServiceOrchestrator（编排层）
+
+替代当前 `processManager.ts` + `startup.ts` 的分散管理，提供统一的服务生命周期：
+
+```typescript
+interface ServiceOrchestrator {
+  /** 注册服务（声明依赖关系） */
+  register(service: ServiceDescriptor): void;
+
+  /** 按拓扑序启动所有服务 */
+  startAll(): Promise<ServiceStartResult>;
+
+  /** 优雅停机（逆序） */
+  stopAll(): Promise<void>;
+
+  /** 健康检查 */
+  healthCheck(): Promise<Record<string, HealthStatus>>;
+
+  /** 获取服务实例 */
+  getService<T>(name: string): T;
+}
+```
+
+### 3.4 核心组件一览
+
+| 组件           | 描述                                            | 详细文档                                                                                |
+| -------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------- |
+| ModelGateway   | 多 Provider 管理，与服务器 `/api/model/*` 同步  | [02-MODEL-CONFIG.md](./02-MODEL-CONFIG.md)                                              |
+| ChatEngine     | 会话引擎，与服务器 `/api/conversation/*` 同步   | [04-SESSION-CHAT.md](./04-SESSION-CHAT.md)                                              |
+| ToolEngine     | 技能 + MCP + Plugin + Workflow 统一工具管理     | [03-SKILLS-MCP.md](./03-SKILLS-MCP.md) / [07-KWP.md](./07-KNOWLEDGE-WORKFLOW-PLUGIN.md) |
+| ChannelGateway | 多 IM 平台接入，可路由到服务器 Agent 或本地引擎 | [05-CHANNELS.md](./05-CHANNELS.md)                                                      |
+| KnowledgeSync  | 知识库/工作流/插件同步与本地 RAG                | [07-KWP.md](./07-KNOWLEDGE-WORKFLOW-PLUGIN.md)                                          |
+
+---
+
+## 四、客户端与服务器的职责划分
+
+| 能力         | 服务器 (Qiming Agent OS)    | 客户端 (QimingClaw · 用户电脑/云电脑) |
+| ------------ | -------------------------- | ----------------------------------- |
+| Agent 配置   | ✅ 权威来源                | 🔧 便捷配置入口 + 拉取同步          |
+| 模型管理     | ✅ CRUD + 连通性测试       | 🔧 便捷配置 + 本地 Provider 扩展    |
+| 技能管理     | ✅ CRUD + 发布 + 广场      | 🔄 同步 + Agent 自学技能推送        |
+| MCP 管理     | ✅ 配置存储 + 服务端运行   | 🔧 便捷配置 + 本地 MCP Server 运行  |
+| 知识库 (RAG) | ✅ 文档管理 + 分段 + 嵌入  | 🔗 配置入口 + 委托服务器执行 RAG    |
+| 工作流       | ✅ 节点编排引擎 + 试运行   | 🔗 配置入口 + 委托服务器执行        |
+| 插件管理     | ✅ HTTP/Code 插件 + 试运行 | 🔗 配置入口 + 委托服务器执行        |
+| 会话管理     | ✅ 服务端会话              | 🔄 双向同步 + 本地引擎会话          |
+| 沙箱/计算    | ✅ 云端沙箱                | ✅ 本地引擎 (ACP 子进程)            |
+| IM Channel   | ❌                         | ✅ 本地 Channel 网关                |
+| 自我进化     | ❌                         | ✅ Memory / EvoMap / Soul           |
+| 离线使用     | ❌                         | ✅ 离线缓存可用                     |
+| 手机操控     | ✅ Web API                 | 🔗 通过服务器 API 实现手机远程管理  |
+| 系统权限     | ❌ (沙箱限制)              | ✅ 文件系统/进程/网络               |
+
+---
+
+## 五、与 V1 的向后兼容
+
+### 保留不变
+
+| 组件                 | 说明                                     |
+| -------------------- | ---------------------------------------- |
+| 三区隔离模型         | App Core / Agent Workspace / User System |
+| ACP 协议栈           | 作为 Agent 引擎层的核心协议              |
+| Computer HTTP Server | 保留 `/computer/*` API 兼容              |
+| 依赖管理             | Node / uv / 引擎安装逻辑不变             |
+
+### 重构 / 新增
+
+| 组件                         | V1 → V2 变化                              |
+| ---------------------------- | ----------------------------------------- |
+| `processManager.ts`          | → `ServiceOrchestrator` 统一编排          |
+| `computerServer.ts` 内嵌路由 | → 独立 `RouterService` 可插拔             |
+| `EngineManager` 双引擎       | → `ModelGateway` 多 Provider + 服务器同步 |
+| MCP Proxy (外部进程)         | → MCP 原生集成 + 服务器 MCP 配置同步      |
+| 独立会话管理                 | → `ChatEngine` + 服务器会话同步           |
+| `IMService` (renderer侧)     | → `ChannelGateway` (main进程 + Worker)    |
+| 无同步层                     | → `QimingSyncService` 双向同步             |
+| 无知识库/工作流/插件         | → 与服务器 Knowledge/Workflow/Plugin 同步 |
+
+---
+
+## 六、服务依赖与启动顺序
+
+### 6.1 服务依赖图
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         服务依赖关系图                                   │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                         │
+│  QimingApiClient ──────────────────────────────────────────────────────  │
+│       │                                                                 │
+│       ├──────────► McpManager ──────────────────────────────────────    │
+│       │                │                                                │
+│       │                └──────────► McpWarmupService                   │
+│       │                                                                 │
+│       ├──────────► SkillManager                                         │
+│       │                                                                 │
+│       ├──────────► ModelGateway                                         │
+│       │                                                                 │
+│       └──────────► QimingSyncService                                     │
+│                            │                                            │
+│                            └──────────► 各领域 SyncAdapter              │
+│                                                                         │
+│  McpManager + SkillManager                                              │
+│       │                                                                 │
+│       └──────────► ToolRegistry ────────────────────────────────────    │
+│                                                                         │
+│  ModelGateway + ToolRegistry                                            │
+│       │                                                                 │
+│       └──────────► ChatEngine                                           │
+│                                                                         │
+│  ChatEngine                                                             │
+│       │                                                                 │
+│       └──────────► ChannelGateway                                       │
+│                                                                         │
+│  QimingApiClient + CronScheduler                                         │
+│       │                                                                 │
+│       └──────────► HeartbeatEngine                                      │
+│                                                                         │
+│  CronScheduler ─────────────────────────────────────────────────────    │
+│       │                                                                 │
+│       └──────────► CronSyncAdapter                                      │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### 6.2 启动顺序
+
+```typescript
+/**
+ * 服务启动顺序（按依赖拓扑排序）
+ * 
+ * 阶段 1: 基础设施
+ * 阶段 2: 数据同步（可并行）
+ * 阶段 3: 工具注册
+ * 阶段 4: 会话引擎
+ * 阶段 5: 渠道接入
+ * 阶段 6: 后台任务
+ */
+const SERVICE_START_ORDER = {
+  // 阶段 1: 基础设施（串行）
+  phase1: [
+    { name: "QimingApiClient", timeout: 10000 },
+    { name: "QimingSyncService", timeout: 5000 },
+  ],
+
+  // 阶段 2: 数据同步（可并行）
+  phase2: [
+    { name: "McpManager", timeout: 30000, parallel: true },
+    { name: "SkillManager", timeout: 10000, parallel: true },
+    { name: "ModelGateway", timeout: 10000, parallel: true },
+  ],
+
+  // 阶段 3: MCP 预热（后台）
+  phase2_5: [
+    { name: "McpWarmupService", timeout: 60000, background: true },
+  ],
+
+  // 阶段 3: 工具注册
+  phase3: [
+    { name: "ToolRegistry", timeout: 5000 },
+  ],
+
+  // 阶段 4: 会话引擎
+  phase4: [
+    { name: "ChatEngine", timeout: 10000 },
+  ],
+
+  // 阶段 5: 渠道接入
+  phase5: [
+    { name: "ChannelGateway", timeout: 5000 },
+  ],
+
+  // 阶段 6: 后台任务
+  phase6: [
+    { name: "HeartbeatEngine", timeout: 5000 },
+    { name: "CronScheduler", timeout: 5000 },
+  ],
+};
+```
+
+### 6.3 ServiceOrchestrator 实现
+
+```typescript
+/**
+ * 服务编排器
+ * 
+ * 职责：
+ * - 按依赖拓扑启动服务
+ * - 处理启动失败（部分回滚）
+ * - 健康检查
+ * - 优雅停机
+ */
+class ServiceOrchestrator {
+  private services: Map<string, ServiceDescriptor> = new Map();
+  private instances: Map<string, any> = new Map();
+  private startedServices: string[] = [];
+
+  /**
+   * 注册服务
+   */
+  register(descriptor: ServiceDescriptor): void {
+    this.services.set(descriptor.name, descriptor);
+  }
+
+  /**
+   * 按阶段启动所有服务
+   */
+  async startAll(): Promise<ServiceStartResult> {
+    const errors: ServiceError[] = [];
+
+    for (const [phaseName, services] of Object.entries(SERVICE_START_ORDER)) {
+      console.log(`[Orchestrator] Starting ${phaseName}...`);
+
+      // 并行启动该阶段服务
+      const parallelServices = services.filter((s) => s.parallel);
+      const serialServices = services.filter((s) => !s.parallel && !s.background);
+      const backgroundServices = services.filter((s) => s.background);
+
+      // 串行服务
+      for (const service of serialServices) {
+        try {
+          await this.startService(service.name, service.timeout);
+          this.startedServices.push(service.name);
+        } catch (error) {
+          errors.push({ name: service.name, error: String(error) });
+          // 关键服务失败，停止启动
+          if (!service.optional) {
+            await this.rollback();
+            return { success: false, errors };
+          }
+        }
+      }
+
+      // 并行服务
+      if (parallelServices.length > 0) {
+        const results = await Promise.allSettled(
+          parallelServices.map((s) => 
+            this.startService(s.name, s.timeout)
+          ),
+        );
+        
+        for (let i = 0; i < results.length; i++) {
+          const result = results[i];
+          const service = parallelServices[i];
+          
+          if (result.status === "fulfilled") {
+            this.startedServices.push(service.name);
+          } else {
+            errors.push({ name: service.name, error: String(result.reason) });
+          }
+        }
+      }
+
+      // 后台服务（不等待）
+      for (const service of backgroundServices) {
+        this.startService(service.name, service.timeout).catch((error) => {
+          console.warn(`[Orchestrator] Background service ${service.name} failed:`, error);
+        });
+      }
+    }
+
+    return {
+      success: errors.length === 0,
+      startedServices: this.startedServices,
+      errors: errors.length > 0 ? errors : undefined,
+    };
+  }
+
+  /**
+   * 优雅停机（逆序）
+   */
+  async stopAll(): Promise<void> {
+    const reversed = [...this.startedServices].reverse();
+    
+    for (const name of reversed) {
+      try {
+        const instance = this.instances.get(name);
+        if (instance?.stop) {
+          await instance.stop();
+        }
+        console.log(`[Orchestrator] Stopped ${name}`);
+      } catch (error) {
+        console.error(`[Orchestrator] Failed to stop ${name}:`, error);
+      }
+    }
+    
+    this.startedServices = [];
+    this.instances.clear();
+  }
+
+  /**
+   * 回滚已启动的服务
+   */
+  private async rollback(): Promise<void> {
+    console.log("[Orchestrator] Rolling back...");
+    await this.stopAll();
+  }
+
+  /**
+   * 启动单个服务
+   */
+  private async startService(name: string, timeout: number): Promise<void> {
+    const descriptor = this.services.get(name);
+    if (!descriptor) {
+      throw new Error(`Service ${name} not registered`);
+    }
+
+    // 检查依赖
+    for (const dep of descriptor.dependencies || []) {
+      if (!this.startedServices.includes(dep)) {
+        throw new Error(`Dependency ${dep} not started`);
+      }
+    }
+
+    // 创建实例
+    const instance = await descriptor.factory(this.getDependencies(descriptor));
+    
+    // 启动（带超时）
+    if (instance.start) {
+      await Promise.race([
+        instance.start(),
+        new Promise((_, reject) => 
+          setTimeout(() => reject(new Error("Timeout")), timeout),
+        ),
+      ]);
+    }
+
+    this.instances.set(name, instance);
+    console.log(`[Orchestrator] Started ${name}`);
+  }
+
+  /**
+   * 获取依赖实例
+   */
+  private getDependencies(descriptor: ServiceDescriptor): Record<string, any> {
+    const deps: Record<string, any> = {};
+    for (const dep of descriptor.dependencies || []) {
+      deps[dep] = this.instances.get(dep);
+    }
+    return deps;
+  }
+
+  /**
+   * 获取服务实例
+   */
+  getService<T>(name: string): T {
+    return this.instances.get(name) as T;
+  }
+
+  /**
+   * 健康检查
+   */
+  async healthCheck(): Promise<Record<string, HealthStatus>> {
+    const results: Record<string, HealthStatus> = {};
+
+    for (const [name, instance] of this.instances) {
+      try {
+        if (instance.healthCheck) {
+          results[name] = await instance.healthCheck();
+        } else {
+          results[name] = { status: "unknown" };
+        }
+      } catch (error) {
+        results[name] = { status: "error", error: String(error) };
+      }
+    }
+
+    return results;
+  }
+}
+
+// ==================== 类型定义 ====================
+
+interface ServiceDescriptor {
+  name: string;
+  dependencies?: string[];
+  optional?: boolean;
+  factory: (deps: Record<string, any>) => Promise<any>;
+}
+
+interface ServiceStartResult {
+  success: boolean;
+  startedServices?: string[];
+  errors?: ServiceError[];
+}
+
+interface ServiceError {
+  name: string;
+  error: string;
+}
+
+interface HealthStatus {
+  status: "ok" | "error" | "unknown" | "degraded";
+  error?: string;
+  details?: Record<string, any>;
+}
+```
+
+---
+
+## 七、错误处理与重试机制
+
+### 7.1 分层错误处理
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         错误处理分层架构                                 │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                         │
+│  Layer 1: UI 层                                                         │
+│  ├── 错误提示（Toast / Modal）                                          │
+│  └── 用户重试按钮                                                       │
+│                                                                         │
+│  Layer 2: IPC 层                                                        │
+│  ├── 错误序列化（Error → IPC 错误对象）                                  │
+│  └── 错误分类（网络错误 / 业务错误 / 系统错误）                           │
+│                                                                         │
+│  Layer 3: Service 层                                                    │
+│  ├── 重试机制（指数退避）                                                │
+│  ├── 降级策略（fallback）                                               │
+│  └── 错误上报（日志 / 监控）                                            │
+│                                                                         │
+│  Layer 4: API 层                                                        │
+│  ├── 请求重试（网络错误）                                                │
+│  ├── Token 刷新（认证错误）                                             │
+│  └── 超时控制                                                           │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### 7.2 重试策略
+
+```typescript
+/**
+ * 统一重试策略
+ */
+interface RetryPolicy {
+  maxRetries: number;
+  initialDelayMs: number;
+  maxDelayMs: number;
+  backoffMultiplier: number;
+  retryableErrors: string[];  // 可重试的错误类型
+  onRetry?: (attempt: number, error: Error) => void;
+}
+
+const DEFAULT_RETRY_POLICY: RetryPolicy = {
+  maxRetries: 3,
+  initialDelayMs: 1000,
+  maxDelayMs: 30000,
+  backoffMultiplier: 2,
+  retryableErrors: [
+    "ECONNRESET",
+    "ETIMEDOUT",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "503",
+    "502",
+    "504",
+  ],
+};
+
+/**
+ * 带重试的执行器
+ */
+async function withRetry<T>(
+  fn: () => Promise<T>,
+  policy: RetryPolicy = DEFAULT_RETRY_POLICY,
+): Promise<T> {
+  let lastError: Error | null = null;
+  let delay = policy.initialDelayMs;
+
+  for (let attempt = 0; attempt <= policy.maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error: any) {
+      lastError = error;
+
+      // 检查是否可重试
+      const isRetryable = policy.retryableErrors.some(
+        (e) => error.code === e || error.message?.includes(e),
+      );
+
+      if (!isRetryable || attempt === policy.maxRetries) {
+        throw error;
+      }
+
+      policy.onRetry?.(attempt + 1, error);
+
+      // 指数退避
+      await sleep(delay);
+      delay = Math.min(delay * policy.backoffMultiplier, policy.maxDelayMs);
+    }
+  }
+
+  throw lastError;
+}
+```
+
+### 7.3 降级策略
+
+```typescript
+/**
+ * 降级策略配置
+ */
+interface FallbackStrategy {
+  // 服务器不可用时
+  onServerUnavailable: "cache" | "offline" | "error";
+
+  // 模型不可用时
+  onModelUnavailable: "fallback-model" | "error";
+
+  // MCP 启动失败时
+  onMcpFailed: "continue-without" | "block";
+
+  // Channel 连接失败时
+  onChannelFailed: "skip-channel" | "error";
+}
+
+const DEFAULT_FALLBACK: FallbackStrategy = {
+  onServerUnavailable: "cache",       // 使用本地缓存
+  onModelUnavailable: "fallback-model", // 使用备用模型
+  onMcpFailed: "continue-without",    // 跳过失败的 MCP，继续运行
+  onChannelFailed: "skip-channel",    // 跳过失败的 Channel
+};
+```
+
+---
+
+## 八、安全性设计
+
+### 8.1 凭据加密存储
+
+```typescript
+/**
+ * 凭据加密配置
+ */
+interface CredentialEncryption {
+  // 加密算法
+  algorithm: "aes-256-gcm";
+
+  // 密钥派生
+  keyDerivation: {
+    method: "pbkdf2" | "argon2";
+    iterations: number;
+    saltLength: number;
+  };
+
+  // 存储
+  storage: {
+    location: "keytar" | "encrypted-file" | "os-keychain";
+    fallbackToMemory: boolean;  // keytar 不可用时是否降级到内存
+  };
+}
+
+const DEFAULT_ENCRYPTION: CredentialEncryption = {
+  algorithm: "aes-256-gcm",
+  keyDerivation: {
+    method: "pbkdf2",
+    iterations: 100000,
+    saltLength: 32,
+  },
+  storage: {
+    location: "keytar",
+    fallbackToMemory: true,
+  },
+};
+```
+
+### 8.2 MCP 沙箱
+
+```typescript
+/**
+ * MCP 执行沙箱配置
+ */
+interface McpSandboxConfig {
+  enabled: boolean;
+
+  // 文件系统限制
+  filesystem: {
+    allowedPaths: string[];      // 允许访问的路径
+    deniedPaths: string[];       // 禁止访问的路径
+    readOnlyPaths: string[];     // 只读路径
+  };
+
+  // 命令限制
+  commands: {
+    deniedPatterns: RegExp[];    // 禁止的命令模式
+    allowedBinaries: string[];   // 允许的可执行文件
+  };
+
+  // 网络限制
+  network: {
+    enabled: boolean;
+    whitelist: string[];         // 允许的域名/IP
+    blacklist: string[];         // 禁止的域名/IP
+  };
+
+  // 资源限制
+  resources: {
+    maxMemoryMB: number;
+    maxCpuPercent: number;
+    timeout: number;
+  };
+}
+
+const DEFAULT_SANDBOX: McpSandboxConfig = {
+  enabled: true,
+  filesystem: {
+    allowedPaths: ["~/.qimingclaw/workspace"],
+    deniedPaths: ["~/.ssh", "~/.gnupg", "~/.qimingclaw/config"],
+    readOnlyPaths: [],
+  },
+  commands: {
+    deniedPatterns: [/rm\s+-rf/, /sudo/, /chmod/],
+    allowedBinaries: ["node", "npx", "uv", "uvx", "python3", "git"],
+  },
+  network: {
+    enabled: true,
+    whitelist: [],
+    blacklist: [],
+  },
+  resources: {
+    maxMemoryMB: 512,
+    maxCpuPercent: 50,
+    timeout: 30000,
+  },
+};
+```
+
+### 8.3 传输安全
+
+```typescript
+/**
+ * 传输安全配置
+ */
+interface TransportSecurity {
+  // HTTPS 强制
+  enforceHttps: boolean;
+
+  // 证书锁定（可选）
+  certificatePinning?: {
+    enabled: boolean;
+    publicKeys: string[];  // 服务器公钥指纹
+  };
+
+  // 请求签名
+  requestSigning?: {
+    enabled: boolean;
+    algorithm: "hmac-sha256";
+  };
+
+  // Token 管理
+  tokenManagement: {
+    autoRefresh: boolean;
+    refreshThresholdMs: number;  // 提前刷新阈值
+    secureStorage: boolean;
+  };
+}
+
+const DEFAULT_TRANSPORT_SECURITY: TransportSecurity = {
+  enforceHttps: true,
+  tokenManagement: {
+    autoRefresh: true,
+    refreshThresholdMs: 5 * 60 * 1000,  // 5 分钟前刷新
+    secureStorage: true,
+  },
+};
+```
+
+---
+
+## 九、数据目录结构 V2
+
+```
+~/.qimingclaw/
+├── config/
+│   ├── server.json             # Qiming 服务端点配置（URL + Auth）
+│   ├── providers.json          # 本地 Provider 配置（加密凭据）
+│   ├── channels.json           # Channel 配置
+│   └── settings.json           # 通用设置
+│
+├── data/
+│   ├── qimingclaw.db             # SQLite 主数据库
+│   │   ├── sessions 表         # 会话（本地缓存 + 服务器同步）
+│   │   ├── messages 表         # 消息
+│   │   ├── skills 表           # 技能注册（与服务器同步）
+│   │   ├── mcp_servers 表      # MCP 配置
+│   │   ├── knowledge_cache 表  # 知识库文档本地缓存
+│   │   └── sync_queue 表       # 待同步队列
+│   └── memory.db               # 向量数据库（sqlite-vec）
+│
+├── soul/                       # Agent 灵魂（Markdown）
+├── memory/                     # 记忆（Markdown + 索引）
+├── skills/                     # 技能文件
+├── evo-map/                    # 进化图谱
+│
+└── mcp-servers/                # 本地 MCP 服务器工作目录
+```
+
+---
+
+## 十、实施路线
+
+```
+Phase 1 (P0)  ─ 服务器连接 + 模型配置同步
+                 → QimingApiClient + QimingSyncService + ModelGateway 双向同步
+Phase 2 (P0)  ─ Skills & MCP & Plugin & Workflow 同步
+                 → ToolRegistry + 服务器技能/MCP/插件/工作流 同步
+Phase 2.5(P0) ─ Knowledge/RAG 同步
+                 → KnowledgeSyncAdapter + 本地 RAG 查询缓存
+Phase 3 (P0)  ─ 会话管理同步
+                 → ChatEngine + 服务器会话双向同步
+Phase 4 (P1)  ─ Channel 多渠道接入
+                 → IM 消息路由到服务器 Agent 或本地引擎
+Phase 5 (P1)  ─ Agent 自我进化落地
+                 → Memory/EvoMap/Soul 实际运行
+```
+
+---
+
+## 相关文档
+
+- [Qiming 产品官网](https://qiming.com/) — 启明智能体 OS 产品介绍
+- [V1 架构总览](../architecture/OVERVIEW.md)
+- [V1 隔离策略](../architecture/ISOLATION.md)
+- [V1 核心组件](../architecture/COMPONENTS.md)