@seeed-studio/sensecraft-cli 0.4.3 → 0.4.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/INSTALL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # SenseCraft CLI install guide
2
2
 
3
- How to install, upgrade, and uninstall `sensecraft-cli`, and how to connect Agent Skills to Cursor and other tools. Commands and sign-in: [`README.md`](README.md) (Chinese: [`README-zh.md`](README-zh.md)).
3
+ How to install, upgrade, and uninstall `sensecraft-cli`, and how to connect Agent Skills to Cursor and other tools. Commands and sign-in: [`README.md`](README.md) (Chinese: [`README.zh.md`](README.zh.md)).
4
4
 
5
5
  ## 1. Requirements
6
6
 
@@ -393,6 +393,6 @@ sensecraft-cli --version
393
393
  | Doc | Contents |
394
394
  |-----|----------|
395
395
  | [`README.md`](README.md) | English install and config summary |
396
- | [`README-zh.md`](README-zh.md) | Chinese command reference |
396
+ | [`README.zh.md`](README.zh.md) | Chinese overview |
397
397
  | [`skills/README.md`](skills/README.md) | Skills layout and agent conventions |
398
398
  | [`LICENSE`](LICENSE) | MIT |
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  The official command-line tool for [SenseCraft](https://sensecraft.seeed.cc). Read sensor data, create models, and publish applications — for developers and AI agents.
4
4
 
5
- Chinese: [README-zh.md](README-zh.md).
5
+ Chinese: [README.zh.md](README.zh.md).
6
6
 
7
7
  ## Install
8
8
 
package/README.zh.md ADDED
@@ -0,0 +1,175 @@
1
+ # sensecraft-cli
2
+
3
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
4
+ [![Go Version](https://img.shields.io/badge/go-%3E%3D1.25-blue.svg)](https://go.dev/)
5
+ [![npm version](https://img.shields.io/npm/v/@seeed-studio/sensecraft-cli.svg)](https://www.npmjs.com/package/@seeed-studio/sensecraft-cli)
6
+
7
+ [中文](./README.zh.md) | [English](./README.md)
8
+
9
+ [SenseCAP](https://sensecap.seeed.cc) 设备与 [SenseCraft AI](https://sensecraft.seeed.cc) 的命令行工具。一把 OpenAPI Access Key 即可访问设备、遥测、应用、模型、文件和云设备。给人用,也给 AI Agent 用。Skills 在 [`skills/`](./skills/)。
10
+
11
+ [安装](#安装) · [AI Agent](#给-ai-agent) · [Skills](#agent-skills) · [登录](#登录) · [命令](#命令) · [进阶](#进阶) · [安全](#安全)
12
+
13
+ ## 能做什么
14
+
15
+ | 类别 | 能力 |
16
+ |------|------|
17
+ | 设备 | 列出、查看、绑定、解绑网关、节点和开发套件 |
18
+ | 分组 | 创建分组、移动设备 |
19
+ | 遥测 | 最新值、历史记录、折线聚合点 |
20
+ | 应用 | CodeCraft Hub:浏览应用,管理自己的应用、物料和活动 |
21
+ | 模型 | 搜索模型库,上传和发布模型 |
22
+ | 文件 | 上传本地文件,得到 `file_url` |
23
+ | 云设备 | 列出 Jetson 等云设备,部署模型 |
24
+ | reCamera | 检查经典 reCamera 的应用或模型,并打开控制台部署页 |
25
+
26
+ 网页控制台是 [https://sensecraft.seeed.cc](https://sensecraft.seeed.cc)。
27
+
28
+ ## 安装
29
+
30
+ 需要 Node.js 16 及以上,以及能访问 SenseCAP 和 SenseCraft AI 的网络。从源码构建另需 Go 1.25 及以上(见 `go.mod`)。
31
+
32
+ ```bash
33
+ npx @seeed-studio/sensecraft-cli install
34
+ sensecraft-cli --version
35
+ ```
36
+
37
+ Windows 上的命令名是 `sensecraft-cli.cmd`。PATH、升级和卸载见 [`INSTALL.md`](INSTALL.md)。
38
+
39
+ ### 三步上手
40
+
41
+ 在 SenseCAP 门户创建 OpenAPI Access Key,然后:
42
+
43
+ ```bash
44
+ # 1. 写入钥匙。--site 为 Global 或 China,省略时是 Global
45
+ sensecraft-cli auth add --key-id <Key ID> --access-key <Access Key> --site Global
46
+
47
+ # 2. 确认。不会打印 Access Key
48
+ sensecraft-cli auth info
49
+
50
+ # 3. 调用接口
51
+ sensecraft-cli device list
52
+ ```
53
+
54
+ 交互终端里可以不带参数运行 `auth add`,按提示填写。
55
+
56
+ ## 给 AI Agent
57
+
58
+ 和用户一起完成。不要让用户把 Access Key 贴进对话,也不要在会被记录的命令行里带上这串密钥。
59
+
60
+ 1. 如果没有命令,先安装:
61
+
62
+ ```bash
63
+ npx @seeed-studio/sensecraft-cli install
64
+ ```
65
+
66
+ 2. 请用户在自己的电脑上运行 `auth add`。
67
+ 3. 确认钥匙已经生效:
68
+
69
+ ```bash
70
+ sensecraft-cli auth info
71
+ ```
72
+
73
+ 4. 再跑只读命令,例如 `sensecraft-cli device list` 或 `sensecraft-cli app list --public`。
74
+ 5. 先读 [`skills/sensecraft-cli/SKILL.md`](skills/sensecraft-cli/SKILL.md),它会转到对应的产品说明。
75
+
76
+ 解绑、删除、发布、部署这类写操作,要等用户单独确认之后才能加 `--yes`。
77
+
78
+ ## Agent Skills
79
+
80
+ | Skill | 说明 |
81
+ |-------|------|
82
+ | [`sensecraft-cli`](skills/sensecraft-cli/SKILL.md) | SenseCraft Data、SenseCraft AI 和 CodeCraft Hub |
83
+ | [`create-app`](skills/sensecraft-cli/create-app/SKILL.md) | 把本地项目做成 CodeCraft Hub 应用 |
84
+
85
+ 全局 npm 安装之后:
86
+
87
+ ```bash
88
+ ls "$(npm root -g)/@seeed-studio/sensecraft-cli/skills"
89
+ ```
90
+
91
+ ## 登录
92
+
93
+ | 命令 | 说明 |
94
+ |------|------|
95
+ | `auth add` | 校验 Access Key,写入本机,并设为当前钥匙 |
96
+ | `auth info` | 显示站点、组织 ID 和 Key ID |
97
+
98
+ ```bash
99
+ sensecraft-cli auth add --key-id <Key ID> --access-key <Access Key> --site Global
100
+ sensecraft-cli auth info
101
+ ```
102
+
103
+ | `--site` | SenseCAP OpenAPI | SenseCraft AI OpenAPI |
104
+ |----------|------------------|------------------------|
105
+ | `Global` | `https://sensecap.seeed.cc/openapi` | `https://api-gateway.seeed.cc/openapi` |
106
+ | `China` | `https://sensecap.seeed.cn/openapi` | `https://api-gateway.seeed.cc/openapi` |
107
+
108
+ 中国站仅支持 SenseCraft Data。SenseCraft AI 和 CodeCraft Hub 请用 Global。同一把 Access Key 用 HTTP Basic 调用接口:用户名是 Key ID,密码是 Access Key。
109
+
110
+ ## 命令
111
+
112
+ 参数用 `sensecraft-cli <command> --help` 查看。每一类一条示例:
113
+
114
+ ```bash
115
+ sensecraft-cli device list --device-type 1
116
+ sensecraft-cli data latest --eui <EUI>
117
+
118
+ sensecraft-cli app list --public --sort popular
119
+ sensecraft-cli model list --public
120
+ sensecraft-cli file upload --type 1 --path ./cover.png --for-app
121
+ sensecraft-cli cloud device list
122
+ sensecraft-cli recamera check --model-id <id>
123
+ ```
124
+
125
+ | 命令 | 说明 |
126
+ |------|------|
127
+ | `device` | 网关(`--device-type 1`)、节点(`2`,默认)、开发套件(`3`) |
128
+ | `group` | 设备分组 |
129
+ | `data` | 最新遥测、历史、折线点 |
130
+ | `app` | CodeCraft Hub 和我的应用。不传 `--public` 时列出自己的应用 |
131
+ | `model` | 模型库。不传 `--mine` 时列出公开模型 |
132
+ | `file` | 上传。`--type`:`1` 图片,`2` 模型,`3` 应用,`4` 固件,`5` 静态资源(需要 `--flow-id`),`6` 压缩包 |
133
+ | `cloud` | 云设备,以及部署模型 |
134
+ | `recamera` | 检查,或打开控制台页面。烧录在网页上完成 |
135
+ | `update` | 安装 npm 上的最新版本 |
136
+
137
+ `app list --sort` 取 `popular`、`newest` 或 `likes`。常用 `--uniform-type`:`40` reCamera,`32` XIAO ESP32S3,`53` reCamera Pro。
138
+
139
+ ## 进阶
140
+
141
+ 成功的数据命令把缩进 JSON 打到 stdout。`auth add` 和 `auth info` 打可读文本。失败在 stderr,退出码非 0。
142
+
143
+ `sensecraft-cli --version` 打印 npm 包版本。直接 `go build` 的二进制打印 `dev`。
144
+
145
+ 配置文件名是 `sensecraft.json`。
146
+
147
+ | 运行方式 | 文件位置 |
148
+ |----------|----------|
149
+ | npm 安装 | macOS / Linux:`~/.config/sensecraft-cli/sensecraft.json`。Windows:`%APPDATA%\sensecraft-cli\sensecraft.json` |
150
+ | `go build` 的二进制 | 当前目录下的 `sensecraft.json` |
151
+
152
+ 命令成功后,stderr 上可能各出现一条英文提示,同一条 24 小时内只出现一次:`Warning:` 表示有新版本,运行 `sensecraft-cli update`;`Notice:` 写出正在进行的活动名称、日期和链接。交互终端里会再问 `Ignore this activity? [y/N]`。
153
+
154
+ ## 从源码构建
155
+
156
+ ```bash
157
+ go build -o sensecraft-cli .
158
+ ./sensecraft-cli --version
159
+
160
+ ./script/build.sh
161
+ ```
162
+
163
+ `./script/build.sh` 按 `packages/cli/package.json` 的版本号交叉编译到 `dist/`。
164
+
165
+ ## 安全
166
+
167
+ Access Key 是密钥。不要提交进仓库,也不要贴进 Agent 对话。`auth info` 只打印 Key ID。
168
+
169
+ 解绑、删除、发布、部署在带上 `--yes` 之前不会执行。Agent 必须先得到用户对这一次操作的确认,再加这个参数。
170
+
171
+ 本工具不通过 USB 或串口烧录固件。`recamera open` 只打开控制台部署页。
172
+
173
+ ## 许可证
174
+
175
+ [MIT](LICENSE)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@seeed-studio/sensecraft-cli",
3
- "version": "0.4.3",
3
+ "version": "0.4.5",
4
4
  "description": "SenseCAP / SenseCraft AI cloud CLI (devices, apps, models, files, cloud deploy)",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -26,7 +26,7 @@
26
26
  "skills",
27
27
  "LICENSE",
28
28
  "README.md",
29
- "README-zh.md",
29
+ "README.zh.md",
30
30
  "INSTALL.md"
31
31
  ],
32
32
  "os": [
@@ -39,7 +39,7 @@ SenseCraft Data: [`references/data.md`](references/data.md).
39
39
  sensecraft-cli auth init --device-code <device_code> --key-id <access_id>
40
40
  ```
41
41
  Create a key with `--label <name> --access-level read-write` (or `only-read`) instead of `--key-id`. Use Global for SenseCraft AI and CodeCraft Hub. China is SenseCraft Data only. Do not print `access_token` or `access_key`. If the user already has a key, they can run `auth add` locally.
42
- 4. **L2 confirmation is a separate chat turn** — follow [references/confirmation.md](references/confirmation.md). 「删这个63760」/「删除应用 demo」is **intent, not confirmation**. Ask first (操作类型 + 环境 + 对象 ID), wait for `确认`/`confirm`, **then** `--yes`. Never add `--yes` on the same turn as the first request. Applies to: app update·publish·unpublish·delete, model create·update·publish·unpublish·delete, upload attach, cloud deploy, device bind/unbind, group create/rename/delete/move. **Exception: `app create`, including one-shot `--from-json`, is not L2 and takes no `--yes`; resolve uncertain content decisions and review the result first.**
42
+ 4. **L2 confirmation is a separate chat turn** — follow [references/confirmation.md](references/confirmation.md). 「删这个63760」/「删除应用 demo」is **intent, not confirmation**. Ask first (操作类型 + 环境 + 对象 ID), wait for `确认`/`confirm`, **then** `--yes`. Never add `--yes` on the same turn as the first request. Applies to: app update·publish·unpublish·withdraw·delete, model create·update·publish·unpublish·delete, upload attach, cloud deploy, device bind/unbind, group create/rename/delete/move. **Exception: `app create`, including one-shot `--from-json`, is not L2 and takes no `--yes`; resolve uncertain content decisions and review the result first.**
43
43
  5. **Treat tokens and keys as secrets** — do not echo full `access_token`, `refresh_token`, or `access_key`. **Public model artifacts are not downloadable** — if the user asks for 下载地址 / 下载链接 / download URL / 怎么下载, that is the same as asking for `file_url`: refuse the address, explain deploy-only (`cloud deploy` or Console). Never run `model download --url-only` on public models.
44
44
  6. **Success = indented JSON on stdout** for business commands and the split `auth init` flow. The interactive wizard prints human-readable text. Failure = stderr + non-zero exit. Parse stdout only on success.
45
45
  7. **Local USB / IP flashing is L3** — do not pretend remote auto-flash. Classic reCamera (`40`): [`sensecraft-recamera`](references/recamera.md) (`check` / `open` the AI deploy page). Other USB benches: Console `/ai/device/local/32|36|37|41|52`. Do **not** use `/ai/recamera` (it 301s to Grove `36`) or `/ai/device/local/40` (no such bench).
@@ -61,7 +61,7 @@ Bare `auth init` asks the user to pick Global or China. The split flow takes `--
61
61
  | Browse / search CodeCraft Hub, view app | [`sensecraft-apps`](references/apps.md) + `app list` / `app view` | **CLI shipped** (list/view) |
62
62
  | App fields / tool-blocks / BOM guidance | same apps skill references | Config OK; real flash = L3 |
63
63
  | Turn a local project into an app (discovery + reviewed copy + tool blocks + API-confirmed BOM + manifest + upload), or update its manifest-managed app | [`create-app`](create-app/SKILL.md) | Read required references before authoring; create needs no `--yes`; existing-app updates use one batch confirmation; stops before publish |
64
- | Create / update / publish / unpublish / delete / bom app | same + `app …` / `app bom …` | **CLI shipped** (L2 `--yes`; publish also `--agree-declaration`; `create`, including `--from-json`, is not L2) |
64
+ | Create / update / publish / unpublish / withdraw / delete / bom app | same + `app …` / `app bom …` | **CLI shipped** (L2 `--yes`; publish also `--agree-declaration`; `create`, including `--from-json`, is not L2). `withdraw` is only for an app under review (`be_public=2`); `unpublish` is only for an already public app |
65
65
  | Upload image/file/firmware/static/archive and obtain `file_url` | [`sensecraft-files`](references/files.md) + `file upload` | Types `1`–`2` require `--model-id`/`--app-id --yes`/`--for-app`/`--unlinked`; type `5` requires `--flow-id`; types `3`–`6` direct |
66
66
  | Model library search/view/download/constants | [`sensecraft-models`](references/models.md) | **CLI shipped** |
67
67
  | Upload / publish / unpublish / delete model | same + `model upload --id --yes` / `create\|update\|publish\|unpublish\|delete` | Attach bumps patch version like Console |
@@ -96,7 +96,7 @@ SenseCraft Data telemetry → pick a public model → deploy to Jetson:
96
96
  | Level | Meaning | Examples |
97
97
  |-------|---------|----------|
98
98
  | L1 Scriptable | Agent may run directly | list / view / auth info / `auth init --no-wait` then later `--device-code` |
99
- | L2 Confirm | Ask user first | publish (+ declaration), unpublish, delete, deploy |
99
+ | L2 Confirm | Ask user first | publish (+ declaration), unpublish, withdraw, delete, deploy |
100
100
  | L3 Interactive | Human-in-the-loop | bare `auth init`, Web Serial flash, payment |
101
101
  | L4 Ops-only | Do not expose to end-user Agent | Admin `judge_app` |
102
102
 
@@ -104,7 +104,7 @@ SenseCraft Data telemetry → pick a public model → deploy to Jetson:
104
104
 
105
105
  Published commands use an Access Key. SenseCraft Data uses its OpenAPI. SenseCraft AI and CodeCraft Hub use `{ai-host}/openapi`.
106
106
 
107
- 1. **CodeCraft Hub** — `app` list/view/fields/blocks/doc; create/update; publish/unpublish/delete (L2); BOM search/list/set; tool-block config via JSON (real flash = L3).
107
+ 1. **CodeCraft Hub** — `app` list/view/fields/blocks/doc; create/update; publish/unpublish/withdraw/delete (L2); BOM search/list/set; tool-block config via JSON (real flash = L3). `withdraw` unlocks an app under review. `unpublish` does not.
108
108
  2. **SenseCraft AI** — model library (list/view/constants; **private** download only; public models deploy-only); `model upload --id --yes`; create/update; publish/unpublish/delete (L2). Cloud devices: `cloud device` / `cloud deploy` / `cloud order`. Classic reCamera 40: `recamera check` / `recamera open` (flash is L3).
109
109
  3. **Files** — `file upload` is shared. Types 1–2 require `--model-id` / `--app-id --yes` / `--for-app` / `--unlinked` before the OSS POST. Type 5 also requires `--flow-id`.
110
110
  4. **Local USB** — Other benches: Console `/ai/device/local/32|36|37|41|52`.
@@ -68,7 +68,7 @@ Read [manifest.md](references/manifest.md) and the template. Populate the canoni
68
68
 
69
69
  - Hash the exact local image and artifact bytes to be uploaded. Keep firmware/model/archive paths, sizes, hashes, and destination block IDs in review notes; those paths do not belong in public tool configs.
70
70
  - Local images have `file_url: null` until uploaded. A pending tool URL is not a fake `https://example.com/...` link. Explain every pending input in review notes and the user summary.
71
- - Use the field locations from the references: every tool, including `flash-firmware`, stores its settings inside one `block.config` object. The ordered blocks array is flat; tool settings are nested. SKU and `uniform_type` are distinct. Sizes are strings.
71
+ - Use the field locations from the references: every tool, including `flash-firmware`, stores its settings inside one `block.config` object. Do not repeat them on the block. The ordered blocks array is flat; tool settings are nested. SKU and `uniform_type` are distinct. Sizes are strings.
72
72
  - Store no access keys, device keys, SDK tokens, or personal credentials in the manifest, notes, or distributed artifacts. Check candidate archives/binaries for embedded credentials; if found, identify the affected artifact without echoing the secret and resolve a clean distribution path with the user before upload.
73
73
  - After gather and each successful push: in git, keep the canonical manifest reviewable in the working tree and follow the user's established Git workflow; outside git, also write an immutable `.sensecraft/archive/<manifest-stem>.YYYYMMDD-HHmmss.json` snapshot. Avoid overwriting a same-second snapshot. Retain the verified sync baseline per the manifest contract; do not hand versioning commands to the user.
74
74
 
@@ -92,7 +92,15 @@ Update the review notes with corrections, evidence, remaining gaps, and readines
92
92
 
93
93
  ## 6. Upload and create once
94
94
 
95
- 1. Read the upload references. Run `sensecraft-cli auth info`. If no Access Key is active, use the split `auth init` flow in [`../SKILL.md`](../SKILL.md). Do not run bare `auth init`. Recheck that selected files still match their reviewed hashes. Upload only reviewed assets; reuse unchanged URLs. Images: `file upload --path <image> --type 1 --for-app`. Firmware: `--type 4`. Other artifacts: select the actual type/flags from the reference. App images use at most 16 JPG/JPEG/PNG/GIF/WebP files, each ≤5 MB; other artifacts are ≤100 MB.
95
+ 1. Read the upload references. Run `sensecraft-cli auth info`. If no Access Key is active, use the split `auth init` flow in [`../SKILL.md`](../SKILL.md). Do not run bare `auth init`. Recheck the environment and that selected files still match their reviewed hashes. Upload only reviewed assets; reuse unchanged URLs. Images: `file upload --path <image> --type 1 --for-app`. Firmware: `--type 4`. Other artifacts: select the actual type/flags from the reference. App images use at most 16 JPG/JPEG/PNG/GIF/WebP files, each ≤5 MB; other artifacts are ≤100 MB.
96
+
97
+ For Muse firmware, scan the exact file selected for upload before `file upload --type 4`. A complete SDK token is `mgst_` followed by 43 characters from `[A-Za-z0-9_-]`. The short `mgst_` prefix used by firmware format validation is not a credential match. Keep the scan quiet so matching values stay local:
98
+
99
+ ```bash
100
+ grep -aqE 'mgst_[A-Za-z0-9_-]{43}' <firmware-file>
101
+ ```
102
+
103
+ Exit code **1** means no complete token was found and this check passes. **0** means a token pattern was found: rebuild without the token and scan again. **2 or higher** is a path or read error to fix before retrying. Report only pass, match, or check error. Do not print matching values.
96
104
  2. Write returned `file_url` values into the canonical manifest as each upload succeeds, keeping image order. Update the intended tool/media fields and the artifact ledger. For firmware fill `config.firmware_url`, `config.firmware_name`, and string `config.firmware_size` on the target block. Never expose temporary signed upload URLs in review prose.
97
105
  3. Validate again, inspect the final projection, and reassess readiness. Required deployment inputs must now be filled unless the user chose an incomplete draft. Apply the [activity submission rules](../references/app-fields.md#activity-selection-during-app-authoring) when relevant and follow [manifest → CLI payload](references/manifest.md#manifest--cli-payload). Omit local bookkeeping; images become URLs with `pic_url = images[0]`; no images → omit both keys, never `images: []`. Never send `be_public` or `privacy`.
98
106
  4. Write `.sensecraft/<manifest-stem>.payload.json`, then create **without `--yes`**:
@@ -111,7 +119,7 @@ Read the references for the affected sections before editing them. Preserve the
111
119
  Handle activity participation on updates per [app-fields.md](../references/app-fields.md#activity-selection-during-app-authoring) and the manifest projection rules.
112
120
 
113
121
  1. Edit the manifest first, increment `sync.local_revision`, and validate. Recheck auth: `identity.remote_type` and `org_id` must match. A mismatch requires switching auth or an explicit decision to adopt the environment; do not write across environments silently.
114
- 2. Read `app view --id <app_id> --sketch`. Under review (`be_public=2`) → stop and explain the lock. Compare with the last verified baseline per [manifest sync](references/manifest.md#sync--local-vs-remote-bookkeeping). Detect outside edits, merge non-conflicting changes, and present conflicts as concrete choices. No verified baseline after a partial create → inspect current remote state and reconcile; never assume it is empty.
122
+ 2. Read `app view --id <app_id> --sketch`. Under review (`be_public=2`) → stop and explain the lock. Do not give `/application/edit` or `console_url`; the editor rejects the save. Editing resumes only after `app withdraw` (separate confirmation), not `app unpublish`. Compare with the last verified baseline per [manifest sync](references/manifest.md#sync--local-vs-remote-bookkeeping). Detect outside edits, merge non-conflicting changes, and present conflicts as concrete choices. No verified baseline after a partial create → inspect current remote state and reconcile; never assume it is empty.
115
123
  3. Complete local preparation and review before any outstanding L2 confirmation. Describe environment, app name/ID, and the entire pending batch. Follow the [confirmation protocol](../references/confirmation.md), honoring valid approval already given for that batch; do not ask per field/upload/BOM row.
116
124
  4. Upload changed assets and send only changed sections, using session-owned transients under `.sensecraft/`:
117
125
 
@@ -39,6 +39,16 @@ TOOL_CONFIG_FIELDS = {
39
39
  "aily-blockly": {"project_id", "device_id"},
40
40
  }
41
41
  FLASH_ADDRESSES = {"0x0", "0x4000", "0x10000", "0x90000"}
42
+ # Keep aligned with museDeviceTable (muse: true) and tool-blocks.md.
43
+ MUSE_GADGET_SKUS = {
44
+ "114993068", # SenseCAP Indicator
45
+ "113991315", "113991275", # SenseCAP Watcher
46
+ "100073581", # reTerminal E1001
47
+ "100017057", # reTerminal E1002
48
+ "100069905", # XIAO 1.47" Touch Display
49
+ "100056818", # reTerminal Sticky
50
+ }
51
+ BOM_QUANTITY_MAX = 999
42
52
  SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
43
53
  QUANTITY_RE = re.compile(r"^[1-9][0-9]*$")
44
54
  # Shapes that must never appear in fields that get published. Matches
@@ -312,6 +322,10 @@ def main():
312
322
  vio(f"{label}: config.{key} must be a JSON boolean")
313
323
  if cfg.get("muse_gadget") is True and cfg.get("full_flash") is True:
314
324
  vio(f"{label}: config.full_flash must be false when config.muse_gadget is true")
325
+ elif cfg.get("muse_gadget") is True or cfg.get("full_flash") is True:
326
+ device_id = cfg.get("device_id")
327
+ if not isinstance(device_id, str) or device_id.strip() not in MUSE_GADGET_SKUS:
328
+ vio(f"{label}: config.muse_gadget and config.full_flash can be true only for a Muse device SKU")
315
329
  if block_type == "node-red":
316
330
  if cfg.get("flow_data") is not None and not isinstance(cfg["flow_data"], (dict, list)):
317
331
  vio(f"{label}: config.flow_data must be an object or array, not a JSON string")
@@ -348,8 +362,9 @@ def main():
348
362
  vio(f"bom.materials[{i}] (catalog row): missing {req!r}")
349
363
  if not isinstance(row.get("name"), str) or not row["name"].strip():
350
364
  vio(f"bom.materials[{i}].name must be a non-empty string")
351
- if not isinstance(row.get("quantity"), str) or not QUANTITY_RE.fullmatch(row["quantity"]):
352
- vio(f"bom.materials[{i}].quantity must be a positive integer string")
365
+ quantity = row.get("quantity")
366
+ if not isinstance(quantity, str) or not QUANTITY_RE.fullmatch(quantity) or int(quantity) > BOM_QUANTITY_MAX:
367
+ vio(f"bom.materials[{i}].quantity must be an integer string from 1 to {BOM_QUANTITY_MAX}")
353
368
  if "note" in row and not isinstance(row["note"], str):
354
369
  vio(f"bom.materials[{i}].note must be a string")
355
370
  if "buy_url" in row and row["buy_url"] != "" and not http_url(row["buy_url"]):
@@ -62,13 +62,13 @@ Formats JPG/JPEG/PNG/GIF/WebP, ≤ 5 MB each, prefer 4:3. SVG is rejected by the
62
62
 
63
63
  ## `deployment.blocks`
64
64
 
65
- Flat ordered array, copied through to the payload unchanged. Blocks before the first `step` = introduction; each `step` starts a deploy step. Read [../../references/tool-blocks.md](../../references/tool-blocks.md) before selecting or configuring tools. After `file upload --type 4`, write `config.firmware_url`, `config.firmware_name`, and string `config.firmware_size` inside the `flash-firmware` block. Every tool uses one nested `config` object. The flat array layout does not permit flat tool settings; modern blocks are not wrapped on read. A needed block with missing inputs may stay in a local draft, but the app is not deployment-ready until those inputs have a usable path; mark gaps in review notes rather than inventing URLs or IDs.
65
+ Flat ordered array, copied through to the payload unchanged. Blocks before the first `step` = introduction; each `step` starts a deploy step. Read [../../references/tool-blocks.md](../../references/tool-blocks.md) before selecting or configuring tools. After `file upload --type 4`, write `config.firmware_url`, `config.firmware_name`, and string `config.firmware_size` inside the `flash-firmware` block. Every tool uses one nested `config` object. Do not repeat those fields on the block. A needed block with missing inputs may stay in a local draft, but the app is not deployment-ready until those inputs have a usable path; mark gaps in review notes rather than inventing URLs or IDs.
66
66
 
67
67
  ## `bom.materials`
68
68
 
69
69
  Seeed catalog rows carry `id` (SKU), `quantity`, `name`, `note`, `buy_url` — never `price`/`pic_url` (resolved by SKU server-side). Set `id` from the live `app bom search` result's `sku`, not an internal product ID. Preserve the lookup evidence in review notes. Custom rows carry `name` + `quantity` (required) and optionally `note` / `buy_url` — no `id`, no image, no price. Read [catalog verification and BOM fields](../../references/app-fields.md#catalog-verification-before-authoring-a-bom) before writing rows; custom entries are not API-confirmed catalog products.
70
70
 
71
- Names are non-empty strings and quantities are positive integer strings such as `"1"`. A custom row omits `id` entirely; `"id": null` is not a custom row. Notes and purchase URLs, when supplied, are strings; an optional empty purchase URL is allowed, but a non-empty one must be HTTP(S). Local shape validation cannot prove a catalog match or the correct quantity.
71
+ Names are non-empty strings and quantities are integer strings from `"1"` to `"999"`. A custom row omits `id` entirely; `"id": null` is not a custom row. Notes and purchase URLs, when supplied, are strings; an optional empty purchase URL is allowed, but a non-empty one must be HTTP(S). Local shape validation cannot prove a catalog match or the correct quantity.
72
72
 
73
73
  ## `sync` — local vs remote bookkeeping
74
74
 
@@ -11,8 +11,6 @@ sensecraft-cli auth info
11
11
  sensecraft-cli auth init --site Global --no-wait # split flow; see SKILL.md
12
12
  ```
13
13
 
14
- Follow the [parent auth workflow](../SKILL.md#auth): the agent handles terminal prompts, the user completes browser authorization, then the agent rechecks auth. Do not ask the user to run CLI commands.
15
-
16
14
  ## Commands
17
15
 
18
16
  ### `app list`
@@ -181,9 +179,9 @@ When `--activity-id` is set and this JSON does not include `allow_clone`, CLI se
181
179
 
182
180
  **Status: implemented.**
183
181
 
184
- - `publish` → `privacy=2` (submit review). Same path as Console **发布草稿** when the app is already public (`is_sketch` + `be_public=1`). Result may include `draft_publish`. Refused if already `be_public=2` or not owner. stdout `detail_url` is `/view-application/<id>-<slug>` with no query. Give the user that URL. Do not append navigation params or replace it with `/application/detail/<id>`.
182
+ - `publish` → `privacy=2` (submit review). Same path as Console **发布草稿** when the app is already public (`is_sketch` + `be_public=1`). Result may include `draft_publish`. Refused if already `be_public=2` or not owner. stdout `detail_url` is `/view-application/<id>-<slug>` with no query. Give the user that URL only. Do not include `console_url` or `/application/edit`: review locks editing, and opening the editor returns `The application must not allow editing`. Do not append navigation params or replace the detail URL with `/application/detail/<id>`.
185
183
  - **Publish Declaration (required for `publish` only):** matches Console 「发布确认」`warrantyAccepted`. Before passing `--agree-declaration`, show the user:
186
- - Review will lock editing until approval (or `unpublish`)
184
+ - Review will lock editing until approval (or `app withdraw`). Do not use `unpublish` to leave review
187
185
  - Declaration URL: https://sensecraft.seeed.cc/legal/en/declaration
188
186
  - Do **not** pass `--agree-declaration` unless the user explicitly agreed
189
187
  - `unpublish` → `privacy=0` for an **already public** app (make it private). Owner only. No declaration flag. Do **not** use it to withdraw a review.
@@ -65,6 +65,8 @@ For an existing app, preserve participation unless changing it is part of the re
65
65
 
66
66
  API: `POST /flow/app/v3/edit_privacy_app` (CLI name: `publish` / `unpublish`).
67
67
 
68
+ Leaving review is not `privacy=0`. `app unpublish` only turns an already public app (`be_public=1`) private. An app under review (`be_public=2`) uses `app withdraw` (`POST /flow/app/v3/callback_sketch`). While it is under review, do not give `console_url` or `/application/edit`.
69
+
68
70
  ## BOM (`materials[]`)
69
71
 
70
72
  ### Catalog verification before authoring a BOM
@@ -87,7 +89,7 @@ Catalog verification proves product identity; it does not prove the app saved th
87
89
  | ---------- | -------- | ----------------------------------------- |
88
90
  | `id` | yes | product **SKU** |
89
91
  | `name` | yes | product name |
90
- | `quantity` | yes | string |
92
+ | `quantity` | yes | integer string from 1 to 999 |
91
93
  | `note` | yes | remark (may be empty string if UI allows) |
92
94
  | `buy_url` | yes | purchase link |
93
95
 
@@ -103,7 +105,7 @@ Pick products with `app bom search` (filters `material_options` from `get_produc
103
105
  | Field | Required | Notes |
104
106
  | ---------- | -------- | ------------------------------------------------------------------------------------------- |
105
107
  | `name` | yes | product name |
106
- | `quantity` | yes | string (Console UI integer stepper; API often string) |
108
+ | `quantity` | yes | integer string from 1 to 999 |
107
109
  | `note` | no | optional remark (Console placeholder: optional) |
108
110
  | `buy_url` | no | optional purchase link (invalid URL may become `""`) |
109
111
  | `id` | **omit** | custom rows must **not** include `id` |
@@ -21,7 +21,7 @@ Child skill: [`../create-app/SKILL.md`](../create-app/SKILL.md) — turn a local
21
21
  4. Tool-block **configuration** may be written into `deployment.blocks`. **Executing** flash / USB deploy / container install on hardware is **L3**. Classic reCamera (`40`): [`sensecraft-recamera`](recamera.md) (`check` / `open`). Other benches: Console `/ai/device/local/32|36|37|41|52`. `flash-firmware` run is out of scope this pass.
22
22
  5. Parse indented JSON on stdout; on failure read stderr + exit code. After `app update`, **re-read** the app — success body may be `{}`.
23
23
  6. **Rename / edit info**: sparse `{"app_name":"…"}` is OK (CLI merges other info fields from sketch). Do not invent HTTP; do **not** put `be_public=1` in user JSON. For **already published** apps the CLI injects `be_public=1` (Console info save) and returns `sketch_saved` — plaza copy is unchanged until `app publish`.
24
- 7. **Lifecycle vs Console**: edit / publish / unpublish / delete / BOM / cover only for **your** apps (`user_id` == profile). Another user's plaza app cannot be edited. `be_public=2` locks owner edit. `be_public=1` owner may save sketch then `app publish` (草稿). Delete only `be_public=0`.
24
+ 7. **Lifecycle vs Console**: edit / publish / unpublish / withdraw / delete / BOM / cover only for **your** apps (`user_id` == profile). Another user's plaza app cannot be edited. `be_public=2` locks owner edit and has no editor link; unlock with `app withdraw`, not `app unpublish`. `be_public=1` owner may save sketch then `app publish` (草稿). `app unpublish` is only for an already public app. Delete only `be_public=0`.
25
25
  8. **Never blind-retry `app create`**: names are not unique. If create output lacks `app_id` or looks empty, run `app list --mine` before creating again.
26
26
 
27
27
  ## CLI status
@@ -84,11 +84,12 @@ sensecraft-cli app update --id <app_id> --cancel-activity-id 1 --yes
84
84
  ```bash
85
85
  # After user agrees to Publish Declaration + confirms submit:
86
86
  sensecraft-cli app publish --id <app_id> --agree-declaration --yes
87
- sensecraft-cli app unpublish --id <app_id> --yes # privacy=0 private / withdraw review
87
+ sensecraft-cli app unpublish --id <app_id> --yes # already public (be_public=1) → private
88
+ sensecraft-cli app withdraw --id <app_id> --yes # under review (be_public=2) only
88
89
  sensecraft-cli app delete --id <app_id> --yes # private only (be_public=0)
89
90
  ```
90
91
 
91
- `app publish` matches Console 「发布确认」: show https://sensecraft.seeed.cc/legal/en/declaration and warn that review locks editing; only then pass `--agree-declaration --yes`. Missing either flag → non-zero. API body is still only `{app_id, privacy:2}` (agreement is client-side, like Console `warrantyAccepted`). stdout includes `detail_url`: `https://codecraft.seeed.cc/hub/view-application/<id>-<slug>`. Give the user that URL as printed. Do not append `from`, `section`, `state`, or `tab`. Do **not** invent `/application/detail/<id>`.
92
+ `app publish` matches Console 「发布确认」: show https://sensecraft.seeed.cc/legal/en/declaration and warn that review locks editing until approval or `app withdraw`; only then pass `--agree-declaration --yes`. Missing either flag → non-zero. API body is still only `{app_id, privacy:2}` (agreement is client-side, like Console `warrantyAccepted`). stdout includes `detail_url`: `https://codecraft.seeed.cc/hub/view-application/<id>-<slug>`. Give the user that URL as printed. Do not include `console_url` or `/application/edit`. Do not append `from`, `section`, `state`, or `tab`. Do **not** invent `/application/detail/<id>`.
92
93
 
93
94
  **Never** send `privacy=1` (ops-approved public). After editing a **published** app, tell the user plaza is unchanged until they confirm `app publish --agree-declaration --yes`.
94
95
 
@@ -133,7 +134,7 @@ For a local project/repository or an existing `codecraft-app.json`, use [create-
133
134
  sensecraft-cli app create --name "My App"
134
135
  sensecraft-cli app update --id <app_id> --from-json ./app.json --yes
135
136
  ```
136
- 5. User agrees to Publish Declaration + confirms → `app publish --agree-declaration --yes` (submit review)
137
+ 5. User agrees to Publish Declaration + confirms → `app publish --agree-declaration --yes` (submit review). After that, give `detail_url` only. `be_public=2` has no editor link.
137
138
 
138
139
  Never put `be_public=1` / `privacy=1` in JSON; use `app publish`.
139
140
 
@@ -7,8 +7,8 @@
7
7
  These are **not** confirmation. Do **not** pass `--yes` on the same turn:
8
8
 
9
9
  - 「删这个63760」「删除应用 demo」「把模型下架」「发布这个模型」
10
- - 「delete this」「unpublish」「deploy to the device」
11
- - Any first mention of create / modify / publish / unpublish / delete / deploy / stop / bind / unbind
10
+ - 「delete this」「unpublish」「withdraw the review」「deploy to the device」
11
+ - Any first mention of create / modify / publish / unpublish / withdraw / delete / deploy / stop / bind / unbind
12
12
 
13
13
  ## Required chat question (before any L2 CLI)
14
14
 
@@ -30,8 +30,8 @@ With no split flags, in a terminal:
30
30
  1. Select site: Global (International) or China. China supports SenseCraft Data only. SenseCraft AI and CodeCraft Hub require Global.
31
31
  2. Request a device authorization code and show the verification URL/code.
32
32
  3. Wait for the user to approve in the browser; the CLI polls automatically.
33
- 4. Select an existing Access Key, or create one with a label and permission level.
34
- 5. Save to local config and set it active.
33
+ 4. Resolve the account and organization, then select an existing Access Key or create one with a label and permission level.
34
+ 5. Save to local config and set it as the active profile.
35
35
 
36
36
  ### Split flow
37
37
 
@@ -11,8 +11,6 @@ sensecraft-cli auth info
11
11
  sensecraft-cli auth init --site Global --no-wait # split flow; see SKILL.md
12
12
  ```
13
13
 
14
- Follow the [parent auth workflow](../SKILL.md#auth): the agent handles terminal prompts, the user completes browser authorization, then the agent rechecks auth. Do not ask the user to run CLI commands.
15
-
16
14
  ## List (existing commands)
17
15
 
18
16
  Always pass `--uniform-type 40`. Empty list → stop.
@@ -22,7 +22,7 @@ Host binaries (images, videos, firmware) via `file upload` first. A relative pat
22
22
 
23
23
  `deployment.blocks` is a **flat** ordered array.
24
24
 
25
- “Flat” describes the array of blocks, not a tool's settings. Every tool block stores its settings inside one `config` object. The page reads `block.config.*` directly for this format; it does not wrap fields from the block root on read. Flattened settings belong to the separate legacy `deployment[].tools[]` format and must not be copied into modern `deployment.blocks[]`.
25
+ “Flat” describes the array of blocks, not a tool's settings. Every tool block, including `flash-firmware`, stores its settings inside one `config` object. The app site reads `block.config.*` and does not read a second copy on the block. Flattened settings belong to the separate legacy `deployment[].tools[]` format.
26
26
 
27
27
  ```text
28
28
  [ intro text blocks... ] [ step ][ text|tools... ] [ step ][ text|tools... ] ...
@@ -60,7 +60,7 @@ Multiple tool-blocks may appear in one step (e.g. paragraph → flash → paragr
60
60
 
61
61
  ### `flash-firmware`
62
62
 
63
- Write every field below inside **`block.config`**, just like other tool blocks, for `app create` / `app update`. Keep `id`, `type`, and layout metadata on the block itself. Reject flat or mixed root/config settings and an extra `config.config` wrapper; do not rely on opening the editor to repair them. Existing flat blocks need an explicit migration that preserves all their settings.
63
+ Write every field below inside **`block.config`**. Keep `id` and `type` on the block. Do not also put these fields on the block, and do not add a `config.config` wrapper. The app site reads `config` only. `app create` / `app update` copy a flat-only block into `config`, then remove the flat fields. When both copies exist and differ, `config` is kept.
64
64
 
65
65
  | Field | How to write |
66
66
  |-------|----------------|
@@ -73,7 +73,7 @@ Write every field below inside **`block.config`**, just like other tool blocks,
73
73
  | `muse_gadget` | JSON boolean, default `false`; write `true`/`false`, never strings or numbers. Some read paths coerce non-booleans by truthiness, so `"false"` can enable the option. `true` shows the Muse SDK token input under the flash button in preview |
74
74
  | `full_flash` | JSON boolean, default `false`. Kept only on the Muse SKUs below; any other device is reset to `false`. `true` erases the whole flash before the write. When `muse_gadget` is `true`, set `full_flash` to `false`. The editor hides the checkbox while Muse is on |
75
75
 
76
- `muse_gadget: true` is kept only for these SKUs. Any other device written `true` is reset to `false` by the editor. `full_flash` uses the same SKU list:
76
+ `muse_gadget: true` is kept only for these SKUs. The CLI and `validate_manifest.py` reject `muse_gadget: true` or `full_flash: true` for any other `device_id`. The editor resets those flags to `false` when the document is opened. `full_flash` uses the same SKU list:
77
77
 
78
78
  | Device | `device_id` (SKU) |
79
79
  |--------|-------------------|
@@ -225,6 +225,6 @@ Used for **container / edge app** deployment UI inside the application doc. Fiel
225
225
 
226
226
  ## Repair an existing malformed block
227
227
 
228
- Read the latest owner sketch, clone its **complete** `deployment`, and move the affected block's settings into `config`, preserving its ID, all values, order, and every other block. If flat and nested values disagree, resolve that conflict before writing. An update containing only a one-element `deployment.blocks` array replaces the document; it is not a patch of that one block.
228
+ Read the latest owner sketch, clone its **complete** `deployment`, and move the affected block's settings into `config`, then remove those fields from the block. Preserve its ID, all values, order, and every other block. If flat and nested values disagree, keep `config`. An update containing only a one-element `deployment.blocks` array replaces the document; it is not a patch of that one block.
229
229
 
230
230
  Validate the corrected document and follow the parent's existing-app write protocol. Re-read the sketch afterward and check the saved `config` and unchanged surrounding blocks. Reconcile the project's local manifest and sync baseline too, so a later push does not restore the malformed shape. A successful API response only proves storage; verify the consumer-visible field paths as well.
package/README-zh.md DELETED
@@ -1,463 +0,0 @@
1
- # SenseCraft CLI
2
-
3
- [English](README.md) | 中文
4
-
5
- SenseCraft CLI(`sensecraft-cli`)是 [SenseCraft](https://sensecraft.seeed.cc) 的官方命令行工具,供开发者和 AI Agent 使用。可以在终端里读取传感数据、创建模型、发布应用,并管理设备和 reCamera。
6
-
7
- 它覆盖这三块产品:
8
-
9
- | 产品 | 管什么 | 子命令 |
10
- |------|--------|--------|
11
- | [SenseCraft Data](https://sensecap.seeed.cc) | 设备、分组、传感数据 | `device` · `group` · `data` |
12
- | [SenseCraft AI](https://sensecraft.seeed.cc) | 模型库,以及 reCamera | `model` · `recamera` · `cloud` |
13
- | [CodeCraft Hub](https://codecraft.seeed.cc/hub) | 应用 | `app` |
14
-
15
- 三个平台均以开放 Access Key 访问。在 [SenseCraft 用户中心](https://account.seeed.cc/account/access-keys) 创建和管理钥匙,再用 `auth add` 写入本机。运行 `auth init`,使用 OAuth2 Device Flow 授权 CLI 访问你的账号。
16
-
17
- 也可以放进脚本和 CI。Agent Skills 见 `skills/`。
18
-
19
- **安装与排障请先读 → [`INSTALL.md`](INSTALL.md)**(平台要求、PATH、升级卸载、离线镜像、Cursor Skills)。
20
-
21
- ## 环境要求
22
-
23
- - Node.js >= 16(用于 npm 安装与分发)
24
- - 构建源码:Go(见 `go.mod`)
25
-
26
- ## 安装
27
-
28
- ```bash
29
- npx @seeed-studio/sensecraft-cli install
30
- sensecraft-cli --version
31
- sensecraft-cli update
32
- ```
33
-
34
- 完整步骤、Windows PATH、离线安装与 Skills 接入见 [`INSTALL.md`](INSTALL.md)。
35
-
36
- ```bash
37
- sensecraft-cli --help
38
- # 或
39
- npx @seeed-studio/sensecraft-cli device list
40
- ```
41
-
42
- ## 快速开始
43
-
44
- ### 1. 初始化认证
45
-
46
- ```bash
47
- # 使用 OAuth2 Device Flow 授权 CLI 访问你的账号。交互选择站点:Global / China
48
- sensecraft-cli auth init
49
-
50
- # 已在账号页创建好钥匙时,直接写入本机
51
- sensecraft-cli auth add --key-id <Key ID> --access-key <Access Key>
52
- ```
53
-
54
- 创建和管理 Access Key:<https://account.seeed.cc/account/access-keys>。
55
-
56
- 中国站仅支持 SenseCraft Data。如果需要使用 SenseCraft CLI 访问 SenseCraft AI 和 CodeCraft Hub,请选择国际站(Global)。
57
-
58
- ### 2. 查看配置
59
-
60
- ```bash
61
- sensecraft-cli auth info
62
- ```
63
-
64
- ### 3. 示例
65
-
66
- ```bash
67
- # SenseCraft Data
68
- sensecraft-cli device list
69
- sensecraft-cli data latest --eui <EUI>
70
-
71
- # SenseCraft AI。任务编号用 model constants 查,不要猜一个数字
72
- sensecraft-cli model constants
73
- sensecraft-cli model list --public --uniform-type 40
74
- sensecraft-cli recamera check --model-id <id>
75
- sensecraft-cli recamera open --model-id <id> --print-only
76
- sensecraft-cli cloud device list --uniform-type 26
77
-
78
- # CodeCraft Hub
79
- sensecraft-cli app list --public --name "vision"
80
- sensecraft-cli app list --public --uniform-type 40
81
- ```
82
-
83
- `--uniform-type`:`40` 是 reCamera,`32` 是 XIAO ESP32S3,`53` 是 reCamera Pro。`cloud device list` 里的 `26` 是 Jetson 云设备界面常用的设备类型。
84
-
85
- 删除、解绑、发布、部署这类写操作必须加 `--yes`。Agent 的确认步骤见 [skills/sensecraft-cli/references/confirmation.md](skills/sensecraft-cli/references/confirmation.md)。
86
-
87
- ## 配置
88
-
89
- | 项 | 说明 |
90
- |----|------|
91
- | npm 安装默认 | macOS/Linux:`~/.config/sensecraft-cli/sensecraft.json`;Windows:`%APPDATA%\sensecraft-cli\sensecraft.json`(wrapper 注入 `SENSECRAFT_CLI_PATH`) |
92
- | 源码直接运行默认 | 当前工作目录下的 `sensecraft.json` |
93
- | `SENSECRAFT_CLI_PATH` | 配置目录(文件名为 `sensecraft.json`) |
94
- | `SENSECRAFT_CONFIG_FILE` | 配置文件完整路径(优先于上面两项) |
95
-
96
- ## 输出格式
97
-
98
- - 业务命令成功:stdout JSON(缩进 2 空格)
99
- - `auth info` / `auth init`:人类可读文本(非 JSON)
100
- - 失败:stderr + 非 0 退出码
101
- - 版本:`sensecraft-cli --version`(与 npm 包版本一致)
102
-
103
- ## 用在脚本和 CI
104
-
105
- 无交互环境不会打开浏览器。用 `auth add` 写入钥匙,并用 `SENSECRAFT_CONFIG_FILE` 指到项目自己的配置文件,避免写进本机的 `~/.config/sensecraft-cli/`。
106
-
107
- ```bash
108
- export SENSECRAFT_CONFIG_FILE="$PWD/.sensecraft/sensecraft.json"
109
- sensecraft-cli auth add \
110
- --key-id "$SENSECRAFT_KEY_ID" \
111
- --access-key "$SENSECRAFT_ACCESS_KEY" \
112
- --site Global
113
- sensecraft-cli device list
114
- ```
115
-
116
- 这个文件含有 Access Key,不要提交到仓库。`--site` 省略时是 `Global`。业务命令成功时解析 stdout 的 JSON;失败看退出码,错误在 stderr。`auth info` 的输出是文本。
117
-
118
- ## AI Agent Skills
119
-
120
- 入口是 [`skills/sensecraft-cli/SKILL.md`](skills/sensecraft-cli/SKILL.md)。设备、模型、应用等说明在 `skills/sensecraft-cli/references/`。从本地工程生成应用用嵌套技能 `skills/sensecraft-cli/create-app/`。
121
-
122
- 安装后把这个目录软链到 Agent 的技能目录,不要复制。升级 CLI 时技能会一起更新。步骤见 [`INSTALL.md` §9](INSTALL.md#9-agent-skills-cursor-and-others)。
123
-
124
- ## 从源码构建
125
-
126
- 完整说明见 [`INSTALL.md` §8](INSTALL.md#8-build-from-source)。摘要:
127
-
128
- ```bash
129
- # 本机调试
130
- go build -o sensecraft-cli .
131
- ./sensecraft-cli --version
132
-
133
- # 多平台发布二进制 → dist/(注入 -ldflags 版本信息)
134
- ./script/build.sh
135
- ```
136
-
137
- 贡献本仓库时的自检:`./script/smoke-ai.sh`、`./script/smoke-sensecap.sh`。隔离安装检查要先 `./script/build.sh`,再在 `packages/cli` 里运行 `npm run test:install`。使用 CLI 的项目不需要这些脚本。
138
-
139
- ## 许可证
140
-
141
- [MIT](LICENSE)
142
-
143
- ---
144
-
145
- ## 命令文档
146
-
147
- 本文展开 SenseCraft Data。其它命令的参数、限制和示例:
148
-
149
- | 范围 | 文档 |
150
- |------|------|
151
- | SenseCraft Data | [data-commands.md](skills/sensecraft-cli/references/data-commands.md) |
152
- | 模型库 | [model-commands.md](skills/sensecraft-cli/references/model-commands.md) |
153
- | reCamera | [recamera-commands.md](skills/sensecraft-cli/references/recamera-commands.md) |
154
- | 云设备部署与订单 | [cloud-commands.md](skills/sensecraft-cli/references/cloud-commands.md) |
155
- | CodeCraft Hub 应用 | [app-commands.md](skills/sensecraft-cli/references/app-commands.md) |
156
- | 文件上传 | [file-commands.md](skills/sensecraft-cli/references/file-commands.md) |
157
-
158
- ## 命令参考(SenseCraft Data)
159
-
160
- ### auth — 认证与配置
161
-
162
- #### `auth init`
163
-
164
- 使用 OAuth2 Device Flow 授权 CLI 访问你的账号。交互选择站点:Global / China。
165
-
166
- | 参数 | 说明 |
167
- |------|------|
168
- | `--sandbox` | 沙盒:不发真实网络请求 |
169
-
170
- #### `auth add`
171
-
172
- 把已有的 Access Key 写入本机,并设为当前钥匙。无交互环境必须带上 `--key-id` 和 `--access-key`。
173
-
174
- | 参数 | 必填 | 默认值 | 说明 |
175
- |------|------|--------|------|
176
- | `--key-id` | 交互终端可省略 | — | Key ID |
177
- | `--access-key` | 交互终端可省略 | — | Access Key |
178
- | `--site` | 否 | `Global` | `Global` 或 `China` |
179
-
180
- ```bash
181
- sensecraft-cli auth add --key-id <Key ID> --access-key <Access Key> --site Global
182
- ```
183
-
184
- #### `auth info`
185
-
186
- `info` 展示当前 Access Key 的站点、组织 ID 和 Key ID,不打印密钥。
187
-
188
- ---
189
-
190
- ### device — 设备管理(SenseCraft Data)
191
-
192
- #### `device list`
193
-
194
- 获取当前账号下的设备列表。
195
-
196
- | 参数 | 必填 | 默认值 | 说明 |
197
- |------|------|--------|------|
198
- | `--device-type` | 否 | `2` | 设备类型:`1`=网关,`2`=节点,`3`=开发套件 |
199
- | `--group-uuid` | 否 | — | 按分组 UUID 筛选;不传则返回所有分组下的设备 |
200
-
201
- ```bash
202
- # 列出所有节点(默认)
203
- sensecraft-cli device list
204
-
205
- # 列出网关
206
- sensecraft-cli device list --device-type 1
207
-
208
- # 列出开发套件
209
- sensecraft-cli device list --device-type 3
210
-
211
- # 列出指定分组下的设备
212
- sensecraft-cli device list --group-uuid <group-uuid>
213
- ```
214
-
215
- #### `device view`
216
-
217
- 获取设备详情(最多 50 个 EUI)。
218
-
219
- | 参数 | 必填 | 默认值 | 说明 |
220
- |------|------|--------|------|
221
- | `--eui` | 是 | — | 设备 EUI,可多次指定 |
222
- | `--device-type` | 否 | `2` | 设备类型:`1`=网关,`2`=节点,`3`=开发套件 |
223
-
224
- ```bash
225
- sensecraft-cli device view --eui 0123456789ABCDEF
226
- ```
227
-
228
- #### `device channels`
229
-
230
- 查询节点通道列表(最多 50 个 EUI)。
231
-
232
- | 参数 | 必填 | 说明 |
233
- |------|------|------|
234
- | `--eui` | 是 | 设备 EUI,可多次指定 |
235
-
236
- ```bash
237
- sensecraft-cli device channels --eui 0123456789ABCDEF
238
- ```
239
-
240
- #### `device status`
241
-
242
- 获取设备运行状态(最多 50 个 EUI)。
243
-
244
- | 参数 | 必填 | 说明 |
245
- |------|------|------|
246
- | `--eui` | 是 | 设备 EUI,可多次指定 |
247
-
248
- ```bash
249
- sensecraft-cli device status --eui 0123456789ABCDEF
250
- ```
251
-
252
- #### `device bind`
253
-
254
- 将设备绑定到当前账号。
255
-
256
- | 参数 | 必填 | 说明 |
257
- |------|------|------|
258
- | `--eui` | 是 | 设备 EUI |
259
- | `--code` | 是 | 设备绑定码 |
260
- | `--name` | 否 | 设备名称 |
261
- | `--group-uuid` | 否 | 目标分组 UUID |
262
- | `--longitude` | 否 | 经度 |
263
- | `--latitude` | 否 | 纬度 |
264
-
265
- ```bash
266
- sensecraft-cli device bind --eui 0123456789ABCDEF --code ABCD1234 --name "我的传感器"
267
- ```
268
-
269
- #### `device unbind`
270
-
271
- 解绑设备(最多 50 个 EUI)。须加 `--yes`。
272
-
273
- | 参数 | 必填 | 说明 |
274
- |------|------|------|
275
- | `--eui` | 是 | 设备 EUI,可多次指定 |
276
- | `--yes` | 是 | 确认执行 |
277
-
278
- ```bash
279
- sensecraft-cli device unbind --eui 0123456789ABCDEF --yes
280
- ```
281
-
282
- #### `device sim`
283
-
284
- 查看 SIM 卡状态。
285
-
286
- | 参数 | 必填 | 说明 |
287
- |------|------|------|
288
- | `--iccid` | 是 | SIM 卡 ICCID |
289
-
290
- ```bash
291
- sensecraft-cli device sim --iccid 89860000000000000000
292
- ```
293
-
294
- ---
295
-
296
- ### device devkit — 开发套件
297
-
298
- #### `device devkit create`
299
-
300
- 创建开发套件设备。同一组织下每个 SKU 最多创建 5 个。
301
-
302
- | 参数 | 必填 | 说明 |
303
- |------|------|------|
304
- | `--sku` | 是 | 开发套件 SKU |
305
- | `--name` | 否 | 设备名称 |
306
-
307
- 支持的 SKU:
308
-
309
- | SKU | 说明 |
310
- |-----|------|
311
- | `blank_device` | Blank Device |
312
- | `xiao` | XIAO |
313
- | `grove_vision_ai` | Grove Vision AI V2 |
314
-
315
- ```bash
316
- sensecraft-cli device devkit create --sku xiao --name "我的 XIAO 套件"
317
- ```
318
-
319
- #### `device devkit key`
320
-
321
- 查看开发套件设备的 `device_key` 与 `token`(仅支持开发套件设备,EUI 为 16 位字符)。
322
-
323
- | 参数 | 必填 | 说明 |
324
- |------|------|------|
325
- | `--eui` | 是 | 开发套件设备 EUI(16 位) |
326
-
327
- ```bash
328
- sensecraft-cli device devkit key --eui 0123456789ABCDEF
329
- ```
330
-
331
- ---
332
-
333
- ### group — 设备分组
334
-
335
- #### `group list`
336
-
337
- 列出当前账号下的所有设备分组。
338
-
339
- #### `group create`
340
-
341
- 创建设备分组(最多 50 个分组)。
342
-
343
- | 参数 | 必填 | 说明 |
344
- |------|------|------|
345
- | `--name` | 是 | 分组名称 |
346
-
347
- ```bash
348
- sensecraft-cli group create --name "温室传感器"
349
- ```
350
-
351
- #### `group update`
352
-
353
- 更新设备分组名称。
354
-
355
- | 参数 | 必填 | 说明 |
356
- |------|------|------|
357
- | `--group-uuid` | 是 | 分组 UUID |
358
- | `--name` | 是 | 新分组名称 |
359
-
360
- ```bash
361
- sensecraft-cli group update --group-uuid <uuid> --name "新名称"
362
- ```
363
-
364
- #### `group delete`
365
-
366
- 删除设备分组(组内设备将移至默认分组)。须加 `--yes`。
367
-
368
- | 参数 | 必填 | 说明 |
369
- |------|------|------|
370
- | `--group-uuid` | 是 | 分组 UUID |
371
- | `--yes` | 是 | 确认执行 |
372
-
373
- ```bash
374
- sensecraft-cli group delete --group-uuid <uuid> --yes
375
- ```
376
-
377
- #### `group move-devices`
378
-
379
- 将设备移动到指定分组。须加 `--yes`。
380
-
381
- | 参数 | 必填 | 说明 |
382
- |------|------|------|
383
- | `--group-uuid` | 是 | 目标分组 UUID |
384
- | `--eui` | 是 | 设备 EUI,可多次指定 |
385
- | `--yes` | 是 | 确认执行 |
386
-
387
- ```bash
388
- sensecraft-cli group move-devices --group-uuid <uuid> --eui 0123456789ABCDEF --yes
389
- ```
390
-
391
- ---
392
-
393
- ### data — 传感数据
394
-
395
- #### `data latest`
396
-
397
- 获取设备最近一年内的最新遥测数据;未指定通道时返回每个通道下最新数据点。
398
-
399
- | 参数 | 必填 | 说明 |
400
- |------|------|------|
401
- | `--eui` | 是 | 设备 EUI |
402
- | `--measurement-id` | 否 | 测量值 ID |
403
- | `--channel-index` | 否 | 通道编号 |
404
-
405
- ```bash
406
- sensecraft-cli data latest --eui 0123456789ABCDEF --measurement-id 4097 --channel-index 1
407
- ```
408
-
409
- #### `data list`
410
-
411
- 获取设备历史遥测数据(单次最长约一个月,且仅可查近三个月内数据)。
412
-
413
- | 参数 | 必填 | 默认值 | 说明 |
414
- |------|------|--------|------|
415
- | `--eui` | 是 | — | 设备 EUI |
416
- | `--measurement-id` | 否 | — | 测量值 ID |
417
- | `--channel-index` | 否 | — | 通道编号 |
418
- | `--limit` | 否 | — | 返回记录数 |
419
- | `--time-start` | 否 | — | 起始时间戳(毫秒) |
420
- | `--time-end` | 否 | — | 结束时间戳(毫秒) |
421
-
422
- ```bash
423
- sensecraft-cli data list --eui 0123456789ABCDEF --limit 100 --time-start 1700000000000 --time-end 1700086400000
424
- ```
425
-
426
- #### `data chart`
427
-
428
- 获取设备遥测折线聚合点(最长一年;每个测量最多约 250 个点)。
429
-
430
- | 参数 | 必填 | 默认值 | 说明 |
431
- |------|------|--------|------|
432
- | `--eui` | 是 | — | 设备 EUI |
433
- | `--measurement-id` | 否 | — | 测量值 ID |
434
- | `--channel-index` | 否 | — | 通道编号 |
435
- | `--interval` | 否 | `60` | 时间段长度(分钟) |
436
- | `--time-start` | 否 | — | 起始时间戳(毫秒) |
437
- | `--time-end` | 否 | — | 结束时间戳(毫秒) |
438
-
439
- ```bash
440
- sensecraft-cli data chart --eui 0123456789ABCDEF --interval 60 --time-start 1700000000000 --time-end 1702592000000
441
- ```
442
-
443
- ---
444
-
445
- ## 典型工作流
446
-
447
- ```bash
448
- # 安装并初始化
449
- npx @seeed-studio/sensecraft-cli install
450
-
451
- # 查看分组
452
- sensecraft-cli group list
453
-
454
- # 列出节点设备
455
- sensecraft-cli device list
456
-
457
- # 查看设备详情与通道
458
- sensecraft-cli device view --eui 0123456789ABCDEF
459
- sensecraft-cli device channels --eui 0123456789ABCDEF
460
-
461
- # 查询最新数据
462
- sensecraft-cli data latest --eui 0123456789ABCDEF
463
- ```