论文与代码深度解析#

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

触发场景#

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

信息收集#

必须收集的信息#

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

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

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

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

1. 获取当前允许的路径范围 text

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

2. 如果用户输入的HTML输出路径验证失败 text

   ❌ 错误：您指定的路径无法访问或不在允许范围内！
   
   请重新指定一个有效的输出路径：
   

• 可以是完整的文件路径（如 output/report.html）
• 可以是目录路径（如 output/）
• 如果不指定，将使用当前工作目录下的默认路径

3. **路径验证规则**
   - 如果用户输入的路径包含父目录，检查父目录是否存在且可写
   - 如果路径不存在，尝试创建目录
   - 如果无法创建，立即提醒用户
4. **保存文件名规则**
   - 用户指定文件路径 → 直接使用该文件名
   - 用户指定目录路径 → 使用默认文件名 `report.html`
   - 用户未指定 → 使用默认路径下的 `report.html`
5. **如果用户未指定输出路径**
   - 使用当前工作目录下的默认路径
   - 并明确告知用户实际保存位置

### 收集特殊需求

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

text

问题标题：本次讲解的特殊需求 问题内容："本次生成论文代码讲解文档是否有特别的问题需求或重点关注方向？" 选项：

1. 完整讲解（推荐）- 覆盖所有标准内容：研究背景、研究动机、方法框架、实验评估、代码一致性、核心代码讲解
2. 仅论文分析 - 仅关注论文的理论贡献和方法创新
3. 代码与论文一致性 - 重点对比代码实现与论文描述的一致性
4. 实验部分详解 - 侧重讲解实验设计和结果分析

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

## 前置检查

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

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

1. **检查 frontend-design skill 是否已安装**
   text

检查方法：尝试调用该 skill，观察是否报错

2. **如果 frontend-design skill 未安装或不可用**
text

❌ 警告：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

```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. 文件树：代码结构展示

交互功能#

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

输出格式#

保存路径规则#

text

规则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 保证交互功能正常目录导航，平滑滚动