远程控制系统设计文档

模块概述

版本: v0.33.0 状态: 100% 完成 最后更新: 2026-02-11

远程控制系统提供从 Android 设备通过 P2P 网络远程控制桌面端的完整能力。系统采用 DID 身份验证、权限分级控制、端到端加密通信，支持 23 种命令类型和浏览器扩展自动化。

核心特性

P2P 远程连接: 基于 WebRTC 的点对点加密通信
DID 身份验证: 去中心化身份认证，无需中心服务器
权限分级控制: 5 级权限模型 (NONE → FULL)
23 个命令处理器: 覆盖系统控制、文件传输、浏览器自动化等
浏览器扩展: Chrome/Firefox 扩展实现深度网页自动化
审计日志: 完整的操作记录和审计追踪

1. 系统架构

1.1 整体架构图

┌──────────────────────────────────────────────────────────────────┐
│                        Android 远程控制端                          │
├──────────────────────────────────────────────────────────────────┤
│  RemoteControlScreen │ ProcessManager │ PowerControl │ ...       │
│         ↓                   ↓               ↓                    │
│  RemoteCommandClient ─── P2P WebRTC ─── DID 签名认证              │
└──────────────────────────────────────────────────────────────────┘
                              ↕ P2P 加密通道
┌──────────────────────────────────────────────────────────────────┐
│                        PC 远程网关层                               │
├──────────────────────────────────────────────────────────────────┤
│                      RemoteGateway                                │
│     ┌─────────────────────────────────────────────────────┐      │
│     │  P2PCommandAdapter  │  PermissionGate  │  CommandRouter    │
│     └─────────────────────────────────────────────────────┘      │
│                              ↓                                    │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │                    23 Command Handlers                      │  │
│  ├────────────────────────────────────────────────────────────┤  │
│  │ AI      │ System   │ File     │ Desktop  │ Knowledge       │  │
│  │ History │ Device   │ Clipboard│ Notify   │ Workflow        │  │
│  │ Browser │ Power    │ Process  │ Media    │ Network         │  │
│  │ Storage │ Display  │ Input    │ App      │ SysInfo         │  │
│  │ Security│ UserBrowser │ Extension                          │  │
│  └────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘
                              ↕
┌──────────────────────────────────────────────────────────────────┐
│                      浏览器扩展层                                  │
├──────────────────────────────────────────────────────────────────┤
│  BrowserExtensionServer ←→ Native Host ←→ Chrome/Firefox 扩展    │
└──────────────────────────────────────────────────────────────────┘

1.2 核心组件

组件	文件	行数	说明
RemoteGateway	`remote-gateway.js`	~740	统一的远程命令处理入口
P2PCommandAdapter	`p2p-command-adapter.js`	~500	P2P 命令适配器
PermissionGate	`permission-gate.js`	~600	权限验证和审计
CommandRouter	`command-router.js`	~300	命令路由和分发
BrowserExtensionServer	`browser-extension-server.js`	~400	浏览器扩展通信服务器

2. 权限系统

2.1 权限等级

javascript

const PERMISSION_LEVELS = {
  NONE: 0, // 无权限 - 仅设备发现
  VIEW: 1, // 只读 - 查看系统信息、文件列表
  CONTROL: 2, // 控制 - 媒体控制、剪贴板同步
  MANAGE: 3, // 管理 - 进程管理、应用控制
  FULL: 4, // 完全 - 所有操作包括电源控制
};

2.2 命令权限映射

命令类别	所需权限	示例命令
系统信息	VIEW	`sysinfo.getCpuUsage`, `network.getInfo`
文件查看	VIEW	`file.list`, `file.getInfo`
媒体控制	CONTROL	`media.play`, `media.pause`
剪贴板	CONTROL	`clipboard.get`, `clipboard.set`
进程管理	MANAGE	`process.list`, `process.kill`
应用控制	MANAGE	`app.launch`, `app.close`
电源控制	FULL	`power.shutdown`, `power.reboot`
安全操作	FULL	`security.lock`, `security.logout`

2.3 权限验证流程

1. 接收命令请求
   ↓
2. 验证 DID 签名
   ↓
3. 检查 Nonce 防重放
   ↓
4. 查询设备权限等级
   ↓
5. 比较命令所需权限
   ↓
6. 通过 → 执行命令
   拒绝 → 返回权限错误

3. 命令处理器详解

3.1 处理器列表

