jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-11-01 06:47:29 +00:00
Code Issues Packages Projects Releases Wiki Activity
835 Commits 5 Branches 29 Tags
ecffb8a7de256324f446b33698a4aa652338355b
Commit Graph

835 Commits

This Branch
This Branch
All Branches
Author SHA1 Message Date
JianFeeeee
ecffb8a7de test(plugin): InjectOptions 含 map 后不可比较，改逐字段验零值 
Payload 字段（map[string]interface{}）加进 InjectOptions 后，
结构体不再可比 ⇒ `z != sdk.InjectOptions{}` 直接编译失败
（invalid operation: struct containing map cannot be compared）。
 2026-10-18 18:30:04 +08:00
JianFeeeee
aad8ddbf1e fix(core): output_send 的 stage 补 Extra 与 after_output 
## 缺陷（2026-10-18 实测定位）

`before_output` 被两个语义共用：

	emitResponse（eventloop.go）   = 一轮的回复，turn 边界
	output.go                      = 单次 output_send__* 的工具输出

**真正把消息发出去的是后者**，而它构造 stageCtx 时连 Extra 都没初始化：

	stageCtx := &sdk.StageContext{
		FinalText: payload,
		Phase:     sdk.StageBeforeOutput,
	}

诊断日志实证：`[qq-dbg] before_output: input_source="" qq_uid=<nil> extra_keys=0`

后果：通道插件在"消息即将发出"这个最需要上下文的时点，什么都读不到。
QQ 的「对方正在输入中」因此一次都没能触发。

## 修法

Extra 补三个键：

	output_channel  目标通道（插件据此判断"是不是发给我的"）
	output_meta     本次发送的 meta 原文（user_id / group_id 在里面）
	output_type     text / image / file / voice

## 同时补上 after_output

这是"消息真的送达"的时刻，但此前只有 before_output。没有配对收尾，
插件只能等自己的超时（QQ 那边是 30 秒）—— 用户看到指示器挂很久。

阶段顺序：before_output（可改写 payload/拦截）→ Execute → after_output。

## 为什么 after_output 放在 Execute 成功之后

失败时不发 after_output：消息没送达，"发出后收尾"的语义不成立，
提前触发会让插件误以为已经发出去（进而在状态跟踪上记错）。
 2026-10-18 18:01:15 +08:00
JianFeeeee
70f7bea4b9 feat(io): InjectOptions.Payload 业务字段扩展，透传到本轮 stage 
## 为什么需要

QQ 的「对方正在输入中」必须只在**自己引起的** before_output 里发，且要
知道发给谁。但两条路都断了：

	on_input 的 stageCtx  是局部变量（stageCtxFromInput），runStage 完就丢
	before_output 的 stageCtx 是内核**新建**的（emitResponse）
	⇒ 两者**不共享 Extra**

## 第一版是错的（用户指出）

我先加了 `InjectOptions.Meta` —— 那是把同一件事做了两遍。用户直接问：
「为什么又额外定义了 injectMeta，而不是包含在 inputch 的请求体中？」

查证后的真实边界：`InputEvent.Payload` **本就是通道送入内核的请求体**，
身份信息本该在那里。但 `IOInjector` 接口全是
`(source, channel, text, opts)`，插件无法给 payload 加字段 —— 所以
payload 需要一个**扩展口**，而不是一个平行的新概念。

改名为 `Payload` 还有一个实际好处：所有注入路径（HTTP/CLI/ACP）共用
同一套机制，不是注入专属。

## 内核怎么处理

	注入点 opts.Payload
	  → 与真 payload 合并（**内核保留键不可覆盖**）
	  → emitResponse 把非保留键原样透传到 stageCtx.Extra

保留键清单 `reservedPayloadKeys` 覆盖注入路径自身写入的键
（no_memory/context_policy/recall_policy/scene_policy/cleaner_name/
priority/type/content）与内核读取的语义键。允许覆盖意味着插件能伪造
"这条不记记忆"或"这条要立即打断"——那是权限提升，不是便利。

拦截方式是**跳过**而非拒绝整次注入：插件可能只想带一个业务字段，
因顺手多写一个保留键就让整条注入失败，代价太大。

## 判据（4 条，变异 2/2 咬）

 · 插件字段原样进 payload
 · 保留键不可覆盖（逐个验证 11 个键）
 · 空 Payload 不改变旧行为
 · 保留字清单必须覆盖注入路径自己写入的键（否则新键=新提权面）

## 附带修掉的编译破坏

`internal/plugin/lua_surface_test.go` 用 `z != sdk.InjectOptions{}` 比较
零值 —— 结构体含 map 就**不可比较**，加了 Payload 后直接编译失败。
改为逐字段验证。
 2026-10-18 17:40:07 +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
6a15b80ee9 revert: 撤掉多余的 auto_start 门（调度器早已处理） 
## 为什么要撤

c426921 我以为"外部插件的 auto_start 完全不生效"。**判断错了。**

实机验证：13 个声明 auto_start=false 的插件在重启后确实没加载
（建链 22 → 11）。靠的是**既有机制**，不是我加的门：

	internal/kernelboot/scheduler.go:277  canLaunch: if !p.AutoStart { return false }
	internal/kernelmod/pluginhost/mod.go  buildSkipSet: catalog 里的插件全交给调度器
	internal/kernelmod/pluginhost/catalog_test.go:198  判据已覆盖

我当时只看到 `Load` 遍历目录时不查 auto_start，就断定该字段不生效 ——
那只是**没看到另一条路径**（LoadSkipping + 调度器分层）。

## 为什么必须撤而不是留作"兜底"

· 两处逻辑重叠：调度器按 catalog 决定跳过，我的门在 loadOne 里再判一次。
  两处各说各话，将来改一处漏另一处就是新的静默不一致。
· 我那条判据测的是**我自己加的门**，不是真实行为 —— 它变绿不证明任何
  产品行为正确（撤掉这道门，判据红，但产品行为不变）。
· **没验证过的防御就是噪音。**

## 撤回后行为不变

按需加载链路实测（weather）：
	plugin_start → loaded=true / alive=true / pid=838963
	plugin_stop  → loaded=false / alive=false，pid 消失
	两者都 persistent="未改动"（不动持久禁用清单）

这些都发生在**没有**我这个门的旧二进制上。
 2026-10-18 13:36:16 +08:00
JianFeeeee
59f7001932 fix(security): 工具输出与参数会原样写进日志 —— 落盘前脱敏 
## 缺陷

两处日志把工具内容原样打印，没有经过 security.Replace：

	task.go:1038  log.Printf("[agent] tool %s result: %s", ..., truncateStr(result, 100))
	task.go:967   log.Printf("[agent] tool %s raw_arguments: %s", ..., truncateStr(tc.RawArguments, 300))

实测场景：enc_shell 跑 curl 拿到 200，响应体里带着上游 key 的完整值
（`{"key":"sk-..."}`），这一行直接写进 /home/newqqagent/log/homed_*.log。

## 为什么日志泄漏比上下文泄漏更严重

	模型上下文  短期——一轮结束就不再发送
	日志        长期——每天一个文件、从不自动清理，systemd journal 另存一份，
	                   排查问题时还会被贴进 issue

一次落盘就是永久泄漏。凭据轮换前，任何拿到日志的人都能直接用。

## 改动

 · 新增 scrubForLog(text, where)：唯一入口，空安全（Global()==nil 时原样返回）
 · 两处日志调用点都改为先 scrubForLog 再落盘
 · 拦截本身记一笔（只记模式与长度，不记原文），便于事后发现"哪个工具常吐凭据"

## 判据（4 条）

 · 明文被换成别名（真 Store，不用 mock）
 · 普通文本不被改动（不误伤）
 · Global() 为 nil 时不 panic（安全模块未启用是常态）
 · **接线**：两处调用点确实走了 scrubForLog（只测函数不测接线会漏掉原缺陷）

变异：scrubForLog 直接返回原文 → 咬；工具结果日志去掉 scrubForLog → 咬。
 2026-10-18 13:20:54 +08:00
JianFeeeee
d9c2e51f61 fix(agent): cancel 停不下调度循环 —— 队列非空时永远不看 ctx.Done 
## 缺陷（真缺陷，不是测试问题）

`schedulerLoop` 只在"队列空"的分支里 select `ctx.Done()`：

	if kind == nextNone {
		select { ... case <-a.ctx.Done(): return }
	}

于是**只要队列里有任务，循环就永远不看 ctx.Done** —— 一直取、一直执行，
直到队列被取空才可能退出。

生产后果（`reclaim` / `destroy`）：销毁流程先回收残余任务、再销毁子。
而回收到销毁之间子仍在运行，继续把队列里的任务取走执行 —— 那些任务的
结果**永远无人认领**（子随即被销毁），且日志无痕迹：既不在"残余清单"里，
也没跑到出结果。带 ResponseCh 的同步调用方（cli/a2a）更糟：Stop 的
drainPendingInterrupts 给它补一个 "skipped"，用户看到"已跳过"，
而任务其实执行过。

## 修法

1. `schedulerLoop` 循环顶部（**取任务之前**）检查 ctx.Done。
2. 新增 `waitSchedulerStopped`：cancel 之后等 running 归零（上限 5s，
   超时如实记日志，不让控制面永久挂住）。
3. 新增 `FinishResident`：停止调度 → 回收残余 → 处置 → 收割记忆 → 销毁，
   **一步完成**，消除"取完到销毁"之间的窗口。`reclaim` / `destroy` 改走它。
4. 记忆收割抽成 `harvestResidentMemory`，供 FinishResident 的 onDestroy 复用
   （必须在 Destroy 之前 —— Destroy 会关掉 temp）。

## 判据（2 条，都做了"撤销修复必须变红"的验证）

 · TestSchedulerStopsTakingTasksAfterCancelWithNonEmptyQueue
   用阻塞 provider 把循环钉在 executeNewTask 里，此时塞 5 条进队列、
   cancel、放行。修复在位 ⇒ 5 条一条都不执行；撤销修复 ⇒ 取走 5 条。
   **实测撤销后报「仍取走了 5 条（剩 0/5）」，恢复后 10/10 绿。**
 · TestFinishResidentIsAtomic
   断言返回后子已从登记表移除（销毁确实在同一事务内完成）。

原 flaky 的 TestResidualKeepReturnsTasksToParent 与
TestResidualDropNotifiesSyncCaller 也修了：先 cancel + 等静止再入队，
得到确定的初始状态（它们验的是转交逻辑，不是子的生命周期）。30/30 绿。

## 我踩过的两条弯路（都写进判据注释了）

1. 加 `scheduler.freeze` 绕过。错在：调度器本来就有停止语义（ctx），
   再引入一个状态位会让"谁负责停"含糊，且忘了解除就永久僵住。已删。
2. 判据第一版写成「先 Start、再 cancel、然后入队」—— 那时队列是**空的**，
   循环正好走 nextNone 看到 ctx.Done 退出，于是**撤掉产品修复判据依然
   30/30 全绿**。是用户追问"凭什么说修好了"才发现这是假绿。
   必须造出"队列非空时 cancel"这个确切场景才测得到。
 2026-10-18 13:07:40 +08:00
JianFeeeee
c426921847 fix(plugin): 外部插件的 auto_start 从未生效 —— 补三态启动门 
## 缺陷

`plugin.json` 的 `auto_start` 一路写得出来（hmapdev 打包会写），
但 **Load 的目录扫描从不读它**：`loadOne` 里只有持久禁用门与运行态门。
也就是说这个字段在**外部插件上完全不生效** —— 声明 `auto_start: false`
的插件照样开机自启。

（内置模块那条走 `kernelboot/scheduler.go` 的 `p.AutoStart`，与外部插件
是两条路，所以缺陷只暴露在外部插件上。）

## 三态语义（现在三条都成立）

	自动启动       auto_start 缺省/true  + 启动扫描   ⇒ 拉起
	启用但不自启   auto_start=false      + 启动扫描   ⇒ 跳过
	               同上                  + plugin_start ⇒ 拉起
	禁用           持久禁用清单          + 任何路径    ⇒ 拒绝（plugin_start 也拒）

★ `explicitStart` 是这次的关键设计点：`auto_start: false` 的含义是
"**别在开机时拉起我**"，不是"永远不许启动"。少了这个区分，
按需加载的插件就再也起不来了 —— 比不声明更糟。

## 判据（4 条）

 · auto_start=false 在启动扫描时被拦（且不调用 Start）
 · 同一插件经显式启动**真的加载并 Start**（plugin_start 可用）
 · 未声明 auto_start ⇒ 自启（不误伤存量插件）
 · plugin.json 读不到 ⇒ 默认自启（清单损坏不该让插件静默消失）

## ★ 判据第一版是假绿（变异不咬）

