@seeed-studio/sensecraft-cli 0.4.2 → 0.4.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/skills/sensecraft-cli/create-app/SKILL.md +2 -2
- package/skills/sensecraft-cli/create-app/assets/validate_manifest.py +52 -30
- package/skills/sensecraft-cli/create-app/references/manifest.md +14 -12
- package/skills/sensecraft-cli/references/app-commands.md +3 -3
- package/skills/sensecraft-cli/references/app-fields.md +1 -1
- package/skills/sensecraft-cli/references/apps.md +3 -3
- package/skills/sensecraft-cli/references/recamera-commands.md +1 -1
- package/skills/sensecraft-cli/references/tool-blocks.md +24 -14
package/package.json
CHANGED
|
@@ -68,7 +68,7 @@ Read [manifest.md](references/manifest.md) and the template. Populate the canoni
|
|
|
68
68
|
|
|
69
69
|
- Hash the exact local image and artifact bytes to be uploaded. Keep firmware/model/archive paths, sizes, hashes, and destination block IDs in review notes; those paths do not belong in public tool configs.
|
|
70
70
|
- Local images have `file_url: null` until uploaded. A pending tool URL is not a fake `https://example.com/...` link. Explain every pending input in review notes and the user summary.
|
|
71
|
-
- Use the field locations from the references: `flash-firmware
|
|
71
|
+
- Use the field locations from the references: every tool, including `flash-firmware`, stores its settings inside one `block.config` object. The ordered blocks array is flat; tool settings are nested. SKU and `uniform_type` are distinct. Sizes are strings.
|
|
72
72
|
- Store no access keys, device keys, SDK tokens, or personal credentials in the manifest, notes, or distributed artifacts. Check candidate archives/binaries for embedded credentials; if found, identify the affected artifact without echoing the secret and resolve a clean distribution path with the user before upload.
|
|
73
73
|
- After gather and each successful push: in git, keep the canonical manifest reviewable in the working tree and follow the user's established Git workflow; outside git, also write an immutable `.sensecraft/archive/<manifest-stem>.YYYYMMDD-HHmmss.json` snapshot. Avoid overwriting a same-second snapshot. Retain the verified sync baseline per the manifest contract; do not hand versioning commands to the user.
|
|
74
74
|
|
|
@@ -93,7 +93,7 @@ Update the review notes with corrections, evidence, remaining gaps, and readines
|
|
|
93
93
|
## 6. Upload and create once
|
|
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 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
|
-
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
|
|
96
|
+
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.
|
|
97
97
|
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`.
|
|
98
98
|
4. Write `.sensecraft/<manifest-stem>.payload.json`, then create **without `--yes`**:
|
|
99
99
|
```bash
|
|
@@ -28,8 +28,16 @@ EXCERPT_MAX = 300 # UTF-16 code units
|
|
|
28
28
|
SCENE_RE = re.compile(r"^[0-9]+$")
|
|
29
29
|
TEXT_BLOCK_TYPES = {"step", "paragraph", "h1", "h2", "h3", "h4", "h5", "h6",
|
|
30
30
|
"bullet", "number", "todo", "quote", "code", "divider"}
|
|
31
|
-
|
|
32
|
-
|
|
31
|
+
# Modern deployment.blocks uses one config envelope for every tool. Keep these
|
|
32
|
+
# config-relative fields aligned with internal/service/app_tool_blocks.go.
|
|
33
|
+
TOOL_CONFIG_FIELDS = {
|
|
34
|
+
"flash-firmware": {"device_id", "device_type", "flash_mode", "firmware_url", "firmware_name", "firmware_size", "flash_address", "project_zip_url", "project_zip_name", "project_zip_size", "precheck_fields", "muse_gadget", "full_flash"},
|
|
35
|
+
"deploy-ai-model": {"model", "device_type", "powerMode", "conf", "iou", "threshold", "triggerAction", "deploy_tool_entry", "firmware_url"},
|
|
36
|
+
"ai-vibration": {"detectionType", "deviceType", "windowSize", "isPower", "gpio", "dStatus"},
|
|
37
|
+
"deploy-container-app": {"app_id", "app_key", "app_display_name", "app_icon", "app_description", "architecture", "architectures", "version", "version_options", "install_form", "merged_service", "user_override_flags", "form_field_values", "raw_by_version", "detail_form_fields"},
|
|
38
|
+
"node-red": {"flow_data_url", "flow_data", "model_id", "model_data"},
|
|
39
|
+
"aily-blockly": {"project_id", "device_id"},
|
|
40
|
+
}
|
|
33
41
|
FLASH_ADDRESSES = {"0x0", "0x4000", "0x10000", "0x90000"}
|
|
34
42
|
SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
|
|
35
43
|
QUANTITY_RE = re.compile(r"^[1-9][0-9]*$")
|
|
@@ -264,45 +272,59 @@ def main():
|
|
|
264
272
|
if block_type == "step" and (not isinstance(b.get("title"), str) or not b["title"].strip()):
|
|
265
273
|
vio(f"{label}: step block needs a non-empty title string")
|
|
266
274
|
cfg = b.get("config")
|
|
275
|
+
if block_type in TOOL_CONFIG_FIELDS:
|
|
276
|
+
if not isinstance(cfg, dict):
|
|
277
|
+
vio(f"{label}: tool block needs a config object; flat legacy fields are not rendered")
|
|
278
|
+
continue
|
|
279
|
+
if TOOL_CONFIG_FIELDS[block_type].intersection(b):
|
|
280
|
+
vio(f"{label}: tool settings belong inside config; remove flat or duplicated settings")
|
|
281
|
+
if isinstance(cfg.get("config"), (dict, list)):
|
|
282
|
+
vio(f"{label}: remove the extra config.config wrapper")
|
|
283
|
+
elif block_type not in TEXT_BLOCK_TYPES:
|
|
284
|
+
vio(f"{label}: unsupported block type")
|
|
267
285
|
if block_type == "flash-firmware":
|
|
268
|
-
if "
|
|
269
|
-
vio(f"{label}:
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
mode =
|
|
286
|
+
if "device_id" in cfg and not isinstance(cfg["device_id"], str):
|
|
287
|
+
vio(f"{label}: config.device_id must be a SKU string")
|
|
288
|
+
elif not cfg.get("device_id"):
|
|
289
|
+
warn(f"{label}: config.device_id is pending — resolve the exact device SKU")
|
|
290
|
+
for key in ("device_type", "firmware_name", "project_zip_name", "flash_mode", "flash_address", "firmware_url", "project_zip_url"):
|
|
291
|
+
if key in cfg and not isinstance(cfg[key], str):
|
|
292
|
+
vio(f"{label}: config.{key} must be a string (empty is allowed for a pending value)")
|
|
293
|
+
mode = cfg.get("flash_mode")
|
|
276
294
|
if mode is None or mode == "":
|
|
277
|
-
warn(f"{label}: flash_mode is pending")
|
|
295
|
+
warn(f"{label}: config.flash_mode is pending")
|
|
278
296
|
elif mode not in ("bin", "zip"):
|
|
279
|
-
vio(f"{label}: flash_mode must be bin or zip")
|
|
297
|
+
vio(f"{label}: config.flash_mode must be bin or zip")
|
|
280
298
|
else:
|
|
281
299
|
prefix = "firmware" if mode == "bin" else "project_zip"
|
|
282
|
-
if not
|
|
283
|
-
warn(f"{label}: {prefix}_url is pending — deployment input incomplete")
|
|
300
|
+
if not cfg.get(prefix + "_url"):
|
|
301
|
+
warn(f"{label}: config.{prefix}_url is pending — deployment input incomplete")
|
|
284
302
|
for size_key in ("firmware_size", "project_zip_size"):
|
|
285
|
-
if size_key in
|
|
286
|
-
vio(f"{label}: {size_key} must be a string")
|
|
287
|
-
elif
|
|
288
|
-
vio(f"{label}: {size_key} must be a positive byte count string or pending empty string")
|
|
289
|
-
address =
|
|
303
|
+
if size_key in cfg and not isinstance(cfg[size_key], str):
|
|
304
|
+
vio(f"{label}: config.{size_key} must be a string")
|
|
305
|
+
elif cfg.get(size_key) and not QUANTITY_RE.fullmatch(cfg[size_key]):
|
|
306
|
+
vio(f"{label}: config.{size_key} must be a positive byte count string or pending empty string")
|
|
307
|
+
address = cfg.get("flash_address")
|
|
290
308
|
if address is not None and address != "" and (not isinstance(address, str) or address not in FLASH_ADDRESSES):
|
|
291
|
-
vio(f"{label}: unsupported flash_address; read tool-blocks.md for device defaults")
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
309
|
+
vio(f"{label}: unsupported config.flash_address; read tool-blocks.md for device defaults")
|
|
310
|
+
for key in ("muse_gadget", "full_flash"):
|
|
311
|
+
if key in cfg and type(cfg[key]) is not bool:
|
|
312
|
+
vio(f"{label}: config.{key} must be a JSON boolean")
|
|
313
|
+
if cfg.get("muse_gadget") is True and cfg.get("full_flash") is True:
|
|
314
|
+
vio(f"{label}: config.full_flash must be false when config.muse_gadget is true")
|
|
315
|
+
if block_type == "node-red":
|
|
316
|
+
if cfg.get("flow_data") is not None and not isinstance(cfg["flow_data"], (dict, list)):
|
|
317
|
+
vio(f"{label}: config.flow_data must be an object or array, not a JSON string")
|
|
318
|
+
if cfg.get("model_data") is not None and not isinstance(cfg["model_data"], dict):
|
|
319
|
+
vio(f"{label}: config.model_data must be an object or null")
|
|
297
320
|
if isinstance(cfg, dict):
|
|
298
|
-
for
|
|
299
|
-
if not
|
|
321
|
+
for key, val in cfg.items():
|
|
322
|
+
if not key.endswith("_url"):
|
|
300
323
|
continue
|
|
301
|
-
location = k if block_type == "flash-firmware" else "config." + k
|
|
302
324
|
if val is None or val == "":
|
|
303
|
-
warn(f"{label}: {
|
|
325
|
+
warn(f"{label}: config.{key} is empty — pending deployment input")
|
|
304
326
|
elif not http_url(val):
|
|
305
|
-
vio(f"{label}: {
|
|
327
|
+
vio(f"{label}: config.{key} must be a valid http(s) URL or a pending empty value")
|
|
306
328
|
|
|
307
329
|
materials = m.get("bom", {}).get("materials", [])
|
|
308
330
|
if not isinstance(materials, list):
|
|
@@ -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`,
|
|
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. The flat array layout does not permit flat tool settings; modern blocks are not wrapped on read. 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
|
|
|
@@ -90,7 +90,7 @@ Build that object as `{"info": {...}, "images": ["<URL>", ...], "deployment": {.
|
|
|
90
90
|
### Compare on update or resume
|
|
91
91
|
|
|
92
92
|
1. Load the retained baseline and check its digest against `sync.last_pushed_hash`. Compare it with the current local projection and the latest remote sketch/BOM to identify local changes, remote changes, and real conflicts.
|
|
93
|
-
2. Normalize equivalent representations consistently: numeric scene/SKU/device-type/size/quantity values to their canonical strings; clone/commercial flags to integers; image objects to URL strings.
|
|
93
|
+
2. Normalize equivalent representations consistently: numeric scene/SKU/device-type/size/quantity values to their canonical strings; clone/commercial flags to integers; image objects to URL strings. Keep every tool config nested. When comparing historical malformed firmware blocks, move their flat settings into `config` without losing fields; do not flatten valid nested blocks. Verify the original retained hash before comparison normalization, and advance the baseline only after a verified push. Conflicting flat/nested values require reconciliation. Treat missing optional empty note/URL strings consistently. Preserve block, image, and BOM order and every substantive tool field.
|
|
94
94
|
3. Exclude the `activity_id` join instruction, derived duplicates (`pic_url`, top-level Node-RED mirrors), and unrelated identity/lifecycle/timestamp fields from all content-drift projections. Assess any intentional participation change separately, using review evidence and the current activity rules. Do not drop a non-empty stable managed field from both sides merely because a remote response omitted it; that is a verification gap to resolve. Do not normalize away a new/deleted/reordered block, a changed URL, or an unknown substantive field.
|
|
95
95
|
4. If an old manifest has only a hash and no retained baseline, recover it from a trusted last-pushed snapshot when possible. Otherwise inspect the remote and present the concrete differences for reconciliation before writing. Do not use the already-edited local manifest as an assumed old baseline.
|
|
96
96
|
|
|
@@ -171,15 +171,17 @@ The template is a blank scaffold; the snapshot below illustrates a filled, cover
|
|
|
171
171
|
{
|
|
172
172
|
"id": "ff_1",
|
|
173
173
|
"type": "flash-firmware",
|
|
174
|
-
"
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
174
|
+
"config": {
|
|
175
|
+
"device_id": "102991299",
|
|
176
|
+
"device_type": "",
|
|
177
|
+
"flash_mode": "bin",
|
|
178
|
+
"firmware_url": "https://files.example.invalid/lap-timer.bin",
|
|
179
|
+
"firmware_name": "lap-timer.bin",
|
|
180
|
+
"firmware_size": "412316",
|
|
181
|
+
"flash_address": "0x4000",
|
|
182
|
+
"muse_gadget": false,
|
|
183
|
+
"full_flash": false
|
|
184
|
+
}
|
|
183
185
|
},
|
|
184
186
|
{
|
|
185
187
|
"id": "step_2",
|
|
@@ -212,7 +214,7 @@ The template is a blank scaffold; the snapshot below illustrates a filled, cover
|
|
|
212
214
|
"local_revision": 1,
|
|
213
215
|
"last_pushed_revision": 1,
|
|
214
216
|
"last_pushed_at": "2026-10-28T08:01:00Z",
|
|
215
|
-
"last_pushed_hash": "sha256:
|
|
217
|
+
"last_pushed_hash": "sha256:5921b86fb5500da24a24b2aeb33fd251213d195ee8c96634f0866045b1153d82"
|
|
216
218
|
}
|
|
217
219
|
}
|
|
218
220
|
```
|
|
@@ -115,9 +115,9 @@ Rejects `be_public=1` / `privacy=1`. Do **not** confuse with `app update` (exist
|
|
|
115
115
|
**Success output:** CLI always prints `app_id`, `console_url`, and `detail_url` on CodeCraft Hub (`https://codecraft.seeed.cc/hub`, or `https://test-codecraft.seeed.cc/hub` when the AI host contains `test-`, including `remote_type=Develop`):
|
|
116
116
|
|
|
117
117
|
- edit: `/application/edit?id=<app_id>`
|
|
118
|
-
-
|
|
118
|
+
- app detail: `/view-application/<app_id>-<slug>`
|
|
119
119
|
|
|
120
|
-
|
|
120
|
+
Owner and plaza links are the same path. Do not append `from`, `section`, `state`, or `tab`. The site shows the author's draft when they are logged in, and the published page to everyone else. If a list item has a non-empty `web_link`, give the user that URL instead of `view-application`. Model and legal pages stay on `sensecraft.seeed.cc`.
|
|
121
121
|
|
|
122
122
|
**Do not retry create blindly:**
|
|
123
123
|
|
|
@@ -181,7 +181,7 @@ When `--activity-id` is set and this JSON does not include `allow_clone`, CLI se
|
|
|
181
181
|
|
|
182
182
|
**Status: implemented.**
|
|
183
183
|
|
|
184
|
-
- `publish` → `privacy=2` (submit review). Same path as Console **发布草稿** when the app is already public (`is_sketch` + `be_public=1`). Result may include `draft_publish`. Refused if already `be_public=2` or not owner. stdout `detail_url` is
|
|
184
|
+
- `publish` → `privacy=2` (submit review). Same path as Console **发布草稿** when the app is already public (`is_sketch` + `be_public=1`). Result may include `draft_publish`. Refused if already `be_public=2` or not owner. stdout `detail_url` is `/view-application/<id>-<slug>` with no query. Give the user that URL. Do not append navigation params or replace it with `/application/detail/<id>`.
|
|
185
185
|
- **Publish Declaration (required for `publish` only):** matches Console 「发布确认」`warrantyAccepted`. Before passing `--agree-declaration`, show the user:
|
|
186
186
|
- Review will lock editing until approval (or `unpublish`)
|
|
187
187
|
- Declaration URL: https://sensecraft.seeed.cc/legal/en/declaration
|
|
@@ -19,7 +19,7 @@ Agent fill-in guide for SenseCraft custom apps (v3). Aligns with Console `infoFo
|
|
|
19
19
|
| `author` | string | recommended on save | current user id/account |
|
|
20
20
|
| `activity_id` | positive integer | no | Join this activity. Omit or send blank to leave existing activity tags unchanged. CLI sends a JSON number. `0`, negatives, and non-integers are rejected before POST. Server: not a positive integer → `11202` `Request parameters are invalid`; missing / unpublished / deleted / outside start–end → `25000` `Activity does not exist or has expired` (the whole edit is discarded). |
|
|
21
21
|
| `cancel_activity_id` | positive integer | no | Leave this activity. Omit or send blank to leave participation unchanged. CLI sends a JSON number and does not change `allow_clone`. Must not equal `activity_id`. |
|
|
22
|
-
| `flow_data` / `model_data` | Node-RED sync | only with `node-red` block | Block `config.flow_data`
|
|
22
|
+
| `flow_data` / `model_data` | Node-RED sync | only with `node-red` block | Block `config.flow_data` is an object or array; `config.model_data` is an object or null. Neither is a JSON string inside the block. On save the app writes `JSON.stringify(config.flow_data)` to this top-level `flow_data` string and copies `model_data` here. |
|
|
23
23
|
|
|
24
24
|
### Activity selection during app authoring
|
|
25
25
|
|
|
@@ -88,7 +88,7 @@ sensecraft-cli app unpublish --id <app_id> --yes # privacy=0 private / withdr
|
|
|
88
88
|
sensecraft-cli app delete --id <app_id> --yes # private only (be_public=0)
|
|
89
89
|
```
|
|
90
90
|
|
|
91
|
-
`app publish` matches Console 「发布确认」: show https://sensecraft.seeed.cc/legal/en/declaration and warn that review locks editing; only then pass `--agree-declaration --yes`. Missing either flag → non-zero. API body is still only `{app_id, privacy:2}` (agreement is client-side, like Console `warrantyAccepted`). stdout includes `detail_url`:
|
|
91
|
+
`app publish` matches Console 「发布确认」: show https://sensecraft.seeed.cc/legal/en/declaration and warn that review locks editing; only then pass `--agree-declaration --yes`. Missing either flag → non-zero. API body is still only `{app_id, privacy:2}` (agreement is client-side, like Console `warrantyAccepted`). stdout includes `detail_url`: `https://codecraft.seeed.cc/hub/view-application/<id>-<slug>`. Give the user that URL as printed. Do not append `from`, `section`, `state`, or `tab`. Do **not** invent `/application/detail/<id>`.
|
|
92
92
|
|
|
93
93
|
**Never** send `privacy=1` (ops-approved public). After editing a **published** app, tell the user plaza is unchanged until they confirm `app publish --agree-declaration --yes`.
|
|
94
94
|
|
|
@@ -121,8 +121,8 @@ For a local project/repository or an existing `codecraft-app.json`, use [create-
|
|
|
121
121
|
```bash
|
|
122
122
|
sensecraft-cli app create --from-json ./app.json
|
|
123
123
|
# CLI returns app_id + console_url + detail_url (even if update_app body was {}).
|
|
124
|
-
# detail_url is https://codecraft.seeed.cc/hub/view-application/<id>-<slug
|
|
125
|
-
# (test AI host or remote_type Develop → https://test-codecraft.seeed.cc/hub).
|
|
124
|
+
# detail_url is https://codecraft.seeed.cc/hub/view-application/<id>-<slug>
|
|
125
|
+
# (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.
|
|
126
126
|
# A non-empty web_link on a list item is the link to give the user.
|
|
127
127
|
# Restore JSON may have pic_url (list) or images[] (view); CLI writes both.
|
|
128
128
|
# Show links to the user. NEVER re-run create because stdout looked empty —
|
|
@@ -57,7 +57,7 @@ Runs the same check, then opens `console_url` (or prints it). Sandbox never open
|
|
|
57
57
|
| Flag | Required | Notes |
|
|
58
58
|
| ------------- | -------- | --------------------------------------------- |
|
|
59
59
|
| `--model-id` | one of | Model detail = AI deploy page (click 部署) |
|
|
60
|
-
| `--app-id` | one of | App detail
|
|
60
|
+
| `--app-id` | one of | App detail: `/view-application/<id>-<slug>` only |
|
|
61
61
|
| `--print-only`| no | Print URL only |
|
|
62
62
|
| `--sandbox` | no | Sample JSON; never open a browser |
|
|
63
63
|
|
|
@@ -12,7 +12,7 @@ Check the exact hardware variant, artifact target/architecture, deployment input
|
|
|
12
12
|
|
|
13
13
|
The editor does **not** render Markdown on read. Preview wraps each block by `type` and treats `content` as HTML or plain text. Raw `**bold**`, `# heading`, or `- item` inside `content` shows up as those characters.
|
|
14
14
|
|
|
15
|
-
Write inline formatting as HTML the editor stores: `<strong>`, `<em>`, `<code>`, `<s>`, links with `target="_blank"`, file links (pdf/zip/bin/…) also with `download` and `doc-file-download-link`, images with `draggable="false"`. A paragraph that is only a video URL becomes `<video controls>` or a `video-embed-wrapper` iframe (YouTube, TikTok, Douyin, Bilibili, Vimeo, Youku, iQiyi).
|
|
15
|
+
Write inline formatting as HTML the editor stores: `<strong>`, `<em>`, `<code>`, `<s>`, links with `target="_blank"`, file links (pdf/zip/bin/…) also with `download` and `doc-file-download-link`, images with `draggable="false"`. A paragraph that is only a video URL becomes `<video controls>` or a `video-embed-wrapper` iframe (YouTube, TikTok, Douyin, Bilibili, Vimeo, Youku, iQiyi). Compile Markdown rather than writing that HTML by hand. For interleaved prose/tools, compile locally, insert tools at their intended positions, and send the final blocks through `--from-json`. Combining `--from-md` with JSON tool blocks appends those tools after the entire compiled document; it does not place them into earlier steps. `--from-json` fills video, link, and image attributes when they are missing. Do not wrap a `paragraph` in an extra `<p>`. `code` block `content` is plain source, not HTML.
|
|
16
16
|
|
|
17
17
|
Compile a Markdown file with `sensecraft-cli app doc compile --from-md <file>` when you only want the JSON (no network). `app create --from-md` and `app update --from-md` run that compile and then write. JSON text blocks that still contain Markdown markers are rejected. How the toolbar maps onto blocks: [../../../docs/md-to-app.md](../../../docs/md-to-app.md).
|
|
18
18
|
|
|
@@ -22,6 +22,8 @@ Host binaries (images, videos, firmware) via `file upload` first. A relative pat
|
|
|
22
22
|
|
|
23
23
|
`deployment.blocks` is a **flat** ordered array.
|
|
24
24
|
|
|
25
|
+
“Flat” describes the array of blocks, not a tool's settings. Every tool block stores its settings inside one `config` object. The page reads `block.config.*` directly for this format; it does not wrap fields from the block root on read. Flattened settings belong to the separate legacy `deployment[].tools[]` format and must not be copied into modern `deployment.blocks[]`.
|
|
26
|
+
|
|
25
27
|
```text
|
|
26
28
|
[ intro text blocks... ] [ step ][ text|tools... ] [ step ][ text|tools... ] ...
|
|
27
29
|
```
|
|
@@ -58,7 +60,7 @@ Multiple tool-blocks may appear in one step (e.g. paragraph → flash → paragr
|
|
|
58
60
|
|
|
59
61
|
### `flash-firmware`
|
|
60
62
|
|
|
61
|
-
Write
|
|
63
|
+
Write every field below inside **`block.config`**, just like other tool blocks, for `app create` / `app update`. Keep `id`, `type`, and layout metadata on the block itself. Reject flat or mixed root/config settings and an extra `config.config` wrapper; do not rely on opening the editor to repair them. Existing flat blocks need an explicit migration that preserves all their settings.
|
|
62
64
|
|
|
63
65
|
| Field | How to write |
|
|
64
66
|
|-------|----------------|
|
|
@@ -68,8 +70,8 @@ Write these as **flat fields** on the block. The editor wraps them into `config`
|
|
|
68
70
|
| `firmware_url` / `firmware_name` / `firmware_size` | Bin mode. `firmware_size` is a string, not a number. Empty `firmware_name` is filled from the URL by the editor |
|
|
69
71
|
| `flash_address` | Only `"0x0"`, `"0x4000"`, `"0x10000"`, `"0x90000"`. Use the device default below. The editor resets a non-default address the first time the doc is opened. Do not write `0x20000` here |
|
|
70
72
|
| `project_zip_url` / `project_zip_name` / `project_zip_size` / `precheck_fields` | Zip mode only. Sizes are strings. `precheck_fields` is `[{ key, name, info, type, default }]` from `sensecraft_config.h`, or omit / `[]` |
|
|
71
|
-
| `muse_gadget` |
|
|
72
|
-
| `full_flash` |
|
|
73
|
+
| `muse_gadget` | JSON boolean, default `false`; write `true`/`false`, never strings or numbers. Some read paths coerce non-booleans by truthiness, so `"false"` can enable the option. `true` shows the Muse SDK token input under the flash button in preview |
|
|
74
|
+
| `full_flash` | JSON boolean, default `false`. Kept only on the Muse SKUs below; any other device is reset to `false`. `true` erases the whole flash before the write. When `muse_gadget` is `true`, set `full_flash` to `false`. The editor hides the checkbox while Muse is on |
|
|
73
75
|
|
|
74
76
|
`muse_gadget: true` is kept only for these SKUs. Any other device written `true` is reset to `false` by the editor. `full_flash` uses the same SKU list:
|
|
75
77
|
|
|
@@ -173,7 +175,7 @@ Used for **container / edge app** deployment UI inside the application doc. Fiel
|
|
|
173
175
|
| Path | Notes |
|
|
174
176
|
|------|-------|
|
|
175
177
|
| `config.flow_data_url` | Flow file URL |
|
|
176
|
-
| `config.flow_data` | Parsed flow; also sync top-level `flow_data` as **JSON string** |
|
|
178
|
+
| `config.flow_data` | Parsed flow object **or array**, not a JSON string; also sync top-level `flow_data` as **JSON string** |
|
|
177
179
|
| `config.model_id` | Cascade pair; `['3', id]` = my model |
|
|
178
180
|
| `config.model_data` | Snapshot; sync top-level `model_data` |
|
|
179
181
|
|
|
@@ -206,15 +208,23 @@ Used for **container / edge app** deployment UI inside the application doc. Fiel
|
|
|
206
208
|
{
|
|
207
209
|
"id": "ff_1",
|
|
208
210
|
"type": "flash-firmware",
|
|
209
|
-
"
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
211
|
+
"config": {
|
|
212
|
+
"device_id": "100017057",
|
|
213
|
+
"device_type": "",
|
|
214
|
+
"flash_mode": "bin",
|
|
215
|
+
"firmware_url": "https://example.com/e1002-app.bin",
|
|
216
|
+
"firmware_name": "e1002-app.bin",
|
|
217
|
+
"firmware_size": "1234567",
|
|
218
|
+
"flash_address": "0x90000",
|
|
219
|
+
"muse_gadget": false,
|
|
220
|
+
"full_flash": false
|
|
221
|
+
}
|
|
218
222
|
}
|
|
219
223
|
]
|
|
220
224
|
```
|
|
225
|
+
|
|
226
|
+
## Repair an existing malformed block
|
|
227
|
+
|
|
228
|
+
Read the latest owner sketch, clone its **complete** `deployment`, and move the affected block's settings into `config`, preserving its ID, all values, order, and every other block. If flat and nested values disagree, resolve that conflict before writing. An update containing only a one-element `deployment.blocks` array replaces the document; it is not a patch of that one block.
|
|
229
|
+
|
|
230
|
+
Validate the corrected document and follow the parent's existing-app write protocol. Re-read the sketch afterward and check the saved `config` and unchanged surrounding blocks. Reconcile the project's local manifest and sync baseline too, so a later push does not restore the malformed shape. A successful API response only proves storage; verify the consumer-visible field paths as well.
|