officecli-academic-paper

OfficeCLI 学术论文 Skill

本 Skill 是建立在 officecli-docx 之上的场景层。 所有 docx 硬性规则（样式体系、标题层级、Shell 引号、分页规则、实时 PAGE 域、交付检查、渲染器特性）均沿用而非重复讲解。本文件仅补充学术论文所需的内容：引文样式、公式、SEQ / PAGEREF 交叉引用、多栏期刊版式、参考文献悬挂缩进，以及摘要 / 关键词 / 作者单位区块。

当 docx 基础规则已涵盖某内容时，本文会标注 → 见 docx v2 §X。如尚未阅读，请先阅读 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 未生效，请打开新的终端）。若安装失败，请从 https://github.com/iOfficeAI/OfficeCLI/releases 下载二进制文件。

⚠️ 帮助优先规则

本 Skill 讲解的是学术论文的要求，而非每一个命令参数。 当属性名、枚举值或域指令不确定时，请先查阅帮助再做判断，切勿凭猜测操作。

officecli help docx                          # All docx elements
officecli help docx <element>                # Full schema (e.g. section, equation, field, footnote)
officecli help docx <element> --json         # Machine-readable

帮助信息与已安装的 CLI 版本保持一致。当本 Skill 与帮助信息不一致时，以帮助为准。 本文中每个 --prop X= 均已通过 officecli help docx <element> 核对；如果帮助在后续版本中新增或重命名了属性，请以帮助为准。

心智模型与继承关系

继承 docx v2。 你应当已阅读 skills/officecli-docx/SKILL.md。本 Skill 假定你已掌握如何添加段落、设置样式、构建表格、插入图片、管理 TOC / 页脚 / 页眉、强制分页以及执行交付检查。如对这些操作不熟悉，请先在另一个会话中学习 docx v2，再继续阅读。

Shell 与执行规范

Shell 引号、增量执行、$FILE 约定 → 见 docx v2 §Shell 与执行规范。这些规则在此原样适用：对 [N] 路径加引号；包含 $ 的值（包括正文段落中的 $2.8B 或 @ 类 DOI）需使用单引号；切勿在可执行示例中手写 \$ \t \n；每次只执行一条命令。下文的学术论文示例使用 $FILE 作为 Shell 变量（FILE="thesis.docx"）。

此处"学术"的含义（定义）

学术论文是一种在 docx 之上附加学术层的文档：可核验的引文、精确的公式、保持同步的交叉引用，以及格式规范的参考文献列表。docx 基础规则依然适用，学术场景额外增加六项差异：

1. 引文样式即约定。 APA / Chicago / IEEE / MLA 分别规定了作者格式、日期位置、参考文献排序及文中标注形式。开始时即选定一种；之后的所有决策（悬挂缩进、脚注还是括注、[1] 还是 (Smith, 2024)）都需与之保持一致。
2. 公式是一等内容。 行内 oMath 嵌于正文中，独立展示的 oMathPara 作为单独块存在，并可选择编号。
3. 图表自动编号。 SEQ Figure / SEQ Table 域负责计数；PAGEREF 将"见图 2"链接到其实时页码。
4. 参考文献采用悬挂缩进（首行顶格，续行缩进），而非首行缩进，也不是仅设置左缩进，而是悬挂缩进。
5. 摘要 / 关键词 / 作者单位区块是首页的三段式结构，而非营销意义上的封面。摘要采用块状样式，无首行缩进，不加修饰。
6. 多栏版式常见于 IEEE / ACM / Nature 及众多期刊：摘要为单栏，正文为双栏。

反向交接：何时回到 docx

对于白皮书、政策简报、技术报告、HR 模板等不涉及发表场所或引文样式的文档，应留在 docx v2。仅当文档至少同时包含以下两项时，才使用本 Skill：引文样式的参考文献、公式、SEQ/PAGEREF 交叉引用、多栏、摘要 + 关键词区块。

工作流：5 个动词

