---
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)