25 Commits

Author	SHA1	Message	Date
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	50ef27891f	fix(clients): 三方客户端与内核的 SSE 协议一致性 —— 幽灵类型、发了没人收、客户端漏接 ... 一次三方（CLI/GUI/鸿蒙）与内核的协议审计，发现四处**全部静默**的不一致 （无任何测试或日志会报），本次一并修复并把它们变成可执行判据。 ## 四处不一致 1. `agent_error` 是**幽灵类型**：SSE 白名单订阅了它、鸿蒙还写了处理分支 （显示「本轮处理失败」），但全仓**无任何发布者** —— events 包与 SDK 都 没有这个常量。于是那段分支永远不可达，而真正的失败帧叫 `error` （webui/cli 都发 `{type:"error"}`），鸿蒙从未接住。 2. `system` **发了没人收**：internal/plugin/dynamic_proc.go 一直在发插件崩溃 （注释还写着「webui/诊断插件可订阅」），却不在 SSE 白名单里 ⇒ 事件发出来 就掉地上，插件崩溃对用户完全不可见。 3. CLI 缺 `stage`/`system`：CLI 是唯一看不到阶段进展的客户端，agent 跑长任务 时终端长时间静默，用户分不清「在干活」还是「卡住了」。 4. 鸿蒙设备桥**静默丢弃**：只处理 bind_ack 与 cmd，服务端下行的 push / cmd_speech_start / cmd_speech_end / hello_ack 直接 return —— 「收到了但不支持」与「根本没收到」在日志上完全一样，无从排查。 ## 修法（注意：三方客户端的通信模型不同，清单不可一刀切） CLI 走 InjectTextSync **同步拿最终回复**（response 帧）+ 事件订阅做过程输出， **不做 SSE 重连** ⇒ 它需要 stage/tool_call/reasoning/delta， 但**不需要** agent_output（正文来自同步回执）与 sync_required（那是 SSE 断线重连专用的补拉信号）。GUI/鸿蒙是真 SSE 客户端，两者都需要全量对话事件。 第一版判据按同一份清单要求三者，误报了 CLI —— 那是判据的错，不是代码的错。 - handler_chat.go：subTypes 删 `agent_error`、补 `system` - dashboard.js / ChatSse.ets：补 `system` 消费（WebUI 用 toast，鸿蒙用 setStage） - ChatSse.ets：幽灵分支 `agent_error` 改为真实类型 `error` - cli/plugin.go：补 `stage`（过滤 `_consolidation_`）与 `system` 订阅 - cmd/waiter：补 Phase/Event/Plugin 字段与 stage/system 渲染 - DeviceBridge.ets：静默丢弃改为带 hilog 日志（区分「不支持」与「没收到」） ## 判据（internal/plugins/webui/handler_sse_protocol_test.go，7 条） TestSSESubTypesAreRealEventTypes（幽灵类型）/ TestEveryPublishedEventHasAnOutwardPath（发了没人收，例外须显式声明理由）/ TestClientsRecognizeServerEventTypes（按客户端分档）/ TestNoPhantomFrameTypes / TestStageFrameFieldsMatchServer / TestSseWhitelistParsesToExpectedSet（**解析器反向自检** —— 解析器失效会让整组 判据静默变成空集并全绿，是最危险的假绿）/ TestDeviceBridgeOpCoverage。已接入 `make check-client-protocol`（进 make test）。 变异 M1–M8 全部验证。其中 M5 首轮未报红：判据只查前缀 `json:"phase`， 把 tag 改成 `phaseX` 仍匹配 ⇒ 改为匹配**完整 tag** 后才咬住。 ## 端到端实测（不只看测试绿） - 真实 SSE 流收到 stage×15 / content_delta×111 / memory_access×3 / agent_llm_chain / tool_call×2，**agent_error 0 次**（幽灵已清） - kill 一个 plugin.bin → SSE 收到 `event: system` `{"event":"plugin_crashed","plugin":"a2a"}`，日志确认「自动重启 a2a」 - WebUI 真弹出 toast「插件 acp 异常退出，内核正在重启它」（MutationObserver 捕获）	2026-10-13 16:20:28 +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	9e69637117	feat(waiter): 设备命令白名单改为 waiter.yaml 可配置 ... ## 起因 白名单是源码里硬编码的正则（`homeagentAllowCmd`，18 个命令）， 而 `waiter.yaml` 里**没有任何键能改它** ⇒ `find` / `grep` / `sed` / `sort` / `tr` 这些排查问题最常用的**只读**命令一律被拒。生产实测： device_ctl_cmdrun device_id:waiter-fnnas error: command not in whitelist 命令执行完全在 waiter 侧（`device.go` 的 `exec.CommandContext`），插件侧无二次 限制；触发者是 **agent**（经 device_ctl_cmdrun），所以这道闸是机器闸、不是人工确认。 ## 改动 waiter.yaml 新增 `device_cmd_allowlist`（字符串数组）： device_cmd_allowlist: - ls - find - grep - sed - **替换**默认集而非追加：避免"以为加了 find、结果还留着 python3 -c 任意执行" - 留空 ⇒ 用内置默认集（★ **绝不能变成"全放行"**，那等于静默拆掉闸门） - 匹配只取命令名**第一段**再整词匹配：`grep -rn x .` 能过， 而 `grepXxx` / `mygrep` 不会因 contains 蒙混过关；也跳过 `FOO=bar cmd` 的赋值前缀 - `deviceCmdAllowed` 是包级函数变量，由配置赋值 —— 与同文件既有的 `sendBridgeResult` 同一模式 ## ★ 一次真实的疏漏（判据记着） waiter 有**两条**设备桥启动路径： - `main.go` 的 `startDeviceBridge` —— 交互/一次性模式 - `daemon.go` 的 `startDaemonDeviceBridge` —— `waiter --daemon`（**生产两台都这么跑**） 我最初只在 `main.go` 里赋值。daemon 路径不经过那里 ⇒ 配置**完全不生效**， 而症状是"配置写了、启动也打了招呼、命令照样被拒"，极难定位。 两处都接上了，并加 `TestDaemonPathAppliesAllowlist` 守住。 ## 判据（5 条） - `TestDefaultAllowlistStillBlocksDestructive` 默认集必须挡住 `rm -rf /`、`dd`、`chmod -R 777`、`mkfs`、fork 炸弹 —— **这道闸存在的唯一理由**，谁把它改成"什么都不拦"这条就要失败 - `TestConfigAllowlistExtends` 配置里声明的 `find/grep/sed/sort/tr` 能过； 配置未含的 `rm -rf /` 仍被拒（证明是"替换"不是"叠加"） - `TestEmptyConfigFallsBackToDefault` 配置为空时回退默认集，**且不放行** `rm -rf /` - `TestCmdAllowlistFromYAML` 走**真实** `readFile` 解析 yaml（不另写一份解析， 两处会漂移，而漂移本身就是漏洞） - `TestDaemonPathAppliesAllowlist` 守住 daemon 路径也应用配置 ## 生效方式 106/30 的 `/opt/waiter/waiter.yaml` 追加 `device_cmd_allowlist`， 并更新二进制。启动日志会打印 `device cmd allowlist: N 条（来自 waiter.yaml）` 或 `默认 N 条`，便于确认配置是否真的被读到。	2026-09-27 19:41:43 +08:00
JianFeeeee	0110d72bff	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	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	46ce92618c	chore(version): 客户端版本与内核对齐（唯一事实源 internal/meta.Version） ... 此前三份版本号互不相干：内核 1.4.0、GUI 1.0.0、鸿蒙 1.1.1。手工各改各的 必然漂移，所以把「对齐」做成机械动作而不是约定： - deploy/scripts/sync-client-versions.sh：从 internal/meta.Version 读版本， 同步 cmd/gui/package.json 与鸿蒙 AppScope/app.json5（versionName + versionCode=X*1e6+Y*1e3+Z）；--check 给 CI/Makefile 做漂移门禁。 - Makefile 新增 sync-client-versions / check-client-versions；build-cli 也注入 LDFLAGS，waiter 与 homed 同版本。 - 鸿蒙：新增 common/AppVersion.ets，从 bundleManager 读安装包 versionName， BridgeProtocol/BridgeCaps 里两处硬编码 '1.1.1' 改为读它——版本只剩 app.json5 一份，杜绝第二真相。 - waiter：`-version` 打印版本，启动横幅与设备桥 hello 的 version 字段 直接引用 internal/meta，与内核天然同源。 对齐后：GUI 1.4.0 / 鸿蒙 1.4.0(1004000) / waiter 1.4.0 / 内核 1.4.0。	2026-09-15 11:03:26 +08:00
JianFeeeee	88934ea98e	feat(waiter): daemon模式 + localuse本机外设插件 ... waiter 新增 --daemon 后台驻留模式 (daemon.go): - 维持 homed 连接，TUI实例经 Unix socket 接入 - 单客户端串行模型：每个TUI独占homed响应，新客户端回放缓冲(256行) - 设备桥场景可无 homed 运行（纯设备桥驻留） - 设备桥看护循环：WS断开自动重连(3-5s间隔) - conn.go 新增 daemonConn 类型，dial() 优先检测 daemon localuse 插件 (internal/plugins/localuse/): - local_screensee / local_camerasue / local_speakeruse - local_screensue / local_clipboardsee / local_clipboardsue / local_computeruse - 跨平台实现(Linux/macOS/Windows)，能力与 waiter device.go 对齐 - headless服务器上缺依赖工具自动返回安装提示 SDK sync: third_party SetToolBlocks 多模态类型同步 README 补充 daemon 模式使用文档	2026-08-27 09:27:15 +08:00
JianFeeeee	91eff27b0a	feat(streaming): token-level delta events + interrupt for CLI/WebUI/GUI ... Expose the LLM token-level streaming deltas (EventReasoningDelta / EventContentDelta) to every client channel and add user-initiated interrupt (cancel generation / send interrupt message) to all three frontends, preserving the existing interrupt-injection semantics. SDK/events: - EventReasoningDelta, EventContentDelta constants exported in the public/internal SDK event alias tables. CLI plugin: - handleChat subscribes to both delta events and forwards reasoning_delta / content_delta JSON frames (channel-filtered); aggregated reasoning/tool_call/response frames still fire as before. - New /stop (alias /interrupt) builtin injects an interrupt via InjectInterrupt(cliSource, cliChannel) - matches interceptLoop semantics: cancels an active stream and re-injects the message as a [中断消息] for a restarted turn; with no active LLM it behaves as a plain input. Waiter client (line mode + TUI): - streamRender accumulates delta chunks and redraws the current line; a reset frame (stream abandoned, e.g. user interrupt) flushes the partial buffer so the next turn does not concatenate onto stale content. Aggregated frames terminate the delta line and render the final text (old servers without deltas behave exactly as before). - TUI merges content_delta into the in-flight agent message and seals it (final flag) on response/tool_call/error so subsequent deltas never append to a finished message. WebUI: - SSE handler subscribes to the two delta events but does NOT record them into the replay ring - reconnection replays only aggregated events (the final truth), avoiding duplicate delta accumulation. - POST /api/v1/chat/interrupt calls InjectInterrupt(webui, webui) with optional message; fronted by a Stop button shown only while a generation is in flight. dashboard.html / GUI app.js: - Stop button next to Send (hidden until chatLoading); interruptChat POSTs /chat/interrupt. Delta listeners append incrementally; agent_output (aggregated) now replaces (not appends) the in-flight content and marks _final; reset frames finalize the partial message. process.go: - chatStreamWithFallback preserves the context.Canceled/ DeadlineExceeded contract: a user interrupt returns the canceled error (never a partial-content success) so the existing continue branch restarts the turn with the [中断消息]. A reset EventContentDelta is published so connected clients drop stale partial renderings before the new turn begins. Verified: /stop 'msg' via waiter triggers 'interrupt from cli/cli' in interceptLoop; unit TestChatStreamCancelPreservesInterrupt confirms the canceled error propagates instead of being swallowed.	2026-08-25 10:50:37 +08:00
JianFeeeee	c834d93d8a	feat(waiter): Bubble Tea TUI modernization ... Replace the line-based REPL with a full-screen Bubble Tea TUI in interactive mode (non-TTY still falls back to the line editor). Layout (deveco-code inspired, no emoji): - Top status bar: HomeAgent brand + connection dot + mode + addr - Scrollable chat viewport with role-based rendering: You (purple) user messages 小宅 (orange) agent responses · reasoning dim gray italic, streaming-merged [ok]/[fail] tool calls with status + truncated result [sys] builtin command output [err] errors - Rounded-border input box with placeholder - Bottom status bar: spinner while busy / hints + connection state Key design points: - reader generation counter prevents stale errors from the old reader being mistaken for the new one after reconnect - handleSubmit always returns waitServer when reader is alive, so server responses to builtin commands like /status are received - History stored as *History (was copying sync.Mutex by value) - Chinese CJK wide-char aware word wrap with hanging indent - /clear /exit /quit handled in TUI; other /cmds still go through handleBuiltin with output captured to message area Verified via tmux PTY: /help, /status, /clear, real chat with LLM (reasoning -> tool_call -> response chain all render correctly).	2026-08-25 01:01:22 +08:00
JianFeeeee	c5c7985366	fix: bump llm http client timeout 120s→180s for llmsproxy AUTO chain failover ... The local llmsproxy AUTO chain tries 6+ slots across 3 tiers sequentially. Each failed tier incurs busyWait (2s) + upstream timeout, so a full chain exhaustion can exceed 120s. The llmsproxy logs showed 143 'context canceled' errors for the homeagent key — the client gave up before the chain finished. 180s gives the chain enough room to complete before the client timeout fires. Also remove stale backup files under /usr/local/bin/.	2026-08-25 00:34:25 +08:00
JianFeeeee	e3f63f145b	feat(cli): streaming process output with npm-style spinner ... CLI 对话现在像 npm 安装一样先显示 braille 加载动画，然后逐步吐出 推理内容和工具调用状态，最后输出最终响应。 协议扩展（JSON 行，向后兼容）： - {"type":"reasoning","content":...} 推理过程帧 - {"type":"tool_call","tool":...,"status":...,"result":...} 工具调用帧 - response / error 仍为终结帧，语义不变 服务端（internal/plugins/cli）： - handleChat: 通过 SDK 订阅 EventReasoning/EventToolCall（按 channel=="cli" 过滤），InjectTextSync 阻塞期间实时转发事件到 socket；connWriter 互斥 保护并发写。纯插件层实现，不触碰内核。 - 不订阅 EventAgentOutput：内核先写 ResponseCh 再 publish 该事件， 订阅会导致响应重复。 客户端（cmd/waiter）： - startSpinner: npm 风格 braille 转圈（80ms），幂等 stop()，非 TTY 自动禁用 - SendChatStream: 循环读帧直至终结帧，onEvent 回调渲染过程帧 - printServerOutput: reasoning 灰色 · 前缀；tool_call ✔/✘ 状态行 + 结果预览 - 交互模式发送后自动起 spinner，首帧到达即停；oneshot 同理 - 向后兼容旧服务器（无类型行直接作为最终输出） 端到端验证：本地 homed 测试实例 + llmsproxy，oneshot 与交互模式均正确 渲染 推理→工具调用→最终响应 完整链路。 另外修正 dashboard.html renderReasoningCard 流式态使用 preview 结构 （与 GUI 渲染器一致，配合此前 renderChatStreamChunk 增量更新）。	2026-08-24 23:34:48 +08:00
JianFeeeee	17a2c7b7ee	feat: 设备鉴权迁移至客户端 + 插件卸载保护 ... 安全修复（客户端鉴权）： - remotedevice 服务端移除授权状态存储（authorized map/SetAuthorized/handleDeviceAuth） - DeviceMeta.Authorized 改为设备 hello 自报，服务端仅透传展示 - device_ctl_* 工具移除服务端授权检查，无条件转发，设备端自行决定是否执行 - 共享设备桥库 Bridge 新增本地 authorized 状态，未授权收到 cmd 直接拒绝 - waiter: --device-authorized / device_authorized 配置控制本地授权 - GUI: 授权存 gui-prefs 本地文件；设备页仅本机可切换开关 - webui /device/auth 旧路径返回 410 Gone - 根因：agent 可经 config_set 篡改服务端授权配置自行授权设备 插件管理强化： - 内置插件禁止卸载（IsBuiltinPlugin + 409），外部插件卸载即时生效 - 卸载不存在插件返回 404；移除误导性 reload_required 提示 - webui 插件路由：名称白名单校验防路径穿越、保留字路径保护	2026-08-24 19:26:11 +08:00
JianFeeeee	b0d6f10522	feat: 设备桥共享库 + CLI全能力补齐 + GUI omniparse/computeruse 重构 ... - 抽取设备桥 WS 协议层为共享库 (internal/devicebridge/client/) - CLI 补齐 11 项 caps 能力(screensee/screensue/speakeruse/camerasue/...) - GUI 新增 omniparse 能力(Windows UIA 窗口解析) - GUI computeruse 改用 koffi 直接调用 user32.dll，不再依赖 PowerShell C# 编译 - GUI computeruse JSON 解析兼容非标准格式 {x:500,y:300} - 新增 mock-server 用于本地测试设备桥协议 - 新增 GUI DLL 桥接模块 (devicebridge_dll.js)	2026-08-23 20:17:38 +08:00
JianFeeeee	c36ac7e3a2	device gateway: remotedevice 插件(设备接入网关) + GUI/waiter 受控设备桥 + 设备页/授权开关/托盘/退出进托盘 + 白屏修复(惰性Tray) + deviceinfo 工具	2026-08-17 09:34:25 +08:00
JianFeeeee	bec39a3285	feat: add package/build.sh cross-platform build script ... - build.sh supports linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, windows/amd64, and 'all' for matrix build - Components: homed (CGO, Linux/macOS-only), waiter (all platforms), gui - Platform matrix documented in script header - waiter: extract setRawMode into rawmode_linux.go + rawmode_other.go for cross-platform support - Add cmd/gui/node_modules/ and dist/ to .gitignore - Fix .gitignore waiter pattern to not ignore cmd/waiter/ directory	2026-07-19 11:40:14 +08:00
JianFeeeee	eca81f2943	feat: waiter connection manager - save/switch/delete connections, auto-apply default	2026-07-16 21:42:23 +08:00
JianFeeeee	3a7136c4b8	feat: align GUI and CLI with WebUI - move GUI to cmd/gui/, add REPL+mgmt to waiter, enhance GUI features	2026-07-16 20:28:56 +08:00
JianFeeeee	5e80db52f5	feat: restructure plugin system, add Lua plugin support, update docs	2026-07-13 21:48:13 +08:00
JianFeeeee	1259e587c3	fix: correct context pruning order and vector alignment ... - Prune context BEFORE processing (LSTM forget gate pattern) so LLM only sees relevant context, instead of pruning after the fact - Fix ensureTrained() to recompute all event vectors after retraining vectorizer, fixing feature-space mismatch between stored vectors and query vector that made relevance scoring effectively random - Add read lock to knowledge BuildTree() (data race fix) - Log writeIndex() errors instead of discarding them - Fix TOCTOU race in document ContextToDoc() dedup - Fix healthcheck timing (measure elapsed before cleanup) - Refactor waiter CLI into separate files (state, conn, config, editor, history, builtin) for maintainability - Add CLI plugin API key authentication	2026-07-07 17:07:38 +08:00
JianFeeeee	fec5cf56ec	feat: add waiter -chat one-shot mode ... - Add explicit -chat flag for blocking one-shot requests - Keep -say as deprecated alias for compatibility - Preserve existing interactive mode for upcoming TUI rewrite	2026-07-06 21:52:57 +08:00
JianFeeeee	1641336ca0	feat: expand local operator controls across CLI and WebUI ... - Add structured CLI commands for status/kernel/settings/plugins/memory/knowledge/agents - Inject core dependencies directly into CLI plugin for non-HTTP operator workflows - Add plugin management panel and API proxy endpoints to WebUI - Let cmd_run inherit default workdir from core.agent.workdir - Use fixed loopback address for pluginmgr API - Remove stale MaxToolTurns config usage from homed wiring	2026-07-06 20:32:04 +08:00
JianFeeeee	b35cf53fb2	feat: 路径配置化 + 裸二进制启动 + pluginmgr 内置插件 ... - types.go: 新增 PluginDirConfig 结构体嵌入 Config - config/registry.go: 新增7个路径配置项 (core.plugin.dir 等) + ConfigDef 元数据 - cmd/homed/main.go: -data 默认自动检测二进制同级目录，使用 cfg.Plugin.Dir - internal/plugins/pluginmgr/: 内置插件实现 (4工具 + HTTP API + 包校验) - all.go: 注册 pluginmgr - manifest.go: 扩展 PluginManifest 字段 - sdk/settings.go: RegisterDef / Defs 接口 - webui: 设置页自动发现 ConfigDef 元数据 - config/config.go, config/config.yaml: 清理 YAML 死代码 - sdk/plugin.go: IO 通道泛型化支持非文本类型 - waiter: CLI 支持 socket 发现和交互模式	2026-07-04 16:56:32 +08:00
JianFeeeee	4a09e358ae	IO 抽象层增强：非文本输入支持 + waiter CLI 重写 ... PluginSDK: - 添加 InjectInput / InjectInputSync / InjectInterrupt 泛型接口 - 插件现在可注入 image/audio/file 等任意类型输入 Provider: - 添加 ContentBlock / ImageURL / AudioURL 类型 - Message 增加 Blocks 字段，Content 在非空 Blocks 时序列化为数组（多模态格式） Agent: - handleInput 新增 image/audio 类型分发 → processMediaInput - processMediaInput 将媒体数据附着到对话上下文，LLM 自主决策处理策略 - 新增内置工具：describe_image / transcribe_audio / ocr_image（pendingMedia 驱动） - 工具仅当有未处理媒体数据时注册，通过 Provider 直接调用多模态模型 Config: - 新增 InputProcessingConfig（image/audio 处理配置） - 含 fallback_provider / describe_prompt / ocr_enabled 等选项 Waiter CLI 重写: - 配置文件 ~/.config/homeagent/cli.yaml（自动发现 socket） - 原始终端行编辑 + 命令历史持久化 + 彩色输出 - 内置命令：/help /reconnect /connect /remote /local /prompt - 断线自动重连	2026-07-04 15:01:35 +08:00
JianFeeeee	33db5f3a40	重构: 插件自注册 + .so 动态加载 + 中断打断机制 ... - 所有内置插件 init() 自注册 (plugin.RegisterFactory), 移除 main.go 硬编码 - 新增 .so 动态加载器 (internal/plugin/dynamic.go), 插件可编译为 plugin.so - 新增 plugin.json 元数据 (internal/plugin/manifest.go) - 新增 interceptLoop 独立 goroutine: (a) cancelLLM() 取消进行中的 HTTP 请求 (b) interceptCh → drainInterrupt() 注入 [打断消息] 到 LLM 上下文 (c) InjectInput 空闲时触发新处理循环 - 新增 internal/plugins/all.go 空白导入触发所有内置插件 init() - internal/sdk/ 作为 PluginSDK 正式 Go API - internal/api/ → internal/plugins/webui/ 迁移 - 删除旧 cmd/cli/, 使用 cmd/waiter/ 替代 - 更新 PLAN.md / ARCHITECTURE.md / README.md 文档	2026-07-03 16:53:34 +08:00