mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-09-30 14:23:00 +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 只是行号漂移，未改它。
78 lines
2.4 KiB
Markdown
78 lines
2.4 KiB
Markdown
<!-- 本页由 tools/apidoc/gensite 从源码生成，请勿手改；要改文档就改 sdk/*.go 的注释。 -->
|
||
|
||
# 工具（Tools）
|
||
|
||
注册 LLM 可调用的工具。工具是插件最主要的能力形态：模型看到 `ToolDef` 的说明后决定是否调用，调用时执行你的 `ToolHandler`。
|
||
|
||
### `ContentBlock`
|
||
|
||
```go
|
||
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 数组里带上图片/音频，实现"模型看图/听音频"。
|
||
|
||
<small>`plugin.go:954`</small>
|
||
|
||
### `PluginSDK.RegisterTool`
|
||
|
||
```go
|
||
func (s *PluginSDK) RegisterTool(name string, def ToolDef, handler ToolHandler) error
|
||
```
|
||
|
||
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:85` | `s.RegisterTool(tp+"video", sdk.ToolDef{` |
|
||
|
||
<small>`plugin.go:557`</small>
|
||
|
||
### `ToolCall`
|
||
|
||
```go
|
||
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.
|
||
|
||
<small>`plugin.go:227`</small>
|
||
|
||
### `ToolDef`
|
||
|
||
```go
|
||
type ToolDef struct { Name string `json:"name"` Plugin string `json:"plugin,omitempty"` Description string …
|
||
```
|
||
|
||
ToolDef describes a tool that the plugin exposes.
|
||
|
||
<small>`plugin.go:279`</small>
|
||
|
||
### `ToolHandler`
|
||
|
||
```go
|
||
type ToolHandler func(args map[string]interface{}) (interface{}, error)
|
||
```
|
||
|
||
ToolHandler is a function that handles a tool call.
|
||
|
||
<small>`plugin.go:20`</small>
|
||
|
||
### `ToolResult`
|
||
|
||
```go
|
||
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.
|
||
|
||
<small>`plugin.go:235`</small>
|
||
|