# HomeAgent v1.2.x 更新日志

本篇文章用来补上 1.0.0 之后缺失的版本记录。博客上此前最新的更新日志停在 v0.9.0，而内核已经从 0.9.0 走到 **1.2.2**——中间跨了三代架构变动：外部插件子进程化、统一多模态向量空间、共享内存接管数据面。这里按版本逐条补齐。

> **版本编号先说明**：SDK 的版本号跟随内核**中版本**，patch 位恒为 `.0`。所以面向内核 1.2.x 线的 SDK 就是 **1.2.0**，不存在 1.2.1。内核发 patch 只做 bugfix、不碰公开接口，插件不需要跟版。

---

## 一、v1.0.0：外部插件从 C ABI 迁移到子进程

发布日期：2026-09-03。这是首个**不再加载 `.so`/`.dll`** 的版本，与 0.9.x 不兼容——存量外部插件必须用新版工具链重编为 `plugin.bin`。

值得注意的是：**业务代码零改动**。17 个 example 插件的 `plugin.go` 在整个迁移过程中逐字节未变，公开 SDK 接口（`sdk/` 目录）全程冻结。

### 三个面 + 三平台实现

- **控制面**：stdio JSON-RPC（NDJSON 帧），51 个 `core.*` method。整数 method id 平移为字符串常量，版本协商改为握手帧的 `protocol` 字段
- **数据面**：共享内存段，**全部子进程共用一块**。这里有个反直觉的取舍——每插件一段会让「内核 ctx → 段 → 插件改 → 回读 ctx」在多插件场景下退化成副本模型，lost update 会原样复现
- **通知面**：事件环 + 三平台通知机制（Linux eventfd / macOS pipe / Windows Event）
- **平台实现**：Linux 用 memfd 经 `ExtraFiles` 传继承 fd（3=StageContext、4=事件环、5=通知）；macOS 用立即 unlink 的临时文件（无 memfd_create）；Windows 用命名 FileMapping + 命名 Event，名字经环境变量传递

### 消除的 6 类 C ABI 缺陷

| 缺陷 | 原状 | 现状 |
|---|---|---|
| 热重载失效 | Go c-shared 的 ELF `DF_1_NODELETE` 标记让 `dlclose` 成为 no-op，换 `.so` 必须重启 homed；`plgreload` 报成功但跑的还是旧代码 | 换 `plugin.bin` 即生效 |
| 崩溃隔离缺失 | 插件 panic 直接带崩整个 homed | 子进程独立崩溃，内核摘除其注册面并按退避自动重启 |
| stage lost update | C ABI 副本模型让并发改写互相覆盖，实测丢失 35.8~36.8% | 经共享内存段，丢失率 0% |
| cgo 工具超时不可中断 | 日志称「已取消」实际什么都没取消，goroutine 永久卡在 `C.call_invoke_tool` 里，OS 线程线性泄漏（现网累计 26 次） | 整套架构零 cgo，`Process.Kill()` 是真取消 |
| output_send 假成功 | cgo 不可嵌套迫使异步 fire-and-forget，永远返回 `{status:queued}` + `err=nil`，模型收到「已发送」而消息实际未送达（现网 7 天内 2 次） | RPC 同步等真实结果，三态回报 sent/error/unconfirmed |
| 能力断层 | Windows DLL 路径只能看到 3 个 stage 字段且无法写回 | 三平台统一 18 字段全可见可写回 |

### 权限梯度显式化为三道闸

1. **类型层**：`procCore` 用命名字段而非嵌入 `*isdk.PluginSDK`——嵌入会让全部方法被提升，外部插件经类型断言就能拿到 `Supervisor()`/`Tracker()`/`Indexer()`
2. **manifest 层**：插件声明 `capabilities`，未声明的能力组不可用
3. **RPC 边界**：内核 handler 对越权 method 明确拒绝

### 子进程生命周期管理

- **专职 waitLoop**：每子进程一根，是 `cmd.Wait()` 的唯一调用点。不依赖 stdout EOF 判定死亡——插件 fork 的孙子进程（browser 拉 chromium、editdoc 拉 python）继承同一 stdout，插件本体死后 EOF 永不到来
- **集中台账 Supervisor**：握手成功即登记，进程退出即注销。`Host.Close()` 先 `StopAll` 再拆段（顺序反了插件还持有映射而段已 unmap，下次访问就是 SIGBUS）
- **崩溃自愈**：摘注册面（工具 + stage handler + IO 通道）→ 从注册表移除 → 异步退避重启（窗口 5 分钟内最多 3 次，线性退避 1s/2s/3s）。生产实测 kill 到恢复 <1s
- **Linux Pdeathsig 兜底**：homed 被 SIGKILL/OOM 时子进程不滞留为孤儿

### 插件管理器增强

- `plugin_list` 输出运行态：`loaded` / `alive` / `pid` / `crash_count` / `channel`
- 新增 `plugin_status`：全量运行期快照 + dead/unhealthy 汇总。工具调不通时先用它确认插件是否还活着
- 新增 `plugin_restart`：无条件重启单个插件。`plgreload` 按入口文件 hash 增量重载，而进程被 kill 时二进制恰恰没变，它不会动

### 实测数据

- RPC 往返 p50 **24.1µs**
- 完整 stage 往返 **132µs**，其中共享段编解码仅占 3.7µs（2.8%）
- 事件环：5000 次 Publish + 20µs 慢消费者 = **2.29ms**，订阅者 1→8 耗时不变，环溢出仍 O(1)

### 已知限制（不留着不说）

- `SetToolBlocks` 未实现：method 已在协议定义并划入 `CapCore` 能力组，但内核侧 handler 仍返回未实现。C ABI 时代它也是空实现，故不是回归
- **内存超计划目标**：15 个插件进程 RSS 88MB（计划是基线 +29MB）。根因是每插件静态链接整个 Go runtime，15 个不同二进制间无共同物理页可映射（PSS/RSS = 99.9%，基线是 44%）。要压需改成共享 launcher + 业务模块，代价是插件不再自包含
- 事件环零真实负载：机制完备且压测通过，但生产上无任何外部插件调用 `Events().Subscribe`
- Lua 未收敛：`lua_plugin.go` / `dynamic_lua.go` 仍走 gopher-lua 解释器的独立路径
- Windows 无真机验证：交叉编译通过 + 单元测试通过，但无 Windows 测试机

---

## 二、v1.2.0：统一多模态向量空间 + 媒体一等节点 + 共享内存接管数据面

协议升到 **2**，与 1.x **不兼容**：存量外部插件必须用新版工具链重编为 `plugin.bin`。老安装**不会自动获得**新的默认 provider——升级即静默加载 1.8GB 模型不是无副作用的事，需要时显式写 `core.memory.multimodal_space.provider = chineseclip`。

