jianf/homeagent-sdk
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/homeagent-sdk.git synced 2026-09-30 06:13:14 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
c7e5d2a446c97a6ecd2bd3825ec8dface551a66c
homeagent-sdk/docs/api/stages.md
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

4.4 KiB
Raw Blame History

阶段钩子（Stages）

在消息处理管道的固定点位插入自己的逻辑。阶段比工具更底层：工具是模型主动调用的，阶段是流程经过时必然触发的。

StageContext.IsResponded

func (c *StageContext) IsResponded() bool

plugin.go:213

StageContext.Lock

func (c *StageContext) Lock()

示例插件里的真实用法

插件 位置 代码
a2a example/a2a/plugin.go:158 p.sessMu.Lock()
acp example/acp/plugin.go:128 p.srvMu.Lock()
bili example/bili/plugin.go:37 p.runMu.Lock()
browser example/browser/plugin.go:427 p.mu.Lock()

plugin.go:211

StageContext.RLock

func (c *StageContext) RLock()

示例插件里的真实用法

插件 位置 代码
acp example/acp/plugin.go:267 p.mu.RLock()
calendar example/calendar/plugin.go:649 p.mu.RLock()
memo example/memo/plugin.go:224 p.mu.RLock()
qq example/qq/plugin.go:1152 ctx.RLock()

plugin.go:209

StageContext.RUnlock

func (c *StageContext) RUnlock()

示例插件里的真实用法

插件 位置 代码
acp example/acp/plugin.go:273 p.mu.RUnlock()
calendar example/calendar/plugin.go:650 defer p.mu.RUnlock()
memo example/memo/plugin.go:229 p.mu.RUnlock()
qq example/qq/plugin.go:1155 ctx.RUnlock()

plugin.go:210

PluginSDK.RegisterStage

func (s *PluginSDK) RegisterStage(stage Stage, handler StageHandler, scope ...StageScope)

RegisterStage registers a handler for a pipeline stage.

scope: StageScopeGlobal (default) — receives all stage events.
       StageScopeOwnTools — only before_toolcall/after_toolcall for this plugin's tools.

示例插件里的真实用法

插件 位置 代码
memo example/memo/plugin.go:152 s.RegisterStage(sdk.StagePreAction, p.stagePreAction)
qq example/qq/plugin.go:719 s.RegisterStage(sdk.StageOnInput, p.onInputAuthContext, sdk.StageScopeGlobal)
sanitizer example/sanitizer/plugin.go:52 s.RegisterStage(sdk.StageOnInput, func(ctx *sdk.StageContext) error {
weather example/weather/plugin.go:94 s.RegisterStage(sdk.StageAfterToolcall, func(ctx *sdk.StageContext) error {

plugin.go:571

Stage

type Stage string

Stage represents a point in the message processing pipeline.

plugin.go:26

StageContext

type StageContext struct { mu sync.RWMutex RawMessage string UserID string GroupID string ContextMsgs []map[string]interface{} L …

StageContext provides context for stage handlers.

plugin.go:189

StageHandler

type StageHandler func(ctx *StageContext) error

StageHandler is a function that handles a pipeline stage event.

plugin.go:23

StageRegistrar

type StageRegistrar func(stage Stage, handler StageHandler)

StageRegistrar registers a stage handler.

plugin.go:407

StageScope

type StageScope int

StageScope controls which events a stage handler receives.

plugin.go:393

StageContext.Unlock

func (c *StageContext) Unlock()

示例插件里的真实用法

插件 位置 代码
a2a example/a2a/plugin.go:164 p.sessMu.Unlock()
acp example/acp/plugin.go:129 defer p.srvMu.Unlock()
bili example/bili/plugin.go:40 p.runMu.Unlock()
browser example/browser/plugin.go:432 p.mu.Unlock()

plugin.go:212