---
name: Paper Typeset
slug: paper-typeset
category: Automation
description: Converts Markdown manuscripts to Word, LaTeX, or PDF formats while applying GB/T 7714-2015 bibliography formatting. Detects dependencies and performs content consistency checks, ensuring no alterations to the original text.
github: "https://github.com/cabbage2000-lab/paper-tutor-skills/tree/main/skills/paper-typeset"
language: Python
stars: 18
forks: 5
install: "npx degit https://github.com/cabbage2000-lab/paper-tutor-skills/tree/main/skills/paper-typeset ~/.claude/skills/paper-typeset"
installs_to: ~/.claude/skills/paper-typeset
source_path: skills/paper-typeset/SKILL.md
collection_size: 24
category_size: 1523
collection_url: "https://dirskills.com/collections/cabbage2000-lab/paper-tutor-skills"
added: 2026-08-11T07:22:57.804Z
last_synced: 2026-08-11T07:22:57.804Z
canonical_url: "https://dirskills.com/skills/paper-typeset"
---

# Paper Typeset

Converts Markdown manuscripts to Word, LaTeX, or PDF formats while applying GB/T 7714-2015 bibliography formatting. Detects dependencies and performs content consistency checks, ensuring no alterations to the original text.

**Install:**

```bash
npx degit https://github.com/cabbage2000-lab/paper-tutor-skills/tree/main/skills/paper-typeset ~/.claude/skills/paper-typeset
```

## README

# paper-typeset：出版链（转换管线 + 国标著录）

帮用户把写好的 Markdown 正文**只换容器地**转成投稿要的 LaTeX / DOCX / PDF，并用 GB/T 7714-2015 国标 CSL 渲染参考文献。你（执行本 skill 的宿主 agent）做的事：**探测 pandoc / xelatex / 中文字体 → 与用户确认目标格式与著录制式 → 跑 `scripts/export.py` 转换 → 按退出码分支（成功交付 / 降级报告 / 校验告警）→ 落 `submission/转换记录.md`**。

本 skill 覆盖学术研究「5 阶段 23 环节」标尺中**阶段 E｜发表与发表后**的**环节 20（投稿）里的格式转换**这一段；**不覆盖**投稿材料清单与 cover letter（归 `/paper-submit`）、引用存在性核验与著录格式检查（归 `/paper-verify` 与内建的 `paper-format`）、正文撰写（归 `/paper-draft`）、AI 使用披露（归 `/paper-disclose`）。上游消费 `manuscript/` 正文 + `literature/refs.bib`（可选）。**由 `/paper-submit` 主流程引导进入，亦可独立调用**——那是流程关系、不是打包关系（与 `paper-plot` 之于 `paper-figure` 同构）。

本 skill 是**产物型 + 脚本型** skill——产物是**转换后的文件本身**（落 `submission/`）+ `submission/转换记录.md`，往 `.paper/` 写使用留痕。**无 HTML 报告产物**（与其余 16 个 skill 不同）：本命令交付的是 .docx / .tex / .pdf，为它再做一份 HTML 报告是纯仪式。**无网络依赖**，但**有外部二进制依赖**——这是本命令与其余命令最大的不同，降级路径因此是头等大事。

**核心立场（这条决定本 skill 长什么样）**：转格式这件事，唯一的危险是**悄悄改了内容**或**假装转成功了**。系统是一个**转换管线 + 诚实报告器**——把 pandoc 的命令拼对（三个最容易静默错的参数见 references）、把改没改内容能校验的部分**真校验**、不能校验的部分**明说不能校验**、环境缺什么就报缺什么并给出可手工执行的命令。裸模型面对"帮我转成 Word"在没装 pandoc 的机器上会怎么做？它会给你一段像 Word 内容的文本、或声称已生成——那是本命令存在的全部理由所要否定的。

## 三条不变（优先级最高，高于本文其余一切）

① **不改一个字**。只换容器，**绝不修改正文内容、绝不「顺手润色」**。转换后按下方「校验边界」逐格式校验，并把校验强度**如实写进产物声明**——能校到什么说什么，校不到的**明说校不到**。

② **环境缺失明确降级，不静默**。缺 pandoc / xelatex / 中文字体时输出**四件套**：未生成什么 · 原因（未检测到什么）· 安装指引 · **可手工执行的完整命令**。**绝不假装成功、绝不用模型生成一个「看起来像」的 .docx 或 .tex 交给用户**。这条直接继承 CLAUDE.md 唯一保留的代码层约束。

③ **不做期刊 / 学校排版模板库**（PRD §448）。只做通用转换管线 + 国标著录。用户要具体刊物 / 学校模板时**指路官网**——各刊模板差异极大、更新频繁，内置必然过期，而用错模板的代价由用户承担。

