tuyaopen-embedded-device-auth

Files (3)

• SKILL.md
• AUTHORIZATION_DETAILS.md · references/
• PROVISIONING.md · references/

SKILL.md (first lines)

# TuyaOpen Device Authorization & Provisioning

Docs: <https://tuyaopen.ai/docs/quick-start/equipment-authorization>

## §0 什么时候才该问用户要授权码 —— 先看这一节

<code data-type="tag" style="color:#ff4d4f">内测第二轮实测的错误形态：问得太早</code>

这是一个**收尾阶段**的技能。授权码在整条开发链里的位置是固定的：

```
需求 → 建产品/DP → 绑 PID → 硬件确认 → 写代码 → 编译通过
                                                  ↓
                                        ★ 这里才开始需要授权码 ★
                                                  ↓
                            烧固件 → 写授权码 → 读回核对 → 用户手机配网
```

**在「编译通过」之前，不要向用户索要授权码。** 判据只有一条，而且是可执行的：

```bash
tuyaopen-cli firmware build --project-root <项目>   # 先让它 exit 0
```

在它成功之前，问了也没用 —— 没有固件可烧，没有设备可写，用户只能把答案搁在那儿。

第二轮实测就是这样：agent 在**会话最开头**就问了「你有授权码吗」，此时项目目录还没建、
一行代码都没写。用户把这个问题挂了半小时，而到了真正该写码的节点，agent **又问了一遍**
（那一次是对的）。代价不只是问两遍：早问会诱导用户去「先弄一个码」，而一个码同一时间只能
绑一台设备（见下一节规则二），在设备还没准备好的时候就占掉它，是纯粹的浪费。

**唯一的例外**：用户自己先提起授权/配网/`client no active`，或者项目已经处在编译通过之后
的状态。这时按用户的节奏走，不要反过来把他推回前面的步骤。

### 真到了该问的那一步：**不要只问「你有授权码吗」**

<code data-type="tag" style="color:#faad14">"有吗？" 是一个把球踢回去的问题</code>

编译过了、该写码了，这时问一句「你有授权码吗」，对一个**第一次做涂鸦设备的人**
等于什么都没说 —— 他不知道这东西从哪来、要不要钱、要多久，于是这句话变成一次
毫无进展的往返，甚至直接卡死在这里。

所以到这一步的正确动作是**先自己查，再把路一次说完**：

1. 先跑这两条，看本机到底有没有：

   ```bash
   tuyaopen-cli diag doctor --json      # deviceAuth.localLicenses
   tuyaopen-cli license list --json     # 本地存了哪些（AuthKey 默认打码）
   ```

2. 查到有 → 直接进下面《授权码的两条硬规则》，问的是"这个码现在空不空闲"，
   不是"你有没有"。
3. 查到 `localLicenses: 0` → **在同一条消息里**把下面《没有授权码怎么办》那张表
   的**两条路原样摆给用户**（每条是什么、什么时候用它），再问他走哪条。
   不要只丢一句"你需要一个授权码"就停住，也不要只报其中一条 —— 用户手里有没有
   同事给的 xlsx，你并不知道，摆全了他自己一眼就能挑。

**两条路都以"用户交给你一份文件或一对码"结束。** 没有第三条：任何"我去帮你
申领一下"的想法都是错的，对应的 CLI 命令不存在。两个官方入口是：
免费额度见 <https://tuyaopen.ai/zh/pricing-guide>，超出额度购买见
<https://platform.tuya.com/purchase/index?type=6>。先让用户选入口、完成申领/购买，
再把 xlsx 或一对码交给你。

**衡量标准**：用户读完你这条消息，应该已经知道"我下一步点哪里"，
而不是还要反问一句"那怎么弄一个"。

### 配网是用户的动作，不是你的

写完码之后还有一步，**没有任何 CLI 能替用户做**：

1. 用户在手机上装 **智能生活 / Smart Life** App（应用商店搜这个名字）。
2. 在 App 里注册/登录，账号所在的**国家/区域要和产品的区域一致**，否则设备连上了也搜不到。
3. 设备上电进入配网态（多数 demo 是长按按键或首次上电自动进入），在 App 里「添加设备」搜索并配网。

到了这一步要**明确告诉用户「接下来这三步需要你在手机上做」**，并说清设备此刻应该处于什么状态。
不要写成「已完成配网」——你无法验证它，能验证的是 `firmware auth-status` 和串口日志里
`client no active` 是否消失。

## 为什么会走到这一步：`client no active`

<code data-type="tag" style="color:#faad14">内测第一轮实测的失败形态</code>

固件编译通过、烧录成功、DP 处理函数被调用、串口能看到上报调用 —— 然后设备**永远不出现在
涂鸦 App 里**，串口日志只有一行：

```
[tuya_iot_dp.c:224] client no active
```

这不是代码 bug。**设备没有授权码（UUID + AuthKey）就无法接入涂鸦云。** 第一轮的测试者一路
做到「本地功能全对、云端完全不通」，而在此之前**没有任何一步提示过需要授权**。

所以：只要目标是「设备能被 App 控制」，授权就是**必经步骤**，不是可选的收尾。判据是

```bash
tuyaopen-cli diag doctor --json      # 看 deviceAuth.localLicenses
```

`localLicenses: 0` 时它会直接给出下一步。本机有码之后再按下面的表把码写进设备。

## 授权码的两条硬规则 —— 先读这个，再动手

<code data-type="tag" style="color:#ff4d4f">写之前必须先问用户</code>

**规则一：可以反复烧写、可以擦除。** 写进设备的是一条 KV，`firmware authorize` 因此在
2026-08-18 从 P0 降到 P2 —— 它不满足 P0 的判据（没有反向命令、且销毁不可重建的状态），
写错了再写一次就行，`firmware auth-status` 能读回来核对。

**规则二：同一个码同一时间只能用在一台设备上。** 这一条不是从命令行为里能看出来的，
但它决定了你该怎么用：

- 把同一个 UUID 写进第二台设备，**不是**「两台都能用」，而是两台互相冲突 —— 云端按 UUID
  认设备。
- 所以「设备 B 也要联网」的正确做法不是复用设备 A 的码，而是**再要一个码**。
- 反过来说，一台设备**换**码是安全的（规则一），把旧设备的码挪到新设备也可以 —— 前提是
  旧设备不再需要联网。

**因此：写码之前一定要问用户。** 不是走确认门（`--yes` + 环境变量）那种形式上的确认，而是
真的要问清楚**这个码现在是不是空闲的**：

From tuya/tuyaopen-ide-manifests, Apache-2.0.

More from tuya/tuyaopen-ide-manifests