# ArcGIS Pro Bridge（YghsBridge）

**用 AI 工具外部驱动 ArcGIS Pro** —— 通过 WorkBuddy、豆包、千问、Codex、Claude 等 AI 助手，  
与正在运行的 ArcGIS Pro 建立连接，直接调用 ArcPy / GP 工具完成工作。不用点击、不用复制粘贴、不用手动开 Python 窗口。

> **"外部驱动"就是本项目的主要工作内容**：让 AI 助手成为 ArcGIS Pro 的操作者，Pro 里发生什么、  
> 做成了什么、导出到哪里，都通过 Pro 内的消息面板和通知实时告诉你。

```
AI 工具（WorkBuddy / 豆包 / 千问 / Codex / Claude …）
        │  MCP
        ▼
MCP 适配器 ──▶ Pro 进程内的插件 ──QueuedTask──▶ arcpy / GP 工具
                     │
                     └──▶ Pro 内消息面板 + 通知中心（实时"人话"反馈）
```

装上这个插件后，你的 ArcGIS Pro 就变成"可被 AI 编程"的：

- 跑**任何** GP 工具
- 在 Pro 的**主线程上下文**里跑任意 Python
- 读取当前打开的是哪个工程、地图里有哪些图层
- **在 Pro 里看得到**：内置「YGHS Bridge」停靠面板，实时滚动每条任务进度；  
  每次 GP / Python 调用结束还会在通知中心弹一条
- **提示是"人话"**：面板与通知里显示的不是裸的工具名，而是按这次要做什么生成的句子，例如
  ```
  ⇒ 给 GHFQ 添加文本字段 GHGHYDYD
  ✅ GHGHYDYD 文本字段 已添加成功（0.3 秒）
  ```
- 任务结束自动收尾：**能上图的产物静默加入当前地图**，Excel/DWG 等导出物**自动打开所在文件夹**并提示导出位置

---

## AI 助手外部驱动（核心用法）

本项目解决的就是一件事：**让 AI 助手"接管" ArcGIS Pro**。

你在 AI 工具里说人话，AI 通过 MCP 驱动 Pro 完成实际操作：

| AI 工具                      | 接入方式                                        |
| -------------------------- | ------------------------------------------- |
| **WorkBuddy**              | MCP 连接器里配置本项目的 `mcp-server/server.py`，对话即驱动 |
| **Claude（Desktop / Code）** | `mcpServers` 一段 JSON 即接入                    |
| **豆包 / 千问**                | 支持 MCP 的客户端直接配                              |
| **Codex / 其它编码类 AI**       | 直接调用 `mcp-server/server.py` 暴露的工具           |

AI 能做什么（MCP 工具一览）：

| 工具                       | 作用                              |
| ------------------------ | ------------------------------- |
| `arcgis_pro_status`      | 插件是否在线、Pro 进程号、当前工程路径           |
| `arcgis_pro_list_layers` | 当前地图与图层清单                       |
| `arcgis_pro_show_log`    | 在 Pro 内打开实时消息面板（人可盯着看）          |
| `arcgis_pro_run_python`  | **在 Pro 进程内跑 Python**（arcpy 可用） |
| `arcgis_pro_run_gp`      | 跑任意 GP 工具（含增删字段等改结构的操作）         |

