# LaTeX论文协作工坊

**Repository Path**: fiagainster/latex-paper-studio

## Basic Information

- **Project Name**: LaTeX论文协作工坊
- **Description**: 结合claude code一起协作论文吧！
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-10
- **Last Updated**: 2026-08-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LaTeX 论文写作协作环境

基于 Claude Code 的 LaTeX 学术论文写作协作工作区。集成 **34 个 AI 技能**，覆盖从研究构思、文献检索、论文撰写、科学绘图到同行评审的完整学术写作周期。

> **支持平台**：Windows（Git Bash）· macOS · Linux  |  LaTeX：MiKTeX / MacTeX / TeX Live

## 快速开始

### 第一步：环境准备

```bash
# 1. 安装 Python 依赖
pip install -r requirements.txt

# 2. （可选）配置 draw.io 桌面版路径，用于技术图表导出
cp .env.example .env
# 编辑 .env，设置你的 draw.io 路径，例如：
#   Windows: DRAWIO=C:\Program Files\draw.io\draw.io.exe
#   macOS:   DRAWIO=/Applications/draw.io.app/Contents/MacOS/drawio
#   Linux:   DRAWIO=/usr/bin/drawio
# 不配置也可正常使用——绘图会自动降级为 Mermaid / PlantUML / Excalidraw 或浏览器版

# 3. 检查环境是否就绪
python scripts/check_env.py
```

### 第二步：放入参考材料

| 材料类型         | 放在哪里                          | 格式     |
| ------------ | ----------------------------- | ------ |
| 论文思路、大纲、方法描述 | `references/`                 | `.md`  |
| 参考文献 PDF     | `literature/manual/`（按学科分子目录） | `.pdf` |

### 第三步：开始写作

在项目根目录打开 Claude Code，说：

> "请阅读 references/ 下的参考材料，在 output/ 下撰写论文并编译为 PDF"

**智能体会自动执行「写作前准备门控」**：读取参考材料 → 检查文献充分性（不足则自动搜索 arXiv 补充）→ 规划图表（自动调用对应绘图 Skill 生成）→ 确认章节结构 → 开始撰写。你只需确认大纲即可。

### 第四步：获取 PDF / 导出 Word

编译成功后，PDF 位于 `output/main.pdf`。

**导出 Word 版本**（保留格式和三线表，交叉引用可点击）：

```bash
python scripts/export_word.py output/main.tex --reference-doc "output/论文模板.docx"
```

Word 打开后 `Ctrl+A → F9` 刷新域代码即可。

### 第五步：继续修改

论文初稿完成后，在项目目录下继续对话即可：

> "修改第三章第二段的论证逻辑"
> "加一张XX的对比图"
> "补充一篇关于数字经济的文献"

**智能体会自动检测已有论文，进入修改模式**——跳过准备门控，直接定位修改位置，精确替换，编译验证。详见下方「迭代修改」章节。

---

## 核心工作流

### 🔴 写作前准备门控（智能体自动执行）

在动笔写任何 LaTeX 代码之前，智能体会自动完成以下检查：

| 门控                | 内容                          | 自动动作                                                                     |
| ----------------- | --------------------------- | ------------------------------------------------------------------------ |
| **G1 读取参考**       | 列出并读取 `references/` 下所有 .md | 提取论文主题、论点、方法、结构                                                          |
| **G2 文献检查**       | 按研究脉络逐条检查文献覆盖度              | 任一脉络不足 3 篇 → 自动 arXiv 搜索补充；有未解析 PDF → 自动批量解析                             |
| **G3 图表规划**       | 列出论文所需全部图表 + **图表叙事流检查**    | 架构图 → draw.io、流程图 → Mermaid、数据图 → matplotlib…；检查图表之间逻辑依赖，确保仅看图就能还原故事线    |
| **G4 结构确认**       | 给出章节大纲                      | 不确定处向用户确认，通过后开始写作                                                        |
| **G4.5 论点对抗（可选）** | 从审稿人视角审视核心论证链               | 调用 `peer-review` + `scientific-critical-thinking` 压力测试，输出 Top 3 薄弱点与防御策略 |

> **🆕 草稿模式**：如果只是想快速起草理清思路，说"快写"或"草稿"即可跳过 G2/G3/G4.5，用占位符标记待补充内容，快速产出可编译 PDF。详见下方「草稿模式」章节。

### 📝 论文写作

