diff --git a/docs/api/constants.md b/docs/api/constants.md index 399c74e..ed06875 100644 --- a/docs/api/constants.md +++ b/docs/api/constants.md @@ -30,6 +30,13 @@ SDK 里的取值枚举。其中带「仅内置」标注的取值在内核侧会 | `RecallPolicyNone` | | | `RecallPolicyAuto` | | +## ScenePolicyAuto 等 + +| 名称 | 说明 | +|---|---| +| `ScenePolicyAuto` | | +| `ScenePolicyNone` | | + ## PriorityL1 等 | 名称 | 说明 | diff --git a/docs/api/lifecycle.md b/docs/api/lifecycle.md index c43ebfc..74f84a7 100644 --- a/docs/api/lifecycle.md +++ b/docs/api/lifecycle.md @@ -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)` | `plugin.go:888` diff --git a/docs/api/settings.md b/docs/api/settings.md index 62403bd..d491de7 100644 --- a/docs/api/settings.md +++ b/docs/api/settings.md @@ -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{` | `plugin.go:505` diff --git a/docs/api/stages.md b/docs/api/stages.md index 779d649..b204560 100644 --- a/docs/api/stages.md +++ b/docs/api/stages.md @@ -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()` | `plugin.go:211` @@ -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()` | `plugin.go:212` diff --git a/docs/api/tools.md b/docs/api/tools.md index e27d76b..6618257 100644 --- a/docs/api/tools.md +++ b/docs/api/tools.md @@ -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{` | `plugin.go:557` diff --git a/docs/examples/index.md b/docs/examples/index.md index dbe4bab..9a2de68 100644 --- a/docs/examples/index.md +++ b/docs/examples/index.md @@ -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` diff --git a/docs/guide/parallel-tool-declaration.md b/docs/guide/parallel-tool-declaration.md new file mode 100644 index 0000000..f6b086b --- /dev/null +++ b/docs/guide/parallel-tool-declaration.md @@ -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` 相关） diff --git a/docs/guide/stream-tool-call-index.md b/docs/guide/stream-tool-call-index.md new file mode 100644 index 0000000..7eae132 --- /dev/null +++ b/docs/guide/stream-tool-call-index.md @@ -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` —— 压测数据与协议族清单 diff --git a/docs/llms.txt b/docs/llms.txt index a8e5992..a365b1c 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -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 位恒为 diff --git a/mkdocs.yml b/mkdocs.yml index 11c81a4..bff39eb 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -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