jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-11-05 16:57:32 +00:00
Code Issues Packages Projects Releases Wiki Activity
1,065 Commits 5 Branches 29 Tags
a8ce5ece30800d656d363e818b40c3fbbabfdcd3
Commit Graph

8 Commits

Author SHA1 Message Date
JianFeeeee
b850feaef2 feat: 段页式记忆流转、coldcontext 重命名与安全治理 
记忆层：
- MemoryBlock 承载 FrameTS/PageSeq/PageKind/BlockRole/CallID
- coldcontext 归档与回填按完整页传递，工具调用参数和配对键不丢失
- 召回先估算总 token，超预算时按全局页相似度标记 inactive
- inactive 仅是 context 渲染期状态，不落盘、不进入 coldcontext，Prune 后重置
- Peek/确认/Remove 两阶段召回，失败保留冷上下文副本
- stablemem 记录 last_recalled_at，删块连带清理边

命名：
- internal/memory/document → internal/memory/coldcontext
- Doc/DocEvent/DocHit → ColdDoc/ColdEvent/ColdHit
- ContextToColdContext/RecentColdContexts/FindColdContexts
- 保留既有 JSON 标签、doc_ 文件前缀与 doc_count 状态键，兼容存量数据

安全治理：
- 工具策略门禁、安全配置、事件总线发布者身份与入站脱敏
- 声明式 SecurityAPI 与 QQ owner/guest profile
- 日志保留策略与相关 e2e/回归判据

验证：go build ./...、go vet ./...、go test ./...（62 包）；
生产副本 e2e：7013 块迁移后 ID/向量/指纹 0 变化、0 缺失。
 2026-10-29 23:53:48 +08:00
JianFeeeee
47c95efb80 feat(memory): L2 与 L1 同构 —— 事件列表承载原文，正文内联在块里 
块化重构（memory-restructure-plan）换了底层数据结构，但 L1↔L2 的流动没跟着改，
导致这条链出现结构性失效。本次按设计原文修复。

## 断点（生产实测）

**① L2 只存渲染视图，事件本体丢失**

ContextToDoc 把每条事件拍平成一行：truncate(Response,100)、truncate(工具输出,200)。
生产库 1000 篇归档文档实测：
  - response 段恰好 103 字符（=100+"..."）：311/2094 = 15.1%
  - 工具输出段恰好 203 字符：7593/13261
  - ToolsUsed 完全不存
⇒ 原文在落库那一刻就不存在了，召回再全也拿不回来。

**② L2 里没有文本块，与 L1 不同构**

L2 块分布 image 437 / audio 7 / text 0 —— 文本全靠 Content 这个视图。

**③ 召回造合成事件，时间戳用归档时刻**

doc_query 用 d.CreatedAt 造一条 cold_storage 事件、正文取 Content 再截 2000 字、
且完全不回填 Blocks。块自带 created_at（捕获时刻），实测与 doc.created_at
差近两小时，却没人用。

**④ 块在 Consume 时两层同时消失**

Consume 从内存与磁盘同时删除文档，而块的字节只存在于那个 .json 里。
生产 L2 有 444 个块，其中 396 个不在 L3（约 248MB）—— 一旦被命中即永久丢失。

## 修法（按设计，不是按我的推断）

设计前提（写进 ARCHITECTURE 与计划文档）：
  · 记忆块是唯一物理载体，层是持有关系
  · L1 与 L2 结构同构，唯一区别是「是否直接投喂给模型」
  · 正文（含多媒体正文）内联在块里；事件只是块的容器
  · 任何一层都不压缩（视图不是记忆）
  · 内核不得硬编码任何插件行为

1. Doc 增加 Events []DocEvent（与 ContextEvent 同构），成为文档主体
2. 正文各自成块：Input 一块、Response 一块（BlockText，Text 即正文）
3. restoreDocEvents 逐条按原始时间戳迁回 L1，块随事件迁回
4. Content 保留为渲染视图（contentFromEvents 生成），不再是原文载体
5. 蒸馏 docToTriples 改用 documentOriginalText：从块读原文，不再用视图
6. 删掉 ARCHITECTURE 里「过滤 agentcli/terminal 来源」——那是内核硬编码
   插件名，改由插件经 NoMemory/Cleaner 声明

## 顺带修掉的真实缺陷

