chendelian
4fe1351e1e
All checks were successful
技能自动化发布 / release (push) Successful in 9s
Co-authored-by: Cursor <cursoragent@cursor.com>
44 lines
2.3 KiB
Markdown
44 lines
2.3 KiB
Markdown
# v1 调用方兼容承诺（account-manager v2）
|
||
|
||
account-manager v2 **不破坏**下列面向脚本 / 其它仓库（通过 CLI subprocess 集成）的契约。
|
||
|
||
## CLI 命令
|
||
|
||
下列命令的**子命令名与既有必填参数**保持不变（v2 仅 **扩展** 可选参数，不移除）：
|
||
|
||
- `account pick-web` / `lease release` / `account mark-used` / `account mark-session` / `account mark-error`
|
||
- `account get` / `account list` / `account add-web` / `account add-secret`
|
||
- 兼容入口：`get`、`list-json`、`pick-web`、`add`、`delete`、`open`
|
||
|
||
加密相关：`account init-master-key` / `account export-credentials` / `account import-credentials`（**仅新增**，不影响旧调用方）。
|
||
|
||
内置 `--help` / 无参数打印的 `_USAGE` 文案见仓库 `scripts/cli/app.py`（阶段 F 已与路由对齐）。
|
||
|
||
## JSON 字段
|
||
|
||
- **`account pick-web`**：成功时为 **单层 JSON 对象**（**无** `success`/`data` 外层）。保留字段包括但不限于：`id`、`platform_key`、`environment`、`role`、`profile_dir`、`lease_token`、`lease_expires_at`（带 `--lease` 时）。v2 **允许追加**字段（如 `auth_strategy`、`session_persistent`、`device_fingerprint`），**不得改名或删除**上述 v1 字段。
|
||
- **`account get`**：仍为单行账号 JSON（字段集合见 [SCHEMA.md](SCHEMA.md)）。
|
||
- **`lease release` / `account mark-*`**：成功时使用 `_ok_json`（`{"success": true, "data": {...}}`）；失败为统一错误 JSON。
|
||
|
||
## 错误码
|
||
|
||
下列 **`error.code` 字面值**保持不变：
|
||
|
||
- `ERROR:NO_ACCOUNT`
|
||
- `ERROR:LEASE_CONFLICT`
|
||
- `ERROR:ACCOUNT_NOT_FOUND`
|
||
- `ERROR:INVALID_PLATFORM`
|
||
- `ERROR:ACCOUNT_DISABLED`
|
||
- `ERROR:DB_ERROR`
|
||
|
||
v2 新增的 `ERR_*` 代码（如 `ERR_LEASE_INVALID`、`ERR_AUTH_STRATEGY_NOT_SUPPORTED`）仅出现在 **v2 新命令**路径，不应干扰上述 monitor 命令的失败解析。
|
||
|
||
## stderr
|
||
|
||
v2 可能在 stderr 打印迁移摘要、`[export] WARNING` 等。**调用方应只解析 stdout**，并与 monitor 一样优先取 **最后一行非空行** 做 `json.loads`（见集成测试 `tests/test_v1_compatibility.py`）。
|
||
|
||
## 集成验证
|
||
|
||
- 仓库内 **`tests/test_v1_compatibility.py`** 以 subprocess 覆盖典型调用序列与 stdout 形态。
|
||
- 已知调用方：**`monitor-competitor-rates`**（物流仓库）—— 仅 CLI，无 Python import。
|