jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-10-15 12:15:16 +00:00
Code Issues Packages Projects Releases Wiki Activity
761 Commits 6 Branches 29 Tags
906821920b02c39aa2618306f062f67a644de487
Commit Graph

761 Commits

This Branch
This Branch
All Branches
Author SHA1 Message Date
JianFeeeee
906821920b fix(gui): 清理由改名遗留的重复开机自启项 
## 现象
本机 HKCU\...\Run 里同时存在两条指向**同一个 exe** 的自启动项：
  electron.app.HomeAgent     = "E:\program\homeagent\...\homeagent-gui.exe"
  electron.app.homeagent-gui =  E:\program\homeagent\...\homeagent-gui.exe
表面看是两个自启动，实际是同一份程序的重复 ⇒ 开机启动两次。

## 根因
Electron 的 app.setLoginItemSettings() 用「electron.app.<exe 名>」作为
注册表项名。本产物改过名（HomeAgent.exe → homeagent-gui.exe），于是写入
新项，而旧项 Electron 不会清理 ⇒ 每改一次名就多留一条。
原 applyAutoLaunch 既不去重、也不清理历史项。

## 修法
新增 cleanupStaleLoginItems()：
  · 只删「指向当前 process.execPath」的 electron.app.* 项 —— 不误伤别的
    Electron 应用（本机还有 electron.app.TencentDocs 同为该前缀）
  · 保留当前 exe 名对应的那条（Electron 期望的名字）
  · 在 app.whenReady() 里也跑一次：否则旧项要等用户手动开关自启才被清

## 实测（非静态检查）
人为再造一条 electron.app.HomeAgent 指向同一 exe，启动 GUI 后：
  启动前 2 条 → 启动后 1 条
  日志: [autolaunch] removed stale login item: electron.app.HomeAgent
判据未改动，npm test 131 条全绿。
 2026-10-04 15:25:11 +08:00
JianFeeeee
8fc9d499d8 docs(gui): 修正 GUI-PLAN 陈旧段落并补齐待办 
## 修正三处因改用 SendInput 而陈旧/错误的表述

1. **「平台硬限制」说法是错的**（重要）
   原文写「Chromium/Electron 自绘界面、游戏会忽略合成消息，这是 Windows
   消息模型的硬限制」。实际那只是 `PostMessage` 这条 API 的限制 ——
   `SendInput` 注入系统输入队列，自绘界面照常接收（Coopanion 即如此）。
   已改为分别说明两种注入的适用范围。

2. **3.4/3.5 已验证节只覆盖 overlay 路径**
   补上 sendinput 路径的回执形态，并把「未验证」的范围写清楚：
   验证的是「错误处理正确」，不是「点击落到目标窗口」。

3. **3.7 跨平台状态仍写「未做模式 A」**
   Windows 已实现两档注入；Linux 仍为 xdotool（会动真鼠标）。

## 修文档自身的缺陷
发现两个重复的 `### 4.3`（编辑时留下的同一设置页条目），已合并去重，
现在编号连续（4.1–4.6）。

## 补齐待办（4.6 其它已定位但未修）
以下均已核对代码确认属实，不是猜测：
  · overlay 模式键盘动作「必须先点过」可改为取前台窗口兜底
    （main.js:2283 / 2291 确为直接报错）
  · real 模式与 sendinput 行为重复，可考虑合并
    （main.js:2051 sendinput / 2189 overlay / 2324 起为旧 koffi 路径，
      real 与未命中两档时都会落到这里走 SetCursorPos）
  · p3.js / p4.js 是本轮遗留的临时补丁脚本（git status 确认为未跟踪），
    确认无价值后删除

判据未改动，npm test 131 条全绿。
 2026-10-02 15:35:27 +08:00
JianFeeeee
57bf942474 feat(gui): 注入改 SendInput（默认）+ 用户操作时暂缓；拆解 Coopanion 桌宠动作系统 
## 拆解 Coopanion（用户指出的参考项目）
新增 DESKTOP-PET-NOTES.md，记录 Pal-AI-Lab/Coopanion 的桌宠动作系统
（packages/cortico-world-desktop-pet）：

  · 4 个工具：pet_say(气泡说话,可夹带动作标记) / pet_ask(提问,异步回答) /
    pet_walk_to(走到 0-1 比例或 left/center/right/cursor,含走到鼠标位置) /
    pet_act(只做动作; sit/sleep 是持续态)
  · 动作词表 VOCAB：10 个表情 + 13 个动作，每个词多个中文别名，
    英文 id 与中文别名进同一张 Map；未知词丢弃而非报错
  · 脚本标记：【词,词】= 先做动作再换新气泡；<词> = 打字到那里时做、不换气泡。
    让文字与动作在时间轴上对齐 —— 实现成本低但表现力强
  · 设计要点：身体是 agent 唯一可见输出通道（用户看不见消息正文）；
    互动事件不单独唤醒模型，跟着下批事件到

可借鉴（已写入文档待办）：姿态表达状态、动作与文字对齐、持续态、
动作解析容错、待机自主行为。不建议照搬：桌宠承载全部对话输出、ASR、戳摸甩。

## 注入层改 SendInput（参考它的实现）
原 PostMessage 路径只能操作原生 Win32 程序 —— Chromium/Electron 自绘界面
与游戏会忽略合成消息。这不是「平台硬限制」，是所选 API 的限制。
Coopanion 用 SendInput 注入系统输入队列，可靠性高得多。

新增三档模式 gui-prefs.deviceBridge.agentCursor：
  sendinput（默认） SendInput，可靠；会动真光标，故先等用户停手
  overlay           PostMessage，不动用户鼠标；只能操作原生程序
  real              保留旧代码路径
另有 deferMs：用户活动时最多等多久（默认 3000，上限 10000）

★ SendInput 绝对坐标是 0–65535 归一化值，不是像素。按虚拟桌面归一化
  并带 MOUSEEVENTV_VIRTUALDESK，多屏下也正确（Coopanion 只按主屏归一化）。
★ 文本用 KEYEVENTF.UNICODE 逐字符发，不受键盘布局与输入法影响（比 WM_CHAR 可靠）。

## 修「用户活动感知」把自己也算进去的 bug
GetLastInputInfo 是**全局**的 —— agent 自己的 SendInput 也被算作「用户输入」。
实测：deferMs 设 0 仍被暂缓，回执写「开始时空闲仅 0ms」，即上一条命令的
注入刚把 idleMs 清零。若不排除自身注入，会永远处于「用户正在操作」状态。

按 Coopanion 的三重判定修正：
  1. ownTick   自己最后一次注入时刻，之后 40ms 内的输入忽略
  2. ownCursor 自己放下的光标位置，偏离 >2px 说明是用户动的
  3. 无符号差值  GetTickCount 每 2^32ms 回绕，必须按无符号比较

## 修同一条命令被执行两遍
sendinput 分支把逻辑包进 runAction 箭头函数，里面的 return 只退出它自己，
于是执行完继续 fall through 到旧 real 路径。实测 8 条命令回了 16 个
cmd_result，且真光标被额外抢一次。补上外层 return。

## 判据
computeruse.test.mjs 47 条（npm test 共 131 条全绿），新增 4 条钉住本轮
踩过的坑，均做变异验证：
  · 三档模式存在（overlay/real 只在条件里，不能要求赋值形式）
  · 用户活动排除自身注入；且盯 send() 里的**调用点** —— 只查函数名时
    删掉调用仍会误报绿（已实测并改正）
  · SendInput 坐标归一化 + VIRTUALDESK
  · sendinput 分支必须 return（防双执行）

## 待办（已写入 GUI-PLAN.md）
  · loadGuiPrefs 不透传 agentCursor，导致 deferMs 配置读取不生效（实测）
  · 显式调 SetProcessDpiAwarenessContext(-4)，不依赖 Electron 默认值
  · mascot 姿态：思考/等待/出错
  · 真实点击效果仍未验证（当前环境无可注入的可见窗口）
 2026-10-02 15:27:33 +08:00
JianFeeeee
f0a7ce23b1 feat(gui): 模式 A agent 独立光标 + 后台注入；修坐标换算；固化计划与交接文档 
## 模式 A：agent 独立光标（不抢用户鼠标）

现有 computeruse 走 SetCursorPos + mouse_event，agent 一干活就抢走用户
真实鼠标，用户无法同时使用电脑。现改为：GUI 自绘 agent 专属光标，实际
输入经 PostMessage 直接投递到目标窗口句柄，用户鼠标全程不动。

新增：
  cmd/gui/agent-cursor.js   透明置顶层窗口 + mascot 指针 + 移动/点击脉冲
                            动画；记录上次命中的 hwnd 供键盘动作使用
  cmd/gui/agent-inject.js   Windows 后台注入：WindowFromPoint 定位、
                            客户区坐标换算、PostMessage 投递鼠标/键盘/
                            滚轮/文本；拖拽分步移动

配置 gui-prefs.deviceBridge.agentCursor.mode = "overlay"(默认) | "real"。

明确的设计边界（不是实现缺陷，是平台限制）：
  · 只对「接受窗口消息的程序」可靠。原生 Win32 程序可靠；Chromium/
    Electron 自绘界面、游戏、DirectX 会忽略合成消息。
  · 不做真实鼠标降级。用户既选了不抢鼠标，就不该偷偷改成操作真鼠标，
    失败即 status=error 并说明原因。
  · 键盘类动作依赖先前的鼠标操作（后台注入不动真光标，
    GetCursorPos 拿到的是用户自己的光标位置）。

端到端 8/8 正确响应；「真实点击是否落到目标窗口」因当前环境无可注入的
可见窗口而未验证，已在 GUI-PLAN.md 列为待办。

## 修坐标换算（我自己上一轮引入的 bug）

上一轮我加了 rawX / scaleFactor 的换算，理由是「SetCursorPos 期望 DIP」。
**那个前提是错的** —— Electron 主进程是 per-monitor DPI-aware，Win32 坐标
不做虚拟化。实测：

  Electron screen API (DIP) : 1260 x 840   scaleFactor=2
  GetSystemMetrics          : 2520 x 1680
  SetCursorPos(200,200) -> GetCursorPos 读回 (200,200)   恒等，不缩放

加 /scale 会把原本正确的点击改坏：200% 屏上点 (600,400) 被送到
(400,267)，越靠右下偏得越远。已改回 physical ? rawX : rawX*scale，
drag 终点同步修正（原先两处换算不一致）。

易误判之处：在普通 node 进程里测同一函数读到的是 1260x840（虚拟化值），
会以为 Win32 用 DIP —— 必须在 Electron 内测。

## 判据
computeruse.test.mjs 43 条（npm test 共 127 条全绿），新增 5 条钉住
模式 A 的核心承诺：
  · agent-inject / agent-cursor 均无 SetCursorPos 调用（查前先剥注释，
    因为注释里会引用该名字解释「为什么不用它」）
  · koffi 指针参数用 Buffer（普通对象不写回，会拿错 hwnd）
  · overlay 默认开启且可切回 real
  · 自绘光标层 setIgnoreMouseEvents 穿透
核心不变量已做变异验证：注入 SetCursorPos 后判据立即转红。
另修正坐标判据方向（原判据断言 /scale 是对的，与实测相反）。

## 文档
GUI-PLAN.md          改造计划与进度的单一事实来源：已完成/待办、坐标
                     实测结论与踩坑、koffi 3.x 使用约定、端到端测试方法、
                     环境注意事项（含本机无 Go 工具链、waiter 改动未编译验证）
SERVER-HANDOFF.md    服务端需同步的部分：放开 action 白名单（schema enum
                     + switch default 双重限制，不改则 11 个新动作下发不到）、
                     透传 tox/toy/steps/dx/ms、统一 scroll 方向语义、
                     写入坐标约定防重蹈
 2026-10-02 14:12:32 +08:00
JianFeeeee
d6dd84e1c8 fix(gui): 启动期误判服务端未启动；keybd_event 类型名致组合键全废 
## 修 GUI 反复误判「服务端未启动」
isServerRunning() 硬编码 http://localhost:8080/。实测该部署下服务端在
192.168.2.60:8080（homed 跑在 WSL 里）：
  localhost:8080      -> 000 连不上
  192.168.2.60:8080   -> 302 正常

于是每次启动都：探测失败 → 误判服务没起 → 去 startHomed() 拉起 GUI 旁
并不存在的 homed.exe（findHomed 返回 null 就 skip）→ 再 waitForServer()
干等 8s 超时 → 打印 "homed failed to start within timeout"。
gui.log 里这条 ERR 累计出现 53 次，是日志里唯一的错误项。

改法：
  · serverProbeTargets() 按「connections.json 里已配置的连接（当前连接
    优先）→ localhost」顺序探测，命中任一即视为在线
  · 服务可达时直接 skip homed 自动拉起
  · 无本地 homed 可执行文件时不再空等超时，直接说明情况
  · probeOne 加超时保护，避免启动被挂住

实测：修复后启动日志为 "server reachable, skip homed autostart"，
该 ERR 不再出现。

## 修 keybd_event 类型名（组合键整体失效）
koffi 不认 Win32 的 `byte`：
  "void keybd_event(byte bVk, ...)"
    -> Error: Unknown or invalid type name 'byte'
  "void keybd_event(uint8 bVk, ...)"  -> 正常

原代码用的正是 `byte`，且整段包在空 catch 里，于是 keybd_event 恒为 null，
所有组合键（keypress/hotkey）都返回 "keybd_event unavailable"。
这个 bug 很难被发现：单键 click/move/scroll 走 mouse_event，不受影响。

