convez.ai
AgenteAutomaçãoAvançado
qingfuliu071313-arch

Word-Agent

qingfuliu071313-arch/Word-agent

Suite completa para processar e revisar documentos Word acadêmicos

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent Python para operações completas em documentos Word acadêmicos. Oferece módulos integrados para leitura, formatação, verificação de qualidade, edição de conteúdo, gerenciamento de tabelas/figuras, referências, revisão e preparação para submissão, com suporte a modificações em tempo real via MCP.

Instalação

$npx convez-ai qingfuliu071313-arch/Word-agent

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
5
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Processar e formatar teses e dissertações em lote
  • Gerenciar revisões e comentários em documentos colaborativos
  • Validar conformidade de referências (GB/T 7714) e estrutura
  • Preparar documentos para submissão (limpeza, remoção de PII, watermarks)
  • Automatizar edição de conteúdo com rastreamento de mudanças nativo

Veredito

Ferramenta especializada e madura para fluxo de trabalho acadêmico em Word. Excelente cobertura de casos de uso reais (revisão, formatação, validação), com arquitetura modular bem pensada e suporte a integração via MCP para edição em tempo real.

README

A tradução para o português deste README ainda está na fila.

Word-Agent v1.1.0

A Claude Code plugin for academic paper Word document operations.

Claude Code 插件:学术论文 Word 文档全流程工具包。

Bilingual support: English & 中文


Features / 功能

Core Modules / 核心模块

ModuleFunction / 功能Description / 说明
word-readerDocument analysis / 文档分析Generate Document Map, compare versions, detect tracked changes / 生成文档地图、对比版本、检测修订
word-formatterFormatting / 格式化Parse format specs → batch apply, TOC generation, CJK normalization / 解析格式要求 → 批量应用、目录生成、中英混排
word-checkerQuality check / 质量检查Cross-reference validation, format compliance, structural validation, layout diagnostics / 交叉引用验证、格式合规、结构验证、布局诊断
word-editContent editing / 内容编辑Replacement, paragraph rewriting, tracked changes, equations, cross-references, bulk edit, undo / 替换、段落改写、修订模式、公式、交叉引用、批量编辑、撤销
word-table-figureTables & figures / 表格与图片Three-line tables, image insertion, caption management, equation insertion / 三线表、插图、题注管理、公式插入
word-referenceReferences / 参考文献GB/T 7714 formatting, Zotero integration, footnote/endnote management / GB/T 7714 格式化、Zotero 集成、脚注尾注管理
word-reviewerReview & revision / 审稿修订Extract comments, plan revisions, threaded comment replies, point-by-point response / 提取批注、规划修订、线程批注回复、逐条回复
word-submitSubmission prep / 投稿准备Clean copy, split/merge, selective accept/reject, watermarks, PII scrubbing / 清理版、拆分合并、选择性修订处理、水印、PII 清洗

v1.0.0 New Capabilities / v1.0.0 新增能力

Capability / 能力Description / 说明Backend / 后端
Native tracked changes / 原生修订模式Single MCP call per edit with Word-native revision marks / 单次调用即可产生 Word 原生修订标记word-mcp-live
Selective accept/reject / 选择性接受拒绝Review and selectively accept or reject individual tracked changes / 逐条审查并选择性接受或拒绝修订docx-mcp
Threaded comments / 线程批注Add, reply to, resolve, and delete individual comments / 添加、回复、解析、删除单条批注word-mcp-live
Structural validation / 结构验证Verify paraId uniqueness, bookmark integrity, image references / 验证段落 ID 唯一性、书签完整性、图片引用docx-mcp
Live editing / 实时编辑Edit documents while Word is open with real-time updates / Word 打开时实时编辑、即时可见word-mcp-live
Bulk edit via Markdown / Markdown 批量编辑Convert to Markdown, apply CriticMarkup, write back atomically / 转为 Markdown、CriticMarkup 批量修改、原子写回adeu SDK
Per-action undo / 逐步撤销Undo individual operations in live editing mode / 实时模式下逐步撤销单个操作word-mcp-live
Equation insertion / 公式插入Insert OMML equations from LaTeX input / 从 LaTeX 输入插入 OMML 公式word-mcp-live
Cross-reference insertion / 交叉引用插入Insert live cross-references to headings, figures, tables, equations / 插入可自动更新的交叉引用word-mcp-live
Layout diagnostics / 布局诊断Check page breaks, orphan/widow lines, text overflow / 检查页面分隔、孤行寡行、文本溢出word-mcp-live
Watermark management / 水印管理Add and remove watermarks (DRAFT, CONFIDENTIAL, etc.) / 添加和移除水印word-mcp-live + docx-mcp
PII scrubbing / PII 清洗Detect and redact personal identifiable information (experimental) / 检测并脱敏个人信息(实验性)docx-mcp

