mijia-control

Original source / Raw SKILL.md

---
name: mijia-control
description: "Control and monitor Xiaomi Mijia smart home devices. Use this skill when the user wants to: 1) Switch device status (on/off, brightness, etc.) 2) List available home devices 3) Run automation scenes 4) Check environmental statistics."
---

# Mijia Control Skill (Universal AI Agent Skill)

该技能使 AI 代理能够通过本地封装的 `mijiaAPI` 驱动，接管并控制小米米家智能家居设备。

> **注意**：本技能包内的所有脚本路径均为相对于本文件所在目录。执行时请务必使用**绝对路径**。

## 快速开始

1. **环境自检**：运行 `<SKILL_ROOT>/scripts/setup_env.py`。
2. **安装/登录**：
   - 安装：`python <SKILL_ROOT>/scripts/setup_env.py --install`。
   - 登录：运行 `mijiaAPI -l`。
3. **执行控制**：所有操作均通过 `<SKILL_ROOT>/scripts/` 下的脚本完成。

## 决策逻辑 (Decision Logic)

- **设备查询**：当用户询问“有哪些设备”、“状态如何”时 -> 执行 `scripts/list_devices.py` 获取实时快照。
- **设备控制**：当用户要求开关、调节亮度/温度等 -> 解析意图 -> 查阅 `reference/device_catalogs.md` -> 执行 `scripts/control_device.py`。
- **场景触发**：用户要求运行场景 -> 调用 CLI 命令执行。

## 约束建议 (Guardrails)

- 对于**窗帘、空调、锁**等涉及安全和昂贵能耗的设备，操作前需口头确认。
- 绝不向用户泄露 `auth.json` 中的敏感 Token。

## 更多信息
- 详尽 SOP 请参阅 [instructions.md](./instructions.md)。


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### instructions.md

```markdown
# Mijia Control SOP (Standard Operating Procedure)

该文档详细描述了 AI 代理应如何利用 `mijiaAPI` 处理复杂的智能家居控制逻辑。

## 重要：路径约束 (Pathing Rules)
- **绝对路径优先**：本技能包可能被放置在任意目录下（如 `.claude/skills/` 或 `.cursor/skills/`）。
- **执行前定位**：AI 代理在调用脚本前，**必须**先获取 `SKILL.md` 所在的绝对路径（记为 `SKILL_ROOT`）。
- **脚本调用格式**：始终使用 `python <SKILL_ROOT>/scripts/<script_name>.py` 格式执行。

## 1. 环境自检与 CLI 安装 (Self-Check & CLI Installation)
- **首先检查环境**：尝试运行 `<SKILL_ROOT>/scripts/setup_env.py`。
- **缺失安装 (Critical)**：
    - 若 `package_installed` 为 `false` 或 `cli_available` 为 `false`：
    - 引导用户运行：“环境尚未就绪。请运行：`python <SKILL_ROOT>/scripts/setup_env.py --install`。”
- **认证失效 (The Login Protocol)**：
    - 若 `auth_exists` 为 `false`：
    - 代理 **必须** 引导用户手动登录：“检测到未登录，请在终端运行：`mijiaAPI -l`。扫码完成后告知我即可。”

## 2. 核心操作规范 (Core Operations)
- **获取快照**：始终由 `scripts/list_devices.py` 开始以获取最新的 `did` 和 `online` 状态。
- **模糊匹配逻辑**：若用户指令不明确（如“开灯”但有多个灯），代理应主动列出设备名供用户选择。
- **CLI 优先策略**：为了保证操作的可追溯性和隔离性，代理应优先调用系统生成的 `mijiaAPI` 命令，或通过 `scripts/control_device.py` 包装器执行。

## 3. 设备识别与参考
- 内部参考：`reference/device_catalogs.md` 存储了常见型号的属性映射。
- 动态查询：若遇到未知型号，运行 `mijiaAPI --get_device_info <MODEL>`。

## 4. 安全约束
- 代理在执行诸如开锁、修改安防设置等高风险动作前，**必须**获得用户的明确肯首。
- 严禁在对话中输出 `auth.json` 中的任何敏感访问令牌。
    - 若用户说“开灯”，但列表里有“客厅灯”和“餐厅灯”，必须询问具体哪一个。
    - 允许根据 `online` 状态过滤。如果一个灯离线而另一个在线，可以优先操作在线的并告知用户。

## 2. 操作执行规范
- **原子化执行**：每个指令应尽量拆解为单步操作。
- **CLI 优先**：虽然可以通过 Python 代码库直接调用，但为了执行的隔离性和日志记录，建议通过 `scripts/` 下的封装脚本或直接调用 `mijiaAPI` 的命令行接口。
    - 设置属性：`python -m mijiaAPI set --dev_name "名称" --prop_name "属性" --value "值"`
    - 获取属性：`python -m mijiaAPI get --dev_name "名称" --prop_name "属性"`

## 3. 型号适配 (Spec Mapping)
- 不同的设备型号（model）使用不同的 `siid` 和 `piid`。
- 如果不确定属性名，指导 Claude 运行 `python -m mijiaAPI --get_device_info "model_name"` 来动态获取最新的定义，并保存在 `reference/` 中以便后续复用。

## 4. 常见问题处理
- **登录失效**：返回结果中包含 `LoginError` 时，引导用户执行交互式登录命令 `python -m mijiaAPI -l`。
- **超时**：米家服务器有时响应较慢，若遇到超时错误，重试一次。若依然失败，告知用户服务器繁忙。
- **不支持的操作**：如果设备不支持某项功能（如给开关调色温），应准确解释该硬件限制。

```

