jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-09-21 09:28:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: 修正全部文档使其与源码实现一致

Browse Source 
主仓库：
- 修复 4 份英文文档语言切换链接指向错误 (../zh/ → ../en/)
- ARCHITECTURE.md 标题 "三种加载方式" → "四种加载方式" (实际表格4行)
- PLUGIN_DEV.md 示例表: 添加 webfetch, 移除不存在的 luaplugintest/testlua
- PLUGIN_DEV.md 代码示例: InjectInput/InjectInterrupt → InjectText/InjectInterruptText
- PLUGIN_DEV.md 代码示例: Memory/Knowledge/LLM/Events 接口签名修正
- PLUGIN_DEV.md .hmap 内容统一, plugindev 编译去除 .exe 后缀

SDK 仓库:
- Plugin.Start(sdk *PluginSDK) 接口签名改为指针
- 方法表重写: 移除 CallLLM/QueryKnowledge/SetMemory 等不存在方法
- IOInjector 参数顺序修正为 (source, channel, text)
- 删除虚构 SDKConfig, 替换为实际 New() 构造函数签名
- .hmap 内容描述一致化

修正前一次会话中的 QQ/Bili 插件问题:
- qq napcat() 超时, fetchBotInfo 竞态, handleWebhook 同步阻塞
- bili CDN 直连失败, 添加 HTTP_PROXY 代理
This commit is contained in:
root
2026-07-18 20:46:58 +08:00
parent 2cc600121c
commit c9e67d3d55
14 changed files with 125 additions and 145 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/en/ADAPTER.md
View File

@ -1,4 +1,4 @@
**中文** | [English](../zh/ADAPTER.md)
**中文** | [English](../en/ADAPTER.md)
# Lua Adapter — LLM Source Adaptation Guide

4
docs/en/ARCHITECTURE.md
View File

@ -1,4 +1,4 @@
**中文** | [English](../zh/ARCHITECTURE.md)
**中文** | [English](../en/ARCHITECTURE.md)
# HomeAgent Architecture
@ -249,7 +249,7 @@ VM built-ins: `json.encode` / `json.decode` / `log` / `http_get` / `http_post`.
## Plugin System
### Three Loading Methods
### Four Loading Methods
| Method | Registration Mechanism | Compilation | Usage |
|--------|----------------------|-------------|-------|

2
docs/en/OVERVIEW.md
View File

@ -1,4 +1,4 @@
**中文** | [English](../zh/OVERVIEW.md)
**中文** | [English](../en/OVERVIEW.md)
# HomeAgent — Project Overview

40
docs/en/PLUGIN_DEV.md
View File

