refactor(agent): 子 agent 类型抽象 + rt 输出异步 + 工具钩子统一

三件事,都是同一个根因的症状:子 agent 的类型逻辑复制成多份,
于是标准路径上的能力没跟着传过来。

## 1. 抽出 child 包(类型抽象 + 单一登记表)

新增 internal/agent/core/child/:
  child.go      Kind / Child(嵌入用)/ State / 残余与通道处置
  registry.go   单一 Registry + Entry 接口 + Cleanup 骨架
  kind.go       ChildKind —— 按两条主轴(上下文 / 工具与输出异步)
  kinds.go      四种子 agent 的清单与迁移状态

此前 Agent 上有两张互不知情的表(residents / rtChildren),各带一把锁。
实测新增一种子 agent 要改 18 个生产文件,并已因复制而漂移过一次
(StopRTChildren 漏注销入站登记,见 engineering-lessons.md §2.3)。

现在单数与复数停止**共用** Cleanup,那个形态在结构上不可能复现。

## 2. rt 的输出改为异步(用户的原始诉求)

rtEmit 曾直接 dev.Execute(...),插件侧延迟(TTS/网络编码/字幕渲染)
直接节流模型的 token 消费 —— 「不攒整段」的收益全被吃掉。

新增 outputpump.go(输出通道的异步壳):
  · Push 立即返回,交付由独立消费 goroutine 完成
  · 有界队列(64),满则**丢最旧**(符合 rt 的"最新者胜")
  · 丢弃与设备缺失都留痕,否则"用户听不到"没有任何线索
  · Close 排空后退出,不吞最后半句
  · 设备每片重新解析(插件崩溃会 Unregister,缓存指针会指向死设备)

## 3. 工具钩子统一(本轮最大发现)

实测:StageBeforeToolcall / StageAfterToolcall 全仓只在
task.go:1022/1079/1194,三处都在 runOneTool / stepToolAfter 里;
而 executeToolCallOutcome 内部**没有任何 runStage**。

⇒ rtchild 与工作式子两条路径**完全跳过插件钩子**:不能审计、
不能拒绝、不能改参、不能脱敏。README 承诺的 before_toolcall
在这两条路径上不成立。

新增 toolbatch.go(唯一批执行实现:批并发 + 双钩子 + 顺序落结果),
两种类型切过去。工作式子的"禁输出工具"与"保持串行"用 batchOpts 注入,
不各写一遍执行逻辑。

## 判据(均经变异验证)

  TestRTChild_OutputIsAsync              改回同步 ⇒ 红(实测确认)
  TestOutputPump_DropsOldestOnFull       改阻塞/无界 ⇒ 红
  TestOutputPump_CloseDrains             丢弃队列 ⇒ 红
  TestOutputPump_ResolvesDeviceEachTime  缓存指针 ⇒ 红
  TestRTChild_ToolsGoThroughPluginStages 绕开钩子 ⇒ 红
  TestRTChild_StageCanDenyTool           同上
  TestWorkerToolsGoThroughPluginStages   同上(变异实测确认)
  TestWorkerToolsStaySerial              改成并发 ⇒ 红
  TestNoChildTypeTablesInCore            源码扫描,禁类型专属表回潮
  TestRTChild_HasGraphMemory 等 5 条     rt 接入图记忆

## 顺带修复

  · rt 接入图记忆(参照驻留子的轻量内核形态):此前 graphMem() == nil,
    memory_recall / memory_commit 在 rt 里全部不可达,每通电话从零开始。
    默认只读(通话高频写入会灌满图谱噪声),4 个失败点合并成一个 rollback
    闭包(逐点挂必然漏一处 ⇒ 泄 SQLite 句柄)。
  · rt 的 PreferredProvider 走候选链(此前裸调 a.provider,优先源无效且零回退)。

