@seeed-studio/sensecraft-cli 0.4.6 → 0.4.8

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/README.zh.md CHANGED
@@ -93,13 +93,16 @@ ls "$(npm root -g)/@seeed-studio/sensecraft-cli/skills"
93
93
  | 命令 | 说明 |
94
94
  |------|------|
95
95
  | `auth add` | 校验 Access Key,写入本机,并设为当前钥匙 |
96
- | `auth info` | 显示站点、组织 ID 和 Key ID |
96
+ | `auth info` | 显示本地认证摘要;加 `--json` 输出结构化数据 |
97
97
 
98
98
  ```bash
99
99
  sensecraft-cli auth add --key-id <Key ID> --access-key <Access Key> --site Global
100
100
  sensecraft-cli auth info
101
+ sensecraft-cli auth info --json
101
102
  ```
102
103
 
104
+ `auth info --json` 返回 `{ "profiles": [...] }`,每项仅含 `site`、`org_id`、`key_id`、`kind`、`created_at` 和 `active`。
105
+
103
106
  | `--site` | SenseCAP OpenAPI | SenseCraft AI OpenAPI |
104
107
  |----------|------------------|------------------------|
105
108
  | `Global` | `https://sensecap.seeed.cc/openapi` | `https://api-gateway.seeed.cc/openapi` |
@@ -136,9 +139,17 @@ sensecraft-cli recamera check --model-id <id>
136
139
 
137
140
  `app list --sort` 取 `popular`、`newest` 或 `likes`。常用 `--uniform-type`:`40` reCamera,`32` XIAO ESP32S3,`53` reCamera Pro。
138
141
 
142
+ 从未发布的应用,`app view --id <id>` 只能读到名称。读取已保存草稿用 `app view --id <id> --sketch`。
143
+
144
+ `app bom search --name "XIAO ESP32-S3 1.47"` 会逐词匹配产品名称、SKU、分类、备注或描述,忽略大小写和标点。结果保持目录原顺序。目录保留 `block_support`,并增加布尔值 `block_supported`(`"是"` 对应 `true`)。
145
+
146
+ `file upload --name <文件名>` 是发给服务器的文件名。服务器出于安全考虑可能会改写其中一部分。访问上传后的文件请使用返回的 `file_url`。
147
+
148
+ `app activity list` 返回当前还在举办的全部活动,`count` 是这次 `list` 的条数。
149
+
139
150
  ## 进阶
140
151
 
141
- 成功的数据命令把缩进 JSON 打到 stdout。`auth add` 和 `auth info` 打可读文本。失败在 stderr,退出码非 0。
152
+ 成功的数据命令把缩进 JSON 打到 stdout。含 `list` 且没有 `count` 的对象会补上当前结果的条数;`page` 和服务器已经给出的 `count` 保持原值。`auth add` 和默认的 `auth info` 打可读文本,`auth info --json` 输出认证摘要。失败在 stderr,退出码非 0。
142
153
 
143
154
  `sensecraft-cli --version` 打印 npm 包版本。直接 `go build` 的二进制打印 `dev`。
144
155
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@seeed-studio/sensecraft-cli",
3
- "version": "0.4.6",
3
+ "version": "0.4.8",
4
4
  "description": "SenseCAP / SenseCraft AI cloud CLI (devices, apps, models, files, cloud deploy)",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -51,7 +51,7 @@ SenseCraft Data: [`references/data.md`](references/data.md).
51
51
 
52
52
  Bare `auth init` asks the user to pick Global or China. The split flow takes `--site` instead. The China site supports SenseCraft Data only. To use SenseCraft AI or CodeCraft Hub, select Global. Do not point the CLI at another host. The login access token stays in the local pending file and is not printed.
53
53
 
54
- `auth info` shows the active Access Key (site, org, key id). Secrets are not printed.
54
+ `auth info` shows local Access Key metadata as text. `auth info --json` returns `{ "profiles": [...] }` with `site`, `org_id`, `key_id`, `kind`, `created_at`, and `active` only. Secrets are not printed.
55
55
 
56
56
  ## Intent → skill / command routing
57
57
 
@@ -94,6 +94,14 @@ Update the review notes with corrections, evidence, remaining gaps, and readines
94
94
 
95
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
96
 
