SurplusToken Desktop

SurplusToken 的 Windows 10/11 与 macOS 12+ 桌面工作台。应用使用 Tauri 2、Vue 3 和 Rust，范围仅包含登录、 账户概览、API Key 列表/创建，以及 Codex/Claude Code 本地配置、备份和恢复。

安装

Windows：从发布产物运行 SurplusToken_0.1.0_x64-setup.exe。未签名安装程序可能触发 SmartScreen“未知发布者”提示；安装范围为当前用户，不要求管理员权限。

macOS：打开 SurplusToken_0.1.0_aarch64.dmg（Apple Silicon）或 SurplusToken_0.1.0_x64.dmg（Intel），将应用拖入“应用程序”。未签名、未公证的开发构建会被 Gatekeeper 拦截，正式分发前需要 Developer ID 签名与 Apple 公证。

应用依赖 Microsoft Edge WebView2 Runtime。Windows 11 通常已预装；Windows 10 缺失时按 安装程序提示安装 WebView2 后重新启动 SurplusToken。

卸载 SurplusToken 不会删除或回滚 Codex/Claude Code 的用户配置，也不会自动删除应用备份。 需要回滚时应在卸载前从“本地配置”页面恢复目标备份。

本地开发

要求 Node.js 24+、npm 11+ 和 Rust stable。Windows 还需要 MSVC、Visual Studio 2022 C++ Build Tools、Windows SDK 和 WebView2 Runtime；macOS 需要 Xcode Command Line Tools。

npm ci
npm run typecheck
npm run lint
npm run test -- --run
npm run cargo:test
npm run tauri dev

macOS 使用相同命令（在 zsh 中无需 PowerShell 语法）。

完整回归：

npm run security:scan
cargo fmt --manifest-path src-tauri/Cargo.toml -- --check
cargo clippy --manifest-path src-tauri/Cargo.toml --all-targets -- -D warnings
cargo clippy --manifest-path src-tauri/Cargo.toml --features e2e --all-targets -- -D warnings
npm run tauri build

npm run cargo:test 会在 Rust 测试前后比较真实 Codex/Claude 配置的存在状态、长度和 SHA-256，任何变化都会使命令失败。

自动发布与更新

应用进入已登录工作区后会静默检查一次更新，用户菜单也提供“检查更新”。只有公开的最新 GitHub Release 会进入更新通道；草稿 Release 不会被客户端发现。发现更新后，用户需要确认 下载和安装，完成后应用自动重启。

发布前先在仓库外生成并备份 updater 签名密钥：

npm run tauri signer generate -- -w "$HOME/.tauri/surplustoken-updater.key"

将私钥文件完整内容和生成时使用的密码分别配置为 GitHub Actions Secrets：

• TAURI_SIGNING_PRIVATE_KEY
• TAURI_SIGNING_PRIVATE_KEY_PASSWORD

两项都是发布硬依赖，私钥或密码丢失后，已安装客户端无法验证后续更新。私钥、密码、PFX、 P12 和 P8 文件不得进入仓库。

Windows Authenticode 是可选配置；启用时必须同时配置：

• WINDOWS_CERTIFICATE：PFX 文件的 Base64 内容
• WINDOWS_CERTIFICATE_PASSWORD
• WINDOWS_CERTIFICATE_THUMBPRINT
• WINDOWS_TIMESTAMP_URL

macOS Developer ID 签名与公证也是可选配置。签名必须同时提供 APPLE_CERTIFICATE、APPLE_CERTIFICATE_PASSWORD、APPLE_SIGNING_IDENTITY，并选择一组 公证凭据：

• Apple ID：APPLE_ID、APPLE_PASSWORD、APPLE_TEAM_ID
• App Store Connect API：APPLE_API_KEY、APPLE_API_ISSUER、APPLE_API_KEY_CONTENT

未配置 Windows 证书时仍生成未签名 NSIS；未配置 Apple 证书时使用 ad-hoc identity 生成未 公证的 macOS 资产。任一可选配置只提供部分值都会使发布提前失败。

从与 origin/main 完全一致且干净的 main 发布稳定版本：

npm run release:bump -- 0.2.0

命令会同步 npm/Cargo 版本、运行完整检查、创建 chore: release v0.2.0 commit 和 tag，并通过 一次原子 push 推送两者。--dry-run 只检查版本方向并展示操作；--no-push 会保留本地 commit 和 tag。tag workflow 构建 Windows x64 安装版、Windows x64 portable 版、macOS ARM64 和 macOS Intel 资产，并创建 GitHub 草稿 Release。portable 压缩包包含 SurplusToken.exe 和 SurplusToken.portable 标记文件，解压后须保留二者在同一目录；portable 客户端会使用独立的 签名更新目标，在退出后原位替换可执行文件并自动重启。

