SKILL.md

---
name: paper-code-html
version: 1.0.0
description: "论文与代码深度解析。当用户需要生成精美科研风格HTML文档来解析论文与其对应代码实现时使用。涵盖论文的理论贡献、方法框架、实验评估，以及代码实现与论文的一致性分析。"
---

# 论文与代码深度解析

> **功能描述：** 当用户需要深入解析论文与其对应代码实现时使用。自动生成精美的科研风格HTML文档，涵盖论文的理论贡献、方法框架、实验评估，以及代码实现与论文的一致性分析。

## 触发场景

- "生成论文代码html解析"
- "生成html解析这篇论文和代码"
- "生成html深度讲解论文和代码"
- "生成html帮我分析这篇论文的实现"
- "生成html讲解一下这个项目"
- "生成论文代码解析html"
- "生成html格式的论文代码解析文档"

## 信息收集

### 必须收集的信息

启动任务前必须收集以下三个信息，**缺少任意一项都应向用户询问**：

1. **论文路径** - 用户提供的论文文件路径（PDF、Markdown或HTML格式）
2. **代码路径** - 用户提供的代码目录或文件路径
3. **HTML输出路径** - 用户指定HTML报告的保存位置

### 路径安全检查（关键！）

**⚠️ 严重警告：在确认任何路径之前，必须执行以下检查**

1. **获取当前允许的路径范围**
   ```
   方法1：检查环境变量 ALLOWED_PATHS（如果存在）
   方法2：检查当前工作目录作为基准
   方法3：询问用户允许的输出路径范围
   ```

2. **如果用户输入的HTML输出路径验证失败**
   ```
   ❌ 错误：您指定的路径无法访问或不在允许范围内！
   
   请重新指定一个有效的输出路径：
   - 可以是完整的文件路径（如 output/report.html）
   - 可以是目录路径（如 output/）
   - 如果不指定，将使用当前工作目录下的默认路径
   ```

3. **路径验证规则**
   - 如果用户输入的路径包含父目录，检查父目录是否存在且可写
   - 如果路径不存在，尝试创建目录
   - 如果无法创建，立即提醒用户

4. **保存文件名规则**
   - 用户指定文件路径 → 直接使用该文件名
   - 用户指定目录路径 → 使用默认文件名 `report.html`
   - 用户未指定 → 使用默认路径下的 `report.html`

5. **如果用户未指定输出路径**
   - 使用当前工作目录下的默认路径
   - 并明确告知用户实际保存位置

### 收集特殊需求

向用户询问是否有特殊需求：

```
问题标题：本次讲解的特殊需求
问题内容："本次生成论文代码讲解文档是否有特别的问题需求或重点关注方向？"
选项：
1. 完整讲解（推荐）- 覆盖所有标准内容：研究背景、研究动机、方法框架、实验评估、代码一致性、核心代码讲解
2. 仅论文分析 - 仅关注论文的理论贡献和方法创新
3. 代码与论文一致性 - 重点对比代码实现与论文描述的一致性
4. 实验部分详解 - 侧重讲解实验设计和结果分析
```

**重要：** 如果用户未选择特定选项，则按照选项1（完整讲解）执行。

## 前置检查

### frontend-design Skill 检查（关键！）

**⚠️ 在开始生成HTML之前，必须执行以下检查**

1. **检查 frontend-design skill 是否已安装**
   ```
   检查方法：尝试调用该 skill，观察是否报错
   ```

2. **如果 frontend-design skill 未安装或不可用**
   ```
   ❌ 警告：frontend-design skill 不可用！
   
   该 skill 负责生成精美的科研风格 HTML 界面。
   没有它将无法生成高质量的报告。
   
   选项：
   1. 取消本次任务，安装 frontend-design skill 后重试
   2. 继续进行，但使用简化版 HTML 模板（不推荐，界面质量可能较差）
   
   请选择：_
   ```

3. **只有当用户明确选择"继续进行"时，才可以使用简化版模板**
   - 在报告中添加说明："本报告未使用 frontend-design skill，界面可能不够精美"

## 工作流程

### 阶段一：信息收集与路径验证

1. 确认论文和代码路径有效
2. **验证HTML输出路径有效性**
   - 检查路径是否可访问
   - 如果是相对路径，转换为绝对路径
   - 确认文件可以创建
3. 向用户询问特殊需求
4. 确认所有路径有效后，创建输出目录（如需要）

### 阶段二：论文深度解析

按以下结构解析论文内容：

#### 1. 研究背景
- 论文所属领域和研究方向
- 该领域的重要性和应用场景
- 相关技术发展历程

#### 2. 研究动机（Problem & Motivation）
- **现有方案的局限性**：别人是怎么做的，有什么问题需要被解决
- 论文指出的核心痛点
- 为什么现有方法不够好

#### 3. 方法框架（Methodology）
- **整体流程**：方法的核心思想和执行步骤
- **模块/组件详解**：每个关键组件的功能和实现原理
- 技术创新点和设计考量
- 用图表和示意图说明流程

#### 4. 实验评估（Experiments）
- 使用的基准测试（Benchmarks）
- 实验设置和配置
- 与基线方法的对比结果
- 关键数据和结论

