编辑计划操作¶

scripts/edit_document_from_plan.ps1 接收 JSON 编辑计划，用来脚本化改写 .docx 文档。本页补齐计划格式、执行结果和常用 operation 的参数字段，避免中文读者只能看到 operation 名称列表。

编辑计划格式¶

编辑计划可以是 JSON 数组，也可以是带 operations 数组的对象。每个 operation 都必须提供 op。op 中的短横线会被规范化为下划线，因此 append-image 和 append_image 会进入同一个 dispatcher 分支。

{
  "operations": [
    {
      "op": "replace_text",
      "find": "草稿",
      "replace": "定稿",
      "match_case": true
    },
    {
      "op": "append_hyperlink",
      "text": "FeatherDoc",
      "target": "https://github.com/wuxianggujun/FeatherDoc"
    }
  ]
}

输入 DOCX、输出 DOCX、可选 summary_json、构建目录和 skip_build 是 scripts/edit_document_from_plan.ps1 的命令参数。单个 operation 通常不设置 input_path 或 output_path；apply_table_position_plan 会在调用 CLI 前把当前 input_path 注入表格定位计划。

执行结果¶

脚本会写出 summary 对象，记录整次运行状态和每个 operation 的执行结果。

字段	含义
`status`	整个编辑计划的状态，通常是 `succeeded` 或 `failed`。
`input_docx` / `output_docx`	解析后的源 DOCX 和目标 DOCX 路径。
`edit_plan`	解析后的 JSON 编辑计划路径。
`summary_json`	调用者要求写出的 summary 文件路径。
`operation_count`	从计划中读取到的 operation 数量。
`operations`	每个 operation 的记录，包含 `index`、`op`、`command`、 `input_docx`、`output_docx`、`status`、`exit_code`、 `output`，以及失败时的 `error`。
`error`	只有在整次运行失败时才出现。

操作参考¶

下面优先列出 JSON 计划里最常用的 operation 参数。完整 operation 名称索引见页面下方。

审阅和修订¶

Operation	必填字段	可选字段和别名	作用
`accept_all_revisions`	`op`	无。	对整个文档调用 `accept-all-revisions`。
`set_comment_resolved`	`op`。脚本会把字段包装为 review mutation plan。	`comment_index`/`index`、`resolved`、`expected_text`/ `expected_anchor_text`、`expected_comment_text`/ `expected_comment_body`、`expected_resolved`、 `expected_parent_index`。	调用 `apply-review-mutation-plan` 更新批注 resolved 状态。
`append_comment`	`selected_text`/`anchor_text` 和 `comment_text`/`text`/`body`。	`author`/`comment_author`、`initials`/`comment_initials`、 `date`/`comment_date`。	在匹配文本上追加批注。
`apply_review_mutation_plan`	`plan_file`/`plan_path`/`review_plan_file`/ `review_mutation_plan_file`，或内联 `review_plan`/`operations`。	文件计划和内联计划不能同时提供。	通过 `apply-review-mutation-plan` 回放批注变更。

注释和字段¶

Operation	必填字段	可选字段和别名	作用
`append_page_number_field`	`op`	`part` 默认 `body`；`part_index`/`index`、`section`、 `kind`、`dirty`、`locked`。	在指定文档 part 中追加页码字段。
`append_hyperlink_field`	`bookmark_name`/`bookmark`/`name`。	`result_text`/`text`、字段状态和 part 选择字段。	追加指向书签的 Word hyperlink field。
`set_update_fields_on_open`	`op`	可通过专用 enable/disable operation 设置 `enabled`。	设置文档打开时更新字段的开关。

模板槽和内容控件¶