第一版直接断言 `loadOneOpt` 返回 true/false。但 **false 有两个来源**：
① 被 auto_start 门拦住（正确）② 没有 plugin.bin 加载失败（噪音）。
两者无法区分 ⇒ 删掉 auto_start 门后判据照样通过。

改成用 `RegisterNative` 注册一个**真能 Start 的**假插件：
返回 true 必然意味着门没拦它，返回 false 必然意味着门拦了它，语义唯一。
修完两个变异都准确咬住（删门 / 忽略 explicitStart）。
 2026-10-18 11:24:14 +08:00
JianFeeeee
53950e0388 test(pluginmgr): 钉住「插件必须走 plugin_install，不能手工替换二进制」 
## 我犯的错（2026-10-18）

改完 commondev 后我是这么"部署"的：

	python3 -c "zipfile...extractall('/tmp/x')"
	install -m 0755 /tmp/x/plugin.bin <插件目录>/plugin.bin
	install -m 0644 /tmp/x/rawfile/runtime/pi/sidecar.mjs <插件目录>/...
	systemctl restart homeagent

用户一句「为什么不打包为 hmap 安装，而是手动替换」点破了问题。

## 手动替换丢了什么

换成标准 plugin_install 后，返回：

	action: "reinstalled",  checksum: "13a46f87161d37c8…",
	config_kept: true,  skills_registered: 1,  reload_required: true

这个 checksum 正是 .hmap 的 sha256（实测一致）。而手工 cp 拿不到的东西：

 · **整包校验和** —— 包与落盘结果之间没有任何可核对的凭据
 · **备份 + 失败回滚** —— 手工 install 半途失败会留下半新半旧的目录，
   比彻底失败更难查（插件能加载、某个功能诡异失效）
 · **全量路径校验** —— validatePackage 遍历**所有**条目拒 `..`/绝对路径
   （该循环曾因 break 漏检 rawfile，已修）
 · **rawfile 全量解包** —— 我只覆盖了 2 个 sidecar，其余（node/pi 运行时）
   仍是旧的。证据：替换后 `rawfile/` 目录 mtime 停在 10-16，
   标准安装后整个目录 mtime 才变成 10-49
 · **配置保留与 skill 注册** —— config_kept / skills_registered 在返回值里

## 判据（2 条）

代码无法禁止人手工 cp，但可以把**唯一正确入口**钉住：

 · TestInstallKeepsBackupAndRollback：installFromData 必须仍有
   「备份旧目录 → extractPackage → 失败回滚」三件事
 · TestValidatePackageChecksAllEntries：路径校验必须遍历全部条目，
   且所在循环里不能有 break（历史缺陷：manifest 之后的条目漏检）

## 变异

去掉备份            → 咬（"安装不再备份旧目录 —— 失败就没法回滚"）
去掉回滚            → 咬
 2026-10-18 10:51:46 +08:00
JianFeeeee
9b2c74bc49 refactor(config): 默认值单一来源 —— ConfigDef.Default，不再各调用点重复硬编码 
## 起因（用户质疑）

我把 offload 的触发阈值从 5 分钟改成 1 分钟时，同一个默认值散落在四处：

	defaultOffloadBusyAfter = 5 * time.Minute     （agent/core 常量）
	set("core.agent.offload_busy_after", "5m")    （seedDBValues 播种）
	reg(ConfigDef{... Default: "5m" ...})         （seedCoreDefs 定义）
	GetDuration("...", 5*time.Minute)             （kernelmod 读取点）

用户问：「为什么不是单一从配置读取，而是硬编码在源码中？」

答：这不是合理的分层，是重复。同一份默认值四处字面量，改一处漏两处
就是**静默的行为漂移** —— 不报错，只是某些路径用 5m、另一些用 1m。

## 改动

**① 默认值的唯一来源 = ConfigDef.Default**

	GetInt/GetDuration/GetBool/GetString 新增 defDefault()：
	DB 里查不到行时，从已注册的 ConfigDef.Default 取，而不是用调用方传的字面量。
	调用点现在写 GetDuration(key, 0) —— 那个 0 只是「连 ConfigDef 都没注册」
	时的兜底，正常路径永远用不到。

**② 删掉 seedDBValues 里 54 行重复的 set()，改由 reg() 落库**

	reg() 原本只 `r.defs[k]=&d`（只登记不落库），默认值另由 set() 写一遍。
	现在 reg() = registerDefLocked（登记 + 落库）。
	为此抽出 registerDefLocked：SeedDefaults 已持 r.mu，直接调 RegisterDef
	会自死锁（sync.Mutex 不可重入）。

**③ 8 个键必须「只登记、不播种」，新增 regMeta()**

	core.agent.system_prompt              播种会把版本号冻死在 DB 里
	core.defaults.llm_endpoints           空默认值
	core.memory.multimodal_space.options.*  provider 私有选项

	第一版没有区分，一改就红了两条既有判据：
	  TestSeedDefaultsDoesNotSeedSystemPrompt
	  TestSeedDefaultsDoesNotInjectIntoLegacyInstall
	后者尤其重要：老安装升级被注入新默认值 = 静默加载 1.8GB 向量模型。

**④ seeded 集合：回退只对「本次真播种过」的键生效**

	这是修 ③ 过程中暴露的更根本的问题。GetXxx 无条件回退到
	ConfigDef.Default 会让**老安装**读到新版本的默认值 —— 即使 DB 里
	根本没有那一行。加了 seeded map 区分：
	  全新安装 → 键已播种 → 回退 ConfigDef.Default（正常）
	  老安装   → 新键没播种 → 返回零值（不注入）

## 顺带修的

offload_busy_after 的 Type 从 "string" 改成 "duration" —— 它本来就是时长，
用 string 时 WebUI 只能给文本框，拿不到时长控件。

## 判据

沿用既有判据，不新增。新写的 offload_threshold_test.go 已删除 ——
它断言「四处默认值必须一致」，方向是**鼓励重复**，与本次目标相反。
 2026-10-18 10:16:53 +08:00
JianFeeeee
ef08ebb7d3 chore(mascot): 立绘 v2 —— 真 alpha 素材 + 头部裁切头像 + 素材判据 
老大给的 4 张新立绘里有 3 张是「棋盘格假透明」JPEG（像素是灰白格子，
不是 alpha）。直接进仓库会在深色面板上露出格子，所以先抠成真 alpha 再落盘。

## 为什么主图与头像要分两个文件

现役 mascot.webp 唯一的消费点是**聊天消息的 30px 圆形头像**
（dashboard.js 4 处 aiAvatar + GUI app.js 2 处），概览页并没有放立绘。
主图是坐姿全身，按现有 CSS（object-fit:cover + scale(1.5)）裁成圆后
只剩裙子、看不到脸 —— 只换图不做头像版，等于把头像换成一张看不懂的图。

- assets/branding/mascot-xiaozhai.webp        1024² 主立绘（官方展示）
- assets/branding/mascot-xiaozhai-avatar.webp  512² 头部方裁（运行期源）
- internal/plugins/webui/mascot.webp           256² 头像版（原 133KB→24KB）
- cmd/gui/renderer/mascot.webp                 128² 头像版（原 133KB→9KB）

参考稿另存三张（不参与运行）：sheet（设定总图）/ portrait（半身）/
turnaround（三视图）。

## 抠图怎么做的（可复现，不是手搓）

背景是 20.45px 周期的棋盘格（237/254 两色）。判据取「中性灰 且 灰度≥228」
的像素做候选，再从图像边界做连通域传播 —— 这样白裙子/白围裙因为不中性
（带蓝调）不会被误判，避免了当年 site/README 记录的 flood-fill 渗色问题。
边界再内缩 1px 抹白边，0.7px 高斯羽化去锯齿。抠完透明占比 55.8%，
深/浅两种背景上目检均无残留格子与白边。

## CSS：scale(1.5) → 1.25

原来的 1.5 是为「全身图裁圆」补的放大。换成头部方裁后，1.5 会切掉两侧
发绳与呆毛 —— 按真实 30px 渲染放大对照看过 1.0/1.15/1.25/1.4 四档。

## 新增判据（含反向验证）

internal/plugins/webui/mascot_asset_test.go 直接读 WebP 容器头，
断言 VP8X 的 Alpha 标志位与 ALPH chunk **同时存在**，外加正方形/≥128px/
≤128KB。理由：这类退化在肉眼 review 里抓不住（缩到 30px 就是一团浅色），
而用户每天都在看；且 site/README.md 记着当年正因为「白底图没法抠」
干脆不放立绘，这个坑值得一个自动化判据。

反向验证（已实跑，非声称）：把素材换成 HEAD 旧图，判据报红并准确指出
「Alpha 标志位未置位 / 缺 ALPH chunk / 体积超限」；换回新图转绿。
另有一条独立用例构造「带 VP8X 但不置 Alpha 位」的最小容器，
确认解析器不会对退化素材误判为绿。

## 顺带修的两处

1. assets/docs/{zh,en}/PLUGIN_DEV.md 的 mascot 引用路径是坏的：
   `../../assets/branding/...` 从 assets/docs/zh/ 出发解析成
   `assets/assets/branding/...`，文件不存在（旧版一直是坏的）。
   已改为 `../../branding/...` 并逐条验证路径可解析。
   同时指向新的头像版（那处是 20px 圆形内联小图标）。
2. gzip.go / gzip_test.go 注释里的「mascot.webp（133KB）」改为不带死数字
   的说法 —— 体积会随素材变，注释写死数字只会变成误导。

## 验证

go build ./...            → 0
go vet ./internal/plugins/webui/ ./cmd/gui/ → 干净
gofmt -l                  → 空
go test ./internal/plugins/webui/ -count=1 → ok（15.1s，含新增 2 个用例）

## 没做的事

- 没碰 main、没开 PR、没部署、没重启服务。
- **概览页仍未放立绘**。site/README 里「素材不可用」这条已不成立（素材有
  alpha 了），但版面是否该放图属于设计取舍，不在本次范围 —— 文档已相应改写，
  不再用「素材不行」当理由。
- 抠图对发丝边缘是「够用」不是「完美」：0.7px 羽化在 1024 下看不出来，
  但若将来要印物料级大图，需要重出带原生 alpha 的源图。
 2026-10-18 07:38:10 +08:00
JianFeeeee
5a3a8f484b fix(agent): 工具超时不再一刀切 60s，支持工具自声明与按参数推导 
## 缺陷（2026-10-17 生产日志实测）

`toolcall.go` 里写死 `time.After(60 * time.Second)`，与工具自己的超时
**互相矛盾**且让内层形同虚设：

	23:13:38  执行 cmd_run（agent 传了 timeout="130" 级参数）
	23:14:38  ★ 内核 60s 硬超时掐断 → 「执行超时（60秒）」

同一份日志里 healthcheck 声明默认 120s ⇒ 被砍掉一半，天生跑不完。

## 改动

1. `ToolDef.Timeout` / `BuiltinToolDef.Timeout`：工具自己声明单次上限。
   留空 = 沿用 60s（存量插件**一行不改，行为逐字不变**）。

2. 内核取 `max(声明值, 调用参数 timeout)`，再夹到硬上限 10m：
   · 声明修好固定时长的工具（healthcheck 5m）
   · 参数推导修好时长可变的工具（cmd_run 的 timeout 参数）
   · 硬上限防插件声明成 0/无限把队列堵死

3. 非法声明（"130" 少单位、0s、负数）**回退默认并记日志**，不静默接受。
   写错单位是最容易犯的错，默默变成 60s 会让人以为"声明没生效"却查不出。

4. healthcheck 声明 5m（它的 llm_timeout 默认就是 120s）。

★ 没有把 timeout 放进 `ToSchema()`：那份 map 是**发给模型**的 function
  schema。把内核的执行参数混进去，模型会以为需要自己传 timeout 参数。

## 判据（6 条）

未声明→60s / 声明生效 / 参数参与取 max / 参数比声明小用声明 /
非法回退 / 超上限夹住。变异全部咬住。

## 附：这条路只治「工具真的需要更久」

向开发线投递（output_send__*）的两次 60s 超时**不是这个原因** ——
那是 commondev 把"投递"实现成了"同步等任务完成"，已在 SDK 仓修成异步。
这里没有给 output_send 放大超时：投递应该瞬时返回，慢是 bug 不是需求。
 2026-10-18 06:38:51 +08:00
JianFeeeee
683f0126af test(webui): 内核按钮必须真的出现在**渲染后**的页面里 
## 为什么需要这组判据

dashboard.html 与 dashboard.js 都是 `//go:embed` 进二进制的，再由 init
组装成 dashboardHTML（替换 {{DASHBOARD_JS}} 等占位符）。这里有两个
**各自都可能坏掉**的环节：

 1. 按钮写进了 dashboard.html，但占位符没被替换 / 替换错位
    ⇒ 页面里看不到按钮
 2. JS 函数写进了 dashboard.js，但被包在 IIFE 里（不在全局）
    ⇒ onclick="kernelRestart()" 点了报 "kernelRestart is not defined"

