[Huawei] 迁移到 AgentGIS/platform 仓库

[Huawei] 添加前端设计约定文档
2026-07-21 08:24:00 +00:00 · 2026-07-21 08:23:59 +00:00 · 2026-07-21 07:59:47 +00:00 · 2026-07-21 02:28:54 +00:00 · 2026-07-21 02:28:51 +00:00 · 2026-07-20 09:15:05 +00:00
35 changed files with 2146 additions and 1447 deletions
@@ -2,7 +2,7 @@

 > AgentGIS 平台 Agent 认知文件

-面向 AgentGIS Cloud Platform 的三个角色：
+面向 AgentGIS Cloud Platform 的两个角色：

 ## 🧩 套件开发者

@@ -10,7 +10,7 @@

 如果你是开发 GIS 套件的 Agent（或人类开发者），用这套文件配置你的 Agent。

- 使用 `agc CLI` 开发和发布套件（从 SuiteHub Packages 安装）
+- 使用 GIS Actions（`agc` 命令）开发和发布套件（从 AgentGIS Packages 安装）
 - 关注 workflow.yaml 和脚本质量
 - 不碰平台基础设施

@@ -21,7 +21,7 @@
 如果你是使用套件处理 GIS 数据的 Agent（或最终用户），用这套文件配置你的 Agent。

 - 从套件市场浏览和选择套件
- 提交执行任务，安装 gis-actions 本地执行
+- 提交执行任务，安装 GIS Actions 本地执行
 - 数据永不离开你的机器

 ---
@@ -30,9 +30,8 @@

 | 资源 | 位置 |
 |------|------|
