agent-profiles/suite-developer/knowledge/data-execution-model.md

数据执行模型

核心原则：数据永不离开本地。 gis-actions 运行在用户自己的机器上。所有数据处理都在用户本地完成，文件不上传到云端。

---

双平台执行架构

Linux（Docker 容器）

用户本地机器
┌─────────────────────────────────────────────────────┐
│                                                      │
│  gis-actions（本地执行器）                            │
│  ┌─────────────────────────────────────────┐         │
│  │                                         │         │
│  │  docker run --rm --tmpfs /dev/shm gis-base + 加密套件脚本
│  ┌────────────────────────────────────────┐
│  │ decrypt_runner.py → AES-256 解密      │
│  │ → /dev/shm（内存文件系统）            │
│  │ → exec() 执行                         │
│  │ → 容器销毁 → /dev/shm 自动清空        │     │         │
│  │  ┌────────────────────────────────┐     │         │
│  │  │  /data/input.shp（只读挂载）    │     │         │
│  │  │  /tmp/output/（写入挂载）       │     │         │
│  │  │  /tmp/scripts/（脚本包，只读）   │     │         │
│  │  └────────────────────────────────┘     │         │
│  └─────────────────────────────────────────┘         │
│                                                      │
│  用户数据文件（原始）  →  ？？不动 →  结果文件       │
│  /home/user/data.shp               /tmp/output/      │
│                                            ↓         │
│                                        拿走使用       │
└─────────────────────────────────────────────────────┘

            ↑ 只拉脚本包，不拉数据
            │
   suites.mercator.cn（套件市场）

什么被上传，什么不

类别	是否上传	说明
用户数据文件（SHP/GeoJSON/TIFF...）	❌ 不上传	始终在用户本地
执行结果	❌ 不上传	留在用户的输出目录
套件脚本包（加密）	✅ 下载到本地	.py.enc AES-256 加密，运行时在容器内解密
套件解密密钥	❌ 不在脚本包中	内置在 gis-base 镜像，用户无法提取
基础镜像	✅ 拉取一次	gis-base 镜像缓存在本地 Docker
任务参数（文件路径、数值）	❌ 不上传	仅在本地传递，不经过网络

为什么这样设计

• 数据安全：敏感 GIS 数据不离开组织网络
• 合规：涉密、保密数据无需担心云端存储合规问题
• 性能：大数据集（GB 级影像/点云）不通过网络传输
• 知识产权：套件脚本包用完即销毁，用户拿到的是结果不是源码

对终端用户的影响

• 需要安装 Docker（一次性）
• 需要安装 gis-actions（一次性）
• 需要能访问 suites.mercator.cn（网络条件）
• 提供本地文件路径，不是上传文件

对套件开发者的影响

• 脚本通过参数接收文件路径，不是文件内容
• 本地测试路径 ≠ 用户路径，脚本要用参数化路径而非硬编码
• 输出必须写入 output_path，由 gis-actions 决定输出目录位置
• 不要假设文件系统结构，用户文件和容器文件系统是隔离的

Playground 在线演示（新增）

agentgis.cn 上的在线 Playground 提供浏览器沙箱体验。

数据差异

场景	数据来源	执行位置
本地 agc run	用户本地文件	用户本地 Docker
在线 Playground	套件包内 demo-data/ 目录	腾迅云隔离容器

对套件开发者的影响

• Playground 可用的套件必须包含 demo-data/ 目录，放入样例数据文件（GeoJSON / SHP / CSV）
• 样例数据需要小而典型，建议 < 5MB
• workflow.yaml 的参数默认值指向 demo-data/ 中的文件路径
• 无 demo-data/ 的套件不会出现在 Playground 中，只能本地执行

---

Windows（本机 subprocess）

用户 Windows 机器
+-------------------------------------------------------+
|                                                        |
|  agc.exe（Windows 版）                                  |
|  +-------------------------------------------+         |
|  |                                            |         |
|  |  读取 workflow.yaml                        |         |
|  |  - runtime: docker -> 报错不兼容           |         |
|  |  - runtime: python3 -> subprocess(agc)     |         |
|  |  - runtime: arcpy   -> subprocess(arcpy)   |         |
|  |                                            |         |
|  |  解密到 tmp -> 执行 -> 清理                |         |
|  +-------------------------------------------+         |
|                                                        |
|  用户数据文件 -> 步骤处理 -> 结果文件                   |
|                                              |         |
|                                          拿走使用       |
+-------------------------------------------------------+

            | 从市场拉脚本包
            |
   suites.mercator.cn（套件市场）

平台选择

场景	推荐平台	执行器
GIS 数据处理	Linux	Docker + gis-base
ArcGIS 符号转换	Windows	subprocess + arcpy
纯 Python 工作流	通用	subprocess + python3
需要容器隔离	Linux	Docker
需要 ArcMap 许可	Windows	arcpy