### scripts/list_devices.py

```python
import sys
import json
from pathlib import Path

# 不再依赖本地相对路径，而是依赖 pip 安装的全局包或虚拟环境包
try:
    from mijiaAPI import mijiaAPI

    api = mijiaAPI()
    if not api.available:
        print(json.dumps({"error": "AUTH_REQUIRED", "message": "Login token expired or missing."}, ensure_ascii=False))
        sys.exit(0)

    devices = api.get_devices_list() + api.get_shared_devices_list()
    
    # 转换为 AI 更容易理解的精简结构
    snapshot = []
    for d in devices:
        snapshot.append({
            "name": d.get("name"),
            "did": d.get("did"),
            "model": d.get("model"),
            "online": d.get("isOnline"),
            "room": d.get("roomName", "未指定房间")
        })
    
    print(json.dumps(snapshot, indent=2, ensure_ascii=False))

except Exception as e:
    print(json.dumps({"error": "EXECUTION_ERROR", "message": str(e)}, ensure_ascii=False))

```

### reference/device_catalogs.md

```markdown
# Mijia Device Reference Catalog

该文档记录了常用设备的型号与其属性对应关系，用于减少动态查询次数。

## 照明类 (Lighting)

### 型号: `lumi.switch.b2nacn02`
- **名称**: Aqara智能墙壁开关 D1（零火双键版）
- **属性**:
    - `on`: 左键开关 (bool)
    - `switch-on`: 右键开关 (bool)
    - `electric-power`: 当前功率 (float, Watt)
- **动作**:
    - `toggle`: 切换左键
    - `switch-toggle`: 切换右键

### 型号: `lumi.switch.b1nacn02`
- **名称**: Aqara智能墙壁开关 D1（零火单键版）
- **属性**:
    - `on`: 开关状态 (bool)

## 环境类 (Environment)

### 型号: `zhimi.airpurifier.ma2`
- **名称**: 米家空气净化器 2
- **属性**:
    - `on`: 开关 (bool)
    - `mode`: 运行模式 (0:Auto, 1:Silent, 2:Favorite)
    - `pm25_density`: PM2.5 浓度 (int)

---
*注：可通过 `python -m mijiaAPI --get_device_info <MODEL>` 持续更新此表。*

```

### scripts/control_device.py

