API与系统集成工程师

开篇速查：推荐模型与工具

推荐模型：GPT-5.6 Terra、Claude Sonnet 5 或 DeepSeek V4 Pro。
理由：适合契约、兼容性和适配层代码；第三方文档必须联网读取当前官方版本，真实沙箱测试不能被模型替代。
推荐产品：Codex、Claude Code、Cursor（本岗位涉及复杂开发、仓库或运行环境）。 常用工具：OpenAPI、Postman/Bruno、Webhook 调试器、Mock Server、契约测试与沙箱环境。 核对日期：2026-08-04；上线前再查厂商官方模型列表并用内部评测集验证。

历史依据：从 8,276 条用户消息中命中 336 条，精确去重后 141 条。以下工作方式优先针对这些历史任务和返工问题。

1. 历史记录暴露的问题

• 明确验收标准：9/141（6%）。
• 明确要求验证：53/141（38%）。
• 提供失败/复现证据：22/141（16%）。
• 出现“功能不可用/报错”类返工：16 条。
• 出现“再检查/再测试”类返工：5 条。
• 出现“继续/不要停”但退出条件不清：7 条。

因此本岗位的模板会把验证、证据和退出条件写进首轮提示，而不是等失败后补充。

2. 什么时候使用

• 对接第三方平台、插件、支付和模型服务
• 设计内部/外部API契约
• 处理Webhook、异步任务和分页
• 诊断请求成功但端到端链路不完整

3. 责任边界

• 负责契约、兼容、限流和故障隔离
• 不假定第三方响应字段永远稳定
• 不在日志中输出Token和完整敏感响应
• 不把接口模拟结果当真实平台验证

4. 开始前必须提供

• 官方文档/Schema/示例响应
• 认证方式和权限范围
• 调用频率、配额和分页
• 超时/重试/回调规则
• 调用方需要的稳定内部模型

缺少信息时，先从仓库、配置、运行状态和现有资料中查证。只有会改变业务方向、造成生产影响或无法安全推断的内容才询问。

5. 完整可复制提示词

你是 API 与系统集成工程师。请对接【系统/平台】的【能力】。

文档与版本：【链接或文件】
认证和权限：【内容】
调用场景与频率：【内容】
内部调用方和稳定模型：【内容】
成功/失败样本：【脱敏样本】

请先列出契约未知项，然后实现：认证、字段映射、分页、限流、超时、重试、幂等、Webhook验签、错误映射和可观测性。区分请求接收、任务运行和最终完成。

测试必须覆盖：正常、空字段、未知字段、部分结果、超时、429、5xx、重复回调、验签失败和分页。优先使用沙箱/测试账号做端到端验证。

交付内部契约、适配器、测试样本、监控指标、降级与人工恢复方案。

6. 推荐执行流程

1. 保存真实但脱敏的成功/失败样本
2. 定义外部字段到内部模型的映射
3. 处理分页、空字段、类型变化和部分结果
4. 隔离第三方错误和内部错误
5. 为Webhook验签和去重
6. 用沙箱或测试账号端到端验证
7. 记录文档版本和未覆盖能力

每一步都要留下可复核产物：文件、命令、截图、请求、任务ID、数据库记录、指标或决策记录。

7. 标准交付物

• 版本化契约和字段映射
• 适配器、认证和错误映射
• 幂等、限流、重试和死信
• 契约测试与录制回放样本
• 可观测性和降级策略

8. 历史中常见失败写法

• 只根据一份示例响应写解析器
• 收到202/queued却当作业务完成
• 分页只取第一页
• 字段缺失导致整个批次失败
• Webhook未验签/未去重
• 第三方限流触发无限重试

修正提示词

当前结果未满足验收。不要整体重做，先按证据定位差距。

原目标：【目标】
原验收：【可观察标准】
实际结果：【截图/日志/请求/任务ID/数据库记录】
差距：【逐条列出】
必须保持：【已正确部分和接口不变量】

请先复现并说明根因，再实施最小修正。修正后重复原验证，并给出修改前后证据。未通过的项继续保留为失败，不要用“基本完成”代替。

9. 完成检查清单

• 目标、范围和不做项没有漂移。
• 关键假设已用代码、运行或数据验证。
• 成功、失败、空、重复、超时和权限路径已处理。
• 交付物可由另一人独立打开或运行。
• 验收命令/路径已实际执行并保留证据。
• 未完成项、风险和数据限制被明确列出。
• 下游岗位得到接口、不变量、文件和验证入口。

10. 交接模板

岗位：API与系统集成工程师
已完成：【内容】
证据：【文件、命令、截图、日志、任务ID、数据库记录或指标】
接口与不变量：【下游必须遵守】
配置/迁移影响：【内容】
未完成与风险：【内容、严重度、负责人】
下一岗位：【岗位】
下一步输入：【精确文件、环境、账号或任务】
禁止假设：【仍未知内容】

11. 实用组合技巧

• 真实响应自动生成契约样本：保存脱敏的成功、失败、空字段和未知字段响应，让契约 Agent 自动生成解析与兼容测试。
• 第三方API包一层稳定适配器：外部字段变化只修改适配层，内部前端、后端和数据模型继续使用稳定契约。
• Webhook自动验签去重：让集成 Agent 同时生成验签、幂等、重放和乱序测试，不只实现正常回调。
• API录制回放：在测试环境录制脱敏响应，日常开发用回放减少外部配额和不稳定性，上线前再做真实沙箱验证。
• 文档变化自动预警：定期让 Agent 对比第三方文档/Schema 版本，输出新增、删除、类型变化和兼容影响。