# GITX AI 亮点介绍

GITX 的 AI 亮点不在于简单调用大模型回答 Git 问题，而在于把 AI Agent 工程化地嵌入开发者命令行工作流：模型需要理解当前 Git 命令、真实执行结果、仓库状态、团队飞书知识和用户授权边界，再决定何时解释、何时检索、何时建议、何时调用工具。

## 使用的高阶 AI 技巧

### 1. 命令生命周期驱动的 Agent 介入

项目没有把 AI 做成一个独立聊天框，而是按照 Git 命令生命周期设计多个阶段：

- `beforeRun`：命令执行前，帮助用户理解命令、检查风险、生成 commit message 建议。
- `afterFail`：命令失败后，读取真实 `exitCode`、`stdout`、`stderr`，解释错误并给出修复命令。
- `afterSuccess`：命令成功后，给出下一步协作建议，但保持只读。
- `chat`：用户通过 `/chat` 明确授权后，再处理飞书写入、发消息、预约会议或更新多维表格。

这种设计让 AI 不再是被动问答，而是成为工作流中的阶段性协作者。

### 2. 双 Agent 分工

项目将 AI 能力拆成两个角色：

- Linus：专注 Git 工作流，负责命令理解、错误诊断、提交建议、终端输出和下一步命令推荐。
- Friday：专注飞书协作，负责飞书授权、文档检索、开发记录写入、消息发送、会议预约和多维表格更新。

这种分工带来两个好处：

- 能力边界更清晰：Git 判断和飞书操作不会混在一个无限权限 Agent 中。
- 权限更可控：Linus 需要飞书上下文时只能通过受控 action 请求 Friday，不能直接执行底层 lark-cli。

### 3. Skill 路由与任务约束

项目把不同任务沉淀为本地 Skill，并由系统固定路由：

- 命令帮助对应 `command-help`。
- 提交信息生成对应 `command-git-commit-message`。
- 失败诊断对应 `command-after-fail`。
- 成功后建议对应 `command-after-success`。
- 自由协作请求对应 `command-chat`。
- 飞书侧动作对应 `lark-doc-lookup`、`lark-im`、`lark-calendar`、`lark-base`、`lark-doc-write` 等。

Agent 不能自由选择 Skill，也不能接受用户任意传入的工具参数。这让 AI 行为从“靠 prompt 约束”升级为“由任务包、Skill、工具 schema 共同约束”。

### 4. 工具调用编排

GITX 使用 LangChain `createAgent` 组织模型和工具调用，并将工具能力拆成可组合模块：

- `tldr_git_manual`：查询 Git 命令快速手册。
- `git_commit_context`：读取 staged diff、branch、status 等提交上下文。
- `git_repository_context`：读取当前仓库、分支、远端和工作区状态。
- `interact_with_lark_agent`：让 Linus 以受控 action 请求 Friday 读取或写入飞书侧信息。
- `run_lark_cli`：由 Friday 封装 lark-cli 调用，并捕获 stdout、stderr、exitCode。
- `final_response`：强制最终输出走结构化工具，避免普通 assistant 文本失控。

工具调用过程会回传进度，TUI 可以展示 Agent 正在查询手册、读取上下文或调用飞书能力。

### 5. 结构化输出与安全校验

项目对 Agent 输出做了结构化约束：

- 最终结果必须包含 `content`。
- 可选的 `suggestedCommand` 必须是一条完整、可执行、相对安全的命令。
- 未知字段、补充 lookup、私自 follow-up action 等会被拒绝。
- 输出需要适合终端阅读，避免复杂 Markdown、表格、链接语法和控制字符。

这让模型输出可以被 TUI 稳定消费，也降低了误导用户执行危险命令的概率。

### 6. 项目级记忆与上下文压缩

项目支持 `.gitx/memory.json`，用于保存长期有价值的信息：

- 团队提交规范。
- 排障经验摘要。
- 项目资料索引。
- 用户工作流偏好。

同时，Agent 运行时支持历史保存、上下文压缩和 context/token 使用统计。实时 Git 状态仍以本次命令上下文为准，长期记忆只作为辅助参考，避免把过期 stdout、stderr 或 git status 当成当前事实。

### 7. 基于历史失败模式的个性化辅助

项目已经实现 Git 命令历史画像：系统会按归一化后的同类 Git 命令记录连续成功次数、最近失败记录、失败次数、退出码和当时的 `stdout`/`stderr`。这些信息会作为 `gitStats` 注入命令侧 Agent 上下文。

