@seeed-studio/sensecraft-cli 0.4.5 → 0.4.7

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.5",
3
+ "version": "0.4.7",
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
 
@@ -46,7 +46,7 @@ Read the applicable references in the table **before** doing each part. Build ev
46
46
 
47
47
  **App information.** Read [app-fields.md](../references/app-fields.md) in full before synthesizing these fields, including its activity selection guidance. Keep the project's name unless the user chooses a change. Write an excerpt for the intended reader: what it does, who uses it, and the useful outcome. Propose a scene label and its real ID from `app_scenarios_array`. Preserve known choices for `allow_clone` and `allow_commerce`; if unknown, ask rather than inherit template defaults or infer permissions from the license. Resolve author from the authenticated account when established; identify the project license separately. Inspect cover/gallery candidates and keep their order explicit. No cover is allowed for a private draft; note the publishing requirement.
48
48
 
49
- **Activity participation.** Use the project understanding from discovery and follow [app-fields.md § Activity selection](../references/app-fields.md#activity-selection-during-app-authoring) to decide whether to join an activity. Record the resolved selection in `info.activity_id` and the rationale in the review.
49
+ **Activity participation.** Whether to join, and which activity, is the user's decision: present the candidates from discovery with a recommendation and ask. Follow [app-fields.md § Activity selection](../references/app-fields.md#activity-selection-during-app-authoring). Record the user's selection in `info.activity_id` and the rationale in the review.
50
50
 
51
51
  **Deployment.** Read all of [tool-blocks.md](../references/tool-blocks.md), then map the complete first-time user journey to its supported blocks. For each action, record prerequisites, the chosen tool, verified config/artifact source, and the observable result. Inspect real artifact existence, target/architecture, build configuration, and required runtime inputs. A firmware file does not establish a model-deploy step; source code alone does not establish a flashable image. Place each tool directly after its instructions in a flat `deployment.blocks` array.
52
52
 
@@ -58,7 +58,7 @@ Record the query and selected result in review notes. Multiple plausible variant
58
58
 
59
59
  ## 3. Resolve uncertain decisions
60
60
 
61
- Present a concise project summary, proposed fields, activity selection or reason for none, deployment actions/tools, BOM matches, and actual gaps. Batch questions about consequential choices: name/language/audience when unclear, scene, clone/commercial permissions, uncertain activity eligibility/selection, hardware variant and BOM scope/quantity, assets, or an unsupported deployment path. Include a recommendation and why; reuse answers already in the conversation.
61
+ Present a concise project summary, proposed fields, activity candidates with a recommendation, deployment actions/tools, BOM matches, and actual gaps. Batch questions about consequential choices: name/language/audience when unclear, scene, clone/commercial permissions, activity choice (join which activity or none), hardware variant and BOM scope/quantity, assets, or an unsupported deployment path. Include a recommendation and why; reuse answers already in the conversation.
62
62
 
63
63
  Ask only for uncertainty that affects correctness or the user's choice. Do not require an arbitrary one-round limit: a new material conflict can need a follow-up. Continue independent preparation while waiting, but do not commit guessed decisions or perform dependent uploads. Review is not an extra approval gate when the requested creation and all necessary decisions are already authorized.
64
64
 
@@ -94,23 +94,31 @@ 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 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:
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
+
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
100
108
  grep -aqE 'mgst_[A-Za-z0-9_-]{43}' <firmware-file>
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 may rewrite part of that name for security, so `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.
@@ -44,11 +44,11 @@ When docs and code disagree, inspect enough to identify the conflict. Use establ
44
44
 
45
45
  ## Ask after discovery has made the choice concrete
46
46
 
47
- Read the field and tool-block references before proposing options. After discovery, run `app activity list` and read the guides/rules for plausible activities per [app-fields.md](../../references/app-fields.md#activity-selection-during-app-authoring); the public activity list does not need an Access Key. Use the gathered project facts to choose a clear fit or none, and ask only when the fit or choice is uncertain. After the agent establishes auth, resolve scene IDs and BOM catalog candidates through the real CLI reads. Record the queries, selected results, source links, and lookup time; offline/sandbox data is not live confirmation. Then batch remaining decisions with a recommendation and a short reason. Typical questions concern:
47
+ Read the field and tool-block references before proposing options. After discovery, run `app activity list` and read the guides/rules for plausible activities per [app-fields.md](../../references/app-fields.md#activity-selection-during-app-authoring); the public activity list does not need an Access Key. Use the gathered project facts to rank the candidates, then ask the user to choose an activity or none. After the agent establishes auth, resolve scene IDs and BOM catalog candidates through the real CLI reads. Record the queries, selected results, source links, and lookup time; offline/sandbox data is not live confirmation. Then batch remaining decisions with a recommendation and a short reason. Typical questions concern:
48
48
 
49
49
  - Product framing or language when the conversation and project do not establish it.
50
50
  - Clone and commercial-use choices; a project license alone does not answer these platform settings.
51
- - Activity options plus no participation when eligibility, missing requirements, or the best candidate is uncertain. Include actual dates, rules and project fit; do not ask a generic opt-in question for every new app.
51
+ - Activity choice for every new app: which candidate to join, or none. Include actual dates, rules, fit and gaps, and a recommendation; never ask a generic opt-in question without candidates.
52
52
  - Similar hardware variants, optional accessories, unknown quantities, or a custom product fallback.
53
53
  - Missing deployable files, an unsupported action, or a choice to upload an explicitly incomplete draft.
54
54
  - Cover selection or an asset with unclear redistribution rights.
@@ -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,13 +211,13 @@ 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
207
218
  ```
208
219
 
209
- The returned `guide_url` is the source for requirements and official rules; requirements are not included as a structured CLI field. Read candidate guides and compare them with the project before selecting an activity. Follow [activity selection during authoring](app-fields.md#activity-selection-during-app-authoring) for choosing a match, choosing none, or asking the user with options. Do not confuse `priority_activity_id` (list ordering) with `activity_id` (joining).
220
+ The returned `guide_url` is the source for requirements and official rules; requirements are not included as a structured CLI field. Read candidate guides and compare them with the project before selecting an activity. Follow [activity selection during authoring](app-fields.md#activity-selection-during-app-authoring) for presenting the candidates, no-activity option, and recommendation that the user chooses from. Do not confuse `priority_activity_id` (list ordering) with `activity_id` (joining).
210
221
 
211
222
  ### `app like` / `app unlike` / `app collect` / `app uncollect` / `app mark-deploy` (L2)
212
223
 
@@ -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,13 +29,13 @@ 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
 
36
- - **Clear suitable activity:** select it with a concise evidence-based reason. If several qualify and one is clearly preferable for this project, explain that choice. Do not use result order or a popular-list `priority_activity_id` as the entry decision.
37
- - **No suitable activity:** select no participation and explain the mismatch or lack of open activities. Omit `activity_id`; do not use `0`, invent an ID, or ask a redundant opt-in question when the evidence supports the decision.
38
- - **Uncertain choice or eligibility:** ask with concrete options: candidate names/IDs, dates with a timezone, important requirements and project fit/gaps, plus **no activity**. Recommend the best-supported option. Reuse known answers. Do not change the project's agreed permissions or invent missing eligibility facts to make an entry fit. If new permission choices or required consent are unresolved, ask about those with the activity options.
36
+ - **Always ask the user.** Never choose participation here, even when one candidate is an obvious fit: whether to join and which activity are the user's decision. Ask with concrete options: each candidate's name and ID, its window with a timezone, the requirements and fit gaps that matter, plus **no activity**. Recommend the best-supported option and say why. Never use result order or a popular-list `priority_activity_id` as the recommendation.
37
+ - **Empty list:** no activity is open, so nothing can be joined; report it and continue without one. A failed request is not an empty list.
38
+ - **Unverified eligibility:** ask with the same options and name what is unverified. Do not change the project's agreed permissions or invent missing eligibility facts to make an entry fit; unresolved permission or consent choices belong in the same question.
39
39
 
40
40
  Record the chosen activity or no-activity reason, lookup time, API/guide sources, applicable rules, and project evidence in local review notes. For `create-app`, store the optional selection in `info.activity_id` and include its positive integer at payload top level on the initial one-shot create; the CLI applies it in the new app's follow-up save. Always send the resolved `allow_clone` explicitly: the CLI may otherwise turn it on when joining an activity. An explicit `allow_clone: 0` is technically preserved by the CLI, but does not establish eligibility for a contest requiring cloning.
41
41
 
@@ -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 server may rewrite part of that name for security. Use the returned `file_url` as the access link. Do not build a URL from `--name` or from the printed `file_name`; that name may not be the object that can be opened. stdout `file_name` echoes the name sent, not a name read back from the cloud.
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. **Use the returned access link.** Optional `--name` is the `file_name` sent to the server. The server may rewrite part of that name for security. 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. `file_name` is the name sent with `--name` or the local base name; the server may store the object under a different 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 point to the Muse Gadget application image, built as `muse-gadget.bin` and linked at `0x20000`. Upload it with `file upload --path <build-dir>/muse-gadget.bin --type 4 --name <project>-muse-gadget.bin`. The server may rewrite part of the stored name, so `firmware_url` must be 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