From c54de04d154d97aa4adcf0a3012fd220f59b3edc Mon Sep 17 00:00:00 2001 From: ymote <151983+ymote@users.noreply.github.com> Date: Fri, 2 Oct 2026 10:01:18 -0700 Subject: [PATCH] docs: connect app hosting to agents and rendering --- AGENTS.md | 25 ++++ README.md | 8 +- README.zh-CN.md | 8 +- scripts/doc-links.mjs | 2 +- src/components/AgentTools.astro | 2 + src/components/DesignFlows.astro | 14 +-- src/components/NativeHosts.astro | 2 +- src/components/RenderingLayers.astro | 4 +- src/components/SplashOverview.astro | 2 +- src/content/guides/component-library.cn.md | 2 + src/content/guides/component-library.en.md | 2 + src/content/guides/design-to-app.cn.md | 10 +- src/content/guides/design-to-app.en.md | 10 +- src/content/guides/language-profiles.cn.md | 2 + src/content/guides/language-profiles.en.md | 2 + src/content/guides/octosense-apps.cn.md | 107 ++++++++++++++++++ src/content/guides/octosense-apps.en.md | 107 ++++++++++++++++++ src/content/guides/splash-a2app.cn.md | 20 +++- src/content/guides/splash-a2app.en.md | 18 ++- .../docs/makepad-ui-compatibility.md | 10 +- .../docs/makepad-ui-compatibility.zh-CN.md | 10 +- .../upstream/octoscript/docs/positioning.md | 15 +-- .../octoscript/docs/positioning.zh-CN.md | 10 +- src/content/upstream/octoscript/sources.json | 12 +- src/data/content.ts | 4 +- src/data/docs.ts | 6 +- tests/story.spec.ts | 2 +- 27 files changed, 355 insertions(+), 61 deletions(-) create mode 100644 AGENTS.md create mode 100644 src/content/guides/octosense-apps.cn.md create mode 100644 src/content/guides/octosense-apps.en.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..1fd242f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,25 @@ +# Working on the OctoScript website + +Read [README.md](README.md) and the bilingual app guides under +`src/content/guides/octosense-apps.*.md` before changing architecture copy. + +- This repository owns website content and a pinned demonstration package. + It does not build the production OctoSense shell or run its app agents. +- Keep English and Chinese claims aligned. Add a guide to `src/data/docs.ts`, + both locale lists in `src/data/content.ts`, and `scripts/doc-links.mjs`. +- Distinguish workflow source, contained Splash apps, L0 card realization, + renderer nodes and native mounting. Explain new terms at their first use. +- Trace permissions and tools to their host implementation. A language + capability, bundle declaration or UI demo does not establish a runtime + service, account access or cross-app grant. State current integration gaps. +- Preserve source provenance: corrections to checked-in upstream snapshots + require updated hashes and an explicit correction record in `sources.json`. + The consuming app's runtime and Cargo locks select its actual implementation. +- Keep browser sample state and historical design examples labelled. Preserve + demo behavior and the prebuilt WASM package unless the task changes them. +- For content/navigation changes run `npm run test:unit`, `npm run build`, + relevant existing Playwright checks, and `git diff --check`. Include a new + guide in the existing guide-navigation test loop when adding a route. + Native build/device commands documented here need separate validation. +- Changes to `main` trigger the Pages deployment workflow. Prepare a PR for + review; do not merge or deploy as part of a documentation task unless asked. diff --git a/README.md b/README.md index 919a300..f405b8f 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,11 @@ 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 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. +The site covers the DSL's motivation, syntax, host authority, L0–L3 rendering layers, UI capability levels, Splash, native composition and agent tooling. Nine 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. + +The [app and agent guide](src/content/guides/octosense-apps.en.md) follows native Rust, Splash and L0 apps into OctoSense, including human/system conversations, app data, tool grants and Tokio tasks. Contributor instructions are in [AGENTS.md](AGENTS.md). ## Run locally @@ -41,7 +43,7 @@ The build checks Astro/TypeScript and writes the static site to `dist/`. Playwri - `src/styles/`: typography, responsive layout and light/dark theme tokens. - `public/examples/provenance.json`: image source hashes and the archived design review's status. -All imports resolve within this repository. Edit website content here. To refresh an upstream snapshot, review the corresponding language-repository document, copy it into the same snapshot path, and update its manifest hash and provenance. Changes in the language repository do not silently change the website. +All imports resolve within this repository. Edit website content here. To refresh an upstream snapshot, review the corresponding language-repository document, copy it into the same snapshot path, and update its manifest hash and provenance. Website-local architecture corrections are recorded separately in `sources.json`, retaining the original snapshot base and date. Changes in the language repository do not silently change the website. The design inspector shows recorded mappings and native captures; it does not run a vision model. The archived review still records remaining visual differences. Purchased Sketch assets are not redistributed. The school, delivery and travel cards use browser-only sample data; their approvals do not run workflows or external actions. diff --git a/README.zh-CN.md b/README.zh-CN.md index 6644671..351b78c 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -4,9 +4,11 @@ > **要开发 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/`。 +[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 实验室。支持浅色和深色主题。 +网站介绍这门 DSL 的设计动机、语法、宿主权限、L0–L3 渲染分层、UI 能力等级、Splash、原生组合以及 Agent 工具链。每种语言各有九篇指南，逐一讲解页面上的各项约定。设计到组件的示例配有可搜索的组件目录和一个真实的 Makepad/WebAssembly 实验室。支持浅色和深色主题。 + +[应用与 Agent 指南](src/content/guides/octosense-apps.cn.md)追踪原生 Rust、Splash 和 L0 应用如何进入 OctoSense，并说明用户／系统对话、应用数据、工具授权与 Tokio 任务。协作规则见 [AGENTS.md](AGENTS.md)。 ## 本地运行 @@ -41,7 +43,7 @@ npm run test:e2e - `src/styles/`：字体排印、响应式布局以及浅色/深色主题 token。 - `public/examples/provenance.json`：图片来源哈希以及已归档设计评审的状态。 -所有导入都在本仓库内解析。网站内容请在这里编辑。若要刷新某个上游快照，请先审阅语言仓库中对应的文档，把它复制到相同的快照路径，并更新清单中的哈希和来源记录。语言仓库的变更不会在不知不觉中改变网站。 +所有导入都在本仓库内解析。网站内容请在这里编辑。若要刷新某个上游快照，请先审阅语言仓库中对应的文档，把它复制到相同的快照路径，并更新清单中的哈希和来源记录。网站本地的架构修正单独记录在 `sources.json`，保留最初快照的基准提交与日期。语言仓库的变更不会在不知不觉中改变网站。 设计查看器展示的是录制好的映射和原生截图；它不运行视觉模型。已归档的评审仍记录着尚存的视觉差异。购买的 Sketch 素材不会再分发。学校、快递和出行卡片使用仅在浏览器中存在的示例数据；其中的审批不会运行工作流，也不会触发外部操作。 diff --git a/scripts/doc-links.mjs b/scripts/doc-links.mjs index 01756a0..03928de 100644 --- a/scripts/doc-links.mjs +++ b/scripts/doc-links.mjs @@ -4,7 +4,7 @@ import { fileURLToPath } from 'node:url'; const root = fileURLToPath(new URL('../', import.meta.url)); const upstream = 'src/content/upstream/octoscript/'; const routes = { - ...Object.fromEntries(['why-octoscript', 'splash-a2app', 'design-to-app', 'language-profiles', 'component-library'].flatMap(slug => ['en', 'cn'].map(locale => [`src/content/guides/${slug}.${locale}.md`, `${locale === 'cn' ? '/cn' : ''}/docs/${slug}/`]))), + ...Object.fromEntries(['octosense-apps', 'why-octoscript', 'splash-a2app', 'design-to-app', 'language-profiles', 'component-library'].flatMap(slug => ['en', 'cn'].map(locale => [`src/content/guides/${slug}.${locale}.md`, `${locale === 'cn' ? '/cn' : ''}/docs/${slug}/`]))), ...Object.fromEntries(Object.entries({ 'README.md': '/', 'README.zh-CN.md': '/cn/', 'docs/README.md': '/docs/', 'docs/README.zh-CN.md': '/cn/docs/', diff --git a/src/components/AgentTools.astro b/src/components/AgentTools.astro index 2dabaa6..c65682b 100644 --- a/src/components/AgentTools.astro +++ b/src/components/AgentTools.astro @@ -20,5 +20,7 @@ const rows = cn ? [
06 / THE APP IS THE WORKBENCH

{cn ? '把开发工具放进应用。\n让 Agent 直接参与。' : 'Put the tools in the app.\nLet the agent work directly.'}

{cn ? '从面向人类的 Studio，到应用内可通过 socket 访问的检查和控制原语。Agent 无需操作 IDE 窗口，就能理解和驱动正在运行的 UI。' : 'From Studio for human developers to inspection and control primitives inside the app, reachable over a socket. An agent can understand and drive the running UI without operating an IDE window.'}

app --remote127.0.0.1:PORT / HTTP
    {rows.map(([endpoint,title,body],i) =>
  1. 0{i+1}

    {title}

    {body}

    {endpoint}
    2. )}
{cn ? '观察 → 操作 → 验证 → 修正 → 再构建' : 'OBSERVE → ACT → VERIFY → REPAIR → REBUILD'}

{cn ? '开发实例显式启用仪器。这里的 headless 指不依赖 Studio GUI，视觉验证仍使用真实 GPU；各平台的检查与采集能力以宿主实现为准。' : 'Instrumentation is enabled explicitly for development. Headless means no Studio GUI is needed; visual checks still use the real GPU, with inspection and capture support determined by each host.'}

+