端到端实测确认：修复前 hotkey ctrl+shift+t 报
  computeruse hotkey: keybd_event unavailable
另外签名解析失败现在会打日志，不再静默。

## 判据
computeruse.test.mjs 扩到 38 条（进 npm test，全量 121 条全绿），新增：
  · keybd_event 签名类型（且已做变异验证：改回 byte 判据立即转红）
  · 服务探测不只探 localhost / localhost 仅兜底 / 仅当有 homed 才拉起
  · 服务可达时 skip autostart / 探测有超时保护
 2026-10-02 13:03:17 +08:00
JianFeeeee
40119e8116 feat(gui+waiter): computeruse 补高级操作、修 HiDPI 坐标；记录 PiDeck 借鉴 
## computeruse 高级操作
此前两端（GUI 本机桥 / waiter 设备侧）都只有 9 个基础 action
（click/move/scroll/keypress/type…），与业界 computer-use 的基本盘差距明显。
现补到 18 个，两端对齐：

  drag          拖拽（分步移动，见下）
  hover         只悬停不点击（触发 tooltip / 悬浮菜单）
  mousedown/up  按下与释放分离，可配对做「按住」
  tripleclick   三击选中整行
  middleclick   中键
  hotkey/combo  组合键（ctrl+c 这类）
  wait/sleep    显式等待，等 UI/动画完成再下一步
  display       显示器几何（bounds + scaleFactor + primary），多屏定位必需

★ 拖拽**分步移动**（默认 12 步，上限 60）而不是一步到位：canvas 拖拽、
列表排序、滑动条这类应用依赖中间 mousemove 事件，一步到位会失效。

## 修 HiDPI 坐标错位（GUI 侧）
截图给模型的是**物理像素**，而 SetCursorPos / xdotool / cliclick 期望
**逻辑点(DIP)**。旧代码只加了 display bounds 的原点偏移，完全没换算
scaleFactor ⇒ 150% 缩放屏上点击系统性偏移（越靠右下偏得越多）。

现在按目标屏 scaleFactor 换算，并提供 `physical:false` 让调用方声明
「坐标已是逻辑点」以免二次换算。

## 组合键归一化（waiter 侧）
旧实现把模型给的 key 字符串原样丢给 `xdotool key`，于是 "Ctrl+C"、
"ctrl + c"、"CTRL-C" 全部失效。新增 normKeySpec：统一 + 与空格分隔、
统一小写、去重复修饰键。

顺带修 waiter 的 `type`：加 `--clearmodifiers`，避免残留的 Ctrl/Alt
把后续输入变成快捷键（旧实现一次输入就可能污染后续所有按键）。

## scroll 修正（两端）
旧实现固定滚 `click 4/5`（上/下），忽略方向语义也不支持横向。
现按 dy 正负给方向、按量级分步、支持 dx 横向滚动。

## 显式声明借鉴 PiDeck
用户要求声明 GUI 借鉴了 PiDeck 的设计与实现。做法：

1. 新增 `cmd/gui/DESIGN-NOTES.md` —— 逐项列出借鉴自 PiDeck 的设计
   （三点渐次明暗 / 运行态呼吸光晕 / 工具调用分组卡）、PiDeck 的原始
   实现（@keyframes 名与 CSS 片段）、HomeAgent 的落地位置、以及**动机**，
   并明确区分「本仓自行决策」的部分（如「只有 1 个工具时不分组」是本地决定，
   不是 PiDeck 做法）。
2. app.js / style.css 的相关代码处补出处注释。
3. 判据 computeruse.test.mjs 钉住这几条声明，防止后续丢失。

参考方式为阅读 PiDeck 打包产物 app.asar 中的 CSS 实现后**独立重写**，
未复制其代码或资源文件。

## 判据
新增 cmd/gui/computeruse.test.mjs（进 npm test），30 条断言：
  · 两端各 9 项高级操作
  · HiDPI 换算与 physical 开关
  · 组合键归一化、type 的 --clearmodifiers
  · 拖拽分步移动（两端）
  · PiDeck 借鉴声明四处（含 DESIGN-NOTES.md 存在）

判据：cmd/gui npm test 全绿（114 条）。
 2026-10-02 11:10:53 +08:00
JianFeeeee
bf06ad029a feat(gui): 加载动画改三点式 + 新增系统通知 
## 1) 加载动画：边框旋转 → 三点渐亮
旧实现是 border + rotate 的 spinner，用在 .loading(16px) /
.loading-spinner(32px) / .live-spinner(15px) 三处。在消息气泡里刺眼，
且语义不对：旋转暗示"正在加载某个确定的东西"，而 agent 思考没有进度。

参考 PiDeck（@deepseek-ai/dsh-web-frontend 与 mermaid bundle 里的
@keyframe 实现）改为「等距三点 + 透明度递减 + 轻微上浮」：
  haDots      三点错峰明暗（1/0.6/0.35/0.15）
  haDotFloat  单点上浮 + 缩放
  haSweep     横向扫光
旧类名 .loading / .loading-spinner 保留为别名指向新动画（还有 6+ 处
调用点，逐处改 HTML 容易漏），并解除其 animation 以免残留旋转。
7 处调用点统一换成 <i>x3 结构。

## 2) 系统通知（此前完全不存在）
主进程无 Notification、preload 无接口、渲染层只有页面内 toast
（用户不盯着窗口就看不到）。补齐一条完整链路：
  main.js  notify:show / notify:supported 两个 IPC + 原生 Notification
  preload  notify.{show,supported,onClicked}
  app.js   notifyTurn / notifyTurnOnce / onNotifyClicked

设计取舍（都写进注释）：
· **一轮只通知一次**。SSE 的 tool_call / stage / agent_output 都可能
  判定"一轮结束"，用 turnSig 去重，否则连弹好几次。
· **不在流式过程中逐 token 通知**。一轮可能几十个 delta，那是噪音；
  用户要的是"有结果了"。
· **窗口在前台且聚焦时不弹**。正看着界面时弹窗只会烦人。
  静默启动（窗口 hidden）正好走"要弹"这条 —— 这也是静默后唯一
  能让用户知道"agent 回了"的途径。
· **挂在 SSE 的 agent_output 收尾处**，不挂 endChatTurn()：
  后者开头 `if (!state.chatLoading) return`，而旁观路径
  （agent 响应 memo/QQ/email，GUI 只收 SSE）chatLoading 恒 false，
  根本走不到那里。挂 SSE 对"自己发"与"旁观"两条路径都生效。
· **点击通知会 show() + 回传渲染进程**，切到 chat 视图并滚到该条。
  点了却不知道该看哪句话等于没通知。
· 正文超 180 字截断，避免通知被撑爆。

## 判据
新增 cmd/gui/loading-notify.test.mjs（进 npm test），24 条断言覆盖
动画关键帧/错峰 delay/别名解除/调用点结构，以及通知链路的六段
（主进程 IPC、preload 桥、去重、挂载位置、点击跳转、可用性探测）。

## 实测
重新打包安装：186 文件 0 处不匹配，exe 188834816 字节
启动正常：silentStart 生效、login 200、device/online 200、
graph/pulse 轮询、0 个 401 / JS 错误。

判据：cmd/gui npm test 全绿（84 条）。
 2026-10-02 10:40:35 +08:00
JianFeeeee
8847ce4cfd fix(gui): 修发行打包的图标与资源漏装（Linux 包会缺星图依赖） 
## 背景
上一提交修了 electron-packager 那条路径的 exe 图标。本提交处理另外两处
同类问题——**都是静默失败**：改了没人知道，坏了要等用户装上才发现。

## 1) package.json build 段（electron-builder 路径）
  · files 白名单漏了 icon.ico / icon-tray.png / icon-tray@2x.png
    ⇒ 这些文件不会被打进包，托盘与窗口图标在发行版里丢失
  · 补 win.target/win.icon；注意 electron-builder 的 icon 路径相对
    **项目目录**（package.json 所在）解析，不是相对输出目录
    （最初写成 'build/icon.ico'，那会找不到文件 —— 已用存在性判据钉住）
  · icon.ico 含 256x256，满足 electron-builder 对 win 图标的要求

