jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-09-21 17:38:10 +00:00
Code Issues Packages Projects Releases Wiki Activity
443 Commits 6 Branches 27 Tags
d17c18665cddfc9de51f7a0cb5ea75f536b74edb
Commit Graph

123 Commits

Author SHA1 Message Date
JianFeeeee
f0be8cbaa5 feat(remotedevice): 设备能力 outputch 化 —— 每设备一个 device/<id> 通道 + 设备指令类工具补授权闸 
用户指出 remotedevice 的能力应当 outputch 化。查证后发现比"应当"更严重：
设备方向**根本没有出站实现**。

## 查到的三个缺口

1. `devicectlDevice` 一直声明 `OutputCapabilities() = CapStructured`（对外宣称可作输出目标），
   但 `Execute` 的 switch 里**没有 "output" 分支** ⇒ `output_send__devicectl` 必然拿到
   `unknown device tool output`，回模型"通过 [devicectl] 通道发送失败"。
2. 全插件没有 `RegisterOutputChannel`，也没有任何 EmitOutput/output_send 路径：
   设备方向只有「工具（请求-响应）」与「设备→agent 注入」，**agent → 设备是断的**
   （唯一的下行通道是个 HTTP 端点 `/api/v1/device/push`，不在 agent 的工具/通道模型里）。
3. 寻址是聚合的：所有设备共用一个名字 `devicectl`，没有 `device/<id>`；且设备 caps 只在
   插件内部软检查（`SupportsTool`），**绕过**了内核的 `AllowedOutputs` 授权闸 ——
   驻留子只要拿到 `device_ctl_cmdrun` 就能指挥**任意**设备。

## 按方向切分（不是一刀切）

**出站/消息类 → 每设备一个输出通道 `device/<id>`**（与入站同名）：
- 上线注册、掉线注销（caps 由设备声明的 caps 映射：文本恒有；有屏→图/文件；
  speaker→音频；可跑命令(cmd/cmdrun/cmdresult)或未声明已知能力→全能力，与
  `deviceSupportsTool` 的旧设备兼容规则一致）。断连不注销会留下死通道骗模型。
- 于是自动获得：内核按 caps 在**发送前**拦（送图给纯文本音箱直接拒）；
  `output_list_channels` 能列出设备；`AllowedOutputs` 可按设备收窄给驻留子。
- 上下线钩子用 `Registry.SetPresenceHandler`（**同步回调**）而不是既有的 `ChangeChan`
  （那是 select+default，缓冲满会丢事件；丢一次就留下死通道或漏注册）。
- `devicectl` 保留为聚合通道，并把它"声明了却不实现"的 output 补实：按
  `meta.device_id`（或 meta 就是设备 id / args.device_id）路由；缺省时返回**可执行**的
  报错（列出在线设备），而不是含糊失败。

**RPC 类保留为工具**（`devicedetect`/`screensee`/`computeruse`/`clipboard*`/
`device_ctl_status|cmdrun|cmdresult`）：它们的返回值（图像/命令输出/状态）必须进模型
上下文，做成通道会丢掉这个语义。

**并给设备指令类工具补上同一道授权闸**（core/toolcall.go）：`device_id` 指向的设备
必须是本 agent 被授权的 `device/<id>`。根 agent 默认完整授权 ⇒ 无行为变化；
驻留子收窄后，"拿到工具就能指挥任意设备"的缺口被堵上（新增 3 条 core 测试钉住）。

**设备端参考实现**（`internal/devicebridge/client/bridge.go` + waiter）：新增 `op=push`
分发与 `OnPush` 回调（文本/结构化；二进制走既有 `cmd_speech_*` → `DataHandler`），
waiter 把它打到终端。

## 设计口径（用户当场纠偏，已写进代码注释与 harness README）

**主动转发只有 webui 与 cli 两个交互界面**（webui 订阅 EventAgentOutput 渲染气泡、
cli 用同步回程写回终端）。其它通道一律要求 agent **显式** `output_send__<通道>`。
我第一版给 remotedevice 加了 `EventAgentOutput` 订阅来自动回投设备——那是凭空造了
第三个转发者，违背"输出是 agent 的主动调用"，已撤回（该测试一并删除）。

## 验收

- 单测：caps 映射词表；设备上线→注册通道（含同名 inputch）/掉线→注销；push 真落到
  WS 设备；聚合通道 `devicectl` 的寻址（无 device_id 报可执行错误、按 meta 投递、
  指定不存在设备报错）；core 授权闸 3 例。
- 全量 `go test ./...` = 37 包 ok / 0 FAIL；`-race`（agent/plugins/plugin/devicebridge/sdk）干净。
- **真二进制端到端**（私有 netns + mock LLM + 真 WS 设备客户端 scripts/kernel-stress/devclient.py）：
  设备上线 → 通道表出现 `device/pydev-1`（caps=[text file image audio structured]，由
  `caps:["cmd"]` 映射）→ agent 经 `output_send__device/pydev-1` 主动发送 → 设备收到
  `{"op":"push","payload":"内核推给你的消息","type":"text"}` → 设备掉线 → 通道从表中消失。
 2026-09-13 12:23:28 +08:00
JianFeeeee
6e6035141a fix(resident/plugin): 二进制级压测暴露的三个真问题（DataDir 漏接线 / inputch 未登记 / create 不开工）+ 通道双向登记贯穿全部内建插件 
在真实内核二进制（私有 netns + mock LLM + CLI unix socket）上做压力测试时，
下面三个问题**只有跑真二进制才暴露** —— 单元测试里都显式传了参数、没走插件加载，
所以全绿也照样漏。

## ① 根 agent 的 DataDir 没接线 ⇒ 驻留子永远建不出来

现象：模型调用 `resident_agents` 成功，但结果是
`创建驻留子需要 data_dir 或显式 temp_path`。
根因：`cmd/homed/main.go` 构造 AgentConfig 时没有 `DataDir`，
而驻留子的 temp 图库需要 `<data>/residents/<id>/graph.db` 这个锚点。
（单测里 `AgentConfig{DataDir: dir}` 显式给了，所以测不出来。）

