@tauron/adapter-vue

tauron

Tauri 2 之上的插件化桌面客户端基础设施 —— 插件隔离、受控能力面、跨语言契约与多形态插件执行。

这是什么

tauron 是跑在 Tauri 2 之上的插件化桌面客户端基础设施。它解决的不是「怎么画界面」， 而是「一个桌面客户端要怎么安全地加载第三方代码、把它们互相隔离、给它们受控的能力， 并且能在不重新发版的前提下换掉它们」。

它由两层组成，可以分开取用：

它不是什么

把边界说清楚比列特性更有用：

• 不是成品应用。仓库里唯一能装的是 examples/minimal-app 示例应用， 用来演示链路，不是产品形态的客户端。
• 不是 Tauri 的替代品。它建在 Tauri 2 之上——Tauri 管窗口 / WebView / IPC， tauron 管其上的插件运行时与能力治理。
• 可通过 registry 安装的 SDK。20 个公开 npm 包与 15 个 Rust crate 可从公共 registry 安装 （registry 上的 latest 目前是 1.0.2；本仓库的 1.1.0 已通过发布内容校验， 但尚未执行发布）。计数别搞混：crates/ 下有 16 个成员，第 16 个 tauron-ffi 从未发布过（1.0.2 时代漏发，不是豁免——它没有 publish = false，且在 publish:crates 的发布集合里），所以 registry 上只有 15 个可装。具体接入方式见 安装与使用。
• 当前版本为 1.1.0。公开 API 遵循语义化版本；具体未接入的运行时与平台能力见下方成熟度说明。

成熟度：哪些是真的，哪些还是占位

本项目刻意区分「真实实现」与「接口占位」，用 simulated 字段与诚实失败码表达， 不伪造成功。判断某个能力到底能不能用，看这三处（不要只看本页的特性表）：

• 架构概览的「接线状态（诚实披露）」
• 竞品分析的兑现度标记（带核对日期）
• CHANGELOG 的「已知债务」

一句话概览：信封协议、命令层、双层 ACL、注册表、事件总线、生命周期状态机、设置 中心、崩溃恢复、i18n、通知、白标/主题是真实实现；QuickJS-WASM 引擎接入、Shell 矩阵 的运行时、Process 插件的执行体、更新下载链路是接口占位或模拟原型。

现在适合拿它做什么

准备上手：安装与使用 —— 三种「安装」怎么选、 各平台安装步骤、从源码构建、装完怎么自检。

特性

快速开始（第三方集成）

0. 一键脚手架（推荐起点）

能一键跑通到哪一步——先把边界说清，避免期待错位：

实测（2026-09-27）：生成的工程（含占位图标与 vite 配置）开箱即可编译——默认形态 与 --features substrate-only 两档 cargo check 均通过（Finished dev profile）。

