构建一个能说会做的智能体

这个作业属于哪个课程	https://edu.cnblogs.com/campus/gdgy/Class78-Grade2024-CS
这个作业要求在哪里	https://edu.cnblogs.com/campus/gdgy/Class78-Grade2024-CS/homework/16761
这个作业的目标	使用现代 AI 工具（MCP 框架）构建一个既能自然语言对话、又能调用工具执行操作的智能体，并借助它为大项目的"智能体"能力打基础
学号	3123006078 胡浩东、3124007003 陈广智、3124007607 石基业
仓库地址	https://github.com/hhd233cored/GitManager

构建一个「会说也会做」的 Git 管理智能体

小组：3123006078 胡浩东、3124007003 陈广智、3124007607 石基业
项目：GitManager —— 基于 WPF + .NET 10 + Git CLI 的 Windows Git 桌面客户端

一、需求描述

在日常开发中，git 命令的分支、同步、重置、变基等操作门槛高、易出错；而开发者又经常需要"解释这段 Diff 在干什么""帮我根据改动写一条提交说明""这次 Fetch 之后本地和远程到底差在哪"。这些需求天然适合交给一个能理解自然语言、又能真正执行 Git 操作的智能体。

因此我们设计了一个能够管理Git的工具 GitManager ，并落地智能体能力，让它成为项目内置的「Git 助手」，需求如下：

1. 能说：支持多轮自然语言对话，理解开发者意图，并用中文解释提交、Diff、同步差异。
2. 会做：能够调用白名单工具读取仓库状态、历史、Diff，并为同步、变基、重置、撤销等操作生成可执行计划。
3. 安全可控：模型只拥有白名单工具，没有任意 Shell / 任意 git 命令入口；真正的写操作必须由用户在界面预览并确认后才能执行。
4. 可对外复用：通过 MCP（Model Context Protocol） 暴露同一套工具，让外部 MCP 客户端（如 OpenCode、各类 IDE 助手）也能读取当前仓库、提出操作计划。
5. 加分项：多轮对话记忆、外部 API / 本机模型接入、简洁前端（WPF 侧栏界面）。

二、业务流描述

2.1 内置助手（会说 + 会做）

flowchart TD A["用户输入<br/>解释提交 / 生成提交说明 / 同步分析 / 自由提问"] --> B["WPF 助手侧栏<br/>预设数据：勾选文件 Diff / 当前提交 / 上游差异"] B --> C["GitManager.Agent<br/>工具循环 · 上下文预算 · 流式输出"] C --> D["RepositoryCoordinator + RepositoryTools<br/>白名单工具 · 操作计划"] D -- "读" --> E["预览 / 校验 / 恢复点 / GitService → Git CLI"] D -- "写操作" --> F["生成操作计划"] F --> G["用户在界面查看预览并确认"] G --> E

说明：用户 → 助手侧栏 → Agent 工具循环 → 共享工具层读取或生成计划 → 用户审批后才由 GitService 执行。

关键业务流：

• 提交说明：程序先读取勾选文件的工作区 Diff（最多 12 个文件），交给模型生成草稿；用户查看后点击"填入提交区"，不自动提交。
• 解释提交 / 解释 Diff：读取所选提交的说明、统计与关键文件 Diff，用自然语言解释。
• 同步分析：先 Fetch，再比较当前分支与上游，分析不会自动 Pull / Push。
• 描述 Git 操作（会做）：模型可生成 sync / rebase / reset_soft|mixed|hard / revert 等操作计划，界面显示计划卡片 → 用户点击"查看预览" → 明确确认后由 GitService 执行，执行前复用已有恢复点。

2.2 外部 MCP 客户端

flowchart LR C["外部 MCP 客户端<br/>Claude Desktop / IDE"] --> M["stdio MCP 进程<br/>GitManager.Mcp.exe"] M --> P["本机命名管道"] P --> G["运行中的 GitManager<br/>与 UI、内置助手共用同一操作队列"]

说明：外部客户端 → stdio MCP 进程 → 本机管道 → 运行中的 GitManager，不另起 Git 实例。

• 客户端先调用 get_active_repository 拿到不透明仓库 ID，后续调用携带该 ID；切换仓库/分支后旧 ID 失效。
• MCP 服务只是桥接到运行中的 GitManager，不另起 Git 实例，与 UI、内置助手共用同一个仓库操作队列。
• apply_operation_plan 只把计划转为"等待界面审批"，不直接执行写操作。

三、实现说明

3.1 技术栈与分层

层	项目	职责
界面	GitManager.App	WPF 侧栏、设置、凭据管理、计划审批、草稿填入、冲突窗口
智能体	GitManager.Agent	模型适配、工具循环、上下文预算、流式输出、草稿生成
共享服务	GitManager.Services	调度、工具定义、计划、本机通信（不依赖模型供应商与 WPF）
MCP 服务端	GitManager.Mcp	独立 stdio 进程，桥接到运行中的 GitManager
核心	GitManager.Core	GitService、GraphLayout、DiffParser 等 Git 与图布局逻辑

