From 8a3151c285a483765452053c2669685ec8f129b7 Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Sat, 31 Oct 2026 11:27:16 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20README=20=E5=BC=80=E5=A4=B4=E6=94=B9?= =?UTF-8?q?=E6=88=90=E7=9C=9F=E6=AD=A3=E7=9A=84=E7=8B=AC=E5=88=B0=E8=AE=BE?= =?UTF-8?q?=E8=AE=A1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 上一版开头是「接上 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 节结构对齐，链接无死链 --- README.md | 42 ++++++++++++++++++------------------- README_EN.md | 58 +++++++++------------------------------------------- 2 files changed, 30 insertions(+), 70 deletions(-) diff --git a/README.md b/README.md index 39f7bb80..a52aefb3 100644 --- a/README.md +++ b/README.md @@ -4,42 +4,40 @@ > **English**: [README_EN.md](./README_EN.md) -自托管 Agent 内核。接上 QQ、WebUI、命令行、文件、浏览器，跑几个月不用重启，还记得住事。 +自托管 Agent 内核。[文档](assets/docs/zh/ARCHITECTURE.md) · [English](README_EN.md) + +**启动顺序是编译期算出来的，不是运行期猜的。** 20 个内核模块各自声明 `Requires`/`Provides`， +构建时算出 6 层依赖图写进 `depgraph.bin`，并把图的 digest 用 `-ldflags` 注入二进制。 +运行期只读图，不重算。图与二进制不配套就拒绝启动，不猜哪边对。 ```bash make build build-cli ./build/homed -data /tmp/ha -./build/waiter ``` -API 密钥在 WebUI（`http://localhost:8080`）里填。需要 Linux。 +**插件按设施就绪时刻启动，不等内核全装完。** 插件声明 `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、音乐 - **模态**：图片、视频、语音、截图、网页 -- **记忆**：三层（上下文 → 文档 → 图）+ 知识库，按场面召回 -- **调度**：并行子 agent、中断抢占、可恢复的现场 +- **内核零 IO**：不发 HTTP、不读文件，全部能力在插件里 28 个内置插件、89 个模型可调工具。外部插件一插件一仓，见 [github.com/HologramAgent](https://github.com/HologramAgent)。 -## 架构 - -```go -homed（内核：LLM 编排、记忆、检索） - ↑ PluginSDK -插件（全部 IO：WebUI、QQ、命令行、文件、网络） -``` - -内核不发任何 IO 调用。插件跑在独立进程里，与内核之间三条通道：stdio 上的 JSON-RPC 管控制， -共享内存管大块数据，事件环管通知。插件 panic 不会带崩内核。 - -记忆随时间下沉。最近几轮留在上下文，旧一点转成文档，再旧蒸馏成图里的三元组。 - -这里记忆按场面划分，不按会话。场面由通道、对话对象、用到的工具和时段构成， -回到同一个话题时上次的结论会被召回。 - ## 下载 [Releases](https://github.com/JianFeeeee/HologramAgent/releases) 提供三种变体： diff --git a/README_EN.md b/README_EN.md index db570f18..134bc250 100644 --- a/README_EN.md +++ b/README_EN.md @@ -4,68 +4,30 @@ > **中文**: [README.md](./README.md) -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. +Self-hosted agent kernel. [Docs](assets/docs/en/ARCHITECTURE.md) · [中文](README.md) + +**Startup order is computed at build time, not guessed at runtime.** Twenty kernel modules each declare `Requires`/`Provides`. The build resolves a 6-layer dependency graph into `depgraph.bin` and injects the graph digest into the binary via `-ldflags`. At runtime the kernel reads the graph and does not recompute it. If the graph and the binary don't match, startup is refused rather than guessing which one is right. ```bash make build build-cli ./build/homed -data /tmp/ha -./build/waiter ``` -API keys go in the web UI at `http://localhost:8080`. Requires Linux. +**Plugins start when their facilities are ready, not when the kernel finishes.** A plugin declaring `requires_facilities: [config]` launches as layer 1 completes instead of waiting for the agent layer. Measured saving: 35 seconds, which is how long the agent layer spends on dense backfill of 750 events plus rebuilding document and knowledge indexes. -## What it does +**Two input classes, four interrupt levels.** Queued input carries no level, so any interrupt can preempt it. Interrupts carry L1–L4; higher preempts lower and the preempted state is pushed onto a stack for later resume. Same level never preempts. L4 belongs to the kernel alone (panics, kernel events); a plugin declaring L4 gets clamped to L3. Preemption count can raise a task's level, but by at most two steps (`preemptPromotionCap = 2`), so low-priority work can't starve indefinitely. + +**Memory is partitioned by scene, not by session.** A scene fingerprint is built from channel, conversation partner, tools, topic, and time of day, weighted 1.0 / 1.0 / 0.8 / 0.4 / 0.2. A scene only comes into being on the second occurrence (`minSceneEvidence = 2`); one-off interactions don't count. Join threshold is 0.5, recall threshold 0.35. Recall is looser than join on purpose: failing to recall is a loss, while recalling one extra scene costs a few lines of context. + +## Everything else - **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 +- **Zero-IO kernel**: no HTTP calls, no file reads; every capability lives in a plugin 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 - -``` -cmd/homed/ Daemon entry, assembles all subsystems -cmd/waiter/ CLI client (Unix socket) -internal/ -├── agent/core/ Agent core: input scheduler (2 classes + 4 levels), event loop, LLM tool loop, 7-stage pipeline, residents -├── agent/api/ LLM Provider (Lua adapter layer: provider.go drives the vm) -├── memory/ Three-layer memory: Graph(SQLite) / Document(JSON+TF-IDF) / Text(JSONL) + StaticEmbedder(pretrained word embedding/TF-IDF fallback) + CleanTemplateText(de-template) -├── knowledge/ Knowledge base (filesystem + TF-IDF) -├── plugin/ Plugin registry + subprocess loader (stdio RPC + shared memory segment + event ring) -├── plugins/ built-in plugins (webui / cli / files / cmd / mcp / kbtree / seq / skillmgr …) -├── sdk/ PluginSDK (Tool/Stage/Event three channels) -├── config/ SQLite config center -├── events/ Event bus -└── internal/lua/adapters/ 10 LLM protocol adapter scripts -External plugin development: see the [hologramagentsdk](https://github.com/JianFeeeee/hologramagentsdk) -repo with the `hmapdev` toolchain. Each plugin has its own repo under -[github.com/HologramAgent](https://github.com/HologramAgent). -``` - ## Downloads [Releases](https://github.com/JianFeeeee/HologramAgent/releases) ship three variants: