jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-09-27 21:03:16 +00:00
Code Issues Packages Projects Releases Wiki Activity
657 Commits 5 Branches 27 Tags
9c93f232e33ada5d41f5339de37cd9b0b97edda1
Commit Graph

657 Commits

This Branch
This Branch
All Branches
Author SHA1 Message Date
JianFeeeee
9c93f232e3 fix(webui): 星图配色改中性灰蓝 + 图例按实际类型动态生成 
### 为什么会出现「一片绿」

上一提交修好了「分类配色从未生效」那个 bug（服务端发 "Concept"、JS 键是
"concept" ⇒ 永不匹配 ⇒ 1150 个节点全回退兜底灰 0xcccccc）。修好之后
颜色值**一个字没改**（concept 键仍是 0x44ff88），于是 1148 个 Concept
节点第一次真的拿到了那个亮青绿 —— 1149 个节点里 1148 个是 Concept，
所以整张图变成绿的。

⇒ 结论：绿色不是渲染 bug，是「配色终于生效」后暴露出的真实数据形状。
   之前的灰色恰好是「全都没匹配上」的症状。

### 换中性色（用户裁定）
默认色改为 SM_COLOR_DIM = 0x7d8a9e（中性灰蓝）。亮青绿配 1149 个
自发光球确实扎眼。

### 顺带把「图例说谎」也修了
原图例写死「人物/概念/对象/地点/来源」五项，而实测图谱里只有
Concept（1148）与 Source（1）—— 列出四个永不出现的类型，等于告诉
用户存在实际不存在的分类。

现在：
- 图例按**实际出现**的类型动态生成，标注占比
- 占比 <1% 的不单列（实测 1/1149 = 0.087%，单列会显示成「来源 0%」，
  既难看又误导读者以为图里没有来源节点），归入「其他 N 个」
- 只有**一种有存在感**的类型时，附一句实话说明「节点同色不是分类图」

### 颜色规则也跟图例对齐
smColorFor：只有存在 >=1% 的第二类型时才按类型上色，否则全图中性色。
理由：99.9% 概念 + 0.1% 其他时按类型上色，得到的仍是一整片同色，
而那一两个异色点在视觉上就是噪点（实测 colors 只剩 ["7d8a9e"]）。

不动服务端类型识别（用户裁定）：nlp/extractor.go 至今不判类型、
graph.go:451 写死 Concept，根治要改记忆链路，本轮不碰。

### 途中修掉一个自己引入的 bug
图例空。首屏星图在**总览页**初始化，那时 #sm-legend 还不存在
（骨架由 renderStarmapTab 建），smLegend 内部 getElementById 返回 null
直接返回；而 renderStarmapTab 建完骨架后只调了 smUpdateStat()。
⇒ 浏览器实测图例 html 长度 0。在 renderStarmapTab 里补一次 smLegend()。

### 验证（真实 1149 节点数据集 + WebGL）
- 颜色：["7d8a9e"]（单一中性色）—— 改前 ["44ff88"] 一片绿
- 图例文本：「概念 100%  其他 1 个（图谱实体几乎都是同一类型，节点同色；
  出现新类型后会自动分类）」
- 统计：1149 节点 / 865 关系；控制台零异常
- go vet 干净；全量测试通过

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
 2026-09-27 07:14:34 +08:00
JianFeeeee
4a231a8d4c style(webui): dashboard.js 两处表达式合并为单行 
纯格式化，无语义变化：
- state.startedAt 的三元表达式（563 行附近）
- renderAll 里 Promise.all 的实参（624 行附近）

两处的表达式与参数列表逐字符相同，只是原先的换行被收拢。
已随二进制部署并验证上线：现网 `/` 返回的 HTML 里单行写法命中 1 处、
旧多行写法 0 残留。
 2026-09-27 06:44:49 +08:00
JianFeeeee
d3315c68ca perf(webui): 前端按页签懒加载 —— 首屏不再拉隐藏页签的数据，空闲请求砍到 1/3 
生产实测的问题：renderAll 无论当前在哪个页签，都无条件拉 9 个接口并
渲染全部 7 个页签。首屏 792,933 B 里**约 230KB 花在用户看不见的隐藏
DOM 上** —— /api/v1/kernel（152KB，只有内核页要）与 /api/v1/settings
（72KB，只有设置页要），而 renderKernel() / renderOneSettings() 是在
**隐藏的 tab 容器**里构建 DOM 的。更糟的是每 15s 重来一遍。

### 依赖关系是实测出来的，不是猜的
逐个 render 函数 grep 它读的 state.*：
  renderOverview     → 无（只读 status/runtime/dom）★ 总览最便宜
  renderKernel       → state.kernel
  renderOneSettings  → state.settings / state.meta
  renderPlugins      → state.kernel / installedPlugins / disabledPlugins
  renderAdapters     → 无（自拉 /api/v1/adapters）
  renderChat         → 自建布局；星图/终端/命令是其子面板
于是「切到哪页才拉哪页的数据」写成一张 TABS 表（唯一真相表），
正确性由结构保证，而不是靠一串 if 串联。

### 顺带治掉三个轮询器（浏览器 40s 空载实测）
改前停在总览页 40s 内 37 个请求：
  /runtime 17 次、/terminals 8 次、/cmd/history 8 次、/status 3 次

1. **terminals/cmd/history 的 5s 轮询是无条件的** —— 但这两个面板只
   存在于**聊天页**（buildChatLayout 里的 chat-panel-terminal/-cmd），
   在总览/设置/内核页渲染它们既没人看也只改看不见的 DOM。
   改为「仅聊天页可见时才轮询」。
2. **/runtime 有两个消费者各拉一遍**：startRuntimeTicker（3s）与
   starmapPullActivity（3s）。星图现在只读 state.runtime，不再自己发请求。
3. 轮询改走共享数据块 starmapFetchBlock（带 3s 节流 + 单一数据源）。

改后 40s 内 17 个请求（-54%），且不再有任何接口用于渲染不可见的面板。

### 首屏
overview 首屏只拉 status/runtime/chat/history/persona/memory-graph，
**不再拉 kernel 与 settings**。

### 刷新语义
区分「活数据」与「近乎不变的数据」：status/runtime 每 3s 允许重拉；
kernel/settings/plugins 首次拉过后**不再每 15s 重拉**（这正是 53MB/h
的主因）。切回页签也不重拉（数据没理由变）。四个变更操作
（源/MCP 的增删）改调 renderAll(true) 强制刷新；启停插件/保存设置那几处
本来就自己 refetch 再局部重渲染，不依赖 renderAll。

### ★ 途中修掉一个被上一提交引入的真 bug
loadChatStarmapData 的空图分支硬写 getElementById("sm-container-chat")。
星图搬到总览后，总览页与独立页签都没有这个 id ⇒ 首页首帧必抛
「Cannot set properties of null」，被 catch 吞掉但 starmapInit 没置上，
于是**永不重试、星图永远空白**。改为取 starmapActiveContainer() 并加
空值保护。浏览器实测：修前 ERRORS 非空，修后 STARTUP + 7 个页签全 clean。
（教训：把 UI 元素挪到新位置后，必须把所有按 id 直取该元素的地方找全 ——
grep 该 id 一次。）

同时删掉被 starmapActiveContainer 取代的死函数 starmapContainer()。

### 验证（浏览器实测，非估算）
- go vet 干净；全量测试通过
- 首屏（overview）：只拉 status/runtime/chat-history/persona/memory-graph，
  kernel 与 settings 确认**未出现**
- 逐页切换记录请求：每页只拉自己那几项
- 空载 40s：37 → 17 个请求
- 运行态面板仍正常渲染（rt-panel 存在、rt-sec-pipe / rt-sec-topo 均在）
- 启动 + 7 个页签全部无控制台异常

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
 2026-09-27 00:23:04 +08:00
JianFeeeee
ae87f4b8b2 perf(webui): 服务端 gzip —— 首屏 wire 字节 -70% 
生产实测：首屏 API 合计 792,933 B，而服务端此前**完全没有** Content-Encoding
（直连 127.0.0.1:8080 与经 nginx 的公网入口两条路径都验过：响应头里没有
该字段，wire 尺寸 == 原始尺寸）。同一份数据 gzip 后：

  /api/v1/kernel     152,667 →  37,697  (-75%)
  /api/v1/chat/history?limit=40   554,764 → 174,594 (-69%)

这些是高度重复的 JSON（同批 key 名反复出现、中文实体名、时间戳），
压缩比自然地高。真实实例上实测首屏 wire 字节 77,943 → 23,339（-70%）。

位置：链改为 proxyDispatch → gzip → logged → mux。夹在 proxyDispatch
与 logged 之间，是因为 proxyDispatch 命中时直接 return、响应来自上游
（其 Content-Encoding 由 httputil 处理），我们不插手；门户自身的全部
响应（requireAPI 的 401/503、requireWeb 的 302、HTML/CSS/JS、全部
JSON API）都压。

### 三个必须显式处理的坑

1. **SSE 不能压。** text/event-stream 进 gzip 缓冲后 flush 语义就废了
   （前端收不到流式，要等缓冲攒够）。对 SSE 请求直接透传。
2. **必须透传 http.Flusher。** handleChatEvents / streamOpenAI 里是
   `w.(http.Flusher)` 类型断言；包装 ResponseWriter 会让断言失败 ⇒
   flusher 为 nil ⇒ 走降级分支 ⇒ SSE **静默**坏掉（不报错，只是收不到
   流式）。这不是「顺手加一下」能过的改动，有专门的判据守着。
3. **204/304/HEAD 没有 body**，压它们只浪费 CPU 并加坏头。
   另外 webp/png/zip/gzip 等已压缩类型也跳过（mascot.webp 133KB 就在内）。

### 小于 1KB 的响应不压
gzip 头 23 字节，几百字节的 JSON 压完反而更大。与 nginx 的
gzip_min_length 1000 对齐。实测 /api/v1/status（197B）不带
Content-Encoding。

### 状态机写成枚举而非多个 bool
第一版用 passthrough/decided/buffering/allowBuf 四个 bool 交叉表示，
结果出两个 bug：小响应内容被写成空、已压缩类型仍被压。根因是
「该不该压」在 Write / WriteHeader / 收尾三处各判一次且判据不一致。
改成单一 mode 枚举（undecided/passThrough/buffering/streaming）、
判据只在 WriteHeader 与 Write 各求值一次后，两个 bug 同时消失。

### ★ 一条判据我自己写错了，值得记下来
TestGzipDropsContentLength 初版断言「压缩响应不应带 Content-Length」，
实测失败。追查后证明**判据错了、代码是对的**：
Go 在 Del("Content-Length") 之后，若响应体小到能被一次性缓冲（<2048B），
net/http 会**自动重算**并补上压缩后的真实长度（实测 14000B → 119B →
响应头 Content-Length: 119，正确）。真正要防的是**陈旧长度**：留着
14000 而实发 119 时，客户端按 Content-Length 读满会先拿到 119 字节再吃
unexpected EOF（已用对照探针实测复现）。判据改成两条：①声明长度 ==
实际读到字节数 ②该值 == 压缩后长度而非压缩前长度。另加一条对照判据
TestGzipStaleContentLengthWouldBreak，把危害钉成可执行断言。

### 验证（不是「应该能跑」）
- go vet 干净；全量测试通过；新增 12 条 gzip 判据；覆盖率 66.5% → 67.0%
- 真实实例（独立数据目录 + 18081 端口）实测：
  · SSE：无 Content-Encoding，2 次独立 TCP 读（逐帧下发，未被缓冲）
  · /api/v1/status（197B）：不带 Content-Encoding
  · /api/v1/kernel -69%、/api/v1/settings -73%、/api/v1/plugins -63%
  · 首屏 wire 字节 77,943 → 23,339（-70%）
  · 内容完整性：gzip 解压后与明文逐字段相等（plugins/tools/build/
    channels 名称集合与顺序均一致）
- ★ 途中被一个「MISMATCH」误导过一轮：/api/v1/kernel 两次请求字节不同。
  追查发现是 IOManager.ListChannels 遍历 **map**（Go 每次迭代随机化），
  **在本次改动之前就已不确定**，与 gzip 无关。差点被我误报成压缩 bug。

附：dashboard.js 被自动格式化器整体重排（6783 增 / 6293 删，纯空白与
引号风格）。已用 prettier 归一化后逐字节比对确认**零语义差异**。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
 2026-09-27 00:02:28 +08:00
JianFeeeee
9346fed0d9 feat(webui): 星图跟随 agent 活动 + 搬到主页 + 修分类配色从未生效 
星图此前只是静态展示：starmapAnimate() 只转星空，节点完全静止，
与 agent 的动作零关联。本轮三件事。

★ 修一个从未被发现的 bug：分类配色一直是坏的
  服务端 type 是首字母大写（"Concept"，见 internal/memory/graph.go），
  而 smTypeColors 的键全是小写 ⇒ 永远匹配不上 ⇒ 1151 个节点全渲染成
  同一个灰色 0xcccccc。浏览器实测确认：改前 colors=["cccccc"]，
  改后 ["44ff88"]（概念绿）。

一、跟随 agent 动（三路信号，全部在渲染循环里推进，不另起定时器）
  1. tool_call / stage / agent_output 的 SSE 事件 → 命中节点发光冲高
     + 尺寸微扩。工具名按**词**匹配实体（knowledge_list → knowledge_*）。
  2. /runtime 调度器（3s）→ 排队/中断/挂起时全图绷紧；中断或抢占计数
     上升时来一记强脉冲。
  3. /memory/graph/pulse（10s，新端点）→ 新记忆「生长」：从 0 弹到
     正常大小并留余晖。
  另：距上次活动越近，全图越亮（抽样呼吸）—— agent 一忙图就活。

