homeagent-sdk/docs/api/misc.md

其他类型

剩余的类型与方法：PluginSDK 本体的访问器、StageContext 的并发控制，以及多模态辅助类型。没有归入上面任何一个主题，但可能仍会用到。

DocMemoryAPI

DocMemoryAPI provides access to the document vector store.

方法	说明
Insert
InsertWithMedia	InsertWithMedia 写入文档并关联媒体。attachments 里带 Data 的会落进
Query
Remove
Stats

DocMemoryAPI.Insert

Insert(doc *Doc) error

memory.go:76

DocMemoryAPI.InsertWithMedia

InsertWithMedia(doc *Doc, attachments []MediaAttachment) error

InsertWithMedia 写入文档并关联媒体。attachments 里带 Data 的会落进 内容寻址存储（相同字节只存一份），只带 Digest 的直接引用已有内容。 媒体成为文档直接持有的一等记忆块：文档向量会融合它们的原生向量， 因此图片按自己的向量被召回，不依赖任何生成的描述文本。

memory.go:81

DocMemoryAPI.Query

Query(text string, topK int) []*Doc

memory.go:75

DocMemoryAPI.Remove

Remove(id string)

memory.go:82

DocMemoryAPI.Stats

Stats() map[string]interface{}

memory.go:83

EventSubscriber

EventSubscriber allows plugins to subscribe to kernel events. This is a restricted interface: plugins can subscribe but the kernel controls which events are delivered.

方法	说明
Subscribe

EventSubscriber.Subscribe

!!! warning "仅内核内置插件可用"

Subscribe(eventType EventType, handler EventHandler) func()

plugin.go:279

IOInjector

IOInjector provides methods for injecting input and interrupts into the agent pipeline. All methods accept (source, channel) where channel is the target output channel for routing the agent's response.

方法	说明
InjectInputMedia
InjectInputMediaOpts
InjectInputMediaSync
InjectInputMediaSyncOpts
InjectInputSync	InjectInputSync 注入输入事件并同步等待 agent 回复，返回回复文本（无回复时返回空串）。
InjectInputSyncOpts
InjectInterruptMedia
InjectInterruptMediaOpts
InjectInterruptText
InjectInterruptTextOpts
InjectText
InjectTextNoMemory
InjectTextOpts	以下 Opts 变体让调用点在这一次注入上声明记忆与裁剪行为。
SetToolBlocks	SetToolBlocks 插件工具注入多模态内容块（image_url/audio_url），内核在下一条

IOInjector.InjectInputMedia

InjectInputMedia(source, channel, text string, blocks []ContentBlock)

plugin.go:230

IOInjector.InjectInputMediaOpts

InjectInputMediaOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions)

plugin.go:241

IOInjector.InjectInputMediaSync

InjectInputMediaSync(source, channel, text string, blocks []ContentBlock) string

plugin.go:231

IOInjector.InjectInputMediaSyncOpts

InjectInputMediaSyncOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions) string

plugin.go:242

IOInjector.InjectInputSync

InjectInputSync(source, channel, text string) string

InjectInputSync 注入输入事件并同步等待 agent 回复，返回回复文本（无回复时返回空串）。 用于通道消息的完整闭环：收到入站 → agent 处理 → 回复取回 → 送回通道。

示例插件里的真实用法

