jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-09-21 01:18:08 +00:00
Code Issues Packages Projects Releases Wiki Activity
345 Commits 6 Branches 27 Tags
2bc813be13c506a17de683fbf017160200e08a91
Commit Graph

345 Commits

This Branch
This Branch
All Branches
Author SHA1 Message Date
JianFeeeee
2bc813be13 feat(shm): InputChannel/OutputChannel lane 基础设施(§13.5/§13.6) 
- injectParams 加 TextRef SharedRef（兼容旧 Text 字段）
- resolveText 辅助函数：优先 SharedRef，否则内联 Text
- 核心注入方法待迁移至 resolveText
 2026-09-10 16:14:17 +08:00
JianFeeeee
9cfdfc9de8 feat(shm): arena + ContextPolicy(§13.2/§13.8) 
- unified.go: arena 分配器 (alloc/write/read/reset)
- NewHost: 分配空间含 arena
- SDK ToolDef 加 ContextPolicy string
- StageAfterToolcall 后检查 prune 策略触发 RelevanceContext.Prune
 2026-09-10 15:49:47 +08:00
JianFeeeee
772a494223 feat(ctx): ContextPolicy tool 上下文策略(§13.8) 
- SDK ToolDef 加 ContextPolicy string（默认 none / 可设 prune）
- StageAfterToolcall 后检查工具 ContextPolicy=prune → RelevanceContext.Prune
- 所有现有测试通过
 2026-09-10 15:41:23 +08:00
JianFeeeee
5608abdf5a feat(shm): Cleaner 迁移到 SharedRef(§13.4) 
- CleanerInvokeParams/Result 的 Text 改为 TextRef SharedRef
- cleanerProxy: 写 text 到 arena，传 SharedRef，读结果 SharedRef
- 插件侧 cleaner.invoke: 从 SharedRef 读 input，清洗后写回 arena 返回 TextRef
- NewHost(): 分配空间含 arena（256KB）
 2026-09-10 15:30:00 +08:00
JianFeeeee
cf098a1d4f feat(shm): arena allocator for unified region (§13.2) 
- SuperBlock 新增 arenaOff/arenaCap/arenaUsed 字段
- arenaAlloc: append-only bump 分配，offset 0 保留给空语义
- arenaWrite: 写入并返回 SharedRef（含 generation）
- arenaRead: 按 SharedRef 切片读取
- arenaReset: 压实后重置游标
 2026-09-10 14:33:44 +08:00
JianFeeeee
a8e3633174 feat(shm): ToolCall ring buffer(§13.3) — 栈帧模型 ring，push/pop 帧状态机 
- ToolCallRing: 定长帧 ring buffer (64 frames × 112B)，状态机 FREE→CALLING→READING→READY→FREE
- Reserve: 环形扫描找 FREE 帧，全忙返回 ErrToolCallRingFull 背压
- SharedRef: pack/unpack 辅助函数
- unified.go: arena 分配器（arenaAlloc/arenaWrite/arenaRead）
- 5 个单测覆盖 init/reserve/背压/find/reuse
 2026-09-10 12:33:58 +08:00
JianFeeeee
ad016e4410 feat(shm): 统一共享内存区域(§13.1) — 单 memfd 容纳 SuperBlock+StageContext+EvtRing 
- unified.go: SuperBlock 布局 + SharedRef 类型
- NewHost(): 两段 memfd 合并为单一 memfd，fd 3 = 统一区域，fd 4 = eventfd
- 子进程侧: testdata 插件从 SuperBlock 解析 ctxOff/evtOff
- streaming 测试: EvtConsumer 协程在 host.Close 前 Stop+Wait 防 SIGSEGV
 2026-09-10 11:42:22 +08:00
JianFeeeee
7a328679da feat(proc): Cleaner 跨进程修复(tool/input/output) + 共享内存安全模式 + plan §13 
- Cleaner 协议统一为 cleaner.invoke(scope,name,text)，覆盖工具/输入/输出三类
- 新增 ShmSecurityMode (safe/debug/full)，Linux 审计探针，Windows crypto nonce
- plan.md 追加 §13 步骤分组
 2026-09-10 10:21:50 +08:00
JianFeeeee
580d5f5501 feat(doc): dense vector index for unified text+media retrieval 
文档层引入稠密向量索引，与媒体检索共享同一多模态空间：
- Doc 加 DenseVec 字段（json:-，运行时计算）
- Consume/QueryScored 优先使用 denseSearchScored（brute-force cosine），
  未配置时退化到 TF-IDF 倒排检索
- buildDenseIndex 在 Agent 启动时为全部文档一次性计算稠密向量
- L0 RelevanceContext 支持 denseSpace（Prune 使用稠密余弦），
  退化到 fastText 稀疏余弦

vector 包新增 DenseCosine（[]float64 brute-force cosine）。

验证：492 篇文档 brute-force ~300ms，全部测试通过。
 2026-09-09 18:56:44 +08:00
JianFeeeee
6c2039f5c9 feat(vector): pluggable multimodal vector space 
核心暴露 MultimodalEmbedder 接口，两条路径共享同一套 L0/L2/L3
向量缓存、media.Store 坐标、QueryMemoryMediaScored 检索：
  - onnx：内嵌 ONNX 模型（CLIP 等），通过 build tag 编译
  - http：外部向量 API 服务（Jina v5 / OpenAI / 自建）

跨模态融合权重改为 CrossModalFusionConfig 可配置结构体，
移除所有模型特定硬编码（CLIP/Jina），版本切换只需改配置。

模型切换自动迁移：
  - StaleVecDigestsAll 支持全模态（image+audio+video）
  - 启动时并发重算（ONNX 4 workers / API 8 workers）
  - 修复 SQL 运算符优先级导致 kind 过滤失效的 bug

实测对比（492 篇生产文档 + 3 张真实图片）：
  - TF-IDF：MRR 0.457（精确匹配快，语义差）
  - fastText：MRR 0.530（语义中等，延迟 8ms）
  - Jina v5-omni：MRR 0.900（全面领先，延迟 40ms）
  - 中文文本→图片：Jina MRR 0.833 vs CLIP 0.611

See docs/embedding-comparison.md for full benchmark.
 2026-09-09 17:38:34 +08:00
JianFeeeee
6f8056d236 refactor(clip): CLIP 收敛为稠密 MultimodalEmbedder，不污染稀疏 Vectorizer/TF-IDF 语义 
文本相似度检索是层次化系统：TF-IDF 高频削弱加权（idf<0.1 丢弃）+
倒排剪枝（只召回共享特征者）+ cosine。CLIP 512 维稠密向量若以
map[string]float64 稀疏形式实现 vector.Vectorizer 并塞进 vector.Store，
会让 512 维全部成为倒排 key → 候选集≈全库、剪枝失效，且绕过 TF-IDF
高频削弱，与既有文本检索语义错配。

收敛：
- vector.MultimodalEmbedder 改为独立稠密接口（VectorizeDense/
  EmbedImageDense/Fingerprint/Dim/Loaded/Close），不再继承稀疏 Vectorizer
- clip.Embedder 删除稀疏垫片 Vectorize/EmbedImage/denseToVector，
  只产出稠密向量；文档/知识/上下文层继续用 TF-IDF/fastText 稀疏路径
- 分层明确：文本→文本走 TF-IDF/fastText；文本↔图像、图像↔图像走
  CLIP 稠密 QueryMedia（媒体层独立稠密余弦，原样保留）
 2026-09-09 10:26:10 +08:00
JianFeeeee
98365f3a55 feat(clip): 多模态向量器（CLIP ONNX）——文本/图像 512 维共享空间 + 媒体向量写入与重算 
- internal/memory/clip：CLIP ONNX 向量器（onnxruntime 构建标签控制，默认构建不链接 ONNX）
  - clip.New(modelDir) 加载 text.onnx/vision.onnx（输出 text_embed/image_embed [batch,512]）
  - 实现 vector.Vectorizer + vector.MultimodalEmbedder（Vectorize/EmbedImage + Dense 变体）
  - 词级 BPE tokenizer：merges 合并后词末片段带 </w> 查 vocab，与官方 encode 逐 id 对齐
  - EmbedImage：解码→resize 224→NCHW→normalize→vision session
  - Fingerprint（text+vision 文件 sha256）供模型切换检测
  - stub 版（无 onnxruntime 标签）保持默认构建行为不变
- vector/store.go：新增 MultimodalEmbedder 接口
- media.Store：新增 StaleVecDigests(currentModel)——查 vec_model 不匹配/缺失的图片
- agent core：AgentConfig.ClipEmbedder + Agent.clipEmb 接线；
  describePendingMedia 描述成功后 EmbedImageDense→SetVec；
  新增 reembedStaleMedia 启动补算历史无向量图片
- config：core.memory.media.clip_model_dir（未配置退化为现有 fastText/TF-IDF 行为）
- cmd/homed：读 clip_model_dir 加载 CLIP，失败仅记日志不阻塞启动

测试：TestSmokeLoadAndEncode（文本语义 cat>dog 0.914>physics 0.740）、
TestCrossModalAlignment（red-image vs red-text 0.063>blue -0.009，与 Python 一致）、
TestTokEnd（与官方 encode 逐 id 对齐）、TestStaleVecDigests，含 -race 全绿
 2026-09-09 10:23:31 +08:00
JianFeeeee
8c9d96e065 feat(media): media.Store 加向量存储与跨模态检索 
media.Item 新增 Vec []float64 和 VecModel 字段，视觉嵌入向量以 JSON
TEXT 存库（为什么不存 BLOB：Go 的 json.Marshal 对 []float64 是自然的，
而 SQLite BLOB 是 []byte 多一层序列化；单条最多 23KB，TEXT 够用）。

initSchema 加 ALTER TABLE 迁移 vec/vec_model 两列（幂等）。scanItem
扩展读回。新增 SetVec 和 QueryMedia 方法。

QueryMedia 对所有已嵌入媒体做余弦相似度检索，维度不一致的项自动跳过
——这是跨模态检索的核心：查询可以是图片也可以是文本，被查的媒体库
里每个 item 也有视觉向量，两者在同一空间比对，谁的相似度更高就召回谁。

配套 5 个单测覆盖：基本相似度排序、无向量项被跳过、维度不匹配过滤、
空查询安全、向量持久化正确性。
 2026-09-07 22:31:39 +08:00
JianFeeeee
e9856c8f65 feat(media): media.Item 加视觉嵌入字段，Store 加 QueryMedia 跨模态检索 
路线 3（完整跨模态检索）的媒体层基础：

- Item 新增 Vec []float64（视觉嵌入向量，JSON 序列化存库）和 VecModel
  （模型标识，用于模型切换后触发重算）
- initSchema 加 ALTER TABLE 迁移 vec/vec_model 两列（幂等，列已存在可忽略）
- scanItem 扩展读回 vec/vec_model
- SetVec(digest, vec, model) 写入向量
- QueryMedia(queryVec, model, topK)：对所有已嵌入媒体做余弦相似度检索，
  维度不一致的项自动跳过（防不同模型空间的向量被混算）

混合检索的设计意图：查询可以是图片也可以是文本（经向量化后调用 QueryMedia），
被查的媒体库里每个 item 也有视觉向量。两者在同一空间比对，谁相似度更高召回谁。
不再区分「图片查询」还是「文本查询」——向量空间的相似度自动决定。
 2026-09-07 17:11:10 +08:00
JianFeeeee
0af38a29c6 feat(vector): Vectorizer 接口加 EmbedImage，支持多模态嵌入扩展 
Vectorizer 新增可选的 EmbedImage(img []byte, mime string) (Vector, error)：
支持视觉嵌入的实现者（如 CLIP/MobileCLIP）覆写此方法；不支持的
（StaticEmbedder、TFIDFVectorizer）返回 ErrNotSupported 调用方按文本降级。

这是路线 3（完整跨模态检索）的接口基础：后续在 media.Store 里，
Describe 时同时算视觉向量并存库，QueryMedia 做跨模态混合检索。
 2026-09-07 17:00:29 +08:00
JianFeeeee
b889934bba docs: 同步仓库文档到 v1.1.1，补媒体记忆与接口扩展规则 
五处文档此前停在 v1.0.0，而 v1.1.0/v1.1.1 都已发布并在现网运行。
本轮补齐三层记忆的媒体架构、模型工具的媒体参数、通信面 method 数，
以及冻结解除后的替代约束。

## 中英双语 OVERVIEW.md

三层记忆段只写了 Context/Document/Graph 三层，而 v1.1.0 起图片/音频是
三层里的一类节点。补上媒体记忆的架构概要：CAS + 引用计数 GC + 标记格式
（描述文本才是持久语义记忆，blob 是可淘汰的缓存）+ 插件边界贯通。

## 中英双语 ARCHITECTURE.md

- 「记忆工具」表补 `memory_commit`/`doc_commit` 的 `media_digests` 与
  `sentence_text`（后者从未暴露给模型，而它是媒体绑定链的必经环节）
- 「三层记忆」段新增媒体记忆子节：CAS 设计表（寻址/完整性/写入原子性/引用/GC）、
  标记格式、可选性（`enabled=false` 时整条链路静默退化）
- 「三个通信面」从 51 改为 55 个 method，新增四个 media method 的说明
- 「SDK 四通道」代码示例补媒体注入三方法 + 与 SetToolBlocks 的区别

## plugin-interface-matrix.md