修：main.go 接线 `DataDir: cfg.Daemon.DataDir`；并在工具层加**兜底 + 告警** ——
data_dir 为空时从主图库路径反推（`<data>/memory/graph.db` ⇒ `<data>`），
失败才报错。静默失败会让线上表现成"工具能调但永远建不出来"。

## ② 插件通道没登记为 inputch ⇒ "划入 inputch"必然失败

现象：`划入 inputch cli: inputch 未注册`。
根因：`cli` 插件只调 `RegisterOutputChannel("cli", ...)`，却用同一个名字
`InjectTextSync("cli", ...)` 注入输入 —— 内核 inputch 登记表里根本没有它。
（实测审计：内建 6 个插件里只有 0 个登记过入站通道；SDK 示例里只有 qq/weather 是对的。）

修两处：
- **全部内建插件显式登记入站通道**：`cli`/`agentcli`/`timer`/`webui`(+`http`, NoMemory)/
  `clawhubadapter`（每个 OC 通道声明处）/`remotedevice`（`device/<id>` 懒登记，幂等）。
- `registry.go` 把隐式兜底改成**留痕的兼容网**：只有当该名字还没登记为 inputch 时
  才兜底登记，并打日志说明"建议显式 RegisterInputChannel"。
  实测：改完内建插件后，启动日志里兜底告警 **0 次**。

## ③ create 之后子不开工 ⇒ rounds 恒为 0

现象：`[agent] r1 started, waiting for IO interrupts` 之后什么都没有，登记表里 rounds=0。
根因：`TaskPrompt` 只进了子的**系统提示词**，从没作为输入投给子。
修：create 即开工 —— 把任务提示词作为**第一条排队输入**投给子（排队而非中断：
创建是"安排工作"，不是"打断它正在做的事"）。

## 测试

- `TestResident_InputchTableAutoAndProactive` / `TestLightKernel_TraditionalContextNoTrimming`
  随行为更新：create 会多跑一轮（任务提示词那轮也会写处理表），
  断言改为"以创建时的表长为基线 + 等待新的一轮"。
- 全量 `go test ./...` = 37 包 ok / 0 FAIL；`-race`（agent/plugin/plugins）干净。

## 真实二进制压力测试结果（修复后）

私有 netns 里跑 mock LLM + 内核，用 CLI socket 驱动多并发连接：
- 密集：16 连接×12 输入 + 4 线程×20 次 L4 中断 → **274 任务 executed=274 / rejected=0 / errors=0**，
  峰值排队 15、峰值待处理中断 76；
- 稀疏（中断每 3s 一次，压在排队任务的流式段上）→ **suspended=27 / resumed=27 / preempted=27**；
- 驻留子全链路：父建子（inputchs=["cli"]）→ 子开工 → 子 `notify_parent` → 父侧收到
  `interrupt from r1/child/r1`（L3，且父被抢占 suspended/resumed=1）；
- 优雅退出：SIGTERM 后驻留子 temp 目录被清除、无残留进程。
 2026-09-13 11:38:03 +08:00
JianFeeeee
aba1770701 fix(lightkernel): 传统上下文落到实处 —— 子不做策略性裁剪（并修掉裁剪估算的字节/rune 单位混用） 
用户指出实现不自洽："子 agent 是传统上下文，没有裁剪"。查证属实：子仍走
`formatMergedTimeline` 的预算裁剪、也可能走 `pruneOnInput`（既裁剪又向 doc 记忆归档）。
即"动态上下文"（父专属能力）漏进了轻量内核。

## 三处闸门（按 isLightKernel() 判）

1. **拼装预算**：新增 `contextTokenBudget(b)` —— 父用动态上下文的 `ContextTokens`，
   子用**整个窗口** `MaxContext`。两个调用点都改（`stepPrepare`、`rebaseFramePrefix`；
   漏掉后者时 prepare 之后的重建仍会裁，实测就是这么被抓出来的）。
2. **pruneOnInput**：轻量内核前置返回 —— 不做按相关度裁剪、不向 doc 记忆归档。
3. doc 记忆 / 整理流水线：早已由 `a.memory == nil` 关闭（N2c）。

## "不裁"的准确含义

不做**策略性**裁剪（不按相关度挑、不归档），只受"模型能收多少"这个硬上限约束；
且在撞到硬上限之前，contextfull（90% 窗口）已按 L4 上报父 agent ⇒
**丢事件的决定权在父**（压缩/回收/销毁），不在内核。文档 §16.0.0 记录三处闸门表。

## 顺带修掉的既有 bug（单位混用）

`formatMergedTimeline` 逐事件估算原来是 `len(e.Source)+len(e.Input)+40` 再 ×2 ——
`len()` 是**字节**，而 `EstimateTokens` 是 rune×2 ⇒ 中文事件被高估 3 倍：
实测 2384 字的中文事件被估成 14398 token > 8192，于是窗口还有余量也提前 break、
把更早的事件整段丢掉。改为统一走 `EstimateTokens`（对父同样生效：中文长会话不再被过早裁剪）。

## 测试

- 新增 `TestLightKernel_TraditionalContextNoTrimming`：用**记录模型实收消息**的 provider
  断言"更早的事件仍在"（为什么不看 TaskFrame：`prepareInputTask` 只做前半段，
  消息在 `runTaskSteps`/`stepPrepare` 才拼出来 —— 我第一版断言就打在了空帧上）；
  填充量取"超过动态份额、但仍在窗口内"，从而能区分父/子两种行为。
- 新增 `TestFullKernel_StillUsesDynamicContext` 作对照（父仍用动态份额）。

全量 go test ./... 37 包 ok / 0 FAIL；-race 干净。
 2026-09-13 10:36:04 +08:00
JianFeeeee
cba33d2a6f test(resident): 压力规模可用环境变量放大（RESIDENT_STRESS_N / RESIDENT_STRESS_ROUNDS） 
默认仍是 8 子 × 12 轮（CI 友好）；要跑加重压力就放大：
  RESIDENT_STRESS_N=64 RESIDENT_STRESS_ROUNDS=40 go test -race -count=2 ./internal/agent/core/ -run TestResident_E2EAndStress

实测已跑：
- 24 子 × 25 轮（-race）：通过
- 64 子 × 40 轮（-race -count=2，即 5120 轮次）：通过
 2026-09-13 10:25:49 +08:00