1. 阅读投稿规范。 APA 7 / Chicago 17 / IEEE / MLA 9 / 期刊专用格式。行距、字体、引注形式、参考文献排序方式，这一个决定将决定后续所有内容。
2. 规划章节。 摘要 → 关键词 → 引言 → 方法 → 结果 → 讨论 → 结论 → 参考文献。预估标题数量以决定是否添加目录（3 个及以上标题则添加目录，参见 docx v2 §Table of Contents）。
3. 提前设置样式。 Heading1 / Heading2 / Heading3 / Caption / AbstractTitle / Bibliography。在添加任何内容之前定义所有样式（→ 参见 docx v2 §Paragraphs and styles，同一规则，跳过时会出现同样的问题）。
4. 按顺序构建正文。 封面 / 标题区块 → 摘要 → 关键词 → 目录（如需要）→ 按阅读顺序排列的正文章节 → 带 SEQ 题注的图表 → 参考文献 → 脚注最后按段落路径添加。
5. 质量检查：交付门禁。 继承 docx v2 门禁 1-3，然后添加下方的学术门禁 4-5。

要求（在 docx v2 基础上的学术底线）

docx v2 §Requirements for Outputs 中的所有内容均适用。此外，学术论文必须满足以下附加规则：

排版与间距（需适配投稿规范）

• 字体。 正文默认使用 Times New Roman 11-12pt，或使用投稿规范指定的字体（IEEE 使用 Times 10pt 双栏；APA 允许 Calibri 11pt）。全文使用同一正文字体；标题不使用装饰性字体。
• 标题层级。 H1 = 20pt 加粗，H2 = 14pt 加粗，H3 = 12pt 加粗斜体，正文 = 11-12pt。（与 docx v2 数值相同，此处重申，因为学术论文从不依赖 Word 默认设置。）
• 行距。 APA 7 = 2 倍行距（双倍）。Chicago / IEEE / 大多数期刊 = 1.5 倍行距。不得低于 1.15 倍。应设置在正文段落和参考文献上。
• 页边距。 四边均为 1 英寸（1440 twips），除非投稿规范另有规定（部分期刊要求左侧 1.25 英寸用于装订，请查阅规范）。

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

• 摘要采用齐头式。 不得设置 firstLineIndent。段落间距使用 spaceAfter=12pt。如果 view issues 对摘要段落报告“正文段落缺少首行缩进”，这是误报，可忽略。
• 参考文献使用悬挂缩进。 每条文献为一个段落，设置 indent=720 hangingIndent=720（左缩进 0.5 英寸，首行按相同距离反向缩进）。首行顶格，换行缩进至作者姓名之下。
• 图的题注置于图下方。 表的题注置于表上方。这是非学术人员最容易出错的单一规则——APA、Chicago、IEEE、MLA 的规定一致。
• 引注闭环。 每个文中引注键都必须能在参考文献列表中找到对应条目。交付门禁 4 将进行验证。
• SEQ 字段必须存在。 任何带有编号图或表的论文，都必须包含动态的 SEQ Figure / SEQ Table 字段（不得使用硬编码的“图 1”文字，否则在文中间插入新图时编号会错位）。交付门禁 5 将进行验证。

封面 / 首页区块

学术封面与专业封面不同。最低要素包括：标题（居中，20-22pt 加粗）、作者、所属机构、投稿目标或期刊、日期、摘要、关键词。docx v2 §Visual delivery floor 中的“60% 填充”规则仍然适用——一个只有三行、留有半页空白的封面即为不合格。首页的具体做法见下文 §Abstract / keywords / affiliation block。

章节编号约定（取决于样式，不要盲目套用）

学术论文的章节编号是标题文本的一部分，而非通过列表编号自动生成。officecli 的 numId/listStyle 机制在复用 Heading1 时不稳定，因此应手动编写前缀。但前缀形式因样式而异，四种样式不能使用同一形式：

样式	一级标题格式	二级标题格式	示例
APA 7	无编号，居中加粗	无编号，左对齐加粗	Introduction / Methods（居中）
Chicago	"N. 标题"，左对齐	"N.M 标题"	1. Introduction、2.1 Policy Formation
IEEE	"N. 标题" 全大写 + 罗马数字	A. 副标题 首字母大写	I. INTRODUCTION、II. RELATED WORK、A. Datasets
MLA 9	无编号，左对齐加粗	相同	Literature Review（无前缀）

