技术拆解-ClaudeCopilot

这个项目可以作为开发 Claude Code 交互软件的参考。

1. 项目概览

项目定位和目标用户

Claude Autopilot 是一个 VS Code 扩展，专为需要批量处理 Claude Code 任务的开发者设计。目标用户是需要自动化处理大量 AI 编程任务的开发者，特别是需要进行大规模代码重构、迁移或生成的场景。

技术栈选择和版本信息

  • VS Code API: ^1.74.0
  • TypeScript: ^4.9.4
  • Node.js: ES2020
  • Express.js: ^5.1.0
  • WebSocket: ^8.18.3
  • Python 3.8+: 用于 Claude CLI 包装器
  • 跨平台支持: Windows (WSL)、macOS、Linux

核心特性和亮点功能

  • 24/7 自动化处理: 队列化批量任务，自动恢复处理
  • 智能队列管理: 支持任务优先级、重试、错误处理
  • 移动端 Web 界面: 通过 WebSocket 实现远程监控和控制
  • 跨平台兼容: 特别针对 Windows WSL 环境优化
  • 依赖管理: 自动检测和验证 Claude CLI、Python 等依赖
  • 睡眠防护: 防止系统休眠影响长时间任务处理

2. 架构设计深度解析

2.1 整体架构图

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
┌─────────────────────────────────────────────────────────────────┐
│                    VS Code Extension Host                      │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────┐ │
│  │   Core      │  │   Claude    │  │   Queue     │  │ Services│ │
│  │   Module    │  │   Module    │  │   Module    │  │ Module  │ │
│  │  • Types    │  │  • Session  │  │  • Manager  │  │  • Health│ │
│  │  • Config   │  │  • Output   │  │  • Memory   │  │  • Sleep │ │
│  │  • State    │  │  • Comm     │  │  • History  │  │  • Usage │ │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────┘ │
│           │                    │                    │         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────┐ │
│  │     UI      │  │   Utils     │  │   Mobile    │  │   Git   │ │
│  │  • Webview  │  │  • Logging  │  │  • Server   │  │ Services│ │
│  │  • Content  │  │  • Error    │  │  • Auth     │  │         │ │
│  │  • State    │  │  • Notify   │  │  • Routes   │  │         │ │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────┘ │
└─────────────────────────────────────────────────────────────────┘
                              │
                    ┌─────────────────────────┐
                    │      External Systems     │
                    │  • Claude CLI Process   │
                    │  • Python PTY Wrapper   │
                    │  • Web Browser Clients  │
                    │  • System Sleep Control  │
                    └─────────────────────────┘

2.2 模块划分策略

Core 模块 (src/core/):

  • types: 定义核心数据结构（MessageItem、HistoryRun）
  • config: 配置管理和验证系统
  • state: 全局状态管理，使用集中式状态模式
  • constants: 常量和 UI 字符串定义

Claude 模块 (src/claude/):

  • session: Claude CLI 会话管理
  • output: 输出处理和格式化
  • communication: 与 Claude 进程的通信

Queue 模块 (src/queue/):

  • manager: 队列操作和自动启动逻辑
  • memory: 内存管理和大小限制
  • processor: 历史记录处理

Services 模块 (src/services/):

  • mobile: Web 服务器和移动端支持
  • health: 健康检查
  • sleep: 睡眠防护
  • usage: 使用限制处理

2.3 依赖关系分析

  • 无循环依赖: 模块间通过接口和事件通信，避免循环依赖
  • 状态管理: 使用集中式状态管理，各模块通过状态变更通知进行通信
  • 事件驱动: 大量使用事件和回调机制处理异步操作
  • 依赖注入: 服务通过工厂函数和单例模式管理

3. 核心设计模式提取

3.1 组件设计模式

模块导出模式:

1
2
3
4
// 每个模块统一导出接口
export * from './session';
export * from './output';
export * from './communication';

状态管理模式:

1
2
3
4
5
6
7
8
9
10
// 集中式状态管理
export let messageQueue: MessageItem[] = [];
export let claudeProcess: ChildProcess | null = null;
export let sessionReady = false;

// 状态变更函数
export function setMessageQueue(queue: MessageItem[]) {
  messageQueue = queue;
  notifyMobileQueueUpdate();
}

配置验证模式:

