feat(agent): rtchild 实时子 agent + 四类 agent 独立模型源 + 残余任务四态

## rtchild(R1–R13)

第三种、**独立**的子 agent 类型,面向语音/视频通话:内核只要文本流,
不定音频(TTS/播放由插件负责)。

- R1  CapRT 能力位 + AgentConfig.IsRealtime;AssignRealtime 两侧校验
- R2  rtSlot 单槽覆盖(latest-wins,从不排队)
- R3  独立 ctx + rtLoop + SpawnRTChild/StopRTChild
- R4  ChatStream 逐块 → outputch(rt).Execute(text)
- R5  打断 = 原地截断,不重试
- R6  工具执行期不可打断(suppressedCancels 让守卫可观测)
- R7  普通上下文 + 窗口裁剪(旧内容不进模型,**原文保留**)
- R9  CloseRTChild → L4 信号 + rt_transcript 按需分页取
- R10 notify_parent(L4,注册一次,停即注销)
- R11 闲置零 token
- R13 rt_children 管理工具(父专属)

刻意**不做** rtPage/anchor/degraded_resets(过设计,已裁定);
不用四级中断阶梯(preemptCooldown+同级不抢占会让 ~75% 的 rt 打断
静默退化为排队)。

## 四类 agent 各自可配模型源

core.agent.llm.{main,resident,rt,child}_provider,语义是**优先不是独占**:
该源排到候选链最前,其余源仍作回退。硬锁定会让"首选源抖一下"变成
"这个 agent 彻底不工作",而多源回退链正是本仓为此建立的机制。
名字写错 ⇒ 回退默认源 + 记日志(不静默)。子 agent 未配置时继承父的。

★ 顺带修掉一个真缺陷:spawn.go 原来直接 a.provider.Chat(),
**普通子 agent 完全绕过 provider 回退链** —— 它是唯一绕过的地方:
默认源抖一次整条子任务就"执行失败",而主 agent 同刻能自动换源。

## 驻留子残余任务四态 + 通道三态

残余任务:keep / takeover(接手,keep 的明确别名)/ stash(暂存到各自
原通道)/ drop。stash 必须**逐条按各自 OutputChannel 归位** —— 一个子
可能同时收 qq 和 webui,混存会让"接回 qq 的人"拿到本该给 webui 的活。

通道:release(零值,向后兼容)/ suspend(挂起,暂存保留)/ takeover
(接回父并立即释放暂存)。原来是无条件 release,于是只有两种坏结局:
通道一直没人分配(消息无人处理且无提示),或刚好被别的 agent 抢到。

一次定完不留窗口:FinishResidentWith → DestroyResidentWith →
teardownResidentWith。任一环退回不带 disp 的旧函数,disp 就被丢掉、
通道被无条件释放 —— 而 stash 的暂存正挂在那条通道上(实际踩过)。

## 修复"手写字段白名单"丢值(7 处)

同一类缺陷:不传整个结构体,而是手写一份"允许通过的字段清单"。
危险在于**写漏了不报错** —— 字段静默归零,故障出现在很远的地方。

- corehandler.go outputRegister: ChannelDef{NoMemory,Cleaner} → 整体传
- pubSdkInjectOpts: 逐字段摊平丢 ScenePolicy/SecurityProfile → 收整个 injectParams
- injectParams/injectMediaParams: 结构本身缺字段 → 补齐 + asInjectParams()
- 配套反射判据 TestSegment_RoundTripEveryField(取代手写断言,
  原判据漏了 Phase/LLMText/FinalText/ToolCalls/ExtraKeyMediaBlocks/ExtraBag)

## 压缩偏离设计

CompressResident 原为截断,与设计(LLM 摘要替换)不符。改走
PlanCompaction → summarizeForCompaction(用子自己的 provider)→
ApplyCompaction,失败回退 TrimKeepRecent。顺带修 ApplyCompaction 的
锁重入 panic 与双重解锁。

并修一处真实生产数据竞争:ctxFullSignaled 由父 goroutine 写、
子调度 goroutine 读,加 ctxFullMu。

## 判据

新增约 70 条。全部验证过能变红(变异测试),包括:
- TestSegment_RoundTripEveryField 的防腐蚀:fullStageContext 反射断言
  每个字段非零,否则新字段永远不会被覆盖("假绿")
- TestPreferredProvider_PutsSourceFirstAndKeepsFallbacks 成对断言
  "在首位且回退仍在"—— 只断言前者的话,硬锁定也会绿

## 判据自身的坑(两次偶发红,都不是产品缺陷)

1. SpawnResident 末尾 Start(),子会在两次 enqueue 之间取走一条
   → "暂存 0 条"。修法:cancel + waitSchedulerStopped。
   (offload_test.go 早有记录,我没先读就重踩了一遍)
2. TaskPrompt 异步投递,可能在清空队列之后才到 → "多 1 条"。
   靠探针打印内容才认出是 TaskPrompt。修法:本文件用 spawnQuietResident。

