@seeed-studio/sensecraft-cli 0.1.6 → 0.2.1
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/INSTALL.md +2 -2
- package/package.json +2 -2
- package/skills/README.md +6 -1
- package/skills/sensecraft-ai/SKILL.md +5 -3
- package/skills/sensecraft-apps/SKILL.md +12 -3
- package/skills/sensecraft-apps/commands.md +14 -8
- package/skills/sensecraft-apps/create-app/SKILL.md +100 -0
- package/skills/sensecraft-apps/create-app/assets/manifest-template.json +46 -0
- package/skills/sensecraft-apps/create-app/assets/validate_manifest.py +215 -0
- package/skills/sensecraft-apps/create-app/reference-manifest.md +156 -0
- package/skills/sensecraft-apps/reference-app-fields.md +3 -0
- package/skills/sensecraft-apps/reference-tool-blocks.md +15 -2
package/INSTALL.md
CHANGED
|
@@ -163,7 +163,7 @@ Copy-Item .\sensecraft.json "$env:APPDATA\sensecraft-cli\sensecraft.json"
|
|
|
163
163
|
sensecraft-cli update
|
|
164
164
|
```
|
|
165
165
|
|
|
166
|
-
命令会查询 npm 上的最新版本,并执行 `npm install -g @seeed-studio/sensecraft-cli
|
|
166
|
+
命令会查询 npm 上的最新版本,并执行 `npm install -g @seeed-studio/sensecraft-cli@<版本>`。本地版本号已经相同也会重新安装。安装器接着比较 `vendor/.version` 与新包版本,不一致就重新下载二进制。配置目录里的 Access Key 会保留。`--version` 只打印本地版本号,不访问 npm。
|
|
167
167
|
|
|
168
168
|
其它用法:
|
|
169
169
|
|
|
@@ -174,7 +174,7 @@ npm install -g @seeed-studio/sensecraft-cli@latest
|
|
|
174
174
|
|
|
175
175
|
平时使用其它命令时,如果缓存里发现了更新,结束时会在 stderr 提示运行 `sensecraft-cli update`。同一版本 24 小时内只提示一次,出现更新的版本会再提示。24 小时内不会重复访问 npm。本地 `dev` 构建、CI、以及设置了 `SENSECRAFT_CLI_NO_UPDATE_NOTIFIER` 时不提示。
|
|
176
176
|
|
|
177
|
-
进行中的活动也在 stderr 以 `Notice:` 提醒,名称、日期和详情链接来自 `https://api-gateway.seeed.cc/openapi/activity/list`(不带参数,即尚未结束的活动)。24
|
|
177
|
+
进行中的活动也在 stderr 以 `Notice:` 提醒,名称、日期和详情链接来自 `https://api-gateway.seeed.cc/openapi/activity/list`(不带参数,即尚未结束的活动)。24 小时内只提醒一次。交互终端会问 `Ignore this activity? [y/N]`,回答 `y` 之后按 `activity_id` 不再提醒;回答 `n` 时 24 小时后还会再出现。非交互只打印,不提问,也不记成忽略。CI 以及 `SENSECRAFT_CLI_NO_ACTIVITY_NOTIFIER` 时不提醒。
|
|
178
178
|
|
|
179
179
|
当前程序如果不是 npm 安装的(例如直接运行编译出的二进制),`update` 只打印上面的手动安装命令,不会覆盖正在运行的文件。
|
|
180
180
|
|
package/package.json
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@seeed-studio/sensecraft-cli",
|
|
3
|
-
"version": "0.1
|
|
3
|
+
"version": "0.2.1",
|
|
4
4
|
"description": "SenseCAP / SenseCraft AI cloud CLI (devices, apps, models, files, cloud deploy)",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
7
7
|
"type": "git",
|
|
8
|
-
"url": "https://github.com/Seeed-Solution/sensecraft-
|
|
8
|
+
"url": "https://github.com/Seeed-Solution/sensecraft-cli.git",
|
|
9
9
|
"directory": "packages/cli"
|
|
10
10
|
},
|
|
11
11
|
"publishConfig": {
|
package/skills/README.md
CHANGED
|
@@ -8,12 +8,17 @@ Skills for this repo live under `skills/`.
|
|
|
8
8
|
|------|------|---------|
|
|
9
9
|
| `skills/sensecraft-ai/SKILL.md` | router | Meta: pick skill + auth kind |
|
|
10
10
|
| `skills/sensecraft-data/` | `sensecap` | SenseCAP PaaS: devices / groups / data |
|
|
11
|
-
| `skills/sensecraft-apps/` | Access Key | Application Plaza |
|
|
11
|
+
| `skills/sensecraft-apps/` | Access Key | Application Plaza (publish / unpublish / delete) |
|
|
12
|
+
| `skills/sensecraft-apps/create-app/` | Access Key | Manifest-driven app lifecycle: gather a finished project into `sensecraft-app.json` (source of truth, versioned when no git), one-go create, local-first updates with drift detection (stops before publish) |
|
|
12
13
|
| `skills/sensecraft-files/` | Access Key | Upload file and obtain `file_url` |
|
|
13
14
|
| `skills/sensecraft-models/` | Access Key | Model library |
|
|
14
15
|
| `skills/sensecraft-recamera/` | `sensecap` Access Key | Classic reCamera 40 pick / check / open |
|
|
15
16
|
| `skills/sensecraft-devices-cloud/` | Access Key | Jetson / cloud kit deploy |
|
|
16
17
|
|
|
18
|
+
**Sub-skill naming:** `sensecraft-apps/create-app` is a nested sub-skill inside the `sensecraft-apps` family. The leaf name `create-app` follows the verb-noun rule (`create` + `app`). Top-level folders keep the `sensecraft-*` domain prefix. Document any new exception here before publishing it.
|
|
19
|
+
|
|
20
|
+
**Archived drafts:** superseded drafts may be kept locally in `*-legacy/` directories. They are not routable skills, are not committed, and are excluded from the npm package by `script/sync-skills-to-npm.sh`.
|
|
21
|
+
|
|
17
22
|
## Cursor / Agent setup
|
|
18
23
|
|
|
19
24
|
1. 安装 CLI:见仓库根目录 [`INSTALL.md`](../INSTALL.md) §2 / §9。
|
|
@@ -10,7 +10,7 @@ description: >-
|
|
|
10
10
|
|
|
11
11
|
# SenseCraft AI (Meta)
|
|
12
12
|
|
|
13
|
-
Router skill for **SenseCraft AI** capabilities exposed via CLI in this repo (`sensecraft-
|
|
13
|
+
Router skill for **SenseCraft AI** capabilities exposed via CLI in this repo (`sensecraft-cli`). Domain skills and AI subcommands are rolled out in phases; this skill always applies for **intent routing, auth kind selection, and product-term disambiguation**.
|
|
14
14
|
|
|
15
15
|
Sibling (already shipped): [`../sensecraft-data/SKILL.md`](../sensecraft-data/SKILL.md) — SenseCAP PaaS OpenAPI (`device` / `group` / `data`).
|
|
16
16
|
|
|
@@ -47,9 +47,9 @@ Sibling (already shipped): [`../sensecraft-data/SKILL.md`](../sensecraft-data/SK
|
|
|
47
47
|
| `Global` | `https://api-gateway.seeed.cc/openapi` | `account.seeed.cc/authapi` |
|
|
48
48
|
| `China` | `https://api-gateway.seeed.cc/openapi` | `account.seeed.cn/authapi` |
|
|
49
49
|
|
|
50
|
-
China 与 Global 使用同一个 AI host,账号中心不同。网页控制台仍是 `https://sensecraft.seeed.cc
|
|
50
|
+
China 与 Global 使用同一个 AI host,账号中心不同。网页控制台仍是 `https://sensecraft.seeed.cc`。`SENSECRAFT_AUTH_HOST` 盖住账号中心(设备码、换 token、换 Access Key);设了之后 Global / China 都打到这个站点根,浏览器打开的是该服务返回的验证地址。
|
|
51
51
|
|
|
52
|
-
成功命令结束后,stderr 可能各有一条英文提示,同一条 24 小时内只出现一次。看到 `Warning: A new version of sensecraft-cli (<version>)` 时,完成当前请求后可以建议用户运行 `sensecraft-cli update`。看到 `Notice: SenseCraft AI is hosting the <name> activity`
|
|
52
|
+
成功命令结束后,stderr 可能各有一条英文提示,同一条 24 小时内只出现一次。看到 `Warning: A new version of sensecraft-cli (<version>)` 时,完成当前请求后可以建议用户运行 `sensecraft-cli update`。看到 `Notice: SenseCraft AI is hosting the <name> activity` 时,把活动名称、日期和链接告诉用户。交互终端会问 `Ignore this activity? [y/N]`;用户回答 `y` 之后,这条活动不再提醒。不要替用户打开链接。
|
|
53
53
|
|
|
54
54
|
`auth info` shows the active Access Key (site, org, key id). Secrets are not printed.
|
|
55
55
|
|
|
@@ -60,6 +60,7 @@ China 与 Global 使用同一个 AI host,账号中心不同。网页控制台
|
|
|
60
60
|
| SenseCAP list/bind device, groups, telemetry | [`sensecraft-data`](../sensecraft-data/SKILL.md) | `sensecap` | Shipped today |
|
|
61
61
|
| Browse / search App Plaza, view app | [`sensecraft-apps`](../sensecraft-apps/SKILL.md) + `app list` / `app view` | `sensecap` | **CLI shipped** (list/view) |
|
|
62
62
|
| App fields / tool-blocks / BOM guidance | same apps skill references | `sensecap` | Config OK; real flash = L3 |
|
|
63
|
+
| Author a new app (create + info + images + BOM + blocks) | [`sensecraft-apps/create-app`](../sensecraft-apps/create-app/SKILL.md) | `sensecap` | One batch confirmation; stops before publish |
|
|
63
64
|
| Create / update / publish / unpublish / delete / bom app | same + `app …` / `app bom …` | `sensecap` | **CLI shipped** (L2 `--yes`; publish also `--agree-declaration`; bare `create --name` not L2) |
|
|
64
65
|
| Upload image/file/firmware/doc/archive and obtain `file_url` | [`sensecraft-files`](../sensecraft-files/SKILL.md) + `file upload` | `sensecap` | Types `1`–`2` require `--model-id`/`--app-id --yes`/`--for-app`/`--unlinked`; types `3`–`6` direct |
|
|
65
66
|
| Model library search/view/download/constants | [`sensecraft-models`](../sensecraft-models/SKILL.md) | `sensecap` | **CLI shipped** |
|
|
@@ -126,6 +127,7 @@ Published AI CLI is `app` / `model` / `file` / `cloud` / `recamera`. If a comman
|
|
|
126
127
|
| [`../sensecraft-data/SKILL.md`](../sensecraft-data/SKILL.md) | SenseCAP PaaS skill (shipped) |
|
|
127
128
|
| [`../sensecraft-data/commands.md`](../sensecraft-data/commands.md) | Full SenseCAP command reference |
|
|
128
129
|
| `skills/sensecraft-apps/` | App Plaza skill + field/block refs (**shipped**) |
|
|
130
|
+
| `skills/sensecraft-apps/create-app/` | App authoring sub-skill: one batch confirmation (**shipped**) |
|
|
129
131
|
| `skills/sensecraft-models/` | Model library skill + field refs (**shipped**) |
|
|
130
132
|
| `skills/sensecraft-recamera/` | Classic reCamera 40 pick → check → open deploy page (**shipped**) |
|
|
131
133
|
| `skills/sensecraft-devices-cloud/` | Jetson / cloud kit (**shipped**) |
|
|
@@ -13,7 +13,8 @@ description: >-
|
|
|
13
13
|
Domain skill for **SenseCraft AI applications**. Auth: **Access Key** → `{ai-host}/openapi` (HTTP Basic).
|
|
14
14
|
|
|
15
15
|
Parent router: [`../sensecraft-ai/SKILL.md`](../sensecraft-ai/SKILL.md).
|
|
16
|
-
SenseCAP IoT: [`../sensecraft-data/SKILL.md`](../sensecraft-data/SKILL.md).
|
|
16
|
+
SenseCAP IoT: [`../sensecraft-data/SKILL.md`](../sensecraft-data/SKILL.md).
|
|
17
|
+
Child skill: [`create-app/SKILL.md`](create-app/SKILL.md) — manifest-driven app lifecycle: mine a finished local project into a versioned `sensecraft-app.json` manifest (source of truth), create the app in one go, then local-first updates with drift detection (one batch confirmation per push). Publish / unpublish / delete stay in this file.
|
|
17
18
|
|
|
18
19
|
## Agent rules
|
|
19
20
|
|
|
@@ -22,7 +23,7 @@ SenseCAP IoT: [`../sensecraft-data/SKILL.md`](../sensecraft-data/SKILL.md).
|
|
|
22
23
|
sensecraft-cli auth info
|
|
23
24
|
```
|
|
24
25
|
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.
|
|
25
|
-
2. **L2 confirm is a separate chat turn** ([`../confirmation.md`](../confirmation.md)) before: `publish` (`--agree-declaration`), `unpublish`, `delete`, **`app update` / `bom set`**. 「删除应用 demo」is **not** confirmation — ask `将从{环境}环境删除应用 demo(ID: …)。删除后可能无法恢复。是否确认执行?`, wait for `确认`, then `--yes`. Never pass `--yes` on the same turn as the first request.
|
|
26
|
+
2. **L2 confirm is a separate chat turn** ([`../confirmation.md`](../confirmation.md)) before: `publish` (`--agree-declaration`), `unpublish`, `delete`, **`app update` / `bom set`**. 「删除应用 demo」is **not** confirmation — ask `将从{环境}环境删除应用 demo(ID: …)。删除后可能无法恢复。是否确认执行?`, wait for `确认`, then `--yes`. Never pass `--yes` on the same turn as the first request. **Exception — batch authoring:** [`create-app`](create-app/SKILL.md) confirms a whole push batch (fields + images + BOM + blocks) in one turn instead of per write; its one-go `app create` needs no confirmation at all.
|
|
26
27
|
**`app create` is not L2** — including `--from-json` with full fields (create + internal follow-up `update_app` on the **new** `app_id` only). Prefer one-shot create when the payload is ready. Still tell the user what will be created before running create.
|
|
27
28
|
3. **Privacy values**: submit review → `privacy` / flow uses **`2`** (pending); unpublish/private → **`0`**. **Never send `1`** (ops-approved public; Admin only).
|
|
28
29
|
4. Tool-block **configuration** may be written into `deployment.blocks`. **Executing** flash / USB deploy / container install on hardware is **L3**. Classic reCamera (`40`): [`sensecraft-recamera`](../sensecraft-recamera/SKILL.md) (`check` / `open`). Other benches: Console `/ai/device/local/32|36|37|41|52`. `flash-firmware` run is out of scope this pass.
|
|
@@ -41,7 +42,7 @@ SenseCAP IoT: [`../sensecraft-data/SKILL.md`](../sensecraft-data/SKILL.md).
|
|
|
41
42
|
| Cover / attachment upload | `file upload --path <img> --type 1 --app-id <id> --yes` (prepends cover, **5 MB**). Unlinked: `file upload --type 1 --for-app` when building a new app payload. |
|
|
42
43
|
| `app bom search\|list\|set` | **Implemented** (catalog = local filter on `get_production_options`; set via `update_app`) |
|
|
43
44
|
| `scene` / option ids | Use `sensecraft-cli model constants` (`app_scenarios_array`) |
|
|
44
|
-
| BOM **price / image** | Seeed rows: **readable** from `app bom search` (`price`, `pic_url`), resolved by SKU — not stored in `materials[]`. Custom rows: **unsupported
|
|
45
|
+
| BOM **price / image** | Seeed rows: **readable** from `app bom search` (`price`, `pic_url`), resolved by SKU — not stored in `materials[]`. Custom rows: price/image **unsupported** (no Console input) — custom rows themselves are fine |
|
|
45
46
|
|
|
46
47
|
When a command exists, prefer it. When it does not, explain the gap and use field/block references below to prepare payloads — do not invent HTTP with guessed tokens; do not misuse SenseCAP CLI.
|
|
47
48
|
|
|
@@ -68,6 +69,14 @@ echo '{"app_name":"Dimmer Tutorial · Grove Beginner Kit"}' \
|
|
|
68
69
|
sensecraft-cli app view --id <app_id> --sketch # must show new app_name
|
|
69
70
|
```
|
|
70
71
|
|
|
72
|
+
### Join an activity (L2)
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
sensecraft-cli app update --id <app_id> --activity-id 1 --yes
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
`activity_id` is an optional positive integer. Omit it to leave existing activity tags unchanged. `tags` is ignored. A bad id fails the whole edit (`11202`); an unknown or inactive activity also fails the whole edit (`25000` `Activity does not exist or has expired`).
|
|
79
|
+
|
|
71
80
|
### Publish / unpublish / delete (L2)
|
|
72
81
|
|
|
73
82
|
```bash
|
|
@@ -58,7 +58,7 @@ sensecraft-cli app view --id <app_id> --sketch
|
|
|
58
58
|
|
|
59
59
|
### `app fields`
|
|
60
60
|
|
|
61
|
-
**Status: implemented.** Prints JSON schema (app info + BOM). Requires AI auth profile; no
|
|
61
|
+
**Status: implemented.** Prints JSON schema (app info + BOM). Requires AI auth profile; static output, zero network — **no `--sandbox` flag; run bare**.
|
|
62
62
|
|
|
63
63
|
```bash
|
|
64
64
|
sensecraft-cli app fields
|
|
@@ -66,7 +66,7 @@ sensecraft-cli app fields
|
|
|
66
66
|
|
|
67
67
|
### `app blocks`
|
|
68
68
|
|
|
69
|
-
**Status: implemented.** Prints deploy layout + tool-block catalog. Requires AI auth profile; no
|
|
69
|
+
**Status: implemented.** Prints deploy layout + tool-block catalog. Requires AI auth profile; static output, zero network — **no `--sandbox` flag; run bare**.
|
|
70
70
|
|
|
71
71
|
```bash
|
|
72
72
|
sensecraft-cli app blocks
|
|
@@ -108,12 +108,13 @@ sensecraft-cli app create --name "My App"
|
|
|
108
108
|
|
|
109
109
|
#### `app update` (L2)
|
|
110
110
|
|
|
111
|
-
| Flag
|
|
112
|
-
|
|
|
113
|
-
| `--id`
|
|
114
|
-
| `--from-json`
|
|
115
|
-
| `--
|
|
116
|
-
| `--
|
|
111
|
+
| Flag | Notes |
|
|
112
|
+
| --------------- | ---------------------------------------------------------------------------------------------------------- |
|
|
113
|
+
| `--id` | required |
|
|
114
|
+
| `--from-json` | path or `-`; required unless `--activity-id` is set |
|
|
115
|
+
| `--activity-id` | optional positive integer. Joins that activity. Omit or pass empty to leave existing activity tags as-is |
|
|
116
|
+
| `--yes` | after user confirmation |
|
|
117
|
+
| `--sandbox` | sample JSON |
|
|
117
118
|
|
|
118
119
|
Rejects `be_public=1` / `privacy=1` in **user** payload. If the app is already public (`be_public=1`), CLI injects `be_public=1` on info saves (Console) and JSON includes `sketch_saved`. Under review (`be_public=2`): **refused**. Others' apps (`user_id` ≠ profile): **refused**.
|
|
119
120
|
|
|
@@ -128,8 +129,13 @@ echo '{"app_name":"New Name"}' | sensecraft-cli app update --id <app_id> --from-
|
|
|
128
129
|
sensecraft-cli app view --id <app_id> --sketch # confirm app_name
|
|
129
130
|
|
|
130
131
|
sensecraft-cli app update --id <app_id> --from-json ./app.json --yes
|
|
132
|
+
|
|
133
|
+
# Join activity 1. activity_id is sent as a JSON number. tags in JSON is dropped.
|
|
134
|
+
sensecraft-cli app update --id <app_id> --activity-id 1 --yes
|
|
131
135
|
```
|
|
132
136
|
|
|
137
|
+
`activity_id` must be a positive integer. The server rejects anything else with `11202` `Request parameters are invalid`, and rejects a missing, unpublished, deleted, or out-of-window activity with `25000` `Activity does not exist or has expired`. Either failure discards the whole edit, including other fields in the same request. Omitting `activity_id` does not change existing activity tags. `tags` is not read by the server.
|
|
138
|
+
|
|
133
139
|
### `app publish` / `app unpublish` / `app delete` (L2)
|
|
134
140
|
|
|
135
141
|
**Status: implemented.**
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
---
|
|
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.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# create-app
|
|
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.
|
|
9
|
+
|
|
10
|
+
Parent skill: [`../SKILL.md`](../SKILL.md). Routing: [`../../sensecraft-ai/SKILL.md`](../../sensecraft-ai/SKILL.md).
|
|
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.
|
|
13
|
+
|
|
14
|
+
## Why the manifest exists
|
|
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.
|
|
17
|
+
|
|
18
|
+
Manifest schema, field-by-field: [reference-manifest.md](reference-manifest.md). Starting template: [assets/manifest-template.json](assets/manifest-template.json).
|
|
19
|
+
|
|
20
|
+
## Manifest files on disk
|
|
21
|
+
|
|
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.
|
|
29
|
+
|
|
30
|
+
## Workflow A — gather
|
|
31
|
+
|
|
32
|
+
Mine first, ask approval once at the end.
|
|
33
|
+
|
|
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 [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.
|
|
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).
|
|
50
|
+
|
|
51
|
+
## Writing the prose
|
|
52
|
+
|
|
53
|
+
Published text is what plaza users actually read — mine it from the project, but author it deliberately.
|
|
54
|
+
|
|
55
|
+
- `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.
|
|
56
|
+
- `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. Text blocks render Markdown — images and external video links are available; see [reference-tool-blocks.md](../reference-tool-blocks.md#content-format).
|
|
57
|
+
- Review once before every push: would a first-time user find every sentence clear, with nothing repeated?
|
|
58
|
+
|
|
59
|
+
## Workflow B — create (one-go)
|
|
60
|
+
|
|
61
|
+
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.
|
|
62
|
+
2. **Upload assets**, writing each returned `file_url` back into the manifest entry:
|
|
63
|
+
|
|
64
|
+
- Images: `sensecraft-cli file upload --path <img> --type 1 --for-app` (unlinked, 5 MB cap). Keep manifest order; index 0 = cover.
|
|
65
|
+
- 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`).
|
|
66
|
+
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).
|
|
67
|
+
4. **Create** — deliberately not L2, no `--yes`:
|
|
68
|
+
```bash
|
|
69
|
+
sensecraft-cli app create --from-json .sensecraft/sensecraft-app.payload.json
|
|
70
|
+
```
|
|
71
|
+
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.
|
|
72
|
+
5. **Record**: write `app_id`, `created_at` into `identity`; set `sync.last_pushed_*` (revision, RFC3339 time, payload hash); archive snapshot.
|
|
73
|
+
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.
|
|
74
|
+
|
|
75
|
+
**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.
|
|
76
|
+
|
|
77
|
+
## Workflow C — update (local-first)
|
|
78
|
+
|
|
79
|
+
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.
|
|
80
|
+
|
|
81
|
+
1. **Edit the manifest first** (user or agent), bump `sync.local_revision`, validate as in Workflow A step 4.
|
|
82
|
+
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.
|
|
83
|
+
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.
|
|
84
|
+
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.
|
|
85
|
+
5. **Push only what changed**:
|
|
86
|
+
| Changed section | Command |
|
|
87
|
+
|---|---|
|
|
88
|
+
| 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) |
|
|
89
|
+
| BOM | `sensecraft-cli app bom set --id <app_id> --from-json .sensecraft/sensecraft-app.materials.json --yes` |
|
|
90
|
+
| deployment blocks | include `deployment` in the `app update` patch |
|
|
91
|
+
- **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)).
|
|
92
|
+
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).
|
|
93
|
+
7. **Record**: `last_pushed_revision = local_revision`, new hash + time; archive snapshot; suggest `git add` when in git.
|
|
94
|
+
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.
|
|
95
|
+
|
|
96
|
+
## Field and block rules
|
|
97
|
+
|
|
98
|
+
- App info + BOM: [../reference-app-fields.md](../reference-app-fields.md)
|
|
99
|
+
- Deployment layout + tool-block configs: [../reference-tool-blocks.md](../reference-tool-blocks.md)
|
|
100
|
+
- CLI flags for every command above: [../commands.md](../commands.md)
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
{
|
|
2
|
+
"manifest_version": 1,
|
|
3
|
+
"identity": {
|
|
4
|
+
"app_id": null,
|
|
5
|
+
"remote_type": null,
|
|
6
|
+
"org_id": null,
|
|
7
|
+
"account": null,
|
|
8
|
+
"created_at": null
|
|
9
|
+
},
|
|
10
|
+
"info": {
|
|
11
|
+
"app_name": "",
|
|
12
|
+
"excerpt": "",
|
|
13
|
+
"scene": "",
|
|
14
|
+
"license": "",
|
|
15
|
+
"author": "",
|
|
16
|
+
"allow_clone": 1,
|
|
17
|
+
"allow_commerce": 0
|
|
18
|
+
},
|
|
19
|
+
"images": [
|
|
20
|
+
{
|
|
21
|
+
"path": "docs/images/cover.png",
|
|
22
|
+
"sha256": null,
|
|
23
|
+
"file_url": null,
|
|
24
|
+
"role": "cover"
|
|
25
|
+
}
|
|
26
|
+
],
|
|
27
|
+
"deployment": {
|
|
28
|
+
"blocks": [
|
|
29
|
+
{
|
|
30
|
+
"id": "intro_1",
|
|
31
|
+
"type": "paragraph",
|
|
32
|
+
"content": "<p>What this app does, who it is for, and what is in the box.</p>",
|
|
33
|
+
"indent": 0
|
|
34
|
+
}
|
|
35
|
+
]
|
|
36
|
+
},
|
|
37
|
+
"bom": {
|
|
38
|
+
"materials": []
|
|
39
|
+
},
|
|
40
|
+
"sync": {
|
|
41
|
+
"local_revision": 1,
|
|
42
|
+
"last_pushed_revision": 0,
|
|
43
|
+
"last_pushed_at": null,
|
|
44
|
+
"last_pushed_hash": null
|
|
45
|
+
}
|
|
46
|
+
}
|
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Validate a sensecraft-app manifest (create-app skill).
|
|
3
|
+
|
|
4
|
+
Mechanical checks only — structure, field limits, image constraints, BOM and
|
|
5
|
+
block shape. This validates FORMAT, never content truth: image content,
|
|
6
|
+
licensing, and factual accuracy remain the agent's job (see SKILL.md,
|
|
7
|
+
Workflow A).
|
|
8
|
+
|
|
9
|
+
Usage: python3 validate_manifest.py [manifest-path] [--scene-ids 1,5,...]
|
|
10
|
+
(both "--scene-ids 1,5" and "--scene-ids=1,5" work; a bare or
|
|
11
|
+
unparsed --scene-ids flag is a hard error, never a silent skip)
|
|
12
|
+
|
|
13
|
+
Exit 0 = pass (warnings allowed); exit 1 = one or more violations.
|
|
14
|
+
"""
|
|
15
|
+
import hashlib
|
|
16
|
+
import json
|
|
17
|
+
import os
|
|
18
|
+
import re
|
|
19
|
+
import sys
|
|
20
|
+
|
|
21
|
+
IMAGE_EXTS = {".jpg", ".jpeg", ".png", ".gif", ".webp"}
|
|
22
|
+
IMAGE_MAX_BYTES = 5 * 1024 * 1024
|
|
23
|
+
IMAGES_MAX = 16
|
|
24
|
+
NAME_MAX = 60 # UTF-16 code units, Console-aligned
|
|
25
|
+
EXCERPT_MAX = 300 # UTF-16 code units
|
|
26
|
+
SCENE_RE = re.compile(r"^\d+$")
|
|
27
|
+
# Shapes that must never appear in fields that get published. Matches
|
|
28
|
+
# credential VALUES (known prefixes, key=value assignments), never the mere
|
|
29
|
+
# words "token"/"password" — instructions about creating a token are legit.
|
|
30
|
+
SECRET_VALUE_RE = re.compile(
|
|
31
|
+
r"(mgst_[A-Za-z0-9_-]{6,}|sk-[A-Za-z0-9_-]{8,}|bearer\s+[A-Za-z0-9._-]{8,}"
|
|
32
|
+
r"|(?i:access[_-]?key|password|passwd|secret|api[_-]?key)\s*[:=]\s*\S{6,})"
|
|
33
|
+
)
|
|
34
|
+
LONG_HEX_RE = re.compile(r"\b[0-9a-f]{40,}\b")
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def utf16_len(s):
|
|
38
|
+
return len(s.encode("utf-16-le")) // 2
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def main():
|
|
42
|
+
argv = sys.argv[1:]
|
|
43
|
+
path, scene_ids = "sensecraft-app.json", set()
|
|
44
|
+
i = 0
|
|
45
|
+
while i < len(argv):
|
|
46
|
+
a = argv[i]
|
|
47
|
+
if a == "--scene-ids":
|
|
48
|
+
if i + 1 >= len(argv) or argv[i + 1].startswith("--"):
|
|
49
|
+
print("ERROR: --scene-ids needs a comma-separated value (or use --scene-ids=...)")
|
|
50
|
+
return 2
|
|
51
|
+
scene_ids = set(argv[i + 1].split(",")) - {""}
|
|
52
|
+
i += 2
|
|
53
|
+
elif a.startswith("--scene-ids="):
|
|
54
|
+
scene_ids = set(a.split("=", 1)[1].split(",")) - {""}
|
|
55
|
+
i += 1
|
|
56
|
+
elif a.startswith("--"):
|
|
57
|
+
print(f"ERROR: unknown flag {a!r}")
|
|
58
|
+
return 2
|
|
59
|
+
else:
|
|
60
|
+
path = a
|
|
61
|
+
i += 1
|
|
62
|
+
|
|
63
|
+
violations, warnings = [], []
|
|
64
|
+
|
|
65
|
+
def vio(msg):
|
|
66
|
+
violations.append(msg)
|
|
67
|
+
|
|
68
|
+
def warn(msg):
|
|
69
|
+
warnings.append(msg)
|
|
70
|
+
|
|
71
|
+
try:
|
|
72
|
+
with open(path, encoding="utf-8") as f:
|
|
73
|
+
m = json.load(f)
|
|
74
|
+
except (OSError, json.JSONDecodeError) as e:
|
|
75
|
+
print(f"VIOLATION cannot read/parse {path}: {e}")
|
|
76
|
+
return 1
|
|
77
|
+
base = os.path.dirname(os.path.abspath(path))
|
|
78
|
+
|
|
79
|
+
for key in ("manifest_version", "identity", "info", "images", "deployment", "bom", "sync"):
|
|
80
|
+
if key not in m:
|
|
81
|
+
vio(f"missing top-level section: {key}")
|
|
82
|
+
|
|
83
|
+
ident = m.get("identity", {})
|
|
84
|
+
rt = ident.get("remote_type")
|
|
85
|
+
if rt is not None and rt not in ("Global", "China", "Private"):
|
|
86
|
+
vio(f"identity.remote_type must be Global|China|Private, got {rt!r}")
|
|
87
|
+
if ident.get("app_id") is not None and not str(ident["app_id"]).strip():
|
|
88
|
+
vio("identity.app_id is set but empty")
|
|
89
|
+
|
|
90
|
+
info = m.get("info", {})
|
|
91
|
+
name = info.get("app_name", "")
|
|
92
|
+
if not name.strip():
|
|
93
|
+
vio("info.app_name is empty")
|
|
94
|
+
elif utf16_len(name) > NAME_MAX:
|
|
95
|
+
vio(f"info.app_name is {utf16_len(name)} UTF-16 code units (max {NAME_MAX})")
|
|
96
|
+
excerpt = info.get("excerpt", "")
|
|
97
|
+
if not excerpt.strip():
|
|
98
|
+
vio("info.excerpt is empty")
|
|
99
|
+
elif utf16_len(excerpt) > EXCERPT_MAX:
|
|
100
|
+
vio(f"info.excerpt is {utf16_len(excerpt)} UTF-16 code units (max {EXCERPT_MAX})")
|
|
101
|
+
scene = str(info.get("scene", ""))
|
|
102
|
+
if not SCENE_RE.match(scene):
|
|
103
|
+
vio(f"info.scene must be a string id from app_scenarios_array, got {scene!r}")
|
|
104
|
+
elif scene_ids and scene not in scene_ids:
|
|
105
|
+
vio(f"info.scene {scene} not in known ids {{{', '.join(sorted(scene_ids))}}}")
|
|
106
|
+
for flag in ("allow_clone", "allow_commerce"):
|
|
107
|
+
if info.get(flag) not in (0, 1):
|
|
108
|
+
vio(f"info.{flag} must be 0 or 1, got {info.get(flag)!r}")
|
|
109
|
+
|
|
110
|
+
images = m.get("images", [])
|
|
111
|
+
if not isinstance(images, list):
|
|
112
|
+
vio(f"images must be an array, got {type(images).__name__}")
|
|
113
|
+
images = []
|
|
114
|
+
elif len(images) > IMAGES_MAX:
|
|
115
|
+
vio(f"images must hold at most {IMAGES_MAX} entries, got {len(images)}")
|
|
116
|
+
elif len(images) == 0:
|
|
117
|
+
warn("no images — fine for a private draft (omit the `images` key in the payload; the CLI rejects an empty array); a cover is required before publishing")
|
|
118
|
+
if isinstance(images, list):
|
|
119
|
+
for i, img in enumerate(images):
|
|
120
|
+
p, role = img.get("path", ""), img.get("role", "")
|
|
121
|
+
if i == 0 and role != "cover":
|
|
122
|
+
vio("images[0].role must be 'cover'")
|
|
123
|
+
if i > 0 and role != "gallery":
|
|
124
|
+
vio(f"images[{i}].role must be 'gallery'")
|
|
125
|
+
ext = os.path.splitext(p)[1].lower()
|
|
126
|
+
if ext not in IMAGE_EXTS:
|
|
127
|
+
vio(f"images[{i}] {p!r}: extension {ext or '(none)'} not in {sorted(IMAGE_EXTS)} (SVG rejected)")
|
|
128
|
+
full = os.path.join(base, p)
|
|
129
|
+
if not os.path.isfile(full):
|
|
130
|
+
vio(f"images[{i}] {p!r}: file not found relative to manifest")
|
|
131
|
+
else:
|
|
132
|
+
size = os.path.getsize(full)
|
|
133
|
+
if size == 0:
|
|
134
|
+
vio(f"images[{i}] {p!r}: zero-byte file")
|
|
135
|
+
elif size > IMAGE_MAX_BYTES:
|
|
136
|
+
vio(f"images[{i}] {p!r}: {size} bytes exceeds 5 MB")
|
|
137
|
+
if img.get("sha256"):
|
|
138
|
+
digest = hashlib.sha256(open(full, "rb").read()).hexdigest()
|
|
139
|
+
if digest != img["sha256"]:
|
|
140
|
+
vio(f"images[{i}] {p!r}: sha256 mismatch (file changed since hash)")
|
|
141
|
+
else:
|
|
142
|
+
warn(f"images[{i}] {p!r}: sha256 not computed yet")
|
|
143
|
+
url = img.get("file_url")
|
|
144
|
+
if url is not None and not re.match(r"^https?://", str(url)):
|
|
145
|
+
vio(f"images[{i}].file_url must be http(s), got {url!r}")
|
|
146
|
+
elif url is None:
|
|
147
|
+
warn(f"images[{i}] {p!r}: not uploaded yet (file_url null)")
|
|
148
|
+
|
|
149
|
+
blocks = m.get("deployment", {}).get("blocks", [])
|
|
150
|
+
if not isinstance(blocks, list):
|
|
151
|
+
vio("deployment.blocks must be an array")
|
|
152
|
+
else:
|
|
153
|
+
seen = set()
|
|
154
|
+
for b in blocks:
|
|
155
|
+
bid = b.get("id")
|
|
156
|
+
if bid in seen:
|
|
157
|
+
vio(f"deployment.blocks: duplicate id {bid!r}")
|
|
158
|
+
seen.add(bid)
|
|
159
|
+
if b.get("type") == "step" and not b.get("title"):
|
|
160
|
+
vio(f"deployment.blocks[{bid}]: step block missing title")
|
|
161
|
+
if b.get("type") not in ("step", "paragraph", "h1", "h2", "h3", "h4", "h5", "h6",
|
|
162
|
+
"bullet", "number", "todo", "quote", "code", "divider") \
|
|
163
|
+
and "config" not in b:
|
|
164
|
+
vio(f"deployment.blocks[{bid}]: tool block {b.get('type')!r} missing config")
|
|
165
|
+
cfg = b.get("config")
|
|
166
|
+
if isinstance(cfg, dict):
|
|
167
|
+
for k, val in cfg.items():
|
|
168
|
+
if k.endswith("_url") and isinstance(val, str) and not val.strip():
|
|
169
|
+
warn(f"deployment.blocks[{bid}]: config.{k} is empty — pending value, fill before publishing")
|
|
170
|
+
|
|
171
|
+
materials = m.get("bom", {}).get("materials", [])
|
|
172
|
+
if not isinstance(materials, list):
|
|
173
|
+
vio("bom.materials must be an array")
|
|
174
|
+
else:
|
|
175
|
+
for i, row in enumerate(materials):
|
|
176
|
+
for forbidden in ("price", "pic_url", "image"):
|
|
177
|
+
if forbidden in row:
|
|
178
|
+
vio(f"bom.materials[{i}]: {forbidden!r} is not a persistable field (dropped server-side)")
|
|
179
|
+
if "id" in row: # Seeed catalog row
|
|
180
|
+
for req in ("name", "quantity", "note", "buy_url"):
|
|
181
|
+
if req not in row:
|
|
182
|
+
vio(f"bom.materials[{i}] (catalog row): missing {req!r}")
|
|
183
|
+
else: # custom row
|
|
184
|
+
if not row.get("name") or not row.get("quantity"):
|
|
185
|
+
vio(f"bom.materials[{i}] (custom row): needs at least name + quantity")
|
|
186
|
+
|
|
187
|
+
sync = m.get("sync", {})
|
|
188
|
+
lr, lpr = sync.get("local_revision"), sync.get("last_pushed_revision")
|
|
189
|
+
if not isinstance(lr, int) or lr < 1:
|
|
190
|
+
vio(f"sync.local_revision must be an integer >= 1, got {lr!r}")
|
|
191
|
+
if not isinstance(lpr, int) or lpr < 0 or (isinstance(lr, int) and lpr > lr):
|
|
192
|
+
vio(f"sync.last_pushed_revision must be 0..local_revision, got {lpr!r}")
|
|
193
|
+
|
|
194
|
+
prose_fields = [info.get("app_name", ""), info.get("excerpt", "")]
|
|
195
|
+
prose_fields += [str(b.get("content", "")) + str(b.get("title", "")) for b in blocks if isinstance(b, dict)]
|
|
196
|
+
prose_fields += [str(r.get("note", "")) for r in materials if isinstance(r, dict)]
|
|
197
|
+
for text in prose_fields:
|
|
198
|
+
if text and SECRET_VALUE_RE.search(text):
|
|
199
|
+
vio(f"secret-shaped value in publishable text: {text[:60]!r}…")
|
|
200
|
+
elif text and LONG_HEX_RE.search(text):
|
|
201
|
+
warn(f"long hex literal in publishable text (key/hash?): {text[:60]!r}…")
|
|
202
|
+
|
|
203
|
+
for w in warnings:
|
|
204
|
+
print(f"WARNING {w}")
|
|
205
|
+
for v in violations:
|
|
206
|
+
print(f"VIOLATION {v}")
|
|
207
|
+
if violations:
|
|
208
|
+
print(f"\nFAIL: {len(violations)} violation(s), {len(warnings)} warning(s)")
|
|
209
|
+
return 1
|
|
210
|
+
print(f"\nPASS: {path} ({len(warnings)} warning(s))")
|
|
211
|
+
return 0
|
|
212
|
+
|
|
213
|
+
|
|
214
|
+
if __name__ == "__main__":
|
|
215
|
+
sys.exit(main())
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
# Manifest reference — `sensecraft-app.json`
|
|
2
|
+
|
|
3
|
+
The manifest is the local source of truth for one SenseCraft app. It is **not** the CLI payload verbatim: it carries local-only bookkeeping (paths, hashes, sync state) that must be stripped when building `--from-json` bodies.
|
|
4
|
+
|
|
5
|
+
Top-level sections: `manifest_version`, `identity`, `info`, `images`, `deployment`, `bom`, `sync`.
|
|
6
|
+
|
|
7
|
+
## `manifest_version`
|
|
8
|
+
|
|
9
|
+
Integer, currently `1`. Bump only when the schema changes shape.
|
|
10
|
+
|
|
11
|
+
## `identity` — which remote app, which account
|
|
12
|
+
|
|
13
|
+
| Key | Filled when | Notes |
|
|
14
|
+
|-----|-------------|-------|
|
|
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 |
|
|
17
|
+
| `org_id` | preflight | from `auth info` |
|
|
18
|
+
| `account` | preflight | from `auth info` |
|
|
19
|
+
| `created_at` | after create | **Local UTC timestamp recorded when create succeeds** — the CLI returns no created time |
|
|
20
|
+
|
|
21
|
+
## `info` — app info gate fields
|
|
22
|
+
|
|
23
|
+
| Key | Rule |
|
|
24
|
+
|-----|------|
|
|
25
|
+
| `app_name` | non-empty, ≤ 60 UTF-16 code units |
|
|
26
|
+
| `excerpt` | non-empty, ≤ 300 UTF-16 code units |
|
|
27
|
+
| `scene` | string id from `app_scenarios_array` (`sensecraft-cli model constants`) |
|
|
28
|
+
| `license` | string, may be `""` |
|
|
29
|
+
| `author` | string; default the `auth info` account |
|
|
30
|
+
| `allow_clone` | `0` or `1` only |
|
|
31
|
+
| `allow_commerce` | `0` or `1` only |
|
|
32
|
+
|
|
33
|
+
Full field compliance: [../reference-app-fields.md](../reference-app-fields.md).
|
|
34
|
+
|
|
35
|
+
## `images` — local paths with upload state
|
|
36
|
+
|
|
37
|
+
Array, order matters: **index 0 is the cover** (becomes `pic_url`). Up to 16 entries. May be empty at create time — a private draft works without images; a cover is required before publishing.
|
|
38
|
+
|
|
39
|
+
| Key | Notes |
|
|
40
|
+
|-----|-------|
|
|
41
|
+
| `path` | local file, relative to the manifest |
|
|
42
|
+
| `sha256` | hex digest of file bytes; `null` until computed. Drives re-upload: upload only when changed or `file_url` is null |
|
|
43
|
+
| `file_url` | returned by `file upload --type 1 --for-app`; `null` until uploaded |
|
|
44
|
+
| `role` | `cover` for index 0, `gallery` otherwise |
|
|
45
|
+
|
|
46
|
+
Formats JPG/JPEG/PNG/GIF/WebP, ≤ 5 MB each, prefer 4:3. SVG is rejected by the CLI.
|
|
47
|
+
|
|
48
|
+
## `deployment.blocks`
|
|
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`.
|
|
51
|
+
|
|
52
|
+
## `bom.materials`
|
|
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).
|
|
55
|
+
|
|
56
|
+
## `sync` — local vs remote bookkeeping
|
|
57
|
+
|
|
58
|
+
| Key | Notes |
|
|
59
|
+
|-----|-------|
|
|
60
|
+
| `local_revision` | integer, `+1` on every local edit after creation of the manifest |
|
|
61
|
+
| `last_pushed_revision` | `local_revision` value as of the last successful create/push. `0` + set `app_id` = half-finished create → resume via update |
|
|
62
|
+
| `last_pushed_at` | RFC3339 of last successful push |
|
|
63
|
+
| `last_pushed_hash` | drift baseline — see the pinned algorithm below |
|
|
64
|
+
|
|
65
|
+
**`last_pushed_hash` algorithm** (compute exactly this way so every session reproduces the same baseline):
|
|
66
|
+
|
|
67
|
+
1. Build the projection object `{"info": {...}, "images": ["<file_url>", ...], "deployment": {...}, "materials": [...]}` from the pushed payload — derived keys like `pic_url` are **excluded** (the hash covers the source fields, not derived duplicates).
|
|
68
|
+
2. Serialize as canonical JSON: UTF-8, keys sorted, no insignificant whitespace (Python: `json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False)`).
|
|
69
|
+
3. `last_pushed_hash = "sha256:" + hex(SHA-256 of those bytes)`.
|
|
70
|
+
|
|
71
|
+
On the drift check, apply the same projection to the `app view --sketch` response before hashing, with these equivalence rules:
|
|
72
|
+
|
|
73
|
+
- **Same key set**: a key absent from the remote view is dropped from **both** sides before hashing (server-normalized views may omit keys).
|
|
74
|
+
- **Type normalization**: coerce values to the manifest's forms — e.g. a remote `"scene": 1` (number) compares as `"1"` (string).
|
|
75
|
+
- **Derived keys excluded** on both sides (`pic_url`, `app_id`, timestamps, review/lifecycle fields like `be_public`).
|
|
76
|
+
|
|
77
|
+
## Manifest → CLI payload
|
|
78
|
+
|
|
79
|
+
Build `--from-json` bodies by projection — keep server fields, drop local-only ones:
|
|
80
|
+
|
|
81
|
+
| Manifest | Payload key |
|
|
82
|
+
|----------|-------------|
|
|
83
|
+
| `info.*` | same names at top level |
|
|
84
|
+
| `images[].file_url` (in order) | `images` (array of URLs); `pic_url` = first element. **Empty → omit both keys entirely** — the info gate rejects `images: []`, but accepts the key being absent |
|
|
85
|
+
| `deployment` | `deployment` |
|
|
86
|
+
| `bom.materials` | `materials` |
|
|
87
|
+
| `identity`, `sync`, `images[].path/sha256/role`, `manifest_version` | **never sent** |
|
|
88
|
+
|
|
89
|
+
Never include `be_public` / `privacy` in any payload.
|
|
90
|
+
|
|
91
|
+
## Worked example
|
|
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:
|
|
94
|
+
|
|
95
|
+
```json
|
|
96
|
+
{
|
|
97
|
+
"manifest_version": 1,
|
|
98
|
+
"identity": {
|
|
99
|
+
"app_id": "12345",
|
|
100
|
+
"remote_type": "Global",
|
|
101
|
+
"org_id": "org-9",
|
|
102
|
+
"account": "maker@example.com",
|
|
103
|
+
"created_at": "2026-10-20T08:30:00Z"
|
|
104
|
+
},
|
|
105
|
+
"info": {
|
|
106
|
+
"app_name": "Jar Lid Counter",
|
|
107
|
+
"excerpt": "Counts screw-cap jars on a conveyor with a XIAO ESP32S3 Sense and a FOMO model.",
|
|
108
|
+
"scene": "7",
|
|
109
|
+
"license": "MIT",
|
|
110
|
+
"author": "maker@example.com",
|
|
111
|
+
"allow_clone": 1,
|
|
112
|
+
"allow_commerce": 0
|
|
113
|
+
},
|
|
114
|
+
"images": [
|
|
115
|
+
{
|
|
116
|
+
"path": "docs/images/cover.png",
|
|
117
|
+
"sha256": "b5bb9d…",
|
|
118
|
+
"file_url": "https://files.seeedstudio.com/…/cover.png",
|
|
119
|
+
"role": "cover"
|
|
120
|
+
}
|
|
121
|
+
],
|
|
122
|
+
"deployment": {
|
|
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 },
|
|
126
|
+
{
|
|
127
|
+
"id": "ff_1",
|
|
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
|
+
}
|
|
135
|
+
}
|
|
136
|
+
]
|
|
137
|
+
},
|
|
138
|
+
"bom": {
|
|
139
|
+
"materials": [
|
|
140
|
+
{
|
|
141
|
+
"id": "113991254",
|
|
142
|
+
"quantity": "1",
|
|
143
|
+
"name": "Seeed Studio XIAO ESP32S3 Sense",
|
|
144
|
+
"note": "Main MCU",
|
|
145
|
+
"buy_url": "https://www.seeedstudio.com/"
|
|
146
|
+
}
|
|
147
|
+
]
|
|
148
|
+
},
|
|
149
|
+
"sync": {
|
|
150
|
+
"local_revision": 1,
|
|
151
|
+
"last_pushed_revision": 1,
|
|
152
|
+
"last_pushed_at": "2026-10-20T08:31:02Z",
|
|
153
|
+
"last_pushed_hash": "sha256:9f2c…"
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
```
|
|
@@ -17,16 +17,19 @@ Agent fill-in guide for SenseCraft custom apps (v3). Aligns with Console `infoFo
|
|
|
17
17
|
| `app_id` | id | required on update | from create/list/view |
|
|
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
|
+
| `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). |
|
|
20
21
|
| `flow_data` / `model_data` | Node-RED sync | only with `node-red` block | `flow_data` must be **JSON string** at top level |
|
|
21
22
|
|
|
22
23
|
### Create vs update
|
|
23
24
|
|
|
24
25
|
- **Create (CLI one-shot)**: `POST /flow/app/v3/create_app` then `update_app` with the rest of `--from-json` on the **new** `app_id` only — **no `--yes`**. Editing an **existing** app is `app update --yes` (L2).
|
|
26
|
+
- The follow-up `update_app` also merges missing info keys when a sketch already exists (same merge as `app update`), so an echoed create result may show sketch values for omitted keys.
|
|
25
27
|
- CLI always surfaces `app_id` / `console_url` / `detail_url` after create, even when `update_app` returns `{}`.
|
|
26
28
|
- **Never** retry `app create` solely because the JSON looked empty — run `app list --mine` first; duplicate names are allowed and will spawn extra apps.
|
|
27
29
|
- **Update (`app update`)**: always include `app_id` (CLI `--id`).
|
|
28
30
|
- **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 `{}`.
|
|
29
31
|
- **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.
|
|
30
33
|
- **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 …`.
|
|
31
34
|
|
|
32
35
|
## Visibility / review
|
|
@@ -2,6 +2,17 @@
|
|
|
2
2
|
|
|
3
3
|
Help the Agent choose the right block and fill `config` safely. Execution on hardware is **L3** unless noted.
|
|
4
4
|
|
|
5
|
+
## Content format
|
|
6
|
+
|
|
7
|
+
Text-block `content` (introduction and step text alike) renders **Markdown** — inline HTML like `<p>` also renders and appears in existing docs. Images and externally hosted media are available through ordinary Markdown:
|
|
8
|
+
|
|
9
|
+
```markdown
|
|
10
|
+

|
|
11
|
+
[Watch the demo video](https://example.com/demo.mp4)
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
Host binaries (images, videos) via `file upload` first; Markdown only links out, it does not embed uploads by itself.
|
|
15
|
+
|
|
5
16
|
## Document layout
|
|
6
17
|
|
|
7
18
|
`deployment.blocks` is a **flat** ordered array.
|
|
@@ -21,6 +32,8 @@ Help the Agent choose the right block and fill `config` safely. Execution on har
|
|
|
21
32
|
|
|
22
33
|
Common fields: `id`, `type`, `content`, `indent`, `title`/`expanded` for `step`.
|
|
23
34
|
|
|
35
|
+
**Step titles**: the UI already prefixes the step number (`Step x:` / `第 x 步`) — `title` is the action name only.
|
|
36
|
+
|
|
24
37
|
Prefer `paragraph` under a `step` for instructions; do not overload tool-block `config` with prose.
|
|
25
38
|
|
|
26
39
|
## Tool-block selection
|
|
@@ -155,8 +168,8 @@ Used for **container / edge app** deployment UI inside the application doc.
|
|
|
155
168
|
{
|
|
156
169
|
"id": "step_1",
|
|
157
170
|
"type": "step",
|
|
158
|
-
"title": "
|
|
159
|
-
"content": "
|
|
171
|
+
"title": "Flash firmware",
|
|
172
|
+
"content": "Flash firmware",
|
|
160
173
|
"expanded": true,
|
|
161
174
|
"indent": 0
|
|
162
175
|
},
|