一、写在收尾时

这是 IntelliGit 系列博客的最后一篇。前面几篇分别记录了 Sidecar 通信链路的打通、前端页面从设计稿到可交互界面的落地、Agent 框架的搭建，以及自然语言助手作为第一个 P1 工作流的端到端实现。项目推进到现在，三个 P1 工作流和影子合并预检都已经完成，整体功能已经达到可以提交的状态，接下来不再新增功能，这篇总结一下整个项目最终落地的样子，以及过程中留下的一些经验。

最初立项时想解决的问题很明确：市面上主流的 Git 图形化工具本质上是命令的图形封装，提交信息质量低、冲突只能在操作失败后才发现、新手很容易在不清楚后果的情况下触发不可逆操作。IntelliGit 想做的事情是在保留完整 Git 操作能力的基础上，叠加语义理解、AI 辅助决策和自然语言交互，把客户端从单纯的命令执行器往"智能开发助手"的方向推进一步。现在这三个方向基本都落地了。

二、最终的系统形态

IntelliGit 维持了立项时确定的三层进程架构：Renderer 进程负责 UI 渲染、状态管理和 AST 分析；Main 进程负责 IPC 调度、LLM Agent 执行和 Sidecar 生命周期管理；Go 编写的 Sidecar 进程统一处理本地 Git 读写和远程网络操作，与 Main 进程之间通过 stdin/stdout 上的 JSON-RPC 2.0 协议通信，消息按 NDJSON 格式分帧，请求和响应靠唯一 ID 配对，支持超时控制，进程异常退出时有指数退避的自动重启机制。这套架构在项目早期就确定了，后续的开发基本没有偏离这个骨架，新增能力都是在三层职责边界内做扩展，没有出现因为架构选错而推倒重来的情况。

Sidecar 这一侧最终实现了 60 多个 JSON-RPC 命令，覆盖仓库管理、暂存区操作、提交、分支、远程同步、合并冲突、差异计算七个领域，全部基于 go-git 实现，不依赖宿主机安装的 git 可执行文件。前端则搭建起了完整的五视图框架：变更工作区、历史与分支、风险管控（冲突面板）、NLP 命令中心，加上设置页面，统一套在一个三栏式的 AppShell 骨架里——左侧活动栏导航、中间主内容区、底部状态栏常驻展示引擎和 AI 服务的连接状态。

三、智能化能力的三块拼图

需求文档里定义的智能化特性分三块：AI 辅助提交、冲突智能管控、自然语言 Git 操作。这三块工作量最大，也是项目区别于传统 Git 客户端的核心价值所在。

AI 智能提交这条链路从暂存区 diff 出发，先做语义意图分组——把变更文件按 feat / fix / refactor / style / docs / test / chore 归类，每组带置信度评分和 AST 摘要；分组结果支持按组精确暂存，只把对应意图的 hunk 送入暂存区，不会把无关改动混进同一次提交；提交信息生成则结合 staged diff 和 AST 符号变更摘要，调用 LLM 生成符合 Conventional Commits 规范的 message。这套流程背后是四层架构——UI 状态、提交动作封装、业务流程编排、AI/fallback 抽象层，分得比较细，主要是为了让 LLM 调用的细节和上层交互解耦，LLM 不可用时能整体降级为基于路径的规则模板，不会让提交功能直接卡死。

冲突处理这一块走得最远的是影子合并预检。在用户真正点击合并之前，系统用 git merge-tree 做一次只读的三路合并模拟，全程不接触工作区、暂存区和任何引用，纯粹是计算一次结果。预检结果会实时显示在分支列表上，每个分支末尾的风险徽章用颜色区分——绿色可以安全合并，蓝色可以快进，红色存在冲突。冲突真正发生之后，面板会通过 Git index 里的三个 stage 读取 ancestor / ours / theirs 的原始内容，搭配 AST 分析识别语义级的风险（调用-删除冲突、签名变更冲突、语义覆盖冲突、类型不兼容冲突），AI 给出修复建议，规则化降级兜底保证 LLM 不可用时也有基本可用的策略。整套流程从选择目标分支发起合并，到冲突解决、暂存、完成合并提交，都收在同一个面板里，不需要在多个页面间切换。

