项目定位与目标

hwpx-mcp-server 是一个基于 Model Context Protocol（MCP） 的服务端实现，专门用于让 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 服务器 → 工具注册"的四层架构。

资料来源：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

flowchart TB
    A[LLM Agent] -->|MCP JSON-RPC| B[FastMCP Server<br/>server.py]
    B --> C[ToolSpec Registry<br/>~150 tools]
    C --> D[Core Layer<br/>core/]
    D --> E[Upstream Adapter<br/>upstream.py]
    E --> F[python-hwpx ≥ 2.23.0]
    F --> G[(HWPX 文档<br/>.hwpx)]
    B --> H[describe_capabilities<br/>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

关键设计原则

资料来源：src/hwpx_mcp_server/core/__init__.py:1-80

资料来源：src/hwpx_mcp_server/upstream.py:1-60

资料来源：src/hwpx_mcp_server/core/__init__.py:80-160

资料来源：src/hwpx_mcp_server/__init__.py:1-40

• 字节保持（byte-preserving）：从 v2.13.0 起，apply_table_ops 等结构化表单填写工具被明确为"事务性 + 永不重建"，未触碰的字节原样保留。这是对早期"重排表格破坏原格式"事故的根因修复。
• 确定性路由（deterministic routing）：社区在 #66 提出的"工具可靠性增强"提案，强调把搜索/替换、读写等易混工具按意图前缀化，降低 LLM 误调用概率。
• 原生韩文域支持：v2.12.0 引入的 add_toc、add_cross_reference、verify_toc 直接调用 Hancom 原生 TABLEOFCONTENTS / CROSSREF 字段，并把 dirty=1 作为默认值——首次打开时由 Hancom 重新计算页码，本仓库仅返回诚实的"估算页码"。
• 字符格式保真：v2.18.2 修复了"病态字间距（hh:spacing <= -40）导致替换/插入/填表后出现叠印鬼影"问题，只对受影响的 run 克隆到去重后的安全副本，原字符样式与合法压缩间距（如 -37）完全保留。

已知约束

社区已记录的常见踩坑点包括：

• 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

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= 过滤单个域。模型示意如下：

flowchart LR
  A[智能体/Agent] -->|describe_capabilities domain=form-fill| B[capabilities.py]
  B --> C[domain 表<br/>read·form-fill·author·edit·tables·styles<br/>layout·toc-xref·pii·redline·exam·seal<br/>generators·memo·verify·package]
  C --> D[入口工具<br/>scan_form_guidance · apply_body_ops<br/>apply_table_ops · inspect_fill_residue]
  D --> E[tool_contract.ToolSpec]
  E --> F[tools.py FastMCP 入口]

该设计直接回应了社区关切（参考 Issue #66）：在 LLM 工具调用层引入确定性的「意图 → 入口」路由，把容易混淆的扁平调用收敛到稳定的能力域。

资料来源：src/hwpx_mcp_server/capabilities.py:20-220，src/hwpx_mcp_server/metadata/tools_meta.py:160-360。

5. 已知问题与可靠性边界

• 大 ID 越界：Issue #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 暴露了运行时分发/路径问题；契约层本身不感知宿主，但 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-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。

部署方式与运行环境

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

常用配置项：

健康检查与能力自描述

启动后建议通过 describe_capabilities 做一次冒烟测试：它会按 16 个领域返回工具清单、意图描述与推荐入口工具，并附带覆盖率告警，方便运维快速识别当前进程注册的工具集是否符合预期。资料来源：CHANGELOG.md:2026-07-08

自检流程：

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 时快速定位。

Pitfall Log / 踩坑日志

项目：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