word-documents

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Word Documents

Word文档

When to Use

适用场景

Tool	Use When
`create_word_document`	User asks to create/generate a NEW Word document
`modify_word_document`	User asks to edit/update an EXISTING document or add content
`list_my_word_documents`	User asks what documents are available
`read_word_document`	User wants to download a document or read its comments
`preview_word_page`	Check actual page appearance (charts, images, complex layouts)

工具	适用情况
`create_word_document`	用户要求创建/生成新的Word文档
`modify_word_document`	用户要求编辑/更新现有文档或添加内容
`list_my_word_documents`	用户询问可用的文档有哪些
`read_word_document`	用户想要下载文档或查看文档中的批注
`preview_word_page`	检查页面实际显示效果（图表、图片、复杂布局）

Workflow

工作流程

Before modifying: call
```
preview_word_page
```
to check current layout.
After creation/modification: call
```
preview_word_page
```
to verify.
Run tools sequentially (never parallel) to prevent file race conditions.

修改前：调用
```
preview_word_page
```
检查当前布局。
创建/修改后：调用
```
preview_word_page
```
进行验证。
按顺序运行工具（禁止并行），以防止文件竞争问题。

Page Setup

页面设置

python-docx defaults to A4. For US Letter size:

python

from docx.shared import Inches
section = doc.sections[0]
section.page_width = Inches(8.5)
section.page_height = Inches(11)

python-docx默认使用A4纸张。若需使用美国信纸尺寸：

python

from docx.shared import Inches
section = doc.sections[0]
section.page_width = Inches(8.5)
section.page_height = Inches(11)

Set 1-inch margins

设置1英寸边距

section.top_margin = Inches(1) section.bottom_margin = Inches(1) section.left_margin = Inches(1) section.right_margin = Inches(1)

undefined

section.top_margin = Inches(1) section.bottom_margin = Inches(1) section.left_margin = Inches(1) section.right_margin = Inches(1)

undefined

Professional Formatting

专业格式设置

Font: Arial as default. Set via
```
style.font.name = 'Arial'
```
.

Headings: Use proper heading styles for TOC compatibility:

doc.add_heading('Title', level=1)

doc.add_paragraph(style='Heading 1')

Bullet lists:
```
doc.add_paragraph(style='List Bullet')
```
. NEVER insert unicode bullet characters.
Numbered lists:
```
doc.add_paragraph(style='List Number')
```
.
Always preserve existing styles, fonts, and colors when modifying.

