feat(core): 注入行为的记忆/裁剪标志位落地 + jieba 词库内嵌 + Windows 改走 WSL

配套 SDK 提交：homeagent-sdk ba49dfd（公开 API 纯追加，无签名变更）。本仓第三方的库镜像同步至该版本，以保证全新 clone 能编译。 ## 1. 注入标志位（内核侧） - 7 条注入路径（排队/中断/同步 × 纯文本/带媒体 + 旧 NoMem 变体）解析并转发 no_memory / context_policy / cleaner_name；策略在入口**校验**，非法值报错而不是静默降级成 none（降级会让调用方以为自己声明的裁剪在生效）。 - 新增 validateContextPolicy（与 tool.register 同一套规则）与 pubSdkInjectOpts。 - input.register 不再手写字段白名单重建 ChannelDef，改为整体传递 + 补 ContextPolicy。 - io 层：applyInjectOpts 把标志位写进事件 payload，仅非零时写（零值与旧 payload 逐字节一致，事件订阅方与旧内核都不受影响）。 - ioAdapter / procCore / internal-sdk 别名补齐六个 *Opts 实现。 ## 2. 修掉「输入无条件裁剪」这个真缺陷 eventloop 此前对**每条非中断输入**都调 `context.Prune(...)`：破坏性（低相关事件被归档移出上下文）且无法从调用点看出是谁触发的。改为 pruneOnInput/pruneDeclared：优先级：注入点声明（payload.context_policy）> 通道声明（ChannelDef.ContextPolicy） > 默认**不裁剪** 查询向量仍取清洗后的内容；新增 cleanInputFor 解析清洗文本，优先级为注入点声明的 cleaner（cleaner_name）> 按 source 查到的通道 cleaner > 原文，名字查不到时**记日志再回退**（注入是 fire-and-forget，插件看不到错误，至少要在内核日志留下「你声明的清洗没生效」的痕迹）。 ## 3. jieba 词库内嵌（修「猜 GOMODCACHE → 静默失效」）原 jiebaDictDir() 去猜 GOMODCACHE/GOPATH/~/go/pkg/mod，部署机上通常没有 Go 模块缓存 → GetJieba() 返回 nil → 分词/关键词提取/NLP 依存解析（进而 doc→graph 三元组抽取）/静态词向量 tokenizer **一律静默返回空列表**，只有一行日志。本机看起来正常只因开发机与生产机重合、恰好有那份缓存。现在词库随二进制分发：internal/memory/jiebadict/ 5 文件约 11.6MB + go:embed，按**内容哈希**命名缓存目录落盘（词库升级不复用旧文件），已齐全则跳过写入。模块缓存降为兜底。homed 体积 32MB。顺带确认（并有测试佐证）：gojieba 的 Tag() 不需要 pos_dict/ 目录—— cppjieba 的 PosTagger 从主词典每行的词性列取 tag。 ## 4. homed 放弃 Windows 原生，改走 WSL2 插件体系依赖「继承的 fd」+「统一共享内存区的段内偏移解引用」，Windows 既无 fd 继承语义，其句柄模型也无法表达后者；强行适配等于再维护一套平台专属 ABI （C ABI 时代三套 ABI 并存曾导致改写型插件在某平台静默失效）。 - cmd/homed/platform_{windows,other}.go：原生 Windows 启动即拒绝并打印 WSL2 指引。 - internal/plugin/proc/shmalloc_windows.go：allocShm 直接返回「请用 WSL2」， **不返回半可用的段**（与 shmalloc_other.go 同风格：未支持平台显式报错）； procEnvForShm 返回 nil。顺手修掉两处长期编译错误（cryptorand→rand、h.evData→h.unified.evtData），使 GOOS=windows 至少能编译。注：homed 本就编不出 Windows——internal/memory 依赖 cgo-only 的 gojieba。 - deploy/packaging/installer.nsi：不再安装 homed.exe/initconfig.exe，改为携带 **linux payload** 并调用新的 install-via-wsl.ps1；退出码 20/21 表示「需先装 WSL/发行版」，走指引而非报错。 - deploy/packaging/windows/install-via-wsl.ps1（新）：检测 WSL → 引导安装 → 确保 WSL2 → 送包进发行版 → 在 WSL 内按 Linux 方式安装。**复用 Linux 包与 linux/setup.sh**，不另写一套安装逻辑；落点与 deb 布局统一（/usr/bin/homed + /usr/lib/homeagent/setup.sh）。 - deploy/packaging/linux/setup.sh：API Key 允许 HOMEAGENT_API_KEY 覆盖（否则安装器界面显示一份、config.db 里另一份 → 登录不上）。 - deploy/packaging/build.sh：windows 目标只构建 waiter + gui，并新增 stage_linux_payload 把 Linux 包暂存给安装器；homed/initconfig 在 windows 目标下明确拒绝。 ## 5. 插件调用点统一写明意图 - webui 的 OpenAI 兼容端点（固定提示词模板）→ InjectTextSyncNoMemory。 - agentcli 的 5 处纯状态通知（已启动/超时/执行结束/进程退出/读取结束）→ NoMemory； **带输出**的 2 处（定时反馈、有新输出）刻意保留记忆并注明理由。 - timer 的定时提醒 → NoMemory（中断本来也隐含 NoMemory，这里是写明意图）。 ## 6. 版本 meta.Version 仍为 1.2.0（main 是下一个未发布中版本）； SDKCompatibleVersion 1.1.0 → **1.2.0**（本内核已实现 SDK 1.2.0 全部新增方法）。 ## 测试 - core：默认不裁剪（无声明/none/空）、通道 opt-in、注入点双向覆盖通道、 nil context/io 安全、cleaner 优先级与未知名回退。 - io：零值 opts 与历史 payload 逐键相同；text/中断/媒体三类注入标志位都落到 payload；旧方法仍生效。 - proc：validateContextPolicy 只接受 ""/none/prune，报错含位置与实际值； **跨进程** e2e——testdata 插件经 io.injectText 送出三个标志位，断言它们穿过 RPC 到达内核。 - memory：模块缓存不可见时内嵌词库仍可用（分词与 POS 内容词均非空）、落盘幂等、内容哈希稳定。验证：go build ./... / go vet ./... / go vet -tags onnxruntime ./... go test -short ./internal/memory/... ./internal/nlp/... ./internal/plugin/... ./internal/agent/{core,io}/... ./pkg/...
2026-10-04 00:03:59 +00:00 · 2026-09-11 20:31:50 +08:00
parent 6f8525cd83
commit f868975c0e
39 changed files with 611001 additions and 204 deletions
--- a/third_party/homeagent-sdk/sdk/plugin.go
+++ b/third_party/homeagent-sdk/sdk/plugin.go
@ -35,12 +35,63 @@ const (
 	StageAfterOutput    Stage = "after_output"
 )

