jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-09-28 13:23:03 +00:00
Code Issues Packages Projects Releases Wiki Activity
705 Commits 5 Branches 27 Tags
bcd75d25fda53b0b8f9af1600c3100232fbd94ee
Commit Graph

24 Commits

Author SHA1 Message Date
JianFeeeee
2232d5483c feat(parallel): 并发安全改为声明式，并审计标注 37 个工具 
把"能不能并发"从内核硬编码名单改成**工具自己的声明项**，形态照 SDK 的
NoMemory 走。

## ★ 起因：提示词在跟内核不一致

阶段 2.5 写进提示词的「内核默认并行执行」当时是**假的**：toolParallelSafe
只查 stageHost 与 io 两个来源，而全仓 ParallelSafe:true 的生产代码数量
是 **0**。于是除碰巧只发一个工具外，每一批都整批串行回退，而提示词正教
模型把多个查询放同一轮。**内核行为与提示词不一致 = 对模型说谎。**

并发面：0 → 37 个工具（18 插件 ParallelSafe + 19 插件 Serial + 9 内置只读）。

## 声明形态（照 SDK，不自创）

### 插件：结构体字段
    s.RegisterTool("config_get", sdk.ToolDef{
        Name: ..., Description: ...,
        Parameters: map[string]interface{}{...},
        // 已核实只读：…
        ParallelSafe: true,      ← 插在 Parameters 之后、handler 之前
    }, p.handleGet(s))

位置与 SDK 的 NoMemory/ContextPolicy/RecallPolicy 一致：Name 在首位，
声明项在末尾，不打散 gofmt 对齐。

### 新增 SDK 声明项：ToolDef.Serial
ParallelSafe 的**反向**标记，判据优先级高于 ParallelSafe。
为什么需要：ParallelSafe 零值 false 已表达"安全"，插件无法区分"我没想过"
与"我确认过必须串行"。没有这个区分，工具作者只能靠命名约定传递意图。

内核已消费它（io.ToolDef 同步加字段对齐），并有判据守"Serial 胜出"。

### 内置工具：toolDef 的 toolParallel 选项
内置工具以裸 schema map 下发，没有 ToolDef 结构，所以用变参选项：
    toolDef(名字, 描述, 属性)                  // 默认串行
    toolDef(名字, 描述, 属性, "toolParallel")  // 已核实只读，可并发
读工具表的老调用点一行不用动，声明就写在工具定义那一行。

## ★ 走过的弯路（都留了判据）

1. **硬编码白名单**：先在 toolParallelSafe 里查一张
   builtinParallelSafeTools map。那把声明从"工具自己"搬回了内核 ——
   工具改名/新增不会自动跟着变，得靠一条 grep 源码的判据才能发现漂移，
   而判据一改就忘。已删，改为从定义读。

2. **判据前提错（同一个坑踩了两次）**：拿裸 &Agent{} 的 buildToolDefs 输出
   当"实际可见工具"，但这 9 个内置工具全在条件分支里（a.knowledge != nil /
   a.social != nil / a.parentID != ""…），裸 Agent 一个都不产出 ⇒ 全部误报
   "声明形同虚设"。第一次叫它"幽灵条目"，没认出是同一个坑。

3. **注释模仿真实签名污染判据**：toolParallel 的用法注释写着
   `toolDef("knowledge_search", ...)`，判据按文本匹配先撞上注释。

4. **buildToolDefs 的 nil 不一致**：开头判了 a.io != nil，末尾却无条件
   a.io.ListChannels()。任何无 IO 的 Agent 调它都 panic —— 而 panic 报在
   io 包里，根因在 tooldefs.go。已补。

5. **插入脚本用正则找"最后一个顶层字段"**：被嵌套 map 里的同形文本骗到，
   823 处错误重排把文件改坏。改用括号深度 + 记录进入深度 3 的行号
   （空 properties 会让深度在同一行进出平衡，只判 depth==2 不够）。
   工具在 SDK 仓 tools/annotate_parallel/，复用时用绝对路径。

## 提示词措辞同步修正
「默认并行执行」→「尽量并发执行，但这是**逐工具判断**的」，并教模型
**把查询类放同一轮、写操作单独发一轮**（写和查混在一批，整批都串行）。

## 判据
- TestSerialOverridesParallelSafe          Serial 优先于 ParallelSafe
- TestToolParallelDeclarationsAudit        并发面不许再归零
- TestNoToolDeclaresBothParallelAndSerial  两者同标即谎话
- TestBuiltinParallelDeclaredWhereDefined  声明写在定义处、且内核真读到
- TestStoreListIgnoresForeignJSON          压测抓到的 List() 缺陷
 2026-09-27 15:15:57 +08:00
JianFeeeee
34c0df2705 feat(toolcall): 批次并发调度与同通道保序（阶段 2d，闭合 2c 判据缺口） 
规则（三条全满足才并发）：
  1. 批内 >1 个工具
  2. **全部**工具声明 ParallelSafe —— 一个不声明就整批降级，不做部分并发
  3. 不含需保序的同通道输出发送

SDK：
· ToolDef 加 ParallelSafe bool。⚠️ 零值 false 是刻意的：存量插件不改一行
  就得到**保守**行为（整批串行），不会因升级被意外并发。声明它是责任
  而非特权。纯新增字段，无签名变更。
· io.ToolDef 同步加该字段（设备/通道工具走 io 路径，只查 StageHost 会漏）。

