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 次、三个社交入口名称正确。
ci: 修 CI 自身的三处错误（本地能过 ≠ CI 能过）
2026-10-03 15:44:11 +00:00 · 2026-09-29 20:43:27 +08:00 · 2026-09-29 15:29:16 +08:00 · 2026-09-29 15:18:58 +08:00 · 2026-09-29 15:18:43 +08:00 · 2026-09-29 14:39:12 +08:00
173 changed files with 27344 additions and 3936 deletions
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@ -0,0 +1,251 @@
 # HomeAgent SDK 仓 CI。
 #
 # 与 release.yml 分工：本文件管「推送到 main / PR 时的检查」，release.yml 管
 # 「release/** 推送时的发版」。此前本仓**只有** release.yml —— main 的推送与
 # PR 完全没有检查，而 SDK 是被外部插件开发者直接依赖的契约面（sdk/plugin.go
 # 的接口一旦破，所有外部插件编译失败），必须有门。
 #
 # 设计原则与主仓一致：**CI 里每条命令都是本地已实测通过的**。
 # 不写「应该有用来试试」的步骤 —— 未验证的 CI 步骤会把假红灯变成常态。
 #
 # 明确不进 CI 的：
 #   - `hmapdev skill install`（会写 ~/.claude、~/.codex 等**开发者本机目录**）
 #   - 需要内核仓在场的检查（本仓独立可测；sync-lua-sdk.sh 会在缺内核时
 #     明确 skip 而不是假装成功）
 #   - 任何网络/真机依赖
 name: CI
 on:
  push:
    branches: [main, 'release/**']
  pull_request:
  workflow_dispatch:
 permissions:
  contents: read
 concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true
 env:
  # SDK 本身不需要 cgo（hmapdev 与 sdk 包都是纯 Go）—— 与主仓相反。
  CGO_ENABLED: 0
  GOFLAGS: -buildvcs=false
 jobs:
  # ── 根模块：SDK 对外接口所在 ──
  go:
    name: Go build / vet / test
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v7
      # ★ 钉 1.25 而不是 go-version-file: go.mod —— 根 go.mod 写的是
      #   go 1.21.0，但 20 个 example/*/go.mod 都要求 go 1.25.0。
      #   读根 go.mod 会装 1.21，examples 构建必然失败
      #   （"go.mod requires go >= 1.25.0 (running go 1.21.0; GOTOOLCHAIN=local)"）。
      #   GitHub runner 上 GOTOOLCHAIN=local，Go 不会自动下载更高工具链，
      #   所以本地「能过」不代表 CI 能过。
      - uses: actions/setup-go@v7
        with:
          go-version: '1.25'
          cache: true
      - name: go build ./...
        run: go build ./...
      - name: go vet ./...
        run: go vet ./...
      - name: go test ./...
        run: go test ./... -count=1 -timeout 10m
  # ── hmapdev 工具链（嵌套 module，根模块的 ./... 不会进入它）──
  hmapdev:
    name: hmapdev (${{ matrix.goos }}/${{ matrix.goarch }})
    runs-on: ubuntu-latest
    timeout-minutes: 20
    strategy:
      fail-fast: false
      matrix:
        include:
          - goos: linux
            goarch: amd64
            ext: ''
          - goos: linux
            goarch: arm64
            ext: ''
          - goos: darwin
            goarch: amd64
            ext: ''
          - goos: darwin
            goarch: arm64
            ext: ''
          - goos: windows
            goarch: amd64
            ext: '.exe'
    steps:
      - uses: actions/checkout@v7
      # ★ 钉 1.25 而不是 go-version-file: go.mod —— 根 go.mod 写的是
      #   go 1.21.0，但 20 个 example/*/go.mod 都要求 go 1.25.0。
      #   读根 go.mod 会装 1.21，examples 构建必然失败
      #   （"go.mod requires go >= 1.25.0 (running go 1.21.0; GOTOOLCHAIN=local)"）。
      #   GitHub runner 上 GOTOOLCHAIN=local，Go 不会自动下载更高工具链，
      #   所以本地「能过」不代表 CI 能过。
      - uses: actions/setup-go@v7
        with:
          go-version: '1.25'
          cache: true
      # tools/hmapdev 是**独立 module**（有自己的 go.mod）——
      # 根模块的 `go test ./...` 不会进入它，必须单独跑，否则它的测试
      # 永远不在 CI 里执行。这是 Go 的模块边界，不是配置问题。
      - name: go test（嵌套 module）
        working-directory: tools/hmapdev
        run: go test ./... -count=1 -timeout 10m
      # main 包在 tools/hmapdev —— 不指定工作目录会在仓库根跑 `go build .`，
      # 而根目录没有 Go 文件（包在 sdk/ 子目录），报 "no Go files in ..."。
      - name: 交叉编译
        working-directory: tools/hmapdev
        env:
          GOOS: ${{ matrix.goos }}
          GOARCH: ${{ matrix.goarch }}
        run: |
          set -euo pipefail
          out="hmapdev_${{ matrix.goos }}_${{ matrix.goarch }}${{ matrix.ext }}"
          go build -trimpath \
            -ldflags "-X gitcode.com/JianFeeeee/homeagent-sdk/meta.Version=0.0.0-ci" \
            -o "/tmp/$out" .
          test -s "/tmp/$out" || { echo "ERROR: 未产出 $out"; exit 1; }
          printf "  ✓ %-28s %s 字节\n" "$out" "$(stat -c %s "/tmp/$out")"
          file "/tmp/$out"
  # ── 示例插件：发版产物里最容易被使用者直接安装的东西 ──
  #
  # 为什么必须验：示例是使用者的模板（拷了就改），且**发版会连同 .hmap 一起发**
  # —— 插件二进制与内核是协议绑定的（ProtocolVersion + 统一共享内存区魔数），
  # 示例编不出来就意味着这次发版发不出配套产物。
  #
  # ★ 示例**不能**用 `go build` 验：它们是插件（只有 plugin.go、没有 func main），
  #   必须由 hmapdev 注入 main 包装。直接 go build 会得到
  #   "function main is undeclared in the main package" —— 那不是缺陷，
  #   是构建方式不对（本地实测确认）。
  examples:
    name: Examples (${{ matrix.target }})
    runs-on: ubuntu-latest
    timeout-minutes: 30
    strategy:
      fail-fast: false
      matrix:
        # windows 不在列：build-examples.sh 会明确拒绝（协议 2 的统一共享
        # 内存区未移植到 Windows），那是有意的设计而不是待修缺陷。
        target: ['linux/amd64', 'darwin/arm64']
    steps:
      - uses: actions/checkout@v7
      # ★ 钉 1.25 而不是 go-version-file: go.mod —— 根 go.mod 写的是
      #   go 1.21.0，但 20 个 example/*/go.mod 都要求 go 1.25.0。
      #   读根 go.mod 会装 1.21，examples 构建必然失败
      #   （"go.mod requires go >= 1.25.0 (running go 1.21.0; GOTOOLCHAIN=local)"）。
      #   GitHub runner 上 GOTOOLCHAIN=local，Go 不会自动下载更高工具链，
      #   所以本地「能过」不代表 CI 能过。
      - uses: actions/setup-go@v7
        with:
          go-version: '1.25'
          cache: true
      - name: 构建 hmapdev（宿主）
        run: |
          set -euo pipefail
          cd tools/hmapdev
          go build -o "$GITHUB_WORKSPACE/build/hmapdev_host" .
      # 用发版同一个脚本（package/build-examples.sh），避免 CI 与发版路径分叉。
      - name: 构建全部示例
        env:
          HMAPDEV: ${{ github.workspace }}/build/hmapdev_host
          TARGET: ${{ matrix.target }}
        run: |
          set -euo pipefail
          bash package/build-examples.sh "$TARGET" /tmp/examples
          echo
          n=$(find /tmp/examples -name '*.hmap' | wc -l)
          echo "  .hmap 产物数: $n"
          # 示例目录数应与产物数一致（少一个都要红）
          want=$(find example -mindepth 2 -maxdepth 2 -name plugin.go | wc -l)
          echo "  示例源码数:   $want"
          [ "$n" -ge "$want" ] || { echo "ERROR: 产物少于示例数"; exit 1; }
          for f in /tmp/examples/*.hmap; do
            printf "    %9.1fKB  %s\n" \
              "$(stat -c %s "$f" | awk '{print $1/1024}')" "$(basename "$f")"
          done
  # ── 一致性与文档 ──
  consistency:
    name: Consistency & docs
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v7
      # sdk.lua 有**四份**副本（本仓三份 + 内核仓一份），历史上漂移过，
      # 出现「mock 有、内核没有」的静默失配。此处钉住本仓内的三份。
      - name: Lua SDK 副本一致性
        run: |
          set -euo pipefail
          canon=sdk/lua/sdk.lua
          [ -f "$canon" ] || { echo "ERROR: 缺 $canon"; exit 1; }
          want=$(sha256sum "$canon" | cut -d' ' -f1)
          fail=0
          for f in tools/hmapdev/assets/sdk.lua example/luademo/sdk.lua; do
            have=$(sha256sum "$f" | cut -d' ' -f1)
            if [ "$have" = "$want" ]; then
              echo "  ✓ $f"
            else
              echo "  ✗ $f 与 $canon 不一致" >&2
              echo "      canon=$want" >&2
              echo "      this =$have" >&2
              echo "      解法：bash scripts/sync-lua-sdk.sh" >&2
              fail=1
            fi
          done
          [ "$fail" = "0" ] || exit 1
      # ★ 钉 1.25 而不是 go-version-file: go.mod —— 根 go.mod 写的是
      #   go 1.21.0，但 20 个 example/*/go.mod 都要求 go 1.25.0。
      #   读根 go.mod 会装 1.21，examples 构建必然失败
      #   （"go.mod requires go >= 1.25.0 (running go 1.21.0; GOTOOLCHAIN=local)"）。
      #   GitHub runner 上 GOTOOLCHAIN=local，Go 不会自动下载更高工具链，
      #   所以本地「能过」不代表 CI 能过。
      - uses: actions/setup-go@v7
        with:
          go-version: '1.25'
          cache: true
      # skills/ 会随 SDK store 分发给所有 agent（hmapdev skill install）。
      # skill list 会读 skills/ 目录并报告可用项 —— 目录结构坏掉会在这里红。
      - name: 技能目录可被 hmapdev 识别
        run: |
          set -euo pipefail
          # ★ 必须把 hmapdev 建在**仓库内**：resolveSkillsSource() 先从
          #   可执行文件位置向上找仓库（tools/hmapdev → ../../skills），
          #   落空才回退到 SDK store 的活跃版本 —— 而 CI 里没有 store，
          #   于是报 "no active SDK version set"。建到 /tmp 就会落空。
          mkdir -p build
          ( cd tools/hmapdev && go build -o "$GITHUB_WORKSPACE/build/hmapdev_ci" . )
          ./build/hmapdev_ci skill list
          ./build/hmapdev_ci skill path
      - uses: actions/setup-python@v7
        with:
          python-version: '3.12'
      # 文档站会被部署（deploy-sdk-site.sh）——站点构建坏了此前无从发现。
      # --strict 把 warning 升级为 error：断链、缺失引用都会红。
      #
      # ★ 不能用 yaml.safe_load 校验 mkdocs.yml：它含 mkdocs-material 的
      #   `!!python/name:` 标签（配置 emoji 的官方写法），safe_load 处理不了，
      #   会报 ConstructorError —— 那是校验方式不对，不是配置有问题。
      - name: 文档站构建（mkdocs --strict）
        run: |
          set -euo pipefail
          python3 -m pip install --quiet mkdocs-material
          mkdocs build --strict --site-dir /tmp/site
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@ -0,0 +1,314 @@
 # HomeAgent SDK 仓发布流水线：release/** 推送即发版。
 #
 # 与主仓的 Release 流水线同构（见主仓 .github/workflows/release.yml），
 # 差异只在产物与打包命令：
 #
 #   主仓 → 3 个 deb + 1 个 tar.gz（含 719MB 向量模型）
 #   SDK  → hmapdev_{linux,darwin}_{amd64,arm64} + hmapdev_windows_amd64.exe
 #          + SHA256SUMS（约 140MB）
 #
 # 产物清单依据：gitcode 上 v1.2.0/v1.3.0 的实际附件（各 6 个），
 # 以及 docs/git-branching.md §七 的「发版产物清单」。
 name: Release
 on:
  push:
    branches: ['release/**']
  workflow_dispatch:
    inputs:
      skip_tests:
        description: '跳过发版前的 go test 门（仅用于已知红的历史维护线）'
        type: boolean
        default: false
 permissions:
  contents: write
 concurrency:
  group: release-${{ github.ref }}
  cancel-in-progress: false
 env:
  CGO_ENABLED: 0
  GOFLAGS: -buildvcs=false
 jobs:
  prepare:
    name: Prepare
    runs-on: ubuntu-latest
    timeout-minutes: 10
    outputs:
      version: ${{ steps.ver.outputs.version }}
      tag: ${{ steps.ver.outputs.tag }}
      prerelease: ${{ steps.ver.outputs.prerelease }}
      exists: ${{ steps.ver.outputs.exists }}
      skip_tests: ${{ steps.ver.outputs.skip_tests }}
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      # 版本事实源是 meta/meta.go 的 Version，故发版动作 =
      # 在 release/vX.Y.x 上把它改成目标版本后推送。
      #
      # 幂等闸门：tag 已存在 ⇒ 整轮跳过（改文档不会重发版）。
      #
      # go test 门可跳过：新旧发布线的测试健康状况不同，硬门会让历史
      # 维护线完全无法发版。发版人可在**改动 meta 的那个提交**里写
      # [skip-release-tests] 显式跳过 —— 决定因此可被 git 历史审计。
      # （标记查在改 meta 的提交上而不是 HEAD：发版提交之后常还会跟
      #   几个提交，只看 HEAD 会让标记被顶掉、静默失效。）
      - id: ver
        name: 读取 meta.Version 并检查 tag
        run: |
          set -euo pipefail
          V=$(sed -n 's/^[[:space:]]*Version = "\(.*\)"/\1/p' \
              meta/meta.go | head -1)
          if [ -z "$V" ]; then
            echo "ERROR: 无法从 meta/meta.go 读出 Version"
            exit 1
          fi
          echo "version=$V" >> "$GITHUB_OUTPUT"
          echo "tag=v$V" >> "$GITHUB_OUTPUT"
          case "$V" in
            *-*) echo "prerelease=true" >> "$GITHUB_OUTPUT" ;;
            *)   echo "prerelease=false" >> "$GITHUB_OUTPUT" ;;
          esac
          if git ls-remote --exit-code --tags origin "refs/tags/v$V" \
               >/dev/null 2>&1; then
            echo "exists=true" >> "$GITHUB_OUTPUT"
            echo "  tag v$V 已存在 —— 跳过发版"
          else
            echo "exists=false" >> "$GITHUB_OUTPUT"
            echo "  将为 v$V 发版"
          fi
          SKIP="${{ inputs.skip_tests }}"
          REL_COMMIT=$(git log -1 --format=%H -- meta/meta.go)
          REL_MSG=$(git log -1 --pretty=%B "$REL_COMMIT")
          case "$REL_MSG" in
            *'[skip-release-tests]'*) MARKER=1 ;;
            *) MARKER=0 ;;
          esac
          echo "  发版提交: ${REL_COMMIT:0:12}"
          if [ "$SKIP" = "true" ] || [ "$MARKER" = "1" ]; then
            echo "skip_tests=true" >> "$GITHUB_OUTPUT"
            echo "  ⚠️  **已请求跳过发版前的 go test 门**"
          else
            echo "skip_tests=false" >> "$GITHUB_OUTPUT"
            echo "  发版前会跑 go test 门"
          fi
  build:
    name: Build hmapdev
    needs: prepare
    if: needs.prepare.outputs.exists == 'false'
    runs-on: ubuntu-latest
    timeout-minutes: 60
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - uses: actions/setup-go@v7
        with:
          go-version-file: go.mod
          cache: true
      # 门：go build 是硬门；go test 可在发版 commit 里显式跳过。
      #
      # 测试分两处跑 —— tools/hmapdev 是**独立 module**，根模块的
      # `go test ./...` 不会进入它（这是 Go 的模块边界，不是配置问题）。
      - name: go build（硬门）
        run: |
          set -euo pipefail
          go build ./...
      - name: go test（根模块）
        if: needs.prepare.outputs.skip_tests != 'true'
        run: go test ./... -count=1 -timeout 15m
      - name: go test（tools/hmapdev 独立 module）
        if: needs.prepare.outputs.skip_tests != 'true'
        working-directory: tools/hmapdev
        run: go test ./... -count=1 -timeout 15m
      - name: go test 被跳过（显式声明的后果）
        if: needs.prepare.outputs.skip_tests == 'true'
        run: |
          echo "::warning title=go test 门已跳过::本次发版未跑 go test，产物可能建立在单元测试失败的代码上。"
      - name: 打包 hmapdev（5 个平台）
        env:
          VERSION: ${{ needs.prepare.outputs.version }}
        run: |
          set -euo pipefail
          rm -rf build
          bash package/build.sh all hmapdev
          echo
          echo "  产物："
          for f in build/*; do
            printf "    %8.1fMB  %s\n" \
              "$(stat -c %s "$f" | awk '{print $1/1048576}')" "$(basename "$f")"
          done
      # 逐个确认 5 个平台都产出了 —— 只查目录非空会漏掉"少了一个平台"。
      - name: 验证产物齐全
        run: |
          set -euo pipefail
          missing=0
          for f in hmapdev_linux_amd64 hmapdev_linux_arm64 \
                   hmapdev_darwin_amd64 hmapdev_darwin_arm64 \
                   hmapdev_windows_amd64.exe; do
            if [ -s "build/$f" ]; then
              echo "  ✓ $f"
            else
              echo "  ✗ 缺 $f" >&2
              missing=1
            fi
          done
          [ "$missing" = "0" ] || exit 1
      # 校验和必须**全部产物齐全之后**一次算完（边打边算会漏包）；
      # 且只覆盖本批产物 —— build/ 可能残留上次的，故先清干净再建。
      - name: 生成 SHA256SUMS
        run: |
          set -euo pipefail
          mkdir -p /tmp/out
          cp build/hmapdev_linux_amd64 build/hmapdev_linux_arm64 \
             build/hmapdev_darwin_amd64 build/hmapdev_darwin_arm64 \
             build/hmapdev_windows_amd64.exe /tmp/out/
          cd /tmp/out
          sha256sum hmapdev_* > SHA256SUMS
          echo "  SHA256SUMS:"
          sed 's/^/    /' SHA256SUMS
          sha256sum -c SHA256SUMS
      - uses: actions/upload-artifact@v7
        with:
          name: hmapdev
          path: /tmp/out/*
          retention-days: 7
          if-no-files-found: error
  publish:
    name: Publish
    needs: [prepare, build]
    if: needs.prepare.outputs.exists == 'false'
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - uses: actions/download-artifact@v8
        with:
          name: hmapdev
          path: dist
      - name: 打 tag
        env:
          TAG: ${{ needs.prepare.outputs.tag }}
        run: |
          set -euo pipefail
          git config user.name  "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git tag -a "$TAG" -m "$TAG"
          git push origin "$TAG"
      - name: 建 release 并上传附件
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          TAG: ${{ needs.prepare.outputs.tag }}
          VERSION: ${{ needs.prepare.outputs.version }}
          PRE: ${{ needs.prepare.outputs.prerelease }}
        run: |
          set -euo pipefail
          cd dist
          FLAGS=()
          [ "$PRE" = "true" ] && FLAGS+=(--prerelease)
          gh release create "$TAG" \
            --title "HomeAgent SDK $VERSION" \
            --notes "HomeAgent 插件 SDK $VERSION
          \`hmapdev\` 工具链（Linux / macOS / Windows，amd64 + arm64）。
          校验见 SHA256SUMS。
          内核版本需与 SDK 的中版本对齐；协议不配套时插件握手会失败
          （魔数不匹配），此时升级内核或改用对应版本的 SDK。" \
            "${FLAGS[@]}" \
            ./hmapdev_* ./SHA256SUMS
          echo "=== release 内容 ==="
          gh release view "$TAG" --json assets \
            --jq '.assets[] | "  \(.name)  \(.size) 字节"'
      - name: 回读校验
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          TAG: ${{ needs.prepare.outputs.tag }}
        run: |
          set -euo pipefail
          mkdir -p /tmp/back && cd /tmp/back
          # 同主仓：/tmp/back 不是 git 仓库，gh 无法从上下文推断仓库，
          # 必须显式 --repo。
          gh release download "$TAG" --repo "$GITHUB_REPOSITORY"
          for f in *; do
            printf "  %8.1fMB  %s\n" \
              "$(stat -c %s "$f" | awk '{print $1/1048576}')" "$f"
          done
          sha256sum -c SHA256SUMS
          echo "  ✓ 回读校验通过"
  sync-gitcode:
    name: Sync to gitcode
    needs: [prepare, publish]
    if: needs.prepare.outputs.exists == 'false'
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v7
      - id: tok
        name: 检查 gitcode 凭据
        run: |
          if [ -n "${{ secrets.GITCODE_TOKEN }}" ]; then
            echo "ok=true" >> "$GITHUB_OUTPUT"
          else
            echo "ok=false" >> "$GITHUB_OUTPUT"
            echo "  未配置 GITCODE_TOKEN —— 跳过 gitcode 同步"
          fi
      - uses: actions/download-artifact@v8
        if: steps.tok.outputs.ok == 'true'
        with:
          name: hmapdev
          path: dist
      - name: 推 tag 与附件到 gitcode
        if: steps.tok.outputs.ok == 'true'
        env:
          GC_TOKEN: ${{ secrets.GITCODE_TOKEN }}
          TAG: ${{ needs.prepare.outputs.tag }}
        run: |
          set -euo pipefail
          git config user.name  "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git tag -a "$TAG" -m "$TAG" 2>/dev/null || true
          GC_URL="https://JianFeeeee:${GC_TOKEN}@gitcode.com"
          git push "${GC_URL}/JianFeeeee/homeagent-sdk.git" "$TAG"
          curl -sS --max-time 60 -X POST \
            -H "private-token: ${GC_TOKEN}" \
            -H "Content-Type: application/json" \
            "https://gitcode.com/api/v5/repos/JianFeeeee/homeagent-sdk/releases" \
            -d "{\"tag_name\":\"$TAG\",\"body\":\"同步自 GitHub\"}" \
            -o /tmp/.gcrel -w "  建 release → %{http_code}\n"
          cd dist
          # 脚本的路径语义是 os.path.join(ASSET_DIR, name) ⇒
          # 必须 cd 进资产目录、ASSET_DIR=.、并传**裸文件名**。
          # 传 "./x" 或 "dist/x" 都会拼成 dist/dist/x 而找不到文件。
          #
          # 为何显式列名而不是让它自动扫描：自动扫描只认 ARTIFACT_SUFFIXES
          # 里的扩展名，而 hmapdev 的产物多数**没有扩展名**（只有 windows
          # 那个是 .exe）⇒ 自动扫描会静默地一个都不传。
          ASSET_DIR=. GITCODE_REPO=JianFeeeee/homeagent-sdk \
            python3 ../scripts/upload-assets.py "$TAG" "$GC_TOKEN" \
            hmapdev_linux_amd64 hmapdev_linux_arm64 \
            hmapdev_darwin_amd64 hmapdev_darwin_arm64 \
            hmapdev_windows_amd64.exe SHA256SUMS
--- a/.gitignore
+++ b/.gitignore
@ -35,3 +35,13 @@ z_entry.c
 # plugindev binary in tools/
 tools/plugindev/plugindev
 # 文档站构建产物（由 tools/apidoc/build.sh 生成）
 site_build/
 # mkdocs 缓存
 .cache/
 # agent 入口的「全文汇总」是派生件：由 gensite 把 docs/ 下所有 Markdown 拼成一份，
 # 每次改任何一页都会整份重写（115KB），进版本库只产生噪声。它由构建产出，
 # llms.txt（索引，小且稳定）仍提交。
 docs/llms-full.txt
--- a/21
+++ b/21
@ -0,0 +1,21 @@
 MIT License
 Copyright (c) 2026 JianFeeeee
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights
 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 The above copyright notice and this permission notice shall be included in all
 copies or substantial portions of the Software.
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
--- a/README.md
+++ b/README.md
@ -2,6 +2,117 @@
 HomeAgent 插件开发 SDK，用于构建与 HomeAgent 平台交互的智能插件。
 > 📖 **完整文档**：<https://sdk.homeagent.jianfgit.xyz/>
 >
 > 快速开始 / API 参考 / 指南 / 示例插件都在那里，**本 README 只是速览**，
 > 接口细节以文档站为准。直接进入：[快速开始](https://sdk.homeagent.jianfgit.xyz/guide/getting-started/)
 > · [API 参考](https://sdk.homeagent.jianfgit.xyz/api/) · [能力边界](https://sdk.homeagent.jianfgit.xyz/guide/capability-boundary/)
 >
 > 面向 agent 的纯文本入口：[`llms.txt`](https://sdk.homeagent.jianfgit.xyz/llms.txt)
 > （含全部 API 的 [`llms-full.txt`](https://sdk.homeagent.jianfgit.xyz/llms-full.txt)）。
 ## 版本与兼容性
 当前：**SDK 1.3.0**（需内核 **1.3.0+**）。
 **版本号跟随内核的中版本，patch 位恒为 `.0`**：
 | 内核版本 | 对应 SDK |
 |---|---|
 | 1.0.0 / 1.0.1 / … / 1.0.4 | 1.0.0 |
 | 1.1.0 / 1.1.1 / … / 1.1.N | **1.1.0** |
 | 1.2.0 / 1.2.1 / … / 1.2.N | **1.2.0** |
 | 1.3.0 起 | **1.3.0** |
 内核的 patch 位专用于 bugfix 与漏洞修复，不碰公开接口，所以 SDK 版本号不跟着动——
 否则你要么被迫跟版、要么怀疑自己版本过时，而接口其实一个字都没变。
 因此 **SDK 仓在一个中版本里只发一次**（`vX.Y.0`），核心的 `v1.3.1`/`v1.3.2`/… 不伴随 SDK 发版。
 （2026-09-13 曾误发过 `v1.3.1`，已撤回 —— patch 位带非零数字的 SDK tag 都是错误的。）
 **1.0.x 插件升到 1.1.x：不需要改代码，也不需要重编。** 1.1.0 的新增全部是
 「插件调用、内核实现」方向，不调就不受影响（已用 SDK 0.9.2 编的旧 `plugin.bin`
 实测验证：在新内核上直接建链通过，因为握手校验的是 `ProtocolVersion`、不是 SDK 版本）。
 想用新字段时重编即可。
 **1.1.x 插件升到 1.2.x：接口纯追加，但必须重编。** 公开接口没有签名变更（新增
 `InjectOptions` 与六个 `*Opts` 变体、`ChannelDef.ContextPolicy`），不调新能力就不受影响；
 但内核的**插件运行协议升到了 2**（统一共享内存区的 fd3 布局改变，**不支持滚动升级**），
 所以 `plugin.bin` 必须用配套的 `hmapdev` 重编后与内核**同批**安装——否则握手时协议版本
 不匹配会被拒绝（错误信息会明确提示用配套 hmapdev 重编，不会静默降级）。
 ## 1.3.0 新增：注入优先级与动态输出通道
 ### 注入优先级（`InjectOptions.Priority`）
 插件可以声明**自己这次注入的中断级别**，内核按四级阶梯调度：
 | 级别 | 常量 | 谁用 |
 |---|---|---|
 | L1–L3 | `PriorityL1` / `PriorityL2` / `PriorityL3` | 插件按紧急程度自选（L1 最低） |
 | L4 | `PriorityL4` | **保留给内核与内核级插件**（内核自身事件、内核级通道） |
 - 零值（不声明）与旧的注入调用**完全等价**：按排队处理，不抢占任何正在执行的回合
  ⇒ 存量插件不需要改一行、也不需要重编。
 - 高优先级中断可以**抢占**低优先级正在跑的回合；被抢占的回合挂起、之后恢复继续
  （现场保存/恢复对插件透明）。
 - 排队输入**没有级别**：排队就是排队，任何中断都能插到它前面。
 ### 动态输出通道（`UnregisterOutputChannel`）
 `RegisterOutputChannel` 注册的通道此前只增不减。对**随资源生灭**的通道（典型：远程设备
 一台设备一个输出通道），设备掉线后通道还在，模型会继续对一个死通道发消息并以为发成功了。
 1.3.0 起成对提供：
 | API | 用途 |
 |---|---|
 | `UnregisterOutputChannel(name)` | 注销输出通道（含能力表与工具） |
 | `OutputChannelUnregistrar` / `SetOutputChannelUnregistrar` | 插件侧拿到注销句柄（内核注入） |
 ⚠️ 通道名要**由插件派生得又合法又唯一**（外部 id 不能直接当通道名）——
 设备 id 这类外部输入可能带 `/` 等字符，而通道名会拼进 LLM 函数名 `output_send__<name>`，
 违规会让**整条 LLM 请求**被上游拒绝（2026-09-13 生产事故：`device/<id>` 导致全量对话 403）。
 派生规则与约束见下方「输出通道」一节。
 ## 注入行为与上下文裁剪（1.2.0）
 「记不记入记忆」与「要不要据此裁剪上下文」这两件事，原先只有 `ToolDef` 能声明；
 1.2.0 起**注入侧也能声明**，并且二者共用同一套语义与取值。
 ```go
 type InjectOptions struct {
 	NoMemory      bool   // true = 不参与记忆计算（向量化/关键词提取/蒸馏），原文仍留在上下文
 	ContextPolicy string // ""/none = 不裁剪（默认）；prune = 据此裁剪上下文
 	CleanerName   string // 计算层过滤函数名：先经 Cleaner 得到实际有效内容，再计算/裁剪
 }
 const (
 	ContextPolicyNone  = "none"
 	ContextPolicyPrune = "prune"
 )
 // 六个变体，与旧的三参数方法一一对应，只多一个 opts
 InjectTextOpts(source, channel, text string, opts InjectOptions)
 InjectInterruptTextOpts(source, channel, text string, opts InjectOptions)
 InjectInputSyncOpts(source, channel, text string, opts InjectOptions) string
 InjectInputMediaOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions)
 InjectInputMediaSyncOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions) string
 InjectInterruptMediaOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions)
 ```
 要点：
 - **零值 `InjectOptions{}` 与旧的三参数方法逐键等价**（记入记忆 + 不裁剪）。旧方法保留为
  零值糖（`InjectText` / `InjectInterruptText` / `InjectTextNoMemory` …），存量插件不改一行、
  不需重编即可继续调用。
 - **裁剪（`prune`）必须显式声明**：它会归档丢弃低相关事件，是有副作用的行为，故默认关闭。
  内核只放行 `""` / `none` / `prune`（`ValidContextPolicy`），未声明的取值会被拒。
 - 裁剪前先经该插件注册的 **`Cleaner`**（由 `CleanerName` 指定）拿到实际有效内容，
  避开「按原文裁剪、按清洗后计算」这种不一致。
 - `ChannelDef` 也有同名 `context_policy`（并且 1.2.0 给它补上了 JSON tag——通道定义要跨进程
  传给内核，而 `Cleaner` 是函数必须忽略；无 tag 时新增字段会被静默丢掉）。
 ## SDK API 接口
 ### Plugin 接口
@ -20,11 +131,15 @@ type Plugin interface {
 通过 `Start(sdk *PluginSDK)` 注入的 SDK 实例提供以下方法：
 > **通道的方向契约**：入站与出站是分开登记的两件事。凡是用 `InjectText*/InjectInput*/InjectInterrupt*`
 > 注入的通道名都要 `RegisterInputChannel` —— inputch 是内核最基本的**输入路由单位**，
 > 只有登记过的通道才能被"划给驻留子"；只登记出站通道时内核会兜底登记同名 inputch 并告警（兼容老插件）。
 | 分类 | 方法 | 说明 |
 |------|------|------|
 | 阶段钩子 | `RegisterStage(stage, handler, scope...)` | 注册阶段回调，scope 可选：`StageScopeGlobal`（全局，默认）或 `StageScopeOwnTools`（仅自己工具） |
-| 输入通道 | `RegisterInputChannel(name, def)` | 注册输入通道，def 为 `ChannelDef`（NoMemory/Cleaner） |
+| 输入通道 | `RegisterInputChannel(name, def)` | 注册输入通道（**入站**：谁会往这个通道注入输入），def 为 `ChannelDef`（NoMemory/Cleaner） |
-| 输出通道 | `RegisterOutputChannel(name, caps, desc, def, handler)` | 注册输出通道，def 为 `ChannelDef`，caps 为能力位掩码 |
+| 输出通道 | `RegisterOutputChannel(name, caps, desc, def, handler)` | 注册输出通道（**出站**：`output_send__<name>` 的回复发给谁），def 为 `ChannelDef`，caps 为能力位掩码。⚠️ 通道名只能用 `[A-Za-z0-9_-]`（见下方"输出通道"一节的命名约束） |
 | 工具注册 | `RegisterTool(name, def, handler)` | 注册工具供 LLM 调用 |
 | 插件 API | `RegisterPluginAPI(name)` | 注册插件 API 供其他插件访问 |
 | 图记忆 | `Memory()` | 访问图记忆 API（实体-关系存储） |
@ -71,6 +186,14 @@ sdk.RegisterInputChannel("qq", ChannelDef{
 ### 输出通道
 > ⚠️ **命名约束（会进 LLM 函数名）**：内核按 `output_send__<name>` 生成工具，
 > 而上游对函数名的规范是 `^[a-zA-Z0-9_-]{1,64}$`。名字违规的后果不是
 > "这个工具不可用"，而是**整条请求被 400 拒绝**（`Invalid 'tools[N].function.name'`），
 > 网关 auto tier 全链条失败，表现成**整个 agent 不回应**。
 > 所以 `name` 只能用 `[A-Za-z0-9_-]`，并留出 `output_send__`（13 字符）的余量。
 > 名字若来自外部输入（设备自报 id 之类），请在插件侧派生一个合规且唯一的名字 ——
 > 内核**不会**替你净化。
 ```go
 sdk.RegisterOutputChannel("my-channel", CapText|CapFile, "通道描述", ChannelDef{}, handler)
 ```
@ -220,18 +343,31 @@ func New(name string, sett SettingsAPI, regTool ToolRegistrar, regStage StageReg
 插件开发者只需实现 `Plugin` 接口并导出 `NewPluginFactory()` 入口函数。
-## plugindev 工具链
+## hmapdev 工具链
-`plugindev` 提供插件开发全流程支持。预编译二进制作为 **release 附件**分发（linux/darwin/windows × amd64/arm64），从
+`hmapdev` 提供插件开发全流程支持，最终产出 `.hmap` 插件包（工具名即来自该包格式）。
-[Releases](https://gitcode.com/JianFeeeee/homeagent-sdk/releases) 下载后加入 PATH 即可：
+预编译二进制作为 **release 附件**分发（linux/darwin/windows × amd64/arm64），
 下载后加入 PATH 即可：
 > ⚠️ **二进制的实际分发地址目前是 gitcode**（两个仓的 release 附件不同步）：
 > `hmapdev_linux_amd64` 等 5 个平台二进制 + `SHA256SUMS` 在
 > <https://gitcode.com/JianFeeeee/homeagent-sdk/releases>。
 > GitHub 侧（<https://github.com/JianFeeeee/homeagentsdk/releases>）从
 > 下一个 SDK 版本（v1.4.0）起才会同步发布 —— 因为 SDK 仓**移仓后还没发过版**。
 > 源码与文档一律以 GitHub 为准，**只有二进制暂时还得到 gitcode 取**。
 > 改名说明：工具链原名 `plugindev`，自 1.2.0 起更名 `hmapdev`。
 > SDK 存储目录同时由 `~/.homeagent/plugindev/sdk` 迁到 `~/.homeagent/hmapdev/sdk`
 > （旧目录会被自动沿用，不会丢已装版本）。
 ```bash
-# 从 release 附件下载（以 v1.0.0 / linux amd64 为例）
+# 从 release 附件下载（以 linux amd64 为例，<版本> 如 v1.3.0）
-curl -Lo plugindev https://gitcode.com/JianFeeeee/homeagent-sdk/releases/download/v1.0.0/plugindev_linux_amd64
+# 当前实际分发地址是 gitcode（见下方说明）：
-chmod +x plugindev
+curl -Lo hmapdev https://gitcode.com/JianFeeeee/homeagent-sdk/releases/download/<版本>/hmapdev_linux_amd64
 chmod +x hmapdev
 # 或从源码自己编
-cd tools/plugindev && go build -o plugindev .
+cd tools/hmapdev && go build -o hmapdev .
 ```
 > 二进制不再随仓库分发（旧的 `bin/` 目录已停用）：5 个平台各 26-28MB，
@ -239,11 +375,11 @@ cd tools/plugindev && go build -o plugindev .
 | 命令 | 说明 |
 |------|------|
-| `plugindev init <name> [--lua]` | 初始化插件项目（生成 plg.json、plugin.go 或 main.lua、go.mod、README.md） |
+| `hmapdev init <name> [--lua]` | 初始化插件项目（生成 plg.json、plugin.go 或 main.lua、go.mod、README.md） |
-| `plugindev build [flags]` | 编译并打包为 `.hmap` 包（支持跨平台编译和 bundle 模式） |
+| `hmapdev build [flags]` | 编译并打包为 `.hmap` 包（支持跨平台编译和 bundle 模式） |
-| `plugindev clean` | 清理 `build/`、`dist/` 目录及生成文件（plugin.json、z_bridge_gen.go） |
+| `hmapdev clean` | 清理 `build/`、`dist/` 目录及生成文件（plugin.json、z_bridge_gen.go） |
-| `plugindev debug [dir]` | 通过 Yaegi Go 解释器加载插件源码，启动交互式 REPL 调试 |
+| `hmapdev debug [dir]` | 通过 Yaegi Go 解释器加载插件源码，启动交互式 REPL 调试 |
-| `plugindev sdk <command>` | SDK 版本管理（子命令：list/install/use/path/current/latest） |
+| `hmapdev sdk <command>` | SDK 版本管理（子命令：list/install/use/path/current/latest） |
 支持 **Go** 和 **Lua** 两种插件语言。
@ -350,7 +486,7 @@ return plugin
 - `sdk.RegisterOnRemoveHandler(fn func())` — 注册删除清理回调。内核在 `RemovePlugin` 流程中、插件 `Stop()` **之后**执行（后注册先执行，执行后清空、幂等）。用于删除插件自身创建的持久化文件（数据/缓存/状态文件）。
 - 内核卸载时一并清理：工具注册、`disabled_plugins` 记录、插件配置项定义（`plugin.<name>.*`）与插件配置表（`config_<name>`），卸载后插件配置区完全消失。
- 示例：`example/calendar`（删 events.json）、`example/memo`（删 memos.json）、`example/rss`（删订阅数据目录）、`example/weather`（删缓存目录）；`plugindev` 模板含 onRemove 演示。
+- 示例：`example/calendar`（删 events.json）、`example/memo`（删 memos.json）、`example/rss`（删订阅数据目录）、`example/weather`（删缓存目录）；`hmapdev` 模板含 onRemove 演示。
 ```go
 sdk.RegisterOnRemoveHandler(func() {
@ -368,6 +504,43 @@ enabled := sdk.AutoRestart()
 插件崩溃时平台自动拉起，保障服务可用性。
 重启是**有节制的**，默认参数（内核 `internal/plugin/registry.go`）：
 | 参数 | 值 | 含义 |
 |---|---|---|
 | `procRestartBackoff` | `1s` | 第 n 次重启前等 `n × 1s`（线性退避，非立即拉起） |
 | `procMaxRestarts` | `3` | 窗口内允许的重启次数上限 |
 | `procCrashWindow` | `5min` | 窗口内无新崩溃则计数归零 |
 即崩溃后的实际序列是 **1s → 2s → 3s**；同一 5 分钟窗口内第 **4** 次崩溃
 （`n > 3`）**不再自动拉起**，交人工介入。这不是「立即无感恢复」——
 如果插件需要秒级就位，请自己在 `OnStart` 里做好重连与重建。
 > ⚠️ `SetAutoRestart` 的典型用法是「外部连接建好后再判定能否自动重启」，而连接建立
 > 通常在后台 goroutine 里，内核又在另一个 goroutine 读它——这对读写天然并发。
 > **SDK 1.1.0 已给这个标志与全部 API 字段加锁**（`-race` 实测 11 处竞态，
 > 生产表现是插件重载瞬间偶发 nil 解引用崩溃）。早于 1.1.0 的版本建议升级。
 ## 插件开发者的并发约定
 `PluginSDK` 是**被多个 goroutine 同时使用的共享对象**：你在 `Start()` 里起的轮询、
 监听、定时器都拿着同一份 `*PluginSDK` 往里注消息，而内核会在加载/重载时写它的
 API 字段。因此：
 - **SDK 侧已保证的**：全部 API 访问器（`Memory()`/`DocMemory()`/…）、全部注入方法、
  `SetAutoRestart`/`AutoRestart`、`RegisterTool`/`RegisterStage`、
  `RunStopHandlers`/`RunOnRemoveHandlers`（幂等，并发调也只执行一次）。
 - **你需要自己保证的**：`StageContext` 的字段全部导出，并发读写必须自己持
  `ctx.Lock()`/`ctx.RLock()`。尤其是 `ctx.Extra`——**map 的并发写在 Go 里是直接 fatal，
  `recover` 接不住**。
 ```go
 ctx.Lock()
 ctx.Extra["mykey"] = value
 ctx.FinalText += "补充说明"
 ctx.Unlock()
 ```
 ## 受限 SDK vs 完整 SDK
 外部插件（第三方分发）使用**受限 SDK**，仅暴露安全子集：
@ -379,6 +552,57 @@ enabled := sdk.AutoRestart()
 内部插件（平台内置）拥有完整 SDK 访问权限，包括 SocialAPI 写操作和 EventPublisher。
 ## 项目声明 SDK 版本（plg.json 的 `sdk` 字段）
 `hmapdev init` 生成的工程里，`plg.json` 会带一个 `sdk` 字段：
 ```json
 {
  "name": "MyPlugin",
  "version": "0.1.0",
  "entry": "plugin.bin",
  "sdk": "1.2.0"
 }
 ```
 它的语义是**本插件针对的 SDK 版本**，工具链据此在本地 SDK 存储里选择版本：
 命中就用它，并把 `go.mod` 的 `require`/`replace` 同步到该版本；未命中则**明确报错**
 （列出已装版本 + `hmapdev sdk install vX.Y.Z`），**绝不静默退化成 `current`**。
 ```bash
 $ hmapdev build
 [hmapdev] SDK 1.2.0（项目声明 sdk=1.2.0）
 ```
 为什么要这个字段：以前项目里没有任何「我要哪版 SDK」的声明，工具链只能用存储里的
 `current`——谁改过 `current` 就拿谁的版本编，出错时表现为一堆看不懂的编译错误
 （例如存储里只有陈旧的 `v0.8.0` 时，模板项目首次构建会报 `undefined: sdk.InjectOptions`）。
 **写法必须是完整版本号（`1.2.0`），不接受区间写法（`1.2`）。** 原因见上文的版本纪律：
 SDK 版本跟随内核中版本、patch 位恒为 `.0`，一条内核线只对应一个 SDK 版本；
 写区间会让人误以为同一条线里还能挑不同 SDK（工具链会直接拒绝并说明这条规矩）。
 - 显式 `--sdk-path` 或 `plg.json` 的 `sdk_path` 优先（本机改 SDK 联调时用）；
 - 存量工程（`plg.json` 没有 `sdk` 字段）行为不变，仍按 `current` 构建；
 - 产物 `.hmap` 里的 `plugin.json` 会记录**实际选中的 SDK 版本**，便于事后追溯。
 ## IDE 支持：VSCode 扩展（`tools/vscode-hmapdev`）
 调试插件的实操回路是「构建 → 运行 → 看内核日志」，这三步都在 IDE 之外很别扭，
 所以仓库里带了一个 VSCode 扩展（[tools/vscode-hmapdev](tools/vscode-hmapdev)）：
 - **plg.json 诊断**：必需字段、`sdk` 是否是完整版本号、声明的 SDK 是否已安装（直接给安装命令）；
 - **状态栏**：`插件 · SDK <声明> · hmapdev <版本>`，工具链缺失或工程有错时变色；
 - **命令 / 任务**：build / build（全部目标）/ clean / debug（解释执行），编译错误进 Problems；
 - **跟随内核日志**：读 `<dataDir>/log` 下最新的 `homed_*.log` 并按插件名过滤。
 ```bash
 cd tools/vscode-hmapdev && npm install && npm run compile   # 然后在 VSCode 里按 F5
 ```
 它不是源码级调试器（没有断点/单步）：插件要么编译成产物在内核里跑、要么用
 `hmapdev debug` 解释执行，两条路都没有 DAP 会话；扩展做的是构建、运行、看日志与清单校验。
 ## 示例插件
 | 插件 | 类型 | 说明 |
@ -399,6 +623,11 @@ enabled := sdk.AutoRestart()
 | [rss](example/rss) | Go | RSS 订阅 |
 | [sanitizer](example/sanitizer) | Go | 内容清洗/安全过滤 |
 **发版时附带预编译示例产物**：SDK 的 release 除 5 平台 `hmapdev` 外，还包含各示例插件的
 `.hmap` 与 `SHA256SUMS`/`MANIFEST.txt`。原因是插件二进制与内核**协议绑定**（`ProtocolVersion`
 + 共享内存区魔数），只发工具链不发示例产物，很容易拿旧产物去装而握手失败——那看起来像
 「插件坏了」而不是「版本不配套」。
 ## Remote Device SDK
 用于开发**远程设备接入适配器**的 C 语言 SDK，零外部依赖，兼容嵌入式平台。
@ -500,10 +729,10 @@ ha_transport_t my_transport = {
 ### 使用方式
-通过 `plugindev` 工具链初始化项目：
+通过 `hmapdev` 工具链初始化项目：
 ```bash
-plugindev init my-adapter --type remotedevice
+hmapdev init my-adapter --type remotedevice
 ```
 生成 `main.c` + `CMakeLists.txt`，可直接编译或作为三方库引入：
@ -715,17 +944,17 @@ curl -X POST http://<homeagent-server>:8080/api/v1/device/esp32-cam-1/cmd \
 ### 位置
 - **SDK 源码**: `remotedevice/`
- **plugindev 模板**: `plugindev init --type remotedevice`
+- **hmapdev 模板**: `hmapdev init --type remotedevice`
 ## 构建与安装
 ### 构建
 ```bash
-plugindev build
+hmapdev build
 ```
-输出 `.hmap` 包到 `dist/` 目录（默认 bundle 多平台合集；单平台构建使用 `plugindev build --no-bundle`）。
+输出 `.hmap` 包到 `dist/` 目录（默认 bundle 多平台合集；单平台构建使用 `hmapdev build --no-bundle`）。
 ### 安装
@ -743,3 +972,32 @@ curl -X POST http://127.0.0.1:9876/plugins \
 ```
 或通过 WebUI 插件管理页面上传，也可手动将 `.hmap` 放入插件目录后重启平台。
 ## 文档
 - 文档站：**<https://sdk.homeagent.jianfgit.xyz/>**
 - 快速开始：[环境与工具链](https://sdk.homeagent.jianfgit.xyz/guide/getting-started/) · [第一个 Go 插件](https://sdk.homeagent.jianfgit.xyz/guide/first-plugin/) · [第一个 Lua 插件](https://sdk.homeagent.jianfgit.xyz/guide/first-lua-plugin/)
 - API 参考：[总览](https://sdk.homeagent.jianfgit.xyz/api/) · [工具](https://sdk.homeagent.jianfgit.xyz/api/tools/) · [阶段钩子](https://sdk.homeagent.jianfgit.xyz/api/stages/) · [记忆](https://sdk.homeagent.jianfgit.xyz/api/memory/) · [输入/输出通道](https://sdk.homeagent.jianfgit.xyz/api/channels/)
 - 指南：[能力边界（哪些 API 外部可用）](https://sdk.homeagent.jianfgit.xyz/guide/capability-boundary/) · [工具并发声明](https://sdk.homeagent.jianfgit.xyz/guide/parallel-tool-declaration/) · [流式多 tool_call](https://sdk.homeagent.jianfgit.xyz/guide/stream-tool-call-index/) · [场景记忆](https://sdk.homeagent.jianfgit.xyz/guide/scene-memory/) · [打包与发布](https://sdk.homeagent.jianfgit.xyz/guide/packaging/)
 - 版本与兼容：<https://sdk.homeagent.jianfgit.xyz/versions/>
 - 核心仓（内核 / 记忆 / 调度）：<https://github.com/JianFeeeee/HomeAgent>
 - 介绍站：<https://introduce.homeagent.jianfgit.xyz/>
 > 文档站为自托管（国内直连，不必挂代理）。构建与部署见核心仓的
 > `deploy-sdk-site.sh`（`--check` 只比对、`--rollback` 回滚）。
 ## 许可
 SDK 以 **MIT** 发布，全文见 [LICENSE](LICENSE)。
 **这是刻意的宽松**：SDK 会随插件一起**静态链接**（其源码进入插件二进制），
 若用 AGPL 之类的传染许可，插件作者就会被强制以其对外开源。选 MIT 就是为了
 让插件作者**自由选择自己的许可**——闭源、商业、私有均可，无需向本项目回馈，
 也无需取得任何例外或商业授权。第三方插件生态的安全与活跃正建立在这条之上。
 前提是 SDK 本身**完全自包含**：`go.mod` 零外部依赖，`sdk/` 只依赖 Go 标准库
 （`sync`），不引用核心仓的任何代码，因此 MIT 授权不与其他许可冲突。
 第三方组件（Go 依赖：go-sqlite3、gojieba、bubbletea 等，均为 MIT / BSD-3 / Apache-2.0）
 保持各自原有许可。平台侧的模型与推理运行时（Chinese-CLIP Apache-2.0、ONNX Runtime MIT）
 不属于本 SDK，其许可全文随发行包放在 `/usr/share/doc/homeagent/licenses/`。
--- a/README_EN.md
+++ b/README_EN.md
@ -2,6 +2,113 @@
 Plugin development SDK for building intelligent plugins that interact with the HomeAgent platform.
 > 📖 **Full documentation**: <https://sdk.homeagent.jianfgit.xyz/>
 >
 > Quick start / API reference / guides / example plugins all live there. **This README is a
 > summary only** — the docs site is authoritative for interface details.
 > Jump to: [Getting started](https://sdk.homeagent.jianfgit.xyz/guide/getting-started/)
 > · [API reference](https://sdk.homeagent.jianfgit.xyz/api/) · [Capability boundary](https://sdk.homeagent.jianfgit.xyz/guide/capability-boundary/)
 >
 > Agent-friendly plain-text entry points: [`llms.txt`](https://sdk.homeagent.jianfgit.xyz/llms.txt)
 > and [`llms-full.txt`](https://sdk.homeagent.jianfgit.xyz/llms-full.txt) (the whole docs in one file).
 ## Version and Compatibility
 Current: **SDK 1.3.0** (requires kernel **1.3.0+**).
 **The version tracks the kernel's minor version, with the patch position pinned at `.0`**:
 | Kernel version | Matching SDK |
 |---|---|
 | 1.0.0 / 1.0.1 / … / 1.0.4 | 1.0.0 |
 | 1.1.0 / 1.1.1 / … / 1.1.N | **1.1.0** |
 | 1.2.0 / 1.2.1 / … / 1.2.N | **1.2.0** |
 | 1.3.0 onward | **1.3.0** |
 The kernel's patch position is reserved for bugfixes and vulnerability fixes, which never touch the
 public interface, so the SDK version has no reason to move with it — otherwise you would either be
 forced to chase releases or suspect your version is stale, when not one character of the interface
 has changed.
 The SDK repository therefore publishes **exactly once per minor version** (`vX.Y.0`); kernel patches
 such as `v1.3.1` do not trigger an SDK release. (A `v1.3.1` tag was mistakenly cut on 2026-09-13 and
 has been withdrawn — any SDK tag with a non-zero patch position is wrong.)
 ## New in 1.3.0: Injection Priority and Dynamic Output Channels
 - **`InjectOptions.Priority` / `PriorityL1`–`PriorityL4`** — a plugin declares the interrupt level of
  its own injection; the kernel schedules L1–L4, where **L4 is reserved for the kernel and
  kernel-level plugins**. The zero value is fully equivalent to the old three-argument call
  (queued, never preempting), so existing plugins need neither a code change nor a rebuild.
  Queued input has no level: anything can jump ahead of it.
 - **`UnregisterOutputChannel` / `OutputChannelUnregistrar` / `SetOutputChannelUnregistrar`** —
  channels that die with their resource (one channel per remote device) can now be unregistered;
  previously they lingered and the model kept "successfully" sending into a dead channel.
 - **Channel names must be legal and unique.** The name is spliced into the LLM function name
  `output_send__<name>`, so it may only contain `[A-Za-z0-9_-]`. A real production incident
  (2026-09-13): `device/<id>` made every LLM request fail with 403. Derive channel names from
  external IDs — never use the raw ID.
 **Upgrading a 1.0.x plugin to 1.1.x: no code changes, no rebuild.** Everything added in 1.1.0 is
 in the "plugin calls, kernel implements" direction, so not calling it means not being affected
 (verified with an old `plugin.bin` built against SDK 0.9.2: it handshakes fine on the new kernel,
 because the handshake validates `ProtocolVersion`, not the SDK version). Rebuild only when you want
 the new fields.
 **Upgrading a 1.1.x plugin to 1.2.x: the interface is purely additive, but a rebuild is required.**
 No public signature changed (the SDK adds `InjectOptions`, six `*Opts` variants and
 `ChannelDef.ContextPolicy`), so not calling the new capabilities means not being affected — but the
 kernel's **plugin protocol went to 2** (the fd3 layout of the unified shared-memory region changed,
 and **rolling upgrades are not supported**). `plugin.bin` must therefore be rebuilt with the matching
 `hmapdev` and installed **together with** the kernel; otherwise the handshake fails on protocol
 version mismatch (the error says explicitly to rebuild with the matching hmapdev — it never
 degrades silently).
 ## Injection Behaviour and Context Pruning (1.2.0)
 "Should this go into memory" and "should the context be pruned based on this" used to be
 something only `ToolDef` could declare. Since 1.2.0 **injections can declare them too**, sharing
 the same semantics and values.
 ```go
 type InjectOptions struct {
 	NoMemory      bool   // true = excluded from memory computation (vectorize/keywords/distill); the
 	                     //        original text still stays in context
 	ContextPolicy string // ""/none = do not prune (default); prune = prune context based on this
 	CleanerName   string // name of the compute-layer cleaner: run it first to get the effective
 	                     // content, then compute/prune on that
 }
 const (
 	ContextPolicyNone  = "none"
 	ContextPolicyPrune = "prune"
 )
 // Six variants, one-to-one with the older three-argument methods, plus opts
 InjectTextOpts(source, channel, text string, opts InjectOptions)
 InjectInterruptTextOpts(source, channel, text string, opts InjectOptions)
 InjectInputSyncOpts(source, channel, text string, opts InjectOptions) string
 InjectInputMediaOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions)
 InjectInputMediaSyncOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions) string
 InjectInterruptMediaOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions)
 ```
 Key points:
 - **A zero-valued `InjectOptions{}` is key-for-key equivalent to the older three-argument methods**
  (recorded in memory, not pruned). The old methods remain as zero-value sugar (`InjectText`,
  `InjectInterruptText`, `InjectTextNoMemory`, …), so existing plugins keep working without a single
  line changed *or* a rebuild.
 - **Pruning (`prune`) must be declared explicitly**: it archives/drops low-relevance events, which
  is a side effect, so it is off by default. The kernel only accepts `""` / `none` / `prune`
  (`ValidContextPolicy`); anything else is rejected.
 - Pruning first goes through the plugin's registered **`Cleaner`** (named by `CleanerName`) to get
  the effective content, avoiding the inconsistency of "prune on the raw text, compute on the
  cleaned text".
 - `ChannelDef` carries the same `context_policy` (1.2.0 also gave `ChannelDef` JSON tags — the
  definition crosses the process boundary, while `Cleaner` is a function that must be ignored; with
  no tags, newly added fields would be silently dropped).
 ## SDK API Surface
 ### Plugin Interface
@ -226,19 +333,24 @@ func New(name string, sett SettingsAPI, regTool ToolRegistrar, regStage StageReg
 Plugin developers only need to implement the `Plugin` interface and export a `NewPlugin()` entry function.
-## plugindev Toolchain
+## hmapdev Toolchain
-`plugindev` provides full development workflow support. Prebuilt binaries ship as **release assets**
+`hmapdev` provides full development workflow support and produces `.hmap` plugin bundles (the tool is
 named after that package format). Prebuilt binaries ship as **release assets**
 (linux/darwin/windows × amd64/arm64); download from
 [Releases](https://gitcode.com/JianFeeeee/homeagent-sdk/releases) and put it on your PATH:
 > Rename note: the toolchain was called `plugindev` and is `hmapdev` since 1.2.0.
 > The SDK store moved from `~/.homeagent/plugindev/sdk` to `~/.homeagent/hmapdev/sdk`
 > (the old directory is still honored, so installed versions are not lost).
 ```bash
-# From release assets (v1.0.0 / linux amd64 shown)
+# From release assets (latest SDK release / linux amd64 shown)
-curl -Lo plugindev https://gitcode.com/JianFeeeee/homeagent-sdk/releases/download/v1.0.0/plugindev_linux_amd64
+curl -Lo hmapdev https://gitcode.com/JianFeeeee/homeagent-sdk/releases/download/<version>/hmapdev_linux_amd64
-chmod +x plugindev
+chmod +x hmapdev
 # Or build from source
-cd tools/plugindev && go build -o plugindev .
+cd tools/hmapdev && go build -o hmapdev .
 ```
 > Binaries no longer ship inside the repository (the old `bin/` directory is retired): five
@ -247,11 +359,11 @@ cd tools/plugindev && go build -o plugindev .
 | Command | Description |
 |---------|-------------|
-| `plugindev init <name> [--lua]` | Initialize plugin project (generates plg.json, plugin.go or main.lua, go.mod, README.md) |
+| `hmapdev init <name> [--lua]` | Initialize plugin project (generates plg.json, plugin.go or main.lua, go.mod, README.md) |
-| `plugindev build [flags]` | Build and package into a `.hmap` (supports cross-compilation and bundle mode) |
+| `hmapdev build [flags]` | Build and package into a `.hmap` (supports cross-compilation and bundle mode) |
-| `plugindev clean` | Clean `build/` and `dist/` plus generated files |
+| `hmapdev clean` | Clean `build/` and `dist/` plus generated files |
-| `plugindev debug [dir]` | Load plugin source through the Yaegi Go interpreter and start an interactive REPL |
+| `hmapdev debug [dir]` | Load plugin source through the Yaegi Go interpreter and start an interactive REPL |
-| `plugindev sdk <command>` | SDK version management (list/install/use/path/current/latest) |
+| `hmapdev sdk <command>` | SDK version management (list/install/use/path/current/latest) |
 Supports both **Go** and **Lua** plugin languages.
@ -323,7 +435,7 @@ Supports both **Go** and **Lua** plugin languages.
 - `sdk.RegisterOnRemoveHandler(fn func())` — Register a remove cleanup callback. The kernel runs it **after** the plugin's `Stop()` in the `RemovePlugin` flow (LIFO order, cleared after running — idempotent). Use it to delete persistent files the plugin created itself (data/cache/state files).
 - The kernel also cleans up on uninstall: tool registrations, the `disabled_plugins` record, the plugin's config definitions (`plugin.<name>.*`) and its config table (`config_<name>`) — the plugin's config section disappears completely after removal.
- Examples: `example/calendar` (removes events.json), `example/memo` (removes memos.json), `example/rss` (removes the subscription data dir), `example/weather` (removes the cache dir); the `plugindev` template includes an onRemove demo.
+- Examples: `example/calendar` (removes events.json), `example/memo` (removes memos.json), `example/rss` (removes the subscription data dir), `example/weather` (removes the cache dir); the `hmapdev` template includes an onRemove demo.
 ```go
 sdk.RegisterOnRemoveHandler(func() {
@ -341,6 +453,46 @@ enabled := sdk.AutoRestart()
 The platform automatically restarts the plugin on crash, ensuring service availability.
 Restarts are **rate-limited**. Defaults (kernel `internal/plugin/registry.go`):
 | Parameter | Value | Meaning |
 |---|---|---|
 | `procRestartBackoff` | `1s` | Before restart #n, wait `n × 1s` (linear backoff, not immediate) |
 | `procMaxRestarts` | `3` | Max restarts within the window |
 | `procCrashWindow` | `5min` | No new crash within the window resets the count |
 So the actual sequence is **1s → 2s → 3s**; the **4th** crash in the same 5-minute
 window (`n > 3`) is **not** restarted automatically and needs manual intervention.
 This is not instant, invisible recovery — if your plugin must be back in seconds,
 reconnect and rebuild your own state in `OnStart`.
 > ⚠️ `SetAutoRestart` is typically used to decide whether auto-restart is safe *after* an
 > external connection has been established, and that connection setup usually happens in a
 > background goroutine while the kernel reads the flag from another one — which is inherently
 > concurrent. **SDK 1.1.0 locks this flag and all API fields** (`-race` reported 11 data races;
 > in production this showed up as sporadic nil-dereference crashes during plugin reload). Upgrade
 > if you are on anything earlier.
 ## Concurrency Contract for Plugin Developers
 `PluginSDK` is a **shared object used by multiple goroutines**: the polling, listening and timer
 callbacks you start in `Start()` all hold the same `*PluginSDK` and push messages into it, while
 the kernel writes its API fields during load/reload. So:
 - **Guaranteed by the SDK**: all API accessors (`Memory()`/`DocMemory()`/…), all injection methods,
  `SetAutoRestart`/`AutoRestart`, `RegisterTool`/`RegisterStage`, and
  `RunStopHandlers`/`RunOnRemoveHandlers` (idempotent; concurrent calls still run it once).
 - **Your responsibility**: every field of `StageContext` is exported, and concurrent read/write
  must hold `ctx.Lock()`/`ctx.RLock()`. Especially `ctx.Extra` — **concurrent map writes are a
  fatal in Go, and `recover` cannot catch it**.
 ```go
 ctx.Lock()
 ctx.Extra["mykey"] = value
 ctx.FinalText += "supplementary note"
 ctx.Unlock()
 ```
 ## Restricted SDK vs Full SDK
 External plugins (third-party distribution) use a **restricted SDK** that only exposes a safe subset:
@ -372,6 +524,13 @@ Internal plugins (platform built-in) have full SDK access including SocialAPI wr
 | [rss](example/rss) | Go | RSS subscriptions |
 | [sanitizer](example/sanitizer) | Go | Content sanitization / safety filtering |
 **Prebuilt example artifacts ship with every release**: besides the 5-platform `hmapdev`, an SDK
 release contains the example plugins' `.hmap` files plus `SHA256SUMS`/`MANIFEST.txt`. The reason is
 that plugin binaries are **protocol-bound** to the kernel (`ProtocolVersion` + the shared-memory
 magic), so shipping the toolchain without matching artifacts invites installing an old artifact —
 which fails the handshake and looks like "the plugin is broken" rather than "the versions don't
 match".
 ## Remote Device SDK
 A C language SDK for developing **remote device access adapters** with zero external dependencies, compatible with embedded platforms.
@ -456,10 +615,10 @@ ha_transport_t my_transport = {
 ### Usage
-Initialize a project via the `plugindev` toolchain:
+Initialize a project via the `hmapdev` toolchain:
 ```bash
-plugindev init my-adapter --type remotedevice
+hmapdev init my-adapter --type remotedevice
 ```
 Generates `main.c` + `CMakeLists.txt`, can be built directly or used as a third-party library:
@ -669,17 +828,17 @@ curl -X POST http://<homeagent-server>:8080/api/v1/device/esp32-cam-1/cmd \
 ### Location
 - **SDK Source**: `remotedevice/`
- **plugindev template**: `plugindev init --type remotedevice`
+- **hmapdev template**: `hmapdev init --type remotedevice`
 ## Building & Installing
 ### Build
 ```bash
-plugindev build
+hmapdev build
 ```
-Outputs a `.hmap` package to the `dist/` directory (default is the multi-platform bundle; use `plugindev build --no-bundle` for a single-target build).
+Outputs a `.hmap` package to the `dist/` directory (default is the multi-platform bundle; use `hmapdev build --no-bundle` for a single-target build).
 ### Install
@ -697,3 +856,23 @@ curl -X POST http://127.0.0.1:9876/plugins \
 ```
 Or upload via the WebUI plugin management page, or manually place the `.hmap` in the plugin directory and restart the platform.
 ## License
 The SDK is released under the **MIT license** — see [LICENSE](LICENSE).
 **This permissiveness is deliberate**: the SDK is **statically linked** into your plugin
 (its source ends up in the plugin binary). Under a copyleft license such as AGPL that would
 force plugin authors to open-source their work; MIT exists precisely so that plugin authors
 can **pick their own license** — closed-source, commercial or private — with no obligation to
 contribute back and no need for any exception or commercial grant. The safety and vitality of
 the third-party plugin ecosystem rest on this.
 This is sound because the SDK is **fully self-contained**: `go.mod` has zero external
 dependencies and `sdk/` imports only the Go standard library (`sync`), never any code from the
 core repository — so the MIT grant conflicts with nothing.
 Third-party components (Go dependencies: go-sqlite3, gojieba, bubbletea, … — MIT / BSD-3 /
 Apache-2.0) keep their own licenses. The platform-side model and inference runtime
 (Chinese-CLIP Apache-2.0, ONNX Runtime MIT) are not part of this SDK; their full license texts
 ship with the release packages under `/usr/share/doc/homeagent/licenses/`.
--- a/docs/api/bridge.md
+++ b/docs/api/bridge.md
@ -0,0 +1,204 @@
 <!-- 本页由 tools/apidoc/gensite 从源码生成，请勿手改；要改文档就改 sdk/*.go 的注释。 -->
 # 桥接装配点（Bridge）
 以下方法**不是给插件业务代码调的**——它们由 `hmapdev` 生成的运行时在启动时调用，用来把内核能力注入到 SDK 实例。列在这里是为了让「公开 API 面」完整，并说明每个注入点对应什么能力。
 ### `APIRegistrar`
 ```go
 type APIRegistrar func(name string) error
 ```
 APIRegistrar registers a plugin API for external access.
 <small>`plugin.go:410`</small>
 ### `InputChannelRegistrar`
 ```go
 type InputChannelRegistrar func(name string, def ChannelDef) error
 ```
 InputChannelRegistrar registers an input channel with its memory behavior.
 <small>`plugin.go:413`</small>
 ### `OutputChannelRegistrar`
 ```go
 type OutputChannelRegistrar func(name string, caps int, desc string, def ChannelDef, handler ToolHandler) error
 ```
 OutputChannelRegistrar registers an output channel that the output_send tool can use.
 <small>`plugin.go:416`</small>
 ### `OutputChannelUnregistrar`
 ```go
 type OutputChannelUnregistrar func(name string) error
 ```
 OutputChannelUnregistrar 注销一个输出通道。
 为什么需要它：输出通道不止有"启动时注册一次"的静态通道，还有**随外部资源生灭**的
 动态通道 —— 典型是远程设备：`device/<id>` 只在设备在线期间存在，设备掉线后
 必须注销，否则 output_list_channels 会一直列着它、模型会往一个死通道发消息。
 <small>`plugin.go:423`</small>
 ### `PluginSDK.SetDocMemoryAPI`
 !!! info "桥接装配点"
    桥接运行时注入点（由 hmapdev 生成的 proc_main 调用，插件业务代码不调用）
 ```go
 func (s *PluginSDK) SetDocMemoryAPI(dm DocMemoryAPI)
 ```
 <small>`plugin.go:718`</small>
 ### `PluginSDK.SetEventSubscriber`
 !!! warning "仅内核内置插件可用"
    同上：无调用点。标 builtin 而非 bridge，因为连桥接运行时都不注入它——外部插件无法用它获得事件订阅能力。
 ```go
 func (s *PluginSDK) SetEventSubscriber(es EventSubscriber)
 ```
 <small>`plugin.go:742`</small>
 ### `PluginSDK.SetIOInjector`
 !!! info "桥接装配点"
    桥接运行时注入点（由 hmapdev 生成的 proc_main 调用，插件业务代码不调用）
 ```go
 func (s *PluginSDK) SetIOInjector(io IOInjector)
 ```
 SetIOInjector sets the IO injector (called by the core at startup).
 <small>`plugin.go:699`</small>
 ### `PluginSDK.SetInputChannelRegistrar`
 !!! info "桥接装配点"
    桥接运行时注入点（由 hmapdev 生成的 proc_main 调用，插件业务代码不调用）
 ```go
 func (s *PluginSDK) SetInputChannelRegistrar(r InputChannelRegistrar)
 ```
 SetInputChannelRegistrar sets the input channel registrar (called by the core at startup).
 <small>`plugin.go:692`</small>
 ### `PluginSDK.SetKnowledgeAPI`
 !!! info "桥接装配点"
    桥接运行时注入点（由 hmapdev 生成的 proc_main 调用，插件业务代码不调用）
 ```go
 func (s *PluginSDK) SetKnowledgeAPI(kn KnowledgeAPI)
 ```
 <small>`plugin.go:724`</small>
 ### `PluginSDK.SetLLMAPI`
 !!! info "桥接装配点"
    桥接运行时注入点（由 hmapdev 生成的 proc_main 调用，插件业务代码不调用）
 ```go
 func (s *PluginSDK) SetLLMAPI(llm LLMAPI)
 ```
 <small>`plugin.go:730`</small>
 ### `PluginSDK.SetMemoryAPI`
 !!! info "桥接装配点"
    桥接运行时注入点（由 hmapdev 生成的 proc_main 调用，插件业务代码不调用）
 ```go
 func (s *PluginSDK) SetMemoryAPI(mem MemoryAPI)
 ```
 SetMemoryAPI sets the memory API (called by the core at startup).
 <small>`plugin.go:706`</small>
 ### `PluginSDK.SetOutputChannelRegistrar`
 !!! info "桥接装配点"
    桥接运行时注入点（由 hmapdev 生成的 proc_main 调用，插件业务代码不调用）
 ```go
 func (s *PluginSDK) SetOutputChannelRegistrar(r OutputChannelRegistrar)
 ```
 SetOutputChannelRegistrar sets the output channel registrar (called by the core at startup).
 <small>`plugin.go:678`</small>
 ### `PluginSDK.SetOutputChannelUnregistrar`
 !!! warning "仅内核内置插件可用"
    同上，桥接模板不注入。
 ```go
 func (s *PluginSDK) SetOutputChannelUnregistrar(r OutputChannelUnregistrar)
 ```
 SetOutputChannelUnregistrar sets the output channel unregistrar (called by the core at startup).
 <small>`plugin.go:685`</small>
 ### `PluginSDK.SetPluginMgrAPI`
 !!! info "桥接装配点"
    桥接运行时注入点（由 hmapdev 生成的 proc_main 调用，插件业务代码不调用）
 ```go
 func (s *PluginSDK) SetPluginMgrAPI(pm PluginMgrAPI)
 ```
 SetPluginMgrAPI sets the plugin manager API (called by the bridge at startup).
 <small>`plugin.go:749`</small>
 ### `PluginSDK.SetSocialAPI`
 !!! info "桥接装配点"
    桥接运行时注入点（由 hmapdev 生成的 proc_main 调用，插件业务代码不调用）
 ```go
 func (s *PluginSDK) SetSocialAPI(social SocialAPI)
 ```
 <small>`plugin.go:736`</small>
 ### `PluginSDK.SetTextMemoryAPI`
 !!! info "桥接装配点"
    桥接运行时注入点（由 hmapdev 生成的 proc_main 调用，插件业务代码不调用）
 ```go
 func (s *PluginSDK) SetTextMemoryAPI(tm TextMemoryAPI)
 ```
 <small>`plugin.go:712`</small>
 ### `ToolRegistrar`
 ```go
 type ToolRegistrar func(name string, def ToolDef, handler ToolHandler) error
 ```
 ToolRegistrar registers a tool dynamically.
 <small>`plugin.go:404`</small>
--- a/docs/api/builtin-only.md
+++ b/docs/api/builtin-only.md
@ -0,0 +1,79 @@
 <!-- 本页由 tools/apidoc/gensite 从源码生成，请勿手改；要改文档就改 sdk/*.go 的注释。 -->
 # 仅内置插件可用的 API
 这些 API **存在于公开 SDK 包里**，但在外部（第三方）插件的运行路径上不可用：要么桥接运行时根本不注入它（拿到 nil），要么内核会拒绝/降级。列在这里是为了让边界显式——而不是让你在运行时才发现拿不到。
 判断依据全部来自源码与 `hmapdev` 桥接模板，逐条记在每条说明里。
 ### `PriorityL4`
 !!! warning "仅内核内置插件可用"
    sdk/plugin.go:119-126 明确：L1..L3 任何插件可声明，L4 只有内核级插件可用，外部插件声明会被内核夹到 L3（内核侧有 priority_clamp_test.go 守着）。外部插件文档应说明「声明 L4 无效」。
 ```go
 const PriorityL4
 ```
 PriorityL4 仅内核级（内置）插件可用；外部插件声明会被夹到 L3。
 <small>`plugin.go:165`</small>
 ### `PluginSDK.Events`
 !!! warning "仅内核内置插件可用"
    实测全仓 SetEventSubscriber 只有定义、无任何调用点（grep -rn SetEventSubscriber --include=*.go 仅命中 sdk/plugin.go 的定义与 lua_plugin.go 的一句注释）。外部插件拿到的 Events() 恒为 nil。外部插件订阅事件走的是桥接运行时的 events.subscribe RPC（proc_main.go.tmpl:1421 在插件侧分发、内核 protocol.go MethodEventsSubscribe），Lua 插件则走内部 SDK 的 Subscribe。这正是 PLUGIN_DEV.md 里没有说清的一处。
 ```go
 func (s *PluginSDK) Events() EventSubscriber
 ```
 Events returns the event subscriber for listening to kernel events (may be nil if not available).
 <small>`plugin.go:550`</small>
 ### `PluginSDK.SetEventSubscriber`
 !!! warning "仅内核内置插件可用"
    同上：无调用点。标 builtin 而非 bridge，因为连桥接运行时都不注入它——外部插件无法用它获得事件订阅能力。
 ```go
 func (s *PluginSDK) SetEventSubscriber(es EventSubscriber)
 ```
 <small>`plugin.go:742`</small>
 ### `PluginSDK.SetOutputChannelUnregistrar`
 !!! warning "仅内核内置插件可用"
    同上，桥接模板不注入。
 ```go
 func (s *PluginSDK) SetOutputChannelUnregistrar(r OutputChannelUnregistrar)
 ```
 SetOutputChannelUnregistrar sets the output channel unregistrar (called by the core at startup).
 <small>`plugin.go:685`</small>
 ### `PluginSDK.UnregisterOutputChannel`
 !!! warning "仅内核内置插件可用"
    外部插件的桥接模板只注入 SetOutputChannelRegistrar（proc_main.go.tmpl:693-705），**未**注入 SetOutputChannelUnregistrar（grep Unregistrar 在 templates/ 下无命中）。因此外部插件的 regOutputUnreg 为 nil，UnregisterOutputChannel 会命中 `if reg != nil` 的 else 分支**直接返回 nil**（sdk/plugin.go:539-549）——即**静默无效**：不报错、通道也没注销。内置插件由 internal/sdk/plugin.go:330 注入 cfg.RegOutputUnreg，真正生效。外部插件要让通道下线，只能重载插件。
 ```go
 func (s *PluginSDK) UnregisterOutputChannel(name string) error
 ```
 UnregisterOutputChannel 注销一个输出通道（动态通道随资源生灭时必须调用）。
 <small>`plugin.go:643`</small>
 ### `EventSubscriber.Subscribe`
 !!! warning "仅内核内置插件可用"
 ```go
 Subscribe(eventType EventType, handler EventHandler) func()
 ```
--- a/docs/api/channels.md
+++ b/docs/api/channels.md
@ -0,0 +1,650 @@
 <!-- 本页由 tools/apidoc/gensite 从源码生成，请勿手改；要改文档就改 sdk/*.go 的注释。 -->
 # 输入 / 输出通道
 通道是插件与外界（设备、其他 Agent、外部系统）交换消息的入口。**输入通道**接收外部消息，**输出通道**把消息投递出去。
 ## `IOInjector`
 IOInjector provides methods for injecting input and interrupts into the agent pipeline.
 All methods accept (source, channel) where channel is the target output channel
 for routing the agent's response.
 | 方法 | 说明 |
 |---|---|
 | [`InjectInputMedia`](#ioinjectorinjectinputmedia) |  |
 | [`InjectInputMediaOpts`](#ioinjectorinjectinputmediaopts) |  |
 | [`InjectInputMediaSync`](#ioinjectorinjectinputmediasync) |  |
 | [`InjectInputMediaSyncOpts`](#ioinjectorinjectinputmediasyncopts) |  |
 | [`InjectInputSync`](#ioinjectorinjectinputsync) | InjectInputSync 注入输入事件并同步等待 agent 回复，返回回复文本（无回复时返回空串）。 |
 | [`InjectInputSyncOpts`](#ioinjectorinjectinputsyncopts) |  |
 | [`InjectInterruptMedia`](#ioinjectorinjectinterruptmedia) |  |
 | [`InjectInterruptMediaOpts`](#ioinjectorinjectinterruptmediaopts) |  |
 | [`InjectInterruptText`](#ioinjectorinjectinterrupttext) |  |
 | [`InjectInterruptTextOpts`](#ioinjectorinjectinterrupttextopts) |  |
 | [`InjectText`](#ioinjectorinjecttext) |  |
 | [`InjectTextNoMemory`](#ioinjectorinjecttextnomemory) |  |
 | [`InjectTextOpts`](#ioinjectorinjecttextopts) | 以下 Opts 变体让调用点在**这一次注入**上声明记忆与裁剪行为。 |
 | [`SetToolBlocks`](#ioinjectorsettoolblocks) | SetToolBlocks 插件工具注入多模态内容块（image_url/audio_url），内核在下一条 |
 ### `IOInjector.InjectInputMedia`
 ```go
 InjectInputMedia(source, channel, text string, blocks []ContentBlock)
 ```
 <small>`plugin.go:329`</small>
 ### `IOInjector.InjectInputMediaOpts`
 ```go
 InjectInputMediaOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions)
 ```
 <small>`plugin.go:340`</small>
 ### `IOInjector.InjectInputMediaSync`
 ```go
 InjectInputMediaSync(source, channel, text string, blocks []ContentBlock) string
 ```
 <small>`plugin.go:330`</small>
 ### `IOInjector.InjectInputMediaSyncOpts`
 ```go
 InjectInputMediaSyncOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions) string
 ```
 <small>`plugin.go:341`</small>
 ### `IOInjector.InjectInputSync`
 ```go
 InjectInputSync(source, channel, text string) string
 ```
 InjectInputSync 注入输入事件并同步等待 agent 回复，返回回复文本（无回复时返回空串）。
 用于通道消息的完整闭环：收到入站 → agent 处理 → 回复取回 → 送回通道。
 **示例插件里的真实用法**
 | 插件 | 位置 | 代码 |
 |---|---|---|
 | [`a2a`](../examples/index.md#a2a) | `example/a2a/plugin.go:345` | `reply := p.sdk.InjectInputSync(p.name, p.name,` |
 | [`acp`](../examples/index.md#acp) | `example/acp/plugin.go:237` | `reply = p.sdk.InjectInputSync(p.name, p.name,` |
 <small>`plugin.go:325`</small>
 ### `IOInjector.InjectInputSyncOpts`
 ```go
 InjectInputSyncOpts(source, channel, text string, opts InjectOptions) string
 ```
 <small>`plugin.go:339`</small>
 ### `IOInjector.InjectInterruptMedia`
 ```go
 InjectInterruptMedia(source, channel, text string, blocks []ContentBlock)
 ```
 <small>`plugin.go:331`</small>
 ### `IOInjector.InjectInterruptMediaOpts`
 ```go
 InjectInterruptMediaOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions)
 ```
 <small>`plugin.go:342`</small>
 ### `IOInjector.InjectInterruptText`
 ```go
 InjectInterruptText(source, channel, text string)
 ```
 <small>`plugin.go:320`</small>
 ### `IOInjector.InjectInterruptTextOpts`
 ```go
 InjectInterruptTextOpts(source, channel, text string, opts InjectOptions)
 ```
 **示例插件里的真实用法**
 | 插件 | 位置 | 代码 |
 |---|---|---|
 | [`browser`](../examples/index.md#browser) | `example/browser/plugin.go:1319` | `p.sdk.InjectInterruptTextOpts(p.name, p.name,` |
 | [`calendar`](../examples/index.md#calendar) | `example/calendar/plugin.go:527` | `p.sdk.InjectInterruptTextOpts("calendar", "calendar", msg, sdk.InjectOptions{NoMemory: true})` |
 | [`memo`](../examples/index.md#memo) | `example/memo/plugin.go:299` | `p.sdk.InjectInterruptTextOpts(p.name, p.name,` |
 | [`qq`](../examples/index.md#qq) | `example/qq/plugin.go:1493` | `p.sdk.InjectInterruptTextOpts(p.name, p.name, text, sdk.InjectOptions{` |
 <small>`plugin.go:338`</small>
 ### `IOInjector.InjectText`
 ```go
 InjectText(source, channel, text string)
 ```
 <small>`plugin.go:321`</small>
 ### `IOInjector.InjectTextNoMemory`
 ```go
 InjectTextNoMemory(source, channel, text string)
 ```
 **示例插件里的真实用法**
 | 插件 | 位置 | 代码 |
 |---|---|---|
 | [`browser`](../examples/index.md#browser) | `example/browser/plugin.go:1114` | `p.sdk.InjectTextNoMemory(p.name, p.name, fmt.Sprintf("[浏览器 %s 已导航到 %s]", id, rawURL))` |
 <small>`plugin.go:322`</small>
 ### `IOInjector.InjectTextOpts`
 ```go
 InjectTextOpts(source, channel, text string, opts InjectOptions)
 ```
 以下 Opts 变体让调用点在**这一次注入**上声明记忆与裁剪行为。
 上面那些不带 opts 的方法等价于传零值 InjectOptions（记入记忆 + 不裁剪），
 保留它们是为了不破坏已有插件；新代码应当用 Opts 变体把意图写清楚。
 <small>`plugin.go:337`</small>
 ### `IOInjector.SetToolBlocks`
 ```go
 SetToolBlocks(blocks []ContentBlock)
 ```
 SetToolBlocks 插件工具注入多模态内容块（image_url/audio_url），内核在下一条
 tool message 的 content 数组里带上这些块，让模型在后续轮次看到图/听到音频。
 <small>`plugin.go:328`</small>
 ### `CapAudio`
 ```go
 const CapAudio
 ```
 Output capability flags
 <small>`plugin.go:430`</small>
 ### `CapFile`
 ```go
 const CapFile
 ```
 Output capability flags
 <small>`plugin.go:428`</small>
 ### `CapImage`
 ```go
 const CapImage
 ```
 Output capability flags
 <small>`plugin.go:429`</small>
 ### `CapStructured`
 ```go
 const CapStructured
 ```
 Output capability flags
 <small>`plugin.go:431`</small>
 ### `CapText`
 ```go
 const CapText
 ```
 Output capability flags
 <small>`plugin.go:427`</small>
 ### `ChannelDef`
 ```go
 type ChannelDef struct { NoMemory bool `json:"no_memory,omitempty"` Cleaner func(string) string `json:"-"` ContextPolicy string `json: …
 ```
 ChannelDef 描述通道在记忆计算层的行为，与 ToolDef.NoMemory/Cleaner 语义一致。
 NoMemory: 此通道输入/输出不参与记忆计算（向量化/关键词提取/蒸馏），但原文保留在上下文中
 Cleaner:  计算层过滤函数，不改原文；仅在向量化/jieba/蒸馏/存档提取关键词时调用
 ContextPolicy: 此通道的输入到达后是否据此裁剪上下文，默认 none（不裁剪）
 RecallPolicy:  此通道的输入到达后是否据此召回相关记忆，默认 auto（召回）
 ScenePolicy:   此通道的输入到达后是否参与场面识别（场景式记忆），默认 auto（参与）
 JSON tag 是必需的：通道定义要跨进程传给内核，而 Cleaner 是函数（必须忽略）。
 没有 tag 时既无法整体 marshal（func 不支持），又会诱使调用方手写字段白名单——
 那样新增字段会被静默丢掉。
 <small>`plugin.go:178`</small>
 ### `ContextPolicyNone`
 ```go
 const ContextPolicyNone
 ```
 上下文策略：决定一次工具调用/输入/注入是否依据其内容裁剪上下文。
 默认（空串或 ContextPolicyNone）**不裁剪**：裁剪会归档丢弃低相关事件，
 必须由工具/通道/注入点显式声明才发生——否则一个只想往上下文里塞内容的
 插件会在背后把别人的内容挤掉，且看不出是谁干的。
 <small>`plugin.go:44`</small>
 ### `ContextPolicyPrune`
 ```go
 const ContextPolicyPrune
 ```
 上下文策略：决定一次工具调用/输入/注入是否依据其内容裁剪上下文。
 默认（空串或 ContextPolicyNone）**不裁剪**：裁剪会归档丢弃低相关事件，
 必须由工具/通道/注入点显式声明才发生——否则一个只想往上下文里塞内容的
 插件会在背后把别人的内容挤掉，且看不出是谁干的。
 <small>`plugin.go:45`</small>
 ### `PluginSDK.InjectInputMedia`
 ```go
 func (s *PluginSDK) InjectInputMedia(source, channel, text string, blocks []ContentBlock)
 ```
 InjectInputMedia 注入带媒体内容块（image_url/audio_url）的输入。
 blocks 会落进媒体存储被记忆引用捕获，同时作为当前轮 content 数组
 发给 LLM，让模型在「本轮」就看到图/听到音频——区别于 SetToolBlocks
 的「下一轮 tool message」语义。
 等价于 InjectInputMediaOpts(..., InjectOptions{})。
 <small>`plugin.go:805`</small>
 ### `PluginSDK.InjectInputMediaOpts`
 ```go
 func (s *PluginSDK) InjectInputMediaOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions)
 ```
 InjectInputMediaOpts 注入带媒体块的输入，并声明记忆/裁剪行为。
 <small>`plugin.go:844`</small>
 ### `PluginSDK.InjectInputMediaSync`
 ```go
 func (s *PluginSDK) InjectInputMediaSync(source, channel, text string, blocks []ContentBlock) string
 ```
 InjectInputMediaSync 注入带媒体内容块的输入并同步等待 agent 回复。
 等价于 InjectInputMediaSyncOpts(..., InjectOptions{})。
 <small>`plugin.go:811`</small>
 ### `PluginSDK.InjectInputMediaSyncOpts`
 ```go
 func (s *PluginSDK) InjectInputMediaSyncOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions) string
 ```
 InjectInputMediaSyncOpts 注入带媒体块的输入并同步等待回复，同时声明记忆/裁剪行为。
 <small>`plugin.go:851`</small>
 ### `PluginSDK.InjectInputSync`
 ```go
 func (s *PluginSDK) InjectInputSync(source, channel, text string) string
 ```
 InjectInputSync injects a text message and synchronously waits for the agent reply,
 returning the reply text (empty string if none). Replies must be dispatched back
 to the source channel by the caller.
 **示例插件里的真实用法**
 | 插件 | 位置 | 代码 |
 |---|---|---|
 | [`a2a`](../examples/index.md#a2a) | `example/a2a/plugin.go:345` | `reply := p.sdk.InjectInputSync(p.name, p.name,` |
 | [`acp`](../examples/index.md#acp) | `example/acp/plugin.go:237` | `reply = p.sdk.InjectInputSync(p.name, p.name,` |
 <small>`plugin.go:796`</small>
 ### `PluginSDK.InjectInputSyncOpts`
 ```go
 func (s *PluginSDK) InjectInputSyncOpts(source, channel, text string, opts InjectOptions) string
 ```
 InjectInputSyncOpts 注入输入并同步等待回复，同时在这次注入上声明记忆/裁剪行为。
 <small>`plugin.go:835`</small>
 ### `PluginSDK.InjectInterruptMedia`
 ```go
 func (s *PluginSDK) InjectInterruptMedia(source, channel, text string, blocks []ContentBlock)
 ```
 InjectInterruptMedia 注入带媒体内容块的中断，可抢占当前 LLM 处理。
 blocks 随中断消息一起发给模型。
 <small>`plugin.go:868`</small>
 ### `PluginSDK.InjectInterruptMediaOpts`
 ```go
 func (s *PluginSDK) InjectInterruptMediaOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions)
 ```
 InjectInterruptMediaOpts 注入带媒体块的中断，并声明记忆/裁剪行为。
 <small>`plugin.go:860`</small>
 ### `PluginSDK.InjectInterruptText`
 ```go
 func (s *PluginSDK) InjectInterruptText(source, channel, text string)
 ```
 InjectInterruptText injects a text interrupt that can preempt current LLM processing.
 等价于 InjectInterruptTextOpts(..., InjectOptions{})：记入记忆、不裁剪。
 <small>`plugin.go:777`</small>
 ### `PluginSDK.InjectInterruptTextOpts`
 ```go
 func (s *PluginSDK) InjectInterruptTextOpts(source, channel, text string, opts InjectOptions)
 ```
 InjectInterruptTextOpts 注入可抢占当前处理的中断文本。
 中断也允许声明 ContextPolicyPrune：中断同样携带内容进入上下文，
 是否需要据此裁剪由调用方决定（默认不裁剪）。
 **示例插件里的真实用法**
 | 插件 | 位置 | 代码 |
 |---|---|---|
 | [`browser`](../examples/index.md#browser) | `example/browser/plugin.go:1319` | `p.sdk.InjectInterruptTextOpts(p.name, p.name,` |
 | [`calendar`](../examples/index.md#calendar) | `example/calendar/plugin.go:527` | `p.sdk.InjectInterruptTextOpts("calendar", "calendar", msg, sdk.InjectOptions{NoMemory: true})` |
 | [`memo`](../examples/index.md#memo) | `example/memo/plugin.go:299` | `p.sdk.InjectInterruptTextOpts(p.name, p.name,` |
 | [`qq`](../examples/index.md#qq) | `example/qq/plugin.go:1493` | `p.sdk.InjectInterruptTextOpts(p.name, p.name, text, sdk.InjectOptions{` |
 <small>`plugin.go:828`</small>
 ### `InjectOptions`
 ```go
 type InjectOptions struct { NoMemory bool ContextPolicy string // RecallPolicy 声明此次注入是否据其内容召回相关记忆。 // 空串 = 默认（输入/注<><E6B3A8> …
 ```
 InjectOptions 声明一次注入行为在记忆层与上下文层的表现。
 零值 = 记入记忆 + 不裁剪上下文，与历史行为（三参数注入方法）完全一致，
 因此调用方只有在确实需要改变行为时才需要填它。
 为什么注入也要这两个标志：注入的内容来源千差万别——轮询到的频道消息
 属于真实对话（该记），而“任务还在跑”“连接已重连”这类提醒不该污染记忆，
 也不该把上下文按它的内容裁一遍。按调用点声明比按通道一刀切准确。
 NoMemory:       此次注入不参与记忆计算（向量化/关键词提取/蒸馏），原文仍留在上下文
 ContextPolicy:  此次注入后是否依据（清洗后的）内容裁剪上下文；默认不裁剪。
 RecallPolicy:   此次注入是否依据（清洗后的）内容召回相关记忆；默认 auto（召回）。
 	中断注入也允许声明 prune——它同样会携带内容进入上下文。
 CleanerName:    此次注入的内容用哪个**已注册的通道 cleaner** 清洗。
 	空串 = 按注入的 source 查通道定义（既有行为）。
 	为什么要能显式指定：注入的 source 未必是注册过的输入通道名，
 	而注入内容往往带 ANSI/JSON 包装，需要清洗后才是有效内容；
 	不指定就只能退到「按 source 查不到就不清洗」。
 <small>`plugin.go:132`</small>
 ### `PluginSDK.InjectText`
 ```go
 func (s *PluginSDK) InjectText(source, channel, text string)
 ```
 InjectText injects a text message into the agent pipeline.
 等价于 InjectTextOpts(..., InjectOptions{})：记入记忆、不裁剪。
 <small>`plugin.go:783`</small>
 ### `PluginSDK.InjectTextNoMemory`
 ```go
 func (s *PluginSDK) InjectTextNoMemory(source, channel, text string)
 ```
 InjectTextNoMemory injects a text message without generating memory.
 等价于 InjectTextOpts(..., InjectOptions{NoMemory: true})。
 **示例插件里的真实用法**
 | 插件 | 位置 | 代码 |
 |---|---|---|
 | [`browser`](../examples/index.md#browser) | `example/browser/plugin.go:1114` | `p.sdk.InjectTextNoMemory(p.name, p.name, fmt.Sprintf("[浏览器 %s 已导航到 %s]", id, rawURL))` |
 <small>`plugin.go:789`</small>
 ### `PluginSDK.InjectTextOpts`
 ```go
 func (s *PluginSDK) InjectTextOpts(source, channel, text string, opts InjectOptions)
 ```
 InjectTextOpts 注入文本到 agent，并在这一次注入上声明记忆与裁剪行为。
 <small>`plugin.go:818`</small>
 ### `PriorityL1`
 ```go
 const PriorityL1
 ```
 中断优先级取值。
 L1..L3 任何插件都可声明；**L4 只有内核级插件**（编译期内置插件，
 如 cli/webui/timer）才能声明——它用于实现真正的“立即打断”能力，
 例如 WebUI 的终止按钮。外部插件（走 proc 桥）声明 L4 会被内核夹到 L3。
 <small>`plugin.go:161`</small>
 ### `PriorityL2`
 ```go
 const PriorityL2
 ```
 中断优先级取值。
 L1..L3 任何插件都可声明；**L4 只有内核级插件**（编译期内置插件，
 如 cli/webui/timer）才能声明——它用于实现真正的“立即打断”能力，
 例如 WebUI 的终止按钮。外部插件（走 proc 桥）声明 L4 会被内核夹到 L3。
 <small>`plugin.go:162`</small>
 ### `PriorityL3`
 ```go
 const PriorityL3
 ```
 中断优先级取值。
 L1..L3 任何插件都可声明；**L4 只有内核级插件**（编译期内置插件，
 如 cli/webui/timer）才能声明——它用于实现真正的“立即打断”能力，
 例如 WebUI 的终止按钮。外部插件（走 proc 桥）声明 L4 会被内核夹到 L3。
 <small>`plugin.go:163`</small>
 ### `PriorityL4`
 !!! warning "仅内核内置插件可用"
    sdk/plugin.go:119-126 明确：L1..L3 任何插件可声明，L4 只有内核级插件可用，外部插件声明会被内核夹到 L3（内核侧有 priority_clamp_test.go 守着）。外部插件文档应说明「声明 L4 无效」。
 ```go
 const PriorityL4
 ```
 PriorityL4 仅内核级（内置）插件可用；外部插件声明会被夹到 L3。
 <small>`plugin.go:165`</small>
 ### `RecallPolicyAuto`
 ```go
 const RecallPolicyAuto
 ```
 召回策略：决定一次工具调用/输入/注入是否据其内容**召回**（注入）相关记忆。
 与 ContextPolicy **正交**：ContextPolicy 管「裁剪」（把低相关 L0 事件归档），
 RecallPolicy 管「召回」（把 L2/L3 的相关记忆注入本轮）。两者默认值刻意相反——
 裁剪是破坏性的，默认关（必须显式声明）；召回是只读增量、日常对话本就需要，
 默认 auto（输入/注入），仅**工具**默认 none（工具输出多为噪声，按需声明）。
 <small>`plugin.go:65`</small>
 ### `RecallPolicyNone`
 ```go
 const RecallPolicyNone
 ```
 召回策略：决定一次工具调用/输入/注入是否据其内容**召回**（注入）相关记忆。
 与 ContextPolicy **正交**：ContextPolicy 管「裁剪」（把低相关 L0 事件归档），
 RecallPolicy 管「召回」（把 L2/L3 的相关记忆注入本轮）。两者默认值刻意相反——
 裁剪是破坏性的，默认关（必须显式声明）；召回是只读增量、日常对话本就需要，
 默认 auto（输入/注入），仅**工具**默认 none（工具输出多为噪声，按需声明）。
 <small>`plugin.go:64`</small>
 ### `PluginSDK.RegisterInputChannel`
 ```go
 func (s *PluginSDK) RegisterInputChannel(name string, def ChannelDef) error
 ```
 RegisterInputChannel registers an input channel with its memory behavior.
 契约：**凡是用 InjectText*/InjectInput*/InjectInterrupt*(source, "<name>", ...)
 注入的通道名，都应当在这里登记**。inputch 是内核里最基本的**输入路由单位**：
 只有登记过的通道才能在 inputch 登记表里出现，父 agent 才能"把某个 inputch 划给驻留子"；
 没登记就划分会直接失败（`inputch 未注册`）。
 只登记输出通道（RegisterOutputChannel）而没登记输入通道时，内核会兜底登记同名
 inputch 并打告警日志 —— 兜底只为兼容老插件，新插件请显式登记。
 def.NoMemory: 此通道输入不参与记忆计算
 def.Cleaner:  计算层对输入文本清洗后（不改原文）再向量化/提关键词
 **示例插件里的真实用法**
 | 插件 | 位置 | 代码 |
 |---|---|---|
 | [`a2a`](../examples/index.md#a2a) | `example/a2a/plugin.go:52` | `_ = s.RegisterInputChannel(p.name, sdk.ChannelDef{})` |
 | [`acp`](../examples/index.md#acp) | `example/acp/plugin.go:52` | `_ = s.RegisterInputChannel(p.name, sdk.ChannelDef{})` |
 | [`browser`](../examples/index.md#browser) | `example/browser/plugin.go:209` | `_ = s.RegisterInputChannel(p.name, sdk.ChannelDef{})` |
 | [`calendar`](../examples/index.md#calendar) | `example/calendar/plugin.go:281` | `_ = s.RegisterInputChannel("calendar", sdk.ChannelDef{NoMemory: true})` |
 <small>`plugin.go:665`</small>
 ### `PluginSDK.RegisterOutputChannel`
 ```go
 func (s *PluginSDK) RegisterOutputChannel(name string, caps int, desc string, def ChannelDef, handler ToolHandler) error
 ```
 RegisterOutputChannel registers an output channel that the output_send tool can route to.
 与 RegisterInputChannel 的分工：本函数声明**出站**（output_send__<name> 的回复发给谁）；
 入站（谁会往 <name> 注入输入）是另一件事，用 RegisterInputChannel 声明。
 若该通道同时也是你的注入入口，两个都要登记。
 name: channel name (e.g. "qq", "webui")。
 ❗**命名约束**：内核会把通道名拼进 LLM 的函数名（`output_send__<name>`），
 而上游对函数名的规范是 `^[a-zA-Z0-9_-]{1,64}$`。违反的后果不是"这个工具不可用"，
 而是**整条请求被上游 400 拒绝**（`Invalid 'tools[N].function.name'`），
 网关的 auto tier 会全链条失败 —— 表现成"整个 agent 不说话了"。
 所以通道名只能用 `[A-Za-z0-9_-]`，且总长要留出 `output_send__`（13 字符）的余量。
 若通道名来自外部输入（设备自报 id 之类），请**在插件侧派生一个合规且唯一的名字**，
 而不是把原始值直接当通道名。
 caps: bitmask of supported output capabilities (CapText, CapFile, etc.)
 desc: description of the channel, expected meta format, and type enum
 def:  通道在记忆计算层的行为（NoMemory/Cleaner）
 handler: receives args map with keys: payload (string), type (string), meta (string|optional)
 **示例插件里的真实用法**
 | 插件 | 位置 | 代码 |
 |---|---|---|
 | [`a2a`](../examples/index.md#a2a) | `example/a2a/plugin.go:57` | `if err := s.RegisterOutputChannel(p.name, 1, "A2A Agent 互联通道（外部 agent 查询的回复由此返回）", sdk.ChannelDef{}, func(args…` |
 | [`acp`](../examples/index.md#acp) | `example/acp/plugin.go:57` | `s.RegisterOutputChannel(p.name, 1, "ACP Agent 互联通道（外部 agent 会话的回复由此返回）", sdk.ChannelDef{}, func(args map[strin…` |
 | [`qq`](../examples/index.md#qq) | `example/qq/plugin.go:411` | `s.RegisterOutputChannel("qq", sdk.CapText\|sdk.CapFile\|sdk.CapImage\|sdk.CapAudio,` |
 | [`weather`](../examples/index.md#weather) | `example/weather/plugin.go:104` | `if err := s.RegisterOutputChannel(tp+"weather_out", 0, "push weather to user", sdk.ChannelDef{` |
 <small>`plugin.go:632`</small>
 ### `PluginSDK.SetToolBlocks`
 ```go
 func (s *PluginSDK) SetToolBlocks(blocks []ContentBlock)
 ```
 SetToolBlocks 在工具处理函数内注入多模态内容块，内核在下一条 tool message
 的 content 数组里带上它们。需要「本轮就让模型看到」时用 InjectInputMedia。
 <small>`plugin.go:876`</small>
 ### `ValidContextPolicy`
 ```go
 func ValidContextPolicy(policy string) bool
 ```
 ValidContextPolicy 校验策略取值；空串等价于 ContextPolicyNone。
 <small>`plugin.go:49`</small>
 ### `ValidRecallPolicy`
 ```go
 func ValidRecallPolicy(policy string) bool
 ```
 ValidRecallPolicy 校验召回策略取值；空串按调用面取默认值。
 <small>`plugin.go:69`</small>
--- a/docs/api/constants.md
+++ b/docs/api/constants.md
@ -0,0 +1,86 @@
 <!-- 本页由 tools/apidoc/gensite 从源码生成，请勿手改；要改文档就改 sdk/*.go 的注释。 -->
 # 常量与枚举
 SDK 里的取值枚举。其中带「仅内置」标注的取值在内核侧会被夹到较低级别。
 ## StageOnInput 等
 | 名称 | 说明 |
 |---|---|
 | `StageOnInput` |  |
 | `StagePreAction` |  |
 | `StagePostAction` |  |
 | `StageBeforeToolcall` |  |
 | `StageAfterToolcall` |  |
 | `StageBeforeOutput` |  |
 | `StageAfterOutput` |  |
 ## ContextPolicyNone 等
 | 名称 | 说明 |
 |---|---|
 | `ContextPolicyNone` |  |
 | `ContextPolicyPrune` |  |
 ## RecallPolicyNone 等
 | 名称 | 说明 |
 |---|---|
 | `RecallPolicyNone` |  |
 | `RecallPolicyAuto` |  |
 ## ScenePolicyAuto 等
 | 名称 | 说明 |
 |---|---|
 | `ScenePolicyAuto` |  |
 | `ScenePolicyNone` |  |
 ## PriorityL1 等
 | 名称 | 说明 |
 |---|---|
 | `PriorityL1` |  |
 | `PriorityL2` |  |
 | `PriorityL3` |  |
 | `PriorityL4` | PriorityL4 仅内核级（内置）插件可用；外部插件声明会被夹到 L3。 |
 ## EventRawInput 等
 | 名称 | 说明 |
 |---|---|
 | `EventRawInput` |  |
 | `EventAgentOutput` |  |
 | `EventAgentLLMChain` |  |
 | `EventToolCall` |  |
 | `EventReasoning` |  |
 | `EventStage` |  |
 | `EventSystem` |  |
 | `EventReasoningDelta` | 流式增量事件（token 级）：核心 process() 流式化后每收到一个增量块发布。 |
 | `EventContentDelta` |  |
 ## StageScopeGlobal 等
 | 名称 | 说明 |
 |---|---|
 | `StageScopeGlobal` | StageScopeGlobal receives all stage events (default). |
 | `StageScopeOwnTools` | StageScopeOwnTools only receives events for this plugin's own tool calls |
 ## CapText 等
 | 名称 | 说明 |
 |---|---|
 | `CapText` |  |
 | `CapFile` |  |
 | `CapImage` |  |
 | `CapAudio` |  |
 | `CapStructured` |  |
 ## ProxyAuthHomeAgent 等
 | 名称 | 说明 |
 |---|---|
 | `ProxyAuthHomeAgent` | ProxyAuthHomeAgent 表示由 HomeAgent 统一保护：浏览器走门户会话 |
 | `ProxyAuthNone` | ProxyAuthNone 表示不经 HomeAgent 鉴权，直接把请求转发给上游。 |
--- a/docs/api/events.md
+++ b/docs/api/events.md
@ -0,0 +1,69 @@
 <!-- 本页由 tools/apidoc/gensite 从源码生成，请勿手改；要改文档就改 sdk/*.go 的注释。 -->
 # 事件（Events）
 订阅内核事件。**注意**：外部分布式插件的事件订阅不走 `Events()`（该接口在外部插件路径上未被注入，恒为 nil），而是由 `hmapdev` 生成的运行时通过 `events.subscribe` 完成。详见下方说明。
 ## `EventSubscriber`
 EventSubscriber allows plugins to subscribe to kernel events.
 This is a restricted interface: plugins can subscribe but the kernel
 controls which events are delivered.
 | 方法 | 说明 |
 |---|---|
 | [`Subscribe`](#eventsubscribersubscribe) |  |
 ### `EventSubscriber.Subscribe`
 !!! warning "仅内核内置插件可用"
 ```go
 Subscribe(eventType EventType, handler EventHandler) func()
 ```
 <small>`plugin.go:378`</small>
 ### `Event`
 ```go
 type Event struct { Type EventType `json:"type"` Source string `json:"source"` Payload map[string]interface{} `json:"payload"` T …
 ```
 Event represents a system event published by the kernel.
 <small>`plugin.go:364`</small>
 ### `EventHandler`
 ```go
 type EventHandler func(evt *Event)
 ```
 EventHandler processes a system event.
 <small>`plugin.go:372`</small>
 ### `EventType`
 ```go
 type EventType string
 ```
 EventType identifies the kind of system event.
 <small>`plugin.go:346`</small>
 ### `PluginSDK.Events`
 !!! warning "仅内核内置插件可用"
    实测全仓 SetEventSubscriber 只有定义、无任何调用点（grep -rn SetEventSubscriber --include=*.go 仅命中 sdk/plugin.go 的定义与 lua_plugin.go 的一句注释）。外部插件拿到的 Events() 恒为 nil。外部插件订阅事件走的是桥接运行时的 events.subscribe RPC（proc_main.go.tmpl:1421 在插件侧分发、内核 protocol.go MethodEventsSubscribe），Lua 插件则走内部 SDK 的 Subscribe。这正是 PLUGIN_DEV.md 里没有说清的一处。
 ```go
 func (s *PluginSDK) Events() EventSubscriber
 ```
 Events returns the event subscriber for listening to kernel events (may be nil if not available).
 <small>`plugin.go:550`</small>
--- a/docs/api/index.md
+++ b/docs/api/index.md
@ -0,0 +1,39 @@
 # API 参考
 本页所有内容**从源码生成**（`tools/apidoc`），签名与说明直接取自 `sdk/*.go` 的
 文档注释。因此不存在「文档写了一套、代码是另一套」的情况——发现不一致时，
 改的是源码注释，不是这里。
 ## 怎么找 API
 <div id="api-search"></div>
 用上面的搜索框可以：
 - **按名称搜**：`InjectText`、`RegisterTool`、`memory.recall`
 - **按描述搜**：`注册工具`、`注入`、`重载`、`崩溃`
 - **按签名搜**：`(string) error`、`[]ContentBlock`
 - 带 <span class="api-badge api-badge-builtin">仅内置</span>
  标记的条目在**外部插件里拿不到**，多数情况下你不需要它
 ## 章节划分
 按「你想做什么」组织，不是按 Go 的符号类别：
 | 章节 | 内容 |
 |---|---|
 | [工具（Tools）](tools.md) | 注册 LLM 可调用的工具——插件最常用的能力形态 |
 | [阶段钩子（Stages）](stages.md) | 在处理管道的固定点位插入逻辑 |
 | [记忆（Memory）](memory.md) | 三层记忆的读写：图 / 文档 / 文本，以及知识库 |
 | [输入/输出通道](channels.md) | 与外界交换消息，以及往流水线里注入内容 |
 | [配置（Settings）](settings.md) | 声明插件配置项，内核渲染到 WebUI |
 | [生命周期（Lifecycle）](lifecycle.md) | 启动、停止、卸载、自动重启 |
 | [事件（Events）](events.md) | 订阅内核事件 |
 | [LLM 调用](llm.md) | 插件主动调用模型 |
 | [常量与枚举](constants.md) | 取值枚举 |
 | [桥接装配点](bridge.md) | 由 `hmapdev` 生成的运行时调用，插件业务代码不碰 |
 | [仅内置插件可用](builtin-only.md) | 边界汇总——外部插件拿不到的 API 全在这里 |
 !!! tip "先看「能力边界」能省很多时间"
    如果你正在设计插件，先读 [能力边界](../guide/capability-boundary.md)：
    它说明哪些能力外部插件有、哪些没有，以及**为什么**。
--- a/docs/api/lifecycle.md
+++ b/docs/api/lifecycle.md
@ -0,0 +1,209 @@
 <!-- 本页由 tools/apidoc/gensite 从源码生成，请勿手改；要改文档就改 sdk/*.go 的注释。 -->
 # 生命周期（Lifecycle）
 插件的启动、停止与卸载回调。停止与卸载是两件事：**停止**是进程/加载状态变化，**卸载**（onRemove）是插件被删除前的清理机会。
 ## `Plugin`
 Plugin is the interface every plugin must implement.
 | 方法 | 说明 |
 |---|---|
 | [`Name`](#pluginname) |  |
 | [`Start`](#pluginstart) |  |
 | [`Stop`](#pluginstop) |  |
 ### `Plugin.Name`
 ```go
 Name() string
 ```
 <small>`plugin.go:14`</small>
 ### `Plugin.Start`
 ```go
 Start(sdk *PluginSDK) error
 ```
 <small>`plugin.go:15`</small>
 ### `Plugin.Stop`
 ```go
 Stop() error
 ```
 <small>`plugin.go:16`</small>
 ## `PluginMgrAPI`
 PluginMgrAPI 提供插件管理能力（外部插件可调用）。
 由 bridge 注入 dispatch 实现，走 C ABI CORE_PLUGIN_RELOAD_ONE 等。
 | 方法 | 说明 |
 |---|---|
 | [`IsPluginDisabled`](#pluginmgrapiisplugindisabled) | IsPluginDisabled 查询插件是否被禁用。 |
 | [`ListLoadedPlugins`](#pluginmgrapilistloadedplugins) | ListLoadedPlugins 列出已加载插件。 |
 | [`ReloadOne`](#pluginmgrapireloadone) | ReloadOne 重载单个插件（停止后重新加载）。 |
 ### `PluginMgrAPI.IsPluginDisabled`
 ```go
 IsPluginDisabled(name string) bool
 ```
 IsPluginDisabled 查询插件是否被禁用。
 <small>`plugin.go:389`</small>
 ### `PluginMgrAPI.ListLoadedPlugins`
 ```go
 ListLoadedPlugins() []string
 ```
 ListLoadedPlugins 列出已加载插件。
 <small>`plugin.go:387`</small>
 ### `PluginMgrAPI.ReloadOne`
 ```go
 ReloadOne(name string) error
 ```
 ReloadOne 重载单个插件（停止后重新加载）。
 <small>`plugin.go:385`</small>
 ### `PluginSDK.AutoRestart`
 ```go
 func (s *PluginSDK) AutoRestart() bool
 ```
 AutoRestart 返回插件是否允许自动重启。
 <small>`plugin.go:895`</small>
 ### `PluginSDK.PluginMgr`
 ```go
 func (s *PluginSDK) PluginMgr() PluginMgrAPI
 ```
 PluginMgr returns the plugin manager API (ReloadOne / ReloadPlugins / list).
 May be nil if the host did not wire it.
 <small>`plugin.go:757`</small>
 ### `PluginSDK.PluginName`
 ```go
 func (s *PluginSDK) PluginName() string
 ```
 PluginName returns the name of the plugin.
 <small>`plugin.go:501`</small>
 ### `PluginSDK.RegisterOnRemoveHandler`
 ```go
 func (s *PluginSDK) RegisterOnRemoveHandler(fn func())
 ```
 RegisterOnRemoveHandler 注册插件被删除（卸载）时的清理回调。
 注册的 handler 会在插件目录被移除前按"后注册先执行"的顺序调用，
 适用于清理外部资源、删除配置表、下线状态等删除后处理。
 可注册多个；执行后清空（一次删除只执行一次）。
 **示例插件里的真实用法**
 | 插件 | 位置 | 代码 |
 |---|---|---|
 | [`calendar`](../examples/index.md#calendar) | `example/calendar/plugin.go:296` | `s.RegisterOnRemoveHandler(p.cleanupData)` |
 | [`memo`](../examples/index.md#memo) | `example/memo/plugin.go:69` | `s.RegisterOnRemoveHandler(p.cleanupData)` |
 | [`rss`](../examples/index.md#rss) | `example/rss/plugin.go:127` | `s.RegisterOnRemoveHandler(p.cleanupData)` |
 <small>`plugin.go:930`</small>
 ### `PluginSDK.RegisterPluginAPI`
 ```go
 func (s *PluginSDK) RegisterPluginAPI(name string) error
 ```
 RegisterPluginAPI registers this plugin's API for access by other plugins.
 <small>`plugin.go:606`</small>
 ### `PluginSDK.RegisterStopHandler`
 ```go
 func (s *PluginSDK) RegisterStopHandler(fn func())
 ```
 RegisterStopHandler 注册插件停止阶段的清理回调。
 注册的 handler 会在插件 Stop() 之前按"后注册先执行"的顺序调用，
 适用于释放资源、落盘状态、关闭子进程等停止时清理操作。
 可注册多个；执行后清空（进程停止前只执行一次）。
 **示例插件里的真实用法**
 | 插件 | 位置 | 代码 |
 |---|---|---|
 | [`calendar`](../examples/index.md#calendar) | `example/calendar/plugin.go:294` | `s.RegisterStopHandler(p.saveEvents)` |
 | [`deepsearch`](../examples/index.md#deepsearch) | `example/deepsearch/plugin.go:695` | `s.RegisterStopHandler(func() { p.shutdownSearxng() })` |
 <small>`plugin.go:905`</small>
 ### `PluginSDK.RunOnRemoveHandlers`
 ```go
 func (s *PluginSDK) RunOnRemoveHandlers()
 ```
 RunOnRemoveHandlers 执行全部已注册的 onRemove handler（后注册先执行，执行后清空，幂等）。
 由内核在卸载插件（registry.RemovePlugin）时、插件 Stop() 之后执行。
 <small>`plugin.go:941`</small>
 ### `PluginSDK.RunStopHandlers`
 ```go
 func (s *PluginSDK) RunStopHandlers()
 ```
 RunStopHandlers 执行全部已注册的 stop handler（后注册先执行，执行后清空，幂等）。
 由内核（内置插件）或插件桥接层（外部插件 z_bridge 的 StopPlugin）在调用插件 Stop() 前执行。
 <small>`plugin.go:916`</small>
 ### `PluginSDK.SetAutoRestart`
 ```go
 func (s *PluginSDK) SetAutoRestart(enabled bool)
 ```
 SetAutoRestart 设置插件崩溃后内核是否自动重启它。
 默认 true。如果插件有无法恢复的状态（如外部连接），应设为 false。
 重启是有限度的：线性退避（第 n 次等 n×1s，即 1s→2s→3s），
 且同一 5 分钟窗口内第 4 次崩溃就停下不再拉起（详见 README）。
 注意这与「重载」（换 plugin.bin 后重新加载）是两回事。
 **示例插件里的真实用法**
 | 插件 | 位置 | 代码 |
 |---|---|---|
 | [`a2a`](../examples/index.md#a2a) | `example/a2a/plugin.go:47` | `s.SetAutoRestart(true)` |
 | [`acp`](../examples/index.md#acp) | `example/acp/plugin.go:47` | `s.SetAutoRestart(true)` |
 | [`ai_image`](../examples/index.md#ai_image) | `example/ai_image/plugin.go:110` | `s.SetAutoRestart(true)` |
 | [`bili`](../examples/index.md#bili) | `example/bili/plugin.go:63` | `s.SetAutoRestart(true)` |
 <small>`plugin.go:888`</small>
--- a/docs/api/llm.md
+++ b/docs/api/llm.md
@ -0,0 +1,50 @@
 <!-- 本页由 tools/apidoc/gensite 从源码生成，请勿手改；要改文档就改 sdk/*.go 的注释。 -->
 # LLM 调用
 让插件自己调用模型（而不是只等模型来调你）。
 ## `LLMAPI`
 LLMAPI provides access to the LLM provider manager.
 | 方法 | 说明 |
 |---|---|
 | [`CurrentSource`](#llmapicurrentsource) |  |
 | [`ListSources`](#llmapilistsources) |  |
 | [`SetSource`](#llmapisetsource) |  |
 ### `LLMAPI.CurrentSource`
 ```go
 CurrentSource() string
 ```
 <small>`llm.go:7`</small>
 ### `LLMAPI.ListSources`
 ```go
 ListSources() []string
 ```
 <small>`llm.go:5`</small>
 ### `LLMAPI.SetSource`
 ```go
 SetSource(name string) error
 ```
 <small>`llm.go:6`</small>
 ### `PluginSDK.LLM`
 ```go
 func (s *PluginSDK) LLM() LLMAPI
 ```
 LLM returns the LLM provider API (may be nil if not available).
 <small>`plugin.go:536`</small>
--- a/docs/api/memory.md
+++ b/docs/api/memory.md
@ -0,0 +1,383 @@
 <!-- 本页由 tools/apidoc/gensite 从源码生成，请勿手改；要改文档就改 sdk/*.go 的注释。 -->
 # 记忆（Memory）
 三层记忆的读写接口：**图记忆**（三元组关系）、**文档记忆**（带元数据的文档）、**文本记忆**（事件流水）。以及知识库。
 ## `DocMemoryAPI`
 DocMemoryAPI provides access to the document vector store.
 | 方法 | 说明 |
 |---|---|
 | [`Insert`](#docmemoryapiinsert) |  |
 | [`InsertWithMedia`](#docmemoryapiinsertwithmedia) | InsertWithMedia 写入文档并关联媒体。attachments 里带 Data 的会落进 |
 | [`Query`](#docmemoryapiquery) |  |
 | [`Remove`](#docmemoryapiremove) |  |
 | [`Stats`](#docmemoryapistats) |  |
 ### `DocMemoryAPI.Insert`
 ```go
 Insert(doc *Doc) error
 ```
 <small>`memory.go:76`</small>
 ### `DocMemoryAPI.InsertWithMedia`
 ```go
 InsertWithMedia(doc *Doc, attachments []MediaAttachment) error
 ```
 InsertWithMedia 写入文档并关联媒体。attachments 里带 Data 的会落进
 内容寻址存储（相同字节只存一份），只带 Digest 的直接引用已有内容。
 媒体成为文档直接持有的一等记忆块：文档向量会融合它们的原生向量，
 因此图片按自己的向量被召回，不依赖任何生成的描述文本。
 <small>`memory.go:81`</small>
 ### `DocMemoryAPI.Query`
 ```go
 Query(text string, topK int) []*Doc
 ```
 <small>`memory.go:75`</small>
 ### `DocMemoryAPI.Remove`
 ```go
 Remove(id string)
 ```
 <small>`memory.go:82`</small>
 ### `DocMemoryAPI.Stats`
 ```go
 Stats() map[string]interface{}
 ```
 <small>`memory.go:83`</small>
 ## `KnowledgeAPI`
 KnowledgeAPI provides access to the knowledge store.
 | 方法 | 说明 |
 |---|---|
 | [`Add`](#knowledgeapiadd) |  |
 | [`List`](#knowledgeapilist) |  |
 | [`Search`](#knowledgeapisearch) |  |
 ### `KnowledgeAPI.Add`
 ```go
 Add(name, content string) error
 ```
 <small>`knowledge.go:6`</small>
 ### `KnowledgeAPI.List`
 ```go
 List() ([]string, error)
 ```
 <small>`knowledge.go:7`</small>
 ### `KnowledgeAPI.Search`
 ```go
 Search(query string, topK int) ([]*Knowledge, error)
 ```
 <small>`knowledge.go:5`</small>
 ## `MemoryAPI`
 MemoryAPI provides access to the graph memory (entity-relation store).
 | 方法 | 说明 |
 |---|---|
 | [`Commit`](#memoryapicommit) |  |
 | [`Introspect`](#memoryapiintrospect) |  |
 | [`MergeEntities`](#memoryapimergeentities) |  |
 | [`Purge`](#memoryapipurge) |  |
 | [`Recall`](#memoryapirecall) |  |
 ### `MemoryAPI.Commit`
 ```go
 Commit(triples []Triple) error
 ```
 <small>`memory.go:6`</small>
 ### `MemoryAPI.Introspect`
 ```go
 Introspect() (map[string]interface{}, error)
 ```
 <small>`memory.go:7`</small>
 ### `MemoryAPI.MergeEntities`
 ```go
 MergeEntities(source, target string) (int, error)
 ```
 <small>`memory.go:8`</small>
 ### `MemoryAPI.Purge`
 ```go
 Purge(criteria map[string]string, mode string) (int, error)
 ```
 <small>`memory.go:9`</small>
 ### `MemoryAPI.Recall`
 ```go
 Recall(query []string, depth int) ([]Entity, []Relation, error)
 ```
 <small>`memory.go:5`</small>
 ## `SocialAPI`
 SocialAPI provides read-only access to the social graph (person profiles and relationships).
 External plugins can query person traits and social networks but cannot modify them.
 | 方法 | 说明 |
 |---|---|
 | [`GetNetwork`](#socialapigetnetwork) |  |
 | [`GetPerson`](#socialapigetperson) |  |
 | [`GetRelations`](#socialapigetrelations) |  |
 | [`GetTrait`](#socialapigettrait) |  |
 | [`ListPersons`](#socialapilistpersons) |  |
 ### `SocialAPI.GetNetwork`
 ```go
 GetNetwork(name string, depth int) ([]*PersonProfile, error)
 ```
 <small>`memory.go:104`</small>
 ### `SocialAPI.GetPerson`
 ```go
 GetPerson(name string) (*PersonProfile, error)
 ```
 <small>`memory.go:101`</small>
 ### `SocialAPI.GetRelations`
 ```go
 GetRelations(name string) ([]SocialRelation, error)
 ```
 <small>`memory.go:103`</small>
 ### `SocialAPI.GetTrait`
 ```go
 GetTrait(name, trait string) (string, bool)
 ```
 <small>`memory.go:102`</small>
 ### `SocialAPI.ListPersons`
 ```go
 ListPersons() ([]string, error)
 ```
 <small>`memory.go:105`</small>
 ## `TextMemoryAPI`
 TextMemoryAPI provides access to chronological text event storage.
 | 方法 | 说明 |
 |---|---|
 | [`Append`](#textmemoryapiappend) |  |
 ### `TextMemoryAPI.Append`
 ```go
 Append(evt TextEvent) error
 ```
 <small>`memory.go:44`</small>
 ### `Doc`
 ```go
 type Doc struct { ID string `json:"id"` Title string `json:"title"` Content string `json:"content"` Score …
 ```
 Doc represents a document in the document store.
 MediaDigests / Attachments 在 Query 返回时由内核填充（仅元数据，不带字节）。
 <small>`memory.go:89`</small>
 ### `PluginSDK.DocMemory`
 ```go
 func (s *PluginSDK) DocMemory() DocMemoryAPI
 ```
 DocMemory returns the document memory API (may be nil if not available).
 <small>`plugin.go:522`</small>
 ### `Entity`
 ```go
 type Entity struct { Name string `json:"name"` Type string `json:"type"` MentionCount int `json:"mention_count"` }
 ```
 Entity represents a named entity in the knowledge graph.
 <small>`memory.go:13`</small>
 ### `Knowledge`
 ```go
 type Knowledge struct { Name string `json:"name"` // Category 是该条目的父分类路径（如 "tech/go"），根下条目为空。 // // 为何加这个字段：对<EFBC9A><E5AFB9> …
 ```
 Knowledge represents a knowledge entry.
 **示例插件里的真实用法**
 | 插件 | 位置 | 代码 |
 |---|---|---|
 | [`recoverydiag`](../examples/index.md#recoverydiag) | `example/recoverydiag/plugin.go:978` | `if p.sdk != nil && p.sdk.Knowledge() != nil {` |
 <small>`knowledge.go:11`</small>
 ### `PluginSDK.Knowledge`
 ```go
 func (s *PluginSDK) Knowledge() KnowledgeAPI
 ```
 Knowledge returns the knowledge store API (may be nil if not available).
 **示例插件里的真实用法**
 | 插件 | 位置 | 代码 |
 |---|---|---|
 | [`recoverydiag`](../examples/index.md#recoverydiag) | `example/recoverydiag/plugin.go:978` | `if p.sdk != nil && p.sdk.Knowledge() != nil {` |
 <small>`plugin.go:529`</small>
 ### `MediaAttachment`
 ```go
 type MediaAttachment struct { Digest string `json:"digest,omitempty"` MIME string `json:"mime,omitempty"` Data []byte `json:"data,omitempty"` Name string `json:"name,omite …
 ```
 TextEvent represents a single text memory event.
 MediaAttachment 描述一份与记忆关联的媒体。
 两个方向共用一个类型：
  - 写入（InsertWithMedia）：给 Data + MIME 就是新内容；只给 Digest 则是引用已有内容。
  - 读出（Query）：内核只填 Digest/MIME，**不回 Data**——
    一次检索可能命中几十张图，把字节全塞回插件会把 ABI 消息撑爆。
    需要字节时拿 Digest 单独取。
 刻意没有 Description 字段：媒体不作为文本被索引，也不带任何生成的描述。
 它只按自己的原生向量被检索与召回；附加文字请写在文档 / 三元组的文本里。
 <small>`memory.go:58`</small>
 ### `PluginSDK.Memory`
 ```go
 func (s *PluginSDK) Memory() MemoryAPI
 ```
 Memory returns the graph memory API (may be nil if not available).
 <small>`plugin.go:508`</small>
 ### `PersonProfile`
 ```go
 type PersonProfile struct { Name string `json:"name"` Traits map[string]string `json:"traits,omitempty"` Relations []SocialRelation `json:"relations,omitemp …
 ```
 PersonProfile represents a person's complete profile (traits + social relations).
 <small>`memory.go:109`</small>
 ### `Relation`
 ```go
 type Relation struct { SourceName string `json:"source_name"` TargetName string `json:"target_name"` RelationType string `json:"relation_type"` Confidence float6 …
 ```
 Relation represents a relationship between two entities.
 <small>`memory.go:20`</small>
 ### `PluginSDK.Social`
 ```go
 func (s *PluginSDK) Social() SocialAPI
 ```
 Social returns the social graph API (may be nil if not available).
 <small>`plugin.go:543`</small>
 ### `SocialRelation`
 ```go
 type SocialRelation struct { Person string `json:"person"` Relation string `json:"relation"` }
 ```
 SocialRelation represents a social relationship between two persons.
 <small>`memory.go:116`</small>
 ### `TextEvent`
 ```go
 type TextEvent struct { Role string `json:"role"` Content string `json:"content"` Timestamp int64 `json:"timestamp"` Channel …
 ```
 <small>`memory.go:65`</small>
 ### `PluginSDK.TextMemory`
 ```go
 func (s *PluginSDK) TextMemory() TextMemoryAPI
 ```
 TextMemory returns the text memory API (may be nil if not available).
 <small>`plugin.go:515`</small>
 ### `Triple`
 ```go
 type Triple struct { Subject string `json:"subject"` Relation string `json:"relation"` Object string `json:"object"` Confidence float64 `json:"c …
 ```
 Triple represents a subject-relation-object triple for the knowledge graph.
 SentenceText 是这条三元组的原句，会写进 sentences 表；媒体引用挂在句子上，
 所以 MediaDigests 非空时内核会保证句子存在（不给就自动合成一句）。
 <small>`memory.go:31`</small>
--- a/docs/api/misc.md
+++ b/docs/api/misc.md
--- a/docs/api/settings.md
+++ b/docs/api/settings.md
@ -0,0 +1,197 @@
 <!-- 本页由 tools/apidoc/gensite 从源码生成，请勿手改；要改文档就改 sdk/*.go 的注释。 -->
 # 配置（Settings）
 声明插件自己的配置项，内核会把它渲染到 WebUI 的设置页，并为每个插件维护独立的配置表。
 ## `SettingsAPI`
 | 方法 | 说明 |
 |---|---|
 | [`DataDir`](#settingsapidatadir) | DataDir returns the plugin-specific data directory (guaranteed to exist): |
 | [`Defs`](#settingsapidefs) | Defs returns config definitions matching the prefix. |
 | [`Dump`](#settingsapidump) | Dump returns all config values. |
 | [`Get`](#settingsapiget) | Get reads the plugin's own config value (config_<name> table). |
 | [`GetCore`](#settingsapigetcore) | GetCore reads the core config table. |
 | [`GetPlugin`](#settingsapigetplugin) | GetPlugin reads another plugin's config table. |
 | [`List`](#settingsapilist) | List returns all keys matching the given prefix. |
 | [`ListCore`](#settingsapilistcore) | ListCore lists core config keys matching the prefix. |
 | [`ListPlugin`](#settingsapilistplugin) | ListPlugin lists another plugin's config keys matching the prefix. |
 | [`Plugins`](#settingsapiplugins) | Plugins returns a list of all plugin config namespaces. |
 | [`RegisterDef`](#settingsapiregisterdef) | RegisterDef registers a config definition for UI display. |
 | [`Set`](#settingsapiset) | Set writes a config value to the plugin's own config table. |
 | [`SetCore`](#settingsapisetcore) | SetCore writes to the core config table. |
 | [`SetPlugin`](#settingsapisetplugin) | SetPlugin writes to another plugin's config table. |
 ### `SettingsAPI.DataDir`
 ```go
 DataDir() string
 ```
 DataDir returns the plugin-specific data directory (guaranteed to exist):
 <daemon data>/plugin_data/<plugin_name>. Plugins should persist any
 runtime files (generated images, caches, downloads) here.
 <small>`settings.go:25`</small>
 ### `SettingsAPI.Defs`
 ```go
 Defs(prefix string) []*ConfigDef
 ```
 Defs returns config definitions matching the prefix.
 <small>`settings.go:40`</small>
 ### `SettingsAPI.Dump`
 ```go
 Dump() map[string]interface{}
 ```
 Dump returns all config values.
 <small>`settings.go:43`</small>
 ### `SettingsAPI.Get`
 ```go
 Get(key string) (interface{}, error)
 ```
 Get reads the plugin's own config value (config_<name> table).
 <small>`settings.go:5`</small>
 ### `SettingsAPI.GetCore`
 ```go
 GetCore(key string) (interface{}, error)
 ```
 GetCore reads the core config table.
 <small>`settings.go:14`</small>
 ### `SettingsAPI.GetPlugin`
 ```go
 GetPlugin(plugin, key string) (interface{}, error)
 ```
 GetPlugin reads another plugin's config table.
 <small>`settings.go:28`</small>
 ### `SettingsAPI.List`
 ```go
 List(prefix string) ([]string, error)
 ```
 List returns all keys matching the given prefix.
 <small>`settings.go:11`</small>
 ### `SettingsAPI.ListCore`
 ```go
 ListCore(prefix string) ([]string, error)
 ```
 ListCore lists core config keys matching the prefix.
 <small>`settings.go:20`</small>
 ### `SettingsAPI.ListPlugin`
 ```go
 ListPlugin(plugin, prefix string) ([]string, error)
 ```
 ListPlugin lists another plugin's config keys matching the prefix.
 <small>`settings.go:34`</small>
 ### `SettingsAPI.Plugins`
 ```go
 Plugins() []string
 ```
 Plugins returns a list of all plugin config namespaces.
 <small>`settings.go:46`</small>
 ### `SettingsAPI.RegisterDef`
 ```go
 RegisterDef(def ConfigDef)
 ```
 RegisterDef registers a config definition for UI display.
 <small>`settings.go:37`</small>
 ### `SettingsAPI.Set`
 ```go
 Set(key string, value interface{}) error
 ```
 Set writes a config value to the plugin's own config table.
 <small>`settings.go:8`</small>
 ### `SettingsAPI.SetCore`
 ```go
 SetCore(key string, value interface{}) error
 ```
 SetCore writes to the core config table.
 <small>`settings.go:17`</small>
 ### `SettingsAPI.SetPlugin`
 ```go
 SetPlugin(plugin, key string, value interface{}) error
 ```
 SetPlugin writes to another plugin's config table.
 <small>`settings.go:31`</small>
 ### `ConfigDef`
 ```go
 type ConfigDef struct { Key string `json:"key"` Default interface{} `json:"default,omitempty"` Type string `json:"type"` DisplayName string …
 ```
 ConfigDef describes a configuration field for the WebUI.
 <small>`settings.go:50`</small>
 ### `PluginSDK.Settings`
 ```go
 func (s *PluginSDK) Settings() SettingsAPI
 ```
 Settings returns the settings API for reading/writing plugin configuration.
 sett 在 New 时一次性写入且无 setter，故不需要加锁。
 **示例插件里的真实用法**
 | 插件 | 位置 | 代码 |
 |---|---|---|
 | [`a2a`](../examples/index.md#a2a) | `example/a2a/plugin.go:68` | `s.Settings().RegisterDef(sdk.ConfigDef{` |
 | [`acp`](../examples/index.md#acp) | `example/acp/plugin.go:63` | `s.Settings().RegisterDef(sdk.ConfigDef{` |
 | [`ai_image`](../examples/index.md#ai_image) | `example/ai_image/plugin.go:114` | `s.Settings().RegisterDef(sdk.ConfigDef{` |
 | [`bili`](../examples/index.md#bili) | `example/bili/plugin.go:67` | `s.Settings().RegisterDef(sdk.ConfigDef{` |
 <small>`plugin.go:505`</small>
--- a/docs/api/stages.md
+++ b/docs/api/stages.md
@ -0,0 +1,154 @@
 <!-- 本页由 tools/apidoc/gensite 从源码生成，请勿手改；要改文档就改 sdk/*.go 的注释。 -->
 # 阶段钩子（Stages）
 在消息处理管道的固定点位插入自己的逻辑。阶段比工具更底层：工具是模型主动调用的，阶段是流程经过时必然触发的。
 ### `StageContext.IsResponded`
 ```go
 func (c *StageContext) IsResponded() bool
 ```
 <small>`plugin.go:213`</small>
 ### `StageContext.Lock`
 ```go
 func (c *StageContext) Lock()
 ```
 **示例插件里的真实用法**
 | 插件 | 位置 | 代码 |
 |---|---|---|
 | [`a2a`](../examples/index.md#a2a) | `example/a2a/plugin.go:158` | `p.sessMu.Lock()` |
 | [`acp`](../examples/index.md#acp) | `example/acp/plugin.go:128` | `p.srvMu.Lock()` |
 | [`bili`](../examples/index.md#bili) | `example/bili/plugin.go:37` | `p.runMu.Lock()` |
 | [`browser`](../examples/index.md#browser) | `example/browser/plugin.go:427` | `p.mu.Lock()` |
 <small>`plugin.go:211`</small>
 ### `StageContext.RLock`
 ```go
 func (c *StageContext) RLock()
 ```
 **示例插件里的真实用法**
 | 插件 | 位置 | 代码 |
 |---|---|---|
 | [`acp`](../examples/index.md#acp) | `example/acp/plugin.go:267` | `p.mu.RLock()` |
 | [`calendar`](../examples/index.md#calendar) | `example/calendar/plugin.go:649` | `p.mu.RLock()` |
 | [`memo`](../examples/index.md#memo) | `example/memo/plugin.go:224` | `p.mu.RLock()` |
 | [`qq`](../examples/index.md#qq) | `example/qq/plugin.go:1152` | `ctx.RLock()` |
 <small>`plugin.go:209`</small>
 ### `StageContext.RUnlock`
 ```go
 func (c *StageContext) RUnlock()
 ```
 **示例插件里的真实用法**
 | 插件 | 位置 | 代码 |
 |---|---|---|
 | [`acp`](../examples/index.md#acp) | `example/acp/plugin.go:273` | `p.mu.RUnlock()` |
 | [`calendar`](../examples/index.md#calendar) | `example/calendar/plugin.go:650` | `defer p.mu.RUnlock()` |
 | [`memo`](../examples/index.md#memo) | `example/memo/plugin.go:229` | `p.mu.RUnlock()` |
 | [`qq`](../examples/index.md#qq) | `example/qq/plugin.go:1155` | `ctx.RUnlock()` |
 <small>`plugin.go:210`</small>
 ### `PluginSDK.RegisterStage`
 ```go
 func (s *PluginSDK) RegisterStage(stage Stage, handler StageHandler, scope ...StageScope)
 ```
 RegisterStage registers a handler for a pipeline stage.
 	scope: StageScopeGlobal (default) — receives all stage events.
 	       StageScopeOwnTools — only before_toolcall/after_toolcall for this plugin's tools.
 **示例插件里的真实用法**
 | 插件 | 位置 | 代码 |
 |---|---|---|
 | [`memo`](../examples/index.md#memo) | `example/memo/plugin.go:152` | `s.RegisterStage(sdk.StagePreAction, p.stagePreAction)` |
 | [`qq`](../examples/index.md#qq) | `example/qq/plugin.go:719` | `s.RegisterStage(sdk.StageOnInput, p.onInputAuthContext, sdk.StageScopeGlobal)` |
 | [`sanitizer`](../examples/index.md#sanitizer) | `example/sanitizer/plugin.go:52` | `s.RegisterStage(sdk.StageOnInput, func(ctx *sdk.StageContext) error {` |
 | [`weather`](../examples/index.md#weather) | `example/weather/plugin.go:94` | `s.RegisterStage(sdk.StageAfterToolcall, func(ctx *sdk.StageContext) error {` |
 <small>`plugin.go:571`</small>
 ### `Stage`
 ```go
 type Stage string
 ```
 Stage represents a point in the message processing pipeline.
 <small>`plugin.go:26`</small>
 ### `StageContext`
 ```go
 type StageContext struct { mu sync.RWMutex RawMessage string UserID string GroupID string ContextMsgs []map[string]interface{} L …
 ```
 StageContext provides context for stage handlers.
 <small>`plugin.go:189`</small>
 ### `StageHandler`
 ```go
 type StageHandler func(ctx *StageContext) error
 ```
 StageHandler is a function that handles a pipeline stage event.
 <small>`plugin.go:23`</small>
 ### `StageRegistrar`
 ```go
 type StageRegistrar func(stage Stage, handler StageHandler)
 ```
 StageRegistrar registers a stage handler.
 <small>`plugin.go:407`</small>
 ### `StageScope`
 ```go
 type StageScope int
 ```
 StageScope controls which events a stage handler receives.
 <small>`plugin.go:393`</small>
 ### `StageContext.Unlock`
 ```go
 func (c *StageContext) Unlock()
 ```
 **示例插件里的真实用法**
 | 插件 | 位置 | 代码 |
 |---|---|---|
 | [`a2a`](../examples/index.md#a2a) | `example/a2a/plugin.go:164` | `p.sessMu.Unlock()` |
 | [`acp`](../examples/index.md#acp) | `example/acp/plugin.go:129` | `defer p.srvMu.Unlock()` |
 | [`bili`](../examples/index.md#bili) | `example/bili/plugin.go:40` | `p.runMu.Unlock()` |
 | [`browser`](../examples/index.md#browser) | `example/browser/plugin.go:432` | `p.mu.Unlock()` |
 <small>`plugin.go:212`</small>
--- a/docs/api/tools.md
+++ b/docs/api/tools.md
@ -0,0 +1,77 @@
 <!-- 本页由 tools/apidoc/gensite 从源码生成，请勿手改；要改文档就改 sdk/*.go 的注释。 -->
 # 工具（Tools）
 注册 LLM 可调用的工具。工具是插件最主要的能力形态：模型看到 `ToolDef` 的说明后决定是否调用，调用时执行你的 `ToolHandler`。
 ### `ContentBlock`
 ```go
 type ContentBlock struct { Type string `json:"type"` Text string `json:"text,omitempty"` ImageURL *ImageURL `json:"image_url,omitempty"` AudioURL *AudioURL `jso …
 ```
 ContentBlock 是多模态内容块（OpenAI 格式：text/image_url/audio_url）。
 插件工具返回结果时可用 PluginSDK.SetToolBlocks 注入，让下一轮 LLM
 请求在 tool message 的 content 数组里带上图片/音频，实现"模型看图/听音频"。
 <small>`plugin.go:954`</small>
 ### `PluginSDK.RegisterTool`
 ```go
 func (s *PluginSDK) RegisterTool(name string, def ToolDef, handler ToolHandler) error
 ```
 RegisterTool registers a tool that the LLM can call.
 **示例插件里的真实用法**
 | 插件 | 位置 | 代码 |
 |---|---|---|
 | [`a2a`](../examples/index.md#a2a) | `example/a2a/plugin.go:76` | `s.RegisterTool(tp+"a2a_query", sdk.ToolDef{` |
 | [`acp`](../examples/index.md#acp) | `example/acp/plugin.go:70` | `s.RegisterTool(tp+"acp_query", sdk.ToolDef{` |
 | [`ai_image`](../examples/index.md#ai_image) | `example/ai_image/plugin.go:159` | `s.RegisterTool(tp+"generate", sdk.ToolDef{` |
 | [`bili`](../examples/index.md#bili) | `example/bili/plugin.go:85` | `s.RegisterTool(tp+"video", sdk.ToolDef{` |
 <small>`plugin.go:557`</small>
 ### `ToolCall`
 ```go
 type ToolCall struct { ID string `json:"id"` Name string `json:"name"` Plugin string `json:"plugin,omitempty …
 ```
 ToolCall represents a model's request to call a tool.
 <small>`plugin.go:227`</small>
 ### `ToolDef`
 ```go
 type ToolDef struct { Name string `json:"name"` Plugin string `json:"plugin,omitempty"` Description string …
 ```
 ToolDef describes a tool that the plugin exposes.
 <small>`plugin.go:279`</small>
 ### `ToolHandler`
 ```go
 type ToolHandler func(args map[string]interface{}) (interface{}, error)
 ```
 ToolHandler is a function that handles a tool call.
 <small>`plugin.go:20`</small>
 ### `ToolResult`
 ```go
 type ToolResult struct { CallID string `json:"call_id"` Name string `json:"name"` Plugin string `json:"plugin,omitempty"` Success bool `json:"suc …
 ```
 ToolResult represents the result of a tool call.
 <small>`plugin.go:235`</small>
--- a/docs/assets/api-index.json
+++ b/docs/assets/api-index.json
--- a/docs/assets/logo-mark.svg
+++ b/docs/assets/logo-mark.svg
@ -0,0 +1,27 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 400" width="400" height="400">
  <g transform="translate(200,200)">
    <circle cx="0" cy="0" r="105" fill="none" stroke="#E2E8F0" stroke-width="2.5" stroke-dasharray="8,6"/>
    <rect x="-130" y="-170" width="36" height="340" rx="8" fill="#3B82F6"/>
    <rect x="94" y="-170" width="36" height="140" rx="8" fill="#CBD5E1"/>
    <rect x="94" y="70" width="36" height="100" rx="8" fill="#CBD5E1"/>
    <rect x="-94" y="-18" width="188" height="36" rx="8" fill="#38BDF8"/>
    <polygon points="0,-28 24.2,14 -24.2,14" fill="#F59E0B" stroke="#F59E0B" stroke-width="8" stroke-linejoin="round"/>
    <circle cx="74" cy="-74" r="14" fill="#DBEAFE" stroke="#3B82F6" stroke-width="2.5"/>
    <line x1="28" y1="-28" x2="63" y2="-63" stroke="#3B82F6" stroke-width="3" stroke-dasharray="6,4" opacity="0.6"/>
    <circle cx="-74" cy="-74" r="14" fill="#EDE9FE" stroke="#8B5CF6" stroke-width="2.5"/>
    <line x1="-28" y1="-28" x2="-63" y2="-63" stroke="#8B5CF6" stroke-width="3" stroke-dasharray="6,4" opacity="0.6"/>
    <circle cx="74" cy="74" r="14" fill="#CFFAFE" stroke="#06B6D4" stroke-width="2.5"/>
    <line x1="28" y1="28" x2="63" y2="63" stroke="#06B6D4" stroke-width="3" stroke-dasharray="6,4" opacity="0.6"/>
    <circle cx="-74" cy="74" r="14" fill="#FEF3C7" stroke="#F59E0B" stroke-width="2.5"/>
    <line x1="-28" y1="28" x2="-63" y2="63" stroke="#F59E0B" stroke-width="3" stroke-dasharray="6,4" opacity="0.6"/>
    <circle cx="0" cy="0" r="42" fill="none" stroke="#F59E0B" stroke-width="4"/>
  </g>
 </svg>
--- a/docs/assets/logo.svg
+++ b/docs/assets/logo.svg
@ -0,0 +1,28 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 400" width="400" height="400">
  <rect width="400" height="400" fill="#F8FAFC"/>
  <g transform="translate(200,200)">
    <circle cx="0" cy="0" r="105" fill="none" stroke="#E2E8F0" stroke-width="2.5" stroke-dasharray="8,6"/>
    <rect x="-130" y="-170" width="36" height="340" rx="8" fill="#3B82F6"/>
    <rect x="94" y="-170" width="36" height="140" rx="8" fill="#CBD5E1"/>
    <rect x="94" y="70" width="36" height="100" rx="8" fill="#CBD5E1"/>
    <rect x="-94" y="-18" width="188" height="36" rx="8" fill="#38BDF8"/>
    <polygon points="0,-28 24.2,14 -24.2,14" fill="#F59E0B" stroke="#F59E0B" stroke-width="8" stroke-linejoin="round"/>
    <circle cx="74" cy="-74" r="14" fill="#DBEAFE" stroke="#3B82F6" stroke-width="2.5"/>
    <line x1="28" y1="-28" x2="63" y2="-63" stroke="#3B82F6" stroke-width="3" stroke-dasharray="6,4" opacity="0.6"/>
    <circle cx="-74" cy="-74" r="14" fill="#EDE9FE" stroke="#8B5CF6" stroke-width="2.5"/>
    <line x1="-28" y1="-28" x2="-63" y2="-63" stroke="#8B5CF6" stroke-width="3" stroke-dasharray="6,4" opacity="0.6"/>
    <circle cx="74" cy="74" r="14" fill="#CFFAFE" stroke="#06B6D4" stroke-width="2.5"/>
    <line x1="28" y1="28" x2="63" y2="63" stroke="#06B6D4" stroke-width="3" stroke-dasharray="6,4" opacity="0.6"/>
    <circle cx="-74" cy="74" r="14" fill="#FEF3C7" stroke="#F59E0B" stroke-width="2.5"/>
    <line x1="-28" y1="28" x2="-63" y2="63" stroke="#F59E0B" stroke-width="3" stroke-dasharray="6,4" opacity="0.6"/>
    <circle cx="0" cy="0" r="42" fill="none" stroke="#F59E0B" stroke-width="4"/>
  </g>
 </svg>
--- a/docs/examples/index.md
+++ b/docs/examples/index.md
@ -0,0 +1,60 @@
 <!-- 本页由 tools/apidoc/gensite 从源码生成，请勿手改；要改文档就改 sdk/*.go 的注释。 -->
 # 示例插件
 SDK 仓 `example/` 下有多个**真实可编译**的示例插件，覆盖工具注册、通道、记忆读写、LLM 调用、生命周期等常见形态。
 每个示例都能用 `hmapdev build` 打成 `.hmap` 装进内核直接跑。
 ## `a2a`
 用到的 API：`Error` · `InjectInputSync` · `Lock` · `RegisterInputChannel` · `RegisterOutputChannel` · `RegisterTool` · `SetAutoRestart` · `Settings` · `Unlock`
 ## `acp`
 用到的 API：`Error` · `InjectInputSync` · `Lock` · `RLock` · `RUnlock` · `RegisterInputChannel` · `RegisterOutputChannel` · `RegisterTool` · `SetAutoRestart` · `Settings` · `Unlock`
 ## `ai_image`
 用到的 API：`Error` · `RegisterTool` · `SetAutoRestart` · `Settings`
 ## `bili`
 用到的 API：`Lock` · `RegisterTool` · `SetAutoRestart` · `Settings` · `Unlock`
 ## `browser`
 用到的 API：`Error` · `InjectInterruptTextOpts` · `InjectTextNoMemory` · `Lock` · `RegisterInputChannel` · `Unlock`
 ## `calendar`
 用到的 API：`InjectInterruptTextOpts` · `RLock` · `RUnlock` · `RegisterInputChannel` · `RegisterOnRemoveHandler` · `RegisterStopHandler`
 ## `deepsearch`
 用到的 API：`RegisterStopHandler`
 ## `memo`
 用到的 API：`InjectInterruptTextOpts` · `RLock` · `RUnlock` · `RegisterOnRemoveHandler` · `RegisterStage`
 ## `qq`
 用到的 API：`InjectInterruptTextOpts` · `RLock` · `RUnlock` · `RegisterOutputChannel` · `RegisterStage`
 ## `recoverydiag`
 用到的 API：`Knowledge`
 ## `rss`
 用到的 API：`RegisterOnRemoveHandler`
 ## `sanitizer`
 用到的 API：`RegisterStage`
 ## `weather`
 用到的 API：`RegisterOutputChannel` · `RegisterStage`
--- a/docs/guide/capability-boundary.md
+++ b/docs/guide/capability-boundary.md
@ -0,0 +1,75 @@
 # 能力边界：哪些 API 外部插件能用
 HomeAgent 有两类插件：
 | 类型 | 说明 | 分发 |
 |---|---|---|
 | **外部插件** | 第三方开发，编译成 `.hmap` 后安装 | 独立分发，**可闭源** |
 | **内置插件** | 编译进内核，`init()` 自注册 | 随内核发行，需合入主仓 |
 SDK 包是**同一个** `gitcode.com/JianFeeeee/homeagent-sdk/sdk`，但两类插件拿到的
 **能力不同**：外部插件跑在独立进程里，由内核通过桥接注入能力（IPC，不是共享内存里的直接调用）。
 本页说明边界在哪、为什么，以及**怎么在写代码前就知道某个 API 是否可用**。
 ## 一句话规则
 > **公开 SDK 包里声明的符号，不等于外部插件拿得到。**
 原因是：有些能力只有进程内的内置插件才可能拥有（比如直接读事件发布通道、
 直接注入到内核 IO 层）。外部插件通过桥接运行时拿到的是一份**受注入的能力集合**。
 ## 外部插件**不可用**的 API
 这些 API 在公开包里存在，但在外部插件路径上拿不到。文档里每条都带
 <span class="api-badge api-badge-builtin">仅内置</span> 标记，
 完整清单见 [仅内置插件可用](../api/builtin-only.md)。
 | API | 外部插件的实际情况 | 该用什么 |
 |---|---|---|
 | `sdk.PluginSDK.Events()` | **恒为 nil**。桥接运行时不注入 event subscriber（`SetEventSubscriber` 全仓无调用点） | 桥接运行时已按你的声明完成 `events.subscribe`；Lua 插件用 `sdk.events.subscribe` |
 | `sdk.PluginSDK.SetEventSubscriber` | 无人调用 | 同上 |
 | `UnregisterOutputChannel` | 桥接只注入 registrar、**不注入 unregistrar**，调用是**静默无效**（返回 nil，不报错也不注销） | `RegisterOutputChannel` 可用；注销需重载插件 |
 | `SocialAPI` 的写操作 | 公开接口只有 6 个**只读**方法 | 读用 `s.GetPerson` 等；写需内置插件 |
 | `EventSubscriber.Publish` | 公开接口**刻意只有 Subscribe**，没有 Publish | 只订阅 |
 | `PriorityL4` | 声明会被内核**夹到 L3** | 用 L1–L3 |
 | `RegisterChannel` / `ListChannels` / `OutputChan` / `InjectInput` / `InjectInterrupt` | 只存在于内核内部 SDK | `RegisterInputChannel` / `RegisterOutputChannel` / `InjectText` 等公开方法 |
 | `PluginMgr()` 的完整能力 | 公开 `PluginMgrAPI` **只有 3 个方法**（`ReloadOne` / `ListLoadedPlugins` / `IsPluginDisabled`） | 就这 3 个；`ReloadPlugins`/`Disable`/`Remove` 属内部接口 |
 !!! warning "两处常见的文档错误（本站已更正）"
    1. **`PluginMgr()` 不是「仅内置可用」**。桥接模板显式注入了它
       （`base.SetPluginMgrAPI(procPluginMgr{})`），公开 `PluginMgrAPI` 也注明
       「外部插件可调用」。真正的区别是**方法数量**：公开面 3 个，内部面 9 个。
       容易混淆是因为两个包里有**同名但不同**的接口：
       `sdk.PluginMgrAPI`（3 方法）与 `internal/sdk.PluginManager`（9 方法）。
    2. **`Events()` 恒为 nil 这件事以前没写清**。旧文档把 `Events()` 当作
       可用的订阅入口，但桥接运行时不注入 subscriber。外部插件的事件订阅
       实际由生成的运行时通过 `events.subscribe` 完成。
 ## 判定依据来自哪里
 本站的「仅内置」标记不是猜的，逐条来自：
 1. **`tools/hmapdev/templates/proc_main.go.tmpl`** —— 外部插件运行时**实际注入**
   哪些能力，看 `buildPluginSDK()` 里的 `base.Set*` 调用。
 2. **`internal/sdk`** —— 内置插件用的完整接口，与公开包对照。
 3. **内核 RPC 协议表**（`internal/plugin/proc/protocol.go`）—— 外部插件**能发哪些请求**。
 每条裁定的具体依据写在该 API 的告警框里，可以直接核对。
 ## 怎么快速确认
 - 用 [API 搜索](../api/index.md) 搜 API 名或功能描述，带
  <span class="api-badge api-badge-builtin">仅内置</span> 的就是外部不可用
 - 直接看 [仅内置插件可用](../api/builtin-only.md) 汇总页
 - 拿不准时，**读 `example/` 下的示例插件** —— 它们全是外部插件，
  能被它们编译通过的写法，外部就一定可用
 ## 为什么这样设计
 不是为了限制，而是**IPC 边界决定了能力边界**：外部插件跑在独立进程里，
 内核只能通过显式的注入点把能力交过去。凡是需要「持有内核内部数据结构」
 的能力（事件发布通道、IO 通道、插件注册表全量操作），进程外都无法安全暴露。
 这套边界同时带来好处：插件崩溃不会带崩内核（进程隔离），
 以及**插件可以闭源**（SDK 是 MIT，见[首页](../index.md#_3)）。
--- a/docs/guide/first-lua-plugin.md
+++ b/docs/guide/first-lua-plugin.md
@ -0,0 +1,111 @@
 # 第一个 Lua 插件
 Lua 插件适合**轻量、快速原型**：不需要 Go 编译环境，改完重启内核即可生效。
 但它有一个必须理解的限制 —— 执行模型是**被动回调**。
 ## 执行模型（先读这段）
 Lua 插件跑在内核进程内的 gopher-lua 解释器里（单 Lua 状态 + 互斥锁）：
 - **被动回调**：`main.lua` 只在加载时执行一次。此后工具、阶段钩子、
  输入输出通道全部由内核事件驱动回调你的 Lua 函数。**插件不能自己启动后台任务。**
 - **没有并发**：Lua 侧没有 goroutine、协程调度，也没有 `os` / `io` 库和 socket 监听。
  唯一主动出站通道是 `sdk.http.get/post`（同步请求）。
 - **任何阻塞循环都会持锁卡死该插件的全部调用。**
 !!! warning "要常驻服务就用 Go 插件"
    需要监听端口、后台轮询、定时任务的，请用 [Go 插件](first-plugin.md)
    （可自行启动 goroutine）。Lua 侧的等价做法是**事件驱动**：把逻辑挂在
    工具、阶段钩子或通道回调上。
 ## 生成工程
 ```bash
 hmapdev init myluaplugin --lua
 cd myluaplugin
 ```
 结构：
 ```
 myluaplugin/
 ├── plg.json    — entry: "main.lua", targets: "lua"
 ├── main.lua    — 插件实现
 ├── sdk.lua     — SDK 模拟层（支持独立测试）
 └── README.md
 ```
 ## 一个完整的插件
 ```lua
 -- main.lua
 local plugin = {
  name = "myluaplugin"
 }
 function plugin.start(sdk)
  sdk.log("info", "myluaplugin starting...")
  sdk.register_tool("myluaplugin_hello", {
    description = "向指定的人打招呼",
    parameters = {
      type = "object",
      properties = {
        who = { type = "string", description = "要打招呼的对象" }
      },
      required = { "who" }
    }
  }, function(args)
    return { content = "hello, " .. (args.who or "world") .. "!" }
  end)
  sdk.log("info", "myluaplugin started")
 end
 function plugin.stop()
  sdk.log("info", "myluaplugin stopped")
 end
 return plugin
 ```
 ## 本地测试
 `sdk.lua` 是纯 Lua 的 SDK 模拟实现，可以直接用解释器跑：
 ```bash
 lua main.lua
 # [lua-plugin] info: myluaplugin starting...
 # [lua-plugin] register_tool: myluaplugin_hello
 # [lua-plugin] info: myluaplugin started
 ```
 在内核里运行时，`sdk.*` 由 Go 层注入，`sdk.lua` 里所有 `-- !impl` 标记的函数
 会被替换成真实实现。
 ## API 约定的两点
 - **注册类函数调用即时报错**（抛 Lua error）—— 注册失败不会静默。
 - **数据类函数统一返回 `(result, err)`**，`err` 为 nil 表示成功。
  核心未装配的子系统（如 SocialAPI）返回空值而非报错。
 Lua 侧的 `sdk.*` 能力与外部 Go 插件对齐至 SDK 1.3.0（需内核 1.4.0+）。
 !!! note "历史提醒"
    1.1–1.3 期间，媒体 / 注入标志位 / 优先级能力只在 Go 侧有，Lua 侧静默缺失。
    现已全量对齐，并由 `internal/plugin/lua_surface_test.go` 的契约测试守住
    「`sdk.lua` 承诺的每个函数都有运行时绑定」。
 ## 构建
 ```bash
 hmapdev build          # → dist/myluaplugin_lua.hmap
 ```
 Lua 插件直接打包源码，不经过编译。
 ## 下一步
 - [能力边界](capability-boundary.md) —— Lua 与 Go 外部插件的能力面一致
 - [打包与发布](packaging.md)
 - [示例](../examples/index.md) —— `example/luademo` 是 Lua 版参考实现
--- a/docs/guide/first-plugin.md
+++ b/docs/guide/first-plugin.md
@ -0,0 +1,162 @@
 # 第一个 Go 插件
 以下是一个**能直接跑起来**的最小插件：注册一个工具、声明一项配置、处理停止与卸载。
 ## 1. 生成工程
 ```bash
 hmapdev init myplugin
 cd myplugin
 ```
 生成的结构：
 ```
 myplugin/
 ├── plg.json       — 插件元信息（名称、版本、入口、目标平台）
 ├── plugin.go      — 插件实现
 ├── go.mod         — 模块定义
 ├── README.md
 └── thirdpart/     — 外部源码存放目录（可选）
 ```
 `hmapdev build` 时会在构建目录自动生成子进程运行时（`z_proc_gen.go` 等），
 **不需要手工创建，也不要提交**。
 ## 2. 插件实现
 插件的全部契约是一个 `Plugin` 接口（[API 参考](../api/lifecycle.md#plugin)）：
 | 方法 | 何时调用 |
 |---|---|
 | `Name() string` | 内核需要标识这个插件时 |
 | `Start(*sdk.PluginSDK) error` | 插件加载后。**在这里注册工具、通道、配置** |
 | `Stop() error` | 插件停止时（重载、禁用、内核退出都会触发） |
 再加一个工厂函数。**名字必须是 `NewPluginFactory`** —— 生成的运行时按这个名字调用：
 ```go
 func NewPluginFactory(name string, config map[string]interface{}) (sdk.Plugin, error) {
    return &Plugin{name: name}, nil
 }
 ```
 !!! warning "不要写成 `NewPlugin`"
    生成的子进程运行时调用的入口是 `NewPluginFactory`。仓库里有 3 个早期示例
    同时保留了两个名字（`NewPlugin` 只是遗留别名），但新插件只写
    `NewPluginFactory` 即可。写错名字的后果是**编译能过、加载时找不到入口**。
 ## 3. 一个完整的例子
 这是一个「打招呼」工具，带一项配置：
 ```go
 package main
 import (
 	"fmt"
 	"gitcode.com/JianFeeeee/homeagent-sdk/sdk"
 )
 type Plugin struct {
 	name string
 	sdk  *sdk.PluginSDK
 }
 func (p *Plugin) Name() string { return p.name }
 func (p *Plugin) Start(s *sdk.PluginSDK) error {
 	p.sdk = s
 	// ① 声明配置项：内核会把它渲染到 WebUI 设置页
 	s.Settings().RegisterDef(sdk.ConfigDef{
 		Key:         "plugin.myplugin.greeting",
 		Default:     "hello",
 		Type:        "string",
 		DisplayName: "问候语",
 		Description: "打招呼时使用的前缀",
 		Category:    "myplugin",
 	})
 	// ② 注册工具：模型看到 Description 后决定是否调用
 	tp := p.name + "_"
 	s.RegisterTool(tp+"hello", sdk.ToolDef{
 		Name:        tp + "hello",
 		Description: "向指定的人打招呼",
 		Parameters: map[string]interface{}{
 			"type": "object",
 			"properties": map[string]interface{}{
 				"who": map[string]interface{}{
 					"type":        "string",
 					"description": "要打招呼的对象",
 				},
 			},
 			"required": []string{"who"},
 		},
 	}, p.handleHello)
 	// ③ 卸载（插件被删除）前清理自己产生的数据。
 	//    注意与 Stop 的区别：Stop 在每次重载时也会触发。
 	s.RegisterOnRemoveHandler(func() {
 		fmt.Printf("[%s] 清理数据\n", p.name)
 	})
 	return nil
 }
 func (p *Plugin) Stop() error { return nil }
 func (p *Plugin) handleHello(args map[string]interface{}) (interface{}, error) {
 	who, _ := args["who"].(string)
 	greeting := "hello"
 	if v, err := p.sdk.Settings().Get("plugin.myplugin.greeting"); err == nil && v != "" {
 		greeting = v
 	}
 	return map[string]interface{}{
 		"content": fmt.Sprintf("%s, %s!", greeting, who),
 	}, nil
 }
 func NewPluginFactory(name string, config map[string]interface{}) (sdk.Plugin, error) {
 	return &Plugin{name: name}, nil
 }
 ```
 ## 4. 工具返回值的两条约定
 `ToolHandler` 返回 `(interface{}, error)`，模型侧看到的是一条 tool message：
 - **正常结果**：返回一个 map，把要展示给模型的文本放在 `content` 字段。
  未识别的字段也会一并传给模型，可以放结构化数据。
 - **业务失败**：返回 `map[string]interface{}{"isError": true, "content": "原因"}`
  **并返回 nil error**。这样模型能看到失败原因并自行调整；
  若返回 Go 的 `error`，那是**工具调用本身出错**，语义不同。
 ```go
 func errorResult(msg string) map[string]interface{} {
 	return map[string]interface{}{"isError": true, "content": msg}
 }
 ```
 ## 5. 构建与安装
 ```bash
 hmapdev build            # 默认产出多平台 bundle
 # → dist/myplugin_bundle.hmap
 hmapdev build --no-bundle  # 只构建当前平台
 # → dist/myplugin_linux_amd64.hmap
 ```
 安装到内核：在 WebUI 的插件管理页上传 `.hmap`，或从 URL / 本地路径安装。
 详见 [打包与发布](packaging.md)。
 ## 下一步
 - [能力边界](capability-boundary.md) —— 哪些 API 外部插件能用
 - [工具（Tools）](../api/tools.md) —— `ToolDef` 的完整字段
 - [记忆（Memory）](../api/memory.md) —— 让插件读写长期记忆
 - [示例插件](../examples/index.md) —— `example/memo` 是个完整的可读实现
--- a/docs/guide/getting-started.md
+++ b/docs/guide/getting-started.md
@ -0,0 +1,68 @@
 # 环境与工具链
 `hmapdev` 是 SDK 仓提供的统一插件开发工具链，Go 与 Lua 两种插件都用它，
 最终产出 `.hmap` 插件包（工具名即取自这个包格式）。
 !!! note "改名说明"
    1.2.0 起工具链由 `plugindev` 更名为 `hmapdev`；SDK 存储目录同时由
    `~/.homeagent/plugindev/sdk` 迁到 `~/.homeagent/hmapdev/sdk`
    （旧目录会自动继续沿用）。
 ## 安装
 从源码构建：
 ```bash
 git clone https://github.com/JianFeeeee/homeagentsdk
 cd homeagentsdk/tools/hmapdev
 go build -o hmapdev
 # 把 hmapdev 放进 PATH，或直接用 ./hmapdev
 ```
 也可以从 SDK 的 release 附件下载预编译二进制（`hmapdev_linux_amd64` 等，
 共 5 个平台：linux/darwin/windows × amd64/arm64）。
 > 仓已迁到 GitHub；gitcode 仅作国内镜像（源码同步，**release 附件暂时仍在那里**）：
 > `https://gitcode.com/JianFeeeee/homeagent-sdk/releases`。
 > Go 模块路径仍是 `gitcode.com/JianFeeeee/homeagent-sdk` —— 这是有意保留的，
 > 改模块路径会让现有插件的 `go.mod` 全面失效。
 ## SDK 版本管理
 `hmapdev` 会维护一份本地 SDK 存储，`init` 时按 `plg.json` 里的 `sdk` 字段
 选择版本。两者**必须**一致，否则编译出的插件与内核协议可能错配。
 ```bash
 hmapdev sdk list            # 已安装的 SDK 版本
 hmapdev sdk current         # 当前使用的版本
 hmapdev sdk latest          # 最新可用版本
 hmapdev sdk install v1.2.0  # 安装指定版本
 hmapdev sdk use v1.2.0      # 切换版本
 hmapdev sdk path            # 当前 SDK 路径
 ```
 存储在 `~/.homeagent/hmapdev/sdk/<version>/`。
 !!! warning "版本未命中会**明确报错**"
    `plg.json` 声明的 `sdk` 版本若不在本地存储里，`hmapdev` 不会退回某个默认版本，
    而是报错并让你先 `hmapdev sdk install`。这是有意的：静默降级会产出与内核
    协议不匹配的插件，那种失败要到运行时才暴露。
 ## 源码调试
 不编译直接跑插件源码，输出调用轨迹：
 ```bash
 hmapdev debug [dir]   # dir 默认当前目录
 ```
 写 Lua 插件时更简单——`sdk.lua` 是 SDK 模拟层，可以直接用解释器跑：
 ```bash
 lua main.lua
 ```
 ## 下一步
 - [第一个 Go 插件](first-plugin.md)
 - [第一个 Lua 插件](first-lua-plugin.md)
--- a/docs/guide/multi-platform.md
+++ b/docs/guide/multi-platform.md
@ -0,0 +1,56 @@
 # 多平台构建
 ## 默认就是多平台
 `hmapdev build` 默认 bundle 模式，一次产出含三个平台的单个 `.hmap`：
 ```
 dist/myplugin_bundle.hmap
  └── plugin.bin.linux.amd64
  └── plugin.bin.darwin.amd64
  └── plugin.bin.windows.amd64
 ```
 安装时内核挑当前平台那份，重命名为 `plugin.bin`。
 ## 逐平台构建
 ```bash
 hmapdev build --no-bundle        # 按 plg.json 的 targets 构建
 hmapdev build --target linux/arm64   # 追加一个目标
 ```
 `plg.json` 里声明目标：
 ```json
 {
  "name": "myplugin",
  "version": "1.0.0",
  "targets": "linux/amd64,windows/amd64"
 }
 ```
 单平台输出文件名：`{name}_{os}_{arch}.hmap`。
 ## 交叉编译
 子进程插件**不再需要 cgo**，所以交叉编译不需要目标平台的 C 工具链 ——
 这是 v1.0.0 的收益之一。
 !!! note "bundle 模式忽略 `targets`"
    固定构建 linux/amd64、darwin/amd64、windows/amd64。如果你只需要其中一个，
    用 `--no-bundle` 更快。
 ## 平台能力差异
 历史上有过一处真实的平台断层，现已消除：
 - **v1.0.0 之前**：Windows 上插件只看到 **3 个 stage 字段、且无法写回**。
 - **v1.0.0 起**：Windows 与其他平台**共用同一套 RPC 实现**，16 字段全可见 + 写回。
 因此**不必**为 Windows 写条件分支 —— 除非你的插件自己用了平台专有的外部命令。
 ## 下一步
 - [打包与发布](packaging.md)
 - [环境与工具链](getting-started.md)
--- a/docs/guide/packaging.md
+++ b/docs/guide/packaging.md
@ -0,0 +1,114 @@
 # 打包与发布
 `hmapdev build` 一次完成编译与打包，产出 `.hmap` 分发包（zip 格式，内含
 `plugin.json` 清单 + 二进制）。
 ## 命令
 ```bash
 hmapdev build                      # 默认 bundle（多平台合集）
 hmapdev build --no-bundle          # 只构建 plg.json targets 里的平台
 hmapdev build --target linux/arm64 # 在 targets 基础上追加目标
 hmapdev build --outdir out         # 指定输出目录（默认 dist）
 hmapdev build --sdk-path <path>    # 覆盖 go.mod 的 replace 指向的 SDK
 hmapdev build --replace <mod@path> # 追加 go.mod replace（可多次）
 ```
 执行流程：
 1. 读 `plg.json` 的 `targets` / `bundle` 决定构建目标
 2. 生成子进程运行时代码（`z_proc_gen.go`、`z_proc_shm_*.go`）
 3. **Go 插件**：`go build`（普通可执行文件，`CGO_ENABLED=0`）
   **Lua 插件**：直接打包源码，不编译
 4. 生成 `plugin.json` 输出清单
 5. 打成 `.hmap`
 ## 两个 JSON 的区别
 这一点经常混淆：
 | 文件 | 谁维护 | 作用 | 关键字段 |
 |---|---|---|---|
 | `plg.json` | **你** | 项目元信息，构建输入 | `targets`、`bundle` |
 | `plugin.json` | `hmapdev` 自动生成 | 构建产物清单 | `entry`、`platforms` |
 `plg.json` 里的 `sdk` 字段声明**本插件针对的 SDK 版本**；未命中本地 SDK 存储
 会明确报错（见[环境与工具链](getting-started.md)）。
 ## 多平台（bundle）
 `build` 默认就是 bundle 模式：一次编译 linux/amd64、darwin/amd64、windows/amd64，
 产出一个含全部平台二进制的 `.hmap`；安装时内核挑当前平台那份。
 ```bash
 hmapdev build              # → dist/myplugin_bundle.hmap
 hmapdev build --no-bundle  # → dist/myplugin_linux_amd64.hmap 等
 ```
 !!! note "bundle 模式会忽略 `plg.json` 的 `targets`"
    固定构建上述三个平台。交叉编译需要对应工具链（如 Linux 上构建 darwin 需要
    clang / macOS SDK），缺工具链时会失败 —— 此时用 `--no-bundle` 只构建当前平台。
 bundle 包内按 `plugin.bin.<goos>.<goarch>` 区分，安装时重命名为 `plugin.bin`。
 ## 产物形态
 子进程插件是**普通可执行文件**，不分平台后缀：
 | 平台 | 二进制 |
 |---|---|
 | Linux / macOS / Windows | `plugin.bin` |
 !!! warning "v1.0.0 破坏性变更：不再加载 `.so` / `.dll`"
    外部插件从 C ABI 动态库改为**子进程 + 共享内存**。
    - `plugin.so` / `plugin.dylib` / `plugin.dll` **不再被加载**。
      新内核遇到旧产物会跳过并报可操作错误，不崩溃。
    - **业务代码不用改一行** —— 公开 SDK 接口零改动，用新版 `hmapdev`
      （原 `plugindev`）重编即可。
    - `plg.json` 的 `entry` 字段对 Go 插件**已无意义**（写 `plugin.so` 也无妨），
      现在只用于区分 Lua 插件。
    - 产物不再需要 cgo，交叉编译无需目标平台 C 工具链。
 ## 安装
 三种方式（`9876` 是 pluginmgr 的本地端口，默认只监听 `127.0.0.1`、无鉴权）：
 ```bash
 # 从 URL 安装（仅 http/https，流式下载不落盘）
 curl -X POST http://127.0.0.1:9876/plugins \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/myplugin.hmap"}'
 # 从本地路径安装（读取文件，不移动原文件）
 curl -X POST http://127.0.0.1:9876/plugins \
  -H "Content-Type: application/json" \
  -d '{"path": "/path/to/myplugin.hmap"}'
 # 直接上传二进制
 curl -X POST http://127.0.0.1:9876/plugins \
  --data-binary @dist/myplugin_bundle.hmap
 ```
 安装后调用 `/api/v1/plugins/reload` 或重启内核生效。
 走 WebUI 的 HTTP API（默认 `8080`，需 `api_key` 鉴权，内部代理到 pluginmgr）：
 ```bash
 curl -X POST http://127.0.0.1:8080/api/v1/plugins \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"path": "/path/to/myplugin.hmap"}'
 ```
 也可以在 WebUI 的插件管理页面上传。
 ## 发布前自查
 - [ ] `plg.json` 的 `sdk` 版本与目标内核匹配
 - [ ] `version` 已递增（内核按版本判断是否需要重装）
 - [ ] 若插件有外部状态，`SetAutoRestart(false)` 或在 `Start` 里重建连接
      （崩溃重启是**线性退避** 1s→2s→3s，5 分钟内第 4 次崩溃即停止，
      见[生命周期](../api/lifecycle.md#pluginsdksetautorestart)）
 - [ ] `RegisterOnRemoveHandler` 里清理自己写下的数据文件
 - [ ] 在 `-race` 下跑一遍：插件的 `Start` 与工具的并发访问是最常见的竞态来源
--- a/docs/guide/parallel-tool-declaration.md
+++ b/docs/guide/parallel-tool-declaration.md
@ -0,0 +1,112 @@
 # 工具并发声明：`ParallelSafe` / `Serial`
 > 对应 `sdk.ToolDef` 的两个字段。内核在**同一轮**收到多个 `tool_call` 时，
 > 依据它们决定并发还是整批串行。
 >
 > 状态：已随 2026-09 的并行内核落地并在生产启用。
 ## 1. 为什么是"保守 opt-in"
 **默认整批串行。** 只有当**批内每一个**工具都显式声明 `ParallelSafe: true`
 时，那一批才并发；**只要有一个不声明，整批退回串行**。
 这不是"漏了声明导致退化"的将就，而是刻意的设计：
 - 存量插件**不改一行**就得到保守行为（整批串行），不会被升级意外并发
 - 声明是**责任**而非特权 —— 声明者必须自己确认线程安全
 - 宁可慢，不可错：一次错误的并发可能让两个工具抢同一个 SQLite 写、
  同一台设备、或同一个输出通道
 ```go
 // 同批全是安全工具 → 并发
 tools: [a(ParallelSafe), b(ParallelSafe)]  ⇒ 并发
 // 只要有一个没声明 → 整批串行
 tools: [a(ParallelSafe), b(默认)]          ⇒ 串行
 ```
 ## 2. 三个条件都满足才可以声明 `ParallelSafe`
 1. **handler 自身线程安全** —— 不持有跨调用的可变状态
 2. **不与同批其它工具争抢同一资源** —— SQLite 写、设备、同一输出通道
 3. **执行顺序无关** —— 顺序敏感的工具应留 `false`，由内核保序
 第 3 条常被忽略：内核能保证**用户可见的消息**按声明顺序落盘，但**工具
 之间的实际执行先后**在并发模式下不确定。有顺序依赖就留 `false`。
 ## 3. `Serial`：显式的反向标记
 ```go
 Serial bool `json:"serial,omitempty"`
 ```
 `ParallelSafe` 的零值 `false` 已经表达"串行"，插件**无法区分**：
 - "我没想过"
 - "我确认过**必须**串行，且有原因"
 一旦工具作者需要把"这里**故意**串行，是有原因的"写进代码（而不只是没填），
 这个区分就是必需的 —— 否则只能靠命名约定传递意图。
 适用场景：读操作但有隐含顺序约束（终端 `read`/`resize` 这类共享会话
 状态）；写操作虽已加锁但需要串行以获得可预测的交错顺序。
 **优先级：`Serial` 胜出。** 即使同时写了 `ParallelSafe: true`，`Serial`
 仍然生效 —— 显式声明"必须串行"不允许被 `ParallelSafe` 或任何默认值覆盖。
 ## 4. 写法
 声明字段放在 `ToolDef` 结构体的**末尾**，遵循既有 `NoMemory` 的风格：
 ```go
 sdk.RegisterTool(sdk.ToolDef{
    Name:        "my_readonly_query",
    Description: "……",
    Parameters:  map[string]interface{}{"type": "object", "properties": map[string]interface{}{}},
    Handler:     h.query,
    ParallelSafe: true,   // 声明在末尾
 }, s)
 ```
 需要"故意串行"时：
 ```go
 sdk.RegisterTool(sdk.ToolDef{
    Name:    "my_terminal_input",
    Handler: h.input,
    Serial:  true,        // 胜出，忽略 ParallelSafe
 }, s)
 ```
 ## 5. 内置工具
 核心仓的内置工具用 `toolDefOptions` / `parallelOpts()` 声明
 （`internal/agent/core/tooldefs.go`），最终由 `buildToolDefs` 汇总成
 `ToolDef.ParallelSafe`。
 内核只提供并行调度基础设施，**不硬编码任何工具名的安全状态表** ——
 状态由每个工具在自己的声明结构里给出，查询时走聚合表。
 ## 6. 效果（实测）
 同批 N 个各约 250ms 的工具，新版内核"内部并发"对"强制串行"：
 | N | 加速比 |
 | --- | --- |
 | 2 | ~1.41× |
 | 4 | ~2.22× |
 | 8 | ~3.88× |
 批耗时几乎不随 N 增长，串行批严格线性。
 > 压测时**必须同时记录实际执行的工具数**，不能只看耗时。
 > 某次对照中旧版本耗时更短、但因适配器缺 `stream_index` 导致
 > **实际处理 0 个工具** —— 那不是性能提升，是全失败。
 ## 相关
 设计背景与踩坑见**核心仓**文档（不在本仓）：
 - `docs/zh/toolcall-contract-and-sequence-design.md` —— 契约与序列设计
 - `docs/zh/toolcall-parallel-execution-plan.md` —— 阶段、实测压测数据
 - `docs/zh/deploy-runbook.md` —— 生产部署（含适配器 `stream_index` 相关）
--- a/docs/guide/scene-memory.md
+++ b/docs/guide/scene-memory.md
@ -0,0 +1,113 @@
 # 场景记忆（Scene Memory）
 > 场景式记忆是内核 v1.3 起的能力。它不新增 API 面，只影响**你的输入被怎样记住与取回**。
 > 与 `NoMemory` / `ContextPolicy` / `RecallPolicy` 并列为第四项声明：`ScenePolicy`。
 ## 它解决什么问题
 三层记忆按**字面相关性**召回：你得说出相近的词，记忆才会被取回来。
 场景记忆补上另一半：按**场合**召回。
 同一场合再次出现时，当时挂在这个场合上的约定、偏好、人物关系会自动回来——
 与这次说了什么措辞无关。
 ```
 你：以后在群里回消息简短点
    └─ 这条记忆挂到场面「chan:qq + peer:group_xxx」上
 一周后，同一个群里有人问「上次说的格式是什么」
    └─ 场面重现（还没等你提到「格式」），那条约定已经被取回
 ```
 ## 场面是自己长出来的
 场景**不需要声明**。每轮交互，内核采集一组可观察信号当这轮<E8BF99><E8BDAE><EFBFBD>「场面指纹」：
 | 特征 | 来源 | 权重 | 说明 |
 |---|---|---|---|
 | `chan` | 输入通道名 | 1.0 | 最强的同一性信号 |
 | `peer` / `peer_group` | 注入点给的 `payload` 里的 `group_id`/`user_id`/`chat_id` 等 | 1.0 | 群与私聊分开，避免互相命中 |
 | `tool` | 触发这一步的工具名 | 0.8 | 行为信号 |
 | `topic` | 清洗后输入的内容词 | 0.4 | 软信号，同场面的不同话题不该被拆开 |
 | `part` | 时段（夜间/上午/下午/晚间） | 0.2 | 最弱，只做辅助 |
 指纹反复重合时，一场场面就成形了。相似度按**加权 Jaccard** 算
 （共享特征的权重和 ÷ 并集的权重和）——不加权的话，一次偶然的话题重合
 会把两个不同场面并成一个。
 **同类场面出现第二次才被认定。** 一次性的交互不建场面：
 那不是「场面」，建了只会让图库被一次性事件撑满。
 ## 声明你的参与姿态
 ```go
 sdk.ChannelDef{
    ScenePolicy: sdk.ScenePolicyNone,  // 这条通道不参与场面识别
 }
 ```
 或单次注入覆盖：
 ```go
 sdk.InjectOptions{
    ScenePolicy: sdk.ScenePolicyNone,
 }
 ```
 | 取值 | 含义 |
 |---|---|
 | `""`（空）/ `ScenePolicyAuto` | **参与**（默认，保持既有行为） |
 | `ScenePolicyNone` | **不参与**：不产任何场面指纹，也不派生场景键 |
 **默认是参与而不是不参与**，与 `ContextPolicy` 刻意相反。原因是场景只
 **附加**检索路径、不改记忆本体，默认关会让存量通道突然失去场景召回；
 而「关」是少数意图（纯内部信号）。
 声明 `none` 之后连时段特征都不产——一个不参与的门面不该在场面索引里
 留下任何足迹。
 ### 谁该考虑关掉
 内核自循环（`system`）、心跳（`timer`）、内部状态汇报（`kernel`）这类
 纯内部信号。它们每次触发都在撑一个场面，会把不相干的交互聚到一起。
 反过来说，**多标一个通道通常没有代价**：一个没人往上面写记忆的场面，
 召回时返回空。关不关都不影响正确性——所以拿不准时，默认参与就好。
 ## 怎么给场面命名
 场景键有两种来源：
 **通道派生（默认）**——`evt.Source` 派生出 `chan:qq` 这类键。你不用管。
 **显式声明（进阶）**——在注入时给出更有语义的键：
 ```go
 p.sdk.InjectInterruptTextOpts("qq", "qq", text, sdk.InjectOptions{
    ScenePolicy: sdk.ScenePolicyAuto,
 })
 ```
 也可以通过 `payload["scene"]` 传层级键（支持 `string` / `[]string` /
 `[]interface{}` 三种形态）：
 ```go
 "chan:qq/peer:group_1027"
 ```
 召回走**前缀匹配**（`chan:qq` 能覆盖 `chan:qq/peer:xxx`），用 `/` 兜底
 以免 `chan:qq` 误吞 `chan:qq2` 这种同前缀但不同层的场景。
 ## 场面记忆不改变什么
 - **不改记忆本体**：场景是记忆的**附加索引**，删掉场景不删记忆。
 - **不让模型负责**：`memory_commit` 的 `scene` 留空即可，内核会挂到本轮
  解析出的场面上。留空是安全的一侧——猜错的场面会把无关记忆钉死。
 - **不影响同步通道**：`webui` / `cli` / 终端走 `ResponseCh`，不经
  `output_send__*`，与场面无关。
 ## 相关 API
 - `ChannelDef.ScenePolicy` —— 通道级声明（见 [输入/输出通道](../api/channels.md)）
 - `InjectOptions.ScenePolicy` —— 单次注入覆盖（见 [其他类型](../api/misc.md)）
 - `ScenePolicyAuto` / `ScenePolicyNone` / `ValidScenePolicy` —— 常量与校验
--- a/docs/guide/security.md
+++ b/docs/guide/security.md
@ -0,0 +1,81 @@
 # 受限 SDK 与安全
 外部插件与内置插件的区别不只是「能不能调某个函数」，还包含一层**安全边界**：
 外部插件的进程不共享内核地址空间，能力通过显式注入点交过去。
 ## 三层隔离
 | 层 | 机制 | 防住了什么 |
 |---|---|---|
 | **进程** | 插件跑在独立子进程 | 插件 panic / 内存越界**不会带崩内核** |
 | **能力** | 只注入显式声明的接口 | 插件拿不到未授权的内核内部结构 |
 | **权限** | 公开接口是内部接口的**只读子集** | 插件无法改写他人数据 |
 第一种是 v1.0.0 从 C ABI 动态库改为子进程 + 共享内存的直接收益：
 在此之前，插件 panic 会带崩 `homed`。
 ## 受限接口是怎么实现的
 **按接口裁剪，而不是按方法裁剪。** 同一个概念在公开包与内部包里是**两个不同的
 接口声明**，公开的那个只保留安全子集：
 ```go
 // 公开 SDK：6 个只读方法
 type SocialAPI interface {
    GetPerson(name string) (*PersonProfile, error)
    GetTrait(name, trait string) (string, bool)
    GetRelations(name string) ([]SocialRelation, error)
    GetNetwork(name string, depth int) ([]*PersonProfile, error)
    ListPersons() ([]string, error)
 }
 ```
 写操作只在内核内部接口里。这样外部插件**在类型层面就调不到**，
 不是靠运行时检查拦截。
 同理，`EventSubscriber` 公开版**刻意只有 `Subscribe`，没有 `Publish`**：
 ```go
 // 插件可以订阅，但由内核决定投递哪些事件
 type EventSubscriber interface {
    Subscribe(eventType EventType, handler EventHandler) func()
 }
 ```
 ## 进程边界带来的约束
 事件订阅是理解这层边界的典型例子。公开包里有一个 `Events() EventSubscriber`，
 但**外部插件拿到的恒为 nil** —— 桥接运行时不注入它（`SetEventSubscriber`
 在全仓没有调用点）。外部插件的事件订阅由生成的运行时通过 `events.subscribe`
 RPC 完成，Lua 插件走内部 SDK 的 `Subscribe`。
 这不是缺陷，而是进程边界的结果：跨进程无法共享内核的事件发布通道。
 详见[能力边界](capability-boundary.md)。
 ## 共享内存中的数据面
 工具调用帧、Cleaner、输入输出通道、媒体块、文档与知识正文**都走共享内存**，
 RPC 只传偏移描述符。因此：
 - 大对象不经 JSON 序列化，避免了大 payload 的性能与内存放大；
 - StageContext 在同一份状态上读改写，消除了副本模型的 lost update
  （实测由 35.8~36.8% 降到 0）。
 `SharedRef`（共享内存描述符）是**内部实现细节**，插件开发者看不到它 ——
 公开 SDK 只暴露普通字符串与 map。
 ## 插件作者的实践建议
 - **不要在 `Start` 里长时间阻塞** —— 内核在等待它返回。
 - **工具处理器要可并发**：模型可能并发发起多个调用；共享状态用锁保护
  （`example/memo` 用 `sync.RWMutex`）。
 - **写文件用原子替换**（临时文件 + rename），避免进程被强杀时截断数据。
 - **声明 `NoMemory`**：定时提醒、连接状态这类不是对话内容的东西，
  别让它们污染记忆（`InjectOptions{NoMemory: true}`）。
 - **在 `-race` 下测**：插件重载瞬间的并发访问是历史高发缺陷。
 ## 许可与分发
 SDK 是 **MIT**，插件可以**闭源分发**，可商用、可私有，无需回馈。
 这是刻意的：SDK 随插件静态链接（源码进入插件二进制），用传染性许可会
 强迫插件开源。内核本身是 AGPL-3.0-only，但那是内核的许可，与外部插件无关。
--- a/docs/guide/stream-tool-call-index.md
+++ b/docs/guide/stream-tool-call-index.md
@ -0,0 +1,108 @@
 # 流式多 `tool_call`：适配器必须透传 `index`
 > 面向在 Lua 里写适配器（`transform_stream_chunk`）的插件作者。
 >
 > 状态：已随 2026-09 的并行内核落地；生产 `openai.lua` 等适配器已修复。
 ## 1. 问题
 OpenAI 兼容的流式响应里，同一轮的多个 `tool_call` 以**分片**形式到达，
 靠 `index` 字段区分归属：
 ```
 data: {"choices":[{"delta":{"tool_calls":[
        {"index":0,"id":"call_a","function":{"name":"alpha","arguments":""}}]}}]}
 data: {"choices":[{"delta":{"tool_calls":[
        {"index":1,"id":"call_b","function":{"name":"beta","arguments":""}}]}}]}
 data: {"choices":[{"delta":{"tool_calls":[
        {"index":0,"function":{"arguments":"{\"x\":1}"}}]}}]}
 data: {"choices":[{"delta":{"tool_calls":[
        {"index":1,"function":{"arguments":"{\"y\":2}"}}]}}]}
 ```
 **每个 SSE chunk 通常只含一个 `tool_call` 元素。** 内核按 `index` 分桶累积
 `id` / `name` / `arguments`。
 ## 2. 适配器必须做的事
 `transform_stream_chunk` 的输出 JSON 里，每个 tool call 分片都要带
 **`stream_index`**（值取上游的 `index`）：
 ```lua
 table.insert(tcs, {
    id = tc.id or "",
    type = tc.type or "function",
    name = name,
    raw_arguments = raw_args,
    -- ★ 必须透传上游 index（键名是 stream_index，不是 index）。
    --   内核按 stream_index 分桶累积同一轮多个 tool_call 的分片。
    stream_index = tc.index or 0
 })
 ```
 ### ★ 键名是 `stream_index`，不是 `index`
 内核的 `ToolCall.StreamIndex` 标签是 `json:"stream_index"`：
 ```go
 StreamIndex int `json:"stream_index,omitempty"`
 ```
 写成 `index` 会被 Go 的解码器**静默丢弃**（无匹配字段），
 `StreamIndex` 恒为 0 ⇒ 全部落进 `accs[0]`。
 ## 3. 不透传的实际后果
 不是"少个字段"，而是**多工具并行调用整体失效**：
 | 现象 | 原因 |
 | --- | --- |
 | `name` 相互覆盖 | 全进 `accs[0]`，后写的赢 |
 | `arguments` 碎片混拼 | 两个工具的 JSON 片段交错拼接 |
 | 报"参数不是合法 JSON" | 上面拼接的产物解析失败 |
 | 工具被当成**空参数**调用 | 同上 |
 2026-09-27 的对照压测里，旧适配器耗时**更短**但**实际处理 0 个工具** ——
 每个工具都因参数非法失败。⇒ 压测**必须同时统计实际执行数**，不能只看耗时。
 ## 4. 还有两个容易踩的点
 **① 不能按 `name` 过滤分片**
 ```lua
 -- ✗ 错：后续块的 name 为空但携带 arguments
 if tc.function and tc.function.name then ... end
 -- ✓ 对：无 name 但有 arguments 的分片也要收，累积时再校验 name
 ```
 **② 扁平结构 + `stream_index`**
 部分协议族（`server` / `kimicode` / `anthropic` / `ollama`）的流式 tool call
 是**扁平**结构（`name`/`arguments` 直接在 `tc` 上，不在 `tc.function` 里），
 同样要带 `stream_index`。
 ## 5. 自检
 ```bash
 # 1) 适配器是否透传
 grep -n "stream_index" /home/newqqagent/adapters/<你的>.lua
 # 2) 实测：发一个同轮多工具的请求，看是否两个都真被执行
 #    内核日志里 executing tool 应出现两次（可能并发）
 journalctl -u homeagent.service --since "-2 min" | grep "executing tool"
 # 3) 有没有参数解析失败
 journalctl -u homeagent.service --since "-2 min" | grep -E "参数|合法 JSON"
 ```
 > `gemini.lua` 目前**没有**流式 tool call 实现，因此不涉及本条。
 > Gemini 协议是 `functionCall` 而非 `tool_calls`，不能照搬 OpenAI 的做法。
 ## 相关
 - `docs/guide/parallel-tool-declaration.md` —— 并发声明 `ParallelSafe`/`Serial`
 - 核心仓 `docs/zh/toolcall-parallel-execution-plan.md` —— 压测数据与协议族清单
--- a/docs/index.md
+++ b/docs/index.md
@ -0,0 +1,49 @@
 # HomeAgent 插件 SDK
 用 **Go** 或 **Lua** 为 HomeAgent 编写插件。插件跑在独立进程里，通过公开 SDK 与内核通信：
 注册工具供模型调用、挂阶段钩子干预流程、读写三层记忆、注册输入输出通道、订阅事件。
 <div id="api-search"></div>
 ## 从这里开始
 <div class="grid cards" markdown>
 -   :material-rocket-launch: **第一次写插件**
    装工具链、生成工程、写一个工具、打包成 `.hmap` 装进内核跑起来。
    [:octicons-arrow-right-24: 快速开始](guide/getting-started.md)
 -   :material-book-open-variant: **API 参考**
    逐个符号的签名与说明，直接取自源码注释。附示例插件里的真实调用点。
    [:octicons-arrow-right-24: 工具（Tools）](api/tools.md)
 -   :material-shield-lock: **能力边界**
    哪些 API 外部插件能用、哪些仅内置插件可用，以及为什么。**先看这个能省很多时间。**
    [:octicons-arrow-right-24: 能力边界](guide/capability-boundary.md)
 -   :material-code-braces: **示例插件**
    `example/` 下有多个真实可编译的插件，覆盖常见形态。
    [:octicons-arrow-right-24: 示例总览](examples/index.md)
 </div>
 ## 许可
 SDK 以 **MIT** 发布 —— 插件作者可**自由选择自己的许可**（闭源、商业、私有均可），
 不必同许可、也不必回馈。原因：SDK 会随插件一起静态链接（源码进入插件二进制），
 若用传染性许可，插件作者就被强制开源；MIT 让第三方插件生态不必承担这个代价。
 内核本身是 **AGPL-3.0-only**，但那是内核的许可，与外部插件无关 ——
 SDK 完全自包含（`go.mod` 零外部依赖，只依赖 Go 标准库），不引用内核任何代码。
 ## 版本
 本文档站的 API 参考从源码生成，对应 SDK 版本见 [版本与兼容](versions.md)。
--- a/docs/javascripts/api-search.js
+++ b/docs/javascripts/api-search.js
@ -0,0 +1,264 @@
 /*
 * API 即时检索。
 *
 * 为什么要自建：Material 内置搜索按「整页文本」建索引，搜 `InjectText`
 * 会把所有提到它的页面都列出来，但**分不清哪一条是它的定义**；而且内置
 * 索引要等 mkdocs build 才生成，改一行 API 也得重建。
 *
 * 这里读的是 `assets/api-index.json`——由 tools/apidoc/gensite 直接产出，
 * 每条记录带 名称/签名/描述/类别/所属页面/是否仅内置/源文件:行号。
 * 因此可以做到：
 *   - 按名称搜（精确/前缀优先）
 *   - 按描述搜（中文按字、英文按词，都对 API 的文档注释做匹配）
 *   - 按签名搜（如 "(string) error"）
 *   - 过滤「仅内置」——外部插件作者最容易被这个绊住
 *
 * 设计取舍：纯前端、零依赖、不阻塞页面。索引 ~130 条、约 40KB，一次拉取足够。
 */
 (function () {
  "use strict";
  var INDEX_URL = (function () {
    // 文档站可能部署在子路径下，按当前页面深度回推到站点根。
    var path = window.location.pathname;
    var marker = "/api/";
    var i = path.indexOf(marker);
    if (i >= 0) return path.slice(0, i) + "/assets/api-index.json";
    // guide/ 等目录同样回退一层。
    var lastSlash = path.lastIndexOf("/");
    return path.slice(0, lastSlash) + "/assets/api-index.json";
  })();
  var state = { all: [], loaded: false, loading: false };
  function load() {
    if (state.loaded || state.loading) return Promise.resolve(state.all);
    state.loading = true;
    return fetch(INDEX_URL)
      .then(function (r) {
        if (!r.ok) throw new Error("HTTP " + r.status);
        return r.json();
      })
      .then(function (data) {
        state.all = data || [];
        state.loaded = true;
        return state.all;
      })
      .catch(function () {
        state.all = [];
        return [];
      });
  }
  /* ---------- 打分 ---------- */
  //
  // 三级优先级：名称命中 > 描述命中 > 签名命中。
  // 名称命中里再分「完全相等 / 前缀 / 子串」，因为用户敲 `InjectText` 时
  // 想要的是那个符号，不是所有名字里含它的。
  function score(item, q) {
    var name = (item.n || "").toLowerCase();
    var ql = q.toLowerCase();
    var s = 0;
    if (name === ql) s += 1000;
    else if (name.indexOf(ql) === 0) s += 600;
    else if (name.indexOf(ql) > 0) s += 350;
    // 中文检索关键词（keywords.json 产出，字段 g）。
    // 为什么需要：SDK 里 66/100 个符号是英文注释（`RegisterTool registers a
    // tool that the LLM can call.`），懂中文的人搜「注册工具」会一条都找不到。
    // 关键词命中给较高权重（仅次于名称精确命中），因为它就是为「按功能找」准备的。
    var kws = item.g || [];
    for (var ki = 0; ki < kws.length; ki++) {
      var kw = String(kws[ki]).toLowerCase();
      if (kw === ql) { s += 480; break; }
      if (kw.indexOf(ql) >= 0) { s += 300; break; }
    }
    // 限定符：PluginSDK.RegisterTool / IOInjector.InjectText。
    // 额外支持「去掉 API/SDK 后缀」与「去掉点号」两种写法，
    // 因为读者习惯写 `memory.recall`（RPC 名），而 Go 名是 `MemoryAPI.Recall`。
    var qual = ((item.r || "") + "." + name).toLowerCase();
    if (item.r && qual.indexOf(ql) >= 0) s += 200;
    if (item.r) {
      var flat = qual.replace(/[._]/g, "").replace(/apis?dk|sdk|api/g, "");
      var qflat = ql.replace(/[._\s]/g, "");
      if (qflat && flat.indexOf(qflat) >= 0) s += 180;
    }
    var desc = (item.d || "").toLowerCase();
    if (desc.indexOf(ql) >= 0) s += 120;
    // 签名按 token 匹配：把查询拆词（去掉括号/逗号等标点），全部命中才算。
    // 这样 `(string) error`、`ContentBlock 媒体` 这类片段都能搜到。
    // 注意必须先去标点：否则 token `(string)` 永远匹配不到签名里的 `string`。
    var sig = (item.s || "").toLowerCase();
    if (sig.indexOf(ql) >= 0) s += 60;
    var toks = ql
      .replace(/[()\[\]{},;:]/g, " ")
      .split(/\s+/)
      .filter(function (t) { return t.length > 1; });
    if (toks.length && sig.length) {
      var allSig = toks.every(function (t) { return sig.indexOf(t) >= 0; });
      if (allSig) s += 55;
    }
    // 中文按字匹配：中文没有词边界，逐字命中比整串更实用。
    // 注意只把它当作**弱信号**：光靠逐字会把「注册工具」匹到凡是含「工具」
    // 字样的任何东西（实测 ContextPolicyNone 的说明里有「工具调用」也会命中）。
    // 所以阈值卡在 60% 以上才算有效命中。
    if (/[\u4e00-\u9fa5]/.test(q)) {
      var hit = 0;
      var hay = desc + " " + kws.join(" ");
      for (var i = 0; i < q.length; i++) {
        if (hay.indexOf(q[i]) >= 0) hit++;
      }
      var ratio = hit / q.length;
      if (ratio >= 0.6) s += Math.round(hit * 6);
    }
    // 公开 API 略优先于「仅内置」——后者通常是噪声。
    if (s > 0 && !item.b) s += 15;
    return s;
  }
  function search(q) {
    var qq = (q || "").trim();
    if (!qq) return [];
    var out = [];
    for (var i = 0; i < state.all.length; i++) {
      var sc = score(state.all[i], qq);
      if (sc > 0) out.push({ item: state.all[i], score: sc });
    }
    out.sort(function (a, b) {
      if (b.score !== a.score) return b.score - a.score;
      return (a.item.n || "").length - (b.item.n || "").length;
    });
    return out;
  }
  /* ---------- 渲染 ---------- */
  //
  // 挂在 Material 首页/目录页的一个容器上：#api-search。
  // 没找到容器就不做任何事——这样同一份 JS 可以安全地全站引入。
  function el(tag, cls, text) {
    var e = document.createElement(tag);
    if (cls) e.className = cls;
    if (text != null) e.textContent = text;
    return e;
  }
  function render(mount, q) {
    mount.innerHTML = "";
    if (!q.trim()) {
      mount.appendChild(el("p", "api-hint",
        "输入 API 名称、描述或签名片段。例：InjectText、注册工具、崩溃、memory.recall、ContentBlock"));
      return;
    }
    var results = search(q);
    if (!results.length) {
      mount.appendChild(el("p", "api-hint", "没有匹配的 API。试试更短的词，或按功能描述搜（如「注入」「重载」）。"));
      return;
    }
    var head = el("p", "api-count", "命中 " + results.length + " 个 API");
    mount.appendChild(head);
    var list = el("ul", "api-results");
    results.slice(0, 40).forEach(function (r) {
      var it = r.item;
      var li = el("li", "api-result");
      var title = el("a", "api-name", (it.r ? it.r + "." : "") + it.n);
      // 锚点必须用**完整标题文本**（`PluginSDK.InjectText`，点号被 slug 丢掉），
      // 不是裸方法名 —— 否则跳到页面顶部而到不了那一条。
      title.href = pageURL(it.p) + "#" + anchorOf((it.r ? it.r + "." : "") + it.n);
      li.appendChild(title);
      if (it.b) {
        var badge = el("span", "api-badge api-badge-builtin", "仅内置");
        badge.title = "外部（第三方）插件运行时拿不到这个 API";
        li.appendChild(badge);
      }
      li.appendChild(el("code", "api-sig", it.s || ""));
      if (it.d) {
        var d = el("span", "api-desc", it.d);
        li.appendChild(d);
      }
      // 关键词是给检索用的；显示出来能让读者明白“为什么这条被匹配到”。
      if (it.g && it.g.length) {
        li.appendChild(el("span", "api-kw", it.g.slice(0, 6).join(" · ")));
      }
      if (it.f) {
        li.appendChild(el("span", "api-loc", it.f + (it.l ? ":" + it.l : "")));
      }
      list.appendChild(li);
    });
    mount.appendChild(list);
  }
  function pageURL(page) {
    if (!page) return "#";
    // 所有 API 章节都在 /api/ 下（生成物），示例页在 /examples/。
    // 从当前 URL 回推到站点根，保证部署在子路径下也能用。
    var path = window.location.pathname;
    var i = path.indexOf("/api/");
    var root;
    if (i >= 0) {
      root = path.slice(0, i + 1);
    } else {
      var j = path.indexOf("/guide/");
      if (j >= 0) root = path.slice(0, j + 1);
      else if (path.indexOf("/examples/") >= 0) root = path.slice(0, path.indexOf("/examples/") + 1);
      else root = path.slice(0, path.lastIndexOf("/") + 1);
    }
    var dir = page === "examples" ? "examples" : "api";
    return root + dir + "/" + page + "/";
  }
  // anchorOf 复现 MkDocs 的 slug：小写、去掉非 [a-z0-9_-] 的字符（点号被去掉）、
  // 下划线保留、空格转连字符。
  function anchorOf(name) {
    return String(name)
      .toLowerCase()
      .replace(/[^a-z0-9_ -]/g, "")
      .replace(/\s+/g, "-");
  }
  function mount() {
    var box = document.getElementById("api-search");
    if (!box) return;
    var input = el("input", "api-input");
    input.type = "search";
    input.placeholder = "搜索 API：名称、描述、签名…";
    input.setAttribute("autocomplete", "off");
    input.setAttribute("spellcheck", "false");
    var out = el("div", "api-output");
    box.appendChild(input);
    box.appendChild(out);
    load().then(function () {
      render(out, "");
      input.addEventListener("input", function () {
        render(out, input.value);
      });
    });
    // 支持 ?q= 直达（可从别处链接到一次检索）。
    var m = /[?&]q=([^&]+)/.exec(window.location.search);
    if (m) {
      input.value = decodeURIComponent(m[1].replace(/\+/g, " "));
    }
  }
  if (document.readyState === "loading") {
    document.addEventListener("DOMContentLoaded", mount);
  } else {
    mount();
  }
 })();
--- a/docs/llms.txt
+++ b/docs/llms.txt
@ -0,0 +1,36 @@
 # HomeAgent 插件 SDK
 > 用 Go 或 Lua 为 HomeAgent 编写插件。插件跑在独立进程里，通过公开 SDK 与内核通信：
 > 注册工具供模型调用、挂阶段钩子干预流程、读写三层记忆、注册输入输出通道、订阅事件。
 >
 > SDK 以 MIT 发布（插件可闭源、可商用，无需回馈）。内核本身是 AGPL-3.0-only。
 >
 > 本文件是给 agent 的入口。下列每个链接都是**纯 Markdown 正文**，可直接读，
 > 不含 HTML 样板；也可以直接取 https://sdk.homeagent.jianfgit.xyz/llms-full.txt 一次读完全部文档。
 - [HomeAgent 插件 SDK](https://sdk.homeagent.jianfgit.xyz/index.md): 用 Go 或 Lua 为 HomeAgent 编写插件
 - [桥接装配点（Bridge）](https://sdk.homeagent.jianfgit.xyz/api/bridge.md): 以下方法不是给插件业务代码调的——它们由 hmapdev 生成的运行时在启动时调用，用来把内核能力注入到 SDK 实例
 - [仅内置插件可用的 API](https://sdk.homeagent.jianfgit.xyz/api/builtin-only.md): 这些 API 存在于公开 SDK 包里，但在外部（第三方）插件的运行路径上不可用：要么桥接运行时根本不注入它（拿到 nil），要么内核会拒绝/降级
 - [输入 / 输出通道](https://sdk.homeagent.jianfgit.xyz/api/channels.md): 通道是插件与外界（设备、其他 Agent、外部系统）交换消息的入口
 - [常量与枚举](https://sdk.homeagent.jianfgit.xyz/api/constants.md): SDK 里的取值枚举
 - [事件（Events）](https://sdk.homeagent.jianfgit.xyz/api/events.md): 订阅内核事件
 - [API 参考](https://sdk.homeagent.jianfgit.xyz/api/index.md): 本页所有内容从源码生成（tools/apidoc），签名与说明直接取自 sdk/*
 - [生命周期（Lifecycle）](https://sdk.homeagent.jianfgit.xyz/api/lifecycle.md): 插件的启动、停止与卸载回调
 - [LLM 调用](https://sdk.homeagent.jianfgit.xyz/api/llm.md): 让插件自己调用模型（而不是只等模型来调你）
 - [记忆（Memory）](https://sdk.homeagent.jianfgit.xyz/api/memory.md): 三层记忆的读写接口：图记忆（三元组关系）、文档记忆（带元数据的文档）、文本记忆（事件流水）
 - [其他类型](https://sdk.homeagent.jianfgit.xyz/api/misc.md): 剩余的类型与方法：PluginSDK 本体的访问器、StageContext 的并发控制，以及多模态辅助类型
 - [配置（Settings）](https://sdk.homeagent.jianfgit.xyz/api/settings.md): 声明插件自己的配置项，内核会把它渲染到 WebUI 的设置页，并为每个插件维护独立的配置表
 - [阶段钩子（Stages）](https://sdk.homeagent.jianfgit.xyz/api/stages.md): 在消息处理管道的固定点位插入自己的逻辑
 - [工具（Tools）](https://sdk.homeagent.jianfgit.xyz/api/tools.md): 注册 LLM 可调用的工具
 - [示例插件](https://sdk.homeagent.jianfgit.xyz/examples/index.md): SDK 仓 example/ 下有多个真实可编译的示例插件，覆盖工具注册、通道、记忆读写、LLM 调用、生命周期等常见形态
 - [能力边界：哪些 API 外部插件能用](https://sdk.homeagent.jianfgit.xyz/guide/capability-boundary.md): HomeAgent 有两类插件：
 - [第一个 Lua 插件](https://sdk.homeagent.jianfgit.xyz/guide/first-lua-plugin.md): Lua 插件适合轻量、快速原型：不需要 Go 编译环境，改完重启内核即可生效
 - [第一个 Go 插件](https://sdk.homeagent.jianfgit.xyz/guide/first-plugin.md): 以下是一个能直接跑起来的最小插件：注册一个工具、声明一项配置、处理停止与卸载
 - [环境与工具链](https://sdk.homeagent.jianfgit.xyz/guide/getting-started.md): hmapdev 是 SDK 仓提供的统一插件开发工具链，Go 与 Lua 两种插件都用它，
 - [多平台构建](https://sdk.homeagent.jianfgit.xyz/guide/multi-platform.md): hmapdev build 默认 bundle 模式，一次产出含三个平台的单个 
 - [打包与发布](https://sdk.homeagent.jianfgit.xyz/guide/packaging.md): hmapdev build 一次完成编译与打包，产出 
 - [工具并发声明：`ParallelSafe` / `Serial`](https://sdk.homeagent.jianfgit.xyz/guide/parallel-tool-declaration.md): > 对应 sdk
 - [场景记忆（Scene Memory）](https://sdk.homeagent.jianfgit.xyz/guide/scene-memory.md): > 场景式记忆是内核 v1
 - [受限 SDK 与安全](https://sdk.homeagent.jianfgit.xyz/guide/security.md): 外部插件与内置插件的区别不只是「能不能调某个函数」，还包含一层安全边界：
 - [流式多 `tool_call`：适配器必须透传 `index`](https://sdk.homeagent.jianfgit.xyz/guide/stream-tool-call-index.md): > 面向在 Lua 里写适配器（transform_stream_chunk）的插件作者
 - [版本与兼容](https://sdk.homeagent.jianfgit.xyz/versions.md): SDK 版本跟随内核的中版本，patch 位恒为 
--- a/docs/stylesheets/extra.css
+++ b/docs/stylesheets/extra.css
@ -0,0 +1,123 @@
 /* API 即时检索与文档站的少量本地样式。
   只补 Material 没覆盖的部分，不覆盖主题变量（保持深浅色自动适配）。 */
 #api-search {
  margin: 1.2rem 0 2rem;
 }
 .api-input {
  width: 100%;
  padding: 0.7rem 0.9rem;
  font-size: 1rem;
  border: 1px solid var(--md-default-fg-color--lightest);
  border-radius: 0.3rem;
  background: var(--md-default-bg-color);
  color: var(--md-default-fg-color);
 }
 .api-input:focus {
  outline: 2px solid var(--md-accent-fg-color);
  outline-offset: 1px;
  border-color: transparent;
 }
 .api-hint {
  color: var(--md-default-fg-color--light);
  font-size: 0.8rem;
  margin: 0.6rem 0 0;
 }
 .api-count {
  color: var(--md-default-fg-color--light);
  font-size: 0.75rem;
  margin: 0.8rem 0 0.4rem;
 }
 .api-results {
  list-style: none;
  margin: 0;
  padding: 0;
 }
 .api-result {
  padding: 0.55rem 0.6rem;
  border-left: 3px solid var(--md-primary-fg-color);
  margin-bottom: 0.4rem;
  background: var(--md-code-bg-color);
  border-radius: 0 0.2rem 0.2rem 0;
  display: flex;
  flex-wrap: wrap;
  align-items: baseline;
  gap: 0.45rem;
 }
 .api-name {
  font-family: var(--md-code-font-family, monospace);
  font-weight: 700;
  font-size: 0.85rem;
 }
 .api-sig {
  font-size: 0.72rem;
  color: var(--md-default-fg-color--light);
  background: none;
  padding: 0;
  overflow-wrap: anywhere;
 }
 .api-desc {
  flex-basis: 100%;
  font-size: 0.78rem;
  color: var(--md-default-fg-color--light);
 }
 /* 「为何命中」的中文关键词（keywords.json 产出）。 */
 .api-kw {
  flex-basis: 100%;
  font-size: 0.7rem;
  color: var(--md-accent-fg-color);
  opacity: 0.9;
 }
 .api-loc {
  flex-basis: 100%;
  font-size: 0.68rem;
  color: var(--md-default-fg-color--lighter, var(--md-default-fg-color--light));
  font-family: var(--md-code-font-family, monospace);
 }
 .api-badge {
  font-size: 0.62rem;
  padding: 0.08rem 0.34rem;
  border-radius: 0.6rem;
  font-weight: 600;
  white-space: nowrap;
 }
 .api-badge-builtin {
  background: rgba(245, 158, 11, 0.18);
  color: #b45309;
  border: 1px solid rgba(245, 158, 11, 0.5);
 }
 [data-md-color-scheme="slate"] .api-badge-builtin {
  color: #fbbf24;
 }
 /* 「仅内置」告警块里的依据说明通常很长，窄屏下允许更小字号。 */
@media screen and (max-width: 44.98em) {
  .api-sig { font-size: 0.68rem; }
 }
 /* 签名与长类型定义可能超出正文宽度（如 ContentBlock 的字段列表）。
   highlight 代码块默认不换行，靠横向滚动；把默认改为换行显示，
   因为文档读者更希望一眼看全签名而不是拖滚动条。 */
 .md-typeset pre > code {
  white-space: pre-wrap;
  overflow-wrap: anywhere;
 }
 /* 接口方法表里的签名可能很长，允许在任意位置折行。 */
 .md-typeset table code {
  overflow-wrap: anywhere;
 }
--- a/docs/versions.md
+++ b/docs/versions.md
@ -0,0 +1,77 @@
 # 版本与兼容
 ## SDK 版本语义
 **SDK 版本跟随内核的中版本，patch 位恒为 `.0`。**
 整条内核 `1.1.x` 线（1.1.0、1.1.1、1.1.7…）共用 **SDK 1.1.0**；
 只有内核进入 `1.2.0` 这种中版本跃迁时，SDK 才升到 1.2.0。
 这样插件作者只需关心「我在为哪个中版本写插件」，不必跟着内核的每个 bugfix 换依赖。
 当前内核声明的兼容上限是 **SDK 1.3.0**。
 ## 版本历史
 | SDK | 内核 | 变化 | 需要重编？ |
 |---|---|---|---|
 | **1.3.0** | 1.4.0+ | 驻留子 agent、`RecallPolicy` 等 | 想用新 API 才需要 |
 | **1.2.0** | 1.2.0 / 1.3.x | `InjectOptions{NoMemory, ContextPolicy}`、六个 `*Opts` 变体、`ChannelDef.ContextPolicy` | 不需要 |
 | **1.1.0** | 1.1.x | 多模态贯通：`Triple.SentenceText`、`Doc.Attachments`、`MediaAttachment`、`InsertWithMedia`、媒体注入方法 | 不需要 |
 | **1.0.0** | 1.0.0+ | **运行模型变更**：C ABI 动态库 → 子进程 + 共享内存 | **需要** |
 ### 1.0.0 是唯一一次破坏性变更
 - `.so` / `.dylib` / `.dll` **不再被加载**，遇到旧产物会跳过并报可操作错误（不崩溃）。
 - **业务代码不用改一行** —— 公开 SDK 接口零改动，用新版 `hmapdev` 重编即可。
 - 产物从 `plugin.so` 变为 `plugin.bin`；不再需要 cgo。
 ### 1.1.0 / 1.2.0 是纯追加
 两次都是**新增方法由插件调用、内核实现**，不调就不受影响。
 零值 `InjectOptions` 与旧的三参数方法完全等价，因此存量插件**不需要改、也不需要重编**；
 想用新字段的重编即可。
 !!! tip "什么时候必须重编"
    只有两种情况：① 内核跨了中版本（如 1.1 → 1.2）且你用了新 API；
    ② 内核的 RPC 协议版本变了（`.hmap` 里的 `protocol` 字段与内核不匹配）。
    后者的错配**不会静默失效** —— 握手时会显式拦下。
 ## RPC 协议版本
 插件包里带 `protocol` 字段，必须等于内核的 `ProtocolVersion`（当前 **2**）。
 协议 v2 引入了调用帧（tool / cleaner / output）与 `blocks_ref` 媒体块。
 v1 插件遇上 v2 内核会拿到空参数，反过来 v2 插件发 `blocks_ref` 会被 v1 内核静默忽略 ——
 **两边错配都不报错、只是静默失效**，所以协议版本在握手上显式校验。
 ## 怎么确认自己在用什么
 装的 SDK 版本：
 ```bash
 hmapdev sdk current
 hmapdev sdk list
 ```
 插件声明的目标版本在 `plg.json` 的 `sdk` 字段。若该版本不在本地存储里，
 `hmapdev` 会**明确报错**，不静默降级 —— 静默降级会产出与内核协议不匹配的包，
 那种失败要到运行时才暴露。
 ## 文档站对应的版本
 本页与 [API 参考](api/index.md) 由 `tools/apidoc` 从源码生成，
 内容随源码一起演进。发现文档与代码不一致时，**改的是源码注释**，
 `go run ./tools/apidoc` 重新生成即可（见下方「维护」）。
 ## 维护（给 SDK 维护者）
 ```bash
 cd homeagent-sdk
 go run ./tools/apidoc -pkgdir ./sdk -out /tmp/api.json
 go run ./tools/apidoc/gensite -api /tmp/api.json -out ./docs -examples ./example
 mkdocs serve     # 本地预览
 mkdocs build     # 产出 site_build/
 ```
 API 面的**能力分层**（哪些 API 仅内置可用）记在 `tools/apidoc/tiers.json`，
 每条裁定都附源码依据 —— 改这里而不是改生成物。
--- a/example/a2a/README.md
+++ b/example/a2a/README.md
@ -0,0 +1,47 @@
 # a2a · Agent-to-Agent 通信
 让本 Agent 与其他 Agent **双向互调**：既能对外暴露自己的能力，也能去问别的 Agent。
 ## 两个方向
 | 方向 | 怎么实现 |
 |---|---|
 | **入站**（别人问我） | 插件起一个 HTTP 服务端，暴露 `/agent-card`（能力描述）与 `/a2a`（JSON-RPC 入口） |
 | **出站**（我问别人） | 提供 `a2a_query` / `a2a_discover` 工具，主动向远端 A2A Agent 发起请求 |
 ## HTTP 端点
 | 路径 | 作用 |
 |---|---|
 | `GET /agent-card` | 返回 Agent Card：本 Agent 的能力描述，供对方发现 |
 | `POST /a2a` | JSON-RPC 2.0 入口，接收对方的任务请求 |
 ## 工具
 | 工具 | 说明 |
 |---|---|
 | `a2a_a2a_query` | 向另一个 A2A Agent 发查询并取回复 |
 | `a2a_a2a_discover` | 取对方的 Agent Card（能力描述） |
 | `a2a_a2a_status` | 看本插件运行状态（监听地址、当前配置） |
 | `a2a_a2a_configure` | 改配置并自动重启服务（可动态改监听地址） |
 | `a2a_a2a_restart` | 重启 HTTP 服务端（连接异常或改配置后用） |
 > 工具名前缀取自插件名（`tp`），按默认 `a2a_` 列出。
 ## 配置项
 | 键 | 默认 | 说明 |
 |---|---|---|
 | `listen` | `127.0.0.1:12000` | 服务端监听地址。**设为空可禁用 HTTP 服务**（只出站、不入站） |
 ## 典型用法
 1. **先发现再调用**：`a2a_discover` 拿对方能力 → 决定要不要发、发什么 → `a2a_query`。
   跳过 discovery 直接问，容易问出对方不支持的东西。
 2. **只出站**：把 `listen` 设为空，本 Agent 不外露端口，但仍能主动联系别人。
 ## 构建
 ```bash
 hmapdev build
 ```
--- a/example/a2a/plg.json
+++ b/example/a2a/plg.json
@ -2,7 +2,7 @@
  "name": "a2a",
  "name_zh": "A2A 代理通信",
  "name_en": "A2A Agent Communication",
-  "version": "1.3.0",
+  "version": "1.3.1",
  "description": "Agent-to-Agent 协议通信插件，支持双向 A2A 通信：可查询其他 Agent 并回复其请求。提供 HTTP 服务端暴露本 Agent 能力。",
  "author": "HomeAgent",
  "entry": "plugin.so",
--- a/example/a2a/plugin.go
+++ b/example/a2a/plugin.go
@ -24,8 +24,8 @@ type Plugin struct {
 	// 会话表：session_id → 上下文前缀。A2A 无状态协议下由插件侧维护
 	// 多轮上下文：同 session 的后续请求会把之前的对话拼进注入文本。
-	sessMu    sync.Mutex
+	sessMu   sync.Mutex
-	sessions  map[string]*a2aSession
+	sessions map[string]*a2aSession
 }
 // a2aSession 记录一个会话的轮次历史，用于延续上下文。
@ -47,6 +47,9 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
 	s.SetAutoRestart(true)
 	p.sdk = s
 	p.sessions = make(map[string]*a2aSession)
 	// 入站通道：本插件用 p.name 通道注入输入（见 InjectInputSync 调用），
 	// 输入侧必须显式登记 —— 否则"把该 inputch 划给驻留子"会报 `inputch 未注册`。
 	_ = s.RegisterInputChannel(p.name, sdk.ChannelDef{})
 	tp := p.name + "_"
 	// 注册自身为输出通道：agent 回复 emit 到本通道时有落点，
@ -66,7 +69,7 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
 		Key: "listen", Default: "127.0.0.1:12000",
 		Type: "string", DisplayName: "监听地址",
 		Description: "A2A 服务端监听地址，设为空可禁用 HTTP 服务",
-		Category: p.name,
+		Category:    p.name,
 	})
 	// Outbound: query + discover
@ -75,10 +78,10 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
 		Parameters: map[string]interface{}{
 			"type": "object",
 			"properties": map[string]interface{}{
-				"agent_url": map[string]interface{}{"type": "string", "description": "目标 Agent 的 A2A 端点 URL"},
+				"agent_url":  map[string]interface{}{"type": "string", "description": "目标 Agent 的 A2A 端点 URL"},
-				"query":     map[string]interface{}{"type": "string", "description": "发送给目标 Agent 的文本查询"},
+				"query":      map[string]interface{}{"type": "string", "description": "发送给目标 Agent 的文本查询"},
 				"session_id": map[string]interface{}{"type": "string", "description": "可选。上次调用返回的 session_id，传入可延续与该 agent 的多轮对话上下文"},
-				"timeout":   map[string]interface{}{"type": "integer", "description": "超时时间（秒），默认 60"},
+				"timeout":    map[string]interface{}{"type": "integer", "description": "超时时间（秒），默认 60"},
 			},
 			"required": []string{"agent_url", "query"},
 		},
@ -287,7 +290,7 @@ func (p *Plugin) handleIncomingA2A(w http.ResponseWriter, r *http.Request) {
 			Query     string `json:"query,omitempty"`
 			SessionID string `json:"session_id,omitempty"`
 			Limit     int    `json:"limit,omitempty"`
-			Message *struct {
+			Message   *struct {
 				Role  string `json:"role"`
 				Parts []struct {
 					Text string `json:"text,omitempty"`
@ -347,7 +350,7 @@ func (p *Plugin) handleIncomingA2A(w http.ResponseWriter, r *http.Request) {
 		if sess := p.sessions[sessionID]; sess != nil {
 			sess.History = append(sess.History, "用户: "+queryText, "助手: "+reply)
 			if len(sess.History) > maxSessionTurns*2 {
-				sess.History = sess.History[len(sess.History)-maxSessionTurns*2 :]
+				sess.History = sess.History[len(sess.History)-maxSessionTurns*2:]
 			}
 			sess.LastUsed = time.Now()
 		}
@ -357,11 +360,11 @@ func (p *Plugin) handleIncomingA2A(w http.ResponseWriter, r *http.Request) {
 			"jsonrpc": "2.0",
 			"id":      req.ID,
 			"result": map[string]interface{}{
-				"id":     fmt.Sprintf("task_%d", time.Now().UnixNano()),
+				"id":         fmt.Sprintf("task_%d", time.Now().UnixNano()),
-				"status": "completed",
+				"status":     "completed",
 				"session_id": sessionID,
 				"message": map[string]interface{}{
-					"role": "agent",
+					"role":  "agent",
 					"parts": []map[string]string{{"type": "text", "text": reply}},
 				},
 			},
@ -457,10 +460,10 @@ type A2AResponse struct {
 }
 type A2AResult struct {
-	TaskID    string       `json:"id,omitempty"`
+	TaskID    string        `json:"id,omitempty"`
-	Status    string       `json:"status,omitempty"`
+	Status    string        `json:"status,omitempty"`
-	SessionID string       `json:"session_id,omitempty"`
+	SessionID string        `json:"session_id,omitempty"`
-	Message   *A2AMessage  `json:"message,omitempty"`
+	Message   *A2AMessage   `json:"message,omitempty"`
 	AgentCard *A2AAgentCard `json:"agent_card,omitempty"`
 }
--- a/example/acp/README.md
+++ b/example/acp/README.md
@ -0,0 +1,51 @@
 # acp · Agent Client Protocol 通信
 [ACP](https://agentclientprotocol.com/) 桥接：本 Agent 既能**当服务端**接别人的任务，也能**当客户端**去调别的 ACP Agent。
 ## 两个方向
 | 角色 | 行为 |
 |---|---|
 | **服务端** | 在本机起 HTTP 服务，处理 `session/new` / `session/update`，接受其他 Agent 的任务请求 |
 | **客户端** | 通过 `acp_query` 向远程 ACP Agent 发 `session/new` 并读回复 |
 ## 协议端点
 - `POST /api/session` —— JSON-RPC，支持 `session/new` 与 `session/update`
 - 客户端侧同时兼容**两种服务端**：SSE 型（流式 `session/reply`）与同步 JSON 型
 ## 工具
 | 工具 | 说明 |
 |---|---|
 | `acp_acp_query` | 向远程 ACP Agent 发起会话并等待回复，返回最终回答文本 |
 | `acp_acp_status` | 查看运行状态与**当前活跃会话数** |
 | `acp_acp_configure` | 改监听配置并重启 HTTP 服务 |
 > 工具名前缀取自插件名（`tp`），按默认 `acp_` 列出。
 `acp_query` 可指向的远端举例（源码注释给的）：
 - opencode：`http://127.0.0.1:13000`
 - pi bridge：`http://127.0.0.1:12011`
 - 回环到自身：`http://127.0.0.1:12001`
 ## 配置项
 | 键 | 默认 | 说明 |
 |---|---|---|
 | `listen` | `127.0.0.1:12001` | 服务端监听地址。**设为空可禁用 HTTP 服务**（只出站） |
 ## 与 a2a 的区别
 | | a2a | acp |
 |---|---|---|
 | 面向 | Agent ↔ Agent 对等通信 | 客户端 → Agent 会话（每次一个 session） |
 | 会话 | 一问一答 | 有 session 生命周期，可续 |
 | 发现 | `/agent-card` | 无（需已知地址） |
 ## 构建
 ```bash
 hmapdev build
 ```
--- a/example/acp/plg.json
+++ b/example/acp/plg.json
@ -2,7 +2,7 @@
  "name": "acp",
  "name_zh": "ACP 代理通信",
  "name_en": "ACP Agent Client Protocol",
-  "version": "1.2.0",
+  "version": "1.2.1",
  "description": "Agent Client Protocol 通信插件：充当 ACP 服务端接受其他 Agent 的任务请求，同时提供客户端工具向远程 ACP Agent（如 opencode）发起会话并读取回复",
  "author": "HomeAgent",
  "entry": "plugin.so",
--- a/example/acp/plugin.go
+++ b/example/acp/plugin.go
@ -47,6 +47,9 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
 	s.SetAutoRestart(true)
 	p.sdk = s
 	p.sessions = make(map[string]*sessionState)
 	// 入站通道：本插件用 p.name 通道注入输入（见 InjectInputSync 调用），
 	// 输入侧必须显式登记 —— 否则"把该 inputch 划给驻留子"会报 `inputch 未注册`。
 	_ = s.RegisterInputChannel(p.name, sdk.ChannelDef{})
 	tp := p.name + "_"
 	// 注册自身为输出通道：agent 回复 emit 到本通道时有落点。
--- a/example/ai_image/README.md
+++ b/example/ai_image/README.md
@ -1,13 +1,34 @@
-# ai_image
+# ai_image · 文生图
-ai_image plugin
+按文字提示生成图片，下载到本地并返回**文件路径**。
-## Build
+## 工具
 | 工具 | 说明 |
 |---|---|
 | `ai_image_generate` | 按 prompt 生成图片 |
 返回值是**本地文件路径**（永久，不过期）。要把图给用户看，再用导出的通道
 以 `type=image`、`payload=<该路径>` 发送。
 ## 配置项
 | 键 | 默认 | 说明 |
 |---|---|---|
 | `api_key` | 空 | OpenAI / Stable Diffusion 的 API Key |
 | `base_url` | 空 | 自定义 OpenAI 兼容网关（**不带 `/v1` 尾缀**，如 `http://127.0.0.1:8081`）。留空走官方 `https://api.openai.com` |
 | `provider` | `openai` | 服务方：`openai` / `stability` |
 | `model` | `dall-e-3` | 模型名（如 `dall-e-3`、`sd-xl`） |
 | `size` | `1024x1024` | 默认尺寸，也可 `1024x1792` / `1792x1024` |
 ## 实现要点
 - **返回本地路径而不是远端 URL**：远端图床链接会过期，写进记忆就成了悬空指针。
  下载到本地后路径稳定，可交给媒体存储做内容寻址。
 - 配了 `base_url` 就能指向自建/兼容网关，不必依赖官方接口。
 ## 构建
 ```bash
-plugindev build
+hmapdev build
 ```
 ## Install
 Upload the .hmap file through the Plugin Manager API.
--- a/example/bili/README.md
+++ b/example/bili/README.md
@ -0,0 +1,43 @@
 # bili · B站视频下载
 用 [yt-dlp](https://github.com/yt-dlp/yt-dlp) 把 B 站视频下载到本地。
 ## 前置依赖
 需要系统里装有 `yt-dlp`：
 ```bash
 pip install -U yt-dlp     # 或 apt install yt-dlp
 ```
 ## 工具
 | 工具 | 说明 |
 |---|---|
 | `bili_video` | 下载 B 站视频；不指定 `format` 时先返回可用清晰度列表，指定后真正下载并返回文件路径 |
 参数：
 | 参数 | 说明 |
 |---|---|
 | `url` | 视频地址 |
 | `format` | 格式 ID。常用：`30112`/`30080`=1080P、`30064`=720P、`30032`=480P、`30016`=360P。不指定则自动选最优 |
 ## 配置项
 | 键 | 默认 | 说明 |
 |---|---|---|
 | `output_dir` | `/tmp/bili_videos` | 下载目录 |
 | `proxy` | 空 | yt-dlp 使用的 HTTP 代理（如 `http://127.0.0.1:7890`）。留空则不设代理 |
 ## 实现要点
 - **`output_dir` 有安全校验**：它是配置项，但会拒绝被配成系统目录，避免 yt-dlp 往任意位置写文件。
 - 两阶段用法：先不传 `format` 拿到清晰度清单（`format_id` + `format_note`），再带上选定的 ID 下载。这样模型不会盲选一个不存在的格式。
 - B 站在部分网络环境下需要代理，见上面的 `proxy`。
 ## 构建
 ```bash
 hmapdev build
 ```
--- a/example/bili/plugin.go
+++ b/example/bili/plugin.go
@ -2,12 +2,15 @@ package main
 import (
 	"bytes"
 	"context"
 	"encoding/json"
 	"fmt"
 	"os"
 	"os/exec"
 	"path/filepath"
 	"strings"
 	"sync"
 	"syscall"
 	"time"
 	"gitcode.com/JianFeeeee/homeagent-sdk/sdk"
@ -17,6 +20,41 @@ type Plugin struct {
 	name  string
 	sdk   *sdk.PluginSDK
 	proxy string
 	// runCancel 取消**正在跑**的 yt-dlp；runWG 等它真正退出。
 	//
 	// 为何需要：下载是分钟级操作，而 Stop() 必须能把它掐掉。
 	// 只 cancel 不 wait 的话内核会在插件死后立刻释放共享段，
 	// 而 yt-dlp 还在往插件的 stdout 写 —— 那正是内核 readLoop 挂死的成因。
 	runMu     sync.Mutex
 	runCancel context.CancelFunc
 	runWG     sync.WaitGroup
 }
 // trackRun 登记一次外部命令运行，返回完成时调用 untrack。
 func (p *Plugin) trackRun() (context.Context, func()) {
 	ctx, cancel := context.WithCancel(context.Background())
 	p.runMu.Lock()
 	p.runCancel = cancel
 	p.runWG.Add(1)
 	p.runMu.Unlock()
 	return ctx, func() {
 		p.runWG.Done()
 		p.runMu.Lock()
 		p.runCancel = nil
 		p.runMu.Unlock()
 	}
 }
 // killRunGroup 掐掉正在跑的 yt-dlp 及其子进程（ffmpeg 等）。
 func (p *Plugin) killRunGroup(pid int) {
 	if pid <= 0 {
 		return
 	}
 	// 负 pid = 整个进程组（yt-dlp 拉起的 ffmpeg 也在内）
 	if err := syscall.Kill(-pid, syscall.SIGKILL); err != nil {
 		_ = syscall.Kill(pid, syscall.SIGKILL)
 	}
 }
 func (p *Plugin) Name() string { return p.name }
@ -30,13 +68,13 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
 		Key: "output_dir", Default: "/tmp/bili_videos",
 		Type: "string", DisplayName: "下载目录",
 		Description: "B站视频下载后的保存目录",
-		Category: p.name,
+		Category:    p.name,
 	})
 	s.Settings().RegisterDef(sdk.ConfigDef{
 		Key: "proxy", Default: "",
 		Type: "string", DisplayName: "HTTP 代理",
 		Description: "yt-dlp 下载使用的 HTTP 代理地址（如 http://127.0.0.1:7890），留空则不设置",
-		Category: p.name,
+		Category:    p.name,
 	})
 	if v, _ := s.Settings().Get("proxy"); v != nil {
 		if str, ok := v.(string); ok {
@ -67,7 +105,24 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
 	return nil
 }
-func (p *Plugin) Stop() error { return nil }
+// Stop 取消并等待正在跑的下载。
 //
 // 空实现的代价（实测）：yt-dlp 是分钟级操作，Stop 时它还在跑，
 // 而它**继承本插件的 stdout**。内核 Kill 掉本插件后，yt-dlp 变孤儿
 // 且继续持有管道写端 ⇒ 内核 readLoop 永远等不到 EOF ⇒ 整个关停挂死
 // 直到 systemd 90 秒超时 SIGKILL（线上症状：只有 bili 报
 // "SIGKILL 后 2s 仍未被收割"，之后近 90 秒无日志）。
 func (p *Plugin) Stop() error {
 	p.runMu.Lock()
 	cancel := p.runCancel
 	p.runMu.Unlock()
 	if cancel != nil {
 		cancel()
 	}
 	// 等它真的退出：不等的话内核会先释放共享段，孙进程仍在写 stdout。
 	p.runWG.Wait()
 	return nil
 }
 type ytdlpFormat struct {
 	FormatID       string  `json:"format_id"`
@ -84,11 +139,11 @@ type ytdlpFormat struct {
 }
 type ytdlpInfo struct {
-	Title       string        `json:"title"`
+	Title      string        `json:"title"`
-	Duration    float64       `json:"duration"`
+	Duration   float64       `json:"duration"`
-	WebpageURL  string        `json:"webpage_url"`
+	WebpageURL string        `json:"webpage_url"`
-	Filename    string        `json:"_filename"`
+	Filename   string        `json:"_filename"`
-	Formats     []ytdlpFormat `json:"formats"`
+	Formats    []ytdlpFormat `json:"formats"`
 }
 func (p *Plugin) handleBiliVideo(args map[string]interface{}) (interface{}, error) {
@ -119,11 +174,20 @@ func (p *Plugin) handleBiliVideo(args map[string]interface{}) (interface{}, erro
 	var out bytes.Buffer
 	ytdlpArgs := []string{"--no-warnings", "--dump-json", url}
-	cmd := exec.Command("yt-dlp", ytdlpArgs...)
+	ctx, done := p.trackRun()
 	defer done()
 	// CommandContext：Stop 里的 cancel 能直接掐掉它。
 	// Setpgid：让 yt-dlp 自成进程组，它再拉的 ffmpeg 也在组内，
 	// killRunGroup 能一次带走整棵子进程树。
 	cmd := exec.CommandContext(ctx, "yt-dlp", ytdlpArgs...)
 	cmd.Stdout = &out
 	cmd.Stderr = &out
 	cmd.Env = proxyEnv(p.proxy)
 	setPgid(cmd)
 	if err := cmd.Run(); err != nil {
 		if ctx.Err() != nil {
 			return nil, fmt.Errorf("yt-dlp info 已取消（插件停止）")
 		}
 		return nil, fmt.Errorf("yt-dlp info: %w\n%s", err, strings.TrimSpace(out.String()))
 	}
@ -209,12 +273,16 @@ func (p *Plugin) handleBiliVideo(args map[string]interface{}) (interface{}, erro
 		dlArgs = append(dlArgs, "-f", format)
 	}
 	dlArgs = append(dlArgs, url)
-	cmd2 := exec.Command("yt-dlp", dlArgs...)
+	cmd2 := exec.CommandContext(ctx, "yt-dlp", dlArgs...)
 	cmd2.Env = proxyEnv(p.proxy)
 	var dlOut bytes.Buffer
 	cmd2.Stdout = &dlOut
 	cmd2.Stderr = &dlOut
 	setPgid(cmd2)
 	if err := cmd2.Run(); err != nil {
 		if ctx.Err() != nil {
 			return nil, fmt.Errorf("下载已取消（插件停止）")
 		}
 		return nil, fmt.Errorf("yt-dlp download: %w\n%s", err, strings.TrimSpace(dlOut.String()))
 	}
@ -256,6 +324,15 @@ func (p *Plugin) handleBiliVideo(args map[string]interface{}) (interface{}, erro
 	}, nil
 }
 // setPgid 让命令自成进程组：它自己拉的子进程（yt-dlp → ffmpeg）
 // 都在同一组里，kill(-pgid) 能一次带走，避免孤儿持有 stdout 管道。
 func setPgid(cmd *exec.Cmd) {
 	if cmd.SysProcAttr == nil {
 		cmd.SysProcAttr = &syscall.SysProcAttr{}
 	}
 	cmd.SysProcAttr.Setpgid = true
 }
 func proxyEnv(proxy string) []string {
 	env := os.Environ()
 	if proxy != "" {
--- a/example/browser/README.md
+++ b/example/browser/README.md
@ -0,0 +1,66 @@
 # browser · 统一浏览器
 一个插件覆盖三种"访问网页"的能力，从最轻到最重。**按需选层**是这个插件的重点 ——
 绝大多数抓取用 HTTP 就够，不该为了一句话启动 Chromium。
 ## 三种能力层
 | 层 | 工具 | 何时用 |
 |---|---|---|
 | **搜索** | `browser_search` | 要的是"找到哪些页面"，不是页面本身 |
 | **quick（纯 HTTP）** | `browser_fetch`（`mode=quick`） | 静态页、API、能直接拿到 HTML |
 | **normal（无头渲染）** | `browser_render` / `browser_fetch`（`mode=render`） | JS 渲染的页面，HTTP 拿不到内容 |
 | **interactive（CDP）** | `browser_start` + `navigate`/`click`/`type`/`scroll`/`html`/`screenshot` | 需要交互：登录、点按、翻页 |
 `browser_fetch` 的 `mode`：
 - `auto`（默认）：先试 HTTP，**遇 403/429 才降级**用 Chromium 渲染
 - `render`：强制 Chromium
 - `quick`：纯 HTTP，不降级
 ## 工具
 | 工具 | 说明 |
 |---|---|
 | `browser_search` | 网页搜索 |
 | `browser_fetch` | 抓取 URL 内容，三种 mode 见上 |
 | `browser_render` | 无头 Chromium 渲染并提取文本（normal） |
 | `browser_start` | 启动交互式浏览器会话（CDP） |
 | `browser_navigate` | 导航到指定 URL |
 | `browser_click` | 点击元素 |
 | `browser_type` | 输入文本 |
 | `browser_scroll` | 滚动页面 |
 | `browser_html` | 取当前页 HTML |
 | `browser_screenshot` | 截图 |
 | `browser_install` | 安装 systemd 托管的共享浏览器后端 |
 | `browser_close` | 关闭会话 |
 ## 共享浏览器后端
 `browser_install` 安装 `homeagent-browser.service`（systemd 托管）。
 装上之后**所有 agent 共享同一个 Chromium 实例与登录态**，各自占独立标签页互不干扰
 （同 source 复用自己的标签页）。
 前提：本机已有 chromium 二进制，没有会提示先装（`apt install chromium` 或等价）。
 ## 实现要点
 - **搜索用 `cn.bing.com` 而不是 `www.bing.com`**：后者对程序化请求常回 302（同意/重定向页），
  根本拿不到结果块。
 - **标题取 `<h2>` 里的 `<a>`**：直接抓结果块里第一个 `<a>` 会拿到来源行而非标题。
 - **摘要认 `b_lineclamp`**：旧版 Bing 用 `b_caption`，新版已迁走，两套都匹配。
 - **有 SSRF 防护**：见源码 `SSRF` 段，抓取前校验目标地址，避免被诱导访问内网。
 ## 测试
 ```bash
 go test -count=1 ./...
 ```
 `testdata/bing_cn.html` 是搜索解析的固定样本，用它做离线断言，避免测试依赖真实网络。
 ## 构建
 ```bash
 hmapdev build
 ```
--- a/example/browser/plg.json
+++ b/example/browser/plg.json
@ -2,7 +2,7 @@
  "name": "browser",
  "name_zh": "浏览器",
  "name_en": "Browser",
-  "version": "2.3.0",
+  "version": "2.4.1",
  "description": "统一浏览器插件：搜索、HTTP抓取(quick)、无头渲染(normal)、交互式浏览器(interactive/CDP)",
  "author": "HomeAgent",
  "entry": "plugin.so",
--- a/example/browser/plugin.go
+++ b/example/browser/plugin.go
@ -6,6 +6,7 @@ import (
 	"encoding/base64"
 	"encoding/json"
 	"fmt"
 	"html"
 	"io"
 	"log"
 	"net"
@ -45,20 +46,20 @@ type Plugin struct {
 	// 登录态/cookies 跨 agent、跨会话、跨插件重启保留），每个 start 创建一个
 	// 新标签页（CDP Target）。同 source 复用自己的标签页。浏览器进程在
 	// 最后一个标签页关闭后保留（避免反复冷启动），仅插件 Stop 时回收。
-	sharedAllocCtx  context.Context
+	sharedAllocCtx    context.Context
 	sharedAllocCancel context.CancelFunc
-	sharedMu        sync.Mutex
+	sharedMu          sync.Mutex
 }
 type BrowserSession struct {
-	id        string
+	id         string
-	allocCtx  context.Context // 共享浏览器进程上下文（shared=true 时指向全局单例）
+	allocCtx   context.Context // 共享浏览器进程上下文（shared=true 时指向全局单例）
-	cancel    context.CancelFunc
+	cancel     context.CancelFunc
-	ctx       context.Context // 本会话的 Target 上下文（一个标签页）
+	ctx        context.Context // 本会话的 Target 上下文（一个标签页）
-	createdAt time.Time
+	createdAt  time.Time
-	timeout   time.Duration
+	timeout    time.Duration
-	closed    bool
+	closed     bool
-	mu        sync.Mutex
+	mu         sync.Mutex
 	currentURL string
 	shared     bool   // true=共享浏览器的一个标签页；false=独占浏览器实例
 	profileDir string // 非空表示使用持久化 profile（关闭时不删目录）
@ -159,6 +160,18 @@ func errResult(msg string) map[string]interface{} {
 	return map[string]interface{}{"isError": true, "content": msg}
 }
 func parseBrowserSessionTimeout(args map[string]interface{}) (time.Duration, error) {
 	raw := strings.TrimSpace(readArg(args, "timeout", ""))
 	if raw == "" {
 		return 0, fmt.Errorf("timeout is required；创建浏览器会话时必须明确指定关闭时长，如 15m 或 2h")
 	}
 	timeout, err := time.ParseDuration(raw)
 	if err != nil || timeout <= 0 {
 		return 0, fmt.Errorf("invalid timeout %q；请使用大于 0 的时长，如 15m 或 2h", raw)
 	}
 	return timeout, nil
 }
 func newHTTPClient(timeout int, proxyURL string) *http.Client {
 	transport := &http.Transport{
 		DialContext: (&net.Dialer{
@ -191,6 +204,9 @@ func newHTTPClient(timeout int, proxyURL string) *http.Client {
 func (p *Plugin) Start(s *sdk.PluginSDK) error {
 	p.sdk = s
 	s.SetAutoRestart(true)
 	// 入站通道：本插件用 p.name 通道注入输入（见 InjectInputSync 调用），
 	// 输入侧必须显式登记 —— 否则"把该 inputch 划给驻留子"会报 `inputch 未注册`。
 	_ = s.RegisterInputChannel(p.name, sdk.ChannelDef{})
 	s.Settings().RegisterDef(sdk.ConfigDef{
 		Key: "timeout", Default: "30", Type: "int",
@ -276,14 +292,15 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
 	s.RegisterTool(tp+"start", sdk.ToolDef{
 		Name:        tp + "start",
-		Description: "启动交互式浏览器会话。优先连接 systemd 托管的共享浏览器后端（登录态全机共享、各 agent 独立标签页）；后端未安装时返回 need_install 引导（调 browser_install）；无法安装时自动降级本地临时模式。同来源复用已有标签页。",
+		Description: "启动交互式浏览器会话。Agent 必须在创建时明确指定 timeout；到期后插件关闭标签页。同来源复用已有标签页时，也按本次 timeout 重新设定关闭时间。",
 		Parameters: map[string]interface{}{
 			"type": "object",
 			"properties": map[string]interface{}{
 				"url":     map[string]interface{}{"type": "string", "description": "初始导航 URL（可选）"},
-				"timeout": map[string]interface{}{"type": "string", "description": "会话超时(如 5m, 10m，默认 10m)"},
+				"timeout": map[string]interface{}{"type": "string", "description": "必填，会话关闭前的存活时长，如 15m、2h；必须大于 0"},
 				"profile": map[string]interface{}{"type": "string", "description": "持久化档案名（可选，如 main）。同名档案共享登录态与浏览历史；不指定则为一次性临时会话"},
 			},
 			"required": []string{"timeout"},
 		},
 	}, p.handleBrowserStart)
@ -471,7 +488,9 @@ type searchResult struct {
 }
 func (p *Plugin) bingSearch(query string, count int) ([]searchResult, error) {
-	u := fmt.Sprintf("https://www.bing.com/search?q=%s&count=%d", url.QueryEscape(query), count)
+	// 用 cn.bing.com：www.bing.com 对程序化请求常回 302（同意/重定向页），拿不到结果块。
 	// 另：Bing 忽略 count 参数，翻页靠 first=，这里保留 count 只为兼容旧调用语义。
 	u := fmt.Sprintf("https://cn.bing.com/search?q=%s&first=1&count=%d&setlang=zh-CN", url.QueryEscape(query), count)
 	req, _ := http.NewRequest("GET", u, nil)
 	req.Header.Set("User-Agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36")
 	req.Header.Set("Accept-Language", "zh-CN,zh;q=0.9,en;q=0.8")
@ -481,38 +500,112 @@ func (p *Plugin) bingSearch(query string, count int) ([]searchResult, error) {
 	}
 	defer resp.Body.Close()
 	body, _ := io.ReadAll(resp.Body)
-	return parseBingResults(string(body), count), nil
+	if resp.StatusCode != http.StatusOK {
 		return nil, fmt.Errorf("Bing 返回 HTTP %d（%d 字节）", resp.StatusCode, len(body))
 	}
 	results := parseBingResults(string(body), count)
 	if len(results) == 0 {
 		// 关键：把「解析不出来」与「真的没结果」区分开。
 		// 以前两者都变成 "No results found."，版式一变就静默退化成「搜不到」。
 		return nil, fmt.Errorf("Bing 返回 %d 字节但未解析出结果（可能被反爬或版式变更，可改用 deepsearch 插件）", len(body))
 	}
 	return results, nil
 }
-func parseBingResults(html string, count int) []searchResult {
+var (
 	bingBlockRe   = regexp.MustCompile(`<li class="b_algo"`)
 	bingTitleRe   = regexp.MustCompile(`(?s)<h2[^>]*>\s*<a[^>]+href="([^"]+)"[^>]*>(.*?)</a>`)
 	bingAnyLinkRe = regexp.MustCompile(`(?s)<a[^>]+href="([^"]+)"[^>]*>(.*?)</a>`)
 	bingSnipRe    = regexp.MustCompile(`(?s)<p class="b_lineclamp[^"]*"[^>]*>(.*?)</p>`)
 	bingCaptionRe = regexp.MustCompile(`(?s)<div class="b_caption"[^>]*>(.*?)</div>`)
 )
 // splitBingBlocks 按块标记切分，每块内容延伸到下一个块标记为止。
 //
 // 不用 `<li class="b_algo"(?s)(.*?)</li>`：结果块内部可能嵌套 <li>（deep links），
 // 非贪婪匹配会在错误位置截断；而且块内第一个 <a> 往往是 Bing 的「来源行」，
 // 取到的是 `deepin.orghttps://www.deepin.org` 这种垃圾标题。
 func splitBingBlocks(pageHTML string) []string {
 	locs := bingBlockRe.FindAllStringIndex(pageHTML, -1)
 	if len(locs) == 0 {
 		return nil
 	}
 	blocks := make([]string, 0, len(locs))
 	for i, loc := range locs {
 		end := len(pageHTML)
 		if i+1 < len(locs) {
 			end = locs[i+1][0]
 		}
 		blocks = append(blocks, pageHTML[loc[1]:end])
 	}
 	return blocks
 }
 func parseBingResults(pageHTML string, count int) []searchResult {
 	if count <= 0 {
 		count = 5
 	}
 	var results []searchResult
-	re := regexp.MustCompile(`<li class="b_algo"(?s)(.*?)</li>`)
+	for _, block := range splitBingBlocks(pageHTML) {
 	matches := re.FindAllStringSubmatch(html, -1)
 	for _, m := range matches {
 		if len(results) >= count {
 			break
 		}
-		block := m[1]
+		// 标题：现代 Bing 是 <h2><a href=...>标题</a></h2>；没有 h2 时才退回到块内第一个链接。
-		var r searchResult
+		var href, title string
-		hrefRe := regexp.MustCompile(`<a[^>]+href="([^"]+)"[^>]*>`)
+		if m := bingTitleRe.FindStringSubmatch(block); m != nil {
-		if hm := hrefRe.FindStringSubmatch(block); len(hm) > 1 {
+			href, title = m[1], html.UnescapeString(stripTags(m[2]))
-			r.URL = hm[1]
+		} else if m := bingAnyLinkRe.FindStringSubmatch(block); m != nil {
 			href, title = m[1], html.UnescapeString(stripTags(m[2]))
 		}
-		titleRe := regexp.MustCompile(`<a[^>]+href="[^"]+"[^>]*>(.*?)</a>`)
+		href = bingRealURL(html.UnescapeString(href))
-		if tm := titleRe.FindStringSubmatch(block); len(tm) > 1 {
+
-			r.Title = stripTags(tm[1])
+		// 摘要：新版在 p.b_lineclamp*，旧版在 div.b_caption > p
 		var snippet string
 		if m := bingSnipRe.FindStringSubmatch(block); m != nil {
 			snippet = html.UnescapeString(stripTags(m[1]))
 		} else if m := bingCaptionRe.FindStringSubmatch(block); m != nil {
 			snippet = html.UnescapeString(stripTags(m[1]))
 		}
-		snipRe := regexp.MustCompile(`<div class="b_caption">.*?<p>(.*?)</p>`)
+
-		if sm := snipRe.FindStringSubmatch(block); len(sm) > 1 {
+		title, snippet = strings.TrimSpace(title), strings.TrimSpace(snippet)
-			r.Snippet = stripTags(sm[1])
+		if href == "" || title == "" || !strings.HasPrefix(href, "http") {
-		}
+			continue
 		if r.URL != "" && r.Title != "" {
 			results = append(results, r)
 		}
 		results = append(results, searchResult{Title: title, URL: href, Snippet: snippet})
 	}
 	return results
 }
 // bingRealURL 解开 Bing 的跳转包装：/ck/a?...&u=a1<base64url>&... → 真实 URL。
 // 不解的话模型拿到的是 `https://cn.bing.com/ck/a?...` 这种不可读地址。
 func bingRealURL(href string) string {
 	href = strings.TrimSpace(href)
 	if href == "" {
 		return ""
 	}
 	if !strings.Contains(href, "/ck/a") && !strings.Contains(href, "u=a1") {
 		return href
 	}
 	u, err := url.Parse(href)
 	if err != nil {
 		return href
 	}
 	raw := u.Query().Get("u")
 	if !strings.HasPrefix(raw, "a1") {
 		return href
 	}
 	b64 := raw[2:]
 	for _, enc := range []*base64.Encoding{base64.RawURLEncoding, base64.URLEncoding, base64.RawStdEncoding} {
 		if dec, err := enc.DecodeString(b64); err == nil {
 			s := string(dec)
 			if strings.HasPrefix(s, "http://") || strings.HasPrefix(s, "https://") {
 				return s
 			}
 		}
 	}
 	return href
 }
 func (p *Plugin) handleSearch(args map[string]interface{}) (interface{}, error) {
 	query := readArg(args, "query", "")
 	if query == "" {
@ -881,10 +974,9 @@ func (p *Plugin) localSpawnFailback() (context.Context, context.CancelFunc, cont
 }
 func (p *Plugin) handleBrowserStart(args map[string]interface{}) (interface{}, error) {
-	timeoutStr := readArg(args, "timeout", "10m")
+	timeout, err := parseBrowserSessionTimeout(args)
 	timeout, err := time.ParseDuration(timeoutStr)
 	if err != nil {
-		timeout = 10 * time.Minute
+		return errResult(err.Error()), nil
 	}
 	source := readArg(args, "source", "")
@ -899,13 +991,19 @@ func (p *Plugin) handleBrowserStart(args map[string]interface{}) (interface{}, e
 			s.mu.Lock()
 			id := s.id
 			cur := s.currentURL
 			s.createdAt = time.Now()
 			s.timeout = timeout
 			closesAt := s.createdAt.Add(timeout)
 			s.mu.Unlock()
 			p.mu.Unlock()
 			log.Printf("[%s] reused browser session %s: timeout=%v closes_at=%s source=%s", p.name, id, timeout, closesAt.Format(time.RFC3339), source)
 			return map[string]interface{}{
-				"id":     id,
+				"id":        id,
-				"status": "reused",
+				"status":    "reused",
-				"url":    cur,
+				"url":       cur,
-				"note":   "已复用本来源的现有标签页（登录态全机共享）",
+				"timeout":   timeout.String(),
 				"closes_at": closesAt.Format(time.RFC3339),
 				"note":      "已复用本来源的现有标签页，并按本次 timeout 重新设定关闭时间",
 			}, nil
 		}
 	}
@ -942,7 +1040,7 @@ func (p *Plugin) handleBrowserStart(args map[string]interface{}) (interface{}, e
 			"插件会注册 homeagent-browser.service 并启动。" +
 			"若本机无法联网安装 chromium，可继续用本地临时模式（重试 browser_start 即自动降级）。"
 		return map[string]interface{}{
-			"error":       "backend not installed",
+			"error":        "backend not installed",
 			"need_install": true,
 			"guide":        guide,
 		}, nil
@ -972,13 +1070,15 @@ func (p *Plugin) handleBrowserStart(args map[string]interface{}) (interface{}, e
 		session.currentURL = initURL
 	}
-	log.Printf("[%s] created browser session %s: url=%s timeout=%v source=%s", p.name, id, initURL, timeout, source)
+	closesAt := session.createdAt.Add(timeout)
 	log.Printf("[%s] created browser session %s: url=%s timeout=%v closes_at=%s source=%s", p.name, id, initURL, timeout, closesAt.Format(time.RFC3339), source)
 	return map[string]interface{}{
-		"id":      id,
+		"id":        id,
-		"status":  "created",
+		"status":    "created",
-		"mode":    "shared-backend",
+		"mode":      "shared-backend",
-		"url":     initURL,
+		"url":       initURL,
-		"timeout": timeout.String(),
+		"timeout":   timeout.String(),
 		"closes_at": closesAt.Format(time.RFC3339),
 	}, nil
 }
@ -1044,11 +1144,11 @@ func (p *Plugin) handleScreenshot(args map[string]interface{}) (interface{}, err
 	}
 	b64 := base64.StdEncoding.EncodeToString(buf)
 	return map[string]interface{}{
-		"status":    "ok",
+		"status":   "ok",
-		"format":    format,
+		"format":   format,
-		"size":      len(buf),
+		"size":     len(buf),
-		"base64":    b64,
+		"base64":   b64,
-		"data_uri":  fmt.Sprintf("data:image/png;base64,%s", b64),
+		"data_uri": fmt.Sprintf("data:image/png;base64,%s", b64),
 	}, nil
 }
@ -1079,11 +1179,11 @@ func (p *Plugin) handleHTML(args map[string]interface{}) (interface{}, error) {
 		html = html[:maxChars] + "\n\n[HTML truncated]"
 	}
 	return map[string]interface{}{
-		"status":  "ok",
+		"status": "ok",
-		"title":   title,
+		"title":  title,
-		"url":     currentURL,
+		"url":    currentURL,
-		"html":    html,
+		"html":   html,
-		"length":  len(html),
+		"length": len(html),
 	}, nil
 }
@ -1204,13 +1304,20 @@ func (p *Plugin) cleanupLoop() {
 		case <-p.stopCh:
 			return
 		case <-ticker.C:
 			now := time.Now()
 			p.mu.Lock()
 			for id, s := range p.sessions {
-				if time.Since(s.createdAt) >= s.timeout {
+				s.mu.Lock()
-					log.Printf("[%s] cleanup: browser session %s expired", p.name, id)
+				closesAt := s.createdAt.Add(s.timeout)
-				delete(p.sessions, id)
+				expired := !now.Before(closesAt)
-				s.Close()
+				s.mu.Unlock()
-				p.sdk.InjectInterruptText(p.name, p.name, fmt.Sprintf("[浏览器会话 %s 已超时关闭]", id))
+				if expired {
 					log.Printf("[%s] cleanup: browser session %s reached agent-specified close time %s", p.name, id, closesAt.Format(time.RFC3339))
 					delete(p.sessions, id)
 					s.Close()
 					// NoMemory：会话生命周期通知，不是记忆内容。
 					p.sdk.InjectInterruptTextOpts(p.name, p.name,
 						fmt.Sprintf("[浏览器会话 %s 已按指定时间关闭]", id), sdk.InjectOptions{NoMemory: true})
 				}
 			}
 			p.mu.Unlock()
@ -1310,7 +1417,7 @@ WantedBy=multi-user.target
 			return map[string]interface{}{
 				"status":   "installed",
 				"endpoint": cdpEndpoint,
-				"chrome":    chromePath,
+				"chrome":   chromePath,
 				"profile":  profileDir,
 				"guide":    guide,
 			}, nil
--- a/example/browser/plugin_test.go
+++ b/example/browser/plugin_test.go
@ -0,0 +1,213 @@
 package main
 import (
 	"net/http"
 	"net/http/httptest"
 	"net/url"
 	"os"
 	"strings"
 	"testing"
 	"time"
 )
 func TestParseBrowserSessionTimeoutRequiresExplicitValue(t *testing.T) {
 	_, err := parseBrowserSessionTimeout(map[string]interface{}{})
 	if err == nil || !strings.Contains(err.Error(), "timeout is required") {
 		t.Fatalf("expected required timeout error, got %v", err)
 	}
 }
 func TestParseBrowserSessionTimeoutAcceptsPositiveDuration(t *testing.T) {
 	got, err := parseBrowserSessionTimeout(map[string]interface{}{"timeout": "2h30m"})
 	if err != nil {
 		t.Fatal(err)
 	}
 	if got != 2*time.Hour+30*time.Minute {
 		t.Fatalf("timeout=%v", got)
 	}
 }
 func TestParseBrowserSessionTimeoutRejectsInvalidOrNonPositive(t *testing.T) {
 	for _, value := range []string{"invalid", "0s", "-1m"} {
 		if _, err := parseBrowserSessionTimeout(map[string]interface{}{"timeout": value}); err == nil {
 			t.Errorf("timeout %q should be rejected", value)
 		}
 	}
 }
 func TestBrowserStartReuseResetsExplicitCloseTime(t *testing.T) {
 	p := &Plugin{
 		name: "browser",
 		sessions: map[string]*BrowserSession{
 			"browser_1": {
 				id:         "browser_1",
 				shared:     true,
 				sessionKey: "qq",
 				createdAt:  time.Now().Add(-time.Hour),
 				timeout:    time.Minute,
 				currentURL: "https://example.com",
 			},
 		},
 	}
 	before := time.Now()
 	result, err := p.handleBrowserStart(map[string]interface{}{"source": "qq", "timeout": "3h"})
 	if err != nil {
 		t.Fatal(err)
 	}
 	out := result.(map[string]interface{})
 	if out["status"] != "reused" || out["timeout"] != "3h0m0s" {
 		t.Fatalf("unexpected result: %#v", out)
 	}
 	s := p.sessions["browser_1"]
 	if s.timeout != 3*time.Hour || s.createdAt.Before(before) {
 		t.Fatalf("deadline not reset: createdAt=%v timeout=%v", s.createdAt, s.timeout)
 	}
 }
 // ── Bing 解析器（2026-09 版式）─────────────────────────────
 //
 // 背景：旧实现把块内**第一个 <a>** 当标题 —— 拿到的是 Bing 的「来源行」
 // `deepin.orghttps://www.deepin.org`；摘要正则 `<div class="b_caption">.*?<p>`
 // 对现代 Bing 命中 0/N（摘要已迁到 p.b_lineclamp*），于是结果「有标题没摘要」，
 // 模型只好反复换词重搜。夹具 testdata/bing_cn.html 是真实 cn.bing.com 响应裁剪。
 func TestParseBingResultsRealBingHTML(t *testing.T) {
 	page, err := os.ReadFile("testdata/bing_cn.html")
 	if err != nil {
 		t.Fatalf("读取夹具失败: %v", err)
 	}
 	results := parseBingResults(string(page), 3)
 	if len(results) != 3 {
 		t.Fatalf("应解析出 3 条，实际 %d 条: %+v", len(results), results)
 	}
 	for i, r := range results {
 		if !strings.HasPrefix(r.URL, "http") {
 			t.Errorf("第 %d 条 URL 不是真实地址: %q", i+1, r.URL)
 		}
 		if strings.Contains(r.Title, "http") || strings.Contains(r.Title, "://") {
 			t.Errorf("第 %d 条标题混入了 URL（旧 bug 的典型症状）: %q", i+1, r.Title)
 		}
 		if r.Snippet == "" {
 			t.Errorf("第 %d 条没有摘要（旧 bug 的典型症状）: %+v", i+1, r)
 		}
 	}
 	// 第一条必须与样本里的真实结果一致
 	if results[0].URL != "https://www.deepin.org/" {
 		t.Errorf("第一条 URL 应为 https://www.deepin.org/，实际 %q", results[0].URL)
 	}
 	if !strings.Contains(results[0].Title, "deepin") {
 		t.Errorf("第一条标题不对: %q", results[0].Title)
 	}
 	if len(results[0].Snippet) < 10 || strings.Contains(results[0].Snippet, "://") {
 		t.Errorf("第一条摘要不对（应是有内容的文本）: %q", results[0].Snippet)
 	}
 }
 // 块内嵌套 <li>（deep links）时不能截断 —— 旧的 `<li class="b_algo"(?s)(.*?)</li>` 会在此翻车
 func TestParseBingResultsNestedLiKeepsResult(t *testing.T) {
 	page := `<ol id="b_results"><li class="b_algo" data-id iid=SERP.1>` +
 		`<h2><a href="https://a.example/x" h="ID=SERP,1">真标题</a></h2>` +
 		`<div class="b_caption"><p class="b_lineclamp2">真摘要</p></div>` +
 		`<div><ul><li><a href="https://sub.example/deeplink">子链接</a></li></ul></div>` +
 		`</li><li class="b_algo"><h2><a href="https://b.example/y">第二条</a></h2>` +
 		`<p class="b_lineclamp3">摘要二</p></li></ol>`
 	rs := parseBingResults(page, 5)
 	if len(rs) != 2 {
 		t.Fatalf("应解析 2 条，实际 %d 条: %+v", len(rs), rs)
 	}
 	if rs[0].URL != "https://a.example/x" || rs[0].Title != "真标题" || rs[0].Snippet != "真摘要" {
 		t.Errorf("第一条解析错误: %+v", rs[0])
 	}
 	if rs[1].Title != "第二条" || rs[1].Snippet != "摘要二" {
 		t.Errorf("第二条（无 b_caption，摘要走 b_lineclamp3）解析错误: %+v", rs[1])
 	}
 }
 func TestBingRealURLDecodesRedirectWrapper(t *testing.T) {
 	// Bing 跳转包装：/ck/a?...&u=a1<base64url>
 	wrapped := "/ck/a?!&&p=abc&u=a1aHR0cHM6Ly93d3cuZGVlcGluLm9yZy96aC9EZWVwaW4v&ntb=1"
 	if got := bingRealURL(wrapped); got != "https://www.deepin.org/zh/Deepin/" {
 		t.Errorf("未解开跳转包装: %q", got)
 	}
 	if got := bingRealURL("https://direct.example/p"); got != "https://direct.example/p" {
 		t.Errorf("直链不应被改动: %q", got)
 	}
 	// 解不开时保守返回原值，不能返回空
 	bad := "/ck/a?u=a1!!!!"
 	if got := bingRealURL(bad); got == "" {
 		t.Errorf("解不开时应保留原值，实际返回空")
 	}
 }
 // roundTripFunc 把任意请求转给本地测试服务器，从而离线测 bingSearch 的完整路径
 type roundTripFunc func(*http.Request) (*http.Response, error)
 func (f roundTripFunc) RoundTrip(r *http.Request) (*http.Response, error) { return f(r) }
 func TestBingSearchReportsParseFailureInsteadOfEmptyResult(t *testing.T) {
 	var seenURL string
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		_, _ = w.Write([]byte("<html><body>no result blocks here</body></html>"))
 	}))
 	defer srv.Close()
 	p := &Plugin{name: "browser", client: &http.Client{Transport: roundTripFunc(func(r *http.Request) (*http.Response, error) {
 		seenURL = r.URL.String()
 		return srv.Client().Transport.RoundTrip(&http.Request{
 			Method: r.Method, URL: mustParseURL(t, srv.URL), Header: r.Header, Body: r.Body,
 		})
 	})}}
 	if _, err := p.bingSearch("任意查询", 5); err == nil {
 		t.Fatal("解析不出结果时必须报错，而不是伪装成「没有结果」")
 	} else if !strings.Contains(err.Error(), "未解析出结果") {
 		t.Errorf("错误信息应说明是解析失败: %v", err)
 	}
 	// 数据源必须是 cn.bing.com（www.bing.com 对程序化请求回 302，拿不到结果块）
 	if !strings.Contains(seenURL, "cn.bing.com") {
 		t.Errorf("应请求 cn.bing.com，实际 %q", seenURL)
 	}
 	if strings.Contains(seenURL, "www.bing.com") {
 		t.Errorf("不应再请求 www.bing.com: %q", seenURL)
 	}
 }
 // 正常路径：能解析出结果时返回结果且不报错
 func TestBingSearchParsesFixtureThroughClient(t *testing.T) {
 	page, err := os.ReadFile("testdata/bing_cn.html")
 	if err != nil {
 		t.Fatalf("读取夹具失败: %v", err)
 	}
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("Content-Type", "text/html; charset=utf-8")
 		_, _ = w.Write(page)
 	}))
 	defer srv.Close()
 	p := &Plugin{name: "browser", client: &http.Client{Transport: roundTripFunc(func(r *http.Request) (*http.Response, error) {
 		return srv.Client().Transport.RoundTrip(&http.Request{
 			Method: r.Method, URL: mustParseURL(t, srv.URL), Header: r.Header, Body: r.Body,
 		})
 	})}}
 	results, err := p.bingSearch("deepin", 2)
 	if err != nil {
 		t.Fatalf("应成功，实际 %v", err)
 	}
 	if len(results) != 2 {
 		t.Fatalf("应返回 2 条（count 生效），实际 %d", len(results))
 	}
 	if results[0].Snippet == "" {
 		t.Errorf("摘要不应为空: %+v", results[0])
 	}
 }
 func mustParseURL(t *testing.T, raw string) *url.URL {
 	t.Helper()
 	u, err := url.Parse(raw)
 	if err != nil {
 		t.Fatalf("解析测试 URL 失败: %v", err)
 	}
 	return u
 }
--- a/example/browser/testdata/bing_cn.html
+++ b/example/browser/testdata/bing_cn.html
--- a/example/calendar/README.md
+++ b/example/calendar/README.md
@ -1,13 +1,57 @@
-# calendar
+# calendar · 日历事件
-calendar plugin
+事件管理：支持**重复事件**与**多档提醒**。
-## Build
+## 工具
-```bash
+| 工具 | 说明 |
-plugindev build
+|---|---|
 | `calendar_event_add` | 添加事件 |
 | `calendar_event_list` | 列出即将到来的事件（含日期、时间、重复规则） |
 | `calendar_event_update` | 更新事件（**只改传入的字段**；会重置提醒状态） |
 | `calendar_event_delete` | 删除事件（连带**该事件及之后的所有重复实例**） |
 | `calendar_today` | 今日事件 + 倒计时 |
 | `calendar_week` | 本周事件，按天分组 |
 | `calendar_month` | 月历网格，带事件标记点 |
 | `calendar_search` | 按关键词搜标题 / 地点 / 备注 |
 `calendar_event_add` 的时间格式：`YYYY-MM-DD HH:MM`；只给 `YYYY-MM-DD` 表示全天事件。
 ## 重复规则
 `repeat` 取值：
 | 值 | 含义 |
 |---|---|
 | `none` | 不重复 |
 | `daily` | 每天 |
 | `weekday` | 每个工作日 |
 | `weekly` | 每周 |
 | `biweekly` | 每两周 |
 | `monthly` | 每月 |
 | `yearly` | 每年 |
 | `lunar_yearly` | **按农历年**（生日、传统节日用） |
 `lunar_yearly` 是刻意加的：农历节日按公历写死会逐年偏移。
 ## 提醒
 `remind_before` 单位是**分钟**，可给多个、逗号分隔：
 ```
 15,60,1440      # 提前 15 分钟 + 1 小时 + 1 天
 0 或留空        # 不提醒
 ```
-## Install
+到点通过 `InjectInterruptText` 注入提醒，带 `NoMemory: true` ——
 提醒是瞬时信号，不是记忆内容。通道 `calendar` 同样声明为 NoMemory。
-Upload the .hmap file through the Plugin Manager API.
+## 存储
 事件存为 JSON，插件重启后保留。
 ## 构建
 ```bash
 hmapdev build
 ```
--- a/example/calendar/plugin.go
+++ b/example/calendar/plugin.go
@ -15,31 +15,31 @@ import (
 )
 const (
-	RepeatNone      = "none"
+	RepeatNone        = "none"
-	RepeatDaily     = "daily"
+	RepeatDaily       = "daily"
-	RepeatWeekday   = "weekday"
+	RepeatWeekday     = "weekday"
-	RepeatWeekly    = "weekly"
+	RepeatWeekly      = "weekly"
-	RepeatBiweekly  = "biweekly"
+	RepeatBiweekly    = "biweekly"
-	RepeatMonthly   = "monthly"
+	RepeatMonthly     = "monthly"
-	RepeatYearly    = "yearly"
+	RepeatYearly      = "yearly"
 	RepeatLunarYearly = "lunar_yearly"
 )
 type CalendarEvent struct {
-	ID         string   `json:"id"`
+	ID         string  `json:"id"`
-	Title      string   `json:"title"`
+	Title      string  `json:"title"`
-	StartTime  string   `json:"start_time"`
+	StartTime  string  `json:"start_time"`
-	EndTime    string   `json:"end_time,omitempty"`
+	EndTime    string  `json:"end_time,omitempty"`
-	AllDay     bool     `json:"all_day,omitempty"`
+	AllDay     bool    `json:"all_day,omitempty"`
-	Location   string   `json:"location,omitempty"`
+	Location   string  `json:"location,omitempty"`
-	Note       string   `json:"note,omitempty"`
+	Note       string  `json:"note,omitempty"`
-	Reminds    []int    `json:"reminds,omitempty"`
+	Reminds    []int   `json:"reminds,omitempty"`
-	RemindAt   []int64  `json:"remind_at,omitempty"`
+	RemindAt   []int64 `json:"remind_at,omitempty"`
-	Repeat     string   `json:"repeat,omitempty"`
+	Repeat     string  `json:"repeat,omitempty"`
-	ParentID   string   `json:"parent_id,omitempty"`
+	ParentID   string  `json:"parent_id,omitempty"`
-	Lunar      bool     `json:"lunar,omitempty"`
+	Lunar      bool    `json:"lunar,omitempty"`
-	LunarMonth int      `json:"lunar_month,omitempty"`
+	LunarMonth int     `json:"lunar_month,omitempty"`
-	LunarDay   int      `json:"lunar_day,omitempty"`
+	LunarDay   int     `json:"lunar_day,omitempty"`
 }
 type Plugin struct {
@ -276,6 +276,9 @@ func nextLunarYearly(targetMonth, targetDay int, after time.Time) (time.Time, bo
 func (p *Plugin) Start(s *sdk.PluginSDK) error {
 	p.sdk = s
 	// 入站通道：本插件用 "calendar" 通道注入输入（见 Inject* 调用），
 	// 输入侧必须显式登记 —— 否则"把该 inputch 划给驻留子"会报 `inputch 未注册`。
 	_ = s.RegisterInputChannel("calendar", sdk.ChannelDef{NoMemory: true})
 	dataDirVal, err := s.Settings().GetCore("core.daemon.data_dir")
 	if err != nil || dataDirVal == "" {
 		dataDirVal = "."
@ -359,7 +362,7 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
 	s.RegisterTool(tp+"today", sdk.ToolDef{
 		Name: tp + "today", Description: "Show today's events with countdown.",
 		Parameters: map[string]interface{}{
-			"type": "object",
+			"type":       "object",
 			"properties": map[string]interface{}{},
 		},
 	}, p.handleToday)
@ -367,7 +370,7 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
 	s.RegisterTool(tp+"week", sdk.ToolDef{
 		Name: tp + "week", Description: "Show this week's events grouped by day.",
 		Parameters: map[string]interface{}{
-			"type": "object",
+			"type":       "object",
 			"properties": map[string]interface{}{},
 		},
 	}, p.handleWeek)
@ -520,7 +523,8 @@ func (p *Plugin) checkReminders() {
 	p.mu.Unlock()
 	for _, msg := range injectMsgs {
-		p.sdk.InjectInterruptText("calendar", "calendar", msg)
+		// NoMemory：日程到点提醒，不是记忆内容。
 		p.sdk.InjectInterruptTextOpts("calendar", "calendar", msg, sdk.InjectOptions{NoMemory: true})
 	}
 }
--- a/example/deepsearch/README.md
+++ b/example/deepsearch/README.md
@ -0,0 +1,100 @@
 # 联网检索插件（HomeAgent）
 给 agent 补上**真正的信息检索**能力：检索交给本地 SearXNG（多引擎聚合、结构化 JSON），
 并补上「读完前 K 篇再回答」的深检索。
 ## 为什么需要它（背景）
 agent 原本只有 `browser_*` 那套浏览器工具，联网检索实际只有 `browser_search` 一个入口，而它是
 **「抓 Bing HTML + 正则解析」**：
 | 缺陷 | 实测结果 |
 |---|---|
 | 标题取的是结果块里**第一个 `<a>`** | 拿到的是 Bing 的「来源行」而非标题 → `deepin.orghttps://www.deepin.org` |
 | 摘要正则 `<div class="b_caption">.*?<p>` | 对现代 Bing **命中 0/10**（摘要已迁到 `p.b_lineclamp*`）→ 结果**完全没有摘要** |
 | 用 `www.bing.com` | 程序化请求直接 302；`cn.bing.com` 才返回 10 个结果块 |
 | 单引擎、无兜底、无去重、无站点读取 | 模型只能反复换词重搜（日志里 8 秒 6 连击） |
 结果就是日志里那句用户反馈：**「你的搜索能力好像不太行啊」**。
 ## 依赖：本地 SearXNG（由本插件托管）
 插件会**自己管后端**：
 - **启动时**：探 `healthz`；已在跑就**直接接管**（不重启），没跑就 `docker compose up -d` 并等就绪（上限 6s）
 - **停止时**：跑 `docker compose stop -t 2` 关闭它
 配置项 `manage_searxng`（默认 true）与 `searxng_dir`（默认 `/root/searxng-agent`）控制这套行为；
 `stop_searxng_on_exit`（默认 true）设 false 可让后端在插件停止后继续跑（**插件重载频繁时建议设 false**，
 否则每次重载都会把后端重启一遍）。
 ### 生命周期契约（依据内核源码，非猜测）
 | 环节 | 内核行为 |
 |---|---|
 | 停止插件 | 发 `plugin.stop` → 插件先跑 **RunStopHandlers（LIFO、幂等）** → 再 `Stop()` → `exit(0)` |
 | 宽限期 | **5 秒**；未退出则直接 SIGKILL —— 所以关闭动作限时 4s（`searxShutdownBudget`） |
 | stdin 关闭 | 同样会跑 handlers + `Stop()` |
 | 崩溃/被 kill | 关闭动作不会执行，后端会留在运行态；下次启动探测到就直接接管（**更安全的失败方向**） |
 | 自动重启 | `SetAutoRestart(true)` 由注入的 runtime 在 `plugin.start` 后经 `lifecycle.autoRestart` **显式上报**内核 |
 ### SearXNG 侧配置
 部署在 **.60**，`127.0.0.1:8888`：
 ```
 /root/searxng-agent/docker-compose.yml    # host 网络（要访问宿主 clash）
 /root/searxng-agent/settings.yml         # json 输出 + limiter 关闭 + 出站走 clash
 ```
 两个必须知道的坑：
 1. **`search.formats` 必须含 `json`**，否则 `/search?format=json` 返回 **403**（看起来像网络问题，其实是配置）。
 2. 该镜像默认 `GRANIAN_PORT=8080`，而 granian 的 `GRANIAN_*` **优先级高于 settings.yml**：
   .60 上 8080 被 homeagent 占用 → 不改 `SEARXNG_PORT` 就是无休止的 `Address already in use` 崩溃循环。
 实测可用的引擎（2026-09-12）：`duckduckgo`、`brave`、`google cse`；`quark` 时好时坏；
 `baidu`/`google` 经代理出口触发 CAPTCHA，`sogou` 崩溃，`wikidata` 报 HTTP error（已关）。
 ## 工具
 | 工具 | 说明 |
 |---|---|
 | `deepsearch_search` | 联网检索（首选）：标题 + URL + 摘要 + 发布时间，支持 `engines`/`category`/`time_range`/`language`，自动按 URL 去重并按分数排序；会回报**引擎覆盖度与无响应引擎** |
 | `deepsearch_news` | 新闻检索：`news` 类别 + 默认最近一周；新闻为空时自动回退 general + 时间范围 |
 | `deepsearch_fetch` | 抓单个网页并抽正文（去脚本/样式/导航），返回标题 + 纯文本，可设截断长度 |
 | `deepsearch_deep` | **深检索**：检索 → 并行抓前 K 篇正文 → 一次返回「候选清单 + 证据正文」；单篇失败不影响整体 |
 | `deepsearch_status` | 自检：healthz、json 是否可用、延迟、**哪些引擎真的在返回结果**（检索出问题先跑这个） |
 ## 配置项
 | 键 | 默认 | 说明 |
 |---|---|---|
 | `searxng_url` | `http://127.0.0.1:8888` | 本地 SearXNG 地址 |
 | `max_results` | `8` | 默认条数（控制上下文体积） |
 | `language` | `zh-CN` | 检索语言 |
 | `safesearch` | `0` | 0 关 / 1 中 / 2 严 |
 | `request_timeout` | `20` | 单次请求超时（秒） |
 | `fetch_max_chars` | `4000` | `deepsearch_fetch` 正文上限 |
 | `proxy` | 空 | 仅作用于本插件直连抓取（搜索出网由 SearXNG 侧负责） |
 | `user_agent` | Chrome UA | 抓取用 |
 每次调用前重读配置，改完即时生效。
 ## 开发与验证
 ```bash
 go test -count=1 -race ./...       # 11 项测试（httptest 打桩 SearXNG）
 # 真实后端联调（默认跳过）：跑的就是当初失败的那条查询
 DEEPSEARCH_LIVE_SEARXNG=http://127.0.0.1:8888 go test -run TestLiveSearxng -v ./...
 hmapdev build                      # 产出 dist/deep_search_bundle.hmap
 ```
 ## 已知边界
 - **知乎等站点对直连抓取返回 403**（反爬），`deepsearch_deep` 会如实标注该篇抓取失败并继续；
  这类页面请改用浏览器工具（`browser_navigate` + `browser_render`）。
 - 引擎可用性随出口 IP 与目标站点风控变化；`deepsearch_status` 与每次结果里的「覆盖度」行就是给这个用的。
 - 未做正文去重/相似度合并：同一事件的多篇转载会各占一条（摘要已能区分）。
--- a/example/deepsearch/go.mod
+++ b/example/deepsearch/go.mod
@ -0,0 +1,21 @@
 module deepsearch-plugin
 go 1.25.0
 require gitcode.com/JianFeeeee/homeagent-sdk v0.0.0
 replace gitcode.com/JianFeeeee/homeagent-sdk => ../../
--- a/example/deepsearch/live_test.go
+++ b/example/deepsearch/live_test.go
@ -0,0 +1,81 @@
 package main
 import (
 	"os"
 	"strings"
 	"testing"
 )
 // 真实后端联调（默认跳过，需显式指定地址）：
 //
 //	DEEPSEARCH_LIVE_SEARXNG=http://127.0.0.1:8888 go test -run TestLiveSearxng -v ./...
 //
 // 它跑的就是当初失败的场景（日志里那条「你的搜索能力好像不太行啊」对应的查询），
 // 用来回答一个具体问题：换了后端之后，模型拿到的是不是「带摘要的相关结果」。
 func TestLiveSearxng(t *testing.T) {
 	base := os.Getenv("DEEPSEARCH_LIVE_SEARXNG")
 	if base == "" {
 		t.Skip("未设置 DEEPSEARCH_LIVE_SEARXNG，跳过真实后端联调")
 	}
 	p := &Plugin{
 		name:      "deepsearch",
 		searxURL:  strings.TrimRight(base, "/"),
 		maxItems:  6,
 		language:  "zh-CN",
 		fetchMax:  1200,
 		userAgent: defaultUA,
 	}
 	p.ensure()
 	// 1) 自检
 	st, err := p.handleStatus(map[string]interface{}{})
 	if err != nil {
 		t.Fatalf("status: %v", err)
 	}
 	t.Logf("status: %v", st)
 	// 2) 当初失败的那条查询
 	res, err := p.handleSearch(map[string]interface{}{"query": "深度科技 deepin 开发者 被开除"})
 	if err != nil {
 		t.Fatalf("search: %v", err)
 	}
 	txt := res.(map[string]interface{})["content"].(string)
 	t.Logf("检索结果：\n%s", txt)
 	if !strings.Contains(txt, "摘要：") {
 		t.Errorf("结果里应当有摘要（这正是原实现缺失的东西）")
 	}
 	if !strings.Contains(txt, "覆盖：") {
 		t.Errorf("应报告引擎覆盖度")
 	}
 	// 3) 正文抓取（取第一条结果的 URL）
 	var firstURL string
 	for _, line := range strings.Split(txt, "\n") {
 		l := strings.TrimSpace(line)
 		if strings.HasPrefix(l, "http") {
 			firstURL = l
 			break
 		}
 	}
 	if firstURL == "" {
 		t.Fatal("未从结果中解析出 URL")
 	}
 	page, err := p.handleFetch(map[string]interface{}{"url": firstURL, "max_chars": float64(600)})
 	if err != nil {
 		t.Logf("抓取 %s 失败（真实站点有反爬/需 JS 属正常）：%v", firstURL, err)
 	} else {
 		body := page.(map[string]interface{})["content"].(string)
 		t.Logf("抓取 %s 正文前 400 字：%s", firstURL, oneLine(body, 400))
 	}
 	// 4) 深检索
 	deep, err := p.handleDeep(map[string]interface{}{"query": "统信 UOS 内核工程师 西装 事件", "top_k": float64(2)})
 	if err != nil {
 		t.Fatalf("deep: %v", err)
 	}
 	dTxt := deep.(map[string]interface{})["content"].(string)
 	if !strings.Contains(dTxt, "候选清单") || !strings.Contains(dTxt, "正文证据") {
 		t.Errorf("深检索输出结构不对")
 	}
 	t.Logf("深检索输出前 800 字：\n%s", oneLine(dTxt, 800))
 }
--- a/example/deepsearch/plg.json
+++ b/example/deepsearch/plg.json
@ -0,0 +1,17 @@
 {
  "name": "deepsearch",
  "name_zh": "联网检索",
  "name_en": "Deep Search",
  "version": "1.1.2",
  "description": "为 agent 提供真正的联网信息检索：本地 SearXNG 聚合多引擎（返回标题/URL/摘要/时间），支持新闻、时间范围、指定引擎；并提供网页正文抽取与「搜索+读前K篇」的深检索",
  "author": "HomeAgent",
  "entry": "plugin.bin",
  "tags": [
    "search",
    "web",
    "searxng",
    "retrieval",
    "news"
  ],
  "targets": "linux/amd64"
 }
--- a/example/deepsearch/plugin.go
+++ b/example/deepsearch/plugin.go
--- a/example/deepsearch/plugin_test.go
+++ b/example/deepsearch/plugin_test.go
@ -0,0 +1,343 @@
 package main
 import (
 	"encoding/json"
 	"net/http"
 	"net/http/httptest"
 	"net/url"
 	"strings"
 	"testing"
 )
 func newTestPlugin(t *testing.T, h http.HandlerFunc) (*Plugin, *httptest.Server) {
 	t.Helper()
 	srv := httptest.NewServer(h)
 	t.Cleanup(srv.Close)
 	p := &Plugin{
 		name:      "deepsearch",
 		searxURL:  srv.URL,
 		maxItems:  5,
 		language:  "zh-CN",
 		fetchMax:  1000,
 		userAgent: "test-agent",
 		http:      srv.Client(),
 	}
 	return p, srv
 }
 // 一份贴近真实 SearXNG 的响应：含重复 URL、缺摘要、多引擎、无响应引擎
 const sampleResponse = `{
  "query": "deepin 被开除",
  "results": [
    {"url":"https://www.zhihu.com/question/1?utm_source=x","title":"网传统信内核开发工程师因没穿西服被开除","content":"截止1月9日最新情况…","engines":["duckduckgo","brave"],"score":9.5,"publishedDate":"2026-09-10T00:00:00"},
    {"url":"https://www.zhihu.com/question/1","title":"网传统信内核开发工程师因没穿西服被开除（重复项）","content":"重复条目","engines":["brave"],"score":1.0},
    {"url":"https://www.163.com/dy/article/KIQURODQ.html","title":"离谱！传某信创操作系统大厂因西装开除核心开发者","content":"一位负责Linux内核开发的核心工程师…","engines":["brave","quark"],"score":7.2},
    {"url":"https://bbs.deepin.org.cn/zh","title":"deepin官方论坛","content":"","engines":["duckduckgo"],"score":2.0}
  ],
  "answers": [],
  "suggestions": ["deepin 王勇 离职"],
  "unresponsive_engines": [["baidu","CAPTCHA"],["sogou","unexpected crash"]],
  "timings": {"search": 1.2}
 }`
 // 1) 检索：去重 + 按分数排序 + 摘要/覆盖度输出
 func TestSearchDedupAndFormat(t *testing.T) {
 	var gotQuery url.Values
 	p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
 		if r.URL.Path == "/search" {
 			gotQuery = r.URL.Query()
 			w.Header().Set("Content-Type", "application/json")
 			_, _ = w.Write([]byte(sampleResponse))
 			return
 		}
 		http.NotFound(w, r)
 	})
 	res, err := p.handleSearch(map[string]interface{}{"query": "deepin 被开除", "count": float64(5)})
 	if err != nil {
 		t.Fatalf("err: %v", err)
 	}
 	if gotQuery.Get("format") != "json" {
 		t.Errorf("必须要求 json 输出，实际 %q", gotQuery.Get("format"))
 	}
 	// SearXNG 的 /search **不认** count/limit（实测两者都返回同样的条数），
 	// 所以「要几条」必须由插件侧截断 —— 也不要再发这种无意义参数（曾以为它生效过）。
 	if gotQuery.Get("limit") != "" || gotQuery.Get("count") != "" {
 		t.Errorf("不应依赖 SearXNG 的条数参数（它不认）: %q", gotQuery.Encode())
 	}
 	txt := res.(map[string]interface{})["content"].(string)
 	// utm_source 应被规范化掉，重复项只剩一条
 	if n := strings.Count(txt, "zhihu.com/question/1"); n != 1 {
 		t.Errorf("URL 未正确去重（出现 %d 次）:\n%s", n, txt)
 	}
 	if !strings.Contains(txt, "网传统信内核开发工程师") {
 		t.Errorf("缺少标题: %s", txt)
 	}
 	if !strings.Contains(txt, "摘要：") {
 		t.Errorf("应输出摘要: %s", txt)
 	}
 	if !strings.Contains(txt, "baidu(CAPTCHA)") {
 		t.Errorf("应回报无响应引擎（让模型知道覆盖度）: %s", txt)
 	}
 	if !strings.Contains(txt, "duckduckgo") || !strings.Contains(txt, "quark") {
 		t.Errorf("应回报引擎覆盖: %s", txt)
 	}
 	// 高分条目应排在前面
 	if strings.Index(txt, "统信内核开发工程师") > strings.Index(txt, "离谱！") {
 		t.Errorf("未按分数排序:\n%s", txt)
 	}
 }
 // 2) 403（未开 json）必须给出可操作提示，而不是裸错误
 func TestSearchForbiddenHint(t *testing.T) {
 	p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
 		w.WriteHeader(http.StatusForbidden)
 		_, _ = w.Write([]byte("Forbidden"))
 	})
 	_, err := p.handleSearch(map[string]interface{}{"query": "x"})
 	if err == nil {
 		t.Fatal("应返回错误")
 	}
 	msg := err.Error()
 	if !strings.Contains(msg, "403") || !strings.Contains(msg, "formats") {
 		t.Errorf("403 提示应指向 json/limiter 配置，实际: %s", msg)
 	}
 }
 // 3) 空结果：要给出原因与下一步建议
 func TestSearchEmptyHint(t *testing.T) {
 	p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
 		_, _ = w.Write([]byte(`{"query":"x","results":[],"suggestions":["换个词"],"unresponsive_engines":[["google","CAPTCHA"]]}`))
 	})
 	res, err := p.handleSearch(map[string]interface{}{"query": "x"})
 	if err != nil {
 		t.Fatalf("err: %v", err)
 	}
 	txt := res.(map[string]interface{})["content"].(string)
 	for _, want := range []string{"未返回结果", "google(CAPTCHA)", "换个词", "deepsearch_news"} {
 		if !strings.Contains(txt, want) {
 			t.Errorf("空结果提示缺少 %q: %s", want, txt)
 		}
 	}
 }
 // 4) 新闻：应带 categories=news 与 time_range=week；新闻为空时回退 general
 func TestNewsParamsAndFallback(t *testing.T) {
 	var calls []url.Values
 	p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
 		calls = append(calls, r.URL.Query())
 		if r.URL.Query().Get("categories") == "news" {
 			_, _ = w.Write([]byte(`{"query":"n","results":[]}`))
 			return
 		}
 		_, _ = w.Write([]byte(`{"query":"n","results":[{"url":"https://a.com/1","title":"回退结果","content":"内容","engines":["brave"],"score":1}]}`))
 	})
 	res, err := p.handleNews(map[string]interface{}{"query": "某事"})
 	if err != nil {
 		t.Fatalf("err: %v", err)
 	}
 	if len(calls) != 2 {
 		t.Fatalf("新闻为空时应回退 general，实际调用 %d 次", len(calls))
 	}
 	if calls[0].Get("categories") != "news" || calls[0].Get("time_range") != "week" {
 		t.Errorf("首次应为 news + week，实际 categories=%q time_range=%q", calls[0].Get("categories"), calls[0].Get("time_range"))
 	}
 	if tmp := res.(map[string]interface{})["content"].(string); !strings.Contains(tmp, "回退结果") {
 		t.Errorf("回退结果未被采用: %s", tmp)
 	}
 }
 // 5) 正文抽取：去脚本/样式/导航，保留 article
 func TestFetchExtractsArticle(t *testing.T) {
 	page := `<!doctype html><html><head><title>测试标题 - 站点</title>
 	<style>.x{color:red}</style><script>var secret="SHOULD_NOT_APPEAR";</script></head>
 	<body><nav>导航链接</nav><article>
 	<p>第一段正文，包含关键事实。</p><p>第二段正文。</p>
 	</article><footer>页脚</footer></body></html>`
 	var srvURL string
 	p, srv := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("Content-Type", "text/html; charset=utf-8")
 		_, _ = w.Write([]byte(page))
 	})
 	srvURL = srv.URL
 	// 注意：不要用 example.com 之类真实域名——本机 DNS/proxy 会把它们转走，测试会飘
 	res, err := p.handleFetch(map[string]interface{}{"url": srvURL + "/a"})
 	if err != nil {
 		t.Fatalf("err: %v", err)
 	}
 	txt := res.(map[string]interface{})["content"].(string)
 	if !strings.Contains(txt, "第一段正文") {
 		t.Errorf("正文丢失: %s", txt)
 	}
 	if strings.Contains(txt, "SHOULD_NOT_APPEAR") {
 		t.Errorf("脚本内容不应出现: %s", txt)
 	}
 	if strings.Contains(txt, "导航链接") || strings.Contains(txt, "页脚") {
 		t.Errorf("导航/页脚应被剥离: %s", txt)
 	}
 	if !strings.Contains(txt, "测试标题") {
 		t.Errorf("标题应被提取: %s", txt)
 	}
 }
 // 6) 深检索：候选 + 正文证据；单篇失败不应导致整体失败
 func TestDeepSearch(t *testing.T) {
 	var srvURL string // 处理函数先于 server 存在，故用闭包变量回填
 	p, srv := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
 		switch r.URL.Path {
 		case "/search":
 			_, _ = w.Write([]byte(`{"query":"d","results":[
 			  {"url":"` + srvURL + `/ok1","title":"好文一","content":"摘要一","engines":["brave"],"score":3},
 			  {"url":"` + srvURL + `/bad","title":"打不开的","content":"摘要二","engines":["brave"],"score":2},
 			  {"url":"` + srvURL + `/ok2","title":"好文二","content":"摘要三","engines":["brave"],"score":1}]}`))
 		case "/ok1", "/ok2":
 			w.Header().Set("Content-Type", "text/html")
 			_, _ = w.Write([]byte("<html><body><article><p>正文内容 " + r.URL.Path + "</p></article></body></html>"))
 		case "/bad":
 			w.WriteHeader(http.StatusForbidden)
 		default:
 			http.NotFound(w, r)
 		}
 	})
 	srvURL = srv.URL
 	res, err := p.handleDeep(map[string]interface{}{"query": "d", "top_k": float64(3), "max_chars": float64(500)})
 	if err != nil {
 		t.Fatalf("err: %v", err)
 	}
 	txt := res.(map[string]interface{})["content"].(string)
 	for _, want := range []string{"候选清单", "正文证据", "正文内容 /ok1", "正文内容 /ok2", "抓取失败"} {
 		if !strings.Contains(txt, want) {
 			t.Errorf("深检索输出缺少 %q:\n%s", want, txt)
 		}
 	}
 }
 // 7) 自检：健康检查 + 探测检索 + 引擎覆盖统计
 func TestStatusReportsEngines(t *testing.T) {
 	p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
 		if r.URL.Path == "/healthz" {
 			_, _ = w.Write([]byte("OK"))
 			return
 		}
 		_, _ = w.Write([]byte(sampleResponse))
 	})
 	res, err := p.handleStatus(map[string]interface{}{})
 	if err != nil {
 		t.Fatalf("err: %v", err)
 	}
 	m := res.(map[string]interface{})
 	if m["healthz"] != 200 {
 		t.Errorf("healthz 应为 200，实际 %v", m["healthz"])
 	}
 	if m["search_ok"] != true {
 		t.Errorf("search_ok 应为 true：%v", m["search_ok"])
 	}
 	engs, ok := m["engines_returning_results"].(map[string]int)
 	if !ok || engs["brave"] == 0 || engs["quark"] == 0 {
 		t.Errorf("引擎统计不正确: %#v", m["engines_returning_results"])
 	}
 }
 // 8) 摘要压成一行并按字符截断（避免巨长摘要吃掉上下文）
 func TestOneLineTruncate(t *testing.T) {
 	got := oneLine("第一行\n第二行\t第三行", 5)
 	if strings.Contains(got, "\n") {
 		t.Errorf("应为单行: %q", got)
 	}
 	if r := []rune(got); len(r) != 6 { // 5 字符 + 省略号
 		t.Errorf("截断长度不符: %q (%d runes)", got, len(r))
 	}
 }
 // 9) 正文抽取长度上限生效
 func TestHtmlToTextTruncation(t *testing.T) {
 	long := strings.Repeat("字", 5000)
 	_, text := htmlToText("<html><body><article><p>"+long+"</p></article></body></html>", 100)
 	if !strings.Contains(text, "已截断") {
 		t.Errorf("超长正文应被截断: %d", len([]rune(text)))
 	}
 }
 // 10) 非 http(s) 协议应被拒绝
 func TestFetchRejectsBadScheme(t *testing.T) {
 	p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {})
 	if _, err := p.handleFetch(map[string]interface{}{"url": "file:///etc/passwd"}); err == nil {
 		t.Fatal("file:// 应被拒绝")
 	}
 	if _, err := p.handleFetch(map[string]interface{}{"url": "javascript:alert(1)"}); err == nil {
 		t.Fatal("javascript: 应被拒绝")
 	}
 }
 // 11) raw 模式返回结构化 JSON（排查用）
 func TestSearchRawMode(t *testing.T) {
 	p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
 		_, _ = w.Write([]byte(sampleResponse))
 	})
 	res, err := p.handleSearch(map[string]interface{}{"query": "q", "raw": true})
 	if err != nil {
 		t.Fatalf("err: %v", err)
 	}
 	m, ok := res.(*searxResponse)
 	if !ok {
 		t.Fatalf("raw 应返回结构化响应，实际 %T", res)
 	}
 	if len(m.Results) != 4 {
 		t.Errorf("结果数应为 4（raw 不去重），实际 %d", len(m.Results))
 	}
 	if _, err := json.Marshal(m); err != nil {
 		t.Errorf("结构化结果应可序列化: %v", err)
 	}
 }
 // 13) 条数截断：SearXNG 不认条数参数，插件必须自己截，并且**如实说明**给了几条
 func TestSearchTruncatesToCountAndSaysSo(t *testing.T) {
 	p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("Content-Type", "application/json")
 		_, _ = w.Write([]byte(sampleResponse)) // 4 条，去重后 3 条
 	})
 	res, err := p.handleSearch(map[string]interface{}{"query": "deepin", "count": float64(2)})
 	if err != nil {
 		t.Fatalf("err: %v", err)
 	}
 	txt := res.(map[string]interface{})["content"].(string)
 	// 必须明确区分「命中几条」与「返回几条」：写成「命中 N 条」而实际给了 M<N 条，
 	// 模型会把 N 当成拿到手的条数（实测被 agent 当成事实报给用户）。
 	if !strings.Contains(txt, "命中 3 条，返回前 2 条") {
 		t.Errorf("应如实说明命中数与返回数:\n%s", txt)
 	}
 	// 按 score 排序后的前两条：zhihu(9.5)、163(7.2)；第三条 bbs.deepin(2.0) 必须被截掉
 	if !strings.Contains(txt, "统信内核开发工程师") || !strings.Contains(txt, "离谱！") {
 		t.Errorf("前两条（按分数）应在:\n%s", txt)
 	}
 	if strings.Contains(txt, "deepin官方论坛") {
 		t.Errorf("第 3 条（score 最低）超出了 count=2，不该出现:\n%s", txt)
 	}
 	// 条目行数也要正好 2 条（防「头部说 2 条、正文还是全量」）
 	if n := strings.Count(txt, "\n   http"); n != 2 {
 		t.Errorf("正文应恰好 2 条，实际 %d 条:\n%s", n, txt)
 	}
 }
 // 14) 条数上限：不因为模型要 200 条就真给 200 条
 func TestLimitResultsCapsAndDefaults(t *testing.T) {
 	p := &Plugin{name: "deepsearch", maxItems: 8}
 	many := make([]searxResult, 30)
 	for i := range many {
 		many[i] = searxResult{URL: "https://e.test/", Title: "t"}
 	}
 	if got := len(p.limitResults(map[string]interface{}{}, many)); got != 8 {
 		t.Errorf("未指定 count 时应取配置的 max_items=8，实际 %d", got)
 	}
 	if got := len(p.limitResults(map[string]interface{}{"count": float64(3)}, many)); got != 3 {
 		t.Errorf("count=3 应返回 3 条，实际 %d", got)
 	}
 	if got := len(p.limitResults(map[string]interface{}{"count": float64(200)}, many)); got != maxSearchResults {
 		t.Errorf("超过上限应收敛到 %d 条，实际 %d", maxSearchResults, got)
 	}
 	// 结果比 count 少时不能造数据
 	few := many[:2]
 	if got := len(p.limitResults(map[string]interface{}{"count": float64(5)}, few)); got != 2 {
 		t.Errorf("结果不足时应原样返回，实际 %d", got)
 	}
 }
--- a/example/deepsearch/searxng.go
+++ b/example/deepsearch/searxng.go
@ -0,0 +1,164 @@
 package main
 // SearXNG 生命周期托管：插件启动时拉起搜索后端，插件停止时关闭它。
 //
 // 契约依据（内核侧 internal/plugin/proc/*，已逐行核对）：
 //   - 内核停止插件：发 `plugin.stop` → 插件先跑 RunStopHandlers（LIFO、幂等）→ 再 Stop() → exit(0)
 //   - 若插件未在 stopGracePeriod（**5 秒**）内退出，内核直接 SIGKILL
 //   - stdin 关闭（内核消失）同样会跑 handlers + Stop()
 //
 // 因此这里的关闭动作必须**有界**：searxShutdownBudget 取 4s，留 1s 余量。
 //
 // 归属规则（谁拉起谁关）：**只有本插件真正执行了 `docker compose up -d` 的实例才算「我们起的」**。
 // 探活发现已在运行的实例只「接管」——不认领关闭责任。否则同一台机器上的第二个实例
 // （E2E 测试拉起的插件、另一个 daemon）退出时会把生产后端一起带走：实测就是这条把
 // 线上搜索服务反复关停的（测试实例用默认配置，测试结束就 `docker compose stop`）。
 // 若插件是被 kill -9 / OOM 带走的，关闭动作不会执行 —— SearXNG 会留在运行态；
 // 下次 Start 探测到它在跑就直接接管，这是更安全的失败方向。
 import (
 	"context"
 	"log"
 	"net/http"
 	"os/exec"
 	"time"
 )
 const (
 	cfgManageSearx = "manage_searxng"
 	cfgSearxDir    = "searxng_dir"
 	cfgStopOnExit  = "stop_searxng_on_exit"
 	defaultSearxDir = "/root/searxng-agent"
 	searxProbeTimeout   = 1500 * time.Millisecond // 单次 healthz 探测
 	searxUpBudget       = 20 * time.Second        // docker compose up -d 的上限（正常 1s 内返回）
 	searxReadyBudget    = 6 * time.Second         // up 之后等 healthz 就绪的上限
 	searxShutdownBudget = 4 * time.Second         // 必须 < 内核 5s 宽限期
 )
 // searxBudget 把四个时间预算收拢，便于单测注入短值（否则测试要真等就绪窗口）。
 type searxBudget struct {
 	probe    time.Duration
 	up       time.Duration
 	ready    time.Duration
 	shutdown time.Duration
 }
 func (p *Plugin) budget() searxBudget {
 	b := p.bud
 	if b.probe == 0 {
 		b.probe = searxProbeTimeout
 	}
 	if b.up == 0 {
 		b.up = searxUpBudget
 	}
 	if b.ready == 0 {
 		b.ready = searxReadyBudget
 	}
 	if b.shutdown == 0 {
 		b.shutdown = searxShutdownBudget
 	}
 	return b
 }
 // cmdRunner 抽出来是为了让生命周期逻辑可单测：注入假执行器，不起真容器。
 type cmdRunner func(ctx context.Context, dir, name string, args ...string) (string, error)
 func defaultRunner(ctx context.Context, dir, name string, args ...string) (string, error) {
 	cmd := exec.CommandContext(ctx, name, args...)
 	cmd.Dir = dir
 	out, err := cmd.CombinedOutput()
 	return string(out), err
 }
 // searxReachable 探测搜索后端是否可用（只看 healthz，不发检索请求）。
 func (p *Plugin) searxReachable(timeout time.Duration) bool {
 	if p.searxURL == "" {
 		return false
 	}
 	base := p.http
 	if base == nil {
 		base = &http.Client{}
 	}
 	cl := *base // 复制一份，避免改到共享 client 的超时
 	cl.Timeout = timeout
 	req, err := http.NewRequest(http.MethodGet, p.searxURL+"/healthz", nil)
 	if err != nil {
 		return false
 	}
 	req.Header.Set("User-Agent", p.userAgent)
 	resp, err := cl.Do(req)
 	if err != nil {
 		return false
 	}
 	defer resp.Body.Close()
 	return resp.StatusCode < 400
 }
 // ensureSearxng 在插件启动时确保搜索后端在跑；已在跑则直接接管，不重启。
 func (p *Plugin) ensureSearxng() {
 	b := p.budget()
 	if !p.manageSearx {
 		log.Printf("[%s] 未启用 SearXNG 托管（manage_searxng=false），假定 %s 由外部维护", p.name, p.searxURL)
 		return
 	}
 	if p.searxReachable(b.probe) {
 		// 只接管，不认领：不是我们拉起来的，就不能由我们关掉
 		log.Printf("[%s] SearXNG 已在运行（%s），直接接管（不认领关闭责任）", p.name, p.searxURL)
 		return
 	}
 	ctx, cancel := context.WithTimeout(context.Background(), b.up)
 	out, err := p.run(ctx, p.searxDir, "docker", "compose", "up", "-d")
 	cancel()
 	if err != nil {
 		log.Printf("[%s] 拉起 SearXNG 失败（dir=%s，请检查 manage_searxng/searxng_dir 配置）: %v；输出: %s",
 			p.name, p.searxDir, err, oneLine(out, 300))
 		return
 	}
 	log.Printf("[%s] 已执行 docker compose up -d（%s）：%s", p.name, p.searxDir, oneLine(out, 200))
 	deadline := time.Now().Add(b.ready)
 	for time.Now().Before(deadline) {
 		if p.searxReachable(800 * time.Millisecond) {
 			log.Printf("[%s] SearXNG 就绪", p.name)
 			p.markSearxOwned()
 			return
 		}
 		time.Sleep(600 * time.Millisecond)
 	}
 	log.Printf("[%s] SearXNG 已启动但 %s 内未就绪；首次检索会自动等待", p.name, b.ready)
 	p.markSearxOwned()
 }
 func (p *Plugin) markSearxOwned() {
 	p.searxMu.Lock()
 	p.searxOwned = true
 	p.searxMu.Unlock()
 }
 // shutdownSearxng 关闭搜索后端。幂等，且有界（内核宽限期 5s，这里最多 4s）。
 func (p *Plugin) shutdownSearxng() {
 	b := p.budget()
 	p.searxMu.Lock()
 	owned := p.searxOwned
 	p.searxOwned = false
 	p.searxMu.Unlock()
 	if !owned {
 		return // 不是我们拉起来的 / 已经关过
 	}
 	if !p.manageSearx || !p.stopOnExit {
 		log.Printf("[%s] 保留 SearXNG 运行（stop_searxng_on_exit=false）", p.name)
 		return
 	}
 	ctx, cancel := context.WithTimeout(context.Background(), b.shutdown)
 	defer cancel()
 	out, err := p.run(ctx, p.searxDir, "docker", "compose", "stop", "-t", "2")
 	if err != nil {
 		// 故意只记日志：这里再重试就会拖过内核宽限期，被 SIGKILL 更糟
 		log.Printf("[%s] 关闭 SearXNG 失败（忽略）: %v；输出: %s", p.name, err, oneLine(out, 200))
 		return
 	}
 	log.Printf("[%s] 已关闭 SearXNG", p.name)
 }
--- a/example/deepsearch/searxng_test.go
+++ b/example/deepsearch/searxng_test.go
@ -0,0 +1,223 @@
 package main
 import (
 	"context"
 	"errors"
 	"net/http"
 	"net/http/httptest"
 	"strings"
 	"sync"
 	"testing"
 	"time"
 )
 type fakeCall struct {
 	dir  string
 	name string
 	args []string
 }
 func (c fakeCall) String() string { return c.name + " " + strings.Join(c.args, " ") }
 // newFakeRunner 记录调用并返回预设结果
 func newFakeRunner(calls *[]fakeCall, out string, err error) cmdRunner {
 	var mu sync.Mutex
 	return func(ctx context.Context, dir, name string, args ...string) (string, error) {
 		mu.Lock()
 		*calls = append(*calls, fakeCall{dir: dir, name: name, args: args})
 		mu.Unlock()
 		return out, err
 	}
 }
 // fastBudget 把就绪窗口压到毫秒级，避免单测真等
 func fastBudget() searxBudget {
 	return searxBudget{
 		probe:    50 * time.Millisecond,
 		up:       time.Second,
 		ready:    200 * time.Millisecond,
 		shutdown: time.Second,
 	}
 }
 // 1) 后端没跑 → 应执行 docker compose up -d，并认领关闭责任
 func TestEnsureSearxngStartsWhenUnreachable(t *testing.T) {
 	var calls []fakeCall
 	p := &Plugin{
 		name: "deepsearch", searxURL: "http://127.0.0.1:1", searxDir: "/tmp/fake-searx",
 		manageSearx: true, stopOnExit: true, userAgent: "test",
 		bud: fastBudget(), run: newFakeRunner(&calls, "Container searxng-agent Started", nil),
 	}
 	p.ensureSearxng()
 	if len(calls) != 1 {
 		t.Fatalf("应恰好拉起一次，实际 %d 次：%v", len(calls), calls)
 	}
 	got := calls[0]
 	if got.name != "docker" || strings.Join(got.args, " ") != "compose up -d" {
 		t.Errorf("命令不对：%s", got)
 	}
 	if got.dir != "/tmp/fake-searx" {
 		t.Errorf("工作目录应为配置的 compose 目录，实际 %q", got.dir)
 	}
 	if !p.searxOwned {
 		t.Error("既然是我们拉起的，就应认领关闭责任")
 	}
 }
 // 2) 后端已在跑 → 不重启，**且不认领关闭责任**
 //
 // 这条是关键：同一台机器上会有第二个实例（E2E 测试拉起的插件、另一个 daemon）。
 // 如果「接管」也算「我拥有」，任一实例退出就会把生产后端关掉 —— 线上实测就是
 // 测试实例在 teardown 时 `docker compose stop`，把搜索服务反复关停。
 func TestEnsureSearxngAdoptsRunningBackendWithoutOwning(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if r.URL.Path == "/healthz" {
 			_, _ = w.Write([]byte("OK"))
 			return
 		}
 		http.NotFound(w, r)
 	}))
 	defer srv.Close()
 	var calls []fakeCall
 	p := &Plugin{
 		name: "deepsearch", searxURL: srv.URL, searxDir: "/tmp/fake-searx",
 		manageSearx: true, stopOnExit: true, userAgent: "test",
 		bud: fastBudget(), run: newFakeRunner(&calls, "", nil),
 	}
 	p.ensureSearxng()
 	if len(calls) != 0 {
 		t.Errorf("已在跑就不该重启它，实际执行了：%v", calls)
 	}
 	if p.searxOwned {
 		t.Error("不是我们拉起的，就不能认领关闭责任（否则退出时会带走别人的后端）")
 	}
 }
 // 2b) 接管的实例退出时，一个 docker 命令都不能发
 func TestAdoptedBackendSurvivesShutdown(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		_, _ = w.Write([]byte("OK"))
 	}))
 	defer srv.Close()
 	var calls []fakeCall
 	p := &Plugin{
 		name: "deepsearch", searxURL: srv.URL, searxDir: "/tmp/fake-searx",
 		manageSearx: true, stopOnExit: true, userAgent: "test",
 		bud: fastBudget(), run: newFakeRunner(&calls, "", nil),
 	}
 	p.ensureSearxng()
 	if err := p.Stop(); err != nil {
 		t.Fatalf("Stop: %v", err)
 	}
 	if len(calls) != 0 {
 		t.Errorf("接管来的后端在退出时必须留着，实际执行了：%v", calls)
 	}
 }
 // 3) 关掉托管 → 完全不碰 docker
 func TestEnsureSearxngDisabled(t *testing.T) {
 	var calls []fakeCall
 	p := &Plugin{
 		name: "deepsearch", searxURL: "http://127.0.0.1:1", searxDir: "/tmp/fake-searx",
 		manageSearx: false, stopOnExit: true, userAgent: "test",
 		bud: fastBudget(), run: newFakeRunner(&calls, "", nil),
 	}
 	p.ensureSearxng()
 	if len(calls) != 0 || p.searxOwned {
 		t.Errorf("manage_searxng=false 时不该有任何动作：calls=%v owned=%v", calls, p.searxOwned)
 	}
 }
 // 4) 拉起失败不能让插件起不来（记日志即可）
 func TestEnsureSearxngFailureNonFatal(t *testing.T) {
 	var calls []fakeCall
 	p := &Plugin{
 		name: "deepsearch", searxURL: "http://127.0.0.1:1", searxDir: "/tmp/fake-searx",
 		manageSearx: true, stopOnExit: true, userAgent: "test",
 		bud: fastBudget(), run: newFakeRunner(&calls, "Cannot connect to the Docker daemon", errors.New("exit status 1")),
 	}
 	p.ensureSearxng() // 不应 panic
 	if p.searxOwned {
 		t.Error("没拉起来就不该认领关闭责任（否则停止时会去关一个不是我们起的服务）")
 	}
 }
 // 5) 停止：关掉我们拉起的后端，且幂等
 func TestShutdownStopsOwnedBackend(t *testing.T) {
 	var calls []fakeCall
 	runner := newFakeRunner(&calls, "ok", nil)
 	p := &Plugin{
 		name: "deepsearch", searxURL: "http://127.0.0.1:1", searxDir: "/tmp/fake-searx",
 		manageSearx: true, stopOnExit: true, userAgent: "test",
 		bud: fastBudget(), run: runner,
 	}
 	p.ensureSearxng()
 	calls = nil
 	p.shutdownSearxng()
 	if len(calls) != 1 {
 		t.Fatalf("应执行一次 compose stop，实际 %v", calls)
 	}
 	if got := strings.Join(calls[0].args, " "); !strings.HasPrefix(got, "compose stop") {
 		t.Errorf("停止命令不对：%s", got)
 	}
 	if p.searxOwned {
 		t.Error("停止后应清掉认领标记")
 	}
 	p.shutdownSearxng() // 幂等：不应再调一次
 	if len(calls) != 1 {
 		t.Errorf("重复停止应无副作用，实际 %v", calls)
 	}
 }
 // 6) 不是我们拉起的 → 停止时不许动它
 func TestShutdownSkippedWhenNotOwned(t *testing.T) {
 	var calls []fakeCall
 	p := &Plugin{
 		name: "deepsearch", searxDir: "/tmp/fake-searx", manageSearx: true, stopOnExit: true,
 		bud: fastBudget(), run: newFakeRunner(&calls, "", nil),
 	}
 	p.shutdownSearxng()
 	if len(calls) != 0 {
 		t.Errorf("不该去停一个我们没起的服务：%v", calls)
 	}
 }
 // 7) 配了「停止时保留」→ 认领过也不关
 func TestShutdownKeepsBackendWhenConfigured(t *testing.T) {
 	var calls []fakeCall
 	p := &Plugin{
 		name: "deepsearch", searxURL: "http://127.0.0.1:1", searxDir: "/tmp/fake-searx",
 		manageSearx: true, stopOnExit: false, userAgent: "test",
 		bud: fastBudget(), run: newFakeRunner(&calls, "", nil),
 	}
 	p.ensureSearxng()
 	calls = nil
 	p.shutdownSearxng()
 	if len(calls) != 0 {
 		t.Errorf("stop_searxng_on_exit=false 时不应关闭：%v", calls)
 	}
 }
 // 8) Stop() 自身也要收尾（内核 stdin 关闭路径不会走 stop handler 的注册顺序之外）
 func TestStopTriggersShutdown(t *testing.T) {
 	var calls []fakeCall
 	p := &Plugin{
 		name: "deepsearch", searxURL: "http://127.0.0.1:1", searxDir: "/tmp/fake-searx",
 		manageSearx: true, stopOnExit: true, userAgent: "test",
 		bud: fastBudget(), run: newFakeRunner(&calls, "", nil),
 	}
 	p.ensureSearxng()
 	calls = nil
 	if err := p.Stop(); err != nil {
 		t.Fatalf("Stop 返回错误: %v", err)
 	}
 	if len(calls) != 1 {
 		t.Errorf("Stop 应触发一次关闭，实际 %v", calls)
 	}
 }
--- a/example/editdoc/README.md
+++ b/example/editdoc/README.md
@ -0,0 +1,49 @@
 # editdoc · Office 文档编辑
 编辑 `.docx` / `.xlsx` / `.pptx` 内容：查找替换、改单元格、插行。
 > ⚠️ **版本说明**：本目录是 **v1.0.0**，只有 `edit_document` 一个工具。
 > 线上部署的 v2.0.0（全能办公版，支持新建/读取/转换 docx·xlsx·pptx·md·csv·txt）
 > **源码尚未公开**，本文档不描述那些能力。参见 `plugin.json` 的 `version`。
 ## 工具
 | 工具 | 说明 |
 |---|---|
 | `edit_document` | 编辑文档内容，**编辑后原文件被覆盖** |
 参数：
 | 参数 | 说明 |
 |---|---|
 | `file` | 文档路径（必填） |
 | `operation` | `replace_text`（查找替换）/ `set_cell`（设置单元格）/ `insert_row`（插入行）（必填） |
 | `target` | 要查找的文本（`replace_text` 用） |
 | `replacement` | 替换为的文本（`replace_text` 用） |
 | `sheet` | 工作表名（xlsx 可选） |
 | `row` | 行号（`set_cell` / `insert_row` 用） |
 | `col` | 列号（`set_cell` 用） |
 | `value` | 单元格值（`set_cell` 用） |
 编辑前建议先读一遍内容确认目标文本 —— 查找替换是**全文件覆盖写**，没有撤销。
 ## 配置项
 | 键 | 默认 | 说明 |
 |---|---|---|
 | `script_path` | 空 | `edit_doc.py` 的绝对路径。留空则用插件可执行文件同目录下的 `edit_doc.py` |
 | `venv_python` | 空 | 执行 `edit_doc.py` 的 Python 解释器（建议用 venv 里的）。**必须配置，留空会报错** |
 ## 工作原理
 本插件是 Go 写的薄壳：把参数序列化成 JSON，交给 Python 脚本 `edit_doc.py` 执行实际文档操作。
 文档解析依赖 Python 侧的库（python-docx / openpyxl / python-pptx 之类），所以：
 - **需要自备 `edit_doc.py`**：它不在本目录里。
 - 用 `venv_python` 指向装了这些库的解释器，避免污染系统 Python。
 ## 构建
 ```bash
 hmapdev build
 ```
--- a/example/files/README.md
+++ b/example/files/README.md
@ -0,0 +1,44 @@
 # files · 沙箱文件操作
 读写与编辑文件，**全部操作限制在沙箱目录内**。
 ## 工具
 | 工具 | 说明 |
 |---|---|
 | `files_read` | 读文件内容，支持 `offset` / `limit` 读大文件 |
 | `files_write` | 写文件，**自动创建父目录** |
 | `files_edit` | 按精确字符串替换改文件 |
 | `files_ls` | 列目录（目录名带 `/` 后缀） |
 `files_edit` 用 `edits[]` 传多组替换，每组 `{old, new}`：
 - 每个 `old` 必须在**原文件**中**恰好出现一次** —— 不唯一会报错，避免改错地方。
 - 所有替换都针对**原内容**匹配，不要在同一个 `edits` 里写相互重叠的改动。
 ## 配置项
 | 键 | 默认 | 说明 |
 |---|---|---|
 | `dir` | 空 | 允许访问的根目录。留空用默认沙箱（主数据目录下的 `files_sandbox`）。**不建议设为 `/`** |
 ## 沙箱实现
 路径校验不止一次，是两道：
 1. **规范化后判断**：`filepath.Abs` + `filepath.Clean`，再用 `withinSandbox`
   检查结果是否在根目录之下（`/` 作为特例放行）。
 2. **解析符号链接后再判断**：`filepath.EvalSymlinks` 求出真实路径，**再查一次**沙箱。
 第 2 步是关键：只做第 1 步的话，沙箱内一个指向外部的软链接就能绕过限制
 （`.../sandbox/link -> /etc`）。报错文案也区分了这两种情况
 （`path outside sandbox` vs `path escapes sandbox via symlink`）。
 对不存在的路径（`write` 会用到），求真实路径时只对已存在的部分做 `EvalSymlinks`，
 其余保留为未创建的尾部。
 ## 构建
 ```bash
 hmapdev build
 ```
--- a/example/luademo/README.md
+++ b/example/luademo/README.md
@ -1,13 +1,16 @@
 # luademo
-Lua 插件全功能示例，展示 v0.8.0 Lua SDK 的完整能力面：
+Lua 插件全功能示例，展示 Lua SDK 的完整能力面（对齐 SDK 1.3.0）：
- **工具注册**：`no_memory` + `cleaner`（记忆计算层过滤）
+- **工具注册**：`no_memory` + `context_policy` + `cleaner`（记忆计算层过滤）
 - **阶段钩子**：`register_stage(stage, handler, scope)`，`own_tools` 与全局作用域
- **通道**：`register_output_channel` / `register_input_channel`（def 支持 no_memory/cleaner）
+- **通道**：`register_output_channel` / `register_input_channel` / `unregister_output_channel`（def 支持 no_memory/context_policy/cleaner）
- **数据类 API**：`sdk.memory.*`、`sdk.doc.*`、`sdk.knowledge.*`、`sdk.text_memory.*`、`sdk.llm.*`、`sdk.settings.*`、`sdk.social.*`
+- **注入**：`inject_text` / `inject_interrupt` / `inject_text_no_memory`、`*_opts`（no_memory/context_policy/cleaner_name/priority）、`inject_input_sync`、`inject_*_media`、`set_tool_blocks`
 - **数据类 API**：`sdk.memory.*`（含 sentence_text/media_digests）、`sdk.doc.*`（含 insert_with_media）、`sdk.knowledge.*`、`sdk.text_memory.*`（含 attachments）、`sdk.llm.*`、`sdk.settings.*`、`sdk.social.*`、`sdk.events.*`、`sdk.plugin_mgr.*`
 - **其他**：`register_api`、`set_auto_restart`
 > `luademo_probe_v2` 巡检 1.1/1.2/1.3 新增面。它**故意不调用** `inject_input_sync`：工具 handler 在 LLM 回合内运行，同步注入会自己等自己（死锁）。
 ## 本地独立测试
 ```bash
@ -17,7 +20,7 @@ lua main.lua   # 使用 sdk.lua mock，不依赖内核
 ## 构建
 ```bash
-plugindev build
+hmapdev build
 ```
 ## 安装
--- a/example/luademo/main.lua
+++ b/example/luademo/main.lua
@ -67,6 +67,65 @@ function plugin.start(sdk)
    return { content = res }
  end)
  -- 工具：1.1/1.2/1.3 新增能力巡检（媒体块 / 注入标志位 / 事件 / 动态通道注销）
  -- 注意：故意不在这里调用 sdk.inject_input_sync——工具handler 运行在 LLM 回合内，
  -- 同步注入会等本轮回复，等于自己等自己（死锁）。同步注入只适合事件回调等外部入口。
  sdk.register_tool("luademo_probe_v2", {
    description = "Exercise media blocks, inject opts, events and channel unregister",
    parameters = { type = "object", properties = {} },
    no_memory = true,
    context_policy = "prune",
  }, function(args)
    local res = {}
    -- 多模态：设置下一轮 tool message 携带的内容块
    sdk.set_tool_blocks({
      { type = "text", text = "luademo media block" },
      { type = "image_url", image_url = { url = "https://example.com/x.png", detail = "low" } },
    })
    res.set_tool_blocks = "ok"
    -- 注入标志位（零值 opts 与旧三参数等价）
    sdk.inject_text_opts("luademo", "luademo_in", "opts inject", {
      no_memory = true, context_policy = "prune",
    })
    res.inject_text_opts = "ok"
    -- 带媒体的中断注入
    sdk.inject_interrupt_media("luademo", "luademo_in", "media inject", {
      { type = "audio_url", audio_url = { url = "https://example.com/a.mp3" } },
    })
    res.inject_interrupt_media = "ok"
    -- 媒体入记忆：三元组带原句，文档带附件
    local _, merr = sdk.memory.commit({{
      subject = "luademo", relation = "shows", object = "image",
      sentence_text = "luademo shows an image", media_digests = {},
    }})
    res.memory_commit_with_sentence = { err = merr }
    local _, derr = sdk.doc.insert_with_media(
      { id = "luademo-media", title = "media", content = "with attachment" },
      { { mime = "image/png", name = "x.png", data = "aGVsbG8=" } })
    res.doc_insert_with_media = { err = derr }
    -- 事件订阅（返回取消订阅函数）
    local unsub = sdk.events.subscribe("agent_output", function(evt)
      sdk.log("info", "luademo event: " .. tostring(evt.type))
    end)
    res.events_subscribe = type(unsub)
    if unsub then unsub() end
    -- 插件管理（只读查询）
    res.plugin_mgr_loaded = type(sdk.plugin_mgr.list_loaded())
    -- 动态输出通道注销
    sdk.register_output_channel("luademo_dyn", 0, "dynamic", {}, function(a) return { ok = true } end)
    local _, uerr = sdk.unregister_output_channel("luademo_dyn")
    res.unregister = { err = uerr }
    return { content = res }
  end)
  -- 阶段钩子：own_tools 作用域（仅本插件工具被调用时触发）
  sdk.register_stage("before_toolcall", function(ctx)
    local calls = ctx.tool_calls or {}
--- a/example/luademo/sdk.lua
+++ b/example/luademo/sdk.lua
@ -1,67 +1,413 @@
-- HomeAgent Lua Plugin SDK (standalone mock)
+-- HomeAgent Lua Plugin SDK
 -- Interface contract between Lua plugins and HomeAgent kernel.
 -- !impl functions are replaced by Go implementations at runtime.
 -- Standalone/debug: pure Lua mock implementations are used.
 -- Usage: local sdk = require("sdk")
 sdk = {}
-function sdk.log(level, msg) print("[lua-plugin] " .. tostring(level) .. ": " .. tostring(msg)) end
+
-function sdk.register_tool(name, def, handler) print("[lua-plugin] register_tool: " .. tostring(name)) end
+-- !impl
-function sdk.register_stage(stage, handler, scope) print("[lua-plugin] register_stage: " .. tostring(stage) .. " scope=" .. tostring(scope)) end
+-- level: "debug" | "info" | "warn" | "error"
-function sdk.register_api(name) print("[lua-plugin] register_api: " .. tostring(name)) end
+function sdk.log(level, msg)
-function sdk.register_output_channel(name, caps, desc, def, handler) print("[lua-plugin] register_output_channel: " .. tostring(name)) end
+    print("[lua-plugin] " .. tostring(level) .. ": " .. tostring(msg))
-function sdk.register_input_channel(name, def) print("[lua-plugin] register_input_channel: " .. tostring(name)) end
+end
-function sdk.get_setting(key) return nil end
+
-function sdk.set_setting(key, value) print("[lua-plugin] set_setting: " .. tostring(key)) end
+-- !impl
-function sdk.inject_text(source, channel, text) print("[lua-plugin] inject_text: " .. tostring(source)) end
+-- def: { description="...", parameters={...}, no_memory=true/false, cleaner=function(text)->text }
-function sdk.inject_interrupt(source, channel, text) print("[lua-plugin] inject_interrupt: " .. tostring(source)) end
+-- handler: function(args) -> result
-function sdk.inject_text_no_memory(source, channel, text) print("[lua-plugin] inject_text_no_memory: " .. tostring(source)) end
+function sdk.register_tool(name, def, handler)
-function sdk.set_auto_restart(enabled) print("[lua-plugin] set_auto_restart: " .. tostring(enabled)) end
+    print("[lua-plugin] register_tool: " .. tostring(name))
 end
 -- !impl
 -- stage: "on_input" | "pre_action" | "post_action" | ...
 -- scope: nil/"global" (默认) | "own_tools"（仅 before_toolcall/after_toolcall 且工具属于本插件时触发）
 function sdk.register_stage(stage, handler, scope)
    print("[lua-plugin] register_stage: " .. tostring(stage) .. " scope=" .. tostring(scope))
 end
 -- !impl
 function sdk.register_api(name)
    print("[lua-plugin] register_api: " .. tostring(name))
 end
 -- !impl
 -- def: { no_memory=true/false, cleaner=function(text)->text }
 -- handler: function(args) -> result
 function sdk.register_output_channel(name, caps, desc, def, handler)
    print("[lua-plugin] register_output_channel: " .. tostring(name))
 end
 -- !impl
 -- def: { no_memory=true/false, cleaner=function(text)->text }
 function sdk.register_input_channel(name, def)
    print("[lua-plugin] register_input_channel: " .. tostring(name))
 end
 -- !impl
 function sdk.get_setting(key)
    return nil
 end
 -- !impl
 function sdk.set_setting(key, value)
    print("[lua-plugin] set_setting: " .. tostring(key))
 end
 -- !impl
 function sdk.inject_text(source, channel, text)
    print("[lua-plugin] inject_text: " .. tostring(source) .. "/" .. tostring(channel))
 end
 -- !impl
 function sdk.inject_interrupt(source, channel, text)
    print("[lua-plugin] inject_interrupt: " .. tostring(source))
 end
 -- !impl
 function sdk.inject_text_no_memory(source, channel, text)
    print("[lua-plugin] inject_text_no_memory: " .. tostring(source))
 end
 -- !impl
 -- opts: { no_memory=bool, context_policy="none"|"prune", cleaner_name=string, priority="L1".."L3" }
 -- 零值/缺省 = 记入记忆 + 不裁剪（与三参数版本等价）。
 function sdk.inject_text_opts(source, channel, text, opts)
    print("[lua-plugin] inject_text_opts: " .. tostring(source))
 end
 -- !impl
 function sdk.inject_interrupt_opts(source, channel, text, opts)
    print("[lua-plugin] inject_interrupt_opts: " .. tostring(source))
 end
 -- !impl
 -- 同步注入在 Lua 插件中**不可用**：会等本轮回复，而本轮正持有插件锁 ⇒ 必然自锁。
 -- 真实内核里恒返回 (nil, err)；这里返回同样的错误，避免离线测试误以为可用。
 function sdk.inject_input_sync(source, channel, text)
    return nil, "同步注入在 Lua 插件中不可用：请在事件回调/外部入口用 inject_text/inject_interrupt；确需同步等待请改用 Go 插件。"
 end
 -- !impl
 function sdk.inject_input_sync_opts(source, channel, text, opts)
    return nil, "同步注入在 Lua 插件中不可用：请在事件回调/外部入口用 inject_text/inject_interrupt；确需同步等待请改用 Go 插件。"
 end
 -- !impl
 -- blocks: ContentBlock 数组，见 sdk.inject_input_media。
 -- 设置下一轮 tool message 携带的多模态内容块（模型据此看图/听音频）。
 function sdk.set_tool_blocks(blocks)
    print("[lua-plugin] set_tool_blocks: " .. tostring(blocks and #blocks or 0))
 end
 -- !impl
 -- blocks 每项：{ type="text", text="..." }
 --          | { type="image_url", image_url={ url="...", detail="high" } }
 --          | { type="audio_url", audio_url={ url="..." } }
 function sdk.inject_input_media(source, channel, text, blocks)
    print("[lua-plugin] inject_input_media: " .. tostring(source))
 end
 -- !impl
 function sdk.inject_input_media_opts(source, channel, text, blocks, opts)
    print("[lua-plugin] inject_input_media_opts: " .. tostring(source))
 end
 -- !impl
 -- 同 sdk.inject_input_sync：Lua 中不可用。
 function sdk.inject_input_media_sync(source, channel, text, blocks)
    return nil, "同步注入在 Lua 插件中不可用：请在事件回调/外部入口用 inject_input_media；确需同步等待请改用 Go 插件。"
 end
 -- !impl
 function sdk.inject_input_media_sync_opts(source, channel, text, blocks, opts)
    return nil, "同步注入在 Lua 插件中不可用：请在事件回调/外部入口用 inject_input_media_opts；确需同步等待请改用 Go 插件。"
 end
 -- !impl
 function sdk.inject_interrupt_media(source, channel, text, blocks)
    print("[lua-plugin] inject_interrupt_media: " .. tostring(source))
 end
 -- !impl
 function sdk.inject_interrupt_media_opts(source, channel, text, blocks, opts)
    print("[lua-plugin] inject_interrupt_media_opts: " .. tostring(source))
 end
 -- !impl
 -- 注销输出通道（随资源生灭的动态通道，如远程设备）。返回 (nil, err)。
 function sdk.unregister_output_channel(name) return nil, nil end
 -- !impl
 -- enabled: true/false，崩溃时内核自动拉起
 function sdk.set_auto_restart(enabled)
    print("[lua-plugin] set_auto_restart: " .. tostring(enabled))
 end
 -- ============ graph memory ============
 -- !impl
 sdk.memory = {}
 -- !impl
 -- query: string, depth: number -> {entities={...}, relations={...}}
 function sdk.memory.recall(query, depth) return {entities={}, relations={}} end
 -- !impl
 -- triples: { {subject=, relation=, object=, [confidence=], [sentence_text=]} } -> err
 function sdk.memory.commit(triples) return nil end
 -- !impl
 function sdk.memory.introspect() return {} end
 -- !impl
 function sdk.memory.merge(source, target) return 0 end
 -- !impl
 -- criteria: {key=value}, hard: boolean
 function sdk.memory.purge(criteria, hard) return 0 end
 -- ============ document memory ============
 -- !impl
 sdk.doc = {}
 -- !impl
 function sdk.doc.query(text, top_k) return {} end
 -- !impl
 -- doc: { id=, title=, content= }
 function sdk.doc.insert(doc) return nil end
 -- !impl
 -- attachments 每项：{ digest=, mime=, name=, data=<base64> }
 function sdk.doc.insert_with_media(doc, attachments) return nil end
 -- !impl
 function sdk.doc.remove(id) return nil end
 -- !impl
 function sdk.doc.stats() return {} end
 -- ============ knowledge ============
 -- !impl
 sdk.knowledge = {}
 -- !impl
 function sdk.knowledge.search(query, limit) return {} end
 -- !impl
 function sdk.knowledge.add(tag, content) return nil end
 -- !impl
 function sdk.knowledge.list() return {} end
 -- ============ text memory ============
 -- !impl
 sdk.text_memory = {}
 -- !impl
 -- evt: { timestamp=, role=, content=, channel= }
 function sdk.text_memory.append(evt) return nil end
 -- ============ llm ============
 -- !impl
 sdk.llm = {}
 -- !impl
 function sdk.llm.list_sources() return {} end
 -- !impl
 function sdk.llm.set_source(name) return nil end
 -- !impl
 function sdk.llm.current_source() return nil end
 -- ============ social (只读) ============
 -- !impl
 sdk.social = {}
 -- !impl
 function sdk.social.get_person(name) return {} end
 -- !impl
 function sdk.social.get_network(name, depth) return {} end
 -- !impl
 function sdk.social.get_trait(name, trait) return {value=nil, found=false} end
 -- !impl
 function sdk.social.get_relations(name) return {} end
 -- !impl
 function sdk.social.list_persons() return {} end
 -- ============ settings (作用域变体) ============
 -- !impl
 sdk.settings = {}
 -- !impl
 function sdk.settings.get_core(key) return nil end
 -- !impl
 function sdk.settings.set_core(key, value) return nil end
 -- !impl
 function sdk.settings.list_core(prefix) return {} end
 -- !impl
 function sdk.settings.get_plugin(plugin, key) return nil end
 -- !impl
 function sdk.settings.set_plugin(plugin, key, value) return nil end
 -- !impl
 function sdk.settings.list_plugin(plugin, prefix) return {} end
 -- !impl
 function sdk.settings.list(prefix) return {} end
 -- !impl
 -- def: { key=, type=, display_name=, description=, category=, options=, default=,
 --        min=, max=, step=, required=, secret= }
 function sdk.settings.register_def(def) return nil end
 -- !impl
 function sdk.settings.defs(prefix) return {} end
 -- !impl
 function sdk.settings.dump() return {} end
 -- !impl
 function sdk.settings.plugins() return {} end
 -- ============ events（只读订阅） ============
 -- !impl
 -- subscribe(event_type, handler) -> unsubscribe()
 -- handler 收到 { type=, source=, timestamp=, payload= }；
 -- 回调在其内核事件发布 goroutine 上执行，只做轻量转发，不可阻塞（Lua 单状态 + 互斥锁）。
 sdk.events = {}
 function sdk.events.subscribe(event_type, handler)
    print("[lua-plugin] events.subscribe: " .. tostring(event_type))
    return function() end
 end
 -- ============ plugin_mgr ============
 -- !impl
 sdk.plugin_mgr = {}
 function sdk.plugin_mgr.reload_one(name) return nil end
 function sdk.plugin_mgr.list_loaded() return {} end
 function sdk.plugin_mgr.is_disabled(name) return false end
 -- json utils (pure Lua)
 sdk.json = {}
 function sdk.json.encode(val)
-    if type(val) == "string" then return '"' .. val:gsub('"', '\\"'):gsub('\n', '\\n') .. '"'
+    local ok, result = pcall(function()
-    elseif type(val) == "number" or type(val) == "boolean" then return tostring(val)
+        local function _encode(v)
-    elseif type(val) == "table" then local parts, i = {}, 1
+            local t = type(v)
-        for k, v in pairs(val) do parts[i] = sdk.json.encode(k) .. ":" .. sdk.json.encode(v); i = i + 1 end
+            if t == "string" then
-        return "{" .. table.concat(parts, ",") .. "}" end
+                local s = v:gsub('\\', '\\\\'):gsub('"', '\\"'):gsub('\n', '\\n'):gsub('\r', '\\r'):gsub('\t', '\\t')
                return '"' .. s .. '"'
            elseif t == "number" then
                return tostring(v)
            elseif t == "boolean" then
                return tostring(v)
            elseif t == "table" then
                local keys = {}
                local is_array = true
                local maxn = 0
                for k in pairs(v) do
                    keys[#keys + 1] = k
                    if type(k) ~= "number" or k < 1 or k ~= math.floor(k) then
                        is_array = false
                    end
                    if type(k) == "number" and k > maxn then maxn = k end
                end
                if is_array and #keys >= maxn then
                    local parts = {}
                    for i = 1, maxn do
                        parts[#parts + 1] = _encode(v[i])
                    end
                    return "[" .. table.concat(parts, ",") .. "]"
                else
                    local parts = {}
                    for _, k in ipairs(keys) do
                        parts[#parts + 1] = _encode(tostring(k)) .. ":" .. _encode(v[k])
                    end
                    return "{" .. table.concat(parts, ",") .. "}"
                end
            else
                return "null"
            end
        end
        return _encode(val)
    end)
    if ok then return result end
    return "null"
 end
-function sdk.json.decode(str) local ok, fn = pcall(load, "return " .. str); if ok then return fn() end; return nil end
+
 function sdk.json.decode(str)
    local ok, result = pcall(function()
        local pos, _end = 1, #str
        local function skip()
            while pos <= _end and str:sub(pos, pos):match("%s") do pos = pos + 1 end
        end
        local function parse()
            skip()
            if pos > _end then return nil end
            local c = str:sub(pos, pos)
            if c == '"' then
                local s = {}
                pos = pos + 1
                while pos <= _end do
                    local ch = str:sub(pos, pos)
                    if ch == '"' then
                        pos = pos + 1
                        return table.concat(s)
                    elseif ch == '\\' then
                        pos = pos + 1
                        local n = str:sub(pos, pos)
                        if n == '"' then s[#s+1] = '"'
                        elseif n == '\\' then s[#s+1] = '\\'
                        elseif n == '/' then s[#s+1] = '/'
                        elseif n == 'b' then s[#s+1] = '\b'
                        elseif n == 'f' then s[#s+1] = '\f'
                        elseif n == 'n' then s[#s+1] = '\n'
                        elseif n == 'r' then s[#s+1] = '\r'
                        elseif n == 't' then s[#s+1] = '\t'
                        elseif n == 'u' then
                            local hex = str:sub(pos+1, pos+4)
                            pos = pos + 4
                            s[#s+1] = utf8 and utf8.char(tonumber(hex, 16)) or '?'
                        end
                        pos = pos + 1
                    else
                        s[#s+1] = ch
                        pos = pos + 1
                    end
                end
                return table.concat(s)
            elseif c == 't' then pos = pos + 4; return true
            elseif c == 'f' then pos = pos + 5; return false
            elseif c == 'n' then pos = pos + 4; return nil
            elseif c == '{' then
                pos = pos + 1; skip()
                local t = {}
                if str:sub(pos, pos) == '}' then pos = pos + 1; return t end
                while true do
                    skip(); local k = parse(); skip()
                    if str:sub(pos, pos) == ':' then pos = pos + 1 end
                    skip(); t[k] = parse(); skip()
                    local sep = str:sub(pos, pos)
                    if sep == '}' then pos = pos + 1; return t end
                    if sep == ',' then pos = pos + 1 end
                end
            elseif c == '[' then
                pos = pos + 1; skip()
                local t = {}
                if str:sub(pos, pos) == ']' then pos = pos + 1; return t end
                local idx = 1
                while true do
                    skip(); t[idx] = parse(); idx = idx + 1; skip()
                    local sep = str:sub(pos, pos)
                    if sep == ']' then pos = pos + 1; return t end
                    if sep == ',' then pos = pos + 1 end
                end
            else
                local s, e = str:find('^[-%d%.eE]+', pos)
                if s then
                    local num = tonumber(str:sub(s, e))
                    pos = e + 1
                    return num
                end
                return nil
            end
        end
        return parse()
    end)
    if ok then return result end
    return nil
 end
 -- http utils
 sdk.http = {}
-function sdk.http.get(url) print("[lua-plugin] http.get: " .. tostring(url)); return {status=200, body='{"mock":true}', headers={}} end
+
-function sdk.http.post(url, body, ct) print("[lua-plugin] http.post: " .. tostring(url)); return {status=200, body='{"mock":true}', headers={}} end
+-- !impl
 function sdk.http.get(url)
    print("[lua-plugin] http.get: " .. tostring(url))
    return {status=200, body='{"mock":true}', headers={}}
 end
 -- !impl
 function sdk.http.post(url, body, content_type)
    print("[lua-plugin] http.post: " .. tostring(url))
    return {status=200, body='{"mock":true}', headers={}}
 end
 return sdk
--- a/example/memo/README.md
+++ b/example/memo/README.md
@ -0,0 +1,43 @@
 # memo · 待办与备忘录
 两类条目，行为**刻意不同**：
 | 类型 | 用途 | 是否主动提醒 |
 |---|---|---|
 | **待办**（todo） | 有截止概念、需要被催的事 | ✅ 会 |
 | **备忘录**（memo） | 纯记事，供以后查阅 | ❌ 不会 |
 分开的理由：把"提醒我"和"记一下"混成一类，要么备忘录天天弹、要么待办被忘掉。
 ## 工具
 | 工具 | 说明 |
 |---|---|
 | `memo_todo_add` | 添加待办（会被主动提醒） |
 | `memo_todo_complete` | 标记待办完成（不再提醒） |
 | `memo_todo_list` | 列出未完成待办（含 ID、内容、创建时间） |
 | `memo_todo_delete` | 删除待办（含已完成的） |
 | `memo_memo_create` | 创建备忘录（纯记事，不提醒） |
 | `memo_memo_list` | 列出全部备忘录 |
 | `memo_memo_delete` | 删除备忘录 |
 > 工具名前缀取自插件名（`p.tp`），上面按默认的 `memo_` 写法列出。
 ## 提醒机制
 - 后台 **每 5 分钟**检查一次未完成待办数；有则通过 `InjectInterruptText` 注入一条
  「注意，你还有 N 条待办未完成，请检查」。
 - 注入带 **`NoMemory: true`** —— 这是定时提醒，不是记忆内容，不该进向量化。
 - 通道声明为 **`NoMemory`**（`RegisterInputChannel(p.name, ChannelDef{NoMemory:true})`），
  理由同上：提醒是瞬时信号。
 - 另有 `StagePreAction` 钩子，在每轮动作前参与。
 ## 存储
 条目落在数据目录的 `todos.json`，插件重启后仍在。
 ## 构建
 ```bash
 hmapdev build
 ```
--- a/example/memo/plugin.go
+++ b/example/memo/plugin.go
@ -48,6 +48,9 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
 	s.SetAutoRestart(true)
 	p.sdk = s
 	p.tp = p.name + "_"
 	// 入站通道：本插件用 p.name 通道注入输入（见 Inject* 调用），
 	// 输入侧必须显式登记 —— 否则"把该 inputch 划给驻留子"会报 `inputch 未注册`。
 	_ = s.RegisterInputChannel(p.name, sdk.ChannelDef{NoMemory: true})
 	dataDirVal, err := s.Settings().GetCore("core.daemon.data_dir")
 	if err != nil || dataDirVal == "" {
@ -292,8 +295,9 @@ func (p *Plugin) periodicCheck() {
 				continue
 			}
 			if p.sdk != nil {
-				p.sdk.InjectInterruptText(p.name, p.name,
+				// NoMemory：这是定时提醒，不是记忆内容。
-					fmt.Sprintf("注意，你还有%d条待办未完成，请检查", n))
+				p.sdk.InjectInterruptTextOpts(p.name, p.name,
 					fmt.Sprintf("注意，你还有%d条待办未完成，请检查", n), sdk.InjectOptions{NoMemory: true})
 			}
 		}
 	}
--- a/example/music/README.md
+++ b/example/music/README.md
@ -0,0 +1,30 @@
 # music · 音乐搜索
 按关键词搜歌、按 ID 查歌词（数据来自网易云音乐公开接口）。
 ## 工具
 | 工具 | 说明 |
 |---|---|
 | `music_search` | 按关键词搜歌，返回歌曲列表（含歌曲 ID） |
 | `music_lyrics` | 按歌曲 ID 取歌词 |
 典型两段式用法：先 `music_search` 拿 ID，再 `music_lyrics` 取词。
 ## 实现要点
 - 请求打的是 `https://music.163.com/api/...`，并固定带上 `Referer: https://music.163.com/` ——
  该接口对缺少来源头的请求会拒绝。
 - 是**只读**插件：不下载音频、不写本地文件，因此没有需要清理的副作用。
 ## 已知边界
 - 依赖第三方（网易云）公开接口，其可用性与返回结构不受本插件控制；
  接口变动时可能返回空列表，而不是报错。
 - 仅覆盖"搜索 + 歌词"，不含播放地址解析。
 ## 构建
 ```bash
 hmapdev build
 ```
--- a/example/ocr/README.md
+++ b/example/ocr/README.md
@ -0,0 +1,40 @@
 # ocr · 图片文字识别
 从图片里提取文字（中英文），基于 [Tesseract](https://github.com/tesseract-ocr/tesseract) OCR 引擎。
 ## 前置依赖
 需要系统里装有 `tesseract` 可执行文件：
 ```bash
 # Debian/Ubuntu
 apt install tesseract-ocr tesseract-ocr-chi-sim
 ```
 中文识别需要 `chi_sim` 语言包；缺它时中文会识别成乱码而非报错。
 ## 工具
 | 工具 | 说明 |
 |---|---|
 | `ocr_ocr_image` | 对图片做 OCR，返回识别文本 |
 参数：
 | 参数 | 说明 |
 |---|---|
 | `image_url` | 图片的 HTTP/HTTPS 地址（与 `image_data` 二选一） |
 | `image_data` | 图片的 base64 数据，**不含** `data:image/...` 前缀（与 `image_url` 二选一） |
 | `language` | 识别语言，默认 `chi_sim+eng`；可选 `chi_sim` / `eng` / `chi_sim+eng` |
 ## 实现要点
 - 传入的图先落到临时目录，OCR 完 `defer os.RemoveAll` 清掉，不残留。
 - 调用参数固定 `--psm 3`（全自动页面分割），适合截图与常规排版图片；对单行小图或竖排文本效果会下降。
 - **`Cleaner`**：工具返回的是 JSON（含 `text`、`language` 等字段），进记忆计算前只取 `text` 正文 —— 否则 JSON 结构本身会参与向量化。
 ## 构建
 ```bash
 hmapdev build
 ```
--- a/example/plugindev/README.md
+++ b/example/plugindev/README.md
@ -0,0 +1,47 @@
 # plugindev — 插件开发工具链（Agent 可调用）
 把 SDK 的 `hmapdev` 封装成插件，让 **Agent 自己**走完「新建插件 → 构建 → 安装」全流程，
 不需要人来敲命令行：
 ```
 plugindev_init    生成工程骨架（等价 hmapdev init <name> [--lua]）
      ↓  改 plugin.go
 plugindev_build   构建打包（等价在该目录 hmapdev build）→ dist/*.hmap
      ↓
 plugin_install    安装（用 path 指向刚构建出的 .hmap，overwrite=true 表示原地更新）
      ↓
 plgreload         重载生效
 ```
 ## 工具
 | 工具 | 参数 | 说明 |
 |---|---|---|
 | `plugindev_status` | — | hmapdev 是否可用/版本/当前 SDK 版本与路径/工作区；**排查"为什么不能构建"先用它** |
 | `plugindev_init` | `name`、`lang`(go/lua)、`dir` | 生成工程骨架；插件名必须 `[a-zA-Z0-9_-]{1,64}` |
 | `plugindev_build` | `dir`、`target` | 在工程目录构建打包；产物路径会在返回里给出 |
 | `plugindev_sdk` | `action`、`version`、`from` | SDK 版本管理（list/current/path/latest/install/use）；`from` 可指向本地 SDK 源码 |
 | `plugindev_projects` | — | 列出工作区里已有工程与产物 |
 ## 配置
 | 键 | 默认 | 说明 |
 |---|---|---|
 | `hmapdev_path` | 自动查找 | 依次尝试：本配置项 → PATH → `/usr/local/bin/hmapdev` → `/root/go/bin/hmapdev` |
 | `workspace_dir` | `<data_dir>/plugindev` | `plugindev_init` 生成工程的默认目录 |
 | `build_timeout_sec` | 600 | 单次 hmapdev 调用超时 |
 ## 前置：装 hmapdev
 ```bash
 cd <sdk-repo>/tools/hmapdev && go build -buildvcs=false -o /usr/local/bin/hmapdev .
 hmapdev version
 ```
 ## 安全边界（都在实现里，不只写在文档里）
 - 只 exec **hmapdev 一个可执行文件**，不接受任意命令、不做 shell 拼接；
 - `plugindev_build` 只接受含 `plg.json` 的目录（"看起来是插件工程"才构建），
  避免把这个工具变成对任意目录跑构建；
 - 子进程全部带超时，输出**截断**后才返回（构建日志动辄几百 KB，直接回灌会撑爆模型上下文）；
 - 工程名约束与内核/上游对"进工具名的标识符"的规则一致（`[a-zA-Z0-9_-]{1,64}`）。
--- a/example/plugindev/go.mod
+++ b/example/plugindev/go.mod
@ -0,0 +1,7 @@
 module plugindev
 go 1.25.0
 require gitcode.com/JianFeeeee/homeagent-sdk v0.0.0
 replace gitcode.com/JianFeeeee/homeagent-sdk => ../../
--- a/example/plugindev/main.go
+++ b/example/plugindev/main.go
@ -0,0 +1,11 @@
 //go:build !windows || !cgo
 package main
 import (
 	sdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk"
 )
 func NewPlugin(name string, config map[string]interface{}) (sdk.Plugin, error) {
 	return NewPluginFactory(name, config)
 }
--- a/example/plugindev/plg.json
+++ b/example/plugindev/plg.json
@ -0,0 +1,19 @@
 {
  "name": "plugindev",
  "name_zh": "插件开发工具链",
  "name_en": "Plugin Dev Toolchain",
  "version": "1.0.0",
  "description": "把 hmapdev 工具链封装成 Agent 可调用的工具：脚手架生成插件工程、构建打包 .hmap、管理 SDK 版本。配合 plugin_install 即可让 Agent 自己做完「新建插件 → 构建 → 安装」全流程。",
  "author": "HomeAgent",
  "entry": "plugin.so",
  "tags": [
    "plugindev",
    "toolchain",
    "developer"
  ],
  "targets": "linux/amd64",
  "outdir": "dist",
  "bundle": true,
  "replaces": {},
  "source_dirs": []
 }
--- a/example/plugindev/plugin.go
+++ b/example/plugindev/plugin.go
@ -0,0 +1,455 @@
 package main
 // plugindev：把 SDK 的 hmapdev 工具链封装成 Agent 可调用的插件。
 //
 // 为什么需要它：hmapdev 是"给人和 CI 用"的命令行工具。做成插件后，Agent 能自己：
 //   plugindev_init（脚手架）→ plugindev_build（构建出 .hmap）→ plugin_install（安装）→ plgreload
 // 也就是"让 Agent 自己写/改/装插件"这条链不需要人来敲命令。
 //
 // 安全边界（都在实现里落实，不只写在描述里）：
 //   - 只有 **hmapdev 一个可执行文件**会被 exec（不接受任意命令/参数拼接）；
 //   - `plugindev_build` 只接受"看起来是插件工程"的目录（含 plg.json），
 //     避免把一个 `hmapdev build` 变成对任意目录的操作；
 //   - `plugindev_init` 生成的工程名必须满足 `[a-zA-Z0-9_-]{1,64}`（与 LLM 函数名
 //     同一套约束 —— 插件名会进 `output_send__<通道>` 之类的工具名）；
 //   - 所有子进程都有超时，输出截断后再返回（防止把几十 MB 构建日志灌进模型上下文）。
 import (
 	"context"
 	"fmt"
 	"log"
 	"os"
 	"os/exec"
 	"path/filepath"
 	"regexp"
 	"sort"
 	"strings"
 	"time"
 	"gitcode.com/JianFeeeee/homeagent-sdk/sdk"
 )
 const (
 	defaultBuildTimeout = 10 * time.Minute
 	maxOutputChars      = 6000
 )
 // namePattern 与内核/上游对"会进工具名的标识符"的约束一致。
 var namePattern = regexp.MustCompile(`^[a-zA-Z0-9_-]{1,64}$`)
 type Plugin struct {
 	name string
 	sdk  *sdk.PluginSDK
 	hmapdev   string        // 解析到的 hmapdev 可执行文件路径
 	workspace string        // 默认工作区（生成的工程落在这里）
 	timeout   time.Duration // 单次 hmapdev 调用的超时
 }
 func NewPluginFactory(name string, config map[string]interface{}) (sdk.Plugin, error) {
 	return &Plugin{name: name}, nil
 }
 func (p *Plugin) Name() string { return p.name }
 func (p *Plugin) Start(s *sdk.PluginSDK) error {
 	p.sdk = s
 	s.SetAutoRestart(true)
 	s.Settings().RegisterDef(sdk.ConfigDef{
 		Key: "hmapdev_path", Type: "string", DisplayName: "hmapdev 路径",
 		Description: "插件开发工具链可执行文件路径。留空则按 PATH → /usr/local/bin/hmapdev → /root/go/bin/hmapdev 查找",
 		Category:    p.name,
 	})
 	s.Settings().RegisterDef(sdk.ConfigDef{
 		Key: "workspace_dir", Type: "string", DisplayName: "工程工作区",
 		Description: "plugindev_init 生成工程的默认目录。留空则用 <data_dir>/plugindev",
 		Category:    p.name,
 	})
 	s.Settings().RegisterDef(sdk.ConfigDef{
 		Key: "build_timeout_sec", Default: 600, Type: "int", DisplayName: "构建超时（秒）",
 		Description: "单次 hmapdev 调用的超时上限",
 		Category:    p.name,
 	})
 	p.hmapdev = p.resolveHmapdev()
 	p.workspace = p.resolveWorkspace()
 	p.timeout = defaultBuildTimeout
 	if v, _ := s.Settings().Get("build_timeout_sec"); v != nil {
 		if n, ok := toInt(v); ok && n > 0 {
 			p.timeout = time.Duration(n) * time.Second
 		}
 	}
 	s.RegisterTool("plugindev_status", sdk.ToolDef{
 		Name:        "plugindev_status",
 		Description: "查看插件开发工具链状态：hmapdev 是否可用、版本、当前 SDK 版本与路径、工程工作区目录。排查\"为什么不能构建插件\"时先用它。",
 		Parameters:  map[string]interface{}{"type": "object", "properties": map[string]interface{}{}},
 	}, p.handleStatus)
 	s.RegisterTool("plugindev_init", sdk.ToolDef{
 		Name:        "plugindev_init",
 		Description: "生成一个新的插件工程骨架（等价于 `hmapdev init <name> [--lua]`）。生成后在返回的目录里改 plugin.go，再用 plugindev_build 构建。",
 		Parameters: map[string]interface{}{
 			"type": "object",
 			"properties": map[string]interface{}{
 				"name": map[string]interface{}{
 					"type":        "string",
 					"description": "插件名（也是工程目录名）：只允许字母数字下划线短横，长度 1-64。例：my_plugin",
 				},
 				"lang": map[string]interface{}{
 					"type": "string", "description": "go（默认）或 lua",
 				},
 				"dir": map[string]interface{}{
 					"type": "string", "description": "在哪个目录下生成（默认工作区）。必须是已存在的目录",
 				},
 			},
 			"required": []string{"name"},
 		},
 	}, p.handleInit)
 	s.RegisterTool("plugindev_build", sdk.ToolDef{
 		Name:        "plugindev_build",
 		Description: "构建并打包一个插件工程（等价于在该工程目录里执行 `hmapdev build [target]`），产物是 dist/*.hmap。构建成功后用 plugin_install 安装（本地路径）。",
 		Parameters: map[string]interface{}{
 			"type": "object",
 			"properties": map[string]interface{}{
 				"dir": map[string]interface{}{
 					"type": "string", "description": "插件工程目录（必须含 plg.json）",
 				},
 				"target": map[string]interface{}{
 					"type": "string", "description": "构建目标，留空 = native（当前平台）。例：linux/amd64",
 				},
 			},
 			"required": []string{"dir"},
 		},
 	}, p.handleBuild)
 	s.RegisterTool("plugindev_sdk", sdk.ToolDef{
 		Name:        "plugindev_sdk",
 		Description: "管理插件 SDK 版本（hmapdev sdk 子命令）：list 列出已安装、current 当前版本、path 当前路径、latest 远端最新、install 安装某版本（可用 from 指定本地源码目录）、use 切换版本。构建插件报\"SDK 缺少某能力\"时用它升级 SDK。",
 		Parameters: map[string]interface{}{
 			"type": "object",
 			"properties": map[string]interface{}{
 				"action": map[string]interface{}{
 					"type": "string", "description": "list | current | path | latest | install | use",
 				},
 				"version": map[string]interface{}{
 					"type": "string", "description": "install/use 的版本号，如 v1.3.0",
 				},
 				"from": map[string]interface{}{
 					"type": "string", "description": "install 时用本地 SDK 源码目录（开发中的 SDK 用这个）",
 				},
 			},
 			"required": []string{"action"},
 		},
 	}, p.handleSDK)
 	s.RegisterTool("plugindev_projects", sdk.ToolDef{
 		Name:        "plugindev_projects",
 		Description: "列出工作区里已有的插件工程（名字、版本、是否已构建出 dist 产物），用于接续之前的开发。",
 		Parameters:  map[string]interface{}{"type": "object", "properties": map[string]interface{}{}},
 	}, p.handleProjects)
 	log.Printf("[plugindev] 就绪：hmapdev=%s 工作区=%s", fallback(p.hmapdev, "(未找到)"), p.workspace)
 	return nil
 }
 func (p *Plugin) Stop() error { return nil }
 // ---------------- 工具实现 ----------------
 func (p *Plugin) handleStatus(args map[string]interface{}) (interface{}, error) {
 	out := map[string]interface{}{
 		"hmapdev":   fallback(p.hmapdev, ""),
 		"workspace": p.workspace,
 	}
 	if p.hmapdev == "" {
 		out["available"] = false
 		out["hint"] = "未找到 hmapdev。请安装：go build -o /usr/local/bin/hmapdev <sdk>/tools/hmapdev"
 		return out, nil
 	}
 	out["available"] = true
 	if txt, err := p.run(nil, ""); err == nil {
 		out["version"] = strings.TrimSpace(txt)
 	} else {
 		out["error"] = err.Error()
 	}
 	if txt, err := p.run([]string{"sdk", "current"}, ""); err == nil {
 		out["sdk_current"] = strings.TrimSpace(txt)
 	}
 	if txt, err := p.run([]string{"sdk", "path"}, ""); err == nil {
 		out["sdk_path"] = strings.TrimSpace(txt)
 	}
 	return out, nil
 }
 func (p *Plugin) handleInit(args map[string]interface{}) (interface{}, error) {
 	name, _ := args["name"].(string)
 	name = strings.TrimSpace(name)
 	if !namePattern.MatchString(name) {
 		return map[string]interface{}{
 			"error": "插件名只允许 [a-zA-Z0-9_-]，长度 1-64（它会进 LLM 工具名，违规会让整条请求被上游拒绝）",
 		}, nil
 	}
 	dir, _ := args["dir"].(string)
 	if dir == "" {
 		dir = p.workspace
 	}
 	if st, err := os.Stat(dir); err != nil || !st.IsDir() {
 		return map[string]interface{}{"error": fmt.Sprintf("目录不存在: %s", dir)}, nil
 	}
 	cmd := []string{"init", name}
 	if lang, _ := args["lang"].(string); strings.EqualFold(lang, "lua") {
 		cmd = append(cmd, "--lua")
 	}
 	txt, err := p.run(cmd, dir)
 	res := map[string]interface{}{"output": txt, "project_dir": filepath.Join(dir, name)}
 	if err != nil {
 		res["error"] = err.Error()
 	}
 	return res, nil
 }
 func (p *Plugin) handleBuild(args map[string]interface{}) (interface{}, error) {
 	dir, _ := args["dir"].(string)
 	if dir == "" {
 		return map[string]interface{}{"error": "dir 不能为空"}, nil
 	}
 	abs, err := filepath.Abs(dir)
 	if err != nil {
 		return map[string]interface{}{"error": err.Error()}, nil
 	}
 	// 只在"插件工程"里构建：必须存在 plg.json。这样这个工具不会变成对任意目录跑构建。
 	manifest := filepath.Join(abs, "plg.json")
 	if _, err := os.Stat(manifest); err != nil {
 		return map[string]interface{}{
 			"error": fmt.Sprintf("%s 不是插件工程（缺 plg.json）；用 plugindev_init 先建一个", abs),
 		}, nil
 	}
 	cmd := []string{"build"}
 	if target, _ := args["target"].(string); strings.TrimSpace(target) != "" {
 		cmd = append(cmd, strings.TrimSpace(target))
 	}
 	txt, runErr := p.run(cmd, abs)
 	res := map[string]interface{}{"output": txt, "project_dir": abs}
 	if pkgs := listHmap(filepath.Join(abs, "dist")); len(pkgs) > 0 {
 		res["artifacts"] = pkgs
 		res["next"] = "用 plugin_install 安装本地产物（path 指向上面 artifacts 里的 .hmap），然后 plgreload"
 	}
 	if runErr != nil {
 		res["error"] = runErr.Error()
 	}
 	return res, nil
 }
 func (p *Plugin) handleSDK(args map[string]interface{}) (interface{}, error) {
 	action, _ := args["action"].(string)
 	action = strings.TrimSpace(action)
 	switch action {
 	case "list", "current", "path", "latest":
 		txt, err := p.run([]string{"sdk", action}, "")
 		res := map[string]interface{}{"output": txt}
 		if err != nil {
 			res["error"] = err.Error()
 		}
 		return res, nil
 	case "install":
 		version, _ := args["version"].(string)
 		from, _ := args["from"].(string)
 		cmd := []string{"sdk", "install"}
 		if strings.TrimSpace(from) != "" {
 			cmd = append(cmd, "--from", strings.TrimSpace(from))
 		}
 		if strings.TrimSpace(version) != "" {
 			cmd = append(cmd, strings.TrimSpace(version))
 		} else if strings.TrimSpace(from) == "" {
 			cmd = append(cmd, "latest")
 		}
 		txt, err := p.run(cmd, "")
 		res := map[string]interface{}{"output": txt}
 		if err != nil {
 			res["error"] = err.Error()
 		}
 		return res, nil
 	case "use":
 		version, _ := args["version"].(string)
 		if strings.TrimSpace(version) == "" {
 			return map[string]interface{}{"error": "use 需要 version"}, nil
 		}
 		txt, err := p.run([]string{"sdk", "use", strings.TrimSpace(version)}, "")
 		res := map[string]interface{}{"output": txt}
 		if err != nil {
 			res["error"] = err.Error()
 		}
 		return res, nil
 	default:
 		return map[string]interface{}{"error": "action 只能是 list/current/path/latest/install/use"}, nil
 	}
 }
 func (p *Plugin) handleProjects(args map[string]interface{}) (interface{}, error) {
 	entries, err := os.ReadDir(p.workspace)
 	if err != nil {
 		return map[string]interface{}{"error": err.Error(), "workspace": p.workspace}, nil
 	}
 	var out []map[string]interface{}
 	for _, e := range entries {
 		if !e.IsDir() {
 			continue
 		}
 		dir := filepath.Join(p.workspace, e.Name())
 		projects := []string{dir}
 		// 有些工程会被生成到子目录里（hmapdev init 支持指定目录），这里只看一层
 		for _, sub := range projects {
 			if _, err := os.Stat(filepath.Join(sub, "plg.json")); err != nil {
 				continue
 			}
 			item := map[string]interface{}{"name": e.Name(), "dir": sub}
 			if v := readPlgVersion(filepath.Join(sub, "plg.json")); v != "" {
 				item["version"] = v
 			}
 			if pkgs := listHmap(filepath.Join(sub, "dist")); len(pkgs) > 0 {
 				item["artifacts"] = pkgs
 			}
 			out = append(out, item)
 		}
 	}
 	sort.Slice(out, func(i, j int) bool { return out[i]["name"].(string) < out[j]["name"].(string) })
 	return map[string]interface{}{"workspace": p.workspace, "projects": out}, nil
 }
 // ---------------- 基础设施 ----------------
 // run 执行一次 hmapdev。args 为空时执行 `hmapdev version`（用于探活）。
 func (p *Plugin) run(args []string, dir string) (string, error) {
 	if p.hmapdev == "" {
 		return "", fmt.Errorf("未找到 hmapdev 可执行文件")
 	}
 	ctx, cancel := context.WithTimeout(context.Background(), p.timeout)
 	defer cancel()
 	cmd := exec.CommandContext(ctx, p.hmapdev, args...)
 	if dir != "" {
 		cmd.Dir = dir
 	}
 	// 继承环境（Go 工具链需要 GOCACHE/GOPATH/PATH 等）。
 	out, err := cmd.CombinedOutput()
 	txt := truncateOutput(string(out))
 	if ctx.Err() == context.DeadlineExceeded {
 		return txt, fmt.Errorf("hmapdev %s 超时（%s）", strings.Join(args, " "), p.timeout)
 	}
 	if err != nil {
 		return txt, fmt.Errorf("hmapdev %s 失败: %v", strings.Join(args, " "), err)
 	}
 	return txt, nil
 }
 // resolveHmapdev 依次尝试：配置项 → PATH → 常见安装位置。
 func (p *Plugin) resolveHmapdev() string {
 	if v, _ := p.sdk.Settings().Get("hmapdev_path"); v != nil {
 		if s, _ := v.(string); strings.TrimSpace(s) != "" {
 			if _, err := os.Stat(strings.TrimSpace(s)); err == nil {
 				return strings.TrimSpace(s)
 			}
 		}
 	}
 	if path, err := exec.LookPath("hmapdev"); err == nil {
 		return path
 	}
 	for _, cand := range []string{"/usr/local/bin/hmapdev", "/root/go/bin/hmapdev"} {
 		if _, err := os.Stat(cand); err == nil {
 			return cand
 		}
 	}
 	return ""
 }
 // resolveWorkspace：配置项 → <data_dir>/plugindev → ./plugindev。
 func (p *Plugin) resolveWorkspace() string {
 	if v, _ := p.sdk.Settings().Get("workspace_dir"); v != nil {
 		if s, _ := v.(string); strings.TrimSpace(s) != "" {
 			ws := strings.TrimSpace(s)
 			_ = os.MkdirAll(ws, 0o755)
 			return ws
 		}
 	}
 	if v, err := p.sdk.Settings().GetCore("core.daemon.data_dir"); err == nil {
 		if dd, _ := v.(string); dd != "" {
 			ws := filepath.Join(dd, "plugindev")
 			_ = os.MkdirAll(ws, 0o755)
 			return ws
 		}
 	}
 	ws := "plugindev"
 	_ = os.MkdirAll(ws, 0o755)
 	return ws
 }
 // truncateOutput 截断长输出：构建日志动辄几百 KB，直接返回会灌爆模型上下文。
 func truncateOutput(s string) string {
 	if len(s) <= maxOutputChars {
 		return s
 	}
 	head := s[:maxOutputChars/2]
 	tail := s[len(s)-maxOutputChars/2:]
 	return fmt.Sprintf("%s\n…（输出被截断，共 %d 字节）…\n%s", head, len(s), tail)
 }
 // listHmap 列出目录下的 .hmap 产物（按名字排序，稳定输出）。
 func listHmap(dir string) []string {
 	entries, err := os.ReadDir(dir)
 	if err != nil {
 		return nil
 	}
 	var out []string
 	for _, e := range entries {
 		if e.IsDir() || !strings.HasSuffix(e.Name(), ".hmap") {
 			continue
 		}
 		out = append(out, filepath.Join(dir, e.Name()))
 	}
 	sort.Strings(out)
 	return out
 }
 func readPlgVersion(path string) string {
 	b, err := os.ReadFile(path)
 	if err != nil {
 		return ""
 	}
 	s := string(b)
 	i := strings.Index(s, `"version"`)
 	if i < 0 {
 		return ""
 	}
 	rest := s[i:]
 	j := strings.Index(rest, ":")
 	if j < 0 {
 		return ""
 	}
 	rest = strings.TrimSpace(rest[j+1:])
 	rest = strings.TrimPrefix(rest, `"`)
 	if k := strings.Index(rest, `"`); k > 0 {
 		return rest[:k]
 	}
 	return ""
 }
 func toInt(v interface{}) (int, bool) {
 	switch n := v.(type) {
 	case int:
 		return n, true
 	case int64:
 		return int(n), true
 	case float64:
 		return int(n), true
 	}
 	return 0, false
 }
 func fallback(s, def string) string {
 	if strings.TrimSpace(s) == "" {
 		return def
 	}
 	return s
 }
--- a/example/qq/README.md
+++ b/example/qq/README.md
@ -0,0 +1,167 @@
 # qq · QQ 消息桥接
 通过 [NapCat](https://github.com/NapNeko/NapCatQQ) 把 QQ 接成 HomeAgent 的一个 IO 通道：
 让 agent 收发 QQ 消息、读群/好友信息、传文件。
 > ⚠️ 这是**安全敏感**插件：它让外部 QQ 用户能触达 agent 的工具。
 > 本文档的「权限模型」一节请务必读完。
 ## 通道与钩子
 | 类型 | 名称 | 说明 |
 |---|---|---|
 | 出站 | `qq` | `CapText` + `CapFile` + `CapImage` + `CapAudio`；发消息/文件给 QQ |
 | 入站 | `qq` | `NoMemory: true` + `Cleaner` + `RecallPolicy: None` |
 四个阶段钩子（全部 `StageScopeGlobal`）：
 | 钩子 | 作用 |
 |---|---|
 | `on_input` | 把本轮 QQ 身份**绑到帧上** |
 | `before_toolcall` | 权限门：逐个工具判断是否放行 |
 | `post_action` | 清掉被拒绝时模型已经吐出的废话 |
 | `after_output` | 收尾时清理插件全局身份 |
 ## 工具（20 个）
 | 工具 | 说明 |
 |---|---|
 | `qq_get_message` | 按 `message_id` 取消息正文、发送者、附件 |
 | `qq_get_history` | 取群/私聊最近历史消息 |
 | `qq_list_chats` | 会话列表（按最新消息排序，带未读数与摘要） |
 | `qq_mark_read` | 把某会话未读数清零 |
 | `qq_send_file` | 发文件/图片（私聊或群聊） |
 | `qq_get_groups` | 群列表，可按关键词搜 |
 | `qq_get_friends` | 好友列表，可按昵称/备注搜 |
 | `qq_get_recent_contacts` | 最近有消息的联系人与群 |
 | `qq_resolve_name` / `qq_resolve_nickname` | 名字 ↔ QQ 号互查 |
 | `qq_get_group_member_info` | 群成员信息 |
 | `qq_group_manage` | 群综合管理（见下） |
 | `qq_friend_action` | 好友操作 |
 | `qq_get_group_files` | 群文件列表 |
 | `qq_download_file` / `qq_upload_group_file` / `qq_get_download_tasks` | 文件传输与任务 |
 | `qq_read_document` | 读 QQ 传来的文档 |
 | `qq_video_download` | 下载视频 |
 | `qq_send_like` | 点赞 |
 `qq_group_manage` 一个工具承载多种操作（`command` 参数）：
 `leave` 退群、`kick` 踢人、`ban`/`unban` 禁言解禁、`rename` 改名、`mute-all` 全员禁言、
 `set-card` 设名片、`set-admin` 设管理、`set-title` 设头衔、`member-list`、`group-info`、
 `msg-history`、`recall` 撤回、`pin-msg` 精华、`list-files`、`pending-requests`、`folder-create` 等。
 **破坏性操作**（`leave`/`kick`/`ban`/`unban`/`rename`/`mute-all`/`set-card`/`set-admin`/
 `set-title`/`recall`/`pin-msg`/`folder-create`）**必须显式传 `confirm: true`**。
 ## 权限模型
 这是本插件最重要的部分。
 ### 身份分级
 | 身份 | 权限 |
 |---|---|
 | **owner**（Bot 所有者） | 私聊或群聊均**完整放行** |
 | **普通 QQ 用户** | 只放行白名单内的工具 |
 ### 身份必须「绑帧」，不能只存插件全局
 源码注释记录了两个真实故障，这就是绑帧的原因：
 1. **中断抢占后身份丢失**：中断会抢占当前轮、把现场压栈。中断轮收尾时
   `after_output` 会清空插件**全局**身份；随后外层被恢复（`resumeTask` 复用同一帧、
   **不重跑 `on_input`**）。若身份只存全局，恢复后的外层就是"无身份"，
   `before_toolcall` 在 `!auth.active` 处直接返回 —— **整个权限门失效**。
 2. **运行中到达的消息改写身份**：新消息会调 `activateAuthContext` 改写全局身份，
   把**正在跑的那一轮**换成另一方的身份（换高=越权，换低=误拒）。
 帧上的 `Extra` 随帧一起压栈/恢复，正好是"这一轮的身份"。
 ### 合并取最小权限
 多来源被内核合并到同一推理时，权限**取交集**而非并集：
 ```go
 p.auth.owner = p.auth.owner && next.owner
 ```
 防的是"非所有者请求 + 随后所有者消息"意外把前一个请求提权。
 ### 硬私有工具
 非所有者**一律拒绝**（不看白名单），按前缀拦截：
 `calendar_`、`email_`、`mail_`、`agentmail_`、`memory_`、`knowledge_`、`device_`、
 `devicectl_`、`terminal_`、`shell_`、`command_`、`exec_`、`filesystem_`、`agentfs_`、
 `config_`、`settings_`、`plugin_`、`plugins_`，
 外加 `read_file`、`write_file`、`edit_file`、`delete_file`、`list_files`、`run_command`、
 `homeagent_config`、`homeagent_restart`、`output_send__email`、`output_send__mail`。
 ### 参数与会话一致性校验
 光看工具名不够，还要检查**参数指向的会话与当前身份一致**，否则可以拿别人的
 `message_id` 去读别处内容：
 - 带 `message_id` 的工具：该 ID 必须属于当前 QQ 会话（`lookupMsgRef` 校验 peer 与群/私聊类型）。
 - `get_group_member_info` / `get_group_files`：`group_id` 必须是**当前群**。
 ### 频率与重复控制
 | 键 | 作用 |
 |---|---|
 | `max_qq_tool_calls` | 单轮工具调用上限 |
 | `max_qq_output_calls` | 单轮输出调用上限 |
 | `max_duplicate_qq_send` | 重复发送上限，防刷屏 |
 | `batch_window_ms` / `batch_max_ms` | 消息合批窗口 |
 被拒时只允许**发一次权鉴说明**，之后锁止本轮剩余工具调用
 （`clearDeniedResponse` 再把模型已写出的内容清掉，避免输出里带一堆"我不能…"）。
 ## 配置项
 ### 连接
 | 键 | 默认 | 说明 |
 |---|---|---|
 | `napcat_url` | — | NapCat 服务地址 |
 | `listen` | — | 本插件 HTTP 监听地址 |
 | `webhook_token` | — | webhook 校验令牌 |
 ### 身份与准入
 | 键 | 默认 | 说明 |
 |---|---|---|
 | `owner` | 空 | Bot 所有者 QQ 列表（逗号分隔），拥有完整权限 |
 | `admin` | 空 | **旧配置名**，`owner` 为空时作为所有者列表（兼容用） |
 | `dm_policy` | `open` | 私聊策略：`open` / `allowlist` / `disabled` |
 | `allow_from` | 空 | 私聊白名单（QQ 号，逗号分隔） |
 | `group_policy` | `open` | 群聊策略：`open` / `allowlist` / `disabled` |
 | `group_allow_from` | 空 | 群白名单 |
 | `private_tool_allowlist` | 空 | 私聊下非所有者可用的工具 |
 | `group_tool_allowlists` | 空 | 按群配置的工具白名单 |
 ### 文件与转发
 | 键 | 说明 |
 |---|---|
 | `files_dir` | 本地文件目录 |
 | `remote_dir` | 供 NapCat 容器访问的目录（发文件前先复制到这里） |
 | `agentfs_dir` | agent 文件系统目录 |
 | `forward_rules` | JSON 数组，每项 `{group_id,host,port,password,template}`：匹配的群消息经 **RCON** 转发到 Minecraft；`template` 支持 `{nickname}` / `{message}` 占位 |
 ## 部署前提
 需要**自行部署 NapCat**（本插件不含 QQ 协议实现，只是 NapCat 的客户端）。
 发文件前会先把文件复制到 `remote_dir`，因为 NapCat 通常在容器里，看不到宿主任意路径。
 ## 测试
 ```bash
 go test -count=1 -race ./...
 ```
 含权限门与绑帧的回归测试。改动权限相关代码后务必跑 `-race`。
 ## 构建
 ```bash
 hmapdev build
 ```
--- a/example/qq/plg.json
+++ b/example/qq/plg.json
@ -2,7 +2,7 @@
  "name": "qq",
  "name_zh": "QQ消息",
  "name_en": "qq",
-  "version": "1.2.0",
+  "version": "1.4.1",
  "description": "QQ 消息收发插件，通过 NapCat 协议桥接",
  "author": "HomeAgent",
  "entry": "plugin.so",
--- a/example/qq/plugin.go
+++ b/example/qq/plugin.go
--- a/example/qq/plugin_test.go
+++ b/example/qq/plugin_test.go
@ -0,0 +1,433 @@
 package main
 import (
 	"encoding/json"
 	"fmt"
 	"net/http"
 	"net/http/httptest"
 	"strings"
 	"testing"
 	"time"
 	"gitcode.com/JianFeeeee/homeagent-sdk/sdk"
 )
 func newPermissionTestPlugin(t *testing.T) *Plugin {
 	t.Helper()
 	instance, err := NewPluginFactory("qq", nil)
 	if err != nil {
 		t.Fatal(err)
 	}
 	return instance.(*Plugin)
 }
 func toolCallContext(name string, args map[string]interface{}) *sdk.StageContext {
 	return &sdk.StageContext{ToolCalls: []sdk.ToolCall{{Name: name, Arguments: args}}}
 }
 func TestOwnerBypassesQQPermissionBoundary(t *testing.T) {
 	p := newPermissionTestPlugin(t)
 	p.auth = qqAuthContext{active: true, owner: true, userID: 2198972886}
 	ctx := toolCallContext("calendar_list", nil)
 	if err := p.beforeToolcall(ctx); err != nil {
 		t.Fatal(err)
 	}
 	if ctx.Response != nil {
 		t.Fatalf("owner call rejected: %s", *ctx.Response)
 	}
 }
 func TestPrivateResourceCannotBeAllowlisted(t *testing.T) {
 	p := newPermissionTestPlugin(t)
 	p.privateToolAllowlist = append(p.privateToolAllowlist, "calendar_*")
 	p.auth = qqAuthContext{active: true, userID: 10001}
 	ctx := toolCallContext("calendar_list", nil)
 	if err := p.beforeToolcall(ctx); err != nil {
 		t.Fatal(err)
 	}
 	if ctx.Response == nil || !strings.Contains(*ctx.Response, "私人资源工具") {
 		t.Fatalf("expected private-resource denial, got %#v", ctx.Response)
 	}
 }
 func TestNonOwnerQQHistoryIsScopedToCurrentGroup(t *testing.T) {
 	p := newPermissionTestPlugin(t)
 	p.auth = qqAuthContext{active: true, messageID: 88, userID: 10001, groupID: 20002, isGroup: true}
 	ctx := toolCallContext("qq_get_history", map[string]interface{}{"group_id": int64(20003)})
 	if err := p.beforeToolcall(ctx); err != nil {
 		t.Fatal(err)
 	}
 	if ctx.Response == nil || !strings.Contains(*ctx.Response, "当前 QQ 会话") {
 		t.Fatalf("cross-group history not rejected: %#v", ctx.Response)
 	}
 	ctx = toolCallContext("qq_get_history", map[string]interface{}{"group_id": int64(20002)})
 	if err := p.beforeToolcall(ctx); err != nil {
 		t.Fatal(err)
 	}
 	if ctx.Response != nil {
 		t.Fatalf("current-group history rejected: %s", *ctx.Response)
 	}
 }
 func TestUnmatchedQQInputIsDowngraded(t *testing.T) {
 	p := newPermissionTestPlugin(t)
 	p.auth = qqAuthContext{active: true, owner: true, userID: 2198972886}
 	ctx := &sdk.StageContext{
 		RawMessage: "来自未知事件(message_id=404)",
 		Extra:      map[string]interface{}{"input_source": "qq"},
 	}
 	if err := p.onInputAuthContext(ctx); err != nil {
 		t.Fatal(err)
 	}
 	if !p.auth.active || p.auth.owner || p.auth.userID != 0 {
 		t.Fatalf("unmatched input reused prior privilege: %+v", p.auth)
 	}
 }
 func TestDuplicateQQOutputIsStopped(t *testing.T) {
 	p := newPermissionTestPlugin(t)
 	p.maxDuplicateSend = 1
 	p.auth = qqAuthContext{active: true, owner: true, userID: 2198972886}
 	args := map[string]interface{}{"payload": "same", "type": "text", "meta": `{"user_id":123}`}
 	ctx := toolCallContext("output_send__qq", args)
 	if err := p.beforeToolcall(ctx); err != nil {
 		t.Fatal(err)
 	}
 	if ctx.Response != nil {
 		t.Fatalf("first send rejected: %s", *ctx.Response)
 	}
 	ctx = toolCallContext("output_send__qq", args)
 	if err := p.beforeToolcall(ctx); err != nil {
 		t.Fatal(err)
 	}
 	if ctx.Response == nil || !strings.Contains(*ctx.Response, "循环保险") {
 		t.Fatalf("duplicate send not stopped: %#v", ctx.Response)
 	}
 }
 func TestGroupAndUserRouteAddsLeadingMention(t *testing.T) {
 	var path string
 	var request map[string]interface{}
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		path = r.URL.Path
 		if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
 			t.Errorf("decode request: %v", err)
 		}
 		w.Header().Set("Content-Type", "application/json")
 		_, _ = w.Write([]byte(`{"status":"ok","retcode":0,"data":{"message_id":1}}`))
 	}))
 	defer server.Close()
 	p := newPermissionTestPlugin(t)
 	p.napcatURL = server.URL
 	p.httpClient = server.Client()
 	_, err := p.handleChannelOutput(map[string]interface{}{
 		"payload": "hello",
 		"type":    "text",
 		"meta":    `{"group_id":20002,"user_id":10001}`,
 	})
 	if err != nil {
 		t.Fatal(err)
 	}
 	if path != "/send_group_msg" {
 		t.Fatalf("path=%q, want /send_group_msg", path)
 	}
 	segments, ok := request["message"].([]interface{})
 	if !ok || len(segments) < 2 {
 		t.Fatalf("message is not a segment array: %#v", request["message"])
 	}
 	mention, _ := segments[0].(map[string]interface{})
 	data, _ := mention["data"].(map[string]interface{})
 	if mention["type"] != "at" || data["qq"] != "10001" {
 		t.Fatalf("leading mention=%#v", mention)
 	}
 }
 // 回归：循环保险曾按“总数”拦截，导致参数不同且必需的调用被误杀。
 // 现在只拦参数完全相同的重复调用。
 func TestDistinctQQOutputsAreNotTreatedAsDuplicates(t *testing.T) {
 	p := newPermissionTestPlugin(t)
 	p.auth = qqAuthContext{active: true, owner: true, userID: 2198972886}
 	// maxDuplicateSend 默认 1：同一条消息重复才会被拦，不同消息必须全部放行。
 	for i := 0; i < 5; i++ {
 		ctx := toolCallContext("output_send__qq", map[string]interface{}{
 			"payload": fmt.Sprintf("message-%d", i),
 			"type":    "text",
 			"meta":    `{"user_id":123}`,
 		})
 		if err := p.beforeToolcall(ctx); err != nil {
 			t.Fatal(err)
 		}
 		if ctx.Response != nil {
 			t.Fatalf("distinct message %d was blocked: %s", i, *ctx.Response)
 		}
 	}
 }
 func TestDistinctNecessaryToolCallsAreNotBlocked(t *testing.T) {
 	p := newPermissionTestPlugin(t)
 	p.auth = qqAuthContext{active: true, owner: true, userID: 2198972886}
 	// 旧实现 maxQQToolCalls=32 会在第 33 个不同参数的必需调用处误拦。
 	for i := 0; i < 50; i++ {
 		ctx := toolCallContext("cmd_run", map[string]interface{}{"command": fmt.Sprintf("cmd-%d", i)})
 		if err := p.beforeToolcall(ctx); err != nil {
 			t.Fatal(err)
 		}
 		if ctx.Response != nil {
 			t.Fatalf("necessary tool call %d was blocked: %s", i, *ctx.Response)
 		}
 	}
 }
 func TestZeroLimitsMeanUnlimited(t *testing.T) {
 	p := newPermissionTestPlugin(t)
 	p.maxQQOutputCalls = 0
 	p.maxDuplicateSend = 0
 	p.maxQQToolCalls = 0
 	p.auth = qqAuthContext{active: true, owner: true, userID: 2198972886}
 	for i := 0; i < 30; i++ {
 		ctx := toolCallContext("output_send__qq", map[string]interface{}{
 			"payload": "same-content",
 			"type":    "text",
 			"meta":    `{"user_id":123}`,
 		})
 		if err := p.beforeToolcall(ctx); err != nil {
 			t.Fatal(err)
 		}
 		if ctx.Response != nil {
 			t.Fatalf("0 should mean unlimited, blocked at %d: %s", i, *ctx.Response)
 		}
 	}
 }
 // 降权（本轮无法精确匹配可信 OneBot 事件 ⇒ auth={active:true}、无 peer、非 owner）时，
 // **输出仍必须放行**：发到哪个会话由 agent 自己给的 meta 决定，
 // 不该被「当前会话身份」挡住。现场：被子的中断唤醒的一轮里，父带齐 meta 也发不出去
 // （报「可信 QQ 会话身份不完整」）。
 //
 // 反之，**读取类**工具在降权时仍受当前会话限制 —— 那才是真的不能跨会话读。
 func TestDowngradedAuthStillAllowsQQOutput(t *testing.T) {
 	p := newPermissionTestPlugin(t)
 	p.auth = qqAuthContext{active: true}
 	p.privateToolAllowlist = []string{"output_send__qq", "qq_get_history"}
 	p.groupToolAllowlists = map[int64][]string{0: {"output_send__qq", "qq_get_history"}}
 	ctx := toolCallContext("output_send__qq", map[string]interface{}{
 		"payload": "带齐 meta 的主动发送",
 		"type":    "text",
 		"meta":    `{"user_id":2198972886}`,
 	})
 	if err := p.beforeToolcall(ctx); err != nil {
 		t.Fatal(err)
 	}
 	if ctx.Response != nil {
 		t.Fatalf("降权时输出被拒: %s", *ctx.Response)
 	}
 	ctx2 := toolCallContext("qq_get_history", map[string]interface{}{"group_id": 1027993713})
 	if err := p.beforeToolcall(ctx2); err != nil {
 		t.Fatal(err)
 	}
 	if ctx2.Response == nil || !strings.Contains(*ctx2.Response, "可信 QQ 会话身份不完整") {
 		t.Fatalf("读取类工具在降权时应被当前会话限制挡住: %#v", ctx2.Response)
 	}
 }
 // ---- 消息合并（debounce）----
 // collectInterrupts 用注入钩子收集中断文本（避免测试依赖真实 SDK）。
 func collectInterrupts(p *Plugin) *[]string {
 	got := []string{}
 	p.injectHook = func(s, _ string) { got = append(got, s) }
 	return &got
 }
 func TestConsecutiveMessagesFromSameSenderAreBatched(t *testing.T) {
 	p := newPermissionTestPlugin(t)
 	got := collectInterrupts(p)
 	p.batchWindow = 20 * time.Millisecond
 	p.batchMax = time.Second
 	for i := 0; i < 3; i++ {
 		p.enqueueInterrupt("private", 10001, 0, int64(100+i), "小明", "单条", false, false)
 	}
 	time.Sleep(120 * time.Millisecond)
 	if len(*got) != 1 {
 		t.Fatalf("同一发送者连发 3 条应合并成 1 次中断，实际 %d 次: %#v", len(*got), *got)
 	}
 	if !strings.Contains((*got)[0], "3 条消息") {
 		t.Fatalf("合并中断应说明一共几条，实际: %s", (*got)[0])
 	}
 	// 三个 message_id 都要带上，模型才能取全
 	for _, id := range []string{"100", "101", "102"} {
 		if !strings.Contains((*got)[0], id) {
 			t.Fatalf("合并中断漏了 message_id=%s: %s", id, (*got)[0])
 		}
 	}
 }
 func TestDifferentSendersAreNotBatchedTogether(t *testing.T) {
 	p := newPermissionTestPlugin(t)
 	got := collectInterrupts(p)
 	p.batchWindow = 20 * time.Millisecond
 	p.batchMax = time.Second
 	p.enqueueInterrupt("private", 10001, 0, 1, "小明", "a", false, false)
 	p.enqueueInterrupt("private", 10002, 0, 2, "小红", "b", false, false)
 	time.Sleep(120 * time.Millisecond)
 	if len(*got) != 2 {
 		t.Fatalf("不同发送者不该合并，应有 2 次中断，实际 %d: %#v", len(*got), *got)
 	}
 }
 func TestBatchWindowZeroFallsBackToPerMessage(t *testing.T) {
 	p := newPermissionTestPlugin(t)
 	got := collectInterrupts(p)
 	p.batchWindow = 0
 	for i := 0; i < 3; i++ {
 		p.enqueueInterrupt("private", 10001, 0, int64(i), "小明", "原文", false, false)
 	}
 	if len(*got) != 3 {
 		t.Fatalf("关闭合并时应逐条投递（3 次），实际 %d: %#v", len(*got), *got)
 	}
 }
 func TestSingleMessageKeepsOriginalText(t *testing.T) {
 	p := newPermissionTestPlugin(t)
 	got := collectInterrupts(p)
 	p.batchWindow = 20 * time.Millisecond
 	p.batchMax = time.Second
 	p.enqueueInterrupt("group", 10001, 20002, 7, "小明", "单条原文", true, false)
 	time.Sleep(120 * time.Millisecond)
 	if len(*got) != 1 || (*got)[0] != "单条原文" {
 		t.Fatalf("单条消息应沿用原文（含所有者前缀），实际 %#v", *got)
 	}
 }
 // Bot 所有者/管理员的消息给 L2，普通人的给 L1 —— 否则所有者的话会被路人
 // 的 L1 闲聊抢占/挤到队尾。
 func TestOwnerMessagesGetHigherInterruptLevel(t *testing.T) {
 	p := newPermissionTestPlugin(t)
 	got := []string{}
 	p.injectHook = func(text, level string) { got = append(got, text+"|"+level) }
 	p.batchWindow = 20 * time.Millisecond
 	p.batchMax = time.Second
 	p.enqueueInterrupt("private", 1, 0, 1, "owner", "owner-msg", true, false)
 	p.enqueueInterrupt("private", 2, 0, 2, "someone", "other-msg", false, false)
 	time.Sleep(120 * time.Millisecond)
 	joined := strings.Join(got, ",")
 	if !strings.Contains(joined, "owner-msg|L2") {
 		t.Fatalf("所有者消息应为 L2，实际 %q", joined)
 	}
 	if !strings.Contains(joined, "other-msg|L1") {
 		t.Fatalf("普通人消息应为 L1，实际 %q", joined)
 	}
 }
 // 身份必须绑在帧上：中断抢占当前轮、中断轮收尾清空插件全局身份之后，
 // 外层轮被恢复（resumeTask 复用同一帧、不重跑 onInput）时权限门不能整体失效。
 func TestAuthSurvivesInterruptPreemptionOfAnotherTurn(t *testing.T) {
 	p := newPermissionTestPlugin(t)
 	// 中断轮（Bot 所有者）跑完：afterOutput 会清掉插件全局身份。
 	inner := &sdk.StageContext{Extra: map[string]interface{}{
 		qqAuthExtraKey: qqAuthContext{active: true, owner: true, userID: 2198972886},
 	}}
 	if err := p.afterOutputAuthContext(inner); err != nil {
 		t.Fatal(err)
 	}
 	if p.auth.active {
 		t.Fatal("收尾后插件全局身份应为空（复现恢复前状态）")
 	}
 	// 外层轮（非所有者群成员）恢复后继续调工具：仍须按非所有者拦下私人资源工具。
 	frame := &sdk.StageContext{
 		Extra:     map[string]interface{}{qqAuthExtraKey: qqAuthContext{active: true, userID: 10001, groupID: 20002, isGroup: true}},
 		ToolCalls: []sdk.ToolCall{{Name: "calendar_list"}},
 	}
 	if err := p.beforeToolcall(frame); err != nil {
 		t.Fatal(err)
 	}
 	if frame.Response == nil || !strings.Contains(*frame.Response, "私人资源工具") {
 		t.Fatalf("中断恢复后权限门失效（整体放行）: %#v", frame.Response)
 	}
 }
 // 运行中到达的新消息会改写插件全局身份；正在跑的那一轮必须不受影响。
 func TestMidTurnMessageDoesNotChangeRunningTurnAuth(t *testing.T) {
 	p := newPermissionTestPlugin(t)
 	frame := &sdk.StageContext{
 		Extra:     map[string]interface{}{qqAuthExtraKey: qqAuthContext{active: true, owner: true, userID: 2198972886}},
 		ToolCalls: []sdk.ToolCall{{Name: "calendar_list"}},
 	}
 	// 路人的群消息在所有者轮运行中到达。
 	p.activateAuthContext(4242, 10001, 20002, true)
 	if p.auth.owner {
 		t.Fatal("到达事件应改写全局身份（复现场景）")
 	}
 	if err := p.beforeToolcall(frame); err != nil {
 		t.Fatal(err)
 	}
 	if frame.Response != nil {
 		t.Fatalf("在跑的所有者轮被到达消息篡改: %s", *frame.Response)
 	}
 }
 // 合并中断正文里的整批 message_id 都要消费掉，并在帧上绑定身份。
 func TestBatchInterruptConsumesAllMessageIDs(t *testing.T) {
 	p := newPermissionTestPlugin(t)
 	p.authByMessageID = map[int64]qqAuthContext{
 		100: {active: true, owner: true, userID: 2198972886},
 		101: {active: true, owner: true, userID: 2198972886},
 	}
 	ctx := &sdk.StageContext{
 		RawMessage: "来自「老板」的私聊短时间内连续发来 2 条消息(message_id=100,101, user_id=2198972886)。",
 		Extra:      map[string]interface{}{"input_source": "qq"},
 	}
 	if err := p.onInputAuthContext(ctx); err != nil {
 		t.Fatal(err)
 	}
 	if !p.auth.owner {
 		t.Fatalf("合并中断未恢复所有者身份: %+v", p.auth)
 	}
 	if len(p.authByMessageID) != 0 {
 		t.Fatalf("同批 message_id 未全部清理: %v", p.authByMessageID)
 	}
 	if auth, ok := authOnFrame(ctx); !ok || !auth.owner {
 		t.Fatalf("身份未绑定到帧上: %+v ok=%v", auth, ok)
 	}
 }
 // 非 QQ 来源（webui/timer 等）的帧上绑空身份：权限门对这些轮整体关闭。
 func TestNonQQFrameBindsInactiveAuth(t *testing.T) {
 	p := newPermissionTestPlugin(t)
 	p.auth = qqAuthContext{active: true, owner: true, userID: 2198972886}
 	ctx := &sdk.StageContext{
 		RawMessage: "webui 里的提问",
 		Extra:      map[string]interface{}{"input_source": "webui"},
 		ToolCalls:  []sdk.ToolCall{{Name: "calendar_list"}},
 	}
 	if err := p.onInputAuthContext(ctx); err != nil {
 		t.Fatal(err)
 	}
 	if err := p.beforeToolcall(ctx); err != nil {
 		t.Fatal(err)
 	}
 	if ctx.Response != nil {
 		t.Fatalf("非 QQ 轮不应被 QQ 权限门拦: %s", *ctx.Response)
 	}
 }
--- a/example/recoverydiag/README.md
+++ b/example/recoverydiag/README.md
@ -0,0 +1,53 @@
 # recoverydiag · 快速检查 / 崩溃取证
 给 guard 与 failback 用的**确定性诊断工具集**。
 设计基调（源码原话）：**返回结论而非原文，确定性检出，不消耗 LLM token。**
 崩溃后最忌讳的是把几万行日志塞进模型上下文让它"看看"，那既慢又不可靠 ——
 这里每个工具都在本地算出结论再返回。
 ## 工具
 | 工具 | 说明 |
 |---|---|
 | `recoverydiag_diag_triage` | 快速分诊：按退出码 / 信号 / 存活状态粗分类别（进程死亡 vs 配置类不可达 vs 正常） |
 | `recoverydiag_diag_db` | config.db 完整性（`PRAGMA integrity_check`）+ LLM 源解析校验（`core.llm.sources.*` 必备字段），逐项 ok/fail |
 | `recoverydiag_diag_log_scan` | 在日志目录的时间窗内统计已知错误签名（panic / OOM / 网络不可达 / provider 失败 / sql / 致命）出现次数，给出主导结论 |
 | `recoverydiag_diag_delta` | 对比 baseline（上次 good 快照/目录）与现状，列出 created / modified / deleted 清单与摘要，判定"改了什么" |
 | `recoverydiag_diag_loc` | 综合前四项结论，按**因果强度正交排序**定位根因并给出推荐恢复动作 |
 ## 用法顺序
 ```
 diag_triage  →  diag_db  →  diag_log_scan  →  diag_delta  →  diag_loc
   （各自独立，可只跑需要的）                        （要传前四项的结论）
 ```
 `diag_loc` 需要你把它余下的结论**作为参数传进去**（`triage` / `db` / `log` / `delta` 四个对象），
 它不自己去调 —— 这样它只做归因，不重复执行。
 ## 配置项
 | 键 | 默认 | 说明 |
 |---|---|---|
 | `db_check_cmd` | `auto` | `diag_db` 用的 `sqlite3` 命令。留空=auto：可用时用 sqlite3，缺失则回退读内核 Settings |
 | `recovery_kb_dir` | 空 | `diag_loc` 结论 JSON 的落盘目录。缺省 `<data_dir>/recovery_kb` |
 ## 不注册通道与钩子
 本插件**只提供工具**，不订阅输入、不挂阶段钩子 —— 它是被 guard 或 agent 主动调用的，
 不做后台干预。
 ## 测试
 ```bash
 go test -count=1 ./...
 ```
 `diag_test.go` 覆盖各诊断项的判定逻辑。
 ## 构建
 ```bash
 hmapdev build
 ```
--- a/example/rss/README.md
+++ b/example/rss/README.md
@ -1,13 +1,44 @@
-# rss
+# rss · RSS/Atom 订阅监控
-rss plugin
+订阅 RSS/Atom 源，**有新文章时主动通知** agent（不必每轮去问）。
-## Build
+## 工具
 | 工具 | 说明 |
 |---|---|
 | `rss_subscribe` | 订阅一个 RSS/Atom 源 |
 | `rss_unsubscribe` | 取消订阅 |
 | `rss_list` | 列出全部订阅 |
 | `rss_check_now` | 立即检查所有源（不等轮询周期） |
 ## 配置项
 | 键 | 默认 | 说明 |
 |---|---|---|
 | `poll_interval` | `30` | 默认轮询间隔（**分钟**） |
 订阅时可对单个源覆盖间隔。
 ## 通知机制
 - 后台按各自间隔轮询（默认 30 分钟）。
 - 发现新条目时通过 `InjectInterruptText` 注入，格式形如
  `📡 <源标题> (<URL>) — N 篇新文章:` 后跟条目。
 - 注入带 **`NoMemory: true`**，通道 `rss` 也声明为 `NoMemory` ——
  订阅推送是信号不是知识，不该进向量化挤掉别的记忆。
 ## 实现要点
 - **订阅时就记下全部已有 GUID**：`handleSubscribe` 会把抓取到的历史条目
  一次性标为 `seenGUIDs`，所以**订阅一个源不会把它的历史文章全部推送一遍**。
  只有订阅之后新出现的条目才通知。这是避免刷屏的关键。
 - **去重按「源 URL + GUID」**：不同源可能用相同 GUID，只用 GUID 会互相误判。
  GUID 缺失时回退用 `link`；两者都缺则跳过该条。
 - `seenGUIDs` 有清理逻辑，不会无限增长。
 - 解析用 [gofeed](https://github.com/mmcdole/gofeed)（`v1.4.0`）。
 ## 构建
 ```bash
-plugindev build
+hmapdev build
 ```
 ## Install
 Upload the .hmap file through the Plugin Manager API.
--- a/example/rss/plugin.go
+++ b/example/rss/plugin.go
@ -104,6 +104,9 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
 	s.SetAutoRestart(true)
 	p.sdk = s
 	p.client = &http.Client{Timeout: 30 * time.Second}
 	// 入站通道：本插件用 "rss" 通道注入输入（见 Inject* 调用），
 	// 输入侧必须显式登记 —— 否则"把该 inputch 划给驻留子"会报 `inputch 未注册`。
 	_ = s.RegisterInputChannel("rss", sdk.ChannelDef{NoMemory: true})
 	p.fp = gofeed.NewParser()
 	p.stopCh = make(chan struct{})
 	p.seenGUIDs = make(map[string]bool)
@ -158,7 +161,7 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
 	s.RegisterTool(tp+"list", sdk.ToolDef{
 		Name: tp + "list", Description: "List all subscribed feeds",
 		Parameters: map[string]interface{}{
-			"type": "object",
+			"type":       "object",
 			"properties": map[string]interface{}{},
 		},
 	}, p.handleList)
@ -167,7 +170,7 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
 		Name: tp + "check_now", Description: "Manually check all feeds for new articles now",
 		NoMemory: true,
 		Parameters: map[string]interface{}{
-			"type": "object",
+			"type":       "object",
 			"properties": map[string]interface{}{},
 		},
 	}, p.handleCheckNow)
@ -300,7 +303,10 @@ func (p *Plugin) checkFeed(sub FeedSub) {
 		lines = append(lines, line)
 	}
-	p.sdk.InjectInterruptText("rss", "rss", strings.Join(lines, "\n"))
+	// 中断注入是「系统通知」，NoMemory 写明意图：这类提醒不参与记忆计算，
 	// 原文仍进上下文（模型当轮看得到）。
 	p.sdk.InjectInterruptTextOpts("rss", "rss", strings.Join(lines, "\n"),
 		sdk.InjectOptions{NoMemory: true})
 	p.saveData()
 }
@ -442,7 +448,7 @@ func (p *Plugin) loadData() {
 		return
 	}
 	var data struct {
-		Feeds     []FeedSub      `json:"feeds"`
+		Feeds     []FeedSub       `json:"feeds"`
 		SeenGUIDs map[string]bool `json:"seen"`
 	}
 	if json.Unmarshal(b, &data) != nil {
@ -460,7 +466,7 @@ func (p *Plugin) saveData() {
 	p.mu.RLock()
 	defer p.mu.RUnlock()
 	data := struct {
-		Feeds     []FeedSub      `json:"feeds"`
+		Feeds     []FeedSub       `json:"feeds"`
 		SeenGUIDs map[string]bool `json:"seen"`
 	}{
 		Feeds:     p.feeds,
@ -485,8 +491,6 @@ func (p *Plugin) cleanupData() {
 	}
 }
 // atomicWriteJSON 原子写 JSON：先写临时文件再 rename，避免进程崩溃截断数据文件。
 func atomicWriteJSON(path string, data []byte) error {
 	tmp := path + ".tmp"
--- a/example/sanitizer/README.md
+++ b/example/sanitizer/README.md
@ -0,0 +1,48 @@
 # sanitizer · 文本清洗
 **不注册任何工具**，只挂三个阶段钩子，在 Agent 全链路上洗掉两类污染：
 1. **坏字节**：坏 UTF-8、`U+FFFD`（替换符）、ANSI 转义序列
 2. **思维泄漏**：LLM 输出里残留的工具调用标记
 ## 为什么需要它
 坏字节会**被 LLM 复读**。一次工具返回乱码（比如源码里带 ANSI 颜色码、或二进制片段被当文本读出来），
 这些字节会进上下文，之后模型每次生成都可能把它抄一遍 —— 越滚越脏。
 在每个入口洗掉，比事后清理便宜得多。
 思维泄漏则是另一种：模型有时把 `<tool_call>...</tool_call>` 这类内部标记直接写进正文，
 用户就看到一堆不该出现的 XML。
 ## 挂载的三个阶段
 | 阶段 | 处理对象 | 作用 |
 |---|---|---|
 | `on_input` | `ctx.RawMessage` | 洗用户输入，脏字节不进后续链路 |
 | `after_toolcall` | `ctx.ToolResults` | 洗工具结果，**坏字节不进 LLM 上下文** |
 | `post_action` | `ctx.LLMText` | 洗模型输出：先清思维泄漏，再清乱码 |
 每次有改动都打一行日志（`cleaned N bytes`），便于确认它真的在工作而不是静默失败。
 ## 识别哪些泄漏形态
 按正则匹配多种标记写法，覆盖不同模型家族的习惯：
 - `<tool_call>…</tool_call>`、`<invoke>…</invoke>`、`<tool>…</tool>`
 - `<function>…</function>`
 - 上述标记包在 ```xml / ```json 代码块里的形态
 - 中文括号变体：`【tool_call】…【/tool_call】`
 ## 实现要点
 - 依赖 **ABI v2 的 stage 写回能力**：插件对 `StageContext` 的修改会同步回内核。
  在 v1 上改了不生效。
 - 读写 `StageContext` 时按约定加 `ctx.Lock()`。
 ## 构建
 ```bash
 go build -buildmode=plugin -o sanitizer.so .
 ```
 或经 `hmapdev build` 打包为 `.hmap`。
--- a/example/vanblog/README.md
+++ b/example/vanblog/README.md
@ -0,0 +1,77 @@
 # vanblog · VanBlog 博客管理
 用管理 API 操作 [VanBlog](https://vanblog.mereith.com/) 开源博客系统：
 文章增删改查、分类标签、草稿发布、备份导出等。
 ## 配置项
 | 键 | 默认 | 说明 |
 |---|---|---|
 | `url` | `https://blog.jianfgit.xyz` | VanBlog 站点基地址 |
 | `token` | 空 | 管理员 API Token（长期令牌，从后台「Token 管理」创建） |
 | `reset_token` | 空 | 用于 `auth/restore` 重置管理员密码的**特殊** Token |
 `token` 与 `reset_token` 都是 `password` 类型（界面遮蔽）。
 ## 工具（28 个）
 ### 文章
 | 工具 | 说明 |
 |---|---|
 | `vanblog_list_articles` | 列文章，支持分页与搜索 |
 | `vanblog_get_article` | 取单篇完整内容 |
 | `vanblog_create_article` | 新建（`title` 与 `category` 必填） |
 | `vanblog_update_article` | 更新（**只传要改的字段**） |
 | `vanblog_delete_article` | 删除（**软删除**） |
 | `vanblog_search_articles` | 按链接搜索文章 |
 ### 草稿
 `vanblog_manage_drafts`：`list` / `get` / `create` / `update` / `delete` / **`publish`**
 ### 内容组织
 | 工具 | 命令 |
 |---|---|
 | `vanblog_manage_categories` | `list` / `get` / `create` / `update` / `delete` |
 | `vanblog_manage_tags` | `list` / `get` / `rename` / `delete` |
 ### 站点与运维
 | 工具 | 说明 |
 |---|---|
 | `vanblog_manage_site` / `_settings` / `_menu` / `_social` / `_links` | 站点配置类 |
 | `vanblog_manage_about` / `_pages` | 关于页与自定义页面 |
 | `vanblog_manage_images` | 图床管理 |
 | `vanblog_manage_rewards` | 赞赏配置 |
 | `vanblog_manage_backup` | 备份 |
 | `vanblog_manage_caddy` | Caddy 配置 |
 | `vanblog_manage_isr` | ISR 增量静态渲染 |
 | `vanblog_manage_pipelines` | 流水线 |
 | `vanblog_manage_collaborators` | 协作者 |
 | `vanblog_manage_tokens` | Token 管理 |
 | `vanblog_get_analysis` / `_logs` / `_meta` | 统计、日志、元信息 |
 | `vanblog_auth` | 认证相关（含 `restore` 重置密码） |
 > 工具名前缀取自插件名（`tp`），上面按默认 `vanblog_` 列出。
 ## 实现要点
 - 走的是 VanBlog 的管理 API（`/api/admin/...`），所以必须配 **admin token**，
  不是前台只读接口。
 - `update_article` 是**部分更新**：只传想改的字段，没传的保持不变。
  （不要为了改标题而把正文一起传一遍。）
 - `delete_article` 是**软删除**，内容仍在，可在后台恢复。
 - 早期版本把 token 放在内核配置（`plugin.vanblog.token`）里，
  现在会**自动迁移**到插件配置，迁移后清空内核侧取值。
 ## 前置
 需要一个可访问的 VanBlog 实例，并在后台创建一个长期 Token。
 ## 构建
 ```bash
 hmapdev build
 ```
--- a/example/vikunja/README.md
+++ b/example/vikunja/README.md
@ -0,0 +1,81 @@
 # Vikunja 插件（HomeAgent）
 把 [Vikunja](https://vikunja.io) 待办/任务管理接入 HomeAgent：用自然语言查任务、建任务、改期、完成、看板拖动、指派、评论、时间跟踪、导入数据等。
 ## 配置项（全部可在插件配置界面修改）
 | 键 | 类型 | 默认 | 说明 |
 |---|---|---|---|
 | `url` | string | `https://vikunja.jianfgit.xyz` | 站点根地址，**不带** `/api` |
 | `token` | password(secret) | 空 | **必填**。Vikunja → 设置 → API Tokens 生成（`tk_` 开头）。令牌的权限范围决定本插件能力上限：勾全范围即为完整能力 |
 | `api_version` | select | `v2` | `v2`（推荐，标准 REST，含时间跟踪等新能力）或 `v1`（用于 v2 暂未提供的端点） |
 | `default_project_id` | string | 空 | 新建任务未指定项目时落到这里；留空则必须显式指定 |
 | `max_items` | int | `25` | 列表类工具的默认条数，控制上下文体积 |
 | `compact_output` | bool | `true` | 任务/项目/标签列表只返回关键字段；关闭则返回 Vikunja 完整对象 |
 | `timeout_seconds` | int | `20` | 单次 HTTP 超时 |
 | `verify_tls` | bool | `true` | 自签证书站点可关闭（不建议） |
 配置在**每次工具调用前重新读取**，因此换了 token 不必重启插件。
 ## 工具
 | 工具 | 能力 |
 |---|---|
 | `vikunja_status` | 连接/配置自检：地址、token 对应的用户、API 版本、服务器能力、CalDAV 地址 |
 | `vikunja_tasks` | 列任务：按项目、完成状态、截止（today/this_week/overdue/no_due）、关键词、原生 filter 表达式 |
 | `vikunja_task_get` / `task_create` / `task_update` / `task_done` / `task_delete` | 任务增删改查（`task_update` 只传要改的字段） |
 | `vikunja_task_bulk` | 批量改完成状态/项目/优先级/截止/标签 |
 | `vikunja_task_assignees` / `task_labels` / `task_comments` / `task_relations` / `task_attachments` | 指派、标签、评论、关联（子任务/依赖/相关）、附件（支持上传本地文件） |
 | `vikunja_projects` / `project_views` | 项目增删改查、归档；视图与看板桶（把任务移入桶＝看板拖动） |
 | `vikunja_labels` / `filters` | 标签、保存的筛选器（Saved Filter） |
 | `vikunja_teams` / `sharing` | 团队与成员；项目分享（用户/团队授权、链接分享含密码） |
 | `vikunja_notifications` / `subscriptions` / `webhooks` | 通知、订阅、Webhook 管理 |
 | `vikunja_time_entries` | 时间跟踪（**仅 v2**）：补录/修改/删除、开始与停止计时器 |
 | `vikunja_migrate` | 从 TickTick/WeKan/CSV/Planka/Vikunja 文件（v2）与 Todoist/Trello/微软待办（v1）导入 |
 | `vikunja_user` / `vikunja_admin` | 当前账号（设置、登录会话、API Token）与实例管理（用户增删/提权/停用/改密、项目归属转移，需实例管理员） |
 | `vikunja_reactions` | 任务/评论的表情回应 |
 | `vikunja_api` | **通用直通**：调任意端点，未封装的能力走这里（可强制指定 v1/v2），保证能力无死角 |
 ## v1 / v2 差异（已按实例自带规范逐条核对）
 插件默认 v2，并自动处理下列差异：
 | 操作 | v1 | v2 |
 |---|---|---|
 | 建任务 | `PUT /projects/{id}/tasks` | `POST /projects/{id}/tasks` |
 | 改任务 | `POST /tasks/{id}`（必须整对象 → 插件自动取回-合并-提交） | `PATCH /tasks/{id}`（merge-patch，只发变更字段；被拒则回落取回-合并-PUT） |
 | 搜索参数 | `?s=` | `?q=` |
 | 加标签 | `PUT`（Label 对象） | `POST`（`{"label_id":N}`） |
 | 批量改 | `POST /tasks/bulk` | `PUT /tasks/bulk` |
 | 时间跟踪 | 不支持 | `/time-entries`（`end_time` 为 null 即计时中；停止用 `/time-entries/timer/stop`） |
 | 导入 | Todoist / Trello / 微软待办 | TickTick / WeKan / CSV / Planka / Vikunja 文件 |
 > 官方路线：v1 仍支持但新端点只进 v2，3.0 弃用、4.0 移除。除“导入”外建议一律用 v2。
 ## 开发与构建
 ```bash
 cd third_party/homeagent-sdk/example/vikunja
 go test -count=1 -race ./...   # 16 项测试（httptest 打桩，不需要真 token）
 hmapdev build                  # 产出 dist/vikunja_bundle.hmap
 ```
 `go.mod` 里的 `replace` 把 SDK 指向仓库内的 `third_party/homeagent-sdk`，因此无需联网拉私有模块。
 ### 部署到运行实例
 `.hmap` 包内是 `plugin.json` + `plugin.bin.<os>.<arch>`，安装时按运行平台重命名入口文件：
 ```bash
 unzip -o dist/vikunja_bundle.hmap -d /home/newqqagent/plugins/vikunja
 cd /home/newqqagent/plugins/vikunja && mv plugin.bin.linux.amd64 plugin.bin
 # 然后重载插件（或重启 homeagent.service）
 ```
 ## 已知边界
 - **附件下载**未单独封装：`task_attachments` 支持列出/上传/删除，下载请用 `vikunja_api` 访问附件 URL。
 - **链接分享的字段**（`right`/`password`）按 Vikunja 版本语义透传；如遇 4xx，可直接用 `raw` 参数传完整 JSON。
 - **批量改标签**的 `fields` 结构以 `BulkTask` 为准，未在真实实例上验证过（缺少可用 token），如有偏差请用 `vikunja_api` 直通。
 - CalDAV 是客户端协议，插件只提供地址（`vikunja_status` 里的 `caldav_url`），不做 CalDAV 同步。
--- a/example/vikunja/go.mod
+++ b/example/vikunja/go.mod
@ -0,0 +1,15 @@
 module vikunja-plugin
 go 1.25.0
 require gitcode.com/JianFeeeee/homeagent-sdk v0.0.0
 // 与同目录其它示例一致：SDK 指向仓库内的 vendored 副本
 replace gitcode.com/JianFeeeee/homeagent-sdk => ../../
--- a/example/vikunja/plg.json
+++ b/example/vikunja/plg.json
@ -0,0 +1,17 @@
 {
  "name": "vikunja",
  "name_zh": "Vikunja 待办",
  "name_en": "Vikunja",
  "version": "1.0.1",
  "description": "Vikunja 待办/任务管理：任务增删改查、项目与看板桶、标签、指派、评论、关联、附件、保存筛选器、团队与分享、通知、订阅、Webhook、时间跟踪、数据导入、实例管理；并附通用 API 直通工具兜底",
  "author": "HomeAgent",
  "entry": "plugin.bin",
  "tags": [
    "vikunja",
    "todo",
    "task",
    "gtd",
    "productivity"
  ],
  "targets": "linux/amd64"
 }
--- a/example/vikunja/plugin.go
+++ b/example/vikunja/plugin.go
--- a/example/vikunja/plugin_test.go
+++ b/example/vikunja/plugin_test.go
@ -0,0 +1,523 @@
 package main
 import (
 	"encoding/json"
 	"io"
 	"net/http"
 	"net/http/httptest"
 	"strings"
 	"testing"
 	"time"
 )
 // newTestPlugin 构造一个不依赖 sdk 的插件实例，指向 httptest 服务。
 // ensure() 在 sdk==nil 时会保留已设置的字段，因此可以这样直接测处理器。
 func newTestPlugin(t *testing.T, h http.HandlerFunc) (*Plugin, *httptest.Server) {
 	t.Helper()
 	srv := httptest.NewServer(h)
 	t.Cleanup(srv.Close)
 	p := &Plugin{
 		name:     "vikunja",
 		baseURL:  srv.URL,
 		token:    "tk_test",
 		apiVer:   "v2",
 		maxItems: 5,
 		compact:  true,
 		http:     srv.Client(),
 	}
 	return p, srv
 }
 func mustJSON(t *testing.T, v interface{}) []byte {
 	t.Helper()
 	b, err := json.Marshal(v)
 	if err != nil {
 		t.Fatalf("marshal: %v", err)
 	}
 	return b
 }
 // 1) 列表：v2 用 q= 搜索，且 filter 会带上默认 done 条件
 func TestTasksListV2(t *testing.T) {
 	var gotQuery string
 	p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
 		gotQuery = r.URL.RawQuery
 		if r.Header.Get("Authorization") != "Bearer tk_test" {
 			t.Errorf("缺少 Bearer 头: %q", r.Header.Get("Authorization"))
 		}
 		w.Header().Set("Content-Type", "application/json")
 		_, _ = w.Write([]byte(`[{"id":1,"title":"写周报","done":false,"project_id":3,"due_date":"2026-09-13T10:00:00Z","labels":[{"title":"工作"}],"assignees":[{"username":"jianf"}]}]`))
 	})
 	res, err := p.handleTasksList(map[string]interface{}{"search": "周报", "limit": float64(5)})
 	if err != nil {
 		t.Fatalf("err: %v", err)
 	}
 	if !strings.Contains(gotQuery, "q=%E5%91%A8%E6%8A%A5") {
 		t.Errorf("v2 应使用 q= 搜索，实际 query=%s", gotQuery)
 	}
 	if strings.Contains(gotQuery, "s=") {
 		t.Errorf("v2 不应使用 s=，实际 query=%s", gotQuery)
 	}
 	if !strings.Contains(gotQuery, "per_page=5") {
 		t.Errorf("per_page 未生效: %s", gotQuery)
 	}
 	if !strings.Contains(gotQuery, "filter=done+%3D+false") && !strings.Contains(gotQuery, "filter=done%20%3D%20false") {
 		t.Errorf("默认应过滤未完成，实际 filter 片段: %s", gotQuery)
 	}
 	m, ok := res.(map[string]interface{})
 	if !ok {
 		t.Fatalf("结果应为 map，实际 %T", res)
 	}
 	if m["count"].(int) != 1 {
 		t.Errorf("count 应为 1，实际 %v", m["count"])
 	}
 	tasks := m["tasks"].([]interface{})
 	tk := tasks[0].(map[string]interface{})
 	if _, ok := tk["labels"].([]string); !ok {
 		t.Errorf("标签应被投影成名称数组，实际 %T", tk["labels"])
 	}
 	if _, ok := tk["description"]; ok {
 		t.Errorf("精简输出不应出现 description")
 	}
 }
 // 2) 列表：v1 用 s= 搜索
 func TestTasksListV1SearchParam(t *testing.T) {
 	var gotQuery string
 	p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
 		gotQuery = r.URL.RawQuery
 		_, _ = w.Write([]byte(`[]`))
 	})
 	p.apiVer = "v1"
 	if _, err := p.handleTasksList(map[string]interface{}{"search": "abc"}); err != nil {
 		t.Fatalf("err: %v", err)
 	}
 	if !strings.Contains(gotQuery, "s=abc") {
 		t.Errorf("v1 应使用 s= 搜索，实际 %s", gotQuery)
 	}
 	if strings.Contains(gotQuery, "q=") {
 		t.Errorf("v1 不应出现 q=，实际 %s", gotQuery)
 	}
 }
 // 3) 建任务：v1=PUT、v2=POST（同路径，方法不同）
 func TestTaskCreateMethodByVersion(t *testing.T) {
 	for _, tc := range []struct {
 		ver    string
 		method string
 	}{
 		{"v1", http.MethodPut},
 		{"v2", http.MethodPost},
 	} {
 		var gotMethod, gotPath string
 		p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
 			gotMethod, gotPath = r.Method, r.URL.Path
 			_, _ = w.Write([]byte(`{"id":42,"title":"买菜"}`))
 		})
 		p.apiVer = tc.ver
 		if _, err := p.handleTaskCreate(map[string]interface{}{"project_id": "3", "title": "买菜"}); err != nil {
 			t.Fatalf("[%s] err: %v", tc.ver, err)
 		}
 		if gotMethod != tc.method {
 			t.Errorf("[%s] 期望 %s，实际 %s", tc.ver, tc.method, gotMethod)
 		}
 		if gotPath != "/api/"+tc.ver+"/projects/3/tasks" {
 			t.Errorf("[%s] 路径错误: %s", tc.ver, gotPath)
 		}
 	}
 }
 // 4) 改任务（v2）：走 merge-patch，只发变更字段
 func TestTaskUpdateV2MergePatch(t *testing.T) {
 	var method, ctype string
 	var body map[string]interface{}
 	p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
 		method = r.Method
 		ctype = r.Header.Get("Content-Type")
 		raw, _ := io.ReadAll(r.Body)
 		_ = json.Unmarshal(raw, &body)
 		_, _ = w.Write([]byte(`{"id":7,"done":true}`))
 	})
 	if _, err := p.handleTaskUpdate(map[string]interface{}{"id": "7", "done": true}); err != nil {
 		t.Fatalf("err: %v", err)
 	}
 	if method != http.MethodPatch {
 		t.Errorf("v2 应用 PATCH，实际 %s", method)
 	}
 	if !strings.Contains(ctype, "merge-patch") {
 		t.Errorf("应使用 merge-patch 内容类型，实际 %s", ctype)
 	}
 	if len(body) != 1 || body["done"] != true {
 		t.Errorf("只应发送变更字段，实际 %v", body)
 	}
 }
 // 5) 改任务（v2）回退：merge-patch 被拒 → 取回-合并-PUT
 func TestTaskUpdateV2FallbackToMergePut(t *testing.T) {
 	var calls []string
 	var putBody map[string]interface{}
 	p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
 		calls = append(calls, r.Method+" "+r.URL.Path)
 		switch {
 		case r.Method == http.MethodPatch:
 			w.WriteHeader(http.StatusUnsupportedMediaType)
 			_, _ = w.Write([]byte(`{"code":9,"message":"unsupported media type"}`))
 		case r.Method == http.MethodGet:
 			_, _ = w.Write([]byte(`{"id":7,"title":"旧标题","done":false,"priority":1}`))
 		case r.Method == http.MethodPut:
 			raw, _ := io.ReadAll(r.Body)
 			_ = json.Unmarshal(raw, &putBody)
 			_, _ = w.Write([]byte(`{"id":7,"title":"新标题","done":false,"priority":1}`))
 		default:
 			t.Errorf("意外请求: %s %s", r.Method, r.URL.Path)
 		}
 	})
 	if _, err := p.handleTaskUpdate(map[string]interface{}{"id": "7", "title": "新标题"}); err != nil {
 		t.Fatalf("err: %v", err)
 	}
 	want := []string{"PATCH /api/v2/tasks/7", "GET /api/v2/tasks/7", "PUT /api/v2/tasks/7"}
 	if len(calls) != len(want) {
 		t.Fatalf("调用序列不符: %v", calls)
 	}
 	for i := range want {
 		if calls[i] != want[i] {
 			t.Errorf("第 %d 步期望 %s，实际 %s", i+1, want[i], calls[i])
 		}
 	}
 	if putBody["title"] != "新标题" {
 		t.Errorf("合并后的 body 应含新标题，实际 %v", putBody)
 	}
 	if putBody["priority"] != float64(1) {
 		t.Errorf("合并必须保留原有字段（priority），实际 %v", putBody)
 	}
 }
 // 6) 改任务（v1）：没有 merge-patch，必须取回-合并-POST
 func TestTaskUpdateV1FetchMergePost(t *testing.T) {
 	var calls []string
 	p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
 		calls = append(calls, r.Method+" "+r.URL.Path)
 		if r.Method == http.MethodGet {
 			_, _ = w.Write([]byte(`{"id":9,"title":"旧","priority":2}`))
 			return
 		}
 		_, _ = w.Write([]byte(`{"id":9,"title":"新","priority":2}`))
 	})
 	p.apiVer = "v1"
 	if _, err := p.handleTaskUpdate(map[string]interface{}{"id": "9", "title": "新"}); err != nil {
 		t.Fatalf("err: %v", err)
 	}
 	want := []string{"GET /api/v1/tasks/9", "POST /api/v1/tasks/9"}
 	if len(calls) != 2 || calls[0] != want[0] || calls[1] != want[1] {
 		t.Fatalf("v1 应为 GET→POST，实际 %v", calls)
 	}
 }
 // 7) 错误映射：401 提示检查 token
 func TestErrorHint401(t *testing.T) {
 	p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
 		w.WriteHeader(http.StatusUnauthorized)
 		_, _ = w.Write([]byte(`{"code":11,"message":"invalid token"}`))
 	})
 	_, err := p.handleTasksList(map[string]interface{}{})
 	if err == nil {
 		t.Fatal("应返回错误")
 	}
 	msg := err.Error()
 	if !strings.Contains(msg, "401") || !strings.Contains(msg, "code=11") {
 		t.Errorf("错误信息应含状态码与 Vikunja code，实际 %s", msg)
 	}
 	if !strings.Contains(msg, "token") {
 		t.Errorf("401 应给出 token 提示，实际 %s", msg)
 	}
 }
 // 8) 未配置 token 时应给出可操作提示，而不是发出无凭据请求
 func TestMissingToken(t *testing.T) {
 	p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
 		t.Error("未配置 token 时不应发请求")
 	})
 	p.token = ""
 	_, err := p.handleTasksList(map[string]interface{}{})
 	if err == nil || !strings.Contains(err.Error(), "vikunja.token") {
 		t.Fatalf("应提示配置项名，实际 %v", err)
 	}
 }
 // 9) 导入：Todoist 必须走 v1（即使插件默认是 v2）
 func TestMigrateUsesV1ForTodoist(t *testing.T) {
 	var path string
 	p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
 		path = r.URL.Path
 		_, _ = w.Write([]byte(`{"ok":true}`))
 	})
 	if _, err := p.handleMigrate(map[string]interface{}{"action": "start", "source": "todoist", "code": "abc"}); err != nil {
 		t.Fatalf("err: %v", err)
 	}
 	if path != "/api/v1/migration/todoist/migrate" {
 		t.Errorf("Todoist 导入必须走 v1，实际 %s", path)
 	}
 }
 // 10) 导入：WeKan 走 v2
 func TestMigrateUsesV2ForWekan(t *testing.T) {
 	var path, method string
 	p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
 		path, method = r.URL.Path, r.Method
 		_, _ = w.Write([]byte(`{"ok":true}`))
 	})
 	if _, err := p.handleMigrate(map[string]interface{}{"action": "start", "source": "wekan"}); err != nil {
 		t.Fatalf("err: %v", err)
 	}
 	if path != "/api/v2/migration/wekan/migrate" || method != http.MethodPost {
 		t.Errorf("WeKan 应走 v2 POST，实际 %s %s", method, path)
 	}
 }
 // 11) 时间跟踪：秒数换算成 end_time；计时开始则不带 end_time
 func TestTimeEntrySecondsBecomesEndTime(t *testing.T) {
 	var body map[string]interface{}
 	p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
 		raw, _ := io.ReadAll(r.Body)
 		_ = json.Unmarshal(raw, &body)
 		_, _ = w.Write([]byte(`{"id":1}`))
 	})
 	start := "2026-09-12T10:00:00+08:00"
 	if _, err := p.handleTimeEntries(map[string]interface{}{
 		"action": "create", "task_id": "5", "seconds": float64(600),
 		"start_time": start,
 	}); err != nil {
 		t.Fatalf("err: %v", err)
 	}
 	// 判据不写死字符串：按时区无关的方式比较两个时间点
 	sStart, err := time.Parse(time.RFC3339, start)
 	if err != nil {
 		t.Fatalf("case 自身时间写错: %v", err)
 	}
 	gotEnd, ok := body["end_time"].(string)
 	if !ok {
 		t.Fatalf("应有 end_time，实际 %v", body["end_time"])
 	}
 	tEnd, err := time.Parse(time.RFC3339, gotEnd)
 	if err != nil {
 		t.Fatalf("end_time 不是 RFC3339: %q", gotEnd)
 	}
 	if diff := tEnd.Sub(sStart); diff != 10*time.Minute {
 		t.Errorf("end_time 应由 start_time+600s 推出，实际差值 %v", diff)
 	}
 	if _, ok := body["seconds"]; ok {
 		t.Errorf("TimeEntry 没有 seconds 字段，不应发送：%v", body)
 	}
 	body = nil
 	if _, err := p.handleTimeEntries(map[string]interface{}{"action": "timer_start", "task_id": "5"}); err != nil {
 		t.Fatalf("err: %v", err)
 	}
 	v, present := body["end_time"]
 	if !present || v != nil {
 		t.Errorf("计时开始应显式 end_time=null（live timer），实际 %v", body)
 	}
 }
 // 12) 时间跟踪在 v1 下应给出明确不可用提示
 func TestTimeEntryUnavailableOnV1(t *testing.T) {
 	p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {})
 	p.apiVer = "v1"
 	_, err := p.handleTimeEntries(map[string]interface{}{"action": "list"})
 	if err == nil || !strings.Contains(err.Error(), "v2") {
 		t.Fatalf("v1 下应提示改用 v2，实际 %v", err)
 	}
 }
 // 13) 标签：v1 收 Label 对象、v2 收 label_id
 func TestLabelBodyByVersion(t *testing.T) {
 	var body map[string]interface{}
 	p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
 		raw, _ := io.ReadAll(r.Body)
 		_ = json.Unmarshal(raw, &body)
 		_, _ = w.Write([]byte(`{}`))
 	})
 	if _, err := p.handleTaskLabels(map[string]interface{}{"action": "add", "id": "1", "label_id": "5"}); err != nil {
 		t.Fatalf("err: %v", err)
 	}
 	if body["label_id"] != float64(5) {
 		t.Errorf("v2 应发送 label_id，实际 %v", body)
 	}
 	body = nil
 	p.apiVer = "v1"
 	if _, err := p.handleTaskLabels(map[string]interface{}{"action": "add", "id": "1", "label_id": "5"}); err != nil {
 		t.Fatalf("err: %v", err)
 	}
 	if body["id"] != float64(5) {
 		t.Errorf("v1 应发送 Label 对象(id)，实际 %v", body)
 	}
 }
 // 14) 时间字符串容忍：today / +3d / ISO
 func TestNormalizeTime(t *testing.T) {
 	for _, in := range []string{"today", "tomorrow", "+3d", "2026-09-12 18:00", "2026-09-12T18:00:00+08:00"} {
 		got := normalizeTime(in)
 		s, ok := got.(string)
 		if !ok {
 			t.Fatalf("%s: 期望字符串，实际 %T", in, got)
 		}
 		if _, err := time.Parse(time.RFC3339, s); err != nil {
 			t.Errorf("%s → %s 不是 RFC3339: %v", in, s, err)
 		}
 	}
 }
 // 15) 通用直通：可指定 api_version，method 大小写不敏感
 func TestRawAPI(t *testing.T) {
 	var method, path string
 	p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
 		method, path = r.Method, r.URL.Path
 		_, _ = w.Write([]byte(`[]`))
 	})
 	if _, err := p.handleRawAPI(map[string]interface{}{"method": "get", "path": "projects", "api_version": "v1"}); err != nil {
 		t.Fatalf("err: %v", err)
 	}
 	if method != http.MethodGet || path != "/api/v1/projects" {
 		t.Errorf("直通参数未生效: %s %s", method, path)
 	}
 }
 // 16) 精简输出可关闭（关闭时返回原样）
 func TestCompactToggle(t *testing.T) {
 	p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
 		_, _ = w.Write([]byte(`[{"id":1,"title":"t","description":"很长的描述","done":false}]`))
 	})
 	p.compact = false
 	res, err := p.handleTasksList(map[string]interface{}{})
 	if err != nil {
 		t.Fatalf("err: %v", err)
 	}
 	arr, ok := res.([]interface{})
 	if !ok {
 		t.Fatalf("关闭精简后应原样返回数组，实际 %T", res)
 	}
 	if _, ok := arr[0].(map[string]interface{})["description"]; !ok {
 		t.Errorf("关闭精简后应保留 description")
 	}
 }
 // ── 回归：JSON body 里的 ID 必须是数字（线上实测的 422 缺口）────────────
 //
 // vikunja v2.6.0 实测（2026-09-12）：
 //   {"project_id":"1"}   → 422 expected integer at body.project_id
 //   {"user_id":"1"}      → 422 expected integer at body.user_id
 //   {"username":"jianf"} → 422 unexpected property at body.username
 // 旧实现把 argID() 的字符串直接塞进 body，assignee 还额外带 username，
 // 于是「建任务」「指派」在 v2 下必定失败 —— 只有真调用才暴露，单测没盖到。
 func TestTaskCreateSendsNumericProjectID(t *testing.T) {
 	var body map[string]interface{}
 	var raw []byte
 	p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
 		raw, _ = io.ReadAll(r.Body)
 		_ = json.Unmarshal(raw, &body)
 		_, _ = w.Write([]byte(`{"id":42,"title":"买菜"}`))
 	})
 	// project_id 传 float64 —— 这正是 SDK 从 JSON 解出来的真实类型
 	if _, err := p.handleTaskCreate(map[string]interface{}{"project_id": float64(3), "title": "买菜"}); err != nil {
 		t.Fatalf("err: %v", err)
 	}
 	if _, ok := body["project_id"].(float64); !ok {
 		t.Errorf("project_id 必须是 JSON 数字，实际 %T=%v", body["project_id"], body["project_id"])
 	}
 	if strings.Contains(string(raw), `"project_id":"`) {
 		t.Errorf("出现字符串型 project_id（v2 会 422 expected integer）: %s", raw)
 	}
 }
 func TestAssigneeAddResolvesUsernameToNumericUserID(t *testing.T) {
 	var body map[string]interface{}
 	var raw []byte
 	var calls []string
 	p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
 		calls = append(calls, r.Method+" "+r.URL.Path)
 		switch r.URL.Path {
 		case "/api/v2/users":
 			if r.URL.Query().Get("q") != "alice" {
 				t.Errorf("v2 用户搜索应用 q=，实际 query=%q", r.URL.RawQuery)
 			}
 			_, _ = w.Write([]byte(`[{"id":7,"username":"alice"},{"id":9,"username":"alice2"}]`))
 		case "/api/v2/tasks/1/assignees":
 			raw, _ = io.ReadAll(r.Body)
 			_ = json.Unmarshal(raw, &body)
 			w.WriteHeader(http.StatusCreated)
 			_, _ = w.Write([]byte(`{"user_id":7}`))
 		default:
 			t.Errorf("意外请求: %s %s", r.Method, r.URL.Path)
 		}
 	})
 	if _, err := p.handleTaskAssignees(map[string]interface{}{"id": "1", "action": "add", "user": "alice"}); err != nil {
 		t.Fatalf("err: %v", err)
 	}
 	if len(calls) != 2 {
 		t.Fatalf("应先查用户再指派，实际调用: %v", calls)
 	}
 	if n, ok := body["user_id"].(float64); !ok || int(n) != 7 {
 		t.Errorf("user_id 必须是数字 7，实际 %T=%v", body["user_id"], body["user_id"])
 	}
 	if _, ok := body["username"]; ok {
 		t.Errorf("v2 不接受 username 字段（422 unexpected property）: %s", raw)
 	}
 }
 func TestAssigneeAddNumericUserSkipsLookup(t *testing.T) {
 	var calls []string
 	var body map[string]interface{}
 	p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
 		calls = append(calls, r.Method+" "+r.URL.Path)
 		if r.URL.Path == "/api/v2/users" {
 			t.Errorf("传数字 ID 时不该再查用户表")
 		}
 		raw, _ := io.ReadAll(r.Body)
 		_ = json.Unmarshal(raw, &body)
 		w.WriteHeader(http.StatusCreated)
 		_, _ = w.Write([]byte(`{"user_id":7}`))
 	})
 	if _, err := p.handleTaskAssignees(map[string]interface{}{"id": "1", "action": "add", "user": "7"}); err != nil {
 		t.Fatalf("err: %v", err)
 	}
 	if len(calls) != 1 {
 		t.Errorf("应只有一次请求，实际: %v", calls)
 	}
 	if n, ok := body["user_id"].(float64); !ok || int(n) != 7 {
 		t.Errorf("user_id 应为数字 7，实际 %T=%v", body["user_id"], body["user_id"])
 	}
 }
 func TestAssigneeRemoveUsesResolvedNumericPath(t *testing.T) {
 	var gotPath string
 	p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
 		switch r.URL.Path {
 		case "/api/v2/users":
 			_, _ = w.Write([]byte(`[{"id":7,"username":"alice"}]`))
 		default:
 			gotPath = r.Method + " " + r.URL.Path
 			w.WriteHeader(http.StatusNoContent)
 		}
 	})
 	if _, err := p.handleTaskAssignees(map[string]interface{}{"id": "1", "action": "remove", "user": "alice"}); err != nil {
 		t.Fatalf("err: %v", err)
 	}
 	if gotPath != "DELETE /api/v2/tasks/1/assignees/7" {
 		t.Errorf("移除应用解析出的数字 ID，实际 %q", gotPath)
 	}
 }
 func TestAssigneeAddUnknownUserGivesReadableError(t *testing.T) {
 	p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
 		_, _ = w.Write([]byte(`[{"id":7,"username":"bob"}]`))
 	})
 	_, err := p.handleTaskAssignees(map[string]interface{}{"id": "1", "action": "add", "user": "alice"})
 	if err == nil {
 		t.Fatal("找不到用户时必须报错，而不是发出一个注定 422 的请求")
 	}
 	if !strings.Contains(err.Error(), "找不到用户") || !strings.Contains(err.Error(), "bob") {
 		t.Errorf("错误信息应说明找不到并给出相近候选: %v", err)
 	}
 }
--- a/example/weather/README.md
+++ b/example/weather/README.md
@ -1,13 +1,33 @@
-# weather
+# weather · 天气查询
-weather plugin
+给 agent 补上天气查询能力（基于 [wttr.in](https://wttr.in)，无需 API Key）。
-## Build
+## 工具
 | 工具 | 说明 |
 |---|---|
 | `weather_current` | 查询某城市当前天气 |
 | `weather_forecast` | 查询未来几天预报 |
 | `weather_set_location` | 设置默认城市 |
 `weather_current` / `weather_forecast` 都接受 `location`（城市名，如 `Beijing`、`Shanghai`）；
 省略时用配置里的默认城市。`weather_current` 另有 `units`：`metric`（摄氏，默认）或 `imperial`（华氏）。
 ## 配置项
 | 键 | 默认 | 说明 |
 |---|---|---|
 | `default_location` | 空 | 默认城市名。留空则每次调用都必须传 `location` |
 ## 实现要点
 - **`NoMemory: true`**：天气是外部实时数据，对记忆计算无长期价值，跳过向量化与关键词提取（原文仍保留在对话里）。
 - **`Cleaner`**：输出参与记忆计算前先过滤，只保留摘要行 —— 天气查询会反复出现，全文进记忆会挤占上下文预算，而"上周三北京多少度"通常并不需要召回。
 ## 构建
 ```bash
-plugindev build
+hmapdev build
 ```
-## Install
+产出 `.hmap` 后经 Plugin Manager API 安装。
 Upload the .hmap file through the Plugin Manager API.
--- a/meta/meta.go
+++ b/meta/meta.go
@ -28,12 +28,27 @@ var (
 	//        存量插件不需要改一行也不需要重编：新增方法由**插件调用、内核实现**，
 	//        不调就不受影响。想用新字段的插件重编即可。
 	//
-	// ❗发布分支上此值是**本条发布线的 SDK 定版**；main 上则是下一个未发布中版本
+	// 1.2.0：注入行为的记忆/裁剪标志位。**全部是新增，无签名变更**：
-	// （见 核心仓 docs/git-branching.md §2.1 与 §七.1）。
+	//          - InjectOptions{NoMemory, ContextPolicy}
 	//          - IOInjector 的六个 *Opts 变体（排队/中断/同步/带媒体各一对）
 	//          - ChannelDef.ContextPolicy（顺带给 ChannelDef 补上 JSON tag：
 	//            它要跨进程传给内核，而 Cleaner 是函数必须忽略；无 tag 时只能
 	//            手写字段白名单，新增字段会被静默丢掉）
 	//        语义：零值 InjectOptions 与旧的三参数方法完全等价（记入记忆 +
 	//        不裁剪），因此存量插件不需要改一行也不需要重编。
 	//        裁剪（ContextPolicy=prune）必须显式声明——它会归档丢弃低相关事件。
 	//
-	// 本分支定版 1.1.0，服务整条核心 1.1.x 线（1.1.0、1.1.1、…）：
+	// ❗main 分支上此值是**下一个未发布中版本**；已发布的值看对应的
-	// patch 位恒为 .0，核心的 bugfix 不碰公开接口，SDK 号没有理由跟着动。
+	// release/vX.Y.x 分支与 tag（见 核心仓 docs/git-branching.md §2.1 与 §七.1）。
-	Version = "1.1.0"
+	//
 	// 现为 1.4.0：1.3.0 已随核心的正式 tag `v1.3.0` 定版并发版（本仓 tag v1.3.0、
 	// release/v1.3.x 承载它），该号从此归发布线所有，main 遂推进到下一个未发布中版本。
 	//
 	// ❗本仓**不发 patch tag**（§七.1）：一个中版本只发一次 `vX.Y.0`，核心的 1.3.x
 	// 后续 patch **不伴随 SDK 发版** —— patch 位恒为 `.0`，带非零 patch 的 SDK tag
 	// 都是错的。（2026-09-13 曾误发 `v1.3.1`，已撤回；`v1.2.1` 是同一类历史遗留。）
 	//
 	Version = "1.4.0"
 	// Commit 是构建时的 Git commit hash。
 	Commit = "unknown"
@ -44,7 +59,7 @@ var (
 	// SDKName 是 SDK 名称。
 	SDKName = "HomeAgent SDK"
-	// CoreModule 是核心仓的 Go module path，供 plugindev 生成 go.mod 时使用。
+	// CoreModule 是核心仓的 Go module path，供 hmapdev 生成 go.mod 时使用。
 	CoreModule = "gitcode.com/JianFeeeee/HomeAgent"
 	// CoreVersion 是此 SDK 所兼容的最低核心版本。
@ -56,6 +71,10 @@ var (
 	// doc.insertWithMedia / io.injectMedia* 这些 RPC，调用会返回 unknown method）。
 	// 这里仍写 1.0.0，因为它是「SDK 能在其上运行」的下限；
 	// 媒体接口是可选能力，不用就不受影响。
 	//
 	// ⚠️ 1.2.0 新增的注入标志位同理需要核心 **1.2.0+**：内核在 1.2.0 之前会
 	// 忽略注入参数里的 no_memory/context_policy 字段（不会报错，但不生效）。
 	// 想用这些标志位的插件应当要求核心 1.2.0+；不用就不受影响。
 	CoreVersion = "1.0.0"
 )
--- a/mkdocs.yml
+++ b/mkdocs.yml
@ -0,0 +1,145 @@
 # HomeAgent 插件 SDK 文档站配置。
 #
 # 设计取舍：
 #   - 每页顶部都放「版本 + 编辑链接」，因为 SDK 与内核的协议版本会错配，
 #     读者必须先能确认自己看的是哪一版。
 #   - 中文检索依赖 jieba（已装）；英文走内置分词。两者都不要额外服务。
 #   - docs/api/*.md 是**生成物**（tools/apidoc/gensite），页首会写明，防止手改。
 site_name: HomeAgent 插件 SDK
 site_description: 用 Go 或 Lua 为 HomeAgent 编写插件 —— API 参考与开发指南
 site_url: https://sdk.homeagent.jianfgit.xyz/
 copyright: MIT 许可 · JianFeeeee
 # 主题覆盖目录：只覆盖 footer.html（补备案号，见该文件里的说明）。
 docs_dir: docs
 site_dir: site_build
 theme:
  name: material
  language: zh
  # custom_dir 必须写在 theme 下（顶层会被判为未知配置）。
  custom_dir: overrides
  # 品牌图标：与主站 introduce 同一份 logo（曾用 Material 默认，不是我们的）。
  logo: assets/logo-mark.svg
  favicon: assets/logo.svg
  features:
    - navigation.instant
    - navigation.instant.progress
    - navigation.tracking
    - navigation.tabs
    - navigation.sections
    - navigation.indexes
    - navigation.top
    - toc.follow
    - search.suggest
    - search.highlight
    - search.share
    - content.code.copy
    - content.code.annotate
    - content.action.edit
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/weather-night
        name: 切换到深色
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/weather-sunny
        name: 切换到浅色
  icon:
    repo: fontawesome/brands/git-alt
 plugins:
  - search:
      lang:
        - zh
        - en
      separator: '[\s\u200b\-]'
      # 中文按词切（jieba），否则整句变一个 token，检索不到。
      jieba_dict: null
 markdown_extensions:
  - admonition
  - attr_list
  - def_list
  - footnotes
  - md_in_html
  - tables
  - toc:
      permalink: true
      toc_depth: 3
  - pymdownx.details
  # Material 的图标语法 :material-xxx: / :octicons-xxx: 依赖这个扩展。
  # 没开时它们会**原样显示为文本**（实测首页四个卡片全花了）。
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
 extra:
  generator: false
  social:
    # 主仓已迁到 GitHub；gitcode 保留为国内镜像（源码同步）。
    # 两个链接都放，是因为国内直连 gitcode 更快，而海外/权威源看 GitHub。
    - icon: fontawesome/solid/code
      link: https://github.com/JianFeeeee/homeagentsdk
      name: SDK 源码（GitHub）
    - icon: fontawesome/solid/code-branch
      link: https://gitcode.com/JianFeeeee/homeagent-sdk
      name: gitcode 镜像（国内）
    - icon: fontawesome/solid/house
      link: https://introduce.homeagent.jianfgit.xyz/
      name: HomeAgent 介绍站
  # 自定义检索端点在 docs/javascripts/api-search.js 里注册，
  # 索引文件由 gensite 产出：docs/assets/api-index.json
 nav:
  - 首页: index.md
  - 快速开始:
      - 环境与工具链: guide/getting-started.md
      - 第一个 Go 插件: guide/first-plugin.md
      - 第一个 Lua 插件: guide/first-lua-plugin.md
  - API 参考:
      - api/index.md
      - 工具（Tools）: api/tools.md
      - 阶段钩子（Stages）: api/stages.md
      - 记忆（Memory）: api/memory.md
      - 输入/输出通道: api/channels.md
      - 配置（Settings）: api/settings.md
      - 生命周期（Lifecycle）: api/lifecycle.md
      - 事件（Events）: api/events.md
      - LLM 调用: api/llm.md
      - 常量与枚举: api/constants.md
      - 桥接装配点: api/bridge.md
      - 其他类型: api/misc.md
      - 仅内置插件可用: api/builtin-only.md
  - 指南:
      - 能力边界（哪些 API 外部可用）: guide/capability-boundary.md
      - 工具并发声明（ParallelSafe/Serial）: guide/parallel-tool-declaration.md
      - 流式多 tool_call（适配器透传 index）: guide/stream-tool-call-index.md
      - 场景记忆（按场合召回）: guide/scene-memory.md
      - 打包与发布: guide/packaging.md
      - 多平台构建: guide/multi-platform.md
      - 受限 SDK 与安全: guide/security.md
  - 示例插件:
      - 总览: examples/index.md
  - 版本与兼容: versions.md
 extra_css:
  - stylesheets/extra.css
 extra_javascript:
  - javascripts/api-search.js
--- a/overrides/partials/footer.html
+++ b/overrides/partials/footer.html
@ -0,0 +1,59 @@
 {#-
  footer.html 覆盖：在版权行下补**备案号**。
  为什么要覆盖主题文件：Material 的 copyright 只渲染 config.copyright（一个字符串），
  而备案号必须是**带链接的 HTML**且含两个条目（ICP + 公安），塞不进那个字段。
  另外把「许可」写进 footer：本站内容与主站一致受 AGPL 约束，
  读者在任何页面底部都能看到，不必翻到首页。
 -#}
 <footer class="md-footer">
  {% if "navigation.footer" in features %}
    {% if page.previous_page or page.next_page %}
      {% if page.meta and page.meta.hide %}
        {% set hidden = "hidden" if "footer" in page.meta.hide %}
      {% endif %}
      <nav class="md-footer__inner md-grid" aria-label="{{ lang.t('footer') }}" {{ hidden }}>
        {% if page.previous_page %}
          {% set direction = lang.t("footer.previous") %}
          <a href="{{ page.previous_page.url | url }}" class="md-footer__link md-footer__link--prev" aria-label="{{ direction }}: {{ page.previous_page.title | e }}">
            <div class="md-footer__button md-icon">
              {% set icon = config.theme.icon.previous or "material/arrow-left" %}
              {% include ".icons/" ~ icon ~ ".svg" %}
            </div>
            <div class="md-footer__title">
              <span class="md-footer__direction">{{ direction }}</span>
              <div class="md-ellipsis">{{ page.previous_page.title }}</div>
            </div>
          </a>
        {% endif %}
        {% if page.next_page %}
          {% set direction = lang.t("footer.next") %}
          <a href="{{ page.next_page.url | url }}" class="md-footer__link md-footer__link--next" aria-label="{{ direction }}: {{ page.next_page.title | e }}">
            <div class="md-footer__title">
              <span class="md-footer__direction">{{ direction }}</span>
              <div class="md-ellipsis">{{ page.next_page.title }}</div>
            </div>
            <div class="md-footer__button md-icon">
              {% set icon = config.theme.icon.next or "material/arrow-right" %}
              {% include ".icons/" ~ icon ~ ".svg" %}
            </div>
          </a>
        {% endif %}
      </nav>
    {% endif %}
  {% endif %}
  <div class="md-footer-meta md-typeset">
    <div class="md-footer-meta__inner md-grid">
      {% include "partials/copyright.html" %}
      <div class="md-copyright ha-beian">
        <a href="https://beian.miit.gov.cn" target="_blank" rel="noopener noreferrer">豫ICP备2024074105号-1</a>
        <span class="ha-beian-sep">·</span>
        <a href="https://beian.mps.gov.cn" target="_blank" rel="noopener noreferrer">豫公网安备41070202001579号</a>
      </div>
      {% if config.extra.social %}
        {% include "partials/social.html" %}
      {% endif %}
    </div>
  </div>
 </footer>
--- a/package/build-examples.sh
+++ b/package/build-examples.sh
@ -0,0 +1,158 @@
 #!/usr/bin/env bash
 # 给 SDK 发版打包**示例插件**的 .hmap 产物。
 #
 # 为什么要在 SDK 仓库里发示例插件的 hmap：
 #   插件二进制与内核是**协议绑定**的（internal/plugin/proc/protocol.go 的
 #   ProtocolVersion + 统一共享内存区魔数）。SDK 升版往往同时意味着协议变化，
 #   而示例插件（qq/memo/browser/…）是使用者最常直接安装的东西。
 #   如果 SDK 只发工具链不发示例产物，使用者要么自己重编、要么用到与本版 SDK
 #   不匹配的旧产物——后者的表现是握手失败（协议/魔数不匹配），而且看起来像
 #   「插件坏了」而不是「版本不配套」。
 #
 # 用法：
 #   package/build-examples.sh [TARGET] [OUT_DIR]
 #     TARGET   native(默认) | linux/amd64 | linux/arm64 | darwin/amd64 | darwin/arm64 | windows/amd64 | all
 #     OUT_DIR  产物目录（默认 build/examples）
 #
 # 产物：
 #   <OUT_DIR>/<name>_<goos>_<goarch>.hmap   每个示例插件一份
 #   <OUT_DIR>/SHA256SUMS                    全部产物齐全**之后**才计算
 #   <OUT_DIR>/MANIFEST.txt                  版本、协议版本、产自哪个 commit
 #
 # 纪律（与本项目其它构建脚本一致）：
 #   1. 判成功看**产物是否存在**，不看退出码——hmapdev 对部分错误只打印不退出。
 #   2. SHA256SUMS 必须在全部产物生成完毕后一次算完，边打边算会漏掉后生成的包。
 set -uo pipefail
 SDK_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 TARGET="${1:-native}"
 OUT_DIR="${2:-$SDK_ROOT/build/examples}"
 GO="${GO:-$(command -v go 2>/dev/null || echo go)}"
 case "$TARGET" in
  native)        GOOS=""; GOARCH="" ;;
  linux/amd64)   GOOS=linux;   GOARCH=amd64 ;;
  linux/arm64)   GOOS=linux;   GOARCH=arm64 ;;
  darwin/amd64)  GOOS=darwin;  GOARCH=amd64 ;;
  darwin/arm64)  GOOS=darwin;  GOARCH=arm64 ;;
  windows/amd64)
    # 明确拒绝，而不是让调用方拿到一句深层 Go 编译错误。
    # 协议 2 的统一共享内存区只移植到了 Unix：内核 internal/plugin/proc/
    # shmpass_windows.go 仍是旧的 SHM_STAGE/SHM_EVTRING 两段布局，
    # 插件模板 proc_shm_windows.go 也缺 attachUnifiedShm。
    echo "windows 目标暂不支持：协议 2 的统一共享内存区未移植到 Windows（内核与插件模板均缺实现）。" >&2
    exit 1
    ;;
  all)
    echo "本脚本一次只构建一个平台；请由 package/build.sh 传入具体目标。" >&2
    exit 1
    ;;
  *)
    echo "Unknown target: $TARGET" >&2
    echo "Usage: $0 [native|linux/amd64|linux/arm64|darwin/amd64|darwin/arm64|windows/amd64|all] [OUT_DIR]" >&2
    exit 1
    ;;
 esac
 export CGO_ENABLED=0
 # 按平台逐个构建，**不用** bundle 模式：
 #   - bundle 会连 windows 一起编，而协议 2 的统一共享区尚未移植到 Windows
 #     （内核 shmpass_windows.go 仍是旧的两段布局），必然失败；
 #   - 逐平台构建每个目标都产出一份 .hmap，正是发版要附的产物。
 # 平台名解析成本脚本后面用（校验和与 MANIFEST 都要写清楚是哪个平台）。
 if [ -z "${GOOS:-}" ]; then
  GOOS="$(go env GOOS)"; GOARCH="$(go env GOARCH)"
 fi
 # 1) 先保证工具链可用：示例必须用**本仓当前源码**构建，否则产物协议与这一版 SDK 不符。
 #    允许外部指定（发版脚本会在跨平台构建后把刚产出的工具链路径传进来）。
 # 工具链二进制名由 plugindev 改为 hmapdev；旧变量名 PLUGINDEV 仍兼容。
 #
 # ★ 下面三处必须读 **HMAPDEV**（上一行刚解析出的规范名）。
 #   曾经读的是 PLUGINDEV：那样只有调用方恰好传旧名时才工作，
 #   而新名 HMAPDEV 只被赋给 HMAPDEV 本身、PLUGINDEV 仍是未定义，
 #   在 `set -u` 下第一处判断就 "PLUGINDEV: unbound variable" 直接退出。
 #   实测（2026-09-29）：HMAPDEV=... → exit 1；PLUGINDEV=... → 20/20 成功。
 #   发版路径传的是旧名（build.sh:92）故一直没暴露——正是「兼容」二字
 #   写在注释里、却没在代码里做到的那种缺陷。
 HMAPDEV="${HMAPDEV:-${PLUGINDEV:-$SDK_ROOT/build/hmapdev}}"
 if [ ! -x "$HMAPDEV" ]; then
  echo "[examples] 先构建 hmapdev ..."
  ( cd "$SDK_ROOT/tools/hmapdev" && "$GO" build -o "$HMAPDEV" . ) || {
    echo "[examples] hmapdev 构建失败，无法继续" >&2; exit 1; }
 fi
 if [ ! -x "$HMAPDEV" ]; then
  echo "[examples] hmapdev 不存在或不可执行：$HMAPDEV" >&2
  exit 1
 fi
 echo "=== 协议 ==="
 echo "  ProtocolVersion = $(grep -m1 '^const ProtocolVersion' "$SDK_ROOT/../internal/plugin/proc/protocol.go" 2>/dev/null | grep -oE '[0-9]+' || echo '?（本仓非内核仓，跳过）')"
 mkdir -p "$OUT_DIR"
 # 清掉上一次的校验和：残留的 SHA256SUMS 会掩盖本次缺产物。
 rm -f "$OUT_DIR"/SHA256SUMS "$OUT_DIR"/MANIFEST.txt
 ok=0
 fail=0
 failed_names=""
 for dir in "$SDK_ROOT"/example/*/; do
  [ -f "$dir/plugin.go" ] || continue
  name="$(basename "$dir")"
  # 清掉旧产物：残留会让人（和本脚本）误判成功。
  rm -rf "$dir/build" "$dir/dist"
  out=$( cd "$dir" && "$HMAPDEV" build --no-bundle --target "$GOOS/$GOARCH" 2>&1 )
  rc=$?
  # 判据是**退出码 + 产物存在**，两者都要。
  #   只看退出码：hmapdev 曾经出错也退 0（已修，但脚本不该依赖它「现在」是对的）。
  #   只看产物：部分平台失败时会留下上一次的产物，看起来像成功。
  hmap="$(ls "$dir"/dist/*.hmap 2>/dev/null | head -1)"
  if [ $rc -eq 0 ] && [ -n "$hmap" ]; then
    # 保留插件自己声明的产物名（它用的是 plg.json 的 name_en，是插件的身份），
    # 只在前面加平台前缀避免多平台互相覆盖。
    dest="$OUT_DIR/${GOOS}_${GOARCH}_$(basename "$hmap")"
    cp "$hmap" "$dest"
    printf "✓ %-14s → %s (%s)\n" "$name" "$(basename "$dest")" "$(du -h "$dest" | cut -f1)"
    ok=$((ok + 1))
  else
    printf "✗ %-14s 构建失败 (rc=%d)\n" "$name" "$rc"
    echo "$out" | tail -6 | sed 's/^/      /'
    fail=$((fail + 1))
    failed_names="$failed_names $name"
  fi
 done
 echo
 echo "示例产物: 成功 $ok / 失败 $fail"
 [ -n "$failed_names" ] && echo "失败:$failed_names"
 # 有失败就不算发版闭环：宁可整个中断，也不要发出「少几个插件」的包。
 if [ $fail -ne 0 ]; then
  echo "[examples] 有示例构建失败，不生成 SHA256SUMS" >&2
  exit 1
 fi
 # 2) 全部产物齐了才算校验和。
 ( cd "$OUT_DIR" && sha256sum ./*.hmap > SHA256SUMS )
 VERSION="${VERSION:-$(git -C "$SDK_ROOT" describe --tags --dirty 2>/dev/null || echo unknown)}"
 COMMIT="${COMMIT:-$(git -C "$SDK_ROOT" rev-parse --short HEAD 2>/dev/null || echo unknown)}"
 {
  echo "sdk_version: $VERSION"
  echo "sdk_commit:  $COMMIT"
  echo "target:      $GOOS/$GOARCH"
  echo "plugins:     $ok"
  echo "built_at:    $(date -u +%Y-%m-%dT%H:%M:%SZ)"
  echo
  echo "这些 .hmap 与本版 SDK 的插件协议绑定，必须与同版本内核配套安装。"
  echo "校验：sha256sum -c SHA256SUMS"
 } > "$OUT_DIR/MANIFEST.txt"
 echo "[examples] 产物: $OUT_DIR"
 echo "[examples] 清单: $OUT_DIR/MANIFEST.txt"
 echo "[examples] 校验: $OUT_DIR/SHA256SUMS"
--- a/package/build.sh
+++ b/package/build.sh
@ -5,6 +5,13 @@ PROJECT_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 BUILD_DIR="${PROJECT_ROOT}/build"
 VERSION="${VERSION:-$(git -C "$PROJECT_ROOT" describe --tags --dirty 2>/dev/null || echo "0.7.1")}"
 GO="${GO:-$(command -v go 2>/dev/null || echo "/home/jianf/go1.26.5/go/bin/go")}"
 # 宿主平台必须在**本脚本 export GOOS/GOARCH 之前**取定。
 # 否则 `go env GOOS` 会返回被 export 的目标平台（此前 `build.sh all all`
 # 就是因此拿 darwin 二进制在 linux 上跑，报 cannot execute binary file）。
 NATIVE_GOOS="$(env -u GOOS -u GOARCH "$GO" env GOOS 2>/dev/null || uname -s | tr 'A-Z' 'a-z')"
 NATIVE_GOARCH="$(env -u GOOS -u GOARCH "$GO" env GOARCH 2>/dev/null || uname -m)"
 case "$NATIVE_GOARCH" in x86_64|amd64) NATIVE_GOARCH="amd64" ;; aarch64|arm64) NATIVE_GOARCH="arm64" ;; esac
 case "$NATIVE_GOOS" in darwin|linux|windows) ;; *) NATIVE_GOOS="linux" ;; esac
 GOCACHE="${GOCACHE:-}"
 GOPATH="${GOPATH:-}"
@ -28,7 +35,7 @@ case "$TARGET" in
    ;;
  *)
    echo "Unknown target: $TARGET"
-    echo "Usage: $0 [native|linux/amd64|linux/arm64|darwin/amd64|darwin/arm64|windows/amd64|all] [all|plugindev]"
+    echo "Usage: $0 [native|linux/amd64|linux/arm64|darwin/amd64|darwin/arm64|windows/amd64|all] [all|hmapdev|examples]"
    exit 1
 esac
@ -42,12 +49,12 @@ export CGO_ENABLED=0
 mkdir -p "$BUILD_DIR"
-build_plugindev() {
+build_hmapdev() {
-  local src="tools/plugindev"
+  local src="tools/hmapdev"
-  local out="$BUILD_DIR/plugindev${SUFFIX:+_$SUFFIX}"
+  local out="$BUILD_DIR/hmapdev${SUFFIX:+_$SUFFIX}"
  if [ "$GOOS" = "windows" ]; then out="${out}.exe"; fi
-  echo "[BUILD] plugindev ${GOOS:-linux}/${GOARCH:-amd64} → $out"
+  echo "[BUILD] hmapdev ${GOOS:-linux}/${GOARCH:-amd64} → $out"
  cd "$PROJECT_ROOT/$src"
  "$GO" build -trimpath -ldflags "-X gitcode.com/JianFeeeee/homeagent-sdk/meta.Version=${VERSION}" \
    -o "$out" .
@ -55,9 +62,47 @@ build_plugindev() {
  cd "$PROJECT_ROOT"
 }
 # 示例插件产物随 SDK 一起发。
 #
 # 为什么必须发：插件二进制与内核是**协议绑定**的（ProtocolVersion + 统一共享
 # 内存区魔数）。SDK 升版常伴随协议变化，只发工具链不发示例产物，使用者很可能
 # 拿旧产物去装，表现是握手失败（魔数不匹配）——看起来像「插件坏了」而不是
 # 「版本不配套」。
 #
 # 用**宿主可执行**的那把工具链（而非 PATH 里的），保证产物与本次发版同源。
 #
 # 为什么不能用目标平台的那把：示例的跨平台构建是由 hmapdev 的 `--target GOOS/GOARCH`
 # 完成的，被执行的进程本身必須能在当前机器上跑。拿目标平台的二进制去跑只会得到
 # “cannot execute binary file: Exec format error”（`build.sh all all` 在 darwin 处断过）。
 build_examples() {
  local dev
  dev="$BUILD_DIR/hmapdev_${NATIVE_GOOS}_${NATIVE_GOARCH}"
  [ "$NATIVE_GOOS" = "windows" ] && dev="${dev}.exe"
  # 宿主工具链缺失时先补建（`all` 的第一个目标可能不是宿主平台）。
  if [ ! -x "$dev" ]; then
    echo "[BUILD] 先补建宿主工具链 ${NATIVE_GOOS}/${NATIVE_GOARCH}（示例的跨平台由 --target 完成）"
    ( unset GOOS GOARCH; bash "$0" "${NATIVE_GOOS}/${NATIVE_GOARCH}" hmapdev ) || return 1
  fi
  if [ ! -x "$dev" ]; then
    echo "[BUILD] 无法构建示例：缺少宿主可执行的工具链 $dev" >&2
    echo "        先跑： $0 ${NATIVE_GOOS}/${NATIVE_GOARCH} hmapdev" >&2
    return 1
  fi
  echo "[BUILD] example plugins ${GOOS:-linux}/${GOARCH:-amd64} → $BUILD_DIR/examples（用 ${NATIVE_GOOS}/${NATIVE_GOARCH} 的工具链交叉构建）"
  PLUGINDEV="$dev" VERSION="$VERSION" bash "$PROJECT_ROOT/package/build-examples.sh" "$TARGET" "$BUILD_DIR/examples"
  echo "  OK"
 }
 case "$COMPONENT" in
-  all|plugindev) build_plugindev ;;
+  all)
    # 工具链必须先建完：示例用它来构建（同源保证协议一致）。
    build_hmapdev
    build_examples
    ;;
  hmapdev) build_hmapdev ;;
  examples)  build_examples ;;
  *)
    echo "Unknown component: $COMPONENT"
    exit 1
    ;;
 esac
--- a/package/toolchain.nsi
+++ b/package/toolchain.nsi
@ -48,7 +48,7 @@ Function pageConfirm
  ${EndIf}
  ${NSD_CreateLabel} 0 5u 100% 12u "将安装以下组件:"
  Pop $0
-  ${NSD_CreateLabel} 15u 20u 100% 12u "• plugindev.exe  — 插件开发工具"
+  ${NSD_CreateLabel} 15u 20u 100% 12u "• hmapdev.exe  — 插件开发工具"
  Pop $0
  ${NSD_CreateLabel} 15u 35u 100% 12u "• SDK ${SDK_VERSION} — 将从远程仓库自动下载"
  Pop $0
@ -64,11 +64,11 @@ Section "Install" SEC_INSTALL
  SetOutPath "$INSTDIR"
  DetailPrint "复制工具链文件..."
-  File "plugindev.exe"
+  File "hmapdev.exe"
  DetailPrint "创建快捷方式..."
  CreateDirectory "$SMPROGRAMS\${PRODUCT_NAME}"
-  CreateShortCut "$SMPROGRAMS\${PRODUCT_NAME}\plugindev.lnk" "$INSTDIR\plugindev.exe" "" "$INSTDIR\plugindev.exe" 0
+  CreateShortCut "$SMPROGRAMS\${PRODUCT_NAME}\hmapdev.lnk" "$INSTDIR\hmapdev.exe" "" "$INSTDIR\hmapdev.exe" 0
  DetailPrint "配置环境变量..."
  ; Add to system PATH
@ -93,23 +93,23 @@ Section "Install" SEC_INSTALL
    DetailPrint "Git 已安装: $1"
  ${Else}
    DetailPrint "未检测到 Git，将跳过 SDK 自动下载"
-    DetailPrint "安装完成后请手动运行: plugindev sdk install ${SDK_VERSION}"
+    DetailPrint "安装完成后请手动运行: hmapdev sdk install ${SDK_VERSION}"
  ${EndIf}
  ${If} $hasGit == "1"
    DetailPrint "正在下载 SDK ${SDK_VERSION}..."
-    nsExec::ExecToStack '"$INSTDIR\plugindev.exe" sdk install ${SDK_VERSION}'
+    nsExec::ExecToStack '"$INSTDIR\hmapdev.exe" sdk install ${SDK_VERSION}'
    Pop $0
    Pop $1
    ${If} $0 == 0
      StrCpy $sdkInstallOk "1"
      DetailPrint "SDK ${SDK_VERSION} 下载完成"
      DetailPrint "正在激活 SDK ${SDK_VERSION}..."
-      nsExec::Exec '"$INSTDIR\plugindev.exe" sdk use ${SDK_VERSION}'
+      nsExec::Exec '"$INSTDIR\hmapdev.exe" sdk use ${SDK_VERSION}'
      Pop $0
    ${Else}
      DetailPrint "SDK 下载失败 (错误码: $0)"
-      DetailPrint "请手动运行: plugindev sdk install ${SDK_VERSION}"
+      DetailPrint "请手动运行: hmapdev sdk install ${SDK_VERSION}"
    ${EndIf}
  ${EndIf}
@ -126,10 +126,10 @@ SectionEnd
 Section "Uninstall"
  Delete "$INSTDIR\Uninstall.exe"
-  Delete "$INSTDIR\plugindev.exe"
+  Delete "$INSTDIR\hmapdev.exe"
  RMDir /r "$INSTDIR\sdk"
  RMDir "$INSTDIR"
-  Delete "$SMPROGRAMS\${PRODUCT_NAME}\plugindev.lnk"
+  Delete "$SMPROGRAMS\${PRODUCT_NAME}\hmapdev.lnk"
  RMDir "$SMPROGRAMS\${PRODUCT_NAME}"
  DeleteRegValue HKLM "SYSTEM\CurrentControlSet\Control\Session Manager\Environment" "HOMEAGENT_SDK_DIR"
  DeleteRegKey HKLM "Software\Microsoft\CurrentVersion\Uninstall\${PRODUCT_NAME}"
--- a/remotedevice/CMakeLists.txt
+++ b/remotedevice/CMakeLists.txt
@ -1,116 +0,0 @@
 cmake_minimum_required(VERSION 3.10)
 project(ha_remotedevice VERSION 0.1.0 LANGUAGES C)
 # ============================================================
 # ha_remotedevice — HomeAgent 远程设备接入 C SDK
 # 零外部依赖，纯 C 实现，兼容嵌入式平台。
 #
 # 使用方式:
 #   add_subdirectory(path/to/ha_remotedevice)
 #   target_link_libraries(my_app ha_remotedevice)
 #   target_include_directories(my_app PRIVATE
 #     ${HA_REMOTEDEVICE_INCLUDE_DIR})
 # ============================================================
 # 选项: 构建为静态库或动态库
 option(BUILD_SHARED_LIBS "Build ha_remotedevice as shared library" OFF)
 # 选项: 禁用 malloc/free（用于裸机环境，用户需提供 alloc 回调）
 option(HA_NO_ALLOC  "Disable dynamic memory allocation" OFF)
 # 选项: 日志级别
 set(HA_LOG_LEVEL 2 CACHE STRING "Log level: 0=none, 1=error, 2=info, 3=debug")
 # 源文件
 set(HA_REMOTEDEVICE_SRC
    src/ha_remotedevice.c
    src/ha_json.c
    src/ha_ws.c
 )
 # 头文件
 set(HA_REMOTEDEVICE_INCLUDE
    ${CMAKE_CURRENT_SOURCE_DIR}/include
 )
 # 编译选项
 if(HA_NO_ALLOC)
    add_definitions(-DHA_NO_ALLOC)
 endif()
 add_definitions(-DHA_LOG_LEVEL=${HA_LOG_LEVEL})
 # 创建库
 if(BUILD_SHARED_LIBS)
    add_library(ha_remotedevice SHARED ${HA_REMOTEDEVICE_SRC})
    if(WIN32)
        # Windows 需要导出符号
        set_target_properties(ha_remotedevice PROPERTIES
            WINDOWS_EXPORT_ALL_SYMBOLS ON)
    endif()
 else()
    add_library(ha_remotedevice STATIC ${HA_REMOTEDEVICE_SRC})
 endif()
 # 包含目录
 target_include_directories(ha_remotedevice
    PUBLIC  ${HA_REMOTEDEVICE_INCLUDE}
    PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src
 )
 # 不链接任何外部库
 target_link_libraries(ha_remotedevice PRIVATE)
 # 导出包含目录供外部项目使用
 set(HA_REMOTEDEVICE_INCLUDE_DIR
    ${HA_REMOTEDEVICE_INCLUDE}
    CACHE INTERNAL "ha_remotedevice include directories")
 # 安装规则
 install(TARGETS ha_remotedevice
    EXPORT  ha_remotedevice-targets
    LIBRARY DESTINATION lib
    ARCHIVE DESTINATION lib
    RUNTIME DESTINATION bin
    INCLUDES DESTINATION include
 )
 install(DIRECTORY include/
    DESTINATION include
 )
 install(EXPORT ha_remotedevice-targets
    DESTINATION lib/cmake/ha_remotedevice
    NAMESPACE ha_remotedevice::
 )
 # ============================================================
 # 测试（可选）
 # ============================================================
 option(BUILD_TESTS "Build ha_remotedevice tests" OFF)
 if(BUILD_TESTS)
    find_package(Threads REQUIRED)
    add_executable(ha_remotedevice_test
        test/test_ha_remotedevice.c
    )
    target_link_libraries(ha_remotedevice_test
        PRIVATE ha_remotedevice Threads::Threads
    )
    target_include_directories(ha_remotedevice_test
        PRIVATE ${HA_REMOTEDEVICE_INCLUDE_DIR}
    )
    # 添加测试
    add_test(NAME ha_remotedevice_test
        COMMAND ha_remotedevice_test
    )
 endif()
 # ============================================================
 # 编译信息
 # ============================================================
 message(STATUS "ha_remotedevice ${PROJECT_VERSION}")
 message(STATUS "  Build type: $<CONFIG>")
 message(STATUS "  Shared lib: ${BUILD_SHARED_LIBS}")
 message(STATUS "  No alloc:   ${HA_NO_ALLOC}")
--- a/remotedevice/include/ha_remotedevice.h
+++ b/remotedevice/include/ha_remotedevice.h
@ -1,216 +0,0 @@
 #ifndef HA_REMOTEDEVICE_H
 #define HA_REMOTEDEVICE_H
 #include <stdint.h>
 #include <stddef.h>
 #ifdef __cplusplus
 extern "C" {
 #endif
 /* ==================================================================
 *  ha_remotedevice — 远程设备接入 C SDK
 *
 *  零外部依赖，纯 C 实现，兼容嵌入式平台。
 *  传输层由用户实现（4 个函数指针），SDK 处理所有协议细节。
 *
 *  声明式设计:
 *    设备在代码中声明自己是什么(kind)和能做什么(caps)，
 *    声明支持哪些命令(shell/camerasue/screensee/...)并注册对应处理函数，
 *    SDK 自动处理协议握手、心跳、消息路由、结果回执。
 *
 *  协议流程:
 *    TCP 连接 → WS 升级 → hello(设备声明) → bind(令牌) → 就绪
 *    就绪后循环：读帧 → 按 handlers 表分发命令 → 自动回执结果
 * ================================================================== */
 /* ======================== 状态码 ======================== */
 typedef enum {
    HA_OK               = 0,
    HA_ERR_GENERIC      = -1,
    HA_ERR_NOMEM        = -2,
    HA_ERR_INVALID      = -3,
    HA_ERR_TIMEOUT      = -4,
    HA_ERR_DISCONNECTED = -5,
    HA_ERR_PROTOCOL     = -6,
    HA_ERR_TRANSPORT    = -7,
    HA_ERR_NOT_FOUND    = -8,
 } ha_status_t;
 /* ======================== 传输层抽象 ========================
 *
 * 用户必须实现这 4 个函数，适配不同平台（FreeRTOS+lwIP、Zephyr、裸机等）。
 *
 *  connect(ctx, host, port) → 建立 TCP 连接，返回 0 成功
 *  send(ctx, data, len)     → 发送 len 字节，返回实际发送字节数，-1 失败
 *  recv(ctx, buf, len)      → 接收最多 len 字节，返回实际接收字节数，0 断开，-1 失败
 *  close(ctx)               → 关闭连接
 */
 typedef struct {
    int  (*connect)(void *ctx, const char *host, uint16_t port);
    int  (*send)(void *ctx, const uint8_t *data, int len);
    int  (*recv)(void *ctx, uint8_t *buf, int len);
    void (*close)(void *ctx);
    void *ctx;
 } ha_transport_t;
 /* ======================== 设备声明 ========================
 *
 * 声明式配置：设备在代码中声明自己的类型和能力。
 * 这些信息通过 hello 消息发送给网关。
 *
 *  device_id  — 唯一标识，如 "esp32-cam-1"
 *  name       — 设备显示名，如 "门口摄像头"
 *  kind       — 设备种类，如 "camera"、"computer"、"speaker"、"light"
 *  caps       — 能力数组，以 NULL 结尾，如 {"camera","status",NULL}
 *  info_json  — 额外信息（JSON 字符串），可选，如 '{"chip":"ESP32-S3","psram":8}'
 */
 typedef struct {
    const char   *device_id;
    const char   *name;
    const char   *kind;
    const char  **caps;        /* NULL 结尾 */
    const char   *info_json;   /* 可选，NULL 或 JSON 字符串 */
 } ha_device_info_t;
 /* ======================== 命令结果 ========================
 *
 * 命令处理函数通过填写此结构体返回数据。
 * SDK 收到结果后自动发送回执（文本或二进制分块）。
 *
 * 使用方式：
 *   1. 简单文本：设置 status=0, output="结果文本"
 *   2. 二进制数据：设置 has_binary=1, binary_data/binary_len/mime
 *   3. 错误：设置 status=1, error="错误信息"
 *
 * 注意：output 字符串由 SDK 内部 strdup 后发送，handler 返回后即可释放。
 *       我们约定 handler 不负责分配，由 SDK 在内部做好拷贝。
 *       所以 handler 可以返回栈上或静态字符串。
 */
 typedef struct {
    int         status;          /* 0=ok, 非0=error */
    const char *output;          /* 输出文本（如 base64 图像数据），SDK 内部拷贝 */
    const char *error;           /* 错误信息 */
    int         has_binary;      /* 1=通过二进制分块回传 */
    const char *binary_mime;     /* 二进制 MIME 类型 */
    const uint8_t *binary_data;  /* 二进制数据指针 */
    int         binary_len;      /* 二进制数据长度 */
 } ha_cmd_result_t;
 /* ======================== 命令处理声明 ========================
 *
 * 声明式命令注册：设备在配置中声明支持哪些命令，并绑定处理函数。
 *
 *  command 值说明：
 *   - "shell"               → 处理 shell 类型命令，args 为完整命令字符串
 *   - "camerasue"            → 处理 homeagent-camerasue 命令，args 为参数
 *   - "screensee"            → 处理 homeagent-screensee 命令
 *   - "speakeruse"           → 处理 homeagent-speakeruse 命令
 *   - "computeruse"          → 处理 homeagent-computeruse 命令
 *   - "clipboardsee"         → 处理 homeagent-clipboardsee 命令
 *   - "clipboardsue"         → 处理 homeagent-clipboardsue 命令
 *   - "screensue"            → 处理 homeagent-screensue 命令
 *   - "deviceinfo"           → 处理设备信息查询
 *   - 其他自定义命令名       → 按字符串匹配分发
 *
 * handler 处理完毕后只需填写 result 结构体，SDK 自动回执。
 */
 typedef ha_status_t (*ha_cmd_handler_t)(const char *req_id, const char *args,
                                        ha_cmd_result_t *result, void *userdata);
 typedef struct {
    const char        *command;    /* 命令名，如 "camerasue"、"shell" */
    ha_cmd_handler_t   handler;    /* 处理函数 */
 } ha_cmd_handler_def_t;
 /* 二进制数据接收回调：收到服务端推送的二进制数据（如 TTS 音频）时调用。
 *  data 指针在回调返回后失效，如需保存请拷贝。 */
 typedef void (*ha_binary_handler_t)(const char *req_id, const char *kind,
                                    const char *mime, const uint8_t *data,
                                    int len, void *userdata);
 /* 连接状态变化回调 */
 typedef void (*ha_state_callback_t)(int connected, void *userdata);
 /* ======================== 客户端配置 ========================
 *
 * 所有配置在 ha_client_new() 时一次性声明。
 * 声明式核心：handlers 表声明了设备支持的所有命令及其处理函数。
 */
 typedef struct {
    ha_transport_t        transport;      /* 传输层实现（必须） */
    ha_device_info_t      device;         /* 设备声明（必须） */
    const char           *server;         /* 服务端地址，如 "192.168.1.100:9890"（必须） */
    const char           *token;          /* 接入令牌（必须） */
    ha_cmd_handler_def_t *handlers;       /* 声明式命令处理表，.command=NULL 标记结束 */
    ha_binary_handler_t   on_binary;      /* 二进制数据接收回调（可选） */
    ha_state_callback_t   on_state;       /* 状态变化回调（可选） */
    void                 *userdata;       /* 用户自定义数据，传给所有回调 */
    int                   ping_interval;  /* 心跳间隔秒数，0 则默认 30 */
    int                   max_reconnect;  /* 最大重连次数，-1 无限重连（默认），0 不重连 */
 } ha_config_t;
 /* ======================== 客户端 API ======================== */
 typedef struct ha_client ha_client_t;
 /* 创建客户端实例。config 数据会在内部拷贝，外部可释放。 */
 ha_client_t *ha_client_new(const ha_config_t *config);
 /* 启动连接：TCP 连接 → WS 升级 → hello → bind → 就绪。阻塞直到完成或失败。 */
 ha_status_t  ha_client_start(ha_client_t *client);
 /* 主循环处理：必须在用户的主循环中周期性调用。
 *   - 读取 WS 帧并分发
 *   - 按 handlers 表查找命令处理函数，自动回执结果
 *   - 处理心跳 ping/pong
 *   - 处理断线重连
 * 返回 HA_OK 表示正常，HA_ERR_DISCONNECTED 表示正在重连。 */
 ha_status_t  ha_client_process(ha_client_t *client);
 /* ===== 主动上报（设备主动推送，非命令响应） ===== */
 /* 发送设备主动上报事件。type 如 "motion_detected"，detail 为 JSON 字符串。 */
 void ha_client_send_event(ha_client_t *client, const char *type,
                          const char *detail);
 /* 发送设备状态更新。status: "online"、"offline"、"busy" 等。 */
 void ha_client_send_status(ha_client_t *client, const char *status);
 /* ===== 生命周期 ===== */
 /* 停止客户端，断开连接。 */
 void ha_client_stop(ha_client_t *client);
 /* 销毁客户端，释放所有资源。 */
 void ha_client_destroy(ha_client_t *client);
 /* ======================== 工具函数 ======================== */
 /* 解析 homeagent-* 命令，返回能力名和参数。
 *   command = "camerasue 5"   → cap="camerasue",  args="5"
 *   command = "screensee"      → cap="screensee",  args=""
 *   command = "computeruse {...}" → cap="computeruse", args="..."  */
 void ha_cmd_parse_homeagent(const char *command, const char **cap,
                            const char **args);
 /* 解析 JSON 格式的命令参数，提取 action 和 JSON 字符串。
 *   command = "computeruse {\"action\":\"click\",\"x\":100}"
 *   → action="computeruse", json_str="{\"action\":\"click\",...}"  */
 void ha_cmd_parse_json(const char *command, const char **action,
                       const char **json_str);
 /* Base64 编码（用于将二进制数据编码为文本回传）。
 * 返回写入 out 的字节数（不含 \0），out 不足时返回所需长度。 */
 int ha_base64_encode(const uint8_t *data, int len, char *out, int out_len);
 /* 获取版本号 */
 const char *ha_version(void);
 #ifdef __cplusplus
 }
 #endif
 #endif /* HA_REMOTEDEVICE_H */
--- a/remotedevice/src/ha_json.c
+++ b/remotedevice/src/ha_json.c
@ -1,369 +0,0 @@
 #include "ha_json.h"
 #include <stdlib.h>
 #include <string.h>
 #include <ctype.h>
 #include <stdio.h>
 /* ======================== 解析器 ======================== */
 /* 前向声明 */
 static ha_json_node_t *parse_value(const char **pp);
 /* 跳过空白 */
 static const char *skip_ws(const char *p) {
    while (*p && (unsigned char)*p <= ' ') p++;
    return p;
 }
 /* 解析字符串（"..."），返回新分配的字符串，p 更新到结束引号后 */
 static char *parse_string(const char **pp) {
    const char *p = skip_ws(*pp);
    if (*p != '"') return NULL;
    p++;
    int len = 0;
    const char *q = p;
    while (*q && *q != '"') {
        if (*q == '\\') { q++; if (*q) q++; }
        else q++;
        len++;
    }
    if (*q != '"') return NULL;
    char *s = (char *)malloc(len + 1);
    if (!s) return NULL;
    q = p;
    int i = 0;
    while (*q && *q != '"') {
        if (*q == '\\') {
            q++;
            switch (*q) {
                case '"':  s[i++] = '"'; break;
                case '\\': s[i++] = '\\'; break;
                case '/':  s[i++] = '/'; break;
                case 'b':  s[i++] = '\b'; break;
                case 'f':  s[i++] = '\f'; break;
                case 'n':  s[i++] = '\n'; break;
                case 'r':  s[i++] = '\r'; break;
                case 't':  s[i++] = '\t'; break;
                case 'u': q += 4; s[i++] = '?'; continue;
                default: s[i++] = *q; break;
            }
            q++;
        } else {
            s[i++] = *q++;
        }
    }
    s[i] = '\0';
    *pp = q + 1;
    return s;
 }
 static ha_json_node_t *new_node(ha_json_type_t type) {
    ha_json_node_t *n = (ha_json_node_t *)calloc(1, sizeof(ha_json_node_t));
    if (n) n->type = type;
    return n;
 }
 /* 解析数字 */
 static ha_json_node_t *parse_number(const char **pp) {
    const char *p = *pp;
    int neg = 0;
    if (*p == '-') { neg = 1; p++; }
    if (!isdigit((unsigned char)*p)) return NULL;
    int val = 0;
    while (isdigit((unsigned char)*p)) {
        val = val * 10 + (*p - '0');
        p++;
    }
    if (*p == '.') { p++; while (isdigit((unsigned char)*p)) p++; }
    if (*p == 'e' || *p == 'E') {
        p++;
        if (*p == '+' || *p == '-') p++;
        while (isdigit((unsigned char)*p)) p++;
    }
    *pp = p;
    ha_json_node_t *n = new_node(HA_JSON_INT);
    if (n) n->int_val = neg ? -val : val;
    return n;
 }
 /* 解析 true/false/null */
 static ha_json_node_t *parse_keyword(const char **pp) {
    const char *p = *pp;
    ha_json_node_t *n = NULL;
    if (strncmp(p, "true", 4) == 0 && !isalnum((unsigned char)p[4])) {
        n = new_node(HA_JSON_BOOL); if (n) n->bool_val = 1;
        *pp = p + 4;
    } else if (strncmp(p, "false", 5) == 0 && !isalnum((unsigned char)p[5])) {
        n = new_node(HA_JSON_BOOL); if (n) n->bool_val = 0;
        *pp = p + 5;
    } else if (strncmp(p, "null", 4) == 0 && !isalnum((unsigned char)p[4])) {
        n = new_node(HA_JSON_NULL);
        *pp = p + 4;
    }
    return n;
 }
 /* 解析对象 */
 static ha_json_node_t *parse_object(const char **pp) {
    const char *p = skip_ws(*pp);
    if (*p != '{') return NULL;
    p++;
    ha_json_node_t *obj = new_node(HA_JSON_OBJECT);
    if (!obj) return NULL;
    ha_json_node_t **tail = &obj->child;
    p = skip_ws(p);
    if (*p == '}') { *pp = p + 1; return obj; }
    while (*p) {
        p = skip_ws(p);
        char *key = parse_string(&p);
        if (!key) break;
        p = skip_ws(p);
        if (*p != ':') { free(key); break; }
        p++;
        ha_json_node_t *val = parse_value(&p);
        if (!val) { free(key); break; }
        val->key = key;
        *tail = val;
        tail = &val->next;
        p = skip_ws(p);
        if (*p == ',') { p++; continue; }
        if (*p == '}') break;
    }
    p = skip_ws(p);
    if (*p == '}') { *pp = p + 1; return obj; }
    ha_json_free(obj);
    return NULL;
 }
 /* 解析数组 */
 static ha_json_node_t *parse_array(const char **pp) {
    const char *p = skip_ws(*pp);
    if (*p != '[') return NULL;
    p++;
    ha_json_node_t *arr = new_node(HA_JSON_ARRAY);
    if (!arr) return NULL;
    ha_json_node_t **tail = &arr->child;
    p = skip_ws(p);
    if (*p == ']') { *pp = p + 1; return arr; }
    while (*p) {
        ha_json_node_t *val = parse_value(&p);
        if (!val) break;
        *tail = val;
        tail = &val->next;
        p = skip_ws(p);
        if (*p == ',') { p++; continue; }
        if (*p == ']') break;
    }
    p = skip_ws(p);
    if (*p == ']') { *pp = p + 1; return arr; }
    ha_json_free(arr);
    return NULL;
 }
 /* 解析值（主入口） */
 static ha_json_node_t *parse_value(const char **pp) {
    const char *p = skip_ws(*pp);
    if (*p == '{') return parse_object(pp);
    if (*p == '[') return parse_array(pp);
    if (*p == '"') {
        char *s = parse_string(pp);
        if (!s) return NULL;
        ha_json_node_t *n = new_node(HA_JSON_STRING);
        if (!n) { free(s); return NULL; }
        n->str_val = s;
        return n;
    }
    if (*p == '-' || isdigit((unsigned char)*p)) return parse_number(pp);
    return parse_keyword(pp);
 }
 /* ======================== 公共 API ======================== */
 ha_json_node_t *ha_json_parse(const char *str) {
    if (!str) return NULL;
    const char *p = str;
    return parse_value(&p);
 }
 const char *ha_json_get_string(const ha_json_node_t *obj, const char *key) {
    ha_json_node_t *n = ha_json_get(obj, key);
    if (!n || n->type != HA_JSON_STRING) return NULL;
    return n->str_val;
 }
 int ha_json_get_int(const ha_json_node_t *obj, const char *key, int def) {
    ha_json_node_t *n = ha_json_get(obj, key);
    if (!n || n->type != HA_JSON_INT) return def;
    return n->int_val;
 }
 ha_json_node_t *ha_json_get(const ha_json_node_t *obj, const char *key) {
    if (!obj || obj->type != HA_JSON_OBJECT) return NULL;
    ha_json_node_t *c = obj->child;
    while (c) {
        if (c->key && strcmp(c->key, key) == 0) return c;
        c = c->next;
    }
    return NULL;
 }
 int ha_json_array_len(const ha_json_node_t *arr) {
    if (!arr || arr->type != HA_JSON_ARRAY) return 0;
    int n = 0;
    ha_json_node_t *c = arr->child;
    while (c) { n++; c = c->next; }
    return n;
 }
 ha_json_node_t *ha_json_array_get(const ha_json_node_t *arr, int index) {
    if (!arr || arr->type != HA_JSON_ARRAY) return NULL;
    ha_json_node_t *c = arr->child;
    int i = 0;
    while (c) {
        if (i == index) return c;
        i++; c = c->next;
    }
    return NULL;
 }
 void ha_json_free(ha_json_node_t *root) {
    if (!root) return;
    ha_json_node_t *c = root->child;
    while (c) {
        ha_json_node_t *next = c->next;
        free(c->key);
        if (c->type == HA_JSON_STRING) free(c->str_val);
        ha_json_free(c);
        c = next;
    }
    free(root);
 }
 /* ======================== 构建器 ======================== */
 static void json_escape(ha_json_builder_t *jb, const char *s) {
    if (!s) { ha_json_builder_raw(jb, "null"); return; }
    ha_json_builder_raw(jb, "\"");
    for (const char *p = s; *p; p++) {
        unsigned char c = (unsigned char)*p;
        switch (c) {
            case '"':  ha_json_builder_raw(jb, "\\\""); break;
            case '\\': ha_json_builder_raw(jb, "\\\\"); break;
            case '\b': ha_json_builder_raw(jb, "\\b"); break;
            case '\f': ha_json_builder_raw(jb, "\\f"); break;
            case '\n': ha_json_builder_raw(jb, "\\n"); break;
            case '\r': ha_json_builder_raw(jb, "\\r"); break;
            case '\t': ha_json_builder_raw(jb, "\\t"); break;
            default:
                if (c < 0x20) {
                    char buf[8];
                    snprintf(buf, sizeof(buf), "\\u%04x", c);
                    ha_json_builder_raw(jb, buf);
                } else {
                    char buf[2] = { (char)c, 0 };
                    ha_json_builder_raw(jb, buf);
                }
                break;
        }
    }
    ha_json_builder_raw(jb, "\"");
 }
 void ha_json_builder_init(ha_json_builder_t *jb, char *buf, int cap) {
    jb->buf = buf;
    jb->len = 0;
    jb->cap = cap;
    jb->depth = 0;
    if (cap > 0) buf[0] = '\0';
 }
 void ha_json_builder_reset(ha_json_builder_t *jb) {
    jb->len = 0;
    jb->depth = 0;
    if (jb->cap > 0) jb->buf[0] = '\0';
 }
 void ha_json_builder_raw(ha_json_builder_t *jb, const char *s) {
    while (*s && jb->len < jb->cap - 1) {
        jb->buf[jb->len++] = *s++;
    }
    jb->buf[jb->len] = '\0';
 }
 void ha_json_builder_comma(ha_json_builder_t *jb) {
    if (jb->depth > 0 && jb->item_count[jb->depth - 1] > 0) {
        ha_json_builder_raw(jb, ",");
    }
    if (jb->depth > 0) jb->item_count[jb->depth - 1]++;
 }
 void ha_json_builder_begin_object(ha_json_builder_t *jb) {
    ha_json_builder_comma(jb);
    ha_json_builder_raw(jb, "{");
    if (jb->depth < 16) jb->item_count[jb->depth] = 0;
    jb->depth++;
 }
 void ha_json_builder_end_object(ha_json_builder_t *jb) {
    jb->depth--;
    ha_json_builder_raw(jb, "}");
 }
 void ha_json_builder_begin_array(ha_json_builder_t *jb) {
    ha_json_builder_comma(jb);
    ha_json_builder_raw(jb, "[");
    if (jb->depth < 16) jb->item_count[jb->depth] = 0;
    jb->depth++;
 }
 void ha_json_builder_end_array(ha_json_builder_t *jb) {
    jb->depth--;
    ha_json_builder_raw(jb, "]");
 }
 void ha_json_builder_key(ha_json_builder_t *jb, const char *key) {
    ha_json_builder_comma(jb);
    json_escape(jb, key);
    ha_json_builder_raw(jb, ":");
 }
 void ha_json_builder_add_string(ha_json_builder_t *jb, const char *val) {
    json_escape(jb, val);
 }
 void ha_json_builder_add_int(ha_json_builder_t *jb, int val) {
    char buf[16];
    snprintf(buf, sizeof(buf), "%d", val);
    ha_json_builder_raw(jb, buf);
 }
 void ha_json_builder_add_bool(ha_json_builder_t *jb, int val) {
    ha_json_builder_raw(jb, val ? "true" : "false");
 }
 void ha_json_builder_add_null(ha_json_builder_t *jb) {
    ha_json_builder_raw(jb, "null");
 }
 void ha_json_builder_string(ha_json_builder_t *jb, const char *key, const char *val) {
    ha_json_builder_key(jb, key);
    json_escape(jb, val);
 }
 void ha_json_builder_int(ha_json_builder_t *jb, const char *key, int val) {
    ha_json_builder_key(jb, key);
    ha_json_builder_add_int(jb, val);
 }
 void ha_json_builder_bool(ha_json_builder_t *jb, const char *key, int val) {
    ha_json_builder_key(jb, key);
    ha_json_builder_add_bool(jb, val);
 }
 const char *ha_json_builder_str(ha_json_builder_t *jb) {
    return jb->buf;
 }
 int ha_json_builder_len(ha_json_builder_t *jb) {
    return jb->len;
 }
--- a/Show More
+++ b/Show More