+// 上下文策略：决定一次工具调用/输入/注入是否依据其内容裁剪上下文。
+//
+// 默认（空串或 ContextPolicyNone）**不裁剪**：裁剪会归档丢弃低相关事件，
+// 必须由工具/通道/注入点显式声明才发生——否则一个只想往上下文里塞内容的
+// 插件会在背后把别人的内容挤掉，且看不出是谁干的。
+const (
+	ContextPolicyNone  = "none"
+	ContextPolicyPrune = "prune"
+)
+
+// ValidContextPolicy 校验策略取值；空串等价于 ContextPolicyNone。
+func ValidContextPolicy(policy string) bool {
+	switch policy {
+	case "", ContextPolicyNone, ContextPolicyPrune:
+		return true
+	}
+	return false
+}
+
+// InjectOptions 声明一次注入行为在记忆层与上下文层的表现。
+//
+// 零值 = 记入记忆 + 不裁剪上下文，与历史行为（三参数注入方法）完全一致，
+// 因此调用方只有在确实需要改变行为时才需要填它。
+//
+// 为什么注入也要这两个标志：注入的内容来源千差万别——轮询到的频道消息
+// 属于真实对话（该记），而“任务还在跑”“连接已重连”这类提醒不该污染记忆，
+// 也不该把上下文按它的内容裁一遍。按调用点声明比按通道一刀切准确。
+//
+// NoMemory:       此次注入不参与记忆计算（向量化/关键词提取/蒸馏），原文仍留在上下文
+// ContextPolicy:  此次注入后是否依据（清洗后的）内容裁剪上下文；默认不裁剪。
+//
+//	中断注入也允许声明 prune——它同样会携带内容进入上下文。
+//
+// CleanerName:    此次注入的内容用哪个**已注册的通道 cleaner** 清洗。
+//
+//	空串 = 按注入的 source 查通道定义（既有行为）。
+//	为什么要能显式指定：注入的 source 未必是注册过的输入通道名，
+//	而注入内容往往带 ANSI/JSON 包装，需要清洗后才是有效内容；
+//	不指定就只能退到「按 source 查不到就不清洗」。
+type InjectOptions struct {
+	NoMemory      bool
+	ContextPolicy string
+	CleanerName   string
+}
+
 // ChannelDef 描述通道在记忆计算层的行为，与 ToolDef.NoMemory/Cleaner 语义一致。
 // NoMemory: 此通道输入/输出不参与记忆计算（向量化/关键词提取/蒸馏），但原文保留在上下文中
 // Cleaner:  计算层过滤函数，不改原文；仅在向量化/jieba/蒸馏/存档提取关键词时调用
