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-03 15:53:56 +00:00 · 2026-09-11 20:31:50 +08:00
parent 6f8525cd83
commit f868975c0e
39 changed files with 611001 additions and 204 deletions
--- a/internal/agent/io/channel.go
+++ b/internal/agent/io/channel.go
@ -25,11 +25,11 @@ const (
 type OutputCapability int

 const (
-	CapText      OutputCapability = 1 << iota // 文本
-	CapFile                                   // 文件
-	CapImage                                  // 图片
-	CapAudio                                  // 音频
-	CapStructured                             // 结构化数据（JSON/卡片）
+	CapText       OutputCapability = 1 << iota // 文本
+	CapFile                                    // 文件
+	CapImage                                   // 图片
+	CapAudio                                   // 音频
+	CapStructured                              // 结构化数据（JSON/卡片）
 )

 func (c OutputCapability) Supports(cap OutputCapability) bool {
@ -242,6 +242,52 @@ func (m *IOManager) InjectInputSyncTo(source, outputChannel, eventType string, p
 	return <-ch
 }

+// InjectOptions 声明一次注入在记忆层与上下文层的表现。
+//
+// 零值 = 记入记忆 + 不裁剪上下文，与历史的三参数注入方法完全一致。
+// 别名到公共 SDK 而非另建一套：内置插件与外部插件必须用同一套结构，
+// 否则内核要认两种类型，而漏认会静默丢失标志位。
+type InjectOptions = pubsdk.InjectOptions
+
+// applyInjectOpts 把注入标志位写进事件 payload。
+//
+// 只在非零时写：零值与旧 payload 逐字节一致，事件订阅方与旧内核
+// （不认识这两个键）都不会受影响。
+//
+// 为什么不把标志位当独立参数传到底：eventloop 与各注入路径都按 payload 取字段
+// （no_memory 本来就是这么走的），payload 是这里唯一已有的携带面。
+func applyInjectOpts(payload map[string]interface{}, opts InjectOptions) {
+	if opts.NoMemory {
+		payload["no_memory"] = true
+	}
+	if opts.ContextPolicy != "" {
+		payload["context_policy"] = opts.ContextPolicy
+	}
+	if opts.CleanerName != "" {
+		payload["cleaner_name"] = opts.CleanerName
+	}
+}
+
+func (m *IOManager) InjectInputOpts(source, eventType string, payload map[string]interface{}, opts InjectOptions) {
+	applyInjectOpts(payload, opts)
+	m.InjectInput(source, eventType, payload)
+}
+
+func (m *IOManager) InjectInputToOpts(source, outputChannel, eventType string, payload map[string]interface{}, opts InjectOptions) {
+	applyInjectOpts(payload, opts)
+	m.InjectInputTo(source, outputChannel, eventType, payload)
+}
+
+func (m *IOManager) InjectInputSyncToOpts(source, outputChannel, eventType string, payload map[string]interface{}, opts InjectOptions) *OutputEvent {
+	applyInjectOpts(payload, opts)
+	return m.InjectInputSyncTo(source, outputChannel, eventType, payload)
+}
+
+func (m *IOManager) InjectInterruptOpts(source, channel string, payload map[string]interface{}, opts InjectOptions) {
+	applyInjectOpts(payload, opts)
+	m.InjectInterrupt(source, channel, payload)
+}
+
 func (m *IOManager) InjectText(source string, text string) {
 	m.InjectInput(source, "text", map[string]interface{}{
 		"content": text,
@ -293,10 +339,31 @@ func (m *IOManager) InjectInterrupt(source, channel string, payload map[string]i
 }

 func (m *IOManager) InjectInterruptText(source, channel, text string) {
-	m.InjectInterrupt(source, channel, map[string]interface{}{
+	m.InjectInterruptTextOpts(source, channel, text, InjectOptions{})
+}
+
+// InjectInterruptTextOpts 注入中断文本，并声明本次注入的记忆/裁剪行为。
+//
+// 中断也允许声明 ContextPolicyPrune：中断同样携带内容进入上下文。
+func (m *IOManager) InjectInterruptTextOpts(source, channel, text string, opts InjectOptions) {
+	m.InjectInterruptOpts(source, channel, map[string]interface{}{
 		"type":    "text",
 		"content": text,
-	})
+	}, opts)
+}
+
+// InjectTextOpts 注入排队文本，并声明本次注入的记忆/裁剪行为。
+func (m *IOManager) InjectTextOpts(source, channel, text string, opts InjectOptions) {
+	m.InjectInputToOpts(source, channel, "text", map[string]interface{}{
+		"content": text,
+	}, opts)
+}
+
+// InjectTextSyncOpts 同步注入文本并声明记忆/裁剪行为。
+func (m *IOManager) InjectTextSyncOpts(source, outputChannel, text string, opts InjectOptions) *OutputEvent {
+	return m.InjectInputSyncToOpts(source, outputChannel, "text", map[string]interface{}{
+		"content": text,
+	}, opts)
 }

 func (m *IOManager) InputInterruptChan() <-chan *InputEvent { return m.interruptCh }
@ -308,6 +375,33 @@ func (m *IOManager) InjectTextSyncTo(source, outputChannel, text string) *Output
 	})
 }

+// ---- 带标志位的注入（记忆/裁剪行为由调用点声明）----
+
+// InjectInputMediaOpts 注入带媒体块的输入，并声明记忆/裁剪行为。
+func (m *IOManager) InjectInputMediaOpts(source, outputChannel, text string, blocks []pubsdk.ContentBlock, opts InjectOptions) {
+	m.InjectInputToOpts(source, outputChannel, "text", map[string]interface{}{
+		"content":      text,
+		"media_blocks": blocks,
+	}, opts)
+}
+
+// InjectInputMediaSyncOpts 注入带媒体块的输入并同步等待回复，同时声明记忆/裁剪行为。
+func (m *IOManager) InjectInputMediaSyncOpts(source, outputChannel, text string, blocks []pubsdk.ContentBlock, opts InjectOptions) *OutputEvent {
+	return m.InjectInputSyncToOpts(source, outputChannel, "text", map[string]interface{}{
+		"content":      text,
+		"media_blocks": blocks,
+	}, opts)
+}
+
+// InjectInterruptMediaOpts 注入带媒体块的中断，并声明记忆/裁剪行为。
+func (m *IOManager) InjectInterruptMediaOpts(source, channel, text string, blocks []pubsdk.ContentBlock, opts InjectOptions) {
+	m.InjectInterruptOpts(source, channel, map[string]interface{}{
+		"type":         "text",
+		"content":      text,
+		"media_blocks": blocks,
+	}, opts)
+}
+
 func (m *IOManager) EmitOutput(target string, outputType string, payload map[string]interface{}) {
 	m.outputCh <- &OutputEvent{
 		RequestID: "",
@ -343,7 +437,7 @@ func (m *IOManager) EmitTextTo(target, outputChannel, text string) {
 	})
 }

-func (m *IOManager) InputChan() <-chan *InputEvent  { return m.inputCh }
+func (m *IOManager) InputChan() <-chan *InputEvent   { return m.inputCh }
 func (m *IOManager) OutputChan() <-chan *OutputEvent { return m.outputCh }

 // RegisterInputChannel 注册输入通道的记忆行为
@ -463,12 +557,14 @@ func NewMicrophone(name string, sampleRate int, io *IOManager) *Microphone {
 	return &Microphone{name: name, sampleRate: sampleRate, io: io}
 }

-func (d *Microphone) Name() string             { return d.name }
-func (d *Microphone) Type() DeviceType         { return DeviceInput }
+func (d *Microphone) Name() string                         { return d.name }
+func (d *Microphone) Type() DeviceType                     { return DeviceInput }
 func (d *Microphone) OutputCapabilities() OutputCapability { return 0 } // 纯输入
-func (d *Microphone) Description() string { return fmt.Sprintf("麦克风 (%s, %dHz)", d.name, d.sampleRate) }
-func (d *Microphone) Start() error        { return nil }
-func (d *Microphone) Stop() error         { return nil }
+func (d *Microphone) Description() string {
+	return fmt.Sprintf("麦克风 (%s, %dHz)", d.name, d.sampleRate)
+}
+func (d *Microphone) Start() error           { return nil }
+func (d *Microphone) Stop() error            { return nil }
 func (d *Microphone) ChannelDef() ChannelDef { return ChannelDef{} }

 func (d *Microphone) Tools() []ToolDef {
@ -498,13 +594,13 @@ func NewSpeaker(name string, io *IOManager) *Speaker {
 	return &Speaker{name: name, io: io}
 }

-func (d *Speaker) Name() string        { return d.name }
-func (d *Speaker) Type() DeviceType    { return DeviceOutput }
+func (d *Speaker) Name() string                         { return d.name }
+func (d *Speaker) Type() DeviceType                     { return DeviceOutput }
 func (d *Speaker) OutputCapabilities() OutputCapability { return CapText | CapAudio }
-func (d *Speaker) Description() string { return fmt.Sprintf("扬声器 (%s)", d.name) }
-func (d *Speaker) Start() error        { return nil }
-func (d *Speaker) Stop() error         { return nil }
-func (d *Speaker) ChannelDef() ChannelDef { return ChannelDef{} }
+func (d *Speaker) Description() string                  { return fmt.Sprintf("扬声器 (%s)", d.name) }
+func (d *Speaker) Start() error                         { return nil }
+func (d *Speaker) Stop() error                          { return nil }
+func (d *Speaker) ChannelDef() ChannelDef               { return ChannelDef{} }

 func (d *Speaker) Tools() []ToolDef {
 	return []ToolDef{{
@ -535,13 +631,13 @@ func NewCamera(name string, io *IOManager) *Camera {
 	return &Camera{name: name, io: io}
 }

-func (d *Camera) Name() string        { return d.name }
-func (d *Camera) Type() DeviceType    { return DeviceInput }
+func (d *Camera) Name() string                         { return d.name }
+func (d *Camera) Type() DeviceType                     { return DeviceInput }
 func (d *Camera) OutputCapabilities() OutputCapability { return CapImage } // 可返回图片
-func (d *Camera) Description() string { return fmt.Sprintf("摄像头 (%s)", d.name) }
-func (d *Camera) Start() error        { return nil }
-func (d *Camera) Stop() error         { return nil }
-func (d *Camera) ChannelDef() ChannelDef { return ChannelDef{} }
+func (d *Camera) Description() string                  { return fmt.Sprintf("摄像头 (%s)", d.name) }
+func (d *Camera) Start() error                         { return nil }
+func (d *Camera) Stop() error                          { return nil }
+func (d *Camera) ChannelDef() ChannelDef               { return ChannelDef{} }

 func (d *Camera) Tools() []ToolDef {
 	return []ToolDef{
@ -583,13 +679,13 @@ func NewRobotArm(name string, io *IOManager) *RobotArm {
 	return &RobotArm{name: name, io: io}
 }

-func (d *RobotArm) Name() string        { return d.name }
-func (d *RobotArm) Type() DeviceType    { return DeviceIO }
+func (d *RobotArm) Name() string                         { return d.name }
+func (d *RobotArm) Type() DeviceType                     { return DeviceIO }
 func (d *RobotArm) OutputCapabilities() OutputCapability { return CapStructured }
-func (d *RobotArm) Description() string { return fmt.Sprintf("机械臂 (%s)", d.name) }
-func (d *RobotArm) Start() error        { return nil }
-func (d *RobotArm) Stop() error         { return nil }
-func (d *RobotArm) ChannelDef() ChannelDef { return ChannelDef{} }
+func (d *RobotArm) Description() string                  { return fmt.Sprintf("机械臂 (%s)", d.name) }
+func (d *RobotArm) Start() error                         { return nil }
+func (d *RobotArm) Stop() error                          { return nil }
+func (d *RobotArm) ChannelDef() ChannelDef               { return ChannelDef{} }

 func (d *RobotArm) Tools() []ToolDef {
 	return []ToolDef{
@ -635,13 +731,13 @@ func NewGPIODevice(name string, pins []int, io *IOManager) *GPIODevice {
 	return &GPIODevice{name: name, pins: pins, io: io}
 }

-func (d *GPIODevice) Name() string        { return d.name }
-func (d *GPIODevice) Type() DeviceType    { return DeviceIO }
+func (d *GPIODevice) Name() string                         { return d.name }
+func (d *GPIODevice) Type() DeviceType                     { return DeviceIO }
 func (d *GPIODevice) OutputCapabilities() OutputCapability { return CapStructured }
-func (d *GPIODevice) Description() string { return "GPIO 通用引脚" }
-func (d *GPIODevice) Start() error        { return nil }
-func (d *GPIODevice) Stop() error         { return nil }
-func (d *GPIODevice) ChannelDef() ChannelDef { return ChannelDef{} }
+func (d *GPIODevice) Description() string                  { return "GPIO 通用引脚" }
+func (d *GPIODevice) Start() error                         { return nil }
+func (d *GPIODevice) Stop() error                          { return nil }
+func (d *GPIODevice) ChannelDef() ChannelDef               { return ChannelDef{} }

 func (d *GPIODevice) Tools() []ToolDef {
 	return []ToolDef{
--- a/internal/agent/io/injectopts_test.go
+++ b/internal/agent/io/injectopts_test.go
@ -0,0 +1,111 @@
+package io
+
+import (
+	"testing"
+
+	pubsdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk"
+)
+
+// drainOne 取出一条注入事件；没有则 Fatal。
+func drainOne(t *testing.T, ch <-chan *InputEvent) *InputEvent {
+	t.Helper()
+	select {
+	case evt := <-ch:
+		return evt
+	default:
+		t.Fatal("没有拿到注入事件")
+		return nil
+	}
+}
+
+// 零值 InjectOptions 必须与历史的三参数注入产出**完全一致**的 payload。
+//
+// 这是兼容性底线：任何按 payload 取字段的下游（事件订阅方、旧内核、
+// 工具链测试）都不能因为这次改造而看到新键。
+func TestInjectTextOpts_ZeroValueMatchesLegacyPayload(t *testing.T) {
+	m := NewIOManager()
+	m.InjectText("src", "hello")
+	legacy := drainOne(t, m.InputChan())
+
+	m2 := NewIOManager()
+	m2.InjectTextOpts("src", "chan", "hello", InjectOptions{})
+	withOpts := drainOne(t, m2.InputChan())
+
+	if len(withOpts.Payload) != len(legacy.Payload) {
+		t.Fatalf("零值注入多出了键：legacy=%v opts=%v", legacy.Payload, withOpts.Payload)
+	}
+	for k, v := range legacy.Payload {
+		if withOpts.Payload[k] != v {
+			t.Fatalf("键 %q 不一致：legacy=%v opts=%v", k, v, withOpts.Payload[k])
+		}
+	}
+}
+
+// 标志位必须出现在事件 payload 上——eventloop 就是从那里读的。
+func TestInjectTextOpts_CarriesFlags(t *testing.T) {
+	m := NewIOManager()
+	m.InjectTextOpts("src", "chan", "hello", InjectOptions{
+		NoMemory:      true,
+		ContextPolicy: "prune",
+		CleanerName:   "clean_me",
+	})
+	evt := drainOne(t, m.InputChan())
+
+	if evt.Payload["no_memory"] != true {
+		t.Errorf("no_memory 未传递: %v", evt.Payload["no_memory"])
+	}
+	if evt.Payload["context_policy"] != "prune" {
+		t.Errorf("context_policy 未传递: %v", evt.Payload["context_policy"])
+	}
+	if evt.Payload["cleaner_name"] != "clean_me" {
+		t.Errorf("cleaner_name 未传递: %v", evt.Payload["cleaner_name"])
+	}
+	if evt.Payload["content"] != "hello" {
+		t.Errorf("content 丢失: %v", evt.Payload["content"])
+	}
+	if evt.OutputChannel != "chan" {
+		t.Errorf("输出通道 = %q，期望 chan", evt.OutputChannel)
+	}
+}
+
+// 中断注入走另一条队列，标志位同样要带上（用户已确认中断允许声明 prune）。
+func TestInjectInterruptTextOpts_CarriesFlags(t *testing.T) {
+	m := NewIOManager()
+	m.InjectInterruptTextOpts("src", "chan", "alert", InjectOptions{ContextPolicy: "prune"})
+	evt := drainOne(t, m.InputInterruptChan())
+
+	if evt.Payload["context_policy"] != "prune" {
+		t.Errorf("中断注入的 context_policy 未传递: %v", evt.Payload)
+	}
+	if evt.Payload["type"] != "text" || evt.Payload["content"] != "alert" {
+		t.Errorf("中断注入的基本字段不对: %v", evt.Payload)
+	}
+	if _, has := evt.Payload["no_memory"]; has {
+		t.Errorf("未声明的 no_memory 不应出现: %v", evt.Payload)
+	}
+}
+
+// 带媒体的注入同样要带标志位。
+func TestInjectInputMediaOpts_CarriesFlags(t *testing.T) {
+	m := NewIOManager()
+	blocks := []pubsdk.ContentBlock{{Type: "image_url", ImageURL: &pubsdk.ImageURL{URL: "data:image/png;base64,AA"}}}
+	m.InjectInputMediaOpts("src", "chan", "看图", blocks, InjectOptions{NoMemory: true})
+	evt := drainOne(t, m.InputChan())
+
+	if evt.Payload["no_memory"] != true {
+		t.Errorf("媒体的 no_memory 未传递: %v", evt.Payload)
+	}
+	if _, ok := evt.Payload["media_blocks"]; !ok {
+		t.Errorf("媒体块丢失: %v", evt.Payload)
+	}
+}
+
+// 旧方法必须继续等价工作（它们是 Opts 变体的零值糖）。
+func TestLegacyNoMemoryMethodStillSetsFlag(t *testing.T) {
+	m := NewIOManager()
+	m.InjectTextNoMemoryTo("src", "chan", "quiet")
+	evt := drainOne(t, m.InputChan())
+	if evt.Payload["no_memory"] != true {
+		t.Fatalf("旧 NoMemory 方法应置位: %v", evt.Payload)
+	}
+}