validator-help

/validator-help

基于证据诊断验证器的行为。此技能仅用于诊断——解释发生了什么以及原因，但不会自动修复问题。它依据运行时产物和 CLI 输出，而非源代码。

诊断工作流

每个诊断问题都按以下顺序处理：

1. 解析 log_dir：读取 .validator/config.yml 并提取 log_dir 字段（默认值：validator_logs）。以下所有日志路径均相对于 <log_dir>/。
2. 先检查被动证据：先读取文件，再运行命令。
   • <log_dir>/.debug.log — 带时间戳的事件日志（命令、门禁结果、状态变更、错误）
   • <log_dir>/.execution_state — JSON，包含 last_run_completed_at、branch、commit、working_tree_ref 和 unhealthy_adapters（适配器名称 → {marked_at, reason}）
   • <log_dir>/console.*.log — 每次运行的控制台输出（编号最大的是最新文件）
   • <log_dir>/check_*.log — 检查门禁输出
   • <log_dir>/review_*.json — 审查门禁结果及违规项（file、line、issue、fix、priority、status）
   • .validator/config.yml — 项目配置
3. 必要时获取主动证据：仅当被动证据不足以支持有把握的诊断时，才运行 CLI 命令。
4. 依据证据说明：明确区分已确认的发现和推断。

证据来源

来源	可确认的内容
.validator/config.yml	log_dir、base_branch、entry_points、cli.default_preference、max_retries、rerun_new_issue_threshold
<log_dir>/.debug.log	带时间戳的事件历史：已执行的命令、门禁结果、状态转换、错误
<log_dir>/.execution_state	上次成功运行的时间戳、当时的分支/提交、工作树暂存引用、不健康适配器的冷却状态
<log_dir>/console.*.log	每次运行迭代的可读输出
<log_dir>/check_*.log	检查门禁命令（如代码检查器、测试运行器等）的原始输出
<log_dir>/review_*.json	结构化审查违规项，包含文件、行号、问题、优先级和解决状态
<log_dir>/.validator-run.lock	锁文件（包含 PID）——仅在执行期间存在
<log_dir>/.ci-wait-attempts	CI 等待尝试计数器

CLI 命令速查

仅当被动证据不足时使用：

命令	使用时机
agent-validate list	查看已配置的门禁和入口点
agent-validate health	检查适配器的可用性和健康状态
agent-validate detect	查看哪些文件发生了变更，以及哪些门禁会适用
agent-validate validate	验证 config.yml 的语法和架构
agent-validate clean	归档当前日志并重置状态（具有破坏性——请先与用户确认）

路由逻辑

根据用户的问题，加载相应的参考文件以获取详细指导：

问题领域	参考文件
配置缺失、YAML 错误、配置不当、初始化问题	references/config-troubleshooting.md
检查失败、审查失败、no_changes、no_applicable_gates、重新运行模式	references/gate-troubleshooting.md
锁冲突、过期锁、并行运行、清理	references/lock-troubleshooting.md
适配器健康状况、缺少工具、使用限额、冷却	references/adapter-troubleshooting.md

如果问题涉及多个领域，请加载每个相关参考文件。

输出约定

每个诊断响应都必须包含以下部分：

诊断

清楚说明发生了什么以及原因。

证据

列出支持诊断的具体文件、观察到的字段值和命令输出。引用相关日志行或配置值。

置信度

以下其中一项：

• 高 — 直接证据充分支持该诊断
• 中 — 诊断很可能正确，但部分证据缺失或含糊
• 低 — 诊断基于推断，无法获取关键证据

在以下情况下调低置信度：

• .debug.log 或 .execution_state 缺失或为空
• 输出中引用的日志文件不存在
• 无法验证配置值
• CLI 命令失败或返回意外输出

后续步骤

为用户提供可执行的建议。如果置信度不是高，请建议补充哪些证据可以确认该诊断。

提交 Bug

完成诊断后，按照以下路由逻辑判断是否应提交 GitHub issue：

• 置信度高 + 指示存在 Bug（证据表明缺陷出在 agent-validator，而不是配置问题、用户错误或预期行为）：自动调用 validator-issue，并将 --auto-file <diagnosis summary> 作为参数。这会将诊断摘要作为 Bug 描述，并跳过交互式确认 — 展示草稿后立即提交 issue。
• 置信度高 + 不属于 Bug（诊断结论为配置问题、用户错误或预期行为）：不执行任何操作。不要调用 validator-issue。
• 置信度中 + 可能是 Bug（证据表明 validator 可能存在缺陷，但尚无定论）：询问用户：“这可能是 validator 的 Bug。要我提交 GitHub issue 吗？”如果用户确认，将诊断摘要作为 Bug 描述调用 validator-issue。如果用户拒绝，则退出，不提交 issue。
• 置信度低：不执行任何操作。不要询问用户，也不要调用 validator-issue。