13 Commits

Author	SHA1	Message	Date
JianFeeeee	a68d6a428c	feat: 模块化内核（编译期依赖图定序）+ 密钥防火墙 + 插件三态生命周期 (#10) ... * feat(kernel): 模块化内核 + 编译期依赖图定序 把单体 init 序列拆成「模块自声明依赖 + 编译期生成依赖图 + 运行期只读图」。 ## 为什么 原 cmd/homed/main.go 里 17 步 init 是**手写顺序**，依赖关系只存在于 注释和人脑里。实测踩到的坑（见 docs/zh/kernel-modularization-design.md）： · nlp.defaultParser 被 initONNXParser 写、被 distiller 读，两者相距 60 行， 只靠 ticker 10min 才没炸（隐式依赖，无声明） · 加一个模块要人肉找"该插在哪"，插错的表现是运行期 nil 解引用 · 关停是 defer ks.CloseAll()，而热更新路径 os.Exit(42) **跳过 defer** ⇒ docStore/distiller/textMem 的 flush 全部丢失（每次热更新都发生） ## 怎么改 - internal/kernelboot/：KernelState（一个结构体收全部包级共享变量，字段 nil 安全）、Module 接口、graphfile（依赖图编解码 + 与二进制 hash 对账）、 scheduler（按 BFS 层并行 Init）、syncbus（层边界写通知）、 lifecycle（Quiesce/Resume 可逆伪关机，区别于一次性 CloseAll） - internal/kernelmod/<name>/：每个模块一个文件夹，Requires/Provides 自声明； all/all.go 是唯一的 import 清单（Go 循环导入约束） - cmd/homed-depgraph：编译期生成依赖图，Makefile 注入 digest - 运行期只**读**图，不计算顺序（顺序是编译期决定的，源码里没有中央清单） ## 判据 kernelboot 8 条 + 图失败模式 7 条（全部拒绝并给准确错误）+ 模块目录数 与注册表一致性。变异测试 15/15 咬住，含： · 删掉 AddCloser 的锁 → -race 报数据竞争 · Scheduler 同批跑去重 → 203 vs 200 · 图 hash 不匹配 → 拒绝启动 ## 顺带修的缺陷 热更新路径漏调模块关闭 ⇒ 显式 stopKernelModules()，并用 AST 判据钉住 "必须在 os.Exit 之前"（字符串检查在本仓已骗过我三次）。 实测：冷启动 1630ms（5 层/17 模块，原 17 步串行）；生产 22 插件全部建链。 * feat(security): 密钥防火墙 + 配置加密 + close 纪律 ## 密钥防火墙 模型只见别名、不见明文；插件工具调用入口（StageHost.ExecuteTool）做入向 回填。三维能力： · 出向：工具输出里的密钥被替换成 [[secret:name]] 别名后才进上下文 · 入向：模型传别名，入口处填回真值（插件完全无感知） · 存储：config.db 里不存明文（0644 的库可读），敏感值独立 0600 文件 模式库「宁漏勿误伤」：宁可漏掉一次替换，也不把正常文本误当密钥。 ## 配置加密 - internal/security/{codec,key,keyring,store,global}.go：AES-256-GCM， enc:v1: 前缀，密钥轮换（OldKeys 解码 + 新钥加密） - harden.go：数据目录权限收紧 - embedded.go：支持内嵌主密钥（可选，仍保留外部 key 文件路径） - EncryptExistingSecrets / AuditSecrets：启动时幂等迁移 + 审计 ## close 纪律（用户明确要求：只要调 close 就要有前置检查） internal/safeclose：Safe / SafeFunc。全仓 37 处裸 close(chan) → 0。 关键教训（都写进注释和判据）： · `select { case <-ch: default: close(ch) }` **不是**并发安全的 （两个 goroutine 可同时命中 default）—— healthcheck 原先是这种写法 · `sync.Once` **不可重入**：X.Do(func(){ Safe(&X, ...) }) 会自锁， 症状是 go test 直接挂住（3 个包 600s 超时），栈里只有嵌套的 Once.Do · map 里按请求持有的 channel（mcp/stdio.go、clawhubadapter/sidecar.go） 改成 *pendingRPC 包装，每通道一个 once ## 判据 security 全量 + TestNoBareCloseOutsideSafeclose（AST 级扫描，含注释剥离） + TestNoNestedSelfOnceDeadlock（正则修正：\w+ 不匹配点号，捕获组要含 '.'）。 变异 2/2 咬住。全量 52 包 ok。 * feat(plugin+deploy): 插件三态生命周期、数据目录迁移、发行包修复 ## 插件三态生命周期（用户要求：自动启动 / 启用但不自动启动 / 禁用） - Manifest 新增 requires_facilities / auto_start（*bool，用于区分 "未声明"与"显式 false"） - plugin-host 模块（internal/kernelmod/pluginhost）：用 kernelboot.Scheduler 按依赖时机拉起，**不再手写两阶段** - 运行态停启 StopPlugin/StartPlugin **可逆**：不写 disabled_plugins （不改用户决定）、不置 shuttingDown（之后还能加载）、会摘掉注册面 - 与 StopAll 的区别写进注释 —— StopAll 置 shuttingDown 后**永久无法加载**， 那是进程退出用的，误用于"暂停"就是关了就死 ## 数据目录迁移（伪关机 → 迁移 → 唤醒） - kernelboot/lifecycle.go：Quiesce/Resume（可逆，区别于一次性 CloseAll）， 逆序暂停、逆序恢复、Pause 失败回滚 - kernelboot/migrate.go：BeginMigration/End 编排（先停插件 → 再停内核写者 → 等在途归零） - distiller/textmem 增 Pause/Resume 门（不是 cancel —— cancel 不可逆， 恢复要重建整个对象） - 模块 migration：体检 + 生成可执行迁移脚本 ★ 迁移脚本的三个实测教训（都写成了判据）： 1. 无条件改 /etc/systemd/system ⇒ 演练把**生产** -data 改成了演练目录。 加 --dry-run（零改动）+ 强制校验 systemd 当前 -data == OLD 2. 本机没装 rsync，脚本在"服务已停、数据未搬"处硬失败 ⇒ cp -a 回退， 并明确警告不保硬链接/ACL（生产 plugindev 有大量 git 硬链接） ## 发行包修复（全部经实测确认） 1. package-linux.sh **完全漏打 depgraph.bin** ⇒ 内核 exit 1 （"生产构建（内嵌 hash 非空）但读不到依赖图"） 2. build_homed 不走 Makefile ⇒ 单独修 Makefile 无效，必须同时生成图+注入 3. build.sh 的 LDFLAGS 用**历史模块路径 gitcode.com** ⇒ -X 静默 no-op ⇒ --version 显示 unknown 4. Makefile -ldflags 用**单引号** ⇒ 注入了字面 $GRAPH_HASH ## ★ build.sh 的版本号必须校验（真实事故） 原 `VERSION="$(git describe --tags --dirty)"`。无 tag 分支上它返回**分支名** `backup/pre-identity-rewrite-20261005-51-g03d87a4e-dirty`，被注入 meta.Version ⇒ 插件握手判据 MajorVersion() 把整串当主版本 ⇒ **22 个子进程插件全部 握手失败**（"主版本不匹配"）。内核活着、systemd active、日志每条都像 插件的问题 —— 实际是发行包带着非法版本号。 修法：git describe 只在形如 vX.Y.Z 时采用，否则回退 meta.Version（权威源）， 并对最终值做形态守卫。deploy/packaging/version_guard_test.go 3 条判据， 变异 2/2 咬住。 ## deb 的 systemd unit 改为 guard 模式 ExecStart=/usr/bin/homed --role=guard --data /var/lib/homeagent （worker exit 42 → guard 重拉，不经过 systemd、不计失败） 含 RestartSteps/RestartMaxDelaySec/TimeoutStopSec + 硬化 （NoNewPrivileges/ProtectSystem/ProtectHome/DevicePolicy/ReadWritePaths）。 ## 其他 - internal/plugin/proc：非法 JSON 帧的报错**可定位**（内容摘要 + 可能原因 + 修法）。生产实测 1038 条非法帧（插件往 stdout 打日志 = 污染协议通道） - 示例插件 4 个 14 处 fmt.Printf → log.Printf - hmapdev 模板同步修复；scaffold 判据剥离注释（模板注释里就含 fmt.Printf） * chore: 收尾（主密钥轮换命令、IPC/知识库加固、SDK 对齐） - cmd/homed-key-rotate：把 security 里的 RotateKey/RotateKeyFile/RekeySecrets 串成一条**可执行**的运维路径。没有它，E-1 就只是库里的能力而不是 "出事时能做的事"，而轮换的价值恰恰在于能执行。 - cmd/homed：kmod_runtime（模块装配入口）、plugins_scheduled（failback 白名单）、memcandidate、bootstrap_order_test / shutdown_flush_test - internal/ipc、internal/devicebridge、internal/knowledge：配套加固 - third_party/homeagent-sdk/sdk：PluginMgrAPI 增三态能力（mgrStop/mgrStart/ mgrIsRuntimeStopped）+ settings 对齐 判据：bootstrap_order_test（启动顺序不依赖手写序列）、 shutdown_flush_test（停机的两条路径必须对称 —— exit 42 会跳过 defer， 热更新路径下模块关闭/flush 曾全部丢失）。 * test(security): 测试夹具改用不可误认的占位值（修 push protection 拦截） GitHub secret scanning 拦住了推送：三处测试夹具用了"看起来像真密钥"的 字面量： internal/security/prefilter_test.go:39 internal/security/store_test.go:177 internal/security/survey_test.go:20 它们全是**假密钥**（`AKIAIOSFODNN7EXAMPLE` 是 AWS 官方文档的标准示例， 其余是 `abcdefghij...` 这类可读占位符），但扫描器无法区分 —— 它只看形态。 ★ 不绕过（不用 unblock URL、不加 allowlist）：直接改夹具。 原因：一旦允许"假密钥可以通过"，真密钥混进来时就没有最后一道门了。 改法：保留**模式库匹配所需的结构**，把可识别内容换成 FAKE： glpat-abcdefghijklmnopqrst → glpat-FAKE-TEST-TOKEN-NOT-REAL sk-abcdefghij...012345 → sk-FAKE-TEST-KEY-NOT-REAL-0000000 AKIAIOSFODNN7EXAMPLE → AKIA0000FAKE0000TEST (保持 20 字符) ASIAIOSFODNN7EXAMPLE → ASIA0000FAKE0000TEST xoxb-123456789012-abcdefghijklmnop → xoxb-FAKE-TEST-TOKEN-NOT-REAL ★ 中途踩到一次：AWS 键的模式是 `\b(AKIA|ASIA)[0-9A-Z]{16}\b`（共 20 字符）， 我第一次替换成 19 字符的 `AKIAFAKETESTKEY0000` ⇒ 模式匹配不上 ⇒ TestSurvey_WhatIsCaught / TestRecognizesCommonShapes / TestPrefilterNeverBlocksRealMatches 三条当场变红。 判据正确地拒绝了"为了过扫描器而削弱覆盖"。 顺带核实：全仓 grep 无任何真实密钥泄漏。 * fix(packaging): package-linux.sh 的版本解析与 build.sh 统一 上一版只修了 build.sh，漏了 package-linux.sh —— 它仍只看 git describe： VERSION="${VERSION:-$(git describe --tags --dirty)}" 无 tag 分支上 git describe 返回**分支名** （backup/pre-identity-rewrite-20261005-56-g98850e1），守卫会正确拒绝， 但要求人**手动传 VERSION** 才能打包。而 build.sh 早已能自动回退 meta.Version ⇒ 同一个版本，走 build.sh 打得出来、走 package-linux.sh 打不出来。 危害不只是"要手动传参"：运维为了跑通会去掉守卫，而分支名一旦进 meta.Version 就是**插件协议主版本**的来源 ⇒ 22 个子进程插件全部握手失败 （这是真实发生过的事故，见 3efa4e5）。 修法：两个脚本用同一套规则（git describe 仅在 vX.Y.Z 形态时采用， 否则回退 meta.Version），并对最终值做形态守卫。 判据：TestBothPackagingScriptsShareVersionRules —— 逐个读两个脚本， 要求都能从 meta/meta.go 取权威版本、都校验 git describe 形态。 变异（把 package-linux.sh 改回旧规则）咬住并准确指出是哪个脚本。 实测：不传 VERSION 跑 package-linux.sh，输出 [PKG] warn: git describe 给出非版本串（...），改用 meta.Version=1.4.0 Version: 1.4.0 * fix(test): 跨仓判据在 CI 上应 skip 而非 fail（修 PR 双红） CI 上 "Go build / vet / test" 与 "Build linux/amd64" 双红： --- FAIL: TestHmapdevTemplateImplementsAllPluginMgrMethods bridge_sync_test.go:170: 读模板: open ../../../third_party/homeagent-sdk/tools/hmapdev/templates/proc_main.go.tmpl: no such file or directory ## 根因：判据依赖了一个**被 gitignore 的路径** `.gitignore:33` 有 `third_party/homeagent-sdk/tools/`（SDK 仓自治，本仓不跟踪）。 于是： · 本机（完整 SDK 检出）有该文件 ⇒ 判据通过 · CI（只 checkout 本仓）没有该文件 ⇒ Fatalf ⇒ **必红** 我提交时只在本机跑测试、没看 CI，所以这个问题拖到 PR 才暴露。 ## 修法 文件缺失时 `t.Skipf` 而不是 `t.Fatalf`。 ★ 这不是"放弃检查"： · 跨仓一致性由 **SDK 仓自己的判据**守着 （tools/hmapdev/scaffold_stdout_test.go 等），那里才是模板的真实归属地 · 本判据在本机开发时**仍然生效**（已验证：有文件时 PASS，缺文件时 SKIP） ## 验证 · 本机（有文件） → PASS（判据真跑） · 模拟 CI（移走 tools/）→ SKIP（不再 fail） · 全量 53 包 ok / 0 fail ## 顺带 同目录还有 e2e_template_test.go 也读 tools/，但它是 `//go:build` 门控的 e2e 判据，CI 默认不跑，无需处理。 --------- Co-authored-by: JianFeeeee <JianFeeeee@users.noreply.gitcode.com>	2026-10-17 19:18:24 +08:00
JianFeeeee	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	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	c04e80f1fe	feat(core): 注入行为的记忆/裁剪标志位落地 + jieba 词库内嵌 + Windows 改走 WSL ... 配套 SDK 提交：homeagent-sdk ba49dfd（公开 API 纯追加，无签名变更）。 本仓第三方的库镜像同步至该版本，以保证全新 clone 能编译。 ## 1. 注入标志位（内核侧） - 7 条注入路径（排队/中断/同步 × 纯文本/带媒体 + 旧 NoMem 变体）解析并转发 no_memory / context_policy / cleaner_name；策略在入口**校验**， 非法值报错而不是静默降级成 none（降级会让调用方以为自己声明的裁剪在生效）。 - 新增 validateContextPolicy（与 tool.register 同一套规则）与 pubSdkInjectOpts。 - input.register 不再手写字段白名单重建 ChannelDef，改为整体传递 + 补 ContextPolicy。 - io 层：applyInjectOpts 把标志位写进事件 payload，仅非零时写 （零值与旧 payload 逐字节一致，事件订阅方与旧内核都不受影响）。 - ioAdapter / procCore / internal-sdk 别名补齐六个 *Opts 实现。 ## 2. 修掉「输入无条件裁剪」这个真缺陷 eventloop 此前对**每条非中断输入**都调 `context.Prune(...)`：破坏性（低相关事件被 归档移出上下文）且无法从调用点看出是谁触发的。改为 pruneOnInput/pruneDeclared： 优先级：注入点声明（payload.context_policy）> 通道声明（ChannelDef.ContextPolicy） > 默认**不裁剪** 查询向量仍取清洗后的内容；新增 cleanInputFor 解析清洗文本，优先级为 注入点声明的 cleaner（cleaner_name）> 按 source 查到的通道 cleaner > 原文， 名字查不到时**记日志再回退**（注入是 fire-and-forget，插件看不到错误， 至少要在内核日志留下「你声明的清洗没生效」的痕迹）。 ## 3. jieba 词库内嵌（修「猜 GOMODCACHE → 静默失效」） 原 jiebaDictDir() 去猜 GOMODCACHE/GOPATH/~/go/pkg/mod，部署机上通常没有 Go 模块 缓存 → GetJieba() 返回 nil → 分词/关键词提取/NLP 依存解析（进而 doc→graph 三元组 抽取）/静态词向量 tokenizer **一律静默返回空列表**，只有一行日志。本机看起来正常 只因开发机与生产机重合、恰好有那份缓存。 现在词库随二进制分发：internal/memory/jiebadict/ 5 文件约 11.6MB + go:embed， 按**内容哈希**命名缓存目录落盘（词库升级不复用旧文件），已齐全则跳过写入。 模块缓存降为兜底。homed 体积 32MB。 顺带确认（并有测试佐证）：gojieba 的 Tag() 不需要 pos_dict/ 目录—— cppjieba 的 PosTagger 从主词典每行的词性列取 tag。 ## 4. homed 放弃 Windows 原生，改走 WSL2 插件体系依赖「继承的 fd」+「统一共享内存区的段内偏移解引用」，Windows 既无 fd 继承语义，其句柄模型也无法表达后者；强行适配等于再维护一套平台专属 ABI （C ABI 时代三套 ABI 并存曾导致改写型插件在某平台静默失效）。 - cmd/homed/platform_{windows,other}.go：原生 Windows 启动即拒绝并打印 WSL2 指引。 - internal/plugin/proc/shmalloc_windows.go：allocShm 直接返回「请用 WSL2」， **不返回半可用的段**（与 shmalloc_other.go 同风格：未支持平台显式报错）； procEnvForShm 返回 nil。顺手修掉两处长期编译错误 （cryptorand→rand、h.evData→h.unified.evtData），使 GOOS=windows 至少能编译。 注：homed 本就编不出 Windows——internal/memory 依赖 cgo-only 的 gojieba。 - deploy/packaging/installer.nsi：不再安装 homed.exe/initconfig.exe，改为携带 **linux payload** 并调用新的 install-via-wsl.ps1；退出码 20/21 表示 「需先装 WSL/发行版」，走指引而非报错。 - deploy/packaging/windows/install-via-wsl.ps1（新）：检测 WSL → 引导安装 → 确保 WSL2 → 送包进发行版 → 在 WSL 内按 Linux 方式安装。**复用 Linux 包与 linux/setup.sh**，不另写一套安装逻辑；落点与 deb 布局统一 （/usr/bin/homed + /usr/lib/homeagent/setup.sh）。 - deploy/packaging/linux/setup.sh：API Key 允许 HOMEAGENT_API_KEY 覆盖 （否则安装器界面显示一份、config.db 里另一份 → 登录不上）。 - deploy/packaging/build.sh：windows 目标只构建 waiter + gui，并新增 stage_linux_payload 把 Linux 包暂存给安装器；homed/initconfig 在 windows 目标下明确拒绝。 ## 5. 插件调用点统一写明意图 - webui 的 OpenAI 兼容端点（固定提示词模板）→ InjectTextSyncNoMemory。 - agentcli 的 5 处纯状态通知（已启动/超时/执行结束/进程退出/读取结束）→ NoMemory； **带输出**的 2 处（定时反馈、有新输出）刻意保留记忆并注明理由。 - timer 的定时提醒 → NoMemory（中断本来也隐含 NoMemory，这里是写明意图）。 ## 6. 版本 meta.Version 仍为 1.2.0（main 是下一个未发布中版本）； SDKCompatibleVersion 1.1.0 → **1.2.0**（本内核已实现 SDK 1.2.0 全部新增方法）。 ## 测试 - core：默认不裁剪（无声明/none/空）、通道 opt-in、注入点双向覆盖通道、 nil context/io 安全、cleaner 优先级与未知名回退。 - io：零值 opts 与历史 payload 逐键相同；text/中断/媒体三类注入标志位都落到 payload；旧方法仍生效。 - proc：validateContextPolicy 只接受 ""/none/prune，报错含位置与实际值； **跨进程** e2e——testdata 插件经 io.injectText 送出三个标志位，断言它们穿过 RPC 到达内核。 - memory：模块缓存不可见时内嵌词库仍可用（分词与 POS 内容词均非空）、 落盘幂等、内容哈希稳定。 验证：go build ./... / go vet ./... / go vet -tags onnxruntime ./... go test -short ./internal/memory/... ./internal/nlp/... ./internal/plugin/... ./internal/agent/{core,io}/... ./pkg/...	2026-09-11 20:31:50 +08:00
JianFeeeee	2bcd3e94ee	refactor(memory): 拆除描述式媒体索引，媒体成为一等块并按原生向量融合 ... 背景：此前媒体是靠「生成的描述文本」将就进记忆的——写 marker 进正文、 再由正则反解成 media_refs 与图库里的 type=Media 实体。这条链路有三个 致命缺陷：描述由异步模型生成（未生成前媒体等于不存在）、语义检索实质上 只搜描述文字、图库里的「媒体节点」是描述文本的投影而不是媒体本身。 本提交把这条链路整体拆除，媒体改为按自己的原生向量参与记忆： 一、描述链彻底删除（无残留、无兼容分支） - media.Item 去掉 Description/DescribedBy 与对应列； - 删除 Store.Describe / Store.Search / Store.Pending； - 删除 Agent.mediaDescribeLoop / describePendingMedia 与配置项 core.memory.media.describe_on_ingest； - SDK 侧 MediaAttachment 去掉 Description（见 SDK 仓独立提交）。 二、marker 机制删除，媒体归属改为结构化块边 - 删除 mediaMarkerLine/parseMediaMarkers/mediaEntityName/mediaTriplesFromText/ extractMediaDigests/sentenceWithMediaMarkers/docMediaContext； - memory.Triple 新增 MediaDigests 结构化字段；句子文本保持原样， 不再被 marker 污染； - 块以 sentence --contains--> block / document --contains--> block 结构边 挂到承载节点（新增 documents 表与 document 节点种类）； - 模型未给原句时用「主谓宾。」拼一句自然语言作落点，不造 marker 文本。 三、旧数据迁移（幂等） - 新增 GraphDB.MigrateLegacyMediaEntities：把 type=Media 的旧实体按短 digest 还原成原生块、挂回原句子、删除旧实体与描述关系；Agent 启动时执行； - CleanupOrphanedSentences 同时看关系引用与块边，避免把只靠块存活的句子 连同块边一起删掉。 四、向量融合：媒体按图本身被召回 - 新增 vector.FuseVectors（逐维求和 + L2 归一化）； - Doc.DenseVec = 文本向量 ⊕ 文档块的媒体向量（同 fingerprint 才融合）， 新增 Doc.DenseFP，指纹变化触发重算； - ContextEvent.DenseVec 同理融合事件块；事件新增 DenseFP，Prune 只在 同一统一空间内比稠密余弦； - 跨模态视觉路只召回「仍被某层记忆块持有」的媒体，CAS 全库字节不再 直接充当记忆检索结果。 五、同时纳入本分支既有的嵌入基础改造（此前工作区未提交，缺它 HEAD 不可构建） - internal/tfidf 懒回退包、千问三段式多模态 ONNX 空间的 Go 侧 （qwen/embedder.go、image.go、model_input.go）、CLIP 移除、 sdk.NewStore 分词器签名与调用点、embed 侧车 systemd 单元。 验证：go build ./... 、go vet ./...（含 -tags medialive）均通过； 在 HEAD 的独立 worktree 上重放本次暂存集后 go test -short ./internal/... 全部通过（端口冲突类用例在隔离环境中亦通过）。未提交工作区中与本改造 无关的改动（HarmonyOS、waiter、devicebridge、plan.md 等）。	2026-09-11 11:45:24 +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	d228f91c4f	feat(shm): 媒体块入共享内存 + 实现 setToolBlocks 桩(§13.13) ... 两个问题叠在一起，先发现的是第二个： 1. **io.setToolBlocks 在内核侧是桩实现**——直接返回“多模态注入待共享段 二进制通道落地”。也就是**子进程插件调 SetToolBlocks 必然失败**（模板 只 log 一行），只有内置插件（multimodal）能用。之前还有测试把这个错误 当作预期行为断言着。 2. 媒体块（injectMedia 系列 + setToolBlocks）把 blocks 内联在 RPC JSON 里， 而本地生成的图/音频是 base64 data URL，一张图可达数 MB。 顺带修掉一条与设计相悖的旧注释：injectMediaParams 写着“data URL 已是 base64 文本、再套一层二进制不会更小，所以走 JSON”。那只算了体积，漏了 两件更重要的事——内联时整份 base64 要在 RPC 报文里再编码/再拷贝一遍； 以及内容本体不在共享段里，插件回调就无法就地改写，只能各持一份拷贝。 共享内存的意义是后者。 实现： - injectMediaParams 加 BlocksRef；新增 resolveBlocks（共享优先、内联回退） - 真正实现 MethodIOSetToolBlocks（空块明确报错，不静默成功） - CoreSDK 接口加 SetToolBlocks，procCore 转调 internal/sdk - 模板：SetToolBlocks / injectMedia 三兄弟经 putValueInArena 传 blocks_ref； 同步调用用 mediaArgsOwned 拿释放函数，**不能在应答返回前释放槽**， 否则内核读到已释放内存 验证（-race 全绿）： - TestCoreHandler_SetToolBlocksViaArena / Inline / EmptyRejected - TestE2E_RealTemplateSetToolBlocksViaArena：真实 SDK 模板编译的插件， 9000 字节 base64 图经 blocks_ref 完整送达 工具链已同步：/usr/local/bin/plugindev 重建为新协议（内嵌 blocks_ref）， 回滚副本 plugindev.bak-20260910-224255。注意内核与全部插件必须同批替换 ——只换一边会静默坏（新内核+旧插件=输出 payload 变空；新插件+旧内核= 媒体注入静默失效），已记入长期记忆。	2026-09-10 22:45:19 +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	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	7ca69f7fb0	feat(proc): Plugin 加载器 + 51 method handler + RunStage 接共享段（Part 2 完成 / Part 4 闭环） ... corehandler.go —— cabi/loader.go 51 个 case 体的整块平移（§3.2）: - 参数从「s1/s2/s3 + i1/i2 五个固定槽」改为结构化 JSON，语义不变 - CoreSDK 接口刻意只含外部插件应得能力：无 Selftest/Supervisor/Tracker/ Status/Adapter/Config/Tool/Indexer/OutputChan/Publish → 权限梯度从「C ABI 表达能力的意外产物」变成「显式声明并强制的策略」（§3.8） - 事件订阅(case 23/24)与 SetToolBlocks 明确返回未实现，不再像 C ABI 那样静默成功 （静默成功后收不到事件比报错更难排查） - ToolDef.Cleaner / ChannelDef.Cleaner 是函数，跨进程置 nil（§3.5 回调型资源） host.go —— 共享段所有权中心: - ❗ 全部子进程插件共享**同一块 memfd**。若每插件一段， 「内核 ctx → 段 → 插件改 → 回读 ctx」在多插件下退化成副本模型， 最后回读者覆盖前者，§8.4 的 35.8~36.8% lost update 原样复现 - stageMu 串行化整次 stage 对段的独占（内核可能并发触发 RunStage） - 首个进入者写入段，最后离开者回读 + Compact（此时无插件持锁，满足 §3.3 前提） stage.go —— RunStage 接线（风险 3.4 落点）: - 并发扇出保留（§0.2 第 1 条：并发扇出是原始设计，不是缺陷） - 插件失败时 ForceReleaseLock，避免后续插件死锁（实验 9，无需 robust mutex） plugin.go —— registry 可加载的插件实体: - Start: spawn（fd 3 传共享段）→ 握手 → plugin.init → plugin.start - Close: **真 kill + wait**，对比 cabi 的 Close 只做 dlclose 而后者是 no-op（§1.1） - invokeOutput **同步等真实结果**，失败上报 error —— §9.4 根治 验证（34 项测试全绿，含 -race，全部用真实子进程）: - 单插件 stage 读改写经共享段回到内核 StageContext - sanitizer(改写) + weather(只读) 并发：清洗结果不被覆盖（现网场景） - **5 个独立进程并发 append 同一 FinalText：5 个标记全部保留，零丢失零撕裂** （实验 8 在真实 RPC + 真实 RunStage 下的复刻） - 工具注册可调用 / 输出通道真实失败上报 / start 期间反向调用 - 未知 method 与未实现能力被拒绝 / stage 外加锁被拒绝 接口冻结: git diff third_party/homeagent-sdk/sdk/ 为空	2026-09-02 11:34:33 +08:00