Boss Agent——自主处理 blocked_pending_human 的仲裁角色——需求文档

日期: 2026-08-13 性质: 需求文档（BRD/PRD 层面），不含详细技术设计。按本仓库既有约定，这份文档确认后本身就 是喂给 graphlemon 自己（Planner→planner_reviewer→Coder→Validator）的一个真实 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. 背景

task.status = 'blocked_pending_human' 目前的语义是"系统遇到自己解决不了的情况，字面意义上 等一个真人来决定下一步"。触发它的 blocked_reason 目前有一个明确的枚举（散落在 src/scheduler.py::_BLOCKED_REASON_FOR_EXCEPTION、src/budget_guardrail.py、 src/org_loop_route.py、src/backend_server.py 里）：budget_exceeded、loop_limit_reached、 classifier_blocked、corrupt_persisted_state、usage_limit_wait_timeout、 prd_consistency_check_failed、planner_review_loop_limit_reached，以及一个兜底的 execution_error（任何未被前面几类捕获的异常都落进这里）。

今天（2026-08-13）自举验证 5 个真实任务时的实况，是这个问题的真实成本：4 个任务先后卡在 blocked_pending_human，blocked_reason 全部显示同一个词 execution_error，但背后其实是三种 完全不同的真实原因——(a) 两个任务是 backend_server 进程跑的是过期代码（一次 schema 迁移改动 还没重启生效）；(b) 一个任务是旧版 Dynamic Workflow 机制遗留的叙述性输出格式，被新的 root_cause_category 枚举校验拒绝；(c) 两个任务是本次会话新发现的真实并发 bug（planner_reviewer 打回 INCONCLUSIVE/FAIL 后，重新规划的路径会在同一个 task_id 已有未终态 work_graph_run 时再插 一行，撞 ux_work_graph_run_active 唯一索引）。这四种情况需要的应对完全不同（重启生效、判断是否 真的是叙述性输出、修一个真实的并发 bug），但从任务列表上看，全部只显示同一个不可区分的 execution_error——过去几个小时里，区分这四种情况、决定怎么处理，全靠人（这次是用户 + Claude Code 协作）手动读 execution_event/日志/代码逐个诊断。

这个诊断过程本身没有用到任何人类独有的判断力——读 DB 里的 execution_event/task/ work_graph_run，读日志，读代码，判断真正卡在哪一类，能不能自主处理——这正是 planner_reviewer（Org Graph unification Phase 1，commit ea19c7d）已经验证过的模式："把原本 需要人工审核的一道关卡换成自主判断的 agent"，只是 planner_reviewer 把关的是 Planner 产出，这次 要把关的是 blocked_pending_human。

今天临时手搭的 watch_resume.py（本次会话内一次性脚本，轮询任务列表、对首次进入 blocked_pending_human 的目标任务调用 manual_resume）是这个需求最原始的雏形，但它只会"不看 原因、直接再试一次"，不做真实诊断——而且这次会话已经实测出它的一个真实缺陷：一次性对多个任务 并发调用 manual_resume，会在全局并发上限（max_concurrent_goals）检查上出现竞态，导致本该排队 的任务反而立刻被判超限、又打回 blocked_pending_human。Boss Agent 需要真正吸取这个教训，不能只 是"更勤快地重试"。

2. 目标

一个新的、常驻的 org 级角色（暂定名 Boss Agent，role_id 暂定 boss_agent——不要叫 "Supervisor"，CLAUDE.md 已经记录过两个同名 Supervisor 概念互相混淆的坑，这会是第三个），职责是：

1. 常驻轮询 task.status = 'blocked_pending_human' 的任务（轮询模式跟 FR-1 docs/done/scheduler-new-goal-dispatch-requirements.md 已经实现的常驻轮询是同一个载体形式的 姊妹机制——那个负责"新 Goal 怎么自动开始"，这个负责"已经卡住的任务怎么自动接回去"，两者是独 立循环，不合并）。
2. 对每个卡住的任务做真实诊断：读 blocked_reason + 相关 execution_event/日志/代码，判断这次 卡住的真实原因属于哪一类（复用今天实际观察到的分类作为起点：过期进程/环境问题、真实代码 bug、内容/规划类问题、资源类限制如 budget_exceeded）。
3. 在明确的自主权边界内（边界怎么画见 §7 开放问题）自主决定并执行下一步——可以是直接 manual_resume、也可以是需要先动代码修一个真实 bug（本次会话的实际先例：直接改代码修 src/schema.py 的迁移函数、改 src/org_loop_route.py 的并发问题），修完再重跑受影响的任务。 超出边界的，才真正升级给人，而不是像现在这样"只要卡住就一律等人"。
4. 不论是自主处理还是升级，都要留下可事后追溯的决策记录（谁/什么时候/诊断出什么原因/做了 什么决定/为什么）——匹配本仓库既有的"记忆必须留 git 痕迹，不能是静默可变的本地状态"的原则 （.claude/agent-memory/ 的既有约定），不是决策了就完事、无迹可查。

3. 非目标

