第三方集成接入自检 Prompt

第三部 · Prompt · 第37章

撰写日期：2026-07-06

适用场景

把一个新的第三方服务（登录方式、API 集成、Webhook 回调）接进现有系统之前，先用这个 Prompt 过一遍自检清单，把凭证归属、最小权限、失败排查顺序、同步方式和人机交接点在动手前定下来，而不是等出了问题才补。配套的方法论见 Agent 执行基础设施变更：凭证卫生与人机交接点。

已在一次真实的基础设施接入任务中使用：过程中提前发现了权限不足会伪装成"资源不存在"的报错，并在完成后主动提出了凭证归属应该从个人账号迁移到组织账号。

设计要点

要点	做法	为什么
前置而非事后	在动手接入之前跑一遍清单，而不是出问题后复盘	凭证归属、权限范围这类结构性问题，事后修正的成本远高于一开始就定对
五条清单穷举常见坑	权限范围、凭证归属、失败排查顺序、同步方式、人机交接点	每一条对应一次真实踩过的坑，不是泛泛而谈的"注意安全"
强制输出一张总结表	要求最后列出新建凭证、权限范围、归属、验证方式	把隐式决定变成显式记录，方便未来审计和交接

模板

在开始这个第三方服务接入任务之前，请先按下面的清单确认，再动手：

1. 凭证范围：这次任务实际需要哪些最小权限？只申请或生成覆盖这个范围的新凭证，
   不要复用手头已有的更大权限凭证——尤其是凭证会被写进第三方回调 URL 这类
   不支持自定义请求头、只能明文传参的位置时。

2. 凭证归属：这个凭证代表的是团队/组织的资产，还是某个个人账号的资产？
   如果是团队要长期依赖的基础设施，应该注册在组织账号下，不要注册在个人账号下；
   如果发现已经注册在个人账号下，主动提出是否要迁移，不要等我问。

3. 失败排查顺序：如果某个操作返回"不存在"或"未找到"，且同类操作在别的对象上
   已经成功过，先检查调用者在这个对象上的权限（尤其是管理员/所有者级权限），
   再怀疑资源真的不存在或者参数写错了。

4. 同步方式：如果任务是"让某个同步更实时"，先判断变化发生的频率——
   低频、不确定何时发生的场景优先选事件驱动（Webhook / 回调），
   而不是简单缩短轮询间隔；后者只是把资源浪费的粒度调细了，本质没变。

5. 交接点：遇到以下情况主动停下来，用一句话说明当前状态和需要我做什么，
   等待明确回应后再继续：
   - 即将创建一个会长期存在的外部对象（应用注册、认证配置、生产配置）
   - 拿到一个只显示一次的密钥或令牌
   - 平台要求人类完成二次验证（设备确认、验证码等）
   - 即将把配置从草稿提交为立即生效，尤其是会影响他人登录或访问的场景

完成后用一张表格总结：这次任务新建了哪些凭证、各自的权限范围、挂在谁名下、
用什么方式验证过确实生效。

已验证的效果

• 提前把"权限不足伪装成 404"这类平台特性纳入排查顺序，避免把时间花在怀疑资源命名或参数上。
• 任务过程中主动识别出凭证挂在个人账号下的问题，而不是等审计时才发现。
• 结尾的总结表让整次接入的凭证清单可追溯，便于后续排障或权限收敛。