docs: 使用 Markdown 格式规范化套件说明

- description 改用 YAML | 保留换行，支持 Markdown 渲染
- 表格展示内置数据和预期输出
- 执行流程表格化
- 步骤描述加入技术细节和注意事项

suites/test-linux/workflow.yaml

@@ -1,29 +1,47 @@
 name: 云南省界叠加分析（Linux 测试）
-description: >
+description: |
-  验证 GIS Actions 4.0 Linux 双平台（Docker + Python3）执行链路的测试套件。
+  # 云南省界叠加分析（Linux 测试）
 
-  【内置测试数据】
+  验证 GIS Actions 4.0 **Linux 双平台**（Docker + Python3）执行链路的官方测试套件。
-  套件包内含 4 个 GeoJSON 文件，开箱即用，无需用户准备数据：
-    - yunnan.geojson — 云南省界（面），作为叠加分析的目标区域
-    - kunming.geojson — 昆明市界（面），预期在云南省内，叠加结果为"通过"
-    - dali.geojson    — 大理州界（面），预期在云南省内，叠加结果为"通过"
-    - baise.geojson   — 广西百色市界（面），预期不在云南省内，叠加结果为"不通过"
 
-  【执行流程】
+  ---
-  Step 1 (GeoJSON → SHP) — 用 geopandas 将内置 GeoJSON 转为 Shapefile
-  Step 2 (叠加分析)      — 用 geopandas 计算各城市中心点是否落在省界内
-  Step 3 (输出 Excel)    — 用 openpyxl 将分析结果写入 Excel，含条件高亮
 
-  【预期输出】
+  ## 内置测试数据
-  输出的 Excel 文件包含一张"叠加分析结果"工作表，含 7 列：
-    城市 | 城市代码 | 城市名称 | 人口 | 在省内 | 相交 | 状态
-  预期结果：
-    - 昆明市 ✅ 在省内（通过，绿色高亮）
-    - 大理州 ✅ 在省内（通过，绿色高亮）
-    - 百色市 ❌ 不在省内（不通过，红色高亮）
 
-  Step 1 和 Step 2 依赖 gis-base 镜像（含 geopandas、openpyxl），
+  套件包内置 4 个 GeoJSON 文件，开箱即用：
-  Step 3 使用 python3 运行时（Linux 本机 Python 环境）。
+
+  | 文件 | 内容 | 角色 |
+  |------|------|------|
+  | `yunnan.geojson` | 云南省界（面） | 叠加分析的目标区域 |
+  | `kunming.geojson` | 昆明市界（面） | 预期在省内 → 通过 |
+  | `dali.geojson` | 大理州界（面） | 预期在省内 → 通过 |
+  | `baise.geojson` | 广西百色市界（面） | 预期不在省内 → 不通过 |
+
+  ## 执行流程
+
+  | 步骤 | 运行时 | 功能 |
+  |------|--------|------|
+  | 1. GeoJSON → SHP | Docker（geopandas） | 内置 GeoJSON 转为 Shapefile |
+  | 2. 叠加分析 | Docker（geopandas） | 空间判断城市是否在省界内 |
+  | 3. Excel 输出 | Python3（openpyxl） | 格式化报表含条件高亮 |
+
+  ## 预期输出
+
+  输出 Excel 工作簿包含 **叠加分析结果** 工作表：
+
+  | 城市 | 城市代码 | 城市名称 | 人口 | 在省内 | 相交 | 状态 |
+  |------|----------|----------|------|--------|------|------|
+  | kunming | 530100 | 昆明市 | 8,500,000 | 是 | 是 | 通过 ✅ |
+  | dali | 532900 | 大理州 | 3,300,000 | 是 | 是 | 通过 ✅ |
+  | baise | 451000 | 百色市 | 3,600,000 | 否 | 是 | 不通过 ❌ |
+
+  **条件格式：** 通过行绿色背景，不通过行红色背景。
+
+  ## 环境要求
+
+  - 依赖 `gis-base:latest` 镜像（内含 geopandas、openpyxl）
+  - Step 1、2 在 Docker 容器中隔离执行
+  - Step 3 使用本机 Python3 运行时
 version: 1.0.2
 author: Robert
 platform: linux
