jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-09-27 21:03:16 +00:00
Code Issues Packages Projects Releases Wiki Activity
681 Commits 5 Branches 27 Tags
116dc413f0f5dd730c435f90aca0ffd600a04890
Commit Graph

15 Commits

Author SHA1 Message Date
JianFeeeee
5dd98d7a05 feat(knowledge): 目录批量导入 + 派生数据批量收口 
## 能力缺口

导入只能一条条 Add（knowledge_create）。agent 拿到一份 200 页的
文档目录要调 200 次工具，且每次都得自己决定分类与名字。

新增工具 `knowledge_import_dir(dir, category?, include_media?, dry_run?, max_items?)`。
语义是**复制**不是引用：源文件删改不影响已导入的副本。
- 文本经 Write 整份写入 <知识根>/<分类>/<名>/content.md
- 媒体按 sha256 进媒体库（内容寻址天然去重），条目只存 digest 引用

## 目录约定（自动适配，不要求改造资料）

1. 含 content.md 的目录 ⇒ 整体作为一个条目（与 scanDir 既有语义一致，
   所以知识库自身目录能被原样再导入而不会被拆散）
2. 否则 .md/.txt 等文件各成一条，**目录路径即分类**

## 三个语义决策

- category 是**前缀叠加**（tech + 源结构），不替换：替换会丢掉源目录
  自身最有价值的层级信息
- 同名冲突**跳过并计数**，绝不覆盖：Write 对同名本就是覆盖语义
  （knowledge_create 靠它做更新），若直接调它，一次重导就会把手工
  补充的内容悄悄抹掉，而日志只写"导入完成"
- dry_run **默认 true**：批量写，agent 第一次试某目录应先看清会写什么

## 安全边界（批量操作，缺一道就可能读到不该读的）

- 必须绝对路径：agent 的 cwd 不受控，相对路径会静默导到别处
- 符号链接不跟随：否则一个软链就把知识根之外的文件导进来
- 拒绝把知识库自身当源（自导会无限自我复制）
- category 复用 normalizeName（与 Write 同一道闸，两处分叉就成了绕过）
- MaxItems 默认 500：防 agent 误传 "/" 把盘灌满

## ★ 批量导入暴露的既有 O(N²)

Write 每条末尾都调 flushDenseLocked，而 saveDenseCacheLocked 是
**全量序列化整个 items map 再重写整个文件**。按 512 维 float64 估，
单条约 10KB，导入 500 条累计要写约 1.4GB。

仓库里索引侧早已有 indexDirty 的「标脏+延迟收口」（实测 writeIndexLocked
6.7ms/次、占单条 Add 绝大部分），**稠密缓存却还是逐条全量重写** ——
同一类开销只修了一半。

照 indexDirty 的模式补 batchDepth：批量期只标脏，endBatch 收口一次。
用 defer 保证提前 return 也会收口 —— 否则这批向量会留成"标脏未写"，
下次启动被当作缺失而全量重算。

## 判据：17 条 + 变异

安全边界做了 4 组变异验证（去符号链接拦截/去绝对路径要求/去自导检查/
content.md 目录不下钻）。

★ 判据第一版有两处自己骗自己，被变异抓出来：
1. 符号链接判据造的是**目录软链**，而 WalkDir 对目录软链本来就不下钻
   ⇒ 有无防护结果都一样，是假绿。改成**文件软链**后才真正判红。
2. 同名冲突判据里已有条目写成 "a/b"、源映射出的是 "b"（不同名），
   判据自己就错了 —— 修判据而不是改实现。

媒体路径用假 MediaPutter：验的是「调了 Put 且 digest 挂到条目上」，
媒体库自身的落盘去重是 media 包的判据，不该在这里重测。

全量 41 包绿。
 2026-09-26 16:19:10 +08:00
JianFeeeee
41d754334e feat(kbtree): 知识库分类树的独立只读服务 + agent 技能 + WebUI 树浏览 
让**外部 agent** 也能按分类树用这套知识库。HomeAgent 自己的 agent 仍
直接调内部方法（knowledge_search/create 等），走进程内直调，不经此服务。

