mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-09-21 09:28:14 +00:00
9b92a04230
README/架构文档仍在描述 C ABI 动态库加载，与 v1.0.0 实际实现不符。
新用户按文档走会去做 -buildmode=c-shared，产物新内核根本不加载。
README.md / README_EN.md：
- 设计要点补子进程架构段（三面通信、崩溃自愈、真热重载）
- 代码结构 plugin/ 描述：.so 动态加载器 → 子进程加载器
- 项目状态补 v1.0.0 条目（6 类缺陷 + 实测数字），v0.9.0 标注 ABI 已退场
- 新增「下载」章节：三变体对照 + 各平台包格式 + macOS 限制
assets/docs/{zh,en}/ARCHITECTURE.md：
- 四种加载方式表：外部 .so/C ABI → 外部子进程/握手+stdio JSON-RPC
- 加载流程改写为 exec.Command → 继承 fd → 握手 → init → start
- 内置 vs 外部对照表 7 行更新
- 新增「子进程插件的三个通信面」小节，含每个面的选择理由
assets/docs/{zh,en}/OVERVIEW.md：插件系统段落改写
deploy/ 发布脚本三处回归（v0.7.2 的 2c5f9ff 把 package/ 移到
deploy/packaging/ 使目录深度 1→2，但没改相对路径，此后两个版本
的发布都没有二进制资产）：
- build.sh：.syso 按目标平台 hide/restore（trap 兜底），恢复
windows 目标的 CXX，arm64 刻意不带 CXX
- installer.nsi：5 处 ..\build → ..\..\build，PRODUCT_VERSION 可注入
（原先硬编码 0.8.0）
- homeagent.spec：server 变体补装 waiter（control-server 声明了 CLI 却没装）
deploy/scripts/upload_assets.py：release 资产上传（两步签名 URL → OBS
PUT）。放 deploy/scripts/ 而非 scripts/，因为后者在 .gitignore 里。
支持 GITCODE_REPO/ASSET_DIR 环境变量以复用于 SDK 仓。
86 lines
5.4 KiB
Markdown
86 lines
5.4 KiB
Markdown
[English](../en/OVERVIEW.md) | **中文**
|
||
|
||
# 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 遍历召回，蒸馏管道从对话中提取三元组
|
||
|
||
三层递进：上下文 → 冷归档 → 长期图记忆，构成从短期到持久的信息衰减与整合管道。
|
||
|
||
## 它实际做了什么
|
||
|
||
代码位于项目仓库根目录，Go 语言实现。
|
||
|
||
**内核** (`internal/agent/core/`)：
|
||
- `eventloop.go` — 消息循环（`eventLoop`），从 IO 层排队接收输入
|
||
- `process.go` / `stages.go` — 处理管道：记忆召回 → 人格注入 → LLM 调用 → 工具执行 → 输出发送，7 阶段钩子
|
||
- `toolcall.go` — 工具调度与执行
|
||
- `context.go` — 上下文管理（预训练词嵌入评分 StaticEmbedder → CosineSimilarity，TF-IDF 回退），自动剪枝低相关性事件
|
||
- LLM 调用通过 Provider 接口抽象，支持 8 个 LLM 源自动降级
|
||
|
||
**记忆系统** (`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
|
||
- 三种实现：OpenAIProvider（标准 OpenAI API）、OllamaProvider（本地）、LuaAdaptedProvider（Lua 胶水适配）
|
||
- LuaAdapter 位于 `internal/lua/adapters/`，每个 LLM 源对应一个 `.lua` 脚本
|
||
- 内置 8 个适配器：deepseek / openai / anthropic / gemini / mistral / groq / github / ollama
|
||
|
||
**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](https://gitcode.com/JianFeeeee/homeagent-sdk) 仓库 `example/`，含 Go 和 Lua 两种类型）：qq / files / a2a / ai_image / bili / browser / calendar / editdoc / memo / music / ocr / rss / sanitizer / weather / luademo
|
||
- 打包分发：`.hmap` 插件包格式，通过 WebUI 安装
|