jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-09-22 18:08:04 +00:00
Code Issues Packages Projects Releases Wiki Activity
523 Commits 6 Branches 27 Tags
3a780384d04964b4e4018aeca570259f78046ac8
Commit Graph

126 Commits

Author SHA1 Message Date
JianFeeeee
37d6796230 feat(gui+ohos): 同步阶段管道工具格「只滚动展示最新一条调用」 
WebUI 已改为工具格只露最新一条。桌面版与鸿蒙端是同一套运行态面板的
镜像，一并跟上，避免三端口径不一致：

- cmd/gui：renderRuntimePanel 工具格只渲染最新条目 + 本轮累计次数；
  overview 是整块 innerHTML 重建，故动画类由 state.toolFlash 单次驱动，
  避免任何重渲染都闪一下。
- cmd/ohos：RuntimePanel 工具格改为 latestEvent() + totalCount()，
  不再 ForEach 追加。已用 hvigor 实测 BUILD SUCCESSFUL。
 2026-09-14 20:09:57 +08:00
JianFeeeee
f3fa0e8f5b feat(ohos): 运行态面板 —— 阶段管道 + 中断队列（落在设置页二级明细顶部） 
接上一条腿：桌面版已同步，这次补鸿蒙端缺的运行态面板。
落点按之前的建议放在「设置 → 运行状态」二级明细页最前：明细卡回答「内核有哪些
东西、多少」，运行态回答「现在在干什么」，后者是进这个页面最先想看的。

## 新增

- `common/StageTrail.ets`：阶段轨迹单例（SSE 驱动）。由 ChatSse 的 stage 分支
  喂入，面板读取。**不并进 StatusStore**：轨迹来自 SSE 流，与 /status、/kernel
  的轮询是两条独立数据源，生命周期与失败模式都不同（SSE 断连不该让状态卡变空，
  状态轮询失败也不该清掉轨迹）。七阶段归并成五格，同阶段同一条累加计数，
  2.5s 无新事件自动回空闲。
- `components/RuntimePanel.ets`：等大表框面板。
  - 四个数字块（排队/中断/栈/子代理）
  - 阶段管道：每格 = 阶段名 + 本阶段本轮事件；当前阶段整框点亮
  - 中断队列：5 格（L4/L3/L2/L1 + 排队），级别色贯穿框头/槽位/描边；
    有积压整框描边点亮；排队队列虚线框区分（另一类别，不是另一优先级）
  - 格槽固定可见：深度为 0 时也有形状，不会剩一片空白

## 改动

- `StatusStore`：新增 `/runtime` 采集与 `RuntimeSnapshot`/`RuntimeQueue`
  （明细与运行态分开取、分开存）；失败保留上一次快照，旧后端无此端点时
  面板显示「运行态数据不可用」。
- `ChatSse`：stage 分支先喂轨迹，再管聊天侧角标。
- `SettingsPage`：`stageTrail.init()`。
- `StatusCards`：二级明细顶部渲染 `RuntimePanel()`。

## 关于宽度

模拟器（API 24，1256x2760 ≈ 360vp 宽）上 5 框一行会让「内核独占」这类标签被
挤成省略号，所以按项目已有的 `isWideScreen` 分两支：宽屏 5 框一行，手机 3+2
（补一个占位格保证框宽对齐）。两档都是等大框。

## 验证

- `hvigorw assembleHap` → **BUILD SUCCESSFUL**；`clean` 后全量重建，
  本次新增/改动的 6 个文件 **零 ArkTS 告警**。
- 未上机实测：本机签名 profile 无法授予 `ohos.permission.READ_PASTEBOARD`
  （module.json5 里已有的一项，非本次改动），`hdc install -r` 报
  `error: install failed due to grant request permissions failed`。
  没有为此卸载设备上的应用（会丢用户已存的连接配置），也没有改权限列表
  （属产品决定）。要上机的话，我可以临时去掉那一条权限打个一次性包验证。
 2026-09-14 19:05:46 +08:00
JianFeeeee
2163a7a092 feat(gui+ohos): 同步 WebUI 总览改版 —— 桌面版补运行态面板，两端补内核身份与开源许可 
WebUI 那边这几轮改完，桌面 app（Electron）与鸿蒙 app（ArkTS）要跟上。
先摸了底：**两个 app 此前都没有运行态面板**（阶段管道 / 中断队列），
所以这不是"移植"，是新做；emoji 图标两端本来就没有，无需处理。

## 桌面 app（cmd/gui/renderer）

1) 运行态面板（新）—— 与 WebUI 同一套设计语言：**等大表框**
   - 数据源 /api/v1/runtime（此前只拉 /status 与 /kernel）。
   - 四个数字块沿用本 app 的 statCard（排队/中断/栈/子代理）。
   - 阶段管道：5 个等大框，框内是本阶段本轮发生的事件 chip；
     当前阶段整框点亮。图标一律内联 SVG（含「工具会循环」标记）。
   - 中断队列：5 个等大框（L4/L3/L2/L1 + 排队）一行排开，
     级别名 16px/800、深度 26px/800、可见格槽（0 时也有形状）；
     有积压整框描边点亮；排队队列虚线框区分（另一类别，不是另一优先级）。
   - stage SSE 事件接上轨迹（rtTrailPush，同阶段同一条累加 xN），
     2.5s 无新事件回空闲。
   - 列宽 repeat(auto-fit, minmax(100px,1fr))：窄容器也保证 5 框一行，
     不出「4 个 + 1 个」的孤行。

2) 版本身份（修一个真缺陷）
   旧实现是 `s.version || "0.1.0"`：拿不到数据时**向用户展示一个不存在的
   版本号** 0.1.0。改为取 /kernel 的 build（-ldflags 注入的真实版本/commit），
   并在版本号下补一行「内核名 · commit」。

3) 开源许可卡（新）
   协议标识 + 协议全文 + 源码仓库 + §13 说明；网络条款按标识是否含 AGPL
   决定是否渲染，不硬写协议名。

## 鸿蒙 app（cmd/ohos/HomeAgent）

4) StatusStore 解析 /kernel 的 build：补 内核版本 / Commit / SDK 兼容 /
   构建时间 到「内核」分组；K_VERSION 统一成 v<版本>，新增 K_BUILD 广播
   「内核名 · commit」给摘要卡（版本号本身没有内核身份）。

5) 新增「开源许可」分组：许可协议 / 协议全文 / 源码仓库 / 网络条款说明。

## 验证

