doc-control

doc-control

让 AI Agent 以修订形式编辑 Word 文档，供作者接受或拒绝。

当 Agent 被要求修正 .docx 文件时，通常会重写文件，并希望其他内容没有发生变化。 这个工具为它提供了一个确定性接口：按段落地址读取文档，然后发送编辑内容，将其作为修订和批注写入，同时每次写入都会备份、验证并支持撤销。它既能处理已关闭的文件，也能通过 LibreOffice Writer 或 Windows 上的 Microsoft Word 操作作者当前打开的文档。工具本身不包含 AI：由 Agent 做决定，由作者审批。

尚未稳定：API 仍可能变更。

快速开始

Python（版本见 pyproject.toml），无需其他依赖。

pip install doc-control            # or run without installing: uvx doc-control ...
doc-control text.find --json '{"doc": "story.docx", "query": "rain"}'

若要在 Windows 上实时控制 Word，请安装 doc-control[live]（会添加 pywin32）； LibreOffice 无需额外软件包。

无需 Python 即可安装（Windows）

最新发布页面 中的每个版本都附带 Claude Desktop 扩展和安装程序。两者都为当前用户安装， 无需管理员权限，可与任何 Claude 账户配合使用（包括免费套餐），并可实时控制 Microsoft Word。完整指南（校验和、更新、卸载）： docs/install-windows.md。

Claude Desktop 扩展（.mcpb）

1. 从最新发布页面下载 doc-control-X.Y.Z-windows-x64.mcpb。
2. 将文件拖到 Claude Desktop 的设置 > 扩展页面，然后点击安装。

Claude Desktop 会警告此扩展可以访问计算机上的所有内容；每个本地扩展都会收到此警告。双击文件不会安装扩展。

安装程序（-setup.exe），用于命令行

1. 从最新发布页面下载 doc-control-X.Y.Z-windows-x64-setup.exe。
2. 双击运行。
3. 如果 Windows SmartScreen 显示“Windows 已保护你的电脑”，请点击更多信息，然后点击仍要运行（安装程序未经代码签名）。
4. 点击安装、下一步和完成，然后打开新的终端：在那里运行 doc-control server.capabilities 即可。

示例

一个包含两个段落的 story.docx。先查找一个单词，再将其替换，并在下一个段落添加批注，全部在一个批次中完成（较长的输出内容已用 ... 截断；其余部分为实际输出）：

$ doc-control text.find --json '{"doc": "story.docx", "query": "rain"}'
{"api": "1.0", "ok": true, "op": "text.find", ..., "result": {"matches": [{"at": "p1#bfa780f9:4-8",
 "text": "rain", "context": "The rain had not stopped since Tuesday…"}], "total": 1, ...}}

$ doc-control doc.batch --json '{"doc": "story.docx", "ops": [
    {"op": "text.replace", "at": "p1#bfa780f9:4-8", "text": "snow"},
    {"op": "comment.add", "at": "p2#f8b24a64", "text": "Which window?"}]}'
{"api": "1.0", "ok": true, "op": "doc.batch", ..., "result": {"applied": 2, "dry_run": false,
 "preview": [{"op": 0, "at": "p1#bfa780f9:4-8", "before": "rain", "after": "snow"},
             {"op": 1, "at": "p2#f8b24a64", "before": "Ana closed the window and waited.",
              "after": "(comment c0 by Claude: Which window?)"}],
 ..., "author": "Claude", "backup": ".../.doc-control/story.docx/backups/20261020T091845Z-0ff4dc24.docx",
 "op_id": "h-000001"}, "warnings": [], "next": null}

$ doc-control review.list --json '{"doc": "story.docx"}'
{..., "result": {"totals": {"comments": 1, "insert": 0, "delete": 0, "replace": 1, ...},
 "paragraphs": [{"at": "p1#c6f909ff", "text": "The snow had not stopped since Tuesday.",
   "changes": [{"type": "replace", "ids": ["1", "2"], "author": "Claude", "old": "rain", "new": "snow", ...}]},
  {"at": "p2#f8b24a64", "text": "Ana closed the window and waited.",
   "comments": [{"id": "0", "author": "Claude", "text": "Which window?", "quote": "Ana closed the window and waited.", ...}]}]}, ...}

Word 会将替换内容显示为修订删除和插入，并在页边显示批注。编辑后若重用旧地址，则会报错，而不是猜测：

