### Prepare Environment and Install Dependencies

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/scripts/install-guide.md

This command runs the installation script in agent-prepare mode to check the environment, install core packages, and start services.

```bash
curl -LsSf https://github.com/XiaoMi/xiaomi-miloco/releases/latest/download/install.sh | bash -s -- --agent-prepare
```

--------------------------------

### One-line Command-Line Install for Miloco

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/README.md

Execute this command to download and run the installation script for Miloco. This is a quick method for installing the software.

```bash
curl -LsSf https://github.com/XiaoMi/xiaomi-miloco/releases/latest/download/install.sh | bash
```

--------------------------------

### Install miloco-miot SDK

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/backend/miot/README.md

Install the MIoT SDK using pip. This command fetches and installs the necessary package for device communication.

```bash
pip install miloco-miot
```

--------------------------------

### Install Frontend Dependencies

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/knowledge/06-dev-guide/dev-guide.md

Installs all necessary dependencies for the web frontend using pnpm.

```bash
cd web
pnpm install                   # 安装依赖
```

--------------------------------

### Install Miloco

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/backend/miloco/README.md

Installs the Miloco backend using the uv tool.

```bash
uv tool install miloco
```

--------------------------------

### Install Development Dependencies for Backend Server

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/knowledge/06-dev-guide/dev-guide.md

Installs all dependencies, including development-specific ones, for the backend server using uv.

```bash
cd backend
uv sync --all-groups           # 安装包含 dev 依赖
```

--------------------------------

### Scope Management Examples

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/plugins/skills/miloco-miot-scope/SKILL.md

Practical examples demonstrating how to view the current scope status, switch households, and manage camera perception.

```APIDOC
## Scope Management Examples

### Description
Practical examples demonstrating how to view the current scope status, switch households, and manage camera perception.

### Viewing Scope Status

**List all households:**
```bash
$ miloco-cli scope home list
```
*Expected Output Example:*
```json
{"code":0,"message":"ok","data":[
   {"home_id":"611001054724","home_name":"HCl的家","in_use":false},
   {"home_id":"611001866489","home_name":"xiaomi","in_use":true}]}
```

**List all cameras:**
```bash
$ miloco-cli scope camera list
```
*Expected Output Example:*
```json
{"code":0,"message":"ok","data":[
   {"did":"1154253569","name":"小米智能摄像机C700","is_online":true,"in_use":true,"connected":true}]}
```

### Switching Households

**Switch to 'xiaomi' household:**
```bash
$ miloco-cli scope home switch 611001866489
```
*Expected Output Example (shows updated `in_use` status for all households):*
```json
{"code":0,"message":"ok","data":[
   {"home_id":"611001054724","home_name":"HCl的家","in_use":false},
   {"home_id":"611001866489","home_name":"xiaomi","in_use":true}]}
```

**Switch back to 'HCl的家' household:**
```bash
$ miloco-cli scope home switch 611001054724
```
*Expected Output Example:*
```json
{"code":0,"message":"ok","data":[
   {"home_id":"611001054724","home_name":"HCl的家","in_use":true},
   {"home_id":"611001866489","home_name":"xiaomi","in_use":false}]}
```

### Managing Camera Perception

**Disable perception for a specific camera (first list to get DID):**
```bash
$ miloco-cli scope camera list        # Obtain the DID first
$ miloco-cli scope camera disable 1154253569
```
*Expected Output Example (shows updated `in_use` and `connected` status):*
```json
{"code":0,"message":"ok","data":[
   {"did":"1154253569","name":"小米智能摄像机C700","is_online":true,"in_use":false,"connected":false}]}
```

**Enable perception for a disabled camera:**
```bash
$ miloco-cli scope camera enable 1154253569
```
*Expected Output Example (shows restored `in_use` and `connected` status):*
```json
{"code":0,"message":"ok","data":[
   {"did":"1154253569","name":"小米智能摄像机C700","is_online":true,"in_use":true,"connected":true}]}
```
```

--------------------------------

### Finish Installation with Configuration

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/scripts/install-guide.md

This command completes the Miloco installation by applying account and model configurations, and installing the OpenClaw plugin. Use parameters based on user choices from Step 2.

