docs: suites-help/开发者指南/最佳实践.md

2026-07-09 15:10:29 +00:00
parent f864cb3737
commit 14418bb0ca
1 changed files with 54 additions and 0 deletions
@@ -0,0 +1,54 @@
+# 最佳实践
+
+## 先查市场，再动手写
+
+开发新套件前，先搜索市场是否已有能复用的套件：
+
+```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: "河网提取阈值（像元数）"
+```
+
+## 输出设计
+
+- 输出 JSON 包含关键字段
+- 文件输出路径写清楚
+
+```python
+result = {
+    "status": "ok",
+    "output_path": "/tmp/output/result.shp",
+    "feature_count": 42
+}
+```
+
+## 测试
+
+发布前用 `agc run` 测试，确认输入输出正确。
+
+## 版本迭代
+
+- 修复 bug 或小幅改进 → 递增补丁版本（1.0.0 → 1.0.1）
+- 新增功能 → 递增次版本（1.0.0 → 1.1.0）
+- 重大变更 → 递增主版本（1.0.0 → 2.0.0）