一、内核树视图（internal/knowledge/tree.go）
  为什么不复用 TreeIndex：那个是**内部导出物**，面向 .index.json 落盘，
  每个条目带 top-20 的 TF-IDF 特征向量。直接序列化给外部有三个问题：
  体积（200 条时 .index.json 已 246KB 且冗余存了 preview，而正本在
  content.md）、泄漏（稀疏特征表 = 分词/IDF 内部表示）、语义错位
  （外部要的是"有哪些分类、每类下有什么"）。
  新增 TreeView/Subtree/Categories/CategoryCounts：不含向量，带条目数
  与可读摘要，支持 MaxDepth 懒加载、IncludeItems 只看结构。
  节点 Name 是**本级段名**（"go"）、Path 是完整路径（"tech/go"）——
  最初把全路径写进 Name，前端拼层级会得到 "tech/tech/go"，已修。

二、kbtree 插件：独立 HTTP 服务（默认 127.0.0.1:9892）
  为何不挂在 WebUI 的 /api/v1/knowledge* 下：
  1. 不共享鉴权与端口。WebUI 的 api_key 是给人操作界面用的，把它分发给
     外部 agent 等于把管理面凭据扩散出去。本服务用**独立 token** +
     独立端口，可单独关闭（token 未配置则启动时随机生成）。
  2. 只读。写入要决定分类归属与媒体处理，外部自行拼装容易造出越界/重名
     条目 —— 写入留给内核工具。
  3. 形状按树组织，而不是平铺搜索接口。
  端点：/tree（可指定 category/depth/items）、/categories、/counts、
  /search、/ （自述）。全部需 token（X-API-Key / Bearer / ?token=），
  非 GET 一律 405。无知识库时 Start 直接失败，不占端口。
  鉴权与 Slowloris/超时设置照 remotedevice 范式。

三、agent 技能（assets/skills/knowledge-base/SKILL.md）
  指令文档型 skill：教模型"先看树 → 定位分类 → 分类内检索"，并列出
  易错点（name 已含分类别再拼、只看第一条、404 附现有分类）。
  加载与校验由 internal/plugin/skill_bundled_test.go 守住 —— 这条断言
  的由来：非白名单的二级标题会被 extractToolDefs 当成工具定义，报错
  "invalid tool name"，而提示与真正原因（标题层级）毫无关联。
  kbtree 的测试还会校验文档提到的端点与代码一致，防漂移。

四、WebUI 树浏览（前端真正用起来，而非留一个没人调的端点）
  面板加可折叠的分类树：逐级点选即把搜索范围切到该子树（原先是让人
  手打分类名）。当前范围有可见标签与「全库」复位。
 2026-09-26 14:20:19 +08:00
JianFeeeee
ce694bc1a1 test(knowledge): 端到端验证多模态与分层链路 + 修稠密路同分次序不确定 
一、修缺陷：denseHits 同分次序随机
  稠密路用 map 遍历 + 只按分数排序，**没有 tie-break**：同分条目的相对
  次序随每次调用变化 ⇒ 同样的查询两次可能给出不同首位（用户看到结果在跳，
  测试偶发变红）。Search 的主排序早就有「分数相同时按名字定序」，这条漏了。
  补上同分按 id 定序，并加 TestDenseHitsTieIsDeterministic 反向守住
  （撤掉 tie-break 后该测试在 5 次运行里稳定报出首位跳变）。

二、端到端验证（两个新文件）
- TestMultimodalEndToEndWithRealProvider：走**真实 embedding provider**
  （内置 http provider + 一个符合内核契约的最小服务），覆盖
  embedding.Open → AdaptProvider → media CAS → SetDenseSpace/SetMediaGetter
  → AddWithMedia（文本⊕图片融合）→ 以图搜知识 → .dense.json 落盘 →
  重启命中缓存（ReindexDense built=0）。
  不用 ONNX provider 是因为真模型 200MB 权重 + 3 分钟加载，进不了 CI；
  该链路是 provider 无关的（AdaptProvider 之后内核只认 MultimodalEmbedder）。