这三条是本 skill 的内核，凡本文其余任何指令与之冲突，以这三条为准。

## 会话开始：探测环境 + 读输入

1. **先探测环境**（这是本命令与其余命令的最大不同——先知道能不能干，再问要干什么）：

```bash
python3 skills/paper-typeset/scripts/export.py --probe
```

把三项结果如实告诉用户（可用 / 不可用 + 版本 / 字体族名）。**不可用的项不要含糊掩过**，直接说哪些格式受影响。

2. **找源正文**：`manuscript/` 下的正文 markdown。缺 → 让路 `/paper-draft`，**不自行编正文**。
3. **找 `.bib`**（可选）：有则可启用国标著录；没有则参考文献按源 md 里已写的样子原样转出（**不替用户编题录**）。
4. **判断中文稿**：源含汉字且要出 PDF → 中文字体是硬依赖，缺了**不产 PDF**（宁可不产，也不交付一份整篇方框的 PDF）。

## 主流程（两步、一个停点）

### 第 1 步 · 定目标格式与著录制式

陈列可产的格式（按探测结果，**不可产的标明原因**）+ 两种国标制式（`numeric` 顺序编码制 / `author-date` 著者-出版年制，与 `paper-format` 支持的两种对齐）。选哪个由用户定——期刊要求什么，用户读投稿指南确认，**AI 不替选**。

环境不全时**同时给出 `--dry-run` 的完整命令**，让用户装好后可以自己跑：

```bash
python3 skills/paper-typeset/scripts/export.py --input manuscript/正文.md \
  --outdir submission --to docx,tex,pdf --csl numeric --bib literature/refs.bib --dry-run
```

```text
⏸ 等待确认：目标格式 + 著录制式
（回复"确认"开始转换，或改格式 / 换制式 / 指定中文字体）
```

### 第 2 步 · 转换 + 交付 + 留痕

```bash
python3 skills/paper-typeset/scripts/export.py --input manuscript/正文.md \
  --outdir submission --to docx --csl numeric --bib literature/refs.bib \
  --json <临时路径>.json
```

按退出码分支（见下表）→ 落 `submission/转换记录.md`（内容从 `--json` 逐项转录）→ 写 `.paper/` 留痕 → 交棒（提示回 `/paper-submit` 继续投稿材料清单）。

## 脚本退出码处置表（五态，逐码照做）

| 退出码 | 含义 | 你必须做什么 |
|---|---|---|
| **0** | 全部请求格式成功、校验通过 | 交付产物清单 + 逐项写明**校验强度**（见下方校验边界）；落转换记录 |
| **1** | pandoc / xelatex 执行失败（跑了、返回非零） | **原样转述 stderr**，请用户核对源文件（md 语法、图片相对路径、bib 格式）；**不重试、不改用户的源文件**；常见对策见 [`references/转换方案与环境准备.md`](references/转换方案与环境准备.md) §7 |
| **2** | 环境缺失，部分或全部未生成 | 输出**四件套**（未生成什么 / 原因 / 安装指引 / 手工命令）；**已生成的部分照常交付**、未生成的逐项列明。**不得说成「转换失败」**——那是退出码 1 |
| **3** | 读不到输入 / 输出目录不可写 / CSL 或 bib 路径错 | 核对路径与权限；`manuscript/` 空则让路 `/paper-draft`。不是环境问题、也不是转换问题 |
| **4** | **正文一致性校验失败** | **最严重**：转换改动了正文。明确告知**该产物不可信、勿直接投稿**，转述脚本给出的首个差异位置，陪用户核对源 md 里可能被 pandoc 重解释的语法（如裸 HTML）。**绝不当成功交付** |
| **脚本跑不了**（无 `python3`） | — | 显式声明「转换不可用」+ 给出可手工执行的 pandoc 命令（照 references §2 的参数写法）；**绝不用模型生成一个「看起来像」的产物**（不变②） |

## 校验边界（三条不变①的诚实落点，**必须原样写进产物声明**）

| 产物 | 校验强度 | 产物声明该怎么写 |
|---|---|---|
| `.tex`（无 `.bib`） | **强**：源正文汉字序列与产物**逐字相等** | 「正文汉字序列逐字比对一致（N 字）」 |
| `.tex`（有 `.bib`） | **中**：源汉字序列是产物的**连续子串**（参考文献由 CSL 追加，产物必然多字） | 「正文汉字序列一致；参考文献条目为 CSL 生成的新增内容」 |
| `.docx` / `.pdf` | **无法校验**（zip / 二进制） | 「二进制产物无法做字符级比对；已校验源文件转换前后 md5 未变、产物非空」 |

