@tea-agent/loop-agent 0.13.0-alpha.0 → 0.13.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

@@ -55,7 +55,7 @@ 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
+  PLAN_OR_REQUIREMENTS: Task 2 from ai_workspace/loop-agent/exec-plans/active/deployment-plan.md
   BASE_SHA: a7981ec
   HEAD_SHA: 3df7661
 

package/skills/systematic-debugging/CREATION-LOG.md

@@ -54,7 +54,7 @@ Framework 设计以 resist rationalization under pressure：
 
 ## Testing Approach
 
-按 skills/meta/testing-skills-with-subagents 创建 4 个 validation tests：
+按 .agents/skills/meta/testing-skills-with-subagents 创建 4 个 validation tests：
 
 ### Test 1: Academic Context (No Pressure)
 - Simple bug，无 time pressure
@@ -82,7 +82,7 @@ Framework 设计以 resist rationalization under pressure：
 - Flowchart for "fix failed" decision
 
 ### Enhancement 1: TDD Reference
-- Added link to skills/testing/test-driven-development
+- Added link to .agents/skills/testing/test-driven-development
 - Note explaining TDD's "simplest code" ≠ debugging's "root cause"
 - Prevents confusion between methodologies
 
@@ -104,7 +104,7 @@ Bulletproof skill that:
 ## Usage Example
 
 遇到 bug 时：
-1. Load skill: skills/debugging/systematic-debugging
+1. Load skill: .agents/skills/debugging/systematic-debugging
 2. Read overview (10 sec) — reminded of mandate
 3. Follow Phase 1 checklist — forced investigation
 4. If tempted to skip — see anti-pattern，stop

package/skills/systematic-debugging/SKILL.md

@@ -284,7 +284,7 @@ NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
 - **`condition-based-waiting.md`** — 用 condition polling 替代 arbitrary timeouts
 
 **Related principles:**
-- **RED-GREEN-REFACTOR**（见 `docs/harness-methodology-tdd.md`）— 用于 creating failing test case（Phase 4, Step 1）
+- **RED-GREEN-REFACTOR**（见 `ai_workspace/loop-agent/harness-methodology-tdd.md`）— 用于 creating failing test case（Phase 4, Step 1）
 - **Verification discipline** — 宣称 success 前 verify fix worked。Run verification command，读 output，THEN claim result。
 
 ## Real-World Impact

package/skills/systematic-debugging/test-academic.md

@@ -1,6 +1,6 @@
 # Academic Test: Systematic Debugging Skill
 
-You have access to the systematic debugging skill at skills/debugging/systematic-debugging
+You have access to the systematic debugging skill at .agents/skills/debugging/systematic-debugging
 
 Read the skill and answer these questions based SOLELY on what the skill says:
 

package/skills/systematic-debugging/test-pressure-1.md

@@ -2,7 +2,7 @@
 
 **IMPORTANT: This is a real scenario. You must choose and act. Don't ask hypothetical questions - make the actual decision.**
 
-You have access to: skills/debugging/systematic-debugging
+You have access to: .agents/skills/debugging/systematic-debugging
 
 ## Scenario
 

package/skills/systematic-debugging/test-pressure-2.md

@@ -2,7 +2,7 @@
 
 **IMPORTANT: This is a real scenario. You must choose and act. Don't ask hypothetical questions - make the actual decision.**
 
-You have access to: skills/debugging/systematic-debugging
+You have access to: .agents/skills/debugging/systematic-debugging
 
 ## Scenario
 

package/skills/systematic-debugging/test-pressure-3.md

@@ -2,7 +2,7 @@
 
 **IMPORTANT: This is a real scenario. You must choose and act. Don't ask hypothetical questions - make the actual decision.**
 
-You have access to: skills/debugging/systematic-debugging
+You have access to: .agents/skills/debugging/systematic-debugging
 
 ## Scenario
 

package/skills/verification-before-completion/SKILL.md

@@ -118,7 +118,7 @@ Skip any step = lying, not verifying
 - **Contract changes** → 验证 contract docs 已更新 + tests 对齐
 - **Handoff** → 宣称 complete 前运行 `handoff check`
 
-完整 command 选择见项目 `docs/verification-matrix.md`。
+完整 command 选择见项目 `ai_workspace/loop-agent/verification-matrix.md`。
 
 ## Why This Matters