jianf/homeagent-sdk
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/homeagent-sdk.git synced 2026-10-01 23:03:06 +00:00
Code Issues Packages Projects Releases Wiki Activity
139 Commits 5 Branches 10 Tags
c7e5d2a446c97a6ecd2bd3825ec8dface551a66c
Commit Graph

139 Commits

This Branch
This Branch
All Branches
Author SHA1 Message Date
JianFeeeee
c7e5d2a446 docs: README 补文档站入口，并把「SDK 源码」链接迁到 GitHub 
SDK 仓此前**没有任何地方指向文档站** —— README 不写、GitHub 仓的
homepage 字段也是空的，于是从仓首页根本走不到 sdk.homeagent.jianfgit.xyz。
文档站本身一直在线（106 个文件的 mkdocs 产物），只是没人从仓里指过去。

本次补上：
  - README.md / README_EN.md 顶部加文档站入口（快速开始 / API 参考 / 能力边界
    / llms.txt + llms-full.txt 的 agent 直读入口），并在末尾加「文档」章节
    列出全部页面的直链。
  - mkdocs.yml 的社交链接由 gitcode 改指 GitHub，并**新增** gitcode 镜像入口与
    介绍站入口（国内直连 gitcode 更快，海外/权威源看 GitHub，两个都留）。
  - docs/guide/getting-started.md 的 `git clone` 地址改为 GitHub 仓名
    （homeagentsdk），并写明「release 附件暂时仍在 gitcode」这个事实。

★ 刻意**不**改的东西：Go 模块路径 `gitcode.com/JianFeeeee/homeagent-sdk`。
改模块路径会让所有现有插件的 go.mod 全面失效，属于破坏性变更，
与「仓库托管位置迁移」是两件事。

关于 GitHub 侧没有 release 条目（因此不能写 releases/latest/download/...，
那会 404）：已在 README 里如实写明 —— 二进制目前只在 gitcode 的 release 附件里，
GitHub 从下一个 SDK 版本（v1.4.0）起才会同步发布。

验证：两份 README 里 28 个 URL 全部实测 200；文档站重建（106 文件）并部署，
线上 `git clone` 已是 GitHub 地址、旧 gitcode clone 地址 0 次、
三个社交入口名称正确。
 2026-09-29 20:43:27 +08:00
JianFeeeee
c16411a77d ci: 修 CI 自身的三处错误（本地能过 ≠ CI 能过） 
首次跑出来的 8 个失败全是本 workflow 自己的问题，不是代码缺陷。
三条都属同一类：**命令本地验证过，但环境前提不同**。

## 1. hmapdev 交叉编译：在错误的目录跑（5 个平台全红）

     no Go files in /home/runner/work/homeagentsdk/homeagentsdk

`go build .` 缺 `working-directory: tools/hmapdev`，于是在仓库根执行 ——
根目录没有 Go 文件（包在 sdk/ 子目录）。加 working-directory 后本地实测
linux/arm64、darwin/arm64、windows/amd64 均产出 27–30MB 二进制。

## 2. Examples：装了 Go 1.21，而 examples 要求 1.25

     go: go.mod requires go >= 1.25.0 (running go 1.21.0; GOTOOLCHAIN=local)

`go-version-file: go.mod` 读的是**根** go.mod —— 它写 `go 1.21.0`，
而 20 个 `example/*/go.mod` 都要求 `go 1.25.0`（只有根与 tools/hmapdev 是 1.21）。
于是 CI 装 1.21，examples 构建必失败。

★ 为什么本地测不出来：本机 Go 1.27 且 GOTOOLCHAIN 默认可自动取更高工具链，
  更高版本能满足 1.25 的下限，所以一路通过。而 GitHub runner 上
  **GOTOOLCHAIN=local**，Go 拒绝自动下载工具链，低版本直接报错。
  本地「能过」在这里完全不构成证据。

改法：SDK CI 全部钉 `go-version: '1.25'`（同时满足 1.21 的下限与
examples 的 1.25 要求）。

## 3. 技能检查：hmapdev 建到了 /tmp

     error: no active SDK version set

`resolveSkillsSource()` 先用**可执行文件位置**向上找仓库
（tools/hmapdev → ../../skills），落空才回退到 SDK store 的活跃版本。
我把二进制建到 /tmp/hmapdev ⇒ 推出仓库失败 ⇒ 回退 ⇒ CI 里没有 store ⇒ 报错。

改法：建到仓库内 `<repo>/build/hmapdev_ci`。本地实测（构建在仓库内时，
即便从 /tmp 调用也能正确识别仓库源——解析依据是 exe 位置而非 cwd）。

## 附带记录

