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

14 Commits

Author SHA1 Message Date
JianFeeeee
f5a1366770 fix(proc): arena 扩容块泄漏 + 取消成为一等状态 
## 1. arena 泄漏（线上 arena 被打满的根因）

插件经 arena.alloc 申请的扩容块，块头 owner 记的是**插件的** ownerID，
而内核三处归还全写着 Free(OwnerHost, ref)。归属校验必然失败，错误又被
`_ =` 吞掉 ⇒ 每返回一次大结果就永久泄漏一块。

线上表现（2026-10-25）：重任务跑几轮后 4MB arena 满，之后连 64KB 调用帧
都分不出来，所有插件工具一起报「arena: 空间不足（请求 65779 字节）」。

修法：三处改用插件自己的 ownerID，且失败必须留日志（吞掉错误等于把
下一次「空间不足」的原因提前销毁）。

## 2. 取消成为一等状态

旧实现里「调用在进行中」只表达为 pending 表里有这个键：取消时直接
delete，状态的痕迹全部消失，插件随后回的应答只能走「未知 id，丢弃」。
那是副作用的正确，不是规则的正确。

改成每次调用带显式状态机（callstate.go）：

    pending ──应答──→ done
       ├──取消/超时──→ canceled ──迟到应答──→ done
       └──进程退出──→ failed

迁移表集中在 legalTransition，非法组合一律拒绝（CAS 只校验 from，
不校验 to——实测曾把 done 改回 failed）。

## 3. 取消跨进程送达

内核超时到点后只停止「等」，插件侧的 handler 还在跑，占着连接/子进程/
文件句柄，结果却已被丢弃。现在 CallContext 取消时向插件发 call.cancel
通知（fire-and-forget），插件运行时按 **RPC id** 定位并 cancel 对应调用的 ctx。

不按工具名定位：同一工具可并发多次，按名字会误伤其它实例。

插件作者零改动：handler 签名不变，取消由模板运行时接住。

## 4. 取消超时判定插件不稳定

严格区分两类超时（用户裁定）：

    业务超时 = 任务跑太久     → 正常，不作为不稳定依据
    取消超时 = 喊停之后还不停 → 异常，是插件失去响应的直接证据

取消宽限（cancelGrace=5s）到期仍无应答 ⇒ ① 强制回收该调用名下的扩容块
（插件已静默退出，永远不会归还）② 计数 ③ 连续两次触发既有崩溃重启链。
插件一旦响应取消即清零；重启后也清零（判据是"连续"不是"累计"）。

判据：8 条新增单测 + 全部变异验证（不回收/不上报/不清零/取消不跨进程
任一处改坏，对应用例立刻变红）。

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-10-25 10:10:21 +08:00
JianFeeeee
198811253a feat(webui+guard): 内核重启/关机按钮，指令走心跳复用既有协议 
## 需求

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

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

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

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

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

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

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

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

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

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

## 判据（7 条）

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

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

## UI

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

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

## 为什么

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

## 怎么改

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

## 判据

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

## 顺带修的缺陷

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

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

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

## 密钥防火墙

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

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

## 配置加密

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

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

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

## 判据

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

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

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

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

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

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

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

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

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

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

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

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

## deb 的 systemd unit 改为 guard 模式

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

## 其他

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## 修法

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

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

## 验证

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

## 顺带

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

---------

Co-authored-by: JianFeeeee <JianFeeeee@users.noreply.gitcode.com>
 2026-10-17 19:18:24 +08:00
JianFeeeee
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
2176917466 feat(knowledge): 分类过滤与多模态打通到工具/插件边界 
- internal/sdk：KnowledgeAPI 增加 SearchIn/AddWithMedia/AttachMedia/
  ReindexDense/DenseStats；新增 MediaAPI（Put/Stat/Get）与 PluginSDK.Media()，
  registry 装配。**公开 SDK 契约一字未动** —— third_party/homeagent-sdk/sdk/
  的 diff 恒为 0（发布纪律的硬约束），走 internal/sdk 这条明确不受冻结约束
  的内部扩展路径。
