tuyaopen-start

Files (4)

• SKILL.md
• CLI_AND_PROJECT_REFERENCE.md · references/
• ROUTING.md · references/
• resolve_cli.py · scripts/

SKILL.md (first lines)

# TuyaOpen — Start Here

> **Renamed 2026-08-31: `tuyaopen-shared` → `tuyaopen-start`.** The old id was
> removed outright, with no alias — the same rule the retired CLI spellings
> follow, and for the same reason: an alias would keep a stale copy of this
> file installed next to the current one, because `pruneRetiredInstalls` treats
> an alias-resolvable id as still live. `tuyaopen-cli skills install` deletes
> the old directory on its next run. The name is the point: this is the file to
> read **first**, and "shared" read like a library nobody had to open.

This skill carries no action of its own. It is the one place the load-bearing
facts about the `tuyaopen-cli` CLI and the skill catalogue are written **once** —
every other TuyaOpen skill should link here instead of restating them, and
should say "not in scope, see skill `tuyaopen-start`" rather than naming
sibling skills by name (see § *Routing table* for why).

## 0. Order of operations — install and read the skills BEFORE you act

This is first because it is the single most expensive mistake made in beta
round 1, by the tester's own account: *"读的时机偏晚"* — the catalogue was
synced at the very start, and the skills were installed and read only **after**
a wrong command recipe had already been handed to the user.

Two concrete costs from that one run:

- Devplat writes take `--dry-run` → `--confirm <token>` rather than `--yes`,
  and `product solution-list` always returns empty — `custom-list` is the
  real listing call. The wrong recipe — `solution-list` + `--yes` — had
  already been sent when the reference stating this was finally read.
- `tuyaopen-start` § 8 draws the project layout (`.tuyaopen/` +
  `source/embedded/`). It was instead re-derived from a `firmware build` error
  and rebuilt by hand.

`iot-product-workflow` was installed and never opened. It is the
end-to-end orchestrator; for anything shaped like "build me a device", read it
**first** and let it route you.

```bash
# 1. catalogue (once per machine)
tuyaopen-cli manifests sync --yes
# 2. what exists, and which one covers this task — match on whenToUse, not the id
tuyaopen-cli skills list --json
# 3. install the ones that do, then READ their SKILL.md before the first action
tuyaopen-cli skills install --ids <ids> --yes
# 4. confirm your own tool can SEE them — `install` reports this now
#    (data.reachability; `tuyaopen-cli diag doctor --json` → agentSkills says the same)
```

### 0.0 Establish the machine's facts — don't take them from the task brief

<code data-type="tag" style="color:#faad14">前两轮这些事实是写在任务提示词里的。那是错的位置。</code>

一个任务书会告诉你「板子接在 `/dev/ttyACM0`」「SDK 在 `~/TuyaOpenIDE/TuyaOpenSDK`」
「登录要用户点浏览器」。**这些不该由提示词提供** —— 提示词换一个人写就会漏、会过时、会写错，
而这些都是**可以自己查**的。你的第一批动作就是把它们查清楚：

| 你需要知道的 | 自己怎么查 | 查不到时问用户什么 |
|---|---|---|
| CLI 在哪、是哪一份 | § 1（`tuyaopen-cli` 通常**不在** `PATH` 上） | — |
| 环境/SDK 是否就绪、SDK 根在哪 | `tuyaopen-cli diag doctor --json` → `sdk` 块；skill `tuyaopen-embedded-env-setup` | 没有 SDK 时**不要**擅自克隆 12 GB —— 先说要下什么、多大 |
| 目录/技能目录状态 | 同上 → `manifests`、`agentSkills` 块（§ 0.1） | — |
| 登录状态 | 同上 → `credential` 块；`tuyaopen-cli credential status` | 未登录 → §「需要人做的四件事」 |
| **有哪些串口、哪个是哪个** | `tuyaopen-cli firmware list-ports --json`（>1 个口时它会给 `hint`） | 列出来**让用户确认哪个是目标板**，不要挑一个就烧 |
| 项目状态 | `tuyaopen-cli project info --json` | — |
| 本机有没有授权码 | `tuyaopen-cli diag doctor --json` → `deviceAuth.localLicenses` | skill `tuyaopen-embedded-device-auth` § 0（**编译通过之后**才问） |
| **目标平台是否就绪**（不是"SDK 是否就绪"） | 同上 → `platforms` 块：`installed` / `missing` | `missing` 里有你的目标板 → 首次编译要先克隆子 SDK 并下载交叉工具链（T5AI 那份约 150 MB），**先告诉用户要下多少**再动手 |

