# MEMORY.md — 套件使用者长期记忆

## 平台入口

- **套件市场:** https://suites.mercator.cn
- **用户交流:** https://discussions.mercator.cn（遇到问题在这里发话题）

## 关键原则

**数据永不离开本地。**
你的文件始终在你的机器上。GIS Actions 在你的机器上处理，不上传到云端。
输入：本地文件路径 | 输出：`/tmp/output/`

## 安装

### Linux

```bash
curl -sLO https://packages.mercator.cn/public/gis-actions/latest.deb
sudo dpkg -i gis-actions_latest.deb
```

要求：Docker Engine 已安装。

### Windows

1. 下载 [latest-windows.zip](https://packages.mercator.cn/public/gis-actions/latest-windows.zip)
2. 解压到 `%LOCALAPPDATA%\\AgentGIS\\gis-actions\\`
3. 将路径加入 `PATH`
4. 验证：`agc --help`

要求：ArcMap 10.8（arcpy 脚本需要）

## 配置 API Key

所有操作前需先配置 API Key（在套件市场个人中心生成）：

```bash
agc config set api-key mk_xxxxxxxxxxxxxxxxxxxx
agc config list                     # 查看所有配置
agc config get api-key              # 查看（脱敏显示）
```

## gis-actions 全部命令

| 命令 | 用途 |
|------|------|
| `agc config` | 管理配置（API Key、市场地址等） |
| `agc run` | 执行套件 |
| `agc search <query>` | 搜索套件 |
| `agc info <suite-id>` | 查看套件详情 |
| `agc logs` | 查看运行历史 |
| `agc cache list / clean` | 管理本地缓存 |
| `agc doctor` | 环境诊断 |
| `agc mcp` | 启动 MCP 服务器（供 AI Agent 集成） |
| `agc self-update` | 自动升级 |

### agc run 用法

```bash
agc run /tmp/output --suite-id <suite-id> --input key=value
agc run /tmp/output --suite-id <suite-id> --input key=value --resume   # 续跑
agc run /tmp/output --suite-id <suite-id> --input key=value --watch    # 实时输出
```

### gis-actions 工作原理

**Linux 版（Docker 容器执行）：**
1. 从套件市场获取脚本包地址
2. 下载加密脚本包到本地（首次下载后自动缓存）
3. 启动 Docker 容器（gis-base 镜像，内置解密密钥 + decrypt_runner）
4. 容器内将加密脚本解密到 /dev/shm（内存）后执行
5. 结果写入工作目录，脚本包和临时数据自动清理

**Windows 版（本机 subprocess 执行）：**
1. 从套件市场获取脚本包地址
2. 下载并解密到临时目录
3. 根据步骤的 runtime 选择执行器：
   - python3 -> agc 内置 Python
   - arcpy -> 调用系统 arcpy（ArcMap Python 2.7）
4. 结果写入工作目录，临时文件自动清理

## 排查问题

```bash
agc doctor        # 一键检查：Docker、镜像、API Key、网络、配置
agc logs --status failed   # 查看失败记录
agc self-update            # 检查并升级到最新版
```

## 常见问题

**Q: 跑任务需要上网吗？**
A: 只有脚本包下载需要网络。数据处理全程在本地。

**Q: 我的文件会被上传吗？**
A: 不会。`agc run` 读取本地路径，在本地 Docker 容器中处理。

**Q: 结果在哪？**
A: 默认在工作目录的 `_step_outputs/` 下。

**Q: 能同时跑多个任务吗？**
A: 可以，打开多个终端各自跑 `agc run`。

**Q: API Key 在哪生成？**
A: 登录套件市场 https://suites.mercator.cn → 个人中心 → API Key 管理 → 创建。

**Q: API Key 会不会过期？**
A: 长期有效。如需吊销，在套件市场个人中心操作。