---
name: o0000-code/manuscript-typeset
source: https://app.decimal.ai/s/o0000-code-manuscript-typeset@1/SKILL.md
source_sha256: 9a82eb131edd
---

# Manuscript Typeset

把一篇**已定稿的学术 Markdown 手稿**排成投稿版 / 发表预览版的通用排版 Skill。它不做内容写作——内容属别的 Skill；它做的是**版式变换**:md → 投稿 docx / 投稿 PDF / 发表预览 PDF / 干净 md 四件,附忠实性声明、占位符清单、剥离报告。上游任意写作 Skill(元分析 L12、系统综述、empirical-imrad-writing 等)成稿后产一份 `typeset_request.yaml` 调用它;也有独立触发场景("把这篇稿子排成投稿版")。

> **第一可执行入口**:§4 输入契约(`typeset_request.yaml`)+ §9 CLI。完整字段 schema 见 `references/MANUSCRIPT-INPUT-CONTRACT.md`,CLI 权威汇总见 `README.md`。

---

## 1. 忠实性纪律 = 本 Skill 的灵魂(先读这一段)

**排版层不得改动任何数字、引用或 claim——一个都不行。** 这不是一句承诺,是一条**脚本断言**:每件产物落盘前必过 `fidelity_check`——源(strip 后的 md)与产物(去 LaTeX 宏的 tex / 去 XML 的 docx 文本)逐 token 比对,**两条硬门(退出码 2,该件不落、整体阻断,无 `--warn-only`)**:①**任何在产物里出现、源里没有的数 → fail**——忠实渲染从不凭空造数(实测 EXTRA=0),故任何**注入或改动**(含纯整数计数:研究数、PRISMA 记录数、千分位样本量、表格单元格计数)必现形;②**任何载荷性数字或 DOI 缺失 → fail**——载荷=数据形数值(效应量/CI/p 值/%/τ²/权重)+ 标签绑定关系(k= / N= / p< …,**含关系符**,比较符翻转 `p<.001→p>.001` 也拦)+ DOI。**诚实边界(唯一未硬拦的方向)**:仅"**纯删除**"一个格式层合法重排的**裸整数**(参考文献页码 / DOI 内嵌年份 / 引擎另渲的标题计数,源里有产物合法省略)呈报供复核、不硬拦——改动永远拦,只有这类裸整数的静默删除落复核(详见 `references/FIDELITY-DISCIPLINE.md` §2/§4c)。

排版是版式变换,不是内容再加工。凡涉及改动数字 / 引用 / claim 的"优化"(顺手改个措辞、"修正"一个看着不对的数、自动翻译一句),一律**不属于本 Skill 的职责边界**——那是上游写作/核验 Skill 的事。实战范式一句话:*"No verified number, citation, or claim was altered."* 本 Skill 把它从"靠 agent 自觉 + 一句声明"升级为**机器强制门**,这是相对实战的核心增量。

**名值绑定边界(诚实,不假装覆盖)**:fidelity_check 的逐字比对天然覆盖"排版层改了正文的数"——改了必被抓。但它**对'输入件本身名值已错'无能为力**:若上游表格里 "Costa 的 0.77" 被错标成 "Abbott et al.",两侧看到的是同一份(错的)绑定,判等放行。这类"名字配错了数据"是**版式检查与数字比对之外的第三类检查**,超出排版层职责。凡交付物含 study 名↔数值绑定(表格 / 图注),BUILD_NOTES 明写此边界,建议上游 / 署名人抽查(见 `references/TYPESET-BUILD-NOTES-PATTERN.md`)。

---

## 2. 触发与适用场景

### 2.1 触发短语
**英文**:typeset manuscript、submission-ready manuscript、publication-ready、submission docx / PDF、APA 7 manuscript formatting、reference-docx、apa7 man/jou、camera-ready、strip internal traces。
**中文**:把 md 学术稿排成投稿版 / 发表版、出投稿 docx / PDF、投稿排版、发表预览、学术排版、内部痕迹剥离、生成投稿 Word。

