refactor(agent): R4 工作式子语义落地 + 清除 R1–R3 遗留的死代码

## 1. 工作式子的工具禁令收成单一事实来源

禁令此前写了两遍:定义侧(把工具从 childTools 滤掉)与执行侧
(模型硬调时拒绝)。两处名单必须逐字一致,任何一边落后就是真实缺口:

  定义侧漏滤 ⇒ 模型看得见但不该能用(白耗 token,还会反复试)
  执行侧漏拒 ⇒ 模型绕过定义直接调用**就能生效**

现在只有 workerForbidden 一张表,每条禁令把"匹配方式 + 类别 + 解释"
绑在一个结构体里;定义侧 workerToolAllowed、执行侧 workerToolReject
都从它派生。

上一版我用 reason 字符串 + 下标猜分类 + hint 查表做了三处间接,
属于新造的技术债,已重写为单表直查。

判据(均经变异验证):
  TestWorkerToolDenyListIsSingleSource  长出第二份名单 ⇒ 红(实测确认)
  TestWorkerToolAllowedMatchesReject    两侧判据漂移 ⇒ 红
  TestWorkerToolRejectExplainsWhy       拒绝文案不可执行 ⇒ 红

## 2. 删除零使用的抽象(不留技术债)

R1–R3 引入了 ChildKind / Host / Deliverer / DeviceResolver / ToolSpec /
ToolResult / DeclaredKinds / KindWorker / State / SetState / BumpRound /
ChannelDisposition,实现过程中发现它们是假抽象:

  · 各类型要用载体 Agent 的大半能力,要满足接口就得在实现里类型断言回 *Agent
  · 接口比被抽象的东西还大 ⇒ 只是把复杂度换个地方放
  · 实测:26 个导出符号里 20 个零使用、零实现

已删除 host.go 与 kind.go,并把"四种类型清单"和"转投驻留子为何不是类型"
这两个有价值的结论移进 kinds.go 的文档注释(知识保留,死代码删除)。

child 包现在只剩实际被用的 9 个符号:Kind / Child / Entry / Registry /
StopDeps / ErrChildExists / ErrChildNotFound(+ 2 个 Kind 常量)。

## 3. 修掉误导性签名

Entry.Dispose(policy ResidualPolicy) 里 policy **两个实现都不读** ——
残余处置实际走 ApplyResidual / FinishResidentWith,在 Dispose 之前就
已经完成。看签名会以为这里处理残余,是误导。已去掉该参数,
并删掉 child 包里重复定义的 ResidualPolicy(core 包已有一份,且多一个 stash)。

## 验证

  go build ./...                                  PASS
  go vet ./...                                    PASS
  gofmt -l                                        干净
  go test ./internal/agent/core/ -count=1         ok 15.300s
  go test ./internal/agent/core/ -count=1 -race   ok 18.040s
  干净检出(git worktree)单独 build + vet + test  PASS
This commit is contained in:
JianFeeeee
2026-11-04 08:35:23 +08:00
parent a02feaaff7
commit 637a3a3d3f
9 changed files with 279 additions and 419 deletions

View File

