agentleFS
dotacloverdotaclover/clover-skills/api-engineering/SKILL.md

api-engineering

Skill0 starsChanged 3 days agoMITView on GitHub

四渠道共用API工程交付。用于HTTP认证、同步/异步任务、应用集成开发与调试、接入程序部署、日志排障和验收;与星桥、聚合、华锐、火山渠道资料一起使用,不代替渠道协议或授权。

3 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Files
SKILL.md

API工程交付

1. 明确输入与协议

先读 task-delivery。显式接收 project_root、各技能实际安装根 skills_root、input_paths、output_dir、private_state_dir、配置来源及部署目标;所有路径按当前任务解析,不绑定 expert/skills 或 _local 布局。取得当前项目语言、依赖、运行方式、目标环境、provider、账号/项目、能力与验收要求;只写代码时使用环境变量占位,不索取真实Key或发送付费探活。

按渠道选择资料:吴燕使用 xingqiao-media,李贺使用 juhe-nexgate,狗总使用 huarui-zhisuan / huarui-video,迟空使用 seedance-dev 的 provider=ark。记录文档版本、服务根地址、路径、认证方式、当前账号可见能力及未验证事项。型号列表可见不代表参数全部支持,其他provider成功不代表当前渠道成功。

确认连接地址被授权接收该Key;使用HTTPS并校验证书,不跟随不可信重定向转发Authorization。视频API Key与素材IAM签名按平台区分,不混用账号、项目、任务ID和素材。Base URL是否带版本路径按文档核对,避免重复 /v1。

2. 实现最小可运行接入

先读项目入口、依赖与现有测试,沿用语言和HTTP客户端,不重造整套架构。优先复用已有渠道脚本:

python "$SKILLS_ROOT/xingqiao-media/scripts/xq.py" --config "$PRIVATE_CONFIG" --state-dir "$STATE_DIR" self-test
python "$SKILLS_ROOT/juhe-nexgate/scripts/juhe.py" --help
python "$SKILLS_ROOT/seedance-dev/scripts/seedance.py" --help

将认证保留在服务端环境变量/凭据库;交付配置示例只列变量名,不把Key放前端、URL、日志、命令字面量或Git。补齐以下实际代码而非伪代码:

  • 请求构造:Content-Type、JSON字段类型、型号、输入文件与大小限制;参数验证在用户输入边界执行。
  • HTTP客户端:连接/读取超时、状态码与响应Content-Type检查;非JSON错误保留脱敏摘要,不盲目 .json()。
  • 响应解析:成功字段、任务ID或业务错误;200/202只是HTTP结果,终态需另判。
  • 下载:确认文档允许的媒体主机,服务端接收用户URL时限制协议与目标地址,防止SSRF;不向媒体域发送API Key,限制大小和超时,先临时文件再校验保存。
  • 日志:本地关联ID、provider、请求路径、HTTP状态、request_id、任务ID、阶段及耗时;不记录Bearer、签名URL、完整base64、私人素材。

先用mock响应或dry-run验证请求及解析,再在用户授权范围内做最小真实调用。模拟测试只验证本地逻辑,不得作为真实接口、网站或部署验收证据;真实授权测试未做即标未验证。只读查询与模型列表可独立验证,不用收费生成为健康检查。

3. 异步状态机与恢复

提交前持久化原请求摘要、provider、账号来源和幂等键;响应后立即保存任务ID。记录 prepared → submitted/unknown → queued/running → succeeded/failed/cancelled/expired,具体状态按渠道映射,未知状态保留原值并停止冒报。

设置轮询间隔、总等待期限与最大查询次数;遵守Retry-After和平台限额。仅对确认安全的查询执行有限退避与抖动重试。提交POST超时/断线时记unknown,先查询已有任务或按平台已验证幂等协议恢复;没有任务ID且无恢复接口,报服务方核账,禁止换键重提。

本地超时不代表服务端取消。取消接口只有文档和权限确认后才使用;取消失败仍查询原任务。程序重启从持久记录恢复查询,不重复创建。星桥等待 terminal + next_action:read_result;聚合图片 needs_review 停止自动处理并核账;Ark只在succeeded且成片存在时下载。

4. 调试与测试

为当前项目补实际测试,至少覆盖:合法请求、参数错误、401/403、429、5xx、非JSON响应、提交响应丢失、查询超时、重复恢复、失败终态、下载过期或空文件。mock层验证“恢复只GET、不重复POST”、脱敏与provider隔离。运行项目现有测试和构建,将命令与退出码写入报告。真实生成测试若未获付费授权,明确未运行,不冒称通过。

排障顺序:本地输入与代码 → DNS/TLS/代理 → HTTP路径与认证 → 权限/余额/限额 → 上游状态 → 结果下载。记录可复现输入摘要、HTTP与业务码、request_id、task_id,不通过换Key/换供应商/重试生成来掩盖根因。

证据下一步
连接或TLS失败核对解析、代理、证书与服务地址,不关闭TLS验证
401核对凭据来源/环境覆盖与Bearer格式,不输出密钥
403/余额不足核对账号权限、型号与额度,报告用户,不自动充值
404核对服务、协议、路径和任务归属,不改写为排队
429按限流退避查询,停止新增任务
5xx/提交超时保存不确定状态并查询原任务,禁止自动重提
succeeded无可用文件检查归档状态/链接过期与下载响应,不报告验收成功

5. 部署接入程序或集成应用

部署不是私有部署上游模型。只有官方软件、授权及部署文档齐备时,才另外评估平台私有部署。

  1. 读取项目构建/启动脚本,锁定依赖、运行时版本与产物;本地执行构建和健康检查。按项目实际选择npm、Python venv、Go或PHP,不盲目套命令。
  2. 确认目标路径、端口、进程管理、环境变量名、存储权限及任务记录持久目录;备份当前产物和配置,写可执行回滚命令。
  3. 在已授权独立开发/测试应用内完成部署。Linux应用可引用 ops-linux 的systemd与反向代理章节;宝塔场景只读 ops-btpanel 对应步骤。共享生产主机、防火墙、系统服务与跨应用改动交华子审核影响与回滚后执行,渠道负责人不卸责。
  4. 使用非root服务账户,应用端口绑定127.0.0.1,Nginx反代到目标端口;按需设置上传大小、读超时和SSE缓冲。配置检验 nginx -t 通过才重载;不能擅自改共享vhost。
  5. 健康端点只检查本应用,不创建生成任务、不暴露Key或完整配置。核验进程、监听、HTTPS、健康端点和脱敏日志;外网复测应用入口。
  6. 验证重启恢复任务与文件权限;检查失败回滚到原产物/配置,再核验原健康状态。数据库迁移和回滚另行授权,不自动覆盖数据。

6. 验收与交付

交付源码/可执行调用、无密钥配置示例、依赖安装与启动命令、构建测试结果、任务恢复方式、部署与回滚记录、实际结果文件和已知限制。媒体用ffprobe或Pillow核对实际尺寸/时长/编码并播放抽帧,不照抄请求参数。

费用表分列provider、服务/型号、任务ID、预计费用、usage、实际结算、币种及凭证。仅星桥已有本地账本;其他渠道未核实自动记账能力时使用私有任务记录,不宣称已有脚本。通过SendMessage回传顺哥并交留名对账。

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.