docs: fix documentation-source mismatches across all doc files

- 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
2026-09-29 06:00:56 +00:00 · 2026-07-16 23:17:55 +08:00
parent 8892bef9a9
commit 90aa8ee662
11 changed files with 64 additions and 36 deletions
--- 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。
+依赖：Go 1.25+, CGo (go-sqlite3), Linux/Windows。
--- 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.
--- 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 |
--- 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
 ```
--- 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`):
--- 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
--- 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 方式 | 格式差异 |
--- 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 元数据
 ```
--- 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`)：
--- 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)

 // 注销通道
--- 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 向量化器