- 根 go.mod(1.21) 与 example/*/go.mod(1.25) 的版本不一致本身值得关注：
  用 Go 1.22–1.24 的用户按示例走会失败。是否统一属产品决策，本次不动。
- actionlint 全绿。
 2026-09-29 15:29:16 +08:00
JianFeeeee
5759e58bad ci: 建立 CI —— 此前 main 的推送与 PR 完全没有检查 
## 缺口

本仓此前**只有 release.yml**（只在 release/** 推送时跑）。也就是说
推 main、开 PR 一律无检查，而 SDK 正是外部插件开发者直接依赖的契约面
（sdk/plugin.go 接口一破，所有外部插件编译失败）。

## 四个 job（每条命令都本地实测过）

| job | 内容 | 实测耗时 |
|---|---|---|
| go | 根模块 build + vet + test | <1s |
| hmapdev | 嵌套 module 测试 + 五平台交叉编译（矩阵） | ~2s + 编译 |
| examples | 构建全部 20 个示例（linux/amd64、darwin/arm64） | 9s / 21s |
| consistency | Lua SDK 三副本一致 + skills 可识别 + mkdocs --strict | ~2s |

## 三处「不能想当然」的地方（都有实测依据）

1. **示例不能用 `go build` 验**。它们是插件（只有 plugin.go、没有 func main），
   必须由 hmapdev 注入 main 包装；直接 go build 得到
   "function main is undeclared in the main package" —— 那不是缺陷，是方式不对。
   故与发版走**同一个脚本**（package/build-examples.sh），避免 CI 与发版路径分叉。
2. **tools/hmapdev 是独立 module**，根模块的 `go test ./...` 不会进入它 ——
   必须单独跑，否则它的测试永远不在 CI 里执行（Go 的模块边界）。
3. **不能用 `yaml.safe_load` 校验 mkdocs.yml**：它含 mkdocs-material 的
   `!!python/name:` 标签（配置 emoji 的官方写法），safe_load 报
   ConstructorError —— 是校验方式不对。改用 `mkdocs build --strict`
   （本地实测 2s、0 warning）。

## 明确不进 CI

- `hmapdev skill install` —— 它会写开发者本机的 ~/.claude、~/.codex 等目录
- 需要内核仓在场的检查（本仓独立可测）
- 任何网络/真机依赖

CGO_ENABLED=0（SDK 纯 Go，与主仓相反）。

actionlint 全绿（修掉一处 shellcheck SC2012）。
 2026-09-29 15:18:58 +08:00
JianFeeeee
275a054287 fix(packaging): build-examples.sh 用新变量名 HMAPDEV 会 unbound variable 
## 症状

按注释声称的「兼容」用法传新名，脚本立刻死：

    HMAPDEV=... bash package/build-examples.sh linux/amd64 /tmp/out
    → package/build-examples.sh: line 72: PLUGINDEV: unbound variable   (exit 1)

而传旧名一切正常：

    PLUGINDEV=... bash package/build-examples.sh linux/amd64 /tmp/out
    → 成功 20 / 失败 0

## 根因

第 71 行写的是：

    HMAPDEV="${HMAPDEV:-${PLUGINDEV:-$SDK_ROOT/build/hmapdev}}"

这**只定义了 HMAPDEV**；PLUGINDEV 若未设置就仍是未定义变量。
而紧接着的 72/77/100 三行读的却是 `$PLUGINDEV`：

    if [ ! -x "$PLUGINDEV" ]; then        # ← 未定义 → set -u 下致命
    out=$( cd "$dir" && "$PLUGINDEV" build ... )

于是只有当调用方**恰好传旧名**时 PLUGINDEV 才有值、才工作。
注释说「旧变量名 PLUGINDEV 仍兼容」——兼容的方向反了：是旧名恰好能跑，
新名不能。

## 为何一直没暴露

发版路径传的正是旧名（build.sh:92 `PLUGINDEV="$dev" ...`），
所以 release 流程一路是绿的。任何人按新名（或根本不传）调用都会撞上。

## 修法

三处改读 `$HMAPDEV`（第 71 行刚解析出的规范名）。

## 验证（三种调用方式都要能工作）

    A) HMAPDEV=...    → exit 0，20/20，20 个 .hmap（修复前 exit 1）
    B) PLUGINDEV=...  → exit 0，20/20（向后兼容保持）
    C) 都不传          → 自动先构建 hmapdev，再 20/20

跨平台也验过：linux/arm64 20/20（19s）、darwin/amd64 20/20（21s）；
windows 被有意拒绝并给出明确原因（协议 2 的统一共享内存区未移植）。
 2026-09-29 15:18:43 +08:00
JianFeeeee
56c694cd7c ci: gh release download 需显式 --repo 
回读校验先 cd /tmp/back（非 git 目录），而 gh 默认从当前目录的
git 上下文推断仓库，于是报 "not a git repository" —— 发布本身
成功（tag/release/附件齐全），却被这道校验误判为失败。

改为 gh release download "$TAG" --repo "$GITHUB_REPOSITORY"。
 2026-09-29 14:39:12 +08:00
JianFeeeee
dc9e7d0495 ci: SDK 仓发布流水线 —— release/** 推送即出 hmapdev 五平台产物 
与主仓 Release 流水线同构，差异只在产物与打包命令：

  prepare  读 meta.Version；tag 已存在则整轮跳过；go test 门可显式跳过
           （改 meta 的提交里写 [skip-release-tests]，查该提交而非 HEAD）
  build    go build（硬门）→ go test → build.sh all hmapdev → 验证 5 平台齐全
           → 生成 SHA256SUMS → artifact
  publish  打 tag → gh release create 传附件 → 回读校验
  sync-gitcode  有 GITCODE_TOKEN 时同步（无则跳过）

产物清单不是猜的，依 gitcode 上 v1.2.0/v1.3.0 的实际附件（各 6 个）：
  hmapdev_{linux,darwin}_{amd64,arm64} + hmapdev_windows_amd64.exe + SHA256SUMS

两个易错点都有实测依据：

1. **测试要分两处跑**：tools/hmapdev 是**独立 module**，根模块的
   `go test ./...` 不会进入它（Go 的模块边界，不是配置问题）。
2. **gitcode 上传必须显式列文件名**：上传脚本的路径语义是
   `os.path.join(ASSET_DIR, name)`，所以要 cd 进目录 + `ASSET_DIR=.` + 裸名；
   而它按扩展名识别产物的默认扫描对 hmapdev **无效** —— 五个产物里只有
   windows 那个有扩展名，自动扫描会静默地一个都不传。
   故把主仓的 upload_assets.py 一并纳入本仓 scripts/（两仓各自独立可取）。

本地已验证：`VERSION=1.4.0 bash package/build.sh all hmapdev` 产出 5 个
二进制（各 27–29M），根模块 go test 通过，actionlint 全绿。
 2026-09-29 14:09:35 +08:00
JianFeeeee
29c61f0e07 feat(hmapdev): skill 子命令 —— 插件开发知识随 SDK 分发 
## 为什么需要

HomeAgent 插件开发的知识（hmapdev 工具链、SDK 版本坑、plg.json、
plugin.bin 部署、内置 vs 独立二进制）此前只存在于**某个 agent 的对话历史**里。
本机四个 agent（pi / claude / codex / .agents）都不会开发插件，
因为它们**没有任何渠道**拿到这些知识。

知识属于 SDK（与工具链同源、随 SDK 版本走），所以：
- 源：`skills/`（随 SDK 仓分发）
- 装：`hmapdev skill install`

## 命令

    hmapdev skill list              列出活跃 SDK 里的 skills
    hmapdev skill install [name...] 装到各 agent 的 skills 目录
    hmapdev skill path               显示源目录与来源

安装目标（**只装这些**，不认识的目录不创建）：

    ~/.pi/agent/skills   ~/.claude/skills
    ~/.codex/skills       ~/.agents/skills

## 两条策略，与别处**故意相反**

1. **总是覆盖**。skill 是**工具生成物**，不是用户数据。保留用户改过的版本
   会让它与工具链脱节 —— 而工具链的命令面会随版本变。
   （对比：`hmapdev build` 写出的适配器更新会**保护**用户修改，
   因为那是运行时代码；skill 只是说明文档。）
2. **不扫 glob 自动发现**。不认识的目录建出来也没用，
   还会让用户以为装上了。

## 源目录：仓库优先，store 回退

store（`~/.homeagent/hmapdev/sdk/<v>/`）是 `sdk install` 复制的**副本**。
而 skill 是纯文档、加它不需要动 SDK 的编译产物 ——
「改了 skill 却要重装 SDK 才能生效」对日常维护不合理。

故优先用 hmapdev **自身所在仓库**的 `skills/`（靠可执行文件位置反推，
并校验 go.mod 的 module 是 homeagent-sdk），落空才回退 store。

## 判据 9 条（cmd_skill_test.go）

覆盖：目标无重复/不逃出 home、**真实仓库**里 skills/ 的布局合规、
隐藏目录与普通文件不算 skill、幂等、覆盖用户修改、跳过未知目标、
真实入口 `cmdSkillInstall` 覆盖用户修改、未知 skill 名不静默。

### 写判据时踩的三个坑

1. **`TestSkillSourceHasValidLayout` 原用 `t.TempDir()`** ⇒ 那个目录是空的，
   判据永远红，且红得毫无意义（"文件不存在"是真的，但真实文件在 SDK 仓里）。
   改为指向**真实仓库**。
2. **fixture 造错**：我 `MkdirAll` 出一个叫 `README.md` 的**目录**，
   于是实现"正确地"把它当 skill，判据却报「把 README.md 当成了 skill」。
   是 fixture 错，不是实现错。
3. ★ **`TestSkillInstallOverwritesUserEdit` 只验 `copyDir`、没走真实入口**
   ⇒ 我把 `cmdSkillInstall` 里的 copyDir 换成「已存在就跳过」，
   **判据依然全绿**。变异测试抓出来的。补 `TestCmdSkillInstallOverwritesUserEdit`
   走真实入口后，变异立刻变红。

## 实测

删掉三处 skill 后 `hmapdev skill install` 一条命令装回四处，
四处 md5 与源一致，二次安装结果不变（幂等）。

## 门禁

- `go test ./...`（hmapdev 独立 module）：ok，0 FAIL
- `go build ./...`：ok
- 9 条判据全通过，变异测试确认能抓回归
 2026-09-28 11:23:58 +08:00
JianFeeeee
82e8d9dbac docs: 补两篇指南 —— 工具并发声明、流式多 tool_call 
`ParallelSafe` / `Serial` / `stream_index` 三个新能力此前**零文档**：
README 提到 `Serial` 的那处是 UART 串口，与并发声明无关。插件作者只能
读源码注释才能知道这些字段存在及其优先级。

## docs/guide/parallel-tool-declaration.md

- 保守 opt-in 的理由：存量插件不改一行就得串行，不会被升级意外并发
- 声明 `ParallelSafe` 的三个条件（线程安全 / 不争抢资源 / 顺序无关）
- `Serial` 存在的意义：让"我确认过**必须**串行"与"我没想过"可区分
- **`Serial` 胜出**，不允许被 `ParallelSafe` 或默认值覆盖
- 声明字段放在 `ToolDef` 末尾，遵循既有 `NoMemory` 风格
- 压测效果 N=2/4/8 → 1.41×/2.22×/3.88×，并附"必须同时统计实际执行数"
  的理由（旧适配器耗时更短但实际处理 0 个工具）

## docs/guide/stream-tool-call-index.md

面向写 Lua 适配器的人：

- 上游 `index` 字段的用途：分桶累积 `id`/`name`/`arguments`
- **键名是 `stream_index` 不是 `index`** —— 写错会被 Go 解码器静默丢弃
- 不透传的实际后果：name 互相覆盖、args 碎片混拼、工具被当空参数调用
- 顺带记两个易踩点：不能按 name 过滤分片；扁平结构的协议族同样要带
- 自检命令；并注明 `gemini.lua` 不涉及（协议是 `functionCall`）

## 其它

- `mkdocs.yml` nav 登记两篇 —— 之前它们会被 mkdocs 明确警告
  "not included in the nav configuration"，等于在站点里不可达
- 重跑 `tools/apidoc/build.sh` 同步 `docs/api/*`、`llms.txt`（生成物）

核实过的事实，避免臆造：
- 内置工具声明是**核心仓**的 `toolDefOptions`/`parallelOpts()`
  （`internal/agent/core/tooldefs.go`），不是 `sdk.BuiltinToolDef` —— 初稿写错
- `gemini.lua` 对 `functionCall|tool_calls` 匹配数为 0，确认无流式实现
- `server/kimicode/anthropic/ollama` 四个适配器确有 `stream_index`（2~5 处）
- 跨仓相对链接不可解析，故改为纯文本路径指路

`docs/api/tools.md` 属生成物（首行注明"请勿手改"），其 `ToolDef` 签名被截断、
不展示字段 —— 这是生成器既有行为，本次 diff 只是行号漂移，未改它。
 2026-09-27 22:25:38 +08:00
JianFeeeee
1b8218afa9 fix(tools): 审计器补齐 recv/selfCalls 索引与只读白名单；标注器定位修正 
## audit_parallel 的四个误判来源

**① indexMethods 没设 recv 和 selfCalls ⇒ 递归跟进空转**
`scanWritesDeep` 靠 recv 组候选键、靠 selfCalls 才知道跟进谁，缺任一个
就静默漏判。handleRestart 只调 p.stopServer/startServer 两个方法，
因此被判成"只读" —— 而 stopServer 里有 `p.server = nil`。
（我先补了闭包那条分支的 selfCalls，误以为问题在闭包上，其实是
 indexMethods 整体缺字段。）

**② writePatterns 写了 ".Set(" 而 callString 收集的是方法名**
`p.sdk.Settings().Set(...)` 是三段链，callString 返回 "Settings.Set"，
永远匹配不上 ".Set("。漏判比误判更难发现：结果看着仍然合理。
→ 模式改为不带括号。

**③ looksLikeExternal 用黑名单 ⇒ 纯读标准库调用全被判"可能写"**
Marshal / ReadAll / NewRequest / NewReader 都不带写操作迹象，却被判写，
120 个工具里 119 个判成 SERIAL —— 等于工具没在工作，却**看上去在工作**
（保守方向不会引起怀疑）。
→ 改为 knownReadOnlyCalls 白名单。判定原则：**默认怀疑，明确信任** ——
   写不动的东西要逐个列出来。

**④ 工具名提取打印 AST 内部结构**
`fmt.Sprintf("%v", a.Y)` 输出 `tp&{10500 10515 STRING "manage_social"}`，
名字里混着指针地址，人没法核对。
→ 改用 BasicLit.Value + 归一化去掉运行期前缀。

## annotate_parallel 的插入点定位

改文本匹配改结构体字面量这条路走了三次弯：
- 正则找"最后一个顶层字段"被嵌套 map 里的同形文本骗到，823 处重排改坏文件
- 变量前缀匹配没要求 RegisterTool( 在**同一行**，命中函数体里散落的字面量，
  起点错到 switch case 中间，报错指向一处看起来完全无辜的分支
- 只按行末**净**深度判断：Parameters 写在单行时（进出同一行，净变化 0）
  永远察觉不到曾进入深度 3，追踪一路跑到 1305 行才"收敛"
→ 最终按**行内峰值深度** + 记录进入深度 3 的行号判定。

## 幂等

未标注过的工具重复跑会插入第二份 ParallelSafe（duplicate field 编译错误）。
→ 加 blockHasDecl 预检。
 2026-09-27 16:17:04 +08:00
JianFeeeee
deeda22650 tools: 工具并发安全审计器（audit_parallel + annotate_parallel） 
两个工具，都是为了让「这个工具能不能并发」有**可复现的依据**，而不是靠人眼扫。

## tools/audit_parallel.go —— 审计

为什么需要它：正则扫 `ToolDef` 字面量**不可靠**。用它审计主仓 27 个工具时，
把 `config_set` 判成"无共享写"，而它的 handler 其实在 `p.handleSet` 里且无锁 ——
原因：RegisterTool 第三个参数是方法名/闭包，正则看不到执行体。

本工具用 go/ast 从**注册点跟进到 handler 实现**，递归 3 层（带环检测），
输出三态：SAFE / SERIAL / UNKNOWN。
★ UNKNOWN 一律不声明并发安全 —— 追不到实现就不能声称安全。

### 开发它时踩的坑（都写在代码注释里）

- **通用 HTTP 包装器**：vanblog 的 manage_social / manage_settings 全走
  `p.do("GET"|"POST"|"PUT", ...)`，方法名毫无写操作迹象，纯靠名字匹配
  **全判成 SAFE** —— 而它们明确含 POST/PUT。审计工具给出与代码相反的结论，
  比不给结论更危险（人会信它）。改为按 HTTP 动词判定后，
  统计从 72/37 变为 46/63。
- **链式调用丢方法**：`p.sdk.Settings().Set(...)` 是三段链，只看最外层只得到
  "Settings"，`.Set` 整个丢失 ⇒ handleConfigure（写配置 + 启停服务）被判只读。
  改为收集整条链的所有方法名。
- **变量名 ≠ 类型名**：调用点写 `p.handleRead()`，定义处是
  `func (p *Plugin) handleRead()`。拿变量名去查类型索引**永远匹配不上**，
  143 个工具全报 UNKNOWN。须建"变量名 → 接收者类型"索引。
- **方法接收者不是局部变量**：example 里根本没有 `p := &Plugin{}`，
  p 是 Start 的接收者，局部变量索引全空。须把接收者变量名也纳入索引。
- **枚举被字符串污染**：verdict = "Serial:true" 而 report 只认三个枚举值
  ⇒ 全部落进 UNKNOWN，输出"共 13：UNKNOWN 13"，看着像工具没在工作。
- **作者声明必须优先**：我把"已声明"当 finding 记录后照常跑写入检测并
  **覆盖** verdict，于是 plugin_install（已标 Serial:true）被判 SAFE。

## tools/annotate_parallel/ —— 标注

按 SDK 风格插入声明项：Name 在首位，声明项在末尾（Parameters 之后、
handler 之前），不打散 gofmt 对齐。

插入点必须用**括号深度 + 记录进入深度 3 的行号**定位：
- `RegisterTool( =1, ToolDef{ =2, Parameters{ =3`
- 只判 depth==2 会在 `Name:` 行就返回（那行本来就是深度 2），
  插入点跑到 RegisterTool 之前，编译报 "expected 1 expression"
- 空 `properties: map[string]interface{}{}` 让深度**在同一行**进出平衡，
  所以"曾触及深度 3"也不能作门控，必须记行号
- 试过用正则找"最后一个顶层字段"，被嵌套 map 里的同形文本骗到，
  823 处错误重排把文件改坏 —— 文本匹配改结构体字面量就是这条路

用法：go build -o /tmp/annotate ./tools/annotate_parallel
     /tmp/annotate <file> <tool:parallel|serial:说明> ...
 2026-09-27 16:17:04 +08:00
JianFeeeee
1d7c330cfc fix(hmapdev): mocksdk 补齐 ToolDef 声明项，并加字段/类型一致性判据 
## 问题

mocksdk（yaegi 解释执行时的替身 SDK）的 ToolDef 只有 6 个字段，
公共 SDK 已有 10 个 —— 缺 RecallPolicy / ParallelSafe / Serial。

★ 危害不在编译期，而在**调试期**：插件作者用 hmapdev 在本地解释执行时，
写了 ParallelSafe:true 照常跑、不报错；直到编译安装后才发现声明根本没
被内核读到。这类不一致不会让任何现有测试失败。

这正是"黑名单不会自动跟上新执行能力"的又一次复现：主 SDK 每加一个声明项，
替身不会自动跟上。

## 修复

① mocksdk/plugin.go 补齐 RecallPolicy / ParallelSafe / Serial 三个字段，
   注释写明"主 SDK 先加、mocksdk 没跟上"这段历史，避免后人再漂移。

② 新增 yaegi/mocksdk/parity_test.go：
   - TestMockSDKToolDefMatchesSDK  比对**字段名**集合，双向都查
     （少字段 = 声明静默失效；多字段 = 替身比本体还多，必有一方理解错了）
   - TestMockSDKToolDefTypesMatch 比对**字段类型**，逐个断言
     ★ 归一化必须抹掉所有空白：gofmt 打印 "interface{}" 而反射给
       "interface {}"，这是打印格式差异。我第一版没抹空白，
       结果每个复合类型都被误报成"类型不符" —— 判据自己制造假警报。

判据放在 tools/hmapdev 模块内（它是独立 module，主模块不包含它），
跑法：cd tools/hmapdev && go test ./yaegi/mocksdk/
 2026-09-27 16:17:04 +08:00
JianFeeeee
bd73a9b241 feat(sdk): 通用反代声明项（DeclareProxy）+ ToolDef.Serial 串行标记 + 场面策略文档 
本次一并提交工作区此前累积的改动（均已验证），并接入工具并发调度所需的
声明项。

把「谁来反代谁」从内核硬编码变成插件可声明。设备网关（remotedevice）
这类**编译进内核、没有独立插件目录与 plugin.json** 的服务，静态扫描扫不到，
此前只能靠约定。新增 DeclareProxy 让它们能自己声明反代路由。

ParallelSafe 的**反向**声明项。判据优先级：Serial 胜出，显式声明不允许被
ParallelSafe 或任何默认值覆盖。

为什么需要它：ParallelSafe 零值 false 已表达「安全/串行」，插件无法区分
「我没想过」和「我确认过必须串行」。没有这个区分，工具作者只能靠命名约定
传递意图，那不是契约。

ParallelSafe 本身也补齐了注释，明确其零值语义（默认串行、保守）与理由
（新语义下并发会改变工具的行为前提，让存量插件意外并发比慢一点危险得多）。

配套 ScenePolicy 声明项的使用说明。

remotedevice/ 整目录（C 实现的设备网关，已由 Go 侧 DeclareProxy 路径取代）。

- sdk/knowledge.go：随场面策略配套调整
- docs/api/*、docs/assets/api-index.json、docs/llms.txt、mkdocs.yml：
  由 tools/apidoc/build.sh 从源码重新生成（行号随 plugin.go 变动漂移）
 2026-09-27 16:17:04 +08:00
dev
e417c69fc8 fix(example/bili): 进程组隔离 + 可取消的下载 —— 修拖死内核关停 
## 现象

线上关停必超时：systemd 报 `State 'stop-sigterm' timed out. Killing.`，
其中只有 bili 报 `[proc] bili SIGKILL 后 2s 仍未被收割`，之后近 90 秒无日志。

## 根因

本插件用 `exec.Command("yt-dlp", ...)` + `cmd.Run()`：
- 无 CommandContext ⇒ Stop 无法取消
- 无 Setpgid      ⇒ yt-dlp 与本插件同进程组
- Stop() 是 `return nil` ⇒ 内核 Kill 插件本体时，yt-dlp 变孤儿

yt-dlp 还会再 fork ffmpeg，**孙进程继承本插件的 stdout 管道写端**。
插件被 SIGKILL 后孙进程仍持有写端 ⇒ 内核 readLoop 永远等不到 EOF
⇒ `Kill()` 末尾的 readerWG.Wait 永不返回 ⇒ 整个关停挂死。

## 改法

1. 两处 `exec.Command` → `exec.CommandContext`，Stop 里 cancel 能掐掉
2. `setPgid` 让命令自成进程组：yt-dlp 拉起的 ffmpeg 也在组内，
   kill(-pgid) 能一次带走整棵子进程树，不留孤儿
3. `Stop()` 不再是空实现：cancel 之后**必须 wait**。
   只 cancel 不 wait 的话内核会先释放共享段，而 yt-dlp 还在写 stdout ——
   那正是内核 readLoop 挂死的成因。`runWG` 等它真正退出。

顺带：取消时返回明确文案（"已取消（插件停止）"）而不是含糊的 exec 错误。

内核侧的三处修法（Setpgid / 杀进程组 / readerWG 超时）在主仓 ceeef0b，
对所有 8 个同样 exec.Command 且无进程组隔离的插件都有效。

验证：hmapdev build 通过；主仓部署后实测关停 90s → 1s、
`[homed] stopped` 打出、孙进程无残留。
 2026-09-26 17:08:34 +08:00
JianFeeeee
a176cc3e20 feat(sdk): 反代声明（ProxyDef / RegisterProxy）—— 插件声明服务，HomeAgent 反代出去 
配套核心仓「webui 通用反向代理」。SDK 1.4.0 尚未发布，接口未冻结，
本次按开发期自由变更处理（正式发版时并入版本号推进）。

## 声明契约

plugin.json 的 proxies 字段（声明式，静态可发现）或 RegisterProxy
（运行期，供没有 plugin.json 的内置插件用）：

    {"name":"ui","host":"myapp","path":"/p/myapp","strip_path":true,
     "target":"127.0.0.1:12100","auth":"homeagent"}

命名与既有能力对齐（ToolDef / ChannelDef / ConfigDef / RegisterTool /
ToolRegistrar）——第一版写成 ProxyDecl / DeclareProxy / ProxyDeclarer
被评审指出「跟 SDK 其他接口不是一个风格」，已全面改名。

## strip_path：Path 的两种语义

Path 不能一刀切成「原样保留」，真实需求有两种且**不能自动判定**
（同一个 path 在两种语义下都说得通，猜错即全部 404 且像上游故障）：

  strip_path 缺省/false（别名模式）—— path 是上游真实路径的一部分
    /api/v1/device/ws + path=/api/v1/device → 上游收到原样
    适用：客户端**已硬编码**路径的机器接口（设备网关即如此）

  strip_path=true（前缀模式）—— path 只是门户上的挂载点
    /p/myapp/api/status + path=/p/myapp → 上游收到 /api/status
    适用：自带 UI 的服务（前端用相对路径）

非法组合（strip_path 而无 path）被 ValidateProxyDef 挡住。

## 单一入口原则（契约级要求）

一个声明 = 一个入口。两种挂载形态对「根路径」处理截然不同：
Host 形态下根路径是插件的根（fetch('/api/x') 天然正确）；
Path 形态下根路径**属于门户**，同样代码会打到门户自己身上
（静默错路由：页面能开、功能全坏）。

故被反代的插件必须**一律使用相对路径**，绝不硬编码以 / 开头的绝对路径。
这样同一份前端在两种形态下都正确，插件不必知道自己被挂在哪，
反代层也能按外部条件（子域是否有证书/放行）自由选择形态。

## 判据

sdk/proxy_test.go：两种语义的映射、非法组合、单一入口原则的契约存在性。
hmapdev proxy_config_test.go：schema 漂移保护（新增字段忘了同步就判红）、
非法声明在**打包时**就被拒（不必装到 HomeAgent 才看到）。

两模块 go test 全绿；文档站已重新生成（ProxyDef 与单一入口原则进入
docs/api/misc.md 与 llms-full.txt）。

## 顺带修回的一处（此前随工作树丢失）

writePluginJSON 漏写 proxies 键 —— 漏写的话插件装得上、启动正常、
就是不出现，没有任何报错。该 bug 曾在核心仓侧出现过（判据抓到过），
这次移植时由 TestWritePluginJSONPreservesProxies 再次判红并修复。
 2026-09-26 14:08:30 +08:00
JianFeeeee
255d6479ad feat(docs): 换品牌图标 + 补备案号 + 给 agent 的直读入口 
三件事，都是「站点上线后看出来的」问题。

## ① 图标用的是 Material 默认，不是我们的

站上 favicon 是 mkdocs-material 自带的那张（`assets/images/favicon.png`），
与主站 introduce 不一致。改为引入主站同一份 logo：

- `docs/assets/logo.svg` —— 原样（浅色底，适合 favicon）
- `docs/assets/logo-mark.svg` —— 去掉底色矩形（否则在靛蓝页头上是个白方块）

`theme.favicon` / `theme.logo` 分别指向它们。实测子页面路径也正确
（mkdocs 生成 `../../assets/logo.svg`，不是错误的相对路径）。

## ② 缺备案号

`introduce` 底部有 ICP + 公安备案，文档站没有。Material 的 footer 只渲染
`config.copyright` 一个字符串，塞不进「两条带链接的备案」——所以覆盖了
`overrides/partials/footer.html`（`theme.custom_dir`），并顺带把许可也写进底部，
读者在任何一页都能看到，不必翻到首页。

## ③ 没有给 agent 的入口

站点是给人看的（HTML + 主题 + JS 搜索），但越来越多读者是 agent。让它们爬
HTML 既浪费 token（样板占大头）又容易漏内容。

新增 `tools/apidoc/gensite/agent.go`，随构建产出：

| 路径 | 内容 |
|---|---|
| `/llms.txt` | 站点目录：每页一行，带 URL 与一句话说明（4.3KB）|
| `/llms-full.txt` | 全部文档正文拼成一份，可一次读完（115KB）|
| `/<page>.md` | 每个页面的 Markdown 原文，含生成的 API 页（text/markdown）|

沿用 llms.txt 社区约定：`llms.txt` 读目录、`llms-full.txt` 一次读全。

**一个必须处理的坑**：mkdocs 只把 `.md` **渲染**成 HTML，不会把 Markdown
放进产物目录 —— 那样 `llms.txt` 里的链接会全部 404。所以 `build.sh` 增加了
第 4 步 `copy_agent_files`，在构建后把 23 个 Markdown 复制进 `site_build/`。

`docs/llms-full.txt` 已 gitignore：它是派生件，改任何一页都会整份重写，
进版本库只产生噪声（`llms.txt` 索引小且稳定，仍提交）。

验证：`mkdocs build --strict` 零告警；favicon/logo 可取（200，naturalWidth=400）；
三页底部均含两个备案号；4 个 agent 入口均可访问且 content-type 正确。
 2026-09-24 13:27:58 +08:00
JianFeeeee
9b6abe1b73 fix(docs): 中文搜不到英文注释的 API —— 补关键词层 
## 问题（实测）

SDK 里 100 个有摘要的符号中 **66 个是英文注释**，例如：

    RegisterTool registers a tool that the LLM can call.

于是搜「注册工具」——中文受众最自然的问法——**RegisterTool 得分 0，一条都搜不到**。
更糟的是逐字匹配把噪声顶上来了：搜「注册工具」返回 24 条，排第一的是
`SetToolBlocks`（描述里有「工具」二字），`RegisterTool` 根本不在列表里。

## 修法

不改源码注释（那会让代码与文档脱节），而是在检索索引上加一层**人工标注的
中文功能词**：`tools/apidoc/keywords.json`。

- `rules`：按符号名前缀/子串批量覆盖（`Register*` 全带「注册」，`*Memory*` 带「记忆」）
- `symbols`：逐符号补充（重点 API、或规则覆盖不到的）

词只进 `api-index.json` 的 `g` 字段，**不影响页面展示**；检索结果里会显示
（「为何命中」），读者能理解排序依据。

同时把中文逐字匹配从主信号降为**弱信号**（要求 60% 以上字符命中）——
它正是噪声来源：凡是含「工具」二字的说明都会被「注册工具」匹上。

## 结果

| 查询 | 修改前 | 修改后 |
|---|---|---|
| 注册工具 | 24 条，RegisterTool 缺席 | **7 条，RegisterTool 第一** |
| 崩溃 | 1 条 | 2 条（SetAutoRestart + AutoRestart）|
| InjectText | 7 条（含重复）| 6 条 |
| memory.recall | 1 条 | 1 条（不变）|

顺带修掉索引重复：接口会同时作为 `type` 符号与接口本身被加两次
（`MemoryAPI` 等 11 个各重复一条）。现在接口只走接口那条路径，索引 200 → 189 条。

keywords.json 是**可选**的：读不到只警告不中断，检索退化为原行为。
 2026-09-24 13:00:32 +08:00
JianFeeeee
0a6e2b7dc4 docs: 插件 SDK 文档站（API 参考从源码生成 + 自建检索） 
为插件作者建一个文档站，重点是**能按描述搜到 API**，以及**明确能力边界**。

## 为什么 API 参考要生成而不是手写

公开 API 面有 115 个符号、11 个接口。手抄必然与代码漂移——这是文档站最常见的
死法（本仓 README 里已经有过几处「文档说一套、代码是另一套」）。

所以 `tools/apidoc` 直接从 `sdk/*.go` 提取签名、文档注释与代码块示例，渲染成
`docs/api/*.md`。发现文档不对时改的是**源码注释**，不是生成物。生成页首行带
「勿手改」标记，防止有人改了下次构建白改。

- `extract.go`：go/ast + go/doc 提取（只用标准库，离线可跑，不引入依赖）
- `gensite/`：渲染 Markdown + 检索索引
- `gensite/usages.go`：从 `example/` 21 个示例插件里反查**真实调用点**，
  贴在每个 API 下（源码注释里几乎没有可运行示例，但示例插件都是能编译跑的真代码）

## 能力边界：写这个站时查出的三处文档错误

这是本次最有价值的部分。原以为「公开 SDK 里有的 API 外部插件都能用」，
实测对照桥接模板后发现三处不符，站内已更正：

1. **`PluginMgr()` 被写成「仅内置可用」——错的。** 桥接模板第 692 行显式
   `base.SetPluginMgrAPI(procPluginMgr{})`，公开 `PluginMgrAPI` 注释也写「外部插件可调用」。
   真正的区别是**方法数**：公开面 3 个（ReloadOne/ListLoadedPlugins/IsPluginDisabled），
   内部面 9 个。容易混淆是因为两个包里有同名但不同的接口。
2. **`Events()` 外部插件恒为 nil。** `SetEventSubscriber` 全仓只有定义、无调用点，
   故 subscriber 从未被注入。外部插件的事件订阅实际由生成的运行时走
   `events.subscribe` RPC 完成——旧文档把它当成可用入口，会让人写出必然失效的代码。
3. **`UnregisterOutputChannel` 是静默无效，不是报错。** 桥接只注入 registrar、
   不注入 unregistrar，于是 `regOutputUnreg == nil`，函数命中 else 分支**直接返回 nil**
   （sdk/plugin.go:539-549）——不报错、通道也没注销。

每条裁定的依据写进 `tools/apidoc/tiers.json`（文件:行号 或 grep 结论），
站上以告警框呈现，读者可自行核对。判断依据三源：桥接模板的 `base.Set*` 注入点、
`internal/sdk` 完整面、`internal/plugin/proc/protocol.go` 的 RPC 表。

## 检索（用户的核心诉求）

两套互补：

- **MkDocs 内置搜索**：全文，中文走 jieba 分词。
- **自建 API 检索**（`docs/javascripts/api-search.js` + `assets/api-index.json`）：
  支持四类查询——按名称、**按功能描述**（「注册工具」→ RegisterTool、
  「崩溃」→ SetAutoRestart）、按 `限定符.方法`（`memory.recall` → MemoryAPI.Recall）、
  按签名片段（`(string) error`）。并标出「仅内置」，避免外部插件作者踩空。

自建的理由：Material 内置搜索按整页文本索引，搜 `InjectText` 会列出所有提到它的
页面，但分不清哪条是它的定义；而且它要等 mkdocs build 才更新。

## 文档结构

- `docs/guide/`：快速开始、Go/Lua 首个插件、能力边界、打包发布、多平台、受限 SDK 与安全
- `docs/api/`：10 个按「你想做什么」划分的章节（工具/阶段/记忆/通道/配置/生命周期/
  事件/LLM/常量/桥接）+ 仅内置汇总页
- `docs/versions.md`：SDK 版本语义（跟随内核中版本、patch 恒为 .0）、
  1.0.0 是唯一破坏性变更、RPC 协议版本

## 验证

- `mkdocs build --strict` 零告警
- 23 个页面的全部站内链接与锚点可达（自动校验）
- 1440 / 768 / 390px 三视口：无横向溢出、无控制台错误
- 四种检索模式实测有结果且跳转锚点正确
- 构建产物 `site_build/` 已 gitignore

用法：`tools/apidoc/build.sh`（生成+构建）、`tools/apidoc/build.sh serve`（预览）。
 2026-09-24 12:08:37 +08:00
JianFeeeee
e97cafc8de license: SDK 改用 MIT —— 让第三方插件不被 AGPL 传染 
原 LICENSE 是 2026-09-12（93ab794）引入的 AGPL-3.0-only 全文，README 据此
声明「插件静态链接 SDK，故必须以相同许可发布，闭源只能另取商业授权」。
这堵死了闭源插件，与第三方插件生态的目标相反。

## 为什么 MIT 才自洽

SDK 会随插件一起静态链接（源码进入插件二进制）。用传染许可，插件作者就被
强制开源；用 MIT，插件作者可自由选择许可（闭源 / 商业 / 私有均可），无需
回馈、无需任何例外或商业授权。这是刻意的宽松，也是插件生态安全的基础。

MIT 在这里**不会与任何许可冲突**：SDK 完全自包含 —— go.mod 零外部依赖，
sdk/ 只 import Go 标准库（sync），不引用核心仓任何代码（已实测确认）。

## 改动

- LICENSE：AGPL-3.0-only 全文（661 行）→ MIT 正文（21 行，版权人 JianFeeeee）
- README.md / README_EN.md：许可章节重写，把「必须同许可」改为「可自选许可」，
  并写明自包含这一前提

内核仓仍为 AGPL-3.0-only（其 README 的对应论述与本提交同批更新）。

验证：go build ./sdk/... ./meta/... 通过。
 2026-09-24 10:55:17 +08:00
JianFeeeee
5af2a86816 docs(sdk): 补全自动重启的真实约束（退避 / 上限 / 非无感） 
原文只说「插件崩溃时平台自动拉起，保障服务可用性」，读起来像
无感瞬时恢复。实测与源码都不是这样：

## 补齐的默认参数（内核 internal/plugin/registry.go）

| 参数 | 值 | 含义 |
|---|---|---|
| procRestartBackoff | 1s | 第 n 次重启前等 n × 1s（线性退避） |
| procMaxRestarts | 3 | 窗口内重启次数上限 |
| procCrashWindow | 5min | 窗口内无新崩溃则计数归零 |

即实际序列 1s → 2s → 3s；同一 5 分钟窗口内第 4 次崩溃（n > 3）不再
自动拉起，交人工介入。首次重启就要等 1s，期间该插件的工具是缺席的、
调用会报错 —— 需要秒级就位的插件应在 OnStart 里自建重连与状态重建。

## 顺带改准一处混淆

`SetAutoRestart` 的文档写「崩溃后自动重载」—— 把「重启」说成了
「重载」。重载是换 plugin.bin 后重新加载那条路径（ReloadOne），
与崩溃自愈不是一回事。已在文档里写清，并附上退避与上限。

这个混淆与内核侧 HEAD 修正的 README/官网是同一处（源码注释里
「足够快到用户感知不到工具缺席」也是同一类无实测支撑的主观断言，
已在主仓同批改掉）。

中英双版同步更新。
 2026-09-21 10:34:27 +08:00
JianFeeeee
7717bf5ca5 feat(sdk): RecallPolicy —— 声明工具输出是否触发记忆召回 
与 ContextPolicy **正交**，但默认值刻意相反：

| | 管什么 | 默认 |
|---|---|---|
| ContextPolicy | **裁剪**：把低相关 L0 事件归档 | 关（剪裁是破坏性的，须显式声明） |
| RecallPolicy | **召回**：把 L2/L3 相关记忆注入本轮 | 输入/注入 `auto`，**工具 `none`** |

工具默认 none 的理由：多数工具输出是噪声，据它召回会把无关记忆拉进来
（源码注释原文）。需要「取回真实内容后据它召回」的工具才显式声明 auto。

## qq 的落地（本改动想解决的具体问题）

qq 通道到达的是**中断通知（meta）**而不是用户正文。原先用这条 meta 文本
去触发召回 —— 那是无关词，召不回真正相关的东西。改为：

- 通道声明 `RecallPolicy: none`（meta 不该据它召回）
- `qq_get_message` 声明 `auto`：消息正文取回后**由正文**触发召回
- `qq_get_history` 同样 `auto` + `prune`：拉回的历史消息既用完即裁、
  又据正文召回（否则有「记忆里有、但拉历史时不注入」的盲区）

注：本实现已先随主仓 vendored 副本进入 main（两份经 diff 校验字节一致，
0 行差异），此处是把 SDK 仓自身补齐，使两仓 HEAD 对齐。
 2026-09-20 09:15:34 +08:00
JianFeeeee
db207fd9b7 fix(scripts): 默认产物目录落到内核仓 dist/plugins 
原默认 `$SDK_DIR/../dist/plugins`，在 SDK 仓位于 third_party/homeagent-sdk 时
会解析成 **third_party/dist/plugins** —— 既不在内核仓的发布产物目录
（upload_assets.py 认 dist/release 那套），也不在 SDK 仓内，等于丢在夹缝里，
必须每次显式传 OUT 才不会错。

改为向上找「含 go.mod 与 internal/ 的目录」即内核仓根，取其 dist/plugins。
不在内核仓内（SDK 被单独 clone）时回退到 SDK 仓自己的 dist/plugins。

不写死 ../../ 的理由：SDK 仓既可作 submodule 位于主仓内，也可被单独 clone，
写死相对路径会把产物丢到仓外。
 2026-09-20 09:07:22 +08:00
JianFeeeee
953fbb2f50 feat(scripts): 批量打插件包（.hmap）供 release 发布 
## 问题

release 此前**只发 homed/waiter 二进制与 hmapdev 工具链，不发插件包**（主仓 20 个
release、本仓的 release 都核实过，0 个 .hmap）。用户要用任何一个插件，都得：

1. 装 Go 1.25 + 网络拉依赖
2. 装 hmapdev 工具链
3. 进 example/<插件>/ 逐个 `hmapdev build`

而 `hmapdev build` **不是可选项**：5 个 example（deepsearch / luademo / vanblog /
vikunja / weather）连 `main.go` 都没有，直接 `go build` 会死在
「function main is undeclared in the main package」——入口是 hmapdev 现生成的。

所以「开箱可用」名不副实。本脚本把这一步前置到发布流程里。

## 用法

```bash
./scripts/build_plugin_bundles.sh                # 全部 21 个
./scripts/build_plugin_bundles.sh weather qq     # 指定
OUT=../dist/plugins ./scripts/build_plugin_bundles.sh
```

产出 `.hmap` + `SHA256SUMS.plugins`，可直接作为 release 附件。

## 实现要点（三处是踩过才写对的）

1. **产物有三种形态**，不能只认 `_bundle.hmap`：
   - `<name>_bundle.hmap` 多平台 bundle（`plg.json` 的 `bundle: true`）
   - `<name>_<os>_<arch>.hmap` 单平台（**qq** 的 plg.json 是 `bundle: false`，
     与其余 20 个不一致）
   - `<name>_lua.hmap` Lua 插件（**luademo**，不编译 Go）
   脚本按形态标注，发布时能一眼看出是哪种。

2. **`set -e` 下不能用 `[ -z "$x" ] && x=$(ls ...)` 做兜底**：
   一次 `ls` 无匹配（退出码 2）就会让整个子 shell 直接退出，后面的兜底根本走不到。
   实测表现是「只有 qq 和 luademo 失败」——因为正是它俩没有 `_bundle.hmap`。
   改成 `for` 循环 + `|| true`。

3. **参数拼错要报错，不能静默跳过**（否则以为打了实际没打）。

## 验证

- 21/21 构建成功，合计约 150 MB（bundle 含 linux/amd64 + darwin/amd64；
  不含 windows 是**策略**——homed 已放弃 Windows 原生，源码注释有说明）
- 每个包内部结构核对：含 plugin.json、含内核认得的入口、当前平台可得
 2026-09-20 09:02:31 +08:00
JianFeeeee
7ef9bc2ad3 docs(example): 为每个插件补 README 
此前 example/ 下 21 个插件里，13 个完全没有 README，另 4 个是
`hmapdev init` 生成的脚手架样板（`# <name>` + `plugin build` + `Install` 三行，
等于从没被写过）。只有 deepsearch / vikunja / plugindev / luademo 是真实文档。

本次为 **17 个**插件写了真文档（13 个缺失 + 4 个样板），现在 21 个全部有内容。

## 写法

每个 README 覆盖：能力一句话 → 为什么需要 → 工具表 → 配置项表 →
通道与钩子（有才写）→ 构建 → 已知边界。

**事实全部从源码读出来，不推测**：
- 工具名核对到注册点（含 `tp+"x"` / `p.name+"_x"` 前缀拼接，展开成最终名）
- 配置键与默认值取自 `RegisterDef` / getStr 默认值
- 通道名、钩子名、依赖命令逐条 grep 确认
- 版本号与已部署实例交叉核对，17 个里 16 个一致

## 几处按源码写、与直觉不同的点

- **rss**：订阅时会把抓到的历史条目一次性标为 seen，所以订阅一个源
  **不会**把历史文章全推一遍 —— 这是避免刷屏的关键，写进了文档。
- **files**：路径校验是**两道**（规范化后判断 + 解析符号链接后再判断），
  只做前者的话沙箱里的软链接就能逃逸。两种情况报错文案不同。
- **qq**：身份必须**绑帧**而非存插件全局，源码注释记录了由此产生的两个真实故障
  （中断抢占恢复后权限门整体失效、运行中到达的消息改写正在跑那一轮的身份）。
  多来源合并时权限取**交集**。硬私有工具按前缀一律拒绝。这些是安全关键，
  单独成节写清楚。
- **memo**：待办与备忘录**刻意分两类**（一提醒一不提醒），提醒注入带 NoMemory。
- **sanitizer**：不注册任何工具，只挂三个阶段钩子；依赖 ABI v2 的 stage 写回能力。
- **editdoc**：本目录是 v1.0.0（单工具），而线上跑 v2.0.0（全能版，源码未公开）——
  在文档开头显式标注，**不按 v2 描述**，避免读者以为这里就是线上那份。

## 验证

- 21/21 文件非空且非样板（最小 913B，最大 6845B）
- 逐个核对 README 中出现的工具名能在源码找到依据；5 处报警经复核**全是误报**
  （`ai_image_generate`/`music_*` 前缀来自 metadata 的 name，`on_input` 等是钩子不是工具）
- README 版本号 vs 线上 plugin.json：16/17 一致，editdoc 的差异已显式说明

注：本仓既有未提交改动（example/qq/plugin.go、sdk/plugin.go）**未纳入本次提交**。
 2026-09-20 00:43:06 +08:00
JianFeeeee
cfa72df3e9 fix(qq): 权限身份改为绑帧，修中断抢占/运行中到达导致的串权与失效 
问题（都是插件全局 p.auth 一份状态引起）：
- 中断抢占当前轮并把现场压栈，中断轮收尾 afterOutput 清空全局身份；外层
  恢复（resumeTask 复用同帧、不重跑 StageOnInput）后 auth.active=false，
  beforeToolcall 在 !active 处直接返回 —— 该轮剩余工具调用**完全不受门**。
- 运行中到达的新消息会调 activateAuthContext 改写全局身份，把正在跑的那一轮
  换成另一方的身份：换高即越权，换低即误拒。

改法：身份在 StageOnInput 绑定到本帧的 StageContext.Extra 上，beforeToolcall
以帧上身份为准（无绑定时才回退插件全局，兼容单测）。帧随中断栈一起压栈/恢复，
身份自然跟着走。

顺带：合并中断正文里的整批 message_id 现在全部消费（原来只清第一个，其余要等
generation 回收），新增 qqMessageIDsRe 支持 message_id=100,101,102 连写。
新增 4 条测试覆盖：中断恢复、运行中到达、整批 id 消费、非 QQ 轮不受门。
 2026-09-14 16:45:09 +08:00
JianFeeeee
fe1c4cdb09 feat(qq): Bot 所有者消息升到 L2；普通消息保持 L1 
jianf：所有者的话不该被普通人的消息打断/挤到队尾。

- 新增 interruptLevel(owner)：owner → PriorityL2（一般提醒），其余 → PriorityL1（后台）。
  一批里只要有一条来自 owner，整批按 L2 投递。
- 为什么不是 L3：L3 是时钟/终端那类"实时"，QQ 是异步消息，抬到 L3 会打断真正实时的工作。
- 新增测试 TestOwnerMessagesGetHigherInterruptLevel 钉住 owner=L2 / 普通人=L1。
 2026-09-14 16:31:27 +08:00
JianFeeeee
a01fe21ab1 feat(qq): 同一会话连续消息合并为一次中断 + 示例 SDK 指回仓库源码 
需求（jianf）：同一个人连发的数条消息应打包成一次中断，别逐条唤醒 Agent。

- debounce 合并：同一会话 + 同一发送者（群聊按 群号+QQ、私聊按 QQ）在
  batch_window_ms（默认 1500）内的连续消息合成一批，每来一条重置计时；
  整批不超过 batch_max_ms（默认 30000），避免对方持续刷屏时一直不投。
- n>1 时中断说明「短时间连续发来 N 条」并列出 message_id，建议一次
  get_history 拿全上下文；n==1 沿用原文，行为与合并前逐字一致。
- 可配置 batch_window_ms / batch_max_ms，0 = 关闭合并（逐条投递）。
- Stop 时 flush 未到点批次，别把对方消息吞掉。
- 新增 4 条测试（同发送者合并 / 不同发送者不合并 / 窗口 0 逐条 / 单条沿用原文）。

顺带：deepsearch / vikunja 的 go.mod 与 plg.json 此前指向本地安装的 SDK 1.2.0，
导致无法用当前 SDK 重编（缺 InjectOptions.Priority）。改回 ../../ 仓库源码，
与其余示例一致。
 2026-09-14 16:09:45 +08:00
HomeAgent Agent
f09891f054 fix(lua-sdk): 同步注入在 Lua 中明确标记为不可用（避免自锁） 
sdk.inject_input_sync / *_sync_opts / inject_input_media_sync* 要等本轮回复，
而 Lua 代码只在持有插件锁的回调里执行 ⇒ 必然自锁。mock 不再假装返回
(reply,nil)，改为与内核一致的明确错误，避免离线测试误以为可用。
 2026-09-13 21:58:58 +08:00
HomeAgent Agent
efb396d7b3 feat(lua): Lua SDK 全量对齐 1.3.0 + hmapdev 单一 mock 源/版本标记/语法预检 
内核侧 Lua 桥此前停在 v0.8.0 时代能力面，而 1.1/1.2/1.3 新增的
媒体、注入标志位、中断优先级、事件订阅、动态通道注销只在 Go 侧存在，
文档却宣称『能力完全对齐』——属于静默漂移。

本仓（事实源）：
- 新增 sdk/lua/sdk.lua：Lua mock 的单一事实源，补齐全部新 API
  （*_opts / inject_input_sync / inject_*_media / set_tool_blocks /
  unregister_output_channel / events / plugin_mgr / insert_with_media /
  sentence_text+media_digests / attachments / context_policy）。
- scripts/sync-lua-sdk.sh：把事实源同步到 hmapdev assets、luademo、
  以及被 vendored 时的内核副本；三份 sdk.lua 不再各自漂移。
- hmapdev init --lua：优先从激活 SDK 拷权威 mock，内嵌模板降级为
  assets/sdk.lua 回退，不再内联手写副本。
- hmapdev build（Lua）：plugin.json 写入 SDK 版本（能力可追溯），
  打包前用 luac -p / lua loadfile 做语法预检，失败以非零码退出。
- hmapdev debug --lua：优先用激活 SDK 的权威 mock（HMAPDEV_SDK_LUA）。
- luademo 升级为全能力示例（新增 luademo_probe_v2）。
 2026-09-13 19:56:12 +08:00
JianFeeeee
4852d70d77 fix(qq): 输出工具不再受"当前会话身份"限制（修「可信 QQ 会话身份不完整」误拒） 
现场（用户线上，驻留子联调回执原文）：
  被**子的中断**唤醒的一轮里，父 agent 调用 output_send__qq（meta 带齐 user_id）被拒：
  「QQ 权限策略拒绝工具 output_send__qq：可信 QQ 会话身份不完整；请不要改用其他会话 ID 重试」

根因：`sessionToolArgsAllowed` 对**所有**工具都先要求"本轮能精确匹配可信 OneBot 事件"。
`onInputAuthContext` 在来源是 QQ 但匹配不到可信事件时会降权成
`auth = qqAuthContext{active: true}`（无 peer、非 owner）⇒ `currentPeer == 0`
⇒ 连**输出**也一并被拒 ✗。

但输出是 agent 的**主动调用**：发到哪个会话由它自己给的 meta（group_id / user_id）决定，
`handleChannelOutput` 已经强制要求该字段存在（缺了给明确报错）。再要求"当前会话身份"
是多余的门，而且会把合法发送一起挡掉 —— 设计上收到输入后可以往任意（已授权）通道
发任意多次。

改法：`output_send__qq` 在身份判据**之前**直接放行；「只能访问当前会话」这类限制
保留给**读取类**工具（get_history / mark_read / get_message）—— 那才真的不能跨会话读。

判据 `TestDowngradedAuthStillAllowsQQOutput`：
降权态下输出放行、读取类仍被当前会话限制挡住。
扰动验证：去掉放行分支 ⇒ 该判据报出与现场**一字不差**的那句拒绝。
线上实测：CLI 发起的轮次里 output_send__qq 返回 ok，插件日志 handleChannelOutput 确认送达。
 2026-09-13 16:03:24 +08:00
JianFeeeee
63b6eafaf0 docs(sdk): 补 1.3.0 的新增能力与发版口径；main 路牌推到 1.4.0 
用户指出：两个仓库的文档都没跟着更新。本仓的缺口：

1. `README.md` / `README_EN.md` 头部仍写「当前：SDK 1.2.0（需内核 1.2.0+）」，
   版本表停在 1.2.0 —— 1.3.0 的两项新增能力（`InjectOptions.Priority`/`PriorityL1`–`PriorityL4`、
   `UnregisterOutputChannel` 一族）在 README 里**一个字都没有**，而它们正是这一版
   插件作者最需要知道的东西。
2. 发版口径没写清"**SDK 仓不发 patch tag**"：核心 1.3.x 的后续 patch 不伴随 SDK 发版，
   patch 位恒为 `.0`（§七.1）。这条以前只在规范里，README 没提，结果我自己在
   2026-09-13 误发了 `v1.3.1`（已撤回）；`v1.2.1` 是同一类历史遗留。
3. `meta/meta.go` 的版本语义注释还停在「现为 1.2.0：核心的 1.2.x 线正在发布中」，
   与事实相反。1.3.0 既已随核心正式 tag 定版，该号归发布线所有 ⇒ main 推进到 **1.4.0**。

补写内容：1.3.0 能力小节（四级中断优先级、动态输出通道、通道名约束与那起
`device/<id>` 生产事故）、发版口径两段、版本表补 1.3.0 行、meta 注释与路牌。
 2026-09-13 14:40:21 +08:00
JianFeeeee
21221f20c5 feat(example): plugindev 插件 —— 把 hmapdev 工具链封装成 Agent 可调用的工具 
用户要求：把 SDK 的 hmapdev 额外封装为 HomeAgent 插件并装上。

## 为什么

hmapdev 原本是"给人/CI 用"的命令行。做成插件后，Agent 能自己完成
「新建插件 → 构建 → 安装 → 重载」全流程（配合已有的 plugin_install / plgreload）：

  plugindev_init → plugindev_build → plugin_install(path) → plgreload

## 工具面（5 个）

`plugindev_status`（可用性/版本/当前 SDK/工作区，排障首选）、
`plugindev_init`（脚手架，插件名约束 `[a-zA-Z0-9_-]{1,64}`）、
`plugindev_build`（在工程目录构建打包，返回产物路径与下一步提示）、
`plugindev_sdk`（SDK 版本 list/current/path/latest/install/use，`from` 支持本地源码）、
`plugindev_projects`（列出工作区已有工程与产物）。

## 安全边界（实现里落实）

- 只 exec **hmapdev 一个可执行文件**，不做 shell 拼接；
- `plugindev_build` 只接受含 `plg.json` 的目录 —— 这个工具不会变成"对任意目录跑构建"；
- 子进程全部带超时；输出截断（6000 字符，保留首尾）后才返回，避免几百 KB 构建日志灌爆模型上下文；
- 工作区默认落在 `<data_dir>/plugindev`，配置可改。

## 现场验证

已在本机生产装上（`plugin_install` 带 path）：5 个工具注册成功、
启动日志 `[plugindev] 就绪：hmapdev=/usr/local/bin/hmapdev 工作区=/home/newqqagent/plugindev`，
`hmapdev` 已装到 `/usr/local/bin/hmapdev`（版本 1.3.0）。
 2026-09-13 14:16:46 +08:00
JianFeeeee
11303e3ee4 chore(example): a2a 1.3.0→1.3.1、acp 1.2.0→1.2.1（补 RegisterInputChannel 后升 patch） 
上一提交（4cb3a0b）给这两个示例补了显式 `RegisterInputChannel`，但没有升版本号，
于是生产上"重装"出来的包与实际安装版本同名（1.3.0/1.2.0），既不好追溯也没法用版本比较升级。

本次只改版本号（`plg.json` 是仓库里的真源；`plugin.json` 由 `hmapdev build` 从它同步，不入库）。

实测：升级并 reload 后，内核启动日志里这两个插件的"只声明了出站通道"告警消失
（它们此前是真实缺口 —— 部署件是 9-11 的旧构建）。
 2026-09-13 14:09:07 +08:00
JianFeeeee
f4f6968987 docs(sdk): 通道名会拼进 LLM 函数名，写明命名约束（[A-Za-z0-9_-]{1,64}） 
生产事故（v1.3.0 部署后 agent 完全不应答）的根因之一就是这个约束没写清：
远程设备通道名 `device/<id>` 里的 `/` 让 `output_send__device/<id>` 无法通过上游的
函数名校验，上游对**整条请求**回 400（`Invalid 'tools[N].function.name'`），
网关 auto tier 全链条失败，内核只能报"所有 provider 都失败"。

这不是"某个工具不可用"，而是**整个 agent 哑掉** —— 所以这条约束必须出现在
插件作者会看的地方（`RegisterOutputChannel` 文档 + README 的通道一节）：
- 通道名只允许 `[A-Za-z0-9_-]`，且总长要留出 `output_send__`(13) 的余量；
- 名字若来自外部输入（设备自报 id 等），请在插件侧派生合规且唯一的名字。

内核侧**不做**净化/反解：通道名是插件自己的声明，就该由插件遵守契约。
 2026-09-13 13:10:40 +08:00
JianFeeeee
da046b2520 feat(sdk): UnregisterOutputChannel —— 动态输出通道（远程设备）随资源生灭 
背景：输出通道不止有"启动时注册一次"的静态通道。远程设备是动态的：
`device/<id>` 只在设备在线期间存在，设备掉线后必须注销 —— 不注销，
`output_list_channels` 会一直列着死通道，模型会往它发消息并拿到"发送已提交"式假回执。

- 新增 `OutputChannelUnregistrar` 类型 + `UnregisterOutputChannel(name)` +
  `SetOutputChannelUnregistrar`（用 setter 而不是给公开的 `New(...)` 加参数，避免破坏调用方）。
- 与既有 `SetInputChannelRegistrar` 同一套注入模式：内核在装载插件时注入。
v1.3.0 		2026-09-13 12:23:15 +08:00
JianFeeeee
4cb3a0bda4 feat(sdk): 通道方向契约落地 + 模板工程/示例插件显式登记 inputch + 生成器两处修正 
## 背景：内核侧发现的真问题

在真实二进制压力测试里发现：插件只调 `RegisterOutputChannel("cli", ...)`，
却用同一个通道名 `InjectTextSync("cli", ...)` 注入输入 ⇒ 内核 inputch 登记表里
**没有**这个通道，"把 inputch 划给驻留子"直接失败（`划入 inputch cli: inputch 未注册`）。

根因是**契约没有落到插件与 SDK 面上**：inputch 是内核最基本的**输入路由单位**，
"谁会往这个通道注入输入"必须显式声明，而 SDK 文档没说清它与 RegisterOutputChannel
的分工，示例与模板工程也没有示范。

## SDK 面

- `RegisterInputChannel` / `RegisterOutputChannel` 的文档补齐**方向契约**：
  入站（谁会注入）与出站（output_send__<name> 的回复发给谁）是分开登记的两件事；
  凡是用 `InjectText*/InjectInput*/InjectInterrupt*(source, "<name>", ...)` 注入的
  通道名都要 RegisterInputChannel。README 同步补了一段契约说明。

## 示例插件（全部补齐，之前只有 qq/weather 是对的）

`a2a`、`acp`、`browser`、`memo`：注入用 `p.name` ⇒ 登记 `p.name`；
`calendar`、`rss`：注入用字面量通道名 ⇒ 登记同名通道。
（这些插件此前是"能注入、但通道不在登记表里"，与 cli 同类问题。）

## 模板工程（生成器 templates.go）

- `tmplPluginGo`：示范入站+出站两个方向（含 ChannelDef/NoMemory 说明与 `inputch 未注册` 的成因）。
- `tmplMainLua`：同样两个方向（`register_input_channel` / `register_output_channel`）。
- `tmplReadme`：新增 "Channels" 一节（方向对照表 + 兜底告警说明）。
- 实测：`hmapdev init` 生成的 Go/Lua 工程都含通道代码，Go 工程可构建打包出 `.hmap`；
  `--lua` 工程同样生成通道代码。

## 生成器两处修正（都是实测踩出来的）

1. `sdk install --from <dir>`：install 原本只能从 Release 归档下载，而 SDK 开发期的新能力
   （如 proc 桥要透传的 `InjectOptions.Priority`）还没发版 ⇒ 生成的工程必然编译失败
   （`z_proc_gen.go: opts.Priority undefined`）。现在可用本地源码装一个版本并激活。
   实测：`hmapdev sdk install --from <local sdk>` → 装成 v1.3.0 并激活 → 工程构建通过。
2. 构建前置校验 `sdkHasInjectPriority`：proc 桥模板需要 `InjectOptions.Priority`，
   旧 SDK 没有时应给出**可执行**的报错（升级 SDK 或用 `--from`），
   而不是把两条 `opts.Priority undefined` 编译错误甩给用户（那些错误指向生成物，
   完全看不出是 SDK 版本问题）。实测：声明 sdk=1.2.0 的工程构建时正确命中该提示。

## 未决（发布期事项）

`InjectOptions.Priority` 属本特性线新增能力，**已发布的 SDK v1.2.0 不含它**；
发版时 SDK 版本需随之内含该能力（当前源码 meta 已是 1.3.0），否则外部开发者
按文档生成的工程会撞上上面那条守卫。
 2026-09-13 11:37:36 +08:00
JianFeeeee
e50bffa34f fix(deepsearch): 只关自己拉起的 SearXNG；条数改由插件侧截断 
两个都由「真调用/真测试」暴露，且都会让线上搜索表现为「后端不可用」。

一、归属：接管不等于拥有（例：E2E 测试把生产后端带走）
  旧实现只要探活成功就认领关闭责任 → 同机第二个实例（测试拉起的插件、另一个 daemon）
  退出时就 docker compose stop 掉**线上正在用的**后端。实测：跑一次
  `go test ./internal/plugins/ -run TestRealPlugin_DeepSearch`，teardown 即关停
  127.0.0.1:8888，用户看到的就是「搜索后端起不来」。
  修：只有真正执行过 `docker compose up -d` 的实例才算「我们起的」；探到已在运行只接管。

二、条数：SearXNG 不认 count/limit（count/max_results 形同虚设）
  实测 ?count=3、?limit=3、不带参数返回**完全相同的 35 条**，所以截断必须在插件里做。
  旧实现把 count 当 limit 参数发给 SearXNG 就以为生效了 → 模型每次吞 35~58 条带摘要结果，
  还会把「命中 N 条」当成「拿到了 N 条」报给用户（实测发生过）。
  修：新增 limitResults（默认取 max_results，上限 20）；输出改成
  「命中 N 条，返回前 M 条」；不再发无意义的 limit 参数。

验证：22 项单测全过、-race 干净、vet/gofmt 干净；两条归属测试做过扰动（把旧语义放回
去后必红，并如实打出它执行的 `docker compose stop -t 2`）；内核 E2E 三条通过且
**跑完 healthz 仍 200、容器未重启**；线上 1.1.2 实测 count=3 → 「命中 40 条，返回前 3 条」。

版本 1.1.0 → 1.1.2。
 2026-09-13 09:55:27 +08:00
JianFeeeee
934eb4da7d feat(sdk): 导出 PriorityL4 —— 内核级插件的“立即打断”能力 
L4 的归属此前写成“只有内核（panic/selfip）”，这是不完整的：**内核级插件**
（编译期内置插件，如 webui/cli/timer）也需要它来实现中断能力——最典型的例子
就是 WebUI 的终止按钮：用户按下时必须有一条能立刻打断当前任务的中断。

- 新增 `PriorityL4 = "L4"`，注释写明“仅内核级（内置）插件可用”。
- `InjectOptions.Priority` 的注释同步更正：取值 L1..L4，L4 属内核级插件，
  外部插件声明 L4 会被内核夹到 L3。

为什么不能给外部插件：否则任何第三方插件都能随时打断用户的一切工作。
夹取有**两道闸**（纵深防御）：
  1. proc 桥（外部进程唯一入口）一律把 L4 夹到 L3——在这里夹是因为
     `source` 是插件自报字段、可以冒名；
  2. 内核侧再按 `IsBuiltinPlugin(source)` 判一次。
`source` 约定为 `插件名` 或 `插件名/实例`（webui/<deviceID>），判据取第一段。

兼容性：纯追加，零值仍等价于 L1。
 2026-09-13 07:18:03 +08:00
JianFeeeee
4f4a03d368 feat(sdk): InjectOptions.Priority —— 插件声明自己中断的级别（L1-L3） 
内核的输入调度器区分两类别：中断输入（可抢占）与排队输入（可被任何中断打断）。
中断的级别是“这项工作有多不能等”的声明，由插件在注入时给出：

    p.sdk.InjectInterruptTextOpts(src, ch, text, sdk.InjectOptions{
        NoMemory: true,
        Priority: sdk.PriorityL2,   // L1 完全可等 / L2 一般提醒 / L3 需及时
    })

- 新增 `InjectOptions.Priority string` 与 `PriorityL1/L2/L3` 常量（纯追加）。
- 空/非法值一律降级为 L1（默认级）——拼写错误不会被静默当成别的级别。
- **L4 由内核独占**（panic 中断、内核事件中断 selfip），插件声明 L4 会被内核
  夹到 L3，远端常量的取值域里也不提供 L4。
- 排队注入（InjectText*/InjectInputSync*）没有级别：它们本就是“不需及时处理”
  的那一类，可被任何中断打断；传了 Priority 也不会生效。
- 贯通链路：sdk.InjectOptions -> proc RPC 参数（priority）-> 内核 payload；
  tools/hmapdev 模板同步透传（三个注入的 6 个 Opts 变体共用 applyInjectOpts）。
- example/qq 显式声明 L1：QQ 消息既不是时钟那样的实时工作，也不是紧急工作。

兼容性：零值等价于旧行为（L1），既有插件无需改动。
 2026-09-13 07:00:59 +08:00
JianFeeeee
4482235312 fix(vikunja): body 里的 ID 必须是 JSON 数字（建任务/指派在 v2 下必定 422） 
线上真调用暴露：vikunja_task_create 把 project_id 当字符串发出 →
422 validation failed: expected integer at body.project_id。同类的还有指派，
而且 v2 的 assignees **根本不接受 username 字段**（422 unexpected property），
两个分支都是坏的。单测没盖到，因为从未发过真实请求体。

实测（vikunja v2.6.0，2026-09-12）：
  {"project_id":"1"}    → 422 expected integer
  {"user_id":"1"}       → 422 expected integer
  {"username":"jianf"}  → 422 unexpected property
  {"user_id":1}          → 201 ✓
  {"label_id":1}         → 201 ✓（插件本来就 Atoi，无需改）

修法：
- taskBody：project_id 走 parseID（数字）
- 新增 resolveUserID：用户名 → 数字 id，查 GET /users?q=（v1 用 ?s=）；
  **只认精确匹配**，不做「只有一条就用它」的模糊兜底 —— 指派是写别人任务的动作，猜错人更贵
- assigneeBody：v2 只发 {"user_id":N}，不再带 username
- task_assignees remove：路径也用解析后的数字 id

新增 5 项回归测试钉住请求体形状（数字 project_id / user_id、无 username 字段、
数字 ID 不查用户表、移除走数字路径、未知用户给可读错误）。
版本 1.0.0 → 1.0.1。线上复验：create(project_id=1, assignees=jianf) 不再报错、
add→list 显示 jianf、标签 add/remove 正常，测试数据已清理（任务/标签残留 0）。
 2026-09-12 23:43:08 +08:00
JianFeeeee
4cf2df5be6 feat(vikunja): Vikunja 任务管理插件（28 工具） 
token 走 password+Secret 配置项、每次调用前 ensure() 重读（换 token 无需重启）；
v1/v2 差异在插件内处理（建任务 PUT/POST、改任务整对象/PATCH、搜索 ?s=/?q=、
标签对象/{label_id}、TimeEntry 无 seconds 语义）；16 项单测 + 沙盒 homed 实测 28 工具全注册。
 2026-09-12 23:16:33 +08:00
JianFeeeee
ebd700eaf9 fix(browser): browser_search 解析现代 Bing 版式，并把解析失败显式报错 
旧实现三处叠加，模型只拿到「标题=来源行 URL 串、无摘要」，表现为反复换词重搜：
- www.bing.com 对程序化请求常回 302，拿不到结果块 → 改 cn.bing.com
- 块内第一个 <a> 当标题 → 抓到来源行 `deepin.orghttps://www.deepin.org`；改取 h2 > a，
  并解开 /ck/a?...&u=a1<base64url> 跳转包装
