dsh-miloco-bridge 0.1.0 → 0.1.1

package/lib/settings-api.js

@@ -21,7 +21,7 @@
  */
 
 import { access } from 'node:fs/promises'
-import { join } from 'node:path'
+import { dirname, join } from 'node:path'
 import { MilocoError, readMilocoConfig } from './miloco-client.js'
 import { normalizePerceptionLevel, PERCEPTION_LEVELS } from './perception.js'
 import { AGENT_MODES, describeMode, readSessions } from './state.js'
@@ -470,6 +470,91 @@ export function registerSettingsApi(options) {
     })
   })
 
+  route(`${SETTINGS_PREFIX}/version`, async (req, res) => {
+    if (req.method !== 'GET') {
+      sendJson(res, 405, { ok: false, error: 'method not allowed' })
+      return
+    }
+    const force = new URL(req.url, 'http://127.0.0.1').searchParams.get('refresh') === '1'
+    const endpoint = await client.endpoint()
+    const fileConfig = await readMilocoConfig(endpoint.home)
+    const pythonBin = String(fileConfig?.server?.python_bin ?? '')
+    // server.python_bin = <source>/backend/.venv/bin/python
+    const sourceRoot = pythonBin
+      ? dirname(dirname(dirname(dirname(pythonBin))))
+      : (config.deploy?.sourceDir || '')
+
+    try {
+      const [version, upgrade, 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' },
+          signal: AbortSignal.timeout(15_000),
+        }).catch(() => null),
+        client.get('/api/admin/upgrade/status', { signal: AbortSignal.timeout(8_000) }).catch(() => null),
+      ])
+      sendJson(res, 200, {
+        ok: true,
+        reachable: true,
+        sourceRoot,
+        version,
+        upgrade,
+        upgradeStatus,
+      })
+    } catch (error) {
+      sendJson(res, 200, {
+        ok: true,
+        reachable: false,
+        sourceRoot,
+        error: error instanceof MilocoError ? error.message : String(error),
+        version: null,
+        upgrade: null,
+        upgradeStatus: null,
+      })
+    }
+  })
+
+  route(`${SETTINGS_PREFIX}/upgrade`, async (req, res) => {
+    if (req.method !== 'POST') {
+      sendJson(res, 405, { ok: false, error: 'method not allowed' })
+      return
+    }
+    const body = await mutateBody(req, res)
+    if (body === null) return
+    // Upstream only allows /upgrade/run for release deployments. It performs
+    // its own has_update check; surface its 400 reason verbatim.
+    try {
+      const data = await client.post('/api/admin/upgrade/run', undefined, {
+        signal: AbortSignal.timeout(30_000),
+      })
+      sendJson(res, 200, { ok: true, data })
+    } catch (error) {
+      sendJson(res, 400, {
+        ok: false,
+        error: error instanceof MilocoError ? error.message : String(error),
+      })
+    }
+  })
+
+  route(`${SETTINGS_PREFIX}/upgrade/status`, async (req, res) => {
+    if (req.method !== 'GET') {
+      sendJson(res, 405, { ok: false, error: 'method not allowed' })
+      return
+    }
+    try {
+      const status = await client.get('/api/admin/upgrade/status', {
+        signal: AbortSignal.timeout(8_000),
+      })
+      sendJson(res, 200, { ok: true, status })
+    } catch (error) {
+      sendJson(res, 200, {
+        ok: true,
+        status: null,
+        error: error instanceof MilocoError ? error.message : String(error),
+      })
+    }
+  })
+
   route(`${SETTINGS_PREFIX}/deploy`, async (req, res) => {
     if (!options.deploy) {
       sendJson(res, 503, { ok: false, error: '部署功能未启用' })

package/lib/tools.js

@@ -136,13 +136,13 @@ export function createMilocoTools(options) {
     name: 'miloco_device_list',
     description: '列出米家设备（did、名称、在线状态、所属房间、设备类型）。要控制某台设备前，先用本工具拿到 did。',
     parameters: {
-      room: { type: 'string', description: '按房间名过滤，留空返回全部设备' },
+      room: { type: 'string', description: '按房间名过滤（本地匹配 room_name），留空返回全部设备' },
     },
     async run(args, exec) {
-      return call('GET', '/api/miot/device_list', {
-        query: args.room ? { room: args.room } : undefined,
-        signal: exec?.signal,
-      })
+      const devices = await call('GET', '/api/miot/device_list', { signal: exec?.signal })
+      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))
     },
   }))
 
@@ -540,6 +540,20 @@ export function createMilocoTools(options) {
 
   const writeTools = []
 
+  const ruleActionSchema = {
+    type: 'object',
+    properties: {
+      did: { type: 'string', description: '设备 did；触发场景时填 scene_id' },
+      iid: { type: 'string', description: 'prop.{siid}.{piid} / action.{siid}.{aiid} / scene' },
+      value: { description: '属性目标值（iid 为 prop.* 时使用）' },
+      params: { type: 'array', items: { type: 'string' }, description: '动作参数（iid 为 action.* 时使用）' },
+      idempotent: { type: 'boolean', description: '默认 true；false 时必须提供 cooldown_minutes' },
+      cooldown_minutes: { type: 'integer', minimum: 0, description: '非幂等动作的去重冷却时间（分钟）' },
+    },
+    required: ['did', 'iid'],
+    additionalProperties: false,
+  }
+
   writeTools.push(defineMilocoTool({
     name: 'miloco_device_control',
     description: '控制米家设备：设置属性（开关、调温、调亮度、开合窗帘）或调用动作。'
@@ -549,7 +563,11 @@ export function createMilocoTools(options) {
       did: { type: 'string', description: '设备 did' },
       iid: { type: 'string', description: '属性 iid（set_property）或动作 iid（call_action）' },
       value: { type: 'string', description: '目标值；字符串会按属性类型转成布尔/数字' },
-      type: { type: 'string', description: '控制类型：set_property（默认）/ set_properties / call_action' },
+      type: {
+        type: 'string',
+        enum: ['set_property', 'set_properties', 'call_action'],
+        description: '控制类型：set_property（默认）/ set_properties / call_action',
+      },
       properties: {
         type: 'array',
         description: '一次设置多个属性时使用',
@@ -573,6 +591,9 @@ export function createMilocoTools(options) {
     async run(args, exec) {
       const did = requireString(args, 'did')
       const type = args.type ?? 'set_property'
+      if (!['set_property', 'set_properties', 'call_action'].includes(type)) {
+        throw new Error('type 只能是 set_property / set_properties / call_action')
+      }
       const body = { type }
       if (type === 'set_properties') {
         if (!Array.isArray(args.properties) || args.properties.length === 0) {
@@ -619,46 +640,238 @@ export function createMilocoTools(options) {
 
   writeTools.push(defineMilocoTool({
     name: 'miloco_rule_create',
-    description: '创建一条自动化规则。推荐用自然语言描述"当 X 时做 Y"，由后端的大模型翻译成条件与动作；'
-      + '也可以直接给结构化的 condition/actions。',
+    description: '创建一条结构化自动化规则。condition 指定感知设备与自然语言条件；'
+      + 'event 模式用 actions（设备直控）或 action_descriptions（Agent 回调），'
+      + 'state 模式用 on_enter_* / on_exit_*。task_id 必须是已存在的长期任务。',
     parameters: {
-      content: { type: 'string', description: '自然语言规则描述，例如"晚上 22 点客厅灯打开"' },
       name: { type: 'string', description: '规则名称' },
-      mode: { type: 'string', description: 'event（默认）/ state' },
-    },
+      task_id: { type: 'string', description: '关联的任务 id（snake_case，需先创建）' },
+      condition: {
+        type: 'object',
+        description: '触发条件：感知设备列表（OR 语义）+ 自然语言描述',
+        properties: {
+          perceive_device_ids: {
+            type: 'array',
+            items: { type: 'string' },
+            description: '参与判断的感知设备 did 列表',
+          },
+          query: { type: 'string', description: '要识别的自然语言条件' },
+        },
+        required: ['perceive_device_ids', 'query'],
+        additionalProperties: false,
+      },
+      mode: { type: 'string', enum: ['event', 'state'], description: 'event（默认）/ state' },
+      direction: {
+        type: 'string',
+        enum: ['enter', 'exit', 'session', 'milestone', 'guard'],
+        description: '可选；提供后优先于 mode，用于表达 exit/session/milestone/guard 语义',
+      },
+      lifecycle: { type: 'string', enum: ['permanent', 'temporary'], description: '默认 permanent' },
+      enabled: { type: 'boolean', description: '是否启用，默认 true' },
+      actions: {
+        type: 'array',
+        items: ruleActionSchema,
+        description: 'event 模式的设备直控动作',
+      },
+      action_descriptions: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'event 模式下投递给 Agent 的回调提示文本',
+      },
+      on_enter_actions: {
+        type: 'array',
+        items: ruleActionSchema,
+        description: 'state 模式进入时的设备直控动作',
+      },
+      on_enter_desc: { type: 'string', description: 'state 模式进入时投递给 Agent 的文本' },
+      on_exit_actions: {
+        type: 'array',
+        items: ruleActionSchema,
+        description: 'state 模式退出时的设备直控动作',
+      },
+      on_exit_desc: { type: 'string', description: 'state 模式退出时投递给 Agent 的文本' },
+      on_target_desc: { type: 'string', description: 'duration record 达标瞬间投递的文本' },
+      terminate_when: { type: 'string', description: 'lifecycle=temporary 时的自然语言终止条件' },
+      exit_debounce_seconds: { type: 'integer', minimum: 0, description: 'state 模式退出防抖秒数' },
+      duration_seconds: { type: 'integer', minimum: 1, description: '累计统计窗口（秒）' },
+      duration_ratio: { type: 'number', exclusiveMinimum: 0, maximum: 1, description: '窗口内 True 比例阈值' },
+    },
+    required: ['name', 'task_id', 'condition'],
     async run(args, exec) {
-      const body = {}
-      if (args.content) body.content = requireString(args, 'content')
-      if (args.name) body.name = args.name
-      if (args.mode) body.mode = args.mode
-      if (Object.keys(body).length === 0) throw new Error('至少提供 content 或 name')
+      const name = requireString(args, 'name')
+      const taskId = requireString(args, 'task_id')
+      if (!/^[a-z0-9_]{1,32}$/.test(taskId)) {
+        throw new Error('task_id 必须匹配 [a-z0-9_]{1,32}（只能用小写字母、数字、下划线）')
+      }
+      const condition = args.condition
+      if (!condition || typeof condition !== 'object') throw new Error('缺少参数 condition')
+      const deviceIds = Array.isArray(condition.perceive_device_ids)
+        ? condition.perceive_device_ids.filter(id => typeof id === 'string' && id)
+        : []
+      const query = typeof condition.query === 'string' ? condition.query.trim() : ''
+      if (deviceIds.length === 0) throw new Error('condition.perceive_device_ids 至少需要一个设备 did')
+      if (!query) throw new Error('condition.query 不能为空')
+
+      const modes = ['event', 'state']
+      const directions = ['enter', 'exit', 'session', 'milestone', 'guard']
+      if (args.direction && !directions.includes(args.direction)) {
+        throw new Error(`direction 只能是 ${directions.join(' / ')}`)
+      }
+      if (args.mode && !modes.includes(args.mode)) {
+        throw new Error(`mode 只能是 ${modes.join(' / ')}`)
+      }
+      if (args.direction && args.mode) {
+        const expected = args.direction === 'session' ? 'state' : 'event'
+        if (args.mode !== expected) throw new Error(`direction=${args.direction} 对应 mode=${expected}`)
+      }
+
+      const body = { name, task_id: taskId, condition: { perceive_device_ids: deviceIds, query } }
+      if (args.direction) body.direction = args.direction
+      else body.mode = args.mode ?? 'event'
+      if (args.lifecycle) body.lifecycle = args.lifecycle
+      if (args.enabled !== undefined) body.enabled = Boolean(args.enabled)
+      for (const key of ['actions', 'action_descriptions', 'on_enter_actions', 'on_exit_actions']) {
+        if (args[key] !== undefined) {
+          if (!Array.isArray(args[key])) throw new Error(`${key} 必须是数组`)
+          body[key] = args[key]
+        }
+      }
+      for (const key of ['on_enter_desc', 'on_exit_desc', 'on_target_desc', 'terminate_when']) {
+        if (args[key] !== undefined) body[key] = args[key]
+      }
+      for (const key of ['exit_debounce_seconds', 'duration_seconds', 'duration_ratio']) {
+        if (args[key] !== undefined) body[key] = args[key]
+      }
       return call('POST', '/api/rules', { body, signal: exec?.signal })
     },
   }))
 
+  writeTools.push(defineMilocoTool({
+    name: 'miloco_rule_delete',
+    description: '删除一条自动化规则。先用 miloco_rule_list 确认 rule_id；删除后不可恢复。',
+    parameters: {
+      rule_id: { type: 'string', description: '规则 id' },
+    },
+    required: ['rule_id'],
+    async run(args, exec) {
+      const ruleId = requireString(args, 'rule_id')
+      return call('DELETE', `/api/rules/${encodeURIComponent(ruleId)}`, { signal: exec?.signal })
+    },
+  }))
+
   writeTools.push(defineMilocoTool({
     name: 'miloco_task_create',
-    description: '创建一个长期任务。kind 决定类型：rule=条件触发的自动化，schedule=定时提醒，record=行为累积统计，lifecycle=限时/长期。',
+    description: '创建一个长期任务的占位行（POST /api/tasks）。'
+      + '任务本身只保存 task_id 与描述；定时提醒再用 miloco_cron_create 关联，'
+      + '条件规则用 miloco_rule_create 关联，累计统计用 miloco_task_record_init 初始化。',
     parameters: {
-      kind: { type: 'string', description: 'rule / schedule / record / lifecycle' },
-      content: { type: 'string', description: '任务内容描述' },
-      name: { type: 'string', description: '任务名称' },
+      task_id: {
+        type: 'string',
+        pattern: '^[a-z0-9_]{1,32}$',
+        description: '任务 id，只能用小写字母、数字、下划线，最长 32 位',
+      },
+      description: {
+        type: 'string',
+        maxLength: 200,
+        description: '任务描述，最多 200 字',
+      },
+      lifecycle: {
+        type: 'string',
+        enum: ['permanent', 'temporary'],
+        description: 'permanent（默认）/ temporary',
+      },
+      expires_at: {
+        type: 'string',
+        description: '到期时刻，ISO 8601 且带时区；仅 lifecycle=temporary',
+      },
     },
-    required: ['kind', 'content'],
+    required: ['task_id', 'description'],
     async run(args, exec) {
-      const body = { kind: requireString(args, 'kind'), content: requireString(args, 'content') }
-      if (args.name) body.name = args.name
+      const taskId = requireString(args, 'task_id')
+      if (!/^[a-z0-9_]{1,32}$/.test(taskId)) {
+        throw new Error('task_id 必须匹配 [a-z0-9_]{1,32}（只能用小写字母、数字、下划线）')
+      }
+      const description = requireString(args, 'description')
+      if (Array.from(description).length > 200) throw new Error('description 不能超过 200 字')
+      const body = { task_id: taskId, description }
+      if (args.lifecycle !== undefined) {
+        if (!['permanent', 'temporary'].includes(args.lifecycle)) {
+          throw new Error('lifecycle 只能是 permanent / temporary')
+        }
+        body.lifecycle = args.lifecycle
+      }
+      if (args.expires_at !== undefined) {
+        if (body.lifecycle !== 'temporary') throw new Error('expires_at 只能配 lifecycle=temporary')
+        body.expires_at = requireString(args, 'expires_at')
+      }
       return call('POST', '/api/tasks', { body, signal: exec?.signal })
     },
   }))
 
+  writeTools.push(defineMilocoTool({
+    name: 'miloco_task_record_init',
+    description: '给已存在的长期任务初始化一份活跃记录（POST /api/tasks/{id}/record）。'
+      + 'kind=progress 需 target/unit/window；kind=duration 可给 target_minutes；kind=event 不需要额外字段。',
+    parameters: {
+      task_id: { type: 'string', description: '任务 id（snake_case，需先创建）' },
+      kind: { type: 'string', enum: ['progress', 'duration', 'event'], description: '记录类型' },
+      content: {
+        type: 'object',
+        description: '按 kind 提供的记录参数',
+        properties: {
+          target: { type: 'integer', minimum: 1, description: 'progress：目标次数' },
+          unit: { type: 'string', description: 'progress：计数单位，例如 次 / 杯' },
+          window: {
+            type: 'string',
+            enum: ['day', 'week', 'month', 'longterm'],
+            description: 'progress：统计窗口',
+          },
+          target_minutes: { type: 'integer', minimum: 1, description: 'duration：每日目标分钟数' },
+          recurring_pattern: { type: 'object', additionalProperties: true, description: '可选重复规则' },
+          expires_at: { type: 'string', description: '可选到期时刻（ISO 8601）' },
+        },
+        additionalProperties: false,
+      },
+    },
+    required: ['task_id', 'kind'],
+    async run(args, exec) {
+      const taskId = requireString(args, 'task_id')
+      if (!/^[a-z0-9_]{1,32}$/.test(taskId)) {
+        throw new Error('task_id 必须匹配 [a-z0-9_]{1,32}（只能用小写字母、数字、下划线）')
+      }
+      const kind = requireString(args, 'kind')
+      if (!['progress', 'duration', 'event'].includes(kind)) {
+        throw new Error('kind 只能是 progress / duration / event')
+      }
+      const content = args.content && typeof args.content === 'object' ? args.content : {}
+      if (kind === 'progress') {
+        if (!Number.isInteger(content.target) || content.target <= 0) {
+          throw new Error('progress 需要正整数 content.target')
+        }
+        if (!content.unit) throw new Error('progress 需要 content.unit')
+        if (!['day', 'week', 'month', 'longterm'].includes(content.window)) {
+          throw new Error('progress 需要 content.window：day / week / month / longterm')
+        }
+      }
+      if (kind === 'duration' && content.target_minutes !== undefined) {
+        if (!Number.isInteger(content.target_minutes) || content.target_minutes <= 0) {
+          throw new Error('content.target_minutes 必须是正整数')
+        }
+      }
+      return call('POST', `/api/tasks/${encodeURIComponent(taskId)}/record`, {
+        body: { kind, content },
+        signal: exec?.signal,
+      })
+    },
+  }))
+
   writeTools.push(defineMilocoTool({
     name: 'miloco_task_delete',
     description: '终止并删除一个长期任务及其关联的规则/定时计划/统计记录。'
       + 'reason=completed/expired/abandoned；用户主动取消时必须先二次确认。',
     parameters: {
       task_id: { type: 'string', description: '任务 id' },
-      reason: { type: 'string', description: 'completed / expired / abandoned' },
+      reason: { type: 'string', enum: ['completed', 'expired', 'abandoned'], description: 'completed / expired / abandoned' },
     },
     required: ['task_id', 'reason'],
     async run(args, exec) {
@@ -679,18 +892,23 @@ export function createMilocoTools(options) {
     description: '在后端注册一个定时计划（cron 表达式 / 指定时刻 / 固定间隔），到点后由 Miloco 主动把事件投递给 DSH。',
     parameters: {
       name: { type: 'string', description: '计划名称' },
-      kind: { type: 'string', description: 'cron / at / every' },
+      kind: { type: 'string', enum: ['cron', 'at', 'every'], description: 'cron / at / every' },
       cron_expr: { type: 'string', description: 'cron 表达式，如 "0 22 * * *"' },
       at_iso: { type: 'string', description: 'ISO 8601 时刻（kind=at）' },
-      every_ms: { type: 'integer', description: '间隔毫秒（kind=every）' },
+      every_ms: { type: 'integer', minimum: 60000, description: '间隔毫秒，最小 60000（kind=every）' },
       tz: { type: 'string', description: '时区，如 Asia/Shanghai' },
       message: { type: 'string', description: '到点后投递给 Agent 的文本' },
       task_id: { type: 'string', description: '关联的长期任务 id' },
     },
     required: ['kind', 'message'],
     async run(args, exec) {
+      const kind = requireString(args, 'kind')
+      if (!['cron', 'at', 'every'].includes(kind)) throw new Error('kind 只能是 cron / at / every')
+      if (kind === 'cron' && !args.cron_expr) throw new Error('kind=cron 需要 cron_expr')
+      if (kind === 'at' && !args.at_iso) throw new Error('kind=at 需要 at_iso')
+      if (kind === 'every' && !args.every_ms) throw new Error('kind=every 需要 every_ms')
       const body = {
-        kind: requireString(args, 'kind'),
+        kind,
         message: requireString(args, 'message'),
         name: args.name ?? 'miloco-cron',
         cron_expr: args.cron_expr,
@@ -703,6 +921,19 @@ export function createMilocoTools(options) {
     },
   }))
 
+  writeTools.push(defineMilocoTool({
+    name: 'miloco_cron_delete',
+    description: '删除一个定时计划（POST /api/crons 创建的 cron/at/every）。先用 miloco_cron_list 确认 cron_id。',
+    parameters: {
+      cron_id: { type: 'string', description: '定时计划 id' },
+    },
+    required: ['cron_id'],
+    async run(args, exec) {
+      const cronId = requireString(args, 'cron_id')
+      return call('DELETE', `/api/crons/${encodeURIComponent(cronId)}`, { signal: exec?.signal })
+    },
+  }))
+
   writeTools.push(defineMilocoTool({
     name: 'miloco_scope_set',
     description: '设置参与感知的摄像头（in_use=true 开始观察，false 停止观察）。这是隐私相关操作，改动前请向用户确认。',
@@ -744,7 +975,11 @@ export function createMilocoTools(options) {
         items: {
           type: 'object',
           properties: {
-            op: { type: 'string', description: 'add / merge / replace / update / delete' },
+            op: {
+              type: 'string',
+              enum: ['add', 'merge', 'replace', 'update', 'delete'],
+              description: 'add / merge / replace / update / delete',
+            },
             id: { type: 'string', description: '正式区条目 id（merge/replace/update/delete 用）' },
             from: { type: 'string', description: '候选条目 id（带上即消费该候选）' },
             entry: {
@@ -753,13 +988,17 @@ export function createMilocoTools(options) {
               properties: {
                 type: {
                   type: 'string',
-                  description: 'member_persona / member_health / member_routine / member_entertain / member_preference / family / space / device',
+                  enum: [
+                    'member_persona', 'member_health', 'member_routine', 'member_entertain',
+                    'member_preference', 'family', 'space', 'device',
+                  ],
+                  description: '成员/家庭/空间/设备档案类型',
                 },
                 subject_id: { type: 'string', description: '成员 person_id' },
                 subject_name: { type: 'string', description: '主体名称（成员称谓 / 空间名）' },
                 content: { type: 'string', description: '条目正文' },
-                confidence: { type: 'number', description: '置信度 0~1' },
-                source: { type: 'string', description: 'observed / user_told' },
+                confidence: { type: 'number', minimum: 0, maximum: 1, description: '置信度 0~1' },
+                source: { type: 'string', enum: ['observed', 'user_told'], description: 'observed / user_told' },
                 evidence_log: { type: 'array', items: { type: 'string' }, description: '证据' },
               },
               required: ['type', 'content'],
@@ -770,12 +1009,18 @@ export function createMilocoTools(options) {
           additionalProperties: true,
         },
       },
+      user_edit: {
+        type: 'boolean',
+        description: '用户直接告知的内容设为 true（后端会按 user_told / 高置信度处理）',
+      },
     },
     required: ['ops'],
     async run(args, exec) {
       const ops = Array.isArray(args.ops) ? args.ops : []
       if (ops.length === 0) throw new Error('缺少参数 ops')
-      return call('POST', '/api/home-profile/profile:write', { body: { ops }, signal: exec?.signal })
+      const body = { ops }
+      if (args.user_edit !== undefined) body.user_edit = Boolean(args.user_edit)
+      return call('POST', '/api/home-profile/profile:write', { body, signal: exec?.signal })
     },
   }))
 
@@ -789,29 +1034,37 @@ export function createMilocoTools(options) {
         items: {
           type: 'object',
           properties: {
-            op: { type: 'string', description: 'add / merge / update / delete' },
+            op: {
+              type: 'string',
+              enum: ['add', 'merge', 'update', 'delete'],
+              description: 'add / merge / update / delete',
+            },
             id: { type: 'string', description: '候选条目 id' },
-            date: { type: 'string', description: '观察日期' },
+            date: { type: 'string', description: '观察日期（YYYY-MM-DD）' },
             entry: {
               type: 'object',
               description: '条目内容',
               properties: {
                 type: {
                   type: 'string',
-                  description: 'member_persona / member_health / member_routine / member_entertain / member_preference / family / space / device',
+                  enum: [
+                    'member_persona', 'member_health', 'member_routine', 'member_entertain',
+                    'member_preference', 'family', 'space', 'device',
+                  ],
+                  description: '成员/家庭/空间/设备档案类型',
                 },
                 subject_id: { type: 'string', description: '成员 person_id' },
                 subject_name: { type: 'string', description: '主体名称' },
                 content: { type: 'string', description: '条目正文' },
-                confidence: { type: 'number', description: '置信度 0~1' },
-                source: { type: 'string', description: 'observed / user_told' },
+                confidence: { type: 'number', minimum: 0, maximum: 1, description: '置信度 0~1' },
+                source: { type: 'string', enum: ['observed', 'user_told'], description: 'observed / user_told' },
                 evidence_log: { type: 'array', items: { type: 'string' }, description: '证据' },
               },
               required: ['type', 'content'],
               additionalProperties: true,
             },
           },
-          required: ['op'],
+          required: ['op', 'date'],
           additionalProperties: true,
         },
       },
@@ -820,6 +1073,9 @@ export function createMilocoTools(options) {
     async run(args, exec) {
       const ops = Array.isArray(args.ops) ? args.ops : []
       if (ops.length === 0) throw new Error('缺少参数 ops')
+      if (ops.some(op => !op || typeof op.date !== 'string' || !op.date.trim())) {
+        throw new Error('candidates:write 的每个 op 都必须带 date（YYYY-MM-DD）')
+      }
       return call('POST', '/api/home-profile/candidates:write', { body: { ops }, signal: exec?.signal })
     },
   }))
@@ -828,7 +1084,7 @@ export function createMilocoTools(options) {
     name: 'miloco_home_profile_commit',
     description: '提交家庭档案：后端会自动做过期候选清理（30 天且证据不足 3 条）、token 预算归档与 markdown 渲染持久化。',
     async run(_args, exec) {
-      return call('POST', '/api/home-profile/commit', { body: {}, signal: exec?.signal })
+      return call('POST', '/api/home-profile/commit', { signal: exec?.signal })
     },
   }))
 
@@ -1032,14 +1288,22 @@ export function createMilocoTools(options) {
         description: '本地图片路径列表',
         items: { type: 'string' },
       },
+      mode: {
+        type: 'string',
+        enum: ['replace', 'append'],
+        description: 'replace（整组替换，默认）/ append（按质量分保留 top-3）',
+      },
     },
     required: ['pet_id', 'files'],
     async run(args, exec) {
       const petId = requireString(args, 'pet_id')
       const paths = Array.isArray(args.files) ? args.files.filter(f => typeof f === 'string' && f) : []
       if (paths.length === 0) throw new Error('缺少参数 files')
+      const fields = {}
+      if (args.mode !== undefined) fields.mode = args.mode
       return client.postMultipart(`/api/identity/pets/${encodeURIComponent(petId)}/reference-crops`, {
-        files: paths.map(p => ({ field: 'file', path: p })),
+        files: paths.map(p => ({ field: 'crops', path: p })),
+        fields,
         signal: exec?.signal,
       })
     },
@@ -1141,9 +1405,12 @@ export const WRITE_TOOL_NAMES = [
   'miloco_scene_trigger',
   'miloco_notify_push',
   'miloco_rule_create',
+  'miloco_rule_delete',
   'miloco_task_create',
+  'miloco_task_record_init',
   'miloco_task_delete',
   'miloco_cron_create',
+  'miloco_cron_delete',
   'miloco_scope_set',
   'miloco_home_profile_write',
   'miloco_home_profile_candidate_write',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-miloco-bridge",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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",
@@ -30,7 +30,7 @@
     "lib",
     "skills",
     "adapter",
-    "doc",
+    "docs",
     "scripts",
     "install.sh",
     "cordis.patch.yml",