# Word 文件操作参数

所有脚本通过 `execute_skill_script` 调用，`skill_name="docx"`，`script_path` 从 skill 根目录开始。下文只列参数，不是 shell 命令。文件路径使用容器内绝对路径。

## 下载远程文档

只接受 HTTPS 地址。完整保留 URL 及查询参数传给脚本，但不要在回复、日志摘要或输出文件名中复述敏感参数。

调用 `scripts/download_document.py`：

```text
--url 'https://example.com/report.docx?signature=...' --output '/usr/local/src/word/tmp/<任务名>/source.docx'
```

可选参数：

- `--timeout <1-600>`：连接和读取超时秒数，默认 `60`。
- `--max-bytes <字节数>`：默认且最高 `26214400`（25 MiB），只允许设置更小的限制。
- `--overwrite`：只在目标是本次任务生成的旧缓存时使用。

`output` 扩展名必须是 `.docx`、`.dotx` 或 `.doc`。脚本阻止 HTTPS 重定向降级到 HTTP，流式限制大小，先写同目录临时文件，再原子发布；DOCX/DOTX 会检查 ZIP 路径、成员大小、必要部件和内容类型，并用 `python-docx` 打开。实际 OOXML 格式与 `output` 扩展名不一致时，根据错误中的实际格式更正缓存扩展名，再调用同一脚本。

成功结果包含 `path`、`size_bytes`、`format` 和 `validation`；OOXML 还包含段落、表格和章节数量。后续脚本只使用返回的本地 `path`，不再访问原 URL。

## 下载通用附件

需要下载作为 Word 任务素材的图片、视频、音频、压缩包或其他文件时，调用 `scripts/download_attachment.py`：

```text
--url 'https://example.com/asset.bin?signature=...' --output '/usr/local/src/word/tmp/<任务名>/asset.bin'
```

只接受 HTTPS 地址，`output` 可使用任意附件扩展名。可选参数只有 `--timeout <1-600>`（默认 `60`）和 `--overwrite`。附件上限固定为 25 MiB（26214400 字节），不可调高：脚本先用 HEAD 探测远端声明大小，再检查 GET 响应声明，并在流式接收时持续兜底计数；任一阶段发现超限都会返回 `ok: false` 和明确的“已拒绝下载”错误，且不会发布部分文件。

成功结果包含 `path`、实际 `size_bytes`、`declared_size_bytes`、`size_limit_bytes`、`size_probe` 和 `content_type`。本脚本不校验文件业务格式；远程 Word 源文档仍使用 `download_document.py`。

## 检查文档

调用 `scripts/inspect_document.py`：

```text
--input '/usr/local/src/word/tmp/<任务名>/source.docx'
```

可选参数：

- `--start-paragraph <索引>`、`--max-paragraphs <1-300>`：分段读取正文，索引从 `0` 开始。
- `--start-table <索引>`、`--max-tables <0-50>`、`--max-table-cells <数量>`：限制表格输出。
- `--max-chars <1000-200000>`：限制单次正文字符数。
- `--include-runs`：需要检查局部字体、粗体、斜体或跨 Run 替换问题时使用。

重点检查：

- `tracked_changes.total` 和 `authors`：是否存在修订及修订作者。
- `comments`：批注正文和作者。
- `sections`：纸张、方向、页边距、页眉、页脚。
- `has_images`、`inline_image_count`、`media_part_count`：是否需要进一步读取图片文字；浮动图片可能只计入媒体部件。
- `archive.missing_required_parts`、`duplicate_members`：结构异常。
- `has_more`、`next_paragraph`、`next_table`：继续读取长文档。

## 识别图片中的文字

需要读取图片、截图或扫描页中的文字时调用：

```text
--input '/usr/local/src/word/tmp/<任务名>/source.docx'
```

省略 `--pages` 时，脚本会把 Word 临时转换为 PDF，自动选择包含足够大图片的页面，每次最多处理 4 页。需要识别较小图片或指定页面时传：

```text
--input '/usr/local/src/word/tmp/<任务名>/source.docx' --pages '2,5-6'
```