{cn ? '这里的 Agent 帮助开发和测试应用。运行时应用 Agent 则由 OctoSense 和 octos 管理，使用用户允许的账户工作区、工具与对话路由。独立 card-host 没有注册 Agent 服务。' : 'These instruments serve a coding agent. Runtime app agents are managed by OctoSense and octos, with permitted account workspaces, tools and conversation routes. Standalone card-host registers no agent services.'}

+ {cn ? '运行应用并追踪它的 Agent' : 'Run an app and follow its agent'} {cn ? '阅读语言、仪器与 A2App 的完整关系' : 'Read how language, instruments and A2App fit together'} diff --git a/src/components/DesignFlows.astro b/src/components/DesignFlows.astro index eaf46a4..070f917 100644 --- a/src/components/DesignFlows.astro +++ b/src/components/DesignFlows.astro @@ -5,11 +5,11 @@ interface Props { locale: Locale; } const { locale } = Astro.props; const cn = locale === 'cn'; const flows = cn ? [ - {id:'image', title:'图集 → 服务 App', name:'image-to-appcard-flow', intro:'一次设计一组相关页面，把视觉、数据和动作一起组织为真实的服务体验。', steps:[['测量来源','保留 prompt、图集、页面裁切与坐标变换。'],['映射语义','把文字、控件、数值图表与图片分别映射到组件。'],['连接服务','提取服务卡片，绑定 reducer、状态、授权与操作。'],['验证与发布','检查组件和实际画面，再输出原生或 WASM 包。']]}, - {id:'sketch',title:'Sketch → 组件 kit', name:'sketch-to-appcard', intro:'利用设计文档的层级、symbol 与 source ID，把完整设计系列转为可复用的原生组件。',steps:[['读取设计','解析画板、分组、字体、mask 和稳定的来源 ID。'],['原生组合','文字成为 Label，控件保留交互，图片保留来源。'],['检查与修复','用组件树、布局、真实输入与原生帧验证结果。'],['提升为 kit','抽取共享定义、token 和绑定，让新页面复用组件。']]}, + {id:'image', title:'图集 → 服务 App', name:'image-to-card', intro:'一次设计一组相关页面，把视觉、数据和动作一起组织为真实的服务体验。', steps:[['测量来源','保留 prompt、图集、页面裁切与坐标变换。'],['映射语义','把文字、控件、数值图表与图片分别映射到组件。'],['连接服务','提取服务卡片，绑定 reducer、状态、授权与操作。'],['验证与发布','检查组件和实际画面，再输出原生或 WASM 包。']]}, + {id:'sketch',title:'Sketch → 组件 kit', name:'kits/sketch', intro:'利用设计文档的层级、symbol 与 source ID，把完整设计系列转为可复用的原生组件。',steps:[['读取设计','解析画板、分组、字体、mask 和稳定的来源 ID。'],['原生组合','文字成为 Label，控件保留交互，图片保留来源。'],['检查与修复','用组件树、布局、真实输入与原生帧验证结果。'],['提升为 kit','抽取共享定义、token 和绑定，让新页面复用组件。']]}, ] : [ - {id:'image',title:'Atlas → service app',name:'image-to-appcard-flow',intro:'Design related screens together, then connect their visuals, data and actions into a working service experience.',steps:[['Measure the source','Preserve the prompt, atlas, scene crops and coordinate transforms.'],['Map semantics','Map text, controls, numerical charts and artwork to appropriate components.'],['Bind the service','Extract service cards and connect reducers, state, grants and actions.'],['Verify and package','Inspect widgets and real frames, then export native or WASM packages.']]}, - {id:'sketch',title:'Sketch → component kit',name:'sketch-to-appcard',intro:'Use document hierarchy, symbols and source IDs to turn a design family into reusable native components.',steps:[['Read the design','Parse artboards, groups, fonts, masks and stable source IDs.'],['Compose natively','Keep text as labels, controls interactive and artwork traceable.'],['Inspect and repair','Verify trees, layout, real input and native frames.'],['Promote to a kit','Extract shared definitions, tokens and bindings for new pages.']]}, + {id:'image',title:'Atlas → service app',name:'image-to-card',intro:'Design related screens together, then connect their visuals, data and actions into a working service experience.',steps:[['Measure the source','Preserve the prompt, atlas, scene crops and coordinate transforms.'],['Map semantics','Map text, controls, numerical charts and artwork to appropriate components.'],['Bind the service','Extract service cards and connect reducers, state, grants and actions.'],['Verify and package','Inspect widgets and real frames, then export native or WASM packages.']]}, + {id:'sketch',title:'Sketch → component kit',name:'kits/sketch',intro:'Use document hierarchy, symbols and source IDs to turn a design family into reusable native components.',steps:[['Read the design','Parse artboards, groups, fonts, masks and stable source IDs.'],['Compose natively','Keep text as labels, controls interactive and artwork traceable.'],['Inspect and repair','Verify trees, layout, real input and native frames.'],['Promote to a kit','Extract shared definitions, tokens and bindings for new pages.']]}, ]; const mappings = [ {id:'choose_time',type:'KitButton',event:'installation.open_slots',rect:[9.2,71.89,37.99,6.66],label:cn?'选择时间':'Choose a time',detail:cn?'来源按钮成为 KitButton，独立保留控件与文字；动作交给安装服务处理。':'The source button becomes a KitButton with separate control and label children; the installation service handles its action.'}, @@ -22,7 +22,7 @@ const mappings = [
{flows.map((flow,i)=>)}
{flows.map((flow,i)=>)}
-
{cn?'阅读两条完整流程与映射规则':'Read both flows and their mapping rules'}{cn?'体验空调服务流程':'Try the aircon service flow'}
+
{cn?'阅读两条完整流程与映射规则':'Read both flows and their mapping rules'}{cn?'体验空调服务示例':'Try the aircon service example'}
diff --git a/src/components/NativeHosts.astro b/src/components/NativeHosts.astro index db4f51b..6e7becc 100644 --- a/src/components/NativeHosts.astro +++ b/src/components/NativeHosts.astro @@ -20,7 +20,7 @@ const platforms = cn ? [
05 / ONE LOGIC, MULTIPLE HOSTS

{cn ? '共享 Rust 逻辑。\n选择界面的呈现方式。' : 'Share the Rust logic.\nChoose the UI host.'}

{cn ? 'Makepad 绘制组件与平台系统控件都可以成为 UI 的目标，也可以在同一页面内组合。语言、逻辑和渲染宿主各司其职。' : 'Makepad-drawn widgets and platform controls are both UI targets. A host can compose them in one page while keeping language, logic and rendering responsibilities clear.'}

{platforms.map(([name,tag,body]) =>
{tag}

{name}

{body}

)}
-

{cn ? '一个页面，一致的交互。' : 'One page, coordinated interaction.'}

{cn ? '宿主协调布局矩形、裁剪、层级、焦点、键盘与生命周期。例如让原生预览负责相机画面，Makepad 负责自定义覆盖层，平台控件提供系统输入体验。' : 'The host coordinates rectangles, clipping, layering, focus, keyboard and lifecycle. A native preview can carry camera frames, Makepad can draw custom overlays, and platform controls can supply system input.'}

{cn ? '已有例证：相机的两个宿主。' : 'In the repository: two camera hosts.'}

{cn ? 'camera/native 和 camera/oh 都依赖 octosense-camera-logic。状态机与场景生成共享，前者使用 Makepad kit，后者通过 ArkUI C API 创建系统节点。' : 'camera/native and camera/oh both depend on octosense-camera-logic. They share the state machine and scene generation, rendering through Makepad kits or ArkUI C API nodes.'}

{cn ? '查看共享逻辑与双宿主实现' : 'Inspect the shared logic and hosts'}
+

{cn ? '一个页面，一致的交互。' : 'One page, coordinated interaction.'}

{cn ? '宿主协调布局矩形、裁剪、层级、焦点、键盘与生命周期。例如让原生预览负责相机画面，Makepad 负责自定义覆盖层，平台控件提供系统输入体验。' : 'The host coordinates rectangles, clipping, layering, focus, keyboard and lifecycle. A native preview can carry camera frames, Makepad can draw custom overlays, and platform controls can supply system input.'}

{cn ? '历史例证：相机的两个宿主。' : 'Historical example: two camera hosts.'}

{cn ? '开发分支中的 camera/native 和 camera/oh 都依赖 octosense-camera-logic；这不是当前 Camera 应用包的架构。状态机与场景生成共享，前者使用 Makepad kit，后者通过 ArkUI C API 创建系统节点。' : 'In the recorded development branch, camera/native and camera/oh depend on octosense-camera-logic. This is not the current Camera bundle architecture. They share the state machine and scene generation, rendering through Makepad kits or ArkUI C API nodes.'}

{cn ? '查看共享逻辑与双宿主实现' : 'Inspect the shared logic and hosts'}

{cn ? 'Makepad 原生绘制组件与平台系统控件是两种后端；同页组合需要具体适配，并不自动将任意 shader 转成系统控件。' : 'Makepad widgets and platform system controls are different backends. Same-page composition needs host adapters; arbitrary shaders do not become system controls automatically.'}

{cn ? '查看平台映射与原生组合细节' : 'Read the platform mapping and composition details'} diff --git a/src/components/RenderingLayers.astro b/src/components/RenderingLayers.astro index 9d8f317..68600ac 100644 --- a/src/components/RenderingLayers.astro +++ b/src/components/RenderingLayers.astro @@ -6,12 +6,12 @@ const cn=locale==='cn'; const layers=cn?[ ['L0','检查与展开','卡片 + 宿主数据 → UI 树','验证数据来源、状态、key 与展开预算。'], ['L1','组件库映射','UI 树 + kit → 组件调用','保留角色、参数、主题和来源 ID。'], - ['L2','VM 与节点翻译','组件调用 → UiNode → Splash','共享 VM 求值，生成后端组件描述。'], + ['L2','VM 与节点翻译','组件调用 → UiNode → Splash','源码求值得到 UiNode，再由 Rust 生成组件描述。'], ['L3','挂载与交互','组件描述 → 像素 + 事件','实际布局、绘制、点击与状态回传。'], ]:[ ['L0','Check & realize','Card + host data → UI tree','Validate origins, state, keys and traversal budgets.'], ['L1','Lower through a kit','UI tree + kit → component calls','Preserve roles, parameters, themes and source IDs.'], - ['L2','Evaluate & translate','Calls → UiNode → Splash','The shared VM produces backend widget descriptions.'], + ['L2','Evaluate & translate','Calls → UiNode → Splash','Evaluate source into UiNode; Rust emits widget descriptions.'], ['L3','Mount & interact','Widgets → pixels + events','Real layout, rendering, input and state feedback.'], ]; --- diff --git a/src/components/SplashOverview.astro b/src/components/SplashOverview.astro index 001c896..5da41ee 100644 --- a/src/components/SplashOverview.astro +++ b/src/components/SplashOverview.astro @@ -22,6 +22,6 @@ const code = `View {\n width: Fill\n height: Fit\n flow: Down\n spac
03 / MEET SPLASH

{cn ? '一种语言，连接\n界面、行为与绘制。' : 'One language for\nUI, behavior and drawing.'}

{cn ? '认识 Rik Arends 与 Makepad 项目中的 Splash：可实时编辑的 UI 语言，也是 Octoscript 的 VM 基础。' : 'Meet Splash from Rik Arends and the Makepad project: a live-editable UI language and the VM foundation of Octoscript.'}

component.splashUI HOST
{code}
:={cn ? '命名子组件' : 'Named child'}:{cn ? '设置属性' : 'Property'}{'{ }'}{cn ? '组合实例' : 'Composition'}

{cn ? 'UI 片段：需要已注册 Label、Button 等组件的宿主。' : 'UI excerpt: requires a host with Label, Button and other widget bindings.'}

    {features.map(([title,body],i) =>
  1. 0{i+1}

    {title}

    {body}

    2. )}
-

{cn ? 'UI 复用 Splash，工作流有自己的边界。' : 'Reuse Splash for UI. Keep workflow admission explicit.'}

{cn ? '直接编写 Splash，或将经过检查的 L0 / L1 转为 UiNode，再经过主题与组件 kit 降低到 Splash。共享 makepad-script 实现，不等于共享所有宿主能力。' : 'Author Splash directly, or check L0 / L1, realize UiNodes and lower them through a theme and component kit. Sharing makepad-script does not share every host capability.'}

+

{cn ? 'UI 复用 Splash，工作流有自己的边界。' : 'Reuse Splash for UI. Keep workflow admission explicit.'}

{cn ? '直接编写 Splash，或先把 L0 / L1 实例化为卡片树，再经 kit 转换和求值得到渲染器 UiNode，最后生成组件源码。共享 makepad-script 实现，不等于共享宿主能力。' : 'Author Splash directly, or realize an L0 / L1 card tree, lower it through a kit, then evaluate renderer UiNodes and emit widget source. Sharing makepad-script does not share host permissions.'}

{cn ? '深入了解 Splash 语法、Rust 与 UI 宿主' : 'Explore Splash syntax, Rust and UI hosts'}
diff --git a/src/content/guides/component-library.cn.md b/src/content/guides/component-library.cn.md index 2ff1235..7db8121 100644 --- a/src/content/guides/component-library.cn.md +++ b/src/content/guides/component-library.cn.md @@ -43,6 +43,8 @@ Flutter kit 覆盖 Material 3、Cupertino Gallery、Form App、Date Planner、Co 演示按需加载，以免阅读文档时下载整个渲染器。需要浏览器支持 WebAssembly 与 WebGL；启动失败会显示重试入口。canvas 的辅助技术支持不同于网页表单，目录、语法和说明始终保留为可访问的 HTML 文本。 +此处 Rust 组件状态与应用数据库、Agent 记忆分开。[应用与 Agent 导读](octosense-apps.cn.md)说明这些存储及其访问规则。 + ## 维护与来源 [语言与四层链路](language-profiles.cn.md)定义生成边界；[像素到组件的流程](design-to-app.cn.md)展示实际来源映射。组件依据 [Material 词汇表](https://github.com/OctoSense-org/Octoscript-Makepad/blob/main/components/material/screens/WIDGETS.md)、[Flutter 示例说明](https://github.com/OctoSense-org/Octoscript-Makepad/blob/main/components/flutter/README.md) 和 [原生 kit 契约](https://github.com/OctoSense-org/Octoscript-Makepad/blob/main/docs/native-l0-kits.md)整理；演示的固定源码版本与构建摘要可在演示面板下载。 diff --git a/src/content/guides/component-library.en.md b/src/content/guides/component-library.en.md index e7aeef1..20b4d38 100644 --- a/src/content/guides/component-library.en.md +++ b/src/content/guides/component-library.en.md @@ -41,6 +41,8 @@ A registered kit has four pieces: `tokens.json` contains measured colors, fonts, The demo draws its content and controls through Rust → WebAssembly → Makepad WebGL. The surrounding page only selects examples, sets a theme and reports actual runtime state. Choose delivery speed, toggle preferences and confirm in Material; navigate subpages and color/type examples in Flutter. State lives only in the current demo instance and resets on reload. +This Rust widget state is separate from an app database or agent memory. [The app and agent guide](octosense-apps.en.md) explains those stores and their access rules. + The renderer loads on demand. WebAssembly and WebGL are required; a failed start exposes a retry action. Canvas assistive-technology support differs from HTML forms, so the catalog, syntax and instructions remain accessible HTML. ## Maintenance and sources diff --git a/src/content/guides/design-to-app.cn.md b/src/content/guides/design-to-app.cn.md index 23c88cc..f6476ad 100644 --- a/src/content/guides/design-to-app.cn.md +++ b/src/content/guides/design-to-app.cn.md @@ -17,7 +17,7 @@ Runner 负责编排阶段，并不自行调用图像模型，也不会从像素 ## 例证：空调送达后预约安装 -[空调流程清单](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/flows/image-to-card/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 场景服务示例，从购买、物流延伸到安装、日历协调与支付。页面转换由示例服务状态驱动。`installation.open_slots` 等名称是示例服务约定，不是预装的跨应用权限；网站不会实际预约或付款。 `aircon-05` 是送达后的安装邀约，它的映射体现了关键决策： @@ -41,6 +41,14 @@ bash tools/image-to-appcard-flow.sh plan \ `plan` 只打印阶段和参数，不执行它们。仓库指南说明准备、编译、采证和打包步骤；源图、服务实现及原生构建环境都是明确输入。 +## 默认 Runner 实际执行什么 + +默认阶段是 `intake,semantic,compile,bundle,service-test`：保留输入、检查已编写的场景映射、编译卡片／数据／kit、导出包，再运行 manifest 明确列出的服务检查。语义检查前，场景契约和映射必须已存在。准备、原生截图、视觉审查与网站打包需要另外选择对应阶段；默认列表不隐含这些步骤。 + +Runner 在修改文件前解析计划，并记录命令、日志和退出状态。第一个失败的命令会停止后续执行，`run.json` 记录尚未运行的阶段。导出成功后仍需应用 manifest、商店列表和发布交接：截图并人工审查、重新盖摘要并检查、由密钥持有者签名，以及批准准确的提交版本。完整顺序见 [Design Flow 源码导读](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/218b25d2460d64f843932f67d419467618464fb9/docs/CODE-WALKTHROUGH.md)。 + +从文字需求生成 `main.splash` 应用时，使用独立的 [script-app 流程](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/tree/main/flows/script-app)。[运行应用，再追踪它的 Agent](octosense-apps.cn.md)说明本地宿主与 Shell 集成。 + ## Flow 2：从 Sketch 文档到可复用组件 kit [kits/sketch](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/tree/main/flows/kits/sketch)从结构化设计资料开始：画板、分组、symbol、文字、字体、mask 与稳定 source ID。这条路线能够保留平面截图已经丢失的信息。 diff --git a/src/content/guides/design-to-app.en.md b/src/content/guides/design-to-app.en.md index 8732e07..589a79e 100644 --- a/src/content/guides/design-to-app.en.md +++ b/src/content/guides/design-to-app.en.md @@ -17,7 +17,7 @@ The runner orchestrates these stages. It does not call an image model or automat ## Worked example: booking an air-conditioner installation -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. +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 the example's service state. Names such as `installation.open_slots` are example service contracts, not preinstalled cross-app permissions. The website does not book appointments or make payments. Scene `aircon-05` offers installation after delivery. Its source-to-component mapping illustrates the key decisions: @@ -41,6 +41,14 @@ bash tools/image-to-appcard-flow.sh plan \ `plan` prints the stages and arguments without executing them. The repository guide describes preparation, compilation, evidence and packaging. The source image, service implementation and native build environment remain explicit inputs. +## What the default runner actually does + +The default stages are `intake,semantic,compile,bundle,service-test`: preserve the inputs, check the authored scene mappings, compile card/data/kit files, export the bundle, then run the manifest's explicit service checks. Scene contracts and mappings must already exist before semantic checking. Preparation, native capture, visual review and website packaging require their own selected stages; they are not implied by the default list. + +The runner resolves the plan before mutation and records commands, logs and exit results. The first failed command stops subsequent execution; `run.json` records what remains unrun. A successful export still needs an app manifest, listing and the publishing hand-off: capture and review screenshots, restamp and check, have the key holder sign, and obtain approval for the exact submission. Follow the [Design Flow code walkthrough](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/218b25d2460d64f843932f67d419467618464fb9/docs/CODE-WALKTHROUGH.md) for that sequence. + +For a text brief and a `main.splash` app, use the separate [script-app flow](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/tree/main/flows/script-app). [Run an app, then follow its agent](octosense-apps.en.md) explains the local host and shell integration. + ## Flow 2: a Sketch document becomes a reusable kit [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. diff --git a/src/content/guides/language-profiles.cn.md b/src/content/guides/language-profiles.cn.md index 8791603..b7c5d52 100644 --- a/src/content/guides/language-profiles.cn.md +++ b/src/content/guides/language-profiles.cn.md @@ -15,6 +15,8 @@ 例如，像素中的“预约时间”按钮先获得 `source_id`；L0 绑定标题与事件；L1 选择 `KitButton` 及主题；L2 构造实际子节点；L3 点击原生 Button，宿主收到 `installation.open_slots`。四层都通过才说明这个按钮能用；只检查源码或比对一张截图都不足以证明交互完成。 +[当前渲染路径](octosense-apps.cn.md)区分 L0 实例化树与渲染器 `UiNode`，并说明哪个宿主负责求值和挂载最终组件。这些层次不会创建应用 Agent，也不会授予服务访问权。 + ## UI 能力等级：另一个独立维度 卡片头部的 `# level:` 说的是允许使用的**语言能力**，与上面的实现层分开理解。 diff --git a/src/content/guides/language-profiles.en.md b/src/content/guides/language-profiles.en.md index 0a03942..12e31be 100644 --- a/src/content/guides/language-profiles.en.md +++ b/src/content/guides/language-profiles.en.md @@ -15,6 +15,8 @@ In design-flow reviews, these labels name the rendering pipeline. They do not re For an appointment button, L0 binds copy and its event to a source ID; L1 selects `KitButton` and a theme; L2 builds its children; L3 activates the native Button and the host receives `installation.open_slots`. Source validation and a matching picture alone do not establish working interaction. +The [current renderer path](octosense-apps.en.md#from-card-source-to-native-widgets) distinguishes the realized L0 tree from the renderer's `UiNode`, and explains which host evaluates and mounts the final widgets. These layers do not create an app agent or grant service access. + ## UI capability levels are a separate axis The `# level:` header describes the language admitted by the UI checker. diff --git a/src/content/guides/octosense-apps.cn.md b/src/content/guides/octosense-apps.cn.md new file mode 100644 index 0000000..a9e660d --- /dev/null +++ b/src/content/guides/octosense-apps.cn.md @@ -0,0 +1,107 @@ +# 运行应用，再追踪它的 Agent + +OctoScript 描述工作流与界面。OctoSense 托管应用，并连接到 Rust Agent 内核 **octos**。本指南先把应用从源码带到运行中的 UI，再追踪一条用户请求如何经过应用 Agent。 + +帮助编写应用的开发 Agent，与回答应用用户的运行时 Agent，是两个角色。开发仪器检查运行中的 UI；应用 Agent 使用产品宿主授予的工具和数据。 + +## 先确定要运行什么 + +| 产物 | 运行时 | 从哪里开始 | +| --- | --- | --- | +| 工作流 `.octoscript` | OctoScript 有界工作流运行时，使用已注册工具和宿主签发的授权 | [工作流示例](why-octoscript.cn.md) | +| 原生 Rust 应用 | 编译后的 `AppModule`，包含 Rust 事件处理与 Makepad 组件 | [OctoSense 构建与启动说明](https://github.com/OctoSense-org/OctoSense/blob/main/README.md) | +| 受限容器中的 `main.splash` 应用 | 在 Splash UI 宿主内求值的 Makepad Script | Design Flow 的 `tools/octo run` 与 App Hub 的 `card-host` | +| L0 `page.card`、数据与 kit | OctoScript 检查并实例化卡片；OctoScript-Makepad 转换和渲染 | 同一个卡片宿主，同时提供声明的数据与 kit 文件 | + +`tools/octo` 是 Python 开发命令，负责启动 Rust 卡片宿主；它不是 `octos` Agent 内核。原生 Rust 应用也可以嵌入 Splash 视图，同时把服务保留在编译后的 Rust 代码里。 + +## 本地运行一个容器应用 + +按 [Design Flow 原生工作区说明](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/docs/NATIVE-WORKSPACE.md)准备仓库和构建环境。运行时锁文件选择彼此兼容的源码版本。 + +**命令验证状态：**下列原生构建与启动命令未在本次网站检查中执行。 + +在 Design Flow 仓库中执行： + +```sh +python3 tools/setup-native.py +python3 tools/setup-native.py --check +``` + +进入同级 App Hub 仓库： + +```sh +cargo build --release -p octosense-card-host -p octosense-app-hub +``` + +回到 Design Flow，选择尚不存在的目标目录与空闲端口： + +```sh +tools/octo doctor +tools/octo new /tmp/octosense-notes --id walkthrough.notes --name "Notes" +tools/octo run /tmp/octosense-notes/bundle --hidden --detach --port 8141 +tools/octo shot 8141 /tmp/octosense-notes/first-frame.png +curl -s http://127.0.0.1:8141/quit +``` + +`run` 的应用包路径是位置参数。使用 `--detach` 时，新进程提供 UI 和已渲染帧后命令返回；不加这个参数，终端会等到应用退出。开发运行默认会更新 manifest 的摘要，因此请使用未签名的工作副本。 + +这条路径检查解析、渲染，以及宿主限制下的存储和网络策略。独立 `card-host` **没有注册宿主服务，也没有 Agent 运行时**，无法完成 `mail.*`、`model.complete` 或 `octos.*` 请求。要在完整 Shell 中测试已安装应用，请按[本地签名目录演练](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/docs/PUBLISHING.md#4-rehearse-the-store-path-locally)操作。桌面、Android Home 与 ROM 命令属于 OctoSense 仓库；ROM 构建还包含操作系统。 + +## 从卡片源码到原生组件 + +**实例化（realization）**检查卡片声明的数据与状态，并展开组件，得到完整的卡片树。**转换（lowering）**把这棵树变成组件 kit 和渲染器需要的更具体的源码。 + +```text +page.card + 宿主数据 + 实例状态 + → OctoScript L0 检查与实例化 + → 组件 kit 转换 + → 受检查的求值，得到渲染器 UiNode 数据 + → Makepad 组件源码 + → 原生宿主挂载 View 并处理事件 +``` + +L0 实例化树与渲染器的 `UiNode` 是不同的数据表示。原生 kit 加载 `native//kit.json`，走保留设计几何的路径；其他 kit 组装调色板和组件源码。两条路径都由宿主提供数据、注册组件、处理动作，并决定何时重新渲染。 + +在框架的目录与预览宿主中，最终组件源码在应用的主 `makepad-script` VM 上求值，得到的 `View` 赋给 `Splash.view`。App Hub 的容器脚本宿主有自己的准入与隔离环境设置。共享 VM 实现并不意味着每个应用共享实例、绑定或权限。[渲染器源码导读](https://github.com/OctoSense-org/OctoScript-Makepad/blob/fb29b6b1cb6e16f38d99a8aef60431a9565dfd59/docs/architecture-walkthrough.md)说明了具体调用和不同的求值预算。 + +## 追踪“总结我保存的笔记” + +假设应用已把笔记存进向 Agent 开放的账户目录，用户也在 OctoSense 中允许了该 Agent。**Peer** 是应用 Agent 的身份；**session** 保存一段对话及其记录；**turn** 是一次请求以及为回答它而执行的模型和工具工作。 + +1. 用户在桌面打开 **Ask <app>** 并发送请求。Shell 选择应用 Peer 及其用户会话。应用也可以通过 Shell 的 `octos.*` 服务提供自己的聊天界面。 +2. Shell 以用户身份发起 turn。Octos 检查是否允许执行、记录归属，再启动模型处理。模型可以请求工具；模型写出的文字不会自行授予权限。 +3. 在 Unix 上，用户同意且账户工作区可用时，Shell 可提供有界的 `files.list`、`files.read` 和 `files.search` 工具。它们读取开放的账户目录。位于应用存储根目录的记录，以及该目录之外的宿主服务密钥，不会自动变成可读数据。 +4. 工具结果回到模型，模型据此写出答案。事件与完成状态返回最初提出请求的用户会话。 + +应用 UI 的数据存储、对话记录与 Agent 记忆是不同的存储。其他位置的结构化记录，需要由已实现的工具读取和解释；仅随应用包提供工具声明，不能让操作自动变成可执行代码。 + +系统 Agent 可以使用应用 Peer 的实际标识委派同一请求。系统请求走 Peer 的系统会话；用户聊天可以使用另一条共享有限上下文的 session。两者各自保存对话记录。用户答案返回该会话的事件接收方。两种来源都可以在 **peer blackboard** 中留下标记了来源的协作结果；用户来源的结果不会自动唤醒系统 Agent。系统 Agent 汇总自己委派请求的结果。 + +## 调用其他应用或系统 Agent + +跨应用调用需要工具所有者的可共享声明、调用方授权、宿主准入，以及实际可执行的路由。工具策略要求确认时，还需经过批准。App Hub 默认提供的工具列表不包含任意名称，例如 `mail.send`；把它加入 `agent.tools` 会被默认准入拒绝。 + +系统到应用的委派已经实现。容器应用不会继承系统 Agent 的工具，也不会自动得到任意应用到系统的委派能力。它只能使用宿主实际提供并授权的协作路由。 + +| 声明或功能 | 当前集成边界 | +| --- | --- | +| 第一方 `implemented_by: "host-service"` 工具 | 按宿主策略，通过已注册的 Rust 服务执行。 | +| 商店应用的 `implemented_by: "app"` 工具 | 当前 Shell 没有这些声明的脚本分发器；打开应用 UI 也不会安装一个。 | +| 应用包 `AGENT.md` 与 skills | App Hub 会验证，但当前 Shell 不把内容安装到应用 Peer。仓库里的 `AGENTS.md` 则用于指导开发 Agent。 | +| 模型 `needs`、后台触发器与调度元数据 | 验证声明不会补齐尚未接入的运行时选择与调度行为。 | +| L0 `sys.chat` / `ChatEntry` | Shell 的运行时支持，但当前 Design Flow 创作版本不支持。编写这类卡片前，先检查 [AI 服务与运行时兼容性](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/docs/AI-SERVICES.md#ai-written-text-and-in-card-chat-model-copy-syschat)。 | + +## Tokio 在哪里 + +Peer 可以在没有任务运行时继续存在。处理请求时，Octos 先创建停在**启动屏障**后的 turn 编排任务，再检查准入、记录归属并发送接受响应，最后释放屏障；拒绝请求时则中止等待中的任务。编排任务随后创建 Agent 处理任务。宿主工具调用通过单次结果通道等待；等待期间 Tokio 可以调度其他工作。实际的数据库或网络操作在哪里执行，由宿主决定。 + +连接传输与事件转发还会增加其他任务。卡片／VM 求值和 UI 事件遵循 UI 宿主的调度；一个 Peer 不等于一个 Tokio 任务，也不等于一个 UI VM。Shell 的应用 Peer 共享内核运行时。桌面与 Android 通常使用子进程，OpenHarmony 使用嵌入式运行时，iOS 当前没有集成内核。[octos 请求与任务导读](https://github.com/octos-org/octos/blob/82900bf149d3a53016c1c1492ffc075d2d4fb0ed/docs/octosense-integration-walkthrough.md)进一步解释准入、取消与应答匹配。 + +## 继续阅读源码 + +- [OctoSense](https://github.com/OctoSense-org/OctoSense/blob/61c668279a7c38a0f8056134d8d29e42ed715806/docs/architecture-walkthrough.md)：原生应用、桌面／Home／ROM、对话入口与 Shell broker。 +- [App Hub](https://github.com/OctoSense-org/OctoSense-App-Hub/blob/19bb52d402e80e89e085dea989615e3ec612d359/docs/CODE-WALKTHROUGH.md)：准入、安装、容器存储与宿主服务请求。 +- [Design Flow](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/218b25d2460d64f843932f67d419467618464fb9/docs/CODE-WALKTHROUGH.md)：CLI 行为、图像／卡片阶段与发布交接。 + +排查实际应用时，请阅读消费方 Cargo 和运行时锁文件选定的源码版本。本站预构建 WASM 实验室有独立的版本与构建记录，只使用本地演示状态，不连接生产 OctoSense 应用 Agent 或账户。 diff --git a/src/content/guides/octosense-apps.en.md b/src/content/guides/octosense-apps.en.md new file mode 100644 index 0000000..cb15674 --- /dev/null +++ b/src/content/guides/octosense-apps.en.md @@ -0,0 +1,107 @@ +# Run an app, then follow its agent + +OctoScript describes workflows and interfaces. OctoSense hosts apps and connects them to **octos**, the Rust agent kernel. This guide follows an app from its source to a running UI, then follows a person's request through its app agent. + +The coding agent that helps write an app and the app agent that answers its users are separate roles. Development instruments inspect a running UI; app agents use the tools and data granted by the product host. + +## Choose what you are running + +| Artifact | Runtime | Start here | +| --- | --- | --- | +| Workflow `.octoscript` | OctoScript's bounded workflow runtime, with registered tools and host-issued grants | The [workflow example](why-octoscript.en.md#what-happens-around-one-call) | +| Native Rust app | A compiled `AppModule` with Rust event handlers and Makepad widgets | [OctoSense build and run instructions](https://github.com/OctoSense-org/OctoSense/blob/main/README.md) | +| Contained `main.splash` app | Makepad Script evaluated inside a Splash UI host | Design Flow's `tools/octo run` and App Hub's `card-host` | +| L0 `page.card` with data and a kit | OctoScript checks and realizes the card; OctoScript-Makepad lowers and renders it | The same card host, with the declared data and kit files | + +`tools/octo` is a Python development command. It starts the Rust card host; it is not the `octos` agent kernel. A native Rust app can embed a Splash view while keeping its services in compiled Rust. + +## Run a contained app locally + +Use [Design Flow's native workspace setup](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/docs/NATIVE-WORKSPACE.md) to prepare the repositories and build prerequisites. Its runtime lock selects compatible source revisions. + +**Recipe status:** these native build and launch commands have not been executed as part of the website checks. + +From the Design Flow checkout: + +```sh +python3 tools/setup-native.py +python3 tools/setup-native.py --check +``` + +From the App Hub sibling: + +```sh +cargo build --release -p octosense-card-host -p octosense-app-hub +``` + +Return to Design Flow and use a new destination directory and a free port: + +```sh +tools/octo doctor +tools/octo new /tmp/octosense-notes --id walkthrough.notes --name "Notes" +tools/octo run /tmp/octosense-notes/bundle --hidden --detach --port 8141 +tools/octo shot 8141 /tmp/octosense-notes/first-frame.png +curl -s http://127.0.0.1:8141/quit +``` + +`run` takes the bundle path as a positional argument. With `--detach`, it returns after the new process exposes its UI and a rendered frame; without it, the terminal waits for the app to exit. The default development run stamps the manifest, so use an unsigned working copy. + +This tests parsing, rendering and the host's contained storage and network policy. Standalone `card-host` registers **no host services and no agent runtime**. It cannot complete `mail.*`, `model.complete` or `octos.*` requests. Use the [local signed-catalog rehearsal](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/docs/PUBLISHING.md#4-rehearse-the-store-path-locally) to test an installed app inside the full shell. Desktop, Android Home and ROM commands belong to the OctoSense repository; a ROM build also includes the operating system. + +## From card source to native widgets + +**Realization** checks the card's declared data and state and expands its components into a complete tree. **Lowering** converts that tree into the more detailed source needed by a component kit and renderer. + +```text +page.card + host data + instance state + → OctoScript L0 check and realization + → component-kit lowering + → checked evaluation into renderer UiNode data + → Makepad widget source + → native host mounts a View and handles events +``` + +The realized L0 tree and the renderer's `UiNode` are different representations. Native kits load `native//kit.json` and use the measured-design path; other kits assemble palette and component source. In either case the host supplies data, registers widgets, handles actions and decides when to render again. + +In the framework's catalog and preview hosts, the final widget source is evaluated on the app's main `makepad-script` VM and its `View` is assigned to `Splash.view`. App Hub's contained script host has its own admission and isolate setup. Sharing the VM implementation does not give every app the same instance, bindings or permissions. Follow the [renderer code walkthrough](https://github.com/OctoSense-org/OctoScript-Makepad/blob/fb29b6b1cb6e16f38d99a8aef60431a9565dfd59/docs/architecture-walkthrough.md) for the exact calls and the different evaluation budgets. + +## Follow “Summarize my saved notes” + +Assume the app has stored notes in its exposed account folder and the person has allowed its agent in OctoSense. A **peer** is that app agent's identity; a **session** holds one conversation and its transcript; a **turn** is one request and the model/tool work needed to answer it. + +1. The person opens desktop **Ask <app>** and sends the request. The shell selects the app peer and its human conversation. An app can also provide a chat surface through the shell's `octos.*` service. +2. The shell starts a turn with the person's origin. Octos admits the turn, records ownership and starts model processing. The model can request a tool; its text does not authorize access. +3. On Unix, the shell can expose bounded `files.list`, `files.read` and `files.search` tools when the person has consented and an account workspace is available. These tools read the exposed account folder. Records at the app's storage root, and host-service secrets outside that folder, are not automatically readable. +4. The tool result returns to the model, which writes an answer. Events and completion go back to the human conversation that submitted the request. + +A UI's data store, the conversation transcript and the agent's memory are separate stores. For structured records elsewhere, the app needs an implemented tool that interprets those records; shipping a tool declaration alone does not make that operation executable. + +The system agent can delegate the same request using the app peer's actual identifier. Its request uses the peer's system conversation; human chat can use a separate session that shares bounded recent context. Each keeps its own transcript. Human answers go to that conversation's event receiver. Both origins can leave labelled results in the **peer blackboard**, the coordination record; a human-origin result does not automatically wake the system agent. The system agent gathers the results of its delegated requests. + +## Calling another app or the system agent + +Cross-app calls require an owner's shareable tool declaration, the caller's grant, host admission and an executable route. Approval applies where the tool's policy requires it. App Hub's default offered-tool list excludes arbitrary names such as `mail.send`; adding that name to `agent.tools` fails default admission. + +System-to-app delegation is implemented. A contained app does not inherit the system agent's tools or gain unrestricted app-to-system delegation. It can use only coordination routes the host actually supplies and authorizes. + +| Declaration or feature | Current integration boundary | +| --- | --- | +| First-party `implemented_by: "host-service"` tools | Run through registered Rust services under the host's policy. | +| Store app `implemented_by: "app"` tools | The current shell has no script dispatcher for these declarations. Opening the UI does not install one. | +| Bundle `AGENT.md` and skills | App Hub validates them; the current shell does not install their contents into app peers. Repository `AGENTS.md` instead instructs the coding agent. | +| Model `needs`, background triggers and scheduling metadata | Validation does not supply the missing runtime selection or scheduling behavior. | +| L0 `sys.chat` / `ChatEntry` | Supported by the shell's runtime, but absent from the current Design Flow authoring pin. Check [AI services and runtime compatibility](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/docs/AI-SERVICES.md#ai-written-text-and-in-card-chat-model-copy-syschat) before authoring such cards. | + +## Where Tokio fits + +A peer can exist while no task is running. When handling a request, Octos spawns turn orchestration behind a **start barrier**. It checks admission, records ownership and sends acceptance before releasing the barrier; a refusal aborts the waiting task. Orchestration then spawns the agent processing task. A host-tool call waits on a one-result channel while Tokio can schedule other work; the host decides where the actual database or network operation executes. + +Transport and event forwarding add other tasks. Card/VM evaluation and UI events follow the UI host's scheduling; a peer is neither one Tokio task nor one UI VM. The shell shares a kernel runtime across app peers. Desktop and Android normally run it as a child process, OpenHarmony embeds it, and iOS currently has no integrated kernel. Follow the [octos request and task walkthrough](https://github.com/octos-org/octos/blob/82900bf149d3a53016c1c1492ffc075d2d4fb0ed/docs/octosense-integration-walkthrough.md) for admission, cancellation and reply correlation. + +## Continue in the source repositories + +- [OctoSense](https://github.com/OctoSense-org/OctoSense/blob/61c668279a7c38a0f8056134d8d29e42ed715806/docs/architecture-walkthrough.md): native apps, desktop/Home/ROM, conversation entry points and the shell broker. +- [App Hub](https://github.com/OctoSense-org/OctoSense-App-Hub/blob/19bb52d402e80e89e085dea989615e3ec612d359/docs/CODE-WALKTHROUGH.md): admission, installation, contained storage and host-service requests. +- [Design Flow](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/218b25d2460d64f843932f67d419467618464fb9/docs/CODE-WALKTHROUGH.md): CLI behavior, image/card stages and publication hand-off. + +Read the source revision selected by the consuming app's Cargo and runtime locks. The website's prebuilt WASM lab has its own pinned build receipt and uses local demo state; it does not connect to a production OctoSense app agent or account. diff --git a/src/content/guides/splash-a2app.cn.md b/src/content/guides/splash-a2app.cn.md index 718a6d2..6769379 100644 --- a/src/content/guides/splash-a2app.cn.md +++ b/src/content/guides/splash-a2app.cn.md @@ -56,12 +56,13 @@ Splash 可以用 `pixel: fn() { ... }` 等 shader 定义描述 GPU 绘制。实 **直接写 Splash：** 可信 UI 宿主安装组件并执行其 DSL，保留 Makepad 完整的组合与样式能力。 -**生成 L0／L1：** 先检查较窄的 UI 约定，实例化语义 `UiNode`，套用主题／组件 kit，再转换为 Splash。L0 实例化无需 VM；L1 增加有界纯算术。kit 求值与最终 Splash 挂载可以使用共享的 `makepad-script` 实现。 +**生成 L0／L1：** 先检查较窄的 UI 约定，实例化语义卡片树，再通过组件 kit 转换。受检查的求值得到渲染器 `UiNode`，翻译后生成 Makepad 组件源码。L0 实例化无需 VM；L1 增加有界纯算术。kit 求值与最终 Splash 挂载可以使用共享的 `makepad-script` 实现。 ```text -Agent → L0/L1 → 检查后的 UiNode → 可复用 kit → Splash → Makepad 组件 - ↑ - 直接编写 Splash UI +L0/L1 + 数据 → 实例化卡片树 → kit 转换 → 渲染器 UiNode + → Makepad 组件源码 → 宿主挂载原生组件 + +直接编写 Splash → 容器 UI 宿主 → 原生组件 ``` 这样既复用了 Splash 语言及组件生态，也给生成式卡片建立明确的准入边界。组件声明不会被误送进独立的工作流检查器。详见 [Makepad 集成](../upstream/octoscript/docs/makepad-ui-compatibility.zh-CN.md)。 @@ -85,9 +86,11 @@ Agent → L0/L1 → 检查后的 UiNode → 可复用 kit → Splash → Makepad 已有接入点包括：[Video 组件](https://github.com/OctoSense-org/makepad/blob/octoscript/widgets/src/video.rs)挂载原生相机预览；[iOS 后端](https://github.com/OctoSense-org/makepad/blob/octoscript/platform/src/os/apple/ios/ios.rs)管理预览生命周期；[Android bridge](https://github.com/OctoSense-org/makepad/blob/octoscript/platform/src/os/linux/android/android_jni.rs)连接 GL 表面上的原生 composer。它们展示了具体的混合组合能力；任意控件之间的层级、裁剪和事件兼容仍需对应适配。 -## Rust 复用的例证：一个相机，两种宿主 +## 历史例证：一个相机，两种宿主 + +[相机项目](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/tree/641353aff8021f9f74e2d8ed259c1d4fc269721e/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`。 +这是开发分支中记录的双宿主例证，不是当前 OctoSense Camera 应用包的架构。 ```text octosense-camera-logic @@ -116,3 +119,8 @@ 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-App-Design-Flow/blob/main/flows/core/NATIVE-INSTRUMENT.md)。 这就形成了 A2App 闭环：源码可检查、组件可定位、动作可测试、视觉修改可追溯。[设计到应用的两条流程](design-to-app.cn.md)将它应用到生成图片和 Sketch 文档。 + + +## 运行应用并与它的 Agent 对话 + +上述仪器用于开发。[运行应用，再追踪它的 Agent](octosense-apps.cn.md)说明产品运行时：独立 card-host 与完整 Shell、原生 Rust 与容器应用、用户／系统对话、数据访问，以及宿主授权的工具。 diff --git a/src/content/guides/splash-a2app.en.md b/src/content/guides/splash-a2app.en.md index ef23a17..2cbf88a 100644 --- a/src/content/guides/splash-a2app.en.md +++ b/src/content/guides/splash-a2app.en.md @@ -56,12 +56,13 @@ These facilities are provided by the Makepad UI host. A shader-capable UI langua **Direct Splash:** a trusted UI host installs widgets and evaluates their DSL, retaining Makepad's full composition and styling model. -**Generated L0/L1:** the host first checks a narrower UI contract, realizes semantic `UiNode`s, applies a theme/component kit, and lowers the result to Splash. L0 realization does not need a VM; L1 adds bounded pure arithmetic. Kit evaluation and final Splash mounting can use the shared `makepad-script` implementation. +**Generated L0/L1:** the host first checks a narrower UI contract, realizes a semantic card tree, then lowers it through a component kit. Checked evaluation produces renderer `UiNode`s; translation produces Makepad widget source. L0 realization does not need a VM; L1 adds bounded pure arithmetic. Kit evaluation and final Splash mounting can use the shared `makepad-script` implementation. ```text -agent → L0/L1 → checked UiNode → reusable kit → Splash → Makepad widgets - ↑ - direct Splash UI authoring +L0/L1 + data → realized card tree → kit lowering → renderer UiNode + → Makepad widget source → host mounts native widgets + +direct Splash source → contained UI host → native widgets ``` This reuses the existing UI language and component system while giving generated cards an explicit admission boundary. It does not route widget declarations through the standalone workflow checker. See [Makepad integration](../upstream/octoscript/docs/makepad-ui-compatibility.md). @@ -85,9 +86,9 @@ A host can place a platform surface or control alongside Makepad-drawn content: There are concrete integration points: [Makepad Video](https://github.com/OctoSense-org/makepad/blob/octoscript/widgets/src/video.rs) attaches native camera previews; [the iOS backend](https://github.com/OctoSense-org/makepad/blob/octoscript/platform/src/os/apple/ios/ios.rs) owns native preview lifecycles; [the Android bridge](https://github.com/OctoSense-org/makepad/blob/octoscript/platform/src/os/linux/android/android_jni.rs) connects a native composer over the GL surface. These prove useful mixed surfaces, not automatic compatibility for every arbitrary control combination. -## Reuse Rust logic: one camera, two hosts +## Historical example: one camera, two hosts -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`. +The [camera example on a development branch](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/tree/641353aff8021f9f74e2d8ed259c1d4fc269721e/apps/camera) separates `logic/`, `native/` and `oh/`. Both host manifests depend on `octosense-camera-logic`. This is a recorded two-host example, not the architecture of the current OctoSense Camera bundle. ```text octosense-camera-logic @@ -116,3 +117,8 @@ An agent asks for current bounds, exercises a control, waits for a frame, checks “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. + + +## Running apps and talking to their agents + +The instruments above support development. [Run an app, then follow its agent](octosense-apps.en.md) explains the product runtime: standalone card-host versus the full shell, native Rust and contained apps, human/system conversations, data access and host-authorized tools. diff --git a/src/content/upstream/octoscript/docs/makepad-ui-compatibility.md b/src/content/upstream/octoscript/docs/makepad-ui-compatibility.md index 860ed18..d39f062 100644 --- a/src/content/upstream/octoscript/docs/makepad-ui-compatibility.md +++ b/src/content/upstream/octoscript/docs/makepad-ui-compatibility.md @@ -13,7 +13,7 @@ host for widget DSL execution. The shared dependency is documented in ```text LLM-generated L0/L1 card → octoscript-ui-l0: check and realize - → semantic UiNode + bindings + → realized semantic card tree + bindings → theme/component kit lowering → renderer UiNode → octoscript-makepad: translate @@ -22,7 +22,7 @@ LLM-generated L0/L1 card → native Makepad widgets ``` -[Octoscript-Makepad](https://github.com/OctoSense-org/Octoscript-Makepad) +[OctoScript-Makepad](https://github.com/OctoSense-org/OctoScript-Makepad) provides the renderer/node model, backend translation and native component kits. The embedding UI host supplies data, widget modules, event handling and state retention. Its adapter connects declared card actions to application @@ -34,13 +34,15 @@ inside the same VM instance or have the same available modules. The [UI profile](ui-profile-l0.md) is the formal contract for generated L0/L1 source. Practical composition, themes and interaction flows are documented in -[Octoscript-AppCard](https://github.com/OctoSense-org/Octoscript-AppCard). +[OctoScript-App-Design-Flow](https://github.com/OctoSense-org/OctoScript-App-Design-Flow). The [purpose and architecture](positioning.md) guide distinguishes the workflow and UI host responsibilities. +For current host ownership and launch commands, follow [the app and agent walkthrough](../../../guides/octosense-apps.en.md). The framework catalog and preview evaluate their final `View` on the main VM and mount it in `Splash.view`; a contained app has its own admission and isolate setup. + ## Makepad host and compatibility fixture -The pinned Makepad source includes the +The Makepad revision recorded in this reference includes the [`Splash` widget](https://github.com/OctoSense-org/makepad/blob/9069cfaf87960f535f2440d736d223238b88c5b1/widgets/src/splash.rs) and a [Splash example application](https://github.com/OctoSense-org/makepad/tree/9069cfaf87960f535f2440d736d223238b88c5b1/examples/splash). The widget supplies native UI bindings and mounts the widget tree. diff --git a/src/content/upstream/octoscript/docs/makepad-ui-compatibility.zh-CN.md b/src/content/upstream/octoscript/docs/makepad-ui-compatibility.zh-CN.md index a55f283..4290177 100644 --- a/src/content/upstream/octoscript/docs/makepad-ui-compatibility.zh-CN.md +++ b/src/content/upstream/octoscript/docs/makepad-ui-compatibility.zh-CN.md @@ -9,7 +9,7 @@ Octoscript 可以描述工作流的界面，并将 UI 节点交给 Makepad 进 ```text LLM 生成的 L0/L1 卡片 → octoscript-ui-l0：校验与实例化 - → 语义 UiNode + 数据绑定 + → 实例化后的语义卡片树 + 数据绑定 → 通过主题／组件 kit 转换 → 渲染器 UiNode → octoscript-makepad：翻译 @@ -18,15 +18,17 @@ LLM 生成的 L0/L1 卡片 → Makepad 原生组件 ``` -[Octoscript-Makepad](https://github.com/OctoSense-org/Octoscript-Makepad) 提供渲染器节点模型、后端翻译和原生组件 kit。嵌入它的 UI 宿主提供数据、组件模块、事件处理和状态保存；宿主适配器把卡片声明的操作连接到应用服务。 +[OctoScript-Makepad](https://github.com/OctoSense-org/OctoScript-Makepad) 提供渲染器节点模型、后端翻译和原生组件 kit。嵌入它的 UI 宿主提供数据、组件模块、事件处理和状态保存；宿主适配器把卡片声明的操作连接到应用服务。 L0 的实例化不依赖 VM。Kit 求值和最终的 Splash 组件宿主可以使用共享 VM；这不意味着工作流与 UI 必须运行在同一个 VM 实例中，或拥有相同的可用模块。 -[UI 规范（英文）](ui-profile-l0.md)是生成 L0/L1 源码的正式约定。实际卡片组合、主题和交互流程见 [Octoscript-AppCard](https://github.com/OctoSense-org/Octoscript-AppCard)。[定位与架构](positioning.zh-CN.md)进一步说明工作流宿主与 UI 宿主的职责。 +[UI 规范（英文）](ui-profile-l0.md)是生成 L0/L1 源码的正式约定。实际卡片组合、主题和交互流程见 [OctoScript-App-Design-Flow](https://github.com/OctoSense-org/OctoScript-App-Design-Flow)。[定位与架构](positioning.zh-CN.md)进一步说明工作流宿主与 UI 宿主的职责。 + +当前宿主职责与启动命令见[应用与 Agent 导读](../../../guides/octosense-apps.cn.md)。框架目录与预览宿主在主 VM 上求值最终 `View`，并挂载到 `Splash.view`；容器应用有自己的准入与隔离环境设置。 ## Makepad 宿主与兼容性样例 -当前固定版本的 Makepad 源码包含 [`Splash` 组件](https://github.com/OctoSense-org/makepad/blob/9069cfaf87960f535f2440d736d223238b88c5b1/widgets/src/splash.rs)和 [Splash 示例应用](https://github.com/OctoSense-org/makepad/tree/9069cfaf87960f535f2440d736d223238b88c5b1/examples/splash)。该组件提供原生 UI 绑定并挂载组件树。 +本参考文档记录的 Makepad 版本包含 [`Splash` 组件](https://github.com/OctoSense-org/makepad/blob/9069cfaf87960f535f2440d736d223238b88c5b1/widgets/src/splash.rs)和 [Splash 示例应用](https://github.com/OctoSense-org/makepad/tree/9069cfaf87960f535f2440d736d223238b88c5b1/examples/splash)。该组件提供原生 UI 绑定并挂载组件树。 本仓库保留 [`examples/makepad_ui_counter.octoscript`](../examples/makepad_ui_counter.octoscript) 作为小型解析器兼容性样例。它使用 Makepad UI 的惯例，包括 `View`、`width: Fill`、命名子节点，以及使用宿主提供的 `ui` 句柄的回调。 diff --git a/src/content/upstream/octoscript/docs/positioning.md b/src/content/upstream/octoscript/docs/positioning.md index 150aa69..249b03d 100644 --- a/src/content/upstream/octoscript/docs/positioning.md +++ b/src/content/upstream/octoscript/docs/positioning.md @@ -23,10 +23,12 @@ VM changes belong there; the pin and update policy are in [UPSTREAM.md](../UPSTR | --- | --- | | Makepad `makepad-script` | Shared VM, parser and script execution machinery | | Octoscript | Workflow language contract, review, execution limits, capability APIs, workflow dataflow and UI profile checking/realization | -| Embedding host, such as Octos | Register services, bind accounts and data, authorize actions, schedule work and retain application state | +| Workflow embedding host | Register services, bind accounts and data, authorize actions, schedule work and retain application state | | Octoscript-Makepad | Translate UI nodes into Makepad's widget DSL and supply native component kits | | Makepad Splash host | Provide widget bindings, mount the generated widget DSL and handle native rendering and interaction | -| Octoscript-AppCard | App Card composition, theme usage, interaction flows, agent/client integration and end-to-end examples | +| OctoScript-App-Design-Flow | App authoring, component composition, CLI launch and design-to-card flows | +| App Hub | Bundle admission, installation, contained UI hosting and host-service transport | +| OctoSense + octos | Shell-owned app data and service adapters; kernel-owned agent turns, sessions and peer routing | Sharing a VM implementation does not require sharing one VM instance, heap or set of host bindings. Workflow hosts expose their registered tools; UI hosts @@ -58,7 +60,7 @@ the grants. The draft itself does not authorize a call. See ```text generated L0/L1 declarations - → checked semantic UiNode tree and data bindings + → realized semantic card tree and data bindings → theme/component kit and renderer nodes → Makepad Splash DSL → Splash host using makepad-script @@ -77,12 +79,7 @@ language, not a sequence of product or rendering layers. The [formal UI profile](ui-profile-l0.md) defines admission; the [Makepad integration guide](makepad-ui-compatibility.md) explains the handoff. -Detailed App Card design and usage belong in -[Octoscript-AppCard](https://github.com/OctoSense-org/Octoscript-AppCard), including -[component composition](https://github.com/OctoSense-org/Octoscript-AppCard/blob/main/docs/APP-CARD-COMPONENTIZATION.md) -and the [agent/client architecture](https://github.com/OctoSense-org/Octoscript-AppCard/blob/main/docs/ARCHITECTURE.md). -Native renderer and kit APIs live in -[Octoscript-Makepad](https://github.com/OctoSense-org/Octoscript-Makepad). +App authoring belongs in [OctoScript-App-Design-Flow](https://github.com/OctoSense-org/OctoScript-App-Design-Flow). Native renderer and kit APIs live in [OctoScript-Makepad](https://github.com/OctoSense-org/OctoScript-Makepad). The website's [app and agent walkthrough](../../../guides/octosense-apps.en.md) follows current shell integration, run commands and tool boundaries. ## Where to start diff --git a/src/content/upstream/octoscript/docs/positioning.zh-CN.md b/src/content/upstream/octoscript/docs/positioning.zh-CN.md index 5b7b8bb..82e66d0 100644 --- a/src/content/upstream/octoscript/docs/positioning.zh-CN.md +++ b/src/content/upstream/octoscript/docs/positioning.zh-CN.md @@ -14,10 +14,12 @@ Octoscript 和 Makepad 的 Splash UI 宿主使用同一套 `makepad-script` VM | --- | --- | | Makepad `makepad-script` | 共享 VM、解析器与脚本执行机制 | | Octoscript | 工作流语言约定、审查、执行限制、能力 API、工作流数据流，以及 UI 规范校验与实例化 | -| 嵌入宿主，例如 Octos | 注册服务、绑定账户和数据、授权操作、调度任务、保存应用状态 | +| 工作流嵌入宿主 | 注册服务、绑定账户和数据、授权操作、调度任务、保存应用状态 | | Octoscript-Makepad | 将 UI 节点转换为 Makepad 组件 DSL，并提供原生组件 kit | | Makepad Splash 宿主 | 提供组件绑定、挂载生成的组件 DSL，并处理原生渲染与交互 | -| Octoscript-AppCard | App Card 组合、主题使用、交互流程、Agent／客户端集成与端到端示例 | +| OctoScript-App-Design-Flow | 应用创作、组件组合、CLI 启动与设计到卡片的流程 | +| App Hub | 应用包准入、安装、容器 UI 宿主与宿主服务传输 | +| OctoSense + octos | Shell 持有应用数据与服务适配器；内核负责 Agent turn、session 与 Peer 路由 | 共享 VM 实现不要求共用同一个 VM 实例、堆或宿主绑定。工作流宿主暴露注册的工具；UI 宿主安装视图所需的组件模块，并接入事件循环。 @@ -40,7 +42,7 @@ LLM 输出 ```text 生成的 L0/L1 声明 - → 校验后的语义 UiNode 树与数据绑定 + → 实例化后的语义卡片树与数据绑定 → 主题／组件 kit 与渲染器节点 → Makepad Splash DSL → 使用 makepad-script 的 Splash 宿主 @@ -51,7 +53,7 @@ LLM 输出 L0 是声明式 UI 规范，包含组件、插槽、数据源、带键集合、状态和事件转换；实例化本身不需要 VM。L1 在此基础上增加有界的纯算术表达式。它们是与工作流语言并列的 UI 规范，并非产品或渲染层的分级。[正式 UI 规范（英文）](ui-profile-l0.md)定义可接受的源码；[Makepad 集成指南](makepad-ui-compatibility.zh-CN.md)说明渲染交接过程。 -App Card 的详细设计与使用文档放在 [Octoscript-AppCard](https://github.com/OctoSense-org/Octoscript-AppCard)，包括[组件组合](https://github.com/OctoSense-org/Octoscript-AppCard/blob/main/docs/APP-CARD-COMPONENTIZATION.md)和 [Agent／客户端架构](https://github.com/OctoSense-org/Octoscript-AppCard/blob/main/docs/ARCHITECTURE.md)。原生渲染器与 kit API 位于 [Octoscript-Makepad](https://github.com/OctoSense-org/Octoscript-Makepad)。 +应用创作流程位于 [OctoScript-App-Design-Flow](https://github.com/OctoSense-org/OctoScript-App-Design-Flow)，原生渲染器与 kit API 位于 [OctoScript-Makepad](https://github.com/OctoSense-org/OctoScript-Makepad)。本站的[应用与 Agent 导读](../../../guides/octosense-apps.cn.md)说明当前 Shell 集成、运行命令与工具边界。 ## 从哪里开始 diff --git a/src/content/upstream/octoscript/sources.json b/src/content/upstream/octoscript/sources.json index d8bf54d..b00c8f7 100644 --- a/src/content/upstream/octoscript/sources.json +++ b/src/content/upstream/octoscript/sources.json @@ -4,13 +4,17 @@ "snapshot_date": "2026-09-19", "note": "Snapshot of the working tree, including local documentation updates; hashes identify the exact copies. These are website-owned snapshots, not live imports.", "files": { - "docs/positioning.md": "49f520b8b6a0491d2d664d279d94f3149b631eeec2ff4373588019e750926a0d", - "docs/positioning.zh-CN.md": "b4296f0c1e6f2c057ff7870619eb28d9b6c25cb25faff7cae4ae1f8d2ff039d9", - "docs/makepad-ui-compatibility.md": "751637eaf8c7623d1a9b2dfe98f142e077d729b9e1a1e8a1c4775b96a3d1b41a", - "docs/makepad-ui-compatibility.zh-CN.md": "34e6be0ff83eb65ca7753ec0ea9d6a01710a9773e1272c600d12dd67cf45b71a", + "docs/positioning.md": "cafe7d05191e6ad9e7ecd4f182d4fc81435625dd756da23d419a4a1b3a1e6c04", + "docs/positioning.zh-CN.md": "efce5e46c4f0582ad0eff44199fc3a206b71ca13d9deb0aae87e31df80f7c3df", + "docs/makepad-ui-compatibility.md": "581b32fef4a3739b2ffff66c4aa903415918cfdf3243a212c72db878e3a795c1", + "docs/makepad-ui-compatibility.zh-CN.md": "17b5cd5888077456ea6f77c08cc8b09d15fe28b3a56b6a758649d76fe4462653", "UPSTREAM.md": "4d5d65c6fc21937d4c67dd2d38e29bc5a933b4459c8729c7d200820b41c5f64c", "UPSTREAM.zh-CN.md": "36b829374e8fd65bd4453ce79bc411a4b2b1d07da2ffad48fcb348655094f567", "examples/tool_workflow.octoscript": "5305e1bd6f8c37b73e36417528c56f7e6335734d6468ed2dd73494299105c276", "LICENSE": "3855d73a873244ec424ac5781d5d8fc8e2a789ff9d2f1cb804bec585a64ea88f" + }, + "website_corrections": { + "date": "2026-10-02", + "scope": "Corrected realized-card versus renderer-node terminology, repository ownership, and current OctoSense host integration links against the ecosystem code walkthroughs. The original source base and snapshot date remain recorded above." } } diff --git a/src/data/content.ts b/src/data/content.ts index cdefa7a..4f2008c 100644 --- a/src/data/content.ts +++ b/src/data/content.ts @@ -1,6 +1,6 @@ export type Locale = 'en' | 'cn'; export const repository = 'https://github.com/OctoSense-org/Octoscript'; -export const appcard = 'https://github.com/OctoSense-org/Octoscript-AppCard'; +export const appcard = 'https://github.com/OctoSense-org/OctoScript-App-Design-Flow'; export const renderer = 'https://github.com/OctoSense-org/Octoscript-Makepad'; export const base = import.meta.env.BASE_URL.replace(/\/$/, ''); export const asset = (path: string) => `${base}/${path}`; @@ -49,6 +49,7 @@ export const content = { docsLabel: '10 / DOCUMENTATION', docsTitle: 'A clear next step', docsIntro: 'Start with the architecture. Go deeper when you need to.', guides: [ + { slug: 'octosense-apps', title: 'Run an app, follow its agent', description: 'Native Rust, Splash and L0 apps; human conversations, app data, tool grants and Tokio.', tag: 'APPS & AGENTS' }, { slug: 'why-octoscript', title: 'Why a DSL for agents?', description: 'Motivation, Python / JavaScript tradeoffs, execution boundaries and Splash lineage.', tag: 'MOTIVATION' }, { slug: 'splash-a2app', title: 'Splash → A2App', description: 'Language features, reusable Rust, native UI hosts and in-app agent instruments.', tag: 'LANGUAGE & HOSTS' }, { slug: 'design-to-app', title: 'Pixels → components', description: 'Two detailed flows: generated image atlases and structured Sketch documents.', tag: 'WORKED EXAMPLES' }, @@ -128,6 +129,7 @@ export const content = { stepTitles: ['获取源码', '校验并运行', '连接你的工具'], stepBodies: ['克隆 Octoscript 仓库。', '执行前，先通过校验器检查源码。', '在嵌入宿主中注册应用工具。'], toolsLink: '宿主工具目录', docsLabel: '10 / 开发文档', docsTitle: '下一步，清晰可见', docsIntro: '先了解架构，再按需深入。', guides: [ + { slug: 'octosense-apps', title: '运行应用，追踪 Agent', description: '原生 Rust、Splash 与 L0 应用；用户对话、应用数据、工具授权和 Tokio。', tag: '应用与 AGENT' }, { slug: 'why-octoscript', title: '为何为 Agent 设计 DSL？', description: '设计动机、Python／JavaScript 的取舍、执行边界与 Splash 来源。', tag: '设计动机' }, { slug: 'splash-a2app', title: 'Splash → A2App', description: '语言特性、Rust 复用、原生 UI 宿主与应用内 Agent 仪器。', tag: '语言与宿主' }, { slug: 'design-to-app', title: '像素 → 组件', description: '生成图集与 Sketch 文档两条流程，以及详细的组件映射例证。', tag: '完整例证' }, diff --git a/src/data/docs.ts b/src/data/docs.ts index 21c9892..e204f01 100644 --- a/src/data/docs.ts +++ b/src/data/docs.ts @@ -16,9 +16,11 @@ import * as syntaxEn from '../content/guides/language-profiles.en.md'; import * as syntaxCn from '../content/guides/language-profiles.cn.md'; import * as componentsEn from '../content/guides/component-library.en.md'; import * as componentsCn from '../content/guides/component-library.cn.md'; +import * as appsEn from '../content/guides/octosense-apps.en.md'; +import * as appsCn from '../content/guides/octosense-apps.cn.md'; const modules = { - en: {'why-octoscript': whyEn, 'splash-a2app': splashEn, 'design-to-app': flowsEn, 'language-profiles': syntaxEn, 'component-library': componentsEn, architecture: architectureEn, makepad: makepadEn, 'shared-vm': vmEn}, - cn: {'why-octoscript': whyCn, 'splash-a2app': splashCn, 'design-to-app': flowsCn, 'language-profiles': syntaxCn, 'component-library': componentsCn, architecture: architectureCn, makepad: makepadCn, 'shared-vm': vmCn}, + en: {'octosense-apps': appsEn, 'why-octoscript': whyEn, 'splash-a2app': splashEn, 'design-to-app': flowsEn, 'language-profiles': syntaxEn, 'component-library': componentsEn, architecture: architectureEn, makepad: makepadEn, 'shared-vm': vmEn}, + cn: {'octosense-apps': appsCn, 'why-octoscript': whyCn, 'splash-a2app': splashCn, 'design-to-app': flowsCn, 'language-profiles': syntaxCn, 'component-library': componentsCn, architecture: architectureCn, makepad: makepadCn, 'shared-vm': vmCn}, }; export const guidesFor = (locale: Locale) => content[locale].guides.map(guide => { const module = modules[locale][guide.slug as keyof typeof modules.en]; diff --git a/tests/story.spec.ts b/tests/story.spec.ts index 8f99e4f..fc18cbc 100644 --- a/tests/story.spec.ts +++ b/tests/story.spec.ts @@ -44,7 +44,7 @@ for (const locale of ['en', 'cn'] as const) { }); test(`${locale}: new guides have working links and readable code in both themes`, async ({ page }) => { - for (const slug of ['why-octoscript', 'splash-a2app', 'design-to-app']) { + for (const slug of ['octosense-apps', 'why-octoscript', 'splash-a2app', 'design-to-app']) { await page.goto(`${home}docs/${slug}/`); await expect(page.locator('article h1')).toHaveCount(1); const localLinks = await page.locator('article a').evaluateAll(links => links.map(link => (link as HTMLAnchorElement).href).filter(href => new URL(href).origin === location.origin));