@tea-agent/loop-agent 0.27.1-beta.2 → 0.28.0

package/skills/playwright-cli/references/video-recording.md

@@ -1,143 +1,5 @@
-# Video Recording
+# Video 输出边界
 
-Capture browser automation sessions as video for debugging, documentation, or verification. Produces WebM (VP8/VP9 codec).
+受治理的 `frontend-test` DAG 不提供 video 输出能力。
 
-## Basic Recording
-
-```bash
-# Open browser first
-playwright-cli open
-
-# Start recording
-playwright-cli video-start demo.webm
-
-# Add a chapter marker for section transitions
-playwright-cli video-chapter "Getting Started" --description="Opening the homepage" --duration=2000
-
-# Navigate and perform actions
-playwright-cli goto https://example.com
-playwright-cli snapshot
-playwright-cli click e1
-
-# Add another chapter
-playwright-cli video-chapter "Filling Form" --description="Entering test data" --duration=2000
-playwright-cli fill e2 "test input"
-
-# Stop and save
-playwright-cli video-stop
-```
-
-## Best Practices
-
-### 1. Use Descriptive Filenames
-
-```bash
-# Include context in filename
-playwright-cli video-start recordings/login-flow-2024-01-15.webm
-playwright-cli video-start recordings/checkout-test-run-42.webm
-```
-
-### 2. Record entire hero scripts.
-
-When recording a video for the user or as a proof of work, it is best to create a code snippet and execute it with run-code.
-It allows inserting appropriate pauses between the actions and annotating the video. There are new Playwright APIs for that.
-
-1) Perform scenario using CLI and take note of all locators and actions. You'll need those locators to request their bounding boxes for highlight.
-2) Create a file with the intended script for video (below). Use pressSequentially w/ delay for nice typing, make reasonable pauses.
-3) Use playwright-cli run-code --filename your-script.js
-
-**Important**: Overlays are `pointer-events: none` — they do not interfere with page interactions. You can safely keep sticky overlays visible while clicking, filling, or performing any actions on the page.
-
-```js
-async page => {
-  await page.screencast.start({ path: 'video.webm', size: { width: 1280, height: 800 } });
-  await page.goto('https://demo.playwright.dev/todomvc');
-
-  // Show a chapter card — blurs the page and shows a dialog.
-  // Blocks until duration expires, then auto-removes.
-  // Use this for simple use cases, but always feel free to hand-craft your own beautiful
-  // overlay via await page.screencast.showOverlay().
-  await page.screencast.showChapter('Adding Todo Items', {
-    description: 'We will add several items to the todo list.',
-    duration: 2000,
-  });
-
-  // Perform action
-  await page.getByRole('textbox', { name: 'What needs to be done?' }).pressSequentially('Walk the dog', { delay: 60 });
-  await page.getByRole('textbox', { name: 'What needs to be done?' }).press('Enter');
-  await page.waitForTimeout(1000);
-
-  // Show next chapter
-  await page.screencast.showChapter('Verifying Results', {
-    description: 'Checking the item appeared in the list.',
-    duration: 2000,
-  });
-
-  // Add a sticky annotation that stays while you perform actions.
-  // Overlays are pointer-events: none, so they won't block clicks.
-  const annotation = await page.screencast.showOverlay(`
-    <div style="position: absolute; top: 8px; right: 8px;
-      padding: 6px 12px; background: rgba(0,0,0,0.7);
-      border-radius: 8px; font-size: 13px; color: white;">
-      ✓ Item added successfully
-    </div>
-  `);
-
-  // Perform more actions while the annotation is visible
-  await page.getByRole('textbox', { name: 'What needs to be done?' }).pressSequentially('Buy groceries', { delay: 60 });
-  await page.getByRole('textbox', { name: 'What needs to be done?' }).press('Enter');
-  await page.waitForTimeout(1500);
-
-  // Remove the annotation when done
-  await annotation.dispose();
-
-  // You can also highlight relevant locators and provide contextual annotations.
-  const bounds = await page.getByText('Walk the dog').boundingBox();
-  await page.screencast.showOverlay(`
-    <div style="position: absolute;
-      top: ${bounds.y}px;
-      left: ${bounds.x}px;
-      width: ${bounds.width}px;
-      height: ${bounds.height}px;
-      border: 1px solid red;">
-    </div>
-    <div style="position: absolute;
-      top: ${bounds.y + bounds.height + 5}px;
-      left: ${bounds.x + bounds.width / 2}px;
-      transform: translateX(-50%);
-      padding: 6px;
-      background: #808080;
-      border-radius: 10px;
-      font-size: 14px;
-      color: white;">Check it out, it is right above this text
-    </div>
-  `, { duration: 2000 });
-
-  await page.screencast.stop();
-}
-```
-
-Embrace creativity, overlays are powerful.
-
-### Overlay API Summary
-
-| Method | Use Case |
-|--------|----------|
-| `page.screencast.showChapter(title, { description?, duration?, styleSheet? })` | Full-screen chapter card with blurred backdrop — ideal for section transitions |
-| `page.screencast.showOverlay(html, { duration? })` | Custom HTML overlay — use for callouts, labels, highlights |
-| `disposable.dispose()` | Remove a sticky overlay added without duration |
-| `page.screencast.hideOverlays()` / `page.screencast.showOverlays()` | Temporarily hide/show all overlays |
-
-## Tracing vs Video
-
-| Feature | Video | Tracing |
-|---------|-------|---------|
-| Output | WebM file | Trace file (viewable in Trace Viewer) |
-| Shows | Visual recording | DOM snapshots, network, console, actions |
-| Use case | Demos, documentation | Debugging, analysis |
-| Size | Larger | Smaller |
-
-## Limitations
-
-- Recording adds slight overhead to automation
-- Large recordings can consume significant disk space
+该 DAG 的证据边界仅保留有界的 screenshot、pdf 和 snapshot evidence。需要记录的验证结论应以这些有界证据为准。

