mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-11-06 17:27:31 +00:00
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:
@ -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),
|
||||
// 而我们在消灭的正是"同一份逻辑写两遍、然后漂移"这个形态。
|
||||
|
||||
Reference in New Issue
Block a user