Pake 的 Rust/Tauri 工程铁律：CLI 错误处理、配置类型安全与 IPC 信任边界

本文基于 Pake 仓库中的规则文件 .claude/rules/rust.md 展开，系统讲解该项目的三组核心工程约定：面向用户的错误处理规范、Tauri 配置的类型安全要求，以及“打包进应用的远程页面不可信”这一 Tauri 信任边界原则。读完本文，你可以掌握 Pake 中 PakeError、--json 机器模式、PakeTauriConfig 类型体系的完整落地方式，并能理解为什么 Pake 强调“永远不要靠 grep 错误消息来分类构建失败”。

规则文档的定位：Pake 特有的 Rust + Tauri 约束

Pake 是一个“一条命令把任意网页打包成桌面应用”的工具（Turn any webpage into a desktop app with one command）。它的技术栈分为两层：

• CLI 构建层（TypeScript，位于 bin/ 目录）：负责解析参数、合并配置、驱动 Tauri/cargo/linuxdeploy 等子进程完成打包；
• 运行时壳层（Rust + Tauri，位于 src-tauri/ 目录）：被打包进每一个生成的桌面应用，负责窗口管理、导航保护、IPC 命令等运行时行为。

.claude/rules/rust.md 开篇即声明了自身边界：

标准 Rust 卫生（? 优先于 unwrap()、cargo clippy 零告警、提交前 cargo fmt）默认成立，不再重复；dist/cli.js 的重建规则、CN 镜像策略、平台敏感规则（Linux/Wayland WebKit 合成、AppImage 警告噪音、--incognito、内嵌 WebView OAuth 等）都放在 AGENTS.md（Current Risk Areas / Network Mirror Behavior 章节），本文不重复。

也就是说，这份规则文件聚焦的是三件跨两层技术栈都必须守住的 Pake 特有约定：错误处理、配置类型、Tauri 信任边界。下面逐一拆解，并用仓库源码印证每条规则的落地实现。

错误处理：四条铁律与它们的源码实现

规则原文对错误处理提出了四条要求，每一条都能在 bin/ 目录下找到对应的实现证据。

铁律 1：用户可达路径上禁止 panic! / .unwrap() / .expect()

在用户可达的路径上（CLI 选项解析、配置加载、事件处理器、IPC 命令）不得使用 panic! / .unwrap() / .expect()，应使用 ? 向上抛出并给出清晰信息。

这条规则横跨两层代码。Rust 侧对应 src-tauri/ 中被打包进用户应用的代码——一旦用户在某个打包出来的应用里触发 IPC 命令崩溃，整个桌面应用直接挂掉，这比 CLI 报错严重得多。TypeScript 侧对应 CLI 的任何用户交互路径。

铁律 2：静默吞错必须至少升级为 logger.warn

TS 中的 catch {} 或 Rust 中的 let _ = ... 这类静默吞错，至少要通过 logger.warn 把真实错误暴露出来。注意 logger.warn 同时会流入 --json 结果的 warnings 数组；状态行应使用 logger.info。

这里的细节很值得展开。Pake 的日志封装在 bin/options/logger.ts 中，基于 loglevel + chalk 实现 info/debug/error/warn/success 五个方法。而在机器模式下（--json），bin/utils/output.ts#L56-L67 中的 enableMachineMode() 会接管 loglevel 的 methodFactory：所有日志被重定向到 stderr，其中 warn 级别的条目会被额外捕获进 capturedWarnings，最终进入 JSON 结果的 warnings 数组。

这意味着 logger.warn 和 logger.info 的语义分界不是随意偏好，而是契约：warn 会被机器读到（进入 warnings: string[]），info 只作为人类可读的状态行。规则文档特意点出这一点，bin/builders/BaseBuilder.ts#L240-L244 中的注释也是同一逻辑：

// Show static message to keep the status visible. Info, not warn: warn
// entries feed the --json warnings array and this is a status line.
logger.info('✸ Building app...');