二、搬到主页 + 独立页签
  总览页内嵌 360px 星图；顶部导航加「星图」独立页签（全高 + 图例）。
  同一套 renderer 用 appendChild 在容器间搬运 canvas（three.js 的
  canvas 只能有一个父节点，同时渲染会一边黑屏）。

三、性能：保留全部 1151 节点，但全部降规格
  改前每节点 = 独立 SphereGeometry(16,12) + 独立光晕球 + 一张 256x64
  CanvasTexture ⇒ 2302 个独立 geometry、约 88 万三角形、1151 个
  <canvas>，仅文字贴图就吃约 72MB 显存。全景远看根本读不清那些标签。
  改后：共享 SphereGeometry(8,6)（约 84 三角形/节点）；标签改为 hover
  时在容器角上显示 HTML 文本（零显存，且比 3D 贴图更清晰）；
  866 条边按关系类型合并成 4 个 LineSegments（draw call 866 → 4）。
  hover 复位随之改为 baseScale —— 旧的 set(1,1,1) 会把按 mention_count
  缩放过的大节点缩成最小尺寸。

四、/memory/graph 瘦身：不再下发稠密向量
  星图是本接口唯一消费者，却从不读 vector。生产实测该字段占
  79,314 / 402,811 字节 = 19%，而 8 块记忆就这么多，200 块就是 ~2MB
  白查白发白堆。真实数据集实测响应 402,811 → 326,997 字节（-18%）。

新增 /memory/graph/pulse：只回 since 窗口内变动过的实体（id/name/type/
mention_count/updated_at）。星图每 10s 拉它来判断「哪个节点新长出来」，
而不必重拉 400KB 全量。

验证（不是「应该能跑」）：
  - go vet 干净；go test 全绿；新增 5 个测试（向量裁剪 / pulse 窗口 /
    since 放大 / pulse 不带向量 / 类型断言失败时透传不丢数据）
  - 覆盖率 65.5% → 66.5%
  - 真实 1151 节点数据集上跑 headless chromium + SwiftShader 实测：
    nodeMeshes=1151、edgeSegs=4、geoShared=true、控制台零报错、
    图例与统计（1151 节点 / 866 关系）正常、canvas 在两个容器间正确搬运
  - 脉冲匹配在浏览器里逐个 hint 验证：
      knowledge_list → 2 个（只命中 knowledge_base / knowledge_list）
      qq_get_message 等无匹配 → 8 个（走「整体活动」兜底）
    ★ 途中修掉自己的两个错：① 最早的子串匹配让 hint="knowledge" 命中
    全部单字实体（一次 pulse 选中 250 个、队列顶到 260 上限）；
    ② 改成词匹配后，旧的「补齐到 20 个」逻辑又把 1 个真实命中补成 20 个
    无关节点 —— 现象与①一样，只是成因不同。补齐现在只在**完全无匹配**
    时启用。

未做（本轮范围外）：服务端 gzip（首屏 793KB 无压缩，实测可压到 ~240KB）、
renderAll 按页签懒加载（首屏仍在拉隐藏页签的 kernel+settings 共 230KB）、
setInterval 15s 全量重拉（空闲 53MB/h）。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
 2026-09-26 23:31:58 +08:00
JianFeeeee
bf5d8915dd docs(site): 介绍站补「场面涌现」板块 
三层记忆那张图只讲了字面相关性召回，缺了按场合召回的那一半。
新增一段说明：场面指纹（通道/对象/工具/话题/时段）如何自己长成场面、
为什么只发生一次的不算场面、以及 ScenePolicy 声明项（默认参与）。

沿用现有 card/grid-3/reveal class，视觉与既有三张卡一致；
div 与 p 配平关系与改动前完全一致（142/142、差值 40 未变）。
 2026-09-26 23:14:17 +08:00
JianFeeeee
2567a22be5 fix(memory): 场景键两路合并去重（现网日志实测 scenes=[chan:qq chan:qq]） 
现网 21:49 的 QQ 轮次日志打出 `scenes=[chan:qq chan:qq]` —— 同一键
出现两次。查因：tooldefs.go:63 与 task.go:793 是同一段拼接写法，

    scenes := a.sceneKeysFor(...)      // 内部有 seen 去重
    turn := a.resolveTurnScenes(...)
    for _, k := range turn.Keys {
        scenes = append(scenes, k)     // ← 两路之间没有共同的 seen
    }

而声明路与通道派生路都会产出 chan:qq（既是插件声明的、也是从
evt.Source 派生的），于是重复。

功能上无害（RecallByScene 内部会再去重），但有两个实际代价：日志里
的 scenes=[...] 误导排查——会让人以为场景集合本身有问题；以及每次
白走一遍前缀匹配。

修法：抽 mergeSceneKeys 共用函数（顺带消掉两处重复代码），两处调用点
都走它。判据 scenemerge_test.go 5 例：3 个合并场景（同名 / 归一化后
同名 / 多路重复）+ scene_policy=none 时两路皆空（防「声明路关了但
涌现路还开着」的半开状态）。

记忆 8 包 + agent/core 全绿，8 包齐全、无 FAIL/panic/race。
 2026-09-26 21:55:12 +08:00
JianFeeeee
13a070fbb2 docs(memory): 标记步骤 3/5 完成，补步骤 4 部署前基线与硬约束 
步骤 4 加了硬约束提醒：必须先部署含 R1 修复的二进制再清理，否则
重新涌现出来的还是带 +/# 的旧键。并记录部署前实测基线（PID 92115、
子进程插件 25、近 24h 异常日志 0、场景 65），以及 homed --version
这个 flag 并不存在（纪律清单那条要用 status 接口或 ps 核对）。
 2026-09-26 20:17:17 +08:00
JianFeeeee
758ec11832 fix(memory): 图整备覆盖 scenes + 证据桶按桶清（R3/R5） 
R3：图整理心跳只查 entities/relations，scenes 完全没有整备路径。
Recall(nil,nil,1,"") 的全量路径只 SELECT 这两张表
（graph.go:609/631），于是同一场面的双胞胎键从建库起无人发现：
auto:chan:qq+part:morning 累积到 strength=271 / 6 features / 0 refs，
孪生的 auto:chan:qq_part:morning 持有 210 refs 却 0 features
（聚类只读 scene_features，所以它永远不被看见）。

新增 GraphDB.DedupeScenes：归一化后同名的场景合成一个——强度相加、
特征取并集（权重取大）、引用全部重定向，存活者保留 id 最小行，
跨 origin 也合。接到 mergeLoop 尾部。

为什么不塞进 detectEntityMerge 的双重循环：
- 实体是全库两两 bigram + LLM 裁决（1 万实体实测 5000 万次配对、
  ~224GB 瞬时分配每轮，是独立问题）；
- 场景的判重口径是**归一化后是否同名**——同名即同一场面，键相同
  本身就是证据，不需要 LLM 裁决。而「像不像」是 EnterScene 聚类的
  职责，不是这里的事。
只做同键合并、不做相似度合并：把 chan:qq 与 chan:webui 合并是危险
的，去重不是「把像的一律合并」。

生产库副本实测（sqlite3 备份式复制到 /tmp，未碰生产）：
65 个场景 → 合并 8 组 → 57 个；
auto:chan:qq_part:morning 的 refs/rel/ent 一条没丢，strength 1 → 272。

R5：createSceneLocked 新场景成立时执行的是
`DELETE FROM situation_evidence`（全表清），而证据表是多通道共用的
计数桶。后果不是「多清一点」：qq 的场景一长出来，就把 mc/webui/cli
尚未攒够 minSceneEvidence=2 的证据抹掉，它们的计数被反复清零，
于是**永远**攒不到 2 次。判据实测：6 个通道各来 3 次，只长出 2 个场景。
改为 `DELETE ... WHERE label = ?`，只清本指纹那个桶。

判据：scene_dedupe_test.go 8 例（含「不同场面不得被合并」与幂等）、
scene_evidence_test.go 3 例。均先红后绿。修 R5 时差点栽：桶键是
sig.Label(2) 本身、不带 auto: 前缀（base 才是带前缀的场景键），
第一版删错对象会「一条没删却看起来通过」，用探针实测真实桶键后改正。

记忆 8 包 + agent/core 全绿，8 包齐全、无 FAIL/panic/race。
 2026-09-26 20:16:11 +08:00
JianFeeeee
8887e06274 feat(sdk+memory): 补 ScenePolicy 声明项，让通道能退出场面识别 
缺口（R6）：ChannelDef 的记忆声明已有三件套——NoMemory 管「进不进
记忆计算」、ContextPolicy 管「裁不裁上下文」、RecallPolicy 管「召不召回
记忆」，唯独没有「这条输入算不算一场戏的一部分」。现状是无条件参与：
situationFeaturesFor 里只要 evt.Source != "" 就产出一个 chan 特征，没有
可关的开关 ⇒ chan:system / chan:kernel / chan:timer 这类纯内部信噪通道
也在撑场面，每次触发都让不相干的场景长出来或变强，召回时又会把
「内核在跑定时器」当成「用户在这类场景下说过的话」取回。

穷举确认不是查漏：go.mod replace 指向 third_party/homeagent-sdk，
plugin.go 中 scene 出现 0 次，SDK 自身 git 历史 -S'Scene' -- sdk/ 为空。

SDK（纯追加，老插件行为逐字节不变）：
- 常量 ScenePolicyAuto / ScenePolicyNone + ValidScenePolicy，形状与
  ContextPolicy / RecallPolicy 完全一致
- ChannelDef.ScenePolicy 与 InjectOptions.ScenePolicy，均带 omitempty
- 默认取 auto（参与）而非 none：场景只附加检索路、不改记忆本体，
  默认关会让存量通道突然失去召回；「关」是少数意图。与 ContextPolicy
  刻意相反（同为破坏性操作，那里是默认关）。

内核：
- applyInjectOpts 搬运 scene_policy（与另外三个标志位同面）
- sceneSuppressed 完全照 recallDeclared 的形状：注入点 payload >
  通道定义 > 默认。none 时连时段(part)特征都不产，也不派生场景键
  （只停指纹采集而留声明路，等于给这个口子开后门）
- situationFeaturesFor / sceneKeysFor 由包级函数改为 Agent 方法
  （需要 a.io 查通道定义），23 个调用点同步

判据：scenepolicy_test.go 7 例，改前编译期红（undefined:
pubsdk.ScenePolicyAuto），改后全绿。其中两例专门护住「未声明时行为
逐字节不变」，是纯追加承诺的护栏。

记忆 8 包 + agent/core 全绿，8 包齐全、无 FAIL/panic/race。