- 桌面：共享浏览器加载 renderer（桩掉 preload 桥）后喂真实形状数据渲染 ——
  版本卡 `v1.4.0+hotfix.f89e57a` + `HomeAgent · f89e57a`；管道
  `输入=输入 | 行动=思考 | 工具=qq_get_message x3 qq* | 输出=生成 | 结束=完成`；
  队列 `L4:0 | L3:3 on=3[active] | L2:2 on=2[active] | L1:0 | 排队:2 on=2[active]`；
  许可卡两个链接均为 target=_blank + rel=noopener noreferrer；无 emoji。
  node --check 通过。
- 鸿蒙：/opt/huawei/command-line-tools/bin/hvigorw assembleHap **BUILD SUCCESSFUL**。

## 未做（下一条腿）

鸿蒙端的运行态面板（阶段管道 + 中断队列）**还没有**。它比桌面端贵：
需要新组件（5 框管道 + 5 框队列）、把 /runtime 快照接入 StatusStore，
以及把 SSE 的 stage 事件从 ChatSse 的 sink 引到状态侧——后者是接口改动。
「状态」Tab 此前已被有意删除（并入设置页 + 二级明细），面板落点也要定
（建议放二级明细页顶部）。桌面的实现可直接作参照。
 2026-09-14 18:53:25 +08:00
HomeAgent Agent
4cbfdc970c perf(webui)+feat(config): 聊天记录写盘节流 + 配置库空闲页回收 
两条都是我上一封里点出、你说继续的问题。

① 聊天记录：每条消息都整段重写 → 节流合并写
   原来 persistChatLocked 每次变更就整段重写记录文件，而一轮对话会触发多次
   （用户消息、每个工具事件、收尾消息）。200 条上限下文件可达数 MB，单轮就能
   放大出几十 MB 写。文件里还留着一个 chatSaveThrottle=3s 常量——声明了但从未
   被使用（疑似上次 revert 的遗留），等于节流从来没生效。
   现在：persistChatLocked 只置脏 + 唤醒写盘协程；chatPersistLoop 去抖
   chatSaveThrottle(3s)、并以 chatSaveMaxDelay(10s) 兜底（持续输出也不会无限拖延）；
   写盘前把快照拷出来，**不持 chatMu 做文件 IO**；写失败重新标脏下轮重试。
   插件 Stop 里调 Handler.Close()：停协程 + 强制落最后一次（幂等），否则丢最后一轮。

   实测（临时实例，连发 3 条消息）：3s 窗口内记录文件**尚未创建**（节流生效）；
   SIGTERM 后文件出现且 6 条（3 用户 + 3 助手，无 LLM key 故为错误回复）全在
   ——关停落盘没丢。

② config.db：SQLite 的 DELETE 不缩文件 → 空闲页够多时 VACUUM
   新增 ConfigRegistry.MaybeCompact(minFreeBytes, minRatio)：空闲页 >= 1MB 且
   占页数 >= 25% 才做一次 VACUUM，避免每次启动都重写整库。库里是 WAL 模式，
   VACUUM 之后必须再 wal_checkpoint(TRUNCATE)，否则主库文件看着没变小。
   调用点放在插件加载**之后**（大值的搬走/删除发生在插件 Start 里，之前调没意义）。

   实测（一个刚被搬走 5MB 聊天记录的实例）：
     freelist 1288 页 × 4096B；启动日志「配置库已压缩: 5394432 -> 118784 字节」
     config.db 5,394,432 → 118,784 字节；记录文件 5,279,491 字节完好未动。

测试：TestChatPersistenceIsThrottled（节流窗口内不写盘 + Close 必落盘 + Close 幂等）、
TestMaybeCompactReclaimsFreePages（删大值后文件确实变小 + 数据完好 + 阈值不达标时不白做功）。
 2026-09-14 07:14:55 +08:00
HomeAgent Agent
0beb389223 fix(webui): 设置接口不再吐内部数据；--webui 覆盖生效；端口占用不再静默成功 
三处实测确认的缺陷：

① 设置接口整块吐出聊天记录
   plugin.webui.chathistory 是 webui 自己持久化的整段聊天记录（生产实例
   实测 5,176,016 字节），躺在插件配置表里被设置接口当普通配置项整块返回，
   前端还会把它渲染成一个巨大的文本框。
   修复：GET 跳过该键（按插件+键精确判定），PUT 直接 400，避免误改。

② CLI --webui 与 webui.listen_addr 一直是死配置
   内核原本在插件加载前写 settings["addr"]，但那时 config_<name> 表还没建
   （表只在插件注册 def 时创建），PluginSettings.Set 的 INSERT 失败，而错误被
   "_ =" 忽略了；随后插件 Start 里 RegisterDef 才建表并写入默认 :8080。
   实测：传 "-webui 127.0.0.1:18099" 仍然监听 :8080。
   修复：覆盖值改由插件自己接收（webui.SetListenOverride，loadPlugins 前调用），
   优先级 CLI > webui.listen_addr（非默认值才算显式配置）> settings["addr"]。
   实测修复后："-webui 127.0.0.1:18099" 正确监听 18099，与生产的 :8080 并存。

③ 端口被占时 webui 静默死亡
   Start 在后台 goroutine 里 ListenAndServe，先打印 "listening on" 再尝试绑定，
   失败只留一行日志，Start 永远返回 nil → 插件仍被当成加载成功。
   修复：net.Listen 同步做，失败即返回 error（交给加载器/守护），
   成功后才起 Serve，并打印真实绑定地址。
   A/B 实测（两个实例都撞生产的 :8080）：
     修复前："listening on :8080" + "server error: address already in use" + LOADED: webui
     修复后："[plugin] start webui: webui: 监听 :8080 失败: ..."，不再有 LOADED: webui

效果实测（同一实例，先注入 5,271,690 字节 chathistory）：
  GET /api/v1/settings   8,244,108 → 28,652 字节（约 1/288）
  meta 条数              5,208 → 105，幻影键 0 条
  设置页仍正常：?prefix=plugin.webui 返回 8 条 def；普通键 PUT 落库；
  校验：GET/PUT 内部键被拒；-webui 覆盖真实生效。

新增测试：TestSettingsNoCrossPluginLeak（跨插件泄漏/幻影键/chathistory 读写）、
TestListenOverrideAndBindFailure（覆盖生效 + 端口占用必须报错）、
TestResolveListenAddrPrecedence（优先级）。
 2026-09-14 06:54:16 +08:00
HomeAgent Agent
3edab0fe68 refactor(homed): main() 696 行按启动阶段拆成 25 个阶段函数 
main() 原本是一整条 696 行的启动脚本：日志、目录、记忆、配置、Lua、守护、
追踪、内核 API、文本记忆、LLM 源、文档/知识、人格、插件、Agent、ONNX、
IPC、心跳、关停全挤在一个函数里，变量跨 500 行互相引用。

