内容
<p align="center">
<h1 align="center">Python-HWPX自动化</h1>
<p align="center">
<strong>用于HWPX文档创作、模板填充和工作流程的Python自动化层</strong>
</p>
<p align="center">
<a href="https://pypi.org/project/python-hwpx-automation/"><img src="https://img.shields.io/pypi/v/python-hwpx-automation?color=blue&label=PyPI" alt="PyPI"></a>
<a href="https://pepy.tech/project/python-hwpx-automation"><img src="https://static.pepy.tech/badge/python-hwpx-automation/month" alt="Downloads"></a>
<a href="https://pypi.org/project/python-hwpx-automation/"><img src="https://img.shields.io/pypi/pyversions/python-hwpx-automation" alt="Python"></a>
<a href="https://github.com/airmang/python-hwpx-automation/actions/workflows/tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/airmang/python-hwpx-automation/tests.yml?branch=main&label=tests" alt="Tests"></a>
<a href="https://github.com/airmang/python-hwpx-automation/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License"></a>
</p>
</p>
<!-- release-state: released -->
> [!NOTE]
> 当前公开版本为 `python-hwpx 5.0.1 → python-hwpx-automation 6.0.4 → hwpx-plugin 1.0.0`（合约 `0ce938371f0b55a6`，2026-07-28 发布）。核心和自动化 PyPI 以及插件 GitHub 发布和市场验证后已提升。现有 5.x 安装由单独发布的 `hwpx-mcp-server 5.1.1` 保护。流程和状态机：[发布运行手册](docs/release-runbook.md)
在 [python-hwpx](https://github.com/airmang/python-hwpx) 引擎上提供文档创作、模板填充、试卷排版和安全代理工作流程的应用层。基本安装使用 Python API 和 `hwpx` CLI，无需 MCP 服务器。可选的 MCP 服务器通过 `[mcp]` 额外功能添加。不需要韩文 Office 或 Windows，因此即使在 **Python 可运行的 ChatGPT 聊天环境中**也能正常工作。
| | 仓库 | 角色 |
|---|---|---|
| 📦 | [`python-hwpx`](https://github.com/airmang/python-hwpx) | 纯 Python 引擎，用于读取、修改和创建 HWPX 文档 |
| 🔌 | [`python-hwpx-automation`](https://github.com/airmang/python-hwpx-automation) | 创作、模板填充工作流程、`hwpx` CLI 和可选 MCP 服务器 |
| 🎯 | [`hwpx-plugins`](https://github.com/airmang/hwpx-plugins) | 帮助代理选择合适工具的插件/技能包 |
## 开始使用 Python 自动化
```bash
pip install python-hwpx-automation
```
```python
from hwpx_automation import create_document_from_plan
document = create_document_from_plan(
{
"schemaVersion": "hwpx.document_plan.v1",
"title": "会议结果",
"blocks": [{"type": "paragraph", "text": "决定事项"}],
}
)
document.save_to_path("meeting-result.hwpx")
```
`python -m hwpx_automation --help` 和 `hwpx help` 运行相同的任务 CLI。
## 开始使用 MCP 适配器
```bash
pip install "python-hwpx-automation[mcp]"
hwpx-automation-mcp
```
在 MCP 客户端配置文件中添加以下块以捕获 `hwpx` 服务器 — Claude Desktop 使用 `claude_desktop_config.json`，VS Code 使用 `.vscode/mcp.json`（键为 `servers` 而非 `mcpServers`），Gemini CLI 使用 `~/.gemini/settings.json`，Cursor 和 Windsurf 使用各自的编辑器 MCP 配置文件。
```json
{
"mcpServers": {
"hwpx": {
"command": "uvx",
"args": [
"--from",
"python-hwpx-automation[mcp]==6.0.4",
"hwpx-automation-mcp"
],
"env": {
"HWPX_AUTOMATION_WORKSPACE_ROOTS": "[\"~/Documents\"]"
}
}
}
}
```
在 `HWPX_AUTOMATION_WORKSPACE_ROOTS` 中指定包含文档的文件夹（绝对路径或 `~`）。Windows 使用 `"[\"C:\\\\hwpx\"]"`。如果值为空，则 GUI 客户端将在系统目录中启动服务器，这可能会阻止所有文档路径 — 建议一开始就指定路径。其他选项请参考 [环境变量](#环境变量) 表。
> 要使用 `document_to_markdown` 读取非 HWPX 文档（PDF/DOCX/XLSX/HTML/TXT），请使用 `pip install "python-hwpx-automation[ingest]"` 安装 MarkItDown 适配器。要求：`Python >= 3.10` · `python-hwpx >= 5.0.0`。
现有 `hwpx-mcp-server` 部署、导入、控制台和配置密钥在 6.x 期间保持不变 — 完整列表和维护规则：[6.x 兼容性表面](docs/compatibility-6x.md)
## 功能
在基本模式下，提供多个 HWPX 工具；在高级模式（`HWPX_AUTOMATION_ADVANCED=1`）下，添加检查和验证工具。
- **读取和导航** — `get_document_info`，`get_document_map`（大纲、表格地图和锚点在一个调用中），`find_text`（不保存）
- **搜索和替换、编辑** — `search_and_replace`，`apply_document_commands`（应用编辑原子、dry-run、回滚和幂等键），`add_tracked_edit`（跟踪更改）
- **表格和模板填充** — `analyze_form_fill` → `apply_form_fill` → `verify_form_fill` 字节保留事务，`table_compute`（求和、子总和）
- **文档创建和公文** — 声明式 `create_document_from_plan`，`inspect_official_document_style`（行政法规 lint），`mail_merge`
- **样式、图片和生成器** — `set_paragraph_format`·`set_page_setup`，`insert_picture`，图片目录·名片·组织结构图
- **预览、提取、恢复和诊断** — `render_preview`（HTML/PNG 自我验证），`hwpx_to_markdown`，`repair_hwpx`，`mcp_server_health`
详细内容：[用例](docs/use-cases.md) · [技能优先工作流程](docs/skill-first-workflows.md)
## 安全使用
一开始不需要记住所有工具。通常流程如下：
1. **读取** — `get_document_info` → `get_document_outline`/`get_document_text` → `find_text`，`get_table_map` 以获取所需部分（不保存）
2. **安全修改** — 使用 `copy_document` 创建副本，应用最小更改（`search_and_replace`，`set_table_cell_text`，`apply_document_commands`），然后重新读取并确认，最后传递审查后的副本。
核心思想是 **先复制 · 最小编辑 · 编辑后重新读取**。修改工具在调用时立即保存，因此请务必在副本上进行审查工作。
模型仅发送操作/计划，不直接编辑原始 XML。普通保存路径通过 python-hwpx 的单个 `SavePipeline` 网关，检查完整性、XML、OPC/ID 和打开安全性，如果网关失败，则不写入任何内容。能力握手使用 fail-closed 阻止核心/自动化/插件版本 + 哈希偏差。安全详细信息：[强化指南](docs/hardening_guide_ko.md) · 旧名称兼容性标识符：[6.x 兼容性表面](docs/compatibility-6x.md)
> **位置约定** — `paragraph_index` 是正文直接段落的 0-based 索引。表格中的段落不混合在此，使用 `{"kind":"table_cell_paragraph","table_index":0,"row":0,"col":1,"cell_paragraph_index":0}` 样式的 `location` 对象，可以直接传递 `get_table_map`/`find_text` 返回的值。
## 环境变量
| 变量 | 描述 | 默认值 |
|---|---|---|
| `HWPX_AUTOMATION_WORKSPACE_ROOTS` | 允许的 workspace 绝对路径 JSON 数组（支持多个根目录）。相对路径基于第一个根目录 | 未设置 → 进程 cwd。 degenerate cwd 被拒绝为 `WORKSPACE_ROOT_INVALID` |
| `HWPX_AUTOMATION_MAX_CHARS` | 文本返回工具的默认最大长度 | `10000` |
| `HWPX_AUTOMATION_AUTOBACKUP` | 如果为 `1`，则在保存前创建 `.bak` 备份 | `1` |
| `HWPX_AUTOMATION_ADVANCED` | 如果为 `1`，则启用高级工具 | `0` |
| `HWPX_AUTOMATION_FETCH_TIMEOUT_SECONDS` | 基于 URL 的 HWPX 获取超时 | `20.0` |
| `HWPX_AUTOMATION_ALLOW_PRIVATE_NETWORK` | 如果为 `1`，则允许受信任的私有/环回 HTTPS 端点。链接本地 · 元数据 · 保留地址仍然被阻止 | `0` |
| `HWPX_AUTOMATION_QUALITY` | 全局默认保存网关策略（`transparent`/`strict`）。工具特定的 `quality` 优先 | `transparent` |
| `HWPX_AUTOMATION_REQUIRE_CAPABILITY` | 如果为 `0`，则关闭 capability 偏差 fail-closed（用于调试/专家） | `1` |
| `HWPX_AUTOMATION_WORKFLOW_STORE` | 持久工作流 SQLite 路径。优先于现有的 `HWPX_WORKFLOW_STORE` | 现有 6.x 状态路径 |
| `LOG_LEVEL` | 日志级别 | `INFO` |
具有相同后缀的现有 `HWPX_MCP_*` 键在 6.x 期间保持为后备，并且如果同时存在两个键，则 `HWPX_AUTOMATION_*` 优先。用于渲染 · 工作流 · 预言 · 插件互操作的保留键的完整列表和工作流 DB 路径规则在 [6.x 兼容性表面](docs/compatibility-6x.md) 中。
路径默认拒绝工作区外部的遍历和符号链接逃逸，URL 输入仅允许 HTTPS 和公共 IP。提供原子重命名的主机的并发注意事项请参见 [强化指南](docs/hardening_guide_ko.md)。
## 贡献
[good first issue](https://github.com/airmang/python-hwpx-automation/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) · [里程碑](https://github.com/airmang/python-hwpx-automation/milestones) · [讨论](https://github.com/airmang/python-hwpx-automation/discussions) · [CONTRIBUTING](CONTRIBUTING.md) · [CHANGELOG](CHANGELOG.md)
```bash
python -m pip install -e ".[test]" # 测试依赖
python -m pytest -q # 运行所有测试
python scripts/run_conformance.py run \
--tier structural --check tests/conformance/golden/structural.json
```
## 致谢
在核心库 [python-hwpx](https://github.com/airmang/python-hwpx) 上运行，并感谢以下公开标准和项目。
- **[OWPML — 开放式文字处理器标记语言（KS X 6101）](https://www.kssn.net/search/stddetail.do?itemNo=K001010119985)** — HWPX 基于的韩国国家标准
- **[hancom-io/hwpx-owpml-model](https://github.com/hancom-io/hwpx-owpml-model)** — OWPML 元素结构参考模型 · **[neolord0/hwpxlib](https://github.com/neolord0/hwpxlib)** — 预言样本语料库
- **[edwardkim/rhwp](https://github.com/edwardkim/rhwp)** — 幂等性和验证网关设计灵感
## License · 维护者
Apache-2.0 ([LICENSE](LICENSE) · [NOTICE](NOTICE)) — **Kohkyuhyun** [@airmang](https://github.com/airmang) · [kokyuhyun@hotmail.com](mailto:kokyuhyun@hotmail.com)