- proc：新增 knowledge.addWithMedia（正文与媒体清单都走共享内存，与
  doc.insertWithMedia 同形）；knowledge.search 支持 category。
- corehandler 用**局部接口 + 类型断言**取扩展能力，而非直接引 internal/sdk：
  后者已依赖 internal/plugin 的类型，直接引会成环（CoreSDK 注释已警示）。
  断言失败明确报"能力不可用"，不静默退化成"媒体已写入"。
- agent 工具面：knowledge_search 增加 category；knowledge_create 增加
  media_digests（复用 doc_commit 的 digest 前缀解析 + Stat 回读 MIME）。
  顺带修 knowledge_search 的分类前缀重复（Name 已含分类，旧代码又拼一次，
  实测输出 tech/go/tech/go/并发）。
- agent 启动接线多模态空间，顺序为先接线再 ReindexDense（否则首次启动
  算出的向量因 MediaStore 未就绪而不落盘）。
 2026-09-26 14:20:19 +08:00
JianFeeeee
fb53ea116b feat(shm): 文档/知识正文入共享内存 + 协议版本 bump 到 2(§13.13) 
## 数据面补齐

- doc.insert / doc.insertWithMedia：新增 doc_ref / attachments_ref，
  模板序列化后 putValueInArena
- knowledge.add：新增 content_ref（内容是 JSON 字符串，读出后再解一层）
- 抽出通用 resolveJSONRef（resolveBlocks 也改用它），三处共用一套
  “共享优先、内联回退”逻辑

## 协议版本 bump：让错配显式失败，而不是静默坏

这是本轮更重要的部分。§13.6/§13.13 改了内核→插件 payload 的承载方式，
两种错配都不会报错、只会静默失效：

- v1 插件只读内联 args（tool/cleaner/output）→ 遇到 v2 内核拿到空参数
- v2 插件发 blocks_ref → v1 内核反序列化时静默忽略（旧内核
  io.setToolBlocks 还是桩实现）

现场表现为“输出变空 / 图注入没反应”，极难定位。所以把 ProtocolVersion
与模板 procProtocolVersion 一起 bump 到 2：双方都是等值校验，v1 插件遇上
v2 内核会在建链时明确报“协议版本不匹配…请用配套 plugindev 重编”。

测试里把“错误必须带出重编指令”也断言上了——生产上碰到它的现场就是
“只更新了内核没重编插件”，光报“不匹配”定位不到行动。

testdata 8 个插件的 protocol 同步更新（badprotoplugin 仍用 999 验证拒绝）。
工具链已重建并安装（协议 2，内嵌 blocks_ref/doc_ref/content_ref），
回滚副本 plugindev.bak-20260910-232544。

验证：-race 全绿。新增 KnowledgeAddViaArena(12000B 正文)、
KnowledgeAddInline、DocInsertViaArena、SetToolBlocks 三例 +
真实模板 e2e + 协议不匹配断言强化。

§13.13 第 5 条（反向大结果）范围更大——需把内核→插件的应答路径整体改成
“大结果写段 + 返回 ref”，涉及 callCore 的返回处理与 doc.query/llm.chat 等
所有读大结果的 method。已在 plan.md 标注未做，不冒充完成。
 2026-09-10 23:26:16 +08:00
JianFeeeee
19c3f9aaa0 feat(shm): 输出通道 payload 走共享内存调用帧(§13.6) 
§13.3 给 ToolInvokeParams 加了调用帧，但 OutputInvokeParams 没跟上——
payload 仍内联在 RPC JSON 里。核实后确认这个 lane 只做了半边：注入侧
（injectParams.TextRef + resolveText）可用，输出侧从内核到插件仍是内联。

改法照搬工具调用的 funccall 帧模型：