🎬 **效果演示视频**：[用 AI 外部驱动 ArcGIS Pro（B 站）](https://www.bilibili.com/video/BV1uWY16cEZN?t=1.6)



## 功能总览

| 功能                  | 说明                                             |
| ------------------- | ---------------------------------------------- |
| 跑任意 GP 工具           | 含增删字段、改**被图层引用**的数据结构                          |
| 在 Pro 主线程跑任意 Python | `QueuedTask` 上下文，`ArcGISProject("CURRENT")` 可用 |
| 读取工程状态              | 当前工程路径、全部地图与各自图层                               |
| **消息面板**            | 实时滚动任务进度，显示"人话"                                |
| **通知中心**            | 每次调用完成弹一条；失败为高优先级                              |
| **自动收尾**            | 能上图的静默上图；导出物自动开文件夹并提示位置                        |
| **问题反馈菜单**          | 一键跳转 GitHub / 抖音 / B站                          |
| 端口自动避让              | 18750→18761 依次尝试，多开 Pro 不打架                    |

## 环境要求

| 你要做什么   | 需要装什么                                  |
| ------- | -------------------------------------- |
| 只用插件    | **ArcGIS Pro 3.4+**（64 位 Windows）      |
| 用 AI 驱动 | 再加 **Python 3.8+**（纯标准库，**不用装 arcpy**） |
| 自己编译插件  | 再加 **.NET 8 SDK**（不需要 Visual Studio）   |

### Python 环境说明（重要）

- **本项目必须通过 Python 驱动脚本与 ArcGIS Pro 通信**（MCP 适配器与流程脚本全部是 Python）。
- 驱动端只依赖 **Python 标准库**，**不需要安装 arcpy**——arcpy 只在 Pro 进程内由插件调用，  
  驱动环境保持干净。
- **独立虚拟环境**：为避免污染系统 Python，本项目使用独立的 Python 虚拟环境（`.venv/`），  
  其配置随本仓库上传（见 `requirements.txt`，当前零第三方依赖）。创建方式：
  ```bash
  python -m venv .venv
  .venv\Scripts\activate        # Windows
  ```

## 问询机制（执行约定，强制）

AI 通过本插件执行**任何任务**前，必须遵守以下约定：

1. **先核对参数**：执行前列出任务所需的全部参数（图层/字段/单位/坐标系/输出位置等）
2. **缺一项就停**：任何参数缺失时**暂停执行**，逐项列出缺失项及用途，请用户一次性补全
   —— 不得自行假设、不得采用未经确认的默认值
3. **确认后严格执行**：按用户确认的参数执行，中途发现新缺失同样停下来问
4. **破坏性操作二次确认**：清空/删除/覆盖类操作，除问询外还须用户再次明确确认
5. **执行后复核**：GetCount / 抽样值 / 成果文件非空，自查后汇报

每个技能的 SKILL.md 自带「使用前必须先问询」清单（见 `skills/`），与本约定配套生效。

## 快速开始

### 1. 构建并安装插件

需要 **ArcGIS Pro 3.4+** + **.NET SDK 8**（不需要 Visual Studio）。一键脚本会自动找 Pro 安装位置、  
构建前校验插件清单、装完清理缓存：

```bash
./build_addin.sh
```

### 2. 重启 ArcGIS Pro（只需一次）

插件在 Pro 启动时加载，之后**永久自动加载**。

### 3. 配置 MCP 客户端（以 WorkBuddy 为例）

在 WorkBuddy 的 MCP 配置文件（`~/.workbuddy/mcp.json`）中加入：

```json
{
  "mcpServers": {
    "arcgis-pro-bridge": {
      "command": "python",
      "args": ["<仓库路径>/mcp-server/server.py"]
    }
  }
}
```

保存后在 WorkBuddy 的连接器管理里**信任并启用**该服务器，即可在对话中直接驱动 ArcGIS Pro。
其它 MCP 客户端（Claude Desktop、Cursor、豆包、千问等）配置方式相同。

### 4. 验证

在 AI 工具里说一句「看看 ArcGIS Pro 在线吗、开着什么工程」——  
AI 调 `arcgis_pro_status`，面板同时亮起来，就说明全链路通了。

## 业务技能库（可选，用户自定义）

`skills/` 内置 20 个规划 / 国土业务技能（用地用海指标汇总、三调 DLBM 转换、
三线占用汇总、批量地类统计、图幅号计算…），对 AI 说
「执行 skills 里的『用地用海指标汇总』」即可调用。

**这是用户可自定义的部分**：把你自己的工具箱 / GP 工具序列 / arcpy 脚本
按模板打包成一个 SKILL.md 放进 `skills/`，AI 就能像内置能力一样调用——
打包与调用方法见 **[skills/README.md](skills/README.md)**。

## 收尾行为（处理完自动上图 / 打开导出目录）

任务成功后插件会自动收尾，不需要额外写代码：

1. **能上图的产物 → 静默加入当前地图**（要素类 / 独立表 / shapefile；自动去重、输入数据不会被重复加载）  
   面板只记一行「已加入地图：xxx」，**不弹窗口**，不打断你干活
2. **不能上图的导出物 → 打开所在文件夹**（.dwg / .csv / .xlsx / .pdf / 图片 …）  
   面板显示「导出位置：<目录>」，方便直接去拿文件
3. 收尾**不会**替你保存工程 —— 需要落盘时自行 Ctrl+S

输出从哪里来：

| 来源              | 说明                                                                                     |
| --------------- | -------------------------------------------------------------------------------------- |
| **GP 工具自动推断**   | 按工具名 + 参数位置推断，覆盖 Buffer / Clip / Dissolve / ExportCAD / Statistics 等常用工具               |
| **Python 脚本声明** | 脚本里打印约定标记：  
`print("@@YGH-ADD " + path)` 加地图  
`print("@@YGH-REVEAL " + folder)` 打开目录 |
| **MCP 显式指定**    | `add_to_map: [...]` / `reveal: [...]`                                                  |

## 安全提示

服务只绑 `127.0.0.1` 且无认证（与 Pro 自带 Python 窗口同一信任模型）。  
它能执行任意 Python / GP 工具，**不要**把端口暴露到局域网。

## License

MIT —— 见 [LICENSE](LICENSE)。作者：YGHS。