论文阅读助手 (Paper Reader)

调用后端接口，对论文进行搜索和多种维度的智能分析。

When to Use

• 用户想搜索某个主题或关键词相关的论文
• 用户想对一篇论文生成思维导图
• 用户想对论文进行深度精读分析（包含精读、关键问答、评价）
• 用户想获取论文的摘要总结
• 用户想翻译一篇外文论文
• 用户想基于论文进行多轮问答对话
• 用户想将论文转为 AI 播客音频
• 用户想基于 AI 播客生成翻转字幕视频

Tools

| 工具 | 说明 | |------|----------------------------------------------------------------------------------------------------------| | paper_search | 根据关键词搜索论文，返回论文列表（标题、作者、摘要、分类、时间、查看论文链接），支持分页。返回的内容已经是格式化好的结果，直接原样展示给用户即可，禁止对搜索结果做任何总结、改写、精简或二次加工。结果中包含 Markdown 链接格式的「查看论文」按钮，必须原样保留 | | paper_mindmap | 生成思维导图（自动渲染为 PNG 图片并上传到腾讯云，返回结果中只包含脑图图片，不包含文本内容。mindmap_image_url 为图片链接，不要询问用户是否需要生成图片） | | paper_deep_read | 论文精读：依次调用深度精读分析、关键问题及回答、论文评价三个接口，返回综合分析结果。返回的内容已经是格式化好的结果，直接原样展示给用户即可，禁止对精读结果做任何总结、改写、精简或二次加工 | | paper_summary | 对论文内容进行摘要总结。返回的内容已经是格式化好的结果，直接原样展示给用户即可，禁止对总结结果做任何总结、改写、精简或二次加工 | | paper_translate | 对论文全文进行翻译。返回的内容已经是格式化好的翻译结果，直接原样展示给用户即可，禁止对翻译结果做任何总结、改写、精简或二次加工 | | paper_chat | 基于论文进行多轮对话问答。返回的内容已经是格式化好的结果，直接原样展示给用户即可，禁止对对话结果做任何总结、改写、精简或二次加工 | | paper_podcast | 将论文转为双人对话播客音频。播客数据会自动保存，用于后续生成翻转字幕视频 | | paper_podcast_video | 基于 AI 播客生成翻转字幕视频。前置条件：必须先调用 paper_podcast 生成播客。如果用户未生成过播客，需引导用户先生成 AI 播客。返回的内容包含 <video> 标签和下载链接，必须原样保留 |

⚠️ file_url 使用规则（极其重要）

禁止将文件下载到本地，禁止启动本地 HTTP 服务器！

• file_url 参数必须直接使用用户提供的原始公网 URL（如 https://xxx.cos.ap-xxx.myqcloud.com/paper.pdf）
• 后端 API 会自行根据 URL 下载文件，不需要也不允许在本地做任何文件下载、转存、代理操作
• 后端 API 不接受 localhost、127.0.0.1、file:// 等本地地址
• 当用户上传文件时，框架会提供文件的公网可访问 URL，直接将该 URL 作为 file_url 传入即可
• 错误做法：下载文件到本地 → 启动 HTTP 服务器 → 用 localhost URL 调用 skill ❌
• 正确做法：直接用用户提供的文件 URL 调用 skill ✅

Workflow

1. 接收请求：handler.py 从 stdin 读取工具调用 JSON
2. 工具匹配：如果请求中没有指定工具或工具名未匹配，自动返回可用工具列表提示用户选择。当用户上传了文件但未明确指定操作时，直接展示返回的工具列表即可
3. 鉴权检查：验证 token 是否存在
4. 构建请求：根据工具类型构建带附件的请求体，file_url 直接使用用户提供的原始公网 URL，不做任何本地下载或转存
5. 调用接口：POST 到 /sse/aiwriter/v1/chat
6. 流式/非流式输出（统一输出纯文本）：
   • 流式输出（paper_summary、paper_translate、paper_chat、paper_deep_read）：逐 chunk 解析 SSE 响应，每收到一个增量内容立即将纯文本写入 stdout 并 flush，实现边接收边输出
   • 非流式输出（paper_mindmap、paper_podcast、paper_search、paper_podcast_video）：等待完整响应后一次性输出纯文本结果
