用 OfficeCLI 生成学术论文 docx：引用样式、OMML 方程、SEQ/PAGEREF 交叉引用与双栏期刊排版实战指南

本指南讲解如何用 OfficeCLI 把 .docx 从"格式好看的商务文档"升级为真正的学术论文：承载 APA / Chicago / IEEE / MLA 四种正式引用样式、编号方程（OMML）、图表自动编号与页码交叉引用、悬挂缩进参考文献、多栏期刊布局，以及第一页的摘要 / 关键词 / 单位信息块。读完本文，你将掌握以 officecli 命令行语义路径 API 从零构建一篇可交付的学术论文（期刊 / 会议 / 学位论文章节）的完整流程，并能用可执行的交付门禁做 QA。

本文对应仓库中的技能文档 skills/officecli-academic-paper/SKILL.md。它是一层构建在 officecli-docx 技能之上的场景层——docx 的所有硬性规则（样式架构、标题层级、shell 引号、分页规则、活页码字段、交付门禁、渲染器怪癖）都被继承而非重述；本文只补充学术论文额外需要的东西：引用样式、方程、SEQ / PAGEREF 交叉引用、多栏期刊布局、参考文献悬挂缩进、摘要 / 关键词 / 单位块。

学术技能是什么：继承 docx v2 的"场景层"

officecli-academic-paper 明确将自己定义为 officecli-docx 之上的场景层（scene layer），"Every docx hard rule — style architecture, heading hierarchy, shell quoting, page-break rules, live PAGE field, Delivery Gate, renderer quirks — is inherited, not re-taught"。因此使用本技能的前提是先读 skills/officecli-docx/SKILL.md 的 v2 规则：如何加段落、设样式、建表格、插图片、管理目录 / 页脚 / 页眉、强制分页、跑交付门禁。若这些还不熟悉，先开一个会话把 docx v2 过一遍。

环境准备

如果 officecli 尚未安装：

• macOS / Linux：curl -fsSL https://d.officecli.ai/install.sh | bash
• Windows (PowerShell)：irm https://d.officecli.ai/install.ps1 | iex

验证：officecli --version（若 PATH 未生效请新开终端）。安装脚本在仓库中也有对应文件：install.sh、install.ps1、dev-install.sh。如果安装失败，可从官方发布页下载单二进制文件——OfficeCLI 是免费、开源、单二进制的工具，无需安装 Office。

⚠️ Help-First 规则

本技能"教学术论文需要什么，而不是每一个命令 flag"。当不确定某个属性名、枚举值或字段指令时，先查 help，不要猜：

officecli help docx                          # 所有 docx 元素
officecli help docx <element>                # 完整 schema（如 section, equation, field, footnote）
officecli help docx <element> --json         # 机器可读

Help 与安装的 CLI 版本绑定。当技能文档和 help 冲突时，以 help 为准。技能文档中每个 --prop X= 都经过对 officecli help docx <element> 的 grep 验证——若后续版本 help 增加 / 重命名了属性，相信 help。

Shell 与执行纪律

shell 引号、增量执行、$FILE 约定与 docx v2 完全一致：始终给 [N] 路径加引号，任何含 $ 的值用单引号包裹（正文里的 $2.8B、DOI 里的 @ 都是如此），可执行示例中绝不手写 \$ \t \n，一次只跑一条命令。学术示例统一用 $FILE 作为 shell 变量（FILE="thesis.docx"）。

"学术"意味着什么：六个增量

学术论文 = 带学术层的 docx：可验证的引用、精确的方程、保持同步的交叉引用、格式化的参考文献表。基础 docx 规则照常适用，学术层增加六个差异点：

1. 引用样式是一种契约。 APA / Chicago / IEEE / MLA 各自规定作者格式、日期位置、参考文献表排序、正文标记形状。开工时先选一个，之后所有决策（悬挂缩进、脚注 vs 圆括号、[1] vs (Smith, 2024)）都跟着它走。
2. 方程是一等公民——正文内联 oMath、独立展示 oMathPara 块，可选编号。
3. 图和表自动编号。 SEQ Figure / SEQ Table 字段负责计数；PAGEREF 把"见 Fig. 2"链接到活的页码。
4. 参考文献用悬挂缩进（首行顶格、续行缩进），不是首行缩进，也不是单纯左缩进——就是悬挂。
5. 摘要 / 关键词 / 单位块是第一页的三件套，不是营销意义的封面。摘要块式排版，无首行缩进，无装饰。
6. 多栏布局出现在 IEEE / ACM / Nature 及大量期刊：单栏摘要 + 双栏正文。

反向交接：何时回到 docx v2

白皮书、政策简报、技术报告、HR 模板——凡是没有"投稿对象 / 引用样式"的文档，留在 docx v2。只有当文档至少携带以下两项时才用本技能：引用样式参考文献、方程、SEQ/PAGEREF 交叉引用、多栏、摘要 + 关键词块。

工作流：五个动词

1. 读投稿要求（venue spec）。 APA 7 / Chicago 17 / IEEE / MLA 9 或期刊专属规范。行距、字体、引用形状、参考文献排序——之后一切都由这一个决策决定。
2. 规划章节。 摘要 → 关键词 → 引言 → 方法 → 结果 → 讨论 → 结论 → 参考文献。预估标题数量以决定是否加目录（3+ 个 Heading1 就加 TOC，见 docx v2 §Table of Contents）。
3. 先定义样式。 Heading1 / Heading2 / Heading3 / Caption / AbstractTitle / Bibliography 全部在写内容之前定义好（→ 见 docx v2 §Paragraphs and styles，规则相同，跳过则失败模式相同）。
4. 按顺序构建正文。 封面 / 标题块 → 摘要 → 关键词 → 目录（如需）→ 正文各节按阅读顺序 → 带 SEQ 标题的图表 → 参考文献 → 脚注最后按段落路径添加。
5. QA —— 交付门禁。 继承 docx v2 的 Gate 1-3，再增加下面的学术 Gate 4-5。

学术底线（在 docx v2 之上）

排版（视投稿要求而定）

• 字体。 正文默认 Times New Roman 11-12pt，或按投稿要求（IEEE 用 Times 10pt 双栏；APA 允许 Calibri 11pt）。全文同一正文字体；不用装饰性标题字体。
• 标题层级。 H1 = 20pt 粗体，H2 = 14pt 粗体，H3 = 12pt 粗斜体，正文 = 11-12pt。（与 docx v2 数字相同——重申是因为学术论文从不依赖 Word 默认值。）
• 行距。 APA 7 = 2x 双倍；Chicago / IEEE / 多数期刊 = 1.5x。绝不低于 1.15x。正文段落和参考文献都要设置。
• 页边距。 四边 1 英寸（1440 twips），除非投稿要求另有说明（有些期刊左侧需要 1.25in 供装订——查规范）。

摘要、参考文献、标题位置

• 摘要是块式。 无 firstLineIndent，用 spaceAfter=12pt 分隔段落。如果 view issues 报"正文段落缺少首行缩进"，在摘要段落上是误报，忽略。
• 参考文献悬挂缩进。 每条目一个段落，indent=720 hangingIndent=720（左缩进 0.5"，首行反向等量）。首行顶格；换行缩进到作者名之下。
• 图标题在图下方，表标题在表上方。 这是非学术界最容易犯的一条——APA、Chicago、IEEE、MLA 全部一致。
• 引用往返。 每个正文引用键必须能在参考文献表中找到对应条目。交付门禁 4 验证。
• SEQ 在场。 任何带编号图表的论文必须携带活体 SEQ Figure / SEQ Table 字段（而不是硬编码的 "Figure 1" 文本——中途插入新图就会漂移）。交付门禁 5 验证。

封面 / 首页块

学术封面不同于商务封面。最少元素：标题（居中，20-22pt 粗体）、作者、单位、投稿对象 / 期刊、日期、摘要、关键词。docx v2 的"60% 填充"规则（§Visual delivery floor）仍然适用——三行封面配半页留白就是失败。见下文"首页块"配方。

章节编号约定（STYLE-DEPENDENT——不要盲目套用）

学术章节号是标题文本的一部分，不是通过列表编号计算的。officecli 的 numId/listStyle 机制在 Heading1 复用时易碎，所以手写前缀。但前缀形状因样式而异——四种样式不要用同一形式：

样式	H1 格式	H2 格式	示例
APA 7	无编号居中粗体	无编号左对齐粗体	Introduction / Methods（居中）
Chicago	"N. Title" 左对齐	"N.M Title"	1. Introduction、2.1 Policy Formation
IEEE	"N. TITLE" 全大写 + 罗马数字	A. Subtitle 标题式大小写	I. INTRODUCTION、II. RELATED WORK、A. Datasets
MLA 9	无编号左对齐粗体	同左	Literature Review（无前缀）

APA 7 的 L1 标题居中、粗体、无编号；L2 左对齐粗体；L3 左对齐粗斜体；L4/L5 run-in。不要给 APA 标题加 1. / 2. 前缀——那是 Chicago/IEEE 的约定。IEEE 要全大写 + 罗马数字（I. INTRODUCTION）；节内用 A./B./C. 子标题（标题式大小写）。阿拉伯数字正文章节是 Chicago 风格专属。

四种样式的共同例外：References / Bibliography / Works Cited / Acknowledgments 无论何种样式都不编号——省略 N. 前缀。

快速开始：最小 APA 论文

以下十行骨架构建一篇完整的最小 APA 论文：

FILE="paper.docx"
officecli create "$FILE"
officecli open "$FILE"
officecli set "$FILE" / --prop defaultFont="Times New Roman"
officecli add "$FILE" /body --type paragraph --prop text="Remote Work and Team Cohesion" --prop align=center --prop size=20pt --prop bold=true --prop spaceAfter=24pt
officecli add "$FILE" /body --type paragraph --prop text="Alice Chen" --prop align=center --prop size=12pt
officecli add "$FILE" /body --type paragraph --prop text="Department of Psychology, Stanford University" --prop align=center --prop size=11pt --prop spaceAfter=24pt
officecli add "$FILE" /body --type paragraph --prop text="Abstract" --prop align=center --prop size=14pt --prop bold=true --prop spaceBefore=12pt --prop spaceAfter=6pt
officecli add "$FILE" /body --type paragraph --prop text="This study examines remote-work adoption on team cohesion across 18 months..." --prop size=12pt --prop lineSpacing=2x --prop spaceAfter=12pt
officecli add "$FILE" /body --type paragraph --prop text="Keywords: remote work, team cohesion, psychological safety" --prop italic=true --prop size=11pt --prop spaceAfter=18pt
officecli add "$FILE" /body --type paragraph --prop text="1. Introduction" --prop style=Heading1 --prop size=20pt --prop bold=true --prop spaceBefore=18pt --prop spaceAfter=12pt
officecli add "$FILE" /body --type paragraph --prop text="Remote-work research (Smith, 2024) has expanded since 2020..." --prop size=12pt --prop lineSpacing=2x --prop firstLineIndent=720
officecli add "$FILE" /body --type paragraph --prop text="References" --prop style=Heading1 --prop size=20pt --prop bold=true --prop spaceBefore=18pt --prop spaceAfter=12pt
officecli add "$FILE" /body --type paragraph --prop text="Smith, J. (2024). Remote work and cohesion. Journal of Applied Psychology, 109(3), 412-430." --prop size=12pt --prop lineSpacing=2x --prop indent=720 --prop hangingIndent=720
officecli add "$FILE" / --type footer --prop type=default --prop align=center --prop size=10pt --prop field=page
officecli close "$FILE"
officecli validate "$FILE"

注意此处用了 APA 的 1. Introduction 前缀作示例演示（实际 APA 应为无编号居中，见上一节约定）；骨架通过 validate。真实论文在此基础上增加更多正文段落、更多参考文献条目（每条同样的 indent=720 hangingIndent=720 组合）、带标题的图表、以及 3+ 个 Heading1 时的目录。

引用样式配方

四种主流引用样式家族，开工时选一种，之后所有下游决策随之而定。

样式	正文标记	参考文献表排序	正文行距	脚注？
APA 7	(Smith, 2024) 或 Smith (2024)	按作者字母序	2x（双倍）	罕见（仅内容注释）
Chicago 17 (Notes-Bib)	上标脚注号	按作者字母序	1.5x-2x	主要（脚注中完整引文）
IEEE	[1]、[2]、…、[N]	首次引用顺序	1.15x-1.5x，双栏	罕见
MLA 9	(Smith 412) 页码	按作者字母序，"Works Cited"	2x	罕见

四种共享默认：参考文献段落 indent=720 hangingIndent=720（悬挂缩进 0.5"）；3+ 个 Heading1 加活体 TOC（→ 见 docx v2 §Table of Contents）；设 updateFields=true 并把 TOC 页码报告为"未计算"，直到 Word 兼容的字段引擎更新。

APA 7（社会科学——心理学、教育学、管理学）

• 正文：(Author, Year)；叙事式用 Author (Year)。直接引语必须带页码：(Smith, 2024, p. 15)。三位及以上作者首次引用后：(Smith et al., 2024)。
• 参考文献排序：按第一作者姓氏字母序。标题大小写：文章标题用句首式大小写（sentence case），期刊名用标题式大小写（斜体）。
• 参考文献形状：Author, A. A., & Co-Author, B. B. (Year). Title of article. Journal Name, Volume(Issue), pages. DOI 优先于 URL；以 https URL 呈现，不用 doi: 前缀。
• 全文双倍行距（lineSpacing=2x），包括摘要和参考文献。正文首行缩进 = 0.5"（firstLineIndent=720）。

# 带圆括号引用的正文段落
officecli add "$FILE" /body --type paragraph --prop text="Remote work adoption accelerated during the pandemic (Kramer & Kramer, 2020)." --prop size=12pt --prop lineSpacing=2x --prop firstLineIndent=720
# 悬挂缩进的参考文献条目
officecli add "$FILE" /body --type paragraph --prop text="Kramer, A., & Kramer, K. Z. (2020). The potential impact of the Covid-19 pandemic on occupational status. Journal of Vocational Behavior, 119, 103442." --prop size=12pt --prop lineSpacing=2x --prop indent=720 --prop hangingIndent=720
# DOI 超链接追加到参考文献段落
officecli add "$FILE" "/body/p[last()]" --type hyperlink --prop url="https://doi.org/10.1016/j.jvb.2020.103442" --prop text="https://doi.org/10.1016/j.jvb.2020.103442"

QA：officecli query "$FILE" 'paragraph[hangingIndent]' 应返回每一条参考文献；零条用首行缩进代替悬挂缩进。

Chicago 17 — 注释-书目（人文学科——历史、哲学、宗教）

• 正文：上标脚注号；完整引文放第一个脚注（Timothy Brook, The Troubled Empire (Cambridge, MA: Harvard UP, 2010), 142.）；此后用缩写形式（Brook, Troubled Empire, 150.）。
• 重复引用规则（Chicago 17，op. cit. 已弃用）：
  • 紧邻连续引用同一来源同一页 → Ibid.
  • 紧邻连续、不同页的同一来源 → Ibid., 22.
  • 非连续重复 → 缩写形式（Brook, Troubled Empire, 150.），不是 op. cit.。Chicago 17 弃用 op. cit.——除紧邻重复外一律用缩写形式。
• 文末 Bibliography 按第一作者姓氏字母序（"Brook, Timothy."），悬挂缩进。脚注正文在查看器中按脚注默认渲染（通常 10pt）；参考文献条目 12pt。（footnote 元素只暴露 text——每条脚注字号不可单独设置；信任渲染器默认。）
• 史料密集型论文的典型切分：单个 Bibliography Heading1 下用两个 Heading2：Primary Sources 和 Secondary Sources。脚注和参考文献中的书名都斜体。
• Chicago 也有 Author-Date 变体用于科学领域——若投稿指定 Chicago Author-Date，退回 APA 配方、只改标点（作者和年份间无逗号：(Smith 2024)）。

# 锚定脚注的正文段落，然后是脚注本身
officecli add "$FILE" /body --type paragraph --prop text="The Ming dynasty's 海禁 policy shaped coastal trade for two centuries." --prop size=12pt --prop lineSpacing=1.5x --prop firstLineIndent=720
officecli add "$FILE" "/body/p[last()]" --type footnote --prop text="Timothy Brook, The Troubled Empire: China in the Yuan and Ming Dynasties (Cambridge, MA: Harvard University Press, 2010), 142."
# 下一个脚注——缩写形式
officecli add "$FILE" "/body/p[last()]" --type footnote --prop text="Brook, Troubled Empire, 150."
# Bibliography 区拆分——先原始文献
officecli add "$FILE" /body --type paragraph --prop text="Bibliography" --prop style=Heading1 --prop size=20pt --prop bold=true --prop spaceBefore=18pt
officecli add "$FILE" /body --type paragraph --prop text="Primary Sources" --prop style=Heading2 --prop size=14pt --prop bold=true --prop spaceBefore=12pt
officecli add "$FILE" /body --type paragraph --prop text="Ming Shilu 明實錄. Taipei: Academia Sinica, 1966." --prop size=12pt --prop indent=720 --prop hangingIndent=720
officecli add "$FILE" /body --type paragraph --prop text="Secondary Sources" --prop style=Heading2 --prop size=14pt --prop bold=true --prop spaceBefore=12pt
officecli add "$FILE" /body --type paragraph --prop text="Brook, Timothy. The Troubled Empire: China in the Yuan and Ming Dynasties. Cambridge, MA: Harvard University Press, 2010." --prop size=12pt --prop indent=720 --prop hangingIndent=720

QA：officecli query "$FILE" 'footnote' 的计数 ≥ 正文段落引用计数。

IEEE（工程——期刊、会议论文集）

