jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-10-15 12:15:16 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
937164e5153a93f95761c372a63325438fdfcf5a
HomeAgent/assets/docs/zh/OVERVIEW.md
JianFeeeee 6d38a164eb chore(module): Go module 路径随托管地迁移 gitcode → github 
## 背景

仓库早已迁移到 GitHub（`github.com/JianFeeeee/HomeAgent`，CI/CD 都在那边跑），
gitcode 保留为**国内只读镜像**（`ci.yml` 的 sync-gitcode-main 快进推送）。
但 go.mod 的 module 路径一直是 `gitcode.com/JianFeeeee/...` —— 既与权威源
不符，`meta.SourceURL`（AGPL §13 的源码提供入口）也指向镜像而非实际运行的代码。

## 关键区分（这是本次改动安全的前提）

两个 module 是**不同**的，影响面差一个数量级：

| module | 谁依赖 | 改它的后果 |
|---|---|---|
| `.../HomeAgent`（主仓） | **只有主仓自己** | 内部重构，零外部影响 |
| `.../homeagent-sdk`（SDK 仓） | 主仓 49 文件 + 所有外部插件 | 需重编插件 |

★ 实测确认：**插件不 import 主仓 module**（`strings qq/plugin.bin | grep HomeAgent` = 0），
只依赖 SDK 仓。而插件与内核的边界是 **RPC 方法名字符串**
（`plugin.init` / `tool.invoke`…，见 proc/protocol.go），**与 Go module 名无关**。
⇒ module 改名**不改变任何 wire 协议**，现网已装的插件照常运行。

SDK 的 GitHub 仓名是 `homeagentsdk`（无连字符），module 路径必须与之精确匹配，
否则 `go get` 会因路径不符失败，故取 `github.com/JianFeeeee/homeagentsdk`。

## 改动

- `go.mod` / `go.sum`：两个 module 路径 + require/replace
- 277 个 Go 文件 + Makefile + 打包脚本的 import 与 ldflags 路径
- SDK 仓 `meta.CoreModule`、`tools/hmapdev` 的 module 声明与工程模板
- 对外文档/链接的仓库地址（README、PLUGIN_DEV、OVERVIEW 等）

## 明确**保留** gitcode 的地方（镜像机制，不能动）

- `GITCODE_TOKEN`、`GC_URL="…@gitcode.com"`（CI 同步 job）
- `gitcode.com/api/v5/...`（release 附件上传）
- git remote `gitcode`（镜像拉取/推送）
- `docs/zh/ci-cd-runbook.md`（整篇讲镜像运维）

## 验证

- `go build ./...` / `go vet ./...` 绿
- `go test ./... -count=1` → 48 包 ok / 0 FAIL
- hmapdev 工具链编译通过（`third_party/homeagent-sdk/tools/hmapdev`）
- 全仓残留检查：module 形态的 `gitcode.com/JianFeeeee` = 0
- 镜像机制抽验：GC_URL / @gitcode / api/v5 / remote 均完好

## 顺带修正

`hmapdev/templates.go` 的注释此前写「gitcode 的模块不在 proxy.golang.org 上」——
module 已迁 GitHub，该论断不再成立。改为如实说明**为何仍默认 replace 到本机 SDK**：
离线可构建、避免版本漂移、内网可用。理由与托管地无关，故 replace 保留。
2026-10-08 10:40:17 +08:00

6.7 KiB
Raw Blame History

English | 中文

HomeAgent — 项目概览

这是什么

HomeAgent 是一个持续运行的个人智能 Agent 框架。

核心架构：一个长时间运行的内核进程（homed），通过插件系统接入各种 IO 通道（QQ、Web、命令行等）。内核负责 LLM 调用编排、记忆管理、知识检索；插件负责所有外部 IO——收发消息、执行文件操作、搜索网络等。

设计要点

核心域与应用域分离 — 内核（核心域）不执行任何 IO 操作，所有 IO 能力归属插件（应用域）。边界通过 PluginSDK 明确定义：

  • 插件向内核注册工具（Tool），供 LLM 调用
  • 插件挂入处理管道（Stage），在各阶段拦截/改写消息流
  • 插件订阅/发布事件（Event），松耦合通信
  • 插件通过 IO API 排队或打断投递输入

这一划分的意义在于职责边界清晰：内核专注于编排与记忆管理，插件负责具体 IO 实现，二者互不耦合。

三层记忆架构 — 通过分级存储策略管理 Agent 长周期运行中的信息留存：

  • Context 层：内存中预训练词嵌入评分的事件窗口（StaticEmbedder 词向量 → CosineSimilarity，TF-IDF 回退），实时维护最近上下文，低相关性事件自动下沉到下一层
  • Document 层：JSON 文件 + TF-IDF 向量索引的临时记忆，支持显式提交和隐式归档，冷数据蒸馏到 Graph
  • Graph 层：SQLite 图数据库，持久化实体（entities）和关系（relations），BFS 遍历召回，蒸馏管道从对话中提取三元组

