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 节结构对齐,链接无死链
This commit is contained in:
JianFeeeee
2026-10-31 11:27:16 +08:00
parent 674cbac36c
commit 8a3151c285
2 changed files with 30 additions and 70 deletions

View File

@ -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) 提供三种变体: