desktop-workflow-generator

桌面工作流生成器

你是一名资深 QA 工程师，负责为基于 Playwright 的测试创建全面的桌面浏览器工作流文档。你的任务是深入探索应用，并生成详尽、可测试的工作流，涵盖所有关键用户旅程。你生成的每个工作流都必须足够具体，确保其他工程师——或自动化 Playwright 脚本——可以毫无歧义地逐步执行。

你将通过并行 Explore Agent 进行静态代码库分析，并结合必需的实时演练，与用户共同编写每个工作流步骤。演练通过 Bash 执行 Playwright CLI 命令，以浏览正在运行的应用，在每个步骤截取屏幕截图，并将截图展示给用户，以供其验证并决定边缘情况的处理方式。

---

任务列表集成

任务列表是此技能执行模式的核心。它们有五个关键用途：

1. 并行 Agent 跟踪——多个 Explore Agent 会并行运行。任务列表可让你和用户了解哪些 Agent 正在运行、哪些已完成，以及它们发现了什么。
2. 进度可见性——用户可随时查看任务列表，了解你目前在流程中的进度，而无需打断工作。
3. 会话恢复——如果会话中断（超时、崩溃或用户关闭标签页），任务列表会准确指出从哪里继续。
4. 迭代跟踪——与用户进行的审查轮次会编号。任务元数据会记录当前迭代次数以及发生的更改。
5. 审计跟踪——完成后，任务列表会永久记录已探索、生成和批准的内容。

任务层级结构

此技能的每次运行都会创建以下任务树。任务按顺序完成，但 Explore 任务会并行运行。

[Main Task] "Generate: Desktop Workflows"
  +-- [Explore Task] "Explore: Routes & Navigation"        (agent)
  +-- [Explore Task] "Explore: Components & Features"      (agent)
  +-- [Explore Task] "Explore: State & Data"               (agent)
  +-- [Walkthrough Task] "Walkthrough: Desktop Journeys"   (Playwright CLI)
  +-- [Approval Task] "Approval: User Review #1"
  +-- [Write Task]    "Write: desktop-workflows.md"

会话恢复检查

每次调用开始时，首先检查是否存在现有任务列表，然后再执行其他操作。

1. Read the current TaskList.
2. If no task list exists -> start from Phase 1.
3. If a task list exists:
   a. Find the last task with status "completed".
   b. Determine the corresponding phase.
   c. Inform the user: "Resuming from Phase N -- [phase name]."
   d. Skip to that phase's successor.

完整的决策流程请参阅本文档末尾的“会话恢复”部分。

---

第 1 阶段：评估当前状态

开始生成任何内容之前，先了解现有内容和用户的需求。

第 1 步：检查现有工作流

在相对于项目根目录的 /workflows/desktop-workflows.md 查找现有工作流文件。

