paper-reader

name	paper-reader
description	Use when user wants to analyze/interpret academic papers. Triggers on /解读 command with paper URL.
user-invocable	true

Paper Reader - 论文深度解读

一键解读学术论文，生成有深度又易懂的HTML报告，配上精美AI生成插图。

核心理念：浅入深出 + 用户主导

浅入深出，不是全篇说人话。

• 浅入：开头用类比和场景引入，让任何人都能进入
• 深出：中间逐步深入专业内容，展现论文真正价值
• 回归：结尾用通俗语言总结，读者带走核心理解

同时，用户应该能在关键节点介入决策。

---

⚠️ 浅入深出方法论（最重要，必读）

问题：之前要求"全篇说人话"，结果像儿童读物，没有深度。

正确做法：渐进式深度，像登山一样。

三层结构（强制执行）

每个章节必须包含这三层：

┌─────────────────────────────────────────────────────────┐
│ 🚪 入口层（1-2段）                                       │
│    目的：让小白能进来                                    │
│    方法：类比、场景、生活化例子                          │
│    问题：这部分在讲什么问题？为什么重要？                │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│ 🔬 核心层（主体部分）                                    │
│    目的：展现论文真正价值                                │
│    方法：专业术语（首次出现时解释）、技术细节、数据      │
│    内容：他们具体怎么做的？有什么创新？                  │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│ 🎯 收尾层（1段）                                         │
│    目的：读者带走核心理解                                │
│    方法：通俗总结 + "这意味着什么"                       │
│    价值：对读者/行业有什么用？                           │
└─────────────────────────────────────────────────────────┘

深度渐进原则

层次	允许的表达	禁止的表达
入口层	类比、场景、"想象一下"	术语、公式、技术细节
核心层	术语（需解释）、数据、原理	不解释就用术语、过度简化
收尾层	通俗总结、意义、展望	新术语、新概念

对比示例

❌ 全篇说人话（错误）：
"这就像传话游戏...每个人传话时不能添油加醋...就像水管网络...
水只能流动不能消失...就像给赛车加限速器..."
→ 问题：全是类比，没有专业内容，像儿童读物

✅ 浅入深出（正确）：
"【入口】想象你在玩传话游戏，队伍越长，信息失真越严重。训练大型AI
模型时也有类似问题——信息在100多层之间传递，会逐渐失控。

【核心】在技术上，这叫做"梯度爆炸"。当残差连接矩阵的谱范数大于1时，
信号会指数级放大。论文实测显示，之前的方法在27B模型上会产生3000倍的
信号放大，导致训练在12000步时崩溃。

mHC的解决方案是将连接矩阵约束到"双随机矩阵"空间——数学上保证每行
每列的和都等于1，从而谱范数恒定。实验结果：信号放大从3000倍降到1.6倍。

【收尾】简单说：他们找到了一条数学规则，让信号传递永远不会失控。
这对于训练更大规模的AI模型至关重要。"
→ 效果：能入门，有深度，有价值

术语处理规则

入口层：不用术语，只用类比
核心层：术语+解释（首次出现时）
        例："这叫做'梯度爆炸'（gradient explosion），指的是..."
收尾层：可以用已解释过的术语，无需重复解释

---

The Iron Law

NO SHORTCUTS. EVERY STEP MUST BE EXECUTED.
USER PREFERENCES MUST BE COLLECTED FIRST.

• Must collect user preferences BEFORE any analysis
• Must fetch paper content BEFORE analysis
• Must use subagents for section-by-section analysis
• Must run critic agent BEFORE generating report
• Must follow user's choice on image generation
• Must generate HTML output with proper design

---

Workflow Overview

