mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-10-03 07:34:23 +00:00
docs: 补两篇指南 —— 工具并发声明、流式多 tool_call
`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 只是行号漂移，未改它。
This commit is contained in:
JianFeeeee
@ -30,6 +30,13 @@ SDK 里的取值枚举。其中带「仅内置」标注的取值在内核侧会
|
||||
| `RecallPolicyNone` | |
|
||||
| `RecallPolicyAuto` | |
|
||||
|
||||
## ScenePolicyAuto 等
|
||||
|
||||
| 名称 | 说明 |
|
||||
|---|---|
|
||||
| `ScenePolicyAuto` | |
|
||||
| `ScenePolicyNone` | |
|
||||
|
||||
## PriorityL1 等
|
||||
|
||||
| 名称 | 说明 |
|
||||
|
||||
@ -203,7 +203,7 @@ SetAutoRestart 设置插件崩溃后内核是否自动重启它。
|
||||
| [`a2a`](../examples/index.md#a2a) | `example/a2a/plugin.go:47` | `s.SetAutoRestart(true)` |
|
||||
| [`acp`](../examples/index.md#acp) | `example/acp/plugin.go:47` | `s.SetAutoRestart(true)` |
|
||||
| [`ai_image`](../examples/index.md#ai_image) | `example/ai_image/plugin.go:110` | `s.SetAutoRestart(true)` |
|
||||
| [`bili`](../examples/index.md#bili) | `example/bili/plugin.go:25` | `s.SetAutoRestart(true)` |
|
||||
| [`bili`](../examples/index.md#bili) | `example/bili/plugin.go:63` | `s.SetAutoRestart(true)` |
|
||||
|
||||
<small>`plugin.go:888`</small>
|
||||
|
||||
|
||||
@ -191,7 +191,7 @@ sett 在 New 时一次性写入且无 setter，故不需要加锁。
|
||||
| [`a2a`](../examples/index.md#a2a) | `example/a2a/plugin.go:68` | `s.Settings().RegisterDef(sdk.ConfigDef{` |
|
||||
| [`acp`](../examples/index.md#acp) | `example/acp/plugin.go:63` | `s.Settings().RegisterDef(sdk.ConfigDef{` |
|
||||
| [`ai_image`](../examples/index.md#ai_image) | `example/ai_image/plugin.go:114` | `s.Settings().RegisterDef(sdk.ConfigDef{` |
|
||||
| [`bili`](../examples/index.md#bili) | `example/bili/plugin.go:29` | `s.Settings().RegisterDef(sdk.ConfigDef{` |
|
||||
| [`bili`](../examples/index.md#bili) | `example/bili/plugin.go:67` | `s.Settings().RegisterDef(sdk.ConfigDef{` |
|
||||
|
||||
<small>`plugin.go:505`</small>
|
||||
|
||||
|
||||
@ -24,8 +24,8 @@ func (c *StageContext) Lock()
|
||||
|---|---|---|
|
||||
| [`a2a`](../examples/index.md#a2a) | `example/a2a/plugin.go:158` | `p.sessMu.Lock()` |
|
||||
| [`acp`](../examples/index.md#acp) | `example/acp/plugin.go:128` | `p.srvMu.Lock()` |
|
||||
| [`bili`](../examples/index.md#bili) | `example/bili/plugin.go:37` | `p.runMu.Lock()` |
|
||||
| [`browser`](../examples/index.md#browser) | `example/browser/plugin.go:427` | `p.mu.Lock()` |
|
||||
| [`calendar`](../examples/index.md#calendar) | `example/calendar/plugin.go:433` | `p.mu.Lock()` |
|
||||
|
||||
<small>`plugin.go:211`</small>
|
||||
|
||||
@ -147,8 +147,8 @@ func (c *StageContext) Unlock()
|
||||
|---|---|---|
|
||||
| [`a2a`](../examples/index.md#a2a) | `example/a2a/plugin.go:164` | `p.sessMu.Unlock()` |
|
||||
| [`acp`](../examples/index.md#acp) | `example/acp/plugin.go:129` | `defer p.srvMu.Unlock()` |
|
||||
| [`bili`](../examples/index.md#bili) | `example/bili/plugin.go:40` | `p.runMu.Unlock()` |
|
||||
| [`browser`](../examples/index.md#browser) | `example/browser/plugin.go:432` | `p.mu.Unlock()` |
|
||||
| [`calendar`](../examples/index.md#calendar) | `example/calendar/plugin.go:523` | `p.mu.Unlock()` |
|
||||
|
||||
<small>`plugin.go:212`</small>
|
||||
|
||||
|
||||
@ -31,7 +31,7 @@ RegisterTool registers a tool that the LLM can call.
|
||||
| [`a2a`](../examples/index.md#a2a) | `example/a2a/plugin.go:76` | `s.RegisterTool(tp+"a2a_query", sdk.ToolDef{` |
|
||||
| [`acp`](../examples/index.md#acp) | `example/acp/plugin.go:70` | `s.RegisterTool(tp+"acp_query", sdk.ToolDef{` |
|
||||
| [`ai_image`](../examples/index.md#ai_image) | `example/ai_image/plugin.go:159` | `s.RegisterTool(tp+"generate", sdk.ToolDef{` |
|
||||
| [`bili`](../examples/index.md#bili) | `example/bili/plugin.go:47` | `s.RegisterTool(tp+"video", sdk.ToolDef{` |
|
||||
| [`bili`](../examples/index.md#bili) | `example/bili/plugin.go:85` | `s.RegisterTool(tp+"video", sdk.ToolDef{` |
|
||||
|
||||
<small>`plugin.go:557`</small>
|
||||
|
||||
|
||||
@ -20,7 +20,7 @@ SDK 仓 `example/` 下有多个**真实可编译**的示例插件，覆盖工具
|
||||
|
||||
## `bili`
|
||||
|
||||
用到的 API：`RegisterTool` · `SetAutoRestart` · `Settings`
|
||||
用到的 API：`Lock` · `RegisterTool` · `SetAutoRestart` · `Settings` · `Unlock`
|
||||
|
||||
## `browser`
|
||||
|
||||
@ -28,7 +28,7 @@ SDK 仓 `example/` 下有多个**真实可编译**的示例插件，覆盖工具
|
||||
|
||||
## `calendar`
|
||||
|
||||
用到的 API：`InjectInterruptTextOpts` · `Lock` · `RLock` · `RUnlock` · `RegisterInputChannel` · `RegisterOnRemoveHandler` · `RegisterStopHandler` · `Unlock`
|
||||
用到的 API：`InjectInterruptTextOpts` · `RLock` · `RUnlock` · `RegisterInputChannel` · `RegisterOnRemoveHandler` · `RegisterStopHandler`
|
||||
|
||||
## `deepsearch`
|
||||
|
||||
|
||||
112
docs/guide/parallel-tool-declaration.md
Normal file
112
docs/guide/parallel-tool-declaration.md
Normal file
@ -0,0 +1,112 @@
|
||||
# 工具并发声明：`ParallelSafe` / `Serial`
|
||||
|
||||
> 对应 `sdk.ToolDef` 的两个字段。内核在**同一轮**收到多个 `tool_call` 时，
|
||||
> 依据它们决定并发还是整批串行。
|
||||
>
|
||||
> 状态：已随 2026-09 的并行内核落地并在生产启用。
|
||||
|
||||
## 1. 为什么是"保守 opt-in"
|
||||
|
||||
**默认整批串行。** 只有当**批内每一个**工具都显式声明 `ParallelSafe: true`
|
||||
时，那一批才并发；**只要有一个不声明，整批退回串行**。
|
||||
|
||||
这不是"漏了声明导致退化"的将就，而是刻意的设计：
|
||||
|
||||
- 存量插件**不改一行**就得到保守行为（整批串行），不会被升级意外并发
|
||||
- 声明是**责任**而非特权 —— 声明者必须自己确认线程安全
|
||||
- 宁可慢，不可错：一次错误的并发可能让两个工具抢同一个 SQLite 写、
|
||||
同一台设备、或同一个输出通道
|
||||
|
||||
```go
|
||||
// 同批全是安全工具 → 并发
|
||||
tools: [a(ParallelSafe), b(ParallelSafe)] ⇒ 并发
|
||||
|
||||
// 只要有一个没声明 → 整批串行
|
||||
tools: [a(ParallelSafe), b(默认)] ⇒ 串行
|
||||
```
|
||||
|
||||
## 2. 三个条件都满足才可以声明 `ParallelSafe`
|
||||
|
||||
1. **handler 自身线程安全** —— 不持有跨调用的可变状态
|
||||
2. **不与同批其它工具争抢同一资源** —— SQLite 写、设备、同一输出通道
|
||||
3. **执行顺序无关** —— 顺序敏感的工具应留 `false`，由内核保序
|
||||
|
||||
第 3 条常被忽略：内核能保证**用户可见的消息**按声明顺序落盘，但**工具
|
||||
之间的实际执行先后**在并发模式下不确定。有顺序依赖就留 `false`。
|
||||
|
||||
## 3. `Serial`：显式的反向标记
|
||||
|
||||
```go
|
||||
Serial bool `json:"serial,omitempty"`
|
||||
```
|
||||
|
||||
`ParallelSafe` 的零值 `false` 已经表达"串行"，插件**无法区分**：
|
||||
|
||||
- "我没想过"
|
||||
- "我确认过**必须**串行，且有原因"
|
||||
|
||||
一旦工具作者需要把"这里**故意**串行，是有原因的"写进代码（而不只是没填），
|
||||
这个区分就是必需的 —— 否则只能靠命名约定传递意图。
|
||||
|
||||
适用场景：读操作但有隐含顺序约束（终端 `read`/`resize` 这类共享会话
|
||||
状态）；写操作虽已加锁但需要串行以获得可预测的交错顺序。
|
||||
|
||||
**优先级：`Serial` 胜出。** 即使同时写了 `ParallelSafe: true`，`Serial`
|
||||
仍然生效 —— 显式声明"必须串行"不允许被 `ParallelSafe` 或任何默认值覆盖。
|
||||
|
||||
## 4. 写法
|
||||
|
||||
声明字段放在 `ToolDef` 结构体的**末尾**，遵循既有 `NoMemory` 的风格：
|
||||
|
||||
```go
|
||||
sdk.RegisterTool(sdk.ToolDef{
|
||||
Name: "my_readonly_query",
|
||||
Description: "……",
|
||||
Parameters: map[string]interface{}{"type": "object", "properties": map[string]interface{}{}},
|
||||
Handler: h.query,
|
||||
ParallelSafe: true, // 声明在末尾
|
||||
}, s)
|
||||
```
|
||||
|
||||
需要"故意串行"时：
|
||||
|
||||
```go
|
||||
sdk.RegisterTool(sdk.ToolDef{
|
||||
Name: "my_terminal_input",
|
||||
Handler: h.input,
|
||||
Serial: true, // 胜出，忽略 ParallelSafe
|
||||
}, s)
|
||||
```
|
||||
|
||||
## 5. 内置工具
|
||||
|
||||
核心仓的内置工具用 `toolDefOptions` / `parallelOpts()` 声明
|
||||
（`internal/agent/core/tooldefs.go`），最终由 `buildToolDefs` 汇总成
|
||||
`ToolDef.ParallelSafe`。
|
||||
|
||||
内核只提供并行调度基础设施，**不硬编码任何工具名的安全状态表** ——
|
||||
状态由每个工具在自己的声明结构里给出，查询时走聚合表。
|
||||
|
||||
## 6. 效果（实测）
|
||||
|
||||
同批 N 个各约 250ms 的工具，新版内核"内部并发"对"强制串行"：
|
||||
|
||||
| N | 加速比 |
|
||||
| --- | --- |
|
||||
| 2 | ~1.41× |
|
||||
| 4 | ~2.22× |
|
||||
| 8 | ~3.88× |
|
||||
|
||||
批耗时几乎不随 N 增长，串行批严格线性。
|
||||
|
||||
> 压测时**必须同时记录实际执行的工具数**，不能只看耗时。
|
||||
> 某次对照中旧版本耗时更短、但因适配器缺 `stream_index` 导致
|
||||
> **实际处理 0 个工具** —— 那不是性能提升，是全失败。
|
||||
|
||||
## 相关
|
||||
|
||||
设计背景与踩坑见**核心仓**文档（不在本仓）：
|
||||
|
||||
- `docs/zh/toolcall-contract-and-sequence-design.md` —— 契约与序列设计
|
||||
- `docs/zh/toolcall-parallel-execution-plan.md` —— 阶段、实测压测数据
|
||||
- `docs/zh/deploy-runbook.md` —— 生产部署（含适配器 `stream_index` 相关）
|
||||
108
docs/guide/stream-tool-call-index.md
Normal file
108
docs/guide/stream-tool-call-index.md
Normal file
@ -0,0 +1,108 @@
|
||||
# 流式多 `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` —— 压测数据与协议族清单
|
||||
@ -29,6 +29,8 @@
|
||||
- [环境与工具链](https://sdk.homeagent.jianfgit.xyz/guide/getting-started.md): hmapdev 是 SDK 仓提供的统一插件开发工具链，Go 与 Lua 两种插件都用它，
|
||||
- [多平台构建](https://sdk.homeagent.jianfgit.xyz/guide/multi-platform.md): hmapdev build 默认 bundle 模式，一次产出含三个平台的单个
|
||||
- [打包与发布](https://sdk.homeagent.jianfgit.xyz/guide/packaging.md): hmapdev build 一次完成编译与打包，产出
|
||||
- [工具并发声明：`ParallelSafe` / `Serial`](https://sdk.homeagent.jianfgit.xyz/guide/parallel-tool-declaration.md): > 对应 sdk
|
||||
- [场景记忆（Scene Memory）](https://sdk.homeagent.jianfgit.xyz/guide/scene-memory.md): > 场景式记忆是内核 v1
|
||||
- [受限 SDK 与安全](https://sdk.homeagent.jianfgit.xyz/guide/security.md): 外部插件与内置插件的区别不只是「能不能调某个函数」，还包含一层安全边界：
|
||||
- [流式多 `tool_call`：适配器必须透传 `index`](https://sdk.homeagent.jianfgit.xyz/guide/stream-tool-call-index.md): > 面向在 Lua 里写适配器（transform_stream_chunk）的插件作者
|
||||
- [版本与兼容](https://sdk.homeagent.jianfgit.xyz/versions.md): SDK 版本跟随内核的中版本，patch 位恒为
|
||||
|
||||
@ -120,6 +120,8 @@ nav:
|
||||
- 仅内置插件可用: api/builtin-only.md
|
||||
- 指南:
|
||||
- 能力边界（哪些 API 外部可用）: guide/capability-boundary.md
|
||||
- 工具并发声明（ParallelSafe/Serial）: guide/parallel-tool-declaration.md
|
||||
- 流式多 tool_call（适配器透传 index）: guide/stream-tool-call-index.md
|
||||
- 场景记忆（按场合召回）: guide/scene-memory.md
|
||||
- 打包与发布: guide/packaging.md
|
||||
- 多平台构建: guide/multi-platform.md
|
||||
|
||||
Reference in New Issue
Block a user