a971fc8877
feat(scheduler): M5 饥饿防护（抢占计数提升有效级 + 抢占冷却）
...
设计依据 docs/zh/input-scheduler-design.md §9、§11.5（G1/G2）。
- Task 增加 PreemptCount / LastPreemptAt；effectiveLevel(t) =
min(L4, Level + min(PreemptCount, 2))：被抢占越多越“值钱”，
逐步追上抢占它的流，但封顶 L4 因而抢不过真正的紧急输入
- 选择函数 taskBefore 改用有效级；requestPreempt 与 preemptGrantedFor
同样以有效级比较
- 抢占冷却 preemptCooldown=2s：刚被抢占的任务期内不再被抢占，
避免同一任务被反复打断到永不完结
- 新增 scheduler_starvation_test.go 4 项：提升与封顶、冷却期内不得再抢占、
提升后同级不得抢占而更高可、选择函数确实用有效级
- 验收：agent 全量 + -race；全仓 build/vet 通过
2026-09-13 00:38:30 +08:00
7565248f61
feat(scheduler): M4 临界区显式化 + 清掉被 pendingInterrupts 取代的 interceptCh
...
设计依据 docs/zh/input-scheduler-design.md §4.3、§11.1（P5/P6）。
- 临界区语义显式化：让位检查**只在 step 之间**做，执行中的 step
（工具 RPC / ONNX / CAS 落盘）天然不可抢占；_consolidation_ 整任务
经 inCriticalSection() 判为不可抢占（它直接改图库）
- 删除 interceptCh 与 drainInterrupts：M3b 起中断一律走 pendingInterrupts，
旧的「同行注入 + 三处 drain + 批次放弃」已无写入者，属死代码
- 新增 scheduler_critical_test.go 3 项：
P5/P6 工具执行中 arm 了让位信号也不得挂起、必须等工具返回后的安全点；
_consolidation_ 判为临界区；无抢占时同批工具必须全部执行（新语义回归）
- 验收：agent 全量 + -race；全仓 build/vet 通过
2026-09-13 00:34:39 +08:00
c69a1f11af
feat(scheduler): M3a+M3b 任务生命周期重构 + 四级优先级抢占
...
设计依据 docs/zh/input-scheduler-design.md §3–§8、§14。
M3a（行为等价的所有权重构）：
- processInput 拆为 prepareInputTask / runTaskSteps / finishInputTask，
帧覆盖 prepare→step…→finish；提交与回执只在 finish 段发生一次，
为安全点挂起做准备（挂起不重复提交）
- process() 不再持 a.mu（挂起不能持锁），a.mu 字段随之移除
- TaskFrame 增加任务层现场（Evt/CleanInput/IsInterrupt/StartedAt/Terminal/
Level/SeedMsgs）与 taskTerminal / outcomeSuspended
- 新增 task_lifecycle_test.go 5 项：正常恰好一次终态、去重 skipped、
on_input 短路、错误终态、consolidation 路由
M3b（优先级与抢占）：
- interceptLoop 重写：只做「收中断 → 定级 → requestPreempt → 必要时取消
LLM」，绝不触碰帧（不变量 I2）；三条降级路径与 interceptCh 兜底退场，
改为统一的 pendingInterrupts
- scheduler：pendingInterrupts / suspendPool / 让位信号，nextRef 在三集合上
按统一排序键取值；深度上限 4（canSuspend 在安全点拦下）
- 抢占判据 incoming.level > running.level；相等与更低只入队
- 安全点只在 step 之间；执行中的 step（工具 RPC/ONNX/CAS）天然不可抢占；
_consolidation_ 整任务视为临界区
- 恢复走 resumeTask：从 frame.Step 继续，不重跑 prepare
- D1=A：suspend 把被打断任务的只读前缀交给抢占比它的中断任务（SeedMsgs）
- 新增 scheduler_preempt_test.go 5 项：抢占-挂起-恢复（含 R1/R5）、同级更低
不抢占、深度上限、空闲中断不丢、seed 路径不污染标志位
验收：agent 全量 + -race 通过；全仓 build/vet 通过
2026-09-13 00:25:52 +08:00
7082a50365
feat(scheduler): M2 调度器骨架（就绪队列 + 选择函数 + 快照 + 任务级 panic 隔离）
...
设计依据 docs/zh/input-scheduler-design.md §14 M2。
- 新增 scheduler.go：四级 Level 常量（默认 L1，显式才是特权）、
Task/TaskKind、scheduler（有界队列/running/统计）、纯函数 pickTaskIndex
（排序键 -Level → EnqueuedAt → ID）、schedulerLoop/pumpInbox/executeTask、
DumpScheduler 原子快照
- eventLoop 退场，职责由 schedulerLoop 承担；M2 全部任务为 L1，
因而行为等价于原先的 channel FIFO
- 每任务 panic 隔离（不变量 I6）：panic 只失败该任务，调度器存活，
取代原先「重启整个循环」
- Start() 改起 schedulerLoop；interceptLoop 暂不动（M3 重写）
- 新增 scheduler_test.go：Q1 排序 4 组、Q4 背压、生命周期、K1 panic 隔离、
O1 快照一致性、Level 取值契约
- 验收：agent 全量 + -race 通过
2026-09-12 23:49:55 +08:00
9a588780b9
refactor(scheduler): M1 把 process() 拆成 step 状态机 + TaskFrame（行为等价）
...
设计依据 docs/zh/input-scheduler-design.md §14 M1。
- 新增 task.go：Step 游标、TaskFrame，以及 stepPrepare/stepLLM/
stepToolBegin/stepToolExec/stepToolAfter/stepTurnEnd 六个 step；
原函数内嵌的 provider 回退/重试抽为 resolveProviders + callLLMWithFallback
- process() 改为驱动状态机的薄壳：签名不变，调用方（processInput/
processConsolidation/测试）零改动
- StepToolExec 显式标注为临界区：工具副作用不可回滚，执行中不是安全点
- 步数上限护栏：转移缺失时以错误退出而非死循环
- 新增 task_test.go：R3（工具往返结果与配对正确）、X3（多轮必然终止）、
批中途中断必须放弃剩余工具、未知 step 必须失败退出
- 验收：既有 agent 全量测试通过；-race 通过（TMPDIR 指向真实磁盘，
/tmp tmpfs 已 98% 满会导致链接失败，与代码无关）
2026-09-12 23:47:12 +08:00
5aaae93367
feat(healthcheck): 内核状态快照报出内核版本号与 ONNX 模型启用状态
...
healthcheck_kernel 此前没有任何「ONNX 模型是否在用」的信息，只报「向量可用/不可用」，
分不清「统一多模态空间已加载」与「退回到词嵌入/TF-IDF 路径」；人格卡要求
「版本以运行时快照为准」，也缺一个可查字段（build.version 早就在，但没人知道）。
- KernelStatus 新增 onnx 段：enabled / provider / dim / fingerprint / modalities / reason。
判据取 Loaded()（provider 真正打开且元数据合法），**不是**「配置里写了 provider」
—— 后者在模型缺失 / 运行时缺失时也为真，报出去就是假绿。
- 未启用时 reason 给**具体原因**：未配置（说明会走回退路径）/ 打开失败的具体错误。
homed 把「配置的 provider 名」与「打开失败原因」透传给 Agent，仅供状态报告。
- ProviderAdapter 新增 Modalities()（可选能力，按接口断言取用，不改公开契约）。
- healthcheck_kernel 的工具描述同步说明它回答这两件事。
**顺带修一个真实 panic**：collectKernelStatus 的 knowledge 是**接口**参数，
(*knowledge.Store)(nil) 塞进接口后 `ks != nil` 仍为真 → 调 List() 直接 panic，
而 healthcheck_kernel 正是走这条路径（panic 发生在工具 goroutine 里）。
GetKernelStatus 改为先按具体指针判空、再赋给接口；并加刻画测试钉住这个成因
（一旦不再 panic 说明参数形状已变，守卫与该测试应同步删除）。
验证：单测 4 例（已启用 / 打开失败 / 未配置 / 未加载）+ 刻画测试；
隔离实例 E2E 7/7：正例 provider=chineseclip → enabled=true、dim=512、模态 2；
反例 provider=nonexistent → enabled=false 且 reason 含具体错误与 provider 名，
真实对话仍通。
2026-09-12 14:56:25 +08:00
46e014a8ca
feat(persona): 首启人格门禁跨通道化 + 内核 persona_set 工具
...
WebUI 首启向导只覆盖 WebUI 这一条通道，而「人格该问一次」是所有通道的事：
走 QQ / CLI / ACP / 邮件来的人永远见不到那个向导，人格就永远是没确认过。
- 门禁移到 buildSystemPrompt（每轮重建 → WebUI/QQ/CLI/ACP/邮件全覆盖），
以 core.internal.persona_initialized 为准：未确认时要求模型主动询问用户
（默认 / 自定义 / 以后再说），确认后该段消失；personaStore 为 nil 时静默关闭。
- 新增内核内置工具 persona_set(mode=default|custom|later[, content])，
落库逻辑与 WebUI 向导**共用 internal/config**（一个实现 + 两个薄入口：
ConfigRegistry 直连 / 插件侧 SettingsAPI），避免两套语义各自漂移。
- AgentConfig 增加 PersonaStore 接口，cmd/homed 用 RegistryPersonaStore 实现。
- 非法输入（未知 mode / custom 空内容）在打标记**之前**拒绝：否则标记置位、
向导被跳过，用户再没机会设。
E2E（隔离实例 + 真实 LLM 往返走 /v1/chat/completions，/var/tmp/persona/e2e.sh）9/9 PASS：
未确认时模型主动询问 → 用户答「用默认的」→ 模型调用 persona_set 落库并置位标记
→ 之后不再追问；反向对照（清标记 + 清会话上下文 + 重启）重新开始询问，
排除了「同一段对话里已问过」这一混淆。
2026-09-12 13:57:06 +08:00
dc80855540
feat(status): 暴露构建源码地址，WebUI 状态页给出 AGPL §13 的源码入口
...
选了 AGPL-3.0-only 之后，§13（Remote Network Interaction）就不只是声明问题：
把修改过的版本作为网络服务提供出去时，必须给使用者取得 Corresponding Source 的机会。
只在仓库里放 LICENSE 并不自动满足这一条——**使用者拿到的是服务，不是仓库**。
所以把它做进产品里，而不是写进文档就算完：
- `internal/meta.SourceURL`：本次构建对应的源码地址，默认指向本仓库。
注释里写明「修改后对外部署的分支必须改指向自己的仓库」，并给出 -ldflags 覆盖方式
（`-X .../internal/meta.SourceURL=<你的仓库>`），不需要改源码。
- `BuildStatus.SourceURL`（`json:"source_url,omitempty"`）+ 内核状态填充：
走已有的 `/api/v1/kernel` 构建身份链路，不新增端点。
- WebUI 状态页在「版本」行下渲染「源码 / Source」链接（URL 经 escHtml 转义后进属性；
`target="_blank" rel="noopener noreferrer"`）。
- 用 `omitempty`：未注入该值的旧构建不会在 JSON 里多出一个空字段。
验证：
- `internal/plugins/webui/dashboard.html` 的两个内联 script 块 `node --check` 均通过；
- 全仓库 `go build ./...` 通过，`internal/meta/meta.go` gofmt 干净
（`internal/agent/core/status.go` 有**既有**的 gofmt 差异，与本改动无关，按纪律未整体重排）；
- 端到端：本地构建 homed → 冷启动 → `GET /api/v1/kernel` 的 `build.source_url`
实测为 `https://gitcode.com/JianFeeeee/HomeAgent `。
2026-09-12 09:41:39 +08:00
f1091676f8
style: gofmt 两处对齐（graphmedia_test.go 注释、tfidf.go 结构体字段）
...
这两处是本次特性分支带入的格式回归（origin/main 上不脏）。
纯空白/对齐调整，无语义变化；不整体重排文件。
2026-09-12 08:23:30 +08:00
d1959cbe80
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-09-11 20:31:50 +08:00
1a02971f88
feat(memory): 千问三段式 ONNX 嵌入补齐——可复现导出脚本 + Go 侧首次完整验证
...
此前三段式拆分后 ONNX 路径从未从 Go 侧跑通：embedder_onnx_test.go 仍引用
分段前的 API（e.renderInput、TextTower.onnx、旧目录），go vet -tags onnxruntime
直接编译失败。导出脚本只在 /tmp 且硬编码本机路径、从第三个目录拷贝固定形状的
Vision.onnx，完全不可复现。音频会被视觉塔编码，静默往统一空间灌入错误坐标。
本提交补齐这些缺口：
一、可复现导出脚本（scripts/export_qwen3vl_embedding_onnx.py）
- 自动拉取模型（HuggingFace 优先，失败回落 ModelScope，支持 HF_ENDPOINT 镜像）；
- 导出 TokenEmbedding + Transformer + Vision 三段图，图文共用同一 token
embedding、28 层 Transformer、last-token 池化与 fingerprint；
- 双重自检（不可省）：分段 PyTorch vs 完整模型 + 导出后的 ONNX vs 完整模型，
cos < 0.999999 即非零退出——「能加载」不等于「算得对」；
- 默认把 L2 归一化后的冻结参考向量写入产物目录（qwen_reference.json）——
Go 测试据此做逐维冻结回归，且「该目录是哪次导出的」从文件本身可追溯；
- --verify-only 校验既有产物不重新导出，可用来确认线上在用的图没坏。
关键实测结论（已写入 docs/zh/multimodal-space.md 与长期记忆）：
原生多帧视频不可行——Qwen3-VL 视觉塔把 grid_thw 当 Python 值消费
（grid_thw.tolist()），legacy tracer 固化为常量，导出后图中根本没有 grid_thw
输入，换帧数调用直接 Invalid input name: grid_thw。故视觉塔固定 (1,48,48)，
视频由上层抽帧后逐帧按图像编码（同模型/同维度/同 fingerprint），音频明确
unsupported。
二、模态边界（vector.ErrModalityUnsupported）
- 新增 vector.ErrModalityUnsupported：表示「该模态不在本统一空间的原生覆盖
范围内」，与普通错误语义不同——调用方应把它当「永远不会有向量」而非
「本次失败、下次重试」；
- qwen.EmbedImageDense 按 mime 拒绝 audio/* 与 video/*：此前它会拿视觉塔
去解音频字节，往统一空间灌入语义错误的坐标且静默；
- reembedStaleMedia 对 ErrModalityUnsupported 不计失败、不重试、不用别的
模型向量顶替（TestReembedStaleMedia_SkipsUnsupportedWithoutFaking 守住）。
三、Go ONNX 测试首次完整通过
- 重写 embedder_onnx_test.go：修复编译 + 文本冻结回归 + 图像冻结回归 +
两条阴性对照（不同输入必须不同、图像与文本必须不同）+ 不支持模态断言；
- 参考值从产物目录的 qwen_reference.json 读取（不在测试里硬编码浮点）；
- 用线上部署产物实测全部通过（text cos=0.999999940, image cos=0.999999762）。
四、.gitignore 修复
- /scripts/ 此前被列在「运行时产物」下，但它是作者维护的工具目录
（模型导出、侧车、部署校验），deploy/systemd/embed-sidecar.service 直接
引用 scripts/embed_sidecar.py，忽略它会让那份 unit 在别人的机器上指向
不存在的文件。改为只忽略 __pycache__。
五、文档（docs/zh/multimodal-space.md）
- 获取/启用/产物契约/模态边界/验证/资源成本/与现有部署产物的等价性。
验证：go build ./...、go vet ./...、go vet -tags onnxruntime ./...、
go test -short 全部通过；ONNX 标签测试对线上部署产物全部通过。
2026-09-11 13:45:25 +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
dae01f9c06
refactor(memory): 移除 media_refs/引用计数，媒体成为一等记忆块
...
媒体此前是"文本块 + digest 引用 + owner 账本 + 独立 GC"：ContextEvent.Media
记 digest，media_refs 表用 owner_kind/owner_id 保活，ref_count 决定 GC 能否清。
这与文本记忆块的管理方式不一致，也是本次一并纠正的核心偏差。
改为与文本块完全一致的生命周期：
1. 一等记忆块直接由所在层持有
- ContextEvent.Blocks / Doc.Blocks / GraphDB memory_blocks
- 块带 modality/digest/MIME/size/vector/fingerprint，文本、图片、视频同构
- Context→Document→Graph 迁移的是块本身（ID 不变），迁移后清空源容器，
同一块不同时存在于两层
2. 删除平行生命周期账本
- media.Store 去掉 media_refs 表、OwnerKind 常量、RefCount 字段、
AddRef/DropRef/DropOwner/Refs、ref_count 列与索引
- 删除 mediaGCLoop、GC(keep,minAge)、容量上限与 media.gc_* / media.max_mb 配置
- 媒体内容在块被永久删除时一并删除（media.Store.Delete + forgetPayloads），
与"删除文本块即删除内容"同一语义
3. L3 原生结构
- memory_blocks / memory_block_edges（contains/depicts/derived_from）
- 边端点必须是真实图节点，不再用 owner 字符串伪装关系
- BlocksForNode 支持 sentence --contains--> block 反查
4. SDK 与检索同步
- 插件附件/标记直接变成块，不再 AddRef
- 跨模态检索改用 QueryMediaScored（CAS 内不再有孤儿缓存需要过滤）
测试全部改写为块语义：删除 refcount/media_refs/GC 断言，新增块迁移、
单层不变量、Delete 语义与并发删除回归。
注：cmd/homed/main.go 同时携带工作区中既有的 CLIP→Qwen 模型目录接线改动。
2026-09-11 10:57:22 +08:00
b393b7072c
fix(ctx): prune 的查询向量改用插件 Cleaner 清洗后的有效内容(§13.8)
...
ContextPolicy=prune 上线时直接把**原始**工具结果传给 RelevanceContext.Prune，
而 Prune 的入参是**相关性查询向量**——它决定保留/归档哪些上下文事件。于是
ANSI 转义、base64、JSON 包装等噪声全被编进查询向量，打分失真，裁掉本该
保留的事件。
而 ToolDef.Cleaner 的契约本就写着「仅在向量化/jieba/蒸馏时调用」，裁剪正是
在向量化——所以这是**回归契约**，不是新增能力。此前只在构建事件向量
（context.go 的 toolOutputClean）时用了 Cleaner，裁剪查询这一处漏了。
回退规则（Cleaner 是计算层优化，不能因它失效而丢内容）：
- 未注册 Cleaner → 原文
- RPC 失败 → 原文（proc 侧 cleanerProxy 已有此保证）
- 返回空串 → 原文（空串会让查询向量退化成零向量，所有事件相关性相同，
等于随机裁剪）
验证：TestToolOutputForQueryAppliesCleaner（Cleaner 被调用恰好一次且用其
结果；无 Cleaner / nil stageHost 回退原文）、
TestToolOutputForQueryEmptyCleanFallsBack。
顺带把 §13.13 第 5 条（反向大结果）按核实结论结掉为「不做」：核实发现根本
不存在 llm.chat（llm.* 只映射切换 LLM 源），唯一可能返回大结果的 doc.query
没有任何外部插件使用且已被 CapDocMemory 能力门限制。留成永久 TODO 只会误导。
2026-09-10 23:59:12 +08:00
e218d0f100
fix(agent): 工具循环占位不再驱动重复发送，输出回执/子任务结果幂等
...
生产现象：单轮内 output_send__qq 被调用 34 次、持续 514 秒，直到 QQ 插件
自己的循环保险拒绝发送才停下（problem.md）。根因是多环节叠加，核心侧修四处：
1. 工具轮补位文案（process.go）
通用占位「请根据以上工具结果继续。」对纯输出通道调用是错的：异步通道
（qq/wechat）的回复只能经 output_send__* 交付，所以模型「已完成回复」的
表达形式就是一个工具调用，紧随其后的「请继续」会被读成「还要再做一步」，
而能做的「一步」恰好还是再发一条消息。
改为按上一批工具的性质选文案：全部是 output_send__* 时补
「若你的回复已完成，直接返回纯文本即可结束本轮，无需再调用任何工具。」
同时每轮先移除旧占位再补一条，避免占位在 prompt 前缀里线性累积。
（该占位是 zen 网关「最后一条必须是 user」的传输层附加物，HEAD 版本是
无条件内联追加、从不移除。）
2. 输出成功回执（output.go）
「已通过 [qq] 通道发送: map[status:sent]」这类富回执会被读成「这步成功，
继续下一步」。成功改为只回极简标记。
3. proc 桥标量透传（internal/plugin/proc/plugin.go）
插件返回 "ok" 时不再伪造 {status:sent} 覆盖插件真实返回值，否则只改
output.go 不生效。
4. 子任务结果幂等（spawn.go）
child_result 原先读到即删，而完成通知长期留在持久上下文里
（formatMergedTimeline 每轮重新注入），第二次查询必然得到
「不存在或已过期」这个永久失败信号，模型据此认为任务未完成而反复重试。
改为保留结果 + delivered 标记，重复查询返回明确提示；结果按上限有界淘汰。
顺带：agent.go 去掉文档层显式向量器注入（TF-IDF 已内置为 fallback），
cmd/homed/main.go 同步 document.NewStore 的 tokenizer 参数。
测试：internal/agent/core/tooloop_test.go（5 例）、spawn_test.go（3 例）。
2026-09-10 20:36:39 +08:00
cf3c99233b
fix(shm): 审核修复——arena 并发安全 + ToolCall ring 抢占 + arenaRead 校验
...
§13.2: arenaAlloc 改 CAS bump（修复并发覆盖）；arenaRead 增加 generation + arena 边界校验
§13.3: Reserve 从 Store+Load 改 CAS-free→Reserved 状态机抢占帧（修复并发分配重复）；
增加 RESERVED 中间态；SetReading/SetReady 改 CAS 返回 bool；ReleaseFrame 清零跳过 state
§13.5/13.6: 注入方法接入 resolveText（从 arena 读 SharedRef）；cleanerProxy 加 arenaMu 串行化+每次重置
§13.8: ContextPolicy prune topK 改为 maxContextSize-1（不再硬编码 20）
tool.register 校验 context_policy 只允许 none/prune
2026-09-10 17:03:32 +08:00
772a494223
feat(ctx): ContextPolicy tool 上下文策略(§13.8)
...
- SDK ToolDef 加 ContextPolicy string（默认 none / 可设 prune）
- StageAfterToolcall 后检查工具 ContextPolicy=prune → RelevanceContext.Prune
- 所有现有测试通过
2026-09-10 15:41:23 +08:00
580d5f5501
feat(doc): dense vector index for unified text+media retrieval
...
文档层引入稠密向量索引，与媒体检索共享同一多模态空间：
- Doc 加 DenseVec 字段（json:-，运行时计算）
- Consume/QueryScored 优先使用 denseSearchScored（brute-force cosine），
未配置时退化到 TF-IDF 倒排检索
- buildDenseIndex 在 Agent 启动时为全部文档一次性计算稠密向量
- L0 RelevanceContext 支持 denseSpace（Prune 使用稠密余弦），
退化到 fastText 稀疏余弦
vector 包新增 DenseCosine（[]float64 brute-force cosine）。
验证：492 篇文档 brute-force ~300ms，全部测试通过。
2026-09-09 18:56:44 +08:00
6c2039f5c9
feat(vector): pluggable multimodal vector space
...
核心暴露 MultimodalEmbedder 接口，两条路径共享同一套 L0/L2/L3
向量缓存、media.Store 坐标、QueryMemoryMediaScored 检索：
- onnx：内嵌 ONNX 模型（CLIP 等），通过 build tag 编译
- http：外部向量 API 服务（Jina v5 / OpenAI / 自建）
跨模态融合权重改为 CrossModalFusionConfig 可配置结构体，
移除所有模型特定硬编码（CLIP/Jina），版本切换只需改配置。
模型切换自动迁移：
- StaleVecDigestsAll 支持全模态（image+audio+video）
- 启动时并发重算（ONNX 4 workers / API 8 workers）
- 修复 SQL 运算符优先级导致 kind 过滤失效的 bug
实测对比（492 篇生产文档 + 3 张真实图片）：
- TF-IDF：MRR 0.457（精确匹配快，语义差）
- fastText：MRR 0.530（语义中等，延迟 8ms）
- Jina v5-omni：MRR 0.900（全面领先，延迟 40ms）
- 中文文本→图片：Jina MRR 0.833 vs CLIP 0.611
See docs/embedding-comparison.md for full benchmark.
2026-09-09 17:38:34 +08:00
98365f3a55
feat(clip): 多模态向量器（CLIP ONNX）——文本/图像 512 维共享空间 + 媒体向量写入与重算
...
- internal/memory/clip：CLIP ONNX 向量器（onnxruntime 构建标签控制，默认构建不链接 ONNX）
- clip.New(modelDir) 加载 text.onnx/vision.onnx（输出 text_embed/image_embed [batch,512]）
- 实现 vector.Vectorizer + vector.MultimodalEmbedder（Vectorize/EmbedImage + Dense 变体）
- 词级 BPE tokenizer：merges 合并后词末片段带 </w> 查 vocab，与官方 encode 逐 id 对齐
- EmbedImage：解码→resize 224→NCHW→normalize→vision session
- Fingerprint（text+vision 文件 sha256）供模型切换检测
- stub 版（无 onnxruntime 标签）保持默认构建行为不变
- vector/store.go：新增 MultimodalEmbedder 接口
- media.Store：新增 StaleVecDigests(currentModel)——查 vec_model 不匹配/缺失的图片
- agent core：AgentConfig.ClipEmbedder + Agent.clipEmb 接线；
describePendingMedia 描述成功后 EmbedImageDense→SetVec；
新增 reembedStaleMedia 启动补算历史无向量图片
- config：core.memory.media.clip_model_dir（未配置退化为现有 fastText/TF-IDF 行为）
- cmd/homed：读 clip_model_dir 加载 CLIP，失败仅记日志不阻塞启动
测试：TestSmokeLoadAndEncode（文本语义 cat>dog 0.914>physics 0.740）、
TestCrossModalAlignment（red-image vs red-text 0.063>blue -0.009，与 Python 一致）、
TestTokEnd（与官方 encode 逐 id 对齐）、TestStaleVecDigests，含 -race 全绿
2026-09-09 10:23:31 +08:00
687e5655bc
feat(sdk): 多模态贯通插件边界——公开接口、内核桥接与统一输入主干
...
记忆系统在 1.1.0 支持了二进制多媒体节点，但那条链路只对**内核自己**开放：
用户在 qq 发图能落进 CAS、能被记忆引用，而插件调 Commit / DocMemory().Insert
交进来的媒体一律无处安放。原因是三层都断着，且**每一层都不报错**。
## 一、公开 SDK：补上媒体的表达能力（全部新增，无签名变更）
- `Triple` += `SentenceText`、`MediaDigests`
- `Doc` += `MediaDigests`、`Attachments`；新增 `MediaAttachment`
- `TextEvent` += `Attachments`
- `DocMemoryAPI` += `InsertWithMedia`
- `IOInjector` += `InjectInputMedia` / `InjectInputMediaSync` / `InjectInterruptMedia`
- `PluginSDK` 补上一直缺失的 `SetToolBlocks` 包装（接口里有、便捷方法里没有）
`MediaAttachment` 一个类型服务两个方向：给 `Data`+`MIME` 是新内容（CAS 按字节
去重），只给 `Digest` 是引用已有内容。读路径**只回元数据不回字节**——一次检索
可能命中几十份媒体，全塞回去会把跨进程消息撑爆。
媒体注入不能搭 `SetToolBlocks` 的车：那个方法只在工具处理函数内部可用，且媒体
要等下一条 tool message 才到模型手上。插件主动发起一轮带媒体的对话、以及中断
注入，需要自己的签名，且媒体在**本轮**就送到模型。
## 二、内核桥接层：原先在静默裁字段
`internal/sdk/memory_impl.go` 此前只搬自己认识的几个字段，其余丢弃且返回 nil：
- 图记忆丢 `Confidence`/`SubjectType`/`ObjectType`/`SentenceText`，又走 `Commit`
而非 `CommitWithMedia`（不回 sentenceIDs）→ 媒体绑定链 `SentenceText → sentences
→ sentence_id → media_refs` 一步都走不通，插件即便按格式写好标记也永远挂不上；
- 知识库 `Query` 只回 ID/Title/Content，`Insert` 只写这三个；`Remove` 不解引用，
于是那些媒体永久处于「被引用」状态，GC 收不掉、磁盘只增不减
（内核的归档路径 `releaseDocMedia` 做了这一步，插件路径漏了同一步）。
规则改为：**内部结构有的字段一律透传**。标记格式处理作为包级私有辅助留在桥接
层自己手里，但必须与内核 `mediaSummaryForEvent` 字节兼容——两边要能互读对方
写下的标记。
标记插入必须在 `ds.Insert` **之前**（向量索引取 `Summary + " " + Content`，
之后补的标记检索不到），引用绑定必须在**之后**（owner_id 是 Insert 生成的 ID）。
## 三、跨进程链路：不接线就是全体外部插件编译失败
`go test` 直接把这一层拍出来了——`procIO does not implement sdk.IOInjector`。
公开接口加方法后，生成模板不跟上，**每个外部插件都编不过**，是硬失败不是软降级。
六处接线：`protocol.go` 四个 method 常量、`capability.go` 能力归属、
`corehandler.go` 四个分派分支、`proc_core.go` 委托、`proc_main.go.tmpl` 模板侧
实现、以及三个测试替身。
## 四、统一输入主干：把模态从「函数选择」降级为「字段」
`processTextInput` / `processMediaInput` 合并为 `processInput`。这个分叉是历史
产物而非设计：`processTextInput` 本来就处理媒体（`bindEventMedia` +
`mediaSummaryForEvent`，与媒体路径尾部完全相同），`process()` 只看
`stageCtx.Extra["media_blocks"]`、根本不认识 `evt.Type`。模态是输入的**属性**，
不是输入的**种类**。
媒体路径由此获得它一直缺的六项：去重、`no_memory`、通道 `Cleaner`、中断语义、
`_consolidation_` 路由、正确的 `EventRawInput`。
最后一项是个真 bug：媒体路径发布 `"content": evt.Payload`（一个 map），而
`webui/handler.go` 断言 `.(string)` → 断言失败、`content == ""`、提前返回。
**用户发的图从来没出现在 WebUI 聊天记录里。**
`media_blocks` 同时接受 `[]agentAPI.ContentBlock` 与 `[]pubsdk.ContentBlock`：
字段一致但 Go 不自动转换，只认一种的后果是另一种被静默丢弃。
## 五、模型可调用的三个工具
`memory_commit` 的 `sentence_text` **从未暴露给模型**，而它是绑定链上的必经环节；
连同 `media_digests` 一起补进 JSON schema 与工具文档。`doc_commit` 加
`media_digests`。`doc_query` 把关联媒体单独一行附在结果末尾（正文按 2000 字截断，
标记通常就在尾部）。
标记由**内核**生成而非插件/模型拼装：要求调用方知道格式，等于让一个拼写错误
静默切断引用绑定，而全链路无人报错。
## 六、WebUI 上传走真实媒体链路
图片/音频读回字节拼 data URL 注入 `media_blocks`（8MB 上限，超限退回按路径处理）。
此前只注入一句「文件已保存到 <路径>」，指望模型自己调 `files_read`——但那返回
文本，图片字节对模型永远不可见。附件类型识别扩展到 audio 并在缺 Content-Type
时按扩展名兜底（判错不只是卡片样式问题，图片被当普通文件就进不了视觉链路）。
## 测试
- `internal/sdk/memory_impl_test.go`（12 例，此前该包**没有任何测试文件**）
- `internal/agent/core/inputunify_test.go`（统一主干 + 双静态类型 + 三工具媒体）
- `third_party/homeagent-sdk/sdk/stress_test.go`（13 例并发压测）
压测抓到两处**真**竞态（不是理论风险）：`PluginSDK` 的 API 字段与 `autoRestart`
无锁，而写方（内核注入 API、插件 `SetAutoRestart`）与读方（插件后台 goroutine
注入、内核 registry 读 `AutoRestart`）天然跨 goroutine。加 `apiMu` 修掉；约定
只在持锁期间取字段值，取完即释放再调用——持锁调用会把 `InjectInputSync` 这类
阻塞到 agent 回复（可达数分钟）的方法与 `SetIOInjector` 串起来，让插件重载卡死。
测试还抓出两个自身缺陷：`bindDocMedia` 把同一份媒体数两次（`AddRef` 幂等所以表
是对的，但日志说「绑定 2 个」而实际 1 条——误导后续排查），以及用单字符实体名
时 `validEntityName` 静默跳过、`Commit` 返回 nil 却什么都没写。
存量插件不需要改一行也不需要重编：新增方法由插件调用、内核实现，不调就不受影响。
17 个 example 插件源码零改动通过类型检查。
2026-09-06 09:51:31 +08:00
a7b54fef7f
test(memory): 修正数据丢失回归用例的构造——它被媒体三元组修复本身弄失效了
...
两个修复之间产生了耦合：TestArchiveColdDocs_KeepsDocWhenGraphWriteEmpty
的前提是「三元组全被 validEntityName 拒绝」，而同批引入的
mediaTriplesFromText 会为正文里的 [image/png <digest>] 标记产出合规的
「图片 <digest>」三元组，于是 ec=4 rc=2、绑定成功、释放引用变成正确行为，
用例的前提消失。
（注意当时 GC 断言并未触发——内容没丢，只是"引用被释放"这条断言不再
适用于该构造。）
改法：正文不再含媒体标记，媒体引用直接 AddRef 挂上。这模拟的是更危险的
组合——文档持有媒体引用，但正文里的媒体标记已在清洗中丢失，于是有引用
要释放却没有句子能承载它。那正是这个守卫要防的情形。
反向验证重做后仍成立：回退守卫 → FAIL（引用被释放 + GC 删掉了本该保留的
内容）；恢复修复 → ok。
教训：只跑针对性测试不足以发现修复之间的耦合。提交前我跑的是
internal/agent/core 与 internal/memory，当时通过是因为缺陷二尚未修完；
两个修复都落地后的第一次全仓回归才暴露它。
2026-09-05 12:08:33 +08:00
387b28ce09
fix(memory): 媒体归档三缺陷——数据丢失、L3 入库不可靠、L3 检索未接线
...
自动触发链实测（medialive）连续暴露的三个缺陷，全部是「手工调 API 的
单测无法发现」的类型。附带该实测本身。
## 缺陷一：三元组全被拒时仍释放引用并删文档（数据丢失）
archiveColdDocs 只检查 len(triples) > 0 就释放媒体引用、删除文档。
但 Commit 会静默跳过实体名不合法的三元组（validEntityName 要求
2–50 字符），于是「无错但一条也没写进去」真实发生：
[agent] doc→graph: doc_xxx → 0 entities, 0 relations
[media] 文档 doc_xxx 入图库，释放 1 个媒体引用（描述已留在图库）
被记忆引用的内容被 GC 删除了（清 1 条/318 字节）
图库里没有任何句子承载引用，文档也被删，blob 被 GC 回收 → 图片与描述
彻底消失。我在上一层写的注释「Commit 之后引用已挂到 graph_sentence」
是错的：ec=0 rc=0 时它什么也没挂。
修法（用户选定 B+A）：
B. ec==0 && rc==0 时保留文档、跳过归档——归档的实质是「信息从 L2
搬到 L3」，搬不过去就不该删源，下轮再试。
A. bindSentenceMedia 返回实际绑定数，commitTriplesWithMedia 透出为
mediaBound；释放前四路判断（查引用出错→保守不释放／本无引用→无需
释放／mediaBound==0→保留并记录原因／否则释放）。宁可留一条悬空
引用（内容还在，可由后续一致性检查清理）也不能丢内容。
反向验证：旧行为下新测试确实 FAIL，报「引用被释放了」+「GC 删掉了本该
保留的内容」；恢复修复后 PASS。
## 缺陷二：媒体入 L3 依赖 NLP 提取器运气（可靠性）
媒体能否进图库，取决于提取器碰巧从描述文本里提出合规三元组。实测 LLM
的 477 字图片描述只产出「水平 -分割-> 成」，obj 仅 1 字被拒 → 整条媒体
记忆进不了图库。表现为「阶段 5 时好时坏」，取决于描述文本。
但媒体自身的 digest / mime / 描述都是确定的，不该受提取器支配。
新增 parseMediaMarkers + mediaTriplesFromText：从文档正文的媒体标记
直接产出确定三元组，先于 NLP 提取。同一份真实文档由 0 entities 0
relations 变为 ec=4 rc=2 且拿到句子 id。
三个设计点：
- 实体名用「图片 <短digest>」而非描述：描述会被重新生成（换视觉模型、
补描述），若名字取自描述，同一张图会在图谱上留下多个节点。digest
不变则名字不变，长度也天然合规。
- SentenceText 用原始标记段，保证 bindSentenceMedia 的正则必然能反解
到 digest——绑定从概率事件变成确定行为。
- 描述为空时仍产出「类型」三元组：描述是后台异步补的，媒体节点不该
因为还没描述就不存在于图谱。
- summarizeForEntity 按 rune 截断而非字节：按字节切会破坏 UTF-8，
图库里会留下乱码实体名。同时清 Markdown 强调符。
这是过渡方案，用户已定：下个 feature 换多模态嵌入后不再依赖
「描述文本 → 提取三元组 → 图谱节点」这条链路。
## 缺陷三：L3 媒体检索没有任何调用方（接线缺失）
第四层实现的 RecallMediaForSentence / mediaContextForSentences 从未被
调用——媒体能存进 L3、能反查，但 agent 拿不出来。实测第二轮 agent 显式
调了 doc_query，回答「没有找到那张图片的任何记录」。
接两个入口：
- buildMemoryContext（自动注入，每次 LLM 调用都走）
- memory_recall 工具结果末尾（显式查询）
关系行只有实体名和关系类型，看不出「这条记忆当时还带了一张图」，
媒体挂在句子上，必须经 关系→句子→media_refs 反查。
一处折返：最初直接用 injected.Relations 取 sentence_id，测试失败。
Indexer.BuildContext 刻意把 Relations 置 nil（自动注入只给实体索引以省
token，细节留给 memory_recall）。改为用命中的实体名再查一次关系，
深度固定 1——媒体是「这条记忆当时带的图」，顺关系网扩散只会带出无关
媒体并挤占 token。
## medialive 自动触发链实测
internal/agent/core/medialive_test.go，medialive build tag，默认
go test 不收录。源/模型/密钥全部由调用方经环境变量显式指定，缺任何一项
Skip 并列出缺哪个——刻意不提供 fallback，猜一个 base_url 可能打到调用者
机器上不相干的服务，而失败会被误报成「媒体记忆有问题」。
MEDIALIVE_BASE_URL=... MEDIALIVE_API_KEY=... \
MEDIALIVE_MODEL=... MEDIALIVE_ADAPTER=... \
go test -tags medialive ./internal/agent/core/ -run TestMediaLive -v
只注入一个 image 事件，之后七个阶段全由生产代码自己触发：CAS 落盘 →
引用绑定 → 描述生成 → L0→L2 转移 → L2→L3 绑定 → GC 保护 → 第二轮召回。
另有阴性对照：不给记忆时不该「记得」，否则阳性用例的通过可能只是模型
猜常见配色。上游不可用时 Skip 而非假 PASS。
真实 claude-opus-5 实测通过：第二轮不给图，agent 答出
「上：紫罗兰色 #8800DD / 中：蓝色 #0055EE / 下：纯红 #EE0000」。
## 测试
graphmedia_test.go 新增 8 例：数据丢失回归（反向验证过）、mediaBound
计数、媒体标记解析、实体名生成、描述截断、确定性三元组必然可入库、
关系→句子映射、L3 检索接线（自动注入与显式查询两路）。
全仓 go build / go vet / go test 通过，internal/agent/core 与
internal/memory 全绿，SDK 冻结 diff = 0。
2026-09-05 12:03:30 +08:00
775d9e8a2e
fix(memory): core.New 漏接 rc.SetMediaStore，L0→L2 引用转移在生产从未生效
...
RelevanceContext.transferMediaRefs 依赖 c.mediaStore，而该字段只有
SetMediaStore() 能设置。搜遍全仓非测试代码，调用点为零——core.New() 里
没有，cmd/homed/main.go 里也没有。
上一层（f855893）把 AgentConfig.MediaStore 接到了 Agent.mediaStore，
漏了 rc 这一路。
后果是静默的：Prune 归档时 c.mediaStore 为 nil，transferMediaRefs 直接
return，而携带引用的 ContextEvent 已被归档删除 → 引用永久悬空在
context owner 上、计数永不归零 → 对应 blob 永远不会被 GC 回收。
## 为什么测试没抓到
mediaref_test.go 里我手工调了 rc.SetMediaStore(ms) 才测转移逻辑。
**测试验证了函数正确，没验证它被接上了。** 与 findPluginPID 那次同一
个教训：测了一件不会自然发生的事。
## 顺带全字段审计
写脚本比对 AgentConfig 的 32 个字段与 New() 函数体的引用情况，
确认无第二处漏接。
2026-09-05 12:02:34 +08:00
28fc833a6f
feat(memory): L3 图库媒体反查 + 修 L2→L3 引用泄漏
...
媒体记忆四层收尾。方案 A：只做引用，不建媒体实体节点。
## 为何不把媒体建成图库实体
图库里的实体与关系全部来自**描述文本**的 NLP 提取——描述经
mediaSummaryForEvent 进 L0 事件的 Input，随归档进 L2 文档的 Content，
蒸馏时提取器自然从描述文字里抽出实体和关系。检索能力已经具备。
若再把媒体本身建成节点，节点名只能从描述里取，而描述会被重新生成
（换个视觉模型、补一次描述，名字就变了），于是同一张图会在图谱上留下
多个语义模糊的节点。代价换不来能力。
所以这一层只做一件事：**反查**。图库句子写着「[image a1b2c3d4e5f6]
一张紫蓝红三色带图」，要能从这条句子取回那份字节。
## CommitWithMedia：新增方法而非改签名
Commit 有 10 个非测试调用点 + 21 个测试调用点。为一个多数调用方都不需要
的返回值改全部签名不划算。新增 CommitWithMedia 返回
map[句子文本]sentences.id，Commit 内部转调同一份落库逻辑。
## digest 靠正则从文本反解
三元组由 NLP 提取器从纯文本产出（nlp.ToMemoryTriple 只填 Subject/
Relation/Object/Confidence/SentenceText），提取链路上没有任何位置能塞进
结构化的 digest。要贯通就得改 internal/nlp 的整条数据流。而媒体标记本身
是我们自己按固定格式写进文本的，反解是最省的可靠做法。
配套加 media.ResolvePrefix：文本里是 12 位短 digest（完整 64 位会把一行
撑爆且无助人眼辨认），media_refs 主键要完整 digest。
**前缀歧义视为错误而非"取第一个"**：挂错引用会让 GC 删掉仍被引用的内容。
完整但不存在的 digest 也报错，否则调用方会挂一条孤儿引用。
## 顺带修掉 L2→L3 的引用泄漏
这是上一层（f855893）留下的缺口：我当时只处理了 L0→L2 的引用转移，
漏了 L2→L3 这一跳。archiveColdDocs 调 docStore.Remove(doc.ID) 时不注销
媒体引用——文档一旦消失就再没有任何东西能告诉我们它引用过哪些 digest，
media_refs 里那条记录永久悬空、引用计数永不归零，对应 blob 永远不会被
GC 回收。
新增 releaseDocMedia。L2→L3 这一跳是**释放**而非转移，因为图库存的是从
描述文本抽出的实体与关系，不再持有字节；媒体此时已完成使命。
顺序有讲究：必须在 commitTriplesWithMedia 之后释放。那一步已把引用挂到
graph_sentence owner 上，先销后挂会让引用计数瞬时归零，此时若后台 GC
正在跑就会把内容当孤儿清掉。
## 顺带修 Pending 的排除逻辑遗漏（承上一提交）
## 测试
graphmedia_test.go 11 例。核心是 TestBindSentenceMedia_RoundTrip：
写入 → 提交 → 从句子 id 反查 digest → 取回字节逐字节比对 → 跑 GC(0)
确认被引用的内容不被清。
其余覆盖：正则不误命中普通方括号（[注意]/[TODO] 不能当 digest，否则会拿
假前缀去 ResolvePrefix）、无法补全的 digest 不挂引用、媒体关闭时全链路
静默 no-op、releaseDocMedia 释放后 GC 真能回收、200 个样本的前缀补全
要么唯一命中要么明确报歧义。
TestCommit_StillWorksAfterRefactor 记录一个既有行为：重复提交时
entitiesCreated 不归零，因为 SQLite 的 ON CONFLICT DO UPDATE 也算一行
affected。用 main 分支的 graph.go 单独跑过基线确认与本次重构无关，
该字段只用于日志，故记录现状不改行为。
全仓 go build / go vet / go test 通过，internal/agent/core 与
internal/memory 全部 -race -count=2 通过，SDK 冻结 diff = 0。
2026-09-04 22:52:30 +08:00
74a24f93d7
feat(memory): 媒体 GC 与描述生成两条后台循环
...
补齐媒体记忆的最后两块：容量上限真正生效，描述文本成为持久语义记忆。
## mediaGCLoop：让容量上限不再形同虚设
CAS 的 GC 只在被显式调用时执行，Put 路径不触发它。此前配置项
core.memory.media.max_mb 注册了却没有任何调用方——一次 see_video 抽 10 帧，
帧本身在工具结果被 Prune 后就没人引用了，若无人清理会一直堆在磁盘上。
现在按 gc_interval（默认 6h）周期调 GC(gc_min_age)。两个不变量：
- 有引用的内容永不删除，即使超容量（宁可超限也不断引用）
- gc_min_age（默认 1h）保护刚 Put 还没来得及 AddRef 的项——它们
refcount 也是 0
## mediaDescribeLoop：描述才是能活过 GC 的那部分
blob 会被容量 GC 淘汰，而描述留在 media 表里，并经 mediaSummaryForEvent
写进 L0 事件、随归档进 L2 文档、经蒸馏进 L3 图库。于是「那张紫蓝红三色
带图」在原始字节早已被清掉之后仍然可被检索到。
复用既有的视觉回退链（resolveModalFallback + chatModalFallbackBatch），
不新造一套模型调用。
三个刻意的决定：
- **走后台而非入库时同步**：视觉模型一次调用生产实测 9.6s。放在对话
路径上会让每张图都给回复加十几秒，而描述的价值是几个月后还能检索到，
不是这一轮——这一轮模型本来就直接看着图。
- **逐条而非批量**：批量拿回来是一整段文字，无法可靠切分回各自的
digest（模型未必按序号输出，也可能把两张图合并成一句）。宁可多几次
往返也要保证「描述 ↔ digest」的对应关系确定。
- **默认关闭**（describe_on_ingest=false）：它消耗视觉模型配额。开启后
每 30s 最多处理 4 条，不跟对话抢额度。
失败处理分三类：
- 网络抖动/配额 → 不标记，下轮重试
- 空回复 → 视作失败（上游剥离媒体时通常回空，与 modalfallback 同理）
- 不可描述（kind=other、blob 已丢失）→ 标记 described_by=unsupported/
content-missing，退出队列
## 顺带修掉 Pending 的一个真缺陷
测试写出来才发现：Pending 原先只看 `description = ''`，于是被标记为
described_by=unsupported 但 description 仍空的项**每轮都会被重新取出来
重试**，永久占着 LIMIT 的名额，真正需要描述的新项永远轮不到。
改为同时要求 described_by 也为空。
这是「先写断言再看它是否成立」抓到的——原本我以为标记一下就够了。
## 测试
medialoop_test.go 7 例：两条循环在禁用时立即返回（nil store / 零间隔 /
describe 关闭三种形态，不留空转 goroutine）、GC 清孤儿保留有引用项、
minAge 保护新项、无可用源时不误标记、不可描述大类被标记后退出队列。
media_test.go 补 1 例专测 Pending 的排除逻辑。
全仓 go build / go vet / go test 通过，SDK 冻结 diff = 0。
2026-09-04 22:00:03 +08:00
f855893d1c
feat(memory): 媒体接入 L0/L2——digest 挂到对话事件，归档时引用随之转移
...
在 a822674
2026-09-04 20:53:32 +08:00
3907347cac
fix(multimodal): 媒体改挂独立 user message，落实「注入后续对话」的原意
...
插件三个工具的返回文案一直写着「已将图片注入后续对话」，b777322 的提交
说明也写着「模型在下一轮 LLM 请求里直接看到图」。但实现是把 block 挂在
tool message 的 content 数组上——role=tool 上的多模态 content 不被当作
可视内容。
同一张图、同一个模型、三轮实测：
图在 user message → 3/3 读到，prompt_tokens 7089
图在 tool message → 0/3（模型答「我没能读到这张图」），tokens 7967
tool 纯文本 + 后接 user → 3/3 读到，tokens 7570
tool message 那轮 token 反而更高，说明 base64 确实进了上游，只是模型看
不到它。这解释了为什么此前只有回退链（转文字进 tool message 的纯文本
content）能用，而「主模型直接看图」这条路从 b777322
2026-09-04 07:49:30 +08:00
09071dc235
fix(multimodal): 修多模态假成功 + 落地视觉回退链 + see_video 帧数语义
...
## 起因
生产盲测：模型调 multimodal_see_picture 后声称看到了图，实际一个字
都没收到。工具却返回「[已将图片注入后续对话]」。
链路：core.llm.model=AUTO → llmsproxy 按优先级选 big-pickle(prio=100)
→ 转 opencode zen。llmsproxy 的 opencode.lua 明写着：
-- zen 上游 schema 只接受 text content part（无视觉/音频能力）
if part.type ~= nil and part.type ~= "text" then -- 丢弃
判据：256x256 纯红 PNG，带图与不带图的 prompt_tokens 都是 256。
图片贡献零 token，即根本没进上游。
内核序列化与注入链本身是对的（Message.MarshalJSON 正确产出 content
数组，SetToolBlocks → IOManager → ConsumeToolBlocks → toolMsg.Blocks
全通）。缺的是「主模型能否消费这些块」这一判断——内核此前完全没有
多模态能力的概念（grep supportsVision|multimodal 在 agent/ 零命中）。
这与 v1.0.0 修的 output_send 假成功同类：告诉调用方成功而实际未送达。
## 1. 能力声明
新增 core.llm.sources.<name>.vision / .audio（走既有 sourceFieldDefs，
WebUI 配置页自动出现），types.LLMSource 与 api.BaseConfig 同步加字段。
新增 agentAPI.ModalProvider 接口 + ProviderSupportsVision/Audio 判定：
未实现该接口的 provider 一律按不支持处理。保守侧是刻意的——宁可多走
一次文字回退，也不能把图默默扔给会剥掉它的上游。
为何是声明而非探测：探测需额外真实调用且结果不稳定（取决于 AUTO 当次
路由到哪）；而 200 响应 + 相同 token 数从响应侧无法区分「看到了但没
内容」和「被剥掉了」。
## 2. 回退链（modalfallback.go）
实现了 config/registry.go 里注册但从未被读取的 image/audio
fallback_provider + fallback_model（此前 0 处读取点）。
prepareToolBlocks 在 process.go 注入前判定：能直视就原样透传；不能就
调声明了该能力的源转写成文字，带 [由 X 转写，非当前模型直接感知] 标注。
几处刻意的设计：
- 逐模态判定，不一刀切。很多视觉模型能看图但听不到音频，全部降级会
白白把可直视的图变成二手描述
- 混合场景下转写文字作为 text 块并入 native，两部分同时到达模型
- 配置指向未声明能力的源时拒绝并继续找——照用只会重演静默剥离
- 未配 fallback_provider 但某源声明了 vision 时自动扫出来用；静默失败
比多找一个能用的源更糟
- 空回复算失败。上游剥掉媒体后模型往往回「我没看到图片」或空串，两种
都说明回退链也没真看到
- 多媒体块按模态合包为一次请求（见下）
## 3. 批量合包（生产实测驱动的返工）
首版逐块调用，生产 see_video 6 帧实测：4 帧里 3 帧超时，整轮 363 秒。
改为按模态合包一次请求后同一用例 131 秒、6/6 成功。
顺带把 modalFallbackTimeout 从 90s 提到 180s：生产经网关转
claude-opus-5 看一张 400x400 图要 ~81s，90s 贴着上限。
多张时 detail 默认 low 控体积，单张用 high 看细节；插件显式给了
detail 则尊重它。
## 4. see_video 帧数语义
fps=1/N 是频率（每 N 秒一帧）不是数量。20s 视频实测：
frames=4 → 5 帧、frames=10 → 2 帧、frames=1 → 20 帧，要得越多拿得越少；
长视频下 frames=4 会产出 时长/4 帧，靠 i>=9 的 break 兜着才没炸上下文，
而那个 break 用的是 ReadDir 索引，跳过条目后与实际帧数错位。
改为 ffprobe 取时长 → fps=N/时长 + -frames:v N 硬封顶。
0.4s/3s/20s/120s × frames=1/2/4/7/10 全部精确。
极短视频的坑：fps=1 在 0.4s 素材上产出 0 帧（不足一秒抽不出），所以
时长探测失败时不能退化成 fps=1，改为不传 -vf 只靠 -frames:v。
## 验证
- modalfallback_test.go 14 例：直视透传 / 回退转写 / 无源如实报告 /
未实现接口按不支持 / 混合模态拆分 / 空回复算失败 / 块数上限 /
多图合一次调用 / detail 策略 / 拒绝未声明能力的源 / 未配置时自动扫源
- go test ./... 全绿，go vet 无警告
- 生产盲测（答案预先封存、生成时不读）：随机三色带 → 模型答
「紫、蓝、红」，与封存答案完全一致
- 负向验证：拿掉回退源后模型如实回答「没看到图片内容」并引用工具返回
的配置提示，且主动纠正了上一轮的答案
- 生产 see_video 6 帧：单次转写，模型正确描述测试图卡的计数器递增与
彩虹带滚动
2026-09-04 06:25:51 +08:00
f91b27aedb
fix: WebUI 版本显示 + Windows 交叉编译 + 发布脚本三处回归
...
## WebUI 版本链路修复
问题：handler.go:949 报的是 sdk.SDKVersion，那条链最终指向
SDK 仓 meta.Version 的硬编码值，与 -ldflags 注入的内核版本
完全不相交。构建时间、commit hash 全部丢失。
dashboard.html 兜底值是 '0.1.0'——碰巧版本号相等时不显眼，
一旦不等就报错。
修复：
- KernelStatus 新增 BuildStatus 字段（Version/Commit/BuildTime/SDKCompatible/KernelName）
取自 internal/meta（-ldflags 注入点），与接口冻结无关（KernelStatus 只在 internal/sdk）
- /api/v1/status 改用 meta.Version，另加 sdk_version 字段暴露 SDK 版本
- dashboard.html 概览卡显示 HomeAgent vX.Y.Z + commit/日期/SDK 兼容版本，
去掉 || '0.1.0' 误导性兜底
## Windows 交叉编译修复
问题：internal/plugin/dynamic_proc_windows.go（Part 1 的桩，610e9d0）只定义了
tryLoadProc，但平台中立的 registry.go 还在调 loadProc / closeProcHost——这两个
函数只在 dynamic_proc_unix.go 里。Windows 下整个 homed 从 Part 1 起编译不过。
plan.md §12.5 声称「Windows 只做了交叉编译，无真机验证」——实际是连编译都没通过。
修复：dynamic_proc_unix.go / dynamic_proc_windows.go 合并为平台中立的
dynamic_proc.go（文件内无任何平台专属调用，proc 包内部通过
shmalloc_* / evtfd_* / shmpass_* / procattr_* 各自带构建标签处理差异）。
## 发布脚本三处回归修复
deploy/packaging/build.sh（从 package/build.sh 移到 deploy/packaging/ 后）：
1. PROJECT_ROOT 少一层目录（.. → ../..），产物落进 deploy/build/ 而非根目录
2. initconfig 从未被构建，但 installer.nsi 和 package-linux.sh 都引用它
3. GO 兜底路径指向 /home/jianf/go1.26.5（陈旧硬编码）改为 command -v go
4. electron-builder --config package.json 校验整个文件导致 devDependencies 被判为 unknown
property，去掉 --config 让它从 build 键读配置
deploy/packaging/package-linux.sh：
1. build_go() 补上 initconfig 构建步骤
2. GO 兜底路径同步修复
知识库 3 条重写 + 1 条新增：
- homeagent_identity：v0.9.0 C ABI → v1.0.0 子进程
- homeagent_architecture：全篇重写为子进程架构（三面通信、Supervisor 台账、
崩溃自愈、权限三道闸）
- homeagent_recent_updates：在 v0.9.0 前插入 v1.0.0 主线摘要
- changelog_v1.0.0（新建）：6 类缺陷消除、架构、实测、已知限制、迁移指引
2026-09-03 15:38:31 +08:00
02cc74ce11
fix(proc): 子进程崩溃自愈 + 集中台账 + 注册面摘除
...
根因：子进程插件被 kill 后，内核只发了一个无人订阅的事件，
工具/stage handler/IO 通道全留在注册表里指向死进程，
模型继续调用只吃 ErrProcessExited，没有任何路径把插件拉回来。
## 四层修复
### 1. 专职 waitLoop（进程收割）
- 每个子进程配一根 waitLoop goroutine，是 cmd.Wait() 的唯一调用点
- 不再依赖 stdout EOF 判定死亡（孙子进程继承 stdout 时 EOF 永不到来）
- 手工 os.Pipe 替代 cmd.StdinPipe/StdoutPipe，避免 waitLoop 与
os/exec 的内部关闭竞争
- host.go: Host.Supervisor()，Host.Close() 先 StopAll 再拆段
### 2. 集中台账 Supervisor
- proc/supervisor.go: 插件 Spawn 握手成功即 track，进程退出即 untrack
- StopAll: 并发发 plugin.stop 走优雅路径，到期仍在的一律 Kill
- 关停后才完成握手的进程被立即结束，不会活过内核
- 消除「孤儿进程持共享段映射 → SIGBUS」的隐患
### 3. 注册面摘除（detachPlugin）
- 新增 StageHost.UnregisterPluginStages：摘除指定插件的全部 stage handler
- 新增 Registry.pluginChannels 台账：记录每个插件注册的 IO 通道
- 三条路径统一走 detachPlugin：Disable / ReloadOne / RemovePlugin
- StopAndUnload 漏了 IO 通道也一并补上
### 4. 自动重启
- onProcCrash 从「只发事件」改为「摘注册面 → 从注册表移除 → 异步排重启」
- scheduleProcRestart: 窗口 5 分钟内最多 3 次，线性退避 1s/2s/3s
- 超限停手留日志；重启前复核是否已被 Disable 或被其他路径加载
- 崩溃计数窗口过期自动归零
### 5. 主动停止 vs 崩溃的区分
- proc.Plugin 新增 stopping 标志：Stop()/Close() 里 Set(true)
- handleExit 读 stopping 标志，主动停止不上报 onCrash
- 防止重载/禁用/卸载被误判为崩溃触发多余重启
### 6. Linux Pdeathsig 兜底
- procattr_linux.go: SysProcAttr.Pdeathsig = SIGKILL
- 兜 homed 自身被 SIGKILL/OOM 时子进程变孤儿的场景
- macOS/Windows 无等价物，空实现
### 7. pluginmgr 升级
- PluginManager 接口新增 PluginRuntime / ListPluginRuntimes
- plugin_list 输出运行态：loaded / alive / pid / crash_count / channel
- 新增 plugin_status: 全量运行期快照 + dead/unhealthy 汇总
- 新增 plugin_restart: 无条件重启单个插件（plgreload 不动未改二进制的插件）
### 测试
- process_test.go: 3 例（grandchild stdout 感知 / Supervisor track-untrack /
StopAll 无孤儿）
- crash_recovery_test.go: 8 例（detach 三项齐全 / 通道重注册 / 崩溃不阻塞 /
退避阈值 / 窗口过期 / 关停中跳过 / PluginRuntime 通道识别）
- stages_plugin_test.go: 4 例（stage 按插件摘除 / 空 stage 清理 / 空名 no-op /
工具+stage 双摘后可重新注册同名）
2026-09-03 12:37:58 +08:00
b74ee15321
fix(cabi): output_send 等待真实发送结果，消除假成功（plan 11.1 / Part 0.1）
...
根因：CORE_REGISTER_OUTPUT_CH handler 无条件返回 {status:queued}+err=nil，
模型永远收到「已发送」，实际失败（如 meta 缺 user_id）只写日志，模型无法感知不会重试。
现网近 7 天成功 44 次、失败 2 次全部谎报成功。
改动：
- loader.go: 新增 awaitOutputResult（+可注入版 awaitOutputResultWith）+ outputSendTimeout=10s
goroutine 执行 cgo 发送 + 带超时 channel 等结果 → sent / error / unconfirmed 三态
handler 由 executeOutputSendTool 从 Go 侧调起，非 cgo 栈，不构成 cgo 嵌套
- output.go: executeOutputSendTool 识别 unconfirmed|queued，回报「发送结果未确认」而非「已发送」
- output_test.go: Success/Failure/Timeout 三用例
验证: go build exit 0; go test ./internal/plugin/... ./internal/agent/... 全绿
接口冻结: git diff third_party/homeagent-sdk/sdk/ 为空
2026-08-31 12:16:39 +08:00
b777322b95
feat(multimodal): 内置多模态感知插件 + process.go 原生支持 tool message 多模态块
...
【新插件 internal/plugins/multimodal】
- see_picture(path): 读取本地图片/URL，base64 注入 image_url block，
模型在下一轮 LLM 请求的 tool message 里直接看到图（1024×1024 图约 8500 token）。
自动识别 MIME，限 3MB 防爆 context。
- see_video(path, frames): ffmpeg 提取关键帧，多帧作为 image_url block 注入。
默认 4 帧，最大 10 帧，每帧限 2MB。
- listen(path): 读取音频文件，转为 audio_url block 注入，支持 mp3/wav/ogg/m4a。
限 5MB。
【内核多模态 tool message 支持】
- agent/api 新增 ToolOutput 类型（为后续 handler 直接返回 blocks 预留）
- SDK 公共层新增 ContentBlock/ImageURL/AudioURL（OpenAI 多模态格式）
- IOManager 新增 SetToolBlocks/ConsumeToolBlocks（interface{} 避免循环依赖）
- PluginSDK.SetToolBlocks(blocks) 插件工具调用后注入 blocks
- ioAdapter 桥接 IOInjector.SetToolBlocks
- process.go 工具执行后消费 pending blocks → 追加到 tool message 的 Blocks 字段
→ MarshalJSON 输出 content 数组格式 → LLM 看到图/音频
【验证】
multimodal_see_picture 注入 1024×1024 PNG 后 llmsproxy 统计：
prompt_tokens=44407（含 ~8500 image token），模型正确描述了图片内容。
2026-08-27 08:39:21 +08:00
ddef1956b5
fix(agent): 流式并行 tool_call 按 JSON index 分桶，修复空参数调用
...
【根因】内核流式解析层丢弃了上游 SSE 分片的 OpenAI index 字段：
- openAIToolCall 结构体无 index 字段，JSON 解析即丢
- homed 的 openai.lua 转换为扁平结构时同样未透传 index
- accumulateStream 退而用 Go range slice 序号做累积桶 key，
但每个 SSE chunk 只含一个 tool_call 元素，序号恒为 0
于是并行多工具调用（index=0,1,2,3）的所有分片全部写入同一个桶：
name 相互覆盖、args 碎片混拼成非法 JSON → parseToolArgsJSON
失败返回空 map → 工具以空参数被调用（spawn_child 报'请提供 task'、
cmd_run 报'command is required'等），agent 只能串行重试自愈。
单工具场景只有一个 index 无污染，故简单请求一直正常；
pi 直连同一 llmsproxy 正常（其实现标准按 index 累积）。
【修复】
- ToolCall 增加 StreamIndex（json:stream_index），openAIToolCall
解析上游 index 并透传；openai.lua 输出 stream_index 字段
- accumulateStream 以 tc.StreamIndex 为累积 key
- flushToolCall 区分三种空参：未收到分片/碎片非合法 JSON/合法空
对象({})，分别打诊断日志，避免误报
- 回归测试 TestAccumulateStreamParallelToolCallsByIndex 模拟
4 路并行分片流验证按 index 正确分组与参数完整性
另含 spawn_child max_turns 参数、child_result 运行中状态区分、
provider 层非流式空参诊断日志。
2026-08-26 16:10:02 +08:00
6009ce801f
feat(agent): spawn_child 支持 max_turns + 并行策略引导
...
1. spawn_child 新增 max_turns 参数（1-30，默认 5）
子 Agent 工具轮数此前硬编码 5，复杂任务跑不完即截断。现可按任务
复杂度调整；返回消息带轮数上限提示。
2. 工具描述与 system prompt 增加并行策略引导
明确'多个互不依赖的子任务应并行 spawn 多个子 Agent，不要串行
逐个执行；长耗时任务交给子 Agent 避免阻塞对话'——针对生产实例
观察到的 agent 倾向自己串行处理所有子任务的问题。
小宅自定义 prompt 同步补充并行策略段。
2026-08-26 13:38:27 +08:00
5f126d4d10
feat(skillmgr): 原生技能管理器插件 + OpenClaw 兼容层职责分离
...
新增 internal/plugins/skillmgr（native skill 全生命周期 owner）：
- skill_list/info/load/unload/enable/disable/create/export/install
- skill_create 两步式：先生成骨架模板，LLM 补全后传 content 覆盖写入
（plugin.ValidateSKILLContent 校验）并自动加载生效
- .skm 分发包（tar.gz）：packSkill/unpackSkill 含 TarSlip 防护
（拒绝绝对路径/../逃逸、强制单根目录、校验包内 SKILL.md）
- skills 目录扫描：纯 SKILL.md/skill.json 条目归本插件；
sidecar(main.js/main.py)/OC plugin(openclaw.plugin.json) 留给兼容层
clawhubadapter 职责分离（OpenClaw 兼容层不再持有 native skill）：
- 删除 p.skills 字段与 default 分支 LoadSKILL 逻辑
- 发现纯 SKILL 条目改为发布 events.EventSkillDetected 移交事件，
由 skillmgr 订阅注册；启动时序 c<s 下全扫兜底，事件用于热新增
- claw_list/plugin_info 不再输出 SKILL 段，统一走 skill_list
方案B prompt 注入：
- agentCore 新增 SkillIndexProvider 接口 + SetSkillIndexProvider
- buildSystemPrompt 注入【可用技能】轻量索引（名称+版本+描述），
LLM 匹配场景时主动 skill_info 拉全文按文档执行
- main.go 在插件加载后将 skillmgr 实例接线到 agent
内核小修：
- extractDescription 跳过 YAML frontmatter 块（此前所有带 frontmatter
的 SKILL.md 描述都被误判为 '---'）
- extractField 剥离 YAML 成对引号（version: "1.0" 不再带尾引号）
- plugin.ValidateSKILLContent 导出供生成侧校验
2026-08-25 20:25:57 +08:00
79b7766ed4
fix: 流式渲染回合生命周期 + LLM 瞬断重试与 SSE body 兜底
...
问题一（webui 不是真流式）：
- sendChat 的 finally 在 POST 结束(15s ackTimer abort)时就复位
chatLoading，但 agent 生成窗口 15~190s，后续 SSE delta 全部走
全量重建路径、停止按钮提前消失、用户误发重复消息。
- GUI app.js 完全没有 content_delta/reasoning_delta 监听器，
只能等聚合帧一次性显示。
修复：三端统一回合生命周期——POST 只是触发，收尾由 SSE 驱动：
- dashboard/GUI 新增 endChatTurn/armTurnWatchdog；拿到同步兜底
响应立即收尾，否则保持回合打开等 agent_output final / reset 帧 /
120s watchdog 兜底
- GUI 补齐 delta 监听器；agent_output 聚合分支 += 改覆盖；
reasoning 聚合帧改覆盖（多轮工具调用时旧逻辑会重复累加）
- agent_output 误杀分支（final 无 source 即 return 丢弃新输出）
改为内容比较去重，多轮连发时新一轮回复不再被吞
- waiter reasoning_delta reset 从清空全部消息改为 sealLastAgent
问题二（三条只成功一条）：
- handleChat 60s ctx 含排队时间，agent 串行处理下第 N 条必超时
（实测第 3 条 62s 超时 504）；放宽到 300s（客户端 abort 时立即取消）
- LLM 单 provider 瞬断无重试：process.go provider 循环内加同源
重试（2 次、退避 2s），401/403 凭证错误与用户中断不重试
- llmsproxy auto 链在非流式请求下可能返回 SSE body（上游恢复后
吐已生成的 chunk 流），非流式解析报 invalid character 'd' 丢掉
整段回复；新增 parseOpenAICompatibleSSEBody 拼接为完整响应
- 顺带修 normalizeStreamToolCalls 分片续传 bug：name 不重发时
argsRaw 被顶层 Arguments(nil) 覆盖丢失 function.arguments
验证：
- 连发 3 条 + 单条共 4 条全部成功（首条 190s 重试扛住瞬断）
- sse_body_test.go 锁定 SSE body 解析契约（content/usage/tool call 分片）
2026-08-25 12:24:11 +08:00
061d2ae320
feat(streaming): token-level delta events + interrupt for CLI/WebUI/GUI
...
Expose the LLM token-level streaming deltas (EventReasoningDelta /
EventContentDelta) to every client channel and add user-initiated
interrupt (cancel generation / send interrupt message) to all three
frontends, preserving the existing interrupt-injection semantics.
SDK/events:
- EventReasoningDelta, EventContentDelta constants exported in the
public/internal SDK event alias tables.
CLI plugin:
- handleChat subscribes to both delta events and forwards
reasoning_delta / content_delta JSON frames (channel-filtered);
aggregated reasoning/tool_call/response frames still fire as before.
- New /stop (alias /interrupt) builtin injects an interrupt via
InjectInterrupt(cliSource, cliChannel) - matches interceptLoop
semantics: cancels an active stream and re-injects the message as
a [中断消息] for a restarted turn; with no active LLM it behaves
as a plain input.
Waiter client (line mode + TUI):
- streamRender accumulates delta chunks and redraws the current line;
a reset frame (stream abandoned, e.g. user interrupt) flushes the
partial buffer so the next turn does not concatenate onto stale
content. Aggregated frames terminate the delta line and render the
final text (old servers without deltas behave exactly as before).
- TUI merges content_delta into the in-flight agent message and seals
it (final flag) on response/tool_call/error so subsequent deltas
never append to a finished message.
WebUI:
- SSE handler subscribes to the two delta events but does NOT record
them into the replay ring - reconnection replays only aggregated
events (the final truth), avoiding duplicate delta accumulation.
- POST /api/v1/chat/interrupt calls InjectInterrupt(webui, webui)
with optional message; fronted by a Stop button shown only while
a generation is in flight.
dashboard.html / GUI app.js:
- Stop button next to Send (hidden until chatLoading); interruptChat
POSTs /chat/interrupt. Delta listeners append incrementally;
agent_output (aggregated) now replaces (not appends) the in-flight
content and marks _final; reset frames finalize the partial message.
process.go:
- chatStreamWithFallback preserves the context.Canceled/
DeadlineExceeded contract: a user interrupt returns the canceled
error (never a partial-content success) so the existing continue
branch restarts the turn with the [中断消息]. A reset
EventContentDelta is published so connected clients drop stale
partial renderings before the new turn begins.
Verified: /stop 'msg' via waiter triggers 'interrupt from cli/cli' in
interceptLoop; unit TestChatStreamCancelPreservesInterrupt confirms the
canceled error propagates instead of being swallowed.
2026-08-25 10:50:37 +08:00
28a6d3f09c
feat(agent): token-level streaming in core process loop
...
Replace the blocking Chat() call in process() with
chatStreamWithFallback: ChatStream first, accumulate chunks, fall back
to non-stream Chat on connect failure or empty-stream failure.
Why: the non-streaming path blocked for the ENTIRE LLM generation (up
to the 180s HTTP timeout). Reasoning models thinking 60-120s plus AUTO
chain failover regularly exceeded it -> context canceled -> full turn
wasted. With streaming the first chunk arrives in ~1-3s and any
flowing token keeps the connection alive; total generation time is no
longer bounded by an overall timeout.
Compatibility (external behavior unchanged):
- process() signature/return values unchanged
- Aggregated events (EventReasoning / EventAgentLLMChain) still fire
once per turn with full text after stream completion - existing
plugin subscribers see identical payloads as before
- New incremental events EventReasoningDelta / EventContentDelta are
additive; old subscribers ignore unknown event types
- Tool execution loop, memory pipeline, stage pipeline untouched
Streaming details:
- Tool call fragments accumulated per OpenAI streaming convention:
id/name arrive on the first fragment, arguments as raw JSON string
shards across fragments; merged and parsed once at stream end
- normalizeStreamToolCalls keeps nameless argument shards (the
non-stream normalizer drops them); ToolCall gains RawArguments to
carry shard text
- Interrupt mid-stream returns partial content instead of discarding
the whole generation
Verified end-to-end against llmsproxy: plain chat streams correctly;
curl confirms tool-call shard wire format ({" + command" + :"date"}
-> {"command":"date"}); unit tests cover shard merging and
content/reasoning accumulation.
2026-08-25 09:30:49 +08:00
d1e502d367
fix(agent): self-input channel carries target output channel flag
...
The selfInputCh previously treated ALL internal messages as memory
consolidation tasks (hardcoded _consolidation_ output channel), which
silently discarded child-agent completion notifications:
- processConsolidation never appends to conversation context, so the
parent agent could not see that its child had finished
- it also discards the LLM response without emitting to any output
channel, so nothing reached the user
- net effect: notifications vanished; parent never called child_result
Restore the intended design: each self-input message now carries a
target output channel. Only consolidation tasks (_consolidation_) go
through the no-memory path (no context write, no emit). Child
notifications carry the parent's original output channel and are
processed as normal input: appended to context, LLM sees them and can
call child_result, and the response is emitted back to the user.
Changes:
- new selfInputMsg{text, channel} type + channelConsolidation const
- selfInputCh: chan string -> chan selfInputMsg
- injectSelf (consolidation) keeps _consolidation_; new
injectSelfChannel for flagged messages
- handleSelfInput routes on msg.channel instead of hardcoding
- executeSpawnChild captures a.currentOutputChannel and passes it to
runChildTask so the notification returns to the originating channel
(falls back to "cli" when unset or consolidation)
- executeChildResultTool: remove dead double-lock/re-check block
Verified end-to-end with tmux PTY against llmsproxy:
spawn_child -> child done -> notification processed via normal path
(log shows 'input from system -> response, tools=[child_result]'),
parent agent retrieved the child result successfully.
2026-08-25 07:52:51 +08:00
8d368913a9
feat: webui 消息重放双重防护(client_msg_id 去重 + agent 内容级去重)
...
回应群聊 08-19 消息轰炸诊断(GUI SSE 重连导致消息重放):
1. webui 层 client_msg_id 单飞去重(与 GUI c29abe9
2026-08-21 10:23:38 +08:00
768c73889e
feat: webui chat 接口支持设备身份(device_id/device_name)
...
- handleChat body 增加 device_id/device_name 可选字段
- 来源编码: 带设备时 webui/{device_id}(agent 可见来源), 无设备保持 webui(兼容)
- injectSourceContext: 检测 device_id 时注入「当前输入来自设备[名](id)」上下文
- 验证: 带 device_id=gui-pc-002 消息 agent 正确回答来源客厅电脑; 无 device_id 兼容
2026-08-18 11:49:57 +08:00
653dd34299
feat: 插件工具按需拉取(get_plugin_tools) + 设备命令类型拆分(shell-cmd/homeagent-cmd)
...
1. 提示词去污染: buildToolCatalog 从全量工具定义改为按插件分组摘要
(插件名 + 工具数 + 能力概览), 完整工具定义由新工具 get_plugin_tools(plugin_name)
动态拉取; 新增 executeGetPluginTools 支持按插件过滤 stageHost/io 工具
2. 设备命令类型: device_ctl_cmdrun 的 command 支持前缀区分
- shell-cmd <cmd> -> 设备端执行原生 shell
- homeagent-<cap> -> 设备端 HomeAgent 内置能力(如 camerasue/screensue)
- homeagent-cmd <cap> -> 同上(兼容写法)
PushCmd 增加 cmd_type 字段下发给设备端分发
3. 测试: TestExecuteGetPluginTools 验证按插件拉取/全部摘要/未知插件
2026-08-18 09:07:21 +08:00
1bc2bf5d8d
fix: WebUI 配置数字科学计数法 + 增强输出通道引导提示词
...
- webui settings PUT: 整数型 float64(如 QQ 号)规范化为 int64 存储,
避免 fmt.Sprint 以科学计数法(2.198972886e+09)存库导致读取解析失败
- 系统提示词【输出规则】重写: 明确消息不会自动路由,
区分同步通道(直接返回文本)与异步通道(必须调用 output_send__{通道}),
引导模型优先回复当前输入通道并带正确 meta(user_id/group_id)
2026-08-15 17:24:14 +08:00
710b1afdf9
C ABI v2: invoke_stage 写回 + ABI 版本对齐核心版本号 (v0.9.0)
...
- C ABI invoke_stage 增加 result 输出参数，外部插件 stage 回调可将修改后的
StageContext(RawMessage/LLMText/FinalText/Response/ToolResults) 写回内核
- ABI 标识版本改为字符串 semver 与核心 Version 对齐(ABIVersion="0.9.0")，
C 层协商用派生整数 CABINum=900(major*100+minor)，不再使用独立数字编码
- version_min 保证 v0.8.x(800) 旧插件向后兼容可加载
- 修复工具循环 zen 兼容补位误伤首轮 system 上下文(仅尾部为 assistant/tool 时补位)
- 更新 README 项目状态说明
2026-08-15 15:38:57 +08:00
147d0baaf9
fix: LLM 工具循环 400、中断消息注入、ConPTY 终端支持
...
- agent: 工具轮请求尾部补 user 占位(zen 网关强制),tool 消息正确配对
- agent: 工具提醒/中断以 system 角色注入并带 [中断消息] 前缀,不进用户履历;系统提示词说明中断消息格式
- agentcli: 基于 ConPTY 的交互式终端(ptywin fork),terminal_create/read/write/resize/close/watch
- webui: server 输出通道适配器(保留 reasoning_content/disable_thinking)
- GUI: 沉浸式标题栏、icon 圆角重制、mascot 等打磨
2026-08-14 00:48:40 +08:00
f960fde785
agent: 更智能的 LLM provider 调度（byModel 精确路由 + AUTO 优先级链）
...
吸收 llmsproxy 的调度思想适配 HomeAgent“一源一模型”结构：
- RoutableProvider{Model,Priority} 次级接口（不破坏既有 Provider 实现）
- ProviderManager.OrderedProviders 改为按 (优先级 desc, 可用, 默认优先) 稳定排序，
AUTO/空模型走该优先级链
- 新增 ProviderManager.ResolveForModel：精确模型名路由到归属源，找不到回落 AUTO 链
- LuaAdaptedProvider 不再无条件覆写 req.Model；显式模型名原样转发
- LLMSource.Priority + core.llm.sources.<name>.priority 配置项
- process.go: 显式模型走 ResolveForModel，AUTO 走 OrderedProviders
- 新增路由单测（优先级排序 + byModel 解析）
验证: go test ./... 27 包 0 失败；Windows 交叉编译通过；部署后服务健康
2026-08-10 11:54:45 +08:00
19410b0e26
蒸馏嵌入接线：Distiller/Agent 注入共享 embedder，修复配置缺失时蒸馏零产出
2026-08-05 09:59:33 +08:00
c7ee45d6e1
refactor: remove core skill direct loading, skills owned by clawhubadapter only
...
- Drop skill.NewManager from homed bootstrap; skills dir no longer core-managed
- Remove GetInjectedPrompt system-prompt injection (skills are not first-class)
- Delete internal/skill package, SkillAPI, webui /api/v1/skills, status skills block
- ConfigRegistry: plugin config tables now created only via RegisterDef; arbitrary
scope Set/Get no longer implicitly creates config_<name> tables (fixes stray
config_today_task table from SKILL directory name being used as a scope)
2026-08-02 11:40:13 +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