### 主线一：模型中立的统一多模态向量空间

- 内核**不再适配任何具体模型**：新增公共 provider SPI（`pkg/embedding`），只有 `Modality` / `Input{Data,MIME}` / `Info{Dimension,Fingerprint,Modalities}` / `Provider` + 一个名字注册表；模型实现放在 `providers/*`
- **默认启用 Chinese-CLIP ViT-B/16** 作为 text+image 统一空间：512 维、指纹 `cd2a495cf990`、Apache-2.0、独立实测常驻约 1.15GB。文本与图像落在**同一空间**，可直接跨模态比较
- `qwen3vl` provider 保留（2048 维、常驻约 9.4GB），供内存充足或将来需要视频的机器切回
- **能力是数据，不是接口方法**：由 `Info().Modalities` 声明；不支持的模态返回 `ErrUnsupportedModality`——**不允许用别的模型向量冒充**。音频本版本明确不支持
- 代价写在文档里且不回避：CLIP 是双塔对比学习，**纯文本语义弱于 MLLM 型嵌入器**，文本检索仍由既有词向量 / TF-IDF 路径兜底

### 主线二：媒体成为图记忆的一等节点

- 媒体在图数据库里是**一等节点与边**，不再是 `media_refs`、正文 marker 或描述文本三元组的外挂
- **彻底删除「用文本描述式索引图片」这套将就机制**（56 文件 +2637/−2785）
- 记忆块**单层不变量**：Context → Document → Graph 是块的**迁移**，不是复制、也不靠引用保活
- 媒体**没有**独立 GC / 引用计数 / keep-set；删除块即删内容，只有确认无存活块共享该 digest 才删字节

### 主线三：共享内存接管全部数据面（协议 2）

- 工具调用/结果、Cleaner、输入/输出通道、媒体块、文档与知识正文**全部走共享内存**，RPC 只传偏移描述符（SharedRef）。判据是「插件回调要能就地改写的内容有没有留在段里」，不是 payload 大小
- 工具调用按 **funccall 帧模型**：payload 始终在共享内存，内核标定帧，插件按需扩容
- 共享内存由**内核全权管理**，是内部实现、不对插件开发者暴露：插件经 syscall 风格 RPC 申请/归还，SDK 公开 API 仍是 string/map/slice
- fd3 布局改变 → **不支持滚动升级**：内核与全部插件必须同批重建、同批安装

### 主线四：注入行为可声明

- `InjectOptions{NoMemory, ContextPolicy}`：排队注入、中断注入、同步注入都能声明「是否记入记忆」与「是否据此裁剪上下文」，**默认都是否**
- 零值 `InjectOptions` 与旧的三参数方法产出**逐键相同**的 payload——纯追加，存量插件不改一行、不需重编
- 裁剪（`ContextPolicy=prune`）必须显式声明，且裁剪前必须经过插件注册的 Cleaner 得到实际有效内容

### 发行与打包

- 发行版**默认启用** ONNX 向量空间（homed 默认带 `onnxruntime` 构建标签）
- **模型与运行库随 server/full 包发布**：模型 754MB 装到 `/usr/lib/homeagent/models/chinese-clip-vit-b16-onnx/`，ONNX Runtime 24MB 装到 `/usr/lib/homeagent/onnxruntime/`，许可证在 `/usr/share/doc/homeagent/licenses/`。缺任一资产打包直接失败——不生成「默认启用但装完不能用」的假包
- `homed` **放弃 Windows 原生支持**，改走 WSL2（只有 homed；waiter/GUI 不受影响）
- jieba 保留，词库**内嵌进二进制**
- 修掉三个「安装链静默失败」：
  1. `initconfig` 以 `CGO_ENABLED=0` 构建，go-sqlite3 退化成静态桩，而它忽略了所有错误 → 打印凭据、退出码 0、`config.db` 一个字节没写（照凭据登录必然失败且无报错）
  2. 全新安装被误判为「已有配置」而**整体跳过默认值播种** → 装完 0 个插件、随包模型成死重量；判据改为显式标记 `core.internal.seed_version`
  3. deb 的 postinst 查错 unit 路径（`/lib/...` vs 实际 `/etc/...`）导致 `daemon-reload`/`enable` **从未执行**，且 `setup.sh` 的失败被 `|| true` 吞掉

---

## 三、v1.2.1：人格门禁跨通道化 + 状态快照补全（2026-09-12）

面向内核 1.2.0 的 **patch 版**：修 bug + 两个小功能，**无破坏性变更**。插件协议仍是 **2**，v1.2.0 编的插件产物可直接沿用。tag `v1.2.1` → commit `4737aa1`。

### 首启人格门禁：从「只有 WebUI 向导」改成跨通道唯一闸口

v1.2.0 的人格确认只在 WebUI 首启向导里问；走 QQ / CLI / ACP / 邮件进来的人永远见不到那个页面，人格就一直处于「没确认过」的状态。现在：

- 门禁放在**系统提示词构建处**（每轮重建）→ WebUI / QQ / CLI / ACP / 邮件等**所有通道自动覆盖**
- 未确认时提示词要求模型主动询问：默认人格 / 自定义 / 以后再说
- 新增内核内置工具 **`persona_set`**（`mode=default|custom|later`，自定义时带 `content`），模型拿到答复后落库并打一次性标记（`core.internal.persona_initialized`），之后不再追问
- 落库逻辑与 WebUI 向导**共用同一份实现**（`internal/config`），不再两套语义各自漂移
- 非法输入（未知 mode / 自定义为空）在打标记**之前**拒绝——否则标记置位、向导被跳过，用户再没机会设

### healthcheck_kernel 现在能回答「内核版本号」与「ONNX 是否启用」

状态快照新增 `onnx` 段：

```json
"onnx": {"enabled": true, "provider": "chineseclip", "dim": 512,
         "fingerprint": "cd2a495cf990…", "modalities": ["text", "image"]}
```

- 判据是 provider **真正打开且元数据合法**，不是「配置里写了 provider」（后者在模型缺失时也为真）
- 未启用时给出**具体原因**：`未配置统一向量空间 provider（走词嵌入/TF-IDF 回退路径）` 或 `打开失败: embedding: unknown provider "xxx"`
- 内核版本号 / 提交 / 构建时间在同快照的 `build` 段

### 修复：healthcheck_kernel 在知识库为空时会让内核 panic

状态聚合函数的 knowledge 参数是**接口**类型，`(*knowledge.Store)(nil)` 塞进接口后判断仍为真 → 调用 `List()` 直接 panic，而 healthcheck_kernel 正走这条路径。已按具体指针判空后再赋给接口，并加刻画测试钉住成因。