--json 模式下最终输出的结构定义在 bin/utils/output.ts#L35-L47：

export interface PakeJsonResult {
  ok: boolean;
  name: string | null;
  platform: NodeJS.Platform;
  arch: string | null;
  outputs: BuildArtifact[];
  warnings: string[];   // ← logger.warn 的捕获结果
  error: {
    code: PakeErrorCode;
    message: string;
    hint: string | null;
  } | null;
}

铁律 3：可预期的失败抛 PakeError {code, hint}，退出码稳定可映射

可预期的 CLI 失败应抛出带 {code, hint} 的 PakeError（定义于 bin/utils/error.ts）：code 映射到稳定的退出码和 --json 错误对象；普通的 Error 则由 bin/cli.ts 按构建阶段（build phase）分类。

实现见 bin/utils/error.ts#L12-L35：

export class PakeError extends Error {
  readonly isUserError = true;
  readonly code?: PakeErrorCode;   // INVALID_INPUT | ENV_MISSING | BUILD_FAILED | NETWORK | UNEXPECTED
  readonly hint?: string;          // 给用户的下一步建议
  // ...
}

退出码契约写死在 bin/utils/output.ts#L19-L27：

code	退出码	含义
INVALID_INPUT	2	输入不合法
BUILD_FAILED / NETWORK	3	构建或网络失败
ENV_MISSING	4	缺少运行环境（如未装 Rust）
UNEXPECTED	1	未预期错误

bin/cli.ts 顶层的 classifyError 逻辑遵循“带显式 code 的 PakeError 优先于阶段默认值”的原则：如果抛出的不是 PakeError，则按当前所处阶段（input → prepare → build，见 bin/cli.ts 中 phase 变量的推进）套用阶段默认 code。这样 CI/Agent 可以仅凭退出码判断失败类别，不需要解析终端文本。一个真实用例：BaseBuilder.prepare() 检测不到 Rust 且处于非交互模式时，抛出 new PakeError('Rust required to package your webapp.', { code: 'ENV_MISSING', hint: 'Install Rust via https://rustup.rs, then rerun the same command.' })（见 bin/builders/BaseBuilder.ts#L135-L157）。

铁律 4：--json 机器模式下 stdout 只属于唯一的 JSON 结果

机器模式下 stdout 被唯一的 JSON 结果独占。bin/ 中任何地方都不得 console.log / process.stdout.write；子进程 stdout 由 shellExec 重定向到 stderr。

这条规则的实现分两处：

1. 日志层：enableMachineMode() 将所有 loglevel 输出改写到 console.error（stderr），并关闭 chalk 颜色，保证 stdout 干净可 JSON.parse；
2. 子进程层：bin/utils/shell.ts#L11-L19 中 execa 的 stdio 配置为 stdout: isMachineMode() ? process.stderr : 'inherit'——交互模式实时透传（linuxdeploy、cargo、npm 的输出即时可见），机器模式重定向到 stderr。

shellExec 陷阱：为什么不能靠 grep error.message 分类构建失败

规则文档中最有分量的一段是：

shellExec 用 stdio: 'inherit' 运行子进程，因此它们的输出（linuxdeploy、cargo、npm）永远不会进入 error.message，只有失败的命令行会进入。不要通过 grep error.message 来分类构建失败——那匹配到的是命令，而不是诊断信息。失败引导应基于调用方持有的结构化事实（例如 target === 'appimage'）。责任方：bin/utils/shell.ts + bin/builders/BaseBuilder.ts。

这个约束的根源在 bin/utils/shell.ts#L25-L40：stdio: 'inherit' 意味着子进程诊断直接流到终端，execa 抛出的 error.message 里只包含命令字符串本身。所以“从错误文本判断失败原因”这条路在架构上就是死的。