simpleHash 是 O(n²) 且哈希串长度正比于内容：
    for _, c := range s { h += fmt.Sprintf("%x", c) }
压力测试实测 1.25MB 正文归档耗时 **270 秒**；生产实测 content_hash
是 content 的 2.2 倍（52072 字 → 114491 字）。
换成 sha256 前 16 字节：**270s → 0.52s（520 倍）**，定长 32 hex。

## 存量

按拍板不迁移，等系统自然冲刷。降级路径：无 Events 的旧文档仍按旧行为召回
（整篇渲成一条事件），不伪造成「有原始事件」。生产副本实测 1104 篇旧文档
全部正常加载。

## 判据（16 条，全部有变异自证）

document/blockflow_test.go（11 条）：正文完整性、文本块粒度、逐条保留、
视图定位、幂等、存量兼容、原文可用性、hash 线性、3 条压力
core/recalldoc_test.go（5 条）：逐条回填、原始时间戳、块迁回、
回填不截断、存量降级、批量压力

变异全部被抓：
  · 落库 truncate(100)        → ArchivePreservesFullText（实测 len=303/原 10215）
  · Input/Response 合成一块    → InputAndResponseAreSeparateTextBlocks（实际 1）
  · 召回用 d.CreatedAt         → RestoresEachEventAtOriginalTimestamp（回填 1/期望 3）
  · 召回不回填 Blocks          → MigratesBlocksBackToContext
  · 召回再截 2000 字           → TextIsNotTruncatedOnTheWayBack（2003/原 18020）
  · 恢复 O(n²) hash            → HashIsLinearAndFixedLength（超时 >300s）

## 验证

- go build ./... 通过
- go test ./... -count=1：58 包 0 失败
- go test -race ./internal/memory/document/ ./internal/agent/core/：通过
- 生产数据副本实际启动：1104 篇文档加载正常、0 崩溃、干净退出
- 副本 e2e：新归档 2 事件 / 4 文本块、正文 3207 字完整回读、时间戳精确

## 不改

- 公开 SDK 契约（TextEvent / DocMemoryAPI / InsertWithMedia 已等价）
- 存量文档（等自然冲刷）
- 渲染层截断常数（独立议题，避免与本次修复互相掩盖）
 2026-10-22 11:09:13 +08:00
JianFeeeee
4e70b8d5d8 refactor(module): 核心仓 Go module 路径改为 github.com/JianFeeeee/HologramAgent 
批 1，不含 SDK 仓与目录改名。

- go.mod 第 1 行 module 路径
- 366 个 .go 文件的完整前缀 github.com/JianFeeeee/HomeAgent 机械替换
  （857 处，仅完整前缀；展示名/注释里的 HomeAgent 字样留给批 5）
- 未改：third_party 目录名、SDK 自身 go.mod module、go.mod replace 目标、
  homed/waiter 可执行名、.hmap 后缀
 2026-10-21 12:17:19 +08:00
JianFeeeee
33e1a0bfaf test(memory)!: 块 union 化判据重写（CAS 淘汰第二阶段：测试） 
生产已在上一提交(86572d13)全绿；本提交把 CAS 专属测试改到块语义，
并修掉几处判据自身的缺陷（判据错 ≠ 生产错）：

- sdk/memory_impl_test: media.Store→块；NewGraphMemoryWithPlugin
- core/{graphmedia,mediaref,medialive,medialoop,inputunify}_test:
  mediaStore→memory；PayloadDigest→Data/BlockData；shortDigest→shortID
- graphmedia: 无引用句子用独立块 ID（shortID 20 字符会与 blk_src_ 撞长度）
- memory/sentence_block: BlockByIDPrefix 加 len<12 下限（短引用守卫）
- core/medialoop: reembedOneBlock 按 BlockData 兜底取字节（lean 列无 data）
- knowledge: broken.png 改目录造读失败（chmod 0000 对 root 无效）；
  dense/attach 测试补 Data 并先落盘后 AttachMedia
- webui: graph_pulse fixture payload_digest→has_data

注：internal/plugin/proc 的 shmVersion 不匹配(内核1/插件2)是
SDK 仓(777c3a0,v2 模板)与本分支内核(v1)的跨仓版本错位，
与块 union 无关（stash 全部改动后仍复现），属 proc-extra 特性线。
 2026-10-12 14:26:13 +08:00
