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 冒烟稿