docs: mascot before each section heading in tutorial docs

This commit is contained in:
JianFeeeee
2026-07-17 21:44:15 +08:00
parent 66b86f6369
commit 67353ec7f7
8 changed files with 108 additions and 16 deletions

View File

@ -1,11 +1,11 @@
**中文** | [English](../zh/ADAPTER.md) **中文** | [English](../zh/ADAPTER.md)
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
# Lua Adapter — LLM Source Adaptation Guide # Lua Adapter — LLM Source Adaptation Guide
Each LLM API source corresponds to a Lua script, responsible for request transformation (Go unified format → API format) and response transformation (API format → Go unified format). Each LLM API source corresponds to a Lua script, responsible for request transformation (Go unified format → API format) and response transformation (API format → Go unified format).
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Adapter Contract ## Adapter Contract
The Lua script must return a table containing the following fields and functions: The Lua script must return a table containing the following fields and functions:
@ -45,6 +45,8 @@ end
return adapter return adapter
``` ```
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Unified CompletionRequest Format (Go → Adapter) ## Unified CompletionRequest Format (Go → Adapter)
```json ```json
@ -63,6 +65,8 @@ return adapter
} }
``` ```
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Unified CompletionResponse Format (Adapter → Go) ## Unified CompletionResponse Format (Adapter → Go)
```json ```json
@ -76,6 +80,8 @@ return adapter
} }
``` ```
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Lua VM Built-in Functions ## Lua VM Built-in Functions
`json.encode(table)` — Encode Lua table to JSON string `json.encode(table)` — Encode Lua table to JSON string
@ -88,6 +94,8 @@ return adapter
`http_post(url, body)` — Perform HTTP POST request, returns response body as string `http_post(url, body)` — Perform HTTP POST request, returns response body as string
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Adapting Typical APIs ## Adapting Typical APIs
| API | endpoint | auth method | Format differences | | API | endpoint | auth method | Format differences |
@ -101,6 +109,8 @@ return adapter
| **GitHub Models** | `/chat/completions` | `Authorization: Bearer <pat>` | OpenAI compatible | | **GitHub Models** | `/chat/completions` | `Authorization: Bearer <pat>` | OpenAI compatible |
| **Ollama** | `/api/chat` | None | Different options format | | **Ollama** | `/api/chat` | None | Different options format |
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Steps to Add a New Source ## Steps to Add a New Source
1. Create `<name>.lua` under `internal/lua/adapters/` 1. Create `<name>.lua` under `internal/lua/adapters/`

View File

