CodeSage — C++ AI 注释生成器

懂你代码的 AI 文档助手

给定一个 .h/.cpp 文件或 C++ 文件夹，CodeSage 自动调用 AI 生成结构化 Markdown 文档，涵盖：类说明、函数说明、Qt Signal/Slot 注释、参数说明。

---

技术栈

层级	技术
前端	Qt 6 / C++
后端	Python + FastAPI + uvicorn
解析	tree-sitter + tree-sitter-cpp
AI	LangGraph + LangChain + OpenAI 兼容 API

---

项目结构

CodeSage/
├── backend/
│   ├── main.py              # FastAPI 服务入口
│   ├── config.py            # AI API 配置持久化
│   ├── requirements.txt
│   ├── parser/
│   │   └── cpp_parser.py    # tree-sitter C++ 解析
│   ├── graph/
│   │   ├── state.py         # LangGraph 状态定义
│   │   ├── nodes.py         # 工作流节点
│   │   └── workflow.py      # StateGraph 编译
│   ├── prompts/
│   │   └── templates.py     # 中文 Prompt 模板
│   └── generator/
│       └── md_generator.py  # MD 文件拼装
└── frontend/
    ├── CMakeLists.txt
    ├── main.cpp
    ├── mainwindow.h/.cpp/.ui
    ├── settingsdialog.h/.cpp/.ui
    ├── apiclient.h/.cpp       # HTTP 通信封装
    └── backendmanager.h/.cpp  # Python 进程管理

---

快速开始

1. 安装 Python 后端依赖

cd backend
pip install -r requirements.txt

2. 构建 Qt 前端

cd frontend
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

3. 运行

直接运行编译好的 CodeSage 可执行文件。
程序启动时会自动在后台拉起 Python FastAPI 服务（端口 18421）。

首次使用请点击 ⚙ AI 配置 填入：

• API Base URL（默认 https://api.openai.com/v1，支持任意 OpenAI 兼容接口）
• API Key
• 模型名称（如 gpt-4o-mini）

---

AI 工作流（LangGraph）

scan_files → parse_files → generate_comment (并行 fan-out) → build_md → write_md

每个类和函数被作为独立任务并行发送给 AI，结果通过 reduce 合并后写入 MD。

---

输出 MD 结构示例

# MyWidget.h
> 文件路径：/path/to/MyWidget.h

## 类：`MyWidget`
> 继承自：QWidget

### 类说明
MyWidget 是一个...

### 信号 (Signals)
#### `void dataReady(QByteArray data)`
当数据准备好时发射该信号...

| 参数 | 类型 | 说明 |
|------|------|------|
| `data` | `QByteArray` | 准备好的数据内容 |

### 槽函数 (Slots)
...