- 摘要正则 <div class="b_caption">.*?<p> 对现代版式 0 命中（已迁到 p.b_lineclamp*）
- 分块不再用 (.*?)</li>：块内可能嵌套 <li>（deep links）会在错误位置截断
- 解析不出结果时明确报错，不再伪装成 "No results found."

夹具 testdata/bing_cn.html 为真实 cn.bing.com 响应裁剪；新增 5 项单测。
版本 2.4.0 → 2.4.1（2.4.0 = 交互式 timeout 改必填，此前已提交）。

验证：go test -race 全过、vet/gofmt 干净；线上实测返回真实标题+摘要+规整链接。
 2026-09-12 23:16:23 +08:00
JianFeeeee
7c0b7a1fb0 feat(deepsearch): 联网检索插件 + SearXNG 生命周期托管 
把原 websearch 示例改名为 deepsearch（目录/go.mod/plg.json/工具前缀/README 全量对齐，
工具名 websearch_* → deepsearch_*）。

新增 searxng.go：插件自己托管搜索后端
- 启动探 healthz：已在跑则直接接管（不重启），没跑就 docker compose up -d 并等就绪
- 关闭动作注册为 stop handler（幂等、限时 4s < 内核 5s 宽限期）
- 配置 manage_searxng / searxng_dir / stop_searxng_on_exit
- 崩溃/被 kill 时不关后端（下次启动接管）：安全失败方向
- 可注入 cmdRunner + 时间预算，8 项单测离线覆盖接管/拉起/失败/幂等/保留