存量通道标注待定：kernel/timer/offload-*/child/* 是纯 0-refs 信噪，
可直接标 none；但 mc:system(12 refs) 与 system(3 refs) 带真实记忆，
性质不明，不擅自标。
 2026-09-26 20:09:17 +08:00
JianFeeeee
f441574b80 docs(memory): 补 R6/R7 与 SDK 声明项方案，重排为 7 步 
R6：ChannelDef 的记忆声明已有三件套（NoMemory/ContextPolicy/
RecallPolicy），唯独没有「这条通道是否参与场面识别」，现状是无条件
参与 ⇒ chan:system/kernel/timer 等内部信噪通道也在场面聚类里。
穷举确认非查漏：go.mod replace 指向 third_party/homeagent-sdk，
plugin.go 中 scene 出现 0 次，SDK 自身 git 历史 -S'Scene' 为空。

R7：payload[scene] 的层级键（chan:qq/peer:group_1）已支持前缀
召回（RecallByScene scene.go:351），但因 R6 无人使用而闲置。

步骤重排为 7 步：SDK 声明项提到步骤 2（用户已授权动公开 SDK，
开发阶段非 release 阶段），并把「peer 覆盖面」拆到步骤 6 单列，
先只读调查插件手上有什么再动。
 2026-09-26 20:03:51 +08:00
JianFeeeee
6e9420965d docs(memory): 补 R4 覆盖面与 R5 证据桶两条根因 
R4：现网 65 个场景键里 peer 主导 0 个、topic 主导 0 个，36 个
auto:chan + 26 个 chan: 全部锚在输入通道。两个独立原因：
采集侧全仓无插件在 InjectInput 填 peer/group_id/user_id/chat_id
（日志中 peer 出现 0 次）；排序侧 chan 与 peer 权重同为 1.0 而
NewSituation 稳定排序让 chan 恒在前，即使采集到也进不了 Label(2)。
这与 R1/R2 是不同层面：R1 修完只会得到「正确的单一维度」。

R5：createSceneLocked 新场景成立即 DELETE FROM situation_evidence
（全表清），会连带清掉别的场景尚未攒够门槛的证据。
 2026-09-26 19:58:00 +08:00
JianFeeeee
1fa9ef68a4 fix(memory): 场景键归一化 + 排除最弱维度，修双胞胎与空转 
现网实测：scenes 表 65 行里有 6 组是同一场面的双胞胎键，最严重的
auto:chan:qq+part:morning 累积到 strength=270、6 个 features、
0 条记忆，日志里被"命中"179 次；孪生的 auto:chan:qq_part:morning
则持有 201 条记忆却有 0 个 features（不参与聚类）。两套特征体系
各活各的，谁也发现不了谁。

病因：键构造不唯一。
- Label() 直接用 "+" 拼接且不过 NormalizeSceneKey，而
  EnsureScene / effectiveScenes / RecallByScene 三处都过了归一化。
  "+" 会被 normalizeSceneSegment 归一成 "_"，于是两个字符串都合法，
  key UNIQUE 约束拦不住。
- Label(2) 会把权重仅 0.2 的 part（时段）挤进场景身份。实测
  morning 场景吞掉 evening 指纹：共享 chan:qq 权重 1.0、并集含
  part 0.2×2，相似度 1.0/1.4 = 0.714 > joinSceneThreshold 0.5。
  这本就是加权 Jaccard 的正常行为，但键名不该写进时段。
- createSceneLocked 的 "#N" 冲突后缀同样会被归一成 "_"，
  造成 auto:chan:mc:event+topic:mc#2 在库、而写侧归一化后去找
  auto:chan:mc:event_topic:mc_2 —— 又一对匹配不上的双胞胎。

修法：
- Label 只取权重 ≥ 0.5 的主导特征，结果过 NormalizeSceneKey；
  全部特征都弱于门槛时退回最强的一批（宁可名字信息量低，也不能
  没有名字 —— 没名字就没有键，场景根本长不出来）。
- createSceneLocked 对 base 再做一次防御性归一化，并在 label 为空
  时拒建无名场景。
- 冲突后缀由 "#" 改为 "."（'#' 会被归一化，'.' 是白名单字符）。

判据：新增 scene_key_test.go 6 例，参照物在生产代码之外（"同一场面
⇒ 同一个键"这条不变量 + 直查 scenes 表复算行数）。先跑红确认判据
在跑（4 红 1 绿，失败的正是键唯一性/时段污染/证据桶），再改实现。
其中 TestWrittenRefReachableFromItsScene 一开始就是绿的——写侧到读侧
那条路本身是通的，坏的只是键的构造。

记忆 8 包 + agent/core 全绿。
 2026-09-26 19:56:28 +08:00
JianFeeeee
8bd8271f49 Revert "fix(agent): output_send 缺收件人时从输入事件自动补" 
This reverts commit 6b74862.

## 为什么撤

方案本身是错的，三点：

1. **假设 meta 的收件人字段跨通道通用。** 只实现了 qq（user_id/group_id），
   而 wechat、群聊各有各的字段名。逐通道补全会变成一张靠猜的映射表，
   每加一个通道就得重猜一遍。

2. **假设「回复来源 = 收件人」。** 线上实测直接推翻（2026-09-26 19:05）：
   一次请求从 webui 会话发起、却要发到 QQ（input source=webui，
   output channel=qq）。收件人与来源根本不是一回事 —— 用户在
   WebUI 里说"发个 QQ 给我"，收件人只能来自上下文或用户明说。
   按 channel 名补，等于用错误的假设去覆盖真实场景。

3. **没解决问题，反而引入新风险。** 19:05:46 那次照样报同样的错
   （"meta 中需要 group_id 或 user_id"），补全逻辑对跨通道场景无效。
   而一旦补错，消息会发给错的人 —— 那比报错坏得多。

## 保留的部分

现象描述与排查结论留在这个 revert 的说明里，便于后续重新设计时
不再重复踩：各通道 meta 结构差异极大，要让插件自己声明收件人来源
（qq 插件知道自己的 user_id 从哪来），内核只转发不猜。

不采用"把格式写进工具描述"这类方案：那只缓解症状，
且各通道格式仍需逐个核实。
 2026-09-26 19:11:51 +08:00
JianFeeeee
6b74862118 fix(agent): output_send 缺收件人时从输入事件自动补 
## 现象（线上 2026-09-26 17:57）

用户从 QQ 私聊发来消息，agent 生成了回复也调了 output_send__qq，
但**没填 meta**：

  17:57:45  qq_get_message → {user_id: 2198972886, message_type: private}
  17:57:46  output_send__qq → 失败：meta 中需要 group_id 或 user_id 字段
  17:58:14  output_send__qq_help → 查格式
  17:58:14  output_send__qq → ok      ← 靠重试成功，整轮耗时 74s

信息内核**本来就有**（输入事件里带着 user_id/group_id），却要模型从
qq_get_message 的返回里手抄进 meta。抄错就失败，失败才去查 _help。
而"回复"这件事的收件人是确定的（= 消息来源），本不该由模型负责。

运气差就不重试：同日 17:15 / 17:21 两次 `tools=[]` —— 模型压根没调
output_send，回复生成了但没发出去，日志连一行告警都没有。

## 改法

meta 缺收件人时，内核从**本轮输入事件**推导后补上。模型只需给内容。

## 边界（都刻意收窄：宁可不补，也不能补错）

- 显式传了 meta ⇒ 原样返回。主动 DM 别人等场景必须保持原行为。
- meta 里已有 group_id/user_id ⇒ 不覆盖。
- meta 是坏 JSON ⇒ 原样返回。让下游报"格式错"，而不是被静默替换成
  一个模型没要求过的收件人 —— 那比报错更坏：消息会发给错的人。
- 非 qq 通道（如 webui）⇒ 不补。webui 走 ResponseCh，不过 output_send。
  其余异步通道（wechat 等）不猜：猜错等于发错人。
- 输入事件里没有收件人信息 ⇒ 留空，让下游按原逻辑报"需要 user_id"。
  宁可报错让模型重试，也不要编一个收件人。
- 群消息里 user_id 是**发送者**不是收件人 ⇒ group_id 非 "0" 时优先用
  group_id，否则会把消息发回给群成员本人。

数字型 user_id 要按整数格式化：JSON 反序列化成 float64 时
fmt.Sprint 会得到 "2.198972886e+09"。

## 判据：7 条

私聊补 user_id / 群聊补 group_id 且不补 user_id / 显式 meta 不改写 /
已有收件人不覆盖 / 坏 JSON 不静默替换 / webui 不补 / 无信息留空（含 nil evt）。

★ 实现时我先自己写了个 payloadString，编译报错才发现包内已有更完整的
  版本（memorypass.go:176，含 float64/int64/int/json.Number 分支），
  直接复用 —— 不重复造轮子。

全量 42 包绿。
 2026-09-26 18:29:23 +08:00
JianFeeeee
bd1d5fff2b chore(vendor): 主仓不再跟踪 SDK 示例代码（决策 A） 
## 背景

`.gitignore` 第 26-45 行早已写明「外部插件与工具链维护在独立 SDK 仓
（决策 sdk_repo_only），本仓经 go.mod 的 replace 引用」，并忽略了
example/、tools/、docs/、site_build/、package/、scripts/。

但有 29 个文件**早于该规则**被跟踪，靠「已跟踪文件不受 .gitignore
影响」留着，注释还特意写了「这是有意的，不要『修』」。

本轮修 example/bili 时踩到了：那 87 行改动先落在主仓、再手动同步到
SDK 仓 —— 同一份代码两个仓各改一遍，正是这个遗留结构的成本。

## 核实：主仓到底需要什么

- 主仓 Go 代码只 import 两个包：`homeagent-sdk/sdk`（插件入口）、
  `homeagent-sdk/meta`（版本号）
- `remotedevice/` 是 C 库，主仓 C 侧明确「不链接任何外部库」，
  只有注释里提到它
- `tools/hmapdev/yaegi` 的 import 出现在 **SDK 仓自己的文件之间**
  （yaegi/interp.go → yaegi/mocksdk），不是主仓依赖；
  且 tools/ 本就在 .gitignore 里，从未被跟踪

所以 29 个文件全部可以删。实际仓库负担也只有 42 个文件 / 0.6MB
（工作树里那 971MB 绝大部分是未跟踪的构建产物，不是仓库体积）。

## 改动

- 删 21 个 example/ 文件（10 个示例的 plg.json + plugin.go + qq/plugin_test.go）
- 删 8 个 remotedevice/ C 文件
- 工作树里一并清掉（不受跟踪的构建产物顺带回收）

构建与全量测试均通过。

## 判据：3 条 + 变异（internal/meta/vendored_sdk_test.go）

- TestVendoredSDKHasNoExampleOrRemotedevice：防止示例代码被重新提交进来
- TestVendoredSDKKeepsRequiredPackages：**反向**保护，防止为省事把
  sdk/ 与 meta/ 也删掉（上一条只防"多了"，删过头要靠这条）
- TestGoModStillReplacesSDKToVendoredPath：决策 A 依赖 replace 指向 vendored 路径

★ 判据自己踩了两个坑，都靠实跑抓出来：
1. `git ls-files` 的路径参数**相对当前目录**解析，而测试跑在
   internal/meta/ 下 ⇒ 就地执行返回空，表现为「必需包全都不在」的假红。
   改用 `git -C <仓库根>`。
2. 把 tools/hmapdev/yaegi 当成主仓依赖写进必需清单 ⇒ 又一次假红。
   根因是把 SDK 内部的引用误当成主仓依赖（它本就在 .gitignore 里）。

变异验证：塞一个 example 文件进版本控制 → 判红。
 2026-09-26 17:18:41 +08:00
JianFeeeee
ceeef0b4e1 fix(proc): 杀插件进程组 + readerWG 超时兜底 —— 修孙进程拖死关停 
## 现象

线上关停必超时：systemd 报 `State 'stop-sigterm' timed out. Killing.`，
进程组里 23 个插件全退完了，最后那条 `[homed] stopped` 仍打不出来。
其中只有 bili 报 `[proc] bili SIGKILL 后 2s 仍未被收割`，之后近 90 秒无日志。

## 根因

bili 用 exec.Command 拉 yt-dlp（源码 example/bili/plugin.go:122/212），
无 CommandContext、无 Setpgid、Stop() 是空的。yt-dlp 再 fork ffmpeg，
**孙进程继承插件的 stdout 管道写端**。

  插件被 SIGKILL → 孙进程仍存活、写端不关
  → readLoop 的 scanner.Scan() 永不 EOF
  → p.readerWG.Wait() 永不返回（Kill 的最后一行，**无超时**）
  → StopAll 的 wg.Wait() 永不返回 ⇒ 关停挂死 ⇒ systemd SIGKILL

内核 process.go:340 的注释早已预警过这个场景（"插件 fork 的孙子进程继承
同一 stdout 写端时，插件本体死了 EOF 也不会到"），但 Kill 没有对应保护。

## 内核三处修法（缺任一条都不够）

1. **spawn 时 Setpgid**：插件自成进程组，不再与内核同组
2. **Kill 杀整个进程组**（kill(-pgid)）：孙进程一起死，管道写端才关。
   兜底：负 pid 失败时退回杀本体（老插件/非 Unix 平台）
3. **readerWG.Wait() 加超时兜底**：这是唯一能保证 Kill 一定返回的地方。
   超时后主动关读端逼 readLoop 退出，再兜一层仍不退就放弃等待 ——
   宁可少等 2 秒，也不能把关停无限期挂住。

## 插件侧（bili）

CommandContext + Setpgid + Stop() 里 cancel 并 wait：
- 只 cancel 不 wait 的话内核会先释放共享段，而 yt-dlp 还在写 stdout
- waitRunGroup 杀整个进程组（ffmpeg 也在内），不留孤儿

## 判据：5 条 + 3 组变异

判据用**真实模板编译的插件**（复用 buildPluginWithRealTemplate，
与 e2e_template_test 同一条路）+ NewHost 启动，不是自造 shim：
裸 Spawn 没有 Host 建共享内存段，插件握手会报 permission denied。

★ 判据自己踩了三次坑，都由变异/合跑抓出来：
1. 给孙进程也加 Setpgid ⇒ 它逃出插件进程组，kill(-pgid) 杀不到，
   造出假失败（真实场景 yt-dlp 不会脱离进程组）
2. 各测试数全局孙进程数 ⇒ 前一个泄漏的被后一个数进去，
   单跑通过、合跑变红。改为记录基线只关心自己新增的
3. readerWG 超时那条用纯构造 &Process{cmd:nil} ⇒ Kill 第 607 行
   早退，根本走不到那段，撤掉超时照样绿。补了「脱组孙进程」
   场景（Setsid 逃出进程组）才真正覆盖到

变异：去 Setpgid → 判红；只杀本体不杀组 → 判红。

全量 41 包绿。
 2026-09-26 16:58:41 +08:00
JianFeeeee
324181d663 fix(plugin): StopAll 并行停插件 —— 修关停必然超时被 SIGKILL 
## 现象

systemd 每次都报 `State 'stop-sigterm' timed out. Killing.`
进程组里 23 个子进程插件**全退完了**，最后那条 `[homed] stopped`
仍打不出来，然后被 SIGKILL。

## 根因（算出来的，不是猜的）

单个插件的 Stop 最坏预算：
  5s（CallContext plugin.stop）+ 5s（等 exited）+ 2s（Kill 后收割）= 12s
串行停 23 个 ⇒ 23 × 12s = 276s，而 systemd 只给 90s。
⇒ 关停必然超时。线上每一条 stop 记录都是 timed out，无一例外。

## 改法

StopAll 改为并行：取插件快照 + 各自的 SDK 句柄后**立即释放 registry 锁**，
每个插件一个 goroutine，等全部完成再释放共享段。

三处必须小心的点（都是并行化引入的新风险）：

1. **先释放 registry 锁再并行停**。p.Stop() 会触发
   markExited → onExit → ReclaimOwner，那条链要读共享内存段。
   持着锁并行跑，若某插件的 onExit 需要拿 registry 锁（摘通道等）
   就是自死锁。
2. **stop handler 的快照要在清空 sdkRefs 之前取**。handler 挂在
   PluginSDK 上（r.sdkRefs），先清空就再也拿不到了。
3. **单个插件 panic 不带崩关停**（那会让剩下的插件全停不掉），
   也不静默吞（留日志）。

## 判据：5 条 + 3 组变异 + race

- TestStopAllStopsInParallel：8 个插件各 120ms，串行 960ms / 并行 120ms。
  判据直接量耗时，串行实现必然变红（实测串行时 962ms）。
- TestStopAllSurvivesPanickingPlugin：panic 不外冒、其它插件照停、不死锁
  （带 10s 超时，死锁会超时而不是挂住测试）
- TestStopAllFreezesAutoRestart / StopsEachPluginExactlyOnce：
  冻结自动重启、每个插件恰好 Stop 一次（重复会二次释放共享段）
- TestStopAllRunsStopHandlerBeforeStop：handler 必须先于 Stop，
  走真实的 PluginSDK.RegisterStopHandler 路径

变异：退回串行 → 判红并打出实测耗时；去掉 handler 调用 → 顺序判红；
假装并行只清空 → 4 条判红。
`-race` 通过（并行化必须验锁，这是本次改动的头号风险）。

全量 41 包绿。
 2026-09-26 16:23:56 +08:00
JianFeeeee
5dd98d7a05 feat(knowledge): 目录批量导入 + 派生数据批量收口 
## 能力缺口

导入只能一条条 Add（knowledge_create）。agent 拿到一份 200 页的
文档目录要调 200 次工具，且每次都得自己决定分类与名字。

新增工具 `knowledge_import_dir(dir, category?, include_media?, dry_run?, max_items?)`。
语义是**复制**不是引用：源文件删改不影响已导入的副本。
- 文本经 Write 整份写入 <知识根>/<分类>/<名>/content.md
- 媒体按 sha256 进媒体库（内容寻址天然去重），条目只存 digest 引用

## 目录约定（自动适配，不要求改造资料）

1. 含 content.md 的目录 ⇒ 整体作为一个条目（与 scanDir 既有语义一致，
   所以知识库自身目录能被原样再导入而不会被拆散）
2. 否则 .md/.txt 等文件各成一条，**目录路径即分类**

## 三个语义决策

- category 是**前缀叠加**（tech + 源结构），不替换：替换会丢掉源目录
  自身最有价值的层级信息
- 同名冲突**跳过并计数**，绝不覆盖：Write 对同名本就是覆盖语义
  （knowledge_create 靠它做更新），若直接调它，一次重导就会把手工
  补充的内容悄悄抹掉，而日志只写"导入完成"
- dry_run **默认 true**：批量写，agent 第一次试某目录应先看清会写什么

## 安全边界（批量操作，缺一道就可能读到不该读的）

- 必须绝对路径：agent 的 cwd 不受控，相对路径会静默导到别处
- 符号链接不跟随：否则一个软链就把知识根之外的文件导进来
- 拒绝把知识库自身当源（自导会无限自我复制）
- category 复用 normalizeName（与 Write 同一道闸，两处分叉就成了绕过）
- MaxItems 默认 500：防 agent 误传 "/" 把盘灌满

## ★ 批量导入暴露的既有 O(N²)

Write 每条末尾都调 flushDenseLocked，而 saveDenseCacheLocked 是
**全量序列化整个 items map 再重写整个文件**。按 512 维 float64 估，
单条约 10KB，导入 500 条累计要写约 1.4GB。

仓库里索引侧早已有 indexDirty 的「标脏+延迟收口」（实测 writeIndexLocked
6.7ms/次、占单条 Add 绝大部分），**稠密缓存却还是逐条全量重写** ——
同一类开销只修了一半。

照 indexDirty 的模式补 batchDepth：批量期只标脏，endBatch 收口一次。
用 defer 保证提前 return 也会收口 —— 否则这批向量会留成"标脏未写"，
下次启动被当作缺失而全量重算。

## 判据：17 条 + 变异

安全边界做了 4 组变异验证（去符号链接拦截/去绝对路径要求/去自导检查/
content.md 目录不下钻）。

★ 判据第一版有两处自己骗自己，被变异抓出来：
1. 符号链接判据造的是**目录软链**，而 WalkDir 对目录软链本来就不下钻
   ⇒ 有无防护结果都一样，是假绿。改成**文件软链**后才真正判红。
2. 同名冲突判据里已有条目写成 "a/b"、源映射出的是 "b"（不同名），
   判据自己就错了 —— 修判据而不是改实现。

媒体路径用假 MediaPutter：验的是「调了 Put 且 digest 挂到条目上」，
媒体库自身的落盘去重是 media 包的判据，不该在这里重测。

全量 41 包绿。
 2026-09-26 16:19:10 +08:00
dev
ef695c2723 chore(meta): main 构建产出 1.4.0dev 路牌，不再自称旧 patch 线 2026-09-26 15:44:35 +08:00
JianFeeeee
dfc05780fd feat(kbtree): 知识库暴露范围配置 —— 按树状只暴露指定分类 
## 问题

kbtree 是**唯一**把知识库开放给外部进程的通道（HomeAgent 自己的 agent
走进程内直调 knowledge_* 内核工具，不经此），但它只有 listen_addr 与
token 两个配置，**没有任何范围限制**：拿到 token 的任何 agent 都能
/tree 列出全部条目、/search 取回任意条目全文。

本机库里混着个人内容（航空发动机教材摘录、课表、身份合并规则），
不该 broadly 可读。

## 改动

1. `internal/plugins/kbtree/scope.go`（新）：暴露范围语义
   - 留空 = 全部可见（范围是"限制"不是"必填"，留空保持既有行为）
   - 前缀按**路径分段**匹配：public 命中 public 与 public/tech，
     但**不**命中 publication（否则 publication 意外暴露）
   - 根下无分类的条目在范围非空时不可见 —— 它没有分类可匹配，
     放行等于范围形同虚设
   - 分隔符容忍逗号/分号/空白/换行/竖线：这是给人手填的字段

2. `plugin.go`：注册 `expose_categories` 配置项，接入**全部四个端点**
   - /tree      服务端裁剪子树（就地改，不重建：TreeView 字段多）
   - /categories 过滤路径列表
   - /counts    过滤计数并**重算 total**（数量本身也是信息泄露）
   - /search    ★ 过滤结果条目；这处最关键：
     只过滤 /tree 而放过 /search 等于范围形同虚设（换个 ?q= 就能拿到全文）。
     同时修正 limit 语义 —— 范围外条目不占名额，范围内条目不会被挤掉。

3. SDK 契约补 `Knowledge.Category`（纯增量）
   - 此前 `sdk.Knowledge` 只有 Name/Content，内核明明返回了 Category
     却在 knowledge_impl 的拷贝里丢掉 ⇒ 外部服务无法按分类判定，
     范围过滤在 SDK 层根本做不了。
   - Name/Content 均保留，无删除。

## 判据（8 条 + 4 组变异）

范围过滤最容易"只做一半"，所以每个端点都单独钉。

★ 判据补强一处：初版只查条目名（priv1），结果「/categories 不过滤」
  这个变异**完全逃过** —— 分类端点返回的是路径不是条目名。
  补上分类路径断言（private）后判红。

变异验证：
- /search 不过滤      → 泄露 priv1 全文        ✓ 判红
- /categories 不过滤  → 泄露 private 分类路径   ✓ 判红（补强后）
- /counts 不过滤      → TestCategoriesAndCountsEndpoint 判红
- 前缀退化为字符串前缀 → publication 被误暴露      ✓ 判红

★ 过程中我的 fake 有两处与真实内核不符，先修 fake 再修实现：
  1. 漏了内核 treeLocked 的"子分类提升一层" ⇒ 得到 children=0 的假空树
  2. filterTree 无差别清空 t.Items ⇒ 整棵树只剩空壳节点
  （第一版的实现是"看着测试红就改"，实际是 fake 在骗我）

全量 41 包绿。SDK 接口纯增量，未发布故无需冻结检查。
 2026-09-26 15:31:15 +08:00
JianFeeeee
78806efa0f fix(kbtree): 修客户端脚本三处实测暴露的缺陷 
都是本机装好后逐条跑命令发现的，不是设想：

1. **token 找不到**：脚本找 `scripts/../config.json`，而实际文件在
   `<skill>/config/config.json`。症状极具迷惑性——「明明配了 token 却说
   没找到」。改为两种布局都试，并在注释里写明为什么不能只写一种。
2. **`-h` 也要 token**：帮助段排在 token 检查之后，`kb_tree.sh -h` 会被
   拦下报「未找到访问令牌」。把 help 提到最前。
3. **`-q` 被当成命令名**：`kb_tree.sh -q 并发`（不给子命令）报
   「未知命令: -q」，而这是很自然的写法。改为：第一个参数是选项时不取作
   子命令，解析完选项后再定——有 -q 走 search，没有走 tree。

另外把 curl -f 换成 -w + 自行判状态码：-f 在 4xx 时只吐一行
`curl: (22) 404`，把响应体丢掉，而 404 响应体里恰是「现有分类」清单，
是排查时最需要的。现在 401/404 都会给出可行动的中文提示，
退出码 0/2/3/4/5/7/8 各有语义。
 2026-09-26 14:47:32 +08:00
JianFeeeee
5a889007d7 docs(kbtree): 补客户端封装脚本 + 本机部署交接说明 
SKILL.md 里原本只有 curl 示例，agent 用起来要自己拼 URL 与鉴权头。
补 scripts/kb_tree.sh（照 dify-ops 的做法把脚本随 skill 分发）：

- 子命令 tree/categories/counts/search，选项 -q/-c/-d/-i/-l
- token 读取顺序：KB_TOKEN 环境变量 → config/config.json。
  **故意不接受命令行传 token**（会进 shell 历史与 ps 输出）
- 预检端口：不通时直接说明「服务未上线」并给出上线步骤，
  而不是抛 curl: (7) Connection refused 让用户自己猜
- 错误翻译成人话：401 → 令牌无效；404 → 附上服务端返回的现有分类
  （用 curl -w 而非 -f，否则 404 响应体里最有用的那份清单会被丢掉）
- 退出码：0 成功 / 2 参数 / 3 令牌 / 4 分类不存在 / 5 HTTP / 7 连不上 / 8 请求失败

DEPLOY.md 是给部署方的交接单：本机 kbtree 代码已合入 main 且 skill/token
已就位，但**运行中的二进制里没有 kbtree**（14:35 有人换过一版二进制），
故替换与重启留给部署方。含备份/替换/验证步骤、回滚方式、端口与 token 说明。

token 与 config.json **不入库**（config/ 目录留空），安装时由部署方从
配置库 config_kbtree 表读取后写入本机。
 2026-09-26 14:43:46 +08:00
JianFeeeee
7212ab4aad fix(webui): 星图依赖本地化 —— 不再从公网 CDN 拉 three.js 
用户点「星图」看到「3D 星图不可用（CDN 加载失败）」。

服务端 curl 那两个 URL 都是 **200** ⇒ 不是服务端的问题，是**浏览器**
访问不到公网 CDN（内网 / 出口受限 / 断网）。dashboard.html 从 cdnjs 与
jsdelivr 拉 4 个库：three.js、OrbitControls、marked、DOMPurify。

换 CDN 只是把同一个赌注重下遍。HomeAgent 明确支持离线与内网部署，
前端却有 4 个硬依赖在公网上 ⇒ 断网即坏，且用户无从修复。

顺带两个收益：
- **安全**：DOMPurify 是净化 Markdown 的关键一环，它挂掉前端会退化到
  「不净化」分支（dashboard.js 里有 typeof 检查）—— 那是安全降级，
  比星图坏更值得修。
- **体积**：四个库共 ~700KB，embed 后由本服务同源提供，省掉 4 个跨域握手，
  也不再受第三方可用性影响。二进制 84MB → 84.7MB（+0.8%）。

- `internal/plugins/webui/static/` 放四个库（固定版本，随二进制走）
- `//go:embed static` + 新增 `/static/` 路由
- dashboard.html 的四个 src 改指 `/static/...`
- 加载失败兜底 8s → 3s（本地是毫秒级；仍超时就说明真有问题）

`/static/` **不走 requireWeb**：未登录时页面也要加载这些库才能渲染登录框，
加认证会让用户看到白屏（比 401 更难自查）。这些资源不含用户数据。

- TestDashboardHasNoExternalCDN：页面不得引用任何公网 CDN
- TestStarmapDependenciesAreLocal：星图两个库必须来自本地
- TestVendorFilesExistInSourceTree：vendor 文件必须在（embed 的前提）
- TestStaticVendorRoutesServeRealLibraries：路由**必须真的返回库内容**

★ 最后一条的判据强度是补出来的：初版只判状态码，变异「返回 200 + 空体」
时**仍然绿** —— 而空体在浏览器里的症状与 404 完全一样（都报加载失败）。
改为同时判体积与特征串（REVISION / OrbitControls / marked / DOMPurify）
后，变异「只写前 10 字节」判红。

变异验证 3 条：HTML 改回 CDN → 2 条判红；路由挂回 requireWeb → 503 判红；
截断响应体 → 体积判红。

全量 38 包全绿。
 2026-09-26 14:41:32 +08:00
JianFeeeee
41d754334e feat(kbtree): 知识库分类树的独立只读服务 + agent 技能 + WebUI 树浏览 
让**外部 agent** 也能按分类树用这套知识库。HomeAgent 自己的 agent 仍
直接调内部方法（knowledge_search/create 等），走进程内直调，不经此服务。

一、内核树视图（internal/knowledge/tree.go）
  为什么不复用 TreeIndex：那个是**内部导出物**，面向 .index.json 落盘，
  每个条目带 top-20 的 TF-IDF 特征向量。直接序列化给外部有三个问题：
  体积（200 条时 .index.json 已 246KB 且冗余存了 preview，而正本在
  content.md）、泄漏（稀疏特征表 = 分词/IDF 内部表示）、语义错位
  （外部要的是"有哪些分类、每类下有什么"）。
  新增 TreeView/Subtree/Categories/CategoryCounts：不含向量，带条目数
  与可读摘要，支持 MaxDepth 懒加载、IncludeItems 只看结构。
  节点 Name 是**本级段名**（"go"）、Path 是完整路径（"tech/go"）——
  最初把全路径写进 Name，前端拼层级会得到 "tech/tech/go"，已修。

二、kbtree 插件：独立 HTTP 服务（默认 127.0.0.1:9892）
  为何不挂在 WebUI 的 /api/v1/knowledge* 下：
  1. 不共享鉴权与端口。WebUI 的 api_key 是给人操作界面用的，把它分发给
     外部 agent 等于把管理面凭据扩散出去。本服务用**独立 token** +
     独立端口，可单独关闭（token 未配置则启动时随机生成）。
  2. 只读。写入要决定分类归属与媒体处理，外部自行拼装容易造出越界/重名
     条目 —— 写入留给内核工具。
  3. 形状按树组织，而不是平铺搜索接口。
  端点：/tree（可指定 category/depth/items）、/categories、/counts、
  /search、/ （自述）。全部需 token（X-API-Key / Bearer / ?token=），
  非 GET 一律 405。无知识库时 Start 直接失败，不占端口。
  鉴权与 Slowloris/超时设置照 remotedevice 范式。

三、agent 技能（assets/skills/knowledge-base/SKILL.md）
  指令文档型 skill：教模型"先看树 → 定位分类 → 分类内检索"，并列出
  易错点（name 已含分类别再拼、只看第一条、404 附现有分类）。
  加载与校验由 internal/plugin/skill_bundled_test.go 守住 —— 这条断言
  的由来：非白名单的二级标题会被 extractToolDefs 当成工具定义，报错
  "invalid tool name"，而提示与真正原因（标题层级）毫无关联。
  kbtree 的测试还会校验文档提到的端点与代码一致，防漂移。

四、WebUI 树浏览（前端真正用起来，而非留一个没人调的端点）
  面板加可折叠的分类树：逐级点选即把搜索范围切到该子树（原先是让人
  手打分类名）。当前范围有可见标签与「全库」复位。
 2026-09-26 14:20:19 +08:00
JianFeeeee
ce694bc1a1 test(knowledge): 端到端验证多模态与分层链路 + 修稠密路同分次序不确定 
一、修缺陷：denseHits 同分次序随机
  稠密路用 map 遍历 + 只按分数排序，**没有 tie-break**：同分条目的相对
  次序随每次调用变化 ⇒ 同样的查询两次可能给出不同首位（用户看到结果在跳，
  测试偶发变红）。Search 的主排序早就有「分数相同时按名字定序」，这条漏了。
  补上同分按 id 定序，并加 TestDenseHitsTieIsDeterministic 反向守住
  （撤掉 tie-break 后该测试在 5 次运行里稳定报出首位跳变）。

二、端到端验证（两个新文件）
- TestMultimodalEndToEndWithRealProvider：走**真实 embedding provider**
  （内置 http provider + 一个符合内核契约的最小服务），覆盖
  embedding.Open → AdaptProvider → media CAS → SetDenseSpace/SetMediaGetter
  → AddWithMedia（文本⊕图片融合）→ 以图搜知识 → .dense.json 落盘 →
  重启命中缓存（ReindexDense built=0）。
  不用 ONNX provider 是因为真模型 200MB 权重 + 3 分钟加载，进不了 CI；
  该链路是 provider 无关的（AdaptProvider 之后内核只认 MultimodalEmbedder）。

- TestHierarchicalIndexEndToEnd：多层分类（tech/go/两段、tech/rust/两段）
  的 Category 推导、树导出结构与挂载点、三级前缀过滤检索、范围外排除、
  索引落盘、重启后不漂移、树在重启后仍可用。
  反向验证：把 inScope 改成恒真后该测试稳定变红（报出范围外条目混入），
  确认它真能抓到「分层不参与召回」这一退化。

三、额外实测（本机，非 CI）
带 onnxruntime tag（生产构建形态）下用真实 Qwen3-VL 模型跑通全链路：
  provider dim=2048 modalities=[text image] fp=e43381246264...
  photo.Dense = 文本⊕图片融合结果
  以图搜知识 top1=photo score=0.757   ← 真正的跨模态召回
  重启后 ReindexDense built=0（命中缓存）
另确认默认构建（无 tag）下 qwen3vl 是 stub、Open 明确报错，不会静默降级成
"看似可用"。Makefile 的 HOMED_TAGS 默认即 onnxruntime，故发行版默认启用。
 2026-09-26 14:20:19 +08:00
JianFeeeee
81cd8231d7 feat(kb-migrate): 存量知识库目录名迁移工具 + 启动期只报告 
背景：旧版 Add 整串 sanitize 名字、逐段 sanitize 建目录，留下 tech/_go_/note、
Tech/Upper、a/b with space 这类「知识名与盘上目录不一致」的目录。修复后
normalizeName 要求二者逐字一致，故需一次性改名。

- 迁移逻辑放在 internal/knowledge/migrate_names.go（PlanMigration/
  ApplyMigration），CLI 与 homed 启动**共用同一份实现**，避免口径漂移。
- 三条硬约束：
  1. 默认只报告（-apply 才真改名）—— 批量 os.Rename 不可逆。
  2. 检出目标名冲突（两条迁到同一目标 / 目标已存在）则**整批拒绝**，
     不做部分迁移：半迁移状态比不迁移更难收拾。
  3. 逐条失败不中断，最后统一报告；执行前重查冲突（计划生成与执行之间
     可能有人改过盘上状态），并校验目标不越出知识根。
- homed 启动在 initKnowledgeStore **之前**调 initKnowledgeMigration：改名后
  扫盘一次到位，避免先以旧名建索引再改名造成内存键与盘上目录短暂不一致。
  defaultApply=false ⇒ 启动只扫描+报告+打印可执行命令行，不替人决定。
  单次改名上限 200 条，防失控目录规模拖住启动。

实测：报告模式零改动；冲突场景整批拒绝且盘上原封不动；迁移后 Store
正确载入 4 条并可按规范名逐条删除。
 2026-09-26 14:20:19 +08:00
JianFeeeee
8842d76aff fix(webui): 知识库不再把二进制当文本存 + 接上分类/媒体/删除 + 实时计数 
后端（handler_memory.go 重写 handleKnowledge）：
- ★ multipart 分支原来无条件 file.Read → string(buf[:n]) → 当 Markdown 存进
  content.md：传一张 PNG 得到的是一份乱码文本知识，还在 .index.json 占一份
  preview，且**没有任何迹象**表明出了问题。
  现在按 http.DetectContentType 探测的**真实类型**分流（不信客户端声明的
  Content-Type——谎报 text/plain 的 PNG 在测试里是真实场景）：
  媒体入 CAS 按 digest 挂条目 / 文本校验 UTF-8 后存正文 / 都不是则 400 明确
  拒绝并回传 rejected 清单。
- 状态码语义修正：此前 POST/GET 一律 500、DELETE 一律 404，把「名称非法」
  这类调用方能自己纠正的错报成服务器故障。现按 errors.Is 分流
  400/404/503。
- 搜索支持 category 与 limit；返回 knowledgeView（不泄露服务端绝对路径，
  不回传几百 KB 的 Dense 浮点数组）。
- 列表端点补 dense 状态（前端据此提示多模态是否就绪）。
- 媒体存储未接线时上传图片返回 503，而非退化成把二进制当文本存。

前端（dashboard.js）：
- 搜索结果从 <pre>{JSON}</pre> 改为结构化渲染（名称/体积/预览/媒体标记
  + 每条删除按钮）。此前前端根本没有删除入口。
- 新增分类输入框（走 category 参数）、多文件上传。
- 计数改实时：原先读 state.kernel 快照，知识条目经工具/上传增删后不会变
  （实测创建完仍显示 "-"）。切到知识面板时拉 /knowledge 的真实 names.length。
- 顶部输入框变多文件；显示多模态就绪状态（ready/total）。
 2026-09-26 14:20:19 +08:00
JianFeeeee
144564f5c2 feat(knowledge): 分类过滤与多模态打通到工具/插件边界 
- internal/sdk：KnowledgeAPI 增加 SearchIn/AddWithMedia/AttachMedia/
  ReindexDense/DenseStats；新增 MediaAPI（Put/Stat/Get）与 PluginSDK.Media()，
  registry 装配。**公开 SDK 契约一字未动** —— third_party/homeagent-sdk/sdk/
  的 diff 恒为 0（发布纪律的硬约束），走 internal/sdk 这条明确不受冻结约束
  的内部扩展路径。
- proc：新增 knowledge.addWithMedia（正文与媒体清单都走共享内存，与
  doc.insertWithMedia 同形）；knowledge.search 支持 category。
- corehandler 用**局部接口 + 类型断言**取扩展能力，而非直接引 internal/sdk：
  后者已依赖 internal/plugin 的类型，直接引会成环（CoreSDK 注释已警示）。
  断言失败明确报"能力不可用"，不静默退化成"媒体已写入"。
- agent 工具面：knowledge_search 增加 category；knowledge_create 增加
  media_digests（复用 doc_commit 的 digest 前缀解析 + Stat 回读 MIME）。
  顺带修 knowledge_search 的分类前缀重复（Name 已含分类，旧代码又拼一次，
  实测输出 tech/go/tech/go/并发）。
- agent 启动接线多模态空间，顺序为先接线再 ReindexDense（否则首次启动
  算出的向量因 MediaStore 未就绪而不落盘）。
 2026-09-26 14:20:19 +08:00
JianFeeeee
9f2ec31cb0 fix(knowledge): 名称规范化/路径安全 + IDF 增量维护 + 多模态稠密路 + 派生数据落盘 
一次知识库子系统的集中加固，四类缺陷各有实测复现：

1. 名称与路径（数据安全，最严重）
   - sanitize 不过滤 .. ⇒ Remove("..") 直接 RemoveAll 掉整个数据目录
     （实测把 <data> 整棵删掉，含 memory/documents/media），且返回 nil，
     工具层回报"已删除"；Add("../../x") 写到知识根外，重启扫不回来
     ⇒ 幽灵条目。
   - Add 整串 sanitize 而建目录逐段 sanitize，内存键与盘上目录从**第一次
     落盘起**就不一致；重启后 name 漂移，knowledge_delete 静默删不掉
     （RemoveAll 删空目录返 nil）。同一个根因。
   - 修法：新增 normalizeName 作为唯一入口（逐段 + 拒绝空段/点段/隐藏段）；
     Remove 改为取条目自记的 Path（不再用名字重拼）+ 返回 ErrNotFound。
   - resolve 三层退让（原样 → 规范名 → 叶名大小写不敏感，唯一命中才接受）：
     scanDir 按盘上目录原样建键，遗留大写目录若只查规范名会变成
     "List 看得到、Remove 报不存在"。删的路径仍取自 Path，退让无风险。

2. IDF 与索引不同步（功能缺陷，非优化）
   - TFIDF Vectorize 跳过 df<=0 的特征，而 Add 只往只增不减的 summaries
     追文本、从不更新 DF ⇒ 库满(≥3篇) + 新词时，新知识**当场搜不到**，
     重启才恢复（实测 Search("量子纠缠") == []）。
   - 修法：vector.Store 新增 AddDoc/RemoveDoc（文档级去重口径与 Train 一致，
     totalDocs 下界守卫，零频 DF 删除防表膨胀）；knowledge 删掉 summaries，
     改 index/unindex/retrain 三件套，覆盖写先 RemoveDoc 旧文本。

3. 多模态稠密路（此前知识库端到端纯文本）
   - 新增 SetDenseSpace/SetMediaGetter/ReindexDense/DenseStats 与
     AddWithMedia/AttachMedia，媒体成为一等节点参与跨模态召回。
   - 维度与指纹双守卫：维度不符的向量会被 FuseVectors 按最大维度拼成错维度
     结果且被当成"已对齐"永久错下去（docStore 踩过）；模态不支持(音频)时
     静默跳过该媒体、退化为纯文本向量，绝不拿别的模型的向量顶替。
   - 未注入多模态空间时行为与此前逐字一致（退化为 0.5/0.5 两路融合）。

4. 派生数据落盘 + 分层参与召回
   - 媒体引用是**作者数据**（丢失即丢信息）→ 条目目录内 .media.json；
     稠密向量是**派生数据**（可重算）→ 全局 .dense.json，tmp+rename 原子。
     混存会让派生数据损坏连带作者数据一起丢。
   - 新增 SearchIn(query, category, topK)：分类前缀匹配子树，让分层真正
     参与召回（此前检索全库平铺，分层只是存储布局）。归一化取作用域内
     最大值，否则范围外的强命中会把域内分数压没。
   - 删除 SearchTree/SearchCategories 死代码（零调用方，且停留在 Search
     修复前的单路口径：无词法融合、0.05 阈值）。

顺带修掉 Add 的 O(N)/写：buildTreeLocked 逐条重算向量（s.vec 里已有）
改为一次建表复用；.index.json 改为标脏 + Flush/Stop 收口。实测单条 Add
2.1ms@50 → 13.7ms@400 压平到 ~400µs（34×）。

存量目录改名迁移落在 migrate_names.go，只报告不改名（os.Rename 不可逆），
冲突整批拒绝以免半迁移。
 2026-09-26 14:20:18 +08:00
JianFeeeee
6c33bfdb82 docs(sdk): 修正 ProxyReg 字段注释里的旧名（DeclareProxy→RegisterProxy） 
Rename 时漏改了字段注释。代码本身一致（proxyReg 字段 + RegisterProxy 方法），
但注释里写着一个不存在的 API 名，读者按注释找不到方法。
 2026-09-26 13:49:59 +08:00
JianFeeeee
a7fbdb3110 fix(webui): 旧反代两条路径合并修复 —— 302变502/泄露内网URL/流式被缓冲 
新反代（proxy.go）早已修掉这些，但**两条旧路径**没跟上，各自复制了一份
http.DefaultClient 实现：

  proxyToPluginmgr        （handler_settings.go）
  handleDeviceGatewayProxy（handler_device.go）

同一个 bug 修了两遍还漏了两处。抽成共用的 reverseToUpstream，不再分叉。

## Bug 1：跟随上游 3xx → 302 变 502 + 泄露内网 URL

http.DefaultClient 默认跟最多 10 跳。上游回 302 时反代跟过去，目标可能是
内网另一个服务或不可达，于是把「上游的 302」变成「本层的 502」，
错误里还带着内网地址：

  {"error":"device gateway unreachable: Get \"http://127.0.0.1:1/api/...\":
   dial tcp 127.0.0.1:1: connect: connection refused"}

外部用户看到 Bad Gateway + 他访问不了的内网地址：既无用又泄露拓扑。
→ 反代**不应有重定向策略**（那是客户端的事），原样透传 3xx。
→ 上游错误细节只写日志，对外统一「上游服务不可达」。

## Bug 2：不逐帧 flush，流式响应被缓冲到结束

原实现 io.Copy(w, resp.Body)，ResponseWriter 自带缓冲 → 上游按帧下发的
SSE/长轮询内容全堆到上游结束才吐。裸 TCP 实测：上游每 80ms 一帧共 3 帧，
缓冲版本只产生 **1 次**读（集中在 161ms），客户端表现为「卡住不动然后
一次性全出来」。改用 flushCopy（4KB 块 + 块间 Flush）。

## Bug 3：不过滤逐跳头

Content-Length / Transfer-Encoding 描述的是**上游那条连接**的分帧方式，
照抄到本层连接会导致客户端按错误长度读；Keep-Alive/Connection 同理。
按 RFC 7230 §6.1 剔除。

## 附带修正

- 补 X-Forwarded-For / X-Real-IP / X-Forwarded-Host / X-Forwarded-Proto，
  且**只在尚未设置时补** —— 外层 nginx 已注入时覆盖会丢掉真实客户端 IP。
- 与 proxy.go 新建了带超时的 upstreamClient（DefaultClient 无超时，
  上游卡住会拖住 goroutine）。

## 判据（5 条）+ ★ 判据设计的两个坑

★ 这条判据我试错了三轮，过程留在测试注释里：

1. 「首帧早于末帧」→ **假绿**。Go 在响应结束后把缓冲一次吐出，首末帧仍有
   微秒级差，任何 `> 0` 都绿。
2. 用 http.Client 量「首帧延迟 < 上游总时长 70%」→ 仍是**假绿**。实测直连
   上游首帧 761ns、总时长 160ms：Go 的 HTTP **客户端**合并读，量到的
   「首帧」是客户端首次取到数据的时间，与服务端何时 flush 无关。
3. 当前（正确）：**裸 TCP 直连被测服务**，看读到几次、分别在什么时刻。
   对照组实测 3 次读 / 0.24ms / 80ms / 161ms —— 正是上游节奏。
   第二个坑：不能按「累计 12 字节正文」判结束（首读含响应头 + 首帧正文，
   会在首读就以为读完，后两帧时序全丢）。改为读到 EOF。

变异验证 4 条（均按预期打红后还原）：退回 DefaultClient → 跟随重定向判红；
错误信息带 err.Error() → 泄露判红；退回 io.Copy → 只读到 1 次判红；
不过滤逐跳头 → Keep-Alive 判红。

全量：35 包全绿。
 2026-09-26 13:49:59 +08:00
JianFeeeee
3273c507b3 fix(webui): Server 读侧超时（防 Slowloris）+ 反向判据守住流式不被腰斩 
http.Server 原本**一个超时都没设**（只有 Handler）。后果是 Slowloris：
攻击者只占连接不发完整请求头，每个连接挂几 KB。MaxHeaderBytes 限的是
头部**大小**，「慢慢发」不占大小、不受它约束，几百个连接就能耗尽 fd。

## 为什么不是「把超时都设上」

webui 有一条长连接 SSE（/api/v1/chat/events）与可跑 300s 的流式
/v1/chat/completions。WriteTimeout 是「从请求开始到响应写完」的**总预算**，
会把它们腰斩 —— 表现为 SSE 每隔一段时间断一次、前端疯狂重连。而这类
回归在功能测试里很难立刻发现。

所以只设读侧三项，各管一段：

  ReadHeaderTimeout 20s —— 请求头必须按时发完，Slowloris 的正解
  ReadTimeout       60s —— 读完整请求（含 body）的预算，防慢速上传
  IdleTimeout      120s —— keep-alive 空闲连接（另两项都管不到）
  WriteTimeout        0 —— **刻意不设**（见上）

## 判据（3 条，含一条反向判据）

- TestServerHasReadSideTimeouts：三个读侧超时都必须 > 0
- TestServerHasNoWriteTimeout：**反向**钉住 WriteTimeout 必须保持 0，
  防止将来有人「顺手补全超时」把 SSE 弄坏
- TestSSEConnectionSurvivesBeyondReadTimeout：SSE 连接确实活过读侧窗口

反向判据看着琐碎，但它守的正是「这次没做的那件事」——
不加 WriteTimeout 是个**决定**，不是疏漏，所以要用判据把决定固定下来。

变异验证：补上 WriteTimeout:30s → 反向判据判红；
去掉 ReadHeaderTimeout → 前向判据判红。

测试脚手架注意：newServerForTest 绑 127.0.0.1:0（内核分配空闲端口），
绝不用 :8080 —— 那是生产端口（见 a752ae1）。

全量：35 包全绿。
 2026-09-26 13:49:59 +08:00
JianFeeeee
35df6f4366 fix(webui): 限流来源识别改为「只信任受信反代的 XFF」—— 修复把自己锁在门外 
★ 这是在生产上亲手踩出来的：上一提交加了按 IP 限流后，我用 8 次错误登录
做验证，结果**把管理员自己锁在外面 10 分钟**。

## 现场证据

  [webui] POST /api/v1/login from=127.0.0.1 auth=none status=429

webui 经 frp/nginx 穿透到公网时，**所有外部请求的 RemoteAddr 都是
127.0.0.1**。于是所有人共用一个桶：任何人爆破 5 次，就把**所有人**
（含管理员）一起锁死。限流从防护变成了 DoS。

## 我第一版还犯了个方向的错

当时我刻意**不采信** X-Forwarded-For，理由是「该头可伪造，换个头就能
绕过限流」。这个理由本身对，但结论下反了：完全不采信，在穿透部署下
**必然退化成全局限流** —— 而全局限流正是我试图避免的那个后果。

## 正确做法：中间路线

**只信任受信反代发来的 XFF**。判定「是否来自受信反代」不能靠
内网/回环 IP 猜 —— 穿透部署下反代恰恰就在本机 127.0.0.1，与直连请求
完全同源，猜不出来。所以由部署方**显式声明**（新设置项
`webui.trusted_proxies`，逗号分隔 CIDR 或裸 IP）。

权衡写明：未声明时穿透明场景下限流退化为「全局」。这是**刻意的保守
默认** —— 宁可限流偏保守，也不能因为采信伪造头而形同虚设。

## 判据（+4）

- TestLoginRateLimitUsesForwardedForFromTrustedProxy：受信反代下按真实
  客户端 IP 隔离（否则就是全局锁）
- TestLoginRateLimitIgnoresUntrustedForwardedFor：换 XFF 头不得绕过限流
- TestLoginRateLimitNeedsExplicitTrustedProxyConfig：未配置 = 不采信
- TestParseTrustedProxies：合法项接受、非法项丢弃、空 = nil

全量：35 包全绿。

★ 附带教训（也记在判据注释里）：**用失败注入做验证时要意识到副作用
范围**。我那次「跑 8 次错误密码看看会不会限流」本身是合理的验证动作，
但它作用在**生产实例**上，且限流的作用域（全局化）正好覆盖了自己。
在带状态的安全机制上做破坏性验证，判据应该先证明作用域是对的。
 2026-09-26 13:49:59 +08:00
JianFeeeee
667b9fdc8a fix(webui): OpenAI 兼容面 —— 补 /v1/models + 真流式（原先是假流式） 
/v1/* 是**给外部程序用的**（IDE、脚本、agent 框架），不是给人看的聊天页。
它的行为必须真符合 OpenAI 协议，否则调用方直接坏掉。下面两条都在
**生产实测**中确认过，不是推理。

## ① GET /v1/models → 404

几乎每个 OpenAI 客户端（curl 脚本、LangChain、OpenAI SDK、IDE 插件）
启动时都会先列模型来探测服务可用性。404 让它们直接判定「服务不可用」，
连试都不试 —— 这是集成方最容易踩空、也最难自查的缺口（表现为
「连不上」，而实际端点是通的）。

新增 handleOpenAIModels。返回什么模型**不重要**，结构合法才重要：
本端点不做模型选择（model 只是回显），所以只暴露 HomeAgent 自身。
不谎报 GPT 之类名字 —— 那会让用户以为能选模型，实际不能。

## ② stream=true 是假流式

实测：首字节 7.79s，随后**整段**内容在一个 chunk 里到达。

根因：两条路径都走 InjectTextSyncNoMemory —— **同步等完整回复**才返回，
之后才把已拼好的全文切成 3 个 chunk 吐出去。客户端的「生成中」/取消/
超时/进度条全部失效；300s 超时表现为「卡 5 分钟然后一次性出现」。

重写为真流式：先订阅 EventContentDelta / EventReasoningDelta **再**启动
注入（顺序反了会漏开头几个分片），边收边转成 chunk，最后用同步调用拿到的
完整回复补 usage、发 finish、[DONE]。沿用 handleSSE 的成熟结构
（批量 16ms 合并、独立 writer goroutine、done channel 而非 close）。

顺带处理内核的 reset 事件：流式失败回退非流式时内核会发
content="" + reset=true（见 internal/agent/core/process.go）。忽略它会让
客户端看到半截内容后又接上完整内容（重复且自相矛盾），故识别并丢弃累积。

## 判据（4 条，变异验证）

- TestOpenAIModelsEndpoint / RequiresAuth
- TestOpenAIStreamIsActuallyStreaming
- TestOpenAINonStreamUnchanged（别把非流式改坏）

★ **判据本身踩了两个坑，都已修正并记在测试注释里**：

1. `httptest.ResponseRecorder` 把整个响应**缓冲在内存里**，请求结束才交付
   —— 它**根本观察不到流式**。用它写的流式判据必然是假的。故改用
   `httptest.NewServer` + `bufio.Reader` 逐帧读。

2. 「要求首帧早于末帧」**抓不住**假流式：假流式确实是分多次 write 的，
   帧间间隔是微秒级 > 0，任何 `> 0` 判据都绿（已实测）。
   真正能区分的是：**首帧是否早于「内核产出最终答案」那一刻**。
   于是假内核被构造成：发 3 个增量后**扣住**最终响应，直到消费者
   表现出「已在读帧」才放行 —— 真流式首帧 0.35s，假流式首帧 3.30s。

3. 鉴权判据一度写错：未登录时门户 302 到 /login，若跟随重定向就会拿到
   登录页的 200，把「被重定向」误判成「鉴权通过」。改用不跟随重定向的
   客户端。

变异验证：去掉 /v1/models 路由 → 判红（还原 404）；
不转发增量 → 判红（首帧 3.30s）。

全量：35 包全绿。
 2026-09-26 13:49:59 +08:00
JianFeeeee
5ebc4481b0 fix(webui): 登录入口加固 —— 限流 + 常量时间比对 + 请求体限量 + 防用户名枚举 
门户可经 frp 穿透到公网（https://homeagent.jianfgit.xyz/ 实测直达），
而 handleLogin 原先是**零防护**：无限流、无失败计数、口令用 == 明文比对、
失败不审计。等于把唯一��口令入口直接开到外网任人爆破。

## 改动

1. **按来源 IP 的失败计数限流**（login_limiter.go）
   - 5 次失败后拦，10 分钟窗口。
   - 退避而非永久封禁：窗口过期自动恢复。永久封禁意味着一旦误撞
     （或被撞库）就再也登不进，只能上机器改配置。
   - 成功即清零：手滑输错几次不该被永久记账。
   - **刻意不采信 X-Forwarded-For** —— 该头可伪造，直接采信等于让
     攻击者换一个头就能绕过限流，甚至把限流当成打别人来源的武器。
     代价（已在注释写明）：若 webui 挂在反代后，限流会退化成「全局」，
     那种部署应在反代层限流或用 PROXY protocol 传真实来源。
   - **刻意不做账号级锁定**：本系统只有一个管理员账号，账号级锁定
     相比 IP 级无额外收益，却多一个误伤面。
   - 过期记录会被 prune —— 否则攻击者轮换 IP 就能喂成内存泄漏。

2. **常量时间比对**（crypto/subtle）：`==` 会在第一个不同字节处短路，
   泄漏「猜对了几位」的时序信息。

3. **请求体限量**：ContentLength 前置拒绝 + MaxBytesReader 兜底。
   ★ 后者**不能只靠解码器报错** —— json.Decoder 按需读流，遇到
   「超大 + 非法 JSON」会在第 0 字节就报语法错误、永远读不到上限，
   于是 8MB 数据已进缓冲而 MaxBytesError 从未出现。只挂 MaxBytesReader
   的写法对最省力的攻击载荷反而无效（实测确认）。

4. **防用户名枚举**：用户不存在与口令错误给完全相同的状态码与报文。

## 判据（8 条）

限流触发 / 按来源隔离（否则一个 IP 就能把所有人锁死，限流即 DoS）/
成功清零 / Retry-After / 请求体限量 / 防枚举 / 过期清理 / 重试时长非零。

变异验证（3 条打红后还原）：
- 去掉限流调用 → 3 条判红
- 去掉 ContentLength 前置检查 → 判红（回到 400）
- 去掉 Reset → **起初没打红**：原判据「跑 30 次看是否限流」在阈值只有 5
  时无论有没有 Reset 都会限流，是条**假判据**。已改为**测出实际阈值**
  （清零后应重新拿到完整额度），再去变异即打红。

诚实说明：常量时间比对那条**无法用单测可靠断言**（时序属性，噪声远大于
信号）。它由代码评审保证，不由测试保证 —— 写明以免后人以为有测试兜着。
 2026-09-26 13:49:59 +08:00
JianFeeeee
6d0c1188f6 fix(webui): 服务入口「打开」改用路径形态 + 别名模式不补尾斜杠 
验收时发现的**用户可见缺口**：API 早就同时返回 url（子域）与 url_portal
（路径），但「服务入口」卡片只用了 url —— 而子域形态在穿透部署下
**恰恰是打不开的那个**（外层只放行一个 Host、三级子域通配证书不匹配）。
用户点「打开」得到坏链接，还会以为是插件的问题。

## 改动

1. 卡片「打开」优先 url_portal（路径形态）：
   无 DNS 依赖，单端口穿透 / 子域无证书时都能用。
   子域链接保留为次选按钮（局域网内直连时更直观）。
   文案补一句说明两者差别（子域需 DNS 能解析 `*.<基域名>`）。

2. **别名模式不再补尾斜杠**（顺带发现的 bug）：
   原实现给所有 url_portal 无条件加 `/`。前缀模式下对（那是规范形态，
   前端靠它算相对路径基准）；别名模式下错 —— 那里的 path 是上游真实
   路径语义（/api/v1/device 是 /api/v1/device/xxx 的前缀），补成
   /api/v1/device/ 会让人误以为存在一个可访问的根。

## 判据

+2 条：TestProxyServicesOffersBothForms（两种形态都必须给出，
且前缀模式的 url_portal 必须带尾斜杠）、
TestProxyServicesAliasKeepsExactPath（别名模式不得带尾斜杠）。

变异验证（2 条，均按预期打红后还原回绿）：
- 别名模式也加尾斜杠 → 判红
- 前缀模式不加尾斜杠 → 判红

另修正一条旧判据的期望值：它当年断言的是「所有 url_portal 都带尾斜杠」
（即把 bug 当成契约钉住了）。那条路由正是设备网关（别名模式），
现在改为断言不补尾斜杠，并注明理由。

全量：35 包全绿。
 2026-09-26 13:49:59 +08:00
JianFeeeee
125bf57cfa fix(test): 测试不再抢生产端口 :8080（internal/plugins 加载内置 webui 所致） 
部署过程中反复出现「8080 被 plugins.test 占用」导致生产 WebUI 起不来。
追到底：internal/plugins 的集成测试会 pluginReg.Load(全部内置插件)，
其中 webui 默认监听 :8080 —— **正是生产实例的端口**。

## 为什么这个 bug 特别难查

它不是测试失败，而是**测试与生产静默抢端口**：先到者胜，另一个 bind 失败。

  - 跑测试的人看到「测试随机失败」（其实是生产先占了）
  - 用生产的人看到「WebUI 随机死掉」（其实是测试先占了）
  - 两边现象互不相干，且各自单独重跑往往都过

叠加 webui 已有的「bind 失败必须显式报错」修复后，症状从「静默死亡」
变成「随机报错」，这反而让归属更容易看错 —— 我一开始也是先怀疑自己的
部署脚本，直到采样 /proc/<pid>/cwd 才确认是测试进程。

## 修法

集成测试在 Load 之前用既有的 SetListenOverride 把地址指到
127.0.0.1:0（内核分配空闲端口），并在 cleanup 还原。
测试因此拿到真实可用的 HTTP 服务，且与任何固定端口实例完全隔离。

- webui 新增 ListenOverride() 读取当前值，供调用方保存/还原
  （只有 setter 时无法在不破坏调用方状态的前提下做临时覆盖）。

## 验证

- 修复前：跑 ./internal/plugins/ 期间 8080 持续归 plugins.test（109/200 采样）
- 修复后：35 次采样全程 8080 归 homed，测试同时全绿
- 变异验证：移除 override 后立刻复现抢端口，判据有效

另记两个测试卫生问题（同一根源，已顺手清理泄漏进程）：
测试会启动**真实插件进程**（/home/newqqagent/plugins/*/plugin.bin）。
kill 测试进程后这些子进程会残留。已全部清理，生产 23 插件恢复正常。
 2026-09-26 13:49:59 +08:00
