dsh-miloco-bridge 0.1.1 → 0.1.2

package/README.md

@@ -48,7 +48,7 @@ dsh plugin --profile web add github:exa160/dsh-miloco-bridge
 
 ```bash
 # 发布包
-dsh plugin --profile web add file:dist/dsh-miloco-bridge-0.1.1.tgz
+dsh plugin --profile web add file:dist/dsh-miloco-bridge-0.1.2.tgz
 
 # 本地开发（link）
 ./install.sh --profile web
@@ -102,7 +102,7 @@ systemctl --user restart dsh-web.service
 ## 开发
 
 ```bash
-npm test                 # 65 项测试
+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 默认模型」配置项。模型下拉只有
         # 「跟随该对话」+ 实际模型；不选模型就完全不动会话的模型选择。
     # ------------------------------------------------------------------
@@ -83,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/docs/ARCHITECTURE.md

@@ -36,7 +36,7 @@ lib/
 ├── 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/docs/INSTALL.md

@@ -33,14 +33,14 @@ npm 新包可能处于审核期；若 `dsh plugin add dsh-miloco-bridge` 暂时
 
 ```bash
 npm run pack:bundle
-# dist/dsh-miloco-bridge-0.1.1.tgz
-dsh plugin --profile web add "file:/path/to/dist/dsh-miloco-bridge-0.1.1.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.1.tgz
+./install.sh --profile web --bundle dist/dsh-miloco-bridge-0.1.2.tgz
 ```
 
 ### 1.3 手动配置
@@ -94,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 的许可证与资源开销。
@@ -272,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.1.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/docs/TOOLS.md

@@ -12,7 +12,7 @@
 |---|---|---|---|
 | `miloco_status` | — | `/api/admin/status` + `/api/perception/engine/status` | 运行状态、账号、引擎、数据库 |
 | `miloco_capabilities` | — | — | 当前模式与已注册工具 |
-| `miloco_device_list` | `room?` | `/api/miot/device_list` | 设备清单；`room` 在本地按 `room_name` 过滤 |
+| `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 |

package/docs/VERIFICATION.md

@@ -220,7 +220,7 @@ dsh-miloco-bridge: push delivery failed ...   # 仅在失败时
 
 ```bash
 npm run pack:bundle
-tar -tzf dist/dsh-miloco-bridge-0.1.1.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`、
@@ -230,7 +230,7 @@ tar -tzf dist/dsh-miloco-bridge-0.1.1.tgz | head -30
 
 ```bash
 DSH_HOME=/tmp/dsh-miloco-bundle-verify \