契约依据（internal/plugin/proc）：停止插件 = plugin.stop → RunStopHandlers（LIFO、
幂等）→ Stop() → exit(0)，宽限期 5s；stdin 关闭同路径。

验证：19 项单测（18 通过 + 1 联调跳过）、-race 干净、vet/gofmt 干净；内核 E2E 真调用
返回 58 条/37 条、58/58 带摘要；线上 daemon 实测 stop handler 与冷启动（约 3s）。
 2026-09-12 23:16:23 +08:00
JianFeeeee
8c10b7ecc7 feat(browser): 交互式会话的 timeout 改为必填，并补参数校验与测试 
此前 `timeout` 默认 10m：Agent 不传也能开会话，于是"忘记设时长"会静默拿到一个
10 分钟就自己消失的浏览器会话，排查起来像是浏览器不稳。

改为**必填**：
- 新增 `parseBrowserSessionTimeout`（空值 → "timeout is required；创建浏览器会话时必须
  明确指定关闭时长，如 15m 或 2h"；非法或 ≤0 → 明确报错），工具 schema 的
  `required` 加上 `timeout` 并同步描述；
- 缺参时返回可读错误结果（而不是静默套默认值）；
- 新增 `plugin_test.go`（62 行）钉住「不传 timeout 必须报错」等边界；
- 示例版本 2.3.0 → 2.4.0，顺带对齐结构体字段（gofmt）。

