契约与细节

tuffite.json

基于权威 schema 生成、可搜索的配置参考。

实验性源码版本。生产安全加固与 SDK 发布仍在进行中。

应用配置文件#

根对象要求 app 和 build。app 定义 identifier、security 和 assets，build.shellApi 定义代码生成。productName 与 bundle 可选。源配置和打包后的应用 manifest 都没有 schemaVersion。additionalProperties 为 false 时拒绝未知属性。使用 tuff check 验证；类型正确并不代表路由和权限语义正确。

json

{
  "$schema": "https://tuffite.org/schema/v2/tuffite.schema.json",
  "productName": "My App",
  "app": {
    "identifier": "org.example.myapp",
    "security": { "capabilities": [] },
    "assets": []
  },
  "build": {
    "shellApi": { "namespace": "myapp", "definitions": ["shell_api.d.ts"] }
  }
}

浏览配置类型#

下面的字段、必填标记、枚举、联合类型和引用直接来自 schemas/tuffite.schema.json。可以按字段或类型名称筛选。没有显示默认值，表示 schema 未声明默认值。

权威 JSON Schemaschema/v2

root

对象不接受未知字段

$schema

string

编辑器验证所用的 JSON Schema 地址。

app必填

app

应用标识、安全、窗口、原生 API 和资源。

build必填

build

代码生成、开发包、Web 服务器和调试设置。

bundle

bundle

应用包包含的资源。

productName

string

应用显示名称与 bundle 名称，默认使用 Cargo 包名。

Application display name and default bundle name. Defaults to the Cargo package name. Use a portable filename (up to 128 UTF-8 bytes); spaces and Unicode are supported.

app

对象不接受未知字段

identifier必填

string

应用标识，通常使用反向域名形式。

security必填

security

内容安全策略和按 origin 限定的能力。

windows

window[]

初始原生窗口配置。

assets必填

assetRoute[]

请求 origin / 路径到资源文件的显式映射。

network

network

应用网络策略。

utilities

object

security

对象不接受未知字段

csp

string

前端 Content-Security-Policy。

格式: ^[^\r\n]+$

capabilities必填

originCapability[]

针对明确匹配 origin 的原生权限。

window

对象不接受未知字段

label必填

string

应用可见的窗口标签。

url必填

string

原生窗口的初始页面 URL。

title

string

x

integer

y

integer

width必填

integer

初始窗口宽度。

min: 1 · max: 16384

height必填

integer

初始窗口高度。

min: 1 · max: 16384

focused

boolean

decorations

boolean

minWidth

integer

min: 1 · max: 16384

minHeight

integer

min: 1 · max: 16384

maxWidth

integer

min: 1 · max: 16384

maxHeight

integer

min: 1 · max: 16384

build

对象不接受未知字段

devPackage

string

刷新后的原生开发包目录。

devUrl

string

经过认证的开发覆盖所使用的回环前端地址。

beforeDevCommand

string | object

在原生开发窗口前启动的命令。

beforeBuildCommand

string | object

devtoolsPort

integer

回环 Chrome DevTools Protocol 端口。

min: 1 · max: 65535

profile

string

shellApi必填

object

类型化代码生成的命名空间与声明文件。

build.shellApi

对象不接受未知字段

namespace必填

string

格式: ^[A-Za-z_$][A-Za-z0-9_$]*$

definitions必填

stringArray

facade

"application" | "framework"

bundle

对象不接受未知字段

executable

string

resources

stringArray

需要包含在应用包中的文件和目录。

icons

object

bundle.icons

对象不接受未知字段

macos

string

Project-relative .icns icon; defaults to Tuffite.

windows

string

Project-relative .ico icon; defaults to Tuffite.

originCapability

对象不接受未知字段

identifier必填

string

格式: ^[A-Za-z0-9_-]+$

description

string

origins必填

string[]

shellApi

shellApiEntry[]

explorer

object

originCapability.explorer

对象不接受未知字段

create

boolean

executeJavaScript

boolean

network

对象不接受未知字段

disableHttp2

boolean

maxResponseBytes

integer

min: 1 · max: 5242880

timeoutSeconds

integer

min: 1 · max: 300

assetRoute

对象不接受未知字段

origins必填

string[]

paths必填

string[]

file

string

directory

string

shellApiEntry.variant2

对象不接受未知字段

method必填

string

格式: ^(?:\*|(?:[A-Za-z_$][A-Za-z0-9_$]*\.)+(?:[A-Za-z_$][A-Za-z0-9_$]*|\*))$

allow

value[]

deny

value[]