jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-09-27 12:53:35 +00:00
Code Issues Packages Projects Releases Wiki Activity
615 Commits 5 Branches 27 Tags
94c74b2ee64de3192de8c2d21dc8929ca7b62856
Commit Graph

21 Commits

Author SHA1 Message Date
JianFeeeee
94c74b2ee6 fix(devicebridge): 修复设备反复掉线/静默失联 —— ping 路径断连 + bind 结果无人处理 
用户要求全面修复「设备桥自动链接」这条链路上的问题。三个真实缺陷，
前两个是**服务端/客户端真 bug**（生产日志实证），第三个是我起初误判的。

## 缺陷 1（最严重）：未 bind 时收到 ping → 服务端直接关连接

原实现：
    err := r.wsWriteLocked(curID, writePong)
    if err != nil { return }   // ← 关连接

而 conns 表**只在 bind 成功后才写入**（bind 前刻意不暴露连接给查询/命令
路径）。于是「握手完成、bind 尚未到达」这个窗口里来的 ping 找不到写入口，
函数返回错误，读循环 return —— 把连接关掉了。

生产后果（journalctl 实证）：客户端每 30s ping 一次，只要有一次落在未 bind
窗口就断连。日志里同一设备 20 秒内多次 "ws connected"，online/offline 与
输出通道注销/注册反复交替：

  17:29:14 ws connected → 17:29:17 ws connected → 17:29:24 ws connected
  → 17:29:29 → 17:29:35 → 17:29:40 online → 17:30:18 offline → ...循环

修法：pong 直接写本连接的 writer。此时该连接尚未进入 conns（没有 Push* 会
碰它的 writer），不存在并发写风险；已 bind 时才取写锁（Push* 可能正在写
同一 buffer）。

判据 TestPingBeforeBindDoesNotDropConnection 直打 bug 点（只握手、不发
hello/bind、发 ping、要求 pong），修复前报 `EOF`，修复后通过。

## 缺陷 2：bind_ack 的 ok 完全没被检查 → 失败静默失联

原实现（客户端）：
    case "hello_ack", "bind_ack":
        log.Printf("... device=%v", msg["device"])

两处错：
- **取错字段**：服务端成功时回 {"op":"bind_ack","ok":true}，没有 device
  字段，于是日志永远显示 `bind_ack device=<nil>`。这让我起初误判成"绑定
  失败"，实际连接是好的（直连与经反代现象完全一致）。
- **不看 ok**：bind 被拒时服务端回 ok:false + error 并关闭连接，客户端既不
  报错也不重连，设备静默失联 —— TCP/WS 通但从未登记进网关。

修法：分别处理两种 ack；bind 判 ok，失败记原因并通知宿主。新增
Bridge.Bound() / BindError() / OnBoundState()：**连接成功 ≠ 设备可用**，
只看连接状态的健康检查会给出假阳性。

判据 TestBindFailureIsObservable / TestBindStateCallback。

## 缺陷 3：-chat 一次性模式下桥存活时间过短

不是我最初以为的"bind 失败"。真因：`-chat` 走进 oneshot 后立刻 return，
触发 defer stopDeviceBridge()，桥只活几百毫秒，设备来不及完成 hello→bind。

修法：退出前等 bind 确认（最多 3s）；bind 明确被拒则打印原因，不静默丢弃。

## 真实验收（隔离实例，命名 netns + 独立 data + 18080）

真 waiter 经**反代自动发现**连接，保持连接期间查询服务端：

  device gateway discovered: ws://127.0.0.1:18080/api/v1/device/ws
  bind 成功，设备已登记
  /api/v1/device/online → waiter-mainserver, online=true, caps=[11 项]

长连接稳定性：70 秒（跨 2 个 ping 周期）三次采样设备始终在线，
无 read loop exit / bind rejected 日志。

## 附：反代通路本身的判定性对照