验证：`go vet ./...` 干净、`go test ./...` → ok（browser 模块自带 go.mod）。
 2026-09-12 20:17:18 +08:00
JianFeeeee
fcb7490f63 feat(vscode): 插件工程调试扩展（plg.json 诊断 / SDK 版本 / 构建运行 / 内核日志跟随） 
插件的真实形态是「独立子进程 + 内核侧握手」，所以插件问题几乎都在 IDE 之外发生：
编不出来（多半是没声明用哪版 SDK，工具链拿了存储里的 current）、编出来起不来
（产物与内核协议绑定）、起来了行为不对（真因只在内核日志里）。这个扩展把这三件事
拉进 IDE。

- `tools/vscode-hmapdev`：TypeScript 扩展（零运行时依赖，仅 devDeps: typescript + @types/vscode）
  - **plg.json 诊断**：必需字段；`sdk` 必须是完整版本号（区间写法 `1.2` 报错并说明
    「patch 位恒为 .0」，与工具链 ResolveSDKForProject 同一套规矩）；声明的 SDK 未安装时
    直接给 `hmapdev sdk install vX.Y.Z`；
  - **状态栏**：`插件 · SDK <声明> · hmapdev <版本>`，工具链缺失/工程有错时变色，tooltip 列已装 SDK；
  - **命令**：build / build --target all / clean / debug（解释执行）/ 工具链版本 / SDK 列表-安装-切换 /
    跟随内核日志 / 停止跟随 / 刷新；
  - **任务**：同一批动作注册为 `hmapdev` 任务 + Go 问题匹配器（编译错误进 Problems）；
  - **内核日志跟随**：读 `<dataDir>/log` 最新 `homed_*.log`，按插件名过滤持续输出；
  - schema 校验 + plg.json 骨架片段。