现在 main() 只剩「顺序编排 + 就地交接」（**149 行**，低于 funlen 阈值 150）：
  opt           := parseFlags()
  logDir        := setupLogging(opt.dataDir)
  agentWorkDir  := ensureDataDirs(opt.dataDir)
  mem, closeMem := initMemoryStack(opt.dataDir)
  ...
共 25 个阶段调用，实现体在同包 bootstrap.go（一一对应）。

零漂移保证：
  * 阶段体逐字取自原 main，只做机械替换（`*dataDir`→参数、`memIdx`→`mem.indexer`）；
  * 原 main 的每个 defer 都换成一个在**同一位置**注册的 cleanup，
    LIFO 释放顺序不变；多资源阶段内部再按原注册顺序取反；
  * 语句级比对：原 main 的 525 条可执行语句全部有对应，无遗漏。
    仅 3 处为**有意**的结构改写（其余为同义替换）：
      1. initLuaVM / initTextMemory：「启动成功才 defer Stop」改为
         「失败返回 no-op cleanup，成功返回 Stop」——调用点语义不变；
      2. startIPCServer：同上（用 started 标志保证失败时不 Stop）；
      3. resolveBaseAPIKey：把三级兜底 API key 解析提成一个纯函数。
  * defaultPrompt 提为包级 const defaultSystemPrompt（不含版本号字面量）。

验证（A/B 实测，不是只跑编译）：
  * go build ./... / go vet ./cmd/homed/ / go test ./cmd/... ./internal/agent/... ./internal/plugin/... 全绿
  * 重构前后二进制各起一次（-data 临时目录，SIGTERM 收尾），日志集合**完全一致**：
    63 个注册工具、同名插件全部 loaded、kernel ready、插件逆序关停、'stopped'
    —— 差异仅为并发加载插件的打印顺序。

全仓非测试 Go 函数现状：≥300 行 **0 个**，≥200 行 9 个，≥150 行 16 个。
 2026-09-14 06:30:45 +08:00
root
62e1e02036 docs(ohos): README 两处事实修正（产物路径前置条件、≤400 行约定的边界） 
1. **安装小节的产物路径**：`entry/build/` 是纯构建产物、不入库，干净 clone 或清理过
   工作区时该文件不存在。补明"必须先跑完第 2 步"，并说明目录名随
   `-p product=<名字>` 变化、同目录还有 unsigned 版（`hdc install` 要用 signed）。
   本次实际构建校验过路径：`entry/build/default/outputs/default/entry-default-signed.hap`。
2. **≤400 行约定补边界**：不到 400 行的文件不要为了拆分而拆分 ——
   `@Component` 的 `build()` 只允许一个根节点，多节点 `@Builder` 改组件会多出一层
   Column 包裹，布局等价是推理出来的、不是看出来的，每拆一次都要付一次
   "未上机验证"的账。并记下 `pages/Index.ets`(396) 属于"不越线就不动"的一类。

无代码改动，纯文档。
 2026-09-13 22:42:37 +08:00
root
8a58cde3ee docs(ohos): 本地构建前置条件 + 运行时验证清单 + 工程结构表刷新 
1. **oh_modules 前置条件**：该目录被 .gitignore 忽略但必须存在 —— hvigor 不会
   自动 ohpm install，移走后构建直接报 arkts-no-untyped-obj-literals（依赖类型
   声明缺失）且不重建目录。写明"clone 后先 ohpm install，别当垃圾清掉"，
   同时说明 entry/build 与 .hvigor 是纯产物、可随时删（冷构建 ~8s）。
2. **hvigorw 绝对路径**：仓库里的 ./hvigorw 是符号链接，启动脚本按
   $(dirname $0) 定位，会报 File not found: <repo>/cmd/ohos/hvigor/bin/hvigorw；
   统一改用 <command-line-tools>/bin/hvigorw（本机 /opt/huawei/command-line-tools/bin/hvigorw）。
3. **运行时验证清单**：把"构建通过 ≠ UI 行为不变"这件事写进仓库而不是留在邮件里
   （流式对话/思考卡与工具卡/附件上传/设置与设备与插件的二级页/宽屏分栏），
   并注明无提权环境起不来模拟器时需在真机补验证。
4. 工程结构表按前几轮拆分后的实际情况刷新（common/components/pages 新增文件与职责），
   并记下"单文件 ≤400 行、页面只做壳"的约定。

无代码改动，纯文档。
 2026-09-13 22:35:29 +08:00
root
e733d05a5e refactor(ohos): DevicePage 560→307 行（入口列表/四个面板/模型拆分） 
- common/DeviceModel.ets（73）：device_id 兜底（桥 id 优先 → 持久化 → 生成并落盘，
  顺序与原 aboutToAppear 一致）、/device/online 响应解析、四个二级页路由 id
- components/DeviceRootEntries.ets（92）：一级入口（本机/通道两组 NavRow 列表）；
  宽屏高亮自己读 AppStorage 的 isWideScreen，页面只给 activeSub 与 onOpen
- components/DevicePanes.ets（316）：DeviceLocalPane（基本信息 + 授权开关）、
  DeviceCapsPane（能力清单）、DeviceGatewayPane（网关信息 + 刷新）、
  DeviceListPane（在线设备列表）、DeviceKvRow；每个面板自带 SubPageLayer

页面保留导航栈、openSub/closeSub、授权开关、toast、refreshDevices 与
SubDestination 分发。所有文案、图标、颜色、过渡与失败分支逐字保留；
面板内容多了一层无 padding 的 Column 根节点（@Component 的 build() 只允许
一个根），宽度 100% + Start 对齐，与 SubPageLayer 内容槽的布局一致。

验证：hvigorw assembleHap BUILD SUCCESSFUL。
 2026-09-13 22:34:20 +08:00
root
8a9fc05451 refactor(ohos): DeviceBridge 409→296 行（协议类型与帧构造移到 BridgeProtocol） 
- common/BridgeProtocol.ets（168）：hello/bind/cmd_result/cmd_data_start/
  cmd_data_end/event/status 七个消息结构、CHUNK_SIZE、BridgeCmdHandler 回调类型，
  以及 bridgeHelloFrame / bridgeBindFrame / bridgeResultFrame /
  bridgeDataStartFrame / bridgeDataEndFrame / bridgeEventFrame /
  bridgeStatusFrame / bridgeChunkSlices 八个纯构造/切片函数