97
+ For Muse Gadget, upload the application image built as `muse-gadget.bin` and linked at `0x20000`. Give each app its own requested name:
98
+
99
+ ```bash
100
+ sensecraft-cli file upload --path <build-dir>/muse-gadget.bin --type 4 --name <project>-muse-gadget.bin
101
+ ```
102
+
103
+ The server may rewrite part of that name. `firmware_url` must be the returned `file_url`.
104
+
97
105
  For Muse Gadget 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
106
 
99
107
  ```bash
@@ -101,16 +109,16 @@ Update the review notes with corrections, evidence, remaining gaps, and readines
101
109
  ```
102
110
 
103
111
  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.
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.
112
+ 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. Optional `file upload --name` only sets the name sent to the server. The server decides the stored object name, so a name specified for the upload is not necessarily the downloaded file name. `firmware_url` and every other stored URL must be the returned `file_url`. Do not build a URL from `--name` or from stdout `file_name`. Never expose temporary signed upload URLs in review prose.
105
113
  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`.
106
114
  4. Write `.sensecraft/<manifest-stem>.payload.json`, then create **without `--yes`**:
107
115
  ```bash
108
116
  sensecraft-cli app create --from-json .sensecraft/codecraft-app.payload.json
109
117
  ```
110
118
  Parse successful stdout for `app_id`, `console_url`, and `detail_url`. Record the ID and local UTC `created_at` immediately, before verification. On any ambiguous failure or missing ID/URLs, run `app list --mine --name "<app_name>"` before deciding whether creation happened; do not blindly retry. An internal follow-up save may fail after creating the app: recover that ID and resume by update.
111
- 5. Re-read `app view --id <app_id> --sketch` and `app bom list --id <app_id> --sketch`. Compare intended fields, image order, blocks/configs, and BOM rows, accounting for documented server normalization. Verify any requested activity association per the activity reference. A create response alone is not proof all sections saved. On a mismatch preserve the ID and report/repair through the update path.
119
+ 5. Re-read `app view --id <app_id> --sketch` and `app bom list --id <app_id> --sketch`. Confirm stdout `view_kind` is `sketch`. Compare intended fields, image order, blocks/configs, and BOM rows, accounting for documented server normalization. For an app never published, the default `app view` returns only its name; `--sketch` reads the saved draft. Verify any requested activity association per the activity reference. A create response alone is not proof all sections saved. On a mismatch preserve the ID and report/repair through the update path.
112
120
  6. Only after verification, advance `sync.last_pushed_*` using the manifest contract and snapshot. Delete only transient payloads created by this session after success; preserve prior files and failure evidence.
113
- 7. Report app name, ID, returned editor/detail links, counts, manifest revision/path, activity choice/result, and readiness. State **private draft (`be_public=0`)**; private and deployment-ready are separate facts. Missing cover affects publishing; missing tool inputs affect deployment. Never claim the hardware was flashed or the app is public. Publish/unpublish/delete/clone use [apps.md](../references/apps.md).
121
+ 7. Report app name, ID, returned editor/detail links, counts, manifest revision/path, activity choice/result, and readiness. State **private draft (`be_public=0`)**; private and deployment-ready are separate facts. Missing cover affects publishing; missing tool inputs affect deployment. Tell the user to test flash on the **editor** (`console_url`); the bare `detail_url` preview may still show the empty published shell. Close the editor while CLI updates so auto-save cannot overwrite the sketch. Never claim the hardware was flashed or the app is public. Sketch vs published: [apps.md](../references/apps.md#sketch-vs-published-snapshots). Publish/unpublish/delete/clone use [apps.md](../references/apps.md).
114
122
 
115
123
  ## Existing app: update or resume
116
124
 
@@ -118,6 +126,8 @@ Read the references for the affected sections before editing them. Preserve the
118
126
 
119
127
  Handle activity participation on updates per [app-fields.md](../references/app-fields.md#activity-selection-during-app-authoring) and the manifest projection rules.
120
128
 
129
+ Have the user close this app's CodeCraft Hub editor page before CLI updates, then reopen it after verification. An open editor saves the copy it loaded and can replace changes made through the CLI meanwhile.
130
+
121
131
  1. Edit the manifest first, increment `sync.local_revision`, and validate. Recheck auth: `identity.remote_type` and `org_id` must match. A mismatch requires switching auth or an explicit decision to adopt the environment; do not write across environments silently.
122
132
  2. Read `app view --id <app_id> --sketch`. Under review (`be_public=2`) → stop and explain the lock. Do not give `/application/edit` or `console_url`; the editor rejects the save. Editing resumes only after `app withdraw` (separate confirmation), not `app unpublish`. Compare with the last verified baseline per [manifest sync](references/manifest.md#sync--local-vs-remote-bookkeeping). Detect outside edits, merge non-conflicting changes, and present conflicts as concrete choices. No verified baseline after a partial create → inspect current remote state and reconcile; never assume it is empty.
123
133
  3. Complete local preparation and review before any outstanding L2 confirmation. Describe environment, app name/ID, and the entire pending batch. Follow the [confirmation protocol](../references/confirmation.md), honoring valid approval already given for that batch; do not ask per field/upload/BOM row.
@@ -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. 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.
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. `firmware_url` is the returned `file_url`. The object name in that URL is the name used to download the file; the name specified for the upload is not necessarily that name. 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
 
@@ -53,17 +53,28 @@ sensecraft-cli app list --public --mark-type 1
53
53
 
54
54
  **Status: implemented.**
55
55
 
56
- | Flag | Required | Notes |
57
- | ----------- | -------- | ---------------------------- |
58
- | `--id` | yes | `app_id` |
59
- | `--sketch` | no | Draft view (`view_sketch=1`) |
60
- | `--sandbox` | no | Sample JSON |
56
+ | Flag | Required | Notes |
57
+ | ----------- | -------- | ------------------------------------------------------------------ |
58
+ | `--id` | yes | `app_id` |
59
+ | `--sketch` | no | Draft / sketch (`view_sketch=1`). Default = published snapshot (`0`) |
60
+ | `--sandbox` | no | Sample JSON |
61
61
 
62
62
  ```bash