go build/vet/gofmt 干净;go test ./... -count=1 -race = 62 包 ok / 0 FAIL / 0 RACE
This commit is contained in:
JianFeeeee
2026-10-30 17:00:47 +08:00
parent b850feaef2
commit eb1deab5dd
36 changed files with 5973 additions and 81 deletions

View File

@ -824,6 +824,45 @@ func (a *Agent) buildToolDefs() []interface{} {
tools = append(tools, toolDefWith("output_list_channels", "列出所有可用输出通道及其能力(如 text/file/image/audio)和对应的输出门工具名称。", map[string]interface{}{}, nil, parallelOpts()))
// 父侧:rtchild 控制面(实时通话子 agent,plan.md 十一)。
if a.parentID == "" {
tools = append(tools, toolDefWith("rt_children",
"管理实时子 agent(rtchild,用于通话/视频通话):list 列出 / "+
"create 创建(**必须成对**给 inputch + outputch)/ "+
"send 注入一条新输入(**会立即打断它当前轮**,不排队)/ "+
"stop 回收(先交给你全部上下文,是否保留由你决定,用 rt_transcript 取回)。"+
"注意:rt 通道必须由插件声明(ChannelDef.Realtime=true);"+
"没有 rt 能力的 agent 不能持有 rt 通道。", map[string]interface{}{
"action": map[string]interface{}{
"type": "string",
"enum": []string{"list", "create", "send", "stop"},
},
"id": map[string]interface{}{"type": "string", "description": "rtchild 的 id"},
"inputch": map[string]interface{}{"type": "string", "description": "create:rt inputch 名(采集侧灌入;成对的一半)"},
"outputch": map[string]interface{}{"type": "string", "description": "create:rt outputch 名(内核把文本写进它;成对的另一半)"},
"system_prompt": map[string]interface{}{"type": "string", "description": "create:系统提示词(留空用内置的实时通话提示词)"},
"max_tools": map[string]interface{}{"type": "number", "description": "create:单轮最多几批工具调用(0=不限,rt 默认不限)"},
"text": map[string]interface{}{"type": "string", "description": "send:要注入的输入(会打断当前轮)"},
},
[]string{"action"}, parallelOpts()))
}
// 父侧:rtchild 上下文交接(用户裁定 2026-10-30:走 contextfull 式中断,
// 主 agent **自行选择**保留哪些内容 —— 所以给一个按需拉取的读口)。
if a.parentID == "" {
tools = append(tools, toolDefWith("rt_transcript",
"取回实时子 agent(rtchild)的通话上下文原文。回收 rtchild 时你会收到一条中断,"+
"告知有多少条消息;**是否保留、保留哪些由你决定** —— 用本工具分段读取后再取舍,"+
"不要把整段塞进自己的上下文(一条通话可能有几百条消息)。",
map[string]interface{}{
"id": map[string]interface{}{"type": "string", "description": "rtchild 的 id"},
"offset": map[string]interface{}{"type": "number", "description": "从第几条消息开始(0 = 从头)"},
"limit": map[string]interface{}{"type": "number", "description": fmt.Sprintf("最多返回多少条(默认 %d)", rtTranscriptDefaultLimit)},
"format": map[string]interface{}{"type": "string", "enum": []string{"text", "raw"}, "description": "text=可读渲染(默认)/ raw=原始消息"},
},
[]string{"id"}, parallelOpts()))
}
// 父侧:驻留子控制面(单工具多动作,见设计 §7)。
if a.parentID == "" {
tools = append(tools, toolDef("resident_agents", "管理驻留子 agent(长期派驻的下属):list 列出 / create 创建(划入 inputch + "+
@ -845,10 +884,20 @@ func (a *Agent) buildToolDefs() []interface{} {
"text": map[string]interface{}{"type": "string", "description": "send:要发给子 agent 的消息"},
"residual": map[string]interface{}{
"type": "string",
"description": "reclaim/destroy:该子手头未处理消息的处置。" +
"keep=转回主 agent 队列(默认,宁可多做一件不可默默丢一条)/ drop=丢弃(已确认不要)。" +
"无论哪种都会逐条记日志;异步通道(如 qq)被丢时用户收不到任何回复,请慎重选 drop。",
"enum": []string{"keep", "drop"},
"description": "reclaim/destroy:该子手头**未处理消息**的处置。" +
"keep=转回你自己的队列(默认)/ takeover=同 keep 但语义明确为「我接手」/" +
"stash=暂存到它各自的原通道,等该通道被接回时再放出(你暂时忙但活不能丢时用)/" +
"drop=丢弃(已确认不要)。" +
"四者都会逐条记日志;异步通道(如 qq)被 drop 时用户收不到任何回复,请慎重。",
"enum": []string{"keep", "takeover", "stash", "drop"},
},
"channels": map[string]interface{}{
"type": "string",
"description": "reclaim/destroy:该子**持有的通道**的处置。" +
"release=归还池子变「未分配」,可被任意 agent 再分配(默认)/ " +
"suspend=挂起:归属清空但不参与自动分配,通道上的暂存任务保留,等你接回/" +
"takeover=接回你自己:通道归你,并立即释放该通道上的暂存任务到你的队列。",
"enum": []string{"release", "suspend", "takeover"},
},
}, "action"))
}