jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-11-05 16:57:32 +00:00
Code Issues Packages Projects Releases Wiki Activity
1,081 Commits 5 Branches 29 Tags
217e32b4945bf94ff05a7d901ccfefdffdb95e50
Commit Graph

81 Commits

Author SHA1 Message Date
JianFeeeee
87f874e06f refactor(webui): 7 个黑箱判据迁到 test/ + 导出前端资源入口 
## 迁移了什么

    chat_ack_timeout_test.go       → test/
    chat_attachment_img_test.go    → test/
    cmd_history_render_test.go     → test/
    config_namespace_test.go       → test/
    dashboard_tabs_deps_test.go    → test/
    plugin_status_render_test.go   → test/
    starmap_perf_test.go           → test/

包名 `webui` → `test`。`webui/` 目录少 7 个测试文件。

## 为什么是这 7 个（分类依据）

先按「对未导出符号的依赖数」把 29 个测试文件测了一遍，这 7 个是
**0 依赖**（既不用 handleXxx，也不用 testSDK/newTestHandler 等测试辅助）。
其余 22 个按强度递增留在包内，后续逐步处理。

## 新增两个导出入口

### webui.FrontendAsset(name)

返回打包进二进制的前端资源原文（dashboard.js / dashboard.css /
mascot.webp / logo.svg …）。

判据要检查「实际会被发出去的那份文本」：dashboard.js 在严格模式下
会不会抛 ReferenceError（用 node 真跑）、mascot.webp 的魔数是否合法、
HTML 属性里有没有残留转义引号。

这些无法通过 HTTP 端点可靠断言（要登录态、且拿到的是拼接后整页，
定位不到单个 asset）。而留在包内测就得读 `dashboardFS` 这个**未导出变量**
—— 那正是"测试耦合实现"。导出后，判据变成「输入 asset 名 → 输出字节」，
与资源存在哪个变量、怎么 embed 无关。

### webui.DashboardPage()

返回组装完成的整页 HTML（外壳 + 内联 CSS/JS）—— 浏览器实际收到的那份。
与 FrontendAsset 的分工：那个取单个源资产，这个取成品。

## 顺带修掉迁移暴露的两个隐患

① 三个判据原本 `os.ReadFile("dashboard.js")` 读**磁盘相对路径**。
   在包内恰好能跑（工作目录就是包目录），但那读的是**工作区文件**，
   不是**二进制里实际嵌入的那份** —— 两者在生产上可能不同
   （比如打包后 dashboard.js 被替换）。统一改走 FrontendAsset。

② starmap_perf_test 的相对路径 `../../../shared/starmap/layout.js`
   与 `static/starmap-layout-worker.js` 在移入子目录后失效，已修正为
   `../../../../shared/...` 与 `../static/...`。

## 判据仍有效（变异验证）

把 dashboard.js 里 ack 超时 `}, 600000);` 改成 `}, 30000);`：

    --- FAIL: TestChatAckTimeoutIsGenerous
        ★ 受理超时只有 30000 ms —— 太小。
          超时太短会让前端 abort，而 agent 仍在正常干活

恢复后全绿。迁移不是搬完就废。

## 验证

    go build ./...            PASS
    go vet ./...              PASS
    gofmt -l                  干净
    go test ./... -count=1    63 包全过，0 FAIL
                             （webui/test 是新包，故 62 → 63）
    干净检出（worktree）       build + webui/... 全绿

## 后续

    webui 剩余 22 个文件（依赖 handleXxx / testSDK 等），按强度递增处理
    agent/core 739 处白盒引用，先分类再动
    CI 补 coverage + staticcheck
 2026-11-04 18:17:31 +08:00
JianFeeeee
55fa2685ae feat(security,device): security 成为独立内核模块（闸门+策略+限式），device 接管内置工具路由 
security（新模块 internal/kernelmod/security）
- 凭据闸门：出向拦截成 @{别名}、入向清洗、执行前回填（internal/security/{gate,runtime}.go）
- 工具黑白名单 + 沙箱（读写根、网络、.. 逃逸）：internal/security/policy.go
- 敏感词过滤 + 提示词注入预警（Finding 不带原文）：internal/security/content.go
- 按主体授权（hard-private 对非内部主体永久拒绝）：internal/security/principal.go
- 插件命名限式（可选档位，插件声明/内核执行，只能收窄）：internal/security/profile.go
- 启动装配从 cmd/homed 迁入模块；启动顺序判据改盯真实装配点

device（新模块）
- 正式内核模块，Provides FacDevice，KernelState.Device
- 内置工具路由表下沉到 internal/toolroute（避免 core↔kernelboot 环），
  device 保留对外入口；agent 未挂载时退化本地 switch
- Agent 侧只留 api.ToolHost/DeviceSurface 适配层

SDK
- InjectOptions.SecurityProfile：插件按 inputch 声明本轮安全档位（可选）
- InjectOptions.TurnHint：插件注入**本轮事实**，内核以独立 system 消息注入，
  不混进用户正文（人设负责怎么说话，TurnHint 只放这一轮成立的事实）
- FacilitySecurity / FacilityDevice

提示词
- 内核自带 prompt/skill/工具返回全面英文化（中文提示会让模型行为漂移）
- 机制解释下沉到 4 个内置 skill（memory/output/tool-order/plugins），
  skill 描述压到 80 runes 内（原来 94–108 全被索引截断）
- 默认人格模板英文化；[Voice] 段删除，规则并入 persona 块（单一段落）
- 历史记忆工具改名 coldcontext_query/commit，图记忆语义改称 stable memory

修复
- tracker: exec mount → unix.Mount（降权运行 + AmbientCapabilities 下才能挂）、
  区分 EPERM 与不支持；启动日志说明后果与恢复方式
- healthcheck_kernel 输出瘦身：status.Tools 只给摘要（原 98,989 tokens/151% 预算）
- plugin_list 描述讲清 auto_start（按需）与 alive（此刻是否在跑），
  明确不能由 alive=false 推断能力不存在
- pluginmgr/webui 去掉写死的 /home/newqqagent 回退路径（env → pluginDir 反推 → 报错）
- lua: 盘上适配器与内置版本不一致且无基线时响亮告警（deepseek 流式丢失
  tool_calls 导致'模型不调工具'的真因）

测试：go build ./... 通过；go test ./... 60 包全绿
 2026-10-26 20:55:25 +08:00
JianFeeeee
475aac867b refactor(update): 内核与插件更新合并为 update 子系统（三端共享一个底层） 
## 为什么合并（用户口径：更新部分应独立为子系统）

之前 kernelupgrade / pluginupdate 两个包，但它们共享三样东西，
分开写就要各复制一份，然后慢慢不一致：

① **版本比较** —— 合并前共 6 个函数做同一件事：
   kernel 侧 ParseSemver / CmpSemver / versionNewer / trimTagV
   plugin 侧 trimV / isNewer / semverNums（还自带一份正则）
   且**行为不一致**：kernel 侧只挡 len<2，"1.4" 漏过去被填成 1.4.0；
   plugin 侧的正则要求两段所以也漏。两份都把 "1.4" 当合法版本。

② **两阶段交互**（检查 → 确认 → 执行）—— 同一套用户口径。

③ **失败要响亮** —— 都不静默降级。

## 收敛结果

internal/update/
  doc.go     子系统头：职责边界、三端共享契约、为何不分家
  semver.go  ParseSemver / CmpSemver / Newer / TrimTag（**唯一一份**）
  kernel.go  内核升级闭环（解包→校验→备份→替换→重启→复核→回滚）
  release.go GitHub Release 查询
  plugin.go  插件升级（查仓库→拉源码→hmapdev 编译→产物）

三端共享：
  agent 工具（plugin_update / kernel_update）  ┐
  WebAPI（/plugins/update、/kernel/update）    ├─ internal/update
  CLI（homed-upgrade）                         ┘

入口层只做参数解析与结果呈现，不含业务逻辑 —— 否则会出现
"agent 说没有新版、WebUI 却升了级"的分裂状态。

## 合并时抓到的两个真实 bug

① **ParseSemver 只挡 len<2** ⇒ "1.4" 被零值填成 1.4.0，
   「1.4 → 1.4.0」被判完全相同（说"无需升级"），而两者内容未必相同。
   现在要求恰好三段。

② **不认 v 前缀** ⇒ GitHub release tag 全是 v1.4.0 形态，
   CLI 对"当前 v1.4.0 vs 包内 v1.4.0"判不可比、只能退回字符串比较。
   现在 TrimTag 去 v 前缀后再比。

## 新增入口

· plugin_update（agent 工具）+ GET/POST /plugins/update
  —— 两阶段：apply=false 只检查（列出 updatable / no_repo 两类，
     后者是"未声明仓库、无法自动更新"的内置/私有插件）；
     apply=true 需显式 plugins=all 或名单（不默认全升）
· kernel_update（agent 工具）+ GET/POST /kernel/update
  —— 两阶段同构；apply 只收本机包路径（URL 下载是 CLI 职责，
     agent 不该在推理中发起长下载）

判据：
· internal/update: Newer / TrimTag / ParseSemver 的边界（含上述两个 bug 的回归）
· pluginmgr 入口层 5 条：检查形状、apply 必须显式给范围、
  kernel apply 必须给 pkg 且指向 homed-upgrade、拒绝目录当包
 2026-10-26 01:05:09 +08:00
JianFeeeee
77f596fb07 chore(log): 全仓运行期日志与 Fatalf 英文化（320 处 / 83 文件） 
用户要求："历史以来的全部写入日志的区域"改为英文，因为中文日志
在没有中文字形的终端/容器里会乱码，且跨机器、跨工具 grep 时不可靠。

## 范围

- 全部 log.Printf / log.Fatalf / log.Println 的**运行期日志**（含启动横幅、
  致命错误、告警）：320 处，83 个文件，占全仓日志的 53%
- 未改动：代码注释、面向用户/模型的文本（工具描述、system prompt、
  错误 Reason）——那是产品语言，不属于日志

## 连带修改（必须同步，否则静默失效）

| 依赖点 | 处置 |
| --- | --- |
| medialoop_test.go 断言中文日志（3 处：失败原因分类 / 模拟解码失败 / 不支持=1） | 同步改为断言英文 |
| 判定日志格式的正则 `\d+ 个: image/webp` | 改为 `\d+ x: image/webp` |

## 顺带修正一处提示词超限（真实回归）

新增【加速序列】块（115 字，让模型知道何时该用 seq，见下）后，
TestSystemPromptStaysCompact 报 2022 > 2000 字。

处置：上限上调到 2100，并在注释里写明**额度用途**——
【加速序列】属于"模型据此做不同决定"的行为判据，占用增删余地正当；
但技术说明仍不许占用这份额度（下次想再调数字时该去掉的是说明本身）。

【加速序列】块内容只留判定条件（多对象重复 / 顺序已知 / 以前做过），
格式细节全部下沉到 seq-tools skill —— 避免两处真相。

## 验证