1
2
3
4
5
6
7
8
// 配置验证和错误处理
export function validateConfig(
  config: Partial<ClaudeAutopilotConfig>
): ConfigValidationError[] {
  const errors: ConfigValidationError[] = [];
  // 验证逻辑
  return errors;
}

3.2 状态管理模式

全局状态管理: 使用 TypeScript 模块级别的变量管理全局状态
状态变更通知: 状态变更时自动通知相关组件和移动端
状态同步机制: 通过 WebSocket 实现多端状态同步

3.3 样式管理模式

VS Code 主题集成: 使用 CSS 变量适配 VS Code 主题
响应式设计: Webview 界面支持不同屏幕尺寸
组件化样式: 模块化的 CSS 类名和样式定义

4. 可复用设计要素

4.1 通用架构模式

模块化导出模式: 每个模块统一导出接口，便于维护和扩展

1
2
3
4
// 可复用的模块导出模式
export * from './submodule1';
export * from './submodule2';
export * from './submodule3';

配置验证模式: 完整的配置验证和错误处理机制

1
2
3
4
5
6
7
8
9
10
11
// 可复用的配置验证模式
interface ConfigValidationError {
  path: string;
  value: any;
  expected: string;
  message: string;
}

function validateConfig(config: Partial<T>): ConfigValidationError[] {
  // 验证逻辑
}

状态管理通知模式: 状态变更时自动通知相关方

1
2
3
4
5
// 可复用的状态通知模式
function setStateAndNotify(value: T) {
  state = value;
  notifyInterestedParties();
}

异步队列处理模式: 支持暂停、恢复、重试的队列处理

1
2
3
4
5
6
7
8
9
10
// 可复用的队列处理模式
async function processQueue(): Promise<void> {
  while (hasItems && shouldProcess) {
    try {
      await processNextItem();
    } catch (error) {
      await handleError(error);
    }
  }
}

4.2 技术实现手法

跨平台进程管理: 统一的跨平台进程创建和管理

1
2
3
4
5
6
7
8
9
10
11
// 可复用的跨平台进程管理
function createCrossPlatformProcess(
  command: string,
  args: string[]
): ChildProcess {
  if (process.platform === 'win32') {
    return spawn('wsl', ['python3', ...args]);
  } else {
    return spawn('python3', args);
  }
}

WebSocket 实时通信: 实时的多端通信机制

1
2
3
4
5
6
7
8
9
10
// 可复用的 WebSocket 通信
class WebSocketManager {
  private clients: Set<WebSocket> = new Set();

  broadcast(message: any): void {
    this.clients.forEach((client) => {
      client.send(JSON.stringify(message));
    });
  }
}

依赖检查系统: 运行时依赖检查和验证

1
2
3
4
5
6
7
// 可复用的依赖检查
interface DependencyCheckResult {
  available: boolean;
  version?: string;
  error?: string;
  path?: string;
}

错误处理和恢复: 完善的错误处理和自动恢复机制

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// 可复用的错误处理
async function withRetry<T>(
  operation: () => Promise<T>,
  maxRetries: number = 3
): Promise<T> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await operation();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await delay(1000 * Math.pow(2, i));
    }
  }
}

4.3 安全设计模式

认证和授权: 基于令牌的认证系统

1
2
3
4
5
6
7
8
9
// 可复用的认证管理
class AuthManager {
  private authToken: string;
  private activeSessions: Set<string> = new Set();

  validateToken(token: string): boolean {
    return token === this.authToken;
  }
}

输入验证: 严格的输入验证和清理

1
2
3
4
// 可复用的输入验证
function validateUserInput(input: string): boolean {
  return input.length > 0 && input.length <= MAX_LENGTH;
}

5. 特定绑定特性

5.1 业务特定实现

Claude CLI 集成: 深度集成 Claude CLI 的特定实现

  • 绑定原因：依赖 Claude CLI 的特定输出格式和交互模式
  • 替代方案：抽象化 CLI 接口，支持多种 AI 编程工具

VS Code 扩展架构: 完全基于 VS Code 扩展 API

  • 绑定原因：使用 VS Code 的 webview、命令、配置等特性
  • 替代方案：抽象化编辑器接口，支持多种编辑器

队列批处理: 针对编程任务的队列处理逻辑

  • 绑定原因：特定于代码生成和重构的任务类型
  • 替代方案：通用任务队列，支持插件式任务处理器