```bash
curl -LsSf https://github.com/XiaoMi/xiaomi-miloco/releases/latest/download/install.sh | bash -s -- --agent-finish \
  --account-auth "<授权码>" \
  --omni-api-key "<API Key>" \
  --omni-model "xiaomi/mimo-v2.5" \
  --omni-base-url "https://api.xiaomimimo.com/v1"
```

--------------------------------

### Develop and Install Skills

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/knowledge/06-dev-guide/dev-guide.md

Steps to modify a Skill, rebuild, and install it. Verify the installation and check logs for troubleshooting. Skills are located in `plugins/skills/` and require a specific directory structure and `SKILL.md` file.

```bash
# 修改 Skill 后重新构建并安装
cd plugins/openclaw
pnpm run build
openclaw plugins install .

# 验证 Skill 已安装
openclaw skills list | grep miloco
```

--------------------------------

### Start Miloco Server

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/backend/miloco/README.md

Starts the Miloco server. The server listens on http://127.0.0.1:1810 by default.

```bash
miloco-backend
```

```bash
miloco-cli service start
```

--------------------------------

### Start the Rule Tester

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/backend/miloco/tests/rule_tester/README.md

Launch the rule tester server on port 8090. After starting, access the web interface via your browser.

```bash
cd backend/miloco
uv run python tests/rule_tester/server.py --port 8090
```

--------------------------------

### Initialize MIoT Client and Get Devices

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/backend/miot/README.md

Demonstrates how to initialize the MIoTClient and retrieve a list of connected devices. Ensure the cloud server is correctly specified.

```python
from miot.client import MIoTClient

client = MIoTClient()
await client.init(cloud_server="cn")
devices = await client.get_devices()
```

--------------------------------

### Install OpenClaw Plugin

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/knowledge/06-dev-guide/dev-guide.md

Installs the built OpenClaw plugin into the OpenClaw system. Requires a prior build step.

```bash
openclaw plugins install .     # 安装到 OpenClaw（build 后需重装）
```

--------------------------------

### Run Backend Development Server

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/knowledge/06-dev-guide/dev-guide.md

Starts the development server in the foreground. This allows immediate visibility of process errors.

```bash
uv run task dev                # 前台直跑开发服务器（进程异常立即可见）
```

--------------------------------

### Start miloco backend

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/backend/miloco/tests/rule_tester/README.md

Ensure the backend is running. This command starts the miloco server, which is called via HTTP by `miloco-cli rule create`.

```bash
cd backend/miloco
uv run miloco_server   # 或 install.sh 脚本
```

--------------------------------

### Configure LLM via Configuration File

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/backend/miloco/tests/rule_tester/README.md

Copy the example configuration file and edit it to provide LLM API key and other settings. This method is an alternative to using environment variables.

```bash
cd backend/miloco/tests/rule_tester
cp config.example.toml config.toml
# 编辑 config.toml 填 api_key
```

--------------------------------

### Start Miloco Service

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/plugins/openclaw/README.md

Starts the Miloco backend service, which is required for the OpenClaw plugin to function correctly.

```bash
miloco-cli service start
```

--------------------------------

### Run Frontend Development Server

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/knowledge/06-dev-guide/dev-guide.md

Starts the Vite development server for the web frontend. It automatically proxies /api requests to the backend.

```bash
pnpm dev                       # Vite dev server，自动代理 /api 到 backend
```

--------------------------------

### Troubleshoot 'uv' Not Found

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/scripts/install-guide.md