只查源码里有没有那个字符串，这两种情况都照不出来。

## 判据（3 条，都查组装后的 dashboardHTML / embed 源）

 · TestKernelButtonsRenderedInPage：渲染后的页面含两个按钮的 id 与 onclick
 · TestKernelFunctionsAreGlobal：4 个函数必须是**顶层**定义
   （浏览器 onclick 走全局查找，jsdom 的行为测试做不到这点）
 · TestKernelButtonsInNavFooter：两个按钮必须落在 nav-footer 内
   —— 它们作用于整个服务，切到任何标签页都该能点到

实测：渲染页面 408057 字节，六项断言全在。

顺带把 dashboard.js 的格式化差异一并提交（-w 对比为空的纯格式调整）。
 2026-10-17 21:26:12 +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
134cd860b6 fix(webui): 聊天受理超时 15s 太短，误报「已取消（用户停止）」 
## 内测用户报告

发一句话，界面回「已取消（用户停止）」，而且连着出现多次。

## 实测真相（用户提供的日志）

    20:58:36  POST /api/v1/chat 开始，agent 开始干活
    20:58:48  agent 仍在跑（terminal_create / terminal_read）
    20:58:52  ★ 前端 15s ackTimer 到点 → ctrl.abort()
              → 服务端记 status=504，耗时 15.89s
    20:59:29  ★ agent 正常跑完，52.5 秒、22 个工具、返回 response

也就是说：**agent 从来没有被取消过**。它一直在正常干活并跑完了，
只是前端自己掐断了连接，回复没法送回，UI 就把"我没等到"显示成了
"用户停止"——一个用户从没做过的操作。

## 根因

`sendChat()` 里把"受理确认"的等待写死 15 秒，而 agent 的正常任务
动辄 45-55 秒（工具越多越久；同一份日志里另一次是 45262ms）。

这个 POST 本来就是**触发式**的：真正渲染靠 SSE 流式（`armTurnWatchdog`
兜 120 秒）。在受理环节抢时间没有任何意义，只会误伤正常任务。

## 改动

1. **超时 15s → 600s**：不再用固定短超时。保留上限只为兜住
   "连 TCP 都建不起来"这类真故障，避免请求永远挂着。

2. **文案改掉**：原来 abort 后提示「请求超时（可能已发送）」，
   红字 error 样式。用户看到"超时"会以为消息丢了而**重发** ——
   实测会造成同一句话产生两条任务。改为：
   「已发出，AI 正在处理（复杂任务可能要一两分钟）。请等待回复，不要重复发送。」
   并且不再用 error 样式（这不是错误）。

## 判据（2 条，源码扫描）

 · `TestChatAckTimeoutIsGenerous`：超时 ≥ 5 分钟
   （实测正常任务 45-55 秒，留足余量）
 · `TestChatAckTimeoutMessageDoesNotBlameFailure`：提示不得出现
   "失败/超时/Error/failed"，必须说清"正在处理"且提醒"不要重发"

变异 2/2 咬住（改回 15s / 改回"请求超时"文案都当场变红）。

★ 为什么用源码扫描而不是行为测试：这是前端 abort 时序，没有可注入的
  时钟。扫描至少能防住"有人把 15s 改回来"。
 2026-10-17 21:16:49 +08:00
JianFeeeee
662d5472ee fix(agent): 安全装饰器吃掉 provider 的模态能力声明（see_image 失效根因） 
## 现象

调用 see_image 工具是通的、图片也确实注入了，但内核回：

    当前模型不支持图片，且没有可用的视觉回退源

而配置明明是 `core.llm.sources.llmsproxy.vision = true`，后端也确实支持看图。
用户以为是配置没热生效、以为要重启，实际都不是。

## 根因：一条完整的静默失效链

    vision=true（配置是对的）
      → LuaAdaptedProvider.Vision = true
      → ProviderManager.Register 把它包成 *secureProviderDecorator
        （security.Global() != nil 时无条件包装）
      → ProviderSupportsVision(p) 做 p.(ModalProvider) 断言
      → ★ 装饰器只实现了 Name/MaxContextTokens/Chat/ChatStream，
          **漏了 ModalProvider 的 SupportsVision/SupportsAudio**
      → 断言失败 ⇒ 返回 false
      → prepareToolBlocks 判定"主模型不支持图片"
      → see_image 的 image_url 被当成需要回退的块
      → resolveModalFallback 找不到可用视觉源
      → 「没有可用的视觉回退源」

装饰器只该**改写请求内容**（明文→别名防泄漏），不该改变能力声明。

## 修法

透传给内层：内层实现了 ModalProvider 就照实转，否则 false（不 panic）。

## 判据（4 条）

`internal/agent/api/provider_security_modal_test.go`：
 vision 透传 / audio 透传 / vision=false 不得被污染成 true / 无 ModalProvider 不 panic

★ 我第一版判据是**假绿**的，值得记下来：
 `WrapProviderForSecurity(p, nil)` 在 store==nil 时**直接返回原对象**
 （见其实现），所以根本没包装，测的是未包装的 stub ⇒ 删掉透传也不红。
 已改为构造真实 security.Store，并加**包装前置断言**
 （`_, ok := wrapped.(*secureProviderDecorator)`），防止再次假绿。

变异 2/2 咬住：
 · 删掉 SupportsVision 透传 → TestRegisterPreservesVisionCapability 红
 · 一律返回 true       → TestRegisterPreservesNonVisionCapability 红

## 实测（完整生产装配路径）

    源 llmsproxy  类型=*api.secureProviderDecorator  vision=true audio=false
    默认源 "llmsproxy": ProviderSupportsVision=true

重启本机实例后：22 插件建链 / 0 panic。
 2026-10-17 20:20:49 +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
03d87a4e21 docs(commondev): 主管式多仓库开发流水线的设计稿（未实现） 
记录一次关于「主管式多仓库开发」的完整设计讨论，供接手者使用。
**状态是设计稿，尚未实现** —— 文档头部已明确标注。

## 为什么写这篇

用户提出：以后由 HomeAgent 作开发主管，人只与主管对接；主管通过一个
commondev 插件管理多平台凭据、项目/分支台账、临时工作目录，并把「拉起
编码 agent → 改 → 自审 → 复审 → 复核 → 提 PR」串起来。

## 已核实的事实（均有可复现命令，见文档 §10 自检清单）

- 本机有 Gitea 1.24.2；TrueAgent 自身 remote 为 gitcode + github
- 插件凭据现状：`config_<plugin>` 明文、`config.db` 权限 644
- **拉起 agent 的三条路**（关键）：
  - `pi -p` ✓ cwd = 进程 cwd（已实测读出 marker）
  - `dsh headless` 逻辑同 CLI，本机凭据失效
  - `a2a_query`/`acp_query` ✗ **参数里没有 cwd**，且只对**已在运行**的
    agent 生效 —— A2A/ACP 是长驻 agent 模型，与「按任务拉起」不匹配
- 端口 14010/14011 由 pi-web-sessiond 监听，**不是** general pi 的能力
- 内核 `spawn_child` 与本题无关（它是工作式轻量子，参数只有 task/max_turns）
- `core.agent.workdir` 是**全局单值**且只是 cmd_run 的 fallback ——
  前序讨论中「给专属 agent 配它」的说法是错的

## 核心设计主张

1. **复核必须两步：正向 + 变异**。用户原话「我定义过单元测试后，插件复核即可」
   隐含了「GREEN = 改对了」这个不成立的假设 —— 插件只能跑预先写下的判据，
   判据没覆盖的 bug 照样打勾。自动化不会发现假绿，只会让假绿跑得更快更可信。
   文档引用了本仓当日实证（协议判据 M5 首轮未报红）作为依据。

2. **主管复审审的是「判据够不够」，不是逐行读 diff** —— 否则主管会变成
   更贵的高级码农。

3. **权限模型要让「必须有主管复审」成为机制而非礼貌**：执行侧凭据只能 push
   `feat/*`、不能 push main；主管侧才能合 PR。

4. **落地顺序**：第 0 刀先修「能拉起 agent」（当前成功率存疑，与 QQ 会话中
   agent 自身遭遇的 403/503 同源），再谈单平台单项目跑通一条真实链路；
   测试模板库放最后（它最容易写，也最容易变成摆设）。

文档还列了 5 个需用户拍板的未决问题（独立仓库 vs worktree、主管自己的模型
可用性、判据落地形态、并行任务间依赖、责任边界）。
 2026-10-13 16:21:31 +08:00
JianFeeeee
cf3d3769b1 perf(starmap): WebUI/GUI 星图卡顿修复 + 抽出共享「布局数学」单一源 
## 症状与实测

WebUI 星图建图阻塞主线程 9339ms、draw calls 7514；GUI 建图 2466ms、
draw calls 3477。两者在空闲时仍在空转渲染。

## WebUI（internal/plugins/webui/dashboard.js）

- 力导向布局 O(n²) 两两互斥改**网格近邻**，并移入 **Web Worker**
  ⇒ 建图阻塞 **9339ms → 57ms**
- 每节点光晕 3753 个 draw call → 1 个 InstancedMesh
- 边 966 → 4 个 LineSegments
- 空闲帧跳过 + 星空时间驱动
- 结果：draw calls **7514 → 3760**，空闲阻塞 **99% → 3%**

## GUI（cmd/gui/renderer/app.js）

- draw calls **3477 → 1809**，建图 **2466ms → 943ms**
- 首屏可见性守卫（GUI 默认 chat 视图，星图不该在后台初始化）
- 空闲 12fps → 0.2fps

修 GUI 两个自引 bug：
  1. 抄 WebUI 的 `starmapMorphSet`（GUI 实际用 `state.starmapGrown`）⇒
     每帧 ReferenceError、星图 0 帧；
  2. `camKey` 读 `starmapCam.position` 无守卫（`switchChatPanel` 同步调
     `starmapAnimate` 时 cam 为 nil）。**同一缺陷 WebUI 也存在，两处均已补守卫。**

## 共享源（方案 A：只共享「布局数学」这一层）

新增 `shared/starmap/layout.js`（3 个纯函数，零 DOM/全局引用）+
生成器 `tools/starmap-sync.mjs` + 门禁 `make check-starmap-shared`（已进
make test）。三处（共享源 / dashboard.js / app.js）的标记块必须逐字节相同。

**为何只共享这一层**（实测依据）：web 星图 54 个函数、gui 24 个，两者同名
函数逐字节相同数为 **0**。GUI 有设备桥/computer use/托盘/自有面板，WebUI 有
侧栏页签体系 —— 共享受众完全不同的 UI 代码是错的，能安全共享的只有布局数学。

**为何用生成器而非运行时加载**：GUI 用 file:// （main.js 的 loadFile），可能
离线；让其拉服务端 dashboard.js 会把「星图能否初始化」绑到网络与登录态上。

**为何 GUI 不用 Web Worker**：file:// 下外链与 Blob Worker 实测都能跑，但不把
「星图能否初始化」押在打包环境的 Worker 行为上。

## 判据

- `cmd/gui/starmap-perf.test.mjs`（21 条，接入 npm test）
- 扩充 `internal/plugins/webui/starmap_perf_test.go`（同源判据 +
  checkStarmapSharedBlock）
- 变异 M1/M2/M3 全部报红

## 附带

cmd/gui/renderer/app.js 同时含上一提交的 GUI `system` 事件消费（协议修复），
因同文件交织未再拆分，见提交 fix(clients)。
 2026-10-13 16:21:04 +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
ec035951cc fix(agent): 批内附加消息延迟到整批落完，修复上游 tool_calls 配对 400 
生产实测（llmsproxy tier 1，每 5 秒持续复现，非偶发）：

    api error 400: An assistant message with 'tool_calls' must be followed by
    tool messages responding to each 'tool_call_id'.
    (insufficient tool messages following tool_calls message)

根因在 stepToolAfter：它在**批内循环**里对每个工具各调一次，却当场追加
两类附加消息（多模态注入 mediaMsg=user、记忆召回=system）。于是 N 个工具
的批变成

    assistant tool_calls=[c1,c2]
    tool c1
    user            ← 插在中间
    tool c2         ← 被挤开，与 assistant 不再相邻

上游按「紧跟 assistant 的连续 tool 消息」计数，只数到 1 条却声明了 2 条。

修复：TaskFrame 增加 batchAttachments / batchRecall 积压附加消息，
新增 flushBatchAttachments() 只在**整批 tool 消息全部落完之后**调用。
两个调用点：并行路径 stepToolBatch 收尾循环之后；串行路径 stepToolBegin
发现批已耗尽时。

这也落实了「多模态注入点应在当前轮工具调用之后」这一设计约束。

判据（internal/agent/core/toolcall_adjacency_test.go）：
- assertToolCallsAdjacent —— assistant(tool_calls=[c1..cn]) 之后必须**紧接**
  n 条 role=tool 且 id 一一对应。既有 TestBatchToolCallIDsAllPaired 只断言
  **数量**配对（其注释明确写着「不断言消息的物理排列」），而数量对、排列错
  上游照样 400。
