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 未就绪而不落盘）。

internal/sdk/knowledge.go

@@ -1,14 +1,50 @@
 package sdk
 
-import pubsdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk"
+import (
+	"gitcode.com/JianFeeeee/HomeAgent/internal/knowledge"
+	pubsdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk"
+)
 
 // KnowledgeAPI 是内置插件使用的全量知识库接口。
+//
+// 为什么不把多模态加进 pubsdk.KnowledgeAPI：那会改动
+// third_party/homeagent-sdk/sdk/ 的公开契约，而发布纪律要求
+// `git diff main -- third_party/homeagent-sdk/sdk/` 恒为 0
+// （改动它等于一次 major bump + 完整的外部发版流程）。
+// internal/sdk 明确不受此约束（"内部实现自由"），且这里本来就是
+// "内核侧接口 = 公共接口 + 内置插件额外能力" 的既有范式
+// （见 PluginSDK 遮蔽访问器：Settings/Memory/TextMemory/DocMemory…）。
+// 结果是：内置插件（含子进程插件的 core handler）拿到多模态能力，
+// 而外部 SDK 契约保持逐字不变。
 type KnowledgeAPI interface {
 	pubsdk.KnowledgeAPI
 	// Stats 返回知识库的运行统计。
 	Stats() map[string]interface{}
 	// Remove 按名称删除一条知识。
 	Remove(name string) error
+
+	// SearchIn 在某个分类子树内检索（category 为空 = 全库）。
+	SearchIn(query, category string, topK int) ([]*Knowledge, error)
+	// AddWithMedia 写入带媒体的知识。媒体是一等节点：其向量会与正文向量
+	// 在多模态统一空间内融合，使该条目能按图本身被召回。
+	//
+	// 未接入多模态空间时与 Add 等价（媒体仍被记录，只是不参与召回）。
+	AddWithMedia(name, content string, media []KnowledgeMediaRef) error
+	// AttachMedia 给已有知识追加媒体，并当场重算其稠密向量。
+	AttachMedia(name string, media ...KnowledgeMediaRef) error
+	// ReindexDense 重建稠密向量（模型/维度变化后调用），返回新建与跳过条数。
+	ReindexDense() (built, skipped int)
+	// DenseStats 报告稠密路的接线与覆盖情况。
+	DenseStats() map[string]interface{}
 }
 
+// KnowledgeMediaRef 是媒体在知识条目中的一等引用。
+//
+// 与内核 knowledge.KnowledgeMediaRef 是**类型别名**而非新类型：别名
+// 才能穿过 C ABI / JSON 边界；若是两种结构，core handler 还得再做一次
+// 手工转换，漏一处就是「媒体被静默丢弃」。
+type KnowledgeMediaRef = knowledge.KnowledgeMediaRef
+
+// Knowledge 沿用公共 SDK 的类型，保证内外两侧对同一批知识条目的
+// 字段理解一致（跨 ABI 传递时按此结构序列化）。
 type Knowledge = pubsdk.Knowledge

internal/sdk/knowledge_impl.go

@@ -25,6 +25,46 @@ func (k *knowledgeImpl) Add(name, content string) error {
 	return k.ks.Add(name, content)
 }
 