APA 7 的一级标题为居中、加粗、无编号；二级标题为左对齐加粗；三级标题为左对齐加粗斜体；四级和五级标题为行内标题。不要为 APA 标题添加 1. / 2. 前缀，那是 Chicago/IEEE 的惯例。IEEE 要求使用全大写和罗马数字（I. INTRODUCTION）；在每个章节内部，使用 A./B./C. 作为子标题（首字母大写）。阿拉伯数字编号的正文章节仅适用于 Chicago 风格。

四种样式均适用的例外：参考文献 / Bibliography / Works Cited / 致谢无论采用何种样式都不编号，省略 N. 前缀。

快速入门：最简 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"

这是一个十行的骨架。真实论文会通过增加更多正文段落、更多参考文献条目（每条都使用相同的 indent=720 hangingIndent=720 组合）、带标题的图表，以及在有 3 个或以上一级标题时添加目录（TOC）来扩展。快速入门示例校验通过；以下各节将详细说明每个维度。

引用样式方案

四种主流体系。项目开始时选定一种，之后的所有决策都依此进行。各样式决策表：

样式	文内引用形式	参考文献排序	正文行距	脚注？
APA 7	(Smith, 2024) 或 Smith (2024)	按作者字母顺序	2 倍（双倍）	很少（仅作内容注释）
Chicago 17（注释-书目）	上标脚注编号	按作者字母顺序	1.5 倍至 2 倍	主要方式（完整引注置于脚注中）
IEEE	[1]、[2]、...、[N]	按首次引用顺序	1.15 倍至 1.5 倍，双栏	很少
MLA 9	(Smith 412) 页码形式	按作者字母顺序，标题为"Works Cited"	2 倍	很少

四种样式的共同默认设置：参考文献段落使用 indent=720 hangingIndent=720（悬挂缩进 0.5 英寸）；若有 3 个或以上一级标题，则添加实时目录（→ 见 docx v2 §目录）；设置 updateFields=true，并在兼容 Word 的字段引擎更新之前，将目录页码标注为未计算。

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

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

# Body paragraph with parenthetical citation
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
# Reference entry with hanging indent
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 hyperlink appended to the reference paragraph
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"

质量检查：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.，除直接重复引用外，一律使用简略形式。
• 参考书目位于文末，按第一作者姓氏字母排序（"Brook, Timothy."），采用悬挂缩进。脚注正文按查看器的脚注默认字号显示（通常为 10 pt）；参考书目条目为 12 pt。（footnote 元素仅暴露 text，无法为单条脚注设置字号；请以渲染器默认值为准。）
• 以一手资料为主的论文通常将 Primary Sources 与 Secondary Sources 作为两个二级标题，置于一级标题 Bibliography 之下。书名在脚注和参考书目中均使用斜体。
• Chicago 还有一种用于自然科学的作者-年份变体。若投稿要求指定 Chicago Author-Date，则沿用 APA 的做法，仅更改标点（作者与年份之间不加逗号：(Smith 2024)）。

# Body paragraph that will anchor a footnote, then the footnote itself
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."
# Next footnote — shortened form
officecli add "$FILE" "/body/p[last()]" --type footnote --prop text="Brook, Troubled Empire, 150."
# Bibliography section split — primary sources first
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

质量检查：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.，而非全称）。
• 正文为双栏排版（见下文 §多栏）。摘要位于首页单栏区域，10 pt，行距 1.15 倍，通常为 200–250 词。
• 正文段落首行缩进为 0.2 英寸（firstLineIndent=288 缇，约 14 pt）。由于双栏宽度较窄，因此小于 APA 的 0.5 英寸。
• 章节标题：全部大写并使用罗马数字，如 I. INTRODUCTION、II. RELATED WORK、III. METHOD。子节如 A. Datasets、B. Baselines 采用首字母大写格式。IEEE 不要使用阿拉伯数字的 1. Introduction，那是 Chicago 风格。
• 表格使用罗马数字编号：Table I、Table II、Table III。图片仍使用阿拉伯数字（Fig. 1、Fig. 2）。recalcFields=seq 会为两者写入阿拉伯数字的缓存值；对于 IEEE 的罗马数字表格，可在重新计算后手动将缓存的 <w:t> 改为罗马数字，或接受阿拉伯数字并在投稿信中说明。