```
┌─────────────────────────────────────────────────┐
│  阶段 A：准备（G1-G4 门控）                       │
│  references/ → 阅读 → 文献检查 → 图表规划 → 确认  │
│  用户确认 ↓                                       │
├─────────────────────────────────────────────────┤
│  阶段 B：撰写                                     │
│  output/main.tex ← 写作中同步生成图表、补充文献     │
│              ↓                                    │
├─────────────────────────────────────────────────┤
│  阶段 C：编译修复（循环直到 0 错误 0 警告）         │
│  bash scripts/build.sh output/main.tex            │
│  有错误？→ 查 debugging-guide → 修复 → 重编译      │
│              ↓                                    │
├─────────────────────────────────────────────────┤
│  阶段 D：输出                                     │
│  output/main.pdf  ✅ 报告页数、图表数、引用数       │
│              ↓                                    │
│  阶段 D.5：审稿（可选）← 🆕                        │
│  三 Skill 并行审稿 → 结构化报告（严重/建议/优势）    │
│              ↓                                    │
│  阶段 E：导出 Word（可选）                         │
│  python scripts/export_word.py output/main.tex    │
│  output/main.docx  ✅ 保留格式和交叉引用            │
└─────────────────────────────────────────────────┘
```

> **🆕 快捷路径——草稿模式**：说"快写"或"草稿" → 跳过 G2/G3 → 用 `\textbf{[待引用]}` / `\todo{}` 占位 → 直接写作编译 → 产出草稿 PDF + 追踪清单。详见下方「草稿模式」章节。

`build.sh` 每次编译后自动报告：Overfull/Underfull hbox、未定义引用、总页数。

### 🚀 草稿模式 / 快写模式（新增）

**不是每次写作都需要完整的门控流程。** 当你想快速探索思路、草拟某个章节、或先搭框架再细化时，直接用对话触发草稿模式：

| 你说什么             | 智能体做什么                                              |
| ---------------- | --------------------------------------------------- |
| "帮我快速起草一个引言"     | 跳过文献/图表门控 → 用占位符标记待补充处 → 写 Introduction → 编译出 PDF   |
| "先搭个方法论框架，不用管文献" | 确认主题 → 列出章标题 → 写 Methods → `\textbf{[待引用]}` 占位 → 编译 |
| "草稿模式，写第三章的实验设计" | 跳过 G1-G4 → 直接写该章 → 编译 → 报告追踪清单（几处待补充）               |

**草稿模式会自动使用以下占位符**：

- 缺失文献 → `\textbf{[待引用: 关键词/领域]}`
- 缺失图表 → `\textbf{[此处插入图 N：图表描述]}`
- 待确认论点 → `\todo{需要确认: 具体疑问}`（编译后在 PDF 页边距可见）

**草稿写完后**，说"正式写"或"进入完整模式"→ 智能体以草稿为参考，重跑 G1-G4 完整门控，逐步将占位符替换为实际内容。

> 草稿模式 ≠ 修改模式：草稿模式是从零快速创建，修改模式是在已有论文上增量修改。详见 [CLAUDE.md](CLAUDE.md) 中「草稿模式 / 快写模式」章节。

### 📂 多论文支持（新）

`output/` 支持两种目录结构：

```
# 单论文模式（默认）
output/main.tex

# 多论文模式
output/论文A/main.tex
output/论文B/main.tex
```

智能体会自动检测 `output/` 下的论文，列出清单让你选择。说"新建论文"即可创建新论文子目录，说"切换到 XX 论文"即可切换工作上下文。`literature/`、`templates/`、`scripts/` 在所有论文间共享，只有 `output/<论文名>/` 内文件是论文隔离的。

### 🔄 迭代修改（已有论文继续改）

论文初稿完成后，智能体会自动检测 `output/main.tex` 并进入**修改模式**——跳过需求澄清和门控检查，直接响应你的修改指令。

**从草稿升级到正式论文**：如果你是从草稿模式起步的，说"正式写"→ 智能体以草稿为参考材料，重跑 G1-G4 完整门控，将 `\textbf{[待引用]}` 等占位符替换为实际内容。

**修改模式支持的六种操作：**

| 操作       | 示例指令            | 智能体自动处理                         |
| -------- | --------------- | ------------------------------- |
| **文本修改** | "修改第三章第二段的论证"   | 定位→Edit 替换→编译验证→报告关联影响          |
| **结构调整** | "把第四章拆成两章"      | 确认新结构→更新交叉引用→编译                 |
| **图表修改** | "把架构图改一下，加入数据流" | 找到源文件→修改→重新导出→编译                |
| **新增图表** | "加一张XX的对比图"     | 走绘图决策树→生成→导出→插入引用               |
| **文献增删** | "补充一篇关于XX的文献"   | academic-search→下载→解析→BibTeX→引用 |
| **审稿回复** | "根据审稿意见改"       | 逐条解析→分类处理→逐条修改→编译               |

**修改→编译→审查 快速循环**：

```
用户说"修改XX"
  → 智能体 Grep 定位 + Read 上下文
  → Edit 精确替换（只改需要改的部分，不动其余内容）
  → bash scripts/build.sh output/main.tex
  → 报告：改了什么 + 编译结果 + 页数变化
  → 主动提议增量审稿（可选）——仅审改动的段落
```

