@seeed-studio/sensecraft-cli 0.4.0 → 0.4.2

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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@seeed-studio/sensecraft-cli",
3
- "version": "0.4.0",
3
+ "version": "0.4.2",
4
4
  "description": "SenseCAP / SenseCraft AI cloud CLI (devices, apps, models, files, cloud deploy)",
5
5
  "license": "MIT",
6
6
  "repository": {
package/skills/README.md CHANGED
@@ -6,12 +6,16 @@ One skill directory. The folder name matches `name` in `SKILL.md`.
6
6
  sensecraft-cli/
7
7
  ├── SKILL.md # only entry
8
8
  ├── references/ # product procedures, opened when needed
9
- ├── create-app/ # nested skill: local project → app
9
+ ├── create-app/ # project discovery → reviewed, deployable CodeCraft Hub app
10
10
  │ ├── SKILL.md
11
11
  │ ├── references/
12
12
  │ └── assets/
13
13
  ```
14
14
 
15
+ `create-app/SKILL.md` routes to its project-discovery, content-review, and manifest references, plus the shared app-fields, tool-block, command, and upload references. Read each applicable reference before authoring that information. The workflow resolves user decisions, verifies BOM catalog matches through the API, builds a local manifest, reviews it, then uploads and verifies a private app. Update sync uses the same manifest.
16
+
17
+ Any `*-legacy/` directory is an archived draft, not an entry point or current reference. The npm packaging script excludes those directories.
18
+
15
19
  `SKILL.md` links straight to a file in `references/` or to `create-app/`. Do not add another folder between them.
16
20
 
17
21
  Install by symlinking this directory into the agent skills folder. Do not copy it. Steps: [`../INSTALL.md`](../INSTALL.md) §9.
@@ -27,18 +27,21 @@ SenseCraft Data: [`references/data.md`](references/data.md).
27
27
  1. **Use the Access Key before any cloud call**
28
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
29
  - Never send the Access Key as a fake Bearer/JWT
30
- 2. **Always run auth check first** (ask user to fix if missing):
30
+ 2. **Always run auth check first**:
31
31
  ```bash
32
32
  sensecraft-cli auth info
33
33
  ```
34
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:
35
+ 3. **Do not run bare `auth init`** — that wizard needs a TTY. In this shell, use the split flow. Each command exits and prints JSON. Show `verification_url` and end the turn before polling:
36
36
  ```bash
37
- sensecraft-cli auth init # Access Key (app/model/file/cloud/recamera)
37
+ sensecraft-cli auth init --site Global --no-wait
38
+ sensecraft-cli auth init --device-code <device_code>
39
+ sensecraft-cli auth init --device-code <device_code> --key-id <access_id>
38
40
  ```
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.
41
+ Create a key with `--label <name> --access-level read-write` (or `only-read`) instead of `--key-id`. Use Global for SenseCraft AI and CodeCraft Hub. China is SenseCraft Data only. Do not print `access_token` or `access_key`. If the user already has a key, they can run `auth add` locally.
42
+ 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 update·publish·unpublish·delete, model create·update·publish·unpublish·delete, upload attach, cloud deploy, device bind/unbind, group create/rename/delete/move. **Exception: `app create`, including one-shot `--from-json`, is not L2 and takes no `--yes`; resolve uncertain content decisions and review the result first.**
40
43
  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.
44
+ 6. **Success = indented JSON on stdout** for business commands and the split `auth init` flow. The interactive wizard prints human-readable text. Failure = stderr + non-zero exit. Parse stdout only on success.
42
45
  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
46
  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
47
 
@@ -46,7 +49,7 @@ SenseCraft Data: [`references/data.md`](references/data.md).
46
49
 
47
50
  `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
51
 
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.
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.
50
53
 
51
54
  `auth info` shows the active Access Key (site, org, key id). Secrets are not printed.
52
55
 
@@ -57,8 +60,8 @@ SenseCraft Data: [`references/data.md`](references/data.md).
57
60
  | SenseCraft Data: list/bind device, groups, telemetry | [`sensecraft-data`](references/data.md) | Shipped today |
58
61
  | Browse / search CodeCraft Hub, view app | [`sensecraft-apps`](references/apps.md) + `app list` / `app view` | **CLI shipped** (list/view) |
59
62
  | 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) |