core：
· 新增 StepToolBatch —— runTaskSteps 是单线程驱动状态机的，
  「每步一个工具」的游标模型无法表达「一批同时跑」，故需独立 step。
· stepToolBatch：fan-out（每工具一 goroutine，各写自己的 toolCtxs[i]）
  → join → **按索引顺序**串行收尾（after_toolcall / 落消息 / 事件）。
  收尾必须串行且按索引：f.Msgs 是共享切片，且按索引落才能让模型读到的
  上下文顺序与它自己发出的顺序一致。
· runOneTool 抽出「before_toolcall + 执行」的单工具逻辑，串行/并发两条路共用。
· toolParallelSafe / batchRunnable 判据函数。

★ 修掉一个我自己引入的竞争：resolveTurnScenes 会把结果记进**共享**的
f.sceneDone / f.turnScene（memorypass.go:289）。最初在每个 goroutine 里
各调一次 —— 既是数据竞争，又会各自触发一次 EnterSceneWithHint，
重复计入场景强度（正是 sceneDone 注释警告过的问题）。改为在 fan-out
**之前**解析一次，goroutine 内只读。

判据（parallelsched_test.go，4 条）：
· 全批 ParallelSafe ⇒ 并发峰值 >= 2（用阻塞设备观察真实并发）
· 一个非 ParallelSafe ⇒ 整批串行，但**仍全部执行**
· 同 output_send__<通道> 连发 3 条 ⇒ 严格按声明顺序到达
· ★ 并发下每个工具的 ctx 只带自己的 ToolCalls、after 读到自己结果

★ 并关闭了 2c 的判据缺口：此前两条 2c 判据在**串行**下无法区分
per-tool 与单槽（变体验证后仍全绿）。新增的并发版判据在退回单槽时
触发 **6 处 DATA RACE 报告 + 串味断言失败**（dup:k_a 与 k_a 撞名）。
至此 2c 可记为已验证。

过程中三次自伤：
· resolveTurnScenes 竞争（上述）；
· 我的 harness 用 StageHost 注册 handler 遮蔽了设备工具，
  slowDevice 根本没被调用（"实际 0"）——改为在 io.ToolDef 上声明；
· 批内并发峰值判据最初用 StageHost 声明 ParallelSafe，掩盖了
  「设备工具也需要该字段」这一真实缺口。

回归：internal/agent/... internal/sdk/... internal/plugin/...
      internal/plugins/... 全绿（17 包）；core 包 -race 全绿。
 2026-09-27 11:27:24 +08:00
JianFeeeee
25f5c53086 feat(io): 多模态块改 per-call 归档，为并行执行铺路（阶段 2b） 
问题：ConsumeToolBlocks 此前是 **IOManager 级单队列**（取走即清空），
没有 call_id 维度。并行化后同批多个工具各自注入媒体时，后执行的
Consume 会**抢走**前一个的块 ⇒ 媒体挂到错误的 tool 消息上。而
task.go 里「媒体必须走 user message 且紧跟自己的 toolMsg」那条结论
是三轮实测才定下来的，并行会直接破坏它。多模态插件在 3 处调
SetToolBlocks（multimodal/plugin.go:136,246,320），是真实使用面。

改动：
· 字段 toolPendingBlocks: []interface{} → map[string][]interface{}
· 新增 SetToolBlocksFor / ConsumeToolBlocksFor / ClearToolBlocks（按 call_id）
· 保留 SetToolBlocks / ConsumeToolBlocks 作兼容入口（走 callID=""），
  存量调用方与串行单工具场景不受影响；其注释写明并行下该路径不可靠

判据（toolblocks_test.go，4 条）：
· 两个 call 各自注入、**交叉顺序**并发取回，各归其主
· 取走即消费（二次取回为空）
· 未知 callID 返回空且**不影响他人**的块
· 32 路并发零串味

变异说明：本阶段是从「单槽」直接改为 per-call，旧实现在这四条判据下
（per-call API 不存在）无法编译通过，等价于判据先失败；per-call 版
再经 `go test -race` 验证无数据竞争。回归：internal/agent/io 全绿。
 2026-09-27 11:06:41 +08:00
JianFeeeee
bce40b5099 feat(toolcall): 按 schema 预校验参数，在分派前拦下（阶段 1c） 
问题：`required` 在仓内被声明 69 处，却**无任何消费方**（内核从不读）。
校验散落在每个工具内部手写成中文字符串（"path is required"），
要等工具真被调用才暴露——而模型看到这类与真因无关的报错只会原样重试
（实测 cmd_run 失败率 34%~48% 的成因）。

改动：
· core/argvalidate.go: validateToolArgs（纯函数）+ validateArgsAgainstSchema。
  ★ 校验器刻意**宽松**：只拦真正无法解析的形态，对模型实际会写的等价形态
  一律放行。依据是工具内部 getter 的既有约定（utils.go 注释：
  "实际调用里 bool/string/float 三种都出现过"；unitNumberRe 修的正是
  `"20s"` 少引号那类）。**校验比工具更严就是在制造新失败**。
  · required 判据是**键存在性** + 非空字符串；显式 null 视为已提供
    （模型可能有意传 null，工具按零值处理，判成缺失即误伤）
  · boolean 全放行（getBool 的 true/"1"/"0"/"yes"/0/1 全都合法）
  · integer 接受 int/float64/"20"/"20s"；string 接受含 JSON 的长文本
  · 无 schema / 无 required / 查不到 schema ⇒ 一律放行
· core/toolcall.go: 在 __arg_error 短路**之后**、分派**之前**接入。
· io/channel.go: 新增 IOManager.ToolDefOf——没有它就只校验到插件工具，
  而 cmd_run / files_write 这类**设备/通道工具会完全绕过校验**。

判据（argvalidate_test.go，7 组）：
· 缺 required 被拦下并指名字段
· ★ 误伤防线：bool 传 "true"/"0"、integer 传 float64/"20"、
  显式 null、字段顺序不同 —— 全部必须放行
· 类型确实不符报 type 错误
· 无约束场景一律放行（含 args 为 nil + schema 带 required ⇒ 应拦，
  这条我最初**误放进放行组**，写完立刻发现改正）
· 错误文案含字段名/必填/改法（否则模型只会原样重试）
· 端到端：缺参时**设备真的没被调用** + 文案指名字段
· 端到端反向：参数齐备照常执行（校验不得阻塞正常路径）

变异验证（两轮）：
· 关闭分派前校验 ⇒ 端到端判据 FAIL「仍进入了工具」
· 把 boolean 校验改严格 ⇒ 宽松防线 FAIL 两个子用例（误伤 "true"/"0"）

过程中三次自伤：臆造 sdkToolError 别名；number 分支写了没有绑定的 x(v)；
把"显式 null"先当成缺失、过度修正后又漏掉"键不存在"的判定——
最终改为「键存在性 + 非空串」双条件，null 与缺失各归其位。

回归：internal/agent/... internal/sdk/... internal/plugin/...
      internal/plugins/... 全绿（18 包）。
 2026-09-27 10:56:02 +08:00
JianFeeeee
7a566d50b7 fix(toolcall): 工具「不存在」类型化 + 修父 io 兜底吞错误 + 修并行 tool_call 落序随机 
主线：工具调用并行化改造（阶段 0 与 0.2）。

① flush 顺序随机（process.go）
   flushToolCall 由 `for idx := range accs` 驱动，Go map 迭代顺序随机化
   ⇒ 同一批并行 tool_call 进入 resp.ToolCalls 的顺序每次运行都可能不同。
   对 output_send__ 这类用户可见通道，分段消息到达顺序不可复现。
   改为收集 index 后 sort.Ints 再 flush（两个调用点统一走 flushAll）。
   判据 stream_flush_order_test.go（8 工具 × 200 轮），已变异验证可检测。

② 工具「不存在」类型化（io/channel.go、core/stages.go、core/toolcall.go）
   工具是动态注册的，「不存在」是运行期常态而非异常。原先内核用
   strings.Contains(err, "not found in any plugin") 判别——约定而非契约，
   插件文案含该子串即被误判。改用哨兵 ErrToolNotFound + errors.Is
   （沿用仓内 ErrInputChannelUnknown 的先例）。

   ⚠️ 顺带修一个静默 bug：IOManager 向父兜底时吞掉父的执行失败，
   误报为「工具不存在」。后果是设备离线这类本该 retry 的失败被判为
   「工具没了」⇒ 整组被跳过，与「插件真没加载」无法区分。改为只传递
   「确实不存在」，其余如实上抛。

   「不存在」的文案改为可执行指引（get_plugin_tools / output_list_channels），
   而非含糊的「执行失败」——后者会让模型反复重试同一个不存在的名字。

判据：toolcall_error_test.go（类型化 vs 诱饵子串、%w 穿透、执行期文案）、
channel_error_test.go（父失败不吞、真的不存在仍可判别）。
两者均经变异验证。回归：internal/agent/... 与 internal/plugins/... 全绿（14 包）。

设计文档：docs/zh/toolcall-contract-and-sequence-design.md
执行计划：docs/zh/toolcall-parallel-execution-plan.md
 2026-09-27 08:55:25 +08:00
JianFeeeee
8887e06274 feat(sdk+memory): 补 ScenePolicy 声明项，让通道能退出场面识别 
缺口（R6）：ChannelDef 的记忆声明已有三件套——NoMemory 管「进不进
记忆计算」、ContextPolicy 管「裁不裁上下文」、RecallPolicy 管「召不召回
记忆」，唯独没有「这条输入算不算一场戏的一部分」。现状是无条件参与：
situationFeaturesFor 里只要 evt.Source != "" 就产出一个 chan 特征，没有
可关的开关 ⇒ chan:system / chan:kernel / chan:timer 这类纯内部信噪通道
也在撑场面，每次触发都让不相干的场景长出来或变强，召回时又会把
「内核在跑定时器」当成「用户在这类场景下说过的话」取回。

穷举确认不是查漏：go.mod replace 指向 third_party/homeagent-sdk，
plugin.go 中 scene 出现 0 次，SDK 自身 git 历史 -S'Scene' -- sdk/ 为空。

SDK（纯追加，老插件行为逐字节不变）：
- 常量 ScenePolicyAuto / ScenePolicyNone + ValidScenePolicy，形状与
  ContextPolicy / RecallPolicy 完全一致
- ChannelDef.ScenePolicy 与 InjectOptions.ScenePolicy，均带 omitempty
- 默认取 auto（参与）而非 none：场景只附加检索路、不改记忆本体，
  默认关会让存量通道突然失去召回；「关」是少数意图。与 ContextPolicy
  刻意相反（同为破坏性操作，那里是默认关）。

