外部服务 API 脚本运行说明

Last Updated: 2026-04-22

本文说明 xworkmate-app 里两份外部服务 API 测试脚本的用途、执行方式和适用边界。

1. 脚本列表

1.1 API 接口测试脚本

scripts/ci/verify_api_interface_contract.sh

用途：

校验账户服务与 bridge 主入口的接口契约
重点验证请求路径、鉴权头、返回结构和能力面数据

1.2 场景测试脚本

scripts/ci/verify_api_scenario_contract.sh

用途：

按真实使用链路跑完整场景
重点验证登录 -> 同步 -> 能力 -> 路由 -> 会话启动 / 续跑 / 取消 / 关闭

2. 运行前提

两份脚本都依赖以下环境变量：

REVIEW_ACCOUNT_LOGIN_PASSWORD
可选 BRIDGE_AUTH_TOKEN，未提供时使用 profile sync 返回的 token
可选 BRIDGE_SERVER_URL
可选 BRIDGE_SERVER_URLS，用于接口脚本同时验证多个 bridge host
可选 REVIEW_ACCOUNT_BASE_URL

推荐直接在命令前临时注入：

REVIEW_ACCOUNT_LOGIN_PASSWORD='***REMOVED-CREDENTIAL***' \
BRIDGE_AUTH_TOKEN='<bridge token>' \
BRIDGE_SERVER_URL='https://xworkmate-bridge.svc.plus' \
bash scripts/ci/verify_api_interface_contract.sh

双入口验证示例：

REVIEW_ACCOUNT_LOGIN_PASSWORD='***REMOVED-CREDENTIAL***' \
BRIDGE_SERVER_URLS='https://xworkmate-bridge.svc.plus,https://cn-xworkmate-bridge.svc.plus' \
bash scripts/ci/verify_api_interface_contract.sh

3. 默认校验入口

推荐使用 Makefile 目标：

make test-api-contract
make test-api-scenario-contract

如果需要一次性执行两份脚本，可使用：

make check-api-external

4. 脚本覆盖内容

4.1 `test-api-contract`

POST /api/auth/login
GET /api/auth/session
GET /api/auth/xworkmate/profile/sync
GET /api/ping
POST /acp/rpc with acp.capabilities
POST /acp/rpc with xworkmate.routing.resolve

4.2 `test-api-scenario-contract`

登录与会话确认
profile sync 元数据读取
bridge capabilities 拉取
routing resolve
session.start
session.message
session.cancel
session.close

5. 已知行为

session.start / session.message 在当前环境下可能返回下游连接失败，这不代表脚本失效
只要脚本正确拿到 JSON-RPC 返回并解析出结果，就认为脚本可用
脚本不会把 BRIDGE_SERVER_URL 当成 runtime 真源；它只作为可选显式输入

2.9 KiB Raw Blame History

外部服务 API 脚本运行说明

1. 脚本列表

1.1 API 接口测试脚本

1.2 场景测试脚本

2. 运行前提

3. 默认校验入口

4. 脚本覆盖内容

4.1 test-api-contract

4.2 test-api-scenario-contract

5. 已知行为

6. 相关文档

2.9 KiB

Raw Blame History

4.1 `test-api-contract`

4.2 `test-api-scenario-contract`