@seeed-studio/sensecraft-cli 0.3.1 → 0.4.0

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.
Files changed (28) hide show
  1. package/INSTALL.md +151 -190
  2. package/README-zh.md +463 -0
  3. package/README.md +9 -13
  4. package/package.json +2 -1
  5. package/scripts/test-install.js +1 -1
  6. package/skills/README.md +14 -35
  7. package/skills/sensecraft-cli/SKILL.md +131 -0
  8. package/skills/{sensecraft-apps → sensecraft-cli}/create-app/SKILL.md +26 -17
  9. package/skills/{sensecraft-apps → sensecraft-cli}/create-app/assets/manifest-template.json +1 -1
  10. package/skills/{sensecraft-apps/create-app/reference-manifest.md → sensecraft-cli/create-app/references/manifest.md} +17 -14
  11. package/skills/{sensecraft-apps/commands.md → sensecraft-cli/references/app-commands.md} +38 -16
  12. package/skills/{sensecraft-apps/reference-app-fields.md → sensecraft-cli/references/app-fields.md} +4 -3
  13. package/skills/{sensecraft-apps/SKILL.md → sensecraft-cli/references/apps.md} +35 -37
  14. package/skills/{sensecraft-devices-cloud/commands.md → sensecraft-cli/references/cloud-commands.md} +1 -1
  15. package/skills/{sensecraft-devices-cloud/SKILL.md → sensecraft-cli/references/cloud.md} +4 -14
  16. package/skills/{confirmation.md → sensecraft-cli/references/confirmation.md} +2 -2
  17. package/skills/{sensecraft-data/commands.md → sensecraft-cli/references/data-commands.md} +2 -2
  18. package/skills/{sensecraft-data/SKILL.md → sensecraft-cli/references/data.md} +10 -18
  19. package/skills/{sensecraft-files/commands.md → sensecraft-cli/references/file-commands.md} +1 -1
  20. package/skills/{sensecraft-files/SKILL.md → sensecraft-cli/references/files.md} +3 -11
  21. package/skills/{sensecraft-models/commands.md → sensecraft-cli/references/model-commands.md} +5 -5
  22. package/skills/{sensecraft-models/SKILL.md → sensecraft-cli/references/models.md} +17 -27
  23. package/skills/{sensecraft-recamera/commands.md → sensecraft-cli/references/recamera-commands.md} +4 -4
  24. package/skills/{sensecraft-recamera/SKILL.md → sensecraft-cli/references/recamera.md} +6 -16
  25. package/skills/{sensecraft-apps/reference-tool-blocks.md → sensecraft-cli/references/tool-blocks.md} +20 -4
  26. package/skills/sensecraft-ai/SKILL.md +0 -134
  27. /package/skills/{sensecraft-apps → sensecraft-cli}/create-app/assets/validate_manifest.py +0 -0
  28. /package/skills/{sensecraft-models/reference-model-fields.md → sensecraft-cli/references/model-fields.md} +0 -0