内核：
- applyInjectOpts 搬运 scene_policy（与另外三个标志位同面）
- sceneSuppressed 完全照 recallDeclared 的形状：注入点 payload >
  通道定义 > 默认。none 时连时段(part)特征都不产，也不派生场景键
  （只停指纹采集而留声明路，等于给这个口子开后门）
- situationFeaturesFor / sceneKeysFor 由包级函数改为 Agent 方法
  （需要 a.io 查通道定义），23 个调用点同步

判据：scenepolicy_test.go 7 例，改前编译期红（undefined:
pubsdk.ScenePolicyAuto），改后全绿。其中两例专门护住「未声明时行为
逐字节不变」，是纯追加承诺的护栏。

记忆 8 包 + agent/core 全绿，8 包齐全、无 FAIL/panic/race。

存量通道标注待定：kernel/timer/offload-*/child/* 是纯 0-refs 信噪，
可直接标 none；但 mc:system(12 refs) 与 system(3 refs) 带真实记忆，
性质不明，不擅自标。
 2026-09-26 20:09:17 +08:00
JianFeeeee
895948b24e fix(stop): 配额须计入停在输入 channel 的待处理消息 
实测：停止后排队消息仍逐条跑完。原因是 armStop 只数 sched.queue，
而用户按下停止时调度器正忙于当前任务，其余消息大多还没被 pumpInbox
搬进队列、仍停在 inputCh ⇒ queued=0、配额归零。

- IOManager.PendingInputs()：暴露 channel 中待处理条数。
- armStop(pending int)：queued = len(s.queue) + pending。
- 补 TestStop_ArmCountsPendingChannelInputs 锁死该口径。
 2026-09-18 11:39:04 +08:00
JianFeeeee
b792a94b84 feat(memory): 新增可声明的召回轴 RecallPolicy（与 prune 正交） 
问题：召回（把 L2/L3 相关记忆注入本轮）此前不可声明、也不受任何 SDK 字段
控制——它只在任务开始时对 f.Input 无条件跑一次。于是 qq_get_message 取回
真实正文后只触发 Prune（裁剪），从不触发召回；而中断通知的 meta 文本反而
会去召回（词不对题，命中一堆泛实体）。

改动：
- SDK 新增 RecallPolicy(none|auto) 轴，落在 InjectOptions / ChannelDef /
  ToolDef 三个声明面，与 ContextPolicy 正交（裁剪 vs 召回）。默认值与
  prune 刻意相反：输入/注入默认 auto（保持既有「每条输入都召回」），
  工具默认 none（工具输出多为噪声，按需声明）。
- 内核：recallDeclared 按 注入点 > 通道 > 默认auto 解析；输入侧用它决定
  是否注入记忆索引；工具侧 ContextPolicy/RecallPolicy 共用同一份清洗后
  query，一次相关性过程分别 prune / recall；召回以 system 消息挂到消息
  末尾（同任务内替换而非累加）。
- 管线：proc RPC（inject/register + 校验）、lua 键、io payload 全量透传。
- QQ 插件：中断与 qq 通道声明 RecallPolicy=none（meta 不是内容）；
  qq_get_message 声明 RecallPolicy=auto（取回正文后据正文召回）。

测试：新增 recallpolicy_test.go（core）与 proc 校验用例；
go build ./... 通过，go test ./internal/... 全通过，SDK 模块与 qq 插件测试通过。
 2026-09-14 23:14:38 +08:00
HomeAgent Agent
11d9038927 fix(io): ChannelRegistry 补 UnbindOutputTarget，Unregister 清理 outputTargets 
outputTargets 只增不减：Unregister 一个 inputch 后，指向它的输出目标登记仍
留在表里，ResolveOutputTarget 会继续把消息路由到已不存在的 agent/inputch。
与刚修的驻留 inputch 残留同属「注册未注销」类。现补 UnbindOutputTarget
（幂等），并让 Unregister 顺手清掉显式绑定与同名回退两种目标登记。
 2026-09-13 21:59:10 +08:00
JianFeeeee
886ba78b11 fix(scheduler): inputch 划给子后输入只流向子 —— 补上「进内核之前」的输入路由 
用户指出的语义（设计稿 §4.1 早已写明）：
**inputch 是可分配资源**，「路由发生在**进内核之前**」—— 划给某个 agent 后，
该通道的输入**只流向那个 agent**；outputch 不同，授权是**非独占**的，
父依旧可以通过它发送内容。

而代码里 inputch 划拨只做了**登记**，没有做**路由**：
- 插件注入输入的 io 是**根 agent 的**（`cmd/homed` 里 `pluginReg.SetIOManager(iom)`）；
- 唯一消费输入的是「该 io 自己的调度器」（`scheduler.go` 读 `a.io.InputChan()`）；
- `ChannelRegistry.Assign` 只把 Owner 写进登记表，**没有任何转发动作**。

⇒ 现场表现（用户线上联调）：子挂 `inputch=[timer]`，**timer 的输入却打在父身上**
（日志 `[agent] interrupt from timer/timer`），子侧 `轮次=0` 永远不动。
登记表里的 Owner 于是沦为标签。

改法（按 §4.1 把路由放回"进内核之前"）：
- `IOManager` 增加 `InputRouter`（`SetInputRouter`），并把**五处直接入队**收口到
  `deliverInput`：`InjectInput` / `InjectInputSync` / `InjectInputTo` /
  `InjectInputSyncTo` / `InjectInterrupt`（排队与中断两条路都过路由）。
- 内核注入路由器 `Agent.routeInputByOwner`：查 inputch 的 Owner —— 归自己/未分配 ⇒
  本内核处理；归自己的某个驻留子 ⇒ `DeliverRouted` 交给它（**不再进父的队列**）；
  归一个不存在的 agent ⇒ **不吞输入**，父兜底 + 留痕（吞掉输入比多处理一条更糟）。
- `DeliverRouted` 是"已路由"的投递口，不再二次路由（避免成环）。
- 同步输入的 `ResponseCh` 随事件一起走 ⇒ 回答由持有者写回同一回程（§4.3）。

判据（新增 6 条）：
- io 层：被接管时排队/中断都**不入本内核队列**（且中断确实经过路由）/ 放行与未设
  路由器时与历史行为一致 / `DeliverRouted` 不再触发路由
- 内核层：划给子的 inputch 输入进**子**（子 Executed>0）且**父 Enqueued 不变** /
  归属到不存在的 agent 时父兜底（不吞）/ 未分配的 inputch 仍归父

(cherry picked from commit 4707b05498)
 2026-09-13 15:35:59 +08:00
JianFeeeee
91c4bc01f1 fix(resident): 驻留子继承父的输出通道 —— 修「子侧 childIO 空壳、子不会发消息」 
现场（用户在线上跑驻留子联调，日志实录）：
  父 agent 侧「通道装载完整」，子 `demo-resident` 侧 `childIO` 是**空壳**：
  子的 `output_list_channels` 为空、`output_send__<通道>` 一律被判
  「通道 [X] 不存在或不可用」，连 `output_send__*` 工具都不生成 ⇒ 子不会发消息。

根因：**输出通道在 io 层就是 Device**，而它们由插件登记在**父**的 `IOManager` 上。
`SpawnResident` 给子建的是全新 `IOManager`（它确实该有自己的输入入口与 outputCh），
却只共享了 inputch 登记表，**没有继承设备/输出通道视图**：
  - `executeOutputSendTool` → `a.io.GetChannelCapabilities(ch)` 查的是 `devices[ch]` ⇒ 0
  - 投递路径 `a.io.GetDevice(ch).Execute("output", …)` ⇒ nil
  - 工具面 `tooldefs.go` 从 `a.io.ListChannels()` 生成 `output_send__*` ⇒ 空

改法：给 `IOManager` 增加**上级回退**（`SetParentIO`）——驻留子创建时把自己的 io 挂到
父的 io 上，`GetDevice` / `GetChannelCapabilities` / `ListChannels` / `ExecuteTool`
在自己没有时回退到上级。

为什么是**实时回退**而不是创建时复制快照：设备随资源生灭（远程设备上线/掉线以分钟计，
现场日志 60 秒一个来回），复制出来的表转瞬即过期；而回退永远与父一致。
**授权不受影响**：回退只解决"看得见"，能不能用仍由各自的 `AllowedOutputs` 白名单把关
（`executeOutputSendTool` 的授权闸 + 工具生成时的过滤都在白名单之后）；
自己的登记优先，子可以覆盖/屏蔽同名通道。

判据（新增 5 条）：
- io 层：无上级时行为与以前完全一致 / 挂上级后看得见 / **实时**（父新登记立刻可见、
  注销立刻不可见）/ 同名自己的优先且不重复列出 / `ExecuteTool` 同样回退
- 内核层：子看得见父通道 + 真能发出（父通道收到 1 次 output）/ 白名单外被拒且未送达 /
  子工具面只生成授权通道（含 `_help`）/ 父后登记的通道立刻可见 / 默认即完整授权

(cherry picked from commit 8537577123)
 2026-09-13 15:09:44 +08:00
JianFeeeee
f0be8cbaa5 feat(remotedevice): 设备能力 outputch 化 —— 每设备一个 device/<id> 通道 + 设备指令类工具补授权闸 
用户指出 remotedevice 的能力应当 outputch 化。查证后发现比"应当"更严重：
设备方向**根本没有出站实现**。

## 查到的三个缺口

1. `devicectlDevice` 一直声明 `OutputCapabilities() = CapStructured`（对外宣称可作输出目标），
   但 `Execute` 的 switch 里**没有 "output" 分支** ⇒ `output_send__devicectl` 必然拿到
   `unknown device tool output`，回模型"通过 [devicectl] 通道发送失败"。
2. 全插件没有 `RegisterOutputChannel`，也没有任何 EmitOutput/output_send 路径：
   设备方向只有「工具（请求-响应）」与「设备→agent 注入」，**agent → 设备是断的**
   （唯一的下行通道是个 HTTP 端点 `/api/v1/device/push`，不在 agent 的工具/通道模型里）。
3. 寻址是聚合的：所有设备共用一个名字 `devicectl`，没有 `device/<id>`；且设备 caps 只在
   插件内部软检查（`SupportsTool`），**绕过**了内核的 `AllowedOutputs` 授权闸 ——
   驻留子只要拿到 `device_ctl_cmdrun` 就能指挥**任意**设备。

## 按方向切分（不是一刀切）

**出站/消息类 → 每设备一个输出通道 `device/<id>`**（与入站同名）：
- 上线注册、掉线注销（caps 由设备声明的 caps 映射：文本恒有；有屏→图/文件；
  speaker→音频；可跑命令(cmd/cmdrun/cmdresult)或未声明已知能力→全能力，与
  `deviceSupportsTool` 的旧设备兼容规则一致）。断连不注销会留下死通道骗模型。
- 于是自动获得：内核按 caps 在**发送前**拦（送图给纯文本音箱直接拒）；
  `output_list_channels` 能列出设备；`AllowedOutputs` 可按设备收窄给驻留子。
- 上下线钩子用 `Registry.SetPresenceHandler`（**同步回调**）而不是既有的 `ChangeChan`
  （那是 select+default，缓冲满会丢事件；丢一次就留下死通道或漏注册）。
- `devicectl` 保留为聚合通道，并把它"声明了却不实现"的 output 补实：按
  `meta.device_id`（或 meta 就是设备 id / args.device_id）路由；缺省时返回**可执行**的
  报错（列出在线设备），而不是含糊失败。

**RPC 类保留为工具**（`devicedetect`/`screensee`/`computeruse`/`clipboard*`/
`device_ctl_status|cmdrun|cmdresult`）：它们的返回值（图像/命令输出/状态）必须进模型
上下文，做成通道会丢掉这个语义。

**并给设备指令类工具补上同一道授权闸**（core/toolcall.go）：`device_id` 指向的设备
必须是本 agent 被授权的 `device/<id>`。根 agent 默认完整授权 ⇒ 无行为变化；
驻留子收窄后，"拿到工具就能指挥任意设备"的缺口被堵上（新增 3 条 core 测试钉住）。

**设备端参考实现**（`internal/devicebridge/client/bridge.go` + waiter）：新增 `op=push`
分发与 `OnPush` 回调（文本/结构化；二进制走既有 `cmd_speech_*` → `DataHandler`），
waiter 把它打到终端。

## 设计口径（用户当场纠偏，已写进代码注释与 harness README）

**主动转发只有 webui 与 cli 两个交互界面**（webui 订阅 EventAgentOutput 渲染气泡、
cli 用同步回程写回终端）。其它通道一律要求 agent **显式** `output_send__<通道>`。
我第一版给 remotedevice 加了 `EventAgentOutput` 订阅来自动回投设备——那是凭空造了
第三个转发者，违背"输出是 agent 的主动调用"，已撤回（该测试一并删除）。

## 验收

- 单测：caps 映射词表；设备上线→注册通道（含同名 inputch）/掉线→注销；push 真落到
  WS 设备；聚合通道 `devicectl` 的寻址（无 device_id 报可执行错误、按 meta 投递、
  指定不存在设备报错）；core 授权闸 3 例。
- 全量 `go test ./...` = 37 包 ok / 0 FAIL；`-race`（agent/plugins/plugin/devicebridge/sdk）干净。
- **真二进制端到端**（私有 netns + mock LLM + 真 WS 设备客户端 scripts/kernel-stress/devclient.py）：
  设备上线 → 通道表出现 `device/pydev-1`（caps=[text file image audio structured]，由
  `caps:["cmd"]` 映射）→ agent 经 `output_send__device/pydev-1` 主动发送 → 设备收到
  `{"op":"push","payload":"内核推给你的消息","type":"text"}` → 设备掉线 → 通道从表中消失。
 2026-09-13 12:23:28 +08:00
JianFeeeee
f7c3a4e81d feat(channel): N1b —— 输出通道授权集合（三处过滤一致）+ 输出通道→目标 agent 的 inputch 解析 
设计：docs/zh/resident-subagent-design.md §4.5（里程碑 N1b）。

## 输出通道授权集合（默认完整授权，父可收窄）

`AgentConfig.AllowedOutputs`（nil/空 = 完整授权）。三处过滤点必须一致，
否则会出现「列表里看不到、按名字还能调」的裂缝：

1. **工具表**：不为未授权的通道生成 output_send__X（模型看不到就不会调）
2. **列表工具**：output_list_channels 只列授权的
3. **调用点**：凭名字直调未授权的输出门必须被拒（纵深防御）

## 输出通道 → 目标 agent 的 inputch 解析

`ChannelRegistry.BindOutputTarget / ResolveOutputTarget`：
把输出通道解析成「目标 agent + 目标 inputch」，这是"输出可寻址到具体 agent"
（子→父、父→指定子）的**数据面**；真正的跨 agent 投递在里程碑 N4。
未登记的输出通道 ok=false —— 表示由传输层 device 自行处理（qq/webui 这类）。
已登记目标的输出通道，在 output_list_channels 里会标出「目标: <agent> / inputch <名字>」。

## 验收

`internal/agent/core/output_grant_test.go`（3 项）：
- 默认完整授权：全部输出门生成 + 列表含全部
- 白名单收窄：三个过滤点同时生效（工具表 / 列表 / 直调被拒）
- 目标解析：绑定/解析、未登记由传输层处理、列表标出目标、空名报错

全仓 go test ./... 37 包 ok / 0 FAIL。
 2026-09-13 09:13:19 +08:00
JianFeeeee
3c961b7bd7 feat(channel): N1a —— inputch 一等化（归属插件/归属 agent/容量/共享登记表）+ 单工具多视图总览 
设计：docs/zh/resident-subagent-design.md §4.6（里程碑 N1a）。

## 用户要求

「父 agent 可以看到所有已注册的 inputch 以及 inputch 的划分情况，用**单工具多视图**方式构筑」

## 登记层（internal/agent/io/inputch.go）

inputch 是**最基本的输入路由单位**（由插件注册，一个插件可注册多个），
所以登记表以 inputch 为键，每条记录：

    名字 / 归属插件 / 归属 agent(被划给谁) / 容量 / 默认回程 outputch / 记忆策略(ChannelDef)

- 新增 `ChannelRegistry`，设计成**可共享对象**（`*ChannelRegistry`）：
  根 agent 与驻留子共用同一份，"划入/授权"才有意义；`SetChannelRegistry` 注入。
- **插件重载不得抹掉划分**：重复登记只更新「归属插件 + 策略」，
  保留已有 Owner/Capacity/Output（否则一次 reload 就把父做的划分清空）。
- `Assign` 语义按设计 R6 默认：**读写授权，不转移所有权**（Plugin 与 Owner 分别记录）。
- 原 `inputChannels map[string]ChannelDef` 被登记表取代；`GetInputChannelDef` 保持兼容。
- `plugin.Registry` 注册时带上**归属插件名**（此前完全无归属信息）。

## 总览工具（internal/agent/core/inputch.go）

单工具 **`input_channels`** + `view` 参数（不是一堆小工具）：

    all（默认）= 全部已注册（带归属插件）
    mine       = 划给本 agent 的
    unassigned = 尚未划出的
    by_agent   = 划分情况总览（按归属分组）
    detail     = 单个 inputch 全字段（需 name）

未知 view **报错并列出可用值**（拼错不得被静默当成默认视图）；登记表为空时明确说明。

## 验收

- `internal/agent/io/inputch_test.go`：归属记录、重载保划分、Assign/视图数据面、
  **跨 manager 共享登记表**、策略查询向后兼容 —— 5 项
- `internal/agent/core/inputch_test.go`：单工具多视图逐视图断言（含未知 view 与空表）—— 2 项
- 全仓 `go test ./...` 37 包 ok / 0 FAIL；`-race ./internal/agent/... ./internal/plugin/...` 干净
 2026-09-13 09:06:50 +08:00
JianFeeeee
cb32032f76 feat(scheduler)!: 中断/排队两类别模型 + 插件声明 L1-L3、L4 内核独占 
用户澄清推翻了早期设计的三处前提，本提交按新模型重做调度核心（行为有意变化）：

1) 类别由注入 API 决定，与通道名无关
   - InjectInterrupt*                      -> TaskInterrupt（带级别，可被严格更高级中断打断）
   - InjectText*/InjectInputSync*/内核自循环 -> TaskQueued（无级别，可被任何中断打断）
   - 删除按通道名推断的 taskLevel()：qq 走 InjectInterruptTextOpts，本就是中断