### 阶段三：代码深度解析

#### 5. 代码与论文一致性分析
- 代码结构是否与论文描述的方法框架一致
- 实现细节与论文描述的对应关系
- 可能的差异和工程妥协

#### 6. 核心代码讲解
- 关键类和函数的功能说明
- 核心算法的代码实现解析
- 数据流和处理逻辑
- 重要的设计模式

### 阶段四：HTML报告生成

**必须调用 `frontend-design` skill 来生成HTML界面。**

1. 将阶段二和三收集的解析内容整理为结构化数据
2. 调用 `frontend-design` skill，传入：
   - 主题：科研论文解析报告
   - 风格要求：学术风格，专业、清晰
   - 内容结构：见下方"报告内容结构"
3. 将生成的HTML保存到验证通过的有效路径

## 报告内容结构

调用 frontend-design skill 时，传递以下内容结构：

```json
{
  "title": "{论文标题}",
  "subtitle": "{英文副标题}",
  "authors": ["{作者列表}"],
  "metadata": {
    "arxiv": "{arXiv编号}",
    "year": "{年份}",
    "source": "{来源机构}"
  },
  "sections": [
    {
      "id": "background",
      "title": "1. 研究背景",
      "content": "{研究背景内容}"
    },
    {
      "id": "motivation", 
      "title": "2. 研究动机",
      "content": "{研究动机内容}",
      "highlight": "{核心创新点}"
    },
    {
      "id": "methodology",
      "title": "3. 方法框架",
      "subsections": [
        {
          "title": "3.1 整体流程",
          "content": "{流程说明}",
          "diagram": "{SVG图表或架构图描述}"
        },
        {
          "title": "3.2 核心模块详解",
          "components": [
            {"name": "{模块名}", "desc": "{模块描述}"}
          ]
        }
      ]
    },
    {
      "id": "experiments",
      "title": "4. 实验评估",
      "benchmarks": ["{基准测试名称}"],
      "results": "{实验结果}"
    },
    {
      "id": "code-consistency",
      "title": "5. 代码与论文一致性分析",
      "assessment": "{一致性评估结果}",
      "details": "{详细分析}"
    },
    {
      "id": "code-analysis",
      "title": "6. 核心代码讲解",
      "fileTree": "{代码文件树结构}",
      "codeSnippets": [
        {
          "title": "{代码标题}",
          "language": "python",
          "code": "{代码内容}"
        }
      ]
    }
  ],
  "footer": {
    "timestamp": "{生成时间}",
    "note": "本文档基于 {论文标题} 论文和源代码生成"
  }
}
```

## UI设计要求（传递给 frontend-design skill）

### 整体风格
- 科研学术风格：专业、严谨、清晰
- 参考学术论文和顶会poster的设计语言

### 配色方案建议
- 主色调：深蓝色系（代表专业、学术）
- 强调色：橙色或金色（用于重点标注）
- 背景：浅色系（如米白、淡灰）
- 代码块：深色背景，与内容区域有明显对比

### 字体选择
- 标题：衬线字体（如 Noto Serif SC）
- 正文：非衬线字体（如 Noto Sans SC）

### 必要组件
1. **文档头部**：论文标题、副标题、作者列表、arXiv信息
2. **目录导航**：可跳转的章节链接
3. **内容卡片**：每个章节独立的视觉容器，带明确边框和阴影
4. **代码展示**：语法高亮的代码块，与背景有明显对比
5. **数据表格**：实验结果对比
6. **高亮框**：核心创新点、关键洞察
7. **架构图**：SVG格式的方法框架图
8. **文件树**：代码结构展示

### 交互功能
- 目录点击跳转（平滑滚动）
- 响应式布局（适配移动端）
- 代码块复制功能（可选）

## 输出格式

### 保存路径规则

```
规则1：用户指定完整文件路径
  → 验证父目录存在且可写
  → 直接保存到该路径
  → 例：output/report.html → /current/working/dir/output/report.html

规则2：用户指定目录路径
  → 验证目录存在且可写
  → 在该目录下创建 report.html
  → 例：output/ → /current/working/dir/output/report.html

规则3：用户未指定路径
  → 使用当前工作目录下的 report.html
  → 告知用户实际保存位置

规则4：路径无效或无法访问
  → ❌ 立即提醒用户路径无效
  → 要求用户重新指定有效路径
```

## 质量检查清单

生成报告前检查：

| 检查项 | 要求 |
|--------|------|
| 路径验证 | HTML输出路径有效可访问，否则提醒用户 |
| frontend-design | 已安装并可用，否则提醒用户选择 |
| 论文信息完整 | 标题、作者、arXiv编号、年份 |
| 研究动机清晰 | 明确现有方法的问题 |
| 方法框架详细 | 包含流程图和模块说明 |
| 实验数据准确 | 基准测试名称和结果数据 |
| 代码分析深入 | 核心类函数详细讲解 |
| HTML样式精美 | 由 frontend-design skill 保证 |
| 交互功能正常 | 目录导航，平滑滚动 |