`sdk` 块的三个布尔说的是**核心 clone**，三个全绿 ≠ 你的目标平台能编。实测过一台
`sdk` 全绿、而 8 个平台里 6 个没有 checkout 的机器 —— 照着绿灯去编 ESP32，等来的是一次
没人预告过的下载。要判断"这块板能不能编"，看 `platforms`，不是 `sdk`。

**`--network` 默认不开。** `diag doctor` 其余每一项都是离线且瞬时的，网络探测会真的发请求
（13 个域名，各 ~5s 超时），所以它是显式 opt-in。**该加的三种情况**：克隆 / `sdk env-pull` /
工具链下载失败时；云命令报网络错时；以及第一次排查"为什么卡住"时 ——
`tuyaopen-cli diag doctor --network --json` 的 `network.brokenCategories` 直接告诉你断的是哪一类
（`tuya` / `miniapp` / `git` / `npm`），比逐个 curl 快。平时不要加。

**规则：能查的就查，查不到就问，不要假设，也不要相信提示词里关于本机的说法胜过 `diag doctor`。**
提示词是需求的来源，不是环境的来源。

### 0.0a 需要人做的四件事 —— 这些你做不了，早点说清楚

有四类动作**没有任何 CLI 能替用户完成**。走到它们时，**明确说「这一步需要你做」**，
说清楚要点什么、以及做完之后设备/页面应该是什么状态。不要卡在那里等，也不要假装做完了。

| 动作 | 你能做的 | 用户必须做的 |
|---|---|---|
| **平台登录** | `tuyaopen-cli credential login --emit-url` —— 它把 URL 打到 stdout 一行 JSON 并**等待** | 在浏览器里打开那个 URL 完成授权。**把 URL 给他**，不要只说"请登录" |
| **申领 appid / 网页步骤** | appid 只在网页控制台签发——说清在哪个产品下申领；有 appid 之后的版本页 / 绑定页参数化 URL 由 `tuyaopen-cli miniapp upload` 的 `webSteps` 信封携带（2026-09-28 起，原 `tuyaopen-miniapp` § 0.2 ③ 锚点在 capability-broker 迁移中已随正文消失） | 在网页上操作 |
| **授权码** | 说明为什么需要、怎么取（skill `tuyaopen-embedded-device-auth`） | 提供码，并确认它当前没被别的设备占用 |
| **手机配网** | 说清前置状态（已写码、设备处于配网态） | 装智能生活 / Smart Life，账号区域与产品一致，App 里添加设备 |

**`--emit-url` 是这里唯一的机器通道。** 第一轮的测试者拿不到登录链接，把登录这一项打了 1/5 分 ——
不是因为 CLI 没打印，而是因为它打在 stderr 上而调用方的采集层把它缓冲了。stdout 那一行 JSON
是为你准备的。

#### 怎么把「需要人做」这件事**说出来** —— 拿到 URL 只是一半

拿到了链接，还会在最后一步丢掉。2026-08-27 实测：agent 正确拿到了登录 URL，然后把它
**复述成了回复中间的一段散文**（"Please open this URL and sign in with your Tuya
account…"）。用户的原话是**容易忽略** —— 链接在对话里滚过去了，登录就停在那儿，而且
没有任何东西说明为什么停住。CLI 那侧已经加了边框和 ACTION REQUIRED 标记，但**决定这
东西长什么样的是你，不是 CLI**。

所以遇到上表四类动作中的任何一类：

- **单独成块，放在回复最前面。** 不要夹在解释、进度汇报或下一步计划中间。
- **URL / 授权码逐字照抄，独占一行。** 不要缩短、不要加 markdown 链接语法把它藏进文字里、
  不要"（链接见上）"。用户要能一眼选中它。
- **说清楚在等什么**：哪个进程在等、等多久超时、他做完之后你会怎么确认。
- **然后停下来。** 不要接着跑后面的步骤假装它已经完成了 —— 后面每一步都会以一种和根因
  无关的方式失败。

判据很简单：**用户扫一眼你的回复，能不能在一秒内找到他要点的那个东西。**

### 0.1 A green install is not proof your tool can see the skills

Round 2 installed 19 skills, exit 0, both project mirrors populated — and the
tester's `/skills` listing showed **none of them**. The install was fine. The
reason is a trap worth knowing by name:

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

More from tuya/tuyaopen-ide-manifests