裸客户端（直接构造 hello/bind 帧）**经反代**与**直连 9890** 返回逐字节
一致（bind_ack ok=true、设备注册、online=true）。所以这条链路上反代
不背锅，问题全在 remotedevice 服务端与客户端自身。
 2026-09-26 13:49:59 +08:00
JianFeeeee
7f5bf1670f feat(clients): 设备桥自动链接改用服务端发现 + 路径挂载（无 DNS 依赖） 
配套 webui 反代改造：网关现在可由 HomeAgent 反代出去，客户端不能再靠
「门户地址同 host 拼 /api/v1/device/ws」猜地址——基域名与子域标签都是
**服务端配置**，客户端无从得知。

## 服务端：/api/v1/device/gateway 发现端点

客户端问「网关在哪」是唯一不会漂移的做法：子域标签可改（插件声明）、
基域名可改（webui.base_domain）、实例可换形态，客户端都不用跟着改。

⚠️ **不返回设备令牌**：本端点用门户凭证鉴权，而设备令牌能执行设备命令；
把令牌塞进来等于「门户只读凭证 → 设备执行权」的越权。令牌仍由客户端
自配。已有判据钉住「不得泄漏凭证字段」。

## ★ 实测发现：*.localhost 只有浏览器能解析

这是本轮最重要的发现，直接决定了设计：

| 环境 | devices.localhost 解析 |
|---|---|
| 浏览器 | ✓（RFC 6761 内置） |
| curl | ✓（内置特例） |
| getent / Go / Node | ✗（系统 nsswitch 是 files,dns，无 nss-myhostname） |

设备客户端（waiter / GUI 主进程 / 嵌入式固件）用的正是系统解析器。
实测 waiter 报「lookup devices.localhost on 192.168.2.1:53」。

因此**两处**设计变更：
1. 发现端点同时返回两种形态，并标 preferred：
   - url（子域）—— 浏览器用
   - url_portal（门户同源，同一 host、同一端口，走路径挂载）—— 非浏览器用，
     无任何 DNS 依赖
2. SDK 的 ProxyDecl 新增 **Path**（路径挂载前缀）：让同一服务同时挂到
   门户自身 host 的路径下。remotedevice 声明 Path="/api/v1/device"，
   设备客户端因此能沿用**它已硬编码的路径**，不需要知道反代存在。

路径挂载语义：请求路径**原样保留**（不剥前缀），上游按真实路径注册即可。
边界卡在路径分隔符上（/api/v1/device 不匹配 /api/v1/devicefoo）。

## 客户端

- **waiter**：新增 discoverGateway()，仅在用户配了门户地址时尝试，失败回退
  自配地址（老版本 HomeAgent 无该端点）。抽出 normalizeGateway() 纯函数，
  显式钉住「已带子域/完整端点的地址不得被改写」。
- **GUI**：renderer 新增 loadDiscoveredGateway()，renderDeviceChannel 优先用
  发现值、回退旧口径。顺带修掉此前插入函数时 anchor 不匹配导致调用点
  找不到定义的问题。
- **鸿蒙**：discoverGateway() + resolveGatewayUrl()，优先 url_portal。
- 三者都**优先 url_portal**（system resolver 的现实约束）。

## 遗留路由鉴权修正

`/api/v1/device/` 的旧路径反代原被 requireAPI 包裹 —— 但其调用方是设备
（带设备令牌而非门户凭证），套上门户鉴权会把它们全挡在 401（**真实实测**：
waiter 经此路径升级握手 401）。去掉这层包装，鉴权交给上游 remotedevice
自己的 requireToken，安全性不降级。

## 判据

webui +6 条、waiter +7 条。

★ 其中一条是**真实回归**：/api/v1/device/gateway 曾被 Path="/api/v1/device"
的路径挂载接走（那服务 auth=none），于是发现请求被转给上游、回 401，
客户端再也发现不到网关。修法是发现端点先于路径挂载判定，并补判据
（走完整生产链，同时确认同前缀的真实设备路径仍归反代）。

