# 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 那种独立进程的隔离级别？