第16章 · 远程与直连

16.1 Remote Session Manager

remote/RemoteSessionManager.ts管理从用户端到远程Bridge会话的连接。

配置：

export type RemoteSessionConfig = {
  sessionId: string
  getAccessToken: () => string
  orgUuid: string
  hasInitialPrompt?: boolean
  viewerOnly?: boolean    // 纯查看模式（无Ctrl+C，无标题更新）
}

viewerOnly模式是一个值得注意的设计——它允许用户仅观察Agent的活动而不进行干预，这在团队协作场景中很有用（例如团队成员查看AI正在执行的自动化任务）。

回调系统：

export type RemoteSessionCallbacks = {
  onMessage: (message: SDKMessage) => void
  onPermissionRequest: (request: SDKControlPermissionRequest, requestId: string) => void
  onPermissionCancelled?: (requestId: string, toolUseId?: string) => void
  onConnected?: () => void
  onDisconnected?: () => void
  onReconnecting?: () => void
  onError?: (error: Error) => void
}

权限桥接：远程会话中的权限请求通过WebSocket转发给用户端，用户可以Allow或Deny：

export type RemotePermissionResponse =
  | { behavior: 'allow'; updatedInput: Record<string, unknown> }
  | { behavior: 'deny'; message: string }

updatedInput字段允许用户在批准时修改工具输入参数——例如批准文件写入但修改目标路径。这是一个细粒度的控制机制。

16.2 Direct Connect Manager

server/directConnectManager.ts实现了本地直连方案，使用NDJSON（换行分隔的JSON）协议：

// WebSocket接收NDJSON消息
ws.addEventListener('message', event => {
  const lines = data.split('\n').filter((l: string) => l.trim())
  for (const line of lines) {
    const parsed = jsonParse(line)
    // 路由不同消息类型
    if (parsed.type === 'control_request') { /* 权限请求 */ }
    if (parsed.type !== 'control_response' &&
        parsed.type !== 'keep_alive' &&
        parsed.type !== 'streamlined_text' &&
        parsed.type !== 'streamlined_tool_use_summary' &&
        !(parsed.type === 'system' && parsed.subtype === 'post_turn_summary')) {
      callbacks.onMessage(parsed)  // 转发SDK消息
    }
  }
})

消息过滤逻辑显示Direct Connect会过滤掉以下消息类型：

control_response — 控制响应（已处理）
keep_alive — 心跳（不转发）
streamlined_text — 流式文本（可能由独立渲染器处理）
streamlined_tool_use_summary — 工具使用摘要
post_turn_summary — 轮次后摘要

16.3 Deep Link协议

utils/deepLink/parseDeepLink.ts实现了claude-cli://协议处理，允许从浏览器或其他应用唤起Claude Code。

URI格式：

claude-cli://open[?q=<query>][&cwd=<path>][&repo=<owner/repo>]

安全验证相当严格：

ASCII控制字符（0x00-0x1F, 0x7F）被拒绝——它们可能被用作Shell分隔符
GitHub owner/repo格式验证：/^[\w.-]+\/[\w.-]+$/
查询长度限制：5,000字符（考虑cmd.exe的8191字符限制）
工作目录长度限制：4,096字符（PATH_MAX/MAX_PATH）
Unicode隐形字符清理：partiallySanitizeUnicode()

CWD解析优先级：

显式cwd > repo的MRU克隆路径 > 用户Home目录

完整处理流程：

用户点击claude-cli://open?q=hello&repo=owner/repo
OS启动claude二进制，传入--handle-uri <url>
handleDeepLinkUri()解析URI为DeepLinkAction
验证所有参数的安全性
解析工作目录
在终端中启动Claude，预填查询内容

Deep Link的设计使Claude Code能与GitHub、Jira等平台集成——例如，GitHub Issue中的"用Claude修复这个Bug"按钮可以直接打开Claude Code并加载相关上下文。

第16章 · 远程与直连