dsh-miloco-bridge 0.1.0 → 0.1.2

package/README.md

@@ -13,13 +13,13 @@
 
 | Agent 预设 | Miloco 配置页 |
 |---|---|
-| ![Agent 预设](https://raw.githubusercontent.com/exa160/dsh-miloco-bridge/main/doc/images/agent-presets.png) | ![Miloco 配置页](https://raw.githubusercontent.com/exa160/dsh-miloco-bridge/main/doc/images/miloco-settings.png) |
+| ![Agent 预设](https://raw.githubusercontent.com/exa160/dsh-miloco-bridge/main/docs/images/agent-presets.png) | ![Miloco 配置页](https://raw.githubusercontent.com/exa160/dsh-miloco-bridge/main/docs/images/miloco-settings.png) |
 
 > 截图使用演示数据；真实账号、内网地址与 token 用量已脱敏。
 
 ## 它解决什么问题
 
-- **Agent 隔离**：53 个 Miloco 工具和 18 个 Skill 只挂在专用预设「Miloco 家庭助手」上。
+- **Agent 隔离**：56 个 Miloco 工具和 18 个 Skill 只挂在专用预设「Miloco 家庭助手」上。
   普通对话看不到 `miloco_*` 工具，也不会被注入 Miloco 技能。
 - **完整能力**：设备、场景、感知、规则、任务、身份、宠物、家庭档案、通知、token 用量。
 - **推送闭环**：Miloco 的感知事件、规则触发、任务到期可以主动推送到 DSH 会话。
@@ -36,11 +36,19 @@
 dsh plugin --profile web add dsh-miloco-bridge
 ```
 
+> npm 新包可能处于审核期；若上述命令暂时 404，请使用下面的源码安装。
+
+### 源码安装（npm 审核期 / 未发布时）
+
+```bash
+dsh plugin --profile web add github:exa160/dsh-miloco-bridge
+```
+
 ### 从 bundle / 本地安装
 
 ```bash
 # 发布包
-dsh plugin --profile web add file:dist/dsh-miloco-bridge-0.1.0.tgz
+dsh plugin --profile web add file:dist/dsh-miloco-bridge-0.1.2.tgz
 
 # 本地开发（link）
 ./install.sh --profile web
@@ -49,7 +57,7 @@ dsh plugin --profile web add file:dist/dsh-miloco-bridge-0.1.0.tgz
 ### Miloco 侧 adapter
 
 如果已安装 Miloco，`install.sh` 会自动安装 adapter、写入连接与推送令牌。
-手动步骤、systemd、升级与卸载见 [doc/INSTALL.md](doc/INSTALL.md)。
+手动步骤、systemd、升级与卸载见 [docs/INSTALL.md](docs/INSTALL.md)。
 
 安装后重启 DSH：
 
@@ -84,17 +92,17 @@ systemctl --user restart dsh-web.service
 
 | 文档 | 内容 |
 |---|---|
-| [doc/INSTALL.md](doc/INSTALL.md) | 安装、连接、adapter、systemd、升级/卸载、排错 |
-| [doc/VERIFICATION.md](doc/VERIFICATION.md) | 离线测试、真实 DSH/Miloco 验证、推送与过滤验证 |
-| [doc/ARCHITECTURE.md](doc/ARCHITECTURE.md) | 双半架构、路由、配置层、状态文件、推送协议 |
-| [doc/SKILL-REWRITES.md](doc/SKILL-REWRITES.md) | 为什么重写 18 个 Skill、改了什么、合规边界 |
-| [doc/TOOLS.md](doc/TOOLS.md) | 53 个工具的参数与语义 |
+| [docs/INSTALL.md](docs/INSTALL.md) | 安装、连接、adapter、systemd、升级/卸载、排错 |
+| [docs/VERIFICATION.md](docs/VERIFICATION.md) | 离线测试、真实 DSH/Miloco 验证、推送与过滤验证 |
+| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 双半架构、路由、配置层、状态文件、推送协议 |
+| [docs/SKILL-REWRITES.md](docs/SKILL-REWRITES.md) | 为什么重写 18 个 Skill、改了什么、合规边界 |
+| [docs/TOOLS.md](docs/TOOLS.md) | 56 个工具的参数与语义 |
 | [SECURITY.md](SECURITY.md) | 安全边界与漏洞报告 |
 
 ## 开发
 
 ```bash
-npm test                 # 50 项测试
+npm test                 # 76 项测试
 npm run selftest         # 离线自检
 npm run verify:readonly  # 真实 Miloco 只读接口
 npm run pack:bundle      # 生成 dist/*.tgz

package/cordis.patch.yml

@@ -53,10 +53,22 @@
             minLevel: "all"
         deploy:
           repo: "https://github.com/XiaoMi/xiaomi-miloco"
+          # 一键部署下载官方 release install.sh，不再 clone 源码。
           # 留空 = $DSH_HOME/plugin-data/dsh-miloco-bridge/xiaomi-miloco
-          # 必须是 DSH 进程用户可读写的目录，不要指向只读工作区或插件 node_modules。
+          # （release 部署不创建该目录；仅保留给旧源码部署/卸载清理）
           sourceDir: ""
-          installArgs: ["--dev", "--skip-openclaw"]
+          # --skip-openclaw 阻止上游安装 OpenClaw 插件；--agent-platform=openclaw
+          # 只用于通过上游非交互式平台检测，实际由 DSH adapter 接管。
+          installArgs: ["--skip-openclaw", "--agent-platform=openclaw", "--lang=zh"]
+          # 直连 GitHub 失败时按顺序尝试这些镜像（直接拼接原 URL）。
+          githubMirrors:
+            - "https://gh-proxy.com/"
+            - "https://gh-proxy.org/"
+          # release 包默认从第一个镜像下载；留空 = 自动拼接 releases/download。
+          downloadSite: ""
+          # 额外的 uv 索引，不覆盖用户默认索引；PyPI 带 upload-time 元数据，
+          # 部分国内镜像缺少该元数据会触发安装器 exclude-newer 解析失败。
+          uvIndex: "https://pypi.org/simple"
         # 设置页里不展示任何「DSH 默认模型」配置项。模型下拉只有
         # 「跟随该对话」+ 实际模型；不选模型就完全不动会话的模型选择。
     # ------------------------------------------------------------------
@@ -68,9 +80,7 @@
         id: miloco
         name: Miloco 家庭助手
         description: >-
-          家里的全屋智能管家：只读 / 管家两种模式，能看设备、问摄像头、查档案与用量。
-          米家工具与技能只在这个预设里；新建会话时选择它。
-          模式说明与使用示例见「设置 → 插件 → Miloco」。
+          家里的全屋智能管家：米家工具与技能隔离在这个预设中，能看设备、问摄像头、查档案与用量。
         order: 30
         plugins:
           - id: dsh-miloco-bridge-tools
@@ -85,3 +95,68 @@
               overlayFile: ""
               stateFile: ""
               cwd: ""
+          # 保留标准 DSH Agent 的工具面；子插件只在 miloco 预设内生效。
+          - id: tool-bash
+            name: '@deepseek-ai/dsh-tool-bash'
+            disabled: !!js process.platform === 'win32'
+          - id: tool-pwsh
+            name: '@deepseek-ai/dsh-tool-pwsh'
+            disabled: !!js process.platform !== 'win32'
+          - id: tool-fs
+            name: '@deepseek-ai/dsh-tool-fs'
+          - id: tool-fs-search
+            name: '@deepseek-ai/dsh-tool-fs-search'
+            config:
+              sampleOverCapGlobResults: false
+          - id: tool-jobs
+            name: '@deepseek-ai/dsh-tool-jobs'
+          - id: tool-schedule
+            name: '@deepseek-ai/dsh-tool-schedule'
+          - id: skill-filesystem
+            name: '@deepseek-ai/dsh-skill-filesystem'
+          - id: tool-skill
+            name: '@deepseek-ai/dsh-tool-skill'
+          - id: command-goal
+            name: '@deepseek-ai/dsh-command-goal'
+          - id: tool-goal
+            name: '@deepseek-ai/dsh-tool-goal'
+          - id: tool-ask-user
+            name: '@deepseek-ai/dsh-tool-ask-user'
+          - id: tool-todo
+            name: '@deepseek-ai/dsh-tool-todo'
+            config:
+              allowParallelInProgress: true
+          - id: tool-web
+            name: '@deepseek-ai/dsh-tool-web'
+            config:
+              fetch: true
+              searchTimeoutMs: 60000
+          - id: present
+            name: '@deepseek-ai/dsh-tool-present'
+          - id: delegation
+            name: cordis:group
+            group: true
+            isolate:
+              workflowEngine: true
+            config:
+              - id: tool-subagent-control
+                name: '@deepseek-ai/dsh-tool-subagent-control'
+              - id: tool-subagent-list-agents
+                name: '@deepseek-ai/dsh-tool-subagent-control/list-agents'
+              - id: tool-subagent
+                name: '@deepseek-ai/dsh-tool-subagent'
+                config:
+                  provider: spawn
+                  toolName: subagent
+                  modelSelectionSettings: true
+              - id: tool-subagent-fork
+                name: '@deepseek-ai/dsh-tool-subagent'
+                config:
+                  provider: fork
+                  toolName: subagent_fork
+              - id: workflow-ptc
+                name: '@deepseek-ai/dsh-workflow-ptc'
+                config:
+                  provider: spawn
+              - id: tool-workflow
+                name: '@deepseek-ai/dsh-tool-workflow'

package/{doc → docs}/ARCHITECTURE.md

@@ -14,7 +14,7 @@ DSH Host
 │    └─ 浏览器设置页
 └── preset「miloco」
      └── dsh-miloco-bridge/tools
-          ├─ 30 只读 + 23 写 + dsh_deliver_message
+          ├─ 30 只读 + 26 写 + dsh_deliver_message
           └─ 18 Skill
 ```
 
@@ -31,12 +31,12 @@ DSH Host
 lib/
 ├── index.js            全局半边：webhook + 设置 API 的装配
 ├── tools-entry.js      预设半边：工具/技能/投递工具的装配
-├── tools.js            53 个原生工具定义
+├── tools.js            56 个原生工具定义
 ├── skills.js           SKILL.md 读取与 ctx.skills.register
 ├── miloco-client.js    Miloco HTTP 客户端（连接优先级、envelope 解包）
 ├── push.js             入站推送：鉴权、目标解析、会话恢复、等待 turn
 ├── settings-api.js     设置 API 路由
-├── deploy.js           一键部署（启动已有 / clone + 安装 / 写 adapter）
+├── deploy.js           一键部署（启动已有 / 下载 release 安装器 / 写 adapter）
 ├── uninstall.js        卸载 Miloco（停服务 / 移除 adapter / 可选删数据或源码）
 ├── perception.js       感知事件优先级解析与阈值过滤
 ├── client.js           浏览器设置页（无构建步骤）
@@ -194,13 +194,20 @@ push.perception.minLevel = all | low | medium | high
 
 1. 健康检查 `127.0.0.1:1810`；
 2. 已装 Miloco → `miloco-cli service start`；
-3. 未装 → `git clone` 官方仓库到 `$DSH_HOME/plugin-data/dsh-miloco-bridge/xiaomi-miloco`；
-4. 运行 `scripts/install.sh --dev --skip-openclaw`；
+3. 未装 → 下载官方 release `install.sh`（直连失败时走 GitHub 镜像）；
+4. 以 headless agent 模式运行 `install.sh --agent-prepare` + `--agent-finish`
+   （`--skip-openclaw --agent-platform=openclaw --lang=zh`）；
 5. 启动服务并等待健康；
 6. 安装 adapter，写令牌；
 7. 写 overlay 的连接与推送令牌。
 
-所有子进程用 `spawn(command, args)`，不做 shell 字符串拼接；仓库地址必须是 `https://`。
+所有子进程用 `spawn(command, args)`，不做 shell 字符串拼接。
+`--agent-platform=openclaw` 只用于通过上游平台的非交互检测，
+`--skip-openclaw` 保证不安装 OpenClaw 插件，实际由 DSH adapter 接管。
+
+镜像模式的一键升级复用同一 release 安装器：下载 → `--agent-prepare` →
+`--agent-finish` → 启动服务 → 写 adapter/webhook。升级状态与日志独立于部署，
+日志在 `$MILOCO_HOME/log/dsh-miloco-upgrade.log`；命令参数和子进程输出都会脱敏。
 
 ## 9. 安全边界
 

package/{doc → docs}/INSTALL.md

@@ -26,18 +26,21 @@ cd /path/to/dsh-miloco-bridge
 dsh plugin --profile web add "link:/path/to/dsh-miloco-bridge"
 ```
 
+npm 新包可能处于审核期；若 `dsh plugin add dsh-miloco-bridge` 暂时 404，
+可改用 `dsh plugin --profile web add github:exa160/dsh-miloco-bridge`。
+
 ### 1.2 打包后安装（发布）
 
 ```bash
 npm run pack:bundle
-# dist/dsh-miloco-bridge-0.1.0.tgz
-dsh plugin --profile web add "file:/path/to/dist/dsh-miloco-bridge-0.1.0.tgz"
+# dist/dsh-miloco-bridge-0.1.2.tgz
+dsh plugin --profile web add "file:/path/to/dist/dsh-miloco-bridge-0.1.2.tgz"
 ```
 
 或：
 
 ```bash
-./install.sh --profile web --bundle dist/dsh-miloco-bridge-0.1.0.tgz
+./install.sh --profile web --bundle dist/dsh-miloco-bridge-0.1.2.tgz
 ```
 
 ### 1.3 手动配置
@@ -91,16 +94,17 @@ install.sh
 3. 点「一键部署 Miloco」；
 4. 面板会实时显示部署日志。流程：
    - 若检测到已安装的 `miloco-cli` 与 `$MILOCO_HOME/config.json`，先尝试 `service start`；
-   - 否则 clone `https://github.com/XiaoMi/xiaomi-miloco` 到
-     `$DSH_HOME/plugin-data/dsh-miloco-bridge/xiaomi-miloco`；
-   - 运行上游 `scripts/install.sh --dev --skip-openclaw`；
+   - 否则下载官方 release `install.sh`（GitHub 直连失败时走 `gh-proxy.com` / `gh-proxy.org`）；
+   - 以 headless agent 模式运行 `install.sh --agent-prepare --skip-openclaw --agent-platform=openclaw --lang=zh`
+     和 `install.sh --agent-finish ...`（`openclaw` 只用于通过上游平台检测，不会安装 OpenClaw 插件）；
+   - 安装器使用 `UV_CACHE_DIR=$MILOCO_HOME/.uv-cache`、额外 `UV_INDEX`（默认 PyPI）
+     和镜像下载 release 包（`MILOCO_DOWNLOAD_URL`，默认第一个 GitHub 镜像）；
    - 启动后端并等待 `127.0.0.1:1810` 健康；
    - 安装本插件的 adapter，生成/复用推送令牌，写入 overlay。
 5. 部署完成后按面板提示绑定米家账号、开启摄像头感知。
 
-> **部署目录必须可写**：默认是 `$DSH_HOME/plugin-data/dsh-miloco-bridge/xiaomi-miloco`
-> （`$DSH_HOME` 默认 `~/.dsh`，跟随环境变量）。不要指向只读工作区、`node_modules`
-> 或其它 DSH 进程用户不可写的路径；部署前会显式检查并给出中文错误。
+> **MILOCO_HOME 必须可写**：默认 `~/.miloco`，部署前会显式检查并给出中文错误。
+> release 部署不再创建源码目录；`deploy.sourceDir` 仅用于旧源码部署或卸载清理。
 
 > 一键部署会运行上游安装器，可能安装 Python 依赖并占用较多磁盘。
 > 请先确认你接受 Xiaomi Miloco 的许可证与资源开销。
@@ -197,7 +201,7 @@ overlay 示例：
 | 模式 | 工具 |
 |---|---|
 | `readonly` | 30 个只读工具 + 18 技能 |
-| `full` | 30 只读 + 23 写 + `dsh_deliver_message` + 18 技能 |
+| `full` | 30 只读 + 26 写 + `dsh_deliver_message` + 18 技能 |
 
 模式写在状态文件里，**插件激活时读取**：
 
@@ -269,10 +273,20 @@ systemctl --user restart dsh-web.service
 
 ```bash
 npm run pack:bundle
-dsh plugin --profile web add "file:dist/dsh-miloco-bridge-0.1.0.tgz"
+dsh plugin --profile web add "file:dist/dsh-miloco-bridge-0.1.2.tgz"
 systemctl --user restart dsh-web.service
 ```
 
+### 8.3 Miloco 版本更新
+
+「运行状态 → 检查更新」按顺序检查：Miloco 后端 → 直连 GitHub → GitHub 镜像。
+
+- 后端能访问 GitHub：走 Miloco 原有一键升级；
+- 后端不可达但镜像可用：由插件下载 release 安装器并执行 headless 升级
+  （`--agent-prepare` + `--agent-finish`，继续使用 `MILOCO_HOME` 和镜像下载）；
+- 源码/dev 部署不提供一键升级；
+- 升级过程写入 `$MILOCO_HOME/log/dsh-miloco-upgrade.log`。
+
 卸载插件：
 
 ```bash

package/{doc → docs}/SKILL-REWRITES.md

@@ -124,7 +124,7 @@ Xiaomi Miloco 的许可证对复制、修改、分发有明确限制。为了能
 | `miloco-devices` | 设备查询/控制/场景 | `miloco_device_*`、`miloco_scene_*` |
 | `miloco-perception` | 摄像头问答与事件回顾 | `miloco_perceive`、`miloco_perception_logs` |
 | `miloco-perception-digest` | 感知日志摘要 | `miloco_perception_logs`、`miloco_event_list` |
-| `miloco-create-task` | 规则/定时/统计/生命周期 | `miloco_rule_create`、`miloco_cron_create`、`miloco_task_create` |
+| `miloco-create-task` | 规则/定时/统计/生命周期 | `miloco_rule_create`、`miloco_cron_create`、`miloco_task_create`、`miloco_task_record_init` |
 | `miloco-terminate-task` | 终止并清理任务 | `miloco_task_delete` |
 | `miloco-notify` | 主动通知与文案 | `miloco_notify_push`、`dsh_deliver_message` |
 | `miloco-home-profile` | 档案查询与维护 | `miloco_home_profile*` |
@@ -153,7 +153,7 @@ Xiaomi Miloco 的许可证对复制、修改、分发有明确限制。为了能
 5. 家庭档案渲染接口返回 `{markdown: "..."}`，不是 `{rendered: "..."}`。
 
 这些坑在上游 Skill 中有的没有写、有的写成了旧接口；本仓库的 Skill 按真实接口行为编写，
-并在 `doc/TOOLS.md` 中保留说明。
+并在 `docs/TOOLS.md` 中保留说明。
 
 ---
 
@@ -162,7 +162,7 @@ Xiaomi Miloco 的许可证对复制、修改、分发有明确限制。为了能
 1. 起一个**默认预设**的新会话，发一句普通问题；
 2. 会话请求头里应有 **0 个** `miloco_*` 工具；
 3. 起一个 **Miloco 家庭助手** 预设的新会话；
-4. 只读模式应有 **30 个** `miloco_*` 工具；管家模式应有 **53 个**（30 读 + 23 写 + `dsh_deliver_message`）。
+4. 只读模式应有 **30 个** `miloco_*` 工具；管家模式应有 **56 个**（30 读 + 26 写 + `dsh_deliver_message`）。
 
 如果普通会话出现 `miloco_*`，说明 preset 作用域没生效，检查 `cordis.patch.yml` 中
 `preset-miloco` 的 `plugins` 是否指向 `dsh-miloco-bridge/tools`。

package/{doc → docs}/TOOLS.md

@@ -3,7 +3,7 @@
 所有米家工具返回 JSON 字符串。工具只在「Miloco 家庭助手」预设的会话中可见。
 
 - 只读模式：30 个只读工具
-- 管家模式：30 只读 + 23 写
+- 管家模式：30 只读 + 26 写
 - 另有 `dsh_deliver_message`（DSH 侧投递，不碰设备）
 
 ## 只读工具（30）
@@ -12,7 +12,7 @@
 |---|---|---|---|
 | `miloco_status` | — | `/api/admin/status` + `/api/perception/engine/status` | 运行状态、账号、引擎、数据库 |
 | `miloco_capabilities` | — | — | 当前模式与已注册工具 |
-| `miloco_device_list` | `room?` | `/api/miot/device_list` | 设备清单（did / 名称 / 房间 / 类型） |
+| `miloco_device_list` | `room?`, `name?`, `online_only?`, `limit?`, `offset?`, `include?[]` | `/api/miot/device_list` | 默认 `did/name/online/room_name/model/home_id`，默认最多 500 台；`include` 可取 `icon/local_ip/home_name/order_time/lan_online/sub_devices` |
 | `miloco_device_spec` | `did` | `/api/miot/devices/{did}/spec` | SPEC：iid、access、枚举、范围 |
 | `miloco_device_status` | `did`, `iid?` | `/api/miot/devices/{did}/status` | 当前属性值 |
 | `miloco_device_history` | — | `/api/miot/device_history` | 最近访问的 iid |
@@ -41,21 +41,24 @@
 | `miloco_push_target` | — | overlay | 当前推送目标与感知等级 |
 | `miloco_push_models` | — | DSH 模型目录 | 可选模型清单 |
 
-## 写工具（23，仅管家模式）
+## 写工具（26，仅管家模式）
 
 | 工具 | 参数 | 说明 |
 |---|---|---|
 | `miloco_device_control` | `did`, `type?`, `iid?`, `value?`, `properties?[]`, `params?[]` | `set_property`（默认）/ `set_properties` / `call_action` |
 | `miloco_scene_trigger` | `scene_id` | 触发手动场景 |
 | `miloco_notify_push` | `notify` | 米家 App 通知 |
-| `miloco_rule_create` | `content?`, `name?`, `mode?` | 创建规则 |
-| `miloco_task_create` | `kind`, `content`, `name?` | `rule` / `schedule` / `record` / `lifecycle` |
+| `miloco_rule_create` | `name`, `task_id`, `condition`, `mode?`, `direction?`, `actions?[]`, `action_descriptions?[]`, `on_enter_*?`, `on_exit_*?` | 创建结构化规则；不再接收自然语言 `content` |
+| `miloco_rule_delete` | `rule_id` | 删除规则 |
+| `miloco_task_create` | `task_id`, `description`, `lifecycle?`, `expires_at?` | 创建任务占位行；`task_id` 只能用小写字母/数字/下划线 |
+| `miloco_task_record_init` | `task_id`, `kind`, `content?` | 初始化累计记录：`progress` / `duration` / `event` |
 | `miloco_task_delete` | `task_id`, `reason` | 删除任务（`completed` / `expired` / `abandoned`） |
-| `miloco_cron_create` | `kind`, `message`, `name?`, `cron_expr?`, `at_iso?`, `every_ms?`, `tz?`, `task_id?` | 注册定时计划 |
+| `miloco_cron_create` | `kind`, `message`, `name?`, `cron_expr?`, `at_iso?`, `every_ms?`, `tz?`, `task_id?` | 注册定时计划；`every_ms` 最小 60000 |
+| `miloco_cron_delete` | `cron_id` | 删除定时计划 |
 | `miloco_scope_set` | `items[]{did, in_use}` | 修改感知摄像头 |
-| `miloco_home_profile_write` | `ops[]` | 写正式档案；`from=<candidate_id>` 消费候选 |
-| `miloco_home_profile_candidate_write` | `ops[]` | 写候选档案 |
-| `miloco_home_profile_commit` | — | 清理/归档/渲染 |
+| `miloco_home_profile_write` | `ops[]`, `user_edit?` | 写正式档案；`from=<candidate_id>` 消费候选 |
+| `miloco_home_profile_candidate_write` | `ops[]` | 写候选档案；每个 op 必须带 `date` |
+| `miloco_home_profile_commit` | — | 清理/归档/渲染（无请求体） |
 | `miloco_home_profile_reassign` | `mappings[]` | 主体归并/名称归一 |
 | `miloco_person_create` | `name`, `role?` | 新增成员花名册 |
 | `miloco_person_update` | `person_id`, `name?`, `role?` | 修改成员 |
@@ -64,7 +67,7 @@
 | `miloco_pet_update` | `pet_id`, `name?`, `species?` | 修改宠物 |
 | `miloco_pet_delete` | `pet_id` | 删除宠物 |
 | `miloco_pet_observe` | `files[]`, `grounding?` | 观察宠物外观（不落库） |
-| `miloco_pet_reference_crops` | `pet_id`, `files[]` | 落库参照图 |
+| `miloco_pet_reference_crops` | `pet_id`, `files[]`, `mode?` | 落库参照图；multipart 字段为 `crops` |
 | `miloco_register_preview` | `media_b64?`, `media_b64_list?`, `media_kind?`, `cluster_id?`, `member_id?`, `topk?` | 身份样本预览 |
 | `miloco_register_commit` | `register_session_id_pending`, `indices?`, `member_name?`, `member_role?` | 身份样本落库 |
 | `miloco_push_target_set` | `sessionId?`, `provider?`, `model?`, `reasoningEffort?`, `perceptionLevel?` | 修改推送目标与感知等级 |

package/{doc → docs}/VERIFICATION.md

@@ -22,7 +22,7 @@ python3 -m py_compile adapter/dsh_adapter.py
 覆盖：
 
 - 连接/overlay/state 的路径与权限（`0600`）；
-- 只读 30 工具、管家 53 工具；
+- 只读 30 工具、管家 56 工具；
 - 推送目标：上次会话 / 显式会话 / 派生会话 / 模型留空不调 `selectModel`；
 - 感知过滤：结构化 urgency、文本“事件优先级”、批量取最高、ignore、阈值比较；
 - webhook：无令牌 503、错令牌 401、正确令牌通过、幂等、turn 等待；
@@ -144,6 +144,21 @@ node tools/verify-readonly.mjs
 真实环境结果（2026-10-28）：24/24 接口通过；账号已绑定、感知引擎运行中。
 账号昵称、设备数量与 token 用量属于家庭隐私，已脱敏，不在仓库中列出。
 
+### 3.1 写接口契约审计
+
+从运行中的 Miloco 读取 `/openapi.json`，用 stub client 执行全部 56 个工具
+（其中 52 个会发 HTTP 请求），逐项比对 method / path / query / body 与 OpenAPI
+schema（required、additionalProperties、enum）。所有 HTTP 工具的路径与方法都存在；本轮修复了：
+
+- `POST /api/tasks` 的 v2 契约（`task_id` + `description`，不再接受 `kind/content/name`）
+- 新增 `POST /api/tasks/{id}/record` 的 `miloco_task_record_init`
+- `POST /api/rules` 改为结构化 `condition/actions`
+- 设备列表的 `room` 改为本地过滤（后端没有该查询参数）
+- `candidates:write` 强制 `date`，`commit` 去掉多余请求体
+- 宠物参照图 multipart 字段改为 `crops`
+
+对应的离线契约测试见 `test/tools-contract.test.js`。真实写操作仍未在家庭设备上执行。
+
 ---
 
 ## 4. 推送闭环验证
@@ -192,7 +207,7 @@ dsh-miloco-bridge: push delivery failed ...   # 仅在失败时
 2. 查看该会话的请求头/工具列表：不应出现任何 `miloco_*`；
 3. 新建一个 **Miloco 家庭助手** 会话：
    - 只读模式：30 个 `miloco_*`；
-   - 管家模式：53 个 `miloco_*` + `dsh_deliver_message`。
+   - 管家模式：56 个 `miloco_*` + `dsh_deliver_message`。
 
 如果标准会话出现 `miloco_*`，检查 `preset-miloco` 是否被正确装载。
 
@@ -205,17 +220,17 @@ dsh-miloco-bridge: push delivery failed ...   # 仅在失败时
 
 ```bash
 npm run pack:bundle
-tar -tzf dist/dsh-miloco-bridge-0.1.0.tgz | head -30
+tar -tzf dist/dsh-miloco-bridge-0.1.2.tgz | head -30
 ```
 
 预期包含：`package/lib/*`、`package/skills/*/SKILL.md`、`package/adapter/dsh_adapter.py`、
-`package/cordis.patch.yml`、`package/doc/*`，且**不含** `test/`、`node_modules/`、真实 token。
+`package/cordis.patch.yml`、`package/docs/*`，且**不含** `test/`、`node_modules/`、真实 token。
 
 安装：
 
 ```bash
 DSH_HOME=/tmp/dsh-miloco-bundle-verify \
-  dsh plugin --profile web add "file:$PWD/dist/dsh-miloco-bridge-0.1.0.tgz"
+  dsh plugin --profile web add "file:$PWD/dist/dsh-miloco-bridge-0.1.2.tgz"
 ```
 
 ---
@@ -226,4 +241,5 @@ DSH_HOME=/tmp/dsh-miloco-bundle-verify \
   推送 turn 的等待/回复逻辑由离线测试覆盖。
 - 一键部署会运行上游安装器，耗时取决于网络与 Python 依赖；本次未在干净机器上从零跑完整安装。
 - 写操作（控制设备、建任务）没有在真实家庭上执行，避免产生物理副作用；
-  写工具的注册与参数形状由测试覆盖。
+  写工具的请求体/查询参数已按 OpenAPI 做契约测试（`test/tools-contract.test.js`），
+  但真实写入链路仍需在用户确认后用测试任务验证。