5.2 技术栈绑定

VS Code API: 扩展完全依赖 VS Code API

  • 绑定关系：无法脱离 VS Code 运行
  • 迁移难度：高，需要重新设计 UI 和扩展机制

Python PTY 包装器: 使用 Python 的 pty 模块

  • 绑定关系：依赖 Unix-like 的 PTY 接口
  • 迁移难度：中，可以使用其他语言的 PTY 库

WebSocket 实时通信: 使用 ws 库

  • 绑定关系：依赖特定的 WebSocket API
  • 迁移难度：低，可以使用其他 WebSocket 库

6. 最佳实践总结

6.1 值得学习的设计思路

模块化架构: 清晰的模块划分和职责分离

  • 每个模块职责单一，便于维护和测试
  • 统一的模块导出模式，提高代码一致性

状态管理: 集中式状态管理配合变更通知

  • 避免状态分散，减少同步问题
  • 自动通知机制确保多端状态一致性

错误处理: 完善的错误处理和恢复机制

  • 多层错误处理，从用户输入到系统错误
  • 自动重试和恢复，提高系统稳定性

跨平台支持: 优雅的跨平台实现

  • 针对不同平台的特定优化
  • 统一的接口，隐藏平台差异

用户体验: 丰富的用户交互和反馈

  • 实时状态更新和进度显示
  • 多种交互方式（键盘、鼠标、移动端）

6.2 可改进的设计点

测试覆盖: 缺少自动化测试

  • 建议添加单元测试和集成测试
  • 使用 VS Code 扩展测试框架

文档完善: API 文档和开发者指南

  • 建议添加详细的 API 文档
  • 提供插件开发指南

性能优化: 大量消息时的性能问题

  • 建议实现虚拟滚动
  • 优化内存使用和垃圾回收

配置复杂度: 配置项过多，用户体验复杂

  • 建议简化配置，提供智能默认值
  • 添加配置向导

6.3 对其他项目的启发

扩展架构: VS Code 扩展开发的标准模式

  • 清晰的模块划分和状态管理
  • 完善的用户界面和交互设计

实时通信: WebSocket 在桌面应用中的应用

  • 多端实时同步的实现方式
  • 事件驱动的架构设计

异步处理: 复杂异步任务的处理模式

  • 队列管理和任务调度
  • 错误处理和恢复机制

跨平台开发: 桌面应用跨平台开发的最佳实践

  • 平台特定代码的抽象
  • 统一的用户体验设计

7. 实施建议

7.1 直接复用建议

状态管理系统: 可直接用于需要集中式状态管理的项目

  • 适合：多组件状态同步、复杂应用状态管理
  • 实现：使用 TypeScript 模块级变量 + 变更通知

配置验证系统: 可直接用于需要复杂配置管理的项目

  • 适合：企业级应用、需要配置验证的项目
  • 实现：配置接口 + 验证函数 + 错误处理

WebSocket 通信框架: 可直接用于需要实时通信的项目

  • 适合：多端同步、实时监控、协作应用
  • 实现：WebSocket 管理器 + 广播机制 + 认证系统

7.2 改进复用建议

队列处理系统: 适用于需要任务队列的项目

  • 改进：抽象化任务处理器，支持插件式任务
  • 适用：工作流引擎、任务调度系统

错误处理框架: 适用于需要高可靠性的项目

  • 改进：支持多种错误处理策略，可配置重试机制
  • 适用：微服务、分布式系统

跨平台进程管理: 适用于需要跨平台进程操作的项目

  • 改进：支持更多平台，抽象化进程接口
  • 适用：DevOps 工具、系统管理软件

7.3 创新扩展建议

AI 编程助手框架: 基于 Claude Autopilot 的架构

  • 扩展：支持多种 AI 编程工具
  • 创新：插件式 AI 工具集成，统一的工作流管理

自动化任务平台: 通用自动化任务处理平台

  • 扩展：支持更多任务类型和触发器
  • 创新：可视化任务编排，智能任务调度

开发工具链: 集成开发环境扩展平台

  • 扩展：支持多种编辑器和 IDE
  • 创新：统一的扩展接口，跨平台开发体验

8. 核心技术实现深度分析

8.1 任务队列的具体实现

8.1.1 队列数据结构

