From c4567c3eb4738c3092406366f71017a8d9548f9f Mon Sep 17 00:00:00 2001 From: ymote <151983+ymote@users.noreply.github.com> Date: Sat, 26 Sep 2026 15:16:56 -0700 Subject: [PATCH] Docs: repoint dead Octoscript-AppCard lab links; contestant pointer MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Hackathon docs audit. - README.md / README.zh-CN.md: add a "Building an OctoSense app?" note under the language switcher pointing app builders to the org profile's reading order; the clone command now uses the repository's current name (`OctoScript-website`). - Guides `design-to-app` and `splash-a2app` (en + cn): every `Octoscript-AppCard/…/lab/…` link was a 404 after the repository became OctoScript-App-Design-Flow and `lab/` became `flows/`. Repointed to `flows/image-to-card`, `flows/image-lib/MAPPING-RULES.md`, `flows/core/NATIVE-INSTRUMENT.md`, `flows/image-to-card/examples/aircon.flow.json`, `flows/kits/sketch`, and the camera example on the `feat/camera-app` branch (verified to exist with the GitHub contents API). The `tools/image-to-appcard-flow.sh plan --project … --manifest …` command in the guide still matches App-Design-Flow `main`. Not changed: the checked-in Octoscript snapshots under `src/content/upstream/octoscript/` (2026-09-19) still carry two dead `Octoscript-AppCard/docs/*.md` links; refreshing them means re-copying the language repository's docs and their hashes, which the README describes as a separate review step. Docs only. Co-Authored-By: Claude Opus 5.5 (1M context) --- README.md | 6 ++++-- README.zh-CN.md | 6 ++++-- src/content/guides/design-to-app.cn.md | 8 ++++---- src/content/guides/design-to-app.en.md | 8 ++++---- src/content/guides/splash-a2app.cn.md | 4 ++-- src/content/guides/splash-a2app.en.md | 4 ++-- 6 files changed, 20 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 3b73887..919a300 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ English | [简体中文](README.zh-CN.md) +> **Building an OctoSense app?** You do not need this repository: it is the source of the language website , useful background reading but not part of building, checking or publishing an app. Start from the [OctoSense organization profile](https://github.com/OctoSense-org)'s reading order: [OctoScript-App-Design-Flow `AGENTS.md`](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/AGENTS.md) → [`flows/README.md`](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/flows/README.md) → [`docs/QUICKSTART.md`](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/docs/QUICKSTART.md). + The independent bilingual website for [Octoscript](https://github.com/OctoSense-org/Octoscript), maintained in [OctoSense-org/Octoscript-website](https://github.com/OctoSense-org/Octoscript-website). English is at `/`; Simplified Chinese is at `/cn/`. The site covers the DSL's motivation, syntax, host authority, L0–L3 rendering layers, UI capability levels, Splash, native composition and agent tooling. Eight guides in each language explain the contracts on the page. A searchable component catalog and a real Makepad/WebAssembly lab accompany the design-to-component examples. Light and dark themes are supported. @@ -11,8 +13,8 @@ The site covers the DSL's motivation, syntax, host authority, L0–L3 rendering Only Node.js >= 22.12 and npm are needed to build the website. No sibling repository, Rust toolchain or remote content fetch is required. ```sh -git clone https://github.com/OctoSense-org/Octoscript-website.git -cd Octoscript-website +git clone https://github.com/OctoSense-org/OctoScript-website.git +cd OctoScript-website npm ci npm run dev ``` diff --git a/README.zh-CN.md b/README.zh-CN.md index a80182b..6644671 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -2,6 +2,8 @@ [English](README.md) | 简体中文 +> **要开发 OctoSense 应用？** 你不需要这个仓库：它是语言网站 的源码，可作为背景阅读，但不属于开发、检查或发布应用的步骤。请按 [OctoSense 组织主页](https://github.com/OctoSense-org)给出的顺序阅读：[OctoScript-App-Design-Flow `AGENTS.md`](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/AGENTS.md) → [`flows/README.md`](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/flows/README.md) → [`docs/QUICKSTART.md`](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/docs/QUICKSTART.md)。 + [Octoscript](https://github.com/OctoSense-org/Octoscript) 的独立双语网站，维护于 [OctoSense-org/Octoscript-website](https://github.com/OctoSense-org/Octoscript-website)。英文版位于 `/`，简体中文版位于 `/cn/`。 网站介绍这门 DSL 的设计动机、语法、宿主权限、L0–L3 渲染分层、UI 能力等级、Splash、原生组合以及 Agent 工具链。每种语言各有八篇指南，逐一讲解页面上的各项约定。设计到组件的示例配有可搜索的组件目录和一个真实的 Makepad/WebAssembly 实验室。支持浅色和深色主题。 @@ -11,8 +13,8 @@ 构建网站只需要 Node.js >= 22.12 和 npm。不需要任何同级仓库、Rust 工具链，也不会拉取远程内容。 ```sh -git clone https://github.com/OctoSense-org/Octoscript-website.git -cd Octoscript-website +git clone https://github.com/OctoSense-org/OctoScript-website.git +cd OctoScript-website npm ci npm run dev ``` diff --git a/src/content/guides/design-to-app.cn.md b/src/content/guides/design-to-app.cn.md index 8abaf0f..23c88cc 100644 --- a/src/content/guides/design-to-app.cn.md +++ b/src/content/guides/design-to-app.cn.md @@ -4,7 +4,7 @@ Agent 要做的是把视觉意图连接到真实组件，再验证结果。图 ## Flow 1：一张图集，生成一组服务界面 -[image-to-appcard-flow](https://github.com/OctoSense-org/Octoscript-AppCard/tree/main/lab/image-to-appcard-flow)以包含一组相关页面的图集为起点。生成前统一描述字体、视觉身份、数据和动作，并明确哪些是应用页面，哪些是桌面服务卡片。 +[image-to-card](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/tree/main/flows/image-to-card)以包含一组相关页面的图集为起点。生成前统一描述字体、视觉身份、数据和动作，并明确哪些是应用页面，哪些是桌面服务卡片。 1. **保留与测量。** 保存实际提交的 prompt、原始像素和真实尺寸，检查每个页面的裁切，保留图像坐标与原生画板坐标之间的变换。 2. **建立语义映射。** 结合设计意图、文字和几何测量与审查结果：标题成为 Label，动作成为控件，照片保持为图片。无法确定的区域需要先明确用途。 @@ -13,11 +13,11 @@ Agent 要做的是把视觉意图连接到真实组件，再验证结果。图 5. **检查与修复。** 分别检查组件结构、几何、交互和实际画面。当前原生仪器可直接查询和驱动应用，历史采集也使用过 Studio。 6. **沿同一路径发布界面。** 流程可导出 Makepad WebAssembly、字体与声明的图片素材供 Astro 网站使用，再用真实组件边界测试浏览器交互。 -Runner 负责编排阶段，并不自行调用图像模型，也不会从像素自动推导完整应用。Agent 与明确的设计约定负责语义决策。详见[映射规则](https://github.com/OctoSense-org/Octoscript-AppCard/blob/main/lab/image-to-appcard/MAPPING-RULES.md)与[当前原生仪器流程](https://github.com/OctoSense-org/Octoscript-AppCard/blob/main/lab/core/NATIVE-INSTRUMENT.md)。 +Runner 负责编排阶段，并不自行调用图像模型，也不会从像素自动推导完整应用。Agent 与明确的设计约定负责语义决策。详见[映射规则](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/flows/image-lib/MAPPING-RULES.md)与[当前原生仪器流程](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/flows/core/NATIVE-INSTRUMENT.md)。 ## 例证：空调送达后预约安装 -[空调流程清单](https://github.com/OctoSense-org/Octoscript-AppCard/blob/main/lab/image-to-appcard-flow/examples/aircon.flow.json)描述一个 12 场景服务示例，从购买、物流延伸到安装、日历协调与支付。页面转换由服务状态驱动，而非按动画时间自动前进。 +[空调流程清单](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/flows/image-to-card/examples/aircon.flow.json)描述一个 12 场景服务示例，从购买、物流延伸到安装、日历协调与支付。页面转换由服务状态驱动，而非按动画时间自动前进。 `aircon-05` 是送达后的安装邀约，它的映射体现了关键决策： @@ -43,7 +43,7 @@ bash tools/image-to-appcard-flow.sh plan \ ## Flow 2：从 Sketch 文档到可复用组件 kit -[sketch-to-appcard](https://github.com/OctoSense-org/Octoscript-AppCard/tree/main/lab/sketch-to-appcard)从结构化设计资料开始：画板、分组、symbol、文字、字体、mask 与稳定 source ID。这条路线能够保留平面截图已经丢失的信息。 +[kits/sketch](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/tree/main/flows/kits/sketch)从结构化设计资料开始：画板、分组、symbol、文字、字体、mask 与稳定 source ID。这条路线能够保留平面截图已经丢失的信息。 ```text Sketch 文档与 source ID diff --git a/src/content/guides/design-to-app.en.md b/src/content/guides/design-to-app.en.md index 0be2e95..8732e07 100644 --- a/src/content/guides/design-to-app.en.md +++ b/src/content/guides/design-to-app.en.md @@ -4,7 +4,7 @@ The agent's job is to connect visual intent to real components, then verify the ## Flow 1: an image atlas becomes a service experience -[image-to-appcard-flow](https://github.com/OctoSense-org/Octoscript-AppCard/tree/main/lab/image-to-appcard-flow) starts with one atlas containing related screens. Shared typography, identity, data and actions are described together before generation. An application surface and a desktop service card are explicitly different owners. +[image-to-card](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/tree/main/flows/image-to-card) starts with one atlas containing related screens. Shared typography, identity, data and actions are described together before generation. An application surface and a desktop service card are explicitly different owners. 1. **Preserve and measure.** Save the submitted prompt, original pixels and actual dimensions. Validate scene crops and retain the transforms between image pixels and the native artboard. 2. **Map semantic roles.** Combine authored intent, measured text/geometry and review. A headline becomes a Label, an action becomes a control, and a photo remains artwork. Unknown regions need a decision before compilation. @@ -13,11 +13,11 @@ The agent's job is to connect visual intent to real components, then verify the 5. **Inspect and repair.** Compare widget structure, geometry, interaction and rendered appearance separately. The current native instrument can inspect and drive an app directly; historical captures also used Studio. 6. **Package the same rendering path.** The flow can export a Makepad WebAssembly package, fonts and declared artwork for the Astro site, then test real native widget bounds in the browser. -The runner orchestrates these stages. It does not call an image model or automatically infer a complete application from pixels. The agent and authored contracts provide the semantic decisions. See the [mapping rules](https://github.com/OctoSense-org/Octoscript-AppCard/blob/main/lab/image-to-appcard/MAPPING-RULES.md) and [current native instrument](https://github.com/OctoSense-org/Octoscript-AppCard/blob/main/lab/core/NATIVE-INSTRUMENT.md). +The runner orchestrates these stages. It does not call an image model or automatically infer a complete application from pixels. The agent and authored contracts provide the semantic decisions. See the [mapping rules](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/flows/image-lib/MAPPING-RULES.md) and [current native instrument](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/flows/core/NATIVE-INSTRUMENT.md). ## Worked example: booking an air-conditioner installation -The [aircon flow manifest](https://github.com/OctoSense-org/Octoscript-AppCard/blob/main/lab/image-to-appcard-flow/examples/aircon.flow.json) describes a 12-scene service example. It moves from shopping and delivery to installation, calendar coordination and payment. Those transitions come from service state, not an animation timeline. +The [aircon flow manifest](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/flows/image-to-card/examples/aircon.flow.json) describes a 12-scene service example. It moves from shopping and delivery to installation, calendar coordination and payment. Those transitions come from service state, not an animation timeline. Scene `aircon-05` offers installation after delivery. Its source-to-component mapping illustrates the key decisions: @@ -43,7 +43,7 @@ bash tools/image-to-appcard-flow.sh plan \ ## Flow 2: a Sketch document becomes a reusable kit -[sketch-to-appcard](https://github.com/OctoSense-org/Octoscript-AppCard/tree/main/lab/sketch-to-appcard) starts from structured design data: artboards, groups, symbols, text, fonts, masks and stable source IDs. It can preserve information that a flat screenshot has lost. +[kits/sketch](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/tree/main/flows/kits/sketch) starts from structured design data: artboards, groups, symbols, text, fonts, masks and stable source IDs. It can preserve information that a flat screenshot has lost. ```text Sketch document and source IDs diff --git a/src/content/guides/splash-a2app.cn.md b/src/content/guides/splash-a2app.cn.md index f88b3fb..718a6d2 100644 --- a/src/content/guides/splash-a2app.cn.md +++ b/src/content/guides/splash-a2app.cn.md @@ -87,7 +87,7 @@ Agent → L0/L1 → 检查后的 UiNode → 可复用 kit → Splash → Makepad ## Rust 复用的例证：一个相机，两种宿主 -[相机项目](https://github.com/OctoSense-org/Octoscript-AppCard/tree/feat/camera-app/apps/camera)拆成 `logic/`、`native/` 和 `oh/`。两个宿主的 Cargo 清单都依赖 `octosense-camera-logic`。 +[相机项目](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/tree/feat/camera-app/apps/camera)拆成 `logic/`、`native/` 和 `oh/`。两个宿主的 Cargo 清单都依赖 `octosense-camera-logic`。 ```text octosense-camera-logic @@ -113,6 +113,6 @@ Studio 为人类开发者提供可视化工作流；Makepad 同时把检查与 Agent 查询最新矩形，操作目标组件，等待一帧，再检查状态和像素，将发现的问题定位回源码。Tweaker 的编辑不会自动写入源文件；Agent 需要把确认后的变更写回，再构建验证。 -这里的 headless 指不依赖 Studio GUI，且在支持的平台上可以隐藏原生窗口。视觉验证仍使用真实 GPU 后端，模拟渲染不构成原生画面证明。仪器覆盖范围取决于后端，控制端口属于显式启用仪器的开发构建。见 [app remote control](https://github.com/OctoSense-org/makepad/blob/octoscript/docs/agents/app-remote.md)与 [AppCard 当前仪器流程](https://github.com/OctoSense-org/Octoscript-AppCard/blob/main/lab/core/NATIVE-INSTRUMENT.md)。 +这里的 headless 指不依赖 Studio GUI，且在支持的平台上可以隐藏原生窗口。视觉验证仍使用真实 GPU 后端，模拟渲染不构成原生画面证明。仪器覆盖范围取决于后端，控制端口属于显式启用仪器的开发构建。见 [app remote control](https://github.com/OctoSense-org/makepad/blob/octoscript/docs/agents/app-remote.md)与 [AppCard 当前仪器流程](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/flows/core/NATIVE-INSTRUMENT.md)。 这就形成了 A2App 闭环：源码可检查、组件可定位、动作可测试、视觉修改可追溯。[设计到应用的两条流程](design-to-app.cn.md)将它应用到生成图片和 Sketch 文档。 diff --git a/src/content/guides/splash-a2app.en.md b/src/content/guides/splash-a2app.en.md index 1b0cc09..ef23a17 100644 --- a/src/content/guides/splash-a2app.en.md +++ b/src/content/guides/splash-a2app.en.md @@ -87,7 +87,7 @@ There are concrete integration points: [Makepad Video](https://github.com/OctoSe ## Reuse Rust logic: one camera, two hosts -The [camera example](https://github.com/OctoSense-org/Octoscript-AppCard/tree/feat/camera-app/apps/camera) separates `logic/`, `native/` and `oh/`. Both host manifests depend on `octosense-camera-logic`. +The [camera example](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/tree/feat/camera-app/apps/camera) separates `logic/`, `native/` and `oh/`. Both host manifests depend on `octosense-camera-logic`. ```text octosense-camera-logic @@ -113,6 +113,6 @@ Studio exposes a visual workflow to a human developer. Makepad also puts inspect An agent asks for current bounds, exercises a control, waits for a frame, checks the state and pixels, and repairs the relevant source. Tweaker edits do not automatically persist to source; the agent applies the reviewed changes and rebuilds to verify them. -“Headless” in this development loop means that the Studio GUI is unnecessary and a supported native window can be hidden. Visual verification still uses the real GPU backend; a simulated renderer does not prove native appearance. Instrument coverage differs by backend, and the port belongs to an explicitly instrumented development build. See [app remote control](https://github.com/OctoSense-org/makepad/blob/octoscript/docs/agents/app-remote.md) and [the current AppCard instrument workflow](https://github.com/OctoSense-org/Octoscript-AppCard/blob/main/lab/core/NATIVE-INSTRUMENT.md). +“Headless” in this development loop means that the Studio GUI is unnecessary and a supported native window can be hidden. Visual verification still uses the real GPU backend; a simulated renderer does not prove native appearance. Instrument coverage differs by backend, and the port belongs to an explicitly instrumented development build. See [app remote control](https://github.com/OctoSense-org/makepad/blob/octoscript/docs/agents/app-remote.md) and [the current AppCard instrument workflow](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/flows/core/NATIVE-INSTRUMENT.md). That closes the A2App loop: source is inspectable, widgets are addressable, actions are testable and visual changes can be traced back to a component. [The design-to-app flows](design-to-app.en.md) apply it to generated images and Sketch documents.