docs: update for v0.7.1 - output channels, restricted API, LLM chain event

2026-09-21 09:28:14 +00:00 · 2026-07-16 18:54:20 +08:00
parent f3b1cef2c1
commit f93b5eccb6
4 changed files with 96 additions and 6 deletions
--- 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 事件已上线。

 ## 文档

--- 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

--- 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
--- 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        — 人格加载