From 7d1f00ccabc6ee6f6192fd8997123cf12719d31d Mon Sep 17 00:00:00 2001 From: "Jing.Li" Date: Sun, 27 Sep 2026 07:27:07 -0700 Subject: [PATCH 1/2] docs: how to open & add the full Makepad catalog Two guides under docs/ plus README links: - open-apps.md: launch the desktop, open an app in a tile, fix an empty catalog (offline cargo metadata), add a new catalog entry. - add-all-makepad-apps.md: point the desktop at apps.makepad.json and open any Makepad app. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 1 + docs/add-all-makepad-apps.md | 192 +++++++++++++++++++++++++++++++++++ docs/open-apps.md | 147 +++++++++++++++++++++++++++ 3 files changed, 340 insertions(+) create mode 100644 docs/add-all-makepad-apps.md create mode 100644 docs/open-apps.md diff --git a/README.md b/README.md index c6863e01..238e2714 100644 --- a/README.md +++ b/README.md @@ -225,6 +225,7 @@ Catalog lookup: `--apps ` if given, else `~/.octosense/apps.json` if it ex ``` - `"source": "makepad"` resolves through Cargo to the same Makepad checkout as the host; such builds go to `~/.octosense/build/makepad`. +- Step-by-step guides: [docs/open-apps.md](docs/open-apps.md) and [docs/add-all-makepad-apps.md](docs/add-all-makepad-apps.md). - Relative paths resolve from the catalog's directory. Arguments are passed literally, without a shell. - `policy`: `"new"` opens another instance; `"focus"` (default) focuses a running one. - Do not add `--stdin-loop` or Studio variables; the shell adds them. Restart after editing. diff --git a/docs/add-all-makepad-apps.md b/docs/add-all-makepad-apps.md new file mode 100644 index 00000000..c7e8634e --- /dev/null +++ b/docs/add-all-makepad-apps.md @@ -0,0 +1,192 @@ +# 把 Makepad 全家桶应用到 OctoSense + +本文说明如何把 Makepad 仓库里的全部应用(浏览器、文件、终端、天气、金融、邮件、笔记、日历、提醒、计算器、Fabric、Score、视频、导航、VJ、Fab、Director、Image、PDF、AI 等)一次性加进 OctoSense 桌面,让它们全部出现在 **⌘Space** 应用菜单里并可随时打开。 + +--- + +## 一、前提条件 + +1. **Makepad 同级框架仓库就位** + + ```sh + cd /path/to/OctoSense + python3 tools/setup-native.py --update + ``` + + 把 `../makepad`、`../octoscript`、`../octoscript-makepad` 检出到锁定版本。 + 目录里 `"source": "makepad"` 的行要靠 `cargo metadata --offline` 解析出 + 这个 checkout 才能生效。 + +2. **Cargo 缓存完整**(离线 metadata 能成功) + + 第一次构建宿主后,跑一次联网 `cargo metadata` 把缺失依赖补进缓存: + + ```sh + cargo metadata --format-version 1 --manifest-path Cargo.toml > /dev/null + ``` + + 之后 `cargo metadata --offline` 正常,目录解析出 Makepad 根。 + (缓存不全时所有 `source: makepad` 行会被静默跳过,日志只显示 + `no app 'X' in the registry`。) + +3. **编译宿主** + + ```sh + cargo build --release + ``` + +--- + +## 二、两个应用目录 + +| 文件 | 内容 | +|---|---| +| `config/apps.json`(默认) | 只有 `reference`(本项目自带的示例) | +| `config/apps.makepad.json` | Reference + Makepad 全家桶(20+ 个应用) | + +`config/apps.makepad.json` 已经包含所有 Makepad 应用,你**不需要手写**。 +启动时指定它: + +```sh +cargo run --release -- --apps config/apps.makepad.json +``` + +如果想把它变成默认,改 `config/apps.json` 的内容(或建 +`~/.octosense/apps.json` 个人目录覆盖),重启即可。 + +--- + +## 三、目录里 Makepad 全家桶的完整条目 + +`config/apps.makepad.json` 的 `source: makepad` 行(每行 3 要素: +`package` = Makepad 的 Cargo 包名,`bin` = 可执行文件名,`policy` = 多实例策略): + +| id | label | package | bin | policy | +|---|---|---|---|---| +| `browser` | Browser | makepad-browser | browser | focus | +| `files` | Files | makepad-files | files | focus (args: `--demo`) | +| `terminal` | Terminal | makepad-terminal | terminal | new | +| `mixer` | Mixer | makepad-mixer | makepad-mixer | focus | +| `task` | Task Manager | makepad-task | task | focus | +| `sheets` | Sheets | makepad-sheets | sheets | focus | +| `photos` | Photos | makepad-photos | photos | focus | +| `clock` | Clock | makepad-clock | clock | focus | +| **`weather`** | **Weather** | **makepad-weather** | **weather** | **focus** | +| `finance` | Finance | makepad-finance | finance | focus | +| `mail` | Mail | makepad-mail | mail | focus | +| `notes` | Notes | makepad-notes | notes | focus | +| `calendar` | Calendar | makepad-calendar | calendar | focus | +| `reminders` | Reminders | makepad-reminders | reminders | focus | +| `calculator` | Calculator | makepad-calculator | calculator | focus | +| `fabric` | Fabric | makepad-fabric | makepad-fabric | focus | +| `score` | Score | makepad-app-score | makepad-app-score | focus | +| `video` | Video Player | makepad-video | video | new | +| `route` | Route | makepad-app-route | route | focus | +| `vj` | VJ | makepad-vj | makepad-vj | focus | +| `fab` | Fab | makepad-fab | makepad-fab | focus | +| `studio` | Director | makepad-director | director | focus | +| `image` | Image Viewer | makepad-image | image | new | +| `pdf` | PDF Viewer | makepad-pdf | pdf | new | +| `aichat` | AI | makepad-aichat | aichat | new | + +`policy: focus` = 已有实例就聚焦,`policy: new` = 每次开新实例。 + +--- + +## 四、启动并打开全家桶 + +```sh +# 1. 启动桌面,加载 Makepad 全家桶目录 +cargo run --release -- --apps config/apps.makepad.json +``` + +启动后用任一方式打开应用: + +**脚本化**(每个应用独立一行,适合自动化): + +```sh +# 在启动参数里同时开多个(可叠加) +cargo run --release -- \ + --apps config/apps.makepad.json \ + --test-action launch-weather \ + --test-action launch-browser + +# 或者在桌面已运行时,另开一个 shell 发 test-action +# (test-action 只在启动时执行一次,所以每次要新起进程) +``` + +**手动**(在桌面里操作,最常用): + +- **⌘Space** → 应用菜单,搜索并点击任意应用名 +- 或 **⌘1…0** 切工作区,**⌘W** 关 tile,**⌘F** 当前 tile 全屏 + +每个应用首次打开会现场 `cargo run` 编译(进度显示在 tile 里, +首次冷构建约 90 秒);之后复用 Cargo 缓存,秒开。 + +--- + +## 五、验证 + +启动后在桌面主日志(重定向 stdout 可得)里找: + +``` +wm: desktop style octosense applied to N clients and 0 modules +# N = 已打开的应用 tile 数 + +# 对每个打开的应用: +wm: --test-action launch weather +wm: launched weather as client 1 +wm: weather client 1 first frame in NNN ms (cold) ← 出画面 + +# 打开多个应用: +wm: launched browser as client 2 +wm: launched terminal as client 3 +... +``` + +`first frame in NNN ms (cold)` 表示该应用的首帧已渲染,tile 里能看到画面。 +每个应用自己的日志在 `~/.octosense/wm/logs/.log`。 + +--- + +## 六、常见问题 + +**打开应用时报 `no app 'X' in the registry`** + +Cargo 离线缓存不全。联网跑一次: + +```sh +cargo metadata --format-version 1 --manifest-path Cargo.toml > /dev/null +``` + +再重启 OctoSense。 + +**应用 tile 里一直显示 "building…" 不出画面** + +首次冷构建,进度正常。等 90 秒左右出首帧。之后秒开。 + +**应用打不开(构建失败)** + +看 `~/.octosense/wm/logs/.log` 里的编译错误。 +Makepad 全家桶应用都依赖同一个 Makepad checkout,版本不匹配会失败。 + +**某个应用不想要,隐藏它的启动器图标** + +在 `~/.octosense/wm/launcher.hides` 里加一行应用 id,例如: + +```json +["image", "pdf", "aichat"] +``` + +Image/PDF/AI 这三个 helper 应用默认出现在启动器里(除非被隐藏)。 + +--- + +## 相关 + +- 单个应用目录格式:README「Add an app」章节 +- 目录解析原理与离线 metadata 踩坑:[open-apps.md](open-apps.md) 第四、五章 +- Makepad 全家桶目录是生成物:由上游 `scripts/upstream.py catalog`(读 + Makepad checkout 的依赖图生成)产出,本地在 `config/apps.overlay.json` + 叠加适配。检查漂移或重新生成: + `python3 scripts/upstream.py catalog`(加 `--apply` 写回)。 diff --git a/docs/open-apps.md b/docs/open-apps.md new file mode 100644 index 00000000..a148124f --- /dev/null +++ b/docs/open-apps.md @@ -0,0 +1,147 @@ +# 在 OctoSense 中打开托管应用(操作记录 + 参考) + +这份文档记录 2026-09-26 实际跑通的流程,并整理成可复用的参考。 + +OctoSense 桌面能把 Makepad 应用作为独立子进程托管在自己的窗口(tile)里。 +下面先按时间顺序记录当时怎么做的,再给可照抄的命令。 + +## 一、当时是怎么操作的(按时间) + +1. **准备同级框架仓库**:`python3 tools/setup-native.py --update` + —— 把 `../makepad`、`../octoscript`、`../octoscript-makepad` 检出到锁定版本。 +2. **编译宿主**:`cargo build`(debug 或 release),产物在 `CARGO_TARGET_DIR` + 指定的 target 目录下(本机是 `/Volumes/PSSD/dev/rust-target`)。 +3. **启动桌面**:跑编译出的 `octosense` 可执行文件。 + 第一次用 `--test-action launch-weather` 打 weather,日志报 + `no app 'weather' in the registry` —— 应用目录里查不到 weather。 +4. **查原因**:目录的 `"source": "makepad"` 行要靠 + `cargo metadata --offline` 解析出 Makepad checkout; + 而离线 metadata 因为缓存缺依赖(`agent-client-protocol` 1.3.0)而失败, + 导致所有 makepad 应用行被静默跳过。 +5. **修复**:联网跑一次 `cargo metadata` 把缺的依赖补进缓存; + 之后离线 metadata 正常,目录解析出 `/Volumes/PSSD/CodeProjects/makepad`。 +6. **再开 weather**:桌面把 weather 作为 **client 1** 托管,现场 + `cargo run` 编译;首次冷构建 91 秒出首帧(`first frame in 91473 ms (cold)`), + 天气应用成功渲染进桌面 tile。 + +## 二、可照抄的命令 + +### 启动并打开天气 + +```sh +# 启动桌面(用 Makepad 全家桶目录) +cargo run --release -- --apps config/apps.makepad.json + +# 在另一个 shell 里,或直接加在启动参数上: +cargo run --release -- --test-action launch-weather +``` + +`--test-action launch-` 是脚本化打开应用的方式, +app-id 就是目录里的 `id`(weather、browser、files、terminal、aichat……)。 +首次启动会现场 `cargo run` 编译应用,进度显示在 tile 里; +之后复用 Cargo 缓存,秒开。 + +### 手动操作(不用 test-action) + +- **⌘Space** 打开应用菜单/搜索,直接搜 "Weather" +- **⌘W** 关 tile,**⌘F** 当前 tile 全屏,**⌘1…0** 切工作区 +- 菜单里 Learn → Keybindings 列全部快捷键 + +### 验证日志 + +启动后在桌面主日志(重定向 stdout 可得)里找这几行: + +``` +wm: --test-action launch weather +wm: launched weather as client 1 +wm: weather client 1 first frame in NNN ms (cold) ← 应用已出画面 +``` + +## 三、两个应用目录 + +| 文件 | 内容 | 何时用 | +|---|---|---| +| `config/apps.json`(默认) | 只有 `reference` | 默认桌面 | +| `config/apps.makepad.json` | Reference + Makepad 全家桶(Browser、Files、Terminal、Weather、Finance、Mail、Notes、Calendar、Reminders、Calculator、Fabric、Score、Video、Route、VJ、Fab、Director、Image、PDF、AI 等) | 想开满应用时用 | + +用 `--apps` 选目录: + +```sh +cargo run --release -- --apps config/apps.makepad.json +``` + +个人目录 `~/.octosense/apps.json` 优先级高于项目默认;`--apps` 永远指向你点名的文件。 + +## 四、目录里为什么应用会"缺席" + +`"source": "makepad"` 的行不是按路径找,而是让 Cargo 报告它用哪个 Makepad checkout +来编译本宿主,然后去那个 checkout 里找应用。 + +1. 宿主启动时跑一次 `cargo metadata --offline --locked`, + 在依赖图里找带 `apps/wm/Cargo.toml` 标记的 Makepad 仓库根。 + (见 `src/octosense/makepad_source.rs`、`src/octosense/catalog.rs`。) +2. 找不到 checkout(比如离线依赖不全),这些行会被**静默跳过**, + 不会报错 —— 日志里只会看到 `no app 'X' in the registry`。 + +症状:启动后用 `--test-action launch-weather` 打开应用, +日志打 `octosense: no app 'weather' in the registry`,目录里却没有 weather。 + +原因:Cargo 缓存里缺少 lock 文件锁定的依赖版本(本次是 +`agent-client-protocol` 要 1.3.0,缓存只有 1.2.0), +`cargo metadata --offline` 直接失败 → 解析不出 Makepad 根 → +所有 `source: makepad` 行被丢弃。 + +修复(联网跑一次 metadata 把依赖补进缓存): + +```sh +cd OctoSense +cargo metadata --format-version 1 --manifest-path Cargo.toml > /dev/null +``` + +之后离线 metadata 正常,目录解析出 `/Volumes/PSSD/CodeProjects/makepad`。 +(前提:同级框架仓库已经用 `python3 tools/setup-native.py` 准备好。) + +## 五、往目录里加一个新应用 + +目录是一组 JSON 数组,每行三选一: + +- `"manifest"` + `"package"` + `"bin"` —— 指到某个 Cargo 工程(相对目录所在目录) +- `"executable"` —— 指到已安装的可执行文件 +- `"source": "makepad"` + `"package"` + `"bin"` —— 让宿主按本构建的 Makepad checkout 解析 + +```json +{ + "id": "notes", + "label": "Notes", + "manifest": "../notes/Cargo.toml", + "package": "my-notes", + "bin": "notes", + "policy": "new", + "args": [] +} +``` + +规则(与 `src/octosense/catalog.rs` 校验一致): + +- `id` 只允许小写字母、数字、`-`、`_`;目录内不允许重复 +- `label` 必填;`policy` 缺省是 `focus`(已有实例就聚焦),`new` 强制开新实例 +- `args` 是字符串数组,原样传给子进程(不经 shell) +- 应用必须支持 `--stdin-loop` 托管协议,且与本宿主同一 Makepad 版本 +- 可执行文件托管的条目不要写 `package` / `bin` + +放哪: + +```sh +# 项目默认目录:改 config/apps.json,重启 OctoSense +# 个人目录(优先于项目默认):~/.octosense/apps.json +# 临时选目录:--apps /path/to/your.json +``` + +写完之后,应用就会出现在 **⌘Space** 应用菜单里;也可以 `--test-action launch-` 直接打开。 +不可用(找不到 manifest / 构建失败)的应用会在桌面日志里报原因,不会崩溃。 + +## 相关 + +- 应用目录格式:README「Add an app」章节 +- 每个应用托管时自己的日志:`~/.octosense/wm/logs/.log` +- 目录里不存在的 app 快捷键会提示「unavailable」,不会崩溃 From f03d2398cfd9ac1bb059fe3de7f738d9f90eb628 Mon Sep 17 00:00:00 2001 From: ymote <151983+ymote@users.noreply.github.com> Date: Sun, 27 Sep 2026 07:27:07 -0700 Subject: [PATCH 2/2] docs: bring the app-opening guides up to date - The default catalog (config/apps.json) already lists the full Makepad set; apps.makepad.json is an identical copy for --apps. - Makepad's Photos and Mail left the catalogs; the system apps replace them (note added). - Machine-specific paths replaced with the standard layout. - README points to both guides (Chinese). Co-Authored-By: Claude Opus 5.5 (1M context) --- README.md | 2 +- docs/add-all-makepad-apps.md | 15 +++++++-------- docs/open-apps.md | 12 ++++++------ 3 files changed, 14 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 238e2714..178085cc 100644 --- a/README.md +++ b/README.md @@ -225,7 +225,7 @@ Catalog lookup: `--apps ` if given, else `~/.octosense/apps.json` if it ex ``` - `"source": "makepad"` resolves through Cargo to the same Makepad checkout as the host; such builds go to `~/.octosense/build/makepad`. -- Step-by-step guides: [docs/open-apps.md](docs/open-apps.md) and [docs/add-all-makepad-apps.md](docs/add-all-makepad-apps.md). +- Step-by-step guides (Chinese): [open a hosted app](docs/open-apps.md), including the fix for an empty catalog when `cargo metadata --offline` fails, and [open the full Makepad catalog](docs/add-all-makepad-apps.md). - Relative paths resolve from the catalog's directory. Arguments are passed literally, without a shell. - `policy`: `"new"` opens another instance; `"focus"` (default) focuses a running one. - Do not add `--stdin-loop` or Studio variables; the shell adds them. Restart after editing. diff --git a/docs/add-all-makepad-apps.md b/docs/add-all-makepad-apps.md index c7e8634e..f38d736e 100644 --- a/docs/add-all-makepad-apps.md +++ b/docs/add-all-makepad-apps.md @@ -41,18 +41,19 @@ | 文件 | 内容 | |---|---| -| `config/apps.json`(默认) | 只有 `reference`(本项目自带的示例) | -| `config/apps.makepad.json` | Reference + Makepad 全家桶(20+ 个应用) | +| `config/apps.json`(默认) | Reference + Makepad 全家桶(20+ 个应用),桌面默认就读它 | +| `config/apps.makepad.json` | 与 `config/apps.json` 相同的副本,供 `--apps` 显式指定 | -`config/apps.makepad.json` 已经包含所有 Makepad 应用,你**不需要手写**。 -启动时指定它: +默认目录已经包含所有 Makepad 应用,你**不需要手写**,直接 `cargo run --release` 即可。 +也可以显式指定副本: ```sh cargo run --release -- --apps config/apps.makepad.json ``` -如果想把它变成默认,改 `config/apps.json` 的内容(或建 -`~/.octosense/apps.json` 个人目录覆盖),重启即可。 +想换成自己的目录,建 `~/.octosense/apps.json` 个人目录覆盖默认目录,重启即可。 + +> 注意：Makepad 自带的 Photos 和 Mail 已从目录中移除，由 OctoSense 的系统应用（News、Photos、Maps、Camera、Mail、AI providers，经 App Hub 打包进 Shell）取代，它们不在开发者程序目录里。 --- @@ -69,11 +70,9 @@ cargo run --release -- --apps config/apps.makepad.json | `mixer` | Mixer | makepad-mixer | makepad-mixer | focus | | `task` | Task Manager | makepad-task | task | focus | | `sheets` | Sheets | makepad-sheets | sheets | focus | -| `photos` | Photos | makepad-photos | photos | focus | | `clock` | Clock | makepad-clock | clock | focus | | **`weather`** | **Weather** | **makepad-weather** | **weather** | **focus** | | `finance` | Finance | makepad-finance | finance | focus | -| `mail` | Mail | makepad-mail | mail | focus | | `notes` | Notes | makepad-notes | notes | focus | | `calendar` | Calendar | makepad-calendar | calendar | focus | | `reminders` | Reminders | makepad-reminders | reminders | focus | diff --git a/docs/open-apps.md b/docs/open-apps.md index a148124f..dd891f92 100644 --- a/docs/open-apps.md +++ b/docs/open-apps.md @@ -1,6 +1,6 @@ # 在 OctoSense 中打开托管应用(操作记录 + 参考) -这份文档记录 2026-09-26 实际跑通的流程,并整理成可复用的参考。 +这份文档整理了在 OctoSense 桌面中打开托管应用的步骤(2026-09-26 实测)。 OctoSense 桌面能把 Makepad 应用作为独立子进程托管在自己的窗口(tile)里。 下面先按时间顺序记录当时怎么做的,再给可照抄的命令。 @@ -10,7 +10,7 @@ OctoSense 桌面能把 Makepad 应用作为独立子进程托管在自己的窗 1. **准备同级框架仓库**:`python3 tools/setup-native.py --update` —— 把 `../makepad`、`../octoscript`、`../octoscript-makepad` 检出到锁定版本。 2. **编译宿主**:`cargo build`(debug 或 release),产物在 `CARGO_TARGET_DIR` - 指定的 target 目录下(本机是 `/Volumes/PSSD/dev/rust-target`)。 + 指定的 target 目录下(默认 `target/`)。 3. **启动桌面**:跑编译出的 `octosense` 可执行文件。 第一次用 `--test-action launch-weather` 打 weather,日志报 `no app 'weather' in the registry` —— 应用目录里查不到 weather。 @@ -19,7 +19,7 @@ OctoSense 桌面能把 Makepad 应用作为独立子进程托管在自己的窗 而离线 metadata 因为缓存缺依赖(`agent-client-protocol` 1.3.0)而失败, 导致所有 makepad 应用行被静默跳过。 5. **修复**:联网跑一次 `cargo metadata` 把缺的依赖补进缓存; - 之后离线 metadata 正常,目录解析出 `/Volumes/PSSD/CodeProjects/makepad`。 + 之后离线 metadata 正常,目录解析出同级的 `../makepad` checkout。 6. **再开 weather**:桌面把 weather 作为 **client 1** 托管,现场 `cargo run` 编译;首次冷构建 91 秒出首帧(`first frame in 91473 ms (cold)`), 天气应用成功渲染进桌面 tile。 @@ -61,8 +61,8 @@ wm: weather client 1 first frame in NNN ms (cold) ← 应用已出画面 | 文件 | 内容 | 何时用 | |---|---|---| -| `config/apps.json`(默认) | 只有 `reference` | 默认桌面 | -| `config/apps.makepad.json` | Reference + Makepad 全家桶(Browser、Files、Terminal、Weather、Finance、Mail、Notes、Calendar、Reminders、Calculator、Fabric、Score、Video、Route、VJ、Fab、Director、Image、PDF、AI 等) | 想开满应用时用 | +| `config/apps.json`(默认) | Reference + Makepad 全家桶(Browser、Files、Terminal、Weather、Finance、Notes、Calendar、Reminders、Calculator、Fabric、Score、Video、Route、VJ、Fab、Director、Image、PDF、AI 等) | 默认桌面 | +| `config/apps.makepad.json` | 与默认目录相同的副本 | 用 `--apps` 显式指定时 | 用 `--apps` 选目录: @@ -98,7 +98,7 @@ cd OctoSense cargo metadata --format-version 1 --manifest-path Cargo.toml > /dev/null ``` -之后离线 metadata 正常,目录解析出 `/Volumes/PSSD/CodeProjects/makepad`。 +之后离线 metadata 正常,目录解析出同级的 `../makepad` checkout。 (前提:同级框架仓库已经用 `python3 tools/setup-native.py` 准备好。) ## 五、往目录里加一个新应用