jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-11-03 07:47:45 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
7b4c6ead7f937c52ae4095b83fa22fb1609b0ae7
HomeAgent/README.md
JianFeeeee 8a3151c285 docs: README 开头改成真正的独到设计 
上一版开头是「接上 QQ、WebUI、命令行、文件、浏览器，跑几个月不用重启」——
这不是设计，是所有 agent 框架都能说的话。用 codegraph 查了实际实现，
真正独到的是四条，每条都有可验证的常量与实测值：

## 1. 启动顺序编译期定序

`internal/kernelboot/kernelboot.go` 的 `Module` 接口声明 `Requires`/`Provides`，
构建时 `homed-depgraph` 算出 6 层依赖图写入 `depgraph.bin`，并把 digest 用
`-ldflags` 注入二进制。运行期 `loadStartupPlan` 只读图。

关键在 `CheckAgainstBinary`：图与二进制 digest 不一致时**拒绝启动**，
不猜哪边对（注释原话："猜一个是拿启动正确性赌运气"）。

`Run` 里还有一层：`produced` 是**执行期事实**而非声明推演，`verifyLayerDependencies`
拿它校验，所以咬得住"层顺序被改坏"（实测 lua 排到 llm 之后 ⇒ llm 拿 0x0 LuaVM，SIGSEGV）。

## 2. 插件按设施就绪提前启动

`cmd/homed/kmod_runtime.go` 的 `BeforeRun` 钩子让插件调度器在**执行任何模块之前**
订阅 syncbus，`OnLayerDone` 在每层完成后重新评估拉起。

不是"内核装完再拉插件"：声明 `requires_facilities: [config]` 的插件在第 1 层
完成时就起，不必等第 4 层 agent（实测 35 秒 = dense backfill 750 事件 + 重建索引）。

## 3. 两级输入、四级中断、饥饿防护

`internal/agent/core/scheduler.go`：排队输入无级别（任何中断可打断），中断带 L1–L4。
`effectiveLevel = min(L4, Level + min(PreemptCount, 2))` —— 抢占能提级但封顶两档，
`preemptPromotionCap = 2`，防低优先级饿死。

L4 内核独占，插件声明 L4 被 `clampPluginLevel` 夹到 L3。

## 4. 场面涌现

`internal/memory/scene_emerge.go`：指纹由 chan/peer/tool/topic/part 构成，
权重 1.0/1.0/0.8/0.4/0.2。`minSceneEvidence = 2` —— 只发生一次的不建场景。
`joinSceneThreshold = 0.5` vs `recallSceneThreshold = 0.35`，
**唤起比归属宽松**（注释："想不起来是损失，多想起一条只是多几行上下文"）。

QQ、WebUI、命令行这些搬到「其余」一节，不再当卖点。

## 验证

- `go run ./cmd/homed-depgraph -print` 确认 20 模块 6 层
- 四个常量在源码里逐一 grep 确认存在且值一致
- 两版各 98 行，4 节结构对齐，链接无死链
2026-10-31 11:27:16 +08:00

5.6 KiB
Raw Blame History

⚠️ AI 辅助编程声明：本项目代码、文档及提交历史中，部分内容由 AI 辅助生成或修改。人工已审阅关键改动，但使用时请自行评估与验证。

HologramAgent

English: README_EN.md

自托管 Agent 内核。文档 · English

启动顺序是编译期算出来的，不是运行期猜的。 20 个内核模块各自声明 Requires/Provides， 构建时算出 6 层依赖图写进 depgraph.bin，并把图的 digest 用 -ldflags 注入二进制。 运行期只读图，不重算。图与二进制不配套就拒绝启动，不猜哪边对。

make build build-cli
./build/homed -data /tmp/ha

插件按设施就绪时刻启动，不等内核全装完。 插件声明 requires_facilities: [config]， config 层（第 1 层）完成时它就起来了，不必等 agent 层。实测省掉 35 秒：agent 层要做 context dense backfill 750 条事件、重建文档与知识库索引。

输入分两类，中断分四级。 排队输入没有级别，任何中断都能打断它。中断带 L1–L4， 高抢占低，被抢占的现场压栈待恢复。同级不互相抢占。L4 归内核独占（panic、内核事件）， 插件声明 L4 会被夹到 L3。抢占计数能提级，但最多两档（preemptPromotionCap = 2）， 防低优先级任务被无限饿死。