每次修改后立即编译验证，错误当场修复。编译成功后主动提议增量审稿和 Word 导出。重大结构调整前智能体会提示你 `git commit` 保存快照。

### 🎨 科学绘图（9 个引擎）

| Skill                       | 引擎                  | 适用场景          |
| --------------------------- | ------------------- | ------------- |
| `drawio-skill`              | draw.io             | 技术架构图、流程图     |
| `creating-mermaid-diagrams` | Mermaid             | 思维导图、时序图      |
| `excalidraw`                | Excalidraw          | 手绘白板风格        |
| `plantuml-skill`            | PlantUML            | UML 类图、组件图    |
| `tldraw-skill`              | TLdraw              | 自由画布          |
| `scientific-schematics`     | 多引擎                 | 科学原理图         |
| `scientific-visualization`  | matplotlib/pgfplots | 数据可视化         |
| `academic-plotting`         | matplotlib          | 出版级图表         |
| `markdown-mermaid-writing`  | Mermaid             | Markdown 写作配图 |

**draw.io 使用说明**：draw.io 需要桌面版 CLI 来导出 PNG/SVG/PDF。如未安装或未配置，drawio-skill 会自动降级使用浏览器版（diagrams.net 在线编辑链接），或选择 Mermaid/PlantUML/Excalidraw 等其他引擎——不影响论文写作流程。

### 📄 Word 导出（新）

一条命令从 LaTeX 源码导出 Word 文档，尽最大努力保留格式：

```bash
python scripts/export_word.py output/main.tex --reference-doc "output/论文模板.docx"
```

**自动处理**：

- 参考文献编号 + 可点击跳转（REF 域代码，F9 刷新）
- 三线表（顶底粗线 + 表头下细线，无竖线）
- 首行缩进 + 宋体/Times New Roman
- bullet 列表 → `•` 符号
- OMML 原生公式（可双击编辑）
- 标题/附录编号冻结为静态文本

**依赖**：`pip install tex2word bibtexparser lxml python-docx`

### 🔍 同行评审（新）

论文编译成功后，智能体会主动提议进行同行评审。支持两种模式：

**完整审稿**（论文初稿完成后）：

| 审稿维度 | Skill                          | 检查内容                 |
| ---- | ------------------------------ | -------------------- |
| 同行评议 | `peer-review`                  | 方法论缺陷、文献盲区、论证漏洞、替代解释 |
| 逻辑审查 | `scientific-critical-thinking` | 循环论证、因果跳跃、过度概括、样本偏差  |
| 贡献评估 | `scholar-evaluation`           | 创新性、与现有文献的差异化程度      |

三技能并行审稿后，输出结构化报告：

- 🔴 严重问题（建议必须修改）→ 具体位置 + 修改建议
- 🟡 改进建议（可选改进）
- 🟢 论证优势（应在导论中强调）
- 📋 下一步建议

**增量审稿**（修改模式每次编译后）：仅审本轮改动的段落 + 前后衔接处，检查是否引入新问题、引用是否连贯、与前后文是否一致。

> 审稿与 G4.5（写作前论点对抗）互补：G4.5 侧重论证链结构性薄弱点，审稿侧重已写成文字的方方面面。

### 📖 文献管理

```
literature/
├── index.json          ← 📋 文献结构化索引（AI 自动维护：摘要、论点、适用章节、文献间关系）
├── manual/             ← 用户手动分类存放 PDF（按学科分子目录）
├── auto/               ← API 自动下载（arxiv/YYYY-MM/）
└── parsed/             ← 解析后的 Markdown（镜像 manual/ + auto/ 结构）
```

**智能体阅读文献流程**：

1. 检查 `literature/parsed/` 是否已有解析缓存 → 有则直接 Read
2. 无缓存 → `python scripts/pdf_reader.py paper.pdf -o literature/parsed/.../paper.md`
3. 提取 DOI → `bash .claude/skills/latex-document/scripts/fetch_bibtex.sh 10.xxxx/...` → 写入 BibTeX
4. 自动更新 `literature/index.json`（记录摘要、关键论点、适用章节、文献间对话关系）

**文献索引（`literature/index.json`）**：每读完一篇文献，AI 自动将其结构化信息写入索引——包括一句话摘要、2-5 条关键论点、适用于论文的哪些章节、与其他文献的对话关系（支持/扩展/反驳）。后续写作时，AI 会先查索引而非逐个打开 .md 文件，大幅减少上下文消耗。

**自动文献补充**：当智能体检测到文献不足 3 篇时，会按学科自动选择最优检索源：

| 论文领域 | 自动使用源 | 命令示例 |
|---------|-----------|---------|
| CS/数学/物理/统计 | arXiv | `fetch_papers.py --query "transformer attention" --max 5 --parse` |
| 政治学/社会学/法学/教育 | **OpenAlex** | `fetch_papers.py --source openalex --concept political_science --max 5 --parse` |
| 经济学/管理学 | **OpenAlex** | `fetch_papers.py --source openalex --concept economics --max 5 --parse` |
| 历史/哲学/文学 | **Crossref** | `fetch_papers.py --source crossref --max 5` |
| 中文社科文献 | **OpenAlex --lang zh** | `fetch_papers.py --source openalex --lang zh --max 5 --parse` |
| 跨学科/不确定 | **三源并行** | `fetch_papers.py --source all --max 10 --parse` |

**三源覆盖范围**：

| 源 | 论文数 | 文科覆盖 | 特点 |
|----|--------|---------|------|
| **arXiv** | 250 万+ | ❌ 仅 CS/数学/物理 | 默认源，PDF 直链，镜像自动切换 |
| **OpenAlex** | 2.4 亿+ | ✅ 全学科 + 中文 | 免费 API，ML 概念分类，OA PDF 检测 |
| **Crossref** | 1.45 亿+ | ✅ 含图书章节 | DOI 权威元数据，出版商级信息 |

**arXiv 下载可靠性**：内置镜像自动切换（`arxiv.org` → `export.arxiv.org` → `cn.arxiv.org`）+ 每次最多 3 次重试（指数退避）。中国大陆用户无需额外配置代理。

```bash
# arXiv 搜索 + 下载 + 自动解析
python scripts/fetch_papers.py --query "digital economy" --max 5 --parse

# 批量解析 manual/ 下的所有 PDF（自动镜像子目录结构）
python scripts/parse_literature.py --batch literature/manual/

# 单文件解析（自动推断输出路径）
python scripts/parse_literature.py --file literature/manual/经济学/paper.pdf

# 试运行（仅列出，不实际解析）
python scripts/parse_literature.py --batch literature/manual/ --dry-run
```

### 📚 文献搜索（5 个引擎）

| Skill                   | 覆盖平台                                                                                                                                            |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `academic-search`       | arXiv / Semantic Scholar / OpenAlex / Crossref / PubMed / Google Scholar / CNKI / ACM DL / IEEE Xplore / Springer / Wiley / ScienceDirect / ACS |
| `research-lookup`       | 并行网络检索                                                                                                                                          |
| `semanticscholar-skill` | Semantic Scholar 专项                                                                                                                             |
| `asta-skill`            | Semantic Scholar MCP 工具                                                                                                                         |
| `paper-fetch`           | PDF 下载                                                                                                                                          |

### 🎯 期刊选刊匹配（新）

帮论文找到适合投稿的期刊。两个脚本配合：`journal_finder.py`（免费检索）+ `journal_impact.py`（影响因子/分区/预警）。

**核心用法——读论文自动选刊**（换论文即可自动响应，无需人工整理关键词）：

```bash
# 读论文自动推荐（自动提取标题/英文关键词/英文摘要）
python scripts/journal_finder.py --paper output/main.tex

# 只看社科域（SSCI 近似）+ 带影响因子/分区/预警
python scripts/journal_finder.py --paper output/main.tex --ssci --impact

# 只要免版面费期刊（订阅制默认免费，排除纯 OA 收费刊）
python scripts/journal_finder.py --paper output/main.tex --ssci --no-apc

# 显式关键词覆盖自动提取
python scripts/journal_finder.py --paper output/main.tex --keywords "digital economy, political economy"
```

**按主题 / 刊名 / ISSN 检索**：

```bash
python scripts/journal_finder.py --topic "premature deindustrialization"   # 主题（统计该主题发文量最高的期刊）
python scripts/journal_finder.py --query "econometrics"                    # 刊名关键词
python scripts/journal_finder.py --issn 0028-0836                          # ISSN 精确定位
python scripts/journal_finder.py --id S137773608                           # OpenAlex 来源 ID
```

**影响因子 / 分区 / 预警**（独立使用，或 `--impact` 附带查询）：

```bash
python scripts/journal_impact.py "Structural Change and Economic Dynamics" "World Development"
python scripts/journal_finder.py --topic "political economy" --impact
```

| 参数 | 说明 |
|------|------|
| `--paper <tex>` | 读 LaTeX 论文自动提取关键词并推荐期刊（泛化入口） |
| `--keywords` | 显式英文关键词，覆盖自动提取（逗号分隔） |
| `--ssci` | 只看社科域期刊（SSCI 近似：`domain=Social Sciences`，**非** Clarivate 官方标记） |
| `--no-apc` | 只看免版面费期刊（订阅制默认免费；OA 仅钻石 OA 免费，混合 OA 的 APC 不强制） |
| `--impact` | 附带查询影响因子/分区/预警（byteslink，需 key） |
| `--sort cited/hindex/citedness` | 按总被引 / h-index / 2 年篇均被引排序 |