- common/DeviceBridge.ets（296）：只剩 socket 生命周期、重连代际、绑定状态机
  与命令分发

**DeviceBridgeClient 的对外方法名与签名一字未改**（isConnected / getDeviceId /
setCmdHandler / setStateListener / connect / updateAuthorized / disconnect /
sendResult / sendDataChunked / sendEvent / sendStatus / send），
`send*` 仍是"拼帧 + 发出去"两步，拼帧那一步搬走；分块发送的
"start → chunks（失败即 break）→ end"顺序与 `bytes.slice` 语义保持不变。
外部只有 deviceBridge 单例被 import（BridgeRouter / DeviceBridgeSession /
DevicePage），无其它符号依赖。

验证：hvigorw assembleHap BUILD SUCCESSFUL；diff 中 DeviceBridge.ets 无
状态机/回调/重连逻辑改动。
 2026-09-13 22:28:53 +08:00
root
31bbde9cdd refactor(ohos): Attachment 463→344 行（纯函数与字节解码移出 components） 
- common/AttachmentMeta.ets（106）：parseAttachment / attachmentFromChannelOutput /
  fileNameOf / formatBytes / oneDecimal / extLabel / sanitize，纯函数无平台依赖
- common/AttachmentImage.ets（37）：loadPixelMap（沙箱 file:// 与远端 /files 两条路径）

components/Attachment.ets 只留 UI：AttachmentCard 与 AttachmentDetailContent。
**两者的导出名、@Prop 形状与 import 路径均未变**（ChatPage 仍从
'../components/Attachment' 取 AttachmentDetailContent），组件内部的布局、
过渡、提示文案与失败分支逐字保留，仅函数体搬走。引用方 5 处 import 路径同步更新。

验证：hvigorw assembleHap BUILD SUCCESSFUL；diff 中 Attachment.ets 只有
"-删除纯函数 + import 改写"，无属性/布局改动。
 2026-09-13 22:27:34 +08:00
root
e0514c3692 refactor(ohos): ChatPage 1962→207 行（状态机/SSE/气泡/输入区拆分） 
- common/ChatStore.ets（388）：消息数组、分页游标、新消息入场标记、
  SSE 连接与重连、防抖刷新（50ms）统一成一个单例状态机
- common/ChatSse.ets（192）：SSE 事件 → 状态的翻译层，逐分支照搬
  channel_output/agent_output/reasoning/delta/tool_call/stage/agent_error/
  sync_required；通过 ChatStreamSink 接口写入，避免与 ChatStore 形成循环依赖
- common/ChatSession.ets（176）：POST /chat 与 POST /chat/file 的发送、
  超时兜底、POST 响应与 SSE 的合并判定
- common/ChatFormat.ets（223）：mime 推断、ForEach 键 structSig、工具卡
  状态/颜色、渠道判定与头像配色
- common/ChatHistory.ets（96）：历史载荷与 tool_calls 解析
- components/ChatBubble.ets（247）：气泡（头像/渠道名/思考卡/工具卡/附件卡/正文）
- components/ChatToolCard.ets（253）：思考卡 + 工具卡
- components/ChatStream.ets（210）：消息列表 + 顶栏遮罩 + 底部淡出 + 触顶懒加载
- components/ChatComposer.ets（357）：输入行、选图/选文件、沙箱落盘、发送
- components/ChatAttachBar.ets（139）：加号菜单 + 待发送附件条

响应式语义刻意保持不变：数组不进 AppStorage，改用自增版本号 K_CHAT_REV
通知订阅组件重取快照（ChatStream 把它镜像进 @State messages，ForEach 每次
拿到的仍是新数组引用，与拆分前 this.messages = this.messages.slice() 等价）；
structSig 仍不含 content，正文靠 MarkdownView 的 @Prop 流式更新；
markNew 仍不切片、入场动画交给紧随其后的 refresh()；
animateTo 只能存在于组件里，所以折叠翻转的动作留在 ChatStream 内。

验证：hvigorw assembleHap BUILD SUCCESSFUL；SSE 各分支、ensureToolCall、
markNew、sendChat/sendWithAttachment 的守卫顺序均与原实现逐条比对过，
守卫从"页面方法内"移到输入区组件时保持了原有先后（连接判定先于清空输入）。
 2026-09-13 22:19:05 +08:00
root
f79e0f82dd refactor(ohos): SettingsPage 1463→389 行（模型/条目卡/四个面板拆分） 
- common/SettingsModel.ets（313）：设置载荷解析、分类归并、分页切片、
  路由常量，纯逻辑无 UI
- components/SettingsEntryCard.ets（215）：单条设置卡（值编辑/保存）
- components/SettingsRootEntries.ets（100）：一级入口行 + 状态汇总卡
- components/SettingsHome.ets（95）：一级页壳（顶栏/浮层/提示条）
- components/ConnectionsPane.ets（347）：后端连接 CRUD（自带二级页壳）
- components/AppearancePane.ets（265）：主题/背景/透明度（自带二级页壳）
- components/BackendSettingsPane.ets（172）：分类与条目两个二级面板

页面保留 @State 集合、加载/保存编排与 SubDestination 分发；数组仍走
@Link 直传（未引入 AppStorage 数组）。相册选择、重启前台桥等既有行为
与提示文案逐字保留。

验证：hvigorw assembleHap BUILD SUCCESSFUL。
 2026-09-13 22:18:56 +08:00
root
131c1ff0e9 refactor(ohos): PluginsPage 995→374 行（接口/状态/列表/详情/浮层拆分） 
拆分方向按职责切，页面只留导航与数据编排：
- common/PluginApi.ets（174）：fetchPluginRows / fetchPluginDetail
- common/PluginStatus.ets（78）：状态判定、文案、颜色、副标题
- components/PluginListView.ets（166）：列表卡 + 列表
- components/PluginDetailPane.ets（291）：详情面板
- components/PluginsOverlays.ets（65）：安装表单
- components/ToastBar.ets（48）：提示条，PluginsToast 与 SettingsPage 的
  toast 合并成这一个组件（此前两处各写一份）

UI 结构与文案逐字保留（含 92%/layoutWeight 等既有布局修法）。

验证：hvigorw assembleHap BUILD SUCCESSFUL。
 2026-09-13 22:18:49 +08:00
root
414e6a1627 refactor(ohos): StaticMarkdown 604→332 行（Markdown 解析抽到 common/MarkdownParser） 
把"文本 → 块/片段"的纯解析逻辑（MdBlock/MdSpan、parseBlocks、parseInline、
表格/分隔线/有序列表判定）整体搬到 common/MarkdownParser.ets（282 行），
StaticMarkdown.ets 只留 StaticMarkdownView 组件（332 行）。

