@tea-agent/loop-agent 0.13.0-alpha.0 → 0.13.0-beta.0

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

@@ -0,0 +1,139 @@
+# Tracing
+
+Capture detailed execution traces for debugging and analysis. Traces include DOM snapshots, screenshots, network activity, and console logs.
+
+## 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

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

@@ -0,0 +1,143 @@
+# Video Recording
+
+Capture browser automation sessions as video for debugging, documentation, or verification. Produces WebM (VP8/VP9 codec).
+
+## 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

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

@@ -0,0 +1,74 @@
+---
+name: playwright-cli-case-generator
+description: 根据 FE-test RAG 知识包生成可由 playwright-cli 串行执行的前端功能测试用例、索引和 case manifest。
+---
+
+# Playwright Test Generator
+
+仅用于 FE-test DAG 的 `generate-frontend-functional-cases-pi`。本 skill
+生成中文 Markdown 测试用例和 `manifest.json`，不执行浏览器、不生成
+Playwright/Pytest 源码，也不修改被测应用。
+
+## 输入与边界
+
+- 只读取 `testcase/frontend/rag/context.md`、`coverage-map.md` 与已有
+  `testcase/frontend/cases/`。
+- 只写 `testcase/frontend/cases/**`；不得回读 PRD、读取 `.harness/`，或写
+  `testcase/frontend/evidence/**`。
+- 所有 API、字段限制、状态流转、数据来源、SLA、URL 与账号要求必须能在
+  RAG 知识包中追溯。缺失信息标记 `blocked` 或“需人工确认”，不得猜测。
+
+## 输出
+
+- 写 `index.md`、`manifest.json` 与独立 case 文件
+  `FE-<FEATURE>-<NNN>-<dimension>.md`；`dimension` 仅为 `core`、`boundary`、
+  `flow` 或 `backend`。
+- `manifest.json` 使用 `schemaVersion: 1`，每项只含 `caseId`、`casePath`、
+  `dimension`、`acIds`、`evidenceDir`。所有 ID、路径和 evidenceDir 必须唯一，
+  并位于 `testcase/frontend/` 内。
+- `index.md` 按功能点列出 case、维度、AC、数据依赖、API 映射和预期执行状态。
+
+每个 case 必须包含：
+
+1. 元信息：功能、CRUD 分类、维度、关联 AC、RAG 来源、API 映射状态与数据策略。
+2. 前置条件：独立 `-s=<case-id>` session、登录状态、fixture/存量数据、清理责任。
+3. 可独立执行的命令序列：`open --browser=chrome --headed <base-url>`、按需登录/数据准备、
+   `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`。
+
+## 覆盖矩阵
+
+| CRUD 类型 | 必选 | 条件 |
+| --- | --- | --- |
+| C-新增 | `core`、`boundary` | 有状态流转时 `flow`；有 API 映射时 `backend` |
+| R-查询 | `core` | 有搜索/筛选输入时 `boundary`；有 API 映射时 `backend` |
+| U-修改 | `core`、`boundary` | 有状态流转时 `flow`；有 API 映射时 `backend` |
+| D-删除 | `core` | 有 API 映射时 `backend` |
+
+- `boundary` 只从已知必填、长度、范围、精度、枚举或字符规则推导；无约束时
+  不伪造边界值。
+- `flow` 是自包含的多步状态旅程；每个关键步骤都有 UI 与已知数据一致性断言，
+  不依赖其他 case 创建的数据。
+- `backend` 只在 API 映射存在时使用 `requests` / `request <id>`，或在精确时序
+  下使用 `run-code`。错误、空态或超时使用 `route`，并在 cleanup 中 `unroute`。
+  响应字段和性能阈值必须来自 RAG。
+
+## 数据策略
+
+- C-新增优先使用需求中给出的测试数据；仅在已授权 API 映射存在时才描述临时构造
+  与清理。
+- R/U/D 优先使用知识包登记的 fixture 或 test-data；不足时只能使用已授权的
+  测试环境 API 注入并清理。
+- 禁止使用生产 URL、真实用户凭据或不可清理的数据写入。无法证明隔离与清理时，
+  case 必须为 `blocked`。
+
+## 交接
+
+生成结束时仅返回紧凑 JSON 摘要：case 总数、各维度数量、manifest 相对路径、
+blocked case ID 与原因。详细内容保留在 case 文件，供后续 manifest/map 子节点
+逐 case 读取，避免把完整用例塞进上游上下文。

package/skills/requesting-code-review/SKILL.md