JianFeeeee
2ebbdadcd6 feat(resident): N3–N7 驻留式子 agent 全量落地（生命周期/双向投递/处理表/contextfull/e2e+压力） 
设计：docs/zh/resident-subagent-design.md §6/§7/§8/§9/§10。

## N3 生命周期（resident.go）

- `SpawnResident`：主库**受限句柄** + 自己的 temp 实例（`LightMemory`）⇒ 子的轻量内核；
  划入 inputch（登记归属）、授权输出通道、注入任务提示词；为父登记 `child/<id>` 入站 inputch；
  建独立 `IOManager`（共享通道登记表）；启动子。
- `DestroyResident`：停子内核、归还划入的 inputch（回到未分配）、丢弃 temp 目录、出登记表。
- `Stop()` → `StopResidents()`：**父退出必须销毁全部子、不留孤儿**（设计 §10 硬约束）。
- `Residents()` 登记表快照；`ResidentTable(id)` 父 pull 子的处理表（不打断）。

## N4 跨 agent 投递

- 子→父：`notify_parent` → 投进父的 `child/<id>` inputch，优先级 **L3**。
- 父→子：`SendToResident` → 投进子的 inputch，优先级 **L4**；
  `isKernelLevelSource` 泛化为"该 agent 的上级"（`AgentConfig.KernelSource`）⇒
  只有父能在子的阶梯上产生 L4（子内部一律 ≤L3）。
- 子的 contextfull → 父侧 `raiseKernelInterrupt`（内核级事件，带子标识，父侧 L4）。

## N5 inputch 处理表

- 子持有；`inputch_note` 主动写**优先**，轮末 `autoRecordInputch` 兜底 ⇒ 每轮必有记录。
- 压缩时清表（表记的是被压掉那段窗口的逐轮处理）。

## N6 contextfull（判据修正）

❗初版判据是"拼好的 `f.Msgs` 估算 > 90% 窗口"，**结构上永不成立**：
`buildMessages` 拿到的 `budget.ContextTokens` 由 `targetUsage = 0.8 × 窗口` 推出，
时间线**在拼进消息之前就被预算裁过**，`f.Msgs` 封顶在 ~80% 窗口。
（初版测试用一个比系统提示词还小的窗口才勉强越线 —— 那等于什么都没测。）
现判据 = **未裁剪的积累上下文**（`a.context.Recent(0)`）超过窗口 90%：
它超过就说明下一轮必须丢事件，这正是"上下文满"。

三处置：`CompressResident`（保留语义：`TrimKeepRecent` 保留最近 N 条 + 清表）/
`ReclaimResident`（取消语义：`ExportTriples` 读 temp → 父选出要保留的 → `Commit` 进 main → 取消该子）/
`DestroyResident`（立刻销毁并移除）。

## 工具面

`resident_agents`（父，单工具多动作：list/create/send/inspect/compress/reclaim/destroy）、
`notify_parent` + `inputch_note`（子）。声明条件式：父才有前者，子才有后两者。

## 验收

`resident_test.go` 五项：生命周期与不留孤儿、双向投递（含"子的主动消息不得以 L4 出现"）、
处理表（自动写 vs 主动写优先）、contextfull + 三处置、
**压力 8 子 × 12 轮（父→子 L4 与普通输入各半）+ 双向汇报 + 父退出清理**。
全仓 go test ./... 37 包 ok / 0 FAIL；`-race`（agent/memory/plugin）干净；
压力 `-race -count=3` 通过。
 2026-09-13 10:20:06 +08:00
JianFeeeee
48cfa8fb6c feat(lightkernel): N2c —— 轻量内核 profile（窄接口 GraphMemory + nil 即禁用整理面） 
按用户指出的关键点（a.memory 多数使用点属"主 agent 整理记忆"与"记忆整理流水线"，
子不该有那些路径）实现，方案见设计 §16.0。

## 窄接口：只有 Recall + Commit

新增 `GraphMemory` 接口（memoryface.go）—— 按调用方实测分类后，真正"根与子都要"的只有这两个：
- `Recall`：上下文检索 / memory_recall
- `Commit`：自动写入路径的图部分 / memory_commit

新增 `Agent.graph`（共同面）与 `Agent.graphMem()` 访问器：
- `graph` 显式为 nil 时**回落**到 `memory` ⇒ 既有"只用 Agent 字面量设 memory"的测试无需改动
  （原本会出现"必须同时设两个字段"的脚坑，实测踩到后去掉了）
- 轻量内核：`graph = *memory.LightMemory`，`memory = nil`

## nil 即禁用：整理面自动消失，不需要受限包装

子的 `a.memory == nil` ⇒ 既有的 22 处 `if a.memory != nil` 关卡自动禁掉全部整理面：
- 记忆整理流水线（distill.go 的 archive/review/merge 循环）
- 记忆块 + 媒体桥（graphmedia.go / medialoop.go）
- 记忆整理工具（memory_merge / memory_delete_entity / memory_block_merge /
  memory_purge / memory_edit / memory_introspect）—— 它们本就在 `if a.memory != nil` 块内

唯一拆开的一处是自动写入 `commitTriplesWithMedia`：
图部分走 `graphMem().Commit`（父落 main、子落 temp），块/媒体部分仍由 `a.memory != nil` 守卫。
`executeMemoryTool` 的读路径改走 `graphMem().Recall`；整理类 case 加 `requireFull()` 闸门，
被直调时明确报"本 agent 是轻量内核：记忆整理不可用"，不静默降级。

## 验收（3 项新测试）

- `TestLightProfile_MemoryFaceWiring`：整理面为 nil、写入只落 temp（主库无子痕迹）、
  读是并集（主库实体 + temp 实体都看得到）
- `TestLightProfile_OrganizeToolsAbsentAndRefused`：整理类工具**不进工具表**；
  即便被直调也明确报"轻量内核不支持"
- `TestFullProfile_KeepsOrganizeFace`：对照，根 agent 仍保留整理面与整理工具

全仓 go test ./... 37 包 ok / 0 FAIL；-race（agent/memory）干净；gofmt 干净。
 2026-09-13 10:02:02 +08:00