JianFeeeee
2c810bbbce feat(webui): 路径挂载的 strip_path 两态 + 尾斜杠重定向（修 /p/huawei 打不开数据） 
用户要求用方案 A（路径挂载）让 huawei 插件 UI 在外部可用，
并把「通过反代的插件必须使用单一入口」写入 SDK 声明。

## 实测暴露的两个真问题

1. **Path 的语义不能一刀切**。原设计「原样保留」只对**机器接口**成立
   （设备客户端硬编码 /api/v1/device/ws，不可能知道反代的存在）；
   而自带 UI 的服务需要**剥掉前缀**（/p/huawei/api/status → 上游 /api/status）。
   猜错的结果是全部请求 404，且看起来像上游故障 —— 所以由声明者选：
   strip_path=false 别名模式 / true 前缀模式。非法组合被 validate 挡住。

2. **前缀模式的尾斜杠是必需的**（自测发现的 bug）。
   访问 /p/huawei（无尾斜杠）时页面能开，但页面里所有 fetch 都 404 ——
   相对路径以「当前文档目录」为基准，没尾斜杠时浏览器把最后一段当文件名，
   目录退回上一级，fetch('api/status') 打到 /p/api/status。
   修：前缀模式且路径恰等于前缀时 301 到 /p/huawei/（保留查询串）。
   **别名模式不做此事** —— 那类路径是上游真实语义，加斜杠会改坏它。

