团队项目第一次作业

项目	内容
这个作业属于哪个课程	计科24级78班（广东工业大学 - 计算机学院）
这个作业要求在哪里	团队项目第一次作业团队展示+选题报告+需求分析
这个作业的目标	为 GitManager 增加“解读项目”能力，让内置助手能读项目源码，并用可验收的需求文档写清前后端、工具层和安全边界。
团队名称	解码小队
团队成员学号-名字	3123006078-胡浩东、3124007003-陈广智、3124007607-石基业
项目源码	https://github.com/hhd233cored/GitManager
演示入口	`dotnet run --project src/GitManager.App`
一句话介绍	一个 Windows Git 客户端，内置助手能读项目源码，关键结论可点回文件和行号。
需求分析在线文档（飞书）	https://xcnmh25153q1.feishu.cn/wiki/LWe1wtt1Fit3MekVWYJc0skKnQf

团队项目第一次作业：GitManager——给 Git 助手加上读项目的能力

GitManager 是一个 Windows Git 客户端，已经能生成提交说明、解释提交和 Diff、分析同步差异，也能把变基、重置、撤销做成计划交给用户确认。它的助手读得到 Git 状态，读不到项目源码。本次作业增加四个只读项目工具，让助手能在当前工作区查看目录、搜索代码、按行读取源码，并把关键结论链接回具体行。

一、团队展示

1.1 队名与项目标志

队名：解码小队

项目名 GitManager

项目标志如下

1.2 团队项目的具体规划及描述

GitManager 是一个 Windows 桌面 Git 客户端，左侧 Changes、中间 History、右侧 Diff，助手侧栏可以收起。它能读仓库状态、历史和 Diff，能生成提交说明、解释提交/Diff、分析同步差异，并把同步、变基、重置、撤销做成计划交给用户确认；同一套工具通过本机 stdio MCP 开放给外部客户端。本次作业新增“解读项目”：项目概况、目录浏览、字面搜索、按行阅读和源码引用。

计划分三阶段：本次完成团队展示、选题报告和需求分析；第二阶段把解读能力做稳；第三阶段发布与答辩。解读项目已实现（提交 e9a24f9），有 8 组自动检查；下面写的工具、限制和验收标准都能在代码里找到对应。

1.3 队员风采

学号	姓名	本阶段负责	软件工程角色
3123006078	胡浩东	主要开发：整体架构、工具契约、项目读取、工具循环、MCP、联调	主开发 / 架构
3124007003	陈广智	文档与演示；协助助手侧栏、源码引用窗口的界面联调	文档 / 演示
3124007607	石基业	部署与测试；发布脚本、MCP 配置、示例仓库、路径问题排查	部署 / 测试

1.4 团队首次合照

1.5 团队项目的愿景（100 字左右）

我们希望 GitManager 成为开发者打开仓库后首先使用的工具：Git 操作安全完成，项目本身也能用自然语言问清楚。新成员不用先翻几十个文件，评审时关键结论能点回源码，危险操作仍然由人确认。

二、选题报告

2.1 选题背景：为什么让 Git 助手读项目

GitManager 的助手主要做两件事：解释 Git 状态，生成操作计划。查看现有的 9 个 MCP 工具可以发现，它们都围绕仓库状态、历史、Diff 和计划，没有一个能读源码。所以它能解释一次 Diff 改了什么，却说不清改动落在哪条调用链上；能列出变了的文件，却不能从入口读到实现。项目里已经有生成提交说明和 MCP 接入的实现，底层链路可用；本次作业补的是源码上下文。

2.2 真实调研：三个典型卡点

卡点	现有表现	用户想要	本次能力
解释提交缺少调用链	只读提交详情和关键 Diff	结合源码说明改动链路	概况 + 搜索 + 阅读
新人接手靠人带	不能浏览、搜索、读源码	打开仓库就能问入口和分层	目录 + 搜索 + 阅读
架构说明不可核对	通用模型能写但无法证明	关键结论点回文件和行号	引用 + 哈希 + 失效

联调中遇到过：同一提交改了 RepositoryTools 和 AssistantSession，现有助手只能分别复述 Diff，说不清调用链关系。需求来自现有工具清单、代码、组内试用和身边同学的非正式交流。

2.3 核心用户与现有方案

这套功能面向已经在用 Git、又经常要向别人解释代码的人：课程项目团队、刚接手仓库的新成员、做代码评审的开发者。

方案	能做什么	缺什么
GitHub Desktop	Git 操作稳定	不读源码，不解释项目
VS Code + Copilot / Cursor	能跨文件找代码	Git 操作与审批不是重点
现有 GitManager	Git 状态、Diff、操作计划、MCP	不能读源码

GitManager 要补的是把 Git 状态、项目源码、可回溯引用和人工审批放在同一个上下文里。

2.4 杀手级功能：读项目，回答能点回源码

本次新增四个只读工具，由模型决定何时调用。

工具	关键输入	返回	作用
`get_project_overview`	无	文件数、目录、扩展名、清单、README、citation	建立全局视图
`list_files`	目录、深度、分页	目录/文件分页、`nextSkip`	按目录浏览
`search_code`	1–300 字、目录、大小写	文件、行号、片段、hash、citation	找入口和调用点
`read_file`	文件、起止行	行号、文本、hash、`truncated`、`nextLine`	精读关键片段

例如问“解释一次助手提问从界面到工具调用的链路”，助手会先看概况，再搜索 AssistantSession，读取 AssistantSession.cs 第 1–80 行，最后给出带 [AssistantSession.cs:33](gitmanager-source://...) 的回答。

它和把代码直接粘给大模型有三点不同：读的是当前工作区，不用用户先挑片段；读取有预算（单文件 1 MB、单次搜索 3,000 文件 / 24 Mi 字符 / 25 秒），读不完会说明；每条结论带 citation 和 hash，点击引用会重新读取当前文件。

2.5 创新点

把 Git 上下文和源码上下文放在同一个会话，问“这次提交为什么改这里”时能顺着 Diff 找到被调用方。引用精确到行，文件变化时提示“文件已变化”。安全边界放在服务层，内置助手和 MCP 共用内容策略；模型也要知道预算有限，回答要说明未验证部分。

2.6 技术可行性与风险

GitManager 的助手、工具循环、MCP 和操作审批已经跑通；新增工具都是只读的，技术栈为 .NET 10 + WPF + Git CLI + Microsoft.Extensions.AI + 官方 MCP C# SDK。

风险	对策
大仓库读不完	分页、行范围、1 MB、搜索上限、概况缓存
模型编造	只引用已读取的 citation，说明未验证部分
敏感文件 / 路径逃逸	默认排除敏感路径，相对路径校验，拒绝链接目录，MCP 同策略

需要认真设计的是读取范围、读取对象、失败时的说明方式，以及读取结果的可验证性。

三、需求分析

3.1 文档迭代记录

版本	日期	修改内容	状态
V1.0	2026-11-06	项目概况与目录浏览：get_project_overview、list_files，先建立项目结构视图	已完成
V1.1	2026-11-07	代码搜索与按行阅读：search_code、read_file，返回行号、片段和内容哈希	已完成
V1.2	2026-11-08	源码引用与安全边界：citation/SHA256、内容策略、敏感路径与链接校验、MCP 复用；最终提交 e9a24f9	已提交

3.2 项目目标与范围

本阶段的目标是让“项目理解”成为 Git 客户端中一项可靠的能力，而不是只会聊天的附属窗口。

范围内	范围外
项目概况、目录、搜索、按行阅读；内置助手 + MCP；引用与内容策略	自动改代码/提交/测试；第三方 MCP；语义检索、调用图、Roslyn/LSP；任意历史版本

3.3 功能思维导图

GitManager · 解读项目
├── 入口：内置助手 / 外部 MCP
├── 工具：项目概况 / 目录 / 搜索 / 按行阅读
├── 回答：Markdown + 工具轨迹 + 源码引用
├── 安全：只读、路径校验、敏感文件过滤、内容开关
└── 预算：分页 / 截断 / 扫描上限 / SHA256 缓存

3.4 核心类图

classDiagram class AssistantViewModel { +SendAsync() } class AssistantSession { +RunAsync() } class RepositoryTools { +InvokeAsync() } class ProjectReader { +InvokeAsync() } class RepositoryContentPolicy { +Excludes() } class GitService AssistantViewModel --> AssistantSession : 发送问题 AssistantSession --> RepositoryTools : 调用工具 RepositoryTools *-- ProjectReader : 读取项目 RepositoryTools --> RepositoryContentPolicy : 应用策略 RepositoryTools --> GitService : Git 状态/Diff

3.5 功能清单与优先级

编号	功能	优先级	实现
F-01	项目概况	高	`get_project_overview`
F-02	目录浏览，每页 200 项	高	`list_files`
F-03	字面搜索，每页 100 处	高	`search_code`
F-04	按行阅读，每次 200 行 / 16,000 字符	高	`read_file`
F-05	引用、读取记录、内容策略、MCP 复用	高/中	`MarkdownView` / `RepositoryContentPolicy`

3.6 前端与后端功能需求

前端：助手侧栏可收起，回答按 Markdown 渲染；工具调用显示读取记录；引用可点击，在只读窗口显示行号和 SHA256；关闭内容共享后，内置助手和 MCP 同时受限。

后端层	职责
`GitManager.App`	侧栏、Markdown、引用窗口、设置、审批
`GitManager.Agent`	系统提示、工具注册、工具循环、预算、流式输出
`GitManager.Services` / `Core`	仓库上下文、项目读取、内容策略、Git 状态与 Diff

工具只读，没有 Shell 或任意 Git 命令入口；路径只允许仓库内相对路径，拒绝 ..、.git、绝对路径和链接目录；单文件最多 1 MB，不读二进制；API Key 存在 Windows 凭据管理器。

3.7 关键流程与异常边界

用户提问后，AssistantSession 把系统提示和工具定义发给模型；模型按需调用项目工具，结果带 citation 和 hash；模型只根据已读取结果回答。用户点击引用后，SourcePreviewWindow 重新读取当前文件，校验仓库身份和内容哈希，再显示只读内容。

异常 / 边界	系统行为
未打开或切换仓库	旧仓库 ID 失效，提示重新读取
内容共享关闭	项目工具和 Diff 报错，状态/历史仍可用
敏感路径、`../`、`.git`、链接目录	不进入清单，读取和搜索拒绝，Windows 上再校验句柄路径
超过 1 MB / 二进制 / 编码不符	拒绝读取，提示使用外部工具
搜索达到上限或超时	返回 `scanLimited` 或取消，提示缩小目录

3.8 验收标准

编号	验收操作	通过条件
A-01	问“介绍这个项目”	含文件数、目录、清单、README，片段有 citation
A-02	浏览 `src`，并读取某文件第 2–3 行	分页和 `nextSkip`；行号从 1 开始，返回 SHA256，超限时 `truncated`/`nextLine`
A-03	搜索 `LoginService` 和 `$(whoami);.*`	返回文件、行号、hash、citation；特殊字符 0 条，不执行命令、不按正则解释
A-04	读取 `.env`、`id_rsa`、`.ssh/`、`../README.md`，并创建仓库外 junction	全部拒绝或不出现在清单，搜索 0 条，不泄漏
A-05	关闭“允许共享仓库内容”	项目工具和 `get_diff` 报错，状态/历史仍可用
A-06	问“解释一次助手提问的调用链”，再点击引用	调用多个工具，回答含 `gitmanager-source://` 引用；只读窗口显示行号，文件变化提示，仓库切换后失效
A-07	外部 MCP 调用 `read_file` / `search_code`	与内置助手同策略，不能绕过内容开关

3.9 非功能需求与已知限制

性能上，项目读取不阻塞 Git 队列，最多 2 个并行读取；单次搜索 25 秒 / 3,000 文件 / 24 Mi 字符；缓存按 SHA256 失效。安全上，模型只有白名单工具，内置与 MCP 同策略；不持久化源码、对话或模型密钥。

目前不包含语义检索、调用图、Roslyn/LSP；只读当前工作区，不自动改代码或提交。

3.10 实现与演示

如图，让侧栏Git助手解释了这个项目，它给出了如图的解答。

四、小组分工

学号	姓名	本阶段负责	软件工程角色
3123006078	胡浩东	主要开发：整体架构、工具契约、项目读取、工具循环、MCP、联调	主开发 / 架构
3124007003	陈广智	文档与演示；协助助手侧栏、源码引用窗口的界面联调	文档 / 演示
3124007607	石基业	部署与测试；发布脚本、MCP 配置、示例仓库、路径问题排查	部署 / 测试

五、小组总结

本次作业的核心是给助手补上源码上下文。项目中的 Git 工具、MCP 和操作审批保留，新增项目读取、引用和安全边界。胡浩东负责主要开发，陈广智负责文档与演示，石基业负责部署与测试。

胡浩东：这次我承担主要开发，把“解读项目”接进工具循环。增加工具本身不难，难的是让内置助手和 MCP 遵守同一套边界：同一份内容策略、同一个仓库身份、同一套预算。

陈广智：我主要负责文档和演示，同时协助助手侧栏与源码引用窗口的界面联调。写需求文档和答辩材料时，要把工具行为、限制和验收标准写成别人能复现的步骤；演示时也要把“提问—读取记录—点击引用”这条链路讲清楚。

石基业：我主要负责部署和测试，同时处理发布脚本、MCP 配置和示例仓库。最初以为把 exe 发出去就结束了，实际发现路径里有中文或括号时 MCP 启动会出问题，发布包还依赖 .NET 10 和 Git；后来把这些都写进了部署说明和测试项。

posted on 2026-11-08 20:04 woshi314 阅读(19) 评论(0) 收藏举报

刷新页面返回顶部

woshi314