# Agent 调用超时判定：不能用固定时长，只能用"是否还活着"——需求文档

**日期**: 2026-08-13
**性质**: 需求文档（BRD/PRD 层面），不含详细技术设计。这是喂给 graphlemon 自己实现的一个真实
Goal，本次会话不直接改代码——这是一条基础设施级别的修复，影响所有 org_node 调用，不只是某一个
具体场景。
**状态**: 草案，待确认后作为 Goal 提交。用户明确重申过的既有决定（本次会话之前已经讨论过一次），
但实际代码目前并不满足这个决定——需要作为一个真实缺口记录下来，不能假设"讨论过就等于已实现"。

## 1. 背景

`src/org_node_trigger.py::trigger_org_node`/`trigger_org_node_structured`（所有 org_node 真实调用
`claude -p` 的唯一入口）目前是一次性阻塞调用：

```python
result = subprocess.run(
    args, cwd=target_folder_path, stdin=subprocess.DEVNULL,
    capture_output=True, text=True, timeout=timeout,
)
```

`timeout` 参数在不同调用点取值不同（大多数是 300 秒，`implement_code`/`validate_implementation`
这类更重的调用是 1200 秒），但性质都是同一种——**固定时长的墙钟超时**：不管这次调用是不是还在正常
产出内容、只要总耗时超过这个数字，`subprocess.TimeoutExpired` 就会被抛出，然后被
`task_execution.py::_mark_blocked` 兜底成 `blocked_reason='execution_error'`、状态打成
`blocked_pending_human`。

今天（2026-08-13）真实撞上了这个问题：任务 `bfd3ee82` 的 Validator 在规划自己的 Work Graph 时，
一次 `claude --agent validator -p ...` 调用（prompt 里嵌了完整的已批准 SDD/PRD 全文，内容量较大）
跑满 300 秒被杀掉，直接变成 `blocked_pending_human`。

这不是这次调用"卡死"了——只是内容量大、真实需要的时间比 300 秒长。**一次真实的 agent 调用本身是
多轮工具调用的会话（读文件、搜索、判断、再读文件……），耗时长短取决于任务复杂度，不取决于一个
预先猜的固定数字**——这跟 `docs/done/validator-loop-until-dry-skill-requirements.md` 里"一次
`agent()` 调用会话自己收敛需要多轮"是同一个认知：**只要这次调用还在真实产出/推进，哪怕跑
10000 秒也不应该被判定为超时**；只有当调用**长时间没有任何新输出、也没有报错**（真正卡死、进程
挂起不动了）时，才应该被判定为异常，需要处理。这是两种完全不同的判断逻辑——前者是"总时长封顶"，
后者是"活跃度/心跳"——现在的实现只有前者，从未实现过后者。

## 2. 目标

`trigger_org_node`/`trigger_org_node_structured`（以及任何其他调用 `claude -p` 的地方，比如
`e2e_pipeline.py::_check_prd_consistency`/`work_graph_plan.py::plan_work_graph` 各自传入的
`timeout` 参数）改成按"是否还活着"判断，而不是按固定总时长判断：

- 只要这次调用还在持续产出内容（不管是 stdout 增量、还是别的可观察的"进行中"信号），无论总耗时
  多长，都不应该被判定为超时/卡死。
- 只有当**长时间没有任何新输出、且没有报错**（真正卡死）时，才应该判定为异常，走现有的
  `blocked_pending_human`/异常处理路径（这种情况下打的 `blocked_reason` 应该是一个专属值，比如
  `agent_call_stalled`，不能再混进笼统的 `execution_error`——跟 Boss Agent 需求文档
  `docs/todo/boss-agent-autonomous-blocked-task-arbiter-requirements.md` 里"细化 blocked_reason
  分类"的要求是同一个方向，这条本身就是那份文档要处理的原因分类之一）。

## 3. 非目标

1. **不裁定具体用什么信号判断"是否还活着"**——这是本文档刻意留给设计阶段的核心技术问题（见
   §7），不同方案（读取 `claude` 是否支持增量输出模式、监控进程 CPU/IO 活动、依赖
   `execution_log_file`/`c_ws_log_tail` 这条已有的实时日志旁路）代价和可靠性都不同，需要先调研
   `claude -p` 这个执行后端实际能提供什么可观察信号，不能在需求阶段假设某个方案一定可行。