If the 'uv' command is not found, use this command to install it and ensure it's added to your PATH.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh && export PATH="$HOME/.local/bin:$PATH"
```

--------------------------------

### Build Miloco from Source

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/README.md

This command builds Miloco from its source code and then installs it locally. Use this option for development or if you need to modify the source.

```bash
bash scripts/install.sh --dev   # build from source (scripts/build.sh), then install locally
```

--------------------------------

### Initialize Camera Connection Logic

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/web/public/watch.html

This asynchronous function handles the initial setup for connecting to a camera. It resolves tokens, processes camera IDs from the URL, and either connects directly in embedded mode or loads the camera list.

```javascript
(async () => { if (!resolveToken()) { setState(t("missingToken"), true); return; } const wantedCamRaw = params.get("camera_id"); const wantedCam = wantedCamRaw ? wantedCamRaw.replace(/[\[\\x00-\\x1f\\x7f\]]/g, "").slice(0, 64) : null; if (params.get("embedded") === "1" && wantedCam) { const opt = document.createElement("option"); opt.value = wantedCam; opt.textContent = wantedCam; $("cam").appendChild(opt); $("cam").value = wantedCam; connect(); return; } await refreshCameraList(); if (wantedCam) { const has = Array.from($("cam").options).some(o => o.value === wantedCam); if (!has) { $("cam").innerHTML = ""; const opt = document.createElement("option"); opt.value = wantedCam; opt.textContent = wantedCam; $("cam").appendChild(opt); setState(t("connectingTo", wantedCam)); } $("cam").value = wantedCam; } if ($("cam").value) connect(); })();
```

--------------------------------

### Install Specific Python Version with 'uv'

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/scripts/install-guide.md

Use this command with 'uv' to install a specific Python version if the current one is not compatible.

```bash
uv python install 3.14
```

--------------------------------

### Kitchen Appliances: Set Parameters Before Start

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/plugins/skills/miloco-devices/SKILL.md

For kitchen appliances like microwaves, ovens, and water heaters, parameters such as temperature and time must be set before initiating the cooking or operation action (e.g., `start-cook`).

```text
start-cook
```

--------------------------------

### Install Miloco via OpenClaw Agent

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/README.md

Use this command to instruct OpenClaw to automatically install the Miloco plugin from a remote script. Ensure OpenClaw is configured and accessible.

```text
Please install the Miloco plugin for me: https://raw.githubusercontent.com/XiaoMi/xiaomi-miloco/main/scripts/install-guide.md
```

--------------------------------

### Re-run Install Script for Missing Models

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/knowledge/06-dev-guide/dev-guide.md

If essential models are missing, re-running the install.sh script with the --dev flag can help complete the installation.

```bash
# 模型缺失时重跑 install.sh 补全
bash scripts/install.sh --dev
```

--------------------------------

### Start, Stop, Restart, and Status of Miloco Service

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/user_guide.md

Manage the Miloco service using these commands. Use `-f` with `logs` for live log streaming.

```bash
miloco-cli service start | stop | restart | status
```

```bash
miloco-cli service logs -f          # Live logs
```

--------------------------------

### Open Miloco Dashboard

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/README.md

Open the Miloco home dashboard in your browser to complete the initial setup. Alternatively, you can visit http://<host>:1810/ directly.

```bash
miloco-cli dashboard
```

--------------------------------

### Call Backend APIs using miloco-cli

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/knowledge/06-dev-guide/dev-guide.md

Examples of using `miloco-cli` to interact with various backend services including device control, rule management, task management, and identity management. The CLI reads configuration from `$MILOCO_HOME/config.json` for server URL and token.

```bash
# 设备控制
miloco-cli device control <did> <key> <value>
miloco-cli device control <did> --set <key> <val> --set <key> <val>  # 多属性合并
miloco-cli device props <did> [key ...]
                               # 查询属性
miloco-cli device action <did> <iid> [param ...]
                               # 调用动作
miloco-cli device list [--room <房间>] [--category <品类>]
                               # 查设备列表
miloco-cli device spec <did>                                           # 查设备 spec

# 规则管理
miloco-cli rule create --task-id <id> --name "规则描述" --mode event --condition "..."
miloco-cli rule list --pretty
miloco-cli rule logs --since 1h

# 任务管理（task：生命周期；record：行为统计）
miloco-cli task create --task-id <id> --description "<desc>"
miloco-cli task link --task <task_id> --kind cron --ref <jobId>       # 挂 cron（rule 由 rule create 自动 link）
miloco-cli task delete <task_id> --reason completed|expired|abandoned  # 终止（写审计快照）
miloco-cli task record init <task_id> --kind progress|duration|event  # 初始化记录
miloco-cli task record progress-inc <task_id> [--delta N]             # 进度累加
miloco-cli task record event-append <task_id> --description "<描述>"   # 事件追加
miloco-cli task record session-start|session-end <task_id>            # 时长计时段
miloco-cli task record get|compute <task_id>                          # 读取 / 聚合

