7fa9018d53
The svc.plus review password and the two bridge tokens were committed in plaintext across the manual case / API test docs. Replace every value with a `.env` / secret-store reference and add a tracked .env.example template. Harden .gitignore (.env.*, *.local.env, secrets.env) while keeping !.env.example. Note: git history was rewritten separately to purge the leaked values; the credentials must be rotated regardless. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
109 lines
3.3 KiB
Markdown
109 lines
3.3 KiB
Markdown
# 外部服务 API 脚本运行说明
|
||
|
||
Last Updated: 2026-04-22
|
||
|
||
本文说明 `xworkmate-app` 里两份外部服务 API 测试脚本的用途、执行方式和适用边界。
|
||
|
||
## 1. 脚本列表
|
||
|
||
### 1.1 API 接口测试脚本
|
||
|
||
- [`scripts/ci/verify_api_interface_contract.sh`](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-app/scripts/ci/verify_api_interface_contract.sh)
|
||
|
||
用途：
|
||
|
||
- 校验账户服务与 bridge 主入口的接口契约
|
||
- 重点验证请求路径、鉴权头、返回结构和能力面数据
|
||
|
||
### 1.2 场景测试脚本
|
||
|
||
- [`scripts/ci/verify_api_scenario_contract.sh`](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-app/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`
|
||
|
||
凭据从本地 `.env`（已 gitignore）或 secret store 注入，**不要把明文密码/Token 写进文档或命令历史**。先准备 `.env`（参考仓库根目录 `.env.example`），再 `source` 后运行：
|
||
|
||
```bash
|
||
set -a; source .env; set +a # 载入 REVIEW_ACCOUNT_LOGIN_PASSWORD / BRIDGE_AUTH_TOKEN 等
|
||
bash scripts/ci/verify_api_interface_contract.sh
|
||
```
|
||
|
||
如需单条命令显式注入，使用变量引用而非明文：
|
||
|
||
```bash
|
||
REVIEW_ACCOUNT_LOGIN_PASSWORD="$REVIEW_ACCOUNT_LOGIN_PASSWORD" \
|
||
BRIDGE_AUTH_TOKEN="$BRIDGE_AUTH_TOKEN" \
|
||
BRIDGE_SERVER_URL='https://xworkmate-bridge.svc.plus' \
|
||
bash scripts/ci/verify_api_interface_contract.sh
|
||
```
|
||
|
||
双入口验证示例：
|
||
|
||
```bash
|
||
REVIEW_ACCOUNT_LOGIN_PASSWORD="$REVIEW_ACCOUNT_LOGIN_PASSWORD" \
|
||
BRIDGE_SERVER_URLS='https://xworkmate-bridge.svc.plus,https://cn-xworkmate-bridge.svc.plus' \
|
||
bash scripts/ci/verify_api_interface_contract.sh
|
||
```
|
||
|
||
## 3. 默认校验入口
|
||
|
||
推荐使用 `Makefile` 目标：
|
||
|
||
```bash
|
||
make test-api-contract
|
||
make test-api-scenario-contract
|
||
```
|
||
|
||
如果需要一次性执行两份脚本，可使用：
|
||
|
||
```bash
|
||
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 真源；它只作为可选显式输入
|
||
|
||
## 6. 相关文档
|
||
|
||
- [APP 对接外部服务 API 接口测试详细清单](./app-external-service-api-test-matrix.md)
|
||
- [XWorkmate 测试规范模板与指南](./xworkmate-test-spec.md)
|
||
- [测试 Case 覆盖矩阵](./test-case-coverage-matrix.md)
|