- OutputInvokeParams 加 Frame/ArgsLen（Args 仅留给直连 RPC 的测试）
- invokeOutput 序列化参数 → Alloc 帧 → 写帧 → 只传偏移描述符 → defer Free
- 帧尾不预留结果区：output 应答很小（"ok"/status map），走 RPC 应答字段即可。
  但 OutputInvokeResult 支持插件把大结果写回帧（ResultRef），并识别
  sharedRefFlagExpand 单独归还扩容块——与 invokeTool 一致。
- 模板 output.invoke 用 frameInput 从帧读参数，无帧才回退内联 Args

为什么要做：output payload 在真机上可能含图片/文件描述等大字段，内联会
撑爆 stdin/stdout 管道。

验证：
- TestPlugin_OutputPayloadViaArena：9000 字节 payload 经帧完整送达（插件回报
  实收长度，不是只看返回值）+ 调用后 arena 归零
- TestE2E_RealTemplateOutputPayloadViaFrame：同上，但用真实 SDK 模板编译的
  插件——生产插件走的就是模板，模板不读帧则此改动等于没做
- TestPlugin_OutputChannelReportsRealFailure 仍绿：同步等真实结果、失败必须
  上报（§9.4）的语义未被破坏
- go test -race ./internal/plugin/... 全绿

plan.md §13.5 也如实标注：注入 side 内核→插件方向仍未接线（procCore.InjectText
直接传字符串，从不 Alloc/Put 构造 TextRef），不是仅打勾的项。
 2026-09-10 21:28:56 +08:00
JianFeeeee
4efc21c90b refactor(shm): 变长块分配器 + 工具调用 funccall 调用帧(§13.2/§13.3) 
按架构约束推进两步：

1) 分配器收回内核后，定长槽失去了唯一存在理由
   （定长槽只是为了绕开"跨进程无法安全变长分配"），
   于是 arena 换成**变长块分配器**：first-fit + 邻块合并，
   块头 16B（size/state/owner/prevSize）。内核可以按需标定每块大小，
   payload 不再受固定槽容量限制（旧上限 16KB）。

   - Alloc/Put/Read/Free/ReclaimOwner 全在内核进程内，一把 sync.Mutex
   - Free 走块链校验 offset 是已分配块的数据起点 + owner 匹配，
     伪造引用不能改动分配器状态
   - Read 允许块内偏移（调用帧的结果区就在帧块中间），但不许跨块边界
   - arena 4MB，底层 memfd 惰性分配：未触碰的页不占物理内存

2) 工具调用 payload **始终**走共享内存，取消按大小切内联的分支。
   按 funccall 模型，内核（caller）标定调用帧交给插件（callee）：

       [0, ArgsLen)              参数 JSON
       [ArgsLen, Frame.Length)   结果区（内核预留的预算）

   结果超出预算时插件才 `arena.alloc` 扩容块，引用上打
   sharedRefFlagExpand 让内核单独归还。Cleaner 复用同一帧模型。
   ToolInvokeParams.Args / ToolInvokeResult.Result 仅剩给直连 RPC 的
   测试（process/bench 不建 Host）；生产路径永远走帧。

测试：
- TestArena_*（分配/归属/回收/并发唯一/耗尽/超限/伪造 offset/
  相邻合并/对齐/布局校验）
- TestPlugin_ToolInvokeArgsResultViaArena：大**小** payload 都经帧往返，
  结果一致且 arena 归零（"小 payload 同样走调用帧"是本轮行为变更）
- TestPlugin_ArenaAllocFreeAcrossProcess、TestE2E_* 保持通过
- 顺手修 process_test.go 一处预存 doc-comment 分段
 2026-09-10 18:54:36 +08:00
JianFeeeee
326c31aea8 refactor(shm): 内核独占共享槽池，插件经 RPC 申请/归还(§13.2/§13.3) 
推翻前两版跨进程分配器设计，根因是"共享内存里放了只被单一进程
更新的可变游标"：

- v1 在 SuperBlock 放 arenaUsed 游标，内核 CAS bump。但插件模板里
  arenaUsed 是**进程本地变量**，两进程各自 bump 必写同一段内存；
  arenaReset 还会重置共享游标覆盖对方数据。