- go build ./... / go vet ./... 通过
- 分块跑全仓测试通过（agent、plugin、plugins/*、security、memory、
  config、kernelboot、kernelmod、cmd）
- 残留中文日志仅 1 条注释，非日志调用

## 运维提示

日志文本变了，依赖 grep 中文的既有习惯要改为对应英文词，例如：
  内核装配完成        -> kernel assembly complete
  插件调度完成        -> plugin scheduling done
  已建链              -> link established
  已加载 N 个         -> N loaded
 2026-10-25 15:55:26 +08:00
JianFeeeee
f256098c9f refactor: 全面改名为 HologramAgent + 提示词技术内容下沉到 skill/工具描述 + 修 21 处乱码 
## ① 全面改名 HomeAgent → HologramAgent

仓库已改名，但代码与文档里仍有大量旧名。本次按"用户能看到的优先"全量替换：

- 用户可见：登录页标题/页脚、默认人格第一句、CLI 状态输出、启动日志、
  plugin_install 的工具描述、AI 图片插件的 User-Agent
- 文档与脚本：README、assets/docs、docs/zh、deploy/*.sh、.github/workflows
- 鸿蒙工程：cmd/ohos/HomeAgent → cmd/ohos/HologramAgent（git mv）
  目录内的 module/app 描述同步；**证书路径原样保留**
  （default_HomeAgent_xxx.cer/p7b/p12 是签名材料的实际文件名，改了会找不到证书）
- 插件元数据：plugin.json 的 author

★ 必须保持原样的两处（改了会坏）：
  · legacySeededPromptSignature = "你是 HomeAgent 的看板娘「小宅」…"
    —— 那是识别历史播种人格卡的**原文锚点**，改了就识别不出旧数据
  · 公开 SDK 的 ProxyAuthHomeAgent = "homeagent"
    —— 那是 SDK 契约里的值，属独立仓库，本仓不改

## ② 修 21 处乱码（U+FFFD）

这些是历史编辑留下的编码破坏，全在注释里，例如：
  「赌注重下���遍」→「赌注重下一遍」
  「「不��滤」」  →「「不过滤」」
  「**待��退场**」→「**待退场**」

★ 保留 providers/chineseclip/tokenizer.go 里的 2 处：那是**故意**用
  U+FFFD 演示"非法 UTF-8 字节被归一成 U+FFFD"，不是乱码。

## ③ 提示词技术内容下沉（用户：技术性内容应该收敛到 skill 与 -help 中）

实测系统提示词 2309 字，其中两段几乎全是**模型无法据以行动的实现细节**：

  【工具执行顺序】1272 字（ParallelSafe 声明、批内降级、batchRunnable 判据…）
  【三层记忆】   1069 字（L1/L2/L3 编号、消费式删除、向量空间、指纹…）

收敛后 **2309 → 1723 字（-25%）**，保留的全是"模型据此做什么不同的事"：

  工具顺序：默认并行 / 不要依赖先后 / 同通道保序 / 写类工具可能串行
  三层记忆：时序里能看最近 / doc_query 把历史事件按原始时间戳插回时序 /
           关系用 memory_recall / 成文知识用 knowledge_search

判断口径写进判据：新加一段提示词前先问"模型会据此做什么不同的事"，
答不上来就该进 skill 或工具描述。

## 判据

prompt_memory_test.go 新增 2 条：
- TestSystemPromptHasNoImplementationJargon
  黑名单：ParallelSafe / batchRunnable / 消费式 / DenseCosine / fingerprint /
  向量空间 / 批内降级 / 自激
- TestSystemPromptStaysCompact：上限 2000 字（当前 1723）

变异：把 "ParallelSafe 声明、批内降级" 加回工具顺序段 ⇒ 第一条立刻红。

## 验证

- go build ./... / go vet ./... 干净
- go test ./... -count=1：58 包 0 失败
- make check-client-versions：客户端与内核版本一致
 2026-10-22 20:49:44 +08:00
JianFeeeee
4e70b8d5d8 refactor(module): 核心仓 Go module 路径改为 github.com/JianFeeeee/HologramAgent 
批 1，不含 SDK 仓与目录改名。

- go.mod 第 1 行 module 路径
- 366 个 .go 文件的完整前缀 github.com/JianFeeeee/HomeAgent 机械替换
  （857 处，仅完整前缀；展示名/注释里的 HomeAgent 字样留给批 5）
- 未改：third_party 目录名、SDK 自身 go.mod module、go.mod replace 目标、
  homed/waiter 可执行名、.hmap 后缀
 2026-10-21 12:17:19 +08:00
root
3119d48625 refactor(terminal): 终端逻辑回归 agentcli，内核不再编码终端语义 
按用户指正调整架构：终端是 agentcli 的职责，内核不该有终端逻辑；插件与
agentcli 的联动应走事件总线，而不是内核内部组件。

## 删掉内核里的终端语义

`internal/agent/core/terminal_registry.go`（280 行）整体删除。它做了两件不该
内核做的事：定义「什么是终端会话」、从 EventToolCall 的 Go map 文本里解析
terminal id / command 并归并会话与命令历史。连带移除：

- Agent 的 terminalReg 字段、构造、subscribeTerminalRegistry 订阅
- StatusAPI 上的 ListTerminals / CmdHistory
- sdk.TerminalAPI + PluginSDK.Terminal() + Registry.SetTerminalAPI 及接线
- 对应测试（迁到插件侧视图包）

保留 `sdk.TerminalStatus` / `CmdExecStatus`：它们只是线上 JSON 格式，WebUI/CLI
返回给前端时口径一致。

## 插件侧订阅事件总线自攒视图

新增 `internal/pluginview`（TerminalView）：把原先内核那份归并逻辑原样搬过来，
由插件自己持有。数据源仍是两条总线事件：

    EventTerminalOutput（agentcli 发）→ 会话输出 + 生命周期
    EventToolCall      （内核发）    → cmd_run 历史、terminal_create/close 归并

WebUI 在 NewHandler 订阅、Close 退订；CLI 在 Start 订阅、Stop 退订。
两边共用同一实现，避免历史上「两份推导各踩一次 Go map 文本」的坑。
视图不是权威：真值在 agentcli，插件晚于会话启动会缺早期会话（注释写明）。

## agentcli 保持内置

它现在仍需要 `Publish`（进程内事件总线写入）——外部插件没有上行事件通道
（`EventPublish` 在 withheldCapabilities 里，proc 只有 events.subscribe）。
按判定标准留内置；将来要外置，须先开一条受控的插件→内核上行事件通道，
本次刻意不开（用户决定：先保持内置）。

## 文档

中英 ARCHITECTURE 新增「终端归属」小节：说明职责边界、两条事件、视图非权威、
以及 agentcli 为何仍内置；内置判定表里 cli/webui 去掉 TerminalAPI 一项。

## 验收（本机实例实测）

- 内核编译通过，删除后 `go build ./... && go vet ./...` 干净，`go test ./internal/...` 全绿
- 实例重启后：让 agent 开终端跑 `echo term-view-test` →
  WebUI `GET /api/v1/terminals` 返回 term_1（output 正确、running=false）
  CLI `/terminals`（unix socket）返回同一份；
  两处都是从事件总线自攒，内核侧无终端代码参与
- cmd 历史分支由迁过来的单测覆盖（Go map 文本解析、生命周期、上限裁剪）
 2026-10-20 09:33:08 +08:00
JianFeeeee
40de84facc feat(systemd,webui,security): 数据目录一致性接线 + 内嵌主密钥注入 
## 1. 数据目录一致性（原为死代码）

`internal/systemd/sync.go` 能编译但**从未接线** —— 没有任何地方调用它。

内核有**两处**数据目录来源且不等价：

	-data <dir>            ← systemd 单元 → memory/graph.db、插件数据根
	core.daemon.data_dir   ← 数据库     → memory/text、documents、knowledge

不一致时数据**分裂**：图记忆在 A、文本/知识在 B，检索跨目录、备份会漏。
生产当前两者一致所以没暴露，但 WebUI 允许改 DB 里的值而**无任何提示**。

接线三处：

 · cmd/homed/main.go 启动时检查，不一致则打告警 + 内联修复命令
 · GET /api/v1/system/data-dir 返回诊断（只在真不一致时给 sync_command）
 · 判据 6 条（InSync/Clean/SyncCommand 内联 sed/备份/daemon-reload/drop-in）

★ 只告警**不改**：静默改 systemd 单元比不提示更危险 —— 改错了服务
起不来，而用户不知道是谁改的。命令里已内联 sed 替换，人复制执行即可。

## 2. 内嵌主密钥（方案 C）

build.sh 支持 `HA_EMBEDDED_KEY_HEX`（64 位 hex）经 -ldflags 注入。
从**环境变量**读而不是写进文件：本仓有两个公开远端，64 位 hex 一旦
写进被跟踪的文件就永久留在 git 历史里。

未设时不注入、不报错：开发机与 CI 本来就不该带生产密钥。
设了但格式不对则**中断构建**（`return 1`）—— 静默产出一个没有内嵌钥的
二进制，会让"防丢失"这个目的悄悄失效。

实测（真机）：磁盘上**没有** security.key 时，仅靠 embedded 密钥即可
Submit + 二次加载解密成功；日志确认
`密钥来源 embedded (构建期注入，指纹 0db8e9c5)`。

## 判据第一版的两个错误（记下来）

 · 没给 UnitPath 就断言"必须含 sed -i" —— 实际 sed 行只在 UnitPath
   非空时生成，判据误报。
 · 断言 `/` 必须转义 —— 但 sed 分隔符是 `|` 不是 `/`。`/` 无需转义；
   真正必须转义的是 `&`（sed 里表示整个匹配）与 `|`（分隔符）。
 2026-10-18 13:51:00 +08:00
JianFeeeee
198811253a feat(webui+guard): 内核重启/关机按钮，指令走心跳复用既有协议 
## 需求

WebUI 加关机与重启按钮，内核提供对应内部接口。有些状态变更只能靠重启
生效（换 LLM 源、换主密钥），没有这条通道时用户只能 ssh 上去敲 systemctl。

## 设计：复用心跳，不新开通道（用户指出的方向）

guard 与 worker 之间已经有一条现成的、每 5s 一次的单向通报（心跳文件，
内容原本是 `t=<unix>`，只用来刷 mtime）。用户点按钮本质就是"我要你在
下一次心跳时知道这件事"——再开 unix socket / 信号 / 临时文件，只会多出
一套要防重、防丢、防竞态的机制。

    WebUI 点按钮
      → POST /api/v1/kernel/{restart,shutdown}
      → sdk.KernelControlAPI（只投递，立即返回）
      → 下一次心跳把 `cmd=restart|shutdown reason=...` 写进 <data>/heartbeat
      → 重启：worker 清理 → exit 42 → guard 重拉（**既有机制，零改动**）
        关机：guard 在 workerCleanExit 分支读到 cmd=shutdown
              → systemctl stop → 不再拉起

★ 关机为什么必须由 guard 做：
  unit 是 Restart=always，guard 自己 return 会被 systemd 立刻拉起
  （用户点了"关机"、几秒后服务又活了）。必须显式 systemctl stop。
  而不让 worker 自己停：它是被守护方，且**只有 guard 知道这次该不该重拉**。

★ 指令必须一次性消费：guard 读完立即原子重写文件清除 cmd 行，
  否则每次心跳都读到同一条 ⇒ 无限重启/关机。worker 侧还要检查
  "指令写过但文件里没了" ⇒ 已被消费 ⇒ 清本地 pending，否则又写回去。

## 顺带修的真缺陷：心跳文件无限增长

生产实测 **14.6MB**（纯 O_APPEND，约 70 天）。心跳的唯一职责是刷 mtime，
历史行没有任何读者 ⇒ 每次 consume 要整读 14.6MB（实测 27ms）。
改为 O_TRUNC 滚动写：只保留当前一行。真机验证 15,322,164 → 13 字节。
consume 也加了尺寸守卫（大文件只读尾部 8KB）。

## 安全：能力分级 + 白名单（两道）

1. proc 桥的 method 能力表：新增 `CapKernelControl` 一档。
   ★ 判据 `TestCapability_AllMethodsClassified` 当场报出
   "未登记 ⇒ 会按 CapCore 放行，绕过权限检查" —— 那意味着任何插件都能关机。
2. 内置插件走 `SDKConfig.KernelControl`，第一版我写成"有就发"，
   等于全部内置插件都能关机。改为按名字白名单（目前只有 webui）。

## 判据（7 条）

心跳：解析 / 消费后必须清除 / worker 不得写回已消费指令 / 未消费时必须续写
能力：只有白名单插件拿得到 / 未装配时返回 nil 不 panic / SDK nil 安全
心跳文件：不得无限增长 / 大文件只读尾部且读后收敛

变异 6/6 咬住。全量 53 包 ok。

## UI

导航底栏两个图标按钮（与主题/语言/退出并列）：重启有确认框 + 轮询等它
回来并自动刷新；关机有**二次确认且写清后果**（必须人工 systemctl start）。
两者都先把响应写回浏览器并 Flush，再让内核退出 —— 否则用户看到的是
connection reset，无法区分"正在重启"和"真出故障了"。
 2026-10-17 21:18:07 +08:00
JianFeeeee
a68d6a428c feat: 模块化内核（编译期依赖图定序）+ 密钥防火墙 + 插件三态生命周期 (#10) 
* feat(kernel): 模块化内核 + 编译期依赖图定序

把单体 init 序列拆成「模块自声明依赖 + 编译期生成依赖图 + 运行期只读图」。

## 为什么

原 cmd/homed/main.go 里 17 步 init 是**手写顺序**，依赖关系只存在于
注释和人脑里。实测踩到的坑（见 docs/zh/kernel-modularization-design.md）：
 · nlp.defaultParser 被 initONNXParser 写、被 distiller 读，两者相距 60 行，
   只靠 ticker 10min 才没炸（隐式依赖，无声明）
 · 加一个模块要人肉找"该插在哪"，插错的表现是运行期 nil 解引用
 · 关停是 defer ks.CloseAll()，而热更新路径 os.Exit(42) **跳过 defer**
   ⇒ docStore/distiller/textMem 的 flush 全部丢失（每次热更新都发生）

## 怎么改

- internal/kernelboot/：KernelState（一个结构体收全部包级共享变量，字段
  nil 安全）、Module 接口、graphfile（依赖图编解码 + 与二进制 hash 对账）、
  scheduler（按 BFS 层并行 Init）、syncbus（层边界写通知）、
  lifecycle（Quiesce/Resume 可逆伪关机，区别于一次性 CloseAll）
- internal/kernelmod/<name>/：每个模块一个文件夹，Requires/Provides 自声明；
  all/all.go 是唯一的 import 清单（Go 循环导入约束）
- cmd/homed-depgraph：编译期生成依赖图，Makefile 注入 digest
- 运行期只**读**图，不计算顺序（顺序是编译期决定的，源码里没有中央清单）

## 判据

kernelboot 8 条 + 图失败模式 7 条（全部拒绝并给准确错误）+ 模块目录数
与注册表一致性。变异测试 15/15 咬住，含：
 · 删掉 AddCloser 的锁 → -race 报数据竞争
 · Scheduler 同批跑去重 → 203 vs 200
 · 图 hash 不匹配 → 拒绝启动

## 顺带修的缺陷

热更新路径漏调模块关闭 ⇒ 显式 stopKernelModules()，并用 AST 判据钉住
"必须在 os.Exit 之前"（字符串检查在本仓已骗过我三次）。

实测：冷启动 1630ms（5 层/17 模块，原 17 步串行）；生产 22 插件全部建链。

* feat(security): 密钥防火墙 + 配置加密 + close 纪律

## 密钥防火墙

模型只见别名、不见明文；插件工具调用入口（StageHost.ExecuteTool）做入向
回填。三维能力：
 · 出向：工具输出里的密钥被替换成 [[secret:name]] 别名后才进上下文
 · 入向：模型传别名，入口处填回真值（插件完全无感知）
 · 存储：config.db 里不存明文（0644 的库可读），敏感值独立 0600 文件

模式库「宁漏勿误伤」：宁可漏掉一次替换，也不把正常文本误当密钥。

## 配置加密

- internal/security/{codec,key,keyring,store,global}.go：AES-256-GCM，
  enc:v1: 前缀，密钥轮换（OldKeys 解码 + 新钥加密）
- harden.go：数据目录权限收紧
- embedded.go：支持内嵌主密钥（可选，仍保留外部 key 文件路径）
- EncryptExistingSecrets / AuditSecrets：启动时幂等迁移 + 审计

## close 纪律（用户明确要求：只要调 close 就要有前置检查）

internal/safeclose：Safe / SafeFunc。全仓 37 处裸 close(chan) → 0。
关键教训（都写进注释和判据）：
 · `select { case <-ch: default: close(ch) }` **不是**并发安全的
   （两个 goroutine 可同时命中 default）—— healthcheck 原先是这种写法
 · `sync.Once` **不可重入**：X.Do(func(){ Safe(&X, ...) }) 会自锁，
   症状是 go test 直接挂住（3 个包 600s 超时），栈里只有嵌套的 Once.Do
 · map 里按请求持有的 channel（mcp/stdio.go、clawhubadapter/sidecar.go）
   改成 *pendingRPC 包装，每通道一个 once

## 判据

security 全量 + TestNoBareCloseOutsideSafeclose（AST 级扫描，含注释剥离）
+ TestNoNestedSelfOnceDeadlock（正则修正：\w+ 不匹配点号，捕获组要含 '.'）。
变异 2/2 咬住。全量 52 包 ok。

* feat(plugin+deploy): 插件三态生命周期、数据目录迁移、发行包修复

## 插件三态生命周期（用户要求：自动启动 / 启用但不自动启动 / 禁用）

- Manifest 新增 requires_facilities / auto_start（*bool，用于区分
  "未声明"与"显式 false"）
- plugin-host 模块（internal/kernelmod/pluginhost）：用 kernelboot.Scheduler
  按依赖时机拉起，**不再手写两阶段**
- 运行态停启 StopPlugin/StartPlugin **可逆**：不写 disabled_plugins
  （不改用户决定）、不置 shuttingDown（之后还能加载）、会摘掉注册面
- 与 StopAll 的区别写进注释 —— StopAll 置 shuttingDown 后**永久无法加载**，
  那是进程退出用的，误用于"暂停"就是关了就死

## 数据目录迁移（伪关机 → 迁移 → 唤醒）

- kernelboot/lifecycle.go：Quiesce/Resume（可逆，区别于一次性 CloseAll），
  逆序暂停、逆序恢复、Pause 失败回滚
- kernelboot/migrate.go：BeginMigration/End 编排（先停插件 → 再停内核写者
  → 等在途归零）
- distiller/textmem 增 Pause/Resume 门（不是 cancel —— cancel 不可逆，
  恢复要重建整个对象）
- 模块 migration：体检 + 生成可执行迁移脚本

★ 迁移脚本的三个实测教训（都写成了判据）：
 1. 无条件改 /etc/systemd/system ⇒ 演练把**生产** -data 改成了演练目录。
    加 --dry-run（零改动）+ 强制校验 systemd 当前 -data == OLD
 2. 本机没装 rsync，脚本在"服务已停、数据未搬"处硬失败 ⇒ cp -a 回退，
    并明确警告不保硬链接/ACL（生产 plugindev 有大量 git 硬链接）

## 发行包修复（全部经实测确认）

 1. package-linux.sh **完全漏打 depgraph.bin** ⇒ 内核 exit 1
    （"生产构建（内嵌 hash 非空）但读不到依赖图"）
 2. build_homed 不走 Makefile ⇒ 单独修 Makefile 无效，必须同时生成图+注入
 3. build.sh 的 LDFLAGS 用**历史模块路径 gitcode.com** ⇒ -X 静默 no-op
    ⇒ --version 显示 unknown
 4. Makefile -ldflags 用**单引号** ⇒ 注入了字面 $GRAPH_HASH

## ★ build.sh 的版本号必须校验（真实事故）

原 `VERSION="$(git describe --tags --dirty)"`。无 tag 分支上它返回**分支名**
`backup/pre-identity-rewrite-20261005-51-g03d87a4e-dirty`，被注入 meta.Version
⇒ 插件握手判据 MajorVersion() 把整串当主版本 ⇒ **22 个子进程插件全部
握手失败**（"主版本不匹配"）。内核活着、systemd active、日志每条都像
插件的问题 —— 实际是发行包带着非法版本号。

修法：git describe 只在形如 vX.Y.Z 时采用，否则回退 meta.Version（权威源），
并对最终值做形态守卫。deploy/packaging/version_guard_test.go 3 条判据，
变异 2/2 咬住。

## deb 的 systemd unit 改为 guard 模式

ExecStart=/usr/bin/homed --role=guard --data /var/lib/homeagent
（worker exit 42 → guard 重拉，不经过 systemd、不计失败）
含 RestartSteps/RestartMaxDelaySec/TimeoutStopSec + 硬化
（NoNewPrivileges/ProtectSystem/ProtectHome/DevicePolicy/ReadWritePaths）。

## 其他

- internal/plugin/proc：非法 JSON 帧的报错**可定位**（内容摘要 + 可能原因 +
  修法）。生产实测 1038 条非法帧（插件往 stdout 打日志 = 污染协议通道）
- 示例插件 4 个 14 处 fmt.Printf → log.Printf
- hmapdev 模板同步修复；scaffold 判据剥离注释（模板注释里就含 fmt.Printf）

* chore: 收尾（主密钥轮换命令、IPC/知识库加固、SDK 对齐）

- cmd/homed-key-rotate：把 security 里的 RotateKey/RotateKeyFile/RekeySecrets
  串成一条**可执行**的运维路径。没有它，E-1 就只是库里的能力而不是
  "出事时能做的事"，而轮换的价值恰恰在于能执行。
- cmd/homed：kmod_runtime（模块装配入口）、plugins_scheduled（failback
  白名单）、memcandidate、bootstrap_order_test / shutdown_flush_test
- internal/ipc、internal/devicebridge、internal/knowledge：配套加固
- third_party/homeagent-sdk/sdk：PluginMgrAPI 增三态能力（mgrStop/mgrStart/
  mgrIsRuntimeStopped）+ settings 对齐

判据：bootstrap_order_test（启动顺序不依赖手写序列）、
shutdown_flush_test（停机的两条路径必须对称 —— exit 42 会跳过 defer，
热更新路径下模块关闭/flush 曾全部丢失）。

* test(security): 测试夹具改用不可误认的占位值（修 push protection 拦截）

GitHub secret scanning 拦住了推送：三处测试夹具用了"看起来像真密钥"的
字面量：

  internal/security/prefilter_test.go:39
  internal/security/store_test.go:177
  internal/security/survey_test.go:20

它们全是**假密钥**（`AKIAIOSFODNN7EXAMPLE` 是 AWS 官方文档的标准示例，
其余是 `abcdefghij...` 这类可读占位符），但扫描器无法区分 —— 它只看形态。

★ 不绕过（不用 unblock URL、不加 allowlist）：直接改夹具。
原因：一旦允许"假密钥可以通过"，真密钥混进来时就没有最后一道门了。

改法：保留**模式库匹配所需的结构**，把可识别内容换成 FAKE：
  glpat-abcdefghijklmnopqrst       → glpat-FAKE-TEST-TOKEN-NOT-REAL
  sk-abcdefghij...012345           → sk-FAKE-TEST-KEY-NOT-REAL-0000000
  AKIAIOSFODNN7EXAMPLE             → AKIA0000FAKE0000TEST   (保持 20 字符)
  ASIAIOSFODNN7EXAMPLE             → ASIA0000FAKE0000TEST
  xoxb-123456789012-abcdefghijklmnop → xoxb-FAKE-TEST-TOKEN-NOT-REAL

★ 中途踩到一次：AWS 键的模式是 `\b(AKIA|ASIA)[0-9A-Z]{16}\b`（共 20 字符），
我第一次替换成 19 字符的 `AKIAFAKETESTKEY0000` ⇒ 模式匹配不上 ⇒
TestSurvey_WhatIsCaught / TestRecognizesCommonShapes /
TestPrefilterNeverBlocksRealMatches 三条当场变红。
判据正确地拒绝了"为了过扫描器而削弱覆盖"。

顺带核实：全仓 grep 无任何真实密钥泄漏。

* fix(packaging): package-linux.sh 的版本解析与 build.sh 统一

上一版只修了 build.sh，漏了 package-linux.sh —— 它仍只看 git describe：

  VERSION="${VERSION:-$(git describe --tags --dirty)}"

无 tag 分支上 git describe 返回**分支名**
（backup/pre-identity-rewrite-20261005-56-g98850e1），守卫会正确拒绝，
但要求人**手动传 VERSION** 才能打包。而 build.sh 早已能自动回退 meta.Version
⇒ 同一个版本，走 build.sh 打得出来、走 package-linux.sh 打不出来。

危害不只是"要手动传参"：运维为了跑通会去掉守卫，而分支名一旦进
meta.Version 就是**插件协议主版本**的来源 ⇒ 22 个子进程插件全部握手失败
（这是真实发生过的事故，见 3efa4e5）。

修法：两个脚本用同一套规则（git describe 仅在 vX.Y.Z 形态时采用，
否则回退 meta.Version），并对最终值做形态守卫。

判据：TestBothPackagingScriptsShareVersionRules —— 逐个读两个脚本，
要求都能从 meta/meta.go 取权威版本、都校验 git describe 形态。
变异（把 package-linux.sh 改回旧规则）咬住并准确指出是哪个脚本。

实测：不传 VERSION 跑 package-linux.sh，输出
  [PKG] warn: git describe 给出非版本串（...），改用 meta.Version=1.4.0
  Version: 1.4.0

* fix(test): 跨仓判据在 CI 上应 skip 而非 fail（修 PR 双红）

CI 上 "Go build / vet / test" 与 "Build linux/amd64" 双红：

  --- FAIL: TestHmapdevTemplateImplementsAllPluginMgrMethods
      bridge_sync_test.go:170: 读模板: open
      ../../../third_party/homeagent-sdk/tools/hmapdev/templates/proc_main.go.tmpl:
      no such file or directory

## 根因：判据依赖了一个**被 gitignore 的路径**

`.gitignore:33` 有 `third_party/homeagent-sdk/tools/`（SDK 仓自治，本仓不跟踪）。
于是：
  · 本机（完整 SDK 检出）有该文件 ⇒ 判据通过
  · CI（只 checkout 本仓）没有该文件 ⇒ Fatalf ⇒ **必红**

我提交时只在本机跑测试、没看 CI，所以这个问题拖到 PR 才暴露。

## 修法

文件缺失时 `t.Skipf` 而不是 `t.Fatalf`。

★ 这不是"放弃检查"：
  · 跨仓一致性由 **SDK 仓自己的判据**守着
    （tools/hmapdev/scaffold_stdout_test.go 等），那里才是模板的真实归属地
  · 本判据在本机开发时**仍然生效**（已验证：有文件时 PASS，缺文件时 SKIP）

## 验证

 · 本机（有文件）  → PASS（判据真跑）
 · 模拟 CI（移走 tools/）→ SKIP（不再 fail）
 · 全量 53 包 ok / 0 fail

## 顺带

同目录还有 e2e_template_test.go 也读 tools/，但它是 `//go:build` 门控的
e2e 判据，CI 默认不跑，无需处理。

---------

Co-authored-by: JianFeeeee <JianFeeeee@users.noreply.gitcode.com>
 2026-10-17 19:18:24 +08:00
JianFeeeee
9f7d91c219 refactor(memory)!: 删除 CAS 包与第二套召回（块 union 化第四阶段：收尾） 
块 union 化前三阶段已让块自带负载、回填存量字节。本提交拆掉 CAS 本身：
`internal/memory/media/`（2100 行）+ `QueryMediaScored`（第二套召回）
+ `media_refs`/`ref_count` 引用账本 + `internal/sdk/media.go`（MediaAPI）
+ `SDKConfig.Media` / `SetMediaStore` 接线。删完 CAS 才真正不存在。

## 为何可删（不是"先删了再说"）

- **MediaAPI 在生产早已是死的**：`SDKConfig.Media` 自 86572d13 起从未被设置，
  `sdk.Media()` 恒为 nil，插件 digest 路径一直走"内容寻址库不可用"分支。
  删的是死代码，不是活路径。
- **第二套召回确无调用方**：`QueryMediaScored` 仅被 media 包自身的测试引用，
  跨包引用为 0（块召回走 `RecallBlocks`）。
- **heldMediaDigests 补丁**（crossmodal 靠它防召回"无处可归的媒体"）
  已在 86572d13 删除 —— 两套存储才需要的那种补丁，随存储一起没了。

## 替代路径：块引用取代 digest

插件取媒体从 `sdk.Media().Get(digest)` 改为 `sdk.Memory().MediaBytes(ref)`：

- **新增 `MemoryAPI.MediaBytes(ref) (data, mime, ok, err)`**（内置接口，非 pubsdk）：
  按块引用（完整块 ID 或唯一前缀）取字节；`ok=false` 而非 error ——
  "这个引用没有媒体"是调用方能处理的常态。
- **seemedia / multimodal**：`digest` 参数语义改为**媒体块引用**，工具描述同步。
  path/url 两条来源不变（生产实际只用这两条）。
- **webui 知识上传**：媒体字节不再 Put 进 CAS 再拿 digest，而是作为
  `KnowledgeMediaRef.Data` 随引用携带，由 knowledge.Write 落进条目目录
  （与 content.md 同生共灭，Remove 的 RemoveAll 天然清掉）。
- **回填命令去依赖**：cmd/homed-media-backfill 不再 import 待删的 media 包，
  改为直接读**冻结的历史布局** blobs/<d[:2]>/<d[2:]> 并自校验 sha256。
  依赖待删代码的迁移工具会在删包那刻失效 —— 迁移必须比被迁移的东西活得久。

## 判据（全部做过变异测试）

- `TestMemoryBytes_ByBlockRef`：完整 ID / 唯一前缀可取回且逐字节一致；
  不存在→ok=false；过短前缀（歧义）→ok=false；无负载块→ok=false；空引用不 panic。
  变异（不校验 ok，把不存在当有）当场被 3 条断言抓住。
- `TestE2EMediaBytesAgainstBackfilledDB`（-tags e2e，读真回填库）：
  10/10 块经 MediaBytes 取回的字节与块 data 的 sha256 完全一致。
- `TestKnowledgeUploadedMediaRetrievable` 重写为**条目目录自带字节**判据
  （不再是"向存储按 digest 读回"）；`TestKnowledgeUploadMediaNeedsNoStore`
  改为"上传无外部存储依赖也必须成功"（旧的 503 语义已随 CAS 消失）。

## 静态确认
`QueryMediaScored` / `internal/memory/media` import / `MediaAPI` /
`sdk.Media()` / `SetMediaStore` / `heldMediaDigests` 全仓均为 0 处
（仅剩 medialoop.go 一句历史注释）。

回归：memory / sdk / agent-core / knowledge / plugin / webui / seemedia /
multimodal 八包全绿；全仓生产编译 GREEN。
 2026-10-12 16:52:43 +08:00
JianFeeeee
6d38a164eb chore(module): Go module 路径随托管地迁移 gitcode → github 
## 背景

仓库早已迁移到 GitHub（`github.com/JianFeeeee/HomeAgent`，CI/CD 都在那边跑），
gitcode 保留为**国内只读镜像**（`ci.yml` 的 sync-gitcode-main 快进推送）。
但 go.mod 的 module 路径一直是 `gitcode.com/JianFeeeee/...` —— 既与权威源
不符，`meta.SourceURL`（AGPL §13 的源码提供入口）也指向镜像而非实际运行的代码。

## 关键区分（这是本次改动安全的前提）

两个 module 是**不同**的，影响面差一个数量级：

| module | 谁依赖 | 改它的后果 |
|---|---|---|
| `.../HomeAgent`（主仓） | **只有主仓自己** | 内部重构，零外部影响 |
| `.../homeagent-sdk`（SDK 仓） | 主仓 49 文件 + 所有外部插件 | 需重编插件 |

★ 实测确认：**插件不 import 主仓 module**（`strings qq/plugin.bin | grep HomeAgent` = 0），
只依赖 SDK 仓。而插件与内核的边界是 **RPC 方法名字符串**
（`plugin.init` / `tool.invoke`…，见 proc/protocol.go），**与 Go module 名无关**。
⇒ module 改名**不改变任何 wire 协议**，现网已装的插件照常运行。

SDK 的 GitHub 仓名是 `homeagentsdk`（无连字符），module 路径必须与之精确匹配，
否则 `go get` 会因路径不符失败，故取 `github.com/JianFeeeee/homeagentsdk`。

## 改动

- `go.mod` / `go.sum`：两个 module 路径 + require/replace
- 277 个 Go 文件 + Makefile + 打包脚本的 import 与 ldflags 路径
- SDK 仓 `meta.CoreModule`、`tools/hmapdev` 的 module 声明与工程模板
- 对外文档/链接的仓库地址（README、PLUGIN_DEV、OVERVIEW 等）

## 明确**保留** gitcode 的地方（镜像机制，不能动）

- `GITCODE_TOKEN`、`GC_URL="…@gitcode.com"`（CI 同步 job）
- `gitcode.com/api/v5/...`（release 附件上传）
- git remote `gitcode`（镜像拉取/推送）
- `docs/zh/ci-cd-runbook.md`（整篇讲镜像运维）

## 验证

- `go build ./...` / `go vet ./...` 绿
- `go test ./... -count=1` → 48 包 ok / 0 FAIL
- hmapdev 工具链编译通过（`third_party/homeagent-sdk/tools/hmapdev`）
- 全仓残留检查：module 形态的 `gitcode.com/JianFeeeee` = 0
- 镜像机制抽验：GC_URL / @gitcode / api/v5 / remote 均完好

## 顺带修正

`hmapdev/templates.go` 的注释此前写「gitcode 的模块不在 proxy.golang.org 上」——
module 已迁 GitHub，该论断不再成立。改为如实说明**为何仍默认 replace 到本机 SDK**：
离线可构建、避免版本漂移、内网可用。理由与托管地无关，故 replace 保留。
 2026-10-08 10:40:17 +08:00
JianFeeeee
e57adb5978 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
be765640d2 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
f93e9347f0 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
55d5f2a1d0 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
cc353765d6 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
7a013f5509 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
431aa91b47 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
b217883c3e 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
39cd42723c 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
5e88865784 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
c05d644dfe 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
dbc493a545 refactor(terminal): 内核开终端/命令历史权威视图，WebUI 与 CLI 都改接内核 
按「内核开，两个插件接」重构终端与命令历史的数据归属。

背景：此前 WebUI 与 CLI 各订 EventToolCall/EventTerminalOutput 攅一份状态，
同一件事两份推导，还各自踩过同一个坑——工具 result 是 Go 的 map 文本
（map[cols:80 ... id:term_2 ...]），断言成 map[string]interface{} 永远失败，
terminal_create 的 id 回填不生效，/terminals 因此恒空（WebUI 也一样）。
实测确认：WebUI 自己的 /api/v1/terminals 与 /api/v1/cmd/history 同样是空的。

内核开（权威唯一真相）：
- internal/agent/core/terminal_registry.go：TerminalRegistry 归并两类事件——
  EventToolCall（terminal_create/close、cmd_run，id/command 从 args 或 Go map
  文本回填）与 EventTerminalOutput（agentcli 生命周期 + 输出，含 64KB 缓冲上限、
  100 条命令历史、50 个终端上限）。
- internal/sdk/terminal.go：新增 TerminalAPI（ListTerminals/CmdHistory）与
  TerminalStatus/CmdExecStatus DTO。**不塞进 KernelStatus**：那是全量快照，
  前端每 3 秒轮询 /kernel，背上每终端最多 64KB 输出会让轮询成本爆炸；
  终端输出是按需拉取的明细，另开接口。
- Agent 订阅自己的事件总线（subscribeTerminalRegistry），且**只根 agent 建**
  （驻留子共用同一总线，每个子都建会 N+1 份重复记账）。
- SDKConfig/Registry/bootstrap 接线：pluginReg.SetTerminalAPI(agent)。

生产者补全（agentcli）：终端无输出时 ticker 不发事件，内核就无从知道终端
存在。新增 emitTermState，在 handleCreate/handleClose/readLoop 退出（超时/
进程结束/读取错误/stopCh）显式上报 running 状态，并给输出事件补 command 字段。
handleClose 改为接收 *sdk.PluginSDK 以便上报。

两个插件接（消费方）：
- WebUI：删掉本地 termStates/cmdHistory/subscribeTerminalStream/handleToolEvent
  及不再使用的 getStr；/terminals 与 /cmd/history 直接读 s.Terminal()。
- CLI：删掉上一轮刚加的 subscribeToolEvents 与 cliTermState/cliCmdExec；
  /terminals 与 /cmd/history 直接读 s.Terminal()。两条路（local/remote）都通。

测试：新增 terminal_registry_test.go，锁死 Go map 文本解析（旧缺陷根因）、
生命周期、CLI 直调路径（无 EventToolCall 仅凭 output 事件建条目）、历史与
终端数量上限。全量 go test ./internal/... ./cmd/... 通过。
 2026-09-17 18:56:15 +08:00
JianFeeeee
28c8631eab feat(webui): 数据查询 API + 前端 keyed 对账，去掉「局部重建」的闪烁 
jianf：局部重建的闪烁几乎消不掉，应暴露数据查询 api，前端轮询后增量更新视图，
聊天记录也用这套。

后端（数据查询 api）：
- ChatMsg 增加 seq（服务端单调递增、随记录落盘）；老记录加载时补 1..n，重启不重编号。
- /api/v1/chat/history 增加 after=<seq> 增量通道：只回 seq 更大的消息，返回 last_seq
  作下次游标；一批超 limit 时回**最旧**的一批（回最新会把被挤掉的旧消息永久漏掉）。
  普通响应也带 last_seq，客户端首次全量后据此初始化游标。
- 测试 TestChatHistoryIncrementalAfterCursor 钉住「不重不漏 + 截断停在返回的最后一条」。

前端：
- 新增通用 morph()：按「子节点位置 + nodeName」递归对账 DOM，同名节点复用、只同步
  变化的属性与文本。运行态面板的 put() 由 innerHTML 重建改为 morph —— SVG 圆环、
  队列条、数字块这些未变节点不再被替换，CSS 过渡与动画不再从头播。
- 聊天列表改用 keyed commitChatList()：按 data-key（服务端 seq / 本地临时 key）对账，
  未变消息节点一个字节都不动，只替换真正变化的那条。
- syncChatFromHistory 改走游标：pollChatIncremental() 用 after 拿增量 + tail=1 探尾部
  原地更新（工具调用/最终文本是原地改的，不产生新 seq）；聊天页可见时 3s 轮询。
 2026-09-14 15:56:27 +08:00
HomeAgent Agent
3afc3ec2ed feat(status+webui): 运行态图形化 —— 排队/四级中断队列/中断栈/驻留子/通道拓扑 
需求：首页不该只有文字，要能一眼看出内核在忙什么——排队消息数、各级中断
排队与中断栈、驻留子 agent 数量；这些要向**内部 SDK 暴露接口**，供 WebUI 等应用
展示；通道划分也要能画出来。

## 一、内核状态面（internal/sdk，内部 SDK，不受公开 SDK 冻结约束）

* SchedulerStatus 补：
  - interrupt_queues[5]：**四级中断队列各自的深度**（下标即级别 1..4，下标 0 恒 0，
    这样 level 能直接当数组下标用）。此前只有 pending_interrupts 总数，
    看不出"堵在 L1 还是 L4"——四级是抢占优先级，堵在哪级是完全不同的运行状态。
  - immediate：刚抢占成功、下一个安全点立即运行的那个中断（此前完全不可见）。
  - suspend_frames：中断栈的帧（栈底→栈顶，只给任务标识），depth 之外还能看出
    "谁被谁打断"。
  - interrupts_by_level / preempts_by_level：各级累计登记数与抢占成功数。
* KernelStatus 补 residents（驻留子运行时视图：状态/轮次/上下文已满/输入通道/允许输出）。
  刻意**不带**每个驻留子的 inputch 登记明细——状态面会被反复轮询，明细会让
  每次 /status 背上几十 KB；只给表大小，要明细走专门接口。
* ChannelInfo 补 direction(in/out/io)、description、tools、output_caps、caps_text。
  此前 collectKernelStatus 只透传 Name/Type，把描述/工具/能力**全丢了**，
  前端只能画出一排光秃秃的名字。

## 二、WebUI

* 新增只读 `/api/v1/runtime`：只回运行态三件事（scheduler/residents/channels），
  实测 **1.0KB**（/kernel 是 30KB 级）——所以能 3 秒轮询做"实时"感，
  而不必反复拉全量状态。
* 首页新增「运行态」面板（纯 CSS + 内联 SVG，前端仍无构建链）：
  - 四个数字块：排队任务 / 待处理中断 / 中断栈(深度/上限) / 驻留子 Agent，带占比条；
  - 四级中断队列条形图：每级"深度 · 登记/抢占"，四级语义**照抄内核**
    （L4 内核独占 / L3 交互 / L2 消息 / L1 后台），不自己起名字；
  - 中断栈层叠图（栈顶在上）+ ⚡立即运行项；
  - 通道拓扑：输入通道 → 内核 → 输出通道，双向通道两侧都出现，能力以胶囊标签显示。
* 3 秒轮询只在总览页可见时才发请求；切回总览时 renderAll 会立刻补一次。

## 验证

* 新增 TestSchedulerStatusExposesLevelsAndStack（四级队列/立即项/栈帧/各级计数映射，
  并断言"未使用的级别必须为 0"与"下标 0 恒 0"）、TestChannelInfoCarriesTopology、
  TestRuntimeEndpoint（形状 + 不携带 tools/plugins + 无状态源时 503）。
* go build / vet / agent+core+sdk+plugin+webui 全量测试绿。
* 真实浏览器实测（CDP 驱动，注入运行态样本走真实渲染路径）：
  数字块 [3, 5, 2/4, 2]；四级条 L4=1/L3=2/L2=1/L1=1 与数据一致；
  栈帧按"栈底→栈顶"渲染且标出栈顶；通道左右分列、io 通道两侧都出现。
 2026-09-14 09:05:14 +08:00
HomeAgent Agent
b8241ac303 refactor(webui): dashboard.html 6637 行拆成「外壳 + 样式 + 脚本」 
前端刻意没有构建链（纯 CSS + Vanilla JS，go:embed 进二进制），所以拆法是：
外壳 dashboard.html 留 {{DASHBOARD_CSS}} / {{DASHBOARD_JS}} 两个占位符，
init() 启动时把两份资产原样填回去 —— **发出的 HTML 与拆分前逐字节一致**，
但 6637 行的单文件变成三份，便于编辑与评审。

  dashboard.html   168 行   外壳（head/body 结构 + 两个占位符）
  dashboard.css   2099 行   样式
  dashboard.js    4371 行   脚本

逐字节校验（三重）：
  * 组装结果 sha256 == git HEAD 里拆分前的 dashboard.html；
  * 真实实例 GET /（带 API key）返回体 sha256 同上：0ef14b49…c053；
  * 新增 TestDashboardAssetsSplit：占位符必须存在、样式/脚本不得再内联回外壳、
    组装结果不得残留占位符且必须含样式与脚本特征串。

按行号切片时踩过一次坑并已修正：`</style>`/`</script>` 两个闭合标签被切掉
（正好少 27 字节）——正是因为当时少了逐字节校验，现在把它固化成断言。
 2026-09-14 07:17:23 +08:00
HomeAgent Agent
e5fa67955f perf(webui)+feat(config): 聊天记录写盘节流 + 配置库空闲页回收 
两条都是我上一封里点出、你说继续的问题。

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

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

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

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

测试：TestChatPersistenceIsThrottled（节流窗口内不写盘 + Close 必落盘 + Close 幂等）、
TestMaybeCompactReclaimsFreePages（删大值后文件确实变小 + 数据完好 + 阈值不达标时不白做功）。
 2026-09-14 07:14:55 +08:00
HomeAgent Agent
4a00922ec3 refactor(webui): handler.go 2993 行按资源拆成 11 个同包文件 
拆法：按「资源面」搬家，每个顶层声明（func/type/var/const）整体搬到目标文件，
声明体一字未改，各文件按实际用到的包重新生成 import。文件头加一行说明本文件负责哪一面。

  handler.go              骨架：嵌入前端资源、Handler/构造、路由表、鉴权会话日志中间件、静态页
  handler_chat.go         对话面：消息模型与内存历史、SSE 事件订阅、对话/历史接口
  handler_upload.go       上传面：handleChatFile / handleUploads / 中断对话
  handler_memory.go       记忆面：图/文档/文本记忆、知识库、LLM 源、变更追踪
  handler_agents.go       内核与代理面：状态、kernel、人格、代理/快照/回滚
  handler_settings.go     设置与插件面：配置读写、插件列表详情（含 pluginmgr 反代）
  handler_terminal.go     终端面：终端会话、终端接口、命令历史
  handler_sse.go          SSE 环形缓冲（断线重连补发）
  handler_openai.go       OpenAI 兼容面：/v1/chat/completions
  handler_device.go       设备网关反代（HTTP + WS 升级透传）
  handler_files.go        /files/ 与 /uploads/ 下载

零漂移校验：拿重构前的 handler.go 与新 11 个文件逐行比对（忽略空行、package/import 头），
**丢失行 0**；新增行恰好是 11 个文件头注释（14 行）。

顺带修掉 import 里两处假使用：handler_openai 的 sdk 只作为 Handler 字段名出现（h.sdk.），
handler_settings 的 fmt 只出现在注释里 —— 都从 import 里去掉。

验证：go build ./... / go vet / webui+config+sdk 测试全绿；
起真实实例（沿用已有 data 目录）后 /status /settings /chat/history /plugins /terminals
/kernel /memory /config /login 全部 200，设置在注入 5MB 历史的情况下仍是 33,921 字节。

最大文件从 2993 → 706 行（handler_chat.go）。
 2026-09-14 07:03:47 +08:00
HomeAgent Agent
ab738fe81a feat(webui): 聊天记录改为独立文件存储（位置可配）+ 存量自动迁移 
起因：聊天记录原先作为插件配置项 plugin.webui.chathistory 存在 config.db 里，
带来三个后果（都在生产实例上实测过）：
  1. 整段记录 5,176,016 字节会被 GET /api/v1/settings 当普通配置项整块返回；
  2. 每来一条消息就把整段记录重新 marshal 后写回 config 表，而那次写要拿
     config registry 的全局写锁 —— 消息频繁时所有配置读写都被拖着排队；
  3. 位置不可配（想放独立挂载盘只能改整个 data_dir）。

改动：
* 新增 internal/plugins/webui/history.go：
  - historyStore：默认 <data>/webui_chat_history.json，写盘用同目录 tmp+rename
    原子替换，崩溃不会留半截 JSON；读失败/JSON 损坏按空历史处理并告警
    （聊天记录不是关键数据，不该让它拖垮 WebUI）。
  - resolveHistoryFile：插件设置 history_file > 默认路径；相对路径按 data 目录
    解析（可指向独立挂载盘），data 目录未知时落到系统临时目录而不是进程 CWD。
  - LoadWithMigration：文件为准；文件为空而老配置项有内容时，把记录搬到文件、
    搬成功才删配置项（删不掉就保留并告警，不丢数据）；文件已有数据时顺手清掉
    上次没删干净的遗留键。
* 新增插件设置项 history_file（设置页可见可改）：留空 = 默认路径。
* handler.go：chatHistory 的读/写改走 historyStore，不再碰 settings；
  顺带把「写失败静默忽略」改成告警。

存量迁移实测（拿仍持有 5,271,690 字节老记录的实例跑新二进制）：
  日志：聊天记录已迁移到独立文件 .../webui_chat_history.json（1300 条），并从插件配置表移除
  迁移后：config_webui 里 chathistory 行数 = 0；记录文件 5,279,491 字节
          GET /api/v1/settings = 33,921 字节（迁移前 8,244,108）
          GET /api/v1/chat/history 正常（从文件读回 1300 条里最新的 3 条）

新增测试：TestResolveHistoryFile、TestHistoryStoreMigratesFromConfig（含二次加载
不重复迁移 + 损坏文件不 panic）、TestHistoryStoreSaveIsAtomicAndRoundTrips。
 2026-09-14 07:00:07 +08:00
HomeAgent Agent
155bb8b198 fix(webui): 设置接口不再吐内部数据；--webui 覆盖生效；端口占用不再静默成功 
三处实测确认的缺陷：

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

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

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

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

新增测试：TestSettingsNoCrossPluginLeak（跨插件泄漏/幻影键/chathistory 读写）、
TestListenOverrideAndBindFailure（覆盖生效 + 端口占用必须报错）、
TestResolveListenAddrPrecedence（优先级）。
 2026-09-14 06:54:16 +08:00
JianFeeeee
96e0da4a11 feat(scheduler): L4 也归内核级插件 —— WebUI 终止按钮可用“立即打断” 
上一提交把 L4 写成“内核独占（panic / selfip）”，漏了内核级插件这类来源。
用户澄清：**内核级插件应当能声明 L4，用于实现中断能力**，例如 WebUI 的终止按钮。

判据（两道闸，纵深防御）：
  1. proc 桥（外部进程唯一入口）一律把 L4 夹到 L3。在这里夹而不是只按 source 判，
     是因为 source 是插件自报字段、可以冒名；本函数所在位置能确知“来自外部进程”。
  2. core：isKernelLevelSource(source) 查 pluginReg.IsBuiltinPlugin，只有编译期内置
     插件（init() 自注册的工厂）才承认 L4。
source 约定 `插件名` 或 `插件名/实例`（webui/<deviceID>），判据取第一段——
否则带设备身份的 WebUI 来源会被误判成外部插件而拿不到 L4。

改动：
- core: interruptLevel(evt, privileged bool)；新增 isKernelLevelSource；
  requestPreempt 不再夹取（级别已由 interruptLevel 解析，否则内核级插件的 L4 被削掉）。
- eventloop: 传入 a.isKernelLevelSource(evt.Source)。
- proc 桥: 新增 clampExternalPriority，pubSdkInjectOpts 一律夹取。
- internal/sdk: 再导出 PriorityL1..L4（内置插件用 sdk.PriorityL4）。
- webui handleChatInterrupt（终止按钮）声明 PriorityL4。
- timer 声明 PriorityL3：定时器是“时钟那种实时工作”，比 QQ 那类可无限等待的
  异步消息高（L1）——这是对用户“它不是时钟那种实时工作”的直接推论，可改。
- 测试: L4 特权矩阵（非特权夹取 / 特权承认）、source 判据（内置、内置/实例、
  外部、空、前缀不误匹配）、内核级插件 L4 一路到达调度器、proc 夹取两条。
- 设计稿 §2/§3.2/§11.1/§14/§15 按“L4 = 内核 + 内核级插件”更正。

验收：go build/vet 干净；go test ./... 37 包 ok 0 FAIL；-race 全绿（含 webui/timer）。
 2026-09-13 07:18:03 +08:00
JianFeeeee
be0eb3eb54 feat(persona): 首启人格门禁跨通道化 + 内核 persona_set 工具 
WebUI 首启向导只覆盖 WebUI 这一条通道，而「人格该问一次」是所有通道的事：
走 QQ / CLI / ACP / 邮件来的人永远见不到那个向导，人格就永远是没确认过。

- 门禁移到 buildSystemPrompt（每轮重建 → WebUI/QQ/CLI/ACP/邮件全覆盖），
  以 core.internal.persona_initialized 为准：未确认时要求模型主动询问用户
  （默认 / 自定义 / 以后再说），确认后该段消失；personaStore 为 nil 时静默关闭。
- 新增内核内置工具 persona_set(mode=default|custom|later[, content])，
  落库逻辑与 WebUI 向导**共用 internal/config**（一个实现 + 两个薄入口：
  ConfigRegistry 直连 / 插件侧 SettingsAPI），避免两套语义各自漂移。
- AgentConfig 增加 PersonaStore 接口，cmd/homed 用 RegistryPersonaStore 实现。
- 非法输入（未知 mode / custom 空内容）在打标记**之前**拒绝：否则标记置位、
  向导被跳过，用户再没机会设。

E2E（隔离实例 + 真实 LLM 往返走 /v1/chat/completions，/var/tmp/persona/e2e.sh）9/9 PASS：
未确认时模型主动询问 → 用户答「用默认的」→ 模型调用 persona_set 落库并置位标记
→ 之后不再追问；反向对照（清标记 + 清会话上下文 + 重启）重新开始询问，
排除了「同一段对话里已问过」这一混淆。
 2026-09-12 13:57:06 +08:00
JianFeeeee
2e73007097 feat(webui): 首启人格向导（默认 / 自定义 / 稍后）+ 一次性标记 
接续人格配置项化（597f07c）：现在人格是 core.agent.personal_prompt，
本次加上「首启问一次」的界面，之后不再打扰。

后端（GET/POST /api/v1/persona）：
- GET  → {initialized, current_prompt, file_override}
        未设置时 current_prompt 回落到内置默认模板；存在 personal/personal.md
        时报告 file_override（它会覆盖配置项，向导据此提示用户）
- POST → {"mode":"default"|"custom"|"later","content":"…"}
        写配置 + 打一次性标记 core.internal.persona_initialized；
        custom 返回 restart_required=true（人格在启动时载入）；
        「稍后」= 保留当前默认 + 打标记，**绝不阻塞任何流程**
- 空内容的 custom 与未知 mode 一律 400，且**不打标记**（否则向导会被跳过）

前端（dashboard.html）：
- 首启拉一次 /api/v1/persona，未初始化则弹向导（复用一直没人用的 .confirm-* 样式）
- 「自定义…」第一次点击展开文本域并预填当前人格，再次点击才提交（避免误提交）
- 中英双语走既有 __() 机制；保存失败/空内容用 toast 提示

测试：TestPersonaWizardFlow（首启状态、later 打标记不改人格、custom 写入 + 需重启、
空内容与未知 mode 被拒且不打标记）、TestPersonaWizardReportsFileOverride。

E2E（真实实例）：首启 initialized=false → POST later → initialized=true，
config 中标记=1、人格键为默认模板；前端页面含向导函数。
 2026-09-12 13:02:18 +08:00
JianFeeeee
c04e80f1fe feat(core): 注入行为的记忆/裁剪标志位落地 + jieba 词库内嵌 + Windows 改走 WSL 
配套 SDK 提交：homeagent-sdk ba49dfd（公开 API 纯追加，无签名变更）。
本仓第三方的库镜像同步至该版本，以保证全新 clone 能编译。

## 1. 注入标志位（内核侧）

- 7 条注入路径（排队/中断/同步 × 纯文本/带媒体 + 旧 NoMem 变体）解析并转发
  no_memory / context_policy / cleaner_name；策略在入口**校验**，
  非法值报错而不是静默降级成 none（降级会让调用方以为自己声明的裁剪在生效）。
- 新增 validateContextPolicy（与 tool.register 同一套规则）与 pubSdkInjectOpts。
- input.register 不再手写字段白名单重建 ChannelDef，改为整体传递 + 补 ContextPolicy。
- io 层：applyInjectOpts 把标志位写进事件 payload，仅非零时写
  （零值与旧 payload 逐字节一致，事件订阅方与旧内核都不受影响）。
- ioAdapter / procCore / internal-sdk 别名补齐六个 *Opts 实现。

## 2. 修掉「输入无条件裁剪」这个真缺陷

eventloop 此前对**每条非中断输入**都调 `context.Prune(...)`：破坏性（低相关事件被
归档移出上下文）且无法从调用点看出是谁触发的。改为 pruneOnInput/pruneDeclared：

  优先级：注入点声明（payload.context_policy）> 通道声明（ChannelDef.ContextPolicy）
          > 默认**不裁剪**

查询向量仍取清洗后的内容；新增 cleanInputFor 解析清洗文本，优先级为
注入点声明的 cleaner（cleaner_name）> 按 source 查到的通道 cleaner > 原文，
名字查不到时**记日志再回退**（注入是 fire-and-forget，插件看不到错误，
至少要在内核日志留下「你声明的清洗没生效」的痕迹）。

## 3. jieba 词库内嵌（修「猜 GOMODCACHE → 静默失效」）

原 jiebaDictDir() 去猜 GOMODCACHE/GOPATH/~/go/pkg/mod，部署机上通常没有 Go 模块
缓存 → GetJieba() 返回 nil → 分词/关键词提取/NLP 依存解析（进而 doc→graph 三元组
抽取）/静态词向量 tokenizer **一律静默返回空列表**，只有一行日志。本机看起来正常
只因开发机与生产机重合、恰好有那份缓存。

现在词库随二进制分发：internal/memory/jiebadict/ 5 文件约 11.6MB + go:embed，
按**内容哈希**命名缓存目录落盘（词库升级不复用旧文件），已齐全则跳过写入。
模块缓存降为兜底。homed 体积 32MB。

顺带确认（并有测试佐证）：gojieba 的 Tag() 不需要 pos_dict/ 目录——
cppjieba 的 PosTagger 从主词典每行的词性列取 tag。

## 4. homed 放弃 Windows 原生，改走 WSL2

插件体系依赖「继承的 fd」+「统一共享内存区的段内偏移解引用」，Windows 既无 fd
继承语义，其句柄模型也无法表达后者；强行适配等于再维护一套平台专属 ABI
（C ABI 时代三套 ABI 并存曾导致改写型插件在某平台静默失效）。

- cmd/homed/platform_{windows,other}.go：原生 Windows 启动即拒绝并打印 WSL2 指引。
- internal/plugin/proc/shmalloc_windows.go：allocShm 直接返回「请用 WSL2」，
  **不返回半可用的段**（与 shmalloc_other.go 同风格：未支持平台显式报错）；
  procEnvForShm 返回 nil。顺手修掉两处长期编译错误
  （cryptorand→rand、h.evData→h.unified.evtData），使 GOOS=windows 至少能编译。
  注：homed 本就编不出 Windows——internal/memory 依赖 cgo-only 的 gojieba。
- deploy/packaging/installer.nsi：不再安装 homed.exe/initconfig.exe，改为携带
  **linux payload** 并调用新的 install-via-wsl.ps1；退出码 20/21 表示
  「需先装 WSL/发行版」，走指引而非报错。
- deploy/packaging/windows/install-via-wsl.ps1（新）：检测 WSL → 引导安装 →
  确保 WSL2 → 送包进发行版 → 在 WSL 内按 Linux 方式安装。**复用 Linux 包与
  linux/setup.sh**，不另写一套安装逻辑；落点与 deb 布局统一
  （/usr/bin/homed + /usr/lib/homeagent/setup.sh）。
- deploy/packaging/linux/setup.sh：API Key 允许 HOMEAGENT_API_KEY 覆盖
  （否则安装器界面显示一份、config.db 里另一份 → 登录不上）。
- deploy/packaging/build.sh：windows 目标只构建 waiter + gui，并新增
  stage_linux_payload 把 Linux 包暂存给安装器；homed/initconfig 在 windows
  目标下明确拒绝。

## 5. 插件调用点统一写明意图

- webui 的 OpenAI 兼容端点（固定提示词模板）→ InjectTextSyncNoMemory。
- agentcli 的 5 处纯状态通知（已启动/超时/执行结束/进程退出/读取结束）→ NoMemory；
  **带输出**的 2 处（定时反馈、有新输出）刻意保留记忆并注明理由。
- timer 的定时提醒 → NoMemory（中断本来也隐含 NoMemory，这里是写明意图）。

## 6. 版本

meta.Version 仍为 1.2.0（main 是下一个未发布中版本）；
SDKCompatibleVersion 1.1.0 → **1.2.0**（本内核已实现 SDK 1.2.0 全部新增方法）。

## 测试

- core：默认不裁剪（无声明/none/空）、通道 opt-in、注入点双向覆盖通道、
  nil context/io 安全、cleaner 优先级与未知名回退。
- io：零值 opts 与历史 payload 逐键相同；text/中断/媒体三类注入标志位都落到
  payload；旧方法仍生效。
- proc：validateContextPolicy 只接受 ""/none/prune，报错含位置与实际值；
  **跨进程** e2e——testdata 插件经 io.injectText 送出三个标志位，断言它们穿过 RPC
  到达内核。
- memory：模块缓存不可见时内嵌词库仍可用（分词与 POS 内容词均非空）、
  落盘幂等、内容哈希稳定。

验证：go build ./... / go vet ./... / go vet -tags onnxruntime ./...
      go test -short ./internal/memory/... ./internal/nlp/... ./internal/plugin/...
      ./internal/agent/{core,io}/... ./pkg/...
 2026-09-11 20:31:50 +08:00
JianFeeeee
3bfaa82a70 feat(sdk): 多模态贯通插件边界——公开接口、内核桥接与统一输入主干 
记忆系统在 1.1.0 支持了二进制多媒体节点，但那条链路只对**内核自己**开放：
用户在 qq 发图能落进 CAS、能被记忆引用，而插件调 Commit / DocMemory().Insert
交进来的媒体一律无处安放。原因是三层都断着，且**每一层都不报错**。

## 一、公开 SDK：补上媒体的表达能力（全部新增，无签名变更）

- `Triple` += `SentenceText`、`MediaDigests`
- `Doc` += `MediaDigests`、`Attachments`；新增 `MediaAttachment`
- `TextEvent` += `Attachments`
- `DocMemoryAPI` += `InsertWithMedia`
- `IOInjector` += `InjectInputMedia` / `InjectInputMediaSync` / `InjectInterruptMedia`
- `PluginSDK` 补上一直缺失的 `SetToolBlocks` 包装（接口里有、便捷方法里没有）

`MediaAttachment` 一个类型服务两个方向：给 `Data`+`MIME` 是新内容（CAS 按字节
去重），只给 `Digest` 是引用已有内容。读路径**只回元数据不回字节**——一次检索
可能命中几十份媒体，全塞回去会把跨进程消息撑爆。

媒体注入不能搭 `SetToolBlocks` 的车：那个方法只在工具处理函数内部可用，且媒体
要等下一条 tool message 才到模型手上。插件主动发起一轮带媒体的对话、以及中断
注入，需要自己的签名，且媒体在**本轮**就送到模型。

## 二、内核桥接层：原先在静默裁字段

`internal/sdk/memory_impl.go` 此前只搬自己认识的几个字段，其余丢弃且返回 nil：

- 图记忆丢 `Confidence`/`SubjectType`/`ObjectType`/`SentenceText`，又走 `Commit`
  而非 `CommitWithMedia`（不回 sentenceIDs）→ 媒体绑定链 `SentenceText → sentences
  → sentence_id → media_refs` 一步都走不通，插件即便按格式写好标记也永远挂不上；
- 知识库 `Query` 只回 ID/Title/Content，`Insert` 只写这三个；`Remove` 不解引用，
  于是那些媒体永久处于「被引用」状态，GC 收不掉、磁盘只增不减
  （内核的归档路径 `releaseDocMedia` 做了这一步，插件路径漏了同一步）。

规则改为：**内部结构有的字段一律透传**。标记格式处理作为包级私有辅助留在桥接
层自己手里，但必须与内核 `mediaSummaryForEvent` 字节兼容——两边要能互读对方
写下的标记。

标记插入必须在 `ds.Insert` **之前**（向量索引取 `Summary + " " + Content`，
之后补的标记检索不到），引用绑定必须在**之后**（owner_id 是 Insert 生成的 ID）。

## 三、跨进程链路：不接线就是全体外部插件编译失败

`go test` 直接把这一层拍出来了——`procIO does not implement sdk.IOInjector`。
公开接口加方法后，生成模板不跟上，**每个外部插件都编不过**，是硬失败不是软降级。
六处接线：`protocol.go` 四个 method 常量、`capability.go` 能力归属、
`corehandler.go` 四个分派分支、`proc_core.go` 委托、`proc_main.go.tmpl` 模板侧
实现、以及三个测试替身。

## 四、统一输入主干：把模态从「函数选择」降级为「字段」

`processTextInput` / `processMediaInput` 合并为 `processInput`。这个分叉是历史
产物而非设计：`processTextInput` 本来就处理媒体（`bindEventMedia` +
`mediaSummaryForEvent`，与媒体路径尾部完全相同），`process()` 只看
`stageCtx.Extra["media_blocks"]`、根本不认识 `evt.Type`。模态是输入的**属性**，
不是输入的**种类**。

媒体路径由此获得它一直缺的六项：去重、`no_memory`、通道 `Cleaner`、中断语义、
`_consolidation_` 路由、正确的 `EventRawInput`。

最后一项是个真 bug：媒体路径发布 `"content": evt.Payload`（一个 map），而
`webui/handler.go` 断言 `.(string)` → 断言失败、`content == ""`、提前返回。
**用户发的图从来没出现在 WebUI 聊天记录里。**

`media_blocks` 同时接受 `[]agentAPI.ContentBlock` 与 `[]pubsdk.ContentBlock`：
字段一致但 Go 不自动转换，只认一种的后果是另一种被静默丢弃。

## 五、模型可调用的三个工具

`memory_commit` 的 `sentence_text` **从未暴露给模型**，而它是绑定链上的必经环节；
连同 `media_digests` 一起补进 JSON schema 与工具文档。`doc_commit` 加
`media_digests`。`doc_query` 把关联媒体单独一行附在结果末尾（正文按 2000 字截断，
标记通常就在尾部）。

标记由**内核**生成而非插件/模型拼装：要求调用方知道格式，等于让一个拼写错误
静默切断引用绑定，而全链路无人报错。

## 六、WebUI 上传走真实媒体链路

图片/音频读回字节拼 data URL 注入 `media_blocks`（8MB 上限，超限退回按路径处理）。
此前只注入一句「文件已保存到 <路径>」，指望模型自己调 `files_read`——但那返回
文本，图片字节对模型永远不可见。附件类型识别扩展到 audio 并在缺 Content-Type
时按扩展名兜底（判错不只是卡片样式问题，图片被当普通文件就进不了视觉链路）。

## 测试

- `internal/sdk/memory_impl_test.go`（12 例，此前该包**没有任何测试文件**）
- `internal/agent/core/inputunify_test.go`（统一主干 + 双静态类型 + 三工具媒体）
- `third_party/homeagent-sdk/sdk/stress_test.go`（13 例并发压测）

压测抓到两处**真**竞态（不是理论风险）：`PluginSDK` 的 API 字段与 `autoRestart`
无锁，而写方（内核注入 API、插件 `SetAutoRestart`）与读方（插件后台 goroutine
注入、内核 registry 读 `AutoRestart`）天然跨 goroutine。加 `apiMu` 修掉；约定
只在持锁期间取字段值，取完即释放再调用——持锁调用会把 `InjectInputSync` 这类
阻塞到 agent 回复（可达数分钟）的方法与 `SetIOInjector` 串起来，让插件重载卡死。

测试还抓出两个自身缺陷：`bindDocMedia` 把同一份媒体数两次（`AddRef` 幂等所以表
是对的，但日志说「绑定 2 个」而实际 1 条——误导后续排查），以及用单字符实体名
时 `validEntityName` 静默跳过、`Commit` 返回 nil 却什么都没写。

存量插件不需要改一行也不需要重编：新增方法由插件调用、内核实现，不调就不受影响。
17 个 example 插件源码零改动通过类型检查。
 2026-09-06 09:51:31 +08:00
JianFeeeee
199e25797e fix: WebUI 版本显示 + Windows 交叉编译 + 发布脚本三处回归 
## WebUI 版本链路修复

问题：handler.go:949 报的是 sdk.SDKVersion，那条链最终指向
SDK 仓 meta.Version 的硬编码值，与 -ldflags 注入的内核版本
完全不相交。构建时间、commit hash 全部丢失。
dashboard.html 兜底值是 '0.1.0'——碰巧版本号相等时不显眼，
一旦不等就报错。

修复：
- KernelStatus 新增 BuildStatus 字段（Version/Commit/BuildTime/SDKCompatible/KernelName）
  取自 internal/meta（-ldflags 注入点），与接口冻结无关（KernelStatus 只在 internal/sdk）
- /api/v1/status 改用 meta.Version，另加 sdk_version 字段暴露 SDK 版本
- dashboard.html 概览卡显示 HomeAgent vX.Y.Z + commit/日期/SDK 兼容版本，
  去掉 || '0.1.0' 误导性兜底

## Windows 交叉编译修复

问题：internal/plugin/dynamic_proc_windows.go（Part 1 的桩，6b47d18）只定义了
tryLoadProc，但平台中立的 registry.go 还在调 loadProc / closeProcHost——这两个
函数只在 dynamic_proc_unix.go 里。Windows 下整个 homed 从 Part 1 起编译不过。

plan.md §12.5 声称「Windows 只做了交叉编译，无真机验证」——实际是连编译都没通过。

修复：dynamic_proc_unix.go / dynamic_proc_windows.go 合并为平台中立的
dynamic_proc.go（文件内无任何平台专属调用，proc 包内部通过
shmalloc_* / evtfd_* / shmpass_* / procattr_* 各自带构建标签处理差异）。

## 发布脚本三处回归修复

deploy/packaging/build.sh（从 package/build.sh 移到 deploy/packaging/ 后）：
1. PROJECT_ROOT 少一层目录（.. → ../..），产物落进 deploy/build/ 而非根目录
2. initconfig 从未被构建，但 installer.nsi 和 package-linux.sh 都引用它
3. GO 兜底路径指向 /home/jianf/go1.26.5（陈旧硬编码）改为 command -v go
4. electron-builder --config package.json 校验整个文件导致 devDependencies 被判为 unknown
   property，去掉 --config 让它从 build 键读配置

deploy/packaging/package-linux.sh：
1. build_go() 补上 initconfig 构建步骤
2. GO 兜底路径同步修复

知识库 3 条重写 + 1 条新增：
- homeagent_identity：v0.9.0 C ABI → v1.0.0 子进程
- homeagent_architecture：全篇重写为子进程架构（三面通信、Supervisor 台账、
  崩溃自愈、权限三道闸）
- homeagent_recent_updates：在 v0.9.0 前插入 v1.0.0 主线摘要
- changelog_v1.0.0（新建）：6 类缺陷消除、架构、实测、已知限制、迁移指引
 2026-09-03 15:38:31 +08:00
JianFeeeee
ca09184a66 revert(webui): 移除 chat/history 的 lean 裁剪模式 
工具调用详情（args/result）与 reasoning_content 是排查问题和还原上下文的
关键信息，不应裁剪下发。瘦身只保留分页一条路径（limit/before 控制条数）。

- 删除 lean 查询参数与 leanChatMsgs()
- 删除 ChatToolCall.Truncated 字段
- 分页仍生效：limit=40 首屏 1287.9KB → 48.5KB，且 tool_calls args/result
  与 reasoning_content 完整下发
 2026-08-28 23:38:11 +08:00
JianFeeeee
4905252f06 perf(webui): /chat/history 分段懒加载 + lean 瘦身模式 
问题：/api/v1/chat/history 无分页返回全量 1.26MB（200条），移动端/弱网首屏很慢。
实测体积构成：tool_calls args/result 占 71.8%，reasoning_content 11.6%，content 仅 3.4%。

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

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

实测：无参数 1287.9KB / limit=40 48.5KB / limit=40&lean=1 26.0KB；
before 游标翻页、limit 越界/非法值、before=0 等边界均正确
 2026-08-28 23:21:13 +08:00
JianFeeeee
f67aa1ffe9 fix(plugin): DisablePlugin 禁止禁用未安装插件，防止脏写 disabled_plugins 
问题：POST /api/v1/plugins/<name>/disable 对不存在的插件也会把它写进
disabled_plugins 表（registry.go DisablePlugin 无条件 AddDisabledPlugin），
产生脏数据堆积，且同名插件日后真实安装会被误判为已禁用。

修复：
- registry.go 新增 pluginInstalled(name)：已加载 / 已注册工厂(内置) / 插件目录存在，
  任一命中视为已安装
- DisablePlugin 开头校验：未安装返回 'plugin X not installed'，不写 disabled_plugins
- webui handler：未安装→404，已禁用→409（原都返回500）；enable 失败含'failed'→404
- 新增 registry_disable_test.go：覆盖未安装拒绝/内置判定/目录存在判定/普通文件不算

本机端到端验证：disable 不存在插件返回404且表无脏数据；真实插件 disable/enable 正常
 2026-08-27 23:29:49 +08:00
JianFeeeee
6081285935 feat(webui): 请求IP日志记录中间件 
- clientIP(): 提取真实客户端IP，优先 X-Forwarded-For(取第一跳) / X-Real-IP，回退 RemoteAddr
- logged(): 最外层中间件，覆盖全部路由，记录方法/路径/IP/认证方式/状态码/耗时
- 认证方式判定: api-key(X-API-Key/Bearer) / session(cookie) / none
- SSE长连接(/chat/events)启动即记，不阻塞等待完成
- statusWriter 捕获响应状态码，支持 Flush/Hijack 透传
- 用于排查'谁调用了什么接口'（如插件禁用等变更操作）
 2026-08-27 23:04:48 +08:00
JianFeeeee
a5bb4cf4ce fix(webui): SSE消息同步不及时 + 后端缓冲加固 
handler.go:
- writeCh 512→2048，新增 sendSSE() 函数（100ms短超时重试替代立即丢弃）
- After(id) 为空时发送 sync_required 事件通知前端补拉历史
- 批量 flush 阈值 64→128

dashboard.html:
- 新增 syncChatFromHistory()：增量同步，仅追加新消息DOM节点，不重建已有消息→无闪烁
- 监听 sync_required 事件触发增量补拉
- SSE onerror 立即 close 阻止双连接竞态，2s后手动重连（原5s）
- init 顺序：先 loadChatHistory 再 connectSSE（避免事件与历史加载竞态）
- 30s轮询兜底（补偿SSE断连窗口期丢失的跨渠道消息）
 2026-08-27 11:10:53 +08:00
JianFeeeee
f9fb735991 fix(webui): /files/ /uploads/ 静态路由接受 X-API-Key 鉴权 
requireWeb 此前只认 cookie session，ArkTS/GUI 等 API key 客户端
加载 agent 输出的附件 URL（/files/xxx、/uploads/xxx）一律 302 到
/login。现 requireWeb 先校验 validAPIKey 放行非浏览器客户端；
无凭证仍 302 登录页，行为不变。

handleFiles/handleUploads 已有严格防穿越（拒 / \ ..），暴露给
key 客户端安全面可控。

端到端验证：X-API-Key 访问 files/uploads 均 200，无凭证 302。
 2026-08-26 18:54:26 +08:00
JianFeeeee
88ac45dad3 fix(webui): SSE writer 批量合并 flush 修复流式 delta 丢包延迟 
【根因】SSE writeCh 缓冲仅 64 且 writer 每条 delta 单独 flush。
reasoning/content 增量是高频小包（单轮 200+ 条），socket
写慢时 writeCh 迅速填满，delta 大量 DROPPED——浏览器收不到
逐 token 增量，只能等最终 agent_output 整段到达，体感明显延迟。

实测一轮 16s 纯文本回复：content_delta DROPPED 202 次、
reasoning_delta DROPPED 345 次，前端全程无流式渲染。

【修复】
- writeCh 缓冲 64 → 512
- writer 加 16ms 批量合并窗口：窗口内收集的增量一次性 flush，
  或满 64 条立即 flush；done 退出前 flush 残留。
  flush 次数从 N 降到约 N/64，socket 写压力骤降。

修复后实测 0 DROPPED，delta 全部实时送达前端。
 2026-08-26 17:59:33 +08:00
JianFeeeee
b16fc9737a fix(webui): 附件死锁 + qq 插件文件发送收敛到 output 通道 
1. webui 附件死锁修复（output_send__webui 发图 60s 超时根因）
   EventAgentOutput 订阅者已持 chatMu，附件分支调 addChatMsg（内部
   再次 Lock）——sync.Mutex 不可重入导致 Publish 永久阻塞，工具超时、
   图片永远发不出来。改为持锁状态下直接操作 chatHistory+persist。

2. qq 插件 image/file 分支收敛到 output 通道
   output_send__qq 的 type=image/file 此前只透传 payload 给 CQ 码，
   发本地文件必须绕道 upload_group_file 独立工具。现在与 voice 分支
   同模式：本地路径拷入 NapCat 共享目录转 file:///app/files/<name> URI，
   http(s)/file:// URL 保持透传。upload_group_file 保留作为群文件柜
   专用入口。

验证：工具链重编译 → qq.hmap 重打包 → pluginmgr overwrite 安装
（config_kept=true）→ agent 经 output_send__qq 用本地路径发图成功，
mascot.webp 已落共享目录。
 2026-08-26 11:14:03 +08:00
JianFeeeee
7bd8ac831d fix(cmd/files/webui): shell 语义修复 + 根沙箱误判 + 上传注入走 interrupt + UI 区分附件来源 
1. cmd_run 改经 /bin/bash -c 执行完整 shell 语法
   旧实现 shellUnquote 拆词后直接 exec：'pwd; ls /' 变成执行名为
   'pwd;' 的程序（exit -1）、heredoc 被截断、管道/命令替换全部失效——
   agent 多次反馈命令解析奇怪即此。危险命令拦截（kill homed 等）保留。

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

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

4. 前端附件卡片按 role 区分来源
   user=右侧+『你发送的』标签+accent 底色；assistant=左侧+『小宅发送的』。
   📌 emoji 按钮换为 SVG 图标，前端 emoji 清零。
 2026-08-26 10:24:47 +08:00
JianFeeeee
052479a0ed fix(webui): 附件消息历史持久化 + 用户文件上传（对齐 qq 插件收文件设计） 
1. 附件展示链路补全
   - ChatMsg 新增 Attachment 字段（type/url/size/name），channel_output
     订阅提取 output_type/url/size 存档——修复刷新后附件变纯文本路径
     （如 '/tmp/homeagent.png'）的问题
   - EventRawInput 订阅支持 upload_* 字段：用户上传的消息也带附件卡片

2. 用户→agent 文件上传（POST /api/v1/chat/file）
   设计对齐 qq 插件收文件模式：
   - multipart(file + message) 落盘 <data>/uploads/<原文件名>（重名加
     毫秒后缀，路径穿越消毒），单文件上限 64MB
   - 注入文本「[用户通过 webui 发送了图片: 名字 (大小)] + 保存路径」，
     agent 用 files_read 等工具按路径消费
   - 回复走与普通消息相同的 SSE 流式管道
   - GET /uploads/<name> 下载，与 /files/ 同一鉴权与安全模型

3. 前端
   - 输入区 📎 按钮；拖拽到聊天区直接发送；粘贴截图即发送
   - 本地预览用 URL.createObjectURL 即时显示
 2026-08-26 10:03:46 +08:00
JianFeeeee
4bf8d825e3 feat(webui): agent 可向 webui 发送图片/文件，前端内联展示与下载 
输出通道能力升级：webui 通道从 CapText(1) 扩展为
CapText|CapFile|CapImage(7)，agent 经 output_send__webui 即可发送
image/file（此前仅文本）。

服务端：
- stageWebFile 把本地路径文件拷贝到 <data>/webui_files/<hex>.<ext>
  （随机名防猜测、危险扩展名强制 .bin），http(s) URL 直接透传不落盘
- 新增 GET /files/<name>（requireWeb 与 dashboard 同鉴权）：扩展名
  白名单映射 Content-Type，图片/音视频 inline、其余 attachment 下载，
  nosniff + 路径穿越拒绝
- SSE agent_output 事件携带 output_type/url/size 字段

前端（dashboard.html）：
- channel_output 识别附件消息：image 渲染内联预览（点击原图）、
  file 渲染下载卡片（含大小）；formatBytes 人性化显示

典型场景：agent 把 remotedevice 回传的录像/截图（device_media/*.mp4）
直接发给 webui，用户在聊天里看到视频预览或一键下载。

新增 TestStageWebFileAndDownload / TestHandleFilesAuth 覆盖。
 2026-08-26 09:17:07 +08:00
JianFeeeee
f18587a01c fix(remotedevice): 媒体回传落盘 + webui SSE panic + GUI 相机跨平台 
1. remotedevice 媒体落盘（核心改动）
   设备录像/照片二进制聚合后写入 <data>/device_media/<reqID>.<ext>，
   cmd_result 返回 file 路径，不再 base64 内联——10s 录像数 MB 的
   base64 会撑爆 LLM 上下文与工具结果管道。未配置目录时保持旧内联行为。
   新增 TestWSBinaryMediaToFile 覆盖。

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

3. GUI camerasue 平台分支
   ffmpeg 参数原硬编码 Linux v4l2(/dev/video0)，Windows 上必然失败。
   现按平台探测：win32=dshow(枚举设备名取第一个视频设备)、
   darwin=avfoundation、linux=v4l2；录像编码 Windows 交给 mp4 muxer 默认。
 2026-08-26 01:25:40 +08:00
JianFeeeee
618f51a136 fix: 流式渲染回合生命周期 + LLM 瞬断重试与 SSE body 兜底 
问题一（webui 不是真流式）：
- sendChat 的 finally 在 POST 结束(15s ackTimer abort)时就复位
  chatLoading，但 agent 生成窗口 15~190s，后续 SSE delta 全部走
  全量重建路径、停止按钮提前消失、用户误发重复消息。
- GUI app.js 完全没有 content_delta/reasoning_delta 监听器，
  只能等聚合帧一次性显示。

修复：三端统一回合生命周期——POST 只是触发，收尾由 SSE 驱动：
- dashboard/GUI 新增 endChatTurn/armTurnWatchdog；拿到同步兜底
  响应立即收尾，否则保持回合打开等 agent_output final / reset 帧 /
  120s watchdog 兜底
- GUI 补齐 delta 监听器；agent_output 聚合分支 += 改覆盖；
  reasoning 聚合帧改覆盖（多轮工具调用时旧逻辑会重复累加）
- agent_output 误杀分支（final 无 source 即 return 丢弃新输出）
  改为内容比较去重，多轮连发时新一轮回复不再被吞
- waiter reasoning_delta reset 从清空全部消息改为 sealLastAgent

问题二（三条只成功一条）：
- handleChat 60s ctx 含排队时间，agent 串行处理下第 N 条必超时
  （实测第 3 条 62s 超时 504）；放宽到 300s（客户端 abort 时立即取消）
- LLM 单 provider 瞬断无重试：process.go provider 循环内加同源
  重试（2 次、退避 2s），401/403 凭证错误与用户中断不重试
- llmsproxy auto 链在非流式请求下可能返回 SSE body（上游恢复后
  吐已生成的 chunk 流），非流式解析报 invalid character 'd' 丢掉
  整段回复；新增 parseOpenAICompatibleSSEBody 拼接为完整响应
- 顺带修 normalizeStreamToolCalls 分片续传 bug：name 不重发时
  argsRaw 被顶层 Arguments(nil) 覆盖丢失 function.arguments

验证：
- 连发 3 条 + 单条共 4 条全部成功（首条 190s 重试扛住瞬断）
- sse_body_test.go 锁定 SSE body 解析契约（content/usage/tool call 分片）
 2026-08-25 12:24:11 +08:00