2) 级别只属于中断
   - 插件在 InjectOptions.Priority 声明 L1-L3（空/非法降级 L1，声明 L4 夹到 L3）
   - L4 内核独占：新增 raiseKernelInterrupt（panic / selfip）；requestKernelPreempt 不夹取
   - panic 现在产生一条带 kernel 标记的 L4 中断；L4 自身 panic 不再产生新 L4（防自我放大）

3) 选择结构：四容器固定次序，删除统一比较器
   - immediate（抢占者立即运行）-> 中断队列 L4..L1 -> 栈顶(与队头比级别) -> 排队 FIFO
   - 删除 pickTaskIndex/taskBefore 与“同级 pending 优先”补丁（根因是抢占者进了队列）
   - 中断栈上界改为结构推论 = 4（= 中断级数）；删除“超限转 pendingInterrupts”降级

公开 SDK（feature 分支有意新增，纯追加）：InjectOptions.Priority + PriorityL1/2/3；
内核 io / proc 桥 / 插件模板同步透传。

设计稿 §2/§3/§4.1/§6.3/§9/§11/§12/§13/§15 按新模型重写。

验收：go build/vet 干净；go test ./... 37 包 ok 0 FAIL；-race 全绿；
e2e（抢占-挂起-恢复）+ 压力（200 排队 + 50 中断，L1/L2/L3 轮转）通过。
 2026-09-13 07:00:51 +08:00
