jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-11-01 14:57:38 +00:00
Code Issues Packages Projects Releases Wiki Activity
858 Commits 5 Branches 29 Tags
4e70b8d5d8a38cf6c7927c275ca50ee1fd7d5fcb
Commit Graph

12 Commits

Author SHA1 Message Date
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
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
69c9a9613f feat(webui): 星图切到块体系数据源 + 全部标名/灰调/读写反馈/三种变化动画 
## 根因：记忆系统已迁移，前端没跟上

`GraphData()` 同时返回两套数据，而前端**只读旧的**：

    nodes/edges                ← 旧表 entities/relations（2026-10-04 停写）
    memory_blocks/block_edges  ← 块/边体系（真实活跃的记忆）

生产实测：`entities` 停更在 2026-10-03（1294 条），而 `memory_blocks`
同期从 1294 涨到 3187。写入函数 `upsertEntity` 已成**全仓零调用的孤儿**。
⇒ 星图结构性看不到任何新记忆。

（另修的同类问题：`starmapDirty` 只写不读且未声明，赋值成隐式全局 ⇒
即使后端发事件，新块也永远不会出现在图上。见下「判据」。）

## 数据源切换

新增 `smAdaptGraph()` 把块/边归一化为星图节点/边（字段与旧格式一致，
下游建图/布局/图例/脉冲无需各自判源）：
- `mention_count` 回填为**度数**（块表无此列，而它驱动节点大小/标签优先级）
- 只画 `status` 为 active/空 的边（deleted/merged 的边留着会让失效关系看着还在）
- 端点缺失的边丢弃（画不出，且会让度数统计偏大）

## 视觉（按「全部标名 + 灰调 + 悬浮提亮 + 查询提亮 + 三种变化动画」）

**全部节点名**：新增标签覆盖层 —— **一个** 2D canvas 画全部名字，而非
每节点一张 CanvasTexture（原实现 1151 张 ≈ 72MB 显存，也是它当初被删的原因）。
三级可读性：活动/悬浮=实色+底块，其余=低透明当底纹；**同屏文本去重**
（3178 块里大量同文本块，不去重会叠成十几层同样的字）。
仅在相机或脉冲集合变化时重绘。

**灰色调**：`smGreyFor()` 全图灰阶，**亮度按度数**（亮处即记忆稠密处）。
原按类型上色对真实数据只用得上一种颜色（99% 同一类型）。

**悬浮提亮**：发光 +1.4 + 放大 1.25×（只放大不亮在淡底上不明显，只亮不放大
又看不出是哪颗）。

**查询提亮**：`memory_access` → `starmapPulseByIDs()`，按**真实块 ID** 精确命中。

**三种变化动画**（三种是**排他状态机**，不与可叠加的活动 pulse 混用）：

| 动画 | 曲线 | 时长 |
|---|---|---|
| 插入生长 | easeOutBack 过冲（从 0.05 起，从 0 起看不出「长」） | 1800ms |
| 删除消散 | 收缩 + 变暗 + 球面均匀粒子飞散（减速淡出） | 1200ms |
| 合入 | 源消散 → **停顿 120ms** → 目标重生 | 1200+120+900ms |

合入刻意分两段且中间停顿：同时放会读成「一个变小一个变大」，
先看不到源、再看到目标冒出，「合入」的因果才成立。
粒子用**单个** Points 承载（上限 600），而非每粒子一个 mesh ——
批量删除（Purge 上百块）时后者会瞬间建上千对象。
消散完成必须真 `scene.remove()`，否则 scale=0 的不可见 mesh 仍可被鼠标拾中。

**顺带**：
- 补选中详情面板（`starmapSelected` 此前**只赋值、无人读取**，点击节点
  没有任何信息反馈 —— 「可读性差」的核心成因之一）
- 布局半径按 √n 自适应 + 相机初始距离自适应（3178 节点挤在旧的固定
  15–80 环带里会糊成一片）
- 图例改为说明**视觉编码**（大小/亮度/活动/三种动画），不再列不存在的类型色
- `starmapDirty` 消费点加 30s 节流（`/memory/graph` 实测 3.3MB，
  密集写入时每 10s 重拉是纯浪费）

## 判据

- `graph_source_test.go`：钉住后端**必须下发 memory_blocks**
  （前端星图的真实数据源），防未来又切回停写的 nodes
- `TestDashboardJS_NoWriteOnlyGlobals`（新增静态判据）：**只写不读的全局布尔标志**
  ⇒ 这类「置了标志无人消费」是静默失效，真跑 node 也抓不到（隐式全局赋值合法）。
  该判据写出来就当场抓到 `starmapDirty`，并经变异验证有效
  （删掉消费点 → 判据点名报错）
- `node --check` + webui 全部判据绿
 2026-10-08 10:41:22 +08:00
JianFeeeee
f53b42efa5 fix(obs): 抢占日志改在判决点打（修自伤）+ scheduler 事件接进 SSE 
## 修我上一版的自伤

上一版把 preempt 日志打在 `executeNewTask`，但那时 `nextRef` 已经把
`s.running` 换成了抢占者自己，于是输出成了

    preempt start: task#2 ... -> victim task#2 (cli)

victim 打印的是入侵者本人。判据必须落在 `registerInterrupt`——那一刻
running 还是真正的受害者。改为在抢占判决点打：

    [agent] preempt: task#2 class=interrupt level=3 from cli (L3) preempts task#1 class=queued level=0 (qq)

