SuperAPI AI 工具集

script-best-practices

编程与开发

查看项目

更新于 10-16 00:29

技能介绍

用途:为在技能中打包可执行脚本提供规范,适用于需要重复使用同一段代码、要求确定性可靠性、需要复杂校验,或生成代码的 token 成本高于执行成本的场景。

主要能力与规范:

  1. 错误处理:显式处理错误而非直接抛给模型,例如捕获 FileNotFoundError 后创建文件,捕获 PermissionError 后打印错误并返回 None。
  2. 常量说明:每个魔法数字都要写明理由,如 TIMEOUT = 30 表示 HTTP 请求通常 30 秒完成,MAX_RETRIES = 3 表示多数失败在第二次重试后解决。
  3. 意图说明:在 SKILL.md 中明确脚本是执行还是仅作参考,例如“运行 scripts/analyze.py 提取 PDF 表单字段”或“参见 scripts/analyze.py 的提取算法(不要直接运行)”。
  4. 组织方式:技能目录包含 SKILL.md 与 scripts/,主入口 analyze.py、校验工具 validate.py、共享工具 helpers/formatting.py 与 parsing.py。
  5. 依赖声明:显式列出依赖,如 pip install pdfplumber python-docx,或 pip install -r scripts/requirements.txt。
  6. 退出码:使用一致约定,EXIT_SUCCESS = 0、EXIT_INVALID_INPUT = 1、EXIT_FILE_NOT_FOUND = 2、EXIT_PERMISSION_ERROR = 3。
  7. 输出格式:输出可解析的结构化结果,如用 json.dumps 输出 status、files_processed、errors。
  8. 幂等性:脚本应可安全重复运行,如 os.makedirs(path, exist_ok=True)、仅在内容变化时写入。

限制:资料未提供具体平台支持范围、版本要求或性能数据。