+func (k *knowledgeImpl) SearchIn(query, category string, topK int) ([]*Knowledge, error) {
+	if k.ks == nil {
+		return nil, nil
+	}
+	got := k.ks.SearchIn(query, category, topK)
+	out := make([]*Knowledge, len(got))
+	for i, item := range got {
+		out[i] = &Knowledge{Name: item.Name, Content: item.Content}
+	}
+	return out, nil
+}
+
+func (k *knowledgeImpl) AddWithMedia(name, content string, media []KnowledgeMediaRef) error {
+	if k.ks == nil {
+		return nil
+	}
+	return k.ks.AddWithMedia(name, content, media)
+}
+
+func (k *knowledgeImpl) AttachMedia(name string, media ...KnowledgeMediaRef) error {
+	if k.ks == nil {
+		return nil
+	}
+	return k.ks.AttachMedia(name, media...)
+}
+
+func (k *knowledgeImpl) ReindexDense() (int, int) {
+	if k.ks == nil {
+		return 0, 0
+	}
+	return k.ks.ReindexDense()
+}
+
+func (k *knowledgeImpl) DenseStats() map[string]interface{} {
+	if k.ks == nil {
+		return map[string]interface{}{}
+	}
+	return k.ks.DenseStats()
+}
+
 func (k *knowledgeImpl) List() ([]string, error) {
 	if k.ks == nil {
 		return nil, nil

internal/sdk/media.go

@@ -0,0 +1,79 @@
+package sdk
+
+import (
+	"errors"
+
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/media"
+)
+
+// ErrMediaUnavailable 表示媒体存储未接线（宿主没注入 media.Store）。
+// 单独成一个哨兵：调用方需要区分"没配"与"读失败"，前者不该重试。
+var ErrMediaUnavailable = errors.New("media: 媒体存储不可用")
+
+// MediaAPI 是内置插件使用的媒体存储接口（内核侧扩展，非公开 SDK 契约）。
+//
+// 存在的理由：多模态链路的一切都以**内容寻址**为锚——media.Store 按
+// sha256 去重落盘，向量按 digest 存在同一条记录上，知识/文档/记忆块都只
+// 存「引用」不存字节。而 WebUI 的上传（handleChatFile）历史上只把文件
+// 落在 uploads/ 目录、直接读字节拼 data URL，**从不入 CAS**，于是拿不到
+// digest，也就无法把图挂到知识条目上。
+//
+// 为什么是 internal/sdk 而不是公开 SDK：同上 KnowledgeAPI 多模态方法的
+// 理由——third_party/homeagent-sdk/sdk/ 受接口冻结约束，diff 必须恒为 0。
+type MediaAPI interface {
+	// Put 把字节存入 CAS，返回内容 digest。同一内容重复 Put 幂等
+	// （不重复落盘，只刷新 last_seen）。
+	Put(data []byte, mime, tool string) (string, error)
+	// Stat 读元数据，不读内容。
+	Stat(digest string) (MediaInfo, error)
+	// Get 读回内容并校验 digest。
+	Get(digest string) ([]byte, error)
+}
+
+// MediaInfo 是媒体元信息的只读视图。
+//
+// 刻意与 media.Item 分离（而非直接别名）：那会把 origin_path / first_seen
+// 等溯源字段一并暴露给插件层，而插件只需要"这条媒体是什么、怎么取回"。
+type MediaInfo struct {
+	Digest string `json:"digest"`
+	Kind   string `json:"kind"`
+	MIME   string `json:"mime"`
+	Size   int64  `json:"size"`
+}
+
+type mediaImpl struct{ ms *media.Store }
+
+// NewMedia 构造媒体存储接口。ms 为 nil 时各方法安全降级（返回 error / 空值）。
+func NewMedia(ms *media.Store) MediaAPI { return &mediaImpl{ms: ms} }
+
+func (m *mediaImpl) Put(data []byte, mime, tool string) (string, error) {
+	if m.ms == nil {
+		return "", nil
+	}
+	return m.ms.Put(data, media.Item{MIME: mime, Tool: tool})
+}
+
+func (m *mediaImpl) Stat(digest string) (MediaInfo, error) {
+	if m.ms == nil {
+		return MediaInfo{}, ErrMediaUnavailable
+	}
+	it, err := m.ms.Stat(digest)
+	if err != nil {
+		return MediaInfo{}, err
+	}
+	return MediaInfo{
+		Digest: it.Digest,
+		Kind:   string(it.Kind),
+		MIME:   it.MIME,
+		Size:   it.Size,
+	}, nil
+}
+
+func (m *mediaImpl) Get(digest string) ([]byte, error) {
+	if m.ms == nil {
+		return nil, ErrMediaUnavailable
+	}
+	return m.ms.Get(digest)
+}
+
+var _ MediaAPI = (*mediaImpl)(nil)

internal/sdk/plugin.go

@@ -153,6 +153,7 @@ type PluginSDK struct {
 	textMem  TextMemoryAPI
 	docMem   DocMemoryAPI
 	know     KnowledgeAPI
+	media    MediaAPI
 	llm      LLMAPI
 
 	iom       *agentIO.IOManager
@@ -182,7 +183,11 @@ func (s *PluginSDK) Memory() MemoryAPI         { return s.memory }
 func (s *PluginSDK) TextMemory() TextMemoryAPI { return s.textMem }
 func (s *PluginSDK) DocMemory() DocMemoryAPI   { return s.docMem }
 func (s *PluginSDK) Knowledge() KnowledgeAPI   { return s.know }
-func (s *PluginSDK) LLM() LLMAPI               { return s.llm }
+
+// Media 返回媒体存储（CAS）。多模态链路的锚：Put 拿 digest，Get 取回字节。
+// 内置插件用；公开 SDK 契约不含此方法（见 MediaAPI 的注释）。
+func (s *PluginSDK) Media() MediaAPI { return s.media }
+func (s *PluginSDK) LLM() LLMAPI     { return s.llm }
 
 // ioAdapter 桥接 IOManager 到公共 SDK 的 IOInjector 接口，
 // 确保外部插件通过 s.InjectText() 等方法的调用能被路由到内核 IO 层。
@@ -298,6 +303,7 @@ type SDKConfig struct {
 	TextMemory     TextMemoryAPI
 	DocMemory      DocMemoryAPI
 	Knowledge      KnowledgeAPI
+	Media          MediaAPI
 	LLM            LLMAPI
 	Settings       SettingsAPI
 	RegTool        ToolRegistrar
@@ -344,6 +350,7 @@ func New(name string, cfg SDKConfig) *PluginSDK {
 		textMem:   cfg.TextMemory,
 		docMem:    cfg.DocMemory,
 		know:      cfg.Knowledge,
+		media:     cfg.Media,
 		llm:       cfg.LLM,
 
 		iom:       cfg.IOManager,