+// ContextPolicy: 此通道的输入到达后是否据此裁剪上下文，默认 none（不裁剪）
+//
+// JSON tag 是必需的：通道定义要跨进程传给内核，而 Cleaner 是函数（必须忽略）。
+// 没有 tag 时既无法整体 marshal（func 不支持），又会诱使调用方手写字段白名单——
+// 那样新增字段会被静默丢掉。
 type ChannelDef struct {
-	NoMemory bool
-	Cleaner  func(string) string
+	NoMemory      bool                `json:"no_memory,omitempty"`
+	Cleaner       func(string) string `json:"-"`
+	ContextPolicy string              `json:"context_policy,omitempty"`
 }

 // StageContext provides context for stage handlers.
@ -100,13 +151,13 @@ type ToolResult struct {

 // ToolDef describes a tool that the plugin exposes.
 type ToolDef struct {
-	Name        string                 `json:"name"`
-	Plugin      string                 `json:"plugin,omitempty"`
-	Description string                 `json:"description"`
-	Parameters  map[string]interface{} `json:"parameters"`
-	NoMemory    bool                   `json:"no_memory,omitempty"` // 此工具输出不参与记忆计算，但原文保留
-	Cleaner     func(string) string    `json:"-"`                   // 计算层过滤函数，不改原文；仅在向量化/jieba/蒸馏时调用
-	ContextPolicy string               `json:"context_policy,omitempty"` // 工具上下文策略："none"(默认) / "prune"
+	Name          string                 `json:"name"`
+	Plugin        string                 `json:"plugin,omitempty"`
+	Description   string                 `json:"description"`
+	Parameters    map[string]interface{} `json:"parameters"`
+	NoMemory      bool                   `json:"no_memory,omitempty"`      // 此工具输出不参与记忆计算，但原文保留
+	Cleaner       func(string) string    `json:"-"`                        // 计算层过滤函数，不改原文；仅在向量化/jieba/蒸馏时调用
+	ContextPolicy string                 `json:"context_policy,omitempty"` // 上下文策略：""(默认，不裁剪) / ContextPolicyNone / ContextPolicyPrune
 }

 // IOInjector provides methods for injecting input and interrupts into the agent pipeline.
@ -125,6 +176,17 @@ type IOInjector interface {
 	InjectInputMedia(source, channel, text string, blocks []ContentBlock)
 	InjectInputMediaSync(source, channel, text string, blocks []ContentBlock) string
 	InjectInterruptMedia(source, channel, text string, blocks []ContentBlock)
+
+	// 以下 Opts 变体让调用点在**这一次注入**上声明记忆与裁剪行为。
+	//
+	// 上面那些不带 opts 的方法等价于传零值 InjectOptions（记入记忆 + 不裁剪），
+	// 保留它们是为了不破坏已有插件；新代码应当用 Opts 变体把意图写清楚。
+	InjectTextOpts(source, channel, text string, opts InjectOptions)
+	InjectInterruptTextOpts(source, channel, text string, opts InjectOptions)
+	InjectInputSyncOpts(source, channel, text string, opts InjectOptions) string
+	InjectInputMediaOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions)
+	InjectInputMediaSyncOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions) string
+	InjectInterruptMediaOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions)
 }

 // EventType identifies the kind of system event.
@ -505,54 +567,94 @@ func (s *PluginSDK) injector() IOInjector {
 }

 // InjectInterruptText injects a text interrupt that can preempt current LLM processing.
+// 等价于 InjectInterruptTextOpts(..., InjectOptions{})：记入记忆、不裁剪。
 func (s *PluginSDK) InjectInterruptText(source, channel, text string) {
-	if io := s.injector(); io != nil {
-		io.InjectInterruptText(source, channel, text)
-	}
+	s.InjectInterruptTextOpts(source, channel, text, InjectOptions{})
 }

 // InjectText injects a text message into the agent pipeline.
+// 等价于 InjectTextOpts(..., InjectOptions{})：记入记忆、不裁剪。
 func (s *PluginSDK) InjectText(source, channel, text string) {
-	if io := s.injector(); io != nil {
-		io.InjectText(source, channel, text)
-	}
+	s.InjectTextOpts(source, channel, text, InjectOptions{})
 }

 // InjectTextNoMemory injects a text message without generating memory.