## 插件侧（huawei_smarthome）

- 前端 4 处根绝对路径（fetch('/api/status') 等）改为相对路径，
  基准由 location.pathname 推导（BASE）。这是 Path 形态能成立的**前提** ——
  否则请求会打到门户自己身上。
- plg.json 声明：host + path=/p/huawei + strip_path=true + auth=homeagent。
- SDK 升到 1.4.0，并用 hmapdev 1.4.0 重新打包（1.3.0 的 hmapdev 无
  proxies 支持，会把声明**静默丢弃** —— 实测确认过，这是打包链路上
  一个不报警的坑，值得记住）。

## 判据

+6 条：TestProxyPathAliasVsStrip（两态各自正确）、
TestProxyPathLongestPrefixWins（/p/app 不得劫持 /p/apple，
且长前缀胜出）、TestProxyStripPathRedirectsToTrailingSlash（尾斜杠，
含查询串保留 + 别名模式不得重定向）。

变异验证（4 条，均按预期打红后还原回绿）：
- 删尾斜杠重定向 → 判红（还原了真实 bug 形态）
- 让别名模式也重定向 → 判红（设备网关语义被毁）
- 从 hmapdev schema 探测体删 StripPath → 判红（漂移检测有效）
- 删 SDK 里的「单一入口原则」字样 → 判红（契约不能只剩口头约定）