- 状态从「完成 v2」改「完成 v3」，v3 记录 v1.1.1 的接口扩展
- §二 A3 DocMemoryAPI 补 InsertWithMedia
- §二 A4 补三个媒体注入方法 + 为何不能搭 SetToolBlocks 的车
- §二 A5 补 MediaAttachment 类型 + Triple/Doc/TextEvent 的扩展字段
- §六「新获得的能力」补 SetToolBlocks 已落地、媒体入记忆、插件主动发起
  带媒体的对话
- §七 冻结检查点补第 5 条（冻结已解除，取代它的是 §九）
- 新增 §九「v1.1.x 的接口扩展规则」：冻结解除后的三条硬约束
  （只增不减签名不改 / 新增方法方向 / 模板接线六处失败链）+ 验证方式
  （存量插件 17/17、旧产物 4/4 建链、模板断言、压测 -race）

## 为何分立两笔 commit

前一笔（SDK 仓 README + 内核 README）改的是给**插件开发者**看的文本，
本笔改的是给**架构师与维护者**看的技术文档。受众与改动层次不同，
放在同一个 commit 会让追溯时看不出"文档在哪一层跟上了代码"。
 2026-09-06 15:07:14 +08:00
JianFeeeee
8cd884027f docs: 项目状态与 plan 同步到 v1.1.1，vendored SDK meta 注释对齐 SDK 仓 
三处失同步，都会让读者拿到错的现状：

## README / README_EN

「项目状态」段的最新条目还停在 v1.0.0，而 1.1.0 与 1.1.1 都已发布。补上两条，
并把顶部特性摘要与下载段的 Windows 安装器版本号一起更新（那里写死了
`HomeAgent_v1.0.0_*_win64.exe`，照着它去 release 页面找是找不到文件的）。

## plan.md §12.1

标题还是「待用户决策后执行」，而四个决策点早已全部落定并执行完毕。改为已完成，
并记下实际演进已超出当初设想的地方（这些后来都写进了 docs/git-branching.md）：
发布分支改为一个中版本一条、三级通道由 tag 区分、SDK 版本跟随核心中版本且
patch 位恒为 .0、beta 阶段不发 SDK、main 永不作发版分支。

同时修掉一处会误导追溯的陈述：§12.1 原文说 `v1.0.0` tag 指向 feature 分支中间点
`670efcd` 需要重打——那件事早已做完，现在指向 `release/v1.0.x` 上的 `9b92a04`。

## plan.md §12.5

「无 Windows 真机验证」这条仍然成立，但补一句区分：Windows NSIS 安装器从 v1.0.0
起就随每个正式版作为 release 资产发布了。**能打出包 ≠ 包里的共享内存/事件对象在
真机上能跑通**，混为一谈会让人以为这项已经关闭。

## vendored SDK meta

主仓跟踪 `third_party/homeagent-sdk/meta/meta.go`，而该文件在 SDK 仓 main 上刚补了
版本路牌的说明注释。两仓这份文件必须逐字一致——否则下次谁改了哪边说不清，
而它正是「两仓中版本对齐」这条纪律的载体。仅注释差异，无行为变化。
 2026-09-06 10:56:42 +08:00
JianFeeeee
e4be9667ec chore(meta): main 的版本路牌推到 1.2.0 
按 docs/git-branching.md §2.1，main 的 meta.Version 始终是**下一个未发布中版本**。
1.1.x 线正在发布中（release/v1.1.x 承载 v1.1.0 / v1.1.1），所以 main 指向 1.2.0。

它标记「main 正在积攒 1.2 的东西」，不表示 1.2.0 已经存在——1.2.0 没有任何 tag。
已发布的版本号一律看对应的 release/vX.Y.x 分支与 tag。

两仓同步：SDK 仓 main 也是 1.2.0（SDK 版本跟随核心中版本，见 §七.1），
而 release/v1.1.x 上 SDK 定版 1.1.0。

**此 commit 不 cherry-pick 到发布分支**（§五：版本号 bump 不跨分支搬）。
 2026-09-06 09:54:55 +08:00
JianFeeeee
1b4643089c Merge branch 'feature/sdk-multimodal' — 多模态贯通插件边界 
公开 SDK 新增媒体字段与媒体注入接口，内核实现对应 RPC 与桥接层，
text/image/audio 三条输入路径归一成一条 processInput 主干。
同步 docs/git-branching.md：SDK 版本语义、beta 不发 SDK、main 永不作发版分支。

存量插件零改动零重编（17 个 example 类型检查通过）。
 2026-09-06 09:54:03 +08:00
JianFeeeee
8c6b593a54 docs(git): SDK 仓版本语义与发版联动，并明确 main 永不作发版分支 
三条此前没写进规范、于是被我在实际操作中做错的规则：

## 一、SDK 版本号跟随核心的中版本，patch 位恒为 .0（新 §七.1）

整条核心 1.1.x 线共用 SDK 1.1.0；只有核心进入 1.2.0 这种中版本跃迁时 SDK 才升。
核心的 patch 位专用于 bugfix 与漏洞修复，这类改动不碰公开 SDK 接口，SDK 版本号
没有理由跟着动。

**为什么不逐位对齐**：SDK 版本号是插件开发者的依赖声明。若核心每发一个 bugfix
就给 SDK 推一个新号，开发者要么被迫跟版、要么怀疑自己版本过时，而接口其实一个
字都没变。让 SDK 号只在**接口可能变化的中版本边界**上跳，开发者只需关心「我在
为哪个中版本写插件」。

因此「两仓版本对齐」在本规范里指**中版本对齐**（核心 1.1.x ↔ SDK 1.1.0），
不是三位全等。核心 1.1.1 配 SDK 1.1.0 就是对齐状态。§四 的措辞同步修正。

## 二、beta 阶段不发 SDK（新 §七.2）

核心的 alpha/beta tag 不伴随 SDK 仓发版：SDK 仓在这一阶段不打 tag、不建 release。

**为什么**：beta 是核心自己的测试阶段，此时 SDK 接口尚未固定。若此刻给 SDK 发版，
插件开发者会照着一个还会变的接口写代码——那是无效开发。接口没定就没有可依赖的
契约，发出去的版本号是一个假承诺。

这条约束的对象是 **SDK 仓的发版动作**，不是核心二进制里有没有 SDK 代码。主仓用
`replace => ./third_party/homeagent-sdk`，任何核心构建都必然含 vendored SDK 源码，
那是构建机制决定的，不在约束范围内。

核心打**正式** tag 时 SDK 才随之发版（§七.3）：SDK 仓也有自己的 `release/vX.Y.x`，
定版为 `X.Y.0`，打 tag、建 release、传 5 平台 plugindev 产物。同一中版本内的后续
核心 patch 不重复发 SDK。

## 三、main 永远不是发版分支（补进 §四）

版本号 bump、打 tag、构建产物、上传附件，全部只在 `release/vX.Y.x` 上做。
**即使某个改动刚合进 main、即使 main 此刻可部署，也不从 main 打 tag。**
main 的版本号是「下一个未发布中版本」的路牌，不是任何一次发布的版本号。

这条本该是 §2.1「main 的 meta.Version 始终是下一个未发布版本」的直接推论，但
只写了状态、没写禁令，于是留下了「main 可部署 ⇒ 可以从 main 发版」的误读空间。
§三 的分支表补上 main 现值 `1.2.0` 与 1.1.x 线的 tag 历史，让路牌语义有实例可对。

## 四、公开接口改动是 feature，不是发布准备（补进 §六）

它必须走 `feature/xxx` → 合回 main → cherry-pick 到发布分支，不允许当成「发布
分支上的 bug 修复」直接提交进 release——发布分支冻结功能（§2.3），而接口是最
典型的功能面。§五 补上这条路径的命令示例，以及 SDK 仓同步发版的命令。
 2026-09-06 09:52:52 +08:00
JianFeeeee
687e5655bc feat(sdk): 多模态贯通插件边界——公开接口、内核桥接与统一输入主干 
记忆系统在 1.1.0 支持了二进制多媒体节点，但那条链路只对**内核自己**开放：
用户在 qq 发图能落进 CAS、能被记忆引用，而插件调 Commit / DocMemory().Insert
交进来的媒体一律无处安放。原因是三层都断着，且**每一层都不报错**。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## 测试

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

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

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

存量插件不需要改一行也不需要重编：新增方法由插件调用、内核实现，不调就不受影响。
17 个 example 插件源码零改动通过类型检查。
 2026-09-06 09:51:31 +08:00
JianFeeeee
e8d12db871 fix(packaging): amd64 GUI 从未走过 electron 缓存，且空壳 node_modules 被当作已安装 
干净 worktree 上打包时 GUI 被静默跳过。两个缺陷叠加，都属于「所有外层
检查都通过，只有嵌套的运行时缺失，而没有任何东西喊出来」。

## 一：electron 架构名与 Debian 架构名混用

electron 官方发布物命名用 x64/arm64，Debian 用 amd64/arm64。缓存查找
一直统一用 TAR_ARCH（amd64），于是 electron-v*-linux-x64.zip 永远命中
不到。arm64 两边恰好同名，所以上次修 arm64 GUI 架构污染（743b963）时
这个不一致没暴露。

推论：v1.0.3 的 amd64 GUI 实际是靠「回退到 host node_modules/electron/
dist」这条路组装的，不是走缓存——那条回退只在目标架构 == host 架构时
才允许，恰好成立所以没出错。干净 checkout 里没有完整 node_modules，
回退路径也没有，GUI 就消失了。

修法：单独映射 ELECTRON_ARCH（amd64→x64，arm64→arm64）。

## 二：判 node_modules 目录存在，而非判 electron 包存在

npm install 失败（离线/网络受限）会留下只有一两个条目的空壳
node_modules。原判据 [ ! -d node_modules ] 认为「已安装」，于是跳过
install → ever 读不到版本 → 缓存匹配退化到通配 → host dist 也没有 →
静默跳过 GUI。包名、目录名、变体名全部正确，只是没有 GUI。

修法：判据改为 electron/package.json 是否存在；目录在而包缺失时明确
说明「疑似上次 npm install 未完成」再重试；install 失败给出明确提示
而不是继续往下走。

顺带给 ever 加兜底：读不到已安装版本时从 package.json 的依赖声明取
数字部分（那里是 "^33.0.0" 这类范围，仅用于给缓存匹配一个提示）。

## 验证

干净 worktree（/tmp/rel104，release/v1.0.x）上重跑：
  node_modules 存在但 electron 缺失（疑似上次 npm install 未完成）
  electron 版本取自 package.json 依赖声明: 33.0.0（非精确）
  electron runtime: electron-v33.4.11-linux-x64.zip
  GUI built: build/homeagent-gui-linux-amd64 (263M, x86-64)

file -b 确认 electron 二进制为 x86-64，与目标架构一致（该硬校验由
743b963 引入，此处继续生效）。
 2026-09-05 14:58:30 +08:00
JianFeeeee
aac88ce5ee Merge branch 'feature/memory-media' — 记忆系统支持二进制多媒体节点 
四层实现 + 五个缺陷修复。方案 B+C（用户选定）：内容寻址存储 + 描述文本
作为持久语义记忆。

## 四层

L1 CAS（internal/memory/media）
  元数据进 SQLite，blob 落盘 blobs/ab/cdef…，.tmp + rename 保证不会把
  半写文件当完整内容读。Get 每次重验 digest——CAS 的全部保证都建立在
  「文件名 == 内容摘要」上，喂一张损坏的图给模型会得到无法追溯的幻觉。
  AddRef 幂等且只在真插入时才涨计数（虚高则 GC 永远不敢清理），
  DropRef 用 MAX(0, ref_count-1)。GC 两段式 + minAge 保护刚落盘还没来得及
  AddRef 的项；被引用的内容即便超容量也永不删除——宁可超限也不能悬空。

L0/L2 接入（internal/agent/core/mediaref.go）
  只捕获 data URL：http(s) 会把一次对话变成一次网络请求（超时/鉴权/SSRF）。
  digest 先 stage 后 bind——媒体在 process() 期间被捕获，而承载它的
  ContextEvent 要等 process() 返回后才 Append，此刻还没有 owner_id。
  归档时先 AddRef 到新 owner 再 DropOwner 旧的：反序会让计数瞬时归零，
  并发 GC 会把仍被引用的内容当孤儿清掉。

后台循环（internal/agent/core/medialoop.go）
  GC 定时清理让容量上限真正生效（此前 max_mb 注册了却无调用方）。
  描述生成走后台而非对话路径：视觉模型一次调用生产实测 9.6s，放在对话里
  会给每张图的回复加十几秒，而描述的价值是几个月后还能检索到——这一轮
  模型本来就直接看着图。逐条而非批量：批量拿回来是一整段文字，无法可靠
  切分回各自的 digest。默认关闭，开启后每 30s 最多 4 条。

L3 图库反查（internal/agent/core/graphmedia.go）
  只做引用不建描述节点（方案 A）：图库的实体与关系来自描述文本的 NLP
  提取，检索能力已具备；若节点名取自描述，描述重新生成后同一张图会留下
  多个语义模糊的节点。媒体实体名用「图片 <短digest>」——digest 不变则
  名字不变。CommitWithMedia 新增而非改 Commit 签名（后者有 31 个调用点）。

## 五个缺陷

1. rc.SetMediaStore 从未被调用 → L0→L2 引用转移在生产静默失效
2. 三元组全被实体名校验拒绝时仍释放引用并删文档 → 数据丢失
3. 媒体入 L3 依赖 NLP 提取器碰巧提出合规三元组 → 时好时坏
4. L3 媒体检索没有任何调用方 → 能存进去，agent 拿不出来
5. 两处数据竞争（remotedevice bufio.Writer / agentcli 共享读缓冲）

