From dd01388e76bf4eb6f0e4252be0811753c97ac40e Mon Sep 17 00:00:00 2001 From: root Date: Thu, 16 Jul 2026 23:17:55 +0800 Subject: [PATCH] docs: fix documentation-source mismatches across all doc files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Go version: 1.19+/1.21+ → 1.25+ (matches go.mod) - document/doc.go → document/document.go (actual filename) - PluginSDK: 3 channels → 4 channels (add RegisterOutputChannel) - InjectInput/InjectInterrupt: 3 params → 4 params (add eventType) - RegisterChannel: document agentIO.Device interface requirement - Architecture: remove non-existent snapshot/tokenizer dirs, add skill/meta - Architecture: fix double internal/internal/sdk, fix Jaccard threshold - Adapter: add http_get/http_post Lua VM built-ins - Knowledge: 4-layer → 3-layer memory, CGO for go-sqlite3 not overlayfs - Code structure tree: fix sdk/ and lua/adapters/ path consistency --- README.md | 6 +++--- README_EN.md | 6 +++--- docs/en/ADAPTER.md | 4 ++++ docs/en/ARCHITECTURE.md | 18 ++++++++++-------- docs/en/OVERVIEW.md | 4 ++-- docs/en/PLUGIN_DEV.md | 14 +++++++++++--- docs/zh/ADAPTER.md | 4 ++++ docs/zh/ARCHITECTURE.md | 18 ++++++++++-------- docs/zh/OVERVIEW.md | 4 ++-- docs/zh/PLUGIN_DEV.md | 14 +++++++++++--- knowledge/homeagent_architecture/content.md | 8 ++++---- 11 files changed, 64 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 17035f2..dce6973 100644 --- a/README.md +++ b/README.md @@ -155,10 +155,10 @@ internal/ ├── knowledge/ 知识库（文件系统 + TF-IDF） ├── plugin/ 插件注册表 + .so 动态加载器 ├── plugins/ 内置 10 个插件（webui/cli/timer/cmd/mcp/openclaw/agentcli/healthcheck/pluginmgr/files） -├── internal/sdk/ PluginSDK（Tool/Stage/Event 三通道） +├── sdk/ PluginSDK（Tool/Stage/Event 三通道） ├── config/ SQLite 配置中心 ├── events/ 事件总线 -└── lua/adapters/ 8 个 LLM 协议适配器脚本 +└── internal/lua/adapters/ 8 个 LLM 协议适配器脚本 外部插件开发见 [homeagent-sdk](https://gitcode.com/JianFeeeee/homeagent-sdk) 仓库，使用 `plugindev` 工具链开发，参考 `example/` 目录下的 Go 和 Lua 示例 ``` @@ -182,4 +182,4 @@ make test # go test ./... make install # 安装到系统 ``` -依赖：Go 1.21+, CGo (go-sqlite3), Linux/Windows。 \ No newline at end of file +依赖：Go 1.25+, CGo (go-sqlite3), Linux/Windows。 \ No newline at end of file diff --git a/README_EN.md b/README_EN.md index 5770a08..323ae6c 100644 --- a/README_EN.md +++ b/README_EN.md @@ -155,10 +155,10 @@ internal/ ├── knowledge/ Knowledge base (filesystem + TF-IDF) ├── plugin/ Plugin registry + .so/.dll dynamic loader ├── plugins/ 10 built-in plugins (webui/cli/timer/cmd/mcp/openclaw/agentcli/healthcheck/pluginmgr/files) -├── internal/sdk/ PluginSDK (Tool/Stage/Event three channels) +├── sdk/ PluginSDK (Tool/Stage/Event three channels) ├── config/ SQLite config center ├── events/ Event bus -└── lua/adapters/ 8 LLM protocol adapter scripts +└── internal/lua/adapters/ 8 LLM protocol adapter scripts External plugin development: see [homeagent-sdk](https://gitcode.com/JianFeeeee/homeagent-sdk) repo, use `plugindev` toolchain, refer to Go and Lua examples in `example/` ``` @@ -182,4 +182,4 @@ make test # go test ./... make install # Install to system ``` -Dependencies: Go 1.21+, CGo (go-sqlite3), Linux/Windows. +Dependencies: Go 1.25+, CGo (go-sqlite3), Linux/Windows. diff --git a/docs/en/ADAPTER.md b/docs/en/ADAPTER.md index 7b9d09e..38fb874 100644 --- a/docs/en/ADAPTER.md +++ b/docs/en/ADAPTER.md @@ -82,6 +82,10 @@ return adapter `log(level, message)` — Output log (level: info/warn/error) +`http_get(url)` — Perform HTTP GET request, returns response body as string + +`http_post(url, body)` — Perform HTTP POST request, returns response body as string + ## Adapting Typical APIs | API | endpoint | auth method | Format differences | diff --git a/docs/en/ARCHITECTURE.md b/docs/en/ARCHITECTURE.md index 2745069..1d8fddc 100644 --- a/docs/en/ARCHITECTURE.md +++ b/docs/en/ARCHITECTURE.md @@ -123,8 +123,8 @@ TF-IDF is the core algorithm running through all three memory layers, used in 4 | Location | File | Purpose | Algorithm | |----------|------|---------|-----------| -| Context Prune | `context.go:162` | Trim low-relevance context events | CosineSimilarity(queryVec, evt.Vector) | -| DocStore Query | `document.go:205` | Recall related content from document memory | InvertedIndex + CosineSimilarity | +| Context Prune | `context.go:161` | Trim low-relevance context events | CosineSimilarity(queryVec, evt.Vector) | +| DocStore Query | `document.go:198` | Recall related content from document memory | InvertedIndex + CosineSimilarity | | Indexer Entity Search | `indexer.go:149` | Recall related entities from Graph | InvertedIndex + CosineSimilarity | | Entity Similarity Detection | `agent.go:2297` | Detect similar entities in Graph | Bigram Jaccard (>0.75 → consolidation) | @@ -136,7 +136,7 @@ TF-IDF is the core algorithm running through all three memory layers, used in 4 ### Document Layer -`internal/memory/document/doc.go` — `Store` +`internal/memory/document/document.go` — `Store` - Consume-on-read mode: deleted after `doc_query` retrieval - TF-IDF index with character bigram + inverted index @@ -185,7 +185,7 @@ Heartbeat 30min: selfInputCh → LLM decides merge/skip ``` -Entity conflict detection heuristic (bigram Jaccard > 0.5), 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. ## Knowledge Base @@ -366,7 +366,7 @@ internal/ │ ├── agentcli/ — PTY terminal │ ├── healthcheck/ — Health check │ └── pluginmgr/ — Plugin manager -├── internal/sdk/ — PluginSDK definitions +├── sdk/ — PluginSDK definitions │ ├── plugin.go — Plugin interface + PluginSDK │ ├── memory.go — MemoryAPI │ ├── knowledge.go — KnowledgeAPI @@ -376,7 +376,7 @@ internal/ │ ├── graph.go — SQLite graph database │ ├── indexer.go — Graph → vector index │ ├── vector/store.go — TF-IDF vector engine -│ ├── document/doc.go — Document memory +│ ├── document/document.go — Document memory │ ├── text/text.go — Text logs │ └── pipeline/ — Distiller ├── knowledge/knowledge.go — Knowledge base @@ -387,6 +387,8 @@ internal/ ├── events/bus.go — Event bus ├── tracker/ — OverlayFS change tracking ├── supervisor/ — Daemon management -├── snapshot/ — Snapshots -└── tokenizer/ — Chinese tokenization (jieba wrapper) +├── skill/ — Skill plugin management +│ └── manager.go — Skill loading/matching +└── meta/ — Meta information + └── meta.go — Agent metadata ``` diff --git a/docs/en/OVERVIEW.md b/docs/en/OVERVIEW.md index 0003134..1af0364 100644 --- a/docs/en/OVERVIEW.md +++ b/docs/en/OVERVIEW.md @@ -37,7 +37,7 @@ Code is in the project root, implemented in Go. **Memory System** (`internal/memory/`): - **GraphDB** (`graph.go`) — SQLite, entities + relations tables, BFS traversal -- **Document Store** (`document/doc.go`) — Temporary memory, JSON files + TF-IDF vector index, consume-on-read +- **Document Store** (`document/document.go`) — Temporary memory, JSON files + TF-IDF vector index, consume-on-read - **Text Memory** (`text/text.go`) — Raw conversation logs, JSONL file rotation - **Social Store** (`social/social.go`) — Persona traits + relationship network, wraps GraphDB - **Memory Indexer** (`indexer.go`) — Auto-vectorizes GraphDB entities, recalls and injects into system prompt on user input @@ -50,7 +50,7 @@ Code is in the project root, implemented in Go. **Plugin System** (`internal/plugin/`): - Built-in plugins: Go `init()` self-registration, compiled into kernel - External plugins: Go `-buildmode=plugin` compiled to `.so`/`.dll`, dynamically loaded via `plugin.Open`; also supports Lua script plugins -- PluginSDK (`internal/sdk/`) defines three channels: RegisterTool / RegisterStage / Subscribe +- PluginSDK (`internal/sdk/`) defines four channels: RegisterTool / RegisterStage / Subscribe / RegisterOutputChannel - 7 stage hooks: on_input → pre_action → post_action → before_toolcall → after_toolcall → before_output → after_output **LLM Provider** (`internal/agent/api/provider.go`): diff --git a/docs/en/PLUGIN_DEV.md b/docs/en/PLUGIN_DEV.md index eac42a0..4780db3 100644 --- a/docs/en/PLUGIN_DEV.md +++ b/docs/en/PLUGIN_DEV.md @@ -265,10 +265,10 @@ s.Settings().GetPlugin("other_plugin", "some_key") ```go // Queued delivery (processed in order) -s.InjectInput(source, channel string, payload map[string]interface{}) +s.InjectInput(source, channel, eventType string, payload map[string]interface{}) // Interrupt delivery (can interrupt current LLM processing) -s.InjectInterrupt(source, channel string, payload map[string]interface{}) +s.InjectInterrupt(source, channel, eventType string, payload map[string]interface{}) // Shortcuts s.InjectText(source, channel, text string) @@ -318,7 +318,15 @@ s.Publish(&events.Event{ #### IO Channel Management (built-in plugins) ```go -// Register a channel (bind device driver) +// Register a channel (bind device driver), dev must implement the agentIO.Device interface: +// Name() string +// Type() DeviceType +// Description() string +// Tools() []ToolDef +// Execute(tool string, args map[string]interface{}) (interface{}, error) +// Start() error +// Stop() error +// OutputCapabilities() OutputCapability s.RegisterChannel("mydevice", deviceImpl) // Unregister a channel diff --git a/docs/zh/ADAPTER.md b/docs/zh/ADAPTER.md index 982aea6..75fde5a 100644 --- a/docs/zh/ADAPTER.md +++ b/docs/zh/ADAPTER.md @@ -82,6 +82,10 @@ return adapter `log(level, message)` — 输出日志（level: info/warn/error） +`http_get(url)` — 发起 HTTP GET 请求，返回响应体字符串 + +`http_post(url, body)` — 发起 HTTP POST 请求，返回响应体字符串 + ## 适配典型 API | API | endpoint | auth 方式 | 格式差异 | diff --git a/docs/zh/ARCHITECTURE.md b/docs/zh/ARCHITECTURE.md index d7f7147..d2f751f 100644 --- a/docs/zh/ARCHITECTURE.md +++ b/docs/zh/ARCHITECTURE.md @@ -123,8 +123,8 @@ TF-IDF 是贯穿三层记忆的核心算法，在 4 个独立位置以不同方 | 位置 | 文件 | 用途 | 算法 | |------|------|------|------| -| Context Prune | `context.go:162` | 裁剪低相关性上下文事件 | CosineSimilarity(queryVec, evt.Vector) | -| DocStore Query | `document.go:205` | 从文档记忆召回相关内容 | InvertedIndex + CosineSimilarity | +| Context Prune | `context.go:161` | 裁剪低相关性上下文事件 | CosineSimilarity(queryVec, evt.Vector) | +| DocStore Query | `document.go:198` | 从文档记忆召回相关内容 | InvertedIndex + CosineSimilarity | | Indexer 实体搜索 | `indexer.go:149` | 从Graph召回相关实体 | InvertedIndex + CosineSimilarity | | 实体相似度检测 | `agent.go:2297` | 检测Graph中相似实体 | Bigram Jaccard (>0.75 → consolidation) | @@ -136,7 +136,7 @@ TF-IDF 是贯穿三层记忆的核心算法，在 4 个独立位置以不同方 ### Document 层 -`internal/memory/document/doc.go` — `Store` +`internal/memory/document/document.go` — `Store` - 消费即删模式：`doc_query` 检索到后删除 - TF-IDF 索引 character bigram + 倒排 @@ -185,7 +185,7 @@ TF-IDF 是贯穿三层记忆的核心算法，在 4 个独立位置以不同方 selfInputCh → LLM 判断合并/跳过 ``` -实体冲突检测启发式（bigram Jaccard > 0.5），走 `selfInputCh` 内部通道，LLM 最终判断是否合并。 +实体冲突检测启发式（bigram Jaccard > 0.75），走 `selfInputCh` 内部通道，LLM 最终判断是否合并。 ## 知识库 @@ -366,7 +366,7 @@ internal/ │ ├── agentcli/ — PTY 终端 │ ├── healthcheck/ — 健康检查 │ └── pluginmgr/ — 插件管理器 -├── internal/sdk/ — PluginSDK 定义 +├── sdk/ — PluginSDK 定义 │ ├── plugin.go — Plugin 接口 + PluginSDK │ ├── memory.go — MemoryAPI │ ├── knowledge.go — KnowledgeAPI @@ -376,7 +376,7 @@ internal/ │ ├── graph.go — SQLite 图数据库 │ ├── indexer.go — 图→向量索引 │ ├── vector/store.go — TF-IDF 向量引擎 -│ ├── document/doc.go — 文档记忆 +│ ├── document/document.go — 文档记忆 │ ├── text/text.go — 文本日志 │ └── pipeline/ — 蒸馏器 ├── knowledge/knowledge.go — 知识库 @@ -387,6 +387,8 @@ internal/ ├── events/bus.go — 事件总线 ├── tracker/ — OverlayFS 变更追踪 ├── supervisor/ — 守护进程管理 -├── snapshot/ — 快照 -└── tokenizer/ — 中文分词 (jieba 包装) +├── skill/ — Skill 插件管理 +│ └── manager.go — Skill 加载/匹配 +└── meta/ — 元信息 + └── meta.go — Agent 元数据 ``` diff --git a/docs/zh/OVERVIEW.md b/docs/zh/OVERVIEW.md index ec6c925..d9c0d42 100644 --- a/docs/zh/OVERVIEW.md +++ b/docs/zh/OVERVIEW.md @@ -37,7 +37,7 @@ HomeAgent 是一个持续运行的个人智能 Agent 框架。 **记忆系统** (`internal/memory/`)： - **GraphDB** (`graph.go`) — SQLite，entities + relations 表，BFS 遍历 -- **Document Store** (`document/doc.go`) — 临时记忆，JSON 文件 + TF-IDF 向量索引，消费即删 +- **Document Store** (`document/document.go`) — 临时记忆，JSON 文件 + TF-IDF 向量索引，消费即删 - **Text Memory** (`text/text.go`) — 原始对话日志，JSONL 文件轮转 - **Social Store** (`social/social.go`) — 人格特质 + 关系网，包装 GraphDB - **Memory Indexer** (`indexer.go`) — 自动将 GraphDB 实体向量化，用户输入时召回注入 system prompt @@ -50,7 +50,7 @@ HomeAgent 是一个持续运行的个人智能 Agent 框架。 **插件系统** (`internal/plugin/`)： - 内置插件：Go `init()` 自注册，编译进内核 - 外部插件：Go `-buildmode=plugin` 编译为 `.so`/`.dll`，通过 `plugin.Open` 动态加载；也支持 Lua 脚本插件 -- PluginSDK (`internal/sdk/`) 定义三通道：RegisterTool / RegisterStage / Subscribe +- PluginSDK (`internal/sdk/`) 定义四通道：RegisterTool / RegisterStage / Subscribe / RegisterOutputChannel - 阶段钩子 7 个：on_input → pre_action → post_action → before_toolcall → after_toolcall → before_output → after_output **LLM Provider** (`internal/agent/api/provider.go`)： diff --git a/docs/zh/PLUGIN_DEV.md b/docs/zh/PLUGIN_DEV.md index 80465fa..ee87807 100644 --- a/docs/zh/PLUGIN_DEV.md +++ b/docs/zh/PLUGIN_DEV.md @@ -266,10 +266,10 @@ s.Settings().GetPlugin("other_plugin", "some_key") ```go // 排队投递（按序处理） -s.InjectInput(source, channel string, payload map[string]interface{}) +s.InjectInput(source, channel, eventType string, payload map[string]interface{}) // 中断投递（可打断当前 LLM 处理） -s.InjectInterrupt(source, channel string, payload map[string]interface{}) +s.InjectInterrupt(source, channel, eventType string, payload map[string]interface{}) // 快捷方式 s.InjectText(source, channel, text string) @@ -319,7 +319,15 @@ s.Publish(&events.Event{ #### IO 通道管理（内置插件） ```go -// 注册通道（绑定设备驱动） +// 注册通道（绑定设备驱动），dev 必须实现 agentIO.Device 接口： +// Name() string +// Type() DeviceType +// Description() string +// Tools() []ToolDef +// Execute(tool string, args map[string]interface{}) (interface{}, error) +// Start() error +// Stop() error +// OutputCapabilities() OutputCapability s.RegisterChannel("mydevice", deviceImpl) // 注销通道 diff --git a/knowledge/homeagent_architecture/content.md b/knowledge/homeagent_architecture/content.md index c86d5bc..62ec3d9 100644 --- a/knowledge/homeagent_architecture/content.md +++ b/knowledge/homeagent_architecture/content.md @@ -30,8 +30,8 @@ HomeAgent 采用内核 + 插件双层架构： ## 核心特性 ### 内核 -- **LLM 引擎**：多 Provider 自动故障转移，8 个适配器（DeepSeek/Anthropic/Gemini/GitHub/Groq/Mistral/Ollama/OpenAI），自动降级 -- **记忆系统**：四层记忆架构——图记忆（实体+关系）、文档记忆、文本记忆、社交记忆，向量索引检索 +- **LLM 引擎**：多 Provider 自动故障转移，8 个适配器（Anthropic/DeepSeek/Gemini/GitHub/Groq/Mistral/Ollama/OpenAI），自动降级 +- **记忆系统**：三层记忆架构——上下文记忆（Context）、文档记忆（Document）、图记忆（Graph，实体+关系），向量索引检索；文本记忆与社交记忆为辅助存储 - **上下文管理**：自动剪枝低相关性事件，蒸馏重要信息写入长期记忆，有效防止上下文膨胀和记忆衰减 - **工具调度**：同质阶段并行执行，支持 pre_action/post_action/on_input 等生命周期钩子 - **事件总线**：发布/订阅模式，插件间松耦合通信 @@ -49,8 +49,8 @@ HomeAgent 采用内核 + 插件双层架构： - 文件变更追踪基于 overlayfs 实现 ## 技术栈 -- 语言：Go 1.19+ -- 构建：标准 Go toolchain，CGO_ENABLED=1（overlayfs 依赖） +- 语言：Go 1.25+ +- 构建：标准 Go toolchain，CGO_ENABLED=1（go-sqlite3 依赖） - 插件：Go -buildmode=plugin - LLM 适配：Lua 胶水层，8 个适配器 - 搜索：内置 TF-IDF 向量化器 \ No newline at end of file