+// 等价于 InjectTextOpts(..., InjectOptions{NoMemory: true})。
 func (s *PluginSDK) InjectTextNoMemory(source, channel, text string) {
-	if io := s.injector(); io != nil {
-		io.InjectTextNoMemory(source, channel, text)
-	}
+	s.InjectTextOpts(source, channel, text, InjectOptions{NoMemory: true})
 }

 // InjectInputSync injects a text message and synchronously waits for the agent reply,
 // returning the reply text (empty string if none). Replies must be dispatched back
 // to the source channel by the caller.
 func (s *PluginSDK) InjectInputSync(source, channel, text string) string {
-	io := s.injector()
-	if io == nil {
-		return ""
-	}
-	return io.InjectInputSync(source, channel, text)
+	return s.InjectInputSyncOpts(source, channel, text, InjectOptions{})
 }

 // InjectInputMedia 注入带媒体内容块（image_url/audio_url）的输入。
 // blocks 会落进媒体存储被记忆引用捕获，同时作为当前轮 content 数组
 // 发给 LLM，让模型在「本轮」就看到图/听到音频——区别于 SetToolBlocks
 // 的「下一轮 tool message」语义。
+// 等价于 InjectInputMediaOpts(..., InjectOptions{})。
 func (s *PluginSDK) InjectInputMedia(source, channel, text string, blocks []ContentBlock) {
-	if io := s.injector(); io != nil {
-		io.InjectInputMedia(source, channel, text, blocks)
-	}
+	s.InjectInputMediaOpts(source, channel, text, blocks, InjectOptions{})
 }

 // InjectInputMediaSync 注入带媒体内容块的输入并同步等待 agent 回复。
+// 等价于 InjectInputMediaSyncOpts(..., InjectOptions{})。
 func (s *PluginSDK) InjectInputMediaSync(source, channel, text string, blocks []ContentBlock) string {
+	return s.InjectInputMediaSyncOpts(source, channel, text, blocks, InjectOptions{})
+}
+
+// ---- 带 InjectOptions 的注入（声明记忆/裁剪行为）----
+
+// InjectTextOpts 注入文本到 agent，并在这一次注入上声明记忆与裁剪行为。
+func (s *PluginSDK) InjectTextOpts(source, channel, text string, opts InjectOptions) {
+	if io := s.injector(); io != nil {
+		io.InjectTextOpts(source, channel, text, opts)
+	}
+}
+
+// InjectInterruptTextOpts 注入可抢占当前处理的中断文本。
+//
+// 中断也允许声明 ContextPolicyPrune：中断同样携带内容进入上下文，
+// 是否需要据此裁剪由调用方决定（默认不裁剪）。
+func (s *PluginSDK) InjectInterruptTextOpts(source, channel, text string, opts InjectOptions) {
+	if io := s.injector(); io != nil {
+		io.InjectInterruptTextOpts(source, channel, text, opts)
+	}
+}
+
+// InjectInputSyncOpts 注入输入并同步等待回复，同时在这次注入上声明记忆/裁剪行为。
+func (s *PluginSDK) InjectInputSyncOpts(source, channel, text string, opts InjectOptions) string {
 	io := s.injector()
 	if io == nil {
 		return ""
 	}
-	return io.InjectInputMediaSync(source, channel, text, blocks)
+	return io.InjectInputSyncOpts(source, channel, text, opts)
+}
+
+// InjectInputMediaOpts 注入带媒体块的输入，并声明记忆/裁剪行为。
+func (s *PluginSDK) InjectInputMediaOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions) {
+	if io := s.injector(); io != nil {
+		io.InjectInputMediaOpts(source, channel, text, blocks, opts)
+	}
+}
+
+// InjectInputMediaSyncOpts 注入带媒体块的输入并同步等待回复，同时声明记忆/裁剪行为。
+func (s *PluginSDK) InjectInputMediaSyncOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions) string {
+	io := s.injector()
+	if io == nil {
+		return ""
+	}
+	return io.InjectInputMediaSyncOpts(source, channel, text, blocks, opts)
+}
+
+// InjectInterruptMediaOpts 注入带媒体块的中断，并声明记忆/裁剪行为。
+func (s *PluginSDK) InjectInterruptMediaOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions) {
+	if io := s.injector(); io != nil {
+		io.InjectInterruptMediaOpts(source, channel, text, blocks, opts)
+	}
 }

 // InjectInterruptMedia 注入带媒体内容块的中断，可抢占当前 LLM 处理。