From 14418bb0ca7bb56c0600e976e2317d6bcdb2360e Mon Sep 17 00:00:00 2001
From: Huawei <huawei@mercator.cn>
Date: Thu, 9 Jul 2026 15:10:29 +0000
Subject: [PATCH] =?UTF-8?q?docs:=20suites-help/=E5=BC=80=E5=8F=91=E8=80=85?=
 =?UTF-8?q?=E6=8C=87=E5=8D=97/=E6=9C=80=E4=BD=B3=E5=AE=9E=E8=B7=B5.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 suites-help/开发者指南/最佳实践.md | 54 ++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 suites-help/开发者指南/最佳实践.md

diff --git a/suites-help/开发者指南/最佳实践.md b/suites-help/开发者指南/最佳实践.md
new file mode 100644
index 0000000..2c96e9f
--- /dev/null
+++ b/suites-help/开发者指南/最佳实践.md
@@ -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）