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

@ -253,6 +253,13 @@ type injectParams struct {
CleanerName string `json:"cleaner_name,omitempty"`
// Priority 声明中断注入的优先级(L1..L3);L4 内核独占,见 InjectOptions。
Priority string `json:"priority,omitempty"`
// ScenePolicy 声明此次注入是否参与场面识别(场景式记忆)。
ScenePolicy string `json:"scene_policy,omitempty"`
// SecurityProfile 选择本插件声明的**命名安全限式**(如 "qq.guest")。
//
// ★ 漏了它等于「插件声明了档位、注入时带了、内核从没收到」——
// 策略静默不生效,且没有任何报错(2026-10-30 审计发现,已修)。
SecurityProfile string `json:"security_profile,omitempty"`
}
// injectMediaParams 是带媒体注入/工具块注入的参数。
@ -275,17 +282,47 @@ type injectMediaParams struct {
RecallPolicy string `json:"recall_policy,omitempty"`
CleanerName string `json:"cleaner_name,omitempty"`
Priority string `json:"priority,omitempty"`
// ScenePolicy / SecurityProfile 与 injectParams 同义(见那里的注释)。
ScenePolicy string `json:"scene_policy,omitempty"`
SecurityProfile string `json:"security_profile,omitempty"`
}
// asInjectParams 把媒体注入参数降成通用注入参数(只取共有的 opts 字段)。
//
// 为什么要有这个转换:pubSdkInjectOpts 接收 injectParams,而媒体路径用的是
// injectMediaParams(多 Blocks/BlocksRef)。与其让 pubSdkInjectOpts 收两个类型
// 或改签名成 8 个裸参数(那正是本次修掉的缺陷形态),不如显式降一次。
func (p injectMediaParams) asInjectParams() injectParams {
return injectParams{
Source: p.Source, Channel: p.Channel, Text: p.Text,
NoMemory: p.NoMemory, ContextPolicy: p.ContextPolicy,
RecallPolicy: p.RecallPolicy, CleanerName: p.CleanerName,
Priority: p.Priority, ScenePolicy: p.ScenePolicy,
SecurityProfile: p.SecurityProfile,
}
}
// pubSdkInjectOpts 把 RPC 报文里的三个字段转成公开 SDK 的 InjectOptions。
//
// 单独提一个转换函数是为了让「默认值」只有一个出处:零值即记入记忆 + 不裁剪,
// 与旧三参数注入等价。
func pubSdkInjectOpts(noMemory bool, policy, recallPolicy, cleanerName, priority string) pubsdk.InjectOptions {
// ★ 签名接收整个 injectParams 而**不是逐个字段**:
//
// 曾经的形态是 `pubSdkInjectOpts(noMemory, policy, recallPolicy, cleanerName, priority)`
// —— 于是新增 InjectOptions 字段时,这个转换函数**不会**提醒任何人去接,
// 实际漏了 ScenePolicy 与 SecurityProfile(后者正是 QQ owner/guest 档位的通路)。
//
// 现在:`injectParams` 与 `pubsdk.InjectOptions` 字段一一对应,
// 新增字段时编译器会在这里提示"未使用/缺字段",而不是静默丢失。
func pubSdkInjectOpts(p injectParams) pubsdk.InjectOptions {
return pubsdk.InjectOptions{
NoMemory: noMemory, ContextPolicy: policy, RecallPolicy: recallPolicy,
CleanerName: cleanerName,
Priority: clampExternalPriority(priority),
NoMemory: p.NoMemory,
ContextPolicy: p.ContextPolicy,
RecallPolicy: p.RecallPolicy,
ScenePolicy: p.ScenePolicy,
CleanerName: p.CleanerName,
Priority: clampExternalPriority(p.Priority),
SecurityProfile: p.SecurityProfile,
}
}
@ -558,8 +595,20 @@ func (h *coreHandler) outputRegister(params json.RawMessage) (interface{}, error
if err != nil {
return nil, fmt.Errorf("output.register: %w", err)
}
return nil, h.sdk.RegisterOutputChannel(channel, p.Caps, p.Desc,
pubsdk.ChannelDef{NoMemory: p.Def.NoMemory, Cleaner: cleaner},
// ★ 整体传 p.Def(只把函数型的 Cleaner 换成代理),**不要手写字段白名单**。
//
// 这里曾写成 `pubsdk.ChannelDef{NoMemory: p.Def.NoMemory, Cleaner: cleaner}` ——
// 一个字段白名单,于是 `Realtime` / `ContextPolicy` / `RecallPolicy` /
// `ScenePolicy` **全部静默丢失**。表现(2026-10-30 外部插件 e2e 实测):
// 插件声明 `ChannelDef{Realtime:true}` 的 outputch,到内核侧
// `OutputCapabilities()` 只有 `[text]`,没有 CapRT ⇒ AssignRealtime 被拒
// ⇒ 作者以为"我声明了 rt"却怎么也划不上,且没有任何报错指向这里。
//
// 输入侧(corehandler_register.go)本来就是正确写法,同一件事故意写成两种,
// 所以只修了一半也看不出来。现在两侧同构。
def := p.Def
def.Cleaner = cleaner
return nil, h.sdk.RegisterOutputChannel(channel, p.Caps, p.Desc, def,
func(args map[string]interface{}) (interface{}, error) {
return h.invokeOutput(channel, args)
})