## 真实验收（隔离实例，命名 netns + 独立 data + 18080）

真 waiter 客户端 + 真 remotedevice 网关：
  device gateway discovered: ws://127.0.0.1:18080/api/v1/device/ws
  device bridge active: waiter-mainserver authorized=true
  hello_ack / bind_ack 均经反代往返成功

说明：`bind_ack device=<nil>` 与在线列表为空的现象，**直连 9890 绕开反代
完全一致复现**，属 remotedevice 与 waiter 之间既有的握手细节，与本次
反代改造无关（反代侧职责已证：连接建立 + 双向帧往返都通）。
 2026-09-26 13:49:59 +08:00
JianFeeeee
1e58af79d3 feat(webui): 通用反向代理 —— 插件声明服务，HomeAgent 按子域反代出去 
用户要求：外部只装 HomeAgent 即可使用自带反代能力；用户只需穿透一个
webui 端口就能访问所有内部插件服务；认证与 WebSocket 支持都作为插件
的可声明项；插件 UI 要有可直接点击的入口。

实测 huawei_smarthome 插件的前端用**根绝对路径**（api('/api/status') →
fetch('/api/status')）。挂在 /p/<name>/ 这类路径前缀下，这些请求会打到
HomeAgent 自己的 /api/status —— 静默错路由；做 HTML/JS 内容重写对拼进
JS 字符串的绝对路径只是"按概率能用"，会产生"页面能开、某个按钮就坏"的
静默故障。子域路由下根路径天然正确，**插件前端零改动**。

且它天然匹配"只穿透一个端口"：webui 监听 0.0.0.0:8080 按 Host 分发，
外层 frp 单端口 TCP 隧道**一行都不用改**。

默认基座 localhost：RFC 6761 规定 *.localhost 强制解析到 loopback，
现代浏览器原生支持 ⇒ <标签>.localhost:8080 **零配置可用**，不需要 DNS、
证书、/etc/hosts。远程部署改 base_domain 即可。

- 外部插件 → plugin.json 的 proxies（静态可发现：插件没起来也能报
  "声明了 ui 但目标不可达"，而不是静默 404）
- 内置插件 → s.DeclareProxy()（remotedevice 是内置的、没有 plugin.json，
  却最需要被反代出去）

反代层在 webui 侧读清单：webui 已能拿到插件目录（PluginManager.PluginDir），
因此**无需给内核接口加方法**。manifest 解析忽略未知字段，加 proxies 对
"旧内核读新插件"与"新内核读旧插件"都无害。

新增 sdk/ProxyDecl 与配套校验（ValidProxyAuth / ValidProxyHostLabel /
NormalizeProxyHost / ValidateProxyDecl）；新增运行期 ProxyDeclarer 通道。
hmapdev 的 writePluginJSON 是**白名单 map 重建**——不同步加字段会让声明
被打包静默丢弃（插件作者本地正常、装上去失效），因此 PlgConfig 与
writePluginJSON 同时加，并在打包前校验声明（插件作者本地就能发现写错）。

auth=homeagent（默认，安全的默认）：门户会话 / X-API-Key / ?__token=；
auth=none：信任上游自身鉴权，供设备与嵌入式客户端使用——它们不可能持有
浏览器会话，强制走门户鉴权会把设备链路挡死。remotedevice 声明 none，
因为它自身用 ws_token 强制校验。

未声明时升级请求**明确拒绝**（400 + 原因），而不是静默降级成普通请求
（后者表现为前端不断重连、日志看不出原因）。

1. 不跟随上游 3xx：旧实现用 http.DefaultClient（默认跟最多 10 跳），
   上游 302 到内网地址时反代自己跟过去、失败回 502 并把内网 URL 泄给
   客户端。httputil.ReverseProxy 默认不跟随，3xx 原样透传。
2. 逐帧 flush：旧实现 io.Copy 导致上游流式响应被缓冲到上游关闭才下发
   （实测 3 帧 200ms 间隔的流，客户端在 +600ms 一次性收到全部）。
   设 FlushInterval=-1。