@@ -0,0 +1,131 @@
1
+ ---
2
+ name: sensecraft-cli
3
+ description: >-
4
+ Operates the SenseCraft CLI across SenseCraft Data (devices, groups, telemetry),
5
+ SenseCraft AI (model library, reCamera), and CodeCraft Hub (applications).
6
+ Use when the user mentions SenseCraft, SenseCraft Data, SenseCraft AI, CodeCraft Hub,
7
+ 应用, 模型库, 上传模型, reCamera, 设备, or sensecraft-cli.
8
+ Open only the reference file for the product being used.
9
+ ---
10
+
11
+ # SenseCraft CLI
12
+
13
+ `sensecraft-cli` is the terminal for the SenseCraft cloud platform. This file is the only entry. Product procedures live in `references/`. A finished local project becomes an app through the nested `create-app` skill.
14
+
15
+ | Product | What it covers | Commands |
16
+ |---------|----------------|----------|
17
+ | SenseCraft Data | devices, groups, telemetry | `device` · `group` · `data` |
18
+ | SenseCraft AI | model library, reCamera | `model` · `recamera` · `cloud` |
19
+ | [CodeCraft Hub](https://codecraft.seeed.cc/hub) | applications | `app` |
20
+
21
+ All three platforms are accessed with an open Access Key. Create or manage a key at https://account.seeed.cc/account/access-keys.
22
+
23
+ SenseCraft Data: [`references/data.md`](references/data.md).
24
+
25
+ ## Agent rules
26
+
27
+ 1. **Use the Access Key before any cloud call**
28
+ - Every cloud command uses the Access Key. SenseCraft Data calls its OpenAPI. `app` / `model` / `file` / `cloud` / `recamera` call `{ai-host}/openapi` with HTTP Basic (no access_token, no `/aiserverapi`)
29
+ - Never send the Access Key as a fake Bearer/JWT
30
+ 2. **Always run auth check first** (ask user to fix if missing):
31
+ ```bash
32
+ sensecraft-cli auth info
33
+ ```
34
+ Published commands require an active **SenseCAP Access Key** → `{ai-host}/openapi` + HTTP Basic.
35
+ 3. **Never run `auth init` on behalf of the user** — browser OAuth Device Flow, interactive TTY only. Tell the user to run locally:
36
+ ```bash
37
+ sensecraft-cli auth init # Access Key (app/model/file/cloud/recamera)
38
+ ```
39
+ 4. **L2 confirmation is a separate chat turn** — follow [references/confirmation.md](references/confirmation.md). 「删这个63760」/「删除应用 demo」is **intent, not confirmation**. Ask first (操作类型 + 环境 + 对象 ID), wait for `确认`/`confirm`, **then** `--yes`. Never add `--yes` on the same turn as the first request. Applies to: app/model create·update·publish·unpublish·delete, upload attach, cloud deploy, device bind/unbind, group create/rename/delete/move.
40
+ 5. **Treat tokens and keys as secrets** — do not echo full `access_token`, `refresh_token`, or `access_key`. **Public model artifacts are not downloadable** — if the user asks for 下载地址 / 下载链接 / download URL / 怎么下载, that is the same as asking for `file_url`: refuse the address, explain deploy-only (`cloud deploy` or Console). Never run `model download --url-only` on public models.
41
+ 6. **Success = indented JSON on stdout**; failure = stderr + non-zero exit. Parse stdout only on success.
42
+ 7. **Local USB / IP flashing is L3** — do not pretend remote auto-flash. Classic reCamera (`40`): [`sensecraft-recamera`](references/recamera.md) (`check` / `open` the AI deploy page). Other USB benches: Console `/ai/device/local/32|36|37|41|52`. Do **not** use `/ai/recamera` (it 301s to Grove `36`) or `/ai/device/local/40` (no such bench).
43
+ 8. **Upgrading the CLI itself** is `sensecraft-cli update` (npm registry, then `npm install -g`). This is not `app update` or `model update`. Uninstall with `npm uninstall -g @seeed-studio/sensecraft-cli`. Do not delete `~/.config/sensecraft-cli` unless the user asked to clear the saved Access Key.
44
+
45
+ ## Auth
46
+
47
+ `auth init` runs Device Flow (`client_id=sensecraft-cli`), exchanges the login for an Access Key, and stores `key_id` + `access_key`. Daily calls use HTTP Basic on SenseCraft Data `/openapi` and on `{ai-host}/openapi` (SenseCraft AI and CodeCraft Hub). An existing key can be saved with `auth add`. Create or manage keys at https://account.seeed.cc/account/access-keys.
48
+
49
+ `auth init` asks the user to pick Global or China. The China site supports SenseCraft Data only. To use SenseCraft AI or CodeCraft Hub, select Global. Do not point the CLI at another host.
50
+
51
+ `auth info` shows the active Access Key (site, org, key id). Secrets are not printed.
52
+
53
+ ## Intent → skill / command routing
54
+
55
+ | User intent | Use | Notes |
56
+ |-------------|-----|--------|
57
+ | SenseCraft Data: list/bind device, groups, telemetry | [`sensecraft-data`](references/data.md) | Shipped today |
58
+ | Browse / search CodeCraft Hub, view app | [`sensecraft-apps`](references/apps.md) + `app list` / `app view` | **CLI shipped** (list/view) |
59
+ | App fields / tool-blocks / BOM guidance | same apps skill references | Config OK; real flash = L3 |
60
+ | Author a new app (create + info + images + BOM + blocks) | [`create-app`](create-app/SKILL.md) | One batch confirmation; stops before publish |
61
+ | Create / update / publish / unpublish / delete / bom app | same + `app …` / `app bom …` | **CLI shipped** (L2 `--yes`; publish also `--agree-declaration`; bare `create --name` not L2) |
62
+ | Upload image/file/firmware/static/archive and obtain `file_url` | [`sensecraft-files`](references/files.md) + `file upload` | Types `1`–`2` require `--model-id`/`--app-id --yes`/`--for-app`/`--unlinked`; type `5` requires `--flow-id`; types `3`–`6` direct |
63
+ | Model library search/view/download/constants | [`sensecraft-models`](references/models.md) | **CLI shipped** |
64
+ | Upload / publish / unpublish / delete model | same + `model upload --id --yes` / `create\|update\|publish\|unpublish\|delete` | Attach bumps patch version like Console |
65
+ | Classic reCamera (`40`) pick / check / open deploy page | [`sensecraft-recamera`](references/recamera.md) + `app/model list --uniform-type 40` + `recamera check` / `open` | **CLI shipped**. Flash is Console L3 (IP/USB). Not `cloud deploy`. Not Pro `53`. |
66
+ | reCamera Pro model library | [`sensecraft-models`](references/models.md) + `model create --target recamera-pro` / `recamera-pro resolve` | Deploy is local IP/USB L3 — not `cloud deploy` |
67
+ | Jetson / cloud kit list & deploy | [`sensecraft-devices-cloud`](references/cloud.md) + `cloud …` | **CLI shipped** (list/view/deploy/order). SenseCraft AI, not SenseCraft Data `device` |
68
+ | Local USB/IP model deploy or firmware flash | [`sensecraft-recamera`](references/recamera.md) then Console Deploy, or `/ai/device/local/32\|36\|37\|41\|52` | **L3 only**; CLI does not talk to the device |
69
+
70
+ ## Cross-domain example
71
+
72
+ SenseCraft Data telemetry → pick a public model → deploy to Jetson:
73
+
74
+ 1. `sensecraft-cli auth info`
75
+ 2. SenseCraft Data: `data latest --eui <eui>` (Access Key)
76
+ 3. SenseCraft AI: `model list --public --name "…"` → `model view --id …` (metadata only; **no** `model download`)
77
+ 4. Confirm with user → `cloud deploy --eui <jetson-eui> --model-id … --yes` (device pulls firmware at apply time)
78
+ 5. `cloud order --request-id …`
79
+
80
+ ## Product-term disambiguation
81
+
82
+ | User says | Possible meanings | Default choice |
83
+ |-----------|-------------------|----------------|
84
+ | application / App Store | CodeCraft Hub app vs in-doc deploy tool-block | **CodeCraft Hub** (`sensecraft-apps`) |
85
+ | device | SenseCraft Data node/gateway vs SenseCraft AI cloud device vs local USB board | Telemetry/bind → **sensecraft-data**; cloud device → devices-cloud; USB/serial → Console local (L3) |
86
+ | deploy a model | Cloud `deploy_model` vs local flash vs app tool-block | Ask which target; local flash = L3 |
87
+ | model download URL / download link / how to download | Public library artifact URL vs private owner file | **Public → no URL**, explain deploy; private My Models → `model download --out` (do not paste URL) |
88
+ | Data | SenseCraft Data telemetry vs training dataset | Telemetry → **sensecraft-data**; dataset → Console |
89
+ | Agent | Watcher Agent vs in-console AI Bot vs these Skills | These Skills ≠ Bot; Watcher has separate auth |
90
+
91
+ ## Capability levels
92
+
93
+ | Level | Meaning | Examples |
94
+ |-------|---------|----------|
95
+ | L1 Scriptable | Agent may run directly | list / view / auth info |
96
+ | L2 Confirm | Ask user first | publish (+ declaration), unpublish, delete, deploy |
97
+ | L3 Interactive | Human-in-the-loop | `auth init`, Web Serial flash, payment |
98
+ | L4 Ops-only | Do not expose to end-user Agent | Admin `judge_app` |
99
+
100
+ ## Shipped commands
101
+
102
+ Published commands use an Access Key. SenseCraft Data uses its OpenAPI. SenseCraft AI and CodeCraft Hub use `{ai-host}/openapi`.
103
+
104
+ 1. **CodeCraft Hub** — `app` list/view/fields/blocks/doc; create/update; publish/unpublish/delete (L2); BOM search/list/set; tool-block config via JSON (real flash = L3).
105
+ 2. **SenseCraft AI** — model library (list/view/constants; **private** download only; public models deploy-only); `model upload --id --yes`; create/update; publish/unpublish/delete (L2). Cloud devices: `cloud device` / `cloud deploy` / `cloud order`. Classic reCamera 40: `recamera check` / `recamera open` (flash is L3).
106
+ 3. **Files** — `file upload` is shared. Types 1–2 require `--model-id` / `--app-id --yes` / `--for-app` / `--unlinked` before the OSS POST. Type 5 also requires `--flow-id`.
107
+ 4. **Local USB** — Other benches: Console `/ai/device/local/32|36|37|41|52`.
108
+
109
+ ## When something is missing
110
+
111
+ SenseCraft AI and CodeCraft Hub commands are `model` / `recamera` / `cloud` and `app`. `file` is shared. If a command fails:
112
+
113
+ 1. Run `sensecraft-cli auth info` — need an active Access Key.
114
+ 2. Do **not** call SenseCraft Data `device`/`data` as a substitute.
115
+ 3. Do **not** scrape Console cookies or invent HTTP with guessed tokens.
116
+ 4. Open the matching file under `references/`. Do not invent a second skill.
117
+
118
+ ## References
119
+
120
+ Read the file for the product in use. Leave the others closed.
121
+
122
+ | When | Read |
123
+ |------|------|
124
+ | Devices, groups, telemetry | [references/data.md](references/data.md), [references/data-commands.md](references/data-commands.md) |
125
+ | Applications | [references/apps.md](references/apps.md), [references/app-commands.md](references/app-commands.md), [references/app-fields.md](references/app-fields.md), [references/tool-blocks.md](references/tool-blocks.md) |
126
+ | Turn a local project into an app | [create-app/SKILL.md](create-app/SKILL.md) |
127
+ | Model library | [references/models.md](references/models.md), [references/model-commands.md](references/model-commands.md), [references/model-fields.md](references/model-fields.md) |
128
+ | Classic reCamera | [references/recamera.md](references/recamera.md), [references/recamera-commands.md](references/recamera-commands.md) |
129
+ | Cloud devices | [references/cloud.md](references/cloud.md), [references/cloud-commands.md](references/cloud-commands.md) |
130
+ | File upload | [references/files.md](references/files.md), [references/file-commands.md](references/file-commands.md) |
131
+ | Write confirmation | [references/confirmation.md](references/confirmation.md) |
@@ -1,21 +1,21 @@
1
1
  ---
2
2
  name: create-app
3
- description: Create a SenseCraft Application Plaza app from a finished local project using a versioned local manifest (sensecraft-app.json) as the single source of truth — mine the project for app info, create the app in one go, then keep later edits local-first and push updates safely with drift detection. Use whenever the user wants to turn a finished or current project into a SenseCraft app, "publish my project" to SenseCraft, make an app from this repo/codebase, or update an app that has a sensecraft-app.json manifest — even if they only say "make this project an app" or "push my app changes". Publishing, unpublishing, deleting, and cloning stay with the parent sensecraft-apps skill.
3
+ description: Create a CodeCraft Hub app from a finished local project using a versioned local manifest (sensecraft-app.json) as the single source of truth — mine the project for app info, create the app in one go, then keep later edits local-first and push updates safely with drift detection. Use whenever the user wants to turn a finished or current project into a SenseCraft app, "publish my project" to SenseCraft, make an app from this repo/codebase, or update an app that has a sensecraft-app.json manifest — even if they only say "make this project an app" or "push my app changes". Publishing, unpublishing, deleting, and cloning stay with the parent sensecraft-cli skill.
4
4
  ---
5
5
 
6
6
  # create-app
7
7
 
8
- Turn a finished local project into a SenseCraft Application Plaza app through a local manifest: gather → write manifest → one-go create → local-first updates.
8
+ Turn a finished local project into a CodeCraft Hub app through a local manifest: gather → write manifest → one-go create → local-first updates.
9
9
 
10
- Parent skill: [`../SKILL.md`](../SKILL.md). Routing: [`../../sensecraft-ai/SKILL.md`](../../sensecraft-ai/SKILL.md).
10
+ Entry skill: [`../SKILL.md`](../SKILL.md). App lifecycle (publish / unpublish / delete / clone): [`../references/apps.md`](../references/apps.md).
11
11
 
12
- > Everything declared upstream applies in full here — lifecycle ops (publish / unpublish / delete / clone) belong to the parent skill, L2 writes follow [`../../confirmation.md`](../../confirmation.md), and the parent's agent rules (auth, visibility values, output contract, re-read after update) hold. Below is only what create-app adds on top.
12
+ > L2 writes follow [../references/confirmation.md](../references/confirmation.md). Auth, site, and output rules in the entry skill still apply. Below is only what create-app adds.
13
13
 
14
14
  ## Why the manifest exists
15
15
 
16
16
  The manifest makes the workflow resumable and safe. It remembers the `app_id` so a retry never spawns a duplicate (the server allows duplicate names). It records what was last pushed so a later Console edit is detected as drift instead of silently overwritten. And in a project without git, its timestamped archive snapshots are the only version history — treat them as precious.
17
17
 
18
- Manifest schema, field-by-field: [reference-manifest.md](reference-manifest.md). Starting template: [assets/manifest-template.json](assets/manifest-template.json).
18
+ Manifest schema, field-by-field: [references/manifest.md](references/manifest.md). Starting template: [assets/manifest-template.json](assets/manifest-template.json).
19
19
 
20
20
  ## Manifest files on disk
21
21
 
@@ -36,7 +36,7 @@ Mine first, ask approval once at the end.
36
36
  - `README*` → `app_name` / `excerpt` candidates (excerpt ≤ 300 UTF-16 code units).
37
37
  - `package.json` / firmware README → name, `license`, `author`.
38
38
  - `docs/`, `images/`, `assets/`, `screenshots/` → image candidates: JPG/JPEG/PNG/GIF/WebP, ≤ 5 MB each, up to 16, first = cover, prefer 4:3. No usable cover yet is fine — a private draft doesn't need one; publishing does. The user decides when to choose, upload, or generate one.
39
- - **Deployment plan**: the steps serve non-developers who can only use the tool blocks provided — plan what they do on the app page (connect, run a block, configure, use), never how the project is built. Read [reference-tool-blocks.md](../reference-tool-blocks.md) before drafting to know what's available. An artifact you can't upload yet never removes a block the flow needs; resolve the config per the reference and mark what's pending. Note candidate artifacts (firmware bins, model files, flow JSON) without deciding yet.
39
+ - **Deployment plan**: the steps serve non-developers who can only use the tool blocks provided — plan what they do on the app page (connect, run a block, configure, use), never how the project is built. Read [../references/tool-blocks.md](../references/tool-blocks.md) before drafting to know what's available. An artifact you can't upload yet never removes a block the flow needs; resolve the config per the reference and mark what's pending. Note candidate artifacts (firmware bins, model files, flow JSON) without deciding yet.
40
40
  - Hardware mentions (XIAO, Grove, reCamera…) → BOM candidates; resolve SKUs with `sensecraft-cli app bom search --name "<kw>"`.
41
41
  2. **Fill gaps in ONE consolidated question round**: present a brief overview of the app fields and the deployment steps, then ask for what is missing — `scene` pick (list ids from `sensecraft-cli model constants` → `app_scenarios_array`; propose the best match), `allow_clone`, `allow_commerce`, and anything you flagged for the user to decide. If a step can't be completed by that audience, surface it here with options instead of writing a flow that contradicts itself. `app_name` defaults to the project's own name — propose any embellishment in the round rather than renaming silently. BOM default scope: **the device plus app-specific accessories named in the project docs** (ordinary cables, computers, and generic tools are excluded). When no Seeed SKU resolves via `app bom search`, custom BOM rows (name/quantity/note/buy_url, no `id`) are the correct fallback.
42
42
  3. **Write the manifest** from the template with `identity.app_id: null`, `sync.local_revision: 1`.
@@ -52,7 +52,16 @@ Mine first, ask approval once at the end.
52
52
 
53
53
  The app editor stores a flat `deployment.blocks` array. It does not keep the Markdown file and it does not re-parse Markdown at preview time. There is no `app import-md` command.
54
54
 
55
- Follow [../../../docs/md-to-app.md](../../../docs/md-to-app.md): lift `app_name` / `excerpt` / scene / BOM out of the prose, map headings that are real user actions to `step` blocks (a `h2` is not a step), and write inline formatting as HTML. Then run the same create → update → publish commands as below. `**bold**` inside `content` will display as asterisks.
55
+ When the source is Markdown, pass it on create or update. The CLI compiles editor HTML, fills `app_name` / `excerpt` when the JSON omits them, and truncates an excerpt longer than 300 characters (see `warnings`).
56
+
57
+ ```bash
58
+ sensecraft-cli app create --from-md ./README.md --from-json .sensecraft/sensecraft-app.payload.json
59
+ sensecraft-cli app update --id <app_id> --from-md ./README.md --yes
60
+ ```
61
+
62
+ `--from-json` `deployment.blocks` are appended after the compiled document. Put tool-blocks there; do not repeat the prose. Upload every `pending_uploads` path, then write the returned https URL back into that block on a follow-up update. `app doc compile --from-md` only prints the JSON and does not create an app. JSON text blocks that still contain Markdown markers are rejected. Scene, cover, and BOM are not invented.
63
+
64
+ Follow [../../../docs/md-to-app.md](../../../docs/md-to-app.md) for step headings (`## 步骤:动作`, `## Step: Flash`, `### 1. 动作`) and for which headings stay headings. A plain `h2` is not a step.
56
65
 
57
66
  Contest entry is a later `app update --activity-id <id>`. CLI also writes `"allow_clone": 1` on that update when the sketch is not already `1` and the JSON did not set `allow_clone`. Confirm the id is in `app activity list` first.
58
67
 
@@ -61,17 +70,17 @@ Contest entry is a later `app update --activity-id <id>`. CLI also writes `"allo
61
70
  Published text is what plaza users actually read — mine it from the project, but author it deliberately.
62
71
 
63
72
  - `excerpt`: what the app is, who it is for, why it is interesting. Nothing else — no hardware/framework spec dump, no deploy steps, no version history or changelog.
64
- - `deployment.blocks` prose: short onboarding steps — necessary prep, main actions, how to start and stop. Include a step only if the feature exists. Target structure: an intro of at most two short paragraphs, then one step per distinct user action (typically 3–5 steps). No full menu enumeration, no exhaustive troubleshooting, no spec tables, no restating the excerpt inside steps. Inline formatting in `content` is HTML, not Markdown. Images and video are uploaded first, then linked; see [reference-tool-blocks.md](../reference-tool-blocks.md#content-format).
73
+ - `deployment.blocks` prose: short onboarding steps — necessary prep, main actions, how to start and stop. Include a step only if the feature exists. Target structure: an intro of at most two short paragraphs, then one step per distinct user action (typically 3–5 steps). No full menu enumeration, no exhaustive troubleshooting, no spec tables, no restating the excerpt inside steps. Inline formatting in `content` is HTML, not Markdown. Images and video are uploaded first, then linked; see [../references/tool-blocks.md#content-format](../references/tool-blocks.md#content-format).
65
74
  - Review once before every push: would a first-time user find every sentence clear, with nothing repeated?
66
75
 
67
76
  ## Workflow B — create (one-go)
68
77
 
69
- 1. **Preflight**: Run `sensecraft-cli auth info`. Need an active SenseCAP Access Key. If missing, ask the user to run `sensecraft-cli auth init --kind sensecap` locally. Never run `auth init` for them.
78
+ 1. **Preflight**: Run `sensecraft-cli auth info`. Need an active SenseCAP Access Key. If missing, ask the user to run `sensecraft-cli auth init` locally. Never run `auth init` for them.
70
79
  2. **Upload assets**, writing each returned `file_url` back into the manifest entry:
71
80
 
72
81
  - Images: `sensecraft-cli file upload --path <img> --type 1 --for-app` (unlinked, 5 MB cap). Keep manifest order; index 0 = cover.
73
- - Firmware/binaries for blocks: check binaries for embedded credentials before uploading — build outputs can compile tokens in; if anything shows up, flag it and let the user decide. Whatever the upload decision, a block the flow needs stays in the doc: fill its config per [reference-tool-blocks.md](../reference-tool-blocks.md) and mark unfilled values as pending (e.g. firmware built locally by the end user). Upload itself: `sensecraft-cli file upload --path <fw> --type 4` → put the URL into the block's `config.firmware_url` (+ `firmware_size`).
74
- 3. **Build the payload** from the manifest per the projection in [reference-manifest.md](reference-manifest.md#manifest--cli-payload). Omit keys that have no values — the CLI rejects an empty `images: []` but accepts the key absent. Write the projection to `.sensecraft/sensecraft-app.payload.json` (transient — delete after the push).
82
+ - Firmware/binaries for blocks: check binaries for embedded credentials before uploading — build outputs can compile tokens in; if anything shows up, flag it and let the user decide. Whatever the upload decision, a block the flow needs stays in the doc: fill its config per [../references/tool-blocks.md](../references/tool-blocks.md) and mark unfilled values as pending (e.g. firmware built locally by the end user). Upload itself: `sensecraft-cli file upload --path <fw> --type 4` → put the URL on the `flash-firmware` block as flat `firmware_url`, with `firmware_name` and string `firmware_size`. Do not nest those fields under `config`. The editor wraps them into `config` when the doc is opened.
83
+ 3. **Build the payload** from the manifest per the projection in [references/manifest.md](references/manifest.md#manifest--cli-payload). Omit keys that have no values — the CLI rejects an empty `images: []` but accepts the key absent. Write the projection to `.sensecraft/sensecraft-app.payload.json` (transient — delete after the push).
75
84
  4. **Create** — deliberately not L2, no `--yes`:
76
85
  ```bash
77
86
  sensecraft-cli app create --from-json .sensecraft/sensecraft-app.payload.json
@@ -84,11 +93,11 @@ Published text is what plaza users actually read — mine it from the project, b
84
93
 
85
94
  ## Workflow C — update (local-first)
86
95
 
87
- The manifest leads, the remote follows. Every remote write below is L2: **one confirmation per batch, on a separate chat turn** ([`../../confirmation.md`](../../confirmation.md)) — the user's first request is intent, not confirmation.
96
+ The manifest leads, the remote follows. Every remote write below is L2: **one confirmation per batch, on a separate chat turn** ([../references/confirmation.md](../references/confirmation.md)) — the user's first request is intent, not confirmation.
88
97
 
89
98
  1. **Edit the manifest first** (user or agent), bump `sync.local_revision`, validate as in Workflow A step 4.
90
99
  2. **Preflight + env guard**: `auth info` — `remote_type`/`org_id` must match `identity`. Mismatch → stop; the user either switches auth or explicitly adopts the new env into the manifest.
91
- 3. **Drift check**: `sensecraft-cli app view --id <app_id> --sketch`, project the remote into the same sections the manifest covers, compare with `sync.last_pushed_hash` (algorithm pinned in [reference-manifest.md](reference-manifest.md#sync--local-vs-remote-bookkeeping)). Same → push. Different → the app was changed outside this manifest: show the field-level diff and use your judgment — merge what doesn't conflict, bring real conflicts to the user as a concrete proposal. Never silently overwrite someone else's edits.
100
+ 3. **Drift check**: `sensecraft-cli app view --id <app_id> --sketch`, project the remote into the same sections the manifest covers, compare with `sync.last_pushed_hash` (algorithm pinned in [references/manifest.md](references/manifest.md#sync--local-vs-remote-bookkeeping)). Same → push. Different → the app was changed outside this manifest: show the field-level diff and use your judgment — merge what doesn't conflict, bring real conflicts to the user as a concrete proposal. Never silently overwrite someone else's edits.
92
101
  4. **Confirm once for the whole batch**: state environment, app name + id, and every pending change (fields, images, BOM rows, blocks). Wait for the user's `确认` / `yes` reply.
93
102
  5. **Push only what changed**:
94
103
  | Changed section | Command |
@@ -96,13 +105,13 @@ The manifest leads, the remote follows. Every remote write below is L2: **one co
96
105
  | info fields and/or image set | `sensecraft-cli app update --id <app_id> --from-json .sensecraft/sensecraft-app.patch.json --yes` (sparse OK — CLI merges missing info keys from the sketch) |
97
106
  | BOM | `sensecraft-cli app bom set --id <app_id> --from-json .sensecraft/sensecraft-app.materials.json --yes` |
98
107
  | deployment blocks | include `deployment` in the `app update` patch |
99
- - **Images**: upload new/changed files with `--type 1 --for-app` (compare `sha256` in the manifest), then send the **full** `images[]` URL array in the update patch. Never use `--app-id` attach here — it prepends one image and scrambles the manifest order (see [../commands.md](../commands.md)).
108
+ - **Images**: upload new/changed files with `--type 1 --for-app` (compare `sha256` in the manifest), then send the **full** `images[]` URL array in the update patch. Never use `--app-id` attach here — it prepends one image and scrambles the manifest order (see [../references/app-commands.md](../references/app-commands.md)).
100
109
  6. **Verify** per the parent rule: success may return `{}`, so re-read with `app view --id <app_id> --sketch` (and `app bom list --id <app_id>` when BOM changed).
101
110
  7. **Record**: `last_pushed_revision = local_revision`, new hash + time; archive snapshot; suggest `git add` when in git.
102
111
  8. **Published app**: the update saves a **draft** — the plaza copy is unchanged until publish (parent skill). Under review (`be_public=2`) the CLI refuses — stop and say so.
103
112
 
104
113
  ## Field and block rules
105
114
 
106
- - App info + BOM: [../reference-app-fields.md](../reference-app-fields.md)
107
- - Deployment layout + tool-block configs: [../reference-tool-blocks.md](../reference-tool-blocks.md)
108
- - CLI flags for every command above: [../commands.md](../commands.md)
115
+ - App info + BOM: [../references/app-fields.md](../references/app-fields.md)
116
+ - Deployment layout + tool-block configs: [../references/tool-blocks.md](../references/tool-blocks.md)
117
+ - CLI flags for every command above: [../references/app-commands.md](../references/app-commands.md)
@@ -29,7 +29,7 @@
29
29
  {
30
30
  "id": "intro_1",
31
31
  "type": "paragraph",
32
- "content": "<p>What this app does, who it is for, and what is in the box.</p>",
32
+ "content": "What this app does, who it is for, and what is in the box.",
33
33
  "indent": 0
34
34
  }
35
35
  ]
@@ -13,7 +13,7 @@ Integer, currently `1`. Bump only when the schema changes shape.
13
13
  | Key | Filled when | Notes |
14
14
  |-----|-------------|-------|
15
15
  | `app_id` | after create | `null` until created. Once set, NEVER re-run create for this manifest |
16
- | `remote_type` | preflight | `Global` / `China` / `Private` from `auth info`. Update flow hard-stops on mismatch |
16
+ | `remote_type` | preflight | `Global` / `China` / `Private` from `auth info`. Update flow hard-stops on mismatch. CodeCraft Hub requires Global; China supports SenseCraft Data only |
17
17
  | `org_id` | preflight | from `auth info` |
18
18
  | `account` | preflight | from `auth info` |
19
19
  | `created_at` | after create | **Local UTC timestamp recorded when create succeeds** — the CLI returns no created time |
@@ -30,7 +30,7 @@ Integer, currently `1`. Bump only when the schema changes shape.
30
30
  | `allow_clone` | `0` or `1` only |
31
31
  | `allow_commerce` | `0` or `1` only |
32
32
 
33
- Full field compliance: [../reference-app-fields.md](../reference-app-fields.md).
33
+ Full field compliance: [../../references/app-fields.md](../../references/app-fields.md).
34
34
 
35
35
  ## `images` — local paths with upload state
36
36
 
@@ -47,11 +47,11 @@ Formats JPG/JPEG/PNG/GIF/WebP, ≤ 5 MB each, prefer 4:3. SVG is rejected by the
47
47
 
48
48
  ## `deployment.blocks`
49
49
 
50
- Flat ordered array, copied through to the payload unchanged. Blocks before the first `step` = introduction; each `step` starts a deploy step. Tool-block configs (`flash-firmware`, `deploy-ai-model`, …): [../reference-tool-blocks.md](../reference-tool-blocks.md). Firmware URLs land in `config.firmware_url` after a `file upload --type 4`.
50
+ Flat ordered array, copied through to the payload unchanged. Blocks before the first `step` = introduction; each `step` starts a deploy step. Tool-block configs (`flash-firmware`, `deploy-ai-model`, …): [../../references/tool-blocks.md](../../references/tool-blocks.md). After `file upload --type 4`, put the URL on the `flash-firmware` block as flat `firmware_url` (plus `firmware_name` and string `firmware_size`). Do not nest those fields under `config`. The editor wraps them into `config` when the doc is opened.
51
51
 
52
52
  ## `bom.materials`
53
53
 
54
- Seeed catalog rows carry `id` (SKU), `quantity`, `name`, `note`, `buy_url` — never `price`/`pic_url` (resolved by SKU server-side). Custom rows carry `name` + `quantity` (required) and optionally `note` / `buy_url` — no `id`, no image, no price. Details: [../reference-app-fields.md](../reference-app-fields.md#bom-materials).
54
+ Seeed catalog rows carry `id` (SKU), `quantity`, `name`, `note`, `buy_url` — never `price`/`pic_url` (resolved by SKU server-side). Custom rows carry `name` + `quantity` (required) and optionally `note` / `buy_url` — no `id`, no image, no price. Details: [../../references/app-fields.md](../../references/app-fields.md#bom-materials).
55
55
 
56
56
  ## `sync` — local vs remote bookkeeping
57
57
 
@@ -90,7 +90,7 @@ Never include `be_public` / `privacy` in any payload.
90
90
 
91
91
  ## Worked example
92
92
 
93
- See [assets/manifest-template.json](assets/manifest-template.json) for a fresh manifest (pre-create), and below for the same manifest after a successful create:
93
+ See [../assets/manifest-template.json](../assets/manifest-template.json) for a fresh manifest (pre-create), and below for the same manifest after a successful create:
94
94
 
95
95
  ```json
96
96
  {
@@ -121,24 +121,27 @@ See [assets/manifest-template.json](assets/manifest-template.json) for a fresh m
121
121
  ],
122
122
  "deployment": {
123
123
  "blocks": [
124
- { "id": "intro_1", "type": "paragraph", "content": "<p>What this app does.</p>", "indent": 0 },
125
- { "id": "step_1", "type": "step", "title": "Step 1: Flash firmware", "content": "Step 1: Flash firmware", "expanded": true, "indent": 0 },
124
+ { "id": "intro_1", "type": "paragraph", "content": "What this app does.", "indent": 0 },
125
+ { "id": "step_1", "type": "step", "title": "Flash firmware", "content": "Flash firmware", "expanded": true, "indent": 0 },
126
126
  {
127
127
  "id": "ff_1",
128
128
  "type": "flash-firmware",
129
- "config": {
130
- "device_id": "",
131
- "device_type": "",
132
- "firmware_url": "https://files.seeedstudio.com/…/firmware.bin",
133
- "firmware_size": "412316"
134
- }
129
+ "device_id": "113991115",
130
+ "device_type": "32",
131
+ "flash_mode": "bin",
132
+ "firmware_url": "https://files.seeedstudio.com/…/firmware.bin",
133
+ "firmware_name": "firmware.bin",
134
+ "firmware_size": "412316",
135
+ "flash_address": "0x0",
136
+ "muse_gadget": false,
137
+ "full_flash": false
135
138
  }
136
139
  ]
137
140
  },
138
141
  "bom": {
139
142
  "materials": [
140
143
  {
141
- "id": "113991254",
144
+ "id": "113991115",
142
145
  "quantity": "1",
143
146
  "name": "Seeed Studio XIAO ESP32S3 Sense",
144
147
  "note": "Main MCU",
@@ -1,6 +1,6 @@
1
1
  # sensecraft-apps — CLI commands
2
2
 
3
- Target binary: `sensecraft-cli` (this repo). Auth: active **SenseCAP Access Key** (`auth init --kind sensecap`) → `{ai-host}/openapi`.
3
+ Target binary: `sensecraft-cli` (this repo). Auth: active **SenseCAP Access Key** (`auth init`) → `{ai-host}/openapi`.
4
4
 
5
5
  > Status: **shipped**. Every command below is implemented — run it rather than describing it. If a flag is rejected, check `--help` instead of assuming the feature is missing.
6
6
 
@@ -8,7 +8,7 @@ Target binary: `sensecraft-cli` (this repo). Auth: active **SenseCAP Access Key*
8
8
 
9
9
  ```bash
10
10
  sensecraft-cli auth info
11
- sensecraft-cli auth init --kind sensecap # user only, interactive
11
+ sensecraft-cli auth init # user only, interactive
12
12
  ```
13
13
 
14
14
  ## Commands
@@ -21,14 +21,13 @@ List apps.
21
21
 
22
22
  | Flag | Default | Notes |
23
23
  | --------------------- | ----------------------- | ------------------------------------------------------------ |
24
- | `--public` | | Plaza (`be_public=1`). Required for the store; not the default |
24
+ | `--public` | | CodeCraft Hub (`be_public=1`). Required for the store; not the default |
25
25
  | `--mine` | default if neither flag | My apps. Omit both visibility flags for the same result |
26
26
  | `--name` | | Search keyword → API `app_name` (Console app list) |
27
27
  | `--scene` | | Scene id |
28
28
  | `--uniform-type` | | Device type → API `uniform_type` (`40` reCamera, `32` XIAO ESP32S3, `53` reCamera Pro) |
29
29
  | `--sort` | | `popular` → `order_type=1`, `newest` → `2`, `likes` → `3`. Omit to leave `order_type` unset |
30
30
  | `--priority-activity-id` | | Positive integer. Only with `--sort popular`. If omitted on popular, CLI fills the first ongoing activity |
31
- | `--tag-id` | | Competition filter → `tag_id` |
32
31
  | `--mark-type` | | `1` = my likes, `0` = my collections |
33
32
  | `--likes` | | `mark_type=1` and `be_public=1`. Not with `--mine` |
34
33
  | `--collections` | | `mark_type=0` and `be_public=1`. Not with `--mine` |
@@ -36,10 +35,9 @@ List apps.
36
35
  | `--sandbox` | | Sample JSON, no network. Includes `sandbox_query` |
37
36
 
38
37
  ```bash
39
- # Application Plaza. Omit visibility flags for my apps. Hot sort is explicit.
38
+ # CodeCraft Hub. Omit visibility flags for my apps. Hot sort is explicit.
40
39
  sensecraft-cli app list --public --name "vision" --scene <scene_id> --page 1 --length 20
41
40
  sensecraft-cli app list --public --sort popular --length 12
42
- sensecraft-cli app list --public --sort popular --tag-id 1
43
41
  sensecraft-cli app list --public --sort newest
44
42
  sensecraft-cli app list --public --likes
45
43
  sensecraft-cli app list --public --collections
@@ -82,6 +80,19 @@ sensecraft-cli app fields
82
80
  sensecraft-cli app blocks
83
81
  ```
84
82
 
83
+ ### `app doc compile`
84
+
85
+ **Status: implemented.** Compiles a Markdown file into editor `deployment.blocks`. No Access Key, no network, no `--sandbox`. Does not upload files and does not insert tool-blocks.
86
+
87
+ ```bash
88
+ sensecraft-cli app doc compile --from-md ./README.md
89
+ # stdin: sensecraft-cli app doc compile --from-md -
90
+ ```
91
+
92
+ Use stdout `deployment` in `app create` / `app update`, or skip this step and pass the file as `app create --from-md` / `app update --from-md`. `suggested_app_name` is the opening `# title`. `suggested_excerpt` is the paragraph under it. `pending_uploads` lists local image/video/file paths that were left out of `content`; upload those, then put the https URL in `src` or `href`.
93
+
94
+ `--from-json` rejects text blocks whose `content` is still Markdown (`**bold**`, `` `code` ``, a leading `#` or list marker). `code` block source is exempt. The same write fills a paragraph that is only a video URL, a remote file link, and a remote image up to the editor's HTML. A video URL inside a sentence is left as text.
95
+
85
96
  ### `app create` / `app update`
86
97
 
87
98
  **Status: implemented.**
@@ -92,18 +103,19 @@ sensecraft-cli app blocks
92
103
 
93
104
  | Flag | Notes |
94
105
  | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
95
- | `--name` | `app_name` only create (empty shell) |
96
- | `--from-json` | JSON path or `-`; must include `app_name` if `--name` omitted. Extra fields → follow-up `update_app` **only on the newly created `app_id`** (cannot target an existing app) |
106
+ | `--name` | `app_name` only create (empty shell). Optional when JSON or the Markdown title provides one |
107
+ | `--from-md` | Markdown path or `-`. Compiled into editor blocks. Fills `app_name` / `excerpt` when omitted. Appends JSON `deployment.blocks` after the document. stdout adds `pending_uploads` and `warnings` |
108
+ | `--from-json` | JSON path or `-`; must include `app_name` if `--name` and `--from-md` omit it. Extra fields → follow-up `update_app` **only on the newly created `app_id`** (cannot target an existing app). Text blocks get editor video, link, and image HTML |
97
109
  | `--sandbox` | sample JSON |
98
110
 
99
111
  Rejects `be_public=1` / `privacy=1`. Do **not** confuse with `app update` (existing app → L2).
100
112
 
101
- **Success output:** CLI always prints `app_id`, `console_url`, and `detail_url` on the app site (`https://app.seeed.cc`, or `https://test-app.seeed.cc` when the AI host contains `test-`):
113
+ **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`):
102
114
 
103
115
  - edit: `/application/edit?id=<app_id>`
104
- - my app detail: `/view-application/<app_id>-<slug>?tab=custom&from=my-apps`
116
+ - my app detail: `/view-application/<app_id>-<slug>?from=user-center&tab=custom`
105
117
 
106
- `from=my-apps` loads the sketch (cover/`images`). A public link uses `tab=public&from=application-store` and must not include `from=my-apps`. 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`.
118
+ `from=user-center` loads the sketch (cover/`images`) and the page back button returns to the creator center. A public link uses `tab=public&from=application-store` and must not include `from=user-center` or `from=my-apps`. 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`.
107
119
 
108
120
  **Do not retry create blindly:**
109
121
 
@@ -112,6 +124,9 @@ Rejects `be_public=1` / `privacy=1`. Do **not** confuse with `app update` (exist
112
124
  - Prefer updating the existing `app_id` with `app update --yes` over creating a duplicate.
113
125
 
114
126
  ```bash
127
+ # Markdown document. Scene, cover, BOM, and tool-blocks stay in the JSON.
128
+ sensecraft-cli app create --from-md ./README.md --from-json ./app.json
129
+
115
130
  # One-shot full create: deliberately not L2
116
131
  sensecraft-cli app create --from-json ./app.json
117
132
  # Expect app_id + console_url + detail_url; if missing, list before retrying:
@@ -126,8 +141,10 @@ sensecraft-cli app create --name "My App"
126
141
  | Flag | Notes |
127
142
  | --------------- | ---------------------------------------------------------------------------------------------------------- |
128
143
  | `--id` | required |
129
- | `--from-json` | path or `-`; required unless `--activity-id` is set |
144
+ | `--from-json` | path or `-`; optional when `--from-md` or `--activity-id` is set |
145
+ | `--from-md` | Markdown path or `-`. Same compile as create. Does not replace an `app_name` / `excerpt` already in the JSON |
130
146
  | `--activity-id` | optional positive integer. Joins that activity. Omit or pass empty to leave existing activity tags as-is |
147
+ | `--cancel-activity-id` | optional positive integer. Leaves that activity. Does not change `allow_clone` |
131
148
  | `--yes` | after user confirmation |
132
149
  | `--sandbox` | sample JSON |
133
150
 
@@ -147,9 +164,14 @@ sensecraft-cli app update --id <app_id> --from-json ./app.json --yes
147
164
 
148
165
  # Join activity 1. activity_id is sent as a JSON number. tags in JSON is dropped.
149
166
  sensecraft-cli app update --id <app_id> --activity-id 1 --yes
167
+
168
+ # Leave activity 1. cancel_activity_id is sent as a JSON number.
169
+ sensecraft-cli app update --id <app_id> --cancel-activity-id 1 --yes
150
170
  ```
151
171
 
152
- `activity_id` must be a positive integer. List ongoing ids with `app activity list` first. If that list succeeds and does not contain the id, CLI does not POST. 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.
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.
173
+
174
+ `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`.
153
175
 
154
176
  When `--activity-id` is set and this JSON does not include `allow_clone`, CLI sets `allow_clone` to `1` unless the sketch is already `1`. That matches the web contest save. An explicit `allow_clone` in the JSON is kept.
155
177
 
@@ -157,7 +179,7 @@ When `--activity-id` is set and this JSON does not include `allow_clone`, CLI se
157
179
 
158
180
  **Status: implemented.**
159
181
 
160
- - `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.
182
+ - `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 the creator-center page (`from=user-center`). Give the user that URL. Do not replace it with `/application/detail/<id>` (plaza page, no private draft).
161
183
  - **Publish Declaration (required for `publish` only):** matches Console 「发布确认」`warrantyAccepted`. Before passing `--agree-declaration`, show the user:
162
184
  - Review will lock editing until approval (or `unpublish`)
163
185
  - Declaration URL: https://sensecraft.seeed.cc/legal/en/declaration
@@ -166,7 +188,7 @@ When `--activity-id` is set and this JSON does not include `allow_clone`, CLI se
166
188
  - `withdraw` → `POST /flow/app/v3/callback_sketch` with `{app_id}` only, and only when `be_public=2`. Public apps: `unpublish`. Private apps: nothing to withdraw.
167
189
  - `delete` → `POST /flow/app/v2/delete_app` — **private + owner** (`be_public=0`)
168
190
  - **Never** send privacy `1`
169
- - All require a **separate chat confirm** ([`../confirmation.md`](../confirmation.md)) then `--yes`; `publish` also requires `--agree-declaration`. 「删除应用 demo」is intent — ask first.
191
+ - All require a **separate chat confirm** ([confirmation.md](confirmation.md)) then `--yes`; `publish` also requires `--agree-declaration`. 「删除应用 demo」is intent — ask first.
170
192
 
171
193
  ```bash
172
194
  # after the user replies 确认:
@@ -178,7 +200,7 @@ sensecraft-cli app delete --id <app_id> --yes
178
200
 
179
201
  ### `app activity list`
180
202
 
181
- **Status: implemented.** Read-only. `GET /activity/list` with no `time` query. stdout is `{ "list": [...] }` with numeric `activity_id`, `name`, `tag_ids`, and unix `start_time` / `end_time` when present. Rows without a positive id or a name are dropped.
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.
182
204
 
183
205
  ```bash
184
206
  sensecraft-cli app activity list
@@ -18,7 +18,8 @@ Agent fill-in guide for SenseCraft custom apps (v3). Aligns with Console `infoFo
18
18
  | `introduction` | legacy long text | no | if non-empty, editor may merge into intro blocks — prefer `deployment.blocks` for new content |
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
- | `flow_data` / `model_data` | Node-RED sync | only with `node-red` block | `flow_data` must be **JSON string** at top level |
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` and `config.model_data` are objects, not strings. On save the app writes `JSON.stringify(config.flow_data)` to this top-level `flow_data` string and copies `model_data` here. |
22
23
 
23
24
  ### Create vs update
24
25
 
@@ -29,7 +30,7 @@ Agent fill-in guide for SenseCraft custom apps (v3). Aligns with Console `infoFo
29
30
  - **Update (`app update`)**: always include `app_id` (CLI `--id`).
30
31
  - **Info fields** (`app_name`, `excerpt`, `scene`, `allow_clone`, `allow_commerce`, `images`, `license`, `author`): aiserver often **ignores** a body that only contains `app_name`. CLI **auto-merges** missing info keys from `app view --sketch` before calling `update_app` (does **not** merge `be_public` from user/existing for private apps). If current `be_public=1`, CLI **injects** `be_public=1` like Console info save (plaza unchanged until `app publish`). `be_public=2` refuses update. Agents may pass a sparse rename patch; still **re-read** with `app view` / `app list` after update because success may be `{}`.
31
32
  - **Other sections** (`deployment`, `materials`, …): may be sent alone without forcing an info merge. Full leave-save usually sends info + deployment + materials together.
32
- - **Activity**: `--activity-id <positive integer>` or JSON `activity_id`. Do not send `tags`; the server ignores it and the CLI strips it. A blank `activity_id` is omitted. If `activity_id` is set and this JSON omits `allow_clone`, CLI sets `allow_clone` to `1` when the current sketch is not already `1`.
33
+ - **Activity**: `--activity-id <positive integer>` or JSON `activity_id`. Do not send `tags`; the server ignores it and the CLI strips it. A blank `activity_id` is omitted. If `activity_id` is set and this JSON omits `allow_clone`, CLI sets `allow_clone` to `1` when the current sketch is not already `1`. `--cancel-activity-id <positive integer>` or JSON `cancel_activity_id` leaves that activity and does not change `allow_clone`. Do not send the same id in both fields.
33
34
  - **Rename workflow**: confirm with user (L2) → `app update --id … --from-json '{"app_name":"…"}' --yes` (CLI fills the rest) → verify name via `app view --id … --sketch` or `app list --mine --name …`.
34
35
 
35
36
  ## Visibility / review
@@ -81,7 +82,7 @@ Custom rows are exactly `name` / `quantity` / `note` / `buy_url` (Console `build
81
82
  {
82
83
  "materials": [
83
84
  {
84
- "id": "113991254",
85
+ "id": "113991115",
85
86
  "quantity": "1",
86
87
  "name": "Seeed Studio XIAO ESP32S3 Sense",
87
88
  "note": "Main MCU",