- v2 把位图 CAS 下沉到插件模板，正确但把分配器实现泄漏进插件运行时，
  且插件必须与内核保持位图布局同步。

新设计（用户明确的架构约束）：内核全权管理共享内存，插件通过
syscall 风格 RPC 申请/归还，内核返回偏移与大小。分配器只存在于内核
进程内，一把 sync.Mutex 即可。共享内存是内部实现，不对插件开发者
暴露——SDK 公开 API 仍是普通字符串/Map。

主要改动：
- arena.go: 定长槽 + 位图，Alloc/Put/Read/Free/ReclaimOwner，内核独占；
  槽头记录 owner，Free 校验归属；payload 超槽容量退回内联 RPC
- protocol.go: 新增 arena.alloc / arena.free（CapCore）
- capability.go: 登记两个新 method（checkAllMethodsClassified 要求）
- corehandler.go: 实现 arena.alloc/free；Cleaner 改为内核预分配
  请求槽 + 响应槽（插件完全不分配）
- plugin.go: Start 领 ownerID；handleExit 调 ReclaimOwner 回收残留槽
- unified.go: 移除坏的 bump 分配器；arena 基址 8 字节对齐
- 删除 toollane.go: ring 状态机是死代码（从未接线），且把 RPC 已有的
  请求 ID 关联/错误传递/ctx 取消重新实现了一遍。控制面保留 RPC，
  只把 payload 搬进共享槽。
- 测试: TestArena_*（归属/回收/并发唯一/耗尽/超限/非法引用/布局）+
  TestPlugin_ArenaAllocFreeAcrossProcess（真进程申请→写入→随业务
  RPC 回传→归还→内核读回一致且池归零）
 2026-09-10 17:56:50 +08:00
JianFeeeee
1339fb6f8e 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
a49ac72968 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
3bfaa82a70 feat(sdk): 多模态贯通插件边界——公开接口、内核桥接与统一输入主干 
记忆系统在 1.1.0 支持了二进制多媒体节点，但那条链路只对**内核自己**开放：
用户在 qq 发图能落进 CAS、能被记忆引用，而插件调 Commit / DocMemory().Insert
交进来的媒体一律无处安放。原因是三层都断着，且**每一层都不报错**。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## 测试

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

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

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

存量插件不需要改一行也不需要重编：新增方法由插件调用、内核实现，不调就不受影响。
17 个 example 插件源码零改动通过类型检查。
 2026-09-06 09:51:31 +08:00
JianFeeeee
b729ebe4c8 proc: Windows 共享内存 + 事件通知适配（Part 6.2 内核侧） 
补齐内核侧的 Windows 创建端，与 6.1 的插件侧打开端配对。三平台
（linux/darwin/windows）现在都能构建 internal/plugin/proc。

## Windows 走命名内核对象（无 fd 继承语义）

os/exec 的 ExtraFiles 在 Windows 实现里不被支持，故：
- shmalloc_windows.go：CreateFileMappingW（INVALID_HANDLE_VALUE + 命名 →
  系统页文件支撑的匿名段，不落盘）+ MapViewOfFile
- evtfd_windows.go：CreateEventW 命名 Event 对象 + SetEvent 通知
- shmpass_windows.go：把段名/对象名经环境变量注入子进程
  （HOMEAGENT_SHM_STAGE / HOMEAGENT_SHM_EVTRING / HOMEAGENT_EVT_EVENT）

名字带 PID + 递增序号：多个 homed 实例并存时不能撞名。

Event 与 eventfd 的语义差异：Event 是二元信号，多次 SetEvent 只对应一次
唤醒，不累积。不影响正确性——消费者被唤醒后按 readSeq 追 writeSeq 批量
drain，丢的是"唤醒次数"不是"事件"；事件环本身就允许溢出丢弃并让消费者
知道丢了（dropped 计数），通知面从来不是可靠投递语义。

## 传递机制抽象为 shmpass_*.go

