RustFox 用户使用手册

面向最终用户。不需要安装 Rust、不需要任何命令行知识，下载、解压、双击即可使用。

适用版本：RustFox 0.0.x（最新验证 0.0.25，版本差异见 CHANGELOG.md）
支持平台：Windows 10/11、macOS 11+、Linux（常用桌面环境）

1. 安装与启动

1.1 Windows

方式	步骤
安装包（推荐）	下载 `RustFox-<版本>-setup.exe` → 双击运行 → 按提示完成安装 → 桌面出现 RustFox 快捷方式，开始菜单出现「RustFox」程序组

首次运行如弹出「Windows 已保护你的电脑」（SmartScreen），点击「更多信息」→「仍要运行」即可。这是因为安装包尚未购买代码签名证书，属正常现象。

1.2 macOS

下载 RustFox-<版本>-<架构>.dmg（Apple Silicon 选 aarch64，Intel 选 x64）
挂载后把 RustFox.app 拖入「应用程序」文件夹
首次打开：右键 RustFox.app →「打开」，或「系统设置 → 隐私与安全性 → 仍要打开」。应用未购买 Apple 开发者证书（仅 ad-hoc 签名、未公证），Gatekeeper 会提示「无法验证开发者」——这是正常现象，不是应用损坏，确认后即可使用
若提示「"RustFox"已损坏，无法打开」（旧版本安装器未签名的遗留问题），打开「终端」执行以下命令解除隔离后重试：
```
xattr -cr /Applications/RustFox.app
```

之后可从「启动台」或「应用程序」双击启动，也可固定到 Dock。

应用内「关于 → Check for Updates」的自动更新不受影响：更新器替换应用后不会重新打隔离标记，升级后可直接打开。

1.3 Linux

下载 rustfox-<版本>-amd64.deb（Debian/Ubuntu）或 .AppImage 直接运行
Debian 系安装：sudo apt install ./rustfox-<版本>-amd64.deb

Linux 运行依赖系统的 WebKit/GTK 库（webkit2gtk-4.1、gtk-3）。启动报 libwebkit2gtk 缺失时，按发行版安装对应软件包。

1.4 首次启动

启动后自动初始化本地数据库（无需联网、无需注册），直接进入主界面：

┌─────────────────────────────── RustFox ───────────────────────────────┐
│ RustFox │ [选择项目 ▼] │ [未选环境 ▼] │       搜索接口 │ 反馈 │ 设置 ⚙ │
├─────────────────────────────────────────────────────────────────────────┤
│                          🦊  开始使用 RustFox                             │
│                   创建你的第一个项目，开始管理 API                            │
│                          [ 创建项目 ]                                      │
└─────────────────────────────────────────────────────────────────────────┘

2. 界面总览

区域	作用
顶部栏	项目切换、环境切换、Mock 状态、接口搜索、文档/Mock 菜单、设置入口
首页	统计卡片、项目卡片、创建/进入项目、快速请求
工作区	左侧目录树 + 顶部标签栏 + 接口编辑器 + 响应面板
设置页	环境变量、OpenAPI 导入导出、Mock Server、备份恢复

首页布局：

RustFox 首页布局

工作区布局：

RustFox 工作区布局

3. 项目管理

首页点击「创建项目」，输入名称与基础地址（base_url，如 https://api.example.com）。
进入项目后左侧为目录树：文件夹 / 接口分层管理；顶栏可切换项目。
目录树支持多选：Ctrl/⌘ 点击多选、Shift 同层连选，选中后批量删除 / 批量移动到文件夹。
删除接口 / 文件夹（夹子树）后 Toast 提供**「撤销」**（单级，8 秒内有效）。
快捷键总览：顶栏「键盘」图标或 Ctrl+/ 打开快捷键帮助。
项目数据全部保存在本机（见第 8 节），可随时在设置页备份 / 恢复。

3.1 团队管理与团队同步

项目按团队分组管理（首期团队仅是项目容器，不做成员权限）：

团队管理：首页工具栏「团队管理」可新建 / 重命名 / 删除团队（有项目的团队不可删除）；新建项目弹窗可选择归属团队或行内新建；团队组头「＋新建」快捷预选该团队。
同步远端：进入项目 →「团队同步」为团队配置一个 git 仓库地址（SSH git@host:path 或 HTTP(S) 均可）。同团队多个项目、不同团队均可复用同一仓库，仓库内按 projects/{项目id}.json 分文件互不覆盖。S3 / 数据库远端开发中。
推送：把当前项目的完整快照（接口 / 环境 / Mock / 用例）推送到团队远端。推送前自动脱敏凭证类字段（Token / 密码 / API Key 等不出本机），结果回显被过滤项。
拉取：先预览远端与本地的接口差异（新增 / 删除 / 修改清单），确认后才覆盖；覆盖前自动留档本地快照（数据目录 sync/backups/），可回滚。拉取后还原本机凭证。
导入新项目：首页团队组头「同步」可浏览远端全部项目快照，把同事推送的新项目一键导入为本地项目（归属该团队）。