前四个都是「手工调 API 的单测无法发现」的类型：函数正确，但没接上，
或只在理想输入下正确。第 2 个做了反向验证（回退修复后测试确实 FAIL）。

## 验证

medialive 自动触发链实测（-tags medialive，源/模型/密钥由调用方经环境
变量显式指定）：只注入一个 image 事件，七个阶段全由生产代码自己触发。
真实 claude-opus-5 通过——第二轮不给图，agent 答出
「上：紫罗兰色 #8800DD / 中：蓝色 #0055EE / 下：纯红 #EE0000」。
配阴性对照：不给记忆时不该「记得」，否则阳性用例可能只是模型猜配色。

551 篇生产归档文档干跑：媒体正则零误命中；28 篇文档在旧逻辑下会被删除
而信息并未进图库，新逻辑保留。

全仓 go build / go vet / go test / go test -race 全绿，SDK 冻结 diff = 0。
 2026-09-05 13:56:57 +08:00
JianFeeeee
a7b54fef7f test(memory): 修正数据丢失回归用例的构造——它被媒体三元组修复本身弄失效了 
两个修复之间产生了耦合：TestArchiveColdDocs_KeepsDocWhenGraphWriteEmpty
的前提是「三元组全被 validEntityName 拒绝」，而同批引入的
mediaTriplesFromText 会为正文里的 [image/png <digest>] 标记产出合规的
「图片 <digest>」三元组，于是 ec=4 rc=2、绑定成功、释放引用变成正确行为，
用例的前提消失。

（注意当时 GC 断言并未触发——内容没丢，只是"引用被释放"这条断言不再
适用于该构造。）

改法：正文不再含媒体标记，媒体引用直接 AddRef 挂上。这模拟的是更危险的
组合——文档持有媒体引用，但正文里的媒体标记已在清洗中丢失，于是有引用
要释放却没有句子能承载它。那正是这个守卫要防的情形。

反向验证重做后仍成立：回退守卫 → FAIL（引用被释放 + GC 删掉了本该保留的
内容）；恢复修复 → ok。

教训：只跑针对性测试不足以发现修复之间的耦合。提交前我跑的是
internal/agent/core 与 internal/memory，当时通过是因为缺陷二尚未修完；
两个修复都落地后的第一次全仓回归才暴露它。
 2026-09-05 12:08:33 +08:00
JianFeeeee
387b28ce09 fix(memory): 媒体归档三缺陷——数据丢失、L3 入库不可靠、L3 检索未接线 
自动触发链实测（medialive）连续暴露的三个缺陷，全部是「手工调 API 的
单测无法发现」的类型。附带该实测本身。

## 缺陷一：三元组全被拒时仍释放引用并删文档（数据丢失）

archiveColdDocs 只检查 len(triples) > 0 就释放媒体引用、删除文档。
但 Commit 会静默跳过实体名不合法的三元组（validEntityName 要求
2–50 字符），于是「无错但一条也没写进去」真实发生：

  [agent] doc→graph: doc_xxx → 0 entities, 0 relations
  [media] 文档 doc_xxx 入图库，释放 1 个媒体引用（描述已留在图库）
  被记忆引用的内容被 GC 删除了（清 1 条/318 字节）

图库里没有任何句子承载引用，文档也被删，blob 被 GC 回收 → 图片与描述
彻底消失。我在上一层写的注释「Commit 之后引用已挂到 graph_sentence」
是错的：ec=0 rc=0 时它什么也没挂。

修法（用户选定 B+A）：
  B. ec==0 && rc==0 时保留文档、跳过归档——归档的实质是「信息从 L2
     搬到 L3」，搬不过去就不该删源，下轮再试。
  A. bindSentenceMedia 返回实际绑定数，commitTriplesWithMedia 透出为
     mediaBound；释放前四路判断（查引用出错→保守不释放／本无引用→无需
     释放／mediaBound==0→保留并记录原因／否则释放）。宁可留一条悬空
     引用（内容还在，可由后续一致性检查清理）也不能丢内容。

反向验证：旧行为下新测试确实 FAIL，报「引用被释放了」+「GC 删掉了本该
保留的内容」；恢复修复后 PASS。

## 缺陷二：媒体入 L3 依赖 NLP 提取器运气（可靠性）

媒体能否进图库，取决于提取器碰巧从描述文本里提出合规三元组。实测 LLM
的 477 字图片描述只产出「水平 -分割-> 成」，obj 仅 1 字被拒 → 整条媒体
记忆进不了图库。表现为「阶段 5 时好时坏」，取决于描述文本。

但媒体自身的 digest / mime / 描述都是确定的，不该受提取器支配。

新增 parseMediaMarkers + mediaTriplesFromText：从文档正文的媒体标记
直接产出确定三元组，先于 NLP 提取。同一份真实文档由 0 entities 0
relations 变为 ec=4 rc=2 且拿到句子 id。

三个设计点：
  - 实体名用「图片 <短digest>」而非描述：描述会被重新生成（换视觉模型、
    补描述），若名字取自描述，同一张图会在图谱上留下多个节点。digest
    不变则名字不变，长度也天然合规。
  - SentenceText 用原始标记段，保证 bindSentenceMedia 的正则必然能反解
    到 digest——绑定从概率事件变成确定行为。
  - 描述为空时仍产出「类型」三元组：描述是后台异步补的，媒体节点不该
    因为还没描述就不存在于图谱。
  - summarizeForEntity 按 rune 截断而非字节：按字节切会破坏 UTF-8，
    图库里会留下乱码实体名。同时清 Markdown 强调符。

这是过渡方案，用户已定：下个 feature 换多模态嵌入后不再依赖
「描述文本 → 提取三元组 → 图谱节点」这条链路。

## 缺陷三：L3 媒体检索没有任何调用方（接线缺失）

第四层实现的 RecallMediaForSentence / mediaContextForSentences 从未被
调用——媒体能存进 L3、能反查，但 agent 拿不出来。实测第二轮 agent 显式
调了 doc_query，回答「没有找到那张图片的任何记录」。

接两个入口：
  - buildMemoryContext（自动注入，每次 LLM 调用都走）
  - memory_recall 工具结果末尾（显式查询）

关系行只有实体名和关系类型，看不出「这条记忆当时还带了一张图」，
媒体挂在句子上，必须经 关系→句子→media_refs 反查。

一处折返：最初直接用 injected.Relations 取 sentence_id，测试失败。
Indexer.BuildContext 刻意把 Relations 置 nil（自动注入只给实体索引以省
token，细节留给 memory_recall）。改为用命中的实体名再查一次关系，
深度固定 1——媒体是「这条记忆当时带的图」，顺关系网扩散只会带出无关
媒体并挤占 token。

## medialive 自动触发链实测

internal/agent/core/medialive_test.go，medialive build tag，默认
go test 不收录。源/模型/密钥全部由调用方经环境变量显式指定，缺任何一项
Skip 并列出缺哪个——刻意不提供 fallback，猜一个 base_url 可能打到调用者
机器上不相干的服务，而失败会被误报成「媒体记忆有问题」。

  MEDIALIVE_BASE_URL=... MEDIALIVE_API_KEY=... \
  MEDIALIVE_MODEL=... MEDIALIVE_ADAPTER=... \
  go test -tags medialive ./internal/agent/core/ -run TestMediaLive -v

只注入一个 image 事件，之后七个阶段全由生产代码自己触发：CAS 落盘 →
引用绑定 → 描述生成 → L0→L2 转移 → L2→L3 绑定 → GC 保护 → 第二轮召回。
另有阴性对照：不给记忆时不该「记得」，否则阳性用例的通过可能只是模型
猜常见配色。上游不可用时 Skip 而非假 PASS。

真实 claude-opus-5 实测通过：第二轮不给图，agent 答出
「上：紫罗兰色 #8800DD / 中：蓝色 #0055EE / 下：纯红 #EE0000」。

## 测试

graphmedia_test.go 新增 8 例：数据丢失回归（反向验证过）、mediaBound
计数、媒体标记解析、实体名生成、描述截断、确定性三元组必然可入库、
关系→句子映射、L3 检索接线（自动注入与显式查询两路）。

全仓 go build / go vet / go test 通过，internal/agent/core 与
internal/memory 全绿，SDK 冻结 diff = 0。
 2026-09-05 12:03:30 +08:00
JianFeeeee
775d9e8a2e fix(memory): core.New 漏接 rc.SetMediaStore，L0→L2 引用转移在生产从未生效 
RelevanceContext.transferMediaRefs 依赖 c.mediaStore，而该字段只有
SetMediaStore() 能设置。搜遍全仓非测试代码，调用点为零——core.New() 里
没有，cmd/homed/main.go 里也没有。

上一层（f855893）把 AgentConfig.MediaStore 接到了 Agent.mediaStore，
漏了 rc 这一路。

后果是静默的：Prune 归档时 c.mediaStore 为 nil，transferMediaRefs 直接
return，而携带引用的 ContextEvent 已被归档删除 → 引用永久悬空在
context owner 上、计数永不归零 → 对应 blob 永远不会被 GC 回收。

## 为什么测试没抓到

mediaref_test.go 里我手工调了 rc.SetMediaStore(ms) 才测转移逻辑。
**测试验证了函数正确，没验证它被接上了。** 与 findPluginPID 那次同一
个教训：测了一件不会自然发生的事。

## 顺带全字段审计

写脚本比对 AgentConfig 的 32 个字段与 New() 函数体的引用情况，
确认无第二处漏接。
 2026-09-05 12:02:34 +08:00
JianFeeeee
968b01f26e fix(plugins): 修复隔离全量测试暴露的两处数据竞争 
-go test ./... -race 全仓复验暴露的 7 处 race、5 个失败测试，全部定位。
两处独立缺陷，互不相关。

## 缺陷一（remotedevice，8 处 race）：连接写无串行化

WARNING: DATA RACE
  Read at 0x... by goroutine 28:
    bufio.(*Writer).Available() / writeFrameHeader / PushData
  Previous write at 0x... by goroutine 27:
    bufio.(*Writer).Flush() / writeFrame / handleWS

同一连接的 bufio.Writer 被两条并发路径写：
  - handleWS 主循环：读到设备帧后回写 hello_ack/bind_ack/pong
  - PushJSON/PushData：agent→设备的下发路径，可来自任意 goroutine

bufio.Writer 不是线程安全的。不加锁就在 WriteByte/Flush 上撞——这
不是理论风险，TestWSPushDataAudio 的异步 PushData 与 handleWS 的
hello_ack 回写并发时被 -race 稳定抓到。

修法：wconn 增加 wmu（sync.Mutex），PushJSON/PushData 拿锁后整条
下发（start + N 个 chunk + end）持锁——设备侧按协议串行聚合，中途
被插帧会破坏协议顺序。handleWS 的 hello_ack/bind_ack/pong 也改走
同一把锁（wsWriteLocked 封装，避免调用方绕过）。设备已离线时不回写。

关键点：不能只锁 Push* 不锁 handleWS——那只是把竞争挪了个位置。

## 缺陷二（agentcli，1 处 race）：共享读缓冲被并发读写

WARNING: DATA RACE
  Write at 0x... by goroutine 26:
    os.File.Read / (*linuxPty).Read / reader
  Previous read at 0x... by goroutine 25:
    runtime.slicecopy / readLoop

readLoop 创建 buf := make([]byte, ReadBufSize) 传给 reader goroutine
（t.session.Read(buf) 持续覆写），自己又在读到结果后
copy(data, buf[:r.n])——同一缓冲被读写并发。Go 的 pty 读走 OS 层
fd，专门在 reader 写下一段时读，跑 -race 稳定复现。

修法：readResult 携带 data field，reader 每次读完后把数据复制进自己
分配的切片再随结果传递，读取与拷贝之间不再共享任何可变状态。原 buf
保留（仍由 reader 独享用于 OS 读），readLoop 不再从其中 copy。

## 验证

  - 两个插件包 -race -count=2 全过
  - 全仓 go build / go vet / go test 通过
  - 全仓 go test ./... -race：32 包全过，0 DATA RACE，0 FAIL
  - SDK 冻结 diff = 0

其中 remotedevice 的 TestScreenseeEndToEnd / TestComputeruseEndToEnd
/ TestClipboardEndToEnd 原本因 race 挂，修后恢复全绿。
 2026-09-05 07:26:10 +08:00
JianFeeeee
6190a5a587 fix(plugins): 修复隔离全量测试暴露的两处数据竞争 
-go test ./... -race 全仓复验暴露的 7 处 race、5 个失败测试，全部定位。
两处独立缺陷，互不相关。

## 缺陷一（remotedevice，8 处 race）：连接写无串行化

WARNING: DATA RACE
  Read at 0x... by goroutine 28:
    bufio.(*Writer).Available() / writeFrameHeader / PushData
  Previous write at 0x... by goroutine 27:
    bufio.(*Writer).Flush() / writeFrame / handleWS

同一连接的 bufio.Writer 被两条并发路径写：
  - handleWS 主循环：读到设备帧后回写 hello_ack/bind_ack/pong
  - PushJSON/PushData：agent→设备的下发路径，可来自任意 goroutine

bufio.Writer 不是线程安全的。不加锁就在 WriteByte/Flush 上撞——这
不是理论风险，TestWSPushDataAudio 的异步 PushData 与 handleWS 的
hello_ack 回写并发时被 -race 稳定抓到。

