jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-11-01 14:57:38 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: README 改成 README 的样子

Browse Source 
前三版都写成了演讲稿：一上来三段议论讲设计理念，用"它就在这些地方干活"
这种拟人句，把架构取舍当成卖点铺在正文里。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
2026-10-31 11:23:56 +08:00
parent 9fe82c8e26
commit 52100dfa77
2 changed files with 59 additions and 252 deletions
Download Patch File Download Diff File Expand all files Collapse all files

155
README.md
View File

@ -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。

156
README_EN.md
View File

@ -4,118 +4,46 @@
> **中文**: [README.md](./README.md)
HologramAgent is an agent kernel that runs on your own hardware. Connect it to QQ, a web UI,
your shell, your files, a browser, and it works in all of them.
Memory sinks: the last few turns stay in context, older ones become documents, oldest get
distilled into triples in a graph database. That is why it can run for months without
stuffing the entire history into every prompt.
```bash
./build/homed -data /tmp/ha # start the kernel
./build/waiter # talk to it
```
You need a Linux box. API keys go in through the web UI and live in local SQLite.
Development started July 2026; currently 1.4.0.
---
## Design decisions
Plugins run in separate processes. One panics and the kernel stays up; it restarts on its
own. Drop in a new `plugin.bin` and it's live. The earlier version used C shared libraries,
where `dlclose` silently no-ops under `DF_1_NODELETE`, cgo timeouts leave threads alive, and
one plugin panic dragged `homed` down with it. That is why it was rewritten as subprocesses
plus shared memory.
The kernel itself makes no HTTP calls and reads no files. Everything that touches the outside
world lives in plugins: the web UI, QQ, command execution, web search, the browser. Not for
tidiness. It means you can swap the entire interaction layer without touching the kernel.
Inside one QQ plugin, a group owner and a random member can hold different permissions.
Instructions arriving from another agent don't get written into your memory, though they can
trigger recall. The kernel's security module makes those calls; plugins only declare.
Memory is partitioned by scene, not by session. Move from work talk to personal talk and it
splits context by channel, conversation partner, tools used, and time of day. When a scene
recurs, last time's conclusions come back, including the ones it got wrong.
## What it can do
Places it talks: web UI, shell, QQ groups and DMs, other agents over A2A, and an ACP server
inside your IDE. It can look at images, video, voice, and web pages, and it can drive a real
Chrome.
For getting things done it reads and writes files, runs commands, writes code, and handles
calendars, notes, RSS, and music. QQ files and voice messages go both ways.
Behind that sit three memory layers plus a graph database plus a knowledge base, recalled by
scene. When new work arrives mid-task it enters a scheduler; if the user pushes back it can
jump the queue, and interrupted work saves its state and resumes. Long jobs can be handed to
sub-agents so they don't block the line you're talking on.
28 built-in plugins, 89 model-callable tools. External plugins live one-per-repo at
[github.com/HologramAgent](https://github.com/HologramAgent).
## How it works
```go
homed (kernel: LLM orchestration + memory + retrieval)
↑ PluginSDK
plugins (web UI / QQ / CLI / files / network / all IO)
```
Three channels between kernel and plugins: JSON-RPC over stdio for control, shared memory
for bulk data, an event ring for notifications. Large objects aren't serialized, so there's
nothing to copy twice.
Incoming messages hit a scheduler first, not the model. This exists for the case where work is
already in flight and a new instruction arrives: queued work and interruptions are separate
classes, interruptions carry four urgency levels, a higher level preempts a lower one and the
preempted work saves its state to resume later. Same level waits.
Below that sits a seven-stage pipeline where the model can call tools in a loop. Multiple tool
calls in one turn are serial by default unless a tool declares itself concurrency-safe. One
undeclared tool in a batch drops the whole batch back to serial.
## Quick Start
Self-hosted agent kernel. Connects to QQ, a web UI, your shell, files, and a browser. Runs for months without a restart and keeps what it learned.
```bash
make build build-cli
./build/homed -data /tmp/ha
```
```bash
# Interactive mode
./build/waiter
# Or a single message
echo "Hi, remember I like coffee" | ./build/waiter
```
### Daemon mode
`waiter` can also run resident, holding a persistent connection to `homed` and waiting for a
TUI instance to attach. Useful when the agent needs to reach you proactively or keep a device
bridge alive.
```bash
# Resident (connects to ~/.homeagent/cli.sock by default)
./build/waiter --daemon
# Custom socket
./build/waiter --socket /path/to/cli.sock --daemon
# Any TUI or one-shot instance then attaches to the running daemon instead of homed directly
./build/waiter
```
The daemon listens on `~/.homeagent/waiter.sock`, replays the last 256 lines of conversation to
new clients, survives disconnects, reconnects to `homed` on its own, and keeps the device bridge
alive when `device_gateway` / `device_token` are configured.
API keys go in the web UI at `http://localhost:8080`. Requires Linux.
Set API keys in the web UI at `http://localhost:8080`; they persist in SQLite.
## What it does
- **Channels**: web UI, CLI, QQ groups and DMs, A2A, ACP in your IDE
- **Tools**: files, shell, code, browser (real Chrome), calendar, notes, RSS, music
- **Modalities**: images, video, voice, screenshots, web pages
- **Memory**: three layers (context → document → graph) plus a knowledge base, recalled by scene
- **Scheduling**: parallel sub-agents, interrupt preemption, resumable state
28 built-in plugins, 89 model-callable tools. External plugins live one per repo under [github.com/HologramAgent](https://github.com/HologramAgent).
## Architecture
```go
homed (kernel: LLM orchestration, memory, retrieval)
↑ PluginSDK
plugins (all IO: web UI, QQ, CLI, files, network)
```
The kernel makes no IO calls. Plugins run as separate processes and talk to it over three channels: JSON-RPC on stdio for control, shared memory for bulk data, an event ring for notifications. A plugin panic doesn't take the kernel down.
Memory sinks over time. Recent turns stay in context, older ones become documents, oldest get distilled into graph triples.
Memory is partitioned by scene rather than by session. A scene is made of channel, conversation partner, tools used, and time of day, so returning to a topic recalls what was concluded last time.
## Documentation
- [Architecture](assets/docs/en/ARCHITECTURE.md) ([中文](assets/docs/zh/ARCHITECTURE.md))
- [Plugin development](assets/docs/en/PLUGIN_DEV.md)
- [SDK docs](https://sdk.homeagent.jianfgit.xyz/) · [llms.txt](https://sdk.homeagent.jianfgit.xyz/llms.txt)
- [Changelog](CHANGELOG_EN.md) · [Design docs](docs/zh/README.md) · [Future plan](docs/zh/future-plan.md)
## Code Structure
@ -138,26 +66,6 @@ repo with the `hmapdev` toolchain. Each plugin has its own repo under
[github.com/HologramAgent](https://github.com/HologramAgent).
```
## Documentation
**Online docs**:
- Introduction site (project overview): <https://introduce.homeagent.jianfgit.xyz/>
- Plugin SDK docs (getting started / API reference / guides / examples): <https://sdk.homeagent.jianfgit.xyz/>
plain-text entry for agents: [`llms.txt`](https://sdk.homeagent.jianfgit.xyz/llms.txt) /
[`llms-full.txt`](https://sdk.homeagent.jianfgit.xyz/llms-full.txt)
**In-repo docs** (versioned with the code):
- [Project Overview](assets/docs/en/OVERVIEW.md) | [中文](assets/docs/zh/OVERVIEW.md)
- [Technical Architecture](assets/docs/en/ARCHITECTURE.md) | [中文](assets/docs/zh/ARCHITECTURE.md)
- [Plugin Development Guide](assets/docs/en/PLUGIN_DEV.md) | [中文](assets/docs/zh/PLUGIN_DEV.md)
- [Lua Adapter](assets/docs/en/ADAPTER.md) | [中文](assets/docs/zh/ADAPTER.md)
- [Knowledge Base Demo](assets/knowledge/homeagent_architecture/content.md)
- [Design doc index](docs/zh/README.md) — status classification and trust rules for 32 design docs
- [Changelog](CHANGELOG_EN.md) — what actually changed in each release
- [Future plan](docs/zh/future-plan.md) — everything not yet built
## Downloads
[Releases](https://github.com/JianFeeeee/HologramAgent/releases) ship three variants: