Web Login & Ops
用 scripts/wlo.py 一个入口完成四件事：登录网站、保持会话、操作页面、导入导出数据。
底层驱动 agent-browser（真实 Chromium），因此能处理 JS 渲染、动态分页、iframe、需要登录才能看的页面。
先决条件
先跑环境自检，它会告诉你 agent-browser 是否可用：
python scripts/wlo.py doctor
- 若提示找不到 agent-browser：
npm install -g agent-browser && agent-browser install - 若命令超时无输出、浏览器起不来：
agent-browser close --all清掉僵尸 daemon 后重试；必要时重跑agent-browser install - 环境变量
WLO_AB_CMD可直接指定完整启动命令，WLO_AB_PACKAGE指定安装目录。
文件与目录约定
所有状态存在 $WLO_HOME（默认 ~/.web-login-ops）：
| 路径 | 内容 |
|---|---|
sites/<站点名>.json |
站点配置：网址、登录步骤、选择器 |
sessions/<站点名>.json |
会话状态（含登录 token，勿提交、勿外发） |
reports/ |
导入结果报告 |
screenshots/ |
失败时的自动截图 |
logs/ |
执行日志（密码已脱敏） |
五步主流程
1. 生成站点配置
python scripts/wlo.py site init <站点名> # 生成模板
python scripts/wlo.py site list # 看已有哪些站点
python scripts/wlo.py site show <站点名> # 看某个站点的配置
生成后必须编辑 ~/.web-login-ops/sites/<站点名>.json，把 base_url、login.url、login.steps 改成真实值。字段详解与各类登录形态见 references/site-profile.md。
2. 存凭据（推荐，密码不进对话上下文）
凭据只从环境变量读取，绝不写进配置文件。
# 方式 A：环境变量（临场可用）
export WLO_<站点名大写>_USER='账号'
export WLO_<站点名大写>_PASS='密码'
# 方式 B：存入 agent-browser 凭据库（长期复用，登录时密码不经过模型）
python scripts/wlo.py auth save <站点名>
python scripts/wlo.py auth list
站点配置里 credentials.vault 有值时，login 优先走凭据库；置空则走 login.steps + 环境变量。
3. 登录并保存会话
python scripts/wlo.py login <站点名>
python scripts/wlo.py login <站点名> --force # 忽略旧会话，强制重登
python scripts/wlo.py login <站点名> --headed # 弹出可见浏览器，手动过一次验证码/短信
登录成功后会话写入 sessions/<站点名>.json，后续 export / import / run 自动复用它，不需要重复登录。
会话失效时会自动重新登录（login 先探测再决定是否复用）。
4. 导出数据（抓取登录后的页面 → 文件）
python scripts/wlo.py export <站点名> --extract extract.json --out data.csv
python scripts/wlo.py export <站点名> --extract extract.json --out data.csv --headed # 排错时看页面
extract.json 定义「在哪一页、按哪个选择器切行、每列取什么」，支持自动翻页。
格式与写法见 references/data-io.md。先 --dry-run 确认选择器编译结果。
5. 导入数据（文件 → 批量填表提交）
python scripts/wlo.py import <站点名> --form form.json --in data.csv --dry-run # 先空跑
python scripts/wlo.py import <站点名> --form form.json --in data.csv
python scripts/wlo.py import <站点名> --form form.json --in data.csv --continue-on-error
逐行填表、提交、校验结果，最后输出成功/失败统计与逐行报告。--dry-run 只打印将要执行的动作，不碰页面。
命令速查
| 目的 | 命令 |
|---|---|
| 环境自检 | wlo.py doctor |
| 站点配置 | wlo.py site init\|list\|show <名字> |
| 凭据库 | wlo.py auth save\|list\|show\|delete <名字> |
| 登录 | wlo.py login <站点名> [--headed] [--force] [--no-vault] |
| 查会话是否还有效 | wlo.py check <站点名> |
| 自定义操作序列 | wlo.py run <站点名> --steps steps.json [--keep-open] [--dry-run] |
| 导出数据 | wlo.py export <站点名> --extract e.json --out data.csv [--format csv\|json\|ndjson] |
| 导入数据 | wlo.py import <站点名> --form f.json --in data.csv [--dry-run] [--limit N] |
| 会话文件管理 | wlo.py session list\|clear\|export\|import |
| 关浏览器 | wlo.py close <站点名> [--all] |
所有命令输出 JSON；失败时退出码为 1，并在 error 字段说明原因。
选择器语法
target 字段统一支持语义定位（比纯 CSS 更抗改版）：
| 写法 | 含义 | 例 |
|---|---|---|
label=用户名 |
按关联标签定位输入框 | {"target": "label=用户名", "action": "fill"} |
placeholder=请输入 |
按占位文本 | placeholder=请输入手机号 |
role=button[name=登录] |
按可访问角色 + 名称 | role=button[name=登录] |
text=提交 |
按可见文本 | text=提交 |
testid=submit-btn |
按 data-testid | testid=submit-btn |
#id / .class / table tbody tr |
原生 CSS | #f-kind |
@e3 |
快照引用 | 先 snapshot 拿到再点 |
语义定位支持 click / fill / type / hover / focus / check / uncheck；下拉框 select、等待与断言用 CSS 更稳。
安全红线
- 密码不落盘：只从环境变量或凭据库读取，不要写进
sites/*.json，不要贴在命令行参数里。 - 会话文件等同密码：
sessions/*.json含 token，别提交到仓库、别发给别人。可设AGENT_BROWSER_ENCRYPTION_KEY加密。 - 导入先空跑：批量写数据前先
--dry-run，再用--limit 1试一行，确认无误再全量。 - 不代购物、不代下单、不代付款：涉及资金、支付、下单的动作一律停下来交给人。
- 只操作被授权的账号与数据。
排错
登录卡住、选择器失效、翻页抓不全、导入失败等问题，见 references/troubleshooting.md。
排查顺序固定为：doctor → --headed 看真实页面 → snapshot -i 拿准确选择器 → --dry-run 验证配置。