记忆按场面分，不按会话。 场面指纹由通道、对话对象、工具、话题、时段构成， 权重依次 1.0 / 1.0 / 0.8 / 0.4 / 0.2。重复出现到第 2 次才长成场面 （minSceneEvidence = 2），只发生一次的不算。归属阈值 0.5，唤起阈值 0.35， 唤起比归属宽松——想不起来是损失，多想一条只是多几行上下文。

其余

  • 通道：WebUI、命令行、QQ 群与私聊、A2A、IDE 里的 ACP
  • 工具：文件、命令、代码、浏览器（真实 Chrome）、日程、备忘、RSS、音乐
  • 模态：图片、视频、语音、截图、网页
  • 内核零 IO：不发 HTTP、不读文件，全部能力在插件里

28 个内置插件、89 个模型可调工具。外部插件一插件一仓，见 github.com/HologramAgent。

下载

Releases 提供三种变体：

变体 内容 适用
full homed + waiter + 桌面 GUI + systemd unit 单机全功能
server homed + waiter + systemd unit 服务器（无桌面环境）
client waiter + 桌面 GUI 连接远程 HologramAgent
  • Linux：.deb（amd64/arm64）、.rpm（x86_64）、.tar.gz
  • Windows：HologramAgent_v1.2.0_{Full,Server,Client}_win64.exe（NSIS 安装向导，含 AGPL 许可页）。自 v1.2.0 起因 homed 不再支持 Windows 原生（依赖 fd 继承与共享内存段内偏移解引用），安装器改为引导到 WSL2，并把 Linux 包送进发行版里按 Linux 方式安装。
  • 免安装：homeagent-bin-<os>_<arch>.tar.gz（含 homed/waiter/initconfig）
  • 校验：SHA256SUMS

macOS 的 homed 需在原生 macOS 构建（CGO + sqlite3），发布包仅含 waiter/initconfig。

构建

依赖 Go 1.25+、CGo（go-sqlite3）、Linux。

make build build-cli    # 守护进程 + CLI
make test               # go test ./...
make install            # 安装到系统

homed 只能在 Linux 上跑（依赖 fd 继承与共享内存段的段内偏移解引用）。 Windows 上构建 waiter.exe，homed 跑在 WSL2 里；macOS 要原生构建 homed。

许可

本项目以 GNU Affero 通用公共许可证第 3 版（AGPL-3.0-only） 发布，全文见 LICENSE。

它是 GPL 家族里传染性最强的一档：不仅分发时须提供完整对应源码， 通过网络提供服务时也要向使用者提供源码（§13 Remote Network Interaction）。 即：任何人把改过的 HologramAgent 对外提供网络服务，都必须让该服务的使用者拿到改动后的源码。

插件与本项目通过公开 hologramagentsdk 静态链接 （SDK 源码会进入插件二进制），但那个仓以 MIT 发布。MIT 是宽松许可，拿到授权的代码不继承 本项目的 AGPL。因此外部插件不是本项目的衍生作品，作者可自行选择许可（含闭源、商业、私有）， 既不必同许可、也不受 §13 网络条款约束。第三方插件生态的安全与活跃正建立在这条之上。

边界很清楚：AGPL 覆盖内核与随包内置插件（homed、internal/、internal/plugins/ 下的内置插件）； MIT 覆盖公开 SDK（sdk/，go.mod 零外部依赖、只依赖 Go 标准库，不引用内核任何代码）。 子进程隔离在这里不重要了。决定许可的是被链接的 SDK 代码本身，而它是 MIT。

随包分发的第三方组件

组件 许可 位置
Chinese-CLIP ViT-B/16（ONNX 产物） Apache-2.0 /usr/lib/hologram/models/chinese-clip-vit-b16-onnx/
ONNX Runtime（libonnxruntime.so） MIT /usr/lib/hologram/onnxruntime/
jieba 词库（内嵌进二进制） MIT 源码 internal/memory/jiebadict/
Go 依赖（go-sqlite3、gojieba、bubbletea 等） MIT / BSD-3 / Apache-2.0 均为宽松许可，与 AGPL-3.0 兼容

这些组件保持各自原有许可，不在本项目的 AGPL 授权范围内；发行包把它们的许可全文放在 /usr/share/doc/hologramagent/licenses/，并在 dep/rpm 元数据里声明本包许可为 AGPL-3.0-only。