@pzy560117/codex-harness 0.1.0 → 0.1.1

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,40 @@
+---
+name: qa-e2e-planner
+description: 专门扫描前端工程，生成零幻觉、元素级的端到端测试大纲 (e2e-plan.md)。不侵入原工程的 tasks 体系。
+---
+
+# QA E2E Planner 专业测试计划生成器
+
+## 核心职责
+本 Skill 完全独立于常规业务开发流程，专职扮演 **QA 架构师** 角色，负责对前端项目进行自动化排雷扫描，生成标准的 `e2e-plan.md` 端到端验证计划。
+
+## 执行前置条件
+用户已完成前端页面的切图/开发，需要开始进入测试验收环节时调用。
+
+## 工作流 (Workflow)
+
+严格按照 **"扫描 -> 计划 -> 审核 -> 生成任务"** 的顺序执行，不得越级跳步：
+
+1. **深度扫描组件 (Mock & DOM 提取)**
+   - 必须通过底层文件 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,26 @@
+---
+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. **装载测试计划**
+   - 强行切入到 `e2e-plan.md`。解读其中的所有的元素和交互基准，特别是 **10 维度断言** 和 **CRUD 全生命周期测试流水线**。
+
+2. **执行自动化测试闭环**
+   - 唤起执行测试的主程序 (通过 `browser_subagent` 或者关联测试框架驱动如 Playwright/Cypress，取决于本地支持)。
+   - 按章节逐页面点击所有的 `<button>`，输入各类异常、边界值至 `<input>` 表单中。
+   - 执行生命周期流程：让测试机器人走完从创建 (Create)、查看 (Read)、更新 (Update) 至终结删除 (Delete) 闭环。
+
+3. **收录与报告输出**
+   - 构建 `qa-e2e-report.md` 测试报告文件，对比原计划中的每一个勾选项标记 Pass 或是 Fail。
+   - 如果发生阻断错误（Fail），提供详尽的终端输出日志摘录，或页面元素截图证据供研发人员回溯修复。

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

@@ -0,0 +1,28 @@
+---
+name: qa-mock-cleaner
+description: 专门依据 e2e-plan.md 执行前端 Mock 数据依赖的扫除行动，将系统与真实后端连通。
+---
+
+# QA Mock Cleaner 前后端连通器
+
+## 核心职责
+在进行严格的端到端浏览器测试之前，必须保证 "Zero-Mock"（零假数据拦截）。本 Skill 的唯一作用就是根据 QA 提供的清洗清单，安全、无损地拆除各个组件中的 Mock，恢复原本的网络层轴心。
+
+## 执行前置条件
+当前特性开发的前端页面中存在虚拟后端支持，并且 `e2e-plan.md` 第一章 (Mock 依赖排雷清单) 已经生成。
+
+## 工作流 (Workflow)
+
+1. **获取排雷计划**
+   - 读取目标路径中的 `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