### 2.2 反向触发(不适用 / 切到其他 Skill)
| 用户场景 | 切到 |
|---|---|
| 写 / 改内容本身(Intro/Method/Results/Discussion 措辞) | 对应写作 Skill(empirical-imrad-writing / meta-analysis L11 / systematic-review) |
| 参考文献核验 / 修 DOI / APA 格式化 | `academic-ref-check`(本 Skill **消费**其核验产物,不代做核验) |
| forest / funnel / PRISMA / RoB 图渲染 | `meta-analysis` 内置 ma-plots 渲染器 / `ssci-plots` |
| **编号制期刊**(Vancouver / AMA / NEJM 数字上标引用) | 须 CSL 档——**v2 延期**,见 §5 边界 |
| md 通用转 Word(非学术投稿规范) | `academic-paper-converter` 等通用转换 Skill |

### 2.3 定位:成稿出口 + 独立入口
- **成稿出口(主用法)**:写作 Skill 完成 md 定稿(含 SP7 核验过的参考列表)后,产 `typeset_request.yaml` 调本 Skill。**假设前提 = md 已定稿、引用已核验**——本 Skill 不回头改内容。
- **独立入口**:用户手上有一篇定稿 md("把这篇排成投稿版"),自行填 `typeset_request.yaml`(或让本 Skill 据 md YAML 头兜底元数据)即可跑。

---

## 3. 双引擎(各干各的,不强求单引擎)

| 产物 | 引擎 | 说明 |
|---|---|---|
| 投稿 **docx** | **pandoc + reference-apa7.docx** | APA 7 样式一次调校成 committed 资产;行号走 OOXML 后处理(stdlib,不依赖 python-docx) |
| 投稿 **PDF**(apa7 **man**) | **XeLaTeX + apa7 类** | 双倍行距 + 行号(`lineno`)+ 图表末置 + CJK 0 缺字 |
| 发表预览 **PDF**(apa7 **jou**) | **XeLaTeX + apa7 类** | 双栏单倍行距 + `\leftheader` 适配 + 悬挂缩进 0.18in + 宽内容 `\onecolumn` 末置 |
| **generic** PDF(兜底) | **XeLaTeX + 通用 article** | 无 apa7 类依赖时的单栏投稿兜底 |

**为什么不追求 pandoc 单引擎出 PDF**:apa7 的 man/jou 细节——自动 title page、running head、行号、de-float 末置结构、CJK unicode-map 逐字符映射、jou 双栏适配(leftheader/hang/onecolumn/de-float GRADE 表)——pandoc 的默认模板做不到。实战已把 LaTeX 这条路验证到 **0 error / 0 缺字 / 双 PDF 均成功编译**,故双引擎各司其职:docx 只走 pandoc + reference-docx,PDF 只走 LaTeX。docx 的 CJK 与复杂表格能力弱于 LaTeX,BUILD_NOTES 诚实标注每件质量状态。

---

## 4. 输入契约(权威 = `typeset_request.yaml`;G9 据此接线)

上游产 `typeset_request.yaml`,声明:`manuscript`(正文 md)/ `outputs`(请求的输出子集)/ `template_family`(apa7 | generic)/ `metadata`(题录,md YAML 头兜底)/ `references`(默认档 = 保真渲染)/ `tables`(`md:` pandoc 或 `raw_tex:` 直通双形态)/ `figures`(末置,顺序即呈现序)/ `strip_rules`(可选)/ `docx_line_numbers`(可选)。

**逐字段 schema、manuscript.md YAML 头约定、IMRaD 标题层级、metadata 覆盖规则,全文见 `references/MANUSCRIPT-INPUT-CONTRACT.md`**(这是 G9 接线的权威)。最小可跑样例 = `scripts/typeset_request.example.yaml`(指向 `scripts/tests/fixtures/smoke/` 的合成非元分析 IMRaD 稿,证通用性)。

