API 接口调试、管理与用例编排 的本地优先（local-first）桌面软件。
一句话：用文件组织的、可编排的 API 用例集。打开一个目录即一个工作空间，folder 即分组，.yml 即用例；单个 API 调试与多步编排在同一套模型下统一。
状态：v0.1 · MVP。已可打开工作空间、可视化编辑与执行单 / 多节点用例。
- 文件即数据（local-first） —— case 不进数据库，就是磁盘上的
.yml。Git 友好、可 diff、可 review、可离线，数据完全由用户掌控。 - 单 / 多请求统一为 DAG —— 不做两套模型：单请求 = 退化的单节点 DAG，多步编排 = 多节点 DAG（节点间以
dependsOn声明依赖）。概念更少、代码路径统一、单 → 多平滑演进。 - 变量与数据流 —— 变量就近覆盖：environment（全局） < case 级
vars< 上游节点outputs；透传语法${{baseUrl}}、${{steps.login.outputs.token}}；输出按 JSONPath 从响应体提取供下游引用。 - YAML 作为载体 —— case / 配置都用 YAML，可读、可注释、Git 友好；schema 参考 Postman / HAR / Insomnia / Bruno（request）与 Arazzo / GitHub Actions（flow）。
- 单 API 调试 —— Postman 风格请求行（方法 + URL + 发送），参数 / 请求头 / 认证 / 请求体四 Tab；响应区展示状态码 / 耗时 / 大小 / 响应头 / 响应体（Pretty / Raw）。请求由 Rust 后端（
reqwest）发出，天然绕过浏览器 CORS。 - 工作空间与文件树 —— 打开 / 创建目录为工作空间（幂等写
application.yml）；懒加载文件树，支持搜索、右键新建 / 重命名 / 删除，可视化对话框新建 case。 - flow 编排（DAG 画布） ——
dependsOn自动分层布局 + SVG 连线；两级视图切换（文本 | 可视，可视再分 流程 / 请求）；内容驱动默认视图。 - 执行引擎 —— 拓扑序串行运行，步骤间变量透传 + 输出提取（JSONPath 常用子集）+ 断言（
eq/ne/contains/exists/notExists/gt/lt/matches，逐条 ✓/✗，失败标红节点）。 - 多环境 ——
application.yml的environment段多套环境切换，运行时注入变量；仿 GitHub 风格的可视化设置页。 - 多标签页 —— 同时打开多个 case，标签切换 / dirty 标记 / 中键关闭 / 右键批量关闭，非活动标签完整保留编辑态。
- 原生桌面体验 —— macOS 自定义标题栏；任意文本 / 二进制文件可打开（二进制由 Rust 端嗅探并友好提示）。
- 命令行 ——
apicase run无界面跑用例并落 HTML 报告（与界面同一个执行内核，结果不会两样）； 退出码区分「断言失败」与「请求发不出去」，接 CI 直接可用。 - MCP 服务器 ——
apicase mcp让 AI Agent 直接查格式、写用例、自检、运行、读失败现场。
| 层 | 选型 |
|---|---|
| 桌面框架 | Tauri 2（Cargo workspace：core/ + src-tauri/ + cli/） |
| 执行内核 | apicase-core（零 GUI 依赖）：reqwest + rustls、cookie_store、tokio、serde_yaml |
| 命令行 / MCP | apicase-cli（零 GUI 依赖）：clap、rmcp（MCP 官方 Rust SDK） |
| 前端 | React 19 + TypeScript + Vite 7（只做配置与展示，无 YAML / HTTP 依赖） |
| 存储格式 | YAML（case / 配置；格式参考 Postman / HAR / Arazzo 等） |
环境要求：Node.js（含 npm）、Rust 工具链（cargo / rustc）；Tauri 系统依赖（macOS 自带 WebKit，Windows 需 WebView2，Linux 需 WebKitGTK）。
cd app
npm install # 首次安装前端依赖
# 图形界面
npm run tauri dev # 启动桌面应用（热重载）
npm run tauri build # 打包各平台安装包
# 命令行（只编 cli 与 core，不碰 Tauri，增量编译约 2 秒）
cargo cli run -e dev # == cargo run -q -p apicase-cli -- run -e dev
cargo build -p apicase-cli --release # 出正式二进制自测：
npm run build # 前端类型检查 + 打包
npm test # 前端单测 + IPC 接线核对
cargo test --workspace # 执行内核 + 命令层 + CLI（默认全部离线）启动后：左上角「选择工作空间」打开一个目录 → 在文件树新建 / 打开 .yml → 编辑请求并「发送」，多节点用例点「▶ 运行」按拓扑序执行。
命令行与界面是两个各自独立的可执行文件，共享同一个执行内核，也共用工作空间配置、 cookie 会话与报告目录：
| 产物 | 包名 | 构建 |
|---|---|---|
apicase |
apicase-cli |
cargo build -p apicase-cli --release |
Apicase.app / .dmg（内含一份 CLI） |
apicase-desktop |
npm run tauri build |
装了桌面版就白得一个 CLI（在 Apicase.app/Contents/Resources/bin/apicase），
且版本与界面天然一致——同一个安装包、同一次编译、同一个执行内核。
CI 与容器里则单独用上面那个二进制，不必为一个命令行工具下几十 MB 的桌面包。
三个包名对齐为 apicase-core / apicase-cli / apicase-desktop；产物名与包名不必相同——
CLI 的产物叫 apicase，因为用户敲的是 apicase run。
桌面端要用
npm run tauri build，不能用cargo build -p apicase-desktop --release代替： 后者只编 Rust，既不会先构建前端（于是嵌进去的是dist/里的旧版本，且不给任何提示）， 也不产出.app/.dmg。cargo build -p apicase-desktop只适合「验证 Rust 侧能不能编过」。
拆成两个而不是一个按参数分流，是因为带 GUI 的二进制在没装桌面环境的机器上
连动态链接都过不去——那时 apicase run 一行代码都执行不到。
两者互不引用，可以单独分发、单独安装、单独升级。
cargo build -p apicase-cli --release # 产出 target/release/apicase
apicase init # 准备好这个目录：配置 + 命令行工具进 PATH + AGENTS.md
apicase self install # 只把 apicase 装进 PATH（软链，不覆盖别人的同名命令）
apicase new 登录 -X POST --url https://api.example.com/login
apicase check # 只解析不发请求，查出依赖断裂 / 断言目标写错等
apicase run # 跑整个工作空间，落一份 HTML 报告
apicase run api/login.yml -e prod # 跑一个用例，用 prod 环境
apicase run flow.yml --step createOrder # 只跑这个请求（上游依赖自动带上）
apicase run --json | jq .summary # 管道里自动给 JSON
apicase docs assertions # 查用例 YAML 的格式规范工作空间向上查找 application.yml（同 git 找 .git），在任何子目录里敲都能工作。
退出码：0 全部通过 · 1 断言失败（被测服务的问题）· 2 用法 / 配置错误 · 3 请求发不出去（环境或用例自身的问题）。
1 与 3 分开，是因为这两者的排查方向完全不同。
首选 AGENTS.md（apicase init 会生成）：Linux Foundation 的开放标准，
Codex / Cursor / Copilot / Gemini CLI / Windsurf / Zed / Aider 等三十多个 Agent 原生读，
Claude Code 也读。零配置——文件在目录里就生效，还随 git 走到每个同事的机器上。
内容只有二十来行，指路而不复制：告诉 AI 敲 apicase docs 查格式、
apicase check 自检、apicase run --json 验证，不把 YAML 规范抄一份进去。
MCP 是另一条路，适合只放行工具、不给 shell 的受管控环境，但要在每个客户端里配一次：
{ "mcpServers": { "apicase": { "command": "apicase", "args": ["mcp", "-w", "/path/to/workspace"] } } }七个工具：apicase_run / check / list / show / env / report / docs。
用例是 YAML 文本，AI 用自带的文件工具直接编辑即可，故不提供写入工具。
典型闭环：docs 查格式 → 写 .yml → check 自检 → run 验证 → 读失败现场再改。
以下为要点与示例，完整字段规范见 docs/0.latest/3.YAML格式规范.md。
工作空间根目录的配置文件，定义多套环境（每套一组变量），topbar 右侧下拉切换活动环境，运行时注入：
environment:
dev: { baseUrl: https://dev.example.com, token: "" }
test: { baseUrl: https://test.example.com, token: "" }
prod: { baseUrl: https://api.example.com, token: "" }一个 .yml 即一个 case，模型上是 DAG；写盘时恒定使用 steps: 列表（单节点也是长度为 1 的列表）。
顶层字段：apicase（版本，必填）· name（可选）· vars（case 级变量，可选）· steps（请求节点列表，必填）。
step 字段（顺序 id → protocol → ui → dependsOn → request → outputs → assertions → docs）：
id 唯一标识 · protocol 协议（当前仅 http）· dependsOn 上游依赖 · request 报文
（method/url/query/headers/auth/body）· outputs 输出提取 · assertions 断言。
单节点用例（等价于「发一个 API」）：
apicase: v0.1
name: 获取用户
vars:
baseUrl: https://api.example.com
steps:
- id: getUser
protocol: http
request:
method: GET
url: ${{baseUrl}}/users/1
assertions:
- { target: res.status, op: eq, value: 200 }
- { target: res.body.data.id, op: exists }多节点用例（登录 → 下单，dependsOn 声明依赖、outputs 提取变量供下游透传）：
apicase: v0.1
name: 登录并下单
vars:
baseUrl: https://api.example.com
steps:
- id: login
protocol: http
request:
method: POST
url: ${{baseUrl}}/login
body:
type: json
json: { username: admin, password: "123456" }
outputs:
token: res.body.data.token
assertions:
- { target: res.status, op: eq, value: 200 }
- id: createOrder
protocol: http
dependsOn: [login]
request:
method: POST
url: ${{baseUrl}}/orders
headers:
- name: Authorization
value: Bearer ${{steps.login.outputs.token}}
body:
type: json
json: { sku: A-1001, qty: 2 }
assertions:
- { target: res.body.code, op: eq, value: 0 }- auth 类型：
none/bearer/basic/apikey/digest/oauth2。 - body 类型：
none/json/xml/text/form-urlencoded/form-data/binary。 - 断言与提取目标统一挂在
res下：res.status/res.headers.<名>/res.body<路径>。 旧写法（status、header.X、$.data.token）不再识别。 - 变量：
${{name}}；跨节点引用上游输出用${{steps.<step id>.outputs.<输出名>}}；未解析保留字面量。
上面这份是摘要，唯一权威是 3.YAML格式规范—— 或者直接敲
apicase docs，那是同一份内容。
apicase/
├── app/ # 应用代码（Cargo workspace + 前端）
│ ├── core/ # apicase-core：执行内核（桌面壳与 CLI 共用）
│ ├── src-tauri/ # 桌面壳：Tauri 命令层
│ ├── cli/ # apicase-cli：命令行与 MCP 服务器
│ └── src/ # 前端：只做配置与展示
├── docs/
│ ├── 0.latest/ # 当前全局最新文档 —— 唯一事实来源
│ └── 1.feature/ # 各需求的产品技术方案（YYYYMMDD-需求名）
└── CLAUDE.md # 全局提示词
docs/0.latest/ 是项目的唯一事实来源，涉及现状的判断以此为准：
- 0.概览 —— 定位、当前能力、技术栈、路线。
- 1.产品概念模型 —— 文件即数据、folder / case、关键设计决策。
- 2.技术架构 —— 目录结构、后端命令与数据模型、运行与构建。
- 3.YAML格式规范 —— case / application.yml 的完整字段格式与序列化约定。
- 未定义变量高亮（
${{var}}找不到时提示）；深色主题。 - JSONPath 通配符 / 过滤器、flow 并发执行、断言更多目标（响应耗时 / 大小）。
- 画布节点拖拽持久化、标签拖拽排序、最近列表持久化、文件树外部变更自动刷新、历史、导入导出（Postman / Arazzo）、OpenAPI(SPEC)。