AI 侧采用 Microsoft.Extensions.AI + 官方 OpenAI .NET 适配器，MCP 采用 官方 C# SDK，兼容任意支持 Chat Completions 与工具调用的 OpenAI 兼容服务（云端或 Ollama / LM Studio 等本机服务）。

3.2 MCP 工具清单（白名单）

工具	功能
get_active_repository	当前开放的仓库及 ID
get_repository_status	分支、状态、冲突及缓存同步信息（≤200 文件）
get_commit_history	当前分支历史，支持分页，不返回作者邮箱
get_commit_details	指定 SHA 的提交、统计与文件列表
get_diff	相对路径 Diff，可选提交或工作区暂存内容
get_sync_analysis	可选先 Fetch，否则明确标为缓存
create_operation_plan	返回计划 ID、固定 SHA 与具体影响
apply_operation_plan	转为等待界面审批，不执行写操作
get_operation_status	查询计划等待/完成/失败/失效/冲突等状态

3.3 安全与恢复设计

• 最小权限：模型只有白名单工具，没有通用 Shell 或任意 Git 命令入口；仓库内容与工具结果只视为数据，不代表操作授权。
• 人审执行：写操作需用户在具体预览中点击执行，覆盖历史还需勾选确认；计划 15 分钟后失效，重启后旧 ID 无效。
• 恢复点：变基、合并、撤销前自动保存未提交改动，完成或中止后恢复，冲突复用既有冲突处理窗口。
• 密钥安全：API Key 按服务地址分别存入 Windows 凭据管理器，不写入 settings.json / assistant.json；常见密钥路径（.env、私钥、证书等）不向助手提供内容。

3.4 加分项实现

• 多轮对话记忆：对话保留在本次应用会话中，按仓库/分支切换清空，避免上下文串味。
• 外部 API / 本机模型：支持自定义 OpenAI 兼容服务与本机模型接入，连接测试发送一次简短请求。
• 前端界面：WPF 可收起的助手侧栏，支持流式回答、停止、计划卡片、草稿填入。

四、使用示例（功能演示）

演示：一句话生成提交说明

采用内置 Git 助手，完整流程如下:

1. 打开仓库：在 GitManager 中打开目标仓库，左侧 Changes 面板勾选本次要提交的改动文件。
2. 点击助手：点击右上角「助手」按钮，展开侧栏，请求助手说明提交。

3. 读取 Diff：助手先由程序读取勾选文件的全部工作区 Diff（最多 12 个，未读取或截断的文件会在卡片上标注），再交给模型。
4. 流式生成草稿：模型在预算内流式输出，生成一张草稿卡片——一行 Summary + 分点 Description。
5. 用户编辑提交：用户查看后点击「填入提交区」，把草稿填入 Summary / Description，必须自己编辑并点击提交，助手不会替你提交。

演示：opencode 通过 MCP 零代码接入

GitManager 通过 MCP 暴露工具，任意支持 MCP 的客户端都能直接接入。以 opencode 为例，在项目根 opencode.json 配置本机 MCP：

{
  "mcp": {
    "gitmanager": {
      "type": "local",
      "command": ["C:\\path\\to\\mcp\\GitManager.Mcp.exe"],
      "enabled": true
    }
  }
}

GitManager 保持运行并打开目标仓库后，在 opencode 对话里说「帮我看下当前仓库勾选了哪些改动，生成一份中文提交说明」。opencode 会自动调用 get_active_repository → get_repository_status → get_diff 读取改动，再产出草稿，整个接入无需一行代码。

五、小组分工

学号	姓名	分工
3123006078	胡浩东	整体架构设计、核心 Git 服务、对话循环、MCP 服务端、联调
3124007003	陈广智	助手侧栏界面与Markdown 渲染、AI连接设置、文档与演示
3124007607	石基业	操作确认/预览、Stash 与恢复点、冲突处理、外部通信桥接、项目测试与验证

六、小组成员心得

3123006078 胡浩东

这次作业我作为负责人先定下整体架构，再把它拆成几个能独立做的小块交给组员。核心难点在对话循环：怎么让模型先想清楚再调用工具、读到真实状态，中间还要控制上下文预算、安全保障等。把对话界面、连接设置等模块交给组员之后，我更专注在接口边界和联调上，也更体会到分工清楚的效率比单人开发更高。

3124007003 陈广智

这次作业让我认识到，一个能演示的智能体不仅需要后端能跑，还需要好用方便的对话界面和清晰的连接配置。做助手侧栏时，我需要完成消息呈现、连接设置与测试、界面自检这些模块。验证中我也体会到智能体输出有不确定性，测试流程与传统软件不同，需要另行设计。

3124007607 石基业

本次作业使我学到了，智能体不仅需要强大的工具调用能力，还需将危险操作交给人工确认。在完成操作确认与通信接入时，我需要将操作预览、重置、变基、撤销与恢复等操作的确认界面，以及程序与外部客户端之间的通信链路贯通，使外部请求仅能先提交计划，并最终由人在界面中确认后执行。联调过程中，我也体会到安全性与易用性之间需反复权衡。