脚本通过 LibreOffice 和 Poppler 临时渲染页面，使用本地 RapidOCR 识别图片区域；临时 PDF 和 PNG 会自动删除，不联网，也不调用大模型识图。PDF 原生文本层用于过滤正文、页眉、页脚和页码产生的重复 OCR，因此 `pages[].text` 只返回可靠的额外图片文字。

检查：

- `candidate_pages`：自动检测到的图片页；`selection_mode` 表示自动或显式选页。
- `status: good` 且 `usable_for_summary: true`：可以把 `text` 补充到原生文档内容中。
- `status: no_image_text`：图片区域没有识别到额外文字，不是错误。
- `status: sparse` 或 `low_confidence`：不要使用返回文字；根据 `needs_review` 人工核验。
- `filtered_native_line_count` 和 `filtered_outside_image_line_count`：被当作原生文字或图片区域外文字过滤的 OCR 行数。

默认 260 DPI，可用 `--dpi 150-400` 调整。若 `has_more: true`：`next_offset > 0` 时传 `--pages <next_page> --start-offset <next_offset>`；`next_offset = 0` 时把 `remaining_pages` 作为下一次 `--pages`。普通小徽标和面积不足页面约 1.5% 的图片不会进入自动候选，但仍可用 `--pages` 显式识别。

## 创建文档

调用 `scripts/create_document.py`（专利结构可加 `--preset patent`，见 `references/patent-writing.md`）：

```text
--output '/usr/local/src/word/result.docx' --spec '<JSON对象>'
```

内容较长时先把 JSON 写到任务临时目录，再传 `--spec-file`。目标是本次任务旧产物且确认可覆盖时才传 `--overwrite`。

文档说明顶层结构：

```json
{
  "properties": {
    "title": "2026 年度经营报告",
    "author": "示例公司",
    "subject": "经营分析"
  },
  "page": {
    "size": "A4",
    "orientation": "portrait",
    "margins": {
      "top": 0.85,
      "bottom": 0.85,
      "left": 0.9,
      "right": 0.9
    }
  },
  "default_font": {
    "name": "Arial",
    "east_asia": "Noto Sans CJK SC",
    "size": 10.5,
    "line_spacing": 1.15,
    "space_after": 6
  },
  "styles": {
    "Title": {"size": 24, "bold": true, "color": "1F4E78"},
    "Heading 1": {"size": 16, "bold": true, "color": "1F4E78"}
  },
  "header": {
    "text": "示例公司 · 年度报告",
    "alignment": "right"
  },
  "footer": {
    "text": "",
    "alignment": "center",
    "page_number": true,
    "page_number_prefix": "第 ",
    "page_number_suffix": " 页"
  },
  "blocks": [],
  "sections": []
}
```

支持的 `blocks[].type`：

| 类型 | 关键字段 |
| --- | --- |
| `paragraph` | `text` 或 `runs`；可选 `style/alignment/space_before/space_after/left_indent/right_indent/first_line_indent` |
| `heading` | `level`（1–9）、`text` 或 `runs` |
| `bullet_list` | `items[]`，可选 `level` |
| `numbered_list` | `items[]`，可选 `level` |
| `table` | `rows[][]`；可选 `column_widths/header_rows/style/header_fill/merges` |
| `image` | `path`；可选 `width_inches/height_inches/alignment/caption` |
| `toc` | 可选 `title`、`levels`，如 `1-3` |
| `horizontal_rule` | 可选 `color/size/style` |
| `page_break` | 无其他必填字段 |
| `section_break` | 可选 `break_type/page size/orientation/margins` |
| `spacer` | 可选 `points` |

带局部格式和链接的段落：

```json
{
  "type": "paragraph",
  "alignment": "justify",
  "runs": [
    {"text": "重要：", "bold": true, "color": "C00000"},
    {"text": "本报告数据截至 2026-06-30。"},
    {
      "text": "查看来源",
      "hyperlink": "https://example.com/source"
    }
  ]
}
```

表格示例：

