\r \r

Aqara Open API Skill\r

\r This file is the single entry router for the Aqara Open Platform HTTP API skill package.\r \r Read this file first. Use it to do four things:\r \r

1. Classify whether the user request lands in device, space, or automation.\r
2. Preserve the shared request envelope, credential rules, and non-guessing rules.\r
3. Build a structured handoff contract instead of forwarding raw user prose.\r
4. Decide whether the next step may use cache-first execution or must upgrade to stricter validation.\r \r Child skills:\r \r

• aqara-open-api-local/device/SKILL.md\r
• aqara-open-api-local/space/SKILL.md\r
• aqara-open-api-local/automation/SKILL.md\r \r

Quick Route Table\r

\r Use this table before reading any child skill in depth.\r \r | User asks for | Final intent | Next file |\r |---|---|---|\r | list devices, count devices, read state, control a device | device | aqara-open-api-local/device/SKILL.md |\r | list spaces, create or rename spaces, move devices between spaces | space | aqara-open-api-local/space/SKILL.md |\r | create automation, inspect automation, update automation config, enable or disable automation, delete automation | automation | aqara-open-api-local/automation/SKILL.md |\r | room-scoped device query such as "what lights are in the living room" | device | confirm room identity, then query devices from data/devices.json |\r | room-related automation such as "turn on the light when someone is in the living room" | automation | resolve room and device evidence first, then enter automation |\r \r

Language Policy\r

\r

• user-facing explanations, routing notes, and clarification questions should use Chinese Simplified\r
• Open API request types, field names, file paths, enums, and code examples must keep exact English identifiers\r
• do not mix Chinese and English in one rule sentence unless an exact identifier must be quoted\r \r

Package Model\r

\r Treat the three business entities as related, not isolated:\r \r

• space is the container and grouping scope for devices\r
• device is the concrete instance that can be queried, counted, and controlled\r
• automation is the orchestration layer that references rooms, devices, and device traits\r \r Route by the final action target, not by keyword count alone.\r \r Important relationship rule:\r \r
• for room-scoped device queries, space is the filter key and device is the answer source\r
• GetSpacesRequest confirms that a room exists or resolves spaceId; it does not answer which devices are inside the room\r
• the actual room-to-device result must come from data/devices.json by filtering devices whose room membership matches the resolved room\r \r Examples:\r \r
• "what devices are in the living room" -> final intent is device\r
• "move all lights from the master bedroom to the second bedroom" -> final intent is space\r
• "create an automation that turns on the light when someone is in the living room" -> final intent is automation\r \r

Shared Runtime Contract\r

\r Runtime configuration may come from:\r \r

• AQARA_ENDPOINT_URL\r
• AQARA_OPEN_API_TOKEN\r
• aqara config\r \r Credential resolution order:\r \r

1. Use the current shell environment if AQARA_ENDPOINT_URL and AQARA_OPEN_API_TOKEN are already set.\r
2. Otherwise read the AQARA CLI config file from ~/.aqa/config.json.\r
3. Use aqara config set-endpoint \x3Curl> and aqara config set-token \x3Ctoken> when the values are not already configured.\r \r Hard credential rules:\r \r

• never guess or hardcode real credentials\r
• never print the real token in chat, logs, or generated files\r
• never write secrets into persistent shell startup files\r
• if the config file is missing or unreadable, stop and report the configuration problem without dumping file contents\r \r

Shared API Contract\r

\r Global execution rules:\r \r

1. All execution should go through the aqara CLI instead of handwritten curl.\r
2. aqara devices cache refresh is the only allowed route for GetAllDevicesWithSpaceRequest.\r
3. Every other documented API request should use the matching aqara command group.\r
4. The underlying request body may contain only type, version, msgId, and data.\r
5. version must always be "v1".\r
6. type is whitelist-only. Never guess nearby request names.\r
7. Never guess deviceId, endpointId, functionCode, traitCode, spaceId, or automationId.\r
8. Command examples assume the current working directory is the aqara-open-api-local package root or that aqara is installed globally.\r
9. For queries such as "what devices are in the living room", never answer from GetSpacesRequest alone. Resolve the room first, then filter data/devices.json to produce the device list.\r \r Shared request envelope:\r \r