#	处理器	注册名	主要功能
1	AICommandHandler	`ai`	AI 对话、RAG 搜索、Agent 控制
2	SystemCommandHandler	`system`	系统操作、截图、窗口控制
3	FileTransferHandler	`file`	文件上传、下载、同步
4	RemoteDesktopHandler	`desktop`	远程桌面流、输入控制
5	KnowledgeHandler	`knowledge`	知识库搜索、笔记操作
6	CommandHistoryHandler	`history`	命令历史记录和查询
7	DeviceManagerHandler	`device`	设备注册、状态管理
8	ClipboardHandler	`clipboard`	剪贴板同步
9	NotificationHandler	`notification`	通知推送和同步
10	WorkflowHandler	`workflow`	工作流自动化执行
11	BrowserHandler	`browser`	Puppeteer 浏览器自动化
12	PowerHandler	`power`	电源控制 (休眠/关机/重启)
13	ProcessHandler	`process`	进程列表、启动、终止
14	MediaHandler	`media`	媒体播放控制
15	NetworkHandler	`network`	网络信息和诊断
16	StorageHandler	`storage`	存储信息和磁盘操作
17	DisplayHandler	`display`	显示器信息和设置
18	InputHandler	`input`	键盘鼠标模拟输入
19	ApplicationHandler	`app`	应用程序启动和管理
20	SystemInfoHandler	`sysinfo`	系统信息收集
21	SecurityHandler	`security`	安全操作 (锁屏/登出)
22	UserBrowserHandler	`userBrowser`	用户浏览器 CDP 控制
23	ExtensionBrowserHandler	`extension`	浏览器扩展通信

3.2 命令格式 (JSON-RPC 2.0)

请求格式:

json

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "method": "handler.action",
  "params": { ... },
  "auth": {
    "did": "did:key:z...",
    "signature": "base64-signature",
    "timestamp": 1707667200000,
    "nonce": "random-nonce"
  }
}

响应格式:

json

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "result": { ... }
}

错误响应:

json

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "error": {
    "code": -32001,
    "message": "Permission Denied",
    "data": "Insufficient permission level"
  }
}

4. 浏览器扩展系统

4.1 架构

┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│  扩展 Popup.js  │ ←──→ │ Background.js   │ ←──→ │  Content.js     │
│  用户界面       │      │ 后台服务        │      │  页面注入       │
└─────────────────┘      └─────────────────┘      └─────────────────┘
                                ↕
                    Native Messaging Protocol
                                ↕
                    ┌─────────────────────────┐
                    │ BrowserExtensionServer  │
                    │ (WebSocket on 18790)    │
                    └─────────────────────────┘

4.2 支持的浏览器命令

命令	说明
`extension.navigate`	导航到指定 URL
`extension.click`	点击页面元素
`extension.type`	输入文本
`extension.screenshot`	获取页面截图
`extension.executeScript`	执行 JavaScript
`extension.getTabs`	获取标签页列表
`extension.closeTab`	关闭标签页
`extension.getPageContent`	获取页面内容
`extension.extractData`	提取页面数据
`extension.fillForm`	自动填充表单

4.3 扩展文件结构

browser-extension/
├── manifest.json       # 扩展清单 (MV3)
├── background.js       # 服务工作者
├── content.js          # 内容脚本
├── popup.html          # 弹出界面
├── popup.js            # 弹出逻辑
└── icons/              # 扩展图标

5. Android 端实现

5.1 UI 组件

界面	文件	功能
RemoteControlScreen	`RemoteControlScreen.kt`	主控制面板
PowerControlScreen	`PowerControlScreen.kt`	电源控制
ProcessManagerScreen	`ProcessManagerScreen.kt`	进程管理
MediaControlScreen	`MediaControlScreen.kt`	媒体控制
InputControlScreen	`InputControlScreen.kt`	输入控制
StorageInfoScreen	`StorageInfoScreen.kt`	存储信息
NetworkInfoScreen	`NetworkInfoScreen.kt`	网络信息
ApplicationManagerScreen	`ApplicationManagerScreen.kt`	应用管理
SecurityInfoScreen	`SecurityInfoScreen.kt`	安全信息
RemoteDesktopScreen	`RemoteDesktopScreen.kt`	远程桌面
FileTransferScreen	`FileTransferScreen.kt`	文件传输
ClipboardSyncScreen	`ClipboardSyncScreen.kt`	剪贴板同步

5.2 命令客户端

kotlin