# 身份管理
miloco-cli identity member list
miloco-cli identity pool fetch --cam <cam_id>
miloco-cli identity register from-cluster --cluster-id <id> [--member-id <id> | --name <名>] 
```

--------------------------------

### Run Local CLI Version

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/knowledge/06-dev-guide/dev-guide.md

Executes the local version of the miloco-cli tool without requiring a full installation, useful after making CLI modifications.

```bash
cd cli
uv run miloco-cli device list  # 直接用 uv run 跑本地版本（不需重装）
```

--------------------------------

### Get Incremental Perception Logs

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/plugins/skills/miloco-perception-digest/SKILL.md

Command to fetch incremental perception logs in JSONL format. This is the first step in processing perception data.

```bash
miloco-cli perceive logs --jsonl
```

--------------------------------

### Direct API Calls for Debugging

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/knowledge/06-dev-guide/dev-guide.md

Examples of making direct HTTP requests to the Mioco backend APIs for debugging purposes. This includes obtaining tokens, querying device lists, controlling devices, checking perception engine status, triggering perception queries, and more.

```bash
# 获取 token
TOKEN=$(miloco-cli config get server.token)

# 查询设备列表
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:1810/api/miot/device_list

# 控制设备
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "set_property", "iid": "prop.<siid>.<piid>", "value": true}' \
  http://127.0.0.1:1810/api/miot/devices/<did>/control

# 查询感知引擎状态
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:1810/api/perception/engine/status

# 触发主动查询
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sources": ["<device_did>"], "query": "客厅里现在有几个人？"}' \
  http://127.0.0.1:1810/api/perception/perceive

# 查询规则列表
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:1810/api/rules

# 查询家庭档案
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:1810/api/home-profile/entries

# 查询节点健康状态
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:1810/api/monitor/nodes
```

--------------------------------

### Build Frontend for Production

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/knowledge/06-dev-guide/dev-guide.md

Builds the web frontend for production, outputting the production package to web/dist/.

```bash
pnpm build                     # 构建到 web/dist/（生产包）
```

--------------------------------

### Task Duration Start/End API

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/knowledge/03-features/task-management.md

Starts or ends a timing session for a duration-type task record.

```python
POST /api/tasks/{id}/record/session-start
```

```python
POST /api/tasks/{id}/record/session-end
```

--------------------------------

### Restart OpenClaw Gateway

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/README.md

Restart the OpenClaw gateway to apply plugin changes. This command is essential after installation.

```bash
openclaw gateway restart
```

--------------------------------

### Create a Daily Water Intake Task with Progress Tracking

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/plugins/skills/miloco-create-task/SKILL.md

Sets up a task to track daily water intake, with a progress record and multiple cron jobs for reminders and termination. This is for recurring, measurable goals.

```bash
EXPIRES_AT=$(miloco-cli time-compute --anchor '{"kind":"end_of_day"}')
miloco-cli task create --task-id drink_8_today --description "今天喝够 8 杯水"

miloco-cli rule create --task-id drink_8_today \
  --name "[drink_8_today] 喝水计数" \
  --mode event \
  --condition "用户手持水杯/水瓶/茶杯/保温杯等饮品容器，杯口贴近嘴边并伴随仰头吞咽动作；不含手持牙刷/麦克风/纸盒/食物/餐盒等非饮品物品，不含举杯凑近鼻子闻、吹凉、展示等动作" \
  --action-desc "喝水次数加一；首次达标时使用手机推送通知：恭喜达标"

miloco-cli task record init drink_8_today \
  --kind progress \
  --content "{\"target\":8,\"unit\":\"杯\",\"window\":\"day\",\"expires_at\":\"$EXPIRES_AT\"}"

# 调 OpenClaw cron 建提醒 cron（喝水无强场景 → 均分 10-20，N=min(8,6)=6 时点）：name="[drink_8_today] 喝水提醒"，cron="0 10,12,14,16,18,20 * * *"，message="调 miloco-cli task record get drink_8_today，按 derived.remaining 决定是否催"
miloco-cli task link --task drink_8_today --kind cron --ref <jobId_remind>

