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