7. 【脑图专用】图片生成与上传：当调用 paper_mindmap 时，handler 内部会自动完成以下流程：渲染 Markdown 为 PNG 图片 → 调用 upload_public_file 接口上传到 腾讯云 → 返回结果中包含 mindmap_image_url（图片链接）。无需手动保存文件到本地，直接将 mindmap_image_url 展示给用户即可。禁止在此步骤前询问用户
8. 【播客专用】音频播放器生成：当调用 paper_podcast 时，handler 内部会自动从 podcast_msg 中提取音频 URL，生成包含 HTML5 <audio> 播放器和下载链接的内容。音频可直接在浏览器/对话框中播放，无需下载。返回结果的 audio_url 字段包含音频的公开链接。同时，播客的完整数据（包含 speaker_text_list）会自动保存到 output/podcast_data 目录，用于后续生成翻转字幕视频。
9. 【翻转字幕视频专用】视频生成：当调用 paper_podcast_video 时，handler 会自动查找最近保存的播客数据文件，使用 video_assembler.py 将 speaker_text_list 转换为翻转字幕视频的入参数据，然后调用 /trpc/aiwriter/v1/podcast/audio_to_video 接口提交视频生成任务，并轮询 /trpc/aiwriter/v1/podcast/video_gen_progress 接口等待视频生成完成。前置条件：必须先调用 paper_podcast 生成播客。

输出协议

handler 统一输出纯文本到 stdout，不包裹任何 JSON 结构：

• 流式工具（paper_summary、paper_translate、paper_chat、paper_deep_read）：逐 chunk 直接输出文本内容（无包裹、无分隔符），最终拼接即为完整结果
• 非流式工具（paper_mindmap、paper_podcast、paper_search、paper_podcast_video）：一次性输出完整纯文本结果
• 错误情况：输出以"错误："开头的文本描述

⚠️ 流式输出要求（极其重要）：

• 流式工具（翻译、总结、精读、对话）的输出内容量很大（通常数万字），必须以流式方式实时读取 skill 进程的 stdout 并逐步展示给用户
• 禁止等待 skill 进程执行完毕后再一次性展示结果，这会导致用户长时间看不到任何输出
• 禁止在流式输出过程中插入自己的状态描述（如"正在等待..."、"让我检查进度..."），直接透传 stdout 内容即可
• skill 进程的 stdout 每收到一个 chunk 就会立即 flush，框架应逐行/逐块读取并实时转发给用户

自动保存输出结果

所有工具调用的结果会自动保存到工作区的 output 目录下（不是 workspace 根目录）：

• 纯文本结果（总结、翻译、精读、对话、搜索等）：保存为 .md 文件
• 脑图：保存 .md 文本 + 下载 .png 脑图图片（返回给用户的内容只包含图片，不包含脑图文本）
• 播客：保存 .md 文本 + 下载 .wav 音频文件 + 保存播客数据 .json（到 output/podcast_data 目录）
• 翻转字幕视频：保存 .md 文本 + 下载 .mp4 视频文件
• 文件命名格式：{工具简称}_{文件名}_{时间戳}.{扩展名}，如 translate_paper_20260420_175300.md
• output 目录位置：优先使用环境变量 OPENCLAW_WORKSPACE 指定的工作区目录下的 output 子目录，否则默认为 ~/.openclaw/workspace/output
• 示例路径：/root/.openclaw/workspace/output/translate_硕士学位论文_20260420_175300.md

⚠️ 重要：skill 执行完成后会在输出末尾显示保存路径，禁止再自行将结果另存到其他位置。结果已自动保存到 output 目录，直接告知用户保存路径即可。

Usage Examples

注意：file_url 必须是公网可访问的 URL，直接使用用户提供的原始链接，禁止下载到本地再转发。

# 论文脑图（直接使用用户提供的文件 URL）
{"tool": "paper_mindmap", "arguments": {"file_url": "https://example.cos.ap-guangzhou.myqcloud.com/paper.pdf"}}

# 论文对话
{"tool": "paper_chat", "arguments": {"question": "这篇论文的主要贡献是什么？", "file_url": "https://example.cos.ap-guangzhou.myqcloud.com/paper.pdf"}}

# AI播客
{"tool": "paper_podcast", "arguments": {"file_url": "https://example.cos.ap-guangzhou.myqcloud.com/paper.pdf", "mode": "quick_insight"}}

# 翻转字幕视频（需要先生成 AI 播客）
{"tool": "paper_podcast_video", "arguments": {"file_name": "paper.pdf"}}

# 论文翻译
{"tool": "paper_translate", "arguments": {"file_url": "https://example.cos.ap-guangzhou.myqcloud.com/paper.pdf"}}