# 调 OpenClaw cron 建到期销毁 at：name="[drink_8_today] 到期销毁"，at=$EXPIRES_AT，message="到期销毁 task drink_8_today"
miloco-cli task link --task drink_8_today --kind cron --ref <jobId_termination>
```

--------------------------------

### Daily Rollover Daemon

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/knowledge/03-features/task-management.md

A background daemon that runs daily to archive completed task records and start new cycles.

```python
main.py lifespan起 _rollover_daily_loop（每日凌晨定时）
```

```python
rollover_daily_job（task_record/rollover.py）
```

--------------------------------

### Event Listeners for Connection and Refresh

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/web/public/watch.html

Sets up event listeners for 'go', 'refresh', 'cam', and 'ch' elements to handle connection, camera list refresh, and camera/channel selection changes.

```javascript
$("go").addEventListener("click", connect);
```

```javascript
$("refresh").addEventListener("click", refreshCameraList);
```

```javascript
// Always (re)connect on either selection change — covers both "switch while // a stream is running" and "pick after a previous connection died" without // requiring the user to also press 重连. $("cam").addEventListener("change", connect);
```

```javascript
$("ch").addEventListener("change", connect);
```

--------------------------------

### Configure LLM via Environment Variables

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/backend/miloco/tests/rule_tester/README.md

Set environment variables to configure the LLM connection details. This is the recommended method for setting up the LLM.

```bash
export MILOCO_TESTER_LLM_BASE_URL="https://api.openai.com/v1"
export MILOCO_TESTER_LLM_API_KEY="sk-..."
export MILOCO_TESTER_LLM_MODEL="gpt-4o-mini"
```

--------------------------------

### Diagnose miloco connection issues

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/knowledge/06-dev-guide/troubleshooting.md

Run this command to diagnose general connection problems with miloco. Ensure the miloco-cli is installed and accessible in your PATH.

```bash
miloco-cli doctor
```

--------------------------------

### Home Profile API Router

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/knowledge/03-features/home-profile.md

The main entry points for the Home Profile API are POST /api/home-profile/commit and GET /api/home-profile/entries, defined in home_profile/router.py.

```python
主要入口：`POST /api/home-profile/commit`（触发提交）、`GET /api/home-profile/entries`（查询档案），完整端点见 `home_profile/router.py`。
```

--------------------------------

### Device Status Query Entry Point

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/knowledge/03-features/device-control.md

Device status queries are handled by MiotService.get_device_status, while scene triggers use trigger_scene and MiotProxy.execute_miot_scene. The underlying link structure is the same for both.

```Python
MiotService.get_device_status
```

```Python
trigger_scene -> MiotProxy.execute_miot_scene
```

--------------------------------

### Miloco Plugin Development Commands

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/plugins/openclaw/README.md

Common commands for developing the Miloco OpenClaw plugin, including installation, building, type checking, testing, and linting.

```bash
pnpm install
```

```bash
pnpm run build          # Build
```

```bash
pnpm run check          # Type check
```

```bash
pnpm test               # Run tests
```

```bash
pnpm run lint           # Lint
```

--------------------------------

### Show and Modify Perception Configuration

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/knowledge/06-dev-guide/dev-guide.md

Use `miloco-cli` to view current perception configurations and restart services to apply changes. Ensure the engine status is confirmed after modifications.

```bash
# 查看当前感知配置
miloco-cli config show | grep perception

# 修改某项参数后重启服务使配置生效
miloco-cli service stop && miloco-cli service start

# 确认引擎状态
curl -H "Authorization: Bearer $(miloco-cli config get server.token)" \
  http://127.0.0.1:1810/api/perception/engine/status