- assertMediaNotSilentlyDropped —— 注入的媒体不得静默丢失。
- 三条用例覆盖串行路径 / 并行路径 / 最小回归。

变异验证（M1 当场追加 media / M3 删并行 flush / M4 删串行 flush）全部报红。
其中两轮暴露「判据太松」并已补强：
  1. 测试工具未声明 ParallelSafe ⇒ 整批降级走串行，并行判据形同虚设。
     补并行专用判据 + 前置断言（不满足即 t.Fatalf，不静默跳过）。
  2. 仅断言相邻性时，删掉 flush 反而"更相邻"（附加消息压根没进来），
     判据全绿而媒体被**静默丢弃** ⇒ 补 assertMediaNotSilentlyDropped。
     教训：只断言一个性质会漏掉另一个，相邻性与不丢失必须同时断言。

验证：core 包三次全绿 + -race 干净；全仓 48 包 0 FAIL；
端到端真实多工具并行对话正常完成，日志 insufficient tool messages = 0 次。
 2026-10-13 16:18:13 +08:00
JianFeeeee
c7da8fde82 perf(webui): 星图力导向布局改网格近邻 + Web Worker，消除主线程 10.9s 阻塞 
生产库 3754 块时，buildChatStarmapGraph 在内联脚本里同步跑 50 轮全对全
（O(n²)）斥力：每轮 704 万次配对，50 轮共 3.52 亿次。CDP Profiler 实测
单次阻塞主线程 10.9 秒，页面启动首帧 11.8 秒；PerformanceObserver 在
40 秒窗口统计到累计 40,005ms 长任务。

两条独立问题叠加，本提交分别解决：

① O(n²) → 网格近邻（O(n·k)）
   斥力体里本来就有 `if (d < 25)` —— 只对近邻施力，全对全是白算。
   改为 3×3×3 网格分桶，只遍历邻近格。实测 3754 节点 7016ms → ~120ms。

② 同线程 → Web Worker
   即使算量合理也不该占主线程。计算整体移入
   static/starmap-layout-worker.js，主线程零阻塞。

配套：迭代数按 n 自适应（小图跑满 50 轮，大图退到 14 轮）+ 迭代间早停
（阈值取平均间距的 0.2%，随规模自适应）。

★ 串行回退（file://、老浏览器、Worker 构造失败）必须用**同一算法**。
   若回退走旧全对全，两条路径会给出不同布局 —— 「有 Worker 和没 Worker
   看到的图不一样」极难排查。故两边各写一份逐字对应的实现。

★ 另修：renderChatStarmap 必须在容器不可见时提前返回（offsetParent）。
   starmapActiveContainer 会 fallback 到聊天面板，导致未打开星图也被迫
   建图，把聊天页签一起拖死。

判据 TestStarmapNoPerFrameFullScan 同时覆盖两处实现，经三向变异验证：
  ① 回退改回 Object.keys 全对全 → FAIL
  ② Worker 去掉 CUTOFF 网格法 → FAIL
  ③ 删除 Worker 文件 → FAIL
 2026-10-13 10:12:57 +08:00
JianFeeeee
ceb8a7b165 refactor(proc)!: 版本身份只由版本号本身承载，删除全部自定版本号 
内核侧配合 SDK 仓 b2872f3：兼容性不再依赖任何自造版本号。

删除三处自造号：
  - ProtocolVersion（协议号）→ 改为比对主版本段（MajorVersion）
  - shmVersion（共享段 header）→ 改为校验描述符个数（field_count）
  - unifiedVersion（SuperBlock）→ 结构自描述，不再校验

握手契约随之调整：
  HandshakeParams:  protocol(int) → core_version(string)
  HandshakeResult:  protocol(int) → sdk_version 承担判据
  内核比对 MajorVersion(meta.Version) == MajorVersion(res.SDKVersion)，
  跨主版本即拒并提示重编（主版本跃迁 = 破坏性变更的定义）。

为什么废除：额外的号需要人去记得升，而它没有任何结构性约束兜底，
必然腐烂。实证：ProtocolVersion 常量在多次布局变更里只升过一次，
对应的守卫测试长期失败无人察觉（期望 18/1，实际 19/2）。

新增判据：
  - TestProcess_MajorVersionMismatchRejected：跨主版本被拒（testdata/badproto）
  - TestProcess_SameMajorDifferentMinorAccepted：同主版本放行（新增 testdata/oldminor）
    后者是 §七「1.x 内纯追加、不调新面不用重编」规约的落地 —— 若误用全等
    比较，未重编的存量插件会被无谓地全部拒绝。
  两条均经变异验证：改成全等比较 → 前者过/后者挂；删掉校验 → 前者挂。
 2026-10-13 09:39:34 +08:00
JianFeeeee
31de3921ed Merge branch 'fix/proc-extra-frame-passthrough' into refactor/block-union-payload 2026-10-13 08:51:11 +08:00
JianFeeeee
1d843daf2a fix(guard): 心跳提前启动 + 首次同步写入 —— 启动竞态的 worker 侧根修 
562ba6bd 修了 guard 侧（给旧 mtime 加启动宽限，不误杀），那只是防御。
**根因**在 worker 侧：心跳文件要等全部重型初始化完（原 main 尾部）才
首写，且首次写是异步（在 goroutine 里，与多模态空间/知识库重建竞争
调度）。停机 >30s 后重启时 mtime 停在上一代 worker，guard 的 5s ticker
先到就 SIGKILL。

两层独立生效：
  worker 侧（本提交，治本）：dataDir 一确定就启动心跳，首次写同步
  guard 侧（562ba6bd，防御）：保留启动宽限期容忍旧 mtime

## 改动

- main.go：startHeartbeat 从尾部（190）移到 dataDir 解析后（54），
  用 context.Background()（心跳生命周期=进程，与 agent ctx 解耦）。
- bootstrap.go：startHeartbeat 首次 writeHB() 提到 goroutine 之外
  同步执行——返回前 mtime 必已变新，main 往下做慢事之前 guard 看到的
  是新心跳。

## 判据（TestHeartbeatFirstWriteSynchronous，变异测试通过）

  (a) 返回后立即查 mtime：必须是新的（同步首写），不许等到第一个 tick
      首写移回 goroutine（异步）→ (a) 当场 FAIL，已实测
  (b) 5s 后 mtime 再变（ticker 在跑）
  (c) stop() 后不再更新（hbStop 生效，不泄漏 goroutine）

判据覆盖完整生命周期：启动即新 → 周期更新 → 停止即停。

cmd/homed 包全量测试通过；全仓生产编译 GREEN。
 2026-10-12 19:32:04 +08:00
JianFeeeee
562ba6bd98 fix(guard): 启动宽限期 —— 停机重启后不再误杀加载中的 worker 
## 故障（2026-10-12 部署实测，6 连杀 + 服务降级）

停机 34s 后重启：heartbeat 文件 mtime 停在**上一代 worker**（已远超
30s 阈值）。新 worker 要先做完全部重型初始化（chineseclip 512 +
两个静态词向量 + 知识重建，冷启动 5–8s）才写第一次心跳
（startHeartbeat 在 main.go:190，位于所有初始化之后）。
而 guard 的 5s ticker 先到、拿旧 mtime 判 stale → 把还在加载的
worker SIGKILL → 循环重启，guard 进入 failback Safe-Mode：

    19:00:28 worker up pid=931403 boot=normal
    19:00:33 heartbeat stale for pid=931403 ... SIGKILL   ← 加载中
    19:00:33 worker up pid=931557 boot=normal
    19:00:38 heartbeat stale ... SIGKILL
    ...（6 连杀后）
    19:00:43 3 failures >= max 3, entering failback (Safe-Mode)

worker 自身日志完全健康（graph/multimodal/knowledge 依次就绪），
纯死于"还没来得及写第一次心跳"。

## 根因

heartbeatStale 对「文件不存在」宽限，但对「文件存在、mtime 是
上一代的」不宽限——停机超过 heartbeatTimeout 的每一次重启都会踩。
旧内核未暴露只因它从未停机这么久（上一次是系统重启，mtime 新鲜）。
既有缺陷，block-union 重构未触碰该逻辑（main 分支同病）。

## 修法

spawn 后给一个 heartbeatTimeout 的**启动宽限期**：期间即使心跳
文件 mtime 极旧也不判杀。宽限期满后恢复原判定（卡死 worker 靠
宽限躲不过去）。决策抽成纯函数 shouldKillStaleHeartbeat。

## 判据（TestStartupGraceAllowsInit，变异测试通过）

  (a) 宽限期内 + mtime 极旧（上一代遗留）→ 不许杀
      （末沿 -50ms 也钉住：ticker 恰在 deadline 前触发是常态）
  (b) 宽限期满 + mtime 极旧（真卡死）→ 必须杀
  (c) 宽限期满 + mtime 新鲜（健康）→ 不许杀

变异（移除宽限判定、直接 heartbeatStale）→ (a) 两条断言当场 FAIL；
恢复后全绿。TestHeartbeatStale（三分支既有判据）不受影响。

cmd/homed 包全量测试通过；全仓生产编译 GREEN。
 2026-10-12 19:16:57 +08:00
JianFeeeee
baf2ecd7c9 test(memory): 块 union 的并发压测（字节与块同表之后的并发热点） 
块 union 化把「元数据」与「负载」合并进同一行（memory_blocks.data BLOB），
原本分属两个存储（media.db 元数据 + blobs 文件）的读写现在全压到同一张表、
同一把 g.mu。这条改动是否引入锁争用/丢更新/字节错位，只有并发实测能回答。

7 条压测（全部 -race 通过，约 26 万次并发读、0 撕裂 0 丢失）：

  1. ConcurrentPutSameContent  —— 16 写者同内容：只留 1 行且字节完整
  2. LeanRewriteMustNotBlankData —— ★ 瘦块（blockColumns 不含 data）重写
     已回填块时，ON CONFLICT 不得把 data 覆盖成空。这正是生产踩过的坑，
     变异（把 `CASE WHEN ... THEN memory_blocks.data` 改成 `= excluded.data`）
     当场被这条判据抓住。
  3. ConcurrentReadWriteNoTear —— 8 读者 + 4 写者（改向量）：16456 次读
     0 撕裂 0 丢失
  4. BackfillConcurrentWithRecall —— 回填（单事务）与读取并发：101033 次读
     0 错字节；终态候选清零
  5. DeleteConcurrentWithRead —— 用真实删除路径 DeleteEntity：143k 次读
     只能看到「完整内容」或「不存在」；终态块与负载一起消失（union 两半同生共灭）
  6. ConcurrentSetVector —— 12 写者并发写向量：仍是合法 JSON、维度正确、字节未动
  7. ManyBlocksLargePayloads —— 120 块 × 256KB = 30MB 反复读写逐字节校验

★ 为何删除压测不用媒体块：生产**没有**按块 ID 删媒体块的路径。删除发生在
实体级（DeleteEntity 按 text_content 匹配）与孤块清理（PurgeOrphans 只扫
text_content != ''），所以用 DeleteEntity 这个真实路径。
 2026-10-12 17:37:08 +08:00
JianFeeeee
fdfbcea479 fix(memory)!: 视觉路被文本块饿死 —— 模态过滤必须在截断之前 
## 回归（块 union 化引入，真实数据实测）

CAS 时代 `crossmodal.go` 的视觉路查 `QueryMediaScored`，SQL 是
`FROM media`——**只含媒体**，结构上不可能被文本块挤掉。
86572d13 把它换成通用 `RecallBlocks`（全局 top-K，含数千文本块），
于是视觉路每查必空。

## 定量证据（生产模型 chineseclip + 真实生产库副本）

同一向量空间内，文本查询与两类块的原始余弦：

| 查询 | 图像块 max / p95 | 文本块 max / p95 |
|---|---|---|
| 图片 | 0.3773 / 0.3554 | 1.0000 / 0.8644 |
| 一张图片 | 0.4096 / 0.3707 | 0.9222 / 0.8693 |
| 照片 | 0.3850 / 0.3651 | 0.9349 / 0.8672 |

图片的绝对相似度天然低于「字面相同的文本」。复刻生产调用
（per = max(8, topK*2)，再 `continue` 掉文本块）：

    per=  8 → 5 次查询 40 条，图像块 0 条
    per=200 → 5 次查询 1000 条，图像块 0 条   ← 视觉路被彻底饿死

根因：**「取全局 top-K 再过滤掉文本块」——过滤发生在截断之后**，
名额早已被文本块占满。下面的 `continue` 只是防御，不是筛选手段。

## 修法

`BlockRecallQuery` 新增 `Modality` / `ExcludeText`，并在 **SQL 层**
限定（不是取回来再丢）：
  - 语义正确：让 top-K 在目标模态内部竞争
  - 顺带省算力：不必反序列化 3639 个文本块的向量再丢弃