解析规则逐字保留，未改任何排版行为；MdBlock/MdSpan 原本只被
StaticMarkdown.ets 使用（唯一引用方是 components/MarkdownView.ets，
它只用 StaticMarkdownView）。

验证：hvigorw assembleHap BUILD SUCCESSFUL。
 2026-09-13 22:18:43 +08:00
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
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
07e08352b9 feat(waiter,devicebridge): 设备桥连接带授权态，命令处理器类型统一 
- `runDeviceBridgeLoop`/`connectDeviceBridge` 增加 `authorized` 入参（未授权不再尝试建立桥连）；
- `Bridge.OnCmd` 的处理器类型改为具名 `BridgeCmdHandler`，与 waiter 侧签名对齐。
 2026-09-12 20:21:01 +08:00
JianFeeeee
8f40b91dea feat(ohos): 设备桥会话管理、状态/设备信息载荷与能力路由完善 
- 新增 `DeviceBridgeSession.ets`：会话生命周期（创建/复用/回收）与 TTS 会话显式 shutdown；
- `BridgeCaps`/`BridgeRouter` 与内核实际支持的本机命令保持一一对应，补齐 status/deviceinfo；
- 页面与状态存储调整（DevicePage/Index/SettingsPage/StatusStore/SubPage）、新增 ScreensuePage；
- module.json5 与 string.json 同步（新增页面与文案）。
 2026-09-12 20:21:01 +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
b15d0bd114 refactor(plugin)!: 重编提示与模板路径改用 hmapdev；文档全面对齐 1.2.0 
工具链在 SDK 1.2.0 更名为 hmapdev（原 plugindev）。核心侧三处功能耦合同步：

1. 用户可见报错：旧 C ABI 产物 / 协议版本不匹配 / 共享段版本不匹配
   三处「请用配套 plugindev 重编」→ hmapdev（对应两条测试断言同步）
2. e2e_template_test 的模板路径改为 tools/hmapdev/templates，
   并保留旧路径回退（旧 SDK 检出仍能跑测试）
3. 注释与文档同步

文档更新（用户可见面）：
- assets/docs/{zh,en}/PLUGIN_DEV.md：工具链章节整体改为 hmapdev，
  补改名说明与 SDK 存储目录迁移；命令示例全部更新
- assets/docs/{zh,en}/ARCHITECTURE.md：**流程图与章节对齐 v1.2.0** ——
  · 向量化章节改为三层降级：统一多模态空间（主）→ 词嵌入 → TF-IDF（回退），
    写明「同指纹且同维度才参与融合」
  · 媒体记忆章节重写：媒体是一等记忆块（无独立 GC / 无引用计数 / 无描述式索引 /
    正文不再写 media marker），并写明 reembedStaleMedia 的跨空间迁移与写回
- README{,_EN}.md、docs/zh/plugin-interface-matrix.md：工具名与模板路径同步
  （历史条目标注「当时名为 plugindev」）

验证：go test ./internal/plugin/ ./internal/plugin/proc/ ok，
含 4 条真实模板 E2E（模板路径切换后仍通过）。
 2026-09-12 12:42:43 +08:00
JianFeeeee
34628720f2 fix(memory): 修 beta.2 压测发现的三个向量/文档缺陷 
来源：v1.2.0-beta.2 全方位压测（报告 /var/tmp/stress/REPORT.md）

1. 文档向量迁移结果不落盘（生产已复现）
   - BuildDenseIndex 改完内存不置 dirty；docStore.Stop() 全仓无调用者 → flush 成死代码
   - 后果：每次启动重算同一批文档（线上 496 篇约 17s），磁盘 dense_fp 永不收敛
   - 修：迁移当场落盘（抽出 flushLocked 以免重入锁）+ main.go 关停链 defer docStore.Stop()
   - 生产证据：线上 488 篇文档仅 4 篇含 dense_fp，且这 4 篇均为运行期 Insert 的新文档
2. 块指纹对但维度错时污染文档向量（健壮性缺口）
   - denseFor 只校验 b.Fingerprint，不校验长度；FuseVectors 取最大维度并跳过长度不符者
     → 512 维文本 + 2048 维块 = 2048 维且打上当前指纹
     → 该文档在检索侧被长度守卫永久跳过，且每次启动重算（不收敛）
   - 修：denseFor 要求 len(b.Vector) == 空间维度
   - 可达性：内核两个块产出点均成对取自同一行（it.Vec ↔ it.VecModel），故属防御性修复
3. Insert 与 loadAll 的 ID 约定不对称（低）
   - Insert 落盘任意 <id>.json，loadAll 只加载 doc_ 前缀 → 自定义 ID 文档重启后静默消失
   - 修：loadAll 只要求 .json（空 ID 仍跳过）

回归测试 4 条：迁移跨重启落盘 + 已对齐 0 重算（用向量空间调用计数判定，
不靠日志）、坏块不参与融合且同维度正常块仍参与、自定义 ID 可加载、Stop 落盘。

反向验证（纪律要求）：临时回退本次修复后，前 3 条均变红且报错正是缺陷签名
（dim=999/space-OLD-999 永不收敛、文档向量 2048 维、文件重启后消失）；恢复后全绿。

验证：go build ./cmd/homed ok；go vet ./internal/memory/document ./cmd/homed ok；
go test ./internal/memory/... 7 包全绿。
 2026-09-12 11:05:11 +08:00
JianFeeeee
6a3439a49c fix(initconfig): 必须带 cgo 构建，且失败不再静默 
cmd/initconfig 通过 database/sql 使用 mattn/go-sqlite3，而 build.sh 一直用
CGO_ENABLED=0 构建它：该库在非 cgo 下退化成 static_mock.go 里的桩，sql.Open
是惰性的所以不报错、第一次 Exec 才失败，而 main.go 丢掉了所有返回值。合起来
是一个完全静默的空操作——打印凭据、退出码 0、config.db 里一个字节都没写。
安装脚本把这份凭据写进 credentials.txt，用户照着登录必然失败，全程无报错。

- build.sh: initconfig 改 CGO_ENABLED=1，并写明为何不能图省事去掉 cgo
- main.go: 每个 Exec 都检查；写完**回读比对**（不看返回码，看真实落盘内容），
  不一致即非零退出

反向验证：仍用 CGO_ENABLED=0 构建时，现在 stderr 报
"Binary was compiled with 'CGO_ENABLED=0', go-sqlite3 requires cgo to work"
且 exit 1（此前是 exit 0 并把凭据照打印出来）。
 2026-09-12 08:10:26 +08:00
