jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-09-27 21:03:16 +00:00
Code Issues Packages Projects Releases Wiki Activity
686 Commits 5 Branches 27 Tags
8a98969fac2d59aa51bf62a4a596da4ce2d2baa2
Commit Graph

68 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
396d13e9af feat(toolcall): 结果契约诚实化 —— Success 不再恒真 + 结构化失败可回填（阶段 1b/1d） 
问题（实测，三条互相印证）：
· ToolResult.Success 硬编码 true（task.go 唯一赋值点）⇒ 该字段在结构上
  不可能为 false，是**谎报字段**；
· 工具失败以 nil error + 错误**值**返回（files 的 errorResult、
  pluginmgr 的 {"error":…}），上游无从判别；
· stepToolAfter 用 `Result.(string)` 断言，而插件返回的多是 map ⇒
  断言几乎恒失败，after_toolcall 阶段对结构化结果的改写**静默失效**。

改动：
· third_party/homeagent-sdk: 新增 ToolError{Field,Reason,Detail,Hint}
  与 Error()。纯新增、无签名变更，存量插件不必改动（零值语义：
  内核的失败识别同时兼容既有三种约定，新类型是可选项而非迁移要求）。
· internal/sdk: 补 ToolError 别名。
· core/toolerror.go: isToolError / toolErrorText / renderToolResult。
  ⚠️ 判据必须同时兼容仓内**三种**既有失败约定，且**不得**把成功误判：
   ① {"error": msg}  ② {"isError":true,content:…}  ③ *ToolError
  明确不判失败的：exit_code != 0（业务结果，带真实 stdout/stderr）、
  stderr 非空（cmd 成功常带 warn）、字符串/数字/bool/数组/nil
  （自由文本按成功处理：宁可少报失败，也不把正常结果报成失败）。
· core/toolcall.go: executeToolCallOutcome 返回 toolOutcome{Text,Raw}，
  **Raw 必须在成功分支也带上**——否则结构化失败在 fmt.Sprintf("%v")
  那一步被抹平，Success 又退回恒真。panic 与 60s 超时统一以 ToolError
  表达（可执行 Hint，避免模型原样重试工具故障）。
· core/task.go: Success=!isToolError(Raw)；修恒失败的类型断言；
  TaskFrame 增 CurRaw（未降级的原值）。

判据：
· toolerror_test.go 单元级：三种失败约定识别 / 成功形态不误判 /
  非零退出不算工具失败 / ToolError 识别。
· TestStageCtxSuccessIsHonestEndToEnd 端到端读 f.StageCtx.ToolResults，
  验证**内核产出的值本身**，而非辅助函数。

变异验证（两轮）：
· Success 退回硬编码 true ⇒ 端到端判据 3 个子用例 FAIL；
· 把字符串判据改成 strings.Contains(x,"error") ⇒ 「成功文本含 error 字样」
  用例 FAIL。**第二轮暴露了判据缺口**（最初没有该用例），已补。

过程中三次自伤（均由判据/编译暴露）：用正则批量包装 return 时把
多行 fmt.Sprintf 截断；包装范围溢出到返回 string 的辅助函数；
测试里重复注册同名工具导致 IOManager 取到错误的 device。