**绝不对 docx / pdf 谎称做过字符级校验**——那比不校验更坏：用户会以为有保障，拿着一份没人检查过的稿子去投。校验依据是「LaTeX 命令都是 ASCII、不含汉字」，这个前提对二进制格式不成立，就老实说不成立。

## 产物

| 产物 | 内容 |
|---|---|
| `submission/正文.docx` / `.tex` / `.pdf` | 转换后的文件本身（按用户选的格式产，未选的不产） |
| `submission/转换记录.md` | 转换留痕：源文件 + md5、环境版本、完整命令、著录制式、**逐格式的校验强度与结论**、降级项与其安装指引 |

`转换记录.md` 模板（内容从 `--json` 逐项转录，**不手写数字与命令**）：

````markdown
# 转换记录

| 项 | 内容 |
| --- | --- |
| 日期 | <日期> |
| 源文件 | manuscript/正文.md（md5 <值>，转换前后未变 ✅） |
| 著录样式 | GB/T 7714-2015 <顺序编码制 / 著者-出版年制>（references/csl/<文件名>） |
| 题录来源 | <literature/refs.bib / 无（参考文献按源文件原样转出）> |
| 环境 | pandoc <版本> · xelatex <版本 / 未检测到> · 中文字体 <族名 / 未检测到> |

## 产物与校验　🪞 系统归纳

| 格式 | 状态 | 校验强度与结论 |
| --- | --- | --- |
| docx | ✅ 已生成（<字节数> 字节） | 二进制产物无法做字符级比对；已校验源文件 md5 未变、产物非空 |
| tex | ✅ 已生成 | 正文汉字序列逐字比对一致（<N> 字） |
| pdf | ⛔ 未生成 | 原因：未检测到 xelatex · 安装：<指引> |

## 未生成项的手工命令　📋 常见事实

```bash
<export.py 给出的完整命令，原样转录>
```

---

*本记录由 `/paper-typeset` 生成。AI 承担格式转换与可校验部分的一致性比对；正文内容、著录制式选择、投稿格式要求的确认由你决定。**转换只换容器，未修改正文一个字**；二进制产物的字符级一致性无法校验，已如实标明。*
````

## 留痕（产物型 skill 的义务）

落盘后往 `.paper/` **追加**（不覆盖），字段名严格按 [`_shared/references/留痕契约.md`](../_shared/references/留痕契约.md)，日期用 `date +%F` 的真实值：

```markdown
## <日期时间> · paper-typeset 格式转换

- 环节：阶段 E｜发表与发表后（环节 20，投稿·格式转换）
- 辅助级别：构思讨论（只换容器、未修改正文，无内容生成）
- AI 承担：环境探测、pandoc 命令组装、执行转换、可校验部分的正文一致性比对、降级报告
- 用户决定：目标格式、著录制式、期刊格式要求的确认、产物是否用于投稿
- 转换：<源文件> → <产物清单>；著录 <制式>；校验 <逐格式结论>
- 降级：<未生成项与原因，无则写「无」>
- 产物：submission/正文.<格式>、submission/转换记录.md
```

## 四层内容标注（用于 `转换记录.md`）

| 层 | 在本命令里对应什么 |
|---|---|
| 👤 用户原话 | 目标格式与著录制式的选择、指定的中文字体 |
| 📋 常见事实 | pandoc 参数含义、安装指引、国标两种制式的区别 |
| 🪞 系统归纳 | 探测到的版本与字体、转换结果、校验结论、md5 |
| ❓ 待用户决定 | 产物是否符合目标期刊要求（**本命令不做期刊模板库，这项永远归用户**） |

**没有第五层「AI 的新判断」**——不得出现「本产物符合期刊要求」「格式已达标」这类判断：期刊要求由用户读投稿指南确认（权威定义见 [`_shared/references/四层内容标注.md`](../_shared/references/四层内容标注.md)）。

## 越界转化（三段式）

