@tea-agent/loop-agent 0.27.1 → 0.28.0

package/skills/playwright-cli/SKILL.md

@@ -1,420 +1,87 @@
 ---
 name: playwright-cli
-description: Automate browser interactions, test web pages and work with Playwright tests.
-allowed-tools: Bash(playwright-cli:*) Bash(npx:*) Bash(npm:*)
+description: 在 frontend-test DAG 中通过受限的结构化 playwright_cli 工具执行浏览器交互与证据采集。
 ---
 
 # Browser Automation with playwright-cli
 
-## Quick start
-
-```bash
-# open new browser
-playwright-cli open
-# navigate to a page
-playwright-cli goto https://playwright.dev
-# interact with the page using refs from the snapshot
-playwright-cli click e15
-playwright-cli type "page.click"
-playwright-cli press Enter
-# take a screenshot (rarely used, as snapshot is more common)
-playwright-cli screenshot
-# close the browser
-playwright-cli close
-```
-
-## Commands
-
-### Core
-
-```bash
-playwright-cli open
-# open and navigate right away
-playwright-cli open https://example.com/
-playwright-cli goto https://playwright.dev
-playwright-cli type "search query"
-playwright-cli click e3
-playwright-cli dblclick e7
-# --submit presses Enter after filling the element
-playwright-cli fill e5 "user@example.com"  --submit
-playwright-cli drag e2 e8
-# drop files or data onto an element (from outside the page)
-playwright-cli drop e4 --path=./image.png
-playwright-cli drop e4 --data="text/plain=hello world"
-playwright-cli hover e4
-playwright-cli select e9 "option-value"
-playwright-cli upload ./document.pdf
-playwright-cli check e12
-playwright-cli uncheck e12
+## frontend-test DAG 契约
+
+本 skill 面向 frontend-test DAG browser child。每个浏览器操作都必须转换为一次结构化
+`playwright_cli` tool call：`{ command, args?, timeoutSeconds? }`。
+
+- 当前运行时不提供任意命令执行入口；不得尝试其他浏览器自动化工具或测试运行器。
+- 缺少普通终端能力不表示浏览器工具不可用；仅当 preflight 或 `playwright_cli` 明确失败时，记录
+  `playwright-cli-unavailable` 或相应 contract error。
+- 不可由受限命令和已记录证据证明的场景必须标记为 `blocked`，不得臆测通过。
+- browser case 只能使用下列 runtime allowlist 中的命令。每个命令行由 controller 转为结构化调用，
+  不直接执行文本命令。
+
+## Runtime allowlist
+
+```text
+open
+close
+goto
+snapshot
+find
+click
+dblclick
+fill
+type
+press
+keydown
+keyup
+hover
+select
+check
+uncheck
+drag
+drop
+upload
+go-back
+go-forward
+reload
+dialog-accept
+dialog-dismiss
+resize
+screenshot
+pdf
+console
+requests
+request
+```
+
+## 推荐执行流程
+
+使用 controller 冻结的非生产 `baseUrl` 和默认浏览器 session；不得创建 named session。交互前先
+获取 snapshot，并只使用 snapshot 中可见的 ref 或已知安全 locator。
+
+```text
+playwright-cli open --browser=chrome --headed http://localhost:5173
 playwright-cli snapshot
-# search the snapshot for text or a regexp, returns matching nodes with surrounding context
 playwright-cli find "Sign in"