```

--------------------------------

### Unescape RBSP Data

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/web/public/watch.html

Removes start codes from Raw Byte Sequence Payload (RBSP) data. Use this before parsing NAL unit data.

```javascript
function unescapeRBSP(nal) { const out = []; for (let i = 0; i < nal.length; i++) { if (i + 2 < nal.length && nal[i] === 0 && nal[i + 1] === 0 && nal[i + 2] === 3) { out.push(0, 0); i += 2; } else out.push(nal[i]); } return Uint8Array.from(out); }
```

--------------------------------

### Initialize Camera Selection

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/web/public/watch.html

Sets the initial camera selection from URL parameters or local storage. This ensures the user sees their preferred camera upon loading.

```javascript
const initialChannel = params.get("channel") || localStorage.getItem("miloco_channel"); if (initialChannel) $("ch").value = initialChannel;
```

--------------------------------

### Get Task Description for Confirmation

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/plugins/skills/miloco-terminate-task/SKILL.md

Before permanently deleting a task initiated by a user, retrieve its description to ask for confirmation. This step is skipped for automatic triggers.

```bash
miloco-cli task get <task_id>
```

--------------------------------

### 修改直播相关功能的文件指引

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/knowledge/03-features/live-camera-view.md

提供了修改直播相关功能的指引，列出了不同修改目标对应的核心文件。例如，修改 WebSocket 订阅逻辑应查看 `miot/ws.py`，修改编码参数则查看 `miot/transcoder.py`。

```markdown
| 修改目标                              | 去看哪个文件                                           |
| ------------------------------------- | ------------------------------------------------------ |
| 修改 WebSocket 订阅/管理逻辑          | `miot/ws.py`（MIoTVideoStreamManager）                 |
| 修改编码参数或 WebSocket 帧格式       | `miot/transcoder.py`（H264LiveEncoder）                |
| 修改 watch.html 页面或 token 注入逻辑 | `miot/router.py`（`watch_page`）和 `static/watch.html` |
| 修改浏览器端解码逻辑                  | `static/watch.html` 内的 JavaScript 部分               |
```

--------------------------------

### Run Frontend Unit Tests

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/knowledge/06-dev-guide/dev-guide.md

Executes the unit tests for the web frontend using Vitest.

```bash
pnpm test                      # 单元测试（vitest）
```

--------------------------------

### Create a Wakeup Curtain Task and Rule

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/plugins/skills/miloco-create-task/SKILL.md

Sets up a task to automatically open curtains upon waking and a rule to manage this state change. It includes a debounce setting for the exit action.

```bash
miloco-cli task create --task-id wakeup_curtain --description "起床开窗帘"
miloco-cli rule create --task-id wakeup_curtain \
  --name "[wakeup_curtain] 起床开窗帘" \
  --mode state \
  --condition "用户从卧床躺姿切换到坐起或离床站立姿态；不含翻身、伸懒腰等床上小动作，不含坐起喝水后躺回等短暂起身动作" \
  --exit-debounce-seconds 60 \
  --on-enter-action '{"did":"<窗帘 DID>","iid":"prop.X","value":true,"idempotent":true}' \
  --on-exit-desc "检查开窗帘是否仍有效，若已结束则复位"
```

--------------------------------

### Device Welcome Data Flow

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/knowledge/03-features/device-welcome.md

Illustrates the data flow from Mi Home app device binding or home change events to the final TTS announcement via the Agent and miloco-notify Skill. It highlights the key components and their interactions.

```text
米家 App 绑定 / 移入设备
  → 小米 MQTT broker 推送 bind/unbind 或 hr_change 事件
  → MIoTMipsCloud（backend/miot/src/miot/mips_cloud.py）
  → MiotProxy（miot/client.py）
  → 对应监听器（miot/mips_listeners.py，trailing-edge 防抖；MQTT payload 非权威）
      BindEventListener（bind 路径）/ DeviceMetaEventListener（home-move 路径）
      → 拉云端终态（refresh_devices）→ present 判断
      → 委托 welcome(did)
  → DeviceWelcomeService（miot/welcome_service.py）
      scope gate（设备在启用家庭内）+ 跨路径去重 + 构造欢迎消息
      → dispatch_event("bind", [msg], ...)
  → AgentDispatcher（dispatch/dispatcher.py）
      bind 事件复用主交互会话
  → run_agent_turn → OpenClaw Webhook
  → Agent 调 miloco-notify Skill 播报欢迎语
