# paper_reader_kimi_agent

**Repository Path**: lvhaodeyeye/paper_reader_kimi_agent

## Basic Information

- **Project Name**: paper_reader_kimi_agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-03
- **Last Updated**: 2026-03-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PaperReader Agent

基于 kimi CLI 的论文深度调研系统。通过自建 Python MCP Server 提供 PDF 处理能力，结合多 Agent 分层工作流，自动对学术论文进行系统性调研并生成结构化报告。

## 功能特性

- **PDF 全面解析**：提取元数据、文本、渲染页面、提取图表
- **多媒体理解**：通过 kimi 原生 `ReadMediaFile` 理解图表内容
- **多 Agent 分层调研**：范围调研 → 细节调研 → 汇总合成
- **自动网络调研**：对每个子主题进行网络搜索和文献收集
- **结构化输出**：生成 Overview.md + 分章节详细报告 + 参考文献

## 项目结构

```
PaperReader/
├── README.md
├── mcp-config-dev.json              # 开发期 MCP 配置（临时注册）
├── check-env.ps1                    # 环境检查脚本（Windows）
├── check-env.sh                     # 环境检查脚本（macOS/Linux）
├── start.ps1                        # 快速启动脚本（Windows）
├── start.sh                         # 快速启动脚本（macOS/Linux）
├── mcp-server/                      # PDF MCP Server（Python 包）
│   ├── pyproject.toml
│   ├── uv.lock                      # 依赖版本锁定
│   └── src/
│       └── pdf_mcp/
│           ├── __init__.py
│           └── server.py            # 4 个 MCP 工具
├── agents/
│   ├── paper-reader.yaml            # 主 Agent（--agent-file 入口）
│   ├── scope-agent.yaml             # Sub-agent: 范围分析
│   ├── section-agent.yaml           # Sub-agent: 细节调研
│   └── synthesis-agent.yaml         # Sub-agent: 汇总合成
├── prompts/
│   ├── main-system.md
│   ├── scope-system.md
│   ├── section-system.md
│   └── synthesis-system.md
├── test_data/                       # 测试用 PDF 文件
└── output/                          # 调研输出（运行时生成）
```

## MCP Server 工具说明

| 工具名 | 参数 | 说明 |
|--------|------|------|
| `pdf_get_metadata` | `pdf_path` | 提取论文元数据（标题、作者、摘要、章节、页数） |
| `pdf_extract_text` | `pdf_path, page_start?, page_end?` | 提取指定页范围的纯文本 |
| `pdf_render_pages` | `pdf_path, output_dir, dpi?=150` | 渲染每页为 PNG（供 ReadMediaFile 使用） |
| `pdf_extract_figures` | `pdf_path, output_dir` | 提取图表区域为独立 PNG + caption |

## 多 Agent 工作流

```
主 Agent (paper-reader)
├── pdf_get_metadata / pdf_extract_text / pdf_render_pages / pdf_extract_figures
├── Task → scope-agent × 2（并行）    # 分析背景和创新点的子主题范围
├── Task → section-agent × N（并行）  # 每个子主题深度网络调研
└── Task → synthesis-agent            # 汇总生成 Overview.md
```

## 依赖环境

- **Python**：>= 3.11
- **包管理**：`uv`
- **Python 依赖**：`mcp>=1.0`, `pymupdf`, `pillow`
- **kimi CLI**：需已安装并配置

## 安装与配置

### 第一步：安装 Python 依赖

```bash
cd /Users/huhuhu/Documents/AgentHome/PaperReader/mcp-server
uv sync
```

### 第二步：验证 MCP Server

```bash
cd /Users/huhuhu/Documents/AgentHome/PaperReader
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | \
  uv --project ./mcp-server run pdf-mcp
```

正常返回应包含 4 个工具的描述。

### 第三步（可选）：正式注册到全局 MCP 配置

```bash
kimi mcp add --transport stdio pdf-reader -- \
  uv --project ./mcp-server run pdf-mcp
```

开发期使用 `--mcp-config-file` 临时注册（不修改全局配置），无需此步骤。

### 替代：使用 Makefile（推荐 macOS/Linux 用户）

```bash
# 查看可用命令
make help

# 安装依赖
make install

# 运行环境检查
make check

# 测试 MCP Server
make test
```

### 准备测试数据

`test_data/` 目录不纳入版本控制，需自行下载 PDF 文件：

```bash
mkdir -p test_data
# 示例：下载 Attention Is All You Need
curl -L "https://arxiv.org/pdf/1706.03762" -o test_data/01_Attention_Is_All_You_Need.pdf
# 示例：下载 DualPath (DeepSeek)
curl -L "https://arxiv.org/pdf/2602.21548" -o test_data/11_DualPath_DeepSeek_Agentic_Inference.pdf
```

