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

@ -0,0 +1,134 @@
package plugin
// 判据:插件通过**普通通道注册接口**声明 rt 能力(`ChannelDef.Realtime`)。
//
// ## 为什么走普通接口而不是新增一对便捷方法
//
// 本仓 SDK 的通道注册只有两个入口(`RegisterInputChannel` /
// `RegisterOutputChannel`),属性一律由 `ChannelDef` 承载 —— 与
// `cli` / `webui` / `remotedevice` 等所有既有插件的写法完全一致:
//
// _ = s.RegisterInputChannel("cli", sdk.ChannelDef{})
// s.RegisterOutputChannel("cli", 1, "CLI 终端", sdk.ChannelDef{}, handler)
//
// 加一对 `RegisterRealtimeInputChannel` / `RegisterRealtimeOutputChannel`
// 会多出**第二套写法**:同一个能力两种声明方式,必然漂移
// (一处改了、另一处没改,且不报错)。所以 rt 能力就走 `ChannelDef.Realtime`。
//
// ## 这两条判据钉的是什么
//
// SDK 声明 → 内核能力位的映射在**两个不同的地方**(输入侧在
// `ChannelRegistry.Register`,输出侧在 `Registry.regOutput`)。
// 只做一侧就会出现"inputch 声明成 rt 了、outputch 没有"⇒
// `AssignRealtime(outputch)` 被拒 ⇒ 插件作者以为"我声明了 rt"却划不上。
// 所以两侧各一条,删掉任一侧的映射都会红。
import (
"testing"
agentIO "github.com/JianFeeeee/HologramAgent/internal/agent/io"
sdk "github.com/JianFeeeee/HologramAgent/internal/sdk"
)
// TestRealtimeChannel_InputSideMapsFromChannelDef 钉住输入侧映射:
// 插件用 ChannelDef{Realtime:true} 声明后,登记表里的通道必须带 CapRT。
func TestRealtimeChannel_InputSideMapsFromChannelDef(t *testing.T) {
reg := agentIO.NewChannelRegistry()
// 走**普通**接口(不存在的便捷方法不该被使用)。
if err := reg.Register(agentIO.InputChannel{
Name: "voice-in", Plugin: "demo",
Def: agentIO.ChannelDef{Realtime: true},
}); err != nil {
t.Fatalf("注册: %v", err)
}
ch, ok := reg.Lookup("voice-in")
if !ok {
t.Fatal("通道未登记")
}
if !ch.Capabilities.Supports(agentIO.CapRT) {
t.Fatalf("Def.Realtime=true 但 Capabilities=%v 缺 CapRT —— "+
"插件声明的 rt 通道无法被 AssignRealtime 划拨", ch.Capabilities)
}
}
// TestRealtimeChannel_OutputSideMapsFromChannelDef 钉住输出侧映射:
// 插件用 RegisterOutputChannel(..., ChannelDef{Realtime:true}, ...) 声明后,
// 该 device 的 OutputCapabilities 必须带 CapRT。
//
// ★ 这条钉的是 `Registry.regOutput` 里的映射 —— 它和输入侧是**两处代码**。
// 删掉那一处,本判据红而输入侧那条仍绿,正好定位到"只改了一半"。
func TestRealtimeChannel_OutputSideMapsFromChannelDef(t *testing.T) {
r := NewRegistry()
iom := agentIO.NewIOManager()
r.SetIOManager(iom)
sd := r.buildSDK("demo")
var called bool
handler := func(args map[string]interface{}) (interface{}, error) {
called = true
return "ok", nil
}
// 走**普通** RegisterOutputChannel(与 cli/webui 等既有插件同一写法),
// rt 能力只靠 ChannelDef.Realtime 表达。
if err := sd.RegisterOutputChannel("voice", 1, "实时通话输出",
sdk.ChannelDef{Realtime: true}, handler); err != nil {
t.Fatalf("注册输出通道: %v", err)
}
dev := iom.GetDevice("voice")
if dev == nil {
t.Fatal("输出通道未注册成 device")
}
gotCaps := dev.OutputCapabilities()
if !gotCaps.Supports(agentIO.CapRT) {
t.Fatalf("ChannelDef.Realtime=true 但 OutputCapabilities=%v 缺 CapRT —— "+
"AssignRealtime(outputch) 会被拒", gotCaps)
}
// caps 原本声明的文本能力不能被覆盖掉。
if !gotCaps.Supports(agentIO.CapText) {
t.Fatalf("补 CapRT 时把原有的 CapText 弄丢了:%v", gotCaps)
}
// handler 仍可执行(映射不能破坏 device 行为)。
if _, err := dev.Execute("voice", map[string]interface{}{"text": "hi"}); err != nil {
t.Fatalf("Execute: %v", err)
}
if !called {
t.Fatal("handler 未被调用")
}
}
// TestRealtimeChannel_NonRealtimeUnchanged 钉住**没有**副作用:
// 不声明 Realtime 的通道,abilities 里不得凭空出现 CapRT。
//
// 这条防"补映射时顺手把所有通道都标成 rt"——那会让 rt 校验形同虚设。
func TestRealtimeChannel_NonRealtimeUnchanged(t *testing.T) {
reg := agentIO.NewChannelRegistry()
if err := reg.Register(agentIO.InputChannel{
Name: "plain", Plugin: "demo", Def: agentIO.ChannelDef{},
}); err != nil {
t.Fatalf("注册: %v", err)
}
ch, _ := reg.Lookup("plain")
if ch.Capabilities.Supports(agentIO.CapRT) {
t.Fatalf("未声明 Realtime 的通道却带上了 CapRT(%v)—— rt 校验会形同虚设",
ch.Capabilities)
}
r2 := NewRegistry()
iom2 := agentIO.NewIOManager()
r2.SetIOManager(iom2)
sd2 := r2.buildSDK("demo2")
if err := sd2.RegisterOutputChannel("plainout", 1, "普通输出",
sdk.ChannelDef{}, func(map[string]interface{}) (interface{}, error) { return "ok", nil }); err != nil {
t.Fatalf("注册输出通道: %v", err)
}
if dev := iom2.GetDevice("plainout"); dev == nil {
t.Fatal("device 未注册")
} else if dev.OutputCapabilities().Supports(agentIO.CapRT) {
t.Fatal("未声明 Realtime 的输出通道却带上了 CapRT")
}
}