screenshots

截取受近期更改影响的组件截图，可从运行中的应用（使用 e2e 身份验证）或 Storybook 截取。

用法：

• /screenshots — 自动检测已更改的组件并截取截图
• /screenshots navigate to /settings, open the "Profile" tab, screenshot the form — 按照自定义说明截取截图

说明：

1. 检查是否有自定义说明：

   • 如果提供了非空的 $ARGUMENTS，运行步骤 2（前置条件检查），然后跳转到 步骤 6（自定义说明模式）
   • 如果 $ARGUMENTS 为空，则继续执行以下自动检测流程（步骤 2–5，然后是步骤 7–10）

2. 检查前置条件：

   • 运行 playwright-cli --help，确认 Playwright CLI 可用
   • 如果命令失败（未找到或报错），显示以下消息并停止：

     ## 缺少前置条件：Playwright CLI
     
     未安装 Playwright CLI。此技能需要使用 Playwright CLI 截取截图。
     
     使用以下命令安装：npm install -g @playwright/cli@latest
     

3. 确定基准分支：

   • 检查当前目录中是否存在 .agent 文件。如果其中包含 baseBranch=<value> 行，则将该值用作基准分支
   • 如果没有 .agent 文件或没有 baseBranch 键，则默认为 main

4. 识别已更改的组件：

   • 运行 git diff --name-only $(git merge-base HEAD <base-branch>)..HEAD，查找与基准分支相比近期更改的文件
   • 筛选组件文件：扩展名为 .tsx、.jsx、.vue、.svelte 的文件
   • 排除测试文件（*.test.*、*.spec.*）、story 文件（*.stories.*）和类型定义文件（*.d.ts）
   • 如果更改中没有组件文件，告知开发者并停止
   • 向开发者列出已更改的组件

5. 询问开发者：应用还是 Storybook？

   • 使用 AskUserQuestion，逐个组件询问（组件很多时可批量询问）：
     • Storybook — 组件有 stories，从 Storybook 截取截图
     • 应用 — 组件在运行中的应用里可见
     • 跳过 — 不截取此组件的截图

6. 自定义说明模式（提供了 $ARGUMENTS 时）：

   此模式允许开发者完全控制截图内容。开发者在 $ARGUMENTS 中说明要访问哪些页面、要执行哪些操作（点击按钮、填写表单、打开菜单等），以及何时截取截图。截图通过编写临时 e2e 测试、运行测试，然后还原测试文件来获取。

   a. 了解 e2e 测试配置：

   • 在代码库中搜索现有的 e2e/Playwright 测试文件（例如 *.e2e.ts、*.e2e-spec.ts、e2e/、tests/ 下的文件，或 Playwright 测试目录中的文件）
   • 找出测试运行器配置（例如 playwright.config.ts），了解基础 URL、测试目录和任何全局设置（身份验证、存储状态等）
   • 了解现有测试如何处理身份验证，并沿用相同方式（例如 storageState、全局设置、beforeEach 登录） b. 编写临时端到端测试文件：
   • 按照现有约定，在项目的端到端测试目录中新建测试文件（例如，e2e/tmp-screenshots.e2e.ts）
   • 测试应当：
     • 使用项目现有的身份验证模式处理身份验证
     • 导航到 $ARGUMENTS 中指定的页面／路由
     • 执行所有要求的操作（点击元素、填写输入框、选择选项、悬停、滚动等）
     • 在每次截图前等待动画／过渡效果完成——使用 page.waitForTimeout()，或等待特定的 CSS 状态（例如，等待元素的 opacity: 1、等待过渡类被移除，或等待元素稳定）。对于模态框和覆盖层，确保打开动画完全结束后再截图。
     • 使用 page.screenshot({ path: '.tmp/<descriptive-name>.png' }) 截图；若需定向截取，则使用 element.screenshot()
     • 根据页面／操作上下文使用描述性文件名（例如，.tmp/settings-profile-tab.png、.tmp/modal-confirm-delete.png）
   • 如果 .tmp/ 目录不存在，则创建该目录：mkdir -p .tmp

   c. 运行临时测试：

   • 使用项目的 Playwright 测试命令（例如，playwright-cli test e2e/tmp-screenshots.e2e.ts）仅运行临时测试文件
   • 如果测试失败，显示错误，尝试修复测试并重新运行。如果经过合理尝试后仍然失败，则显示错误并继续清理。

   d. 查看结果：

   • 使用 Read 工具查看生成的每张截图，并展示给开发者

   e. 清理——还原临时测试文件：

   • 如果修改的是现有文件，则运行 git restore <test-file-path> 还原临时测试文件
   • 如果是新建的测试文件，则运行 rm <test-file-path> 删除该文件
   • 使用 git status 确认没有遗留临时测试改动

   f. 总结：

   • 拍摄完所有截图并完成清理后，列出保存的文件，并说明每张截图展示的内容
   • 然后停止（不要继续执行自动检测步骤）