JianFeeeee
bfdb395731 feat(memory): 新增 chineseclip provider —— text+image 的小体积可商用向量空间 
## 为什么

用户决定「本轮不覆盖 video，先支持 text+image」。这一刀正好解锁了此前
「小 + 可商用 + 覆盖视频」三者不可兼得的僵局：不要求视频后，唯一同时满足
**小、可商用、中文原生** 的选项是 Chinese-CLIP ViT-B/16。

实测对比（同机、真实跑出来的数字）：

| | Chinese-CLIP | jina-v5-omni-nano | Qwen3-VL-Emb-2B |
|---|---|---|---|
| 参数量 | 188M | 1.04B | 2B |
| 产物 / 常驻内存 | 754MB / **1.15GB** | ~2GB / 2.23GB | 8GB / 9.4GB |
| 维度 | 512 | 768 | 2048 |
| 许可 | **Apache-2.0** | CC BY-NC（不可商用） | Apache-2.0 |
| 视频 | 无 | 有 | 有 |

本机可用内存只有 5.3GB，Qwen 的 9.4GB 无法进程内使用；而 ORT format + mmap
那条路被证实当前不通（转换器对三段图段错误；走通还需同时升 ORT 运行时与
Go 绑定，v1.36 要求 API 29 而本机只有 28）。1.15GB 则可以直接进程内跑。

**代价已写进包注释与文档**：CLIP 是双塔对比学习，text↔image 是强项，但纯文本
语义明显弱于 MLLM 型嵌入器；文本检索仍由既有词向量/TF-IDF 路径兜底。
需要更强文本语义或视频时切回 qwen3vl。

## 内容

- `providers/chineseclip/`：按公共 SPI 实现的 provider（注册名 `chineseclip`），
  含 BERT WordPiece 分词器、图像预处理、ONNX 双塔推理、无标签 stub。
- `scripts/export_chineseclip_onnx.py`：从官方权重导出规范产物 + 冻结参考，
  自带逐用例 PyTorch 对比与覆盖度断言（计划集合≠执行集合即非零退出）。
- `cmd/homed/main.go`：空白导入两个 provider，由配置选其一。
- `go.mod`：`golang.org/x/text` 由间接依赖转为直接依赖（删音标需要 NFD）。

## 实现要点

- **分词器逐 token 对齐官方**。第一版探针自己拼 BertTokenizer（只给 vocab.txt、
  没删音标、中文没逐字切），中文被整体切成 [UNK]，三个不同句子产出几乎相同的
  向量（余弦 0.98）——差点把「模型坏了」当成结论。官方配置是 do_lower_case=true
  + 删音标生效 + 中文逐字切分；`TestTokenizerMatchesOfficialReference` 钉住
  逐 token 一致。
- **图像缩放自写 bicubic**（复刻 PIL 的 precompute_coeffs + a=-0.5 核），不引
  golang.org/x/image：它未进本机模块缓存，且最新版要求把整个工具链升到 Go 1.26，
  为一个缩放函数动工具链不划算。
- **归一化在 provider 侧**（两个塔的图里都没归一化），检索按余弦。
- **指纹覆盖全部影响语义的产物**：两个 ONNX 图 + vocab.txt + embed_config.json，
  读不到就写 MISSING（跳过等于对缺件不敏感）。
- 会话 Run 用 runMu 串行化（ORT 会话不保证并发安全），创建/销毁用 mu。

## 模态范围

只声明 `text` 与 `image`；`audio`/`video` 明确返回 `ErrUnsupportedModality`，
绝不用别的模型向量冒充（这是「音频明确 unsupported」纪律的落地）。

## 验证（实测）

导出侧：10 个用例（5 文本 + 5 图像）ONNX vs 官方 PyTorch 全部
`cos = 1.000000000`，覆盖度断言 10/10 通过。

Go 侧（`CHINESECLIP_MODEL_DIR=... go test -tags onnxruntime ./providers/chineseclip/ -v`）：
11/11 通过，其中
- 文本 5 用例 `cos = 1.000000000000`（逐位一致）
- 图像 4 纯色用例 `cos = 1.000000`（与官方预处理在 6 位小数内一致）
- 跨模态判别：红图对「红色」文本高于「蓝色」文本
- 模态拒绝 / 空输入 / 指纹稳定 / 产物缺失报错

顺带修掉测试自身的一个假通过：参考向量是**未归一化**的原始输出（模长 10~36），
原先「点积当余弦 + 单侧下界」会让 13.6 也判过，已改为真余弦 + 双侧容差。

构建矩阵：`go build/vet ./...` 与 `-tags onnxruntime` 两种都过；
`providers/... pkg/... internal/config/... internal/memory/vector/...` 回归通过
（qwen3vl 的 TestVideoModelInputMRope 需要 QWEN_ONNX_MODEL_DIR 指向含视频档的
v3 目录，缺该环境变量时用的是只有文本+图像的目录，与本改动无关）。

## 未做（明确记录）

- 发行版默认 provider 与构建标签变更：留下一提交（涉及打包与模型分发策略）。
- 模型产物（754MB）不进仓库，由导出脚本生成。
 2026-09-11 23:58:53 +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
a37bc7333e refactor(memory): 核心不再适配具体模型——公共 embedding provider SPI + 注册表 
问题：cmd/homed 里 `case "onnx": qwen.New(modelDir)` 把模型适配写进了核心，
`type=onnx` 名义上是格式、实际写死了一个模型家族；2117 行 Qwen 专属代码
（BPE、chat template、M-RoPE、Vision_gN 命名）住在内核树里，还带着一对
`//go:build onnxruntime` 的 stub。加任何新模型都要改内核。

现在核心只认一个模型无关的公共契约（pkg/embedding）：
- 输入是不透明的 Data+MIME，解码/预处理/时序分组全归 provider
- 能力是数据（Info.Modalities），不是接口方法——新增模态无需改核心接口
- 不支持的模态返回 embedding.ErrUnsupportedModality（可 errors.Is 识别）
- 按名字注册，重复注册 panic；Options 是 provider 私有命名空间，核心不解释

改动：
- 新增 pkg/embedding：Modality/Purpose/Input/Info/Provider/Config + 注册表
  （Open 校验 Info，ValidateVector 在入库前拦下维度错与非有限值）
- providers/qwen3vl：Qwen 实现整体移出内核（git mv），实现公共 SPI 并自注册
- internal/memory/vector：新增 ProviderAdapter（公共 SPI → 内部小接口）；
  ErrModalityUnsupported 改为公共哨兵别名；删除 VideoEmbedder 可选接口
  （那正是「核心为每个新模态长方法」的坏味道）
