Release v1.0.56: Credential & Browser Profile Manager

references/ERRORS.md

@@ -1,8 +1,20 @@
-# 终端前缀约定（account-manager）
+# 终端错误码（account-manager）
 
 约定：**机器解析只依赖 `stdout` 首行**时，应先判断首行是否以 `ERROR:` 开头；多行说明可忽略或仅作展示。
 
-## `ERROR:` — CLI 参数 / 路由
+## 新增机器 JSON 失败格式
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "ERROR:...",
+    "message": "..."
+  }
+}
+```
+
+## ERROR:CLI — CLI 参数 / 路由
 
 | 前缀 | 含义 |
 |------|------|
@@ -13,31 +25,55 @@
 | `ERROR:CLI_DELETE_BAD_MODE` | `delete` 第二段不是 `id`/`platform` |
 | `ERROR:CLI_LIST_JSON_MISSING_PLATFORM` | `list-json` 缺少平台参数 |
 | `ERROR:CLI_PICK_WEB_MISSING_ARGS` | `pick-web` 缺少平台 |
+| `ERROR:CLI_BAD_ARGS` | 子命令参数缺失或非法 |
 | `ERROR:CLI_UNKNOWN_OR_BAD_ARGS` | 无法识别的子命令或参数组合 |
 
-## `ERROR:` — 业务与数据
+## ERROR: — 数据库
 
 | 前缀 | 含义 |
 |------|------|
-| `ERROR:INVALID_PLATFORM_LIST` | `list` 的平台名无法识别 |
-| `ERROR:INVALID_PLATFORM_LIST_JSON` | `list-json` 的平台名无法识别 |
-| `ERROR:INVALID_PLATFORM` | 其它子命令中平台无法识别 |
-| `ERROR:NO_ACCOUNTS_FOUND` | 列表无结果（或 `delete platform` 下无记录） |
-| `ERROR:ACCOUNT_NOT_FOUND` | 指定 id/记录不存在 |
-| `ERROR:PHONE_REQUIRED` | 缺少手机号 |
-| `ERROR:PHONE_INVALID` | 手机号格式不符合大陆 11 位规则 |
-| `ERROR:DUPLICATE_PHONE_PLATFORM` | 同平台下山手机号已存在 |
-| `ERROR:DELETE_INVALID_ID` | 删除 id 非法 |
-| `ERROR:NO_ACCOUNT` | `pick-web` 该平台无任何记录 |
+| `ERROR:DB_ERROR` | SQLite 写入失败等 |
 
-## `ERROR:` — 浏览器 / 环境
+## ERROR: — 平台与账号
 
 | 前缀 | 含义 |
 |------|------|
-| `ERROR:需要 playwright Python 包：…` | 未安装 `playwright` 包，或本机无 Chrome/Edge（channel 模式，**不**需 `playwright install chromium`） |
+| `ERROR:INVALID_PLATFORM` | 平台名无法识别 |
+| `ERROR:NO_ACCOUNTS_FOUND` | 列表无结果 |
+| `ERROR:ACCOUNT_NOT_FOUND` | 指定 id 不存在 |
+| `ERROR:ACCOUNT_DISABLED` | 账号状态为 disabled |
+| `ERROR:NO_ACCOUNT` | `pick-web` 无符合条件的可用账号（含：均被 active 未过期 lease 占用时） |
+
+## ERROR: — 租约
+
+| 前缀 | 含义 |
+|------|------|
+| `ERROR:LEASE_CONFLICT` | 同账号已有 active 未过期 lease |
+| `ERROR:LEASE_NOT_FOUND` | 未找到活跃租约 |
+| `ERROR:LEASE_EXPIRED` | 租约已过期 |
+
+## ERROR: — 凭据与 Secret
+
+| 前缀 | 含义 |
+|------|------|
+| `ERROR:CREDENTIAL_NOT_FOUND` | 凭据不存在 |
+| `ERROR:CREDENTIAL_DISABLED` | 凭据不可用 |
+| `ERROR:SECRET_STORAGE_UNSUPPORTED` | 不支持的 secret 存储方式 |
+| `ERROR:SECRET_REF_MISSING` | env 存储缺少环境变量名 |
+| `ERROR:SECRET_READ_FAILED` | 读取 secret 失败 |
+| `ERROR:SECRET_WRITE_FAILED` | 写入 secret 失败 |
+| `ERROR:SECRET_ENV_MISSING` | 环境变量未设置 |
+| `ERROR:WINDOWS_CREDENTIAL_UNAVAILABLE` | 非 Windows 平台不支持 |
+
+## ERROR: — 浏览器 / 环境
+
+| 前缀 | 含义 |
+|------|------|
+| `ERROR:需要 playwright Python 包` | 未安装 `playwright` 包或本机无 Chrome/Edge |
 | `ERROR:PROFILE_DIR_MISSING` | 账号记录中 `profile_dir` 为空 |
 
 ## 非前缀输出
 
-- **成功添加账号**、**删除成功**等可能包含 `✅` 等人类可读行，**不宜**作为稳定协议解析。
-- **`get` / `list-json` / `pick-web` 成功**：`stdout` 应为**单行 JSON**（失败时首行 `ERROR:`，勿当 JSON）。
+- **`get` / `list-json` / `pick-web`** 成功时：`stdout` 应为**单行 JSON**。
+- 失败时首行 `ERROR:`，可能有后续说明行。
+- **新增机器命令建议统一 JSON 输出**，旧兼容命令可继续输出 `ERROR:` 文本前缀。