63
+ | Turn a local project into an app (discovery + reviewed copy + tool blocks + API-confirmed BOM + manifest + upload), or update its manifest-managed app | [`create-app`](create-app/SKILL.md) | Read required references before authoring; create needs no `--yes`; existing-app updates use one batch confirmation; stops before publish |
64
+ | Create / update / publish / unpublish / delete / bom app | same + `app …` / `app bom …` | **CLI shipped** (L2 `--yes`; publish also `--agree-declaration`; `create`, including `--from-json`, is not L2) |
62
65
  | 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
66
  | Model library search/view/download/constants | [`sensecraft-models`](references/models.md) | **CLI shipped** |
64
67
  | Upload / publish / unpublish / delete model | same + `model upload --id --yes` / `create\|update\|publish\|unpublish\|delete` | Attach bumps patch version like Console |
@@ -92,9 +95,9 @@ SenseCraft Data telemetry → pick a public model → deploy to Jetson:
92
95
 
93
96
  | Level | Meaning | Examples |
94
97
  |-------|---------|----------|
95
- | L1 Scriptable | Agent may run directly | list / view / auth info |
98
+ | L1 Scriptable | Agent may run directly | list / view / auth info / `auth init --no-wait` then later `--device-code` |
96
99
  | L2 Confirm | Ask user first | publish (+ declaration), unpublish, delete, deploy |
97
- | L3 Interactive | Human-in-the-loop | `auth init`, Web Serial flash, payment |
100
+ | L3 Interactive | Human-in-the-loop | bare `auth init`, Web Serial flash, payment |
98
101
  | L4 Ops-only | Do not expose to end-user Agent | Admin `judge_app` |
99
102
 
100
103
  ## Shipped commands
@@ -1,117 +1,124 @@
1
1
  ---
2
2
  name: create-app
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.
3
+ description: Turn a local project into a deployable CodeCraft Hub app, or update an app managed by codecraft-app.json. Discover project facts, resolve user decisions, author and review app copy, configure deployment tool blocks, verify BOM products through the API, then validate and upload the local manifest. Use for requests to upload a project or repo as a CodeCraft Hub or SenseCraft app. App publishing, unpublishing, deleting, and cloning use the parent skill.
4
4
  ---
5
5
 
6
- # create-app
6
+ # Create a CodeCraft Hub app
7
7
 
8
- Turn a finished local project into a CodeCraft Hub app through a local manifest: gather → write manifest → one-go create → local-first updates.
8
+ Deliver a reviewed `codecraft-app.json` and a private CodeCraft Hub app whose deployment instructions work through the available tool blocks. Follow discovery → synthesis → decisions → manifest → review → upload → verification. A saved draft with missing deployment inputs is an incomplete result; report those inputs explicitly.
9
9
 
10
- Entry skill: [`../SKILL.md`](../SKILL.md). App lifecycle (publish / unpublish / delete / clone): [`../references/apps.md`](../references/apps.md).
10
+ The manifest is the source of truth for app values. Project evidence and review notes explain those values; they are not a second payload. An existing `identity.app_id` always means update/resume, never another create.
11
11
 
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.
12
+ ## Read references before authoring
13
13
 
