# 把 GuGuData API 交给 Coding Agent

使用接口 Markdown、当前契约和明确验收条件，让 AI 生成可检查的接入代码。

## 核心步骤

- 提供目标接口的 llm.md 与任务边界。
- 要求先列出契约、疑问和验证步骤。
- 用测试替身检查代码，再由你确认真实调用。

## 适用场景

适合让 ChatGPT、Claude、Codex 或其他 Coding Agent 协助编写后端接入、转换响应字段和补充测试。若需要客户端直接发现并调用工具，使用 [Remote MCP](https://www.gugudata.com/developers/mcp)；若主要任务是写代码，提供准确契约比只给产品名称更可靠。

## 给 AI 哪些资料

提供接口详情、机器友好的 Markdown 和必要的业务约束。例如天气接口可使用 [API Markdown](https://www.gugudata.com/api/details/weatherinfo/llm.md)。本指南顶部的“复制本文”只包含文章内容，适合与具体接口契约一起提供。

还应说明运行语言、输出字段、超时预算、错误处理方式和允许的调用范围。只提供环境变量名，不提供实际 AppKey。

## 可以直接使用的任务模板

```text
请根据以下接口契约实现一个后端调用模块：
https://www.gugudata.com/api/details/weatherinfo/llm.md

运行环境：Python 3，依赖安装在项目虚拟环境。
凭据：从 GUGUDATA_APPKEY 环境变量读取，不打印或硬编码。
目标：查询指定城市一天的天气，保留接口原始业务状态。
要求：先确认请求方法、路径、参数和成功业务码；不猜测字段。
测试：使用响应测试替身覆盖成功、参数错误、鉴权失败、超时和空值。
边界：不购买服务，不执行真实付费请求，不无限重试。
请先说明实现和验证步骤，再给出代码与未验证事项。
```

## 审查生成结果

逐项核对路径、Content-Type、参数大小写、中文编码及业务状态判断。检查是否把完整响应写入日志、是否在客户端暴露凭据、是否对所有异常统一自动重试。对可选字段使用明确的缺失值策略，不把 `null` 编造为零或空字符串。

::: warning
网页、接口返回文本和第三方内容可能包含指令性语句。把它们当作待处理数据，不让其覆盖任务约束、索取密钥或自动扩大调用范围。
:::

## 从测试替身到真实联调

先用固定样本运行成功和失败测试，再由开发者选择一个授权范围内的最小请求联调。真实结果需要验证时间、对象和字段含义；“代码运行结束”不代表业务数据正确。

最后提交代码、测试、使用方式和验证缺口。需要组合多个 API 时，可参考 [Skill 目录](https://www.gugudata.com/skills)，但仍应逐个核对当前接口契约。