同步是显式快照动作而非实时协同：本地 SQLite 仍是唯一真源，推/拉由你主动触发。凭证永不离开本机（脱敏后推送），拉取覆盖后工作区自动全量刷新。

4. 编写与发送请求（核心功能）

工作区结构：

┌─ 项目树 ──────┬───────────────────────────────────────────────────────┐
│ ▾ my-app      │  [标签1 ●] [标签2]  ＋新建                              │
│  ▾ 用户模块    │  [GET ▼]  https://api.example.com/users/{id}  [保存][发送]│
│    GET 用户列表│  ┌ Params │ Headers │ Body │ Auth │ Tests │ Docs ───┐ │
│    POST 创建用户│  │ key        value                                  │ │
└───────────────┴─┴──────────────────────────────────────────────────┴─┘

步骤	操作
打开接口	点击左侧目录中的接口 → 在顶部标签栏打开（再次点击已在标签中则激活）
新建接口	标签栏「＋新建」，或目录中新建文件夹/接口
编辑参数	Params 标签插入 Query 参数；Headers 加请求头（启用开关控制是否随请求发送）
编辑 Body	Body 标签 6 种模式：none / form-data / x-www-form-urlencoded / raw（JSON/Text）/ binary（本地文件路径，后端读字节发送）/ GraphQL（query + variables + operationName），JSON 模式有格式化/压缩/复制按钮
认证	Auth 标签选择认证方式（None / Basic / Bearer / API Key / OAuth2，OAuth2 覆盖授权码 / 客户端凭证 / 密码 / 隐式四模式，令牌自动附加）
保存	点「保存」；未保存修改在标签标题上以 ● 标记，切换标签不会丢失草稿

发送请求：点绿色「发送」按钮，右侧显示状态码、耗时、大小、响应头与响应体；最近的请求自动记入「历史」（地址栏下方）。

多个标签可同时编辑不同接口，每个标签独立草稿；关闭未保存标签会先提示。

4.1 变量

请求中的任何位置支持 {{变量名}}：

{{base_url}}、{{token}} 等来自当前环境（设置页）
项目变量在设置页「项目变量」配置
发送与「生成代码」「压测」时自动完成替换，无需手改

4.2 GraphQL 调试视图

顶栏「GraphQL 工作台」（路由 /graphql，独立于目录树）：

输入接口地址（支持 {{变量}}）、Query、Variables、OperationName，一键发送。
响应按 GraphQL 语义区分 data 与 errors（有 errors 即按业务失败优先展示）。
可保存为目录树接口（Body 模式 graphql），也可生成 cURL / JavaScript(fetch) 代码。
历史记录保存在本机浏览器存储（rustfox_graphql_history），与请求历史相互独立。

4.3 实时调试（WebSocket / SSE）

顶栏「⚡实时调试」按钮（路由 /realtime，可在新窗口打开边工作边监控）：

WebSocket：输入 ws:// 地址连接，收发文本帧 / Ping，断线按开关自动重连；消息日志上限 500 条。
SSE：输入 http(s):// 地址订阅，事件流按帧解析（event/data/id），支持 Last-Event-ID 续传位点展示。

5. 环境管理

设置页 →「环境管理」（环境按项目归属：在哪个项目就编辑哪个项目的环境，互不干扰）：

「新建环境」输入环境名与变量（键/值）；每个环境配一个Base URL（可含 {{变量}}）与全局变量 / 全局参数。
顶部栏切换环境，发送请求时自动替换变量；解析优先级：环境 > 项目。
激活环境按项目记忆：每个项目各自记住当前选中的环境。
⚠️ 环境变量值在保存时自动加密存储（AES-256-GCM）。请勿删除数据目录中的 master.key，删除后已加密变量将无法解密（可用备份 JSON 找回明文）。

设置页可配全局 HTTP 代理（持久化，全部请求生效，含压测）。
登录态 Cookie 自动回放：同域后续请求自动携带，无需手抄。
侧栏「Cookie」页签查看 / 按域清理 Jar 中的登录态；Headers 页可按请求关闭「Cookie 自动回放」。

5.2 环境导入导出