-  dsh plugin --profile web add "file:$PWD/dist/dsh-miloco-bridge-0.1.1.tgz"
+  dsh plugin --profile web add "file:$PWD/dist/dsh-miloco-bridge-0.1.2.tgz"
 ```
 
 ---

package/lib/client.js

@@ -755,6 +755,8 @@ window.__ModuleLoader__.load({
           h('div', { className: 'muted' },
             backend.error || `连不上 ${connection.baseUrl || '（未配置地址）'}。`
             + '插件本身可以独立安装；部署或连接之后才会出现设备与感知能力。'),
+          h('div', { className: 'muted' },
+            '一键部署会下载官方 release 安装器（支持 GitHub 镜像），不会在本机编译源码。'),
           h('div', { className: 'row' },
             h('button', { type: 'button', className: 'primary', disabled: busy, onClick: deploy },
               busy ? '部署中…' : '一键部署 Miloco'),
@@ -926,14 +928,19 @@ window.__ModuleLoader__.load({
       const upgradeInfo = versionInfo?.upgrade ?? null
       const currentVersion = upgradeInfo?.current || versionData?.version || ''
       const latestVersion = upgradeInfo?.latest || ''
-      const deployKind = upgradeInfo?.deploy_kind || ''
+      const deployKind = upgradeInfo?.deploy_kind
+        || (currentVersion && /\.dev\d*|\+/.test(currentVersion) ? 'dev' : '')
       const hasUpdate = Boolean(upgradeInfo?.has_update)
       const isDevDeployment = deployKind === 'dev'
+      const upgradeSource = upgradeInfo?.source || 'backend'
+      const mirrorCheck = upgradeSource === 'mirror'
+      const upgradeUnavailable = !upgradeInfo || upgradeInfo.reachable === false
       const releaseUrl = upgradeInfo?.release_url || ''
       const sourceRoot = versionInfo?.sourceRoot || deployState.sourceDir || ''
       const gitDirty = Boolean(versionData?.git?.dirty)
       const commitShort = versionData?.git?.commit_short || ''
       const upgradePhase = upgradeStatus?.phase || ''
+      const upgradeLogPath = upgradeStatus?.logPath || ''
       const upgradePhaseLabels = {
         idle: '空闲',
         starting: '准备中',
@@ -952,9 +959,11 @@ window.__ModuleLoader__.load({
           ? ['', versionBusy ? '读取中' : '未知']
           : isDevDeployment
             ? ['', '源码部署']
-            : hasUpdate
-              ? ['warn', '有新版本']
-              : ['ok', '已是最新']
+            : upgradeUnavailable
+              ? ['warn', '检查失败']
+              : hasUpdate
+                ? ['warn', '有新版本']
+                : ['ok', '已是最新']
 
       cards.push(h('div', { className: 'card', key: 'runtime' },
         h('div', { className: 'cardHead' },
@@ -1027,12 +1036,18 @@ window.__ModuleLoader__.load({
               latestVersion
                 ? h('span', null, `最新正式版 ${latestVersion}`)
                 : null,
+              mirrorCheck
+                ? h('span', {
+                  className: 'muted',
+                  title: 'GitHub 直连不可用，已通过镜像检查',
+                }, '镜像')
+                : null,
               releaseUrl
                 ? h('a', {
                   href: releaseUrl,
                   target: '_blank',
                   rel: 'noopener noreferrer',
-                  title: '在 GitHub 查看发布说明',
+                  title: '查看发布说明',
                 }, '发布页')
                 : null,
               isDevDeployment && devUpdateCommand
@@ -1050,6 +1065,12 @@ window.__ModuleLoader__.load({
                 disabled: versionBusy,
                 onClick: () => loadVersion(true),
               }, versionBusy ? '检查中…' : '检查更新'),
+              upgradeUnavailable
+                ? h('span', {
+                  className: 'versionDirty',
+                  title: upgradeInfo?.error || 'GitHub 与镜像均不可达',
+                }, '更新检查不可用')
+                : null,
               isDevDeployment && gitDirty
                 ? h('span', {
                   className: 'versionDirty',
@@ -1083,7 +1104,7 @@ window.__ModuleLoader__.load({
               }, '复制命令')))
           : null,
         upgradePhase === 'failed'
-          ? h('div', { className: 'muted versionNote' }, '上次升级失败，可查看 Miloco 的 upgrade.log 后重试。')
+          ? h('div', { className: 'muted versionNote' }, `上次升级失败${upgradeLogPath ? `，可查看 ${upgradeLogPath}` : '，可查看 Miloco 的 upgrade.log'} 后重试。`)
           : null,
         upgradeConfirmOpen
           ? h('div', { className: 'danger' },

package/lib/deploy.js

@@ -5,15 +5,15 @@
  * reach a backend it can:
  *
  * - start an already-installed Miloco (`miloco-cli service start`), or
- * - clone the upstream repository into a configurable directory and run its
- *   own installer (`scripts/install.sh --dev --skip-openclaw`).
+ * - download the official release installer and run it without OpenClaw
+ *   (`install.sh --skip-openclaw`), then install this package's adapter.
  *
- * It then installs this package's `agent_platform` adapter, points Miloco's
- * webhook at DSH, and writes the runtime overlay so the plugin can talk to the
- * new backend immediately.
+ * The release installer is downloaded directly from GitHub first and then
+ * through the configured mirrors. It is a self-contained script and downloads
+ * its own release assets through the mirrors embedded in its manifest.
  *
- * This module never vendors upstream code: the clone and install happen at
- * runtime, on the owner's machine, after an explicit button press.
+ * This module never vendors upstream code: the release installer download and
+ * install happen at runtime, on the owner's machine, after a button press.
  *
  * @module dsh-miloco-bridge/deploy
  */
@@ -21,11 +21,17 @@
 import { spawn } from 'node:child_process'
 import { randomBytes } from 'node:crypto'
 import { constants, existsSync } from 'node:fs'
-import { access, copyFile, mkdir, readFile, writeFile } from 'node:fs/promises'
+import { access, chmod, copyFile, mkdir, readFile, writeFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { readMilocoConfig } from './miloco-client.js'
+import {
+  DEFAULT_GITHUB_MIRRORS,
+  normalizeRepo,
+  releaseInstallerUrls,
+  viaMirror,
+} from './github-release.js'
 
 /** Upstream source repository used when no local checkout exists. */
 export const MILOCO_REPO = 'https://github.com/XiaoMi/xiaomi-miloco'
@@ -48,6 +54,46 @@ function expandHome(value) {
   return text
 }
 
+/**
+ * Mask credentials in command logs.
+ * @param {string[]} args - Command arguments.
+ * @returns {string[]} Arguments safe to log.
+ */
+export function redactCommandArgs(args) {
+  const out = [...args]
+  const secretFlags = new Set(['agent.auth_bearer', 'auth_bearer', '--token', '--bearer'])
+  for (let index = 0; index < out.length - 1; index += 1) {
+    if (secretFlags.has(out[index])) out[index + 1] = '<redacted>'
+  }
+  return out
+}
+
+/**
+ * Force release-installer arguments.
+ *
+ * The old source flow used `--dev`; a release installer rejects it. OpenClaw is
+ * used only to satisfy upstream platform detection, while `--skip-openclaw`
+ * prevents its plugin from being installed.
+ * @param {string[]} [raw] - Configured arguments.
+ * @returns {string[]} Safe release-installer arguments.
+ */
+function normalizeInstallArgs(raw) {
+  const args = Array.isArray(raw) ? raw.map(String) : []
+  const filtered = args.filter(arg =>
+    arg !== '--dev'
+    && !arg.startsWith('--dev=')
+    && !arg.startsWith('--agent-prepare')
+    && !arg.startsWith('--agent-finish'))
+  if (!filtered.includes('--skip-openclaw')) filtered.push('--skip-openclaw')
+  if (!filtered.some(arg => arg === '--agent-platform' || arg.startsWith('--agent-platform='))) {
+    filtered.push('--agent-platform=openclaw')
+  }
+  if (!filtered.some(arg => arg === '--lang' || arg.startsWith('--lang='))) {
+    filtered.push('--lang=zh')
+  }
+  return filtered
+}
+
 /**
  * Create a directory and prove the DSH process can write to it.
  * @param {string} dir - Directory path.
@@ -85,22 +131,45 @@ export function createDeployService(options) {
   )
   const milocoHome = expandHome(config.home || '~/.miloco')
   const repo = String(deployConfig.repo || MILOCO_REPO)
-  const installArgs = Array.isArray(deployConfig.installArgs) && deployConfig.installArgs.length
-    ? deployConfig.installArgs.map(String)
-    : ['--dev', '--skip-openclaw']
+  const githubMirrors = Array.isArray(deployConfig.githubMirrors) && deployConfig.githubMirrors.length
+    ? deployConfig.githubMirrors.map(String)
+    : DEFAULT_GITHUB_MIRRORS
+  const installArgs = normalizeInstallArgs(deployConfig.installArgs)
+  const repoUrl = `https://github.com/${normalizeRepo(repo)}`
+  const downloadSite = String(deployConfig.downloadSite || '').trim()
+    || (githubMirrors[0] ? viaMirror(githubMirrors[0], `${repoUrl}/releases/download`) : '')
+  const installEnv = {
+    UV_CACHE_DIR: join(milocoHome, '.uv-cache'),
+    UV_INDEX: String(deployConfig.uvIndex || 'https://pypi.org/simple'),
+    ...(downloadSite ? { MILOCO_DOWNLOAD_URL: downloadSite } : {}),
+  }
   const logPath = expandHome(deployConfig.logPath || join(milocoHome, 'log', 'dsh-miloco-deploy.log'))