- http embedder 也变成普通 provider（注册名 http）
- cmd/homed：删除 qwen import 与 onnx/http 分支，改为按 provider 名打开 +
  透传 options.*；provider 打开失败只警告并禁用多模态检索，不影响启动
- config：multimodal_space.type/onnx./http.* → provider + options.*
- 删除 internal/memory/qwen（整体搬迁）

测试：
- pkg/embedding：注册表隔离/未知名字/非法 Info 自动关闭/ValidateVector
- vector：适配器原样透传字节与 MIME、维度错被拦、Close 幂等且停止使用、
  两个哨兵 errors.Is 互通
- providers/qwen3vl：新增公共 SPI 全链路集成测试（Open→Info→Embed→
  未知模态哨兵），并明确断言 Info 不声明 video

已知未完成（不得当作已验证）：
- 视频冻结回归 TestEmbedderVideoMatchesONNXReference **显式跳过**：Go 侧
  video 模板缺少 processor 按时间组插入的字面时间戳文本
  （<0.0 seconds>/<1.0 seconds>），同一输入 Python seq=1190(1152+38)、
  Go 只有 22 个文本 token。时间戳也占 M-RoPE 位置，故现有 M-RoPE 自洽断言
  通过不能证明与官方实现一致。修复属 provider 内部工作。
- 视觉侧三档已导出并逐档校验通过（cos 1.000000119/1.000000119/1.000000000）

验证：go build ./... ；go vet -tags onnxruntime ./... ；
go test -short ./internal/memory/... ./internal/agent/core/... ./internal/sdk/... ./pkg/...
；onnxruntime 下 providers/qwen3vl 全绿（视频为显式 skip）
 2026-09-11 18:26:19 +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
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
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
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
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
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
JianFeeeee
48b5c2401c feat(ohos): MotionBase 统一按压动效 + 分层图标随主题切换 
## 动效统一

各组件重复实现按压反馈（@State pressed + scale + animation + onTouch 四件套），
时长各写魔数导致全局手感不一致。

- 新增 components/MotionBase.ets：通用动效的"父组件"。ArkUI V1 的 @Component
  struct 无法继承他人 build，改用组合表达继承——调用组件把内容经 @BuilderParam
  内容插槽传入，MotionBase 在包装节点统一挂动效修饰器。
  pressEnabled 默认关（纯展示容器零开销）；fillWidth=false 供气泡内卡片按内容
  自适应宽度；flexWeight 供等分排列按钮参与剩余空间分配。
  onPress 只作按压瞬时轻量钩子，导航/提交语义仍由调用组件 onClick 负责，
  避免"按下即触发"的手感偏差。
- Constants.ets 新增动效 token：ANIM_FAST(150) / ANIM_NORMAL(220) /
  ANIM_ENTER(280) / ANIM_SLOW(400) / PRESS_SCALE(0.97)。
  取值依据：状态切换 150-250ms（>300ms 显拖沓），大位移进出场 300-400ms
  才不突兀；曲线统一 EaseOut 起步快收尾缓。
- NavRow / StatusSummaryCard / AttachmentCard / 插件卡片等公共组件接入
  MotionBase，移除各自的按压四件套。组件专属动效（聊天输入框上弹、加号菜单
  浮起、折叠面板展开、toast 进出场）保留在各组件内，不塞进父组件。

## 图标与启动页随主题切换

原先直接指向位图 app_icon.png，浅色底被烧进图标，深色模式下桌面与启动页跳脱。

- 改用分层图标 layered_image：foreground 为字形，background（沉淀色）在
  base/ 与 dark/ 各一份，随系统主题切换。app.json5 与 module.json5 的
  icon 均指向 :layered_image。