JianFeeeee
f7c3a4e81d feat(channel): N1b —— 输出通道授权集合（三处过滤一致）+ 输出通道→目标 agent 的 inputch 解析 
设计：docs/zh/resident-subagent-design.md §4.5（里程碑 N1b）。

## 输出通道授权集合（默认完整授权，父可收窄）

`AgentConfig.AllowedOutputs`（nil/空 = 完整授权）。三处过滤点必须一致，
否则会出现「列表里看不到、按名字还能调」的裂缝：

1. **工具表**：不为未授权的通道生成 output_send__X（模型看不到就不会调）
2. **列表工具**：output_list_channels 只列授权的
3. **调用点**：凭名字直调未授权的输出门必须被拒（纵深防御）

## 输出通道 → 目标 agent 的 inputch 解析

`ChannelRegistry.BindOutputTarget / ResolveOutputTarget`：
把输出通道解析成「目标 agent + 目标 inputch」，这是"输出可寻址到具体 agent"
（子→父、父→指定子）的**数据面**；真正的跨 agent 投递在里程碑 N4。
未登记的输出通道 ok=false —— 表示由传输层 device 自行处理（qq/webui 这类）。
已登记目标的输出通道，在 output_list_channels 里会标出「目标: <agent> / inputch <名字>」。

## 验收

`internal/agent/core/output_grant_test.go`（3 项）：
- 默认完整授权：全部输出门生成 + 列表含全部
- 白名单收窄：三个过滤点同时生效（工具表 / 列表 / 直调被拒）
- 目标解析：绑定/解析、未登记由传输层处理、列表标出目标、空名报错

全仓 go test ./... 37 包 ok / 0 FAIL。
 2026-09-13 09:13:19 +08:00
JianFeeeee
3c961b7bd7 feat(channel): N1a —— inputch 一等化（归属插件/归属 agent/容量/共享登记表）+ 单工具多视图总览 
设计：docs/zh/resident-subagent-design.md §4.6（里程碑 N1a）。

## 用户要求

「父 agent 可以看到所有已注册的 inputch 以及 inputch 的划分情况，用**单工具多视图**方式构筑」

## 登记层（internal/agent/io/inputch.go）

inputch 是**最基本的输入路由单位**（由插件注册，一个插件可注册多个），
所以登记表以 inputch 为键，每条记录：

    名字 / 归属插件 / 归属 agent(被划给谁) / 容量 / 默认回程 outputch / 记忆策略(ChannelDef)

- 新增 `ChannelRegistry`，设计成**可共享对象**（`*ChannelRegistry`）：
  根 agent 与驻留子共用同一份，"划入/授权"才有意义；`SetChannelRegistry` 注入。
- **插件重载不得抹掉划分**：重复登记只更新「归属插件 + 策略」，
  保留已有 Owner/Capacity/Output（否则一次 reload 就把父做的划分清空）。
- `Assign` 语义按设计 R6 默认：**读写授权，不转移所有权**（Plugin 与 Owner 分别记录）。
- 原 `inputChannels map[string]ChannelDef` 被登记表取代；`GetInputChannelDef` 保持兼容。
- `plugin.Registry` 注册时带上**归属插件名**（此前完全无归属信息）。

## 总览工具（internal/agent/core/inputch.go）

单工具 **`input_channels`** + `view` 参数（不是一堆小工具）：

    all（默认）= 全部已注册（带归属插件）
    mine       = 划给本 agent 的
    unassigned = 尚未划出的
    by_agent   = 划分情况总览（按归属分组）
    detail     = 单个 inputch 全字段（需 name）

未知 view **报错并列出可用值**（拼错不得被静默当成默认视图）；登记表为空时明确说明。

## 验收

- `internal/agent/io/inputch_test.go`：归属记录、重载保划分、Assign/视图数据面、
  **跨 manager 共享登记表**、策略查询向后兼容 —— 5 项
- `internal/agent/core/inputch_test.go`：单工具多视图逐视图断言（含未知 view 与空表）—— 2 项
- 全仓 `go test ./...` 37 包 ok / 0 FAIL；`-race ./internal/agent/... ./internal/plugin/...` 干净
 2026-09-13 09:06:50 +08:00
JianFeeeee
f2ec46480e refactor(core)!: N0 无状态化 —— 删除 Agent.currentOutputChannel，通道只跟输入事件/帧走 
驻留式子 agent 设计（docs/zh/resident-subagent-design.md）的里程碑 N0。

## 问题

`a.currentOutputChannel` 是 **agent 级可变字段**，只在 prepare 段写入，而被打断任务
恢复时**不重新 prepare**（resumeTask 只 rebase 前缀）。于是中断任务 prepare 时把它
覆盖成自己的通道，被恢复的任务再把回复发到**中断任务的通道**上——两个任务串台。

后果不只是标签错：工具提示词里那句"当前输入来源通道是 X，对应输出门工具是
output_send__X"会诱导模型**把回复主动发到错误的通道**。

## 两处一起改（用户指出的两件事）

1. **内核不应持有"当前通道"**：通道是随输入事件带进来的，路由发生在**进内核之前**，
   输出是 agent 的**主动调用**。删除该字段，改为一律从输入事件推导
   （`outputChannelOf(evt)`）或读本任务的帧（`f.OutputChannel`）。
2. **提示词不应预设 outputch**：删掉"当前输入来源通道是 X → 用 output_send__X"那两行，
   改为"不要假设当前通道是固定值；先看消息本身与上下文的来源信息，不确定时先调
   output_list_channels"。

## 改动面（把通道一路显式传下去，而不是读共享状态）

- `agent.go`：删字段
- `task.go`：新增 `outputChannelOf` / `isCriticalChannel`；帧记录通道；
  安全点与 setCritical 用帧/事件推导；步骤内事件标签改用 `f.OutputChannel`；
  `executeToolCall(f.CurTool, f.OutputChannel)`；`callLLMWithFallback(..., f.OutputChannel)`
- `process.go`：`chatStreamWithFallback` / `accumulateStream` 增加 channel 参数
  （增量事件的 channel 标签由此而来）
- `stage.go`：`runStage` 从 `ctx.Extra["output_channel"]` 读（发起方写入）
- `eventloop.go`：`emitResponse` 用 `outputChannelOf(evt)`；stageCtx 带上通道
- `spawn.go` / `toolcall.go`：`executeSpawnChild` 的 parentChannel 由调用方（帧）传入
  （子任务完成通知要回到**发起这次 spawn 的那个任务**的通道）