# 论文搜索（不需要 file_url）
{"tool": "paper_search", "arguments": {"keyword": "deepseek", "page": 1, "size": 10}}

Dependencies

论文脑图（paper_mindmap）渲染依赖

脑图功能使用纯 Python SVG + cairosvg 方案将 Markdown 渲染为高清思维导图 PNG 图片。 无需浏览器、Node.js 或任何外部进程，仅依赖 Python 的 cairosvg 库。

重要：必须安装 cairosvg 才能使用脑图功能

安装 cairosvg

pip install cairosvg

Linux 环境额外依赖（必须）

# cairosvg 需要 cairo 库
sudo apt-get install -y libcairo2-dev
# 中文字体（必须安装，否则脑图中文会显示为方块）
sudo apt-get install -y fonts-noto-cjk fonts-wqy-zenhei fonts-wqy-microhei
# 安装后刷新字体缓存
fc-cache -fv

脑图生成流程（重要）

当调用 paper_mindmap 工具后，handler 内部已自动完成图片生成和上传，无需手动操作。返回结果中包含以下字段：

• mindmap_image_url：脑图图片的 公开链接（上传成功时）
• mindmap_image_filename：图片文件名
• mindmap_image_error：错误信息（上传失败时）

内部流程说明（已在 paper_reader_skill.py 中自动完成）：

1. 调用后端接口获取 Markdown 层级脑图文本
2. 使用 mindmap.py 将 Markdown 渲染为 PNG 图片（保存到临时目录）
3. 调用 /trpc/aiwriter/v1/upload_public_file 接口，将图片以 base64 编码上传到腾讯云
4. 返回 图片链接，清理临时文件

使用示例：

# paper_mindmap 返回的 result 中已包含图片链接
result = paper_mindmap(authorization, file_url, file_name)
if result.get("mindmap_image_url"):
    print(f"脑图图片链接：{result['mindmap_image_url']}")
else:
    print(f"脑图生成失败：{result.get('mindmap_image_error', '未知错误')}")

• 不要询问用户是否需要生成图片，直接展示返回的图片链接
• 不需要手动保存文件到本地目录，图片已上传到腾讯云

⚠️ 格式保留要求：脑图返回的 mindmap_image_url 是图片链接，展示给用户时必须保留完整的 Markdown 图片或链接格式（如 ![脑图](URL) 或 [查看脑图](URL)），禁止将链接转为纯文本或丢弃 URL。

AI播客（paper_podcast）音频播放功能

当调用 paper_podcast 工具后，handler 内部已自动完成音频 URL 提取和内容格式化，无需手动操作。返回结果中包含以下字段：

• audio_url：播客音频的公开链接
• content：包含 HTML5 <audio> 播放器和下载链接的内容

音频播放功能说明：

• 返回的内容包含 HTML5 <audio controls> 标签，支持在浏览器/对话框中直接播放
• 音频格式为 WAV，兼容所有现代浏览器
• 提供备用下载链接，确保在不支持音频播放的环境中也能使用
• 音频可以直接在对话回复中播放，无需用户手动下载

内部流程说明（已在 handler.py 中自动完成）：

1. 调用后端接口获取播客音频 URL（从 podcast_msg.audio_url 提取）
2. 生成包含 HTML5 <audio> 播放器和下载链接的内容
3. 返回可直接播放的音频内容

使用示例：

# paper_podcast 返回的 result 中已包含可直接播放的音频内容
result = paper_podcast(authorization, file_url, file_name)
if result.get("audio_url"):
    # 直接使用 result["content"] 展示给用户，包含音频播放器
    print(result["content"])
else:
    print(f"播客生成失败：{result.get('error', '未知错误')}")

• 不要询问用户是否需要播放音频，直接展示包含播放器的返回内容
• 音频已优化为可直接在浏览器中播放的格式

⚠️ 格式保留要求：播客返回的内容包含 HTML <audio> 标签和 Markdown 下载链接，展示给用户时必须原样保留这些 HTML 标签和 Markdown 链接格式，禁止将其转为纯文本、丢弃标签、或做任何改写。丢弃 <audio> 标签会导致用户无法播放音频，丢弃下载链接会导致用户无法下载文件。

Configuration

配置文件路径：config.json（位于项目根目录，即与 SKILL.md 同级目录下）。

完整路径示例：<skill_root>/config.json

代码中的查找优先级：

1. 环境变量 PAPER_READER_CONFIG 指定的路径
2. 当前工作目录下的 config.json
3. 源码目录结构：src/paper_reader/../../config.json（即项目根目录）
4. 用户 home 目录 ~/.paper_reader/config.json

