@seeed-studio/sensecraft-cli 0.4.3 → 0.4.4

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.4",
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": [
@@ -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`**:
@@ -62,7 +62,7 @@ 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
 
@@ -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`
@@ -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
  |-------|----------------|
@@ -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
- ```