$ doc-control text.replace --json '{"doc": "story.docx", "at": "p1#bfa780f9:4-8", "text": "fog"}'
{"api": "1.0", "ok": false, "op": "text.replace", "error": {"code": "STALE_ADDRESS",
 "message": "p1#bfa780f9 no longer matches the document",
 "hint": "Re-read the paragraph (para.get) or resolve its anchor, then retry.",
 "details": {"address": "p1#bfa780f9", "current": "p1#c6f909ff"}}}

与 AI Agent 搭配使用

MCP 服务

doc-control mcp 通过 stdio 提供 60 多项操作作为 MCP 工具，每项操作对应一个工具（doc.batch 会变为 doc_batch），并使用与 CLI 相同的 JSON Schema 和响应封套。每个工具都会声明一个 outputSchema；调用成功时还会以 structuredContent 返回该封套。仅使用标准库。

{
  "mcpServers": {
    "doc-control": { "command": "uvx", "args": ["doc-control", "mcp"] }
  }
}

要在 Windows 上使用实时 Word，请使用 "args": ["--from", "doc-control[live]", "doc-control", "mcp"]，或安装上方的 .mcpb 扩展。live_places 还附带 MCP Apps UI（一个 ui:// 页面），页面上的按钮会调用 live_select。

分组	工具
读取	doc_outline、para_list、para_get、para_locate、text_find、doc_stats、doc_segment、review_list、comment_list、revision_list
编辑（跟踪）	doc_batch、text_replace、para_insert、para_delete、comment_add、note_add、term_rename、table_row_insert、table_row_delete
审阅	revision_accept、revision_reject、doc_diff、doc_compare
布局和字段	layout_get、layout_apply、field_list、field_update、toc_insert、caption_add、xref_add、index_mark、index_insert
样式	style_*、styleset_*
安全	history_list、history_undo、history_restore、history_search、...
实时窗口	live_status、live_open、live_select、live_places、live_save、live_close、...
发现	server_capabilities、server_help、recipe_list、recipe_run

使用 {"op": "<name>"} 调用 server_help，可返回任意操作的 Schema 和摘要。

从 CLI 使用

Agent 可以直接驱动 CLI。它不会提示用户，且只有在使用 --json - 时才会读取 stdin。它会在 stdout 上准确输出一个 JSON 封套：{"ok": true, "result": ...} 或 {"ok": false, "error": {"code", "message", "hint", "details"}}。 退出代码：0 表示成功，1 表示操作错误，2 表示用法错误（未知操作或无效请求）。错误代码列于 docs/errors.md。

建议的工作循环：读取内容（doc.outline、para.list、text.find），构建一个 doc.batch，使用 "dry_run": true 运行以获取预览，然后应用更改，并引导撰写者查看 Word 的“审阅”窗格。history.undo 可撤销写入。

工作原理

• 使用地址，而非偏移量。 p12#a7b2a7b2:4-10 表示第 12 段、该段的文本指纹和字符范围。段落发生变化时，会返回包含当前地址的 STALE_ADDRESS。编辑后，anchor.create / anchor.resolve 可再次查找某段内容。
• 所有内容更改都会被跟踪，作者为 DOC_CONTROL_AUTHOR（默认为 Claude）。对于撰写者已批准的编辑，文本编辑操作和 history.restore 可使用 "tracked": false（仅文件引擎支持）。
• **安全层：**锁文件和磁盘更改检测、每次写入前备份、回读验证、失败时自动恢复，以及支持撤销的操作日志。
• **文件引擎和实时引擎共用一个 API。**文件引擎使用 Python 标准库编辑已关闭的 .docx 文件，只重写其实际修改的部分；读取也支持 .txt、.md 和 .odt。实时引擎可操控 LibreOffice Writer 或 Word（Windows，COM）中打开的文档。
• 配方会提出修复批次（西班牙语排版、引号、破折号、间距、空段落）：先运行 recipe.list，再运行 recipe.run，它会返回供审核和应用的批次。

用法

操作命名为 resource.action；任何单项编辑操作都会作为仅包含一项编辑的 doc.batch 运行。doc-control server.help <op> 会打印操作的 Schema。从 Python 调用：

from doc_control import api

with api.open("Novela.docx") as doc:
    for p in doc.paragraphs(normalized=True, pages=True):
        print(p["at"], p["style_name"], p["page"], p["text"][:40])
    chapters = doc.run("doc.segment", {"unit": "chapters"})["chapters"]

注释、页眉、页脚和表格

读取范围默认为正文；在 stories 中添加 "notes"（脚注、尾注）或 "headers"（页眉、页脚）即可扩展读取范围。这些段落带有前缀地址（fn3/p1#0c9e0c9e、hdr1.default/...），可用于编辑。