- startWindowIcon 改用透明底 start_icon.png，配合 start_window_background
  的 base(#F1F3F5) / dark(#000000) 两份取值，浅深模式遮罩与图标都能对上。

## 验证

清空 entry/build 后全量重编：hvigorw assembleHap BUILD SUCCESSFUL（9.8s），
零 ArkTS 错误。提交内容已确认不含 build/ oh_modules/ .hap 与签名材料。
 2026-08-30 17:23:40 +08:00
root
8510a2f2eb fix(ohos): 移除硬编码后端凭据，地址规范化默认 https 
- Model.ets: defaultConnection 不再内置 url/apiKey，改为空白模板
- 新增 normalizeBaseUrl：补协议（默认 https）、去尾斜杠、去误粘的 /api/v1
  裸域名走 http 会被反代 302 到门户站，客户端只拿到 404，表现为"连接直接失败"
- ConnStore: 增删改与读取存量数据时统一规范化 url
- 去掉 ensureDefaultConnection，首启不再预置连接，未配置时走统一提示
 2026-08-29 13:49:30 +08:00
JianFeeeee
46e942f0c2 feat(ohos): 鸿蒙端聊天历史分段懒加载 + 首次提交完整工程 
原有 cmd/ohos/HomeAgent 是未入库的鸿蒙原生 ArkTS 工程，本次随改动一并入库，
保证他人 clone 后可直接编译（含 .gitignore 排除 build/oh_modules/签名材料，
提供 build-profile.json5.example 模板）。

本次功能改动（与 WebUI / GUI 三端对齐）：
- /chat/history 首屏只拉最新 CHAT_PAGE_SIZE(40) 条，1.26MB → 48.5KB
- 抽出 parseHistoryPayload() 复用解析，记录 chatOffset/chatHasMore
- 新增 loadOlderChat()：向上滚动触顶（yOffset<60）懒加载更早页
- 工具调用 args/result 与 reasoning_content 完整还原，不做裁剪

构建验证：hvigorw assembleHap BUILD SUCCESSFUL（7.8s，ChatPage 零告警）
 2026-08-29 10:25:12 +08:00
JianFeeeee
a0f7c9b5eb perf(webui): /chat/history 分段懒加载 + lean 瘦身模式 
问题：/api/v1/chat/history 无分页返回全量 1.26MB（200条），移动端/弱网首屏很慢。
实测体积构成：tool_calls args/result 占 71.8%，reasoning_content 11.6%，content 仅 3.4%。

后端 handler.go：
- 新增查询参数 limit（1..maxChatHistory）/ before（游标）/ lean（瘦身）
- 全部可选，省略时返回全量 → 向后兼容旧客户端
- 响应加 total/offset/has_more，供前端判断能否继续向上加载
- lean=1 裁剪 tool_calls 的 args/result 并置 truncated 标记、省略 reasoning_content
- ChatToolCall 新增 Truncated 字段（前端可显示'详情需展开加载'而非误判执行失败）

前端 WebUI + GUI（两端同步）：
- 首屏只拉最新 40 条（CHAT_PAGE_SIZE），1.26MB → 48.5KB（lean 26KB）
- 新增 loadOlderChat()：滚动触顶（<60px）自动拉上一页，插入后按 scrollHeight 差值补偿
  滚动位置避免视口跳动
- state 新增 chatOffset/chatTotal/chatHasMore
- syncChatFromHistory 改用重叠区对齐（分段后不能再用长度比较判断新增），
  找不到重叠点安全退化为全量刷新最新页

实测：无参数 1287.9KB / limit=40 48.5KB / limit=40&lean=1 26.0KB；
before 游标翻页、limit 越界/非法值、before=0 等边界均正确
 2026-08-28 23:21:13 +08:00
JianFeeeee
b902d61bb9 fix(gui): SSE消息同步不及时，同步webui修复 
- 新增 syncChatFromHistory()：增量同步，仅追加新消息不重建已有DOM→无闪烁
- handleSSEEvent 监听 sync_required 事件 → 增量补拉历史
- SSE 断连(pump退出)后先 syncChatFromHistory 补偿再重连
- startUptimeTicker 增加30s轮询兜底（补偿跨渠道消息丢失，CLI连接跳过）
 2026-08-27 11:29:20 +08:00
JianFeeeee
c44ec0f210 feat(waiter): daemon模式 + localuse本机外设插件 
waiter 新增 --daemon 后台驻留模式 (daemon.go):
  - 维持 homed 连接，TUI实例经 Unix socket 接入
  - 单客户端串行模型：每个TUI独占homed响应，新客户端回放缓冲(256行)
  - 设备桥场景可无 homed 运行（纯设备桥驻留）
  - 设备桥看护循环：WS断开自动重连(3-5s间隔)
  - conn.go 新增 daemonConn 类型，dial() 优先检测 daemon

localuse 插件 (internal/plugins/localuse/):
  - local_screensee / local_camerasue / local_speakeruse
  - local_screensue / local_clipboardsee / local_clipboardsue / local_computeruse
  - 跨平台实现(Linux/macOS/Windows)，能力与 waiter device.go 对齐
  - headless服务器上缺依赖工具自动返回安装提示

SDK sync: third_party SetToolBlocks 多模态类型同步
README 补充 daemon 模式使用文档
 2026-08-27 09:27:15 +08:00
JianFeeeee
f0cdbdb030 feat(sdk): SettingsAPI.DataDir() 插件专属数据目录 + ai_image 本地交付 
【SDK DataDir API】
- SettingsAPI 新增 DataDir() string：返回插件专属数据目录
  <data>/plugin_data/<name>（内核保证存在），解决此前插件只能
  靠 GetCore("daemon.data_dir") 手工解析的缺陷
- settingsImpl 新增 dataDir 字段 + SetDataDir；Registry buildSDK
  注入（<data>/plugin_data/<name> 并 MkdirAll）；main.go 接线
- cabi 新增 CORE_SETTINGS_DATA_DIR (id 51)；plugindev dispatchSettings
  模板补 DataDir() 实现

【ai_image 交付本地路径】
- 生成后下载临时 S3 URL 到插件数据目录，返回本地文件路径（永久不
  过期），而非 1 小时过期的 S3 URL。带 UA 规避图床对无 UA 客户端拦截
  （此前 agent 裸 curl 验证被拒导致误报失败）
- 返回 local_paths 字段 + 提示用 output_send(type=image) 展示

端到端：ai_image_generate → plugin_data/ai_image/*.png 有效 PNG(1024²)，
经 llmsproxy→siliconflow 生成。
 2026-08-26 21:40:29 +08:00
JianFeeeee
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
JianFeeeee
cb76828e43 fix(cmd/files/webui): shell 语义修复 + 根沙箱误判 + 上传注入走 interrupt + UI 区分附件来源 
1. cmd_run 改经 /bin/bash -c 执行完整 shell 语法
   旧实现 shellUnquote 拆词后直接 exec：'pwd; ls /' 变成执行名为
   'pwd;' 的程序（exit -1）、heredoc 被截断、管道/命令替换全部失效——
   agent 多次反馈命令解析奇怪即此。危险命令拦截（kill homed 等）保留。

2. files 沙箱根目录判断修复
   pathWithinSandbox 在 base='/' 时 prefix 变 '//'，所有绝对路径误判
   逃逸（生产实锤：files.dir=/ 下 files_read/write/ls 全部报 outside
   sandbox）。根沙箱直接放行。

3. webui 文件上传注入改走 interrupt（system 角色）
   文件元信息不再混入用户消息气泡；用户附言作为正常消息先行注入，
   文件说明紧随其后以 no_memory interrupt 补充——对齐 terminal_watch/
   timer 工具提醒模式，聊天流保持干净。

4. 前端附件卡片按 role 区分来源
   user=右侧+『你发送的』标签+accent 底色；assistant=左侧+『小宅发送的』。
   📌 emoji 按钮换为 SVG 图标，前端 emoji 清零。
 2026-08-26 10:24:47 +08:00
JianFeeeee
fad490dca0 fix(remotedevice): 媒体回传落盘 + webui SSE panic + GUI 相机跨平台 
1. remotedevice 媒体落盘（核心改动）
   设备录像/照片二进制聚合后写入 <data>/device_media/<reqID>.<ext>，
   cmd_result 返回 file 路径，不再 base64 内联——10s 录像数 MB 的
   base64 会撑爆 LLM 上下文与工具结果管道。未配置目录时保持旧内联行为。
   新增 TestWSBinaryMediaToFile 覆盖。

2. webui SSE 'send on closed channel' panic（生产单日 4924 次）
   handleChatEvents 的 defer close(writeCh) 与 Subscribe 回调闭包竞态：
   handler 退出后总线仍可能异步触发回调向已关闭 channel 发送。
   改为 writer goroutine select on done 退出，不 close channel；
   defer 中等待 writerDone 保证无残余写入。
   顺带补 mockPluginMgr.StopAndUnload（ae42e48 接口变更漏改测试）。

3. GUI camerasue 平台分支
   ffmpeg 参数原硬编码 Linux v4l2(/dev/video0)，Windows 上必然失败。
   现按平台探测：win32=dshow(枚举设备名取第一个视频设备)、
   darwin=avfoundation、linux=v4l2；录像编码 Windows 交给 mp4 muxer 默认。
 2026-08-26 01:25:40 +08:00
JianFeeeee
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