5aaae93367
feat(healthcheck): 内核状态快照报出内核版本号与 ONNX 模型启用状态
...
healthcheck_kernel 此前没有任何「ONNX 模型是否在用」的信息，只报「向量可用/不可用」，
分不清「统一多模态空间已加载」与「退回到词嵌入/TF-IDF 路径」；人格卡要求
「版本以运行时快照为准」，也缺一个可查字段（build.version 早就在，但没人知道）。
- KernelStatus 新增 onnx 段：enabled / provider / dim / fingerprint / modalities / reason。
判据取 Loaded()（provider 真正打开且元数据合法），**不是**「配置里写了 provider」
—— 后者在模型缺失 / 运行时缺失时也为真，报出去就是假绿。
- 未启用时 reason 给**具体原因**：未配置（说明会走回退路径）/ 打开失败的具体错误。
homed 把「配置的 provider 名」与「打开失败原因」透传给 Agent，仅供状态报告。
- ProviderAdapter 新增 Modalities()（可选能力，按接口断言取用，不改公开契约）。
- healthcheck_kernel 的工具描述同步说明它回答这两件事。
**顺带修一个真实 panic**：collectKernelStatus 的 knowledge 是**接口**参数，
(*knowledge.Store)(nil) 塞进接口后 `ks != nil` 仍为真 → 调 List() 直接 panic，
而 healthcheck_kernel 正是走这条路径（panic 发生在工具 goroutine 里）。
GetKernelStatus 改为先按具体指针判空、再赋给接口；并加刻画测试钉住这个成因
（一旦不再 panic 说明参数形状已变，守卫与该测试应同步删除）。
验证：单测 4 例（已启用 / 打开失败 / 未配置 / 未加载）+ 刻画测试；
隔离实例 E2E 7/7：正例 provider=chineseclip → enabled=true、dim=512、模态 2；
反例 provider=nonexistent → enabled=false 且 reason 含具体错误与 provider 名，
真实对话仍通。
2026-09-12 14:56:25 +08:00
46e014a8ca
feat(persona): 首启人格门禁跨通道化 + 内核 persona_set 工具
...
WebUI 首启向导只覆盖 WebUI 这一条通道，而「人格该问一次」是所有通道的事：
走 QQ / CLI / ACP / 邮件来的人永远见不到那个向导，人格就永远是没确认过。
- 门禁移到 buildSystemPrompt（每轮重建 → WebUI/QQ/CLI/ACP/邮件全覆盖），
以 core.internal.persona_initialized 为准：未确认时要求模型主动询问用户
（默认 / 自定义 / 以后再说），确认后该段消失；personaStore 为 nil 时静默关闭。
- 新增内核内置工具 persona_set(mode=default|custom|later[, content])，
落库逻辑与 WebUI 向导**共用 internal/config**（一个实现 + 两个薄入口：
ConfigRegistry 直连 / 插件侧 SettingsAPI），避免两套语义各自漂移。
- AgentConfig 增加 PersonaStore 接口，cmd/homed 用 RegistryPersonaStore 实现。
- 非法输入（未知 mode / custom 空内容）在打标记**之前**拒绝：否则标记置位、
向导被跳过，用户再没机会设。
E2E（隔离实例 + 真实 LLM 往返走 /v1/chat/completions，/var/tmp/persona/e2e.sh）9/9 PASS：
未确认时模型主动询问 → 用户答「用默认的」→ 模型调用 persona_set 落库并置位标记
→ 之后不再追问；反向对照（清标记 + 清会话上下文 + 重启）重新开始询问，
排除了「同一段对话里已问过」这一混淆。
2026-09-12 13:57:06 +08:00
10367b384e
feat(webui): 首启人格向导（默认 / 自定义 / 稍后）+ 一次性标记
...
接续人格配置项化（597f07c）：现在人格是 core.agent.personal_prompt，
本次加上「首启问一次」的界面，之后不再打扰。
后端（GET/POST /api/v1/persona）：
- GET → {initialized, current_prompt, file_override}
未设置时 current_prompt 回落到内置默认模板；存在 personal/personal.md
时报告 file_override（它会覆盖配置项，向导据此提示用户）
- POST → {"mode":"default"|"custom"|"later","content":"…"}
写配置 + 打一次性标记 core.internal.persona_initialized；
custom 返回 restart_required=true（人格在启动时载入）；
「稍后」= 保留当前默认 + 打标记，**绝不阻塞任何流程**
- 空内容的 custom 与未知 mode 一律 400，且**不打标记**（否则向导会被跳过）
前端（dashboard.html）：
- 首启拉一次 /api/v1/persona，未初始化则弹向导（复用一直没人用的 .confirm-* 样式）
- 「自定义…」第一次点击展开文本域并预填当前人格，再次点击才提交（避免误提交）
- 中英双语走既有 __() 机制；保存失败/空内容用 toast 提示
测试：TestPersonaWizardFlow（首启状态、later 打标记不改人格、custom 写入 + 需重启、
空内容与未知 mode 被拒且不打标记）、TestPersonaWizardReportsFileOverride。
E2E（真实实例）：首启 initialized=false → POST later → initialized=true，
config 中标记=1、人格键为默认模板；前端页面含向导函数。
2026-09-12 13:02:18 +08:00
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
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
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
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
f6f92a8a6e
fix(plugins): 修复两处预存缺陷（agentcli 临界区 / localuse 脚本转义）
...
agentcli cleanupLoop：
持锁期间为每个过期终端 go func 调 term.Close()（内部会 Kill 进程并等
<-t.done），临界区被拉长且与 TerminalSession 退出路径交错。改为持锁
只做筛选与摘除，锁外再逐个关闭。
localuse 脚本转义（两处真实 bug）：
1. AppleScript 注入：handleScreensue 只把 `"` 转义为 `\"`，未转义 `\`。
内容结尾的反斜杠会吃掉闭合引号，使后续内容逃逸出字符串字面量。
改为 escapeAppleScriptString：**先转义反斜杠再转义双引号**（顺序
不可颠倒，否则刚插入的反斜杠会被二次转义）。
2. PowerShell 路径被错误加倍反斜杠：handleScreensee 把 Windows 临时
路径的 `\` 写成 `\\`。但 PowerShell 单引号串里反斜杠是普通字符
（转义符是反引号），加倍会让截图保存到错误路径。
新增 psSingleQuote 统一处理，并把 4 处零散的 `ReplaceAll(x,"'","''")`
收敛到该 helper。
2026-09-10 17:56:57 +08:00
687e5655bc
feat(sdk): 多模态贯通插件边界——公开接口、内核桥接与统一输入主干
...
记忆系统在 1.1.0 支持了二进制多媒体节点，但那条链路只对**内核自己**开放：
用户在 qq 发图能落进 CAS、能被记忆引用，而插件调 Commit / DocMemory().Insert
交进来的媒体一律无处安放。原因是三层都断着，且**每一层都不报错**。
## 一、公开 SDK：补上媒体的表达能力（全部新增，无签名变更）
- `Triple` += `SentenceText`、`MediaDigests`
- `Doc` += `MediaDigests`、`Attachments`；新增 `MediaAttachment`
- `TextEvent` += `Attachments`
- `DocMemoryAPI` += `InsertWithMedia`
- `IOInjector` += `InjectInputMedia` / `InjectInputMediaSync` / `InjectInterruptMedia`
- `PluginSDK` 补上一直缺失的 `SetToolBlocks` 包装（接口里有、便捷方法里没有）
`MediaAttachment` 一个类型服务两个方向：给 `Data`+`MIME` 是新内容（CAS 按字节
去重），只给 `Digest` 是引用已有内容。读路径**只回元数据不回字节**——一次检索
可能命中几十份媒体，全塞回去会把跨进程消息撑爆。
媒体注入不能搭 `SetToolBlocks` 的车：那个方法只在工具处理函数内部可用，且媒体
要等下一条 tool message 才到模型手上。插件主动发起一轮带媒体的对话、以及中断
注入，需要自己的签名，且媒体在**本轮**就送到模型。
## 二、内核桥接层：原先在静默裁字段
`internal/sdk/memory_impl.go` 此前只搬自己认识的几个字段，其余丢弃且返回 nil：
- 图记忆丢 `Confidence`/`SubjectType`/`ObjectType`/`SentenceText`，又走 `Commit`
而非 `CommitWithMedia`（不回 sentenceIDs）→ 媒体绑定链 `SentenceText → sentences
→ sentence_id → media_refs` 一步都走不通，插件即便按格式写好标记也永远挂不上；
- 知识库 `Query` 只回 ID/Title/Content，`Insert` 只写这三个；`Remove` 不解引用，
于是那些媒体永久处于「被引用」状态，GC 收不掉、磁盘只增不减
（内核的归档路径 `releaseDocMedia` 做了这一步，插件路径漏了同一步）。
规则改为：**内部结构有的字段一律透传**。标记格式处理作为包级私有辅助留在桥接
层自己手里，但必须与内核 `mediaSummaryForEvent` 字节兼容——两边要能互读对方
写下的标记。
标记插入必须在 `ds.Insert` **之前**（向量索引取 `Summary + " " + Content`，
之后补的标记检索不到），引用绑定必须在**之后**（owner_id 是 Insert 生成的 ID）。
## 三、跨进程链路：不接线就是全体外部插件编译失败
`go test` 直接把这一层拍出来了——`procIO does not implement sdk.IOInjector`。
公开接口加方法后，生成模板不跟上，**每个外部插件都编不过**，是硬失败不是软降级。
六处接线：`protocol.go` 四个 method 常量、`capability.go` 能力归属、
`corehandler.go` 四个分派分支、`proc_core.go` 委托、`proc_main.go.tmpl` 模板侧
实现、以及三个测试替身。
## 四、统一输入主干：把模态从「函数选择」降级为「字段」
`processTextInput` / `processMediaInput` 合并为 `processInput`。这个分叉是历史
产物而非设计：`processTextInput` 本来就处理媒体（`bindEventMedia` +
`mediaSummaryForEvent`，与媒体路径尾部完全相同），`process()` 只看
`stageCtx.Extra["media_blocks"]`、根本不认识 `evt.Type`。模态是输入的**属性**，
不是输入的**种类**。
媒体路径由此获得它一直缺的六项：去重、`no_memory`、通道 `Cleaner`、中断语义、
`_consolidation_` 路由、正确的 `EventRawInput`。
最后一项是个真 bug：媒体路径发布 `"content": evt.Payload`（一个 map），而
`webui/handler.go` 断言 `.(string)` → 断言失败、`content == ""`、提前返回。
**用户发的图从来没出现在 WebUI 聊天记录里。**
`media_blocks` 同时接受 `[]agentAPI.ContentBlock` 与 `[]pubsdk.ContentBlock`：
字段一致但 Go 不自动转换，只认一种的后果是另一种被静默丢弃。
## 五、模型可调用的三个工具
`memory_commit` 的 `sentence_text` **从未暴露给模型**，而它是绑定链上的必经环节；
连同 `media_digests` 一起补进 JSON schema 与工具文档。`doc_commit` 加
`media_digests`。`doc_query` 把关联媒体单独一行附在结果末尾（正文按 2000 字截断，
标记通常就在尾部）。
标记由**内核**生成而非插件/模型拼装：要求调用方知道格式，等于让一个拼写错误
静默切断引用绑定，而全链路无人报错。
## 六、WebUI 上传走真实媒体链路
图片/音频读回字节拼 data URL 注入 `media_blocks`（8MB 上限，超限退回按路径处理）。
此前只注入一句「文件已保存到 <路径>」，指望模型自己调 `files_read`——但那返回
文本，图片字节对模型永远不可见。附件类型识别扩展到 audio 并在缺 Content-Type
时按扩展名兜底（判错不只是卡片样式问题，图片被当普通文件就进不了视觉链路）。
## 测试
- `internal/sdk/memory_impl_test.go`（12 例，此前该包**没有任何测试文件**）
- `internal/agent/core/inputunify_test.go`（统一主干 + 双静态类型 + 三工具媒体）
- `third_party/homeagent-sdk/sdk/stress_test.go`（13 例并发压测）
压测抓到两处**真**竞态（不是理论风险）：`PluginSDK` 的 API 字段与 `autoRestart`
无锁，而写方（内核注入 API、插件 `SetAutoRestart`）与读方（插件后台 goroutine
注入、内核 registry 读 `AutoRestart`）天然跨 goroutine。加 `apiMu` 修掉；约定
只在持锁期间取字段值，取完即释放再调用——持锁调用会把 `InjectInputSync` 这类
阻塞到 agent 回复（可达数分钟）的方法与 `SetIOInjector` 串起来，让插件重载卡死。
测试还抓出两个自身缺陷：`bindDocMedia` 把同一份媒体数两次（`AddRef` 幂等所以表
是对的，但日志说「绑定 2 个」而实际 1 条——误导后续排查），以及用单字符实体名
时 `validEntityName` 静默跳过、`Commit` 返回 nil 却什么都没写。
存量插件不需要改一行也不需要重编：新增方法由插件调用、内核实现，不调就不受影响。
17 个 example 插件源码零改动通过类型检查。
2026-09-06 09:51:31 +08:00
968b01f26e
fix(plugins): 修复隔离全量测试暴露的两处数据竞争
...
-go test ./... -race 全仓复验暴露的 7 处 race、5 个失败测试，全部定位。
两处独立缺陷，互不相关。
## 缺陷一（remotedevice，8 处 race）：连接写无串行化
WARNING: DATA RACE
Read at 0x... by goroutine 28:
bufio.(*Writer).Available() / writeFrameHeader / PushData
Previous write at 0x... by goroutine 27:
bufio.(*Writer).Flush() / writeFrame / handleWS
同一连接的 bufio.Writer 被两条并发路径写：
- handleWS 主循环：读到设备帧后回写 hello_ack/bind_ack/pong
- PushJSON/PushData：agent→设备的下发路径，可来自任意 goroutine
bufio.Writer 不是线程安全的。不加锁就在 WriteByte/Flush 上撞——这
不是理论风险，TestWSPushDataAudio 的异步 PushData 与 handleWS 的
hello_ack 回写并发时被 -race 稳定抓到。
修法：wconn 增加 wmu（sync.Mutex），PushJSON/PushData 拿锁后整条
下发（start + N 个 chunk + end）持锁——设备侧按协议串行聚合，中途
被插帧会破坏协议顺序。handleWS 的 hello_ack/bind_ack/pong 也改走
同一把锁（wsWriteLocked 封装，避免调用方绕过）。设备已离线时不回写。
关键点：不能只锁 Push* 不锁 handleWS——那只是把竞争挪了个位置。
## 缺陷二（agentcli，1 处 race）：共享读缓冲被并发读写
WARNING: DATA RACE
Write at 0x... by goroutine 26:
os.File.Read / (*linuxPty).Read / reader
Previous read at 0x... by goroutine 25:
runtime.slicecopy / readLoop
readLoop 创建 buf := make([]byte, ReadBufSize) 传给 reader goroutine
（t.session.Read(buf) 持续覆写），自己又在读到结果后
copy(data, buf[:r.n])——同一缓冲被读写并发。Go 的 pty 读走 OS 层
fd，专门在 reader 写下一段时读，跑 -race 稳定复现。
修法：readResult 携带 data field，reader 每次读完后把数据复制进自己
分配的切片再随结果传递，读取与拷贝之间不再共享任何可变状态。原 buf
保留（仍由 reader 独享用于 OS 读），readLoop 不再从其中 copy。
## 验证
- 两个插件包 -race -count=2 全过
- 全仓 go build / go vet / go test 通过
- 全仓 go test ./... -race：32 包全过，0 DATA RACE，0 FAIL
- SDK 冻结 diff = 0
其中 remotedevice 的 TestScreenseeEndToEnd / TestComputeruseEndToEnd
/ TestClipboardEndToEnd 原本因 race 挂，修后恢复全绿。
2026-09-05 07:26:10 +08:00
98dcb2556c
fix(test): 崩溃隔离测试误杀同机生产插件，且断言无效
...
## 现象
生产 homed 的 editdoc 子进程从 9-03 起被 SIGKILL 9 次，间隔完全不规律
（126~485 分钟），全部发生在无工具调用的空闲期。查过 OOM（dmesg/
journalctl -k/cgroup oom_kill 全为 0）、systemd 内存限制（MemoryMax=
infinity）、cron/timer、内核自身的 StopAll 路径、agent 执行过的 cmd_run
命令，以及 Pdeathsig 绑创建线程的可能——全部排除。
## 真因：测试杀了生产的进程
用 ftrace 的 signal_generate tracepoint 挂监视器后抓到发送者 cmdline：
/tmp/go-build.../plugins.test -test.run=TestRealPlugin_CrashDoesNotKillKernel
findPluginPID 用**全系统** `pgrep -f plugin.bin`，然后只比"exe 路径含
editdoc"。生产实例的 /home/newqqagent/plugins/editdoc/plugin.bin 也满足
这个条件，谁先被 pgrep 列出来就杀谁。9 次 kill 全部落在有人跑 go test
的时段——18:18:30 那次正是一轮 `go test ./... -race` 的窗口。
之前几轮排查一直在生产实例内部找原因，方向从一开始就错了：杀手在仓库里。
## 更严重的是这个测试本身无效
旧断言是"SIGKILL 之后内核仍存活"。可内核本来就活着——即使信号发错了
对象（杀了生产实例的插件），测试内核的插件压根没死，断言照样通过。
**它在测一件没发生的事**，同时把生产环境打坏了，而绿色的测试结果掩盖了
这一切。这也是它能连续 9 次造成生产故障却从没被注意到的原因。
## 修法
findPluginPID 增加 root 硬约束：/proc/<pid>/exe 必须以测试自己的 plgDir
为前缀，且是目标插件，两道条件同时成立才算命中。root 为空直接 t.Fatal
——这不是可选过滤器，是防误杀的前提。
- 用 exe 而非 cmdline：cmdline 可被进程自行改写，exe 符链由内核维护。
- root 先过 EvalSymlinks：/tmp 在部分发行版上是符链，不归一化会让前缀
比较永远不命中，退化成静默 Skip（那样测试就白跑了）。
断言改成两步：先轮询确认目标进程真的退出（3s 上限），再验内核未被连带。
两步都成立才能证明隔离生效。
## 验证
修复后跑 TestRealPlugin_CrashDoesNotKillKernel：
- 杀的是 pid=3448366，exe 在 /tmp/hc_integration_3823918128/plugins 下 ✓
- 生产 editdoc pid 测试前后均为 3362892，存活时长连续 ✓
- 四个 TestRealPlugin_* 全部 PASS
2026-09-04 21:44:05 +08:00
09071dc235
fix(multimodal): 修多模态假成功 + 落地视觉回退链 + see_video 帧数语义
...
## 起因
生产盲测：模型调 multimodal_see_picture 后声称看到了图，实际一个字
都没收到。工具却返回「[已将图片注入后续对话]」。
链路：core.llm.model=AUTO → llmsproxy 按优先级选 big-pickle(prio=100)
→ 转 opencode zen。llmsproxy 的 opencode.lua 明写着：
-- zen 上游 schema 只接受 text content part（无视觉/音频能力）
if part.type ~= nil and part.type ~= "text" then -- 丢弃
判据：256x256 纯红 PNG，带图与不带图的 prompt_tokens 都是 256。
图片贡献零 token，即根本没进上游。
内核序列化与注入链本身是对的（Message.MarshalJSON 正确产出 content
数组，SetToolBlocks → IOManager → ConsumeToolBlocks → toolMsg.Blocks
全通）。缺的是「主模型能否消费这些块」这一判断——内核此前完全没有
多模态能力的概念（grep supportsVision|multimodal 在 agent/ 零命中）。
这与 v1.0.0 修的 output_send 假成功同类：告诉调用方成功而实际未送达。
## 1. 能力声明
新增 core.llm.sources.<name>.vision / .audio（走既有 sourceFieldDefs，
WebUI 配置页自动出现），types.LLMSource 与 api.BaseConfig 同步加字段。
新增 agentAPI.ModalProvider 接口 + ProviderSupportsVision/Audio 判定：
未实现该接口的 provider 一律按不支持处理。保守侧是刻意的——宁可多走
一次文字回退，也不能把图默默扔给会剥掉它的上游。
为何是声明而非探测：探测需额外真实调用且结果不稳定（取决于 AUTO 当次
路由到哪）；而 200 响应 + 相同 token 数从响应侧无法区分「看到了但没
内容」和「被剥掉了」。
## 2. 回退链（modalfallback.go）
实现了 config/registry.go 里注册但从未被读取的 image/audio
fallback_provider + fallback_model（此前 0 处读取点）。
prepareToolBlocks 在 process.go 注入前判定：能直视就原样透传；不能就
调声明了该能力的源转写成文字，带 [由 X 转写，非当前模型直接感知] 标注。
几处刻意的设计：
- 逐模态判定，不一刀切。很多视觉模型能看图但听不到音频，全部降级会
白白把可直视的图变成二手描述
- 混合场景下转写文字作为 text 块并入 native，两部分同时到达模型
- 配置指向未声明能力的源时拒绝并继续找——照用只会重演静默剥离
- 未配 fallback_provider 但某源声明了 vision 时自动扫出来用；静默失败
比多找一个能用的源更糟
- 空回复算失败。上游剥掉媒体后模型往往回「我没看到图片」或空串，两种
都说明回退链也没真看到
- 多媒体块按模态合包为一次请求（见下）
## 3. 批量合包（生产实测驱动的返工）
首版逐块调用，生产 see_video 6 帧实测：4 帧里 3 帧超时，整轮 363 秒。
改为按模态合包一次请求后同一用例 131 秒、6/6 成功。
顺带把 modalFallbackTimeout 从 90s 提到 180s：生产经网关转
claude-opus-5 看一张 400x400 图要 ~81s，90s 贴着上限。
多张时 detail 默认 low 控体积，单张用 high 看细节；插件显式给了
detail 则尊重它。
## 4. see_video 帧数语义
fps=1/N 是频率（每 N 秒一帧）不是数量。20s 视频实测：
frames=4 → 5 帧、frames=10 → 2 帧、frames=1 → 20 帧，要得越多拿得越少；
长视频下 frames=4 会产出 时长/4 帧，靠 i>=9 的 break 兜着才没炸上下文，
而那个 break 用的是 ReadDir 索引，跳过条目后与实际帧数错位。
改为 ffprobe 取时长 → fps=N/时长 + -frames:v N 硬封顶。
0.4s/3s/20s/120s × frames=1/2/4/7/10 全部精确。
极短视频的坑：fps=1 在 0.4s 素材上产出 0 帧（不足一秒抽不出），所以
时长探测失败时不能退化成 fps=1，改为不传 -vf 只靠 -frames:v。
## 验证
- modalfallback_test.go 14 例：直视透传 / 回退转写 / 无源如实报告 /
未实现接口按不支持 / 混合模态拆分 / 空回复算失败 / 块数上限 /
多图合一次调用 / detail 策略 / 拒绝未声明能力的源 / 未配置时自动扫源
- go test ./... 全绿，go vet 无警告
- 生产盲测（答案预先封存、生成时不读）：随机三色带 → 模型答
「紫、蓝、红」，与封存答案完全一致
- 负向验证：拿掉回退源后模型如实回答「没看到图片内容」并引用工具返回
的配置提示，且主动纠正了上一轮的答案
- 生产 see_video 6 帧：单次转写，模型正确描述测试图卡的计数器递增与
彩虹带滚动
2026-09-04 06:25:51 +08:00
f91b27aedb
fix: WebUI 版本显示 + Windows 交叉编译 + 发布脚本三处回归
...
## WebUI 版本链路修复
问题：handler.go:949 报的是 sdk.SDKVersion，那条链最终指向
SDK 仓 meta.Version 的硬编码值，与 -ldflags 注入的内核版本
完全不相交。构建时间、commit hash 全部丢失。
dashboard.html 兜底值是 '0.1.0'——碰巧版本号相等时不显眼，
一旦不等就报错。
修复：
- KernelStatus 新增 BuildStatus 字段（Version/Commit/BuildTime/SDKCompatible/KernelName）
取自 internal/meta（-ldflags 注入点），与接口冻结无关（KernelStatus 只在 internal/sdk）
- /api/v1/status 改用 meta.Version，另加 sdk_version 字段暴露 SDK 版本
- dashboard.html 概览卡显示 HomeAgent vX.Y.Z + commit/日期/SDK 兼容版本，
去掉 || '0.1.0' 误导性兜底
## Windows 交叉编译修复
问题：internal/plugin/dynamic_proc_windows.go（Part 1 的桩，610e9d0）只定义了
tryLoadProc，但平台中立的 registry.go 还在调 loadProc / closeProcHost——这两个
函数只在 dynamic_proc_unix.go 里。Windows 下整个 homed 从 Part 1 起编译不过。
plan.md §12.5 声称「Windows 只做了交叉编译，无真机验证」——实际是连编译都没通过。
修复：dynamic_proc_unix.go / dynamic_proc_windows.go 合并为平台中立的
dynamic_proc.go（文件内无任何平台专属调用，proc 包内部通过
shmalloc_* / evtfd_* / shmpass_* / procattr_* 各自带构建标签处理差异）。
## 发布脚本三处回归修复
deploy/packaging/build.sh（从 package/build.sh 移到 deploy/packaging/ 后）：
1. PROJECT_ROOT 少一层目录（.. → ../..），产物落进 deploy/build/ 而非根目录
2. initconfig 从未被构建，但 installer.nsi 和 package-linux.sh 都引用它
3. GO 兜底路径指向 /home/jianf/go1.26.5（陈旧硬编码）改为 command -v go
4. electron-builder --config package.json 校验整个文件导致 devDependencies 被判为 unknown
property，去掉 --config 让它从 build 键读配置
deploy/packaging/package-linux.sh：
1. build_go() 补上 initconfig 构建步骤
2. GO 兜底路径同步修复
知识库 3 条重写 + 1 条新增：
- homeagent_identity：v0.9.0 C ABI → v1.0.0 子进程
- homeagent_architecture：全篇重写为子进程架构（三面通信、Supervisor 台账、
崩溃自愈、权限三道闸）
- homeagent_recent_updates：在 v0.9.0 前插入 v1.0.0 主线摘要
- changelog_v1.0.0（新建）：6 类缺陷消除、架构、实测、已知限制、迁移指引
2026-09-03 15:38:31 +08:00
02cc74ce11
fix(proc): 子进程崩溃自愈 + 集中台账 + 注册面摘除
...
根因：子进程插件被 kill 后，内核只发了一个无人订阅的事件，
工具/stage handler/IO 通道全留在注册表里指向死进程，
模型继续调用只吃 ErrProcessExited，没有任何路径把插件拉回来。
## 四层修复
### 1. 专职 waitLoop（进程收割）
- 每个子进程配一根 waitLoop goroutine，是 cmd.Wait() 的唯一调用点
- 不再依赖 stdout EOF 判定死亡（孙子进程继承 stdout 时 EOF 永不到来）
- 手工 os.Pipe 替代 cmd.StdinPipe/StdoutPipe，避免 waitLoop 与
os/exec 的内部关闭竞争
- host.go: Host.Supervisor()，Host.Close() 先 StopAll 再拆段
### 2. 集中台账 Supervisor
- proc/supervisor.go: 插件 Spawn 握手成功即 track，进程退出即 untrack
- StopAll: 并发发 plugin.stop 走优雅路径，到期仍在的一律 Kill
- 关停后才完成握手的进程被立即结束，不会活过内核
- 消除「孤儿进程持共享段映射 → SIGBUS」的隐患
### 3. 注册面摘除（detachPlugin）
- 新增 StageHost.UnregisterPluginStages：摘除指定插件的全部 stage handler
- 新增 Registry.pluginChannels 台账：记录每个插件注册的 IO 通道
- 三条路径统一走 detachPlugin：Disable / ReloadOne / RemovePlugin
- StopAndUnload 漏了 IO 通道也一并补上
### 4. 自动重启
- onProcCrash 从「只发事件」改为「摘注册面 → 从注册表移除 → 异步排重启」
- scheduleProcRestart: 窗口 5 分钟内最多 3 次，线性退避 1s/2s/3s
- 超限停手留日志；重启前复核是否已被 Disable 或被其他路径加载
- 崩溃计数窗口过期自动归零
### 5. 主动停止 vs 崩溃的区分
- proc.Plugin 新增 stopping 标志：Stop()/Close() 里 Set(true)
- handleExit 读 stopping 标志，主动停止不上报 onCrash
- 防止重载/禁用/卸载被误判为崩溃触发多余重启
### 6. Linux Pdeathsig 兜底
- procattr_linux.go: SysProcAttr.Pdeathsig = SIGKILL
- 兜 homed 自身被 SIGKILL/OOM 时子进程变孤儿的场景
- macOS/Windows 无等价物，空实现
### 7. pluginmgr 升级
- PluginManager 接口新增 PluginRuntime / ListPluginRuntimes
- plugin_list 输出运行态：loaded / alive / pid / crash_count / channel
- 新增 plugin_status: 全量运行期快照 + dead/unhealthy 汇总
- 新增 plugin_restart: 无条件重启单个插件（plgreload 不动未改二进制的插件）
### 测试
- process_test.go: 3 例（grandchild stdout 感知 / Supervisor track-untrack /
StopAll 无孤儿）
- crash_recovery_test.go: 8 例（detach 三项齐全 / 通道重注册 / 崩溃不阻塞 /
退避阈值 / 窗口过期 / 关停中跳过 / PluginRuntime 通道识别）
- stages_plugin_test.go: 4 例（stage 按插件摘除 / 空 stage 清理 / 空名 no-op /
工具+stage 双摘后可重新注册同名）
2026-09-03 12:37:58 +08:00
2ebdb9a5b7
plugin: 权限梯度显式化（Part 6.4）
...
迁移前，「外部插件拿不到 Selftest/Supervisor/Tracker」是 C ABI 表达能力的
**意外产物**——C 结构体不好传函数指针，这些能力自然到不了插件侧。那是运气
不是策略：任何人给 dispatch 加个 case 就能捅穿。
现在变成显式声明并强制，分三道闸：
1. **类型层**（proc_core.go，Part 6.2 已落地）：procCore 用命名字段持有
内核 SDK 而非嵌入，未在收窄面写出的方法编译期就不存在。
2. **能力集**（新增 capability.go）：54 个 plugin→kernel method 划入 11 个
capability 组，manifest 未声明的组被拒。
3. **RPC 边界**（corehandler.Handle 入口）：被拒时返回**明确错误**而非
静默忽略。
第 3 条针对一类真实故障：C ABI 时代 case 23/24（事件订阅）是空实现，
返回成功但永远收不到事件（§1.3 的「给不了」而非「不给」），插件作者无从得知。
错误消息含四要素：哪个插件、哪个调用、缺什么能力、在哪声明。
## 能力划分的两个判断
**粒度按能力域而非单 method**。逐 method 授权看似更精细，但插件作者要在
manifest 里列 60 个名字，且内核每加 method 所有 manifest 都得改。
**空声明 = 不受限，而非「只有 core」**。17 个存量插件的 plugin.json 都没有
capabilities 字段。若空声明当作最小权限，它们会全部失去 IO 注入、记忆读写
而**静默降级**——违反「外部插件零改动」的硬约束。收紧的路径是让插件显式
声明，而不是默默拒绝老插件。
## core 与受限能力的边界
core（无需声明，始终可用）：注册自身工具/阶段/通道/API、读写**自己的**配置、
共享段锁仲裁、握手、autoRestart 自述、setToolBlocks。没有这些插件无法工作。
受限（需声明）：io / memory / doc_memory / knowledge / text_memory / llm /
social / events / plugin_mgr / settings_cross。
settings 刻意拆成两级：读写自己的配置属 core（正常工作所需），读写**其他插件**
配置或**内核核心**配置属 settings_cross（能改别人/内核的行为）。
## withheldCapabilities：让「不给」可见
10 项刻意不提供的内核内部机制列在表里并附理由。它们没有对应 method 常量——
不是忘了加，是决定不加。列表存在本身就是「这是策略而非疏漏」的证据，
读代码的人能看到边界在哪，而不是从「protocol.go 里没有」这个负面事实去推断。
## 测试
proc 包 10 项：
- AllMethodsClassified：**最重要的一项**。漏登记的 method 会按 CapCore 放行，
等于绕过整套检查。新增 method 忘登记时当场报出。
- EmptyDeclarationIsUnrestricted / DeclaredSetRestrictsOthers / CoreAlwaysAllowed
- SettingsScopeSeparation：自身配置 vs 跨插件配置的归属
- DeniedErrorIsActionable：错误消息四要素
- HandleEnforcesAtRPCBoundary：被拒的调用不进 switch
- WithheldListIsDocumented：每项都有理由，且不被任何 method 暴露
- UnknownMethodFallsThrough：未知 method 报「未知」而非「权限被拒」，
否则作者会以为是漏声明能力
写这个测试时踩到自己的坑：第一版用子串匹配查 withheld 泄漏，"Tool" 匹配到
tool.register 和 io.setToolBlocks 误报——那两个是合法开放的（注册自己的工具）。
改成前缀 + unregister 关键字匹配，withheld 项也改名带 API 后缀以示区分。
internal/plugins 2 项接线验证：
- RestrictedPluginStillLoads：只声明 io 的 weather 仍能加载并注册工具
（它在 Start 里读 Settings，属 core）
- LegacyManifestUnrestricted：无 capabilities 字段的存量插件正常加载
真实 homed 实测：
[plugin] weather-capped 声明能力: [io]
[plugin] weather-capped: 经 proc 通道加载（子进程）
registering tool: weather-capped_current / _forecast / _set_location
验证：go build ./... 通过；go test ./... 全仓无失败；
go test -race ./internal/plugin/... 全绿；go vet 干净。
Ref: docs/zh/架构迁移评估.md §3.8、docs/zh/plugin-migration-plan.md Part 6.4
2026-09-02 21:27:13 +08:00
1d7f011e5d
plugin: 17 插件全量重编 + 端到端冒烟验证（Part 6.3）
...
## 17 个插件源码零改动，全部重编为 plugin.bin
16 个 × 3 平台（linux/darwin/windows），qq 1 平台（plg.json 自己声明
bundle:false）。luademo 走 Lua 解释器不适用。
git status example/ 无输出 —— 这是「业务代码零改动」的硬证据。
批 3 那些预估高风险的插件（qq 2686 行双向通道、browser 12 工具 +
InjectInterruptText、a2a/acp 的 InjectInputSync 同步注入）一次全过，
因为它们只碰公开 SDK 合同面，而合同面在 Part 2 已 51 个 method 全量平移。
唯一一次失败与迁移无关：rss 的 github.com/mmcdole/gofeed 不在本地模块
缓存且 proxy.golang.org 不通，换 GOPROXY=https://goproxy.cn 后通过。
## 真实 homed 加载验证
15 个外部插件全部经 proc 通道建链（protocol=1 sdk=0.9.2，各自独立 PID），
31 个插件 loaded（15 外部 + 16 内置）。
ai_image / files 未走 proc 通道：同名内置插件优先（工厂编译期注册），
外部插件被遮蔽。这是既有行为，与迁移无关。
事件环与共享段均正常创建，且共享段是**一块** 256KB 服务全部 15 个插件。
## 冒烟测试 4 项（internal/plugins/real_plugin_smoke_test.go）
用真实 example 产物而非 testdata 假插件；manifest 刻意写 "entry":"plugin.so"
验证工具链与内核都已不看 entry 值。未重编时 skip 而非 fail。
- ToolInvokeRoundTrip：工具真实调用往返（此前只验证到"注册"）。
weather_current 返回结构化参数校验错误——这恰是链路通的证据。
- StageRewriteTakesEffect：sanitizer 清洗 ANSI 序列，改写经共享段回到
内核 StageContext
- MultiPluginShareOneSegment：sanitizer + weather 并发，清洗结果不被覆盖
- CrashDoesNotKillKernel：SIGKILL 插件进程后 homed 存活、17 插件仍在
（对比 C ABI 下插件 panic 直接带崩 homed，§1.2 现网已发生）
## 开销实测与基线偏差
15 个插件进程 RSS=88.0MB PSS=87.9MB 线程=82，均摊 5.87MB / 5.5 线程。
RSS 88MB vs 实验 5 基线 29.1MB **不是回归，是基线不可比**：实验 5 用
2.68MB 最小插件，真实插件 3.1~14.8MB。可比的结构性指标：
- 均摊线程 5.5 vs 4.9 —— 同量级，无线程膨胀
- PSS/RSS 99.9% vs 44% —— **明显差于基线**
第二项是真实发现：基线里 PSS 远低于 RSS 说明 Go runtime 只读代码页在
进程间共享；实测几乎不共享，因为 15 个插件是 15 个不同的二进制，没有
共同物理页可映射。这是「每插件独立二进制」的固有代价，意味着实际内存
开销高于 §4.3 的乐观估计。压这一项的方向是共享 launcher 二进制。
## 工具脚本入 experiments/19-migration-verify
scripts/ 被 .gitignore 排除，故放到已跟踪的 experiments 目录下，
与 01~18 的可复跑实验并列。
measure-plugin-overhead.sh 第一版有统计口径 bug：RSS 读 status 的 VmRSS、
PSS 读 smaps_rollup 的 Pss，输出 PSS(87.9MB) > RSS(69.1MB) —— 物理上不可能。
两者对共享内存段计入方式不同（smaps 的 Rss 含 Pss_Shmem）。已统一从
smaps_rollup 读。另修 bc 不可用导致 MB 全显示 0.0（改用 awk）。
Ref: docs/zh/plugin-migration-plan.md Part 6.3、docs/zh/架构迁移评估.md §4.3
2026-09-02 20:20:25 +08:00
b20121f703
plugin: 删除 C ABI 通道（Part 6.2 完成，-3198 行）
...
外部插件统一走子进程 + stdio RPC，三套独立 ABI 实现收敛为单一 RPC 实现。
用户决策：彻底舍弃 .so 能力，不保留双通道回退。
## 删除清单
internal/plugin/cabi/ 1156 行（loader.go/loader.c/types.go/output_test.go）
internal/plugin/dynamic_dll_windows.go 272 行（§9.2 记录的能力退化实现）
internal/plugin/dynamic_loader_unix.go 79 行（唯一 cabi 引用点）
internal/plugin/dynamic_dll_test.go 32 行
internal/plugin/dynamic_dll_stub.go 11 行
internal/plugin/dynamic_loader_windows.go 11 行
internal/plugin/bridge_e2e_test.go （测的是 cabi 路径）
third_party/.../plugindev/templates.go 1296 行（取消跟踪，SDK 仓才是权威副本）
dynamic.go：entryCABI 通道删除，soEntry/dllEntry 常量删除。
registry.go：tryDynamic 探测顺序从 .so → .dll → .lua 变成 proc → lua。
## 旧 .so 给明确错误，不静默跳过
静默跳过会让「插件目录在但没加载」看起来像配置问题，而实际原因是需要
用新版 plugindev 重编。故保留 legacyCABIEntries 表专门用于识别残留：
plugin legacy: 检测到旧 C ABI 产物（plugin.so/.dll/.dylib）。
外部插件已改为子进程模式，请用新版 plugindev 重编产出 plugin.bin
（业务代码无需修改）
错误消息里「业务代码无需修改」这句是有测试守着的——迁移的核心承诺就是它。
## pluginmgr 安装逻辑跟进 bundle 命名
子进程模式下各平台产物统一叫 plugin.bin（进程边界即 ABI 边界），故 zip 内
按平台加后缀 plugin.bin.<goos>.<goarch>，解包时挑当前平台那一份重命名。
platformBinary 改为按 runtime.GOOS+GOARCH 生成条目名；platformBinaries 固定表
换成 isPlatformBinary 前缀判断（平台组合会增长：linux/arm64、darwin/arm64…，
按前缀判断无需维护清单）。
新增 chmod 0755：zip 保留了原权限位，但经某些工具链/传输后可能丢失，
内核加载时会因缺执行位报错。提前补上比事后让用户 chmod 更好。
## 测试
entry_dispatch_test.go 重写（12 项）：
- classifyEntry 对 .so/.dll/.dylib 现在返回 unknown
- LegacyManifestFallsBackToProbe：存量插件 manifest 仍写 "plugin.so"
（17 个插件没人去改），须靠目录探测找到 plugin.bin —— 这是
「外部插件零改动」的直接后果
- LegacyCABIGivesActionableError：错误消息须含 plugindev / plugin.bin / 业务代码
- PluginEntryHash_IgnoresLegacyCABI：.so 不参与 hash（内核已不认它）
upgrade_test.go 的 .hmap 构造改用 plugin.bin。
验证：go build ./... 通过；go test ./... 全仓无失败；
go test -race ./internal/plugin/... 全绿；三平台构建通过。
Ref: docs/zh/架构迁移评估.md §3.1/§9.2、docs/zh/plugin-migration-plan.md Part 6
2026-09-02 19:26:40 +08:00
3de6b0426f
revert(webui): 移除 chat/history 的 lean 裁剪模式
...
工具调用详情（args/result）与 reasoning_content 是排查问题和还原上下文的
关键信息，不应裁剪下发。瘦身只保留分页一条路径（limit/before 控制条数）。
- 删除 lean 查询参数与 leanChatMsgs()
- 删除 ChatToolCall.Truncated 字段
- 分页仍生效：limit=40 首屏 1287.9KB → 48.5KB，且 tool_calls args/result
与 reasoning_content 完整下发
2026-08-28 23:38:11 +08:00
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
5fccc31afc
fix(plugin): DisablePlugin 禁止禁用未安装插件，防止脏写 disabled_plugins
...
问题：POST /api/v1/plugins/<name>/disable 对不存在的插件也会把它写进
disabled_plugins 表（registry.go DisablePlugin 无条件 AddDisabledPlugin），
产生脏数据堆积，且同名插件日后真实安装会被误判为已禁用。
修复：
- registry.go 新增 pluginInstalled(name)：已加载 / 已注册工厂(内置) / 插件目录存在，
任一命中视为已安装
- DisablePlugin 开头校验：未安装返回 'plugin X not installed'，不写 disabled_plugins
- webui handler：未安装→404，已禁用→409（原都返回500）；enable 失败含'failed'→404
- 新增 registry_disable_test.go：覆盖未安装拒绝/内置判定/目录存在判定/普通文件不算
本机端到端验证：disable 不存在插件返回404且表无脏数据；真实插件 disable/enable 正常
2026-08-27 23:29:49 +08:00
2564e53342
feat(webui): 请求IP日志记录中间件
...
- clientIP(): 提取真实客户端IP，优先 X-Forwarded-For(取第一跳) / X-Real-IP，回退 RemoteAddr
- logged(): 最外层中间件，覆盖全部路由，记录方法/路径/IP/认证方式/状态码/耗时
- 认证方式判定: api-key(X-API-Key/Bearer) / session(cookie) / none
- SSE长连接(/chat/events)启动即记，不阻塞等待完成
- statusWriter 捕获响应状态码，支持 Flush/Hijack 透传
- 用于排查'谁调用了什么接口'（如插件禁用等变更操作）
2026-08-27 23:04:48 +08:00
4def5e9ed4
fix(webui): SSE消息同步不及时 + 后端缓冲加固
...
handler.go:
- writeCh 512→2048，新增 sendSSE() 函数（100ms短超时重试替代立即丢弃）
- After(id) 为空时发送 sync_required 事件通知前端补拉历史
- 批量 flush 阈值 64→128
dashboard.html:
- 新增 syncChatFromHistory()：增量同步，仅追加新消息DOM节点，不重建已有消息→无闪烁
- 监听 sync_required 事件触发增量补拉
- SSE onerror 立即 close 阻止双连接竞态，2s后手动重连（原5s）
- init 顺序：先 loadChatHistory 再 connectSSE（避免事件与历史加载竞态）
- 30s轮询兜底（补偿SSE断连窗口期丢失的跨渠道消息）
2026-08-27 11:10:53 +08:00
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
b777322b95
feat(multimodal): 内置多模态感知插件 + process.go 原生支持 tool message 多模态块
...
【新插件 internal/plugins/multimodal】
- see_picture(path): 读取本地图片/URL，base64 注入 image_url block，
模型在下一轮 LLM 请求的 tool message 里直接看到图（1024×1024 图约 8500 token）。
自动识别 MIME，限 3MB 防爆 context。
- see_video(path, frames): ffmpeg 提取关键帧，多帧作为 image_url block 注入。
默认 4 帧，最大 10 帧，每帧限 2MB。
- listen(path): 读取音频文件，转为 audio_url block 注入，支持 mp3/wav/ogg/m4a。
限 5MB。
【内核多模态 tool message 支持】
- agent/api 新增 ToolOutput 类型（为后续 handler 直接返回 blocks 预留）
- SDK 公共层新增 ContentBlock/ImageURL/AudioURL（OpenAI 多模态格式）
- IOManager 新增 SetToolBlocks/ConsumeToolBlocks（interface{} 避免循环依赖）
- PluginSDK.SetToolBlocks(blocks) 插件工具调用后注入 blocks
- ioAdapter 桥接 IOInjector.SetToolBlocks
- process.go 工具执行后消费 pending blocks → 追加到 tool message 的 Blocks 字段
→ MarshalJSON 输出 content 数组格式 → LLM 看到图/音频
【验证】
multimodal_see_picture 注入 1024×1024 PNG 后 llmsproxy 统计：
prompt_tokens=44407（含 ~8500 image token），模型正确描述了图片内容。
2026-08-27 08:39:21 +08:00
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
a82b5b1626
fix(webui): /files/ /uploads/ 静态路由接受 X-API-Key 鉴权
...
requireWeb 此前只认 cookie session，ArkTS/GUI 等 API key 客户端
加载 agent 输出的附件 URL（/files/xxx、/uploads/xxx）一律 302 到
/login。现 requireWeb 先校验 validAPIKey 放行非浏览器客户端；
无凭证仍 302 登录页，行为不变。
handleFiles/handleUploads 已有严格防穿越（拒 / \ ..），暴露给
key 客户端安全面可控。
端到端验证：X-API-Key 访问 files/uploads 均 200，无凭证 302。
2026-08-26 18:54:26 +08:00
2d5d246606
fix(webui): SSE writer 批量合并 flush 修复流式 delta 丢包延迟
...
【根因】SSE writeCh 缓冲仅 64 且 writer 每条 delta 单独 flush。
reasoning/content 增量是高频小包（单轮 200+ 条），socket
写慢时 writeCh 迅速填满，delta 大量 DROPPED——浏览器收不到
逐 token 增量，只能等最终 agent_output 整段到达，体感明显延迟。
实测一轮 16s 纯文本回复：content_delta DROPPED 202 次、
reasoning_delta DROPPED 345 次，前端全程无流式渲染。
【修复】
- writeCh 缓冲 64 → 512
- writer 加 16ms 批量合并窗口：窗口内收集的增量一次性 flush，
或满 64 条立即 flush；done 退出前 flush 残留。
flush 次数从 N 降到约 N/64，socket 写压力骤降。
修复后实测 0 DROPPED，delta 全部实时送达前端。
2026-08-26 17:59:33 +08:00
ddef1956b5
fix(agent): 流式并行 tool_call 按 JSON index 分桶，修复空参数调用
...
【根因】内核流式解析层丢弃了上游 SSE 分片的 OpenAI index 字段：
- openAIToolCall 结构体无 index 字段，JSON 解析即丢
- homed 的 openai.lua 转换为扁平结构时同样未透传 index
- accumulateStream 退而用 Go range slice 序号做累积桶 key，
但每个 SSE chunk 只含一个 tool_call 元素，序号恒为 0
于是并行多工具调用（index=0,1,2,3）的所有分片全部写入同一个桶：
name 相互覆盖、args 碎片混拼成非法 JSON → parseToolArgsJSON
失败返回空 map → 工具以空参数被调用（spawn_child 报'请提供 task'、
cmd_run 报'command is required'等），agent 只能串行重试自愈。
单工具场景只有一个 index 无污染，故简单请求一直正常；
pi 直连同一 llmsproxy 正常（其实现标准按 index 累积）。
【修复】
- ToolCall 增加 StreamIndex（json:stream_index），openAIToolCall
解析上游 index 并透传；openai.lua 输出 stream_index 字段
- accumulateStream 以 tc.StreamIndex 为累积 key
- flushToolCall 区分三种空参：未收到分片/碎片非合法 JSON/合法空
对象({})，分别打诊断日志，避免误报
- 回归测试 TestAccumulateStreamParallelToolCallsByIndex 模拟
4 路并行分片流验证按 index 正确分组与参数完整性
另含 spawn_child max_turns 参数、child_result 运行中状态区分、
provider 层非流式空参诊断日志。
2026-08-26 16:10:02 +08:00
c945eace1a
fix(webui): 附件死锁 + qq 插件文件发送收敛到 output 通道
...
1. webui 附件死锁修复（output_send__webui 发图 60s 超时根因）
EventAgentOutput 订阅者已持 chatMu，附件分支调 addChatMsg（内部
再次 Lock）——sync.Mutex 不可重入导致 Publish 永久阻塞，工具超时、
图片永远发不出来。改为持锁状态下直接操作 chatHistory+persist。
2. qq 插件 image/file 分支收敛到 output 通道
output_send__qq 的 type=image/file 此前只透传 payload 给 CQ 码，
发本地文件必须绕道 upload_group_file 独立工具。现在与 voice 分支
同模式：本地路径拷入 NapCat 共享目录转 file:///app/files/<name> URI，
http(s)/file:// URL 保持透传。upload_group_file 保留作为群文件柜
专用入口。
验证：工具链重编译 → qq.hmap 重打包 → pluginmgr overwrite 安装
（config_kept=true）→ agent 经 output_send__qq 用本地路径发图成功，
mascot.webp 已落共享目录。
2026-08-26 11:14:03 +08:00
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
534232b768
fix(webui): 附件消息历史持久化 + 用户文件上传（对齐 qq 插件收文件设计）
...
1. 附件展示链路补全
- ChatMsg 新增 Attachment 字段（type/url/size/name），channel_output
订阅提取 output_type/url/size 存档——修复刷新后附件变纯文本路径
（如 '/tmp/homeagent.png'）的问题
- EventRawInput 订阅支持 upload_* 字段：用户上传的消息也带附件卡片
2. 用户→agent 文件上传（POST /api/v1/chat/file）
设计对齐 qq 插件收文件模式：
- multipart(file + message) 落盘 <data>/uploads/<原文件名>（重名加
毫秒后缀，路径穿越消毒），单文件上限 64MB
- 注入文本「[用户通过 webui 发送了图片: 名字 (大小)] + 保存路径」，
agent 用 files_read 等工具按路径消费
- 回复走与普通消息相同的 SSE 流式管道
- GET /uploads/<name> 下载，与 /files/ 同一鉴权与安全模型
3. 前端
- 输入区 📎 按钮；拖拽到聊天区直接发送；粘贴截图即发送
- 本地预览用 URL.createObjectURL 即时显示
2026-08-26 10:03:46 +08:00
0afa84a13f
feat(webui): agent 可向 webui 发送图片/文件，前端内联展示与下载
...
输出通道能力升级：webui 通道从 CapText(1) 扩展为
CapText|CapFile|CapImage(7)，agent 经 output_send__webui 即可发送
image/file（此前仅文本）。
服务端：
- stageWebFile 把本地路径文件拷贝到 <data>/webui_files/<hex>.<ext>
（随机名防猜测、危险扩展名强制 .bin），http(s) URL 直接透传不落盘
- 新增 GET /files/<name>（requireWeb 与 dashboard 同鉴权）：扩展名
白名单映射 Content-Type，图片/音视频 inline、其余 attachment 下载，
nosniff + 路径穿越拒绝
- SSE agent_output 事件携带 output_type/url/size 字段
前端（dashboard.html）：
- channel_output 识别附件消息：image 渲染内联预览（点击原图）、
file 渲染下载卡片（含大小）；formatBytes 人性化显示
典型场景：agent 把 remotedevice 回传的录像/截图（device_media/*.mp4）
直接发给 webui，用户在聊天里看到视频预览或一键下载。
新增 TestStageWebFileAndDownload / TestHandleFilesAuth 覆盖。
2026-08-26 09:17:07 +08:00
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
168c88593d
fix(remotedevice): WS 握手 Accept 改用 SHA-1（RFC6455 合规）
...
wsAccept 误用 sha256 计算 Sec-WebSocket-Accept，RFC6455 §4.2.2 规定
必须为 base64(SHA1(key + GUID))。后果：所有标准 WS 客户端（浏览器/
Electron/各语言标准库）校验 Accept 失败后立即断开连接，设备永远无法
完成 hello 注册——devicedetect 恒返回空列表，核心看不到任何设备，
而设备端本地授权状态正常，形成'已授权但核心看不见'的表象。
验证：openssl sha1 对照 + 干净实例端到端握手 Accept 完全一致。
2026-08-25 23:48:20 +08:00
ae42e486de
feat(pluginmgr): 插件更新接口（upgrade/downgrade 保留配置）+ skill_install overwrite
...
内核 Registry 拆出 StopAndUnload：
- 停止并从注册表移除插件但保留 config_<name> 表
- 不触发 onRemove 回调（那是删除专用语义）
- RemovePlugin 改为追加清理配置表示清除，更新场景调 StopAndUnload
pluginmgr:
- installFromData/installFromURL/installFromPath 加 overwrite 参数
- 已存在+overwrite=true：StopAndUnload→备份旧目录→解压新包→失败回滚→
返回 action=upgraded/downgraded/reinstalled+previous_version+config_kept
- 已存在+overwrite=false：返回 error+hint（指向 overwrite 用法）
- cmpVersion 点分版本号数字比较（非字典序）
- 测试覆盖：首次安装→重装拒绝→升级保留配置→降级→失败回滚
skill_install 加 overwrite 参数：
- 同名技能存在时先卸载旧实例+删除目录再安装新包
SDK PluginMgr 接口同步加 StopAndUnload(name string) error
工具链 plugindev 已重建到 /usr/local/bin（7/29→8/25 版本）
QQ 插件诊断日志版（webhook recv 到达+isAtBot 失败日志）已打包并
通过 upgrade 接口热更新部署，配置保留验证通过。
2026-08-25 22:02:17 +08:00
5f126d4d10
feat(skillmgr): 原生技能管理器插件 + OpenClaw 兼容层职责分离
...
新增 internal/plugins/skillmgr（native skill 全生命周期 owner）：
- skill_list/info/load/unload/enable/disable/create/export/install
- skill_create 两步式：先生成骨架模板，LLM 补全后传 content 覆盖写入
（plugin.ValidateSKILLContent 校验）并自动加载生效
- .skm 分发包（tar.gz）：packSkill/unpackSkill 含 TarSlip 防护
（拒绝绝对路径/../逃逸、强制单根目录、校验包内 SKILL.md）
- skills 目录扫描：纯 SKILL.md/skill.json 条目归本插件；
sidecar(main.js/main.py)/OC plugin(openclaw.plugin.json) 留给兼容层
clawhubadapter 职责分离（OpenClaw 兼容层不再持有 native skill）：
- 删除 p.skills 字段与 default 分支 LoadSKILL 逻辑
- 发现纯 SKILL 条目改为发布 events.EventSkillDetected 移交事件，
由 skillmgr 订阅注册；启动时序 c<s 下全扫兜底，事件用于热新增
- claw_list/plugin_info 不再输出 SKILL 段，统一走 skill_list
方案B prompt 注入：
- agentCore 新增 SkillIndexProvider 接口 + SetSkillIndexProvider
- buildSystemPrompt 注入【可用技能】轻量索引（名称+版本+描述），
LLM 匹配场景时主动 skill_info 拉全文按文档执行
- main.go 在插件加载后将 skillmgr 实例接线到 agent
内核小修：
- extractDescription 跳过 YAML frontmatter 块（此前所有带 frontmatter
的 SKILL.md 描述都被误判为 '---'）
- extractField 剥离 YAML 成对引号（version: "1.0" 不再带尾引号）
- plugin.ValidateSKILLContent 导出供生成侧校验
2026-08-25 20:25:57 +08:00
51eb98e0ae
fix(mcp+adapter): 流式 tool_calls 解析修复 + MCP transport 超时保护
...
openai adapter transform_stream_chunk:
- OpenAI 流式分片是嵌套格式 function.{name,arguments}，原样透传后
json.Unmarshal 到扁平 ToolCall{name,arguments} 时 name 恒为空，
accumulateStream flushToolCall 因 acc.name=="" 静默丢弃整个工具调用
（流式路径自上线起 tool_calls 全部丢失的根因）
- 现在正确解包 function.name → name，function.arguments → raw_arguments
（保留原始 JSON 字符串分片，由 accumulateStream 按 index 拼接）
- 不按 name 过滤分片：OpenAI 流式续传块 name 为空但携带 arguments 分片
mcp stdio/sse transport:
- stdio Send() 无超时：server 进程卡死时插件加载永久阻塞
- sse http.Client 无超时：远程 server 网络抖动/无响应时永久阻塞，
导致 webui 等后续插件全部无法启动（生产实例偶发启动卡死根因）
- stdio 加 60s 请求超时；sse client 加 30s 整体 + 10s 拨号超时
2026-08-25 18:59:00 +08:00
79b7766ed4
fix: 流式渲染回合生命周期 + LLM 瞬断重试与 SSE body 兜底
...
问题一（webui 不是真流式）：
- sendChat 的 finally 在 POST 结束(15s ackTimer abort)时就复位
chatLoading，但 agent 生成窗口 15~190s，后续 SSE delta 全部走
全量重建路径、停止按钮提前消失、用户误发重复消息。
- GUI app.js 完全没有 content_delta/reasoning_delta 监听器，
只能等聚合帧一次性显示。
修复：三端统一回合生命周期——POST 只是触发，收尾由 SSE 驱动：
- dashboard/GUI 新增 endChatTurn/armTurnWatchdog；拿到同步兜底
响应立即收尾，否则保持回合打开等 agent_output final / reset 帧 /
120s watchdog 兜底
- GUI 补齐 delta 监听器；agent_output 聚合分支 += 改覆盖；
reasoning 聚合帧改覆盖（多轮工具调用时旧逻辑会重复累加）
- agent_output 误杀分支（final 无 source 即 return 丢弃新输出）
改为内容比较去重，多轮连发时新一轮回复不再被吞
- waiter reasoning_delta reset 从清空全部消息改为 sealLastAgent
问题二（三条只成功一条）：
- handleChat 60s ctx 含排队时间，agent 串行处理下第 N 条必超时
（实测第 3 条 62s 超时 504）；放宽到 300s（客户端 abort 时立即取消）
- LLM 单 provider 瞬断无重试：process.go provider 循环内加同源
重试（2 次、退避 2s），401/403 凭证错误与用户中断不重试
- llmsproxy auto 链在非流式请求下可能返回 SSE body（上游恢复后
吐已生成的 chunk 流），非流式解析报 invalid character 'd' 丢掉
整段回复；新增 parseOpenAICompatibleSSEBody 拼接为完整响应
- 顺带修 normalizeStreamToolCalls 分片续传 bug：name 不重发时
argsRaw 被顶层 Arguments(nil) 覆盖丢失 function.arguments
验证：
- 连发 3 条 + 单条共 4 条全部成功（首条 190s 重试扛住瞬断）
- sse_body_test.go 锁定 SSE body 解析契约（content/usage/tool call 分片）
2026-08-25 12:24:11 +08:00
061d2ae320
feat(streaming): token-level delta events + interrupt for CLI/WebUI/GUI
...
Expose the LLM token-level streaming deltas (EventReasoningDelta /
EventContentDelta) to every client channel and add user-initiated
interrupt (cancel generation / send interrupt message) to all three
frontends, preserving the existing interrupt-injection semantics.
SDK/events:
- EventReasoningDelta, EventContentDelta constants exported in the
public/internal SDK event alias tables.
CLI plugin:
- handleChat subscribes to both delta events and forwards
reasoning_delta / content_delta JSON frames (channel-filtered);
aggregated reasoning/tool_call/response frames still fire as before.
- New /stop (alias /interrupt) builtin injects an interrupt via
InjectInterrupt(cliSource, cliChannel) - matches interceptLoop
semantics: cancels an active stream and re-injects the message as
a [中断消息] for a restarted turn; with no active LLM it behaves
as a plain input.
Waiter client (line mode + TUI):
- streamRender accumulates delta chunks and redraws the current line;
a reset frame (stream abandoned, e.g. user interrupt) flushes the
partial buffer so the next turn does not concatenate onto stale
content. Aggregated frames terminate the delta line and render the
final text (old servers without deltas behave exactly as before).
- TUI merges content_delta into the in-flight agent message and seals
it (final flag) on response/tool_call/error so subsequent deltas
never append to a finished message.
WebUI:
- SSE handler subscribes to the two delta events but does NOT record
them into the replay ring - reconnection replays only aggregated
events (the final truth), avoiding duplicate delta accumulation.
- POST /api/v1/chat/interrupt calls InjectInterrupt(webui, webui)
with optional message; fronted by a Stop button shown only while
a generation is in flight.
dashboard.html / GUI app.js:
- Stop button next to Send (hidden until chatLoading); interruptChat
POSTs /chat/interrupt. Delta listeners append incrementally;
agent_output (aggregated) now replaces (not appends) the in-flight
content and marks _final; reset frames finalize the partial message.
process.go:
- chatStreamWithFallback preserves the context.Canceled/
DeadlineExceeded contract: a user interrupt returns the canceled
error (never a partial-content success) so the existing continue
branch restarts the turn with the [中断消息]. A reset
EventContentDelta is published so connected clients drop stale
partial renderings before the new turn begins.
Verified: /stop 'msg' via waiter triggers 'interrupt from cli/cli' in
interceptLoop; unit TestChatStreamCancelPreservesInterrupt confirms the
canceled error propagates instead of being swallowed.
2026-08-25 10:50:37 +08:00
ece06b0375
feat(cli): streaming process output with npm-style spinner
...
CLI 对话现在像 npm 安装一样先显示 braille 加载动画，然后逐步吐出
推理内容和工具调用状态，最后输出最终响应。
协议扩展（JSON 行，向后兼容）：
- {"type":"reasoning","content":...} 推理过程帧
- {"type":"tool_call","tool":...,"status":...,"result":...} 工具调用帧
- response / error 仍为终结帧，语义不变
服务端（internal/plugins/cli）：
- handleChat: 通过 SDK 订阅 EventReasoning/EventToolCall（按 channel=="cli"
过滤），InjectTextSync 阻塞期间实时转发事件到 socket；connWriter 互斥
保护并发写。纯插件层实现，不触碰内核。
- 不订阅 EventAgentOutput：内核先写 ResponseCh 再 publish 该事件，
订阅会导致响应重复。
客户端（cmd/waiter）：
- startSpinner: npm 风格 braille 转圈（80ms），幂等 stop()，非 TTY 自动禁用
- SendChatStream: 循环读帧直至终结帧，onEvent 回调渲染过程帧
- printServerOutput: reasoning 灰色 · 前缀；tool_call ✔/✘ 状态行 + 结果预览
- 交互模式发送后自动起 spinner，首帧到达即停；oneshot 同理
- 向后兼容旧服务器（无类型行直接作为最终输出）
端到端验证：本地 homed 测试实例 + llmsproxy，oneshot 与交互模式均正确
渲染 推理→工具调用→最终响应 完整链路。
另外修正 dashboard.html renderReasoningCard 流式态使用 preview 结构
（与 GUI 渲染器一致，配合此前 renderChatStreamChunk 增量更新）。
2026-08-24 23:34:48 +08:00
121a2b9ace
fix(webui): 聊天流式增量渲染（移植 GUI renderChatStreamChunk 方案）
...
问题：webui 流式推理阶段虽有 90ms 防抖，但每次防抖到期仍是
全量 innerHTML 重建，视觉上「一下渲染一大块」。
修复：移植 GUI 的增量渲染方案——
- rerenderChat() 在流式中（chatLoading && 最后一条未 _final）走
增量路径：90ms 合并 chunk 后只调 renderChatStreamChunk()
- renderChatStreamChunk 仅更新最后一条消息节点：
· 正文 >200字符 或 >300ms 才 renderMd（节流 markdown parse）
· 小增量纯文本 createTextNode 追加，零 parse 开销
· 思考预览只刷 .reasoning-preview 文本
· 结构变化时兜底全量 renderChat()
- 工具卡/历史等非流式变化仍走全量路径
2026-08-24 22:40:48 +08:00
8157772132
fix(webui): sendChat 超时后 SSE 兜底渲染（对齐 GUI 模式）
...
问题：agent 长任务(159s)超过 15s ack 超时后，旧代码 return 导致
finally 清空 loading 并重置按钮，用户以为失败；SSE 回复虽到但
用户可能已离开/刷新页面。
修复（完全对齐 GUI renderer 的 sendChat 模式）：
- 超时后 r=null 不 return，流程继续
- finally 总是清 loading + 恢复按钮（loading 只是 UI 提示）
- toast 明确提示「请求超时（可能已发送，请稍候勿重复发送）」
- r 有值则直接填充最终回复；r=null 则靠 SSE agent_output 流式渲染
2026-08-24 22:36:45 +08:00
e1a94fc896
fix(webui): 聊天渲染优化 + 触发式 POST
...
- 删除死的 tool_result SSE 监听器（后端不发布此事件类型）
- 流式渲染防抖 90ms：SSE 高频 chunk 合并为一次重建，流式期间跳过
星图/终端/命令历史等无关渲染（renderChat 签名短路 + 防抖双重优化）
- sendChat 改触发式 POST：15s 短超时仅确认受理，超时后不报错，
回复靠 SSE 流式渲染（对齐 GUI 行为，解决长 LLM 工具链 60s 超时报错）
- sendChat 用户操作走 rerenderChat(true) 全量重渲；SSE 流式走
rerenderChat() 防抖仅聊天
2026-08-24 21:53:53 +08:00
ce53e8816b
chore(webui): 清理前端死代码
...
- 删除 8 个未引用 JS 函数: confirmDialog/showToast/timeAgo/statCard/
systemTheme/getStarmapBg/resetStarmapCamera/toggleStarmapAuto
（实际使用的是 toast()/内联卡片构建/setTheme）
- 删除星图 hover info 空转块（starmap-info 容器不存在，infoEl 永远 null，
sm-info-name/type/mentions/links 子元素查询全部无效）
- 删除死 CSS: #starmap-container/#starmap-stats/#starmap-info/
#starmap-loading/.starmap-toggle（对应 HTML 元素已不存在）
- 删除重复的 #sm-container-chat height:480px（被后续 260px 覆盖）
共 -266 行，JS/CSS 语法验证通过
2026-08-24 21:01:06 +08:00
2ee007edc9
chore: 清理垃圾文件与构建产物
...
- 删除 internal/plugins/webui/dashboard2.html（遗留压缩实验代码，含乱码，零引用）
- 删除根目录旧二进制 homed/waiter（build/ 已有最新版）
- 删除 build/ 实验二进制 homed2/3/4/-audio/-img/-lua/-multi/-sched/_v2
- 删除 deploy/build 重复发布包 + dist 打包产物
- 删除 .gopath（旧 SDK v0.7.2 模块缓存，已 replace 到 third_party 本地副本）
2026-08-24 20:18:59 +08:00
ba5785036a
feat: 设备鉴权迁移至客户端 + 插件卸载保护
...
安全修复（客户端鉴权）：
- remotedevice 服务端移除授权状态存储（authorized map/SetAuthorized/handleDeviceAuth）
- DeviceMeta.Authorized 改为设备 hello 自报，服务端仅透传展示
- device_ctl_* 工具移除服务端授权检查，无条件转发，设备端自行决定是否执行
- 共享设备桥库 Bridge 新增本地 authorized 状态，未授权收到 cmd 直接拒绝
- waiter: --device-authorized / device_authorized 配置控制本地授权
- GUI: 授权存 gui-prefs 本地文件；设备页仅本机可切换开关
- webui /device/auth 旧路径返回 410 Gone
- 根因：agent 可经 config_set 篡改服务端授权配置自行授权设备
插件管理强化：
- 内置插件禁止卸载（IsBuiltinPlugin + 409），外部插件卸载即时生效
- 卸载不存在插件返回 404；移除误导性 reload_required 提示
- webui 插件路由：名称白名单校验防路径穿越、保留字路径保护
2026-08-24 19:26:11 +08:00
5163ce51a7
feat: SSE Last-Event-ID 断线重放 + GUI 表单防刷新
...
- webui handler: 新增 sseEventRing 环状缓冲区(200条)，断线重连按 Last-Event-ID 重放遗漏事件
- GUI app.js: doRenderAll 检测连接表单打开时改走 refreshDataOnly，修复 15s 定时器擦掉用户输入的 bug
- 附带 dashboard.html/index.html 前端调整 + handler_sse_test.go 单测
2026-08-24 16:22:28 +08:00
4dcd3623cb
feat: 设备能力矩阵校验 + 设备主动上报事件通道
...
回应架构讨论: 外接设备各自声明能力, 且补齐设备→agent 单向推送缺口。
1. 能力矩阵 (registry.go):
- capabilityTools 映射: caps 声明 → 可用工具
screen/screensue/screensee, computeruse, clipboard(see/sue),
camera/camerasue, speaker/speakeruse
- SupportsTool 校验: screensee/computeruse/clipboard* 执行前检查
目标设备是否声明对应能力, 未声明直接报错(不再下发到设备端才失败)
- 兼容规则: 声明 cmd/cmdrun 等历史值 → 全能力;
未声明任何已知能力 → 全能力(旧设备兼容);
有已知能力声明则严格匹配
2. 设备主动上报事件 (WS op=event):
- 设备可推 {op:event, type, detail/payload} 无需回执
- 插件层 SetEventHandler 回调: 格式化为人类可读文本,
经 SDK InjectInput 异步注入 agent(source=device/{id}, 回复路由回同通道)
- 同设备同类型事件 10s 节流防传感器风暴
- 场景: 摄像头识别未知人员驻留主动告警, agent 收到后自主处置
测试: 能力矩阵8场景 + 摄像头调screensee被拒 + 事件上报回调(含device_id回退)
2026-08-21 19:58:37 +08:00
c0e92cceb1
feat: clipboardsee/clipboardsue 工具 — agent 读写远程设备剪切板
...
与 screensue/screensee 同模式配对命名:
- clipboardsee: 读取设备剪切板当前内容(用户最近复制的文字)
- clipboardsue: 写入文字到设备剪切板(用户可直接 Ctrl+V 粘贴)
设计要点:
- 协议: homeagent-clipboardsee / homeagent-clipboardsue <文字>
- clipboardsee 回执 output 字段为剪切板文字, 响应含 content/empty 字段
- clipboardsue 响应含 written 字节数 + preview 截断预览(60 rune)
- 隐私提示写入工具描述: 剪切板可能含密码, 仅在用户明确要求时读取
- 典型组合写入描述: clipboardsue + computeruse keypress ctrl+v 自动粘贴
- 未授权/离线/超时完整错误路径
GUI 配套需求(已发群): executeHomeagentCmd 加 case clipboardsee/clipboardsue,
Electron clipboard.readText()/writeText(text) 一行实现。
测试: 端到端读写+参数校验+未授权拒绝 全通过
2026-08-21 16:31:23 +08:00
cacd9a8572
feat: computeruse 工具 — agent 结构化操控远程鼠标/键盘
...
配合 GUI b4e5b39 (homeagent-computeruse 能力):
- 新增 computeruse 工具, LLM 传结构化参数(action/x/y/dy/key/text/button)
- 服务端序列化为 GUI 约定的 JSON 参数格式下发, 避免 LLM 手拼字符串出错
- action 校验: click/doubleclick/rightclick/move 需坐标; scroll 需 dy;
keypress 需 key; type 需 text; 未知 action 报错
- 典型工作流写入工具描述: screensee 看屏 → computeruse 操作 → screensee 确认
- 未授权/离线完整错误路径; 结果留档 cmdresult
测试: 端到端验证 JSON 参数格式下发+回执+参数校验错误路径
2026-08-21 12:32:07 +08:00
