@pzy560117/codex-harness 0.1.0 → 0.1.2

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/midscene-log-analysis/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: midscene-log-analysis
+description: Midscene 日志分析指南，用于快速定位自动化测试失败原因
+---
+
+# Midscene 日志分析工作流
+
+> 通过分析 Midscene 运行日志（console.log, agent.log, reports），快速定位测试失败的根本原因。
+
+---
+
+## 工作流概览
+
+```mermaid
+graph TD
+    A[定位日志目录] --> B[分析 Console Log]
+    B --> C{是否有明确错误?}
+    C -->|是| D[查看上下文与重试]
+    C -->|否| E[分析 Agent Log]
+    E --> F[查看可视化报告]
+    F --> G[确定根本原因]
+```
+
+---
+
+## 第一步：定位日志目录
+
+Midscene 的运行产物通常存储在 `midscene_run/` 目录下，以时间戳命名。
+
+**目录结构示例**：
+```text
+midscene_run/
+└── 2026-01-19_17-57-35-7a58cpyz/
+    ├── log/
+    │   ├── console.log        # 核心日志，包含流程、警告和错误
+    │   ├── agent.log          # 详细日志，包含 AI 思考、截图尺寸、DOM 信息
+    │   └── ...
+    ├── report/
+    │   └── *.html             # 可视化测试报告
+    └── run-info.json          # 运行元数据
+```
+
+---
+
+## 第二步：分析 Console Log
+
+`console.log` 是排查的第一入口，重点关注以下关键词：
+
+- `[WARN]`, `[ERROR]`
+- `timeout`, `ActivityTimeout`
+- `SmartWait`, `fallback`
+- `aiWaitFor`, `aiQuery`, `aiAssert` 
+
+### 关键检查点
+
+1. **测试流程中断点**：
+   查找最后的日志时间点，确认测试是在哪个步骤停止的。
+   ```text
+   [ActivityTimeout] 活动: aiWaitFor failed @ ...
+   ```
+
+2. **AI 调用超时**：
+   如果出现 `AI 调用超时`，通常意味着页面没有在规定时间内达到预期状态，或者 AI 无法识别目标元素。
+   ```text
+   [WARN ] AI 调用超时 ... error: "AI 调用超时: aiWaitFor 操作在 5000ms 内未完成"
+   ```
+
+3. **SmartWait 重试**：
+   检查 `SmartWait` 是否达到最大重试次数。
+   ```text
+   [ERROR] SmartWait 达到最大重试次数 ... retryCount: 2
+   ```
+
+---
+
+## 第三步：分析 Agent Log (详细调试)
+
+当 `console.log` 信息不足时，查看 `agent.log` 获取更底层的执行细节。
+
+### 关注内容
+
+1. **Action Plan**：
+   AI 实际规划了什么动作？
+   ```text
+   actionPlan {
+     type: 'Tap',
+     param: { locate: { prompt: '登录按钮' } }
+   }
+   ```
+
+2. **Screenshots & Context**：
+   查看日志中是否有截图尺寸调整或 Context 解析的记录，确认页面是否正确加载。
+   ```text
+   [... will get screenshot scale ...]
+   [... computedScreenshotScale 2.74 ...]
+   ```
+
+---
+
+## 第四步：查看可视化报告
+
+打开 `report/*.html` 文件。这是最直观的分析方式。
+
+- **Timeline**：查看时间轴，确认每一步的耗时。
+- **Screenshots**：查看失败时刻的屏幕截图，确认页面实际状态（如加载中、白屏、弹窗遮挡）。
+- **Video**：如果有录制视频，回放操作过程。
+
+---
+
+## 常见故障模式与解决方案
+
+| 现象 | 可能原因 | 解决方案 |
+| :--- | :--- | :--- |
+| **aiWaitFor 超时** | 页面加载慢、描述不准确、元素未出现 | 增加超时时间、优化 prompt 描述、检查网络 |
+| **SmartWait 循环失败** | 页面状态反复跳变、AI 判断不稳定 | 增加 `stabilityCount`、检查页面是否有动态干扰元素 |
+| **元素找不到 (Element Not Found)** | 选择器/Prompt 不准确、弹窗遮挡 | 使用更精确的 prompt、处理前置弹窗 (`PopupHandler`) |
+| **操作无响应** | 按钮可点击但在 Loading 状态、点击位置偏移 | 等待 Loading 消失后再点击、检查点击坐标 |
+
+---
+
+## 示例：Timeout 分析
+
+**日志片段**：
+```text
+[WARN ] [time] [WARN ] AI 调用超时
+  Context: {
+  "callType": "aiWaitFor",
+  "prompt": "判断页面底部是否存在底部导航栏...",
+  "elapsed": 5008
+}
+[ERROR] aiWaitFor 所有重试都失败，共尝试 3 次
+```
+
+**分析**：
+1. `aiWaitFor` 试图寻找“底部导航栏”。
+2. 连续 3 次尝试均超时（每次 5s）。
+3. 这表明在 15s+ 的时间内，底部导航栏一直未出现，或者 AI 无法在当前页面识别出该元素。
+4. **下一步**：查看 Report 截图，确认当时页面是否还在 Loading，或者是否在错误的页面（如依然停留在登录页）。
+
+---
+
+## 相关 Skills
+
+- #midscene-framework - Midscene 框架开发指南
+- #vitest - 测试运行器配置
+- #error-handling - 通用错误处理技巧

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/mobile-e2e-test-case/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: mobile-e2e-test-case
+description: 移动端 APP 纯自然语言 E2E 测试方法论。基于 8 大 AI 共识维度，不再生成任何底层测试脚本，直接利用大语言模型（如通过 Appium 桥接或人工指引 Subagent）执行基于 Markdown 的测试指令。重点强化了移动端容错（异常弹窗）和断言设计策略。
+---
+
+# 移动端纯自然语言 APP E2E 测试指南 (Zero-Code Agentic Testing)
+
+你是一位精通自然语言驱动和 AI 智能操控的资深移动端测试工程师。在自动化技术演进下，本次测试规范**彻底摈弃将测试转化为 Midscene.ts / Appium 脚本**的做法。所有的 E2E 测试全盘依赖 AI 直接解读精细化的 Markdown 文件以执行点击、滑动与观察验证。
+
+## 零代码驱动核心哲学
+
+1. **唯一真相来源**: `test-cases.md` 就是执行文件，无需转化，人类可读且机器可跑。
+2. **语境化状态 (State Memory)**: 把自然语言当内存，比如让 AI 记住上一步创建的手机号，用到下一步的搜索列表中去比对。
+3. **视觉为先的锚点**: 由于没有 selector，必须强化颜色、图标附近文本等极具辨认特征的**视觉参照描述**来帮助判定执行。
+4. **移动特有容错 (Mobile Self-Healing)**: 重点处理移动端的系统权限索取和意料外打断。
+
+---
+
+## 专属适用大模型执行的 8 维度体系
+
+专为机器视觉与页面文本嗅探设计的维度，统一跨端理解：
+
+| # | 维度 | 英文全称 | 标记 | 大模型验证要素 / 移动端盲区防范 |
+|---|------|----------|------|-------------------------------|
+| D1 | 渲染对齐 | Element Render | 🎨 | 所需的核心模块、TabBar、标题文字是否可视。（防止超出屏幕被截断） |
+| D2 | 深度交互 | Interaction | 🖱️ | 滑动 (Swipe)、长按 (Long Press) 以及点击后的立即响应能力。 |
+| D3 | 状态反馈 | State Control | ⏳ | 移动网络下 Loading 的存在、骨架屏，和成功后的 Toast 一瞬而过的提示。 |
+| D4 | 路径回环 | Navigation | 🔀 | 原生 APP 的侧滑返回、点击物理返回键、从底导航栏切换 Tab 的流畅流转。 |
+| D5 | 数据透传 | Data Display | 📊 | 列表数据是否与输入保持一致，以及下拉刷新后的数据保留情况。 |
+| D6 | 系统特权 | System Perm. | 🔒 | **移动特有**：触发相机、相册、通知时的系统鉴权申请，拦截未登录跳转。 |
+| D7 | 表单防腐 | Form Limit | ✅ | 输入法弹起遮挡处理，输入极限边界值或非法空格的兜底显示。 |
+| D8 | 悬浮与打断| Ext. Interrupt | ⚠️ | **移动特有**：开屏广告、协议弹窗、升级弹窗等，强制 AI 主动尝试找到 `[X]` 关掉它。 |
+
+---
+
+## 📄 工作流：精细化指令生产与托管
+
+没有任何转码脚本，我们仅在 `test-cases.md` 上极力优化 prompt 以指引 Agent 或者执行器。
+
+### 第一步：正反向穷举与鲁棒性 Markdown 编写
+
+**输出**：`test-data/e2e/test-cases.md`
+
+用例设计的核心是**全量页面扫雷**，拒绝只测“主流程”的偷懒行为。每个界面所有的输入区、交互图标，甚至返回按钮，都必须至少产出一个【正向顺畅测试】和一个【反向阻断/报错测试】（如长按非法区域、中断撤销、极端脏数据、无权限试探），做到每一个边角场景都不被遗漏。
+
+用例书写的致命错误是覆盖率不足、描述过于模糊（例如：“检查登录是否成功”）以及**用例堆积过于冗长**（超过模型的最大执行耐力）。
+1. **穷举与正反交替**: 为业务操作生成 `[正向通道]` 与 `[反向与异常通道]` 属性标签，在反向用例时必须明确列出产生操作后系统应当反馈的错误红字预期。
+2. **控制切片限制 (Chunking)**: 为了预防执行中断不完整，一份纯自然语言脚本里不能包含超过 3-5 个完整闭环用例，总步长限制在 30 步内，严控给 Agent 施加的记忆负担。长测试单需分拆下发。
+3. **把控执行精确度**：还需要极度强化**视觉锚点**和**记忆传导**的写法。
+
+```markdown
+### TC-M-01: 发布社区动态并验证展示与清理
+
+**【前置状态声明】**: 已经登录 APP 并停留在“首页” Tab 页面。
+**【AI记忆变量】**: 生成一段 10 个字符的随机文本，标记为 `[RandomPostText]`。
+
+| 步序 | 维度 | Agent 动作指令 (包含排错引导) | 预期结果断言 (视觉标准判定) |
+|---|---|---|---|
+| 1 | [D1] 🎨 | 在底部的 TabBar 找到并点击带有加号 `[+]` 且文本为 `[发布]` 的图标 | 画面改变，唤出了一个包含标题 `[发布动态]`的全屏表单页，光标自动在输入区闪烁。 |
+| 2 | [D7] ✅ | 尝试直接点击右上角的 `[发送]` 按钮 | 不能跳转，并且在输入框附近看到标红的提错文字如 `[内容不能为空]`。 |
+| 3 | [D2] 🖱️ | 在输入区域内，输入你记得的变量 `[RandomPostText]` 文字 | `[RandomPostText]` 的文字成功占据了输入框。 |
+| 4 | [D3] ⏳ | 点击右上角的蓝色 `[发送]` 按钮。**如有弹窗，点击允许。** | 获取到一闪而过的 Toast `[发布成功]`，并且画面自动切回了动态列表。 |
+| 5 | [D5] 📊 | （如果没看到，请在当前页面**上滑一指的距离**）寻找最新一条动态 | 它的内容正好匹配你记住的 `[RandomPostText]`。 |
+| 6 | [D2] 🖱️ | **[清理动作]** 点击这条动态右上角的 `[...]` 更多图标，然后点击红色的 `[删除]` | 这条带有 `[RandomPostText]` 的卡片从画面上彻底消失。 |
+```
+
+### 第二步：带有防崩塌协议（Self-Healing Proto.）下发任务
+
+当下发 Agent 任务执行该用例文档时，务必携带以下“潜规则”：
+
+1. **遇阻绕协议 (Blocker Protocol)**：当你进入新层级并且遇到“需要权限（位置/图库/通知）”、“强制更新说明”和“引导滑窗”时，允许跳过此用例的当步预期，优先点击**『确定、允许、稍后再说、叉叉』**。
+2. **遮挡协议 (Keyboard & Overlay)**：如果输入完成后需要点击提交按钮但找不到，优先猜测是因为 iOS/Android 原生键盘遮挡，请尝试触发一次『点击界面空白处』来收起键盘，再执行寻找。
+3. **寻找协议 (Scroll Protocol)**：在长列表页，所寻文字未必在首屏视口 (Viewport) 内，如果直接寻找失败，必须先主动追加 `滑动(Swipe Down)` 动作再次扫描。
+4. **防中断硬执行 (Continue-On-Error)**：绝对禁止测试中断烂尾行动！即便你在执行 TC-M-01 时发现全盘卡死错位，也必须记下该 `FAIL`，然后**立刻发起『物理返回/关闭应用重启/狂点底部 Home Tab』强制回到一个干净界面状态**，去接着跑完接下来的 TC-M-02 和 TC-M-03。
+
+### 第三步：人工/集成复核生成的 Report 书
+
+Agent 跑完不需要输出 log，只要求产生一份纯文本带截图的 `e2e-report.md`，上面标注 `TC-M-01: ✅ Pass (附有执行截图)`。

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/mock-strategy/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: mock-strategy
+description: Mock Strategy Skill
+---
+
+# Mock Strategy Skill
+
+前端 Mock 数据策略与工具选型。
+
+## 工具对比
+
+| 工具 | 特点 | 适用场景 |
+|------|------|----------|
+| MSW | 拦截网络请求 | 推荐，最接近真实 |
+| json-server | 快速 REST API | 简单 CRUD |
+| 手动 Mock | 完全可控 | 复杂逻辑 |
+
+## MSW 配置（推荐）
+
+```typescript
+// src/mocks/handlers.ts
+import { http, HttpResponse, delay } from 'msw';
+
+export const handlers = [
+  http.get('/api/users', async ({ request }) => {
+    await delay(200);
+    const url = new URL(request.url);
+    const page = Number(url.searchParams.get('page')) || 1;
+    
+    return HttpResponse.json({
+      code: 0,
+      message: 'success',
+      data: { list: mockUsers, total: 100, page },
+    });
+  }),
+  
+  http.get('/api/users/:id', async ({ params }) => {
+    const user = mockUsers.find(u => u.id === Number(params.id));
+    if (!user) {
+      return HttpResponse.json(
+        { code: 40401, message: '用户不存在' },
+        { status: 404 }
+      );
+    }
+    return HttpResponse.json({ code: 0, data: user });
+  }),
+];
+```
+
+```typescript
+// src/mocks/browser.ts
+import { setupWorker } from 'msw/browser';
+import { handlers } from './handlers';
+
+export const worker = setupWorker(...handlers);
+```
+
+```typescript
+// main.tsx - 条件启用
+async function enableMocking() {
+  if (import.meta.env.VITE_USE_MOCK !== 'true') return;
+  const { worker } = await import('./mocks/browser');
+  return worker.start({ onUnhandledRequest: 'bypass' });
+}
+
+enableMocking().then(() => {
+  ReactDOM.createRoot(root).render(<App />);
+});
+```
+
+## Mock 数据生成
+
+```typescript
+// src/mocks/data/users.ts
+import { faker } from '@faker-js/faker/locale/zh_CN';
+
+export const mockUsers = Array.from({ length: 50 }, (_, i) => ({
+  id: i + 1,
+  name: faker.person.fullName(),
+  email: faker.internet.email(),
+  avatar: faker.image.avatar(),
+  createdAt: faker.date.past().toISOString(),
+}));
+```
+
+## 环境配置
+
+```bash
+# .env.development
+VITE_USE_MOCK=true
+
+# .env.development.local（联调时）
+VITE_USE_MOCK=false
+```
+
+```typescript
+// src/config/index.ts
+export const config = {
+  useMock: import.meta.env.VITE_USE_MOCK === 'true',
+  apiBaseUrl: import.meta.env.VITE_API_BASE_URL || '/api',
+};
+```
+
+## 常见问题
+
+| 问题 | 解决 |
+|------|------|
+| Mock 不生效 | 检查环境变量和 worker 启动 |
+| 请求未拦截 | 检查 handler 路径匹配 |
+| 类型不一致 | 对照 OpenAPI 契约 |
+

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/openspec-apply/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: openspec-apply
+description: Implement an approved OpenSpec change and keep tasks in sync.
+---
+
+$ARGUMENTS
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+
+**Steps**
+Track these steps as TODOs and complete them one by one.
+1. Read `changes/<id>/proposal.md`, `design.md` (if present), and `tasks.md` to confirm scope and acceptance criteria.
+2. Work through tasks sequentially, keeping edits minimal and focused on the requested change.
+3. Confirm completion before updating statuses—make sure every item in `tasks.md` is finished.
+4. Update the checklist after all work is done so each task is marked `- [x]` and reflects reality.
+5. Reference `openspec list` or `openspec show <item>` when additional context is required.
+
+**Reference**
+- Use `openspec show <id> --json --deltas-only` if you need additional context from the proposal while implementing.
+<!-- OPENSPEC:END -->