JianFeeeee
6d38a164eb chore(module): Go module 路径随托管地迁移 gitcode → github 
## 背景

仓库早已迁移到 GitHub（`github.com/JianFeeeee/HomeAgent`，CI/CD 都在那边跑），
gitcode 保留为**国内只读镜像**（`ci.yml` 的 sync-gitcode-main 快进推送）。
但 go.mod 的 module 路径一直是 `gitcode.com/JianFeeeee/...` —— 既与权威源
不符，`meta.SourceURL`（AGPL §13 的源码提供入口）也指向镜像而非实际运行的代码。

## 关键区分（这是本次改动安全的前提）

两个 module 是**不同**的，影响面差一个数量级：

| module | 谁依赖 | 改它的后果 |
|---|---|---|
| `.../HomeAgent`（主仓） | **只有主仓自己** | 内部重构，零外部影响 |
| `.../homeagent-sdk`（SDK 仓） | 主仓 49 文件 + 所有外部插件 | 需重编插件 |

★ 实测确认：**插件不 import 主仓 module**（`strings qq/plugin.bin | grep HomeAgent` = 0），
只依赖 SDK 仓。而插件与内核的边界是 **RPC 方法名字符串**
（`plugin.init` / `tool.invoke`…，见 proc/protocol.go），**与 Go module 名无关**。
⇒ module 改名**不改变任何 wire 协议**，现网已装的插件照常运行。

SDK 的 GitHub 仓名是 `homeagentsdk`（无连字符），module 路径必须与之精确匹配，
否则 `go get` 会因路径不符失败，故取 `github.com/JianFeeeee/homeagentsdk`。

## 改动

- `go.mod` / `go.sum`：两个 module 路径 + require/replace
- 277 个 Go 文件 + Makefile + 打包脚本的 import 与 ldflags 路径
- SDK 仓 `meta.CoreModule`、`tools/hmapdev` 的 module 声明与工程模板
- 对外文档/链接的仓库地址（README、PLUGIN_DEV、OVERVIEW 等）

## 明确**保留** gitcode 的地方（镜像机制，不能动）

- `GITCODE_TOKEN`、`GC_URL="…@gitcode.com"`（CI 同步 job）
- `gitcode.com/api/v5/...`（release 附件上传）
- git remote `gitcode`（镜像拉取/推送）
- `docs/zh/ci-cd-runbook.md`（整篇讲镜像运维）

## 验证

- `go build ./...` / `go vet ./...` 绿
- `go test ./... -count=1` → 48 包 ok / 0 FAIL
- hmapdev 工具链编译通过（`third_party/homeagent-sdk/tools/hmapdev`）
- 全仓残留检查：module 形态的 `gitcode.com/JianFeeeee` = 0
- 镜像机制抽验：GC_URL / @gitcode / api/v5 / remote 均完好

## 顺带修正

`hmapdev/templates.go` 的注释此前写「gitcode 的模块不在 proxy.golang.org 上」——
module 已迁 GitHub，该论断不再成立。改为如实说明**为何仍默认 replace 到本机 SDK**：
离线可构建、避免版本漂移、内网可用。理由与托管地无关，故 replace 保留。
 2026-10-08 10:40:17 +08:00
JianFeeeee
2bcd3e94ee refactor(memory): 拆除描述式媒体索引，媒体成为一等块并按原生向量融合 
背景：此前媒体是靠「生成的描述文本」将就进记忆的——写 marker 进正文、
再由正则反解成 media_refs 与图库里的 type=Media 实体。这条链路有三个
致命缺陷：描述由异步模型生成（未生成前媒体等于不存在）、语义检索实质上
只搜描述文字、图库里的「媒体节点」是描述文本的投影而不是媒体本身。

本提交把这条链路整体拆除，媒体改为按自己的原生向量参与记忆：

一、描述链彻底删除（无残留、无兼容分支）
- media.Item 去掉 Description/DescribedBy 与对应列；
- 删除 Store.Describe / Store.Search / Store.Pending；
- 删除 Agent.mediaDescribeLoop / describePendingMedia 与配置项
  core.memory.media.describe_on_ingest；
- SDK 侧 MediaAttachment 去掉 Description（见 SDK 仓独立提交）。