修法：wconn 增加 wmu（sync.Mutex），PushJSON/PushData 拿锁后整条
下发（start + N 个 chunk + end）持锁——设备侧按协议串行聚合，中途
被插帧会破坏协议顺序。handleWS 的 hello_ack/bind_ack/pong 也改走
同一把锁（wsWriteLocked 封装，避免调用方绕过）。设备已离线时不回写。

关键点：不能只锁 Push* 不锁 handleWS——那只是把竞争挪了个位置。

## 缺陷二（agentcli，1 处 race）：共享读缓冲被并发读写

WARNING: DATA RACE
  Write at 0x... by goroutine 26:
    os.File.Read / (*linuxPty).Read / reader
  Previous read at 0x... by goroutine 25:
    runtime.slicecopy / readLoop

readLoop 创建 buf := make([]byte, ReadBufSize) 传给 reader goroutine
（t.session.Read(buf) 持续覆写），自己又在读到结果后
copy(data, buf[:r.n])——同一缓冲被读写并发。Go 的 pty 读走 OS 层
fd，专门在 reader 写下一段时读，跑 -race 稳定复现。

修法：readResult 携带 data field，reader 每次读完后把数据复制进自己
分配的切片再随结果传递，读取与拷贝之间不再共享任何可变状态。原 buf
保留（仍由 reader 独享用于 OS 读），readLoop 不再从其中 copy。

## 验证

  - 两个插件包 -race -count=2 全过
  - 全仓 go build / go vet / go test 通过
  - 全仓 go test ./... -race：32 包全过，0 DATA RACE，0 FAIL
  - SDK 冻结 diff = 0

其中 remotedevice 的 TestScreenseeEndToEnd / TestComputeruseEndToEnd
/ TestClipboardEndToEnd 原本因 race 挂，修后恢复全绿。
 2026-09-05 05:53:17 +08:00
JianFeeeee
28fc833a6f feat(memory): L3 图库媒体反查 + 修 L2→L3 引用泄漏 
媒体记忆四层收尾。方案 A：只做引用，不建媒体实体节点。

## 为何不把媒体建成图库实体

图库里的实体与关系全部来自**描述文本**的 NLP 提取——描述经
mediaSummaryForEvent 进 L0 事件的 Input，随归档进 L2 文档的 Content，
蒸馏时提取器自然从描述文字里抽出实体和关系。检索能力已经具备。

若再把媒体本身建成节点，节点名只能从描述里取，而描述会被重新生成
（换个视觉模型、补一次描述，名字就变了），于是同一张图会在图谱上留下
多个语义模糊的节点。代价换不来能力。

所以这一层只做一件事：**反查**。图库句子写着「[image a1b2c3d4e5f6]
一张紫蓝红三色带图」，要能从这条句子取回那份字节。

## CommitWithMedia：新增方法而非改签名

Commit 有 10 个非测试调用点 + 21 个测试调用点。为一个多数调用方都不需要
的返回值改全部签名不划算。新增 CommitWithMedia 返回
map[句子文本]sentences.id，Commit 内部转调同一份落库逻辑。

## digest 靠正则从文本反解

三元组由 NLP 提取器从纯文本产出（nlp.ToMemoryTriple 只填 Subject/
Relation/Object/Confidence/SentenceText），提取链路上没有任何位置能塞进
结构化的 digest。要贯通就得改 internal/nlp 的整条数据流。而媒体标记本身
是我们自己按固定格式写进文本的，反解是最省的可靠做法。

配套加 media.ResolvePrefix：文本里是 12 位短 digest（完整 64 位会把一行
撑爆且无助人眼辨认），media_refs 主键要完整 digest。

**前缀歧义视为错误而非"取第一个"**：挂错引用会让 GC 删掉仍被引用的内容。
完整但不存在的 digest 也报错，否则调用方会挂一条孤儿引用。

## 顺带修掉 L2→L3 的引用泄漏

这是上一层（f855893）留下的缺口：我当时只处理了 L0→L2 的引用转移，
漏了 L2→L3 这一跳。archiveColdDocs 调 docStore.Remove(doc.ID) 时不注销
媒体引用——文档一旦消失就再没有任何东西能告诉我们它引用过哪些 digest，
media_refs 里那条记录永久悬空、引用计数永不归零，对应 blob 永远不会被
GC 回收。

新增 releaseDocMedia。L2→L3 这一跳是**释放**而非转移，因为图库存的是从
描述文本抽出的实体与关系，不再持有字节；媒体此时已完成使命。

顺序有讲究：必须在 commitTriplesWithMedia 之后释放。那一步已把引用挂到
graph_sentence owner 上，先销后挂会让引用计数瞬时归零，此时若后台 GC
正在跑就会把内容当孤儿清掉。

## 顺带修 Pending 的排除逻辑遗漏（承上一提交）

## 测试

graphmedia_test.go 11 例。核心是 TestBindSentenceMedia_RoundTrip：
写入 → 提交 → 从句子 id 反查 digest → 取回字节逐字节比对 → 跑 GC(0)
确认被引用的内容不被清。

其余覆盖：正则不误命中普通方括号（[注意]/[TODO] 不能当 digest，否则会拿
假前缀去 ResolvePrefix）、无法补全的 digest 不挂引用、媒体关闭时全链路
静默 no-op、releaseDocMedia 释放后 GC 真能回收、200 个样本的前缀补全
要么唯一命中要么明确报歧义。

TestCommit_StillWorksAfterRefactor 记录一个既有行为：重复提交时
entitiesCreated 不归零，因为 SQLite 的 ON CONFLICT DO UPDATE 也算一行
affected。用 main 分支的 graph.go 单独跑过基线确认与本次重构无关，
该字段只用于日志，故记录现状不改行为。

全仓 go build / go vet / go test 通过，internal/agent/core 与
internal/memory 全部 -race -count=2 通过，SDK 冻结 diff = 0。
 2026-09-04 22:52:30 +08:00
JianFeeeee
74a24f93d7 feat(memory): 媒体 GC 与描述生成两条后台循环 
补齐媒体记忆的最后两块：容量上限真正生效，描述文本成为持久语义记忆。

## mediaGCLoop：让容量上限不再形同虚设

CAS 的 GC 只在被显式调用时执行，Put 路径不触发它。此前配置项
core.memory.media.max_mb 注册了却没有任何调用方——一次 see_video 抽 10 帧，
帧本身在工具结果被 Prune 后就没人引用了，若无人清理会一直堆在磁盘上。

现在按 gc_interval（默认 6h）周期调 GC(gc_min_age)。两个不变量：
  - 有引用的内容永不删除，即使超容量（宁可超限也不断引用）
  - gc_min_age（默认 1h）保护刚 Put 还没来得及 AddRef 的项——它们
    refcount 也是 0

## mediaDescribeLoop：描述才是能活过 GC 的那部分

blob 会被容量 GC 淘汰，而描述留在 media 表里，并经 mediaSummaryForEvent
写进 L0 事件、随归档进 L2 文档、经蒸馏进 L3 图库。于是「那张紫蓝红三色
带图」在原始字节早已被清掉之后仍然可被检索到。

复用既有的视觉回退链（resolveModalFallback + chatModalFallbackBatch），
不新造一套模型调用。

三个刻意的决定：

  - **走后台而非入库时同步**：视觉模型一次调用生产实测 9.6s。放在对话
    路径上会让每张图都给回复加十几秒，而描述的价值是几个月后还能检索到，
    不是这一轮——这一轮模型本来就直接看着图。
  - **逐条而非批量**：批量拿回来是一整段文字，无法可靠切分回各自的
    digest（模型未必按序号输出，也可能把两张图合并成一句）。宁可多几次
    往返也要保证「描述 ↔ digest」的对应关系确定。
  - **默认关闭**（describe_on_ingest=false）：它消耗视觉模型配额。开启后
    每 30s 最多处理 4 条，不跟对话抢额度。

失败处理分三类：
  - 网络抖动/配额 → 不标记，下轮重试
  - 空回复 → 视作失败（上游剥离媒体时通常回空，与 modalfallback 同理）
  - 不可描述（kind=other、blob 已丢失）→ 标记 described_by=unsupported/
    content-missing，退出队列

## 顺带修掉 Pending 的一个真缺陷

测试写出来才发现：Pending 原先只看 `description = ''`，于是被标记为
described_by=unsupported 但 description 仍空的项**每轮都会被重新取出来
重试**，永久占着 LIMIT 的名额，真正需要描述的新项永远轮不到。
改为同时要求 described_by 也为空。

这是「先写断言再看它是否成立」抓到的——原本我以为标记一下就够了。

## 测试

medialoop_test.go 7 例：两条循环在禁用时立即返回（nil store / 零间隔 /
describe 关闭三种形态，不留空转 goroutine）、GC 清孤儿保留有引用项、
minAge 保护新项、无可用源时不误标记、不可描述大类被标记后退出队列。
media_test.go 补 1 例专测 Pending 的排除逻辑。

全仓 go build / go vet / go test 通过，SDK 冻结 diff = 0。
 2026-09-04 22:00:03 +08:00
JianFeeeee
2879e76883 fix(test): 崩溃隔离测试误杀同机生产插件，且断言无效 
## 现象

生产 homed 的 editdoc 子进程从 9-03 起被 SIGKILL 9 次，间隔完全不规律
（126~485 分钟），全部发生在无工具调用的空闲期。查过 OOM（dmesg/
journalctl -k/cgroup oom_kill 全为 0）、systemd 内存限制（MemoryMax=
infinity）、cron/timer、内核自身的 StopAll 路径、agent 执行过的 cmd_run
命令，以及 Pdeathsig 绑创建线程的可能——全部排除。

## 真因：测试杀了生产的进程

用 ftrace 的 signal_generate tracepoint 挂监视器后抓到发送者 cmdline：

  /tmp/go-build.../plugins.test -test.run=TestRealPlugin_CrashDoesNotKillKernel

findPluginPID 用**全系统** `pgrep -f plugin.bin`，然后只比"exe 路径含
editdoc"。生产实例的 /home/newqqagent/plugins/editdoc/plugin.bin 也满足
这个条件，谁先被 pgrep 列出来就杀谁。9 次 kill 全部落在有人跑 go test
的时段——18:18:30 那次正是一轮 `go test ./... -race` 的窗口。

之前几轮排查一直在生产实例内部找原因，方向从一开始就错了：杀手在仓库里。

## 更严重的是这个测试本身无效

旧断言是"SIGKILL 之后内核仍存活"。可内核本来就活着——即使信号发错了
对象（杀了生产实例的插件），测试内核的插件压根没死，断言照样通过。
**它在测一件没发生的事**，同时把生产环境打坏了，而绿色的测试结果掩盖了
这一切。这也是它能连续 9 次造成生产故障却从没被注意到的原因。

## 修法

findPluginPID 增加 root 硬约束：/proc/<pid>/exe 必须以测试自己的 plgDir
为前缀，且是目标插件，两道条件同时成立才算命中。root 为空直接 t.Fatal
——这不是可选过滤器，是防误杀的前提。

  - 用 exe 而非 cmdline：cmdline 可被进程自行改写，exe 符链由内核维护。
  - root 先过 EvalSymlinks：/tmp 在部分发行版上是符链，不归一化会让前缀
    比较永远不命中，退化成静默 Skip（那样测试就白跑了）。

断言改成两步：先轮询确认目标进程真的退出（3s 上限），再验内核未被连带。
两步都成立才能证明隔离生效。

## 验证

修复后跑 TestRealPlugin_CrashDoesNotKillKernel：
  - 杀的是 pid=3448366，exe 在 /tmp/hc_integration_3823918128/plugins 下 ✓
  - 生产 editdoc pid 测试前后均为 3362892，存活时长连续 ✓
  - 四个 TestRealPlugin_* 全部 PASS
 2026-09-04 21:45:17 +08:00
JianFeeeee
98dcb2556c fix(test): 崩溃隔离测试误杀同机生产插件，且断言无效 
## 现象

生产 homed 的 editdoc 子进程从 9-03 起被 SIGKILL 9 次，间隔完全不规律
（126~485 分钟），全部发生在无工具调用的空闲期。查过 OOM（dmesg/
journalctl -k/cgroup oom_kill 全为 0）、systemd 内存限制（MemoryMax=
infinity）、cron/timer、内核自身的 StopAll 路径、agent 执行过的 cmd_run
命令，以及 Pdeathsig 绑创建线程的可能——全部排除。

## 真因：测试杀了生产的进程

用 ftrace 的 signal_generate tracepoint 挂监视器后抓到发送者 cmdline：

  /tmp/go-build.../plugins.test -test.run=TestRealPlugin_CrashDoesNotKillKernel

findPluginPID 用**全系统** `pgrep -f plugin.bin`，然后只比"exe 路径含
editdoc"。生产实例的 /home/newqqagent/plugins/editdoc/plugin.bin 也满足
这个条件，谁先被 pgrep 列出来就杀谁。9 次 kill 全部落在有人跑 go test
的时段——18:18:30 那次正是一轮 `go test ./... -race` 的窗口。

之前几轮排查一直在生产实例内部找原因，方向从一开始就错了：杀手在仓库里。

## 更严重的是这个测试本身无效

旧断言是"SIGKILL 之后内核仍存活"。可内核本来就活着——即使信号发错了
对象（杀了生产实例的插件），测试内核的插件压根没死，断言照样通过。
**它在测一件没发生的事**，同时把生产环境打坏了，而绿色的测试结果掩盖了
这一切。这也是它能连续 9 次造成生产故障却从没被注意到的原因。

