mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-10-03 15:44:11 +00:00
82e8d9dbac
`ParallelSafe` / `Serial` / `stream_index` 三个新能力此前**零文档**： README 提到 `Serial` 的那处是 UART 串口，与并发声明无关。插件作者只能 读源码注释才能知道这些字段存在及其优先级。 ## docs/guide/parallel-tool-declaration.md - 保守 opt-in 的理由：存量插件不改一行就得串行，不会被升级意外并发 - 声明 `ParallelSafe` 的三个条件（线程安全 / 不争抢资源 / 顺序无关） - `Serial` 存在的意义：让"我确认过**必须**串行"与"我没想过"可区分 - **`Serial` 胜出**，不允许被 `ParallelSafe` 或默认值覆盖 - 声明字段放在 `ToolDef` 末尾，遵循既有 `NoMemory` 风格 - 压测效果 N=2/4/8 → 1.41×/2.22×/3.88×，并附"必须同时统计实际执行数" 的理由（旧适配器耗时更短但实际处理 0 个工具） ## docs/guide/stream-tool-call-index.md 面向写 Lua 适配器的人： - 上游 `index` 字段的用途：分桶累积 `id`/`name`/`arguments` - **键名是 `stream_index` 不是 `index`** —— 写错会被 Go 解码器静默丢弃 - 不透传的实际后果：name 互相覆盖、args 碎片混拼、工具被当空参数调用 - 顺带记两个易踩点：不能按 name 过滤分片；扁平结构的协议族同样要带 - 自检命令；并注明 `gemini.lua` 不涉及（协议是 `functionCall`） ## 其它 - `mkdocs.yml` nav 登记两篇 —— 之前它们会被 mkdocs 明确警告 "not included in the nav configuration"，等于在站点里不可达 - 重跑 `tools/apidoc/build.sh` 同步 `docs/api/*`、`llms.txt`（生成物） 核实过的事实，避免臆造： - 内置工具声明是**核心仓**的 `toolDefOptions`/`parallelOpts()` （`internal/agent/core/tooldefs.go`），不是 `sdk.BuiltinToolDef` —— 初稿写错 - `gemini.lua` 对 `functionCall|tool_calls` 匹配数为 0，确认无流式实现 - `server/kimicode/anthropic/ollama` 四个适配器确有 `stream_index`（2~5 处） - 跨仓相对链接不可解析，故改为纯文本路径指路 `docs/api/tools.md` 属生成物（首行注明"请勿手改"），其 `ToolDef` 签名被截断、 不展示字段 —— 这是生成器既有行为，本次 diff 只是行号漂移，未改它。
109 lines
3.6 KiB
Markdown
109 lines
3.6 KiB
Markdown
# 流式多 `tool_call`：适配器必须透传 `index`
|
||
|
||
> 面向在 Lua 里写适配器（`transform_stream_chunk`）的插件作者。
|
||
>
|
||
> 状态：已随 2026-09 的并行内核落地；生产 `openai.lua` 等适配器已修复。
|
||
|
||
## 1. 问题
|
||
|
||
OpenAI 兼容的流式响应里，同一轮的多个 `tool_call` 以**分片**形式到达，
|
||
靠 `index` 字段区分归属：
|
||
|
||
```
|
||
data: {"choices":[{"delta":{"tool_calls":[
|
||
{"index":0,"id":"call_a","function":{"name":"alpha","arguments":""}}]}}]}
|
||
|
||
data: {"choices":[{"delta":{"tool_calls":[
|
||
{"index":1,"id":"call_b","function":{"name":"beta","arguments":""}}]}}]}
|
||
|
||
data: {"choices":[{"delta":{"tool_calls":[
|
||
{"index":0,"function":{"arguments":"{\"x\":1}"}}]}}]}
|
||
|
||
data: {"choices":[{"delta":{"tool_calls":[
|
||
{"index":1,"function":{"arguments":"{\"y\":2}"}}]}}]}
|
||
```
|
||
|
||
**每个 SSE chunk 通常只含一个 `tool_call` 元素。** 内核按 `index` 分桶累积
|
||
`id` / `name` / `arguments`。
|
||
|
||
## 2. 适配器必须做的事
|
||
|
||
`transform_stream_chunk` 的输出 JSON 里，每个 tool call 分片都要带
|
||
**`stream_index`**（值取上游的 `index`）：
|
||
|
||
```lua
|
||
table.insert(tcs, {
|
||
id = tc.id or "",
|
||
type = tc.type or "function",
|
||
name = name,
|
||
raw_arguments = raw_args,
|
||
-- ★ 必须透传上游 index（键名是 stream_index，不是 index）。
|
||
-- 内核按 stream_index 分桶累积同一轮多个 tool_call 的分片。
|
||
stream_index = tc.index or 0
|
||
})
|
||
```
|
||
|
||
### ★ 键名是 `stream_index`，不是 `index`
|
||
|
||
内核的 `ToolCall.StreamIndex` 标签是 `json:"stream_index"`：
|
||
|
||
```go
|
||
StreamIndex int `json:"stream_index,omitempty"`
|
||
```
|
||
|
||
写成 `index` 会被 Go 的解码器**静默丢弃**（无匹配字段），
|
||
`StreamIndex` 恒为 0 ⇒ 全部落进 `accs[0]`。
|
||
|
||
## 3. 不透传的实际后果
|
||
|
||
不是"少个字段"，而是**多工具并行调用整体失效**：
|
||
|
||
| 现象 | 原因 |
|
||
| --- | --- |
|
||
| `name` 相互覆盖 | 全进 `accs[0]`，后写的赢 |
|
||
| `arguments` 碎片混拼 | 两个工具的 JSON 片段交错拼接 |
|
||
| 报"参数不是合法 JSON" | 上面拼接的产物解析失败 |
|
||
| 工具被当成**空参数**调用 | 同上 |
|
||
|
||
2026-09-27 的对照压测里，旧适配器耗时**更短**但**实际处理 0 个工具** ——
|
||
每个工具都因参数非法失败。⇒ 压测**必须同时统计实际执行数**，不能只看耗时。
|
||
|
||
## 4. 还有两个容易踩的点
|
||
|
||
**① 不能按 `name` 过滤分片**
|
||
|
||
```lua
|
||
-- ✗ 错：后续块的 name 为空但携带 arguments
|
||
if tc.function and tc.function.name then ... end
|
||
|
||
-- ✓ 对：无 name 但有 arguments 的分片也要收，累积时再校验 name
|
||
```
|
||
|
||
**② 扁平结构 + `stream_index`**
|
||
|
||
部分协议族（`server` / `kimicode` / `anthropic` / `ollama`）的流式 tool call
|
||
是**扁平**结构（`name`/`arguments` 直接在 `tc` 上，不在 `tc.function` 里），
|
||
同样要带 `stream_index`。
|
||
|
||
## 5. 自检
|
||
|
||
```bash
|
||
# 1) 适配器是否透传
|
||
grep -n "stream_index" /home/newqqagent/adapters/<你的>.lua
|
||
|
||
# 2) 实测：发一个同轮多工具的请求，看是否两个都真被执行
|
||
# 内核日志里 executing tool 应出现两次（可能并发）
|
||
journalctl -u homeagent.service --since "-2 min" | grep "executing tool"
|
||
|
||
# 3) 有没有参数解析失败
|
||
journalctl -u homeagent.service --since "-2 min" | grep -E "参数|合法 JSON"
|
||
```
|
||
|
||
> `gemini.lua` 目前**没有**流式 tool call 实现，因此不涉及本条。
|
||
> Gemini 协议是 `functionCall` 而非 `tool_calls`，不能照搬 OpenAI 的做法。
|
||
|
||
## 相关
|
||
|
||
- `docs/guide/parallel-tool-declaration.md` —— 并发声明 `ParallelSafe`/`Serial`
|
||
- 核心仓 `docs/zh/toolcall-parallel-execution-plan.md` —— 压测数据与协议族清单
|