Native 能力层

职责概述

解决的问题：CC 的一些核心能力需要高性能——语法高亮要快、文件搜索要快、终端布局计算要快。以前这些用 Rust/C++ 原生模块实现，但原生二进制导致跨平台分发困难。这一层把所有原生模块用纯 TypeScript 重写，消除了原生依赖，同时保持性能可接受。

应用场景：① 代码差异的彩色渲染（新增行绿色、删除行红色）② 输入文件路径时的模糊搜索补全 ③ 终端界面的 Flexbox 布局计算 ④ 容器环境中的 MITM 代理设置 ⑤ 远程开发时本地 IDE 驱动容器内的 CC。

一句话理解：就像 Electron 之于桌面 App——用 Web 技术替代原生开发，牺牲一点极致性能，换来跨平台和可维护性。

架构设计

Native 模块架构图

核心数据流

1. Yoga Layout 计算流程

2. Upstream Proxy 初始化流程

关键类型与接口

FileIndex API (native-ts/file-index/index.ts)

// native-ts/file-index/index.ts — 核心接口
export type SearchResult = {
  path: string
  score: number  // 越低越好，最佳匹配 = 0.0
}

export class FileIndex {
  loadFromFileList(fileList: string[]): void
  loadFromFileListAsync(fileList: string[]): {
    queryable: Promise<void>  // 首个 chunk 就绪即可搜索
    done: Promise<void>       // 全部索引构建完成
  }
  search(query: string, limit: number): SearchResult[]
}

Yoga Node 核心 (native-ts/yoga-layout/index.ts)

// native-ts/yoga-layout/index.ts:403-466 — Node 类（核心字段）
export class Node {
  style: Style
  layout: Layout
  children: Node[]
  measureFunc: MeasureFunction | null
  isDirty_: boolean
  // 多级布局缓存
  _hasL: boolean         // 单条目 layout 缓存
  _cIn: Float64Array     // 多条目缓存输入（4 slot × 8 float）
  _cOut: Float64Array    // 多条目缓存输出（4 slot × 2 float）
  _fbGen: number         // flexBasis 缓存的 generation
  // 快速跳过标志
  _hasAutoMargin: boolean
  _hasPosition: boolean
  _hasPadding: boolean
  _hasBorder: boolean
  _hasMargin: boolean

  calculateLayout(ownerWidth?: number, ownerHeight?: number): void
}

Color Diff 接口 (native-ts/color-diff/index.ts)

// native-ts/color-diff/index.ts:52-69
export type Hunk = {
  oldStart: number; oldLines: number
  newStart: number; newLines: number
  lines: string[]
}
export type NativeModule = {
  ColorDiff: typeof ColorDiff
  ColorFile: typeof ColorFile
  getSyntaxTheme: (themeName: string) => SyntaxTheme
}

Bridge API (bridge/bridgeApi.ts)

// bridge/bridgeApi.ts:68 — 工厂函数签名
export function createBridgeApiClient(deps: BridgeApiDeps): BridgeApiClient
// deps 包含: baseUrl, getAccessToken, runnerVersion,
//   onAuth401 (OAuth 刷新), getTrustedDeviceToken

设计模式与亮点

◈ 可视化处理拓扑图

Phase 1 — Color-Diff 差异渲染管线

从终端颜色检测到语法高亮再到 ANSI 输出的完整渲染管线，支持 truecolor/256色/ANSI 三种终端模式。

Phase 2 — File-Index 模糊搜索与 Yoga 布局计算

Phase 3 — UpstreamProxy 代理中继

CCR 容器环境下的透明代理建立流程，每步失败开放。

⇉ 核心处理流程详解

Native 能力层的五个模块各自独立，但共享一个核心设计理念：从原生二进制依赖迁移到纯 TypeScript 实现，消除跨平台编译和 NAPI 绑定的复杂性。以下以 color-diff 差异渲染、file-index 模糊搜索、yoga-layout 布局计算 和 upstreamproxy 代理中继 四条核心流程展开。

★ 设计精华

1. 位图快速拒绝——O(1) 路径过滤

FileIndex.indexPath()（L156-167）为每个文件路径预计算一个 26 位整数位图，每一位对应 a-z 中的一个字母。搜索时先对查询字符串做位图 AND 操作，如果结果的位图是查询位图的子集，才进入昂贵的模糊匹配。这一步可以拒绝约 89% 的路径（对于常见查询如"test"），将实际需要评分的路径数量降低一个数量级。

// file-index/index.ts:156-167
private indexPath(i: number): void {
  const lp = this.paths[i]!.toLowerCase()
  this.lowerPaths[i] = lp
  this.pathLens[i] = len
  let bits = 0
  for (let j = 0; j < len; j++) {
    const c = lp.charCodeAt(j)
    if (c >= 97 && c <= 122) bits |= 1 << (c - 97)  // a-z 映射到 bit 0-25
  }
  this.charBits[i] = bits
}
// 搜索时：if ((charBits[i] & needleBits) !== needleBits) → 跳过

2. Yoga 多级布局缓存——热路径优化