另补齐 X-Forwarded-For/Host/Proto（旧实现完全不注入，上游无法判断真实
来源），并剥掉上游 Set-Cookie 的 Domain（防止插件 cookie 打到主门户域）。

插件页新增「服务入口」卡片：列出全部被反代的插件服务（含被拒条目与
不可达原因），点「打开」直接访问。链接带 ?__token=<api_key>，因为子域
与门户不同源、浏览器不会自动带会话 cookie。

webui +35 条、SDK +4 条、工具链 +4 条。关键几条：
- 根绝对路径必须原样到上游（选 Host 路由的核心理由）
- 上游 302 必须原样透传、且反代不得跟随（旧缺陷）
- 已知 Content-Length 的慢速响应必须逐帧到达（**这条经过变异验证**：
  把 FlushInterval 改回 0 后判据挂死 → FAIL，还原后回绿。
  说明：最初写的 SSE/chunked 版本是假判据——ReverseProxy 对
  text/event-stream 与 ContentLength=-1 会自动立即 flush，与
  FlushInterval 无关，变异抓不到，已改正）
- 子域标签冲突不得静默覆盖（后者保留可见并带原因）
- 非法声明不进路由但必须可见（配置页要能看到原因）
- 未声明 websocket 的升级请求必须 400
- auth 逐条生效：none 放行匿名、homeagent 与默认档 401 且给可操作提示
- 自动发现：显式 host 不得被自动编号覆盖（**测试抓到的真 bug**：
  remotedevice 声明的 "devices" 会被改成 "devices-2" 而静默失效）
- 真实端到端：生产实例 huawei_smarthome 的 UI（9444 字节）与其
  /api/status 经反代正确透传

go build ./... 通过；相关包全量测试通过。
internal/plugin/proc 的 TestStreaming_PublishLatencyFlatAcrossSubscribers
是**预存在的不稳定测试**（同一份代码 10 次跑 9 过 1 败，且本改动完全
未触及该包），非本次引入。
 2026-09-26 13:49:59 +08:00
JianFeeeee
17e7094967 fix(plugins): 修三处端口/监听缺陷 + 让测试用临时端口（消除既有 flaky） 
排查内核 SIGSEGV 时用 A/B 对照（我的树 20 轮 vs 干净树 20 轮）确认了
两条**既有** flaky，与 C 化改动无关。本提交把它们修掉。

## 缺陷 ①（真 bug，不只是测试卫生）：pluginmgr 监听地址是包级可变全局

`var HTTPAddr = "127.0.0.1:9876"` 是包级可变全局，`Start()` 还把 settings 读到的值
**反写**回它，`startHTTPServer` 再读它。后果：
  - 多实例互相污染：后启动的实例把地址写进全局，先启动那个读到的是**别人的**地址
    （实测与生产 homed 抢 9876）
  - 全局读写无同步，属数据竞态

修法：改为实例字段 `p.httpAddr`（默认走 `const defaultHTTPAddr`），
不再有可被任意代码改写的包级状态；并新增 `HTTPURL()` 访问器。

## 缺陷 ②：remotedevice 用 ListenAndServe，监听失败静默且 :0 无法回报端口

`p.server = &http.Server{Addr: p.addr}` + `ListenAndServe()` 在后台 goroutine 里报错，
端口被占时只打一行日志、`Start()` 仍返回 nil —— 插件表面「已加载」而网关根本没跑。
且 `:0` 下拿不到真实端口。

修法：改为 `net.Listen` + `Serve`（与 webui/pluginmgr 同形）：
  - 监听失败**同步**返回，交给加载器
  - 用**实际绑定**地址回写 p.addr，日志与诊断面显示真实端口

## 测试侧：全部改用 :0，不再抢固定端口

