account-manager/references/V1_COMPATIBILITY.md

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）。
• 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。