-playwright-cli find --regex "Sign (in|up)"
-# wrap the regexp in slashes to add flags, e.g. /i for case-insensitive
-playwright-cli find --regex "/sign (in|up)/i"
-playwright-cli eval "document.title"
-playwright-cli eval "el => el.textContent" e5
-# get element id, class, or any attribute not visible in the snapshot
-playwright-cli eval "el => el.id" e5
-playwright-cli eval "el => el.getAttribute('data-testid')" e5
-playwright-cli dialog-accept
-playwright-cli dialog-accept "confirmation text"
-playwright-cli dialog-dismiss
-playwright-cli resize 1920 1080
-playwright-cli close
-```
-
-### Navigation
-
-```bash
-playwright-cli go-back
-playwright-cli go-forward
-playwright-cli reload
-```
-
-### Keyboard
-
-```bash
-playwright-cli press Enter
-playwright-cli press ArrowDown
-playwright-cli keydown Shift
-playwright-cli keyup Shift
-```
-
-### Mouse
-
-```bash
-playwright-cli mousemove 150 300
-playwright-cli mousedown
-playwright-cli mousedown right
-playwright-cli mouseup
-playwright-cli mouseup right
-playwright-cli mousewheel 0 100
-```
-
-### Save as
-
-```bash
-playwright-cli screenshot
-playwright-cli screenshot e5
-playwright-cli screenshot --filename=page.png
-playwright-cli screenshot --hires
-playwright-cli pdf --filename=page.pdf
-```
-
-### Tabs
-
-```bash
-playwright-cli tab-list
-playwright-cli tab-new
-playwright-cli tab-new https://example.com/page
-playwright-cli tab-close
-playwright-cli tab-close 2
-playwright-cli tab-select 0
-```
-
-### Storage
-
-```bash
-playwright-cli state-save
-playwright-cli state-save auth.json
-playwright-cli state-load auth.json
-
-# Cookies
-playwright-cli cookie-list
-playwright-cli cookie-list --domain=example.com
-playwright-cli cookie-get session_id
-playwright-cli cookie-set session_id abc123
-playwright-cli cookie-set session_id abc123 --domain=example.com --httpOnly --secure
-playwright-cli cookie-delete session_id
-playwright-cli cookie-clear
-
-# LocalStorage
-playwright-cli localstorage-list
-playwright-cli localstorage-get theme
-playwright-cli localstorage-set theme dark
-playwright-cli localstorage-delete theme
-playwright-cli localstorage-clear
-
-# SessionStorage
-playwright-cli sessionstorage-list
-playwright-cli sessionstorage-get step
-playwright-cli sessionstorage-set step 3
-playwright-cli sessionstorage-delete step
-playwright-cli sessionstorage-clear
-```
-
-### Network
-
-```bash
-playwright-cli route "**/*.jpg" --status=404
-playwright-cli route "https://api.example.com/**" --body='{"mock": true}'
-playwright-cli route-list
-playwright-cli unroute "**/*.jpg"
-playwright-cli unroute
-```
-
-### DevTools
-
-```bash
-playwright-cli console
-playwright-cli console warning
-playwright-cli requests
-playwright-cli request 5
-playwright-cli run-code "async page => await page.context().grantPermissions(['geolocation'])"
-playwright-cli run-code --filename=script.js
-playwright-cli tracing-start
-playwright-cli tracing-stop
-playwright-cli video-start video.webm
-playwright-cli video-chapter "Chapter Title" --description="Details" --duration=2000
-playwright-cli video-stop
-
-# annotate each subsequent action (click, type, ...) with a callout naming the action and highlighting the target
-playwright-cli video-show-actions --duration=600 --position=top-right
-playwright-cli video-hide-actions
-
-# launch the dashboard for UI review / design feedback — user annotates the page, you receive the annotated screenshot, snapshot, and notes
-playwright-cli show --annotate
-
-# generate a Playwright locator for an element from its ref or selector
-playwright-cli generate-locator e5 --raw
-
-# show a persistent highlight overlay for an element, optionally with a custom style
-playwright-cli highlight e5
-playwright-cli highlight e5 --style="outline: 3px dashed red"
-# hide a single element highlight, or all page highlights when no target is given
-playwright-cli highlight e5 --hide
-playwright-cli highlight --hide
-```
-
-## Raw output
-
-The global `--raw` option strips page status, generated code, and snapshot sections from the output, returning only the result value. Use it to pipe command output into other tools. Commands that don't produce output return nothing.
-
-```bash
-playwright-cli --raw eval "JSON.stringify(performance.timing)" | jq '.loadEventEnd - .navigationStart'
-playwright-cli --raw eval "JSON.stringify([...document.querySelectorAll('a')].map(a => a.href))" > links.json
-playwright-cli --raw snapshot > before.yml
-playwright-cli click e5
-playwright-cli --raw snapshot > after.yml
-diff before.yml after.yml
-TOKEN=$(playwright-cli --raw cookie-get session_id)
-playwright-cli --raw localstorage-get theme
-```
-
-For structured output wrapping every reply as JSON, pass --json
-```bash
-playwright-cli list --json
-```
-
-## Open parameters
-```bash
-# Use specific browser when creating session
-playwright-cli open --browser=chrome
-playwright-cli open --browser=firefox
-playwright-cli open --browser=webkit
-playwright-cli open --browser=msedge
-
-# Emulate a generic mobile device (Pixel 10 for Chromium, iPhone 17 for WebKit).
-# Prefer this when a mobile layout is acceptable: mobile pages are usually
-# lighter, so snapshots are smaller and cheaper.
-playwright-cli open --mobile
-playwright-cli open --device="iPhone 15"
-
-# Use persistent profile (by default profile is in-memory)
-playwright-cli open --persistent
-# Use persistent profile with custom directory
-playwright-cli open --profile=/path/to/profile
-
-# Connect to browser via Playwright Extension
-playwright-cli attach --extension=chrome
-
-# Connect to a running Chrome or Edge by channel name
-playwright-cli attach --cdp=chrome
-playwright-cli attach --cdp=msedge
-
-# Connect to a running browser via CDP endpoint
-playwright-cli attach --cdp=http://localhost:9222
-
-# Start with config file
-playwright-cli open --config=my-config.json
-
-# Close the browser
-playwright-cli close
-# Detach from an attached browser (leaves the external browser running)
-playwright-cli -s=msedge detach
-# Delete user data for the default session
-playwright-cli delete-data
-```
-
-## URLs with `&` on Windows
-
-On Windows, `cmd.exe` and PowerShell treat `&` as a command separator, so URLs with multiple query parameters get truncated before `playwright-cli` runs. Escape `&` with `^&` in `cmd.exe`, or use `--%` in PowerShell:
-
-```batch
-playwright-cli goto "https://example.com/?a=1^&b=2"
-```
-
-```powershell
-playwright-cli --% goto "https://example.com/?a=1&b=2"
-```
-
-## Snapshots
-
-After each command, playwright-cli provides a snapshot of the current browser state.
-
-```bash
-> playwright-cli goto https://example.com
-### Page
-- Page URL: https://example.com/
-- Page Title: Example Domain
-### Snapshot
-[Snapshot](.playwright-cli/page-2026-02-14T19-22-42-679Z.yml)
-```
-
-You can also take a snapshot on demand using `playwright-cli snapshot` command. All the options below can be combined as needed.
-
-```bash
-# default - save to a file with timestamp-based name
-playwright-cli snapshot
-
-# save to file, use when snapshot is a part of the workflow result
-playwright-cli snapshot --filename=after-click.yaml
-
-# snapshot an element instead of the whole page
-playwright-cli snapshot "#main"
-
-# limit snapshot depth for efficiency, take a partial snapshot afterwards
-playwright-cli snapshot --depth=4
-playwright-cli snapshot e34
-
-# include each element's bounding box as [box=x,y,width,height]
-playwright-cli snapshot --boxes
-
-# search a large snapshot instead of capturing it all — returns matching nodes
-# with 3 lines of context around each match (like grep -C)
-playwright-cli find "Add to cart"
-playwright-cli find --regex "\\$[0-9]+\\.[0-9]{2}"
-```
-
-## Targeting elements
-
-By default, use refs from the snapshot to interact with page elements.
-
-```bash
-# get snapshot with refs
-playwright-cli snapshot
-
-# interact using a ref
-playwright-cli click e15
-```
-
-You can also use css selectors or Playwright locators.
-
-```bash
-# css selector
-playwright-cli click "#main > button.submit"
-
-# role locator
-playwright-cli click "getByRole('button', { name: 'Submit' })"
-
-# test id
-playwright-cli click "getByTestId('submit-button')"
-```
-
-## Browser Sessions
-
-```bash
-# create new browser session named "mysession" with persistent profile
-playwright-cli -s=mysession open example.com --persistent
-# same with manually specified profile directory (use when requested explicitly)
-playwright-cli -s=mysession open example.com --profile=/path/to/profile
-playwright-cli -s=mysession click e6
-playwright-cli -s=mysession close  # stop a named browser
-playwright-cli -s=mysession delete-data  # delete user data for persistent session
-
-playwright-cli list
-# Close all browsers
-playwright-cli close-all
-# Forcefully kill all browser processes
-playwright-cli kill-all
-```
-
-## Installation
-
-If global `playwright-cli` command is not available, try a local version via `npx playwright cli`:
-
-```bash
-npx --no-install playwright --version
-```
-
-When local version is available, use `npx playwright cli` in all commands. Otherwise, install `playwright-cli` as a global command:
-
-```bash
-npm install -g @playwright/cli@latest
-```
-
-## Example: Form submission
-
-```bash
-playwright-cli open https://example.com/form
-playwright-cli snapshot
-
 playwright-cli fill e1 "user@example.com"
 playwright-cli fill e2 "password123"
 playwright-cli click e3