新增 `ConfigRegistry.SetPluginConfig(name, key, value)`：插件表原本只在
`RegisterDef`（插件 Start 时）创建，导致「想在插件加载前预置配置」无从下手
（直接 Set 会因表不存在而失败，错误常被忽略）。新方法先建表再写，填补该时序缺口。

`setupIntegration` 在 `Load()` 前预置：
  - pluginmgr.http_addr / remotedevice.listen_addr → `127.0.0.1:0`
  - webui 走已有的 `SetListenOverride("127.0.0.1:0")`（它有独立旁路）

实测三个插件现在各自绑到 OS 分配的空闲端口（41895 / 35855 / 34021）。

## 缺陷 ③：deepsearch 测试把「上游限流」当成功能回归

`TestRealPlugin_DeepSearchInvoke` 的断言会在上游限流时失败，但插件此时返回的是
**正常结果**（err==nil，content 含 "未返回结果" 与无响应引擎列表）——那是外部条件。
实测失败信息：`brave(Suspended: too many requests), duckduckgo(CAPTCHA), google cse(...)`。

更糟的是它**不可控地随机红**：干净树连跑 20 轮复现 2 次，与代码改动无关。
这种判据会让真正的回归淹没在噪声里。

修法：区分「上游不可用（限流/CAPTCHA）⇒ t.Skip 并说明理由」与
「其他异常 ⇒ fail」。不用静默 return，避免环境退化时判据无声失效。

## 由此发现并修掉的真缺陷：监听地址被硬编码在三处

`127.0.0.1:9876` 曾硬编码在 pluginmgr / cli / webui 各一份。cli 与 webui 后来改为
运行时读 `pluginmgr.http_addr` 设置（本次核实），pluginmgr 自己却仍是全局 —— 三处
口径现在统一为「读设置 + 实例字段」。

## 验证

- 新增 `TestTwoInstances_ListenIndependently`（pluginmgr）：两个实例同时监听、
  各自 HTTPURL 指向自己端口、两个地址都真的可连。
  ★ 经**忠实变异**验证有牙：复原「包级全局 + Start 反写 + 读全局」后该测试判红
  （我第一版测试只断言字段不共享，变异证明它没牙，已重写为端到端判据）。
- `internal/plugins` 连跑 **30 轮：30/30 全过**（修复前干净树 18/20）。
- 全量连跑 3 轮：38 ok / 0 FAIL / 0 bind 冲突。
- go build ./... / go vet ./... 干净。
 2026-09-25 17:57:15 +08:00
JianFeeeee
75f377fd4d fix(remotedevice): 心跳 pong 忘了 Flush —— 修「设备通道每 60 秒掉线重连」 
真因（实测定位）：服务端 writePong 只调 writeFrameHeader，**不 Flush**。
pong 只有两个字节，且设备空闲时没有任何别的写会顺带把 bufio 缓冲刷出去 ——
于是 pong 永远留在服务端缓冲里。

链路：客户端每 30s 发一个 ping（pingLoop）→ 服务端算出 pong 却没发出 →
客户端的读循环设的是「2 倍 ping 间隔」读超时（默认 60s）→ 每 60 秒准点
i/o timeout → 桥断开 → 3s 后重连 → 服务端 markOffline 注销 outputch，
重连后再注册。

生产日志就是这个指纹（online :20 → offline 下一分钟 :20 → 重连 :23，
连续数小时无一次例外）；面板上表现为设备通道/工具凭空消失又出现，
/devices 列表跟着闪。

改法：writePong 复用 writeFrame（它 Flush）。另把客户端读循环退出时的
静默 return 改成带错误与 opcode 的日志 —— 此前断线真因在设备侧完全不可见，
只能靠对端日志倒推，正是这次排查一开始卡住的地方。

回归用例 TestWSPingGetsPongWhileIdle：只发一个 ping，随后什么都不发，
要求 2s 内必须收到 pong。**反向验证过**：把修复改回 writeFrameHeader，
用例即以 `read tcp ...: i/o timeout` 失败（与生产症状一致）。
 2026-09-14 11:15:21 +08:00
