论文与代码深度解析

功能描述： 当用户需要深入解析论文与其对应代码实现时使用。自动生成精美的科研风格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 时，传递以下内容结构：

{
  "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：路径无效或无法访问
  → ❌ 立即提醒用户路径无效
  → 要求用户重新指定有效路径

质量检查清单

生成报告前检查：