@pzy560117/codex-harness 0.1.4 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/commands/e2e.md

@@ -0,0 +1,389 @@
+---
+description: 使用 Playwright 生成并运行端到端测试。创建测试旅程、运行测试、捕获截图/视频/跟踪，并上传工件。
+---
+
+# E2E 命令
+
+此命令调用 **e2e-runner** 代理来使用 Playwright 生成、维护和执行端到端测试。
+
+## 此命令的作用
+
+1. **生成测试旅程** - 为用户流程创建 Playwright 测试
+2. **运行 E2E 测试** - 跨浏览器执行测试
+3. **捕获工件** - 失败时的截图、视频、跟踪
+4. **上传结果** - HTML 报告和 JUnit XML
+5. **识别不稳定测试** - 隔离不稳定的测试
+
+## 何时使用
+
+在以下情况使用 `/e2e`：
+
+* 测试关键用户旅程（登录、交易、支付）
+* 验证多步骤流程端到端工作
+* 测试 UI 交互和导航
+* 验证前端和后端之间的集成
+* 为生产部署做准备
+
+## 工作原理
+
+e2e-runner 代理将：
+
+1. **分析用户流程**并识别测试场景
+2. **优先从 `docs/ai/repo-map.md` 或等价代码地图进入代码结构**，再补局部页面、接口和测试入口
+3. **使用页面对象模型模式生成 Playwright 测试**
+4. **跨多个浏览器（Chrome、Firefox、Safari）运行测试**
+5. **捕获失败**，包括截图、视频和跟踪
+6. **生成包含结果和工件的报告**
+7. **识别不稳定测试**并推荐修复方法
+
+如果仓库已经采用 Harness testing truth sources，建议先补齐 `docs/testing/e2e-plan.md`，再让 `/e2e` 落测试代码。对于只读研究阶段，应先通过 `repo-map`、验收示例、追溯矩阵和验证矩阵确定范围，而不是直接全仓扫描。
+
+## 使用示例
+
+````
+用户：/e2e 测试市场搜索和查看流程
+
+代理（e2e-runner）：
+# E2E 测试生成：市场搜索和查看流程
+
+## 已识别测试场景
+
+**用户旅程：** 市场搜索 → 查看结果 → 点击市场 → 查看详情
+
+**测试覆盖范围：**
+1. 导航至市场页面
+2. 执行语义搜索
+3. 验证搜索结果
+4. 点击第一个结果
+5. 验证市场详情页面加载
+6. 验证图表渲染
+
+## 生成的测试代码
+
+```typescript
+// tests/e2e/markets/search-and-view.spec.ts
+import { test, expect } from '@playwright/test'
+import { MarketsPage } from '../../pages/MarketsPage'
+import { MarketDetailsPage } from '../../pages/MarketDetailsPage'
+
+test.describe('Market Search and View Flow', () => {
+  test('user can search markets and view details', async ({ page }) => {
+    // 1. Navigate to markets page
+    const marketsPage = new MarketsPage(page)
+    await marketsPage.goto()
+
+    // Verify page loaded
+    await expect(page).toHaveTitle(/Markets/)
+    await expect(page.locator('h1')).toContainText('Markets')
+
+    // 2. Perform semantic search
+    await marketsPage.searchMarkets('election')
+
+    // Wait for API response
+    await page.waitForResponse(resp =>
+      resp.url().includes('/api/markets/search') && resp.status() === 200
+    )
+
+    // 3. Verify search results
+    const marketCards = marketsPage.marketCards
+    await expect(marketCards.first()).toBeVisible()
+    const resultCount = await marketCards.count()
+    expect(resultCount).toBeGreaterThan(0)
+
+    // Take screenshot of search results
+    await page.screenshot({ path: 'artifacts/search-results.png' })
+
+    // 4. Click on first result
+    const firstMarketTitle = await marketCards.first().textContent()
+    await marketCards.first().click()
+
+    // 5. Verify market details page loads
+    await expect(page).toHaveURL(/\/markets\/[a-z0-9-]+/)
+
+    const detailsPage = new MarketDetailsPage(page)
+    await expect(detailsPage.marketName).toBeVisible()
+    await expect(detailsPage.marketDescription).toBeVisible()
+
+    // 6. Verify chart renders
+    await expect(detailsPage.priceChart).toBeVisible()
+
+    // Verify market name matches
+    const detailsTitle = await detailsPage.marketName.textContent()
+    expect(detailsTitle?.toLowerCase()).toContain(
+      firstMarketTitle?.toLowerCase().substring(0, 20) || ''
+    )
+
+    // Take screenshot of market details
+    await page.screenshot({ path: 'artifacts/market-details.png' })
+  })
+
+  test('search with no results shows empty state', async ({ page }) => {
+    const marketsPage = new MarketsPage(page)
+    await marketsPage.goto()
+
+    // Search for non-existent market
+    await marketsPage.searchMarkets('xyznonexistentmarket123456')
+
+    // Verify empty state
+    await expect(page.locator('[data-testid="no-results"]')).toBeVisible()
+    await expect(page.locator('[data-testid="no-results"]')).toContainText(
+      /no.*results|no.*markets/i
+    )
+
+    const marketCount = await marketsPage.marketCards.count()
+    expect(marketCount).toBe(0)
+  })
+
+  test('can clear search and see all markets again', async ({ page }) => {
+    const marketsPage = new MarketsPage(page)
+    await marketsPage.goto()
+
+    // Initial market count
+    const initialCount = await marketsPage.marketCards.count()
+
+    // Perform search
+    await marketsPage.searchMarkets('trump')
+    await page.waitForLoadState('networkidle')
+
+    // Verify filtered results
+    const filteredCount = await marketsPage.marketCards.count()
+    expect(filteredCount).toBeLessThan(initialCount)
+
+    // Clear search
+    await marketsPage.searchInput.clear()
+    await page.waitForLoadState('networkidle')
+
+    // Verify all markets shown again
+    const finalCount = await marketsPage.marketCards.count()
+    expect(finalCount).toBe(initialCount)
+  })
+})
+
+````
+
+## 运行测试
+
+```bash
+# Run the generated test
+npx playwright test tests/e2e/markets/search-and-view.spec.ts
+
+Running 3 tests using 3 workers
+
+  ✓  [chromium] › search-and-view.spec.ts:5:3 › user can search markets and view details (4.2s)
+  ✓  [chromium] › search-and-view.spec.ts:52:3 › search with no results shows empty state (1.8s)
+  ✓  [chromium] › search-and-view.spec.ts:67:3 › can clear search and see all markets again (2.9s)
+
+  3 passed (9.1s)
+
+Artifacts generated:
+- artifacts/search-results.png
+- artifacts/market-details.png
+- playwright-report/index.html
+```
+
+## 测试报告
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║                    E2E 测试结果                          ║
+╠══════════════════════════════════════════════════════════════╣
+║ 状态：     PASS: 所有测试通过                              ║
+║ 总计：      3 项测试                                          ║
+║ 通过：     3 (100%)                                         ║
+║ 失败：     0                                                ║
+║ 不稳定：    0                                                ║
+║ 耗时：   9.1s                                             ║
+╚══════════════════════════════════════════════════════════════╝
+
+产物：
+ 截图： 2 个文件
+ 视频： 0 个文件（仅在失败时生成）
+ 追踪文件： 0 个文件（仅在失败时生成）
+ HTML 报告： playwright-report/index.html
+
+查看报告： npx playwright show-report
+```
+
+PASS: E2E 测试套件已准备好进行 CI/CD 集成！
+
+````
+## 测试产物
+
+当测试运行时，会捕获以下产物：
+
+**所有测试：**
+- 包含时间线和结果的 HTML 报告
+- 用于 CI 集成的 JUnit XML 文件
+
+**仅在失败时：**
+- 失败状态的截图
+- 测试的视频录制
+- 用于调试的追踪文件（逐步重放）
+- 网络日志
+- 控制台日志
+
+## 查看产物
+
+```bash
+# 在浏览器中查看 HTML 报告
+npx playwright show-report
+
+# 查看特定的追踪文件
+npx playwright show-trace artifacts/trace-abc123.zip
+
+# 截图保存在 artifacts/ 目录中
+open artifacts/search-results.png
+
+````
+
+## 不稳定测试检测
+
+如果测试间歇性失败：
+
+```
+WARNING:  FLAKY TEST DETECTED: tests/e2e/markets/trade.spec.ts
+
+测试通过了 7/10 次运行 (70% 通过率)
+
+常见失败原因:
+"等待元素 '[data-testid="confirm-btn"]' 超时"
+
+推荐修复方法:
+1. 添加显式等待: await page.waitForSelector('[data-testid="confirm-btn"]')
+2. 增加超时时间: { timeout: 10000 }
+3. 检查组件中的竞争条件
+4. 确认元素未被动画遮挡
+
+隔离建议: 在修复前标记为 test.fixme()
+```
+
+## 失败处理顺序
+
+不要在失败后第一时间弱化断言或跳过测试。先分类：
+
+1. `TEST_CODE_ISSUE`
+2. `PRODUCT_BUG`
+3. `REQUIREMENT_CHANGE`
+4. `ENV_OR_DATA_ISSUE`
+5. `FLAKY`
+
+然后再进入 owner 级归因和修复动作。对于 Harness 项目，建议把分类结果同步到 `docs/testing/failure-triage.md`。
+
+## 浏览器配置
+
+默认情况下，测试在多个浏览器上运行：
+
+* PASS: Chromium（桌面版 Chrome）
+* PASS: Firefox（桌面版）
+* PASS: WebKit（桌面版 Safari）
+* PASS: 移动版 Chrome（可选）
+
+在 `playwright.config.ts` 中配置以调整浏览器。
+
+## CI/CD 集成
+
+添加到您的 CI 流水线：
+
+```yaml
+# .github/workflows/e2e.yml
+- name: Install Playwright
+  run: npx playwright install --with-deps
+
+- name: Run E2E tests
+  run: npx playwright test
+
+- name: Upload artifacts
+  if: always()
+  uses: actions/upload-artifact@v3
+  with:
+    name: playwright-report
+    path: playwright-report/
+```
+
+## PMX 特定的关键流程
+
+对于 PMX，请优先考虑以下 E2E 测试：
+
+**关键（必须始终通过）：**
+
+1. 用户可以连接钱包
+2. 用户可以浏览市场
+3. 用户可以搜索市场（语义搜索）
+4. 用户可以查看市场详情
+5. 用户可以下交易单（使用测试资金）
+6. 市场正确结算
+7. 用户可以提取资金
+
+**重要：**
+
+1. 市场创建流程
+2. 用户资料更新
+3. 实时价格更新
+4. 图表渲染
+5. 过滤和排序市场
+6. 移动端响应式布局
+
+## 最佳实践
+
+**应该：**
+
+* PASS: 使用页面对象模型以提高可维护性
+* PASS: 使用 data-testid 属性作为选择器
+* PASS: 等待 API 响应，而不是使用任意超时
+* PASS: 测试关键用户旅程的端到端
+* PASS: 在合并到主分支前运行测试
+* PASS: 在测试失败时审查工件
+
+**不应该：**
+
+* FAIL: 使用不稳定的选择器（CSS 类可能会改变）
+* FAIL: 测试实现细节
+* FAIL: 针对生产环境运行测试
+* FAIL: 忽略不稳定测试
+* FAIL: 在失败时跳过工件审查
+* FAIL: 使用 E2E 测试每个边缘情况（使用单元测试）
+
+## 重要注意事项
+
+**对 PMX 至关重要：**
+
+* 涉及真实资金的 E2E 测试**必须**仅在测试网/暂存环境中运行
+* 切勿针对生产环境运行交易测试
+* 为金融测试设置 `test.skip(process.env.NODE_ENV === 'production')`
+* 仅使用带有少量测试资金的测试钱包
+
+## 与其他命令的集成
+
+* 使用 `/plan` 来识别要测试的关键旅程
+* 使用 `/tdd` 进行单元测试（更快、更细粒度）
+* 使用 `/e2e` 进行集成和用户旅程测试
+* 使用 `/code-review` 来验证测试质量
+
+## 相关代理
+
+此命令调用由 ECC 提供的 `e2e-runner` 代理。
+
+对于手动安装，源文件位于：
+`agents/e2e-runner.md`
+
+## 快速命令
+
+```bash
+# Run all E2E tests
+npx playwright test
+
+# Run specific test file
+npx playwright test tests/e2e/markets/search.spec.ts
+
+# Run in headed mode (see browser)
+npx playwright test --headed
+
+# Debug test
+npx playwright test --debug
+
+# Generate test code
+npx playwright codegen http://localhost:3000
+
+# View report
+npx playwright show-report
+```

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/commands/eval.md

@@ -0,0 +1,122 @@
+# Eval 命令
+
+管理基于评估的开发工作流。
+
+## 用法
+
+`/eval [define|check|report|list] [feature-name]`
+
+## 定义评估
+
+`/eval define feature-name`
+
+创建新的评估定义：
+
+1. 使用模板创建 `.claude/evals/feature-name.md`：
+
+```markdown
+## EVAL: 功能名称
+创建于: $(date)
+
+### 能力评估
+- [ ] [能力 1 的描述]
+- [ ] [能力 2 的描述]
+
+### 回归评估
+- [ ] [现有行为 1 仍然有效]
+- [ ] [现有行为 2 仍然有效]
+
+### 成功标准
+- 能力评估的 pass@3 > 90%
+- 回归评估的 pass^3 = 100%
+
+```
+
+2. 提示用户填写具体标准
+
+## 检查评估
+
+`/eval check feature-name`
+
+为功能运行评估：
+
+1. 从 `.claude/evals/feature-name.md` 读取评估定义
+2. 对于每个能力评估：
+   * 尝试验证标准
+   * 记录 通过/失败
+   * 在 `.claude/evals/feature-name.log` 中记录尝试
+3. 对于每个回归评估：
+   * 运行相关测试
+   * 与基线比较
+   * 记录 通过/失败
+4. 报告当前状态：
+
+```
+EVAL CHECK: feature-name
+========================
+功能：X/Y 通过
+回归测试：X/Y 通过
+状态：进行中 / 就绪
+```
+
+## 报告评估
+
+`/eval report feature-name`
+
+生成全面的评估报告：
+
+```
+EVAL REPORT: feature-name
+=========================
+生成时间: $(date)
+
+能力评估
+----------------
+[eval-1]: 通过 (pass@1)
+[eval-2]: 通过 (pass@2) - 需要重试
+[eval-3]: 失败 - 参见备注
+
+回归测试
+----------------
+[test-1]: 通过
+[test-2]: 通过
+[test-3]: 通过
+
+指标
+-------
+能力 pass@1: 67%
+能力 pass@3: 100%
+回归 pass^3: 100%
+
+备注
+-----
+[任何问题、边界情况或观察结果]
+
+建议
+--------------
+[SHIP / NEEDS WORK / BLOCKED]
+```
+
+## 列出评估
+
+`/eval list`
+
+显示所有评估定义：
+
+```
+功能模块定义
+================
+feature-auth      [3/5 通过] 进行中
+feature-search    [5/5 通过] 就绪
+feature-export    [0/4 通过] 未开始
+```
+
+## 参数
+
+$ARGUMENTS:
+
+* `define <name>` - 创建新的评估定义
+* `check <name>` - 运行并检查评估
+* `report <name>` - 生成完整报告
+* `list` - 显示所有评估
+* `clean` - 删除旧的评估日志（保留最近 10 次运行）

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/commands/evolve.md

@@ -0,0 +1,194 @@
+---
+name: evolve
+description: 分析本能并建议或生成进化结构
+command: true
+---
+
+# Evolve 命令
+
+## 实现方式
+
+使用插件根路径运行 instinct CLI：
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" evolve [--generate]
+```
+
+或者如果 `CLAUDE_PLUGIN_ROOT` 未设置（手动安装）：
+
+```bash
+python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py evolve [--generate]
+```
+
+分析本能并将相关的本能聚合成更高层次的结构：
+
+* **命令**：当本能描述用户调用的操作时
+* **技能**：当本能描述自动触发的行为时
+* **代理**：当本能描述复杂的、多步骤的流程时
+
+## 使用方法
+
+```
+/evolve                    # 分析所有本能并建议进化方向
+/evolve --generate         # 同时在 evolved/{skills,commands,agents} 目录下生成文件
+```
+
+## 演化规则
+
+### → 命令（用户调用）
+
+当本能描述用户会明确请求的操作时：
+
+* 多个关于“当用户要求...”的本能
+* 触发器类似“当创建新的 X 时”的本能
+* 遵循可重复序列的本能
+
+示例：
+
+* `new-table-step1`: "当添加数据库表时，创建迁移"
+* `new-table-step2`: "当添加数据库表时，更新模式"
+* `new-table-step3`: "当添加数据库表时，重新生成类型"
+
+→ 创建：**new-table** 命令
+
+### → 技能（自动触发）
+
+当本能描述应该自动发生的行为时：
+
+* 模式匹配触发器
+* 错误处理响应
+* 代码风格强制执行
+
+示例：
+
+* `prefer-functional`: "当编写函数时，优先使用函数式风格"
+* `use-immutable`: "当修改状态时，使用不可变模式"
+* `avoid-classes`: "当设计模块时，避免基于类的设计"
+
+→ 创建：`functional-patterns` 技能
+
+### → 代理（需要深度/隔离）
+
+当本能描述复杂的、多步骤的、受益于隔离的流程时：
+
+* 调试工作流
+* 重构序列
+* 研究任务
+
+示例：
+
+* `debug-step1`: "当调试时，首先检查日志"
+* `debug-step2`: "当调试时，隔离故障组件"
+* `debug-step3`: "当调试时，创建最小复现"
+* `debug-step4`: "当调试时，用测试验证修复"
+
+→ 创建：**debugger** 代理
+
+## 操作步骤
+
+1. 检测当前项目上下文
+2. 读取项目 + 全局本能（项目优先级高于 ID 冲突）
+3. 按触发器/领域模式分组本能
+4. 识别：
+   * 技能候选（包含 2+ 个本能的触发器簇）
+   * 命令候选（高置信度工作流本能）
+   * 智能体候选（更大、高置信度的簇）
+5. 在适用时显示升级候选（项目 -> 全局）
+6. 如果传入了 `--generate`，则将文件写入：
+   * 项目范围：`~/.claude/homunculus/projects/<project-id>/evolved/`
+   * 全局回退：`~/.claude/homunculus/evolved/`
+
+## 输出格式
+
+```
+============================================================
+  演进分析 - 12 种直觉
+  项目：my-app (a1b2c3d4e5f6)
+  项目范围：8 | 全局：4
+============================================================
+
+高置信度直觉 (>=80%)：5
+
+## 技能候选
+1. 聚类："adding tests"
+   直觉：3
+   平均置信度：82%
+   领域：testing
+   范围：project
+
+## 命令候选 (2)
+  /adding-tests
+    来源：test-first-workflow [project]
+    置信度：84%
+
+## 代理候选 (1)
+  adding-tests-agent
+    涵盖 3 种直觉
+    平均置信度：82%
+```
+
+## 标志
+
+* `--generate`：除了分析输出外，还生成进化后的文件
+
+## 生成的文件格式
+
+### 命令
+
+```markdown
+---
+name: new-table
+description: Create a new database table with migration, schema update, and type generation
+command: /new-table
+evolved_from:
+  - new-table-migration
+  - update-schema
+  - regenerate-types
+---
+
+# 新建数据表命令
+
+[基于集群本能生成的内容]
+
+## 步骤
+1. ...
+2. ...
+
+```
+
+### 技能
+
+```markdown
+---
+name: functional-patterns
+description: 强制执行函数式编程模式
+evolved_from:
+  - prefer-functional
+  - use-immutable
+  - avoid-classes
+---
+
+# 函数式模式技能
+
+[基于聚类本能生成的内容]
+
+```
+
+### 代理
+
+```markdown
+---
+name: debugger
+description: 系统性调试代理
+model: sonnet
+evolved_from:
+  - debug-check-logs
+  - debug-isolate
+  - debug-reproduce
+---
+
+# 调试器代理
+
+[基于聚类本能生成的内容]
+
+```