ln-316-review-refinement-worker

路径： 文件路径（references/、../ln-*）均相对于此技能目录。

类型： L3 Worker
类别： 3XX 规划

Review Refinement Worker

必须阅读

必须阅读： 加载 references/evaluation_worker_runtime_contract.md、references/evaluation_summary_contract.md、references/refinement_trace_contract.md、references/cleanup_evidence_contract.md
必须阅读： 加载 references/agents/prompt_templates/iterative_refinement.md、references/agents/prompt_templates/refinement_perspectives.md
必须阅读： 加载 references/monitor_integration_pattern.md、references/agent_review_workflow.md（步骤：迭代优化）

用途

• 合并后使用 agent_runner.mjs 通过非宿主顾问 Agent 运行两阶段优化
• 阶段 1：3 个并行且独立的顾问会话（dry_run_executor、new_dev_tester、adversarial_reviewer）
• 阶段 2：合并阶段 1 的结果后，运行 1 个按顺序执行的顾问会话（final_sweep）
• 为每个顾问会话记录优化追踪和清理证据

关键：优化阶段会在外部启动顾问。请勿在此阶段使用宿主原生子 Agent。

运行时

运行时系列：

• evaluation-worker-runtime

必需的清单字段：

• identifier
• phase_order
• summary_kind=review-refinement
• operation=refinement

建议的 phase_order：

1. PHASE_0_CONFIG
2. PHASE_1_STAGE1_PARALLEL
3. PHASE_2_STAGE2_FINAL_SWEEP
4. PHASE_3_WRITE_SUMMARY
5. PHASE_4_SELF_CHECK

优化状态机

关键：独立会话

每个视角都必须通过单独的 node agent_runner.mjs --agent {advisor_agent} 调用来运行。
请勿将多个视角合并到同一个顾问提示词或会话中。
每个 iter{N}/ 子目录都对应一个拥有独立 PID 的顾问进程。

视角分类

阶段	视角	执行方式	用途
1	dry_run_executor	并行	找出无法执行的步骤和顺序错误
1	new_dev_tester	并行	找出隐性知识缺口和未定义术语
1	adversarial_reviewer	并行	找出必然失败和静默损坏
2	final_sweep	合并后	找出回归问题以及与阶段 1 修复内容的偏离

所有 4 个视角都是必需的。不包含 generic_quality——它由第 2 阶段的顾问审查（review_base.md + 模式模板）涵盖。

第 1 阶段：并行专项评审

1. 构建待评审产物： 读取待评审产物的当前状态（Story+Tasks / 计划文件 / 上下文文档）。
2. 并行处理 3 个视角中的每一个： a. 从 refinement_perspectives.md 中加载与视角名称匹配的视角。 b. 构建提示词：填入 iterative_refinement.md 中的占位符（{artifact_type}、{artifact_content}、{project_context}、{review_perspective}、{iteration_number}、{max_iterations}、{previous_findings_summary}）。 c. 将提示词保存到 .hex-skills/agent-review/refinement/{identifier}/iter{N}/prompt.md
   • iter1/ = dry_run_executor
   • iter2/ = new_dev_tester
   • iter3/ = adversarial_reviewer d. 启动独立顾问进程：

   node references/agents/agent_runner.mjs --agent {advisor_agent} \
     --prompt-file .hex-skills/agent-review/refinement/{identifier}/iter{N}/prompt.md \
     --output-file .hex-skills/agent-review/refinement/{identifier}/iter{N}/result.md \
     --cwd {project_dir}
   