```json
{
  "type": "table",
  "rows": [
    ["指标", "本期", "同比"],
    ["收入", "1,250 万元", "12.5%"],
    ["毛利率", "38.2%", "2.1 个百分点"]
  ],
  "column_widths": [2.2, 1.7, 1.7],
  "header_rows": 1,
  "header_fill": "1F4E78",
  "style": "Table Grid"
}
```

`runs[]` 支持 `bold/italic/underline/strike/color/font/east_asia_font/size/superscript/subscript/style/hyperlink`。不要用换行符模拟段落或分页；使用独立 `paragraph` 或 `page_break`。项目符号和编号必须使用列表块，不要手写 `•` 或数字前缀。

## 编辑文档

调用 `scripts/edit_document.py`：

```text
--input '/usr/local/src/word/tmp/<任务名>/source.docx' --output '/usr/local/src/word/edited.docx' --spec '<JSON对象>'
```

JSON 顶层只有 `operations`。支持：

| `operations[].type` | 关键字段 |
| --- | --- |
| `replace_text` | `find`、`replace`；可选 `scope/match_case/whole_word/count/required` |
| `append_blocks` | `blocks[]`，格式与创建脚本相同 |
| `insert_blocks_after` | `find`、`blocks[]`；可选 `match: exact|contains` |
| `remove_paragraphs` | `text`；可选 `match/count/required` |
| `set_paragraph_style` | `style`，以及 `indexes[]` 或 `contains` |
| `set_properties` | `properties` |
| `set_page` | `page`；`section` 为索引或 `all` |
| `set_header_footer` | 可选 `header`、`footer` |
| `remove_tables` | `indexes[]` |

查找替换会处理 Word 把可见短语拆成多个 `<w:r>` 的情况，并尽量保留首个匹配 Run 的格式。默认范围 `all` 包含正文、表格、页眉和页脚；可指定 `body/tables/headers/footers`。

仅当用户要求记录文本替换时传 `--track-changes --author <作者>`，此时所有操作必须是 `replace_text`。脚本生成真实的删除/插入修订，保留未改动 Run 的格式。含已有修订的输入、跨书签/批注范围、含域/图片等复杂节点或带换行的修订替换会明确拒绝；需要先缩小目标或按用户已明确的意图处理原修订。

输入含现有修订时默认停止：

- 用户希望干净副本：先用 `accept_changes.py`。
- 用户明确要求保留修订：才传 `--allow-existing-revisions`；修改后的内容本身不会自动变成新的修订。
- 新增、删除段落、调整格式等操作暂不支持自动记录修订。不要把这些操作作为“已显示修订”交付。

## 添加批注

调用 `scripts/add_comment.py`：

```text
--input '/usr/local/src/word/tmp/<任务名>/source.docx' --output '/usr/local/src/word/commented.docx' --find '费用上限' --comment '请确认该上限是否含税' --author '审阅人' --initials 'SR'
```

可选：

- `--scope <body|tables|headers|footers|all>`。
- `--occurrence <序号>`：为全文第几个匹配添加批注，默认 `1`。
- `--ignore-case`。

脚本会在必要时拆分 Run，让批注尽量精确锚定到目标文本，而不是整个段落。

## 接受修订

调用 `scripts/accept_changes.py`：

```text
--input '/usr/local/src/word/tmp/<任务名>/redlined.docx' --output '/usr/local/src/word/clean.docx'
```

脚本只执行固定的“接受全部修订”宏，不能运行用户提供的宏。必须检查：

- `revision_markers_before` 大于 `0` 时，`revision_markers_after` 必须为 `0`。
- `status` 必须为 `success`。
- 之后仍要执行结构校验和逐页渲染，特别检查删除段落、编号列表和空白段落。

## 转换

调用 `scripts/convert_document.py`：

```text
--input '/usr/local/src/word/tmp/<任务名>/legacy.doc' --output '/usr/local/src/word/tmp/task/source.docx'
```

支持：

- `.doc` / `.dotx` → `.docx`。
- `.docx` → `.pdf`，用于预览或用户明确要求的 PDF 副本。
- `.docx` → `.md` / `.txt`，默认按接受修订后的视图导出；可传 `--track-changes reject|all`。

