From 52100dfa773a09c1935e30d888176e595ba5e426 Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Sat, 31 Oct 2026 11:23:56 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20README=20=E6=94=B9=E6=88=90=20README=20?= =?UTF-8?q?=E7=9A=84=E6=A0=B7=E5=AD=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 前三版都写成了演讲稿：一上来三段议论讲设计理念，用"它就在这些地方干活" 这种拟人句，把架构取舍当成卖点铺在正文里。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 节结构对齐 英文版同步，不是直译。 --- README.md | 155 +++++++++----------------------------------------- README_EN.md | 156 +++++++++++---------------------------------------- 2 files changed, 59 insertions(+), 252 deletions(-) diff --git a/README.md b/README.md index b0de5c55..39f7bb80 100644 --- a/README.md +++ b/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 不会带崩内核。 -**在线文档**： +记忆随时间下沉。最近几轮留在上下文，旧一点转成文档，再旧蒸馏成图里的三元组。 -- 介绍站（项目总览）： -- 插件 SDK 文档（快速开始 / API 参考 / 指南 / 示例）： - 给 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。 diff --git a/README_EN.md b/README_EN.md index 830c39af..db570f18 100644 --- a/README_EN.md +++ b/README_EN.md @@ -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): -- Plugin SDK docs (getting started / API reference / guides / examples): - 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: