feat(resident): 分诊助手定位 + 残余任务由父显式决定

用户澄清(重要定性):这不是「内核替父决定」,而是**及时反馈** ——
主 agent 忙时不该让用户干等十几分钟。子 agent 是**分诊助手**:
简单的直接处理并回复,需要主 agent 的立刻回「忙碌中,请稍候」、不勉强作答。

三处补齐:

1. 分诊助手的职责提示词(之前完全没给 ⇒ 子不知道自己为什么存在):
   两条路(直接办 / 报忙碌)、拿不准时报忙碌、必须 output_send 到原通道。
2. 驻留子继承父的 SystemPrompt(之前没传 ⇒ 子只用一句兜底文案,
   拿不到「异步通道必须显式 output_send,否则回复被静默丢弃」这条铁律。
   webui 这类同步通道能回是因为走 ResponseCh,掩盖了这个缺陷)。
3. 残余任务由父显式决定(用户要求):reclaim/destroy 时子手头未处理的消息
   不再由内核悄悄处置 —— 内核只负责列清楚,父用 residual=keep/drop 决定。
   之前 pendingEvents 只收带 ResponseCh 的,异步(qq)残余任务完全不在内,
   被销毁时静默消失、用户零反馈且日志无痕。

配套:
- scheduler.takeAllPendingEvents:取走全部未执行事件(不筛通道)
- ApplyResidual(keep|drop):keep 转回父队列(保留 ResponseCh),
  drop 逐条记日志 + 给同步调用方补终态(否则 cli/a2a 永久挂起)
- 状态面暴露 offload_owned,让父分清「我建的子」与「内核临时拉的助手」
- 工具 schema 加 residual 参数并说明 drop 的代价

这也是用户观察到的「机制很自然」的落点:分诊助手就在同一张登记表里,
父能 inspect/send/compress/reclaim/destroy,控制面 6 动作按 id 生效不区分来源。

测试 +7(残余 keep 转回且保留 ResponseCh / drop 通知同步调用方 /
空残余如实报告 / 分诊提示词 / 继承 SystemPrompt),
其中 drop 那条已实测「对着静默丢弃的旧实现会失败」。全套绿。
This commit is contained in:
JianFeeeee
2026-09-19 17:43:16 +08:00
parent 01909bb914
commit 943eef01cf
10 changed files with 459 additions and 37 deletions

View File

@ -341,28 +341,40 @@
- **创建/销毁/回收/查看/发送**是**父可调用的原语(工具)****决策**(压还是收、收哪些)
在父的模型手里 —— 内核不替父决定。
### 7.1 例外:积压任务自动转投(内核主动拉起)[已定 · 唯一例外
### 7.1 积压任务的**及时反馈**(内核主动拉起分诊助手)[已定
**背景2026-09-19 线上实测)**:主 agent 被一条长任务占住时当天现场128 秒、
69 次工具调用),后来的 QQ 消息全部以 `level insufficient` 排进中断队列干等 ——
**背景2026-09-19 线上实测)**:主 agent 被一条长任务占住时当天现场135 秒、
8 次 cmd_run),后来的 QQ 消息全部以 `level insufficient` 排进中断队列干等 ——
同级中断不能抢占同级运行任务(`scheduler.canPreempt`),只能等前一个跑完。
而内核明明有驻留子(独立 agent + 独立调度器 + 共享输出通道视图)可以并行干活
用户在这十几分钟里**收不到任何回复**
**定性(用户明确)**:这不是"内核替父决定",而是**及时反馈** ——
主 agent 忙时不该让用户干等。分诊助手的职责是:
- **简单的、不需主 agent 介入的** → 直接处理并回复;
- **需要主 agent 介入的** → 立刻回「主 agent 忙碌中,请稍候」,**不勉强作答**。
**行为**:当运行任务已持续超过 `core.agent.offload_busy_after`(默认 5m
**且**排队输入积到 `offload_min_pending`(默认 3条时内核
1. 拉起(或在 `offload_max_residents` 内复用一个)**转投专用驻留子**
2. 把积压的**纯排队输入**转投给它
3. 在原队列位置留下一条说明:`[系统] N 条积压任务已转投给驻留子 agent X 处理…`
1. 拉起(或在 `offload_max_residents` 内复用一个)**分诊助手**`OffloadOwned`
2. 把积压的**纯排队输入**交给它先行分诊
3. 在原队列位置留下一条说明:`[系统] N 条积压消息已在主 agent 忙期间交由临时助手 X 先行分诊…`
**转投驻留子的通道配置(刻意与人工创建的子不同)**
**分诊助手的通道配置(刻意与人工创建的子不同)**
- **不配 inputch**:它是内核的干活 agent不接收任何插件的用户输入
- **持有全部输出通道**`AllowedOutputs` 为空 = 完整授权):它必须能把结果发回
qq/webui 等正确通道(否则干活结果无处可去)。
**为什么这是对上述原则的例外,且可接受**:父此刻正忙(物理上无法做决策),
而积压任务**本来就是空的** —— 转投只是把「排队干等」换成「有人在做」,
不改变任何已提交决策的语义。若不做例外,这个能力就只能由父的模型发起,
而它恰恰是忙不过来的那个
**为什么这套机制自然(用户观察)**:分诊助手就在**同一张登记表**里 ——
父能 `inspect` 它的处理表与轮次、能 `send`、能按需 `compress`/`reclaim`/`destroy`
控制面 6 个动作均按 id 生效、不区分来源,因此回收策略对它自动适用。
状态面额外暴露 `offload_owned`,让父能分清"我建的子"与"内核临时拉的助手"
**残余任务由父显式决定**(用户 2026-09-19 要求):回收/销毁一个分诊助手时,
它手头可能还有尚未处理的消息。内核**不自己决定**这些消息的命运,而是:
- `residual=keep`(默认):逐条转回父自己的队列,父稍后处理;
- `residual=drop`:明确丢弃,**逐条记日志**(不可追溯的丢弃是不允许的);
- 两种路径都仍要给 `ResponseCh` 补终态,否则 cli/a2a 这类无超时同步调用方
会永久挂起(设计 §7 I5
**默认关闭**`core.agent.offload_enabled=false`):它改变的是系统行为而非修 bug
按「显式才是特权」(与 `scheduler.DefaultLevel` 同一条理由)由部署方打开。
@ -373,6 +385,14 @@
- 只对**根 agent** 生效:子再去拉孙子会形成无界增殖,而积压的源头是根那条链。
- 实现上检查跑在**独立 goroutine**`schedulerLoop` 是同步执行的,
放在那里在「正忙」期间根本不会回到循环顶部(等于永不触发)。
- 转投时**推原事件**`DeliverRouted`)而不是重建:重建会丢掉 `ResponseCh`
使同步调用方永久挂起。
💡 **两条容易重犯的坑(都已在实现里修掉并写进测试)**
1. 积压可能全堆在 `io.inputCh`(因为忙时 `pumpInbox` 没被调用),
只数 `sched.queue` 会得到 0 ⇒ 永不触发。
2. 分诊助手必须**继承父的 SystemPrompt**:它里面写着「面向 qq 等异步通道时
必须显式 `output_send`,纯文本会被静默丢弃」。缺了它,子处理完却发不出去。
- **默认完整授权**[已定]:子默认拿到全部插件与工具(含输出门);
父可在创建时**收窄**(收窄工具子集、收窄可用输出通道集合)。