---
name: docx-generate
description: 在工作区内用 Python 标准库（zipfile + XML）生成 Word .docx，无需 python-docx 或 docx_tool
---

# Word 文档生成（.docx）

## 重要说明

- **平台没有 `docx_tool` / `update_doc`**，不要编造或调用不存在的工具
- **`write_file` 不能写二进制 .docx**，不要用 write_file 假装生成 Word
- **禁止**在 HTML 里用 `data:application/...;base64,...` 内嵌 docx（极易被截断损坏，下载后乱码）
- 需要公网下载时：先用本脚本生成 `.docx` 落盘，再在 HTML 里用**相对路径**链接（如 `public/方案.docx`）
- 生产沙箱通常**不能 pip install**，优先用本技能自带的 **stdlib 脚本**
- 生成后必须用 **`list_dir oa/`**（或目标目录）确认文件已落盘，再告诉用户

## 何时使用

- 用户要 Word / docx / .doc 文档（输出 `.docx`）
- 需要保存到 `oa/`、`private/`、`public/` 等分区

## 推荐方式（优先）

**优先调用 sandbox-fs 的 `generate_docx` 工具**（与 `generate_long_image` 同级），直接写入 `public/文件名.docx` 或 `oa/文件名.docx`：

- `output_path`：如 `public/协和智慧门诊研究摘要.docx`
- `title`：文档标题
- `sections`：章节数组（`heading`、`paragraphs`、可选 `table`）

生成后必须 `list_dir public/` 确认目标文件已落盘，再写 HTML 下载链接。

## 备选命令（仅当 MCP 不可用时）

技能目录内有 `generate_docx.py`（仅依赖 Python 3 标准库）：

```bash
python3 .agents/skills/docx-generate/generate_docx.py --json - --output oa/报告.docx <<'EOF'
{
  "title": "文档标题",
  "sections": [
    {
      "heading": "一、章节标题",
      "paragraphs": ["段落一", "段落二"],
      "table": {
        "headers": ["列1", "列2"],
        "rows": [["A", "B"], ["C", "D"]]
      }
    }
  ]
}
EOF
```

然后：

```bash
list_dir oa
```

## JSON 字段

| 字段 | 说明 |
|------|------|
| `title` | 文档主标题（可选） |
| `sections[]` | 章节数组 |
| `sections[].heading` | 章节标题 |
| `sections[].paragraphs` | 字符串段落列表 |
| `sections[].table.headers` | 表头 |
| `sections[].table.rows` | 表格行 |

**禁止**把 `<w:tbl>` 等 OOXML 标签写进 `paragraphs` 文本里；表格只能走 `table` 字段。

## 公网下载页（HTML + docx）

用户要「打开链接下载 Word」时：

1. 用本脚本生成 docx（建议 `public/文件名.docx` 或 `oa/文件名.docx` 再复制到 `public/`）
2. 用 `static-page-publish` 写下载页，`href` 指向**同目录相对路径**：

```html
<a href="medical-plan.docx" download>下载 Word 文档</a>
```

3. **禁止** `href="data:...;base64,..."` 嵌入 docx

## 备选方案

1. **用户要在线查看、可分享**：用 `static-page-publish` 技能写 `public/xxx.html`
2. **环境有 python-docx**（工作区 `.venv` 已装）：仍可用，但生成后必须 `list_dir` 验证
3. **禁止**在未验证文件存在时宣称「已生成 docx」