mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-10-15 12:15:16 +00:00
docs: 修正「项目概览/架构」把已删除机制写成现行机制(中英四份)
## 问题
assets/docs/{zh,en}/OVERVIEW.md 的媒体记忆段仍在描述 v1.2.0 **已整体拆除**的机制,
且两份文档的第一读者入口(README「文档」区、site/index.html 的「项目概览」链接)
都指向它。docs/git-branching.md §七.7 的反例表里恰好列着这一条,说明这是
「文档当事实后反向误导」的复发项。
同时修掉同一批里其余过期的结构性断言(均为逐条回源码核实后改)。
## 改动(四份文件,7 处)
OVERVIEW.md(zh/en 对称):
- 媒体记忆段:「引用计数 GC + 描述文本才是持久语义记忆 + [<mime> <digest>] 标记」
→ 「一等记忆块:块自带向量与指纹直接检索;无独立 GC / 无引用计数 / 无 keep-set;
删除块即删内容」,并显式注明旧机制已在 v1.2.0 拆除
- 依据:internal/memory/block.go("不携带 Layer、Owner 或 RefCount")、
ARCHITECTURE.md 自身的「不再有描述式索引」段、
graphmedia_test.go:24「描述文本、marker 反解…全部已废弃」、
inputunify_test.go:226「不往文本里贴 marker」
- LLM Provider 段:「三种实现 OpenAIProvider/OllamaProvider/LuaAdaptedProvider」
→ 「唯一实现 LuaAdaptedProvider」
- 依据:internal/agent/api/provider.go 只有 LuaAdaptedProvider 一个实现类型
- 适配器:「内置 8 个」→「内置 10 个」并补全名单(+kimicode/server)
- 依据:ls internal/lua/adapters/*.lua = 10;README.md 同一处早已写「10 个」,
两份文档此前自相矛盾
- 「支持 8 个 LLM 源自动降级」→「多源自动降级」
- 依据:源数量由部署配置,默认 seed 仅 deepseek 一个
(registry.go defaultSources 唯一条目)
ARCHITECTURE.md(zh/en 对称):
- 代码结构树 internal/skill/(**该目录不存在**)→ 移入 plugins/skillmgr/
- 依据:internal/plugins/skillmgr/ 存在,internal/skill/ 不存在(README 亦写 plugins/skillmgr)
- dynamic.go 描述「.so 动态加载器」→「加载通道分派(proc/lua/skill);.so 仅剩给明确报错」
- 依据:dynamic.go 的 tryDynamic 实际只分派 proc 与 lua,.so 命中只为给出「请用新版
hmapdev 重编」的明确错误(legacyCABIEntries 注释)
- 配置系统「8 个 LLM 源的 seeds」→「含 1 个 LLM 源 seed,其余源由部署时添加」
- 适配器数 8 → 10
- Provider 分层图(仅 en 侧滞后):删掉不存在的 OpenAIProvider/OllamaProvider
- 依据:zh 侧同一图早已写作「LuaAdaptedProvider (唯一实现)」,en 侧未跟上
## 验证
- 全量残留扫描:OpenAIProvider / OllamaProvider / 引用计数 GC /
Reference-counted GC / 8 个 LLM / 8 LLM / internal/skill / .so 动态加载
→ 在 assets/docs/ 与两份 README 中均为 **0 命中**(改前分别为 3/2/2/1/2/1/2/2)
- 每条新断言逐条回源码核实(adapters=10、provider struct=1、skillmgr 存在、
internal/skill 不存在、defaultSources=1、无 marker 写入代码)
- 纯文档改动:不涉及 .go,不改变构建产物(assets/docs 未被 //go:embed 打包,
仅被 site/index.html 以 GitHub 链接形式引用)
- 未新增版本号字面量,符合 §七.7 的「模型或用户会当作事实的文本不得写死版本号」
## 分支归属
按 docs/git-branching.md §七.7:面向使用者的开发者文档先落 release 线、
再 cherry-pick 合入 main(不 merge)。本次提交在 release/v1.3.x。
This commit is contained in:
@ -25,16 +25,17 @@ HomeAgent 是一个持续运行的个人智能 Agent 框架。
|
||||
|
||||
三层递进:上下文 → 冷归档 → 长期图记忆,构成从短期到持久的信息衰减与整合管道。
|
||||
|
||||
**媒体记忆(v1.1.0 起)** — 图片/音频不是附属物,而是三层里的一类节点:
|
||||
- **内容寻址存储(CAS)**:digest 寻址,元数据在 SQLite、blob 在磁盘,相同字节只存一份,
|
||||
**媒体记忆(v1.2.0 起:一等记忆块)** — 图片/音频不是附属物,而是记忆的一等节点:
|
||||
- **内容寻址存储(CAS)**:digest 寻址,元数据在 SQLite、blob 在磁盘(两级分桶),相同字节只存一份,
|
||||
每次 `Get` 重校 digest(磁盘损坏静默返回脏数据比报错更危险)
|
||||
- **引用计数 GC**:`owner_kind/owner_id/digest` 三元组为主键,上下文事件/文档/图谱句子各自持引用;
|
||||
**有引用者绝不删除**,仅回收无主且超过 `minAge` 的内容
|
||||
- **描述文本才是持久语义记忆**:视觉模型生成的描述以
|
||||
`[<mime> <短digest>] <描述>` 标记形式写进纯文本记忆,参与向量检索与蒸馏;
|
||||
blob 只是可被容量 GC 淘汰的缓存。几个月后“那张紫蓝红三色带图”仍可检索,靠的是描述而不是字节
|
||||
- **媒体块直接参与向量检索**:块携带**自己的多模态向量与指纹**,正文里不再有任何媒体标记
|
||||
- **无独立 GC、无引用计数、无 keep-set**:记忆块遵循单层不变量——Context → Document → Graph
|
||||
是块的**迁移**,不是复制、也不靠引用保活;**删除块即删内容**
|
||||
- **v1.1.1 起贯通插件边界**:插件可通过 `InsertWithMedia` / `InjectInputMedia` 读写媒体,
|
||||
模型可用 `memory_commit` / `doc_commit` 的 `media_digests` 参数关联媒体
|
||||
- **旧机制已整体拆除**:此前把视觉模型生成的描述写进正文、以 `[<mime> <短digest>] <描述>` 标记
|
||||
参与检索的**描述式索引**,以及 `media_refs` 引用计数,均已在 v1.2.0 删除——描述是模型生成的
|
||||
二手信息,检索「别人转述的图片」不如检索图片自己的向量
|
||||
|
||||
## 它实际做了什么
|
||||
|
||||
@ -45,7 +46,7 @@ HomeAgent 是一个持续运行的个人智能 Agent 框架。
|
||||
- `process.go` / `stages.go` — 处理管道:记忆召回 → 人格注入 → LLM 调用 → 工具执行 → 输出发送,7 阶段钩子
|
||||
- `toolcall.go` — 工具调度与执行
|
||||
- `context.go` — 上下文管理(预训练词嵌入评分 StaticEmbedder → CosineSimilarity,TF-IDF 回退),自动剪枝低相关性事件
|
||||
- LLM 调用通过 Provider 接口抽象,支持 8 个 LLM 源自动降级
|
||||
- LLM 调用通过 Provider 接口抽象,多源自动降级
|
||||
|
||||
**记忆系统** (`internal/memory/`):
|
||||
- **GraphDB** (`graph.go`) — SQLite,entities + relations 表,BFS 遍历
|
||||
@ -69,9 +70,10 @@ HomeAgent 是一个持续运行的个人智能 Agent 框架。
|
||||
|
||||
**LLM Provider** (`internal/agent/api/provider.go`):
|
||||
- Provider 接口:Name / Chat / ChatStream
|
||||
- 三种实现:OpenAIProvider(标准 OpenAI API)、OllamaProvider(本地)、LuaAdaptedProvider(Lua 胶水适配)
|
||||
- LuaAdapter 位于 `internal/lua/adapters/`,每个 LLM 源对应一个 `.lua` 脚本
|
||||
- 内置 8 个适配器:deepseek / openai / anthropic / gemini / mistral / groq / github / ollama
|
||||
- 唯一实现 `LuaAdaptedProvider`:所有源都经 Lua 适配脚本做请求/响应变换;
|
||||
适配器脚本位于 `internal/lua/adapters/`,每类协议一个 `.lua` 脚本
|
||||
- 内置 10 个适配器:deepseek / openai / anthropic / gemini / mistral / groq / github / kimicode / ollama / server
|
||||
- 源(`core.llm.sources.<name>.*`)由部署时配置,数量不固定,不随内置适配器数绑定
|
||||
|
||||
**WebUI** (`internal/plugins/webui/`):
|
||||
- 嵌入式 SPA 仪表盘(`dashboard.html` 通过 `//go:embed` 打包)
|
||||
|
||||
Reference in New Issue
Block a user