# Body citing reference 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
# Reference list entry — number in the text
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

质量检查：正文中最大的 [N] 必须等于参考文献列表的条目数。检索命令：officecli view "$FILE" text | grep -oE '\[[0-9]+\]' | sort -u | tail -5。

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

与 APA 的区别：正文引用格式为 (Author Page)，不加逗号（如 (Smith 412)）；直接引语必须标注页码。参考文献部分标题为 Works Cited（而非 References / Bibliography）。条目按作者姓氏字母排序，采用悬挂缩进，行距为双倍，并以句点分隔九个"核心要素"：Author. Title. Container, Other Contributors, Version, Number, Publisher, Date, Location.，不适用的要素省略。书名用斜体；文章标题用引号。其余段落设置与 APA 相同。

公式（OMML：行内与行间）

--type equation 会将类 LaTeX 公式解析为 OMML。通过 --prop mode= 选择两种模式：

模式	XML	视觉效果	用途
display（默认）	/body 下的 <m:oMathPara>	独立居中的块级公式	编号公式、定理陈述
inline	追加到段落内某个 run 中的 <m:oMath>	与文字同行显示	正文中的 if $x > 0$ 样式

# Display equation (own paragraph, centered) — explicitly set mode=display for clarity
officecli add "$FILE" /body --type equation --prop mode=display --prop formula="x^2 + y^2 = z^2"
# Display equation with Greek / subscript / integral — verify rendering below
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 equation INSIDE prose — required whenever variables like x_{t+1}, \lambda, etc. appear in a body paragraph:
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 标记。执行 close 后，运行：

officecli view "$FILE" text | head -20       # λ₁ + α, ∫₀∞, x² must appear as unicode math (verified renders)
officecli raw "$FILE" /document | grep -c '<m:oMathPara'   # ≥ 1 per display equation

如果正文中含有原始的 lambda_1、x_{t+1}、\alpha 等纯文本标记（即直接写入了 paragraph --prop text=，而没有使用 --type equation --prop mode=inline 包裹），下游查看器会将其显示为字面 ASCII 字符。规则：正文中所有数学变量、希腊字母和下标，都必须通过 --type equation mode=inline 生成，绝不能通过 paragraph --prop text= 写入。

LaTeX 子集的常见陷阱（不可违反）：

1. 定界符内部带有上下标的 \left(...\right) / \left[...\right] 会导致解析错误（Error: cast object … Subscript）。外部上标（如 \left(x+y\right)^2）没有问题；普通的 (、)、[、] 始终可用，且 OMML 在行间模式下会自动调整其大小。
2. 对 /body/oMathPara[N] 执行 move 会重新排列行间公式（即移动包裹它的段落）。--before <path> 可能会留下多余的空段落；为了干净地重新排序，优先使用 --index 或 --after。

公式编号：没有原生的 \eqno。符合期刊标准的排版是单行排版：公式居中，编号靠右对齐到栏边缘（Y = A(X) ⊗ X (1)）。实现方法是为段落设置两个制表位：一个位于栏中点的 center 制表位，以及一个位于栏右边缘的 right 制表位，然后在同一段落中按 [tab] equation(inline) [tab] (1) 的顺序排列。不要使用“行间居中公式加单独右对齐 (1) 行”的做法，因为这会把编号拆到单独一行，是智能体最常无法复现预期效果的原因。

# Tab positions depend on the COLUMN width (twips). Default blank doc = A4, 3.18cm margins
#   → text width = 8300 twips.
#   single column: center tab = 4150, right tab = 8300
#   two columns (default 720-twip gutter): col = (8300-720)/2 = 3790 → center 1895, right 3790
# (other page size / margins: text width = pageWidth - marginLeft - marginRight; recompute.)
officecli add "$FILE" /body --type paragraph                                   # the equation paragraph (say it lands at 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 → jump to center
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 → jump to right edge, then the number

对于双栏章节，只需使用双栏的制表位位置（1895 / 3790）；随后该段落会将公式在其所在栏内居中，并将 (1) 置于栏的右边缘。架构说明：officecli help docx tab。