Operation	必填字段	可选字段和别名	作用
`replace_content_control_text_by_tag`	`text`，并且只能提供一种 selector：`tag`/`content_control_tag` 或 `alias`/`content_control_alias`。	`part` 默认 `body`；`part_index`/`index`、`section`、 `kind`。	对选中的内容控件调用 `replace-content-control-text`。
`replace_content_control_table_rows`	selector 字段和 `rows`。	part 选择字段；本 operation 允许空 rows。	替换内容控件表格行。
`replace_bookmark_text`	`bookmark`/`bookmark_name` 和 `text`。	书签 selector 选项。	用文本替换书签内容。

图片、链接和 OMML¶

Operation	必填字段	可选字段和别名	作用
`append_image`	`image_path`/`image`/`path`/`file`。	part 选择字段；`floating`；`width`/`width_px`；`height`/ `height_px`；浮动图片还支持 `horizontal_reference`、 `horizontal_offset`、`vertical_reference`、`vertical_offset`、 `behind_text`、`allow_overlap`、`z_order`、`wrap_mode`、 wrap distance 和 crop 字段。	调用 `append-image`。默认追加行内图片，`floating` 为 true 时追加浮动图片。
`append_hyperlink`	`text` 和 `target`/`url`/`href`。	无。	调用 `append-hyperlink` 追加超链接。
`append_omml`	`xml`/`omml`/`omml_xml`。	无。	追加 OMML 公式。

文本和段落变更¶

Operation	必填字段	可选字段和别名	作用
`replace_text`	`find`/`search`/`old_text` 和 `replace`/`replacement`/ `new_text`/`text`。	`match_case` 默认 `true`。	替换 `word/document.xml` 中的段落文本，并返回替换数量。
`set_text_style`	一个目标：`paragraph_index`/`index`、`text_contains`/ `contains`，或 `table_index` + `row_index` + `cell_index`；同时至少提供一个样式字段。	`bold`、`font_family`/`font`/`latin_font_family`、 `east_asia_font_family` 别名、`language` 别名、 `east_asia_language` 别名、`color`/`text_color`/ `font_color`、`font_size_points` 别名、`font_size_half_points` 别名。	对正文段落或表格单元格内段落的 runs 设置样式。
`set_paragraph_alignment`	目标 `paragraph_index`/`index` 或 `text_contains`/ `paragraph_text_contains`；`alignment`/`horizontal_alignment`。	对齐值别名：`start` = `left`，`centre` = `center`， `end` = `right`，`justify` = `both`。	设置正文段落水平对齐。

表格和编号¶

Operation	必填字段	可选字段和别名	作用
`set_table_col_width`	`table_index`、`column_index`/`col_index`/`column`，以及大于 0 的 `width_twips`/`column_width_twips`/`width`。	除上述别名外无额外字段。	设置正文表格 grid column 和单元格宽度。
`merge_table_cell`	`table_index`、`row_index`、`cell_index`、`direction`/ `merge_direction`。	`count`/`merge_count`。	从指定单元格向指定方向调用 `merge-table-cells`。
`unmerge_table_cell`	`table_index`、`row_index`、`cell_index`、`direction`/ `merge_direction`。	无。	从指定单元格向指定方向调用 `unmerge-table-cells`。
`apply_table_position_plan`	`plan_file`/`plan_path`/`table_position_plan_file`/ `table_position_plan_path`，或内联 `table_position_plan`/`plan`。	`dry_run` 必须省略或为 `false`；脚本会在调用 `apply-table-position-plan` 前注入 `input_path`。	应用表格定位计划并写出编辑计划的目标 DOCX。
`import_numbering_catalog`	`catalog_file`/`catalog_path`/`numbering_catalog_file`/ `numbering_catalog_path`。	无。	调用 `import-numbering-catalog` 导入编号目录。

JSON 示例¶

替换内容控件、追加图片并设置文本样式：