yoga-layout/index.ts 实现了多级缓存策略：calculateLayout() 在 L932-934 重置访问计数器，layoutNode() 通过 cacheWrite()（L969-1012）比较当前 style 快照 + 父约束是否匹配缓存。命中时跳过整个布局递归，直接返回缓存的 Layout 对象。sameFloat()（L113-115）使用 a === b || (isNaN(a) && isNaN(b)) 做 NaN 安全的浮点比较。

// yoga-layout/index.ts:969-1012
function cacheWrite(node: Node, performLayout: boolean, ...): boolean {
  // 比较 style 快照 + 父约束
  if (sameFloat(cached.ownerWidth, ownerWidth) &&
      sameFloat(cached.ownerHeight, ownerHeight) &&
      // ... 所有 style 字段一致
     ) {
    commitCacheOutputs(node, performLayout)  // 命中：直接返回
    return true
  }
  // 未命中：更新缓存并重新计算
}

3. 异步分 chunk 构建——不阻塞事件循环

FileIndex.buildAsync()（L95-133）将文件列表索引化过程拆分为多个 chunk，每处理约 8-12k 条路径后调用 yieldToEventLoop() 让出控制权。这使得即使有 10 万级文件，索引构建也不会阻塞 UI 渲染和用户输入。

// file-index/index.ts:95-133
private async buildAsync(
  fileList: string[], markQueryable: () => void,
): Promise {
  const CHUNK_SIZE = 8192
  for (let i = 0; i < fileList.length; i += CHUNK_SIZE) {
    const end = Math.min(i + CHUNK_SIZE, fileList.length)
    const chunk = fileList.slice(i, end)
    this.buildIndex(chunk)
    if (i === 0) markQueryable()  // 首个 chunk 后即可查询
    await yieldToEventLoop()       // 让出事件循环
  }
}

4. CONNECT→WebSocket 中继——代理透明化

upstreamproxy 在 CCR 容器中建立透明代理：本地工具（Bash/MCP/LSP）通过 HTTP_PROXY=http://127.0.0.1:{port} 发出请求，proxy 拦截 CONNECT 请求，通过 WebSocket 隧道转发到 Anthropic 的 egress 网关。工具代码无需知道代理的存在——getUpstreamProxyEnv()（upstreamproxy.ts:160-199）将代理环境变量注入到每个子进程。

// upstreamproxy.ts:160-199
export function getUpstreamProxyEnv(): Record {
  if (!state.enabled) return {}
  return {
    HTTP_PROXY:  `http://127.0.0.1:${state.port}`,
    HTTPS_PROXY: `http://127.0.0.1:${state.port}`,
    NO_PROXY: NO_PROXY_LIST.join(','),  // 排除 Anthropic 内部域名
    NODE_EXTRA_CA_CERTS: state.caBundlePath,
  }
}

◈ Agent 实践借鉴 — 客服 Agent 平台能力设计

一、场景映射：客服 agent 的跨平台部署挑战

客服 agent 可能部署在三种截然不同的环境：云端 Docker 容器（有完整的语音识别 API、大模型服务、弹性扩缩容）、本地服务器（GPU 有限、网络可能受限、但有局域网 CRM 系统直连）、门店智能终端（有摄像头可扫条码、有本地数据库、但没有云端语音 API）。CC 用纯 TS 重写消除原生依赖以实现跨平台一致性，客服 agent 也面临同样的问题——同一个 agent 在不同环境下必须有统一的表现。

二、借鉴 CC + 客服改造

实践 1：平台能力检测 + 优雅降级（借鉴 CC 的 UpstreamProxy 环境检测）

CC 的 initUpstreamProxy() 检测 CCR 环境变量，每一步都失败开放。客服 agent 启动时也需要检测所在环境的能力——没有语音 API 就纯文字模式，没有摄像头就禁用扫码功能，没有本地数据库就用远程 API。

// 借鉴 upstreamproxy.ts:79-153 的环境检测 + 失败开放模式
interface PlatformCapabilities {
  canUseVoice: boolean       // 语音识别/合成
  canUseCamera: boolean      // 摄像头扫条码
  canUseLocalDB: boolean     // 本地数据库（门店场景）
  canUseGPU: boolean         // 本地推理能力
  canUseInternet: boolean    // 外网访问（门店可能断网）
}

class PlatformDetector {
  private capabilities: PlatformCapabilities

  constructor() {
    this.capabilities = {
      // 逐项检测，每项失败不影响其他项（失败开放）
      canUseVoice: this.checkVoiceAPI(),
      canUseCamera: this.checkCameraAccess(),
      canUseLocalDB: this.checkLocalDB(),
      canUseGPU: this.checkGPU(),
      canUseInternet: this.checkInternet(),
    }
    console.log('平台能力检测结果:', this.capabilities)
  }

  private checkVoiceAPI(): boolean {
    try {
      // 云端：检测 ASR 服务是否可达
      if (process.env.ASR_ENDPOINT) return true
      // 本地：检测 Whisper 模型是否可用
      return fs.existsSync('/usr/local/models/whisper')
    } catch { return false }  // 失败开放：不可用就不启用
  }

