@seeed-studio/sensecraft-cli 0.1.1 → 0.1.3

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.
@@ -0,0 +1,129 @@
1
+ ---
2
+ name: sensecraft-ai
3
+ description: >-
4
+ Routes SenseCraft AI platform work for Agents: Application Plaza, model library,
5
+ model upload, and cloud deploy vs SenseCAP IoT CLI. Use when the user mentions
6
+ SenseCraft AI, 应用广场, App Square, 模型库, 上传模型, aiserverapi, or asks
7
+ which SenseCraft skill/CLI profile to use. Does not replace domain skills
8
+ (apps/models/files) or sensecraft-data (SenseCAP devices/data).
9
+ ---
10
+
11
+ # SenseCraft AI (Meta)
12
+
13
+ Router skill for **SenseCraft AI** capabilities exposed via CLI in this repo (`sensecraft-data-terminal`). Domain skills and AI subcommands are rolled out in phases; this skill always applies for **intent routing, auth kind selection, and product-term disambiguation**.
14
+
15
+ Sibling (already shipped): [`../sensecraft-data/SKILL.md`](../sensecraft-data/SKILL.md) — SenseCAP PaaS OpenAPI (`device` / `group` / `data`).
16
+
17
+ ## Agent rules
18
+
19
+ 1. **Pick the auth kind before any cloud call**
20
+ - `app` / `model` / `file` / `cloud` use SenseCAP **Access Key** → `{ai-host}/openapi` + HTTP Basic (no access_token, no `/aiserverapi`)
21
+ - Never send Access Key as a fake Bearer/JWT
22
+ 2. **Always run auth check first** (ask user to fix if missing):
23
+ ```bash
24
+ sensecraft-cli auth info
25
+ ```
26
+ Published commands require an active **SenseCAP Access Key** → `{ai-host}/openapi` + HTTP Basic.
27
+ 3. **Never run `auth init` on behalf of the user** — browser OAuth Device Flow, interactive TTY only. Tell the user to run locally:
28
+ ```bash
29
+ sensecraft-cli auth init --kind sensecap # Access Key (app/model/file/cloud)
30
+ ```
31
+ 4. **L2 confirmation is a separate chat turn** — follow [`../confirmation.md`](../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/model create·update·publish·unpublish·delete·clone, upload attach, cloud deploy, device bind/unbind, group create/rename/delete/move.
32
+ 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.
33
+ 6. **Success = indented JSON on stdout**; failure = stderr + non-zero exit. Parse stdout only on success.
34
+ 7. **Local USB / Web Serial flashing is L3** — do not pretend remote auto-flash. Guide the user to Console `/ai/device/local/...` when real hardware burn is required. Skill/CLI may configure app tool-blocks only.
35
+
36
+ ## Auth model (same OAuth client, different persistence)
37
+
38
+ | Kind | After Device Flow (`client_id=sensecraft-cli`) | Daily API auth |
39
+ |------|-----------------------------------------------|----------------|
40
+ | `sensecap` | Exchange for Access Key; store `key_id` + `access_key` | HTTP Basic → SenseCAP `/openapi` **and** AI `{ai-host}/openapi` (app/model/file/cloud) |
41
+
42
+ ### Site / `remote_type` (AI)
43
+
44
+ | `remote_type` | AI openapi | authapi (refresh / org) |
45
+ |---------------|-------------|-------------------------|
46
+ | `Global` | `https://sensecraft.seeed.cc/openapi` | `account.seeed.cc/authapi` |
47
+ | `Develop` | **`https://test-sensecraft.seeed.cc/openapi`** | `test-account.seeed.cc/authapi` |
48
+
49
+ Console 测试站 `test-sensecraft.seeed.cc` → CLI 必须用 **`remote_type: Develop`**,勿用 Global。
50
+
51
+ `auth info` shows both SenseCAP and SenseCraft AI sections (tokens masked).
52
+
53
+ ## Intent → skill / command routing
54
+
55
+ | User intent | Use | Auth kind | Notes |
56
+ |-------------|-----|-----------|--------|
57
+ | SenseCAP list/bind device, groups, telemetry | [`sensecraft-data`](../sensecraft-data/SKILL.md) | `sensecap` | Shipped today |
58
+ | Browse / search App Plaza, view app | [`sensecraft-apps`](../sensecraft-apps/SKILL.md) + `app list` / `app view` | `sensecap` | **CLI shipped** (list/view) |
59
+ | App fields / tool-blocks / BOM guidance | same apps skill references | `sensecap` | Config OK; real flash = L3 |
60
+ | Clone / create / update / publish / unpublish / delete / bom app | same + `app …` / `app bom …` | `sensecap` | **CLI shipped** (L2 `--yes`; clone also `--agree-disclaimer`; publish also `--agree-declaration`; bare `create --name` not L2) |
61
+ | Upload image/file/firmware/doc/archive and obtain `file_url` | [`sensecraft-files`](../sensecraft-files/SKILL.md) + `file upload` | `sensecap` | Types `1`–`2` require `--model-id`/`--app-id --yes`/`--for-app`/`--unlinked`; types `3`–`6` direct |
62
+ | Model library search/view/download/constants | [`sensecraft-models`](../sensecraft-models/SKILL.md) | `sensecap` | **CLI shipped** |
63
+ | Upload / publish / unpublish / delete model | same + `model upload --id --yes` / `create\|update\|publish\|unpublish\|delete` | `sensecap` | Attach bumps patch version like Console |
64
+ | reCamera Pro model library | [`sensecraft-models`](../sensecraft-models/SKILL.md) + `model create --target recamera-pro` / `recamera-pro resolve` | `sensecap` | Deploy is local IP/USB L3 — not `cloud deploy` |
65
+ | Jetson / cloud kit list & deploy | [`sensecraft-devices-cloud`](../sensecraft-devices-cloud/SKILL.md) + `cloud …` | `sensecap` | **CLI shipped** (list/view/deploy/order); not SenseCAP `device` |
66
+ | Local USB/IP model deploy or firmware flash | Console reCamera workspace / local device page | — | **L3 only** |
67
+
68
+ ## Cross-domain example
69
+
70
+ SenseCAP telemetry → pick public model → deploy to Jetson:
71
+
72
+ 1. `sensecraft-cli auth info` (both profiles if needed)
73
+ 2. SenseCAP: `data latest --eui <sensecap-eui>` (Access Key)
74
+ 3. AI: `model list --public --name "…"` → `model view --id …` (metadata only; **no** `model download`)
75
+ 4. Confirm with user → `cloud deploy --eui <jetson-eui> --model-id … --yes` (device pulls firmware at apply time)
76
+ 5. `cloud order --request-id …`
77
+
78
+ Do **not** mix AI token into SenseCAP / AI `/openapi` Access Key calls.
79
+
80
+ ## Product-term disambiguation
81
+
82
+ | User says | Possible meanings | Default choice |
83
+ |-----------|-------------------|----------------|
84
+ | 应用 / App Store / Application | App Plaza (docs+BOM community app) vs in-doc deploy tool-block | **App Plaza** |
85
+ | 设备 / device | SenseCAP node/gateway vs Console kit/Jetson vs local USB board | Telemetry/bind → **sensecraft-data**; AI cloud device → devices-cloud; USB/serial → Console local (L3) |
86
+ | 部署模型 / deploy model | Cloud `deploy_model` vs local flash vs app tool-block | Ask which target; local flash = L3 |
87
+ | 模型下载地址 / 下载链接 / 怎么下载 | Public library artifact URL vs private owner file | **Public → no URL**, explain deploy; private My Models → `model download --out` (do not paste URL) |
88
+ | Data | SenseCAP telemetry vs training dataset | Telemetry → **sensecraft-data**; dataset → Console |
89
+ | Agent | Watcher Agent vs in-console AI Bot vs these Skills | These Skills ≠ Bot; Watcher has separate auth |
90
+ | Clone vs Install | Clone to My Apps vs install on a device | **Clone** = App Plaza |
91
+
92
+ ## Capability levels
93
+
94
+ | Level | Meaning | Examples |
95
+ |-------|---------|----------|
96
+ | L1 Scriptable | Agent may run directly | list / view / auth info |
97
+ | L2 Confirm | Ask user first | clone (+ disclaimer), publish (+ declaration), unpublish, delete, deploy |
98
+ | L3 Interactive | Human-in-the-loop | `auth init`, Web Serial flash, payment |
99
+ | L4 Ops-only | Do not expose to end-user Agent | Admin `judge_app` |
100
+
101
+ ## SenseCraft AI surface (shipped MVP)
102
+
103
+ Published commands use **SenseCAP Access Key** (`kind=sensecap`) → `{ai-host}/openapi`:
104
+
105
+ 1. **Apps** — list/view/fields/blocks; create/update/clone; publish/unpublish/delete (L2); BOM search/list/set; tool-block config via JSON (real flash = L3).
106
+ 2. **Files** — `file upload` for image/model/app/firmware/doc/archive; types 1–2 require `--model-id` / `--app-id --yes` / `--for-app` / `--unlinked` before PUT (bare upload fails).
107
+ 3. **Model library** — list/view/constants; **private** download only; public models deploy-only (no `file_url`); `model upload --id --yes` attaches and auto-bumps patch version; create/update; publish/unpublish/delete (L2).
108
+ 4. **Cloud devices** — `cloud device` / `cloud deploy` / `cloud order`.
109
+ 5. **Local USB** — Meta guides to Console local device page only.
110
+
111
+ ## When something is missing
112
+
113
+ Published AI CLI is `app` / `model` / `file` / `cloud`. If a command fails:
114
+
115
+ 1. Run `sensecraft-cli auth info` — need an active SenseCAP Access Key.
116
+ 2. Do **not** call SenseCAP `device`/`data` as a substitute.
117
+ 3. Do **not** scrape Console cookies or invent HTTP with guessed tokens.
118
+ 4. Prefer domain skills (`apps` / `files` / `models` / `devices-cloud`).
119
+
120
+ ## Related files in this repo
121
+
122
+ | Path | Role |
123
+ |------|------|
124
+ | [`../sensecraft-data/SKILL.md`](../sensecraft-data/SKILL.md) | SenseCAP PaaS skill (shipped) |
125
+ | [`../sensecraft-data/commands.md`](../sensecraft-data/commands.md) | Full SenseCAP command reference |
126
+ | `skills/sensecraft-apps/` | App Plaza skill + field/block refs (**shipped**) |
127
+ | `skills/sensecraft-models/` | Model library skill + field refs (**shipped**) |
128
+ | `skills/sensecraft-devices-cloud/` | Jetson / cloud kit (**shipped**) |
129
+ | `skills/README.md` | Skill discovery for Agents |
@@ -0,0 +1,197 @@
1
+ ---
2
+ name: sensecraft-apps
3
+ description: >-
4
+ Manages SenseCraft Application Plaza (应用广场 / App Square): search public apps,
5
+ view detail (docs, tool-blocks, BOM), clone to My Apps, create/edit/publish/
6
+ unpublish/delete apps. Use when the user mentions 应用广场, Application Store,
7
+ clone SenseCraft apps, app BOM, deploy tool-blocks, or SenseCraft app upload.
8
+ Requires Access Key (`auth init --kind sensecap`). Not for Fleet container install or SenseCAP devices.
9
+ ---
10
+
11
+ # SenseCraft Apps (Application Plaza)
12
+
13
+ Domain skill for **SenseCraft AI applications**. Auth: **Access Key** → `{ai-host}/openapi` (HTTP Basic). Do **not** send the AI user token on these calls.
14
+
15
+ Parent router: [`../sensecraft-ai/SKILL.md`](../sensecraft-ai/SKILL.md).
16
+ SenseCAP IoT: [`../sensecraft-data/SKILL.md`](../sensecraft-data/SKILL.md).
17
+
18
+ ## Agent rules
19
+
20
+ 1. Check auth first:
21
+ ```bash
22
+ sensecraft-cli auth info
23
+ ```
24
+ Need an active **SenseCAP Access Key**. If missing, ask the user to run `sensecraft-cli auth init --kind sensecap` locally. **Never** run `auth init` for them.
25
+ 2. **L2 confirm is a separate chat turn** ([`../confirmation.md`](../confirmation.md)) before: `clone` (also `--agree-disclaimer`), `publish` (`--agree-declaration`), `unpublish`, `delete`, **`app update` / `bom set`**. 「删除应用 demo」is **not** confirmation — ask `将从{环境}环境删除应用 demo(ID: …)。删除后可能无法恢复。是否确认执行?`, wait for `确认`, then `--yes`. Never pass `--yes` on the same turn as the first request.
26
+ **`app create` is not L2** — including `--from-json` with full fields (create + internal follow-up `update_app` on the **new** `app_id` only). Prefer one-shot create when the payload is ready. Still tell the user what will be created before running create.
27
+ 3. **Privacy values**: submit review → `privacy` / flow uses **`2`** (pending); unpublish/private → **`0`**. **Never send `1`** (ops-approved public; Admin only).
28
+ 4. **Clone ≠ Fleet install**. Clone copies into My Apps. Installing Docker apps on devices is Fleet — out of scope.
29
+ 5. Tool-block **configuration** may be written into `deployment.blocks`. **Executing** flash / USB deploy / container install on hardware is **L3** — guide user to Console preview / `/ai/device/local/...`.
30
+ 6. Parse indented JSON on stdout; on failure read stderr + exit code. After `app update`, **re-read** the app — success body may be `{}`.
31
+ 7. **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`.
32
+ 8. **Lifecycle vs Console**: edit / publish / unpublish / delete / BOM / cover only for **your** apps (`user_id` == profile). Others' plaza apps: **clone** then edit the copy. `be_public=2` locks owner edit. `be_public=1` owner may save sketch then `app publish` (草稿). Delete only `be_public=0`.
33
+ 9. **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.
34
+
35
+ ## CLI status
36
+
37
+ | Area | Status |
38
+ | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
39
+ | Auth `--kind sensecap` | **Implemented** (`auth init --kind sensecap`; `app` uses `{ai-host}/openapi` Basic) |
40
+ | `app list` / `app view` / `app fields` / `app blocks` | **Implemented** |
41
+ | `app clone` / `create` / `update` / `publish` / `unpublish` / `delete` | **Implemented** (L2 = `--yes`; clone also `--agree-disclaimer`; publish also `--agree-declaration`; **`create` never needs `--yes`**, even with full `--from-json`) |
42
+ | Cover / attachment upload | `file upload --path <img> --type 1 --app-id <id> --yes` (prepends cover, **5 MB**). Unlinked: `file upload --type 1 --for-app` when building a new app payload. |
43
+ | `app bom search\|list\|set` | **Implemented** (catalog = local filter on `get_production_options`; set via `update_app`) |
44
+ | `scene` / option ids | Use `sensecraft-cli model constants` (`app_scenarios_array`) |
45
+ | BOM **price / image** | Seeed rows: **readable** from `app bom search` (`price`, `pic_url`), resolved by SKU — not stored in `materials[]`. Custom rows: **unsupported by the platform** (no input in Console) |
46
+
47
+ When a command exists, prefer it. When it does not, explain the gap and use field/block references below to prepare payloads — do not invent HTTP with guessed tokens; do not misuse SenseCAP CLI.
48
+
49
+ ## Typical workflows
50
+
51
+ ### Discover public apps
52
+
53
+ ```bash
54
+ sensecraft-cli auth info
55
+ sensecraft-cli app list --public --name "<keyword>" --scene <id>
56
+ sensecraft-cli app list --public --uniform-type 40
57
+ sensecraft-cli app view --id <app_id>
58
+ ```
59
+
60
+ Summarize: name, excerpt, scene, tool-block types used, BOM highlights, deploy steps.
61
+
62
+ ### Clone to My Apps (L2)
63
+
64
+ ```bash
65
+ # 1) Show Disclaimer for Use, get explicit agreement
66
+ # 2) Confirm clone, then:
67
+ sensecraft-cli app clone --id <app_id> --agree-disclaimer --yes
68
+ sensecraft-cli app clone --id <app_id> --name "Clone_MyName" --agree-disclaimer --yes
69
+ ```
70
+
71
+ `app clone` matches Console 「克隆应用」: show https://sensecraft.seeed.cc/legal/en/disclaimer (使用免责声明) and only then pass `--agree-disclaimer --yes`. Missing either flag → non-zero. API body is still only `{app_id, app_name}` (agreement is client-side, like Console `disclaimerAccepted`). Clone ≠ Fleet install.
72
+
73
+ ### Rename an existing app (L2)
74
+
75
+ ```bash
76
+ # Confirm with the user first. Sparse name-only JSON is OK — CLI merges other info fields.
77
+ echo '{"app_name":"Dimmer Tutorial · Grove Beginner Kit"}' \
78
+ | sensecraft-cli app update --id <app_id> --from-json - --yes
79
+ sensecraft-cli app view --id <app_id> --sketch # must show new app_name
80
+ ```
81
+
82
+ ### Publish / unpublish / delete (L2)
83
+
84
+ ```bash
85
+ # After user agrees to Publish Declaration + confirms submit:
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
88
+ sensecraft-cli app delete --id <app_id> --yes # private only (be_public=0)
89
+ ```
90
+
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`).
92
+
93
+ **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
+ ### BOM
96
+
97
+ ```bash
98
+ sensecraft-cli app bom search --name "XIAO"
99
+ sensecraft-cli app bom list --id <app_id>
100
+ # confirm with user, then:
101
+ sensecraft-cli app bom set --id <app_id> --from-json ./materials.json --yes
102
+ ```
103
+
104
+ Seeed rows need `id`(=SKU). Custom rows omit `id`. No manual custom image upload.
105
+
106
+ ### Author path
107
+
108
+ 0. Resolve `scene`, inspect fields, and inspect block layouts:
109
+ ```bash
110
+ sensecraft-cli model constants
111
+ sensecraft-cli app fields
112
+ sensecraft-cli app blocks
113
+ ```
114
+ Use `app_scenarios_array` from constants and the two static catalogs; never invent option ids or block shapes.
115
+ 1. Fill required app info (see [reference-app-fields.md](reference-app-fields.md)).
116
+ 2. Build intro + stepped deploy + tool-blocks ([reference-tool-blocks.md](reference-tool-blocks.md)).
117
+ 3. BOM: Seeed SKU rows and/or custom rows ([reference-app-fields.md](reference-app-fields.md#bom-materials))
118
+ 4. **Prefer one-shot create** when JSON is complete (**no `--yes`**):
119
+ ```bash
120
+ sensecraft-cli app create --from-json ./app.json
121
+ # CLI returns app_id + console_url + detail_url (even if update_app body was {}).
122
+ # detail_url includes from=my-apps so cover/images load from the sketch.
123
+ # Restore JSON may have pic_url (list) or images[] (view); CLI writes both.
124
+ # Show links to the user. NEVER re-run create because stdout looked empty —
125
+ # check first: app list --mine --name "<name>"
126
+ ```
127
+ Incremental path (empty shell, then L2 edit of existing app):
128
+ ```bash
129
+ sensecraft-cli app create --name "My App"
130
+ sensecraft-cli app update --id <app_id> --from-json ./app.json --yes
131
+ ```
132
+ 5. User agrees to Publish Declaration + confirms → `app publish --agree-declaration --yes` (submit review)
133
+
134
+ Never put `be_public=1` / `privacy=1` in JSON; use `app publish`.
135
+
136
+ ## App info fields (summary)
137
+
138
+ | Field | Type | Required | Constraints |
139
+ | ---------------- | ------------------ | --------------- | ------------------------------------------------------------------------------ |
140
+ | `app_name` | text | yes | trim, max **60** |
141
+ | `excerpt` | text | yes | trim, max **300** |
142
+ | `scene` | option (string id) | yes | id from `app_scenarios_array` — list via `sensecraft-cli model constants` |
143
+ | `allow_clone` | option 0/1 | yes | boolean in UI |
144
+ | `allow_commerce` | option 0/1 | yes | boolean in UI |
145
+ | `images` | image URL[] | yes | JPG/GIF/PNG(/WebP), **≤5 MB**/image, **max 16**, first = cover, prefer **4:3** |
146
+ | `license` | text | often with save | string |
147
+ | `be_public` | 0/1/2 | lifecycle | 0 private, 1 public (ops), 2 pending review |
148
+
149
+ Full table + `update_app` keys: [reference-app-fields.md](reference-app-fields.md).
150
+
151
+ ## Deploy docs + tool-blocks (summary)
152
+
153
+ Structure: `deployment.blocks` flat array.
154
+
155
+ - Blocks **before first `step`** = Introduction
156
+ - From each `step` until next `step` = one deploy step (text + tool-blocks mixed)
157
+
158
+ **High-priority tool-blocks** (pick by scenario):
159
+
160
+ | `type` | When to use | Execute? |
161
+ | --------------------------- | --------------------------------------------------------- | --------------------------------------------------- |
162
+ | `flash-firmware` | Burn firmware to supported board | Config = L1/L2 write; **run flash = L3** |
163
+ | `deploy-ai-model` | Vision / audio AI model to device (task/device in config) | Config OK; **run deploy = L3** |
164
+ | `ai-vibration` | Vibration detection on XIAO-class device | Config OK; run = L3 |
165
+ | `deploy-container-app` | Edge container app (Fleet-related UX in preview) | Config OK; **install on devices ≠ App Plaza clone** |
166
+ | `node-red` / `aily-blockly` | Flow / Blockly projects | Lower priority unless user asks |
167
+
168
+ Details: [reference-tool-blocks.md](reference-tool-blocks.md).
169
+
170
+ ## BOM (summary)
171
+
172
+ | Kind | Keys | Notes |
173
+ | ------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------- |
174
+ | Seeed catalog | `id` (SKU), `quantity`, `name`, `note`, `buy_url` | `price` / `pic_url` come from the catalog by SKU — report them, never persist them |
175
+ | Custom | `quantity`, `name`, `note`, `buy_url` | **No `id`**, and **no price / image** — Console offers no input for either |
176
+
177
+ ## APIs (implementation reference)
178
+
179
+ Base: `{host}/openapi` with HTTP Basic (`key_id`:`access_key`).
180
+
181
+ | Action | Method | Path |
182
+ | ------- | ------ | ---------------------------------------------------------------- |
183
+ | List | GET | `/flow/app/v2/list_app` (`be_public=1` for plaza; optional `uniform_type`) |
184
+ | View | GET | `/flow/app/v3/view_app` |
185
+ | Create | POST | `/flow/app/v3/create_app` |
186
+ | Update | POST | `/flow/app/v3/update_app` |
187
+ | Clone | POST | `/flow/app/v3/clone_app` |
188
+ | Privacy | POST | `/flow/app/v3/edit_privacy_app` (`2` submit / `0` private) |
189
+ | Delete | POST | `/flow/app/v2/delete_app` (confirm path in code when wiring CLI) |
190
+
191
+ Authoritative field dump (Console repo): `website-sensecraft-console/docs/app-edit-v3-custom-app-field-reference.md`.
192
+
193
+ ## Additional resources
194
+
195
+ - [commands.md](commands.md) — CLI flags for every shipped `app` subcommand
196
+ - [reference-app-fields.md](reference-app-fields.md) — app info + BOM compliance
197
+ - [reference-tool-blocks.md](reference-tool-blocks.md) — tool-block configs and selection
@@ -0,0 +1,195 @@
1
+ # sensecraft-apps — CLI commands
2
+
3
+ Target binary: `sensecraft-cli` (this repo). Auth: active **SenseCAP Access Key** (`auth init --kind sensecap`) → `{ai-host}/openapi`.
4
+
5
+ > Status: **shipped**. Every command below is implemented — run it rather than describing it. If a flag is rejected, check `--help` instead of assuming the feature is missing.
6
+
7
+ ## Auth prerequisite
8
+
9
+ ```bash
10
+ sensecraft-cli auth info
11
+ sensecraft-cli auth init --kind sensecap # user only, interactive
12
+ ```
13
+
14
+ ## Commands
15
+
16
+ ### `app list`
17
+
18
+ **Status: implemented.**
19
+
20
+ List apps.
21
+
22
+ | Flag | Default | Notes |
23
+ | --------------------- | ----------------------- | ------------------------------------------------------------ |
24
+ | `--public` | plaza mode | `be_public=1` |
25
+ | `--mine` | default if neither flag | My apps |
26
+ | `--name` | | Search keyword → API `app_name` (Console app list) |
27
+ | `--scene` | | Scene id |
28
+ | `--uniform-type` | | Device type → API `uniform_type` (`40` reCamera, `32` XIAO ESP32S3, `53` reCamera Pro) |
29
+ | `--mark-type` | | Optional mark filter, such as `like` / `star` when supported |
30
+ | `--page` / `--length` | 1 / 20 | Pagination |
31
+ | `--sandbox` | | Sample JSON, no network |
32
+
33
+ ```bash
34
+ # Application Plaza
35
+ sensecraft-cli app list --public --name "vision" --scene <scene_id> --page 1 --length 20
36
+ sensecraft-cli app list --public --uniform-type 40
37
+
38
+ # My Apps / marked apps
39
+ sensecraft-cli app list --mine
40
+ sensecraft-cli app list --mine --mark-type star
41
+ ```
42
+
43
+ ### `app view`
44
+
45
+ **Status: implemented.**
46
+
47
+ | Flag | Required | Notes |
48
+ | ----------- | -------- | ---------------------------- |
49
+ | `--id` | yes | `app_id` |
50
+ | `--sketch` | no | Draft view (`view_sketch=1`) |
51
+ | `--sandbox` | no | Sample JSON |
52
+
53
+ ```bash
54
+ sensecraft-cli app view --id <app_id>
55
+ sensecraft-cli app view --id <app_id> --sketch
56
+ ```
57
+
58
+ ### `app fields`
59
+
60
+ **Status: implemented.** Prints JSON schema (app info + BOM). Requires AI auth profile; no network.
61
+
62
+ ```bash
63
+ sensecraft-cli app fields
64
+ ```
65
+
66
+ ### `app blocks`
67
+
68
+ **Status: implemented.** Prints deploy layout + tool-block catalog. Requires AI auth profile; no network.
69
+
70
+ ```bash
71
+ sensecraft-cli app blocks
72
+ ```
73
+
74
+ ### `app clone` (L2)
75
+
76
+ **Status: implemented.**
77
+
78
+ | Flag | Required |
79
+ | -------------------- | ------------------------------------------- |
80
+ | `--id` | yes |
81
+ | `--name` | no (default `Clone_<source app_name>`) |
82
+ | `--agree-disclaimer` | **after** user agrees to Disclaimer for Use |
83
+ | `--yes` | **after** user confirmation |
84
+ | `--sandbox` | sample JSON |
85
+
86
+ Matches Console 「克隆应用」`disclaimerAccepted`. Before passing `--agree-disclaimer`, show the user:
87
+
88
+ - https://sensecraft.seeed.cc/legal/en/disclaimer
89
+ - Do **not** pass `--agree-disclaimer` unless the user explicitly agreed (checkbox equivalent)
90
+
91
+ ```bash
92
+ # Ask the user to agree to the disclaimer, then confirm:
93
+ sensecraft-cli app clone --id <source_app_id> --name "My Clone" --agree-disclaimer --yes
94
+ ```
95
+
96
+ ### `app create` / `app update`
97
+
98
+ **Status: implemented.**
99
+
100
+ #### `app create` (not L2)
101
+
102
+ **Intent:** one-shot authoring. Full `--from-json` is allowed **without** `--yes`.
103
+
104
+ | Flag | Notes |
105
+ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
106
+ | `--name` | `app_name` only create (empty shell) |
107
+ | `--from-json` | JSON path or `-`; must include `app_name` if `--name` omitted. Extra fields → follow-up `update_app` **only on the newly created `app_id`** (cannot target an existing app) |
108
+ | `--sandbox` | sample JSON |
109
+
110
+ Rejects `be_public=1` / `privacy=1`. Do **not** confuse with `app update` (existing app → L2).
111
+
112
+ **Success output:** CLI always prints `app_id`, `console_url` (edit `/ai/application/edit?id=…`), and `detail_url` (`/ai/application/detail/<id>?tab=custom&from=my-apps`). The `from=my-apps` query loads the sketch (cover/`images`) the same as Console 我的应用. Do **not** send users to `/application/detail/<id>` without that query — that page fetches `view_sketch=0` and will look like it has no cover after create/restore.
113
+
114
+ **Do not retry create blindly:**
115
+
116
+ - Same `app_name` can be created multiple times (no server-side uniqueness).
117
+ - If stdout looks empty/`{}` or you are unsure, run `app list --mine --name "<app_name>"` **before** another `app create`.
118
+ - Prefer updating the existing `app_id` with `app update --yes` over creating a duplicate.
119
+
120
+ ```bash
121
+ # One-shot full create: deliberately not L2
122
+ sensecraft-cli app create --from-json ./app.json
123
+ # Expect app_id + console_url + detail_url; if missing, list before retrying:
124
+ sensecraft-cli app list --mine --name "My App"
125
+
126
+ # Empty shell
127
+ sensecraft-cli app create --name "My App"
128
+ ```
129
+
130
+ #### `app update` (L2)
131
+
132
+ | Flag | Notes |
133
+ | ------------- | ----------------------- |
134
+ | `--id` | required |
135
+ | `--from-json` | required (path or `-`) |
136
+ | `--yes` | after user confirmation |
137
+ | `--sandbox` | sample JSON |
138
+
139
+ Rejects `be_public=1` / `privacy=1` in **user** payload. If the app is already public (`be_public=1`), CLI injects `be_public=1` on info saves (Console) and JSON includes `sketch_saved`. Under review (`be_public=2`): **refused**. Others' apps (`user_id` ≠ profile): **refused** (clone first).
140
+
141
+ **Info patch merge:** if `--from-json` touches any of `app_name` / `excerpt` / `scene` / `allow_clone` / `allow_commerce` / `images` / `license` / `author`, CLI loads `view_app` (sketch) and fills missing info keys before `update_app`. Sparse `{"app_name":"…"}` rename is OK. Materials/deployment-only JSON is **not** force-merged with info. Private info saves still do **not** copy `be_public` from the existing view.
142
+
143
+ **Always verify** after update (`app view` / `app list`) — API may return `{}` on success.
144
+
145
+ ```bash
146
+ # Ask the user before changing an existing app:
147
+ # Rename (sparse OK — CLI merges other info fields):
148
+ echo '{"app_name":"New Name"}' | sensecraft-cli app update --id <app_id> --from-json - --yes
149
+ sensecraft-cli app view --id <app_id> --sketch # confirm app_name
150
+
151
+ sensecraft-cli app update --id <app_id> --from-json ./app.json --yes
152
+ ```
153
+
154
+ ### `app publish` / `app unpublish` / `app delete` (L2)
155
+
156
+ **Status: implemented.**
157
+
158
+ - `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.
159
+ - **Publish Declaration (required for `publish` only):** matches Console 「发布确认」`warrantyAccepted`. Before passing `--agree-declaration`, show the user:
160
+ - Review will lock editing until approval (or `unpublish`)
161
+ - Declaration URL: https://sensecraft.seeed.cc/legal/en/declaration
162
+ - Do **not** pass `--agree-declaration` unless the user explicitly agreed
163
+ - `unpublish` → `privacy=0` (private / withdraw review). Owner only. No declaration flag.
164
+ - `delete` → `POST /flow/app/v2/delete_app` — **private + owner** (`be_public=0`)
165
+ - **Never** send privacy `1`
166
+ - All require a **separate chat confirm** ([`../confirmation.md`](../confirmation.md)) then `--yes`; `publish` also requires `--agree-declaration`. 「删除应用 demo」is intent — ask first.
167
+
168
+ ```bash
169
+ # after the user replies 确认:
170
+ sensecraft-cli app publish --id <app_id> --agree-declaration --yes
171
+ sensecraft-cli app unpublish --id <app_id> --yes
172
+ sensecraft-cli app delete --id <app_id> --yes
173
+ ```
174
+
175
+ ### `app bom`
176
+
177
+ **Status: implemented.**
178
+
179
+ | Subcommand | Notes |
180
+ | ---------------------------- | ---------------------------------------------------- |
181
+ | `search [--name]` | `get_production_options` → filter `material_options` |
182
+ | `list --id` | materials from `view_app` |
183
+ | `set --id --from-json --yes` | `update_app` materials[] (L2) |
184
+
185
+ ```bash
186
+ sensecraft-cli app bom search --name "XIAO"
187
+ sensecraft-cli app bom list --id <app_id>
188
+ # Ask the user before replacing materials:
189
+ sensecraft-cli app bom set --id <app_id> --from-json ./materials.json --yes
190
+ ```
191
+
192
+ ## Output
193
+
194
+ Success: indented JSON on stdout (business `data` only).
195
+ Failure: stderr + non-zero exit.
@@ -0,0 +1,95 @@
1
+ # Application info & BOM field reference
2
+
3
+ Agent fill-in guide for SenseCraft custom apps (v3). Aligns with Console `infoForm.vue` / `billForm.vue` / `update_app`.
4
+
5
+ ## App information
6
+
7
+ | Field | UI type | Required | Compliance |
8
+ | -------------------------- | -------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
9
+ | `app_name` | text | yes | max **60** chars, trim; CLI rejects empty / overlength before API |
10
+ | `excerpt` | text (textarea) | yes | max **300** chars, trim; CLI rejects empty / overlength (align publish validateForm) |
11
+ | `scene` | single select | yes | string id from `app_scenarios_array`. **Resolve ids with `sensecraft-cli model constants`**; CLI rejects empty / unknown ids |
12
+ | `allow_clone` | boolean → API `0`/`1` | yes | whether others may clone; CLI rejects null / values other than 0\|1 |
13
+ | `allow_commerce` | boolean → API `0`/`1` | yes | commercial use flag; CLI rejects null / values other than 0\|1 |
14
+ | `images` | multi image upload → URL[] | yes | **JPG / GIF / PNG** (CLI also accepts WebP like Console); **≤ 5 MB** each; **max 16** (Console `maxImageCount`); **min 1**; first image = **cover**; prefer **4:3**. Also send `pic_url` (= `images[0]`). CLI rejects null / `[]` / non-http(s) URLs. |
15
+ | `license` | text / derived | with full save | string; often set with license confirmations |
16
+ | `be_public` | lifecycle | n/a for draft edit | `0` private · `1` public (ops) · `2` pending review. User JSON must not set `1`. Published owner saves: CLI injects `1` (sketch). `2` locks edit. |
17
+ | `app_id` | id | required on update | from create/list/view |
18
+ | `introduction` | legacy long text | no | if non-empty, editor may merge into intro blocks — prefer `deployment.blocks` for new content |
19
+ | `author` | string | recommended on save | current user id/account |
20
+ | `flow_data` / `model_data` | Node-RED sync | only with `node-red` block | `flow_data` must be **JSON string** at top level |
21
+
22
+ ### Create vs update
23
+
24
+ - **Create (CLI one-shot)**: `POST /flow/app/v3/create_app` then `update_app` with the rest of `--from-json` on the **new** `app_id` only — **no `--yes`**. Editing an **existing** app is `app update --yes` (L2).
25
+ - CLI always surfaces `app_id` / `console_url` / `detail_url` after create, even when `update_app` returns `{}`.
26
+ - **Never** retry `app create` solely because the JSON looked empty — run `app list --mine` first; duplicate names are allowed and will spawn extra apps.
27
+ - **Update (`app update`)**: always include `app_id` (CLI `--id`).
28
+ - **Info fields** (`app_name`, `excerpt`, `scene`, `allow_clone`, `allow_commerce`, `images`, `license`, `author`): aiserver often **ignores** a body that only contains `app_name`. CLI **auto-merges** missing info keys from `app view --sketch` before calling `update_app` (does **not** merge `be_public` from user/existing for private apps). If current `be_public=1`, CLI **injects** `be_public=1` like Console info save (plaza unchanged until `app publish`). `be_public=2` refuses update. Agents may pass a sparse rename patch; still **re-read** with `app view` / `app list` after update because success may be `{}`.
29
+ - **Other sections** (`deployment`, `materials`, …): may be sent alone without forcing an info merge. Full leave-save usually sends info + deployment + materials together.
30
+ - **Rename workflow**: confirm with user (L2) → `app update --id … --from-json '{"app_name":"…"}' --yes` (CLI fills the rest) → verify name via `app view --id … --sketch` or `app list --mine --name …`.
31
+
32
+ ## Visibility / review
33
+
34
+ | User action | Value to send | Level |
35
+ | ------------------------------- | --------------------------------- | ---------- |
36
+ | Keep / make private (unpublish) | `0` | L2 confirm |
37
+ | Submit for review | `2` | L2 confirm |
38
+ | Become public `1` | **Do not send as end-user Agent** | L4 Admin |
39
+
40
+ API: `POST /flow/app/v3/edit_privacy_app` (CLI name: `publish` / `unpublish`).
41
+
42
+ ## BOM (`materials[]`)
43
+
44
+ ### Seeed Studio catalog row
45
+
46
+ | Field | Required | Notes |
47
+ | ---------- | -------- | ----------------------------------------- |
48
+ | `id` | yes | product **SKU** |
49
+ | `name` | yes | product name |
50
+ | `quantity` | yes | string |
51
+ | `note` | yes | remark (may be empty string if UI allows) |
52
+ | `buy_url` | yes | purchase link |
53
+
54
+ Pick products with `app bom search` (filters `material_options` from `get_production_options`).
55
+
56
+ **Price / image for Seeed rows:** `price` and `pic_url` **exist in the catalog** and are returned by `app bom search`, but they are **not part of `materials[]`**. Console re-looks them up by SKU (`billForm.vue` picker, `preview.vue` BOM total). So:
57
+
58
+ - Reporting a Seeed product's price/image to the user: **supported** — read them from `app bom search`.
59
+ - Writing them into the app: **not a field** — persist the SKU in `id` and the platform resolves price/image.
60
+
61
+ ### Custom / other product row
62
+
63
+ | Field | Required | Notes |
64
+ | ---------- | -------- | ------------------------------------------------------------------------------------------- |
65
+ | `name` | yes | product name |
66
+ | `quantity` | yes | string (Console UI integer stepper; API often string) |
67
+ | `note` | no | optional remark (Console placeholder: optional) |
68
+ | `buy_url` | no | optional purchase link (invalid URL may become `""`) |
69
+ | `id` | **omit** | custom rows must **not** include `id` |
70
+ | image | — | **Not supported**: the Console "其他" row has no image input and no upload path |
71
+ | price | — | **Not supported**: no price input; `preview.vue` counts custom rows as `0` in the BOM total |
72
+
73
+ Custom rows are exactly `name` / `quantity` / `note` / `buy_url` (Console `buildMaterialsArray`). Do not invent `price` / `pic_url` / `image` keys — they are silently dropped, and the app will look "saved but lost".
74
+
75
+ ### Example
76
+
77
+ ```json
78
+ {
79
+ "materials": [
80
+ {
81
+ "id": "113991254",
82
+ "quantity": "1",
83
+ "name": "Seeed Studio XIAO ESP32S3 Sense",
84
+ "note": "Main MCU",
85
+ "buy_url": "https://www.seeedstudio.com/"
86
+ },
87
+ {
88
+ "quantity": "1",
89
+ "name": "Custom enclosure",
90
+ "note": "3D printed",
91
+ "buy_url": "https://example.com/part"
92
+ }
93
+ ]
94
+ }
95
+ ```