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. 先探测环境（这是本命令与其余命令的最大不同——先知道能不能干，再问要干什么）：

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 的完整命令，让用户装好后可以自己跑：

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

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

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

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 §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 逐项转录，不手写数字与命令）：

# 转换记录

| 项 | 内容 |
| --- | --- |
| 日期 | <日期> |
| 源文件 | 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，日期用 date +%F 的真实值：

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

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

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

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

没有第五层「AI 的新判断」——不得出现「本产物符合期刊要求」「格式已达标」这类判断：期刊要求由用户读投稿指南确认（权威定义见 _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 无法字符级校验这一条）——这是诚信底线、不是可选项。