```

--------------------------------

### Manage Miloco Members and Perception Devices

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/user_guide.md

List members, add new members with name and role, list perception devices, or query perception status from a specific device.

```bash
miloco-cli person list              # List members
```

```bash
miloco-cli person add --name "John" --role "Dad"
```

```bash
miloco-cli perceive devices         # List perception devices
```

```bash
miloco-cli perceive query --source <did> --query "Is anyone in the living room?"
```

--------------------------------

### Iterate NAL Units

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/web/public/watch.html

A generator function to iterate over Network Abstraction Layer (NAL) units within a byte buffer. It identifies NAL units by their start codes (0x000001 or 0x00000001).

```javascript
function* iterNALUnits(buf) {
  let i = 0;
  while (i < buf.length - 3) {
    let sc = -1, scLen = 0;
    if (buf[i] === 0 && buf[i + 1] === 0 && buf[i + 2] === 0 && buf[i + 3] === 1) {
      sc = i;
      scLen = 4;
    } else if (buf[i] === 0 && buf[i + 1] === 0 && buf[i + 2] === 1) {
      sc = i;
      scLen = 3;
    }
    if (sc < 0) {
      i++;
      continue;
    }
    const start = sc + scLen;
    // find next start code
    let j = start;
    let nextSc = -1;
    while (j < buf.length - 2) {
      if (buf[j] === 0 && buf[j + 1] === 0 && (buf[j + 2] === 1 || (buf[j + 2] === 0 && buf[j + 3] === 1))) {
        nextSc = j;
        break;
      }
      j++;
    }
    const end = nextSc >= 0 ? nextSc : buf.length;
    yield buf.subarray(start, end);
    i = end;
  }
}
```

--------------------------------

### Manage Rules with miloco-cli

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/knowledge/06-dev-guide/dev-guide.md

Commands for listing rules, viewing rule trigger logs, and manually triggering rules for debugging purposes. Note that rule conditions cannot start with assertive phrases like '检测到'.

```bash
# 查看当前规则列表
miloco-cli rule list --pretty

# 查看规则触发日志（最近 1 小时）
miloco-cli rule logs --since 1h --pretty

# 手动触发规则测试（debug 用）
miloco-cli rule trigger <rule_id>
```

--------------------------------

### Run Backend Tests

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/knowledge/06-dev-guide/dev-guide.md

Executes the test suite for the backend server.

```bash
uv run task test               # 运行测试
```

--------------------------------

### IM Push Response with NeedsBind

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/plugins/skills/miloco-notify/references/channel-config.md

When an IM push is attempted on an unconfigured or invalid channel, the system returns a JSON object indicating `needsBind: true`. This response includes a reason, an example hint, and the next action.

```json
{
  "ok": false, "needsBind": true,
  "bindReason": "not_configured | configured_but_invalid",
  "bindHintExample": "<可直接翻译的引导语范例>",
  "nextAction": "..."
}
```

--------------------------------

### `/api/miot/watch` 端点：提供 watch.html 模板

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/knowledge/03-features/live-camera-view.md

这是直播功能的入口端点。它读取 `static/watch.html` 模板，并将 `__MILOCO_TOKEN__` 占位符替换为真实的 `server.token` 后返回给浏览器。浏览器随后使用此 token 请求摄像头列表并建立 WebSocket 连接。

```python
`/api/miot/watch` 端点（`miot/router.py::watch_page`）

入口端点：读取 `static/watch.html` 模板，将 `__MILOCO_TOKEN__` 占位符替换为真实 `server.token` 后返回给浏览器。浏览器收到注入 token 的页面后，用 token 调 `/api/perception/devices` 拉摄像头列表，用户选择后通过 WebSocket 接入视频流。

**信任边界**：`/api/miot/watch` 响应体内嵌明文 token，等价于"能访问该 URL 的人拥有 token"。默认仅监听 `127.0.0.1`；若开放 LAN 访问，应自行评估网络可信边界。`server.token` 未配置则返回 `503`。
```

--------------------------------

### Loading Home Profile for Agent System Prompt

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/knowledge/03-features/home-profile.md

The helpers.ts::loadHomeProfile function reads the profile.md file, constructs a profile block, and appends it to the Agent's system prompt. This is part of the archive consumption path.

```typescript
helpers.ts::loadHomeProfile 读取文件 → 拼档案块 → 追加到 Agent system prompt
```

--------------------------------

### Modifying Identity Recognition Features

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/knowledge/03-features/person-identity.md

This table guides developers on which files to modify for specific changes to the identity recognition system, covering state machine logic, stranger pool clustering, sample library I/O, registration flow, and CRUD APIs.

```text
修改识别状态机逻辑（何时触发/确认）
  `perception/engine/identity/engine.py`（IdentityEngine）
修改陌生人池聚类逻辑
  `perception/engine/identity/tier_u.py`（TierUPool）
修改样本库读写逻辑
  `perception/engine/identity/library.py`（IdentityLibrary）
修改注册流程（预览/commit 逻辑）
  `perception/engine/identity/registration_session.py`
修改成员 CRUD API
  `person/router.py`、`person/service.py`