@ -1,11 +1,11 @@
**中文** | [English](../zh/ARCHITECTURE.md) **中文** | [English](../zh/ARCHITECTURE.md)
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
# HomeAgent Architecture # HomeAgent Architecture
The kernel performs zero IO; all external interaction comes from plugins. The kernel performs zero IO; all external interaction comes from plugins.
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Message Processing Flow ## Message Processing Flow
### Full Pipeline ### Full Pipeline
@ -66,6 +66,8 @@ Exit conditions: LLM has no tool calls / all rejected / exceeded limit.
Setting `ctx.Response` at any stage jumps to `after_output`. Setting `ctx.Response` at any stage jumps to `after_output`.
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Three-Layer Memory ## Three-Layer Memory
### Memory Flow ### Memory Flow
@ -203,6 +205,8 @@ Heartbeat 30min:
Entity conflict detection heuristic (bigram Jaccard > 0.75), routed through `selfInputCh` internal channel, LLM makes the final merge decision. Entity conflict detection heuristic (bigram Jaccard > 0.75), routed through `selfInputCh` internal channel, LLM makes the final merge decision.
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Knowledge Base ## Knowledge Base
`internal/knowledge/knowledge.go` `internal/knowledge/knowledge.go`
@ -210,6 +214,8 @@ Entity conflict detection heuristic (bigram Jaccard > 0.75), routed through `sel
- Independent TF-IDF index, separate from memory system - Independent TF-IDF index, separate from memory system
- `knowledge_search` / `knowledge_create` / `knowledge_list` - `knowledge_search` / `knowledge_create` / `knowledge_list`
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Provider & Lua Adapter Layer ## Provider & Lua Adapter Layer
``` ```
@ -234,6 +240,8 @@ ProviderManager manages multiple sources, fallback in registration order. Lua ad
VM built-ins: `json.encode` / `json.decode` / `log` / `http_get` / `http_post`. VM built-ins: `json.encode` / `json.decode` / `log` / `http_get` / `http_post`.
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Plugin System ## Plugin System
### Three Loading Methods ### Three Loading Methods
@ -284,6 +292,8 @@ type Plugin interface {
} }
``` ```
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Output Channel System ## Output Channel System
Each output channel generates two tools: Each output channel generates two tools:
@ -306,6 +316,8 @@ Capability flags:
System prompt injection: output gate rules, multi-call support, long message splitting. System prompt injection: output gate rules, multi-call support, long message splitting.
Child agent permission: `output_send__` prefix tools are allowed. Child agent permission: `output_send__` prefix tools are allowed.
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## EventAgentLLMChain Event ## EventAgentLLMChain Event
- Event type `agent_llm_chain` emitted after each LLM turn - Event type `agent_llm_chain` emitted after each LLM turn
@ -313,6 +325,8 @@ Child agent permission: `output_send__` prefix tools are allowed.
- WebUI subscribes to this event via SSE for real-time display - WebUI subscribes to this event via SSE for real-time display
- Plugins can subscribe via EventSubscriber (read-only for external plugins) - Plugins can subscribe via EventSubscriber (read-only for external plugins)
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Restricted External Plugin API ## Restricted External Plugin API
Layered architecture: internal plugins get full PluginSDK, external plugins get restricted SDK. Layered architecture: internal plugins get full PluginSDK, external plugins get restricted SDK.
@ -326,6 +340,8 @@ Extended fields:
- Triple extensions: Confidence, SubjectType, ObjectType - Triple extensions: Confidence, SubjectType, ObjectType
- Relation extension: Confidence - Relation extension: Confidence
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Interrupt Mechanism ## Interrupt Mechanism
``` ```
@ -346,6 +362,8 @@ Three delivery paths:
Code: `internal/agent/core/agent.go` — `interceptLoop` / `drainInterrupt` Code: `internal/agent/core/agent.go` — `interceptLoop` / `drainInterrupt`
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Configuration System ## Configuration System
`internal/config/registry.go` — ConfigRegistry `internal/config/registry.go` — ConfigRegistry
@ -355,6 +373,8 @@ Code: `internal/agent/core/agent.go` — `interceptLoop` / `drainInterrupt`
- `RegisterDefault` inserts ~80 default keys (seeds for 8 LLM sources) - `RegisterDefault` inserts ~80 default keys (seeds for 8 LLM sources)
- WebUI settings page `/api/v1/settings` for read/write - WebUI settings page `/api/v1/settings` for read/write
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Code Structure ## Code Structure
``` ```

View File

@ -1,9 +1,9 @@
**中文** | [English](../zh/OVERVIEW.md) **中文** | [English](../zh/OVERVIEW.md)
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
# HomeAgent — Project Overview # HomeAgent — Project Overview
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## What Is This ## What Is This
HomeAgent is a continuously-running personal intelligent Agent framework. HomeAgent is a continuously-running personal intelligent Agent framework.
@ -27,6 +27,8 @@ The significance: the kernel stays pure (zero IO, only orchestration and memory)
Three progressive layers: context → cold archive → long-term graph memory, ensuring the agent doesn't degrade over time. Three progressive layers: context → cold archive → long-term graph memory, ensuring the agent doesn't degrade over time.
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## What It Actually Does ## What It Actually Does
Code is in the project root, implemented in Go. Code is in the project root, implemented in Go.
@ -67,6 +69,8 @@ Code is in the project root, implemented in Go.
- OpenAI API-compatible `/v1/chat/completions` endpoint - OpenAI API-compatible `/v1/chat/completions` endpoint
- SSE event stream `/api/v1/chat/events` - SSE event stream `/api/v1/chat/events`
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Project Status ## Project Status
Core functionality is operational. Plugin system and SDK are ready for independent external plugin development. Core functionality is operational. Plugin system and SDK are ready for independent external plugin development.

View File

@ -1,9 +1,9 @@
**中文** | [English](../zh/PLUGIN_DEV.md) **中文** | [English](../zh/PLUGIN_DEV.md)
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
# HomeAgent Plugin Development Guide # HomeAgent Plugin Development Guide
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Overview ## Overview
All external interaction capabilities of HomeAgent comes from plugins. Plugins interact with the kernel through `PluginSDK` (Go API). All external interaction capabilities of HomeAgent comes from plugins. Plugins interact with the kernel through `PluginSDK` (Go API).
@ -35,6 +35,8 @@ type Plugin interface {
--- ---
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 1. Quick Start: Using the plugindev Toolchain ## 1. Quick Start: Using the plugindev Toolchain
`plugindev` is the unified plugin development toolchain provided in the SDK repository, supporting both Go and Lua plugin types. `plugindev` is the unified plugin development toolchain provided in the SDK repository, supporting both Go and Lua plugin types.
@ -134,6 +136,8 @@ Or upload via WebUI plugin management page.
--- ---
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 2. Go Plugin Development in Detail ## 2. Go Plugin Development in Detail
### Plugin Interface ### Plugin Interface
@ -346,6 +350,8 @@ channels := s.ListChannels()
--- ---
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 3. Lua Plugin Development in Detail ## 3. Lua Plugin Development in Detail
Lua plugins are suitable for lightweight rapid prototyping, requiring no Go compilation environment. Changes take effect after kernel restart. Lua plugins are suitable for lightweight rapid prototyping, requiring no Go compilation environment. Changes take effect after kernel restart.
@ -416,6 +422,8 @@ When running inside the kernel, `sdk.*` global variables are injected by the Go
--- ---
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 4. Built-in Plugins ## 4. Built-in Plugins
Built-in plugins use `init()` self-registration, compiled into the kernel, no separate deployment needed. Built-in plugins use `init()` self-registration, compiled into the kernel, no separate deployment needed.
@ -479,6 +487,8 @@ import (
--- ---
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 5. Best Practices ## 5. Best Practices
1. `Start()` is non-blocking — start long tasks in goroutines, don't block Start 1. `Start()` is non-blocking — start long tasks in goroutines, don't block Start
@ -491,6 +501,8 @@ import (
--- ---
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 6. Example Plugin Reference ## 6. Example Plugin Reference
### SDK Repository Examples (`homeagent-sdk/example/`) ### SDK Repository Examples (`homeagent-sdk/example/`)

View File

@ -1,11 +1,11 @@
[English](../en/ADAPTER.md) | **中文** [English](../en/ADAPTER.md) | **中文**
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
# Lua Adapter — LLM 源适配指南 # Lua Adapter — LLM 源适配指南
每个 LLM API 源对应一个 Lua 脚本,负责请求转换(Go 统一格式 → API 格式)和响应转换(API 格式 → Go 统一格式)。 每个 LLM API 源对应一个 Lua 脚本,负责请求转换(Go 统一格式 → API 格式)和响应转换(API 格式 → Go 统一格式)。
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 适配器契约 ## 适配器契约
Lua 脚本必须返回一个包含以下字段和函数的 table: Lua 脚本必须返回一个包含以下字段和函数的 table:
@ -45,6 +45,8 @@ end
return adapter return adapter
``` ```
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 统一 CompletionRequest 格式(Go → Adapter) ## 统一 CompletionRequest 格式(Go → Adapter)
```json ```json
@ -63,6 +65,8 @@ return adapter
} }
``` ```
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 统一 CompletionResponse 格式(Adapter → Go) ## 统一 CompletionResponse 格式(Adapter → Go)
```json ```json
@ -76,6 +80,8 @@ return adapter
} }
``` ```
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Lua VM 内置函数 ## Lua VM 内置函数
`json.encode(table)` — 将 Lua table 编码为 JSON 字符串 `json.encode(table)` — 将 Lua table 编码为 JSON 字符串
@ -88,6 +94,8 @@ return adapter
`http_post(url, body)` — 发起 HTTP POST 请求,返回响应体字符串 `http_post(url, body)` — 发起 HTTP POST 请求,返回响应体字符串
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 适配典型 API ## 适配典型 API
| API | endpoint | auth 方式 | 格式差异 | | API | endpoint | auth 方式 | 格式差异 |
@ -101,6 +109,8 @@ return adapter
| **GitHub Models** | `/chat/completions` | `Authorization: Bearer <pat>` | OpenAI 兼容 | | **GitHub Models** | `/chat/completions` | `Authorization: Bearer <pat>` | OpenAI 兼容 |
| **Ollama** | `/api/chat` | 无 | 不同的 options 格式 | | **Ollama** | `/api/chat` | 无 | 不同的 options 格式 |
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 添加新源步骤 ## 添加新源步骤
1. 在 `internal/lua/adapters/` 下创建 `<name>.lua` 1. 在 `internal/lua/adapters/` 下创建 `<name>.lua`

View File

@ -1,11 +1,11 @@
[English](../en/ARCHITECTURE.md) | **中文** [English](../en/ARCHITECTURE.md) | **中文**
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
# HomeAgent 架构 # HomeAgent 架构
内核零 IO,一切外界交互来自插件。 内核零 IO,一切外界交互来自插件。
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 消息处理流程 ## 消息处理流程
### 完整链路 ### 完整链路
@ -66,6 +66,8 @@ eventLoop() → processTextInput()
任意阶段设 `ctx.Response` 即跳到 `after_output`。 任意阶段设 `ctx.Response` 即跳到 `after_output`。
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 三层记忆 ## 三层记忆
### 记忆流转 ### 记忆流转
@ -203,6 +205,8 @@ eventLoop() → processTextInput()
实体冲突检测启发式(bigram Jaccard > 0.75),走 `selfInputCh` 内部通道,LLM 最终判断是否合并。 实体冲突检测启发式(bigram Jaccard > 0.75),走 `selfInputCh` 内部通道,LLM 最终判断是否合并。
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 知识库 ## 知识库
`internal/knowledge/knowledge.go` `internal/knowledge/knowledge.go`
@ -210,6 +214,8 @@ eventLoop() → processTextInput()
- 独立 TF-IDF 索引,与记忆系统不冲突 - 独立 TF-IDF 索引,与记忆系统不冲突
- `knowledge_search` / `knowledge_create` / `knowledge_list` - `knowledge_search` / `knowledge_create` / `knowledge_list`
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## Provider 与 Lua 适配层 ## Provider 与 Lua 适配层
``` ```
@ -234,6 +240,8 @@ ProviderManager 管理多个源,按注册顺序 fallback。Lua 适配器位于
VM 内置 `json.encode` / `json.decode` / `log` / `http_get` / `http_post`。 VM 内置 `json.encode` / `json.decode` / `log` / `http_get` / `http_post`。
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 插件系统 ## 插件系统
### 三种加载方式 ### 三种加载方式
@ -284,6 +292,8 @@ type Plugin interface {
} }
``` ```
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 输出通道系统 ## 输出通道系统
每个输出通道生成两个工具: 每个输出通道生成两个工具:
@ -306,6 +316,8 @@ type Plugin interface {
系统提示注入:输出门控规则、多调用支持、长消息拆分。 系统提示注入:输出门控规则、多调用支持、长消息拆分。
子代理权限:`output_send__` 前缀工具允许使用。 子代理权限:`output_send__` 前缀工具允许使用。
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## LLM 链事件 ## LLM 链事件
- 事件类型 `agent_llm_chain`,每次 LLM 轮次后发射 - 事件类型 `agent_llm_chain`,每次 LLM 轮次后发射
@ -313,6 +325,8 @@ type Plugin interface {
- WebUI 通过 SSE 订阅此事件实现实时显示 - WebUI 通过 SSE 订阅此事件实现实时显示
- 插件可通过 EventSubscriber 订阅(外部插件只读) - 插件可通过 EventSubscriber 订阅(外部插件只读)
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 受限外部插件 API ## 受限外部插件 API
分层架构:内部插件获得完整 PluginSDK,外部插件获得受限 SDK。 分层架构:内部插件获得完整 PluginSDK,外部插件获得受限 SDK。
@ -326,6 +340,8 @@ type Plugin interface {
- Triple 扩展:Confidence、SubjectType、ObjectType - Triple 扩展:Confidence、SubjectType、ObjectType
- Relation 扩展:Confidence - Relation 扩展:Confidence
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 中断机制 ## 中断机制
``` ```
@ -346,6 +362,8 @@ interceptLoop (goroutine)
代码:`internal/agent/core/agent.go` — `interceptLoop` / `drainInterrupt` 代码:`internal/agent/core/agent.go` — `interceptLoop` / `drainInterrupt`
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 配置系统 ## 配置系统
`internal/config/registry.go` — ConfigRegistry `internal/config/registry.go` — ConfigRegistry
@ -355,6 +373,8 @@ interceptLoop (goroutine)
- `RegisterDefault` 插入 ~80 个默认键(8 个 LLM 源的 seeds) - `RegisterDefault` 插入 ~80 个默认键(8 个 LLM 源的 seeds)
- WebUI 设置页 `/api/v1/settings` 读写 - WebUI 设置页 `/api/v1/settings` 读写
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 代码结构 ## 代码结构
``` ```

View File

@ -1,9 +1,9 @@
[English](../en/OVERVIEW.md) | **中文** [English](../en/OVERVIEW.md) | **中文**
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
# HomeAgent — 项目概览 # HomeAgent — 项目概览
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 这是什么 ## 这是什么
HomeAgent 是一个持续运行的个人智能 Agent 框架。 HomeAgent 是一个持续运行的个人智能 Agent 框架。
@ -27,6 +27,8 @@ HomeAgent 是一个持续运行的个人智能 Agent 框架。
三层递进:上下文 → 冷归档 → 长期图记忆,确保 Agent 长时间运行不退化。 三层递进:上下文 → 冷归档 → 长期图记忆,确保 Agent 长时间运行不退化。
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 它实际做了什么 ## 它实际做了什么
代码位于项目仓库根目录,Go 语言实现。 代码位于项目仓库根目录,Go 语言实现。
@ -67,6 +69,8 @@ HomeAgent 是一个持续运行的个人智能 Agent 框架。
- 兼容 OpenAI API 格式的 `/v1/chat/completions` 端点 - 兼容 OpenAI API 格式的 `/v1/chat/completions` 端点
- SSE 事件流 `/api/v1/chat/events` - SSE 事件流 `/api/v1/chat/events`
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 项目状态 ## 项目状态
核心功能已可运行。插件系统和 SDK 已就绪,可独立开发外部插件。 核心功能已可运行。插件系统和 SDK 已就绪,可独立开发外部插件。

View File

@ -1,9 +1,9 @@
[English](../en/PLUGIN_DEV.md) | **中文** [English](../en/PLUGIN_DEV.md) | **中文**
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
# HomeAgent 插件开发指南 # HomeAgent 插件开发指南
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 概述 ## 概述
HomeAgent 的所有外部交互能力都来自插件。插件通过 `PluginSDK`(Go API)与内核交互。 HomeAgent 的所有外部交互能力都来自插件。插件通过 `PluginSDK`(Go API)与内核交互。
@ -36,6 +36,8 @@ type Plugin interface {
--- ---
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 一、快速开始:使用 plugindev 工具链 ## 一、快速开始:使用 plugindev 工具链
`plugindev` 是 SDK 仓库提供的统一插件开发工具链,支持 Go 和 Lua 两种插件类型。 `plugindev` 是 SDK 仓库提供的统一插件开发工具链,支持 Go 和 Lua 两种插件类型。
@ -135,6 +137,8 @@ curl -X POST http://127.0.0.1:9876/plugins \
--- ---
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 二、Go 插件开发详解 ## 二、Go 插件开发详解
### 插件接口 ### 插件接口
@ -347,6 +351,8 @@ channels := s.ListChannels()
--- ---
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 三、Lua 插件开发详解 ## 三、Lua 插件开发详解
Lua 插件适合轻量级快速原型,无需 Go 编译环境,修改后直接重启内核即可生效。 Lua 插件适合轻量级快速原型,无需 Go 编译环境,修改后直接重启内核即可生效。
@ -417,6 +423,8 @@ lua main.lua
--- ---
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 四、内置插件 ## 四、内置插件
内置插件使用 `init()` 自注册方式,编译进内核,无需单独部署。 内置插件使用 `init()` 自注册方式,编译进内核,无需单独部署。
@ -480,6 +488,8 @@ import (
--- ---
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 五、最佳实践 ## 五、最佳实践
1. `Start()` 非阻塞 — goroutine 启动长任务,不要阻塞 Start 1. `Start()` 非阻塞 — goroutine 启动长任务,不要阻塞 Start
@ -492,6 +502,8 @@ import (
--- ---
<img src="../../branding/mascot-xiaozhai.webp" width="20" style="border-radius:50%;vertical-align:middle"> :
## 六、示例插件参考 ## 六、示例插件参考
### SDK 仓库示例(`homeagent-sdk/example/`) ### SDK 仓库示例(`homeagent-sdk/example/`)