## 补上「入队而非抢占」的日志

中断到了却没生效，此前完全不可解释。现在两种成因分开写：

    [agent] interrupt queued: ... vs ... (qq) — running in critical section; queue=N
    [agent] interrupt queued: ... vs ... (qq) — preempt cooldown; queue=N
    [agent] interrupt queued: ... vs ... (qq) — level insufficient; queue=N

没有这条，`interrupt from X` 打过之后任务为什么没让位就只能猜。

## scheduler 事件接进 SSE

`EventScheduler` 此前既不在 `handler_chat.go` 的 subTypes、也没有任何订阅者
（全仓 grep 零命中）——内核里 suspend/resume 只 publishEvent，于是事件发出来
就掉地上，对内对外都不可见。加进 subTypes 后前端/客户端能看到抢占链。

## 验证

- preempt_logging_test.go 增一条：victim 与入侵者必须是不同来源（qq vs cli），
  且排队输入对排队任务 `canPreempt` 必为假。
- 实测输出含 `cli (L3) preempts task#1 class=queued level=0 (qq)`。
- 全量 `go test ./internal/... ./cmd/...` 与 `go vet ./internal/...` 全绿。
 2026-09-19 11:57:50 +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
JianFeeeee
0e69af1d9f feat(webui): 总览改版 —— 阶段管道滑块 / per-agent 负载环 / 通道→agent 拓扑与光点 
总览页此前是一堆数字与文字块，看不出「这一轮走到哪、谁忙、消息从哪进哪出」。
本次把运行态面板改成以图形为主：

- 阶段管道：七阶段滑块，由 SSE stage 事件驱动，当前阶段高亮、滑块滑过去；
  一轮结束（after_output 或 2.5s 无事件）自动回到空闲，不做假动画。
- 队列与中断栈：沿用五条进度条（L1–L4 + 排队），中断栈补一条深度进度条。
- Agent 拓扑：改成「每 agent 一条横带」——左 inputch、中 agent 节点（圆环 = 负载）、
  右 outputch，连线即路由；删掉旧的「归属框 + 单个内核盒」画法（看得出哪个子接了哪条输入）。
- 光点动画：channel_input（新增轻量 SSE 事件）沿 inputch→agent 连线跑；
  agent_output 沿 agent→outputch 连线跑。用 SMIL animateMotion，不需要 rAF 循环。
- 负载：由该 agent **自己的**调度器积压（排队 / 四级中断 / 中断栈）按级别加权折算，
  环形图展示。为此把驻留子的调度器积压透出到状态面（SDK 纯追加字段）。

后端：sdk.ResidentStatus / core.ResidentInfo 增加子 agent 调度器积压四项；
WebUI SSE 增加 channel_input 轻量事件（只带通道名与 agent id，不带正文）。

顺带收口对话区视觉（页签改分段控件、消息间距/气泡区分、输入区分隔线）。
 2026-09-14 15:33:23 +08:00
HomeAgent Agent
da499625fb fix(webui): 聊天记录不再"每次都发完整记录"，并修掉视口跳顶 
两个都是你指出的症状，都定位到了具体代码路径。

① 「每次都发完整聊天记录」
   a) API 缺省值错了：/api/v1/chat/history 的 limit 缺省是 0 = **不限制**，
      于是任何不带 limit 的调用每次都拿到整段记录。实测（126 条）：
      不带 limit 635,297 字节；现在默认只回一页 180,668 字节。
      显式 limit=0 仍可整取（逃生口）。WebUI/GUI 本来都带 limit，不受影响。
   b) 前端 30s 轮询（以及每次 SSE 报错）都直接拉一页 40 条：
      浏览器实测单次 180,813 字节。现在先做"尾巴探测"（limit=1，362 字节），
      尾巴一致就直接跳过；不一致才拉整页。

② 「聊天记录会跳到顶部」——两条会导致视口丢失的路径都堵上
   a) syncChatFromHistory 在"找不到重合点"时直接 `state.messages = serverMsgs`：
      服务端只回一页，而本地可能已经向上翻了好几页；一覆盖，容器立刻变矮，
      视口被夹回顶部，用户翻过的旧消息也凭空消失。现在只在服务端页**不短于**本地时
      才整体替换。
   b) renderChat 全量重建 innerHTML 后，仅在粘底时滚到底；非粘底（用户正在向上读）
      时位置没人管。改为重建前记住 scrollTop、非粘底时原样还回去。

浏览器实测（CDP 驱动真实页面，126 条历史）：
  * 15s/30s 定时器跑满 40s：聊天区滚动位置 **0 px 变化**，未跳顶；
  * 期间 chat/history 请求：limit=1 × 2（各 362 字节）+ 首屏 limit=40 一次；
  * 控制台无报错；新增消息后轮询仍能正确并进来（尾巴探测→拉整页→合并）。

测试：新增 TestChatHistoryDefaultIsPaged（默认一页 / has_more / limit=0 整取 / 显式分页）。
顺带修测试串味：迁移用例往 os.TempDir() 写共享历史文件，会让其它用例的
NewHandler 加载到脏历史（表现为条数多 1）；现在各用例用自己的临时文件。
 2026-09-14 08:06:16 +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