┌─────────────────────────────────────────────────────────────┐
│  Phase 0: User Preference Collection (CRITICAL)            │
│  └─→ 使用 AskUserQuestion 询问风格、图片、介入点           │
├─────────────────────────────────────────────────────────────┤
│  Phase 1: Parse & Fetch Paper                               │
├─────────────────────────────────────────────────────────────┤
│  Phase 1.5: Outline Confirmation (if user chose)            │
├─────────────────────────────────────────────────────────────┤
│  Phase 2: Subagent Analysis (5 agents, 浅入深出)            │
│  └─→ 每章Review (if user chose)                            │
├─────────────────────────────────────────────────────────────┤
│  Phase 2.5: Image Generation (based on user choice)         │
│  └─→ 逐张确认Prompt (if user chose)                        │
├─────────────────────────────────────────────────────────────┤
│  Phase 3: Critic Agent Review                               │
├─────────────────────────────────────────────────────────────┤
│  Phase 4: Generate HTML Report                              │
│  └─→ 引用 html-design-patterns.md 选择设计范式            │
│  └─→ 最后Review (if user chose)                            │
└─────────────────────────────────────────────────────────────┘

---

Phase 0: User Preference Collection (CRITICAL - DO NOT SKIP)

在做任何事情之前，必须使用 AskUserQuestion 工具收集用户偏好。

一次性询问所有偏好

使用 AskUserQuestion 工具，一次性问3个问题：

AskUserQuestion(
  questions=[
    {
      "header": "解读风格",
      "question": "论文解读的整体风格，你更偏好哪种？",
      "multiSelect": False,
      "options": [
        {"label": "小红书/社交分享风", "description": "活泼、emoji丰富、适合转发，年轻化表达"},
        {"label": "专业科普风", "description": "严谨但通俗，像果壳/知乎的深度科普"},
        {"label": "学术简报风", "description": "精炼、结构化，适合快速了解论文要点"},
        {"label": "故事叙事风", "description": "把论文讲成一个故事，有起承转合"}
      ]
    },
    {
      "header": "图片用途",
      "question": "图片生成你希望怎么用？（Imagen 3 可生成带中文的精美信息图）",
      "multiSelect": False,
      "options": [
        {"label": "核心概念可视化", "description": "把论文的关键idea画成直观的图"},
        {"label": "信息图/要点卡片", "description": "生成带中文文字的精美信息图，可直接分享"},
        {"label": "让我逐张确认prompt", "description": "每张图先让我看prompt，确认后再生成"},
        {"label": "跳过图片生成", "description": "这篇论文不需要配图"}
      ]
    },
    {
      "header": "介入点",
      "question": "你希望在哪些环节能介入决策？",
      "multiSelect": False,
      "options": [
        {"label": "解读大纲确认", "description": "先列出要解读的章节和要点，确认后再写"},
        {"label": "每章节解读后review", "description": "每写完一章让我确认，再写下一章"},
        {"label": "只在最后review", "description": "全部写完后给我看，我提修改意见"},
        {"label": "全自动，最后给我成品", "description": "不需要中间介入，直接出最终报告"}
      ]
    }
  ]
)

---

Phase 1: Parse & Fetch

Step 1: Parse Paper URL

支持的链接格式：

• arXiv: https://arxiv.org/abs/2401.12345 或 https://arxiv.org/pdf/2401.12345.pdf
• 直接 PDF 链接: https://example.com/paper.pdf

Step 2: Fetch Paper Content

python .claude/skills/paper-reader/scripts/fetcher.py \
  --url "<paper_url>" \
  --output "papers/"

输出文件：

• papers/<paper_id>_meta.json - 元数据
• papers/<paper_id>_content.txt - 论文全文

---

Phase 1.5: Outline Confirmation (条件执行)

仅当用户选择"解读大纲确认"时执行。

展示解读大纲，使用 AskUserQuestion 确认后再继续。

---

Phase 2: Subagent Analysis

5 Subagents Configuration

Agent	负责段落	输出内容
Agent 1	Abstract + Introduction	研究背景、问题定义、核心贡献
Agent 2	Related Work	相关研究、本文创新点对比
Agent 3	Methodology	技术方法、算法流程
Agent 4	Experiments	实验结果、数据分析
Agent 5	Conclusion + Limitations	结论、局限性、未来方向

