From 666c41bbd1484215f80469685213993dcc9d5da8 Mon Sep 17 00:00:00 2001 From: Edward Tan Date: Wed, 21 Oct 2026 15:55:37 +0800 Subject: [PATCH] docs: carry the OctoSense icon format into app authoring --- AGENTS.md | 10 ++++++++++ README.md | 4 ++++ README.zh-CN.md | 2 ++ docs/PUBLISHING.md | 8 ++++++-- docs/PUBLISHING.zh-CN.md | 4 ++-- docs/QUICKSTART.md | 6 ++++++ docs/QUICKSTART.zh-CN.md | 2 ++ flows/image-to-card/FLOW.md | 7 +++++++ flows/script-app/FLOW.md | 2 +- templates/card-app/README.md | 6 +++++- templates/card-app/README.zh-CN.md | 2 +- templates/script-app/AGENTS.md | 9 +++++++++ templates/script-app/README.md | 7 +++++-- templates/script-app/README.zh-CN.md | 2 +- templates/script-app/bundle/assets/icon.svg | 14 +++++++++++--- 15 files changed, 72 insertions(+), 13 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2b6cb03f..23179ef3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -170,6 +170,16 @@ says who runs each one and when. sends only through the host's review, which RC2 has on macOS and Android. Check [docs/HOST-API-FAMILIES.md](docs/HOST-API-FAMILIES.md), and `runtime.describe` for optional methods, before writing a screen around a call. +- **Give every new app its own family icon.** Follow App Hub's + [icon authoring guide](https://github.com/OctoSense-org/OctoSense-App-Hub/blob/main/docs/ICONS.md#design-and-export-recommendations) + and the approved OctoSense family linked there. Use a 64-point square master, + keep foreground in the central 66%, use a restrained illustrated object and + ivory/ink materials with supporting accents. No baked platform corners, + circular mask or outer shadow. Replace the starter identity and review + 64/40/24 px, light/dark grounds and Android/macOS/iOS frames. Ship one + canonical bundle icon declared in `listing.json`; do not modify Makepad or + add store apps to OctoSense's built-in overlay. The gate checks file validity, + not visual conformity or device acceptance. - **No placeholder screenshots.** Capture the real app in a real state with `tools/octo shot`, then open each PNG and look at it. Never draw, generate, redraw from `/snap`, crop from another app, or copy a screenshot to make diff --git a/README.md b/README.md index efe6d21e..6d50e83d 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,10 @@ It is for hackathon contestants and other developers building an OctoSense app, and for the coding agents they work with. This repository was originally named *OctoScript-AppCard*. +Every new app also needs its own icon in the approved OctoSense illustrated +family. App Hub's [icon authoring guide](https://github.com/OctoSense-org/OctoSense-App-Hub/blob/main/docs/ICONS.md) owns the format, +export rules and review checklist; both app templates link to it. + ## Contents - [Hackathon: start here](#hackathon-start-here) diff --git a/README.zh-CN.md b/README.zh-CN.md index 3f1f913c..7afe88c5 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -14,6 +14,8 @@ App Flow 带着你（或编码 Agent）从一个想法（一段文字需求、 本仓库面向黑客松选手、其他 OctoSense 应用开发者，以及与他们协作的编码 Agent。本仓库最初名为 *OctoScript-AppCard*。 +每个新应用还需要符合已批准 OctoSense 插画家族的独立图标。格式、导出规则与评审清单由 App Hub 的[图标创作指南](https://github.com/OctoSense-org/OctoSense-App-Hub/blob/main/docs/ICONS.zh-CN.md)统一维护；两类应用模板均链接到该指南。 + ## 目录 - [黑客松：从这里开始](#黑客松从这里开始) diff --git a/docs/PUBLISHING.md b/docs/PUBLISHING.md index ae7fd72b..7f7e56e0 100644 --- a/docs/PUBLISHING.md +++ b/docs/PUBLISHING.md @@ -113,7 +113,11 @@ reviewer does not, and `tools/octo check` prints a note while they remain. - `publisher.privacy_policy_url`: an HTTPS URL that exists (**HUMAN**: the publisher owns this text). If the bundle ships `tools.json`, the app has an agent; say so in the listing and the privacy text. -- The icon: follow App Hub's [`docs/ICONS.md`](https://github.com/OctoSense-org/OctoSense-App-Hub/blob/main/docs/ICONS.md). +- The icon: replace the starter identity with this app's own object following + App Hub's [approved OctoSense format](https://github.com/OctoSense-org/OctoSense-App-Hub/blob/main/docs/ICONS.md#design-and-export-recommendations). + Use a 64-point square master, central 66% foreground and no baked platform + corners or outer shadow. Inspect 64/40/24 px and Android/macOS/iOS frames, + then verify the target shell; a gate pass alone does not check the design. The listing is part of the attested release: changing its text later takes a new version. @@ -505,7 +509,7 @@ under `store-data/my-test-notes/bundle`; **OPEN** does not show the app. [ ] tools/octo doctor -> hub and card-host [ok] [ ] manifest.json: id final (last segment not reserved), version NEW, capabilities minimal, every host declared [ ] listing.json: no placeholders; category/platforms/age_rating valid; privacy URL HTTPS and real (HUMAN) -[ ] icon at the path the listing names; readable at small size (App Hub docs/ICONS.md) +[ ] distinct app icon in the OctoSense family format at the listing path; central 66% safe area; no baked corners/shadow; 64/40/24 px and platform-frame review (App Hub docs/ICONS.md) [ ] tools/octo run "$B" --port 8141 --hidden --detach -> "admitted" line [ ] every interaction driven natively (click/type/tap) and its effect observed (screenshot or /snap or jail file) [ ] screenshots captured from the unsigned bundle with tools/octo shot, each opened and looked at; listed in listing.json diff --git a/docs/PUBLISHING.zh-CN.md b/docs/PUBLISHING.zh-CN.md index c8d44cb7..d14ea2f2 100644 --- a/docs/PUBLISHING.zh-CN.md +++ b/docs/PUBLISHING.zh-CN.md @@ -74,7 +74,7 @@ export B="$APP/bundle" - `platforms`：只写你实际运行过应用的平台（**HUMAN**：由人确认）。在 Mac 上用 `card-host` 运行，对应的是 `macos`。`tools/octo new` 写入的是你用 `--platform` 传入的平台；删掉没有测试过的平台。 - `category`、`age_rating` 等字段的取值见 App Hub 的 [商店信息](https://github.com/OctoSense-org/OctoSense-App-Hub/blob/main/docs/PUBLISHING.zh-CN.md#商店信息) 一节。 - `publisher.privacy_policy_url`：一个确实存在的 HTTPS URL（**HUMAN**：隐私政策的文字由发布者负责）。如果应用包附带 `tools.json`，应用就有 Agent，请在商店信息和隐私文本中写明。 -- 图标：遵循 App Hub 的 [`docs/ICONS.zh-CN.md`](https://github.com/OctoSense-org/OctoSense-App-Hub/blob/main/docs/ICONS.zh-CN.md)。 +- 图标：按照 App Hub 的[已批准 OctoSense 格式](https://github.com/OctoSense-org/OctoSense-App-Hub/blob/main/docs/ICONS.zh-CN.md#设计与导出建议)，用应用自己的物件替换模板身份。使用 64 点正方形原稿、中央 66% 前景，不预置平台圆角或外部阴影。检查 64/40/24 像素及 Android/macOS/iOS 外框，再在目标 Shell 中验证；仅通过准入检查不代表设计合格。 商店信息是带证明的 Release 的一部分：以后要修改其中的文字，就需要新版本。 @@ -315,7 +315,7 @@ App Hub 的独立商店 `appstore` 不需要 Shell 也能从同一个镜像安 [ ] tools/octo doctor -> hub 和 card-host 均为 [ok] [ ] manifest.json：id 已定稿（最后一段不是保留名），version 是新值，capabilities 最小化，每个主机都已声明 [ ] listing.json：没有占位内容；category/platforms/age_rating 取值合法；隐私政策 URL 是 HTTPS 且真实存在（HUMAN） -[ ] 图标位于商店信息指定的路径；小尺寸下清晰可辨（App Hub docs/ICONS.md） +[ ] 独立应用图标符合 OctoSense 家族格式且位于商店信息指定的路径；中央 66% 安全区域；不预置圆角/阴影；已检查 64/40/24 像素及平台外框（App Hub docs/ICONS.md） [ ] tools/octo run "$B" --port 8141 --hidden --detach -> 输出含 "admitted" 的一行 [ ] 每个交互都以原生方式操作过（点击、输入、轻触），并观察到效果（截图、/snap 或 jail 中的文件） [ ] 用 tools/octo shot 从未签名的应用包截图，每张都打开看过；都已列入 listing.json diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index 617aed71..ff1cfe50 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -189,6 +189,12 @@ platforms in the store, so before you publish, keep only the ones you tested, and have a person confirm the claim. Without the option, `new` stops with `tools/octo new: error: the following arguments are required: --platform`. +The copied icon is a format example, not your app's final identity. Replace it +with a distinct icon following App Hub's [OctoSense family format](https://github.com/OctoSense-org/OctoSense-App-Hub/blob/main/docs/ICONS.md#design-and-export-recommendations): +64-point square master, foreground in the central 66%, restrained illustrated +object, no baked platform corners or outer shadow. Inspect 64/40/24 px and +platform frames before submission; admission does not judge the design. + Pick the id with care: - It is 1 to 64 characters of `[a-z0-9.-]`, does not start with `.` and has diff --git a/docs/QUICKSTART.zh-CN.md b/docs/QUICKSTART.zh-CN.md index 315c2ad1..ad99efec 100644 --- a/docs/QUICKSTART.zh-CN.md +++ b/docs/QUICKSTART.zh-CN.md @@ -125,6 +125,8 @@ created …/my-app `--platform` 是必填项，你要在哪些平台上运行应用，就为每个平台写一次：`macos`、`windows`、`linux`、`android`、`ios`、`openharmony` 或 `web`。在 Mac 上用 `card-host` 运行，测试的是 `macos`。商店信息会在商店中声明这些平台，所以发布之前，只保留你实际测试过的平台，并由人确认这一声明。不加这个选项时，`new` 会停止，并输出 `tools/octo new: error: the following arguments are required: --platform`。 +复制的图标只演示格式，不是应用最终身份。按照 App Hub 的 [OctoSense 家族格式](https://github.com/OctoSense-org/OctoSense-App-Hub/blob/main/docs/ICONS.zh-CN.md#设计与导出建议)替换为独立图标：64 点正方形原稿、中央 66% 前景、克制的插画物件，不预置平台圆角或外部阴影。提交前检查 64/40/24 像素及平台外框；准入检查不评判设计。 + 请慎重选择 id： - 长度为 1 到 64 个字符，只能用 `[a-z0-9.-]`，不能以 `.` 开头，也不能包含 `..`。`new` 会检查这一点。 diff --git a/flows/image-to-card/FLOW.md b/flows/image-to-card/FLOW.md index cecc8caf..0a8d85d3 100644 --- a/flows/image-to-card/FLOW.md +++ b/flows/image-to-card/FLOW.md @@ -165,6 +165,13 @@ listing's https support and privacy links, which the gate allows.) The prefix in step 3 is the manifest's `artwork.source_prefix`; adjust the pattern if you changed it. +Create a distinct app icon before the hand-off, following App Hub's +[OctoSense icon format](https://github.com/OctoSense-org/OctoSense-App-Hub/blob/main/docs/ICONS.md#design-and-export-recommendations). +The extracted screen artwork is not automatically a launcher icon: author a +64-point square master, central 66% foreground and one illustrated object, +without baked platform corners or an outer shadow. Replace the starter icon, +declare its path in `listing.json`, and review 64/40/24 px plus platform frames. + Then run steps 2–9 of the [common hand-off](../README.md#every-flow-follows-the-same-contract), which sets `HUB_BIN` and `CARD_HOST_BIN`. Step 3 expects only the missing-screenshot diff --git a/flows/script-app/FLOW.md b/flows/script-app/FLOW.md index 41779baf..4787c16f 100644 --- a/flows/script-app/FLOW.md +++ b/flows/script-app/FLOW.md @@ -57,7 +57,7 @@ runs, and tie the final evidence to the tested source. | 7 | Drive every action in the brief with `curl -s "127.0.0.1:$P/click?x=&y=&wait=1"`, `curl -s "127.0.0.1:$P/t?t=…&wait=1"` and `curl -s "127.0.0.1:$P/k?k=down&c=ReturnKey"`. After each action, check a screenshot, `/snap?q=…` or the jail file under `$A/.local-state//`. Click a `TextInput` again before each `/t`, because a button click takes its focus. On a Retina Mac, divide screenshot pixels by 2 to get click points. | Each action's effect is observed and recorded (command + what changed). | no | | 8 | Test states: empty, error (for example network off or bad input), restart persistence (`curl -s 127.0.0.1:$P/quit`, rerun step 5). | Each state shows its intended message or data; stored data survives a restart when the brief says so. | no | | 9 | Give the author of `main.splash` (a person or a model) the reproduction, source revision, PNG and log findings; make one focused fix and repeat steps 4–8. Keep the failed runs in their own folder. | Every action the brief requires passes on the final source, in both the behavior checks and a direct visual review. Screenshots taken before the last edit do not count. | no | -| 10 | Edit `$B/listing.json`: subtitle, description (what it does, truthfully), category, keywords, the platforms you ran it on (`macos` for a `card-host` run on a Mac), release notes. Leave the publisher fields to the person if you do not know them. Replace `$B/assets/icon.svg`. | Listing parses (step 12) and says only what the app does. | Publisher name, support and privacy URL, platform claims: **HUMAN**. | +| 10 | Edit `$B/listing.json`: subtitle, description (what it does, truthfully), category, keywords, the platforms you ran it on (`macos` for a `card-host` run on a Mac), release notes. Leave the publisher fields to the person if you do not know them. Create a distinct `$B/assets/icon.svg` using the [OctoSense family format](https://github.com/OctoSense-org/OctoSense-App-Hub/blob/main/docs/ICONS.md#design-and-export-recommendations): 64-point square, central 66% foreground, restrained illustrated object, no baked platform corners or outer shadow. | Listing parses (step 12) and says only what the app does; the icon was inspected at 64/40/24 px, on light/dark grounds and with Android/macOS/iOS frames. A gate pass does not assess its design. | Publisher name, support and privacy URL, platform claims: **HUMAN**. | | 11 | Drive the unsigned app to its best real state; `tools/octo shot $P $B/screenshots/01-main.png` (add `02-…png` for more screens, at most 8, and list them in `listing.json`); open each; `curl -s 127.0.0.1:$P/quit`. | Each PNG is a real capture you looked at. | no | | 12 | `find $B -name .DS_Store -delete && tools/octo check $B` | ` — PASSED`, only the unsigned warning; no placeholder note, or only placeholders that wait for the person's publisher details. | no | | 13 | `mkdir -p $A/build $A/review && "$HUB" scan $B --packet $A/build/review.json`, then write answers to its questions into `$A/review/ANSWERS.md`. | Packet written; every question answered honestly: seven, or eight when the bundle ships `tools.json`, `AGENT.md` or skills. | no | diff --git a/templates/card-app/README.md b/templates/card-app/README.md index bb277b02..0eb0b49c 100644 --- a/templates/card-app/README.md +++ b/templates/card-app/README.md @@ -16,7 +16,11 @@ is the metadata scaffold for a card bundle: manifest, listing, icon and agent instructions. It has no entry file (`page.card`) and no screenshot, so the gate refuses it even after `hub stamp`, with `entry` and `listing` refusals. Add the flow's `page.card` and `kit/` and a real capture, and replace its placeholder -`platforms` with the platforms you tested. +`platforms` with the platforms you tested. Replace the starter icon with your +own identity following App Hub's [OctoSense icon format](https://github.com/OctoSense-org/OctoSense-App-Hub/blob/main/docs/ICONS.md#design-and-export-recommendations): +64-point square, central 66% foreground, restrained illustrated object and no +baked platform corners or outer shadow. The card's extracted screen artwork +does not replace this icon-authoring step. To use a font of your own, put the `.ttf` or `.otf` file in the bundle and name it in `font_src` with a bundle-relative path, such as diff --git a/templates/card-app/README.zh-CN.md b/templates/card-app/README.zh-CN.md index 3d147209..0cce5c84 100644 --- a/templates/card-app/README.zh-CN.md +++ b/templates/card-app/README.zh-CN.md @@ -6,7 +6,7 @@ **卡片应用**是用 L0（声明式卡片语言）编写的 `page.card`，加上它的 `page.data.json` 和 `kit/`，由宿主转换为控件。它是生成出来的，不是手写的：使用 [image-to-card 流程](../../flows/image-to-card/FLOW.md)（或者用 [Sketch 套件流程](../../flows/kits/sketch/FLOW.md)生成套件），然后按 [flows/README.zh-CN.md](../../flows/README.zh-CN.md#每个流程都遵循同一份约定) 中的统一交接步骤完成；应用包中放的是 `page.card` 和 `kit/`，而不是 `main.splash`。 -App Hub 的 [`templates/app/`](https://github.com/OctoSense-org/OctoSense-App-Hub/tree/main/templates/app) 是卡片应用包的元数据脚手架：清单、商店信息、图标和 Agent 说明。它没有入口文件（`page.card`），也没有截图，即使先运行 `hub stamp`，准入检查仍会报 `entry` 和 `listing` 两项拒绝。请加入流程生成的 `page.card`、`kit/` 和一张真实截图，并把占位的 `platforms` 换成你测试过的平台。 +App Hub 的 [`templates/app/`](https://github.com/OctoSense-org/OctoSense-App-Hub/tree/main/templates/app) 是卡片应用包的元数据脚手架：清单、商店信息、图标和 Agent 说明。它没有入口文件（`page.card`），也没有截图，即使先运行 `hub stamp`，准入检查仍会报 `entry` 和 `listing` 两项拒绝。请加入流程生成的 `page.card`、`kit/` 和一张真实截图，并把占位的 `platforms` 换成你测试过的平台。按照 App Hub 的 [OctoSense 图标格式](https://github.com/OctoSense-org/OctoSense-App-Hub/blob/main/docs/ICONS.zh-CN.md#设计与导出建议)，用自己的身份替换模板图标：64 点正方形、中央 66% 前景、克制的插画物件，不预置平台圆角或外部阴影。从卡片提取的界面素材不能替代这一步图标创作。 要使用自己的字体，把 `.ttf` 或 `.otf` 文件放进应用包，并在 `font_src` 中用相对于应用包的路径引用它，例如 `"font_src": "assets/Body.ttf"`。打包的字体计入 8 MiB 上限，所以较大的中日韩字体请只打包所需的子集。字体中没有的字形（例如中文）会改用 Makepad 内置的中文字体霞鹜文楷（LXGW WenKai）。套件可以引用的内置字体只有 `makepad_widgets:resources/Inter.ttf`、`makepad_widgets:resources/LXGWWenKaiRegular.ttf` 和 `makepad_widgets:resources/LXGWWenKaiBold.ttf`（[App Hub PUBLISHING § 字体](https://github.com/OctoSense-org/OctoSense-App-Hub/blob/main/docs/PUBLISHING.zh-CN.md#字体)）。请用 `MAKEPAD_SYSTEM_FONTS=0` 检查文字，这样系统字体就掩盖不了缺失的字形。 diff --git a/templates/script-app/AGENTS.md b/templates/script-app/AGENTS.md index 1697c1ef..5bc6cde6 100644 --- a/templates/script-app/AGENTS.md +++ b/templates/script-app/AGENTS.md @@ -57,6 +57,15 @@ Follow these rules: without an extension, 8 MiB at most. Plain `.txt`/`.md` license and attribution URLs are allowed; keep required notices. Agent guidance and structured resources retain their host/resource checks. +- Create a distinct app icon following App Hub's + [OctoSense icon format](https://github.com/OctoSense-org/OctoSense-App-Hub/blob/main/docs/ICONS.md#design-and-export-recommendations): + one dominant illustrated object, 64-point square master, foreground inside + the central 66% (10.88–53.12), ivory/ink materials and restrained accents. + Use a full-bleed ground without baked platform corners, circular crop or + outer shadow. Replace the starter identity; inspect 64/40/24 px on light/dark + grounds and Android/macOS/iOS frames. Declare one canonical bundle icon in + `listing.json`; do not patch Makepad or register this store app in the shell's + built-in override list. File admission is separate from visual review. - Capture screenshots from the unsigned bundle with `$OCTO shot`, and look at each one; never use a placeholder. - Restamp editable unsigned source after every edit (`$OCTO check` does it). diff --git a/templates/script-app/README.md b/templates/script-app/README.md index e61e5522..b4c8f87b 100644 --- a/templates/script-app/README.md +++ b/templates/script-app/README.md @@ -51,8 +51,11 @@ accident: - The publisher name, support URL and privacy-policy URL are placeholders, and so is the description's last sentence ("Replace this with …"). `tools/octo check` reports them. A person replaces the publisher fields. -- `assets/icon.svg` is the template's icon. Replace it with your own (App - Hub's [ICONS.md](https://github.com/OctoSense-org/OctoSense-App-Hub/blob/main/docs/ICONS.md)). +- `assets/icon.svg` demonstrates the approved OctoSense family format. Replace + its identity with this app's own illustrated object: 64-point square master, + central 66% foreground and restrained ivory/ink materials and accents, with + no baked platform corners or outer shadow. Review 64/40/24 px and platform + frames; App Hub's [ICONS.md](https://github.com/OctoSense-org/OctoSense-App-Hub/blob/main/docs/ICONS.md) owns the packaging and review rules. - `platforms` is empty, and the gate refuses an empty list (`listing names no platforms`). `tools/octo new` requires `--platform` and writes the platforms you pass; repeat the option for each one. Passing a diff --git a/templates/script-app/README.zh-CN.md b/templates/script-app/README.zh-CN.md index 97f11f0e..f0a6f273 100644 --- a/templates/script-app/README.zh-CN.md +++ b/templates/script-app/README.zh-CN.md @@ -39,7 +39,7 @@ script-app/ - `listing.json` 引用了 `screenshots/01-main.png`，但这个文件并不存在。在你用 `tools/octo shot` 截取真实截图之前，准入检查会拒绝这个应用包。不要放占位图片。 - 发布者名称、支持 URL 和隐私政策 URL 都是占位内容，描述的最后一句（“Replace this with …”）也是。`tools/octo check` 会提示它们；发布者字段由人来替换。 -- `assets/icon.svg` 是模板自带的图标，请换成你自己的（见 App Hub 的 [ICONS.zh-CN.md](https://github.com/OctoSense-org/OctoSense-App-Hub/blob/main/docs/ICONS.zh-CN.md)）。 +- `assets/icon.svg` 演示已批准的 OctoSense 家族格式。必须用应用自己的插画物件替换其身份：64 点正方形原稿、中央 66% 前景、克制的象牙白/墨色材质与点缀色，不预置平台圆角或外部阴影。检查 64/40/24 像素及平台外框；打包和评审规则由 App Hub 的 [ICONS.zh-CN.md](https://github.com/OctoSense-org/OctoSense-App-Hub/blob/main/docs/ICONS.zh-CN.md)规定。 - `platforms` 是空列表，准入检查会拒绝空列表（`listing names no platforms`）。`tools/octo new` 必须指定 `--platform`，并写入你传入的平台；每个平台写一次。传入平台只是声明，不是测试：发布之前，只保留你实际运行过的平台，并由人确认这一声明。在 Mac 上运行 `card-host` 测试的是 `macos`，不是 Android。 - 如果修改 id，它的最后一段不能是 App Hub 的保留名（`notes`、`weather`、`terminal` 等）。`tools/octo new` 创建应用时会拒绝保留名；之后改过的 id 若用了保留名，准入检查会拒绝。 diff --git a/templates/script-app/bundle/assets/icon.svg b/templates/script-app/bundle/assets/icon.svg index 4978331a..a804f4ff 100644 --- a/templates/script-app/bundle/assets/icon.svg +++ b/templates/script-app/bundle/assets/icon.svg @@ -1,4 +1,12 @@ - - - + + Starter icon — replace with this app's own identity + + + + + + + + +