# https://github.com/airmang/hwpx-mcp-server 项目说明书生成时间：2026-07-13 10:21:03 UTC ## 目录 - [项目概述与 HWPX 技术栈架构](#page-1) - [MCP 工具表面、契约与能力域](#page-2) - [文档编辑、表单填写与质量门控](#page-3) - [部署、运维与常见故障排查](#page-4) ## 项目概述与 HWPX 技术栈架构 ### 相关页面相关主题：[MCP 工具表面、契约与能力域](#page-2), [文档编辑、表单填写与质量门控](#page-3), [部署、运维与常见故障排查](#page-4)

相关源码文件

以下源码文件用于生成本页说明： - [README.md](https://github.com/airmang/hwpx-mcp-server/blob/main/README.md) - [pyproject.toml](https://github.com/airmang/hwpx-mcp-server/blob/main/pyproject.toml) - [src/hwpx_mcp_server/__init__.py](https://github.com/airmang/hwpx-mcp-server/blob/main/src/hwpx_mcp_server/__init__.py) - [src/hwpx_mcp_server/server.py](https://github.com/airmang/hwpx-mcp-server/blob/main/src/hwpx_mcp_server/server.py) - [src/hwpx_mcp_server/core/__init__.py](https://github.com/airmang/hwpx-mcp-server/blob/main/src/hwpx_mcp_server/core/__init__.py) - [src/hwpx_mcp_server/upstream.py](https://github.com/airmang/hwpx-mcp-server/blob/main/src/hwpx_mcp_server/upstream.py)

# 项目概述与 HWPX 技术栈架构 ## 项目定位与目标 `hwpx-mcp-server` 是一个基于 [Model Context Protocol（MCP）](https://modelcontextprotocol.io/) 的服务端实现，专门用于让 LLM 智能体能够程序化地读取、编辑与生成韩文 HWPX（한/글 XML 容器）文档。该项目作为 HWPX 文档处理栈与 AI 智能体之间的"桥接层"，把底层 `python-hwpx` 库的丰富能力（约 150 个原子工具）暴露为统一、可发现、可验证的 MCP 工具表面。资料来源：[README.md:1-40]() 其核心目标包括： - **互操作性**：把 HWPX 文档标准封装为 LLM 可调用的结构化工具，规避"在复杂 XML 结构中误把 `search` 与 `replace` 混用"等工具调用错误。 - **保真性**：在样式、表格、字符格式等"看不见"的细节上保留模板原貌，避免下游消费者重建（rebuild）带来的副作用。 - **可发现性**：通过 `describe_capabilities` 等能力地图工具把扁平工具表按"任务域"组织，方便智能体按意图选择入口。资料来源：[README.md:42-80]() ## 技术栈分层整个仓库的目录与依赖结构清晰地反映了"上游库 → 核心层 → MCP 服务器 → 工具注册"的四层架构。 | 层级 | 模块 / 路径 | 职责 | |------|------------|------| | 上游适配 | `src/hwpx_mcp_server/upstream.py` | 封装 `python-hwpx` 调用，处理版本兼容与补丁回退 | | 核心能力 | `src/hwpx_mcp_server/core/` | 文档打开/保存、表格补丁、字体物化、字节保持逻辑 | | MCP 入口 | `src/hwpx_mcp_server/server.py` | 基于 FastMCP 注册工具，公开 ToolSpec | | 包入口 | `src/hwpx_mcp_server/__init__.py` | 对外暴露 `mcp` / `app` 等运行对象 | 资料来源：[pyproject.toml:1-50]() 依赖方面，项目以 `fastmcp`、`python-hwpx>=2.23.0` 为运行核心，辅以 `lxml`、`pydantic` 等做 XML 与 schema 校验。`python-hwpx` 的版本下限被显式锁住，原因是 v2.14 引入的 `set_column_widths` / `autofit_columns` 依赖 2.23.0 起开放的 `hwpx.table_patch` 字体物化能力。资料来源：[pyproject.toml:30-75]() ## 核心架构 `hwpx-mcp-server` 的运行入口与注册逻辑集中在 `server.py` 与 `__init__.py` 中。FastMCP 实例化后，通过 `ToolSpec` 契约把"注册、能力汇报、技能 API 文档生成、已安装表面测试"统一到同一份元数据源，避免出现"注册了但能力报告没统计到"的不一致问题——这正是 v2.18.1 修复的核心回归。资料来源：[src/hwpx_mcp_server/server.py:1-120]() ```mermaid flowchart TB A[LLM Agent] -->|MCP JSON-RPC| B[FastMCP Server
server.py] B --> C[ToolSpec Registry
~150 tools] C --> D[Core Layer
core/] D --> E[Upstream Adapter
upstream.py] E --> F[python-hwpx ≥ 2.23.0] F --> G[(HWPX 文档
.hwpx)] B --> H[describe_capabilities
16 domains] ``` 16 个任务域（read·form-fill·author·edit·tables·styles·layout·toc-xref·pii·redline·exam·seal·generators·memo·verify·package）由 v2.18.0 引入的 `describe_capabilities` 暴露，每个域附带 `intent`、`when-to-use` 与入口工具，使智能体能按语义路由而非按扁平名匹配。资料来源：[src/hwpx_mcp_server/server.py:120-260]() ## 关键设计原则 - **字节保持（byte-preserving）**：从 v2.13.0 起，`apply_table_ops` 等结构化表单填写工具被明确为"事务性 + 永不重建"，未触碰的字节原样保留。这是对早期"重排表格破坏原格式"事故的根因修复。资料来源：[src/hwpx_mcp_server/core/__init__.py:1-80]() - **确定性路由（deterministic routing）**：社区在 #66 提出的"工具可靠性增强"提案，强调把搜索/替换、读写等易混工具按意图前缀化，降低 LLM 误调用概率。资料来源：[src/hwpx_mcp_server/upstream.py:1-60]() - **原生韩文域支持**：v2.12.0 引入的 `add_toc`、`add_cross_reference`、`verify_toc` 直接调用 Hancom 原生 `TABLEOFCONTENTS` / `CROSSREF` 字段，并把 `dirty=1` 作为默认值——首次打开时由 Hancom 重新计算页码，本仓库仅返回诚实的"估算页码"。资料来源：[src/hwpx_mcp_server/core/__init__.py:80-160]() - **字符格式保真**：v2.18.2 修复了"病态字间距（`hh:spacing <= -40`）导致替换/插入/填表后出现叠印鬼影"问题，只对受影响的 run 克隆到去重后的安全副本，原字符样式与合法压缩间距（如 `-37`）完全保留。资料来源：[src/hwpx_mcp_server/__init__.py:1-40]() ## 已知约束社区已记录的常见踩坑点包括： - **ID 溢出**：v2.18.2 之前 `add_paragraph` / `add_table` / `add_memo` 等工具会下发 `>= 2^31` 的段落 ID，源于上游 `python-hwpx` 的 `_paragraph_id` 计数器未对齐 32 位约束（#63）。 - **Windows 环境**：在 Windows 11 + Claude Desktop 下，需注意路径中的韩文/特殊字符与 `file://` URI 编码，否则 MCP 调用会以 `tool call failed` 终止（#56）。资料来源：[README.md:80-140]() --- ## MCP 工具表面、契约与能力域 ### 相关页面相关主题：[项目概述与 HWPX 技术栈架构](#page-1), [文档编辑、表单填写与质量门控](#page-3), [部署、运维与常见故障排查](#page-4)

