eve-job-debugging

Eve 作业调试

仅通过 CLI 调试

只能通过 Eve CLI 调试。 这能复现客户端体验——客户端没有 kubectl 或主机访问权限。

所有调试功能都必须能通过 CLI 使用。如果你发现需要借助系统工具来诊断作业问题，说明 CLI 存在需要修复的缺口。

监控

• 使用 eve job follow <id> 实时查看日志。
• 使用 eve job wait <id> --timeout 300 --json 等待作业完成。
• 使用 eve job result <id> --format text 查看最新结果。

诊断

• 使用 eve job diagnose <id> 查看时间线和错误摘要。
• 使用 eve job show <id> --verbose 查看尝试次数和阶段。
• 使用 eve job dep list <id> 查看依赖阻塞情况。

单个作业的 Harness 覆盖项

调试意外的 Harness 行为时，应先怀疑单个作业的覆盖项，再怀疑 Agent 默认设置。作业可能带有创建时设置的内联覆盖项：

• --harness-override-file <path.json> — 内联 {harness, model?, reasoning_effort?, variant?, temperature?} 配置包，其优先级高于 harness_profile。
• --env-override KEY=VALUE（可重复）— 单个作业的环境变量值，可包含在启动时解析的 ${secret.KEY} 占位符。

这两个字段都会保存在作业记录（harness_profile_override、env_overrides）和每次尝试记录（harness_profile_source、harness_profile_hash）中。使用 eve job show <id> --json 检查，并查看尝试记录中的路由日志条目，确认解析后的 harness_profile_source（agent_default、string_ref、inline_override 或 workflow_template）。缺少 Secret 插值时会立即失败，并返回 error_code: missing_secret_override。

卡住的作业

编排器现在可以从 agent-runtime Pod 丢失的情况中自动恢复——这些情况不再会导致作业卡住：

• 执行期间 Pod 退出：recoverActiveJobsWithTerminatedAttempts 扫描会回收尝试已被外部终结的活动作业、释放限制器槽位并关闭工作流根节点。
• 优雅关停：agent-runtime 的 preStop 会将运行中的尝试标记为 pod_terminated，并将 Pod 状态设为 draining，避免新的路由请求分配到该 Pod。
• 过期恢复：覆盖所有受派者类型（而非仅 orchestrator），因此看门狗可以检测到分配给 Agent 的作业（例如 map-generator、pm-coordinator）。

如果作业仍显示为 active 且超过 5 分钟没有心跳，请运行 eve job diagnose <id> 并检查 Pod 状态——如果 Pod 处于 draining 状态或已缺失，下一轮扫描就会回收该作业。

环境门控和临时 Agent

环境门控（项目范围内的串行化）仅适用于操作作业（设置了 action_type：deploy、build、migrate）。仅携带 env_name 的临时 Agent 运行不再通过环境互斥锁进行串行化——现在同一环境中的多个临时作业可以并行运行。如果需要互斥，请显式添加 action_type。

多次尝试的 Agent 运行

每次尝试进入终态（成功、失败、编排器错误）时，编排器都会发出 system.job.attempt.completed。可用它来驱动学习循环或会话后审查工作流。写入 Agent 记忆（learnings、decisions、runbooks、context、conventions、user）的延续上下文可供同一 Agent 的后续尝试使用。

系统健康状况

• 使用 eve system health 确认 API 可以访问。