### 4.1 四件输出 + 附件
请求的 `outputs` 子集,每件如 §3;此外**每次必产三份附件**:
- `BUILD_NOTES.md` — 忠实性声明 + recompile 指令 + 每件质量状态(页数 / 缺字数 / overfull)+ **名值绑定边界诚实声明**。模板见 `references/TYPESET-BUILD-NOTES-PATTERN.md`。
- `PLACEHOLDERS.md` — 占位符清单(author / affiliation / funding / corresponding,PDF/docx 内清楚标记,待用户填)。
- `STRIP_REPORT.md` — 剥离报告(剥了什么 / 留了什么 / 为什么——判断留痕)。

---

## 5. 引用:v1 只做默认档 + author-date 锁定边界

- **默认档(v1 唯一支持)** = 上游 **SP7 核验过的 md 参考列表 → 保真渲染**:解析 md(`## 组标题` 分组,如 Cited / Included / Excluded,每条一段)→ hanging-indent tex(man 0.5in / jou 0.18in)。**不引入 citeproc、不走 .bib**。
- **理由(R5-A10,比蓝图更强)**:风险不在 citeproc 格式化本身(它不改数据),而在"SP7 核验过的 APA 文本 → .bib 结构化"这步**无核验的再转换**——避开它 = 保住 **0 幻觉链**。上游引用真值已在核验产物里,排版层无权再加工。
- **author-date 锁定边界(诚实)**:默认档**只服务 author-date 制期刊(APA 系)**。投**编号制期刊(Vancouver / AMA)必须走 CSL 档**,且此时引用文本要重新过一遍核验——**CSL / .bib 通用引用档 = v2 账本 V6,显式延期**(首个编号制投稿需求时启用)。
- **治本接口愿望(additive,不阻塞 v1)**:handoff 给 `academic-ref-check` 一条愿望——核验时**同步产出 verified CSL-JSON 侧车**(核验器本就查 CrossRef/OpenAlex,结构化数据在手,顺手落盘零成本)。此后 CSL 档 = 同一核验真值的第二渲染,双档从"保真 vs 灵活"两难变成"同一真值两渲染"。

---

## 6. 内部痕迹剥离(strip)

排版前对**全部输入件(正文 + 参考 + 表格)**按 `strip_rules.yaml` 剥离内部过程痕迹,产剥离报告。这是实战发现的**新问题类别**:
- **剥离**:gate codes(`SP7 §3c` / `SP7 open item`)、内部 corpus ID(`papersearchpro-1628`,直接致 overfull hbox)、过程顶注(`L11 integrated final draft`)。
- **保留**:方法学披露(Method 里的 `SP1–SP7 sign-off gates` 是有意的监督流程披露)——strip 规则精确到能区分,判断入剥离报告留痕。
- **安全断言**:strip 只能删配置的痕迹模式,被删 span **不得含任何数字 / 引用 token**(strip_traces 自查,违规 exit 2)。
- 注:样本痕迹常在**参考文献与表格**而非正文(`SP7 §3c` 在 References、`papersearchpro-1628` 在 Table 1 ID 列)——strip 范围 = 全部排版输入件,别只 grep 正文。

`strip_rules` 缺失 → 恒等复制 + 报告声明"未配置"(不阻塞)。规则 schema 见 `references/STRIP-RULES-SPEC.md`(Lane C)。

---

## 7. 退出码契约(全脚本统一)

| 码 | 含义 |
|---|---|
| `0` | 成功(请求输出全建 + fidelity 全绿) |
| `1` | 输入 / 契约错(request 缺字段 / 文件缺失 / 硬依赖缺失且无降级)——硬 fail |
| `2` | **fidelity 断言失败 或 strip 安全违规**(数字 / 引用 / claim 变动)——铁律,不设 `--warn-only`,必阻断,不落该件 |
| `3` | 空(无正文可排) |

**依赖降级(honest)**:缺 xelatex → 降级为 **docx + md 两件**(请求的 PDF 件标记 skipped,stderr WARN + BUILD_NOTES 声明,整体 exit 0);缺 pandoc → 连 docx 不能出 → exit 1。**fidelity 失败永不降级**(码 2 硬阻断)。详见 §8 + README。

