jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-09-22 09:58:06 +00:00
Code Issues Packages Projects Releases Wiki Activity
341 Commits 6 Branches 27 Tags
cf098a1d4f96de3494c9aa79491d1167b6a99aa7
Commit Graph

5 Commits

Author SHA1 Message Date
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
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
2ebdb9a5b7 plugin: 权限梯度显式化（Part 6.4） 
迁移前，「外部插件拿不到 Selftest/Supervisor/Tracker」是 C ABI 表达能力的
**意外产物**——C 结构体不好传函数指针，这些能力自然到不了插件侧。那是运气
不是策略：任何人给 dispatch 加个 case 就能捅穿。

现在变成显式声明并强制，分三道闸：

1. **类型层**（proc_core.go，Part 6.2 已落地）：procCore 用命名字段持有
   内核 SDK 而非嵌入，未在收窄面写出的方法编译期就不存在。
2. **能力集**（新增 capability.go）：54 个 plugin→kernel method 划入 11 个
   capability 组，manifest 未声明的组被拒。
3. **RPC 边界**（corehandler.Handle 入口）：被拒时返回**明确错误**而非
   静默忽略。

第 3 条针对一类真实故障：C ABI 时代 case 23/24（事件订阅）是空实现，
返回成功但永远收不到事件（§1.3 的「给不了」而非「不给」），插件作者无从得知。
错误消息含四要素：哪个插件、哪个调用、缺什么能力、在哪声明。

## 能力划分的两个判断

**粒度按能力域而非单 method**。逐 method 授权看似更精细，但插件作者要在
manifest 里列 60 个名字，且内核每加 method 所有 manifest 都得改。

**空声明 = 不受限，而非「只有 core」**。17 个存量插件的 plugin.json 都没有
capabilities 字段。若空声明当作最小权限，它们会全部失去 IO 注入、记忆读写
而**静默降级**——违反「外部插件零改动」的硬约束。收紧的路径是让插件显式
声明，而不是默默拒绝老插件。

## core 与受限能力的边界

core（无需声明，始终可用）：注册自身工具/阶段/通道/API、读写**自己的**配置、
共享段锁仲裁、握手、autoRestart 自述、setToolBlocks。没有这些插件无法工作。

受限（需声明）：io / memory / doc_memory / knowledge / text_memory / llm /
social / events / plugin_mgr / settings_cross。

settings 刻意拆成两级：读写自己的配置属 core（正常工作所需），读写**其他插件**
配置或**内核核心**配置属 settings_cross（能改别人/内核的行为）。

## withheldCapabilities：让「不给」可见

10 项刻意不提供的内核内部机制列在表里并附理由。它们没有对应 method 常量——
不是忘了加，是决定不加。列表存在本身就是「这是策略而非疏漏」的证据，
读代码的人能看到边界在哪，而不是从「protocol.go 里没有」这个负面事实去推断。

## 测试

proc 包 10 项：
- AllMethodsClassified：**最重要的一项**。漏登记的 method 会按 CapCore 放行，
  等于绕过整套检查。新增 method 忘登记时当场报出。
- EmptyDeclarationIsUnrestricted / DeclaredSetRestrictsOthers / CoreAlwaysAllowed
- SettingsScopeSeparation：自身配置 vs 跨插件配置的归属
- DeniedErrorIsActionable：错误消息四要素
- HandleEnforcesAtRPCBoundary：被拒的调用不进 switch
- WithheldListIsDocumented：每项都有理由，且不被任何 method 暴露
- UnknownMethodFallsThrough：未知 method 报「未知」而非「权限被拒」，
  否则作者会以为是漏声明能力

写这个测试时踩到自己的坑：第一版用子串匹配查 withheld 泄漏，"Tool" 匹配到
tool.register 和 io.setToolBlocks 误报——那两个是合法开放的（注册自己的工具）。
改成前缀 + unregister 关键字匹配，withheld 项也改名带 API 后缀以示区分。

internal/plugins 2 项接线验证：
- RestrictedPluginStillLoads：只声明 io 的 weather 仍能加载并注册工具
  （它在 Start 里读 Settings，属 core）
- LegacyManifestUnrestricted：无 capabilities 字段的存量插件正常加载

真实 homed 实测：
  [plugin] weather-capped 声明能力: [io]
  [plugin] weather-capped: 经 proc 通道加载（子进程）
  registering tool: weather-capped_current / _forecast / _set_location

验证：go build ./... 通过；go test ./... 全仓无失败；
go test -race ./internal/plugin/... 全绿；go vet 干净。

Ref: docs/zh/架构迁移评估.md §3.8、docs/zh/plugin-migration-plan.md Part 6.4
 2026-09-02 21:27:13 +08:00
JianFeeeee
5bbfcc02fb plugin: 事件环内核侧实现（§3.6 Part 5 核心） 
事件环（EvtRing）是子进程首次获得事件订阅能力的基础设施。
此前 case 23/24 明确返回未实现，现在经事件环真正可用。

核心设计（§3.6，实验 4 已验证 post-and-forget 加速比 2218x）：
- 事件环放**独立共享段**（不与 StageContext 混放）：stage compact 会清 arena，
  事件要独立于 stage 生命周期。Host 持有两块 memfd：fd 3 = StageContext，
  fd 4 = 事件环段，fd 5 = eventfd。
- 无锁数据结构：内核 WritePush 追加写 slot，子进程 EvtConsumer 消费。
  writeSeq 原子递增（Bus.Publish 并发调用），readSeq 每订阅者独立。
- eventfd 通知：Linux 用 unix.Eventfd（计数合并，1000 token 只唤醒几次），
  macOS 用 os.Pipe（阻塞模式走 netpoller，只 park goroutine，实验 1 验证
  200 等待者仅 +1 OS 线程）。两者行为一致：Read 阻塞直到有新事件。
- 溢出语义：落后超 cap 时跳到最新，丢弃计数记入 dropped（消费者知道丢了）。
  不静默覆盖最旧（写端直接覆盖 slot，读端靠 seq 判断跳过）。
- 事件类型编码：pubsdk.EventType 字符串 ↔ uint32 位索引（编译时映射表），
  typeMask 位掩码过滤（1<<idx）。

Host 改动：
- NewHost 同时创建事件环段和 eventfd（惰创建，一次分配）。
- Host 持有 evtSubscriber 接口（EvtRingSubscriber），由 Registry 注入
  EventRing 实现——proc 包不依赖 internal/plugin（避免循环依赖）。

corehandler 改动：
- events.subscribe（原 case 23）：子进程传事件类型列表，coreHandler
  通过 evtRing 接口调用 EvtRingSubscribe，注册到 Bus 上。
  事件经 EventRing 写入环后由子进程 mmap 读取。
- events.unsubscribe（原 case 24）：当前由内核统一清理（子进程 Stop 时）。

Registry 改动：
- ensureProcHost 在创建 Host 后同时创建 EventRing（Bus → EvtRing → eventfd），
  并通过 Host.SetEvtSubscriber 注入给 coreHandler。

测试 3 项：
- BasicWriteAndConsume：Host 创建 → EventRing 写入 → 消费者读到
- OverflowStillDelivers：写入超过 cap 后消费者仍能读到最新事件
- TypeMaskFiltering：typeMask 只订阅 tool_call，agent_output 被过滤

验证：go build ./... 通过；go test -race ./internal/plugin/... 全绿；
既有事件环测试 3/3 通过；proc 包测试未受影响。

Ref: docs/zh/架构迁移评估.md §3.6、docs/zh/plugin-migration-plan.md Part 5
 2026-09-02 16:48:27 +08:00
dev
82dcc86173 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