dsh-miloco-bridge 0.1.0 → 0.1.1

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.1.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                 # 65 项测试
 npm run selftest         # 离线自检
 npm run verify:readonly  # 真实 Miloco 只读接口
 npm run pack:bundle      # 生成 dist/*.tgz

package/cordis.patch.yml

@@ -68,9 +68,7 @@
         id: miloco
         name: Miloco 家庭助手
         description: >-
-          家里的全屋智能管家：只读 / 管家两种模式，能看设备、问摄像头、查档案与用量。
-          米家工具与技能只在这个预设里；新建会话时选择它。
-          模式说明与使用示例见「设置 → 插件 → Miloco」。
+          家里的全屋智能管家：米家工具与技能隔离在这个预设中，能看设备、问摄像头、查档案与用量。
         order: 30
         plugins:
           - id: dsh-miloco-bridge-tools

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,7 +31,7 @@ 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

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.1.tgz
+dsh plugin --profile web add "file:/path/to/dist/dsh-miloco-bridge-0.1.1.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.1.tgz
 ```
 
 ### 1.3 手动配置
@@ -197,7 +200,7 @@ overlay 示例：
 | 模式 | 工具 |
 |---|---|
 | `readonly` | 30 个只读工具 + 18 技能 |
-| `full` | 30 只读 + 23 写 + `dsh_deliver_message` + 18 技能 |
+| `full` | 30 只读 + 26 写 + `dsh_deliver_message` + 18 技能 |
 
 模式写在状态文件里，**插件激活时读取**：
 
@@ -269,7 +272,7 @@ 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.1.tgz"
 systemctl --user restart dsh-web.service
 ```
 

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?` | `/api/miot/device_list` | 设备清单；`room` 在本地按 `room_name` 过滤 |
 | `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.1.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.1.tgz"
 ```
 
 ---
@@ -226,4 +241,5 @@ DSH_HOME=/tmp/dsh-miloco-bundle-verify \
   推送 turn 的等待/回复逻辑由离线测试覆盖。
 - 一键部署会运行上游安装器，耗时取决于网络与 Python 依赖；本次未在干净机器上从零跑完整安装。
 - 写操作（控制设备、建任务）没有在真实家庭上执行，避免产生物理副作用；
-  写工具的注册与参数形状由测试覆盖。
+  写工具的请求体/查询参数已按 OpenAPI 做契约测试（`test/tools-contract.test.js`），
+  但真实写入链路仍需在用户确认后用测试任务验证。