@pzy560117/codex-harness 0.1.0 → 0.1.2

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/property-testing/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: property-testing
+description: 属性测试 (Property-Based Testing) 指南
+---
+
+# 属性测试 (Property-Based Testing) 指南
+
+使用 fast-check 进行属性驱动测试的规范和最佳实践。
+
+## 核心概念
+
+属性测试通过验证代码在所有有效输入上都满足某些属性（不变量）来测试代码正确性。
+
+### 与单元测试的区别
+
+| 特性 | 单元测试 | 属性测试 |
+|------|----------|----------|
+| 输入 | 手动指定具体值 | 自动生成随机值 |
+| 覆盖 | 有限的边界情况 | 广泛的输入空间 |
+| 断言 | 具体的预期结果 | 通用的属性/不变量 |
+| 用途 | 具体示例验证 | 通用规则验证 |
+
+## fast-check 基础
+
+### 安装
+
+```bash
+npm install -D fast-check
+```
+
+### 基本用法
+
+```typescript
+import * as fc from 'fast-check';
+import { describe, it, expect } from 'vitest';
+
+describe('Property Tests', () => {
+  it('should satisfy property', () => {
+    fc.assert(
+      fc.property(
+        fc.string(),  // 生成器
+        (input) => {  // 属性函数
+          // 返回 true 表示属性满足
+          return input.length >= 0;
+        }
+      ),
+      { numRuns: 100 }  // 至少运行 100 次
+    );
+  });
+});
+```
+
+## 常用生成器
+
+### 基础类型
+
+```typescript
+// 字符串
+fc.string()                    // 任意字符串
+fc.string({ minLength: 1 })    // 非空字符串
+fc.hexaString()                // 十六进制字符串
+fc.emailAddress()              // 邮箱地址
+
+// 数字
+fc.integer()                   // 整数
+fc.integer({ min: 0, max: 100 })
+fc.nat()                       // 自然数 (>=0)
+fc.float()                     // 浮点数
+
+// 布尔
+fc.boolean()
+
+// 数组
+fc.array(fc.integer())
+fc.array(fc.string(), { minLength: 1, maxLength: 10 })
+
+// 对象
+fc.record({
+  name: fc.string(),
+  age: fc.nat(),
+})
+```
+
+### 组合生成器
+
+```typescript
+// 可选值
+fc.option(fc.string())  // string | null
+
+// 联合类型
+fc.oneof(fc.string(), fc.integer())
+
+// 常量
+fc.constant('fixed-value')
+
+// 从数组中选择
+fc.constantFrom('a', 'b', 'c')
+
+// 条件过滤
+fc.string().filter(s => s.length > 0)
+
+// 映射转换
+fc.integer().map(n => n * 2)
+```
+
+### 自定义生成器
+
+```typescript
+// 自定义用户生成器
+const userArb = fc.record({
+  id: fc.uuid(),
+  email: fc.emailAddress(),
+  name: fc.string({ minLength: 1, maxLength: 50 }),
+  age: fc.integer({ min: 18, max: 120 }),
+  role: fc.constantFrom('admin', 'user', 'guest'),
+});
+
+// 自定义密码生成器
+const passwordArb = fc.string({ minLength: 8, maxLength: 128 })
+  .filter(p => /[A-Z]/.test(p) && /[a-z]/.test(p) && /[0-9]/.test(p));
+```
+
+## 常见属性模式
+
+### 1. 往返属性 (Round-Trip)
+
+```typescript
+// Property: 序列化后反序列化应得到原值
+// Validates: Requirements X.Y
+it('serialization round-trip', () => {
+  fc.assert(
+    fc.property(userArb, (user) => {
+      const serialized = JSON.stringify(user);
+      const deserialized = JSON.parse(serialized);
+      return deepEqual(user, deserialized);
+    }),
+    { numRuns: 100 }
+  );
+});
+```
+
+### 2. 幂等性 (Idempotence)
+
+```typescript
+// Property: 操作执行两次应与执行一次结果相同
+// Validates: Requirements X.Y
+it('normalize is idempotent', () => {
+  fc.assert(
+    fc.property(fc.string(), (input) => {
+      const once = normalize(input);
+      const twice = normalize(normalize(input));
+      return once === twice;
+    }),
+    { numRuns: 100 }
+  );
+});
+```
+
+### 3. 不变量 (Invariant)
+
+```typescript
+// Property: 排序后数组长度不变
+// Validates: Requirements X.Y
+it('sort preserves length', () => {
+  fc.assert(
+    fc.property(fc.array(fc.integer()), (arr) => {
+      const sorted = sort(arr);
+      return sorted.length === arr.length;
+    }),
+    { numRuns: 100 }
+  );
+});
+```
+
+### 4. 变换属性 (Metamorphic)
+
+```typescript
+// Property: 过滤后长度应小于等于原长度
+// Validates: Requirements X.Y
+it('filter reduces or maintains length', () => {
+  fc.assert(
+    fc.property(
+      fc.array(fc.integer()),
+      fc.func(fc.boolean()),
+      (arr, predicate) => {
+        const filtered = arr.filter(predicate);
+        return filtered.length <= arr.length;
+      }
+    ),
+    { numRuns: 100 }
+  );
+});
+```
+
+### 5. 错误条件 (Error Conditions)
+
+```typescript
+// Property: 无效输入应抛出错误
+// Validates: Requirements X.Y
+it('rejects invalid input', () => {
+  const invalidEmailArb = fc.string()
+    .filter(s => !s.includes('@'));
+  
+  fc.assert(
+    fc.property(invalidEmailArb, (invalidEmail) => {
+      try {
+        validateEmail(invalidEmail);
+        return false;  // 应该抛出错误
+      } catch {
+        return true;   // 正确抛出错误
+      }
+    }),
+    { numRuns: 100 }
+  );
+});
+```
+
+## 测试配置
+
+### Vitest 配置
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['**/*.test.ts', '**/*.property.test.ts'],
+    testTimeout: 30000,  // 属性测试可能需要更长时间
+  },
+});
+```
+
+### 属性测试配置
+
+```typescript
+fc.assert(
+  fc.property(...),
+  {
+    numRuns: 100,           // 最少运行次数
+    seed: 12345,            // 固定种子（可复现）
+    verbose: true,          // 详细输出
+    endOnFailure: true,     // 失败时立即停止
+  }
+);
+```
+
+## 调试失败的测试
+
+### 查看反例
+
+```typescript
+fc.assert(
+  fc.property(fc.string(), (input) => {
+    console.log('Testing with:', input);  // 打印测试输入
+    return someCondition(input);
+  }),
+  { verbose: true }
+);
+```
+
+### 使用固定种子复现
+
+```typescript
+// 失败时会输出种子，使用该种子复现
+fc.assert(
+  fc.property(...),
+  { seed: 1234567890 }  // 使用失败时的种子
+);
+```
+
+### 缩小反例
+
+fast-check 自动缩小反例到最小失败输入，便于调试。
+
+## 最佳实践
+
+1. **每个属性一个测试**：便于定位问题
+2. **至少 100 次迭代**：确保足够覆盖
+3. **注释属性来源**：标注对应的需求
+4. **使用有意义的生成器**：约束到有效输入空间
+5. **避免过度约束**：让生成器探索边界情况
+6. **结合单元测试**：属性测试补充而非替代单元测试
+
+## 与需求的映射
+
+```typescript
+/**
+ * Property 1: 密码强度计算一致性
+ * *For any* 有效密码，强度计算应返回一致的结果
+ * **Validates: Requirements 1.1, 1.2**
+ */
+it('password strength is consistent', () => {
+  fc.assert(
+    fc.property(validPasswordArb, (password) => {
+      const strength1 = calculateStrength(password);
+      const strength2 = calculateStrength(password);
+      return strength1 === strength2;
+    }),
+    { numRuns: 100 }
+  );
+});
+```
+

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/qa-e2e-planner/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: qa-e2e-planner
+description: 专门扫描前端工程，生成零幻觉、元素级的端到端测试大纲 (e2e-plan.md)。不侵入原工程的 tasks 体系。
+---
+
+# QA E2E Planner 专业测试计划生成器
+
+## 核心职责
+本 Skill 完全独立于常规业务开发流程，专职扮演 **QA 架构师** 角色，负责对前端项目进行自动化排雷扫描，生成标准的 `e2e-plan.md` 端到端验证计划。
+
+## 执行前置条件
+用户已完成前端页面的切图/开发，需要开始进入测试验收环节时调用。
+
+## 工作流 (Workflow)
+
+严格按照 **"扫描 -> 计划 -> 审核 -> 生成任务"** 的顺序执行，不得越级跳步：
+
+1. **深度扫描组件 (Mock & DOM 提取)**
+   - 若项目存在 `docs/ai/repo-map.md`、`docs/context/repo-map.md` 或同类 codemap，先阅读导航文件定位前端入口、路由、状态源和测试相关目录，再进入具体组件；禁止上来就全仓盲扫。
+   - 必须通过底层文件 API (`find_by_name` / `list_dir` / `view_file`) 全面读取当前正在开发或测试的 Vue/React 视图组件文件。
+   - 提取 `<template>` 中所有的交互式控件，例如：`<button>`、`<input>`、`<select>` 等。
+   - 通过 `grep_search` 或深度读取，检索代码中 `mock`、`MockStateWrapper` 等硬编码虚拟数据的痕迹。
+
+2. **导出标准化测试大纲 (e2e-plan.md)**
+   - 根据收集到的待测点与排雷点，调用模板 `.agents/.specify/templates/e2e-plan-template.md`。
+   - 分章节输出：**代码入口与影响面**、**Mock 排雷清单**、**各页面元素级断言**（即测试用例）、**CRUD 闭环业务流**。
+   - ⚠️ **输出路径强制规范**：必须使用 `write_to_file` 将文件写入**项目根目录**（即与 `frontend/`、`backend/` 同级），路径为 `<项目根路径>/e2e-plan.md`。**绝对禁止**将此文件写入 artifact 目录（`~/.gemini/...`）。
+   - **注意**：大纲生成完毕后必须立即挂起操作。
+
+3. **🚧 强制人工Review拦截点 (Mandatory User Review) 🚧**
+   - 此时**严禁直接生成 Tasks 或去执行**。
+   - 必须使用 `notify_user` (设置 `BlockedOnUser: true`) 向用户发起 `e2e-plan.md` 的审核请求。
+   - 附带话术请用户审查是否存在测试用例遗漏（例如边界状态、特定弹窗未包含）。
+
+4. **生成测试执行任务 (Generate Tasks)**
+   - 仅在用户针对 `e2e-plan.md` 审核通过后！！！
+   - 向 `tasks.md` 的末尾（或专门的测试 Task 文件中），严格追加 E2E 阶段特有格式的验证和执行层 Task。
+   - 任务点必须显式指定调用后面的专用 Skills：`/qa-mock-cleaner` 和 `/qa-e2e-runner`。
+
+5. **交接执行层 (Handoff)**
+   - 任务追加完毕后通知用户：测试架构已准备就绪。引导用户调用执行工具链开始真正的自动化验证。

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/qa-e2e-runner/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: qa-e2e-runner
+description: 根据 e2e-plan.md 纯粹地唤起并调度 browser_subagent 进行全量 UI 测试，记录通过率并输出结果。
+---
+
+# QA E2E Runner 测试执行官
+
+## 核心职责
+独立的端到端自动化测试调度员。主要职责是加载已排版的测试大纲，调度原生的 `browser-e2e-testing` 和 `browser_subagent` 依照计划执行页面点击流、表单覆盖和断言测试，出具无假数据干扰的 E2E 测试结果。
+
+## 执行前置条件
+项目代码的 Mock 层已经由 `qa-mock-cleaner` 清除完毕（真实后端已开机可用），且具备待执行的 `e2e-plan.md` 测试计划。
+
+## 工作流 (Workflow)
+
+1. **装载测试计划**
+   - 若项目存在 `docs/ai/repo-map.md`、`docs/context/repo-map.md` 或同类 codemap，先读取导航文件确认页面入口、路由、状态源和关联测试目录，再切入 `e2e-plan.md`。
+   - 解读 `e2e-plan.md` 中的所有元素和交互基准，特别是 **代码入口与影响面**、**10 维度断言** 和 **CRUD 全生命周期测试流水线**。
+
+2. **执行自动化测试闭环**
+   - 唤起执行测试的主程序 (通过 `browser_subagent` 或者关联测试框架驱动如 Playwright/Cypress，取决于本地支持)。
+   - 按章节逐页面点击所有的 `<button>`，输入各类异常、边界值至 `<input>` 表单中。
+   - 执行生命周期流程：让测试机器人走完从创建 (Create)、查看 (Read)、更新 (Update) 至终结删除 (Delete) 闭环。
+
+3. **收录与报告输出**
+   - 构建 `qa-e2e-report.md` 测试报告文件，对比原计划中的每一个勾选项标记 Pass 或是 Fail。
+   - 如果发生阻断错误（Fail），先按 `TEST_CODE_ISSUE / PRODUCT_BUG / REQUIREMENT_CHANGE / ENV_OR_DATA_ISSUE / FLAKY` 做一级分类，再提供详尽的终端输出日志摘录或页面元素截图证据供研发人员回溯修复。

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

@@ -0,0 +1,29 @@
+---
+name: qa-mock-cleaner
+description: 专门依据 e2e-plan.md 执行前端 Mock 数据依赖的扫除行动，将系统与真实后端连通。
+---
+
+# QA Mock Cleaner 前后端连通器
+
+## 核心职责
+在进行严格的端到端浏览器测试之前，必须保证 "Zero-Mock"（零假数据拦截）。本 Skill 的唯一作用就是根据 QA 提供的清洗清单，安全、无损地拆除各个组件中的 Mock，恢复原本的网络层轴心。
+
+## 执行前置条件
+当前特性开发的前端页面中存在虚拟后端支持，并且 `e2e-plan.md` 第一章 (Mock 依赖排雷清单) 已经生成。
+
+## 工作流 (Workflow)
+
+1. **获取排雷计划**
+   - 若项目存在 `docs/ai/repo-map.md`、`docs/context/repo-map.md` 或同类 codemap，先读取导航文件定位页面入口、Mock 所在目录和真实接口边界。
+   - 读取目标路径中的 `e2e-plan.md` 文件的 "代码入口与影响面"、"Mock 依赖排雷清单" 章节。
+   - 精准定位被指出的那些 `.vue` 页面文件或 `src/mock/` 目录下的拦截文件。
+
+2. **精细化剥离与真实接口替换**
+   - 针对文件内的 `<MockStateWrapper>` 进行剥离，改为通过 axios 或 Vue store 调用真实后端接口的错误/加载捕获机制。
+   - 如果遇到全局拦截（如 MSW 或 axios-mock-adapter），执行完全关闭操作，保证接下来的流量必须直通后端环境。
+
+3. **联通自检**
+   - 确认关键文件的修改未破坏 Vue 组件编译 (`npm run build` 或依赖自身验证手段不报错)。
+
+4. **完成与交接**
+   - 在完成剥离动作后，通知用户清理工作结束，并转交权柄给 `qa-e2e-runner` 去启动测试运行。

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/qoder-codex-api-config/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: "qoder-codex-api-config"
+description: "Use when configuring local Qoder/Qoder CLI to use the current Codex API settings, including writing Qoder custom model records, encrypted SecretStorage API keys, and default model selections on Windows."
+---
+
+# Qoder Codex API Config
+
+用于把当前 Codex 的 API 配置写入本机 Qoder 配置。适用场景：
+
+- 用户要求“配置 Qoder 使用当前 Codex API”
+- 用户要求“把 Codex 的 API/模型接到 Qoder”
+- 用户要求“直接修改 Qoder 配置”
+
+## 核心规则
+
+- 不把 API key 明文写入仓库、日志或普通 JSON 配置。
+- 写入前检查 Qoder 是否正在运行；正在运行时默认停止并让用户关闭 Qoder，避免 Qoder 退出时覆盖 SQLite。
+- 写入前备份 `User/globalStorage/state.vscdb` 及同名 `-wal`、`-shm`。
+- 默认从 `C:\Users\<user>\.codex\config.toml` 读取 `model`、当前 `model_provider` 和对应 provider 的 `base_url`。
+- 默认从 `C:\Users\<user>\.codex\auth.json` 读取 `OPENAI_API_KEY`，用 Qoder `Local State` 的 Chromium OSCrypt key 加密后写入 `secret://aicoding.customModel.apiKey.<model_id>`。
+
+## 一步配置
+
+运行 bundled 脚本：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .agents\skills\qoder-codex-api-config\scripts\configure-qoder-codex-api.ps1
+```
+
+常用覆盖参数：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .agents\skills\qoder-codex-api-config\scripts\configure-qoder-codex-api.ps1 `
+  -Model "gpt-5.5" `
+  -BaseUrl "http://47.250.148.224" `
+  -Alias "Codex GPT-5.5" `
+  -Provider "openai" `
+  -ByokTypeKey "openai"
+```
+
+## 写入内容
+
+脚本会写入：
+
+- `aicoding.customModels`: Qoder custom model 数组
+- `secret://aicoding.customModel.apiKey.<model_id>`: 加密后的 API key
+- `chat.modelConfig.assistant`: `custom:<model_id>`
+- `chat.modelConfig.experts`: `custom:<model_id>`
+- `aicoding.aicoding-agent`: `globalstate-selected-models` 中的 chat/assistant
+- `__$__targetStorageMarker`: 补充相关 storage scope marker
+
+默认模型 ID 会从模型名生成，例如 `gpt-5.5` -> `model_codex_gpt_5_5`。
+
+## 验证
+
+配置后脚本会验证：
+
+- `aicoding.customModels` 是数组且包含目标模型
+- SecretStorage 记录可被当前 Windows 用户解密，且和 Codex API key 一致
+- 默认模型选择已写入
+
+如果 Qoder 启动后仍不显示该模型，优先检查：
+
+1. Qoder 是否在写入时仍在运行。
+2. Qoder 后端是否允许 BYOK，自定义模型功能可能受账号/远端开关控制。
+3. Qoder 实际 provider 是否接受 `Provider`/`ByokTypeKey`，默认使用 `openai`。
+4. Codex 当前 `wire_api` 可能是 `responses`，而 Qoder BYOK 后端可能只支持 provider 自身协议。

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/qoder-codex-api-config/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Qoder Codex API Config"
+  short_description: "配置 Qoder 使用当前 Codex API"
+  default_prompt: "Use $qoder-codex-api-config to configure Qoder to use my current Codex API settings."
+
+policy:
+  allow_implicit_invocation: true