class RemoteCommandClient(
    private val p2pClient: P2PClient,
    private val didSigner: DIDSigner
) {
    suspend fun sendCommand(
        method: String,
        params: Map<String, Any>,
        targetDid: String
    ): CommandResponse {
        val auth = AuthPayload(
            did = didSigner.getDid(),
            signature = didSigner.sign(params),
            timestamp = System.currentTimeMillis(),
            nonce = generateNonce()
        )

        val request = CommandRequest(
            jsonrpc = "2.0",
            id = UUID.randomUUID().toString(),
            method = method,
            params = params,
            auth = auth
        )

        return p2pClient.send(targetDid, request)
    }
}

6. 安全机制

6.1 认证流程

DID 签名验证: 每个命令必须携带 DID 签名
时间戳检查: 防止过期命令重放 (5分钟窗口)
Nonce 唯一性: 每个 Nonce 只能使用一次
权限验证: 检查设备权限等级

6.2 审计日志

javascript

// 审计日志结构
{
  id: "audit-uuid",
  timestamp: 1707667200000,
  did: "did:key:z...",
  peerId: "peer-id",
  method: "power.shutdown",
  params: { ... },
  result: "success" | "denied" | "error",
  reason: "Permission level insufficient",
  ip: "192.168.1.100"
}

6.3 敏感操作确认

对于高危操作 (如 power.shutdown)，系统会：

在 PC 端弹出确认对话框
记录详细审计日志
发送通知到所有已连接设备

7. 性能指标

指标	目标值	实际值
命令响应延迟	<100ms	~50ms
P2P 连接建立	<3s	~2s
权限验证耗时	<10ms	~5ms
并发命令处理	100/s	150/s
命令成功率	>99%	99.5%

8. 配置选项

javascript

// remote-gateway 配置
{
  enableP2P: true,           // 启用 P2P 通信
  enableWebSocket: true,     // 启用 WebSocket 扩展通信
  wsPort: 18789,             // WebSocket 端口
  wsHost: "127.0.0.1",       // WebSocket 主机

  permission: {
    defaultLevel: "VIEW",    // 新设备默认权限
    requireConfirmation: ["power.shutdown", "power.reboot"],
    auditRetentionDays: 30
  },

  fileTransfer: {
    maxFileSize: 100 * 1024 * 1024,  // 100MB
    chunkSize: 64 * 1024,            // 64KB
    allowedExtensions: ["*"]
  },

  browserExtension: {
    port: 18790,
    allowedOrigins: ["chrome-extension://...", "moz-extension://..."]
  }
}

9. 文件结构

desktop-app-vue/src/main/remote/
├── index.js                      # 模块入口
├── remote-gateway.js             # 远程网关
├── remote-ipc.js                 # IPC 处理器
├── p2p-command-adapter.js        # P2P 命令适配器
├── permission-gate.js            # 权限控制
├── command-router.js             # 命令路由
├── browser-extension-server.js   # 浏览器扩展服务器
├── browser-extension/            # 浏览器扩展文件
│   ├── manifest.json
│   ├── background.js
│   ├── content.js
│   ├── popup.html
│   └── popup.js
├── handlers/                     # 命令处理器 (23个)
│   ├── ai-handler.js
│   ├── system-handler.js
│   ├── file-transfer-handler.js
│   ├── remote-desktop-handler.js
│   ├── knowledge-handler.js
│   ├── command-history-handler.js
│   ├── device-manager-handler.js
│   ├── clipboard-handler.js
│   ├── notification-handler.js
│   ├── workflow-handler.js
│   ├── browser-handler.js
│   ├── power-handler.js
│   ├── process-handler.js
│   ├── media-handler.js
│   ├── network-handler.js
│   ├── storage-handler.js
│   ├── display-handler.js
│   ├── input-handler.js
│   ├── application-handler.js
│   ├── system-info-handler.js
│   ├── security-handler.js
│   └── user-browser-handler.js
├── logging/                      # 日志系统
│   ├── command-logger.js
│   ├── batched-command-logger.js
│   └── statistics-collector.js
└── workflow/                     # 工作流引擎
    └── workflow-engine.js

10. 使用示例

10.1 初始化远程网关

javascript

const { createRemoteGateway } = require("./remote");

const gateway = await createRemoteGateway(
  {
    p2pManager,
    didManager,
    ukeyManager,
    database,
    mainWindow,
    aiEngine,
    ragManager,
  },
  {
    enableP2P: true,
    permission: {
      defaultLevel: "VIEW",
    },
  },
);

// 监听事件
gateway.on("device:connected", (peerId) => {
  console.log("设备已连接:", peerId);
});

gateway.on("command:completed", ({ method, success, duration }) => {
  console.log(
    `命令 ${method} ${success ? "成功" : "失败"}, 耗时 ${duration}ms`,
  );
});

10.2 Android 端发送命令

kotlin

