217 lines
11 KiB
Markdown
217 lines
11 KiB
Markdown
# account-manager 接入标准（账号 / Profile / 租约）
|
||
|
||
> 本文是浏览器 RPA 技能接入账号体系的统一标准。开发者和 AI 编程工具在编写 `account_client.py`、处理多账号、排查登录状态或验收浏览器任务前，必须阅读本文。
|
||
|
||
## 目录
|
||
|
||
- [1. 为什么必须依赖 account-manager](#1-为什么必须依赖-account-manager)
|
||
- [2. 核心模型](#2-核心模型)
|
||
- [3. 强制规则](#3-强制规则)
|
||
- [4. 标准生命周期](#4-标准生命周期)
|
||
- [5. 账号选择与多账号](#5-账号选择与多账号)
|
||
- [6. 创建后去哪里查看](#6-创建后去哪里查看)
|
||
- [7. 登录状态与 Profile 验收](#7-登录状态与-profile-验收)
|
||
- [8. 租约与异常退出](#8-租约与异常退出)
|
||
- [9. 工业级测试](#9-工业级测试)
|
||
- [10. 排障顺序与提问证据](#10-排障顺序与提问证据)
|
||
- [11. 安全边界](#11-安全边界)
|
||
|
||
## 1. 为什么必须依赖 account-manager
|
||
|
||
真实用户会长期使用同一个账号，也会在批量发布、矩阵运营、多店铺、多租户等场景中使用多个账号。一次打开临时浏览器、成功操作一两条数据，不能证明技能可交付。
|
||
|
||
account-manager 统一负责：
|
||
|
||
- 账号身份及平台归属；
|
||
- 一账号一份持久化浏览器 Profile；
|
||
- Cookie、会话和登录状态的持续复用；
|
||
- 多任务之间的账号租约与并发互斥；
|
||
- 账号状态、最近错误和运维排查入口。
|
||
|
||
业务技能只负责编排业务动作，不得再造一套账号库，也不得随意找一个浏览器目录直接运行。
|
||
|
||
## 2. 核心模型
|
||
|
||
| 对象 | 含义 | 业务技能应如何使用 |
|
||
|------|------|--------------------|
|
||
| `account` | 某个平台上的一个账号身份 | 通过 account-manager CLI 获取，不自行落库 |
|
||
| `profile_dir` | 该账号独占的浏览器用户数据目录 | 只传给 `launch_persistent_context`，长期复用 |
|
||
| 登录状态 | 目标站 Cookie / Session 等实际会话 | 由业务技能打开同一 Profile 后检查；账号已登记不代表已登录 |
|
||
| `lease_token` | 当前任务对账号的临时独占权 | 打开浏览器前取得，所有退出路径释放 |
|
||
| `session_status` / error | 会话健康和最近故障线索 | 登录失效或账号异常时按约定回写 |
|
||
|
||
关系必须保持为：
|
||
|
||
```text
|
||
一个账号记录 ──绑定──► 一个稳定 profile_dir
|
||
│
|
||
└──任务运行前取得 lease_token ──► 同一时刻只允许一个任务使用
|
||
```
|
||
|
||
## 3. 强制规则
|
||
|
||
1. 所有浏览器 RPA，包括公开页和无需登录的页面，都必须先经 account-manager 取得 `profile_dir`。
|
||
2. 一个账号只能绑定一个稳定 Profile；不同账号禁止共用 Profile。
|
||
3. 禁止使用本机日常 Chrome / Edge 用户目录，禁止每次运行创建无归属的临时 Profile。
|
||
4. 获取账号时必须同时取得租约；仅 `account get <id>` 不能代替租约。
|
||
5. 业务代码只通过单一 `scripts/service/account_client.py` 集中调用 account-manager CLI。
|
||
6. 禁止 import account-manager 的 `service/`、`db/`、`util/`、`rpa_helpers` 等内部模块。
|
||
7. 未取得非空 `profile_dir` 和 `lease_token` 时禁止打开浏览器。
|
||
8. 账号均被占用时返回 `ERROR:LEASE_CONFLICT`，不得自动创建重复账号或换号绕过。
|
||
9. 所有成功、失败、取消和异常路径都必须在 `finally` 中释放租约。
|
||
10. 密码、Cookie、Token、短信验证码等敏感信息不得写入业务技能配置、数据库、日志或错误信息。
|
||
|
||
对应机器门禁：`POLICY-RPA-004`、`POLICY-RPA-006`。
|
||
|
||
## 4. 标准生命周期
|
||
|
||
```text
|
||
解析用户指定账号
|
||
→ ensure / pick 账号并取得租约
|
||
→ 校验账号平台、profile_dir、lease_token
|
||
→ 用 profile_dir 启动持久浏览器
|
||
→ 打开目标站并检查实际登录状态
|
||
→ 执行业务并记录结果
|
||
→ 回写会话状态 / 最近错误
|
||
→ 关闭浏览器
|
||
→ finally 释放租约
|
||
```
|
||
|
||
参考结构：
|
||
|
||
```python
|
||
account = pick_web_account(platform=TARGET_PLATFORM, account_id=account_id, login_id=login_id)
|
||
lease_token = account["lease_token"]
|
||
try:
|
||
profile_dir = account["profile_dir"]
|
||
# 只用 profile_dir 启动 persistent context，然后检查登录并执行任务
|
||
finally:
|
||
release_lease(lease_token)
|
||
```
|
||
|
||
浏览器启动、登录门禁、业务执行和关闭顺序见 [`RPA.md`](RPA.md) §0.2；CLI 封装边界见 [`ADAPTER.md`](ADAPTER.md)。
|
||
|
||
## 5. 账号选择与多账号
|
||
|
||
选择优先级：
|
||
|
||
1. 用户明确指定纯数字 `DEFAULT_ACCOUNT_ID`：先确认账号存在且平台一致，再通过可定位该账号的 pick 流程取得租约；不得只 `get` 后返回空租约。
|
||
2. 用户指定 `DEFAULT_LOGIN_ID`：使用 `ensure-web --login-id` 获取或登记，并取得租约。
|
||
3. 用户未指定账号：按平台 `ensure-web`，有则选择可用账号，无则登记一条。
|
||
4. 多条记录无法唯一确定：返回 `ERROR:AMBIGUOUS_ACCOUNT`，要求用户明确选择。
|
||
5. 匹配账号均被占用：返回 `ERROR:LEASE_CONFLICT`，等待或由运维确认租约状态。
|
||
|
||
批量和矩阵任务必须以账号为隔离单元：
|
||
|
||
- 每个账号独立 Profile、独立租约、独立任务结果和失败原因；
|
||
- 同一账号默认串行，不因追求吞吐提高同账号并发；
|
||
- 一个账号失败不得污染其他账号的 Profile 或结果；
|
||
- 设置单账号批量上限、单位时间操作上限和任务总时长；
|
||
- 风控、封禁或权限错误不得自动切换下一个账号继续试探。
|
||
|
||
## 6. 创建后去哪里查看
|
||
|
||
账号创建成功后必须可见、可查，不得只相信命令没有报错。
|
||
|
||
### 6.1 宿主数据管理
|
||
|
||
优先在匠厂宿主的**数据管理页面**查看 account-manager 数据：
|
||
|
||
- 账号记录：确认账号 ID、平台、账号名称 / 登录标识、状态、`profile_dir`、会话状态；
|
||
- 租约记录：确认当前持有者、用途、到期时间和是否已释放；
|
||
- 凭据记录：只能查看类型、引用和脱敏值，不应出现明文密码或 Token。
|
||
|
||
宿主版本若直接展示数据库表，对应核心表为 `accounts`、`account_leases`、`credentials`、`platforms`。不得在数据管理页面或 SQLite 工具中随意修改记录。
|
||
|
||
### 6.2 account-manager CLI
|
||
|
||
在 account-manager 仓库或宿主提供的入口中检查：
|
||
|
||
```powershell
|
||
python scripts/main.py account list --platform <platform_key> --limit 50
|
||
python scripts/main.py account get <account_id>
|
||
python scripts/main.py lease list --active
|
||
python scripts/main.py account open <account_id>
|
||
```
|
||
|
||
`account open` 仅用于查看指定 Profile。业务运行仍须走带租约的 pick / ensure 流程。
|
||
|
||
### 6.3 本地用户数据目录
|
||
|
||
实际数据按宿主注入的用户隔离：
|
||
|
||
```text
|
||
{JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/account-manager/
|
||
├── account-manager.db
|
||
└── profiles/
|
||
└── {domain}/
|
||
└── {platform_key}/
|
||
└── {safe_label}[_{login_id_suffix}]/
|
||
```
|
||
|
||
- `account-manager.db` 保存账号、平台、凭据元数据和租约。
|
||
- `profiles/...` 是真实浏览器用户数据目录，保存对应账号的 Cookie / Session 等浏览器状态。
|
||
- 实际路径以 `account get <id>` 返回的 `profile_dir` 为准，不得在代码里拼写固定盘符或用户 ID。
|
||
- Profile 正在使用时禁止复制、移动、删除或同时打开；需要迁移或清理时先停止任务并释放租约。
|
||
|
||
## 7. 登录状态与 Profile 验收
|
||
|
||
“账号已创建”只表示账号记录和 Profile 已准备，不代表目标站已经登录。
|
||
|
||
最小验收必须完成：
|
||
|
||
1. 数据管理页面或 `account list` 能看到账号记录。
|
||
2. `profile_dir` 非空、真实存在，并位于当前用户的 account-manager 数据目录。
|
||
3. 两个不同账号的 `profile_dir` 不相同。
|
||
4. 第一次用该 Profile 打开目标站，按平台要求人工登录或扫码。
|
||
5. 正常关闭浏览器并释放租约。
|
||
6. 再次取得同一账号租约，用同一 `profile_dir` 重开浏览器。
|
||
7. 验证登录状态仍有效；失效时返回 `ERROR:REQUIRE_LOGIN`，不得假成功。
|
||
|
||
## 8. 租约与异常退出
|
||
|
||
- 租约持有者应使用技能 slug 或可追踪任务标识，`purpose` 写明用途。
|
||
- 租约 TTL 应覆盖正常任务时长；长任务需要平台支持的续租策略，不能依赖永不过期。
|
||
- `finally release_lease(...)` 是最低要求，浏览器关闭失败也不能跳过释放尝试。
|
||
- 进程被强制结束后可能留下租约；先用 `lease list --active` 核对，确认没有真实任务仍在使用后再释放或清理。
|
||
- 禁止看到租约冲突就直接删数据库记录、删 Profile、换账号或新建重复账号。
|
||
|
||
## 9. 工业级测试
|
||
|
||
除单账号冒烟测试外，至少覆盖：
|
||
|
||
- 指定账号 ID、指定登录标识和自动选择三条路径；
|
||
- 账号不存在、平台不匹配、Profile 缺失、返回格式异常；
|
||
- 同一账号并发抢占和 `LEASE_CONFLICT`；
|
||
- 业务成功、业务失败、用户取消、浏览器崩溃后的租约释放；
|
||
- 登录过期、验证码 / 二次验证、账号风险和权限不足；
|
||
- 两个以上账号轮换且 Profile、登录态、结果互不污染；
|
||
- 关闭重开后登录保持；
|
||
- 批量长时间运行、限流、有限重试和断点续跑。
|
||
|
||
不得以“单账号成功操作一两次”作为多账号或矩阵能力已经交付的证明。
|
||
|
||
## 10. 排障顺序与提问证据
|
||
|
||
开发者和 AI 在群里提问前按顺序自查：
|
||
|
||
1. 阅读本文以及 [`RPA.md`](RPA.md)、[`ADAPTER.md`](ADAPTER.md)。
|
||
2. 在数据管理页面确认账号记录是否存在、平台和状态是否正确。
|
||
3. 执行 `account list/get`，核对账号 ID、`profile_dir`、`session_status`。
|
||
4. 在文件系统确认 `profile_dir` 是否存在、是否错用了其他用户目录。
|
||
5. 执行 `lease list --active`，确认是否被其他任务占用或残留。
|
||
6. 查看运行日志、任务中心终态、错误码、失败截图和浏览器当前页面。
|
||
7. 判断问题属于账号不存在、租约冲突、登录失效、Profile 损坏、页面变化还是业务失败。
|
||
|
||
仍需协助时必须提供：技能 slug、平台、脱敏账号标识 / 账号 ID、任务时间、错误码、账号与租约检查结果、`profile_dir` 是否存在、脱敏日志和截图。禁止发送密码、Cookie、Token 或验证码。
|
||
|
||
## 11. 安全边界
|
||
|
||
- 账号和 Profile 只能用于用户或企业明确授权的正常业务操作。
|
||
- 多账号管理用于账号隔离、矩阵业务和稳定调度，不得用于绕过频控、封禁或平台限制。
|
||
- 禁止破解协议、逆向客户端、伪造设备指纹、验证码破解、养号、撞库、代理池轮换或自动换号继续试探。
|
||
- 风控、封禁、安全警告和权限不足必须停止或转人工。
|
||
- 不手工编辑 `account-manager.db`，不在账号使用期间操作 Profile 文件。
|
||
|
||
完整合规与风控边界见 [`AI_RPA.md`](AI_RPA.md)。
|