公共 registry 消费验收已覆盖脚手架创建、前端依赖安装与构建、Rust adapter 安装及 Tauri 2 项目编译。 本机 npm run tauri dev 仍需要安装系统 WebView 与 Tauri CLI。另有两条源码开发前置： ① file: 依赖是软链，所以本机 tauron 检出必须已 pnpm install（供 @tauron/host 解析它自己的 workspace:* 依赖）；② packages/*/dist 必须是已构建状态（pnpm -r build）。

# 公共 registry（latest 现为 1.0.2；别点名 @1.1.0，它尚未发布，会 ETARGET）：
npm create tauron-app@latest -- ./my-app --framework react

# 在 Tauron 仓库内开发时，显式启用本地源码依赖：
node packages/tauron-app-cli/dist/cli.js new ./my-app --tauron-path ..

# 一步到位：
cd my-app && npm install && npm run tauri dev

# 或先单独验证「真接上了 tauron」：
cd my-app/src-tauri && cargo check                          # 85 条命令
cargo check --features substrate-only                       # 只取底座：61 条命令

常用参数：--framework react|vue|svelte|vanilla、--shell tauri|electron、 --capabilities host_registry_list,host_lifecycle_report、--tauron-path <检出根相对路径> （显式切换为本地源码）、--dry-run、--force。

已有 Tauri 2 项目改用注入式接入：tauron-app init --dir <你的项目>——它会加固定 1.1.0 依赖、接线 Builder 链，并保留现有权限与 client config；若你原有 .invoke_handler(..) 已存在，它会保留该处理器、报告需要手工合并的步骤，并以非零状态结束。

v1 官方宿主范围为 Tauri 2；React、Vue、Svelte 与原生 TypeScript 是前端选择。其他客户端宿主 须实现自己的 Backend/HostTransport 适配并保留宿主授权边界。详情见支持边界。

1. 安装依赖

SDK 可从公共 registry 安装：20 个公开 npm 包与 15 个 Rust crate（registry 现值 1.0.2；本仓库的 1.1.0 已备好但尚未发布，点名 @1.1.0 现在装不到）；另有 1 个仅供仓库内部测试的私有 npm 包。下面给出最小依赖示例：

# 前端：选择需要的入口包，包管理器会安装其传递依赖
pnpm add @tauron/host @tauron/ui

# src-tauri/Cargo.toml
[dependencies]
tauron-adapter = { version = "=1.1.0", features = ["tauri"] }

本地源码开发可使用 workspace/path 依赖；发布包用户无需手工安装内部依赖。

2. 注册 Rust 命令层

tauron-shell 默认不依赖 tauri，命令注册层由 tauri feature 提供：

# src-tauri/Cargo.toml
[dependencies]
tauron-shell = { version = "=1.1.0", features = ["tauri"] }

// src-tauri/src/main.rs
fn main() {
    tauri::Builder::default()
        // 状态 + 事件出口（不注册命令）
        .plugin(tauron_shell::commands::state_init())
        // root 注册 plugin_invoke / plugin_cancel / plugin_emit
        //（裸命令名，与 @tauron/core createTauriBackend() 直接匹配；
        //  **不是「零 capability」**：Tauri v2 下不匹配任何 capability 的 webview 完全没有
        //  IPC 访问，所以任何形态都至少需要一份 capability 文件，示例已随仓提供。
        //  若改用 .plugin(tauron_shell::commands::init()) 插件形态，
        //  则必须为 `tauron-shell` 插件配置 capability——Tauri v2 对 plugin:* 命令强制 ACL）
        .invoke_handler(tauron_shell::tauron_generate_handler![])
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

⚠️ 上面这段能注册命令，但跑不通一次真实调用：框架层的信封需要 PluginDispatcher 的生产实现，仓库内只有测试用的 EchoDispatcher。 未装载分发器时 plugin_invoke 一律返回 SC-9001（tauron-shell 的 dispatch.rs 明写「装载插件分发器。未装载时 plugin_invoke 返回 SC-9001」）。 想要装完就能用的插件系统，请走应用层（下一节 tauron_adapter::tauron_generate_handler![]）。

3. 初始化前端运行时

// src/main.ts
import { createTauriBackend, invokePlugin } from '@tauron/core';

const backend = createTauriBackend();

// 调用插件
const result = await invokePlugin(
  backend,
  'com.example.formatter',  // 插件 ID
  'format',                 // 方法名
  { code: '  let  x = 1; ' } // 参数
);

if (result.ok) {
  console.log(result.result);  // { formatted: 'let x = 1;' }
}

4. 订阅事件

import { listenEvent } from '@tauron/core';

const unlisten = await listenEvent(
  backend,
  'plugin:com.example.formatter:data-changed',
  (payload) => console.log('Event:', payload)
);

// 取消订阅
unlisten();

调用链：invokePlugin() → createTauriBackend() → Tauri IPC plugin_invoke → tauron_shell::HostState::handle_invoke() → 注册表状态检查 → PluginDispatcher。 命令名、camelCase 字段与错误码由 @tauron/contract-tests 的跨语言门禁锁定。

UI 框架集成

React

import { TauronProvider, useInvoke, useEvent } from '@tauron/adapter-react';

function App() {
  return (
    <TauronProvider backend={backend}>
      <Formatter />
    </TauronProvider>
  );
}

function Formatter() {
  const { state, invoke } = useInvoke('com.example.formatter');
  
  return (
    <button onClick={() => invoke('format', { code: '...' })}>
      {state.loading ? 'Formatting...' : 'Format'}
    </button>
  );
}

Vue

<script setup>
import { useInvoke, useEvent } from '@tauron/adapter-vue';

const { state, invoke } = useInvoke('com.example.formatter');
</script>

Svelte

<script>
import { createInvokeStore } from '@tauron/adapter-svelte';
const { subscribe, invoke } = createInvokeStore('com.example.formatter');
</script>

插件开发

创建插件

# tauron = node packages/tauron-cli/bin/tauron.js（npm 上 @tauron/cli 的 latest 是 1.0.2，落后于仓库源码）
tauron plugin new my-plugin --type js

插件入口 (JS)

import { registerPlugin } from '@tauron/plugin-sdk';

registerPlugin({
  name: 'my-plugin',
  version: '1.0.0',
  methods: {
    async format({ args, ctx }) {
      return { formatted: args.code.replace(/\s+/g, ' ') };
    },
  },
  events: {
    'data-changed': ({ payload }) => payload,
  },
  onEnable(ctx) { console.log('Plugin enabled'); },
});

进程插件 (Process)

const { createServer } = require('net');

const server = createServer((socket) => {
  socket.on('data', (data) => {
    const request = JSON.parse(data.toString());
    const response = handleRequest(request);
    socket.write(JSON.stringify(response) + '\n');
  });
});

配置

import type { TauronConfig } from '@tauron/types';

const config: TauronConfig = {
  capabilities: ['base', 'store', 'network'],
  plugins: {
    local: './plugins',
    registry: 'https://registry.tauron.dev',
    autoUpdate: true,
  },
  shell: {
    type: 'local',
    distDir: './dist',
  },
  updater: {
    endpoints: ['https://updates.tauron.dev'],
    pubkey: 'public-key-hex',
  },
  brands: {
    default: './config/brand.json',
  },
  i18n: {
    defaultLocale: 'zh-CN',
    supported: ['zh-CN', 'en-US', 'ja-JP'],
  },
};

Shell 形态

import { createShellManager } from '@tauron/shell-matrix';

const shell = createShellManager();
const instance = shell.create({
  pluginId: 'com.example.plugin',
  form: 'local-server',
  host: 'localhost',
  port: 8080,
});
await instance.start();

这段代码现在只做状态编排，不拉起真实容器：shell-matrix 的实例恒带 simulated: true（src/manager.ts），start() 只把状态机推到 ready， 不会起本地 HTTP 服务、不会开子 webview、不会加载远程 URL。所以 status: 'ready' 不等于"插件已经跑起来"——判据是那个 simulated 标志， 细节见 packages/tauron-shell-matrix/README.md。本仓里真正加载插件 UI 的路径是 宿主的 host_window_create（plugin-* 标签走安装目录资产协议）与 @tauron/plugin-sdk 的 PluginBridge。

错误处理

import { PluginErrorCode, isRetryable } from '@tauron/types';

try {
  const result = await invokePlugin(backend, pluginId, method, payload);
  
  if (!result.ok) {
    if (isRetryable(result.error!.code)) {
      // 可重试：TIMEOUT, CHANNEL_BROKEN, INTERNAL
      await retry();
    } else {
      throw new Error(`${result.error!.code}: ${result.error!.message}`);
    }
  }
} catch (err) {
  console.error(err);
}

错误码表

权限管理

import { checkPluginPermission, grantPermissions } from '@tauron/core';

// 授予权限
grantPermissions(grants, 'com.example.plugin', [
  'store:read',
  'http:fetch',
  'fs:read-app-dirs',
], 'install');

// 检查权限
const error = checkPluginPermission(
  'com.example.plugin',
  'format',
  ['store:read', 'http:fetch'],
  grants,
);

CLI 工具

⚠️ registry 现状（2026-10-02 实测）：npm 上 @tauron/cli 的 latest 是 1.0.2—— 本仓库的 1.1.0 已通过 pnpm publish:npm -- --check，但还没有 --publish， 所以 npx @tauron/cli 拿到的是 1.0.2 的行为，与当前代码不一定一致。 下文用 tauron 代指 node packages/tauron-cli/bin/tauron.js（在仓库根执行）， 以本仓库代码为准。

# 环境诊断
tauron doctor

# 创建应用（真的落盘；目录已存在需 --force）
tauron create my-app

# 插件开发（真的落盘；--type 支持空格与等号两种写法）
tauron plugin new com.example.myplugin --type js
tauron plugin new com.example.calc     --type wasm

# 以下四条**未实现**，会如实返回 success: false（不谎报、不编造结果）
tauron plugin dev      # 未实现：不启动 dev server
tauron plugin test     # 未实现：不执行测试、不编造通过数
tauron plugin pack     # 未实现：不产出归档
tauron plugin publish  # 未实现：不上传、不编造商城地址

# 已实现：算真实 SHA-256 内容摘要并写出 .sig
tauron plugin sign

各命令的真实边界见 插件开发指南。

项目结构

tauron/
├── crates/                          # Rust 工作区
│   ├── tauron-shell/                # ★ 框架壳层：信封/命令层/ACL/注册表/事件总线/配置
│   ├── tauron-host/                 # 应用宿主核心（注册表/生命周期/授权/清单）
│   ├── tauron-adapter/              # Tauri 命令适配层（host_* 命令族，feature = "tauri"）
│   ├── tauron-acl/                  # 权限授予与审批
│   ├── tauron-schema/               # Schema 规范化管线
│   ├── tauron-settings/             # 设置中心（四层合并）
│   ├── tauron-market/               # 插件商城
│   ├── tauron-brand/                # 白标品牌化
│   ├── tauron-theme/                # 主题 / 皮肤
│   ├── tauron-i18n/                 # 国际化
│   ├── tauron-notify/               # 通知中心
│   ├── tauron-recovery/             # 崩溃恢复
│   ├── tauron-distribute/           # CI 分发运维
│   ├── tauron-proc/                 # 进程插件 Host
│   ├── tauron-wasm/                 # WASM Supervisor
│   ├── tauron-test-sidecar/         # CI 真 sidecar 夹具（`publish = false`，永不上架）：
│   │                                #   可执行 stdio 帧回路端，仅供 tauron-proc 的端到端测试起真进程
│   └── tauron-ffi/                  # 稳定 C ABI 所有权边界（供**非 Rust 宿主**接入 Universal Wire；
│                                    #   仓内没有 Rust 消费者是设计使然，契约见 docs/contracts/ffi-v1.md）
├── packages/                        # npm 包（21 个目录：20 公开 + 私有 `tauron-contract-tests`；下面按层分组）
│   # ── 框架层（12 个）──
│   ├── types/                       # @tauron/types — 信封/错误码/ACL/Manifest/事件
│   ├── tauron-core/                 # @tauron/core — invoke/backend/registry/event-bus/acl/config
│   ├── tauron-plugin-sdk/           # @tauron/plugin-sdk — bridge/context
│   ├── tauron-plugin-context-contract/  # @tauron/plugin-context-contract — 两套 PluginContext 的共享契约
│   ├── tauron-dual-world/           # @tauron/dual-world — QuickJS-WASM 双世界沙箱
│   ├── tauron-adapter-react/        # @tauron/adapter-react — TauronProvider/useInvoke/useEvent
│   ├── tauron-adapter-vue/          # @tauron/adapter-vue — composables
│   ├── tauron-adapter-svelte/       # @tauron/adapter-svelte — stores
│   ├── tauron-cli/                  # @tauron/cli — 插件工具链（bin: tauron）
│   ├── tauron-market/               # @tauron/market — 签名/注册表
│   ├── tauron-shell-matrix/         # @tauron/shell-matrix — 4 种 shell 形态
│   ├── tauron-contract-tests/       # @tauron/contract-tests — TS↔Rust 跨语言门禁
│   # ── 应用层（9 个）──
│   ├── tauron-host/                 # @tauron/host — 能力编排层（HostClient/TauriBackend）
│   ├── tauron-shell-events/         # @tauron/shell-events — 壳层事件名常量（零依赖）
│   ├── tauron-ui-primitives/        # @tauron/ui-primitives — UI 原语（零宿主依赖）
│   ├── tauron-app-cli/              # @tauron/app-cli — 应用脚手架（bin: tauron-app）
│   ├── create-tauron-app/           # create-tauron-app — `npm create` 入口（未 scoped；与 `tauron-app new` 同一实现）
│   ├── tauron-app-plugin-sdk/       # @tauron/app-plugin-sdk — 应用级插件 SDK
│   ├── tauron-app-contract-kit/     # @tauron/app-contract-kit — 应用契约套件
│   ├── tauron-framework/            # @tauron/framework — 框架薄封装
│   └── tauron-ui/                   # @tauron/ui — Lit Web Components
├── examples/
│   └── minimal-app/                 # 最小应用示例（仓库里唯一可打包运行的应用）
└── docs/
    ├── installation.md              # ★ 安装与使用（落地入口：怎么装 / 怎么跑 / 怎么自检）
    ├── architecture/                # 权威架构说明 / 线格式协议 / canonical 归属 / 0.3 方案
    ├── integration/                 # 渐进接入指南（三档装配）
    ├── api/                         # 插件开发指南
    └── competitive-analysis/        # 竞品分析（带兑现度标记）

两层架构说明

• 框架层（@tauron/types / core / plugin-sdk / adapter-* + tauron-shell） 面向通用集成：信封协议 plugin_invoke、PluginType 四形态、插件市场（Ed25519 验签）。 第三方客户端从这一层接入。 ⚠️ 注意：这一层目前没有生产装配——PluginDispatcher 仍是零生产实现， plugin_invoke 三命令无接线（详见架构概览的接线状态表）。
• 应用层（@tauron/host / app-* / framework / ui + tauron-host / tauron-adapter） 面向完整客户端交付：host_* 命令族、生命周期、设置中心、白标。 它复用框架层的类型与协议，但不改变框架层契约。

测试

用例数

单一真源：下表里所有"可复算的静态事实"（#[test] 声明数、测试文件数、crate/package 数、 命令面条数）都由 contracts/facts.json 承载，node scripts/generate-facts.mjs 从代码复算、 pnpm facts:check 复算比对、CI 门禁。README 不再手写这些数字——手写数字即 bug （历史上徽章/正文/各方案曾给出互相矛盾的 1759/1426/1498/1284/1221，无一正确）。

声明数 ≠ 执行通过数（诚实边界）：上表 Rust 一栏是源码里 #[test] 属性的声明数，一个可复算 的静态事实。某次 cargo test 的实际通过数会因 #[ignore]、feature 门（tauri / plugin-install / runtime-wasm-broker）与编译期裁剪而与声明数不同——feature 矩阵的真实执行结果 以 CI 的 Rust (tauri feature) / Rust (minimal substrate) 等 job 为准，本 README 不再钉死一个 会腐烂的"实跑数"。复算命令：node scripts/generate-facts.mjs && node scripts/generate-facts.mjs --check。

本地命令

# 安装依赖
pnpm install

# ── TypeScript ───────────────────────────────
# ⚠️ 顺序不可换：测试从各包的 dist/ 解析 workspace 导入，
#    不先 build 会得到一批 "Failed to resolve import" 的假失败。
pnpm -r build
pnpm -r --no-bail typecheck
pnpm lint             # ESLint（0 error / 0 warning）
pnpm -r --no-bail test

# 等价的一键命令（build → typecheck → test）
pnpm verify

# ── Rust ─────────────────────────────────────
cargo test --workspace                  # 默认特性：不依赖 tauri，无需系统库
cargo test -p tauron-shell   --features tauri
cargo test -p tauron-adapter --features tauri

# 格式化与 lint（硬门禁）
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings

架构设计

┌─────────────────────────────────────────────────────────────┐
│                     前端应用层                                 │
│   React / Vue / Svelte / 原生 TS                              │
├─────────────────────────────────────────────────────────────┤
│                     适配层 (@tauron/adapter-*)                 │
│   useInvoke / useEvent / store / composables                 │
├─────────────────────────────────────────────────────────────┤
│                     核心层 (@tauron/core)                      │
│   invokePlugin / EventBus / ACL / Registry / Config           │
├─────────────────────────────────────────────────────────────┤
│                     类型层 (@tauron/types)                     │
│   信封 / 错误码 / ACL / Manifest / 事件                        │
├─────────────────────────────────────────────────────────────┤
│                     Rust 壳层 (tauron-shell)                   │
│   信封处理 / 错误映射 / 权限检查 / 状态机 / 配置合并           │
└─────────────────────────────────────────────────────────────┘

文档

V4 进度的一句话口径（可核查，改代码时同轮改这里，别凭印象写）：A64–A110 共 47 项 —— 已落 22 / 部分 21 / 未落 4；§134 的 DoD 表逐行数得 ✅ 16 / ⚠️ 15 / ❌ 1。 逐条证据、门禁输出与「本轮未做」清单都在 V4 工业级缺口收口方案。 对外表述维持 「较强的 Tauri-first substrate 基础 + 完整的 Universal/Industrial 演进设计」， 不出现 industrial-grade。

持续集成与发布

发布流程：

# 1. 一条命令写齐全部版本号落点（根 package.json 是唯一事实源 → Cargo workspace、
#    packages/* 的每个 package.json、示例应用的 package.json、它的 src-tauri
#    Cargo.toml 与 tauri.conf.json）：
pnpm version:sync 1.2.0
pnpm version:check     # 同一判定已进 CI；漏改任何一处都会在这里红，而不是在 Release 里
# 2. 更新 CHANGELOG.md 并提交。tag 号必须等于根版本号——release.yml 的 version-check
#    会把它与上述落点逐一比对（此前这一步只有校验器，没有生产者）
git tag v1.2.0 && git push origin v1.2.0

cargo fmt、cargo clippy、ESLint 和应用示例装配均为硬门禁。cargo-deny 自轮 9 复核起也是阻断式硬门禁（ci.yml 的 deny 作业跑 command: check --all-features， 无 continue-on-error）；任何例外必须在 deny.toml 显式登记并附审查说明。 唯一还不在 CI 里的强制项是 main 分支保护——它是仓库设置，需人工开启， 详见 docs/architecture/v4-industrial-gap-closure-plan.md 的 Batch 0-7。

许可证

MIT