在开发 IntelliGit 的过程中，Git 底层操作的性能问题是绕不开的一个技术决策点。Electron 应用天然适合快速构建跨平台桌面界面，但涉及到大仓库的文件索引、提交历史遍历、差异计算这类操作时，纯 Node.js 方案的性能上限很容易成为瓶颈。本文记录我们最终采用的"Electron Main + Go Sidecar"混合架构设计，以及如何通过 JSON-RPC over stdio 实现两个进程之间高效、类型安全的通信。

---

一、为什么需要 Sidecar？

在确定方案之前，我们梳理了 Electron Git 客户端常见的两种技术路线，以及各自的局限性。

纯 Node.js 方案，通常使用 simple-git 这类库封装系统 Git CLI。实现简单，但问题也很明显：每次 Git 操作都要 spawn 一个子进程，在操作频繁或仓库体量大的场景下，进程创建的开销会直接反映到界面响应速度上。另外，这种方案强依赖用户本地的 Git 环境，版本不一致带来的兼容性问题在跨平台场景下尤其难以控制。

原生模块方案，通过 C++ Addons 绑定 libgit2，性能有了保障，但引入了新的麻烦：C++ 扩展的跨平台编译本身就是一件复杂的事情，不同 Node.js 版本、不同操作系统之间的兼容性需要大量额外维护。更关键的是，原生模块运行在主进程中，一旦出现内存管理问题或未捕获的异常，整个 Electron 主进程都会受到牵连。

IntelliGit 选择了第三条路：Go Sidecar。

Go 编译产出的是静态二进制文件，无外部运行时依赖，执行效率接近原生，跨平台编译也相对简单。更重要的是，Sidecar 作为独立进程运行，与 Electron 主进程完全隔离——即使 Go 侧发生 panic，也不会波及主界面的稳定性。Git 底层操作方面，go-git 库支持直接在内存中操作 Git 对象，绕开了频繁的文件 I/O，这在处理大型仓库时优势比较明显。

---

二、通信协议设计：JSON-RPC over Stdio

确定了 Sidecar 方案之后，下一个问题是：主进程（Node.js）和 Go 进程之间用什么方式通信？

进程间通信有不少选择——Unix Socket、HTTP、gRPC、stdio 管道……综合考虑实现复杂度和运行时开销，最终选择了 JSON-RPC 2.0 over stdio。两个进程通过 stdin/stdout 全双工通信，数据格式采用 NDJSON（换行分隔 JSON），每一行是一个独立的 JSON 对象，解析简单，边界清晰。

请求与响应结构

类型定义放在 src/shared/types/sidecar.ts 中，作为 TypeScript 和 Go 两侧的协议契约：

// src/shared/types/sidecar.ts
export interface SidecarRequest {
  jsonrpc: '2.0';
  id: string;        // 唯一请求 ID，用于异步响应配对
  method: string;    // 例如 "git/status"、"git/log"
  params?: Record<string, unknown>;
}

export interface SidecarResponse {
  jsonrpc: '2.0';
  id: string;
  result?: unknown;
  error?: JsonRpcError;
}

把类型定义放在 shared 层而非某一侧单独维护，是为了确保 TypeScript 的类型检查能覆盖到 Go 层返回的数据结构，避免两侧字段定义悄悄出现偏差。

Go 端的协议解析

Go Sidecar 的协议解析逻辑位于 sidecar/internal/protocol/protocol.go，核心是一个归一化处理函数，兼容标准 JSON-RPC 格式和内部简化格式：

// Normalize 将请求归一化为 command/payload 形式
func (r *Request) Normalize() {
    if strings.TrimSpace(r.Command) == "" {
        // 从 "git/status" 这类 method 字段中提取末段作为 command
        if idx := strings.LastIndex(r.Method, "/"); idx >= 0 {
            r.Command = strings.TrimSpace(r.Method[idx+1:])
        } else {
            r.Command = r.Method
        }
    }
    // params 作为 payload 的兜底来源
    if r.Payload == nil && r.Params != nil {
        r.Payload = r.Params
    }
}

这样处理的好处是，对外暴露的是标准 JSON-RPC 接口，内部执行逻辑统一走 command/payload 的形式处理，不需要在每个命令处理器里各自解析 method 字段。

---

三、主进程侧：SidecarManager

Electron 主进程中的 SidecarManager（src/main/core/SidecarManager.ts）是整个通信机制的核心，承担三块职责。

生命周期管理。 根据当前是开发环境还是生产环境，自动定位 Go 二进制文件的路径并启动进程。开发环境下指向编译输出目录，生产环境下指向打包后的资源目录，两种情况下的路径解析逻辑分开处理，避免环境差异导致的启动失败。

请求路由与超时控制。 每个请求在发出时生成唯一 ID，同时挂载一个 30 秒的超时定时器。响应到达时通过 ID 匹配对应的 pending Promise 并 resolve；超时未响应则 reject 并清理。这套机制保证了异步请求在并发场景下不会错乱，也不会因为 Go 侧无响应而无限等待。

流式数据解析。 stdout 的数据是流式到达的，单次 data 事件不一定对应完整的一行 JSON。processBuffer 方法负责处理这个问题：

// 关键逻辑：处理 stdout 缓冲区
private processBuffer(): void {
  const lines = this.buffer.split('\n');
  this.buffer = lines.pop() || ''; // 末尾不完整的部分留到下次处理

  for (const line of lines) {
    if (!line.trim()) continue;
    try {
      const response: SidecarResponse = JSON.parse(line);
      this.handleResponse(response); // 根据 ID resolve 对应的 Promise
    } catch {
      console.warn('[SidecarManager] 无法解析 stdout 行:', line);
    }
  }
}

每次 data 事件触发时，把新数据追加到内部 buffer，按换行符切分后逐行解析。末尾不完整的部分保留在 buffer 中等待后续数据补全，这样就正确处理了 JSON 对象跨多次 data 事件到达的情况。

---

四、当前进展与下一步

我们设计的IntelliGit跨进程通信与架构流转图如下：

目前 Renderer → Preload → Main → Sidecar 的完整链路已经打通，git/status 和 git/log 两个命令完成了端到端验证，通信机制运行稳定。

后续会在这套架构基础上推进两个较复杂的功能模块：

影子合并预检（Shadow Merge）：在用户执行实际 merge 之前，利用 Go Sidecar 在内存中模拟合并操作，提前检测潜在冲突并给出提示，而不需要修改工作区的任何文件。

语义化 Diff：不只是展示行级别的文本差异，而是结合代码结构（函数、类、模块边界）给出更有意义的变更描述，让 diff 结果对开发者更友好。

这两个功能依赖 go-git 对 Git 对象的内存级操作能力，也是引入 Go Sidecar 而非纯 Node.js 方案的核心价值所在。