@ -1,87 +1,44 @@
package child
// kinds.go 记录**当前全部子 agent 类型**及其迁移归属。
// kinds.go 记录**当前全部子 agent 类型**及其归属。
//
// # 为什么要把这份清单写进代码而不是只写在 plan.md
// # 为什么这份清单必须以文档形式留在代码里
//
// 用户 2026-11-04 指出:"其他的哪几个子 agent 类型也要迁移"。
// 这个问题之所以要问,正是因为没有一份**唯一清单** ——
// 只能靠 grep `Spawn*` 反推,而反推会漏(工作式子叫 `runChildTask`,
// 前面没有 Spawn 前缀;转投驻留子是 `ensureOffloadResident`,
// 前面也没有 Spawn 前缀)。
// 用户曾问"其他的哪几个子 agent 类型也要迁移"。这个问题的存在本身说明
// 没有一份唯一清单 —— 只能靠 grep `Spawn*` 反推,而反推会漏:
//
// 所以清单必须在这里,且与 Kind 常量一一对应。新增类型时:
// 1. 在这里加一个 Kind + 一行说明
// 2. 实现 ChildKind
// 3. 装配期 Register
// 漏了第 2/3 步时 Register 不会报错但路由会走兜底 —— 由
// TestAllDeclaredKindsAreRegistered 钉住。
// 工作式子 入口叫 runChildTask,前面没有 Spawn 前缀 ⇒ grep 会漏
// 转投驻留子 入口叫 ensureOffloadResident,同样没有前缀 ⇒ grep 会漏
//
// # 四种类型的实际形态(2026-11-04 实测)
//
// 类型 入口 载体 独立IO 通道 子策略 上下文
// 主 agent New() *Agent(完整) 有 有 - 相关性
// 驻留子 SpawnResident 完整 *Agent + Start 有 有 有 RelevanceContext
// rtchild SpawnRTChild 完整 *Agent 不 Start 有 有 有 跨轮 history
// 工作式子 runChildTask goroutine + 局部msgs 无 无 无 局部 msgs
// 转投驻留子 ensureOffloadResident = 驻留子(offloadOwned=true 标记)
// 类型 入口 载体 独立IO 通道 登记表
// 主 agent New() *Agent(完整) 有 有 -
// 驻留子 SpawnResident 完整 *Agent + Start 有 有 children(KindResident)
// rtchild SpawnRTChild 完整 *Agent 不 Start 有 有 children(KindRT)
// 工作式子 runChildTask goroutine + 局部msgs 无 无 ✗(见下)
// 转投驻留子 ensureOffloadResident = 驻留子 有 有 children(KindResident)
//
// ★ 迁移范围(用户裁定"注意其他的哪几个子 agent 类型也要迁移"):
// # 为什么这里没有 KindWorker 常量
//
// 必须迁(有独立生命周期与登记状态):驻留子、rtchild、工作式子
// 不需要独立 Kind(是驻留子的一个变体):转投驻留子
// 工作式子**不进** children 登记表,因此不需要类型标签:
//
// 工作式子**不走骨架的 spawn**(它没有 io/通道/策略,也不需要登记进
// 通道归属表),但它的**执行循环**必须走共享的 runToolBatch ——
// 这是 ChildKind.RunTools 的职责,与"是否登记进 Registry"无关。
// 以下常量在 child.go 的 Kind 定义里已有 KindResident / KindRT,
// 这里只补尚未迁移的那几种的**规划标签**(迁移前不注册实现)。
const (
// KindWorker 是一次性工作式子 agent(spawn_child / runChildTask)。
//
// 与其余三种的结构差异(实测):
// · 无独立 IOManager(工具直接走父的 executeToolCall)
// · 无通道(不注册 inputch,父被显式剥掉 output_send__*)
// · 无子策略声明(不存在 declareChildPolicy 调用)
// · 上下文是**局部 msgs**,跑完即弃(父可按 taskID 取回结果,有界淘汰 20 条)
//
// ⇒ 它**不需要**进 Registry(没有通道归属要路由),但需要 ChildKind 的
// RunTools / BuildContext 两处语义。
KindWorker Kind = "worker"
// KindOffload 是 Kernel 为承接积压自动拉起的驻留子(offload.go)。
//
// ★ **它不是一种类型,是对驻留子的一种特殊调用。**
//
// 依据(offload.go:293 ensureOffloadResident):
//
// info, err := a.SpawnResident(ResidentOptions{
// ID: "offload-<unix>",
// InputChs: nil, // 不接插件输入,只由父转投
// AllowedOutputs: nil, // 完整输出授权(要能回发到原通道)
// TempPath: a.residentTempPath(id),
// OffloadOwned: true, // ← 唯一的“特殊”标在这里
// TaskPrompt: offloadTaskPrompt(),
// })
//
// 走的完全是驻留子那一条路(同样的 spawn / 同样的登记表 / 同样的 memory 装配),
// 差异只有两处,且都已在 ResidentOptions 上表达:
//
// ① OffloadOwned 布尔标记 —— 只影响“能否被自动复用 / 是否计入上限”,
// 不影响任何生命周期语义(不能拿去复用人工建的子,也不占用它们的名额)
// ② TaskPrompt 是分诊职责说明 —— 纯粹是提示词内容,不是机制
//
// ⇒ 因此**不应**为它新增 Kind。若新增,就得为它写一份 ChildKind,
// 那份实现会与驻留子的实现逐字重复(除了一个 bool),
// 而我们正要消灭“同一份逻辑写两遍、然后漂移”这个形态。
//
// 判据 TestOffloadIsNotItsOwnKind 钉住这条:DeclaredKinds() 里不得出现它。
)
// DeclaredKinds 返回**应当被注册**的全部类型标签(测试与装配自检用)。
// · 它没有 io、没有通道、没有子策略 ⇒ 不需要"按通道归属路由"
// · 它的 `childTasks` 是**已完成任务的幂等结果缓存**(child_result 要能
// 重复查询 + 20 条有界淘汰),语义与"存活登记"完全不同
// · 塞进 registry 会让 StopAll 去 Dispose 一个已经跑完的实例,
// 并把结果缓存一起清掉 ⇒ child_result 立刻变成"不存在",
// 模型会无限重试(实测单轮 35 次工具调用、持续 514 秒)
//
// 不含 KindOffload(它是驻留子变体),不含主 agent(它不是子)。
func DeclaredKinds() []Kind {
return []Kind{KindResident, KindRT, KindWorker}
}
// 曾定义过 `KindWorker` 常量,实测零使用,已删除(不留技术债)。
//
// # 为什么转投驻留子不是独立类型
//
// `ensureOffloadResident` 走的就是 `SpawnResident`,差异只有两处,
// 且都已在 ResidentOptions 上表达:
//
// ① OffloadOwned 布尔标记 —— 只影响"能否被自动复用 / 是否计入上限"
// ② TaskPrompt 是分诊职责说明 —— 纯粹是提示词内容,不是机制
//
// 若为它新增类型,那份实现会与驻留子逐字重复(除了一个 bool),
// 而我们在消灭的正是"同一份逻辑写两遍、然后漂移"这个形态。