正确的做法示范就在 bin/builders/BaseBuilder.ts 的 Linux AppImage 失败处理中：调用方天然持有结构化事实 isLinuxAppImage = process.platform === 'linux' && target === 'appimage'（L255-L256），于是它：

• 第一次构建失败后，基于该事实自动用 NO_STRIP=1 重试一次（glibc 2.38+ 的 strip 兼容问题是 AppImage 最常见的失败原因）；
• 重试仍失败时，把 APPIMAGE_FAILURE_GUIDANCE（L34-L53）追加到错误消息中——这份引导不声称知道具体原因（注释明确写道 “we cannot name the exact cause”），而是列出全部已知原因与修复命令：gdk-pixbuf loaders 缺失（给出 Arch/Debian/Fedora 三种发行版的安装命令）、Docker 容器缺 /dev/fuse 时的启动参数、以及退路方案 pake <url> --targets deb（详细指南指向 docs/faq.md）。

这个设计是“铁律 3 + 铁律 4”的合力产物：hint/引导文本承担给人类的下一步建议，退出码与 code 承担给机器的分类，而具体诊断则留在终端由用户自行阅读——三层各司其职。

配置类型安全：禁止 tauriConf: any

规则原文：

不允许 tauriConf: any 或其他无类型配置袋。使用 PakeTauriConfig。 窗口选项分布在 bin/helpers/cli-program.ts、bin/types.ts、bin/defaults.ts、bin/helpers/merge.ts 四处。新增一个选项意味着要同时改这四个文件，再加上 schema/pake.schema.json 和 docs/cli-usage*.md。漏掉任何一个都是回归；其中 schema 那半边由 tests/unit/config-file.test.ts 兜底。

这条规则针对的是 Pake 的工作流本质：CLI 选项最终会被合并写进一个临时的 src-tauri/.pake/tauri.conf.json 供 Tauri 构建使用（见 bin/builders/BaseBuilder.ts#L475-L483）。如果配置是无类型的 any 袋，任何一个拼写错误都只会表现为“选项悄悄不生效”，而不是编译错误。

类型体系定义在 bin/types.ts，核心有三个接口：

• PakeTauriConfig（L213-L241）：对 Tauri 配置结构的类型化描述，包含 productName、identifier、version、mainBinaryName、pake: PakeConfig、bundle（含各平台细分字段）等；
• PakeConfig / WindowConfig（L171-L211）：Pake 自有配置块的结构，WindowConfig 的字段（hide_title_bar、always_on_top、internal_url_regex、zoom、min_width 等）与 CLI 选项一一对应；
• PakeCliOptions（L4-L159）：全部 CLI 选项的完整类型定义，每个字段带默认值注释（如 width 默认 1200、zoom 默认 100、bundle 默认 true 等），可作为参数速查表。

运行时装配逻辑在 bin/helpers/tauriConfig.ts：它从 npm 包目录读取 src-tauri/pake.json 和 tauri.conf.json，再按 process.platform 选择 tauri.windows.conf.json / tauri.macos.conf.json / tauri.linux.conf.json 之一，仅取其中的 bundle 与 app.trayIcon 平台差异字段，合并出最终基线配置。

“新增选项五处必改”清单（cli-program.ts 解析 + types.ts 类型 + defaults.ts 默认值 + merge.ts 合并 + schema/pake.schema.json 校验 + docs/cli-usage*.md 与 docs/cli-usage_CN.md 文档）本质上是一张变更影响面清单；tests/unit/config-file.test.ts 负责在测试中拦截“schema 忘了加字段”这一类最常见的遗漏。

Tauri 信任边界：打包进去的远程页面是不可信输入

规则原文（三条要求）：

打包进应用的远程页面是不可信的。每个 #[tauri::command] 的输入都必须做语义边界校验；远程页面的 capability 保持“恰好够用”；长时间运行的 IPC 保持异步，让页面代码无法阻塞应用主循环。