### 验证

- 隔离验收 `ACCEPTANCE=PASS`（解包真实 server 包 → 按 postinst 顺序执行 setup.sh → 冷启动 → 真实 HTTP 对话）
- 发布回归门 **5/5**（200 篇陈旧向量迁移落盘 512 维 / 重启 **0 重算** / 中断后补齐 300 篇 / 媒体 30/30 写回 / 坏块不污染）
- 端到端：人格门禁 **9/9**；状态报告 **7/7**
- 现网部署 13 项后置验证全绿：`source_url` 出现（AGPL §13 生效）、插件 33 目录 16 进程无缺失、16 个协议 2 握手、真实对话正常、fatal/panic 0、`dense_fp` 487/487 篇且启动重算 0 篇

---

## 四、v1.2.2：知识库检索的排序质量（当前版本）

发布时间：2026-09-12。**bugfix 版本**，无破坏性变更：插件协议仍为 **2**，v1.2.0/v1.2.1 编译的插件产物可直接沿用，无需重编。

此前知识库检索**基本不可信**（实测真实知识库 33 条）：

- 自检索 top-1 只有 **5/33 = 15%**，MRR **0.271**，前两名分差平均 **0.013**（≈噪声）
- 查询词若全在停用词表里（例如「最近更新」），稠密向量为零 → **什么都搜不到**

根因（先量后改）：词向量取平均后各向异性严重，所有文档挤在语料均值方向附近，相似度落在 0.6~0.75 的窄带里，几乎没有区分度；另外候选阈值被写死为 0.05（那是给稠密路标定的，词向量余弦通常 0.3~0.9），而 **TF-IDF 余弦量级只有 0.0~0.2** —— 词法路的有效候选会被**静默砍掉**。

改法：检索改为**稠密（词向量）+ 词法（TF-IDF）两路融合**，各自按查询内最大值归一化后加权（权重 0.5，由真实知识库上的权重扫描确定）；候选阈值改为按向量空间可设（默认仍是 0.05）。索引维护也从「无追踪 goroutine 写文件」改为持锁就地 flush。

效果（现网真实查询，部署前 → 部署后）：

| 查询 | v1.2.1 | v1.2.2 |
|---|---|---|
| 首启人格门禁 | openharmony 噪声条目 | **changelog_v1.2.1** |
| 插件怎么开发和部署 | homeagent_identity | **plugin_dev_build** |
| 最近更新 | **（无结果）** | 有结果（但 top-1 仍非最规范条目，见下） |
| 隐私政策 | privacy_policy ✓ | privacy_policy ✓ |

**尚未到位**：纯停用词类查询（如「最近更新」）现在有结果了，但 top-1 不是最该命中的条目；这类查询要让规范条目排第一，需要标题/字段级加权，本轮未做。

### 其它

- 测试改进：真实插件产物先校验平台再执行，错误平台给出可读提示与重建命令（此前会抛误导性的 `exec format error`）
- 打包脚本：`SHA256SUMS` 改为只列本批产物且用平铺名（此前会带上历史版本文件名）

---

## 五、升级步骤

```bash
sudo dpkg -i homeagent-server_1.2.2_amd64.deb   # 或 full 包
sudo systemctl restart homeagent
sha256sum -c SHA256SUMS
```

- **从 1.2.0/1.2.1 升级：插件不用重编**（协议 2 未变）
- **从 0.9.x 及更早升级：必须重编全部外部插件**（1.0.0 换掉 C ABI、1.2.0 又升了协议）
- 首次启动会一次性重算文档向量；v1.2.0 已修「迁移不落盘」，此后再启动为 **0 重算**
- 若想启用统一多模态向量空间，显式写 `core.memory.multimodal_space.provider = chineseclip`，改配置后需重启进程生效
- 人格若来自 `personal/personal.md`，1.2.1 起会**告警提示其中含版本号字面量或已退场机制词**（那类表述会随版本腐坏）

---

## 六、这几代变动的共同线索

回头看 0.9.0 → 1.2.2 这段路，能拎出一条主线：**把「将就」逐个换成「明确」**。

- 插件隔离从「靠纪律」换成「靠进程边界」——崩溃不再带崩内核，超时是真取消
- 记忆的媒体支持从「用文本描述图片」换成「媒体是一等节点」
- 向量空间从「内核适配具体模型」换成「模型是 provider，能力是数据」
- 注入行为从「隐式默认」换成「显式声明」
- 插件运行态从「加载了没」换成「alive / pid / crash_count 三态可见」

代价也写在同一份文档里：内存没压到计划目标、事件环没有真实负载、Lua 路径还没收敛。这些都不藏着。

---

