Merge pull request #131 from pikasTech/fix/issue-127-playwright-tooling

fix: add commander Playwright wrapper

docs/reference/cli.md

@@ -65,6 +65,19 @@ CLI 可以从 `master` 快速演进，但必须兼容 `deploy.json` 固定的 CI
 - `debug health`、`debug dispatch` 与 `debug task` 走真实内部 core、WebSocket、数据库、provider、系统指标、Docker 状态和 Host SSH 维护桥流程，只用于开发调试，不写入 `TEST.md` 的正式验收步骤。
 - `e2e run [--only pattern[,pattern...]] [--skip pattern[,pattern...]]` 使用 publicHost 派生的公开 production frontend/dev frontend/provider ingress URL，并通过 Docker 内网验证 core API、PostgreSQL、provider self-connection、系统指标曲线、Docker 状态快照、provider.upgrade 预检和 Playwright 前端页面，是交付前的自动化 E2E 门禁；CLI 默认输出 check 状态摘要，完整诊断写入 `resultPath`，日常迭代应优先用 `--only` / `--skip` 跑最小必要集合。
 
+## Playwright Commander Wrapper
+
+UniDesk 仓库自带 `scripts/playwright-cli.ts` 作为 host commander 浏览器手测 wrapper。它是短生命周期、JSON 输出的命令，不是长驻浏览器 daemon。
+
+- `bun scripts/playwright-cli.ts screenshot <url> [path] [--session id] [--selector css] [--full-page]` 默认 headless 打开 URL、保存截图、把 storage state 写到 `.state/playwright-cli/sessions/`，并返回 `status`、`finalUrl`、`title`、`screenshotPath` 等紧凑 JSON。
+- `bun scripts/playwright-cli.ts open <url> [--session id] [--screenshot path]` 执行一次导航；需要证据时加 `--screenshot`。
+- `bun scripts/playwright-cli.ts eval <url> '<javascript-expression>' [--session id]` 在导航后执行单个表达式并返回结构化值。
+- `session-list` 和 `session-delete [sessionId]` 只管理 storage-state 文件。`--session` 不表示 live page，也不会保留 element refs。
+- `click`、`fill`、`snapshot`、`tab-list`、`close` 等交互式 daemon 命令会返回 `unsupported-command` 和下一步建议，不会透传给 `npx playwright`，因此 `--session=<id>` 不会再被上游 Playwright 当作未知参数。
+- 默认走 headless，适合无 XServer runner。确实需要 headed 时使用 `xvfb-run -a bun scripts/playwright-cli.ts open <url> --headed --screenshot /tmp/page.png`；Code Queue runner 镜像必须包含 `xvfb-run` 和 `xauth` 作为该兜底路径。
+
+外部 agent skill `~/.agents/skills/playwright` 是另一个 source of truth。当前宿主上它可能仍是 `npx playwright` passthrough，但 `SKILL.md` 里描述了更丰富的 `--session`、`snapshot` 和 element-ref 操作。外部 skill 分发更新前，UniDesk/HWLAB 指挥手测应使用本仓库 wrapper；不要把外部 skill 文档当成 daemon/session 能力已经可用的证据。
+
 ## Async Job State
 
 长时操作采用 Fire-and-Forget 模式：CLI 创建 `.state/jobs/{jobId}.json`，后台进程执行真实命令，并将 stdout、stderr 分别写入 `.state/jobs/{jobId}.stdout.log` 与 `.state/jobs/{jobId}.stderr.log`。调用者通过 `bun scripts/cli.ts job status <jobId>` 查询进度和尾部输出。