内容
# HWPX · Excel · QGIS 本地工具，用于 Codex
[中文](#中文)
> 中文 HWPX、Microsoft Excel、QGIS QGS/QGZ 文件在 Codex 中的本地安全处理工具集。
## 中文
### 介绍
本项目提供三个本地工具集，允许在 Codex 中直接检查和编辑文档、电子表格和 GIS 项目。
- `$hwpx-local`：验证 HWPX 结构，分析合并单元格、标题、主体、底部表单、内外边框，搜索、提取、替换文本，使用韩文办公软件进行打开检查和 PDF 转换
- `$excel-local`：检查工作簿、表格和公式，读取和搜索范围，保留格式写入，重新计算 Excel，导出 PDF
- `$qgis-local`：检查 QGS/QGZ 项目和图层，审计缺失数据源，重置路径，查询和运行 QGIS Processing 算法
每个工具都可以作为本地 MCP 服务器使用，也可以作为 `$` 技能在当前 Codex 任务中直接调用本地运行器。
### 安全模型
- 默认情况下，编辑操作会创建单独的副本，而不是覆盖源文件。
- HWPX 操作验证 ZIP/XML 完整性，Excel 操作使用本地 Excel COM 进行保真，QGZ 操作检查嵌入的 QGS XML 和图层源。
- 中文路径和 JSON 有效载荷以 UTF-8 传递。
- 用户文档、测试产物、虚拟环境和特定于机器的运行时路径被排除在 Git 之外。
### 要求
- Windows 10/11
- [uv](https://docs.astral.sh/uv/) 和 Python 3.11
- Codex CLI
- 可选的本地应用程序：
- 韩文办公软件，用于本地 HWPX 打开检查和 PDF 导出
- Microsoft Excel，用于高保真 COM 编辑、重新计算和 PDF 导出
- QGIS，用于 Processing 算法
### 安装
```powershell
git clone https://github.com/kdhchgo-bit/hwpx-excel-qgis-qgz-mcp.git
cd hwpx-excel-qgis-qgz-mcp
powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1
```
在需要时，传递自定义 QGIS Processing 路径：
```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1 `
-QgisProcessPath 'C:\OSGeo4W\bin\qgis_process-qgis-ltr.bat'
```
安装程序创建项目虚拟环境，将所有三个 MCP 服务器注册到 Codex，并将三个 `$` 技能安装在用户的全局技能目录中。打开新的 Codex 任务或重启应用程序，然后调用 `$hwpx-local`、`$excel-local` 或 `$qgis-local`。
### 示例提示
```text
$hwpx-local 检查 D:\docs\report.hwpx 并创建一个替换 250mm 为 350mm 的单独副本。
$hwpx-local 分析 D:\docs\form.hwpx 中每个表格的合并单元格、标题/主体/页脚角色和内外边框。
$excel-local 读取 D:\data\estimate.xlsx 中的 Summary!G3:H30 并填充值，同时保留现有格式。
$qgis-local 审计 D:\GIS\project.qgz 中缺失的图层源，并创建一个具有重置路径的副本。
```
自然语言路由可以自动选择技能，但显式命名 `$skill-name` 是最可靠的选择。
### 验证
```powershell
.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe .\scripts\smoke_mcp.py
```
`verify_real_files.py` 使用私有本地文件和已安装的桌面应用程序。它旨在进行工作站验收测试，而不是通用公共 CI。
## 可用工具
| 服务器/技能 | 工具 |
|---|---|
| `hwpx-local` | `hwpx_validate`, `hwpx_inspect`, `hwpx_analyze_tables`, `hwpx_extract_text`, `hwpx_find_text`, `hwpx_replace_text`, `hwpx_native_open_check`, `hwpx_export_pdf` |
| `excel-local` | `excel_inspect`, `excel_read_range`, `excel_find`, `excel_write_range`, `excel_recalculate`, `excel_export_pdf` |
| `qgis-local` | `qgz_inspect`, `qgz_audit_sources`, `qgz_rebase_paths`, `qgis_list_algorithms`, `qgis_algorithm_help`, `qgis_run_algorithm` |
## 技术参考
- [模型上下文协议 Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [QGIS 项目文件](https://docs.qgis.org/3.44/en/docs/user_manual/introduction/project_files.html)
- [QGIS QGS/QGZ 文件格式](https://docs.qgis.org/3.44/en/docs/user_manual/appendices/qgis_file_formats.html)
