1. 为什么 BDD 新手总在第一步卡住Gauge 是一个行为驱动开发BDD测试框架它把「用自然语言描述的业务行为」和「真正执行的底层代码」拆成两类文件.spec写场景.js/.py/.java写步骤实现。这样做的好处是产品、测试、开发能看同一份用例描述而执行逻辑单独维护天然适合做数据驱动和回归。它自带 HTML 测试报告VsCode 里也有官方插件做语法高亮、跳转和运行。但真正上手时新手最容易卡住的不是语法而是环境Gauge CLI 装没装对、VsCode 插件认不认得到 CLI、项目模板拉下来跑不起来、以及最要命的——步骤实现里要调用大模型或外部 API 时Key 散落在各个文件里换一个模型就要改一遍配置。这篇就按「安装 Gauge → 在 VsCode 配好统一 Key 通道 → 跑通第一个 spec」的顺序走一遍目标是一次性从零到gauge run出现绿色通过。适合谁看刚接触 BDD、想在 VsCode 里把 Gauge 跑起来的人已经会写测试但被多模型 Key 管理搞烦的人以及想把 AI 能力接进测试步骤、又不想每个项目复制一份密钥的人。下面所有命令和配置都可以直接抄环境以 macOS 为主Windows/Linux 的差异我会单独标出来。2. 装 Gauge 与 VsCode 插件先把地基打平2.1 安装 Gauge CLIGauge 本体是一个命令行工具VsCode 插件只是它的前端。所以顺序一定是先 CLI 后插件。macOS 用 Homebrew 最省事brew install gauge如果你没有 Homebrew或者用的是 Windows / Linux可以走 npm 这条通用路径前提是 Node.js 10.16.3 LTSnpm install -g getgauge/cli装完验证一下版本能打印出来就说明 CLI 就位gauge --version我试过在没装 Node 的机器上直接跑 npm 命令会报command not found这时候先补 Node 再回来。另外 Homebrew 安装偶尔会遇到权限提示按它给的sudo chown命令处理即可不要跳过。2.2 安装 VsCode 插件打开 VsCode在扩展面板搜索Gauge认准发布者是 Gauge 官方那个点安装。装完后建议重启一次 VsCode让插件重新扫描系统里的 Gauge CLI。重启后按Cmd Shift PWindows/Linux 是Ctrl Shift P打开命令面板输入Gauge如果能看到Gauge: Create new Gauge Project这类命令说明插件和 CLI 已经握手成功。如果命令面板里搜不到 Gauge 相关命令八成是插件没激活或 CLI 路径没被识别。可以先在 VsCode 设置里搜gauge确认没有把插件禁用再不行就在终端里which gauge拿到绝对路径填到插件配置里。3. 用 TaoToken 统一 Key 打通模型调用通道3.1 为什么要在 Gauge 项目里放统一 KeyGauge 的步骤实现里经常会调用大模型做文本生成、断言或数据构造。如果每个项目、每个步骤文件都硬编码一个 Key维护起来是灾难换模型要改代码Key 泄露风险也高。更合理的做法是把「调用哪个模型、用哪个 Key」收敛到一处配置代码里只引用一个环境变量或配置项。TaoToken 在这里扮演的就是这个统一入口它提供兼容 OpenAI 风格的 API 通道你拿一个 Key 就能在代码里通过标准接口调用不同模型不用为每个模型单独接一套 SDK。对 Gauge 这种「步骤代码里顺手调一下模型」的场景很合适。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 。3.2 拿到 Key 并写进环境变量先在控制台创建 API Key地址是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建后复制那串 Key不要直接写进代码文件。推荐写进 shell 环境变量macOS/Linux 编辑~/.zshrc或~/.bashrcexport TAOTOKEN_API_KEY你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/apiWindows 可以在系统环境变量里新增同名项或者用 PowerShell 临时设置$env:TAOTOKEN_API_KEY你的Key $env:TAOTOKEN_BASE_URLhttps://taotoken.net/api改完记得source ~/.zshrc或重开终端然后echo $TAOTOKEN_API_KEY确认能打印出来。这一步别偷懒后面 Gauge 步骤代码全靠读这个变量。3.3 VsCode 的 settings.json 骨架为了让 VsCode 里的终端和调试会话都能读到这些变量可以在项目根目录建.vscode/settings.json把 Gauge 插件和终端环境一起配好{ gauge.executable: gauge, gauge.launchArgs: [run], terminal.integrated.env.osx: { TAOTOKEN_API_KEY: ${env:TAOTOKEN_API_KEY}, TAOTOKEN_BASE_URL: https://taotoken.net/api }, terminal.integrated.env.linux: { TAOTOKEN_API_KEY: ${env:TAOTOKEN_API_KEY}, TAOTOKEN_BASE_URL: https://taotoken.net/api }, terminal.integrated.env.windows: { TAOTOKEN_API_KEY: ${env:TAOTOKEN_API_KEY}, TAOTOKEN_BASE_URL: https://taotoken.net/api } }这里gauge.executable告诉插件用哪个 CLIterminal.integrated.env.*保证 VsCode 内置终端启动时带上 Key。注意${env:TAOTOKEN_API_KEY}是引用系统环境变量不是把 Key 明文写进 settings.json这样文件可以安全提交到仓库。4. 创建项目并写 config.toml 与首个 spec4.1 用命令面板创建 Gauge 项目按Cmd Shift P执行Gauge: Create new Gauge Project选一个模板新手建议选 JavaScript 或 Python 的默认模板然后选保存路径、输入项目名。等初始化结束目录结构大致是这样my-gauge-project/ ├── env/ │ └── default/ │ └── default.properties ├── specs/ │ └── example.spec ├── tests/ │ └── step_implementation.js ├── manifest.json └── config.tomlspecs/放行为描述tests/放步骤实现config.toml是项目级配置。如果初始化后没有config.toml手动建一个也行。4.2 config.toml 骨架config.toml用来声明项目里用到的插件、环境等。一个够用的骨架# Gauge 项目配置 location specs [env.default] TAOTOKEN_BASE_URL https://taotoken.net/api [[plugins]] name js path testslocation指定 spec 搜索目录[[plugins]]声明语言插件和步骤实现目录。如果你用的是 Python 模板把js换成python路径对应改掉。[env.default]里可以放非敏感的默认配置Key 本身仍然走环境变量不写进这个文件。4.3 写第一个 spec打开specs/example.spec改成下面这样描述一个最简单的场景# 首个 Gauge 用例 ## 验证统一 Key 通道可用 * 调用模型接口并返回文本 * 返回内容不为空Gauge 的 spec 用#做标题、##做场景、*做步骤。步骤文字要和步骤实现里的函数名对应Gauge 靠这个映射把自然语言和代码连起来。4.4 写步骤实现接入 TaoToken打开tests/step_implementation.js写入const { Step } require(gauge); const https require(https); Step(调用模型接口并返回文本, async function () { const apiKey process.env.TAOTOKEN_API_KEY; const baseUrl process.env.TAOTOKEN_BASE_URL || https://taotoken.net/api; if (!apiKey) { throw new Error(TAOTOKEN_API_KEY 未设置请检查环境变量); } const payload JSON.stringify({ model: gpt-4o-mini, messages: [{ role: user, content: 用一句话说明 BDD 是什么 }] }); const result await new Promise((resolve, reject) { const req https.request( ${baseUrl}/v1/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${apiKey} } }, (res) { let data ; res.on(data, (chunk) (data chunk)); res.on(end, () resolve(JSON.parse(data))); } ); req.on(error, reject); req.write(payload); req.end(); }); this.context.responseText result.choices[0].message.content; }); Step(返回内容不为空, function () { const text this.context.responseText; if (!text || text.trim().length 0) { throw new Error(模型返回内容为空); } });这里用 Node 原生https发请求避免额外装依赖。baseUrl从环境变量读默认指向https://taotoken.net/api路径拼/v1/chat/completions就是标准的 OpenAI 兼容接口。模型名按你实际可用的填代码里只是示例。5. 跑通 gauge run 并验证结果5.1 命令行执行在项目根目录打开终端确认环境变量在echo $TAOTOKEN_API_KEY有输出后执行gauge run specs正常的话会看到类似输出# 首个 Gauge 用例 ## 验证统一 Key 通道可用 ✔ Successfully generated html-report to reports/html-report/index.html Specifications: 1 executed, 1 passed1 passed就是我们要的结果。Gauge 还会在reports/下生成 HTML 报告浏览器打开能看到每个步骤的耗时和状态。5.2 在 VsCode 里执行装好插件后spec 文件里每个场景上方会出现运行按钮点一下就能跑输出在Gauge输出面板里。如果按钮没出现检查文件是否在specs/目录下、插件是否激活。用命令面板执行Gauge: Run Specifications也可以。5.3 验证模型通道确实通了想确认返回的是真实模型输出可以在步骤里把responseText打印出来console.log(模型返回:, this.context.responseText);再跑一次终端里能看到模型生成的那句话说明从 Gauge 到 TaoToken 通道整条链路是通的。如果只想单独验证模型对话可以直接用模型对话入口 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 发一条消息对比结果。6. 本篇常见报错与排查报错一gauge: command not foundCLI 没装或没进 PATH。先which gauge没有就重装有路径但 VsCode 终端找不到检查settings.json里gauge.executable是否写成了绝对路径。报错二TAOTOKEN_API_KEY 未设置环境变量没生效。确认~/.zshrc改完执行了sourceVsCode 要完全退出重开只关窗口不算。Windows 用户注意设置的是用户级还是系统级变量。报错三401 UnauthorizedKey 错了或没带上。检查Authorization头是不是Bearer加 Key中间有空格确认 Key 没有多余换行。可以到 API Keys 页面 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 重新生成一个对比。报错四ECONNREFUSED或超时baseUrl拼错了。确认是https://taotoken.net/api请求路径是/v1/chat/completions不要重复拼/api。公司网络限制出口的话换网络环境再试。报错五步骤显示 undefinedspec 里的步骤文字和Step()注册的字符串不完全一致包括标点和空格。Gauge 是精确匹配复制粘贴时注意别多空格。报错六插件运行按钮不出现项目没被识别为 Gauge 项目。确认根目录有manifest.json且 VsCode 打开的是项目根目录而不是子目录。排查完这些基本能覆盖从安装到首个用例执行的全部坑。如果你后面要长期写编码类或 Agent 类步骤可以考虑 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 把模型调用额度集中管理接入细节可以对照接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里的参数说明逐项核对。