7. 对于使用 Storybook 路径的组件：

   a. 查找对应的 story 文件：

   • 在组件旁边或同一目录中查找 .stories.tsx、.stories.jsx、.stories.ts 或 .stories.js 文件
   • 如果未找到 story 文件，告知开发者并跳过该组件

   b. 提取 story 元数据：

   • 读取 story 文件
   • 从默认导出中提取 meta.title（或 default.title）
   • 提取所有具名导出（即 story 名称），排除默认导出和任何非 story 导出（例如 args、argTypes 等）

   c. 构造 story URL：

   • 将标题转换为 kebab-case：把空格、/ 和特殊字符替换为 -，并将所有字母转为小写
   • 将每个 story 名称转换为 kebab-case
   • 构造 story ID：<title-kebab-case>--<story-name-kebab-case>
   • 构造 iframe URL：http://localhost:6006/iframe.html?id=<story-id>&viewMode=story

   d. 确认 Storybook 正在运行：

   • 尝试访问 http://localhost:6006（例如，curl -s -o /dev/null -w "%{http_code}" http://localhost:6006）
   • 如果 Storybook 未运行（连接被拒绝或响应码非 200），请开发者启动它并等待确认

   e. 截图：

   • 如果 .tmp/ 目录不存在，则创建该目录：mkdir -p .tmp
   • 对每个 story 运行：

     playwright-cli screenshot --browser chromium --wait-for-timeout 2000 "<iframe-URL>" .tmp/<component-name>-<story-name>.png
     

   • 如果有多个 story，则并行运行截图命令（在 Bash 中使用 & 和 wait）
   • 告知开发者 --wait-for-timeout 2000 是默认值；对于较复杂的组件，他们可以要求增加等待时间 f. 查看结果：
   • 使用 Read 工具查看生成的每张截图，并展示给开发者

8. 对于使用 App 路径的组件：

   通过编写临时 e2e 测试、运行测试，然后还原更改，来截取运行中应用的截图。

   a. 询问开发者要导航到哪个 URL/路由：

   • 使用 AskUserQuestion 获取组件在运行中的应用里可见的 URL 或路由
   • 同时询问是否需要执行任何操作才能到达所需状态（例如，“点击 Edit 按钮”、“打开下拉菜单”）

   b. 了解 e2e 测试设置：

   • 搜索现有的 e2e/Playwright 测试文件和配置（与步骤 6a 相同）
   • 注意现有测试如何处理身份验证，并沿用相同的方法

   c. 编写临时 e2e 测试文件：

   • 在项目的 e2e 测试目录中创建新的测试文件（例如，e2e/tmp-screenshots.e2e.ts）
   • 测试应当：
     • 使用项目现有的身份验证模式处理身份验证
     • 导航到指定的 URL/路由
     • 执行到达所需组件状态所需的操作
     • 等待动画/过渡效果完成后再截图——使用 page.waitForTimeout()，或等待特定的 CSS 状态（例如，opacity: 1、移除过渡类、元素稳定）。对于模态框、下拉菜单和覆盖层，请确保其打开动画已完全结束。
     • 使用 page.screenshot({ path: '.tmp/<component-name>-app.png' }) 截图，或使用 element.screenshot() 截取指定元素
   • 如果 .tmp/ 目录不存在，则创建该目录：mkdir -p .tmp

   d. 运行临时测试：

   • 仅运行临时测试文件（例如，playwright-cli test e2e/tmp-screenshots.e2e.ts）
   • 如果测试失败，请展示错误，尝试修复，然后重新运行

   e. 查看结果：

   • 使用 Read 工具查看生成的每张截图，并展示给开发者

   f. 清理——还原临时测试文件：

   • 如果该文件是新建的，请运行 rm <test-file-path>
   • 使用 git status 验证没有遗留临时测试更改

9. 摘要：

   • 截图全部完成后，提供摘要：

     ## 截图完成
     
     保存到 `.tmp/`：
     - .tmp/ComponentA-Default.png（Storybook）
     - .tmp/ComponentA-WithProps.png（Storybook）
     - .tmp/ComponentB-app.png（应用 - /dashboard）
     
     截图保存在项目的 .tmp/ 目录中。
     

10. 处理边缘情况：

• 如果截图命令失败，请展示错误，并继续处理其余截图
• 如果无法创建 .tmp/ 目录，请展示错误并停止
• 如果 story 文件没有具名导出（没有 stories），则跳过该文件并告知开发者
• 如果开发者跳过所有组件，请告知他们并停止