## 修法

findPluginPID 增加 root 硬约束：/proc/<pid>/exe 必须以测试自己的 plgDir
为前缀，且是目标插件，两道条件同时成立才算命中。root 为空直接 t.Fatal
——这不是可选过滤器，是防误杀的前提。

  - 用 exe 而非 cmdline：cmdline 可被进程自行改写，exe 符链由内核维护。
  - root 先过 EvalSymlinks：/tmp 在部分发行版上是符链，不归一化会让前缀
    比较永远不命中，退化成静默 Skip（那样测试就白跑了）。

断言改成两步：先轮询确认目标进程真的退出（3s 上限），再验内核未被连带。
两步都成立才能证明隔离生效。

## 验证

修复后跑 TestRealPlugin_CrashDoesNotKillKernel：
  - 杀的是 pid=3448366，exe 在 /tmp/hc_integration_3823918128/plugins 下 ✓
  - 生产 editdoc pid 测试前后均为 3362892，存活时长连续 ✓
  - 四个 TestRealPlugin_* 全部 PASS
 2026-09-04 21:44:05 +08:00
JianFeeeee
f855893d1c feat(memory): 媒体接入 L0/L2——digest 挂到对话事件，归档时引用随之转移 
在 a822674 的 CAS 层之上把媒体真正接进记忆链路。此前 CAS 只是个孤立的
存储包，没有任何写入方。

## 媒体进入对话有两条路，两条都只把文字留给记忆

  1. 用户直接发图 → processMediaInput → mediaToBlocks
     ContextEvent.Input 只存 alt 文本（"[从 qq 收到了 image]"），
     base64 随 message 数组发给模型后就丢了。
  2. 插件注入 → SetToolBlocks → process.go 的 mediaMsg
     ToolResultItem.Output 只存那句 "[已将图片注入后续对话] /tmp/x.png"。

于是下一轮起，模型能看到的只剩一句路径或一句 alt。那个文件被删、被覆盖，
或者本来就是 /tmp 下的临时产物，连线索都断了。

现在两条路在同一处收口（captureBlockMedia）：从 ContentBlock 的 data URL
取出字节存进 CAS，digest 挂到当轮 ContextEvent。

## 改动

internal/agent/core/mediaref.go（新）
  - captureBlockMedia：ContentBlock → CAS。只处理 data URL——http(s) URL
    拿不到字节就无法内容寻址，而「下载它再存」会把一次对话变成一次网络
    请求（超时、鉴权、SSRF 全来了），不在本层解决。
  - stage/drainMediaDigests：媒体在 process() 期间被捕获，而承载它的
    ContextEvent 要等 process() 返回后才 Append——此刻还没有 owner_id，
    故先缓存。与既有 pendingMedia 同一手法，同受 a.mu 保护。
  - bindEventMedia：双向落地。evt.Media 让事件记得引了什么（随
    context.json 持久化），media_refs 让 CAS 知道谁在引用（GC 的判断依据）。
    只写一边的话，要么 GC 误删仍被引用的内容，要么孤儿永远清不掉。
  - mediaSummaryForEvent：把已有描述拼成一行写进 Input。这是方案 C 的
    落点——**描述文本才是持久语义记忆，blob 只是缓存**。blob 可能被容量
    GC 淘汰，但描述会一直留在 L0/L2/L3 的文本里，让「那张紫蓝红三色带图」
    几个月后仍可被检索。

ContextEvent 新增 ID 与 Media 两个字段，都是 omitempty：
  - ID 懒生成，只有真要挂媒体时才赋值。绝大多数对话没有媒体，全量生成
    会让每条事件都多一个字段进 context.json。
  - 存量 context.json 读回来两字段皆空，不影响任何既有行为（有测试）。

RelevanceContext.Prune 归档时转移引用（transferMediaRefs）：
  **先挂到归档文档、再注销原事件引用**。顺序不能反——先销后挂会让引用
  计数瞬时归零，若此刻后台 GC 正在跑就会把仍被记忆引用的内容当孤儿清掉。
  为此把 Prune 内的局部类型 scored 提为包级 scoredEvent（局部类型无法
  出现在方法签名上）。

media 包新增 OwnerContext/OwnerDocument/OwnerGraphSentence 常量：
  owner_kind 进了主键，拼错一个字符就是一条永远对不上的孤立引用——
  AddRef 不报错，DropOwner 也永远匹配不到。

## 配置

core.memory.media.enabled（默认 true）、.dir、.max_mb（2048）、
.gc_interval（6h）、.gc_min_age（1h）。

关闭后全链路静默跳过，对话行为与本特性上线前完全一致（有测试）。
mediaStore 为 nil 时同理——它是记忆增强，不是对话必需品，开不起来
只记一条 warning 不阻止启动。

## 测试（11 例）

入库与 MIME 归类、http URL 跳过、nil store 全链路 no-op、音视频混合、
stage/drain 清空语义、懒生成 ID、描述作为持久记忆、**归档转移期间内容
始终可读且 refcount 不归零**、无媒体存储时归档照常、context.json
向后兼容往返。

全仓 go build / go vet / go test 通过，SDK 冻结 diff = 0。

## 尚未接入

L3 图库的 graph_sentence owner（常量已备好，无写入方）、
描述生成的后台任务（Pending() 已就绪，尚无消费者）、
媒体 GC 的定时触发（配置项已注册，尚未接 ticker）。
 2026-09-04 20:53:32 +08:00
JianFeeeee
5c214cac23 fix(packaging): arm64 GUI 塞了 x86-64 electron——按目标架构取运行时并强制校验 
## 现象

v1.0.0 与 v1.0.1 的 arm64 full/client 包里，homed 与 waiter 都是正确的
aarch64，但 GUI 目录下的 electron 是 x86-64。实测从 gitcode 下载的
homeagent-full_1.0.1_arm64.deb：

  usr/bin/homed                    ELF 64-bit ARM aarch64   ✓
  usr/bin/waiter                   ELF 64-bit ARM aarch64   ✓
  usr/lib/homeagent-gui/electron   ELF 64-bit x86-64        ✗

在 arm64 机器上装完，双击 GUI 得到 Exec format error。

## 根因

build_gui 无条件 `cp -r "$gui_dir/node_modules/electron/dist"/*`，而那里
永远是 **host 架构**（本机 x64）。目录名 homeagent-gui-linux-arm64 只是
命名，内容从未跟着目标架构变。

这与 v1.0.0 arm64 缺 homed 是同一类错误：**产物名声称的架构与实际内容
不符**，且都因为没做交叉验证而漏过整个发布流程——包名对、目录名对、
主二进制对，只有一个嵌套的运行时是错的，没有任何一环会喊出来。

## 修法：三层取 + 一道强制校验

1. 优先从 electron 缓存取目标架构的 zip
   （~/.cache/electron/<hash>/electron-v<ver>-linux-<arch>.zip）。
   版本号从已安装的 node_modules/electron/package.json 读，保证运行时
   与 app 依赖一致。
2. 回退到 host node_modules/electron/dist 前**先比对架构**：只有目标
   架构 == host 架构才允许；否则打印缺哪个 zip、该放哪里，然后跳过 GUI。
3. 最后用 `file -b` 校验 electron 二进制的实际架构必须匹配目标架构，
   不符就删掉 GUI 目录并跳过。

第 3 步是关键。前两步是「尽量拿对的」，第 3 步是「绝不发错的」——
宁可不发 GUI，也不发装了跑不起来的包。`GUI built:` 日志行也加上架构
标注，日常构建就能看见。

## 验证

下载 arm64 electron 运行时（electron-v33.4.11-linux-arm64.zip，106MB，
unzip -t 无错，解出的 electron 确认为 ARM aarch64）放入缓存后重打包，
三个 arm64 deb 实测：

  server   homed=aarch64  waiter=aarch64
  full     homed=aarch64  waiter=aarch64  electron=aarch64
  client                  waiter=aarch64  electron=aarch64
  amd64 对照                              electron=x86-64

arm64 tar.gz 从 120M 涨到 125M，也印证运行时换成了正确架构。
 2026-09-04 20:12:35 +08:00
JianFeeeee
9b7b2675da fix(packaging): arm64 GUI 塞了 x86-64 electron——按目标架构取运行时并强制校验 
## 现象

v1.0.0 与 v1.0.1 的 arm64 full/client 包里，homed 与 waiter 都是正确的
aarch64，但 GUI 目录下的 electron 是 x86-64。实测从 gitcode 下载的
homeagent-full_1.0.1_arm64.deb：

  usr/bin/homed                    ELF 64-bit ARM aarch64   ✓
  usr/bin/waiter                   ELF 64-bit ARM aarch64   ✓
  usr/lib/homeagent-gui/electron   ELF 64-bit x86-64        ✗

在 arm64 机器上装完，双击 GUI 得到 Exec format error。

## 根因

build_gui 无条件 `cp -r "$gui_dir/node_modules/electron/dist"/*`，而那里
永远是 **host 架构**（本机 x64）。目录名 homeagent-gui-linux-arm64 只是
命名，内容从未跟着目标架构变。

这与 v1.0.0 arm64 缺 homed 是同一类错误：**产物名声称的架构与实际内容
不符**，且都因为没做交叉验证而漏过整个发布流程——包名对、目录名对、
主二进制对，只有一个嵌套的运行时是错的，没有任何一环会喊出来。

## 修法：三层取 + 一道强制校验

1. 优先从 electron 缓存取目标架构的 zip
   （~/.cache/electron/<hash>/electron-v<ver>-linux-<arch>.zip）。
   版本号从已安装的 node_modules/electron/package.json 读，保证运行时
   与 app 依赖一致。
2. 回退到 host node_modules/electron/dist 前**先比对架构**：只有目标
   架构 == host 架构才允许；否则打印缺哪个 zip、该放哪里，然后跳过 GUI。
3. 最后用 `file -b` 校验 electron 二进制的实际架构必须匹配目标架构，
   不符就删掉 GUI 目录并跳过。

第 3 步是关键。前两步是「尽量拿对的」，第 3 步是「绝不发错的」——
宁可不发 GUI，也不发装了跑不起来的包。`GUI built:` 日志行也加上架构
标注，日常构建就能看见。

## 验证

下载 arm64 electron 运行时（electron-v33.4.11-linux-arm64.zip，106MB，
unzip -t 无错，解出的 electron 确认为 ARM aarch64）放入缓存后重打包，
三个 arm64 deb 实测：

  server   homed=aarch64  waiter=aarch64
  full     homed=aarch64  waiter=aarch64  electron=aarch64
  client                  waiter=aarch64  electron=aarch64
  amd64 对照                              electron=x86-64

arm64 tar.gz 从 120M 涨到 125M，也印证运行时换成了正确架构。
 2026-09-04 20:12:35 +08:00
JianFeeeee
e2d04a31a7 docs(git): 发布分支改为一个中版本一条，补三级发布通道规范 
## 一个中版本一条发布分支

原规范写 release/vX.Y.Z（含 patch 位），实践中 1.0.0 与 1.0.1 各建了一条
分支，导致同一条 1.0.x 发布线被切成互不相连的碎片——追溯时无法用一条
分支看完整条线的演进。改为 release/vX.Y.x，patch 位用 x 占位，
承载该中版本全部 patch 直到下一条中版本分支切出。

## 三级发布通道（alpha / beta / 正式）

通道由 tag 区分而非分支：三者共用同一条 release/vX.Y.x。

  alpha  vX.Y.Z-alpha.N  功能齐了未充分验证    仅内部自测
  beta   vX.Y.Z-beta.N   alpha 问题已修        小范围试用
  正式   vX.Y.Z          通过验证可上现网      所有用户

这是 semver 标准预发布语义（1.1.0-alpha.1 < 1.1.0-beta.1 < 1.1.0），
版本比较逻辑天然认得，无需额外约定。允许跳级但要在发布说明写明理由；
alpha/beta 产物不上现网——预发布通道的存在就是为了不拿 24/7 服务冒险。

## 回流仍是 cherry-pick

明确不改 merge：merge 会把已发布的版本号带进 main，与「main 的
meta.Version 始终是下一个未发布版本」直接矛盾。

新补一条：修复落地当天要 pick 到所有活跃 feature 分支，否则它们合回
main 时可能带回旧代码（2026-09-04 的 stage 双重解锁修复即同时 pick 到
main 与 feature/memory-media）。

## 运维纪律沉淀

把今天走通的部署流程写进第四节，其中两条是踩过的坑：
  - 备份配置库用 sqlite3 .backup 而非 cp（WAL 模式下 cp 可能拿到
    不一致快照）
  - install -m 0755 替换而非 cp（原子 rename，不写坏运行中的进程镜像）
健康检查列出六项，含「一次真实对话」与「fatal error 计数为 0」。

## 当前分支对齐

第三节更新为 2026-09-04 的实际状态，并记录 1.0.x 的 tag 历史表
（含 v1.0.2 未使用的原因、v1.0.3 直接跳正式 tag 的理由）。
按 patch 号命名的历史发布分支标注为应当删除的遗留形态。
 2026-09-04 20:11:19 +08:00
JianFeeeee
aa3ff5a12f fix(proc): stage 协调器双重解锁——内核本体 fatal 崩溃的真因 
## 现象

2026-09-04 06:56:18 生产 homed 主进程直接死亡，退出码 2，
带走全部 27 个子进程插件。

  fatal error: sync: unlock of unlocked mutex
  proc.(*Host).endStage(...)             host.go:189
  proc.(*coreHandler).runStage.func1()   stage.go:94
  core.(*StageHost).RunStage.func1()     stages.go:190

stage.go:94 与 stages.go:190 各有一层 recover，专为「插件出错不拖垮内核」
而设，却全部失效：**sync.Mutex 的双重解锁走 runtime fatal，不是 panic，
recover 结构上就拦不住**。这就是本次「插件崩溃被隔离」的设计没能生效、
内核本体整体死亡的原因。

## 根因

endStage 把 coord.leave()（递减 inflight、判定「我是最后离开者」）放在
coordMu 临界区**之外**，而摘除 h.coord 在临界区**之内**，留出窗口：

  A.endStage: leave() → inflight 1→0, last=true，尚未摘除 h.coord
  B.beginStage: 看到 h.coord != nil，以「后到者」身份 enter，inflight 0→1
                （后到者按设计不取 stageMu）
  A.endStage: h.coord = nil；stageMu.Unlock()                    ← 第 1 次
  B.endStage: leave() → inflight 1→0, last=true → stageMu.Unlock() ← 第 2 次 💥

B 从未持有 stageMu，却因挂进一个正在收尾的协调器而被判成「最后离开者」，
对同一把锁解了两次。崩溃前一行日志是 config_list_keys 的结果——那一刻
正好有 stage 扇出，与竞态窗口重合。

## 修复

把「递减 inflight → 判定最后离开者 → 摘除 h.coord」收进同一个 coordMu
临界区，后到者再不可能挂进已收尾的协调器。为此把 leave() 拆成：
  - depart()：纯计数，由 endStage 在 coordMu 内调用
  - finish()：共享段回读 + arena 压实，在 coordMu 外、但仍在
    stageMu.Unlock() 之前（先放锁会让下一轮 stage 在回读未完时改写共享段）
leave() 保留给单测。

同一函数的第二个隐患一并修掉：首进者的 enter()（含 WriteAll 写共享段）
原先在 coordMu 之外，后到者可能拿到 coord 就去读**写了一半**的段。
现在 enter() 在锁内完成。

beginStage 错误路径的 stageMu.Unlock() 必须保留并已加注释说明：
runStage 的 defer endStage(coord) 是在 beginStage 返回 err 的检查**之后**
才注册的，这条路径上没有任何人会替它解锁，漏掉就是整个 stage 通道永久卡死。

锁序 stageMu → coordMu；endStage 只解锁 stageMu 不获取，无环。

## 验证

反向验证：把 host.go stash 回旧版跑新测试 → fatal error: sync: unlock of
unlocked mutex；恢复修复 → 通过。测试抓的确实是这个缺陷。

5 个回归用例（host_stage_test.go）：
  - 后到者不复用已收尾的协调器（直接构造那个时序，不靠调度巧合）
  - 8 worker × 40 轮并发进出（旧实现下整个测试二进制 fatal 而非 FAIL）
  - 同阶段多插件扇出共用一个协调器、仅最后离开者解锁
  - 50 轮串行不泄漏（少解锁会在第二轮卡死）
  - 四阶段序列 pre_action→chat→after_toolcall→post_action

internal/plugin/... 全量 -race -count=2 通过。

## 同类缺陷审计（本 commit 未改动其他文件，仅记录结论）

针对「recover 拦不住的 runtime fatal」这一整类做了全仓审计：

1. 跨函数持锁（本缺陷的形状，脚本枚举 Lock/Unlock 不配对的函数）
   - proc/lock.go 的 Release/ForceRelease 同样「只 Unlock 不 Lock」，
     但两者都在 ownerMu 下先检查 held/owner 再解锁，非持有者直接返回，
     不存在双解锁路径。
   - 其余 22 处 Lock/Unlock 计数不等的函数逐一复核：全部是多分支早退各自
     解锁（waiter 的 goto nextMessage、sidecar.call 的五个错误分支、
     lua adapterPool 的 cond.Wait 池模式等），配对正确。
2. 并发 map 读写（同样是 runtime fatal）
   - 16 处「无锁访问 map」全部复核为安全：Locked 后缀约定（orderedLocked、
     defsLockedRegisterSource）、调用方持锁（document 的 addSummary/
     removeDoc/loadAll、registry 的 runStopHandlers/runOnRemoveHandlers）、
     或启动期单线程（knowledge.scanAll、static_embedder 构造后只读）。
3. close of closed channel
   - 全仓仅 sidecar.go 有同名变量的两处 close(ch)，但作用于不同集合成员，
     且 Close() 前有 readerWg.Wait() 与 stopped 标志，reader 侧已 delete
     出 pending，不会双关。
   - 各插件 stopCh 的 close：healthcheck 用 select 守卫、clawhubadapter 用
     stopOnce、evtring 用 running 标志、timer 交给 StopHandler 单次调用。
     agentcli.Stop() 是裸 close(p.stopCh) 无幂等守卫，但 Registry 的六处
     Stop 调用点都在同一把 r.mu 下先 delete(r.plugins)+摘 r.instances 再
     Stop，不存在二次调用路径——记录为「依赖调用方约定」而非当前缺陷。
4. WaitGroup 误用：未发现 Add 出现在 goroutine 体内的形状。
5. 全仓 go test ./... -race：零 DATA RACE、零 FAIL。
 2026-09-04 18:45:19 +08:00
JianFeeeee
e272c686d3 fix(proc): stage 协调器双重解锁——内核本体 fatal 崩溃的真因 
## 现象

2026-09-04 06:56:18 生产 homed 主进程直接死亡，退出码 2，
带走全部 27 个子进程插件。

  fatal error: sync: unlock of unlocked mutex
  proc.(*Host).endStage(...)             host.go:189
  proc.(*coreHandler).runStage.func1()   stage.go:94
  core.(*StageHost).RunStage.func1()     stages.go:190

stage.go:94 与 stages.go:190 各有一层 recover，专为「插件出错不拖垮内核」
而设，却全部失效：**sync.Mutex 的双重解锁走 runtime fatal，不是 panic，
recover 结构上就拦不住**。这就是本次「插件崩溃被隔离」的设计没能生效、
内核本体整体死亡的原因。

## 根因

endStage 把 coord.leave()（递减 inflight、判定「我是最后离开者」）放在
coordMu 临界区**之外**，而摘除 h.coord 在临界区**之内**，留出窗口：

  A.endStage: leave() → inflight 1→0, last=true，尚未摘除 h.coord
  B.beginStage: 看到 h.coord != nil，以「后到者」身份 enter，inflight 0→1
                （后到者按设计不取 stageMu）
  A.endStage: h.coord = nil；stageMu.Unlock()                    ← 第 1 次
  B.endStage: leave() → inflight 1→0, last=true → stageMu.Unlock() ← 第 2 次 💥

B 从未持有 stageMu，却因挂进一个正在收尾的协调器而被判成「最后离开者」，
对同一把锁解了两次。崩溃前一行日志是 config_list_keys 的结果——那一刻
正好有 stage 扇出，与竞态窗口重合。

## 修复

把「递减 inflight → 判定最后离开者 → 摘除 h.coord」收进同一个 coordMu
临界区，后到者再不可能挂进已收尾的协调器。为此把 leave() 拆成：
  - depart()：纯计数，由 endStage 在 coordMu 内调用
  - finish()：共享段回读 + arena 压实，在 coordMu 外、但仍在
    stageMu.Unlock() 之前（先放锁会让下一轮 stage 在回读未完时改写共享段）
leave() 保留给单测。

同一函数的第二个隐患一并修掉：首进者的 enter()（含 WriteAll 写共享段）
原先在 coordMu 之外，后到者可能拿到 coord 就去读**写了一半**的段。
现在 enter() 在锁内完成。

beginStage 错误路径的 stageMu.Unlock() 必须保留并已加注释说明：
runStage 的 defer endStage(coord) 是在 beginStage 返回 err 的检查**之后**
才注册的，这条路径上没有任何人会替它解锁，漏掉就是整个 stage 通道永久卡死。

锁序 stageMu → coordMu；endStage 只解锁 stageMu 不获取，无环。

## 验证

反向验证：把 host.go stash 回旧版跑新测试 → fatal error: sync: unlock of
unlocked mutex；恢复修复 → 通过。测试抓的确实是这个缺陷。

5 个回归用例（host_stage_test.go）：
  - 后到者不复用已收尾的协调器（直接构造那个时序，不靠调度巧合）
  - 8 worker × 40 轮并发进出（旧实现下整个测试二进制 fatal 而非 FAIL）
  - 同阶段多插件扇出共用一个协调器、仅最后离开者解锁
  - 50 轮串行不泄漏（少解锁会在第二轮卡死）
  - 四阶段序列 pre_action→chat→after_toolcall→post_action

internal/plugin/... 全量 -race -count=2 通过。

## 同类缺陷审计（本 commit 未改动其他文件，仅记录结论）

针对「recover 拦不住的 runtime fatal」这一整类做了全仓审计：

1. 跨函数持锁（本缺陷的形状，脚本枚举 Lock/Unlock 不配对的函数）
   - proc/lock.go 的 Release/ForceRelease 同样「只 Unlock 不 Lock」，
     但两者都在 ownerMu 下先检查 held/owner 再解锁，非持有者直接返回，
     不存在双解锁路径。
   - 其余 22 处 Lock/Unlock 计数不等的函数逐一复核：全部是多分支早退各自
     解锁（waiter 的 goto nextMessage、sidecar.call 的五个错误分支、
     lua adapterPool 的 cond.Wait 池模式等），配对正确。
2. 并发 map 读写（同样是 runtime fatal）
   - 16 处「无锁访问 map」全部复核为安全：Locked 后缀约定（orderedLocked、
     defsLockedRegisterSource）、调用方持锁（document 的 addSummary/
     removeDoc/loadAll、registry 的 runStopHandlers/runOnRemoveHandlers）、
     或启动期单线程（knowledge.scanAll、static_embedder 构造后只读）。
3. close of closed channel
   - 全仓仅 sidecar.go 有同名变量的两处 close(ch)，但作用于不同集合成员，
     且 Close() 前有 readerWg.Wait() 与 stopped 标志，reader 侧已 delete
     出 pending，不会双关。
   - 各插件 stopCh 的 close：healthcheck 用 select 守卫、clawhubadapter 用
     stopOnce、evtring 用 running 标志、timer 交给 StopHandler 单次调用。
     agentcli.Stop() 是裸 close(p.stopCh) 无幂等守卫，但 Registry 的六处
     Stop 调用点都在同一把 r.mu 下先 delete(r.plugins)+摘 r.instances 再
     Stop，不存在二次调用路径——记录为「依赖调用方约定」而非当前缺陷。
4. WaitGroup 误用：未发现 Add 出现在 goroutine 体内的形状。
5. 全仓 go test ./... -race：零 DATA RACE、零 FAIL。
 2026-09-04 18:43:05 +08:00
JianFeeeee
4ef3371701 test(memory): 媒体存储的压力、冒烟与长稳测试 
在 a822674 的 CAS 层之上补齐三类验证。

## 压力测试（stress_test.go，9 例）

核心不是吞吐数字，而是并发下的不变量。为此写了 checkRefIntegrity：
用 SQL 对比每个 digest 的 ref_count 与 media_refs 实际行数。这条对不上
就意味着 GC 的判断依据是错的——计数偏低会误删有引用的内容，虚高会让
孤儿永远清不掉。所有并发用例收尾都验它。

  - 32 goroutine 并发 Put 同一内容 → digest 一致、磁盘只 1 份
  - 400 个不同内容并发入库 → 无丢条目、逐条回读无内容串位
  - 24 worker × 40 轮引用增删风暴（含故意重复 AddRef 验并发下的幂等）
  - GC 与读写并发 1.5s → 实测 11508 次 Put / 604 轮 GC，受保护内容零失败
  - Describe 与 Search/Pending 并发 → 无 database is locked
  - 容量上限持续加压 → 上限 256KB 收尾 98KB，有引用项全存活
  - 重度 churn 后重开 → 磁盘文件数 == 元数据条数，无双向孤儿
  - 4MB 单文件往返（see_video 10 帧 × 2MB 是现实上限附近）
  - data URL 往返 ×50（SetToolBlocks 给出的实际形态）

-race -count=3 干净。

## 冒烟测试（smoke_test.go，6 场景）

走真实数据路径：真 PNG（自建 IHDR/IDAT/IEND + zlib）、真 data URL、
真 sha256、真 GC、真重启，而不是随机字节。

  - 同一张截图连问 5 轮 → 磁盘 1 份、5 个 context 引用
  - see_video 6 帧内容各异 → 各存一份、共享一个 owner
  - 描述落库后按关键词检索命中（方案 C 最关键的一环：blob 可被淘汰，
    描述会长期留在记忆里）
  - L0→L2 归档时引用从 context owner 转到 document owner，期间内容可读
  - 别的工具留下的一次性图被 GC 清掉，被记忆引用的一个不少
  - 全生命周期跨重启：描述、引用、内容、磁盘一致性全部完好

第一次跑挂在「6 帧只搜到 5 条」，看着像存储丢帧，实际是夹具的
palette[(variant+y*3/h)%5] 只有 5 色，variant=0 与 5 产出逐字节相同的
PNG，被 CAS 正确去重。已把 variant 写进像素保证帧间真不同，并把这段
经过记进注释——误报本身证明了去重在工作，也证明冒烟确实有能力发现
「帧数对不上」这类问题。