Installation / 安装

Prerequisites / 前置条件

Quick Install / 一键安装

git clone https://github.com/qingfuliu071313-arch/Word-agent.git
cd Word-agent
bash scripts/setup.sh

Manual Install / 手动安装

# 1. Install Python dependencies / 安装 Python 依赖
pip3 install -r scripts/requirements.txt

# 2. Register as Claude Code plugin marketplace / 注册为 Claude Code 插件市场
claude plugin marketplace add "$(pwd)"

# 3. Install the plugin / 安装插件
claude plugin install word-agent@word-agent

Docker Install / Docker 安装

# Build and run / 构建并运行
bash scripts/docker-setup.sh --run

# Or use Docker Compose / 或使用 Docker Compose
docker compose up -d

Note: Docker mode only supports file-level operations. Live editing (COM/JXA) requires a native Word installation.

注意:Docker 模式仅支持文件级操作。实时编辑(COM/JXA)需要本地安装 Word。

Windows Install / Windows 安装说明

All core features work on Windows — the Python script layer is fully cross-platform, live editing uses COM (Windows-native), and the default fonts (宋体/黑体/Times New Roman) are Windows system fonts. Three extra steps:

全部核心功能在 Windows 上可用——Python 脚本层完全跨平台,实时编辑走 Windows 原生的 COM,默认字体(宋体/黑体/Times New Roman)本就是 Windows 系统字体。需要额外做三件事:

# 1. Install Git for Windows (Claude Code runs hooks via Git Bash)
#    安装 Git for Windows(Claude Code 通过 Git Bash 执行 hook)
winget install Git.Git

# 2. Install jq — required by the smart-routing hook.
#    Without it the hook degrades gracefully (no errors), but automatic
#    skill routing is disabled and you must invoke skills manually.
#    安装 jq——智能路由 hook 依赖它。缺失时 hook 静默降级(不报错),
#    但自动路由失效,需要手动调用 skill。
winget install jqlang.jq

# 3. (Optional) LibreOffice — only needed for legacy .doc conversion.
#    Add its program directory to PATH so `soffice` resolves.
#    (可选)LibreOffice——仅处理旧版 .doc 文件时需要,
#    安装后把程序目录加入 PATH 使 `soffice` 命令可用。
winget install TheDocumentFoundation.LibreOffice
# PATH += C:\Program Files\LibreOffice\program

Then follow Manual Install above in Git Bash (use pip instead of pip3 if that is how Python is installed). scripts/setup.sh also runs in Git Bash.

之后在 Git Bash 中按上方"手动安装"步骤执行即可(若 Python 安装方式不同,pip3 换成 pip)。scripts/setup.sh 也可以在 Git Bash 中运行。

Feature / 功能Windows 支持
Formatting, editing, checking, references, submission prep / 排版、编辑、检查、参考文献、投稿准备✅ Full / 完整
Live editing (Word open) / 实时编辑(Word 打开状态)✅ Via COM / 走 COM
File-lock detection / 文件锁检测✅ Native ~$ owner files / 原生 ~$ 锁文件
Smart routing hook / 智能路由 hook✅ Needs Git Bash + jq / 需 Git Bash + jq
Legacy .doc conversion / 旧版 .doc 转换✅ Needs LibreOffice in PATH / 需 LibreOffice 加入 PATH

MCP Server Configuration / MCP 服务器配置

word-agent uses a multi-backend architecture with three MCP servers:

word-agent 使用三后端架构,包含三台 MCP 服务器:

{
  "mcpServers": {
    "word-document-server": {
      "command": "your-start-command",
      "args": []
    },
    "word-mcp-live": {
      "command": "uvx",
      "args": ["word-mcp-live"],
      "env": {
        "MCP_AUTHOR": "Claude",
        "MCP_AUTHOR_INITIALS": "CL"
      }
    },
    "docx-mcp": {
      "command": "uvx",
      "args": ["docx-mcp-server"]
    }
  }
}
ServerRole / 角色Required / 必需
word-document-serverCore read/write, formatting, tables / 基础读写、格式化、表格Yes / 是
word-mcp-liveLive editing, tracked changes, comments, equations / 实时编辑、修订、批注、公式Recommended / 推荐
docx-mcpStructural validation, selective accept/reject, PII / 结构验证、选择性修订、PIIRecommended / 推荐

word-agent gracefully degrades when optional servers are unavailable — features fall back to XML manipulation or skip with a warning.

当可选 server 不可用时,word-agent 自动降级到 XML 操作或跳过并给出提示。