```python
import sys
import argparse
import json
from pathlib import Path

# 不再依赖本地相对路径，而是依赖 pip 安装的全局包或虚拟环境包
def main():
    parser = argparse.ArgumentParser(description="Mijia Control Script for Claude Skill")
    parser.add_argument("--action", choices=["get", "set"], required=True)
    parser.add_argument("--did", help="Device DID")
    parser.add_argument("--name", help="Device Name")
    parser.add_argument("--prop", required=True, help="Property Name")
    parser.add_argument("--value", help="Value to set (for action=set)")

    args = parser.parse_args()

    try:
        from mijiaAPI import mijiaAPI, mijiaDevice
        api = mijiaAPI()
        
        # 优先使用 DID
        device = mijiaDevice(api, did=args.did, dev_name=args.name)
        
        if args.action == "get":
            val = device.get(args.prop)
            unit = device.prop_list[args.prop].unit if args.prop in device.prop_list else ""
            print(json.dumps({"status": "success", "result": val, "unit": unit}, ensure_ascii=False))
        
        elif args.action == "set":
            # 自动处理 Boolean 转换
            target_val = args.value
            if args.value.lower() == "true": target_val = True
            elif args.value.lower() == "false": target_val = False
            elif args.value.replace('.', '', 1).isdigit(): target_val = float(args.value) if '.' in args.value else int(args.value)
            
            device.set(args.prop, target_val)
            print(json.dumps({"status": "success", "message": f"Set {args.prop} to {target_val}"}, ensure_ascii=False))

    except Exception as e:
        print(json.dumps({"status": "error", "message": str(e)}, ensure_ascii=False))

if __name__ == "__main__":
    main()

```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### scripts/setup_env.py

```python
import subprocess
import sys
import json
import shutil
from pathlib import Path

def check_env():
    results = {
        "venv_exists": False,
        "package_installed": False,
        "cli_available": False,
        "auth_exists": False,
        "python_path": sys.executable
    }
    
    # 1. 检查虚拟环境
    python_executable = Path(sys.executable)
    results["venv_exists"] = ".venv" in python_executable.parts
    
    # 2. 检查 mijiaAPI 库是否安装
    try:
        import mijiaAPI
        results["package_installed"] = True
    except ImportError:
        results["package_installed"] = False
        
    # 3. 检查 CLI 命令是否可用
    # 除了 shutil.which，还要检查 python -m mijiaAPI 是否能运行
    results["cli_available"] = shutil.which("mijiaAPI") is not None
    if not results["cli_available"]:
        try:
            # 尝试静默运行 python -m mijiaAPI --help
            subprocess.run([sys.executable, "-m", "mijiaAPI", "--help"], 
                           capture_output=True, check=True)
            results["cli_available"] = True
        except:
            pass
    
    # 4. 检查登录状态
    auth_path = Path.home() / ".config" / "mijia-api" / "auth.json"
    results["auth_exists"] = auth_path.exists()
    
    return results

def install_dependencies():
    skill_dir = Path(__file__).resolve().parents[1]
    req_path = skill_dir / "requirements.txt"
    # 自愈逻辑：如果当前处于开发仓库中，则安装本地包；否则通过 requirements.txt (GitHub) 安装
    # 查找 pyproject.toml 或 setup.py
    root_dir = None
    for p in Path(__file__).resolve().parents:
        if (p / "pyproject.toml").exists() or (p / "setup.py").exists():
            root_dir = p
            break

    try:
        # 1. 安装 Skill 基础依赖
        if req_path.exists():
            subprocess.check_call([sys.executable, "-m", "pip", "install", "-r", str(req_path)])
        
        # 2. 如果找到了本地根目录且不是正在开发 Skill 本身（即 root_dir 不是 skill_dir 的父目录以外的地方）
        # 这里为了彻底解耦，如果 root_dir 存在，我们优先安装本地的，方便开发调试。
        if root_dir and root_dir != skill_dir.parents[1]: # 简单判断逻辑
             subprocess.check_call([sys.executable, "-m", "pip", "install", "-e", str(root_dir)])
             return {"status": "success", "message": "Installed using local development source."}
        
        return {"status": "success", "message": "All dependencies (including core library) installed from requirements.txt"}
    except Exception as e:
        return {"status": "error", "message": str(e)}

if __name__ == "__main__":
    if "--install" in sys.argv:
        print(json.dumps(install_dependencies(), ensure_ascii=False))
    else:
        print(json.dumps(check_env(), indent=2, ensure_ascii=False))

```