docs: 第二层改名 Cold Context,清理四组已不存在的符号名

## 问题

README 与两份 ARCHITECTURE / OVERVIEW 仍在用旧称「Document 层」,
而第二层早已改名 cold context(工具名 `coldcontext_query` / `coldcontext_commit`)。

不止是层名。文档里引用的四个符号在代码里**一个都不存在**:

| 文档里写的 | 代码里实际 |
|---|---|
| `docStore.ContextToDoc` | `coldcontextStore.ContextToColdContext` |
| `FindColdDocs` | `FindColdContexts` |
| `docToTriples` | `coldDocToTriples` |
| `docStore.SetVectorizer` | (已无此调用,embedder 构造期注入) |

四处都用 `grep -rn "\b名字\b" --include=*.go` 确认过:旧名 0 处,新名各自 4 处。

## 改了什么

- `assets/docs/zh/ARCHITECTURE.md` 13 处、`en/ARCHITECTURE.md` 15 处
- `assets/docs/zh|en/OVERVIEW.md` 各 3 处
- README 两版:「文档层」→「冷上下文层」
- `assets/branding/mascot-xiaozhai-guide.md` 的丝带配色表(三色分别对应三层)

## 顺带修正层号

ARCHITECTURE 用的是 **L1 Context / L2 Cold Context / L3 Stable**,
我上一版 README 写成了 L0/L1/L2 —— 少了一层,且与架构文档对不上。已改为 L1/L2/L3。

## 顺带修掉断掉的交叉引用

`internal/agent/core/toolcall.go` 与 `recallcoldcontext_test.go` 的注释写
「ARCHITECTURE「记忆流转」② Document 层的读取分支」,指的正是刚改名的节。
不改就成了悬空引用。三个测试函数名(`TestContextToDoc` 等)指向已删函数,一并改名。

## 验证

- 全仓 `grep` 旧名:`*.md` / `*.go` 均 0 处(排除 build/third_party/.pi)
- `go build ./...` ✓
- `go test ./internal/memory/coldcontext/ ./internal/agent/core/` ✓
This commit is contained in:
JianFeeeee
2026-10-31 11:39:13 +08:00
parent 6a2c907e04
commit 7c0eec1b2f
10 changed files with 68 additions and 92 deletions

View File

@ -14,12 +14,12 @@ make build build-cli
API 密钥在 WebUI(`http://localhost:8080`)里填。需要 Linux。
跟常见 agent 框架的主要差别在上下文管理:不是超窗就截断或让模型摘要,
而是按相关度取舍,低分的下沉成文档、再蒸馏进图数据库。另外两处不太一样的是
而是按相关度取舍,低分的下沉成冷上下文、再蒸馏进图数据库。另外两处不太一样的是
启动顺序在编译期定序,以及插件按设施就绪提前启动(详见下方架构)。
## 架构
```
```text
homed(内核)
LLM 编排 · 三层记忆 · 检索 · 调度
│
@ -40,9 +40,9 @@ API 密钥在 WebUI(`http://localhost:8080`)里填。需要 Linux。
### 上下文不是「截断 + 摘要」
常见做法是把超窗的对话裁掉或让模型自己摘要,两者的共同问题是**丢什么由位置决定**。
这里换成了按相关度取舍:用当前输入给每条历史事件打分,低分的下沉到文档层。
这里换成了按相关度取舍:用当前输入给每条历史事件打分,低分事件下沉到冷上下文层。
打分用稠密向量余弦(与媒体、文档共享同一向量空间),模型未就绪时退化到 TF-IDF。
打分用稠密向量余弦(与媒体、冷上下文共享同一向量空间),模型未就绪时退化到 TF-IDF。
裁剪时无条件保住最近 N 条,但 N 本身受预算约束:
```go
@ -55,18 +55,18 @@ pCount = min(配置值, budgetCap)
「钉住 10 条」本身就装不下,于是每轮裁剪都撞保护下限,两轮后预算耗尽,任务直接终止。
召回率从 44% 掉到 22%。现在窗口越小越自动收紧,1M 窗口下则能用满配置值。
被裁掉的事件不是丢弃,是迁移:事件连同它持有的媒体块一起进文档层,块的 ID 不变、
被裁掉的事件不是丢弃,是迁移:事件连同它持有的媒体块一起进冷上下文层,块的 ID 不变、
只换持有层。回灌时用 `coldcontext_query` 取回,两阶段(先 Peek 确认、再 Remove),
不用「先删后灌」——那会在回灌失败时永久丢数据。
### 三层记忆是迁移,不是复制
```
L0 上下文 相关性裁剪,最近 N 条恒受保护
↓ 低分事件下沉(带媒体块)
L1 文档 稠密检索,访问计数 ≤2 且久未访问则继续下沉
↓ 蒸馏成三元组
L2 图 实体关系 + 场面索引,支持按场面召回
```text
L1 上下文 Context 相关性裁剪,最近 N 条恒受保护
↓ 低分事件下沉(带媒体块)
L2 冷上下文 Cold Context 稠密检索,≤2 次访问且 72h 未访问则继续下沉
↓ 蒸馏成三元组
L3 稳定记忆 Stable 实体关系 + 场面索引,支持按场面召回
```
块在任一层只有一份持有者,不靠引用计数保活。媒体不是附件:图片、音频是图里的一等节点,
@ -142,13 +142,9 @@ Windows 上构建 `waiter.exe`,`homed` 跑在 WSL2 里;macOS 要原生构建
## 许可
内核以 **AGPL-3.0-only** 发布([LICENSE](LICENSE))。改过的版本如果对外提供网络服务,
必须向使用者提供源码(§13)。
以 **AGPL-3.0-only** 发布,全文见 [LICENSE](LICENSE)。
自己写的插件不受此约束。插件静态链接的 [hologramagentsdk](https://github.com/JianFeeeee/hologramagentsdk)
是 **MIT**,宽松许可不继承 AGPL,所以外部插件可以闭源、可以商用,也不必开源自改。
随包第三方组件保持各自许可,全文在 `/usr/share/doc/hologramagent/licenses/`。
随包的第三方组件保持各自许可,全文在 `/usr/share/doc/hologramagent/licenses/`。
### 随包分发的第三方组件
@ -159,5 +155,4 @@ Windows 上构建 `waiter.exe`,`homed` 跑在 WSL2 里;macOS 要原生构建
| jieba 词库(内嵌进二进制) | MIT | 源码 `internal/memory/jiebadict/` |
| Go 依赖(go-sqlite3、gojieba、bubbletea 等) | MIT / BSD-3 / Apache-2.0 | 均为宽松许可,与 AGPL-3.0 兼容 |
这些组件**保持各自原有许可**,不在本项目的 AGPL 授权范围内;发行包把它们的许可全文放在
`/usr/share/doc/hologramagent/licenses/`,并在 dep/rpm 元数据里声明本包许可为 `AGPL-3.0-only`。
发行包在 dep/rpm 元数据里声明本包许可为 `AGPL-3.0-only`。