Additional optional MCP servers / 其他可选 MCP 服务器:

  • Zotero MCP — Zotero library integration for word-reference / 启用 word-reference 的 Zotero 文献库集成
  • Semantic Scholar MCP — Literature search and citation analysis / 启用文献搜索和引用分析

See references/mcp_servers.md for detailed configuration guide / 详细配置见 references/mcp_servers.md。


Usage / 使用

Describe your task in Claude Code and the plugin auto-routes to the right module:

在 Claude Code 中直接描述你的需求,插件会自动路由到对应模块:

# Analyze document structure / 分析文档结构
Analyze this document: paper.docx
分析一下这个文档:论文.docx

# Apply formatting from a spec / 按格式要求排版
Format according to this spec: format_guide.pdf
按照这个格式要求排版:格式要求.pdf

# Edit with tracked changes / 修订模式编辑
Change "30 days" to "60 days" with tracked changes
用修订模式把"30天"改成"60天"

# Insert an equation / 插入公式
Insert equation E=mc^2 after paragraph 3
在第3段后面插入公式 E=mc²

# Review and revise / 审稿修订
Process these reviewer comments and make revisions
处理这些审稿意见并修订

# Selective accept/reject / 选择性修订处理
Show me all tracked changes and let me choose which to accept
列出所有修订让我选择接受或拒绝

# Check structural integrity / 结构检查
Run a full check including structural validation
运行全面检查(含结构验证)

# Generate a clean copy for submission / 生成投稿清理版
Generate a clean copy ready for submission
帮我生成 clean copy 准备投稿

# Bulk edit / 批量编辑
Make these 15 changes to the manuscript
批量修改这15处内容

You can also invoke a specific module directly / 也可以直接调用特定模块:

/word-agent:word-read
/word-agent:word-format
/word-agent:word-check
/word-agent:word-edit
/word-agent:word-review
/word-agent:word-submit

Architecture / 架构

Three-Layer Design / 三层设计

agents/            → WHO  (persona, model routing, tool permissions)
                          (角色定义、模型选择、工具权限)