字体：默认使用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')
```
。
修改文档时，始终保留现有样式、字体和颜色。

Images

图片插入

python

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

python

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

Code Rules

代码规则

The document is pre-initialized as
```
doc = Document()
```
(create) or loaded as
```
doc
```
(modify). Do NOT include
```
Document()
```
or
```
doc.save()
```
.
Available libraries: python-docx, matplotlib, pandas, numpy (seaborn NOT available)
Use
```
add_paragraph(style='List Bullet')
```
for bullet lists. NEVER insert unicode bullet characters.
NEVER use
```
paragraph.text = 'new text'
```
(destroys formatting). Use runs instead.
Filenames: letters, numbers, hyphens only.

创建文档时，
```
doc
```
已预先初始化为
```
doc = Document()
```
；修改文档时，
```
doc
```
已加载完成。请勿包含
```
Document()
```
或
```
doc.save()
```
代码。
可用库：python-docx、matplotlib、pandas、numpy（seaborn不可用）
使用
```
add_paragraph(style='List Bullet')
```
创建项目符号列表。禁止手动插入Unicode项目符号字符。
禁止使用
```
paragraph.text = 'new text'
```
（会破坏格式）。请使用run对象替代。
文件名：仅允许使用字母、数字和连字符。

Tool Reference

工具参考

create_word_document

Create a new Word document using python-docx code.

Parameter	Type	Required	Description
`python_code`	str	Yes	Python code using python-docx (see Code Rules above)
`document_name`	str	Yes	Filename without extension (letters, numbers, hyphens only)

Example tool_input:

json

{
  "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"
}

WARNING: Parameter is

document_name

, NOT

filename

name

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

参数	类型	是否必填	描述
`python_code`	str	是	使用python-docx编写的Python代码（需遵守上述代码规则）
`document_name`	str	是	无扩展名的文件名（仅允许字母、数字和连字符）

示例工具输入：

json

{
  "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

Modify an existing Word document and save with a new name.

Parameter	Type	Required	Description
`source_name`	str	Yes	Existing document name (without .docx)
`output_name`	str	Yes	New output name (MUST differ from source)
`python_code`	str	Yes	Python code to modify the document

Example tool_input:

json

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

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

参数	类型	是否必填	描述
`source_name`	str	是	现有文档的名称（无.docx扩展名）
`output_name`	str	是	新的输出文件名（必须与源文件名不同）
`python_code`	str	是	用于修改文档的Python代码

示例工具输入：

json

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

list_my_word_documents

List all Word documents in workspace. No parameters needed.

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

read_word_document

Read document content. With

include_comments=True

, also shows all comments with author, date, text, and which paragraph they're attached to.

Parameter	Type	Required	Description
`document_name`	str	Yes	Document name without extension
`include_comments`	bool	No	If true, extract and display comments with paragraph mapping (default: false)

读取文档内容。若设置

include_comments=True

，还会显示所有批注，包括批注作者、日期、文本以及关联的段落。

参数	类型	是否必填	描述
`document_name`	str	是	无扩展名的文档名称
`include_comments`	bool	否	若为true，提取并显示带段落关联的批注（默认：false）

preview_word_page

Get page screenshots for visual inspection before editing.

Parameter	Type	Required	Description
`document_name`	str	Yes	Document name without extension
`page_numbers`	list[int]	Yes	1-based page numbers to preview

获取页面截图，用于编辑前的视觉检查。

参数	类型	是否必填	描述
`document_name`	str	是	无扩展名的文档名称
`page_numbers`	list[int]	是	需要预览的从1开始计数的页码

UI Guidance (from tools-config)

UI指引（来自工具配置）

Sequential Execution Required: Run modification tools sequentially, never in parallel (prevents race conditions on S3 file read/write).

When to Use:

create_word_document: User asks to create/generate a NEW Word document
modify_word_document: User asks to edit/modify/update an EXISTING document or add content to existing document
list_my_word_documents: User asks what documents are available
read_word_document: User wants to download a document
preview_word_page: Check actual page appearance when editing (charts, images, complex layouts)

Before Modifying: Always use preview_word_page first to see the current layout.

Page Setup:

python-docx defaults to A4. For US Letter:

section.page_width = Inches(8.5); section.page_height = Inches(11)

Set 1" margins:

section.top_margin = section.bottom_margin = section.left_margin = section.right_margin = Inches(1)

Professional Formatting:

Font: Arial as default. Set via
```
style.font.name = 'Arial'
```

Use proper heading styles for TOC compatibility:

document.add_heading('Title', level=1)

add_paragraph(style='Heading 1')

Lists: use

add_paragraph(style='List Bullet')

add_paragraph(style='List Number')

. NEVER insert unicode bullet characters manually.

Formatting Preservation:

ALWAYS preserve existing styles, fonts, colors
NEVER use paragraph.text = 'new text' (destroys formatting)
Use runs to modify text while preserving formatting

Filenames: Letters, numbers, hyphens only (e.g., "sales-report.docx")

Available Libraries: python-docx, matplotlib, pandas, numpy (seaborn NOT available)

Images: If workspace has relevant images:

run.add_picture('file.png', width=Inches(6))

QA: Always use preview_word_page after creation to verify appearance.

必须按顺序执行：修改类工具需按顺序运行，禁止并行（防止S3文件读写的竞争问题）。

适用场景：

create_word_document：用户要求创建/生成新的Word文档
modify_word_document：用户要求编辑/修改/更新现有文档或为现有文档添加内容
list_my_word_documents：用户询问可用的文档有哪些
read_word_document：用户想要下载文档
preview_word_page：编辑时检查页面实际显示效果（图表、图片、复杂布局）

修改前：务必先使用preview_word_page查看当前布局。

页面设置：

python-docx默认使用A4纸张。若需使用美国信纸尺寸：
```
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'
```
（会破坏格式）
使用run对象修改文本以保留格式

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

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

图片：若工作区中有相关图片，使用

run.add_picture('file.png', width=Inches(6))

插入

质量验证：创建文档后务必使用preview_word_page验证显示效果。