7f43a6bfc7
## 问题：README 像架构文档，不像 README 原文 420 行，开头第一句是「以核心域与应用域分离为设计原则的 Agent 框架」。 读者点进来想知道「这东西能给我干什么」，得到的是一句需要三分钟才能理解的定义。 量化一下 AI 味的几个典型指纹： | 指标 | 改前 | 改后 | |---|---|---| | 加粗标记 | **230** 处 | 56 处 | | 破折号插入语 | **17** 处 | 0 | | 行数 | 420 | 204 | | 「项目状态」占比 | 86 行（21%） | 移出 | 几乎每条 bullet 都是同一个模板：粗体术语开头 + 三行解释 + 收尾总结。 结构过度对称、每段都自我收尾，是 AI 写作最明显的痕迹。 ## 改法：先说人话，再讲设计 开头四句： > 一个能自己跑几个月、还记得住事的 Agent 内核。 > 说人话：你给它接上 QQ、WebUI、命令行、文件、浏览器，它就能在这些地方替你干活。 > 白天聊过的事，晚上还记得。三周前说过的偏好，不会因为上下文窗口滚动就丢了。 > 插件崩了它不倒，模型换了它不改。 然后把 `## 设计要点` 改成 `## 它跟别的 Agent 框架哪里不一样` ——从「我们有什么设计」 改成「你和别人有什么不同」。每条都给了**为什么这么选**，不是**我们做得多好**： - 插件是独立进程 → 因为 `.so` 那套踩过 `dlclose` 空操作、cgo 超时杀不掉线程 - 内核不碰 IO → 好处不是干净，是能换掉整个交互层而不改内核 - 记忆会下沉 → 所以能跑几个月而不把历史全塞进 prompt `## 能力` 不列 API，列「你能让它干什么」：说话的地方 / 看和听 / 动手 / 记住 / 调度。 ## 删掉 227 行重复与历史 - **`## 架构图`（142 行）**：`ARCHITECTURE.md` 里已有完整的「消息处理流程」「7 阶段 钩子」「三层记忆」，README 里这套是**逐字重复**。README 留一张 8 行流程图 + 三段话讲清机制，细节指向架构文档。 - **`## 项目状态`（85 行）**：这是更新日志，不是 README。移入新建的 `CHANGELOG.md` / `CHANGELOG_EN.md`。 ## 中英文同步 `README_EN.md` 之前停在旧版式（439 行，含 `Architecture Diagrams` / `Project Status`），与中文版结构完全不同 —— 不是这次才不同步，是**一直是两份不同的文档**。 本次按节 1:1 对齐（9 节完全一致），英文不是逐字直译，按英文习惯重写： ``` ## 它跟别的 Agent 框架哪里不一样 → ## What makes it different ## 能力 → ## What it can do ## 怎么工作的 → ## How it works ## 快速体验 → ## Quick Start ## 代码结构 → ## Code Structure ... ``` 补上英文版一直**缺失**的 `## Quick Start` 整节（中文有、英文没有）。 ## 顺带修正的事实错误 - 「内置 13 个插件」→ 实际 18 个插件目录（`webui`/`cli`/`files`/`cmd`/`mcp`/`kbtree`/`seq`/`skillmgr` …） - 「参考 `example/` 目录下的 Go 和 Lua 示例」→ 26 个插件已迁到 [github.com/HologramAgent](https://github.com/HologramAgent)，`example/` 只剩 2 个 ## 验证 - 两版死链检查：`README.md` / `README_EN.md` 内部链接全部有效 - 9 个二级标题逐一对齐 - 破折号插入语归零（英文剩余 4 处全是列表分隔符）
10 KiB
更新记录
本文件记录各版本的实质变化。README 只留"现在能干什么"，历史演进在这里。
v1.4.x 线（进行中，main）—— 声明式并发安全 + 序列编排（seq） + 工具结果诚实化。
- 同轮工具并行执行：同一轮里的多个
tool_call默认并发执行，但以「安全」为前置—— 工具必须在自己的ToolDef里显式声明ParallelSafe（内置工具用toolDefOptions）， 未声明的一律串行；Serial优先级更高。批内只要有一个不安全，整批降级为串行。 并发声明写在工具自身，内核不做硬编码工具名安全表。同通道输出严格保序， 结果与文本分离（toolOutcome.Text/Raw）。 seq序列编排插件：AST 解析 + 持久化、具名 group、变量槽、组内并行 + 组间串行、 条件调用（seq_when_call）、跨序列调用图与环检测、错误契约。- 工具结果只统计不裁剪：结果超出预算时报告统计量，不静默截断。
- 结构化工具错误契约：参数按 schema 预校验（分派前拦下）、
「工具不存在」与「执行失败」区分、
Success不再恒真。 - 设备命令白名单可配置（waiter
device_cmd_allowlist）、 站点漂移巡检、GUI 增量渲染（保留全部历史，按data-msgkey复用节点， 50/200/400 条实测 8.2/23.5/38.2ms）。
v1.3.x 线（v1.3.1–v1.3.13）—— 驻留式子 agent + 输入调度器重做。
- 驻留式子 agent：内核可派驻轻量内核的子 agent（自己的调度器、自己的 temp 稳定记忆、
共享通道登记表）。父经
resident_agents（list/create/send/inspect/compress/reclaim/destroy） 派活与收活；inputch 可划给子，输入在进内核之前就已路由到子。 - 输出通道可寻址到具体 agent：
AllowedOutputs授权集合（三处过滤点一致）， 父/子之间可互相投递；设备能力也 outputch 化（每设备一个device/<id>通道）。 - 输入调度器：排队/中断两类别 + 四级中断（L1~L4）+ 抢占/挂起/恢复/中断栈； 同级不抢占、有饥饿防护与抢占冷却；L4 只归内核与内核级插件（WebUI 终止按钮）。
- 轻量内核 profile：子的记忆面收窄为「传统上下文 + 稳定记忆（stablemem）」（窄接口， 主库以 query_only 受限句柄打开，写走自己的 temp 实例）。
- 积压及时反馈（后续线）：主 agent 长时间忙时，内核把排队输入交给临时分诊助手 —— 简单的直接处理并回复，需要主 agent 的立刻回「忙碌中，请稍候」，用户不再干等十几分钟。
- 修掉一批真实缺陷：销毁驻留子时入站 inputch（
child/<id>）注册残留、 子的轮次永远显示 0（info()根本没填）、子侧 childIO 空壳（未继承父的输出通道）、 设备心跳 pong 忘了 Flush（每 60 秒掉线）、Lua 插件桥与 SDK 1.3.0 对齐。
v1.2.0 — 统一多模态向量空间 + 媒体升为稳定记忆一等节点 + 数据面全量迁到共享内存。
- 模型中立的统一向量空间：内核不再适配任何具体模型，只提供公共 provider SPI
（
pkg/embedding：Modality/Input{Data,MIME}/Info{Dimension,Fingerprint,Modalities}- 名字注册表），实现在
providers/*。默认 Chinese-CLIP ViT-B/16 —— text 与 image 落在同一空间（512 维、指纹cd2a495cf990、Apache-2.0；实测加载峰值 1.59GB、静置回收后稳态约 0.89GB）；qwen3vl保留（2048 维、常驻约 9.4GB，供内存充足或将来要视频的机器切回）。 文本检索仍由既有词向量 / TF-IDF 兜底：CLIP 双塔的纯文本语义弱于 MLLM 型嵌入器， 这是已知并写进文档的代价。
- 名字注册表），实现在
- 媒体是图数据库的一等节点与边：彻底删除「用文本描述式索引图片」这套将就机制，
以及
media_refs与媒体引用计数。记忆块遵循单层不变量——Context → Document → Graph 是块的迁移，不是复制、也不靠引用保活。 - 数据面全部走共享内存（工具调用帧 / Cleaner / 输入输出通道 / 媒体块 / 文档与知识正文），
RPC 只传偏移描述符；RPC 协议升到 2，fd3 布局改变，不支持滚动升级——
内核与全部插件必须同批重建、同批安装，存量插件须用新版
hmapdev重编。 - 注入可声明
InjectOptions{NoMemory, ContextPolicy}（默认仍记入记忆、默认不裁剪）； 裁剪必须显式声明，且先经插件注册的Cleaner。SDK 1.2.0 相对 1.1.0 纯追加。 - 发行包默认启用 ONNX 向量空间，并把模型（754MB）与 ONNX Runtime（24MB）随
server/full 包发布；
homed放弃 Windows 原生支持改走 WSL2；jieba 词库内嵌进二进制。 - 修掉三个安装链静默失败：
initconfig因CGO_ENABLED=0是空操作（打印凭据却一个字节 没写）、全新安装被误判「已有配置」而整体跳过默认值播种（装完 0 插件）、deb 的postinst查错 unit 路径导致enable从未执行。 - 自本版起以 AGPL-3.0-only 发布（含网络条款；插件静态链接 SDK 故须同许可，见「许可」）。
以下历史条目保留原文以呈现演进，其中两条机制已在 v1.2.0 移除： 「媒体以
[<mime> <短digest>] <描述>标记参与检索」（描述式索引）与「媒体引用计数式 GC」。另有一处许可口径已变更（2026-09-24）：上面 v1.2.0 条目里的「插件静态链接 SDK 故须同许可」 自今日起不成立。SDK 改以 MIT 发布（宽松许可，不继承内核的 AGPL），故外部插件不是 本项目的衍生作品，作者可自行选择许可（含闭源、商业、私有），亦不受 §13 网络条款约束。 原文保留以呈现当时的口径。
另有两项性能断言的量纲需要更正（2026-09-20 实测）： 「崩溃到恢复 <1s」不成立 —— 崩溃后是线性退避重启，即 1s / 2s / 3s（
procRestartBackoff=1s × 第 n 次）， 首次重启就要等 1s。且 5 分钟窗口内第 4 次崩溃即停止自动重启待人工介入（procMaxRestarts=3，判定为n > 3）。 该断言写下时（v1.0.0）退避值已是 1s，故从未成立。 「RPC 往返 p50 24.1µs」与当前实测同量级但不吻合：本机BenchmarkToolInvoke实测 inline/small 30.4µs、frame/small 51.5µs、inline/large 767µs、frame/large 398µs。 保留原文不修改，以免伪造历史。
v1.1.1 — 多模态贯通插件边界。v1.1.0 让记忆系统支持了二进制多媒体节点，但那条链路只对内核自己开放；本版打通到插件与模型。公开 SDK 新增媒体字段与三个媒体注入接口（配套 SDK v1.1.0，整条 1.1.x 线共用），内核实现对应四个 RPC。桥接层此前在静默裁字段：插件交进来的 Confidence/类型/SentenceText 全被丢弃、Doc 只留三个字段、Remove 不解引用（媒体永久算「被引用」，GC 收不掉）。processTextInput/processMediaInput 归一成一条 processInput，媒体路径由此获得它一直缺的去重、no_memory、通道 Cleaner、中断语义、EventRawInput。修掉三处真实缺陷：用户发的图从来没出现在 WebUI 聊天记录里（媒体路径发布 map 而订阅方断言 string）、memory_commit 的 sentence_text 从未暴露给模型（注：该工具现名 stablemem_commit，本条保留 1.1.1 发布时的原名）（而它是媒体绑定链的必经环节）、PluginSDK 两处并发竞态（-race 实测 11 处，插件重载瞬间偶发 nil 解引用崩溃）。
v1.1.0 — 记忆系统支持二进制多媒体节点。内容寻址媒体存储（CAS + SQLite 元数据 + 磁盘 blob，Get always 重校 digest），贯通 L0（上下文事件）/L2（文档）/L3（图谱句子）三层，引用计数式 GC（有引用者绝不删）。视觉模型生成的描述文本是持久语义记忆，blob 只是可被容量 GC 淘汰的缓存。
v1.0.0 — 外部插件从 C ABI 动态库迁移到子进程 + 共享内存。首个不再加载 .so/.dll 的版本，与 0.9.x 不兼容（存量插件须用新版工具链重编；该工具链当时名为 plugindev，现名 hmapdev）。外部插件需重编为 plugin.bin，业务代码零改动）。消除 6 类此前在生产造成故障的缺陷：热重载失效（DF_1_NODELETE 让 dlclose 成 no-op）、崩溃隔离缺失（插件 panic 带崩 homed）、stage lost update（副本模型丢失 35.8~36.8%）、cgo 超时不可中断（线程线性泄漏）、output_send 假成功（模型收到「已发送」而消息未送达）、Windows 能力断层（只见 3 个 stage 字段且无法写回）。三面通信：stdio JSON-RPC（控制）+ 共享内存段（数据）+ 事件环（通知）；权限梯度显式化为三道闸。RPC 往返 p50 24.1µs，崩溃到恢复 <1s。
v0.9.0 — C ABI v2：外部插件 Stage 回调支持写回（invoke_stage 增加 result 输出，插件可在 OnInput/AfterToolcall/PostAction 修改 RawMessage/LLMText/ToolResults 等并同步回内核），ABI 版本随内核 minor 对齐（v0.9.x → ABIVersion=2，version_min=1 向后兼容旧插件）。同步修复工具循环 zen 兼容补位误伤首轮 system 上下文的问题。配套 SDK 提供增强版 sanitizer 示例（坏 UTF-8/U+FFFD/ANSI 转义全链路清洗）。该 ABI 已随 v1.0.0 退场。
v0.8.0 — 核心可用，插件系统增强。内置 20+ 插件，外部插件开发见 hologramagentsdk 仓库。新增输入通道 NoMemory/Cleaner、ChannelDef、插件禁用/启用系统（CLI + WebUI），plugindev 工具链完成 C ABI ChannelDef 传递。