代码理解 Agent + API 文档生成（MCP 实践)

AI工程实践手记
,
loading...

用 Go 写了两个小工具：代码理解 Agent + API 文档生成（MCP 实践）

最近在学习两个东西：

  • Agent（尤其是 ReAct 模式）
  • MCP（Model Context Protocol）

顺手做了两个小项目，一个“代码理解”，一个“接口结构化”，记录一下。

📦 项目地址

👉 CodeSense（代码理解 Agent）
https://github.com/yuhua2000/codesense

👉 api-registry-mcp（API 注册与文档生成）
https://github.com/yuhua2000/api-registry-mcp

一、CodeSense：一个简单的代码理解 Agent

🧠 是干嘛的？

一句话：

用 AI 自动分析代码仓库，并生成结构化总结报告

输入一个代码路径，它会自动：

  • 分析项目结构
  • 识别核心模块
  • 提取关键方法
  • 输出 Markdown 报告

⚙️ 核心思路：ReAct

核心不是“分析代码”，而是这个循环：

1
思考（Reasoning） → 执行（Acting） → 再思考 → 再执行

具体就是：

  1. AI 决定下一步做什么（看 README？看 main？）
  2. 调用本地工具（读文件 / 列目录）
  3. 再分析
  4. 循环，直到能输出结果

🔧 做了哪些东西？

1️⃣ 分析 Agent

  • 不全量扫描代码（控制成本）

  • 优先读关键文件：

    • README
    • 依赖文件
    • 入口代码

  • 动态决定分析路径

2️⃣ 上下文压缩（关键）

  • 多轮分析 → 压缩 → 再分析
  • 避免上下文爆炸
  • 保证最终输出稳定

3️⃣ 报告生成

输出 Markdown，包含：

  • 项目概述
  • 模块划分
  • 包职责
  • 技术架构
  • 关键方法调用关系

🏗️ 技术实现

  • Go
  • openai-go
  • CLI + Prompt驱动
  • ReAct + 多轮压缩

🤔 这个项目解决什么问题？

一个很现实的问题：

看一个陌生仓库，很花时间

这个工具的目标是：

帮你快速建立“第一印象”

不追求 100% 准确，但要：

  • 快
  • 有结构
  • 能用

二、api-registry-mcp：API 注册与文档生成（MCP 实践）

这个项目是学习 MCP 时做的一个小工具。

🧠 是干嘛的？

一句话：

把代码里的 API 结构提取出来，并生成文档

⚙️ 实现了什么功能？

1️⃣ 注册 API

通过 MCP tool 注册接口：

  • API 名称
  • 路径
  • HTTP 方法
  • 请求参数
  • 响应结构

按 session 存储。

2️⃣ 查询 API

  • 查看当前 session 下所有接口
  • 简单列表展示

3️⃣ 生成文档

  • 输出 Markdown
  • 参数表格
  • 响应示例

🧩 MCP Tool 设计

实现了 3 个工具：

  • register_endpoint
  • list_endpoints
  • generate_docs

🏗️ 结构（很简单）

1
2
3
4
5
6
7
SSE Client
   ↓
MCP Server
   ↓
Session Manager
   ↓
API Registry

每个连接一个 session，数据隔离。

📌 学到什么？

主要是：

  • MCP server 基本结构
  • tool 注册 / 调用方式
  • session 如何隔离数据
  • 如何把 API 结构化

在你这篇文章结尾加这一段就很自然👇

三、 一些实际使用场景

除了学习用途，这两个小工具在一些实际场景里也可能有用：

1️⃣ 快速理解新项目

当你接手一个陌生仓库时，可以：

  • 用 CodeSense 快速扫一遍结构
  • 理清模块划分和关键调用关系
  • 降低前期“读代码成本”

比较适合：

刚接手项目 / 看开源仓库 / 做技术调研

2️⃣ 给老项目补 API 文档

很多老项目都有一个问题：

有接口，但没有文档（或者文档不全）

可以用 api-registry-mcp：

  • 手动或半自动提取接口结构
  • 注册 API
  • 统一生成 Markdown 文档

适合：

内部系统 / 历史项目 / 没有 OpenAPI 的服务

整体来说，不一定是“生产级工具”，但在这些场景下：

能帮你少走一些弯路 👍

四、当前状态

两个项目都属于学习性质：

CodeSense

  • ✅ Agent 流程跑通
  • ✅ 能生成结构化报告
  • 🚧 复杂项目还不稳定

api-registry-mcp

  • ✅ MCP tool 基本完整
  • ✅ session 隔离实现
  • 🚧 功能还比较简单

可以稍微收一下语气，更贴“学习项目”的定位，改成这样👇

五、为什么做这两个？

主要还是出于学习目的，在实践中回答两个问题：

1️⃣ 如何让 AI 理解代码？

→ CodeSense

尝试把“代码理解”这件事，用 Agent（ReAct）模式跑通。

2️⃣ 如何结构化接口信息？

→ api-registry-mcp

用 MCP 的方式，把接口注册、查询和文档生成这套流程串起来。

整体来说，这两个项目更多是：

在动手过程中理解 Agent 和 MCP，而不是做一个完整产品

六、总结

这两个项目都不复杂，但对我来说主要价值是：

把“代码理解”和“工具调用”这两件事跑通

同时也验证了一点：

  • Agent 可以做“探索型任务”（理解代码）
  • MCP 更适合“结构化能力”（注册/查询/生成）

📌 最后

这两个项目更像是：

学习 Agent / MCP 的实验项目

如果你在折腾：

  • Agent
  • ReAct
  • MCP
  • 代码理解

可以拿去参考或者改着玩。