# codegraph-summary

> CodeGraph 中文语义摘要工具 — 为代码符号生成中文业务摘要，支持语义搜索和 PRD 关联分析。

将代码知识图谱与 LLM 结合，让你用中文业务术语搜索代码、理解系统架构、追踪需求覆盖。

## 特性

- **一键初始化** — `codegraph-summary init` 自动构建索引 + 生成摘要
- **中文语义搜索** — 用 "交易查询"、"清退流程" 等业务术语搜索代码
- **FTS5 trigram** — 高质量中文子串匹配，无需分词器
- **图谱扩展** — 搜索结果展示调用链（谁调用了它、它调用了谁）
- **PRD 关联** — 导入需求文档，自动关联到代码实现
- **多协议 LLM** — 支持 Anthropic / OpenAI 兼容 API
- **启发式降级** — 无 LLM API Key 时仍可生成基础摘要
- **三种接口** — CLI / HTTP API / MCP Server

## 快速开始

### 安装

```bash
npm install -g codegraph-summary
```

需要先安装 [CodeGraph](https://github.com/colbymchenry/codegraph)：

```bash
npm install -g @colbymchenry/codegraph
```

### 一键初始化

```bash
cd your-project
codegraph-summary init
```

这会自动完成：
1. 构建 CodeGraph 代码索引（如果不存在）
2. 用 LLM 为所有导出符号生成中文摘要

### 配置 LLM（可选）

在项目根目录创建 `.env` 文件：

```env
SUMMARY_LLM_API_KEY=your-api-key
SUMMARY_LLM_BASE_URL=https://api.anthropic.com
SUMMARY_LLM_MODEL=claude-sonnet-4-20250514
SUMMARY_LLM_API_TYPE=anthropic
```

不配置 API Key 也能用（启发式模式，用函数签名作为摘要）。

## 使用

### 搜索代码

```bash
codegraph-summary search "交易查询" -p /path/to/project
```

### 查看状态

```bash
codegraph-summary status -p /path/to/project
```

### 强制重新生成

```bash
codegraph-summary init -f
codegraph-summary generate -f -p /path/to/project
```

### PRD 关联

```bash
# 导入 PRD 文档（支持 .md / .docx / .pdf / .txt）
codegraph-summary prd-import ./docs/prd.md -p /path/to/project

# 用需求描述搜索代码
codegraph-summary prd-search "用户清退流程" -p /path/to/project

# 查看需求覆盖率
codegraph-summary prd-coverage -p /path/to/project
```

### MCP Server（AI 助手集成）

```bash
codegraph-summary mcp
```

在 Claude Code 的 MCP 配置中添加即可让 AI 助手直接搜索代码摘要。

### HTTP API

```bash
codegraph-summary serve --port 3000
```

## 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `SUMMARY_LLM_API_KEY` | LLM API Key | (空，启发式模式) |
| `SUMMARY_LLM_BASE_URL` | LLM API 地址 | (空) |
| `SUMMARY_LLM_MODEL` | 模型名称 | (空) |
| `SUMMARY_LLM_API_TYPE` | `anthropic` 或 `openai` | `anthropic` |
| `SUMMARY_LLM_BATCH_SIZE` | 每批符号数量 | `10` |
| `SUMMARY_LLM_CONCURRENCY` | 并发请求数 | `3` |
| `SUMMARY_VECTOR_GATEWAY_URL` | 向量服务地址（可选） | (空) |
| `CODEGRAPH_BIN` | 自定义 codegraph 路径 | (自动查找) |

## 系统要求

- Node.js >= 22.5.0
- [CodeGraph](https://github.com/colbymchenry/codegraph) (用于代码索引)
- PDF 支持需要 `poppler-utils`（macOS: `brew install poppler`）
- DOCX 支持需要 `unzip` 命令

## License

MIT