docs: README 更新到 v1.2.0,并纠正已在 v1.2.0 删除的机制

README 的「项目状态」停在 **v1.1.1**,而且其中两条描述与当前实现**相反**:
「媒体以 `[<mime> <短digest>] <描述>` 标记存在于纯文本记忆中,描述是可检索的
语义记忆」与「引用计数式 GC(有引用者绝不删)」——这两套机制正是 v1.2.0 拆掉的。

本次不重写历史条目(它们记录了演进),而是:

1. 「项目状态」顶部新增 **v1.2.0** 条目:统一多模态向量空间(模型中立 SPI +
   Chinese-CLIP 默认,含「纯文本语义弱于 MLLM 型嵌入器」这一已知代价)、
   媒体升为图记忆一等节点(并写明具体删掉了什么)、数据面全量走共享内存
   (协议 2、不支持滚动升级)、注入标志位、发行包默认启用 ONNX 且随包模型、
   homed 改走 WSL2、以及三个安装链静默失败的修复。
2. 在 v1.2.0 条目后加一条显式提示:下方历史条目中的「描述式索引」与
   「媒体引用计数式 GC」**已在 v1.2.0 移除**——避免读者按旧文档理解现行行为。
3. 「下载」:Windows 安装器的版本号改到 v1.2.0,并写明自 v1.2.0 起因 homed
   不再支持 Windows 原生,安装器改为引导到 WSL2 并在其中按 Linux 方式安装;
   同时注明安装器含 AGPL 许可页。

中英双份同步。SDK 仓 README 另在 SDK 仓提交(d893bfa)。
This commit is contained in:
JianFeeeee
2026-09-12 09:27:28 +08:00
parent 5e10f012cb
commit 0b1c201b5c
2 changed files with 63 additions and 2 deletions

View File

@ -195,6 +195,33 @@ internal/
## 项目状态 ## 项目状态
**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.15GB
`qwen3vl` 保留2048 维、常驻约 9.4GB,供内存充足或将来要视频的机器切回)。
文本检索仍由既有词向量 / TF-IDF 兜底CLIP 双塔的**纯文本语义弱于 MLLM 型嵌入器**
这是已知并写进文档的代价。
- **媒体是图数据库的一等节点与边****彻底删除**「用文本描述式索引图片」这套将就机制,
以及 `media_refs` 与媒体引用计数。记忆块遵循单层不变量——Context → Document → Graph
是块的**迁移**,不是复制、也不靠引用保活。
- **数据面全部走共享内存**(工具调用帧 / Cleaner / 输入输出通道 / 媒体块 / 文档与知识正文),
RPC 只传偏移描述符;**RPC 协议升到 2**fd3 布局改变,**不支持滚动升级**——
内核与全部插件必须同批重建、同批安装,存量插件须用新版 `plugindev` 重编。
- 注入可声明 `InjectOptions{NoMemory, ContextPolicy}`**默认仍记入记忆、默认不裁剪**
裁剪必须显式声明,且先经插件注册的 `Cleaner`。SDK 1.2.0 相对 1.1.0 **纯追加**
- **发行包默认启用** ONNX 向量空间并把模型754MB与 ONNX Runtime24MB
server/full 包发布;`homed` 放弃 Windows 原生支持改走 WSL2jieba 词库内嵌进二进制。
- 修掉三个**安装链静默失败**`initconfig``CGO_ENABLED=0` 是空操作(打印凭据却一个字节
没写)、全新安装被误判「已有配置」而整体跳过默认值播种(装完 0 插件、deb 的 `postinst`
查错 unit 路径导致 `enable` 从未执行。
- 自本版起以 **AGPL-3.0-only** 发布(含网络条款;插件静态链接 SDK 故须同许可,见「许可」)。
> 以下历史条目保留原文以呈现演进,其中两条机制**已在 v1.2.0 移除**
> 「媒体以 `[<mime> <短digest>] <描述>` 标记参与检索」(描述式索引)与「媒体引用计数式 GC」。
**v1.1.1** — 多模态贯通**插件边界**。v1.1.0 让记忆系统支持了二进制多媒体节点,但那条链路只对内核自己开放;本版打通到插件与模型。公开 SDK 新增媒体字段与三个媒体注入接口(配套 [SDK v1.1.0](https://gitcode.com/JianFeeeee/homeagent-sdk/releases/tag/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` 从未暴露给模型**(而它是媒体绑定链的必经环节)、**`PluginSDK` 两处并发竞态**`-race` 实测 11 处,插件重载瞬间偶发 nil 解引用崩溃)。 **v1.1.1** — 多模态贯通**插件边界**。v1.1.0 让记忆系统支持了二进制多媒体节点,但那条链路只对内核自己开放;本版打通到插件与模型。公开 SDK 新增媒体字段与三个媒体注入接口(配套 [SDK v1.1.0](https://gitcode.com/JianFeeeee/homeagent-sdk/releases/tag/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` 从未暴露给模型**(而它是媒体绑定链的必经环节)、**`PluginSDK` 两处并发竞态**`-race` 实测 11 处,插件重载瞬间偶发 nil 解引用崩溃)。
**v1.1.0** — 记忆系统支持**二进制多媒体节点**。内容寻址媒体存储CAS + SQLite 元数据 + 磁盘 blob`Get` always 重校 digest贯通 L0上下文事件/L2文档/L3图谱句子三层引用计数式 GC有引用者绝不删。视觉模型生成的描述文本是持久语义记忆blob 只是可被容量 GC 淘汰的缓存。 **v1.1.0** — 记忆系统支持**二进制多媒体节点**。内容寻址媒体存储CAS + SQLite 元数据 + 磁盘 blob`Get` always 重校 digest贯通 L0上下文事件/L2文档/L3图谱句子三层引用计数式 GC有引用者绝不删。视觉模型生成的描述文本是持久语义记忆blob 只是可被容量 GC 淘汰的缓存。
@ -224,7 +251,7 @@ internal/
| **client** | waiter + 桌面 GUI | 连接远程 HomeAgent | | **client** | waiter + 桌面 GUI | 连接远程 HomeAgent |
- Linux`.deb`amd64/arm64)、`.rpm`x86_64)、`.tar.gz` - Linux`.deb`amd64/arm64)、`.rpm`x86_64)、`.tar.gz`
- Windows`HomeAgent_v1.1.1_{Full,Server,Client}_win64.exe`NSIS 安装向导 - Windows`HomeAgent_v1.2.0_{Full,Server,Client}_win64.exe`NSIS 安装向导 AGPL 许可页)。 v1.2.0 起因 `homed` 不再支持 Windows 原生依赖 fd 继承与共享内存段内偏移解引用安装器改为引导到 **WSL2**并把 Linux 包送进发行版里按 Linux 方式安装
- 免安装`homeagent-bin-<os>_<arch>.tar.gz` homed/waiter/initconfig - 免安装`homeagent-bin-<os>_<arch>.tar.gz` homed/waiter/initconfig
- 校验`SHA256SUMS` - 校验`SHA256SUMS`

