From fa930b9b52860e3bbbacece3dde391300923f66f Mon Sep 17 00:00:00 2001 From: bboonnee Date: Thu, 13 Aug 2026 17:38:47 +0800 Subject: [PATCH] docs: sharpen Boss Agent scope + new requirements doc for liveness-based agent-call timeout --- docs/todo/agent-call-liveness-not-fixed-duration-timeout-requirements.md | 104 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/todo/boss-agent-autonomous-blocked-task-arbiter-requirements.md | 9 ++++++++- 2 files changed, 112 insertions(+), 1 deletion(-) create mode 100644 docs/todo/agent-call-liveness-not-fixed-duration-timeout-requirements.md diff --git a/docs/todo/agent-call-liveness-not-fixed-duration-timeout-requirements.md b/docs/todo/agent-call-liveness-not-fixed-duration-timeout-requirements.md new file mode 100644 index 0000000..1f87d62 --- /dev/null +++ b/docs/todo/agent-call-liveness-not-fixed-duration-timeout-requirements.md @@ -0,0 +1,104 @@ +# 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 将来要处理的"假异常"数量，建议这条优先。 diff --git a/docs/todo/boss-agent-autonomous-blocked-task-arbiter-requirements.md b/docs/todo/boss-agent-autonomous-blocked-task-arbiter-requirements.md index e4d0218..e229acb 100644 --- a/docs/todo/boss-agent-autonomous-blocked-task-arbiter-requirements.md +++ b/docs/todo/boss-agent-autonomous-blocked-task-arbiter-requirements.md @@ -4,7 +4,13 @@ **性质**: 需求文档（BRD/PRD 层面），不含详细技术设计。按本仓库既有约定，这份文档确认后本身就 是喂给 graphlemon 自己（Planner→planner_reviewer→Coder→Validator）的一个真实 Goal，由它自举 实现，不是本次会话直接写代码。 -**状态**: 草案，待确认后作为 Goal 提交。 +**状态**: 草案，待确认后作为 Goal 提交。2026-08-13 修订：原稿把"细化真实原因"框定成"Boss Agent +自己去诊断",讨论中发现这个框定不够——**至少一部分原因在触发的当下就已经是明确、结构化已知的** +（比如并发上限、Agent 调用是否真的卡死），根本不需要事后靠 Boss Agent 去反推,系统自己在触发的 +那一刻就该打上准确的原因,不能眉毛胡子一把抓全丢进 `execution_error` 再指望下游硬猜。见 §4 新增 +FR-7，以及关联文档 +`docs/todo/agent-call-liveness-not-fixed-duration-timeout-requirements.md`（同日新增，独立于本 +文档，但直接影响本文档要处理的"假异常"数量，建议优先于本文档落地）。 ## 1. 背景 @@ -86,6 +92,7 @@ Code 协作）手动读 `execution_event`/日志/代码逐个诊断。 | FR-4 | 超出授权边界的情况，明确升级给人，并说明升级原因（不能是"我不确定所以升级"这种不可操作的理由，要具体到"诊断出的原因是 X，属于需要人工判断的 Y 类别"）。 | 必须 | | FR-5 | 每一次处理（自主执行或升级）都要留下可事后追溯的决策记录，包含：task_id、诊断出的真实原因、采取的动作、时间。 | 必须 | | FR-6 | 并发安全：同一时刻可能有多个任务同时卡住，Boss Agent 对它们的处理不能重蹈今天 `watch_resume.py` 的覆辙——批量触发 resume 前必须正确读取当前并发占用（`max_concurrent_goals`），不能对全局并发上限的检查引入竞态。 | 必须 | +| FR-7 | **系统自己在触发 `blocked_pending_human` 的那一刻，就要给出明确、专属、可区分的 `blocked_reason`，不能让"不认识的异常"全部落入笼统的 `execution_error`。** 今天真实观察到的例子：`ConcurrencyLimitReachedError`（并发上限，本质是"正常排队等待"，不是错误）和 `subprocess.TimeoutExpired`（调用超时，且现有超时判定本身有问题，见关联文档）都被 `task_execution.py::_mark_blocked` 的兜底逻辑（`_ROUTABLE_EXCEPTIONS` 白名单之外一律 `execution_error`）打成了同一个含糊的原因。至少需要扩充 `_ROUTABLE_EXCEPTIONS`/`_BLOCKED_REASON_FOR_EXCEPTION`，让 `ConcurrencyLimitReachedError` 有自己专属的 reason；并且要重新评估"并发上限"这类**系统自己造成、不需要任何判断力就能自动恢复**的场景，是否真的应该产生 `blocked_pending_human`（暗示"需要人/Boss Agent 介入判断"），还是应该是一种不需要人工/Boss Agent 判断介入、由既有的自动派发/复原循环自然清空的状态——如果两种真实原因用同一个状态表达，Boss Agent 就没法只凭状态本身区分"需要我判断"和"不需要任何判断,系统自己会恢复"。 | 必须 | ## 5. 验收标准 -- libgit2 0.21.4