JianFeeeee
18d7ad3a36 fix(remotedevice): 设备通道名改用 - 分隔并派生合规名（v1.3.0 部署后 agent 完全不应答的根因） 
## 事故

v1.3.0 部署到生产后，**整个 agent 不应答**：任何对话都返回
`all 3 providers failed, last error: api error 403: model "claude-opus-5" is not allowed for this key`。
回滚到 1.2.2 立即恢复（部署前 403=0/成功对话=10，部署后 403=5/成功对话=0）。

## 根因（网关日志给出的原文）

```
tier 3 gozen/deepseek-v4.1-flash: api error 400: [invalid_request_error]
  Invalid 'tools[299].function.name': string does not match pattern '^[a-zA...
```

设备的每设备输出通道名叫 `device/<id>`，内核按 `output_send__<通道名>` 生成工具 ⇒
`output_send__device/<id>` 里的 `/` 违反上游函数名规范 `^[a-zA-Z0-9_-]{1,64}$`。
上游不是"拒掉这一个工具"，而是**整条请求 400** ⇒ 网关 auto tier 全链条失败
（400/429/503 混在一起）⇒ 内核只能报"所有 provider 都失败"。
两台真实设备（waiter-fnnas / waiter-mainnas）一上线就登记了这种通道，于是必然触发。

## 修法（改插件，不改内核）

初版我在内核里加了"通道名净化 + 反向解析"层。用户否掉了这个方向，理由对：
**通道名是插件自己的声明，不合契约就该改插件**，不该让内核替插件擦屁股。
内核侧改动已全部回退（HEAD 干净）。

插件侧两处：
1. 分隔符 `device/<id>` → `device-<id>`（源码与来源标签统一，不留两套名字）。
2. 设备 id 是**外部输入**（设备自己声明），可能含空格/非 ASCII/超长 ⇒
   `deviceChannelName()` 把它派生为**合规且唯一**的通道名：
   保留 `[A-Za-z0-9_-]`、其它折成 `-`、主体截断到 32 字符（预算 64 = 13+7+32+7+…）、
   发生截断或撞名时追加 id 的 6 位短哈希。同一 id 恒定同名；真名仍用于路由与日志。

核心契约写进了插件注释与 SDK 文档（见 SDK 仓同批提交）：名字若来自外部输入，
**在插件侧派生合规名**，内核不会替你净化。

## 验证

- 新增 `TestDeviceChannelNameIsLLMFunctionNameSafe`：恶意 id（空格/符号/非 ASCII/超长/
  会折成同名的两个 id）都必须派生出**合法且互不重复**的通道名与工具名。
  反向验证：把分隔符改回 `/` 即 FAIL。
- 生产两台设备派生结果：`device-waiter-fnnas`、`device-waiter-mainnas`
  ⇒工具名 `output_send__device-waiter-fnnas`（37 字符，合规）。
- 全量 `go test ./...` = 37 包 ok / 0 FAIL；`-race`（remotedevice + core）无 DATA RACE。
 2026-09-13 13:10:38 +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
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
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
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
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
JianFeeeee
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
JianFeeeee
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
JianFeeeee
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
JianFeeeee
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
JianFeeeee
cfe5a1a7f1 feat: screensue 默认 5s 超时，agent 可指定时长或永不超时 
- GUI main.js: screensue 默认 duration 从 0(常驻) 改为 5 秒自动关闭
- 命令带数字 token 指定时长: "screensue 30 内容"=显示30秒
- 命令带 0 表示永不超时: "screensue 0 重要公告"=常驻直到用户手动关闭
- gui-prefs.screensueDuration 用户配置默认值(未配置时 5)，命令参数优先级最高
- 设置页(app.js)新增「默认时长(秒)」输入框(placeholder 提示 0=常驻)
- 回执文案区分 for Ns / persistent until closed
- 服务端 device_ctl_cmdrun 工具描述同步更新(5秒默认/指定秒数/0永不超时)
 2026-08-21 12:10:28 +08:00
