HTTP Studio

一个“配置随代码走”的 VS Code HTTP 客户端。环境、目录和请求都保存在项目里的 .http/conf.json，和代码一起提交、一起 Code Review。

• 永久免费，无需登录，离线可用，支持 Remote / WSL / SSH
• 图形化请求编辑器，支持 Params、Headers、Body、Auth、Tests
• 多环境：每个环境配置协议、域名或 IP、端口、上下文路径，在请求面板工具栏或状态栏一键切换
• 目录层级不限，支持拖拽排序；目录和集合可设置公共请求头与认证，下级自动继承
• 不写脚本也能做请求链和断言：从响应提取 token 等变量供后续请求使用；“预执行”可以让请求在发送前先跑登录等已有请求，成功后再发送
• 一键生成 .http/README.md 配置说明，交给 AI 编程助手根据代码里的 Controller 自动生成接口配置
• 一键导入 Postman、Thunder Client、OpenAPI / Swagger、.http 文件和 cURL
• 可以运行整个目录，也可以用 CLI 在 CI 中复用同一份配置

快速开始

1. 打开项目，点击活动栏中的 HTTP Studio 图标
2. 点击“初始化”，插件会生成 .http/conf.json（带示例）和 .http/.gitignore
3. 在请求面板顶部的环境下拉菜单中选择“管理环境…”编辑环境；在下方的请求树中新建目录和请求（右键菜单或工具栏按钮）
4. 在请求编辑器里按 Cmd/Ctrl+Enter 发送，按 Cmd/Ctrl+S 保存

想让 AI 根据代码生成接口配置时，在侧栏“更多”菜单（未初始化时为欢迎页按钮）点击“初始化 AI 配置说明”，插件会在 .http/README.md 写入配置文件的结构与编写规则，再让 AI 读这份说明并扫描 Controller 即可。

如果项目里已经有 .http/conf.json，打开工作区时插件会自动加载。执行 git pull、切换分支或手动修改文件后，界面会实时刷新。

文件说明

conf.json 采用确定性格式：字段顺序固定，省略默认值，JSON 请求体以原生 JSON 存储，节点使用稳定 id。加载后再保存不会产生任何 diff，在 PR 里可以直接看出接口改了什么。手工编辑时有 JSON Schema 补全和校验。

{
  "version": 1,
  "environments": [
    { "id": "k3j9x0a1", "name": "测试", "protocol": "https", "host": "test.example.com", "port": 8443, "basePath": "/api",
      "variables": [{ "key": "token", "value": "", "secret": true }] },
    { "id": "p8d2m4q7", "name": "生产", "protocol": "https", "host": "api.example.com", "basePath": "/api",
      "color": "red", "confirmSend": true }
  ],
  "items": [
    { "id": "f1a2b3c4", "type": "folder", "name": "用户", "items": [
      { "id": "r5d6e7f8", "type": "request", "name": "用户详情", "method": "GET", "url": "/users/{{userId}}",
        "auth": { "type": "bearer", "token": "{{token}}" },
        "assertions": [{ "source": "status", "operator": "eq", "expected": "200" }] }
    ] }
  ]
}

变量

• 语法为 {{name}}。相对路径会自动拼接当前环境的 {{baseUrl}}，即 protocol://host:port/basePath
• 优先级从高到低：本地环境值 > 共享环境变量 > 本地全局值 > 共享全局变量 > 内置变量（baseUrl、host、port、basePath、protocol）
• 动态变量：{{$uuid}}、{{$timestamp}}、{{$isoTimestamp}}、{{$datetime "YYYY-MM-DD"}}、{{$randomInt 1 100}}、{{$processEnv NAME}}（仅在受信任的工作区可用）
• 标记为 secret 的变量，真实值只保存在 conf.local.json
• 存在未解析的变量时会拦截发送，不会把 {{x}} 原样发出去

生产环境保护

在环境上设置 confirmSend: true 后，状态栏会显示警示色，发送 POST、PUT、PATCH、DELETE 等写操作前会弹出二次确认。

CLI

node dist/cli.js run --env 测试 --folder 用户 --reporter text

全部通过时退出码为 0，有失败为 1，配置或参数错误为 2。

开发

npm install
npm run build          # 构建扩展、CLI 和 Webview
npm run typecheck      # 宿主 + Webview 类型检查
npm test               # vitest 单元测试（core、三方合并等）
npm run test:e2e       # 真实 VS Code 集成测试（首次运行会下载 VS Code 到 .vscode-test/）
npm run check:l10n     # 检查中文翻译是否齐全（加 -- --prune 删除无引用条目）
npm run vsix           # 生产构建并打包到 release/<名称>-<版本>.vsix（发布流程见 CLAUDE.md）
npm run check:webview  # 无头 Chrome 驱动 Webview 预览夹具做交互检查
npm run icon           # 把 media/logo.svg 渲染为 media/icon.png（仅 macOS，需要 Chrome）
npm run vsix           # 打包为 .vsix

集成测试可以用环境变量 E2E_SUITES 和 E2E_GREP 只跑一部分。