插件	位置	代码
a2a	example/a2a/plugin.go:345	reply := p.sdk.InjectInputSync(p.name, p.name,
acp	example/acp/plugin.go:237	reply = p.sdk.InjectInputSync(p.name, p.name,

plugin.go:226

IOInjector.InjectInputSyncOpts

InjectInputSyncOpts(source, channel, text string, opts InjectOptions) string

plugin.go:240

IOInjector.InjectInterruptMedia

InjectInterruptMedia(source, channel, text string, blocks []ContentBlock)

plugin.go:232

IOInjector.InjectInterruptMediaOpts

InjectInterruptMediaOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions)

plugin.go:243

IOInjector.InjectInterruptText

InjectInterruptText(source, channel, text string)

plugin.go:221

IOInjector.InjectInterruptTextOpts

InjectInterruptTextOpts(source, channel, text string, opts InjectOptions)

示例插件里的真实用法

插件	位置	代码
browser	example/browser/plugin.go:1319	p.sdk.InjectInterruptTextOpts(p.name, p.name,
calendar	example/calendar/plugin.go:527	p.sdk.InjectInterruptTextOpts("calendar", "calendar", msg, sdk.InjectOptions{NoMemory: true})
memo	example/memo/plugin.go:299	p.sdk.InjectInterruptTextOpts(p.name, p.name,
qq	example/qq/plugin.go:1493	p.sdk.InjectInterruptTextOpts(p.name, p.name, text, sdk.InjectOptions{

plugin.go:239

IOInjector.InjectText

InjectText(source, channel, text string)

plugin.go:222

IOInjector.InjectTextNoMemory

InjectTextNoMemory(source, channel, text string)

示例插件里的真实用法

插件	位置	代码
browser	example/browser/plugin.go:1114	p.sdk.InjectTextNoMemory(p.name, p.name, fmt.Sprintf("[浏览器 %s 已导航到 %s]", id, rawURL))

plugin.go:223

IOInjector.InjectTextOpts

InjectTextOpts(source, channel, text string, opts InjectOptions)

以下 Opts 变体让调用点在这一次注入上声明记忆与裁剪行为。

上面那些不带 opts 的方法等价于传零值 InjectOptions（记入记忆 + 不裁剪）， 保留它们是为了不破坏已有插件；新代码应当用 Opts 变体把意图写清楚。

plugin.go:238

IOInjector.SetToolBlocks

SetToolBlocks(blocks []ContentBlock)

SetToolBlocks 插件工具注入多模态内容块（image_url/audio_url），内核在下一条 tool message 的 content 数组里带上这些块，让模型在后续轮次看到图/听到音频。

plugin.go:229

KnowledgeAPI

KnowledgeAPI provides access to the knowledge store.

方法	说明
Add
List
Search

KnowledgeAPI.Add

Add(name, content string) error

knowledge.go:6

KnowledgeAPI.List

List() ([]string, error)

knowledge.go:7

KnowledgeAPI.Search

Search(query string, topK int) ([]*Knowledge, error)

knowledge.go:5

LLMAPI

LLMAPI provides access to the LLM provider manager.

方法	说明
CurrentSource
ListSources
SetSource

LLMAPI.CurrentSource

CurrentSource() string

llm.go:7

LLMAPI.ListSources

ListSources() []string

llm.go:5

LLMAPI.SetSource

SetSource(name string) error

llm.go:6

MemoryAPI

MemoryAPI provides access to the graph memory (entity-relation store).

方法	说明
Commit
Introspect
MergeEntities
Purge
Recall

MemoryAPI.Commit

Commit(triples []Triple) error

memory.go:6

MemoryAPI.Introspect

Introspect() (map[string]interface{}, error)

memory.go:7

MemoryAPI.MergeEntities

MergeEntities(source, target string) (int, error)

memory.go:8

MemoryAPI.Purge

Purge(criteria map[string]string, mode string) (int, error)

memory.go:9

MemoryAPI.Recall

Recall(query []string, depth int) ([]Entity, []Relation, error)

memory.go:5

Plugin

Plugin is the interface every plugin must implement.

方法	说明
Name
Start
Stop

Plugin.Name

Name() string

plugin.go:14

Plugin.Start

Start(sdk *PluginSDK) error

plugin.go:15

Plugin.Stop

Stop() error

plugin.go:16

PluginMgrAPI

PluginMgrAPI 提供插件管理能力（外部插件可调用）。 由 bridge 注入 dispatch 实现，走 C ABI CORE_PLUGIN_RELOAD_ONE 等。

方法	说明
IsPluginDisabled	IsPluginDisabled 查询插件是否被禁用。
ListLoadedPlugins	ListLoadedPlugins 列出已加载插件。
ReloadOne	ReloadOne 重载单个插件（停止后重新加载）。

PluginMgrAPI.IsPluginDisabled

IsPluginDisabled(name string) bool

IsPluginDisabled 查询插件是否被禁用。

plugin.go:290

PluginMgrAPI.ListLoadedPlugins

ListLoadedPlugins() []string

ListLoadedPlugins 列出已加载插件。

plugin.go:288

PluginMgrAPI.ReloadOne

ReloadOne(name string) error

ReloadOne 重载单个插件（停止后重新加载）。

plugin.go:286

SettingsAPI

方法	说明
DataDir	DataDir returns the plugin-specific data directory (guaranteed to exist):
Defs	Defs returns config definitions matching the prefix.
Dump	Dump returns all config values.
Get	Get reads the plugin's own config value (config_ table).
GetCore	GetCore reads the core config table.
GetPlugin	GetPlugin reads another plugin's config table.
List	List returns all keys matching the given prefix.
ListCore	ListCore lists core config keys matching the prefix.
ListPlugin	ListPlugin lists another plugin's config keys matching the prefix.
Plugins	Plugins returns a list of all plugin config namespaces.
RegisterDef	RegisterDef registers a config definition for UI display.
Set	Set writes a config value to the plugin's own config table.
SetCore	SetCore writes to the core config table.
SetPlugin	SetPlugin writes to another plugin's config table.

SettingsAPI.DataDir

DataDir() string

DataDir returns the plugin-specific data directory (guaranteed to exist): /plugin_data/<plugin_name>. Plugins should persist any runtime files (generated images, caches, downloads) here.

settings.go:25

SettingsAPI.Defs

Defs(prefix string) []*ConfigDef

Defs returns config definitions matching the prefix.

settings.go:40

SettingsAPI.Dump

Dump() map[string]interface{}

Dump returns all config values.

settings.go:43

SettingsAPI.Get

Get(key string) (interface{}, error)

Get reads the plugin's own config value (config_ table).

settings.go:5

SettingsAPI.GetCore

GetCore(key string) (interface{}, error)

GetCore reads the core config table.

settings.go:14

SettingsAPI.GetPlugin

GetPlugin(plugin, key string) (interface{}, error)

GetPlugin reads another plugin's config table.

settings.go:28

SettingsAPI.List

List(prefix string) ([]string, error)

List returns all keys matching the given prefix.

settings.go:11

SettingsAPI.ListCore

ListCore(prefix string) ([]string, error)

ListCore lists core config keys matching the prefix.

settings.go:20

SettingsAPI.ListPlugin

ListPlugin(plugin, prefix string) ([]string, error)

ListPlugin lists another plugin's config keys matching the prefix.

settings.go:34

SettingsAPI.Plugins

Plugins() []string

Plugins returns a list of all plugin config namespaces.

settings.go:46

SettingsAPI.RegisterDef

RegisterDef(def ConfigDef)

RegisterDef registers a config definition for UI display.

settings.go:37

SettingsAPI.Set

Set(key string, value interface{}) error

Set writes a config value to the plugin's own config table.

settings.go:8

SettingsAPI.SetCore

SetCore(key string, value interface{}) error

SetCore writes to the core config table.

settings.go:17

SettingsAPI.SetPlugin

SetPlugin(plugin, key string, value interface{}) error

SetPlugin writes to another plugin's config table.

settings.go:31

SocialAPI

SocialAPI provides read-only access to the social graph (person profiles and relationships). External plugins can query person traits and social networks but cannot modify them.

方法	说明
GetNetwork
GetPerson
GetRelations
GetTrait
ListPersons

SocialAPI.GetNetwork

GetNetwork(name string, depth int) ([]*PersonProfile, error)

memory.go:104

SocialAPI.GetPerson

GetPerson(name string) (*PersonProfile, error)

memory.go:101

SocialAPI.GetRelations

GetRelations(name string) ([]SocialRelation, error)

memory.go:103

SocialAPI.GetTrait

GetTrait(name, trait string) (string, bool)

memory.go:102

SocialAPI.ListPersons

ListPersons() ([]string, error)

memory.go:105

TextMemoryAPI

TextMemoryAPI provides access to chronological text event storage.

方法	说明
Append

TextMemoryAPI.Append

Append(evt TextEvent) error

memory.go:44

AudioURL

type AudioURL struct { URL string `json:"url"` }

plugin.go:867

EffectiveProxyAuth

func EffectiveProxyAuth(auth string) string

EffectiveProxyAuth 返回生效的鉴权模式（空串归一化为 ProxyAuthHomeAgent）。

proxy.go:169

ImageURL

type ImageURL struct { URL string `json:"url"` Detail string `json:"detail,omitempty"` }

plugin.go:862

MemItem

type MemItem struct { Role string `json:"role"` Content string `json:"content"` Score float64 `json:"score"` }

MemItem represents a memory item in stage context.

plugin.go:179

NormalizeProxyHost

func NormalizeProxyHost(pluginName string) string

NormalizeProxyHost 由插件名派生默认 Host 标签。

下划线转连字符：插件名允许下划线（huawei_smarthome），但 DNS label 不允许， 直接用会导致该子域名无法解析——这里统一转换，避免每个插件各自碰运气。

proxy.go:202

PluginSDK

type PluginSDK struct { name string regTool ToolRegistrar regStage StageRegistrar regAPI APIRegistrar regOutput OutputChannelRegistrar …

PluginSDK is the main API surface provided to plugins at runtime. It wraps tool registration, settings, memory, knowledge, LLM, and IO injection.

plugin.go:337

ProxyAuthHomeAgent

const ProxyAuthHomeAgent

ProxyAuthHomeAgent 表示由 HomeAgent 统一保护：浏览器走门户会话 （homeagent_session cookie），非浏览器客户端走 X-API-Key。 两者都没有时返回 401，而不是把请求透传给上游。

proxy.go:149

ProxyAuthNone

const ProxyAuthNone

ProxyAuthNone 表示不经 HomeAgent 鉴权，直接把请求转发给上游。

适用场景：上游自己有鉴权且调用方不是浏览器（设备/嵌入式客户端）， 或上游是刻意公开的服务。选用它意味着信任上游自身的鉴权， 且该服务在网络层可达范围内对所有人开放。

proxy.go:156

ProxyDef

type ProxyDef struct { // Name 是同一插件内多条声明的唯一标识（如 "ui"、"api"）。 // 运行期由 RegisterProxy 的第一个参数填入；声明式由 …

反向代理声明：插件告诉 HomeAgent「我起了个 HTTP 服务，请把它反代出去」。

为什么需要：插件自带 Web UI / HTTP API 时，监听地址在插件自己的配置里 （如 127.0.0.1:12100），外部无从得知；而 webui 的对外端口通常只有一个 （默认 :8080，且常经 frp 单端口隧道穿透）。没有声明机制时，用户只能 「知道端口 + 自己配转发」，插件换端口就失效。

设计取舍——声明式而非注册式：声明写在 plugin.json 里，由 HomeAgent 在加载插件时读取聚合，而不是让插件在运行期调 API 注册。理由：

1. 静态可发现：未启动/已崩溃的插件，其服务声明依然可见（可给出准确报错 「插件 X 声明了 ui 但目标 127.0.0.1:12100 不可达」，而不是静默 404）；
2. 可版本化：声明随插件包一起分发、可 diff、可审计；
3. 旧内核无害：manifest 解析忽略未知字段，未支持该能力的 HomeAgent 读旧 插件、或旧 HomeAgent 读新插件都不会报错。

与 ToolDef / ChannelDef / ConfigDef 同族：SDK 定义声明契约，内核实现行为。 声明方式与其它能力一致 —— 在 Start() 里调 RegisterProxy(name, def)， 或写进 plugin.json 的 proxies 字段（外部插件两种都支持）。

安全性：不声明 = 不被反代。声明本身就是能力声明，因此不需要在 capabilities 里另外开一个开关——最小权限默认生效。

单一入口原则（强制要求）

一个声明 = 一个入口。被反代的插件必须让它的全部资源与接口都能从 该入口的一个基准路径出发访问到，不得依赖「入口之外的根路径」。

为什么强制：反代有两种挂载形态，而它们对「根路径」的处理截然不同——

Host 形态（host）：插件独占 <标签>.<基域名>，根路径就是插件的根。
                  根绝对路径（fetch('/api/x')）**天然正确**。
Path 形态（path）：插件挂在门户自身 host 的某个前缀下，根路径属于**门户**。
                  此时插件里的 fetch('/api/x') 会打到门户自己的 /api/x
                  —— 静默错路由，页面能开但功能全坏。

于是「同一个插件必须同时支持两种形态」这条要求，等价于：

**插件内部一律使用相对路径**（或基于 <base>/location 推导的路径），
绝不硬编码以 / 开头的绝对路径。

这样同一份前端在两种形态下都正确，插件作者也不必知道自己被挂在哪。 反代层据此可以：外部子域可用时给 Host 形态，子域不可用（证书/放行限制） 时给 Path 形态，无需插件配合改动。

自检（插件作者在本地就该做）：把页面挂到 <门户>/<任意前缀>/ 下访问， 所有请求都必须仍然打到插件自己。

本项目实测案例：某插件前端写死 fetch('/api/status')，配在 /p/huawei/ 下会打到门户的 /api/status（404 或返回门户数据）； 改成相对路径后两种形态同时可用。 ProxyDef 是一个服务的反代声明体。

与 ToolDef 同构：Name 同时出现在字段与 RegisterProxy 的第一个参数里 （ToolDef 也是这么做的 —— 字段供 plugin.json 序列化，参数供运行期调用）。 Name 只用于展示、日志与冲突提示，不参与路由（路由键是 Host 与 Path）。

proxy.go:64

ProxyRegistrar

type ProxyRegistrar func(name string, def ProxyDef)

ProxyRegistrar 由内核注入（与 ToolRegistrar / InputChannelRegistrar 同族）。 插件不直接调它，用 RegisterProxy。

为什么需要运行期注册（明明有 plugin.json 自动发现）：内置插件 （编译进内核、没有独立插件目录与 plugin.json，如 remotedevice）扫不到； 而它们恰恰最需要被反代出去（设备网关就是内置的）。两种来源互补：

• 外部插件 → plugin.json 的 proxies（静态，未启动也可见）
• 内置插件 → RegisterProxy（运行期，随 Start 注册）

proxy.go:306

PluginSDK.RegisterProxy

func (s *PluginSDK) RegisterProxy(name string, def ProxyDef)

RegisterProxy 声明一个需要 HomeAgent 反代出去的服务。

与 RegisterTool / RegisterInputChannel / RegisterOutputChannel 同一风格： 显式给名字 + 声明体。名字用于展示、日志与冲突提示（不参与路由 —— 路由键是 def.Host / def.Path）。

用法（通常在 Start 里调用）：

s.RegisterProxy("ui", sdk.ProxyDef{
    Host: "myapp", Target: "127.0.0.1:12100",
})

声明立即生效（反代表在下一次请求时重建）。不做去重：同一 Host/Path 被两条声明占用时由反代层判定冲突并明确报错，而不是在这里静默吞掉 —— 插件作者需要看见冲突。

与 plugin.json 的 proxies 字段等价：写哪个都行，两者会合并（同名以本调用为准）。

proxy.go:335

SDKVersion

var SDKVersion

SDKVersion 是对外暴露的 SDK 版本号。

plugin.go:10

PluginSDK.SetProxyRegistrar

func (s *PluginSDK) SetProxyRegistrar(r ProxyRegistrar)

SetProxyRegistrar 由内核注入。插件不直接调它（与 SetInputChannelRegistrar 同族）。

proxy.go:309

PluginSDK.UnregisterOutputChannel

!!! warning "仅内核内置插件可用" 外部插件的桥接模板只注入 SetOutputChannelRegistrar（proc_main.go.tmpl:693-705），未注入 SetOutputChannelUnregistrar（grep Unregistrar 在 templates/ 下无命中）。因此外部插件的 regOutputUnreg 为 nil，UnregisterOutputChannel 会命中 if reg != nil 的 else 分支直接返回 nil（sdk/plugin.go:539-549）——即静默无效：不报错、通道也没注销。内置插件由 internal/sdk/plugin.go:330 注入 cfg.RegOutputUnreg，真正生效。外部插件要让通道下线，只能重载插件。

func (s *PluginSDK) UnregisterOutputChannel(name string) error

UnregisterOutputChannel 注销一个输出通道（动态通道随资源生灭时必须调用）。

plugin.go:544

ValidProxyAuth

func ValidProxyAuth(auth string) bool

ValidProxyAuth 校验 Auth 取值；空串合法（等价 ProxyAuthHomeAgent）。

proxy.go:160

ValidProxyHostLabel

func ValidProxyHostLabel(label string) bool

ValidProxyHostLabel 校验子域名标签是否合法（DNS label 规则）。

独立成导出函数：插件作者在写声明时、HomeAgent 在加载时、工具链在打包时 都要用同一套规则判定，避免三处各写一份而互相不一致。

proxy.go:180

ValidateProxyDef

func ValidateProxyDef(d ProxyDef) string

ValidateProxyDef 校验一条反代声明，返回人类可读的错误说明（合法时为空）。

为什么要在 SDK 里做校验：HomeAgent 加载插件时必须能明确拒绝坏声明并说明 原因（而不是静默忽略导致用户以为配好了）；插件作者也需要在本地就能查出 拼错的 Target/Host。同一套规则两端共用。

proxy.go:229