# GUESGISAgent 0.4.2

Windows x64 地理信息智能体，继承 GeoFusionAgentGS 0.4 系列。

## 启动

解压完整 Windows ZIP 后，双击 `GUESGISAgent.exe`。已内置 CPython 3.12
运行时和 GIS/STAC 依赖，不需要安装 Python。不要单独移动 EXE，
必须保留同目录的 `_internal`。

Windows 需要 Microsoft Edge WebView2 Runtime 和 .NET Framework 4.8。
关闭窗口会收起到托盘；从托盘的“退出”结束程序。
需要随文件夹携带数据时，运行 `Start-Portable.cmd`，数据位于旁边的 `UserData`。
`Install-Shortcut.cmd` 可为当前位置创建桌面快捷方式。
安装版 `GUESGISAgent-0.4.2-Setup.exe` 与便携版使用同一套程序。

## 原功能保留

- GeoJSON、经纬度 CSV、含 PRJ 的 Shapefile ZIP、GeoPackage 导入与拖放。
- 图层选择、显隐、颜色、弹出属性、属性表、统计、GeoJSON 导出。
- 米制缓冲、面裁剪、面内点统计、模拟教学数据。
- GeoAgent / Strands 在线智能体及兼容 Chat Completions 的模型接口。
- ArcGIS MCP 发现、读取、人工审批、执行记录、本地与 ArcGIS 图层交换。
- STAC 目录、影像检索、资产信息和外包框图层，保留原 4 个智能体 STAC 入口。
- Windows 桌面、托盘、单实例、DPAPI 凭据保护、原用户数据目录。
- 隔离的真实模型工具检查、只读 ArcGIS 诊断、诊断导出。
- 签名更新清单、安装器签名校验、安装器构建和云网关源码。

没有把 GeoAgent 或 ArcGIS 上游未接入的工具写成已具备的本地功能。

## 本次修复和改进

1. 无数值字段的面/线图层统计不再报错，仍返回几何统计和米制测量。
2. “测试连接”发送独立文本请求，不注册工具、不传工作区数据；
   原隔离合成数据工具检查保留为“验证工具”和诊断中心选项。
3. 显式任意代码入口继续禁用。字段计算、通用地理处理、删除等高风险操作保留，
   但需在原审批外单独勾选风险确认，并在执行前重检。审批不是代码沙箱。
4. STAC 客户端与依赖纳入冻结包；服务异常不再静默当成空结果。
5. 聊天发送前保存图层快照，并使用后端本轮结果 ID，修复轮询导致的选中丢失。
6. 图层颜色与显隐持久化；移除图层只移动程序内的副本到工作区 `trash`。
7. 可导出执行记录；可请求停止后续模型/工具步骤。已开始的请求或工具需等待返回，
   不回滚已完成结果，也不强制终止 ArcGIS。
8. 新增无需模型的 STAC 面板，可选服务、数据集、时间、范围、云量并查看资产元数据。

## 默认地图

启动默认显示毕节市区域的 Esri World Topographic Map 地形底图。
“返回毕节市”按钮恢复区域视图。联网底图会向 Esri 发送当前瓦片范围，
可用开关关闭；离线或网络故障时本地矢量功能仍可用。
区域视图是查看范围，不是官方行政边界。底图不是 DEM，不能用于坡度计算。
教学片区、道路、观测站为模拟数据，不是实测数据。

## STAC

先在设置中授权“允许查询在线 STAC 影像目录”。默认不自动发送检索请求。

- Planetary Computer：`https://planetarycomputer.microsoft.com/api/stac/v1`
- Earth Search：`https://earth-search.aws.element84.com/v1`
- 默认数据集：`sentinel-2-l2a`。

STAC 页的“检查服务”会列目录，用 2025 年的毕节样区查询 Sentinel-2，
并读取资产元数据。状态有检查时间，不把“已安装依赖”当成“服务在线”。
每次最多返回 10 项，内存保留最近 20 次检索，避免模型上下文和网络请求失控。
数据集输入框允许输入目录中存在但前 10 条列表未显示的集合 ID。
影像范围图层是外包矩形，不是精确影像足迹。
本版不自动下载波段、不显示实际遥感像元，也不把资产元数据可读等同于影像可下载。
带签名的临时 URL 参数不返回给模型。

## 模型与 ArcGIS

在设置中填写服务接口、准确模型 ID 和自己的密钥，确认数据发送授权。
先“测试连接”，再按需“验证工具”。模型调用可能收费，本包不含密钥。
未连接模型时，本地 GIS 和已授权的 STAC 面板仍可独立使用。

ArcGIS 需独立授权的 ArcGIS Pro 3.7+ 及随包候选 MCP 插件。
插件在 `ArcGIS-Plugin`，连接地址默认 `http://127.0.0.1:6520/mcp`。
所有非只读操作都等待审批。通用工具可能运行代码或修改外部文件，请核对参数。
发送本地图层用 Shapefile，字段名有 10 字符限制；导回结果另存新图层。
本次未在真实 ArcGIS 工程或用户付费模型上完成运行验收。

## 数据与升级

为兼容旧版，普通启动继续使用 `%LOCALAPPDATA%\GeoFusionAgent`。
该旧目录名是兼容标识，不表示运行的是旧程序。旧 `GEOFUSION_*` 环境变量、
本地请求头、Cookie 名和单实例锁保留，已有配置与工作区不会因改名失联。
`--profile-dir <目录>` 可指定独立配置目录。
清理旧发行包不应清理此用户数据目录。

图层原始文件不会被分析覆盖。每层最多 50,000 要素、上传最多 25 MB，
ZIP 解压最多 100 MB；自动 UTM 不适用于跨度过大或极区数据。
CSV 默认 WGS84 经度/纬度列，不猜测投影。
统计长度对面图层表示边界总长度，面积为投影测量；跨区域分析需专业投影选择。
会话执行记录保留最近 100 条，审计导出也限于该窗口，不是长期完整审计库。

## 源码和构建

源码包、第三方许可证及插件随 Windows 包提供。开发依赖在 `requirements-dev.txt`，
`requirements-lock.txt` 保留完整 Windows 构建环境锁定版本。

```powershell
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements-lock.txt
.\.venv\Scripts\python.exe -m pytest tests -q
.\.venv\Scripts\python.exe -m PyInstaller --noconfirm GUESGISAgent.spec
.\.venv\Scripts\python.exe windows\Package-Release.py --app dist\GUESGISAgent --output dist\release
```

源码桌面入口：`Start.cmd`。浏览器调试：`python run.py --open`。
源码 `cloud` 与 Windows 包内 `Cloud` 保留团队网关及部署文档，未自动部署任何公网服务。

本包未做 Authenticode 签名，也未配置可信在线更新源。哈希仅用于完整性检查，
不能代替发布者签名。未配置更新信任时不会下载或执行未知安装器。
完整验收结果见随包 `Verification`，功能边界见 `CAPABILITIES.md`。
许可证与上游版权信息见 `LICENSE`、`NOTICE.md`。