python-hwpx-automation：让 AI agent 安全处理 HWPX 文档
很多 agent 工具都很擅长改代码，却不擅长碰真实办公室里的文件格式。尤其是 HWPX 这种在韩国办公场景里常见、但在一般开发者工具链里相对边缘的格式：人想让 agent 填一份表、检查一份公文、把内容抽成 Markdown，最后才发现模型能读文本，却不一定知道如何安全地写回一个结构完整的 HWPX 包。
今天看的是 airmang/python-hwpx-automation。它不是一个泛用的“文档聊天机器人”，而是建在 python-hwpx 引擎之上的 Python 自动化层：提供 Python API、hwpx CLI，以及可选的 MCP adapter，让 agent 能在本地 workspace 里读取、编辑、生成、填表和验证 HWPX 文档。README 里明确说，基本用法不需要 MCP，也不需要 Hancom Office 或 Windows；如果要接 Claude Desktop、VS Code、Gemini CLI、Cursor、Windsurf 这类 MCP client，再安装 [mcp] extra。
按 GitHub repository API、README、Releases、Tags 和默认分支 commit history 在 2026-08-04 能核验的公开信息，airmang/python-hwpx-automation 当前有 65 stars、23 forks。仓库主语言是 Python，许可证是 Apache-2.0。仓库创建于 2025-09-19 10:39:17 UTC，最近 push 是 2026-08-04 09:53:29 UTC。默认分支当前最新提交是 66ec479，提交时间 2026-08-04 09:49:01 UTC。GitHub Releases 页面当前最新发布版是 v6.7.1，发布时间 2026-08-03 10:43:30 UTC；Tags 列表已经出现 v7.0.1，对应提交也是 66ec479。
项目概览
| 属性 | 详情 |
|---|---|
| 仓库 | airmang/python-hwpx-automation |
| 定位 | 面向 HWPX 文档的 Python 自动化层、CLI 和可选 MCP server |
| Stars | 65 |
| Forks | 23 |
| 主要语言 | Python |
| 许可证 | Apache-2.0 |
| 创建时间 | 2025-09-19 10:39:17 UTC |
| 最近 push | 2026-08-04 09:53:29 UTC |
| 当前默认分支提交 | 66ec479，2026-08-04 09:49:01 UTC |
| 最新 GitHub Release | v6.7.1，2026-08-03 10:43:30 UTC |
| 最新 Git tag | v7.0.1 |
| 关键词 | HWPX、document automation、MCP、local-first、Python、CLI、form fill |
它有意思的地方在于边界很窄
现在 MCP server 和 agent plugin 很多，但不少项目的问题是边界太宽：什么都想接一点，最后真正能可靠修改的东西并不多。python-hwpx-automation 的角度相反，它盯住 HWPX 这个具体格式，把读取、查找、替换、表格、表单、文档生成、预览、修复和校验这些动作拆成 agent 可以调用的工具。
README 里列出的工具面并不抽象。基础读取包括 get_document_info、get_document_map、find_text；编辑路径包括 search_and_replace、apply_document_commands、add_tracked_edit；表单流程是 analyze_form_fill 到 apply_form_fill 再到 verify_form_fill；生成侧有 create_document_from_plan、公文样式检查、mail merge、照片台纸、名牌、组织图；还提供 render_preview、hwpx_to_markdown、repair_hwpx 和健康检查。
这类项目的价值不是“模型终于会写文档了”这么简单，而是把一个难以让 LLM 直接碰的二进制/压缩包式办公格式，变成一组可验证的小操作。Agent 发的是 plan 和 operation，不是直接改 raw XML。对真实办公文档来说，这个差别很大：你需要的不只是生成一段文字，而是让格式、表格、字段和包结构在保存后仍然可用。
MCP 只是其中一个入口
README 里一个细节值得注意：它把 MCP server 放在可选层，而不是唯一入口。最简单的安装是：
pip install python-hwpx-automation然后可以在 Python 里用 create_document_from_plan 创建文档，也可以通过 python -m hwpx_automation --help 或 hwpx help 进入 CLI。只有当你想把它接到 MCP client 时，才安装：
pip install "python-hwpx-automation[mcp]"
hwpx-automation-mcp这让它不像一个只服务于某个 agent host 的临时 adapter。你可以先在普通 Python 脚本或 CI 里跑文档生成，再把同一套能力暴露给 Claude Desktop、VS Code、Gemini CLI、Cursor 或 Windsurf。对团队工作流来说，这比“只能在某个聊天窗口里用”更容易落地。
MCP 配置里还有一个实际约束：HWPX_AUTOMATION_WORKSPACE_ROOTS 要明确指定允许访问的文档目录。README 解释说，如果留空，GUI client 往往会从系统目录启动 server，导致文档路径被挡住。这个默认思路是对的：文档自动化工具不应该默认能扫整个文件系统。
安全设计比格式转换更重要
文档 agent 的风险点和代码 agent 不完全一样。代码 agent 改坏了文件，Git 通常还能兜底；办公文档一旦写坏，可能表现为“能保存但打不开”“表格还在但字段错位”“生成预览和最终打开效果不一致”。python-hwpx-automation 的 README 反复强调 copy first、smallest edit、re-read after edits。修改工具会立即保存，所以建议先复制文档，在副本上做最小变更，再重新读取确认。
项目还描述了一个保存门禁：常规保存路径通过 python-hwpx 的 SavePipeline，做完整性、XML、OPC/ID 和打开安全检查；失败时不写入。路径处理上，它默认拒绝 workspace 外 traversal 和 symlink escape；URL 输入只允许 HTTPS 和公开 IP，私有网络访问需要显式打开。MCP 场景里还有 capability handshake，用 core、automation、plugin 的版本和 hash 检查 skew，默认 fail-closed。
这些听起来像工程细节，但正是这类项目能不能真的进工作流的分界。一个“能把文档读成文本”的工具只解决了 demo；一个“能在受限 workspace 里做小步修改、保存前后检查、失败不写”的工具，才有机会被拿来处理真实文件。
适合什么场景
最明显的场景是韩国业务文档自动化：批量生成 HWPX 会议记录、通知、公文、试题、名牌、组织图，或者把表格字段从结构化数据里填进去。README 里提到的 form fill 流程和 table_compute，就是面向这种“文档长得像表单，但数据来自别处”的工作。
第二类场景是把 HWPX 接进 agent workflow。比如让 agent 先 get_document_map 看文档结构，再只改某几个段落或表格单元；让 agent 把一份 HWPX 转成 Markdown 做摘要；或者让它先 render preview，再把结果交给人类检查。这比把整份文档丢给模型让它“理解一下”更可靠，也更容易审计。
第三类场景是非 Windows 环境里的 HWPX 处理。README 明确写到不需要 Hancom Office，也不需要 Windows，只要 Python 能跑即可。这对服务器、CI、远端 agent session 或 ChatGPT/Codex 这类运行环境很关键：你可以把文档处理放在自动化管线里，而不是被桌面办公软件绑住。
Caveat
第一个 caveat 是领域性很强。如果你不处理 HWPX，或者你的团队主要用 DOCX、PDF、Markdown，这个项目不会立刻改变日常工作流。它的价值来自专门解决 HWPX，而不是替代所有文档工具。
第二个 caveat 是 release 状态需要看清。GitHub Releases 当前最新是 v6.7.1，但 Tags 已经有 v7.0.1，最新 commit message 也在描述 7.0.1 的恢复坐标和 CI gate。也就是说，项目非常活跃，但版本列车推进很快。写生产脚本时，最好固定依赖版本，并且按 README 的安全流程先在副本上验证。
第三个 caveat 是文档主要是韩文。对韩国 HWPX 场景这当然合理，但中文或日文团队第一次评估时会多一点理解成本。好在 API、环境变量和命令名本身相当直白，真正接入时不必依赖大量自然语言说明。
总结
airmang/python-hwpx-automation 是一个小众但很明确的项目：把 HWPX 这种真实办公格式，放进 Python、CLI 和 MCP agent 的可控操作面里。它有意思的不是“又做了一个 MCP server”，而是把文档修改拆成可限制、可验证、可回读的小步动作。
如果你的工作里有 HWPX、公文、表单或本地文档自动化，这个项目值得放进工具箱。对更广泛的 agent 工程来说，它也提供了一个不错的提醒：让 agent 处理文件时，最重要的往往不是生成能力，而是边界、回滚和验证。