JianFeeeee
d1959cbe80 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
b777322b95 feat(multimodal): 内置多模态感知插件 + process.go 原生支持 tool message 多模态块 
【新插件 internal/plugins/multimodal】
- see_picture(path): 读取本地图片/URL，base64 注入 image_url block，
  模型在下一轮 LLM 请求的 tool message 里直接看到图（1024×1024 图约 8500 token）。
  自动识别 MIME，限 3MB 防爆 context。
- see_video(path, frames): ffmpeg 提取关键帧，多帧作为 image_url block 注入。
  默认 4 帧，最大 10 帧，每帧限 2MB。
- listen(path): 读取音频文件，转为 audio_url block 注入，支持 mp3/wav/ogg/m4a。
  限 5MB。

【内核多模态 tool message 支持】
- agent/api 新增 ToolOutput 类型（为后续 handler 直接返回 blocks 预留）
- SDK 公共层新增 ContentBlock/ImageURL/AudioURL（OpenAI 多模态格式）
- IOManager 新增 SetToolBlocks/ConsumeToolBlocks（interface{} 避免循环依赖）
- PluginSDK.SetToolBlocks(blocks) 插件工具调用后注入 blocks
- ioAdapter 桥接 IOInjector.SetToolBlocks
- process.go 工具执行后消费 pending blocks → 追加到 tool message 的 Blocks 字段
  → MarshalJSON 输出 content 数组格式 → LLM 看到图/音频