项目地址：[gitcode.com/JianFeeeee/HomeAgent](https://gitcode.com/JianFeeeee/HomeAgent)
SDK 地址：[gitcode.com/JianFeeeee/homeagent-sdk](https://gitcode.com/JianFeeeee/homeagent-sdk)
当前版本：v1.2.2（commit `e803e77`）｜SDK 1.2.0｜插件协议 2


HomeAgent v1.2.x 更新日志（1.0.0 → 1.2.2）

> **版本提示**（写作于 v0.9.0）
>
> 本文记录的 **C ABI v2 / `plugin.so` / `invoke_stage`** 这套机制在 **v1.0.0 已整体退场**：
> 外部插件改为「子进程 + stdio JSON-RPC + 共享内存」，**子进程 RPC 协议版本 2**（v1.2.0 起），
> 产物由 `plugin.so` 改为 `plugin.bin`，工具链 `plugindev` 已更名 **`hmapdev`**。
> 文中提到的「ABI 版本号对齐内核版本」也随之取消。
>
> 版本现状请看 →《HomeAgent v1.2.x 更新日志（1.0.0 → 1.2.2）》。

# HomeAgent v0.9.0 更新日志

日期：2026-08-15

HomeAgent v0.9.0 正式发布！本次版本核心是 **C ABI v2：外部插件 Stage 写回**，同时带来 ABI 版本对齐、Lua 插件写回、插件生态全面重建等一系列更新。

---

## 🎯 C ABI v2：外部插件 Stage 写回（核心变更）

- `invoke_stage` 增加第 3 参数 `result`（`char**`），外部插件在 Stage 回调中修改 StageContext（RawMessage / LLMText / FinalText / Response / ToolResults / ToolCalls / UserID / GroupID / NoMemory）后可回传，内核 `applyStageResult` 同步写回
- 内核 `CORE_REGISTER_STAGE` handler 接收插件返回值并应用
- 对应 SDK `plugindev` 模板：`go_invoke_stage` 增加 resultOut 输出，新增 `fillStageContext` / `stageContextWritable` 辅助

## 🔢 ABI 版本对齐核心版本号（不再独立数字编码）

- 标识层：`ABIVersion = "0.9.0"`（字符串 semver，与内核 `Version` 同值）
- 协商层：`CABINum = 900`（`major*100 + minor` 派生整数，供 C 结构体 int 字段）
- 映射：v0.8.x → 800，v0.9.x → 900；patch 演进不影响 ABI
- 兼容：`CABINumMin = 1`，旧工具链插件（整数 version 1/2）仍可加载（仅缺写回能力）

## 🐛 Bug 修复

- 移除 `tryLoadSO` 的 Go `plugin.Open` fallback：本项目插件统一为 c-shared，对 c-shared .so 调用 Go plugin.Open 会 fatal（no plugin module data），直接返回 C ABI 错误
- 工具循环 zen 兼容补位误伤首轮 system 上下文：仅当尾部消息为 assistant/tool 时才补 user 占位
- WebUI 配置保存：整数型 float64（如 QQ 号）规范化为 int64，避免科学计数法（2.198972886e+09）存库

## 🧠 系统提示词增强

- 明确「消息不会自动发送到对话来源通道」，核心不做自动路由
- 区分同步通道（webui/cli/终端：直接返回文本送达）与异步通道（qq/wechat：必须调用 output_send__{通道} + 正确 meta）
- 引导优先当前输入通道回复，跨通道追问先回忆上次上下文

## 🟢 Lua 插件 Stage 写回

- `makeStageHandler` 以引用 table 传 ctx，Lua handler 修改的字段同步写回内核 StageContext
- 新增 `applyLuaStageResult`，测试 `TestLuaStageWriteback` 验证 on_input/post_action 写回

## 🔌 插件生态

- 全部 17 个外部插件以新 ABI（900）重建并经 pluginmgr 内核接口重装（remove → install）
- qq 插件：parseIDList 兼容科学计数法历史坏值（防御 WebUI 旧数据）
- sanitizer 示例增强：全链路脏字节/ANSI/思维泄漏清洗（OnInput + AfterToolcall + PostAction）

## 📋 其他

- README 项目状态更新至 v0.9.0；SDK 与核心 meta 同步

---

**项目地址**：[gitcode.com/JianFeeeee/HomeAgent](https://gitcode.com/JianFeeeee/HomeAgent)
**SDK 地址**：[gitcode.com/JianFeeeee/homeagent-sdk](https://gitcode.com/JianFeeeee/homeagent-sdk)

HomeAgent v0.9.0 更新日志——C ABI v2 外部插件 Stage 写回

# 手把手部署 HomeAgent——从 Release 二进制开始（v1.2.x 版）

本文配套 **内核 1.2.2（commit `e803e77`）/ SDK 1.2.0 / 子进程 RPC 协议 2**。

如果你读过旧版（v0.9.0 时期）的部署文章，请注意三个已经变化的点：**发行包现在自带模型与运行库**、**`homed` 放弃了 Windows 原生支持**、**外部插件协议升到 2（与 1.x 不兼容）**。旧版里那些以 v0.9.0 为准的版本号、Release 链接和插件产物格式都不再适用。

---

## 第一步：选平台和包变体

发行在 GitCode Release：

- HomeAgent 主仓库：https://gitcode.com/JianFeeeee/HomeAgent/releases
- SDK 仓库：https://gitcode.com/JianFeeeee/homeagent-sdk/releases

### 三种变体

- **Full** — homed + waiter + GUI，桌面端适用
- **Server** — homed + waiter，服务器 / VPS 无头运行
- **Client** — waiter + GUI，远程连接另一台机器的 homed

长期部署选 **Server**。服务器上跑 agent 不需要 GUI，也不需要把桌面依赖拉进来。

### Linux 包格式

- **.deb** — Debian / Ubuntu / Linux Mint，`dpkg -i` 安装，带 postinst（会做 daemon-reload 与 enable）
- **.rpm** — Fedora / RHEL / CentOS，`dnf install` 安装
- **.tar.gz** — 通用，解压后手动放置二进制

### 关于 Windows

**`homed` 已放弃 Windows 原生支持，改走 WSL2。** 这是刻意的收敛而非遗漏——协议 2 的统一共享内存区未移植 Windows。waiter / GUI 不受影响，仍可原生运行。

在 WSL2 里按 Linux 的方式部署即可：

```bash
# WSL2 (Ubuntu) 内
sudo dpkg -i homeagent-server_1.2.2_amd64.deb
sudo systemctl restart homeagent
```

> WSL2 的 systemd 需要在 `/etc/wsl.conf` 里开启：`[boot]` 段加 `systemd=true`，然后 `wsl --shutdown` 重启。

---

## 第二步：安装

### Debian / Ubuntu

```bash
wget https://gitcode.com/JianFeeeee/HomeAgent/releases/download/v1.2.2/homeagent-server_1.2.2_amd64.deb
sudo dpkg -i homeagent-server_1.2.2_amd64.deb
sudo apt-get install -f    # 缺依赖时装
```

安装后主要落点：

```
/usr/bin/homed                          核心守护进程
/usr/bin/waiter                         命令行客户端
/usr/bin/initconfig                     配置初始化工具
/etc/systemd/system/homeagent.service   systemd 服务单元
/var/lib/homeagent/                     数据目录
/usr/lib/homeagent/models/              随包模型（754MB）
/usr/lib/homeagent/onnxruntime/         ONNX Runtime（24MB）
/usr/share/doc/homeagent/licenses/      第三方许可证
```

### Fedora / RHEL

```bash
sudo dnf install homeagent-server-1.2.2-1.x86_64.rpm
```

### 通用 Linux（tar.gz）

```bash
tar xzf homeagent-server_1.2.2_linux_amd64.tar.gz
sudo cp homeagent-1.2.2-linux-amd64/usr/bin/* /usr/local/bin/
```

### 校验产物完整性

```bash
sha256sum -c SHA256SUMS
```

`SHA256SUMS` 只列本批产物、用平铺文件名（此前版本会带上历史版本的文件名，容易对不上）。

---

## 第三步：随包模型与 ONNX Runtime（v1.2.0 起的新变化）

这是 v1.2.0 之后部署流程里**最需要知道的一件事**：发行包**不再依赖你另外下载模型**。

```
/usr/lib/homeagent/models/chinese-clip-vit-b16-onnx/    754MB
/usr/lib/homeagent/onnxruntime/                          24MB
/usr/share/doc/homeagent/licenses/                       许可证
```

- 发行版**默认启用** ONNX 向量空间（homed 默认带 `onnxruntime` 构建标签）
- **缺任一资产则打包直接失败**——不会生成「默认启用但装完不能用」的假包
- 模型是 **Chinese-CLIP ViT-B/16**：512 维、Apache-2.0、常驻约 1.15GB，文本与图像落在同一空间

**老安装不会自动获得新的默认 provider**（有意设计）：升级即静默加载 1.8GB 模型不是无副作用的事。需要时显式开启：

```bash
settings set core.memory.multimodal_space.provider chineseclip
sudo systemctl restart homeagent    # 改配置后需重启进程生效
```

想确认它到底有没有真正启用：

```bash
# waiter 里问内核
waiter -chat "healthcheck_kernel" -api-key "<你的 api_key>"
```

快照里的 `onnx` 段会给出答案：

```json
"onnx": {"enabled": true, "provider": "chineseclip", "dim": 512,
         "fingerprint": "cd2a495cf990…", "modalities": ["text", "image"]}
```

判据是 provider **真正打开且元数据合法**，不是「配置里写了 provider」。未启用时会给出具体原因，例如 `未配置统一向量空间 provider（走词嵌入/TF-IDF 回退路径）` 或 `打开失败: embedding: unknown provider "xxx"`。

同一个快照的 `build` 段里有**内核版本号 / 提交 / 构建时间**——被问「现在是什么版本」时以它为准。

---

## 第四步：首次启动

```bash
homed -data /var/lib/homeagent -webui :8080
```

首次启动会在日志里打印 bootstrap 凭据，**务必保存**：

```
[webui] bootstrap password generated for user admin: ...
[webui] bootstrap api_key generated: ...
```

正常启动的最后一行：

```
[homed] kernel ready, waiting for plugin IO...
```

以及插件与工具计数：

```
[homed] stage host ready with NN registered tools
```

### v1.2.0 修掉的三个「安装链静默失败」

旧版部署文章里有一整节在讲 «0 registered tools» 的排查，根因是 `core.plugin.dir` 缺失。**这个坑从 v1.2.0 起已经在安装链里堵上了**，但知道来龙去脉仍有价值：

1. **`initconfig` 是空操作**：它以 `CGO_ENABLED=0` 构建，go-sqlite3 退化成静态桩，而它**忽略了所有错误** → 打印凭据、退出码 0、`config.db` 一个字节没写。照凭据登录必然失败，且没有任何报错
2. **全新安装被误判为「已有配置」**而**整体跳过默认值播种** → 装完 0 个插件、随包模型成了死重量。判据已改为显式标记 `core.internal.seed_version`
3. **deb 的 postinst 查错 unit 路径**（`/lib/...` vs 实际 `/etc/...`），导致 `daemon-reload` / `enable` **从未执行**；且 `setup.sh` 的失败被 `|| true` 吞掉

所以：**用官方包 + 官方安装流程**，这三类问题不会再遇到。只有当你手工操作 `config.db`、跳过后置脚本时，才需要回到旧式排查。

### 如果确实遇到了（手工场景）

```bash
# 检查关键默认值是否存在
sqlite3 /var/lib/homeagent/config.db \
  "SELECT key, value FROM config WHERE key IN
   ('core.plugin.dir','core.daemon.data_dir','core.internal.seed_version');"
```

缺失时补齐（或删掉 `config.db` 重启，重新走一遍播种）：

```bash
sqlite3 /var/lib/homeagent/config.db \
  "INSERT OR IGNORE INTO config (key,value) VALUES ('core.plugin.dir','/var/lib/homeagent/plugins');"
sqlite3 /var/lib/homeagent/config.db \
  "INSERT OR IGNORE INTO config (key,value) VALUES ('core.daemon.data_dir','/var/lib/homeagent');"
```

**路径显示为相对路径**（如 `memory/text` 而不是 `/var/lib/homeagent/memory/text`）也是同一类症状——`core.daemon.data_dir` 没设上。

### 注册为系统服务

```bash
sudo systemctl enable --now homeagent
sudo journalctl -u homeagent -f          # 实时日志
```

---

## 第五步：配置 LLM

HomeAgent 需要 LLM API 才能工作。

### 方式一：WebUI 图形界面（推荐）

浏览器打开 `http://服务器IP:8080` → 用 `admin` + 日志里的 bootstrap 密码登录 → 设置页面填 `core.llm.api_key`。

### 方式二：环境变量

```bash
LLM_API_KEY=sk-xxx homed -data /var/lib/homeagent
```

也支持 `DEEPSEEK_API_KEY` 作为后备。

### 方式三：waiter 命令行

```bash
waiter -socket /var/lib/homeagent/cli.sock
# 交互模式内：
# /settings set core.llm.api_key sk-xxx
```

### 注意：直接写 config.db 时必须同时注册 LLM 源

跳过 WebUI 直接用 sqlite3 插配置时，**必须把 provider 与 sources 一起写**，否则 `cfg.LLM.Sources` 为空列表，providerMgr 返回 nil，agent 无法调用 LLM：

```bash
sqlite3 /var/lib/homeagent/config.db "INSERT OR REPLACE INTO config (key,value) VALUES ('core.llm.provider','yourprovider');"
sqlite3 /var/lib/homeagent/config.db "INSERT OR REPLACE INTO config (key,value) VALUES ('core.llm.sources.yourprovider.base_url','https://api.example.com/v2');"
sqlite3 /var/lib/homeagent/config.db "INSERT OR REPLACE INTO config (key,value) VALUES ('core.llm.sources.yourprovider.model','your-model');"
sqlite3 /var/lib/homeagent/config.db "INSERT OR REPLACE INTO config (key,value) VALUES ('core.llm.sources.yourprovider.api_key','sk-xxx');"
sqlite3 /var/lib/homeagent/config.db "INSERT OR REPLACE INTO config (key,value) VALUES ('core.llm.sources.yourprovider.adapter','openai');"
```

日志里看到 `sources=0` 就是这个问题：

```
[homed] main agent started, model=... base=... sources=0 adapters=8
#                                                     ^ 表示 LLM 不可用
```

---

## 第六步：连接 waiter

### 本地连接

```bash
waiter
```

自动按顺序查找 socket：`XDG_RUNTIME_DIR/homeagent/cli.sock` → `~/.homeagent/cli.sock` → 数据目录。手动指定加 `-socket`。

### 远程连接

```bash
waiter -remote http://服务器IP:8080 -api-key "<你的 api_key>"
```

### 单条命令

```bash
waiter -chat "/status" -api-key "<你的 api_key>"
```

### 内置命令

```
/help              显示帮助
/status            查看系统状态
/kernel            内核 JSON 快照
/settings          查看/修改配置
/plugin list       已加载插件
/memory query <t>  查询图记忆
/chat <text>       发送消息给 Agent
直接输入文本        自动发给 Agent
```

---

## 第七步：插件——协议 2 的关键注意事项

这一节是升级/部署时最容易吃亏的地方。

### 协议 2 与 1.x 不兼容

- **从 1.2.0/1.2.1 升级**：插件**不用重编**（协议 2 未变）
- **从 0.9.x 及更早升级**：**必须重编全部外部插件**——1.0.0 换掉了 C ABI（`.so` → `plugin.bin`），1.2.0 又把协议升到 2
- **fd3 布局在 1.2.0 改变 → 不支持滚动升级**：内核与全部插件必须**同批构建、同批安装**

### 插件是怎么"活"的（v1.0.0 起的子进程架构）

```
内核 (homed)
   │ stdio JSON-RPC（控制面，51 个 core.* method）
   │ 共享内存段（数据面，全部子进程共用一块）
   │ 事件环（通知面）
   ▼
插件子进程 (plugin.bin)
```

部署上关心的三件事：

1. **崩溃隔离**：插件 panic 只崩自己，内核摘除其注册面并按退避自动重启（窗口 5 分钟内最多 3 次）。生产实测 kill 到恢复 <1s
2. **热重载真生效**：旧版换 `.so` 因 ELF `DF_1_NODELETE` 标记导致 `dlclose` 是 no-op，必须重启 homed。现在换 `plugin.bin` 即生效
3. **超时是真取消**：旧版 cgo 工具超时只打印"已取消"，goroutine 永久卡死、OS 线程线性泄漏（现网累计 26 次）。现在零 cgo，`Process.Kill()` 回收全部资源

### 插件管理命令

```bash
# HTTP API 安装（pluginmgr，默认 127.0.0.1:9876）
curl -X POST http://127.0.0.1:9876/plugins \
  -H "Content-Type: application/json" \
  -d '{"path":"/path/to/plugin_linux_amd64.hmap"}'

curl http://127.0.0.1:9876/plugins                     # 列表
curl http://127.0.0.1:9876/plugins/<name>              # 详情
curl -X DELETE http://127.0.0.1:9876/plugins/<name>    # 卸载
```

三个内核内置工具要分清楚用途：

| 工具 | 用途 |
|---|---|
| `plugin_list` | `loaded` / `alive` / `pid` / `crash_count` / `channel` |
| `plugin_status` | 全量运行期快照 + dead/unhealthy 汇总。**工具调不通时先跑它** |
| `plugin_restart` | 无条件重启单个插件（进程已死、或换了二进制要立即生效） |
| `plgreload` | 扫描目录变更，按入口文件 hash **增量**重载 |

> `plgreload` 只在入口文件内容真变了才动；进程被 kill 时二进制没变，它不会重启——这种情况用 `plugin_restart`。

### 插件开发与部署

插件怎么开发、`hmapdev` 工具链怎么用、`plg.json` 与 `.hmap` 产物长什么样，见配套文章：《从零开发 HomeAgent QQ 插件（v1.2.x / hmapdev 工具链）》。

---

## 第八步：升级到 1.2.2

```bash
sudo dpkg -i homeagent-server_1.2.2_amd64.deb
sudo systemctl restart homeagent
sha256sum -c SHA256SUMS
```

升级后的预期行为：

- 首次启动会**一次性重算文档向量**；v1.2.0 已修「迁移不落盘」，此后再启动为 **0 重算**
- 插件协议仍是 2，**从 1.2.x 升上来不用重编**
- 人格文件若来自 `personal/personal.md`，1.2.1 起会**告警提示其中含版本号字面量或已退场机制词**（那类表述会随版本腐坏）

**v1.2.2 修了什么**：知识库检索此前"基本不可信"（真实知识库 33 条，自检索 top-1 仅 15%，MRR 0.271；查询词全为停用词时**什么都搜不到**）。现在改为**稠密（词向量）+ 词法（TF-IDF）两路融合**，各自按查询内最大值归一化后加权（权重 0.5）。

---

## 第九步：数据目录结构

```
/var/lib/homeagent/
├── config.db              SQLite 配置库
├── adapters/              LLM 适配器（Lua 脚本，编译期内置）
├── plugins/               外部插件安装目录
├── memory/
│   ├── graph.db           图记忆（实体 + 关系 + 句子溯源）
│   ├── context.json       上下文窗口
│   ├── raw/               原始对话缓冲
│   └── text/              文本记忆（JSONL）
├── knowledge/             知识库
├── agentfs/               Agent 工作目录
├── snapshots/             状态快照
├── changesets/            变更追踪
├── log/                   日志
└── cli.sock               Unix socket
```

---

## 常见问题快速排查

**`GLIBC_2.38 not found`** — homed 在较新的发行版上编译。用较新的系统，或用 `LD_LIBRARY_PATH` 隔离新版 libc：

```bash
#!/bin/bash
export LLM_API_KEY="your-api-key"
exec /opt/homeagent-libs/lib64/ld-linux-x86-64.so.2 \
  --library-path /opt/homeagent-libs/usr/lib/x86_64-linux-gnu:/opt/homeagent-libs/lib64 \
  /usr/bin/homed "$@"
```

**`0 registered tools` / 路径是相对的** — 手工操作 config.db 导致默认值未播种。补齐 `core.plugin.dir`、`core.daemon.data_dir`，或删掉 `config.db` 重启。

**`sources=0`** — LLM 源未注册，需写全 `core.llm.sources.*` 系列配置。

**WebUI 访问不了** — 检查 `-webui :8080` 参数与防火墙 / 端口转发。

**waiter 找不到 socket** — 手动指定 `waiter -socket /var/lib/homeagent/cli.sock`。

**日志没有 bootstrap 密码** — 不是首次启动。删掉 `config.db` 重启可重新生成。

**插件工具调不通** — 先跑 `plugin_status` 看进程是否 `alive`；`alive=false` 时看 `crash_count`，达上限就用 `plugin_restart`。

**模型似乎没生效** — 跑 `healthcheck_kernel`，看 `onnx.enabled` 与原因字段。注意老安装**不会自动启用**新 provider，需要显式设 `core.memory.multimodal_space.provider = chineseclip`。

**版本号到底是多少** — 别凭记忆，看 `healthcheck_kernel` 的 `build` 段（version / commit / build_time）。

---

## QEMU/KVM 虚拟化部署

```bash
# QEMU 启动时加端口转发
-netdev user,id=net0,hostfwd=tcp::2222-:22,hostfwd=tcp::8080-:8080
```

```bash
# 宿主机访问
# http://127.0.0.1:8080/     → 虚拟机内 WebUI
# ssh -p 2222 user@127.0.0.1 → 虚拟机 SSH

# 传包进虚拟机
scp -P 2222 homeagent-server_1.2.2_amd64.deb user@127.0.0.1:/tmp/
```

---

## 总结

```
sudo dpkg -i homeagent-server_1.2.2_amd64.deb && sudo systemctl restart homeagent
```

从 Release 部署在 1.2.x 上比旧版简单了：装完即带模型与 ONNX Runtime，模型随包发布、默认启用；三个安装链静默失败已在打包与安装脚本里堵上；插件运行态（alive / pid / crash_count）直接可见。

仍要留心的三件事：

1. **协议 2 与 1.x 不兼容** — 从 0.9.x 及更早升级必须重编全部外部插件，且不能滚动升级
2. **老安装不自动启用新 provider** — 想用统一多模态向量空间得显式配一次
3. **`homed` 不再支持 Windows 原生** — 用 WSL2

---

项目地址：https://gitcode.com/JianFeeeee/HomeAgent
SDK 地址：https://gitcode.com/JianFeeeee/homeagent-sdk
适用版本：内核 v1.2.2（commit `e803e77`）｜ SDK 1.2.0 ｜ 插件协议 2


手把手教你部署 HomeAgent——从 Release 二进制开始（v1.2.x 版）

> **版本提示**（写作于 v0.9.0）
>
> 本文的架构对比与数据停在 v0.9.0，其中两条已被后续版本改写：
> ① 外部插件不再是 **C ABI `dlopen .so`**，改为**子进程 + 共享内存**（v1.0.0）；
> ② 记忆系统新增**统一多模态向量空间**（Chinese-CLIP，512 维，文本与图像同一空间），媒体成为图记忆的**一等节点**（v1.2.0）。
> 代码规模、插件数量等数字也已增长，请以运行时快照为准。
>
> 最新架构与版本请看 →《HomeAgent v1.2.x 更新日志（1.0.0 → 1.2.2）》。

我是 jianf，HomeAgent 的作者。这篇文章讲讲我为什么要写这个东西，以及它的设计思路。

## 起因：被 OpenClaw 逼的

2025 年底我开始深度使用 OpenClaw，当时觉得这个概念很酷——把 agent 接入群聊，让机器人能调用工具、有记忆、能持续运行。但实际用下来，三个问题让我越来越难受。

### 记忆系统约等于没有

OpenClaw 的记忆系统就是一个 root-memory-files.ts 文件。我用了一个月，发现它根本记不住任何跨 session 的东西——你和它在群 A 聊过的事情，到群 B 它就完全不记得了。它的"记忆"就是简单的 prompt 拼接，不是真正的持久化存储。

我需要的是一个能跨 session、跨时间维度的记忆系统。不仅仅是"记住最近 N 轮对话"，而是短期工作记忆、中期归档记忆、长期知识图谱。OpenClaw 一个都没做到。

### 频繁崩溃

OpenClaw 跑在 Node.js 上，430k 行 TypeScript，进程中加载了几十个 npm 包。时不时一个未捕获的异常就把整个 Gateway 带走了。我不止一次早上醒来发现机器人掉了，群友在问"怎么 bot 又死了"。

如果你要做的是一个 7x24 小时的守护进程，稳定性必须是架构设计的核心约束，而不是事后补救。

### 多 session 的割裂感

OpenClaw 的设计是：每个群聊就是一个独立 session，每个 session 有自己独立的上下文。听起来合理？实际上用起来特别奇怪。

比如我在群 A 和群 B 都跟同一个 bot 聊天。我问群 A "帮我查一下昨天的会议记录"，bot 在群 A 的 session 里搜不到，因为会议记录是在群 B 讨论的。同一个 bot，同一个用户，但因为 session 隔离，信息完全不互通。bot 在群 A 记住的性格特征，到了群 B 就忘了。

我想要的是一个真正的 agent——它能跨群聊、跨频道地认识用户、记住事情、保持一致的个性和知识。session 只应该作为事件来源的标签，而不应该是记忆的隔离边界。

## 核心设计：核心域与应用域分离

想清楚这三个痛点之后，我开始设计 HomeAgent。最核心的决策是让内核不做网络 IO——没有 http.Get，没有数据库直连。内核只做三件事：LLM 编排、三层记忆管理、知识检索。所有与外部世界的交互，全部由插件承载。（注：内核 Context 层仍会读写 context.json 做持久化，但不做任何网络请求。）

拿 QQ 插件举个例子——它注册了 qq_get_message、qq_send_file、qq_group_manage 等十几个工具，每个工具的参数用 JSON Schema 描述。当 LLM 决定调用某个工具时，内核只负责传递参数和结果，不碰任何网络或文件 IO。

这直接解决了 OpenClaw 的安全问题。在 OpenClaw 里，pi agent runtime 既做推理又做 IO，一个 prompt injection 就能让 agent 读写任意文件。在 HomeAgent 里，prompt injection 最多控制某个插件，永远碰不到内核的记忆数据。

## 三层记忆

HomeAgent 的记忆系统是我花时间最多的部分：

- **Context 层**：工作窗口，用 StaticEmbedder + TF-IDF 余弦相似度裁剪上下文。保护最近 10 条对话，保留跟当前输入最相关的 topK 条。被裁剪的自动下沉到 Document 层。
- **Document 层**：归档记忆，JSON 文件存储。支持向量相似度检索，被召回的记忆会重新注入到 Context 层。冷数据超过 72h 且访问次数不超过 2 次的，自动下沉到 Graph 层。
- **Graph 层**：SQLite 图数据库，持久化实体关系和语义记忆。每 30 分钟的心跳管道自动从原始对话中蒸馏三元组（可配置）。支持 BFS 遍历、关键字搜索、session 过滤。还带一个实体合并检测——发现两个名字相似度超过 0.75，会交给 LLM 判断是否应该合并。

三个层的核心设计思想是：数据永远向更持久的层级流动，但在被需要时可以随时回召。

## session 只是标签，不是边界

与 OpenClaw 不同，HomeAgent 不按 session 隔离记忆。session 只是 GraphDB 中关系的一个属性标签——用来追溯"这条知识是在哪个对话里学到的"。所有 session 共享同一个 context 窗口和同一个知识图谱。

这意味着你在 QQ 群跟 bot 说过"我喜欢喝冰美式"，到微信群它记得。你在私聊教了它你的名字，到群里它也能正确称呼你。

## 插件设计：以 QQ 插件为例

QQ 插件是展示 HomeAgent 插件设计最好的例子。它连接 NapCat（QQ 协议实现）和 HomeAgent 内核。

### 插件启动时做什么

插件在 Start() 中做了四件事：

1. 注册配置项：14 个设置项（监听地址、NapCat URL、白名单、文件目录等），用户通过 WebUI 或 pluginmgr API 修改，无需改代码
2. 注册输出通道：调用 RegisterOutputChannel 声明这个插件可以处理文字、图片、文件、语音四种输出类型。内核的 output_send 工具通过通道名路由回复
3. 注册工具：15 个工具，每个都带有 JSON Schema 描述的完整参数定义。包括消息查询、文件发送、群管理、好友管理、文档读取、视频下载等
4. 注册 stage 钩子：RegisterStage(StageBeforeToolcall, handler, StageScopeOwnTools) —— 只拦截自己的工具调用，在 tool call 执行前做安全检查

### 消息处理流程

当 QQ 群里有人 @bot 时，NapCat 通过 webhook 把消息 POST 到 QQ 插件。插件解析消息后调用 InjectInterruptText()，将一条中断消息注入 agent 管道：

```
来自张三的（技术交流群）群聊消息，通过 id 42 使用 qq_get_message 工具获取消息正文。
必须使用 output_send__qq 工具回复该群聊，系统不会自动发送回复
```

注意这里的设计：插件只负责把消息推进管道，回复由 LLM 决定是否调用 output_send 工具。内核不自动回复任何消息。这样 LLM 可以判断什么时候该回复、什么时候不该回复。

### 安全设计

QQ 插件在 before_toolcall 阶段做了三层安全检查：

- 高危操作确认：踢人、禁言、退群、撤回消息等操作必须显式传 confirm=true，否则插件拒绝执行
- 白名单策略：私聊和群聊各自可以设为 open/allowlist/disabled，白名单外的来源一概忽略
- 管理员标记：管理员的消息附带"【重要！老大消息】"前缀，LLM 会优先处理

这些全在插件层完成，不依赖 LLM 的纪律性。即使 prompt injection 骗过了 LLM，插件层的安全检查依然会拦截。

### 文件插件的沙箱模式

文件插件展示了另一个安全模式：沙箱路径校验。每个文件操作都经过 resolvePath() 函数，确保没有路径逃逸：

```
func (p *Plugin) resolvePath(userPath string) (string, error) {
    if !filepath.IsAbs(userPath) {
        userPath = filepath.Join(p.filesDir, userPath)
    }
    abs, _ := filepath.Abs(userPath)
    base := filepath.Clean(p.filesDir)
    if base != "/" && !strings.HasPrefix(abs, base+string(filepath.Separator)) {
        return "", fmt.Errorf("path outside sandbox: %s", userPath)
    }
    return abs, nil
}
```

插件根目录通过配置 plugin.files.dir 设定，可以限制 LLM 只能在某个沙箱目录内操作文件。

## 技术选型：为什么是 Go

我选 Go 有几个原因：

1. 单二进制部署：go build 出来一个文件，丢到服务器就能跑。没有 node_modules，没有 pip install
2. 静态类型加编译检查：430k 行 TypeScript 的维护成本有一半来自"这个函数的参数到底是什么类型"这种问题
3. CGo 是一把双刃剑：需要 CGo（go-sqlite3 + gojieba，外加插件加载器的 libdl），但限制在最小范围——只有数据库、分词和动态链接加载三处需要 C，其余全部是纯 Go
4. 插件系统多样性：内置插件用 Go 编译期注册，外部插件通过 C ABI（dlopen .so）或者 sidecar 进程（JS/Python 走 JSON-RPC）接入

## 当前状态

v0.9.0，核心可用，插件系统和 SDK 就绪。C ABI v2 外部插件 Stage 写回、17 个外部插件以新 ABI 重建。10 个内置插件，外部插件 SDK 在 homeagent-sdk 仓库，示例插件包括 qq、browser、bili、ocr、memo、files、a2a 等。单 agent 多通道——同一个 agent 同时接入 QQ 群、WebUI、命令行。

## 与 OpenClaw 和 OpenHarness 的对比

### 对比总结

- **语言**: OpenClaw TypeScript 约 430k 行 / OpenHarness Python 约 5k 行骨架 / HomeAgent Go 约 33k 行
- **内核网络 IO**: OpenClaw 内核也做 IO / OpenHarness 无严格分离 / HomeAgent 内核零网络 IO
- **记忆**: OpenClaw 简单 context 管理 / OpenHarness 只定义了接口 / HomeAgent 三层记忆
- **session 模型**: OpenClaw 多 session 隔离 / OpenHarness 无 / HomeAgent 单 agent session 仅做标签
- **插件语言**: OpenClaw TS/JS (npm) / OpenHarness 未定义 / HomeAgent Go/JS/Python/Lua
- **插件安全**: OpenClaw npm run scripts / OpenHarness 无 / HomeAgent 沙箱路径加高危操作 confirm
- **插件热加载**: OpenClaw 需重启 Gateway / OpenHarness 未实现 / HomeAgent plgreload 热重载
- **外部插件加载**: OpenClaw require() 进进程 / OpenHarness N/A / HomeAgent dlopen .so 或 sidecar JSON-RPC
- **Stage 管道**: OpenClaw 4 阶段 / OpenHarness 只定义了 loop / HomeAgent 7 阶段
- **稳定性**: OpenClaw 未捕获异常易崩溃 / OpenHarness 教学原型 / HomeAgent panic 恢复加插件自动重载
- **社区**: OpenClaw 约 250k 星 / OpenHarness 约 200 星 / HomeAgent 约 0 星
- **作者**: OpenClaw Peter Steinberger 团队 / OpenHarness HKU 学术团队 / HomeAgent jianf

## 写在最后

做 HomeAgent 的出发点很简单：我想要的 agent 框架不存在，所以我自己写了一个。

OpenClaw 证明了 agent 可以接入聊天、可以调用工具、可以有生态。但它的 session 模型和稳定性不适合我这种想让 agent 7x24 运行、跨群聊认知一致的需求。

HomeAgent 只有 33k 行 Go。但它解决了我真实遇到的问题。如果你也有类似的困扰——看看源码，也许对你也有用。

---

项目地址：[gitcode.com/JianFeeeee/HomeAgent](https://gitcode.com/JianFeeeee/HomeAgent)
SDK 地址：[gitcode.com/JianFeeeee/homeagent-sdk](https://gitcode.com/JianFeeeee/homeagent-sdk)
作者：jianf
版本：v0.9.0（2026-08-15）

HomeAgent v1.2.x 更新日志#

手把手部署 HomeAgent——从 Release 二进制开始（v1.2.x 版）#

从零开发 HomeAgent QQ 插件（v1.2.x 版）#