@@ -35,18 +53,21 @@ params:
   output_path:
     type: string
     required: true
-    desc: >
+    desc: |
-      输出 Excel 文件路径，例如 /home/user/output/result.xlsx。
+      输出 Excel 文件路径，例如 `/home/user/output/result.xlsx`。
-      文件包含"叠加分析结果"工作表，标题行有表头，数据行按通过/不通过绿色/红色高亮。
+
+      输出文件包含一张 **叠加分析结果** 工作表，表头加粗、蓝色底白色字；
+      通过行绿色高亮，不通过行红色高亮。
 
 base_image: gis-base:latest
 
 steps:
   - id: geojson_to_shp
     name: 内置数据 → 转为 Shapefile
-    description: >
+    description: |
-      从套件包内置 data/ 目录读取 4 个 GeoJSON 文件（云南省界 + 昆明/大理/百色），
+      从套件包内置 `data/` 目录读取 4 个 GeoJSON 文件（云南省界 + 昆明/大理/百色），
-      用 geopandas 读取后转为 ESRI Shapefile 格式，存入共享工作目录 /tmp/output/shp/。
+      使用 **geopandas** 逐文件读取，转为 ESRI Shapefile 格式，
+      输出至共享工作目录 `/tmp/output/shp/`。
     runtime: docker
     script_id: convert
     params:
@@ -54,13 +75,18 @@ steps:
 
   - id: overlay
     name: 叠加分析（空间判断）
-    description: >
+    description: |
-      读取省界 Shapefile，读取各城市 Shapefile，
+      读取省界 Shapefile，读取各城市 Shapefile。
-      使用投影坐标系（EPSG:3857）计算每个城市的几何中心点，
+      使用投影坐标系 **EPSG:3857（Web 墨卡托）** 计算每个城市的几何中心点，
-      判断中心点是否落在省界多边形内（contains），
+      判断中心点是否落在省界多边形内（`contains`），
-      同时检查面面相交（intersects）作为辅助信息。
+      同时检查面面相交（`intersects`）作为辅助信息。
-      输出分析结果 JSON 到 /tmp/output/result/。
+
-      预期结果：昆明、大理在省内通过；百色不在省内不通过。
+      分析结果以 JSON 格式输出到 `/tmp/output/result/`。
+
+      **预期结果：**
+      - 昆明市 → 在省内 ✅
+      - 大理州 → 在省内 ✅
+      - 百色市 → 不在省内 ❌（验证"不过"分支）
     runtime: docker
     script_id: overlay
     depends_on: [geojson_to_shp]
@@ -71,10 +97,16 @@ steps:
 
   - id: export_excel
     name: 输出 Excel 报表
-    description: >
+    description: |
-      读取叠加分析结果 JSON，用 openpyxl 生成格式化的 Excel 工作簿。
+      读取上一步产生的叠加分析结果 JSON，使用 **openpyxl** 生成格式化的 Excel 工作簿。
-      表头加粗白色字蓝色底色，数据行按"在省内"为是/否分别绿色/红色高亮。
+
-      写入用户指定的 output_path。
+      **格式细节：**
+      - 表头：加粗、白色字体、蓝色背景（#4472C4）
+      - 通过行：绿色背景（#E2EFDA）
+      - 不通过行：红色背景（#FCE4EC）
+      - 自动调整列宽
+
+      输出文件写入用户指定的 `output_path`。
     runtime: python3
     script_id: excel
     depends_on: [overlay]

suites/test-windows/workflow.yaml

@@ -1,34 +1,47 @@
 name: 云南省界叠加分析（Windows 测试）
-description: >
+description: |
-  验证 GIS Actions 4.0 Windows 双平台（arcpy + Python3）执行链路的测试套件。
+  # 云南省界叠加分析（Windows 测试）
 
