不少开发者在编写接口对接文档时，常常陷入“告知对方如何调用”的套路——结果合作方的技术人员依然反复追问“字段来源”“签名算法”“超时重试次数”。真正能落地的接口说明，必须明确谁提供什么、谁验证什么、失败后如何定位、哪些步骤需要双方同步确认，并逐条固化。以下这套提示词写法，可直接用于让Trae生成一份交给合作方技术对接人的完整文档。

明确对接角色与责任边界

第一步，锁定双方身份和交付物。提示词开头就要写清楚：“作为甲方系统（订单中心），需向乙方物流系统（运单查询服务）提供运单号列表并获取实时轨迹；乙方负责提供接口地址、签名规则文档、测试环境Token，甲方负责按约定格式拼接请求体、实现验签逻辑。”这一步若不明确谁出什么，Trae默认生成单边视角的文档，例如遗漏“乙方需在3个工作日内提供正式环境公钥”这类关键交付承诺。

第二步，强制要求输出权责对照表。追加指令：“输出表格，列名：事项｜甲方动作｜乙方动作｜完成标志｜超期后果；事项包括：接口地址交付、签名密钥交换、联调账号开通、压测报告互认。”若未写明超期后果，Trae不会自动补全——比如“乙方延迟交付密钥导致甲方无法启动开发，上线计划顺延”这类刚性约束必须写进提示词里。

绑定真实签名流程与验签细节

方法一：直接贴出乙方提供的原始签名说明片段。例如粘贴：“HMAC-SHA256算法，密钥为base64编码字符串，待签字符串为method+path+query+body（不含空格与换行），body需JSON序列化后去除所有空白符。”然后写：“请将上述规则转为甲方开发可执行的验签步骤，每步含命令或代码片段”。举个例子：curl -X POST https://api.logistics.com/v1/tracks → 提取body → python3 -c "import json,hashlib,base64; d=json.loads('{"sn":["SN123"]}') ; s='POST/track?env=test'+json.dumps(d,separators=(',',':')) ; print(base64.b64encode(hashlib.sha256((s+'SECRET_KEY').encode()).digest()).decode())"。这样Trae能生成可直接复制运行的验证命令。

方法二：指定错误场景反推校验点。输入：“当甲方调用返回code=401且message='invalid signature'时，请列出5个最可能的验签失败原因，并标注每个原因对应的排查命令”。例如：① 待签字符串中body未去空格 → 检查json.dumps(..., separators=(',', ':'))是否生效；② 时间戳超过5分钟有效期 → 用date -u +%s验证本地时间是否偏差过大。Trae会根据场景输出针对性的排查链路，而不是泛泛的“检查签名”。

定义联调闭环动作与交付物

这一步的操作其实很简单，直接把以下四条闭环动作复制进项目排期表即可：

① 甲方提供最小可行请求体（含真实运单号SN123456789）→ 乙方返回完整轨迹JSON → 双方确认响应中status字段值为"delivered"且update_time晚于2026-07-01。

② 乙方提供签名密钥及测试Token → 甲方用该密钥生成签名 → 调用/v1/auth/verify接口验证签名有效性 → 返回{"valid":true}视为通过。

③ 压测阶段：甲方发起1000次并发请求 → 乙方监控QPS与错误率 → 若5xx错误率＞0.1%或平均响应＞800ms，立即暂停并邮件同步根因。注意，这里的“5xx错误率＞0.1%”必须写死数字，不能写“极低比例”，否则Trae会模糊处理成“少量错误”。

④ 正式上线前：乙方提供生产环境证书链文件 → 甲方将证书导入Java truststore → 运行openssl s_client -connect api.logistics.com:443 -CAfile prod.crt验证握手成功。