- TestHierarchicalIndexEndToEnd：多层分类（tech/go/两段、tech/rust/两段）
  的 Category 推导、树导出结构与挂载点、三级前缀过滤检索、范围外排除、
  索引落盘、重启后不漂移、树在重启后仍可用。
  反向验证：把 inScope 改成恒真后该测试稳定变红（报出范围外条目混入），
  确认它真能抓到「分层不参与召回」这一退化。

三、额外实测（本机，非 CI）
带 onnxruntime tag（生产构建形态）下用真实 Qwen3-VL 模型跑通全链路：
  provider dim=2048 modalities=[text image] fp=e43381246264...
  photo.Dense = 文本⊕图片融合结果
  以图搜知识 top1=photo score=0.757   ← 真正的跨模态召回
  重启后 ReindexDense built=0（命中缓存）
另确认默认构建（无 tag）下 qwen3vl 是 stub、Open 明确报错，不会静默降级成
"看似可用"。Makefile 的 HOMED_TAGS 默认即 onnxruntime，故发行版默认启用。
 2026-09-26 14:20:19 +08:00
JianFeeeee
9f2ec31cb0 fix(knowledge): 名称规范化/路径安全 + IDF 增量维护 + 多模态稠密路 + 派生数据落盘 
一次知识库子系统的集中加固，四类缺陷各有实测复现：

1. 名称与路径（数据安全，最严重）
   - sanitize 不过滤 .. ⇒ Remove("..") 直接 RemoveAll 掉整个数据目录
     （实测把 <data> 整棵删掉，含 memory/documents/media），且返回 nil，
     工具层回报"已删除"；Add("../../x") 写到知识根外，重启扫不回来
     ⇒ 幽灵条目。
   - Add 整串 sanitize 而建目录逐段 sanitize，内存键与盘上目录从**第一次
     落盘起**就不一致；重启后 name 漂移，knowledge_delete 静默删不掉
     （RemoveAll 删空目录返 nil）。同一个根因。
   - 修法：新增 normalizeName 作为唯一入口（逐段 + 拒绝空段/点段/隐藏段）；
     Remove 改为取条目自记的 Path（不再用名字重拼）+ 返回 ErrNotFound。
   - resolve 三层退让（原样 → 规范名 → 叶名大小写不敏感，唯一命中才接受）：
     scanDir 按盘上目录原样建键，遗留大写目录若只查规范名会变成
     "List 看得到、Remove 报不存在"。删的路径仍取自 Path，退让无风险。

2. IDF 与索引不同步（功能缺陷，非优化）
   - TFIDF Vectorize 跳过 df<=0 的特征，而 Add 只往只增不减的 summaries
     追文本、从不更新 DF ⇒ 库满(≥3篇) + 新词时，新知识**当场搜不到**，
     重启才恢复（实测 Search("量子纠缠") == []）。
   - 修法：vector.Store 新增 AddDoc/RemoveDoc（文档级去重口径与 Train 一致，
     totalDocs 下界守卫，零频 DF 删除防表膨胀）；knowledge 删掉 summaries，
     改 index/unindex/retrain 三件套，覆盖写先 RemoveDoc 旧文本。

3. 多模态稠密路（此前知识库端到端纯文本）
   - 新增 SetDenseSpace/SetMediaGetter/ReindexDense/DenseStats 与
     AddWithMedia/AttachMedia，媒体成为一等节点参与跨模态召回。
   - 维度与指纹双守卫：维度不符的向量会被 FuseVectors 按最大维度拼成错维度
     结果且被当成"已对齐"永久错下去（docStore 踩过）；模态不支持(音频)时
     静默跳过该媒体、退化为纯文本向量，绝不拿别的模型的向量顶替。
   - 未注入多模态空间时行为与此前逐字一致（退化为 0.5/0.5 两路融合）。