这让 AI 能识别用户是否反复卡在同一类问题上，例如多次 `git push` 因 upstream 缺失失败，或多次 `git commit` 被提交规范拦截。相比只看当前一次报错，Agent 可以给出更个性化的解释和学习建议：新手常见问题会讲清原因和下一步，已经多次成功的命令则可以减少重复打扰。

## 人和 AI 的分工

GITX 的人机分工遵循一个核心原则：AI 负责理解、检索、建议和编排；人负责最终授权和关键动作确认。

### 用户负责

- 输入真实 Git 命令。
- 决定是否按 Tab 请求命令前帮助。
- 判断是否接受 AI 推荐的下一步命令。
- 对飞书写入、发送消息、预约会议、更新看板等敏感动作进行明确授权。
- 在冲突解决等需要业务判断的场景中完成最终代码选择。

### AI 负责

- 读取命令、参数、仓库状态、历史失败记录和命令输出。
- 结合用户同类 Git 命令的成功/失败画像，判断是否需要更基础的解释、重复错误提醒或更直接的下一步建议。
- 判断错误类型：通用 Git 用法问题、仓库状态问题、远端/upstream 问题或团队流程问题。
- 选择工具：简单错误查 tldr，复杂协作问题再查询飞书团队资料。
- 生成短、准、可执行的终端建议。
- 在用户明确授权后，编排飞书文档、消息、会议、多维表格等协作动作。

### 安全边界

项目特意把 `afterSuccess` 设计为只读阶段。即使 push 成功后系统知道应该写开发记录或通知 reviewer，也只会建议用户通过 `/chat` 手动触发，不会自动写飞书或发消息。

这让 AI 能主动提醒，但不会替用户越权执行团队协作动作。

## 核心模型选型思路

项目的模型选型不是简单固定一个模型，而是按角色和任务复杂度预留了分层配置：

- 默认模型通过 `MODEL` 配置，用于通用 Agent 能力。在本次比赛的demo展示中使用了 豆包2.0 Pro。
- 命令侧模型可通过 `COMMAND_MODEL` 配置，重点优化 Git 判断、短文本建议和终端输出稳定性。
- 飞书侧模型可通过 `LARK_MODEL` 配置，重点优化工具调用、文档检索结果理解和企业协作动作规划。

选型思路上，GITX 更看重以下能力：

- 工具调用稳定性：能准确选择工具，并按 schema 输出参数。
- 短上下文决策能力：能在命令、stderr、仓库状态和团队规则之间做判断。
- 结构化输出可靠性：能稳定返回 `content` 和 `suggestedCommand`。
- 中文终端表达能力：输出要简短、准确、可执行，适合开发者现场阅读。
- 成本与延迟可控：命令行场景要求响应快，不能每次都做过重检索。

## 引入 AI 后对原有工作流的改变

### 从“报错后搜索”变成“报错后即时诊断”

传统流程是 Git 报错后复制错误信息搜索、翻文档、问同事。GITX 让系统在失败后自动拿到真实命令结果，直接解释原因并给出下一步命令。

### 从“团队规范靠记忆”变成“规范进入命令现场”

提交规范、分支规范、排障手册原本在飞书文档中，需要开发者主动查找。GITX 让这些知识可以在 commit、push、merge 等关键节点被即时引用。

### 从“协作动作事后补”变成“成功后自然提醒”

push 成功后，系统会提醒开发者写开发记录、通知 reviewer、更新需求状态或安排 review 会议，让团队协作不再完全依赖人工记忆。

### 从“AI 直接替人做事”变成“AI 建议 + 人授权”

GITX 没有让 AI 在成功后自动写文档或发消息，而是把敏感动作放到 `/chat` 明确授权阶段。这种设计更适合企业协作环境，也更容易被团队接受。

### 从“所有人收到同样提示”变成“基于历史卡点的个性化帮助”

传统 Git 帮助通常只根据当前命令输出固定说明。GITX 会把同类命令的连续成功次数和最近失败模式带入 Agent 上下文，让 AI 能区分“第一次遇到的新手错误”和“反复出现的同类卡点”，从而提供更贴近用户当前水平的 Git 学习建议。

## AI 工程化落地价值

GITX 的 AI 工程化价值体现在三个层面：

- 对开发者：减少 Git 排障时间，提高新人独立解决问题的能力。
- 对团队：把知识库、协作规范和看板流转接入日常开发动作，减少信息断层。
- 对工程体系：沉淀了可扩展的 Agent 分工、Skill 路由、工具 schema、结构化输出、长期记忆、历史失败画像和实验评估框架。