@seeed-studio/sensecraft-cli 0.1.2 → 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.
- package/INSTALL.md +442 -0
- package/LICENSE +21 -0
- package/README.md +50 -0
- package/package.json +28 -5
- package/scripts/constants.js +18 -3
- package/scripts/download.js +64 -16
- package/scripts/download.test.js +110 -0
- package/scripts/paths.js +28 -4
- package/scripts/paths.test.js +92 -0
- package/scripts/platform.js +8 -2
- package/scripts/postinstall.js +28 -7
- package/scripts/test-install.js +121 -0
- package/skills/README.md +32 -0
- package/skills/confirmation.md +54 -0
- package/skills/sensecraft-ai/SKILL.md +129 -0
- package/skills/sensecraft-apps/SKILL.md +197 -0
- package/skills/sensecraft-apps/commands.md +195 -0
- package/skills/sensecraft-apps/reference-app-fields.md +95 -0
- package/skills/sensecraft-apps/reference-tool-blocks.md +132 -0
- package/skills/sensecraft-data/SKILL.md +180 -0
- package/skills/sensecraft-data/commands.md +858 -0
- package/skills/sensecraft-devices-cloud/SKILL.md +53 -0
- package/skills/sensecraft-devices-cloud/commands.md +58 -0
- package/skills/sensecraft-files/SKILL.md +73 -0
- package/skills/sensecraft-files/commands.md +61 -0
- package/skills/sensecraft-models/SKILL.md +196 -0
- package/skills/sensecraft-models/commands.md +177 -0
- package/skills/sensecraft-models/reference-model-fields.md +139 -0
|
@@ -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
|
+
```
|