{\r
  "type": "\x3CRequestType>",\r
  "version": "v1",\r
  "msgId": "\x3Cunique-id>",\r
  "data": {}\r
}\r
```\r
\r
CLI execution note:\r
\r
- `aqara` encapsulates the request envelope and headers\r
- do not hand-build headers in normal skill execution\r
\r
Request type whitelist:\r
\r
- `GetAllDevicesWithSpaceRequest`\r
- `GetDeviceTypeInfosRequest`\r
- `ExecuteTraitRequest`\r
- `GetSpacesRequest`\r
- `CreateSpaceRequest`\r
- `UpdateSpaceRequest`\r
- `AssociateDevicesToSpaceRequest`\r
- `QueryAutomationCapabilitiesRequest`\r
- `CreateAutomationRequest`\r
- `UpdateAutomationRequest`\r
- `UpdateAutomationStatusRequest`\r
- `GetAutomationListRequest`\r
- `GetAutomationDetailsRequest`\r
- `DeleteAutomationRequest`\r
\r
## Capability Validation Strategy\r
\r
This package uses two validation modes for automation work:\r
\r
- `cache_first_generate`: default path for creation. Use resolved room and device context plus `data/devices.json` to build an automation-instance style `config`.\r
- `query_capabilities_required`: stricter path for risky or ambiguous automation work. Upgrade to `QueryAutomationCapabilitiesRequest` before finalizing the config.\r
\r
Upgrade from `cache_first_generate` to `query_capabilities_required` when any of the following is true:\r
\r
- the needed starter, condition, or action trait cannot be copied safely from `data/devices.json`\r
- the request depends on uncertain enum or event values\r
- the request is cross-space and the source or target mapping is still ambiguous\r
- the action is high risk, unusual, or not covered by the package's safe defaults\r
- the user explicitly asks for capability confirmation\r
\r
Important rule:\r
\r
- `data/devices.json` is the default creation evidence source\r
- `QueryAutomationCapabilitiesRequest` is the escalation path, not the default first step\r
\r
## Handoff Contract\r
\r
Before entering a child skill, build this structured handoff contract in reasoning. These are semantic routing fields only, not new Open API request fields.\r
\r
### Required handoff fields\r
\r
```json\r
{\r
  "finalIntentType": "device | space | automation",\r
  "resolvedSpace": {\r
    "name": "\x3CspaceName or null>",\r
    "spaceId": "\x3CspaceId or null>",\r
    "resolutionSource": "route | get_spaces | device_cache | unresolved"\r
  },\r
  "resolvedDevices": [\r
    {\r
      "deviceId": "\x3CdeviceId>",\r
      "deviceName": "\x3Cdisplay name>",\r
      "spaceName": "\x3Cspace name or null>",\r
      "spaceId": "\x3CspaceId or null>",\r
      "matchReason": "exact_name | room_plus_name | type_match | parent_context"\r
    }\r
  ],\r
  "resolvedAutomation": {\r
    "automationId": "\x3CautomationId or null>"\r
  },\r
  "ambiguityState": {\r
    "status": "none | room | device | automation | event_enum",\r
    "questionNeeded": true\r
  },\r
  "operationContext": {\r
    "operation": "query | control | create | update | rename | status | delete",\r
    "cacheFreshness": "fresh | stale | unknown",\r
    "detailsLoaded": false\r
  },\r
  "capabilityValidationMode": "cache_first_generate | query_capabilities_required",\r
  "branchingIntent": {\r
    "needsSplit": false,\r
    "reason": "\x3Coptional reason>"\r
  }\r
}\r
```\r
\r
### Handoff rules\r
\r
- do not hand off the raw user sentence alone\r
- if room scope is already resolved, pass it as `resolvedSpace` instead of forcing the child skill to rediscover it\r
- if several candidate devices remain, preserve them in `resolvedDevices` and ask for clarification before mutation\r
- if the request is an automation update, pass whether current automation details have already been loaded\r
- if a preceding space mutation may have changed room membership, mark `cacheFreshness` as `stale`\r
\r
## Router SOP\r
\r
Follow this order. Do not skip steps.\r
\r
1. Parse which entities are mentioned: `space`, `device`, `automation`.\r
2. Classify the final action target.\r
3. Resolve the anchor entity first: room-first, device-first, or automation-first.\r
4. If the task is a room-scoped device query, use `GetSpacesRequest` only to confirm the room identity when needed, then use `data/devices.json` to reverse lookup the devices in that room.\r
5. Build the handoff contract.\r
6. If ambiguity remains, ask before entering a mutating child workflow.\r
7. Enter the child skill whose domain matches `finalIntentType`.\r
\r
## Shared Recovery And Reliability Rules\r
\r
Response code reminders:\r
\r
- `code: 0` means success\r
- `400` usually means invalid request data\r
- `1001` usually means token expired or invalid\r
- `2030` usually means device not found\r
\r
Recovery rules:\r
\r
- device not found during device or space work: refresh `data/devices.json` once, then re-resolve the device\r
- invalid space update: re-check `spaceId`, mutation scope, and device membership\r
- invalid automation request: move to the automation child skill, re-check schema shape, and upgrade validation mode if needed\r
- network timeout: retry once, then report the failure\r
- space mutation before automation generation: refresh `data/devices.json` or mark `cacheFreshness: "stale"` and stop before create\r
\r
Platform note:\r
\r
- the package uses `aqara devices cache refresh` for the full device cache\r
- if Node.js or the CLI entry cannot run in the current runtime, stop and explain that the CLI path is unavailable instead of inventing ad hoc shell replacements\r
\r
## Forbidden Behavior\r
\r
Never do any of the following:\r
\r
- call Aqara APIs directly with `curl` when an `aqara` command exists\r
- guess request types or identifiers\r
- use stale prose memory or trait glossaries as authority for live state\r
- use `data/devices.json` as if it were an unconditional automation capability whitelist\r
- place automation `name`, `starters`, `condition`, or `actions` directly under top-level `data`\r
- describe impossible state such as "light is off and brightness is 100%"\r
\r
## Reference Index\r
\r
- `aqara-open-api-local/device/SKILL.md` — device cache-first query and control\r
- `aqara-open-api-local/space/SKILL.md` — space listing and mutation\r
- `aqara-open-api-local/automation/SKILL.md` — automation creation and CRUD\r
- `aqara-open-api-local/docs/commands.md` — CLI command catalog\r
- `aqara-open-api-local/data/devices.json` — device cache\r
- `aqara-open-api-local/references/examples.md` — intent-based example index\r
- `aqara-open-api-local/references/automation-http-examples.md` — automation HTTP lifecycle examples