【验证】
multimodal_see_picture 注入 1024×1024 PNG 后 llmsproxy 统计：
  prompt_tokens=44407（含 ~8500 image token），模型正确描述了图片内容。
 2026-08-27 08:39:21 +08:00
root
a899d777c3 sdk: embed non-toolchain SDK in third_party, add NoMemory/Cleaner support 
- Embed sdk/, example/, meta/, go.mod from homeagent-sdk (no .git)
- Core .gitignore excludes SDK toolchain: bin/, tools/, package/
- RegisterInputChannel + ChannelDef(NoMemory, Cleaner) in SDK
- IOManager input channel registry with GetInputChannelDef
- eventloop: apply channel Cleaner/NoMemory to interrupt text
- context engine: channelDefLookup applied in textForVector
- document store: ChannelCleaner param for archive functions
- All callers/adapters updated with ChannelDef{} default
 2026-07-29 14:48:23 +08:00
root
7f28b997e6 feat: output channel redesign - per-channel output gates, LLM chain events, SDKConfig 
- Output channels generate per-channel tools: output_send__{name} (type=output) + output_send__{name}_help
- content is JSON string transparently passed to plugin handler for routing
- EventAgentLLMChain: full LLM response forwarded after each turn for webui/logs
- sdk.New refactored to SDKConfig struct (no more 13 positional args)
- RegisterOutputChannel adds desc param for JSON format documentation
- channelDevice simplified (no Tools method), desc field added
- Child agent permission updated for output_send__ prefix
- System prompt: output gates, multi-call, long messages split
- WebUI: subscribes to EventAgentLLMChain in SSE, no output channel
- Tests updated for new naming convention
 2026-07-16 12:11:16 +08:00