冒烟原先是 internal/memory/media/smoke/ 下带 //go:build smoke 的独立
main，得记着加 -tags smoke 才跑得到，那种早晚被忘掉。已搬成普通测试，
随 go test ./... 一起跑，冒烟的意义才真正成立。

## 长稳测试（soak_test.go，-short 下跳过）

60 秒五路混合负载。实测：put=281885 get=1644084 gc=9142
describe=53875 search=23268 refOps=187926，零失败。收尾 20 个受保护项
内容字节一致、ref_count 全为 1；8MB 上限下实际占用 139KB / 48 条，
说明 28 万次写入产生的孤儿被持续清理，无无界增长。

描述者从 Pending() 取项再 Describe()，GC 随时可能在这两步之间清掉它。
这是正常竞态，故忽略 unknown digest 并注明原因；5 万多次调用没把它
升级成计数错位，印证了 Describe 对已删项返回错误而非静默建条目的选择。

全仓 go build / go vet / go test 通过，SDK 接口冻结 diff 为 0。
 2026-09-04 11:29:18 +08:00
JianFeeeee
a82267484a feat(memory): 内容寻址媒体存储（CAS）——图记忆支持二进制多媒体节点的底座 
此前四层记忆全是纯文本载体，没有任何一层能存二进制：
  L0 ContextEvent  — Input/Response/ToolResults[].Output 全 string
  L1 text.Event    — 同上
  L2 document.Doc  — Summary/Content/Tags 全 string
  L3 图库           — sentences.text TEXT UNIQUE，节点身份就是那串文本

于是 multimodal 插件注入的图只在本轮对话内可见（走 message 数组，不经
记忆），下一轮起只剩 ToolResultItem.Output 里那句
"[已将图片注入后续对话] /tmp/x.png"——一条路径字符串。那个文件被删或
被覆盖之后连线索都断了。

## 为何内容寻址而不是存路径

- 路径会失效。/tmp 下的探针图、下载缓存、别的进程的临时产物，记忆里
  留个路径等于留个悬空指针。
- 同一内容常被反复注入（连问几轮同一张截图、see_video 相邻帧高度相似），
  按 sha256 寻址天然去重。
- 内容即身份，与 L3 图库 sentences.text UNIQUE 思路一致：文本节点用文本
  本身做身份，媒体节点用内容摘要做身份。

## 结构

元数据（SQLite media.db）与内容（磁盘 blobs/ 两级前缀分桶）分离，不把
blob 塞进库：单张图动辄几 MB，塞进去让每次 VACUUM/备份都拖着几百 MB 走，
WAL 也会迅速膨胀。

  media(digest PK, kind, mime, size, width, height, origin_path, tool,
        description, described_by, ref_count, first_seen, last_seen)
  media_refs(digest, owner_kind, owner_id, created_at, PK 三列)

digest 既是主键也是文件名，所以没有 Path 字段——路径由 digest 推导，
不落库（落了就又是个会失效的引用）。origin_path 仅供人类溯源，注释里
明确标注不可用于读取。owner_kind 预留 context/document/graph_sentence。

## 几处刻意的决定

- Get 强制校验 digest：CAS 的全部保证建立在「文件名 == 内容摘要」上，
  位翻转或外部误改必须被发现——把损坏的图喂给模型只会得到无从追溯的幻觉。
- 先写 .tmp 再 rename：中途崩溃不留半个 blob 被当成完整内容读走。
- AddRef 幂等：只有真插进 media_refs 才递增，否则计数虚高会让 GC 永远
  不敢清。DropRef 用 MAX(0,...) 兜底防负数。
- Put 的空描述不冲掉已有描述（先到的可能来自更强的模型），但尺寸/工具名
  这类前一次缺失的信息会被补写。Describe 是显式操作，允许覆盖。
- GC 两段 + minAge 保护：刚 Put 还没 AddRef 的项 refcount 也是 0，minAge
  防「落地后还没挂上就被清掉」。有引用的项永不删除，即使超容量——宁可
  超限也不断引用。

## 测试

21 例，覆盖去重 / MIME 归类 / 损坏检测 / 无残留临时文件 / AddRef 幂等 /
计数不为负 / DropOwner / GC 保留有引用项 / minAge 保护 / 容量淘汰 /
描述覆盖与补写策略 / Search 按描述与 kind 过滤 / Pending / data URL
往返 / Stats / 跨重启持久化。

本 commit 只加存储层，尚未接入 L0/L2/L3 与描述生成。
 2026-09-04 11:03:36 +08:00
JianFeeeee
6bf34e051b fix(release): upload_assets.py 按 go.mod 定位仓库根，不再数 dirname 
脚本从 scripts/ 移到 deploy/scripts/ 后目录深度 1→2，而两层 dirname
是写死的，于是资产目录解析成 deploy/dist/release，上传直接
FileNotFoundError（v1.0.1 首次上传即因此失败）。

这与 v0.7.2 的 2c5f9ff 把 package/ 移到 deploy/packaging/ 打断
build.sh 的 PROJECT_ROOT 是同一个坑：目录搬家没更新相对路径。改成
向上找 go.mod，以后脚本放哪都不会错。

顺带把两个静默失败改为显式报错：目录不存在、目录下无可识别产物
（原先前者抛裸 FileNotFoundError，后者会打出 ALL OK 却一个都没传）。
 2026-09-04 10:34:51 +08:00
JianFeeeee
4f31f942a5 fix(build): arm64 交叉编译补 CXX——「刻意不设 CXX」的注释判断是错的 
build.sh 的 linux/arm64 分支此前刻意不设 CXX，注释理由是「设了会让
Go 用 aarch64 的 g++ 去链接，而它对 host 产生的 .o 报 file format
not recognized」。