## 快速开始

### 1. 环境检查

运行环境检查脚本，验证所有依赖是否正确安装：

**Windows:**
```powershell
.\check-env.ps1
```

**macOS/Linux:**
```bash
chmod +x check-env.sh
./check-env.sh
```

预期输出应显示所有检查项为 `[OK]`。

### 2. 快速启动分析

使用启动脚本快速分析论文：

**Windows:**
```powershell
# 分析指定 PDF，输出到默认目录
.\start.ps1 -PdfPath "./test_data/01_Attention_Is_All_You_Need.pdf"

# 指定输出目录
.\start.ps1 -PdfPath "./test_data/paper.pdf" -OutputDir "./output/my_analysis"

# 交互模式
.\start.ps1 -PdfPath "./test_data/paper.pdf" -Interactive
```

**macOS/Linux:**
```bash
# 分析指定 PDF，输出到默认目录
./start.sh ./test_data/01_Attention_Is_All_You_Need.pdf

# 指定输出目录
./start.sh ./test_data/paper.pdf ./output/my_analysis

# 交互模式
./start.sh ./test_data/paper.pdf -i
```

## 使用方法

如需手动运行或使用自定义参数，请参考以下命令：

### print 模式（推荐用于测试）

```bash
cd /Users/huhuhu/Documents/AgentHome/PaperReader

kimi --print \
  --mcp-config-file ./mcp-config-dev.json \
  --agent-file ./agents/paper-reader.yaml \
  -p "请分析这篇论文，输出目录设为 ./output/attention: ./test_data/01_Attention_Is_All_You_Need.pdf" \
  --quiet
```

### 交互模式

```bash
kimi --mcp-config-file ./mcp-config-dev.json \
  --agent-file ./agents/paper-reader.yaml
```

然后输入：
```
请分析这篇论文，输出目录设为 ./output/attention: ./test_data/01_Attention_Is_All_You_Need.pdf
```

## 输出目录结构

```
{output_dir}/
├── Overview.md                      # 完整调研摘要（必须存在）
├── pages/                           # 渲染的页面 PNG（供 ReadMediaFile）
├── figures/                         # 提取的图表 PNG
├── background/
│   ├── background_overview.md
│   └── {subtopic}.md
├── related_work/
│   ├── related_work_overview.md
│   └── {subtopic}.md
├── innovations/
│   ├── innovations_overview.md
│   └── {subtopic}.md
├── results/
│   └── results_analysis.md
├── outlook/
│   └── future_directions.md
└── ref/
    ├── {paper_name}.pdf             # 下载的引用论文
    └── web_ref.csv                  # 网页引用（url, title, description, accessed_date）
```

## 测试验证检查点

运行完成后，验证以下内容：

- [ ] MCP Server 启动成功，`tools/list` 返回 4 个工具
- [ ] `output/attention/Overview.md` 存在且包含 6 个章节
- [ ] `output/attention/ref/web_ref.csv` 存在
- [ ] 各章节目录均有内容文件
- [ ] Markdown 中公式使用 `$...$` / `$$...$$` 格式，无裸文本公式
- [ ] 文件中无表情符号
- [ ] 关键结论有文献引用标注

## 示例

项目提供现成的分析示例：

| 示例 | 命令 |
|------|------|
| Attention Is All You Need | `cd examples/attention-is-all-you-need && ./run.sh` |

示例脚本会自动下载论文、运行分析并输出完整报告。

## 环境变量配置（可选）

如需自定义配置，可复制 `.env.example` 为 `.env` 并修改：

```bash
cp .env.example .env
# 编辑 .env 文件
```

支持的配置项包括代理设置、路径配置、PDF处理参数等。

## 设计决策

| 决策点 | 选择 | 理由 |
|--------|------|------|
| PDF 读取方式 | 自建 Python MCP Server（stdio） | kimi 原生不支持 PDF |
| 图表理解 | `pdf_extract_figures` 提取 PNG → `ReadMediaFile` | kimi 原生多媒体理解 |
| MCP 注册方式 | 开发期：`--mcp-config-file`；正式：`kimi mcp add` | 开发期不污染全局 MCP 配置 |
| Sub-agent 方式 | 静态 YAML + `Task` 工具 | 稳定可控，每个 agent 有独立提示词 |
| 工作流控制 | 主 agent 根据 scope 结果动态决定 section 数量 | 遵循"先了解再安排"原则 |