@pzy560117/codex-harness 0.1.1 → 0.1.3

package/package-source/docs/codex-harness-engineering/templates/prompts/failure-triage.md

@@ -18,13 +18,14 @@
 
 ## 归因规则
 
-1. 先区分失败来源：spec mismatch、visual mismatch、unit、integration、e2e、build、typecheck、lint、security、environment、unknown。
-2. 每个 finding 必须能追溯到具体证据路径或日志片段。
-3. 合并重复 finding，避免同一根因生成多个 repair task。
-4. 给出 owner：frontend、backend、test、visual-reviewer、docs、controller、environment。
-5. 给出推荐复验命令。
-6. 无法归因时输出 `owner=controller`，并标记 `needs_human=true`。
-7. 如果失败暴露了可复用风险、历史坑或排查步骤，给出 `knowledgeOutputSuggestions`，供 `ARCHIVE-*` 任务写入 `docs/knowledge/pitfalls/` 或 `guidelines/`。
+1. 先输出一级分类：`TEST_CODE_ISSUE` / `PRODUCT_BUG` / `REQUIREMENT_CHANGE` / `ENV_OR_DATA_ISSUE` / `FLAKY`。
+2. 再区分失败来源：spec mismatch、visual mismatch、unit、integration、e2e、build、typecheck、lint、security、environment、unknown。
+3. 每个 finding 必须能追溯到具体证据路径或日志片段。
+4. 合并重复 finding，避免同一根因生成多个 repair task。
+5. 给出 owner：frontend、backend、test、visual-reviewer、docs、controller、environment。
+6. 给出推荐复验命令。
+7. 无法归因时输出 `owner=controller`，并标记 `needs_human=true`。
+8. 如果失败暴露了可复用风险、历史坑或排查步骤，给出 `knowledgeOutputSuggestions`，供 `ARCHIVE-*` 任务写入 `docs/knowledge/pitfalls/` 或 `guidelines/`。
 
 ## 输出格式
 