```

--------------------------------

### Ensure MSE Decoder with jmuxer

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/web/public/watch.html

Initializes the MSE decoder using the jmuxer library for fMP4 fragments. This path is used for non-secure contexts like LAN HTTP. It handles video element setup, event listeners for resolution synchronization, and FPS display.

```javascript
async function ensureMseDecoder(firstKeyNAL, firstKeyTs) { if (typeof window.JMuxer === "undefined") { throw new Error(t("mseLibMissing")); } const canvas = $("v"); const video = $("vmse"); // 切显示态:canvas 隐,video 显。tearDown 会反向切回。 canvas.classList.add("hidden"); video.classList.remove("hidden"); $("codec").textContent = 	extvariable{codecHint} (MSE / fmp4 via jmuxer)	extvariable; jmuxer = new window.JMuxer({ node: video, mode: "video", flushingTime: 0, // 立即 flush,降低延迟到 1 帧 fps: 25, debug: false, onError: (data) => { console.warn("jmuxer error", data); setState(t("mseDecodeError", data?.message || data), true); }, }); // playing 时同步分辨率,跟 WebCodecs 路径口径一致。 video.addEventListener("playing", () => { hideLoading(); if (video.videoWidth) { $("res").textContent = 	extvariable{video.videoWidth}×${video.videoHeight}	extvariable; } }, { once: true }); // FPS:requestVideoFrameCallback 现代浏览器都有(Chrome 83+ / Safari 15.4+), // 没有则不显示 fps,功能不影响。 if ("requestVideoFrameCallback" in HTMLVideoElement.prototype) { let lastSec = performance.now(); let frames = 0; const cb = (rame, rameMeta) => { // tearDown 把 jmuxer 设 null;cb 仍可能在 cancel 跟 fire 的 race window 里 // 跑一次,此时再 self-schedule 会留个孤悬 handle 让 mseFpsRaf 写回非 null。 // 用 jmuxer 状态强对齐:jmuxer 销毁就停 self-schedule。 if (!jmuxer) return; frames++; stats.lastFrameLocalMs = Date.now(); const now = performance.now(); if (now - lastSec >= 1000) { $("fps").textContent = frames.toFixed(0); frames = 0; lastSec = now; } mseFpsRaf = video.requestVideoFrameCallback(cb); }; mseFpsRaf = video.requestVideoFrameCallback(cb); } // 喂第一个 IDR(SPS/PPS+IDR 在同一 access unit 里)。jmuxer 内部用 SPS // 推 codec 配置,后续 P 帧才能解。duration 40ms 跟 onMessage 里同款假设。 // lastMseTs = firstKeyTs 让第二帧能用 ts2-firstKeyTs 算真实间隔,不再 fallback 40。 jmuxer.feed({ video: firstKeyNAL, duration: 40 }); lastMseTs = firstKeyTs; configured = true; }
```

--------------------------------

### Probe VideoDecoder Configuration Support

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/web/public/watch.html

Asynchronously probes for supported video decoder configurations, iterating through different hardware acceleration preferences ('prefer-hardware', 'prefer-software', 'no-preference').

```javascript
async function probeCodec(codec) {
  for (const hwAccel of ["prefer-hardware", "prefer-software", "no-preference"]) {
    try {
      const sup = await VideoDecoder.isConfigSupported({ codec, hardwareAcceleration: hwAccel });
      if (sup.supported) return { codec, hwAccel };
    } catch {
      // keep trying
    }
  }
  return null;
}
```

--------------------------------

### Manage Miloco Rules and Notifications

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/user_guide.md

List automation rules, send a push notification to the Xiaomi Home app, or manage the camera allow/deny list.

```bash
miloco-cli rule list                # List automation rules
```

```bash
miloco-cli notify push --text "test push"   # Push to the Xiaomi Home app
```

```bash
miloco-cli scope camera list        # Camera allow/deny list
```

--------------------------------

### View and Modify Miloco Configuration

Source: https://github.com/xiaomi/xiaomi-miloco/blob/main/user_guide.md

Display current configuration (with masked keys), set specific configuration values like API keys, retrieve configuration values, or list all configurable paths.

```bash
miloco-cli config show              # Show config (keys masked)
```

```bash
miloco-cli config set model.omni.api_key sk-xxxx
```

```bash
miloco-cli config get model.omni.model
```

```bash
miloco-cli config list-paths        # List all configurable paths
```