// 获取系统信息
val result = remoteCommandClient.sendCommand(
    method = "sysinfo.getCpuUsage",
    params = emptyMap(),
    targetDid = desktopDid
)

// 控制媒体播放
remoteCommandClient.sendCommand(
    method = "media.pause",
    params = mapOf("player" to "spotify"),
    targetDid = desktopDid
)

// 终止进程
remoteCommandClient.sendCommand(
    method = "process.kill",
    params = mapOf("pid" to 12345),
    targetDid = desktopDid
)

11. 相关文档

文档版本: 1.0 最后更新: 2026-02-11

附录：规范章节补全（v5.0.3.108）

本文为系统设计子文档。为对齐项目文档标准结构，下列章节以 见正文 指引或简述方式补齐若干视角，不重复正文细节。

1. 概述

见正文「模块概述 / 功能描述」。远程控制系统：跨设备远程操控（桌面 ↔ 移动）。

2. 核心特性

远程命令 / signaling / WebRTC / 配对信任。

3. 系统架构

见正文「架构设计」。

4. 系统定位

ChainlessChain 的「远程控制系统」。

5. 核心功能

见正文模块概述与各节。

6. 技术架构

见正文实现章节；remote 模块 / signaling。

7. 系统特点

见正文（状态 / 版本 / 特性）。

8. 应用场景

跨设备远程操控桌面。

9. 竞品对比

见正文对比（如有）。

10. 配置参考

见正文配置 / 参数章节。

11. 性能指标

见正文性能 / 指标章节。

12. 测试覆盖

见正文测试章节。

13. 安全考虑

见正文安全 / 权限章节；本地加密 + RBAC（如适用）。

14. 故障排除

见正文故障 / 已知限制章节。

15. 关键文件

remote 模块 / signaling。

16. 使用示例

见正文使用 / API 示例。

17. 相关文档

系统设计主文档、docs-site 对应功能页。

远程控制系统设计文档 ​

模块概述 ​

核心特性 ​

1. 系统架构 ​

1.1 整体架构图 ​

1.2 核心组件 ​

2. 权限系统 ​

2.1 权限等级 ​

2.2 命令权限映射 ​

2.3 权限验证流程 ​

3. 命令处理器详解 ​

3.1 处理器列表 ​

3.2 命令格式 (JSON-RPC 2.0) ​

4. 浏览器扩展系统 ​

4.1 架构 ​

4.2 支持的浏览器命令 ​

4.3 扩展文件结构 ​

5. Android 端实现 ​

5.1 UI 组件 ​

5.2 命令客户端 ​

6. 安全机制 ​

6.1 认证流程 ​

6.2 审计日志 ​

6.3 敏感操作确认 ​

7. 性能指标 ​

8. 配置选项 ​

9. 文件结构 ​

10. 使用示例 ​

10.1 初始化远程网关 ​

10.2 Android 端发送命令 ​

11. 相关文档 ​

附录：规范章节补全（v5.0.3.108） ​

1. 概述 ​

2. 核心特性 ​

3. 系统架构 ​

4. 系统定位 ​

5. 核心功能 ​

6. 技术架构 ​

7. 系统特点 ​

8. 应用场景 ​

9. 竞品对比 ​

10. 配置参考 ​

11. 性能指标 ​

12. 测试覆盖 ​

13. 安全考虑 ​

14. 故障排除 ​

15. 关键文件 ​

16. 使用示例 ​

17. 相关文档 ​

远程控制系统设计文档

模块概述

核心特性

1. 系统架构

1.1 整体架构图

1.2 核心组件

2. 权限系统

2.1 权限等级

2.2 命令权限映射

2.3 权限验证流程

3. 命令处理器详解

3.1 处理器列表

3.2 命令格式 (JSON-RPC 2.0)

4. 浏览器扩展系统

4.1 架构

4.2 支持的浏览器命令

4.3 扩展文件结构

5. Android 端实现

5.1 UI 组件

5.2 命令客户端

6. 安全机制

6.1 认证流程

6.2 审计日志

6.3 敏感操作确认

7. 性能指标

8. 配置选项

9. 文件结构

10. 使用示例

10.1 初始化远程网关

10.2 Android 端发送命令

11. 相关文档

附录：规范章节补全（v5.0.3.108）

1. 概述

2. 核心特性

3. 系统架构

4. 系统定位

5. 核心功能

6. 技术架构

7. 系统特点

8. 应用场景

9. 竞品对比

10. 配置参考

11. 性能指标

12. 测试覆盖

13. 安全考虑

14. 故障排除

15. 关键文件

16. 使用示例

17. 相关文档