• 正文：[1]、[2]。按首次出现顺序编号，不按字母序。重复引用复用同一编号。页码引用 [1, p. 15]，范围 [1]-[3]。
• 参考文献条目以方括号编号开头：[1] A. Smith and B. Jones, "Title," IEEE Trans. X, vol. 5, no. 3, pp. 1-10, 2024, doi: ...。作者名缩写在前；期刊名按 IEEE 缩写表（IEEE Trans. Neural Netw.，不用全名）。
• 正文双栏（见多栏小节）。摘要单栏、置于上方，10pt，1.15x 行距，通常 200-250 词。
• 正文首行缩进 = 0.2"（firstLineIndent=288 twips ≈ 14pt）。比 APA 的 0.5" 小，因为双栏宽度更窄。
• 章节标题：全大写 + 罗马数字——I. INTRODUCTION、II. RELATED WORK、III. METHOD。子节 A. Datasets、B. Baselines 用标题式大小写。不要用 1. Introduction（阿拉伯数字）——那是 Chicago 风格。
• 表格编号用罗马数字：Table I、Table II、Table III。图保持阿拉伯数字（Fig. 1、Fig. 2）。recalcFields=seq 对两者都写阿拉伯缓存值——若 IEEE 表格要罗马数字，要么在 recalc 后手动把缓存 <w:t> 改为罗马，要么接受阿拉伯数字并在 cover letter 中说明。

# 引用编号 1 的正文
officecli add "$FILE" /body --type paragraph --prop text="Attention-based anomaly detection has been applied to industrial sensor data [1], [2]." --prop size=10pt --prop lineSpacing=1.15x
# 参考文献条目——编号在文本中
officecli add "$FILE" /body --type paragraph --prop text="[1] A. Smith and B. Jones, \"Attention for anomaly detection,\" IEEE Trans. Neural Netw., vol. 35, no. 2, pp. 412-430, 2024." --prop size=10pt --prop indent=720 --prop hangingIndent=720
officecli add "$FILE" /body --type paragraph --prop text="[2] C. Lee, \"Time-series anomaly survey,\" in Proc. ICML, 2023, pp. 1200-1215." --prop size=10pt --prop indent=720 --prop hangingIndent=720

QA：正文最高 [N] 必须等于参考文献条目数。Grep：officecli view "$FILE" text | grep -oE '\[[0-9]+\]' | sort -u | tail -5。

MLA 9（文学、语言、文化研究）

与 APA 的差异：正文是 (Author Page) 无逗号（如 (Smith 412)）；直接引语总带页码。参考文献区标题为 Works Cited（不是 References / Bibliography）。条目按姓氏字母序、悬挂缩进、2x 行距，九大"核心元素"用句点分隔：Author. Title. Container, Other Contributors, Version, Number, Publisher, Date, Location.——不适用则跳过。书名斜体；文章标题加引号。其余与 APA 段落设置相同。

方程：OMML，inline vs display

--type equation 把 LaTeX 风格公式解析成 OMML（Office Math Markup Language）。两种模式由 --prop mode= 选择：

模式	XML	视觉	用途
display（默认）	/body 下的 <m:oMathPara>	独立居中块	编号方程、定理陈述
inline	追加到段落内某 run 的 <m:oMath>	随文本排布	正文中的 if $x > 0$ 风格

从源码看，FormulaParser.cs 是 LaTeX 子集到 OMML 的转换器：支持 _{} 下标、\frac{}{} 分数、\left( \right) 自动尺寸定界符、{a \over b} 老式分数重写等；display 模式通过 ParseAsDisplayParagraph 包进 <m:oMathPara>，inline 模式直接产出 <m:oMath> 追加到段落。schema 见 schemas/help/docx/equation.json：路径 /body/oMathPara[N]（display）与 /body/p[N]/oMath[M]（inline），mode 取 display | inline。

# Display 方程（独立段落，居中）——明确写 mode=display 以清晰
officecli add "$FILE" /body --type equation --prop mode=display --prop formula="x^2 + y^2 = z^2"
# Display 方程带希腊字母 / 下标 / 积分——下方验证渲染
officecli add "$FILE" /body --type equation --prop mode=display --prop formula="\\lambda_1 + \\alpha"
officecli add "$FILE" /body --type equation --prop mode=display --prop formula="\\frac{1}{2\\pi} \\int_0^{\\infty} e^{-x^2} dx"
# Inline 方程嵌在正文里——正文出现 x_{t+1}、\lambda 等变量时必用：
officecli add "$FILE" /body --type paragraph --prop text="Given the weight " --prop size=11pt
officecli add "$FILE" "/body/p[last()]" --type equation --prop mode=inline --prop formula="W_t"
officecli add "$FILE" "/body/p[last()]" --type run --prop text=" we define the loss..."

验证方程渲染为 OMML 数学（而非纯文本 LaTeX token）。close 之后运行：

officecli view "$FILE" text | head -20       # λ₁ + α、∫₀∞、x² 必须以 Unicode 数学符号出现
officecli raw "$FILE" /document | grep -c '<m:oMathPara'   # 每个 display 方程 ≥ 1

如果正文散文里出现原始 lambda_1、x_{t+1}、\alpha 之类纯文本 token（即你把它输入到 paragraph --prop text= 而不是包进 --type equation --prop mode=inline），下游查看器会渲染成字面 ASCII。规则：正文中每个数学变量 / 希腊字母 / 下标都必须走 --type equation mode=inline，绝不走 paragraph --prop text=。

仓库中的 examples/word/formulas.md 展示了完整覆盖度：67 个方程覆盖代数、微积分、线性代数、统计学、数论、化学、物理，例如 \frac{-b \pm \sqrt{b^{2} - 4ac}}{2a}（二次公式）、\int_{-\infty}^{+\infty} e^{-x^{2}} dx = \sqrt{\pi}（高斯积分）、\det(A - \lambda I) = 0（特征方程），可作公式语法参考。

LaTeX 子集陷阱（不可协商）：

