agent-profiles/suites-help/开发者指南/最佳实践.md

最佳实践

先查市场，再动手写

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

curl -s 'https://suites.mercator.cn/api/v1/suites/search?q=缓冲区' | jq '.[] | {name, version}'
curl -s 'https://suites.mercator.cn/api/v1/suites/search?q=面积计算' | jq '.[] | {name, version}'

能找到现成的就引用它。不需要每次都写自己的脚本。

套件命名规范

• 使用英文小写 + 连字符：buffer-analysis、land-use-classification
• 名称反映功能：stream-extraction 而非 my-suite-1

参数设计

• 参数名用 snake_case：input_path、buffer_distance
• 必填参数和可选参数区分清楚
• 提供合理的默认值
• 写清楚描述和单位

threshold:
  type: number
  default: 100
  description: "河网提取阈值（像元数）"

输出设计

• 输出 JSON 包含关键字段
• 文件输出路径写清楚

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）