二、marker 机制删除，媒体归属改为结构化块边
- 删除 mediaMarkerLine/parseMediaMarkers/mediaEntityName/mediaTriplesFromText/
  extractMediaDigests/sentenceWithMediaMarkers/docMediaContext；
- memory.Triple 新增 MediaDigests 结构化字段；句子文本保持原样，
  不再被 marker 污染；
- 块以 sentence --contains--> block / document --contains--> block 结构边
  挂到承载节点（新增 documents 表与 document 节点种类）；
- 模型未给原句时用「主谓宾。」拼一句自然语言作落点，不造 marker 文本。

三、旧数据迁移（幂等）
- 新增 GraphDB.MigrateLegacyMediaEntities：把 type=Media 的旧实体按短 digest
  还原成原生块、挂回原句子、删除旧实体与描述关系；Agent 启动时执行；
- CleanupOrphanedSentences 同时看关系引用与块边，避免把只靠块存活的句子
  连同块边一起删掉。

四、向量融合：媒体按图本身被召回
- 新增 vector.FuseVectors（逐维求和 + L2 归一化）；
- Doc.DenseVec = 文本向量 ⊕ 文档块的媒体向量（同 fingerprint 才融合），
  新增 Doc.DenseFP，指纹变化触发重算；
- ContextEvent.DenseVec 同理融合事件块；事件新增 DenseFP，Prune 只在
  同一统一空间内比稠密余弦；
- 跨模态视觉路只召回「仍被某层记忆块持有」的媒体，CAS 全库字节不再
  直接充当记忆检索结果。

五、同时纳入本分支既有的嵌入基础改造（此前工作区未提交，缺它 HEAD 不可构建）
- internal/tfidf 懒回退包、千问三段式多模态 ONNX 空间的 Go 侧
  （qwen/embedder.go、image.go、model_input.go）、CLIP 移除、
  sdk.NewStore 分词器签名与调用点、embed 侧车 systemd 单元。

验证：go build ./... 、go vet ./...（含 -tags medialive）均通过；
在 HEAD 的独立 worktree 上重放本次暂存集后 go test -short ./internal/...
全部通过（端口冲突类用例在隔离环境中亦通过）。未提交工作区中与本改造
无关的改动（HarmonyOS、waiter、devicebridge、plan.md 等）。
 2026-09-11 11:45:24 +08:00
JianFeeeee
704bda9141 refactor(memory): 移除 media_refs/引用计数，媒体成为一等记忆块 
媒体此前是"文本块 + digest 引用 + owner 账本 + 独立 GC"：ContextEvent.Media
记 digest，media_refs 表用 owner_kind/owner_id 保活，ref_count 决定 GC 能否清。
这与文本记忆块的管理方式不一致，也是本次一并纠正的核心偏差。

改为与文本块完全一致的生命周期：

1. 一等记忆块直接由所在层持有
   - ContextEvent.Blocks / Doc.Blocks / GraphDB memory_blocks
   - 块带 modality/digest/MIME/size/vector/fingerprint，文本、图片、视频同构
   - Context→Document→Graph 迁移的是块本身（ID 不变），迁移后清空源容器，
     同一块不同时存在于两层

2. 删除平行生命周期账本
   - media.Store 去掉 media_refs 表、OwnerKind 常量、RefCount 字段、
     AddRef/DropRef/DropOwner/Refs、ref_count 列与索引
   - 删除 mediaGCLoop、GC(keep,minAge)、容量上限与 media.gc_* / media.max_mb 配置
   - 媒体内容在块被永久删除时一并删除（media.Store.Delete + forgetPayloads），
     与"删除文本块即删除内容"同一语义

3. L3 原生结构
   - memory_blocks / memory_block_edges（contains/depicts/derived_from）
   - 边端点必须是真实图节点，不再用 owner 字符串伪装关系
   - BlocksForNode 支持 sentence --contains--> block 反查

4. SDK 与检索同步
   - 插件附件/标记直接变成块，不再 AddRef
   - 跨模态检索改用 QueryMediaScored（CAS 内不再有孤儿缓存需要过滤）

测试全部改写为块语义：删除 refcount/media_refs/GC 断言，新增块迁移、
单层不变量、Delete 语义与并发删除回归。

注：cmd/homed/main.go 同时携带工作区中既有的 CLIP→Qwen 模型目录接线改动。
 2026-09-11 10:57:22 +08:00