- `distill.go`：删掉 consolidation 路径里的赋值
- `tooldefs.go`：删掉提示词里的通道预设

## 验收

- `scheduler_channel_routing_test.go`（N0 守卫）：中断任务跑过之后，被恢复任务的
  输出通道仍是它自己的（改前实测为 cli，期望 qq）
- `TestCriticalSection_ConsolidationMarked`：补上推导链
  「输入事件 → 通道 → isCriticalChannel → scheduler.critical」的集成断言
- 全仓 `go test ./...` 37 包 ok / 0 FAIL；`-race ./internal/agent/...` 干净
- 残留 `currentOutputChannel` 引用为 0（只剩描述历史的注释）
 2026-09-13 08:59:15 +08:00
JianFeeeee
158395bfdf test(scheduler): 优先级压力测试（100 排队 + 100 中断各级混合、嵌套到 4 帧上限） 
按需造一个固定内容的 fakeprovider，做两件事：

E4：混合载荷（用户指定的形状）
  100 条排队输入 + 100 条中断（L1/L2/L3/L4 各 25）混合打入。每条中断都等到
  “该被它打断的受害者正在跑”时才注入——调度器是单线程的，闭着眼睛猛灌只会
  让绝大多数中断退化成排队，压力就压不到抢占/挂起路径上。
  判据：200 个任务全部到达终态、Rejected=0、各级登记数=25、**各级抢占数都>0**、
  排空后 Suspended==Resumed、每次“取消流式段”都换来一次挂起。

E5：嵌套到结构上限
  排队任务运行中依次注入 L1→L2→L3→L4（每级都等上一级在跑）。判据：栈深峰值
  恰好 4（= 结构上限，此时 canSuspend()=false），恢复顺序严格 LIFO
  [L3,L2,L1,排队]，Suspended==Resumed==4。

顺带修掉两处：
- **Resumed 双计**：nextRef 弹栈与 resumeTask 各计一次，使“排空后
  Suspended==Resumed”这条不变量失真。现在只在 resumeTask 计（nextRef 只负责选出）。
- 新增分级可观测：SchedulerStats.InterruptsByLevel[1..4] / PreemptsByLevel[1..4]。
  只看总数会掩盖“总数一样但级别分布完全不同”，按级别验收才是这套调度器的判据。
  注意 PreemptsByLevel 是“判定可抢占并进入 immediate”的次数，与 Suspended 不等价：
  受害者可能在让位生效前就自行结束，此时抢占者只是“下一个运行”，没有挂起发生。

教训：provider 必须感知 ctx 取消。第一版没做，结果 LLM完成==任务数、挂起≈0——
抢占全落在“步骤之间”，流式段（真正需要保存/恢复现场的地方）一次都没压到。

验收：go test ./... 37 包 ok 0 FAIL；-race 全绿；压力连跑 3 次稳定；
新内核 go build 通过并真实启动冒烟 OK。
 2026-09-13 07:31:32 +08:00
JianFeeeee
f3232000f4 feat(scheduler): L4 也归内核级插件 —— WebUI 终止按钮可用“立即打断” 
上一提交把 L4 写成“内核独占（panic / selfip）”，漏了内核级插件这类来源。
用户澄清：**内核级插件应当能声明 L4，用于实现中断能力**，例如 WebUI 的终止按钮。

判据（两道闸，纵深防御）：
  1. proc 桥（外部进程唯一入口）一律把 L4 夹到 L3。在这里夹而不是只按 source 判，
     是因为 source 是插件自报字段、可以冒名；本函数所在位置能确知“来自外部进程”。
  2. core：isKernelLevelSource(source) 查 pluginReg.IsBuiltinPlugin，只有编译期内置
     插件（init() 自注册的工厂）才承认 L4。
source 约定 `插件名` 或 `插件名/实例`（webui/<deviceID>），判据取第一段——
否则带设备身份的 WebUI 来源会被误判成外部插件而拿不到 L4。

改动：
- core: interruptLevel(evt, privileged bool)；新增 isKernelLevelSource；
  requestPreempt 不再夹取（级别已由 interruptLevel 解析，否则内核级插件的 L4 被削掉）。
- eventloop: 传入 a.isKernelLevelSource(evt.Source)。
- proc 桥: 新增 clampExternalPriority，pubSdkInjectOpts 一律夹取。
- internal/sdk: 再导出 PriorityL1..L4（内置插件用 sdk.PriorityL4）。
- webui handleChatInterrupt（终止按钮）声明 PriorityL4。
- timer 声明 PriorityL3：定时器是“时钟那种实时工作”，比 QQ 那类可无限等待的
  异步消息高（L1）——这是对用户“它不是时钟那种实时工作”的直接推论，可改。
- 测试: L4 特权矩阵（非特权夹取 / 特权承认）、source 判据（内置、内置/实例、
  外部、空、前缀不误匹配）、内核级插件 L4 一路到达调度器、proc 夹取两条。
- 设计稿 §2/§3.2/§11.1/§14/§15 按“L4 = 内核 + 内核级插件”更正。

验收：go build/vet 干净；go test ./... 37 包 ok 0 FAIL；-race 全绿（含 webui/timer）。
 2026-09-13 07:18:03 +08:00
JianFeeeee
cb32032f76 feat(scheduler)!: 中断/排队两类别模型 + 插件声明 L1-L3、L4 内核独占 
用户澄清推翻了早期设计的三处前提，本提交按新模型重做调度核心（行为有意变化）：

1) 类别由注入 API 决定，与通道名无关
   - InjectInterrupt*                      -> TaskInterrupt（带级别，可被严格更高级中断打断）
   - InjectText*/InjectInputSync*/内核自循环 -> TaskQueued（无级别，可被任何中断打断）
   - 删除按通道名推断的 taskLevel()：qq 走 InjectInterruptTextOpts，本就是中断