公开草稿前必须检查三个平台安装包、Windows portable 压缩包、updater 包、每个签名文件及 latest.json，并核对 Actions Summary 中的平台签名状态。草稿有问题时删除草稿和远端 tag， 修复后重新发布同一版本；版本一旦公开，不再替换其资产或签名。公开版本需要回滚时发布更高的 补丁版本，客户端不会自动降级。

隔离 E2E

开发模式 E2E 使用独立的 Tauri identifier、内存凭据存储、本地 mock API 和仓库内临时根目录， 不会读取或写入真实 Windows Credential Manager / macOS Keychain、用户目录中的 .codex、 .claude 或生产 API。先启动 mock API：

node scripts/mock-api-server.mjs

再在另一个终端启动隔离应用：

$env:SURPLUSTOKEN_E2E_USERPROFILE="$PWD\.e2e-runtime\user"
$env:SURPLUSTOKEN_E2E_APPDATA="$PWD\.e2e-runtime\appdata"
npm run tauri -- dev --features e2e --config src-tauri/tauri.e2e.conf.json --target-dir src-tauri/target-e2e

macOS / zsh：

export SURPLUSTOKEN_E2E_USERPROFILE="$PWD/.e2e-runtime/user"
export SURPLUSTOKEN_E2E_APPDATA="$PWD/.e2e-runtime/appdata"
npm run tauri -- dev --features e2e --config src-tauri/tauri.e2e.conf.json --target-dir src-tauri/target-e2e

该模式只用于合成数据验证。提交、截图和日志仍不得包含真实凭据。

安全边界

• 密码、TOTP、Turnstile token 和 2FA 临时 token 仅存在于当前登录组件内存。
• access token 仅存在于 Pinia 内存状态，不进入 localStorage、sessionStorage、URL 或日志。
• refresh token 仅保存在当前用户的系统凭据存储（Windows Credential Manager 或 macOS Keychain），服务名以 com.surplustoken.desktop/refresh-token 开头。
• API Key 默认掩码显示，仅存在于应用内存和用户明确确认写入的工具配置文件中。
• 普通偏好仅保存上次邮箱、主题、选中的 Key ID 和脱敏的最近配置结果。
• 生产 HTTP capability 仅允许 https://surplustoken.com/**；模型网关地址与业务 API Root 分离并固定校验。

不要把真实密码、token 或完整 Key 写入 issue、截图、日志、fixture、环境示例或提交记录。

工具配置

SurplusToken 只会处理以下固定路径：

• ~/.codex/config.toml
• ~/.codex/auth.json
• ~/.claude/settings.json

Codex 配置写入 surplustoken provider，并把 Key 写入 auth.json 的 OPENAI_API_KEY。Claude Code 配置写入 settings.json.env 的网关变量。应用使用结构化合并，保留用户模型、MCP、插件、 features、permissions、hooks、注释和未知字段；损坏或非 UTF-8 文件会中止而不是覆盖。

完整 API Key 会以明文进入上述工具配置。配置前的原文件也可能已经含有明文，因此备份同样 按原始字节保存秘密。备份目录是：

• Windows：%APPDATA%\com.surplustoken.desktop\backups\<tool>\<backup-id>
• macOS：~/Library/Application Support/com.surplustoken.desktop/backups/<tool>/<backup-id>

每个工具仅保留最近五个完整备份。manifest 只保存目标标识、存在状态、长度和 SHA-256，不 保存解析内容或请求参数。配置或恢复后必须重启对应的 Codex/Claude Code；应用不会自动启动 或终止这些工具。

恢复

在“本地配置”中选择最近备份并确认恢复。应用先校验全部备份字节和 SHA-256，再备份当前 状态，随后逐字节恢复。原来不存在的文件会恢复为不存在；路径穿越、绝对路径和损坏 manifest 会被拒绝。恢复前生成的新备份可用于撤销本次恢复。

已知限制

• 自动更新已启用，但 Windows Authenticode 和 macOS Developer ID/公证取决于发布仓库是否配置 对应的可选 Secrets；未配置时仍会出现 SmartScreen 或 Gatekeeper 提示。
• Turnstile 启用前，服务端必须确认允许 Tauri WebView 的实际 hostname；客户端不会绕过限制。
• Claude 仅接受 Anthropic、Antigravity 或服务端明确允许 Messages 转发的 OpenAI 分组。
• 自动化测试只使用临时用户目录，绝不读写运行者真实 .codex 或 .claude 配置。
• Windows 与 macOS 的安装、卸载、系统安全提示和真实生产账号只读冒烟需要在独立人工验收环境完成。

API 契约见 docs/api-contract.md，关键决策见 docs/decisions.md，当前完成证据和剩余人工门槛见 docs/completion-audit.md。