@@ -1,101 +1,101 @@
----
-name: requesting-code-review
-description: 在完成任务、实现 major features，或 merge 前验证 work 是否满足 requirements 时使用
----
-
-# Requesting Code Review
-
-Dispatch code reviewer subagent，在问题级联前捕获 issue。Reviewer 获得精确 crafted 的 evaluation context — 绝不是你的 session history。这使 reviewer 聚焦 work product，而非你的 thought process，并保留你自己的 context 以继续工作。
-
-**Core principle：** Review early, review often.
-
-## When to Request Review
-
-**Mandatory：**
-- subagent-driven development 中每个 task 之后
-- 完成 major feature 之后
-- merge 到 main 之前
-
-**Optional but valuable：**
-- 卡住时（fresh perspective）
-- refactoring 前（baseline check）
-- 修复 complex bug 之后
-
-## How to Request
-
-**1. Get git SHAs:**
-```bash
-BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
-HEAD_SHA=$(git rev-parse HEAD)
-```
-
-**2. Use the code reviewer template**（本 skill 目录下的 `code-reviewer.md`）：
-
-**Placeholders:**
-- `{DESCRIPTION}` — 简要 summary of what you built
-- `{PLAN_OR_REQUIREMENTS}` — 它应做什么（contract、exec plan 或 requirements）
-- `{BASE_SHA}` — Starting commit
-- `{HEAD_SHA}` — Ending commit
-
-**3. Act on feedback:**
-- Critical issues 立即修复
-- Important issues 在继续前修复
-- Minor issues 稍后处理
-- Reviewer 有误时 push back（附 reasoning）
-
-## Example
-
-```
-[Just completed Task 2: Add verification function]
-
-You: Let me request code review before proceeding.
-
-BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
-HEAD_SHA=$(git rev-parse HEAD)
-
-[Dispatch code reviewer subagent]
-  DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
-  PLAN_OR_REQUIREMENTS: Task 2 from docs/exec-plans/active/deployment-plan.md
-  BASE_SHA: a7981ec
-  HEAD_SHA: 3df7661
-
-[Subagent returns]:
-  Strengths: Clean architecture, real tests
-  Issues:
-    Important: Missing progress indicators
-    Minor: Magic number (100) for reporting interval
-  Assessment: Ready to proceed
-
-You: [Fix progress indicators]
-[Continue to Task 3]
-```
-
-## Integration with Harness Workflow
-
-**每个 work chunk 之后（Plan → Contract → Implement → Verify → Handoff）：**
-- Implement 之后、Verify 之前 review
-- 在问题 compound 前捕获
-- 进入 next task 前修复
-
-**Before merge / Handoff：**
-- 宣称 complete 前 review
-- 对照 contract acceptance criteria 验证
-
-**Ad-Hoc Development：**
-- merge 前 review
-- 卡住时 review
-
-## Red Flags
-
-**Never：**
-- 因 "it's simple" 跳过 review
-- 忽略 Critical issues
-- 带着未修复的 Important issues 继续
-- 与 valid technical feedback 争辩
-
-**If reviewer wrong：**
-- 用 technical reasoning push back
-- 展示证明其有效的 code/tests
-- 请求 clarification
-
-Template 见：requesting-code-review/code-reviewer.md
+---
+name: requesting-code-review
+description: 在完成任务、实现 major features，或 merge 前验证 work 是否满足 requirements 时使用
+---
+
+# Requesting Code Review
+
+Dispatch code reviewer subagent，在问题级联前捕获 issue。Reviewer 获得精确 crafted 的 evaluation context — 绝不是你的 session history。这使 reviewer 聚焦 work product，而非你的 thought process，并保留你自己的 context 以继续工作。
+
+**Core principle：** Review early, review often.
+
+## When to Request Review
+
+**Mandatory：**
+- subagent-driven development 中每个 task 之后
+- 完成 major feature 之后
+- merge 到 main 之前
+
+**Optional but valuable：**
+- 卡住时（fresh perspective）
+- refactoring 前（baseline check）
+- 修复 complex bug 之后
+
+## How to Request
+
+**1. Get git SHAs:**
+```bash
+BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
+HEAD_SHA=$(git rev-parse HEAD)
+```
+
+**2. Use the code reviewer template**（本 skill 目录下的 `code-reviewer.md`）：
+
+**Placeholders:**
+- `{DESCRIPTION}` — 简要 summary of what you built
+- `{PLAN_OR_REQUIREMENTS}` — 它应做什么（contract、exec plan 或 requirements）
+- `{BASE_SHA}` — Starting commit
+- `{HEAD_SHA}` — Ending commit
+
+**3. Act on feedback:**
+- Critical issues 立即修复
+- Important issues 在继续前修复
+- Minor issues 稍后处理
+- Reviewer 有误时 push back（附 reasoning）
+
+## Example
+
+```
+[Just completed Task 2: Add verification function]
+
+You: Let me request code review before proceeding.
+
+BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
+HEAD_SHA=$(git rev-parse HEAD)
+
+[Dispatch code reviewer subagent]
+  DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
+  PLAN_OR_REQUIREMENTS: Task 2 from docs/exec-plans/active/deployment-plan.md
+  BASE_SHA: a7981ec
+  HEAD_SHA: 3df7661
+
+[Subagent returns]:
+  Strengths: Clean architecture, real tests
+  Issues:
+    Important: Missing progress indicators
+    Minor: Magic number (100) for reporting interval
+  Assessment: Ready to proceed
+
+You: [Fix progress indicators]
+[Continue to Task 3]
+```
+
+## Integration with Harness Workflow
+
+**每个 work chunk 之后（Plan → Contract → Implement → Verify → Handoff）：**
+- Implement 之后、Verify 之前 review
+- 在问题 compound 前捕获
+- 进入 next task 前修复
+
+**Before merge / Handoff：**
+- 宣称 complete 前 review
+- 对照 contract acceptance criteria 验证
+
+**Ad-Hoc Development：**
+- merge 前 review
+- 卡住时 review
+
+## Red Flags
+
+**Never：**
+- 因 "it's simple" 跳过 review
+- 忽略 Critical issues
+- 带着未修复的 Important issues 继续
+- 与 valid technical feedback 争辩
+
+**If reviewer wrong：**
+- 用 technical reasoning push back
+- 展示证明其有效的 code/tests
+- 请求 clarification
+
+Template 见：requesting-code-review/code-reviewer.md