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
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
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
50e5dec745
feat: converge dynamic plugins onto canonical homeagent-sdk
...
- Separate built-in plugin interface from external plugin interface
- Route dynamic plugin loading through homeagent-sdk/sdk using reflection
- Turn internal/sdk into an enhanced wrapper over canonical SDK types
- Vendor SDK repo snapshot under third_party/homeagent-sdk for stable builds
- Keep internal constructors/adapters for memory, knowledge, llm, settings
- Align dynamic QQ loading with canonical SDK chain
2026-07-06 19:27:51 +08:00
2d314b3e9c
重构: 插件自注册 + .so 动态加载 + 中断打断机制
...
- 所有内置插件 init() 自注册 (plugin.RegisterFactory), 移除 main.go 硬编码
- 新增 .so 动态加载器 (internal/plugin/dynamic.go), 插件可编译为 plugin.so
- 新增 plugin.json 元数据 (internal/plugin/manifest.go)
- 新增 interceptLoop 独立 goroutine:
(a) cancelLLM() 取消进行中的 HTTP 请求
(b) interceptCh → drainInterrupt() 注入 [打断消息] 到 LLM 上下文
(c) InjectInput 空闲时触发新处理循环
- 新增 internal/plugins/all.go 空白导入触发所有内置插件 init()
- internal/sdk/ 作为 PluginSDK 正式 Go API
- internal/api/ → internal/plugins/webui/ 迁移
- 删除旧 cmd/cli/, 使用 cmd/waiter/ 替代
- 更新 PLAN.md / ARCHITECTURE.md / README.md 文档
2026-07-03 16:53:34 +08:00