package/skills/playwright-cli-case-generator/SKILL.md

@@ -1,63 +1,72 @@
 ---
 name: playwright-cli-case-generator
-description: 根据 FE-test RAG 知识包生成可由 playwright-cli 串行执行的前端功能测试用例、索引和 case manifest。
+description: 根据 FE-test RAG 知识包生成可由受限 playwright_cli runtime 串行执行的前端功能测试用例、索引和 case manifest。
 ---
 
 # Playwright Test Generator
 
-仅用于 FE-test DAG 的 `generate-frontend-functional-cases-pi`。本 skill
-生成中文 Markdown 测试用例和 `manifest.json`，不执行浏览器、不生成
-Playwright/Pytest 源码，也不修改被测应用。
+仅用于 FE-test DAG 的 `generate-frontend-functional-cases-pi`。本 skill 生成中文 Markdown
+测试用例和 `manifest.json`，不执行浏览器、不生成测试源码，也不修改被测应用。
+
+生成的 case 步骤写成 `playwright-cli <command> ...` 行；执行阶段由 frontend-test browser child
+通过结构化 `playwright_cli` tool 消费。生成节点本身不获得 command capability。
 
 ## 输入与边界
 
-- 只读取 `testcase/frontend/rag/context.md`、`coverage-map.md` 与已有
-  `testcase/frontend/cases/`。
+- 只读取 `testcase/frontend/rag/context.md`、`coverage-map.md` 与已有 `testcase/frontend/cases/`。
 - 只写 `testcase/frontend/cases/**`；不得回读 PRD、读取 `.harness/`，或写
   `testcase/frontend/evidence/**`。
-- 所有 API、字段限制、状态流转、数据来源、SLA、URL 与账号要求必须能在
-  RAG 知识包中追溯。缺失信息标记 `blocked` 或“需人工确认”，不得猜测。
+- 所有 API、字段限制、状态流转、数据来源、SLA、URL 与账号要求必须能在 RAG 知识包中追溯。
+  缺失信息标记 `blocked` 或“需人工确认”，不得猜测。
 
 ## 输出
 
-- 写 `index.md`、`manifest.draft.json`（生成阶段；materialize 会写成
-  `manifest.json`）与独立 case 文件
-  `FE-<FEATURE>-<NNN>-<dimension>.md`；`dimension` 仅为 `core`、`boundary`、
-  `flow` 或 `backend`。
+- 写 `index.md`、`manifest.draft.json`（生成阶段；materialize 会写成 `manifest.json`）与独立 case 文件
+  `FE-<FEATURE>-<NNN>-<dimension>.md`；`dimension` 仅为 `core`、`boundary`、`flow` 或 `backend`。
 - **ID 契约（高频失败点，禁止混用）**：
   - `caseId` / 文件名 = **用例 ID**，形态 `FE-<FEATURE>-<NNN>-<dimension>`
-    （例：`FE-LOGIN-001-core`）。**禁止**把验收标准写成 caseId
-    （错误：`AC-FE-001.md` / `caseId: "AC-FE-001"`）。
+    （例：`FE-LOGIN-001-core`）。禁止把验收标准写成 caseId。
   - `acIds` = **验收标准 ID 列表**，形态 `AC-FE-*` / `AC-*`
