mirror of https://gitcode.com/JianFeeeee/homeagent-sdk.git synced 2026-09-30 14:23:00 +00:00

Files

JianFeeeee 82e8d9dbac 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 只是行号漂移，未改它。

2026-09-27 22:25:38 +08:00

2.4 KiB

Raw Blame History

工具（Tools）

`ContentBlock`

type ContentBlock struct { Type string `json:"type"` Text string `json:"text,omitempty"` ImageURL *ImageURL `json:"image_url,omitempty"` AudioURL *AudioURL `jso …

ContentBlock 是多模态内容块（OpenAI 格式：text/image_url/audio_url）。插件工具返回结果时可用 PluginSDK.SetToolBlocks 注入，让下一轮 LLM 请求在 tool message 的 content 数组里带上图片/音频，实现"模型看图/听音频"。

plugin.go:954

`PluginSDK.RegisterTool`

func (s *PluginSDK) RegisterTool(name string, def ToolDef, handler ToolHandler) error

RegisterTool registers a tool that the LLM can call.

示例插件里的真实用法

插件	位置	代码
`a2a`	`example/a2a/plugin.go:76`	`s.RegisterTool(tp+"a2a_query", sdk.ToolDef{`
`acp`	`example/acp/plugin.go:70`	`s.RegisterTool(tp+"acp_query", sdk.ToolDef{`
`ai_image`	`example/ai_image/plugin.go:159`	`s.RegisterTool(tp+"generate", sdk.ToolDef{`
`bili`	`example/bili/plugin.go:85`	`s.RegisterTool(tp+"video", sdk.ToolDef{`

plugin.go:557

`ToolCall`

type ToolCall struct { ID string `json:"id"` Name string `json:"name"` Plugin string `json:"plugin,omitempty …

ToolCall represents a model's request to call a tool.

plugin.go:227

`ToolDef`

type ToolDef struct { Name string `json:"name"` Plugin string `json:"plugin,omitempty"` Description string …

ToolDef describes a tool that the plugin exposes.

plugin.go:279

`ToolHandler`

type ToolHandler func(args map[string]interface{}) (interface{}, error)

ToolHandler is a function that handles a tool call.

plugin.go:20

`ToolResult`

type ToolResult struct { CallID string `json:"call_id"` Name string `json:"name"` Plugin string `json:"plugin,omitempty"` Success bool `json:"suc …

ToolResult represents the result of a tool call.

plugin.go:235

2.4 KiB Raw Blame History Unescape Escape

工具（Tools）

ContentBlock

PluginSDK.RegisterTool

ToolCall

ToolDef

ToolHandler

ToolResult