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
dfc05780fd
feat(kbtree): 知识库暴露范围配置 —— 按树状只暴露指定分类
...
## 问题
kbtree 是**唯一**把知识库开放给外部进程的通道（HomeAgent 自己的 agent
走进程内直调 knowledge_* 内核工具，不经此），但它只有 listen_addr 与
token 两个配置，**没有任何范围限制**：拿到 token 的任何 agent 都能
/tree 列出全部条目、/search 取回任意条目全文。
本机库里混着个人内容（航空发动机教材摘录、课表、身份合并规则），
不该 broadly 可读。
## 改动
1. `internal/plugins/kbtree/scope.go`（新）：暴露范围语义
- 留空 = 全部可见（范围是"限制"不是"必填"，留空保持既有行为）
- 前缀按**路径分段**匹配：public 命中 public 与 public/tech，
但**不**命中 publication（否则 publication 意外暴露）
- 根下无分类的条目在范围非空时不可见 —— 它没有分类可匹配，
放行等于范围形同虚设
- 分隔符容忍逗号/分号/空白/换行/竖线：这是给人手填的字段
2. `plugin.go`：注册 `expose_categories` 配置项，接入**全部四个端点**
- /tree 服务端裁剪子树（就地改，不重建：TreeView 字段多）
- /categories 过滤路径列表
- /counts 过滤计数并**重算 total**（数量本身也是信息泄露）
- /search ★ 过滤结果条目；这处最关键：
只过滤 /tree 而放过 /search 等于范围形同虚设（换个 ?q= 就能拿到全文）。
同时修正 limit 语义 —— 范围外条目不占名额，范围内条目不会被挤掉。
3. SDK 契约补 `Knowledge.Category`（纯增量）
- 此前 `sdk.Knowledge` 只有 Name/Content，内核明明返回了 Category
却在 knowledge_impl 的拷贝里丢掉 ⇒ 外部服务无法按分类判定，
范围过滤在 SDK 层根本做不了。
- Name/Content 均保留，无删除。
## 判据（8 条 + 4 组变异）
范围过滤最容易"只做一半"，所以每个端点都单独钉。
★ 判据补强一处：初版只查条目名（priv1），结果「/categories 不过滤」
这个变异**完全逃过** —— 分类端点返回的是路径不是条目名。
补上分类路径断言（private）后判红。
变异验证：
- /search 不过滤 → 泄露 priv1 全文 ✓ 判红
- /categories 不过滤 → 泄露 private 分类路径 ✓ 判红（补强后）
- /counts 不过滤 → TestCategoriesAndCountsEndpoint 判红
- 前缀退化为字符串前缀 → publication 被误暴露 ✓ 判红
★ 过程中我的 fake 有两处与真实内核不符，先修 fake 再修实现：
1. 漏了内核 treeLocked 的"子分类提升一层" ⇒ 得到 children=0 的假空树
2. filterTree 无差别清空 t.Items ⇒ 整棵树只剩空壳节点
（第一版的实现是"看着测试红就改"，实际是 fake 在骗我）
全量 41 包绿。SDK 接口纯增量，未发布故无需冻结检查。
2026-09-26 15:31:15 +08:00
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
144564f5c2
feat(knowledge): 分类过滤与多模态打通到工具/插件边界
...
- internal/sdk：KnowledgeAPI 增加 SearchIn/AddWithMedia/AttachMedia/
ReindexDense/DenseStats；新增 MediaAPI（Put/Stat/Get）与 PluginSDK.Media()，
registry 装配。**公开 SDK 契约一字未动** —— third_party/homeagent-sdk/sdk/
的 diff 恒为 0（发布纪律的硬约束），走 internal/sdk 这条明确不受冻结约束
的内部扩展路径。
- proc：新增 knowledge.addWithMedia（正文与媒体清单都走共享内存，与
doc.insertWithMedia 同形）；knowledge.search 支持 category。
- corehandler 用**局部接口 + 类型断言**取扩展能力，而非直接引 internal/sdk：
后者已依赖 internal/plugin 的类型，直接引会成环（CoreSDK 注释已警示）。
断言失败明确报"能力不可用"，不静默退化成"媒体已写入"。
- agent 工具面：knowledge_search 增加 category；knowledge_create 增加
media_digests（复用 doc_commit 的 digest 前缀解析 + Stat 回读 MIME）。
顺带修 knowledge_search 的分类前缀重复（Name 已含分类，旧代码又拼一次，
实测输出 tech/go/tech/go/并发）。
- agent 启动接线多模态空间，顺序为先接线再 ReindexDense（否则首次启动
算出的向量因 MediaStore 未就绪而不落盘）。
2026-09-26 14:20:19 +08:00
5836c2ce5c
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
dbbd73b930
refactor: migrate built-in plugins to SDK-only interface
...
- Six-phase plan complete: webui/cli/healthcheck/pluginmgr/clawhubadapter
now interact with the kernel exclusively via internal/sdk interfaces;
all Configure() calls and package-level global injection removed
- buildSDK in internal/plugin/registry.go is the single assembly point
- Add internal/sdk/events.go exporting event types/constants
- Fix ProviderManager cooldown sharing: LuaAdaptedProvider.Name() now
returns the source name instead of lua_<adapter>, so multiple sources
sharing an adapter (single script load via shared VM AdapterCache) no
longer share failure-cooldown state
- Verified: build/vet/tests green, deployed to homeagent.service with
full plugin capability testing via local OpenAI-compatible mock
2026-08-01 12:17:17 +08:00
1f1233b823
refactor: P0-P3 fixes, C1 cleanup, architecture diagrams, go.work upgrade
...
- P0-1: ProviderError type + ReportStatus for precise 401/403 detection
- P0-2: Remove -config flag from deploy/homeagent.service
- P2-1: 5s debounce on context.go Save()
- P2-2→C1: Delete output_set_channel entirely
- P2-3: Extract mediaDataURL/mediaChat helpers
- P2-4: Dedup defaultSources var
- P3: Delete dead packages (embed/tokenizer/container/snapshot)
- P3: Delete dead functions (messagesToMap, RunStageAll)
- CL: Update .gitignore, docs, Makefile, gojieba removal
- Config: Delete config/config.yaml, update docs
- Arch: Remove EmitOutputTo from emitResponse
- CL-1: go.work 1.19→1.21
- Docs: Add Mermaid architecture diagrams to README
- Docs: Add kernel-rebuild requires plugin-rebuild note to PLUGIN_DEV.md
2026-07-12 11:42:56 +08:00