**选刊匹配原理**：`--paper` 从论文自动提取英文关键词，对每个关键词做主题检索并按**关键词特异性（IDF）加权**——稀有词（如 `premature deindustrialization`）权重高、泛词（如 `institutional capacity`）权重低，避免泛词冲淡主题；自动剔除工作论文/预印本/会议/报告系列等非期刊来源。

> **数据源与免责**：期刊主题/引用指标来自 OpenAlex（免费、无需密钥）；影响因子/分区/预警来自 byteslink 期刊数据开放 API（第三方公开数据，2026-06-17 版）。**SSCI/SCIE/ESCI 收录标记是 Clarivate 专有索引信息，免费源无法提供**，且 2023 年起 ESCI 期刊也进入 JCR 获得影响因子，故「有 JIF ≠ SSCI」。投稿前请到 Clarivate Master Journal List（mjl.clarivate.com，免费）逐本核实。

**环境配置**（仅影响因子/分区/预警需要，检索本身免费无需配置）：

```bash
# .env 中添加（期刊数据开放 API，https://api.byteslink.cn/journals 用户中心生成）
BYTESLINK_API_KEY=你的密钥
# OpenAlex 免费无需密钥；可选 OPENALEX_API_KEY 提升限速
```

> 换一篇论文只需 `--paper output/<新论文>/main.tex`，系统自动提取关键词并推荐，无需人工整理。

---

## 项目结构

```
latex论文协作/
├── .env.example             ← 环境配置模板（复制为 .env 后编辑）
├── .env                     ← 你的本地配置（不会被提交到 git）
├── .gitignore               ← Git 忽略规则
├── CLAUDE.md                ← Claude 工作流程定义
├── README.md                ← 本文件
├── requirements.txt         ← Python 依赖
│
├── references/              ← 📝 你的写作思路 .md
├── output/                  ← 📦 论文 .tex + 编译产物
│
├── literature/              ← 📚 文献存储
│   ├── index.json           ←    📋 文献结构化索引（AI 自动维护）
│   ├── README.md
│   ├── manual/              ←    手动导入的 PDF（按学科分子目录）
│   ├── auto/arxiv/          ←    API 自动下载的 PDF
│   └── parsed/              ←    解析后的 Markdown（镜像结构）
│
├── templates/               ← 📄 模板
│   ├── academic-paper.tex   ←    学术论文 LaTeX 模板
│   ├── references.bib       ←    BibTeX 示例
│   └── paper-figure-template.drawio ← 论文配图模板
│
├── scripts/
│   ├── config.py            ←    draw.io 路径自动检测
│   ├── check_env.py         ←    一键环境检测
│   ├── build.sh             ←    LaTeX 编译 + 诊断报告
│   ├── pdf_reader.py        ←    PDF → 结构化 Markdown
│   ├── parse_literature.py  ←    批量文献解析
│   ├── fetch_papers.py      ←    arXiv API 搜索 + 下载 + 解析
│   ├── batch_export.py      ←    批量 .drawio → PNG/SVG/PDF
│   ├── export_word.py       ←    LaTeX → DOCX（保留格式+交叉引用）
│   ├── fix_crossrefs.py     ←    DOCX 引用升级为 REF 域代码
│   ├── compare_docx.py      ←    .docx 格式对比分析
│   ├── journal_finder.py    ←    期刊查询/选刊匹配（OpenAlex 免费）
│   ├── journal_impact.py    ←    影响因子/分区/预警查询（byteslink）
│   └── academic-search/     ←    学术搜索辅助脚本
│
└── .claude/
    ├── settings.json        ←    权限配置
    └── skills/              ← 🤖 34 个 AI 技能
```

---

## 常用命令速查