  private checkCamera(): boolean {
    try {
      // 门店终端：检测 /dev/video* 设备
      const devices = fs.readdirSync('/dev').filter(f => f.startsWith('video'))
      return devices.length > 0
    } catch { return false }
  }

  // 获取能力报告，供上层判断
  getCapabilities(): Readonly<PlatformCapabilities> {
    return this.capabilities
  }
}

// 使用：agent 启动时检测一次，运行时按能力路由
const platform = new PlatformDetector()
const caps = platform.getCapabilities()

// 没有语音 API 就关闭语音入口
if (!caps.canUseVoice) {
  channelRegistry.disable('phone')
  console.warn('语音 API 不可用，已关闭电话渠道')
}

实践 2：统一平台接口（借鉴 CC 的 Shell Provider 抽象）

CC 用 ShellProvider 接口统一了 Bash 和 PowerShell。客服 agent 的平台差异更大——语音、图像、本地存储都需要统一接口，让上层业务代码不关心底层是云端 API 还是本地模块。

// 借鉴 shellProvider.ts 的 Provider 抽象模式
interface SpeechService {
  recognize(audioBuffer: Buffer): Promise<string>    // 语音转文本
  synthesize(text: string): Promise<Buffer>           // 文本转语音
}

interface VisionService {
  scanBarcode(imageBuffer: Buffer): Promise<string>   // 扫条码
  ocr(imageBuffer: Buffer): Promise<string>           // 图片文字识别
}

interface StorageService {
  queryProduct(barcode: string): Promise<Product | null>
  saveInteraction(record: InteractionRecord): Promise<void>
}

// 云端实现：调用远程 API
class CloudSpeechService implements SpeechService {
  async recognize(audioBuffer: Buffer): Promise<string> {
    const resp = await fetch(`${process.env.ASR_ENDPOINT}/recognize`, {
      method: 'POST', body: audioBuffer,
    })
    return resp.json().then(r => r.text)
  }
}

// 本地实现：调用本地 Whisper 模型
class LocalSpeechService implements SpeechService {
  async recognize(audioBuffer: Buffer): Promise<string> {
    const whisper = require('whisper.cpp')  // 本地 NAPI 模块
    return whisper.transcribe(audioBuffer)
  }
}

// 工厂函数：根据平台能力自动选择实现
function createSpeechService(caps: PlatformCapabilities): SpeechService {
  if (caps.canUseInternet) return new CloudSpeechService()    // 云端优先
  if (caps.canUseGPU) return new LocalSpeechService()         // 本地降级
  return new TextOnlyFallback()                                // 纯文字兜底
}

实践 3：知识库搜索的预过滤（借鉴 CC 的位图快速拒绝思路）

CC 的 FileIndex 用 26 位字母位图预过滤 89% 的路径。客服场景的知识库搜索同样需要预过滤——10 万条 FAQ/商品条目中，先用轻量条件排除不可能匹配的，再做昂贵的语义搜索。

// 借鉴 file-index/index.ts:156-167 的位图预过滤思路
// （不需要抄位图算法本身，用标准搜索引擎的预过滤即可）

interface KnowledgeEntry {
  id: string
  category: string           // 'product' | 'faq' | 'policy' | 'troubleshoot'
  title: string
  keywords: string[]
  tags: string[]
}

class KnowledgeSearchEngine {
  private entries: KnowledgeEntry[] = []
  // 预过滤索引：按类别和标签建立倒排索引
  private categoryIndex = new Map<string, number[]>()
  private tagIndex = new Map<string, number[]>()

  // 步骤 1：轻量预过滤（类似位图快速拒绝）
  preFilter(query: SearchQuery): KnowledgeEntry[] {
    let candidateIndices: number[] | null = null

    // 按类别过滤
    if (query.category) {
      const indices = this.categoryIndex.get(query.category) ?? []
      candidateIndices = candidateIndices
        ? intersect(candidateIndices, indices)
        : indices
    }
    // 按标签过滤
    if (query.tags && query.tags.length > 0) {
      for (const tag of query.tags) {
        const indices = this.tagIndex.get(tag) ?? []
        candidateIndices = candidateIndices
          ? intersect(candidateIndices, indices)
          : indices
      }
    }
    // 如果没有过滤条件，返回全部
    const result = candidateIndices ?? this.entries.map((_, i) => i)
    return result.map(i => this.entries[i])
  }

  // 步骤 2：对幸存条目做昂贵的语义搜索
  async search(query: SearchQuery): Promise<KnowledgeEntry[]> {
    const candidates = this.preFilter(query)
    // 只对候选条目做向量相似度搜索（昂贵的操作）
    return this.semanticSearch(query.text, candidates, query.limit)
  }
}

// 使用示例：搜索退货相关的 FAQ
const results = await knowledgeBase.search({
  text: '买的东西坏了怎么退',
  category: 'faq',
  tags: ['refund', 'after_sales'],
  limit: 5,
})

三、落地清单

四、常见坑

代码索引