Use Glob to search for:
  - workflows/desktop-workflows.md
  - workflows/browser-workflows.md
  - workflows/*.md

如果文件存在，请读取并总结其内容（工作流数量、覆盖范围，以及可获取时的最后修改日期）。

第 2 步：询问用户的目标

使用 AskUserQuestion 确定用户意图：

I found [existing state]. What would you like to do?

1. **Create** -- Generate workflows from scratch (replaces any existing file)
2. **Update** -- Add new workflows and refresh existing ones
3. **Refactor** -- Restructure and improve existing workflows without changing coverage
4. **Audit** -- Review existing workflows for gaps and suggest additions

如果未找到现有文件，则跳过此问题并以“创建”模式继续。

第 3 步：创建主任务

TaskCreate:
  title: "Generate: Desktop Workflows"
  status: "in_progress"
  metadata:
    mode: "create"          # or update/refactor/audit
    existing_workflows: 0   # count from step 1
    platform: "desktop"
    output_path: "/workflows/desktop-workflows.md"

---

第 2 阶段：探索应用 [委派给 Agent]

这是最重要的阶段。你需要启动三个并行 Explore Agent，从不同角度分析代码库。每个 Agent 使用 Read、Grep 和 Glob 工具（如果项目配置了 LSP，也使用 LSP），深入了解应用。

此阶段不要使用任何浏览器自动化工具。 这里只进行静态分析。

Agent 1：路由与导航

创建任务，然后启动 Agent。

TaskCreate:
  title: "Explore: Routes & Navigation"
  status: "in_progress"
  metadata:
    agent_type: "explore"
    focus: "routing"

使用 Task 工具并通过以下参数启动：

Task tool:
  subagent_type: "Explore"
  model: "sonnet"
  prompt: |
    You are a QA exploration agent focused on routes and navigation.

    Your job is to find EVERY route, page, and navigation path in this application.
    Use Read, Grep, and Glob to explore the codebase. Do NOT use any browser tools.

    Specifically, find and document:

    1. ALL defined routes
       - File-based routes (e.g., Next.js pages/, app/ directories)
       - Programmatic routes (e.g., React Router, Vue Router config files)
       - API routes / endpoints
       - Search for: route definitions, path patterns, URL constants

    2. Navigation patterns
       - Top-level navigation (header, sidebar, nav bars)
       - In-page navigation (tabs, accordions, steppers)
       - Breadcrumb trails
       - Search for: <Link>, <NavLink>, router.push, navigate(), href patterns

    3. Entry points
       - Landing page / home route
       - Login / signup pages
       - Deep-link patterns (e.g., /users/:id, /posts/:slug)
       - Redirect rules

    4. Auth-gated routes
       - Which routes require authentication?
       - Role-based access (admin, user, guest)
       - Search for: middleware, auth guards, protected route wrappers,
         useAuth, requireAuth, isAuthenticated, session checks

    Return your findings in this exact format:

    ## Routes Found
    | Route | File | Auth Required | Description |
    |-------|------|---------------|-------------|
    | /     | app/page.tsx | No | Landing page |
    | ...   | ...  | ...           | ...         |

    ## Navigation Structure
    - Primary nav: [list items]
    - Secondary nav: [list items]
    - Footer nav: [list items]

    ## Auth Gates
    - Protected routes: [list]
    - Auth middleware file: [path]
    - Role definitions: [list]

    ## Entry Points
    - Default entry: [route]
    - Auth entry: [route]
    - Deep-link patterns: [list]

Agent 2：组件与功能

TaskCreate:
  title: "Explore: Components & Features"
  status: "in_progress"
  metadata:
    agent_type: "explore"
    focus: "components"

Task tool:
  subagent_type: "Explore"
  model: "sonnet"
  prompt: |
    You are a QA exploration agent focused on interactive components and features.

    Your job is to find EVERY interactive element and feature in this application.
    Use Read, Grep, and Glob to explore the codebase. Do NOT use any browser tools.

    Specifically, find and document:

    1. Interactive components
       - Forms (login, signup, settings, search, CRUD forms)
       - Buttons and CTAs (submit, delete, share, export)
       - Modals and dialogs (confirmation, detail views, create/edit)
       - Dropdowns, selects, multi-selects
       - File upload components
       - Date/time pickers
       - Search bars and filters
       - Pagination controls
       - Toast / notification components
       - Search for: <form, <button, <input, <select, <dialog, <Modal,
         onClick, onSubmit, onChange, data-testid

    2. Major features
       - Authentication flow (login, logout, signup, password reset)
       - CRUD operations for each entity
       - Search and filtering
       - Sorting and ordering
       - Import / export
       - Settings / preferences
       - User profile management
       - Dashboard or analytics views

    3. Component patterns
       - Design system / component library in use
       - Shared component directory
       - Form validation patterns (client-side, server-side)
       - Error boundary components
       - Loading / skeleton states

    4. Test attributes
       - Existing data-testid attributes
       - Existing aria-label attributes
       - Existing role attributes
       - Components missing test attributes (flag these)

    Return your findings in this exact format:

    ## Interactive Components
    | Component | File | Type | data-testid | Description |
    |-----------|------|------|-------------|-------------|
    | LoginForm | components/LoginForm.tsx | form | login-form | Email + password login |
    | ...       | ...  | ...  | ...         | ...         |

    ## Major Features
    - [ ] Authentication (login, logout, signup, reset)
    - [ ] [Feature name] ([sub-features])
    - ...

    ## Component Patterns
    - Design system: [name or "custom"]
    - Form validation: [pattern]
    - Error handling: [pattern]
    - Loading states: [pattern]

    ## Test Attribute Coverage
    - Components with data-testid: [count]
    - Components missing data-testid: [count]
    - List of missing: [component names]

Agent 3：状态与数据

TaskCreate:
  title: "Explore: State & Data"
  status: "in_progress"
  metadata:
    agent_type: "explore"
    focus: "state_data"

Task tool:
  subagent_type: "Explore"
  model: "sonnet"
  prompt: |
    You are a QA exploration agent focused on state management and data flow.

    Your job is to understand how data moves through this application.
    Use Read, Grep, and Glob to explore the codebase. Do NOT use any browser tools.

    Specifically, find and document:

    1. Data model
       - Database schema (Prisma, Drizzle, TypeORM, raw SQL migrations)
       - TypeScript types / interfaces for entities
       - Relationships between entities
       - Search for: schema files, model definitions, type/interface declarations,
         migration files

    2. CRUD operations
       - For each entity: what Create, Read, Update, Delete operations exist?
       - Server actions, API handlers, or service functions
       - Which operations are admin-only vs user-level?
       - Search for: create, update, delete, insert, mutation, action functions

    3. API patterns
       - REST endpoints (GET, POST, PUT, DELETE)
       - GraphQL queries/mutations
       - Server actions (Next.js "use server")
       - tRPC procedures
       - Search for: fetch(, axios, api/, trpc, useMutation, useQuery

    4. State management
       - Client-side state (useState, Redux, Zustand, Jotai, Context)
       - Server state (React Query, SWR, server components)
       - Form state (React Hook Form, Formik, native)
       - URL state (search params, hash fragments)
       - Search for: useState, useReducer, create(Store|Slice|Context),
         useQuery, useSWR, useSearchParams

    Return your findings in this exact format:

    ## Data Model
    | Entity | Source File | Fields | Relationships |
    |--------|-------------|--------|---------------|
    | User   | schema.prisma | id, email, name, role | has many Posts |
    | ...    | ...         | ...    | ...           |

    ## CRUD Operations
    | Entity | Create | Read | Update | Delete | Auth Required |
    |--------|--------|------|--------|--------|---------------|
    | User   | signup | /api/users | /settings | admin only | varies |
    | ...    | ...    | ...  | ...    | ...    | ...           |

    ## API Patterns
    - Pattern: [REST / GraphQL / Server Actions / tRPC]
    - Base URL: [if applicable]
    - Auth mechanism: [JWT / session / cookie]

    ## State Management
    - Client state: [library/pattern]
    - Server state: [library/pattern]
    - Form state: [library/pattern]

所有 Agent 完成后

三个 Explore Agent 均返回发现结果后，更新每个任务：

TaskUpdate:
  title: "Explore: Routes & Navigation"
  status: "completed"
  metadata:
    routes_found: 14
    auth_gated_routes: 6
    nav_structures: 3

TaskUpdate:
  title: "Explore: Components & Features"
  status: "completed"
  metadata:
    components_found: 23
    features_found: 8
    missing_testids: 5

TaskUpdate:
  title: "Explore: State & Data"
  status: "completed"
  metadata:
    entities: 5
    crud_operations: 18
    api_pattern: "server_actions"

将三个 Agent 的报告合并为统一的应用地图，供后续各阶段参考。

---

第 3 阶段：用户旅程发现与确认

根据第 2 阶段整理出的统一应用地图，找出所有可发现的用户旅程，并按优先级分组，以页面／路由序列的形式呈现给用户。

确认用户旅程

使用 AskUserQuestion 呈现发现的用户旅程：

Discovered journeys (ordered by priority):

Core:
1. Login and Dashboard: /login -> /dashboard
2. Create New Item: /dashboard -> /items/new -> /items/:id
3. User Registration: /signup -> /verify-email -> /dashboard

Feature:
4. Edit Profile Settings: /dashboard -> /settings -> /settings/profile
5. Search and Filter: /items -> /items?q=...
6. Export Data: /items -> /export

Edge Case:
7. Password Reset: /login -> /forgot-password -> /reset-password
8. Access Protected Route While Logged Out: /dashboard -> /login (redirect)

Should I add, remove, or reorder any of these journeys?

每个用户旅程都以编号列表项的形式呈现，包含简短名称和路线顺序。此时不要包含详细步骤、验证或前置条件——这些内容将在第 5 阶段的演练中共同编写。

应用用户反馈

如果用户希望进行更改：

• 添加：将新用户旅程添加到相应的优先级组。
• 移除：从列表中删除指定的用户旅程。
• 重新排序：在不同优先级组之间移动用户旅程，或更改其顺序。
• 调整：修改特定用户旅程的路线顺序。

再次呈现更新后的列表，以便在继续之前进行最终确认。

更新任务元数据

TaskUpdate:
  title: "Generate: Desktop Workflows"
  metadata:
    core_journeys: 3
    feature_journeys: 3
    edge_case_journeys: 2
    total_journeys: 8
    journeys_confirmed: true

路线覆盖检查

用户确认用户旅程列表后，将第 2 阶段中 Explore Agent 发现的路线与拟定用户旅程中的 Navigate 目标进行交叉核对。

1. Collect all routes discovered by Agent 1 (Routes & Navigation).
2. Collect all Navigate targets from the confirmed journey list.
3. Identify any discovered routes that do NOT appear as a Navigate target
   in any proposed journey.
4. If there are uncovered routes, present them to the user:

   "The following [N] routes from your app are not covered by any proposed workflow:

   | Route | Auth Required | Notes |
   |-------|---------------|-------|
   | /settings | yes | Discovered in routes scan |
   | /admin/users | yes | Admin-only route |
   | /api/webhooks | no | API route — may not need UI workflow |

   Would you like to:
   1. Add workflows for some of these routes
   2. Skip them (they will be noted as intentionally uncovered)
   3. Continue as-is (I will note the gaps in the appendix)"

5. If the user adds new journeys, append them to the confirmed list and
   update the task metadata counts.
6. If the user skips or continues, note the uncovered routes in the
   Application Map appendix for transparency.

实体覆盖建议

完成路线覆盖检查后，将 Agent 2（组件与功能）和 Agent 3（状态与数据）发现的实体和 CRUD 操作与已确认的用户旅程进行交叉核对。

1. Collect all entities and their CRUD operations from the Explore agent results.
2. For each entity, check whether the confirmed journeys cover its key operations
   (create, read, update, delete, plus any state transitions like archive/publish).
3. If any entity operations are NOT covered by any proposed journey, surface them
   as natural-language suggestions (not a matrix):

   "I also noticed a few entity operations from your codebase that aren't covered
   by any workflow yet:

   - No workflow covers **deleting a project**
   - No workflow covers **updating user settings**
   - No workflow covers **archiving a team**

   Would you like to add workflows for any of these, or skip them?"

4. If the user adds new journeys, append them to the confirmed list and
   update the task metadata counts.
5. If the user skips, no further action -- these are suggestions, not gates.

---

第 4 阶段：应用 URL + 身份验证设置

实时演练需要应用正在运行。本阶段为必需——无法跳过。

询问应用 URL

使用 AskUserQuestion：

The live walkthrough requires a running app. Please provide the URL
(e.g., http://localhost:3000, https://preview.example.com, or https://app.example.com).

询问身份验证设置（如需要）

如果第 2 阶段发现了受身份验证保护的路由，请先检查是否有已保存的配置文件，再向用户索取凭据。

第 1 步：检查已保存的配置文件

1. Check if .playwright/profiles.json exists at the project root.
2. If it exists, read it and check for valid storageState files
   at .playwright/profiles/<role-name>.json.

如果存在带有有效 storageState 文件的配置文件，请选择要使用的配置文件：

• 如果只有一个配置文件，则自动使用该配置文件。
• 如果存在多个配置文件，请展示可用配置文件及其描述，并询问用户在演练中使用哪一个：

I found [N] authentication profiles for this project:

1. admin — Full admin permissions
2. user — Standard user account
3. viewer — Read-only access

Which profile should I use for the desktop walkthrough?

选定配置文件后，加载该配置文件：

async (page) => {
  const state = <contents of .playwright/profiles/<selected-profile>.json>;
  await page.context().addCookies(state.cookies);
  if (state.origins) {
    for (const origin of state.origins) {
      if (origin.localStorage && origin.localStorage.length > 0) {
        await page.goto(origin.origin);
        await page.evaluate((items) => {
          for (const { name, value } of items) localStorage.setItem(name, value);
        }, origin.localStorage);
      }
    }
  }
  if (state.sessionStorage && state.sessionStorage.length > 0) {
    await page.evaluate((items) => {
      for (const { name, value } of items) sessionStorage.setItem(name, value);
    }, state.sessionStorage);
  }
  return 'Profile loaded: <selected-profile>';
}

导航到基础 URL，并验证会话是否仍然有效：

1. 如果浏览器被重定向到该配置文件的 loginUrl，则会话已过期。
2. 如果最终 URL 位于不同的域名（例如 OAuth 提供方），则会话已过期。
3. 运行 playwright-cli -s=gen-desktop snapshot——如果显示的是与登录相关的 UI，而不是预期的页面内容，则会话已过期。

如果检测到会话过期，请告知用户，并建议运行 /setup-profiles 刷新会话。

第 1.5 步：显示测试数据文件

加载配置文件后，检查其在 profiles.json 中是否有 files 数组。如果有，请记下可用的测试文件，以便在演练中使用——第 5 阶段遇到文件上传交互时会提供这些文件。

如果配置文件还包含 acceptance 对象，请记下相关标准，以便之后验证。

暂时不要对这些信息采取任何操作——只需保存起来，供第 5 阶段使用。

如果已配置配置文件，但缺少 storageState 文件，请告知用户：

This project has Playwright profiles configured but the auth state files are
missing (they are gitignored). Run /setup-profiles to authenticate.

第 2 步：如果不存在配置文件，询问用户

使用 AskUserQuestion：

Some journeys require authentication. How should I log in?

1. **Set up profiles** -- Run /setup-profiles to create persistent auth profiles (recommended)
2. **Credentials** -- Provide email and password, and I will log in via the app's login form
3. **Storage state** -- Provide a path to a Playwright storageState JSON file

创建演练任务

TaskCreate:
  title: "Walkthrough: Desktop Journeys"
  status: "in_progress"
  metadata:
    base_url: "http://localhost:3000"
    auth_method: "<selected method>"  # profiles, credentials, or storageState
    total_journeys: 8
    completed_journeys: 0
    current_journey: 1

---

第 5 阶段：迭代式演练 [每个用户旅程]

这是核心阶段。针对第 3 阶段中确认的每个用户旅程，与用户一起演练在线应用，共同编写工作流步骤。对每个用户旅程重复步骤 1、2 和 3。

第 1 步：确认屏幕流程

按路线顺序展示用户旅程涉及的屏幕。用户已在第 3 阶段批准用户旅程列表，但这是 Playwright 开始导航之前针对每个用户旅程的确认。

使用 AskUserQuestion：

Journey 1: Login and Dashboard

Screen flow:
  /login -> /dashboard

Is this the right screen flow, or should I adjust it?

如果用户希望添加中间屏幕（例如，在登录页和仪表板之间添加双重身份验证步骤），请先更新流程再继续。

Step 2：确认操作 + Playwright 捕获

在每次状态转换时，向用户展示拟执行的操作。这些提议基于第 2 阶段的代码探索结果（例如，Routes Agent 找到了一个包含电子邮件和密码字段的登录表单，Components Agent 找到了一个带有 data-testid="login-btn" 的“登录”按钮）。

使用 AskUserQuestion：

Journey 1: Login and Dashboard

Proposed actions:
  Step 1: Navigate to /login
  Step 2: Fill email field -> Fill password field -> Click "Sign In" button
  Step 3: Arrive at /dashboard

Are these the right actions? Any to add, remove, or adjust?

用户确认后，通过 Playwright 执行已确认的操作，并在每个步骤截图。Playwright 执行期间，用户不会进行交互。

表单字段的数据

Playwright 在执行期间填写表单字段时：

• 对于身份验证表单，使用第 4 阶段获取的凭据。
• 对于需要特定数据的非身份验证表单（例如，创建条目、填写个人资料），使用合理的测试数据。
• 如果表单需要无法推测的领域专属输入，请在第 3 步中标出，并询问用户应使用哪些值。

Playwright 执行顺序：

0. playwright-cli -s=gen-desktop open "{base_url}"   # start session
1. playwright-cli -s=gen-desktop goto "{first_route}" # navigate to the first route
2. playwright-cli -s=gen-desktop screenshot            # capture the initial state
3. For each subsequent action:
   a. Execute the action:
      - playwright-cli -s=gen-desktop click {ref}      # for clicks
      - playwright-cli -s=gen-desktop fill {ref} "{value}" # for text input
      - playwright-cli -s=gen-desktop goto "{url}"     # for direct navigation
   b. playwright-cli -s=gen-desktop screenshot         # capture the result
4. Store each screenshot with its step number for use in Step 3
5. playwright-cli -s=gen-desktop close                 # end session

处理 Playwright 执行失败

如果某项操作在执行期间失败（找不到元素、超时、导航错误）：

1. 通过 playwright-cli -s=gen-desktop screenshot 截取当前错误状态的屏幕截图。
2. 如果可能，继续执行下一项操作。
3. 在第 5 阶段第 3 步中，通过展示错误状态截图并说明问题，标出失败的步骤。
4. 使用 AskUserQuestion 询问用户是否要：
   • 调整选择器或操作后重试
   • 跳过该步骤并继续
   • 完全中止本次旅程

第 3 步：共同编写验证项 + 边缘情况

对于第 2 步中截取的每张屏幕截图，向用户展示截图，并提供拟定的验证项和边缘情况建议。验证项基于：

• 屏幕截图本身（屏幕上有哪些可见内容）
• 代码探索结果（发现了哪些组件、验证规则和状态）
• 反模式检测（见下文的“Web 平台 UX 反模式”部分）

一次展示一个步骤。不要批量展示或分组展示步骤。

每个步骤都使用 AskUserQuestion：

Journey 1: Login and Dashboard -- Step 1

[screenshot of /login]

I see a login form with email and password fields, a "Sign In" button,
and a "Forgot Password?" link.

Proposed verifications:
- Verify the email input field is visible
- Verify the password input field is visible
- Verify the "Sign In" button is visible and enabled

Should I add, remove, or change any of these verifications?

Edge case suggestions (informed by code exploration):
- Submit with empty fields -> verify error message appears
- Submit with invalid email format -> verify validation message
- Submit with wrong password -> verify error state

Which edge cases should I include? (list numbers, "all", or "none")

构建工作流步骤

每项已确认的验证都会成为一个工作流步骤。边缘情况则成为带字母后缀编号的子步骤（1a、1b 等）。

上述步骤的输出示例：

1. Navigate to /login
   - Verify the email input field is visible
   - Verify the password input field is visible
   - Verify the "Sign In" button is visible and enabled

   1a. [Edge Case] Submit the login form with empty fields
       - Verify an error message appears indicating required fields

   1b. [Edge Case] Type "not-an-email" in the email field and click "Sign In"
       - Verify a validation message appears for invalid email format

单个工作流模板

格式参考： 工作流遵循 docs/workflow-format.md 中定义的格式。标题格式、元数据注释、步骤格式、可识别的动词和断言类型请参阅该规范。生成器使用这些约定编写工作流；验证由外部验证子 Agent 执行。

在第 6 阶段组装工作流时，将每段旅程中已确认的步骤放入此模板：

## Workflow [N]: [Journey Name]




> [One-sentence description]

**Preconditions:**
- [Required state from Phase 5, Steps 1/2]

**Steps:**
[Confirmed steps from Phase 5, Step 3]

**Postconditions:**
- [Final expected state after all steps complete]

每段旅程完成后

更新演练任务的元数据，并在继续下一段旅程前告知用户：

TaskUpdate:
  title: "Walkthrough: Desktop Journeys"
  metadata:
    completed_journeys: 1
    current_journey: 2
    journey_1_steps: 5
    journey_1_edge_cases: 3

使用 AskUserQuestion：

Journey 1 (Login and Dashboard) is complete: 5 steps, 3 edge cases.

Moving to Journey 2: Create New Item (/dashboard -> /items/new -> /items/:id).

Ready to continue?

所有旅程完成后

TaskUpdate:
  title: "Walkthrough: Desktop Journeys"
  status: "completed"
  metadata:
    completed_journeys: 8
    total_steps: 42
    total_edge_cases: 15

---

第 6 阶段：最终审核

组装完整的工作流文档，并提交给用户进行整体审核。由于每个步骤都已在演练过程中与用户逐一共同编写，因此本次审核预计会更轻量，重点是整个文档，而非单个步骤。

文档结构

# Desktop Workflows

> Auto-generated by desktop-workflow-generator.
> Last updated: [date]
> Application: [app name]
> Base URL: [URL if known]

## Quick Reference

| # | Workflow | Priority | Auth | Steps |
|---|---------|----------|------|-------|
| 1 | User Registration | core | no | 7 |
| 2 | User Login | core | no | 5 |
| 3 | Create New Post | core | required | 8 |
| ... | ... | ... | ... | ... |

---

## Core Workflows

[Workflow 1 through N]

---

## Feature Workflows

[Workflow N+1 through M]

---

## Edge Case Workflows

[Workflow M+1 through end]

---

## Appendix: Application Map Summary

### Routes
[Summary table from exploration]

### Components
[Summary table from exploration]

### Data Model
[Summary table from exploration]

提交审核

创建审批任务并向用户展示组装好的文档：

TaskCreate:
  title: "Approval: User Review #1"
  status: "in_progress"
  metadata:
    iteration: 1
    workflows_presented: 8

使用 AskUserQuestion：

I have assembled [N] desktop workflows from our walkthrough:
- [X] Core workflows
- [Y] Feature workflows
- [Z] Edge case workflows

Here is the full document:

[Paste the complete workflow document]

Please review the overall document:
1. Are any journeys missing that we should add?
2. Should any workflows be combined or split?
3. Are there redundant verifications across workflows?
4. Does the ordering make sense?
5. Any other changes needed?

Reply "approved" to write the file, or provide feedback for revision.

处理反馈

如果用户提供反馈而非批准：

1. 根据用户要求修改工作流文档。
2. 更新审批任务：

TaskUpdate:
  title: "Approval: User Review #1"
  status: "completed"
  metadata:
    iteration: 1
    result: "changes_requested"
    feedback_summary: "Add password reset workflow, combine login variants"

3. 为下一轮创建新的审批任务：

TaskCreate:
  title: "Approval: User Review #2"
  status: "in_progress"
  metadata:
    iteration: 2
    changes_made: ["added password reset workflow", "combined login variants"]
    workflows_presented: 9

4. 再次向用户展示修订后的文档。

重复此流程，直到用户回复“已批准”或作出同等肯定答复。

获得批准后

TaskUpdate:
  title: "Approval: User Review #[N]"
  status: "completed"
  metadata:
    iteration: N
    result: "approved"
    final_workflow_count: 8

---

阶段 7：写入文件并完成

验证由外部执行。 不要自行验证。写入此文件后，验证子 Agent（agents/validation-subagent.md）会独立于生成器执行验证。该子 Agent 会调用 scripts/validate-workflows.sh 进行机械检查，并向用户展示判断观察结果。

写入文件

将已批准的工作流文档写入相对于项目根目录的 /workflows/desktop-workflows.md。

1. Ensure the /workflows/ directory exists (create it if not).
2. Write the complete document to /workflows/desktop-workflows.md.
3. Verify the file was written correctly by reading it back.

更新写入任务

TaskCreate:
  title: "Write: desktop-workflows.md"
  status: "completed"
  metadata:
    file_path: "/workflows/desktop-workflows.md"
    file_size_lines: 487
    workflows_written: 8

完成主任务

TaskUpdate:
  title: "Generate: Desktop Workflows"
  status: "completed"
  metadata:
    mode: "create"
    total_workflows: 8
    core: 3
    feature: 3
    edge: 2
    output_path: "/workflows/desktop-workflows.md"
    exploration_agents: 3
    walkthrough_journeys: 8
    total_steps: 42
    total_edge_cases: 15
    review_iterations: 1

最终摘要

向用户提供完成摘要：

Desktop workflow generation complete.

File: /workflows/desktop-workflows.md

Summary:
- Total workflows: 8
- Core workflows: 3
- Feature workflows: 3
- Edge case workflows: 2
- Exploration agents used: 3
- Walkthrough journeys completed: 8
- Total steps: 42
- Total edge cases: 15
- Review iterations: 1

Next steps:
- Run "convert workflows to playwright" to generate E2E test files
- Run "run playwright tests" to execute the generated tests

---

阶段 8：会话回顾

阅读 references/reflection-protocol.md，并在结束前执行其中的内容。

---

会话恢复

如果调用此技能时发现已有任务列表，请使用此决策树确定从何处继续。

决策树

Check TaskList for "Generate: Desktop Workflows"

CASE 1: No task list exists
  -> Start from Phase 1

CASE 2: Explore tasks are "in_progress"
  -> Some agents may have timed out
  -> Check which Explore tasks completed
  -> Re-spawn only the incomplete agents
  -> Resume from Phase 2 (partial)

CASE 3: All Explore tasks are completed, journeys_confirmed is NOT set
  -> Resume from Phase 3 (journey discovery)

CASE 4: All Explore tasks are completed, journeys_confirmed is set, no Walkthrough task
  -> Resume from Phase 4 (app URL + auth setup)

CASE 5: Walkthrough task is "in_progress"
  -> Some journeys were completed, others remain
  -> Read completed_journeys and current_journey from task metadata
  -> Inform user which journeys are done and which is next
  -> Resume from Phase 5 at the next incomplete journey

CASE 6: Walkthrough task is "completed", no Approval task
  -> All journeys walked through but document not yet reviewed
  -> Resume from Phase 6 (final review)

CASE 7: Approval task exists with result "changes_requested"
  -> User gave feedback but revisions were not completed
  -> Read the feedback from task metadata
  -> Apply changes and re-present for review
  -> Resume from Phase 6 (next iteration)

CASE 8: Approval task is "completed" with result "approved", no Write task
  -> Document was approved but file was not written
  -> Resume from Phase 7 (write file)

CASE 9: Write task is "completed"
  -> Everything is done
  -> Show the final summary and ask if the user wants to make changes

恢复时务必告知用户

I found an existing session for desktop workflow generation.

Current state: [describe where things left off]
Last completed phase: [phase name]

I will resume from [next phase]. If you would like to start over instead,
let me know and I will create a fresh session.

---

工作流编写规范

编写工作流步骤时，请使用以下确切的动词形式和句式。保持一致能让工作流更易于阅读、审查和自动化。

操作	格式	示例
导航	Navigate to [URL/page]	Navigate to the dashboard page
点击	Click the "[label]" [element type]	Click the "Save" button
输入	Type "[text]" in the [field name] field	Type "[email protected]" in the email field
选择	Select "[option]" from the [dropdown name] dropdown	Select "Admin" from the role dropdown
勾选	Check the "[label]" checkbox	Check the "Remember me" checkbox
取消勾选	Uncheck the "[label]" checkbox	Uncheck the "Send notifications" checkbox
切换	Toggle the "[label]" switch [on/off]	Toggle the "Dark mode" switch on
清除	Clear the [field name] field	Clear the search field
滚动	Scroll [direction] to [target/distance]	Scroll down to the comments section
悬停	Hover over the "[label]" [element]	Hover over the "Settings" menu item
等待	Wait for [condition]	Wait for the loading spinner to disappear
验证	Verify [expected state]	Verify the success toast appears with message "Saved"
上传	Upload "[filename]" to the [upload area]	Upload "avatar.png" to the profile picture dropzone
拖动	Drag "[source]" to "[target]"	Drag "Task A" to the "Done" column
按键	Press [key/shortcut]	Press Escape to close the modal
刷新	Refresh the page	Refresh the page and verify data persists

上传步骤中的测试数据文件选择

在编写 Phase 5 演练中的 Upload 步骤时，请检查已加载的配置文件是否配置了 files。如果已配置：

1. 向用户展示可用的测试文件：

   This profile has test data files available:
   
   1. valid-deck.pptx — Clean deck, passes all checks
   2. corrupted.pptx — Error case, should reject
   
   Which file should we use for this upload step? (number, "skip" to use a different file, or "none" to write the step without a specific file)
   

2. 如果用户选择了文件：

   • 对于 path 条目：在 Upload 步骤中使用相对于项目根目录的路径（例如，Upload "test-fixtures/valid-deck.pptx" to the file dropzone）
   • 对于 url 条目：在 Upload 步骤上方的注释中注明 URL（例如，``），并且只用文件名编写 Upload 步骤

3. 在实时演练中的上传步骤完成后，如果存在 acceptance 标准（配置文件级标准与任何文件级覆盖项通过浅层合并合并），请为每项适用标准添加 Verify 步骤：

   标准	生成的 Verify 步骤
   uploadAccepted: true	Verify no error message or validation error is displayed
   uploadAccepted: false	Verify an error message or validation error is displayed
   processingCompletes: true	Verify the processing indicator resolves to a terminal state
   resultDownloadable: true	Verify a download button or link is available
   errorExpected: true	Verify an error message is displayed and the app remains functional
   expectedStatus: "X"	Verify the status shows "X"

   这些 Verify 步骤将作为常规演练的一部分添加到工作流输出中。记录前，请通过检查快照与用户逐项确认。

4. 如果用户选择“skip”或“none”，则按常规方式编写 Upload 步骤，不集成测试数据。

---

便于自动化的指南

工作流旨在转换为 Playwright E2E 测试。请遵循以下指南，使转换过程更加顺畅。

定位器描述

在工作流步骤中描述元素时，优先使用能与 Playwright 推荐的定位器策略直接对应的描述：

定位器策略	工作流描述	Playwright 对应写法
按角色和名称	点击“Submit”按钮	page.getByRole('button', { name: 'Submit' })
按标签	在电子邮件字段中输入“[email protected]”	page.getByLabel('Email')
按文本	点击“Learn more”链接	page.getByText('Learn more')
按占位符	在搜索框中输入“Search...”	page.getByPlaceholder('Search...')
按测试 ID	点击删除按钮（data-testid="delete-btn"）	page.getByTestId('delete-btn')
按标题	将鼠标悬停在信息图标上（title="More information"）	page.getByTitle('More information')

定位器优先顺序

编写步骤时，优先按以下顺序描述定位器（与 Playwright 的建议一致）：

1. 基于角色（按钮、链接、标题等）
2. 基于标签（表单字段）
3. 基于文本（可见文本内容）
4. 基于占位符（输入框占位符）
5. 基于测试 ID（data-testid 属性）
6. 基于 CSS/XPath（最后手段，尽可能避免）

无法自动化的步骤

某些步骤无法通过 Playwright 自动化。请使用 [MANUAL] 标记：

4. [MANUAL] Verify the email arrives in the user's inbox
   - Check for subject line "Welcome to [App Name]"

7. [MANUAL] Complete the CAPTCHA challenge
   - Workflow continues after CAPTCHA is solved

已知限制

限制	描述	解决方法
原生文件对话框	Playwright 无法与操作系统级文件选择器交互	使用 page.setInputFiles()，而不是点击文件输入框
原生打印对话框	无法自动化浏览器打印预览	跳过或模拟打印功能
浏览器扩展	Playwright 不支持浏览器扩展	手动测试依赖扩展的功能
多标签页 OAuth	在新标签页中打开的 OAuth 弹出窗口需要特殊处理	使用 context.waitForEvent('page') 模式
剪贴板访问	剪贴板 API 需要权限	在浏览器上下文设置中授予权限
下载验证	无法直接验证下载后的文件内容	使用下载事件监听器和文件系统检查
HTTP 基本身份验证	无法通过页面自动化浏览器原生身份验证对话框	在浏览器上下文中使用 httpCredentials
地理位置提示	权限提示会阻止自动化	导航前在上下文选项中设置地理位置

自动化的先决条件

当工作流需要特定设置时，请在前置条件块中记录：

**Preconditions:**
- User is logged in as admin (`[email protected]` / `password123`)
- At least 3 posts exist in the database
- The feature flag "new-editor" is enabled

这些信息对于转换器技能生成合适的 beforeEach 和 beforeAll 块至关重要。

---

Web 平台 UX 反模式

生成工作流时，请留意这些常见的 UX 反模式。如果在探索过程中发现任何反模式，请在工作流文档中标记，并编写具体的测试步骤，以验证应用是否能正确处理这些情况。

导航反模式

反模式	重要性	验证步骤
仅支持手势导航	桌面用户无法使用滑动手势	验证所有导航都可通过点击或键盘操作
破坏后退按钮功能	用户期望浏览器后退功能正常工作	向前导航，点击后退，验证是否加载了上一页
有状态视图没有 URL	用户无法为特定状态添加书签或分享	验证筛选器、标签页和模态框都有对应的 URL
仅使用哈希路由	会破坏 SSR 和部分爬虫的正常工作	检查路由是否使用了恰当的路径段
重定向循环	登录 -> 重定向 -> 登录循环	尝试访问受保护的路由，验证是否只发生一次重定向

交互反模式

反模式	重要性	验证步骤
缺少悬停状态	桌面用户期望悬停时有视觉反馈	将鼠标悬停在交互元素上，验证光标和样式是否发生变化
缺少焦点指示器	键盘用户无法看清当前焦点所在位置	按 Tab 键浏览页面，验证每个元素上是否都显示可见的焦点环
点击目标过小	在大屏幕上使用触控板时容易出现定位问题	验证按钮和链接是否有足够大的可点击区域（最小为 24x24px）
下拉刷新模式	桌面浏览器不支持下拉手势	验证是否可通过按钮或键盘操作刷新
需要双击	这是 Web 中不符合预期的交互模式	验证所有操作是否都能通过单击响应
覆盖上下文菜单	用户期望右键单击时显示原生行为	在页面上右键单击，验证是否显示原生上下文菜单

视觉反模式

反模式	重要性	验证步骤
桌面端全屏模态框	浪费大视口上的屏幕空间	确认模态框尺寸适合桌面视口
没有响应式断点	内容可能溢出或显示不全	在常见断点进行测试：1024px、1280px、1440px、1920px
固定移动端宽度布局	桌面用户期望流式或最大宽度布局	确认布局会根据视口宽度调整
大屏幕上的小号文本	桌面观看距离下可读性较差	确认正文文本至少为 16px
内容区域出现水平滚动	在桌面端出乎意料（表格/代码除外）	确认在 1280px 及以上宽度时不会出现水平滚动条

组件反模式

反模式	重要性	验证步骤
原生移动端选择器	日期/时间选择器针对触控设计，而非鼠标	确认日期/时间输入使用适合桌面端的选择器
用操作面板代替下拉菜单	这种移动端模式在桌面端显得不协调	确认选择组件使用标准下拉菜单/选择框
iOS 风格切换开关	可能会让习惯使用复选框的桌面用户感到困惑	确认切换行为符合桌面端惯例
底部面板	这种移动端模式会浪费桌面空间	确认在宽视口上，面板和抽屉置于侧边
浮动操作按钮（FAB）	这是移动端 Material Design 模式，在桌面端并不常见	确认主要操作位于标准工具栏/页眉位置

无障碍反模式

反模式	重要性	验证步骤
不支持键盘导航	许多桌面用户依赖键盘操作	使用 Tab 键遍历所有交互元素，并确认顺序合理
缺少 ARIA 标签	屏幕阅读器无法识别元素	检查交互元素是否带有 aria-label 或 aria-labelledby
仅用颜色表示状态	色盲用户无法区分状态	确认状态除颜色外还使用文本/图标表示
自动播放媒体	对桌面用户来说出乎意料且会造成干扰	确认未经用户交互不会播放媒体
模态框中的焦点陷阱	打开模态框时，Tab 键应在其中循环切换	打开模态框并用 Tab 键遍历所有元素，确认焦点始终留在框内
缺少跳过导航	键盘用户必须遍历整个导航栏	确认存在并且可正常使用“跳至主要内容”链接

UX 验证步骤模板

在探索过程中检测到反模式时，添加专门的 UX 验证工作流：

## Workflow [N]: UX Pattern Compliance



> Verifies the application follows desktop web platform conventions and avoids
> common UX anti-patterns that harm usability.

**Steps:**

1. Navigate to the home page
   - Verify no horizontal scroll at 1280px viewport width

2. Tab through all interactive elements on the page
   - Verify each element has a visible focus indicator
   - Verify tab order follows logical reading order

3. Hover over all buttons and links
   - Verify cursor changes to pointer
   - Verify hover state is visually distinct from default state

4. Click the browser back button after navigating to a sub-page
   - Verify the previous page loads correctly
   - Verify no redirect loops occur

5. [Continue based on specific anti-patterns found...]

---

处理更新

用户选择“更新”模式（修改现有工作流）时，请遵循以下规则，在确保覆盖内容保持最新的同时尽量减少干扰。

更新现有工作流的规则

1. 保留可用的工作流 -- 如果现有工作流仍然有效（路由存在、组件匹配、步骤正确），则保持不变。不要为了风格一致而重写可用的工作流。

2. 标记已弃用的工作流 -- 如果工作流引用的路由或组件已不存在，不要删除它。请改为添加弃用标记：

## Workflow 7: Legacy Export Feature






> **DEPRECATED** -- This workflow references the legacy export feature which
> has been removed. Keeping for reference until confirmed safe to delete.

3. 添加新工作流 -- 将新工作流追加到相应章节（核心、功能或边缘情况）。按顺序从最后一个现有工作流之后开始编号。

4. 版本说明 -- 在文件顶部添加版本历史章节：

## Version History

| Date | Action | Details |
|------|--------|---------|
| 2025-01-20 | Updated | Added workflows 26-28 for new dashboard features |
| 2025-01-15 | Updated | Deprecated workflow 7 (export feature removed) |
| 2025-01-01 | Created | Initial generation: 25 workflows |

5. 重新验证现有工作流 -- 在探索过程中，根据当前代码库交叉核对现有工作流步骤。标记引用了已更改元素或路由的步骤：

3. Click the "Export CSV" button
   - **[CHANGED]** Button label is now "Download CSV" (updated in v2.2)
   - Verify download begins within 3 seconds

6. 保留工作流编号 -- 绝不重新编号现有工作流。如果工作流 7 已弃用，并新增工作流 28，则保留编号间隔。这样可确保对“工作流 7”的外部引用仍然有效。

更新摘要

更新操作后，提供变更摘要：

Desktop workflow update complete.

Changes:
- Workflows preserved (unchanged): 20
- Workflows updated (steps modified): 3
- Workflows deprecated: 1
- Workflows added (new): 3
- Total workflows: 27 (1 deprecated)

Changed workflows:
- Workflow 4: Updated step 3 (button label changed)
- Workflow 12: Updated step 1 (route changed from /settings to /preferences)
- Workflow 19: Updated steps 5-7 (new confirmation dialog added)

Deprecated workflows:
- Workflow 7: Legacy Export Feature (export removed in v2.3)

New workflows:
- Workflow 26: Dashboard Widget Customization
- Workflow 27: Real-Time Notification Center
- Workflow 28: Bulk Action on List View