ppw:repo-to-paper

目的

此 Skill 会扫描 Python ML 实验仓库，并生成分层的论文大纲（H1/H2/H3），在每个标题层级设置用户确认节点。它面向已完成实验、需要将研究发现整理成学术论文的研究人员。扫描会根据 references/repo-patterns.md 中的模式对仓库文件分类，然后逐步从粗略的章节标题生成到更细致的子小节标题；用户确认或修改每个层级后，才会继续。确认 H2 后，Skill 会自动通过 Semantic Scholar MCP 收集学术参考文献，并将其保存为各章节的 ref 文件，供后续正文生成使用。

触发条件

当用户要求以下内容时激活：

• 根据仓库或代码库生成论文结构、大纲或框架
• 扫描项目，并根据实验代码或结果创建论文各章节
• 从实验仓库/代码仓库生成论文大纲或论文结构

示例请求：

• “根据我的仓库生成论文大纲”
• “帮我从实验仓库生成论文大纲”
• “扫描我的项目并创建论文结构”
• “把我的代码仓库转成论文框架”

模式

模式	默认	行为
guided	是	完整的 5 步工作流；在每个标题层级确认，并按章节逐一生成正文
direct		不支持——大纲生成本质上需要用户在每个层级进行确认
batch		不支持——每个仓库都需要单独分析

默认模式： guided。分层确认设计是此 Skill 的核心。

参考资料

必需（始终加载）

文件	用途
references/repo-patterns.md	文件分类模式和章节映射规则
references/bilingual-output.md	双语输出格式（此 Skill 支持双语）
references/body-generation-rules.md	防止幻觉的规则、引文整合、双语格式、references.bib 算法
references/journals/ceus.md	CEUS 期刊格式规范（写作风格、章节指南）

叶节点提示

无。所有参考文件都列在 required 中，因为第 5 步的正文生成始终需要 CEUS 格式规范。

加载规则

• 在第 1 步开始时加载 repo-patterns.md 和 bilingual-output.md。
• 在第 5 步开始时加载 body-generation-rules.md 和 journals/ceus.md。
• 如果期刊模板文件缺失，则拒绝处理：“未找到 [X] 的期刊模板。可用模板：CEUS。”

提问策略

开始前，询问以下内容：

1. 仓库路径（必需）：“要扫描哪个仓库？”——如果可用，使用结构化交互
2. 目标期刊（可选）：“这篇论文面向哪个期刊？”——选项：CEUS、其他、无/通用。 如果选择 CEUS，则在第 2 步加载模板。如果选择“其他”，则询问期刊名称。如果选择“无”，则使用 IMRaD 默认格式。

双语模式： 根据触发请求推断。按照 references/bilingual-output.md 检查退出关键词 （确切短语：english only、no bilingual、only english、不要中文）。不要主动询问。

规则：

• 最多只问 2 个明确问题（仓库路径 + 期刊）
• 在 direct 模式下跳过提问——但此 Skill 不支持 direct 模式

工作流

步骤 0：工作流记忆检查

• 读取 .planning/workflow-memory.json。如果文件不存在或为空，跳至步骤 1。
• 检查最近 1–2 条日志是否与 ppw:repo-to-paper 构成已识别模式，且该模式在日志中出现次数 >= 阈值。完整算法请参阅 skill-conventions.md > Workflow Memory > Pattern Detection。
• 如果发现模式，通过 AskUserQuestion 提出建议：
  • 问题："检测到常用流程：[pattern]（已出现 N 次）。是否直接以 direct 模式运行 ppw:repo-to-paper？"
  • 选项："Yes, proceed" / "No, continue normally"
• 如果用户接受：将模式设为 direct，跳过 Ask Strategy 问题。
• 如果用户拒绝或 AskUserQuestion 不可用：以正常模式继续。
• **注意：**此 Skill 不支持完整的 direct 模式。如果用户接受建议，使用推断出的上下文跳过 Ask Strategy 问题（仓库路径、期刊），但保留所有引导式步骤检查点（步骤 2–5 的确认）。输出约定不变。

步骤 1：扫描仓库

准备：

• 加载 references/repo-patterns.md 和 references/bilingual-output.md
• 读取仓库目录结构（顶层 2 级：根目录和第一级子目录）
• 使用 repo-patterns.md 中的文件识别模式表对每个文件进行分类
• 对匹配多个类别的文件应用歧义规则（优先级数字最低者优先）
• 根据 repo-patterns.md 中的跳过规则，跳过隐藏文件、测试文件和二进制数据文件

展示：

• 显示分类汇总表：

  类别	找到的文件	关键项
  documentation	3	README.md, docs/overview.md
  results	5	results/metrics.csv, scores.json

• 标记缺失的类别："未找到 [category] 文件"

• 汇总行："已扫描 M 个类别中的 N 个文件。正在继续生成 H1 大纲……"

• 如果用户想要检查或更正，可以随时打断；否则自动继续至步骤 2

• **记录工作流：**将 {"skill": "ppw:repo-to-paper", "ts": "<ISO timestamp>"} 追加到 .planning/workflow-memory.json。如果文件不存在，则创建文件并写入 []。如果日志长度 >= 50，则删除最早的条目。

---

步骤 2：生成 H1 大纲

准备：

• 如果指定了期刊（例如 CEUS），加载 references/journals/[journal].md，并使用其中的 Section Guidance 标题作为 H1 结构。CEUS 章节：Abstract、Introduction、Study Area / Data / Methods、Results、Discussion、Conclusion
• 如果未指定期刊，使用 IMRaD 默认结构：Introduction、Methods、Results and Discussion、Conclusion
• 根据扫描汇总调整基础章节（例如，检测到空间数据时添加 "Study Area"）

展示：

• 显示 H1 标题及每个标题的一句话描述：

  # 1. Introduction
      Establish research context, literature gap, and contribution statement.
  # 2. Methods
      Describe the analytical approach, data sources, and model architecture.
  

• 双语：如果双语模式为 ON，使用 Markdown 引用格式为每条描述添加中文翻译：> **[Chinese]** ...，参阅 references/bilingual-output.md
• 汇总行："已生成 N 个 H1 章节。请在继续生成 H2 前确认、修改或添加内容。"
• 等待用户确认（"ok"）或提供修改说明

**修改时：**根据用户反馈修改 H1 标题并重新展示。循环直至确认。

章节调整示例：

• 如果扫描发现空间数据文件（shapefiles、GeoJSON）-> 考虑添加 "Study Area" H1 章节
• 如果扫描未发现结果文件 -> 为 Results 章节标记警告占位符
• 如果扫描发现多个不同的模型实现 -> 考虑将 Methods 拆分为多个子方法

步骤 3：生成 H2 大纲

准备：

• 对每个已确认的 H1 章节，阅读相关仓库文件以生成 H2 子标题
• 使用 repo-patterns.md 中的类别与论文章节映射，确定哪些文件 可为每个 H1 章节提供信息
• 阅读实际文件内容（引言部分读 README，方法部分读配置文件，结果部分读结果文件）——生成 H2 需要阅读内容，而不能只看目录结构
• 每个 H1 章节生成 2-4 个 H2 子标题，并为每个子标题写一句描述

展示：

• 展示完整的 H1 + H2 层级结构，并为每个 H2 标注来源：

  # 1. Introduction
  ## 1.1 Research Background and Motivation  <- from: README.md
      Urban heat island measurement requires fine-grained spatial analysis approaches.
  ## 1.2 Literature Gap and Contribution  <- from: README.md
      Existing methods lack integration of street-level semantics with thermal data.
  

• 来源标注：列出最直接相关的 1-3 个文件（按 repo-patterns.md 中的优先级排序）
• 双语：如果开启，在 > **[Chinese]** ... 引用块中添加中文描述
• 与步骤 2 使用相同的确认流程：“已在 M 个 H1 章节下生成 N 个 H2 子章节。请在继续生成 H3 前确认、修改或添加。”

---

步骤 2.5：文献收集

预检：

• 使用 {"query": "test", "limit": 1} 调用 mcp__semantic-scholar__papers-search-basic
• 如果调用成功：继续进行下方的文献收集
• 如果调用失败或工具不可用：完全跳过步骤 2.5
  • 在大纲中每个 H2 子章节描述后添加 [CITATION NEEDED]
  • 显示：“Semantic Scholar MCP 不可用。跳过文献收集。已添加 [CITATION NEEDED] 标记。”
  • 直接进入步骤 4（H3 生成）

收集参考文献：

对每个 H1 章节： 对该 H1 下的每个 H2 子章节： 1. 推导搜索查询：从 H2 标题和描述中提取 2-5 个关键技术术语， 并结合 H1 章节标题作为上下文。仅使用英文术语（双语模式下忽略中文翻译）。 去掉填充词（and、of、the、for）。 示例：H1="Methods"，H2="Gradient Boosting Prediction Framework"， 描述="Feature engineering using street-level semantic segmentation data" -> 查询："gradient boosting prediction street-level semantic segmentation" 2. 使用 {"query": derived_query, "limit": 10} 调用 mcp__semantic-scholar__papers-search-basic 3. 对于摘要字段为空的每条结果：使用论文的 paperId 调用 mcp__semantic-scholar__get-paper-abstract 获取摘要。如果获取后摘要仍为空，则标记为“摘要不可用” 4. 按相关性筛选结果：评估 H2 子章节需要提出多少个不同的论点或主张，然后保留 5-10 篇最能支持这些论点或主张的论文。根据标题和摘要内容，剔除仅有间接关联的论文 5. 显示进度行：✓ 1.1 Research Background: 8 refs found（如果没有结果，则显示 ⚠ 1.1 Research Background: 0 refs found） 6. 如果批次中途搜索调用失败：将该 H2 标记为 [CITATION NEEDED]，显示警告，然后继续处理下一个 H2 结束内层循环 结束外层循环

编写参考文献文件：

创建 {repo_path}/.paper-refs/ 目录。每个 H1 章节编写一个 Markdown 文件，文件名使用小写的章节主题（例如 introduction.md、methods.md、results.md）。

每个文件使用以下结构：

# [H1 Section Title] - References

## [H2 Number] [H2 Subsection Title]

### [FirstAuthor] et al. ([Year])
**Title:** [Full title from MCP]
**Authors:** [Author1; Author2; ...]
**Year:** [YYYY] | **Citations:** [N]
**Relevance:** [[H2 number] [H2 subsection title]]
[One-sentence explanation of why this paper is relevant to this subsection]

> [Abstract summary: 1-2 sentences from MCP abstract data. If abstract not available, write "Abstract not available"]