63
- sensecraft-cli app view --id <app_id>
64
- sensecraft-cli app view --id <app_id> --sketch
63
+ sensecraft-cli app view --id <app_id> # published snapshot (view_kind=published)
64
+ sensecraft-cli app view --id <app_id> --sketch # draft / sketch (view_kind=sketch)
65
65
  ```
66
66
 
67
+ Stdout always includes CLI markers:
68
+
69
+ - `view_kind`: `"sketch"` \| `"published"`
70
+ - `view_sketch`: `1` \| `0`
71
+
72
+ These mark **which snapshot this command requested**. They are not the same as API `is_sketch` (whether a draft differs from the published copy).
73
+
74
+ **After `app create` / `app update`:** always re-read with `--sketch`. On a private draft, default `app view` is often only the create shell (name, little or no deployment). Full info, BOM, and flash-firmware blocks live in the sketch until `app publish` promotes them. See [apps.md — Sketch vs published](apps.md#sketch-vs-published-snapshots).
75
+
76
+ **Hub flash testing (private draft):** use the editor (`console_url`), or open the app from my-apps / user-center. Do not assume the bare `detail_url` preview shows sketch content.
77
+
67
78
  ### `app fields`
68
79
 
69
80
  **Status: implemented.** Prints JSON schema (app info + BOM). Requires AI auth profile; static output, zero network — **no `--sandbox` flag; run bare**.
@@ -169,7 +180,7 @@ sensecraft-cli app update --id <app_id> --activity-id 1 --yes
169
180
  sensecraft-cli app update --id <app_id> --cancel-activity-id 1 --yes
170
181
  ```
171
182
 
172
- `activity_id` must be a positive integer. List activities in progress with `app activity list` first. Before POST, CLI loads the server activity list (activities that have not ended, which can include ones that have not started). If that request succeeds and does not contain the id, CLI does not POST. A failed list request is ignored. The server still rejects a bad id with `11202` and a missing or expired activity with `25000` `Activity does not exist or has expired` (the whole edit is discarded). Omitting `activity_id` does not change existing activity tags. `tags` is not read by the server.
183
+ `activity_id` must be a positive integer. List every activity currently being held with `app activity list` first. Before POST, CLI loads that same server list. If that request succeeds and does not contain the id, CLI does not POST. A failed list request is ignored. The server still rejects a bad id with `11202` and a missing or expired activity with `25000` `Activity does not exist or has expired` (the whole edit is discarded). Omitting `activity_id` does not change existing activity tags. `tags` is not read by the server.
173
184
 
