开始做这个项目之前，我们花了不少时间想一个问题：实训项目到底做什么才有意义？

堆功能？拼技术栈？还是找个听起来高大上的方向凑数？最后我们绕回了一个最朴素的出发点——找一个自己真实遇到过的问题，认认真真做一个能解决它的工具。

于是有了 IntelliGit。

---

一、为什么是 Git 客户端？

Git 是每个开发者绕不开的工具，但说实话，它的使用体验并不友好。

命令行操作对新人来说门槛不低，rebase、cherry-pick、stash 这些操作背后的逻辑如果没搞清楚，敲错一条命令可能就把提交历史搞得一团糟。更麻烦的是，Windows 和 macOS/Linux 之间还存在各种环境兼容性问题，路径分隔符、换行符、权限模型……每个坑踩过才知道有多烦。

市面上当然有成熟的 Git GUI 工具，比如 Sourcetree、GitKraken，但要么太重，启动慢功能多却不常用；要么对新人不够友好，界面复杂反而增加了理解成本。

所以我们想做一个轻量、跨平台、上手成本低的 Git 桌面客户端——不是要替代命令行，而是给那些还没完全掌握 Git 的开发者一个更顺手的过渡工具，同时保留足够的扩展空间，让有经验的开发者也能用得舒服。

定位清楚了，目标就具体了：

• 降低门槛：用可视化交互覆盖高频 Git 操作，减少死记命令的负担
• 跨平台：Windows、macOS、Linux 三端都能跑，不能因为系统不同就体验割裂
• 轻量：启动快、运行流畅，不堆没用的功能
• 留好扩展口：Git 钩子、自定义脚本这类进阶需求，架构上先把位置留出来

---

二、技术选型：不追新，选合适的

选型过程我们讨论了挺久，核心原则只有一条：技术服务于需求，而不是需求迁就技术。

主框架：Electron + React + TypeScript

跨平台桌面应用，Electron 几乎是绕不开的选择。基于 Chromium 和 Node.js，前端那套东西可以直接复用，主进程又能做系统级的事情——文件操作、进程管理、窗口控制，这些在纯前端里做不了的，Electron 都能接住。

UI 层选了 React，组件化开发对于一个交互比较复杂的工具类应用来说维护起来省心很多。TypeScript 则是为了项目规模大了之后不翻车——静态类型在多人协作时能帮你在编译阶段拦住很多低级错误，比上线后 debug 要省力得多。

高性能部分：Go Sidecar

Git 命令执行、文件系统读写这类操作，对响应速度很敏感。如果全塞在 Electron 主进程里，Node.js 的性能上限会成为瓶颈。

我们的方案是引入一个 Go 写的侧车服务（Sidecar）——Go 是编译型语言，执行效率高，跨平台编译也很方便，通过 IPC 和 Electron 主进程通信，把性能敏感的操作卸载到 Go 这边处理。这个思路在一些成熟的桌面工具里也有类似实践，并不算冒险。

工程化工具链

团队协作最怕的就是"代码风格战争"——每个人习惯不一样，PR 里净是格式改动。所以工程化这块我们从一开始就配齐了：

• .editorconfig 统一编辑器基础行为
• ESLint + Prettier 管代码规范和格式化，自动处理，不靠自觉
• 构建工具选了 electron-vite 而不是传统 webpack，热更新速度快很多，开发体验有明显提升
• 打包用 electron-builder，多平台一键出包，省去手动处理各平台差异的麻烦

依赖管理上前端走 npm，Go 侧车走 go.mod，各管各的，互不干扰。

目录结构

架构设计上遵循一个原则：让每个模块只做自己该做的事。

IntelliGit/
├── src/
│   ├── main/        # Electron主进程：系统交互、窗口、IPC
│   ├── preload/     # 主/渲染进程通信桥接，安全暴露API
│   ├── renderer/    # React渲染进程：前端界面
│   └── shared/      # 前后端共享的类型定义和工具函数
├── sidecar/         # Go侧服务
├── resources/       # 图标、静态资源
└── docs/            # 需求文档、设计文档

界面、系统交互、高性能计算三层分离，改一块不会牵连另一块，后续迭代的成本会低很多。

---

三、需求文档：把模糊的想法变成具体的细节

技术架构定完，我们做了一件很多项目会忽略的事：认真写需求文档。

不是走过场，而是真的把每个功能逼到足够具体——不写清楚，开发阶段一定会返工。

需求分层：先做什么，后做什么

我们把所有需求分成两层：

核心需求，必须完成，包括仓库管理（新建/克隆/切换）、基础 Git 操作（add/commit/push/pull/branch/merge）、提交历史可视化、文件差异对比等高频功能。

拓展需求，视进度决定，比如 Git 钩子配置、自定义快捷键、脚本集成等。标注优先级，不盲目扩展，避免前期铺太大最后核心功能没做好。

把每个功能写到操作步骤级别

以"新建 Git 仓库"为例，光写"支持新建仓库"是不够的，需求文档里要写清楚：

• 怎么触发：点击界面上的"新建仓库"按钮
• 完整交互流程：弹出路径选择窗口 → 输入仓库名 → 确认 → 调用 git init → 返回结果 → 刷新仓库列表
• 异常场景怎么处理：路径已存在仓库怎么提示、权限不足怎么提示、路径为空怎么处理
• 跨平台差异：Windows 的路径分隔符和 macOS/Linux 不一样，这里要明确兼容方案

这样写完，开发的时候才不会边做边猜"这个场景应该怎么处理"。

验收标准要可以被验证

每个需求都要有验收条件，而且条件要能被真实测试。比如"克隆仓库"功能的验收标准：

• 支持输入远程仓库 URL 和本地保存路径
• 克隆过程展示进度
• 失败时给出具体错误信息（网络异常和 URL 格式错误要区分提示）
• 克隆完成后自动加载仓库并出现在列表里

这种粒度的验收标准写出来，测试阶段才有据可依，不会出现"功能上了但是不知道算不算完成"的尴尬。

---

四、写在开发开始之前

回头看这段前期工作，我们花在"想清楚"上的时间，大概比动手写代码的时间还多。

但这值得。

选题、架构、需求文档，每一步都是在缩小后续的不确定性。技术选型讨论时多说一句"这个方案在 Windows 上有没有坑"，比上线前才发现兼容性问题要轻松得多。需求文档里多写一个异常场景，比开发一半才想到要好处理得多。

接下来进入正式开发阶段，计划先把基础工程跑通——环境搭建、主进程与渲染进程的通信链路、Go 侧车服务的调通——再逐步落地各功能模块。

文档里的需求变成真正能跑的应用，这个过程才刚刚开始。