Plugin.Start 不再直接构造 ExtraFiles 列表，改为问 Host 要：
  Env:        p.host.procEnvForShm()        // Windows 返回段名，Unix 返回 nil
  ExtraFiles: p.host.procExtraFilesForShm() // Unix 返回 fd 列表，Windows 返回 nil

平台差异被收敛到这一对函数，Plugin/coreHandler/stage 全部平台无关。

## macOS pipe 生命周期修正

原实现只返回读端 fd，写端 *os.File 无人持有 → 可能被 GC 回收 →
读端收到 EOF 而非阻塞 → 消费循环变忙转。改为 pipePair 表同时持有两端，
evtfdClose 一并关闭。

## E2E 测试跟进模板拆分

模板从单文件拆成三个（主体 + unix/windows 挂载），测试需要一并落盘，
否则编译报 attachStageShm undefined。procRuntimeTemplates 表必须与
SDK 仓 proc_runtime.go 的 procRuntimeFiles 一致。

验证：三平台 go build ./internal/plugin/... 通过（gojieba 的 cgo 依赖
导致 internal/memory 在非 linux 失败，与本次无关）；
go test -race ./internal/plugin/... 全绿，含 2 项真实模板 E2E。

Ref: docs/zh/架构迁移评估.md §9.2、docs/zh/plugin-migration-plan.md Part 6
 2026-09-02 19:07:14 +08:00
JianFeeeee
f3915d38a6 feat(proc): 子进程通道 —— RPC 协议 + 进程管理（Part 2 核心） 
协议面（protocol.go，§3.2 method id 平移为 method 名）:
- NDJSON 帧，双向复用同一对 stdio；ID>0 需应答，ID==0 为通知(post-and-forget)
- 51 个 C ABI method id 全部平移为可读 method 名并标注原编号对照
  编号本身扔掉——加能力不用改两边常量表，不再有 47 夹在 7 和 8 之间的痕迹
- case 25(CORE_FREE_STRING) 无对应 method：进程模型下各自 GC，概念消失
- case 23/24(事件订阅) 与 io.setToolBlocks 今日均为空实现「给不了」，
  子进程下首次真正可给（§3.8 能力对齐）
- 新增 stage.lock/stage.unlock（C ABI 下不存在跨进程锁概念）
- StageInvokeParams 不含 StageContext 数据本身——数据在共享段，只带 stage 名 + seq

进程面（process.go，§2.3 保留现有生命周期机制）:
- Spawn: 启动 + 握手（协议版本不匹配显式拒绝，不半兼容运行）
- readLoop: NDJSON 分派应答/插件反向请求，1MB 单帧上限（大 payload 走 arena）
- CallContext: ctx 取消时立即返回**且清理 pending 条目**
  对比 cgo：超时只让调用方返回，goroutine 永久卡在 C 调用里（现网泄漏 26 次）
- Notify: ID=0 不占 pending 表，满足约束 B（流式逐 token 发布不得等待消费者）
- markExited: EOF/退出 → 唤醒全部在途调用 → onExit 回调
  这是「把 panic 捕获换成进程退出检测」的落点，plugin_health 逻辑完全复用
- Stop: plugin.stop → 宽限期 → 超时 Kill；Kill 后 OS 回收全部资源，零泄漏
- serveRequest 带 panic 隔离：内核 handler panic 不带崩 readLoop

验证（10 项，真实子进程而非 mock，含 -race）:
- 握手/工具调用/错误上报（插件失败调用方收到 error，非假成功）
- 插件反向调用内核（tool.register + settings.get 双向往返）
- **崩溃隔离**：插件 panic → 子进程 exit 2，内核存活、收到 onExit、在途调用不挂死
- 优雅停止 / **Kill 卡死插件**（ctx 超时返回 + pending 清零 + 资源回收）
- 通知不等应答（100 条 < 1s）/ 50 并发调用应答不串 / 协议版本不匹配拒绝

接口冻结: git diff third_party/homeagent-sdk/sdk/ 为空
 2026-09-02 10:59:59 +08:00