# 与其它 Skill 集成（account-manager）

## 核心约束

业务 skill **不能自己存账号、密码、API Key、Token**。必须通过 account-manager CLI 获取。

## 推荐调用方式

使用 **`subprocess`** 调用 `scripts/main.py`，工作目录可为技能根或 `scripts/`。宿主注入的 **`JIANGCHANG_DATA_ROOT` / `JIANGCHANG_USER_ID`** 必须与最终用户会话一致。

## 机器可读命令摘要

| 目的 | 命令 | 成功时 stdout |
|------|------|----------------|
| 取单条账号 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:`** 开头 → 失败。
3. 否则对首行做 `json.loads`。

## JSON 对象字段

### account get / pick-web

```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 额外字段（带 lease 时）：
- `lease_token`: 租约 token
- `lease_expires_at`: 过期时间

### credential pick

```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. 在业务进程内存中使用，不写文件、不打日志

## 退出码

请以 **stdout 首行前缀** 与 **JSON 可解析性** 为准；不要仅依赖退出码。