相关源码文件

以下源码文件用于生成本页说明： - [src/hwpx_mcp_server/tools.py](https://github.com/airmang/hwpx-mcp-server/blob/main/src/hwpx_mcp_server/tools.py) - [src/hwpx_mcp_server/capabilities.py](https://github.com/airmang/hwpx-mcp-server/blob/main/src/hwpx_mcp_server/capabilities.py) - [src/hwpx_mcp_server/tool_contract.py](https://github.com/airmang/hwpx-mcp-server/blob/main/src/hwpx_mcp_server/tool_contract.py) - [src/hwpx_mcp_server/metadata/tools_meta.py](https://github.com/airmang/hwpx-mcp-server/blob/main/src/hwpx_mcp_server/metadata/tools_meta.py) - [src/hwpx_mcp_server/core/document.py](https://github.com/airmang/hwpx-mcp-server/blob/main/src/hwpx_mcp_server/core/document.py) - [src/hwpx_mcp_server/core/content.py](https://github.com/airmang/hwpx-mcp-server/blob/main/src/hwpx_mcp_server/core/content.py)

# MCP 工具表面、契约与能力域 ## 1. 设计目标与总体职责 `hwpx-mcp-server` 在 LLM 工具调用层暴露约 150 个扁平工具，覆盖 HWPX 文档的读取、表单填写、编辑、表格、样式、版面、目录/交叉引用、PII 脱敏、修订、考试、印章、生成器、备忘录、验证与打包共 16 个能力域。为了让智能体在面对庞大的扁平工具列表时仍能选择正确入口，并在 LLM 工具调用错配（如将 `search` 与 `replace` 混淆）时保持可观察的契约一致性，仓库自 v2.18.0/v2.18.1 起构建了「**ToolSpec 契约 + 能力域映射 + 元数据注册**」三层结构。 - 契约层：`tool_contract.py` 用 `ToolSpec` 统一描述名称、入参、域、用途、副作用。 - 注册层：`tools.py` 借助 `FastMCP` 入口把 `ToolSpec` 真正暴露为 MCP 工具。 - 能力域层：`capabilities.py` + `metadata/tools_meta.py` 把扁平工具聚合为面向任务的 16 个能力域，并通过 `describe_capabilities` 让智能体按意图挑选入口工具。资料来源：[src/hwpx_mcp_server/tool_contract.py:1-120]()，[src/hwpx_mcp_server/capabilities.py:1-80]()。 ## 2. ToolSpec 契约：注册、报告与文档的唯一真源 v2.18.1 明确把「legacy-union/count-based 健康检查」替换为「exact `ToolSpec` contract」，由注册、能力报告、生成式 skill API 文档与已安装表面测试共同遵守同一份契约。`ToolSpec` 通常包含： - `name`：MCP 工具名（例如 `add_paragraph`、`apply_table_ops`、`describe_capabilities`）。 - `domain`：所属能力域枚举（read/form-fill/author/edit/tables/styles/layout/toc-xref/pii/redline/exam/seal/generators/memo/verify/package）。 - `intent` / `when_to_use`：供 `describe_capabilities` 输出的人类可读说明。 - `params`：JSON-Schema 风格的入参定义。 - `mutates` / `byte_preserving`：声明副作用级别，对应「字节保留表单填写」等不变量。该契约在注册、能力报告与生成文档之间被共享，使「工具真实在册」与「对外承诺」不再分裂。资料来源：[src/hwpx_mcp_server/tool_contract.py:30-200]()，[src/hwpx_mcp_server/metadata/tools_meta.py:1-160]()。 ## 3. FastMCP 入口与工具注册 `tools.py` 是发布面（release-facing）的 FastMCP 入口，承担： 1. **ToolSpec → MCP 工具的绑定**：遍历 `tool_contract` 列表，把每个 `ToolSpec` 注册到 FastMCP server。 2. **健康检查**：v2.18.1 后不再使用「注册表并集 ∩ 计数」近似，而是基于精确 `ToolSpec` 集合判断「已声明 = 已安装」。 3. **核心/MCP/插件兼容层**：`tools.py` 同时处理核心库（`core/document.py`、`core/content.py`）与外部插件之间的版本兼容，避免在工具层出现降级。 4. **七个通用表单填写工具的恢复**：v2.18.1 显式把 `scan_form_guidance`、`apply_body_ops`、`inspect_fill_residue` 与 `apply_table_ops` 子操作（`fill_cell`、`delete_column`、`delete_row`、`delete_table`、`insert_row_by_clone`、`split_cell_vertical`、`clone_table`、`set_column_widths`、`autofit_columns` 等）重新挂载到发布入口。资料来源：[src/hwpx_mcp_server/tools.py:1-180]()，[src/hwpx_mcp_server/core/document.py:1-120]()。 ## 4. 能力域映射与 `describe_capabilities` `capabilities.py` 实现 `describe_capabilities` 工具，按 16 个能力域输出「意图 + 何时使用 + 入口工具」三元组，支持 `domain=` 过滤单个域。模型示意如下： ```mermaid flowchart LR A[智能体/Agent] -->|describe_capabilities domain=form-fill| B[capabilities.py] B --> C[domain 表
read·form-fill·author·edit·tables·styles
layout·toc-xref·pii·redline·exam·seal
generators·memo·verify·package] C --> D[入口工具
scan_form_guidance · apply_body_ops
apply_table_ops · inspect_fill_residue] D --> E[tool_contract.ToolSpec] E --> F[tools.py FastMCP 入口] ``` 该设计直接回应了社区关切（参考 [Issue #66](https://github.com/airmang/hwpx-mcp-server/issues/66)）：在 LLM 工具调用层引入确定性的「意图 → 入口」路由，把容易混淆的扁平调用收敛到稳定的能力域。资料来源：[src/hwpx_mcp_server/capabilities.py:20-220]()，[src/hwpx_mcp_server/metadata/tools_meta.py:160-360]()。 ## 5. 已知问题与可靠性边界 - **大 ID 越界**：[Issue #63](https://github.com/airmang/hwpx-mcp-server/issues/63) 指出 `add_paragraph`、`add_table`、`add_memo` 等编辑工具透出的 ID ≥ 2³¹，源自上游 `python-hwpx` 的 `hwpx.oxml.document._paragraph_id` 等辅助函数。`ToolSpec` 契约并未对 ID 范围做约束，提示应在客户端做规范化或在元数据中标注「ID 类型」。 - **Windows 11 Claude Desktop 失败**：[Issue #56](https://github.com/airmang/hwpx-mcp-server/issues/56) 暴露了运行时分发/路径问题；契约层本身不感知宿主，但 `tools.py` 的 FastMCP 注册需要稳定的入口与依赖。 - **字形叠印**：v2.18.2 修复了模板占位符 `hh:spacing <= -40` 时的不可读叠印。该修复属于运行时行为而非契约变更，但强调了对「被改动 run」做精确识别（`ToolSpec.mutates` + 字节保留路径）的重要性。资料来源：[src/hwpx_mcp_server/core/content.py:1-160]()，[src/hwpx_mcp_server/tools.py:180-360]()。 ## 6. 小结「MCP 工具表面」由 `ToolSpec` 契约唯一定义；「契约」通过 `tools.py` 的 FastMCP 入口真正注册；「能力域」由 `capabilities.py` + `tools_meta.py` 聚合并通过 `describe_capabilities` 对智能体可见。三层共享同一份 `ToolSpec`，从而在 v2.18.1 后消除了「声明 = 安装」的歧义，也为基础设施层（核心/MCP/插件）的版本兼容提供了清晰的接缝。社区提出的确定性路由（#66）与 ID 规范化（#63）将进一步收紧这层契约。 --- ## 文档编辑、表单填写与质量门控 ### 相关页面相关主题：[项目概述与 HWPX 技术栈架构](#page-1), [MCP 工具表面、契约与能力域](#page-2), [部署、运维与常见故障排查](#page-4)

相关源码文件

以下源码文件用于生成本页说明： - [src/hwpx_mcp_server/core/handles.py](https://github.com/airmang/hwpx-mcp-server/blob/main/src/hwpx_mcp_server/core/handles.py) - [src/hwpx_mcp_server/core/locations.py](https://github.com/airmang/hwpx-mcp-server/blob/main/src/hwpx_mcp_server/core/locations.py) - [src/hwpx_mcp_server/core/locator.py](https://github.com/airmang/hwpx-mcp-server/blob/main/src/hwpx_mcp_server/core/locator.py) - [src/hwpx_mcp_server/core/plan.py](https://github.com/airmang/hwpx-mcp-server/blob/main/src/hwpx_mcp_server/core/plan.py) - [src/hwpx_mcp_server/core/transactions.py](https://github.com/airmang/hwpx-mcp-server/blob/main/src/hwpx_mcp_server/core/transactions.py) - [src/hwpx_mcp_server/core/txn.py](https://github.com/airmang/hwpx-mcp-server/blob/main/src/hwpx_mcp_server/core/txn.py)

# 文档编辑、表单填写与质量门控 ## 概述 hwpx-mcp-server 的核心层在 `core/` 包内承担三类相互衔接的职责：元素身份与定位（handles、locations、locator）、结构化计划与事务（plan、transactions、txn），以及由 MCP 表层工具统一调用的"编辑、表单填写、质量门控"能力。这套分层让"agent 发出意图 → 拆解为结构化操作 → 事务化落盘 → 验证门控"形成可观测链路，并支撑 v2.18.0 引入的 16 域能力图（`describe_capabilities`）与 v2.18.1 重写的 ToolSpec 契约。 ## 元素身份、句柄与定位 `handles.py` 负责为段落、表格、单元格、批注等对象分配稳定句柄。Issue #63 指出 `add_paragraph`、`insert_paragraph`、`add_table`、`add_memo` 等编辑工具在调用上游 `python-hwpx` 的 `hwpx.oxml.document._paragraph_id` 等助手后，会回写 `>= 2^31` 的大整数 id；因此 `handles.py` 必须对 id 范围做规范化封装，使下游 consumer 看到的始终是受控的句柄空间资料来源：[src/hwpx_mcp_server/core/handles.py:1-120]()。 `locations.py` 与 `locator.py` 共同实现"位置描述符"模型：`locations` 定义可序列化的位置结构（段落索引、表格路径、子元素偏移），`locator` 把位置解析回运行时 XML 节点。编辑工具链在执行前需先经 `locator` 解析，失败时回退到 dryRun 报告，这一约定是 v2.17.0 `apply_body_ops` 的 `dryRun` 参数以及 v2.13.0 `apply_table_ops` 字节保留语义的实现基础资料来源：[src/hwpx_mcp_server/core/locations.py:1-200]() 资料来源：[src/hwpx_mcp_server/core/locator.py:1-200]()。 ## 计划、事务与字节保留 `plan.py` 承载"文档计划"抽象，是 v2.16.0 `markdown_plan` 桥与外部 Markdown → `hwpx.document_plan` 转换的内部表示。计划由有序的段落/表格/批注 ops 组成，结构上与 `apply_table_ops` 的 ops 列表、`apply_body_ops` 的 op 序列保持一致，使编辑器、表单填写器、内容生成器共用同一套执行底盘资料来源：[src/hwpx_mcp_server/core/plan.py:1-200]()。 `transactions.py` 与 `txn.py` 形成两层事务模型：`txn.py` 提供底层 begin/commit/rollback 语义，`transactions.py` 在其之上叠加"字节保留"约束——即 v2.13.0 release notes 明确强调的"never rebuild"，未触及的字节必须原样保留。该约束要求所有 op 在执行时对 XML 切片做精确的就地编辑，而不是把整段 section 序列化-反序列化重建，这也是 v2.18.2 修复"病态字符间距（`hh:spacing <= -40`）下字形重印"问题所依赖的基础资料来源：[src/hwpx_mcp_server/core/txn.py:1-150]() 资料来源：[src/hwpx_mcp_server/core/transactions.py:1-200]()。 ## 表单填写与质量门控通用表单填写工具集（`apply_table_ops`、`apply_body_ops`、`scan_form_guidance`、`inspect_fill_residue`）在 v2.17.0 完成 Stage 3 表层；其内部执行顺序遵循"先定位（locator）→ 计划（plan）→ 事务（txn）→ 残留检查（inspect_fill_residue）"的链路。v2.18.2 进一步修复了当模板占位符携带 `hh:spacing <= -40` 病态字符间距时出现的字形重印：被改写 run 重新映射到去重的安全克隆，而源字符样式与合法的负间距（如 -37）保持原样资料来源：[src/hwpx_mcp_server/core/locator.py:200-400]() 资料来源：[src/hwpx_mcp_server/core/transactions.py:200-400]()。质量门控由两类工具组成：结构验证（`verify_toc` 检查 TABLEOFCONTENTS 与 CROSSREF 缓存一致性，提供 v2.12.0 引入的"无 oracle 的 stale 信号"）和契约验证（v2.18.1 重写的 ToolSpec 契约，统一覆盖注册、能力报告、生成的技能 API 文档与 installed-surface 测试）。两者共享 `locator` 与 `plan` 提供的可定位语义，使"未通过门控即可回滚"成为可能，也呼应了 Issue #66 关于"在复杂 XML 结构上提升工具调用确定性"的诉求资料来源：[src/hwpx_mcp_server/core/handles.py:120-260]() 资料来源：[src/hwpx_mcp_server/core/plan.py:200-400]()。 | 层 | 文件 | 主要职责 | |---|---|---| | 句柄 / 位置 | `handles.py`、`locations.py`、`locator.py` | 元素身份、位置描述符、运行时解析 | | 计划 / 事务 | `plan.py`、`txn.py`、`transactions.py` | 结构化计划、字节保留事务、Markdown 桥接 | --- ## 部署、运维与常见故障排查 ### 相关页面相关主题：[项目概述与 HWPX 技术栈架构](#page-1), [MCP 工具表面、契约与能力域](#page-2), [文档编辑、表单填写与质量门控](#page-3)

相关源码文件

以下源码文件用于生成本页说明： - [README.md](https://github.com/airmang/hwpx-mcp-server/blob/main/README.md) - [Dockerfile](https://github.com/airmang/hwpx-mcp-server/blob/main/Dockerfile) - [pyproject.toml](https://github.com/airmang/hwpx-mcp-server/blob/main/pyproject.toml) - [CHANGELOG.md](https://github.com/airmang/hwpx-mcp-server/blob/main/CHANGELOG.md) - [src/hwpx_mcp_server/legacy_server.py](https://github.com/airmang/hwpx-mcp-server/blob/main/src/hwpx_mcp_server/legacy_server.py) - [src/hwpx_mcp_server/errors.py](https://github.com/airmang/hwpx-mcp-server/blob/main/src/hwpx_mcp_server/errors.py)

# 部署、运维与常见故障排查本页面向在生产环境或本地桌面端（如 Claude Desktop）部署并运行 `hwpx-mcp-server` 的工程师、运维与 LLM 代理集成者，覆盖安装方式、运行时配置、健康检查、典型故障路径及对应的处置建议。 ## 部署方式与运行环境 `hwpx-mcp-server` 是一个面向 Model Context Protocol 的工具服务器，向 LLM 暴露约 150 个针对韩文 HWPX（`.hwpx`，即 ZIP 内含 OXML 的容器）的读写、改写、表单填充、目录与样式等工具。其部署形态由 `pyproject.toml` 与 `Dockerfile` 共同定义。 - **Python 包安装**：通过 `pyproject.toml` 中声明的入口点（如 `hwpx-mcp-server`）以 `pip install` 或 `uv`/`poetry` 方式安装，依赖 `python-hwpx`（≥ 2.23.0，用于表格字体物化等高级特性）。资料来源：[pyproject.toml:1-80]() - **容器化部署**：根目录 `Dockerfile` 提供标准化的容器镜像，可通过 MCP 客户端以 stdio 或 HTTP/SSE 协议注入，避免本地 Python 环境污染。 - **桌面端 MCP 集成**：在 Claude Desktop 等桌面客户端中，通过 `claude_desktop_config.json` 注册 `command` + `args`，并通过 `cwd` 或 `HWPX_DOCS_ROOT` 等环境变量限定可访问的文档目录。 ## 关键配置与运行参数运行时行为主要由 `legacy_server.py` 中 FastMCP 入口的 ToolSpec 契约控制；自 v2.18.1 起，工具注册、能力报告、生成的技能 API 文档与已安装表面测试共享同一份精确 ToolSpec 契约，不再依赖旧的 union/count 健康检查。资料来源：[CHANGELOG.md:2026-07-10]() 常用配置项： | 配置项 | 作用 | 备注 | | --- | --- | --- | | `HWPX_DOCS_ROOT` | 限定可读写的根目录，避免越权访问 | Windows 下必须使用正斜杠或原始字符串 | | `HWPX_MAX_FILE_SIZE` | 单文档大小上限，防止 OOM | 与 `python-hwpx` 解析能力对齐 | | `HWPX_TOOLSET_FILTER` | 按 `domain=` 过滤暴露的 16 个领域（read·form-fill·author·edit·tables·styles·layout·toc-xref·pii·redline·exam·seal·generators·memo·verify·package） | v2.18.0 引入 `describe_capabilities` 后推荐使用 | | `MCP_TRANSPORT` | `stdio` 或 `http+sse` | 容器化部署通常使用后者 | ## 健康检查与能力自描述启动后建议通过 `describe_capabilities` 做一次冒烟测试：它会按 16 个领域返回工具清单、意图描述与推荐入口工具，并附带覆盖率告警，方便运维快速识别当前进程注册的工具集是否符合预期。资料来源：[CHANGELOG.md:2026-07-08]() 自检流程： ```mermaid flowchart LR A[启动进程] --> B[注册 ToolSpec] B --> C[describe_capabilities] C --> D{覆盖 16 领域?} D -- 是 --> E[进入就绪] D -- 否 --> F[告警并记录缺失领域] ``` ## 常见故障与处置 ### 1. Windows 11 Claude Desktop 调用失败社区报告（issue #56）显示，Claude Desktop 通过 `file:///C:/...` 协议头访问本地 HWPX 时，会出现 `tool call failed`。根因通常是： - **路径分隔符**：MCP 客户端传给工具的 Windows 绝对路径包含反斜杠或韩文文件名（如 `(연구개발계획서)참여연구자 현황.hwpx`），需要在调用前用 `pathlib.Path.as_posix()` 归一化。资料来源：[issue #56]() - **容器路径隔离**：若 MCP 以容器方式运行而文档在宿主 Windows 上，必须通过卷挂载并显式声明 `:z` 或 `:ro` SELinux 标签。 - **编码**：HWPX 内部 XML 声明使用 UTF-8，但韩文文件名若以 CP949 写入，会被 `python-hwpx` 拒绝解析。 ### 2. 编辑工具产出的 ID 越界 issue #63 指出，`add_paragraph` / `insert_paragraph` / `add_table` / `add_memo` 等编辑工具经 `python-hwpx` 的 `hwpx.oxml.document._paragraph_id` 等辅助函数生成的新节点 ID ≥ 2^31，会被部分下游 HWP 渲染器或校验器拒绝。临时规避方案是在写入后做一次 `replace_id_with_safe_int`，并通过 `verify_toc` / `verify_render` 复核；长期修复需等待上游 `python-hwpx` 调整 ID 生成器。资料来源：[issue #63]() ### 3. 模板病态字符间距导致的“鬼影字” v2.18.2 修复了当模板占位符携带 `hh:spacing <= -40` 时，文本替换、段落插入、单元格填充后出现的不可读字形叠印。仅被改写的运行会被重映射到去重后的安全克隆，源字符样式与合法的负间距（如 `-37`）保持不变。资料来源：[CHANGELOG.md:2026-07-13]() ### 4. 表单填充残留与字节保护 - `apply_table_ops`（v2.13.0 起）以事务方式执行 `fill_cell` / `delete_column` / `delete_row` / `delete_table` / `insert_row_by_clone`，强制保留原表格格式与未触及字节，绝不重建表格。 - `inspect_fill_residue`（v2.17.0 起）作为“填零检出门”，在表单填充后必须返回 0 残留，否则应回滚并重试。 ### 5. 错误码与异常分类 `errors.py` 统一了 MCP 返回的错误结构，包含 `code`（如 `HWPX_PARSE_ERROR`、`HWPX_OXML_LOCKED`、`HWPX_TEMPLATE_SPACING`）、`message` 与 `details.affected_ids[]`，便于运维侧按错误码做告警路由。资料来源：[src/hwpx_mcp_server/errors.py:1-120]() ## 运维最佳实践 1. **版本对齐**：将 `hwpx-mcp-server` 与 `python-hwpx` 锁版本，避免被 v2.15.0 之后的 `apply_table_ops fill_cell max_lines` 等新特性反向破坏。 2. **目录权限最小化**：永远以非 root 用户运行容器，并通过 `HWPX_DOCS_ROOT` 只读挂载样本、读写挂载工作目录。 3. **能力变更可观测**：订阅 release note，重点关注 v2.18.1 引入的 ToolSpec 契约变更，必要时用 `describe_capabilities` 回归测试。 4. **表单工作流三段闸**：Stage 1 读取 → Stage 2 `scan_form_guidance` 侦察 → Stage 3 `apply_table_ops` / `apply_body_ops` 写入 → `inspect_fill_residue` 验证，形成闭环。 5. **故障复现三件套**：保留原文件、`describe_capabilities` 输出、`tool call` 的完整 payload（含 path、ops、参数），便于提交 issue 时快速定位。 --- --- ## Doramagic 踩坑日志项目：airmang/hwpx-mcp-server 摘要：发现 23 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：配置坑 - 来源证据：Windows 11 Claude Desktop 환경에서 작동 실패。 ## 1. 配置坑 · 来源证据：Windows 11 Claude Desktop 환경에서 작동 실패 - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Windows 11 Claude Desktop 환경에서 작동 실패 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/airmang/hwpx-mcp-server/issues/56 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。 ## 2. 安装坑 · 失败模式：installation: Documents emitted by `add_paragraph` / `add_table` / `add_memo` carry ids `>= 2^31` - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: Documents emitted by `add_paragraph` / `add_table` / `add_memo` carry ids `>= 2^31` - 对用户的影响：Developers may fail before the first successful local run: Documents emitted by `add_paragraph` / `add_table` / `add_memo` carry ids `>= 2^31` - 证据：failure_mode_cluster:github_issue | https://github.com/airmang/hwpx-mcp-server/issues/63 | Documents emitted by `add_paragraph` / `add_table` / `add_memo` carry ids `>= 2^31` ## 3. 安装坑 · 失败模式：installation: v2.18.1 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: v2.18.1 - 对用户的影响：Upgrade or migration may change expected behavior: v2.18.1 - 证据：failure_mode_cluster:github_release | https://github.com/airmang/hwpx-mcp-server/releases/tag/v2.18.1 | v2.18.1 ## 4. 安装坑 · 来源证据：Documents emitted by `add_paragraph` / `add_table` / `add_memo` carry ids `>= 2^31` - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Documents emitted by `add_paragraph` / `add_table` / `add_memo` carry ids `>= 2^31` - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/airmang/hwpx-mcp-server/issues/63 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 5. 安装坑 · 来源证据：✨️ Proposal: Enhancing HWPX Tool Reliability via Deterministic Routing - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：✨️ Proposal: Enhancing HWPX Tool Reliability via Deterministic Routing - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/airmang/hwpx-mcp-server/issues/66 | 来源类型 github_issue 暴露的待验证使用条件。 ## 6. 配置坑 · 可能修改宿主 AI 配置 - 严重度：medium - 证据强度：source_linked - 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。 - 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 - 证据：capability.host_targets | https://github.com/airmang/hwpx-mcp-server | host_targets=mcp_host, claude, cursor, gemini_cli ## 7. 配置坑 · 失败模式：configuration: Windows 11 Claude Desktop 환경에서 작동 실패 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: Windows 11 Claude Desktop 환경에서 작동 실패 - 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Windows 11 Claude Desktop 환경에서 작동 실패 - 证据：failure_mode_cluster:github_issue | https://github.com/airmang/hwpx-mcp-server/issues/56 | Windows 11 Claude Desktop 환경에서 작동 실패 ## 8. 配置坑 · 失败模式：configuration: v2.12.0 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: v2.12.0 - 对用户的影响：Upgrade or migration may change expected behavior: v2.12.0 - 证据：failure_mode_cluster:github_release | https://github.com/airmang/hwpx-mcp-server/releases/tag/v2.12.0 | v2.12.0 ## 9. 配置坑 · 失败模式：configuration: v2.13.0 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: v2.13.0 - 对用户的影响：Upgrade or migration may change expected behavior: v2.13.0 - 证据：failure_mode_cluster:github_release | https://github.com/airmang/hwpx-mcp-server/releases/tag/v2.13.0 | v2.13.0 ## 10. 配置坑 · 失败模式：configuration: v2.18.0 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: v2.18.0 - 对用户的影响：Upgrade or migration may change expected behavior: v2.18.0 - 证据：failure_mode_cluster:github_release | https://github.com/airmang/hwpx-mcp-server/releases/tag/v2.18.0 | v2.18.0 ## 11. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/airmang/hwpx-mcp-server | README/documentation is current enough for a first validation pass. ## 12. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/airmang/hwpx-mcp-server | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/airmang/hwpx-mcp-server | no_demo; severity=medium ## 14. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/airmang/hwpx-mcp-server | no_demo; severity=medium ## 15. 运行坑 · 失败模式：performance: ✨️ Proposal: Enhancing HWPX Tool Reliability via Deterministic Routing - 严重度：low - 证据强度：source_linked - 发现：Developers should check this performance risk before relying on the project: ✨️ Proposal: Enhancing HWPX Tool Reliability via Deterministic Routing - 对用户的影响：Developers may hit a documented source-backed failure mode: ✨️ Proposal: Enhancing HWPX Tool Reliability via Deterministic Routing - 证据：failure_mode_cluster:github_issue | https://github.com/airmang/hwpx-mcp-server/issues/66 | ✨️ Proposal: Enhancing HWPX Tool Reliability via Deterministic Routing ## 16. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/airmang/hwpx-mcp-server | issue_or_pr_quality=unknown ## 17. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/airmang/hwpx-mcp-server | release_recency=unknown ## 18. 维护坑 · 失败模式：maintenance: v2.11.0 - 严重度：low - 证据强度：source_linked - 发现：Developers should check this maintenance risk before relying on the project: v2.11.0 - 对用户的影响：Upgrade or migration may change expected behavior: v2.11.0 - 证据：failure_mode_cluster:github_release | https://github.com/airmang/hwpx-mcp-server/releases/tag/v2.11.0 | v2.11.0 ## 19. 维护坑 · 失败模式：maintenance: v2.14.0 - 严重度：low - 证据强度：source_linked - 发现：Developers should check this maintenance risk before relying on the project: v2.14.0 - 对用户的影响：Upgrade or migration may change expected behavior: v2.14.0 - 证据：failure_mode_cluster:github_release | https://github.com/airmang/hwpx-mcp-server/releases/tag/v2.14.0 | v2.14.0 ## 20. 维护坑 · 失败模式：maintenance: v2.15.0 - 严重度：low - 证据强度：source_linked - 发现：Developers should check this maintenance risk before relying on the project: v2.15.0 - 对用户的影响：Upgrade or migration may change expected behavior: v2.15.0 - 证据：failure_mode_cluster:github_release | https://github.com/airmang/hwpx-mcp-server/releases/tag/v2.15.0 | v2.15.0 ## 21. 维护坑 · 失败模式：maintenance: v2.16.0 - 严重度：low - 证据强度：source_linked - 发现：Developers should check this maintenance risk before relying on the project: v2.16.0 - 对用户的影响：Upgrade or migration may change expected behavior: v2.16.0 - 证据：failure_mode_cluster:github_release | https://github.com/airmang/hwpx-mcp-server/releases/tag/v2.16.0 | v2.16.0 ## 22. 维护坑 · 失败模式：maintenance: v2.17.0 - 严重度：low - 证据强度：source_linked - 发现：Developers should check this maintenance risk before relying on the project: v2.17.0 - 对用户的影响：Upgrade or migration may change expected behavior: v2.17.0 - 证据：failure_mode_cluster:github_release | https://github.com/airmang/hwpx-mcp-server/releases/tag/v2.17.0 | v2.17.0 ## 23. 维护坑 · 失败模式：maintenance: v2.18.2 - 严重度：low - 证据强度：source_linked - 发现：Developers should check this maintenance risk before relying on the project: v2.18.2 - 对用户的影响：Upgrade or migration may change expected behavior: v2.18.2 - 证据：failure_mode_cluster:github_release | https://github.com/airmang/hwpx-mcp-server/releases/tag/v2.18.2 | v2.18.2