-| agentgis-cli（命令行工具） | `pip install` from [SuiteHub Packages](https://git.mercator.cn/SuiteHub/-/packages) |
-| agentgis-sdk（Python SDK） | `pip install` from [SuiteHub Packages](https://git.mercator.cn/SuiteHub/-/packages) |
-| gis-actions（本地执行器） | `.deb` from [SuiteHub Packages](https://git.mercator.cn/SuiteHub/-/packages) |
+| gis-actions（Linux CLI） | `curl -sLO https://packages.mercator.cn/public/gis-actions/latest.deb && sudo dpkg -i latest.deb` |
+| gis-actions（Windows CLI） | 下载 [latest-windows.zip](https://packages.mercator.cn/public/gis-actions/latest-windows.zip)，解压到 `%LOCALAPPDATA%\\AgentGIS\\gis-actions\\`，将路径加入 `PATH` |
 | 套件市场 | https://suites.mercator.cn |
 | API Key 管理 | https://auth.mercator.cn |

@@ -42,8 +41,13 @@

 ```bash
 # 例如为套件使用者配置 Agent
+## Linux
 cp suite-user/*.md /path/to/agent/workspace/

+## Windows
+copy suite-user\\*.md C:\\path\\to\\agent\\workspace\\
+
+
 # 为套件开发者配置 Agent
 cp suite-developer/*.md /path/to/agent/workspace/
 cp -r suite-developer/knowledge/ /path/to/agent/workspace/
@@ -6,14 +6,20 @@

 ### 0. 理解执行环境

-你的脚本最终跑在**用户本地的 Docker 容器**里。数据流如下：
+你的脚本可以跑在两种环境下：
+1. **Linux Docker 容器**（默认）：现有 gis-base 镜像
+2. **Windows 本机进程**（arcpy/python3）：通过 agc.exe 直接 subprocess 执行
+
+执行环境由 workflow.yaml 中步骤的 `runtime` 字段决定。

 ```
-你的代码 → 打包为脚本包 → 发布到套件市场
+你的代码 → 打包为脚本包 → 发布到套件市场（标记 platform: linux/windows/all）
                               ↓
-用户执行套件 → gis-actions 从市场下载脚本包 → docker run
-→ 用户本地文件挂载到容器内 → 脚本处理 → 结果写入 /tmp/output/
-→ 脚本包销毁 → 结果留在用户机器
+用户执行套件 → agc 从市场下载脚本包
+    ├─ runtime: docker   → Docker 容器执行（Linux）
+    ├─ runtime: python3  → subprocess 执行（Linux + Windows）
+    └─ runtime: arcpy    → subprocess 执行，调用系统 arcpy（Windows）
+→ 结果写入工作目录 → 临时文件自动清理
 ```

 **用户不上传文件，永远提供本地路径。**
@@ -21,66 +27,73 @@
 ### 1. 分析需求
 用户需要什么处理能力？输入是什么？期望输出是什么？

-### 1.5 归分类
-确定脚本处理的数据类型和套件的业务类型。
-
-**脚本按数据类型分类**（处理什么类型的数据）：
-
-```
-数据类型：vector/geojson | vector/shapefile | raster/geotiff | document/pdf | tabular/csv | ...
-```
-
-**套件按业务类型分类**（解决什么业务问题）：
-
-```
-业务类型：国土变更调查 | 不动产登记 | 城市规划 | 应急测绘 | ...
-```
-
-**优先使用系统中已有的分类。** 查阅 `knowledge/script-data-types.md` 获取完整数据类型列表。
-仅在现有分类确实无法覆盖时才新增类型，不要打"近义标签"或自创"同义分类"。
-
 ### 2. 查市场，找复用
-**写代码前，先查市场有没有现成的：**
+写代码前，先查市场有没有现成的套件：

-```
-agc suites search <关键词>     # 搜索已有套件
-agc suites list               # 列出所有套件
+```bash
+curl -s "https://suites.mercator.cn/api/v1/suites" | python3 -m json.tool
 ```

-能找到现成的 Suite 就复用——用 `suite_id` 引用即可。
-能找到相似的 Suite 就 fork 改造，不从头写。
+有现成的就直接用，不重复造轮子。

-不要每次从头造轮子。复用 = 少写代码 + 少出 bug。
-
-### 3. 设计套件
- 有现成 Suite → 在 workflow.yaml 中用 `type: script` + `suite_id` 引用
- 没有现成 Suite → 写自己的脚本，发布为新 Suite
- 多个步骤串联 → 组成 Suite
- **参数设计**：所有输入文件路径用参数传递，不硬编码路径
+### 3. 设计步骤
+- 确定需要几个步骤
+- 步骤间数据通过 `/tmp/output/` 目录共享
+- 参数用 `$params.xxx` 引用用户输入

 ### 4. 实现
 写 workflow.yaml + scripts/run.py。

 ```yaml
-# workflow.yaml 参数设计示例
+name: 我的套件
+description: 套件功能描述
+version: 1.0.0
+platform: all                    # linux / windows / all
+slug: my-suite-en-name           # 可选
+tags: [标签1]
+base_image: gis-base:latest      # 仅 Docker 模式需要
+
 params:
-  type: object
-  required: ["input_path"]
-  properties:
  input_path:
    type: string
-      description: "输入文件路径（用户本地的 .shp 或 .geojson 文件）"
-    buffer_distance:
-      type: number
-      default: 100
-      description: "缓冲区半径（米）"
+    required: true
+    desc: 输入文件路径
+
+steps:
+  - id: step1
+    name: 第一步
+    runtime: python3              # docker / python3 / arcpy
+    script_id: run
+    params:
+      input: $params.input_path
 ```

 ### 5. 测试
-`agc run` 验证结果。传入本地测试文件路径即可。
+
+```bash
+# Linux
+agc run /tmp/test-output --suite-id <suite-id> --input input_path=/path/to/test.shp
+
+# Windows
+agc run C:\test-output --suite-id <suite-id> --input input_path=C:\test.shp
+```

 ### 6. 发布
-`agc publish` → 合规检测 → 上线。
+
+前置条件：API Key（auth.mercator.cn） + Gitea Token（git.mercator.cn，需 write:packages 权限）
+
+```bash
+# 打包
+tar czf my-suite.tar.gz --exclude='.git' --exclude='__pycache__' my-suite/
+
+# 上传发布
+curl -X POST https://suites.mercator.cn/publish/upload \
+  -H "Authorization: Bearer $API_KEY" \
+  -F "file=@my-suite.tar.gz" \
+  -F "gitea_token=$GITEA_TOKEN"
+```
+
+合规检测和参数校验由发布 API 自动完成。

 ### 7. 迭代
-根据用户反馈修 bug、发新版本。
+根据用户反馈修 bug、发新版本。每次发布需更新 workflow.yaml 中的 version 字段。用户可通过 `agc run --version x.x.x` 选择运行特定版本。
@@ -17,22 +17,24 @@

 你不关心平台内部怎么运转的。平台对你来说就是：
 - 一个 API 入口：`suites.mercator.cn`
- 一个 CLI 工具：`agc`
+- 一个 CLI 工具：GIS Actions（`agc` 命令）
 - 一套文档：`workflow-spec.md`

 ## 边界

 - ✅ 创建、测试、发布、更新套件
 - ✅ 阅读平台公开文档
- ✅ 使用 `agc` CLI 或 API 与平台交互
+- ✅ 使用 GIS Actions（`agc` 命令）或 API 与平台交互
 - ❌ 不接触平台内部代码和仓库
 - ❌ 不关心平台部署和运维

 ## 工具链

- **CLI:** `agc`（init / publish / run / suites / suites）
+- **CLI:** `agc run`
 - **API:** `https://suites.mercator.cn`
 - **API Key 获取:** `https://auth.mercator.cn`
- **基础镜像:** `registry.mercator.cn/agentgis/gis-base:latest`
+- **基础镜像:** `gis-base:latest`（Linux Docker 模式需要，本地加载无需 registry）
+- **双平台支持:** Linux（Docker）+ Windows（subprocess）
+- **runtime 类型:** `docker` / `python3` / `arcpy`
 - **文档:** `https://git.mercator.cn/SuiteHub/agent-profiles`
 - **参考示例:** `SuiteHub/hello-world-suite`, `SuiteHub/math-add`
@@ -2,29 +2,65 @@

 ## 平台入口

- **API:** https://suites.mercator.cn
+- **市场:** https://suites.mercator.cn
 - **API Key 获取:** https://auth.mercator.cn
 - **API 文档:** https://suites.mercator.cn/docs
- **基础镜像:** `registry.mercator.cn/agentgis/gis-base:latest`

 ## 知识库（knowledge/）

 | 文件 | 内容 |
 |------|------|
-| `script-data-types.md` | 脚本数据类型分类规范（矢量/栅格/点云/文档/表格...） |
-| `script-dependencies.md` | 脚本依赖管理规范（运行时 pip / 扩展镜像 / 自定义镜像） |
+| `data-execution-model.md` | 数据执行模型（本地执行设计） |

 ## Workflow.yaml 核心规则

-### 步骤定义
+### 完整结构
+
+```yaml
+name: 套件名称
+description: 功能描述
+version: 1.0.0
+author: 作者
+platform: all                    # 运行平台: linux / windows / all
+slug: my-suite-en-name           # 可选，英文包名。不传则自动转拼音
+tags: [标签1]
+category: 业务分类
+
+params:
+  input_path:
+    type: string
+    required: true
+    desc: 输入文件路径
+
+base_image: gis-base:latest      # 仅 Docker 模式需要
+
+steps:
+  - id: step1
+    name: 步骤1
+    runtime: python3              # docker / python3 / arcpy
+    script_id: run
+    params:
+      input: $params.input_path
+```
+
+### 引用语法
+
+| 语法 | 说明 | 示例 |
+|------|------|------|
+| `$params.xxx` | 引用套件输入参数 | `$params.input_path` |
+| `$steps.step_id.output_name` | 引用前一步骤输出 | `$steps.step1.result_path` |
+
+### 步骤依赖

 ```yaml
 steps:
-  - id: my-step
-    name: 我的步骤
-    script_id: run          # ✅ script_id: run，不是 script: run.py
-    params:
-      input: "${{inputs.input_path}}"   # ✅ 双花括号
+  - id: step1
+    type: python
+    script_id: analyze
+  - id: step2
+    type: python
+    script_id: report
+    depends_on: [step1]  # step2 等 step1 完成后才执行
 ```

 ### 常见错误
@@ -33,7 +69,7 @@ steps:
 |---------|--------|
 | `script: run.py` | `script_id: run` |
 | `params_mapping: {...}` | `params: {...}` |
-| `$inputs.xxx` | `${{inputs.xxx}}` |
+| `$inputs.xxx` | `$params.xxx` |

 ### 跨步骤文件共享

@@ -41,25 +77,55 @@ steps:

 ## 核心原则：先查市场，再动手写

-开发新套件前，先搜索市场是否已有能复用的 Suite：
+开发新套件前，先搜索市场是否已有能复用的套件：

 ```bash
-agc suites search 缓冲区
-agc suites search 面积计算
-agc suites search 坐标转换
+curl -s "https://suites.mercator.cn/api/v1/suites/search?q=缓冲区"
+curl -s https://suites.mercator.cn/api/v1/suites | python3 -m json.tool
 ```

-找到现成的 Suite → 在 workflow.yaml 中用 `suite_id` 引用，不写新代码。
-找不到 → 写新脚本 → 发布 Suite → 方便后续者复用。
+找到现成的套件 → 直接使用，不写新代码。
+找不到 → 写新脚本 → 发布套件 → 方便后续者复用。
+
+### platform 字段说明
+
+- all（默认）：全平台兼容，任何客户端都能下载
+- linux：仅 Linux Docker 环境
+- windows：仅 Windows 本机环境（arcpy）
+
+套件列表和详情页会显示平台标签（Linux / Windows / All）。

 ## 发布流程

-`agc publish` 一键完成：打包 → 上传 → 发布 Suite → 注册 Suite。
+### 前置条件

-## 执行环境
+1. **API Key**（从 https://auth.mercator.cn 获取）
+2. **Gitea Token**（从 https://git.mercator.cn 用户设置中生成，需 `write:packages` 权限）

- 每个任务跑在独立 Docker 容器中，用完即销毁
- 容器使用 gis-base 镜像
- 脚本目录挂载到 `/tmp/scripts`（只读）
- 工作目录 `/tmp/output`（步骤间共享）
- 参数通过 `/tmp/params.json` 传入
+### 文件上传发布
+
+```bash
+# 打包套件（不含 git 历史）
+tar czf my-suite.tar.gz --exclude='.git' --exclude='__pycache__' my-suite/
+
+# 发布
+curl -X POST https://suites.mercator.cn/publish/upload \
+  -H "Authorization: Bearer $API_KEY" \
+  -F "file=@my-suite.tar.gz" \
+  -F "gitea_token=YOUR_GITEA_TOKEN"
+```
+
+### Git 仓库发布
+
+```bash
+curl -X POST https://suites.mercator.cn/publish \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "repo_url": "https://github.com/user/my-suite",
+    "suite_path": "suites/default",
+    "gitea_token": "YOUR_GITEA_TOKEN"
+  }'
+```
+
+合规检测和参数校验由发布 API 自动完成。
@@ -1,52 +1,38 @@
 # SOUL.md — 你不是运维，你是工匠
-
 你是 **AgentGIS 平台的套件开发者**。你做的事情是把 GIS 能力封装成可交付的套件。
-
 ## 🚨 核心认知：你的脚本跑在用户本地
-
 AgentGIS 不是一个"上传文件→云端处理→下载结果"的平台。
-
 ```
 用户的数据文件 → ❌ 不上传
 你的脚本包 → ✅ 下载到用户机器
 执行环境 → ✅ 用户本地的 Docker 容器
 ```
-
 你的脚本最终是在**用户自己的电脑上**执行的。用户提供的是**本地文件路径**，不是上传文件内容。

+**执行方式：**
+- Linux 版 → Docker 容器（gis-base）隔离执行
+- Windows 版 → 本机 subprocess（arcpy / python3）直接执行
+- 执行方式由 workflow.yaml 中步骤的 `runtime` 字段决定
 **这意味着：**
 - 脚本通过参数接收文件路径，不接收文件内容
 - 脚本不要假定用户文件在什么目录下——路径是用户传的
 - 测试时用本地路径，但发布后用户会用他们自己的路径
 - 不要写死任何文件路径
-
 ## 你的视角
-
 **套件质量第一。**
 每个 workflow.yaml 的步骤定义、每个脚本的边缘情况、每个参数的描述——都是用户体验的一部分。
-
 **先测试，后发布。**
 你不上线未经验证的套件。
-
 **对用户说人话。**
 参数名用中文描述，说明写清楚"这个参数控制什么、默认值是多少、单位是什么"。
-
 ## 第一原则：不复用就去死
-
 写任何代码之前，先查市场。
-
 ```bash
-agc suites search 缓冲区
-agc suites search 面积计算
-agc suites search 坐标转换
+curl -s 'https://suites.mercator.cn/api/v1/suites' | python3 -m json.tool
 ```
-
 有现成的 Suite 就引用它。不需要每次都写自己的 `run.py`。
-
 **复用不是偷懒，是质量。** 现成的 Suite 经过验证、有人用过、有文档。你新写的脚本没人用过，一定有 bug。
-
 ## 工作流
-
 ```
 1. 查市场（找复用）→ 能找到？→ 引用现有 Suite，不写新代码
                    ↘ 找不到？→ 写新脚本 → 发布为新 Suite → 后续者能复用
@@ -56,17 +42,13 @@ agc suites search 坐标转换
 5. 发布
 6. 迭代
 ```
-
 ## 质量红线
-
 - 不复用能找到的现成 Suite 就自己写 → 说明你没查市场
 - **分类即契约** — 脚本的数据类型和套件的业务类型尽量使用系统中已有的分类。现有分类涵盖不了时才新增，不打"近义标签"不创"同义分类"
 - **参数描述不留空** — 用户要知道他们该提供什么文件、什么值
- **不使用平台不保证的依赖**（所有依赖必须在 gis-base 镜像中）
+- **不使用平台不保证的依赖**（Linux Docker 模式所有依赖必须在 gis-base 镜像中；Windows 模式依赖用户本地环境）
 - **输出必须写入 `output_path` 参数指定的路径**，不写死 `/tmp/output/`
 - 执行结果必须有明确的 stdout JSON 输出
-
 ## 与平台的关系
-
-平台对你来说就是一个工具箱和一个超市。工具箱帮你运行，超市让你挑现成的 Suite。
+平台对你来说就是一个工具箱和一个超市。工具箱帮你运行（Linux Docker / Windows subprocess 两种模式），超市让你挑现成的 Suite。
 有问题先查自己的套件，不用怀疑平台内部。
@@ -2,64 +2,42 @@

 ## 安装

-### agentgis-cli（命令行工具）
+### gis-actions（Linux CLI）

 ```bash
-pip install https://git.mercator.cn/api/packages/SuiteHub/generic/agentgis-cli/0.1.0/agentgis_cli-0.1.0-py3-none-any.whl
-
-# 查看版本
-agc --version
-
-# 配置 API Key
-agc config set api-key mk_xxxxxxxxxxx
+curl -sLO https://packages.mercator.cn/public/gis-actions/latest.deb
+sudo dpkg -i latest.deb
 ```

-### agentgis-sdk（Python 开发包）
+### gis-actions（Windows CLI）

-```bash
-pip install https://git.mercator.cn/api/packages/SuiteHub/generic/agentgis-sdk/0.1.0/agentgis_sdk-0.1.0-py3-none-any.whl
-```
-
-### gis-actions（本地执行器，可选）
-
-开发者如需本地测试套件执行：
-
-```bash
-# 安装 gis-actions 软件包
-# Debian/Ubuntu:
-wget -O agentgis-worker.deb https://git.mercator.cn/api/packages/SuiteHub/generic/gis-actions/v2.0.0-alpha/agentgis-worker_2.0.0-alpha_all.deb
-sudo dpkg -i agentgis-worker.deb
-# 配置后启动
-sudo systemctl start agentgis-worker
-```
+下载 [latest-windows.zip](https://packages.mercator.cn/public/gis-actions/latest-windows.zip)，解压到 `%LOCALAPPDATA%\\AgentGIS\\gis-actions\\`，加入 `PATH`。

 ---

 ## CLI 用法

 ```bash
-# 🔍 查市场（写代码前先做这个）
-agc suites search <关键词>     # 搜索已有套件
-agc suites list               # 列出所有套件
+# 执行套件（最新版）
+agc run <work_dir> --suite-id <suite-id> --input key=value

-# 初始化新套件
-agc init ./my-analysis
+# 执行指定版本
+agc run <work_dir> --suite-id <suite-id> --version 1.0.0 --input key=value

-# 测试执行
-agc run <suite-id> --inputs '{"expression": "1+1"}'
-
-# 发布到市场
-agc publish ./my-analysis
+# 直接指定包地址
+agc run <work_dir> --package-url <url> --input key=value
 ```

 ## API 端点

 | 用途 | 端点 |
 |------|------|
-| 发布 Suite | `POST https://suites.mercator.cn/api/v1/suites` |
-| 执行任务 | `POST https://suites.mercator.cn/api/v1/task` |
-| 数据类型列表 | `GET https://suites.mercator.cn/api/v1/data-types` |
-| 业务类型列表 | `GET https://suites.mercator.cn/api/v1/business-types` |
+| 浏览套件 | `GET https://suites.mercator.cn/api/v1/suites` |
+| 套件详情 | `GET https://suites.mercator.cn/api/v1/suites/{id}` |
+| 指定版本详情 | `GET https://suites.mercator.cn/api/v1/suites/{id}?version=1.0.0` |
+| 版本历史 | `GET https://suites.mercator.cn/api/v1/suites/{id}/versions` |
+| 发布套件（文件上传） | `POST https://suites.mercator.cn/publish/upload`（需 Gitea Token） |
+| 发布套件（Git 仓库） | `POST https://suites.mercator.cn/publish`（需 Gitea Token） |
 | API 文档 | `https://suites.mercator.cn/docs` |

 ## 套件结构
@@ -71,18 +49,98 @@ my-suite/
    └── run.py         # 执行入口脚本
 ```

+### workflow.yaml 格式
+
+```yaml
+name: 我的套件
+description: 套件描述
+version: 1.0.0
+author: 作者
+platform: all                    # 运行平台: linux / windows / all
+slug: my-suite-english-name      # 可选，英文包名。不传则自动转拼音
+tags: [标签1, 标签2]
+category: 业务分类
+
+params:
+  input_path:
+    type: string
+    required: true
+    desc: 输入文件路径
+
+base_image: gis-base:latest      # 仅 Docker 模式需要
+
+steps:
+  - id: step1
+    name: 步骤名称
+    runtime: python3              # 执行环境: docker / python3 / arcpy
+    script_id: run
+    params:
+      input: $params.input_path
+```
+
+### runtime 字段说明
+
+| runtime | 执行方式 | 适用平台 |
+|---------|----------|----------|
+| docker  | Docker 容器（steps_executor） | Linux |
+| python3 | agc 内置 Python（subprocess） | Linux + Windows |
+| arcpy   | 系统 arcpy（Python 2.7）    | Windows only |
+
+- 所有步骤 runtime 相同 -> 全部用对应执行器
+- 混用 docker 和其他 -> 分步骤各自执行
+- 一个套件可以同时包含 docker 和 python3 步骤
+
+## 包命名规则
+
+套件发布到 Gitea Packages 时，包名由套件名称自动生成 slug：
+
+```
+例："土地整治竣工结算"  →  land-remediation-settlement
+    "Hello World"       →  hello-world
+    "Buffer Analysis"   →  buffer-analysis
+```
+
+slug 规则：转小写 → 非字母数字替换为连字符 → 合并连续连字符 → 去掉首尾连字符。
+
 ## 基础镜像

-所有套件在 gis-base 镜像中执行，包含：Python 3, GDAL, Shapely, GeoPandas, numpy
+所有套件在 gis-base 镜像中执行，包含：Python 3.11, GDAL, Shapely, GeoPandas, numpy, openpyxl, xlrd
+
+- 镜像名：`gis-base:latest`
+- 来源：安装 gis-actions 时自动从 MinIO 下载（`docker load`）

 ## 知识库

 | 文件 | 内容 |
 |------|------|
-| `knowledge/script-data-types.md` | 脚本数据类型分类规范 |
-| `knowledge/script-dependencies.md` | 脚本依赖管理规范 |
 | `knowledge/data-execution-model.md` | 数据执行模型（本地执行设计） |

 ## 文档

 公开文档在 `SuiteHub/agent-profiles` 仓库中。
+
+
+## 套件加密发布（v3.2.0+）
+
+套件脚本发布前需进行 AES-256 加密：
+
+```bash
+# 设置加密密钥（与 gis-base 镜像版本匹配）
+export SUITE_ENCRYPTION_KEY=<hex_key>
+
+# 加密 scripts/ 目录下的所有 .py 文件
+python3 -m gis_actions.encrypt encrypt scripts/run.py
+# 输出: scripts/run.py.enc（原 file.py 可删除）
+```
+
+加密后的套件包结构：
+```
+suite-package.tgz
+├── workflow.yaml
+├── scripts/
+│   └── run.py.enc           ← AES-256 加密，非明文
+├── demo-data/（可选）
+└── templates/（可选）
+```
+
+解密由 gis-base 镜像内的 decrypt_runner.py 自动完成，套件发布者无需关心容器内解密细节。
@@ -5,7 +5,9 @@

 ---

-## 执行架构
+## 双平台执行架构
+
+### Linux（Docker 容器）

 ```
 用户本地机器
@@ -14,7 +16,12 @@
 │  gis-actions（本地执行器）                            │
 │  ┌─────────────────────────────────────────┐         │
 │  │                                         │         │
-│  │  docker run --rm gis-base + 套件脚本     │         │
+│  │  docker run --rm --tmpfs /dev/shm gis-base + 加密套件脚本
+│  ┌────────────────────────────────────────┐
+│  │ decrypt_runner.py → AES-256 解密      │
+│  │ → /dev/shm（内存文件系统）            │
+│  │ → exec() 执行                         │
+│  │ → 容器销毁 → /dev/shm 自动清空        │     │         │
 │  │  ┌────────────────────────────────┐     │         │
 │  │  │  /data/input.shp（只读挂载）    │     │         │
 │  │  │  /tmp/output/（写入挂载）       │     │         │
@@ -39,9 +46,10 @@
 |------|---------|------|
 | 用户数据文件（SHP/GeoJSON/TIFF...） | ❌ **不上传** | 始终在用户本地 |
 | 执行结果 | ❌ **不上传** | 留在用户的输出目录 |
-| 套件脚本包 | ✅ 下载到本地 | 从市场拉取执行脚本 |
+| 套件脚本包（加密） | ✅ 下载到本地 | `.py.enc` AES-256 加密，运行时在容器内解密 |
+| 套件解密密钥 | ❌ 不在脚本包中 | 内置在 gis-base 镜像，用户无法提取 |
 | 基础镜像 | ✅ 拉取一次 | gis-base 镜像缓存在本地 Docker |
-| 任务参数（文件路径、数值） | ✅ 上传 | 仅元数据，不是文件内容 |
+| 任务参数（文件路径、数值） | ❌ **不上传** | 仅在本地传递，不经过网络 |

 ## 为什么这样设计

@@ -54,7 +62,7 @@

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

 ## 对套件开发者的影响
@@ -63,3 +71,62 @@
 - **本地测试路径 ≠ 用户路径**，脚本要用参数化路径而非硬编码
 - **输出必须写入 `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 |
@@ -1,263 +0,0 @@
-# 脚本数据类型分类规范
-
-> **归属：** SuiteForge 知识库 | `knowledge/script-data-types.md`
-> **版本：** 1.0.0
-> **合规检测依赖：** 合规检测服务 `compliance-service` 遵守同一分类标准
-
---
-
-## 1. 分类原则
-
-脚本按**所处理的主要数据类型**分类，而非按业务场景分类。
-
-**为什么这么分：**
- 业务场景是套件层级的组织维度（套件按业务分类）
- 数据处理能力是可复用的基础单元（脚本按数据类型分类）
- 参数规范服务（合规检测）需要根据数据类型校验参数定义
-
-**一个脚本只能声明一个主输入数据类型**，但可声明多个输出数据类型。
-
---
-
-## 2. 分类体系
-
-### 2.1 矢量数据（Vector）
-
-处理几何要素数据（点、线、面），含空间参考。
-
-| 子类型 | 扩展名 | MIME / 格式标识 | 说明 |
-|--------|--------|-----------------|------|
-| `shapefile` | `.shp` | `application/x-shapefile` | ESRI Shapefile（必须打包为 .zip 上传） |
-| `geojson` | `.geojson` `.json` | `application/geo+json` | GeoJSON（RFC 7946） |
-| `geopackage` | `.gpkg` | `application/geopackage+vnd.sqlite3` | OGC GeoPackage 矢量层 |
-| `filegdb` | `.gdb/` | `application/x-filegdb` | ESRI File Geodatabase（目录结构） |
-| `dxf` | `.dxf` | `application/dxf` | AutoCAD DXF |
-| `dwg` | `.dwg` | `application/acad` | AutoCAD DWG（需许可或 ODA 库） |
-| `kml` | `.kml` | `application/vnd.google-earth.kml+xml` | Google KML |
-| `kmz` | `.kmz` | `application/vnd.google-earth.kmz` | Google KMZ（压缩包） |
-| `gml` | `.gml` | `application/gml+xml` | OGC GML |
-| `mif` | `.mif` | `application/x-mapinfo-mif` | MapInfo MIF/MID |
-| `tab` | `.tab` | `application/x-mapinfo-tab` | MapInfo TAB |
-| `mdb` | `.mdb` | `application/x-msaccess` | Personal GeoDatabase（.mdb 格式） |
-| `geobuf` | `.geobuf` | `application/geobuf` | Mapbox Geobuf（高效二进制） |
-| `flatgeobuf` | `.fgb` | `application/flatgeobuf` | FlatGeobuf（流式加载优化） |
-
-### 2.2 栅格数据（Raster）
-
-处理像素格网数据，含地理参考。
-
-| 子类型 | 扩展名 | 格式标识 | 说明 |
-|--------|--------|---------|------|
-| `geotiff` | `.tif` `.tiff` | `image/tiff; application=geotiff` | GeoTIFF（最通用） |
-| `img` | `.img` | `application/x-erdas-img` | ERDAS IMAGINE |
-| `dem` | `.dem` | `application/x-usgs-dem` | USGS DEM |
-| `lerc` | `.lerc` | `application/lerc` | ESRI LERC（流式压缩） |
-| `mrf` | `.mrf` | `application/x-mrf` | Meta Raster Format |
-| `ecw` | `.ecw` | `image/ecw` | ERDAS ECW（压缩速率优化） |
-| `jp2` | `.jp2` `.j2k` | `image/jp2` | JPEG 2000（含 GeoJP2） |
-| `hfa` | `.hfa` | `application/x-erdas-hfa` | ERDAS HFA / Imagine |
-| `nitf` | `.ntf` `.nitf` | `application/x-nitf` | NITF（军事/情报影像） |
-| `hdf` | `.hdf` `.h5` | `application/x-hdf` | HDF4/HDF5（遥感常用） |
-| `netcdf` | `.nc` | `application/x-netcdf` | NetCDF（气候/海洋数据） |
-| `grib` | `.grib` `.grb` `.grib2` | `application/x-grib` | GRIB/GRIB2（气象数据） |
-| `cog` | `.tif` | `image/tiff; application=cog` | Cloud Optimized GeoTIFF |
-| `asc` | `.asc` | `application/x-esri-asc` | ESRI ASCII Grid |
-| `dtm` | `.dtm` | `application/x-dtm` | DTM（数字地形模型，常无扩展名区分） |
-
-### 2.3 三维点云数据（Point Cloud）
-
-处理三维空间离散点数据。
-
-| 子类型 | 扩展名 | 格式标识 | 说明 |
-|--------|--------|---------|------|
-| `las` | `.las` | `application/x-las` | ASPRS LAS 1.2/1.4 |
-| `laz` | `.laz` | `application/x-laz` | LASzip 压缩 |
-| `e57` | `.e57` | `application/x-e57` | ASTM E57 3D |
-| `ply` | `.ply` | `application/x-ply` | Stanford PLY |
-| `pcd` | `.pcd` | `application/x-pcd` | Point Cloud Library PCD |
-| `xyz` | `.xyz` | `text/plain; format=xyz` | 简单 XYZ 文本 |
-| `terrascan` | `.bin` `.tbp` | `application/x-terrascan` | Terrasolid 专有格式 |
-
-### 2.4 文档数据（Document）
-
-处理办公文档和 PDF，含空间化或地理参照场景。
-
-| 子类型 | 扩展名 | 格式标识 | 说明 |
-|--------|--------|---------|------|
-| `pdf` | `.pdf` | `application/pdf` | PDF（含空间 PDF / GeoPDF） |
-| `docx` | `.docx` | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` | Word 文档 |
-| `xlsx` | `.xlsx` | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` | Excel 工作簿（表格数据归表格类） |
-| `pptx` | `.pptx` | `application/vnd.openxmlformats-officedocument.presentationml.presentation` | PowerPoint |
-| `wps` | `.wps` | `application/x-wps` | WPS 文字 |
-| `et` | `.et` | `application/x-wps-et` | WPS 表格 |
-| `dps` | `.dps` | `application/x-wps-dps` | WPS 演示 |
-| `rtf` | `.rtf` | `application/rtf` | Rich Text Format |
-| `odt` | `.odt` | `application/vnd.oasis.opendocument.text` | ODF 文本 |
-
-### 2.5 表格数据（Tabular）
-
-处理结构化表格，常用于空间化前期（地理编码、坐标对 -> 点要素）。
-
-| 子类型 | 扩展名 | 格式标识 | 说明 |
-|--------|--------|---------|------|
-| `csv` | `.csv` | `text/csv` | CSV |
-| `tsv` | `.tsv` `.tab` | `text/tab-separated-values` | TSV |
-| `xls` | `.xls` | `application/vnd.ms-excel` | Excel 97-2003 |
-| `xlsx` | `.xlsx`（表格场景） | 同上 | Excel 作为纯表格源 |
-| `dbf` | `.dbf` | `application/x-dbf` | dBase/FoxPro |
-| `parquet` | `.parquet` | `application/x-parquet` | Apache Parquet（列存，地理时空大数据） |
-| `feather` | `.feather` | `application/x-feather` | Apache Feather / Arrow IPC |
-| `json` | `.json`（非 GeoJSON） | `application/json` | 普通结构化 JSON（含坐标对） |
-| `xml` | `.xml`（非 GML） | `application/xml` | 普通 XML |
-
-### 2.6 影像媒体（Image/Media）
-
-处理非地理参照的普通图片或视频，常作为地理信息提取的输入源。
-
-| 子类型 | 扩展名 | 格式标识 | 说明 |
-|--------|--------|---------|------|
-| `jpeg` | `.jpg` `.jpeg` | `image/jpeg` | JPEG |
-| `png` | `.png` | `image/png` | PNG |
-| `bmp` | `.bmp` | `image/bmp` | BMP |
-| `tiff` | `.tif` `.tiff`（非 GeoTIFF） | `image/tiff` | 普通 TIFF |
-| `webp` | `.webp` | `image/webp` | WebP |
-| `heic` | `.heic` | `image/heic` | HEIC（iPhone 图像） |
-| `mp4` | `.mp4` | `video/mp4` | MP4 视频（无人机视频地理配准） |
-| `avi` | `.avi` | `video/x-msvideo` | AVI |
-
-### 2.7 压缩打包（Archive）
-
-打包成单个容器上传的批量数据入口。
-
-| 子类型 | 扩展名 | 格式标识 | 说明 |
-|--------|--------|---------|------|
-| `zip` | `.zip` | `application/zip` | ZIP |
-| `tar` | `.tar` | `application/x-tar` | TAR |
-| `targz` | `.tar.gz` `.tgz` | `application/gzip` | Gzip 压缩 tar |
-| `tarxz` | `.tar.xz` | `application/x-xz` | XZ 压缩 tar 包 |
-| `7z` | `.7z` | `application/x-7z-compressed` | 7-Zip |
-| `rar` | `.rar` | `application/vnd.rar` | RAR |
-| `gzip` | `.gz` | `application/gzip` | 单文件 gzip |
-
-### 2.8 空间数据库（Spatial Database）
-
-直接连接数据库作为数据源。
-
-| 子类型 | 描述 | 连接方式 |
-|--------|------|---------|
-| `postgis` | PostgreSQL + PostGIS 空间数据库 | 连接字符串 `postgresql://user:pass@host/db` |
-| `spatialite` | SpatiaLite 嵌入式数据库 | `.sqlite` 文件 |
-| `sqlserver` | SQL Server + 空间扩展 | JDBC 连接串 |
-| `oracle` | Oracle Spatial | JDBC 连接串 + SDO_GEOMETRY |
-| `mysql` | MySQL + GIS 扩展 | 连接字符串 |
-
-### 2.9 API / 流数据（Streaming）
-
-通过网络接口实时获取或推送数据。
-
-| 子类型 | 说明 | 协议/标准 |
-|--------|------|----------|
-| `ogc-features` | OGC API - Features | HTTP API / JSON-FG |
-| `ogc-tiles` | OGC API - Tiles | HTTP API / TileJSON |
-| `ogc-coverages` | OGC API - Coverages | HTTP API / CoverageJSON |
-| `wfs` | WFS 服务 | OGC WFS 3.0 |
-| `wms` | WMS 服务 | OGC WMS |
-| `wmts` | WMTS 服务 | OGC WMTS 瓦片服务 |
-| `tms` | TMS（Tile Map Service） | URL 模板 `{z}/{x}/{y}.pbf` |
-| `mvt` | Mapbox Vector Tile | `application/vnd.mapbox-vector-tile` |
-| `rest-api` | 通用 REST API 响应 | HTTP JSON |
-| `mqtt` | MQTT 流式数据 | MQTT Topic 订阅 |
-
---
-
-## 3. 数据类型映射规则
-
-### 3.1 主类型（high-level）
-
-脚本声明 `data_type` 时，必须指定一个主分类：
-
-```
-data_type: "<主分类>/<子类型>"
-```
-
-示例：
-```yaml
-data_type: "vector/geojson"
-data_type: "raster/geotiff"
-data_type: "pointcloud/las"
-data_type: "document/pdf"
-```
-
-### 3.2 输入输出声明
-
-脚本通过 `params_schema` 和 `output_schema` 声明输入输出的数据类型：
-
-```yaml
-params_schema:
-  type: object
-  properties:
-    input_file:
-      type: string
-      data_type: "vector/geojson"       # ← 标注入参数据类型
-      desc: "输入矢量数据"
-    buffer_distance:
-      type: number
-      desc: "缓冲区半径（米）"
-
-output_schema:
-  type: object
-  properties:
-    result_file:
-      type: string
-      data_type: "vector/geojson"       # ← 标注出参数据类型
-      desc: "缓冲区结果"
-```
-
-### 3.3 合规检测规则
-
-合规检测服务使用以下规则校验脚本：
-
-1. **主类型必须属于上述分类** — 不支持的分类返回 `invalid_data_type`
-2. **输入数据类型与脚本声明的 `data_type` 必须兼容** — 子类型属于主类型即可
-3. **跨子类型兼容性规则**：
-   - `vector/*` ⊆ `vector`（统一主类即可，子类互转合规检测不校验）
-   - `raster/*` ⊆ `raster`
-4. **链式脚本的数据类型传递**：脚本 B 的输入数据类型必须与前序脚本 A 的输出数据类型匹配（同一主类即可）
-
---
-
-## 4. 参数模板映射
-
-合规检测服务根据数据类型推荐参数模板：
-
-| 主类型 | 默认模板 | 可配置模板 |
-|--------|---------|-----------|
-| `vector` | `vector-input`（文件路径 + 坐标系 + 编码） | `vector-batch`, `vector-stream` |
-| `raster` | `raster-input`（文件路径 + 波段 + CRS） | `raster-multiband`, `raster-pyramid` |
-| `pointcloud` | `pointcloud-input`（文件路径 + 坐标精度） | `pointcloud-filter`, `pointcloud-tile` |
-| `document` | `document-input`（文件路径 + 解析选项） | `document-extract`, `document-convert` |
-| `tabular` | `tabular-input`（文件路径 + 分隔符 + 编码） | `tabular-batch`, `tabular-join` |
-| `image` | `image-input`（文件路径 + 格式） | `image-batch`, `image-ocr` |
-| `archive` | `archive-input`（压缩包路径 + 解压规则） | `archive-extract`, `archive-repack` |
-| `spatialdb` | `spatialdb-input`（连接串 + 查询 + 表名） | 无 |
-| `streaming` | `api-input`（URL + 认证 + 请求参数） | 无 |
-
---
-
-## 5. 新增数据类型流程
-
-当平台需要支持新的数据类型时，更新此文件并重新发布到 SuiteForge 知识库：
-
-1. 确定主分类归属（或创建新主分类）
-2. 定义子类型标识符、扩展名、格式标识
-3. 编写对应的参数模板（合规检测服务端）
-4. 更新此文件（SuiteForge 知识库）
-5. 通知合规检测服务更新模板注册表
-
---
-
-## 6. 参考实现
-
- **合规检测服务**：`compliance-service` 校验时，数据类型列表由 `TYPE_REGISTRY` 提供
- **脚本元数据结构**：参考[脚本开发指南](../script-dev-guide.md)
- **参数模板**：存储在合规检测服务的 `templates/` 目录
@@ -1,251 +0,0 @@
-# 脚本依赖管理规范
-
-> **归属：** SuiteForge 知识库 | `knowledge/script-dependencies.md`
-> **版本：** 1.0.0
-> **关联：** [脚本数据类型分类规范](./script-data-types.md)
-
---
-
-## 1. 核心原则
-
- **gis-base 保持精干** — 只放所有脚本绝对需要的核心库
- **依赖按需加载** — 不允许在基础镜像预装所有可能的依赖
- **依赖类型决定加载策略** — 轻量运行时装、中量预构建镜像、重型发布时构建
-
---
-
-## 2. gis-base 内置依赖（开箱即有）
-
-以下库在 `gis-base` 镜像中预置，脚本无需额外声明依赖即可使用：
-
-| 类别 | 库 | 用途 |
-|------|----|------|
-| Python 标准库 | `os`, `sys`, `json`, `csv`, `math`, `re`, `pathlib`, `shutil`, `subprocess`, `tempfile`, `zipfile`, `tarfile`, `uuid`, `datetime`, `logging` | 基础操作 |
-| 数值计算 | `numpy` | 核心数组运算 |
-| GIS 核心 | `gdal`（含 `ogr`, `osr`, `gdalconst`）, `osgeo` | 栅格/矢量读写 |
-| GIS 扩展 | `shapely`, `geopandas`, `pyproj`, `fiona` | 空间分析 |
-| 序列化 | `orjson` | 高性能 JSON |
-
-> **注意：** gis-base 镜像内容由平台团队维护。需要新增内置库时，请通过 Issue 提出，交 Admin 处理。
-
---
-
-## 3. 依赖声明方式
-
-### 3.1 脚本 metadata 中声明
-
-```yaml
-# scripts/run.py 同目录的 metadata.yaml
-name: 读取 Excel 坐标转 Shapefile
-version: 1.0.0
-data_type: document/xlsx
-dependencies:
-  # 轻量运行时依赖
-  pip:
-    - openpyxl>=3.0
-    - python-docx>=0.8
-
-  # 系统级依赖（apt 包）
-  system:
-    - libpdal-dev        # 点云处理库
-
-  # 构建时依赖（必须通过 Dockerfile.ext 安装）
-  build:
-      # 空数组表示无构建时依赖
-```
-
-### 3.2 workflow.yaml 中声明
-
-当在套件中直接引用脚本时，也可以在步骤级别声明：
-
-```yaml
- id: parse-excel
-  type: script
-  script_id: run
-  dependencies:
-    pip:
-      - openpyxl>=3.0
-```
-
-> 步骤级声明会覆盖脚本自带的依赖声明。
-
---
-
-## 4. 依赖分级处理机制
-
-### 4.1 级别一：轻量运行时依赖（pip）
-
-**适用场景：**
- 纯 Python 包，无编译依赖
- 体积小，安装快（< 30 秒）
- 非高频调用（偶尔使用）
-
-**处理流程：**
-```bash
-# 容器启动时自动安装
-docker run --rm gis-base \
-  pip install openpyxl python-docx --no-cache-dir \
-  && python /tmp/scripts/run.py
-```
-
-**限速规则：** 单次任务安装的 pip 包不超过 10 个，总安装时间不超过 60 秒。
-
-### 4.2 级别二：中量扩展镜像（预构建）
-
-**适用场景：**
- 经常被调用的扩展依赖
- 有编译环节的包（C 扩展）
- 安装需要 30 秒以上的
-
-**扩展镜像命名规则：**
-
-```
-registry.mercator.cn/agentgis/gis-ext-{功能}:{版本}
-```
-
-**已规划扩展镜像：**
-
-| 镜像名 | 包含依赖 | 典型脚本场景 |
-|--------|---------|-------------|
-| `gis-ext-doc` | `openpyxl`, `python-docx`, `pypdf2`, `python-pptx` | Office 文档处理 |
-| `gis-ext-pointcloud` | `laspy`, `pdal`, `open3d-python` | 点云处理 |
-| `gis-ext-raster` | `rioxarray`, `rasterio`, `xarray`, `scipy` | 高级栅格分析 |
-| `gis-ext-geoanalysis` | `scipy`, `scikit-learn`, `statsmodels` | 空间统计分析 |
-| `gis-ext-ml` | `scikit-learn`, `xgboost`, `lightgbm` | 地理空间机器学习 |
-| `gis-ext-web` | `requests`, `httpx`, `aiohttp`, `beautifulsoup4` | 网络数据抓取 |
-| `gis-ext-db` | `psycopg2-binary`, `sqlalchemy`, `sqlite-utils` | 数据库连接 |
-
-**匹配逻辑（调度中心）：**
-
-```
-脚本声明的 pip 依赖
-           ↓
-调度中心匹配 → 命中扩展镜像 → 使用扩展镜像运行
-           → 未命中 → 回退级别一（运行时安装）
-```
-
-匹配是取**最小子集**——如果脚本只需要 `openpyxl`，就用 `gis-ext-doc`，而不是选所有包含 `openpyxl` 的镜像。
-
-### 4.3 级别三：重型自定义镜像（构建时）
-
-**适用场景：**
- 深度学习框架（PyTorch, TensorFlow）
- 需要 GPU 加速（CUDA 依赖）
- 专有库/商业许可库（选装）
- 安装时间 > 120 秒的
-
-**处理方式：**
-
-脚本发布时附带 `Dockerfile.ext`：
-
-```dockerfile
-# Dockerfile.ext
-FROM registry.mercator.cn/agentgis/gis-base:latest
-
-# 安装系统依赖
-RUN apt-get update && apt-get install -y --no-install-recommends \
-    libgl1-mesa-glx \
-    && rm -rf /var/lib/apt/lists/*
-
-# 安装 Python 依赖
-RUN pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu \
-    opencv-python-headless \
-    --no-cache-dir
-```
-
-**合规检测规则：**
- `FROM` 只能引用 `registry.mercator.cn/agentgis/*` 系列镜像
- 不允许 `FROM` 外部镜像库（安全性）
- `RUN pip` 的来源 URL 必须在白名单内（PyPI 官方默认通过）
- `RUN apt` 来源必须在 `apt allowlist` 内
-
-**CI 流水线（Cron 兜底）：**
-
-```
-脚本发布 → 检测到 Dockerfile.ext
-         → 合规检测通过
-         → 构建自定义镜像
-         → 推送到 registry.mercator.cn/agentgis/custom/{suite_id}:{version}
-         → 将镜像 ID 写入脚本 metadata
-```
-
---
-
-## 5. 依赖来源安全白名单
-
-### 5.1 Python 包
-
-| 来源 | 状态 | 说明 |
-|------|------|------|
-| `pypi.org`（官方） | ✅ 白名单 | 默认允许 |
-| `download.pytorch.org` | ✅ 白名单 | ML 框架 |
-| `github.com/releases` | ⚠️ 需审核 | 非标准包需要人工审核 |
-
-### 5.2 系统包（apt）
-
-| 来源 | 状态 | 说明 |
-|------|------|------|
-| `archive.ubuntu.com` | ✅ 白名单 | Ubuntu 官方源 |
-| `security.ubuntu.com` | ✅ 白名单 | 安全更新 |
-| `ppa.launchpad.net` | ❌ 禁止 | PPA 源不稳定 |
-
---
-
-## 6. 常见场景参考
-
-| 脚本要做什么 | 推荐方案 | 依赖示例 |
-|------------|---------|---------|
-| 读取 Excel 坐标转点 | 级别一 | `openpyxl` |
-| PDF 空间信息提取 | 级别一 | `pypdf2` |
-| 点云格式转换（LAS → LAZ）| 级别二 | 预置 `gis-ext-pointcloud` |
-| 地形分析（坡度/坡向）| 内置 | `numpy` + `gdal` 已内置 |
-| 地理空间分类模型 | 级别二 | 预置 `gis-ext-geoanalysis` |
-| 遥感影像深度学习分类 | 级别三 | `torch`, `opencv` |
-| 企业微信消息推送 | 级别一 | `requests` 已内置 |
-| 大量 GeoJSON 合并 | 内置 | `geopandas` 已内置 |
-
---
-
-## 7. 镜像更新策略
-
-### 扩展镜像
- 每月重建一次（拉取最新安全更新）
- 有 CVE 时立即重建
- 版本锁定的包如无必要不升级大版本
-
-### gis-base
- 仅在有架构级更新时重建
- 版本变更需经过完整回归测试
- 历史版本保留至少 3 个次要版本
-
-### 自定义镜像
- 由脚本开发者管理版本
- 重新发布脚本时自动重建
- 无自动更新，需要开发者主动重新发布
-
---
-
-## 8. 开发者工作流（供 SuiteForge 参考）
-
-```
-1. 想清脚本需要什么依赖
-2. 查 gis-base 内置列表 → 已有的不声明
-3. 查扩展镜像列表 → 匹配的用级别二
-4. 都不行 → 看看能不能用轻量安装（级别一）
-5. 真不行 → 写 Dockerfile.ext（级别三）
-6. 完成 metadata.yaml 声明
-7. agc publish → 合规检测自动处理
-```
-
-**SuiteForge 应在初始化套件时根据脚本内容自动推断依赖**，无需开发者手动填写 metadata。开发者只需要告诉 SuiteForge "我想处理 Excel 文件"，剩下的由 Agent 完成。
-
---
-
-## 9. 与相关服务的关系
-
-| 服务 | 对接方式 |
-|------|---------|
-| **合规检测服务** | 读取 dependencies 字段 + Dockerfile.ext 进行安全校验 |
-| **调度中心** | 根据依赖选择镜像层次（base / ext / custom） |
-| **构建流水线（Cron）** | 检测到 Dockerfile.ext 时触发自定义镜像构建 |
-| **镜像仓库（Registry）** | 存储 gis-base、扩展镜像、自定义镜像 |
@@ -1,65 +1,80 @@
 # AGENTS.md — 你是套件使用者

-你是 AgentGIS Cloud Platform 的终端用户。你用现成的套件处理 GIS 数据。
+你是 AgentGIS 平台的最终用户。你的任务是使用现成的 GIS 套件处理数据。

-## 🚨 核心概念：本地执行
+## 前置准备

-**你的数据文件永远不上传云端。** 流程是这样的：
+### 安装 gis-actions

-```
-你的操作                          背后发生的事情
-──────────                      ──────────────────
-1. 打开 suites.mercator.cn       → 浏览公开套件列表，无需登录
-   浏览套件市场
-2. 找到想要的套件，记下 ID        → 套件详情有参数说明
-3. 准备本地的数据文件             → 文件在你的硬盘上
-   记下文件路径
-4. 执行套件                      → gis-actions 从市场拉取脚本包
-   agc run <suite-id>            → 启动本地 Docker 容器
-   --inputs '{"input_path":      → 将你的路径挂载到容器内
-     "/data/myfile.shp"}'        → 脚本在容器中处理你的文件
-                                 → 结果写入 /tmp/output/
-5. 查看结果                      → 你的机器上的文件
+**Linux：**
+```bash
+curl -sLO https://packages.mercator.cn/public/gis-actions/latest.deb
+sudo dpkg -i latest.deb
+agc --help
 ```

-**全程你的数据文件没有离开过你的机器。**
+**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`

-## 你的工作方式
+### 配置 API Key

-### 1. 浏览市场
+首次运行前需要配置 Auth Center 的 API Key：

-打开 https://suites.mercator.cn，浏览套件列表。
-按关键词搜索，按分类筛选。
-浏览公开内容不需要登录，也不需要 API Key。
+1. 登录 https://auth.mercator.cn，创建 API Key
+2. 运行 `agc config set api_key <你的 API Key>`

-### 2. 选择套件
+## Linux 版首次执行 `agc run` 时会自动下载 gis-base 运行镜像。Windows 版不需要镜像。

-看套件详情：
- **用途**：描述信息
- **输入**：需要你提供什么（文件路径、数值等）
- **输出**：执行完能拿到什么
+## 遇到问题？

-确认符合需求后，记下套件 ID。
+前往 https://discussions.mercator.cn/ 发话题。贴出你的命令和错误信息，管理员会帮你排查。

-### 3. 准备输入
+## 执行流程

-套件需要的本地数据文件准备好，记下路径。
+### 1. 查市场，选套件

-### 4. 执行
+```bash
+# 所有套件（Linux + Windows）
+curl -s https://suites.mercator.cn/api/v1/suites | python3 -m json.tool

-用 `agc run <suite-id>` 提交任务。GIS Actions 会：
-1. 从套件市场拉取执行脚本
-2. 在本地 Docker 容器中处理你的文件（挂载只读输入，挂载写入输出）
-3. 脚本包执行完后自动销毁
-4. 输出结果到本地目录
+# 仅 Windows 套件
+curl -s 'https://suites.mercator.cn/api/v1/suites?platform=windows' | python3 -m json.tool
+```

-### 5. 查看结果
+记下你要用的套件 ID。

-执行完成后，结果文件在 `/tmp/output/` 目录中。
-如果套件生成了报告，查看报告了解处理前后的对比。
+### 2. 在本地执行

-## 多一步的思考
+```bash
+SUITE_MARKET_URL="https://suites.mercator.cn" \
+agc run /tmp/my-output \
+  --suite-id <suite-id> \
+  --input key=value \
+  --input key2=value2
+```

- **执行失败了？** → 看错误信息，检查输入文件路径是否正确、格式是否支持
- **结果不对？** → 检查参数值是否合理
- **套件不好用？** → 换个套件或反馈给开发者
+- 文件路径用本地绝对路径
+- 一个文件一个 `--input`，支持多个
+- shapefile 只需传 `.shp` 路径，配套文件（.shx/.dbf/.prj）会自动复制
+
+### 3. 取结果
+
+结果文件在 `--input output_path` 指定的路径下，默认在 `/tmp/my-output/_step_outputs/` 中。
+
+## 数据流向
+
+```
+你本地的 SHP/XLS 文件
+    │
+    ▼
+agc run（你的机器）
+    │  ← 从套件市场下载脚本包
+    │  ← 复制输入文件到工作目录
+    │  → docker run gis-base + 套件脚本
+    │  → 结果写入 /tmp/output/
+    ▼
+结果文件留在你的机器
+```
@@ -20,7 +20,7 @@

 **数据永不离开本地。**
 你提供给套件的文件（SHP、GeoJSON、TIFF）始终在你的机器上。
-GIS Actions 在你的机器上处理它们，结果文件也在你的机器上。
+GIS Actions 在你的机器上处理它们（Linux Docker 容器或 Windows 本机进程），结果文件也在你的机器上。

 **只使用已发布的套件。**
 从市场选择，不自己改代码。套件不好用就换个套件，或者反馈给开发者。
@@ -40,5 +40,5 @@ GIS Actions 在你的机器上处理它们，结果文件也在你的机器上
 ## 工具

 - **市场前端:** https://suites.mercator.cn — 浏览、选择、提交
- **CLI:** `agc run <suite-id>` — 快速执行
- **GIS Actions:** 运行在你的机器上，处理本地数据
+- **CLI:** `agc run <work-dir> --suite-id <suite-id> --input key=value` — 快速执行
+- **GIS Actions（`agc` 命令）:** 运行在你的机器上（Linux agc 或 Windows agc.exe），处理本地数据
@@ -3,21 +3,90 @@
 ## 平台入口

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

 ## 关键原则

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

-## gis-actions 工作原理
+## 安装

-gis-actions 是你机器上的本地执行器，它：
-1. 连接调度中心等待任务
-2. 收到任务后下载套件脚本包
-3. 在 Docker 容器中执行（使用 gis-base 镜像）
-4. 结果写入本地目录，脚本包自动清理
+### 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            # 检查并升级到最新版
+```

 ## 常见问题

@@ -25,18 +94,16 @@ gis-actions 是你机器上的本地执行器，它：
 A: 只有脚本包下载需要网络。数据处理全程在本地。

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

 **Q: 结果在哪？**
-A: 默认在 `/tmp/output/`（可在配置文件中设置）。
-
-**Q: gis-actions 占资源吗？**
-A: 空闲时几乎不占资源。执行时才启动 Docker 容器。
+A: 默认在工作目录的 `_step_outputs/` 下。

 **Q: 能同时跑多个任务吗？**
-A: 取决于你的机器配置和配置项。
+A: 可以，打开多个终端各自跑 `agc run`。

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

-你需要在自己机器上安装 gis-actions 才能执行套件。
-详见 TOOLS.md 中的部署步骤：Python 3 + Docker + API Key 配置。
+**Q: API Key 会不会过期？**
+A: 长期有效。如需吊销，在套件市场个人中心操作。
@@ -8,7 +8,7 @@ AgentGIS 和你用过的其他平台不一样：

 ```
 其他平台：你把文件上传到服务器 → 服务器处理 → 你下载结果
-AgentGIS：你的文件留在本地 → gis-actions 在你机器上处理 → 结果在你本地
+AgentGIS：你的文件留在本地 → agc 在你机器上处理（Linux Docker 或 Windows 本机）→ 结果在你本地
 ```

 **你不用上传任何数据文件。** 永远提供本地文件路径，不提供文件内容。
@@ -31,7 +31,7 @@ AgentGIS：你的文件留在本地 → gis-actions 在你机器上处理 →
 ## 执行规则

 - **提供本地文件路径**（例如 `/data/myfile.shp`），不是上传文件
- **数据永不离开你的机器** — gis-actions 在你的 Docker 中处理，不在云端
+- **数据永不离开你的机器** — agc 在你的 Linux Docker 或 Windows 本机中处理，不在云端
 - **文件即点即用**，无需等待上传
 - **执行过程中你可以离开**，完成后回来查看结果
 - 任务失败了：看错误信息。信息看不懂 → 反馈给套件开发者
@@ -4,118 +4,105 @@

 https://suites.mercator.cn

-浏览套件、查看详情、提交执行任务。
+浏览套件、查看详情。

-## CLI（可选）
+## 安装
+
+### Linux
+
+安装 `gis-actions` 包即可获得全部功能（CLI + 执行引擎），一次安装：

 ```bash
-# 安装 agentgis-cli
-pip install https://git.mercator.cn/api/packages/SuiteHub/generic/agentgis-cli/0.1.0/agentgis_cli-0.1.0-py3-none-any.whl
+# 下载
+curl -sLO https://packages.mercator.cn/public/gis-actions/latest.deb

-# 配置 API Key
-agc config set api-key mk_xxxxxxxxx
-
-# 执行套件（在市场找到 suite-id 后）
-agc run <suite-id> --inputs '{"input_path": "/data/myfile.shp"}'
-
-# 查看套件列表
-agc suites list
-
-# 查看执行状态
-agc status <task-id>
+# 安装
+sudo dpkg -i latest.deb
 ```

-## gis-actions（本地执行器部署）
+安装后可用 `agc` 命令（已内置在包中）。

-gis-actions 是套件的本地执行引擎，跑在你的机器上。
+## 交流反馈

-### 前提条件
+遇到任何问题或需要帮助，前往 https://discussions.mercator.cn/ 发话题。平台管理员和其他用户会在那里解答。

- **Debian / Ubuntu 系统**
- **Docker**（验证：`docker ps`）
-  - `sudo apt install docker.io`
- 能访问 `registry.mercator.cn`（拉取 gis-base 镜像）
+- **提问** — 使用 `question` 标签
+- **报 Bug** — 使用 `bug` 标签
+- **提建议** — 使用 `feature` 或 `suggestion` 标签

-### 安装
+### Windows
+
+1. 下载 [latest-windows.zip](https://packages.mercator.cn/public/gis-actions/latest-windows.zip)
+2. 解压到 `%LOCALAPPDATA%\\AgentGIS\\gis-actions\\`
+3. 将 `%LOCALAPPDATA%\\AgentGIS\\gis-actions\\` 加入 `PATH`
+4. 验证：`agc --help`
+
+> Windows 版支持 **arcpy**（需要 ArcMap 10.8）和 **python3** 两种 runtime。
+> 不依赖 Docker，直接在本地进程执行。
+
+## 前提条件
+
+- **Linux 系统**（Debian / Ubuntu）
+- **Docker**（验证：`docker ps`，仅 Linux 版需要）
+- **API Key** — 登录 https://auth.mercator.cn 获取，后续 `agc config set api_key <你的API Key>` 使用
+
+### gis-base 基础镜像
+
+Linux 版所有套件运行在 `gis-base` 镜像中（含 Python 3, GDAL, Shapely, GeoPandas, numpy, openpyxl, xlrd）。
+Windows 版使用本地 Python 环境（arcpy 或 python3），不需要 Docker。
+
+首次安装 gis-actions 时会自动下载镜像。也可提前手动准备：

 ```bash
-# 下载并安装 gis-actions
-wget -O agentgis-worker.deb https://git.mercator.cn/api/packages/SuiteHub/generic/gis-actions/v2.0.0-alpha/agentgis-worker_2.0.0-alpha_all.deb
-sudo dpkg -i agentgis-worker.deb
-
-# 安装后会自动配置 systemd 服务和 Docker insecure-registry
+# 从 Gitea 直接下载镜像包（无需 registry 账号）
+curl -sLO https://packages.mercator.cn/public/gis-base/latest.tar.gz
+docker load -i gis-base.tar.gz
 ```

-### 配置
-
-编辑 `/etc/agentgis/worker.json`：
-
-```json
-{
-  "worker": {
-    "id": "my-machine-001",
-    "capabilities": ["gis-operations"]
-  },
-  "scheduler": {
-    "url": "https://suites.mercator.cn",
-    "poll_interval": 5,
-    "heartbeat_interval": 30
-  },
-  "auth": {
-    "api_key": "你的 API Key"
-  }
-}
-```
-
-API Key 从 https://auth.mercator.cn 获取。
-
-### 启动
+## 执行套件

 ```bash
-sudo systemctl start agentgis-worker
-sudo systemctl status agentgis-worker
+# 查询市场套件（通过 curl）
+curl -s https://suites.mercator.cn/api/v1/suites | python3 -m json.tool
+
+# 执行套件，输入参数用 key=value 格式
+agc run /tmp/output --suite-id <suite-id> --input key=value
 ```

-### 验证
+`<suite-id>` 从市场 API 或前端页面获取。
+
+
+
+## AI Agent 集成（MCP）
+
+GIS Actions 支持 MCP（Model Context Protocol），AI Agent 可直接调用 GIS 工具：

 ```bash
-journalctl -u agentgis-worker -f
-# 应看到：Worker xxx started, polling https://suites.mercator.cn every 5s
+# 启动 MCP Server（stdio 模式，供 Claude Desktop 等本地 Agent 使用）
+agc mcp
+
+# SSE 模式（HTTP，供远程 Agent 调用）
+agc mcp --transport sse --port 8080
 ```

-### 停止
+Agent 通过 MCP 协议自动发现可用套件并调用执行，无需人工介入。

-```bash
-sudo systemctl stop agentgis-worker
-```
-
-### 卸载
-
-```bash
-sudo dpkg --purge agentgis-worker
-```
-
-### 数据流向
+## 数据流向

 ```
-你本地的 SHP/GeoJSON/TIFF 文件
+你本地的 SHP/GeoJSON/TIFF/XLS 文件
    │
    ▼
 gis-actions（你的机器）
-    │  ← 从调度中心拉取任务
-    │  ← 下载套件脚本包
+    │  ← 从市场下载套件脚本包
    │  ← docker run gis-base + 套件脚本
    │  → 结果写入 /tmp/output/
    ▼
 结果文件（你的机器）
 ```

-## 支持的输入类型
+## 注意事项

-| 类型 | 说明 | 示例 |
-|------|------|------|
-| `file` | 本地文件路径 | `/data/land_use.shp` |
-| `string` | 文本 | `"缓冲区距离: 500"` |
-| `number` | 数值 | `500.0` |
-| `integer` | 整数 | `100` |
-| `boolean` | 布尔值 | `true` |
+- 输入文件路径使用你的本地绝对路径
+- shapefile 需要传入目录路径而非单文件路径（因 .dbf/.shx 配套文件）
+- 套件数据不上传云端，全部在你的机器上处理
@@ -1,54 +0,0 @@
-# 套件市场帮助中心
-
-> `suites.mercator.cn` 是 AgentGIS Cloud Platform 的套件市场入口。
-
---
-
-## 📖 系统使用手册
-
-面向**终端用户**——浏览套件、执行任务、查看结果。
-
-| 文档 | 说明 |
-|------|------|
-| [快速入门](./系统使用手册/快速入门.md) | 从零开始使用套件市场 |
-| [浏览与选择套件](./系统使用手册/浏览与选择套件.md) | 查找和选择适合的套件 |
-| [执行任务与查看结果](./系统使用手册/执行任务与查看结果.md) | 提交任务、获取结果 |
-| [GIS Actions 本地部署](./系统使用手册/GIS-Actions-本地部署.md) | 在用户机器上安装和执行器 |
-
-## 🔧 开发者指南
-
-面向**套件开发者**——开发、测试、发布套件。
-
-| 文档 | 说明 |
-|------|------|
-| [快速开始](./开发者指南/快速开始.md) | 从零开发第一个套件 |
-| [Workflow 规范](./开发者指南/Workflow-规范.md) | workflow.yaml 完整参考 |
-| [脚本开发指南](./开发者指南/脚本开发指南.md) | Python 脚本编写方法 |
-| [套件发布指南](./开发者指南/套件发布指南.md) | 发布套件到市场 |
-| [最佳实践](./开发者指南/最佳实践.md) | 复用、测试、调试技巧 |
-
-## 📦 SDK 参考
-
-面向**程序化调用**——Python SDK、CLI、API。
-
-| 文档 | 说明 |
-|------|------|
-| [Python SDK](./SDK参考/Python-SDK.md) | Python 客户端使用 |
-| [CLI 参考](./SDK参考/CLI-参考.md) | agc 命令全览 |
-| [API 参考](./SDK参考/API-参考.md) | REST API 端点说明 |
-
-## 💡 示例代码
-
-| 文档 | 说明 |
-|------|------|
-| [Hello World](./示例代码/Hello-World.md) | 最小可工作套件 |
-| [缓冲区分析](./示例代码/缓冲区分析.md) | 完整的 GIS 文件处理套件 |
-
-## 🤖 智能体提示
-
-面向 **AI Agent** 的身份认知文件。
-
-| 文档 | 说明 |
-|------|------|
-| [套件开发者配置](../suite-developer/IDENTITY.md) | SuiteForge 角色定位 |
-| [套件使用者配置](../suite-user/IDENTITY.md) | SuiteEndUser 角色定位 |
@@ -8,8 +8,6 @@ https://suites.mercator.cn

 ## 认证

-使用 `Bearer Token` 或 `API Key`：
-
 ```bash
 Authorization: Bearer mk_xxxxxxxxxxxxx
 ```
@@ -20,31 +18,15 @@ API Key 从 https://auth.mercator.cn 获取。

 | 方法 | 端点 | 说明 |
 |------|------|------|
-| POST | `/api/v1/suites` | 创建套件 |
-| GET | `/api/v1/suites` | 套件列表 |
-| GET | `/api/v1/suites/search?q=` | 搜索套件 |
+| GET | `/api/v1/suites` | 套件列表（支持 `?category=` `?platform=linux/windows/all` 筛选） |
 | GET | `/api/v1/suites/{id}` | 套件详情 |
 | PATCH | `/api/v1/suites/{id}` | 更新套件 |
-| DELETE | `/api/v1/suites/{id}` | 删除套件 |
-| POST | `/api/v1/suites/{id}/execute` | 执行套件 |

-## 任务 API
+## 发布 API

 | 方法 | 端点 | 说明 |
 |------|------|------|
-| GET | `/api/v1/task/next` | 拉取待执行任务（长轮询）|
-| PATCH | `/api/v1/task/{id}/status` | 更新任务状态 |
-| GET | `/api/v1/task/{id}` | 查询任务详情 |
-
-## 脚本 API
-
-| 方法 | 端点 | 说明 |
-|------|------|------|
-| POST | `/api/v1/scripts` | 注册脚本 |
-| GET | `/api/v1/scripts` | 脚本列表 |
-| GET | `/api/v1/scripts/search?q=` | 搜索脚本 |
-| GET | `/api/v1/scripts/{id}` | 脚本详情 |
-| PATCH | `/api/v1/scripts/{id}` | 更新脚本 |
+| POST | `/api/v1/publish/upload` | 发布套件（上传 TGZ 包 + `platform` 字段 + 需 Gitea Token） |

 ## 完整文档

@@ -64,3 +46,15 @@ API Key 从 https://auth.mercator.cn 获取。
 | 409 | 资源冲突 |
 | 422 | 参数校验失败 |
 | 500 | 服务器内部错误 |
+
+
+### POST /api/v1/publish/upload
+
+**参数：**
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `file` | ✅ | File | 套件压缩包（含 workflow.yaml + scripts/）|
+| `gitea_token` | ✅ | string | 发布者的 Gitea Token（需包写入权限） |
+
+发布到 `SuiteHub` 组织下，包名为英文 slug。
@@ -2,48 +2,59 @@

 ## 安装

+`agc` 命令随 gis-actions 包一起安装。
+
+**Linux：**
 ```bash
-# 从 Gitea 安装
-pip install https://git.mercator.cn/SuiteHub/agentgis-cli/raw/branch/main/dist/agentgis_cli-0.1.0-py3-none-any.whl
+curl -sLO https://packages.mercator.cn/public/gis-actions/latest.deb
+sudo dpkg -i latest.deb
 ```

-## 配置
+**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`

-```bash
-agc config set api-key mk_xxxxxxxxxxxxx
-```
+安装后直接使用 `agc` 命令。

 ## 命令

-### 查询套件
+### agc run
+
+执行套件。
+
+```bash
+agc run <work_dir> --suite-id <suite-id> --input <key=value> [--input <key=value> ...]
+agc run <work_dir> --package-url <url> --input <key=value>
+```
+
+| 参数 | 说明 |
+|------|------|
+| `work_dir` | 工作目录路径（输出写入此目录） |
+| `--suite-id` | 套件 ID（从市场 API 查询） |
+| `--package-url` | 直接指定脚本包下载地址（替代 --suite-id） |
+| `--input` / `-i` | 输入参数，格式 `key=value`，可多次指定 |
+| `--api-key` | API Key（查市场时使用，也可设环境变量 `AGENTGIS_API_KEY`） |
+
+### 示例
+
+```bash
+# 通过套件 ID 执行
+agc run /tmp/output --suite-id 2c99a1cb-84a5-42dd-9147-1c8e8f7f2941 --input buffer_distance=0.5
+
+# 直接指定包地址
+agc run /tmp/output --package-url https://git.mercator.cn/.../suite.tgz --input input_path=/data/my.shp
+```
+
+## 查询市场
+
+`agc` 暂未内置市场查询命令，使用 curl：

 ```bash
 # 列出所有套件
-agc suites list
+curl -s https://suites.mercator.cn/api/v1/suites | python3 -m json.tool

 # 搜索套件
-agc suites search <关键词>
-
-# 查看套件详情
-agc suites get <suite-id>
-```
-
-### 执行
-
-```bash
-# 执行套件
-agc run <suite-id> --inputs '{"expression": "1+1"}'
-
-# 查看执行状态
-agc status <task-id>
-```
-
-### 开发
-
-```bash
-# 从模板创建新套件
-agc init ./my-suite
-
-# 发布套件
-agc publish ./my-suite
+curl -s "https://suites.mercator.cn/api/v1/suites/search?q=缓冲区"
 ```
@@ -1,37 +0,0 @@
-# Python SDK
-
-## 安装
-
-```bash
-pip install https://git.mercator.cn/SuiteHub/agentgis-sdk/raw/branch/main/dist/agentgis_sdk-0.1.0-py3-none-any.whl
-```
-
-## 快速开始
-
-```python
-from agentgis import AgentGIS
-
-client = AgentGIS(api_key="mk_xxxxxxxxx", base_url="https://suites.mercator.cn")
-
-# 查询套件列表
-suites = client.list_suites()
-for s in suites:
-    print(f"{s.name} v{s.version}")
-
-# 查询套件详情
-detail = client.get_suite("suite-id-xxx")
-print(detail.description)
-
-# 执行套件
-execution = client.execute_suite("suite-id-xxx", inputs={"buffer_distance": 0.5})
-print(f"Execution: {execution.execution_id}")
-
-# 查询执行状态
-status = client.get_execution(execution.execution_id)
-print(f"Status: {status.status}")
-```
-
-## API 参考
-
-完整的 API 客户端方法列表和参数说明见自动生成的 API 文档：
-[https://suites.mercator.cn/docs](https://suites.mercator.cn/docs)
@@ -0,0 +1,322 @@
+# 🏗️ AgentGIS 前端约定
+
+> **目的**: 减少每个子系统在前端上的反复调整，一次定规矩，后续照做。
+> **适用**: suite-market、auth-center、discussions 等所有 Next.js 前端。
+> **版本**: v1.0 (2026-07-21)
+
+---
+
+## 一、页面骨架
+
+所有页面使用统一的三段式骨架布局，不另起炉灶：
+
+```
+┌──────────────────────────────────────────────┐
+│ 顶部导航（Navbar）                             │
+│ 套件 | 发布 | 管理 | 文档    [登录/用户头像]   │
+├────────┬─────────────────────────────────────┤
+│ 左侧   │           右侧内容区                  │
+│ 导航   │   （各页面自定）                      │
+│        │                                     │
+│ (各页面  │                                     │
+│  自定)  │                                     │
+└────────┴─────────────────────────────────────┘
+└────────────── 页脚（Footer） ──────────────────┘
+```
+
+**规则：**
+- 顶部导航统一在 `Navbar.tsx` 维护，不单独定制
+- 左侧导航通过页面级 `layout.tsx` 注入（Next.js App Router）
+- 页脚全局统一
+- 不出现面包屑（用左侧导航替代）
+
+---
+
+## 二、未认证状态
+
+所有需要登录的页面，未认证时**必须**做到：
+
+```
+┌─────────────────────────────────────┐
+│     🔒 请登录后浏览                  │
+│                                      │
+│  登录后可查看套件、文档、管理后台等    │
+│                                      │
+│  （不显示登录按钮 — header 右上角有） │
+└─────────────────────────────────────┘
+```
+
+**规则：**
+- 使用统一 `LoginPrompt.tsx` 组件，不自制
+- 不显示登录按钮/链接（header 右上角已有「登录」按钮）
+- API 调用返回 401 时，前端必须捕获并切换到 LoginPrompt，**不能卡在加载中**
+- 公开页面（首页等）不需登录，正常渲染
+
+---
+
+## 三、数据加载与错误处理
+
+所有页面按此顺序处理状态：
+
+```
+加载中 → 出错 → 空数据 → 正常渲染
+```
+
+**规则：**
+- 加载中：显示统一的「加载中...」骨架屏
+- 出错（含 401）：捕获错误，切换 LoginPrompt 或显示错误信息
+- 空数据：显示「暂无内容」+ 引导文案
+- 正常渲染：展示数据
+- 不允许出现「永远卡在加载中」的情况
+
+**所有 API 调用都必须有 `.catch()`：**
+
+```typescript
+// ✅ 正确
+fetchData().then(setData).catch(handleError)
+
+// ❌ 错误
+fetchData().then(setData)  // 无 catch = 卡在加载中
+```
+
+---
+
+## 四、目录结构
+
+每个 Next.js 前端项目统一按以下结构组织：
+
+```
+frontend/
+├── app/                    # App Router 页面
+│   ├── layout.tsx          # 全局布局（Navbar + Footer）
+│   ├── page.tsx            # 首页
+│   ├── suites/             # 套件
+│   │   ├── layout.tsx      # 套件左侧导航
+│   │   ├── page.tsx        # 列表
+│   │   └── [id]/page.tsx   # 详情
+│   ├── docs/               # 文档
+│   │   ├── layout.tsx      # 文档树形导航
+│   │   ├── page.tsx
+│   │   └── [slug]/page.tsx
+│   ├── admin/              # 管理后台
+│   │   ├── layout.tsx      # 管理侧边栏
+│   │   ├── applications/
+│   │   ├── suites/
+│   │   └── docs/
+│   └── publish/
+│
+├── components/             # 共享组件
+│   ├── Navbar.tsx          # 顶部导航
+│   ├── LayoutShell.tsx     # 骨架布局
+│   ├── LoginPrompt.tsx     # 未登录提示
+│   └── ...                 # 其他通用组件
+│
+├── lib/                    # 工具库
+│   ├── api.ts             # API 封装（含统一 401 处理）
+│   ├── auth.ts            # 认证
+│   └── auth-context.tsx   # 认证上下文
+│
+├── public/
+├── package.json
+└── next.config.ts
+```
+
+**规则：**
+- `app/` 下只放路由文件，不放组件
+- 业务组件放 `components/`
+- 工具函数放 `lib/`
+
+---
+
+## 五、API 401 拦截器
+
+`lib/api.ts` 中的 axios 实例统一处理 401：
+
+```typescript
+api.interceptors.response.use(
+  (res) => res,
+  async (err) => {
+    if (err.response?.status === 401 && typeof window !== "undefined") {
+      // 公开页面：静默返回错误，让页面组件自己处理
+      const path = window.location.pathname;
+      if (path === "/" || path.startsWith("/suites") || path.startsWith("/docs")) {
+        return Promise.reject(err);
+      }
+      // 管理类页面：尝试刷新 token
+      try {
+        const refreshRes = await axios.post(
+          "https://auth.mercator.cn/api/v1/public/refresh/",
+          {},
+          { withCredentials: true }
+        );
+        if (refreshRes.data?.access_token) {
+          setAccessToken(refreshRes.data.access_token);
+          err.config.headers["Authorization"] = "Bearer " + refreshRes.data.access_token;
+          return axios(err.config);
+        }
+      } catch {}
+      // 刷新失败：跳转登录
+      window.location.href = "https://auth.mercator.cn/login?return_url=" + encodeURIComponent(path);
+    }
+    return Promise.reject(err);
+  }
+);
+```
+
+**规则：**
+- 公开页面（suites、docs）的 401 → 静默返回，页面组件切换到 LoginPrompt
+- 管理页面（admin、publish）的 401 → 尝试刷新 token，刷新失败跳转登录
+- 不拦截器里弹 alert 或直接修改 DOM
+
+---
+
+## 六、深色/浅色主题
+
+- 使用 Tailwind `dark:` 变体控制深色模式
+- 通过 `ThemeToggle` 组件切换（位于 `components/`）
+- 默认跟随系统 `prefers-color-scheme`
+- 切换结果存入 localStorage，下次加载优先读取
+- 所有新组件必须同时测试浅色和深色模式
+
+---
+
+## 七、页面宽度与容器尺寸
+
+统一使用以下预设宽度：
+
+| 用途 | Tailwind class | 说明 |
+|------|---------------|------|
+| 最宽布局 | `max-w-7xl mx-auto` | 列表页、管理后台 |
+| 内容页（窄） | `max-w-3xl mx-auto` | 详情页、阅读页 |
+| 内容页（中） | `max-w-5xl mx-auto` | 文档列表、套件详情 |
+| 表单 | `max-w-lg mx-auto` | 登录、设置 |
+| 全宽 | `max-w-none` | 极少使用 |
+
+**不允许：** 每个页面自定义宽度，导致用户在页面间切换时视觉跳跃。
+
+---
+
+## 八、移动端适配
+
+- 使用 Tailwind 响应式前缀：`sm:`（640px）、`md:`（768px）、`lg:`（1024px）、`xl:`（1280px）
+- 导航栏在 `lg` 断点以下折叠为汉堡菜单（已实现）
+- 左侧导航在 `md` 以下默认隐藏，通过按钮切换显示
+- 表格在 `md` 以下切换为卡片视图（每行一张卡片）
+- 不允许仅桌面端可用的设计，所有页面必须跑通 375px 宽度
+
+---
+
+## 九、通知（Toast 替代 alert/confirm）
+
+- 不使用浏览器原生的 `alert()`、`confirm()`、`prompt()`
+- 使用统一的 Toast 通知组件
+- Toast 位置：右上角固定
+- 类型：success（绿色）、error（红色）、warning（黄色）、info（蓝色）
+- 自动消失：success/info 3 秒，warning/error 5 秒
+- 实现：用 react-hot-toast 或自建 `ToastProvider`
+
+---
+
+## 十、布局模板
+
+按是否有侧边导航分两种布局：
+
+### 带侧边导航
+
+```
+┌──────────┬────────────────────────────────┐
+│ 顶部导航  │                                │
+├──────────┤        右侧内容区                │
+│  侧边栏   │                                │
+│  (页面    │                                │
+│  自定)    │                                │
+└──────────┴────────────────────────────────┘
+```
+
+适用：suites、docs、admin
+实现方式：`<page>/layout.tsx`
+
+### 无侧边导航（全宽）
+
+```
+┌────────────────────────────────────────────┐
+│ 顶部导航                                    │
+├────────────────────────────────────────────┤
+│                                            │
+│              居中内容区                      │
+│                                            │
+└────────────────────────────────────────────┘
+```
+
+适用：/、/publish
+实现方式：`<page>/layout.tsx` 或直接在 page 中 `max-w-* mx-auto`
+
+---
+
+## 十一、FastAPI 端点避免冲突
+
+suite-market 和 auth-center 后端都是 FastAPI，默认暴露 `/docs`（Swagger UI）、`/redoc`、`/openapi.json`。
+
+如果前端有同名路由（如文档模块的 `/docs`），会与 FastAPI 默认端点冲突。
+
+**必须：**
+
+```python
+app = FastAPI(
+    docs_url="/api/docs",         # 改 /docs → /api/docs
+    redoc_url="/api/redoc",       # 改 /redoc → /api/redoc
+    openapi_url="/api/openapi.json"  # 改 /openapi.json → /api/openapi.json
+)
+```
+
+---
+
+## 十二、Header/Footer 统一
+
+- Header：统一使用 `Navbar.tsx`（components/ 下），不单独在各页面重复
+- Footer：全局底部，包含 ICP 备案号、公安备案号、版权信息
+- Header 和 Footer 在全局 `layout.tsx` 中加载，页面层不覆盖
+
+---
+
+## 十三、组件命名
+
+| 类型 | 命名规则 | 示例 |
+|------|---------|------|
+| 页面组件（app/） | PascalCase + Page 后缀 | `DocsPage`, `SuiteDetailPage` |
+| 布局（layout） | 文件名固定 `layout.tsx` | 不导出命名函数 |
+| 通用组件 | PascalCase | `LoginPrompt`, `SuiteCard` |
+| 工具函数 | camelCase | `fetchDocuments`, `formatDate` |
+| API 函数 | camelCase | `fetchDocuments`, `createDocument` |
+
+---
+
+## 六、认证
+
+- header 右上角只有一个「登录」按钮
+- 登录跳转到 `auth.mercator.cn`
+- 登录后通过 JWT cookie 回传
+- API 调用由 `api.ts` 中的 axios 实例统一处理（interceptor 自动附带 token）
+
+**不允许：**
+- 页面内部额外加「登录」按钮或链接
+- 手动拼写 `Authorization` header
+- 直接调用 `fetch`
+
+---
+
+## 七、样式
+
+- 使用 Tailwind CSS
+- 基础样式在 `globals.css` 中定义
+- 组件样式使用 Tailwind class，不单独写 CSS 文件
+- 不使用 CSS Modules 或 styled-components
+
+---
+
+## 八、落地方式
+
+1. 此文档纳入 `SuiteHub/agent-profiles/suites-help/` 作为平台规范
+2. 新建前端页面时，开发者对照此文档逐一检查
+3. Code Review 时以此文档为标准
+4. 后续如有不合理之处，更新此文档（不改代码，改规矩）
@@ -0,0 +1,206 @@
+# Mercator 云平台 & AgentGIS 平台 使用入门
+
+> 📝 本文档面向 **套件使用者**（非技术人员），帮助您快速了解平台全貌和日常使用方式。
+
+---
+
+## 一、两个平台的关系
+
+用一个比喻来理解：
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│               Mercator 云平台（线上服务）                     │
+│                                                              │
+│   你在这里：                                                   │
+│   · 登录账号（auth.mercator.cn）                              │
+│   · 浏览套件（suites.mercator.cn）                            │
+│   · 交流反馈（discussions.mercator.cn）                       │
+│                                                              │
+│          │                                                   │
+│          ▼ 查询套件、下发任务                                 │
+│                                                              │
+│   ┌──────────────────────────────────────────────────┐       │
+│   │        AgentGIS 平台（本地工具）                   │       │
+│   │                                                  │       │
+│   │   在你的电脑上运行：                               │       │
+│   │   · GIS Actions（执行引擎）                       │       │
+│   │   · GIS Base（地理信息工具箱）                    │       │
+│   │                                                  │       │
+│   │   📍 数据始终留在你的电脑，不上传云端              │       │
+│   └──────────────────────────────────────────────────┘       │
+│                                                              │
+└──────────────────────────────────────────────────────────────┘
+```
+
+**一句话：** Mercator 云平台是"超市"，AgentGIS 是"厨房"。你在超市选好菜（套件），在自家厨房（本地电脑）做菜。食材（你的数据）从不出厨房。
+
+---
+
+## 二、Mercator 云平台 — 你每天在网页上用的服务
+
+### 2.1 统一认证中心（auth.mercator.cn）
+
+**用来做什么：** 登录所有 Mercator 服务的统一入口。
+
+**你的用法：**
+1. 打开 https://auth.mercator.cn/login
+2. 用企业微信扫码，或用账号密码登录
+3. 登录后自动跳转到对应的服务（套件市场、讨论板等）
+
+**特别说明：**
+- 一套账号通吃所有服务
+- 你可以随时在后台创建自己的 API Key（类似"程序密码"），供自动化脚本使用
+
+### 2.2 专家套件市场（suites.mercator.cn）
+
+**用来做什么：** 浏览、查找、使用各类 GIS 套件的在线商店。
+
+**你的用法：**
+1. 进入首页 → 浏览套件列表
+2. 按分类筛选（自然资源、土地利用、测绘等）
+3. 点击套件 → 查看详情、参数说明、版本历史
+4. 找到需要的套件后，记下套件 ID 或名称
+5. 在本地通过 `agc` 命令运行它
+
+**界面预览：**
+
+| 区域 | 内容 |
+|------|------|
+| 顶部导航 | 浏览套件、帮助文档 |
+| 左侧分类 | 按业务分类筛选 |
+| 中间列表 | 套件卡片（名称、作者、版本、简介） |
+| 详情页 | 参数说明、版本日志 |
+
+### 2.3 Discussions 用户交流平台（discussions.mercator.cn）
+
+**用来做什么：** 用户之间交流问题、提建议、讨论用法的社区。
+
+**你的用法：**
+1. 浏览已有话题 → 看看别人遇到什么问题
+2. 搜索关键词 → 查找已有的解答
+3. 创建新话题 → 提问、建议、报 Bug
+4. 回复参与 → 帮助其他用户
+
+**话题类型：**
+
+| 标签 | 说明 |
+|------|------|
+| 🐛 bug | 报告平台或套件的问题 |
+| ✨ feature | 提功能建议 |
+| ❓ question | 提问求助 |
+| 💬 discussion | 一般讨论 |
+| 📢 announcement | 管理员发布的通知 |
+
+---
+
+## 三、AgentGIS 平台 — 你电脑上运行的工具
+
+### 3.1 GIS Actions（`agc` 命令）
+
+**是什么：** 一个安装在你电脑上的命令行工具（`agc`），负责执行套件。
+
+**它做什么：**
+- 从 Mercator 云平台查询套件信息
+- 在本地创建一个执行环境（Linux：Docker 容器 / Windows：本机进程）
+- 在该环境中执行套件规定的步骤
+- 执行完成后自动清理临时文件
+
+**你的用法：**
+```bash
+# 1. 运行一个套件
+agc run /路径/到/输出目录 --suite-id <套件ID> --input 参数名=值
+
+# 2. 查看运行状态
+agc status
+
+# 3. 列出已安装的套件
+agc list
+```
+
+**数据安全：**
+- ✅ **你的数据永远留在本地**，不上传云端
+- ✅ 套件脚本在隔离的 Linux Docker 容器或 Windows 本机进程中执行
+ Docker 容器中运行
+- ✅ 执行完毕后临时文件自动清理
+- ✅ 只有最终成果文件保留在输出目录
+
+### 3.2 GIS Base（基础环境）
+
+**是什么：** 预装了 GIS 工具（GDAL、Python、Shapely、GeoPandas 等）的 Docker 镜像。
+
+**你不需要直接操作它。** 当你运行 `agc run` 时，GIS Actions 会自动下载或使用本地缓存的基础镜像来执行套件。
+
+---
+
+> 💬 **使用中遇到任何问题？** 前往 [discussions.mercator.cn](https://discussions.mercator.cn/) 发话题，平台管理员和其他用户会帮你解答。
+
+## 四、从零开始：一个任务的全流程
+
+假设你是一名地理信息技术服务从业人员，需要做"土地整治竣工结算"：
+
+```
+第 1 步：打开 auth.mercator.cn → 登录
+           ↓
+第 2 步：打开 suites.mercator.cn → 搜索"土地整治竣工结算"
+           ↓
+第 3 步：查看套件详情 → 了解需要哪些输入参数
+           ↓
+第 4 步：打开终端，运行命令：
+           agc run ./output --suite-id xxxx-xxxx --input range_path=./范围.shp
+           ↓
+第 5 步：GIS Actions 自动执行：
+           ├── 下载套件脚本包
+           ├── 启动 Docker 容器（含 GIS 工具）
+           ├── 运行脚本，处理你的数据
+           └── 生成成果文件到 ./output/ 目录
+           ↓
+第 6 步：在 ./output/ 中拿到结果文件
+```
+
+---
+
+## 五、常见问题
+
+### Q: 我需要安装什么软件？
+**A:** 只需要两样：Docker 和 `agc` 命令行工具。安装步骤见帮助文档。
+
+### Q: 我的数据安全吗？
+**A:** 绝对安全。你的数据全程在本地处理，不上传任何文件到云端。只有套件的运行日志回传到服务器（不含原始数据）。
+
+### Q: 套件不会用怎么办？
+**A:** 
+- 在套件市场查看套件详情中的参数说明
+- 在 Discussions 搜索或提问
+- 在 Discussions 提交功能建议或 Bug 报告
+
+### Q: 我可以自己发布套件吗？
+**A:** 可以。需要申请开发者角色，在 Auth Center 后台创建 API Key，然后通过 API 发布。具体步骤见开发指南。
+
+---
+
+## 六、快速参考
+
+### 网址
+
+| 服务 | 网址 |
+|------|------|
+| 登录入口 | https://auth.mercator.cn |
+| 套件市场 | https://suites.mercator.cn |
+| 用户交流 | https://discussions.mercator.cn/ |
+| 首页 | https://www.mercator.cn |
+
+### agc 常用命令
+
+| 命令 | 说明 |
+|------|------|
+| `agc run <输出目录> --suite-id <ID> --input key=val` | 运行套件 |
+| `agc status` | 查看运行状态 |
+| `agc list` | 列出可用的套件 |
+| `agc config set api_key <你的API Key>` | 配置认证 |
+
+### 推荐工作流
+
+```
+登录云平台 → 查找套件 → 本地运行 → 获取结果 → 有疑问去 Discussions
+```
@@ -0,0 +1,464 @@
+# Mercator 云平台 & AgentGIS 培训文案
+
+> 基于 SuiteHub/agent-profiles 文档及 2026-07-16 实际系统验证。
+> 预计 32 页，每页标题 + 要点 = 一张 PPT。
+
+---
+
+## 第一部分：平台概述（2 页）
+
+### 第 1 页：Mercator 云平台是什么
+
+- 企业级智能自动化云平台
+- 核心定位：**AI 调度 + 本地执行 + 全链路安全**
+- 三个核心子系统：
+  - **统一认证中心**（auth.mercator.cn）— 你是谁
+  - **专家套件市场**（suites.mercator.cn）— 你能做什么
+  - **用户交流中心**（discussions.mercator.cn）— 怎么反馈
+- AgentGIS = GIS 能力扩展层，面向地理空间数据处理
+
+### 第 2 页：平台总体架构
+
+- 云端 + 本地两层架构
+- **云端**：认证、市场、讨论区、代码托管、脚本包分发
+- **本地**：GIS Actions 执行引擎，下载脚本包后在本地运行（Linux Docker / Windows 本机进程）
+- **核心原则：数据永不离开本地**
+- 用户数据始终在自己的机器上处理，不上传云端
+- Linux：Docker 容器隔离执行 / Windows：本机进程执行
+- 云端只做管理、分发、协作
+
+---
+
+## 第二部分：统一认证中心（5 页）
+
+### 第 3 页：Auth Center 是什么
+
+- 域名：auth.mercator.cn
+- 职责：统一身份认证，所有子系统的入口
+- 一句话：**一次登录，通行全平台**
+- 支持三种登录方式：
+  - 密码登录
+  - 企业微信扫码登录
+  - 忘记密码 → 邮箱重置
+
+### 第 4 页：登录与注册
+
+- **密码登录**：输入用户名/邮箱 + 密码
+- **企业微信扫码**：首次扫码自动创建账户，绑定企业微信身份
+- **注册**：自助注册，需企业邮箱验证（@mercator.cn）
+- **忘记密码**：通过绑定邮箱发送重置链接
+- 支持 MFA（多因素认证）：TOTP 动态码
+
+### 第 5 页：API Key 管理
+
+- 什么场景用：AI Agent（如 OpenClaw）调用平台 API
+- API Key 格式：`mk_` 开头，46 位字符
+- 获取方式：登录 Auth Center → API Key 管理 → 创建
+- 可设置过期时间（1-365 天，默认 90 天）
+- 可随时吊销
+- **安全提醒**：API Key 创建后只显示一次，请立即保存
+
+### 第 6 页：OAuth2 / OIDC 服务端
+
+- Auth Center 内置完整的 OAuth2 和 OpenID Connect 服务端
+- 支持授权码流程（Authorization Code）+ PKCE
+- 支持 Refresh Token 自动续期
+- RS256 签名，JWKS 公开密钥
+- 企业微信为 OIDC 身份源
+- 可注册第三方 OAuth Client，实现 SSO
+
+### 第 7 页：个人信息管理
+
+- 个人资料：修改昵称、邮箱、手机号、地址
+- 头像上传：支持 JPG/PNG/WebP/GIF，最大 500KB
+- 会话管理：查看当前登录设备，可远程登出
+- 修改密码
+
+---
+
+## 第三部分：专家套件市场（8 页）
+
+### 第 8 页：Suite Market 是什么
+
+- 域名：suites.mercator.cn
+- 职责：GIS 套件的发现、发布、版本管理
+- 面向两类用户：
+  - **套件使用者**：浏览、选择、执行套件
+  - **套件开发者**：开发、测试、发布套件
+- 公开可访问，认证只约束操作（创建/执行/发布）
+
+### 第 9 页：浏览与搜索套件
+
+- **套件列表**：展示所有已发布套件
+  - 名称、描述、分类、版本号、作者
+- **搜索栏**：关键词搜索名称和描述
+- **分类筛选**：按业务分类过滤（如土地整治、数据转换等）
+- **状态筛选**：按发布状态筛选
+
+### 第 10 页：套件详情
+
+- 点击套件名称进入详情页
+- 展示内容：
+  - **详细描述**：套件的完整功能说明
+  - **输入参数**：需要用户提供的参数列表（名称、类型、是否必填、默认值）
+  - **输出结果**：执行完成后能获取的结果说明
+  - **版本选择**：可选择指定版本执行
+- 快速执行命令：一键复制 `agc run` 命令
+
+### 第 11 页：选择套件的方法
+
+- 看用途：描述是否匹配你的需求？
+- 看输入：需要提供的文件或参数是否容易获取？
+- 看输出：结果是否符合预期？
+- 看不明白的套件就不选，换一个
+- 先查市场，再动手——避免重复造轮子
+
+### 第 12 页：套件的结构
+
+- 一个套件 = workflow.yaml + scripts/ 目录 + [可选] demo-data/ 目录
+  - workflow.yaml：工作流定义
+  - scripts/：Python 脚本文件
+  - demo-data/（可选）：Playground 在线演示用的样例数据
+    - 有 demo-data/ 的套件可在 agentgis.cn Playground 中在线试用
+    - 没有 demo-data/ 的套件只能通过 agc run 本地执行
+- workflow.yaml 定义了：
+  - **name**：套件名称
+  - **description**：功能描述
+  - **version**：版本号
+  - **slug**：英文包名（可选）
+  - **params**：输入参数声明
+  - **base_image**：运行镜像（默认 gis-base:latest）
+  - **steps**：执行步骤列表
+- scripts/：包含实际的 Python 脚本文件
+
+### 第 13 页：工作流（Workflow）机制
+
+- Steps 定义执行流水线
+- 引用语法：
+  - `$params.xxx`：引用用户输入的参数
+  - `$steps.step_id.output_name`：引用前一步骤的输出
+- 步骤依赖：`depends_on` 定义执行顺序
+- 所有步骤共享 `/tmp/output` 工作目录
+- 示例：三步流水线
+  ```
+  Step 1: 空间分析（flow_dir.py）→ 输出流向栅格
+  Step 2: 汇流累积（accumulation.py）→ 依赖 Step 1
+  Step 3: 河网提取（stream_extract.py）→ 依赖 Step 2
+  ```
+
+### 第 14 页：发布套件（面向开发者）
+
+- 前置条件：
+  - API Key（auth.mercator.cn 获取）
+  - Gitea Token（git.mercator.cn 获取，需 write:packages 权限）
+- 发布方式：
+  - **文件上传**：`POST /publish/upload`，上传 tar.gz/zip
+  - **Git 仓库**：`POST /publish`，从 Git 仓库拉取
+- 发布流程自动完成：
+  - 合规检测 → 参数校验 → 打包脚本 → 上传 Gitea Packages → 注册到数据库
+  - 包含 demo-data/ 目录的套件自动支持 Playground 在线演示
+
+### 第 15 页：版本管理
+
+- 每次发布自动保存历史版本快照
+- 版本记录包含：version、workflow 定义、package_url、description、category、tags
+- 用户可通过 `--version x.x.x` 指定执行历史版本
+- API 支持：`GET /api/v1/suites/{id}?version=1.0.0`
+- 包命名规则：中文自动转拼音，或通过 slug 字段手动指定英文名
+
+---
+
+## 第四部分：用户交流中心（3 页）
+
+### 第 16 页：Discussions 是什么
+
+- 域名：discussions.mercator.cn
+- 职责：用户交流、反馈、问题讨论
+- 功能：
+  - 创建话题
+  - 评论互动
+  - 标签分类
+  - 话题关闭/重开
+
+### 第 17 页：话题与标签
+
+- 预置标签体系：
+  - **bug**（红色）：缺陷报告
+  - **feature**（绿色）：功能请求
+  - **question**（蓝色）：使用疑问
+  - **discussion**（紫色）：一般讨论
+  - **announcement**（橙色）：公告
+  - **suggestion**（青色）：改进建议
+  - **auto-report**（灰色）：系统自动生成的报告
+- 标签帮助快速筛选和分类话题
+
+### 第 18 页：错误反馈机制
+
+- gis-actions 执行失败时，会自动发话题到 Discussions（需配置 API Key）
+- 自动生成的话题包含：
+  - 套件名称和版本号
+  - 错误摘要
+  - 脱敏后的日志
+  - 标签：bug + auto-report
+- 好处：
+  - 开发者第一时间知道套件出问题
+  - 其他用户可能遇到相同问题可以找到解决方案
+  - 可关闭话题表示已修复
+
+---
+
+## 第五部分：GIS Actions 本地执行引擎（6 页）
+
+### 第 19 页：GIS Actions 是什么
+
+- 本地执行器
+  - **Linux**：安装在自己的机器上（deb 包）
+  - **Windows**：安装 agc.exe（zip 包）
+- 命令行工具：`agc`
+- 完整命令集：
+  - `agc config` — 配置 API Key 和市场地址
+  - `agc run` — 执行套件（支持 `--watch` 实时输出、`--resume` 续跑）
+  - `agc search / info` — 搜索和查看套件
+  - `agc doctor` — 环境诊断
+  - `agc logs / cache` — 运行历史和缓存管理
+  - `agc mcp` — AI Agent 集成入口（MCP 协议）
+  - `agc self-update` — 自动升级
+- 职责：从套件市场下载脚本包 → 在本地执行（Linux Docker / Windows 本机）→ 返回结果
+- 安装方式：
+  **Linux：**
+  ```bash
+  curl -sLO https://packages.mercator.cn/public/gis-actions/latest.deb
+  sudo dpkg -i latest.deb
+  ```
+  **Windows：**
+  1. 下载 latest-windows.zip
+  2. 解压到 %LOCALAPPDATA%\AgentGIS\gis-actions\
+  3. 加入 PATH
+  4. 验证：`agc --help`
+
+### 第 20 页：环境要求
+
+**Linux：**
+- 操作系统：Debian / Ubuntu
+- Docker Engine
+- Python 3.10+
+- 首次运行时自动下载 gis-base 镜像（约 465MB）
+
+**Windows：**
+- 操作系统：Windows 10/11
+- ArcMap 10.8（arcpy 步骤需要）
+- 无需 Docker
+
+**通用：**
+- 网络：需要能访问 suites.mercator.cn 和 git.mercator.cn
+
+### 第 21 页：配置 API Key
+
+- 为什么需要 API Key：用于认证身份、调取套件信息和下载脚本包
+- 获取方式：登录 auth.mercator.cn → API Key 管理 → 创建
+- 配置方式：
+  ```bash
+  agc config set api-key mk_xxxxxxxxxxxxxxxxxxxx
+  ```
+- 查看配置：`agc config list`
+- 切换市场地址：`agc config set market-url <url>`
+- 所有配置保存在 `~/.config/gis-actions/config.toml`
+
+### 第 22 页：执行套件
+
+- 基本命令：
+  ```bash
+  agc run /tmp/output --suite-id <suite-id> --input key=value
+  agc run /tmp/output --suite-id <suite-id> --input key=value --watch   # 实时输出
+  agc run /tmp/output --suite-id <suite-id> --input key=value --resume  # 断点续跑
+  ```
+- 其他命令：
+  | 命令 | 用途 |
+  |------|------|
+  | `agc search <query>` | 搜索套件 |
+  | `agc info <suite-id>` | 套件详情 |
+  | `agc logs` | 历史记录 |
+  | `agc cache list / clean` | 缓存管理 |
+  | `agc mcp` | AI Agent 集成（MCP 协议） |
+- 执行流程：
+  1. 从市场查询套件的脚本包地址（package_url）
+  2. 检查本地缓存，命中则跳过下载
+  3. 从 Gitea Packages 下载脚本包（自动缓存）
+  4. 解压并读取 workflow.yaml
+  5. 按 depends_on 拓扑顺序执行各步骤
+  6. 每步按 runtime 执行：
+     - runtime: docker → Docker 容器（gis-base 镜像）
+     - runtime: python3 → 本地 subprocess
+     - runtime: arcpy → 系统 arcpy（Windows only）
+  7. 结果写入本地工作目录的 `_step_outputs/` 下
+  8. 清理下载的脚本包和临时文件
+
+### 第 23 页：数据安全
+
+- **数据永不离开本地**
+- 输入文件始终在用户自己的机器上
+- 数据处理在本地完成（Linux Docker 容器 / Windows 本机进程）
+- 不上传到云端、不经过平台服务器
+- 执行完成后脚本包自动清理
+- 用户数据和结果文件始终保留在本地
+
+### 第 24 页：错误处理
+
+- 执行失败怎么办：
+  1. 查看控制台错误信息
+  2. 检查输入文件路径是否正确
+  3. 运行 `agc doctor` 一键诊断环境：
+     - Linux: Docker 是否运行 / Windows: agc.exe 是否在 PATH
+     - 镜像是否存在（Linux）
+     - API Key 是否有效
+     - 能否连通套件市场
+  4. 查看失败记录：`agc logs --status failed`
+  5. 确认已升级到最新版：`agc self-update`（Linux: deb / Windows: zip 自动解压）
+- 自动报告失败：已配置 API Key 的情况下，执行失败会自动发帖到 Discussions
+- 如果怀疑是套件本身的 Bug：
+  - 配置 API Key 后，自动反馈到讨论区
+  - 或手动访问 discussions.mercator.cn 发帖
+
+---
+
+## 第六部分：GIS Base 基础镜像（3 页）
+
+### 第 25 页：GIS Base 是什么
+
+- **Linux 模式**：所有 Docker 套件的运行基石
+  - 预装完整 GIS 工具链的 Linux Docker 镜像
+  - 永久存储在用户本地，所有套件共享
+  - 镜像名：`gis-base:latest`，约 465MB
+- **Windows 模式**：不需要 gis-base 镜像
+  - 使用本地 arcpy / Python 环境
+  - 依赖 ArcMap 10.8 的 arcpy 环境
+
+### 第 26 页：预装环境
+
+- 系统级：
+  - GDAL 命令行工具
+  - mdbtools（Access 数据库读取）
+  - libgeos、libproj 等 GIS 底层库
+- Python 3.11：
+  - 核心 GIS：numpy、shapely、pyproj、fiona、rasterio、geopandas
+  - 数据处理：pandas、scipy、openpyxl、xlrd、xlsxwriter
+  - 可视化：matplotlib
+  - 文档生成：python-docx、reportlab
+  - 工具库：Pillow、requests、Jinja2
+
+### 第 27 页：获取方式
+
+- 安装 gis-actions 时自动下载
+- 也可手动拉取：
+  ```bash
+  docker pull registry.mercator.cn/library/gis-base:latest
+  ```
+- 离线环境：在可联网机器上导出镜像
+  ```bash
+  docker save gis-base:latest | gzip > gis-base.tar.gz
+  ```
+  然后在目标机器
+  ```bash
+  docker load -i gis-base.tar.gz
+  ```
+
+### 第 28 页：AI Agent 集成（MCP 协议）
+
+- GIS Actions v3.1 起支持 MCP（Model Context Protocol）
+- AI Agent（Claude / DeepSeek / 本地 Agent）可自动发现和调用 GIS 工具
+- 启动方式：
+  ```bash
+  agc mcp                            # stdio 模式（默认）
+  agc mcp --transport sse --port 8080  # SSE 模式（HTTP）
+  ```
+- AI Agent 无需关心 Docker、镜像、套件包——只需调用工具名和参数
+
+### 第 29 页：包签名与安全
+
+- 套件包发布时使用 Ed25519 签名
+- 下载后自动验证签名，防止篡改
+- 手动验签：`python3 -m gis_actions.signing verify <file> <sig>`
+
+- 安装 gis-actions 时自动下载
+- 手动下载：
+  ```bash
+  curl -sLO https://packages.mercator.cn/public/gis-base/latest.tar.gz
+  docker load -i latest.tar.gz
+  ```
+- 镜像存储在 MinIO 公共存储上
+- 所有套件脚本在此镜像中隔离执行
+
+---
+
+## 第八部分：AI Agent 集成与安全（2 页）
+
+> 新增：MCP 协议适配 + 包签名验证
+
+---
+
+### 第 28 页：AI Agent 集成（MCP 协议）
+
+- GIS Actions v3.1 起支持 MCP（Model Context Protocol）
+- AI Agent（Claude / DeepSeek / 本地 Agent）可自动发现和调用 GIS 工具
+- 启动方式：
+  ```bash
+  agc mcp                            # stdio 模式（默认）
+  agc mcp --transport sse --port 8080  # SSE 模式（HTTP）
+  ```
+- AI Agent 无需关心 Docker、镜像、套件包——只需调用工具名和参数
+
+### 第 29 页：包签名与安全
+
+- 套件包发布时使用 Ed25519 签名
+- 下载后自动验证签名，防止篡改
+- 手动验签：`python3 -m gis_actions.signing verify <file> <sig>`
+
+---
+
+## 第九部分：各系统关系与生态（3 页）
+
+### 第 30 页：端到端工作流程
+
+```
+用户 → Auth Center 登录/获取 API Key
+    → 浏览 Suite Market → 选择合适的套件（关注平台标签）
+    → 复制 agc run 命令 → 在本地终端执行
+    → GIS Actions 下载脚本包 → 执行（Linux Docker / Windows 本机）→ 得到结果
+    → 出问题 → Discussions 反馈 → 开发者收到 → 修复 → 发布新版本
+```
+
+### 第 31 页：系统关系图
+
+```
+┌─────────────────────────────────────────────────┐
+│                  云端平台                         │
+│                                                   │
+│  Auth Center ◄── Suite Market ◄── Discussions    │
+│     │                  │                           │
+│     │                  ▼                           │
+│     │          Gitea Packages                      │
+│     │        （脚本包 + 基础镜像）                  │
+│     └──────────────────│───────────────────────────┘
+                        │ 下载
+                        ▼
+┌─────────────────────────────────────────────────┐
+│                  本地用户                         │
+│                                                   │
+│  gis-actions (agc)                                │
+│  ├─ Linux: docker run gis-base → 脚本执行         │
+│  └─ Windows: subprocess(arcpy/python3) → 执行     │
+└─────────────────────────────────────────────────┘
+```
+
+### 第 32 页：总结
+
+- **Mercator 云平台**：认证 + 市场 + 讨论区，构成完整生态
+- **AgentGIS**：将 GIS 能力扩展到本地，数据安全有保障
+- **GIS Actions**：一键安装（Linux deb / Windows zip），即装即用
+- **GIS Base**：Linux Docker 模式的 GIS 工具箱 / Windows 使用本地 arcpy
+- **核心价值**：数据不离开本地，算法安全交付，身份贯穿全域
+
+---
+
+> 本文案基于 SuiteHub/agent-profiles 文档及 2026-07-16 实际系统部署验证编写。
+
@@ -1,111 +1,90 @@
 # Workflow 规范

-## 文件位置
+## 概述

-套件根目录下的 `workflow.yaml`。
+`workflow.yaml` 定义套件的步骤、参数和执行流程。

-## 顶层字段
+## 文件结构
+
+```yaml
+name: 套件名称
+description: 套件功能描述
+version: 1.0.0
+author: 作者名
+tags: [标签1, 标签2]
+platform: all
+category: 业务分类（如：土地整治）
+
+params:
+  input_path:
+    type: string
+    required: true
+    desc: 输入文件路径
+  buffer_distance:
+    type: number
+    default: 100
+    desc: 缓冲区半径（米）
+
+base_image: gis-base:latest
+
+env:
+  LOG_LEVEL: INFO
+
+steps:
+  - id: step1
+    name: 步骤名称
+    type: python
+    runtime: python3
+    script_id: run
+    params:
+      input: $params.input_path
+      distance: $params.buffer_distance
+```
+
+## 字段说明

 | 字段 | 必填 | 说明 |
 |------|------|------|
-| `name` | 是 | 套件名称 |
-| `description` | 否 | 描述 |
-| `version` | 否 | 版本号，默认 1.0.0 |
-| `category` | 否 | 分类标签 |
-| `tags` | 否 | 标签列表 |
-| `params` | 是 | 输入参数的 JSON Schema |
-| `output_schema` | 否 | 输出结果的结构定义 |
-| `steps` | 是 | 执行步骤列表 |
-| `resolved_params` | 是 | 参数解析后的默认值 |
+| `name` | ✅ | 套件名称 |
+| `description` | ✅ | 套件功能描述 |
+| `version` | ✅ | 语义化版本号 |
+| `slug` | ❌ | 英文包名。不传则从 name 自动转拼音 |
+| `params` | ❌ | 参数声明（供用户查看） |
+| `base_image` | ❌ | Docker 镜像，默认 `gis-base:latest` |
+| `steps` | ✅ | 步骤列表，至少 1 步 |

-## 参数声明（params）
+### steps 字段

-使用 JSON Schema 格式：
-
-```yaml
-params:
-  type: object
-  required:
-    - input_path
-  properties:
-    input_path:
-      type: string
-      description: 输入文件路径
-    threshold:
-      type: number
-      default: 0.5
-      description: 阈值
-```
-
-### 参数类型
-
-| 类型 | 说明 | 示例 |
+| 字段 | 必填 | 说明 |
 |------|------|------|
-| `string` | 文本或文件路径 | `/data/input.shp` |
-| `number` | 浮点数 | `0.5` |
-| `integer` | 整数 | `100` |
-| `boolean` | 布尔值 | `true` |
+| `id` | ✅ | 步骤唯一 ID |
+| `name` | ❌ | 步骤显示名称 |
+| `type` | ✅ | 步骤类型，当前固定为 `python` |
+| `script_id` | ✅ | 脚本 ID（对应 scripts/ 下的 .py 文件名，不含扩展名） |
+| `params` | ❌ | 步骤参数，值中使用 `$params.xxx` 引用用户输入 |
+| `depends_on` | ❌ | 依赖的步骤 ID 列表，控制执行顺序 |

-## 步骤定义（steps）
+## 参数传递
+
+步骤参数通过 `$params.xxx` 语法引用用户输入：

 ```yaml
-nodes:
-  - id: my-step          # 步骤 ID，唯一
-    name: 我的步骤        # 步骤名称
-    script_id: run        # 脚本标识（不是 script: run.py）
 params:
-      input: "${{inputs.input_path}}"   # 双花括号语法
+  input: $params.input_path     # 引用用户的 input_path 参数
+  distance: $params.buffer_distance  # 引用用户的 buffer_distance 参数
 ```

-### 常见错误
+引擎会自动：
+1. 将用户提供的文件路径复制到工作目录
+2. 替换路径为容器内可访问的路径（`/tmp/output/文件名`）
+3. shapefile 自动复制配套文件（.shx/.dbf/.prj）

-| ❌ 错误写法 | ✅ 正确写法 | 原因 |
-|-----------|-----------|------|
-| `script: run.py` | `script_id: run` | 执行器读的是 `script_id` |
-| `params_mapping: {...}` | `params: {...}` | 字段名是 `params` |
-| `$inputs.xxx` | `${{inputs.xxx}}` | 双花括号语法 |
+## 执行顺序

-## 文件共享
+- 无 `depends_on` 的步骤并行执行
+- 有 `depends_on` 的步骤在依赖步骤完成后执行
+- 默认串行（`depends_on` 为空时按列表顺序执行）

-所有步骤共享 `/tmp/output` 目录。Step 1 写入的文件，Step 2 可以直接读取：
+## 步骤输出

-```python
-# Step 1：写文件
-with open("/tmp/output/result.json", "w") as f:
-    json.dump(data, f)
-
-# Step 2：读文件
-with open("/tmp/output/result.json") as f:
-    data = json.load(f)
-```
-
-每个步骤也有独立的 `/tmp/step_output` 目录。
-
-## 脚本约定
-
-脚本通过 `PARAMS_FILE` 环境变量获取参数（默认 `/tmp/params.json`），结果通过 stdout 输出 JSON：
-
-```python
-import json, os
-
-params_file = os.environ.get("PARAMS_FILE", "/tmp/params.json")
-with open(params_file) as f:
-    params = json.load(f)
-
-# 处理逻辑...
-result = {"status": "ok", "value": 42}
-print(json.dumps(result))
-```
-
-## resolved_params
-
-提供参数解析后的默认值，执行器直接使用这些值：
-
-```yaml
-resolved_params:
-  - step_index: 0
-    step_name: 我的步骤
-    params:
-      input_path: "/data/input.shp"
-      threshold: 0.5
-```
+每个步骤执行完成后，脚本向 stdout 输出 JSON 结果。步骤间的数据通过 `/tmp/output/` 目录共享。
@@ -5,59 +5,50 @@
 - 一个 API Key（从 https://auth.mercator.cn 获取）
 - 套件目录包含 `workflow.yaml` 和 `scripts/`

-## 一、使用 CLI 发布（推荐）
+## 通过 API 发布

 ```bash
-# 安装 CLI
-pip install https://git.mercator.cn/SuiteHub/agentgis-cli/raw/branch/main/dist/agentgis_cli-0.1.0-py3-none-any.whl
-
-# 配置 API Key
-agc config set api-key mk_xxxxxxxxxxxxx
-
-# 发布
-agc publish ./my-suite
-```
-
-## 二、手动发布
-
-### 1. 打包
-
-```bash
-cd my-suite
-tar czf scripts.tar.gz workflow.yaml scripts/
-```
-
-### 2. 上传到包存储
-
-```bash
-curl -X PUT \
+curl -X POST https://suites.mercator.cn/api/v1/publish/upload \
  -H "Authorization: Bearer mk_xxxx" \
-  -F "file=@scripts.tar.gz" \
-  https://suites.mercator.cn/api/v1/publish/upload
+  -F "file=@my-suite.tar.gz" \
+  -F "platform=all"    # linux / windows / all
+
+> 发布后套件包会上传到 https://git.mercator.cn/SuiteHub 组织。
 ```

-### 3. 注册套件
+其中 `my-suite.tar.gz` 包含：

-```bash
-curl -X POST https://suites.mercator.cn/api/v1/suites \
-  -H "Authorization: Bearer mk_xxxx" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "name": "my-suite",
-    "description": "我的套件",
-    "version": "1.0.0",
-    "workflow": { ... },
-    "package_url": "https://..."
-  }'
+```
+my-suite/
+├── workflow.yaml
+└── scripts/
+    └── run.py
 ```

-## 合规检测
+`workflow.yaml` 示例：

-发布时自动检测：
+```yaml
+platform: all
+name: my-suite
+description: 我的套件
+version: 1.0.0
+author: 作者
+tags: [gis]
+category: general

- `workflow.yaml` 格式是否正确
- 参数声明是否完整
- 脚本文件是否存在
- 参数类型是否匹配
+params:
+  input_path:
+    type: string
+    required: true
+    desc: 输入文件路径

-不通过则发布失败，返回具体错误信息。
+base_image: gis-base:latest
+
+steps:
+  - id: step1
+    name: 处理步骤
+    type: python
+    script_id: run
+    params:
+      input_path: $params.input_path
+```
@@ -1,94 +1,34 @@
-# 快速开始 — 开发第一个套件
+# 快速开始

-## 什么是套件
-
-套件（Suite）是平台的可执行单元。一个套件包含：
- **workflow.yaml**：步骤定义（核心）
- **scripts/run.py**：执行脚本
-
-## 第一步：创建套件目录
+## 安装 gis-actions

 ```bash
-mkdir my-first-suite
-cd my-first-suite
+# 下载
+# Linux
+curl -sLO https://packages.mercator.cn/public/gis-actions/latest.deb
+sudo dpkg -i latest.deb
+
+# Windows
+# 下载 latest-windows.zip 解压到 %LOCALAPPDATA%\AgentGIS\gis-actions\ 并加入 PATH
 ```

-## 第二步：编写 workflow.yaml
-
-```yaml
-name: hello-world
-description: 最小示例套件 — 输出用户输入的文本
-version: 1.0.0
-category: utility
-
-params:
-  type: object
-  required:
-    - message
-  properties:
-    message:
-      type: string
-      description: 要输出的文本
-
-steps:
-  - id: say-hello
-    name: 输出信息
-    script_id: run
-    params:
-      message: "${{inputs.message}}"
-
-resolved_params:
-  - step_index: 0
-    step_name: 输出信息
-    params:
-      message: "Hello, AgentGIS!"
-```
-
-## 第三步：编写脚本
+## 浏览套件

 ```bash
-mkdir scripts
+curl -s https://suites.mercator.cn/api/v1/suites | python3 -m json.tool
 ```

-`scripts/run.py`：
+## 执行套件

-```python
-#!/usr/bin/env python3
-import json, os
-
-params_file = os.environ.get("PARAMS_FILE", "/tmp/params.json")
-with open(params_file) as f:
-    params = json.load(f)
-
-message = params.get("message", "Hello!")
-result = {"output": message, "length": len(message)}
-print(json.dumps(result))
-```
-
-## 第四步：测试
+选择一个套件 ID，在本地执行：

 ```bash
-agc run <suite-id> --inputs '{"message": "测试"}'
+agc run /tmp/my-output \
+  --suite-id 2c99a1cb-84a5-42dd-9147-1c8e8f7f2941 \
+  --input bid_xls=/path/to/标段清单.xls \
+  --input points_shp=/path/to/点状工程.shp
 ```

-或直接提交任务到 API：
+## 发布套件

-```bash
-curl -X POST https://suites.mercator.cn/api/v1/task \
-  -H "Authorization: Bearer mk_xxxx" \
-  -d '{"suite_id": "...", "inputs": {"message": "测试"}}'
-```
-
-## 第五步：发布
-
-```bash
-agc publish ./my-first-suite
-```
-
-发布后套件会在市场中展示，其他用户可以搜索和使用。
-
-## 查看已发布的套件
-
-```bash
-agc suites list
-```
+套件通过 Gitea 仓库 + 发布 API 发布，详见 [套件发布指南](../开发者指南/套件发布指南.md)。
@@ -1,54 +1,30 @@
-# 最佳实践
+# 套件开发最佳实践

-## 先查市场，再动手写
-
-开发新套件前，先搜索市场是否已有能复用的套件：
-
-```bash
-agc suites search 缓冲区
-agc suites search 面积计算
-```
-
-能找到现成的就引用它。不需要每次都写自己的脚本。
-
-## 套件命名规范
+## 命名规范

 - 使用英文小写 + 连字符：`buffer-analysis`、`land-use-classification`
 - 名称反映功能：`stream-extraction` 而非 `my-suite-1`
-
-## 参数设计
-
 - 参数名用 snake_case：`input_path`、`buffer_distance`
- 必填参数和可选参数区分清楚
- 提供合理的默认值
- 写清楚描述和单位

-```yaml
-threshold:
-  type: number
-  default: 100
-  description: "河网提取阈值（像元数）"
+## 查市场
+
+开发新套件前，先查询市场是否已有能复用的套件：
+
+```bash
+curl -s https://suites.mercator.cn/api/v1/suites | python3 -c "import json,sys; [print(s['name']) for s in json.load(sys.stdin)]"
 ```

-## 输出设计
+## 模板复用

- 输出 JSON 包含关键字段
- 文件输出路径写清楚
+有现成的 Suite → 在 workflow.yaml 中用 `suite_id` 引用。
+找不到 → 写新脚本 → 发布为新 Suite → 方便后续者复用。

-```python
-result = {
-    "status": "ok",
-    "output_path": "/tmp/output/result.shp",
-    "feature_count": 42
-}
-```
+## 调试技巧

-## 测试
+在 `agc run` 时，注意观察：

-发布前用 `agc run` 测试，确认输入输出正确。
+1. 是否成功解析套件和下载 package_url
+2. 输入文件是否复制到工作目录
+3. 执行输出（Linux Docker 容器内或 Windows 本机进程）

-## 版本迭代
-
- 修复 bug 或小幅改进 → 递增补丁版本（1.0.0 → 1.0.1）
- 新增功能 → 递增次版本（1.0.0 → 1.1.0）
- 重大变更 → 递增主版本（1.0.0 → 2.0.0）
+日志在控制台直接打印，无需额外配置。
@@ -1,55 +1,64 @@
 # 脚本开发指南

-## 脚本约定
+## 脚本执行环境

-`scripts/run.py` 通过环境变量获取参数，通过 stdout 输出 JSON 结果。
+脚本在两种环境中执行：
+1. **Linux Docker 容器**（runtime: docker）—— 隔离执行，gis-base 镜像
+2. **Windows 本机进程**（runtime: python3 / arcpy）—— 直接 subprocess 执行

-### 接收参数
+执行环境由 workflow.yaml 中步骤的 `runtime` 字段决定。下面以 Docker 为例说明容器结构：

-```python
-import json, os
+### 容器内目录结构

-params_file = os.environ.get("PARAMS_FILE", "/tmp/params.json")
-with open(params_file) as f:
-    params = json.load(f)
-
-expression = params.get("expression", "1+1")
-precision = int(params.get("precision", 2))
+```
+/tmp/
+├── scripts/          ← 套件脚本包（只读）
+│   ├── run.py
+│   └── ...其他脚本文件
+├── output/           ← 工作目录（读写，步骤间共享）
+│   ├── 点状工程.shp    ← 用户提供的输入文件
+│   └── computed_data.json
+├── params.json       ← 参数文件（只读）
+└── step_output/      ← 当前步骤输出目录
 ```

-### 输出结果
+### 基础镜像

-```python
-result = {"status": "ok", "result": 42, "output_path": "/tmp/output/result.geojson"}
-print(json.dumps(result))
-```
-
-stdout 的 JSON 会被执行器捕获并作为步骤结果。
-
-### 文件输出
-
- 输出文件写入 `/tmp/output/`（步骤间共享）
- 执行结束后脚本目录自动清理
-
-## 执行环境
-
- **基础镜像**：`registry.mercator.cn/agentgis/gis-base:latest`
- **包含**：Python 3.11, GDAL, Shapely, GeoPandas, Fiona, PyProj, Rasterio, numpy
- **脚本路径**：`/tmp/scripts/run.py`（只读）
- **工作目录**：`/tmp/output`（读写，步骤间共享）
+- **镜像**：`gis-base:latest`（执行 `agc run` 时自动从 Gitea Packages 下载）
+- **内置**：Python 3.11, GDAL, Shapely, GeoPandas, numpy, openpyxl, xlrd, fiona
 - **参数文件**：`/tmp/params.json`
+- **输出目录**：`/tmp/output/`

-## 错误处理
+### 脚本入口

-退出码非 0 表示失败：
+脚本通过命令行参数接收参数：

 ```python
-print(json.dumps({"status": "error", "message": "文件不存在"}))
-sys.exit(1)
+import sys, json
+
+if __name__ == "__main__":
+    params = json.loads(sys.argv[1]) if len(sys.argv) > 1 else {}
+    # params = {"input_path": "/tmp/output/data.shp", ...}
+    result = run(params)
+    print(json.dumps(result, ensure_ascii=False))
 ```

-## 开发建议
+### 依赖管理

-1. **输出明确**：结果 JSON 包含关键信息
-2. **错误友好**：失败信息写清楚原因
-3. **使用 GDAL**：GIS 文件处理优先使用 GDAL 命令行工具
+脚本中缺失的依赖通过运行时 pip 安装：
+
+```python
+import subprocess, sys
+try:
+    import openpyxl
+except ImportError:
+    subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'openpyxl'])
+```
+
+## 输出规范
+
+脚本执行完成后，向 stdout 输出 JSON：
+
+```json
+{"status": "completed", "output_path": "/tmp/output/result.shp"}
+```
@@ -18,7 +18,7 @@ Agent 配置文件在 `suite-user/` 目录下：

 ```
 浏览市场 → 找到套件 → 查看参数说明
-→ 准备本地文件 → 提交执行 → 拿结果
+→ 准备本地文件 → 提交执行（Linux Docker / Windows 本机）→ 拿结果
 ```

 ## 关键原则
@@ -1,6 +1,6 @@
 # 套件开发者 Agent 配置

-如果你是 AI Agent，你的角色是 **套件开发者**——开发和发布 GIS 套件。
+如果你是 AI Agent，你的角色是 **套件开发者**——开发和发布 GIS 套件（需在 workflow.yaml 中设定 `platform` + `runtime`）。

 ## 认知文件

@@ -20,7 +20,7 @@ Agent 配置文件在 `suite-developer/` 目录下：
 1. 分析需求 → 查市场找复用
 2. 设计步骤 → 写 workflow.yaml
 3. 实现脚本 → 测试
-4. 发布 → 迭代
+4. 发布（需在 workflow.yaml 中设定 platform + runtime）→ 迭代
 ```

 ## 关键原则
@@ -1,67 +1,67 @@
-# Hello World 套件
+# Hello, World! 套件示例

-## 完整代码
+一个最简单的套件，演示 workflow.yaml 和脚本结构。

-最小的可工作套件，接收一个文本参数并输出。
+## 文件结构

-### workflow.yaml
-
-```yaml
-name: hello-world
-description: 输出用户输入的文本
-version: 1.0.0
-category: utility
-
-params:
-  type: object
-  required:
-    - message
-  properties:
-    message:
-      type: string
-      description: 要输出的文本
-
-steps:
-  - id: say-hello
-    name: 输出信息
-    script_id: run
-    params:
-      message: "${{inputs.message}}"
-
-resolved_params:
-  - step_index: 0
-    step_name: 输出信息
-    params:
-      message: "Hello, AgentGIS!"
+```
+hello-world/
+├── workflow.yaml
+└── scripts/
+    └── run.py
 ```

-### scripts/run.py
+## workflow.yaml
+
+```yaml
+name: Hello World
+description: 首个 AgentGIS 套件，接收一条消息并打印
+version: 1.0.0
+author: SuiteForge
+platform: all
+tags: [示例, 入门]
+
+params:
+  message:
+    type: string
+    required: true
+    desc: 要打印的消息
+
+base_image: gis-base:latest
+
+steps:
+  - id: hello
+    name: 打印消息
+    runtime: python3
+    script_id: run
+    params:
+      message: $params.message
+```
+
+## scripts/run.py

 ```python
 #!/usr/bin/env python3
-import json, os
+import sys, json

-params_file = os.environ.get("PARAMS_FILE", "/tmp/params.json")
-with open(params_file) as f:
-    params = json.load(f)
-
-message = params.get("message", "Hello!")
-
-result = {
-    "output": message,
-    "length": len(message)
+def run(params):
+    message = params.get("message", "Hello, AgentGIS!")
+    print(f"📢 {message}")
+    return {
+        "status": "completed",
+        "message": message,
    }
-print(json.dumps(result))
+
+if __name__ == "__main__":
+    params = json.loads(sys.argv[1]) if len(sys.argv) > 1 else {}
+    result = run(params)
+    print(json.dumps(result, ensure_ascii=False))
 ```

-## 测试
+## 执行

 ```bash
-# 打包
-tar czf scripts.tar.gz workflow.yaml scripts/
-
-# 发布后执行
-agc run <suite-id> --inputs '{"message": "你好，AgentGIS!"}'
+agc run /tmp/hello-output \
+  --suite-id <your-suite-id> \
+  --input message="你好，AgentGIS!"
 ```
-
-完整代码参考：`SuiteHub/hello-world-suite`
@@ -12,6 +12,7 @@ description: 地块数据批处理 — 生成→验证→缓冲区→对比→
 version: 2.0.0
 category: gis-processing
 tags: [gis, parcel, buffer]
+platform: all

 params:
  type: object
@@ -26,15 +27,13 @@ params:
 steps:
  - id: main
    name: 全流水线
+    type: python
+    runtime: python3
    script_id: process
    params:
-      buffer_distance: "${{inputs.buffer_distance}}"
+      buffer_distance: $params.buffer_distance
+

-resolved_params:
-  - step_index: 0
-    step_name: 全流水线
-    params:
-      buffer_distance: 0.5
 ```

 ## 处理流程
@@ -1,75 +1,86 @@
-# GIS Actions 本地部署指南
+# GIS Actions 本地部署指南（双平台）

 ## 架构

-GIS Actions 是**本地执行器**，从套件市场下载脚本包并在本地 Docker 中运行：
+GIS Actions 是**本地执行器**，从套件市场下载脚本包并在本地运行（Linux Docker / Windows 本机）：

 ```
 用户 / Agent 指定套件 ID
    → gis-actions（本地）
    → 从 Suite Market 下载脚本包
    → 解析 workflow.yaml
-    → docker run gis-base + 脚本
-    → 结果写入本地 /tmp/output/
+    \u2192 runtime: docker -> docker run gis-base / python3/arcpy -> subprocess
+    \u2192 \u7ed3\u679c\u5199\u5165\u672c\u5730\u5de5\u4f5c\u76ee\u5f55
 ```

 ## 环境要求

+**Linux：**
+- Debian / Ubuntu 系统
+- Docker
 - Python 3.10+
- Docker（用于容器化执行）

-## 获取代码
+**Windows：**
+- Windows 10/11
+- ArcMap 10.8（arcpy 步骤需要）
+- 无需 Docker

+## 安装
+
+**Linux：**
 ```bash
-curl -L -o gis-actions.tar.gz "https://git.mercator.cn/api/packages/AgentGIS/generic/gis-actions/v2.4.0/gis-actions.tar.gz"
-tar xzf gis-actions.tar.gz
-cd gis-actions
+curl -sLO https://packages.mercator.cn/public/gis-actions/latest.deb
+sudo dpkg -i latest.deb
 ```
+安装后 `agc` 命令即可用。

-## 配置
+**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`
+
+## 配置（可选）

 ```bash
 # 设置 API Key（从 https://auth.mercator.cn 获取）
 export AGENTGIS_API_KEY=mk_xxxxxxxxxxxxx
 ```

-或创建 `worker.json`：
-
-```json
-{
-  "worker": { "id": "my-machine-001" },
-  "scheduler": { "url": "https://suites.mercator.cn" },
-  "auth": { "api_key": "***" }
-}
-```
-
 ## 运行套件

 ```bash
-# 通过套件 ID 执行（推荐）
-python cli.py run /tmp/workdir --suite-id parcel-analysis --input buffer_distance=0.5
+# 通过套件 ID 执行
+agc run /tmp/output --suite-id <suite-id> --input key=value

-# 或直接指定脚本包地址
-python cli.py run /tmp/workdir --package-url https://git.mercator.cn/.../scripts.tar.gz
+# 示例
+agc run /tmp/output --suite-id 2c99a1cb-84a5-42dd-9147-1c8e8f7f2941 --input buffer_distance=0.5
 ```

-## 目录结构
+## 包结构

+**Linux（deb 包）：**
 ```
-gis-actions/
-├── cli.py                  # 命令行入口（支持 --suite-id / --package-url）
-├── download_and_run.py     # 下载 + 执行核心逻辑
-├── steps_executor.py       # workflow.yaml 步骤执行器
-├── workdir/                # 默认工作目录
-└── packaging/deb/          # DEB 打包结构（待完善）
+/usr/bin/agc                          # CLI 入口
+/usr/share/gis-actions/cli.py         # CLI 逻辑
+/usr/share/gis-actions/download_and_run.py  # 下载+执行
+/usr/share/gis-actions/local_executor.py    # 本地步骤执行器
+/usr/share/gis-actions/steps_executor.py    # Docker 步骤执行器
+```
+
+**Windows（zip 包）：**
+```
+%LOCALAPPDATA%\AgentGIS\gis-actions\agc.exe   # CLI 入口
 ```

 ## 执行流程

-1. `cli.py run` 启动
+1. `agc run` 启动
 2. 解析套件 ID（调用 Suite Market API 获取 package_url）
-3. 下载 scripts.tar.gz → 解压到工作目录
+3. 下载脚本包 → 解压到工作目录
 4. 读取 workflow.yaml，按 steps 顺序执行
-5. 每个步骤在 Docker 容器中运行（gis-base 镜像）
-6. 清理脚本目录（知识产权保护）
-7. 结果写入本地输出目录
+5. 每个步骤按 runtime 执行：
+   - `docker` -> Docker 容器（gis-base 镜像）
+   - `python3` -> 本地 subprocess
+   - `arcpy` -> 系统 arcpy
+6. 结果写入本地输出目录，临时文件自动清理
@@ -0,0 +1,183 @@
+# 平台架构文档
+
+> 面向平台运维的架构描述。反映 **2026-07-16** 实际部署状态。
+> 生产环境：阿里云 ECS（39.107.238.22）。
+> 冷备：腾迅云 ECS（106.54.216.234），每日数据同步，不对外暴露。
+
+---
+
+## 一、总览
+
+```
+用户 / AI Agent
+    │
+    ▼
+Nginx Proxy Manager (mercator-npm) ← HTTPS 统一入口
+    │
+    ├── www.mercator.cn        → homepage:3000
+    ├── auth.mercator.cn       → auth-center-frontend:3000  (→ backend :8000)
+    ├── suites.mercator.cn     → suite-market-frontend:3302  (→ backend :8001)
+    ├── discussions.mercator.cn → discussions-frontend:3001  (→ backend :8005)
+    └── git.mercator.cn        → gitea:3000
+```
+
+**核心原则：执行在本地，云端只做管理和分发。**
+
+---
+
+## 二、容器清单
+
+全部运行在阿里云 ECS，Docker 网络 `mercator-net`。
+
+### 2.1 认证中心 — auth-center
+
+| 项目 | 说明 |
+|------|------|
+| 前端 | `mercator-auth-center-frontend`，Next.js，:3000 |
+| 后端 | `mercator-auth-center-backend`，FastAPI，:8000 |
+| 数据库 | `auth_center_db`（PostgreSQL） |
+
+API 分组：登录注册、企业微信 OIDC 扫码、API Key 管理（`mk_` 前缀）、服务账户 Token（HS256 JWT，1h）、MFA TOTP、OAuth2/OIDC 服务端、用户管理、会话管理、审计日志。
+
+### 2.2 套件市场 — suite-market
+
+| 项目 | 说明 |
+|------|------|
+| 前端 | `mercator-suite-market-frontend`，Next.js，:3302 |
+| 后端 | `mercator-suite-market-backend`，FastAPI，:8001 |
+| 数据库 | `suite_market_db`（PostgreSQL） |
+
+API 概览：
+
+| 路由 | 功能 |
+|------|------|
+| `GET/POST /api/v1/suites` | 套件 CRUD |
+| `GET /api/v1/suites/search?q=` | 搜索 |
+| `POST /api/v1/suites/{id}/versions` | 发布版本 |
+| `POST /publish` / `POST /publish/upload` | 发布套件 |
+| `POST /api/v1/compliance/check` | 合规检测 |
+| `POST /api/v1/parameters/validate` | 参数校验 |
+| `GET /api/v1/categories` | 分类管理 |
+| `GET /api/v1/health` | 健康检查 |
+
+### 2.3 讨论区 — discussions
+
+| 项目 | 说明 |
+|------|------|
+| 前端 | `mercator-discussions-frontend`，Next.js，:3001 |
+| 后端 | `mercator-discussions-backend`，FastAPI，:8005 |
+| 数据库 | `discussions_db`（PostgreSQL） |
+
+API：话题 CRUD + 关闭/重开，评论 CRUD，标签管理。种子标签：bug, feature, question, discussion, announcement, suggestion。
+
+### 2.4 基础设施
+
+| 服务 | 容器 | 版本 |
+|------|------|------|
+| PostgreSQL | mercator-postgres | postgres:16-alpine |
+| Redis | mercator-redis | redis:7-alpine |
+| NPM | mercator-npm | jc21/nginx-proxy-manager:latest |
+| MinIO | minio-nginx | nginx:alpine（MinIO 反代，:9000） |
+
+---
+
+## 三、Gitea
+
+| 域名 | 用途 |
+|------|------|
+| `git.mercator.cn` | 源码托管 + Packages（OCI 镜像仓库 + Generic 脚本包存储） |
+
+### 组织与仓库
+
+**AgentGIS**（源码仓库）：
+
+| 仓库 | 说明 |
+|------|------|
+| `auth-center` | 认证中心 |
+| `suite-market` | 套件市场 |
+| `discussions` | 讨论区 |
+| `gis-actions` | 本地执行器（`cli.py` + `steps_executor.py`） |
+| `gis-base-image` | 基础镜像 Dockerfile |
+| `mercator-homepage` | 官网首页 |
+
+**SuiteHub**（项目文档）：`agent-profiles` — Agent 认知文件 + 用户文档 + 平台架构文档
+
+
+---
+
+## 四、认证
+
+| 凭证 | 有效期 | 用途 |
+|------|--------|------|
+| JWT（密码/OIDC 登录） | 15 分钟 | 浏览器 Web UI |
+| API Key（`mk_`） | 自定义（默认 90 天） | AI Agent 自动化 |
+| 服务账户 Token（HS256 JWT） | 1 小时 | 微服务间通信 |
+| Gitea Token | 自定义 | Publish API 上传脚本包 |
+
+**认证流程：**
+
+```
+浏览器 → auth.mercator.cn → 密码/企业微信扫码 → JWT
+AI Agent → API Key → suite-market API
+微服务 → HS256 JWT → Auth Center 签发
+```
+
+Auth Center 内置 OAuth2/OIDC 服务端，企业微信为身份源，RS256 签名。
+
+---
+
+## 五、套件生命周期
+
+### 5.1 发布
+
+```
+开发者打包 workflow.yaml + scripts/ → .tar.gz
+    → POST /publish/upload（需 API Key + Gitea Token）
+    → 合规检测
+    → 参数校验
+    → 上传脚本包到 Gitea Packages
+    → 写入 suite_suites
+```
+
+### 5.2 本地执行
+
+```
+agc run <work_dir> --suite-id <id> --input key=value
+    │
+    ├── GET suites.mercator.cn/api/v1/suites/{id}（查 package_url）
+    ├── wget 从 Gitea Packages 下载脚本包
+    ├── 解压 → 读取 workflow.yaml
+    ├── steps_executor: 按 depends_on 拓扑序
+    │   ├── runtime=docker  → 每步 docker run --rm gis-base 隔离执行
+  │   └── runtime=python3/arcpy → 本地 subprocess（Windows agc.exe）
+    ├── 清理脚本包
+    └── 结果留在本地 work_dir/_step_outputs/
+```
+
+平台上没有任务队列、没有 Worker。执行完全在用户本地完成。
+
+### 5.3 基础镜像
+
+| 项目 | 说明 |
+|------|------|
+| 仓库 | `git.mercator.cn/AgentGIS/gis-base-image` |
+| 分发 | `https://packages.mercator.cn/public/gis-base/latest.tar.gz`（MinIO） |
+| 预装 | Python 3.11 + GDAL + Shapely + GeoPandas + Fiona + Rasterio + PyProj + numpy + scipy + pandas + openpyxl + python-docx + matplotlib + Pillow + requests + Jinja2 |
+| 大小 | ~465MB，Debian slim 基底 |
+
+---
+
+## 六、技术栈
+
+| 层级 | 选型 |
+|------|------|
+| 前端 | Next.js |
+| 后端 | FastAPI |
+| 数据库 | PostgreSQL 16 + Redis 7 |
+| 反向代理 | Nginx Proxy Manager |
+| 代码托管 / Packages | Gitea |
+| OIDC 身份源 | 企业微信 |
+| 对象存储 | MinIO |
+| 邮件 | 阿里云 DirectMail |
+| 本地执行器（Linux） | gis-actions（Python CLI + Docker） |
+| 本地执行器（Windows） | gis-actions（agc.exe + 本机 subprocess） |
@@ -1,81 +1,35 @@
 # 快速入门

-## 第一步：获取 API Key
+## 第一步：安装 gis-actions

-访问 https://auth.mercator.cn，创建 API Key（`mk_` 开头）。
+```bash
+# Linux
+curl -sLO https://packages.mercator.cn/public/gis-actions/latest.deb
+sudo dpkg -i latest.deb

-API Key 是 Agent 与平台交互的唯一凭证。
+# Windows
+# 下载 latest-windows.zip 解压到 %LOCALAPPDATA%\AgentGIS\gis-actions\，加入 PATH
+```
+
+前提条件：Linux 系统 + Docker。首次执行时会自动下载 gis-base 镜像。

 ## 第二步：浏览套件

 ```bash
-# 列出所有套件
-curl -s https://suites.mercator.cn/api/v1/suites
-
-# 搜索套件
-curl -s "https://suites.mercator.cn/api/v1/suites/search?q=缓冲区"
-
-# 查看套件详情
-curl -s https://suites.mercator.cn/api/v1/suites/{suite_id}
+curl -s https://suites.mercator.cn/api/v1/suites | python3 -m json.tool
 ```

-## 第三步：选择套件
+记下你要用的套件 ID。

-从列表中筛选符合需求的套件，记录它的 `suite_id`。
-
-## 第四步：读取参数结构
-
-查看套件详情中的 `params_schema`，了解需要提供哪些参数：
+## 第三步：执行套件

 ```bash
-curl -s https://suites.mercator.cn/api/v1/suites/{suite_id} | jq '.params_schema'
+SUITE_MARKET_URL="https://suites.mercator.cn" \
+agc run /tmp/output --suite-id <suite-id> --input key=value
 ```

-返回示例：
-```json
-{
-  "type": "object",
-  "required": ["buffer_distance"],
-  "properties": {
-    "buffer_distance": {
-      "type": "number",
-      "default": 0.5,
-      "description": "缓冲区距离（度）"
-    }
-  }
-}
-```
+执行在本地 Docker 容器中完成，数据不上传云端。

-根据参数声明构造输入数据。
+## 第四步：查看结果

-## 第五步：提交执行
-
-```bash
-curl -s -X POST https://suites.mercator.cn/api/v1/suites/{suite_id}/execute \
-  -H "Authorization: Bearer ***" \
-  -H "Content-Type: application/json" \
-  -d '{"buffer_distance": 0.5}'
-```
-
-返回结果中包含 `task_id`，用这个 ID 查询执行状态。
-
-## 第五步：查询状态
-
-```bash
-curl -s https://suites.mercator.cn/api/v1/task/{task_id}/status
-```
-
-状态：`pending` → `running` → `completed` / `failed`
-
-## 第六步：获取结果
-
-任务完成后，从返回结果中读取输出数据。
-
-## 前置条件
-
- **API Key**（必须）
- **GIS Actions** 在本地运行（用于实际执行任务）
-
-## 数据安全
-
-**数据永不离开本地。** 你的文件始终在你的机器上处理。
+执行完成后，结果文件在工作目录（如 `/tmp/output/_step_outputs/`）中。
@@ -1,47 +1,50 @@
-# 执行任务与查看结果
+# 执行套件与查看结果

-## 提交任务
+## 执行套件

-1. 进入套件详情页
-2. 填写输入参数：
-   - **本地文件路径**：GIS Actions 将在你的机器上读取这些文件
-   - **数值参数**：如缓冲区距离、精度等
-3. 点击「执行」按钮
+使用 `agc run` 命令在本地执行套件：
+
+```bash
+SUITE_MARKET_URL="https://suites.mercator.cn" \
+agc run <work_dir> \
+  --suite-id 2c99a1cb-84a5-42dd-9147-1c8e8f7f2941 \
+  --input bid_xls=/path/to/标段清单.xls \
+  --input points_shp=/path/to/点状工程.shp
+```
+
+参数说明：
+- `--suite-id`：套件 ID，从市场获取
+- `--input`：输入参数，每个参数一个 `--input`，文件路径用本地绝对路径

 ## 执行流程

 ```
-你提交任务
+agc run 执行
  │
-    ▼
-调度中心接收 → 放入队列
+  ├── 从市场查询套件的脚本包地址
+  ├── 下载脚本包到本地
+  ├── 复制输入文件到工作目录
  │
-    ▼
-GIS Actions（你的机器）拉取任务
+  ├── Step 1: docker run gis-base 执行脚本（Linux）
+  ├── Step 2: 本地 subprocess 执行（Windows）
  │
-    ├── 下载套件脚本包
-    ├── Docker 容器中执行
-    └── 结果写入本地目录
-    │
-    ▼
-任务状态更新为「已完成」
+  └── 结果写入 /tmp/output/
 ```

 ## 查看结果

- **执行状态**：任务列表显示每个任务的状态（待处理 / 运行中 / 已完成 / 失败）
- **执行结果**：完成后可以看到输出的结果数据
- **本地文件**：GIS Actions 处理后的文件保存在你机器上的指定输出目录
+- **控制台输出**：执行过程实时打印，每个步骤的状态、产出一目了然
+- **结果文件**：在工作目录（如 `/tmp/my-output/`）的 `_step_outputs/` 下

 ## 错误处理

-如果任务失败：
+如果执行失败：

-1. 查看错误信息
+1. 查看控制台错误信息
 2. 检查输入文件路径是否正确
-3. 检查文件格式是否支持
-4. 确认 GIS Actions 是否正常运行
+3. 确认执行环境（Linux: `docker ps`, Windows: `agc --help`）
+4. 确认 gis-actions 版本（`dpkg -l gis-actions`）

 ## 数据安全

-**数据永不离开本地。** 你提供的输入文件始终在你的机器上，GIS Actions 在你的本地 Docker 容器中处理，不上传到云端。
+**数据永不离开本地。** 输入文件始终在你的机器上，在本地处理（Linux Docker 或 Windows 本机），不上传到云端。
@@ -14,6 +14,7 @@

 - **搜索栏**：输入关键词搜索套件名称和描述
 - **分类筛选**：按分类过滤套件
+- **平台筛选**：按 Linux / Windows / 全平台 过滤
 - **状态筛选**：按发布状态筛选

 ## 套件详情