JianFeeeee
5b0cd45093 feat: screensee 工具 — agent 查看远程设备屏幕内容 
与 screensue(向用户屏幕显示)配对: screensue 是给用户看, screensee 是 agent 看。

服务端实现:
1. remotedevice 新增 screensee 工具:
   - 下发 homeagent-screensee 命令 → 设备截屏回传 jpeg base64
   - seeHandler 回调(agent 核心注入)用视觉模型自动描述屏幕内容
   - 未授权/离线/超时完整错误路径; 结果留档 cmdresult
2. SDK LLMMessage 扩展多模态 Blocks(text/image_url):
   - llm_impl 转换为 agentAPI.ContentBlock, 视觉模型可看图
3. describeScreen: 默认提示词描述窗口/文字/界面状态;
   provider 参数可指定视觉源(临时切换后恢复)

GUI 端需配套(已发群): onDeviceMsg 加 case "screensee",
desktopCapturer 截屏 → jpeg base64 data URL 回执(同 camerasue 抓拍模式)。

测试: 端到端模拟设备截屏回传+视觉回调验证; 全项目 go test 通过
 2026-08-21 11:31:45 +08:00
JianFeeeee
f2e3215c77 feat: remotedevice 二进制分块协议(录像回传+音频下发) + 工具描述增强 
回应 GUI c29abe9 需服务端配套项([阻塞]两项 + [中]一项):

1. readFrame 支持 0x2 二进制帧(之前遇 0x2 直接断连):
   - 返回 opcode, 二进制帧上限放宽至 8MB
2. handleWS 二进制聚合协议(设备→网关, 录像回传):
   - cmd_data_start 开启按 req_id 聚合 → 0x2 帧追加 → cmd_data_end 聚合完成
   - 结果存 cmdresult(data_base64 字段), device_ctl_cmdresult 可取回
   - 超限防护(声明 total×2 或硬上限 64MB)
3. PushData 下发协议(网关→设备, 音频/TTS):
   - cmd_speech_start → 0x2 分块(8KB) → cmd_speech_end
   - GUI 端已实现接收侧(speakeruse 播放链路打通)
4. device_ctl_cmdrun 工具描述补齐:
   - screensue 带参示例(<内容>/<秒> <内容>)
   - camerasue 录像说明(cmdresult 含 data_base64)
   - speakeruse 文字朗读

测试: 最小 WS 客户端端到端验证二进制分块上传/PushData 下发/离线报错
 2026-08-21 10:53:38 +08:00
JianFeeeee
653dd34299 feat: 插件工具按需拉取(get_plugin_tools) + 设备命令类型拆分(shell-cmd/homeagent-cmd) 
1. 提示词去污染: buildToolCatalog 从全量工具定义改为按插件分组摘要
   (插件名 + 工具数 + 能力概览), 完整工具定义由新工具 get_plugin_tools(plugin_name)
   动态拉取; 新增 executeGetPluginTools 支持按插件过滤 stageHost/io 工具
2. 设备命令类型: device_ctl_cmdrun 的 command 支持前缀区分
   - shell-cmd <cmd>      -> 设备端执行原生 shell
   - homeagent-<cap>      -> 设备端 HomeAgent 内置能力(如 camerasue/screensue)
   - homeagent-cmd <cap>  -> 同上(兼容写法)
   PushCmd 增加 cmd_type 字段下发给设备端分发
3. 测试: TestExecuteGetPluginTools 验证按插件拉取/全部摘要/未知插件
 2026-08-18 09:07:21 +08:00
jianf
ef5f010e87 device gateway: remotedevice 插件(设备接入网关) + GUI/waiter 受控设备桥 + 设备页/授权开关/托盘/退出进托盘 + 白屏修复(惰性Tray) + deviceinfo 工具 2026-08-17 09:34:25 +08:00