3. 通过运行时 sync-agent 等待 3 个进程全部完成；Claude 主机可使用 Monitor 进行可观测性检查（见下方“等待”部分）。
4. 解析结果： 从每个已完成会话的 ## Structured Data 部分提取 JSON。
5. 合并发现： 按（area、issue）去重，保留置信度较高的发现。
6. 分类： HIGH（impact_percent >= 20%）、MEDIUM（10-19%）、LOW（< 10%）。
7. 对每项接受的修复执行架构门禁：“这是否直接实现了正确的架构，而不使用向后兼容垫片？”
8. 应用接受的修复。
9. 终止全部 3 个进程： 对每个会话运行 node agent_runner.mjs --verify-dead {pid}。Windows 上必须执行。
10. 记录清理证据： 对每个会话按照 cleanup_evidence_contract.md 记录。
11. 为第 2 阶段构建 {previous_findings_summary}。

如果 3 个顾问会话全部失败 → EXIT(ERROR)，跳过第 2 阶段。 如果部分会话失败 → 使用可用结果继续，并记录部分错误。

第 2 阶段：最终检查

1. 构建待评审产物： 读取第 1 阶段修复后的状态。
2. 从 refinement_perspectives.md 加载 final_sweep 视角。
3. 使用第 1 阶段的 {previous_findings_summary} 构建提示词。
4. 将提示词保存到 .hex-skills/agent-review/refinement/{identifier}/iter4/prompt.md。
5. 启动顾问（单个独立会话）。
6. 通过运行时 sync-agent 等待；Claude 主机可使用 Monitor 进行可观测性检查。
7. **解析结果，**应用任何接受的修复（对每项修复执行架构门禁）。
8. **终止进程，**记录清理证据。

等待顾问结果（必须执行）

在解析或执行合并门禁之前，使用当前运行时的 sync-agent 命令。Monitor 仅是 Claude Code 中可选的可观测性工具。

对每个已启动的顾问进程：

在 Claude Code 下运行时，可选的可观测性检查：

Monitor(command="tail -f {agent_log} | grep --line-buffered -E 'Phase|ERROR|DONE'", timeout_ms=120000, description="advisor refinement {perspective_name}")

每次 sync/monitor 循环后：

• 检查结果文件中是否存在 `` 标记。
• 存在标记 → 解析结果并继续。
• 不存在标记，且日志持续增长 → 继续运行时 sync 或可选的 monitor 循环。
• 不存在标记，且日志超过 3 分钟未更新 → 运行存活性协议（见 agent_review_workflow.md）。

不要将 sleep 或手动轮询文件状态作为主要等待机制。

进程清理

每次顾问调用后（两个阶段均适用）：

1. 从运行器标准输出或元数据中提取 pid。
2. 运行 node references/agents/agent_runner.mjs --verify-dead {pid}。
3. 按照 cleanup_evidence_contract.md 记录清理证据。
4. 如果不终止，Windows 上的 CLI 顾问进程可能会不断累积。

退出状态

状态	含义
COMPLETED	两个阶段均已完成，所有结果均已合并
PARTIAL_ERROR	第 1 阶段有失败，但第 2 阶段已完成
ERROR	第 1 阶段的所有顾问会话均失败（已跳过第 2 阶段）
SKIPPED	健康检查中没有可用的顾问

摘要

发出 summary_kind=review-refinement。

载荷必须包含：

• worker=ln-316
• status
• operation=refinement
• warnings

建议包含以下字段：

• stages_completed（整数：1 或 2）
• exit_reason（枚举：COMPLETED、PARTIAL_ERROR、ERROR、SKIPPED）
• applied（整数：所有阶段中应用的建议总数）
• architecture_gate_rejections（拒绝次数）
• stage1_perspectives（已完成视角名称列表）
• stage1_failed（失败视角名称列表）
• metadata.refinement_trace

完成标准

• 阶段 1：并行启动全部 3 个顾问会话
• 阶段 2：阶段 1 合并后启动 final_sweep
• 所有顾问均通过 agent_runner.mjs 启动（而非主机原生子 Agent）
• 等待时使用运行时 sync-agent；Claude Monitor 可用于可观测性，但并非必需
• 按照 refinement_trace_contract.md 记录优化跟踪信息
• 记录所有已启动进程的清理证据
• 写入 review-refinement 摘要
• 自检通过

版本： 2.0.0 最后更新： 2026-04-13