paper-analyzer

Structured paper deconstruction and analysis

Conduct structured deconstruction of academic papers based on 12 reading elements, and save the results as an Excel file stored in the folder where the paper is located.

Workflow

1. Read the paper

• Use the Read tool to read the paper file provided by the user (supports PDF, Word and other formats)
• For PDF files, if the Read tool cannot read them directly, use pdftotext command to extract text
• For PDF files, if there are many pages, first read the first few pages to understand the structure, then read the full text in batches
• Ensure complete reading of all parts of the paper: abstract, introduction, literature review, methods, results, discussion, conclusion
• Record the folder path where the paper is located, for subsequent saving of the Excel file

2. Extract information according to the 12 elements

After reading the paper, extract the 12 reading elements one by one. For detailed element definitions, see references/reading_elements.md。

Extraction points:

• Research background: Extract the macro background from the beginning of the introduction, distinguishing practical background, theoretical background, and policy background
• Research question: Identify the core research question and determine its type (what/why/how/should)
• Research conclusion: Extract the direct answer to the research question from the conclusion and discussion sections
• Literature synthesis: From the literature review section, sort out how the author classifies and organizes existing research
• Literature critique: Extract the author's evaluation of existing research, focusing on statements of the research gap
• Research method: Extract specific research methods and research design from the methodology section
• Theoretical perspective and theoretical framework: Identify the theoretical basis and analytical framework adopted by the paper
• Consistent findings: Extract findings from the discussion section that are consistent with existing research
• Inconsistent findings: Extract findings from the discussion section that are inconsistent with existing research
• Research contributions: Extract the research contributions stated by the author (new method/new material/new theory/new viewpoint/new concept)
• Research limitations: Extract from the limitations section of the conclusion or discussion
• Future research prospects: Extract the author's suggestions for follow-up research

If a certain element is not explicitly mentioned in the paper, mark it as "not explicitly mentioned in the paper" and try to make a reasonable inference based on the paper content, with the inferred content marked in parentheses.

3. Save as an Excel file

After the analysis is completed, save the results as an Excel file, stored inthe folder where the analyzed paper is located.

Use scripts/export_excel.py script to generate Excel. First use Python to write the analysis data into a temporary JSON file, then call the script.

Single paper

Generate file name:论文拆解_<论文简称>.xlsx, containing one worksheet.

Construct JSON data and call the script:

python3 <skill_path>/scripts/export_excel.py --mode single --output "<论文所在文件夹>/论文拆解_<论文简称>.xlsx" --json '<json_string>'

JSON structure:

{
  "title": "论文标题",
  "author": "作者",
  "source": "期刊/来源",
  "year": "年份",
  "elements": {
    "研究背景": "内容...",
    "研究问题": "内容...",
    "研究结论": "内容...",
    "文献综合": "内容...",
    "文献批评": "内容...",
    "研究方法": "内容...",
    "理论视角与理论框架": "内容...",
    "一致性发现": "内容...",
    "不一致性发现": "内容...",
    "研究贡献": "内容...",
    "研究不足": "内容...",
    "未来研究展望": "内容..."
  }
}

Multiple papers

Generated file name:论文拆解汇总_<N>篇.xlsx, containing an independent worksheet for each paper + a final "Horizontal Comparison Summary" worksheet.

python3 <skill_path>/scripts/export_excel.py --mode multi --output "<论文所在文件夹>/论文拆解汇总_<N>篇.xlsx" --json '<json_string>'

JSON structure:

{
  "papers": [
    { "title": "...", "author": "...", "source": "...", "year": "...", "elements": { ... } },
    ...
  ],
  "summary": {
    "paper_labels": ["论文A简称", "论文B简称", ...],
    "elements": {
      "研究背景": ["论文A精简版", "论文B精简版", ...],
      ...12个要素各一个数组...
    }
  }
}

Important: Since the JSON string may be very long, use Python to write the JSON to a temporary file, then pass it in with --json "$(cat /tmp/paper_data.json)" , or call the script directly in Python. Recommended approach:

import json, subprocess
data = { ... }  # 构造好的数据
with open("/tmp/_paper_analysis.json", "w") as f:
    json.dump(data, f, ensure_ascii=False)
subprocess.run(["python3", "<skill_path>/scripts/export_excel.py",
    "--mode", "multi",
    "--output", "<输出路径>",
    "--json", json.dumps(data, ensure_ascii=False)])

4. Output to the conversation

After saving the Excel file, also briefly present the analysis results in the conversation as a markdown table, and inform the user of the save path of the Excel file.

5. Content requirements

• Use Chinese output (unless the paper is in English and the user requests English output)
• The content of each element should be concise but sufficiently informative; each element in a single-paper table should be 2-5 sentences
• Each cell in the summary comparison table should be compressed to 1-2 sentences of core key points
• Be faithful to the original paper and avoid overinterpretation; clearly mark inferred content
• In the research question element, indicate the question type (what/why/how/should)