不要将 --type equation 直接放在表格单元格 tc[N] 路径上——它会被防护错误拒绝（table cells only accept paragraphs, tables, or SDTs），因此不会写入错误的 XML。若需要在单元格中使用公式，请指向 tc[N]/p[1] 并设置 mode=inline。

完整公式架构：officecli help docx equation。

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

有两种基础元素，均为原生 fieldType（枚举见 officecli help docx field）：seq 用于自动编号的题注计数器，pageref 用于“见第 7 页图 2”之类的回指引用。原生域插入时带有未求值的缓存结果；只需执行一次 set "$FILE" / --prop recalcFields=seq（见下文 §SEQ 编号），即可按文档顺序填入真实编号，无需逐个域修补。

SEQ 自动编号——图和表

SEQ 字段是一个带名称（identifier）的计数器。每个 SEQ Figure 在重新计算时使图计数器加一；每个 SEQ Table 使表计数器加一。

SEQ 缓存值——一条命令，在所有题注添加完成后执行。 新添加的 SEQ 字段没有已计算的缓存编号；在重新计算之前，view text 会显示 #OCLI_NOTEVAL!{SEQ Figure} 占位符（且 Format["evaluated"]=false）。不要逐个手动修补字段。 所有图/表题注就位后，运行一次：

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

它按正文文档顺序统计 SEQ Figure / SEQ Table 字段，写入真实的缓存值（Figure 1 / Figure 2 / Figure 3），并将 evaluated 设为 true。若在文档中间插入题注，需重新运行，以保持编号同步。（基于标题的 \s 以及页眉/页脚中的 SEQ 交由 Word 自身重新计算——参见 help docx document。）验证：officecli view "$FILE" text 应显示互不相同且递增的编号。

# Figure with caption BELOW the image. Caption = "Figure <seq>: title" + optional bookmark for cross-ref.
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"
# Caption paragraph (below the figure, per academic convention)
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."
# Bookmark the caption so other paragraphs can PAGEREF it
officecli add "$FILE" /body --type bookmark --prop name=fig_arch
# (Numbers are filled later by a single `set / --prop recalcFields=seq`, after all captions exist.)

PAGEREF——通过书签的交叉引用

# Cross-ref paragraph: "see Figure 1 on 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=")."

表格——题注位于表格上方

# Caption first (ABOVE the table), THEN the table
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%
# ... fill header + rows per docx v2 §Tables

验证 SEQ + PAGEREF 字段已生效

# At least one SEQ Figure or SEQ Table in the body document part
officecli raw "$FILE" /document | grep -c 'w:instrText[^>]*>[^<]*SEQ'   # expect ≥ 1
officecli raw "$FILE" /document | grep -c 'w:instrText[^>]*>[^<]*PAGEREF' # 0 ok if no cross-refs

实时字段带有缓存值，在人工在 Word 中按 F9 之前会显示为过时内容。重新计算后，"Figure 1" 应立即显示为 1、2……；在重新计算之前，部分查看器可能显示 0 或空白。应通过 fldChar 是否存在来判断字段是否存在，而不是依据可见数字（→ 参见 docx v2 §Field / cached-value spot-check）。

脚注与尾注

脚注——位于其锚点段落所在页面的底部。用于 Chicago Notes-Bib 的文献来源引注，以及任何样式中的内容注释。

尾注——位于文档末尾（或参考文献之前）。部分期刊用其代替脚注，或用于不宜占用页面篇幅的较长背景注释。

# Footnote anchored to paragraph N
officecli add "$FILE" "/body/p[3]" --type footnote --prop text="Smith et al. reported similar findings in their 2023 review."
# Endnote — anchored to paragraph N (like footnote); lands at /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 输出中都显示为空字符串运行（r[N] ""）——该运行包含 <w:footnoteReference> XML 元素，而非可见文本。可使用 officecli query "$FILE" 'footnote' 或 officecli get "$FILE" "/footnotes/footnote[N]" 确认插入结果。脚注不会改变段落索引；正文内容就位后，可按任意顺序添加。完整架构参见：officecli help docx footnote / officecli help docx endnote。

参考文献部分

每篇学术论文都以参考文献列表结尾。章节名称取决于所用样式（APA / IEEE / Chicago Author-Date 使用 References；Chicago Notes-Bib 使用 Bibliography；MLA 使用 Works Cited）。每条文献都是单独的段落，并采用悬挂缩进。