不要把转换为 Markdown 的结果当作版式等价副本；表格宽度、浮动图片、页眉页脚、脚注和分页可能简化。

## 高级 OOXML 编辑

只有 `edit_document.py` 无法完成且确实需要编辑底层部件时：

1. 调用 `scripts/unpack_document.py --input <docx> --output-dir <空目录>`。
2. 用可用的文件编辑工具最小化修改 `word/document.xml` 或相关部件；不要重排、格式化或重写无关 XML。
3. 调用 `scripts/pack_document.py --input-dir <目录> --output <新docx>`。
4. 调用 `validate_document.py --check-convert` 和 `render_document.py`。

解包脚本拒绝路径穿越、符号链接和压缩炸弹；打包脚本拒绝缺少 `[Content_Types].xml`、`_rels/.rels` 或 `word/document.xml` 的目录。不要手动调用 `unzip`、`zip`、`find` 或删除命令。

## 校验

调用 `scripts/validate_document.py`：

```text
--input '/usr/local/src/word/result.docx' --check-convert
```

必须满足：

- `status: valid`。
- `issue_count: 0`。
- `archive.missing_required_parts` 和 `duplicate_members` 为空。
- 批注引用完整，内部关系目标存在，所有 XML 可安全解析。
- 修订元素有作者和时间；干净副本的 `tracked_changes.total` 应为 `0`。
- `render_check.success: true` 且页数大于 `0`。

该检查验证结构和可打开性，不替代人工视觉检查。

## 渲染与视觉检查

调用 `scripts/render_document.py`：

```text
--input '/usr/local/src/word/result.docx' --output-dir '/usr/local/src/word/tmp/task/rendered'
```

默认 150 DPI、单次最多 20 页。可传：

- `--start-page`、`--end-page`、`--max-pages`：分批渲染。
- `--dpi <72-300>`：小字、复杂表格或页眉脚注可提高到 180–220。
- `--include-pdf`：同时保留 `document.pdf`。
- `--overwrite`：只覆盖本次任务旧渲染。

若 `has_more: true`，用 `next_page` 继续。通过可用的图片查看工具逐页检查。

## 质量要求

- 默认采用 A4、合理页边距、清晰标题层级；现有文档的规范优先。
- 字体必须实际安装；检查方法和可用字体见 `references/fonts.md`。已有模板优先保留字体，缺失时明确报告；普通新文档可用 Noto/Fandol 与 Arial/Times New Roman。
- 标题必须使用内置 `Heading 1`–`Heading 9` 或具有大纲级别的样式，目录才能收录。
- 表格明确设置列宽、重复表头并禁止跨页拆分关键行；不要使用百分比列宽假设不同客户端一致。
- 表格底色使用明确填充色；不要用表格模拟水平线。
- 页码、目录和交叉引用使用字段，不手写空格或点号对齐。
- 图片保持纵横比，注明来源或说明文字，确认没有超出版心。
- 不用 `\n` 代替独立段落，不用空格填充对齐，不把分页符直接放在正文字符串中。
- 检查孤行孤字、标题落在页尾、表格断裂、图片拉伸、文字裁切、异常空白页、乱码、重叠和页码连续性。
- 最终文档必须内容准确、结构有效、可由 LibreOffice 打开，并通过全部页面视觉检查。

## 分节页眉、页脚和页码

创建说明可带 `sections`，每项使用已存在且不重复的 `index`（从 0 开始），可设置 `header`、`footer` 和 `page_number_start`。先用 `section_break` 块创建分节，再覆盖对应节。全局 `header/footer` 用作默认值，分节设置优先且解除与上一节的链接。

```json
{"sections": [{"index": 1, "header": {"text": "说明书", "alignment": "center"}, "page_number_start": 1}]}
```

页边距、列宽和缩进的单位是英寸，`2.5 cm = 2.5 / 2.54` 英寸。字号与段前段后间距使用 pt。`default_font.line_spacing` 是倍数；段落块的 `line_spacing` 是固定 pt，不能把 `1.5` 当成 1.5 倍行距传入段落块。