14
- ## Why the manifest exists
14
+ Read each applicable reference **in full before drafting or changing the corresponding information**, including on an update. A link, search snippet, template, static schema, or remembered config does not replace the read. Reuse a reference already read in this session unless it changed. If a required reference is unavailable, continue independent discovery and report the gap; do not guess the affected fields.
15
15
 
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.
16
+ | Before this work | Required reading / inspection |
17
+ |---|---|
18
+ | Any CLI work | [Parent skill](../SKILL.md), [app commands](../references/app-commands.md); `auth info` before cloud calls |
19
+ | Project discovery | [Project discovery](references/project-discovery.md), then the relevant project files themselves |
20
+ | App fields, scene, images, permissions, BOM rows | [App fields and BOM](../references/app-fields.md); `app fields`; `model constants` for actual scene options |
21
+ | Activity participation | [Activity selection](../references/app-fields.md#activity-selection-during-app-authoring), [activity command](../references/app-commands.md#app-activity-list) |
22
+ | Any human-facing copy | [Writing and review](references/content-review.md), plus project evidence for the claims |
23
+ | Deployment plan or tool-block config | [Tool blocks](../references/tool-blocks.md), including device-specific rules; `app blocks` |
24
+ | Model-backed tool needing model selection/metadata | [Models](../references/models.md), [model commands](../references/model-commands.md), [model fields](../references/model-fields.md); verify the selected model through the supported API reads |
25
+ | Manifest creation, projection, sync bookkeeping | [Manifest contract](references/manifest.md), [template](assets/manifest-template.json) |
26
+ | Asset upload | [File upload](../references/files.md), [file command flags](../references/file-commands.md) |
27
+ | Update of an existing remote app | [Confirmation protocol](../references/confirmation.md); review the concrete batch before requesting any outstanding approval |
17
28
 
18
- Manifest schema, field-by-field: [references/manifest.md](references/manifest.md). Starting template: [assets/manifest-template.json](assets/manifest-template.json).
29
+ `app fields` and `app blocks` are static, zero-network commands: run them bare, without `--sandbox`. They describe structure, not live catalog matches. `model constants` and `app bom search` are cloud reads; sandbox samples are not API confirmation.
19
30
 
20
- ## Manifest files on disk
31
+ ## 1. Discover the project and current app state
21
32
 
22
- - **Canonical**: `sensecraft-app.json` in the project root. Several apps in one repo: `sensecraft-app.<slug>.json` per app (`<slug>` = lowercase-hyphen app short name).
23
- - **Versioning**: run `git rev-parse --is-inside-work-tree` **once at gather time** and reuse the decision for the whole session.
24
- - Inside git → canonical file only; suggest the user `git add` it after every successful push.
25
- - No git → after every successful create/push and at the end of gather, also write `.sensecraft/archive/sensecraft-app[.<slug>].YYYYMMDD-HHmmss.json`. The canonical file is always the latest; archives are immutable history.
26
- - **Discovery** (update flow): prefer `sensecraft-app.json`; else a single `sensecraft-app.*.json` — excluding the reserved transient names `*.payload.json` / `*.patch.json` / `*.materials.json`; else list candidates and ask which app. A candidate must have manifest shape (`manifest_version` + `identity` + `sync`) — reject lookalikes. No manifest → this is a create flow. A discovered manifest whose `identity.app_id` is null and which fails validation or cannot be trusted: tell the user what was wrong, archive it under `.sensecraft/archive/`, rebuild from the template, and run `app list --mine --name "<app_name>"` as a duplicate check before creating.
27
- - **Transient payload/patch files** (the projected `--from-json` bodies) live under `.sensecraft/` — create the dir if needed — and are deleted once the push completes. Never leave them as untracked clutter in the project root. Only delete transients this session created — pre-existing leftovers from an earlier session are reported to the user and removed only with their agreement.
28
- - Never store tokens, access keys, or device keys in the manifest. If a mined value looks secret-like, warn and keep it out.
33
+ Read [project-discovery.md](references/project-discovery.md). Mine this conversation first, then inspect the actual project: purpose and audience, implemented behavior, supported hardware, build/deployment configuration, artifacts, runtime setup, limitations, assets, and license. README claims are candidates; cross-check them with implementation and configuration before using them in app copy.
29
34
 
30
- ## Workflow A — gather
35
+ Keep concise evidence and open decisions in `.sensecraft/<manifest-stem>.review.md` (for example `.sensecraft/codecraft-app.review.md`). Record file locations or conversation decisions, not credentials. Use it to carry unresolved facts, the deployment plan, BOM lookup evidence, artifact paths/hashes, and the final review through a resumed session. Final app values live in the manifest.
31
36
 
32
- Mine first, ask approval once at the end.
37
+ - Run `git rev-parse --is-inside-work-tree` once and reuse the result for versioning.
38
+ - Prefer `codecraft-app.json`; otherwise use a single `codecraft-app.<slug>.json` with `manifest_version`, `identity`, and `sync`. Exclude `*.payload.json`, `*.patch.json`, and `*.materials.json`. Several candidates → ask which app. An explicit request for another app → use a separate slugged manifest, preserve the existing one.
39
+ - Also discover legacy `sensecraft-app.json` / `sensecraft-app.<slug>.json` with the same shape checks and transient exclusions. Migrate the chosen manifest to the corresponding `codecraft-app` filename, preserving its contents, especially `identity.app_id` and `sync`. Never overwrite an existing destination: resolve competing manifests first. Preserve old archive snapshots; carry forward any existing review/artifact notes and sync baseline. A filename change is not a new app.
40
+ - Preserve an invalid pre-create manifest in `.sensecraft/archive/` before rebuilding it from the template. Explain the fault and run `app list --mine --name "<app_name>"` before creating. If an app ID exists, preserve it and repair/resume that app.
41
+ - Run `sensecraft-cli auth info` before cloud reads. CodeCraft Hub requires Global and an active SenseCAP Access Key. If auth is missing, use the split `auth init` flow in [`../SKILL.md`](../SKILL.md): `--site Global --no-wait`, show `verification_url` and end the turn, then `--device-code` after the user authorizes. Do not run bare `auth init`. Do not invent account, scene, or catalog values before authentication succeeds.
33
42
 
34
- 1. **Mine this conversation, then the project directory** (read-only). You are usually inside the development session — what was built, configured, and decided here is the primary source; project files are the cross-check. Organize what is already known directly.
35
-
36
- - `README*` → `app_name` / `excerpt` candidates (excerpt ≤ 300 UTF-16 code units).
37
- - `package.json` / firmware README → name, `license`, `author`.
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 [../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
- - Hardware mentions (XIAO, Grove, reCamera…) → BOM candidates; resolve SKUs with `sensecraft-cli app bom search --name "<kw>"`.
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
- 3. **Write the manifest** from the template with `identity.app_id: null`, `sync.local_revision: 1`.
43
- 4. **Validate locally before any network write** — fail fast here, not after create. Run the shipped validator so every session applies the same checks:
44
-
45
- ```bash
46
- python3 <this-skill-dir>/assets/validate_manifest.py <manifest> --scene-ids <ids from model constants>
47
- ```
48
- It only validates **format, never content truth**. Cross-check structure with the static schema commands `sensecraft-cli app fields` and `sensecraft-cli app blocks` — they are zero-network, run them bare (they take **no** `--sandbox` flag).
49
- 5. Snapshot the manifest (archive copy when there is no git).
43
+ ## 2. Synthesize fields, deployment, and BOM
50
44
 
51
- ## When the source is a Markdown document
45
+ Read the applicable references in the table **before** doing each part. Build evidence-backed candidates first; serialize after material decisions are resolved.
52
46
 
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.
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.
54
48
 
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`).
49
+ **Activity participation.** Use the project understanding from discovery and follow [app-fields.md § Activity selection](../references/app-fields.md#activity-selection-during-app-authoring) to decide whether to join an activity. Record the resolved selection in `info.activity_id` and the rationale in the review.
56
50
 
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
- ```
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
+
53
+ Use available artifacts or a documented reproducible build when feasible within the user's scope. If an artifact, board variant, model, container version, or necessary action is unresolved, explain the specific gap and propose choices. Keep needed blocks in the local draft with pending values; never replace them with prose that pretends the deployment works. If no tool supports a required action, say so and agree on a supported path or an explicitly incomplete draft. Do not claim deployability until every required action has a usable path.
54
+
55
+ **BOM.** Follow [app-fields.md § Catalog verification](../references/app-fields.md#catalog-verification-before-authoring-a-bom). Identify devices and app-specific accessories from project evidence; exclude ordinary cables, computers, and generic tools by default. Query `app bom search --name "<product or SKU>"` for each catalog candidate, broadening the name if necessary. Match the exact variant. Copy returned `sku` to manifest row `id`, along with the returned name and purchase URL; derive quantity and a useful role note from the project. Do not use a catalog's internal `id` as the SKU.
56
+
57
+ Record the query and selected result in review notes. Multiple plausible variants → ask. A successful search with no matching product permits a clearly labeled custom row without `id`; API/auth failure means unverified, not no match. Never present custom rows or sandbox output as API-confirmed. No-hardware projects may have an empty BOM with that reason stated. After upload, checking saved rows is a separate verification from catalog matching.
58
+
59
+ ## 3. Resolve uncertain decisions
60
+
61
+ Present a concise project summary, proposed fields, activity selection or reason for none, deployment actions/tools, BOM matches, and actual gaps. Batch questions about consequential choices: name/language/audience when unclear, scene, clone/commercial permissions, uncertain activity eligibility/selection, hardware variant and BOM scope/quantity, assets, or an unsupported deployment path. Include a recommendation and why; reuse answers already in the conversation.
62
+
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.
61
64
 
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.
65
+ ## 4. Build the local manifest
63
66
 
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.
67
+ Read [manifest.md](references/manifest.md) and the template. Populate the canonical manifest with resolved fields, optional activity selection, ordered images, the authored intro and deployment blocks, and confirmed BOM rows. Fresh create: `identity.app_id: null`, `sync.local_revision: 1`; fill environment/account from auth. Do not send the manifest itself to the API.
65
68
 
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.
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
+ - 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` fields are **flat on the block**; other tools use `config`. SKU and `uniform_type` are distinct. Sizes are strings.
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
+ - 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.
67
74
 
68
- ## Writing the prose
75
+ ### Markdown sources
69
76
 
70
- Published text is what plaza users actually read — mine it from the project, but author it deliberately.
77
+ Read [tool-blocks.md § Content format](../references/tool-blocks.md#content-format) and [app-commands.md § app doc compile](../references/app-commands.md#app-doc-compile) before compiling. Author only the reader-facing content; do not upload a developer README wholesale. `app doc compile --from-md <file>` is local and does not upload or insert tools. Inspect its `deployment`, `warnings`, and `pending_uploads`, then merge the compiled text and tool blocks **at their intended positions in the manifest**. Step headings such as `## Step: Flash` become steps; a plain `h2` does not.
71
78
 
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.
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).
74
- - Review once before every push: would a first-time user find every sentence clear, with nothing repeated?
79
+ Push the final manifest projection with `--from-json`. Combining `--from-md` again would append JSON blocks after the compiled document and can duplicate/reorder the reviewed content. JSON text `content` uses HTML/plain text, never raw Markdown markers; `code` content is plain source. Local media paths must be uploaded and replaced with real URLs before submission.
75
80
 
76
- ## Workflow B — create (one-go)
81
+ ## 5. Review before upload
77
82
 
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.
79
- 2. **Upload assets**, writing each returned `file_url` back into the manifest entry:
80
-
81
- - Images: `sensecraft-cli file upload --path <img> --type 1 --for-app` (unlinked, 5 MB cap). Keep manifest order; index 0 = cover.
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).
84
- 4. **Create** — deliberately not L2, no `--yes`:
83
+ Read [content-review.md](references/content-review.md) before drafting copy and apply its full review to the assembled manifest before every push. Review the actual name, excerpt, introduction, step titles/instructions, and BOM notes as a first-time reader. Fix unsupported claims, ambiguity, repetition, missing prerequisites, and instructions that do not match the adjacent tool. Run this editorial pass separately from format validation.
84
+
85
+ ```bash
86
+ python3 <this-skill-dir>/assets/validate_manifest.py <manifest> --scene-ids <comma-separated-ids-from-model-constants>
87
+ ```
88
+
89
+ Fix format violations before any upload or app write. This validator does **not** prove factual accuracy, catalog identity, tool compatibility, or deployability. Review its warnings: planned uploads may remain pending until the next stage; missing deployment artifacts/configs remain blockers to a deployable result.
90
+
91
+ Update the review notes with corrections, evidence, remaining gaps, and readiness. Show the user the final name/excerpt, permission choices, activity name/ID and rationale or reason for no activity, ordered deployment actions and tools, BOM including custom/unverified status, selected assets, manifest path, and whether required deployment inputs are complete. Link the local manifest and review for full inspection. If all decisions are settled and creation is authorized, proceed without demanding another confirmation. An upload of a knowingly incomplete draft needs the user's choice of that outcome.
92
+
93
+ ## 6. Upload and create once
94
+
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 use flat `firmware_url`, `firmware_name`, and string `firmware_size`. Never expose temporary signed upload URLs in review prose.
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
+ 4. Write `.sensecraft/<manifest-stem>.payload.json`, then create **without `--yes`**:
85
99
  ```bash
86
- sensecraft-cli app create --from-json .sensecraft/sensecraft-app.payload.json
100
+ sensecraft-cli app create --from-json .sensecraft/codecraft-app.payload.json
87
101
  ```
88
- Expect `app_id` + `console_url` + `detail_url` on stdout. If the **`app_id` or URLs** are missing or empty, run `sensecraft-cli app list --mine --name "<app_name>"` BEFORE any retry — never blind re-create. Echoed fields differing from what you sent are not by themselves a failure signal.
89
- 5. **Record**: write `app_id`, `created_at` into `identity`; set `sync.last_pushed_*` (revision, RFC3339 time, payload hash); archive snapshot.
90
- 6. **Report**: app name, `app_id`, `console_url`, `detail_url`, image/BOM/block counts, `sync.local_revision` as the version — and the lifecycle state: created **private** (`be_public=0`), a draft only the user can see, already test-deployable to their own devices, not on the plaza (publish = parent skill). No cover yet → note one is required before publishing. Never describe a private or pending app as 已上线 / published.
102
+ 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.
103
+ 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.
104
+ 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.
105
+ 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).
91
106
 
