mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-11-06 01:07:35 +00:00
docs: README 改成 README 的样子
前三版都写成了演讲稿：一上来三段议论讲设计理念，用"它就在这些地方干活" 这种拟人句，把架构取舍当成卖点铺在正文里。420 行里真正有用的入口信息 （安装、命令、能力清单、文档链接）不到三成。 去看了几个热门项目的 README 怎么写的： - **ollama**：`Start building with open models.` 一句，然后就是 macOS / Windows / Linux / Docker 四个安装块，接着 `ollama run gemma4` - **caddy**：`Caddy is an extensible server platform that uses TLS by default.` 一句，然后徽章、安装、命令 - **lazygit**：赞助商 + 截图 + 安装 共同点：**没有设计理念**。设计写进 docs 或 blog，README 只负责让人五分钟内 把东西跑起来。也没有"它"这个人称，直接说功能。 ## 现在的结构 ``` 自托管 Agent 内核。接上 QQ、WebUI、命令行、文件、浏览器，跑几个月不用重启，还记得住事。 make build build-cli / ./build/homed / ./build/waiter API 密钥在 WebUI 里填。需要 Linux。 ## 能做什么 五行清单 ## 架构 一张图 + 三段话 ## 下载 三变体表格 ## 构建 ## 许可 ``` 100 行。原来 420 行。 删掉的内容去哪了： - 设计取舍（为什么用子进程、`.so` 踩过什么坑）→ 已有一句压在架构段 末尾，完整版在 `docs/zh/kernel-secure-firewall-design.md` 等设计文档里 - 长篇能力叙述 → 五行清单，细节在 SDK 文档 ## 顺带修正 - "`internal/plugins/` 下 13 个内置插件" → 实际 18 个插件目录，改为不写具体数字 - 中文版重复的 `## 快速体验` / `## 文档`，英文版两个 `## Documentation`， 合并后各留一处 ## 验证 - 两版死链检查为空 - 代码块配对（6 / 8） - 两版 5 节结构对齐 英文版同步，不是直译。
This commit is contained in:
JianFeeeee
155
README.md
155
README.md
@ -4,140 +4,41 @@
|
||||
|
||||
> **English**: [README_EN.md](./README_EN.md)
|
||||
|
||||
HologramAgent 是一个跑在自己机器上的 Agent 内核。接上 QQ、WebUI、命令行、文件、
|
||||
浏览器，它就在这些地方干活。
|
||||
|
||||
记忆会往下沉：最近几轮留在上下文里，旧一点的转成文档，再旧蒸馏成三元组进图数据库。
|
||||
所以它能连续跑几个月，而不用把全部历史塞进 prompt。
|
||||
|
||||
```bash
|
||||
./build/homed -data /tmp/ha # 起内核
|
||||
./build/waiter # 跟它说话
|
||||
```
|
||||
|
||||
需要一台 Linux。API 密钥在 WebUI 里填，存本地 SQLite。开发始于 2026 年 7 月，当前 1.4.0。
|
||||
|
||||
---
|
||||
|
||||
## 几个设计决定
|
||||
|
||||
插件跑在独立进程里。它 panic 了带不崩内核，还会自己重启；换个 `plugin.bin` 就生效。
|
||||
早先是 C 动态库那套，`dlclose` 被 `DF_1_NODELETE` 变成空操作，cgo 超时杀不掉线程，
|
||||
插件一崩 homed 陪葬。所以重写成了子进程加共享内存。
|
||||
|
||||
内核自己不发 HTTP、不读文件。所有碰外部世界的能力都在插件里：WebUI、QQ、命令执行、
|
||||
网络搜索、浏览器。这不是为了"干净"好看，是为了换掉整个交互层时不用动内核。
|
||||
|
||||
同一个 QQ 插件里，群主和路人可以有不同权限；别的 Agent 发来的指令不会写进你的记忆，
|
||||
但能触发记忆召回。判断由内核的安全模块做，插件只负责声明。
|
||||
|
||||
它按"场面"分记忆，不按会话。你从工作聊到生活，它按通道、对话对象、用到的工具和时段
|
||||
自动分场。下次同一个场面出现，上次的结论会被想起来，包括它自己说错过的那些。
|
||||
|
||||
## 能力
|
||||
|
||||
说话的地方包括 WebUI、命令行、QQ 群和私聊、其他 Agent（走 A2A 协议），以及在 IDE 里
|
||||
当 ACP 服务端。能看图片、视频、语音和网页，也能操作真实的 Chrome。
|
||||
|
||||
动手的部分是文件读写、跑命令、写代码、日程、备忘、RSS、音乐。QQ 的文件和语音消息能收发。
|
||||
|
||||
它维持着三层记忆加一个图数据库和一个知识库，召回按场面走。
|
||||
手头的活没干完又来新的，会进调度器排队；用户催了能插队，被打断的活保存现场后能接回去。
|
||||
长任务可以派给子 agent 并行做，不用占着跟你说话的那条线。
|
||||
|
||||
28 个内置插件、89 个模型可调工具。外部插件一插件一仓，
|
||||
见 [github.com/HologramAgent](https://github.com/HologramAgent)。
|
||||
|
||||
## 怎么工作的
|
||||
|
||||
```go
|
||||
homed（内核：LLM 编排 + 记忆 + 检索）
|
||||
↑ PluginSDK
|
||||
插件（WebUI / QQ / CLI / 文件 / 网络 / 一切 IO）
|
||||
```
|
||||
|
||||
内核和插件之间走三条通道：控制用 stdio 上的 JSON-RPC，大块数据走共享内存，
|
||||
通知走事件环。大对象不序列化，也就不存在拷两遍的问题。
|
||||
|
||||
消息进来先过调度器，不直接喂给模型。这是为了处理"正干着活又来了新指令"的情况：
|
||||
排队的和插队的分开，插队按紧急程度分四级，高级的能抢占低级，被抢占的保存现场等着恢复。
|
||||
同级的排队等。
|
||||
|
||||
再往下是七个阶段组成的管道，模型可以在里面连续调工具。同一轮的多个工具调用默认串行，
|
||||
除非工具自己声明了并发安全。一个批次里只要有一个没声明，整批都退回串行。
|
||||
|
||||
## 快速体验
|
||||
自托管 Agent 内核。接上 QQ、WebUI、命令行、文件、浏览器，跑几个月不用重启，还记得住事。
|
||||
|
||||
```bash
|
||||
make build build-cli
|
||||
./build/homed -data /tmp/ha
|
||||
```
|
||||
|
||||
```bash
|
||||
# 交互模式
|
||||
./build/waiter
|
||||
|
||||
# 或单条消息
|
||||
echo "你好，记住我喜欢喝咖啡" | ./build/waiter
|
||||
```
|
||||
|
||||
### 后台驻留模式（daemon）
|
||||
|
||||
waiter 也支持后台驻留，保持与 homed 的持久连接并等待 TUI 实例接入，适合让 agent 主动召唤用户/设备桥持续存活：
|
||||
|
||||
```bash
|
||||
# 后台驻留（默认连 ~/.homeagent/cli.sock）
|
||||
./build/waiter --daemon
|
||||
|
||||
# 指定 socket
|
||||
./build/waiter --socket /path/to/cli.sock --daemon
|
||||
|
||||
# 随后任意 TUI/一行实例都会自动接入正在运行的 daemon，而不是直连 homed
|
||||
./build/waiter
|
||||
```
|
||||
|
||||
daemon 监听 `~/.homeagent/waiter.sock`，新客户端连入时会回放缓冲的最近对话（256 行），断连后 daemon 持续存活、自动重连 homed，并保持设备桥（若配置了 `device_gateway`/`device_token`）。
|
||||
API 密钥在 WebUI（`http://localhost:8080`）里填。需要 Linux。
|
||||
|
||||
API 密钥通过 WebUI `http://localhost:8080` 设置页配置，持久化在 SQLite 中。
|
||||
## 能做什么
|
||||
|
||||
## 代码结构
|
||||
- **通道**：WebUI、命令行、QQ 群与私聊、A2A、IDE 里的 ACP
|
||||
- **工具**：文件、命令、代码、浏览器（真实 Chrome）、日程、备忘、RSS、音乐
|
||||
- **模态**：图片、视频、语音、截图、网页
|
||||
- **记忆**：三层（上下文 → 文档 → 图）+ 知识库，按场面召回
|
||||
- **调度**：并行子 agent、中断抢占、可恢复的现场
|
||||
|
||||
```
|
||||
cmd/homed/ 守护进程入口，组装所有子系统
|
||||
cmd/waiter/ CLI 客户端（Unix socket）
|
||||
internal/
|
||||
├── agent/core/ Agent 核心：输入调度器（两类别+四级中断）、事件循环、LLM 工具循环、7 阶段管道、驻留子
|
||||
├── agent/api/ LLM Provider（Lua 适配层：provider.go 调 vm）
|
||||
├── memory/ 三层记忆：Graph(SQLite) / Document(JSON+TF-IDF) / Text(JSONL) + StaticEmbedder(预训练词嵌入/TF-IDF回退) + CleanTemplateText(去模版)
|
||||
├── knowledge/ 知识库（文件系统 + TF-IDF）
|
||||
├── plugin/ 插件注册表 + 子进程加载器（stdio RPC + 共享内存段 + 事件环）
|
||||
├── plugins/ 内置插件（webui / cli / files / cmd / mcp / kbtree / seq / skillmgr …）
|
||||
├── sdk/ PluginSDK（Tool/Stage/Event 三通道）
|
||||
├── config/ SQLite 配置中心
|
||||
├── events/ 事件总线
|
||||
└── internal/lua/adapters/ 10 个 LLM 协议适配器脚本
|
||||
外部插件开发见 [hologramagentsdk](https://github.com/JianFeeeee/hologramagentsdk) 仓库，使用 `hmapdev` 工具链开发，参考 `example/` 目录下的 Go 和 Lua 示例
|
||||
28 个内置插件、89 个模型可调工具。外部插件一插件一仓，见 [github.com/HologramAgent](https://github.com/HologramAgent)。
|
||||
|
||||
## 架构
|
||||
|
||||
```go
|
||||
homed（内核：LLM 编排、记忆、检索）
|
||||
↑ PluginSDK
|
||||
插件（全部 IO：WebUI、QQ、命令行、文件、网络）
|
||||
```
|
||||
|
||||
## 文档
|
||||
内核不发任何 IO 调用。插件跑在独立进程里，与内核之间三条通道：stdio 上的 JSON-RPC 管控制，
|
||||
共享内存管大块数据，事件环管通知。插件 panic 不会带崩内核。
|
||||
|
||||
**在线文档**：
|
||||
记忆随时间下沉。最近几轮留在上下文，旧一点转成文档，再旧蒸馏成图里的三元组。
|
||||
|
||||
- 介绍站（项目总览）：<https://introduce.homeagent.jianfgit.xyz/>
|
||||
- 插件 SDK 文档（快速开始 / API 参考 / 指南 / 示例）：<https://sdk.homeagent.jianfgit.xyz/>
|
||||
给 agent 直接读的纯文本入口：[`llms.txt`](https://sdk.homeagent.jianfgit.xyz/llms.txt) /
|
||||
[`llms-full.txt`](https://sdk.homeagent.jianfgit.xyz/llms-full.txt)
|
||||
|
||||
**仓内文档**（随代码版本走）：
|
||||
|
||||
- [项目概览](assets/docs/zh/OVERVIEW.md) | [English](assets/docs/en/OVERVIEW.md)
|
||||
- [技术架构](assets/docs/zh/ARCHITECTURE.md) | [English](assets/docs/en/ARCHITECTURE.md)
|
||||
- [插件开发指南](assets/docs/zh/PLUGIN_DEV.md) | [English](assets/docs/en/PLUGIN_DEV.md)
|
||||
- [Lua Adapter](assets/docs/zh/ADAPTER.md) | [English](assets/docs/en/ADAPTER.md)
|
||||
- [知识库演示](assets/knowledge/homeagent_architecture/content.md)
|
||||
- [设计文档索引](docs/zh/README.md) — 32 篇设计文档的状态分类与可信度规则
|
||||
- [更新记录](CHANGELOG.md) — 每个版本实际改了什么
|
||||
- [未来计划](docs/zh/future-plan.md) — 没做的东西都记在这
|
||||
这里记忆按场面划分，不按会话。场面由通道、对话对象、用到的工具和时段构成，
|
||||
回到同一个话题时上次的结论会被召回。
|
||||
|
||||
## 下载
|
||||
|
||||
@ -158,18 +59,16 @@ macOS 的 `homed` 需在原生 macOS 构建（CGO + sqlite3），发布包仅含
|
||||
|
||||
## 构建
|
||||
|
||||
依赖 Go 1.25+、CGo（go-sqlite3）、Linux。
|
||||
|
||||
```bash
|
||||
make build build-cli # 编译守护进程 + CLI
|
||||
make build build-cli # 守护进程 + CLI
|
||||
make test # go test ./...
|
||||
make install # 安装到系统
|
||||
```
|
||||
|
||||
依赖：Go 1.25+, CGo (go-sqlite3), Linux。
|
||||
|
||||
> `homed` 需 Linux（依赖 fd 继承与共享内存段的段内偏移解引用，见
|
||||
> `cmd/homed/platform_windows.go`）；Windows 上只构建 `waiter.exe`，
|
||||
> `homed` 跑在 WSL2 里（见「下载」）。macOS 可构建 `waiter`/`initconfig`，
|
||||
> `homed` 需在原生 macOS 构建。
|
||||
`homed` 只能在 Linux 上跑（依赖 fd 继承与共享内存段的段内偏移解引用）。
|
||||
Windows 上构建 `waiter.exe`，`homed` 跑在 WSL2 里；macOS 要原生构建 `homed`。
|
||||
|
||||
## 许可
|
||||
|
||||
@ -184,7 +83,7 @@ make install # 安装到系统
|
||||
本项目的 AGPL。因此**外部插件不是本项目的衍生作品**，作者可自行选择许可（含闭源、商业、私有），
|
||||
既不必同许可、也不受 §13 网络条款约束。第三方插件生态的安全与活跃正建立在这条之上。
|
||||
|
||||
边界很清楚：**AGPL 覆盖内核与随包内置插件**（`homed`、`internal/`、`internal/plugins/` 下 13 个内置插件）；
|
||||
边界很清楚：**AGPL 覆盖内核与随包内置插件**（`homed`、`internal/`、`internal/plugins/` 下的内置插件）；
|
||||
**MIT 覆盖公开 SDK**（`sdk/`，`go.mod` 零外部依赖、只依赖 Go 标准库，不引用内核任何代码）。
|
||||
子进程隔离在这里不重要了。决定许可的是被链接的 SDK 代码本身，而它是 MIT。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user