2) 级别只属于中断
   - 插件在 InjectOptions.Priority 声明 L1-L3（空/非法降级 L1，声明 L4 夹到 L3）
   - L4 内核独占：新增 raiseKernelInterrupt（panic / selfip）；requestKernelPreempt 不夹取
   - panic 现在产生一条带 kernel 标记的 L4 中断；L4 自身 panic 不再产生新 L4（防自我放大）

3) 选择结构：四容器固定次序，删除统一比较器
   - immediate（抢占者立即运行）-> 中断队列 L4..L1 -> 栈顶(与队头比级别) -> 排队 FIFO
   - 删除 pickTaskIndex/taskBefore 与“同级 pending 优先”补丁（根因是抢占者进了队列）
   - 中断栈上界改为结构推论 = 4（= 中断级数）；删除“超限转 pendingInterrupts”降级

公开 SDK（feature 分支有意新增，纯追加）：InjectOptions.Priority + PriorityL1/2/3；
内核 io / proc 桥 / 插件模板同步透传。

设计稿 §2/§3/§4.1/§6.3/§9/§11/§12/§13/§15 按新模型重写。

验收：go build/vet 干净；go test ./... 37 包 ok 0 FAIL；-race 全绿；
e2e（抢占-挂起-恢复）+ 压力（200 排队 + 50 中断，L1/L2/L3 轮转）通过。
 2026-09-13 07:00:51 +08:00
JianFeeeee
86a702b3b0 fix(scheduler)!: 中断栈语义（嵌套抢占 LIFO），并修掉抢占空转 
用户指正：存在**中断被中断**的场景，所以被打断的现场要进**中断栈**。
我此前把 suspendPool 明确写成“不是栈、按优先级取”，是错的。

改动：
- suspendPool 改名 suspendStack，恢复纪律改为**严格 LIFO（只比栈顶）**；
  栈内不做优先级重排——嵌套抢占天然使栈自底向上基础级递增，
  且“后被打断的先恢复”才是栈语义。取出即弹栈。
- 修掉一个由此暴露的真 bug（抢占空转）：一次抢占生效后，被挂起的原任务
  会因饥饿防护提升有效级，与抢占者同级；此时若按“先到先服务”，原任务
  （入队更早）会被立刻选回，抢占者永远排不到 —— 抢占等于没发生。
  现在**同级时 pendingInterrupts 优先于其它两类**，保证抢占必然生效。
- 状态 DTO：SuspendPool/suspend_pool → SuspendStack/suspend_stack
- 设计稿：§2 用语更正（它**就是**中断栈）、§4.1 选择函数（候选只含栈顶 +
  pending 同级优先，并说明为何必需）、§6.2/§6.3/§9/§11 用例同步

测试新增 scheduler_stack_test.go 3 项：
- 嵌套 L1→L2→L3，恢复严格 LIFO（B 先于 A）
- 只比栈顶：人为构造“栈底 L3、栈顶 L2”，必须取栈顶（区分两种实现）
- 嵌套下的深度上限

验收：agent 全量 + -race；全仓 build/vet 通过
 2026-09-13 06:30:23 +08:00
JianFeeeee
d4764e3682 fix(scheduler)!: D1 更正为「中断从上一个任务之前的完整状态开始」，并实现现场合回 
用户明确语义（我此前对 D1 的解析就是错的——当时回答里的“A”指的是 git 选项，
D1 实际要的是方案 B）：

  中断打断时，上个任务到达以来的所有上下文现场被保护（含 toolcall），
  然后中断在「上个任务前的那个完整状态」上开始运行；
  中断结束后再把被挂起的任务与其上下文现场加载回中断任务之上，并继续运行。

实现：
- 删除 SeedMsgs 与 D1=A 的“只读前缀”机制：中断任务不再继承被打断任务的任何内容，
  它就是普通新任务，正常走完整 prepare（system prompt + timeline + 自己的输入）
- TaskFrame 新增 PrefixLen（基础前缀长度）与 InputBlocks；
  stepPrepare 在 buildMessages 之后记录 PrefixLen
- 新增 rebaseFramePrefix：恢复时重建基础前缀（中断已提交进 a.context，
  重建的 timeline 含中断效果＝“加载回中断之上”），再把本任务自己的尾部
  （Stage 上下文 + 工具轮产物 + 占位）接回；并补回 IsInterrupt 标记与多模态块
- resumeTask 在 runTaskSteps 之前调用 rebaseFramePrefix
- 设计稿 §5.3 改写为「已定：D1=B」并写明实现对应；§6.2 补“重建前缀→接回尾部”；
  §12 的 D1 行更新

测试：
- TestPreempt_HigherPreemptsAndResumes 改为断言「中断不继承、恢复后看得见中断内容」
- 新增 TestPreempt_ResumeRebaseRestoresTailDecorations（前缀重建后尾部装饰补回）
- 原 TestPreempt_SeedPathDoesNotLeakInterruptFlag 随之删除（机制已不存在）

验收：agent 全量 + -race；全仓 build/vet 通过
 2026-09-13 06:24:20 +08:00
JianFeeeee
8372f5bd8f fix(scheduler)!: 撤掉“优先级=可配置策略表”的错误设计，回归内核内部属性 
用户指正：**优先级是内核内部属性**，不是配置项，更不该由插件声明。
我此前把它建模成“策略表 + 字符串解析”，甚至准备接配置中心
（core.agent.priority.<channel>）——方向性错误，故整体撤销。

撤销：
- 删除 ParseLevel（字符串解析只服务于“外部可配”这个错误前提）
- 删除 AgentConfig.PriorityLookup / Agent.priorityLookup 及 taskLevel 中的查表分支；
  taskLevel 回归为纯内核内部规则（cli/webui/http→L3，system/_consolidation_→L1，
  其余 L1），注释明确“不对外暴露、不做运维可调项”
- 设计稿 §3.2 改写为“内核内部属性，不做成配置项”，并删除 §15 里
  “ChannelDef.Priority / InjectOptions.Priority 进公开 SDK”这一方向（同属外化）
- 未触碰配置中心（registry.go/main.go 的优先级配置一行未加）

同时落地 D6（与本撤销无关、此前遗漏的承诺）：
- AgentConfig.MaxToolTurns + runTaskSteps 在发起新一轮 LLM 前按 f.Turn 收尾；
  0 = 不限；cmd/homed/main.go 从既有 core.agent.max_tool_turns 取值