为什么这是 Pake 必须单独写进规则的一条？因为 Pake 打包的恰恰是任意的第三方网页——任何用户都可以对任何 URL 执行 pake <url>。生成的应用里，WebView 加载的页面代码与 Rust 侧的 Tauri 命令之间只隔一层 IPC + capability 声明，这条边界一旦被突破，远程网页就能以桌面应用的身份调用受限能力。

三处实现印证：

1. 命令输入做语义边界校验。 src-tauri/src/app/invoke.rs 中集中了应用的全部 #[tauri::command]（位于 L103、L180、L193、L200、L208、L214、L221、L237、L248 共九处）。以 macOS Dock 角标的命令为例，invoke.rs#L17-L37 展示了“语义边界”的校验方式——不是仅做类型检查，而是约束取值域：

const MAX_BADGE_COUNT: i64 = 99_999;
const MAX_BADGE_LABEL_CHARS: usize = 16;

fn normalize_badge_count(count: Option<i64>) -> Option<i64> {
    count.filter(|n| (1..=MAX_BADGE_COUNT).contains(n))
}

fn normalize_badge_label(label: Option<&str>) -> Result<Option<String>, String> {
    let Some(label) = label.map(str::trim).filter(|label| !label.is_empty()) else {
        return Ok(None);
    };
    if label.chars().count() > MAX_BADGE_LABEL_CHARS {
        return Err(format!("Badge label must be {MAX_BADGE_LABEL_CHARS} characters or fewer"));
    }
    Ok(Some(label.to_owned()))
}

Option 输入归一化、闭区间范围约束、超长/非法值返回 Err 而非 panic——正是铁律 1 在 Rust 侧的体现。

2. capability 最小化。 Tauri v2 的权限模型通过 src-tauri/capabilities/default.json 声明每个窗口可触达的插件与命令集合。规则要求该集合保持“精确到刚好覆盖所需操作”，即不为打包的网页开放超出运行时功能需要的能力面。

3. IPC 异步化。 规则要求长时间运行的命令保持异步，从源码结构看，invoke.rs 中的命令函数普遍以 async fn ... -> Result<..., String> 形态返回错误字符串而非抛出 panic（配合 Tauri 的异步命令机制），这样页面侧即使发起慢命令，也不会卡死应用主循环——而卡死主循环的正是远程页面可能达到的最坏后果之一。

小结：一套可对照的工程检查清单

把 .claude/rules/rust.md 的约定浓缩成一张改动前的自检清单，每条都附仓库内可验证的依据：

检查项	依据文件
用户可达路径无 panic!/unwrap()/expect()，错误用 ? 上抛	规则原文 + src-tauri/src/app/invoke.rs 的 Result 返回范式
静默吞错至少 logger.warn；状态行走 logger.info	bin/options/logger.ts、bin/utils/output.ts#L56-L67
可预期失败抛 PakeError {code, hint}，退出码按契约映射	bin/utils/error.ts、bin/utils/output.ts#L19-L27
--json 模式 stdout 只输出一个 JSON；子进程输出重定向 stderr	bin/utils/shell.ts#L11-L19
失败引导基于调用方结构化事实（如 target === 'appimage'），不 grep error.message	bin/builders/BaseBuilder.ts#L255-L295
配置一律走 PakeTauriConfig，禁止 any 配置袋	bin/types.ts#L213-L241
新增窗口选项：四处代码 + schema + 文档，缺 schema 由测试兜底	tests/unit/config-file.test.ts、schema/pake.schema.json
#[tauri::command] 输入做语义边界校验、capability 最小化、IPC 保持异步	src-tauri/src/app/invoke.rs#L17-L37、src-tauri/capabilities/default.json

这套规则的共同指向只有一个：Pake 的输出物是面向最终用户的桌面应用，其构建器（CLI）和运行时壳（Tauri）都必须做到——错误永远以结构化、可预期的形式呈现，配置永远有类型契约兜底，来自网页的一切都按不可信输入对待。