95 lines
3.1 KiB
Markdown
95 lines
3.1 KiB
Markdown
# 与其它 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 可解析性** 为准；不要仅依赖退出码。
|