那个判断是错的。那个报错的真因是 cmd/{homed,waiter}/*.syso（x86-64
COFF Windows 资源对象）被 Go 无条件链进了目标，与 CXX 无关。四组对照：

  syso 在   + 无 CXX → Relocations in generic ELF (EM: 183)
  syso 在   + 有 CXX → 000000.o: file format not recognized
  syso 隐藏 + 无 CXX → Relocations in generic ELF (EM: 183)
  syso 隐藏 + 有 CXX → 成功，ELF aarch64

两个条件缺一不可。之前诊断时只单独试了其中一个，得出错误结论后写进
注释固化了下来，于是 arm64 的 homed 一直编不出（v1.0.0 发布时 arm64
deb 里只有 waiter/initconfig）。

本脚本的 hide_syso_for_target 已处理 syso 那半，这里补上 CXX 那半。
实测 v1.0.1：build.sh linux/arm64 直接产出 ELF aarch64，arm64 的
full/server deb 里 homed 与 waiter 均为 aarch64。
 2026-09-04 10:24:55 +08:00
JianFeeeee
3907347cac fix(multimodal): 媒体改挂独立 user message，落实「注入后续对话」的原意 
插件三个工具的返回文案一直写着「已将图片注入后续对话」，b777322 的提交
说明也写着「模型在下一轮 LLM 请求里直接看到图」。但实现是把 block 挂在
tool message 的 content 数组上——role=tool 上的多模态 content 不被当作
可视内容。

同一张图、同一个模型、三轮实测：

  图在 user message        → 3/3 读到，prompt_tokens 7089
  图在 tool message        → 0/3（模型答「我没能读到这张图」），tokens 7967
  tool 纯文本 + 后接 user  → 3/3 读到，tokens 7570

tool message 那轮 token 反而更高，说明 base64 确实进了上游，只是模型看
不到它。这解释了为什么此前只有回退链（转文字进 tool message 的纯文本
content）能用，而「主模型直接看图」这条路从 b777322 起就没通过——当时
的验证只看了 prompt_tokens 涨了 8500，没有校验模型答案对不对。

改为：tool message 保持纯文本结果，媒体另起一条紧随其后的 user message
承载，并在首个 text 块标注 [以下是 <tool> 注入的媒体内容]，避免模型误
以为是用户新发的图。位置必须紧跟 toolMsg，中间插入其他消息会让
tool_call_id 配对断开。

验证（生产，答案预先封存、生成时不读）：
- AUTO 源 vision=true 直视路径：随机三色带 → 答「紫、蓝、黄」，与封存
  答案一致，日志无 modal fallback（确实走的直视），耗时 9.6s
  （回退链同一用例需 ~90s，省掉了绕视觉模型一圈）
- see_video 6 帧直视：23s（回退链合包版 131s，逐块版 363s），模型正确
  描述测试图卡的彩条布局、彩虹带滚动与计数器递增
- 负向：AUTO 源改回 vision=false，回退链仍正常转写，模型如实标注来源
 2026-09-04 07:49:30 +08:00
JianFeeeee
09071dc235 fix(multimodal): 修多模态假成功 + 落地视觉回退链 + see_video 帧数语义 
## 起因

生产盲测：模型调 multimodal_see_picture 后声称看到了图，实际一个字
都没收到。工具却返回「[已将图片注入后续对话]」。

链路：core.llm.model=AUTO → llmsproxy 按优先级选 big-pickle(prio=100)
→ 转 opencode zen。llmsproxy 的 opencode.lua 明写着：

    -- zen 上游 schema 只接受 text content part（无视觉/音频能力）
    if part.type ~= nil and part.type ~= "text" then  -- 丢弃

判据：256x256 纯红 PNG，带图与不带图的 prompt_tokens 都是 256。
图片贡献零 token，即根本没进上游。

内核序列化与注入链本身是对的（Message.MarshalJSON 正确产出 content
数组，SetToolBlocks → IOManager → ConsumeToolBlocks → toolMsg.Blocks
全通）。缺的是「主模型能否消费这些块」这一判断——内核此前完全没有
多模态能力的概念（grep supportsVision|multimodal 在 agent/ 零命中）。

这与 v1.0.0 修的 output_send 假成功同类：告诉调用方成功而实际未送达。

## 1. 能力声明

新增 core.llm.sources.<name>.vision / .audio（走既有 sourceFieldDefs，
WebUI 配置页自动出现），types.LLMSource 与 api.BaseConfig 同步加字段。

新增 agentAPI.ModalProvider 接口 + ProviderSupportsVision/Audio 判定：
未实现该接口的 provider 一律按不支持处理。保守侧是刻意的——宁可多走
一次文字回退，也不能把图默默扔给会剥掉它的上游。

为何是声明而非探测：探测需额外真实调用且结果不稳定（取决于 AUTO 当次
路由到哪）；而 200 响应 + 相同 token 数从响应侧无法区分「看到了但没
内容」和「被剥掉了」。

## 2. 回退链（modalfallback.go）

实现了 config/registry.go 里注册但从未被读取的 image/audio
fallback_provider + fallback_model（此前 0 处读取点）。

prepareToolBlocks 在 process.go 注入前判定：能直视就原样透传；不能就
调声明了该能力的源转写成文字，带 [由 X 转写，非当前模型直接感知] 标注。

几处刻意的设计：
- 逐模态判定，不一刀切。很多视觉模型能看图但听不到音频，全部降级会
  白白把可直视的图变成二手描述
- 混合场景下转写文字作为 text 块并入 native，两部分同时到达模型
- 配置指向未声明能力的源时拒绝并继续找——照用只会重演静默剥离
- 未配 fallback_provider 但某源声明了 vision 时自动扫出来用；静默失败
  比多找一个能用的源更糟
- 空回复算失败。上游剥掉媒体后模型往往回「我没看到图片」或空串，两种
  都说明回退链也没真看到
- 多媒体块按模态合包为一次请求（见下）

## 3. 批量合包（生产实测驱动的返工）

首版逐块调用，生产 see_video 6 帧实测：4 帧里 3 帧超时，整轮 363 秒。
改为按模态合包一次请求后同一用例 131 秒、6/6 成功。

顺带把 modalFallbackTimeout 从 90s 提到 180s：生产经网关转
claude-opus-5 看一张 400x400 图要 ~81s，90s 贴着上限。
多张时 detail 默认 low 控体积，单张用 high 看细节；插件显式给了
detail 则尊重它。

## 4. see_video 帧数语义

fps=1/N 是频率（每 N 秒一帧）不是数量。20s 视频实测：
frames=4 → 5 帧、frames=10 → 2 帧、frames=1 → 20 帧，要得越多拿得越少；
长视频下 frames=4 会产出 时长/4 帧，靠 i>=9 的 break 兜着才没炸上下文，
而那个 break 用的是 ReadDir 索引，跳过条目后与实际帧数错位。

改为 ffprobe 取时长 → fps=N/时长 + -frames:v N 硬封顶。
0.4s/3s/20s/120s × frames=1/2/4/7/10 全部精确。

极短视频的坑：fps=1 在 0.4s 素材上产出 0 帧（不足一秒抽不出），所以
时长探测失败时不能退化成 fps=1，改为不传 -vf 只靠 -frames:v。

## 验证

- modalfallback_test.go 14 例：直视透传 / 回退转写 / 无源如实报告 /
  未实现接口按不支持 / 混合模态拆分 / 空回复算失败 / 块数上限 /
  多图合一次调用 / detail 策略 / 拒绝未声明能力的源 / 未配置时自动扫源
- go test ./... 全绿，go vet 无警告
- 生产盲测（答案预先封存、生成时不读）：随机三色带 → 模型答
  「紫、蓝、红」，与封存答案完全一致
- 负向验证：拿掉回退源后模型如实回答「没看到图片内容」并引用工具返回
  的配置提示，且主动纠正了上一轮的答案
- 生产 see_video 6 帧：单次转写，模型正确描述测试图卡的计数器递增与
  彩虹带滚动
 2026-09-04 06:25:51 +08:00
JianFeeeee
9b92a04230 docs: 文档与发布脚本同步到 v1.0.0 子进程架构 
README/架构文档仍在描述 C ABI 动态库加载，与 v1.0.0 实际实现不符。
新用户按文档走会去做 -buildmode=c-shared，产物新内核根本不加载。

README.md / README_EN.md：
- 设计要点补子进程架构段（三面通信、崩溃自愈、真热重载）
- 代码结构 plugin/ 描述：.so 动态加载器 → 子进程加载器
- 项目状态补 v1.0.0 条目（6 类缺陷 + 实测数字），v0.9.0 标注 ABI 已退场
- 新增「下载」章节：三变体对照 + 各平台包格式 + macOS 限制

assets/docs/{zh,en}/ARCHITECTURE.md：
- 四种加载方式表：外部 .so/C ABI → 外部子进程/握手+stdio JSON-RPC
- 加载流程改写为 exec.Command → 继承 fd → 握手 → init → start
- 内置 vs 外部对照表 7 行更新
- 新增「子进程插件的三个通信面」小节，含每个面的选择理由

assets/docs/{zh,en}/OVERVIEW.md：插件系统段落改写

deploy/ 发布脚本三处回归（v0.7.2 的 2c5f9ff 把 package/ 移到
deploy/packaging/ 使目录深度 1→2，但没改相对路径，此后两个版本
的发布都没有二进制资产）：
- build.sh：.syso 按目标平台 hide/restore（trap 兜底），恢复
  windows 目标的 CXX，arm64 刻意不带 CXX
- installer.nsi：5 处 ..\build → ..\..\build，PRODUCT_VERSION 可注入
  （原先硬编码 0.8.0）
- homeagent.spec：server 变体补装 waiter（control-server 声明了 CLI 却没装）

deploy/scripts/upload_assets.py：release 资产上传（两步签名 URL → OBS
PUT）。放 deploy/scripts/ 而非 scripts/，因为后者在 .gitignore 里。
支持 GITCODE_REPO/ASSET_DIR 环境变量以复用于 SDK 仓。
v1.0.0 		2026-09-03 19:26:17 +08:00
JianFeeeee
f91b27aedb fix: WebUI 版本显示 + Windows 交叉编译 + 发布脚本三处回归 
## WebUI 版本链路修复

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

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

## Windows 交叉编译修复

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

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

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

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

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

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

知识库 3 条重写 + 1 条新增：
- homeagent_identity：v0.9.0 C ABI → v1.0.0 子进程
- homeagent_architecture：全篇重写为子进程架构（三面通信、Supervisor 台账、
  崩溃自愈、权限三道闸）
- homeagent_recent_updates：在 v0.9.0 前插入 v1.0.0 主线摘要
- changelog_v1.0.0（新建）：6 类缺陷消除、架构、实测、已知限制、迁移指引
 2026-09-03 15:38:31 +08:00
JianFeeeee
525aa1f943 Merge branch 'feature/plugin-proc-migration' into main 
插件架构子进程化迁移（8-9 周）+ 崩溃自愈收尾。

## 消除的 6 类 C ABI 前提缺陷（对照 plan.md §11.0）

| 缺陷 | 原状 | 现状 |
|---|---|---|
| 热重载失效 | DF_1_NODELETE 让 dlclose 成 no-op | 换 plugin.bin 即生效 |
| 崩溃隔离缺失 | 插件 panic 带崩 homed | 子进程独立崩溃 + 自动重启 |
| stage lost update | 副本模型互相覆盖 35.8~36.8% | 共享内存段，0% |
| cgo 超时泄漏 | 现网泄漏 26 次线程 | 整套架构零 cgo，Kill 真取消 |
| output_send 假成功 | 永远返回 queued+nil | RPC 同步等真实结果 |
| 能力断层 | Windows 只见 3 字段无写回 | 18 字段全可见可写回 |

## 架构

- 控制面：stdio JSON-RPC（51 个 core.* method）
- 数据面：共享内存段（全部子进程共用一块，避免退化成副本模型）
- 通知面：事件环 + 三平台通知（Linux eventfd / macOS pipe / Windows Event）
- 权限梯度显式化为三道闸：procCore 命名字段 + manifest 能力声明 + RPC 边界拒绝
- C ABI 通道整体删除（-3198 行）

## 子进程生命周期管理

- 每子进程专职 waitLoop（cmd.Wait 唯一调用点），不依赖 stdout EOF
- proc.Supervisor 集中台账，Host.Close 先 StopAll 再拆段
- 崩溃自愈：摘注册面（工具+stage+IO通道）→ 移除注册表 → 退避重启
- Linux Pdeathsig 兜底 homed 被强杀场景

## 门禁

make test 零失败 / go vet 无告警 / SDK 公开接口 diff 为空（接口冻结不变量）
 2026-09-03 13:46:51 +08:00
JianFeeeee
02cc74ce11 fix(proc): 子进程崩溃自愈 + 集中台账 + 注册面摘除 
根因：子进程插件被 kill 后，内核只发了一个无人订阅的事件，
工具/stage handler/IO 通道全留在注册表里指向死进程，
模型继续调用只吃 ErrProcessExited，没有任何路径把插件拉回来。

## 四层修复

### 1. 专职 waitLoop（进程收割）
- 每个子进程配一根 waitLoop goroutine，是 cmd.Wait() 的唯一调用点
- 不再依赖 stdout EOF 判定死亡（孙子进程继承 stdout 时 EOF 永不到来）
- 手工 os.Pipe 替代 cmd.StdinPipe/StdoutPipe，避免 waitLoop 与
  os/exec 的内部关闭竞争
- host.go: Host.Supervisor()，Host.Close() 先 StopAll 再拆段

### 2. 集中台账 Supervisor
- proc/supervisor.go: 插件 Spawn 握手成功即 track，进程退出即 untrack
- StopAll: 并发发 plugin.stop 走优雅路径，到期仍在的一律 Kill
- 关停后才完成握手的进程被立即结束，不会活过内核
- 消除「孤儿进程持共享段映射 → SIGBUS」的隐患

### 3. 注册面摘除（detachPlugin）
- 新增 StageHost.UnregisterPluginStages：摘除指定插件的全部 stage handler
- 新增 Registry.pluginChannels 台账：记录每个插件注册的 IO 通道
- 三条路径统一走 detachPlugin：Disable / ReloadOne / RemovePlugin
- StopAndUnload 漏了 IO 通道也一并补上

### 4. 自动重启
- onProcCrash 从「只发事件」改为「摘注册面 → 从注册表移除 → 异步排重启」
- scheduleProcRestart: 窗口 5 分钟内最多 3 次，线性退避 1s/2s/3s
- 超限停手留日志；重启前复核是否已被 Disable 或被其他路径加载
- 崩溃计数窗口过期自动归零

### 5. 主动停止 vs 崩溃的区分
- proc.Plugin 新增 stopping 标志：Stop()/Close() 里 Set(true)
- handleExit 读 stopping 标志，主动停止不上报 onCrash
- 防止重载/禁用/卸载被误判为崩溃触发多余重启

### 6. Linux Pdeathsig 兜底
- procattr_linux.go: SysProcAttr.Pdeathsig = SIGKILL
- 兜 homed 自身被 SIGKILL/OOM 时子进程变孤儿的场景
- macOS/Windows 无等价物，空实现

### 7. pluginmgr 升级
- PluginManager 接口新增 PluginRuntime / ListPluginRuntimes
- plugin_list 输出运行态：loaded / alive / pid / crash_count / channel
- 新增 plugin_status: 全量运行期快照 + dead/unhealthy 汇总
- 新增 plugin_restart: 无条件重启单个插件（plgreload 不动未改二进制的插件）

### 测试
- process_test.go: 3 例（grandchild stdout 感知 / Supervisor track-untrack /
  StopAll 无孤儿）
- crash_recovery_test.go: 8 例（detach 三项齐全 / 通道重注册 / 崩溃不阻塞 /
  退避阈值 / 窗口过期 / 关停中跳过 / PluginRuntime 通道识别）
- stages_plugin_test.go: 4 例（stage 按插件摘除 / 空 stage 清理 / 空名 no-op /
  工具+stage 双摘后可重新注册同名）
 2026-09-03 12:37:58 +08:00
JianFeeeee
351e99dd70 docs(plan): 第 12 节 —— 子进程化迁移剩余工作与目标效果 
迁移主体已完成上生产（内核 v1.0.0，17 插件全部子进程化），
但有若干项未做完或未达成。写进 plan.md 而非只留在对话里，
避免下次接手时靠猜。

八个小节按「阻塞程度」排：

**12.1 合并到 main + 发布分支** —— 卡在四个决策点，非技术阻塞：
merge 方式（--no-ff vs squash）、是否删 feature 分支、release 构建是否
再替换生产二进制、SDK 仓是否同步。附完整执行序列。

记了一个易错点：v1.0.0 tag 当前打在 feature 分支中间点 670efcd，
按规范应在 release 分支上，需删除重打。

**12.2 验收清单两项未达成** —— 这两项在迁移计划里已如实标 ⚠️：
- SetToolBlocks 仍未实现。C ABI 时代也是空实现故不算回归，
  但 §3.8 明确承诺过「二进制写入 arena + Slice 描述符回传」，没兑现。
- 内存 88MB 远超「基线 +29MB」。根因是每插件静态链接整个 Go runtime，
  15 个不同二进制无共同物理页（PSS/RSS 99.9% vs 基线 44%）。
  基线用 2.68MB 最小插件复制 17 份，绝对数字本就不可比。

**12.3 事件环零真实负载检验** —— 机制完成、压测通过（2.29ms 与实验 4
一致），但 grep 确认无任何插件使用 Events().Subscribe。压测是我构造的
负载，生产上这条路径从未被真实插件走过。只写 ✅ 会掩盖这一点。

**12.4 三套 ABI 只收敛两套** —— C ABI 删了、Windows DLL 收敛了，
Lua 仍走独立解释器路径。§9.2 那句「三套收敛为单一 RPC」本轮兑现 2/3。
不阻塞是因为 Lua 不经 C ABI，不属于要消除的 6 类缺陷。

**12.5 Windows 无真机验证** —— 只做了交叉编译 + 单元测试。
已知语义差异（Event 是二元信号非计数器）推理上不影响正确性，
但没在真机确认过。§9.2 声称 Windows「从受害者变受益方」缺实证。

**12.6 stage 往返省两次 IPC** —— 132µs 里编解码只占 3.7µs，
其余是 3 次进程往返（invoke + 插件侧反向 lock/unlock）。合并后预期
降到 ~30µs。风险是锁持有时机改变，插件若在 handler 里再请求锁会死锁。

**12.7 遗留项** —— homed 主 heap 2.36GB（与插件无关）、鸿蒙端未提交改动。

**12.8 已达成目标留档** —— 6 类缺陷逐条对账，每条附证据
（测试名或生产日志），便于日后确认哪些是真解决了。
 2026-09-03 08:50:48 +08:00
JianFeeeee
12259ed4ec chore: 修 .gitignore 误伤源码目录（4 类，28 个已跟踪文件） 
`git ls-files | xargs -n1 git check-ignore --no-index` 查出 49 个已跟踪
源码文件落在 ignore 规则下。它们现在能提交只是因为「已跟踪文件不受
.gitignore 影响」这条 git 规则在兜着——**新增文件会默默不入库**。

## 根因一：缺前导斜杠（28 个文件）

`knowledge/` / `memory/` / `scripts/` 不带前导斜杠，git 把它们当作
「任意层级的同名目录」：

    memory/     → 吞掉 internal/memory/         24 个文件
    knowledge/  → 吞掉 internal/knowledge/       3 个文件
                          assets/knowledge/
    scripts/    → 吞掉 deploy/scripts/           1 个文件

本意只是忽略根级运行时数据目录。旁边的 `/adapters/` 就写对了，
这三条是漏了斜杠。

修法：补 `/` 前缀。验证两侧行为：
  根级 knowledge/y.md memory/z.db scripts/tmp.sh   仍被忽略 ✓
  深层 internal/memory/new.go internal/knowledge/new.go
       deploy/scripts/new.sh                        可入库 ✓

## 根因二：internal/meta/ 整目录被忽略（1 个文件）

引入于 1f1233b（2026-07-12），同批还有 `.go/`、`.local/`、
`internal/plugins/openclaw/{manager,pysimulator}/`（后两个目录现已不存在）。
`internal/meta/meta.go` 是内核版本号与元数据的唯一数据源，本轮升 1.0.0 时
`git add` 报「paths are ignored」，就是这条。已跟踪所以改动能提交，
但新增 meta 文件会丢。直接删掉这条规则。

## 保留的 20 项不是缺陷

`third_party/homeagent-sdk/example/` 下 20 个已跟踪文件（plg.json +
plugin.go）仍在规则覆盖下，这是**有意的**：外部插件维护在独立 SDK 仓
（决策 sdk_repo_only），主仓只需要这 20 个源码文件参与构建，不要 SDK 仓的
main.go/go.mod/go.sum。删掉该规则会让 60+ 个文件涌进主仓——实测确认过。

已在两处 ignore 段落写明理由，避免后来人「修」错方向。

验证：修复后 check-ignore 扫描从 49 降到 20（全部是有意保留的 example/）；
go build ./... 通过。
 2026-09-03 08:39:23 +08:00