@pzy560117/codex-harness 0.1.4 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/ai-ui-prompts/SKILL.md

@@ -0,0 +1,350 @@
+---
+name: ai-ui-prompts
+description: AI 生图提示词模板
+---
+
+# AI 生图提示词模板
+
+## 标准工作流
+
+AI 生图不能直接替代前端规格。UI-facing feature 必须执行"早期方向图 + 最终规格图"两轮生图：
+
+1. 完成 `docs/product/prd-lite.md` 初稿、`docs/product/page-inventory.md` 初稿和轻量 `docs/product/requirement-interface-matrix.md`，确保每条 P0/P1 需求至少映射到页面、区域、字段、操作和状态。
+2. 完成 `docs/design/page-rules-draft.md`，写清页面类型、信息密度、基础视觉方向、关键组件、状态要求和禁止事项。
+3. 使用 `docs/design/early-ai-image-brief.md` 生成第一轮方向图，图片保存到 `artifacts/ai-images/early/`。
+4. 使用 `docs/design/early-ui-review.md` 评审方向图，并把结论反哺到 PRD、页面清单、状态矩阵和需求-界面追溯矩阵。
+5. 完成 `docs/product/requirement-interface-matrix.md`、`docs/product/difficulty-research.md` 和测试追溯文档，确保每条 P0/P1 需求都映射到页面、状态、字段、操作、接口、验收、测试数据和证据。
+6. 完成 `docs/design/design-brief.md`，写清 CSS / token 要求：颜色、字体、字号、间距、圆角、阴影、状态色、信息密度和响应式。
+7. 使用 `docs/design/ai-image-brief.md` 生成或编辑第二轮多状态规格图。
+8. 使用 `docs/design/ui-image-review.md` 评审图片。未通过时继续编辑图片，不进入代码。
+9. 使用 `docs/design/image-to-frontend-spec.md` 把通过的图片转换为前端规格，再交给 Codex 实现代码。
+
+## Prompt Enrichment Gate
+
+生成图片前，提示词不能只包含页面名称和一句风格描述。每个页面 prompt 必须先合并以下输入：
+
+- `docs/design/frontend-skill-intake.md`：前端 skills 约束和 `prompt_enrichment_matrix`。
+- `docs/product/requirement-interface-matrix.md`：需求、页面、字段、操作、状态映射。
+- `docs/design/page-rules-draft.md` 或 `docs/design/design-brief.md`：信息密度、组件、token 和禁止事项。
+- `docs/product/page-inventory.md`：页面编号、平台、路径和优先级。
+
+每个页面 prompt 至少包含这些段落：
+
+1. 画布与设备：平台、尺寸、页面编号、页面类型。
+2. 产品语境：目标用户、核心任务、页面在主流程中的位置。
+3. 信息架构：一级/二级区域、视觉焦点、阅读顺序。
+4. 组件清单：导航、卡片、表格、筛选、表单、弹窗、抽屉、底部栏。
+5. 字段与数据：必须出现的字段、格式、状态标签、金额/库存/时间格式。
+6. 交互与反馈：主按钮、次按钮、禁用态、确认态、成功/失败反馈。
+7. 状态覆盖：正常、空、加载、错误、权限、业务异常。
+8. 视觉原则：来自 `frontend-skill-intake.md` 的密度、层级、留白、颜色、字体、圆角、阴影。
+9. 响应式约束：移动端安全区、桌面栅格、固定比例和不可重排区域。
+10. 图标与视觉资产：图标风格、按钮图标、禁止自造低质符号。
+11. 中文文案：必须照抄的短中文文案。
+12. 禁止项：不得新增需求外功能、不得乱码、不得营销化后台、不得省略 P0 状态。
+
+如果某个页面缺少字段、状态或组件约束，先回补 `frontend-skill-intake.md` 或需求矩阵，不直接生图。
+
+## Codex Responses API 生图方式
+
+当当前 Codex 配置使用自定义 `wire_api = "responses"` provider，而内置 `image_gen` 工具不可见时，优先使用当前 Codex provider 的 `/v1/responses` + `image_generation` 工具链路，不要直接调用官方 Images API。
+
+已验证的约束：
+
+- 认证优先读取 `C:\Users\<user>\.codex\auth.json` 中的 `OPENAI_API_KEY`，只在进程环境变量中使用，禁止打印或写入仓库。
+- endpoint 使用当前 Codex provider 的 `base_url` 拼接 `/v1/responses`。
+- 不要把 `gpt-image-2` 作为顶层 `model` 直接请求；在 ChatGPT OAuth/Codex 账号模式下可能返回 `The 'gpt-image-2' model is not supported when using Codex with a ChatGPT account.`。
+- 顶层 `model` 使用当前 Codex 文本模型，例如 `gpt-5.5`；图片通过 `tools: [{ type: "image_generation" }]` 触发。
+- `instructions` 必填。
+- `input` 必须是消息数组，不是字符串。
+- 成功响应中的图片在 `output[]` 里查找 `type == "image_generation_call"`，读取其 `result` 字段并按 base64 解码为 PNG。
+- 响应里的 `status` 可能仍显示 `generating`，只要顶层响应 `status == "completed"` 且 `result` 有值，就可以落盘并进入人工/视觉评审。
+- 第一轮方向图保存到 `artifacts/ai-images/early/`；测试图或临时验证图保存到 `output/imagegen/`，不要混入正式评审目录。
+
+PowerShell 请求骨架：
+
+```powershell
+$configBaseUrl = "http://your-codex-provider"
+$auth = Get-Content "$env:USERPROFILE\.codex\auth.json" -Raw | ConvertFrom-Json
+$headers = @{
+  Authorization = "Bearer $($auth.OPENAI_API_KEY)"
+  "Content-Type" = "application/json"
+}
+$payload = [ordered]@{
+  model = "gpt-5.5"
+  instructions = "You are an image generation assistant. Use the image_generation tool when the user asks for an image."
+  input = @(@{
+    role = "user"
+    content = @(@{
+      type = "input_text"
+      text = "<把 early-ai-image-brief 或单页生图提示词放在这里>"
+    })
+  })
+  tools = @(@{
+    type = "image_generation"
+    size = "1024x1024"
+    quality = "low"
+  })
+}
+$res = Invoke-RestMethod `
+  -Uri "$configBaseUrl/v1/responses" `
+  -Method Post `
+  -Headers $headers `
+  -Body ($payload | ConvertTo-Json -Depth 12) `
+  -TimeoutSec 360
+$img = $res.output | Where-Object { $_.type -eq "image_generation_call" } | Select-Object -First 1
+[IO.File]::WriteAllBytes("artifacts\ai-images\early\mobile-M-PAGE-001-home.png", [Convert]::FromBase64String($img.result))
+```
+
+## Responses 并发生成规则
+
+早期方向图和第二轮规格图应按页面拆分为多个独立 prompt，并发生成，而不是把所有页面塞进一个超长 prompt。
+
+并发生成要求：
+
+- 先创建 `docs/design/ai-image-jobs.jsonl`，一行一个页面任务，字段包括 `id`、`platform`、`page_id`、`title`、`prompt`、`out`、`priority`。
+- `prompt` 必须通过 Prompt Enrichment Gate，不能是页面名短句。
+- 默认并发数为 3；图片服务稳定且无 429 时可提升到 5。
+- 每个任务最多重试 2 次；失败要记录错误，不得用其它页面图片顶替。
+- 输出文件必须使用稳定语义文件名，例如 `mobile-M-PAGE-003-product-detail.png`。
+- 并发完成后生成 `artifacts/ai-images/early/manifest.md`，记录每张图的 prompt source、输出路径、响应 id、状态和评审结论。
+
+PowerShell 7 并发骨架：
+
+```powershell
+$auth = Get-Content "$env:USERPROFILE\.codex\auth.json" -Raw | ConvertFrom-Json
+$baseUrl = "http://your-codex-provider"
+$headers = @{
+  Authorization = "Bearer $($auth.OPENAI_API_KEY)"
+  "Content-Type" = "application/json"
+}
+$jobs = Get-Content docs\design\ai-image-jobs.jsonl | ForEach-Object { $_ | ConvertFrom-Json }
+
+$jobs | ForEach-Object -Parallel {
+  $job = $_
+  $headers = $using:headers
+  $baseUrl = $using:baseUrl
+  $payload = [ordered]@{
+    model = "gpt-5.5"
+    instructions = "You generate UI direction images. Use image_generation. Preserve the requested Chinese UI copy exactly."
+    input = @(@{
+      role = "user"
+      content = @(@{ type = "input_text"; text = $job.prompt })
+    })
+    tools = @(@{ type = "image_generation"; size = "1024x1024"; quality = "medium" })
+  }
+  $res = Invoke-RestMethod -Uri "$baseUrl/v1/responses" -Method Post -Headers $headers -Body ($payload | ConvertTo-Json -Depth 12) -TimeoutSec 360
+  $img = $res.output | Where-Object { $_.type -eq "image_generation_call" } | Select-Object -First 1
+  if (-not $img.result) { throw "No image result for $($job.id)" }
+  New-Item -ItemType Directory -Force -Path (Split-Path $job.out) | Out-Null
+  [IO.File]::WriteAllBytes($job.out, [Convert]::FromBase64String($img.result))
+  [PSCustomObject]@{ id = $job.id; out = $job.out; response_id = $res.id; status = $res.status }
+} -ThrottleLimit 3
+```
+
+## 早期方向图提示词结构
+
+```
+生成"[产品/功能名称]"的第一轮 UI 方向图
+
+目标：
+- 用于在完整 PRD 和测试矩阵定稿前校准页面方向、信息架构和信息密度
+- 发现需求、字段、状态、导航路径和后台运营视图的问题
+
+输入真相源：
+- `docs/product/prd-lite.md` 初稿
+- `docs/product/page-inventory.md` 初稿
+- 轻量 `docs/product/requirement-interface-matrix.md`
+- `docs/design/page-rules-draft.md`
+- `docs/design/frontend-skill-intake.md`
+
+设备与页面：
+- 移动端：[列出 P0 移动端页面]
+- 桌面后台：[列出 P0 后台页面]
+
+语言与文字质量：
+- 默认使用简体中文生成所有可见 UI 文案
+- 必须照抄关键中文文案清单，不要自由编造小字
+- 不要出现乱码、伪中文、拼音占位、Lorem ipsum 或随机英文字母
+- 小字号说明文字必须短句化，避免大段不可读文字
+
+设计方向：
+- 信息密度：[低/中/高，按产品场景说明]
+- 视觉气质：[品牌/行业方向]
+- 关键组件：[底部导航、商品卡、表格、筛选、详情抽屉等]
+
+必须体现：
+- 每条 P0/P1 需求对应的页面入口
+- 正常态、空态、错误态、权限态或关键业务异常态的位置
+- 主要字段、主要按钮、主要状态标签和关键操作反馈
+
+禁止：
+- 不要新增 Product Spec 没有的功能
+- 不要把营销装饰放在运营后台主区域
+- 不要省略 P0 页面
+- 不要生成乱码、伪中文、随机字符或不可读关键文案
+```
+
+## 默认语言与文字质量
+
+除非用户明确指定其他语言，AI 生图提示词必须默认要求**简体中文界面文案**。
+
+写入 `docs/design/early-ai-image-brief.md` 和 `docs/design/ai-image-brief.md` 时必须包含以下约束：
+
+- 所有可见 UI 文案、标题、按钮、标签、表格列名、状态、错误提示默认使用简体中文。
+- 英文只允许用于必要品牌名、产品名、专有名词、技术缩写或真实 API/代码字段；业务界面文案不要中英混排。
+- 禁止乱码、伪中文、无意义拉丁字母、拼音占位、Lorem ipsum、随机字符、错别字密集的小字。
+- 对容易生成乱码的小字号长文本，改成短中文词组或结构化数据，不要求图像模型渲染大段正文。
+- 提示词必须给出关键中文文案清单，让图像模型照抄，而不是自由编造。
+
+`docs/design/early-ui-review.md` 和 `docs/design/ui-image-review.md` 必须检查文字质量：只要出现明显乱码、假字、伪中文、错误中英混排或不可读关键文案，图片不得进入下一阶段，必须重新编辑图片提示词并再生成。
+
+## 基础提示词结构
+
+```
+生成"[页面名称]"的 UI 设计图
+
+页面类型：[列表页/详情页/表单页/仪表盘/登录页]
+设计风格：[Ant Design/Element Plus/Material Design]
+设备类型：[桌面端/移动端]（宽度）
+输入真相源：[PRD / requirement-interface-matrix / early-ui-review / design-brief / design-tokens / component-map / screen-states]
+
+语言与文字质量：
+- 默认使用简体中文生成所有可见 UI 文案
+- 必须照抄关键中文文案清单，不要自由编造小字
+- 不要出现乱码、伪中文、拼音占位、Lorem ipsum 或随机英文字母
+- 小字号说明文字必须短句化，避免大段不可读文字
+
+必须生成以下状态的设计图：
+1. 正常态（有数据）
+2. 空态（无数据）
+3. 加载态
+4. [其他需要的状态]
+
+页面元素：
+- 顶部区域：[描述]
+- 内容区域：[描述]
+- 底部区域：[描述]
+
+边界场景：
+- 文本超长：[处理方式]
+- 数据超多：[处理方式]
+
+CSS / Token 要求：
+- 颜色：[来自 design-tokens]
+- 字体/字号：[来自 design-brief]
+- 间距/圆角/阴影：[来自 design-tokens]
+- 表格/表单密度：[来自 design-brief]
+
+交互说明：
+- [关键交互]
+
+禁止：
+- 不要添加需求矩阵中没有的功能
+- 不要省略 required state
+- 不要使用与 Design Tokens 冲突的样式
+- 不要生成乱码、伪中文、随机字符或不可读关键文案
+```
+
+## 图片编辑提示词结构
+
+```
+基于上一版 UI 图继续编辑，不改变已通过评审的信息架构和组件结构。
+
+需要修复：
+- [来自 ui-image-review.md 的失败项]
+- 如有乱码/伪中文/不可读关键文案，逐项替换为明确中文短文案
+
+保持不变：
+- [已通过的布局、组件、颜色、状态]
+
+补充状态：
+- [需要补充的页面状态]
+
+禁止：
+- 不要新增 Product Spec 没有的功能
+- 不要改变已通过评审的需求映射
+- 不要保留任何乱码、伪中文、拼音占位或随机字符
+```
+
+## 列表页示例
+
+```
+生成"订单列表页"的 UI 设计图
+
+页面类型：列表页
+设计风格：Ant Design 5.x 风格，简洁专业
+设备类型：桌面端（1440px宽度）
+
+必须生成以下状态的设计图：
+1. 正常态：显示10条订单数据
+2. 空态：无订单时的引导界面
+3. 加载态：骨架屏效果
+
+页面元素：
+- 顶部：面包屑、页面标题、"新建订单"按钮
+- 筛选区：状态下拉、时间范围、搜索框
+- 表格列：订单号、客户名、金额、状态、时间、操作
+- 底部：分页器
+
+边界场景：
+- 订单号超长：最多20字符+省略号
+- 客户名超长：最多10字+省略号
+
+状态标签颜色：
+- 草稿：灰色
+- 待审核：橙色
+- 已通过：绿色
+- 已拒绝：红色
+```
+
+## 表单页示例
+
+```
+生成"新建订单"表单页的 UI 设计图
+
+页面类型：表单页
+设计风格：Ant Design 5.x 风格
+设备类型：桌面端（1440px宽度）
+
+必须生成以下状态的设计图：
+1. 初始态：空表单，显示必填项标记
+2. 校验错误态：显示字段错误提示
+3. 提交中态：提交按钮显示loading
+
+页面元素：
+- 顶部：面包屑、页面标题
+- 表单区域：基本信息卡片、订单信息卡片
+- 底部操作栏：取消、保存草稿、提交
+
+表单规则：
+- 必填字段标记红色星号
+- 错误提示显示在字段下方
+```
+
+## 移动端示例
+
+```
+生成"订单列表"移动端页面的 UI 设计图
+
+页面类型：列表页
+设计风格：iOS 风格
+设备类型：移动端（375px宽度）
+
+必须生成以下状态的设计图：
+1. 正常态：订单卡片列表
+2. 空态：无订单引导
+3. 下拉刷新态
+4. 上拉加载态
+
+页面元素：
+- 顶部导航栏：返回、标题、筛选图标
+- 标签栏：全部/待付款/待发货/已完成
+- 订单卡片：店铺名+状态、商品信息、金额、操作按钮
+
+交互说明：
+- 下拉刷新
+- 上拉加载更多
+- 左滑显示删除
+```
+

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/allure-report/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: Allure Report
+description: 生成和查看 Allure 测试报告 - 从指定的测试运行目录生成准确的报告
+---
+
+# Allure Report - Allure 测试报告生成与查看
+
+## 概述
+
+本技能提供了生成和查看 Allure 测试报告的标准化方法。Allure 是一个灵活的多语言测试报告工具，可以生成美观的、交互式的测试报告，包含详细的测试历史、图表、时间线等功能。
+
+## 何时使用此技能
+
+- 用户想要查看特定测试运行的 Allure 报告
+- 需要从 `midscene_run` 目录中的某次运行生成报告
+- 需要确保报告数据与特定运行目录匹配（避免使用全局混合数据）
+- 需要以可视化方式分析测试结果
+
+## 关键原则
+
+> [!IMPORTANT]
+> **数据源准确性**：必须从指定的运行目录的 `allure-results` 生成报告，而不是使用全局目录。这样可以确保报告数据与具体的测试运行一一对应。
+
+## 使用步骤
+
+### 步骤 1: 识别测试运行目录
+
+测试运行目录位于 `midscene_run/<timestamp>-<id>/` 下，例如：
+```
+midscene_run/2026-01-23_14-13-21-8ufgvd3i/
+├── allure-results/    # Allure 原始结果文件
+├── report/            # Midscene HTML 报告
+├── log/              # 日志文件
+└── screenshots/      # 截图文件
+```
+
+### 步骤 2: 生成并查看报告（推荐方式）
+
+使用 `allure serve` 命令直接从指定目录启动服务：
+
+```powershell
+npx allure serve midscene_run/<运行目录>/allure-results
+```
+
+**示例**：
+```powershell
+npx allure serve midscene_run/2026-01-23_14-13-21-8ufgvd3i/allure-results
+```
+
+**优点**：
+- ✅ 自动生成临时报告并打开浏览器
+- ✅ 数据源准确，不会混入其他测试数据
+- ✅ 无需手动清理生成的报告文件
+
+### 步骤 3: 生成自定义品牌报告（推荐）
+
+使用自定义品牌脚本生成带有公司 logo 和配色的报告：
+
+```powershell
+.\allure-custom\inject-custom.ps1 -RunDir "<运行目录名称>"
+```
+
+**示例**：
+```powershell
+.\allure-custom\inject-custom.ps1 -RunDir "2026-01-23_14-13-21-8ufgvd3i"
+```
+
+**特性**：
+- ✅ 自动注入自定义蓝色 logo
+- ✅ 应用蓝色主题配色 (#1B8AC8)
+- ✅ 设置中文为默认语言
+- ✅ 自动打开浏览器查看
+
+### 步骤 4: 生成标准静态报告（可选）
+
+如果需要生成标准的 Allure 报告（无自定义品牌）：
+
+```powershell
+npx allure generate midscene_run/<运行目录>/allure-results -o <输出目录> --clean
+```
+
+**示例**：
+```powershell
+# 生成到 allure-report 目录
+npx allure generate midscene_run/2026-01-23_14-13-21-8ufgvd3i/allure-results -o allure-report --clean
+
+# 打开静态报告
+npx allure open allure-report
+```
+
+## 命令对比
+
+| 命令 | 用途 | 数据源 | 适用场景 |
+|------|------|--------|----------|
+| `allure serve <dir>/allure-results` | 临时服务 | 指定目录 | ✅ **推荐**：快速查看单次运行 |
+| `allure generate + allure open` | 静态报告 | 指定目录 | 保存报告供分享 |
+| `allure serve allure-results` | 临时服务 | 全局目录 | ❌ **避免**：可能混入历史数据 |
+
+## 报告内容说明
+
+Allure 报告包含以下主要部分：
+
+### 左侧导航栏
+- 📊 **Overview** (概览): 测试统计、通过率、环境信息
+- 📁 **Suites** (套件): 按测试套件分组的详细结果
+- 📈 **Graphs** (图表): 各种可视化统计图表
+- ⏱️ **Timeline** (时间线): 测试执行的时间分布
+- 🎯 **Behaviors** (行为): 按标签/特性分组
+- 📦 **Packages** (包): 按代码包结构查看
+
+### 验证报告正确性
+
+检查以下指标确保报告数据正确：
+- ✅ 报告标题的日期/时间与运行目录匹配
+- ✅ 测试用例数量与预期一致
+- ✅ 套件名称正确（如 `blocked-features.suite.yaml`）
+
+## 常见问题
+
+**Q: 为什么报告显示的测试数量不对？**
+
+A: 可能使用了全局 `allure-results` 目录，包含了历史测试数据。解决方法：
+```powershell
+# ❌ 错误：使用全局目录
+npx allure serve allure-results
+
+# ✅ 正确：指定运行目录
+npx allure serve midscene_run/2026-01-23_14-13-21-8ufgvd3i/allure-results
+```
+
+**Q: 如何关闭 Allure 服务？**
+
+A: 在命令行中按 `Ctrl+C`，或者：
+```powershell
+# Windows
+taskkill /F /IM node.exe /FI "WINDOWTITLE eq allure*"
+```
+
+**Q: 报告左侧导航栏看不到怎么办？**
+
+A: 
+1. 点击浏览器左上角的汉堡菜单图标（☰）展开侧边栏
+2. 扩大浏览器窗口宽度
+3. 检查是否使用了正确的 `allure serve` 命令
+
+**Q: 可以同时打开多个运行的报告吗？**
+
+A: 可以，使用不同的端口：
+```powershell
+npx allure serve midscene_run/run1/allure-results --port 54617
+npx allure serve midscene_run/run2/allure-results --port 54618
+```
+
+## 配置说明
+
+Allure 配置在 `vitest.e2e.config.ts` 中：
+
+```typescript
+reporters: [
+  'verbose',
+  [
+    'allure-vitest/reporter',
+    {
+      resultsDir: getAllureResultsDir(), // 结果输出目录
+      environmentInfo: {                 // 环境信息
+        os_platform: os.platform(),
+        os_release: os.release(),
+        node_version: process.version,
+      },
+    },
+  ],
+]
+```
+
+## 最佳实践
+
+1. **始终从运行目录启动**：确保报告数据与测试运行对应
+2. **使用 `allure serve`**：快速查看，无需清理临时文件
+3. **验证数据正确性**：检查日期、测试数量、套件名称
+4. **保存重要报告**：使用 `allure generate` 生成静态报告
+
+## 示例脚本
+
+创建便捷的报告查看脚本 `scripts/view-allure.ps1`：
+
+```powershell
+# view-allure.ps1
+param(
+    [Parameter(Mandatory=$true)]
+    [string]$RunDir
+)
+
+$allureResultsPath = "midscene_run/$RunDir/allure-results"
+
+if (-not (Test-Path $allureResultsPath)) {
+    Write-Error "Allure results not found: $allureResultsPath"
+    exit 1
+}
+
+Write-Host "📊 Opening Allure report for: $RunDir" -ForegroundColor Green
+npx allure serve $allureResultsPath
+```
+
+使用示例：
+```powershell
+.\scripts\view-allure.ps1 -RunDir "2026-01-23_14-13-21-8ufgvd3i"
+```
+
+## 相关资源
+
+- [Allure 官方文档](https://docs.qameta.io/allure/)
+- [allure-vitest GitHub](https://github.com/allure-framework/allure-js/tree/master/packages/allure-vitest)
+- 项目配置: `vitest.e2e.config.ts`
+- 运行目录: `midscene_run/`
+
+## 注意事项
+
+> [!WARNING]
+> - 不要使用全局 `allure-results` 目录查看报告，会导致数据混合
+> - 确保 Allure 服务端口未被占用（默认随机分配）
+> - 大型报告可能需要较长加载时间
+
+> [!TIP]
+> - 使用浏览器的开发者工具可以查看报告加载细节
+> - 报告支持多种语言，可在设置中切换
+> - 可以导出报告为 HTML 文件供离线查看
+
+## 更新日志
+
+- **2026-01-23**: 创建初始版本，基于项目实践经验

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/allure-report/examples/usage.md

@@ -0,0 +1,99 @@
+# Allure Report Skill - 使用示例
+
+## 示例 1: 快速查看最近一次测试的报告
+
+```powershell
+# 查看指定运行目录的报告
+npx allure serve midscene_run/2026-01-23_14-13-21-8ufgvd3i/allure-results
+```
+
+## 示例 2: 使用辅助脚本
+
+```powershell
+# 使用提供的脚本
+.\.agent\skills\allure-report\scripts\view-allure.ps1 -RunDir "2026-01-23_14-13-21-8ufgvd3i"
+
+# 指定端口
+.\.agent\skills\allure-report\scripts\view-allure.ps1 -RunDir "2026-01-23_14-13-21-8ufgvd3i" -Port 54617
+```
+
+## 示例 3: 生成静态报告用于分享
+
+```powershell
+# 生成静态报告到 allure-report 目录
+npx allure generate midscene_run/2026-01-23_14-13-21-8ufgvd3i/allure-results -o allure-report --clean
+
+# 打开静态报告
+npx allure open allure-report
+
+# 或直接在浏览器中打开
+start allure-report/index.html
+```
+
+## 示例 4: 对比多次运行结果
+
+```powershell
+# 打开第一次运行（端口 54617）
+npx allure serve midscene_run/2026-01-23_14-13-21-8ufgvd3i/allure-results --port 54617
+
+# 在另一个终端打开第二次运行（端口 54618）
+npx allure serve midscene_run/2026-01-23_15-20-10-xyz123ab/allure-results --port 54618
+```
+
+## 示例 5: 错误排查
+
+```powershell
+# ❌ 错误：使用全局目录（会混入历史数据）
+npx allure serve allure-results
+
+# ✅ 正确：指定运行目录
+npx allure serve midscene_run/2026-01-23_14-13-21-8ufgvd3i/allure-results
+
+# 检查运行目录是否存在
+Test-Path midscene_run/2026-01-23_14-13-21-8ufgvd3i/allure-results
+
+# 列出所有可用的运行目录
+Get-ChildItem -Path midscene_run -Directory | Select-Object Name, CreationTime
+```
+
+## 验证报告正确性
+
+打开报告后，检查：
+
+1. **概览页面**：
+   - 报告生成时间应匹配运行目录时间戳
+   - 测试用例数量应符合预期
+
+2. **套件页面**：
+   - 套件名称正确（如 `blocked-features.suite.yaml`）
+   - 测试用例名称准确
+
+3. **环境信息**：
+   - OS 平台、版本
+   - Node.js 版本
+
+## 常见工作流
+
+### 每日测试报告查看
+
+```powershell
+# 1. 运行测试（会自动生成 allure-results）
+npx vitest --config vitest.e2e.config.ts
+
+# 2. 查看最新的运行目录
+$latestRun = Get-ChildItem -Path midscene_run -Directory | Sort-Object CreationTime -Descending | Select-Object -First 1
+
+# 3. 打开报告
+npx allure serve "midscene_run/$($latestRun.Name)/allure-results"
+```
+
+### 归档重要报告
+
+```powershell
+# 生成静态报告并归档
+$runDir = "2026-01-23_14-13-21-8ufgvd3i"
+npx allure generate "midscene_run/$runDir/allure-results" -o "reports/archive/$runDir" --clean
+
+# 压缩归档
+Compress-Archive -Path "reports/archive/$runDir" -DestinationPath "reports/archive/$runDir.zip"
+```