1. \left(...\right) / \left[...\right] 定界符内部带上下标 → 解析错误（Error: cast object … Subscript）。外部上下标（\left(x+y\right)^2）没问题；普通 (、)、[、] 始终可用，display 模式下 OMML 自动调整尺寸。
2. 对 /body/oMathPara[N] 做 move 会重排 display 方程（移动的是包它的段落）。--before <path> 可能留下一个多余空段落；干净的移动优先用 --index 或 --after。

方程编号：一行双制表位排版

没有原生 \eqno。 期刊标准布局是一行：方程居中，编号靠右列边（Y = A(X) ⊗ X (1)）。用两个制表位构建——列中点一个 center 制表位、列右边缘一个 right 制表位——然后在单个段落里排 [tab] equation(inline) [tab] (1)。不要用居中 display 方程后接独立右对齐 (1) 行——那会把编号拆到单独一行，是 Agent 无法复现期刊观感的最常见原因。

# 制表位位置取决于 COLUMN 宽度（twips）。默认空白文档 = A4，3.18cm 页边距
#   → 文本宽度 = 8300 twips。
#   单栏：center 制表位 = 4150，right 制表位 = 8300
#   双栏（默认 720-twip 栏距）：col = (8300-720)/2 = 3790 → center 1895, right 3790
# （其他页面尺寸 / 页边距：text width = pageWidth - marginLeft - marginRight；重新计算。）
officecli add "$FILE" /body --type paragraph                                   # 方程段落（假设落在 p[N]）
officecli add "$FILE" "/body/p[N]" --type tab --prop pos=4150 --prop val=center
officecli add "$FILE" "/body/p[N]" --type tab --prop pos=8300 --prop val=right
officecli add "$FILE" "/body/p[N]" --type run --prop text=$'\t'                 # tab → 跳到居中点
officecli add "$FILE" "/body/p[N]" --type equation --prop mode=inline --prop formula='Y = A(X) \otimes X'
officecli add "$FILE" "/body/p[N]" --type run --prop text=$'\t(1)'             # tab → 跳到右边缘，然后是编号

双栏节直接改用双栏制表位（1895 / 3790）；同一段落就在栏内居中方程、(1) 靠栏右缘。Schema：officecli help docx tab。

不要把 --type equation 直接放到表格单元格 tc[N] 路径上——会被守卫错误拒绝（table cells only accept paragraphs, tables, or SDTs），因此不会写出坏 XML。单元格内需要方程时，目标 tc[N]/p[1] 并加 --prop mode=inline。

完整方程 schema：officecli help docx equation。

图、表与交叉引用（SEQ + PAGEREF）

两个原语都是原生字段类型（officecli help docx field 查枚举）：seq 用于自动编号标题计数器，pageref 用于"见 Fig. 2 第 7 页"回引。原生字段插入时带未求值的缓存结果；一条 set "$FILE" / --prop recalcFields=seq（见下节）按文档顺序填入真实编号——无需逐字段修补。底层实现可见 WordHandler.Add.Misc.cs（seq 要求 identifier 属性、拼装 PAGEREF {name} / SEQ {identifier} 指令）与 WordBatchEmitter.Fields.cs（PAGEREF / SEQ 字段的解析回放）。

SEQ 自动编号——图与表

SEQ 字段是一个带名字（identifier）的计数器。每次 SEQ Figure 在 recalc 时递增 Figure 计数器；SEQ Table 同理。

SEQ 缓存值——一条命令，在所有标题添加完之后。 新加的 SEQ 字段没有已求值的缓存编号；view text 显示 #OCLI_NOTEVAL!{SEQ Figure} 哨兵（且 Format["evaluated"]=false）直到你 recalc。不要手工逐字段修补。 所有图表标题就位后，运行一次：

officecli set "$FILE" / --prop recalcFields=seq

它按正文文档顺序数 SEQ Figure / SEQ Table 字段并写入真实缓存值（Figure 1 / Figure 2 / Figure 3），把 evaluated 翻为 true。中途插入标题后重跑，编号保持同步。（Heading 相对的 \s 和页眉 / 页脚中的 SEQ 交给 Word 自行重算——见 help docx document。）验证：officecli view "$FILE" text 显示互不相同的升序编号。

# 图片，标题在图下方。标题 = "Figure <seq>: title" + 可选书签供交叉引用。
officecli add "$FILE" /body --type picture --prop src=arch.png --prop width=5in
officecli set "$FILE" "/body/p[last()]/r[last()]" --prop alt="Model architecture: attention over time-series sensors"
# 标题段落（图下方，学术惯例）
officecli add "$FILE" /body --type paragraph --prop text="Figure " --prop style=Caption --prop size=10pt --prop italic=true --prop align=center
officecli add "$FILE" "/body/p[last()]" --type field --prop fieldType=seq --prop identifier=Figure
officecli add "$FILE" "/body/p[last()]" --type run --prop text=": Attention-based anomaly detection model."
# 给标题加书签，供其他段落 PAGEREF
officecli add "$FILE" /body --type bookmark --prop name=fig_arch
# （编号稍后由一条 `set / --prop recalcFields=seq` 填充，等所有标题存在后执行。）

PAGEREF——按书签交叉引用

# 交叉引用段落："As shown in Figure 1 (see page X)"
officecli add "$FILE" /body --type paragraph --prop text="As shown in Figure 1 (see page " --prop size=11pt --prop lineSpacing=1.5x
officecli add "$FILE" "/body/p[last()]" --type field --prop fieldType=pageref --prop name=fig_arch
officecli add "$FILE" "/body/p[last()]" --type run --prop text=")."

表格——标题在表上方

# 先标题（表上方），再表格
officecli add "$FILE" /body --type paragraph --prop text="Table " --prop style=Caption --prop size=10pt --prop italic=true --prop spaceAfter=6pt
officecli add "$FILE" "/body/p[last()]" --type field --prop fieldType=seq --prop identifier=Table
officecli add "$FILE" "/body/p[last()]" --type run --prop text=": Participant demographics (N=47)."
officecli add "$FILE" /body --type table --prop rows=5 --prop cols=4 --prop width=100%
# ... 按 docx v2 §Tables 填充表头与行