2. **不改变 `claude` CLI 本身的调用方式约定**（`--agent`/`--output-format json`/
   `--permission-mode auto`，见 CLAUDE.md"硬约束"一节）——如果心跳检测需要切换到某种增量输出
   格式，这需要先验证是否兼容现有的 ```json fence 提取约定（`org_node_trigger.py` 模块文档已经
   记录过的先例：`--agent` + `--json-schema` 一起用会静默丢失 `structured_output`，切输出格式
   前必须先做同类的真实兼容性验证，不能假设新格式和旧解析逻辑天然兼容）。
3. **不等同于**已有的 `p_usage_limit_wait`（`work_graph_execute.py::UsageLimitWaitTimeoutError`，
   处理 Claude 账号本身触发用量限额时的等待重试）——那是一个已知、已分类的特定信号触发的等待
   逻辑，跟"普通调用要跑多久才算异常"是两回事，不要合并成同一个机制。

## 4. 功能需求

| # | 需求描述 | 优先级 |
|---|---|---|
| FR-1 | `trigger_org_node`/`trigger_org_node_structured` 的超时判断从"总时长超过 N 秒"改为"距离上一次可观察的活跃信号超过 N 秒"，具体信号来源留待设计阶段调研确定。 | 必须 |
| FR-2 | 真正判定为"卡死"（而不是"还在正常跑"）时，`blocked_reason` 使用专属值（如 `agent_call_stalled`），不落入笼统的 `execution_error`。 | 必须 |
| FR-3 | 各调用点现有的固定 `timeout` 参数值（300/1200 秒等）语义需要重新定义——如果改成心跳判断，这些数字可能变成"心跳最大间隔"而不是"总时长上限"，需要在设计阶段明确每个数字新的含义，不能保留旧数字但换了新语义却没人核对是否还合理。 | 必须 |

## 5. 验收标准

1. 构造一个真实场景：一次 agent 调用总耗时明显超过当前 300 秒的固定值，但过程中持续有可观察的
   活跃信号（不管最终选的是什么信号），验证这次调用**不会**被判定为超时/卡死，能正常跑到完成。
2. 构造一个真实场景：一次调用在启动后很快就不再有任何活跃信号、且没有报错（模拟进程真正挂起），
   验证系统能在合理时间内判定为 `agent_call_stalled` 并正确处理，不会无限等下去。
3. 今天实际复现的 `bfd3ee82` 场景（大 prompt、验证式 Work Graph 规划调用）用修复后的机制重跑，
   验证不再因为总时长超过 300 秒就被杀。

## 6. 风险

如果最终选择的"活跃信号"本身不可靠（比如信号源本身有延迟、或者某些真实卡死的场景恰好还在产生
噪声信号），可能导致真正卡死的调用永远不会被判定为异常、任务无限挂起——这跟"固定超时太激进、
误杀正常调用"是同一个问题的另一个极端，设计阶段需要两头都验证到，不能只解决"误杀"这一半。

## 7. 开放问题

- [ ] **"活跃信号"具体是什么**：`claude -p ... --output-format json` 目前是一次性输出，本身不是
      增量流；需要先调研 `claude` CLI 是否有增量/流式输出格式可用（如果有，切换格式本身要先做真实
      兼容性验证，见 §3.2），如果没有，是否可以用进程级别的 CPU/IO 活动作为替代信号，或者依赖
      `work_node_run.py`/`execution_log_file` 这条已有的实时日志旁路（如果这次调用本身会写日志的
      话）。这是本文档最核心、最需要先调研清楚的技术问题。
- [ ] **"长时间没有活跃信号"的具体阈值定多少**：不再是"总时长 N 秒"，而是"距上次活跃信号 N 秒"，
      这个新的 N 该怎么定，是否所有调用点都用同一个值。
- [ ] 跟 Boss Agent（`docs/todo/boss-agent-autonomous-blocked-task-arbiter-requirements.md`）的
      实现顺序：这条修复解决的是"避免正常调用被误判为异常进而错误占用 `blocked_pending_human`"，
      Boss Agent 解决的是"任务真的卡在 `blocked_pending_human` 之后怎么自主处理"——两者独立，但
      这条修复先落地，能显著减少 Boss Agent 将来要处理的"假异常"数量，建议这条优先。