174
185
  `cancel_activity_id` must be a positive integer. CLI sends it as a JSON number and does not check the ongoing list or change `allow_clone`. Omitting it leaves participation unchanged. The same id cannot be both `activity_id` and `cancel_activity_id`.
175
186
 
@@ -200,7 +211,7 @@ sensecraft-cli app delete --id <app_id> --yes
200
211
 
201
212
  ### `app activity list`
202
213
 
203
- **Status: implemented.** Read-only. No Access Key. `GET /activity/list` with no `time` query. stdout is `{ "list": [...] }` for activities in progress now: numeric `activity_id`, `name`, `guide_url`, and `start_time` / `end_time` as UTC timestamps (`2026-10-18T16:00:00Z`). Rows outside that window, or missing an id, name, or either time, are dropped. Tag ids are not shown.
214
+ **Status: implemented.** Read-only. No Access Key. `GET /activity/list` with no `time` query. The server defaults to the current time and returns every activity currently being held, not a page and not activities that have ended or not started. The CLI does not filter that set again. stdout is `{ "count": N, "list": [...] }` with numeric `activity_id`, `name`, `guide_url`, and `start_time` / `end_time` converted to UTC (`2026-10-18T16:00:00Z`). `count` is the number of activities in this result. An empty result is `{ "count": 0, "list": [] }`. Rows missing an id, a name, or either time are omitted. Tag ids are not shown.
204
215
 
205
216
  ```bash
206
217
  sensecraft-cli app activity list
@@ -246,6 +257,8 @@ sensecraft-cli app clone --id <source_app_id> --name "New name" --yes
246
257
  | `list --id [--sketch]` | materials from `view_app`; use `--sketch` to verify saved draft rows |
247
258
  | `set --id --from-json --yes` | `update_app` materials[] (L2) |
248
259
 
260
+ Search returns `{count, list}` in catalog order. Every query token must occur in the product name, SKU, category, note or description after case and punctuation normalization; `ESP32S3` and `ESP32-S3` are equivalent. `XIAO ESP32-S3 1.47`, `1.47 Touch`, and `Touch Display ESP32-S3` all find `XIAO 1.47" Touch Display (ESP32-S3)`. An exact SKU query also matches. Each returned catalog `block_support` is preserved, with `block_supported: true` for `"是"` and `false` otherwise.
261
+
249
262
  ```bash
250
263
  sensecraft-cli app bom search --name "XIAO"
251
264
  sensecraft-cli app bom list --id <app_id>
@@ -29,7 +29,7 @@ For a new app, assess participation using the project discovery results; do not
29
29
  sensecraft-cli app activity list
30
30
  ```
31
31
 