Subagent Prompt Template（浅入深出版）

你是一个{风格描述}的科普作家。你的任务是把学术论文解读成**有深度又易懂**的内容。

【最重要的规则：浅入深出结构】

每个章节必须包含三层：

1. 🚪 入口层（1-2段）
   - 用类比或场景引入
   - 让完全不懂的人能理解"这是什么问题"
   - 禁止使用任何术语

2. 🔬 核心层（主体部分）
   - 展开专业内容，展现论文价值
   - 可以使用术语，但首次出现必须解释
   - 包含技术细节、数据、原理

3. 🎯 收尾层（1段）
   - 通俗语言总结这章讲了什么
   - 说明"这意味着什么"、有什么价值

【写作风格】
{根据用户选择插入对应风格要求}

【完整论文内容】
{full_paper_content}

【你的任务】
只解读以下部分：{section_name}

【输出格式】
Markdown，使用中文，800-1200字

【禁止事项】
- 禁止全篇都用类比（那是儿童读物）
- 禁止全篇都用术语（那是论文原文）
- 禁止入口层出现术语
- 禁止核心层不解释就用术语

风格具体要求

小红书/社交分享风：

• 开头可以用"姐妹们/兄弟们"等口语化表达
• emoji装饰但不过度
• 核心层仍然要有专业内容

专业科普风：

• 像果壳/知乎深度文章
• 逻辑链条完整
• 核心层可以更专业

学术简报风：

• 开门见山，结构清晰
• 多用列表和表格
• 核心层侧重数据和对比

故事叙事风：

• 有主角、冲突、转折
• 核心层融入叙事中

---

Phase 2.5: Image Generation

根据 Phase 0 中用户的图片选择执行。

生成命令（一张一张来，API有限流）：

python .claude/skills/paper-reader/scripts/image_generator.py \
  --prompt "[Prompt内容]" \
  --output "reports/<paper_id>_images/[编号]_[名称].png"

---

Phase 3: Critic Agent Review

This phase cannot be skipped.

Critic Checklist

□ 是否遵循了"浅入深出"结构？
  - 入口层：有类比/场景引入吗？
  - 核心层：有专业内容和技术细节吗？
  - 收尾层：有通俗总结吗？
□ 入口层是否避免了术语？
□ 核心层的术语是否都有解释？
□ 是否符合用户选择的风格？
□ 是否遗漏了论文的关键贡献？
□ 技术方法解读是否准确？

---

Phase 4: Generate HTML Report

⚠️ 这不只是"生成HTML"，而是"做前端设计"。

REQUIRED REFERENCE: 查阅 @html-design-patterns.md 获取完整的设计范式库。

设计决策流程

1. 根据论文内容选择"视觉隐喻"
2. 根据用户风格选择"设计模板"
3. 从设计范式库选择布局模式（至少2种）
4. 选择动画效果
5. 应用CSS代码片段

必须满足的设计要求

□ 有 Hero 开篇区（不能直接开始正文）
□ 至少使用2种布局模式
□ 有滚动动画或交互效果
□ 视觉层级分明
□ 和上一篇报告有明显差异

输出路径

Type	Path
HTML Report	reports/<paper_id>_report.html
Illustrations	reports/<paper_id>_images/*.png

---

Common Mistakes

Mistake	Fix
全篇说人话	遵循"浅入深出"三层结构
全篇堆术语	入口层必须用类比，术语必须解释
Skip user preferences	ALWAYS run Phase 0 first
流水账HTML	引用 html-design-patterns.md
Skip critic review	ALWAYS run critic before HTML

---

Quick Reference: AskUserQuestion 使用时机

阶段	何时使用	条件
Phase 0	收集偏好	必须执行
Phase 1.5	大纲确认	用户选择"解读大纲确认"
Phase 2 后	每章review	用户选择"每章节解读后review"
Phase 2.5	逐张确认图片	用户选择"让我逐张确认prompt"
Phase 4 后	最后review	用户选择"只在最后review"