From f93b5eccb6027aa3ede5ab1c3fa4b96aaccaf1a1 Mon Sep 17 00:00:00 2001 From: root Date: Thu, 16 Jul 2026 18:54:20 +0800 Subject: [PATCH] docs: update for v0.7.1 - output channels, restricted API, LLM chain event --- README.md | 2 +- README_EN.md | 2 +- docs/en/ARCHITECTURE.md | 49 +++++++++++++++++++++++++++++++++++++++-- docs/zh/ARCHITECTURE.md | 49 +++++++++++++++++++++++++++++++++++++++-- 4 files changed, 96 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 3b189f1..17035f2 100644 --- a/README.md +++ b/README.md @@ -164,7 +164,7 @@ internal/ ## 项目状态 -核心可用，插件系统和 SDK 已就绪。内置 10 个插件，外部插件开发见 [homeagent-sdk](https://gitcode.com/JianFeeeee/homeagent-sdk) 仓库，使用 `plugindev` 工具链。 +**v0.7.1** — 核心可用，插件系统和 SDK 已就绪。内置 10 个插件，外部插件开发见 [homeagent-sdk](https://gitcode.com/JianFeeeee/homeagent-sdk) 仓库，使用 `plugindev` 工具链。输出通道系统、受限外部插件 API、EventAgentLLMChain 事件已上线。 ## 文档 diff --git a/README_EN.md b/README_EN.md index 3a7aabc..5770a08 100644 --- a/README_EN.md +++ b/README_EN.md @@ -164,7 +164,7 @@ External plugin development: see [homeagent-sdk](https://gitcode.com/JianFeeeee/ ## Project Status -Core is functional, plugin system and SDK are ready. 10 built-in plugins. External plugin development via [homeagent-sdk](https://gitcode.com/JianFeeeee/homeagent-sdk) repo using `plugindev` toolchain. +**v0.7.1** — Core is functional, plugin system and SDK are ready. 10 built-in plugins. External plugin development via [homeagent-sdk](https://gitcode.com/JianFeeeee/homeagent-sdk) repo using `plugindev` toolchain. Output channel system, restricted external plugin API, and EventAgentLLMChain event are live. ## Documentation diff --git a/docs/en/ARCHITECTURE.md b/docs/en/ARCHITECTURE.md index df2885b..2745069 100644 --- a/docs/en/ARCHITECTURE.md +++ b/docs/en/ARCHITECTURE.md @@ -143,7 +143,7 @@ TF-IDF is the core algorithm running through all three memory layers, used in 4 ### Graph Layer `internal/memory/graph.go` — `GraphDB` -- SQLite WAL mode, two tables +- SQLite WAL mode, two tables (driver: mattn/go-sqlite3, CGo) - `Commit(triples)` — UPSERT entities + INSERT relations - `Recall(keywords, depth)` — Keyword LIKE search + BFS traversal @@ -233,7 +233,7 @@ Built-in plugin registration: `internal/plugins/all.go` blank imports → each p External plugin loading: `internal/plugin/dynamic.go` → copy to SHA256 temp path (bypass `plugin.Open` path cache) → `Open` + `Lookup("NewPlugin")`. Lua script plugin loading: `internal/lua/` → parse `main.lua` via Lua VM, call `start()` to register tools. -### PluginSDK Three Channels +### PluginSDK Four Channels ``` Plugin ──→ Kernel @@ -241,6 +241,7 @@ Plugin ──→ Kernel RegisterTool(name, fn) ──→ buildToolDefs() / executeToolCall() RegisterStage(stage, fn) ──→ runStage() called at corresponding phase Subscribe(event, fn) ──→ Publish() notify all subscribers +RegisterOutputChannel(name, caps, desc, handler) ──→ output_send__{name} tool generation ``` `internal/sdk/` bridges external SDK interface to kernel, defines complete PluginSDK: @@ -254,6 +255,7 @@ sdk.InjectInterrupt(source, channel, payload) sdk.Memory().Recall/Commit sdk.Knowledge().Search/Create sdk.Settings().Get/Set/List +sdk.RegisterOutputChannel("qq", sdk.CapText, "QQ消息通道，content为JSON: {text, group_id, user_id}", handler) ``` ### Plugin Interface @@ -266,6 +268,48 @@ type Plugin interface { } ``` +## Output Channel System + +Each output channel generates two tools: + +| Tool | Type | Purpose | +|------|------|---------| +| `output_send__{name}` | function | Accepts a `content` JSON string parameter, transparently routed to the plugin's registered handler | +| `output_send__{name}_help` | function | Returns the channel's JSON format documentation (desc field) | + +Capability flags: + +| Flag | Value | Meaning | +|------|-------|---------| +| CapText | 1 | Plain text | +| CapFile | 2 | File | +| CapImage | 4 | Image | +| CapAudio | 8 | Audio | +| CapStructured | 16 | Structured data | + +System prompt injection: output gate rules, multi-call support, long message splitting. +Child agent permission: `output_send__` prefix tools are allowed. + +## EventAgentLLMChain Event + +- Event type `agent_llm_chain` emitted after each LLM turn +- Contains the full LLM response (text + tool calls + reasoning) +- WebUI subscribes to this event via SSE for real-time display +- Plugins can subscribe via EventSubscriber (read-only for external plugins) + +## Restricted External Plugin API + +Layered architecture: internal plugins get full PluginSDK, external plugins get restricted SDK. + +| API | Internal Plugin | External Plugin | +|-----|-----------------|-----------------| +| SocialAPI | Full read/write | Read-only (GetPerson / GetTrait / GetRelations / GetNetwork / ListPersons) | +| EventSubscriber | Subscribe + Publish | Subscribe-only (no Publish capability) | + +Extended fields: +- Triple extensions: Confidence, SubjectType, ObjectType +- Relation extension: Confidence + ## Interrupt Mechanism ``` @@ -303,6 +347,7 @@ cmd/waiter/main.go — CLI client (Unix socket) internal/ ├── agent/ │ ├── core/ — Agent core (eventLoop/process/stages/context) +│ │ └── plugin_health.go — Plugin health monitoring and auto-restart │ ├── api/ — Provider interface + LuaAdaptedProvider │ ├── io/ — IOManager (queue/interrupt/output) │ └── personal.go — Persona loading diff --git a/docs/zh/ARCHITECTURE.md b/docs/zh/ARCHITECTURE.md index 50df7fa..d7f7147 100644 --- a/docs/zh/ARCHITECTURE.md +++ b/docs/zh/ARCHITECTURE.md @@ -143,7 +143,7 @@ TF-IDF 是贯穿三层记忆的核心算法，在 4 个独立位置以不同方 ### Graph 层 `internal/memory/graph.go` — `GraphDB` -- SQLite WAL 模式，两张表 +- SQLite WAL 模式，两张表（驱动：mattn/go-sqlite3，CGo） - `Commit(triples)` — UPSERT entities + INSERT relations - `Recall(keywords, depth)` — 关键词 LIKE 搜索 + BFS 遍历 @@ -233,7 +233,7 @@ VM 内置 `json.encode` / `json.decode` / `log` / `http_get` / `http_post`。 外部插件加载：`internal/plugin/dynamic.go` → 复制到 SHA256 临时路径（绕过 `plugin.Open` 路径缓存）→ `Open` + `Lookup("NewPlugin")`。 Lua 脚本插件加载：`internal/lua/` → 通过 Lua VM 解析 `main.lua`，调用 `start()` 注册工具。 -### PluginSDK 三通道 +### PluginSDK 四通道 ``` 插件 ──→ 核心 @@ -241,6 +241,7 @@ Lua 脚本插件加载：`internal/lua/` → 通过 Lua VM 解析 `main.lua`， RegisterTool(name, fn) ──→ buildToolDefs() / executeToolCall() RegisterStage(stage, fn) ──→ runStage() 在对应阶段调用 Subscribe(event, fn) ──→ Publish() 通知所有订阅者 +RegisterOutputChannel(name, caps, desc, handler) ──→ output_send__{name} 工具生成 ``` `internal/sdk/` 桥接外部 SDK 接口到内核，定义完整 PluginSDK： @@ -254,6 +255,7 @@ sdk.InjectInterrupt(source, channel, payload) sdk.Memory().Recall/Commit sdk.Knowledge().Search/Create sdk.Settings().Get/Set/List +sdk.RegisterOutputChannel("qq", sdk.CapText, "QQ消息通道，content为JSON: {text, group_id, user_id}", handler) ``` ### Plugin 接口 @@ -266,6 +268,48 @@ type Plugin interface { } ``` +## 输出通道系统 + +每个输出通道生成两个工具： + +| 工具 | 类型 | 作用 | +|------|------|------| +| `output_send__{name}` | function | 接受 `content` JSON 字符串参数，透明路由到插件注册的 handler | +| `output_send__{name}_help` | function | 返回通道的 JSON 格式文档（desc 字段） | + +能力标志位： + +| 标志 | 值 | 含义 | +|------|-----|------| +| CapText | 1 | 纯文本 | +| CapFile | 2 | 文件 | +| CapImage | 4 | 图片 | +| CapAudio | 8 | 音频 | +| CapStructured | 16 | 结构化数据 | + +系统提示注入：输出门控规则、多调用支持、长消息拆分。 +子代理权限：`output_send__` 前缀工具允许使用。 + +## LLM 链事件 + +- 事件类型 `agent_llm_chain`，每次 LLM 轮次后发射 +- 包含完整 LLM 响应（文本 + 工具调用 + 推理） +- WebUI 通过 SSE 订阅此事件实现实时显示 +- 插件可通过 EventSubscriber 订阅（外部插件只读） + +## 受限外部插件 API + +分层架构：内部插件获得完整 PluginSDK，外部插件获得受限 SDK。 + +| API | 内部插件 | 外部插件 | +|-----|----------|----------| +| SocialAPI | 完整读写 | 只读（GetPerson / GetTrait / GetRelations / GetNetwork / ListPersons） | +| EventSubscriber | 订阅 + 发布 | 仅订阅（无 Publish 能力） | + +扩展字段： +- Triple 扩展：Confidence、SubjectType、ObjectType +- Relation 扩展：Confidence + ## 中断机制 ``` @@ -303,6 +347,7 @@ cmd/waiter/main.go — CLI 客户端 (Unix socket) internal/ ├── agent/ │ ├── core/ — Agent 核心 (eventLoop/process/stages/context) +│ │ └── plugin_health.go — 插件健康监控与自动重启 │ ├── api/ — Provider 接口 + LuaAdaptedProvider │ ├── io/ — IOManager (排队/中断/输出) │ └── personal.go — 人格加载