`crossmodal.go` 视觉路传 `ExcludeText: true`。修复后同一诊断：
`per=200 → 560 条全部是图像块，文本块 0 条`。

## 判据（含变异）

- `TestRecallBlocks_模态过滤在截断前生效`（单测，500 满分文本块 + 2 低分媒体块）：
  ① `ExcludeText` TopK=2 仍取到 2 个媒体块；② `Modality=image` 只返回图像块。
  **变异**（同时移除 SQL 过滤与循环内 continue）→ 两条断言当场 FAIL。
  注：只移除 SQL 过滤而保留循环内 continue **不算变异**——语义等价，
  差别仅在性能（这点也实测确认过）。
- `TestE2E_MultimodalBlockRecall`（-tags 'e2e onnxruntime'，生产模型 + 真库）：
  ① 12 个真图块可嵌入（512 维）；② 12/12 块能被自己的向量召回（纯向量）；
  ③ 跨进程重开后向量/指纹/字节都在；④ `ExcludeText` 视觉路召到 20 个媒体块。
  判据②原写成"必须 top1"，实测发现同一张图被存成 4 个块（digest 相同）
  → 向量逐位相同 → 并列满分，top1 只取决于排序稳定性。
  改为"必须出现在满分并列集，且排在它前面的都必须是同内容"。

回归：memory / agent-core / sdk 全绿；全仓生产编译 GREEN。
 2026-10-12 17:18:04 +08:00
JianFeeeee
937164e515 docs(memory): 修正三处仍把已删 CAS 当活的注释 
9f7d91c2 删掉了 media.Store，但有三处注释还在说"向量存在 media.Store 里"、
"直接用于 media.Store 的稠密余弦检索"——留着会让读者以为那个包还在。

- internal/memory/vector/store.go：多模态稠密空间现用于**媒体块自带向量**的
  余弦召回，不再经 media.Store。
- internal/knowledge/knowledge.go：MediaRef 注释澄清字节作为条目自带数据
  落在条目目录的 File 上（Digest 只是内容派生身份，同内存无第二份）。
- internal/memory/migrate_blockdata.go：resolver 由调用方提供（迁移命令直读
  旧 CAS 冻结布局），sha256 校验也在那一侧做，不在这里重复。

纯注释，无行为变更。全仓生产编译 GREEN；memory/knowledge/vector 包测试通过。
 2026-10-12 16:55:40 +08:00
JianFeeeee
c620694084 docs(memory)!: 同步 CAS 淘汰后的媒体记忆描述 + 清死配置键 
承接 9f7d91c2（删 CAS 包）：文档与配置注册表仍在描述已经不存在的
内容寻址存储，留着会误导后来者按旧模型接线。

- internal/config/registry.go：删 `core.memory.media.enabled` 与
  `core.memory.media.dir` 两个配置键。唯一读取方 initMediaStore 已随
  9f7d91c2 删除，两键再无读取处（已 grep 确认 0 处）。

- assets/docs/{zh,en}/ARCHITECTURE.md：媒体记忆一节从"CAS + digest 寻址"
  改写为"块 union：媒体即块的一种取值"。要点：
    - 负载归属 memory_blocks.data（随块同生共灭，无块外字节层）
    - 块身份内容派生 blk_media_<sha256(mime+data)[:12]>（同内容同 ID）
    - 检索走块自身向量；负载按需 BlockData / 插件经 Memory().MediaBytes
    - 知识库媒体字节落条目目录（Remove 的 RemoveAll 天然清理）
    - 跨空间迁移改用 fingerprint 字段名（vec_model 已是旧概念）
  并写明为何删（两套存储必然要打补丁、digest 与块 ID 双身份易错位），
  避免"旧设计看起来也行"的错觉。

全仓生产编译 GREEN；config 包测试通过。
 2026-10-12 16:54:46 +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
2585bc67ef feat(memory)!: 存量媒体字节回填（块 union 化第三阶段：数据迁移） 
块 union 化后媒体字节归块所有（memory_blocks.data），但存量库里
data 为空、payload_digest 仍指向旧 CAS。不回填就删 CAS ⇒ BlockData
取不到字节，图永久丢失。本提交补上这一步。

生产数据实测（/home/newqqagent/memory）：
  - graph.db 112 个媒体块，引 106 个唯一 digest
  - media.db 156 条 + blobs 87M，112/112 digest 命中

内核（internal/memory/migrate_blockdata.go）
  - BackfillBlockData(resolver)：单事务、全回滚，按 payload_digest
    把字节写进块自身 data 列。保留原块 ID —— 边/场景/向量都挂在它上面。
  - CountBlockDataBackfillCandidates：报告模式，不写库。
  - ProbeBackfillAvailability：dry-run 看 CAS 命中率。
  - ensurePayloadDigestColumn：★ 关键。block union 化后新库的 CREATE
    已删该列，旧库还留着。迁移必须两者都能跑：旧库忽略 duplicate
    column 错误，新库补列后得到 0 候选（安全空操作），而不是崩在
    "no such column"。
  - CAS 取不到字节的块计 Missing 并跳过（既有数据损失，不阻断其余）。

命令（cmd/homed-media-backfill）
  - 默认只报告，-apply 才写；写前自动 sqlite3 .backup 快照。
  - 回填后立刻 BlockData 抽样自检。

判据（4 条单元 + 1 条真实数据 e2e，全部做过变异测试）
  - RoundTrip：BlockData 取回字节 == 来源逐字节一致
  - MissingDigestSkipped：缺失内容计 Missing 且不阻断
  - IdempotentThreeRuns：连跑三次只真回填一次
  - FreshDBSafeNoOp：新库（无该列、无历史数据）上是安全空操作
  - E2E（-tags e2e，读真 graph.db）：112 块全部可取回、sha256 与
    payload_digest 全等、抽样 20 块用自己的向量自召回 score=1.0

变异测试（判据不是装饰）：
  - 回填写空字节 → RoundTrip 挂
  - Missing 分支改为也写入 → MissingDigestSkipped 挂
  - 候选查询不排除已回填 → IdempotentThreeRuns 挂
  - 移除 ensure 调用 → FreshDBSafeNoOp 挂（no such column）

生产数据 e2e 已在 /tmp/e2e-backfill 副本上完成（sqlite3 .backup 快照 +
CAS 拷贝）：报告 112/112 命中 → apply 回填 112 块 55.03MB → 独立
交叉验证（python hashlib 全量 112/112 sha256 吻合 + sha256sum 对照
磁盘 blob 一致）→ 幂等复跑 0 候选 → 读路径召回 20/20 命中。
 2026-10-12 16:23:23 +08:00
JianFeeeee
33e1a0bfaf test(memory)!: 块 union 化判据重写（CAS 淘汰第二阶段：测试） 
生产已在上一提交(86572d13)全绿；本提交把 CAS 专属测试改到块语义，
并修掉几处判据自身的缺陷（判据错 ≠ 生产错）：

- sdk/memory_impl_test: media.Store→块；NewGraphMemoryWithPlugin
- core/{graphmedia,mediaref,medialive,medialoop,inputunify}_test:
  mediaStore→memory；PayloadDigest→Data/BlockData；shortDigest→shortID
- graphmedia: 无引用句子用独立块 ID（shortID 20 字符会与 blk_src_ 撞长度）
- memory/sentence_block: BlockByIDPrefix 加 len<12 下限（短引用守卫）
- core/medialoop: reembedOneBlock 按 BlockData 兜底取字节（lean 列无 data）
- knowledge: broken.png 改目录造读失败（chmod 0000 对 root 无效）；
  dense/attach 测试补 Data 并先落盘后 AttachMedia
- webui: graph_pulse fixture payload_digest→has_data

注：internal/plugin/proc 的 shmVersion 不匹配(内核1/插件2)是
SDK 仓(777c3a0,v2 模板)与本分支内核(v1)的跨仓版本错位，
与块 union 无关（stash 全部改动后仍复现），属 proc-extra 特性线。
 2026-10-12 14:26:13 +08:00
JianFeeeee
86572d134d refactor(memory)!: 块 union 化，彻底淘汰 CAS 第一阶段（生产代码） 
块自带负载（MemoryBlock.Data），删 PayloadDigest；检索纯向量，媒体随块
同生灭。生产代码全绿；CAS 专属测试将在下一提交随判据重写。

- memory: Data BLOB + migration9；blockColumns 不含 data（召回只比向量）；
  MediaBlockID 内容派生 ID；BlockByIDPrefix/BlockData 按需加载
- sdk: memory_impl 去 media.Store；MemoryBlockView PayloadDigest→HasData
- core: mediaref/graphmedia/crossmodal/medialoop 全部改块语义；
  captureBlockMedia 直接产块；resolveMediaRefs 按块 ID 解析
- knowledge: 媒体字节随条目目录自带（File+Data），删 mediaGet/mediaPut
- webui: graphBlockView/pulse payload_digest→has_data
- bootstrap/registry: 去 MediaStore 接线（SetMediaStore 空实现，待⑥删包）
 2026-10-12 10:13:36 +08:00
JianFeeeee
6abf03bd78 fix(proc)!: shm 桥 v2 —— fExtraBag 透传插件自建 Extra 键，修复绑桁权限门失效 
根因（2026-10-12 生产实证）：shm 桥此前只透传 4 个具名 Extra 键
（media_blocks/media_type/input_source/output_channel），插件自建键
（qq 的 qq_auth 绑帧身份）在 WriteDirty/captureLocal 处被静默丢弃，
下一 stage ReadInto 重建的 Extra 永远没有它 → authOnFrame 恒 miss →
before_toolcall 回落到可变全局身份。owner 轮被并发的非 owner 中断
合并降权后，自己的 memory_commit 被硬私名单误拒（日志 22:20:58
「改写了 1 个字段」）；反向时序则可能把非 owner 误放为 owner。

- shm.go：stageField 加 fExtraBag（19 字段），shmVersion 1→2
  （AttachSegment 与插件握手对旧版失败即拒，不静默错读新布局）
- shmcodec.go：captureLocal/WriteAll/ReadInto/newSnapshotFromLocal
  全链接入 bag；写侧过滤具名键（bag 不偷具名键槽位）；读侧 bag 先
  打平、具名键后覆盖（具名键永远赢）；不可序列化值显式报错——
  宁失败不静默丢键（丢键对 qq 是权限失效）
- extra_bag_test.go：判据 8 条（往返无损/具名键语义不变/不可序列化
  报错/WriteDirty 零写与脏写/跨 stage 帧存活/袋污染具名键必输/
  raw-JSON 写侧过滤/快照脏检），变异 M1-M3 全杀

配套：SDK 仓 777c3a0（模板 v2 同步 + qq 身份可序列化 + 插件侧判据）。
部署注意：shmVersion 2 后全部 23 个 proc 插件须用新 hmapdev 重编。
 2026-10-12 08:30:14 +08:00