---

## 8. 依赖诚实(与 G10 doctor 对齐)

- **用户 runtime 硬依赖**:`pandoc`(docx 必需)、`xelatex`(TinyTeX,PDF 必需)、`python3` + `pyyaml`。
- **不依赖** `python-docx` / `lxml`:reference-apa7.docx 是 committed 二进制资产;docx 行号注入用 **stdlib** zipfile+xml。`make_reference_docx.py` 用 python-docx 仅 **dev-time**(重生成资产时),用户不需要。
- **字体**:Times New Roman(main)/ Songti SC 宋体(CJK)/ Heiti SC(CJK sans)——macOS 自带;缺字体探测 + 降级说明见 README + BUILD_NOTES。
- **探测**:`typeset.py` 启动查 `shutil.which('pandoc'/'xelatex')`,据此决定是否降级(见 §7)。降级路径权威汇总见 `README.md`。

---

## 9. CLI 概览(权威签名见 README)

编排器 `typeset.py` 读 `request` → `strip_traces`(所有输入件)→ 对每个请求引擎跑 `build_pdf` / `build_docx` → **对每件产物跑 `fidelity_check`(source=stripped 输入,rendered=该产物)** → 全绿才落该件;任一 fidelity fail(码 2)→ 该件不落 + 整体 exit 2 + 报告。产 BUILD_NOTES / PLACEHOLDERS / STRIP_REPORT。

四个底层脚本(`build_pdf.py` / `build_docx.py` / `strip_traces.py` / `fidelity_check.py`)+ 编排器 `typeset.py` 的**完整 CLI 签名、参数、机读摘要 JSON、退出码,权威汇总见 `README.md`**。

---

## 10. 边界与模板族(不过度工程)

- **模板族 v1** = `apa7`(man + jou)+ `generic`。APA 7 覆盖心理学 / 社科主战场,够第一版。
- `scripts/templates/<family>/` 只留**空槽位**(Elsevier / 双栏会刊等)——按真实需求再加 = **v2**,不预填。
- **不自动翻译**:表本地化(如中文 GRADE 表 → 英文)= 上游提供已本地化版本,走 `raw_tex:` 直通,本 Skill 绝不自译(违忠实性)。
- **CSL / .bib 通用引用档、编号制期刊、非 APA 期刊族** = v2 延期(§5 / §10 V6)。

---

## 11. 文件组织

```
manuscript-typeset/
├── SKILL.md                              本文件:触发 / 忠实性纪律 / 输入契约 / 双引擎 / 边界
├── README.md                             CLI 签名权威 + 依赖探测 + 降级路径 + 目录导览
├── LICENSE                               dual: PolyForm-NC 1.0.0 (code) + CC BY-NC-SA 4.0 (docs)
├── references/
│   ├── MANUSCRIPT-INPUT-CONTRACT.md      输入契约全文(G9 接线权威)
│   ├── TYPESET-BUILD-NOTES-PATTERN.md    BUILD_NOTES / 占位符 / 忠实性声明 / 名值边界 模板
│   ├── FIDELITY-DISCIPLINE.md            铁律 + 断言覆盖边界(Lane C)
│   └── STRIP-RULES-SPEC.md               strip_rules schema + 剥离报告格式(Lane C)
└── scripts/
    ├── typeset.py                        编排器(读 request → strip → 引擎 → fidelity gate → 四件+附件)
    ├── build_pdf.py / build_docx.py      PDF / docx 引擎
    ├── strip_traces.py / fidelity_check.py   剥离 + 忠实性门
    ├── typeset_request.example.yaml      最小可跑样例(指向合成非 MA 稿)
    ├── assets/tex/                        preamble-common / unicode-map / apa7-man/jou/generic 模板
    ├── assets/docx/reference-apa7.docx    APA7 样式 reference-docx(committed 资产)
    ├── templates/<family>/                v2 期刊族槽位(空)
    └── tests/                             各引擎回归 + fixtures/smoke 非 MA 冒烟稿
```