配置项说明：

• api.base_url — API 基础地址
• api.authorization — 鉴权 token（必填，需要在此字段填入有效的 Bearer token）
• api.timeout — 请求超时时间（秒），默认 180
• api.podcast_timeout — 播客请求超时时间（秒），默认 300
• api.search_paper_endpoint — 论文搜索接口路径，默认 /trpc/aiwriter/v1/search_paper
• apps — 各工具的 app_name / agent_tag 映射
• podcast — 播客默认配置（模式、声音）

Authentication (Token 鉴权)

所有接口调用需要提供鉴权 token。

Token 缺失或无效时的提示

当用户未提供 token，或接口返回 HTTP 401（鉴权失败）时，技能会返回以下提示信息：

[点击获取 token](https://edu.tencent.com/agent/#/api-keys)

⚠️ 格式保留要求（极其重要）：上述提示信息包含 Markdown 链接格式 [文本](URL)，展示给用户时必须原样保留该 Markdown 链接格式，禁止将其转为纯文本、丢弃链接、或做任何改写。只有保留完整的 [点击获取 token](URL) 格式，用户才能在对话界面中看到可点击的链接按钮。如果丢弃格式，用户将无法点击跳转获取 token。

该地址由 config.json 的 api.auth_url 字段统一配置，代码中从 config 读取。

AI播客返回格式示例

播客功能使用 HTML5 <audio> 标签返回内容，浏览器/对话框可直接播放音频：

## 🎙️ AI播客已成功生成！

**📁 文件：** paper.pdf　|　**🎙️ 模式：** quick_insight

<audio controls src="https://example.com/ai-audio/2026-04-17/paper.wav">您的浏览器不支持音频播放</audio>

[📥 下载音频文件](https://example.com/ai-audio/2026-04-17/paper.wav)

效果说明：

• ✅ 使用 HTML5 <audio controls> 标签，浏览器直接渲染为音频播放控件
• ✅ 支持播放、暂停、进度拖拽、音量调节
• ✅ 提供备用下载链接，确保兼容性
• ✅ audio_url 字段单独存放音频 URL，方便前端做自定义渲染

⚠️ 格式保留要求（极其重要）：上述播客返回内容中的 <audio controls src="..."> HTML 标签和 [📥 下载音频文件](URL) Markdown 链接，展示给用户时必须原样保留，禁止将其转为纯文本、移除 HTML 标签、丢弃链接、或做任何改写。这些格式是用户播放音频和下载文件的唯一入口，丢弃后用户将无法使用播客功能。

翻转字幕视频返回格式示例

翻转字幕视频功能使用 HTML5 <video> 标签返回内容，浏览器/对话框可直接播放视频：

## 🎬 翻转字幕视频已生成！

**📹 标题：** 中国镍矿供应风险识别安全评价研究

<video controls width="100%" src="https://example.com/uploads/xxx.mp4">您的浏览器不支持视频播放</video>

[📥 下载视频文件](https://example.com/uploads/xxx.mp4)

前置条件：

• ✅ 必须先调用 paper_podcast 生成 AI 播客
• ✅ 播客数据会自动保存到 output/podcast_data 目录
• ✅ 调用 paper_podcast_video 时会自动查找最近的播客数据

内部流程说明（已在 handler.py 和 paper_reader_skill.py 中自动完成）：

1. 查找最近保存的播客数据文件（output/podcast_data/podcast_*.json）
2. 使用 video_assembler.py 将 speaker_text_list 转换为翻转字幕视频的入参数据（包含字幕拆分、动画效果、旋转等）
3. 调用 /trpc/aiwriter/v1/podcast/audio_to_video 接口提交视频生成任务
4. 轮询 /trpc/aiwriter/v1/podcast/video_gen_progress 接口等待视频生成完成（最长等待 10 分钟）
5. 返回视频播放链接

⚠️ 格式保留要求（极其重要）：翻转字幕视频返回内容中的 <video controls> HTML 标签和 [📥 下载视频文件](URL) Markdown 链接，展示给用户时必须原样保留，禁止将其转为纯文本、移除 HTML 标签、丢弃链接、或做任何改写。

⚠️ 前置条件提示：如果用户直接请求生成翻转字幕视频但尚未生成 AI 播客，必须先引导用户使用 paper_podcast 工具生成 AI 播客，然后再调用 paper_podcast_video 生成视频。