- 诚实边界（写进 README）：**不是源码级调试器**——没有断点/单步，没有 DAP 会话；
  做的是构建、运行、看内核日志、清单校验。

验证：`tsc` 零错误；`node --test` 13/13（版本规则、诊断分级、SDK 列表解析、状态栏文本、
以及**反向核对抓到的真缺陷**：`hmapdev 未找到` 这类输出曾被解析成版本号 → 已要求版本
token 以数字开头，否则「工具链不在」会被显示成「工具链 <垃圾词>」并让 SDK 诊断失真）；
与真实工具链输出的集成核对 PASS（`hmapdev version` / `sdk list` 的真输出解析正确）。

README 同时补两节：plg.json 的 `sdk` 字段语义（含「为什么必须有」与「为什么拒区间写法」）、
本扩展的用法与边界。
 2026-09-12 16:07:34 +08:00
JianFeeeee
9206353858 feat(hmapdev): 项目声明 SDK 版本，工具链据此自动选（plg.json 的 sdk 字段） 
此前项目里没有任何「我要哪版 SDK」的声明：go.mod 的 require 是个 Go 模块版本，
而工具链实际用的是存储里的 current——谁改过 current 就拿谁的版本编，出错时
表现为莫名其妙的编译错误（本轮就踩过：存储里只有陈旧的 v0.8.0，模板项目
首次构建报 undefined: sdk.InjectOptions）。