{
  "operations": [
    {
      "op": "replace_content_control_text_by_tag",
      "tag": "customer_name",
      "text": "Ada Lovelace"
    },
    {
      "op": "append_image",
      "image_path": "assets/logo.png",
      "part": "body",
      "width": 320
    },
    {
      "op": "set_text_style",
      "text_contains": "Ada Lovelace",
      "bold": true,
      "font_family": "Aptos",
      "east_asia_font_family": "Microsoft YaHei",
      "color": "1F4E79",
      "font_size_points": 12
    }
  ]
}

更新表格布局和编号：

{
  "operations": [
    {
      "op": "set_table_col_width",
      "table_index": 0,
      "column_index": 1,
      "width_twips": 2880
    },
    {
      "op": "apply_table_position_plan",
      "table_position_plan": {
        "tables": [
          {
            "table_index": 0,
            "alignment": "center"
          }
        ]
      }
    },
    {
      "op": "import_numbering_catalog",
      "catalog_file": "numbering.catalog.json"
    }
  ]
}

完整操作索引¶

审阅与修订操作¶

accept_all_revisions
reject_all_revisions
set_comment_resolved
set_comment_metadata
append_comment
append_comment_reply
replace_comment
remove_comment
apply_review_mutation_plan (CLI route: apply-review-mutation-plan)
append_insertion_revision
append_deletion_revision
insert_run_revision_after
delete_run_revision
replace_run_revision
accept_revision
reject_revision
set_revision_metadata

注释、脚注尾注与字段¶

append_footnote
replace_footnote
remove_footnote
append_endnote
replace_endnote
remove_endnote
append_page_number_field (CLI route: append-page-number-field)
append_total_pages_field
append_table_of_contents_field
append_document_property_field
append_field
append_date_field
append_reference_field
append_page_reference_field
append_style_reference_field
append_hyperlink_field
append_caption
append_index_entry_field
append_index_field
append_sequence_field
append_complex_field
replace_field
set_update_fields_on_open
enable_update_fields_on_open
disable_update_fields_on_open
clear_update_fields_on_open

模板槽与内容控件¶

replace_content_control_text
replace_content_control_text_by_tag
replace_content_control_text_by_alias
replace_content_control_paragraphs
replace_content_control_table
replace_content_control_table_rows
replace_content_control_image
set_content_control_form_state
sync_content_controls_from_custom_xml
sync_content_control_from_custom_xml
replace_bookmark_text
replace_bookmark_paragraphs
replace_bookmark_table_rows
replace_bookmark_table
remove_bookmark_block
delete_bookmark_block
replace_bookmark_image
replace_bookmark_floating_image

图片、链接与 OMML¶

append_image (CLI route: append-image)
append_floating_image
replace_image
remove_image
append_hyperlink (CLI route: append-hyperlink)
replace_hyperlink
remove_hyperlink
delete_hyperlink
append_omml (CLI route: append-omml)
replace_omml
remove_omml
delete_omml

文本与段落变更¶

insert_paragraph_text_revision
delete_paragraph_text_revision
replace_paragraph_text_revision
insert_text_range_revision
delete_text_range_revision
replace_text_range_revision
append_paragraph_text_comment
append_text_range_comment
set_paragraph_text_comment_range
set_text_range_comment_range
replace_text
replace_document_text
set_text_style
set_text_format
set_paragraph_text_style
delete_paragraph
remove_paragraph
set_paragraph_horizontal_alignment
set_paragraph_alignment
clear_paragraph_horizontal_alignment
clear_paragraph_alignment
set_paragraph_line_spacing
clear_paragraph_spacing

表格与编号¶

apply_table_position_plan (CLI route: apply-table-position-plan)
import_numbering_catalog
set_table_col_width
clear_table_col_width
clear_table_width
clear_table_alignment
clear_table_indent
clear_table_layout_mode
clear_table_style_id
clear_table_style_look
clear_table_cell_spacing
clear_table_default_cell_margin
clear_table_border
delete_table_row
delete_table_column
delete_table
insert_table_before
insert_table_like_before
merge_table_cell
unmerge_table_cells
unmerge_table_cell