本地联调：命令行 cop-cli 与本地 AI 助手

如果你习惯命令行，或者要把联调写进脚本，直接装 cop-cli——它自己就能用；本机已有 AI 编程助手的，再装两份技能就是能力最全的形态。三种联调形态的对比见 联调工具与 AI 助手。

安装

# macOS / Linux
curl -fsSL https://open.caocaokeji.cn/asset/cop-cli/install.sh | sh

# Windows PowerShell
irm https://open.caocaokeji.cn/asset/cop-cli/install.ps1 | iex

之后升级只要一条命令：

cop-cli update

配上本地 AI 助手：两份技能

如果你本机已经在用 AI 编程助手（Claude Code、Cursor、Codex、Gemini 等），装完 cop-cli 后再执行一条命令：

cop-cli skill setup

它会在你的项目目录下装出两份技能，让你的 AI 助手立刻知道"曹操开放平台怎么对接、cop-cli 怎么用"。

技能	它会做什么	什么时候找它
对接助手 cop-integration	回答接口/签名/回调/错误码问题；帮你选定流程；按流程在你的工程里生成最小可用 SDK	正在写对接代码，或还在决定方案
联调助手 cop-order-testing	陪你把联调场景一层层问清楚再切换；跑完整条订单闭环；造沙箱测试司机；报错时给出下一步	代码写完了，要实际跑单验证

举几个真实说法

对对接助手说：

• 「我用 Java + Spring，帮我把最短的用车下单流程封一个 SDK 出来」
• 「我们要同时对接多家运力，这个流程我该怎么设计？」
• 「我的签名算出来和你的不一样，帮我对一下」

对联调助手说：

• 「帮我把这个应用切成需要确认接单的场景」
• 「跑一单，司机举手后帮我确认接单」
• 「叫了单没人接，帮我查是哪里不对」

为什么值得装

• 知识随时同步：对接助手用的是随时更新的官方知识库，不靠模型记忆编答案，回答会给出引用的文档。
• 代码贴着你的工程：生成 SDK 不会硬塞你没用过的依赖，签名统一收口在一个类里，生成后还会先对拍签名、再对沙箱真调一次只读接口做验证。
• 联调不靠猜：卡住时按固定检查清单逐项排除，而不是反复重试同一条命令。
• 版本不会错配：技能内容随 cop-cli 一起分发，cop-cli update 会自动重装，两边永远同版本。

---

三步走通一单

下面这些命令你可以自己敲，也可以直接让装了技能的 AI 助手替你敲。

# 1. 登录（浏览器完成验证，凭据存在本机）
cop-cli auth login

# 2. 选定要联调的沙箱应用
cop-cli account app list
cop-cli account app use <client_id>

# 3. 存两个常用地点，然后叫一单
cop-cli place add 公司 --name 曹操总部 --address 杭州市滨江区 --lat 30.18 --lng 120.20 --city-code 0571
cop-cli place add 东站 --name 杭州东站 --address 天城路1号 --lat 30.29 --lng 120.21 --city-code 0571

cop-cli order create --from @公司 --to @东站 --yes

拿到订单号后：

cop-cli order detail --order-no <订单号>      # 看当前状态
cop-cli order cancel --order-no <订单号> --yes # 取消

切换联调场景

场景是一组预先配好的联调条件的组合——是否走预锁定（司机举手后再确认接单）、取消订单是否收取消费、开票方式、支付方式等。想验哪条流程，就把应用切到对应场景，不用逐项去改配置。

cop-cli app config show          # 先看当前应用的配置和所处场景
cop-cli app scenario list        # 列出可切换的场景
cop-cli app scenario use <场景名> --yes

scenario list 的每个场景都带 title、description 和 affects——affects 说明这次切换会连带影响什么，切换前务必先看它。场景清单由平台侧维护，会随能力增加而变化，所以不要把场景名写死进脚本，每次先 list。

切完再 app config show 确认已生效。不带 --yes 时只打印将要提交的变更预览、不真正切换（见下方「两道安全闸门」）。

⚠️ 预锁定相关的切换代价很高：它决定了回调里 event=1 是"订单已成立"还是"司机只是举手"——切换后你这边处理回调的逻辑要跟着改，双方都要重新联调。建议在对接初期就定下来，不要中途变更。这条流程本身见 确认接单，回调事件取值见 订单状态及类型。

用云端或本地 AI 助手时不用记命令，直接说「把这个应用切成需要确认接单的场景」，它会先把场景问清楚、给出影响面再切。

接口权限自己开

每篇接口文档的「沙箱API ID」就是给这里用的。想调某个接口却报未授权时：

cop-cli app api add --api-id <沙箱API ID> --yes

开通即时生效，网关配置最多 60 秒同步完成。

一单从头到尾长什么样

这里有一个必须知道的事实：从"司机接单"到"待支付"之间的每一步——出发接乘客、到达上车点、开始计费、结束计费、结算——没有命令可以代替，要用沙箱司机账号登录司机端 App 实际走一遍。命令行这边用 order detail 观察状态变化。

沙箱司机也能一条命令造出来

沙箱司机有三种创建方式，效果完全一样（同一套数据，造出来的司机都能登录司机端 App）：

方式	怎么做
命令行	cop-cli driver create --city-code 0571 --service-type 2 --yes
云端 / 本地 AI 助手	直接说「给我造一个杭州的沙箱司机」
网页	开发者管理中心 → 沙箱应用 → 调试 → 接单调试，见 请求域名及测试司机端

命令会返回司机手机号，用它登录司机端 App（验证码任意 4 位数字）。查看当前应用下已有的沙箱司机：

cop-cli driver show

造司机时的城市和车型必须和叫单参数对齐，否则派不到单。不想让司机跑到起点附近，可以让他必接这个应用的单：

cop-cli driver force-accept enable --yes

注意它只免掉「位置」这一项——城市、车型、司机是否已上线仍要对齐。司机端 App 的下载与登录、以及完整的"无法接单自检清单"见 请求域名及测试司机端。

两道安全闸门

闸门	作用
--dry-run	只打印将要发出的请求，不真正调用。想先看看参数对不对时加上它
--yes	取消、改费、改配置这类操作不带 --yes 时只给预览，加上才真正执行

输出是 JSON，方便进脚本

成功走标准输出，失败走标准错误，格式固定，错误里带可执行的下一步提示。配合 --jq 可以直接取某个字段：

cop-cli order create --from @公司 --to @东站 --yes --jq .order_no