word-documents

Word 文档

适用场景

工具	适用场景
create_word_document	用户要求创建/生成新的 Word 文档
modify_word_document	用户要求编辑/更新现有文档或添加内容
list_my_word_documents	用户询问有哪些可用文档
read_word_document	用户想下载文档或阅读文档评论
preview_word_page	检查页面的实际外观（图表、图片、复杂布局）

工作流

1. 修改前：调用 preview_word_page 检查当前布局。
2. 创建/修改后：调用 preview_word_page 进行验证。
3. 按顺序运行工具（切勿并行），以避免文件争用问题。

页面设置

python-docx 默认使用 A4 纸张。若要使用 US Letter 尺寸：

from docx.shared import Inches
section = doc.sections[0]
section.page_width = Inches(8.5)
section.page_height = Inches(11)
# Set 1-inch margins
section.top_margin = Inches(1)
section.bottom_margin = Inches(1)
section.left_margin = Inches(1)
section.right_margin = Inches(1)

专业排版

• 字体：默认使用 Arial。通过 style.font.name = 'Arial' 设置。
• 标题：使用适当的标题样式以兼容目录：doc.add_heading('Title', level=1) 或 doc.add_paragraph(style='Heading 1')。
• 项目符号列表：使用 doc.add_paragraph(style='List Bullet')。切勿插入 Unicode 项目符号字符。
• 编号列表：使用 doc.add_paragraph(style='List Number')。
• 修改文档时，始终保留现有样式、字体和颜色。

图片

from docx.shared import Inches
paragraph = doc.add_paragraph()
run = paragraph.add_run()
run.add_picture('file.png', width=Inches(6))

代码规则

• 文档已预先初始化为 doc = Document()（创建时），或已作为 doc 加载（修改时）。不要包含 Document() 或 doc.save()。
• 可用库：python-docx、matplotlib、pandas、numpy（不提供 seaborn）
• 项目符号列表请使用 add_paragraph(style='List Bullet')。切勿插入 Unicode 项目符号字符。
• 切勿使用 paragraph.text = 'new text'（这会破坏格式）。请改用 runs。
• 文件名仅限字母、数字和连字符。

---

工具参考

create_word_document

使用 python-docx 代码创建新的 Word 文档。

参数	类型	必填	说明
python_code	str	是	使用 python-docx 的 Python 代码（参见上文的代码规则）
document_name	str	是	不带扩展名的文件名（仅限字母、数字和连字符）

工具输入示例：

{
  "python_code": "doc.add_heading('Quarterly Report', 0)\ndoc.add_paragraph('This report summarizes Q4 performance.')\ndoc.add_heading('Revenue', level=1)\ndoc.add_paragraph('Total revenue: $1.2M')",
  "document_name": "quarterly-report"
}

警告：参数是 document_name，不是 filename 或 name。

modify_word_document

修改现有 Word 文档并以新名称保存。

参数	类型	必填	说明
source_name	str	是	现有文档名称（不带 .docx）
output_name	str	是	新输出名称（必须与源名称不同）
python_code	str	是	用于修改文档的 Python 代码

工具输入示例：

{
  "source_name": "quarterly-report",
  "output_name": "quarterly-report-v2",
  "python_code": "doc.add_paragraph('Additional notes added.')"
}

list_my_word_documents

列出工作区中的所有 Word 文档。无需参数。

read_word_document

读取文档内容。设置 include_comments=True 后，还会显示所有评论及其作者、日期、内容和对应段落。

参数	类型	必填	说明
document_name	str	是	不带扩展名的文档名称
include_comments	bool	否	若为 true，则提取并显示评论及其段落对应关系（默认值：false）

preview_word_page

获取页面截图，以便在编辑前进行视觉检查。

参数	类型	必填	说明
document_name	str	是	不带扩展名的文档名称
page_numbers	list[int]	是	要预览的页码，从 1 开始

UI 指南（来自 tools-config）

**必须按顺序执行：**依次运行修改工具，绝不并行运行（避免 S3 文件读写时发生竞态条件）。

适用场景：

• create_word_document：用户要求创建／生成新的 Word 文档
• modify_word_document：用户要求编辑／修改／更新现有文档，或向现有文档添加内容
• list_my_word_documents：用户询问有哪些可用文档
• read_word_document：用户想要下载文档
• preview_word_page：编辑时检查页面的实际外观（图表、图像、复杂版式）

**修改前：**务必先使用 preview_word_page 查看当前版式。

页面设置：

• python-docx 默认使用 A4。对于 US Letter：section.page_width = Inches(8.5); section.page_height = Inches(11)
• 将页边距设为 1"：section.top_margin = section.bottom_margin = section.left_margin = section.right_margin = Inches(1)

专业排版：

• 字体：默认使用 Arial。通过 style.font.name = 'Arial' 设置
• 使用正确的标题样式以兼容目录：document.add_heading('Title', level=1) 或 add_paragraph(style='Heading 1')
• 列表：使用 add_paragraph(style='List Bullet') 或 add_paragraph(style='List Number')。切勿手动插入 Unicode 项目符号。

保留格式：

• 始终保留现有样式、字体和颜色
• 切勿使用 paragraph.text = 'new text'（这会破坏格式）
• 使用 runs 修改文本，同时保留格式

**文件名：**仅使用字母、数字和连字符（例如："sales-report.docx"）

**可用库：**python-docx、matplotlib、pandas、numpy（不提供 seaborn）

**图像：**如果工作区中有相关图像：run.add_picture('file.png', width=Inches(6))

**质量检查：**创建后务必使用 preview_word_page 验证外观。