Skip to content

OpenTray v0.21.1：把一个命令变成托盘应用

jixoai v0.21.1 opentray

OpenTray v0.21.1 是仓库的第一份 GitHub Release。它给命令行工具、AI skill 与本地守护进程这类轻量程序一个常驻托盘入口，不必引入 Electron 或整套桌面应用框架：npx create-opentray 一行把现有命令包装成托盘应用，SDK 侧一个 createTray() 就够。

$ npm view create-opentray version
0.21.1

OpenTray v0.21.1 发布了（2026-09-06，仓库的第一份 GitHub Release）。它给命令行工具、AI skill 和本地守护进程这类轻量程序一个常驻的托盘入口：有图标、有菜单、能收点击事件，不必为一个小图标引入 Electron 或整套桌面应用框架。

一行命令，把现有命令包装成托盘应用

已经在本地起 HTTP 服务的命令，npx create-opentray 直接给它套一层 OpenTray 应用。三条进入路径都在 create-app 指南 里：

npx create-opentray web      # 浏览器向导，交互式
npx create-opentray create --app-id com.example.build \
  --app-name "Build" --exec "npm run dev"   # 完全非交互
npx create-opentray skill    # 内置 AI skill，交给代理读

向导里的命令输入现在收敛成单行输入组（command families，按运行器家族组织）：家族选择前缀 + 命令体。家族覆盖 npm 系（npx/pnpx/bunx/yarn dlx/nubx/deno run/vpx）、go run、cargo install，以及 uvx/pipx run 与 dnx。每个家族渲染成只读命令面，点开是结构化表单，填 runner、包标识（包名 / 模块 / crate / 工具 id）、版本与参数；确认后写回命令串，取消则整个输入作废。

appId 由家族推导，同一个包换 runner 也拿到稳定身份：

npx @deepseek-ai/dsh@latest web   → web.dsh.npmjs
go run rsc.io/fortune@latest      → fortune.golang
cargo install ripgrep（rg）        → rg.rust

应用代码只调一个 createTray()

写托盘应用不需要打包器，也不加载 Node addon。应用代码直接 createTray()，自己管前台与后台的生命周期：

import { createTray, type TrayIcon } from "opentray";

let tray;
tray = await createTray(
  {
    id: "com.example.first-app",
    icon: { "text-only": "OT" },
    menu: {
      items: [
        { title: "Quit", primaryEvent: true, onMenuClick: () => void tray.destroy() },
      ],
    },
  },
  { appId: "com.example.first-app", appName: "First App" },
);

应用代码经公共 tray/session 协议与运行时对话。运行时侧有四个本体。

  • App：调用方持有的运行时身份，同时是隔离边界

  • Tray：一个 app 下的单个托盘图标及其状态

  • Session：托盘事件与变更的实时权威来源

  • Extension：只作用在这个 app 与它的托盘上的原生能力包

上一代公共 API 的 Space 与 Surface 两个本体已退役。

工作区的所有包按固定版本一起发布：opentray（SDK + CLI）、@opentray/spec（协议契约）、@opentray/packaging 与四个 bundler 适配器（vite/tsdown/esbuild/webpack 同一 manifest 形状）、@opentray/ext-webview 及平台 WebView 动态库、@opentray/ext-badge，Lynx 扩展独立维护在 jixoai/opentray-ext-lynx。

其余变更

  • 修复全新安装 404：私有 workspace 包 @create-opentray/core 与 @create-opentray/cli 误入运行时 dependencies（0b0fe63）。这条判定规则由 2026-08-20 的一次真实安装失败反馈定位，本版是 command families 第一个装得上的版本。

  • 发布自动化：每个发布版本自动切出一份 GitHub Release（tag = 包版本，notes = changesets 生成的 changelog 节），本站版本 pill 从「v—」第一次显示出版本号。本版是走 bootstrap 路径补切的第一份，从下一个版本起 release notes 全自动。

  • @opentray/spec、@opentray/packaging 与 @opentray/vite-plugin 随本版一起发布 0.21.1。

升级

npm i create-opentray@0.21.1   # 旧版装不上，装过的一定要升
npm i opentray@0.21.1          # SDK 同线

使用官方扩展时锁同一条协议线：pnpm add opentray@stable-A-B @opentray/ext-webview@stable-A-B（协议线 tag 由 @opentray/spec 发布，勿与 latest 混用）。

致谢

感谢 2026-08-20 报告安装失败的那次反馈，devDependencies 的判定规则由此收紧。

链接

jixoai logo jixoai jixoai.com