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,167 @@
package core
// R10 判据:rtchild 的工具面(用户裁定 R3 / R4)。
//
// R3:rt 流**不禁工具**;`askparent` 工具**保留**
// R4:提示词要求「调用工具前先用 outputch 告知用户稍等」
//
// `askparent` 在本仓的实际形态是 `notify_parent`(子侧向父发问的唯一通道,
// 见 tooldefs.go:874 的注册条件 parentID != "")。所以这里钉的是:
//
// 1. rtchild 的工具表里**有** notify_parent(且不是被剥掉的)
// 2. 它的回调**真的接线**(初版没接 ⇒ 模型一调就得到"没有上级")
// 3. 工具面**不因 rt 而收缩**(R3:不禁工具)
import (
"strings"
"testing"
agentAPI "github.com/JianFeeeee/HologramAgent/internal/agent/api"
agentIO "github.com/JianFeeeee/HologramAgent/internal/agent/io"
)
// rtToolNames 从 buildToolDefs 的结果里抽工具名。
func rtToolNames(defs []interface{}) map[string]bool {
out := map[string]bool{}
for _, t := range defs {
m, ok := t.(map[string]interface{})
if !ok {
continue
}
fn, ok := m["function"].(map[string]interface{})
if !ok {
continue
}
if name, ok := fn["name"].(string); ok {
out[name] = true
}
}
return out
}
// TestRTChild_AskparentToolPresent 钉住 R3 后半:`askparent`(= notify_parent)保留。
//
// 若有人"顺手"在 rtStripOutputTools 里把它也剥掉(它确实和输出有关),本判据必红。
func TestRTChild_AskparentToolPresent(t *testing.T) {
p := &rtBlockingProvider{}
host, _ := newRTHost(t, p)
id := rtSpawn(t, host, "ask")
rc := host.rtChildren[id]
if rc == nil {
t.Fatal("实例不在登记表")
}
tools := rtStripOutputTools(rc.agent.buildToolDefs())
names := rtToolNames(tools)
// carrier 的 parentID != "" ⇒ notify_parent 应在子侧工具表里。
// 若这里没有,说明 rtchild 的 carrier 没被正确标记为"子"。
if !names["notify_parent"] {
t.Fatalf("rtchild 工具表里没有 notify_parent(askparent)—— 用户裁定 R3 要求保留\n已有工具:%v",
func() []string {
var ks []string
for k := range names {
ks = append(ks, k)
}
return ks
}())
}
// output_send__* 必须被剥掉(rt 输出走 outputch(rt) 流式管线)。
for name := range names {
if strings.HasPrefix(name, "output_send__") {
t.Fatalf("rtchild 工具表里仍有 %s —— 会与流式管线产生两套输出语义", name)
}
}
}
// TestRTChild_NotifyParentIsWired 钉住**接线**(这是初版的真实缺陷):
// notify_parent 的回调必须已接上,调用后不能返回"没有上级"。
//
// 初版 carrier 没设 notifyParent ⇒ notifyParentFrom 直接返回
// 「本 agent 没有上级,无法发送消息」——工具在、调用必失败。
func TestRTChild_NotifyParentIsWired(t *testing.T) {
p := &rtBlockingProvider{}
host, _ := newRTHost(t, p)
id := rtSpawn(t, host, "wire")
rc := host.rtChildren[id]
if rc == nil || rc.agent.notifyParent == nil {
t.Fatal("rtchild 的 notifyParent 未接线 —— notify_parent 工具会永远失败")
}
// 走真实工具入口(不是直接调回调):这才是模型看到的那条路。
got := rc.agent.executeNotifyParent(agentAPI.ToolCall{
Name: "notify_parent",
Arguments: map[string]interface{}{"text": "我想问一下"},
})
if strings.Contains(got, "没有上级") {
t.Fatalf("notify_parent 走真实入口仍报「没有上级」:%s", got)
}
// 入站通道只登记一次:反复发问不应让登记表累积。
reg := host.io.ChannelRegistry()
before := reg.Count()
for i := 0; i < 5; i++ {
rc.agent.executeNotifyParent(agentAPI.ToolCall{
Name: "notify_parent",
Arguments: map[string]interface{}{"text": "再问一次"},
})
}
if after := reg.Count(); after != before {
t.Fatalf("连发 5 次 notify_parent 后登记表从 %d 涨到 %d —— 每次发问都在重复登记(写放大+脏数据)",
before, after)
}
}
// TestRTChild_ToolFaceNotNarrowedByRT 钉住 R3 前半:**rt 流不禁工具**。
//
// 判据取法:把 rtchild 的工具数量与"同一个 agent 不用 rt 时的工具数量"比 ——
// rt 只该剥掉 output_send__*,不该额外剥任何东西。
func TestRTChild_ToolFaceNotNarrowedByRT(t *testing.T) {
p := &rtBlockingProvider{}
host, _ := newRTHost(t, p)
id := rtSpawn(t, host, "face")
rc := host.rtChildren[id]
all := rtToolNames(rc.agent.buildToolDefs())
kept := rtToolNames(rtStripOutputTools(rc.agent.buildToolDefs()))
// 只允许 output_send__* 与 output_list_channels 被剥。
for name := range all {
if kept[name] {
continue
}
if !strings.HasPrefix(name, "output_send__") && name != "output_list_channels" {
t.Fatalf("rt 额外剥掉了工具 %s —— 用户裁定 R3「rt 流不禁工具」", name)
}
}
// 至少要保留一些工具(否则"不禁工具"名存实亡)。
if len(kept) == 0 {
t.Fatal("rtchild 工具表为空 —— 等于禁了所有工具")
}
}
// TestRTChild_StopUnregistersInbound 钉住 Stop 时注销入站通道(不留脏登记)。
func TestRTChild_StopUnregistersInbound(t *testing.T) {
p := &rtBlockingProvider{}
host, _ := newRTHost(t, p)
reg := host.io.ChannelRegistry()
before := reg.Count()
id := rtSpawn(t, host, "unreg")
if reg.Count() <= before {
t.Fatal("创建后没有登记入站通道 —— 父侧收不到 rtchild 的发问")
}
if err := host.StopRTChild(id); err != nil {
t.Fatalf("停止: %v", err)
}
if got := reg.Count(); got != before {
t.Fatalf("停止后登记表 %d,期望回到 %d —— 入站通道未注销", got, before)
}
}
// 确保 agentIO 被使用(ChannelRegistry 类型在断言中通过接口访问)。
var _ = agentIO.CapText