Back to Details

eve-job-debugging

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Eve Job Debugging

Eve作业调试

CLI-Only Debugging

仅通过CLI调试

Debug via the Eve CLI exclusively. This replicates the client experience — clients don't have kubectl or host access.
Every debugging capability must be available through the CLI. If you find yourself needing system tools to diagnose a job issue, that's a gap in our CLI that should be fixed.
仅通过Eve CLI进行调试。 这复刻了客户端的使用体验——客户端没有kubectl或主机访问权限。
所有调试功能都必须能通过CLI使用。如果你发现需要借助系统工具来诊断作业问题，这说明我们的CLI存在需要修复的缺口。

Monitor

监控

  • eve job follow <id>
    to stream logs.
  • eve job wait <id> --timeout 300 --json
    to wait on completion.
  • eve job result <id> --format text
    for the latest result.
  • eve job follow <id>
    ：流式查看日志。
  • eve job wait <id> --timeout 300 --json
    ：等待作业完成。
  • eve job result <id> --format text
    ：获取最新结果。

Diagnose

诊断

  • eve job diagnose <id>
    for timeline and error summary.
  • eve job show <id> --verbose
    for attempts and phase.
  • eve job dep list <id>
    for dependency blocks.
  • eve job diagnose <id>
    ：查看时间线和错误摘要。
  • eve job show <id> --verbose
    ：查看尝试记录和阶段状态。
  • eve job dep list <id>
    ：查看依赖阻塞项。

Per-Job Harness Overrides

单作业Harness覆盖配置

When debugging unexpected harness behavior, suspect a per-job override before suspecting agent defaults. Jobs may carry inline overrides set at create time:
  • --harness-override-file <path.json>
    — inline 
    {harness, model?, reasoning_effort?, variant?, temperature?}
    bundle that wins over 
    harness_profile
    .
  • --env-override KEY=VALUE
    (repeatable) — per-job env values, may include 
    ${secret.KEY}
    placeholders resolved at spawn.
Both fields persist on the job record (
harness_profile_override
, 
env_overrides
) and on each attempt (
harness_profile_source
, 
harness_profile_hash
). Inspect via 
eve job show <id> --json
and check the routing log entry on the attempt for the resolved 
harness_profile_source
(
agent_default
, 
string_ref
, 
inline_override
, or 
workflow_template
). Missing-secret interpolation fails fast with 
error_code: missing_secret_override
.
当调试异常的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
）。缺失密钥的插值会快速失败，错误码为
error_code: missing_secret_override
。

Stuck Jobs

卡住的作业

The orchestrator now self-heals from agent-runtime pod loss — these no longer leave jobs stuck:
  • Pod death mid-execution: 
    recoverActiveJobsWithTerminatedAttempts
    sweep reclaims active jobs whose attempts were externally finalized, releases limiter slots, and closes workflow roots.
  • Graceful shutdown: agent-runtime preStop marks running attempts as 
    pod_terminated
    and sets pod status to 
    draining
    so no new routing lands on it.
  • Stale recovery: covers all assignee types (not just 
    orchestrator
    ), so agent-assigned jobs (e.g. 
    map-generator
    , 
    pm-coordinator
    ) are visible to the watchdog.
If a job still appears stuck for >5 minutes in 
active
with no heartbeat, run 
eve job diagnose <id>
and check pod status — if the pod is 
draining
or missing, the next sweep will reclaim it.
编排器现在可以自动从Agent-runtime Pod丢失的状态中恢复——这类情况不再会导致作业卡住：
  • 执行过程中Pod死亡：
    recoverActiveJobsWithTerminatedAttempts
    扫描会回收那些尝试被外部终止的活跃作业，释放限制器插槽，并关闭工作流根节点。
  • 优雅关闭：Agent-runtime的preStop钩子会将运行中的尝试标记为
    pod_terminated
    ，并将Pod状态设置为
    draining
    ，这样就不会有新的路由请求分配给它。
  • 过期恢复：覆盖所有分配者类型（不仅限于
    orchestrator
    ），因此Agent分配的作业（如
    map-generator
    、
    pm-coordinator
    ）会被监控进程检测到。
如果作业在
active
状态下超过5分钟仍无心跳，运行
eve job diagnose <id>
并检查Pod状态——如果Pod处于
draining
状态或已丢失，下一次扫描会回收该作业。

Env Gates and Ad-Hoc Agents

环境闸门与临时Agent

Env gates (project-scoped serialization) fire only for action jobs (
action_type
set: 
deploy
, 
build
, 
migrate
). Ad-hoc agent runs that carry only 
env_name
are no longer serialized through the env mutex — multiple ad-hoc jobs in the same env now run in parallel. If you need exclusion, add an explicit 
action_type
.
环境闸门（项目级序列化）仅针对动作类作业触发（设置了
action_type
：
deploy
、
build
、
migrate
）。仅携带
env_name
的临时Agent运行不再通过环境互斥锁进行序列化——同一环境中的多个临时作业现在可以并行运行。如果需要互斥，请显式添加
action_type
。

Multi-Attempt Agent Runs

多尝试Agent运行

The orchestrator emits 
system.job.attempt.completed
on every attempt terminal state (success, failure, orchestrator error). Use this to drive learning-loop or post-session-review workflows. Carryover context written to agent memory (
learnings
, 
decisions
, 
runbooks
, 
context
, 
conventions
, 
user
) is available to subsequent attempts of the same agent.
编排器会在每次尝试进入终端状态（成功、失败、编排器错误）时发出
system.job.attempt.completed
事件。可利用此事件驱动学习循环或会话后审查工作流。写入Agent内存的上下文（
learnings
、
decisions
、
runbooks
、
context
、
conventions
、
user
）可用于同一Agent的后续尝试。

System health

系统健康

  • eve system health
    to confirm the API is reachable.
  • eve system health
    ：确认API是否可达。