4. 派生数据落盘 + 分层参与召回
   - 媒体引用是**作者数据**（丢失即丢信息）→ 条目目录内 .media.json；
     稠密向量是**派生数据**（可重算）→ 全局 .dense.json，tmp+rename 原子。
     混存会让派生数据损坏连带作者数据一起丢。
   - 新增 SearchIn(query, category, topK)：分类前缀匹配子树，让分层真正
     参与召回（此前检索全库平铺，分层只是存储布局）。归一化取作用域内
     最大值，否则范围外的强命中会把域内分数压没。
   - 删除 SearchTree/SearchCategories 死代码（零调用方，且停留在 Search
     修复前的单路口径：无词法融合、0.05 阈值）。

顺带修掉 Add 的 O(N)/写：buildTreeLocked 逐条重算向量（s.vec 里已有）
改为一次建表复用；.index.json 改为标脏 + Flush/Stop 收口。实测单条 Add
2.1ms@50 → 13.7ms@400 压平到 ~400µs（34×）。

存量目录改名迁移落在 migrate_names.go，只报告不改名（os.Rename 不可逆），
冲突整批拒绝以免半迁移。
 2026-09-26 14:20:18 +08:00
JianFeeeee
241f5fac04 fix(knowledge): 拒绝越出知识根的知识名（可致整个数据目录被删） 
sanitize 只做小写/去空格/换下划线，**不过滤 ".."**，而 Remove 直接把
sanitize 的结果 filepath.Join 到知识根后 os.RemoveAll。

后果（实测）：
- Remove("..") → RemoveAll(<data>)，把整个数据目录连同 memory/
  documents/media 一起删掉；且 os.RemoveAll 对已不存在的目标返回 nil，
  调用方（含 knowledge_delete 工具）会回报"已删除"。
- Remove("../..") → RemoveAll(<data 的父目录>)。
- Add("../../x") → 内容写到知识根之外；重启后 scanAll 扫不到该目录，
  条目既不在盘上正确位置也无法重建 ⇒ 幽灵条目（内存有、索引有、盘上没有）。
- Add(".hidden") → 写到隐藏目录，scanDir 明确跳过隐藏目录 ⇒ 同样的幽灵。

修复：
- 新增 checkSafeName：拒绝空段、"."、".."，以及以点开头的段。
  Add 与 Remove 在拼接路径前都过它。
- 双保险：拼接后用 filepath.Clean 复核结果仍在知识根内，
  防止 checkSafeName 将来被改宽而重新引入越界。

反向验证：临时拆掉这两处防护后重跑新测试，Add/Remove 对 .. 与隐藏名
全部"成功"，测试稳定变红；恢复后全绿。

影响范围：该缺陷存在于 release/v1.0.x ~ v1.3.x 四条发布线（各自的
internal/knowledge/knowledge.go 的 Remove 均为同一写法），本次修复需按
hotfix 纪律 cherry-pick 回流 main 并前向传播。
 2026-09-26 13:11:08 +08:00
JianFeeeee
5fbd6514c2 fix(knowledge): 知识库检索改为「稠密 + 词法」两路融合（真实 KB 自检索 MRR 0.271→0.376） 
追「实例看起来没更新」时发现知识库检索本身也不可信，先把病因查清再动手：

- **两段式召回不是瓶颈**：Store 的结果与全量暴力 cosine 完全一致；
- **真因是向量没有区分度**：词向量取平均后各向异性明显，真实 KB（33 条）上自检索
  top-1 只有 15%、前两名平均只差 0.013，排序基本是噪声；
- 且全为停用词的查询会得到**空向量**（"最近更新"），直接搜不出任何东西。

先在真实数据上把候选方案量了一遍（用自检索 top-1 / MRR）再动手：IDF 维度加权零收益、
去均值反而更差，**都不做**；唯一有收益的是与词法路（TF-IDF）融合。

改动：
- `Store` 增设词法路索引，`Search` 融合两路：各自按**查询内最大值**归一化后加权。
  权重 0.5 由权重扫描定：1.0（旧行为）MRR 0.271 / 0.8→0.354 / 0.7→0.358 / **0.5→0.376** /
  0.3→0.336 / 0.0→0.307；语义查询也从"全是 openharmony 噪声"变成命中正确条目
  （「首启人格门禁」→changelog_v1.2.1、「插件怎么开发和部署」→plugin_dev_build）；