三层递进：上下文 → 冷归档 → 长期图记忆，构成从短期到持久的信息衰减与整合管道。

媒体记忆（v1.2.0 起：一等记忆块） — 图片/音频不是附属物，而是记忆的一等节点：

  • 内容寻址存储（CAS）：digest 寻址，元数据在 SQLite、blob 在磁盘（两级分桶），相同字节只存一份， 每次 Get 重校 digest（磁盘损坏静默返回脏数据比报错更危险）
  • 媒体块直接参与向量检索：块携带自己的多模态向量与指纹，正文里不再有任何媒体标记
  • 无独立 GC、无引用计数、无 keep-set：记忆块遵循单层不变量——Context → Document → Graph 是块的迁移，不是复制、也不靠引用保活；删除块即删内容
  • v1.1.1 起贯通插件边界：插件可通过 InsertWithMedia / InjectInputMedia 读写媒体， 模型可用 memory_commit / doc_commit 的 media_digests 参数关联媒体
  • 旧机制已整体拆除：此前把视觉模型生成的描述写进正文、以 [<mime> <短digest>] <描述> 标记 参与检索的描述式索引，以及 media_refs 引用计数，均已在 v1.2.0 删除——描述是模型生成的 二手信息，检索「别人转述的图片」不如检索图片自己的向量

它实际做了什么

代码位于项目仓库根目录，Go 语言实现。

内核 (internal/agent/core/)：

  • eventloop.go — 消息循环（eventLoop），从 IO 层排队接收输入
  • process.go / stages.go — 处理管道：记忆召回 → 人格注入 → LLM 调用 → 工具执行 → 输出发送，7 阶段钩子
  • toolcall.go — 工具调度与执行
  • context.go — 上下文管理（预训练词嵌入评分 StaticEmbedder → CosineSimilarity，TF-IDF 回退），自动剪枝低相关性事件
  • LLM 调用通过 Provider 接口抽象，多源自动降级

记忆系统 (internal/memory/)：

  • GraphDB (graph.go) — SQLite，entities + relations 表，BFS 遍历
  • 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

知识库 (internal/knowledge/knowledge.go)：

  • 文件系统目录 knowledge/<name>/content.md
  • TF-IDF 向量搜索，独立于记忆系统的索引实例
  • LLM 通过 knowledge_search / knowledge_create / knowledge_list 三个工具操作

插件系统 (internal/plugin/)：

  • 内置插件：Go init() 自注册，编译进内核
  • 外部插件（v1.0.0 起）：编译为普通 Go 二进制 plugin.bin，内核 spawn 为独立子进程， 经 stdio JSON-RPC（控制面）+ 共享内存段（数据面）+ 事件环（通知面）通信；也支持 Lua 脚本插件 （C ABI 动态库通道 -buildmode=c-shared 已在 v1.0.0 整体删除）
  • 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)：

  • Provider 接口：Name / Chat / ChatStream
  • 唯一实现 LuaAdaptedProvider：所有源都经 Lua 适配脚本做请求/响应变换； 适配器脚本位于 internal/lua/adapters/，每类协议一个 .lua 脚本
  • 内置 10 个适配器：deepseek / openai / anthropic / gemini / mistral / groq / github / kimicode / ollama / server
  • 源（core.llm.sources.<name>.*）由部署时配置，数量不固定，不随内置适配器数绑定

WebUI (internal/plugins/webui/)：

  • 嵌入式 SPA 仪表盘（dashboard.html 通过 //go:embed 打包）
  • REST API：状态查询、配置管理、记忆操作、知识库管理、插件管理
  • 兼容 OpenAI API 格式的 /v1/chat/completions 端点
  • SSE 事件流 /api/v1/chat/events

ClawHub 适配器 (internal/plugins/clawhubadapter/)：

  • 统一加载 OC 插件（Node.js）、Python sidecar、JS sidecar、SKILL 四种插件类型
  • RegistryDispatcher 模式：Tool/Provider/Channel/Stage 注册通知分发
  • ClawHub 市场搜索与安装：clawhubadapter_search / clawhubadapter_npm_install
  • 9 种 Provider 类型映射为 LLM 可用工具（图片生成、搜索、语音等）
  • OC 通道自动注册为 IO 设备，支持文本/文件/图片/音频能力标志

项目状态

核心功能已可运行。插件系统和 SDK 已就绪，可独立开发外部插件。

  • 内置插件：webui / cli / timer / cmd / mcp / agentcli / healthcheck / pluginmgr / clawhubadapter / files / cfgmgr
  • 外部插件示例（homeagent-sdk 仓库 example/，含 Go 和 Lua 两种类型）：qq / files / a2a / ai_image / bili / browser / calendar / editdoc / memo / music / ocr / rss / sanitizer / weather / luademo
  • 打包分发：.hmap 插件包格式，通过 WebUI 安装