32
- Read [the activity command reference](app-commands.md#app-activity-list) before using the result. The current CLI returns `activity_id`, `name`, UTC `start_time`/`end_time`, and `guide_url` for activities open now. It does **not** return a structured requirements field. Open and read the API-provided guide for each plausible candidate, including its official rules where linked, before claiming eligibility. Missing/inaccessible guidance is an information gap, not proof that there are no requirements. Do not invent an activity-detail CLI or guessed API endpoint.
32
+ Read [the activity command reference](app-commands.md#app-activity-list) before using the result. `app activity list` returns every activity currently being held: the server already limits the list to the current time, and the CLI does not drop rows by time again. Each row has `activity_id`, `name`, UTC `start_time`/`end_time`, and `guide_url`. It does **not** return a structured requirements field. Open and read the API-provided guide for each plausible candidate, including its official rules where linked, before claiming eligibility. Missing/inaccessible guidance is an information gap, not proof that there are no requirements. Do not invent an activity-detail CLI or guessed API endpoint.
33
33
 
34
34
  Compare the documented theme, entry window/deadline, eligibility, supported/required hardware or features, required artifacts/demo/docs, and licensing/clone/commercial conditions with the actual project and settled user choices. Distinguish what the project already satisfies from deliverables still needed. A successful empty list means no currently available activity; a failed request is not an empty list. Sandbox output is not a live activity or eligibility check.
35
35
 
@@ -19,10 +19,37 @@ Child skill: [`../create-app/SKILL.md`](../create-app/SKILL.md) — turn a local
19
19
  **`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.
20
20
  3. **Privacy values**: submit review → `privacy` / flow uses **`2`** (pending); unpublish/private → **`0`**. **Never send `1`** (ops-approved public; Admin only).
21
21
  4. Tool-block **configuration** may be written into `deployment.blocks`. **Executing** flash / USB deploy / container install on hardware is **L3**. Classic reCamera (`40`): [`sensecraft-recamera`](recamera.md) (`check` / `open`). Other benches: Console `/ai/device/local/32|36|37|41|52`. `flash-firmware` run is out of scope this pass.
22
- 5. Parse indented JSON on stdout; on failure read stderr + exit code. After `app update`, **re-read** the app — success body may be `{}`.
22
+ 5. Parse indented JSON on stdout; on failure read stderr + exit code. After `app update`, **re-read with `--sketch`** — success body may be `{}`, and default `app view` is the published snapshot (often an empty create shell / name-only on private drafts).
23
23
  6. **Rename / edit info**: sparse `{"app_name":"…"}` is OK (CLI merges other info fields from sketch). Do not invent HTTP; do **not** put `be_public=1` in user JSON. For **already published** apps the CLI injects `be_public=1` (Console info save) and returns `sketch_saved` — plaza copy is unchanged until `app publish`.
24
24
  7. **Lifecycle vs Console**: edit / publish / unpublish / withdraw / delete / BOM / cover only for **your** apps (`user_id` == profile). Another user's plaza app cannot be edited. `be_public=2` locks owner edit and has no editor link; unlock with `app withdraw`, not `app unpublish`. `be_public=1` owner may save sketch then `app publish` (草稿). `app unpublish` is only for an already public app. Delete only `be_public=0`.
25
25
  8. **Never blind-retry `app create`**: names are not unique. If create output lacks `app_id` or looks empty, run `app list --mine` before creating again.
26
+ 9. **Sketch vs published** ([below](#sketch-vs-published-snapshots)): `app create` / `app update` write the **sketch**. Verify with `app view --sketch`. Do not treat default `app view` or a bare Hub preview URL as proof that CLI content is live.
27
+
28
+ ## Sketch vs published snapshots
29
+
30
+ Each app has two `view_app` snapshots:
31
+
32
+ | Snapshot | CLI | `view_sketch` | Written by |
33
+ | -------- | --- | ------------- | ---------- |
34
+ | **Sketch** (draft) | `app view --id … --sketch` | `1` | `app create` follow-up save, `app update`, Hub editor save, BOM set |
35
+ | **Published** | `app view --id …` (default) | `0` | `create_app` shell (often name-only); promoted on `app publish` |
36
+
37
+ `app view` stdout always includes CLI markers (not server fields):
38
+
39
+ - `view_kind`: `"sketch"` or `"published"`
40
+ - `view_sketch`: `1` or `0`
41
+
42
+ Do **not** confuse these with `is_sketch` from the API (`1` means a draft differs from the published snapshot).
43
+
44
+ **Private drafts (`be_public=0`):** default `app view` (no `--sketch`) is frequently only the create shell — no excerpt, deployment, or flash blocks — while `--sketch` shows what CLI just wrote. Always re-read with `--sketch` after create/update.
45
+
46
+ **Hub pages:**
47
+
48
+ - **Editor** (`console_url` / `/hub/application/edit?id=…`): loads sketch (`view_sketch=1`). Flash-firmware blocks here see CLI content. Keep the editor closed while CLI writes; an open editor can auto-save older content over a fresh `app update`.
49
+ - **Preview** (`detail_url` = `/hub/view-application/<id>-<slug>`, no query): visitors see the published snapshot. Author login *tries* to show the draft, but a private draft's published snapshot may still look empty. Prefer the **editor** (or a my-apps / user-center entry) to test flash on a private draft — not the bare preview URL alone.
50
+ - **Plaza /「查看已发布版本」** (`from=application-store`): always the published snapshot.
51
+
52
+ **When the published snapshot updates:** create shell at `app create`; then usually only when `app publish` promotes the sketch (submit review / publish draft). Daily editor or CLI saves stay on the sketch. For an already-public app, plaza stays on the old published copy until `app publish` again (`sketch_saved` hint).
26
53
 
27
54
  ## CLI status
28
55
 
@@ -56,6 +83,8 @@ Summarize: name, excerpt, scene, tool-block types used, BOM highlights, deploy s
56
83
 
57
84
  ### Rename an existing app (L2)
58
85
 
86
+ Have the user close this app's CodeCraft Hub editor page before CLI updates and reopen it after verification. The open editor saves the copy it loaded and can replace CLI changes made meanwhile. Apply this sequence to info, deployment, BOM, cover, and activity updates.
87
+
59
88
  ```bash
60
89
  # Confirm with the user first. Sparse name-only JSON is OK — CLI merges other info fields.
61
90
  echo '{"app_name":"Dimmer Tutorial · Grove Beginner Kit"}' \
@@ -104,6 +133,8 @@ sensecraft-cli app bom set --id <app_id> --from-json ./materials.json --yes
104
133
 
105
134
  Seeed rows need `id`(=SKU). Custom rows omit `id`. No manual custom image upload.
106
135
 
136
+ `app bom search` matches every normalized query token against the product name, SKU, category, note or description, ignoring case and punctuation. `XIAO ESP32-S3 1.47`, `1.47 Touch`, and `Touch Display ESP32S3` match `XIAO 1.47" Touch Display (ESP32-S3)`; exact SKU searches also work. Results keep catalog order and return `{count, list}`. Catalog rows retain `block_support` and add boolean `block_supported` (`true` for `"是"`). Object outputs that contain `list` and have no `count` gain `count` for the current result; existing `page` and a server-provided `count` stay as they are.
137
+
107
138
  ### Author path
108
139
 
109
140
  For a local project/repository or an existing `codecraft-app.json`, use [create-app](../create-app/SKILL.md) for the full discovery, writing review, BOM verification, and manifest workflow. The abbreviated commands below apply to content that is already authored and reviewed; do not bypass that workflow by uploading a developer README directly.
@@ -123,7 +154,9 @@ For a local project/repository or an existing `codecraft-app.json`, use [create-
123
154
  sensecraft-cli app create --from-json ./app.json
124
155
  # CLI returns app_id + console_url + detail_url (even if update_app body was {}).
125
156
  # detail_url is https://codecraft.seeed.cc/hub/view-application/<id>-<slug>
126
- # (test AI host or remote_type Develop → https://test-codecraft.seeed.cc/hub). No query. The site shows the author's draft when they are logged in.
157
+ # (test AI host or remote_type Develop → https://test-codecraft.seeed.cc/hub). No query.
158
+ # Content landed in the sketch — verify with app view --sketch (view_kind=sketch).
159
+ # For private drafts, test flash on the editor (console_url), not the bare preview alone.
127
160
  # A non-empty web_link on a list item is the link to give the user.
128
161
  # Restore JSON may have pic_url (list) or images[] (view); CLI writes both.
129
162
  # Show links to the user. NEVER re-run create because stdout looked empty —
@@ -133,6 +166,7 @@ For a local project/repository or an existing `codecraft-app.json`, use [create-
133
166
  ```bash
134
167
  sensecraft-cli app create --name "My App"
135
168
  sensecraft-cli app update --id <app_id> --from-json ./app.json --yes
169
+ sensecraft-cli app view --id <app_id> --sketch # confirm blocks / flash config
136
170
  ```
137
171
  5. User agrees to Publish Declaration + confirms → `app publish --agree-declaration --yes` (submit review). After that, give `detail_url` only. `be_public=2` has no editor link.
138
172
 
@@ -186,7 +220,7 @@ Base: `{host}/openapi` with HTTP Basic (`key_id`:`access_key`).
186
220
  | Action | Method | Path |
187
221
  | ------- | ------ | ---------------------------------------------------------------- |
188
222
  | List | GET | `/flow/app/v2/list_app` (`be_public`, `order_type` `1`/`2`/`3`, `priority_activity_id`, `mark_type` `1`/`0`) |
189
- | Activities | GET | `/activity/list` (no `time`) |
223
+ | Activities | GET | `/activity/list` (no `time`; server default is now, every activity currently being held) |
190
224
  | View | GET | `/flow/app/v3/view_app` |
191
225
  | Create | POST | `/flow/app/v3/create_app` |
192
226
  | Update | POST | `/flow/app/v3/update_app` |
@@ -9,6 +9,7 @@ Acquires an OSS POST policy, uploads the local file with multipart/form-data, an
9
9
  | Flag | Required | Default | Notes |
10
10
  |------|----------|---------|-------|
11
11
  | `--path` | yes | — | Local file |
12
+ | `--name` | no | local base name | `file_name` sent to `acquire_file_url` and the multipart filename. Spaces are removed |
12
13
  | `--type` | no | `2` | `1=image`, `2=file/model`, `3=app`, `4=firmware`, `5=static resource`, `6=archive/zip` |
13
14
  | `--flow-id` | type 5 | — | Required for static resources; omitted for other types |
14
15
  | `--checksum` | no | false | Compute local MD5 and include it in output |
@@ -31,6 +32,8 @@ Acquires an OSS POST policy, uploads the local file with multipart/form-data, an
31
32
 
32
33
  `--model-id` and `--app-id` are mutually exclusive. Types `1`/`2` without attach/`--for-app`/`--unlinked` exit non-zero **before** the OSS POST (`ErrAttachRequired`). Types `3`–`6` upload directly. Type `5` without `--flow-id` exits before acquire.
33
34
 
35
+ `--name` is only the name sent with the upload. The filename used to access or download the file is the object name in the returned `file_url`. A name specified for the upload is not necessarily that download name. stdout `file_name` echoes the name sent, not a name read back from the server. Do not build a URL from `--name` or from the printed `file_name`.
36
+
34
37
  ```bash
35
38
  sensecraft-cli file upload --path ./cover.png --type 1 --for-app
36
39
  sensecraft-cli file upload --path ./cover.png --type 1 --app-id <app_id> --yes
@@ -23,6 +23,7 @@ Auth: **Access Key**. The China site supports SenseCraft Data only; file upload
23
23
  7. Do not pass oversized files or more than 16 app image URLs; CLI rejects them before upload/update.
24
24
  8. Types `3`–`6` have no model/app attach path and upload directly (no `--unlinked` needed).
25
25
  9. **Security gates**: empty (0 B) files rejected; type 2–6 ≤ **100 MB**; every image ≤ **5 MB**. The CLI does not count uploads. A rate limit comes back as `11209` or `11210`.
26
+ 10. **The access name is the server's.** Optional `--name` is the `file_name` sent to the server. The filename used to open or download the file is the object name in the returned `file_url`. A name specified for the upload is not necessarily that download name. Put the returned `file_url` into the app or model payload. Do not build a URL from `--name`, the local file name, or stdout `file_name`.
26
27
 
27
28
  ## Examples
28
29
 
@@ -51,7 +52,7 @@ sensecraft-cli file upload --path ./dataset.zip --type 6 --checksum
51
52
  sensecraft-cli file upload --path ./fixture.bin --type 2 --checksum --unlinked --sandbox
52
53
  ```
53
54
 
54
- Success JSON contains `file_name`, `file_type`, `file_url`, `size`, optional `checksum`, and `attached`.
55
+ Success JSON contains `file_name`, `file_type`, `file_url`, `size`, optional `checksum`, and `attached`. `file_url` is the access link, and the object name in it is the name the server stored. `file_name` is the name sent with `--name` or the local base name; it is not necessarily the downloaded file name.
55
56
  When attached to a model it also includes `model_id`, `previous_version`, `version`. Explicit `--unlinked` / `--for-app` sets `attached: false` and a `hint`.
56
57
 
57
58
  ## Model shortcut
@@ -84,7 +84,7 @@ Write every field below inside **`block.config`**. Keep `id` and `type` on the b
84
84
  | XIAO 1.47" Touch Display | `100069905` |
85
85
  | reTerminal Sticky | `100056818` |
86
86
 
87
- When `muse_gadget` is `true`, set `full_flash` to `false`. The editor hides that checkbox until Muse is turned off. `firmware_url` must be `muse-gadget.bin` linked at `0x20000`. A binary linked at `0x90000` or `0x10000` will not boot. Checking the box does not change `flash_address`: E100x stays `0x90000`, Sticky / Indicator / 1.47" Touch stay `0x0`, Watcher stays on the XIAO address rule.
87
+ When `muse_gadget` is `true`, set `full_flash` to `false`. The editor hides that checkbox until Muse is turned off. `firmware_url` must be the Muse application image linked at `0x20000`. The local build product is usually `muse-gadget.bin`; the name stored by the server does not have to stay that name. Upload it with `file upload --path <build-dir>/muse-gadget.bin --type 4 --name <project>-muse-gadget.bin`, and set `firmware_url` to the returned `file_url`. A binary linked at `0x90000` or `0x10000` will not boot. Checking the box does not change `flash_address`: E100x stays `0x90000`, Sticky / Indicator / 1.47" Touch stay `0x0`, Watcher stays on the XIAO address rule.
88
88
 
89
89
  `full_flash: true` with `muse_gadget: false` is the switch back from a Muse image to another firmware. E1001 / E1002 then also rewrite the stock bootloader at `0x0` and the partition table at `0x8000`; the app stays at `0x90000`. Indicator, 1.47" Touch, Sticky, and Watcher non-Muse images are already merged at `0x0`, so the flag only turns on erase-all. Do not put the reTerminal stock bootloader into those images, and do not put it into a Muse image.
90
90
 
@@ -106,7 +106,7 @@ Unchecked `muse_gadget` keeps the single-file device table below and does not re
106
106
  | XIAO ESP32C3 | `113991054` | `bin` or `zip` | URL contains `application` → `0x10000`, otherwise `0x0` | `.bin` or zip |
107
107
  | XIAO ESP32C6 / S3 / S3 Plus | matching SKU (`material.device_id` empty; row comes from `app_block_options`) | same as C3 | same as C3 | same as C3 |
108
108
  | XIAO ESP32S3 Sense | `113991115` | same as C3 | same as C3 | same as C3 |
109
- | SenseCAP Watcher | `113991315` or `113991275` (one group) | `bin` | same as XIAO, optional | `.bin` on the Xiao / ESP32-S3 port |
109
+ | SenseCAP Watcher | `113991315` or `113991275` (one group) | `bin` | `0x0` | `merged-binary.bin`: bootloader at `0x0`, partition table at `0x8000`, app at `0x10000` |
110
110
  | Wio Terminal | `102991299` | `bin` | `0x4000` | `.bin` |
111
111
  | Grove Beginner Kit | `110061162` | `bin` | `0x0` (address bar hidden; `.hex` uses addresses inside the file) | `.bin` or `.hex`. `.hex` locks the board to this kit |
112
112
  | XIAO 0.96" / 1.14" IPS, 1.47" Touch (ESP32-S3) | representative SKU of the group; 1.47" Touch Muse SKU is `100069905` | `bin` | `0x0` | merged `.bin`. nRF52840 variants cannot be flashed |
@@ -116,7 +116,9 @@ Unchecked `muse_gadget` keeps the single-file device table below and does not re
116
116
  | reTerminal Sticky | `100056818` | `bin` | `0x0` | merged `.bin` |
117
117
  | SenseCAP Indicator D1 / D1S / D1L / D1Pro | one group; example `114993068` (D1) | `bin` | `0x0` | merged ESP32-S3 `.bin`, not the RP2040 port |
118
118
 
119
- `.hex` is only for Grove Beginner (`110061162`). E100x, e-paper, Sticky, IPS, Touch, and Indicator accept `.bin` only. Do not use zip for Grove, Wio, those screens, or Indicator. XIAO C3 / C6 / S3 / S3 Sense / S3 Plus / Watcher keep 115200 and `flashSize` / `flashMode` / `flashFreq` = `keep`; do not apply the screen `0x90000` or merged-`0x0` rules to them.
119
+ A SenseCAP Watcher project that is not joining an activity uploads `merged-binary.bin` at `0x0`. Build it from the same `flash_args` (`0x0` bootloader, `0x8000` partition table, `0x10000` app). Leave out the app-only `.bin`, `bootloader.bin`, and `partition-table.bin`. The file name and URL must not contain `application`; that word moves the write to `0x10000`. Keep `full_flash` false.
120
+
121
+ `.hex` is only for Grove Beginner (`110061162`). E100x, e-paper, Sticky, IPS, Touch, and Indicator accept `.bin` only. Do not use zip for Grove, Wio, those screens, or Indicator. XIAO C3 / C6 / S3 / S3 Sense / S3 Plus / Watcher keep 115200 and `flashSize` / `flashMode` / `flashFreq` = `keep`. Screen boards use `0x90000`. A Watcher project that is not joining an activity uses `merged-binary.bin` at `0x0`.
120
122
 
121
123
  **Agent:** write the SKU, file, and address into the app doc. **Do not** claim the firmware was flashed. Serial flashing stays L3 (Console / Web Serial).
122
124