JianFeeeee
22e15ea3c1 feat(memory): 媒体接入 L0/L2——digest 挂到对话事件，归档时引用随之转移 
在 f408ccd 的 CAS 层之上把媒体真正接进记忆链路。此前 CAS 只是个孤立的
存储包，没有任何写入方。

## 媒体进入对话有两条路，两条都只把文字留给记忆

  1. 用户直接发图 → processMediaInput → mediaToBlocks
     ContextEvent.Input 只存 alt 文本（"[从 qq 收到了 image]"），
     base64 随 message 数组发给模型后就丢了。
  2. 插件注入 → SetToolBlocks → process.go 的 mediaMsg
     ToolResultItem.Output 只存那句 "[已将图片注入后续对话] /tmp/x.png"。

于是下一轮起，模型能看到的只剩一句路径或一句 alt。那个文件被删、被覆盖，
或者本来就是 /tmp 下的临时产物，连线索都断了。

现在两条路在同一处收口（captureBlockMedia）：从 ContentBlock 的 data URL
取出字节存进 CAS，digest 挂到当轮 ContextEvent。

## 改动

internal/agent/core/mediaref.go（新）
  - captureBlockMedia：ContentBlock → CAS。只处理 data URL——http(s) URL
    拿不到字节就无法内容寻址，而「下载它再存」会把一次对话变成一次网络
    请求（超时、鉴权、SSRF 全来了），不在本层解决。
  - stage/drainMediaDigests：媒体在 process() 期间被捕获，而承载它的
    ContextEvent 要等 process() 返回后才 Append——此刻还没有 owner_id，
    故先缓存。与既有 pendingMedia 同一手法，同受 a.mu 保护。
  - bindEventMedia：双向落地。evt.Media 让事件记得引了什么（随
    context.json 持久化），media_refs 让 CAS 知道谁在引用（GC 的判断依据）。
    只写一边的话，要么 GC 误删仍被引用的内容，要么孤儿永远清不掉。
  - mediaSummaryForEvent：把已有描述拼成一行写进 Input。这是方案 C 的
    落点——**描述文本才是持久语义记忆，blob 只是缓存**。blob 可能被容量
    GC 淘汰，但描述会一直留在 L0/L2/L3 的文本里，让「那张紫蓝红三色带图」
    几个月后仍可被检索。

ContextEvent 新增 ID 与 Media 两个字段，都是 omitempty：
  - ID 懒生成，只有真要挂媒体时才赋值。绝大多数对话没有媒体，全量生成
    会让每条事件都多一个字段进 context.json。
  - 存量 context.json 读回来两字段皆空，不影响任何既有行为（有测试）。

RelevanceContext.Prune 归档时转移引用（transferMediaRefs）：
  **先挂到归档文档、再注销原事件引用**。顺序不能反——先销后挂会让引用
  计数瞬时归零，若此刻后台 GC 正在跑就会把仍被记忆引用的内容当孤儿清掉。
  为此把 Prune 内的局部类型 scored 提为包级 scoredEvent（局部类型无法
  出现在方法签名上）。

media 包新增 OwnerContext/OwnerDocument/OwnerGraphSentence 常量：
  owner_kind 进了主键，拼错一个字符就是一条永远对不上的孤立引用——
  AddRef 不报错，DropOwner 也永远匹配不到。

## 配置

core.memory.media.enabled（默认 true）、.dir、.max_mb（2048）、
.gc_interval（6h）、.gc_min_age（1h）。

关闭后全链路静默跳过，对话行为与本特性上线前完全一致（有测试）。
mediaStore 为 nil 时同理——它是记忆增强，不是对话必需品，开不起来
只记一条 warning 不阻止启动。

## 测试（11 例）

入库与 MIME 归类、http URL 跳过、nil store 全链路 no-op、音视频混合、
stage/drain 清空语义、懒生成 ID、描述作为持久记忆、**归档转移期间内容
始终可读且 refcount 不归零**、无媒体存储时归档照常、context.json
向后兼容往返。

全仓 go build / go vet / go test 通过，SDK 冻结 diff = 0。

## 尚未接入

L3 图库的 graph_sentence owner（常量已备好，无写入方）、
描述生成的后台任务（Pending() 已就绪，尚无消费者）、
媒体 GC 的定时触发（配置项已注册，尚未接 ticker）。
 2026-09-04 20:53:32 +08:00