JianFeeeee
b15994d964 fix(seemedia): hear_audio 不再承诺「你会听到」，如实说明可能不支持 (#7) 
## 问题（e2e 抓出，非猜测）

端到端跑 hear_audio 时模型答「老实说，这次我没法真的听到」，转而去数 WAV
字节。查日志：

    tool hear_audio result: {"note":"音频已投给你——请在下一步直接聆听..."}
    modal fallback: 0 block(s) transcribed, 0 skipped
                    (provider=llmsproxy vision=true audio=false)

真因是**配置缺口 + 描述说谎**叠加：
- 当前部署所有 LLM 源都是 audio=false（visionllm/llmsproxy 均如此）
- core.input_processing.audio.fallback_provider 为空 ⇒ 无回退源
- 于是内核既不能直视、也无法转写，只发一条「拿不到音频」的 notice

而工具描述写死「你会直接听到它」、note 写「请在下一步直接聆听」——
模型同时看到「你会听到」与「拿不到」，两句自相矛盾（这就是它转去数
WAV 字节的原因）。

## 为何不改代码改行为

插件在调用时**无法**得知当前模型是否支持音频，SDK 未暴露能力查询接口
（只有 LLMAPI 的 Chat/ReloadFromConfig）。所以插件没有能力「先判断再决定
要不要注块」。正确做法是：内核继续做它该做的诚实降级（已在 modalfallback
里实现），插件这边**不许替内核承诺**。

## 改了什么

- hear_audio 描述：从无条件承诺改为条件式（「若当前模型支持音频或配了回退源，
  你会在下一步听到」），并明说：若都不支持，内核会明确告知拿不到（不会假装
  听到），那时改用 transcribe_audio 或配置回退源
- handler 的 note：从「请直接聆听」改为「请确认是否真的收到；没收到就改用
  transcribe_audio」

## 判据（可杀变异，3/3 实测）

- TestHearAudioDoesNotPromiseAudibility：描述不得含无条件承诺；必须指明
  transcribe_audio 出路；必须如实说「不支持」
- TestHearAudioNoteIsHonest：note 不得说「直接聆听」；必须给替代方案

★ 判据自身修了一个 bug（变异测试抓出）：原先用「下一个 RegisterTool」做段
终点，但 hear_audio 是**最后一个**注册 ⇒ 一路截到文件尾，把 handler 的 note
也吞进来，于是 note 里残留的 transcribe_audio 让「删掉描述出路」的变异逃逸。
改用 "p.handleHearAudio)" 作终点后该变异被杀。

变异实测：
  F 描述改回无条件承诺      → FAIL ✓
  G 描述删掉 transcribe_audio 出路 → FAIL ✓（修判据前曾逃逸）
  H note 改回「直接聆听」     → FAIL ✓
  I 描述删掉「不支持」说明    → FAIL ✓

18/18 通过；全量 homed 构建通过；二进制内已无旧假承诺、含新的诚实措辞。

Co-authored-by: JianFeeeee <JianFeeeee@users.noreply.gitcode.com>
 2026-10-11 13:22:15 +08:00
JianFeeeee
16309c3307 feat(seemedia): 多模态直视插件——让模型一手看图/看视频/听音频 (#6) 
* feat(seemedia): 新增多模态直视插件，让模型一手看图/看视频/听音频

## 动机

现有 multimodal（describe_image / transcribe_audio / ocr_image）走的是**二手**路：
插件自己起一次 VLM 子调用，把结果**文字**喂回主模型。省 token、能入记忆正文、
主模型非视觉也能用，但模型看到的是「别人转述的描述」，细节丢失不可逆。

缺的是**一手**路：让模型主动把原始像素/帧/音频投给**自己**去判读。本插件补上。

## 工具（三模态，用户决策 image+video+audio）

- `see_image`：path/digest/url → image_url 块，经 SetToolBlocks 直投主模型
- `see_video`：ffmpeg 抽帧（默认 6 帧，上限 10，对齐内核 modalfallback 约束）
  → 多张 image_url 块一起投；探时长成功走均匀定位抽帧，失败退单遍 thumbnail
- `hear_audio`：path/digest/url → audio_url 块直投

三者都 `ParallelSafe:false`：SetToolBlocks 写的是「当前 call」的块，并发会串台。

## 与 multimodal 并存（用户决策 coexist）

职责分工，不互相取代：
- 要省 token / 要把结论写进记忆 / 主模型不支持该模态 → describe_image（二手文字）
- 要模型亲自判读细节（看清截图、逐帧看操作） → see_*（一手原始媒体）

## 媒体来源（用户决策 path+digest+url 全支持）

- path：设备/工具回传的落盘文件（local_screensee、browser_screenshot、mc 截图…）
- digest：用户上传已入 CAS 的媒体，sdk.Media().Get 取回，不在内核↔插件间传 base64
- url：http(s) 直链；图/音频原样透传（不下载、不入 CAS），视频交 ffmpeg 原生读 http

## 直接进记忆（记忆载体已块化，天然打通）

seemedia 经 SetToolBlocks 注入的块，内核 task.go captureBlockMedia 处**无条件**
落进 CAS 并转成一等记忆块挂到本轮 ContextEvent（「无论直视还是回退，媒体本体都该
进记忆」）。所以一手看到的图/帧**同时**进了记忆，之后能按多模态向量被
doc_query / memory_recall 召回。本插件不写任何入库代码，复用既有块化链路。

★ 边界（刻意取舍）：captureBlockMedia 只对 data URL 入库，http(s) URL 被跳过
（不下载、不入记忆、不算向量，规避 SSRF/超时）。即 path/digest 来源可召回，
url 来源只是模型当场看到但不进记忆。要让 http 媒体长期可召回，先落盘再传 path。

## 形态：内置插件（用户决策 builtin）

与 multimodal 并排 internal/plugins/seemedia，经 all.go init() 注册。代价是延续
「内核进程内读任意本地文件」这个 a02d8b00 本想消除的张力——但 multimodal 已是
内置且同样读 path，保持一致比单独走子进程沙箱更不易让人困惑；日后收紧应两者同搬。

## 判据（可杀变异，实测）

plugin_test.go：
- url 透传且拒 file://（去掉 isHTTPURL 校验 → FAIL）
- path 优先于 digest、url 优先于 path，且 path 命中时不碰 CAS
- 无来源报错且信息可操作（指明 path/digest/url）
- 文件错误带路径、空文件明说「空」
- clampFrames 把帧数夹到 [1,10]、非正回默认（超限不夹 → FAIL）
- 三工具不得声明 ParallelSafe:true（防 SetToolBlocks 串台）

9/9 单测通过；本机 ffmpeg/ffprobe 已就位；全插件 + homed（-tags onnxruntime）
构建通过；internal/plugins 装配冒烟通过。

* test(seemedia): 补集成/压力/变异测试（16 判据，5 变异全杀）

上一个提交只带 9 个纯逻辑单测（来源解析、clamp、MIME）。抽帧是本插件唯一
真正驱动外部进程、且会并发的部分，必须真跑 ffmpeg 压一压：

- 真视频 → 请求 N 帧就拿到 N 帧，每帧校验 PNG 魔数（1/3/6/10 四档）
- ffprobe 置空 → 走单遍兜底仍能拿到帧
- 损坏/非视频文件 → 如实报错，不 panic、不返半成品
- 已取消的 ctx → ffmpeg 必须立刻失败（取消传播真生效）
- 并发 16 路抽帧 → 不串台、不泄漏临时目录（前后计数比对）
- digest 视频 → 真 CAS 取字节落临时文件，cleanup 后必须删掉
- 静态判据：所有子进程必须 exec.CommandContext，不得裸 exec.Command

为什么超时判据从「计时」改成「已取消 ctx」：合成视频抽帧本来就快（~0.1s），
「1ns 超时」和「忽略超时」在计时上分不出——实测这种变异杀不掉，是判据设计
缺陷。改用已取消 ctx 的行为判据（CommandContext 在 ctx 已取消时 Start 即失败）
后，忽略 ctx 的变异被杀。

变异实测（5/5 全 FAIL，还原后全绿）：
  A clampFrames 超限不夹        → TestClampFrames FAIL
  B url 分支去掉 isHTTPURL      → TestResolveMediaURL_URLPassthrough FAIL
  C cleanup 不删临时文件         → TestResolveVideoInput_DigestCleanup FAIL
  D grabFrameAt 忽略 ctx         → TestFrameGrabHonorsCanceledContext FAIL
  E 抽帧数写死 1                 → TestExtractFrames_RealVideoExactCount FAIL

16/16 通过；`-tags onnxruntime` 全量 homed 构建通过，三工具在册。

---------

Co-authored-by: JianFeeeee <JianFeeeee@users.noreply.gitcode.com>
 2026-10-11 13:06:23 +08:00
JianFeeeee
a7f89a1b45 fix(guard)!: L2 自杀防护 + 配置零值兜底 + 补齐零覆盖的测试 
部署 guard 前的审查发现两个**致命**缺陷。它们此前都零测试覆盖 ——
正是「没测过才敢发现」。

## ① L2 自杀循环（启用 guard 就会触发）

doLastResort(restart_app) 执行 `systemctl restart <unit>`，而启用 guard 的
标准做法正是让 systemd 管理 `homed --role=guard` —— <unit> 就是它自己：

    guard: doLastResort → systemctl restart homeagent
           → 杀掉自己 → systemd 按 Restart=always 拉起新 guard
           → 新 guard 再 spawn 失败 → 再自杀 …… 无限循环

每轮白跑一遍完整启动。与 2026-09-05 那次 systemd 审计记录的事故同类
（坏配置导致 836 次重启、79 分钟）。

### 修法：自指时直接退出，而不是换个单元名

「换个别的服务」语义完全不对 —— L2 的本意就是重启自己。而
`Restart=always` 已经提供了这件事：**guard 退出 == systemd 重新拉起 ==
重启整个单元**。所以自指时 os.Exit(41) 与 restart_app 完全等价，且无自杀窗口。

- `doLastResortGuarded(cfg, unit)`：判自指 → 退出 41；否则原逻辑
- `detectOwnSystemdUnit()`：读 /proc/self/cgroup（cgroup v2），兜底
  $INVOCATION_ID → /run/systemd/invocation/<id>。**拿不到就返回空字符串**
  让调用方跳过检测 —— 不猜单元名（猜错 = 拦错/杀错服务）
- `exitGuardRestartRequested = 41`：刻意避开 worker 的 42-44 区间
- 两处 doLastResort 调用点全部改走防护版

## ② 配置损坏 → agent 装上就崩

defaultGuardConfig **不解析时长字符串**（只给 "30s" 这类字面量），
parseDur 在 loadGuardConfig 里、且在 yaml.Unmarshal **失败时提前 return
之后**——那段根本不执行。

于是 guard.yaml 一旦写坏（缩进错、半截内容，手改文本极常见）：

| 字段 | 实际值 | 后果 |
|---|---|---|
| heartbeatTimeout | **0** | `time.Since(mtime) > 0` 恒真 → **每轮杀 worker** → 无限重启 |
| heartbeatInterval | 0 | `time.NewTicker(0)` panic |
| attemptTimeout | 0 | 恢复 probe 立即超时 → L1 梯子必败 |
| Recovery.Plugins | 空 | 受限启动什么都不加载 |

这不是「配置没生效」，是「装上就崩」。修法：把 parseDur 与插件集缺省
移进 defaultGuardConfig，任何路径都有正值兜底。

## ③ 测试：0 → 25 条（全可杀变异）

| 文件 | 覆盖 |
|---|---|
| `guard_config_test.go` | 配置默认值/YAML/损坏/越界 + 心跳三态 |
| `guard_lifecycle_test.go` | worker 生命周期：6 种退出码分类、信号转发、坏二进制、卡死压力测试、L2 防护行为、单元探测 |
| `guard_safety_test.go` | 破坏性路径：回滚不可逆、任务协议往返、failback 插件集 |
| `rollback_irreversible_test.go` | 不可逆性证据 + 二次回滚 no-op + 新建→删除 |

**7 个变异逐个实测被杀**：parseDur 移回原处 / 心跳漏判 / 心跳误判 /
插件集留空 / exitRecovered→crash / exitRecoveryFailed→recovered /
rollback 不删 changeset / L2 防护失效 / 单元探测返回假名。

### 判据自身被变异测试逼着改三次

1. `isSelfRestartCommand` 的测试全绿，但把 `doLastResortGuarded` 改成
   直接调 `doLastResort`（防护完全不生效）时**仍然全绿** ⇒ 补了
   **行为测试**：真子进程 + 假 systemctl（PATH 前置），验「自指时
   restart_command 绝不被执行」
2. 单元探测只断言「非空+格式合法」，被 `return "wrong.service"` 骗过
   ⇒ 补了与**独立第二实现**（测试里重写一遍 cgroup 解析）的交叉核对
3. 信号转发测试用 `sleep 300` 会泄漏孤儿进程（sh fork 子进程，信号只到 sh）
   ⇒ 改 `exec sleep 300`，并加断言检测泄漏（60s → 0.52s）

### 踩到的两个坑（都记在判据注释里）

- **POSIX 环境变量不能含 NUL**：`\x00` 分隔符让 exec 直接报
  "environment variable contains NUL"，改用 `\x1f`
- **测试函数里 os.Exit 会终止整个测试二进制** ⇒ 子进程入口必须用 TestMain

全仓 `go test ./... -count=1` → 48 包 ok / 0 FAIL。
 2026-10-11 10:09:15 +08:00
JianFeeeee
33a042e4a3 chore(sdk-mirror): 同步 vendored SDK meta —— 补 SDKModule/LegacySDKModule 
把 SDK 仓 e0ee0c4 的 `meta/meta.go` 同步到主仓的镜像副本。

## 为何主仓要跟踪这一份

主仓有 13 个 SDK 文件是**镜像副本**（`chore(sdk-mirror)` 系列提交维护），
`meta/meta.go` 在其中。主仓 Go 代码通过 module 路径 import 它
（`internal/agent/core/tooldefs.go` 用 `sdkmeta`），所以它的内容必须与
SDK 仓一致 —— 否则主仓编译到的是旧常量。

## 本次同步的内容

- 新增 `SDKModule` / `LegacySDKModule` 常量
- （原注释引用了 `SDKModule` 但常量并不存在，一并补上）

两个名字都要保留的原因见该文件注释：存量插件的 go.mod 里写的仍是旧路径
（本机实测 5 个插件工作区全是 `gitcode.com/...`），识别逻辑必须两种都认。

主仓 `go build ./...` 与 `internal/agent/core` 全量测试通过。
 2026-10-10 23:27:46 +08:00
JianFeeeee
5187a62f47 feat(knowledge)!: 检索改为纯稠密向量路，去掉三路融合 
按「完全改用向量方案」的要求，SearchIn 现在只走多模态稠密路，
不再与稀疏语义路 / 词法路融合。

## 为什么必须去掉融合（实测，不是判断）

生产知识库（192 条）上，10 条带标注查询的命中率：

    改前（三路融合）  top1= 1/10  top3= 2/10
    改后（纯稠密路）  top1= 6/10  top3= 7/10

改前连条目**自己的全名**都搜不到：
`plugin_dev_sdk` 搜不到 `plugin_dev_sdk`、`homeagent_identity` 搜不到
`homeagent_identity`，用户看到的是「查什么都返回同样的几个无关条目」。

而稠密路单独打分时**全库排名 1/192**：

    the_jet_engine     → the_jet_engine_rolls-royce  0.769
    plugin_dev_sdk     → plugin_dev_sdk              0.852
    homeagent_identity → homeagent_identity          0.823

### 根因：逐路归一化把噪声抬到与信号同权

`addPath` 把每路都按**查询内最大值**归一化到 1.0 再加权：

    scores[h.id] += weight * h.score / max

于是词法路原始分只有 **0.027** 的弱信号归一化后也变成 1.0，与稠密路的
1.0 等权相加。叠加两个因素：

- jieba 把英文标识符切碎：`the_jet_engine_rolls-royce` →
  `[t h e _ j n g i r o l s - y c]`，两条**无关**文档 token 重叠 50%
- `SetMinScore(0)` 导致 186/192 条都进候选，几乎全库打分

余弦分数**本身就可比**（同空间同维度），根本不需要逐路归一化 ——
那一步当初是为「量级不同的三路」服务的，现在只剩一路，它反而成了
破坏排序的东西。

## 历史结论为何在此翻转

旧注释引的实测（仅稠密路 top-1 15% / MRR 0.271；融合后 21% / 0.376）
建立在这两个**已不成立的前提**上：

- 33 条的小规模 KB（现 192 条，含大量英文标识符）
- 稀疏 fastText 词向量（现 chineseclip 512 维多模态空间）

那段结论我没删，而是在 Search 的注释里写明「前提已变、结论翻转」，
免得后来者看到旧数字又把它改回去。

## 退化路径有意保留

未注入多模态空间时（provider 留空）仍走稀疏两路。不保留的话，
那些部署的知识库会直接变成**完全不可用** —— 比排序差更严重。
该路径行为与接入稠密路之前逐字一致（TestNoDenseSpaceKeepsLegacyBehavior）。

## 判据（都可杀变异，逐个实测）

新增 `dense_recall_quality_test.go`：

- `TestDenseRecallQuality`——带标注 10 条查询，门槛 top1≥4 且 top3≥7。
  把 denseEnabled 改成恒假 → FAIL「top1 仅 1/10」（正是退化态）
- `TestDensePathIsSoleRecall`——钉形状：稠密路必须在稀疏路之前且
  **结果真的参与组装**。第一版只查「有没有调 denseHits」，把结果赋给 `_`
  仍能骗过它；补上 `s.items[h.id]` 断言后，变异（结果不参与组装）才被杀
- `TestSearchDocReflectsDenseOnly`——防文档漂移。第一版简单搜「三路」
  会误伤（新文档解释「为何不再融合」时正当地提到它），改为检查只在
  *声称当前如此* 时才会出现的句子

## 顺带修的

- `TestDenseCrossModalRecall` 的桩把**所有未知文本**映射到同一向量，
  导致 `other` 与 `cat-photo` 正文同向、「猫」查询下 `other` 以余弦 1.0
  压过 `cat-photo` 的 0.707。那是**桩的假象不是产品缺陷**。给 other
  一个真正正交的方向（且 key 必须是 denseFor 实际传入的
  `Name + " " + Content`，写成纯 Content 会静默回落到默认向量）。
- 清掉随融合退场的死代码 `denseSpaceWeight` / `hasAnyDense`，
  并把 `vec`/`lex` 字段注释改准（它们现在只服务退化路径）。
- `rankdiag_test.go` 现在测的是**退化路径**（它不注入多模态空间），
  注释与门槛说明据此改准：实测 top-1 24% / MRR 0.358，
  别拿它当知识库的检索水平。

全仓 `go test ./...` → 48 包 ok / 0 FAIL。
 2026-10-08 21:34:30 +08:00
JianFeeeee
df865518e6 perf(memory): Introspect 507ms→11ms、ListPersons 130ms→3ms 
继续清「非常卡」。上次修完 pulse 端点后，`/kernel` 与 `/runtime` 仍各约
600ms（每 15s 一次）。这次**逐项量**而不是猜（临时探针量各子收集器）：

    memDB.Introspect      507ms   ← 主凶
    social.ListPersons    129ms
    textMem.FileCount     0.1ms
    docStore.Stats        0.0ms
    knowledge.List/Stats  0.0ms

## ① Introspect 507ms → 11ms（43×）

hotspots 的度数写成**相关标量子查询**：

    COALESCE((SELECT COUNT(*) FROM memory_block_edges e
               WHERE (e.source_id = b.id OR e.target_id = b.id) ...), 0)

EXPLAIN 是 `SCAN b`（3364 块）→ `CORRELATED SCALAR SUBQUERY` → `SCAN e`
（2829 边），即 **3364 × 2829 ≈ 950 万次行扫描**，且 ORDER BY 前必须算完
全部块的度数。

改成边表按端点 UNION ALL + GROUP BY 聚合一次，再 LEFT JOIN 回块表。
边表只扫两遍而不是 3364 遍。**新旧查询输出逐字节一致**（已 diff 验证）。

## ② ListPersons 130ms → 3ms（38×）

它走 `Recall(nil, nil, 1, "")`，而那条 full-recall 路径为了填
`result.Entities` 会加载**全部块（blockColumns 含稠密向量）**：

    Recall 全程 130ms：实体 3266 个、关系 30 条

即为了 30 条关系反序列化了 3266 个块的向量，而 ListPersons
**只看 result.Relations**。

新增 `GraphDB.RecentRelations(limit)`：与 full-recall 分支里的关系子查询
**逐字对齐**（同一 WHERE/ORDER/LIMIT，含 trait 边——过滤掉它会让特质
主体漏出人物表）。实测该查询单独 4ms。

等价性验证：新旧路径的人物列表 + 关系集**逐字节 diff 完全一致**
（56 人、同样的边）。旧路径输出是先 git stash 采样的，不是凭记忆比对。

## 验证

- `TestIntrospect_HotspotsQueryIsNotCorrelated`（源码形状）+
  `TestIntrospect_LargeGraphIsFast`（2000 块/1500 边的耗时门）。
  **两者各自独立可杀变异**（实测）：
  - 源码断言：退回相关子查询 → FAIL「必须用一次聚合」
  - 耗时门：同变异 → FAIL「149ms 超过 60ms 门槛」（修复后 11ms）

  为何源码断言要锚在返回值行而非 `Index`：注释里也提到 memory_hotspots，
  用 Index 会截到注释处、取到的片段根本没有查询——第一版就这么写错了，
  自己先红了一次才发现。
- 全仓 `go test ./... -count=1` → 48 包 ok / 0 FAIL
 2026-10-08 16:41:03 +08:00
JianFeeeee
aaf833a687 fix(proc): 关闭时等 stage 收尾，修每次 shutdown 必现的 SIGSEGV 
连续两次部署都被验证门拦下（「近 2 分钟出现 5 条 panic/fatal」）。
查出这不是新版本崩了，而是**旧进程关闭时**必崩 —— 每次 shutdown 都触发：

    fatal error: fault
    [signal SIGSEGV: segmentation violation ...]
    proc.(*Segment).descOffset
    proc.(*Segment).setDesc
    proc.(*Segment).writeLocal.func1   shmcodec.go:104
    proc.(*Segment).writeLocal
    proc.(*Segment).WriteAll
    proc.(*stageCoordinator).enter     host.go:310
    proc.(*Host).beginStage
    proc.(*coreHandler).runStage
    agent/core.(*StageHost).RunStage

## 根因：Close 只处理了「事件环」一路写者，漏了「stage 数据面」

Host.Close 里那段长注释把事件环写得非常清楚（订阅 handler 会
ring.WritePush 写共享内存，unmap 后必炸，而 recover 捕不到 runtime
fatal），也**确实**在 freeShm 前退订了。

但共享段有**两条独立写者**。beginStage 的首进者会持 stageMu 调
Segment.WriteAll 写同一块段 —— 它**不在事件环订阅里**，退订阅根本管不到它。
于是 Close 只等问题 A 就 freeShm，问题 B 继续写已 unmap 的内存。

## 修法：用 stageMu 作为「没有 stage 在写段」的判据

stageMu 的既有语义已经就是我们要等的东西（首进者取、最后离开者放，
见 beginStage/endStage 注释），不必再造一个会与它失去同步的并行状态。
`Close` 现在 unmap 前独占获取它。

另加 `closing atomic.Bool`：光「等正在进行的 stage」还不够 —— Close
释放 stageMu 之后仍可能有新 stage 进场（agent 收尾路径），那时它照写已
释放的段。beginStage 现在看到一个明确的错误，而不是撞 SIGSEGV。

## 为何这件事必须修，而不只是「已知缺陷」

它让部署验证门失效：门报的「5 条 panic/fatal」分不清是新版本坏了，
还是旧版本关闭时的既有噪声。我这两次都手工核对了 PID 才敢继续 ——
下一个部署的人不该被迫做这种考古。修掉之后，这个门才真的能拦回归。

## 验证（判据可杀变异，逐个实测）

- `TestHost_CloseWaitsForInflightStage`：stage 持锁时 Close 必须阻塞。
  删掉 `closing.Store` + `stageMu.Lock` → FAIL「未等 stage 收尾就返回」
- `TestHost_BeginStageAfterCloseRejected`：Close 后 beginStage 必须报错。
  把检查改成 `if false` → **测试进程真的 SIGSEGV 被杀**（与生产同栈）
- `go test -race ./internal/plugin/proc/` 通过
- 全仓 `go test ./... -count=1` → 48 包 ok / 0 FAIL
 2026-10-08 12:46:02 +08:00
JianFeeeee
8336509bfa perf(webui): 修星图形变活跃集的泄漏 + 加回归判据 
上一提交（3e201dd4）把 starmapTickMorph 从「每帧全量遍历」改成
starmapMorphSet 活跃集，但我漏了一处：buildChatStarmapGraph 重建图时
只重置了 starmapNodeMeshes / starmapEdgeLines，**没清空 starmapMorphSet**。

后果：旧 mesh 已从场景摘掉，却留在活跃集里，于是
- 集合随每次重建单调增长、永不归零 ⇒「空集时 O(1) 返回」的快速路径
  从此失效，正是这次优化想省掉的那笔开销又回来了
- 每帧遍历一批已经不在场景里的废弃 mesh

同时补 starmap_perf_test.go。为何用源码断言而非运行时测量：
dashboard.js 是嵌入的浏览器脚本（依赖 three.js / DOM），Node 跑不了；
而这几条都是**结构性**缺陷（循环扫全表、循环不停、每帧重建），
源码里能可靠判定，回归时立刻红。

判据可杀变异（逐个实测过，不是装饰）：
- 节流常量改名 → FAIL「缺少节流」
- morph 早退条件删掉 → FAIL「必须提前返回」
- clear() 改成 if (false) 或整行删除 → FAIL「必须无条件清空」

第三处特意断言在**重建函数体内**且是 `(?m)^\s*if \(starmapMorphSet\) ...`
（先写成全仓搜 `starmapMorphSet.clear()`，变异测试显示 `if (false)` 能骗过
它 —— 弱判据当场修强）。
 2026-10-08 12:40:43 +08:00
JianFeeeee
3e201dd4af perf(webui): pulse 端点不再全量扫描图库；修星图每帧全量开销 
用户反馈「非常卡」。实测定位到两处（都在轮询/渲染的每帧路径上）：

## 1. 后端：/memory/graph/pulse 名为轻量、实为全量

该端点自称轻量（注释写着「只回窗口内变动的实体，与完整图谱差两个数量级」），
但实现是**先调 GraphData() 取全量快照 → json.Marshal 约 3.3MB →
反序列化 → 才按时间过滤**。生产实测与全量端点**同价**：

    /memory/graph          135-147ms
    /memory/graph/pulse    144-157ms   ← 每 10s 被轮询一次

即每 10 秒白付一次全量序列化。生产库 3190 块 / 2692 边。

改法：新增 `GraphDB.BlocksChangedSince(since, limit)` —— 库侧 SQL 过滤
（`WHERE created_at >= ? OR updated_at >= ?` + LIMIT），响应体只含窗口内
的块。limit 上限保护：窗口内可能有很多块（批量迁移），而星图只需知道
「有新东西」。

接口走内置 `sdk.MemoryAPI`（非 pubsdk），与既有 GraphData 同理，
**不影响外部插件**。

## 2. 前端：星图渲染循环每帧全量遍历 + 永不停止

三处，都是我上一批星图改动引入的：

- **RAF 循环从不停**：切到聊天/终端页签、甚至页面不可见时，仍以 60fps
  跑着每帧 3190 节点的遍历。改用显式开关 + `starmapWake()` 重新点火
  （判据问「星图容器是否可见」，不用 document.hidden —— 星图可能在
  未激活的页签里，那时页面可见但星图看不到）。
- **starmapTickMorph 每帧扫全部节点**：3190 × 60fps = 每秒 19 万次
  userData 读取与分支，而绝大多数帧里「正在形变」的节点是 0 个。
  改用 `starmapMorphSet` 活跃集合，空集时 O(1) 返回。
- **标签层每帧重建 plan + measureText**：加 100ms 节流（文字层 10fps
  肉眼无差别，3D 图形仍 60fps）与 measureText 缓存（同步文字布局很贵，
  同文字同字体宽度不变）+ 缓存上限保护。

## 验证

- `blocks_changed_test.go`（新增）：窗口语义、空窗口恒 0（否则星图会每次
  轮询重放生长动画）、limit 真的封顶
- 既有 pulse 判据全过（`OnlyRecent` / `SinceWidens` / `NoVector` /
  `IgnoresFrozenLegacyNodes`）—— 改写没破坏语义。
  测试替身 `fakeGraphMemory` 同步实现新方法，且**忠实反映过滤语义**
  （偷懒返回全部会把「窗口过滤」判据架空）
- `go test ./... -count=1` → 48 包 ok / 0 FAIL
 2026-10-08 12:35:28 +08:00
JianFeeeee
9d097febc9 chore(module): 打包脚本的 SDK clone/replace 路径随 module 迁移更新 
package-linux.sh 里三处 sed 替换模式与 SDK clone 地址仍用 gitcode 形态。
module 已迁 github（仓名 homeagentsdk），这些模式串若不跟着改，
打包时会匹配不到 ⇒ **静默跳过 SDK 路径修正** ⇒ 在缺 in-repo SDK 的
环境下构建失败（或用了错误的 SDK 路径且不报错）。

属上一条 module 迁移提交的遗漏文件——它含 gitcode 形态的模式串，
但被「纯 module 改名」的自动分类漏了（模式串里同时出现 replace 与路径）。
 2026-10-08 10:41:33 +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
9036db9321 feat(memory): 图数据库自报真实读写事件，取代「按工具名猜节点」 
## 问题（生产实证）

星图的「跟随 agent 活动」此前靠**工具名词元猜节点**：把 `memory_recall`
拆成 [memory, recall] 去匹配实体名。而图谱里的实体名是**中文概念**
（小宅/对话/待命），工具名是英文 —— 两套命名空间永不交集。

实测（生产库）每个工具名命中 **0** 个节点：

    hint=memory_recall  → memory/recall  → 0
    hint=files_read     → files/read     → 0
    hint=knowledge_search → knowledge/search → 0

匹配失败后走「补齐」分支，按 mention_count 取前 8 个 ⇒ **无论 agent 在干什么，
点亮的都是同一批无关节点**（小宅/对话/待命/投递/图片/文档/插件/老大）。
这就是「星图没有读写反馈」的真身。

## 改法：让图数据库在真正读写处上报

新增 `events.EventMemoryAccess` + `GraphDB.AccessHook`，在读写入口埋点上报
**真实块 ID**（不再猜）：

| 操作 | 埋点 | 上报 |
|---|---|---|
| 读 | RecallSorted | blocks |
| 写 | commit | blocks + **created**（真正新建的） |
| 删 | DeleteEntity | removed |
| 合 | MergeBlocks | merged(from→to) + removed |

三处关键设计：

1. **钩子用独立锁** `hookMu`。用 `g.mu` 会**自死锁** —— 埋点方法已持该锁，
   而 Go 的 RWMutex 不可重入。
2. **上报在锁外**。拆 `commit`→`commitLocked` 两层解决 `defer Unlock` 的时序：
   钩子内部可能要回调内存系统（如 SSE 订阅者补数据），持锁调用必死锁。
3. **区分「新建」与「更新」**（`putBlockTx` 返回 isNew）。用 SELECT 判存在性
   而非 `RETURNING (xmax = 0)` —— 后者在**事务 + ON CONFLICT** 下报
   `no such column: xmax`（实测：autocommit 可用、包进 tx 就不可用），
   而本函数只在事务里被调用。重复提交同一事实不会重复播「生长」动画。

接线：`bootstrap.newMainAgent` 里 `memDB.SetAccessHook(...)` → `events.Bus`。
只在 `evBus != nil` 时接，把「内核进程」与「独立 CLI 工具」
（homed-graph-migrate / memgc 也用 NewGraphDB）区分开 —— 后者不该为一次
批量迁移向不存在的订阅者发几万条事件。

## 验证

- `access_hook_test.go`：钉住 commit/recall/delete 三类埋点真的触发、
  且重复提交不误报新建
- `access_hook_race_test.go`：4 写 + 4 读 + 钩子热替换并发，`-race` 下无竞态、
  无死锁；**断言事件数 > 0**（否则「钩子从未触发」也会假通过）
- 该测试起初是 flaky 的（读者可能在写者落库前查询 ⇒ 空结果不报事件 ⇒
  断言随机失败）。修法是先播种确定数据再并发读，已连跑 3 次稳定
- 生产实例端到端：CLI 注入一句话 → SSE 收到 6 条 memory_access，
  带真实块 ID 与 op/created
 2026-10-08 10:41:07 +08:00
JianFeeeee
e6c1bfa6bf fix(spawn): 子 Agent 报告如实 + 跑满预算不再丢弃成果 + 提示词补执行纪律 
三处修复，均来自生产日志实证（本机 systemd 实例，2026-10-08）。

## 1. 报告轮数在说谎（max_turns != 5 时必现）

生产日志：`spawn_child` 声明「最多 10 轮」，子 Agent 实际跑满 10 轮后被判定
「子 Agent 执行超时（超过 5 轮）」——**那个 5 是硬编码的**，与真实轮数无关。
排查时会被这个假数字带偏（我本人就先据此去查「为什么是 5」）。

改法：新增 `completed` / `reachedLimit` 两个标志如实分类收尾原因，
文案用 `maxTurns` 插值。顺带修两个边界：
- 模型返回**空文本**也算「回答完了」，此前会被误报成故障；
- 「跑满预算」不是「超时」，不再如此描述。

## 2. 跑满预算时丢弃全部中间成果

原实现直接回一句「超时」，子 Agent 前几轮已取到的工具结果**全部丢弃**。
父 Agent 拿到不可操作的信号只能重 spawn —— 生产日志里 `child_5→6→7` 正是
同一任务连试三次，每次重烧一整个上下文（也是实例内存偏高的成因之一）。

改法：新增 `salvageChildSummary()`，在**失败路径**上多做一次不带工具的调用
（`ToolChoice: "none"`），把已有成果落成文本并标注「可能不完整」。
成本权衡：多一次 LLM 调用 ≪ 父重 spawn 烧掉整个上下文。
正常完成的子任务**不会**触发它（有判据钉住，避免白花调用）。

## 3. 提示词缺「执行纪律」与「工具执行顺序」

子 Agent 的提示词原先只有 3 行，而父有 7 个章节。缺失的直接后果（生产日志）：

    child_1 done: I'll start by searching for each school's admissions catalog information.
    child_3 done: 我将逐校用官方渠道核实。先并行检索四校的招生专业目录信息。

**它把「宣告计划」当成任务完成了**——因为退出判据只看模型有没有返回 tool_calls，
而「I'll start by…」之后就不再调工具。父的提示词里早有同类先例
（【记忆清理指令】：「必须实际调用…不能只回复文本」「不要只描述计划而不执行」），
子这里一句都没有。

另缺【工具执行顺序】：同轮多个 tool_call 默认**并行**，而子不知道
「依赖前一步结果的调用必须分两轮」，多步任务因此被塞进一轮。

★ 循环判据**未改动**（它是对的：模型确实不再要求工具了）——
靠提示词让模型不要过早停止调用，而不是放宽判据。

## 验证

- 新增 `spawn_replenish_test.go`：4 组判据覆盖 max_turns ∈ {1,5,10,14}、
  成果保留、正常完成不触发收尾、日志含轮次/预算/工具名
- **变异测试**：把轮数改回硬编码 5 / 去掉收尾提炼 / 删掉子日志 → 三个变异全部被杀
- `go test ./internal/agent/core/ -count=1` 绿；`-race` 绿

注：本提交含一行随 module 迁移的 import 路径更新（spawn.go 的 agentAPI 导入）。
 2026-10-08 10:40:53 +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
476e1b1296 fix(proc): stage 锁改可重入 + 协调器结束解绑与自愈，解 qq「重复申请 stage 锁」 
## 生产现象

本机 homed（10-07 11:28~21:58）93+1 条：

	[stage] before_toolcall handler error: proc: qq.stage.invoke:
	  申请 stage 锁: proc: 插件 qq 重复申请 stage 锁（handler 内不应嵌套加锁）

qq 的 before_toolcall 是它的**权限门**，每次工具调用都跑。
被拒 ⇒ 该 handler 永不执行 ⇒ **权限门失效**。

## 走过的三条错路（记录以免重犯）

❌ 错路一：「内核没释放锁」。模板 handleStageInvoke 的加解锁完整配对
   （unlocked 标志保证只解一次），不会漏解。

❌ 错路二：「同一插件注册了两个 before_toolcall handler」。
   实测线上 qq 是单进程（pid 恒定），且
   `strings plugin.bin | grep beforeOwnToolcall` = 0 ⇒ 只有一份 handler。

❌ 错路三（我自己实现的）：把「重入即报错」改成「重入即等待」。
   ★ 同进程重入就是自己等自己 ⇒ 30s 超时死锁，比原报错更糟。
   跑判据时立刻挂 30s 才发现。**重入的正确解是可重入，不是等待。**

## 真正的根因与修法

`stageLock` 是每个协调器新建一个，而 `lockRegistry` 只 bind 从不解绑；
且 Acquire 对同插件重入直接报错。两个缺口叠加：

1. **Acquire 改为可重入**（新增 depth 计数）
   同一插件可在同一 stage 注册多个 handler（内核 RegisterStageFor 用
   append），它们并发扇出各发一次 stage.lock；同一进程内第二个进来时
   已在临界区，本就不该再取互斥量。depth 减到 0 才真正释放
   ——内层释放时若直接放锁，外层还在临界区就会被别人抢进去。
   不同插件的互斥语义完全不变。

2. **endStage 在「最后离开者」分支解绑路由**
   协调器结束时它就不该再被路由到；否则下一轮的 stage.lock 会打到
   上一轮那只可能仍 held 的锁上。

3. **endStage 补泄漏自愈**（releaseIfLeaked）
   插件异常路径（handler panic 被 recover 吞掉、RPC 写失败）会让 defer
   unlock 之前就 return，锁就永久挂着。锁的所有权在内核进程
   （这正是 ForceRelease 存在的理由），那内核就必须能收尾。

## 判据

stage_lock_reentrant_test.go（8 条）+ 改写 lock_test.go 那条旧判据。

★ 旧判据 TestStageLock_ReentrantAcquireRejected 原本要求「重入必须被拒绝」
  ——它在 2026-09 实验 9 里是对的（那时 Acquire 做成等待）。
  生产证明「拒绝」本身是错的，已改名为 ...ReentrantAcquirePassesThrough，
  并在注释里写明为什么改。

★ **变异测试抓到判据两个缺口**（判据不红 = 判据没覆盖，不是实现没问题）：
  · 去掉 releaseIfLeaked → 判据不红 ⇒ 补 TestEndStage_ReleasesLeakedLock
  · 内层 Release 直接放锁 → 判据不红 ⇒ 补 TestStageLock_InnerReleaseKeepsOuterLock
    （原来只断言最终状态，bug 在中间状态）

四个变异重做后全红：还原报错 / 去掉解绑 / 去掉自愈 / 破坏 depth。

## 部署验证

- 内核 install -m 0755 原子替换；qq 用 `hmapdev build` 重编 hmap，
  经内核接口 `plugin_install(path=…, overwrite=true)` 装（reinstalled，
  config_kept=true），再 `plgreload` 生效（pid 2643323 新进程）
- 重载后连调 5 次 qq_get_friends：**重复申请 stage 锁 0 条**
  （部署前那份日志 94 条），stage handler error 0 条
- 权限门确认在执行：5 次调用全部返回真实好友数据，非拒绝
- panic/fatal 0、39 插件、graph.db integrity ok
- 快照 /home/newqqagent/memory/pre-qq-rebuild-20261007-233032/

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
 2026-10-08 07:56:51 +08:00