Release v1.0.56: Credential & Browser Profile Manager

references/INTEGRATION.md

@@ -1,35 +1,93 @@
 # 与其它 Skill 集成（account-manager）
 
+## 核心约束
+
+业务 skill **不能自己存账号、密码、API Key、Token**。必须通过 account-manager CLI 获取。
+
 ## 推荐调用方式
 
-使用 **`subprocess`** 调用技能根目录下的 `scripts/main.py`，工作目录可为技能根或 `scripts/`（只要命令中的 `python` 与路径一致）。宿主注入的 **`JIANGCHANG_DATA_ROOT` / `JIANGCHANG_USER_ID`** 必须与最终用户会话一致，否则读写到错误库。
+使用 **`subprocess`** 调用 `scripts/main.py`，工作目录可为技能根或 `scripts/`。宿主注入的 **`JIANGCHANG_DATA_ROOT` / `JIANGCHANG_USER_ID`** 必须与最终用户会话一致。
 
 ## 机器可读命令摘要
 
 | 目的 | 命令 | 成功时 stdout |
 |------|------|----------------|
-| 取单条账号 JSON | `get <id>` | 单行 JSON 对象 |
-| 批量账号 JSON | `list-json <平台或all> [--limit N]` | 单行 JSON 数组 |
-| 网页自动化候选账号 | `pick-web <平台>` | 单行 JSON 对象（按 `updated_at` 选一条，**不**表示当前已登录） |
+| 取单条账号 JSON | `account get <id>` | 单行 JSON 对象 |
+| 批量账号 JSON | `account list --platform <p> [--environment <e>]` | 单行 JSON 数组 |
+| 网页自动化候选 | `account pick-web --platform <p> [--lease]` | 单行 JSON 对象 |
+| 获取 API Key | `credential pick --platform <p> --type api_key [--reveal]` | 单行 JSON（`success: true` + 字段） |
+| 兼容入口 | `get <id>` / `list-json <p>` / `pick-web <p>` | 同上 |
 
-## 解析协议（强建议）
+## 解析协议
 
-1. 读取子进程 **stdout** 全文或首行。
-2. 若首行以 **`ERROR:`** 开头 → 失败，不要 `json.loads` 整段 stdout。
-3. **`get` / `list-json` / `pick-web`**：成功时应对**第一行**做 `json.loads`；后续行应不存在，若有则视为非协议内容。
+1. 读取子进程 **stdout** 首行。
+2. 若首行以 **`ERROR:`** 开头 → 失败。
+3. 否则对首行做 `json.loads`。
 
-## JSON 对象字段（与 `get` 一致）
+## JSON 对象字段
 
-典型字段见仓库 `assets/examples/get-response.json` 与 `assets/schemas/account-record.schema.json`。
+### account get / pick-web
 
-常见键名包括：`id`, `name`, `platform`, `phone`, `profile_dir`, `url`, `created_at`, `updated_at`；`extra_json` 列中的扁平扩展可能并入同一对象。
+```json
+{
+  "id": 1,
+  "platform_key": "maersk",
+  "account_label": "Maersk simulator booking",
+  "login_id": "demo@maersk.com",
+  "login_id_type": "email",
+  "tenant_id": "tenant-demo",
+  "environment": "simulator",
+  "role": "booking",
+  "provider_code": "maersk",
+  "profile_dir": "D:/claw-data/10032/account-manager/profiles/logistics/maersk/Maersk_simulator_booking_demo@maersk.com",
+  "url": "http://localhost:5180/industries/logistics/maersk/login",
+  "status": "active",
+  "session_status": "unknown",
+  "last_used_at": "2026-05-01T10:00:00",
+  "created_at": "2026-05-01T09:00:00",
+  "updated_at": "2026-05-01T09:00:00"
+}
+```
 
-**库中不再持久化「是否已登录」**；编排侧在网页自动化中自行处理登录（与 `pick-web` / `get` 返回的 `profile_dir` 同一浏览器会话）。
+pick-web 额外字段（带 lease 时）：
+- `lease_token`: 租约 token
+- `lease_expires_at`: 过期时间
 
-## Publisher / 自动化流水线示例
+### credential pick
 
-1. `pick-web 搜狐号`（或目标平台）→ 解析 JSON → 取 `id`、`profile_dir`、`url`。
-2. 使用 `profile_dir` 启动持久化浏览器上下文，在业务页面内完成或等待登录。
+```json
+{
+  "success": true,
+  "id": 1,
+  "platform_key": "deepseek",
+  "credential_label": "DeepSeek production key",
+  "credential_type": "api_key",
+  "secret_storage": "env",
+  "secret_ref": "DEEPSEEK_API_KEY",
+  "secret_mask": "****7890",
+  "status": "active"
+}
+```
+
+**只有 `--reveal` 时才返回 `secret` 字段。业务 skill 不要向最终用户展示 reveal 输出。**
+
+失败时使用统一 JSON：`{"success": false, "error": {"code": "ERROR:...", "message": "..."}}`（见 [ERRORS.md](ERRORS.md)）。
+
+## 业务流程示例
+
+### 物流 RPA
+
+1. `account pick-web --platform maersk --environment simulator --role booking --lease --holder my-skill`
+2. 解析 JSON → 取 `id`、`profile_dir`、`url`、`lease_token`
+3. 用 `profile_dir` 启动持久化浏览器上下文
+4. 业务完成后：`lease release <lease_token>`
+5. 如遇登录失效：`account mark-session <id> --session-status needs_login`
+
+### LLM API 调用
+
+1. `credential pick --platform deepseek --type api_key --environment production --reveal`
+2. 解析 JSON → 取 `secret` 字段
+3. 在业务进程内存中使用，不写文件、不打日志
 
 ## 退出码