## 2) deploy/packaging/package-linux.sh（Linux 发行实际走这条）
  原实现手工 cp 七个文件：
    main.js / preload.js / package.json
    renderer/{index.html, app.js, style.css, mascot.svg}
  实测漏掉：
    · renderer/mascot.svg        —— 源码里根本不存在（真名 mascot.webp）
    · icon.svg / icon.ico / icon-tray*.png
    · renderer/icon.svg
    · renderer/vendor/*          ★★ 本次本地化新增的四个第三方库
                                  （three/OrbitControls/marked/purify）
                                  ⇒ Linux 发行包装完星图与 Markdown 渲染直接坏，
                                    且**没有任何构建报错**

改为：
  · renderer 按目录整体同步（cp -r "$gui_dir/renderer/."）
  · 根级 *.svg / *.ico / icon-tray*.png 同步
  · 新增必备文件校验：vendor 四库与 icon.svg 缺任一 ⇒ 报错并删目录跳过，
    沿用本脚本既有的"宁可不发，也不发装了跑不起来的包"原则

## 判据
新增 cmd/gui/package-config.test.mjs（进 npm test），14 条断言覆盖三条
打包路径的配置一致性。已做变异测试：Makefile 去 --icon、files 去 icon.ico、
package-linux.sh 还原逐文件 cp，三者均判红。

判据：cmd/gui npm test 全绿（60 条）。
 2026-10-02 10:25:43 +08:00
JianFeeeee
46a600c01b fix(gui): 打包未传 --icon，exe 内嵌图标一直是 Electron 默认图标 
## 现象
GUI 的 exe 图标不正确（显示为 Electron 默认图标）。

## 根因
Makefile 的 build-gui 调electron-packager 时**没有 --icon 参数**：

    npx electron-packager . homeagent-gui --out=... --no-sandbox

electron-packager 默认不写 exe 资源图标，于是 exe 保持 Electron 自带图标。
仓库里 cmd/gui/icon.ico 一直存在且完全合法（file 识别为
"MS Windows icon resource - 7 icons, 16x16, 24x24"），只是从未被打包进去。

注意这是**两条独立的打包路径**：
  · electron-packager（make build-gui，本机/开发用）→ 靠 --icon 参数
  · electron-builder（package.json 的 build 段，发行用）→ 靠
    build.linux.icon，且 files 数组里也没列 icon.ico
本次只修前者（本地安装与实测走这条）。

## 证据
重新打包前后 exe 大小：
  188784128  →  188834816   （+50688 = 7 个尺寸的图标资源）
此前多次打包产物大小完全一致，可反证图标从未被写入。

## 改动
build-gui 补 --icon=icon.ico。托盘图标无需改动：它走
Tray/nativeImage，按 icon-tray@2x.png → icon-tray.png → icon.ico
三级候选回退，文件都在且逻辑健壮。

## 实测
重新打包并安装：184 文件 0 处不匹配，exe = 188834816 字节
启动正常：prefs.silentStart=true → 4 进程 0 可见窗口、
login 200、0 个 401 / JS 错误。
 2026-10-02 10:19:18 +08:00
JianFeeeee
58ad6831f5 fix(gui): 静默启动开关此前是死设置，永远不生效 
## 现象
设置页有「静默启动」开关，文案写着「启动时不显示主窗口，驻留托盘
后台运行」，勾选后启动 GUI 照样弹窗。

实测（本机，gui-prefs.json 里 silentStart=true）：窗口标题 HomeAgent
照常出现。

## 根因
silentStart 从未被消费：
  · main.js 的 loadGuiPrefs() 把它读进对象
  · 渲染层设置页读写它
  · **但主进程没有任何地方读它做判断** —— whenReady 无条件 createWindow()
是个纯粹的界面开关，接线缺失。

## 改动
1) createWindow(show = true)：支持「创建但不显示」。
   BrowserWindow 初始 show:false，非静默时经 ready-to-show 显示
   （避免先显示再隐藏的闪烁）。

   ★ 为什么静默时**仍然创建窗口**、而不是不创建：
     不创建 ⇒ 渲染进程不启动 ⇒ app.js 整个不执行 ⇒ SSE 通道、
     设备桥轮询、聊天全部失效，GUI 退化成纯托盘图标；且
     showMainWindow() 只做 show()、不会创建窗口，app.on("activate")
     又只在 macOS 触发 —— Windows 上托盘点「显示主界面」将毫无反应，
     进程变成唤不起来的僵尸。已按此结论实现（评审时确认为「创建后隐藏」）。

2) whenReady 读 silentStart 并据此 createWindow(!silent)。
   与 applyAutoLaunch 里的 openAsHidden 是两条不同路径：那个告诉 OS
   「开机自启时如何启动」，这里决定本进程要不要显示，对手动启动同样生效。

3) showMainWindow() 增加兜底：窗口不存在时重建；隐藏时先 show 再 focus。
   消除上述「唤不起来」的隐患。

4) loadGuiPrefs() 补去 UTF-8 BOM。
   ★ 这是排查中发现的**第二个真实缺陷**：Windows 工具
   （PowerShell Set-Content -Encoding UTF8、记事本）改过 gui-prefs.json
   会写入 BOM，而 JSON.parse 遇 BOM 直接抛错 → 走 catch → 返回**默认
   prefs** ⇒ silentStart/exitToTray/deviceBridge 全部被静默重置，
   表现为「开关保存了但不起作用」。loadConnections 早就有去 BOM 处理、
   这里没有，两个读取点不一致。
   （本次实测正是被自己的判据脚本用 Set-Content 改 prefs 后踩到的。）

## 判据
新增 cmd/gui/silent-start.test.mjs（进 npm test），14 条断言：
  · whenReady 确实读 silentStart 并决定 show
  · 静默路径仍创建窗口（不许退化成不建窗）
  · showMainWindow 能在窗口缺失时重建
  · loadGuiPrefs 去 BOM，且 loadConnections 的既有处理不回退
已做变异测试：还原成无条件 createWindow()、抽掉 BOM 处理，均判红。

## 实测（本机 Electron，真实 prefs）
  silentStart=true  → processes=8 visibleWindows=0，日志出现
                      [startup] silentStart=on: window created hidden
  silentStart=false → processes=4 visibleWindows=1（标题 HomeAgent）

判据：cmd/gui npm test 全绿（46 条）。
 2026-10-02 09:47:11 +08:00
JianFeeeee
5a00361d8e docs(ci): GUI job 注释同步为五个 .mjs，补 connections-io 说明 2026-10-01 23:17:39 +08:00
JianFeeeee
e3c81269b6 fix(gui): 连接配置不再被空/半截文件覆写，保存改原子写 
## 现象
connections.json 变成 {"connections":[],"currentId":null}，
用户的连接列表全部丢失（2026-10-01 实测）。

## 根因：两个缺陷叠加
1) loadConnections() 的损坏恢复分支无法区分两种情况：
     · 文件内容确实损坏        → 备份+重建（合理）
     · 读到空/半截内容        → **也走同一条路，覆写成空配置**
   第二类真实会发生：saveConnections() 用非原子 writeFileSync 截断重写，
   落地过程存在「已截断、未写完」窗口；此刻任何一次读取拿到半截内容，
   JSON.parse 抛错 → 用户配置被永久销毁，且没有二次确认。

   实测（沙箱跑真实函数）：空文件 -> 返回空配置，
   **并把文件改写成 {"connections":[],"currentId":null}**。

2) 损坏备份只写一个固定的 .bak，反复损坏会把上一份真实配置覆盖掉，
   于是「唯一的退路」也丢了。

## 改动
1) loadConnections()：raw.trim()==="" 视为「尚未配置」，
   直接返回空配置，**不覆写、不备份**（BOM/纯空白同样处理）。
2) saveConnections()：改为原子写 —— 先写同目录 .tmp-<pid>，
   再 renameSync 覆盖。rename 在同卷内原子，读者只会看到改写前
   或改写后的完整文件，从根上消除产生半截内容的竞态；失败时清理 tmp。
3) 真损坏的备份名带时间戳（connections.json.corrupt-<ISO>.bak），
   反复损坏不再互相覆盖。

## 判据
新增 cmd/gui/connections-io.test.mjs（进 npm test）：
在 node:vm 里抽出 main.js 的**真实函数**执行，11 条断言覆盖
合法/空/纯空白/损坏/原子写残留。已做变异测试：删掉空文件守卫、
把备份名改回固定 .bak，均被判红。

## 实测（本机 Electron + 真实凭据）
  正常启动：connections.json MD5 前后一致（E8DD588F...），0 个 tmp 残留
  人工清空后启动：文件被自愈填充回真实配置，而非覆写成空

判据：cmd/gui npm test 全绿（32 条）。
 2026-10-01 23:16:49 +08:00
JianFeeeee
ee2d43dcbc perf(gui): 流式渲染判据改看 _streaming，不再依赖 chatLoading 
## 现象
旁观 agent 响应其它渠道（memo / QQ / email）时，聊天页每秒全量重渲多次，
消息越多越卡。

## 根因
流式分支判据写的是 `state.chatLoading && ...`，而 chatLoading 只在
「用户从 GUI 自己发消息」（sendChat）时置 true。旁观路径（agent 响应
memo/QQ/email，GUI 仅通过 SSE 收流式帧）下它恒为 false ⇒ 判据恒假 ⇒
每个 content_delta / reasoning_delta / tool_call 帧都掉进「非流式」分支，
走**全量** innerHTML 重建。

而且它出现**三处**，只改一处无效：
  · rerenderChatIfActive（决定走 renderChatStreamChunk 还是 renderChat）
  · renderChat 内部的 streamingLast（决定单条消息的渲染分支）
  · 工具 pill 的「进行中」收集（旁观时列表恒空，看不到 agent 在做什么）

## 实测（本机 Electron + 192.168.2.60，真实凭据，同一条消息）
  修复前：1.7~2 秒内 13~26 次全量重渲，间隔 10~30ms
  修复后：同一场景降到 5 次（含轮询触发的）
200 条消息时单次全量重建实测 235ms —— 这是「聊天卡得没有用的欲望」的直接来源。

## 改法
所有 SSE 流式帧创建的 assistant 消息都带 _streaming:true
（content_delta / reasoning_delta / tool_call / agent_output 五个 push 点），
收尾时才置 _final。所以正确判据是「最后一条是尚未收尾的流式 assistant」，
即用 last._streaming 取代 state.chatLoading。

保留 chatLoading 的两处语义不同，未动：
  · 「思考中」占位气泡：只在用户自己发消息后等待时显示，旁观不需要
  · sendChat / interruptChat 自身的并发保护

判据：cmd/gui npm test 全绿。
 2026-10-01 22:02:37 +08:00
JianFeeeee
60f51f40e0 fix(gui): 设备接口补设备令牌，设备页不再恒 401 
## 现象
GUI 设备页长期空白。日志每 15s 一条：
    GET 401 /api/v1/device/online

## 根因：/api/v1/device/ 命名空间下并存两套鉴权
  · /device/gateway    注册在 webui 插件，走 requireAPI，认 session cookie
  · /device/online、/device/、/device/push
                       注册在 remotedevice 插件，走 requireToken，
                       **只认 X-API-Key 头或 ?token=，完全不认 cookie**
实测可区分：cookie 401 与错 token 401 的响应体都是纯文本
"unauthorized"，而 webui 鉴权返回 JSON {"error":...}。

所以 GUI 只带 cookie 时：gateway 200、online 401 —— 同一连接同一
时刻，现象自相矛盾。

## 三种能工作的客户端做法一致，GUI 两样都没做
  · WebUI 浏览器：cookie 进内核，reverseToUpstream 注入
    deviceGatewayToken（handler_device.go:118）
  · waiter：客户端自己带 X-API-Key（gateway_discover.go:103）
  · GUI：既没注入、也没自带 ⇒ 设备页恒 401，且异常被 catch
    吞掉置空数组，界面与「确实没有设备」完全一样

## 改动
1) main.js：device-bridge:get 回传 token 明文（此前只有 tokenSet
   布尔，渲染进程永远拿不到）。明文本就存在本机 gui-prefs.json，
   不新增密钥存储面，且不落日志、不进 URL。
2) app.js：新增 isDeviceTokenPath / deviceApiKey，对设备接入面
   端点附加 X-API-Key（优先连接自身 apiKey，退回设备桥 token）。
3) app.js：新增 ensureDeviceToken，并**在首次 /device/* 请求之前**
   调用 —— 此前令牌加载排在 /device/online 之后，顺序正好反了。
4) app.js：401 时记下可读原因（deviceAuthHint），设备页顶部渲染
   红色提示卡，不再把鉴权失败伪装成「没有设备」。
5) app.js：网关发现加缓存，并从每 15s 的 refreshAll 轮询里移出
   （改为按需 + 切连接/手动刷新时重取）。网关地址是服务端配置的
   慢变量，15s 拉一次没有意义；此前它与 online 同秒重复调用。

## 实测（本机 Electron，192.168.2.60:8080，真实凭据）
  修复前：device/online 恒 401，设备列表空
  修复后：device/gateway 1 次（之后走缓存）
          device/online  每 15s，全部 200，返回 waiter-fnnas /
          waiter-mainnas 两台设备
          401 计数 0

判据：cmd/gui npm test 全绿。
 2026-10-01 20:24:55 +08:00
JianFeeeee
53d9af446c feat(gui): 星图接上 /memory/graph/pulse + 前端依赖本地化 + 端点对齐门禁 
GUI 与服务端 WebUI 插件共享同一套 REST 接口，但两边独立演进、没有任何
强制手段。这次核实发现三处真实漂移（服务端 42 路由 / GUI 只用 29）。

1) 星图接上服务端专为它造的轻量活动端点
   服务端 handleMemoryGraphPulse 的注释写了动机：生产实例全量图谱
   408KB / 1151 节点，为了「知道哪些节点是新的」而每 N 秒拉全量是把
   带宽和 JSON.parse 全花在重复数据上；pulse 只回 id+name+type+
   mention_count+updated_at，几百字节 ~ 几 KB，差两个数量级。
   WebUI dashboard 接了它，GUI 此前只在初始化拉一次全量且完全不轮询
   ⇒ 星图停在打开那一刻的快照，agent 后来学的东西它永远看不到。
   现接入：/runtime 3s + /memory/graph/pulse 10s，两路轮询幂等、
   切连接时停；新实体标「生长」；SSE 的 tool_call/stage/agent_output
   也会触发脉冲（用工具名与回复前 60 字当 hint，让点亮落到本轮相关实体）。
   pulse 检出「全量图里没有的新实体」时置脏，由下一次 renderChatStarmap
   惰性重拉全量 —— 不在脉冲回调里直接拉，否则会把轻量活动源变成每 10s
   拉一次 408KB 全量，正好是 pulse 端点要消除的浪费。

2) 前端依赖本地化，顺带修掉一处安全边界
   四个库从 internal/plugins/webui/static/ 复制到 renderer/vendor/
   （字节一致，由门禁钉住），index.html 不再引用任何公网 CDN。
   与服务端同一理由（见 webui/starmap_vendor_test.go 的注释）：
   HomeAgent 支持离线/内网部署，换 CDN 只是把同一个赌注重下一遍。
   ★ renderMd() 的净化器缺失分支不再回退到手写正则（剥 <script>/on*=/
   javascript:）—— 那不是完备的 HTML sanitizer，漏 <iframe srcdoc>、
   SVG 内联事件、data: URI 等，而它渲染的是模型输出与记忆文本，
   都算不可信输入。现在直接退纯文本：库已本地化，走不到该分支。

3) 新增 endpoint-align.test.mjs（进 npm test / CI）
   扫描 app.js 的 api("...") 与 handler.go 的 mux.HandleFunc 对账，
   7 条判据。与既有判据同一路子：读真实源码，不抄逻辑重写。
   反向差集只报告不门禁（管理面端点接不接是产品决策），
   只硬钉「服务端已明确为其设计」的 pulse —— 即本判据的由来。
   已做变异测试：改错 pulse 路径、改回 CDN 均能判红。
   protocol-align.test.mjs 是真浏览器判据（需 Electron+Xvfb+真后端），
   CI 明确不跑，所以这类漂移此前无人发现。

顺带：connectSSE 由隐式全局赋值改为 function 声明（加 "use strict"
会在文件靠后处 ReferenceError，报错点离调用点很远）。

判据：cmd/gui 下 npm test 全绿（4 个 .mjs / 25 条）。
 2026-10-01 18:23:20 +08:00
JianFeeeee
a39e316e45 docs(ci): 记录 cmd/gui 假告警的根因与本机补丁（手册 §6） 
每轮编辑后 pi-lens 都会报 `FAIL ./cmd/gui [setup failed]`，看着像仓库有测试红了，
实为工具缺陷。本会话内重复触发 20+ 次，每次都需人工复核，故完整记录并修掉。

根因（两个缺陷叠加）：
  1. pi-lens 的 runner 按**仓库根**检测（本仓有 go.mod ⇒ go），但被测文件可能
     在另一种语言的项目里；`cmd/gui/*.test.mjs` 命中通用测试命名 ⇒ 对纯 Electron
     目录生成 `go test -run . ./cmd/gui` ⇒ 必然 "no Go files" 失败。
  2. 该失败进入进程内 failedTestsByRunner，而 failed-first 策略此后**每次**编辑
     都优先重跑它（与当前编辑的文件无关）；条目只在测试**通过**时移除 ⇒ 永不自愈。
     日志形态：turn_end: README.md → test go cmd/gui/sse-backoff.test.mjs (failed-first)

为什么不能靠配置关掉（都实测/读码确认）：
  - `.pi-lens.json` 是项目级，只认 ignore/rules/maxProjectFiles/reviewGraph/trivy
    + 三个改动开关；`tests` 是全局级，写进去会被忽略并告警。
  - 全局 `{"tests":{"enabled":false}}` 会一起关掉**所有项目**的回合末测试反馈，
    为一个仓库的误报付全局代价 —— 不值。
  - `ignore` 也挡不住：它只作用于扫描，不参与测试目标选择。

修法：给 pi-lens 的 getTestRunTarget 加一道「该 runner 真能跑这个目标吗」的校验
（go：目标目录至少有一个 .go 文件），不能跑就拒并清掉那条不可运行的失败记录。
runTestFileAsync 只有这一个调用点，是唯一收口。

验证：node --check 过语法；/usr/bin/diff 核对为纯新增零删除；
真实路径模拟 6/6 符合预期（cmd/gui 的 .mjs → 拒；真 Go 测试文件 → 放行）；
go test ./... 仍 43 包全绿。

注意：补丁在 ~/.pi/agent/npm/... 里，pi-lens 升级后会被覆盖（届时误报会回来，
不影响仓库，只是噪音）。备份 index.js.orig-*，回退方式写在本节。

本手册同时补上 §6.1 症状 / §6.2 根因 / §6.3 配置为何无效 / §6.4 修法与回退。
 2026-09-29 21:24:09 +08:00
JianFeeeee
6b0bc00d40 docs: 主仓 README 补在线文档入口（介绍站 + SDK 文档站） 
与 SDK 仓同一个问题：主仓 README 的「文档」章节只列了仓内 markdown
（assets/docs/...），没有任何**在线**地址 —— 而主仓 README 正是绝大多数人
的第一入口，从它走不到介绍站与 SDK 文档站。

改为两段并列：
  **在线文档**：介绍站 + SDK 文档站（含 llms.txt / llms-full.txt 的 agent 直读入口）
  **仓内文档**（随代码版本走）：原有的 OVERVIEW / ARCHITECTURE / PLUGIN_DEV 等

分开标注是有意的：在线站与内核版本**不严格对齐**（站点按发布节奏更新），
而仓内文档跟代码走。写清楚归属，读者才知道该信哪个。

中英文两份同步；两处 README 的 7 个 URL 全部实测 200。
 2026-09-29 20:52:32 +08:00
JianFeeeee
b9780954d0 docs(ci): 记录 GITCODE_TOKEN 已配置及其验收方式 
原 3.6 节只写「未配置时该 job 显式跳过」，读起来像是一直没配。补上实际状态：
两仓 secret 均已配置（值取自 ~/.git-credentials 的 gitcode 条目），
配置命令走 stdin（避免 token 出现在进程列表），以及三道等价验收 ——
因为 sync job 只在**新版本**发版时运行（prepare.outputs.exists == 'false'），
历史 tag 触发不了，无法用旧版本实跑，所以要用等价命令验：

  ① gh secret list 确认 secret 在
  ② /api/v5/user 确认 token 有效
  ③ 带 private-token 头读 release 确认 job 用的鉴权方式可用（两仓都测）

并记下一条待改进项：该 token 是**宽范围个人令牌**（可读 92 仓/48 私有、有写权限），
而 CI 只需这两个仓；更稳的是换一枚仅限这两仓的令牌，把 CI 泄漏的影响面收窄。
当前按用户 2026-09-29 的决定保持原状。
 2026-09-29 17:42:46 +08:00
JianFeeeee
573c84baa5 docs: 补上最后两处历史 SDK 链接的迁移（v1.1.0 tag） 
README 里还剩 1 处、README_EN 里 1 处指向 gitcode.com 的 SDK v1.1.0 release 链接。
核查后确认：GitHub 的 SDK 仓**只有 tag 没有 release**（releases 数为 0），
所以不能照抄「releases/tag/...」的路径 —— 改指 tag 页 tree/v1.1.0，
实测 HTTP 200（gitcode 侧同样仍可用，两边都保留可达性）。

至此两份 README 的 gitcode 链接归零。
 2026-09-29 17:30:56 +08:00
JianFeeeee
fb32d51aad docs(deploy): 手册补「本机 diff 是坏的」—— 比对判据的硬前置 
这条已骗过两次（openai.lua、两版 release.yml），今天又骗了第三次，且这次
后果最重：它把部署脚本的比对判据整个架空成假绿灯。

补进手册 0.1 节（放在拓扑之后、各部署章节之前，因为它是所有比对的前提）：
  - 结论：一律 /usr/bin/diff 或 cmp，不要裸 diff
  - 三条可自证真伪的单行命令（含 cmp 未被污染这个事实）
  - 为什么比「偶尔报错」危险：部署判据假绿灯 ⇒ 站点永久不再更新
  - ★ 判据自检的通用写法（拿必然不同的输入验判据，不过就退出）
  - 同类信号表：diff 说无差异但 wc -c 说大小不同 / 报一致但线上明显是旧的 /
    测必然不同的样本却报相同
  - 远端 diff 健康，但嵌在 ssh "…" 里要分清本地还是远端执行
 2026-09-29 17:25:51 +08:00
JianFeeeee
fe6f898159 fix(deploy): 站点比对判据被坏 diff 静默架空（假绿灯） 
deploy-sdk-site.sh 的 7 处本地比对用的是**裸 `diff`**，而本机 PATH 首位是
/opt/huawei/harmonyos/ohos-sdk/linux/toolchains/diff —— 它对**任何**输入都
返回 0 且无输出。后果不是「偶尔报错」，而是：

    --check 永远打印「✓ 线上与本机源逐字节一致」
    ⇒ 永远判定「无需部署」⇒ 站点改完再也不会被更新，且完全看不出来

实测凭据（本次）：site/index.html 本地 f8898cfc…、线上 cc615cfa…，
两边**确实不同**，而 --check 报「逐字节一致」；用两个必然不同的小文件
（A / B）验证，坏 diff 退出码 0、/usr/bin/diff 退出码 1。

修法（两层）：
  1. 钉绝对路径 DIFF=/usr/bin/diff，7 处本地比对全部改用它；
  2. **启动自检**：拿两个必然不同的输入验证一次，若它仍报「无差异」
     就直接退出，而不是继续拿一个坏判据去做部署决定。
     （同源的教训：「探针不红先怀疑探针」——判据本身坏了，
       它给出的「没问题」毫无意义。）

远端那一处保持 `diff` 并在旁边写明理由：远端是健康的 /usr/bin/diff，
不在本机这个坏 PATH 的影响范围内。

顺带补两个选项：
  --introduce         只部署 introduce 站。改 site/ 时用 —— 原 do_deploy 会先把
                      SDK 文档站重建一遍（apidoc + mkdocs，106 文件），而 site/
                      的改动跟它毫无关系，既慢又把没必要碰的线上站卷进变更面。
  --rollback-introduce 对称的回滚入口（原先只有 sdk 站能回滚）。

验证：--check 现在能正确报出差异（附带两份 md5 对照）；--introduce 走完
「先比对→打包→备份→原子替换→回验」，线上 md5 与本地一致，http 200。
 2026-09-29 17:23:17 +08:00
JianFeeeee
ed7fb3c6d9 chore: 排除 pi-lens 对 cmd/gui 的 Go 测试误报 
cmd/gui 是纯 Electron/Node 目录：0 个 .go 文件、无 go.mod、`go list ./...`
匹配 0 个包，它的测试入口是 package.json 里的 `node *.test.mjs`。

但 pi-lens 的 test runner 在写文件时按**仓库主语言**（Go）为所在目录跑测试，
而 cmd/gui/*.test.mjs 被识别成测试文件 ⇒ 它对一个纯 Node 目录执行
`go test ./cmd/gui`，必然得到 `no Go files ... [setup failed]`，
却被报成「测试失败」。本会话内重复触发 13 次，每次都要人工复核一遍。

排除触发源（而非关闭 tests.enabled —— 那是**全局**开关，会一起削弱所有真实
项目的测试网）。.mjs 的真实运行方式是 `npm test`，CI 的 GUI job 已在跑。

上游缺陷：runner 应先确认目录内存在该语言的源文件，再决定是否执行。
 2026-09-29 17:09:02 +08:00
JianFeeeee
c330dee4bc chore(site): 介绍站同步 1.4.0，并迁移 gitcode → GitHub 链接 
1) 链接迁移：33 处 gitcode.com → GitHub（20 处 SDK、13 处主仓），0 残留。

2) 补齐 1.4.0 特性：「真正的 AgentOS」四张卡（隔离/调度/通信/资源）之外，
   新增第五张「并行 —— 同轮的工具，一起跑」，把声明式并发安全与
   整批降级这两条关键语义写清楚（这是当前版本最重要的架构变化，
   而站点此前一个字都没提）。

3) 插件列表与实际 SDK 示例对齐：补 ai_image(v1.3.0) / files(v1.0.0) /
   luademo(v0.1.0) 三张卡与对应徽章（23 项）。版本与描述取自各自 plg.json。
   注意 mc / homeagent-mail-bridge **不是**过期项 —— 它们是真实插件，
   只是源码不在 SDK 仓，各有自己的链接。

已用共享浏览器（CDP）在 file:// 下实测：徽章 23 个、点 ai_image 能正确
切换出卡片（可见性检查通过）、第五张卡渲染正常、页面内 gitcode 残留为 0。
 2026-09-29 17:09:02 +08:00
JianFeeeee
fc35798eaa ci(pages): 介绍站的 GitHub Pages 镜像 
主站仍自托管在 NAS（192.168.2.106），国内内网直连毫秒级；GitHub Pages 提供
海外可达性与灾备。两边同源（同一个 site/ 目录），不存在谁是「真身」。

发布前的完整性检查是必要的：Pages 是静态托管的，**缺文件不会让部署失败**
（照样 200 + 404 页），所以「引用存在但文件没提交」这类问题必须在这里拦住 ——
检查 index.html 引用的每个 assets/ 资源都实际存在。

三个 action 版本已逐个查 GitHub API 确认真实存在（checkout@v7 与仓库其余
workflow 保持一致；configure-pages@v5 / upload-pages-artifact@v4 / deploy-pages@v4）。
workflow 已过 actionlint，检查逻辑已在本机原样跑通（3 个文件、165778 字节、
引用清单 assets/logo.svg）。

注：Pages 需在仓库设置里把 Source 选为「GitHub Actions」后本流水线才会真正发布。
 2026-09-29 17:09:02 +08:00
JianFeeeee
f0d943e4bb docs: README 对齐 1.4.0 现状，并移除看板娘 
四处过时事实：
  1. 「v1.3.x 线（v1.3.1–v1.3.12，最新已发布）」→ 补上 v1.3.13，并按 main 的实际内容
     新增 v1.4.x 段落（同轮工具并行、seq 序列编排、结果只统计不裁剪、结构化错误契约、
     设备命令白名单、GUI 增量渲染）。这些是 MAIN 上已合入但 README 从未提及的特性。
  2. 「内置 18 个插件」×2 → 实际 20 个（漏了 seq / kbtree 等）。
  3. 6 处 gitcode 链接 → GitHub（仓库已迁至 github.com/JianFeeeee/HomeAgent，
     SDK 为 github.com/JianFeeeee/homeagentsdk）。gitcode 仍作国内镜像保留。
  4. 移除「看板娘 / Web Mascot」整段（中英文各一处）—— 按用户要求。

三张架构图按代码重画（此前图上缺了 1.4.0 的核心机制）：
  - 图一「消息处理时序」：tool 分支改为**批**语义 —— batchRunnable 三条判据
    （批内 >1、全部 ParallelSafe、无同通道重复发送）、可并发/整批降级两条路、
    以及「按声明序收尾 + 同通道保序」。
  - 图二「Stage 管道」：④⑤ 拆成并发/串行两条边，并注明并行只影响执行时序，
    post_action 与 after_toolcall 的可见顺序不变。
  - 图三「三层记忆」：补上**场面识别（声明 + 涌现）**子系统 —— 指纹权重、
    归属/唤起阈值、origin=declared|emergent、用进废退衰减。

另加一段说明：agent 自己的回复也写回记忆（context.Append(Source:"agent")），
因此它能读到自己先前的结论并主动纠正 —— 这是记忆召回的自然结果，
内核里**没有**任何名为「反思」的机制（避免把涌现行为误读成已实现的特性）。
 2026-09-29 17:09:02 +08:00
JianFeeeee
2c34a7938c chore: 用 .mailmap 归并虚拟贡献者身份 
GitHub 的 Contributors 列表按**提交邮箱**归并身份，而本项目历史里同一个人的提交来自
多个邮箱（本地 root、个人 QQ、gitcode noreply、GitHub noreply、dev@local 等），
于是列表里冒出 5 个并不存在的「协作者」：
  root@qq.com(135) / root@qq.com(51) / 2198972886@qq.com(33+4)
  dev@local(14) / root@minecraft-server(10) / 109188060+JianFeeeee@...noreply(19)
加上真实身份，7 条里只有 1 条是人。

.mailmap 只影响**展示层**（git shortlog / git log --use-mailmap / GitHub Contributors），
不改写任何提交对象 —— 历史 SHA 全部不变。归并后：
  git log --use-mailmap → JianFeeeee(715) + HomeAgent Agent(19)

HomeAgent Agent <agent@homeagent.local> **刻意不归并**：agent 的自动提交保留独立身份，
便于区分人类提交与自动化提交。
 2026-09-29 17:09:02 +08:00
JianFeeeee
2a2bc1aa79 chore(watch): 下线站点漂移巡检脚本 
用户指示「那个脚本直接去了吧」：site-drift-watch.sh 每半小时巡检一次两个文档站
的产物漂移，但实测 5 次告警**全是源码漂移误报**（判据只比时间戳，而产物生成后的
提交都不影响文档站），线上漂移与探活失败从未报过 —— 信噪比太差，去掉损失很小。

调用方核查：只有 root crontab 的 `7,37 * * * *` 一条，systemd 无 unit，
脚本/Makefile/.github 里零引用。crontab 已按行备份并只删该两行（其余三条任务保留），
脚本本体备份在 /root/backups/ 可随时还原。

本提交只删仓库内的脚本文件；crontab 与运行环境侧的调整已在部署时完成。
 2026-09-29 17:09:02 +08:00
JianFeeeee
8be79a4c32 docs(ci): CI/CD 流水线手册 —— 用法、机制与 6 个踩过的坑 
仓库迁 GitHub 后新增两条流水线（ci.yml / release.yml），但用法与机制
此前只存在于 workflow 的注释和提交信息里。发版是高频操作，写成手册。

内容：
- §1 CI 六个 job 与「明确不进 CI」的清单（真机/密钥/内网依赖）
- §2 发版标准流程、幂等闸门（tag 存在即跳过）、
     发版门（go build 硬门 + go test 可用 [skip-release-tests] 跳过）
- §2.5 构建资产（ci-assets-v1）的托管与升级方式
- §3 六个实测踩过的坑：
      3.1 workflow 文件必须存在于目标分支（否则推 release/** 不触发）
      3.2 runner 无 electron 缓存 ⇒ 必须 npm ci（且不能用 --production）
      3.3 管道里的 grep -q 因 SIGPIPE 误杀检测（800M 包必炸）
      3.4 gh 在非 git 目录要显式 --repo
      3.5 gitcode 上传的 ASSET_DIR + 裸名语义
      3.6 手工补发 gitcode 附件的流程
- §4 SDK 仓的差异（独立 module 测试要跑两处、CGO 不需要）
- §5 关于失败邮件的说明（可能是验证步骤自身 bug 的假警报）

markdownlint 全绿（两个产物清单代码块补了 text 语言标注）。
 2026-09-29 15:03:05 +08:00
JianFeeeee
e60870c969 ci(release): gh release download 需显式 --repo（非 git 目录无法推断） 
## 症状（第三次试发布）

Build 全绿、tag 已建、release 已建、2.40GB 附件全部上传成功 ——
唯独最后一道「回读校验」失败，整个 workflow 因此标记为 failure：

    failed to run git: fatal: not a git repository (or any of the
    parent directories): .git
    ##[error]Process completed with exit code 1.

## 根因

回读校验为了"下一份干净副本"先 `cd /tmp/back`，那里不是 git 仓库。
而 `gh release download` 默认从**当前目录的 git 上下文**推断仓库与
host（GITHUB_REPOSITORY / GH_HOST 之类环境变量不足以让它跳过推断），
于是报 "not a git repository"。

## 修法

    gh release download "$TAG" --repo "$GITHUB_REPOSITORY"

两个仓的 workflow 都有同一处（主仓 + SDK），一并修。

## 顺带

`third_party/homeagent-sdk/.github/` 加入 .gitignore —— 与 skills/ 同类：
SDK 仓自己的 workflow 由 SDK 仓跟踪管理（那边已跟踪），本仓不参与
构建，不需要在这边重复一份。未加规则时它会出现在本仓的未跟踪列表里。
 2026-09-29 14:39:08 +08:00
JianFeeeee
503f5e7737 ci(release): 验证产物改用 >/dev/null 而非 grep -q —— SIGPIPE 误杀检测 
## 问题（第二次试发布实测）

打包成功后，「验证产物」步骤失败：

    tar: stdout: write error
    dpkg-deb: error: tar subprocess returned error exit status 2

而三个 deb 的元数据其实已全部正确打印（Package/Version/Architecture）。

## 根因

`dpkg-deb -c <800M 的 full 包> | grep -q <模型文件>`：

grep -q 匹配到目标行后**立即退出**、关闭管道读端 ⇒ dpkg-deb 内部的
tar 继续写 stdout 时收到 EPIPE ⇒ pipefail 判整条 pipeline 失败。

⇒ 检测项本身是好的（模型确实在包里），却被检测手段误杀。

本地用 CI 上同一个 800M full 包复现：
    grep -q 版    → dpkg-deb: error: tar subprocess was killed by
                    signal (Broken pipe)
    >/dev/null 版 → 通过

client（80M）没炸、full（800M）炸 —— 包越大越容易触发（内容越多，
grep -q 提前退出的窗口越大）。这正是它没在本地小规模测试里暴露的原因。

## 改法

检测存在性时用 `grep <pattern> >/dev/null`（读完整个输入再退出），
不用 `grep -q`。顺带补了 server 包的模型在位检测（原来只测了 full）。
 2026-09-29 14:19:29 +08:00
JianFeeeee
c55d35ca23 ci(release): 修 gitcode 同步的路径拼法（原写法必然找不到文件） 
upload_assets.py 的路径语义是 `os.path.join(ASSET_DIR, name)`，
而原写法先 `cd dist` 再传 `./*.deb` ⇒ 拼成 `dist/dist/...`，
必然 "资产目录不存在" 或逐个 skip。token 一配上就会炸，属隐患。

改为：cd 进资产目录 + `ASSET_DIR=.` + **不传文件名**（让它扫描当前目录，
.deb/.tar.gz/SHA256SUMS 都在它的产物白名单里）。

SDK 侧另有一处同类问题，但那里**必须显式列名** —— hmapdev 的产物多数
没有扩展名（只有 windows 那个是 .exe），自动扫描会静默地一个都不传。
已同步修在 SDK 仓的 workflow 里。
 2026-09-29 14:09:19 +08:00
JianFeeeee
1978fa6c97 ci(release): [skip-release-tests] 标记改查发版提交，不再查 HEAD 
原实现用 `git log -1 --pretty=%B`（即 HEAD）找标记。但发版提交之后
往往还会跟几个提交（同步 workflow、改文档、修脚本），HEAD 一移动，
标记就被顶掉 —— 跳过机制**静默失效**，流水线又回去撞旧线的红测试。

改为查**改动 internal/meta/meta.go 的那个提交**（语义上正是「发版提交」）：
  REL_COMMIT=$(git log -1 --format=%H -- internal/meta/meta.go)

顺带把 grep -qF 换成 case 匹配，避免多层引号嵌套。

自测（本地 worktree）：
  发版提交 23a98f1 → 命中标记 ✓
  HEAD      df0d4b0 → 不命中（旧逻辑会在此静默失效）

actionlint 全绿。
 2026-09-29 14:03:25 +08:00
JianFeeeee
f56c3c9324 ci(release): 打包前装 Electron，否则 GUI 被静默跳过 
## 问题

打包脚本从两处找 Electron 运行时：
  1) ~/.cache/electron 里的 electron-v<ver>-linux-<arch>.zip
  2) cmd/gui/node_modules/electron/dist（目标架构 == host 时）

全新 GitHub runner **两处都没有** —— 脚本在都没有时只能跳过 GUI，
于是 client/full 包会**静默地不含界面**（正是脚本作者担心的「假包」）。
实测：本地移走缓存后 GUI 被跳过，包仍能产出。

## 改法

打包前在 cmd/gui 执行 `npm ci`，让 electron 落到 node_modules。
runner 是 amd64 == 目标架构，脚本便走第 2 条路径。

**用 npm ci 而不是 `npm install electron@<range>`**：后者是非确定性的
（range 会随上游漂移，也锁不住传递依赖），zizmor 也把它标为
adhoc-packages 风险。package-lock.json（lockfileVersion 3）已锁定
electron，ci 严格按 lock 安装 ⇒ 同一 commit 永远得到同一套依赖。

不能用 `npm install --production`：那会跳过 devDependencies，
而 electron 正是 devDependency（这正是脚本自己那条命令找不到它的原因）。

## 验证

- 无声 cache + 有 node_modules/electron 时，脚本走 host-arch 回退并
  成功构建 GUI（263M / x86-64）—— 已本地实测
- 两者都无时改为打印明确原因并跳过（配合上一个 commit 的 find 修复）
- npm ci --dry-run 通过；actionlint 全绿
 2026-09-29 14:02:18 +08:00
JianFeeeee
4d0ea0a41d fix(packaging): find 在 set -euo pipefail 下致命退出 —— 任何无 electron 缓存的机器都打不出包 
## 症状

CI 发布在「打包」步骤失败，输出停在：

    >>> Building GUI directory for linux/amd64...
      npm install...
      electron 版本取自 package.json 依赖声明: 33.0.0（非精确）
    >>> Restoring original go.mod...
    ##[error]Process completed with exit code 1.

没有错误信息，看不出真因。build_go 之前已全部成功（homed 80M 带 onnxruntime）。

## 根因（本地精确复现 + bash -x 追踪）

    + zip=$(find "$HOME/.cache/electron" -name "electron-v33.0.0-linux-x64.zip" | head -1)
    + zip=
    + restore_all          ← 直接退出

脚本是 `set -euo pipefail`。`find` 对**不存在的目录**返回退出码 1，
pipefail 让 pipeline 返回该 1，而 `set -e` 对**赋值语句里的命令替换**同样生效
⇒ 整个脚本当场退出。

实测退出码对照：
    x=$(find /不存在 | head -1)               → 1（脚本死）
    x=$(find /不存在 | head -1 || true)       → 0（存活）
    x=$(find /不存在)                          → 1（无管道也死）

⇒ 任何**没有 ~/.cache/electron 的机器**（全新克隆、CI runner、其他开发机）
都会撞上。本机一直「能打包」只是碰巧有那份 646M 缓存。

## 修法

给 4 处 find 加 `|| true` 兜底（214/217 electron 缓存、623/625 rpm_deb）。
另修 206 行 `[ -n "$ever" ] && echo ...`：`ever` 为空时该列表返回 1，
在 set -e 下同样会杀死脚本 —— 改为 if 形式。

★ 注意 608 行（fpm 查找）**早就有** `|| true`，说明这个模式被意识到过，
只是漏了这几处。属同一类缺陷的补全，不是新引入的写法。

## 验证

- 复现：移走 ~/.cache/electron 后 `package-linux.sh amd64 build` → 修复前 exit=1
  （输出与 CI 逐行一致），修复后 exit=0 且打印明确原因：
  `WARNING: electron binary not found at ... GUI will be skipped.`
- 有 electron 时仍正常构建：GUI 263M / x86-64（走 host-arch 回退路径）
- bash -n 与 shellcheck -S error 均通过
 2026-09-29 13:59:47 +08:00
JianFeeeee
7798bf3f00 ci(release): go test 门可显式跳过（默认仍严格） 
## 问题（试发布实测暴露）

把 CI/Release 带到 release/v1.3.x 后，CI 三个 job 全红，但**每个失败都是
该分支自身的旧状态，与改动无关**：

| job | 失败原因 | main 上 |
|---|---|---|
| GUI (node) | `npm error Missing script: "test"`（1.3.x 尚无该脚本）| 正常 |
| Go test | TestRealPlugin_DeepSearchKeepsSharedBackendOnStop | **通过** |
| C gates | exit 2（1.3.x 无 csrc 基础设施）| 正常 |

⇒ 给已存在的发布线补新流水线 = 用今天的门去量旧代码。硬门会让该历史
维护线**完全无法发版**，正是用户要的「推 rel 分支就出产物」被挡死。

## 改法

拆开两道门，语义不同：

- `go build ./...` —— **硬门**，不可跳过。产物不可能建立在编译失败的代码上。
- `go test ./...` —— 默认跑，但可跳过。两个来源：
  1. workflow_dispatch 的 `skip_tests` 输入
  2. **发版 commit 里写 `[skip-release-tests]`**

第二个来源是关键：决定落在**定义该次发版的那个 commit** 里，`git log` 可审计，
而不是一个随手勾的开关。跳过时输出 `::warning` 注释，让后果在 run 页可见。

## 未决（留给用户）

`release/v1.3.x` 的 deepsearch 测试失败属该线既存状态（main 已修）。是否把它
cherry-pick 回 1.3.x 属产品决策（1.3.x 是历史维护线，main 已是 1.4.0），
故本次不擅自拉回绿，只提供显式跳过通道。

actionlint 全绿。
 2026-09-29 13:40:25 +08:00
JianFeeeee
80aac5ec4d ci: 发布流水线 —— release/** 推送即发版（tag/打包/发布/镜像全自动化） 
## 设计

版本号唯一事实源是 internal/meta/meta.go 的 Version（仓库纪律），
所以发版动作 = 在 release/vX.Y.x 上把 meta.Version 改成目标版本后推送：

  prepare      读版本号；tag 已存在则整轮跳过（幂等闸门，改文档不会重发）
  build-linux  go build + go test 过门 → 下载资产 → 打包 3 deb + 1 tar.gz
               → 平铺 → 验证（deb 元数据/模型在位/校验和自验）→ artifact
  publish      打 tag → gh release create 传附件 → 回读下载验证校验和
  sync-gitcode 有 GITCODE_TOKEN 时同步 tag+附件到 gitcode（无则跳过不阻断）

## 关键事实（全部本地实测过才写进 workflow）

1. **编译不需要 ONNX Runtime**：onnxruntime_go 是 dlopen 方式（运行期才
   加载 .so），本地在清空 ORT 相关环境变量的条件下带 -tags=onnxruntime
   编译通过（83M）。CI 只需在**打包**时有 ORT（要打进 deb）。
2. **构建资产托管在 release ci-assets-v1**（已上传）：
   chinese-clip-vit-b16-onnx.tar 719MB + onnxruntime-linux-amd64-1.28.0.tar
   24MB + SHA256SUMS。模型内容不随版本变 ⇒ 一次上传反复复用，CI 打包前
   下载并 sha256sum -c 校验。上传实测 3.2MB/s，构建期下载同源更快。
3. **打包链路在干净 worktree 全程实跑通过**（release/v1.3.x + VERSION=1.3.13）：
   full 800M / server 726M / client 80M / tar.gz 841M，SHA256SUMS 平铺自验
   4/4 OK，full 包内确认含 TextEncoder/VisionEncoder.onnx 与 libonnxruntime.so。
4. **SHA256SUMS 的坑**：脚本把校验和写成平铺名（./xxx.deb），而产物在
   deb/ tar/ 子目录 ⇒ 直接 -c 会全 FAILED。workflow 里显式平铺后再验。
   （呼应 git-branching.md §七「校验和必须覆盖全部附件、只传一次」。）
5. ORT 资产补齐了缺失的 LICENSE + ThirdPartyNotices.txt（取自
   microsoft/onnxruntime v1.28.0 tag，与本地 .so 的内嵌版本号一致）——
   打包脚本的 stage_multimodal_assets 对这两文件非空校验，缺失即失败。
6. actionlint 全绿（修掉了 shellcheck SC2012：ls 改 stat 循环）。

## 已知边界

- arm64 发布产物暂缺（package-linux.sh 支持，但 CI 未配 QEMU 交叉；待需要时加 matrix）。
- Windows 安装器未纳入（需 electron-builder win 打包，单独验证后接入）。
- sync-gitcode 依赖 secret GITCODE_TOKEN（待用户配置；未配置时该 job 显式跳过）。
 2026-09-29 13:07:36 +08:00
JianFeeeee
2167dc1748 fix: 修 CI 抓到的两类真实缺陷（.syso 破坏 arm64 + 测试硬编码 /etc） 
第一次 CI 跑出 2 类失败，都是**本地以 root/amd64 跑永远看不见**的问题。
这正是建 CI 的价值：换一个环境就暴露了。

## 一、.syso 无条件被链进所有平台 → arm64 交叉编译必炸

CI 报：
  $WORK/b001/_pkg_.a(waiter.syso): 310766: unknown ARM64 relocation type 3
  （linux/arm64 与 darwin/arm64 两个 job 都红；amd64 两个都绿）

根因（已在本地用 Go 1.25.9 + arm64 精确复现）：Go 会把**同目录的 *.syso
无条件链进任何 GOOS/GOARCH**，而这两个 .syso 是 Windows 资源对象
（x86-64 COFF，只含 .rsrc 图标段）。链进 arm64 目标即报「未知 ARM64 重定位」。

仓库其实**早就知道**这件事 —— deploy/packaging/build.sh:86-90 写着
「Go 会把同目录的 .syso 无条件链进任何目标」，并留了 hide_syso_for_target()
绕过，注释还点名「这正是 arm64 产物长期缺失的原因（曾被误判为缺 g++
交叉编译器）」。但那是打包脚本里的私有绕道：任何**直接 go build** 的路径
（包括 CI、包括本机原生 arm64 构建）都仍会撞上。修在源头而不是再加一层绕道。

修法分两种，因为两个文件的处境**完全不同**：

1. cmd/waiter/waiter_windows_amd64.syso（原 waiter.syso，git mv）
   waiter **仍支持 Windows**（package-windows.sh:68 明确构建 waiter.exe），
   所以不能删。按 Go 的文件名约定加 _windows_amd64 后缀 ⇒ 只在
   windows/amd64 被链入。实测：linux/amd64、linux/arm64、darwin/arm64、
   windows/amd64 四平台全部通过，且 Windows 产物的 .rsrc 段大小
   （00049eb8 字节）与改动前**逐字节一致** —— 图标没丢。

2. cmd/homed/{homed.syso,homed.rc} 删除
   homed 的 Windows 原生支持**已放弃**，五处独立来源一致：
     - README.md:251「homed 放弃 Windows 原生支持改走 WSL2」
     - cmd/homed/platform_windows.go 的 requireSupportedPlatform 直接拒绝启动
       （理由是设计性的：fd 继承 + 同段内偏移解引用，Windows 句柄模型无法表达）
     - package-windows.sh:4「❗安装器不往 Windows 装 homed」
     - build.sh:35「Windows 不再安装 homed.exe」
     - installer.nsi:230「homed 不再装到 Windows」
   即 homed.exe 即便构建出来也拒绝运行 ⇒ 图标资源毫无意义，却是 arm64
   构建失败的来源之一。顺带查明：homed.syso 与 waiter.syso 本是**同一个
   blob**（两个 .rc 指向同一 icon），属纯重复。

★ 由此留下一处**未修的残留**（已确认，不在本次范围）：installer.nsi:297,313
  仍在创建指向 homed.exe 的快捷方式与 Run 注册项，而同文件 230 行已声明
  homed 不装 Windows。那是 Windows 安装器的独立缺陷，需单独处理。

## 二、internal/system 测试硬编码 /etc → 非 root 必失败

CI 报：
  system_test.go:51: expected archive to happen
  system_test.go:97: expected restore to happen

测试写死 target := "/etc/xxx.test.tmp" 并**忽略了 os.WriteFile 的错误**。
GitHub Actions runner 以非 root 运行 ⇒ 写 /etc permission denied ⇒ 文件
不存在 ⇒ ArchiveBeforeWrite 按「新建文件无需留档」返回 false ⇒ 断言失败。
本地以 root 跑则一路通过 —— 缺陷因此长期不可见。

修法：用仓库**已有**的 SetProtectedPaths([]string{临时目录}) 显式声明受保护
前缀（不再碰真实 /etc），defer SetProtectedPaths(nil) 复原默认。既去掉了对
root 的隐式依赖，也没有削弱被测语义（保护的仍是「受保护前缀下的文件」）。

## 验证

- go test ./... -count=1        全绿
- go build ./...                通过
- waiter 四平台交叉编译          全通过（含此前必红的 arm64）
- homed linux/amd64 原生构建     通过（确认删除 .syso 无害）
- Windows 产物 .rsrc 段          改动前后一致（00049eb8 字节）
 2026-09-29 11:11:34 +08:00
JianFeeeee
c22c84f8d6 ci: 建立 GitHub Actions 流水线（六个 job，全部命令已本地实测） 
## 为什么现在做

这次排查「QQ 收不到回复」花了大半程才定位到根因，途中我犯了两类错：
先断言「提示词没写 output_send 规则」（实际 buildSystemPrompt:48-52 写了），
又断言「适配器丢了内容」（实际两版等价、直连上游正常）。
两次都是**在无自动化判据的情况下凭局部证据外推**。

仓库已有 60 个 Go 包、`go build ./...` 仅 2.2 秒，成本极低却无人强制跑。
AtomGit 停用流水线后更无兜底，故迁到 GitHub 补齐。

## 设计原则：CI 里每条命令都是本地已实测通过的

不写「可能有用先试试」的步骤 —— 未验证的 CI 步骤会把假红灯变成常态，
最后所有人都学会忽略它。本文六个 job 的每条命令都本地跑过：

  go build ./...                      ✓
  go vet ./...                        ✓
  go test ./... -count=1              ✓（干净克隆亦通过）
  make check-client-versions          ✓
  go test -race core + waiter         ✓
  waiter/initconfig/mock-server 交叉  ✓（5 平台）
  npm test（cmd/gui）                 ✓
  make check-csrc                     ✓（告警/ABI/ASan+UBSan/跨架构）

## 六个 job

| job   | 覆盖                                                     |
|-------|----------------------------------------------------------|
| go    | build + vet + test + **跨平台客户端版本一致性**           |
| race  | 并发核心的竞态检测                                        |
| cross | linux/darwin/windows × amd64/arm64（仅可纯交叉的 3 个 cmd）|
| gui   | Electron 仓的 Node 测试                                   |
| csrc  | C 基础设施门禁                                            |
| docs  | 站点配置可解析                                            |

## 关键事实（都由实测确立，不是推断）

1. **只有 waiter/initconfig/mock-server 能纯交叉编译**。homed、memgc、
   homed-kb-migrate 依赖 cgo（gojieba / onnx），必须原生构建 ⇒ 不进 cross matrix。
2. **CGO 必须为 1**：gojieba 需要 cgo，`CGO_ENABLED=0` 下 internal/memory
   直接编译失败（实测）。
3. **`go test ./...` 不会碰到 cmd/gui**。该目录是纯 Electron（0 个 .go、
   无 go.mod），`./...` 只匹配含 Go 文件的包；只有显式 `go test ./cmd/gui`
   才报 "no Go files"。这不是缺陷，是 Go 的包匹配语义 —— 之前把它当
   [setup failed] 是误读。
4. **cmd/gui 的 npm test 零依赖**：三个 .mjs 只 import node: 内置模块
   （fs/url/path/vm）⇒ 不需要 npm ci、不需要 electron，秒级完成。
5. **测试自足，CI 上不会因缺本地服务而红**：webui 测试用 httptest 与
   `127.0.0.1:0`，真实 LLM 测试带 t.Skip 守卫。
6. **action 版本已核实存在**：checkout/setup-go/setup-node/setup-python 均用
   v7（经 GitHub API 逐个确认 tag 存在，避免「版本不存在 ⇒ 立刻红」）。

## 明确不进 CI（依赖真机/密钥/内网，否则只会变 flaky 噪音）

deploy-*.sh、waiter 真机（192.168.2.x）、`npm run test-live`（需真 Electron
+ Xvfb + 真后端）、scripts/kernel-stress/*、需 DEEPSEEK_API_KEY 的真实 LLM 测试。
 2026-09-29 10:23:21 +08:00
JianFeeeee
bc00791813 chore: 排除 SDK 仓的 skills/；清掉误建的 --help/ 目录 
## skills/ 不该进本仓

SDK 仓新增了 `skills/`（hmapdev skill install 的源），本仓的
`.gitignore` 已排除 `tools/`、`docs/`、`example/`、`package/`、`scripts/`
等 SDK 仓自治范围，唯独漏了新加的 `skills/`。

`skills/` 是**文档**（skill 说明），归 SDK 仓管 —— 本仓经 go.mod 的
`replace` 只引用它的**编译必需文件**（sdk/*.go、go.mod、meta/meta.go），
文档不在其中。

⇒ 这不是新规则，是把已有规则的适用范围补齐。

## 误建的 --help/ 目录

我在验证 skill 时跑了 `hmapdev init demo`，但那次实际执行的是
`hmapdev init --help` 之类 —— `--help` 被当作**目录名**，在仓库根生成了
一个含 `go.mod`/`plg.json`/`plugin.go` 的 hmapdev 脚手架。

`plg.json` 里 `"name": "--help"` 坐实了这点。已删除。

★ 顺带记一条本机特性：`/tmp` 是 **tmpfs(内存盘) 只有 653M 可用**，
而 SDK store 有 4 个版本、备份要几 G ⇒ 大文件备份必须放 `/var/tmp`。
（这轮第一次备份就撞了 `No space left on device`。）
 2026-09-28 11:30:55 +08:00
JianFeeeee
7151f1db85 feat(gui): 协议对齐 —— 补齐 6 个只读诊断端点 + 人设/反代面板 
GUI 原来只用 22 个端点，服务端有 47 个。补齐**只读诊断类**：
agents / network / tracker / config / persona / proxy(+services)。

## 刻意不接 /login 与 /logout

那是 cookie 会话认证流程，而 GUI 走 `X-API-Key` 头（见 `api()`）。
接了不是"对齐"，是接错。

## 三处新增

**总览诊断卡片**（renderDiagPanel）：Agent 健康、LLM 可达、网络端点数、
文件变更集、数据目录、心跳间隔。全部走 `(x && x.y)` 安全取值 ——
任一端点没取到（老内核无该路由、连接断开）只显示 "-"，不抛错。

**人设面板**（renderPersona）：实测结构是
`{current_prompt, file_override, initialized}`。我第一版按 map 遍历，
结果只会显示三个字段名 —— 真机验证时才发现。改成展示提示词全文 +
两个状态卡。**只读**，编辑涉及保存/回滚/并发覆盖，与"协议对齐"是两件事。

**反代面板**（renderProxy）：base_domain / mode / total / manual +
服务列表（`✓ gateway → 127.0.0.1:9890`）。实测字段是
`{name, host, path, url, target, ok, auth, websocket}`，不是我第一版假设的
`subdomain`。

## 加载策略

只加进 `refreshAll`，**不加** `refreshDataOnly`（后者每 15 秒一轮，
诊断数据不必高频轮询）。7 个新端点实测只 +3ms。

## 判据 protocol-align.test.mjs（10 条，真 Electron）

- 7 个 state 槽都取到真实数据
- 总览出现诊断卡片
- 人设面板**真的显示提示词内容**（不只查元素存在）
- 反代面板**真的列出服务**（查 `→` 出现）

### 判据踩的三个坑

1. **默认假 key 导致 9 项全红** —— webui 对错误凭据返回 200 + 登录页 HTML
   （`looks_like_login_page` 能识别），于是所有取数失败。看起来像
   「代码坏了」，实际只是认证缺失。改为默认从 `config.db` 读真 key。
2. **判据绕过了应用路径** —— 表达式里直接调 `refreshDiagData()`，
   于是把应用里的 `await refreshDiagData()` 注释掉，判据**仍全绿**。
   改为走应用自己的 `refreshAll()`。
3. **变异后 GUI 仍加载旧代码** —— `ensure()` 看到端口有页面就复用，
   注入变异后没重启 GUI ⇒ 又一次假绿。**变异测试必须先杀掉 GUI 进程。**

变异测试（注释掉调用点）⇒ 9 项变红，坐实判据验的是真路径。

## 门禁

- `npm run test-live`：22/22 通过（12 性能+滚动 + 10 协议对齐）
- `npm test`、`make test-gui`：全通过
- `go test ./...`：43 包 ok、0 FAIL
 2026-09-28 10:45:54 +08:00
JianFeeeee
17fee7fabd perf(gui): 聊天页增量渲染 + 修「打开不在最新消息」（10× 提速） 
用户报「聊天页面卡得让人没有用的欲望」+「打开 app 和 webui，没有停在
最新消息处，还要反复滑动」。真机实测（Xvfb + Electron + CDP）定位到两个
根因，都修了。

## 根因 1：renderChat 每次全量重建 innerHTML

200 条消息 = 3500 个 DOM 节点全部销毁重建。拆分测量：

    200 条：整体 234.6ms，其中 renderMd 25.4ms（**11%**）

⇒ markdown 渲染只占 11%，**89% 在 DOM 写入与布局**。
流式追加时每个放行的 chunk 都走这条路（200 条时每 chunk 6.6ms），
聊到几百条就是 0.5 秒/次 —— 这就是体感。

**改法**：按 `data-msgkey` 复用节点，四种策略按代价从低到高：
尾部追加（最常见）→ 头部前插（loadOlderChat）→ 局部替换 → 兜底整棵重建。

`data-msgkey` = role + 序号 + 内容长度 + 首尾片段。
★ **不能靠下标定位**：`loadOlderChat` 会 `unshift` 前插消息，下标整体位移。

实测：

| 消息数 | 改前 | 改后 | 改善 |
| --- | --- | --- | --- |
| 50 | 59ms | **8.2ms** | 7.2× |
| 200 | 235ms | **23.5ms** | 10× |
| 400 | 474ms | **38.2ms** | 12× |

关键是**次线性**了：400 条只比 200 条多 15ms（改前多 240ms）。

## 根因 2：滚动没落地

    scrollTo 被调: 1, 参数: {top: 23446, behavior: "smooth"}
    scrollTop: 0            ← 调了，但没生效
    可滚动上限: 22838

smooth 立即值 0、300ms 后只到 6894（上限 22838）⇒ **既慢又没到位**；
手动 `scrollTop = scrollHeight` **立即 22838 一次到位**。

原因：紧邻的 DOM 全量变更让 smooth 动画的起点算在**旧**布局上。
重建后本就不该有动画 —— 用户要的是「立刻看到最新」。

**改法**：`msgsEl.scrollTop = msgsEl.scrollHeight`。

## 判据 chat-perf.test.mjs（10 条，真 Electron 跑）

新增 `npm run test-live`（需 Xvfb + electron，**不进 make test** ——
它要起真浏览器、30 秒启动，不适合当门禁）。

- 性能：200 条 < 100ms（**产品体感阈值**，不是 benchmark 数字）
- 次线性：单条成本不随规模上升
- 滚动：打开即在底部、300ms 后不被带偏
- **正确性：增量不丢消息**（5 种增删改路径）—— 比性能更重要

### 写判据时踩的坑（都记在文件里）

1. **第一版测出「0ms / 0 DOM 节点」** —— `buildChatLayout()` 在**无后端连接**时
   走「请先添加连接」分支、聊天区压根没建 ⇒ **测不到**而非「不卡」。
2. **`ensureGui` 定义了但从未被调用** —— 重写文件时把调用丢了，
   而定义还在，看起来一切正常。
3. **`detached: true` 只脱离进程组、不脱离会话** —— 脚本结尾 `process.exit()`
   把刚起来的 GUI 带走（症状：`[tray] READY` 打了，判据却报「找不到页面」）。
   改用 `setsid`。
4. **`JSON.parse(e.data)` 裸调** —— CDP 的 onmessage 也会收到非 JSON 帧，
   抛在回调里既冒泡不到 await 也等不到 resolve ⇒ 整个判据挂死。
5. 我自己的滚动探针 `el.innerHTML=''` 让 `scrollHeight` 变 0，
   「到位」判定是假象。改用「保留内容、只改滚动方式」重测。

## 变异测试

把 `applyIncrementalChatRender(msgsEl, html)` 改回 `msgsEl.innerHTML = html`
⇒ 判据立刻红（实测 268ms + 严格线性）。

## 门禁

- `npm run test-live`：10/10 通过
- `npm test`、`make test-gui`：全通过
- `go test ./...`：43 包 ok、0 FAIL
 2026-09-28 10:26:58 +08:00
JianFeeeee
ba367ddf67 test(proc): 修 grandchild 测试的三个设计缺陷（不是生产代码问题） 
## 定位结论

`TestKillReturnsEvenWhenGrandchildSurvives` 曾在 `go test ./...`（600s 超时）
与 `make test`（20.4s FAIL）里失败，但**单跑 0.24s 通过**、连跑 3 次全绿
⇒ 「单跑绿、合跑红」。查下来是**三个测试设计缺陷**，
生产代码（`process.go`）没问题。

### 缺陷 1：名字说 Survives，实际测的是「被杀」

| 测试 | 源 | 孙进程 | kill(-pgid) 能杀吗 |
| --- | --- | --- | --- |
| …EvenWhenGrandchildSurvives | grandchildPluginSource | sleep 400，**不**设 Setpgid | **能** |
| …WhenGrandchildEscapesProcessGroup | escapingGrandchildSource | sleep 401 + Setsid | **不能** |

`grandchildPluginSource` 自己的注释写着「孙进程**不**设 Setpgid：它要留在
插件的进程组里」⇒ 第一个测试里孙进程不会 Survive。容易让人误以为
「脱组场景已被覆盖」，而它覆盖的是另一个场景。

**已改名** `…WhenGrandchildDiesWithProcessGroup`。

### 缺陷 2：判据数的是全系统进程

两个计数器扫 `/proc` 找 `"sleep 400"` / `"sleep 401"` 字符串，
**不区分父子关系** ⇒ 同机任何命中同样 cmdline 的进程/容器都串味。

原注释记过一次前车之鉴（「我第一版就踩了：明明单跑通过，合跑却红」），
但当时只加了 base 快照，**没解决全局匹配这个根因** —— base 救不了
「别的测试中途拉起 sleep 400」。

**已修**：新增 `procPPid()`，两个计数器都限定 PPid 属于本测试的插件。
顺带补 `e.Name()` 的 `Atoi` 校验（原来会把 /proc/self、/proc/net 也读一遍）。

### 缺陷 3：defer 清理「拿不到 pid 就整个跳过」

`if pid := pluginPid(p); pid > 0 { Kill }` 在 pid 取不到时静默跳过
⇒ 残留 sleep 400 污染后续测试 ⇒ 变成下一个测试的假失败。

**已修**：新增 `cleanupSleepMarkers(marker)`，按唯一 cmdline 标记兜底清理。

## ★ 我被推翻的一个假设

我一度认定根因是 `waitLoop` 里 `p.cmd.Wait()` **先阻塞**、拆管道在**之后**
（`process.go:359-367`）—— Go 的 `exec` 里 `Wait()` 会等 copy goroutine，
而那些要等所有管道写端关闭，孙进程持有着 ⇒ 死锁。

**实测推翻了它**：把拆管道提到 `Wait` 之前，那个测试 **5 次全 FAIL**
（改前只是偶发）。真正的根因是上面三个测试设计问题；「Wait 阻塞」只是
**被孙进程持管道放大**的效应。

⇒ 改生产代码不但没修好，还把偶发变成必现。**先证明因果再动手。**

## 判据：grandchild_design_test.go（4 条）

★ 它是**查源码文本**的，我一改源文件（改名/加 ppid 限定/加兜底清理），
锚点就全过期 ⇒ 三条判据一起红。

⇒ 判据自己被重构打断时，要改的是**判据的锚点**（认新旧两种形态），
不是回退修复。最后把判据①从「解函数体比对 spawn 参数」简化为
「只问名字是否还说 Survives」—— 少耦合一层，少失效一处。

变异测试三个都抓到：改名回 Survives / 抽掉 ppid 限定 / 去掉兜底清理。

## 门禁

- 全量 `go test ./...`：**43 包 ok、0 FAIL**
- `internal/plugin/proc` 连跑 **5 次全绿**（原来会红的地方）
- `go test -race ./internal/plugin/proc/`：ok
- 无 sleep 400/401 残留

## 顺带

`9e76132` 之后 README 的 biome 格式化不再 churn：仓库**没有** biome 配置，
格式来自流水线默认 ⇒ 每次提交后它都会把工作区改脏。我这次会话里反复
`git checkout --` 把它丢掉，那是和流水线对抗。**提交后 biome 再跑就是
no-op**，问题根除。
 2026-09-28 10:00:10 +08:00
JianFeeeee
9e76132658 style(readme): 接受流水线的 markdown 格式化 
三处纯格式，**无语义变化**：
- 嵌套列表 `+ ` → `- `（渲染效果相同）
- 表格分隔符 `|---|---|---|` → `| --- | --- | --- |`

## 为什么要提交而不是继续丢弃

仓库**没有 biome 配置**（无 biome.json），格式来自流水线默认。
⇒ 它每次跑都会把 README 与 cmd/gui/renderer/app.js 改成 dirty 工作区。

我这次会话里反复 `git checkout -- README.md cmd/gui/renderer/app.js`
把它丢掉，**那是在和流水线对抗，纯属白费力气**：每次提交后它又变 dirty。

提交后 biome 再跑就是 no-op ⇒ 永久不再 churn。

★ 教训：可自动复现的格式化，正确做法是**接受并单独提交**，
而不是每次手动回退。回退只是把冲突推迟到下一次提交。
 2026-09-28 09:40:37 +08:00
JianFeeeee
f476bf4487 test(webui): 压测补齐另外 3 个插件的路由 —— 我第一版漏了两个 
第一版只压了 webui 的 `/api/v1/*`。核实后发现 **8080 上注册 HTTP 路由的
插件有 4 个，监听端口还不止 8080**（`ss -ltnp` 实测）：

| 端口 | 插件 | 路由 | 认证 |
| --- | --- | --- | --- |
| 127.0.0.1:8080 | webui | /api/v1/* | config_webui.api_key |
| | remotedevice | /api/v1/device/* | config_remotedevice.ws_token |
| | kbtree 子路径 | /api/v1/knowledge/tree/{categories,counts} | config_webui.api_key |
| 127.0.0.1:9876 | **pluginmgr** | /plugins（**无** /api/v1） | **无需认证** |
| 127.0.0.1:9892 | **kbtree** | /categories /counts（**无**前缀） | config_kbtree.token |
| 127.0.0.1:9890 | remotedevice | 设备 WS 网关（非 REST） | 不压 |

⇒ 「打 /api/v1/*」这个假设只对 8080 上的 webui 成立：`:8080/plugins`
实测 **404**。三套认证各不相同，脚本现在按分组取对应 token。

## 端点 18 → 24

新增：`/api/v1/device/online`（remotedevice）、`/plugins`（pluginmgr）、
`/categories` `/counts`（kbtree 根路由）、以及 webui 前缀内的
`/api/v1/knowledge/tree/{categories,counts}`。

收 `/api/v1/device/online` 之前逐行读过实现：仅 `GET` +
`registry.OnlineList()`，纯读。**不收** `/device/push`（向真实设备下发）、
`/device/ws`（长连接）、`/device/{id}`（语义未核实）。

## 实测（24 端点 × 3 档，2880 请求零失败）

| scale | 请求 | 吞吐 | p50 | p95 | p99 | max | 成功 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 1 | 480 | 953 req/s | 4.0ms | 23.0ms | 34.7ms | 40.6ms | 480/480 |
| 2 | 960 | 1310 req/s | 7.9ms | 32.4ms | 48.4ms | 72.3ms | 960/960 |
| 3 | 1440 | 1422 req/s | 12.0ms | 42.7ms | 60.5ms | 88.7ms | 1440/1440 |

压测期间服务端 `active`、0 个 5xx。

**p99 随并发单调上升**（34.7 → 48.4 → 60.5ms），符合排队预期。
上一轮曾出现 scale=2 的 p99 反常地高于 scale=3，当时机器上另一个 agent 的
chromium 占 766% CPU ⇒ 环境噪声，已明确不作为性能特征。

## 又踩了一次前缀的坑（两种方向都踩了）

1. 「表里存路径后半段 + 代码按 group 补前缀」⇒ remotedevice 拼成
   `/api/v1/api/v1/device/online` ⇒ 落到 webui 兜底路由、
   返回 **200 + 登录页 HTML**（靠 `looks_like_login_page()` 抓到）。
2. 反过来「表里已含前缀 + 代码仍补」⇒ webui 组全 404。

⇒ 最终统一成**表里写完整路径、代码不补**。两次都是靠 `--probe` 抓到的，
这正是它存在的理由。

## 顺带修掉我写错的一处

`contextlib.suppress(sqlite3.connect)` —— `connect` 是函数不是异常类，
`suppress` 会抛 `TypeError`。改回显式 `try/except sqlite3.Error`，
并把 `config.db` 的打开方式保持 `mode=ro`（压测不碰生产库写路径）。

## 文档里我自己写错又改正的一处

§7 表格里 scale=1 一行先写成 1680/2013/5.4ms，核对 JSON 后实为
**480/953/4.0ms**（24 端点 × 20 轮）。已订正，并加了提交前的
JSON 逐项比对，三档现已全部一致。
 2026-09-28 09:33:22 +08:00
JianFeeeee
2bd1bac0ee test(webui): WebAPI 只读端点压测 + 实测 2160 请求零失败 
打的是**生产实例** 127.0.0.1:8080。

## 为什么只压只读端点

压测绝不能改状态。18 个端点**逐个探测确认**是 GET + 只读：
小（/status…/proxy/services，104B–1.8KB）、中（/plugins…/knowledge，
4.4KB–53KB）、大（/kernel 157KB、/memory/graph 338KB、/knowledge/tree 425KB）。

**排除**：/chat（真调 LLM）、/chat/interrupt（中断在跑的任务）、
/settings/* 与 /plugins/*（改配置）、/login /logout（改会话）、
knowledge/memory 写接口、/device/*（控制真实设备）。

## ★ 两条判据（都不是"看有没有报错"）

### 1. 必须先 `--probe`：webui 无认证时返回 200 + 登录页 HTML

含 `THEME_PLACEHOLDER`，**状态码是 200**。只看 `http_code` 会把登录页
当成健康响应 ⇒「全部 200」是假的。脚本因此额外校验响应体。

### 2. 端点表漏了 `/api/v1` 前缀 ⇒ 18 个端点全 404

第一版把端点存成路径后半段（`"/status"`），拼出
`http://127.0.0.1:8080/status`，而真实路径是 `/api/v1/status` ⇒
**全部 404**，同一时刻 curl `/api/v1/status` 却是 200。

⇒ **压测脚本必须先 probe 再压。** 不 probe 的话那一跑的结论会是
「webui 全挂」，完全错误。这条已写进手册。

## 实测（2026-09-28）

| scale | 请求 | 吞吐 | p50 | p95 | p99 | max | 成功 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 1 | 360 | 779 req/s | 6.7ms | 26.8ms | 45.5ms | 51.6ms | 360/360 |
| 2 | 720 | 788 req/s | 12.2ms | 52.6ms | 163.0ms | 213.5ms | 720/720 |
| 3 | 1080 | 1038 req/s | 16.4ms | 60.4ms | 79.7ms | 123.0ms | 1080/1080 |

**2160 请求零失败**；压测期间服务端 `active`、0 个 5xx、0 个 webui 错误，
QQ/agent 链路未受影响，homed CPU 仅 1.2%。

### 重响应不是瓶颈（并发 1 → 16）

| 端点 | 大小 | 并发 1 | 并发 16 | 吞吐 |
| --- | --- | --- | --- | --- |
| /status | 0.2KB | 104 req/s | **1781 req/s** | 320KB/s |
| /kernel | 153KB | 126 req/s | 375 req/s | 19 → **57 MB/s** |
| /memory/graph | 330KB | 70 req/s | 410 req/s | 23 → **135 MB/s** |
| /knowledge/tree | 415KB | 79 req/s | 717 req/s | 33 → **297 MB/s** |

大 JSON 端点的 p50 **不随并发上升**（/knowledge/tree 12.3ms → 8.9ms，
排队更充分、效率更高）⇒ 瓶颈不在 JSON 序列化。

## ⚠ 一处未下结论的观察

scale=2 的 p99（163ms）反而**高于** scale=3（79.7ms）。看着反常，但当时
机器上另一个 agent 的 chromium 占 **766% CPU**（另有 cjpm/cjc 在编译）
⇒ 是**环境噪声**。

**未在可比条件下重测就不下结论** —— 不拿这一组当性能特征。要判定需先
固定负载条件再跑。这条也写进手册。

## 顺带

ruff 报的三条 blocker 都修了：`pct()` 空样本不再抛错（调用方直接拿去做
f-string 格式化）、写 JSON 失败明确报错而非静默丢报告、错误体读取用
`contextlib.suppress` 免得二次异常盖掉真正的状态码。
 2026-09-28 09:22:16 +08:00
JianFeeeee
1fe1b6e466 fix(gui): 401 重试无限递归 —— 我上一个优化放大的 bug 
## 真机实测发现的

Xvfb + Electron + CDP 真跑，发现 `api()` 的 401 分支**无限自我递归**：

    第1次: lock=false → 重登 → lock=false → return api()   ← 递归
    第2次: lock=false → 重登 → lock=false → return api()   ← 又递归
    …

那把锁的语义本该是「已经重登过一次，别再登」，但它在递归**之前**就被
清掉了 ⇒ 每层递归看到的都是 `false`。真机实测 **fetch 被调 13 次、
重登 12 次**才被我的探针上限截断。

## 为什么这与我的上一个提交直接相关

`74dbbb3` 把 401 分支的固定等待从 800ms 降到 30ms（修「认证过期时每个
请求白等 0.8s」）。但重试**没有次数上限** ⇒

- 改前：每 800ms 慢速空转
- 改后：每 30ms 快速烧 CPU + 反复打服务端

**我的优化把这个 bug 放大了。** 真机上探针调用 `api()` 直接挂死，
我起初还以为是我的测试写法问题。

## 修法

两处递归点（真 401 / 门户返回 200 但内容是登录页）都改成：

    try {
      return await api(p, o);
    } finally {
      window._haReloginLock = false;
    }

`finally` 保证递归抛错时也释放锁 —— 否则会把后续所有请求都锁死成直接 401。

## 判据 retry-guard.test.mjs

在 `node:vm` 沙箱里跑**真实抽出的 `api()`**，用恒回 401 的 `fetch` 驱动，
统计真实调用次数。

### 写这条判据时踩的四个坑（都记在文件里）

1. **先给了假绿灯**：把 401 分支当独立函数体执行，但那块以
   `return api(p,o)` 结尾、外面没有调用它的上下文 ⇒ 我从未真正进入那个
   `if` ⇒ `api 递归=0` ⇒ 什么都没测到。改成跑**真实 api()** 才对。
2. **递归时忘了保持 `r.status===401`**：真实场景是「重登后凭据仍是错的」。
   漏了它 ⇒ 递归那层不进 401 分支 ⇒ 又一次假绿灯。
3. **沙箱 `setTimeout` 只记录不执行**：`api()` 用它做超时控制
   （`setTimeout(() => ctl.abort(), to)`）⇒ AbortController 永不被 abort
   ⇒ 表现为「fetch 只调 1 次、8000ms 被当成 401 等待」。
4. **沙箱缺 `clearTimeout`** ⇒ 抛 `clearTimeout is not defined` ⇒
   整段在 fetch 之后就断了 ⇒ 永远走不到 401 分支。

★ 共同点：**沙箱不完整 ⇒ 静默地什么都没测 ⇒ 假绿灯**。
判据自己给假绿灯比没有判据更危险。

### 变异测试（精确锚点，验证判据真能抓）

把第一处 try/finally 退回「递归前清锁」⇒ 判据立刻红
（`fetch 被调 13 次`）；恢复后全绿。

★ 第一次做这个变异时我误判「判据漏抓」—— 实际是我的变异脚本用了模糊
锚点、**压根没改到文件**（`grep` 显示 return await 从 2 变 1，但 `sed`
命中的是另一处）。两个信号矛盾时先坐实文件状态，别急着改判据。

## 顺带把 `make test` 的门禁修好（37ae621 / 31b882a 之外）

新判据已接入 `npm test`，实测 14 项通过、`make test-gui` 全绿。
 2026-09-28 09:11:58 +08:00
JianFeeeee
76cc733273 docs(runbook): 记「判断线上跑哪次构建」的正确判据（我今天差点白部署） 
## 线上其实已经是修好的版本

去部署 `a926744`（webui 总览 5 个 KPI 空）前核实，发现：

    /api/v1/status → {"commit":"a926744", "startedAt":"2026-09-27T23:23:39"}

23:23 那次部署**不是我做的**（我只在 21:50 部署过），已经包含
`a926744`。`/api/v1/kernel` 里 5 个 KPI 依赖的字段也全部有值
（`plugins` 39 个、`llm`/`memory`/`documents`/`runtime`/`onnx` 非空）。

⇒ **不需要部署。**

## ★ 为什么 `strings` 不能用来判断

webui 等插件的静态资源是 `//go:embed` **编译进二进制**的
（`internal/plugins/webui/handler.go:27`），内容取决于**构建时**磁盘上的
文件。⇒ 已提交但未部署的改动，线上二进制的 `strings` 里**也可能**
出现新代码片段。

我据此差点白重启一次生产。同一天还撞上**字节数完全相同**的巧合
（86811464），更掩盖了这点 —— 大小相同更让人以为"没变化，不用管"。

## 正确的判据顺序

1. `/api/v1/status` 的 `commit` —— 线上在跑什么
2. `git log <commit>..HEAD` —— 差哪些提交
3. 那些提交里**有无运行时改动**（`internal/`、`cmd/`）—— 只有它需要部署
4. 文档 / 判据 / 部署脚本类提交**不需要**部署

## ⚠ 那条命令必须带认证头

无认证时 `/api/v1/status` 返回**登录页 HTML**（200 + `THEME_PLACEHOLDER`），
`grep '"commit"'` 匹配不到 —— 看起来像"命令没输出"，实际是认证缺失。
与 GUI 客户端 `api()` 专门检测 `THEME_PLACEHOLDER` 是同一件事。

## 顺带：内置插件 vs 独立二进制

`internal/plugins/<name>/` 编译进 homed；`plugins/<name>/plugin.bin`
是独立插件，要单独构建部署。**目录存在不等于有独立二进制** ——
`plugins/webui/` 目录存在但 **0 个文件**，走内置。

实测（2026-09-28）：`webui`/`cmd`/`seq` 内置，`qq` 独立。
改内置插件只需重编 homed。
 2026-09-28 08:52:12 +08:00
JianFeeeee
c4a8caf13f feat(watch): 站点漂移巡检（只读，有差异才提醒） 
`site-drift-watch.sh` 巡检 192.168.2.106 上的两个站，**只读不动**：
不构建、不上传、不碰线上任何文件。档位是「有差异就提醒」而不是
「自动推」—— 文档站发错了是公开可见的，宁可等人点一下。

判三类信号：
1. 线上漂移：.106 上的站 ≠ 本机产物/site 源（逐字节 md5 清单比对）
2. 源码漂移：git HEAD 比产物新 ⇒ 提交了但没重新构建部署
3. 探活失败：.106 或 NapCat 挂了（比文档漂移紧急）

不复用 `deploy-sdk-site.sh --check`：那脚本输出是给人看的彩色文本，
拿来当机器判断依据太脆（改个文案就失效）。md5 清单逻辑很短，
这里复刻一份并在注释里指向 deploy-sdk-site.sh 保持同步。

## `.drift-watch/` 加入 .gitignore

里面的 `state` 是运行时状态（含时间戳与指纹，每次跑都变），不该入库。

## 提交前核实（两处我的检查写错了，脚本本身没问题）

- 我查"凭据"命中 1 处 ⇒ 实为注释里的「烧 token」，指 LLM token 非密钥。
  真实密钥形态（`sk-*` / `password=`）**0 处**。
- 我查"部署调用"命中 6 处 ⇒ 全是**注释与提示文本**（提醒人去跑
  `deploy-sdk-site.sh`）。实际执行 `rsync`/`scp`/调用部署脚本**均 0 处**，
  `rm -rf` 0 处 —— 与它「只读」的声明一致。
- `set -uo pipefail` 少了 `-e`：**有意为之**。巡检要在某项检查失败时
  继续跑完其余项，`-e` 会中途打断。实测跑一次四项全绿、无差异。
 2026-09-28 08:45:03 +08:00
JianFeeeee
31b882a439 fix(make): test-gui 不再被前序失败短路（门禁曾形同虚设） 
## 问题

`make test` 原本是 make 的**依赖链**：

    test:
    	$(GO) test ./...
    	@$(MAKE) test-gui
    	@$(MAKE) csrc-test
    	...

`go test ./...` 一旦 FAIL，make **立即中止** ⇒ 挂在它后面的目标一行都不跑。

实测坐实：`internal/plugin/proc` 偶发 FAIL 时，`make test` 的日志里
**找不到 test-gui 的任何输出** —— 刚接进去的 GUI 判据根本没被执行。
门禁挂上去等于没挂。

## 为什么不能简单用 `-@$(MAKE) test-gui`

`-` 前缀会**吞掉 GUI 判据自己的失败码** —— 判据红了 make 照样绿，
等于给假绿灯。那比短路更糟：它让人以为门禁在生效。

## 做法

全部跑完，最后统一判退出码：

    test:
    	@rc=0; $(GO) test ./... || rc=$$?; \
    	 $(MAKE) test-gui || rc=$$?; \
    	 $(MAKE) csrc-test || rc=$$?; \
    	 $(MAKE) check-csrc || rc=$$?; \
    	 $(MAKE) check-codec-cgo-only || rc=$$?; \
    	 exit $$rc

既保证每一步都跑，也保留每一步自己的失败。

## 验证（注入失败实测，不是推断）

往 `TestKillReturnsEvenWhenGrandchildSurvives` 里塞 `t.Fatal` 制造必然失败：

| 验证项 | 结果 |
| --- | --- |
| `make test` 退出码 | **2**（非 0，失败被上报） |
| proc 包 FAIL | 抓到 |
| **GUI 判据输出** | **仍执行** ← 这是要证明的那件事 |
| csrc-test | 也执行了 |
| 汇总 | ok=43 FAIL=1 |

随后已恢复该测试文件（`git checkout` + 确认 0 处残留 `t.Fatal`），
并复跑该包确认 ok 10.6s。

全绿路径也验过：`make test` 退出码 0、ok=44 FAIL=0、GUI 判据执行。
 2026-09-28 08:43:04 +08:00
JianFeeeee
a656588ed9 docs(make): 记下 proc grandchild 测试本身不稳定（现象，未下根因） 
`make test` 的后置验证里发现 `internal/plugin/proc` 会 FAIL，实测形态：

- 单独跑**同一命令**：`ok 11.5s` / `FAIL` 交替出现（至少各一次）
- 全量并发跑：曾 600s 超时（`panic: test timed out after 10m0s`），
  也曾 90s 就 FAIL
- 失败测试固定是 `TestKillReturnsEvenWhenGrandchildSurvives`，
  伴随日志 `[proc] audit 退出: signal: killed`

与本次改动（74dbbb3 SSE 退避、37ae621 判据）无关联：改的是
`cmd/gui/renderer/app.js` 与判据脚本，没碰 `internal/plugin/proc`。

症状**像** fork/kill 的进程组语义在容器/并发下不稳（孙进程 setsid
脱组后杀不掉 ⇒ Wait 挂死），但**尚未定位到根因**，因此 Makefile 里
只记现象、不下结论。

★ 记这一条是因为我自己先踩了坑：一开始连跑 3 次全绿，我就准备写
「单跑稳定、仅并发偶发」；紧接着同一命令又 FAIL 了。**单跑通过不能
当结论** —— 这类 fork/kill 测试必须重试才能给出可信判断。
 2026-09-28 08:30:44 +08:00