- `vector.Store` 的候选中选阈值改为**可设**（默认 0.05 保持既有行为）：TF-IDF 余弦量级
  只有 0.0~0.2，沿用 0.05 会把词法路有效候选**静默砍掉**——这一条正是 0.376→0.197 的
  差距来源，且当时没有任何报错；
- Add/Remove/scanAll/ReindexWithVectorizer 同步维护两路；分数相同时按名字定序（结果可重复）。

**顺带修一个真实毛病**：Add/Remove 原先用**无追踪的 goroutine** 写索引（因为
writeIndex→BuildTree 会 RLock，而调用方持写锁，同步调用会死锁）→ 失败只打日志，
且与调用方竞态（测试的临时目录清理就撞上了）。改为持锁就地 flush
（buildTreeLocked / writeIndexLocked）。

判据（不依赖人工标注问答对）：新增 `internal/knowledge/rankdiag_test.go`，用**自检索
top-1 / MRR** 量区分度，`KB_DIAG=1` 跑、`KB_DIAG_ASSERT=1` 断言（MRR ≥ 0.34）。
另有不依赖真实数据的单测 6 条（空稠密向量靠词法路救回、稠密并列时词法路定序、
词法路阈值接线、Add/Remove 双路一致、并列时确定性、空库不 panic）。

**反向验证**（证明判据真能发现缺陷）：权重退回 1.0、词法路阈值改回 0.05、
把阈值写死回 0.05 —— 对应测试逐条变红。另：我第一版夹具余弦 0.365/0.273 远高于阈值，
注入缺陷也不报错（等于没验），故加了「夹具前提」断言并改成两层判据
（语义层由 vector 包测试证明、接线层由知识库测试钉住）。

顺带纳入上一轮漏提交的 `TestAddOverwriteReplacesVector`（同名覆盖必须摘掉旧向量，
生产改动当时已提交，测试一直未入库）。
 2026-09-12 18:14:22 +08:00
JianFeeeee
685ed7e4a0 fix(knowledge): 覆盖同名条目时摘掉旧向量 
从一次真实的知识库更新里发现：在线实例更新一个已有条目之后，
knowledge_count=32 而 vector_count=33——多出来的那一条是上一版的副本。

成因：vector.Store.Insert 是**追加**语义（s.docs = append + index.Add），不按 id 去重；
而 Store.Add 走的是「写 content.md + 覆盖 items[id] + Insert 向量」。
文件与内存条目都被正确替换了，只有向量索引多留了一份。

危害不在于多占内存：**检索可能命中已被替换掉的旧内容**，而且完全静默——
条目数看起来是对的，只有向量数比条目数多。

修法：Insert 之前先 s.vec.Remove(id)（Remove 已按 id 过滤 docs 与倒排索引）。
回归测试 TestAddOverwriteReplacesVector 钉住 knowledge_count / vector_count /
content.md 三者都必须只剩新版。

注：该文件在 origin/main 上本就有 32 行 gofmt 差异（结构体字段注释对齐），
不属本次改动，按纪律不做整体重排。
 2026-09-12 08:30:22 +08:00
JianFeeeee
2c5f9ff262 v0.7.2: 根目录清理 + Agent 心跳重构 + 内嵌 ONNX 模型 
- 根目录清理: branding/docs/knowledge -> assets/, package/tools/deploy -> deploy/
- meta.go: Version 0.7.2, SDKCompatibleVersion 语义改为最高兼容
- Makefile: 版本回退 0.7.2
- registry.go: 系统提示词改用 meta.Version 格式化
- Agent 心跳: reorgGraph 拆分为三个独立循环(archive/merge/review)，各自可配间隔
- GraphDB: 新增 sentences 表 + 关系句子溯源 + ClearSentenceID + CleanupOrphanedSentences
- Knowledge: 支持词嵌入向量化器
- NLP 四阶段流水线: Parse -> Extract -> Verify -> Fuse + SentenceRef
- 移除远程 HTTP 解析器(remote_parser.go)
- 新增内嵌 ONNX 模型(vocab + dep_parser.onnx):
  +build onnxruntime: 全量 ONNX Runtime 推理
  !build onnxruntime: 内嵌词表规则式降级解析器
