mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-11-01 06:47:29 +00:00
docs: 按源码全面校正(插件数/内置 timer/RPC 数/工具数/失效行号)
逐条对着源码核过,修掉 5 类与实现不符的陈述(中英四份文档同步): 1. **内置插件数 20 → 17** `internal/plugins/all.go` 的空白导入实际是 17 个。旧文档还列了 `timer` (已外置)与 `data`/`kbtree`(根本不是内置插件,前者只有 skills 目录, 后者未进 all.go)。清单按 all.go 重写。 涉及:README、README_EN(含「许可」章节的 AGPL 覆盖范围)、OVERVIEW 中英、 ARCHITECTURE 中英的加载方式表。 2. **删除所有把 timer 当内置插件的表述** ARCHITECTURE 中英目录树里的 `internal/plugins/timer/` 行、 PLUGIN_DEV 内置插件示例表的 Timer 行(该行还与同页下方「timer 已移出内置插件」 的说明自相矛盾)。示例表改用 healthcheck(真实存在、30m 定时自检)。 3. **子进程 RPC 方法数 55 → 82** 权威清单是 `internal/plugin/proc/protocol.go` 的 Method 常量, 实际 82 个(settings 16 / plugin 9 / io 8 / secrets 7 …)。 v1.1.1「51 → 55」作为历史叙述保留,但补注说明 82 才是当前值, 避免读者把 55 当现值。 4. **qq 示例工具数 20 → 24** 按 `example/qq/plugin.go` 的 `Name: tp + "..."` 实数。 5. **修掉整张失效的「文件:行号」引用表** 原文写 `context.go:155` / `document.go:206` / `indexer.go:96+111`, 但 memory 重组后 `context.go` 已迁到 `agent/core/`,行号全部错位。 改为**函数名锚点**(`RelevanceContext.Prune`、`Store.Query`、 `Indexer.vectorSearchEntities`),并改正 `distill.go` 的算法描述: 文档写 Bigram Jaccard,源码是**加权** Jaccard(`scene_emerge.go` 有明确注释), 阈值 `sim > 0.75` 在 `distill.go`。 同时补 Provider 接口漏项:实际有 4 个方法(Name / Chat / ChatStream / MaxContextTokens),文档只写了前 3 个。 验证:`go build ./...` 通过;文档内相对链接 0 坏链; 引用的 22 个 .go 路径逐个 stat 存在(`internal/memory/media/` 两处是 「已删除机制」的历史叙述,指向不存在路径是正确语义,保持不变)。
This commit is contained in:
@ -158,10 +158,17 @@ dimension** participate in fusion (mixing coordinate systems yields a direction
|
||||
|
||||
| Location | File | Purpose | Algorithm |
|
||||
|----------|------|---------|-----------|
|
||||
| Context Prune | `context.go:155` | Trim low-relevance context events | VectorizeClean → CosineSimilarity(queryVec, evt.Vector) |
|
||||
| DocStore Query | `document.go:206` | Recall from document memory | StaticEmbedder.Vectorize (primary) / TF-IDF (fallback) → vec.Search |
|
||||
| Indexer Entity Search | `indexer.go:96+111` | Recall from Graph | vector entity search + jieba keywords → SQLite LIKE + BFS |
|
||||
| Entity Similarity Detection | `distill.go` | Detect similar entities in Graph | Bigram Jaccard (>0.75 → consolidation) |
|
||||
> The table below pins **function names**, not line numbers: lines drift on every edit,
|
||||
> function names are the stable anchor. (The old version cited `context.go:155` /
|
||||
> `document.go:206` / `indexer.go:96+111`; after the memory reorg `context.go` moved to
|
||||
> `agent/core/`, so those line numbers had long been stale.)
|
||||
|
||||
| Location | File (function) | Purpose | Algorithm |
|
||||
|----------|------|---------|-----------|
|
||||
| Context Prune | `internal/agent/core/context.go` — `RelevanceContext.Prune` / `PruneWithProtected` | Trim low-relevance context events | VectorizeClean → CosineSimilarity(queryVec, evt.Vector) |
|
||||
| DocStore Query | `internal/memory/document/document.go` — `Store.Query` / `QueryScored` | Recall from document memory | StaticEmbedder.Vectorize (primary) / TF-IDF (fallback) → vec.Search |
|
||||
| Indexer Entity Search | `internal/memory/indexer.go` — `Indexer.vectorSearchEntities` | Recall from Graph | vector entity search + jieba keywords → SQLite LIKE + BFS |
|
||||
| Entity Similarity Detection | `internal/agent/core/distill.go` | Detect similar entities in Graph | Weighted Jaccard (`sim > 0.75` → consolidation) |
|
||||
|
||||
### Context Layer
|
||||
|
||||
@ -311,7 +318,7 @@ VM built-ins: `json.encode` / `json.decode` / `log` / `http_get` / `http_post`.
|
||||
|
||||
| Method | Registration Mechanism | Compilation | Usage |
|
||||
|--------|----------------------|-------------|-------|
|
||||
| Built-in | `init()` → `RegisterFactory` | `internal/plugins/` compiled into kernel | webui/cli/timer/mcp etc. |
|
||||
| Built-in | `init()` → `RegisterFactory` | `internal/plugins/` compiled into kernel | webui/cli/cmd/mcp etc. (17 total) |
|
||||
| External subprocess plugin | Handshake + stdio JSON-RPC reverse registration | `hmapdev build` → `plugin.bin` (ordinary Go binary) | qq/browser/files etc. |
|
||||
| Lua script plugin | Execute `main.lua` to register tools | No compilation, takes effect after restart/reload | luademo etc. |
|
||||
| SKILL plugin | Parse `SKILL.md` | Markdown definition | Loaded via clawhubadapter |
|
||||
@ -349,7 +356,7 @@ Common ground:
|
||||
|
||||
| Plane | Mechanism | Why this choice |
|
||||
|---|---|---|
|
||||
| Control | stdio JSON-RPC (NDJSON frames), 55 `core.*` methods | The process boundary *is* the ABI boundary—no need to maintain three platform-specific dynamic-library loaders |
|
||||
| Control | stdio JSON-RPC (NDJSON frames), currently 82 methods (authoritative list: `internal/plugin/proc/protocol.go`) | The process boundary *is* the ABI boundary—no need to maintain three platform-specific dynamic-library loaders |
|
||||
| Data | Shared memory segment, **one segment shared by all subprocesses** | One segment per plugin would degrade "kernel ctx → segment → plugin mutates → read back" into the copy model under concurrency, reproducing lost updates exactly |
|
||||
| Notification | Event ring + platform notify (Linux eventfd / macOS pipe / Windows Event) | The kernel must never block on a consumer: streaming output publishes per token, so any wait shows up as stutter |
|
||||
|
||||
@ -591,7 +598,6 @@ internal/
|
||||
│ ├── all.go — Blank imports
|
||||
│ ├── webui/ — HTTP server + embedded SPA
|
||||
│ ├── cli/ — Unix socket CLI
|
||||
│ ├── timer/ — Timer
|
||||
│ ├── cmd/ — Command execution
|
||||
│ ├── mcp/ — MCP protocol
|
||||
│ ├── files/ — File operations
|
||||
|
||||
@ -75,7 +75,7 @@ Code is in the project root, implemented in Go.
|
||||
- 7 stage hooks: on_input → pre_action → post_action → before_toolcall → after_toolcall → before_output → after_output
|
||||
|
||||
**LLM Provider** (`internal/agent/api/provider.go`):
|
||||
- Provider interface: Name / Chat / ChatStream
|
||||
- Provider interface: Name / Chat / ChatStream / MaxContextTokens
|
||||
- Single implementation, `LuaAdaptedProvider`: every source goes through a Lua adapter script that
|
||||
transforms requests/responses; adapter scripts live in `internal/lua/adapters/`, one `.lua` per protocol
|
||||
- 10 built-in adapters: deepseek / openai / anthropic / gemini / mistral / groq / github / kimicode / ollama / server
|
||||
|
||||
@ -811,7 +811,7 @@ Internal: records are stored in SQLite `disabled_plugins` table (`name`, `disabl
|
||||
|---------|------|----------|
|
||||
| [weather](https://github.com/JianFeeeee/homeagentsdk/tree/main/example/weather) | Go | Weather queries (wttr.in); demonstrates NoMemory/Cleaner/stage hooks/channels/text memory |
|
||||
| [luademo](https://github.com/JianFeeeee/homeagentsdk/tree/main/example/luademo) | Lua | Full-featured Lua example covering the whole v0.8.0 Lua SDK surface |
|
||||
| [qq](https://github.com/JianFeeeee/homeagentsdk/tree/main/example/qq) | Go | NapCat OneBot integration, 20 tools, full input/output channel wiring |
|
||||
| [qq](https://github.com/JianFeeeee/homeagentsdk/tree/main/example/qq) | Go | NapCat OneBot integration, 24 tools, full input/output channel wiring |
|
||||
| [memo](https://github.com/JianFeeeee/homeagentsdk/tree/main/example/memo) | Go | Memo management, PreAction injection + timed interrupt dual reminder |
|
||||
| [files](https://github.com/JianFeeeee/homeagentsdk/tree/main/example/files) | Go | File system operations, 4 write modes, sandbox isolation |
|
||||
| [browser](https://github.com/JianFeeeee/homeagentsdk/tree/main/example/browser) | Go | Web search + HTTP fetch (SSRF) + Chromium render (merged from web/webfetch) |
|
||||
@ -835,7 +835,7 @@ Internal: records are stored in SQLite `disabled_plugins` table (`name`, `disabl
|
||||
|
||||
| Plugin | Location | Features |
|
||||
|--------|----------|----------|
|
||||
| Timer | `internal/plugins/timer/` | Simplest complete example, registers one tool + interrupt feedback |
|
||||
| Healthcheck | `internal/plugins/healthcheck/` | Periodic self-check (30min) + tool-surface status, the simplest tool-type built-in |
|
||||
| CLI | `internal/plugins/cli/` | Unix socket listener + synchronous request-response |
|
||||
| WebUI | `internal/plugins/webui/` | HTTP service + dependency injection |
|
||||
|
||||
|
||||
Reference in New Issue
Block a user