- `plg.json` 新增 `sdk` 字段：本插件针对的 SDK 版本。`hmapdev init` 生成时写入
  **完整版本号**（如 "1.2.0"）。
- `hmapdev build` 按声明的版本在本地 SDK 存储里定位：命中则用它并把 go.mod 的
  require/replace 同步到该版本；未命中则报**可执行**的错误（列出已装版本 +
  `hmapdev sdk install vX.Y.Z`），绝不静默退化成 current。
- **区间写法（"1.2"）被拒绝**并说明规矩：SDK 版本跟随内核中版本、patch 位恒为 .0，
  一条内核线只有一个 SDK 版本（写区间会让人误以为同一条线里还能挑不同 SDK）。
- 产物 `plugin.json` 记录实际选中的版本（`sdk`），便于追溯「这个 .hmap 是哪版编的」。
- 显式 `--sdk-path` / `plg.json sdk_path` 优先（本机改 SDK 联调的路径），此路径下也尽力记录版本。
- 存量项目（plg.json 无 sdk 字段）行为不变，向后兼容。

顺带修一处自相矛盾：解析出 1.2.0 之外的版本时，原先只改 replace 而 require 保持旧版本，
一旦有人删掉 replace 就会静默用回旧 SDK 编译（`go list -m` 报的也是假版本）。