-  【内置测试数据】
+  验证 GIS Actions 4.0 **Windows 双平台**（arcpy + Python3）执行链路的官方测试套件。
-  套件包内含 4 个 GeoJSON 文件，开箱即用，无需用户准备数据：
-    - yunnan.geojson — 云南省界（面），作为叠加分析的目标区域
-    - kunming.geojson — 昆明市界（面），预期在云南省内，叠加结果为"通过"
-    - dali.geojson    — 大理州界（面），预期在云南省内，叠加结果为"通过"
-    - baise.geojson   — 广西百色市界（面），预期不在云南省内，叠加结果为"不通过"
 
-  【执行流程】
+  ---
-  Step 1 (GeoJSON → SHP) — 用 arcpy.JSONToFeatures 将内置 GeoJSON 转为 Shapefile
-  Step 2 (叠加分析)      — 用 arcpy 空间选择，判断城市中心点是否在省界内
-  Step 3 (输出 Excel)    — 用 openpyxl 将分析结果写入 Excel，含条件高亮
 
-  【预期输出】
+  ## 内置测试数据
-  输出的 Excel 文件包含一张"叠加分析结果"工作表，含 7 列：
-    城市 | 城市代码 | 城市名称 | 人口 | 在省内 | 相交 | 状态
-  预期结果：
-    - 昆明市 ✅ 在省内（通过，绿色高亮）
-    - 大理州 ✅ 在省内（通过，绿色高亮）
-    - 百色市 ❌ 不在省内（不通过，红色高亮）
 
-  Step 1 和 Step 2 依赖系统 ArcGIS arcpy 环境（Python 2.7），
+  套件包内置 4 个 GeoJSON 文件，开箱即用：
-  Step 3 使用 python3 运行时（Windows 本机 Python 3 环境）。
 
-  【环境要求】
+  | 文件 | 内容 | 角色 |
-  - ArcGIS 10.x（含 arcpy）
+  |------|------|------|
-  - Python 3（用于 Excel 输出步骤）
+  | `yunnan.geojson` | 云南省界（面） | 叠加分析的目标区域 |
-  - openpyxl 库（pip install openpyxl）
+  | `kunming.geojson` | 昆明市界（面） | 预期在省内 → 通过 |
+  | `dali.geojson` | 大理州界（面） | 预期在省内 → 通过 |
+  | `baise.geojson` | 广西百色市界（面） | 预期不在省内 → 不通过 |
+
+  ## 执行流程
+
+  | 步骤 | 运行时 | 功能 |
+  |------|--------|------|
+  | 1. GeoJSON → SHP | arcpy | 内置 GeoJSON 转为 Shapefile |
+  | 2. 叠加分析 | arcpy | 空间选择判断城市是否在省界内 |
+  | 3. Excel 输出 | Python3（openpyxl） | 格式化报表含条件高亮 |
+
+  ## 预期输出
+
+  输出 Excel 工作簿包含 **叠加分析结果** 工作表：
+
+  | 城市 | 城市代码 | 城市名称 | 人口 | 在省内 | 相交 | 状态 |
+  |------|----------|----------|------|--------|------|------|
+  | kunming | 530100 | 昆明市 | 8,500,000 | 是 | 是 | 通过 ✅ |
+  | dali | 532900 | 大理州 | 3,300,000 | 是 | 是 | 通过 ✅ |
+  | baise | 451000 | 百色市 | 3,600,000 | 否 | 是 | 不通过 ❌ |
+
+  **条件格式：** 通过行绿色背景，不通过行红色背景。
+
+  ## 环境要求
+
+  - Step 1、2 依赖系统 **ArcGIS 10.x**（arcpy，Python 2.7 环境）
+  - Step 3 使用系统本机 **Python 3** 运行时（需安装 openpyxl）
+  - 建议安装顺序：ArcGIS → Python 3 → `pip install openpyxl`
 version: 1.0.2
 author: Robert
 platform: windows