```bibtex
@article{[citationkey], ...}

BibTeX rules (reuse literature-skill patterns):
- Citation key format: `firstAuthorLastnameLowercaseYYYYfirstKeyword` (e.g., `smith2023urban`)
- Entry type: `@article` for journal, `@inproceedings` for conference, `@misc` for preprints (follow MCP paper type)
- All BibTeX fields MUST come from MCP-returned data. If a field is not in the MCP response, OMIT it
- If DOI missing, add comment: `% DOI not available -- verify manually`
- Never fill missing fields from prior knowledge

Duplicate handling: allow same paper to appear in multiple section files. Each file is self-contained.

**Display summary table:**

After all H2 subsections processed, display:

章节	子章节	参考文献数	代表性参考文献
1. Introduction	1.1 Research Background	8	Smith et al. (2023) - 142 citations
...	...	...
共收集 [N] 条参考资料。请确认是否继续生成 H3 大纲。

Wait for user confirmation before proceeding to Step 4.

---

### Step 4: Generate H3 Outline

**Prepare:**
- For each confirmed H2 subsection, read deeper file contents to generate H3 sub-sub-headings
- H3 captures specific technical details: individual model components, specific metrics,
  particular datasets, analysis steps
- Not every H2 needs H3 -- generate only where repo content supports further breakdown
  (typically Methods and Results). Generate 0-3 H3 entries per H2 subsection

**Present:**
- Display full H1 + H2 + H3 hierarchy with source annotations on H3 entries:

1.1 研究背景与动机

1.1.1 城市热岛测量挑战 <- 来源：README.md:L15-30

  当前城市热岛测量方法依赖分辨率有限的卫星影像。

- Bilingual: if ON, add Chinese descriptions in `> **[Chinese]** ...` blockquote format
- Same confirmation loop as Step 2: "Generated N H3 sub-subsections. Please confirm, modify,
or add. This completes the outline structure."

---

### Step 5: Body Generation

Step 5 auto-continues in the same session after H3 confirmation. It uses the H3 outline already in memory -- does not re-read `paper_outline.md`.

**Prepare:**
- Load `references/body-generation-rules.md` and `references/journals/ceus.md`
- Check if `{repo_path}/.paper-refs/` exists. If missing: note that all citation positions will use `[CITATION NEEDED]`
- Create `{repo_path}/.paper-output/` directory if it does not exist

**Section selection:**
- Display all H1 sections via AskUserQuestion (multiSelect):

AskUserQuestion({ question: "你希望我为哪些章节生成正文？", options: [ { label: "1. [H1 标题]", description: "[H2 小节摘要]" }, ...根据已确认大纲，为每个 H1 章节提供一个选项 ] })

- User selects which sections to generate in this session

**Generation loop (for each selected H1 section, sequentially):**

1. Read relevant repo files using the Category to Paper Section Mapping from `references/repo-patterns.md`
2. Read `{repo_path}/.paper-refs/{section}.md` if it exists -- extract `\cite{key}` citation keys
3. Generate full section `.tex` content following ALL rules in `references/body-generation-rules.md`:
 - `\section{}`, `\subsection{}`, `\subsubsection{}` LaTeX heading commands from confirmed H2/H3 structure
 - Academic prose following CEUS writing style from `references/journals/ceus.md`
 - `\cite{key}` inline citations (keys from `.paper-refs/` only; `[CITATION NEEDED]` for unsupported claims)
 - `[SOURCE: file:line]` annotations on all repo-derived claims (specific numbers, configs, model names)
 - `[RESULTS NEEDED]` / `[EXACT VALUE: metric]` for unknown quantitative data
 - Bilingual: `% --- Paragraph N ---` markers + `%` Chinese comment lines before each English paragraph (skip if opt-out detected)
4. Write to `{repo_path}/.paper-output/{section}.tex`
5. Display the generated section content to the user
6. AskUserQuestion for confirmation:

AskUserQuestion({ question: "第 [N] 节：[标题] 已生成。请查看上文。", options: [ { label: "确认", description: "接受本节并继续下一节" }, { label: "修改", description: "描述需要修改的内容（将重新生成整个章节）" }, { label: "跳过", description: "跳过本节并继续下一节" } ] })

- **Confirm:** proceed to next selected section
- **Modify:** user describes changes -> regenerate entire section -> re-display -> loop until confirmed
- **Skip:** move to next section without writing file

**After all selected sections confirmed:**
- Generate `references.bib` following the algorithm in `references/body-generation-rules.md`
- Display completion summary: number of sections generated, files written, references.bib entry count

## Output Contract

| Output | Format | Condition |
|--------|--------|-----------|
| `scan_summary` | Categorized summary table | Always -- Step 1 |
| `paper_outline` | Hierarchical H1/H2/H3 with descriptions and source annotations | After all steps confirmed |
| `literature_refs` | Per-section Markdown files in `{repo_path}/.paper-refs/` with reference cards | After Step 2.5 (skipped if MCP unavailable) |
| `body_text` | Per-H1 `.tex` files in `{repo_path}/.paper-output/` + `references.bib` | After Step 5 sections confirmed |

**Bilingual eligibility:** This Skill produces academic text (one-sentence heading descriptions).
Bilingual mode is ON by default; opt-out via keywords in `references/bilingual-output.md`.

After final H3 confirmation, offer to save the complete outline to a file using Write tool:
- Default filename: `paper_outline.md` in the repo root
- Include all heading levels with descriptions and source annotations
- Bilingual descriptions included if bilingual mode is ON

## Edge Cases

| Situation | Handling |
|-----------|----------|
| Empty repository (no recognized files) | Refuse: "No scannable files found in [path]. Please verify the repository path." |
| No README.md found | Warn in scan summary; proceed with available files; Introduction H2 will have limited source annotations |
| No result files found | Warn in scan summary; Results H2/H3 use placeholder: "[RESULTS NEEDED: add result files to populate this section]" |
| Journal specified but template missing | Refuse: "Journal template for [X] not found. Available: CEUS." |
| Non-Python repo | Warn: "Scan patterns are calibrated for Python ML projects. Non-Python files may be miscategorized." Proceed with best-effort |
| Very large repo (>500 files in top 2 levels) | List only top 10 files per category in scan summary; note total count |
| All files in one category | Proceed -- outline may be unbalanced; user corrects at confirmation step |
| Semantic Scholar MCP unavailable | Skip Step 2.5; insert [CITATION NEEDED] markers in outline; proceed to Step 4 |
| Zero search results for an H2 | Display warning with ⚠ prefix; mark H2 as [CITATION NEEDED]; continue to next H2 |
| MCP call fails mid-batch | Mark that specific H2 as [CITATION NEEDED]; continue with remaining H2 subsections |
| Springer papers with empty abstracts | Call get-paper-abstract; if still empty, display "Abstract not available" in ref card; still include paper |
| .paper-refs/ directory missing | Continue generating; all citation positions use `[CITATION NEEDED]` placeholders; do not block |
| User selects zero sections in Step 5 | Skip body generation entirely; display "No sections selected. Body generation skipped." |
| Modification loop exceeds 3 iterations | Proceed with current version; warn "Multiple revision cycles detected. Consider manual editing for fine adjustments." |

## Fallbacks

| Scenario | Fallback |
|----------|----------|
| Structured Interaction unavailable | Ask repo path and journal as plain-text questions |
| `references/repo-patterns.md` missing | Refuse: "Required reference file references/repo-patterns.md not found. Cannot categorize repo files." |
| `references/bilingual-output.md` missing | Proceed with English-only output; warn user |
| Journal template missing | Refuse with message from Edge Cases |
| Write tool unavailable | Present final outline in conversation; user saves manually |
| Semantic Scholar MCP unavailable | Skip Step 2.5 entirely; add [CITATION NEEDED] after each H2 description; warn user; proceed to H3 generation |
| `references/body-generation-rules.md` missing | Refuse: "Required reference file references/body-generation-rules.md not found. Cannot generate body text." |

## Examples

**Minimal invocation:** User provides repo path `~/projects/uhi-prediction/` and selects CEUS as target journal.

**Step 1 output (scan summary):**

类别	找到的文件数	关键内容
文档	2	README.md, docs/data-sources.md
配置	3	config.yaml, params.json, .env.example
结果	4	results/metrics.csv, results/ablation/
代码	8	src/model.py, src/train.py, src/eval.py
图表	3	figures/heatmap.png, figures/scatter.svg
依赖项	1	requirements.txt

已扫描 6 个类别中的 21 个文件。正在生成 H1 大纲……

**Step 2 output (H1 with CEUS template):**

1. 引言

阐述城市热岛预测问题及本研究贡献。
> **[Chinese]** 阐述城市热岛预测问题及本研究贡献。

2. 研究区域与数据

描述城市热岛分析的地理范围与数据来源。
> **[Chinese]** 描述研究区域范围及城市热岛分析的数据来源。

3. 方法

介绍梯度提升预测框架与特征工程。
> **[Chinese]** 介绍梯度提升预测框架与特征工程方法。

4. 结果

报告预测精度与空间格局分析结果。
> **[Chinese]** 报告预测精度与空间格局分析结果。

5. 讨论

结合城市规划和既有城市热岛研究解读发现。
> **[Chinese]** 在城市规划和既有热岛研究背景下解读发现。

6. 结论

总结研究贡献并指出局限性。
> **[Chinese]** 总结贡献并指出局限性。

已生成 6 个 H1 章节。请在继续生成 H2 之前确认、修改或添加内容。

User confirms. Steps 3-4 follow the same pattern with increasing detail and source annotations.

---

*Skill: repo-to-paper-skill*
*Conventions: references/skill-conventions.md*