92
- **Partial failure resume**: once `identity.app_id` is set, creation happened. Any later failure (upload, follow-up write) → continue with Workflow C against that `app_id`. Never start Workflow B over for the same manifest.
107
+ ## Existing app: update or resume
93
108
 
94
- ## Workflow C — update (local-first)
109
+ Read the references for the affected sections before editing them. Preserve the same discovery, synthesis, and review standards, scaled to the requested change.
95
110
 
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.
111
+ Handle activity participation on updates per [app-fields.md](../references/app-fields.md#activity-selection-during-app-authoring) and the manifest projection rules.
97
112
 
98
- 1. **Edit the manifest first** (user or agent), bump `sync.local_revision`, validate as in Workflow A step 4.
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.
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.
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.
102
- 5. **Push only what changed**:
103
- | Changed section | Command |
113
+ 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.
114
+ 2. Read `app view --id <app_id> --sketch`. Under review (`be_public=2`) → stop and explain the lock. 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.
115
+ 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.
116
+ 4. Upload changed assets and send only changed sections, using session-owned transients under `.sensecraft/`:
117
+
118
+ | Change | Command |
104
119
  |---|---|
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) |
106
- | BOM | `sensecraft-cli app bom set --id <app_id> --from-json .sensecraft/sensecraft-app.materials.json --yes` |
107
- | deployment blocks | include `deployment` in the `app update` patch |
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)).
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).
110
- 7. **Record**: `last_pushed_revision = local_revision`, new hash + time; archive snapshot; suggest `git add` when in git.
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.
112
-
113
- ## Field and block rules
114
-
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)
120
+ | Info, images, deployment | `app update --id <app_id> --from-json <patch-path> --yes` |
121
+ | BOM | `app bom set --id <app_id> --from-json <materials-path> --yes` |
122
+
123
+ Images require the full ordered URL array; upload with `--for-app`, not `--app-id` (attach prepends a cover). Deployment updates carry the full intended `deployment`; do not accidentally drop unchanged tools.
124
+ 5. Re-read sketch and, when changed, `app bom list --id <app_id> --sketch` even if the write returns `{}`. Advance sync baseline and snapshot only for verified success. On partial failure keep the known ID/upload URLs and reconcile the saved sections before retrying. A published app's update saves a draft; the public copy changes only through the parent publish workflow.
@@ -13,26 +13,13 @@
13
13
  "scene": "",
14
14
  "license": "",
15
15
  "author": "",
16
- "allow_clone": 1,
17
- "allow_commerce": 0
16
+ "allow_clone": null,
17
+ "allow_commerce": null,
18
+ "activity_id": null
18
19
  },
19
- "images": [
20
- {
21
- "path": "docs/images/cover.png",
22
- "sha256": null,
23
- "file_url": null,
24
- "role": "cover"
25
- }
26
- ],
20
+ "images": [],
27
21
  "deployment": {
28
- "blocks": [
29
- {
30
- "id": "intro_1",
31
- "type": "paragraph",
32
- "content": "What this app does, who it is for, and what is in the box.",
33
- "indent": 0
34
- }
35
- ]
22
+ "blocks": []
36
23
  },
37
24
  "bom": {
38
25
  "materials": []