全量：35 包全绿。
 2026-09-26 13:49:59 +08:00
JianFeeeee
5da0f8f9fb feat(webui): 外部入口 base_url 配置 —— 穿透场景下链接不再靠猜 
用户指出 webui 实际是经 https://homeagent.jianfgit.xyz/ 穿透出去的，
应当支持配置 base URL。实测确认了这个诉求的正当性。

## 实测发现的约束（决定方案）

1. **子域形态在外部不可用**：`*.homeagent.jianfgit.xyz` 泛解析存在，
   但外层只给 `*.jianfgit.xyz` 通配证书 —— 该证书**不匹配三级子域**，
   实测 `huawei-smarthome.homeagent.jianfgit.xyz` 外部握手失败（HTTP 000）。
   外层只放行 `homeagent.jianfgit.xyz` 这一个 Host。
2. **路径挂载形态外部可用**：实测
   `https://homeagent.jianfgit.xyz/api/v1/device/online` → 200。
   所以「一个外部 Host + 路径挂载」是这条链路的正解，且已经工作。
3. 外层 nginx/WAF 会带 `X-Forwarded-Proto: https` 与 `X-Forwarded-Host`，
   因此即使不配置也能推出正确链接；配 base_url 则是显式兜底。

## 新增设置项 base_url

