mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-10-03 15:53:56 +00:00
refactor: pluginize text cleaning and tool NoMemory control
- SDK: ToolDef.NoMemory field, PluginSDK.RegisterTextCleaner/TextCleaners - Registry: aggregate text cleaners from plugins, expose CleanText() - Memory: replace hardcoded QQ regex CleanTemplateText with dynamic CleanText/SetTextCleaner - StageHost: add ToolDef(name) lookup - eventloop: check ToolDef.NoMemory before emitMemoryCandidate - context/Prune: replace hardcoded agentcli/terminal source filter with ToolsUsed NoMemory check - agentcli/cmd: mark tools with NoMemory: true - main.go: wire memory.SetTextCleaner(pluginReg.CleanText)
This commit is contained in:
root
205
_sdk_local/README.md
Normal file
205
_sdk_local/README.md
Normal file
@ -0,0 +1,205 @@
|
||||
# HomeAgent SDK
|
||||
|
||||
HomeAgent 插件开发 SDK，用于构建与 HomeAgent 平台交互的智能插件。
|
||||
|
||||
## SDK API 接口
|
||||
|
||||
### Plugin 接口
|
||||
|
||||
插件需实现 `Plugin` 接口：
|
||||
|
||||
```go
|
||||
type Plugin interface {
|
||||
Name() string
|
||||
Start(sdk *PluginSDK) error
|
||||
Stop() error
|
||||
}
|
||||
```
|
||||
|
||||
### PluginSDK 方法
|
||||
|
||||
通过 `Start(sdk *PluginSDK)` 注入的 SDK 实例提供以下方法：
|
||||
|
||||
| 分类 | 方法 | 说明 |
|
||||
|------|------|------|
|
||||
| 阶段钩子 | `RegisterStage(stage, handler, scope...)` | 注册阶段回调，scope 可选：`StageScopeGlobal`（全局，默认）或 `StageScopeOwnTools`（仅自己工具） |
|
||||
| 输出通道 | `RegisterOutputChannel(name, caps, desc, handler)` | 注册输出通道，caps 为能力位掩码 |
|
||||
| 工具注册 | `RegisterTool(name, def, handler)` | 注册工具供 LLM 调用 |
|
||||
| 插件 API | `RegisterPluginAPI(name)` | 注册插件 API 供其他插件访问 |
|
||||
| 图记忆 | `Memory()` | 访问图记忆 API（实体-关系存储） |
|
||||
| 文本记忆 | `TextMemory()` | 访问文本记忆 API（时序事件） |
|
||||
| 文档记忆 | `DocMemory()` | 访问文档记忆 API（向量存储） |
|
||||
| 社交图谱 | `Social()` | 访问社交图谱 API（外部插件只读） |
|
||||
| 知识库 | `Knowledge()` | 访问知识库 API |
|
||||
| LLM | `LLM()` | 访问 LLM 提供商管理 API |
|
||||
| 设置 | `Settings()` | 访问设置 API |
|
||||
| 事件 | `Events()` | 访问事件订阅器（外部插件仅订阅） |
|
||||
| 注入 | `InjectText(source, channel, text)` / `InjectInterruptText(source, channel, text)` / `InjectTextNoMemory(source, channel, text)` | 向管道注入文本 |
|
||||
| 自动重启 | `SetAutoRestart(enabled)` / `AutoRestart()` | 控制崩溃自动重启 |
|
||||
|
||||
### 阶段钩子
|
||||
|
||||
```go
|
||||
// 全局监听所有插件的阶段事件
|
||||
sdk.RegisterStage(StagePreAction, func(ctx *StageContext) error { return nil })
|
||||
|
||||
// 仅监听自己注册的工具的 before_toolcall / after_toolcall
|
||||
sdk.RegisterStage(StageBeforeToolcall, myHandler, StageScopeOwnTools)
|
||||
```
|
||||
|
||||
### 输出通道
|
||||
|
||||
```go
|
||||
sdk.RegisterOutputChannel("my-channel", CapText|CapFile, "通道描述", handler)
|
||||
```
|
||||
|
||||
handler 接收三个参数：
|
||||
- `payload` (string) — 消息载荷。`type=text` 时直接填文字，`type=file/image` 时填 URL
|
||||
- `meta` (string) — 可选的 JSON 路由元数据（如 `{"group_id":123,"user_id":456}`）
|
||||
- `type` (string) — 载荷类型，枚举值见下
|
||||
|
||||
能力标志位：
|
||||
|
||||
| 标志 | 值 | 说明 |
|
||||
|------|----|------|
|
||||
| `CapText` | 1 | 纯文本输出 |
|
||||
| `CapFile` | 2 | 文件输出 |
|
||||
| `CapImage` | 4 | 图片输出 |
|
||||
| `CapAudio` | 8 | 音频输出 |
|
||||
| `CapStructured` | 16 | 结构化数据输出 |
|
||||
|
||||
type 枚举值：
|
||||
|
||||
| 值 | 说明 |
|
||||
|----|------|
|
||||
| `text` | 纯文本 |
|
||||
| `voice` / `audio` | 语音 |
|
||||
| `image` | 图片 |
|
||||
| `file` | 文件 |
|
||||
|
||||
### IOInjector 通道路由
|
||||
|
||||
| 方法 | 说明 |
|
||||
|------|------|
|
||||
| `InjectText(source, channel, text)` | 注入文本，记入内存，路由到指定通道 |
|
||||
| `InjectInterruptText(source, channel, text)` | 注入中断文本，打断当前处理，路由到指定通道 |
|
||||
| `InjectTextNoMemory(source, channel, text)` | 注入文本，不记入内存，路由到指定通道 |
|
||||
|
||||
`source` 标识来源，`channel` 指定目标输出通道。
|
||||
|
||||
### Triple 扩展字段
|
||||
|
||||
Triple 数据结构新增字段：
|
||||
|
||||
- `Confidence` — 置信度（0.0~1.0）
|
||||
- `SubjectType` — 主体类型
|
||||
- `ObjectType` — 客体类型
|
||||
|
||||
### New 构造函数
|
||||
|
||||
`New()` 由内核在加载插件时调用，插件开发者无需手动构造 PluginSDK：
|
||||
|
||||
```go
|
||||
func New(name string, sett SettingsAPI, regTool ToolRegistrar, regStage StageRegistrar, regAPI APIRegistrar, regOutput OutputChannelRegistrar) *PluginSDK
|
||||
```
|
||||
|
||||
插件开发者只需实现 `Plugin` 接口并导出 `NewPlugin()` 入口函数。
|
||||
|
||||
## plugindev 工具链
|
||||
|
||||
`plugindev` 提供插件开发全流程支持：
|
||||
|
||||
| 命令 | 说明 |
|
||||
|------|------|
|
||||
| `plugindev init` | 初始化插件项目（生成 plg.json、入口模板） |
|
||||
| `plugindev build` | 构建插件，输出 .hmap 包 |
|
||||
| `plugindev clean` | 清理构建产物 |
|
||||
| `plugindev debug` | 本地调试模式运行插件 |
|
||||
|
||||
支持 **Go** 和 **Lua** 两种插件语言。
|
||||
|
||||
### plg.json 清单格式
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"version": "1.0.0",
|
||||
"lang": "go",
|
||||
"entry": "main.go",
|
||||
"description": "插件描述",
|
||||
"channels": ["my-channel"],
|
||||
"dependencies": {}
|
||||
}
|
||||
```
|
||||
|
||||
### .hmap 包格式
|
||||
|
||||
`.hmap` 为 ZIP 归档，包含：
|
||||
|
||||
- `plugin.json` — 插件元数据
|
||||
- `plugin.so` — Go 编译产物（Linux）
|
||||
- `plugin.dll` — Go 编译产物（Windows）
|
||||
- `main.lua` — Lua 插件入口（Lua 插件时）
|
||||
|
||||
## 插件生命周期
|
||||
|
||||
### 启动与停止
|
||||
|
||||
- `Start(sdk *PluginSDK) error` — 插件启动，接收 SDK 实例
|
||||
- `Stop() error` — 插件停止，释放资源
|
||||
|
||||
### 自动重启
|
||||
|
||||
```go
|
||||
sdk.SetAutoRestart(true)
|
||||
// 查询状态
|
||||
enabled := sdk.AutoRestart()
|
||||
```
|
||||
|
||||
插件崩溃时平台自动拉起，保障服务可用性。
|
||||
|
||||
## 受限 SDK vs 完整 SDK
|
||||
|
||||
外部插件（第三方分发）使用**受限 SDK**，仅暴露安全子集：
|
||||
|
||||
| 受限 API | 允许操作 |
|
||||
|----------|----------|
|
||||
| `SocialAPI` | 只读：`GetPerson`、`GetTrait`、`GetRelations`、`GetNetwork`、`ListPersons` |
|
||||
| `EventSubscriber` | 仅订阅：`Subscribe`（无 `Publish`） |
|
||||
|
||||
内部插件（平台内置）拥有完整 SDK 访问权限，包括 SocialAPI 写操作和 EventPublisher。
|
||||
|
||||
## 示例插件
|
||||
|
||||
| 插件 | 说明 |
|
||||
|------|------|
|
||||
| a2a | Agent-to-Agent 协议通信 |
|
||||
| bili | Bilibili 视频下载 |
|
||||
| browser | 网络搜索、网页抓取、浏览器渲染（合并自 web/webfetch） |
|
||||
| editdoc | 文档编辑 |
|
||||
| files | 文件管理 |
|
||||
| memo | 备忘录/记忆 |
|
||||
| ocr | 光学字符识别 |
|
||||
| qq | QQ 消息集成 |
|
||||
| sanitizer | 内容清洗/安全过滤 |
|
||||
|
||||
## 构建与安装
|
||||
|
||||
### 构建
|
||||
|
||||
```bash
|
||||
plugindev build
|
||||
```
|
||||
|
||||
输出 `.hmap` 包到项目目录。
|
||||
|
||||
### 安装
|
||||
|
||||
通过 pluginmgr HTTP API 安装：
|
||||
|
||||
```bash
|
||||
curl -X POST http://<host>:<port>/api/plugins/install \
|
||||
-F "package=@my-plugin.hmap"
|
||||
```
|
||||
|
||||
或手动将 `.hmap` 放入插件目录后重启平台。
|
||||
206
_sdk_local/README_EN.md
Normal file
206
_sdk_local/README_EN.md
Normal file
@ -0,0 +1,206 @@
|
||||
# HomeAgent SDK
|
||||
|
||||
Plugin development SDK for building intelligent plugins that interact with the HomeAgent platform.
|
||||
|
||||
## SDK API Surface
|
||||
|
||||
### Plugin Interface
|
||||
|
||||
Plugins implement the `Plugin` interface:
|
||||
|
||||
```go
|
||||
type Plugin interface {
|
||||
Name() string
|
||||
Start(sdk *PluginSDK) error
|
||||
Stop() error
|
||||
}
|
||||
```
|
||||
|
||||
### PluginSDK Methods
|
||||
|
||||
The SDK instance injected via `Start(sdk *PluginSDK)` provides:
|
||||
|
||||
| Category | Method | Description |
|
||||
|----------|--------|-------------|
|
||||
| Stage Hooks | `RegisterStage(stage, handler, scope...)` | Register stage callback; scope: `StageScopeGlobal` (all, default) or `StageScopeOwnTools` (own tools only) |
|
||||
| Output Channel | `RegisterOutputChannel(name, caps, desc, handler)` | Register output channel with capability bitmask |
|
||||
| Tool Registration | `RegisterTool(name, def, handler)` | Register a tool for LLM invocation |
|
||||
| Plugin API | `RegisterPluginAPI(name)` | Register plugin API for inter-plugin access |
|
||||
| Graph Memory | `Memory()` | Access graph memory API (entity-relation store) |
|
||||
| Text Memory | `TextMemory()` | Access text memory API (chronological events) |
|
||||
| Doc Memory | `DocMemory()` | Access document memory API (vector store) |
|
||||
| Social Graph | `Social()` | Access social graph API (read-only for external plugins) |
|
||||
| Knowledge | `Knowledge()` | Access knowledge base API |
|
||||
| LLM | `LLM()` | Access LLM provider manager API |
|
||||
| Settings | `Settings()` | Access settings API |
|
||||
| Events | `Events()` | Access event subscriber (subscribe-only for external plugins) |
|
||||
| Inject | `InjectText(source, channel, text)` / `InjectInterruptText(source, channel, text)` / `InjectTextNoMemory(source, channel, text)` | Inject text into the agent pipeline |
|
||||
| Auto-Restart | `SetAutoRestart(enabled)` / `AutoRestart()` | Control automatic restart on crash |
|
||||
|
||||
### Stage Hooks
|
||||
|
||||
```go
|
||||
// Listen to all stage events globally
|
||||
sdk.RegisterStage(StagePreAction, func(ctx *StageContext) error { return nil })
|
||||
|
||||
// Listen only to this plugin's own tool calls (before_toolcall / after_toolcall only)
|
||||
sdk.RegisterStage(StageBeforeToolcall, myHandler, StageScopeOwnTools)
|
||||
```
|
||||
|
||||
### Output Channels
|
||||
|
||||
```go
|
||||
sdk.RegisterOutputChannel("my-channel", CapText|CapFile, "channel description", handler)
|
||||
```
|
||||
|
||||
The handler receives three arguments:
|
||||
- `payload` (string) — message content. For `type=text` it's plain text, for `type=file/image` it's a URL
|
||||
- `meta` (string) — optional JSON routing metadata (e.g. `{"group_id":123,"user_id":456}`)
|
||||
- `type` (string) — content type enum (see below)
|
||||
|
||||
Capability flags:
|
||||
|
||||
| Flag | Value | Description |
|
||||
|------|-------|-------------|
|
||||
| `CapText` | 1 | Plain text output |
|
||||
| `CapFile` | 2 | File output |
|
||||
| `CapImage` | 4 | Image output |
|
||||
| `CapAudio` | 8 | Audio output |
|
||||
| `CapStructured` | 16 | Structured data output |
|
||||
|
||||
Type enum values:
|
||||
|
||||
| Value | Description |
|
||||
|-------|-------------|
|
||||
| `text` | plain text |
|
||||
| `voice` / `audio` | audio/voice |
|
||||
| `image` | image |
|
||||
| `file` | file |
|
||||
|
||||
### IOInjector Channel Routing
|
||||
|
||||
| Method | Description |
|
||||
|--------|-------------|
|
||||
| `InjectText(source, channel, text)` | Inject text, record to memory, route to specified channel |
|
||||
| `InjectInterruptText(source, channel, text)` | Inject interrupt text, interrupt current processing, route to specified channel |
|
||||
| `InjectTextNoMemory(source, channel, text)` | Inject text without memory recording, route to specified channel |
|
||||
|
||||
`source` identifies the origin, `channel` specifies the target output channel.
|
||||
|
||||
### Triple Extended Fields
|
||||
|
||||
The Triple data structure includes additional fields:
|
||||
|
||||
- `Confidence` — confidence score (0.0–1.0)
|
||||
- `SubjectType` — subject type
|
||||
- `ObjectType` — object type
|
||||
|
||||
### New Constructor
|
||||
|
||||
`New()` is called by the kernel when loading a plugin. Plugin developers do not need to construct PluginSDK manually:
|
||||
|
||||
```go
|
||||
func New(name string, sett SettingsAPI, regTool ToolRegistrar, regStage StageRegistrar, regAPI APIRegistrar, regOutput OutputChannelRegistrar) *PluginSDK
|
||||
```
|
||||
|
||||
Plugin developers only need to implement the `Plugin` interface and export a `NewPlugin()` entry function.
|
||||
|
||||
## plugindev Toolchain
|
||||
|
||||
`plugindev` provides full development workflow support:
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `plugindev init` | Initialize plugin project (generates plg.json, entry template) |
|
||||
| `plugindev build` | Build plugin, output .hmap package |
|
||||
| `plugindev clean` | Clean build artifacts |
|
||||
| `plugindev debug` | Run plugin in local debug mode |
|
||||
|
||||
Supports both **Go** and **Lua** plugin languages.
|
||||
|
||||
### plg.json Manifest Format
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"version": "1.0.0",
|
||||
"lang": "go",
|
||||
"entry": "main.go",
|
||||
"description": "Plugin description",
|
||||
"channels": ["my-channel"],
|
||||
"dependencies": {}
|
||||
}
|
||||
```
|
||||
|
||||
### .hmap Package Format
|
||||
|
||||
`.hmap` is a ZIP archive containing:
|
||||
|
||||
- `plugin.json` — plugin metadata
|
||||
- `plugin.so` — Go compiled artifact (Linux)
|
||||
- `plugin.dll` — Go compiled artifact (Windows)
|
||||
- `main.lua` — Lua plugin entry (for Lua plugins)
|
||||
|
||||
## Plugin Lifecycle
|
||||
|
||||
### Start & Stop
|
||||
|
||||
- `Start(sdk *PluginSDK) error` — Plugin startup, receives SDK instance
|
||||
- `Stop() error` — Plugin shutdown, release resources
|
||||
|
||||
### Auto-Restart
|
||||
|
||||
```go
|
||||
sdk.SetAutoRestart(true)
|
||||
// Query state
|
||||
enabled := sdk.AutoRestart()
|
||||
```
|
||||
|
||||
The platform automatically restarts the plugin on crash, ensuring service availability.
|
||||
|
||||
## Restricted SDK vs Full SDK
|
||||
|
||||
External plugins (third-party distribution) use a **restricted SDK** that only exposes a safe subset:
|
||||
|
||||
| Restricted API | Allowed Operations |
|
||||
|----------------|-------------------|
|
||||
| `SocialAPI` | Read-only: `GetPerson`, `GetTrait`, `GetRelations`, `GetNetwork`, `ListPersons` |
|
||||
| `EventSubscriber` | Subscribe-only: `Subscribe` (no `Publish`) |
|
||||
|
||||
Internal plugins (platform built-in) have full SDK access including SocialAPI write operations and EventPublisher.
|
||||
|
||||
## Example Plugins
|
||||
|
||||
| Plugin | Description |
|
||||
|--------|-------------|
|
||||
| a2a | Agent-to-Agent protocol communication |
|
||||
| bili | Bilibili data fetching |
|
||||
| editdoc | Document editing |
|
||||
| files | File management |
|
||||
| memo | Memo/notes |
|
||||
| ocr | Optical character recognition |
|
||||
| qq | QQ messaging integration |
|
||||
| sanitizer | Content sanitization/safety filtering |
|
||||
| web | Web browsing and interaction |
|
||||
| webfetch | Web content fetching |
|
||||
|
||||
## Building & Installing
|
||||
|
||||
### Build
|
||||
|
||||
```bash
|
||||
plugindev build
|
||||
```
|
||||
|
||||
Outputs a `.hmap` package to the project directory.
|
||||
|
||||
### Install
|
||||
|
||||
Via pluginmgr HTTP API:
|
||||
|
||||
```bash
|
||||
curl -X POST http://<host>:<port>/api/plugins/install \
|
||||
-F "package=@my-plugin.hmap"
|
||||
```
|
||||
|
||||
Or manually place the `.hmap` in the plugin directory and restart the platform.
|
||||
11
_sdk_local/example/files/plg.json
Normal file
11
_sdk_local/example/files/plg.json
Normal file
@ -0,0 +1,11 @@
|
||||
{
|
||||
"name": "files",
|
||||
"name_zh": "文件系统",
|
||||
"name_en": "File System",
|
||||
"version": "1.0.0",
|
||||
"description": "文件系统操作工具集（读取/写入/编辑/列表），提供沙箱化文件访问，支持配置工作目录。",
|
||||
"author": "HomeAgent",
|
||||
"entry": "plugin.so",
|
||||
"tags": ["files", "filesystem"],
|
||||
"targets": "linux/amd64"
|
||||
}
|
||||
483
_sdk_local/example/files/plugin.go
Normal file
483
_sdk_local/example/files/plugin.go
Normal file
@ -0,0 +1,483 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"log"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"sort"
|
||||
"strings"
|
||||
"sync"
|
||||
|
||||
"gitcode.com/JianFeeeee/homeagent-sdk/sdk"
|
||||
)
|
||||
|
||||
type Plugin struct {
|
||||
name string
|
||||
sdk *sdk.PluginSDK
|
||||
mu sync.RWMutex
|
||||
filesDir string
|
||||
}
|
||||
|
||||
func (p *Plugin) Name() string { return p.name }
|
||||
|
||||
func (p *Plugin) Start(s *sdk.PluginSDK) error {
|
||||
s.SetAutoRestart(true)
|
||||
p.sdk = s
|
||||
s.Settings().RegisterDef(sdk.ConfigDef{
|
||||
Key: "plugin.files.dir",
|
||||
Default: "/",
|
||||
Type: "string",
|
||||
DisplayName: "文件系统根目录",
|
||||
Description: "文件操作允许访问的根目录（设为 / 表示完整主机文件系统）",
|
||||
Category: "files",
|
||||
})
|
||||
|
||||
dir := getSetting[string](s.Settings(), "dir", "/")
|
||||
if strings.HasPrefix(dir, "~/") {
|
||||
home, _ := os.UserHomeDir()
|
||||
dir = filepath.Join(home, dir[2:])
|
||||
}
|
||||
abs, err := filepath.Abs(dir)
|
||||
if err != nil {
|
||||
return fmt.Errorf("resolve files.dir: %w", err)
|
||||
}
|
||||
p.filesDir = abs
|
||||
os.MkdirAll(p.filesDir, 0755)
|
||||
|
||||
tp := p.name + "_"
|
||||
|
||||
s.RegisterTool(tp+"read", sdk.ToolDef{
|
||||
Name: tp + "read",
|
||||
Description: fmt.Sprintf("Read file contents within the sandbox directory (%s). Supports offset/limit for large files.", p.filesDir),
|
||||
Parameters: map[string]interface{}{
|
||||
"type": "object",
|
||||
"properties": map[string]interface{}{
|
||||
"path": map[string]interface{}{"type": "string", "description": "File path relative to sandbox or absolute"},
|
||||
"offset": map[string]interface{}{"type": "integer", "description": "Starting line number (1-indexed, optional)"},
|
||||
"limit": map[string]interface{}{"type": "integer", "description": "Max lines to return (optional)"},
|
||||
},
|
||||
"required": []string{"path"},
|
||||
},
|
||||
}, p.handleRead)
|
||||
|
||||
s.RegisterTool(tp+"write", sdk.ToolDef{
|
||||
Name: tp + "write",
|
||||
Description: fmt.Sprintf("Write content to a file. Creates parent directories automatically. Sandbox: %s", p.filesDir),
|
||||
Parameters: map[string]interface{}{
|
||||
"type": "object",
|
||||
"properties": map[string]interface{}{
|
||||
"path": map[string]interface{}{"type": "string", "description": "File path"},
|
||||
"content": map[string]interface{}{"type": "string", "description": "Content to write"},
|
||||
"mode": map[string]interface{}{"type": "string", "description": "Write mode: overwrite (default) | append | insert | create"},
|
||||
"line": map[string]interface{}{"type": "integer", "description": "Line number for insert mode (1-indexed)"},
|
||||
},
|
||||
"required": []string{"path", "content"},
|
||||
},
|
||||
}, p.handleWrite)
|
||||
|
||||
s.RegisterTool(tp+"edit", sdk.ToolDef{
|
||||
Name: tp + "edit",
|
||||
Description: fmt.Sprintf("Apply exact string replacements to a file within the sandbox (%s). All edits are matched against the original file content.", p.filesDir),
|
||||
Parameters: map[string]interface{}{
|
||||
"type": "object",
|
||||
"properties": map[string]interface{}{
|
||||
"path": map[string]interface{}{"type": "string", "description": "File path relative to sandbox or absolute"},
|
||||
"edits": map[string]interface{}{
|
||||
"type": "array",
|
||||
"description": "One or more targeted replacements. Each old must match exactly once in the original file. Do not include overlapping edits.",
|
||||
"items": map[string]interface{}{
|
||||
"type": "object",
|
||||
"properties": map[string]interface{}{
|
||||
"old": map[string]interface{}{"type": "string", "description": "Exact text to find (must be unique)"},
|
||||
"new": map[string]interface{}{"type": "string", "description": "Replacement text"},
|
||||
},
|
||||
"required": []string{"old", "new"},
|
||||
},
|
||||
},
|
||||
},
|
||||
"required": []string{"path", "edits"},
|
||||
},
|
||||
}, p.handleEdit)
|
||||
|
||||
s.RegisterTool(tp+"ls", sdk.ToolDef{
|
||||
Name: tp + "ls",
|
||||
Description: fmt.Sprintf("List directory contents within the sandbox (%s). Directories are marked with / suffix.", p.filesDir),
|
||||
Parameters: map[string]interface{}{
|
||||
"type": "object",
|
||||
"properties": map[string]interface{}{
|
||||
"path": map[string]interface{}{"type": "string", "description": "Directory path (optional, defaults to sandbox root)"},
|
||||
"limit": map[string]interface{}{"type": "integer", "description": "Max entries (optional, default 500)"},
|
||||
},
|
||||
},
|
||||
}, p.handleLs)
|
||||
|
||||
log.Printf("[%s] started, sandbox: %s", p.name, p.filesDir)
|
||||
return nil
|
||||
}
|
||||
|
||||
func (p *Plugin) Stop() error {
|
||||
log.Printf("[%s] stopped", p.name)
|
||||
return nil
|
||||
}
|
||||
|
||||
// resolvePath resolves user-provided path to an absolute path within filesDir.
|
||||
func (p *Plugin) resolvePath(userPath string) (string, error) {
|
||||
if userPath == "" {
|
||||
userPath = "."
|
||||
}
|
||||
if !filepath.IsAbs(userPath) {
|
||||
userPath = filepath.Join(p.filesDir, userPath)
|
||||
}
|
||||
abs, err := filepath.Abs(userPath)
|
||||
if err != nil {
|
||||
return "", fmt.Errorf("resolve path: %w", err)
|
||||
}
|
||||
base := filepath.Clean(p.filesDir)
|
||||
if base != "/" && !strings.HasPrefix(abs, base+string(filepath.Separator)) && abs != base {
|
||||
return "", fmt.Errorf("path outside sandbox: %s", userPath)
|
||||
}
|
||||
return abs, nil
|
||||
}
|
||||
|
||||
// handleRead implements the read tool.
|
||||
func (p *Plugin) handleRead(args map[string]interface{}) (interface{}, error) {
|
||||
path, _ := args["path"].(string)
|
||||
if path == "" {
|
||||
return errorResult("path is required"), nil
|
||||
}
|
||||
|
||||
absPath, err := p.resolvePath(path)
|
||||
if err != nil {
|
||||
return errorResult(err.Error()), nil
|
||||
}
|
||||
|
||||
info, err := os.Stat(absPath)
|
||||
if err != nil {
|
||||
if os.IsNotExist(err) {
|
||||
return errorResult("file not found: " + path), nil
|
||||
}
|
||||
return errorResult("stat error: " + err.Error()), nil
|
||||
}
|
||||
if info.IsDir() {
|
||||
return errorResult("is a directory, use ls instead: " + path), nil
|
||||
}
|
||||
|
||||
data, err := os.ReadFile(absPath)
|
||||
if err != nil {
|
||||
return errorResult("read error: " + err.Error()), nil
|
||||
}
|
||||
|
||||
text := string(data)
|
||||
lines := strings.Split(text, "\n")
|
||||
totalLines := len(lines)
|
||||
|
||||
offset := 0
|
||||
if v, ok := args["offset"].(float64); ok && v > 0 {
|
||||
offset = int(v) - 1
|
||||
}
|
||||
if offset >= totalLines {
|
||||
return errorResult(fmt.Sprintf("offset %d exceeds file length (%d lines)", offset+1, totalLines)), nil
|
||||
}
|
||||
|
||||
limit := totalLines - offset
|
||||
if v, ok := args["limit"].(float64); ok && v > 0 {
|
||||
if int(v) < limit {
|
||||
limit = int(v)
|
||||
}
|
||||
}
|
||||
|
||||
end := offset + limit
|
||||
if end > totalLines {
|
||||
end = totalLines
|
||||
}
|
||||
|
||||
selected := lines[offset:end]
|
||||
output := strings.Join(selected, "\n")
|
||||
|
||||
truncated := false
|
||||
if limit < totalLines-offset {
|
||||
truncated = true
|
||||
}
|
||||
|
||||
var sb strings.Builder
|
||||
sb.WriteString(output)
|
||||
if truncated {
|
||||
nextOffset := end + 1
|
||||
sb.WriteString(fmt.Sprintf("\n\n[Showing lines %d-%d of %d. Use offset=%d to continue.]", offset+1, end, totalLines, nextOffset))
|
||||
} else if offset > 0 || end < totalLines {
|
||||
sb.WriteString(fmt.Sprintf("\n\n[%d lines total]", totalLines))
|
||||
}
|
||||
|
||||
return map[string]interface{}{
|
||||
"content": sb.String(),
|
||||
}, nil
|
||||
}
|
||||
|
||||
// handleWrite implements the write tool.
|
||||
func (p *Plugin) handleWrite(args map[string]interface{}) (interface{}, error) {
|
||||
path, _ := args["path"].(string)
|
||||
if path == "" {
|
||||
return errorResult("path is required"), nil
|
||||
}
|
||||
content, _ := args["content"].(string)
|
||||
mode, _ := args["mode"].(string)
|
||||
if mode == "" {
|
||||
mode = "overwrite"
|
||||
}
|
||||
|
||||
line := 0
|
||||
if v, ok := args["line"].(float64); ok && v > 0 {
|
||||
line = int(v)
|
||||
}
|
||||
|
||||
absPath, err := p.resolvePath(path)
|
||||
if err != nil {
|
||||
return errorResult(err.Error()), nil
|
||||
}
|
||||
|
||||
switch mode {
|
||||
case "create":
|
||||
if _, err := os.Stat(absPath); err == nil {
|
||||
return errorResult("file already exists: " + path), nil
|
||||
}
|
||||
dir := filepath.Dir(absPath)
|
||||
if err := os.MkdirAll(dir, 0755); err != nil {
|
||||
return errorResult("mkdir error: " + err.Error()), nil
|
||||
}
|
||||
if err := os.WriteFile(absPath, []byte(content), 0644); err != nil {
|
||||
return errorResult("write error: " + err.Error()), nil
|
||||
}
|
||||
return map[string]interface{}{
|
||||
"content": fmt.Sprintf("Created %s (%d bytes)", path, len(content)),
|
||||
}, nil
|
||||
|
||||
case "append":
|
||||
dir := filepath.Dir(absPath)
|
||||
if err := os.MkdirAll(dir, 0755); err != nil {
|
||||
return errorResult("mkdir error: " + err.Error()), nil
|
||||
}
|
||||
f, err := os.OpenFile(absPath, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
|
||||
if err != nil {
|
||||
return errorResult("open error: " + err.Error()), nil
|
||||
}
|
||||
defer f.Close()
|
||||
if _, err := f.WriteString(content); err != nil {
|
||||
return errorResult("append error: " + err.Error()), nil
|
||||
}
|
||||
return map[string]interface{}{
|
||||
"content": fmt.Sprintf("Appended %d bytes to %s", len(content), path),
|
||||
}, nil
|
||||
|
||||
case "insert":
|
||||
if line < 1 {
|
||||
return errorResult("line must be >= 1 for insert mode"), nil
|
||||
}
|
||||
data, err := os.ReadFile(absPath)
|
||||
if err != nil {
|
||||
if os.IsNotExist(err) {
|
||||
return errorResult("file not found: " + path), nil
|
||||
}
|
||||
return errorResult("read error: " + err.Error()), nil
|
||||
}
|
||||
lines := strings.Split(string(data), "\n")
|
||||
if line > len(lines)+1 {
|
||||
return errorResult(fmt.Sprintf("line %d exceeds file length (%d lines)", line, len(lines))), nil
|
||||
}
|
||||
idx := line - 1
|
||||
newLines := make([]string, 0, len(lines)+1)
|
||||
newLines = append(newLines, lines[:idx]...)
|
||||
newLines = append(newLines, content)
|
||||
newLines = append(newLines, lines[idx:]...)
|
||||
result := strings.Join(newLines, "\n")
|
||||
if err := os.WriteFile(absPath, []byte(result), 0644); err != nil {
|
||||
return errorResult("write error: " + err.Error()), nil
|
||||
}
|
||||
return map[string]interface{}{
|
||||
"content": fmt.Sprintf("Inserted %d bytes at line %d in %s", len(content), line, path),
|
||||
}, nil
|
||||
|
||||
default: // overwrite
|
||||
dir := filepath.Dir(absPath)
|
||||
if err := os.MkdirAll(dir, 0755); err != nil {
|
||||
return errorResult("mkdir error: " + err.Error()), nil
|
||||
}
|
||||
if err := os.WriteFile(absPath, []byte(content), 0644); err != nil {
|
||||
return errorResult("write error: " + err.Error()), nil
|
||||
}
|
||||
return map[string]interface{}{
|
||||
"content": fmt.Sprintf("Wrote %d bytes to %s", len(content), path),
|
||||
}, nil
|
||||
}
|
||||
}
|
||||
|
||||
// handleEdit implements the edit tool.
|
||||
func (p *Plugin) handleEdit(args map[string]interface{}) (interface{}, error) {
|
||||
path, _ := args["path"].(string)
|
||||
if path == "" {
|
||||
return errorResult("path is required"), nil
|
||||
}
|
||||
|
||||
absPath, err := p.resolvePath(path)
|
||||
if err != nil {
|
||||
return errorResult(err.Error()), nil
|
||||
}
|
||||
|
||||
rawEdits, ok := args["edits"].([]interface{})
|
||||
if !ok || len(rawEdits) == 0 {
|
||||
return errorResult("edits must be a non-empty array"), nil
|
||||
}
|
||||
|
||||
data, err := os.ReadFile(absPath)
|
||||
if err != nil {
|
||||
if os.IsNotExist(err) {
|
||||
return errorResult("file not found: " + path), nil
|
||||
}
|
||||
return errorResult("read error: " + err.Error()), nil
|
||||
}
|
||||
|
||||
original := string(data)
|
||||
content := original
|
||||
applied := 0
|
||||
var errors []string
|
||||
|
||||
for i, raw := range rawEdits {
|
||||
edit, ok := raw.(map[string]interface{})
|
||||
if !ok {
|
||||
errors = append(errors, fmt.Sprintf("edit[%d]: invalid format", i))
|
||||
continue
|
||||
}
|
||||
oldText, _ := edit["old"].(string)
|
||||
newText, _ := edit["new"].(string)
|
||||
if oldText == "" {
|
||||
errors = append(errors, fmt.Sprintf("edit[%d]: old is required", i))
|
||||
continue
|
||||
}
|
||||
|
||||
count := strings.Count(content, oldText)
|
||||
if count == 0 {
|
||||
errors = append(errors, fmt.Sprintf("edit[%d]: could not find %q in %s", i, oldText, path))
|
||||
continue
|
||||
}
|
||||
if count > 1 {
|
||||
errors = append(errors, fmt.Sprintf("edit[%d]: found %d occurrences of %q, must be unique", i, count, oldText))
|
||||
continue
|
||||
}
|
||||
|
||||
content = strings.Replace(content, oldText, newText, 1)
|
||||
applied++
|
||||
}
|
||||
|
||||
if applied == 0 {
|
||||
msg := "no edits applied"
|
||||
if len(errors) > 0 {
|
||||
msg += ": " + strings.Join(errors, "; ")
|
||||
}
|
||||
return errorResult(msg), nil
|
||||
}
|
||||
|
||||
if err := os.WriteFile(absPath, []byte(content), 0644); err != nil {
|
||||
return errorResult("write error: " + err.Error()), nil
|
||||
}
|
||||
|
||||
msg := fmt.Sprintf("Successfully applied %d/%d edits to %s", applied, len(rawEdits), path)
|
||||
if len(errors) > 0 {
|
||||
msg += "\nWarnings:\n" + strings.Join(errors, "\n")
|
||||
}
|
||||
|
||||
return map[string]interface{}{
|
||||
"content": msg,
|
||||
}, nil
|
||||
}
|
||||
|
||||
// handleLs implements the ls tool.
|
||||
func (p *Plugin) handleLs(args map[string]interface{}) (interface{}, error) {
|
||||
path, _ := args["path"].(string)
|
||||
if path == "" {
|
||||
path = "."
|
||||
}
|
||||
|
||||
absPath, err := p.resolvePath(path)
|
||||
if err != nil {
|
||||
return errorResult(err.Error()), nil
|
||||
}
|
||||
|
||||
info, err := os.Stat(absPath)
|
||||
if err != nil {
|
||||
if os.IsNotExist(err) {
|
||||
return errorResult("path not found: " + path), nil
|
||||
}
|
||||
return errorResult("stat error: " + err.Error()), nil
|
||||
}
|
||||
if !info.IsDir() {
|
||||
return errorResult("not a directory: " + path), nil
|
||||
}
|
||||
|
||||
entries, err := os.ReadDir(absPath)
|
||||
if err != nil {
|
||||
return errorResult("readdir error: " + err.Error()), nil
|
||||
}
|
||||
|
||||
limit := 500
|
||||
if v, ok := args["limit"].(float64); ok && v > 0 {
|
||||
limit = int(v)
|
||||
}
|
||||
|
||||
sort.Slice(entries, func(i, j int) bool {
|
||||
return strings.ToLower(entries[i].Name()) < strings.ToLower(entries[j].Name())
|
||||
})
|
||||
|
||||
var lines []string
|
||||
entryLimitReached := false
|
||||
for i, entry := range entries {
|
||||
if i >= limit {
|
||||
entryLimitReached = true
|
||||
break
|
||||
}
|
||||
name := entry.Name()
|
||||
if entry.IsDir() {
|
||||
name += "/"
|
||||
}
|
||||
lines = append(lines, name)
|
||||
}
|
||||
|
||||
if len(lines) == 0 {
|
||||
return map[string]interface{}{
|
||||
"content": "(empty directory)",
|
||||
}, nil
|
||||
}
|
||||
|
||||
output := strings.Join(lines, "\n")
|
||||
if entryLimitReached {
|
||||
output += fmt.Sprintf("\n\n[%d entries limit reached. Use limit=N for more.]", limit)
|
||||
}
|
||||
|
||||
return map[string]interface{}{
|
||||
"content": output,
|
||||
}, nil
|
||||
}
|
||||
|
||||
// errorResult returns a standardized error result.
|
||||
func errorResult(msg string) map[string]interface{} {
|
||||
return map[string]interface{}{
|
||||
"isError": true,
|
||||
"content": msg,
|
||||
}
|
||||
}
|
||||
|
||||
// getSetting reads a setting with generic type assertion.
|
||||
func getSetting[T any](s sdk.SettingsAPI, key string, def T) T {
|
||||
v, err := s.Get(key)
|
||||
if err != nil || v == nil {
|
||||
return def
|
||||
}
|
||||
val, ok := v.(T)
|
||||
if !ok {
|
||||
return def
|
||||
}
|
||||
return val
|
||||
}
|
||||
|
||||
func NewPlugin(name string, config map[string]interface{}) (sdk.Plugin, error) {
|
||||
return &Plugin{name: name}, nil
|
||||
}
|
||||
3
_sdk_local/go.mod
Normal file
3
_sdk_local/go.mod
Normal file
@ -0,0 +1,3 @@
|
||||
module gitcode.com/JianFeeeee/homeagent-sdk
|
||||
|
||||
go 1.25.0
|
||||
23
_sdk_local/meta/meta.go
Normal file
23
_sdk_local/meta/meta.go
Normal file
@ -0,0 +1,23 @@
|
||||
// Package meta 收集 HomeAgent SDK 的全部元数据。
|
||||
// 版本号应与核心 meta.Version 保持一致。
|
||||
package meta
|
||||
|
||||
var (
|
||||
// Version 是 HomeAgent SDK 版本号。
|
||||
// 通过 `-ldflags="-X gitcode.com/JianFeeeee/homeagent-sdk/meta.Version=vX.Y.Z"` 注入。
|
||||
Version = "0.7.1"
|
||||
|
||||
// Commit 是构建时的 Git commit hash。
|
||||
Commit = "unknown"
|
||||
|
||||
// BuildTime 是构建时间。
|
||||
BuildTime = "unknown"
|
||||
|
||||
// SDKName 是 SDK 名称。
|
||||
SDKName = "HomeAgent SDK"
|
||||
)
|
||||
|
||||
// FullVersion 返回完整的版本字符串。
|
||||
func FullVersion() string {
|
||||
return SDKName + " v" + Version + " (" + Commit + ")"
|
||||
}
|
||||
14
_sdk_local/sdk/knowledge.go
Normal file
14
_sdk_local/sdk/knowledge.go
Normal file
@ -0,0 +1,14 @@
|
||||
package sdk
|
||||
|
||||
// KnowledgeAPI provides access to the knowledge store.
|
||||
type KnowledgeAPI interface {
|
||||
Search(query string, topK int) ([]*Knowledge, error)
|
||||
Add(name, content string) error
|
||||
List() ([]string, error)
|
||||
}
|
||||
|
||||
// Knowledge represents a knowledge entry.
|
||||
type Knowledge struct {
|
||||
Name string `json:"name"`
|
||||
Content string `json:"content"`
|
||||
}
|
||||
8
_sdk_local/sdk/llm.go
Normal file
8
_sdk_local/sdk/llm.go
Normal file
@ -0,0 +1,8 @@
|
||||
package sdk
|
||||
|
||||
// LLMAPI provides access to the LLM provider manager.
|
||||
type LLMAPI interface {
|
||||
ListSources() []string
|
||||
SetSource(name string) error
|
||||
CurrentSource() string
|
||||
}
|
||||
87
_sdk_local/sdk/memory.go
Normal file
87
_sdk_local/sdk/memory.go
Normal file
@ -0,0 +1,87 @@
|
||||
package sdk
|
||||
|
||||
// MemoryAPI provides access to the graph memory (entity-relation store).
|
||||
type MemoryAPI interface {
|
||||
Recall(query []string, depth int) ([]Entity, []Relation, error)
|
||||
Commit(triples []Triple) error
|
||||
Introspect() (map[string]interface{}, error)
|
||||
MergeEntities(source, target string) (int, error)
|
||||
Purge(criteria map[string]string, mode string) (int, error)
|
||||
}
|
||||
|
||||
// Entity represents a named entity in the knowledge graph.
|
||||
type Entity struct {
|
||||
Name string `json:"name"`
|
||||
Type string `json:"type"`
|
||||
MentionCount int `json:"mention_count"`
|
||||
}
|
||||
|
||||
// Relation represents a relationship between two entities.
|
||||
type Relation struct {
|
||||
SourceName string `json:"source_name"`
|
||||
TargetName string `json:"target_name"`
|
||||
RelationType string `json:"relation_type"`
|
||||
Confidence float64 `json:"confidence,omitempty"`
|
||||
}
|
||||
|
||||
// Triple represents a subject-relation-object triple for the knowledge graph.
|
||||
type Triple struct {
|
||||
Subject string `json:"subject"`
|
||||
Relation string `json:"relation"`
|
||||
Object string `json:"object"`
|
||||
Confidence float64 `json:"confidence,omitempty"`
|
||||
SubjectType string `json:"subject_type,omitempty"`
|
||||
ObjectType string `json:"object_type,omitempty"`
|
||||
}
|
||||
|
||||
// TextMemoryAPI provides access to chronological text event storage.
|
||||
type TextMemoryAPI interface {
|
||||
Append(evt TextEvent) error
|
||||
}
|
||||
|
||||
// TextEvent represents a single text memory event.
|
||||
type TextEvent struct {
|
||||
Role string `json:"role"`
|
||||
Content string `json:"content"`
|
||||
Timestamp int64 `json:"timestamp"`
|
||||
Channel string `json:"channel,omitempty"`
|
||||
}
|
||||
|
||||
// DocMemoryAPI provides access to the document vector store.
|
||||
type DocMemoryAPI interface {
|
||||
Query(text string, topK int) []*Doc
|
||||
Insert(doc *Doc) error
|
||||
Remove(id string)
|
||||
Stats() map[string]interface{}
|
||||
}
|
||||
|
||||
// Doc represents a document in the document store.
|
||||
type Doc struct {
|
||||
ID string `json:"id"`
|
||||
Title string `json:"title"`
|
||||
Content string `json:"content"`
|
||||
Score float64 `json:"score,omitempty"`
|
||||
}
|
||||
|
||||
// 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.
|
||||
type SocialAPI interface {
|
||||
GetPerson(name string) (*PersonProfile, error)
|
||||
GetTrait(name, trait string) (string, bool)
|
||||
GetRelations(name string) ([]SocialRelation, error)
|
||||
GetNetwork(name string, depth int) ([]*PersonProfile, error)
|
||||
ListPersons() ([]string, error)
|
||||
}
|
||||
|
||||
// PersonProfile represents a person's complete profile (traits + social relations).
|
||||
type PersonProfile struct {
|
||||
Name string `json:"name"`
|
||||
Traits map[string]string `json:"traits,omitempty"`
|
||||
Relations []SocialRelation `json:"relations,omitempty"`
|
||||
}
|
||||
|
||||
// SocialRelation represents a social relationship between two persons.
|
||||
type SocialRelation struct {
|
||||
Person string `json:"person"`
|
||||
Relation string `json:"relation"`
|
||||
}
|
||||
356
_sdk_local/sdk/plugin.go
Normal file
356
_sdk_local/sdk/plugin.go
Normal file
@ -0,0 +1,356 @@
|
||||
package sdk
|
||||
|
||||
import (
|
||||
"sync"
|
||||
|
||||
"gitcode.com/JianFeeeee/homeagent-sdk/meta"
|
||||
)
|
||||
|
||||
// SDKVersion 是对外暴露的 SDK 版本号。
|
||||
var SDKVersion = meta.Version
|
||||
|
||||
// Plugin is the interface every plugin must implement.
|
||||
type Plugin interface {
|
||||
Name() string
|
||||
Start(sdk *PluginSDK) error
|
||||
Stop() error
|
||||
}
|
||||
|
||||
// ToolHandler is a function that handles a tool call.
|
||||
type ToolHandler func(args map[string]interface{}) (interface{}, error)
|
||||
|
||||
// StageHandler is a function that handles a pipeline stage event.
|
||||
type StageHandler func(ctx *StageContext) error
|
||||
|
||||
// Stage represents a point in the message processing pipeline.
|
||||
type Stage string
|
||||
|
||||
const (
|
||||
StageOnInput Stage = "on_input"
|
||||
StagePreAction Stage = "pre_action"
|
||||
StagePostAction Stage = "post_action"
|
||||
StageBeforeToolcall Stage = "before_toolcall"
|
||||
StageAfterToolcall Stage = "after_toolcall"
|
||||
StageBeforeOutput Stage = "before_output"
|
||||
StageAfterOutput Stage = "after_output"
|
||||
)
|
||||
|
||||
// StageContext provides context for stage handlers.
|
||||
type StageContext struct {
|
||||
mu sync.RWMutex
|
||||
RawMessage string
|
||||
UserID string
|
||||
GroupID string
|
||||
ContextMsgs []map[string]interface{}
|
||||
LLMText string
|
||||
ReasoningContent string
|
||||
TokenUsage map[string]int
|
||||
ToolCalls []ToolCall
|
||||
ToolResults []ToolResult
|
||||
FinalText string
|
||||
Response *string
|
||||
Phase Stage
|
||||
Memory []MemItem
|
||||
NoMemory bool
|
||||
Extra map[string]interface{}
|
||||
Errors []string // 阶段处理过程中的错误信息
|
||||
}
|
||||
|
||||
func (c *StageContext) RLock() { c.mu.RLock() }
|
||||
func (c *StageContext) RUnlock() { c.mu.RUnlock() }
|
||||
func (c *StageContext) Lock() { c.mu.Lock() }
|
||||
func (c *StageContext) Unlock() { c.mu.Unlock() }
|
||||
func (c *StageContext) IsResponded() bool { c.mu.RLock(); defer c.mu.RUnlock(); return c.Response != nil }
|
||||
|
||||
// MemItem represents a memory item in stage context.
|
||||
type MemItem struct {
|
||||
Role string `json:"role"`
|
||||
Content string `json:"content"`
|
||||
Score float64 `json:"score"`
|
||||
}
|
||||
|
||||
// ToolCall represents a model's request to call a tool.
|
||||
type ToolCall struct {
|
||||
ID string `json:"id"`
|
||||
Name string `json:"name"`
|
||||
Plugin string `json:"plugin,omitempty"`
|
||||
Arguments map[string]interface{} `json:"arguments"`
|
||||
}
|
||||
|
||||
// ToolResult represents the result of a tool call.
|
||||
type ToolResult struct {
|
||||
CallID string `json:"call_id"`
|
||||
Name string `json:"name"`
|
||||
Plugin string `json:"plugin,omitempty"`
|
||||
Success bool `json:"success"`
|
||||
Result interface{} `json:"result"`
|
||||
}
|
||||
|
||||
// ToolDef describes a tool that the plugin exposes.
|
||||
type ToolDef struct {
|
||||
Name string `json:"name"`
|
||||
Plugin string `json:"plugin,omitempty"`
|
||||
Description string `json:"description"`
|
||||
Parameters map[string]interface{} `json:"parameters"`
|
||||
NoMemory bool `json:"no_memory,omitempty"`
|
||||
}
|
||||
|
||||
// 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.
|
||||
type IOInjector interface {
|
||||
InjectInterruptText(source, channel, text string)
|
||||
InjectText(source, channel, text string)
|
||||
InjectTextNoMemory(source, channel, text string)
|
||||
}
|
||||
|
||||
// EventType identifies the kind of system event.
|
||||
type EventType string
|
||||
|
||||
const (
|
||||
EventRawInput EventType = "raw_input"
|
||||
EventAgentOutput EventType = "agent_output"
|
||||
EventAgentLLMChain EventType = "agent_llm_chain"
|
||||
EventToolCall EventType = "tool_call"
|
||||
EventReasoning EventType = "reasoning"
|
||||
EventStage EventType = "stage"
|
||||
EventSystem EventType = "system"
|
||||
)
|
||||
|
||||
// Event represents a system event published by the kernel.
|
||||
type Event struct {
|
||||
Type EventType `json:"type"`
|
||||
Source string `json:"source"`
|
||||
Payload map[string]interface{} `json:"payload"`
|
||||
Timestamp int64 `json:"timestamp"`
|
||||
}
|
||||
|
||||
// EventHandler processes a system event.
|
||||
type EventHandler func(evt *Event)
|
||||
|
||||
// EventSubscriber allows plugins to subscribe to kernel events.
|
||||
// This is a restricted interface: plugins can subscribe but the kernel
|
||||
// controls which events are delivered.
|
||||
type EventSubscriber interface {
|
||||
Subscribe(eventType EventType, handler EventHandler) func()
|
||||
}
|
||||
|
||||
// StageScope controls which events a stage handler receives.
|
||||
type StageScope int
|
||||
|
||||
const (
|
||||
// StageScopeGlobal receives all stage events (default).
|
||||
StageScopeGlobal StageScope = 0
|
||||
// StageScopeOwnTools only receives events for this plugin's own tool calls
|
||||
// (before_toolcall / after_toolcall only). Other stages degrade to global.
|
||||
StageScopeOwnTools StageScope = 1
|
||||
)
|
||||
|
||||
// ToolRegistrar registers a tool dynamically.
|
||||
type ToolRegistrar func(name string, def ToolDef, handler ToolHandler) error
|
||||
|
||||
// StageRegistrar registers a stage handler.
|
||||
type StageRegistrar func(stage Stage, handler StageHandler)
|
||||
|
||||
// APIRegistrar registers a plugin API for external access.
|
||||
type APIRegistrar func(name string) error
|
||||
|
||||
// OutputChannelRegistrar registers an output channel that the output_send tool can use.
|
||||
type OutputChannelRegistrar func(name string, caps int, desc string, handler ToolHandler) error
|
||||
|
||||
// Output capability flags
|
||||
const (
|
||||
CapText = 1
|
||||
CapFile = 2
|
||||
CapImage = 4
|
||||
CapAudio = 8
|
||||
CapStructured = 16
|
||||
)
|
||||
|
||||
// PluginSDK is the main API surface provided to plugins at runtime.
|
||||
// It wraps tool registration, settings, memory, knowledge, LLM, and IO injection.
|
||||
type PluginSDK struct {
|
||||
name string
|
||||
regTool ToolRegistrar
|
||||
regStage StageRegistrar
|
||||
regAPI APIRegistrar
|
||||
regOutput OutputChannelRegistrar
|
||||
io IOInjector
|
||||
mem MemoryAPI
|
||||
textMem TextMemoryAPI
|
||||
docMem DocMemoryAPI
|
||||
know KnowledgeAPI
|
||||
llm LLMAPI
|
||||
sett SettingsAPI
|
||||
social SocialAPI
|
||||
events EventSubscriber
|
||||
|
||||
autoRestart bool
|
||||
textCleaners []func(text string) string
|
||||
}
|
||||
|
||||
// New creates a PluginSDK with the given dependencies.
|
||||
func New(name string, sett SettingsAPI, regTool ToolRegistrar, regStage StageRegistrar, regAPI APIRegistrar, regOutput OutputChannelRegistrar) *PluginSDK {
|
||||
return &PluginSDK{
|
||||
name: name,
|
||||
sett: sett,
|
||||
regTool: regTool,
|
||||
regStage: regStage,
|
||||
regAPI: regAPI,
|
||||
regOutput: regOutput,
|
||||
autoRestart: true,
|
||||
textCleaners: make([]func(text string) string, 0),
|
||||
}
|
||||
}
|
||||
|
||||
// PluginName returns the name of the plugin.
|
||||
func (s *PluginSDK) PluginName() string { return s.name }
|
||||
|
||||
// Settings returns the settings API for reading/writing plugin configuration.
|
||||
func (s *PluginSDK) Settings() SettingsAPI { return s.sett }
|
||||
|
||||
// Memory returns the graph memory API (may be nil if not available).
|
||||
func (s *PluginSDK) Memory() MemoryAPI { return s.mem }
|
||||
|
||||
// TextMemory returns the text memory API (may be nil if not available).
|
||||
func (s *PluginSDK) TextMemory() TextMemoryAPI { return s.textMem }
|
||||
|
||||
// DocMemory returns the document memory API (may be nil if not available).
|
||||
func (s *PluginSDK) DocMemory() DocMemoryAPI { return s.docMem }
|
||||
|
||||
// Knowledge returns the knowledge store API (may be nil if not available).
|
||||
func (s *PluginSDK) Knowledge() KnowledgeAPI { return s.know }
|
||||
|
||||
// LLM returns the LLM provider API (may be nil if not available).
|
||||
func (s *PluginSDK) LLM() LLMAPI { return s.llm }
|
||||
|
||||
// Social returns the social graph API (may be nil if not available).
|
||||
func (s *PluginSDK) Social() SocialAPI { return s.social }
|
||||
|
||||
// Events returns the event subscriber for listening to kernel events (may be nil if not available).
|
||||
func (s *PluginSDK) Events() EventSubscriber { return s.events }
|
||||
|
||||
// RegisterTool registers a tool that the LLM can call.
|
||||
func (s *PluginSDK) RegisterTool(name string, def ToolDef, handler ToolHandler) error {
|
||||
if def.Plugin == "" {
|
||||
def.Plugin = s.name
|
||||
}
|
||||
if s.regTool != nil {
|
||||
return s.regTool(name, def, handler)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// 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.
|
||||
func (s *PluginSDK) RegisterStage(stage Stage, handler StageHandler, scope ...StageScope) {
|
||||
if s.regStage == nil {
|
||||
return
|
||||
}
|
||||
sc := StageScopeGlobal
|
||||
if len(scope) > 0 {
|
||||
sc = scope[0]
|
||||
}
|
||||
if sc == StageScopeGlobal {
|
||||
s.regStage(stage, handler)
|
||||
return
|
||||
}
|
||||
// OwnTools scope — only for before_toolcall / after_toolcall
|
||||
if stage != StageBeforeToolcall && stage != StageAfterToolcall {
|
||||
s.regStage(stage, handler)
|
||||
return
|
||||
}
|
||||
s.regStage(stage, func(ctx *StageContext) error {
|
||||
ctx.RLock()
|
||||
match := false
|
||||
switch stage {
|
||||
case StageBeforeToolcall:
|
||||
match = len(ctx.ToolCalls) > 0 && ctx.ToolCalls[0].Plugin == s.name
|
||||
case StageAfterToolcall:
|
||||
match = len(ctx.ToolResults) > 0 && ctx.ToolResults[0].Plugin == s.name
|
||||
}
|
||||
ctx.RUnlock()
|
||||
if !match {
|
||||
return nil
|
||||
}
|
||||
return handler(ctx)
|
||||
})
|
||||
}
|
||||
|
||||
// RegisterPluginAPI registers this plugin's API for access by other plugins.
|
||||
func (s *PluginSDK) RegisterPluginAPI(name string) error {
|
||||
if s.regAPI != nil {
|
||||
return s.regAPI(name)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// RegisterOutputChannel registers an output channel that the output_send tool can route to.
|
||||
// name: channel name (e.g. "qq", "webui")
|
||||
// caps: bitmask of supported output capabilities (CapText, CapFile, etc.)
|
||||
// desc: description of the channel, expected meta format, and type enum
|
||||
// handler: receives args map with keys: payload (string), type (string), meta (string|optional)
|
||||
func (s *PluginSDK) RegisterOutputChannel(name string, caps int, desc string, handler ToolHandler) error {
|
||||
if s.regOutput != nil {
|
||||
return s.regOutput(name, caps, desc, handler)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// SetOutputChannelRegistrar sets the output channel registrar (called by the core at startup).
|
||||
func (s *PluginSDK) SetOutputChannelRegistrar(r OutputChannelRegistrar) { s.regOutput = r }
|
||||
|
||||
// SetIOInjector sets the IO injector (called by the core at startup).
|
||||
func (s *PluginSDK) SetIOInjector(io IOInjector) { s.io = io }
|
||||
|
||||
// SetMemoryAPI sets the memory API (called by the core at startup).
|
||||
func (s *PluginSDK) SetMemoryAPI(mem MemoryAPI) { s.mem = mem }
|
||||
func (s *PluginSDK) SetTextMemoryAPI(tm TextMemoryAPI) { s.textMem = tm }
|
||||
func (s *PluginSDK) SetDocMemoryAPI(dm DocMemoryAPI) { s.docMem = dm }
|
||||
func (s *PluginSDK) SetKnowledgeAPI(kn KnowledgeAPI) { s.know = kn }
|
||||
func (s *PluginSDK) SetLLMAPI(llm LLMAPI) { s.llm = llm }
|
||||
func (s *PluginSDK) SetSocialAPI(social SocialAPI) { s.social = social }
|
||||
func (s *PluginSDK) SetEventSubscriber(es EventSubscriber) { s.events = es }
|
||||
|
||||
// ---- IO Convenience Methods ----
|
||||
|
||||
// InjectInterruptText injects a text interrupt that can preempt current LLM processing.
|
||||
func (s *PluginSDK) InjectInterruptText(source, channel, text string) {
|
||||
if s.io != nil {
|
||||
s.io.InjectInterruptText(source, channel, text)
|
||||
}
|
||||
}
|
||||
|
||||
// InjectText injects a text message into the agent pipeline.
|
||||
func (s *PluginSDK) InjectText(source, channel, text string) {
|
||||
if s.io != nil {
|
||||
s.io.InjectText(source, channel, text)
|
||||
}
|
||||
}
|
||||
|
||||
// InjectTextNoMemory injects a text message without generating memory.
|
||||
func (s *PluginSDK) InjectTextNoMemory(source, channel, text string) {
|
||||
if s.io != nil {
|
||||
s.io.InjectTextNoMemory(source, channel, text)
|
||||
}
|
||||
}
|
||||
|
||||
// SetAutoRestart 设置插件是否允许内核自动重启（崩溃后自动重载）。
|
||||
// 默认 true。如果插件有无法恢复的状态（如外部连接），应设为 false。
|
||||
func (s *PluginSDK) SetAutoRestart(enabled bool) { s.autoRestart = enabled }
|
||||
|
||||
// AutoRestart 返回插件是否允许自动重启。
|
||||
func (s *PluginSDK) AutoRestart() bool { return s.autoRestart }
|
||||
|
||||
// RegisterTextCleaner registers a text cleaning function that is applied to
|
||||
// all text before it enters memory. Multiple cleaners can be registered and
|
||||
// are applied in registration order.
|
||||
func (s *PluginSDK) RegisterTextCleaner(cleaner func(text string) string) {
|
||||
s.textCleaners = append(s.textCleaners, cleaner)
|
||||
}
|
||||
|
||||
// TextCleaners returns all registered text cleaning functions.
|
||||
func (s *PluginSDK) TextCleaners() []func(text string) string {
|
||||
return s.textCleaners
|
||||
}
|
||||
229
_sdk_local/sdk/plugin_test.go
Normal file
229
_sdk_local/sdk/plugin_test.go
Normal file
@ -0,0 +1,229 @@
|
||||
package sdk
|
||||
|
||||
import (
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestRegisterStageGlobalDefault(t *testing.T) {
|
||||
called := false
|
||||
regStage := func(stage Stage, handler StageHandler) {
|
||||
called = true
|
||||
}
|
||||
s := &PluginSDK{regStage: regStage, name: "test"}
|
||||
s.RegisterStage(StageBeforeToolcall, func(ctx *StageContext) error { return nil })
|
||||
|
||||
if !called {
|
||||
t.Error("global scope: handler not registered")
|
||||
}
|
||||
}
|
||||
|
||||
func TestRegisterStageGlobalExplicit(t *testing.T) {
|
||||
called := false
|
||||
regStage := func(stage Stage, handler StageHandler) {
|
||||
called = true
|
||||
}
|
||||
s := &PluginSDK{regStage: regStage, name: "test"}
|
||||
s.RegisterStage(StageBeforeToolcall, func(ctx *StageContext) error { return nil }, StageScopeGlobal)
|
||||
|
||||
if !called {
|
||||
t.Error("global scope: handler not registered")
|
||||
}
|
||||
}
|
||||
|
||||
func TestRegisterStageOwnToolsMatch(t *testing.T) {
|
||||
var registered StageHandler
|
||||
regStage := func(stage Stage, handler StageHandler) {
|
||||
registered = handler
|
||||
}
|
||||
s := &PluginSDK{regStage: regStage, name: "myplugin"}
|
||||
s.RegisterStage(StageBeforeToolcall, func(ctx *StageContext) error { return nil }, StageScopeOwnTools)
|
||||
|
||||
if registered == nil {
|
||||
t.Fatal("handler not registered")
|
||||
}
|
||||
|
||||
ctx := &StageContext{}
|
||||
ctx.ToolCalls = []ToolCall{{Plugin: "myplugin", Name: "my_tool"}}
|
||||
ctx.ToolResults = nil
|
||||
|
||||
err := registered(ctx)
|
||||
if err != nil {
|
||||
t.Errorf("expected nil, got %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestRegisterStageOwnToolsSkipOtherPlugin(t *testing.T) {
|
||||
var registered StageHandler
|
||||
regStage := func(stage Stage, handler StageHandler) {
|
||||
registered = handler
|
||||
}
|
||||
s := &PluginSDK{regStage: regStage, name: "myplugin"}
|
||||
|
||||
callCount := 0
|
||||
s.RegisterStage(StageBeforeToolcall, func(ctx *StageContext) error {
|
||||
callCount++
|
||||
return nil
|
||||
}, StageScopeOwnTools)
|
||||
|
||||
if registered == nil {
|
||||
t.Fatal("handler not registered")
|
||||
}
|
||||
|
||||
ctx := &StageContext{}
|
||||
ctx.ToolCalls = []ToolCall{{Plugin: "other", Name: "other_tool"}}
|
||||
|
||||
err := registered(ctx)
|
||||
if err != nil {
|
||||
t.Errorf("expected nil, got %v", err)
|
||||
}
|
||||
if callCount != 0 {
|
||||
t.Error("handler should not be called for other plugin's tool")
|
||||
}
|
||||
}
|
||||
|
||||
func TestRegisterStageOwnToolsNonToolcallDegrades(t *testing.T) {
|
||||
regStage := func(stage Stage, handler StageHandler) {
|
||||
if stage != StagePreAction {
|
||||
t.Errorf("expected StagePreAction, got %s", stage)
|
||||
}
|
||||
}
|
||||
s := &PluginSDK{regStage: regStage, name: "test"}
|
||||
s.RegisterStage(StagePreAction, func(ctx *StageContext) error { return nil }, StageScopeOwnTools)
|
||||
}
|
||||
|
||||
func TestRegisterStageOwnToolsStageBeforeToolcallNoToolCalls(t *testing.T) {
|
||||
var registered StageHandler
|
||||
regStage := func(stage Stage, handler StageHandler) {
|
||||
registered = handler
|
||||
}
|
||||
s := &PluginSDK{regStage: regStage, name: "myplugin"}
|
||||
|
||||
callCount := 0
|
||||
s.RegisterStage(StageBeforeToolcall, func(ctx *StageContext) error {
|
||||
callCount++
|
||||
return nil
|
||||
}, StageScopeOwnTools)
|
||||
|
||||
if registered == nil {
|
||||
t.Fatal("handler not registered")
|
||||
}
|
||||
|
||||
ctx := &StageContext{}
|
||||
|
||||
err := registered(ctx)
|
||||
if err != nil {
|
||||
t.Errorf("expected nil, got %v", err)
|
||||
}
|
||||
if callCount != 0 {
|
||||
t.Error("handler should not be called when ToolCalls is empty")
|
||||
}
|
||||
}
|
||||
|
||||
func TestRegisterStageOwnToolsStageAfterToolcallMatch(t *testing.T) {
|
||||
var registered StageHandler
|
||||
regStage := func(stage Stage, handler StageHandler) {
|
||||
registered = handler
|
||||
}
|
||||
s := &PluginSDK{regStage: regStage, name: "myplugin"}
|
||||
|
||||
callCount := 0
|
||||
s.RegisterStage(StageAfterToolcall, func(ctx *StageContext) error {
|
||||
callCount++
|
||||
return nil
|
||||
}, StageScopeOwnTools)
|
||||
|
||||
if registered == nil {
|
||||
t.Fatal("handler not registered")
|
||||
}
|
||||
|
||||
ctx := &StageContext{}
|
||||
ctx.ToolResults = []ToolResult{{Plugin: "myplugin", Name: "my_tool"}}
|
||||
|
||||
err := registered(ctx)
|
||||
if err != nil {
|
||||
t.Errorf("expected nil, got %v", err)
|
||||
}
|
||||
if callCount != 1 {
|
||||
t.Error("handler should be called for own plugin's tool result")
|
||||
}
|
||||
}
|
||||
|
||||
func TestRegisterStageOwnToolsStageAfterToolcallSkip(t *testing.T) {
|
||||
var registered StageHandler
|
||||
regStage := func(stage Stage, handler StageHandler) {
|
||||
registered = handler
|
||||
}
|
||||
s := &PluginSDK{regStage: regStage, name: "myplugin"}
|
||||
|
||||
callCount := 0
|
||||
s.RegisterStage(StageAfterToolcall, func(ctx *StageContext) error {
|
||||
callCount++
|
||||
return nil
|
||||
}, StageScopeOwnTools)
|
||||
|
||||
ctx := &StageContext{}
|
||||
ctx.ToolResults = []ToolResult{{Plugin: "other", Name: "other_tool"}}
|
||||
|
||||
err := registered(ctx)
|
||||
if err != nil {
|
||||
t.Errorf("expected nil, got %v", err)
|
||||
}
|
||||
if callCount != 0 {
|
||||
t.Error("handler should not be called for other plugin's tool result")
|
||||
}
|
||||
}
|
||||
|
||||
func TestRegisterStageOwnToolsNilRegStage(t *testing.T) {
|
||||
s := &PluginSDK{name: "test"}
|
||||
s.RegisterStage(StageBeforeToolcall, func(ctx *StageContext) error { return nil }, StageScopeOwnTools)
|
||||
}
|
||||
|
||||
func TestToolDefNoMemory(t *testing.T) {
|
||||
def := ToolDef{
|
||||
Name: "test_tool",
|
||||
NoMemory: true,
|
||||
}
|
||||
if !def.NoMemory {
|
||||
t.Error("NoMemory should be true")
|
||||
}
|
||||
def2 := ToolDef{Name: "normal_tool"}
|
||||
if def2.NoMemory {
|
||||
t.Error("default NoMemory should be false")
|
||||
}
|
||||
}
|
||||
|
||||
func TestRegisterTextCleaner(t *testing.T) {
|
||||
s := &PluginSDK{name: "test"}
|
||||
|
||||
c1 := func(text string) string { return text + "_c1" }
|
||||
c2 := func(text string) string { return text + "_c2" }
|
||||
|
||||
s.RegisterTextCleaner(c1)
|
||||
s.RegisterTextCleaner(c2)
|
||||
|
||||
cleaners := s.TextCleaners()
|
||||
if len(cleaners) != 2 {
|
||||
t.Fatalf("expected 2 cleaners, got %d", len(cleaners))
|
||||
}
|
||||
|
||||
got := cleaners[0]("hello")
|
||||
if got != "hello_c1" {
|
||||
t.Errorf("expected hello_c1, got %s", got)
|
||||
}
|
||||
|
||||
got = cleaners[1]("hello")
|
||||
if got != "hello_c2" {
|
||||
t.Errorf("expected hello_c2, got %s", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestTextCleanersEmpty(t *testing.T) {
|
||||
s := New("test", nil, nil, nil, nil, nil)
|
||||
cleaners := s.TextCleaners()
|
||||
if cleaners == nil {
|
||||
t.Error("TextCleaners should return empty slice, not nil")
|
||||
}
|
||||
if len(cleaners) != 0 {
|
||||
t.Errorf("expected 0 cleaners, got %d", len(cleaners))
|
||||
}
|
||||
}
|
||||
58
_sdk_local/sdk/settings.go
Normal file
58
_sdk_local/sdk/settings.go
Normal file
@ -0,0 +1,58 @@
|
||||
package sdk
|
||||
|
||||
type SettingsAPI interface {
|
||||
// Get reads the plugin's own config value (config_<name> table).
|
||||
Get(key string) (interface{}, error)
|
||||
|
||||
// Set writes a config value to the plugin's own config table.
|
||||
Set(key string, value interface{}) error
|
||||
|
||||
// List returns all keys matching the given prefix.
|
||||
List(prefix string) ([]string, error)
|
||||
|
||||
// GetCore reads the core config table.
|
||||
GetCore(key string) (interface{}, error)
|
||||
|
||||
// SetCore writes to the core config table.
|
||||
SetCore(key string, value interface{}) error
|
||||
|
||||
// ListCore lists core config keys matching the prefix.
|
||||
ListCore(prefix string) ([]string, error)
|
||||
|
||||
// GetPlugin reads another plugin's config table.
|
||||
GetPlugin(plugin, key string) (interface{}, error)
|
||||
|
||||
// SetPlugin writes to another plugin's config table.
|
||||
SetPlugin(plugin, key string, value interface{}) error
|
||||
|
||||
// ListPlugin lists another plugin's config keys matching the prefix.
|
||||
ListPlugin(plugin, prefix string) ([]string, error)
|
||||
|
||||
// RegisterDef registers a config definition for UI display.
|
||||
RegisterDef(def ConfigDef)
|
||||
|
||||
// Defs returns config definitions matching the prefix.
|
||||
Defs(prefix string) []*ConfigDef
|
||||
|
||||
// Dump returns all config values.
|
||||
Dump() map[string]interface{}
|
||||
|
||||
// Plugins returns a list of all plugin config namespaces.
|
||||
Plugins() []string
|
||||
}
|
||||
|
||||
// ConfigDef describes a configuration field for the WebUI.
|
||||
type ConfigDef struct {
|
||||
Key string `json:"key"`
|
||||
Default interface{} `json:"default,omitempty"`
|
||||
Type string `json:"type"`
|
||||
DisplayName string `json:"display_name"`
|
||||
Description string `json:"description,omitempty"`
|
||||
Category string `json:"category,omitempty"`
|
||||
Options []string `json:"options,omitempty"`
|
||||
Min float64 `json:"min,omitempty"`
|
||||
Max float64 `json:"max,omitempty"`
|
||||
Step float64 `json:"step,omitempty"`
|
||||
Required bool `json:"required,omitempty"`
|
||||
Secret bool `json:"secret,omitempty"`
|
||||
}
|
||||
Reference in New Issue
Block a user