@ -1,4 +1,4 @@
**中文** | [English](../zh/PLUGIN_DEV.md)
**中文** | [English](../en/PLUGIN_DEV.md)
# HomeAgent Plugin Development Guide
@ -45,8 +45,8 @@ type Plugin interface {
```bash
cd homeagent-sdk/tools/plugindev
go build -o plugindev.exe
# Add plugindev.exe to PATH or use directly
go build -o plugindev
# Add plugindev to PATH or use directly
```
### Creating a Go Plugin
@ -112,7 +112,7 @@ Execution process:
2. **Go plugin**: Runs `go build -buildmode=c-shared` (produces `.so` + C ABI header)
3. **Lua plugin**: Packages source code directly, no compilation needed
4. Generates `plugin.json` manifest file
5. Packages as `.hmap` distribution (zip format, containing `plugin.json` + `plugin.so`/`plugin.dll`/`main.lua`)
5. Packages as `.hmap` distribution (zip format, containing `plugin.json` + `plugin.so` + `plugin.dll` + `main.lua`)
Output in `dist/` directory:
```
@ -274,21 +274,22 @@ s.Settings().GetPlugin("other_plugin", "some_key")
#### Input Delivery
```go
// Queued delivery (processed in order)
s.InjectInput(source, channel, eventType string, payload map[string]interface{})
// Normal delivery (processed in order)
s.InjectText(source, channel, text string)
// Interrupt delivery (can interrupt current LLM processing)
s.InjectInterrupt(source, channel, eventType string, payload map[string]interface{})
// Shortcuts
s.InjectText(source, channel, text string)
s.InjectInterruptText(source, channel, text string)
// No memory recording
s.InjectTextNoMemory(source, channel, text string)
```
#### Event Subscription
```go
unsub := s.Subscribe("tool_call", func(evt *events.Event) {
import "gitcode.com/JianFeeeee/homeagent-sdk/sdk"
unsub := s.Events().Subscribe(sdk.EventToolCall, func(evt *sdk.Event) {
log.Printf("Tool was called: %v", evt.Payload)
})
defer unsub()
@ -297,16 +298,18 @@ defer unsub()
#### Capability Access
```go
// Memory
s.Memory().Recall(query string) ([]MemItem, error)
s.Memory().Commit(triples []Triple) error
// Graph Memory (entity-relation store)
entities, relations, err := s.Memory().Recall([]string{"keyword"}, 2)
// Document Memory (vector store)
docs := s.DocMemory().Query("query text", 3)
// Knowledge
s.Knowledge().Search(query string) ([]string, error)
results, err := s.Knowledge().Search("query", 5)
// LLM source management
s.LLM().ListSources() []SourceInfo
s.LLM().SetSource(name string) error
s.LLM().ListSources() // returns []string
s.LLM().SetSource("deepseek")
```
#### Event Subscription (built-in plugins)
@ -512,14 +515,13 @@ import (
| [memo](https://gitcode.com/JianFeeeee/homeagent-sdk/tree/main/example/memo) | Go | Memo management, PreAction injection + timed interrupt dual reminder |
| [files](https://gitcode.com/JianFeeeee/homeagent-sdk/tree/main/example/files) | Go | File system operations, 4 write modes, sandbox isolation |
| [web](https://gitcode.com/JianFeeeee/homeagent-sdk/tree/main/example/web) | Go | DuckDuckGo search + web scraping, SSRF protection |
| [webfetch](https://gitcode.com/JianFeeeee/homeagent-sdk/tree/main/example/webfetch) | Go | Web content fetching |
| [qq](https://gitcode.com/JianFeeeee/homeagent-sdk/tree/main/example/qq) | Go | NapCat OneBot integration, 17 tools |
| [bili](https://gitcode.com/JianFeeeee/homeagent-sdk/tree/main/example/bili) | Go | Bilibili video download (you-get) |
| [editdoc](https://gitcode.com/JianFeeeee/homeagent-sdk/tree/main/example/editdoc) | Go | Office document editing and format conversion |
| [a2a](https://gitcode.com/JianFeeeee/homeagent-sdk/tree/main/example/a2a) | Go | Agent-to-Agent protocol |
| [ocr](https://gitcode.com/JianFeeeee/homeagent-sdk/tree/main/example/ocr) | Go | Offline text recognition (Tesseract) |
| [sanitizer](https://gitcode.com/JianFeeeee/homeagent-sdk/tree/main/example/sanitizer) | Go | Output sanitizer filter |
| [luaplugintest](https://gitcode.com/JianFeeeee/homeagent-sdk/tree/main/example/luaplugintest) | Lua | Lua plugin Hello World |
| [testlua](https://gitcode.com/JianFeeeee/homeagent-sdk/tree/main/example/testlua) | Lua | Lua plugin example |
### Built-in Plugins

2
docs/zh/ARCHITECTURE.md
View File

@ -249,7 +249,7 @@ VM 内置 `json.encode` / `json.decode` / `log` / `http_get` / `http_post`。
## 插件系统
### 三种加载方式
### 四种加载方式
| 方式 | 注册机制 | 编译 | 用途 |
|------|----------|------|------|

40
docs/zh/PLUGIN_DEV.md
View File

@ -46,8 +46,8 @@ type Plugin interface {
```bash
cd homeagent-sdk/tools/plugindev
go build -o plugindev.exe
# 将 plugindev.exe 加入 PATH 或直接使用
go build -o plugindev
# 将 plugindev 加入 PATH 或直接使用
```
### 创建 Go 插件
@ -113,7 +113,7 @@ plugindev build
2. **Go 插件**：执行 `go build -buildmode=c-shared`（生成 `.so` + C ABI header）
3. **Lua 插件**：直接打包源码，无需编译
4. 生成 `plugin.json` 清单文件
5. 打包为 `.hmap` 分发包（zip 格式，内含 `plugin.json` + `plugin.so` + `plugin.h` + `main.lua`）
5. 打包为 `.hmap` 分发包（zip 格式，内含 `plugin.json` + `plugin.so` + `plugin.dll` + `main.lua`）
输出在 `dist/` 目录：
```
@ -275,21 +275,22 @@ s.Settings().GetPlugin("other_plugin", "some_key")
#### 输入投递
```go
// 排队投递（按序处理）
s.InjectInput(source, channel, eventType string, payload map[string]interface{})
// 普通投递（按序处理）
s.InjectText(source, channel, text string)
// 中断投递（可打断当前 LLM 处理）
s.InjectInterrupt(source, channel, eventType string, payload map[string]interface{})
// 快捷方式
s.InjectText(source, channel, text string)
s.InjectInterruptText(source, channel, text string)
// 不记入记忆
s.InjectTextNoMemory(source, channel, text string)
```
#### 事件订阅
```go
unsub := s.Subscribe("tool_call", func(evt *events.Event) {
import "gitcode.com/JianFeeeee/homeagent-sdk/sdk"
unsub := s.Events().Subscribe(sdk.EventToolCall, func(evt *sdk.Event) {
log.Printf("工具被调用: %v", evt.Payload)
})
defer unsub()
@ -298,16 +299,18 @@ defer unsub()
#### 能力访问
```go
// 记忆
s.Memory().Recall(query string) ([]MemItem, error)
s.Memory().Commit(triples []Triple) error
// 图记忆（实体-关系存储）
entities, relations, err := s.Memory().Recall([]string{"关键词"}, 2)
// 知识
s.Knowledge().Search(query string) ([]string, error)
// 文档记忆（向量存储）
docs := s.DocMemory().Query("查询文本", 3)
// 知识库
results, err := s.Knowledge().Search("查询", 5)
// LLM 源管理
s.LLM().ListSources() []SourceInfo
s.LLM().SetSource(name string) error
s.LLM().ListSources() // 返回 []string
s.LLM().SetSource("deepseek")
```
#### 事件订阅（内置插件）
@ -513,14 +516,13 @@ import (
| [memo](https://gitcode.com/JianFeeeee/homeagent-sdk/tree/main/example/memo) | Go | 备忘管理，PreAction 注入 + 定时打断双提醒 |
| [files](https://gitcode.com/JianFeeeee/homeagent-sdk/tree/main/example/files) | Go | 文件系统操作，4 种写入模式，沙箱隔离 |
| [web](https://gitcode.com/JianFeeeee/homeagent-sdk/tree/main/example/web) | Go | DuckDuckGo 搜索 + 网页抓取，SSRF 防护 |
| [webfetch](https://gitcode.com/JianFeeeee/homeagent-sdk/tree/main/example/webfetch) | Go | 网页内容抓取 |
| [qq](https://gitcode.com/JianFeeeee/homeagent-sdk/tree/main/example/qq) | Go | NapCat OneBot 对接，17 个工具 |
| [bili](https://gitcode.com/JianFeeeee/homeagent-sdk/tree/main/example/bili) | Go | B 站视频下载（you-get） |
| [editdoc](https://gitcode.com/JianFeeeee/homeagent-sdk/tree/main/example/editdoc) | Go | Office 文档编辑与格式转换 |
| [a2a](https://gitcode.com/JianFeeeee/homeagent-sdk/tree/main/example/a2a) | Go | Agent-to-Agent 协议 |
| [ocr](https://gitcode.com/JianFeeeee/homeagent-sdk/tree/main/example/ocr) | Go | 离线文字识别（Tesseract） |
| [sanitizer](https://gitcode.com/JianFeeeee/homeagent-sdk/tree/main/example/sanitizer) | Go | 输出清洗过滤器 |
| [luaplugintest](https://gitcode.com/JianFeeeee/homeagent-sdk/tree/main/example/luaplugintest) | Lua | Lua 插件 Hello World |
| [testlua](https://gitcode.com/JianFeeeee/homeagent-sdk/tree/main/example/testlua) | Lua | Lua 插件示例 |
### 内置插件