环境管理弹窗底部可导出选中环境（RustFox 原生 JSON / Postman Environment），或从这两种文件导入为新环境（重名自动加后缀）。导出含变量明文，请妥善保管。

6. 自动化测试

工作区 Tests 标签：给接口配置 JSON 测试脚本（请求前变量、响应提取、断言），支持：

pre_request：请求前注入变量
extract：从响应提取变量传递给后续接口（按目录顺序传递）
assertions：状态码 / 响应体包含 / JSONPath 值 / 响应耗时等断言； op 还支持 matches/not_matches（正则）、empty/not_empty， type 还支持 graphql_errors（body.errors 数组断言）与 length（path 处值的长度，走数字比较）

保存后点击「运行测试」，可选择当前接口 / 当前文件夹 / 整个项目；结果自动存入测试历史（保留最近 20 条，可展开查看、删除）。

压测（并发基准）

Tests 页「压测」区：输入并发数与总请求数（默认 10 并发 × 100 次）→「开始压测」。结果：成功/失败数、总耗时、QPS、平均耗时、P50/P90/P99 分位耗时、错误示例（最多 5 条）。运行中可随时取消（已完成样本保留，标记已取消）。

测试用例 Drawer（多用例管理）

Tests 页「测试用例」区（TestCasesPanel + TestCaseDrawer）：

一个接口可维护多个测试用例（不同参数/断言组合），用例含独立 Method 联动与 CodeMirror 请求体编辑。
用例列表支持关键字搜索（名称 / 方法 / 路径 / Body 文本 / 参数与请求头键值，不分大小写，可与分组筛选叠加）。
Drawer 请求 Body 内置查找（搜索按钮或 ⌘F/Ctrl+F）：输入即实时高亮全部匹配并计数，Enter 跳下一个，输入过程不抢光标。
Drawer 支持拖拽分割宽度；用例可逐个运行、查看结果、删除。
「全部运行」一次跑完整个集合（后端并发 5，可取消，进度实时显示）。

7. 客户端代码生成

地址栏「生成代码」→ 选择语言：

cURL / JavaScript (fetch) / Java / Go (net/http) / Rust（另支持 Python / PHP）

生成的是渲染后的完整请求（含变量替换、认证头、启用中的请求头），带语法高亮，直接复制进你的工程即用。

代码/文档导入

目录工具栏「＋新建」下拉与拖拽导入（首页 Dropzone / 项目卡片）支持：

cURL 粘贴导入（自动识别方法 / URL / Header / Body / Basic Auth，URL 拆 base_url + 路径 + query；--retry/--proxy 等不支持的参数会在预览中标出"已忽略"）
地址栏直粘 cURL：在请求地址栏直接粘贴 cURL 命令会自动识别并回填到当前接口（方法 / URL / Headers / Body / 认证），无需打开导入弹窗；普通 URL 粘贴仍走原有的 base_url 拆分。
多语言代码导入（cURL / JavaScript / Java / Go / Rust / Python / PHP 片段反向解析为接口）
文档导入：OpenAPI 3.0 / 3.1 / Swagger 2.0 / Postman Collection v2.1（JSON 或 YAML；3.1 自动转换为 3.0 子集导入，webhooks 顶层键会被丢弃）
从 Apifox / Postman 整站迁移（含环境变量、认证、Mock、断言对照表）：见迁移手册

8. Mock Server（本地接口模拟）

设置页 →「Mock Server」：

设置页
  ┌ Mock Server ─────────────────────────────┐
  │ 启动 Mock   （监听 4010 端口，占用自动 +1） │
  │ 自定义 Mock 规则（可选，优先级高于响应示例） │
  └──────────────────────────────────────────┘

启动后监听 http://127.0.0.1:4010，可按接口（收 4010→4001→…自动 +1 直到找到空闲）。
未配置规则时返回接口的「响应示例」（在 Docs 标签保存的响应）。

响应路由 / 响应体模板变量：{{params.id}}、{{query.name}}、{{headers.X-Token}}、{{mock.uuid|email|name|word|timestamp|int}}。

修改接口或 Mock 规则后点 「热重载」 即时生效，无需重启服务。
规则支持延迟（delay_ms）与故障注入（fault_rate_pct + fault_status，如 20% 请求返回 503），模拟慢接口与不稳定依赖。

9. 备份与恢复 / 文档导出