自然语言助手则是把前两块能力包了一层口语化的入口。用户输入一句话描述想做的操作，LLM 解析成结构化的操作计划，每一步标注风险等级，safe 级直接执行，high 级需要二次确认，extreme 级默认拦截。执行结果会再交给 LLM 转写成一句自然语言回复，而不是甩给用户原始的命令输出。这条链路还支持多轮追问，对话历史按仓库隔离存储，切换仓库时不会串台。

支撑这三块能力的是底层的 AST 多语言语义分析框架，TypeScript / JavaScript 用 Babel Parser 精细解析，Python / Go / Java / C / C++ 用 web-tree-sitter 按需加载对应语言的 WASM grammar。核心能力是把 Git Diff 的每个 Hunk 通过行范围映射到对应的 AST 节点，识别变更属于新增、删除、函数体修改、参数签名修改还是返回类型修改，再以一定的置信度输出。这一层的分析结果同时供智能提交和冲突管控两个工作流复用，是这两条链路能做到"语义级"而不只是"文本级"的关键支撑。

四、LLM 接入层的几次调整

整个项目里 LLM 接入层经历的变动比较多，值得单独说一下。最早的版本完全跑在 Renderer 进程里，用手写的 fetch 客户端直接调用 LLM API；后来因为 CSP/CORS 限制和 API Key 不该留在 Renderer 里这两个问题，把整个执行层迁移到了 Main 进程，同时引入 Vercel AI SDK 替换掉手写客户端，顺带获得了开箱即用的多轮 tool call 支持。迁移过程中踩到的两个坑——连接测试机制本身设计得不合理、以及 SDK 版本升级导致 OpenAI 兼容接口默认路由错误——在之前的博客里都记录过，这里不重复。

最终落地的 LLM 框架支持 Anthropic 和任意 OpenAI 兼容接口（覆盖 DeepSeek、通义千问等国内服务和本地部署模型），统一的 runAgentTask 入口根据配置动态选择 SDK，工具调用支持十几个 Git 工具供 LLM 直接调用，多轮对话按仓库隔离，30 秒超时控制，连通性测试不消耗实际 token。这套设计让后续接入新的模型 Provider 基本不需要改动业务代码，只是配置层的事。

五、工程规模

代码结构上始终维持着一套约束相对严格的分层规范——视图、布局、组件只通过 viewModel 消费 store，不允许在业务代码里直接调用底层 IPC 接口，CSS 用 CSS Modules 做隔离，每个主要目录配一份说明职责边界的 README。这套规则在项目早期就立下来了，中后期多人并行开发的时候，这套边界基本起到了应有的作用——没有出现大范围的相互踩踏或者职责混乱。类型系统这一侧，60 多个 Git 命令的输入输出类型做了完整映射，跨进程通信基本消除了无约束的类型断言。

也有一些原计划没有做完的部分，诚实地记录一下。C/C++ 的 AST 符号提取框架搭起来了，但完整度大概在七成左右。本地 RAG 知识库——把项目历史 commit 向量化、检索增强生成——完全没有动工，主要顾虑是本地 Embedding 模型和向量数据库在跨平台打包上的复杂度，权衡之后放在了后续计划里。Docker 沙箱质量验证、结构化错误码体系、文件日志系统这几项也都停留在规划阶段。

六、收尾的几点感受

回头看这个项目，几个阶段的工作性质其实差别很大：早期是搭骨架、打通跨进程通信，中期是把页面从设计稿落到可交互组件，后期则是把"智能"这件事真正嵌入到提交、冲突、自然语言这几条具体的工作流里。每个阶段遇到的问题类型也不太一样——前期更多是协议设计和类型契约的问题，中期是状态管理和组件拆分的问题，后期则更多是 LLM 输出的不确定性带来的解析容错问题，以及 SDK 升级带来的隐性 breaking change。

比较明显的一个体会是，"P0 底座先行、P1 工作流复用底座能力"这套任务结构在多人协作下确实起到了作用——Agent 框架和底层 Git 数据能力作为两个并行的 P0，让三个 P1 工作流可以各自独立推进，不需要互相等待，也避免了几个方向同时改一层代码导致的冲突。代价是 P0 阶段本身的设计需要更谨慎一些，类型契约、Schema、降级策略这些东西一旦定下来，后面所有 P1 工作流都会依赖它，改起来的成本比单纯的业务代码改动要高。