三级优先解析「对外入口」（resolveEntry）：

  1. **配置项 base_url** —— 外部入口是部署事实，不该靠请求猜。
     经多层网关时请求可能带内网 Host，按它推导会拼出用户点不开的链接。
  2. **X-Forwarded-Proto / X-Forwarded-Host** —— 反代层给权威信息时可靠。
  3. **请求自身** —— 直连时的正确来源。

base_url 的主机名同时用作**子域反代的基域名**：入口是 homeagent.example.com
时，插件服务自然是 <标签>.homeagent.example.com。

服务清单另增 entry_url 字段，直接给出「外部入口是什么」，便于前端与排错。

## 生效点

- `/api/v1/proxy/services`：url / url_portal / base_domain / entry_url
- `/api/v1/device/gateway`：url / url_portal / http_url / host
- 两处原先各自推导 portalHost，现统一走 resolveEntry，避免再次漂移

## 部署后实测（生产，经真实外部入口）

  entry_url:   https://homeagent.jianfgit.xyz
  base_domain: homeagent.jianfgit.xyz
  remotedevice    | https://devices.homeagent.jianfgit.xyz
                  | https://homeagent.jianfgit.xyz/api/v1/device/   ← 外部可点
  huawei_smarthome| https://huawei-smarthome.homeagent.jianfgit.xyz

发现端点（外部视角）：
  url_portal = wss://homeagent.jianfgit.xyz/api/v1/device/ws   ← 外部可连

## 判据

+3 条：TestBaseURLOverridesRequestDerived（内网 Host 场景下必须用 base_url）、
TestEntryPrefersForwardedHeaders（XFF 优先于请求自身）、
TestBaseURLTolerant（尾斜杠/空格容错 —— 手填配置最常见的两种手误）。

另更新一条旧判据的期望值：外部入口是 portal.example.com 时，子域基名应取
**实际入口**而非本机配置的 localhost（后者对远程用户无意义）。
 2026-09-26 13:49:59 +08:00
JianFeeeee
a96ad9ca97 fix(webui): 服务入口 URL 端口必须恰好出现一次（生产部署后暴露） 
生产部署后立刻暴露的真 bug：请求 Host 自带端口（实测 Host=127.0.0.1:8080），
而 url_portal 合成时无条件再追加监听端口，拼出
  http://127.0.0.1:8080:8080/api/v1/device/     ← 链接点不开

单测抓不到的原因：此前测试用的 Host 不含端口。真实服务器上 Host 一定带端口
（除非经 nginx 剥掉），所以这个 bug 必然出现在生产。

修法：抽出 portalHostWithPort(host, hostPort) 统一合成 ——
  - host 已含端口 → 原样（尊重调用方看到的真实入口）
  - host 不含端口 → 追加监听端口
两处调用点（服务清单 url_portal、发现端点 url_portal/url/http_url）共用它。

新增 3 条判据，都刻意用**自带端口**的 Host：
  TestPortalHostPortExactlyOnce（7 组输入，含带/不带端口、空值、无冒号端口）
  TestProxyServiceURLsWithPortInHost
  TestDeviceGatewayDiscoveryNoDuplicatePort
 2026-09-26 13:49:59 +08:00
JianFeeeee
a781f8e1ba fix(gui): 设备桥 bind 结果判 ok + 暴露登记状态，与鸿蒙端对齐 
GUI 主进程与 Go 客户端同病： 只打日志、不看 ok。
服务端 bind 被拒时回 {"ok":false,"error":"bind rejected"} 并关闭连接，
GUI 既不报错也不重连 ⇒ 设备静默失联（TCP/WS 通但从未登记进网关）。

另：成功时服务端不含 device 字段，原日志用 `msg.device || deviceBridgeId`
兜底才显得像成功，掩盖了「从未真的读 ok」。

鸿蒙端 DeviceBridge.ets:209 本来就是正确实现（检查 ok、区分 connected
与 bound），本次把 GUI 与 Go 客户端对齐到同一语义：
新增 deviceBridgeBound / deviceBridgeBindError，bind 被拒打 error 级日志
并说明常见原因（令牌不匹配 / 设备未授权）。
 2026-09-26 13:49:59 +08:00
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
5d278cffdb fix(webui): 反代两处真实故障 —— 凭证头按 auth 区分 + Host 分发先于门户路由 
两处都是**隔离实例上跑真实端到端**才暴露的，单测（用不校验凭证的假上游、
直接调 serveProxyHost）全绿却线上出错。记录在此以免重蹈。