- 新增 task_test.go 2 项：上限 3 时恰好跑 3 批工具/3 次 LLM 并收尾；
  0 = 不限（跑完脚本）

验收：agent 全量 + -race；全仓 build/vet 通过
 2026-09-13 06:17:49 +08:00
JianFeeeee
98d67559d1 fix(scheduler): 补齐 M3 与设计稿的两处语义偏离（发现即修） 
两处都不是风格差异，而是真的偏离设计语义（其一为回归），
已按“先写判据确认失败、再修”的方式处理，判据保留为回归测试。

1. 空闲时到达的中断永远不会被处理（设计 §5.1 ③ 未落地）
   调度器空闲时只阻塞在 select{InputChan, selfInputCh, ctx.Done}，
   而 pendingInterrupts 不是 channel——interceptLoop 把中断入队后
   没有任何东西唤醒调度器，中断要等“下一条输入”才被看到。
   修复：调度器加 wake channel，enqueueInterrupt 非阻塞 signalWake，
   空闲分支增加 wake 分支。

2. 临界区内只“不让位”却仍被“取消”（设计 §4.3/§5.2）
   requestPreempt 不判临界区，interceptLoop 照常 cancelLLM，
   于是正在流式的记忆整理被中断，stepLLM 以 error 提前结束——
   整理任务被砍掉一半，而设计要求的是“请求排队等它结束”。
   修复：scheduler 增加原子 critical 标志（帧仍只由调度器读写），
   runInputTask 在 prepare 后设置、结束（含挂起）时清除；
   requestPreempt 在临界区内不 arm、不取消，中断只入队。

- 新增 scheduler_regression_test.go 2 项（先失败后通过）
- 验收：agent 全量 + -race；全仓 vet 通过
 2026-09-13 06:10:44 +08:00
JianFeeeee
f11de37bf2 feat(scheduler): M7 可观测性 + 压力测试 + 端到端测试 
设计依据 docs/zh/input-scheduler-design.md §11.5（O1/O2）、§11.6（E1/E2）。

- 可观测性：KernelStatus 新增 Scheduler 段（running/三集合深度/计数/
  深度上限），由 GetKernelStatus 从 DumpScheduler 原子快照填充；
  新增 events.EventScheduler，挂起/恢复各发一条（action/task/level）
- TaskKind.String() 便于日志与状态输出
- 新增 scheduler_e2e_test.go 3 项：
  · 压力：200 排队输入 + 50 中断全部经真实 loop 执行，结束时三集合排空、
    LLM 调用数精确等于输入数、无 Rejected
  · 可观测性：挂起/恢复事件齐备，状态快照计数一致
  · 端到端：完整启动 schedulerLoop+interceptLoop，经真实 channel 投递
    L1 任务与 L4 中断，验证「LLM 流式中断 → 挂起 → 中断先完成 → 原任务恢复」
    整条链路（LLM 调用数 = 丢弃1+中断1+恢复1+常规1）
- 验收：agent 全量 + -race；全仓 build/vet 通过
 2026-09-13 00:45:28 +08:00
JianFeeeee
4e4e0ad656 feat(scheduler): M6 任务级回执 + 断链点统一为终态事件 
设计依据 docs/zh/input-scheduler-design.md §7（I5）、§11.3（X1/X2/X4）。

- 新增 emitSkippedReply：跳过路径（去重命中、空输入）给同步调用方一个
  skipped 终态，但**不发 agent_output 事件**（避免 WebUI 聊天记录凭空多出
  空消息）。修复前 cli/clawhubadapter 这类无超时的同步注入在去重命中时永久挂起
- 回执按任务归属：中断任务的回执只写自己的 ResponseCh，绝不误投给被挂起的等待者；
  被挂起任务恢复并结束后才拿到自己的回执
- 新增 task_terminal_test.go 3 项：X1 回执不误投、X2 空输入有 skipped 终态、
  X4 无超时同步调用方 1s 内拿到终态（回归判据）
- 更新 M3a 去重用例：由「不得回执」改为「必须有 skipped 终态」
- 验收：agent 全量 + -race；全仓 build/vet 通过
 2026-09-13 00:39:56 +08:00
JianFeeeee
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
JianFeeeee
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
JianFeeeee
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
JianFeeeee
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
JianFeeeee
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
JianFeeeee
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
JianFeeeee
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
JianFeeeee
7318a10828 feat(persona): 人格设定配置项化 + 默认模板契约测试 + 腐坏告警 
起因（v1.2.0 压测）：线上实例内核日志/接口都报 1.2.0，agent 被问版本时却按人格卡
自述 v0.9.0 + C ABI v2（该机制 v1.0.0 已删除）。根因是人格只有「文件」一个来源且无人
维护——写死的版本号必然随发版腐坏。

改动：
1. 新增配置项 core.agent.personal_prompt（多行文本），默认值为内置模板
   config.DefaultPersonaPrompt，随其它默认值同批播种（老安装不注入，语义不变）
2. 默认模板**不含任何版本号字面量**，并显式要求「被问到版本/构建信息时以运行时快照
   （healthcheck_kernel）为准」——从根上消掉这类腐坏
3. 人格来源优先级：personal/personal.md（存在且非空）> 配置项 > 无
   启动日志明确打印来源；文件含腐坏内容（版本号字面量 / 已删除机制的说法）时告警并
   建议迁移到配置项
4. internal/agent.PersonaStaleHints：腐坏检测（版本号正则 + 已删除机制词表）

契约测试（防复发）：
- TestDefaultPersonaPromptHasNoVersionLiterals：默认模板不得含 v?\d+\.\d+\.\d+，
  且必须含「运行时快照」要求
- TestPersonaPromptRegisteredWithDefault：注册存在、默认值一致、播种真的写入
- TestPersonaStaleHints：线上人格卡原文必须被识别（v0.9.0 / C ABI v2），干净文本不误报

验证：go build ./cmd/homed ok；go vet 三个包 ok；go test ./internal/config ./internal/agent ok；
端到端两场景（无文件→来源=配置项 1307 字节；有旧文件→来源=文件 + 告警列出 v0.9.0 与 C ABI v2）。
 2026-09-12 12:42:43 +08:00