验证 SEQ + PAGEREF 字段已落地

# 正文文档部件中至少一个 SEQ Figure 或 SEQ Table
officecli raw "$FILE" /document | grep -c 'w:instrText[^>]*>[^<]*SEQ'   # 期望 ≥ 1
officecli raw "$FILE" /document | grep -c 'w:instrText[^>]*>[^<]*PAGEREF' # 无交叉引用时 0 也 OK

活体字段携带的缓存值在人工按 F9（Word）之前可能过时。recalc 后"Figure 1"立即显示 1、2…；recalc 前某些查看器渲染 0 或空白。判断字段是否在场要看 fldChar 是否存在，而不是看可见数字（→ 见 docx v2 §Field / cached-value spot-check）。

脚注与尾注

• 脚注（Footnote）——位于锚点段落所在页底部。用于 Chicago Notes-Bib 的来源引用，以及任何样式的内容旁注。
• 尾注（Endnote）——位于文档末尾（或参考文献之前）。某些投稿以此代替脚注，或用于会弄乱页面的长上下文注释。

# 锚定到段落 N 的脚注
officecli add "$FILE" "/body/p[3]" --type footnote --prop text="Smith et al. reported similar findings in their 2023 review."
# 尾注——锚定到段落 N（同脚注）；落在 /endnote[@endnoteId=N]
officecli add "$FILE" "/body/p[3]" --type endnote --prop text="Extended derivation of equation (4) is available at the project repository."

