@hunter-harness/workflow-harness 0.4.8 → 0.4.9

package/harness/bundles/java/cursor/harness-test/SKILL.md

@@ -1,264 +0,0 @@
----
-name: harness-test
-description: 测试执行：读取场景表，执行单元测试+API接口测试+数据兼容验证，输出测试报告。仅当用户显式调用 /harness-test
-  时使用；不得在 run 结束后自动接续执行。
----
-<!-- generated by harness_deploy.py; core=3bcbcb49356096df; overlay=java; agent=cursor; do not edit -->
-# harness-test — 测试执行
-
-> **2026-08 阶段合并**：原 `run`（编码）与 `test`（验证）合并为单一 `execute` 阶段，
-> 统一入口为 **`/harness-execute`**（`harness/harness-execute/SKILL.md`）。本 skill 作为
-> 别名保留，frontmatter `name` 不变、内容照旧可用；门禁入参 `--phase test` 经
-> `LEGACY_PHASE_ALIASES` 归一为 execute。别名至少保留一个 minor 版本，退役时间见
-> `docs/harness-improvement-roadmap/`。下文出现的阶段名 `run`/`test` 均按别名解析。
->
-> 合并语义注意：execute 关门时 C9 场景覆盖要求全部 `ownerPhase=execute` 场景有通过
-> receipt（包括本属 test 的接口/兼容场景）；`ownerPhase=review`/`submit` 仍按计划顺延。
-
-## Purpose
-
-读取测试场景表，逐条执行单元测试和接口测试，验证代码变更的正确性，输出测试报告。
-
-## When to Use
-
-仅当用户显式调用 `/harness-test` 时执行（已设 `disable-model-invocation`）。run 阶段结束后**不自动**进入本阶段；用户口头提到"跑测试"而未调用本 skill 时，先确认是否走 Harness 测试阶段。
-
-**单阶段原则**：test 关门后必须停止并交还用户，仅提示 `plannedPhases` 中的真实下一阶段；禁止自动接续执行。
-
-使用场景：
-- 完成 `/harness-run` 编码后，验证单元测试 + 接口测试 + 数据兼容
-- 修改公共模块 / 数据访问 / sql / 权限认证 / 接口层 / 数据契约 后需要真实接口验证
-- run 阶段 ledger 可复用时，跳过单元测试重跑，只补接口测试
-
-前置依赖：
-- `.harness/changes/<change-name>/plans/<change-name>-test-scenarios.md` 存在（测试真相源）
-- `/harness-run` 已完成，或 ledger 中有可复用的 unitTest 结果
-- 必须读取 `.harness/changes/<change-name>/meta/worktree.json`：`requested=true` 且 worktree 已创建 → 在 worktree 目录中执行测试；`requested=true` 但 worktree 不存在 → 停止，提示先修复 `harness-run`，不得静默回到主目录
-
-跳过场景：
-- 仅改了注释 / 格式化等非行为性清理，且 ledger `postTestClassification=NON_BEHAVIORAL_CLEANUP`，可复用已有 apiTest 结果，不必重跑
-
-## 统一读取协议
-
-0. **脚本在 `<skills-root>/scripts/` 共享，不在每个 skill 子目录下** — 实际形态是 `.codebuddy/skills/scripts/harness_*.py`（`.claude`/`.cursor`/`.codex` 同理），**没有** `.../skills/harness-<phase>/scripts/`。plan、run/test、archive 三份执行日志里都先猜成后者、报 `No such file` 再靠 Search 找回来；照第一种写法直接用
-1. **`.harness/changes/<change-name>/` 是唯一真相源** — 所有输入从该目录读取，产物写入对应子目录
-2. **change-name 优先从 frontmatter 读取** — `plans/*-design.md`、`spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
-3. **frontmatter 缺失时兼容旧格式** — 从路径推断，标记 `🟡 legacy-plan`，不失败
-4. **design** — 设计真相源按序取第一个存在的：`plans/<change>-design.md`（v2 发布产物，哈希绑定）→ `spec/<change>-design.md`（legacy 手写）。两份**同时存在**时以 `plans/` 为准，并记 `🟡 WARN 设计文档双份`——v2 发布的那份才受完整性门禁保护，读手写的那份等于绕过校验
-5. **plan** — 任务真相源：`plans/<change>-plan.md`
-6. **implementation-detail** — 自适应执行参考；legacy 缺失 🟡WARN，不阻断
-7. **test-scenarios** — 测试真相源：`plans/<change>-test-scenarios.md`
-8. **禁止读取 `docs/superpowers/` 作为正式输入** — 旧草稿仅人工线索
-9. **每个 skill 边界只刷新一次状态快照** — 先运行 `python <skills-root>/scripts/harness_state.py capture --project . --change-dir ".harness/changes/<change-name>" --json`。首次 Plan 捕获时，脚本把当时的 Git HEAD 写入不可变 `changeBase`；后续阶段只刷新 `git.head` 与各段指纹，不得用当前 HEAD 覆盖 `changeBase`。只有迁移旧 change 且已能证明真实计划起点时，才在首次补录时传 `--base <baseCommit>`。`changedSegments=[]` 时复用已有 profile/rules/map/change/code 指纹，不再重复跑全量 `harness-sync` 或代码库扫描。`knowledge` 段仅为兼容空段，知识始终按需远端查询；快照不能替代源码读取和验证门禁。
-
-状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
-> 片段：read-protocol
-
-## Workflow
-
-测试跟踪由 `harness_gate.py begin/close` 统一协调 test guard；不得额外手工执行 guard close。任一失败都必须使用 gate 返回的结构化状态，不得以自然语言覆盖失败状态。所有 change/state 路径必须使用 `harness_change.py resolve` 或 context 返回的 `executionRoot`，不得固定拼接 `.harness/changes/**`；split-v1 默认位于 `.harness/state/changes/**`。
-
-兼容实现中的底层命令名是 `harness_test_guard.py begin` 与 `harness_test_guard.py close`，两者只允许由 gate 内部调用；写在这里用于能力审计，不构成模型执行步骤。
-
-并行服务测试先运行 `harness_change.py lease-port --change <id> --run-id <run-id> --range <start-end> --json`，再把返回端口传给 `harness_service.py ensure --leased-port <port> --lease-owner <run-id>`。`serviceStart` 的 command/health/overlay 可用 `{leasedPort}` 占位符；用户自启进程仍只进入 Service Gate，禁止 kill。测试清理的 `finally` 中运行 `harness_change.py release-port --change <id> --run-id <run-id> --json`，避免租约池耗尽。
-
-### Phase -1：资源安全门（任何测试命令之前）
-
-测试默认使用 `safe` 资源档位，禁止直接执行会把整套测试放进同一长生命周期的裸命令。所有本地测试命令必须由 `harness/scripts/harness_test_runner.py` 托管：
-
-```text
-python harness/scripts/harness_test_runner.py exec --profile safe --timeout-seconds <秒> -- <测试命令及参数>
-```
-
-对于 Python `unittest` 测试库，必须使用逐模块隔离模式，不得执行裸 `python -m unittest discover ...`：
-
-```text
-python harness/scripts/harness_test_runner.py unittest --profile safe --tests-dir <测试目录>
-```
-
-资源档位是硬合同：
-
-- `safe`：默认；普通测试模块串行执行，每个模块使用全新进程。
-- `system`：只执行服务生命周期、集成等资源密集型模块。
-- `full`：先执行普通模块，再执行资源密集型模块；仍保持逐模块串行。
-- `system` / `full` 只有在用户明确要求资源密集型测试、传入 `--confirm-resource-intensive`，或受控 CI 设置 `CI=true` / `HARNESS_ALLOW_RESOURCE_INTENSIVE_TESTS=1` 时才允许执行。
-
-Runner 强制同项目单实例、低调度优先级、逐命令超时、正常结束和异常结束的进程树清理。`HARNESS_TEST_MAX_WORKERS` 默认且最高为 `2`，只能调低，不能调高；技术栈自身的并发参数也必须收敛到该值。Windows detached-service 模块在执行前先做 nested-breakaway 能力探测，受限沙箱不支持时立即返回 `DETACHED_PROCESS_CAPABILITY_UNAVAILABLE`，不得让每个服务用例逐一超时。出现该错误、`TEST_RUN_ALREADY_ACTIVE`、`PROCESS_TREE_ISOLATION_UNAVAILABLE` 或 `TEST_COMMAND_TIMEOUT` 必须停止，不得绕过 Runner 重跑裸命令。完整约束见 `checklist.md`「0.0-A 资源安全档位」。
-
-动态数据库/Redis/令牌字段必须先由 `harness_environment.py prepare` 生成 secret-free receipt，再用 `exec --environment-receipt <file> --required-environment-field <NAME>` 闭包注入；缺失或指纹变化在启动测试前返回 `VERIFICATION_ENVIRONMENT_INCOMPLETE`。复杂 JSON、Docker template 或含引号参数不得跨多层 `-Command` 传递，改用 `exec --argv-file <utf8-json> --runtime-receipt <file>`；参数文件记录 PowerShell edition/version，运行回执只存 argv hash。`harness_service.py ensure` 属于正式持久服务模式，禁止从 bounded runner 内启动；命中时返回 `PERSISTENT_SERVICE_MODE_REQUIRED`。
-
-预计超过交互窗口的正式验证使用 `harness_runtime.py run-start`，随后通过
-`run-status` / `run-log --cursor` 重连；不得把调用方存活当作验证存活条件。环境 acquire
-必须显式选择 `change-session`（同 change + 内容指纹复用）或 `ephemeral`（每次重置）。
-验证 DAG 的并行度由 `resourceLocks` 决定，未分类重任务默认串行。完整合同见
-`../protocols/execution-session-protocol.md`。
-
-### Phase 0：环境准备（主会话执行，需要交互确认）
-
-先 `harness_context.py prepare --project . --change <id> --phase test --executor <tool> --json`（`--project` 必填，漏了直接 argparse 报错），再 `harness_context.py begin --project . --change <id> --phase test --executor <tool> --json` 校验最新 run→test receipt 的 artifact/hash/HEAD；然后 **`harness_gate.py begin --phase test --change <id>`**（禁止手工 phase.start / 手写 ledger）。执行各项强制环境检查 + **命令执行模式 preflight (0.1)**；只有首选执行器不可用时，才执行 fallback 执行器探测。
-
-验证写入**仅**允许 `harness_ledger.py record` / `can-reuse`；禁止 Write/Edit `verification-ledger.json`。测试跟踪：gate begin → 执行（可选 `harness_test_guard.py mark stale-test-repair`）→ 单次 `harness_gate.py close`。`--to-phase` 取实际阶段计划的后继；Fixback 返回 run，普通流程可直接进入 Review、Submit 或 Archive。Fixback 只失效与改动文件相交的验证目标。
-
-- **Read `checklist.md`** — 各项检查详情 + 0.1 preflight + Playwright 探测 + 避坑规则指引
-- **失败处理**：任一项检查失败 → 终止流程并报告原因，用户确认修复后才能继续
-- 通过后进入 Phase 1
-
-### Phase 0.1：命令执行模式 preflight（⚠️ 必须在编译/启动服务/生成 runner 之前执行）
-
-`/harness-test` 高度依赖 PowerShell 与接口测试执行器。如果当前会话处于 Auto mode / 安全分类器降级 / PowerShell 被拒，会反复失败并错误降级到 Playwright MCP 逐条接口，造成长时间阻塞。**必须先做 4 项执行模式检查**（PowerShell 基础命令、执行器运行时可用性、构建工具可用性、安全分类器），将通过的 `executorPath` 写入 `.harness/changes/<change-name>/runtime/preflight.json`。
-
-任一硬停情况（安全分类器不可用 / Auto mode 拦截 / PowerShell 被拒 / 执行器或构建工具不可执行）→ 原文输出"❌ 命令执行模式不可用..."，不得继续编译/启动服务/生成执行器，不得盲目降级到 Playwright MCP。用户确认切换权限模式后**必须重新执行 0.1**，重试 ≤ 1 次。详见 `reference.md`「命令执行模式 preflight」。
-
-### Phase 0.2：fallback 执行器探测（仅在首选执行器不可用时执行）
-
-只有 0.1 通过但首选接口测试执行器不可用时才执行 0.2。如果 0.1 已确认执行器在 PowerShell 中可用，直接选择 **接口测试执行器**（Node runner 为一种实现，可按项目替换），不得继续探测或使用 Playwright MCP。
-
-严格优先级（不得颠倒）：接口测试执行器（默认首选，Node runner 为一种实现，可按项目替换为其他 HTTP 客户端）> PowerShell batch `.ps1`（首选不可用时降级）> Playwright MCP `browser_evaluate`（仅当 1+2 都不可用或用户明确选择）> curl + UTF-8 JSON body file（最后兜底）> 禁止直接用 curl 内联发送含中文 JSON body。
-
-> ⚠️ Playwright MCP `browser_evaluate` 不得替代执行器。执行器在 PowerShell 可用时，**禁止**使用 Playwright MCP 逐条执行接口测试——认证凭证是独立凭证，应读认证凭证缓存，由执行器直连本地 baseURL 发起请求。详见 `reference.md`「fallback 执行器探测」。
-
-### Phase 1-2：测试执行（默认主会话执行）
-
-**Phase 1 前先检查 verification-ledger**：先执行 `harness_preflight.py check --project . --json`；profile 缺失或因清单、锁文件、源码根、技术栈变化而陈旧时立即执行一次 `detect --project . --json`。随后通过 state layout 解析后的路径调用 `harness_ledger.py can-reuse --project . --profile-input <key> --command <profile 解析出的规范命令>`；可复用时不得重跑。不得手工读取实现源码来猜账本参数。按返回的 `executionNeed` 使用中文：`first-run`=“尚未执行，需要首次运行”，`rerun`=“证据已失效，需要重新运行”，`evidence-incomplete`=“已有记录不完整，需要重新验证”，`reuse`=“现有证据可复用”；禁止把首次执行统一描述成“强制重跑”。
-
-**默认在主会话执行**（不委派 subagent）：
-- 单元测试：可复用则跳过重跑；否则按技术栈执行测试命令
-- 接口测试：**强制批量执行器**，一次跑完全部场景，主会话只读 JSON
-
-### Phase 3：覆盖率总结 + 关门检查（主会话执行）
-
-读取测试报告，生成覆盖率总结，**执行关门检查**，包含：单元测试通过/失败/跳过计数、接口测试逐条结果+汇总+耗时、数据兼容验证汇总、败因分类（代码 Bug vs 测试脚本 vs 预存问题）、请求执行器及降级原因、关门检查 10 项（见「关键规则·十」）。
-
-### Java 测试环境补充
-
-- **preflight 0.1**：写入 `runtime/preflight.json` 的 `executorPath`/`mvnVersion` 等；Maven 可用性 `mvn -version` exit 0
-- **编译门禁**：测试前按 `build-profile.json` 的 `commands.compile`（v2，profile key resolve）；输出须含 `BUILD SUCCESS` 或 exit 0 证据
-- **条件 install**：worktree 首建或上游模块变更时按 profile 执行 `commands.install`（非每次强制 `-am`）
-- **单元测试**：可复用 ledger unitTest 则跳过；否则 `commands.unitTest`（典型 `mvn test -pl <module>`）；执行模块全量 `commands.unitTestFull` 成功 → 记 `unitTestFull`（scope=module，供 submit 复用）
-- **陈旧测试安全修复**：测试编译明确命中已移除/改名 API 且当前代码与批准计划唯一确定新契约时，只修测试并定向重跑，记录 `stale-test-repair`；有歧义则 `BLOCKED_PREEXISTING`，禁止 `.bak`/删除/禁用/exclude
-- **服务启动**：`build-profile.json` 的 `serviceStartTemplate`（典型 `spring-boot:run` + profile）；**禁止 hardcode 端口/模块路径**
-- **Maven 生命周期去重**：单元测试已独立通过后，服务启动命令可配置 `-Dmaven.test.skip=true` 避免重复测试编译；它仅优化启动，不是测试通过证据
-- **服务指纹输入**（Task 3 §5.1）：`serviceStart.inputFiles` 必须列出 module 源 glob（如 `["<module>/pom.xml", "<module>/src/main/**/*.java", "<module>/src/main/resources/**"]`）；`harness_service.py ensure` 取 CLI `--files` ∪ `inputFiles` 计算 `moduleInputsHash`。**空输入被拒绝**，不得生成可复用空指纹。源码/command/profile/overlayPath 任一变化即 restart
-- **runtime overlay**：`-Dspring.config.additional-location=file:<ascii-abs-path>/application-harness-test.yml`；禁止默认 Edit tracked `application*.yml`
-- **known-good-test-profile**：profile 名、baseURL、healthUrl 写在 build-profile，非 skill 硬编码
-- **多租户请求头**：header 名/值来自 build-profile 的 `httpHeaders` 配置
-- **Service Gate**：`harness_service.py ensure` 返回 `needs-user-decision`（用户进程占端口）时**才** blocking user confirmation
-## P0 执行可信度规则
-
-- 命令结果不得靠猜测；普通 Bash 被拒 → 立即改用等价 PowerShell 重试一次
-- 仅 PowerShell 成功且有明确证据（构建/git/测试输出、文件存在、exit 0）时可标 ✅OK；否则 ❌FAIL 或 🟡WARN
-- 禁止把 hook 拒绝、静态验证、无输出、用户跳过说成成功 → 详见 [[../protocols/powershell-protocol.md|powershell-protocol]]、[[../protocols/evidence-based-reporting-protocol.md|evidence-based-reporting-protocol]]
-
-## 生成内容语言约定
-
-- sync/ingest 等生成的文档、规则、知识条目、架构说明一律**优先使用中文**撰写（标识符、命令、代码、API 字段名保持原文）
-- 面向平台展示的标题/摘要/正文默认中文；仅当用户明确要求或目标系统强制时才用英文
-> 片段：p0-trust
-
-## 关键规则（硬门禁速查）
-
-> 每条规则的详细判定、模板、表格见 `reference.md` 对应章节；Shell 执行安全见 `../protocols/powershell-protocol.md`，证据化报告见 `../protocols/evidence-based-reporting-protocol.md`，敏感信息见 `../protocols/sensitive-info-protocol.md`，ledger 见 `../protocols/ledger-protocol.md`，状态目录见 `../protocols/state-layout-protocol.md`，结构化报告事件见 `../protocols/report-pipeline-protocol.md`。
-
-### 一、接口测试工具优先级
-
-强制优先级：**接口测试执行器**（默认首选，Node runner 为一种实现，可按项目替换为其他 HTTP 客户端）> PowerShell batch `.ps1`（首选不可用时降级）> Playwright MCP `browser_evaluate`（仅 1+2 不可用或用户明确选择）> curl + UTF-8 JSON body file（最后兜底，须通过 PowerShell 调用）。**禁止裸 `node`、禁止用 Bash 执行 node**（`disallowed-tools` 已禁 `Bash(node *)`）；执行器在 PowerShell 可用时**不得**用 Playwright MCP 逐条执行。详见 `reference.md`「接口测试工具优先级」。
-
-### 二、批量测试执行 + Runner 三阶段
-
-0.1 通过后生成 `.harness/changes/<change-name>/runtime/api-test-runner.mjs`（按技术栈选择实现，Node runner 为一种实现，可按项目替换），通过**一次命令**（PowerShell + 执行器绝对路径）执行全部场景，输出 `api-test-results.json`，主会话只读 JSON。执行器必须按 **setup / test / cleanup** 三阶段：setup 失败时依赖场景标 🟡 BLOCKED，**不得用 null ID 继续请求**。绝对路径从 `runtime/preflight.json` 的 `executorPath` 读取，禁止 hardcode。详见 `reference.md`「批量测试执行器」「执行器三阶段模板」。
-
-### 三、请求体与测试数据
-
-请求体必须从数据契约 / 接口定义 / 真实样例生成，**禁止临场猜字段、禁止先跑失败接口再补**。测试数据用唯一前缀 `TEST_<change-name>_<timestamp>_<random>`；唯一约束字段必须随机或避让，避免冲突导致大面积 BLOCKED。详见 `reference.md`「请求体生成」「测试数据治理」。
-
-### 四、单元测试复用 + 写入 ledger
-
-Phase 1 前用 `harness_ledger.py diff-hash` 和 `can-reuse` 重算真实指纹。验证目标必须使用 profile key 的单一入口：`--project . --profile-input unitTest|unitTestFull --command <规范命令>`；声明 `--profile-input` 后不得同时传入另一套 `--files`。`record` 与 `can-reuse` 必须消费同一 profile target，由 CLI 推导 scope、coverage、规范命令与输入闭包。`npx vitest run` 与 `vitest run` 等包装差异由账本规范化，`safe runner` 等说明只能写 `--runner-command` 元数据。可复用则跳过；否则执行同一 profile 命令并只登记一条结果。增量测试记 `unitTest`，模块全量记 `unitTestFull`，API/浏览器分别记录。详见 `checklist.md` 与 ledger protocol。
-
-报告必须分开呈现“产品测试”与“工具维护”。`ownership.productPaths` 决定产品结论；`.cursor/.agents/.claude/.codebuddy` 的 Harness 投影、context-index 与安装状态变化只进入“工具维护”，不得单独把产品结果降为 WARN。已知升级使用明确文案“Harness 已从 <旧版本> 更新到 <新版本>”，不得写“无关漂移”。场景统计分别列出：已执行、待手工验收、已豁免、说明性、NOT_APPLICABLE；“未验证”必须只等于仍要求执行但尚未完成的场景数。
-
-### 五、命令与请求超时治理
-
-所有命令必须通过资源安全 Runner 设置「预期时长 + 超时上限」，超过预期必须输出一次状态行，**不得静默等待**。测试模块超时或退出时必须清理其进程树；`durationMs > 10000` → 🟡 SLOW，`> 30000` → ❌ TIMEOUT_RISK。详见 `reference.md`「命令与请求超时治理」。
-
-### 五-A、陈旧测试安全修复
-
-若测试编译或执行明确指向已移除/改名 API 的陈旧测试，且当前生产代码、已批准计划或可验证历史能唯一确定新契约，可仅修改测试并立即重跑该测试与目标测试，然后记录：
-
-```text
-python <skills-root>/scripts/harness_test_guard.py record --project . --change-dir ".harness/changes/<change-name>" --files "<精确测试文件路径，逗号分隔>" --reason stale-test-repair --json
-```
-
-普通新增/更新测试使用 `tdd-created` / `test-updated`。存在业务歧义或修复会触及生产代码时，记录 `BLOCKED_PREEXISTING` 并停止复用该验证，不得猜测或绕过。
-
-**禁止临时排除测试**：禁止 `.bak`/改名、移出测试目录、删除、禁用注解、构建 exclude、`skipTests`/`maven.test.skip` 充当测试通过证据；服务启动可在单元测试已独立通过后使用 `-Dmaven.test.skip=true` 避免重复编译测试，但不得据此声明测试通过。所有本轮新增、更新或安全修复且被忽略的测试必须写入 test-tracking manifest；仅执行、未修改的只读 ignored test 不获得 force-track 授权。
-
-### 六、服务启动 + 生命周期管理
-
-启动等待状态机：0–30s 每 2s 探测、30–120s 每 5s 探测、>120s 读日志判定；遇启动失败特征立即停。**Service Gate**：`harness_service.py ensure` 返回 `action=needs-user-decision`（用户自启服务占端口）时 **才** blocking user confirmation；AI 托管服务或端口空闲则自动继续，不询问。服务指纹（`moduleInputsHash`，来自 CLI `--files` ∪ `serviceStart.inputFiles`）+ `startCommandHash` + `profile` + `overlayPath` + 进程身份任一变化即 restart；**空输入被拒绝**，不生成可复用空指纹。测试结束默认清理 AI 启动的服务。详见 `reference.md`「服务决策门」。
-
-### 七、运行时配置叠加（不动 tracked 配置）
-
-禁止默认 Edit tracked 应用配置文件。默认运行时配置叠加（ASCII 绝对路径）；改 tracked 配置 → 默认拒绝，记 `decision` 事件（不 blocking user confirmation，报告 🟡 WARN）。详见 `reference.md`。
-
-### 八、Token 缓存与复用
-
-先读 `.harness/changes/<change-name>/runtime/credential-cache.json`（认证凭证缓存，按项目认证机制；token/SSO 为常见实现），本地轻量接口验证通过则复用，失败才走远程认证。接口测试执行器用 request context / 原生 HTTP 客户端直连本地 baseURL，**不得依赖浏览器当前页面 origin**。同一次流程内凭证刷新计数 > 1 → 🟡 WARN。**不得在报告/日志/对话总结中输出明文凭证**。详见 `reference.md`「认证凭证缓存与复用」。
-
-> ⛔ **验证码 = 硬停，不是待解的技术问题。** 登录响应出现 `验证码` / `captcha` / `blockPuzzle` / `slider` / `geetest` 等特征时，**禁止**编写或运行任何求解代码（图像匹配、OCR、打码平台、反编译服务端找容差均在禁止之列）。立即记 `apiTest=BLOCKED`，请用户手工把凭证写入 `runtime/credential-cache.json` 或临时关闭测试环境验证码，并提示 `.harness/config/harness-test-config.md` 的认证方式已过期。详见 `pitfalls.md` 规则 31。
-
-### 九、测试报告状态规则
-
-整体 ✅OK / 🟡WARN / ❌FAIL 三态；API 维度使用 `OK` / `PARTIAL` / `BLOCKED` / `NOT_RUN` / `FAIL` 五态。**不得把「5 PASS + 9 BLOCKED + 1 FAIL」写成 `apiTest=NOT_RUN`**，正确为 `apiTest=PARTIAL`。P0 场景 BLOCKED 不得仍 OK。详见 `reference.md`「结果分级规则」。
-
-### 十、关门检查（结束前强制执行）
-
-输出最终总结前必须执行 10 项：`git status --porcelain` / `git diff --stat` / `git diff --check`（失败→❌FAIL，必须 PowerShell-only）/ 明文敏感信息 / runtime 不提交 / 服务生命周期收尾 / 测试数据清理 / 执行器表完整 / 慢请求或超时 / 未清理+fallback+慢请求→至少 🟡WARN。详见 `checklist.md`「关门检查」、`reference.md`「关门检查」。
-
-### 十一、请求执行器 fallback 输出 + 性能统计
-
-报告必须区分四种执行器（接口测试执行器 / PowerShell batch / Playwright MCP browser_evaluate / curl），**不得笼统写"Playwright"**，不得把 "Playwright API 执行器" 与 "Playwright MCP browser_evaluate" 混写。报告必须含请求耗时统计表。详见 `reference.md`「请求执行器 fallback 输出」「输出格式」。
-
-## Output Format
-
-> 详细报告格式见 `reference.md` 的「输出格式」模板。
-
-测试报告保存到 `.harness/changes/<change-name>/reports/test/test-report-YYYYMMDD-HHmm.md`（时间戳区分多次运行），同时在控制台输出摘要。
-
-## 渐进披露
-
-- **Read `checklist.md`** 仅在 Phase 0 环境准备时 — 含 各项强制检查、0.1 命令执行模式 preflight、服务生命周期清单
-- **Read `reference.md`** 仅在执行接口测试时 — 含 API 测试执行方法、已知良好测试配置、运行时配置叠加、setup/test/cleanup 执行器模板、双格式错误码兼容
-- **Read `pitfalls.md`** 仅在遇到测试失败时 — 含所有踩坑规则（30 条，含 Bash 执行执行器 / 运行时配置叠加 / 唯一字段冲突 / 服务生命周期等）
-
-## 交互白名单
-
-本 skill **仅允许**以下 blocking user confirmation；其余默认值 + `decision` 事件：
-
-1. **Service Gate**：仅当 `harness_service.py ensure` 返回 `needs-user-decision`（用户进程占端口）时询问处理方式
-2. **资源密集型测试确认**：仅当发布/验收确实需要 `system` 或 `full` 档位，且用户尚未明确授权时询问；获得授权后传入 `--confirm-resource-intensive`
-
-## 执行日志
-
-`events.ndjson` 为唯一事实源（schema_version 3，兼容读取 v1/v2；`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止用 Write/Edit 直接维护**。直接修改的内容会在 `phase.end` 或 finalize 时被完整重建覆盖，属于数据丢失；需要保留的详情必须进入事件 `note`。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
-
-**`phase.start` 由 `harness_gate.py begin` 写，不要再手工追加一次。** 两条同 `run-id` 的
-`phase.start` 会让 `plan finalize` 以 `PHASE_START_DUPLICATE` 卡死，而且手工那次会先触发
-auto-seal、把正在开始的 attempt 封成 `RECOVERED`。要补触发指令说明就带 `--note` 跑 `gate begin`。
-（重复追加现已按 `(phase, run-id)` 判为幂等 no-op，但依赖它不如不写。）
-
-```powershell
-# 阶段开始：gate begin 负责，note 在这里给
-python <skills-root>/scripts/harness_gate.py begin --change-dir ".harness/changes/<change-name>" --phase <phase> --note "<触发指令>"
-# 阶段中的其他事件才用 append
-python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type <command|issue|verification> --run-id <phase-run-id> --note "<摘要>"
-```
-
-> **脚本接线**：`harness_events.py append`；`harness_archive.py finalize`；`harness_preflight.py check`；`harness_ledger.py can-reuse`；`harness_service.py ensure/stop`（须 `--files`/`serviceStart.inputFiles`）。JSON 输出按 D13 护栏解读。
-
-> **Task 4 §6.1 写入契约**：普通 `append` = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex` 无需去重扫描）。仅 `--type phase.end` append 在追加成功后渲染一次 `execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。高频 command append 期间 log 可能滞后，phase 边界保持最新。
-
-每个阶段的 `phase.start` 与对应 `phase.end` 必须复用同一 `--run-id` / `--attempt`；阶段结束必须写 `--status OK|WARN|FAIL|BLOCKED`。重试同一阶段时生成新的 run-id 并增加 `--attempt <n>`，不得覆盖或伪装成一次执行。**`attempt` 按 phase 全局递增，不是按 run-id**：一个 run-id 只绑定一个 attempt，重试必须「新 run-id ＋ 下一个 attempt」两者同时换，只换其一会撞 `EVENT_ATTEMPT_CONFLICT` 或 `PHASE_ALREADY_CLOSED`。已发布 plan 的修订通过重跑 `plan evidence-pack` + `plan finalize` 分配新 attempt（`harness_plan_finalize.py republish` 已于 0.3.0 移除）。
-
-阶段跑得久（plan/run 常见）时用 `harness_context.py renew --project . --change <cn> --executor <tool>` 续租；租约到期本身不再阻断 `close`（同一 owner 的过期租约不构成冲突，收据里记 `leaseLapsed`），但续租能让 `view` 的状态如实反映在跑。跨工具继续执行时写 `--executor-tool <codex|claude-code|codebuddy|cursor>`，并在接棒事件写 `--handoff-from-tool` / `--handoff-reason`；也可由 `HUNTER_HARNESS_TOOL/AGENT/MODEL/RUN_ID` 环境变量统一注入。
-> 片段：logging · phase=`test` · 事件：phase/command/verification/decision/issue/artifact

package/harness/bundles/java/cursor/harness-test/pitfalls.md

@@ -1,307 +0,0 @@
----
-description: harness-test 的踩坑规则（来自真实对话日志）。执行测试前必须通读，遇到测试失败时重新参考。
----
-
-# 避坑规则（32 条）
-
-> 以下规则来自真实对话日志（2026-06-12 ~ 08-17），每个都有明确的现象和根因。
-> 执行 `harness-test` 时必须通读，避免重蹈覆辙。
-
-| # | 规则 | 现象 | 根因 | 解法 |
-|:--:|------|------|------|------|
-| 1 | 凭证可展示但注意安全 | 对话日志记录了凭证 | Bearer 凭证被粘贴到聊天中 | 凭证可以在对话中展示用于调试，但不要写入持久化文件（测试报告、执行日志等） |
-| 2 | 不用 curl 发中文 | `Invalid UTF-8 start byte 0xb2` | Windows curl 默认 GBK 编码 | 用 PowerShell Invoke-WebRequest 或 Playwright fetch |
-| 3 | 必须带租户标识 | 所有接口 500，或 200 但 `data:null` | 租户上下文为空，或请求头租户值与测试数据行的租户不一致 | 请求头加租户标识（见 build-profile.httpHeaders）；**取值必须等于测试数据实际所属租户**，先查数据行的租户列再填，不要默认写 0 |
-| 4 | 认证降级 | 接口 401 "账号未登录" | 本地无认证服务 | 应用配置放行（如 permit-all-urls）或权限降级 |
-| 5 | 错误码双格式兼容 | 测试断言失败 | 预期 `1_003_002_009`，实际 `1003002009` | 自动兼容下划线和数字两种格式 |
-| 6 | 编译产物确认 | 修改代码后测试结果不变 | IDE 热重载未触发 | 测试前编译（如 `mvn compile -o`） |
-| 7 | 构建工具配置路径用相对 | 构建工具输出 `׻ֹ` 乱码 | 配置文件路径含中文 | 构建工具配置用相对路径（如 `.mvn/maven.config` 用 `-s ../settings.xml`） |
-| 8 | 跳过无关模块 | `mvn compile -am` 在无关子模块报错 | 子模块 POM 无 parent | 用 `-pl <module>` 不 `-am` |
-| 9 | 服务注册只发现不注册 | 线上流量被路由到本地 | register-enabled=true | 确认服务注册开关关闭（如 `register-enabled=false`） |
-| 10 | 先导航再 fetch | `fetch is not defined` | 页面是 about:blank | 先 `browser_navigate` 到服务页面 |
-| 11 | MCP 就绪等待 | `No such tool available` | 服务器仍在连接 | 等 MCP 连接完成再调用 |
-| 12 | 大请求体分批 | `Range of input length [1, 202745]` | 上下文超 API 输入限制 | 超过 200KB 时分批 |
-| 13 | 必填字段先查明 | 创建资源 500 | 不知道必填字段有哪些 | 查看已有代码或数据契约定义 |
-| 14 | 用唯一编码 | 编码冲突错误 | 之前测试已创建同名编码 | 每个用例使用唯一编码，测试后清理 |
-| 15 | permit-all 放行 ≠ 有用户上下文 | 接口返回 500 "系统异常" | 安全层放行但业务层调用权限校验时当前用户为 null | 获取真实凭证带上，或跳过需要用户上下文的接口 |
-| 16 | 远程认证服务获取凭证 | 本地无独立认证服务，无法登录 | 应用服务不提供登录接口 | 通过远程认证服务（如 SSO/Gateway）登录获取凭证，或从项目配置文件中读取已知凭证 |
-| 17 | Windows 禁用 Python3 解析 JSON | 凭证提取静默失败，后续所有请求未认证 | Windows 环境 Python3 可能段错误（segfault） | 用 `grep -o + cut` 或 PowerShell `ConvertFrom-Json` 替代 |
-| 18 | **Bash 不可执行执行器（如 node）** | "Bash 中没有 node" → 错误降级到 Playwright MCP | Windows 中文路径项目下 Bash 被 hook 拒；Node 不在 Bash PATH | 强制 `powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "& '<executorPath>' '...mjs'"`，禁止裸 `node`、禁止用 Bash 执行执行器 |
-| 19 | **Auto mode / 安全分类器降级时静默等待** | 接口测试长时间无响应，最终错误降级到逐条 MCP | PowerShell 命令被安全分类器拦截，Claude 静默重试 + fallback | Phase 0.1 preflight 检测出后**硬停**，原文输出"命令执行模式不可用..."，提示用户切换权限模式 |
-| 20 | **Playwright API 执行器与 Playwright MCP 混写** | 报告写"Playwright ✅ 使用"，实际是逐条 `browser_evaluate` | 两者被笼统称为"Playwright" | 报告中**强制区分**四种执行器：接口测试执行器 / PowerShell batch / Playwright MCP browser_evaluate / curl |
-| 21 | **直接 Edit tracked 应用配置文件** | 测试期间改配置，之后又还原，diff 噪声大 | 把运行时配置覆盖直接写进 tracked 文件 | 生成 ASCII 运行时配置叠加 `C:/temp/harness-test-overlay/<change>/application-harness-test.yml`，启动用该绝对路径叠加（如 `-Dspring.config.additional-location=...`） |
-| 22 | **唯一约束字段与本地预存数据冲突** | 大面积唯一约束冲突，9 个场景 BLOCKED | 执行器用硬编码字段值 | 用随机值（如 `900000 + random`）/ 先查避让 / 用唯一隔离值 |
-| 23 | **setup 失败后继续用 null ID 发送请求** | 后续 9 个接口全部 400/500，掩盖真正问题 | 执行器不区分 BLOCKED 状态 | 执行器强制 setup/test/cleanup 三阶段，依赖未满足 → 标 🟡 BLOCKED，**不发起请求** |
-| 24 | **归档数据把 PARTIAL 写成 NOT_RUN** | 平台显示「未执行」，但实际跑了 6 个场景 | 状态枚举不完整，只有 OK/FAIL/NOT_RUN | API 维度状态使用 OK/PARTIAL/BLOCKED/NOT_RUN/FAIL，5 PASS+9 BLOCKED+1 FAIL → `apiTest=PARTIAL` |
-| 25 | **AI 启动的服务测试结束不关闭** | 端口长期占用，下次启动端口占用异常（如 `BindException`） | 没有 service lifecycle 管理 | 通过 `service.pid` + `serviceState` 区分，AI_STARTED 默认 Stop-Process，**即使测试失败也 finally 清理** |
-| 26 | **凭证在同一流程内重复获取** | 浏览器 origin 在认证服务就再走一次登录 | 执行器依赖浏览器当前页面 origin | 执行器用 request context 直连本地 baseURL，凭证从 cache 读，`credentialRefreshCount > 1` → 🟡 WARN |
-| 27 | **服务启动盲等 + 无反馈** | 等待 90s 后才发现启动报错 | 没有启动状态机和异常关键字检测 | 0–30s/2s × 30–120s/5s 状态机；遇启动失败特征（按技术栈，如 BindException/Could not resolve placeholder/BeanCreationException）立即停；> 10s 必须输出一次状态行 |
-| 28 | **已有服务未先决策就跑业务接口** | 旧服务不含新代码，接口 500 后才发现版本不匹配 | 检测到已有应用服务（端口被占）后，未先展示服务决策门就跑业务接口 | 先展示服务决策门，询问复用/重启/跳过/停止；询问前只允许 health/meta 检查 |
-| 29 | **启动命令反复试相对配置叠加 / 中文路径** | 相对路径或中文路径导致应用读不到运行时配置叠加，启动失败 | 默认只用 `C:/temp/harness-test-overlay/<change>/application-harness-test.yml` ASCII 绝对路径，并固化已知良好测试配置 |
-| 30 | **伪 diffHash 导致错误复用** | `3files-84plus-5minus` 不能证明代码未变 | 用 `git diff --binary` 生成 patch 并计算 SHA-256，ledger 只认 `sha256:<hash>` |
-| 31 | **尝试破解验证码 / 人机验证** | 认证服务返回"验证码不能为空"，AI 写图像识别脚本反复试坐标（实测 28 次 / 4 种算法全失败） | 测试配置里的账号密码登录流程被加了滑块/图形验证码，配置未同步 | **硬停**。禁止编写或运行任何验证码求解代码；立即标 `apiTest=BLOCKED`，请用户手工提供凭证写入 `runtime/credential-cache.json`，或临时关闭测试环境验证码 |
-| 32 | **预存环境缺陷被当成本次变更的阻塞** | `unitTestFull` 144 个测试挂 1 个，根因是别人提交引入的缺省配置缺失 | 全量验证把预存缺陷和本次 diff 混在一起判定 | 先用 `git log -S` + diff 触点证明与本次变更无关，再按「预存缺陷」上报并请用户决策（修根因 / 记 🟡WARN / 停止），**不得**擅自改 tracked 配置或排除测试 |
-
-
-## 详细说明
-
-### 规则 1：凭证可展示但注意安全
-**严重度**：🟡WARN
-**场景**：测试脚本需要 Bearer 凭证时，需要在对话中展示用于调试
-**正确做法**：凭证可以在对话中展示用于调试和验证。但不要将凭证写入持久化文件（测试报告、执行日志、代码注释等）。测试报告中引用凭证时用前 8 位 + `***` 脱敏。
-
-> 凭证处理遵循 `../protocols/sensitive-info-protocol.md`。
-
-### 规则 2：不用 curl 发中文
-**严重度**：❌FAIL
-**场景**：用 `curl -d '{"name":"张三"}'` 测试接口
-**后果**：Windows curl 默认 GBK 编码，服务器期望 UTF-8，导致 `Invalid UTF-8 start byte 0xb2`
-**正确做法**：用 PowerShell `Invoke-WebRequest` 或 Playwright MCP 的 `browser_evaluate` + `fetch`
-
-### 规则 3：必须带租户标识
-**严重度**：❌FAIL
-**场景**：忘记在请求头中加租户标识
-**后果**：租户上下文为空，所有接口返回 500，错误信息不直观，容易误判为权限问题
-**正确做法**：所有 HTTP 请求头使用 build-profile 的 `httpHeaders`（项目自定义）
-
-### 规则 4：认证降级
-**严重度**：🟡WARN
-**场景**：本地测试时收到 401 "账号未登录"
-**后果**：无法测试需要认证的接口
-**正确做法**：在应用配置文件中配置放行（如 `permit-all-urls`），或降级为高权限账号上下文。测试完成后还原配置。
-
-### 规则 5：错误码双格式兼容
-**严重度**：🟡WARN
-**场景**：测试断言预期 `1_003_002_009`，实际返回 `1003002009`
-**后果**：断言失败，误判为 Bug
-**正确做法**：自动兼容两种格式，比较时统一去掉下划线
-
-### 规则 6：编译产物确认
-**严重度**：🟡WARN
-**场景**：修改代码后运行测试，结果不变
-**后果**：IDE 热重载未触发，测试运行的是旧产物，浪费排查时间
-**正确做法**：测试前执行构建工具编译（如 `mvn compile -o`）确保编译产物最新
-
-### 规则 7：构建工具配置路径用相对
-**严重度**：🟡WARN
-**场景**：构建工具配置文件路径包含中文（如 Maven 的 settings.xml）
-**后果**：构建工具输出乱码字符 `׻ֹ`，编译失败
-**正确做法**：构建工具配置中使用相对路径（如 Maven 的 `.mvn/maven.config` 中 `-s ../settings.xml`）
-
-### 规则 8：跳过无关模块
-**严重度**：🟡WARN
-**场景**：构建工具编译带依赖模块（如 `mvn compile -am`）在无关子模块报错
-**后果**：被不相关的编译错误阻塞
-**正确做法**：只编译目标模块（如 Maven 用 `-pl <module>` 指定模块，不 `-am`）
-
-### 规则 9：服务注册只发现不注册
-**严重度**：❌FAIL
-**场景**：本地启动服务，服务注册开关开启（如 Spring Cloud Nacos 的 `register-enabled=true`）
-**后果**：线上流量可能被网关路由到本地机器
-**正确做法**：确认服务注册开关关闭（如 `spring.cloud.nacos.discovery.register-enabled: false`）
-
-### 规则 10：先导航再 fetch
-**严重度**：🟡WARN
-**场景**：直接调用 Playwright MCP 的 `browser_evaluate` 执行 fetch
-**后果**：`fetch is not defined`，因为页面是 about:blank
-**正确做法**：先 `browser_navigate` 到服务的任意页面，再执行 fetch
-
-### 规则 11：MCP 就绪等待
-**严重度**：🟡WARN
-**场景**：刚启动 Claude Code 就调用 MCP 工具
-**后果**：`No such tool available`，MCP 服务器仍在连接中
-**正确做法**：等待几秒确认 MCP 连接完成后再调用
-
-### 规则 12：大请求体分批
-**严重度**：🟡WARN
-**场景**：请求体超过 200KB
-**后果**：超出 API 输入限制，请求被截断
-**正确做法**：超过 200KB 时分批发送
-
-### 规则 13：必填字段先查明
-**严重度**：🟡WARN
-**场景**：创建资源时 500 错误
-**后果**：不知道必填字段有哪些，反复试错
-**正确做法**：查看已有代码中的请求示例或数据契约定义，确认必填字段
-
-### 规则 14：用唯一编码
-**严重度**：🟡WARN
-**场景**：多个测试用例使用相同编码
-**后果**：编码冲突错误，后续用例失败
-**正确做法**：每个用例使用唯一编码（加时间戳后缀），测试完成后清理
-
-### 规则 15：permit-all 放行 ≠ 有用户上下文
-**严重度**：❌FAIL
-**场景**：在应用配置文件中配置了放行（如 `permit-all-urls`），接口返回 200 但业务逻辑报 500 "系统异常"
-**后果**：安全框架（如 Spring Security）放行了请求，但安全工具获取当前用户返回 null。业务层调用权限校验方法时，内部远程调用失败，错误信息不直观
-**正确做法**：理解两层检查机制——安全层（Filter）和业务层（Service）是独立的。放行只跳过第一层，第二层仍需要有效的用户上下文。要么获取真实凭证带上，要么跳过需要用户上下文的接口
-
-### 规则 16：远程认证服务获取凭证
-**严重度**：❌FAIL
-**场景**：本地启动应用服务，自身不提供登录接口，无法获取访问凭证
-**后果**：所有需要认证的接口返回 401，无法测试
-**正确做法**：通过远程认证服务（如 SSO/Gateway）的登录接口获取凭证。查看项目配置文件（`harness-test-config.md`）中的登录端点和测试账号。如果项目配置不存在，询问用户如何获取有效的凭证
-
-### 规则 17：Windows 禁用 Python3 解析 JSON
-**严重度**：❌FAIL
-**场景**：用 Python3 解析 curl 返回的 JSON（如提取凭证）
-**后果**：Windows 环境 Python3 可能段错误（segfault），导致脚本静默失败，后续所有依赖该输出的命令全部异常（如凭证为空导致所有请求未认证）
-**正确做法**：用 PowerShell `Invoke-RestMethod` + `ConvertFrom-Json` 替代（推荐）：
-```powershell
-# 推荐：PowerShell Invoke-RestMethod + ConvertFrom-Json（经 Bash(powershell.exe:*) 通道或直接 PowerShell）
-$resp = Invoke-RestMethod -Uri '...' -Method Post -Headers @{...} -Body '...'
-$cred = $resp.data.accessToken
-```
-
-> **反例（禁止）**：以下 Bash + curl + grep + cut 方式违反 PowerShell-first 规则，不得使用：
-> ```bash
-> # ❌ 禁止：裸 Bash + curl + grep + cut（Windows 中文路径 + GBK 编码双重风险）
-> CRED=$(curl -s ... | grep -o '"accessToken":"[^"]*"' | cut -d'"' -f4)
-> ```
-
-### 规则 18：Bash 不可执行执行器（如 node）
-**严重度**：❌FAIL
-**场景**：日志显示 PowerShell 中确认了执行器可用，但接着错误地用 Bash `node api-test-runner.mjs` 执行，失败后直接降级到 Playwright MCP 逐条执行接口
-**后果**：浪费 1–2 分钟在错误降级路径上；接口测试以"Playwright"名义被逐条执行，丧失批量执行器的所有优势
-**正确做法**：硬规则——禁止裸 `node`、禁止用 Bash 执行执行器；必须 `powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "& '<executorPath>' '...mjs'"`，`<executorPath>` 从 0.1 preflight 写入的 `preflight.json` 读取
-
-### 规则 19：Auto mode / 安全分类器降级时静默等待
-**严重度**：❌FAIL
-**场景**：Claude Code 在 Auto mode / 安全分类器临时不可用时，PowerShell 命令被拦截，Claude 静默重试、静默 fallback，最终接口测试卡住很久
-**后果**：用户体验极差，错误降级到逐条 MCP，最终报告里"Playwright"✅ 使用但实际是 fallback
-**正确做法**：Phase 0.1 preflight 检测出以下任一情况立即**硬停**：
-- 出现"安全分类器暂时不可用"
-- Auto mode 导致 PowerShell 命令不可执行
-- PowerShell 被拒
-- PowerShell 可用但执行器/构建工具不可执行
-
-输出原文："❌ 命令执行模式不可用：PowerShell/接口测试执行器无法稳定执行。请切换 Claude Code 权限模式..."；用户确认后重试 ≤ 1 次
-
-> 结果状态分级与硬停判定遵循 `../protocols/evidence-based-reporting-protocol.md`。
-
-### 规则 20：Playwright API 执行器与 Playwright MCP 混写
-**严重度**：🟡WARN
-**场景**：报告写"Playwright ✅ 使用"，实际是 Playwright MCP `browser_evaluate` 逐条执行
-**后果**：审计混乱，看不出真实降级路径
-**正确做法**：报告中**强制区分**四种执行器，且不得用一个"Playwright"代指两者：
-- `接口测试执行器` (`.mjs`)
-- `PowerShell batch runner` (`.ps1`)
-- `Playwright MCP browser_evaluate`
-- `curl`
-
-### 规则 21：直接 Edit tracked 应用配置文件
-**严重度**：🟡WARN
-**场景**：测试期间为了切换外部服务配置直接 Edit tracked 配置文件（如 `application-local-dev.yml`），测试后再还原，留下 diff 噪声
-**后果**：git diff --stat 出现意外文件、提交风险、误以为有业务变更
-**正确做法**：生成运行时配置叠加 `.harness/changes/<change>/runtime/application-harness-test.yml`（不提交），启动用 `-Dspring.config.additional-location=file:...` 叠加（按技术栈）；如必须改 tracked 配置，先 blocking user confirmation，最终报告至少 🟡 WARN
-
-### 规则 22：唯一约束字段与本地预存数据冲突
-**严重度**：❌FAIL
-**场景**：执行器创建资源时唯一约束字段用硬编码值（如 `priority=1`），与本地已存在数据冲突，导致 9 个依赖该资源的场景全部 BLOCKED
-**后果**：API 测试出现大面积 BLOCKED，且容易误判为代码 Bug
-**正确做法**：所有创建类接口对唯一约束字段三选一：
-1. 随机：`900000 + Math.floor(Math.random() * 9999)`
-2. 先查再避让
-3. 用唯一隔离值隔离
-
-### 规则 23：setup 失败后用 null ID 继续请求
-**严重度**：❌FAIL
-**场景**：执行器没有阶段化，`createResource` 失败后 `resourceId=null`，但仍用 null 继续请求 9 个后续接口
-**后果**：后续接口大面积 400/500，掩盖真正的根因（setup 失败）
-**正确做法**：执行器强制 setup/test/cleanup 三阶段；依赖 setup 数据的场景在 test 阶段开头判定依赖，缺失则标 🟡 BLOCKED，**不发起请求**
-
-### 规则 24：归档数据把 PARTIAL 写成 NOT_RUN
-**严重度**：🟡WARN
-**场景**：15 个 API 场景中 5 PASS + 9 BLOCKED + 1 FAIL，`summary-data.json` 却写成 `apiTest=NOT_RUN`，导致平台错误显示为「未执行」。
-**后果**：报告与现实不符，下游 review / submit / package 误判
-**正确做法**：API 维度状态使用 5 个值：`OK / PARTIAL / BLOCKED / NOT_RUN / FAIL`。"部分执行+部分阻塞" 是 `PARTIAL`，附说明：`apiTest=PARTIAL — 15 个场景中 5 个 PASS, 9 个 BLOCKED, 1 个 FAIL`
-
-> 结果状态枚举与证据要求遵循 `../protocols/evidence-based-reporting-protocol.md`。
-
-### 规则 25：AI 启动的服务测试结束不关闭
-**严重度**：❌FAIL
-**场景**：选择 AI 启动服务，测试结束后忘记 Stop-Process，端口被长期占用；下次启动端口占用异常（如 `BindException`）
-**后果**：端口被占、内存浪费、下次启动失败
-**正确做法**：维护 `service.pid` + `serviceState`：
-- `AI_STARTED` → 默认 Stop-Process 并删除 pid 文件
-- `USER_STARTED` → 不动，只提示
-- `REUSED_EXISTING` → 不动，除非用户确认
-
-即使测试失败，也必须进入 finally 清理 AI_STARTED 服务
-
-### 规则 26：凭证在同一流程内重复获取
-**严重度**：🟡WARN
-**场景**：执行器因为浏览器当前 origin 在远程认证服务，就重新走一次认证登录获取凭证，覆盖了刚拿到的有效凭证
-**后果**：浪费一次认证调用（10+ 秒），且暴露低效流程的根本误解（凭证是独立凭证，不依赖浏览器 origin）
-**正确做法**：执行器用 `request.newContext({ baseURL: 本地 })` 或原生 HTTP 客户端直连本地 baseURL；凭证从 `credential-cache.json` 读，本地轻量接口验证；同一次流程内 `credentialRefreshCount > 1` → 🟡 WARN，原因要写入报告
-
-### 规则 27：服务启动盲等 + 无反馈
-**严重度**：🟡WARN
-**场景**：选择 AI 启动后默认每 30 秒检查一次健康，等 90 秒才发现启动失败（如配置缺失导致 `Could not resolve placeholder`）
-**后果**：启动反馈滞后，节奏极慢
-**正确做法**：启动状态机——0–30s 每 2s/30–120s 每 5s 探测；> 10s 必须输出一次状态行；遇到启动失败特征（按技术栈识别，如 Java Spring Boot 的 `BindException` / `Could not resolve placeholder` / `Connection refused during bean init` / `BeanCreationException` / `Failed to start bean` / `BUILD FAILURE`）立即停止等待
-
-### 规则 28：已有服务未先决策就跑业务接口
-**严重度**：❌FAIL
-**场景**：检测到已有应用服务进程（端口被占），未先展示服务决策门，直接调用业务接口
-**后果**：旧服务不含新代码，接口 500 后才发现版本不匹配，浪费时间分析业务数据，掩盖根因（服务版本/配置不匹配）
-**正确做法**：检测到已有服务后，先展示服务决策门（pid/profile/startTime/commandLine/fingerprint/源码是否晚于服务启动时间），询问复用/重启/跳过/停止。询问前只允许 health/meta 检查。只有 service-fingerprint 与当前真实 diffHash/profile/sdkUrl/startCommandHash 完全匹配时才允许自动复用。
-
-### 规则 29：启动命令反复试相对配置叠加 / 中文路径
-**严重度**：🟡WARN
-**场景**：运行时配置叠加用相对路径 `.harness/changes/<change>/runtime/application-harness-test.yml` 或中文路径作为 JVM `additional-location`，应用（如 Spring Boot）读不到配置叠加，启动失败后反复试不同路径
-**后果**：启动反复失败，浪费时间；中文路径进入 JVM 参数也可能失败
-**正确做法**：默认只用 ASCII 绝对路径 `C:/temp/harness-test-overlay/<change-name>/application-harness-test.yml`，并固化已知良好测试配置。禁止把相对路径作为默认 JVM `additional-location`。
-
-### 规则 30：伪 diffHash 导致错误复用
-**严重度**：❌FAIL
-**场景**：ledger 的 diffHash 用描述性文本如 `3files-84plus-5minus`，无法证明代码未变，却据此复用 run 的 unitTest/apiTest 结果
-**后果**：代码已变却复用旧测试结果，掩盖回归问题
-**正确做法**：用 `git diff --binary` 生成 patch 并计算 SHA-256，ledger 只认 `sha256:<hash>` 格式。diffHash 不一致时必须重跑相关测试。
-
-### 规则 31：尝试破解验证码 / 人机验证
-**严重度**：❌FAIL（硬性禁止）
-**场景**：本地服务已起来，但业务接口需要真实登录上下文；认证服务登录接口返回 `验证码不能为空` / 返回滑块拼图（如 AJ-Captcha `blockPuzzle`）/ 图形验证码 / 短信验证码
-**后果**：真实日志里 AI 连续写了 4 版求解算法（边缘求和 → NCC 模板匹配 → 二维边缘匹配 → 一维归一化互相关）、反编译服务端 jar 找容差、共 28 次尝试全部失败，烧掉整段会话，最终仍然 BLOCKED
-**正确做法**：**验证码是安全控制，不是待调试的技术问题。** 一旦识别到验证码/人机验证：
-
-1. **立即停止**，不得编写、下载或运行任何验证码求解代码（图像匹配、OCR、打码平台、反编译校验逻辑找容差都在禁止之列）
-2. 该维度记 `apiTest=BLOCKED`，受影响场景标 🟡 BLOCKED，**不得**伪造 receipt 或把未执行写成通过
-3. 向用户输出原文，并给出三条可选出路：
-   - 用户手工登录后把凭证写入 `.harness/changes/<change-name>/runtime/credential-cache.json`（推荐，执行器本来就先读 cache）
-   - 用户在测试环境临时关闭验证码开关，AI 重跑
-   - 本轮跳过接口验证，按 BLOCKED 归档，留待环境就绪
-4. 顺手提示更新 `.harness/config/harness-test-config.md`——认证方式已变更，配置已过期
-
-> 判据：只要登录响应里出现 `验证码` / `captcha` / `blockPuzzle` / `slider` / `geetest` / `secretKey + originalImageBase64` 任一特征，即触发本规则。
-
-### 规则 32：预存环境缺陷被当成本次变更的阻塞
-**严重度**：🟡WARN
-**场景**：模块全量验证（如 `unitTestFull`）失败，但失败点在本次 diff 之外——例如别人提交的类新增了无默认值的配置占位符，导致某个全上下文测试无法加载
-**后果**：要么误判成自己的回归浪费时间排查，要么擅自改 tracked 配置 / 排除测试把问题掩盖掉，污染 diff
-**正确做法**：
-
-1. **先证明无关**：`git log -S '<符号>' --oneline` 定位引入提交 + `git diff` 证明本次触点不涉及该文件/目录，两条证据都要有
-2. **再上报**：按「预存缺陷」向用户说明——受影响模块、失败文件、引入提交、不阻断依据
-3. **由用户决策**：修根因（会扩大 diff，需明确点头）/ 记 🟡WARN 继续 / 停止本轮
-4. **禁止自作主张**：不得改 tracked 配置文件、不得 `-Dtest=` 排除失败测试、不得偏离 build-profile 的规范命令——这些都会让证据与 ledger 命令不一致
-
-> 用户批准修复后，该修复文件即进入本次 diff：必须在提交前复核它仍在工作区（真实日志里用户中途手工还原了该修复，AI 直到 staging 才发现）。
-
-> diffHash/ledger 复用规则遵循 `../protocols/ledger-protocol.md`；结果证据要求遵循 `../protocols/evidence-based-reporting-protocol.md`。
-
-## BOM-safe JSON / identifier sanitizer / 凭据扫描 (runtime-helpers.mjs)
-
-> 变更簇 5 (spec §3.4)：Node runtime helper 集中处理 PS5.1 BOM、非法测试标识符、凭据边界三类返工。源码 `scripts/runtime-helpers.mjs`，测试 `scripts/tests/runtime-helpers.test.mjs`（`node --test`）。
-
-| 函数 | 用途 | 规避的坑 |
-|------|------|----------|
-| `readJsonUtf8BomSafe(path)` | 读 credential-cache.json / api-test-results.json，容忍 U+FEFF BOM | PS5.1 `Out-File -Encoding utf8` 写入 BOM 导致 `JSON.parse` 失败 |
-| `writeJsonUtf8NoBom(path, value)` | 原子写 (temp+rename)，UTF-8 no BOM，LF，2-space 缩进 | 结果文件被 BOM/换行符污染破坏字节稳定；半写入文件被并发读到 |
-| `sanitizeTestIdentifier({name, pattern, maxLength, prefix})` | change-name → 稳定标识（清洗非法字符 + 超长截断 + 原文名短 hash 防碰撞） | 中文/连字符/超长 change-name 生成非法 identifier 触发服务端 400 |
-| `validateRunnerPayload(payload, {identifierPattern})` | Runner 生成前本地校验 payload schema/必填/identifier/重复 id，返回结构化错误码 | 测试脚本错误（缺字段/非法 id）直到请求服务后才暴露，返工成本高 |
-| `findCredentialValues(text)` | 扫描 profile/Markdown/docs 中的凭据明文值（password/token/secret/Authorization/jdbc password），占位符 `<*_REDACTED>` 与 env 引用 `${ENV}`/`$ENV` 不报 | profile/规则文档误含明文凭据被发布 |
-
-**Runner 生成前强制**（spec §3.4 point 3）：生成 `api-test-runner.mjs` 前用 `validateRunnerPayload` 校验全部场景；`ok=false` → 修复脚本错误，**不得带错请求服务**。场景 id 用 `sanitizeTestIdentifier` 生成（Build Profile v3 `identifier.pattern/maxLength/prefix` 已声明）。
-
-**凭据边界**（spec §3.4 point 4）：credential 配置只含 env key（如 `${TEST_TOKEN}`）、cache path、角色，不含值。发布前用 `findCredentialValues` 扫 profile/规则/Markdown，命中即 ❌FAIL。详见 `../protocols/sensitive-info-protocol.md` §6。