JianFeeeee
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
JianFeeeee
f1091676f8 style: gofmt 两处对齐（graphmedia_test.go 注释、tfidf.go 结构体字段） 
这两处是本次特性分支带入的格式回归（origin/main 上不脏）。
纯空白/对齐调整，无语义变化；不整体重排文件。
 2026-09-12 08:23:30 +08:00
JianFeeeee
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
JianFeeeee
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
JianFeeeee
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
JianFeeeee
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
JianFeeeee
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
JianFeeeee
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
JianFeeeee
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
JianFeeeee
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
JianFeeeee
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
JianFeeeee
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
JianFeeeee
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
JianFeeeee
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
JianFeeeee
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
JianFeeeee
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
JianFeeeee
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
JianFeeeee
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
JianFeeeee
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
JianFeeeee
f855893d1c feat(memory): 媒体接入 L0/L2——digest 挂到对话事件，归档时引用随之转移 
在 a822674 的 CAS 层之上把媒体真正接进记忆链路。此前 CAS 只是个孤立的
存储包，没有任何写入方。

## 媒体进入对话有两条路，两条都只把文字留给记忆

  1. 用户直接发图 → processMediaInput → mediaToBlocks
     ContextEvent.Input 只存 alt 文本（"[从 qq 收到了 image]"），
     base64 随 message 数组发给模型后就丢了。
  2. 插件注入 → SetToolBlocks → process.go 的 mediaMsg
     ToolResultItem.Output 只存那句 "[已将图片注入后续对话] /tmp/x.png"。

于是下一轮起，模型能看到的只剩一句路径或一句 alt。那个文件被删、被覆盖，
或者本来就是 /tmp 下的临时产物，连线索都断了。

现在两条路在同一处收口（captureBlockMedia）：从 ContentBlock 的 data URL
取出字节存进 CAS，digest 挂到当轮 ContextEvent。

## 改动

internal/agent/core/mediaref.go（新）
  - captureBlockMedia：ContentBlock → CAS。只处理 data URL——http(s) URL
    拿不到字节就无法内容寻址，而「下载它再存」会把一次对话变成一次网络
    请求（超时、鉴权、SSRF 全来了），不在本层解决。
  - stage/drainMediaDigests：媒体在 process() 期间被捕获，而承载它的
    ContextEvent 要等 process() 返回后才 Append——此刻还没有 owner_id，
    故先缓存。与既有 pendingMedia 同一手法，同受 a.mu 保护。
  - bindEventMedia：双向落地。evt.Media 让事件记得引了什么（随
    context.json 持久化），media_refs 让 CAS 知道谁在引用（GC 的判断依据）。
    只写一边的话，要么 GC 误删仍被引用的内容，要么孤儿永远清不掉。
  - mediaSummaryForEvent：把已有描述拼成一行写进 Input。这是方案 C 的
    落点——**描述文本才是持久语义记忆，blob 只是缓存**。blob 可能被容量
    GC 淘汰，但描述会一直留在 L0/L2/L3 的文本里，让「那张紫蓝红三色带图」
    几个月后仍可被检索。

ContextEvent 新增 ID 与 Media 两个字段，都是 omitempty：
  - ID 懒生成，只有真要挂媒体时才赋值。绝大多数对话没有媒体，全量生成
    会让每条事件都多一个字段进 context.json。
  - 存量 context.json 读回来两字段皆空，不影响任何既有行为（有测试）。

RelevanceContext.Prune 归档时转移引用（transferMediaRefs）：
  **先挂到归档文档、再注销原事件引用**。顺序不能反——先销后挂会让引用
  计数瞬时归零，若此刻后台 GC 正在跑就会把仍被记忆引用的内容当孤儿清掉。
  为此把 Prune 内的局部类型 scored 提为包级 scoredEvent（局部类型无法
  出现在方法签名上）。

media 包新增 OwnerContext/OwnerDocument/OwnerGraphSentence 常量：
  owner_kind 进了主键，拼错一个字符就是一条永远对不上的孤立引用——
  AddRef 不报错，DropOwner 也永远匹配不到。

## 配置

core.memory.media.enabled（默认 true）、.dir、.max_mb（2048）、
.gc_interval（6h）、.gc_min_age（1h）。

关闭后全链路静默跳过，对话行为与本特性上线前完全一致（有测试）。
mediaStore 为 nil 时同理——它是记忆增强，不是对话必需品，开不起来
只记一条 warning 不阻止启动。

## 测试（11 例）

入库与 MIME 归类、http URL 跳过、nil store 全链路 no-op、音视频混合、
stage/drain 清空语义、懒生成 ID、描述作为持久记忆、**归档转移期间内容
始终可读且 refcount 不归零**、无媒体存储时归档照常、context.json
向后兼容往返。

全仓 go build / go vet / go test 通过，SDK 冻结 diff = 0。

## 尚未接入

L3 图库的 graph_sentence owner（常量已备好，无写入方）、
描述生成的后台任务（Pending() 已就绪，尚无消费者）、
媒体 GC 的定时触发（配置项已注册，尚未接 ticker）。
 2026-09-04 20:53:32 +08:00
JianFeeeee
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 起就没通过——当时
的验证只看了 prompt_tokens 涨了 8500，没有校验模型答案对不对。

改为：tool message 保持纯文本结果，媒体另起一条紧随其后的 user message
承载，并在首个 text 块标注 [以下是 <tool> 注入的媒体内容]，避免模型误
以为是用户新发的图。位置必须紧跟 toolMsg，中间插入其他消息会让
tool_call_id 配对断开。

验证（生产，答案预先封存、生成时不读）：
- AUTO 源 vision=true 直视路径：随机三色带 → 答「紫、蓝、黄」，与封存
  答案一致，日志无 modal fallback（确实走的直视），耗时 9.6s
  （回退链同一用例需 ~90s，省掉了绕视觉模型一圈）
- see_video 6 帧直视：23s（回退链合包版 131s，逐块版 363s），模型正确
  描述测试图卡的彩条布局、彩虹带滚动与计数器递增
- 负向：AUTO 源改回 vision=false，回退链仍正常转写，模型如实标注来源
 2026-09-04 07:49:30 +08:00
JianFeeeee
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
JianFeeeee
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
JianFeeeee
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