@@ -40,18 +53,21 @@ params:
   output_path:
     type: string
     required: true
-    desc: >
+    desc: |
-      输出 Excel 文件路径，例如 C:\Users\test\output\result.xlsx。
+      输出 Excel 文件路径，例如 `C:\Users\test\output\result.xlsx`。
-      文件包含"叠加分析结果"工作表，标题行有表头，数据行按通过/不通过绿色/红色高亮。
+
+      输出文件包含一张 **叠加分析结果** 工作表，表头加粗、蓝色底白色字；
+      通过行绿色高亮，不通过行红色高亮。
 
 steps:
   - id: geojson_to_shp
     name: 内置数据 → 转为 Shapefile
-    description: >
+    description: |
-      从套件包内置 data/ 目录读取 4 个 GeoJSON 文件（云南省界 + 昆明/大理/百色），
+      从套件包内置 `data/` 目录读取 4 个 GeoJSON 文件（云南省界 + 昆明/大理/百色），
-      用 arcpy.JSONToFeatures_conversion 转为 ESRI Shapefile 格式，
+      使用 **arcpy.JSONToFeatures_conversion** 工具将 JSON 转为要素类并输出为 Shapefile，
-      存入共享工作目录 /tmp/output/shp/。
+      存入共享工作目录 `/tmp/output/shp/`。
-      注意：arcpy 步骤运行在 Python 2.7 环境。
+
+      ⚠️ 本步骤运行在 **Python 2.7（arcpy）** 环境。
     runtime: arcpy
     script_id: arcpy_convert
     params:
@@ -59,13 +75,19 @@ steps:
 
   - id: overlay
     name: 叠加分析（空间选择）
-    description: >
+    description: |
-      读取省界 Shapefile，创建要素图层（MakeFeatureLayer），
+      读取省界 Shapefile，创建要素图层。
-      对每个城市创建要素图层后使用 FeatureToPoint 计算几何中心点，
+      对每个城市 Shapefile 使用 **FeatureToPoint** 计算几何中心点，
-      再用 SelectLayerByLocation（WITHIN 关系）判断中心点是否在省界内。
+      再通过 **SelectLayerByLocation**（空间关系：WITHIN）判断中心点是否在省界内。
-      输出分析结果 JSON 到 /tmp/output/result/。
+
-      预期结果：昆明、大理在省内通过；百色不在省内不通过。
+      分析结果以 JSON 格式输出到 `/tmp/output/result/`。
-      注意：arcpy 步骤运行在 Python 2.7 环境。
+
+      **预期结果：**
+      - 昆明市 → 在省内 ✅
+      - 大理州 → 在省内 ✅
+      - 百色市 → 不在省内 ❌（验证"不过"分支）
+
+      ⚠️ 本步骤运行在 **Python 2.7（arcpy）** 环境。
     runtime: arcpy
     script_id: arcpy_overlay
     depends_on: [geojson_to_shp]
@@ -76,11 +98,18 @@ steps:
 
   - id: export_excel
     name: 输出 Excel 报表
-    description: >
+    description: |
-      读取叠加分析结果 JSON，用 openpyxl 生成格式化的 Excel 工作簿。
+      读取上一步产生的叠加分析结果 JSON，使用 **openpyxl** 生成格式化的 Excel 工作簿。
-      表头加粗白色字蓝色底色，数据行按"在省内"为是/否分别绿色/红色高亮。
+
-      写入用户指定的 output_path。
+      **格式细节：**
-      注意：此步骤使用 python3 运行时在 Windows 本机 Python 3 环境执行。
+      - 表头：加粗、白色字体、蓝色背景（#4472C4）
+      - 通过行：绿色背景（#E2EFDA）
+      - 不通过行：红色背景（#FCE4EC）
+      - 自动调整列宽
+
+      输出文件写入用户指定的 `output_path`。
+
+      ⚠️ 本步骤使用 **Python 3** 运行时在 Windows 本机执行。
     runtime: python3
     script_id: excel
     depends_on: [overlay]