+  const upgradeLogPath = expandHome(
+    deployConfig.upgradeLogPath || join(milocoHome, 'log', 'dsh-miloco-upgrade.log'),
+  )
 
   /** @type {{running: boolean, step: string, startedAt: string | null, exitCode: number | null}} */
   const state = { running: false, step: 'idle', startedAt: null, exitCode: null }
+  /** @type {{running: boolean, step: string, startedAt: string | null, exitCode: number | null}} */
+  const upgradeState = { running: false, step: 'idle', startedAt: null, exitCode: null }
+
+  /**
+   * Write a line into a log file.
+   * @param {string} path - Log path.
+   * @param {string} text - The line.
+   */
+  async function logTo(path, text) {
+    const stamp = new Date().toISOString().replace('T', ' ').slice(0, 19)
+    await mkdir(dirname(path), { recursive: true })
+    await writeFile(path, `[${stamp}] ${text}\n`, { flag: 'a' })
+  }
 
   /**
    * Write a line into the deployment log.
    * @param {string} text - The line.
    */
   async function logLine(text) {
-    const stamp = new Date().toISOString().replace('T', ' ').slice(0, 19)
-    await mkdir(dirname(logPath), { recursive: true })
-    await writeFile(logPath, `[${stamp}] ${text}\n`, { flag: 'a' })
+    return logTo(logPath, text)
   }
 
   /**
@@ -112,16 +181,27 @@ export function createDeployService(options) {
    */
   function run(command, args, extra = {}) {
     return new Promise(resolve => {
-      void logLine(`$ ${command} ${args.join(' ')}`)
+      const secrets = (extra.secrets ?? []).filter(Boolean)
+      const sanitize = value => secrets.reduce(
+        (text, secret) => text.split(secret).join('<redacted>'),
+        String(value),
+      )
+      const commandLog = extra.logPath || logPath
+      void logTo(commandLog, `$ ${command} ${redactCommandArgs(args).join(' ')}`)
       const child = spawn(command, args, {
         cwd: extra.cwd,
-        env: { ...process.env, MILOCO_HOME: milocoHome, ...(extra.env ?? {}) },
+        env: {
+          ...process.env,
+          PATH: [join(homedir(), '.local', 'bin'), process.env.PATH].filter(Boolean).join(':'),
+          MILOCO_HOME: milocoHome,
+          ...(extra.env ?? {}),
+        },
         stdio: ['ignore', 'pipe', 'pipe'],
       })
       const pump = stream => {
         stream.on('data', chunk => {
-          for (const line of String(chunk).split('\n')) {
-            if (line.trim() !== '') void logLine(line.trim())
+          for (const line of sanitize(chunk).split('\n')) {
+            if (line.trim() !== '') void logTo(commandLog, line.trim())
           }
         })
       }
@@ -191,6 +271,37 @@ export function createDeployService(options) {
     return false
   }
 
+  /**
+   * Download the self-contained official release installer.
+   * @returns {Promise<string>} Path to the installer script.
+   */
+  async function downloadReleaseInstaller(logTarget = logPath) {
+    const target = join(milocoHome, '.dsh-release-install.sh')
+    const urls = releaseInstallerUrls({ repo, mirrors: githubMirrors })
+    const failures = []
+    for (const url of urls) {
+      await logTo(logTarget, `downloading release installer: ${url}`)
+      try {
+        const response = await fetch(url, {
+          headers: { 'user-agent': 'dsh-miloco-bridge' },
+          redirect: 'follow',
+          signal: AbortSignal.timeout(30_000),
+        })
+        if (!response.ok) throw new Error(`HTTP ${response.status}`)
+        const text = await response.text()
+        if (!text.startsWith('#!')) throw new Error('响应不是 shell 安装脚本')
+        await writeFile(target, text, { encoding: 'utf8', mode: 0o700 })
+        await chmod(target, 0o700)
+        return target
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        failures.push(`${url}: ${message}`)
+        await logTo(logTarget, `download failed: ${message}`)
+      }
+    }
+    throw new Error(`无法下载 Miloco release 安装器：${failures.join('; ')}`)
+  }
+
   /**
    * Resolve the effective Miloco URL/token from `$MILOCO_HOME/config.json`.
    * @returns {Promise<{baseUrl: string, token: string}>} Connection settings.
@@ -244,10 +355,13 @@ export function createDeployService(options) {
   async function wireMiloco(opts) {
     const webhook = `${opts.origin}/miloco/webhook`
     if (opts.cli) {
-      await run(opts.cli, ['config', 'set', 'agent.platform', 'dsh'], { cwd: sourceDir })
-      await run(opts.cli, ['config', 'set', 'agent.webhook_url', webhook], { cwd: sourceDir })
-      await run(opts.cli, ['config', 'set', 'agent.auth_bearer', opts.token], { cwd: sourceDir })
-      await run(opts.cli, ['service', 'restart'], { cwd: sourceDir })
+      await run(opts.cli, ['config', 'set', 'agent.platform', 'dsh'], { cwd: milocoHome })
+      await run(opts.cli, ['config', 'set', 'agent.webhook_url', webhook], { cwd: milocoHome })
+      await run(opts.cli, ['config', 'set', 'agent.auth_bearer', opts.token], {
+        cwd: milocoHome,
+        secrets: [opts.token],
+      })
+      await run(opts.cli, ['service', 'restart'], { cwd: milocoHome })
     }
     if (options.overlay) {
       const current = await options.overlay.current()
@@ -279,7 +393,6 @@ export function createDeployService(options) {
     void (async () => {
       try {
         await ensureWritableDir(milocoHome, 'MILOCO_HOME')
-        await ensureWritableDir(dirname(sourceDir), 'deploy.sourceDir 的父目录')
         await logLine('=== dsh-miloco-bridge: 一键部署 Miloco 开始 ===')
 
         if (await healthy()) {
@@ -290,28 +403,28 @@ export function createDeployService(options) {
           if (cli && existsSync(join(milocoHome, 'config.json'))) {
             state.step = 'starting-existing'
             await logLine(`检测到已安装的 Miloco，尝试启动：${cli}`)
-            await run(cli, ['service', 'start'], { cwd: sourceDir })
+            await run(cli, ['service', 'start'], { cwd: milocoHome })
             await waitHealthy(DEFAULT_MILOCO_URL, 45_000)
           }
 
           if (!await healthy()) {
-            state.step = 'preparing-source'
-            if (!existsSync(join(sourceDir, 'scripts', 'install.sh'))) {
-              if (!/^https:\/\//i.test(repo)) {
-                throw new Error('deploy.repo 必须是 https:// 地址')
-              }
-              await mkdir(dirname(sourceDir), { recursive: true })
-              await logLine(`cloning ${repo} -> ${sourceDir}`)
-              const clone = await run('git', ['clone', '--depth', '1', repo, sourceDir], { cwd: homedir() })
-              if (clone !== 0) throw new Error(`git clone 失败（exit ${clone}）`)
-            }
+            state.step = 'downloading-installer'
+            const installer = await downloadReleaseInstaller()
             state.step = 'installing'
-            const install = await run('bash', ['scripts/install.sh', ...installArgs], { cwd: sourceDir })
-            if (install !== 0) throw new Error(`Miloco 安装器返回 ${install}`)
+            const prepare = await run('bash', [installer, '--agent-prepare', ...installArgs], {
+              cwd: milocoHome,
+              env: installEnv,
+            })
+            if (prepare !== 0) throw new Error(`Miloco release 安装器 prepare 返回 ${prepare}`)
+            const finish = await run('bash', [installer, '--agent-finish', ...installArgs], {
+              cwd: milocoHome,
+              env: installEnv,
+            })
+            if (finish !== 0) throw new Error(`Miloco release 安装器 finish 返回 ${finish}`)
             state.step = 'starting-service'
             const cliAfter = await findMilocoCli()
-            if (cliAfter) await run(cliAfter, ['service', 'start'], { cwd: sourceDir })
-            if (!await waitHealthy(DEFAULT_MILOCO_URL, 90_000)) {
+            if (cliAfter) await run(cliAfter, ['service', 'start'], { cwd: milocoHome })
+            if (!await waitHealthy(DEFAULT_MILOCO_URL, 120_000)) {
               throw new Error('Miloco 安装完成但没有在 127.0.0.1:1810 上响应')
             }
           }
@@ -346,6 +459,88 @@ export function createDeployService(options) {
     return { started: true, logPath }
   }
 
+  /**
+   * Run a mirror-backed upgrade through the same release installer as deploy.
+   * @param {{origin?: string}} [opts] - Request origin.
+   * @returns {Promise<{started: boolean, reason?: string, logPath?: string}>} Outcome.
+   */
+  async function startUpgrade(opts = {}) {
+    if (upgradeState.running) {
+      return { started: false, reason: 'already-running', logPath: upgradeLogPath }
+    }
+    if (state.running) {
+      return { started: false, reason: 'deploy-running', logPath: upgradeLogPath }
+    }
+    upgradeState.running = true
+    upgradeState.step = 'starting'
+    upgradeState.startedAt = new Date().toISOString()
+    upgradeState.exitCode = null
+    const origin = String(opts.origin || '').replace(/\/+$/, '') || 'http://127.0.0.1:3080'
+
+    void (async () => {
+      try {
+        await ensureWritableDir(milocoHome, 'MILOCO_HOME')
+        await logTo(upgradeLogPath, '=== Miloco 升级开始 ===')
+        upgradeState.step = 'downloading-installer'
+        const installer = await downloadReleaseInstaller(upgradeLogPath)
+        upgradeState.step = 'installing'
+        const installOpts = { cwd: milocoHome, env: installEnv, logPath: upgradeLogPath }
+        const prepare = await run('bash', [installer, '--agent-prepare', ...installArgs], installOpts)
+        if (prepare !== 0) throw new Error(`Miloco release 安装器 prepare 返回 ${prepare}`)
+        const finish = await run('bash', [installer, '--agent-finish', ...installArgs], installOpts)
+        if (finish !== 0) throw new Error(`Miloco release 安装器 finish 返回 ${finish}`)
+        upgradeState.step = 'starting-service'
+        const cli = await findMilocoCli()
+        if (cli) {
+          await run(cli, ['service', 'start'], { cwd: milocoHome, logPath: upgradeLogPath })
+        }
+        if (!await waitHealthy(DEFAULT_MILOCO_URL, 120_000)) {
+          throw new Error('Miloco 升级后没有在 127.0.0.1:1810 上响应')
+        }
+        upgradeState.step = 'wiring'
+        const connection = await localConnection()
+        const fileConfig = await readMilocoConfig(milocoHome)
+        const existingToken = String(fileConfig?.agent?.auth_bearer ?? '').trim()
+        const pushToken = existingToken || randomBytes(32).toString('base64url')
+        await installAdapter({ origin, token: pushToken })
+        await wireMiloco({ cli, origin, token: pushToken, connection })
+        upgradeState.step = 'done'
+        upgradeState.exitCode = 0
+        await logTo(upgradeLogPath, '=== 升级完成 ===')
+      } catch (error) {
+        upgradeState.step = 'failed'
+        upgradeState.exitCode = 1
+        await logTo(upgradeLogPath, `升级异常：${error instanceof Error ? error.message : String(error)}`)
+      } finally {
+        upgradeState.running = false
+      }
+    })()
+
+    return { started: true, logPath: upgradeLogPath }
+  }
+
+  /**
+   * @returns {any} Upgrade state for the settings API.
+   */
+  function upgradeStateView() {
+    return { ...upgradeState, logPath: upgradeLogPath, milocoHome }
+  }
+
+  /**
+   * Read the tail of the upgrade log.
+   * @param {number} [lines] - Number of trailing lines.
+   * @returns {Promise<string>} The log tail.
+   */
+  async function upgradeTail(lines = 60) {
+    try {
+      const text = await readFile(upgradeLogPath, 'utf8')
+      const all = text.split('\n').filter(line => line.trim() !== '')
+      return all.slice(-lines).join('\n')
+    } catch {
+      return ''
+    }
+  }
+
   /**
    * Read the tail of the deployment log.
    * @param {number} [lines] - Number of trailing lines.
@@ -371,5 +566,8 @@ export function createDeployService(options) {
     }),
     tail,
     start,
+    upgradeState: upgradeStateView,
+    upgradeTail,
+    startUpgrade,
   }
 }

package/lib/github-release.js

@@ -0,0 +1,162 @@
+/**
+ * GitHub release lookup with mirror fallback.
+ *
+ * Miloco only publishes on GitHub. Direct GitHub access is preferred; when it
+ * is unavailable, the same API/installer URLs are requested through public
+ * pull-through mirrors.
+ *
+ * @module dsh-miloco-bridge/github-release
+ */
+
+export const DEFAULT_GITHUB_REPO = 'XiaoMi/xiaomi-miloco'
+export const DEFAULT_GITHUB_API = 'https://api.github.com'
+export const DEFAULT_GITHUB_MIRRORS = [
+  'https://gh-proxy.com/',
+  'https://gh-proxy.org/',
+]
+
+/**
+ * Normalise an owner/repo or GitHub URL to `owner/repo`.
+ * @param {string} [repo] - Repository URL or slug.
+ * @returns {string} Repository slug.
+ */
+export function normalizeRepo(repo) {
+  const text = String(repo ?? '').trim().replace(/\/+$/, '').replace(/\.git$/i, '')
+  const match = /^(?:https?:\/\/github\.com\/)?([^/\s]+\/[^/\s]+)$/i.exec(text)
+  return match ? match[1] : DEFAULT_GITHUB_REPO
+}
+
+/**
+ * Prefix a URL with a mirror, or expand a `{url}` template.
+ * @param {string} mirror - Mirror base or template.
+ * @param {string} url - Original URL.
+ * @returns {string} Mirrored URL.
+ */
+export function viaMirror(mirror, url) {
+  const base = String(mirror ?? '').trim()
+  if (!base) return url
+  if (base.includes('{url}')) return base.replaceAll('{url}', url)
+  return `${base.replace(/\/+$/, '')}/${url}`
+}
+
+/**
+ * Build direct + mirrored URLs for the latest-release API.
+ * @param {{repo?: string, apiBase?: string, mirrors?: string[]}} [opts] - Options.
+ * @returns {string[]} Candidate URLs, direct first.
+ */
+export function releaseApiUrls(opts = {}) {
+  const repo = normalizeRepo(opts.repo)
+  const apiBase = String(opts.apiBase || DEFAULT_GITHUB_API).replace(/\/+$/, '')
+  const direct = `${apiBase}/repos/${repo}/releases/latest`
+  const mirrors = (opts.mirrors ?? DEFAULT_GITHUB_MIRRORS).map(mirror => viaMirror(mirror, direct))
+  return [...new Set([direct, ...mirrors])]
+}
+
+/**
+ * Build direct + mirrored URLs for the release installer script.
+ * @param {{repo?: string, mirrors?: string[]}} [opts] - Options.
+ * @returns {string[]} Candidate URLs, direct first.
+ */
+export function releaseInstallerUrls(opts = {}) {
+  const repo = normalizeRepo(opts.repo)
+  const direct = `https://github.com/${repo}/releases/latest/download/install.sh`
+  const mirrors = (opts.mirrors ?? DEFAULT_GITHUB_MIRRORS).map(mirror => viaMirror(mirror, direct))
+  return [...new Set([direct, ...mirrors])]
+}
+
+/**
+ * Fetch the latest release, trying direct GitHub then mirrors.
+ * @param {{repo?: string, apiBase?: string, mirrors?: string[], timeoutMs?: number, fetchImpl?: typeof fetch}} [opts] - Options.
+ * @returns {Promise<{tag: string, html_url: string, source: 'github'|'mirror', mirror: string|null, release_url: string, request_url: string}>} Latest release.
+ */
+export async function fetchLatestRelease(opts = {}) {
+  const doFetch = opts.fetchImpl ?? fetch
+  const timeoutMs = Number.isFinite(opts.timeoutMs) && opts.timeoutMs > 0 ? opts.timeoutMs : 6_000
+  const urls = releaseApiUrls(opts)
+  const errors = []
+  for (const [index, url] of urls.entries()) {
+    try {
+      const response = await doFetch(url, {
+        headers: {
+          accept: 'application/vnd.github+json',
+          'user-agent': 'dsh-miloco-bridge',
+        },
+        redirect: 'follow',
+        signal: AbortSignal.timeout(timeoutMs),
+      })
+      if (!response.ok) throw new Error(`HTTP ${response.status}`)
+      const body = await response.json()
+      const tag = String(body?.tag_name ?? '').trim()
+      if (!tag) throw new Error('响应缺少 tag_name')
+      const htmlUrl = String(body?.html_url ?? '').trim()
+      const mirrored = index > 0
+      const mirror = mirrored ? (opts.mirrors ?? DEFAULT_GITHUB_MIRRORS)[index - 1] : null
+      return {
+        tag,
+        html_url: htmlUrl,
+        source: mirrored ? 'mirror' : 'github',
+        mirror,
+        release_url: mirrored && htmlUrl ? viaMirror(mirror, htmlUrl) : htmlUrl,
+        request_url: url,
+      }
+    } catch (error) {
+      errors.push(`${url}: ${error instanceof Error ? error.message : String(error)}`)
+    }
+  }
+  throw new Error(`最新版本查询失败：${errors.join('; ')}`)
+}
+
+/**
+ * Parse a CalVer/PEP440-style release string.
+ * @param {string} value - Version string.
+ * @returns {{parts: number[], post: number, dev: number|null}|null} Parsed version.
+ */
+export function parseReleaseVersion(value) {
+  const text = String(value ?? '').trim().replace(/^v/i, '').split('+')[0]
+  const match = /^(\d+(?:\.\d+)*)(?:\.post(\d+))?(?:\.dev(\d+))?$/.exec(text)
+  if (!match) return null
+  return {
+    parts: match[1].split('.').map(Number),
+    post: Number(match[2] ?? 0),
+    dev: match[3] === undefined ? null : Number(match[3]),
+  }
+}
+
+/**
+ * Normalise a release tag for display.
+ * @param {string} value - Tag or version.
+ * @returns {string} Version without a leading `v`.
+ */
+export function normalizeReleaseVersion(value) {
+  return String(value ?? '').trim().replace(/^v/i, '')
+}
+
+/**
+ * Whether `latest` is strictly newer than `current`.
+ * Dev builds and unparseable versions are treated conservatively as "no update".
+ * @param {string} current - Current version.
+ * @param {string} latest - Latest release tag.
+ * @returns {boolean} Whether an update is available.
+ */
+export function isNewerRelease(current, latest) {
+  const left = parseReleaseVersion(current)
+  const right = parseReleaseVersion(latest)
+  if (!left || !right) return false
+  if (left.dev !== null) return false
+  const length = Math.max(left.parts.length, right.parts.length)
+  for (let index = 0; index < length; index += 1) {
+    const a = left.parts[index] ?? 0
+    const b = right.parts[index] ?? 0
+    if (b !== a) return b > a
+  }
+  return right.post > left.post
+}
+
+/**
+ * Infer release/dev deployment kind from a package version.
+ * @param {string} version - Package version.
+ * @returns {'release'|'dev'} Deployment kind.
+ */
+export function inferDeployKind(version) {
+  return /\.dev\d*|\+/.test(String(version ?? '')) ? 'dev' : 'release'
+}

package/lib/index.js

@@ -96,7 +96,17 @@ export function normalizeConfig(raw) {
         : join(resolveDshHome(), 'plugin-data', 'dsh-miloco-bridge', 'xiaomi-miloco'),
       installArgs: Array.isArray(deployRaw.installArgs)
         ? deployRaw.installArgs.map(String)
-        : ['--dev', '--skip-openclaw'],
+        : ['--skip-openclaw', '--agent-platform=openclaw', '--lang=zh'],
+      githubMirrors: Array.isArray(deployRaw.githubMirrors)
+        ? deployRaw.githubMirrors.map(String).filter(Boolean)
+        : ['https://gh-proxy.com/', 'https://gh-proxy.org/'],
+      githubApi: typeof deployRaw.githubApi === 'string' && deployRaw.githubApi
+        ? deployRaw.githubApi
+        : 'https://api.github.com',
+      downloadSite: typeof deployRaw.downloadSite === 'string' ? deployRaw.downloadSite : '',
+      uvIndex: typeof deployRaw.uvIndex === 'string' && deployRaw.uvIndex
+        ? deployRaw.uvIndex
+        : 'https://pypi.org/simple',
       logPath: typeof deployRaw.logPath === 'string' ? deployRaw.logPath : '',
     },
   }

package/lib/settings-api.js

@@ -22,6 +22,7 @@
 
 import { access } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
+import { fetchLatestRelease, inferDeployKind, isNewerRelease, normalizeReleaseVersion } from './github-release.js'
 import { MilocoError, readMilocoConfig } from './miloco-client.js'
 import { normalizePerceptionLevel, PERCEPTION_LEVELS } from './perception.js'
 import { AGENT_MODES, describeMode, readSessions } from './state.js'
@@ -212,6 +213,8 @@ export function registerSettingsApi(options) {
   const { ctx, config, client, overlay } = options
   const log = options.logger ?? ctx.logger
   const disposers = []
+  /** @type {null | {at: number, source: string, has_update: boolean, current: string, latest: string}} */
+  let lastUpgradeCheck = null
 
   /**
    * Register one exact route.
@@ -485,7 +488,7 @@ export function registerSettingsApi(options) {
       : (config.deploy?.sourceDir || '')
 
     try {
-      const [version, upgrade, upgradeStatus] = await Promise.all([
+      const [version, backendUpgrade, upgradeStatus] = await Promise.all([
         client.get('/api/admin/version', { signal: AbortSignal.timeout(8_000) }),
         client.get('/api/admin/upgrade/check', {
           query: { force: force ? 'true' : 'false' },
@@ -493,6 +496,55 @@ export function registerSettingsApi(options) {
         }).catch(() => null),
         client.get('/api/admin/upgrade/status', { signal: AbortSignal.timeout(8_000) }).catch(() => null),
       ])
+      let upgrade = backendUpgrade
+      if (!upgrade || upgrade.reachable === false) {
+        const current = String(upgrade?.current || version?.version || '')
+        const deployKind = upgrade?.deploy_kind || inferDeployKind(current)
+        try {
+          const latest = await fetchLatestRelease({
+            repo: config.deploy?.repo,
+            apiBase: config.deploy?.githubApi,
+            mirrors: config.deploy?.githubMirrors,
+            timeoutMs: 6_000,
+          })
+          upgrade = {
+            current,
+            latest: normalizeReleaseVersion(latest.tag),
+            has_update: Boolean(current) && deployKind === 'release'
+              && isNewerRelease(current, latest.tag),
+            deploy_kind: deployKind,
+            release_url: latest.release_url || latest.html_url,
+            reachable: true,
+            source: latest.source,
+            mirror: latest.mirror || null,
+            checked_at: Math.floor(Date.now() / 1000),
+          }
+        } catch (fallbackError) {
+          const message = fallbackError instanceof Error ? fallbackError.message : String(fallbackError)
+          upgrade = {
+            ...(upgrade ?? {}),
+            current,
+            latest: null,
+            has_update: false,
+            deploy_kind: deployKind,
+            release_url: null,
+            reachable: false,
+            source: 'none',
+            error: message,
+          }
+        }
+      } else {
+        upgrade = { ...upgrade, source: upgrade.source || 'backend' }
+      }
+      if (upgrade) {
+        lastUpgradeCheck = {
+          at: Date.now(),
+          source: upgrade.source || 'backend',
+          has_update: Boolean(upgrade.has_update),
+          current: String(upgrade.current || ''),
+          latest: String(upgrade.latest || ''),
+        }
+      }
       sendJson(res, 200, {
         ok: true,
         reachable: true,
@@ -521,6 +573,24 @@ export function registerSettingsApi(options) {
     }
     const body = await mutateBody(req, res)
     if (body === null) return
+    const recent = lastUpgradeCheck && Date.now() - lastUpgradeCheck.at < 10 * 60_000
+    const pluginUpgrade = recent
+      && lastUpgradeCheck.source !== 'backend'
+      && lastUpgradeCheck.has_update
+      && typeof options.deploy?.startUpgrade === 'function'
+    if (pluginUpgrade) {
+      const proto = String(req.headers['x-forwarded-proto'] || 'http').split(',')[0].trim()
+      const origin = typeof req.headers.origin === 'string' && req.headers.origin
+        ? req.headers.origin
+        : `${proto}://${req.headers.host ?? '127.0.0.1:3080'}`
+      const outcome = await options.deploy.startUpgrade({ origin })
+      if (!outcome.started) {
+        sendJson(res, 409, { ok: false, error: outcome.reason || '升级未启动', ...outcome })
+        return
+      }
+      sendJson(res, 200, { ok: true, source: 'plugin', ...outcome })
+      return
+    }
     // Upstream only allows /upgrade/run for release deployments. It performs
     // its own has_update check; surface its 400 reason verbatim.
     try {
@@ -541,6 +611,20 @@ export function registerSettingsApi(options) {
       sendJson(res, 405, { ok: false, error: 'method not allowed' })
       return
     }
+    const pluginState = options.deploy?.upgradeState?.()
+    if (pluginState && pluginState.step !== 'idle') {
+      const phaseMap = {
+        'downloading-installer': 'downloading',
+        'starting-service': 'restarting',
+        wiring: 'installing',
+      }
+      sendJson(res, 200, {
+        ok: true,
+        source: 'plugin',
+        status: { ...pluginState, phase: phaseMap[pluginState.step] || pluginState.step },
+      })
+      return
+    }
     try {
       const status = await client.get('/api/admin/upgrade/status', {
         signal: AbortSignal.timeout(8_000),

package/lib/tools.js

@@ -23,6 +23,16 @@ import { MilocoError } from './miloco-client.js'
 import { PERCEPTION_LEVELS } from './perception.js'
 import { noteSession } from './state.js'
 
+/** Extra device fields that callers may request explicitly. */
+const DEVICE_LIST_EXTRA_FIELDS = [
+  'icon',
+  'local_ip',
+  'home_name',
+  'order_time',
+  'lan_online',
+  'sub_devices',
+]
+
 /**
  * Serialise a canonical tool value as readable JSON text.
  * @param {unknown} value - Value to serialise.
@@ -134,15 +144,63 @@ export function createMilocoTools(options) {
 
   tools.push(defineMilocoTool({
     name: 'miloco_device_list',
-    description: '列出米家设备（did、名称、在线状态、所属房间、设备类型）。要控制某台设备前，先用本工具拿到 did。',
+    description: '列出米家设备。默认返回 did、名称、在线状态、房间、型号和 home_id；'
+      + '可用 include 显式取回 icon/local_ip 等额外字段。默认最多 500 台，超过时用 offset 翻页。',
     parameters: {
-      room: { type: 'string', description: '按房间名过滤（本地匹配 room_name），留空返回全部设备' },
+      room: { type: 'string', description: '按房间名过滤（本地匹配 room_name）' },
+      name: { type: 'string', description: '按设备名过滤（本地子串匹配，忽略大小写）' },
+      online_only: { type: 'boolean', description: '只返回在线设备' },
+      limit: {
+        type: 'integer',
+        minimum: 1,
+        maximum: 500,
+        description: '最多返回多少台，默认 500',
+      },
+      offset: { type: 'integer', minimum: 0, description: '从第几台开始，默认 0' },
+      include: {
+        type: 'array',
+        items: { type: 'string', enum: DEVICE_LIST_EXTRA_FIELDS },
+        description: '额外字段：icon / local_ip / home_name / order_time / lan_online / sub_devices',
+      },
     },
     async run(args, exec) {
       const devices = await call('GET', '/api/miot/device_list', { signal: exec?.signal })
+      const list = Array.isArray(devices) ? devices : []
       const room = typeof args.room === 'string' ? args.room.trim().toLowerCase() : ''
-      if (!room || !Array.isArray(devices)) return devices
-      return devices.filter((device) => String(device?.room_name ?? device?.room ?? '').toLowerCase().includes(room))
+      const name = typeof args.name === 'string' ? args.name.trim().toLowerCase() : ''
+      const onlineOnly = args.online_only === true
+      const includes = Array.isArray(args.include)
+        ? [...new Set(args.include.filter(field => typeof field === 'string'))]
+        : []
+      for (const field of includes) {
+        if (!DEVICE_LIST_EXTRA_FIELDS.includes(field)) throw new Error(`include 不支持字段：${field}`)
+      }
+      const limit = args.limit === undefined ? 500 : Number(args.limit)
+      const offset = args.offset === undefined ? 0 : Number(args.offset)
+      if (!Number.isInteger(limit) || limit < 1 || limit > 500) throw new Error('limit 必须是 1~500 的整数')
+      if (!Number.isInteger(offset) || offset < 0) throw new Error('offset 必须是非负整数')
+      const filtered = list.filter((device) => {
+        if (!device || typeof device !== 'object') return false
+        if (onlineOnly && device.online !== true) return false
+        if (room && !String(device.room_name ?? device.room ?? '').toLowerCase().includes(room)) return false
+        if (name && !String(device.name ?? '').toLowerCase().includes(name)) return false
+        return true
+      })
+      const page = filtered.slice(offset, offset + limit).map((device) => {
+        const row = {
+          did: device.did ?? '',
+          name: device.name ?? '',
+          online: device.online === true,
+          room_name: device.room_name ?? '',
+          model: device.model ?? '',
+          home_id: device.home_id ?? '',
+        }
+        for (const field of includes) {
+          if (Object.prototype.hasOwnProperty.call(device, field)) row[field] = device[field]
+        }
+        return row
+      })
+      return { total: filtered.length, returned: page.length, offset, limit, devices: page }
     },
   }))
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-miloco-bridge",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Unofficial DSH bridge for Xiaomi Miloco: an isolated Agent preset for Miloco tools, native tools/skills, Web settings, perception-priority filtering, and Miloco -> DSH push.",
   "keywords": [
     "dsh",

package/skills/miloco-devices/SKILL.md

@@ -12,7 +12,7 @@ whenToUse: 用户说“开/关/调/查某台设备”“客厅多少度”“执
 
 | 目的 | 工具 |
 |---|---|
-| 找设备 did | `miloco_device_list(room?)` |
+| 找设备 did | `miloco_device_list(room?, online_only?, name?, include?)` |
 | 读 SPEC / iid | `miloco_device_spec(did)` |
 | 读当前属性 | `miloco_device_status(did, iid?)` |
 | 控制设备（写） | `miloco_device_control(...)` |
@@ -21,7 +21,7 @@ whenToUse: 用户说“开/关/调/查某台设备”“客厅多少度”“执
 
 ## 查询流程
 
-1. `miloco_device_list` 拿 did。名字相同或跨房间时先缩小范围，不猜。
+1. `miloco_device_list` 拿 did（结果在 `devices` 数组里）。名字相同或跨房间时用 `name` / `room` / `online_only` 先缩小范围，不猜。
 2. `miloco_device_status` 读状态。传 `iid` 读单项，不传读全部。
 3. 回答里带上设备名、房间、关键数值和时间（若后端返回）。
 
@@ -42,6 +42,7 @@ whenToUse: 用户说“开/关/调/查某台设备”“客厅多少度”“执
 - 门锁、燃气阀、摄像头开关、厨房电器等有物理风险的操作，先说明将要做什么并取得确认。
 - 不要把“感知事件里的 did”当成控制目标：事件 did 通常是摄像头/传感器。
 - 不确定设备是否存在时重新 `miloco_device_list` 或 `miloco_home_info(refresh=true)`，禁止编造 did。
+- 需要 `icon`、`local_ip` 等默认裁剪字段时，用 `include=[...]` 显式请求，不要为了一个字段重拉全量原始对象。
 
 ## 场景