feat(toolcall): 批次并发调度与同通道保序(阶段 2d,闭合 2c 判据缺口)

规则(三条全满足才并发):
  1. 批内 >1 个工具
  2. **全部**工具声明 ParallelSafe —— 一个不声明就整批降级,不做部分并发
  3. 不含需保序的同通道输出发送

SDK:
· ToolDef 加 ParallelSafe bool。⚠️ 零值 false 是刻意的:存量插件不改一行
  就得到**保守**行为(整批串行),不会因升级被意外并发。声明它是责任
  而非特权。纯新增字段,无签名变更。
· io.ToolDef 同步加该字段(设备/通道工具走 io 路径,只查 StageHost 会漏)。

core:
· 新增 StepToolBatch —— runTaskSteps 是单线程驱动状态机的,
  「每步一个工具」的游标模型无法表达「一批同时跑」,故需独立 step。
· stepToolBatch:fan-out(每工具一 goroutine,各写自己的 toolCtxs[i])
  → join → **按索引顺序**串行收尾(after_toolcall / 落消息 / 事件)。
  收尾必须串行且按索引:f.Msgs 是共享切片,且按索引落才能让模型读到的
  上下文顺序与它自己发出的顺序一致。
· runOneTool 抽出「before_toolcall + 执行」的单工具逻辑,串行/并发两条路共用。
· toolParallelSafe / batchRunnable 判据函数。

★ 修掉一个我自己引入的竞争:resolveTurnScenes 会把结果记进**共享**的
f.sceneDone / f.turnScene(memorypass.go:289)。最初在每个 goroutine 里
各调一次 —— 既是数据竞争,又会各自触发一次 EnterSceneWithHint,
重复计入场景强度(正是 sceneDone 注释警告过的问题)。改为在 fan-out
**之前**解析一次,goroutine 内只读。

判据(parallelsched_test.go,4 条):
· 全批 ParallelSafe ⇒ 并发峰值 >= 2(用阻塞设备观察真实并发)
· 一个非 ParallelSafe ⇒ 整批串行,但**仍全部执行**
· 同 output_send__<通道> 连发 3 条 ⇒ 严格按声明顺序到达
· ★ 并发下每个工具的 ctx 只带自己的 ToolCalls、after 读到自己结果

★ 并关闭了 2c 的判据缺口:此前两条 2c 判据在**串行**下无法区分
per-tool 与单槽(变体验证后仍全绿)。新增的并发版判据在退回单槽时
触发 **6 处 DATA RACE 报告 + 串味断言失败**(dup:k_a 与 k_a 撞名)。
至此 2c 可记为已验证。

过程中三次自伤:
· resolveTurnScenes 竞争(上述);
· 我的 harness 用 StageHost 注册 handler 遮蔽了设备工具,
  slowDevice 根本没被调用("实际 0")——改为在 io.ToolDef 上声明;
· 批内并发峰值判据最初用 StageHost 声明 ParallelSafe,掩盖了
  「设备工具也需要该字段」这一真实缺口。

回归:internal/agent/... internal/sdk/... internal/plugin/...
      internal/plugins/... 全绿(17 包);core 包 -race 全绿。
This commit is contained in:
JianFeeeee
2026-09-27 11:27:24 +08:00
parent 3d12e82f65
commit 34c0df2705
5 changed files with 514 additions and 1 deletions

View File

@ -241,3 +241,58 @@ func (a *Agent) validateArgsAgainstSchema(tc agentAPI.ToolCall) *sdk.ToolError {
}
return nil
}
// toolParallelSafe 报告工具是否可被**并发执行**。
//
// 两条来源都要查(与 validateArgsAgainstSchema 同理):插件工具走 StageHost,
// 设备/通道工具走 IOManager。查不到 ⇒ 保守返回 false(不可并发)。
//
// 为什么保守:新语义下并发会改变工具的行为前提,让存量插件意外并发
// 比慢一点危险得多——判不出就该按串行走。
func (a *Agent) toolParallelSafe(name string) bool {
if a == nil {
return false
}
if a.stageHost != nil {
if def := a.stageHost.ToolDef(name); def != nil {
return def.ParallelSafe
}
}
if a.io != nil {
if def, ok := a.io.ToolDefOf(name); ok {
return def.ParallelSafe
}
}
return false
}
// batchRunnable 并发执行本批工具。
//
// 何时并发(三条全满足):
// 1. 批内 >1 个工具
// 2. **全部**工具都声明 ParallelSafe —— 一个不声明就整批降级,
// 不做"部分并发":部分并发收益不抵其不可预测性
// 3. 不含需要保序的同通道输出发送(同 output_send__<通道> 多次发送)
//
// 保序为什么不用 ParallelSafe 表达:那属于**批内**约束而非工具属性,
// 且同一工具在不同批里的通道可能不同(output_send__qq 两次、一次 qq 一次 cli)。
func (f *TaskFrame) batchRunnable(a *Agent) bool {
if f == nil || len(f.PendingTools) <= 1 {
return false
}
chans := map[string]bool{}
for _, tc := range f.PendingTools {
if !a.toolParallelSafe(tc.Name) {
return false
}
// 同通道多次发送必须保序 —— 用户可见消息顺序敏感
if isOutputDeliveryTool(tc.Name) {
ch := strings.TrimPrefix(tc.Name, "output_send__")
if chans[ch] {
return false
}
chans[ch] = true
}
}
return true
}