@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 +13 -2
- package/package.json +1 -1
- package/skills/sensecraft-cli/SKILL.md +1 -1
- package/skills/sensecraft-cli/create-app/SKILL.md +16 -6
- package/skills/sensecraft-cli/create-app/references/project-discovery.md +2 -2
- package/skills/sensecraft-cli/references/app-commands.md +23 -10
- package/skills/sensecraft-cli/references/app-fields.md +4 -4
- package/skills/sensecraft-cli/references/apps.md +37 -3
- package/skills/sensecraft-cli/references/file-commands.md +3 -0
- package/skills/sensecraft-cli/references/files.md +2 -1
- package/skills/sensecraft-cli/references/tool-blocks.md +1 -1
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` |
|
|
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
|
|
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
|
@@ -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
|
|
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.**
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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": [...] }`
|
|
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
|
|
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.
|
|
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
|
-
- **
|
|
37
|
-
- **
|
|
38
|
-
- **
|
|
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
|
|
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.
|
|
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
|
|
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
|
|