```bash
# ── 环境 ────────────────────────────
python scripts/check_env.py                           # 一键环境检测
python scripts/config.py                              # JSON 格式输出配置信息

# ── 编译 ────────────────────────────
bash scripts/build.sh output/main.tex                 # 基本编译（多遍 + 诊断）
bash scripts/build.sh output/main.tex --verbose       # 详细编译日志
bash scripts/build.sh output/main.tex --clean         # 编译后清理辅助文件

# ── 文献获取 ────────────────────────
python scripts/fetch_papers.py --query "关键词" --max 5            # arXiv 搜索 + 下载（默认）
python scripts/fetch_papers.py --query "关键词" --max 3 --parse    # 搜索 + 下载 + 解析
python scripts/fetch_papers.py --source openalex --query "..." --max 5 --parse  # OpenAlex（人文社科）
python scripts/fetch_papers.py --source openalex --query "..." --lang zh --max 5 # OpenAlex 中文文献
python scripts/fetch_papers.py --source crossref --query "..." --max 5          # Crossref（图书章节/DOI 元数据）
python scripts/fetch_papers.py --source all --query "..." --max 10 --parse      # 三源并行去重
python scripts/fetch_papers.py --id 2401.12345                     # 下载指定 arXiv 论文
python scripts/fetch_papers.py --id "10.xxxx/..."                  # 通过 DOI 获取单篇
python scripts/fetch_papers.py --list-concepts                     # 列出 OpenAlex 学科概念

# ── 文献解析 ────────────────────────
python scripts/pdf_reader.py paper.pdf -o literature/parsed/manual/.../paper.md
python scripts/parse_literature.py --batch literature/manual/      # 批量解析（自动镜像子目录）
python scripts/parse_literature.py --file literature/manual/经济学/paper.pdf  # 单文件（自动推断输出路径）
python scripts/parse_literature.py --batch literature/manual/ --dry-run

# ── 期刊选刊匹配 ────────────────────
python scripts/journal_finder.py --paper output/main.tex                 # 读论文自动选刊
python scripts/journal_finder.py --paper output/main.tex --ssci --no-apc  # 社科域+免版面费
python scripts/journal_finder.py --paper output/main.tex --ssci --impact  # 社科域+IF/分区/预警
python scripts/journal_finder.py --topic "关键词" --max 15               # 按主题检索
python scripts/journal_finder.py --query "关键词"                         # 按刊名检索
python scripts/journal_impact.py "期刊A" "期刊B"                          # 影响因子/分区/预警

# ── Word 导出 ────────────────────────
python scripts/export_word.py output/main.tex \                    # LaTeX → DOCX
  --reference-doc "output/论文模板.docx"                            # （含交叉引用+三线表+缩进）
python scripts/fix_crossrefs.py output/main.docx                   # 单独升级引用为 REF 域代码
python scripts/compare_docx.py a.docx b.docx                       # 两个 .docx 格式对比

# ── 绘图导出 ────────────────────────
python scripts/batch_export.py -d output/                          # 批量 .drawio → PNG/SVG/PDF

# ── LaTeX 工具 ──────────────────────
python .claude/skills/latex-document/scripts/validate_latex.py output/main.tex
python .claude/skills/latex-document/scripts/csv_to_latex.py data.csv
bash .claude/skills/latex-document/scripts/fetch_bibtex.sh 10.xxxx/...
python .claude/skills/latex-document/scripts/generate_chart.py bar --data '...' --output chart.png

# ── 迭代修改常用 ────────────────────
# 直接对话即可，智能体自动处理：
#   "修改第三章XX部分"     → 定位+Edit+编译验证+增量审稿
#   "加一张XX的图"         → 绘图决策树+生成+导出+引用
#   "补充一篇XX文献"        → 搜索+下载+解析+BibTeX+引用+更新索引
#   "根据审稿意见改"        → 逐条解析+逐条修改+编译
#   "帮我审一下这篇论文"     → 三技能并行审稿→结构化报告
#   "新建论文" / "切换到XX"  → 多论文管理
```

---

## 长文格式保障（5 页以上论文）

编译前 Claude 自动检查 9 大反模式（来源：`long-form-best-practices.md`）：

| #   | 反模式                       | 正确做法                                       |
| --- | ------------------------- | ------------------------------------------ |
| 1   | `<` `>` 裸角括号（PDF 显示为 ¡ ¿） | `$<$` / `$>$`                              |
| 2   | 图片宽度过大                    | `0.75-0.85\textwidth`（不超过 0.90）            |
| 3   | 用 `[H]` 强制浮动体位置           | 用 `[htbp]` 让 LaTeX 自动优化                    |
| 4   | `\newpage` 强制分页           | 让文本自然流动                                    |
| 5   | Widow/Orphan 孤行           | `\widowpenalty=10000` `\clubpenalty=10000` |
| 6   | 列表未压缩                     | `\setlist[itemize]{nosep, leftmargin=*}`   |
| 7   | 大量 itemize 代替 prose       | 正文用段落，列表仅用于枚举                              |
| 8   | `%` `$` `&` `#` `_` 未转义   | 文本模式中需 `\%` `\$` `\&` `\#` `\_`            |
| 9   | 绝对尺寸而非相对单位                | 优先 `\textwidth` `\linewidth`               |

## 常见编译错误速查

| 错误                           | 原因                      | 解决                              |
| ---------------------------- | ----------------------- | ------------------------------- |
| `Undefined control sequence` | 命令拼写错误或缺少 `\usepackage` | 检查拼写或添加 package                 |
| `Missing $ inserted`         | 数学符号在文本模式               | 用 `$...$` 包裹                    |
| `File 'xxx.sty' not found`   | 缺少宏包                    | LaTeX 发行版自动安装，重试即可       |
| `Overfull \hbox`             | 内容溢出边距                  | `\usepackage{microtype}` + 调整措辞 |
| `Citation 'xxx' undefined`   | 引用未定义                   | 检查 .bib 文件或 `\bibliography` 路径  |
| `<` / `>` 在 PDF 中显示为 ¡ / ¿   | 文本模式用了裸角括号              | 改用 `$<$` / `$>$`                |

