jianf/homeagent-sdk
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/homeagent-sdk.git synced 2026-10-01 14:53:12 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
bd73a9b2419fa04cf851166c10627bc415e04893
homeagent-sdk/docs/api/stages.md
JianFeeeee bd73a9b241 feat(sdk): 通用反代声明项（DeclareProxy）+ ToolDef.Serial 串行标记 + 场面策略文档 
本次一并提交工作区此前累积的改动（均已验证），并接入工具并发调度所需的
声明项。

把「谁来反代谁」从内核硬编码变成插件可声明。设备网关（remotedevice）
这类**编译进内核、没有独立插件目录与 plugin.json** 的服务，静态扫描扫不到，
此前只能靠约定。新增 DeclareProxy 让它们能自己声明反代路由。

ParallelSafe 的**反向**声明项。判据优先级：Serial 胜出，显式声明不允许被
ParallelSafe 或任何默认值覆盖。

为什么需要它：ParallelSafe 零值 false 已表达「安全/串行」，插件无法区分
「我没想过」和「我确认过必须串行」。没有这个区分，工具作者只能靠命名约定
传递意图，那不是契约。

ParallelSafe 本身也补齐了注释，明确其零值语义（默认串行、保守）与理由
（新语义下并发会改变工具的行为前提，让存量插件意外并发比慢一点危险得多）。

配套 ScenePolicy 声明项的使用说明。

remotedevice/ 整目录（C 实现的设备网关，已由 Go 侧 DeclareProxy 路径取代）。

- sdk/knowledge.go：随场面策略配套调整
- docs/api/*、docs/assets/api-index.json、docs/llms.txt、mkdocs.yml：
  由 tools/apidoc/build.sh 从源码重新生成（行号随 plugin.go 变动漂移）
2026-09-27 16:17:04 +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()
browser example/browser/plugin.go:427 p.mu.Lock()
calendar example/calendar/plugin.go:433 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()
browser example/browser/plugin.go:432 p.mu.Unlock()
calendar example/calendar/plugin.go:523 p.mu.Unlock()

plugin.go:212