1
2
3
4
5
6
7
8
9
10
11
12
13
// src/core/types/index.ts
export interface MessageItem {
  id: string;
  text: string;
  timestamp: string;
  status: 'pending' | 'processing' | 'completed' | 'error' | 'waiting';
  output?: string;
  error?: string;
  processingStartedAt?: string;
  completedAt?: string;
  waitUntil?: number;
  waitSeconds?: number;
}

8.1.2 队列管理核心逻辑

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// src/queue/manager/index.ts
export function addMessageToQueueFromWebview(message: string): void {
  const messageItem: MessageItem = {
    id: generateMessageId(),
    text: message,
    timestamp: new Date().toISOString(),
    status: 'pending',
  };

  // 应用大小限制
  const sizeLimitedMessage = enforceMessageSizeLimits(messageItem);

  messageQueue.push(sizeLimitedMessage);

  // 检查并强制执行队列大小限制
  enforceQueueSizeLimit();

  updateWebviewContent();

  // 保存待处理队列
  savePendingQueue();

  // 尝试自动启动处理
  tryAutoStartProcessing();
}

8.1.3 自动启动机制

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
// src/queue/manager/index.ts
export function tryAutoStartProcessing(): void {
  const hasProcessingMessages = messageQueue.some(
    (msg) => msg.status === 'processing'
  );
  const hasPendingMessages = messageQueue.some(
    (msg) => msg.status === 'pending'
  );
  const hasWaitingMessages = messageQueue.some(
    (msg) => msg.status === 'waiting'
  );

  // 自动启动条件：
  // 1. 会话已就绪
  // 2. 没有正在处理的消息
  // 3. 有待处理的消息
  // 4. 没有等待中的消息（避免与使用限制等待冲突）
  const shouldAutoStart =
    sessionReady &&
    !hasProcessingMessages &&
    hasPendingMessages &&
    !hasWaitingMessages &&
    (processingQueue ||
      (!processingQueue &&
        messageQueue.filter((m) => m.status !== 'waiting').length === 1));

  if (shouldAutoStart) {
    if (!processingQueue) {
      setProcessingQueue(true);
      setIsRunning(true);
    }
    setTimeout(() => {
      processNextMessage();
    }, 200);
  }
}

8.2 与 Claude Code 的交互机制

8.2.1 Claude Code 进程启动

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
// src/claude/session/index.ts
export async function startClaudeSession(
  skipPermissions: boolean = true
): Promise<void> {
  // 检查依赖
  const dependencyResults = await runDependencyCheck();

  // 获取工作目录
  const workspaceFolder = vscode.workspace.workspaceFolders?.[0];
  const cwd = workspaceFolder?.uri.fsPath || process.cwd();

  // 跨平台进程创建
  let command: string;
  let args: string[];

  if (process.platform === 'win32') {
    // Windows 使用 WSL
    const wslWrapperPath = wrapperPath.replace(
      /^([A-Za-z]):/,
      (match, driveLetter) => {
        return `/mnt/${driveLetter.toLowerCase()}`;
      }
    );
    command = 'wsl';
    args = ['python3', wslWrapperPath];
    if (skipPermissions) {
      args.push('--skip-permissions');
    }
  } else {
    // macOS/Linux 直接使用 Python
    command = pythonPath;
    args = [wrapperPath];
    if (skipPermissions) {
      args.push('--skip-permissions');
    }
  }

  // 创建进程
  const spawnedProcess = spawn(command, args, {
    cwd: cwd,
    stdio: ['pipe', 'pipe', 'pipe'],
    env: {
      ...process.env,
      TERM: 'xterm-256color',
      COLUMNS: '120',
      LINES: '30',
    },
  });

  setClaudeProcess(spawnedProcess);
}

