内容
# wordlive
[](https://pypi.org/project/wordlive/)
[](https://pypi.org/project/wordlive/)
[](https://github.com/thomas-villani/wordlive/blob/main/LICENSE)
[](https://github.com/thomas-villani/wordlive/actions/workflows/ci.yml)
[](https://thomas-villani.github.io/wordlive/)
通过 Python 控制正在运行的 Microsoft Word 实例 — 类似于 `xlwings`，但适用于 Word。
适用于人类脚本编写和大型语言模型代理。仅限 Windows。
## 安装
```bash
pip install wordlive
# 添加到 Python 项目
uv add wordlive
# 或作为 `uv` 工具
uv tool install wordlive
```
（需要 Python 3.10+ 和 Windows 上的 `pywin32`。）
渲染页面到 PNG（`snapshot`）需要可选的 `snapshot` 扩展，这会引入 PyMuPDF：
```bash
pip install "wordlive[snapshot]"
uv add "wordlive[snapshot]"
```
## Python
```python
import wordlive as wl
with wl.attach() as word:
doc = word.documents.active
# 读取
outline = doc.outline()
bookmarks = doc.bookmarks.list()
# 以视觉模型的视角查看 - 渲染一个部分到 PNG
# （需要 `wordlive[snapshot]`）：
png = doc.heading("Introduction").snapshot()[0].png
# 礼貌地写入 - 保留用户的光标和视图，原子化 Ctrl-Z。
with doc.edit("更新地址块"):
doc.bookmarks["Address"].set_text("123 Main St")
doc.content_controls["Signatory"].set_text("Jane Doe")
doc.heading("Introduction").insert_paragraph_after("新上下文段落。")
# 返回一个交付成果（Python API 无限制访问）：
doc.export_pdf("report.pdf")
```
## 命令行界面
JSON 输入，JSON 输出 - 设计用于直接接入大型语言模型工具使用循环：
```bash
wordlive status
wordlive outline # 标题结构（heading:N）
wordlive outline --all # 每个段落（para:N）- 别名 `paragraphs`
wordlive paragraphs # 相同：para:N，级别，偏移，文本
wordlive read bookmark Address
wordlive write bookmark Address --text "123 Main St"
# 导航和定位（只读）：
wordlive read section "Introduction" # 标题下的正文
wordlive read markdown --within heading:3 # 序列化为干净的 Markdown（读取镜像插入 Markdown）
wordlive read between --start heading:1 --end heading:3 # 两个标题之间的块
wordlive read nearest-heading --anchor-id para:42 # 段落所在的章节
wordlive find --text "精确短语" # 精确（标准化）→ 范围：S-E
wordlive find-paragraph --text "大致记得的文本" # 模糊 → 排名 para:N + 分数
# 在任意锚点插入新段落（标题，段落，书签，...）：
wordlive insert --anchor-id heading:1 --text "..." # 在后（默认）
wordlive insert --anchor-id para:3 --text "..." --before
wordlive insert --anchor-id end --runs '[{"text":"粗体引导","bold":true},{"text":" - 休息"}]'
# 插入整个样式部分（使用 **粗体** / *斜体* Markdown）：
wordlive insert-block --anchor-id heading:1 --items \
'[{"text":"**礼貌** 首先.","style":"List Bullet"},"原子撤销。"]'
# → 报告范围：START-END；然后：wordlive list apply --anchor-id range:... --type bulleted
# 或提供受限的 Markdown 并获取真正的标题/列表/段落（子集，不是 CommonMark）：
printf '# 计划\n\n启动。\n\n- 范围它\n- 人员配备它\n' | wordlive insert-markdown --anchor-id end --markdown -
# insert-section 添加标题 + 正文；replace-section --anchor-id heading:N 重写章节内容
# 在文档的末尾/开头追加/前置（无需锚点）：
wordlive append --text "关闭备注。" # 新的最终段落
wordlive prepend --text "草稿" --inline # 加入第一个段落
# 通过 ID 地址锚点（`outline`/`paragraphs` 发出的 ID - `heading:N`，`para:N`，`bookmark:NAME`，`cc:NAME`）：
wordlive replace --anchor-id heading:3 --text "更新的章节文本"
wordlive go-to --anchor-id bookmark:Address
# 耐用句柄 - 位置 para:N/heading:N 在编辑下重新编号；固定为稳定 ID：
wordlive pin heading:3 --name methods # -> {"pin": "pin:methods", ...}
wordlive replace --anchor-id pin:methods --text "在后续插入中幸存"
# 显式光标表面（非首选模式 - 故意移动光标）：
wordlive cursor read # 光标在哪里？哪个 para:N？
wordlive cursor write --text "插入此处" # 在光标处输入
# 样式 + 段落格式（原子撤销）：
wordlive style list
wordlive style apply --anchor-id heading:3 --name "Heading 2"
wordlive format-paragraph --anchor-id heading:3 --alignment center --space-before 6
# 表格（单元格是锚点：table:N:R:C）：
wordlive table list
wordlive table read 1
wordlive table records 1 # 正文行作为 {header: value} 字典
wordlive replace --anchor-id table:1:2:2 --text "$450"
wordlive table add-row --table 1 --values '["住宿", "$600"]'
wordlive table append-record --table 1 --record '{"Item":"住宿","Cost":"$600"}' # 按标题名称
wordlive table update-row --table 1 --key Travel --values '{"Cost":"$450"}' # 按内容匹配行
wordlive table create --anchor-id end --data '[["项目","成本"],["旅行","$400"]]' --header
wordlive table create --anchor-id end \
--data '[{"Item":"旅行","Cost":"$400"}]' # 记录 → 键是标题行
# --rows/--cols 从 --data 推断（仅提供以填充较大）
# ... （其他命令）
```
## 代理技能
> 设置特定工具（Claude Code，Claude Desktop，Cursor，...）？
> [代理和 LLM 工具](https://thomas-villani.github.io/wordlive/agents/) 指南
> 提供每种客户端的复制粘贴设置。
wordlive 提供了 **两个** 面向 LLM 的技能（`SKILL.md`）：`wordlive-cli`（命令行工作流程）和 `wordlive-python`（`import wordlive as wl` API）。
每个技能都涵盖了锚点模型、每个动词和退出代码/异常契约。
代理通过 `wordlive --help` 直接指向 `wordlive llm-help`，
它将整个指南打印到 stdout - 无需安装步骤，无需 Word：
```bash
wordlive llm-help # CLI 指南
wordlive llm-help --python # Python-API 指南
```
或将技能文件放入项目或主目录，以便编码工具自行发现它们（默认 CLI 技能；`--python` 表示仅 Python，`--both` 表示两者）：
```bash
wordlive install-skill # ./.agents/skills/wordlive-cli/SKILL.md
wordlive install-skill --both # 还会添加 wordlive-python/SKILL.md
wordlive install-skill --system # 进入 ~/.agents/skills/
```
## MCP 服务器（Claude Desktop 和其他代理）
更喜欢 MCP？wordlive 提供了一个服务器，以便 Claude Desktop 和其他 MCP 客户端可以直接驱动您的打开文档。有三种设置方法，最简单的方法如下：
**1. 一键式捆绑。** 下载 `wordlive.mcpb`（从 [`mcpb/`](https://github.com/thomas-villani/wordlive/tree/main/mcpb) 构建）并将其放到
Claude Desktop → **设置 → 扩展**。
**2. `install-mcp`.** 在客户端配置中注册服务器（使用 `uvx`，因此无需单独安装）：
```bash
wordlive install-mcp # → Claude Desktop 的配置
wordlive install-mcp --client claude-code # → ./.mcp.json
wordlive install-mcp --print # 仅打印 JSON 片段
```
**3. 手动。** `pip install "wordlive[mcp,snapshot]"`（`snapshot` 扩展添加了视觉工具），然后添加到 `claude_desktop_config.json`：
```json
{ "mcpServers": { "wordlive": { "command": "wordlive-mcp" } } }
```
或，如果您更喜欢 `uvx`：
```json
{ "mcpServers": { "wordlive": { "command": "uvx wordlive[mcp,snapshot]" } } }
```
它公开了四个调度工具 - `word_read`，`word_write`，`word_exec` 和
`word_snapshot`（它将渲染的页面作为图像返回）。完整的动词词汇和锚点模型在指南中，可以通过工具调用
`word_read(command="guide")` 获取（也是 `wordlive://guide` 资源）。Word
必须在同一台 Windows 机器上运行。参见
[docs/mcp.md](https://thomas-villani.github.io/wordlive/mcp/)。
## 示例
可运行的开箱即用脚本位于
[`examples/`](https://github.com/thomas-villani/wordlive/tree/main/examples) - Python
（使用库）和 PowerShell（驱动 CLI）。每个都附加到您已经打开的文档；只读和仅追加的示例可以安全地在真实文档上尝试。
```bash
python examples/python/read_outline.py # 只读：打印大纲
python examples/python/append_note.py "Reviewed." # 追加一个段落（原子，礼貌）
```
```powershell
.\examples\powershell\Show-Outline.ps1
.\examples\powershell\Invoke-WordliveWithRetry.ps1 write bookmark Address --text "123 Main St"
```
## 设计
- **礼貌第一** - 操作保留用户的 `Selection`，视图和
滚动。用户可以继续编辑。
- **语义锚点优于 `Selection`** - 操作针对书签，内容
控件或标题 - 永远不会是实时光标，除非您要求。
- **原子撤销** - 每个 `doc.edit()` 都打开一个 Word `UndoRecord`，因此单个
Ctrl-Z 可以撤销整个块。
- **逃生阀** - 每个包装器都公开 `.com` 以获取原始 COM 对象；
您永远不会被缺少覆盖而阻止。
参见 [`spec.md`](https://github.com/thomas-villani/wordlive/blob/main/spec.md) 以获取完整设计。
## 贡献和安全
欢迎贡献 - 参见
[`CONTRIBUTING.md`](https://github.com/thomas-villani/wordlive/blob/main/CONTRIBUTING.md)
获取开发设置（`uv`），设计不变性和测试 / 校验 / 文档
门控。要报告安全问题，请使用
[`SECURITY.md`](https://github.com/thomas-villani/wordlive/blob/main/SECURITY.md)
中描述的私有披露，而不是公共问题。