1. 不在本文档里裁定"哪些 blocked_reason 可以完全自主处理、哪些必须升级给人"这个具体边界。 这是一个改变系统自主权边界的真实决策（跟 FR-1 当初"要不要自动派发新 Goal"是同一量级的决策）， 需要用户在设计阶段之前先明确拍板，不能让 Planner 自己悄悄选一种理解——本文档 §7 只列出这个 问题本身和已知的参考信息（比如 budget_exceeded 涉及真实花费、动生产 DB 这类操作需要先 dry-run），不代为决定。
2. 不要求把这次会话里的 4 个具体任务和相关代码 bug 也一并算进本次实现范围——那几个 bug 已经 由本次会话直接修复（不经过 graphlemon 自己的 Coder），Boss Agent 是面向未来的通用机制，不是 "顺便把今天的坑填了"。
3. 不重新设计 blocked_pending_human 状态机本身（task.status/blocked_reason 的既有取值、 org_loop_route.py 的路由逻辑）。Boss Agent 是在这个既有状态机之上新增一个"自动响应者"，不是 替换它。
4. 不等同于、也不合并 FR-1 的新 Goal 自动派发（面向 queued 状态的新任务）——两者是完全独立 的两类工作，动机相似但触发条件、风险量级都不同，具体理由见 §1 最后一段。

4. 功能需求

#	需求描述	优先级
FR-1	需要一个机制，定期扫描 task.status = 'blocked_pending_human' 的任务（轮询周期留待设计阶段）。	必须
FR-2	对每个扫到的任务，基于 blocked_reason + 相关 execution_event/日志/代码做真实诊断，区分"环境/进程问题"“真实代码 bug”“内容/规划问题”“资源限制”等类别，不能只看 blocked_reason 这个粗粒度字符串就下结论（今天 execution_error 这一个值背后有三种完全不同真实原因的教训）。	必须
FR-3	在授权边界内（§7 待拍板）自主执行下一步：可能是直接触发 resume（POST /api/tasks/:id/route，decided_route=manual_resume），也可能是需要先定位并修复一个真实 bug 后再 resume。	必须
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. 验收标准

1. 人为制造一个已知、可自主处理类别的 blocked_pending_human 任务（比如模拟一次可安全重试的 execution_error），验证 Boss Agent 能在轮询周期内自主诊断、自主 resume，不需要人工点击。
2. 人为制造一个应当升级的场景（比如 budget_exceeded，或诊断置信度不足的情况），验证 Boss Agent 不会自作主张处理，而是正确升级并留下可读的升级原因。
3. 同时制造 3+ 个卡住任务、且当前并发已接近上限，验证 Boss Agent 的批量处理不会出现竞态导致 任务被错误地重复打回。
4. 查询决策记录（不论是自主处理还是升级的），能还原出"这个任务什么时候卡住、诊断出什么原因、 Boss Agent 做了什么"的完整链路，不需要再回头翻 execution_event/日志。

6. 风险

这是本仓库第二次改变系统自主权边界的决策（第一次是 FR-1 的新 Goal 自动派发，已经拍板"完整 开放"）。跟 FR-1 不同，这次涉及的场景本质更不均质——FR-1 的每一次自动派发都是同一件事（开始 执行一个新 Goal），风险边界清楚；而 blocked_pending_human 背后的原因五花八门，有的自主处理零 风险（比如今天的场景 a：进程重启后重跑），有的自主处理风险很高（budget_exceeded 意味着自主决 定继续花真实的 API 调用费用；涉及生产 DB/schema 的修复如果不先 dry-run 就直接自主执行，本次会话 已经真实示范过"不 dry-run 直接迁移生产库"是会出真事故的操作）。"哪些能自主、哪些必须升级"这条 边界线画错的代价，在两侧是不对称的——画得太保守，Boss Agent 就退化成"更勤快但没有真正自主权 的通知器"；画得太激进，可能出现自主决策造成真实数据/费用损失后才被发现。这条边界线必须在设计 阶段之前由用户明确拍板，不能让实现过程中的 Planner/Coder 自己悄悄决定。

7. 开放问题

• [ ] 自主权边界怎么画：按 blocked_reason 分类，哪些默认允许 Boss Agent 完全自主处理 （比如 classifier_blocked/corrupt_persisted_state 这类看起来是纯技术性、可安全重试的）， 哪些必须默认升级给人（比如 budget_exceeded 涉及真实花费；任何需要修改生产数据库 schema/迁移的场景）？还是应该反过来，默认全部升级、只有显式加入白名单的类别才允许自主？
• [ ] 决策记录存在哪：新建一张表（类似 bug_record 但记录的是"Boss Agent 的处理决策"而不是 "缺陷"），还是复用 execution_event 追加一种新 event_type，还是两者都要？
• [ ] 是否需要同时补上 bug_record.source 的枚举缺口：bug_record.source 目前只允许 'validator'/'human' 两个值（src/schema.py:217）。如果希望 Boss Agent 诊断出的真实代码 bug 也能走正式的 bug_record/skill_iteration 闭环（而不是像本次会话一样绕开这条正式路径 直接改代码），这个枚举需要新增一个值代表 Boss Agent 自己——这个决策会牵动 roles/planner_reviewer/role.json 之外，是否也要给 Boss Agent 建一份独立的 roles/boss_agent/role.json（用哪些工具权限：只读诊断 vs 允许直接改代码修 bug，是两种完全 不同的权限量级，需要先决定 Boss Agent 到底是"诊断+建议"还是"诊断+亲自动手修"）。
• [ ] 轮询周期：跟 FR-1 的 45 秒、还是"在途任务复原"的 300 秒更接近？blocked_pending_human 的紧迫性介于两者之间，需要拍板一个具体数字。
• [ ] 载体形式：跟 FR-1/在途任务复原同款、backend_server.py 内置后台线程，还是独立进程？ 如果 Boss Agent 被授权直接改代码修 bug（而不只是 resume），它可能需要调用 claude -p 本身（跟 Planner/Coder/Validator 一样是一次真实 agent 调用），这种情况下用简单的后台线程 是否够用，还是需要更接近 Deploy Supervisor 那种独立进程的隔离级别？