---

## 环境要求

### 必需

| 组件 | 说明 | 安装 |
|------|------|------|
| **LaTeX 发行版** | 编译 PDF | Windows: [MiKTeX](https://miktex.org/) · macOS: `brew install --cask mactex` · Linux: `sudo apt install texlive-full` |
| **Python 3.10+** | 运行辅助脚本 | `pip install -r requirements.txt` |
| **Bash** | 运行 shell 脚本 | Windows: [Git Bash](https://git-scm.com/) · macOS/Linux: 系统自带 |
| **Claude Code** | AI 写作助手 | [claude.ai/code](https://claude.ai/code) |

### 可选：draw.io 桌面版

本项目使用 draw.io 桌面版 CLI 导出 `.drawio` 文件为 PNG/SVG/PDF。**draw.io 不是必需的**——如未安装或未配置，绘图会自动降级：

| 降级方案                | 说明                                 |
| ------------------- | ---------------------------------- |
| 浏览器版 (diagrams.net) | 通过 `encode_drawio_url.py` 生成在线编辑链接 |
| Mermaid             | 流程图、时序图、思维导图（纯文本，无需安装）             |
| PlantUML            | UML 类图、组件图                         |
| Excalidraw          | 手绘白板风格                             |

**如需安装 draw.io：**

1. 下载安装：https://github.com/jgraph/drawio-desktop/releases
2. 配置路径（三选一）：
   - **方式 A（推荐）**：`cp .env.example .env`，编辑 `.env` 设置 `DRAWIO=你的路径`
   - **方式 B**：设置环境变量 `DRAWIO` 指向可执行文件
   - **方式 C**：安装到系统 PATH（macOS `brew install --cask drawio` 自动完成）
3. 验证：`python scripts/check_env.py`

### 可选：Graphviz

用于大型图表（>15 节点）的自动布局：

```bash
# macOS:  brew install graphviz
# Linux:  sudo apt install graphviz  (或 dnf install graphviz)
# Windows: https://graphviz.org/download/
```

---

## 技能来源与致谢

本项目集成了来自多个优秀开源项目的技能包，感谢所有贡献者：

| 来源                                                                                               | 集成内容                                                 |
| ------------------------------------------------------------------------------------------------ | ---------------------------------------------------- |
| [LaTeX Document Skill](https://github.com/ndpvt-web/latex-document-skill) by HappyCapy AI        | LaTeX 写作核心：27 个模板、27 个脚本、26 份参考指南                    |
| [sci-plotter](https://github.com/OpenRaiser/sci-plotter) by OpenRaiser                           | 9 个绘图/文献 skill + 4 个脚本 + 配色参考                        |
| [AI-Research-SKILLs](https://github.com/username/AI-Research-SKILLs)                             | 5 个学术写作与研究构思 skill                                   |
| [academic-search](https://github.com/username/academic-search)                                   | 多平台文献检索（arXiv/Semantic Scholar/PubMed/CNKI 等 14 个平台） |
| [claude-scientific-writer](https://github.com/username/claude-scientific-writer)                 | 11 个论文写作/评审/投稿 skill                                 |
| [scientific-agent-skills](https://github.com/username/scientific-agent-skills)                   | 6 个统计分析与科学可视化 skill                                  |
| [research-skills](https://github.com/username/research-skills)                                   | 研究提案生成 skill                                         |
| [stats-paper-writing-agent-skills](https://github.com/username/stats-paper-writing-agent-skills) | 统计论文写作 skill                                         |
| [PaperFit](https://github.com/OpenRaiser/PaperFit) by OpenRaiser                                 | 五类层次化排版缺陷分类体系的思路启发                                   |

---

**License:** MIT

---

## 更新日志

### 2026-08-14 — 期刊选刊匹配工具

**新增功能：**

- **🎯 期刊选刊匹配（`journal_finder.py` + `journal_impact.py`）**：帮论文找到适合投稿的期刊。
  - **读论文自动选刊（`--paper`）**：从 LaTeX 主文件自动提取标题/英文关键词/英文摘要，按关键词特异性（IDF）加权做主题检索，自动剔除工作论文/预印本等非期刊来源——换一篇论文即可自动响应，无需人工整理。
  - **免费检索（OpenAlex）**：`--topic`（主题）/ `--query`（刊名）/ `--issn` / `--id`，展示学科分类、h-index、2 年篇均被引、OA/APC 等指标。
  - **影响因子/分区/预警（byteslink）**：`--impact` 附带 JIF/JCR 分区/中科院分区/预警名单，或独立 `journal_impact.py` 查询。
  - **筛选参数**：`--ssci`（社科域近似）、`--no-apc`（免版面费）、`--sort`（按引用指标排序）。
- **文档**：新增 `output/选刊报告.md`（本论文 SSCI 选刊推荐 + 复现命令）。

**免责说明**：SSCI/ESCI 收录标记为 Clarivate 专有索引，免费源无法提供；「有 JIF ≠ SSCI」，投稿前需到 Master Journal List 逐本核实。

### 2026-07-09 — 文献索引、多论文支持、审稿阶段

**新增功能：**

- **📋 文献结构化索引（`literature/index.json`）**：AI 每读完一篇文献自动写入结构化条目——一句话摘要、2-5 条关键论点、适用章节、文献间对话关系。G2 文献检查优先查索引，写作时按章节匹配可引用文献。解决"文献读完就忘"的上下文丢失问题。
- **📂 多论文支持**：`output/` 支持 `output/论文名/main.tex` 多论文子目录结构。智能体自动检测论文列表，支持"新建论文"、"切换到 XX 论文"。`literature/`、`templates/`、`scripts/` 所有论文共享，输出文件隔离。
- **🔍 同行评审阶段（阶段 5.5 + 增量审稿）**：论文编译成功后主动提议审稿。完整审稿（三 Skill 并行：`peer-review` + `scientific-critical-thinking` + `scholar-evaluation`）→ 结构化报告（严重/建议/优势）。修改模式每次编译后支持增量审稿（仅审改动段落+衔接处）。

**流程改进：**

- G0 模式判断扩展为三层（新写作→单论文→多论文）
- G2 文献检查增加索引优先策略
- 阶段 6.3 修改循环增加步骤 5（增量审稿提议）
- README 新增审稿章节、多论文支持章节、文献索引说明

### 2026-07-07 — 流程优化：草稿模式、论点对抗、图表叙事流

**新增功能：**

- **🚀 草稿模式 / 快写模式**：说"快写"或"草稿"即可跳过 G2/G3 门控，用 `\textbf{[待引用]}` 和 `\todo{}` 占位符快速起草，编译出可追踪的草稿 PDF。完成后说"正式写"切回完整门控流程。
- **🛡️ 论点对抗与打磨（G4.5）**：结构确认后，可选触发审稿人视角的压力测试——用 `peer-review` + `scientific-critical-thinking` + `hypothesis-generation` 三技能审视论证链，输出 Top 3 薄弱点与防御策略。
- **🔗 图表叙事流检查（G3.1）**：图表规划增加"独立可读性测试"和"逻辑依赖检查"——确保读者仅浏览图表及其标题就能还原论文核心故事线。

**流程改进：**

- G0.5 工作模式判断增加第三条分支（草稿模式检测）
- 多轮循环架构增加草稿模式路径和可选论点对抗子循环
- G2/G3 门控增加草稿模式跳过条件
- 阶段 6 增加"从草稿升级到正式写作"切换路径
- Skill 矩阵 E 类增加论点对抗触发条件

### 2026-07-06 — 系统优化

**新增功能：**

- **写作前准备门控**：智能体在动笔前自动完成 G1-G4 四项检查（参考材料读取、文献充分性、图表规划、结构确认），通过后方可写作
- **绘图 Skill 自动触发**：10 类关键词 → Skill 映射，5 条强制触发规则（框架/流程/比较/数据/机制），写作中同步生成图表
- **文献搜索自动触发**：文献不足 3 篇时自动搜索 arXiv 补充，根据论文主题自动生成英文搜索词

**问题修复：**

- **arXiv 下载可靠性**：移除废弃的 v2.x 兼容代码，新增 3 个镜像自动切换（`arxiv.org` → `export.arxiv.org` → `cn.arxiv.org`），每次下载最多重试 3 次（指数退避 2s/4s/8s），修复流式下载响应体读取 bug
- **单文件解析路径**：`parse_literature.py --file` 现在自动推断输出路径——PDF 在 `literature/manual/` 下则自动镜像到 `literature/parsed/manual/`，不再错误地放到 `parsed/` 根目录
- **批量解析路径修复**：`parse_literature.py --batch` 修复子目录路径丢失 `manual/` 前缀的 bug。改为基于 `literature/` 目录计算完整相对路径，确保 `literature/manual/任意/子目录/` → `literature/parsed/manual/任意/子目录/`
- **draw.io PDF 导出单页裁剪**：所有 draw.io 图表导出 PDF 时统一加 `--crop` 标志，裁剪到图面实际尺寸、单页输出，避免跨页断裂
- **图片排版优化**：LaTeX `\includegraphics` 统一使用 `width=\textwidth,height=0.88\textheight,keepaspectratio`，确保图片不超出页面边界
- **newtxmath 冲突修复**：移除 `newtxmath`（与 `ctexart` 的 `\openbox` 已定义冲突），保留 `newtxtext` 提供 Times 正文字体