图标

在 VS Code 中按 F5，会用 sample-workspace/ 启动扩展调试。设计细节见 docs/DESIGN.md。

Webview 可以脱离 VS Code 在浏览器中预览：先运行 node webview/dev/build.mjs，再打开 webview/dev/index.html?view=request&theme=dark&locale=zh-cn。view 可选 request、environments、folder、runner，theme 可选 light、dark、hc。

开发进度（2026-10-30 更新）

当前状态

所有计划内的功能都已完成，并通过了以下检查：

集成测试覆盖了：扩展激活、命令注册、配置加载与保存（加载后再保存零 diff）、热加载、非法 JSON 和 Git 冲突标记下的只读保护、打开请求后 Webview 真正运行、对本地服务的真实请求与变量捕获、初始化、编辑器同步消息、侧栏的状态推送 / 切换环境 / 管理环境 / 拖拽移动 / 定位，以及 Webview 运行期无脚本错误。

已完成

待办

• [ ] 确认 sample-workspace/.http/conf.json 中 Admin 目录的顺序改动是否有意为之；不是的话把 reqpatch 移回 requpdat 之后，集成测试即可全部通过
• [ ] 按 F5 手动验证：重载窗口后恢复已打开的面板（测试模式下无法覆盖真实重载）；侧栏的真实鼠标拖拽
• [x] 发布第一个版本 26.10.1（2026-10-30）：已打包到 release/http-workspace-client-26.10.1.vsix（.gitignore 忽略 *.vsix，安装包不进 Git）并完成首次提交
• [x] 项目更名为 HTTP Studio（2026-10-30）：包名 http-studio（扩展 ID lupee.http-studio），命令、视图、设置项前缀由 httpWorkspace. 改为 httpStudio.，CLI 命令名 http-studio
• [x] 发布 26.10.2（2026-10-30）：更名后的首个版本，已打包到 release/http-studio-26.10.2.vsix，旧名安装包已清理
• [x] 发布 26.10.3（2026-10-30）：产品图标去掉火焰两侧的绿色、蓝色尾迹，已打包到 release/http-studio-26.10.3.vsix
• [x] 配置远程仓库并推送（2026-10-30）：origin 为 https://gitee.com/Lupeed/http-studio-plugin.git
• [ ] （可选）在 package.json 补上 repository 字段，打包时就不再需要 --allow-missing-repository
• [ ] （可选）补一个 LICENSE 文件（package.json 声明了 MIT），打包时就不再需要 --skip-license
• [ ] （可选）缩小 Webview 包：生产构建 JS 为 955KB（gzip 后 310KB），去掉 @codemirror/lang-html 可再减少约 100KB
• [ ] （可选）响应支持 HTML 预览：需要在 CSP 中放开 frame-src，并为 iframe 加 sandbox

已知限制

• VS Code 只在标签页首次可见时才恢复面板。在此之前从树中打开同一个请求会新建面板，之后再点开旧标签，旧标签会被关闭
• 环境编辑器收到 environments/local 时，被清空的“仅本地”变量会保留为空行，以免行错位
• 变量单元格的编辑器是懒挂载的，挂载后需要轻移鼠标才会出现变量悬停提示
• 侧栏宽度不到 260px 时，“新建目录”“全部折叠”按钮会收进“更多”菜单
• 侧栏拖拽用合成的 DragEvent 测试，真实鼠标拖拽和悬停自动展开需要手动验证

开发约定（继续开发前请先看）

• 发给宿主的对象上不能挂 UI 临时字段。serializeConfig 会原样保留未知字段，写进 conf.json。表格行的 React key 应在组件内部单独维护
• 预执行请求按 id 引用：preRequests[].requestId 指向同一 conf.json 中的请求；expectStatus 为 200 时不落盘，宿主 writePreRequests 与 Webview cleanPreRequests 必须保持同一规则。修改 conf.json 结构时同步更新 src/core/configGuide.ts 的说明（单测会校验字段覆盖与示例可加载）
• request.url 不包含 query。query 统一放在 params 中。Webview 载入旧数据时会把 URL 里的 query 自动迁移到 params
• 存在未解析变量时拦截发送，错误码为 UNRESOLVED_VARIABLES。没有本地值的 secret 变量也视为未解析
• secret 变量的真实值只能存在 conf.local.json 中，conf.json 里一律写空串。导入和保存集合设置时，由宿主负责转存
• 保存本地值时做三方合并：environments/save 带上 Webview 的基线 baseLocal，用户没改过的值以磁盘为准
• core 层（src/core）不能依赖 vscode，因为 CLI 和单元测试都要复用它
• 新增协议消息时，宿主和 Webview 两侧都要实现，并在 test/e2e 与 webview/dev/check.mjs 中加上对应用例
• 宿主中的运行时字符串用 vscode.l10n.t('English')，中文翻译放在 l10n/bundle.l10n.zh-cn.json，改完运行 npm run check:l10n；Webview 的翻译词典在 webview/src/i18n.ts