8.2.2 输出监听和状态检测

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
// src/claude/session/index.ts
spawnedProcess.stdout?.on('data', (data: Buffer) => {
  const output = data.toString();

  // 发送输出到界面
  sendClaudeOutput(output);

  // 检测使用限制
  if (
    output.includes('Claude usage limit reached') ||
    output.includes('usage limit reached')
  ) {
    if (currentMessage && isCurrentUsageLimit(output)) {
      handleUsageLimit(output, currentMessage);
    }
    return;
  }

  // 检测认证错误
  const isAuthError = output.includes('Claude CLI authentication failed');
  if (isAuthError) {
    setSessionReady(false);
    if (currentMessage) {
      currentMessage.status = 'error';
      currentMessage.error = 'Claude CLI authentication failed';
    }
    return;
  }

  // 检测权限提示和就绪状态
  const hasPermissionPrompt = output.includes(
    'Do you want to make this edit to'
  );
  const shortcutsPromptRegex =
    /\\u001b\[39m\\u001b\[22m\s>\s\\u001b\[7mT\\u001b\[27m/;

  if (hasPermissionPrompt && !sessionReady) {
    setSessionReady(true);
    startHealthCheck();
    startSleepPrevention();
  } else if (
    (output.includes('? for shortcuts') ||
      shortcutsPromptRegex.test(JSON.stringify(output))) &&
    !sessionReady
  ) {
    setSessionReady(true);
    startHealthCheck();
    startSleepPrevention();
  }
});

8.2.3 任务完成检测和下一个任务执行

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
// src/claude/communication/index.ts
export async function processNextMessage(): Promise<void> {
  if (!sessionReady || !processingQueue) {
    debugLog(
      '❌ Cannot process next message: session not ready or processing disabled'
    );
    return;
  }

  // 查找下一个待处理的消息
  const nextMessage = messageQueue.find((msg) => msg.status === 'pending');
  if (!nextMessage) {
    debugLog('✅ No more messages to process');
    setProcessingQueue(false);
    setIsRunning(false);
    return;
  }

  // 设置当前消息状态
  setCurrentMessage(nextMessage);
  nextMessage.status = 'processing';
  nextMessage.processingStartedAt = new Date().toISOString();

  updateWebviewContent();

  try {
    // 发送消息到 Claude
    await sendMessageToClaude(nextMessage.text);

    // 等待任务完成（通过输出监听器检测）
    await waitForTaskCompletion(nextMessage);

    // 标记任务完成
    nextMessage.status = 'completed';
    nextMessage.completedAt = new Date().toISOString();

    // 处理下一个任务
    setTimeout(() => processNextMessage(), 1000);
  } catch (error) {
    nextMessage.status = 'error';
    nextMessage.error = error.message;

    // 继续处理下一个任务
    setTimeout(() => processNextMessage(), 1000);
  } finally {
    setCurrentMessage(null);
    updateWebviewContent();
  }
}

8.3 命令行输出的获取和展示

8.3.1 输出获取机制

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// src/claude/output/index.ts
export function sendClaudeOutput(output: string): void {
  // 更新输出缓冲区
  claudeOutputBuffer += output;
  setLastClaudeOutputTime(Date.now());

  // 格式化输出（保持 ANSI 转义序列）
  const formattedOutput = formatTerminalOutput(output, 'info');

  // 发送到 webview 终端
  sendToWebviewTerminal(formattedOutput);

  // 发送到移动端
  notifyMobileOutputUpdate();

  // 清理旧的输出定时器
  if (claudeOutputTimer) {
    clearTimeout(claudeOutputTimer);
  }

  // 设置新的输出定时器（防抖）
  claudeOutputTimer = setTimeout(() => {
    flushClaudeOutput();
  }, 100);
}

8.3.2 ANSI 转义序列处理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
// src/utils/logging/index.ts
export function formatTerminalOutput(
  output: string,
  type: 'info' | 'error' | 'warning'
): string {
  // 保持原始的 ANSI 转义序列，这些会在前端解析
  const timestamp = new Date().toLocaleTimeString();
  const prefix = `[${timestamp}] `;

  // 将输出包装在 spans 中，保持原始格式
  return `<span class="terminal-line terminal-${type}">${prefix}${escapeHtml(
    output
  )}</span>`;
}

// src/webview/extension/utils/ansi-parser.js
export function parseAnsiText(text) {
  // 解析 ANSI 转义序列并转换为 HTML
  const ansiRegex = /\x1b\[([0-9;]*)m/g;
  let result = '';
  let currentStyle = {};
  let lastIndex = 0;
  let match;

  while ((match = ansiRegex.exec(text)) !== null) {
    // 添加文本内容
    result += escapeHtml(text.substring(lastIndex, match.index));

    // 处理 ANSI 码
    const codes = match[1].split(';');
    codes.forEach((code) => {
      const num = parseInt(code);
      if (num === 0) {
        currentStyle = {};
      } else if (num === 1) {
        currentStyle.fontWeight = 'bold';
      } else if (num === 3) {
        currentStyle.fontStyle = 'italic';
      } else if (num >= 30 && num <= 37) {
        currentStyle.color = getAnsiColor(num - 30);
      } else if (num >= 40 && num <= 47) {
        currentStyle.backgroundColor = getAnsiColor(num - 40);
      }
    });

    lastIndex = match.index + match[0].length;
  }

  // 添加剩余文本
  result += escapeHtml(text.substring(lastIndex));

  // 应用样式
  if (Object.keys(currentStyle).length > 0) {
    const styleStr = Object.entries(currentStyle)
      .map(([key, value]) => `${key}: ${value}`)
      .join('; ');
    result = `<span style="${styleStr}">${result}</span>`;
  }

  return result;
}

8.3.3 终端界面展示

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// src/webview/extension/ui/output-handlers.js
export function updateTerminalOutput(output) {
  const terminal = document.getElementById('claudeOutput');
  if (!terminal) return;

  // 解析 ANSI 转义序列
  const parsedOutput = parseAnsiText(output);

  // 创建新的输出行
  const outputLine = document.createElement('div');
  outputLine.className = 'terminal-output-line';
  outputLine.innerHTML = parsedOutput;

  // 添加到终端
  terminal.appendChild(outputLine);

  // 自动滚动到底部
  terminal.scrollTop = terminal.scrollHeight;

  // 限制输出行数
  const maxLines = 1000;
  while (terminal.children.length > maxLines) {
    terminal.removeChild(terminal.firstChild);
  }
}

8.4 Web 展示和通信机制

8.4.1 Web 服务器架构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
// src/services/mobile/index.ts
export class MobileServer {
  private authManager: AuthManager;
  private staticRoutes: StaticRoutes;
  private apiRoutes: APIRoutes;
  private webSocketManager: WebSocketManager;
  private serverManager: ServerManager;

  constructor() {
    this.config = {
      authToken: uuidv4(),
      useExternalServer: false,
      webPassword: '',
      passwordAttempts: new Map(),
      blockedIPs: new Set(),
      activeSessions: new Set(),
    };

    this.authManager = new AuthManager(this.config, () => this.stop());
    this.staticRoutes = new StaticRoutes(this.authManager, this.config);
    this.apiRoutes = new APIRoutes(this.authManager, this.config);
    this.webSocketManager = new WebSocketManager(this.config.authToken);
    this.serverManager = new ServerManager(this.authManager, this.config);

    this.setupRoutes();
    this.setupNotificationCallbacks();
  }

  public async start(): Promise<string> {
    const url = await this.serverManager.start();

    const httpServer = this.serverManager.getHttpServer();
    if (httpServer) {
      this.webSocketManager.setupWebSocket(httpServer);
    }

    return url;
  }
}

8.4.2 WebSocket 实时通信

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
// src/services/mobile/websocket/websocket-manager.ts
export class WebSocketManager {
  private clients: Set<WebSocket> = new Set();
  private authToken: string;

  constructor(authToken: string) {
    this.authToken = authToken;
  }

  public setupWebSocket(httpServer: any): void {
    const wss = new WebSocket.Server({
      server: httpServer,
      path: '/ws',
    });

    wss.on('connection', (ws: WebSocket, req: http.IncomingMessage) => {
      // 验证认证令牌
      const token = new URL(
        req.url!,
        `http://${req.headers.host}`
      ).searchParams.get('token');
      if (token !== this.authToken) {
        ws.close(1008, 'Invalid authentication token');
        return;
      }

      this.clients.add(ws);

      ws.on('close', () => {
        this.clients.delete(ws);
      });

      ws.on('message', (message: string) => {
        this.handleMessage(ws, message);
      });

      // 发送初始状态
      this.sendInitialState(ws);
    });
  }

  public notifyQueueUpdate(): void {
    this.broadcast({
      type: 'queueUpdate',
      queue: messageQueue,
      timestamp: Date.now(),
    });
  }

  public notifyOutputUpdate(): void {
    this.broadcast({
      type: 'outputUpdate',
      output: claudeOutputBuffer,
      timestamp: Date.now(),
    });
  }

  private broadcast(message: any): void {
    const messageStr = JSON.stringify(message);
    this.clients.forEach((client) => {
      if (client.readyState === WebSocket.OPEN) {
        client.send(messageStr);
      }
    });
  }
}

8.4.3 Web 端实时输出展示

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
// src/webview/web/js/core/MobileInterface.js
export class MobileInterface {
  constructor() {
    this.setupWebSocket();
    this.setupTerminal();
  }

  setupWebSocket() {
    const wsUrl = `ws://${
      window.location.host
    }/ws?token=${this.getAuthToken()}`;
    this.ws = new WebSocket(wsUrl);

    this.ws.onmessage = (event) => {
      const data = JSON.parse(event.data);

      switch (data.type) {
        case 'queueUpdate':
          this.updateQueueDisplay(data.queue);
          break;
        case 'outputUpdate':
          this.updateTerminalOutput(data.output);
          break;
        case 'statusUpdate':
          this.updateStatusDisplay(data.status);
          break;
      }
    };

    this.ws.onclose = () => {
      // 尝试重连
      setTimeout(() => this.setupWebSocket(), 5000);
    };
  }

  updateTerminalOutput(output) {
    const terminal = document.getElementById('terminal');
    if (!terminal) return;

    // 解析 ANSI 转义序列
    const parsedOutput = this.parseAnsiText(output);

    // 创建输出行
    const line = document.createElement('div');
    line.className = 'terminal-line';
    line.innerHTML = parsedOutput;

    terminal.appendChild(line);
    terminal.scrollTop = terminal.scrollHeight;

    // 限制输出行数
    while (terminal.children.length > 2000) {
      terminal.removeChild(terminal.firstChild);
    }
  }

  parseAnsiText(text) {
    // 使用与扩展端相同的 ANSI 解析逻辑
    return parseAnsiToHtml(text);
  }
}

8.4.4 跨域和安全机制

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
// src/services/mobile/server/server-manager.ts
export class ServerManager {
  private app: Express;
  private server: http.Server | null = null;

  constructor(private authManager: AuthManager, private config: AuthConfig) {
    this.app = express();
    this.setupMiddleware();
  }

  private setupMiddleware(): void {
    // CORS 中间件
    this.app.use(
      cors({
        origin: (origin, callback) => {
          // 允许的来源
          const allowedOrigins = [
            'http://localhost:3000',
            'http://localhost:8080',
            'http://127.0.0.1:3000',
          ];

          if (!origin || allowedOrigins.includes(origin)) {
            callback(null, true);
          } else {
            callback(new Error('Not allowed by CORS'));
          }
        },
        credentials: true,
      })
    );

    // 安全中间件
    this.app.use(helmet());

    // 请求限制
    this.app.use(
      rateLimit({
        windowMs: 15 * 60 * 1000, // 15 分钟
        max: 100, // 限制每个 IP 15 分钟内最多 100 个请求
      })
    );

    // 解析中间件
    this.app.use(cookieParser());
    this.app.use(express.json());
    this.app.use(express.urlencoded({ extended: true }));
  }

  public async start(): Promise<string> {
    if (this.config.useExternalServer) {
      // 使用 ngrok 外部服务器
      return this.startExternalServer();
    } else {
      // 使用本地服务器
      return this.startLocalServer();
    }
  }

  private async startLocalServer(): Promise<string> {
    return new Promise((resolve, reject) => {
      this.server = this.app.listen(0, '127.0.0.1', () => {
        const port = this.server!.address().port;
        const url = `http://127.0.0.1:${port}`;
        resolve(url);
      });
    });
  }

  private async startExternalServer(): Promise<string> {
    // 使用 ngrok 创建隧道
    const ngrok = require('ngrok');
    const localPort = await this.startLocalServer();
    const publicUrl = await ngrok.connect(localPort.split(':')[2]);
    return publicUrl;
  }
}

9. 总结

Claude Autopilot 通过精心设计的架构实现了复杂的任务队列管理、Claude Code 交互、命令行输出处理和 Web 展示功能。其核心优势在于：

  1. 模块化设计: 清晰的职责分离，便于维护和扩展
  2. 异步处理: 完善的异步任务处理和错误恢复机制
  3. 实时通信: WebSocket 实现多端实时同步
  4. 跨平台支持: 优雅地处理不同平台的差异
  5. 用户体验: 丰富的交互方式和实时反馈

这些设计模式和实现手法为其他开发者提供了宝贵的参考，特别是在需要构建复杂的桌面应用、任务管理系统或实时协作工具时。