遗留：全量 go test ./internal/... 在本机无法完整跑完——/tmp 是 9.8G
tmpfs 且已 98% 占用，link 阶段报 "no space left on device"；
/var/tmp 另有约 29G 陈旧 release worktree。与本次改动无关（未触碰
memory/* 等失败包），已在干净基线（7a566d5）对比确认。
 2026-09-27 09:17:16 +08:00
JianFeeeee
758ec11832 fix(memory): 图整备覆盖 scenes + 证据桶按桶清（R3/R5） 
R3：图整理心跳只查 entities/relations，scenes 完全没有整备路径。
Recall(nil,nil,1,"") 的全量路径只 SELECT 这两张表
（graph.go:609/631），于是同一场面的双胞胎键从建库起无人发现：
auto:chan:qq+part:morning 累积到 strength=271 / 6 features / 0 refs，
孪生的 auto:chan:qq_part:morning 持有 210 refs 却 0 features
（聚类只读 scene_features，所以它永远不被看见）。

新增 GraphDB.DedupeScenes：归一化后同名的场景合成一个——强度相加、
特征取并集（权重取大）、引用全部重定向，存活者保留 id 最小行，
跨 origin 也合。接到 mergeLoop 尾部。

为什么不塞进 detectEntityMerge 的双重循环：
- 实体是全库两两 bigram + LLM 裁决（1 万实体实测 5000 万次配对、
  ~224GB 瞬时分配每轮，是独立问题）；
- 场景的判重口径是**归一化后是否同名**——同名即同一场面，键相同
  本身就是证据，不需要 LLM 裁决。而「像不像」是 EnterScene 聚类的
  职责，不是这里的事。
只做同键合并、不做相似度合并：把 chan:qq 与 chan:webui 合并是危险
的，去重不是「把像的一律合并」。

生产库副本实测（sqlite3 备份式复制到 /tmp，未碰生产）：
65 个场景 → 合并 8 组 → 57 个；
auto:chan:qq_part:morning 的 refs/rel/ent 一条没丢，strength 1 → 272。

R5：createSceneLocked 新场景成立时执行的是
`DELETE FROM situation_evidence`（全表清），而证据表是多通道共用的
计数桶。后果不是「多清一点」：qq 的场景一长出来，就把 mc/webui/cli
尚未攒够 minSceneEvidence=2 的证据抹掉，它们的计数被反复清零，
于是**永远**攒不到 2 次。判据实测：6 个通道各来 3 次，只长出 2 个场景。
改为 `DELETE ... WHERE label = ?`，只清本指纹那个桶。

判据：scene_dedupe_test.go 8 例（含「不同场面不得被合并」与幂等）、
scene_evidence_test.go 3 例。均先红后绿。修 R5 时差点栽：桶键是
sig.Label(2) 本身、不带 auto: 前缀（base 才是带前缀的场景键），
第一版删错对象会「一条没删却看起来通过」，用探针实测真实桶键后改正。

记忆 8 包 + agent/core 全绿，8 包齐全、无 FAIL/panic/race。
 2026-09-26 20:16:11 +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
bd1d5fff2b chore(vendor): 主仓不再跟踪 SDK 示例代码（决策 A） 
## 背景

`.gitignore` 第 26-45 行早已写明「外部插件与工具链维护在独立 SDK 仓
（决策 sdk_repo_only），本仓经 go.mod 的 replace 引用」，并忽略了
example/、tools/、docs/、site_build/、package/、scripts/。

但有 29 个文件**早于该规则**被跟踪，靠「已跟踪文件不受 .gitignore
影响」留着，注释还特意写了「这是有意的，不要『修』」。

本轮修 example/bili 时踩到了：那 87 行改动先落在主仓、再手动同步到
SDK 仓 —— 同一份代码两个仓各改一遍，正是这个遗留结构的成本。

## 核实：主仓到底需要什么

- 主仓 Go 代码只 import 两个包：`homeagent-sdk/sdk`（插件入口）、
  `homeagent-sdk/meta`（版本号）
- `remotedevice/` 是 C 库，主仓 C 侧明确「不链接任何外部库」，
  只有注释里提到它
- `tools/hmapdev/yaegi` 的 import 出现在 **SDK 仓自己的文件之间**
  （yaegi/interp.go → yaegi/mocksdk），不是主仓依赖；
  且 tools/ 本就在 .gitignore 里，从未被跟踪

所以 29 个文件全部可以删。实际仓库负担也只有 42 个文件 / 0.6MB
（工作树里那 971MB 绝大部分是未跟踪的构建产物，不是仓库体积）。

## 改动

- 删 21 个 example/ 文件（10 个示例的 plg.json + plugin.go + qq/plugin_test.go）
- 删 8 个 remotedevice/ C 文件
- 工作树里一并清掉（不受跟踪的构建产物顺带回收）

构建与全量测试均通过。

## 判据：3 条 + 变异（internal/meta/vendored_sdk_test.go）

- TestVendoredSDKHasNoExampleOrRemotedevice：防止示例代码被重新提交进来
- TestVendoredSDKKeepsRequiredPackages：**反向**保护，防止为省事把
  sdk/ 与 meta/ 也删掉（上一条只防"多了"，删过头要靠这条）
- TestGoModStillReplacesSDKToVendoredPath：决策 A 依赖 replace 指向 vendored 路径

★ 判据自己踩了两个坑，都靠实跑抓出来：
1. `git ls-files` 的路径参数**相对当前目录**解析，而测试跑在
   internal/meta/ 下 ⇒ 就地执行返回空，表现为「必需包全都不在」的假红。
   改用 `git -C <仓库根>`。
2. 把 tools/hmapdev/yaegi 当成主仓依赖写进必需清单 ⇒ 又一次假红。
   根因是把 SDK 内部的引用误当成主仓依赖（它本就在 .gitignore 里）。

变异验证：塞一个 example 文件进版本控制 → 判红。
 2026-09-26 17:18:41 +08:00
JianFeeeee
ceeef0b4e1 fix(proc): 杀插件进程组 + readerWG 超时兜底 —— 修孙进程拖死关停 
## 现象

线上关停必超时：systemd 报 `State 'stop-sigterm' timed out. Killing.`，
进程组里 23 个插件全退完了，最后那条 `[homed] stopped` 仍打不出来。
其中只有 bili 报 `[proc] bili SIGKILL 后 2s 仍未被收割`，之后近 90 秒无日志。

## 根因

bili 用 exec.Command 拉 yt-dlp（源码 example/bili/plugin.go:122/212），
无 CommandContext、无 Setpgid、Stop() 是空的。yt-dlp 再 fork ffmpeg，
**孙进程继承插件的 stdout 管道写端**。

  插件被 SIGKILL → 孙进程仍存活、写端不关
  → readLoop 的 scanner.Scan() 永不 EOF
  → p.readerWG.Wait() 永不返回（Kill 的最后一行，**无超时**）
  → StopAll 的 wg.Wait() 永不返回 ⇒ 关停挂死 ⇒ systemd SIGKILL

内核 process.go:340 的注释早已预警过这个场景（"插件 fork 的孙子进程继承
同一 stdout 写端时，插件本体死了 EOF 也不会到"），但 Kill 没有对应保护。

## 内核三处修法（缺任一条都不够）

1. **spawn 时 Setpgid**：插件自成进程组，不再与内核同组
2. **Kill 杀整个进程组**（kill(-pgid)）：孙进程一起死，管道写端才关。
   兜底：负 pid 失败时退回杀本体（老插件/非 Unix 平台）
3. **readerWG.Wait() 加超时兜底**：这是唯一能保证 Kill 一定返回的地方。
   超时后主动关读端逼 readLoop 退出，再兜一层仍不退就放弃等待 ——
   宁可少等 2 秒，也不能把关停无限期挂住。

## 插件侧（bili）

CommandContext + Setpgid + Stop() 里 cancel 并 wait：
- 只 cancel 不 wait 的话内核会先释放共享段，而 yt-dlp 还在写 stdout
- waitRunGroup 杀整个进程组（ffmpeg 也在内），不留孤儿

## 判据：5 条 + 3 组变异

判据用**真实模板编译的插件**（复用 buildPluginWithRealTemplate，
与 e2e_template_test 同一条路）+ NewHost 启动，不是自造 shim：
裸 Spawn 没有 Host 建共享内存段，插件握手会报 permission denied。

★ 判据自己踩了三次坑，都由变异/合跑抓出来：
1. 给孙进程也加 Setpgid ⇒ 它逃出插件进程组，kill(-pgid) 杀不到，
   造出假失败（真实场景 yt-dlp 不会脱离进程组）
2. 各测试数全局孙进程数 ⇒ 前一个泄漏的被后一个数进去，
   单跑通过、合跑变红。改为记录基线只关心自己新增的
3. readerWG 超时那条用纯构造 &Process{cmd:nil} ⇒ Kill 第 607 行
   早退，根本走不到那段，撤掉超时照样绿。补了「脱组孙进程」
   场景（Setsid 逃出进程组）才真正覆盖到

变异：去 Setpgid → 判红；只杀本体不杀组 → 判红。

全量 41 包绿。
 2026-09-26 16:58:41 +08:00
JianFeeeee
dfc05780fd feat(kbtree): 知识库暴露范围配置 —— 按树状只暴露指定分类 
## 问题

kbtree 是**唯一**把知识库开放给外部进程的通道（HomeAgent 自己的 agent
走进程内直调 knowledge_* 内核工具，不经此），但它只有 listen_addr 与
token 两个配置，**没有任何范围限制**：拿到 token 的任何 agent 都能
/tree 列出全部条目、/search 取回任意条目全文。

本机库里混着个人内容（航空发动机教材摘录、课表、身份合并规则），
不该 broadly 可读。

## 改动

1. `internal/plugins/kbtree/scope.go`（新）：暴露范围语义
   - 留空 = 全部可见（范围是"限制"不是"必填"，留空保持既有行为）
   - 前缀按**路径分段**匹配：public 命中 public 与 public/tech，
     但**不**命中 publication（否则 publication 意外暴露）
   - 根下无分类的条目在范围非空时不可见 —— 它没有分类可匹配，
     放行等于范围形同虚设
   - 分隔符容忍逗号/分号/空白/换行/竖线：这是给人手填的字段

2. `plugin.go`：注册 `expose_categories` 配置项，接入**全部四个端点**
   - /tree      服务端裁剪子树（就地改，不重建：TreeView 字段多）
   - /categories 过滤路径列表
   - /counts    过滤计数并**重算 total**（数量本身也是信息泄露）
   - /search    ★ 过滤结果条目；这处最关键：
     只过滤 /tree 而放过 /search 等于范围形同虚设（换个 ?q= 就能拿到全文）。
     同时修正 limit 语义 —— 范围外条目不占名额，范围内条目不会被挤掉。

3. SDK 契约补 `Knowledge.Category`（纯增量）
   - 此前 `sdk.Knowledge` 只有 Name/Content，内核明明返回了 Category
     却在 knowledge_impl 的拷贝里丢掉 ⇒ 外部服务无法按分类判定，
     范围过滤在 SDK 层根本做不了。
   - Name/Content 均保留，无删除。

## 判据（8 条 + 4 组变异）

范围过滤最容易"只做一半"，所以每个端点都单独钉。

★ 判据补强一处：初版只查条目名（priv1），结果「/categories 不过滤」
  这个变异**完全逃过** —— 分类端点返回的是路径不是条目名。
  补上分类路径断言（private）后判红。

变异验证：
- /search 不过滤      → 泄露 priv1 全文        ✓ 判红
- /categories 不过滤  → 泄露 private 分类路径   ✓ 判红（补强后）
- /counts 不过滤      → TestCategoriesAndCountsEndpoint 判红
- 前缀退化为字符串前缀 → publication 被误暴露      ✓ 判红

★ 过程中我的 fake 有两处与真实内核不符，先修 fake 再修实现：
  1. 漏了内核 treeLocked 的"子分类提升一层" ⇒ 得到 children=0 的假空树
  2. filterTree 无差别清空 t.Items ⇒ 整棵树只剩空壳节点
  （第一版的实现是"看着测试红就改"，实际是 fake 在骗我）

全量 41 包绿。SDK 接口纯增量，未发布故无需冻结检查。
 2026-09-26 15:31:15 +08:00
JianFeeeee
6c33bfdb82 docs(sdk): 修正 ProxyReg 字段注释里的旧名（DeclareProxy→RegisterProxy） 
Rename 时漏改了字段注释。代码本身一致（proxyReg 字段 + RegisterProxy 方法），
但注释里写着一个不存在的 API 名，读者按注释找不到方法。
 2026-09-26 13:49:59 +08:00
JianFeeeee
2c810bbbce feat(webui): 路径挂载的 strip_path 两态 + 尾斜杠重定向（修 /p/huawei 打不开数据） 
用户要求用方案 A（路径挂载）让 huawei 插件 UI 在外部可用，
并把「通过反代的插件必须使用单一入口」写入 SDK 声明。

## 实测暴露的两个真问题

1. **Path 的语义不能一刀切**。原设计「原样保留」只对**机器接口**成立
   （设备客户端硬编码 /api/v1/device/ws，不可能知道反代的存在）；
   而自带 UI 的服务需要**剥掉前缀**（/p/huawei/api/status → 上游 /api/status）。
   猜错的结果是全部请求 404，且看起来像上游故障 —— 所以由声明者选：
   strip_path=false 别名模式 / true 前缀模式。非法组合被 validate 挡住。

2. **前缀模式的尾斜杠是必需的**（自测发现的 bug）。
   访问 /p/huawei（无尾斜杠）时页面能开，但页面里所有 fetch 都 404 ——
   相对路径以「当前文档目录」为基准，没尾斜杠时浏览器把最后一段当文件名，
   目录退回上一级，fetch('api/status') 打到 /p/api/status。
   修：前缀模式且路径恰等于前缀时 301 到 /p/huawei/（保留查询串）。
   **别名模式不做此事** —— 那类路径是上游真实语义，加斜杠会改坏它。

## 插件侧（huawei_smarthome）

- 前端 4 处根绝对路径（fetch('/api/status') 等）改为相对路径，
  基准由 location.pathname 推导（BASE）。这是 Path 形态能成立的**前提** ——
  否则请求会打到门户自己身上。
- plg.json 声明：host + path=/p/huawei + strip_path=true + auth=homeagent。
- SDK 升到 1.4.0，并用 hmapdev 1.4.0 重新打包（1.3.0 的 hmapdev 无
  proxies 支持，会把声明**静默丢弃** —— 实测确认过，这是打包链路上
  一个不报警的坑，值得记住）。

## 判据

+6 条：TestProxyPathAliasVsStrip（两态各自正确）、
TestProxyPathLongestPrefixWins（/p/app 不得劫持 /p/apple，
且长前缀胜出）、TestProxyStripPathRedirectsToTrailingSlash（尾斜杠，
含查询串保留 + 别名模式不得重定向）。

变异验证（4 条，均按预期打红后还原回绿）：
- 删尾斜杠重定向 → 判红（还原了真实 bug 形态）
- 让别名模式也重定向 → 判红（设备网关语义被毁）
- 从 hmapdev schema 探测体删 StripPath → 判红（漂移检测有效）
- 删 SDK 里的「单一入口原则」字样 → 判红（契约不能只剩口头约定）

全量：35 包全绿。
 2026-09-26 13:49:59 +08:00
JianFeeeee
7f5bf1670f feat(clients): 设备桥自动链接改用服务端发现 + 路径挂载（无 DNS 依赖） 
配套 webui 反代改造：网关现在可由 HomeAgent 反代出去，客户端不能再靠
「门户地址同 host 拼 /api/v1/device/ws」猜地址——基域名与子域标签都是
**服务端配置**，客户端无从得知。

## 服务端：/api/v1/device/gateway 发现端点

客户端问「网关在哪」是唯一不会漂移的做法：子域标签可改（插件声明）、
基域名可改（webui.base_domain）、实例可换形态，客户端都不用跟着改。

⚠️ **不返回设备令牌**：本端点用门户凭证鉴权，而设备令牌能执行设备命令；
把令牌塞进来等于「门户只读凭证 → 设备执行权」的越权。令牌仍由客户端
自配。已有判据钉住「不得泄漏凭证字段」。

## ★ 实测发现：*.localhost 只有浏览器能解析

这是本轮最重要的发现，直接决定了设计：

| 环境 | devices.localhost 解析 |
|---|---|
| 浏览器 | ✓（RFC 6761 内置） |
| curl | ✓（内置特例） |
| getent / Go / Node | ✗（系统 nsswitch 是 files,dns，无 nss-myhostname） |

设备客户端（waiter / GUI 主进程 / 嵌入式固件）用的正是系统解析器。
实测 waiter 报「lookup devices.localhost on 192.168.2.1:53」。

因此**两处**设计变更：
1. 发现端点同时返回两种形态，并标 preferred：
   - url（子域）—— 浏览器用
   - url_portal（门户同源，同一 host、同一端口，走路径挂载）—— 非浏览器用，
     无任何 DNS 依赖
2. SDK 的 ProxyDecl 新增 **Path**（路径挂载前缀）：让同一服务同时挂到
   门户自身 host 的路径下。remotedevice 声明 Path="/api/v1/device"，
   设备客户端因此能沿用**它已硬编码的路径**，不需要知道反代存在。

路径挂载语义：请求路径**原样保留**（不剥前缀），上游按真实路径注册即可。
边界卡在路径分隔符上（/api/v1/device 不匹配 /api/v1/devicefoo）。

## 客户端

- **waiter**：新增 discoverGateway()，仅在用户配了门户地址时尝试，失败回退
  自配地址（老版本 HomeAgent 无该端点）。抽出 normalizeGateway() 纯函数，
  显式钉住「已带子域/完整端点的地址不得被改写」。
- **GUI**：renderer 新增 loadDiscoveredGateway()，renderDeviceChannel 优先用
  发现值、回退旧口径。顺带修掉此前插入函数时 anchor 不匹配导致调用点
  找不到定义的问题。
- **鸿蒙**：discoverGateway() + resolveGatewayUrl()，优先 url_portal。
- 三者都**优先 url_portal**（system resolver 的现实约束）。

## 遗留路由鉴权修正

`/api/v1/device/` 的旧路径反代原被 requireAPI 包裹 —— 但其调用方是设备
（带设备令牌而非门户凭证），套上门户鉴权会把它们全挡在 401（**真实实测**：
waiter 经此路径升级握手 401）。去掉这层包装，鉴权交给上游 remotedevice
自己的 requireToken，安全性不降级。

## 判据

webui +6 条、waiter +7 条。

★ 其中一条是**真实回归**：/api/v1/device/gateway 曾被 Path="/api/v1/device"
的路径挂载接走（那服务 auth=none），于是发现请求被转给上游、回 401，
客户端再也发现不到网关。修法是发现端点先于路径挂载判定，并补判据
（走完整生产链，同时确认同前缀的真实设备路径仍归反代）。

## 真实验收（隔离实例，命名 netns + 独立 data + 18080）

真 waiter 客户端 + 真 remotedevice 网关：
  device gateway discovered: ws://127.0.0.1:18080/api/v1/device/ws
  device bridge active: waiter-mainserver authorized=true
  hello_ack / bind_ack 均经反代往返成功

说明：`bind_ack device=<nil>` 与在线列表为空的现象，**直连 9890 绕开反代
完全一致复现**，属 remotedevice 与 waiter 之间既有的握手细节，与本次
反代改造无关（反代侧职责已证：连接建立 + 双向帧往返都通）。
 2026-09-26 13:49:59 +08:00
JianFeeeee
1e58af79d3 feat(webui): 通用反向代理 —— 插件声明服务，HomeAgent 按子域反代出去 
用户要求：外部只装 HomeAgent 即可使用自带反代能力；用户只需穿透一个
webui 端口就能访问所有内部插件服务；认证与 WebSocket 支持都作为插件
的可声明项；插件 UI 要有可直接点击的入口。

实测 huawei_smarthome 插件的前端用**根绝对路径**（api('/api/status') →
fetch('/api/status')）。挂在 /p/<name>/ 这类路径前缀下，这些请求会打到
HomeAgent 自己的 /api/status —— 静默错路由；做 HTML/JS 内容重写对拼进
JS 字符串的绝对路径只是"按概率能用"，会产生"页面能开、某个按钮就坏"的
静默故障。子域路由下根路径天然正确，**插件前端零改动**。

且它天然匹配"只穿透一个端口"：webui 监听 0.0.0.0:8080 按 Host 分发，
外层 frp 单端口 TCP 隧道**一行都不用改**。

默认基座 localhost：RFC 6761 规定 *.localhost 强制解析到 loopback，
现代浏览器原生支持 ⇒ <标签>.localhost:8080 **零配置可用**，不需要 DNS、
证书、/etc/hosts。远程部署改 base_domain 即可。

- 外部插件 → plugin.json 的 proxies（静态可发现：插件没起来也能报
  "声明了 ui 但目标不可达"，而不是静默 404）
- 内置插件 → s.DeclareProxy()（remotedevice 是内置的、没有 plugin.json，
  却最需要被反代出去）

反代层在 webui 侧读清单：webui 已能拿到插件目录（PluginManager.PluginDir），
因此**无需给内核接口加方法**。manifest 解析忽略未知字段，加 proxies 对
"旧内核读新插件"与"新内核读旧插件"都无害。

新增 sdk/ProxyDecl 与配套校验（ValidProxyAuth / ValidProxyHostLabel /
NormalizeProxyHost / ValidateProxyDecl）；新增运行期 ProxyDeclarer 通道。
hmapdev 的 writePluginJSON 是**白名单 map 重建**——不同步加字段会让声明
被打包静默丢弃（插件作者本地正常、装上去失效），因此 PlgConfig 与
writePluginJSON 同时加，并在打包前校验声明（插件作者本地就能发现写错）。

auth=homeagent（默认，安全的默认）：门户会话 / X-API-Key / ?__token=；
auth=none：信任上游自身鉴权，供设备与嵌入式客户端使用——它们不可能持有
浏览器会话，强制走门户鉴权会把设备链路挡死。remotedevice 声明 none，
因为它自身用 ws_token 强制校验。

未声明时升级请求**明确拒绝**（400 + 原因），而不是静默降级成普通请求
（后者表现为前端不断重连、日志看不出原因）。

1. 不跟随上游 3xx：旧实现用 http.DefaultClient（默认跟最多 10 跳），
   上游 302 到内网地址时反代自己跟过去、失败回 502 并把内网 URL 泄给
   客户端。httputil.ReverseProxy 默认不跟随，3xx 原样透传。
2. 逐帧 flush：旧实现 io.Copy 导致上游流式响应被缓冲到上游关闭才下发
   （实测 3 帧 200ms 间隔的流，客户端在 +600ms 一次性收到全部）。
   设 FlushInterval=-1。

另补齐 X-Forwarded-For/Host/Proto（旧实现完全不注入，上游无法判断真实
来源），并剥掉上游 Set-Cookie 的 Domain（防止插件 cookie 打到主门户域）。

插件页新增「服务入口」卡片：列出全部被反代的插件服务（含被拒条目与
不可达原因），点「打开」直接访问。链接带 ?__token=<api_key>，因为子域
与门户不同源、浏览器不会自动带会话 cookie。

webui +35 条、SDK +4 条、工具链 +4 条。关键几条：
- 根绝对路径必须原样到上游（选 Host 路由的核心理由）
- 上游 302 必须原样透传、且反代不得跟随（旧缺陷）
- 已知 Content-Length 的慢速响应必须逐帧到达（**这条经过变异验证**：
  把 FlushInterval 改回 0 后判据挂死 → FAIL，还原后回绿。
  说明：最初写的 SSE/chunked 版本是假判据——ReverseProxy 对
  text/event-stream 与 ContentLength=-1 会自动立即 flush，与
  FlushInterval 无关，变异抓不到，已改正）
- 子域标签冲突不得静默覆盖（后者保留可见并带原因）
- 非法声明不进路由但必须可见（配置页要能看到原因）
- 未声明 websocket 的升级请求必须 400
- auth 逐条生效：none 放行匿名、homeagent 与默认档 401 且给可操作提示
- 自动发现：显式 host 不得被自动编号覆盖（**测试抓到的真 bug**：
  remotedevice 声明的 "devices" 会被改成 "devices-2" 而静默失效）
- 真实端到端：生产实例 huawei_smarthome 的 UI（9444 字节）与其
  /api/status 经反代正确透传

go build ./... 通过；相关包全量测试通过。
internal/plugin/proc 的 TestStreaming_PublishLatencyFlatAcrossSubscribers
是**预存在的不稳定测试**（同一份代码 10 次跑 9 过 1 败，且本改动完全
未触及该包），非本次引入。
 2026-09-26 13:49:59 +08:00
JianFeeeee
4f3de61d8f license: 明确内核 AGPL / SDK MIT 的边界（插件不受 AGPL 传染） 
SDK 仓改为 MIT（同批提交 e97cafc）后，核心仓几处「插件静态链接 SDK 故须同许可」
的论述不再成立，一并更正。

## 边界（现在写清楚了）

- **AGPL-3.0-only 覆盖内核与随包内置插件**：homed、internal/、internal/plugins/
  下 18 个内置插件。§13 网络条款照旧适用。
- **MIT 覆盖公开 SDK**：sdk/ 零外部依赖、只依赖 Go 标准库，不引用内核任何代码。
- 因此**外部插件不是本项目的衍生作品**，作者可自行选择许可（含闭源、商业、
  私有），既不必同许可、也不受 §13 约束。

## 改动

- README.md / README_EN.md「许可」章节：改写静态链接那段，写明上述边界与理由
  （决定许可的是被链接的 SDK 代码，而它是 MIT；子进程隔离不再是关键论点）
- README.md / README_EN.md changelog：**按本仓惯例保留历史原文**，在既有更正
  注记区追加一条「许可口径已变更（2026-09-24）」，而不是去改写 v1.2.0 的原文
  —— 避免伪造当时的语境
- site/index.html footer：状态栏拆成「内核许可：AGPL-3.0-only」+「插件 SDK：MIT」
  两行；声明区分「AGPL（内核与其内置插件）」与「SDK 以 MIT 发布，插件不受传染」
- .gitignore：example/ 注释里的计数 20 → 21（实际 10 个示例 ×2 + qq/plugin_test.go；
  规则本身与「有意保留」的说明不变）

验证：go build ./internal/meta/ ./internal/agent/core/ 通过；官网 1440px 无横向溢出、
无控制台错误，footer 许可两行正确渲染（/tmp/lic-footer.png）。
 2026-09-24 10:55:23 +08:00
JianFeeeee
11144c62b5 chore(sdk): 同步 SDK 仓 SetAutoRestart 文档修正 
SDK 仓 5af2a86 把 `SetAutoRestart` 的「崩溃后自动重载」改准为
「崩溃后自动重启」，并补上真实约束（线性退避 1s→2s→3s、
5 分钟窗口内第 4 次崩溃即停止、与「重载」是两回事）。

主仓以 vendored 方式跟踪该文件（third_party/homeagent-sdk/sdk/plugin.go，
主仓只跟踪其 40 个文件、不含 README），故此处同步同一改动，
保持两处一致。
 2026-09-21 10:35:12 +08:00
JianFeeeee
3a780384d0 refactor(memory): 裁剪与召回收敛到唯一入口 memoryPass 
把「踢出去（prune）」与「取进来（recall）」从两处各写一遍，收敛为
memoryPass(query, trigger, prune, recall) 单一入口，统一：

- 同一份清洗后的 query（避免噪声带偏相关性打分）；
- 同一次 token 预算与召回截断；
- 同一条带 trigger 的审计日志（谁、据什么触发了哪种操作）。

落地：
- 新增 memorypass.go：memoryPass + pruneByQuery（原 pruneOnInput 的执行体）；
- pruneOnInput 只解析声明，执行委托 memoryPass；
- stepToolAfter 的裁剪/召回改为一次 memoryPass 调用（去掉重复的 topK 逻辑）；
- 抽出 recallText，输入侧 buildTaskMemoryContext 与工具侧 recallTextFor 共用；
- 输入侧召回 query 改用 CleanInput（清洗文本），与裁剪侧同一语义；
- QQ qq_get_history 补齐声明 ContextPolicy=prune + RecallPolicy=auto
  （内容类工具：真实聊天正文既当轮用完即裁，又据正文召回）。

测试：新增 memorypass_test.go，锁死 no-op / 两轴同时生效 / 正交不互相触发 /
输入侧用清洗 query。go build/vet 干净，internal/... 全绿，qq 插件模块测试通过。
 2026-09-14 23:32:41 +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
JianFeeeee
5ea87a498a chore(vendor): 同步 qq 插件权限身份绑帧修复（sdk cfa72df） 2026-09-14 16:45:17 +08:00
JianFeeeee
c252915083 feat(webui): 阶段管道改「循环 + 本轮轨迹」，区分工具/输出调用；再砍总览文字 
jianf：阶段管道像无记忆的单向滑块，但一轮里会多次 toolcall、也可能多次输出；
且没区分 output_* 调用与普通工具调用；总览仍有一大坨文字。

- 阶段管道不再是单向滑块：#
  画成 输入 → 行动 ⇄(工具↻) → 输出 → 结束 的循环结构，当前阶段高亮；
  下面用一排 chip 记**本轮真实发生过的序列**（on_input 重置、before_toolcall 追加、
  after_output 收尾，最多 24 条）。工具调用会反复出现，循环因此可见。
- 区分调用类型：普通工具 chip 前缀 ⚙（青），output_* 输出通道调用前缀 ⇥（accent 色），
  两者配色与图标都不同。
- 文字再收缩：删掉「累计：入队/执行/抢占/挂起/背压」整行；队列标签由
  「L4 内核独占…」压成 L4/L3/L2/L1/排队（原描述进 title）；各段标题压成
  「队列」「栈」「拓扑」；KPI 块标签压成 排队/中断/栈/子代理。

顺带（同类问题）：CLI /stop 是人在终端当场下的指令，优先级由默认 L1 提到 L3。
 2026-09-14 16:31:37 +08:00
JianFeeeee
7768168dd2 chore(sdk-vendor): 同步 qq 插件的消息合并改动（对应 SDK 仓 a01fe21） 
本仓 vendored 了 SDK 的部分文件（third_party/homeagent-sdk，经 go.mod replace
引用），其中 example/qq/plugin.go 被跟踪。SDK 仓的 qq 消息合并提交同步过来，
保持 vendored 副本与 SDK 仓一致。
 2026-09-14 16:11:22 +08:00
HomeAgent Agent
6878f0126d fix(lua): 同步注入在 Lua 中明确报不可用（避免自锁）+ 文档/mock 同步 
sdk.inject_input_sync / *_opts / inject_input_media_sync* 在 Lua 里必然自锁：
Lua 代码只在 Start/工具/阶段/输出/事件回调中执行，这些路径都持有 plg.mu，
而同步注入要等本轮回复（回复路径上的回调又需要同一把锁）。原实现会挂死
直到超时；现改为立即返回明确错误，并在中英文 PLUGIN_DEV 里标注不可用 +
指向 Go 插件/异步注入。mock sdk.lua（SDK 仓为事实源）同步为同样的错误语义。
新增 TestLuaSyncInjectUnavailable 钉住不挂死。
 2026-09-13 21:59:23 +08:00
HomeAgent Agent
162f33f81e feat(lua): Lua 插件桥全量对齐 SDK 1.3.0（媒体/注入标志位/优先级/事件/通道注销） 
内核 Lua 桥（internal/plugin/lua_plugin.go）此前停在 v0.8.0 时代能力面，
1.1/1.2/1.3 新增能力只在 Go 侧存在，而 PLUGIN_DEV.md 宣称『能力完全对齐』。
本补丁把 Lua 侧补齐到与公开 SDK 1.3.0 对齐：

- 1.1 媒体：memory.commit 支持 sentence_text/media_digests；
  doc.insert_with_media + attachments；text_memory.append attachments；
  set_tool_blocks / inject_input_media(_sync) / inject_interrupt_media。
- 1.2 注入语义：inject_input_sync(_opts)、六个 *_opts 变体
  （no_memory/context_policy/cleaner_name/priority）；
  ToolDef/ChannelDef 解析 context_policy。
- 1.3 优先级与动态通道：priority 常量透传；unregister_output_channel。
- StageContext 暴露 reasoning_content/context_msgs/token_usage/memory/extra/errors。
- 新增 sdk.events.subscribe 与 sdk.plugin_mgr.*。
- sdk.lua mock 同步（单一事实源在 SDK 仓 sdk/lua/sdk.lua，内核副本由
  third_party/homeagent-sdk/scripts/sync-lua-sdk.sh 同步）。

契约测试（lua_surface_test.go）：
- 守住内核内嵌 mock 与 SDK 仓事实源一致；
- 守住 mock 承诺的每个函数都有运行时 RawSetString 绑定；
- 覆盖 opts/media/attachments 解析与 context_policy 透传。

文档：中英 PLUGIN_DEV.md 的 Lua API 表补齐并改为『对齐至 SDK 1.3.0』。
 2026-09-13 19:56:32 +08:00
JianFeeeee
5160d8d4d1 chore(sdk-mirror): qq 插件 1.4.1（输出工具不再受当前会话身份限制） 
镜像 SDK 仓的插件修复：被子的中断唤醒的一轮里，父带齐 meta 调 output_send__qq 也被
「可信 QQ 会话身份不完整」拒掉；输出改为先放行（目标由 meta 决定），读取类工具仍限当前会话。
 2026-09-13 16:03:28 +08:00
JianFeeeee
fb2db2c304 docs: 两仓文档对齐当前版本状态 + 补发版产物清单；同步 SDK meta 路牌 
用户指出：SDK 版本又带 patch 位、agent 自称 1.0.3、两个仓库文档都没更新。

docs/git-branching.md：
1. **§三 状态表**重写（停在 2026-09-12：main 还写 1.3.0、release/v1.2.x 还被当成"本条发布线、
   尚无 tag"、SDK main 还写 1.2.0、完全没有 release/v1.3.x）。现按事实更新，并写明
   `v1.3.0` 是已撤回的坏 tag。
2. **§2.3** 增补：发布线的 `meta.Version` 必须跟着该线已发的最后一个 patch 走；
   只用 `-ldflags -X` 打版本而不改源码会让二进制与源码对不上账（1.3.1–1.3.4 就是这么打的）。
3. **反例表**补两行：人格文本在**播种时**固化版本（生产实例自称 v1.0.3）、
   发布线路牌不随 patch 推进 / 给 SDK 误发 patch tag。并澄清"插值"必须在**渲染时**，
   把算好的结果固化进配置库与写死没有区别。
4. **§七.5 新增"发版产物清单（可复现）"**：核心仓（tar.gz + 3 个 deb + SHA256SUMS，
   校验和必须在全部产物生成后统一算）、SDK 仓（5 平台 hmapdev + SHA256SUMS）、
   上传脚本的用法与两个坑（release 条目必须先存在；`hmapdev_*` 无扩展名不会被自动识别）。
   起因就是本次"推了 tag 却没建 release、没打包"——推 tag ≠ 完成发版。

third_party/homeagent-sdk/meta/meta.go：镜像 SDK 仓 main 的路牌（1.3.0 → 1.4.0）与
版本语义注释更新（1.3.0 已定版 ⇒ 该号归发布线，main 推进）。
 2026-09-13 14:41:24 +08:00
JianFeeeee
44cc824b28 chore(sdk-mirror): a2a 1.3.0→1.3.1、acp 1.2.0→1.2.1 的 plg.json 跟上 SDK 仓 
SDK 仓 11303e3 升了两个示例插件的版本（补 RegisterInputChannel 后按插件自身语义升 patch），
外层仓镜像里这两个 plg.json 忘了同步 —— 镜像与源头不一致会让"装的是哪个版本"对不上账。
 2026-09-13 14:30:56 +08:00
JianFeeeee
3f431063e2 chore(sdk-mirror): 同步 SDK 仓 v1.3.1 的文档 —— 通道名会进 LLM 函数名（命名约束） 
镜像文件：`third_party/homeagent-sdk/sdk/plugin.go`（`RegisterOutputChannel` 的命名约束）。
SDK 仓对应提交/tag：v1.3.1。

说明：内核 v1.3.1 的 tag 已指向功能修复提交 d17c186，本镜像提交在其之后 ——
文档镜像不参与二进制构建，故不影响已部署产物；功能与文档的对应关系见两仓 tag 说明。
 2026-09-13 13:10:38 +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
ae9b06976c chore(sdk-mirror): 同步 SDK 仓 4cb3a0b —— 通道方向契约 + 示例插件显式登记 inputch 
镜像文件（外层仓按策略只跟这些；`example/` 被 .gitignore 忽略，已跟踪文件用 -f 提交）：
- `sdk/plugin.go`：RegisterInputChannel/RegisterOutputChannel 的方向契约文档
  （入站 vs 出站分开登记；用哪个通道名注入就要登记哪个）。
- `example/{a2a,acp,browser,memo,calendar,rss}/plugin.go`：补 RegisterInputChannel。

未镜像（外层 .gitignore 忽略，按策略不入镜像）：
`README.md`（README*）、`tools/hmapdev/{templates.go,cmd_sdk.go,cmd_build.go}`（tools/）
—— 即"模板工程"与"`sdk install --from`"两项改动只存在于 SDK 仓，详见该仓提交 4cb3a0b。

注：这 6 个示例此前未 gofmt（`example/*` 共有 9 个未格式化文件），
本次改动文件被 gofmt 顺带规范，diff 里含格式噪音（calendar 49 行、a2a 33 行）。
 2026-09-13 11:38:10 +08:00
JianFeeeee
f3232000f4 feat(scheduler): L4 也归内核级插件 —— WebUI 终止按钮可用“立即打断” 
上一提交把 L4 写成“内核独占（panic / selfip）”，漏了内核级插件这类来源。
用户澄清：**内核级插件应当能声明 L4，用于实现中断能力**，例如 WebUI 的终止按钮。

判据（两道闸，纵深防御）：
  1. proc 桥（外部进程唯一入口）一律把 L4 夹到 L3。在这里夹而不是只按 source 判，
     是因为 source 是插件自报字段、可以冒名；本函数所在位置能确知“来自外部进程”。
  2. core：isKernelLevelSource(source) 查 pluginReg.IsBuiltinPlugin，只有编译期内置
     插件（init() 自注册的工厂）才承认 L4。
source 约定 `插件名` 或 `插件名/实例`（webui/<deviceID>），判据取第一段——
否则带设备身份的 WebUI 来源会被误判成外部插件而拿不到 L4。

改动：
- core: interruptLevel(evt, privileged bool)；新增 isKernelLevelSource；
  requestPreempt 不再夹取（级别已由 interruptLevel 解析，否则内核级插件的 L4 被削掉）。
- eventloop: 传入 a.isKernelLevelSource(evt.Source)。
- proc 桥: 新增 clampExternalPriority，pubSdkInjectOpts 一律夹取。
- internal/sdk: 再导出 PriorityL1..L4（内置插件用 sdk.PriorityL4）。
- webui handleChatInterrupt（终止按钮）声明 PriorityL4。
- timer 声明 PriorityL3：定时器是“时钟那种实时工作”，比 QQ 那类可无限等待的
  异步消息高（L1）——这是对用户“它不是时钟那种实时工作”的直接推论，可改。
- 测试: L4 特权矩阵（非特权夹取 / 特权承认）、source 判据（内置、内置/实例、
  外部、空、前缀不误匹配）、内核级插件 L4 一路到达调度器、proc 夹取两条。
- 设计稿 §2/§3.2/§11.1/§14/§15 按“L4 = 内核 + 内核级插件”更正。

验收：go build/vet 干净；go test ./... 37 包 ok 0 FAIL；-race 全绿（含 webui/timer）。
 2026-09-13 07:18:03 +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
163c5f70b3 chore(sdk-mirror): 同步 vendored SDK 到 SDK main（browser_search 现代 Bing 版式解析修复） 
镜像追平 SDK main（`ebd700e`）：
- browser 示例：browser_search 三处根因修复（www.bing.com 302 → cn.bing.com；
  标题取 h2 > a 而非块内第一个 <a>；摘要兼容 p.b_lineclamp*）并解开 /ck/a 跳转包装，
  解析不出结果时显式报错；附真实响应夹具与 5 项单测；版本 2.4.0 → 2.4.1。

注：SDK 仓新增的 example/deepsearch（联网检索 + SearXNG 生命周期托管）与
example/vikunja（任务管理）按本仓策略（.gitignore 忽略 example/ 下未跟踪文件）不入镜像。
 2026-09-12 23:39:10 +08:00
JianFeeeee
d1662e77cf chore(sdk-mirror): 同步 vendored SDK 到 SDK main（qq 插件重写、browser 会话超时必填、路牌 1.3.0） 
核心仓 `third_party/homeagent-sdk` 是 SDK 仓的 vendored 副本，内容以 SDK 仓 main 为准
（本仓 `.gitignore` 忽略 example/ 下的未跟踪文件，已跟踪的镜像文件用 `git add -u` 更新）。
本次把镜像追平到 SDK main（`8c10b7e`）：

- qq 插件重写（+498 行）：`output_send` 回声/自激路径的根因修复与去重；
- browser 示例：交互式会话 `timeout` 由默认 10m 改为**必填**（附参数校验与测试）；
- `meta.Version` 1.2.0 → **1.3.0**（SDK v1.2.0 已定版，SDK main 按纪律推进到下一个中版本）。
 2026-09-12 20:21:01 +08:00
JianFeeeee
5e10f012cb docs(license): 核心仓采用 AGPL-3.0-only，并写进包内与安装器 
本仓此前**没有任何许可文件**，README 里也没有许可声明，而 rpm 元数据里甚至写着
`--license "Proprietary"`（与我们实际的分发意图相反）。

## 选择了什么

`LICENSE`：GNU Affero 通用公共许可证第 3 版官方全文（gnu.org 正本，
661 行 / 34523 字节，
sha256 0d96a4ff68ad6d4b6f1f30f713b18d5184912ba8dd389f86aa7710db079abcb0）。

选 AGPL-3.0-only 的理由：GPL 家族里**传染性最强**的一档，并且不允许选后续版本。
它比 GPL-3.0 多出 §13（Remote Network Interaction）——通过网络提供服务时也要向
使用者提供源码。这正是「最严格」在 GPL 家族里的落点。

依赖许可已核对为全部宽松且兼容：go-sqlite3 / gojieba / gopher-lua / bubbletea /
bubbles / lipgloss / yaml.v3（MIT）、golang.org/x/{sys,text}（BSD-3）、
Chinese-CLIP 产物（Apache-2.0，与 GPLv3+/AGPLv3 双向兼容）、ONNX Runtime（MIT）。
没有 GPL-2.0-only 这类与 AGPL 不兼容的依赖。

## 落在哪些地方

- `README.md` / `README_EN.md`：新增「许可 / License」章节，写明 §13 的含义、
  插件因**静态链接 SDK 源码**而成为衍生作品须同许可发布、以及随包第三方组件清单
- `deploy/packaging/package-linux.sh`：
  · 新增 `stage_license()`，**四个变体（full/server/client/tar）全带**
    `/usr/share/doc/homeagent/{LICENSE,copyright}`（copyright 为 DEP-5 机器可读格式，
    含第三方条目）
  · fpm 的 `--license "Proprietary"` → `"AGPL-3.0-only"`
- `deploy/packaging/installer.nsi`：新增 MUI 许可页
  （`..\..\LICENSE`，NSIS 以 .nsi 所在目录解析相对路径）
- `third_party/homeagent-sdk/LICENSE`：vendored SDK 的许可一并入库 —— 本仓
  `.gitignore` 有意不镜像 SDK 的 README/tools/package/example，但依赖的许可
  应当随依赖可见

## 待办（下一步）

README 的「项目状态」仍停在 v1.1.1，且写着已被 v1.2.0 **删除**的机制
（引用计数式 GC、`[<mime> <digest>] <描述>` 描述式索引）——单独一个提交修。
 2026-09-12 09:17:03 +08:00
JianFeeeee
fbd3adabea fix(sdk-mirror): vendored SDK 路牌回到 1.2.0（SDK 不跟 beta 发版） 
SDK 仓 44bd915 把 main 的 meta.Version 推到 1.3.0 是错的（12cabcb 已改回 1.2.0）。
按 §七.2，beta 不伴随 SDK 发版：SDK 1.2.0 要等核心的**正式** tag 才定版打 tag
（§七.3），在那之前 1.2.0 仍是 SDK 尚未发布的中版本，路牌不得越过它。

核心 main 的 1.3.0 不受影响（1.2.0 已归 release/v1.2.x 所有），两仓在此阶段
故意不对称——这一点已写进 SDK meta.go 的注释，避免再被「对齐」回去。

本提交只同步 core 里跟踪的镜像：sdk/ 目录与 SDK 仓仍然逐字节一致。
 2026-09-12 09:00:41 +08:00
JianFeeeee
1fb5700662 chore(meta): main 的版本路牌推到 1.3.0 
按 docs/git-branching.md §2.1，main 的 meta.Version 始终是**下一个未发布中版本**。
1.2.x 线已开（release/v1.2.x 承载 1.2.0），所以 main 指向 1.3.0。

它标记「main 正在积攒 1.3 的东西」，不表示 1.3.0 已经存在——1.3.0 没有任何 tag。
1.2.0 已由 release/v1.2.x 承载；main 不能再挂着 1.2.0，否则 main 的版本号
就与某一次发布的版本号相同，违反 §2.1「main 的版本号不是任何一次发布的版本号」。

两仓同步：SDK 仓 main 也在同一时刻推到 1.3.0（commit 44bd915）——SDK 版本跟随
核心中版本（§七.1），且两仓 main 都表示下一个未发布中版本（§七.4）。
本 commit 同时把 vendored SDK 镜像（third_party/homeagent-sdk/meta/meta.go）
更新到与 SDK 仓一致。

SDKCompatibleVersion 保持 1.2.0：那是本内核**实际实现并兼容的最高 SDK 接口版本**，
与「下一个未发布中版本」是两件事（参见 e4be966 时 main 的 1.2.0 / SDK 兼容 1.1.0）。

**此 commit 不 cherry-pick 到发布分支**（§五：版本号 bump 不跨分支搬）。
 2026-09-12 08:25:30 +08:00
JianFeeeee
4d2028fbef chore(sdk): 同步 vendored SDK 镜像到 1.2.0 
core 仓里跟踪的 SDK 镜像落后于 third_party/homeagent-sdk（那是个独立仓库）：
已提交的 sdk/memory.go 仍带 MediaAttachment.Description，而 SDK 仓 b2eafdf 已把它
删掉（媒体不再以文本描述参与索引）。磁盘上的文件其实就是 SDK 仓当前的版本，
只是 core 的索引没有跟上——于是**干净检出 main 拿到的是一个与它构建所用 SDK
不一致的镜像**。

clean worktree 能编译（内核已不再引用 Description），所以这个不一致不会被构建
发现，只能靠比对发现——属于本项目一直在治的「静默不一致」。

同步内容：sdk/memory.go 与 SDK 仓 HEAD 逐字节一致。
 2026-09-12 08:21:21 +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
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
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
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
670efcd426 sdk: 同步 SDK 仓 meta 到 1.0.0（vendored 侧） 
SDK 仓的 5ed8d65 在主仓这边的对应提交。主仓经 replace 引用
third_party/homeagent-sdk，其 sdk/ 与 meta/ 由主仓一并跟踪
（只有 example/ 与 tools/ 被 .gitignore 忽略）。
 2026-09-02 23:02:26 +08:00
JianFeeeee
b20121f703 plugin: 删除 C ABI 通道（Part 6.2 完成，-3198 行） 
外部插件统一走子进程 + stdio RPC，三套独立 ABI 实现收敛为单一 RPC 实现。
用户决策：彻底舍弃 .so 能力，不保留双通道回退。

## 删除清单

internal/plugin/cabi/                     1156 行（loader.go/loader.c/types.go/output_test.go）
internal/plugin/dynamic_dll_windows.go     272 行（§9.2 记录的能力退化实现）
internal/plugin/dynamic_loader_unix.go      79 行（唯一 cabi 引用点）
internal/plugin/dynamic_dll_test.go         32 行
internal/plugin/dynamic_dll_stub.go         11 行
internal/plugin/dynamic_loader_windows.go   11 行
internal/plugin/bridge_e2e_test.go              （测的是 cabi 路径）
third_party/.../plugindev/templates.go    1296 行（取消跟踪，SDK 仓才是权威副本）

dynamic.go：entryCABI 通道删除，soEntry/dllEntry 常量删除。
registry.go：tryDynamic 探测顺序从 .so → .dll → .lua 变成 proc → lua。

## 旧 .so 给明确错误，不静默跳过

静默跳过会让「插件目录在但没加载」看起来像配置问题，而实际原因是需要
用新版 plugindev 重编。故保留 legacyCABIEntries 表专门用于识别残留：

  plugin legacy: 检测到旧 C ABI 产物（plugin.so/.dll/.dylib）。
  外部插件已改为子进程模式，请用新版 plugindev 重编产出 plugin.bin
  （业务代码无需修改）

错误消息里「业务代码无需修改」这句是有测试守着的——迁移的核心承诺就是它。

## pluginmgr 安装逻辑跟进 bundle 命名

子进程模式下各平台产物统一叫 plugin.bin（进程边界即 ABI 边界），故 zip 内
按平台加后缀 plugin.bin.<goos>.<goarch>，解包时挑当前平台那一份重命名。

platformBinary 改为按 runtime.GOOS+GOARCH 生成条目名；platformBinaries 固定表
换成 isPlatformBinary 前缀判断（平台组合会增长：linux/arm64、darwin/arm64…，
按前缀判断无需维护清单）。

新增 chmod 0755：zip 保留了原权限位，但经某些工具链/传输后可能丢失，
内核加载时会因缺执行位报错。提前补上比事后让用户 chmod 更好。

## 测试

entry_dispatch_test.go 重写（12 项）：
- classifyEntry 对 .so/.dll/.dylib 现在返回 unknown
- LegacyManifestFallsBackToProbe：存量插件 manifest 仍写 "plugin.so"
  （17 个插件没人去改），须靠目录探测找到 plugin.bin —— 这是
  「外部插件零改动」的直接后果
- LegacyCABIGivesActionableError：错误消息须含 plugindev / plugin.bin / 业务代码
- PluginEntryHash_IgnoresLegacyCABI：.so 不参与 hash（内核已不认它）

upgrade_test.go 的 .hmap 构造改用 plugin.bin。

验证：go build ./... 通过；go test ./... 全仓无失败；
go test -race ./internal/plugin/... 全绿；三平台构建通过。

Ref: docs/zh/架构迁移评估.md §3.1/§9.2、docs/zh/plugin-migration-plan.md Part 6
 2026-09-02 19:26:40 +08:00
dev
2e2602f437 docs(plan): Part 0.1/0.2 勾选 + 迁移计划进度标记 
- plan.md 11.1 (3 checkbox)、11.3 (3 checkbox) 全部勾选
- plugin-migration-plan.md: 0.1/0.2 标记 ✅ 完成（含踩坑记录与待部署项）
 2026-08-31 12:33:24 +08:00
JianFeeeee
eba300aec2 chore: 同步 vendored SDK（qq v1.2.0 + plugindev bridge 修复） 
third_party/homeagent-sdk 同步至 SDK 仓 61f307b：
- fix(plugindev): bridge 模板补 dispatchIO.SetToolBlocks
  SDK v0.9.2 给 IOInjector 加了该方法但 C ABI bridge 模板未同步，
  导致任何外部插件编译失败（missing method SetToolBlocks）
- feat(qq) v1.2.0: msg_id→get_history 7 天兜底（不缓存正文）
  + qq_list_chats / qq_mark_read 会话列表（按最新消息排序 + 未读数）
  + 中断模板补 fallback 路径与私聊 user_id

.gitignore 补 HarmonyOS 构建工具链缓存（.hvigor-home/ .npm-cache/ .ohpm/），
这些由 HVIGOR_USER_HOME/ohpm 生成，非源码。

go build ./cmd/homed/ 通过。
 2026-08-30 17:14:07 +08:00
JianFeeeee
14f3605f6e chore: sdk v0.9.2 vendored副本同步 + go.mod 依赖更新 
- third_party/homeagent-sdk/meta/meta.go: 0.9.1 → 0.9.2
- go.mod: require v0.9.2（replace 保留，指向本地 vendored 目录确保可编译性）
- CoreVersion 同步更新
 2026-08-27 09:36:49 +08:00
JianFeeeee
c44ec0f210 feat(waiter): daemon模式 + localuse本机外设插件 
waiter 新增 --daemon 后台驻留模式 (daemon.go):
  - 维持 homed 连接，TUI实例经 Unix socket 接入
  - 单客户端串行模型：每个TUI独占homed响应，新客户端回放缓冲(256行)
  - 设备桥场景可无 homed 运行（纯设备桥驻留）
  - 设备桥看护循环：WS断开自动重连(3-5s间隔)
  - conn.go 新增 daemonConn 类型，dial() 优先检测 daemon

localuse 插件 (internal/plugins/localuse/):
  - local_screensee / local_camerasue / local_speakeruse
  - local_screensue / local_clipboardsee / local_clipboardsue / local_computeruse
  - 跨平台实现(Linux/macOS/Windows)，能力与 waiter device.go 对齐
  - headless服务器上缺依赖工具自动返回安装提示

SDK sync: third_party SetToolBlocks 多模态类型同步
README 补充 daemon 模式使用文档
 2026-08-27 09:27:15 +08:00
JianFeeeee
f0cdbdb030 feat(sdk): SettingsAPI.DataDir() 插件专属数据目录 + ai_image 本地交付 
【SDK DataDir API】
- SettingsAPI 新增 DataDir() string：返回插件专属数据目录
  <data>/plugin_data/<name>（内核保证存在），解决此前插件只能
  靠 GetCore("daemon.data_dir") 手工解析的缺陷
- settingsImpl 新增 dataDir 字段 + SetDataDir；Registry buildSDK
  注入（<data>/plugin_data/<name> 并 MkdirAll）；main.go 接线
- cabi 新增 CORE_SETTINGS_DATA_DIR (id 51)；plugindev dispatchSettings
  模板补 DataDir() 实现

【ai_image 交付本地路径】
- 生成后下载临时 S3 URL 到插件数据目录，返回本地文件路径（永久不
  过期），而非 1 小时过期的 S3 URL。带 UA 规避图床对无 UA 客户端拦截
  （此前 agent 裸 curl 验证被拒导致误报失败）
- 返回 local_paths 字段 + 提示用 output_send(type=image) 展示

端到端：ai_image_generate → plugin_data/ai_image/*.png 有效 PNG(1024²)，
经 llmsproxy→siliconflow 生成。
 2026-08-26 21:40:29 +08:00
JianFeeeee
d0fc7e03c1 feat(ai_image): base_url 设置项支持自定义 OpenAI 兼容网关 v1.1.0 
generateOpenAI 原硬编码上游为 https://api.openai.com，无法接入
本机 llmsproxy(ModelRouter) 等标准 OpenAI 兼容网关。新增：

- 设置项 base_url（string，默认空）：为空保持官方直连；非空时
  上游改为 {base_url}/v1/images/generations（约定不带 /v1 尾缀，
  拼接时自动去重避免 /v1/v1）
- Plugin.baseURL 字段 Start 时读入；注册 ConfigDef（category
  ai_image）供 WebUI 配置页展示

部署：plugindev 打包 1.1.0 → pluginmgr overwrite:true 升级安装
config_kept=true → plgreload 热加载。

配置（category ai_image）：api_key=sk-gw-local-0001,
base_url=http://127.0.0.1:8081, provider=openai,
model=Kwai-Kolors/Kolors, size=1024x1024

验收：agent 实调 ai_image_generate 出图成功——llmsproxy audit
记录 type=image src=siliconflow model=AUTO ok=true（经网关非直连），
返回临时 S3 URL 下载为有效 PNG (1024x1024)。
 2026-08-26 19:46:59 +08:00
JianFeeeee
5fb15f5045 feat(a2a/acp): 会话历史查询 session.get + 客户端 session_id 透传 
a2a:
- tasks.get 从空壳改为按 session_id 返回会话内近 N 条消息（默认10）；
  新增 session.get 别名同语义
- a2a_query（出站）接受 session_id 参数透传给目标 agent，
  响应回显 session_id + 延续提示
- A2AParams/A2AResult 加 session_id 字段；工具描述补说明

acp:
- 新增 JSON-RPC method session/get：按 session_id 返回近 N 条消息
- acp_query（出站）接受 session_id 透传给 session/new，
  响应回显 + 延续提示
- params 结构体加 limit 字段

端到端验证（回环本机）：
  a2a tasks.send→建会话；session.get→返回[user/agent]交替消息列表
  同 session 第二轮延续上下文正确（记数字→答数字）
  acp session/new + session/get 同样通过
 2026-08-26 19:30:32 +08:00
JianFeeeee
14aa0c880b fix(a2a/acp): 回复闭环 + 会话延续 + 同步注入（不再抢占打断） 
【问题】
1. 入站请求用 InjectInterruptText 抢占打断当前对话，立即回 202 submitted，
   agent 的回复 emit 到未注册的 channel（a2a/acp）→ 请求方永远拿不到回复文本，
   只能干等超时。（acp 的 session.Replying 从未被填真回复 → SSE 永远 "(未收到回复)"）
2. 无法指定/延续 session：a2a 无 session 概念；acp session/new 每次新建、
   不接受调用方 session_id，多轮上下文断裂。
3. a2a/acp 通道未注册为输出设备 → emitResponse 的回复无落点，
   output_list_channels 也不可见 → agent 困惑"回复该发到哪"。

【修复】
- 入站改用 SDK InjectInputSync 同步注入：阻塞等待 agent 处理完成，
  直接把最终回复文本返回给 HTTP 请求方（不再回 202）。
  这是 A2A/ACP 协议的合理形态——客户端控制超时，服务端同步返回。
- session 支持：a2a tasks.send 与 acp session/new 均接受 params.session_id，
  指定则延续已有会话（拼上下文前缀），不指定则新建并返回 session_id。
  单会话保留最多 10 轮历史防膨胀；30min GC 清理 2h 未用会话。
- a2a/acp 注册为输出通道（RegisterOutputChannel）：回复有落点，
  output_list_channels 可见，agent 可主动 output_send 推消息。
- 注入提示词明确"直接以文本回复即可，无需调 output_send"——
  agent 不再把回复走 queued 入队而返回干净文本。

端到端验证：
  单轮：status=completed, reply=真实回复文本（非 submitted）
  多轮：同 session_id 第二轮准确复述第一轮问题（上下文生效）
  a2a v1.2.0 / acp v1.1.0 安装 config_kept=true
 2026-08-26 19:16:46 +08:00