- config: core.agent.onnx_model_path 替代 dep_parser_url
 2026-07-28 09:56:26 +08:00
root
1cb3e87dde feat: 完整实现 NLP 三元组提取系统 + token budget 上下文分配 
- 重写 extractor.go: 分句、17条 POS 模板、依存模板 + COO 链、ATT合并
- parser.go: 分句循环 + TransE 向量验证(h+r≈t)
- fallback.go: jieba POS 降级解析器
- bridge.go: nlp.Triple ↔ memory.Triple 转换
- pipeline.go: extractKeyTriples 改用 NLP 提取器, 删除5条旧前缀规则
- distill.go: docToTriples 改用 NLP 提取器
- reorgGraph: 语义相似度增强检测, 保持纯 LLM 决断
- Provider 接口加 MaxContextTokens() + 模型窗口映射表
- tokenbudget.go: 中文 token 估算器 + budget 分配(80%利用率)
- process.go/buildSystemPrompt: 按 token 预算截断 memory+timeline
 2026-07-27 15:26:23 +08:00
root
09b79811a0 feat: add knowledge_delete tool + cmd_run self-kill guard via before_toolcall stage hook 2026-07-16 19:24:31 +08:00
root
c951e75b39 fix: async knowledge writeIndex + 60s tool execution timeout 2026-07-16 19:04:10 +08:00
root
7f28b997e6 feat: output channel redesign - per-channel output gates, LLM chain events, SDKConfig 
- Output channels generate per-channel tools: output_send__{name} (type=output) + output_send__{name}_help
- content is JSON string transparently passed to plugin handler for routing
- EventAgentLLMChain: full LLM response forwarded after each turn for webui/logs
- sdk.New refactored to SDKConfig struct (no more 13 positional args)
- RegisterOutputChannel adds desc param for JSON format documentation
- channelDevice simplified (no Tools method), desc field added
- Child agent permission updated for output_send__ prefix
- System prompt: output gates, multi-call, long messages split
- WebUI: subscribes to EventAgentLLMChain in SSE, no output channel
- Tests updated for new naming convention
 2026-07-16 12:11:16 +08:00
root
2edc039351 fix: correct context pruning order and vector alignment 
- Prune context BEFORE processing (LSTM forget gate pattern)
  so LLM only sees relevant context, instead of pruning after the fact
- Fix ensureTrained() to recompute all event vectors after retraining
  vectorizer, fixing feature-space mismatch between stored vectors and
  query vector that made relevance scoring effectively random
- Add read lock to knowledge BuildTree() (data race fix)
- Log writeIndex() errors instead of discarding them
- Fix TOCTOU race in document ContextToDoc() dedup
- Fix healthcheck timing (measure elapsed before cleanup)
- Refactor waiter CLI into separate files (state, conn, config, editor,
  history, builtin) for maintainability
- Add CLI plugin API key authentication
 2026-07-07 17:07:38 +08:00
root
304c3ae294 refactor: remove IO route mapping, add HTTP API tests, system prompt update 2026-07-02 15:47:16 +08:00
root
bc26850b50 feat: complete HomeAgent architecture v2 
- IO abstraction layer with OutputChannel routing and capability validation
- Three-layer memory (Context-Document-Graph) with TF-IDF relevance pruning
- OneBot V11 QQ protocol plugin with Reverse WebSocket client
- Plugin system with hot-reload (SKILL.md + native factories)
- Knowledge system with TF-IDF vector indexing
- Personality system (personal.md)
- Text memory (JSONL with rotation)
- Change tracker (overlayfs) with rollback
- Lua adapter VM
- Design document (DESIGN.md)

Module: gitcode.com/JianFeeeee/HomeAgent
 2026-07-02 12:04:36 +08:00