-    （例：`["AC-FE-001"]`）。**禁止**把用例 ID 放进 acIds
-    （错误：`acIds: ["FE-LOGIN-001-core"]`）。
+    （例：`["AC-FE-001"]`）。禁止把用例 ID 放进 acIds。
   - `casePath` 必须等于 `testcase/frontend/cases/<caseId>.md`；
     `evidenceDir` 必须等于 `testcase/frontend/evidence/<caseId>/`。
-- `manifest` 使用 `schemaVersion: 1`，每项只含 `caseId`、`casePath`、
-  `dimension`、`acIds`、`evidenceDir`。所有 ID、路径和 evidenceDir 必须唯一，
-  并位于 `testcase/frontend/` 内。
+- `manifest` 使用 `schemaVersion: 1`，每项只含 `caseId`、`casePath`、`dimension`、`acIds`、
+  `evidenceDir`。所有 ID、路径和 evidenceDir 必须唯一，并位于 `testcase/frontend/` 内。
 - `index.md` 按功能点列出 case、维度、AC、数据依赖、API 映射和预期执行状态。
 
 每个 case 必须包含：
 
 1. 元信息：功能、CRUD 分类、维度、关联 AC、RAG 来源、API 映射状态与数据策略。
-2. 前置条件：默认浏览器 session 中的登录状态、fixture/存量数据、清理责任；不得用 `-s=<case-id>` 建立 named session。
-3. 可独立执行的命令序列：使用 RAG `context.md` 中已解析的绝对 `baseUrl`（优先来自任务源 `config.md`；缺失时默认 `http://localhost:5173`），必须以
-   `playwright-cli open --browser=chrome --headed <resolved-base-url>` 开始，禁止保留 `<base-url>` 占位符，也不得使用 `-s=<case-id>` 或其他 named session；再按需登录/数据准备、
-   `snapshot` 后优先使用元素引用、操作、UI 断言、可选 API 断言、cleanup、`close`。
-4. 明确的 UI/API 预期与数据清理结果；无法满足的环境或数据依赖必须写为 `blocked`。
-
-所有 snapshot、screenshot、trace 和 video 命令必须指向执行节点提供的
-`testcase/frontend/evidence/<case-id>/` 工作目录。命令必须使用现有
-`playwright-cli` skill 已声明的接口；不要生成 `requests --clear`、
-`request-body` 或 `response-body`。
+2. 前置条件：默认浏览器 session 中的登录状态、fixture/存量数据、清理责任；不得用
+   `-s=<case-id>` 建立 named session。
+3. 可独立执行的命令序列：使用 RAG `context.md` 中已解析的绝对 `baseUrl`（优先来自任务源
+   `config.md`；缺失时默认 `http://localhost:5173`），必须以
+   `playwright-cli open --browser=chrome --headed` 后接解析出的具体 base URL 开始；不得保留
+   base-url 占位符，也不得使用 `-s=<case-id>` 或其他 named session；再按需登录、数据准备、
+   `snapshot` 后优先使用元素引用和操作。每个拟通过场景必须在 `open` 后以成功的 `find` 作为
+   唯一结构化 UI 语义断言，再由 controller 执行 post-execution cleanup。`snapshot`、`goto`、
+   `screenshot`、`requests`、`request` 和普通交互不能单独取得 passed authority。
+4. **动态元素 ref（硬约束）**：可执行的 `playwright-cli` 行绝不得包含尖括号 token，例如
+   `<fresh-ref>` 或描述性的 `<...>` 占位符。只能使用 shell-safe 文档占位符 `eX`、`eY` 等；每个
+   占位符仅表示从紧邻其前、最新一次 `snapshot` 输出解析出的真实 `eNN` ref。生成的 case 必须在每次
+   引用元素前写明 fresh snapshot；`eX`/`eY` 不是可传给 structured tool 的 literal ref，新的 snapshot
+   会使旧 ref 失效，不得复用 stale ref。
+5. 明确的 UI/API 预期与数据清理结果；无法满足的环境或数据依赖必须写为 `blocked`。
+
+所有文件型输出均由 controller 绑定到执行节点提供的
+`testcase/frontend/evidence/<case-id>/` 工作目录。截图一律使用 canonical 语法
+`playwright-cli screenshot --filename final.png`；如确有从最新 snapshot 解析出的真实元素 ref，写为
+`playwright-cli screenshot e5 --filename final.png`。`pdf` 必须写为
+`playwright-cli pdf --filename final.pdf`。`snapshot` 无 filename 时仅返回响应；需要文件时使用
+`playwright-cli snapshot --filename snapshot.txt`。不得生成 `playwright-cli screenshot <path>`，不得使用
+`--path`、`--output` 或 `--file`，文件路径绝不能作为 screenshot 位置参数。命令只能使用
+`playwright-cli` skill 已声明的 runtime allowlist；不要生成未声明的命令变体。
 
 ### playwright-cli-only（硬约束）
 
 - 用例步骤只能使用 `playwright-cli` skill 已声明的命令语法。