-playwright-cli snapshot
-playwright-cli close
-```
-
-## Example: Multi-tab workflow
-
-```bash
-playwright-cli open https://example.com
-playwright-cli tab-new https://example.com/other
-playwright-cli tab-list
-playwright-cli tab-select 0
-playwright-cli snapshot
-playwright-cli close
-```
-
-## Example: Debugging with DevTools
-
-```bash
-playwright-cli open https://example.com
-playwright-cli click e4
-playwright-cli fill e7 "test"
-playwright-cli console
-playwright-cli requests
+playwright-cli find "Welcome"
 playwright-cli close
 ```
 
-```bash
-playwright-cli open https://example.com
-playwright-cli tracing-start
-playwright-cli click e4
-playwright-cli fill e7 "test"
-playwright-cli tracing-stop
-playwright-cli close
-```
-
-## Example: Interactive session
+成功的 `find` 是唯一可用于 UI 语义断言的浏览器证据。`snapshot`、导航、截图、网络观察、
+普通交互和控制台输出均不能单独取得 passed authority。通过的 case 还需要同一 child 的有序
+controller receipts：successful `open` → successful `find` → successful post-execution cleanup。
 
-Ask the user for UI review or design feedback. The user draws boxes on the live page and types comments; you receive the annotated screenshot, the snapshot of the marked region, and the user's notes. Use this whenever the user asks for "UI review", "design feedback", or to "ask the user what they think / want / mean":
+## 受限证据采集
 
-```bash
-playwright-cli open https://example.com
-playwright-cli show --annotate
-```
+- UI 状态：先 `snapshot`，完成交互后以成功 `find` 证明用户可见结果。
+- 后端观察：可使用 `requests` 列出已观察到的请求，再以 `request <id>` 查看单个已观察请求。
+  这类观察不能替代成功 `find` 的 UI 语义证据。
+- 文件型证据：`screenshot` 与 `pdf` 必须使用 `--filename <file>`，且文件名由 controller 规范化到当前 case evidence 目录。截图一律写为 `playwright-cli screenshot --filename final.png`；有真实元素 ref 时写为 `playwright-cli screenshot e5 --filename final.png`。`pdf` 写为 `playwright-cli pdf --filename final.pdf`。`snapshot` 不带 filename 时只返回响应；需要文件时写为 `playwright-cli snapshot --filename snapshot.txt`。不得使用 `--path`、`--output`、`--file`，也不得把文件路径作为位置参数。
+- 对话框、上传、拖放和视口变化仅在 case 已给出所需前置条件时使用对应 allowlist 命令。
 
-## Specific tasks
+## 阻塞处理
 
-* **Running and Debugging Playwright tests** [references/playwright-tests.md](references/playwright-tests.md)
-* **Request mocking** [references/request-mocking.md](references/request-mocking.md)
-* **Running Playwright code** [references/running-code.md](references/running-code.md)
-* **Browser session management** [references/session-management.md](references/session-management.md)
-* **Storage state (cookies, localStorage)** [references/storage-state.md](references/storage-state.md)
-* **Test generation (plan / generate / heal)** [references/test-generation.md](references/test-generation.md)
-* **Tracing** [references/tracing.md](references/tracing.md)
-* **Video recording** [references/video-recording.md](references/video-recording.md)
-* **Inspecting element attributes** [references/element-attributes.md](references/element-attributes.md)
+当环境、数据、权限、时序、异常路径或响应内容无法用 RAG、冻结配置和 runtime allowlist 证明时，
+写入 `blocked` evidence，并提供具体 `blockedReason`。不要引入替代执行路径，也不要把隐藏状态或
+未观察到的网络结果当作通过证据。

package/skills/playwright-cli/references/tracing.md

@@ -1,139 +1,5 @@
-# Tracing
+# Tracing 输出边界
 
-Capture detailed execution traces for debugging and analysis. Traces include DOM snapshots, screenshots, network activity, and console logs.
+受治理的 `frontend-test` DAG 不提供 tracing 输出能力。
 
-## Basic Usage
-
-```bash
-# Start trace recording
-playwright-cli tracing-start
-
-# Perform actions
-playwright-cli open https://example.com
-playwright-cli click e1
-playwright-cli fill e2 "test"
-
-# Stop trace recording
-playwright-cli tracing-stop
-```
-
-## Trace Output Files
-
-When you start tracing, Playwright creates a `traces/` directory with several files:
-
-### `trace-{timestamp}.trace`
-
-**Action log** - The main trace file containing:
-- Every action performed (clicks, fills, navigations)
-- DOM snapshots before and after each action
-- Screenshots at each step
-- Timing information
-- Console messages
-- Source locations
-
-### `trace-{timestamp}.network`
-
-**Network log** - Complete network activity:
-- All HTTP requests and responses
-- Request headers and bodies
-- Response headers and bodies
-- Timing (DNS, connect, TLS, TTFB, download)
-- Resource sizes
-- Failed requests and errors
-
-### `resources/`
-
-**Resources directory** - Cached resources:
-- Images, fonts, stylesheets, scripts
-- Response bodies for replay
-- Assets needed to reconstruct page state
-
-## What Traces Capture
-
-| Category | Details |
-|----------|---------|
-| **Actions** | Clicks, fills, hovers, keyboard input, navigations |
-| **DOM** | Full DOM snapshot before/after each action |
-| **Screenshots** | Visual state at each step |
-| **Network** | All requests, responses, headers, bodies, timing |
-| **Console** | All console.log, warn, error messages |
-| **Timing** | Precise timing for each operation |
-
-## Use Cases
-
-### Debugging Failed Actions
-
-```bash
-playwright-cli tracing-start
-playwright-cli open https://app.example.com
-
-# This click fails - why?
-playwright-cli click e5
-
-playwright-cli tracing-stop
-# Open trace to see DOM state when click was attempted
-```
-
-### Analyzing Performance
-
-```bash
-playwright-cli tracing-start
-playwright-cli open https://slow-site.com
-playwright-cli tracing-stop
-
-# View network waterfall to identify slow resources
-```
-
-### Capturing Evidence
-
-```bash
-# Record a complete user flow for documentation
-playwright-cli tracing-start
-
-playwright-cli open https://app.example.com/checkout
-playwright-cli fill e1 "4111111111111111"
-playwright-cli fill e2 "12/25"
-playwright-cli fill e3 "123"
-playwright-cli click e4
-
-playwright-cli tracing-stop
-# Trace shows exact sequence of events
-```
-
-## Trace vs Video vs Screenshot
-
-| Feature | Trace | Video | Screenshot |
-|---------|-------|-------|------------|
-| **Format** | .trace file | .webm video | .png/.jpeg image |
-| **DOM inspection** | Yes | No | No |
-| **Network details** | Yes | No | No |
-| **Step-by-step replay** | Yes | Continuous | Single frame |
-| **File size** | Medium | Large | Small |
-| **Best for** | Debugging | Demos | Quick capture |
-
-## Best Practices
-
-### 1. Start Tracing Before the Problem
-
-```bash
-# Trace the entire flow, not just the failing step
-playwright-cli tracing-start
-playwright-cli open https://example.com
-# ... all steps leading to the issue ...
-playwright-cli tracing-stop
-```
-
-### 2. Clean Up Old Traces
-
-Traces can consume significant disk space:
-
-```bash
-# Remove traces older than 7 days
-find .playwright-cli/traces -mtime +7 -delete
-```
-
-## Limitations
-
-- Traces add overhead to automation
-- Large traces can consume significant disk space
-- Some dynamic content may not replay perfectly
+该 DAG 的证据边界仅保留有界的 screenshot、pdf 和 snapshot evidence。需要记录的验证结论应以这些有界证据为准。