skills/*/SKILL.md  → HOW  (workflow phases, templates, output format)
                          (工作流程、模板、输出格式)
references/        → WHAT (domain knowledge, standards, rules)
                          (领域知识、标准、规则)

Five-Tier Tool Routing / 五层工具路由

P1: word-document-server  → Stable primary (read/write/format/tables)
                             稳定主力(读写/格式化/表格)
P2: word-mcp-live         → Live editing, tracked changes, comments, equations
                             实时编辑、修订、批注、公式
P3: docx-mcp              → Structural validation, selective accept/reject
                             结构验证、选择性接受拒绝
P4: adeu Python SDK       → Bulk editing via Markdown intermediate
                             通过 Markdown 中间表示批量编辑
P5: XML unpack/edit/pack  → Legacy fallback
                             遗留兜底方案

Each operation routes to the highest-priority backend available. See references/tool_routing.md for the complete routing table.

每个操作路由到可用的最高优先级后端。详见 references/tool_routing.md。


Design Principles / 设计原则

  • Document Map caching — word-reader generates a structural summary once; all downstream modules reuse it, never re-read the full document Document Map 缓存 — word-reader 生成一次结构摘要,所有下游模块复用
  • Multi-backend with graceful degradation — Three MCP servers with automatic fallback; no feature is hard-locked to a single backend 多后端自动降级 — 三台 MCP 服务器自动回退,无功能硬绑定到单一后端
  • Style-first — Control formatting through paragraph styles, never apply direct formatting, avoid font chaos 样式先行 — 通过段落样式控制格式,禁止直接格式化,避免字体混乱
  • Mandatory font normalization — Every write operation triggers normalize_fonts.py to fix theme fonts, missing eastAsia, and bare runs 强制字体归一化 — 每次写操作后执行字体归一化,修复主题字体、缺失 eastAsia、裸 run
  • User-provided format specs — No pre-built journal templates; parse the user's format requirement document into executable rules 用户提供格式规范 — 不预设期刊模板,解析用户的格式要求文档为可执行规则
  • Text Box awareness — Extract text box content (w:txbxContent) via XML parsing, since standard text extraction tools skip them entirely 文本框感知 — 通过 XML 解析提取文本框内容,标准文本提取工具会完全跳过文本框
  • No mixed modes — Live editing and file editing never mix on the same file in the same session 模式不混用 — 同一文件同一会话中实时模式和文件模式不得混用

Quality Checks / 质量检查

word-checker provides four verification modes:

word-checker 提供四种检查模式:

ModeTrigger / 触发词What It Checks / 检查内容
A Cross-Reference / 交叉引用"检查引用", "cross-reference"Figure/table/equation references match assets / 图表公式引用与实际资产匹配
B Format Compliance / 格式合规"检查格式", "format compliance"Document formatting vs user-provided spec / 文档格式与用户规范对比
C Structural Validation / 结构验证"结构检查", "structural"paraId uniqueness, bookmarks, image refs / 段落 ID、书签、图片引用完整性
D Layout Diagnostics / 布局诊断"布局检查", "layout"Orphan/widow lines, page breaks, overflow (live mode only) / 孤行寡行、分页、溢出(仅实时模式)

Dependencies / 依赖

PackagePurpose / 用途Priority / 优先级
docx2pythonDocument structure extraction / 文档结构提取Required / 必需
deepdiffDocument comparison / 文档对比Required / 必需
redlinesDiff visualization / 差异可视化Required / 必需
word-mcp-liveLive editing, tracked changes, comments, equations / 实时编辑、修订、批注、公式Recommended / 推荐
docx-mcp-serverStructural validation, selective accept/reject / 结构验证、选择性修订Recommended / 推荐
adeuMarkdown intermediate for bulk editing / 批量编辑 Markdown 中间表示Recommended / 推荐
python-docx-replaceCross-run text replacement / 跨 run 文本替换Optional / 可选
docxcomposeDocument merging / 文档合并Optional / 可选
citeproc-pyCitation formatting / 引用格式化Optional / 可选
pytestTest suite / 测试套件Dev / 开发

Testing / 测试

# Run all tests / 运行所有测试
bash scripts/run_tests.sh

# Run with verbose output / 详细输出
bash scripts/run_tests.sh -v

# Run specific test class / 运行特定测试类
bash scripts/run_tests.sh -k "FontNormalization"

Test coverage includes: font normalization, document structure parsing, text box extraction, skill routing consistency, and reference file completeness.

测试覆盖:字体归一化、文档结构解析、文本框提取、技能路由一致性、参考文档完整性。


Project Structure / 项目结构

Word-agent/
├── .claude-plugin/          Plugin manifests / 插件清单
│   ├── plugin.json
│   └── marketplace.json
├── agents/                  9 agent definitions / 9 个 Agent 定义
├── skills/                  9 skill workflows / 9 个 Skill 工作流
│   ├── word-read/
│   ├── word-format/
│   ├── word-edit/
│   ├── word-check/
│   ├── word-review/
│   ├── word-submit/
│   ├── word-reference/
│   ├── word-table-figure/
│   └── word-orchestrate/
├── references/              Shared knowledge files / 共享知识文件
│   ├── tool_routing.md          Five-tier routing rules / 五层路由规则
│   ├── mcp_servers.md           MCP server configuration / MCP 服务器配置
│   ├── tracked_changes.md       Native vs Legacy tracked changes / 原生与遗留修订模式
│   ├── comment_operations.md    Threaded comment operations / 线程批注操作
│   ├── structural_validation.md OOXML structural checks / OOXML 结构检查
│   ├── live_editing.md          Live editing mode / 实时编辑模式
│   ├── equation_crossref.md     Equations & cross-references / 公式与交叉引用
│   ├── adeu_integration.md      adeu bulk editing pipeline / adeu 批量编辑
│   ├── font_normalization.md    Font normalization script / 字体归一化脚本
│   ├── submission_checklist.md  Pre-submission checklist / 投稿前检查清单
│   └── ...
├── scripts/                 Setup & utility scripts / 安装与工具脚本
├── test/                    Test suite / 测试套件
├── docs/                    Runtime instructions / 运行时指令
├── Dockerfile               Docker image / Docker 镜像
├── docker-compose.yml       Docker Compose config / Docker Compose 配置
└── CLAUDE.md                Developer guide / 开发者指南

Updating the Plugin / 更新插件

After modifying source files, reinstall the cache:

修改源文件后需要重新安装缓存:

claude plugin uninstall word-agent@word-agent
claude plugin install word-agent@word-agent

Or use the setup script / 或使用 setup 脚本:

bash scripts/setup.sh

Acknowledgments / 致谢

Word-Agent's multi-backend architecture was inspired by and integrates with the following open-source projects. We thank their authors for their excellent work.

Word-Agent 的多后端架构受到以下开源项目的启发并与之集成。感谢这些项目的作者们的出色工作。

Project / 项目Author / 作者LicenseContribution / 贡献
word-mcp-liveykarapazarMITLive editing, native tracked changes, threaded comments, equation insertion / 实时编辑、原生修订、线程批注、公式插入
docx-mcpSecurityRoninMITStructural validation, selective accept/reject, PII scrubbing / 结构验证、选择性修订处理、PII 清洗
adeudealfluenceMITMarkdown intermediate representation for bulk editing / 批量编辑的 Markdown 中间表示

License

MIT

Ver o original no GitHub

Bom para

Relacionados