两者在 view annotated 输出中都显示为空字符串 run（r<a href="https://link.gitcode.com/i/6f1e094dd1f9cb55ec22bd87f6a680b3" target="_blank">N] ""）——该 run 携带 <w:footnoteReference> XML 元素而非可见文本。用 officecli query "$FILE" 'footnote' 或 officecli get "$FILE" "/footnotes/footnote[N]" 确认插入。脚注不会移动段落索引；正文就位后可任意顺序添加。脚注的完整 schema 见 [schemas/help/docx/footnote.json：addParent 为 /body/p[N]（不接受 run 级父路径），注释体追加到 footnotes.xml，可用 text、align、direction、font.* 等属性。完整 schema：officecli help docx footnote / officecli help docx endnote。

参考文献区

每篇学术论文都以参考文献表结尾。区名取决于样式（APA / IEEE / Chicago Author-Date 用 References；Chicago Notes-Bib 用 Bibliography；MLA 用 Works Cited）。每条目是独立的悬挂缩进段落。

# 区标题——与正文 Heading1 相同（按惯例不参与正文编号）
officecli add "$FILE" /body --type paragraph --prop text="References" --prop style=Heading1 --prop size=20pt --prop bold=true --prop spaceBefore=18pt --prop spaceAfter=12pt
# 每条目：悬挂缩进 720 twips (0.5")，配 indent=720（首行顶格，换行缩进）
officecli add "$FILE" /body --type paragraph --prop text="Smith, J. (2024). Remote work and cohesion. Journal of Applied Psychology, 109(3), 412-430." --prop size=12pt --prop lineSpacing=2x --prop indent=720 --prop hangingIndent=720
# DOI 超链接作为独立 run 追加到条目段落
officecli add "$FILE" "/body/p[last()]" --type hyperlink --prop url="https://doi.org/10.1037/apl0001123" --prop text="https://doi.org/10.1037/apl0001123"

已验证：--prop indent=720 --prop hangingIndent=720 是规范悬挂缩进组合（per officecli help docx paragraph）。旧的 ind.firstLine=-720 形式（负首行缩进）不规范，emit 时 schema 失败——→ 见 docx v2 §Schema-invalid-on-emit。

往返 QA。 数正文引用标记（APA (Author, Year)、IEEE [N]、MLA (Author N)）对比参考文献条目数。见交付门禁 4。每个引用键必须能解析；每条列出条目至少应被引用一次。

多栏布局：IEEE 双栏配方

IEEE 及许多工程 / 物理期刊正文双栏、摘要单栏置顶。机制：一个 type=continuous 且 columns=2 的分节符，文末再一个分节符恢复单栏。

恢复步骤不是可选项。 没有它，文档其余部分——包括参考文献——都会渲染成双栏。这是多栏布局最常见的失败点。

FILE="ieee.docx"
officecli create "$FILE"
officecli open "$FILE"

# 1. 标题、作者、单位——单栏（默认第一段）
officecli add "$FILE" /body --type paragraph --prop text="Attention-Based Anomaly Detection for Industrial Time Series" --prop align=center --prop size=18pt --prop bold=true --prop spaceAfter=12pt
officecli add "$FILE" /body --type paragraph --prop text="Alice Chen, Bob Martinez" --prop align=center --prop size=11pt
officecli add "$FILE" /body --type paragraph --prop text="Department of CS, Stanford University" --prop align=center --prop size=10pt --prop spaceAfter=18pt

# 2. 摘要——仍单栏、块式
officecli add "$FILE" /body --type paragraph --prop text="Abstract" --prop align=center --prop size=12pt --prop bold=true --prop spaceAfter=6pt
officecli add "$FILE" /body --type paragraph --prop text="We present an attention-based model for detecting anomalies in industrial sensor time series..." --prop size=10pt --prop lineSpacing=1.15x --prop spaceAfter=12pt

# 3. 分节符 + 从此双栏
#    /section[last()] 解析到最终节（同 p[last()]）；显式 /section[N] 也可。
officecli add "$FILE" /body --type section --prop type=continuous
SECTION_COUNT=$(officecli query "$FILE" section --json | jq '.data.results | length')
# add 之后 SECTION_COUNT 应为 2 —— [1] 是分节前，[2] 是分节后（双栏正文区）。
officecli set "$FILE" "/section[2]" --prop columns=2 --prop columnSpace=1cm

# 4. 正文——IEEE 要罗马数字 + 全大写节标题（见章节编号约定）
officecli add "$FILE" /body --type paragraph --prop text="I. INTRODUCTION" --prop style=Heading1 --prop size=10pt --prop bold=true
officecli add "$FILE" /body --type paragraph --prop text="Industrial anomaly detection has been studied since [1]..." --prop size=10pt --prop lineSpacing=1.15x --prop firstLineIndent=360

# 5. 双栏正文结尾处，再一个分节符 + 恢复单栏用于参考文献 / 附录
# （若参考文献也想双栏可跳过步骤 5——但多数 IEEE 论文参考文献也双栏。）
# officecli add "$FILE" /body --type section --prop type=continuous
# 最终节用 /section[last()]，或重新计数后显式 /section[N]：
# officecli set "$FILE" "/section[3]" --prop columns=1

# 6. 页脚、关闭、验证
officecli add "$FILE" / --type footer --prop type=default --prop align=center --prop size=9pt --prop field=page
officecli close "$FILE"
officecli validate "$FILE"

视觉验证。 运行 officecli view "$FILE" html 并阅读返回的 HTML 审计渲染结果。摘要必须全宽渲染，引言起双栏。若摘要折进两条窄栏，说明第一个分节符落在了摘要之前——移走它。

节索引记账。 每次 add /body --type section 都会向 /body 插入一个空段落（分节符标记）。其后所有 p[N] 索引随每个分节符 +1 偏移。提前规划分节符；添加后先 officecli get "$FILE" /body --depth 1 重新索引再继续。

完整 section schema（columns、columnSpace、orientation、pageNumFmt、titlePage、lineNumbers）：officecli help docx section。

首页块：摘要 / 关键词 / 单位

首页元信息栈：标题（居中 20-22pt 粗体）→ 作者（居中 12pt，多单位用上标 ^1 ^2）→ 单位（居中 11pt，与上标对应）→ 投稿对象 / 日期 → Abstract 标题（14pt 粗体）→ 摘要正文（块式、无 firstLineIndent、150-300 词）→ 关键词行（斜体 11pt）。沿用 docx v2 的"封面 ≥ 60% 填充"规则。

# 上标单位标记（多机构论文）
officecli add "$FILE" /body --type paragraph --prop text="Alice Chen" --prop align=center --prop size=12pt
officecli add "$FILE" "/body/p[last()]" --type run --prop text="1" --prop superscript=true
officecli add "$FILE" "/body/p[last()]" --type run --prop text=", Bob Martinez"
officecli add "$FILE" "/body/p[last()]" --type run --prop text="2" --prop superscript=true
# 页眉（封面用 type=first 空页眉跳过——见 docx v2 §headers）
officecli add "$FILE" / --type header --prop type=default --prop align=right --prop size=9pt --prop text="Short Running Title"

Nature 系双栏摘要很罕见——如需要，在 Abstract 标题之前开一个 section type=continuous columns=2；短摘要（<100 词）会留下参差不齐的栏。镜像奇偶页眉由高层 API 暴露：officecli set "$FILE" /settings --prop evenAndOddHeaders=true，然后加 even 页眉 --type header --prop type=even。完整 header schema：officecli help docx header。

QA —— 交付门禁（可执行）

假设存在问题。你的工作是把它们找出来。 第一次渲染几乎从不对。宣布完成前必须运行本块。

Gate 1-3 —— 从 docx v2 继承

→ 见 docx v2 §Delivery Gate。Schema 验证、token 泄漏 grep、活体 PAGE 字段结构。先复制 docx v2 的门禁块。每条检查都必须打印成功消息。

Gate 4 —— 引用往返

每个正文引用键应能解析到参考文献条目。计数不匹配 = REJECT。

# IEEE 示例（方括号数字）。APA (Author, Year) 或 MLA (Author Page) 请调整正则。
CITATIONS=$(officecli view "$FILE" text | grep -oE '\[[0-9]+\]' | sort -u | wc -l)
ENTRIES=$(officecli query "$FILE" 'paragraph[hangingIndent]' --json | jq '.data.results | length')
echo "In-text citation markers: $CITATIONS | Bibliography entries: $ENTRIES"
# 引用数超过条目数（有引无参）时 REJECT。条目 > 引用在部分投稿可接受。
[ "$CITATIONS" -le "$ENTRIES" ] && echo "Gate 4 OK" || { echo "REJECT Gate 4: $CITATIONS in-text markers but only $ENTRIES bibliography entries"; exit 1; }

Gate 5a —— SEQ 在场 + 缓存编号互异

若论文有任何编号图或表，正文必须携带活体 SEQ 字段 且 其缓存值必须显示互不相同的升序编号（否则 view text 和不重算缓存字段的下游查看器会对所有图都显示"Figure 1"）。

# 用 query 数 SEQ 字段（raw-grep 会把同一条 XML 行上的多个匹配折叠 → 少计）。
SEQ_COUNT=$(officecli query "$FILE" 'field[fieldType=seq]' --json | jq '.data.results | length')
VISIBLE_FIG=$(officecli view "$FILE" text | grep -cE '(Figure|Table) [0-9]+')
if [ "$VISIBLE_FIG" -gt 0 ] && [ "$SEQ_COUNT" -eq 0 ]; then
  echo "REJECT Gate 5a: $VISIBLE_FIG visible Figure/Table labels but 0 SEQ fields."
  exit 1
fi
# 缓存值必须互异。所有标题存在后运行一次 `set / --prop recalcFields=seq`；
# recalc 前字段渲染 #OCLI_NOTEVAL! 哨兵，recalc 后 Figure 1 / Figure 2 / Figure 3：
DISTINCT=$(officecli view "$FILE" text | grep -oE '(Figure|Table) [0-9]+' | sort -u | wc -l)
[ "$SEQ_COUNT" -le "$DISTINCT" ] && echo "Gate 5a OK (SEQ=$SEQ_COUNT, distinct=$DISTINCT)" || { echo "REJECT Gate 5a: $SEQ_COUNT SEQ fields but only $DISTINCT distinct rendered labels — run 'set \"$FILE\" / --prop recalcFields=seq'"; exit 1; }

Gate 5b —— 通过 HTML 预览做视觉审计（MANDATORY，不可省略）

Gate 1–5a 能抓 schema、token 泄漏、活体字段在场、引用计数。它们抓不到物理装配缺陷——页面顺序错乱、摘要重复出现在文档中部、三个图都标"Fig. 1"（尽管 SEQ 字段在场）、方程变量渲染成纯文本 LaTeX（lambda_1、x_{t+1}）而不是数学。别跳过——Gate 1–5a 通过 ≠ 视觉 OK。

运行 officecli view "$FILE" html 并阅读返回的 HTML 路径。对论文每一页回答：

(a) 页面是否符合学术逻辑顺序？（标题 → 摘要 → 关键词 → 引言 → 正文 → 参考文献——无前跳、无后漏。） (b) 摘要是否恰好出现一次，而不是在文档中部重复？ (c) Figure N / Table N 标签是否互异且升序？（Fig. 1、Fig. 2、Fig. 3——不是全"Fig. 1"。表同理。） (d) 方程是否渲染为数学？（斜体变量、λ / α 等希腊字母、正确的积分 / 分数——不是纯文本 lambda_1、x_{t+1}、\int。） (e) IEEE 论文：节标题是否全大写 + 罗马数字（I. INTRODUCTION）？表格是否罗马数字（Table I、Table II）？ (f) APA 论文：Level-1 标题是否居中粗体且无编号（不是 1. Introduction）？ (g) 每个正文"see Fig. N" / "see Table N" 是否解析到实际携带该编号的图 / 表？ (h) 标题层级在视觉上是否可区分（H1 / H2 / H3 的字号 + 字重）？

逐条报告。哪怕只发现一个缺陷 → REJECT；修复前不交付。

人工预览（可选）。 若希望用户亲自预览论文，运行 officecli watch "$FILE" 提供实时预览供用户自行打开，或让用户直接用 Word / WPS / Pages 打开 .docx。最终视觉验证在目标查看器中打开文件。

诚实边界

validate 抓 schema 错误，不抓学术样式错误。一篇文档可以带着 APA 引用跑 IEEE 论文、带着某样式禁止的脚注、或带着中途插入新图就会漂移的硬编码编号而照样通过 validate。上面的门禁——尤其是 Gate 4（往返）和 Gate 5（SEQ 在场）——才是你抓到 validate 抓不到之物的方法。

已知问题与陷阱（学术专项）

→ 基础陷阱（shell 转义、\$ \t \n 字面量、表格单元格格式顺序、分页边界、shd.fill / ind.firstLine schema 无效形式、TOC 缓存值、水印两步）：见 docx v2 §Known Issues & Pitfalls。

学术专项：

• \left(...\right) / \left[...\right] 定界符内部带上下标 → 解析错误（cast object … Subscript）。外部上下标（\left(x+y\right)^2）没问题。用普通 (、)、[、]——display 模式下 OMML 自动调整尺寸。
• 对 /body/oMathPara[N] 做 move 会重排方程（移动的是包它的段落）。--before <path> 可能留下多余空段落；优先 --index / --after。
• 分节符 +1 段落偏移。 每次 add /body --type section 向 /body 插入一个空段落。分节符之后所有 p[N] 索引 +1。规划分节符；任何 add section 后，officecli get "$FILE" /body --depth 1 重新索引。
• /section[last()] 解析到最终节（镜像 p[last()]），get 和 set 都适用。显式 /section[N] 也可：

  SECTION_COUNT=$(officecli query "$FILE" section --json | jq '.data.results | length')
  # 最终节用 /section[last()]，或显式 /section[2]、/section[3]、……
  

  每次 add /body --type section 递增计数。每加一个分节符就重新查询。
• 多栏不会自动恢复。 columns=2 节之后，必须再加一个分节符并显式在新 /section[N]（N = 恢复后计数）上设 columns=1——否则文档其余部分（包括参考文献）渲染成双栏。用 officecli get "$FILE" "/section[N]" 对每个 N 验证。
• --type equation 放到 tc[N] 单元格路径会被守卫错误拒绝（table cells only accept paragraphs, tables, or SDTs）——不会写出坏 XML。表格单元格内改用 tc[N]/p[1] + --prop mode=inline。
• SEQ 标题编号由 set / --prop recalcFields=seq 填充（所有标题存在后运行一次），不是逐字段 raw-set 修补。recalc 前的 SEQ 字段在 view text 中显示 #OCLI_NOTEVAL! 哨兵。
• 悬挂缩进规范形式是 indent=720 hangingIndent=720。 不是 ind.firstLine=-720。点式形式会在 <w:jc> 之后发出 <w:ind> 并在 emit 时 schema 失败。
• 脚注引用 run 在 view annotated 中显示为空字符串。 <w:footnoteReference> XML 元素在引用侧没有可见文本；注释体在 /footnotes/footnote[N]。用 officecli query "$FILE" 'footnote' 确认，而不是目测 view text。
• 标题位置：表标题在表上方；图标题在图下方。 所有主要样式（APA、Chicago、IEEE、MLA）一致。表标题放到表下方是学术样式错误而非渲染问题——validate 不会抓。
• TOC 缓存渲染 / shell 转义： → 见 docx v2 §Table of Contents、§Shell escape。

渲染器怪癖（跨查看器）

→ 见 docx v2 §Renderer quirks。PAGE / TOC 缓存值、OMML 基线偏移、配色方案——所有相同的怪癖都适用于学术论文。在判定某个方程或引用标记"坏了"之前，先在用户的目标查看器（Word、WPS、Pages）中打开文件——如果在那里渲染正确，那是查看器怪癖，不是技能缺陷。

帮助指针

拿不准时：officecli help docx、officecli help docx <element>、officecli help docx <element> --json。Help 是权威 schema；本技能是 docx v2 之上学术差异的决策指南。仓库内 schemas/help/docx/ 目录也随发行版提供了元素 schema 的机器可读副本，可离线查阅 equation、field、section、footnote、endnote、tab、bookmark 等元素的属性定义。