root
fab58e709a feat: complete P0/P1/P2 — WebUI SPA, OpenClaw sidecar+simulator, healthcheck auto-sched+perf 
P0: WebUI重构
- 完整 SPA 仪表盘 (7标签页), //go:embed dashboard.html
P1: OpenClaw兼容 (三通道: SKILL.md / sidecar / simulator)
- Node.js 模拟进程统一加载任意 OpenClaw 插件
- JSON-RPC 2.0 over stdio 协议, go:embed 内嵌
P2: Healthcheck 优化
- 定时自动执行 (startAutoCheck, 30min)
- healthcheck_perf 性能监控工具

其他: agentcli/cmd 插件, integration_test, status.go,
      test_deepseek 清理, 多项 bug 修复
 2026-07-04 12:51:32 +08:00
root
239a22899b fix: 模型思考模式配置 + Unicode 截断 + 审计修复 (13 files) 
模型模式:
- 新增 LLMConfig/Source.ThinkingEnabled 配置，通过 ExtraBody
  控制 DeepSeek thinking mode，默认关闭
- SeedDefaults/ToConfig 读写 core.llm.thinking_enabled
- deepseek.lua 移除硬编码 temperature=0

Unicode 截断:
- truncateStr 改按 rune 计数，修复中文截断乱码

审计修复 (Critical):
- graph.go: defer rows.Close 在 for 循环 → 显式 Close (连接池泄漏)
- cli/openclaw/plugin.go: bare type assertion → comma-ok (panic)
- channel.go: payload["type"].(string) → comma-ok (panic)
- webui/handler.go: .(string) → fmt.Sprint (panic)
- agent.go: 添加 nil provider 错误返回

审计修复 (High):
- events/bus.go: copy handler slice under RLock (data race)
- webui/handler.go: SSE 通过 channel 串行化写入 (data race)
- timer/plugin.go: time.Sleep → select with stopCh (Stop 阻塞)
- provider.go: stream ch <- 添加 select ctx.Done (goroutine 泄漏)
- main.go: outputCh goroutine 添加 ctx.Done 退出路径
 2026-07-03 20:46:04 +08:00
root
2d314b3e9c 重构: 插件自注册 + .so 动态加载 + 中断打断机制 
- 所有内置插件 init() 自注册 (plugin.RegisterFactory), 移除 main.go 硬编码
- 新增 .so 动态加载器 (internal/plugin/dynamic.go), 插件可编译为 plugin.so
- 新增 plugin.json 元数据 (internal/plugin/manifest.go)
- 新增 interceptLoop 独立 goroutine:
  (a) cancelLLM() 取消进行中的 HTTP 请求
  (b) interceptCh → drainInterrupt() 注入 [打断消息] 到 LLM 上下文
  (c) InjectInput 空闲时触发新处理循环
- 新增 internal/plugins/all.go 空白导入触发所有内置插件 init()
- internal/sdk/ 作为 PluginSDK 正式 Go API
- internal/api/ → internal/plugins/webui/ 迁移
- 删除旧 cmd/cli/, 使用 cmd/waiter/ 替代
- 更新 PLAN.md / ARCHITECTURE.md / README.md 文档
 2026-07-03 16:53:34 +08:00
root
304c3ae294 refactor: remove IO route mapping, add HTTP API tests, system prompt update 2026-07-02 15:47:16 +08:00
root
bc26850b50 feat: complete HomeAgent architecture v2 
- IO abstraction layer with OutputChannel routing and capability validation
- Three-layer memory (Context-Document-Graph) with TF-IDF relevance pruning
- OneBot V11 QQ protocol plugin with Reverse WebSocket client
- Plugin system with hot-reload (SKILL.md + native factories)
- Knowledge system with TF-IDF vector indexing
- Personality system (personal.md)
- Text memory (JSONL with rotation)
- Change tracker (overlayfs) with rollback
- Lua adapter VM
- Design document (DESIGN.md)

Module: gitcode.com/JianFeeeee/HomeAgent
 2026-07-02 12:04:36 +08:00