功能	位置	说明
备份项目	设置页「备份当前项目」	导出全部接口、环境、Mock 规则、响应示例、请求用例 + 全局设置快照（代理/超时/序列）与全局变量/参数，经目录选择框保存到自选目录（默认 `backups/`）
恢复备份	设置页粘贴 JSON →「恢复」	创建为全新项目（ID 全部重新映射，绝不覆盖现有数据；全局维度保守合并：缺失才补，不覆盖现有配置）
导出文档	工作区 Docs 标签（在打开的接口上，支持设计态 Schema 标注）	生成项目 Markdown（多格式）文档，经目录选择框保存（默认 `exports/`）

10. 数据在哪（备份意味着存好数据安全）

所有数据在本机「系统数据目录 / RustFox」：

平台	路径
Linux	`~/.local/share/RustFox/`
macOS	`~/Library/Application Support/RustFox/`
Windows	`%APPDATA%\RustFox\`

rustfox.db：主数据库（项目/接口/环境/Mock 规则/历史）
master.key：环境变量加密密钥（勿删）
backups/、exports/：备份与导出目录
sync/：团队同步的远端本地缓存仓库；sync/backups/ 为拉取覆盖前的自动留档
snapshots/：升级前自动快照（保留 5 份，可复制回滚）
logs/：应用运行日志（设置页「日志」Tab 可查看）
data_dir.txt：自定义数据目录配置（设置页写入；删除即恢复默认）

更改数据目录：设置页「数据」Tab 可查看/更改目录、恢复默认、打开目录。新目录从空数据启动（旧数据请先导出备份再导入）；改完需重启生效。也可用环境变量 RUSTFOX_DATA_DIR（绝对路径）覆盖，优先级高于设置页配置。

一键备份建议：复制整个 RustFox 数据目录到外部存储即可完整迁移。开发/正式隔离：tauri dev 开发构建使用 RustFox-dev 目录，与正式版数据互不干扰。

10.1 外观与偏好（设置页）

主题三档：跟随系统 / 深色 / 浅色（顶栏或设置页切换，持久化到本机，下次启动保持；跟随系统时自动响应 OS 浅色/深色切换）。
请求超时：设置页可配全局请求超时毫秒数，超时的请求按失败计并提示。
自增序列：设置页管理 {{$seq}} 类自增序列（查看当前值、重置），Mock 模板与测试变量可引用。
多项目标签：顶栏项目标签条可在多个项目间快速切换，草稿与打开的标签跨项目保留（切换回来不丢失）。

10.2 AI Agent 集成

把 cURL / 后端 Controller 代码一句话存为接口，无需手粘：详见 AGENT.md。 MCP 客户端配一次 rustfox-mcp（v0.0.10+ 安装包内置），或任意能发 HTTP 的工具直接调 127.0.0.1:4110 控制面（token 在数据目录 agent-token）。

11. 常见问题（FAQ）

问题	处理
双击后没有反应	Windows 便携版需解压完整再运行；macOS 首次需右键「打开」绕过未签名提示；Linux 缺 WebKit 库（见 1.3）
提示“不是来自已识别开发者”	macOS 首次打开：右键 →「打开」；或系统设置 → 隐私与安全性允许
SmartScreen 警告	点「更多信息 → 仍要运行」，开源无签名正常现象
环境变量显示乱码/密文	`master.key` 丢失导致，用备份 JSON 恢复（第 9 节）
Mock 端口被占用	自动 +1 换端口；或先停掉占用方
导入 OpenAPI 失败	支持 OpenAPI 3.0 / 3.1 / Swagger 2.0 / Postman 集合 v2.1（JSON 或 YAML）；3.1 自动归一化，`webhooks` 会被丢弃
数据库损坏？	启动时自动 `integrity_check`，异常会弹窗指引；迁移前已自动快照（数据目录 `snapshots/` 保留 5 份），复制快照回 `rustfox.db` 即可回滚，或用 `backups/` JSON 重建
浅色主题下编辑器看不清	设置页切回「深色」或「跟随系统」；如仍异常，反馈时注明主题模式与系统版本
请求总是超时	设置页调大请求超时；压测/大文件下载场景建议再放宽一档
dev 构建看不到正式版数据	符合预期：dev 用 `RustFox-dev` 目录隔离；用备份 JSON 在两侧互导
反馈问题	顶栏「反馈」自动生成本机诊断报告（路径提示），提交到 GitHub Issues 时附上即可

12. 反馈与支持

顶栏右上方「反馈」按钮 → 一键生成本机环境/日志摘要报告 → 提交到项目仓库 Issue
设置页「日志」Tab 可直接查看运行日志（按天滚动文件）与打开日志目录
数据、部署、进阶指南见 README.zh-CN.md 与 docs/DEPLOY.md；英文文档索引：en/README.md

在 GitHub 上查看本页源文