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,146 @@
package core
// R2 判据:rtSlot 单槽覆盖语义(plan.md 十一.五)。
//
// 三条判据分别钉住三件事,删掉对应实现任一条都会红:
// 1. 新输入覆盖旧输入(旧值**作废**,不保留、不补偿)—— 契约 1
// 2. 永不排队(连续 N 次 Push 后待处理恒为 1)—— 契约 3
// 3. 覆盖是**有统计**的(dropped 单调前进)—— 否则"打断生效了几次"不可观测
import (
"fmt"
"testing"
agentIO "github.com/JianFeeeee/HologramAgent/internal/agent/io"
)
func rtEvent(content string) *agentIO.InputEvent {
return &agentIO.InputEvent{
Source: "voice",
Type: "text",
Payload: map[string]interface{}{"content": content},
}
}
func rtContent(evt *agentIO.InputEvent) string {
if evt == nil || evt.Payload == nil {
return ""
}
s, _ := evt.Payload["content"].(string)
return s
}
// TestRTSlot_NewInputReplacesOld 钉住「最新者胜」:后到的输入**作废旧值**。
//
// 若把 Push 改成"入队"(append 到 slice),本判据必然红:Take 会先取到旧值。
func TestRTSlot_NewInputReplacesOld(t *testing.T) {
s := newRTSlot()
s.Push(rtEvent("第一句"))
s.Push(rtEvent("第二句"))
evt, _, ok := s.Take()
if !ok {
t.Fatal("槽里应有待处理输入")
}
if got := rtContent(evt); got != "第二句" {
t.Fatalf("取到的输入 = %q,期望 %q —— 最新者胜未生效(旧值竟然先出队)",
got, "第二句")
}
// 取走后必须清空:否则 rtLoop 会反复拿到同一条输入重跑同一轮。
if _, _, ok := s.Take(); ok {
t.Fatal("Take 之后槽未清空 —— rtLoop 会重复处理同一条输入")
}
}
// TestRTSlot_NeverQueues 钉住「不吃队列」:无论 Push 多少次,待处理恒为 1 条。
//
// 这是契约 3 的直接判据。若实现改成有界队列(哪怕容量 8),
// 连续 Push 100 次后 Take 会连续取出 100 条 —— 本判据立刻红。
func TestRTSlot_NeverQueues(t *testing.T) {
const n = 100
s := newRTSlot()
for i := 0; i < n; i++ {
s.Push(rtEvent(fmt.Sprintf("第%d句", i)))
}
// 只应该能取出**一条**(最后那条)。
evt, _, ok := s.Take()
if !ok {
t.Fatal("槽里应有待处理输入")
}
if got, want := rtContent(evt), fmt.Sprintf("第%d句", n-1); got != want {
t.Fatalf("取到 %q,期望最后一条 %q", got, want)
}
if _, _, ok := s.Take(); ok {
t.Fatalf("连续 Push %d 次后能取出第二条 —— 这不是单槽,是队列(违反契约 3)", n)
}
}
// TestRTSlot_CountsDropped 钉住可观测性:被覆盖的输入必须计数。
//
// 为什么这是判据而不只是日志:rt 场景下"打断"是常态,但如果
// dropped 恒为 0,说明要么插件攒批没生效、要么输入速率极低 ——
// 两种情况下阶段二的延迟数据都不可信。所以它必须能被读到。
func TestRTSlot_CountsDropped(t *testing.T) {
s := newRTSlot()
if got := s.Dropped(); got != 0 {
t.Fatalf("初始 dropped = %d,期望 0", got)
}
s.Push(rtEvent("a")) // 第一次不丢弃(槽是空的)
if got := s.Dropped(); got != 0 {
t.Fatalf("首次 Push 不应计丢弃,得到 %d", got)
}
s.Push(rtEvent("b")) // 覆盖 a ⇒ +1
s.Push(rtEvent("c")) // 覆盖 b ⇒ +1
if got := s.Dropped(); got != 2 {
t.Fatalf("dropped = %d,期望 2(两次覆盖)", got)
}
// 取走之后槽为空 ⇒ 下一次 Push 不算覆盖。
s.Take()
s.Push(rtEvent("d"))
if got := s.Dropped(); got != 2 {
t.Fatalf("取空后 Push 不应计丢弃,dropped = %d", got)
}
}
// TestRTSlot_SeqMonotonicAndMatchesTake 钉住 seq 单调递增且 Take 取到的是**最新 seq**。
//
// seq 是契约 1 的可验证凭据(plan.md 十一.四 空白 3):
// 输出要回传它,判据才能证明"这一轮是用最新输入跑的,而不是旧输入的残余"。
func TestRTSlot_SeqMonotonicAndMatchesTake(t *testing.T) {
s := newRTSlot()
var last uint64
for i := 0; i < 5; i++ {
seq := s.Push(rtEvent(fmt.Sprintf("v%d", i)))
if seq <= last {
t.Fatalf("seq 未单调递增:%d 之后是 %d", last, seq)
}
last = seq
}
_, seq, ok := s.Take()
if !ok {
t.Fatal("应有待处理")
}
if seq != last {
t.Fatalf("Take 返回 seq=%d,期望最新 %d —— 取到的不是最新输入", seq, last)
}
}
// TestRTSlot_WakeIsNonBlocking 钉住唤醒是**电平**语义:
// 槽里已有信号时重复 Push 不得阻塞(cap=1,非阻塞写)。
//
// 若把 wake 改成无缓冲通道或阻塞写,本判据会因 Push 卡死而超时。
func TestRTSlot_WakeIsNonBlocking(t *testing.T) {
s := newRTSlot()
// 连推多次:第一次填满 wake(cap=1),后续必须走 default 分支返回。
for i := 0; i < 10; i++ {
s.Push(rtEvent(fmt.Sprintf("w%d", i)))
}
// 至少要能收到一次唤醒信号。
select {
case <-s.Wake():
default:
t.Fatal("Push 之后 Wake 从未就绪 —— rtLoop 会永久阻塞(待机醒不来)")
}
}