mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-09-30 06:13:14 +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 只是行号漂移，未改它。
198 lines
4.9 KiB
Markdown
198 lines
4.9 KiB
Markdown
<!-- 本页由 tools/apidoc/gensite 从源码生成，请勿手改；要改文档就改 sdk/*.go 的注释。 -->
|
||
|
||
# 配置（Settings）
|
||
|
||
声明插件自己的配置项，内核会把它渲染到 WebUI 的设置页，并为每个插件维护独立的配置表。
|
||
|
||
## `SettingsAPI`
|
||
|
||
| 方法 | 说明 |
|
||
|---|---|
|
||
| [`DataDir`](#settingsapidatadir) | DataDir returns the plugin-specific data directory (guaranteed to exist): |
|
||
| [`Defs`](#settingsapidefs) | Defs returns config definitions matching the prefix. |
|
||
| [`Dump`](#settingsapidump) | Dump returns all config values. |
|
||
| [`Get`](#settingsapiget) | Get reads the plugin's own config value (config_<name> table). |
|
||
| [`GetCore`](#settingsapigetcore) | GetCore reads the core config table. |
|
||
| [`GetPlugin`](#settingsapigetplugin) | GetPlugin reads another plugin's config table. |
|
||
| [`List`](#settingsapilist) | List returns all keys matching the given prefix. |
|
||
| [`ListCore`](#settingsapilistcore) | ListCore lists core config keys matching the prefix. |
|
||
| [`ListPlugin`](#settingsapilistplugin) | ListPlugin lists another plugin's config keys matching the prefix. |
|
||
| [`Plugins`](#settingsapiplugins) | Plugins returns a list of all plugin config namespaces. |
|
||
| [`RegisterDef`](#settingsapiregisterdef) | RegisterDef registers a config definition for UI display. |
|
||
| [`Set`](#settingsapiset) | Set writes a config value to the plugin's own config table. |
|
||
| [`SetCore`](#settingsapisetcore) | SetCore writes to the core config table. |
|
||
| [`SetPlugin`](#settingsapisetplugin) | SetPlugin writes to another plugin's config table. |
|
||
|
||
### `SettingsAPI.DataDir`
|
||
|
||
```go
|
||
DataDir() string
|
||
```
|
||
|
||
DataDir returns the plugin-specific data directory (guaranteed to exist):
|
||
<daemon data>/plugin_data/<plugin_name>. Plugins should persist any
|
||
runtime files (generated images, caches, downloads) here.
|
||
|
||
<small>`settings.go:25`</small>
|
||
|
||
### `SettingsAPI.Defs`
|
||
|
||
```go
|
||
Defs(prefix string) []*ConfigDef
|
||
```
|
||
|
||
Defs returns config definitions matching the prefix.
|
||
|
||
<small>`settings.go:40`</small>
|
||
|
||
### `SettingsAPI.Dump`
|
||
|
||
```go
|
||
Dump() map[string]interface{}
|
||
```
|
||
|
||
Dump returns all config values.
|
||
|
||
<small>`settings.go:43`</small>
|
||
|
||
### `SettingsAPI.Get`
|
||
|
||
```go
|
||
Get(key string) (interface{}, error)
|
||
```
|
||
|
||
Get reads the plugin's own config value (config_<name> table).
|
||
|
||
<small>`settings.go:5`</small>
|
||
|
||
### `SettingsAPI.GetCore`
|
||
|
||
```go
|
||
GetCore(key string) (interface{}, error)
|
||
```
|
||
|
||
GetCore reads the core config table.
|
||
|
||
<small>`settings.go:14`</small>
|
||
|
||
### `SettingsAPI.GetPlugin`
|
||
|
||
```go
|
||
GetPlugin(plugin, key string) (interface{}, error)
|
||
```
|
||
|
||
GetPlugin reads another plugin's config table.
|
||
|
||
<small>`settings.go:28`</small>
|
||
|
||
### `SettingsAPI.List`
|
||
|
||
```go
|
||
List(prefix string) ([]string, error)
|
||
```
|
||
|
||
List returns all keys matching the given prefix.
|
||
|
||
<small>`settings.go:11`</small>
|
||
|
||
### `SettingsAPI.ListCore`
|
||
|
||
```go
|
||
ListCore(prefix string) ([]string, error)
|
||
```
|
||
|
||
ListCore lists core config keys matching the prefix.
|
||
|
||
<small>`settings.go:20`</small>
|
||
|
||
### `SettingsAPI.ListPlugin`
|
||
|
||
```go
|
||
ListPlugin(plugin, prefix string) ([]string, error)
|
||
```
|
||
|
||
ListPlugin lists another plugin's config keys matching the prefix.
|
||
|
||
<small>`settings.go:34`</small>
|
||
|
||
### `SettingsAPI.Plugins`
|
||
|
||
```go
|
||
Plugins() []string
|
||
```
|
||
|
||
Plugins returns a list of all plugin config namespaces.
|
||
|
||
<small>`settings.go:46`</small>
|
||
|
||
### `SettingsAPI.RegisterDef`
|
||
|
||
```go
|
||
RegisterDef(def ConfigDef)
|
||
```
|
||
|
||
RegisterDef registers a config definition for UI display.
|
||
|
||
<small>`settings.go:37`</small>
|
||
|
||
### `SettingsAPI.Set`
|
||
|
||
```go
|
||
Set(key string, value interface{}) error
|
||
```
|
||
|
||
Set writes a config value to the plugin's own config table.
|
||
|
||
<small>`settings.go:8`</small>
|
||
|
||
### `SettingsAPI.SetCore`
|
||
|
||
```go
|
||
SetCore(key string, value interface{}) error
|
||
```
|
||
|
||
SetCore writes to the core config table.
|
||
|
||
<small>`settings.go:17`</small>
|
||
|
||
### `SettingsAPI.SetPlugin`
|
||
|
||
```go
|
||
SetPlugin(plugin, key string, value interface{}) error
|
||
```
|
||
|
||
SetPlugin writes to another plugin's config table.
|
||
|
||
<small>`settings.go:31`</small>
|
||
|
||
### `ConfigDef`
|
||
|
||
```go
|
||
type ConfigDef struct { Key string `json:"key"` Default interface{} `json:"default,omitempty"` Type string `json:"type"` DisplayName string …
|
||
```
|
||
|
||
ConfigDef describes a configuration field for the WebUI.
|
||
|
||
<small>`settings.go:50`</small>
|
||
|
||
### `PluginSDK.Settings`
|
||
|
||
```go
|
||
func (s *PluginSDK) Settings() SettingsAPI
|
||
```
|
||
|
||
Settings returns the settings API for reading/writing plugin configuration.
|
||
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:67` | `s.Settings().RegisterDef(sdk.ConfigDef{` |
|
||
|
||
<small>`plugin.go:505`</small>
|
||
|