验证：单测 10 例（精确命中/带 v 前缀目录/区间写法被拒并说明规矩/未命中给可执行命令/
空存储给安装指引/非法值拒绝/杂项目录不干扰）+ 反向验证（把版本比较退化成字典序，
「1.2.x 取最新」用例立刻变红，证明判据能发现缺陷）。
E2E：init → plg.json `"sdk": "1.2.0"`；build → 精确解析、go.mod require/replace 一致、
产物 plugin.json 记录 sdk；声明不存在的版本 → 可执行报错；无 sdk 字段 → 照旧构建。
 2026-09-12 15:51:23 +08:00
JianFeeeee
83a54f321e fix(hmapdev): 工具链能报出版本（此前 -ldflags -X meta.Version 静默无效） 
两个缺口叠加：既没有 `version` 子命令，构建时的
`-ldflags "-X gitcode.com/JianFeeeee/homeagent-sdk/meta.Version=…"` 也因为
**meta 包根本没被工具链引用**而完全不生效（链接器不会保留未被引用的符号，
rodata 里连那个字符串都没有）——于是「手里是哪一版 hmapdev」无从判断，
而插件产物与内核是协议绑定的，这恰恰是最需要判断的一件事（v0.8.0 SDK 陈旧目录
导致模板编译失败那次就是靠猜）。

- main.go 引用 meta 包并新增 `version`（以及 `-v/--version`）子命令，
  输出工具链版本 / SDK 模块 / 构建提交 / 构建时间 / 构建用 Go / 可执行文件路径；
- 未注入（源码默认值）时也照常报，unknown 字段不打印（避免噪声）；
- usage 里补上 `hmapdev version`；
- 加测试钉住两件事：注入值必须出现在输出里（-X 一旦失效立刻变红）、
  未注入时也要能报出源码默认版本。

验证：`go build` 默认输出 1.3.0（主干默认值）；`-X …meta.Version=1.2.1
-X …meta.Commit=abc1234` 后输出 1.2.1 + 提交号，且二进制内精确匹配到该串
（说明注入真的进了镜像）；`go test -run PrintVersion` 2/2 PASS。
 2026-09-12 15:08:56 +08:00
JianFeeeee
b93fe6b878 chore(version): main 路牌推到 1.3.0（v1.2.0 已从 release/v1.2.x 发出） 
按版本纪律：release/v1.2.x 停在 v1.2.0 的发布提交（140cd34），主干 meta.Version
永远是「下一个未发布中版本」。
 2026-09-12 14:16:46 +08:00
JianFeeeee
140cd34b56 fix(package): 示例构建改用宿主工具链，跨平台不再 Exec format error 
`build.sh all all` 此前必然失败：示例的跨平台是由 hmapdev 的 `--target` 完成的，
被执行的进程必须在当前机器上跑，而 build_examples 传的是**目标平台**那把工具链
→ darwin 目标下拿 darwin 二进制在 linux 上跑，报
"cannot execute binary file: Exec format error"（linux/amd64 之后的所有目标全灭）。

- 宿主平台在脚本顶部、**export GOOS/GOARCH 之前**取定（`go env GOOS` 在 export
  之后会返回目标平台，这正是原 bug 的成因），并用 `env -u GOOS -u GOARCH` 兜底；
- `all` 的第一个目标可能不是宿主平台 → 缺宿主工具链时先补建一次；
- 宿主工具链仍缺失则**显式报错并给出该跑哪条命令**，不再静默退化成 Exec format error。

验证（VERSION=1.2.0 bash package/build.sh all all）：
linux/amd64、linux/arm64、darwin/amd64、darwin/arm64 四个目标示例产物均 17/17 成功
（修复前 darwin 两个目标 0/17）；windows 目标仍按设计显式拒绝
（协议 2 的统一共享内存区未移植 Windows，走 WSL）。
v1.2.0 		2026-09-12 14:15:20 +08:00
JianFeeeee
b237787c90 refactor(toolchain)!: 工具链 plugindev 更名为 hmapdev，module path 改回 gitcode 
- 目录 tools/plugindev → tools/hmapdev，可执行文件名/平台产物名同步
  （hmapdev_linux_amd64 等；包格式仍叫 .hmap）
- module path github.com/JianFeeeee/homeagent-sdk/tools/... → gitcode.com/...
  （与仓库实际托管一致；核心仓不依赖该 path，改动无外部影响）
- SDK 存储目录 ~/.homeagent/plugindev/sdk → ~/.homeagent/hmapdev/sdk
  新目录不存在而旧目录存在时沿用旧目录 → 已装 SDK 版本不会丢失
- 命令表/usage/--help/生成项目 README/示例 README/NSIS 安装器/
  package/build.sh/build-examples.sh 全部同步；PLUGINDEV 环境变量保留兼容
- sdk/ 目录零改动（公开接口不变）

验证：
- go build ./... ok；go test ./tools/hmapdev/ ok（含模板接线守卫 TestProcTemplate_CoversAllCoreMethods）
- bash -n package/{build,build-examples}.sh ok
- 端到端：hmapdev init demo && hmapdev build → dist/demo_bundle.hmap（linux+darwin）
- 本机安装 /usr/local/bin/hmapdev，旧名以软链保留；sdk list/current 正常
 2026-09-12 12:30:20 +08:00
JianFeeeee
69ff3089a4 fix(mocksdk): 补上漏掉的 InjectInputSync，恢复与公共 SDK 的同构 
mocksdk 自己的注释立了规矩：「插件在 yaegi 下调得通的方法，编成 plugin.bin 后
必须也调得通，否则调试期与真实运行行为不一致」。但这个 mock 一直没有旧的三参数
`InjectInputSync`（`git log -S` 可证并非本次引入），而那正是通道类插件
（qq / a2a）完成「收到入站 → agent 处理 → 回复取回」闭环要调的方法：

- 编译成 plugin.bin：能用（实现在模板里）
- 在 yaegi 下调试：方法根本不存在

§九 早就点过 mocksdk 是最容易悄悄漂的一处（它没有任何代码对着编译，编译器抓不到；
上次漂的是 `Triple.Predicate` vs 公共 SDK 的 `Relation`）。

本次做的是**机械比对**而不是凭印象：抽出公共 SDK `IOInjector` 的 14 个方法名
与 mock 的方法集求差，差异恰好只有 `InjectInputSync` 一个，补上后差集为空。
mock 仍可编译，plugindev 测试全绿。
 2026-09-12 09:34:51 +08:00