-- **禁止**裸 `playwright`、`npx playwright`、`playwright test`、`@playwright/test`、
-  Node Playwright API 或生成 Playwright/Pytest 源码。
-- `playwright-cli` 不可用时不得降级到原生 Playwright；应写 blocked evidence，
+- 不生成其他浏览器自动化调用、测试运行器调用或测试源码。
+- `playwright-cli` 不可用时不得降级；应写 blocked evidence，
   `blockedReason: playwright-cli-unavailable`。
 
 ## 覆盖矩阵
@@ -69,35 +78,33 @@ Playwright/Pytest 源码，也不修改被测应用。
 | U-修改 | `core`、`boundary` | 有状态流转时 `flow`；有 API 映射时 `backend` |
 | D-删除 | `core` | 有 API 映射时 `backend` |
 
-- `boundary` 只从已知必填、长度、范围、精度、枚举或字符规则推导；无约束时
-  不伪造边界值。
+- `boundary` 只从已知必填、长度、范围、精度、枚举或字符规则推导；无约束时不伪造边界值。
 - `flow` 是自包含的多步状态旅程；每个关键步骤都有 UI 与已知数据一致性断言，
   不依赖其他 case 创建的数据。
-- `backend` 只在 API 映射存在时使用 `requests` / `request <id>`，或在精确时序
-  下使用 `run-code`。错误、空态或超时使用 `route`，并在 cleanup 中 `unroute`。
-  响应字段和性能阈值必须来自 RAG。
+- `backend` 只在 API 映射存在时使用 `requests` / `request <id>` 记录已观察到的后端证据；
+  响应字段和性能阈值必须来自 RAG。时序、异常、响应内容、数据准备或环境条件无法由 runtime
+  allowlist 与 RAG 证明时，必须生成 `blocked` case/evidence，并说明原因。
 
 ## 数据策略
 
-- C-新增优先使用需求中给出的测试数据；仅在已授权 API 映射存在时才描述临时构造
-  与清理。
+- C-新增优先使用需求中给出的测试数据；仅在已授权 API 映射存在时才描述临时构造与清理。
 - R 查询优先使用知识包登记的 fixture 或当前用户可见数据。
 - **U/D 修改删除归属顺序（硬约束）**：
   1. 仅操作可由**当前登录用户身份**与 UI/API 可观测归属字段共同证明的数据；
      禁止只凭名称、猜测 ID 或列表顺序认定归属。
-  2. 当前用户无可用数据时，优先在当前用户上下文创建带 run/case 可追踪标记、
-     可清理的数据，再执行 U/D，并在 cleanup 中验证清理。
+  2. 当前用户无可用数据时，优先在当前用户上下文创建带 run/case 可追踪标记、可清理的数据，
+     再执行 U/D，并在 cleanup 中验证清理。
   3. 无法安全创建时，仅可使用任务源/RAG 已确认且受路径/环境约束的 Mock，
      并明确标注为 Mock（不得声称真实后端验证）。
   4. 既无法证明归属、也无法安全创建或 Mock 时，写 `blocked` evidence，
      `blockedReason` 使用：`current-user-data-unavailable` |
      `data-ownership-unverifiable` | `safe-test-data-setup-unavailable`，不执行 U/D。
   5. 禁止修改/删除其他用户数据、共享 fixture、生产数据或无法确认可清理的数据。
-- 禁止使用生产 URL、真实用户凭据或不可清理的数据写入。无法证明隔离与清理时，
-  case 必须为 `blocked`。
+- 禁止使用生产 URL、真实用户凭据或不可清理的数据写入。无法证明隔离与清理时，case 必须为
+  `blocked`。
 
 ## 交接
 
-生成结束时仅返回紧凑 JSON 摘要：case 总数、各维度数量、manifest 相对路径、
-blocked case ID 与原因。详细内容保留在 case 文件，供后续 manifest/map 子节点
-逐 case 读取，避免把完整用例塞进上游上下文。
+生成结束时仅返回紧凑 JSON 摘要：case 总数、各维度数量、manifest 相对路径、blocked case ID
+与原因。详细内容保留在 case 文件，供后续 manifest/map 子节点逐 case 读取，避免把完整用例塞进
+上游上下文。