doc-control para.list --json '{"doc": "Tesis.docx", "stories": ["body", "notes"]}'
doc-control text.replace --json '{"doc": "Tesis.docx", "at": "fn3/p1#0c9e0c9e:4-10", "text": "2019"}'
doc-control note.add --json '{"doc": "Tesis.docx", "at": "p40#c0ffee00:17", "kind": "footnote", "text": "Ver el cap. 2."}'
doc-control table.row.insert --json '{"doc": "Tesis.docx", "table": 1, "after_row": 2, "cells": ["a", "b"]}'

页面布局和字段

layout.get 按节返回页面方案（起始位置、分隔符、编号、各类型的页眉和页脚）；layout.apply 会将文档调整为相同格式的方案。以下示例为小说设置无页码的标题页，然后从右侧页面开始第 1 章，页码为 1，奇数页页眉显示章节标题，偶数页页眉显示书名：

doc-control layout.apply --json '{"doc": "Novela.docx", "untracked": true, "plan": {
  "version": 1, "two_sided": true, "mirror_margins": true,
  "sections": [
    {"from": "p1#ea7412aa", "break": "nextPage",
     "numbering": {"shown": false, "start": 1, "format": "lowerRoman"},
     "header": {"default": "", "even": ""}, "footer": {"default": "", "even": ""}},
    {"from": "p2#5fac7aad", "break": "oddPage",
     "numbering": {"shown": true, "start": 1, "format": "decimal"},
     "header": {"default": "{chapter}", "even": "La casa del río"},
     "footer": {"default": "{PAGE}", "even": "{PAGE}"}}]}}'

{PAGE}、{NUMPAGES} 和 {chapter} 会成为字段。分隔符和编号会被跟踪；Word 无法跟踪新建的页眉部分和双面设置，因此会标记为 untracked: true。请先尝试 "dry_run": true。field.list、toc.insert、caption.add、xref.add 和 index.insert 用于处理字段；field.update 通过无头模式的 LibreOffice 刷新这些字段。

实时操作：作者当前打开的文档

doc-control live.open --json '{"doc": "Novela.docx"}'
doc-control doc.batch --json '{"doc": "Novela.docx", "engine": "live", "ops": [
  {"op": "comment.add", "at": "p40#c0ffee00", "text": "¿Seguro?"}]}'
doc-control live.close --json '{"doc": "Novela.docx", "save": true}'

实时 doc.batch 支持 comment.add、text.replace 和 para.insert。如果没有可用的应用，它会返回 ENGINE_UNAVAILABLE 和原因；live.status 会列出找到的应用，以及 LibreOffice 的 UNO 桥接所需的 Python。关闭时不会丢弃未保存的工作。

环境变量

变量	作用
DOC_CONTROL_AUTHOR	修订和批注的作者（默认值为 Claude）
DOC_CONTROL_STORE	appdata 会将备份和历史记录保存在用户存储区，而不是文档旁边的 .doc-control/ 中
DOC_CONTROL_STORE_DIR	覆盖存储根目录
DOC_CONTROL_HOME	用户存储区和配方文件夹
DOC_CONTROL_UPDATE_CHECK	1 表示每天最多检查一次 GitHub Releases，并在 server.capabilities 中报告较新版本；不会下载任何内容

所有操作均在本地运行。关闭更新检查（默认设置）后，不会有任何内容离开本机。

它不是什么

• 它不是 AI：不会调用模型，也不会做判断。它只执行 Agent 发送的指令。
• macOS 上尚不支持实时控制；实时 doc.batch 仅支持部分编辑类型。
• 索引由 Word 生成（F9）；引用字段不会被更改。

文档

• 操作参考和错误参考，由代码生成
• Windows 安装指南
• 在真实 Word 中检查结果
• 设计决策

开发

uv sync
make check     # ruff, mypy, pytest, hygiene script

工作计划通过 claude-arsenal 按设有门槛的任务制定； 请参阅 CLAUDE.md。

相关项目

• claude-arsenal — 规范驱动的 Claude Code 工作流和设有门槛的任务队列。
• drawspec — 声明式图表规范 → 简洁的 SVG/PNG/文本，可由大模型编写；内含 MCP 服务。
• literary-critic — 以专业编辑的方式分析大模型手稿。
• integral-job-search — 在 Claude Code 中运行、以求职者为中心的求职工具。

许可证

MIT — 参见 LICENSE。