# Section heading — same as body Heading1 (excluded from body numbering by convention)
officecli add "$FILE" /body --type paragraph --prop text="References" --prop style=Heading1 --prop size=20pt --prop bold=true --prop spaceBefore=18pt --prop spaceAfter=12pt
# Each entry: hanging indent 720 twips (0.5"), with indent=720 as the partner (first line flush, wraps indented)
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 hyperlink on its own run appended to the entry paragraph
officecli add "$FILE" "/body/p[last()]" --type hyperlink --prop url="https://doi.org/10.1037/apl0001123" --prop text="https://doi.org/10.1037/apl0001123"

已验证：根据 officecli help docx paragraph，--prop indent=720 --prop hangingIndent=720 是标准的悬挂缩进组合。旧的 ind.firstLine=-720 写法（负的首行缩进）不是标准做法，写入时会导致架构校验失败——→ 参见 docx v2 §Schema-invalid-on-emit。

往返核对。 统计正文中的引注标记（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. Title, authors, affiliation — single-column (the default first section)
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. Abstract — still single-column, block-style
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 break + two-column from here on
#    `/section[last()]` resolves to the final section (like p[last()]); an explicit /section[N] also works.
officecli add "$FILE" /body --type section --prop type=continuous
SECTION_COUNT=$(officecli query "$FILE" section --json | jq '.data.results | length')
# After the add, SECTION_COUNT should be 2 — [1] is pre-break, [2] is post-break (2-col body area).
officecli set "$FILE" "/section[2]" --prop columns=2 --prop columnSpace=1cm

# 4. Body — IEEE wants Roman numerals + ALL CAPS section titles (P1.2).
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. At the end of 2-column body, ANOTHER section break + revert to single column for references / appendices
# (If you want references in 2-col too, skip step 5 — but most IEEE papers use 2-col for references as well.)
# officecli add "$FILE" /body --type section --prop type=continuous
# Use /section[last()] for the final section, or re-count for an explicit /section[N]:
# officecli set "$FILE" "/section[3]" --prop columns=1

# 6. Footer, close, validate
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 重新获取索引，再继续操作。

完整的节结构定义（columns、columnSpace、orientation、pageNumFmt、titlePage、lineNumbers）请参阅：officecli help docx section。

摘要 / 关键词 / 作者单位区块

首页元数据依次为：标题（居中，20–22pt 加粗）→ 作者（居中，12pt，多个单位时使用上标 ^1 ^2）→ 作者单位（居中，11pt，与上标对应）→ 投稿目标 / 日期 → 摘要标题（14pt 加粗）→ 摘要正文（块级样式，不设置 firstLineIndent，150–300 字）→ 关键词行（11pt 斜体）。同样遵循 docx v2 中“封面填充率 ≥ 60%”的规则。

# Superscript affiliation markers (multi-institution paper)
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
# Running header (skip on cover via type=first empty header — see docx v2 §headers)
officecli add "$FILE" / --type header --prop type=default --prop align=right --prop size=9pt --prop text="Short Running Title"

Nature 系列的双栏摘要较为少见。如确需使用，请在摘要标题之前插入 section type=continuous columns=2；摘要过短（少于 100 字）会导致各栏长度参差不齐。奇偶页镜像页眉可通过高层 API 设置：officecli set "$FILE" /settings --prop evenAndOddHeaders=true，然后使用 --type header --prop type=even 添加偶数页页眉。完整的页眉结构定义请参阅：officecli help docx header。

质量检查——交付关口（可执行）

假设文档存在问题，你的任务就是找出它们。 首次渲染结果几乎从来不是完全正确的。宣布完成之前，请运行以下代码块。

关口 1–3 — 继承自 docx v2

→ 参见 docx v2 §交付关口。包括结构校验、令牌泄漏检查以及实时 PAGE 域结构检查。请先复制 docx v2 的关口代码块运行。每项检查都必须输出成功信息。

关口 4 — 引用往返校验

正文中的每个引用键都应能对应到参考文献条目。出现不匹配的数量即判定为拒绝（REJECT）。