View File

@ -184,6 +184,40 @@ External plugin development: see [homeagent-sdk](https://gitcode.com/JianFeeeee/
## Project Status ## Project Status
**v1.2.0** — unified multimodal vector space, media promoted to first-class graph memory, and the whole data plane moved into shared memory.
- **Model-neutral unified embedding space**: the kernel no longer adapts to any specific model.
It exposes only a public provider SPI (`pkg/embedding`: `Modality` / `Input{Data,MIME}` /
`Info{Dimension,Fingerprint,Modalities}` + a name registry), with implementations under
`providers/*`. Default: **Chinese-CLIP ViT-B/16** — text and image land in the **same space**
(512-dim, fingerprint `cd2a495cf990`, Apache-2.0, ~1.15GB RSS measured standalone);
`qwen3vl` is kept (2048-dim, ~9.4GB) for machines with headroom or future video. Text search
still falls back to the existing word-vector / TF-IDF path — a CLIP dual tower's pure-text
semantics are **weaker than an MLLM-style embedder**, a cost documented rather than hidden.
- **Media are first-class nodes and edges in the graph DB**: the "index images via generated
text descriptions" stopgap, `media_refs` and media reference counting are **removed**.
Memory blocks follow a single-layer invariant — Context → Document → Graph is a **migration**,
not a copy, and not kept alive by references.
- **The entire data plane goes through shared memory** (tool-call frames, Cleaners, input/output
lanes, media blocks, document and knowledge bodies); RPC carries only offset descriptors.
**RPC protocol is now 2**: the fd3 layout changed and there is **no rolling upgrade**
kernel and all plugins must be rebuilt and installed together.
- Injections can declare `InjectOptions{NoMemory, ContextPolicy}` (**defaults: still recorded,
not pruned**); pruning must be requested explicitly and goes through the plugin's registered
`Cleaner`. SDK 1.2.0 is **purely additive** over 1.1.0.
- **Release packages enable the ONNX space by default** and bundle the model (754MB) plus
ONNX Runtime (24MB) in the server/full packages; `homed` drops native Windows support in
favour of WSL2; the jieba dictionary is embedded in the binary.
- Fixed three **silent install-chain failures**: `initconfig` was a no-op (`CGO_ENABLED=0` stub)
that printed credentials without writing any, fresh installs were misdetected as "already
configured" so default seeding was skipped entirely (0 plugins installed), and the deb
`postinst` looked for the unit in the wrong path so `enable` never ran.
- Licensed **AGPL-3.0-only** from this version on (network clause included; statically linked
plugins must match — see License).
> The historical entries below are kept verbatim to show the evolution; two mechanisms in them
> were **removed in v1.2.0**: text-description-based media indexing, and reference-counted media GC.
**v1.1.1** — Multimodal reaches the **plugin boundary**. v1.1.0 gave the memory system binary **v1.1.1** — Multimodal reaches the **plugin boundary**. v1.1.0 gave the memory system binary
multimedia nodes, but that path was open only to the kernel itself; this release opens it to multimedia nodes, but that path was open only to the kernel itself; this release opens it to
plugins and the model. The public SDK gains media fields and three media injection methods plugins and the model. The public SDK gains media fields and three media injection methods
@ -231,7 +265,7 @@ semantic memory; the blob is only a cache that capacity GC may evict.
| **client** | waiter + desktop GUI | Connecting to a remote HomeAgent | | **client** | waiter + desktop GUI | Connecting to a remote HomeAgent |
- Linux: `.deb` (amd64/arm64), `.rpm` (x86_64), `.tar.gz` - Linux: `.deb` (amd64/arm64), `.rpm` (x86_64), `.tar.gz`
- Windows: `HomeAgent_v1.1.1_{Full,Server,Client}_win64.exe` (NSIS installer) - Windows: `HomeAgent_v1.2.0_{Full,Server,Client}_win64.exe` (NSIS installer, includes the AGPL license page). Since v1.2.0 `homed` no longer supports native Windows (it relies on fd inheritance and in-segment offset dereferencing), so the installer bootstraps **WSL2** and installs the Linux packages inside the distribution the same way a Linux host would.
- Portable: `homeagent-bin-<os>_<arch>.tar.gz` (homed/waiter/initconfig) - Portable: `homeagent-bin-<os>_<arch>.tar.gz` (homed/waiter/initconfig)
- Verification: `SHA256SUMS` - Verification: `SHA256SUMS`