@@ -53,6 +54,7 @@
     {
       "findingId": "<task-id>-F001",
       "severity": "HIGH",
+      "primaryClass": "PRODUCT_BUG",
       "category": "visual_mismatch",
       "owner": "frontend",
       "evidence": ["artifacts/visual-review/<task-id>/desktop.png"],

package/package-source/docs/codex-harness-engineering/templates/runtime/codex-loop.ps1

@@ -421,15 +421,15 @@ function Get-TaskDefinitionDefaults {
     }
     "feature_plan" {
       $defaultGateProfile = "spec_required"
-      $defaultTruthSources = @("product", "design", "testing")
+      $defaultTruthSources = @("product", "design", "testing", "repo_context")
     }
     "feature_impl" {
       $defaultGateProfile = "spec_required"
-      $defaultTruthSources = @("product", "design", "plan", "testing")
+      $defaultTruthSources = @("product", "design", "plan", "testing", "repo_context")
     }
     "release" {
       $defaultGateProfile = "release_required"
-      $defaultTruthSources = @("product", "design", "plan", "testing")
+      $defaultTruthSources = @("product", "design", "plan", "testing", "repo_context")
     }
     "archive" {
       $defaultGateProfile = "lightweight"
@@ -1766,6 +1766,116 @@ function Invoke-TestCommand {
   }
 }
 
+function Invoke-FailureTriage {
+  <#
+    在测试失败后运行只读失败归因链路，输出结构化 triage 结果。
+  #>
+  param(
+    [object]$Task,
+    [string]$Root,
+    [object]$ExecutionPolicy,
+    [object]$ReviewContext,
+    [object]$CodexResult,
+    [object]$Stage1Result,
+    [object]$TestResult,
+    [string]$CodexCommand,
+    [string]$LogDirectory,
+    [switch]$CaptureJsonEvents
+  )
+
+  $template = Get-PromptTemplate -Root $Root -TemplateName "failure-triage.md"
+  $requirementIdsText = ConvertTo-BulletLines -Items (ConvertTo-StringArray -Value (Get-ObjectPropertyValue -InputObject $Task -Name "requirement_ids")) -EmptyText "- 未显式声明 Requirement IDs"
+  $acceptanceText = ConvertTo-BulletLines -Items (ConvertTo-StringArray -Value $Task.acceptance)
+  $contextFilesText = ConvertTo-BulletLines -Items $ReviewContext.task_context
+  $testingText = ConvertTo-BulletLines -Items $ReviewContext.testing
+  $truthSourceStateText = Convert-TruthSourceStateToBulletLines -States $ReviewContext.truth_source_state
+  $triageOutputPath = Join-Path $LogDirectory "$($Task.id)-failure-triage.json"
+  $testOutputPathText = if ([string]::IsNullOrWhiteSpace($TestResult.OutputLog)) { "- 无测试日志文件" } else { "- $($TestResult.OutputLog)" }
+
+  $prompt = @"
+$template
+
+## Driver Context
+
+- Task ID: $($Task.id)
+- 描述: $($Task.description)
+- Requirement IDs:
+$requirementIdsText
+- 验收标准:
+$acceptanceText
+- 失败来源: test
+- 测试命令: $($Task.test_command)
+- 测试退出码: $($TestResult.ExitCode)
+
+### Task Context Files
+$contextFilesText
+
+### Testing Truth Sources
+$testingText
+
+### Truth Source Completeness
+$truthSourceStateText
+
+### Evidence Files
+- 实现 stdout: $($CodexResult.StdoutLog)
+- 实现 stderr: $($CodexResult.StderrLog)
+- Stage 1 stdout: $($Stage1Result.StdoutLog)
+- Stage 1 stderr: $($Stage1Result.StderrLog)
+$testOutputPathText
+
+### Raw Test Output
+```text
+$($TestResult.Output)
+```
+
+输出要求:
+- 只输出一个合法 JSON 对象。
+- 必须包含 findings 数组；没有 finding 也要输出空数组。
+- 优先把失败归类为 `TEST_CODE_ISSUE`、`PRODUCT_BUG`、`REQUIREMENT_CHANGE`、`ENV_OR_DATA_ISSUE` 或 `FLAKY`。
+"@
+
+  $triageResult = Invoke-CodexTask `
+    -Prompt $prompt `
+    -Root $Root `
+    -Command $CodexCommand `
+    -LogDirectory $LogDirectory `
+    -TaskId "$($Task.id)-failure-triage" `
+    -Sandbox $ExecutionPolicy.codex.review_sandbox `
+    -ActivityLabel "Failure Triage" `
+    -DisableHooks $ExecutionPolicy.codex.disable_hooks `
+    -CaptureJsonEvents:$CaptureJsonEvents
+
+  $triageJson = $triageResult.Output
+  if ([string]::IsNullOrWhiteSpace($triageJson)) {
+    $triageJson = $triageResult.LastMessage
+  }
+
+  $reportPath = $null
+  $parseError = $null
+  if (-not [string]::IsNullOrWhiteSpace($triageJson)) {
+    try {
+      $triageObject = $triageJson | ConvertFrom-Json -ErrorAction Stop
+      $triageObject | ConvertTo-Json -Depth 12 | Set-Content -LiteralPath $triageOutputPath -Encoding UTF8
+      $reportPath = $triageOutputPath
+    }
+    catch {
+      $parseError = $_.Exception.Message
+    }
+  }
+
+  return [PSCustomObject]@{
+    ExitCode = $triageResult.ExitCode
+    Output = $triageResult.Output
+    LastMessage = $triageResult.LastMessage
+    StdoutLog = $triageResult.StdoutLog
+    StderrLog = $triageResult.StderrLog
+    PromptLog = $triageResult.PromptLog
+    LastMessageLog = $triageResult.LastMessageLog
+    ReportPath = $reportPath
+    ParseError = $parseError
+  }
+}
+
 function Write-ProgressEntry {
   <#
     追加固定格式的人类可读进度记录。
@@ -2103,7 +2213,10 @@ function Invoke-OneTask {
   $testResult = Invoke-TestCommand -Command $task.test_command -Root $ProjectRoot -LogDirectory $taskLogDirectory -TaskId $task.id
 
   if ($testResult.ExitCode -ne 0) {
-    Write-ProgressEntry -Path $ProgressPath -Task $task -WorkSummary "Codex 已产生改动。" -TestSummary "测试失败，退出码 $($testResult.ExitCode)。" -Notes "禁止标记 passes=true，请人工查看 trace。" -Stage1Summary "PASS - 审查通过。" -Stage2Summary "NOT_RUN - 未进入 Stage 2 审查。"
+    Write-Step "测试失败，开始自动失败归因。"
+    $triageResult = Invoke-FailureTriage -Task $task -Root $ProjectRoot -ExecutionPolicy $executionPolicy -ReviewContext $reviewContext -CodexResult $codexResult -Stage1Result $stage1Result -TestResult $testResult -CodexCommand $CodexCommand -LogDirectory $taskLogDirectory -CaptureJsonEvents:$CaptureJsonEvents
+    $triageNote = if ($null -ne $triageResult.ReportPath) { "failure triage: $($triageResult.ReportPath)" } elseif (-not [string]::IsNullOrWhiteSpace($triageResult.ParseError)) { "failure triage parse failed: $($triageResult.ParseError)" } else { "failure triage did not produce a structured report" }
+    Write-ProgressEntry -Path $ProgressPath -Task $task -WorkSummary "Codex 已产生改动。" -TestSummary "测试失败，退出码 $($testResult.ExitCode)。" -Notes "禁止标记 passes=true，请人工查看 trace；$triageNote" -Stage1Summary "PASS - 审查通过。" -Stage2Summary "NOT_RUN - 未进入 Stage 2 审查。"
     $tracePayload = [PSCustomObject]@{
       task_id = $task.id
       task_session_id = $taskSessionId
@@ -2135,7 +2248,8 @@ function Invoke-OneTask {
       commands = @(
         @{ cmd = "codex exec"; exit_code = $codexResult.ExitCode },
         @{ cmd = "stage1 review"; exit_code = $stage1Result.ExitCode; verdict = $stage1Verdict },
-        @{ cmd = $task.test_command; exit_code = $testResult.ExitCode }
+        @{ cmd = $task.test_command; exit_code = $testResult.ExitCode },
+        @{ cmd = "failure triage"; exit_code = $triageResult.ExitCode; report = $triageResult.ReportPath }
       )
       final_message = $codexResult.Output
       logs = @{
@@ -2148,15 +2262,24 @@ function Invoke-OneTask {
         stage1_prompt = $stage1Result.PromptLog
         stage1_last_message = $stage1Result.LastMessageLog
         test_output = $testResult.OutputLog
+        failure_triage_stdout = $triageResult.StdoutLog
+        failure_triage_stderr = $triageResult.StderrLog
+        failure_triage_prompt = $triageResult.PromptLog
+        failure_triage_last_message = $triageResult.LastMessageLog
       }
+      failure_triage_report = $triageResult.ReportPath
+      failure_triage_parse_error = $triageResult.ParseError
     }
-    Add-TraceDurableFields -Trace $tracePayload -SessionDirectory $taskLogDirectory -CaptureJsonEvents:$CaptureJsonEvents -EventsSource $codexResult -LogFiles (@(Get-TraceLogFiles -CodexResults @($codexResult, $stage1Result)) + @(ConvertTo-StringArray -Value $testResult.OutputLog)) | Out-Null
+    Add-TraceDurableFields -Trace $tracePayload -SessionDirectory $taskLogDirectory -CaptureJsonEvents:$CaptureJsonEvents -EventsSource $codexResult -LogFiles (@(Get-TraceLogFiles -CodexResults @($codexResult, $stage1Result, $triageResult)) + @(ConvertTo-StringArray -Value $testResult.OutputLog) + @(ConvertTo-StringArray -Value $triageResult.ReportPath)) | Out-Null
     Save-Trace -Directory $TracePath -Trace $tracePayload | Out-Null
     Write-Step "FAILED: 测试失败，退出码 $($testResult.ExitCode)。"
     Write-Output ""
     Write-Output "测试输出:"
     Write-Output $testResult.Output
     Write-Output ""
+    Write-Output "Failure triage:"
+    Write-Output $triageNote
+    Write-Output ""
     Write-Output "Codex 完整日志: $($codexResult.StdoutLog)"
     return [PSCustomObject]@{
       Status = "failed"

package/package-source/docs/codex-harness-engineering/templates/runtime/doctor.ps1

@@ -69,7 +69,19 @@ function Add-DoctorWarning {
 function Get-DoctorFileSha256 {
   param([string]$Path)
 
-  return (Get-FileHash -LiteralPath $Path -Algorithm SHA256).Hash.ToLowerInvariant()
+  $sha256 = [System.Security.Cryptography.SHA256]::Create()
+  $stream = $null
+  try {
+    $stream = [System.IO.File]::OpenRead($Path)
+    $hashBytes = $sha256.ComputeHash($stream)
+    return (($hashBytes | ForEach-Object { $_.ToString("x2") }) -join "")
+  }
+  finally {
+    if ($null -ne $stream) {
+      $stream.Dispose()
+    }
+    $sha256.Dispose()
+  }
 }
 
 function Test-TaskFileHasTemplatePlaceholder {

package/package-source/docs/codex-harness-engineering/templates/runtime/project-task-template.json

@@ -159,9 +159,12 @@
       },
       "steps": [
         "围绕已确认 spec 补齐页面清单、状态矩阵、边界条件、异常流和难点研究",
+        "先从 docs/ai/repo-map.md 或 docs/context/repo-map.md 进入代码结构，再补局部文件阅读；不要直接全仓盲扫",
         "把 Requirement IDs 映射到界面、状态、接口、测试层级、测试数据和证据路径",
+        "输出可复用的代码理解摘要，至少包含入口、关键调用链、受影响文件、受影响测试和高风险点",
         "把系统交付形态、公开入口、数据边界、异步边界、测试替身策略和禁止实现写入架构约束 truth source",
-        "生成后续设计和实现必须依赖的 feature-pack、repo-map、architecture-brief 与 testing truth source"
+        "生成后续设计和实现必须依赖的 feature-pack、repo-map、architecture-brief 与 testing truth source",
+        "如果任务涉及用户可见行为、路由、表单、权限、状态流转或关键业务闭环，补齐 docs/testing/e2e-plan.md 或同等 feature 级 E2E 计划"
       ],
       "test_command": "git diff --check",
       "acceptance": [
@@ -349,6 +352,7 @@
         "把自然语言测试用例中的 TDD 候选转换为每个 feature_impl.qa_contract.tdd_contract，并保留 source_case_ids",
         "把非 TDD 自然语言用例映射到 feature_impl.qa_contract.story_full_chain.source_case_ids、acceptance_validation.source_case_ids、回归计划或 verify-matrix",
         "确认每个实现任务都已有 requirement_ids、owned_paths、context_files 和最小可行验收闭环",
+        "对涉及用户可见行为、路由、表单、权限、状态流转或关键业务闭环的任务，明确是否要求 docs/testing/e2e-plan.md，并把相关 E2E 命令写进 test_command 或 release 验证链路",
         "确认每个 feature_impl 任务都携带 architecture_constraints、forbidden_implementations、tdd_contract 和项目真实可执行的 test_command",
         "明确哪些故事必须串行，哪些依赖可在后续手工改成并行"
       ],
@@ -357,6 +361,7 @@
         "dev-plan、verify-matrix 和 story 级执行顺序保持一致",
         "每个 feature_impl 的 tdd_contract.red.source_case_ids 均能回溯到 NATURAL_LANGUAGE_TEST_CASES.md",
         "每个 feature_impl 的非 TDD 自然语言用例均能回溯到 story_full_chain、acceptance_validation、回归计划或 verify-matrix",
+        "高风险用户可见任务已经明确是否需要 e2e-plan 与对应 E2E 证据",
         "实现任务不会把测试替身、local-only adapter 或领域原型伪装成声明的交付路径",
         "后续实现与 release 任务的验证边界已经明确且可执行"
       ]

package/package-source/docs/codex-harness-engineering/templates/testing/e2e-plan.md

@@ -5,34 +5,135 @@
 **后端 URL**:
 **Seed 命令**:
 **测试数据计划**:
+**导航入口**: `docs/ai/repo-map.md` / `docs/context/repo-map.md`
+**关联代码理解摘要**:
 
-## 1. 范围
+## 1. 功能概览
+
+- 目标:
+- 业务背景:
+- 适用角色:
+- 不覆盖范围:
+
+## 2. 代码入口与影响面
+
+先从 `repo-map` / codemap 进入，再补充局部文件阅读。不要先全仓盲扫。
+
+| 类别 | 入口 / 文件 | 说明 | 受影响测试 |
+| --- | --- | --- | --- |
+| 页面 / 路由 |  |  |  |
+| 组件 |  |  |  |
+| Hook / Store / State |  |  |  |
+| API / Service |  |  |  |
+| 数据模型 / 持久化 |  |  |  |
+
+## 3. 范围与角色
 
 - 范围内:
 - 范围外:
 - 必需角色:
+- 权限差异:
+- 登录态要求:
+
+## 4. 前置条件
+
+- 环境与服务:
+- Feature flag:
+- 账号 / 权限:
+- Seed 数据:
+- 外部依赖:
+- 已知豁免:
 
-## 2. 主流程
+## 5. 测试数据
+
+| 数据名称 | 用途 | 来源 | 重置方式 |
+| --- | --- | --- | --- |
+| 正常数据 | 主流程 |  |  |
+| 边界数据 | 边界 / 上下限 |  |  |
+| 非法数据 | 异常 / 权限 / 拒绝路径 |  |  |
+
+## 6. 核心主流程
 
 | ID | 角色 | 主流程 | 对应需求 | 测试数据 | 期望证据 |
 | --- | --- | --- | --- | --- | --- |
-| E2E-001 | 用户 | | | | 报告 + 截图 / 视频 |
+| E2E-001 | 用户 |  |  |  | 报告 + 截图 / 视频 + 状态证据 |
+
+## 7. 异常与边界流程
+
+| ID | 类型 | 场景 | 预期结果 | 证据 |
+| --- | --- | --- | --- | --- |
+| E2E-NEG-001 | 异常 |  |  |  |
+| E2E-BND-001 | 边界 |  |  |  |
+
+至少检查：
+
+- 空数据
+- 最大 / 最小输入
+- 重复提交
+- 网络慢
+- 接口失败
+- 登录过期
+- 权限不足
 
-## 3. 页面断言
+## 8. 页面与 UI 断言
 
 | 页面 | 状态 | 断言 | 测试层级 |
 | --- | --- | --- | --- |
-| | 默认 | | T5 / T6 |
+|  | 默认 |  | T5 / T6 |
+|  | 错误态 |  | T5 / T6 |
+|  | 空态 |  | T5 / T6 |
+|  | 成功态 |  | T5 / T6 |
+
+## 9. 接口与网络预期
+
+| 入口动作 | 请求 | 成功预期 | 失败预期 |
+| --- | --- | --- | --- |
+|  | `METHOD /path` |  |  |
+
+## 10. 可访问性与交互约束
+
+- 优先使用用户可见语义定位：
+  - `getByRole`
+  - `getByLabel`
+  - `getByPlaceholder`
+  - `getByTestId`
+- 避免把 DOM 层级或脆弱 CSS 选择器作为主定位手段。
+- 记录关键按钮、表单标签、错误提示、loading、键盘操作和 aria 期望。
+
+## 11. Mock 排雷
+
+- [ ] 从 `repo-map`、代码入口和测试目录搜索 `mock`、`fixture`、`fake`、`hardcoded`。
+- [ ] P0 / P1 主流程使用真实后端或明确声明的 mock server。
+- [ ] 必须 mock 的状态已在 `test-matrix.md`、`verify-matrix.md` 或豁免说明中写明。
+- [ ] 前端页面如仍依赖本地假数据，先创建清理任务，再把该 E2E 标记为可执行。
+
+## 12. 受影响测试与执行顺序
+
+| 类别 | 测试 / 命令 | 原因 | 优先级 |
+| --- | --- | --- | --- |
+| Existing |  |  | P0 |
+| New |  |  | P0 |
+
+推荐顺序：
+
+1. 先跑 affected tests / contract checks。
+2. 再跑本计划对应的最小 E2E 集。
+3. 最后跑 P0 / P1 回归或跨故事整链路。
+
+## 13. 失败归因入口
+
+失败后不要直接改测试，先分类：
 
-## 4. Mock 排雷
+1. 测试代码问题
+2. 产品 Bug
+3. 需求变更
+4. 环境 / 数据问题
+5. Flaky 问题
 
-- [ ] 搜索 `mock`、`fixture`、`fake`、`hardcoded`。
-- [ ] P0 主流程使用真实后端或明确的 mock server。
-- [ ] 必须 mock 的状态已在 `test-matrix.md` 中写明豁免。
+分类结果写入 `docs/testing/failure-triage.md` 或等价报告。
 
-## 5. 失败归因
+## 14. 风险与待确认问题
 
-| 失败信号 | 责任方 | 下一步动作 |
-| --- | --- | --- |
-| API 返回 500 | 后端 | 创建修复任务 |
-| 按钮不可点击 | 前端 | 创建修复任务 |
+- 高风险点:
+- 未确认点:
+- 需要人工验收的部分:

package/package-source/docs/codex-harness-engineering/templates/testing/failure-triage.md

@@ -1,24 +1,62 @@
 # 失败归因
 
-| 失败类别 | 典型信号 | 归属方 | 修复目标 | 回归执行方 |
-| --- | --- | --- | --- | --- |
-| `REQ_GAP` | 缺少验收示例、业务规则含糊、没有可观察判定依据 | 产品 | 产品 / 需求负责人 | 原审查人或测试代理 |
-| `TRACE_GAP` | 需求未映射到 UI / API / 测试 / 证据 | requirements-trace | 追溯负责人 | 原审查人或测试代理 |
-| `DESIGN_GAP` | 缺少状态、选择器、交互或视觉规则 | 设计 | 设计负责人 | 原视觉 / 测试代理 |
-| `CONTRACT_GAP` | 缺字段、类型错误、错误码错误、鉴权规则不清楚 | 契约 | 契约负责人 | 契约测试者 |
-| `FRONTEND_BUG` | 按钮不可点击、路由错误、状态缺失 | 前端 | 原开发者 | 原测试代理 |
-| `BACKEND_BUG` | 500、业务规则错误、权限未生效 | 后端 | 后端开发者 | API 测试者 |
-| `TEST_BUG` | 断言错误、等待不稳定、fixture 无效或误报 | 测试 | 测试作者 | 原测试代理 |
-| `TEST_DATA_GAP` | 缺少 seed、账号状态错误、数据重置不可靠 | 测试 / 数据 | 测试数据负责人 | E2E 测试者 |
-| `ENV_BUG` | 端口冲突、服务未启动、依赖缺失 | 环境 | controller / 操作人 | test-runner |
-| `FLAKY` | 间歇性、非确定性失败 | test-runner | 对应 worker + 测试负责人 | 原测试代理 |
-| `SECURITY_RISK` | 认证、权限、密钥或敏感数据问题 | 安全 | 安全 / 后端负责人 | 安全审查者 |
+## 一级分类
+
+先做五选一，不要一上来就改代码或改断言。
+
+| 一级分类 | 定义 | 允许动作 | 禁止动作 |
+| --- | --- | --- | --- |
+| `TEST_CODE_ISSUE` | 定位器、断言、等待时机、fixture 或测试搭建错误 | 修测试代码，保持原测试意图 | 弱化断言掩盖产品问题 |
+| `PRODUCT_BUG` | 实际行为违反需求、契约或设计预期 | 输出 bug report，按 owner 修业务代码 | 把 bug 改写成测试通过 |
+| `REQUIREMENT_CHANGE` | 规格、文案、流程或契约已明确变化 | 先更新真相源，再更新测试 | 不更新规格就改测试预期 |
+| `ENV_OR_DATA_ISSUE` | 服务未启动、数据不完整、权限、端口、外部依赖问题 | 修环境 / 数据并重跑 | 删除测试或直接跳过 |
+| `FLAKY` | 偶发、非确定性、重跑不稳定 | 收集证据，修等待/隔离/时序 | 用 `waitForTimeout` 掩盖问题 |
+
+## 二级归因
+
+在一级分类后，再细分 owner。
+
+| 失败类别 | 对应一级分类 | 典型信号 | 归属方 | 修复目标 | 回归执行方 |
+| --- | --- | --- | --- | --- | --- |
+| `REQ_GAP` | `REQUIREMENT_CHANGE` | 缺少验收示例、业务规则含糊、没有可观察判定依据 | 产品 | 产品 / 需求负责人 | 原审查人或测试代理 |
+| `TRACE_GAP` | `REQUIREMENT_CHANGE` | 需求未映射到 UI / API / 测试 / 证据 | requirements-trace | 追溯负责人 | 原审查人或测试代理 |
+| `DESIGN_GAP` | `REQUIREMENT_CHANGE` | 缺少状态、选择器、交互或视觉规则 | 设计 | 设计负责人 | 原视觉 / 测试代理 |
+| `CONTRACT_GAP` | `REQUIREMENT_CHANGE` | 缺字段、类型错误、错误码错误、鉴权规则不清楚 | 契约 | 契约负责人 | 契约测试者 |
+| `FRONTEND_BUG` | `PRODUCT_BUG` | 按钮不可点击、路由错误、状态缺失 | 前端 | 原开发者 | 原测试代理 |
+| `BACKEND_BUG` | `PRODUCT_BUG` | 500、业务规则错误、权限未生效 | 后端 | 后端开发者 | API 测试者 |
+| `TEST_BUG` | `TEST_CODE_ISSUE` | 断言错误、等待不稳定、fixture 无效或误报 | 测试 | 测试作者 | 原测试代理 |
+| `TEST_DATA_GAP` | `ENV_OR_DATA_ISSUE` | 缺少 seed、账号状态错误、数据重置不可靠 | 测试 / 数据 | 测试数据负责人 | E2E 测试者 |
+| `ENV_BUG` | `ENV_OR_DATA_ISSUE` | 端口冲突、服务未启动、依赖缺失 | 环境 | controller / 操作人 | test-runner |
+| `FLAKY` | `FLAKY` | 间歇性、非确定性失败 | test-runner | 对应 worker + 测试负责人 | 原测试代理 |
+| `SECURITY_RISK` | `PRODUCT_BUG` | 认证、权限、密钥或敏感数据问题 | 安全 | 安全 / 后端负责人 | 安全审查者 |
+
+## 归因记录模板
+
+```md
+### Finding ID
+
+- 一级分类:
+- 二级分类:
+- 失败测试 / 命令:
+- 责任方:
+- 根因:
+- 证据:
+  - 日志:
+  - trace:
+  - screenshot / video:
+  - network / console:
+- 修复动作:
+- 重新运行结果:
+- 后续验证:
+```
 
 ## 规则
 
 - 不要默认把所有失败都归给前端。
+- 先从 `repo-map`、`verify-matrix`、`acceptance examples` 和相关测试计划确认预期，再判断失败性质。
 - 需求或追溯缺陷应回退给产品 / 追溯负责人，不应由实现者自行猜测修补。
 - 契约缺陷应先在契约或对应 owner 流程中修复；不要在前端 / 后端绕过问题。
 - 不要只靠代码评审就关闭 finding；应重跑最小相关测试。
 - 提出 finding 的测试者 / 审查者应在修复后负责关闭它。
 - 环境和网络失败除非超出重试预算并重复出现，否则不应视为产品失败。
+- `FLAKY` 不是兜底垃圾桶；必须附带重跑结果和时序 / 隔离分析。

package/package-source/install-manifest.json

@@ -2,7 +2,7 @@
   "schemaVersion": "0.1",
   "status": "draft",
   "package": "codex-harness",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "installModes": [
     {
       "name": "user",

package/package-source/tools/install/install-agent.ps1

@@ -2500,6 +2500,7 @@ try {
     Write-Output ("- 裁剪 `"{0}`" 和 `"{1}`" 为目标项目事实" -f (Join-Path $resolvedProjectRoot 'docs\ai\repo-map.md'), (Join-Path $resolvedProjectRoot 'docs\ai\architecture-brief.md'))
     Write-Output ("- powershell -NoProfile -ExecutionPolicy Bypass -File `"{0}`"" -f (Join-Path $resolvedProjectRoot 'tools\install\env-check.ps1'))
     Write-Output ("- powershell -NoProfile -ExecutionPolicy Bypass -File `"{0}`"" -f (Join-Path $resolvedProjectRoot 'tools\harness\verify.ps1'))
+    Write-Output ("- 如需 7x24 长时间推进，可在 Codex app 中使用 `/goal`；推荐先读 `"{0}`" 和 `"{1}`"" -f (Join-Path $resolvedProjectRoot 'docs\codex-harness-engineering\goal-harness-integration-guide.md'), (Join-Path $resolvedProjectRoot 'docs\codex-harness-engineering\examples\goal-templates.md'))
     Write-Output ("- powershell -NoProfile -ExecutionPolicy Bypass -File `"{0}`"" -f (Join-Path $resolvedProjectRoot 'tools\harness\codex-loop.ps1'))
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pzy560117/codex-harness",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Codex Harness installer and project runtime CLI",
   "type": "module",
   "bin": {