From 515cf2deb116e48e606ae688b8586a01ac68c5b6 Mon Sep 17 00:00:00 2001 From: root Date: Mon, 19 Oct 2026 20:49:43 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=8C=89=E6=BA=90=E7=A0=81=E5=85=A8?= =?UTF-8?q?=E9=9D=A2=E6=A0=A1=E6=AD=A3=EF=BC=88=E6=8F=92=E4=BB=B6=E6=95=B0?= =?UTF-8?q?/=E5=86=85=E7=BD=AE=20timer/RPC=20=E6=95=B0/=E5=B7=A5=E5=85=B7?= =?UTF-8?q?=E6=95=B0/=E5=A4=B1=E6=95=88=E8=A1=8C=E5=8F=B7=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 逐条对着源码核过，修掉 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/` 两处是 「已删除机制」的历史叙述，指向不存在路径是正确语义，保持不变）。 --- README.md | 4 ++-- README_EN.md | 4 ++-- assets/docs/en/ARCHITECTURE.md | 20 +++++++++++++------- assets/docs/en/OVERVIEW.md | 2 +- assets/docs/en/PLUGIN_DEV.md | 4 ++-- assets/docs/zh/ARCHITECTURE.md | 22 +++++++++++++++------- assets/docs/zh/OVERVIEW.md | 4 ++-- assets/docs/zh/PLUGIN_DEV.md | 4 ++-- 8 files changed, 39 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 0438965d..85ae3431 100644 --- a/README.md +++ b/README.md @@ -235,7 +235,7 @@ internal/ ├── memory/ 三层记忆：Graph(SQLite) / Document(JSON+TF-IDF) / Text(JSONL) + StaticEmbedder(预训练词嵌入/TF-IDF回退) + CleanTemplateText(去模版) ├── knowledge/ 知识库（文件系统 + TF-IDF） ├── plugin/ 插件注册表 + 子进程加载器（stdio RPC + 共享内存段 + 事件环） -├── plugins/ 内置 20 个插件（webui/cli/timer/cmd/mcp/files/cfgmgr/agentcli/healthcheck/pluginmgr/clawhubadapter/multimodal/remotedevice/ai_image/localuse/skillmgr/data/seq/kbtree 等） +├── plugins/ 内置 17 个插件（webui/cli/cmd/mcp/files/cfgmgr/agentcli/healthcheck/pluginmgr/clawhubadapter/multimodal/remotedevice/ai_image/localuse/skillmgr/seemedia/seq） ├── sdk/ PluginSDK（Tool/Stage/Event 三通道） ├── config/ SQLite 配置中心 ├── events/ 事件总线 @@ -390,7 +390,7 @@ make install # 安装到系统 本项目的 AGPL。因此**外部插件不是本项目的衍生作品**，作者可自行选择许可（含闭源、商业、私有）， 既不必同许可、也不受 §13 网络条款约束。第三方插件生态的安全与活跃正建立在这条之上。 -边界很清楚：**AGPL 覆盖内核与随包内置插件**（`homed`、`internal/`、`internal/plugins/` 下 20 个内置插件）； +边界很清楚：**AGPL 覆盖内核与随包内置插件**（`homed`、`internal/`、`internal/plugins/` 下 17 个内置插件）； **MIT 覆盖公开 SDK**（`sdk/`，`go.mod` 零外部依赖、只依赖 Go 标准库，不引用内核任何代码）。 子进程隔离在这里不重要了——决定许可的是被链接的 SDK 代码本身，而它是 MIT。 diff --git a/README_EN.md b/README_EN.md index 39b6d538..1a1bdfc2 100644 --- a/README_EN.md +++ b/README_EN.md @@ -216,7 +216,7 @@ internal/ ├── memory/ Three-layer memory: Graph(SQLite) / Document(JSON+TF-IDF) / Text(JSONL) + StaticEmbedder(pretrained word embedding/TF-IDF fallback) + CleanTemplateText(de-template) ├── knowledge/ Knowledge base (filesystem + TF-IDF) ├── plugin/ Plugin registry + subprocess loader (stdio RPC + shared memory segment + event ring) -├── plugins/ 20 built-in plugins (webui/cli/timer/cmd/mcp/files/cfgmgr/agentcli/healthcheck/pluginmgr/clawhubadapter/multimodal/remotedevice/ai_image/localuse/skillmgr/data/seq/kbtree, ...) +├── plugins/ 17 built-in plugins (webui/cli/cmd/mcp/files/cfgmgr/agentcli/healthcheck/pluginmgr/clawhubadapter/multimodal/remotedevice/ai_image/localuse/skillmgr/seemedia/seq) ├── sdk/ PluginSDK (Tool/Stage/Event three channels) ├── config/ SQLite config center ├── events/ Event bus @@ -416,7 +416,7 @@ private included), with no same-license obligation and no §13 network clause. T vitality of the third-party plugin ecosystem rest on this. The boundary is clean: **AGPL covers the kernel and the bundled plugins** (`homed`, `internal/`, -the 20 built-in plugins under `internal/plugins/`); **MIT covers the public SDK** (`sdk/`, whose +the 17 built-in plugins under `internal/plugins/`); **MIT covers the public SDK** (`sdk/`, whose `go.mod` has zero external dependencies and imports only the Go standard library — it never references any kernel code). Process isolation is beside the point here — what decides the license is the linked SDK code itself, and that code is MIT. diff --git a/assets/docs/en/ARCHITECTURE.md b/assets/docs/en/ARCHITECTURE.md index 32a64361..54cf003d 100644 --- a/assets/docs/en/ARCHITECTURE.md +++ b/assets/docs/en/ARCHITECTURE.md @@ -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 diff --git a/assets/docs/en/OVERVIEW.md b/assets/docs/en/OVERVIEW.md index 35a8e2a1..c2e3906b 100644 --- a/assets/docs/en/OVERVIEW.md +++ b/assets/docs/en/OVERVIEW.md @@ -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 diff --git a/assets/docs/en/PLUGIN_DEV.md b/assets/docs/en/PLUGIN_DEV.md index 7f59c204..abfc5d43 100644 --- a/assets/docs/en/PLUGIN_DEV.md +++ b/assets/docs/en/PLUGIN_DEV.md @@ -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 | diff --git a/assets/docs/zh/ARCHITECTURE.md b/assets/docs/zh/ARCHITECTURE.md index 05ad46d9..da31c850 100644 --- a/assets/docs/zh/ARCHITECTURE.md +++ b/assets/docs/zh/ARCHITECTURE.md @@ -156,10 +156,16 @@ eventLoop() → processTextInput() | 位置 | 文件 | 用途 | 算法 | |------|------|------|------| -| Context Prune | `context.go:155` | 裁剪低相关性上下文事件 | VectorizeClean → CosineSimilarity(queryVec, evt.Vector) | -| DocStore Query | `document.go:206` | 文档记忆召回 | StaticEmbedder.Vectorize（首选）/ TF-IDF（兜底）→ vec.Search | -| Indexer 实体搜索 | `indexer.go:96+111` | Graph实体召回 | 向量实体搜索 + jieba关键词 → SQLite LIKE + BFS | -| 实体相似度检测 | `distill.go` | Graph中相似实体 | Bigram Jaccard (>0.75 → consolidation) | +> 下表按**函数名**定位，不绑定行号：行号随每次改动漂移，函数名才是稳定锚点。 +> （旧版这里写的是 `context.go:155` / `document.go:206` / `indexer.go:96+111`， +> 但 memory 重组后 `context.go` 已迁到 `agent/core/`，那些行号早已失效。） + +| 位置 | 文件（函数） | 用途 | 算法 | +|------|------|------|------| +| Context Prune | `internal/agent/core/context.go` — `RelevanceContext.Prune` / `PruneWithProtected` | 裁剪低相关性上下文事件 | VectorizeClean → CosineSimilarity(queryVec, evt.Vector) | +| DocStore Query | `internal/memory/document/document.go` — `Store.Query` / `QueryScored` | 文档记忆召回 | StaticEmbedder.Vectorize（首选）/ TF-IDF（兜底）→ vec.Search | +| Indexer 实体搜索 | `internal/memory/indexer.go` — `Indexer.vectorSearchEntities` | Graph实体召回 | 向量实体搜索 + jieba关键词 → SQLite LIKE + BFS | +| 实体相似度检测 | `internal/agent/core/distill.go` | Graph中相似实体 | 加权 Jaccard（阈值 `sim > 0.75` → consolidation） | ### Context 层 @@ -301,7 +307,7 @@ VM 内置 `json.encode` / `json.decode` / `log` / `http_get` / `http_post`。 | 方式 | 注册机制 | 编译 | 用途 | |------|----------|------|------| -| 内置插件 | `init()` → `RegisterFactory` | `internal/plugins/` 编译进内核 | webui/cli/timer/mcp 等 | +| 内置插件 | `init()` → `RegisterFactory` | `internal/plugins/` 编译进内核 | webui/cli/cmd/mcp 等 17 个 | | 外部子进程插件 | 握手 + stdio JSON-RPC 反向注册 | `hmapdev build` → `plugin.bin`（普通 Go 二进制） | qq/browser/files 等 | | Lua 脚本插件 | 执行 `main.lua` 注册工具 | 无需编译，重启/重载生效 | luademo 等 | | SKILL 插件 | 解析 `SKILL.md` | Markdown 定义 | clawhubadapter 兼容加载 | @@ -339,7 +345,7 @@ Lua 脚本插件加载：`internal/plugin/` → gopher-lua 解释器执行 `main | 面 | 机制 | 为何这么选 | |---|---|---| -| 控制面 | stdio JSON-RPC（NDJSON 帧），55 个 `core.*` method | 进程边界即 ABI 边界，无需维护三套平台特定的动态库加载代码 | +| 控制面 | stdio JSON-RPC（NDJSON 帧），当前 82 个 method（权威清单见 `internal/plugin/proc/protocol.go`） | 进程边界即 ABI 边界，无需维护三套平台特定的动态库加载代码 | | 数据面 | 共享内存段，**全部子进程共用一块** | 每插件一段会让「内核 ctx → 段 → 插件改 → 回读 ctx」在多插件下退化成副本模型，lost update 原样复现 | | 通知面 | 事件环 + 平台通知（Linux eventfd / macOS pipe / Windows Event） | 内核发事件绕不等消费者，流式输出逐 token 发布时任何等待都会造成卡顿 | @@ -347,6 +353,9 @@ v1.1.1 新增 4 个 method（51 → 55）：`doc.insertWithMedia`、`io.injectMe `io.injectMediaSync`、`io.injectInterruptMedia`。**媒体块走 JSON 而非共享段二进制通道**—— data URL 本身已是 base64 文本，包进二进制传输省不了空间，还要跟其余 51 个 method 分道。 +> 上表的「82 个」是**当前**值；51/55 是 v1.1.1 当时的数字，此后各条发布线继续追加 +> （settings / secrets / social / knowledge 等面），故不再回填到历史叙述里。 + **子进程生命周期管理**： - 每子进程一根专职 `waitLoop`（`cmd.Wait()` 唯一调用点）——不依赖 stdout EOF， 因为插件 fork 的孙子进程（browser 拉 chromium、editdoc 拉 python）继承同一 stdout， @@ -568,7 +577,6 @@ internal/ │ ├── all.go — 空白导入 │ ├── webui/ — HTTP 服务器 + 嵌入式 SPA │ ├── cli/ — Unix socket CLI -│ ├── timer/ — 定时器 │ ├── cmd/ — 命令执行 │ ├── mcp/ — MCP 协议 │ ├── files/ — 文件操作 diff --git a/assets/docs/zh/OVERVIEW.md b/assets/docs/zh/OVERVIEW.md index 19ae3b7c..3f5d72ee 100644 --- a/assets/docs/zh/OVERVIEW.md +++ b/assets/docs/zh/OVERVIEW.md @@ -69,7 +69,7 @@ HomeAgent 是一个持续运行的个人智能 Agent 框架。 - 阶段钩子 7 个：on_input → pre_action → post_action → before_toolcall → after_toolcall → before_output → after_output **LLM Provider** (`internal/agent/api/provider.go`)： -- Provider 接口：Name / Chat / ChatStream +- Provider 接口：Name / Chat / ChatStream / MaxContextTokens - 唯一实现 `LuaAdaptedProvider`：所有源都经 Lua 适配脚本做请求/响应变换； 适配器脚本位于 `internal/lua/adapters/`，每类协议一个 `.lua` 脚本 - 内置 10 个适配器：deepseek / openai / anthropic / gemini / mistral / groq / github / kimicode / ollama / server @@ -93,6 +93,6 @@ HomeAgent 是一个持续运行的个人智能 Agent 框架。 核心功能已可运行。插件系统和 SDK 已就绪，可独立开发外部插件。 -- 内置插件：webui / cli / timer / cmd / mcp / agentcli / healthcheck / pluginmgr / clawhubadapter / files / cfgmgr +- 内置插件（17 个）：webui / cli / cmd / mcp / agentcli / healthcheck / pluginmgr / clawhubadapter / files / cfgmgr / multimodal / remotedevice / ai_image / localuse / skillmgr / seemedia / seq - 外部插件示例（[homeagent-sdk](https://github.com/JianFeeeee/homeagentsdk) 仓库 `example/`，含 Go 和 Lua 两种类型）：qq / files / a2a / ai_image / bili / browser / calendar / editdoc / memo / music / ocr / rss / sanitizer / weather / luademo - 打包分发：`.hmap` 插件包格式，通过 WebUI 安装 diff --git a/assets/docs/zh/PLUGIN_DEV.md b/assets/docs/zh/PLUGIN_DEV.md index b9d1f9a6..b5657269 100644 --- a/assets/docs/zh/PLUGIN_DEV.md +++ b/assets/docs/zh/PLUGIN_DEV.md @@ -802,7 +802,7 @@ pmgr.ReloadPlugins() // 重载所有插件 |------|------|------| | [weather](https://github.com/JianFeeeee/homeagentsdk/tree/main/example/weather) | Go | 天气查询（wttr.in），演示 NoMemory/Cleaner/阶段钩子/通道/文本记忆 | | [luademo](https://github.com/JianFeeeee/homeagentsdk/tree/main/example/luademo) | Lua | Lua 全功能示例，覆盖 v0.8.0 Lua SDK 全部 API 面 | -| [qq](https://github.com/JianFeeeee/homeagentsdk/tree/main/example/qq) | Go | NapCat OneBot 对接，20 个工具，输入/输出通道完整对接 | +| [qq](https://github.com/JianFeeeee/homeagentsdk/tree/main/example/qq) | Go | NapCat OneBot 对接，24 个工具，输入/输出通道完整对接 | | [memo](https://github.com/JianFeeeee/homeagentsdk/tree/main/example/memo) | Go | 备忘管理，PreAction 注入 + 定时打断双提醒 | | [files](https://github.com/JianFeeeee/homeagentsdk/tree/main/example/files) | Go | 文件系统操作，4 种写入模式，沙箱隔离 | | [browser](https://github.com/JianFeeeee/homeagentsdk/tree/main/example/browser) | Go | 网络搜索、网页抓取（SSRF）、浏览器渲染（合并自 web/webfetch） | @@ -826,7 +826,7 @@ pmgr.ReloadPlugins() // 重载所有插件 | 插件 | 位置 | 特点 | |------|------|------| -| Timer | `internal/plugins/timer/` | 最简单的完整示例，注册一个工具 + 中断反馈 | +| Healthcheck | `internal/plugins/healthcheck/` | 定时自检（30min）＋ 工具面自报状态，最简的工具型内置插件 | | CLI | `internal/plugins/cli/` | Unix socket 监听 + 同步请求响应 | | WebUI | `internal/plugins/webui/` | HTTP 服务 + 依赖注入 |