# IEEE example (bracketed numerics). Adjust regex for APA (Author, Year) or 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 when citations exceed entries (cites without references). Entries > citations is allowed by some venues.
[ "$CITATIONS" -le "$ENTRIES" ] && echo "Gate 4 OK" || { echo "REJECT Gate 4: $CITATIONS in-text markers but only $ENTRIES bibliography entries"; exit 1; }

关口 5a — SEQ 存在性及缓存编号唯一性

如果论文包含带编号的图或表，正文必须包含实时 SEQ 域，且其缓存值必须显示互不相同、递增的编号（否则 view text 以及不会重新计算缓存域的下游查看器会把所有图都显示为“图 1”）。

# Count SEQ fields via query (raw-grep collapses multi-matches on one XML line → undercounts).
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
# Cached values must be distinct. Run `set / --prop recalcFields=seq` once after all captions exist;
# before recalc the fields render the #OCLI_NOTEVAL! sentinel, after 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 预览进行视觉审核（强制，非可选）

Gate 1–5a 可检查 schema、token 泄漏、实时字段是否存在以及引用数量。它们无法发现实际排版组装缺陷，例如页面顺序错乱、摘要在文中重复出现、三张图都标为“Fig. 1”（尽管存在 SEQ 字段），或公式变量显示为纯文本 LaTeX（lambda_1、x_{t+1}）而非数学公式。不可跳过——Gate 1–5a 通过不等于视觉审核通过。

运行 officecli view "$FILE" html，然后读取返回的 HTML 路径。对论文的每一页，回答以下问题：

(a) 页面是否符合学术论文的逻辑顺序？（标题 → 摘要 → 关键词 → 引言 → 正文 → 参考文献——不得前跳，不得后退泄漏。） (b) 摘要是否只出现一次，而非在文中间重复？ (c) 图 N / 表 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 论文：一级标题是否居中加粗且不编号（而非 1. Introduction）？ (g) 文中每一处“see Fig. N”/“see Table N”是否都指向确实带有该编号的图或表？ (h) 标题层级在视觉上是否可区分（字号与字重）于 H1 / H2 / H3？

报告每一处问题。只要存在一处缺陷 → 驳回；在修复之前不得交付。

人工预览（可选）。 如果希望用户对论文进行视觉预览，可运行 officecli watch "$FILE" 启动实时预览，由用户自行决定是否打开；或让用户直接在 Word / WPS / Pages 中打开 .docx。最终视觉验证时，请在目标查看器中打开文件。

诚实的局限

validate 只能发现 schema 错误，无法发现学术风格错误。一份文档可以通过 validate，但其中可能是 IEEE 论文却使用了 APA 引用，或使用了风格规范禁止的脚注，或图表编号为硬编码，在插入新图后会出现编号偏移。上述各道 Gate——尤其是 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）没有问题。请使用普通的 (、)、[、]，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')
  # use /section[last()] for the final section, or an explicit /section[2], /section[3], ...
  

  每执行一次 add /body --type section，节的数量就会增加。每次插入分节符后都要重新查询。
• 分栏不会自动恢复。 设置 columns=2 的节之后，必须再添加一个分节符，并在新的 /section[N] 上显式设置 columns=1（N 为恢复后的节数）；否则文档的其余部分（包括参考文献）都会以双栏显示。请对每个 N 执行 officecli get "$FILE" "/section[N]" 进行验证。
• 在 tc[N] 单元格路径上使用 --type equation 会被保护性错误拒绝（table cells only accept paragraphs, tables, or SDTs），不会写入错误的 XML。在表格单元格内，应改为以 --prop mode=inline 指向 tc[N]/p[1]。
• SEQ 题注编号由 set / --prop recalcFields=seq 填充（应在所有题注都存在之后执行一次），而不是通过逐个字段的原始 set 补丁修改。在重新计算之前，SEQ 字段在 view text 中会显示 #OCLI_NOTEVAL! 占位符。
• 悬挂缩进的规范写法是 indent=720 hangingIndent=720，而不是 ind.firstLine=-720。点号形式会在 <w:jc> 之后输出 <w:ind>，导致输出时 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。帮助信息是权威的 schema；本技能则是在 docx v2 基础上针对学术场景差异的决策指南。