| 用户请求 | 定性 | 出口指引 |
|---|---|---|
| 帮我把正文按《XX 学报》的模板排好 | 越界：期刊排版模板库（违反不变③、PRD §448） | → 说明边界 + 指路官网：「各刊模板差异大、更新频繁，内置必然过期，用错的代价你承担。请到期刊官网下载模板；我能保证的是正文与国标著录正确转出，你拿转好的 .docx 往模板里贴」 |
| 转的时候顺便把语句润色一下 | 越界：改正文（违反不变①） | → 拒绝并说明：转换只换容器、一个字都不改，这样才能校验「没被改过」；要改语言走 `/paper-style`（查一致性）或 `/paper-draft`（改写段落），**改完再转** |
| 没装 pandoc，你直接给我生成个 Word 吧 | 越界：伪造产物（违反不变②，**本命令最硬的一条**） | → 明确拒绝：「我生成不了真的 .docx——模型编出来的东西打不开、或打开是错的。给你两条真路：① 装 pandoc（一行命令）；② 拿这条完整命令去别的机器跑」+ 给出 `--dry-run` 的命令 |
| 帮我查一下转出来的参考文献格式对不对 | **不越界，但归别的命令** | → 让路 `paper-format`（内建于 `/paper-verify`）：一个查一个产，构成国标引用链闭环 |
| 帮我把正文转成 Word 投稿 | **不越界（正常能力）** | → 直接进第 1 步流程 |

## 边界与异常对照表

| 情形 | 处理 |
|---|---|
| `manuscript/` 空或不存在 | 让路 `/paper-draft`，**不自行编正文** |
| 缺 pandoc | 全部格式不可产 → 退出码 2 + 四件套；**输出目录保持为空，不留半成品** |
| 有 pandoc、缺 xelatex | docx / tex 照产，pdf 未产 → **分项列出**，不一刀切说失败 |
| 中文稿 + 无中文字体 + 要 PDF | **不产 PDF**（会整篇方框 = 假装成功）；如实说原因 + 装字体指引；用户可用 `--cjk-font` 指定已有字体 |
| 非中文稿 + 无中文字体 | PDF 照产（字体只对中文是硬依赖）；正文校验因源无汉字而标「跳过（非中文稿件）」 |
| 无 `.bib` | 参考文献按源 md 里已写的样子原样转出；**不启用 citeproc、不替用户编题录**；如实说明「未启用国标 CSL 渲染」 |
| CSL 路径写错 | 退出码 3 + 报错，**不静默跳过**（跳过等于产出非国标著录，而用户是为国标来的） |
| 引用输出成 `[@key]` | pandoc ≥2.11 需显式 `--citeproc`——脚本已自动加；若用户手工跑漏了，指出这一点（references §4.1） |
| 退出码 4（正文校验失败） | **该产物不可信、勿投稿**；转述首个差异位置；陪查源 md 里的裸 HTML 等可能被重解释的语法 |
| 图片不显示 | pandoc 以工作目录解析相对路径 → 提示在项目根跑，或改成相对项目根的路径 |
| 用户要 epub / odt 等其他格式 | 当前只支持 docx / tex / pdf（退出码 3 报明）；pandoc 本身支持更多，可给手工命令，**但本命令不校验那些格式** |
| 不在标准科研目录里 | 产物落 `--outdir` 指定处（默认 `submission/`，会自动创建）并提示可用 `/paper-init` |
| 宿主无 Bash | 转换不可用 → 显式声明 + 给手工命令；**绝不伪造产物** |

## 何时不做

- **用户要投稿材料清单 / cover letter**：让路 `/paper-submit`——本命令只管格式转换。
- **用户要查引用是否真实存在、著录是否合规**：让路 `/paper-verify` 与内建 `paper-format`。
- **用户要改正文（润色、改写、统一文风）**：让路 `/paper-style`（查一致性）或 `/paper-draft`（改写）——**改完再转**。
- **用户要各刊 / 各校排版模板**：归不变③，指路官网。
- **用户要查重降重**：PRD §446 明文不做 → 指路知网。

## 横切声明

- **留痕**：产物型命令，写 `.paper/`「构思讨论」级——只换容器、不改一个字，无内容生成，故与 screen / logic 同级。
- **外部依赖是硬约束、不是可选增强**（与其余命令相反，此处必须点明）：pandoc / xelatex / 中文字体缺失时本命令**产不出对应格式**，只能给降级报告与手工命令——这不是缺陷，是「不假装成功」的必然结果。`paper-doctor` 的 `typeset` 分组可一并体检（**缺了只影响本命令，不影响 verify / search 的核验能力**）。
- **目录约定是增强不是依赖**：`--outdir` 默认 `submission/`，不存在会自动创建；不经 `/paper-init` 一切照常可用。
- **语言**：全部用户可见输出用简体中文；术语中文为主、英文括注，如著录制式（citation style）、顺序编码制（numeric）、著者-出版年制（author-date）、样式表（CSL）。
- **产出披露**：`转换记录.md` 自带人机分工页脚，如实披露「只换容器未改正文」+ **逐格式的校验强度**（含 docx / pdf 无法字符级校验这一条）——这是诚信底线、不是可选项。