## 保留的语义(逐项确认仍在)

  驻留子三层压缩:checkContextFull / handleChildContextFull / CompressResident
  三种通道处置:ChannelRelease / Suspend / Takeover
  残余 keep/drop + harvestResidentMemory
  child.Start() 的 7 个 goroutine

验证:build / vet / gofmt / go test -race 全绿;
且在干净检出(git worktree)上单独 build + test 通过。
This commit is contained in:
JianFeeeee
2026-11-04 08:21:15 +08:00
parent 24b03e56e9
commit a02feaaff7
31 changed files with 3101 additions and 349 deletions

View File

@ -117,7 +117,7 @@ func TestResident_LifecycleAndNoOrphans(t *testing.T) {
}
// 子的轻量内核:有共同面、没有整理面。
c1 := parent.residents["child-1"]
c1 := parent.residentOf("child-1")
if c1.agent.memory != nil {
t.Fatal("驻留子不该有记忆整理面")
}
@ -181,7 +181,7 @@ func osStat(path string) (interface{}, error) {
func TestResident_DeliveryBothDirections(t *testing.T) {
parent, _, dir := newRootForResidents(t)
spawnTestResident(t, parent, dir, "child-1")
child := parent.residents["child-1"].agent
child := parent.residentOf("child-1").agent
// 父 → 子:发送消息 ⇒ 子在 **L4** 上收到(父是子的内核级来源)。
if err := parent.SendToResident("child-1", "先停一下,改做 X"); err != nil {
@ -207,7 +207,7 @@ func TestResident_DeliveryBothDirections(t *testing.T) {
func TestResident_InputchTableAutoAndProactive(t *testing.T) {
parent, _, dir := newRootForResidents(t)
spawnTestResident(t, parent, dir, "child-1")
child := parent.residents["child-1"].agent
child := parent.residentOf("child-1").agent
// 说明:create 会把任务提示词作为**第一条输入**投给子("create 即开工"),
// 所以这里先等那一轮写完 —— 表里每多一轮就多一条,正是"每轮必有记录"。
@ -255,7 +255,7 @@ func TestResident_ContextFullAndDispositions(t *testing.T) {
// ① contextfull:把子的**积累上下文**(a.context,不是拼好的消息)灌到超过窗口 90%。
// 注意不能靠"拼好的消息很大"来触发:拼装前时间线已被 token 预算裁到 ~80% 窗口。
spawnTestResident(t, parent, dir, "child-1")
rc := parent.residents["child-1"]
rc := parent.residentOf("child-1")
child := rc.agent
child.context.Append(ContextEvent{
Timestamp: time.Now(), Source: "sub/in",
@ -364,7 +364,7 @@ func TestResident_E2EAndStress(t *testing.T) {
t.Fatal(err)
}
} else {
parent.residents[id].agent.io.InjectInput("sub/"+id+"/in", "text",
parent.residentOf(id).agent.io.InjectInput("sub/"+id+"/in", "text",
map[string]interface{}{"content": msg})
}
}
@ -383,7 +383,7 @@ func TestResident_E2EAndStress(t *testing.T) {
// 双向通信在压力下也成立:让每个子都汇报一次(父侧 L3)。
for _, id := range ids {
parent.residents[id].agent.notifyParent("压力汇报 " + id)
parent.residentOf(id).agent.notifyParent("压力汇报 " + id)
}
waitForWithin(t, "父收到全部子的汇报", 10*time.Second, func() bool {
return parent.DumpScheduler().Stats.InterruptsByLevel[LevelInteractive] >= uint64(nResidents)
@ -442,7 +442,7 @@ func TestLightKernel_TraditionalContextNoTrimming(t *testing.T) {
provider := &captureProvider{}
parent, _, dir := newRootWith(t, provider)
spawnTestResident(t, parent, dir, "child-1")
child := parent.residents["child-1"].agent
child := parent.residentOf("child-1").agent
if !child.isLightKernel() {
t.Fatal("驻留子必须被识别为轻量内核")