## 故障 1：auth=none 路由的凭证被无条件剥掉 ⇒ 设备链路全 401

Rewrite 里原本无条件 Del("Cookie"/"Authorization"/"X-API-Key")。但
auth=none 的语义是"请求原样交给上游"，凭证本来就是给**上游**的——
remotedevice 的接入令牌正是走 X-API-Key 传的。

实测症状：带设备令牌经反代访问 /api/v1/device/online → 401；
直连 127.0.0.1:9890 → 200。差异极难定位，因为两侧状态码语义相同。

修法：按路由 auth 分流。
- auth=homeagent：凭证是门户的，剥掉（避免泄漏给插件）
- auth=none：保留（上游要用）

复验：经反代与直连**逐字节一致**（HTTP 200 / 17B，cmp 相同）。

## 故障 2：插件子域被门户路由截走 ⇒ 401 且响应体是门户的 JSON

原实现把 Host 分发放在 mux 的 "/" 兜底里。但 stdlib ServeMux 是**最长前缀
优先**：任何更具体的模式都先命中。插件子域上的 /api/v1/device/online 被门户
为「旧路径反代」注册的 /api/v1/device/ 接走（requireAPI 包裹）→ 401。

判据（响应体格式）是定位关键：
  webui requireAPI        → {"error":"unauthorized"} 25B  ← 实际拿到
  remotedevice requireToken → "unauthorized" text/plain 13B
看响应体格式就能区分是谁拒的，比看状态码有效。

修法：Host 分发提为**最外层中间件**，包在整个 mux 之外，先于任何路径匹配。

## 顺带：消除判据与生产接线错位的可能

新增 Handler.Handler() 返回生产用的完整链（Host 分发 → 日志 → mux），
plugin.go 与测试共用同一条。本次踩过：测试自己组装 mux、中间件却挂在
plugin.go，判据全绿而线上 401；共享同一条链可结构性避免。
（写这条判据时还发现测试里 h.mux 为 nil 导致 panic——也正是这种错位的表现。）

## 新增判据 2 条

- TestProxyCredentialHeadersDependOnAuth：auth=none 必须转发上游令牌、
  auth=homeagent 必须剥掉门户凭证（两个方向都钉）
- TestProxyHostTakesPrecedenceOverPortalRoutes：走**完整生产链**，确认
  插件子域上的 /api/v1/device/online、/api/v1/status、/api/v1/plugins/ 都
  归反代；同时确认门户自身的 /api/v1/status 仍返回门户 JSON（没被反代吞掉）

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

- 设备网关：令牌经反代 200，与直连逐字节一致；WS 升级 101
- 未声明子域：404 且错误信息含具体标签
- huawei_smarthome（用新 hmapdev 重打包、真装载）：
  匿名 401 + 可操作提示；带门户 key 拿到真实 UI（9444B，
  <title>华为智慧生活管家）；页面内根绝对路径 /api/status 正确透传
 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
4e40597954 merge: 内核编解码层 C 化 + C 基础设施门禁（feature/c-core） 
## 内容
- C 化第一刀 L1 纯函数层（ha_codec）：token 估算/截断/上下文窗口推断
- 零分配 JSON 扫描层 ha_json_scan（scan/extract 两段分离，黄金对照 + fuzz）
- SSE 协议导航层 ha_sse（**默认关闭**，见下）
- C 基础设施门禁六项（make check-csrc / check-csrc-full，已接进 make test）
- 共享内存与 IPC 的成本地板基准（纯测量）
- 分词器热路径分配优化（差分 oracle 验收）

## 实测（main 同机对照，50000 次迭代）
| 场景 | main | 本次 | 提升 |
|---|---|---|---|
| Truncate zh_1k | 6570ns / 2 allocs | 174ns / 0 | 37.8× |
| Truncate long_zh | 5984ns / 2 allocs | 179ns / 0 | 33.5× |
| Truncate ascii_1k | 1580ns / 2 allocs | 95ns / 0 | 16.6× |
| Estimate ascii_1k | 445ns | 51ns | 8.7× |
| Estimate zh_1k | 2262ns | 1172ns | 1.93× |
| Estimate short_zh | 22ns | 35ns | -58%（cgo 边界固定成本） |

几何平均 4.20× / 中位 1.93×；**变快 7 项、变慢 2 项**（短串受 cgo 边界拖累，
如实记录未掩盖）。调用点在热路径：process.go 对每个上下文事件都调
EstimateTokens，tooldefs.go 的工具定义裁剪调 TruncateByTokens。

## 默认关闭的部分（实测更慢，不当作成果）
- chunkFastEnabled = false：SSE 分块快速路径。首版更慢 52~79%；
  返工（5+ 次 cgo 边界压成 1 次）后为「三项赢、一项输」，toolcall 仍慢 15%
  ⇒ 不打开。TestChunkFast_BenchGate 断言该开关必须为 false。
- ha_json_scan 未接生产路径：库已验完（119 契约断言 + 黄金对照 5 组 +
  4948 万次 fuzz 零崩溃 + 6 万+ 差分用例），作为可复用底座留存。

## 为什么共享内存没有 C 化（附成本分解基准）
编解码占端到端 34%，但 **C 的甜区（字节搬运）仅占 0.2%~2%**
（1KB 拷贝 18ns、16KB 210ns；Go copy 已 44~71 GB/s），大头是 JSON 反射 34%。
另：段内读是**不可信偏移**（offset 由插件转述，伪造会破坏块链），
保留 Go 边界检查 / panic / -race / 模糊测试覆盖比省 0.2% 更值。
IPC 的真正地板是 OS 调度：cat 管道 echo 就要 16µs，占最简 RPC 的 62%。

## 验证
- 全量 go test -count=1 ./... 38 包 0 FAIL
- C 六门禁全过：gcc+clang 零告警（-Wconversion 必备）、ASan+UBSan、
  arm64 交叉编译、头文件自包含、libFuzzer 零崩溃、ABI 版本自述
- 端到端启动实测：14 插件 / 63 工具 / kernel ready / 0 panic
- make build-linux-arm64 → ELF aarch64
- SDK 公开接口 diff = 0 行（csrc/ 是内核 C ABI，不属 SDK 冻结范围）
- git-release-discipline 体检 FAIL=0

## 纪律
- meta.Version 未被污染（未动 internal/meta）
- main 上无 merge 来自 release 分支（仅本 feature 合入）
- 本分支未部署任何生产环境
 2026-09-26 13:32:36 +08:00
JianFeeeee
241f5fac04 fix(knowledge): 拒绝越出知识根的知识名（可致整个数据目录被删） 
sanitize 只做小写/去空格/换下划线，**不过滤 ".."**，而 Remove 直接把
sanitize 的结果 filepath.Join 到知识根后 os.RemoveAll。

后果（实测）：
- Remove("..") → RemoveAll(<data>)，把整个数据目录连同 memory/
  documents/media 一起删掉；且 os.RemoveAll 对已不存在的目标返回 nil，
  调用方（含 knowledge_delete 工具）会回报"已删除"。
- Remove("../..") → RemoveAll(<data 的父目录>)。
- Add("../../x") → 内容写到知识根之外；重启后 scanAll 扫不到该目录，
  条目既不在盘上正确位置也无法重建 ⇒ 幽灵条目（内存有、索引有、盘上没有）。
- Add(".hidden") → 写到隐藏目录，scanDir 明确跳过隐藏目录 ⇒ 同样的幽灵。

修复：
- 新增 checkSafeName：拒绝空段、"."、".."，以及以点开头的段。
  Add 与 Remove 在拼接路径前都过它。
- 双保险：拼接后用 filepath.Clean 复核结果仍在知识根内，
  防止 checkSafeName 将来被改宽而重新引入越界。

反向验证：临时拆掉这两处防护后重跑新测试，Add/Remove 对 .. 与隐藏名
全部"成功"，测试稳定变红；恢复后全绿。

影响范围：该缺陷存在于 release/v1.0.x ~ v1.3.x 四条发布线（各自的
internal/knowledge/knowledge.go 的 Remove 均为同一写法），本次修复需按
hotfix 纪律 cherry-pick 回流 main 并前向传播。
 2026-09-26 13:11:08 +08:00
JianFeeeee
a006237105 test(proc): 建立进程间通信的成本地板（判定「优化 IPC」的空间） 
目标：回答「工具调用往返 30µs 里，非编解码的 ~20µs 花在哪、能否优化」。
方法：先立地板 —— 任何跨进程方案都有 OS 调度决定的下界。

三层对照（同机同会话，3000 次迭代）：

| 层 | ns/op | allocs |
|---|---:|---:|
| ① OS 调度地板（cat 子进程管道 echo，无协议无 JSON） | **16071** | 0 |
| ② 最简 RPC（无载荷、不经共享帧） | **25840** | 20 |
| ③ 纯编解码（共享段 write+read+compact，纯内存） | 10200 | 84 |

## 两条判据
1. **① 已占 ② 的 62%**：一个什么都不做的  echo（两次进程唤醒 +
   两次管道读写）就要 16µs。⇒ RPC 层的成本主要是 **OS 调度**，
   不是协议解析或 JSON 序列化。
2. **②−① 只剩约 10µs**：这才是协议层（JSON 帧 + pending map +
   channel 握手）可优化的全部空间，且其中还包含一次真实的 JSON
   编解码往返。⇒ 「优化 IPC」的理论上限约为端到端 30µs 的三分之一。

## 结论
跨进程数据面的**协议侧已接近其地板**。若要把端到端再压下去，
方向不是「优化协议」，而是**改变通信形态本身**：
  · 批量调用（一次往返做多件事，摊薄固定调度成本）
  · 或对高频小调用改走共享内存 + 自旋/事件通知（绕过两次进程唤醒）
两者都是架构级改动，不是参数调优。

★ 这也解释了此前几轮的困惑：为什么 C 化数据面收益总是很小 ——
  因为真正的大头（OS 调度 16µs）与语言无关。

验证：基准可复现；internal/plugin/proc 全量测试绿。
 2026-09-26 13:06:10 +08:00
JianFeeeee
84d2d7c313 perf(chineseclip): 分词器热路径分配优化 + 差分 oracle 验收（含一处真实语义修复） 
嵌入式模型推理（ONNX）本身已是 C++，**可优化的 Go 侧是分词器与预处理**。
本轮先测出成本分布，再改，且**不假设 C 更快**。

## 实测（合成词表，无需 CHINESECLIP_MODEL_DIR）
| 场景 | ns/op | allocs |
|---|---:|---:|
| short_zh | 25681 | 60 |
| short_en | 19100 | 43 |
| mid_en | 117343 | 451 |
| mid_zh | 189260 | 1047 |
| punct_heavy | 283265 | 1388 |
| long_zh | 757746 | 4233 |

## pprof 指出的分配源（alloc_objects，mid_zh）
- splitOnPunctuation **33.5%**（每 token 都做 []rune + string(cur)）
- wordpiece **32.3%**（内层每轮候选都 string(runes[a:b])，多数未命中）
- stripAccents/NFD 33.6% cum
- basicTokenize 自身只 1.4%

## 改了三处
1. `basicTokenize`：`len([]rune(token))` → `utf8.RuneCountInString`
   （原为「数个长度」就把整个 token 转 rune 切片）
2. `splitOnPunctuation`：去掉整串 []rune，改逐 rune 扫描 + 一次 flush
3. `wordpiece`：预建 rune 边界表，按字节区间取 substring，
   消除「每轮候选都构造 string」

## ★★ 差分 oracle 抓到一处**真实语义缺陷**（非测量噪声）
本机无模型产物，权威的 TestTokenizerMatchesOfficialReference 会 **SKIP**
⇒ 仅靠现有测试，我的重写**没有被有效验证**。故把改动前的实现原样内联为
oracle 做差分（split/wordpiece/basicTokenize/Encode 四组 + 随机字节 2 万组
+ 随机 rune 5000 组）。

它立刻抓到：`"\xbc\xef=..."` 旧实现得 `["��" ...]`，新实现得 `["\xbc\xef" ...]`。
根因是 `[]rune(s)` 会把**非法字节归一成 U+FFFD**，而纯字节切片原样保留坏字节。
⇒ 真实差异（会进日志/去重/hash），已改为对非法序列写回 RuneError，与旧行为逐值一致。

## 诚实的收益结论：**基本没有**
改动后：mid_zh 189260（改前 186777）、long_zh 757746（改前 786416）、
mid_en 117343（改前 120422）。分配数 mid_en -40%、其余基本持平，
**时间无实质改善**（部分场景还略慢）。

复查原因（不掩盖）：重新做 CPU profile 后发现 **~25% 的样本是
runtime 锁/抢占**（unlock2 8.1% + lock2 6.8% + procyieldAsm 6.8% +
asyncPreempt 5.4%），而 utf8/unicode 相关不足 20%。
且 GOMAXPROCS 敏感：1→375365ns、4→209922ns、12→189543ns
⇒ **大量时间花在调度与 GC 而非分词算术**。

⇒ 结论：Go 侧微优化这条路**已到头**。真正的杠杆在别处：
① 提高 GOMAXPROCS/减少 GC 压力 ② 批量分词（降低每条输入的固定开销）
③ 减少送入模型的 token 量。三者都不是 C 能解决的。

改动本身保留（正确性等价、有 oracle 守护），但**不应据此宣称性能收益**。
与 C 化那几刀同一条纪律：没有数据支撑的优化不算优化。

验证：差分 oracle 6 组全过（含非法 UTF-8）；providers/... 全绿。
 2026-09-26 11:44:49 +08:00