groq-local-dev-loop

用途

该技能用于为 Groq 搭建快速、可复现的本地开发工作流。由于 Groq 的响应时间在亚秒级，适合紧凑的开发循环——LLM 响应足够快，可以在不切换上下文的情况下迭代。该技能会脚手架化一个项目，包含带记忆化的客户端、模型常量以及两级测试策略（模拟单元测试 + 可选加入的实时集成测试）。精简骨架在此处给出，完整代码位于 references/implementation.md 和 references/examples.md。

前置条件

已安装 groq-sdk（npm install groq-sdk）
已设置 GROQ_API_KEY（开发阶段使用免费套餐即可）
Node.js 18+，并安装 tsx 用于执行 TypeScript
使用 vitest 进行测试

认证

groq-sdk 客户端会自动从环境变量读取 GROQ_API_KEY——new Groq() 和 getGroqClient() 都能获取到它。在 console.groq.com/keys 获取密钥，存放在被 git 忽略的 .env.local 中，仅提交 .env.example 作为模板。切勿硬编码密钥或提交 .env.local。

使用方式

按顺序执行以下七个步骤。步骤 1-2 搭建项目；步骤 3-4 集中管理客户端与模型 ID；步骤 5-6 建立测试层级；步骤 7 生成环境模板。每一步的完整代码在参考文件中。

项目结构 — 创建 src/groq/{client,models,completions}.ts、tests/ 以及 .env.local / .env.example。
包配置 — 接通 dev（tsx watch）、test / test:watch（vitest）以及 test:integration 脚本。
单例客户端 — 一个惰性记忆化的 getGroqClient()，在缺少 GROQ_API_KEY 时快速失败；以及用于测试的 resetClient()。
模型常量 — 一个 MODELS 映射，其中 DEV_MODEL 默认使用 llama-3.1-8b-instant 以节省开发配额。
带模拟的单元测试 — 使用 vi.mock("groq-sdk")，使单元测试在亚秒级内运行且零 API 调用。
集成测试 — 将实时 API 测试置于 GROQ_INTEGRATION=1 之后，配合 describe.skipIf，使默认运行保持离线。
环境模板 — 提交 .env.example，将 .env.local 加入 git 忽略。

客户端示例代码（src/groq/client.ts，惰性记忆化单例）：

import Groq from "groq-sdk";

let _client: Groq | null = null;

export function getGroqClient(): Groq {
  if (!_client) {
    if (!process.env.GROQ_API_KEY) {
      throw new Error("GROQ_API_KEY not set. Copy .env.example to .env.local");
    }
    _client = new Groq({ apiKey: process.env.GROQ_API_KEY, maxRetries: 2, timeout: 30_000 });
  }
  return _client;
}
export function resetClient(): void { _client = null; }

完整项目脚手架、package.json、模型常量与 .env.example 见 references/implementation.md；完整的单元与集成测试文件见 references/examples.md。

输出结果

应用该工作流后会产生：

一个脚手架化项目，包含 src/groq/{client,models,completions}.ts 与 tests/ 目录。
一个记忆化的 getGroqClient()，共享同一个已配置客户端，并在未设置 GROQ_API_KEY 时抛出可操作的错误。
一个 MODELS 映射 + DEV_MODEL 常量，使开发运行在便宜的 8B 模型上。
两级测试套件：模拟单元测试（npm run test:watch，无 API 调用）与可选加入的实时测试（npm run test:integration，由 GROQ_INTEGRATION=1 控制）。
为团队提交的 .env.example 模板，真实密钥存放在被 git 忽略的 .env.local 中。

错误处理

错误	原因	解决方案
GROQ_API_KEY not set	缺少 .env.local	从 .env.example 复制
测试超时	单元测试中发起实时 API 调用	在单元测试中模拟 groq-sdk
429 rate_limit_exceeded	触及免费套餐 RPM	等待 60 秒，或使用 test:watch 并延长间隔
端口已被占用	另一个 tsx watch 正在运行	结束进程或更改端口

开发提示

开发期间使用 llama-3.1-8b-instant（配额消耗最低、速度最快）。
调试时设置 temperature: 0 以获得确定性输出。
保守设置 max_tokens，避免耗尽免费套餐。
Groq 免费套餐：70B 与 8B 模型为 30 RPM——据此规划开发循环。

示例命令

npm run dev                # tsx watch src/index.ts (hot reload)
npm run test:watch         # vitest --watch (mocked, no API calls)
npm run test:integration   # GROQ_INTEGRATION=1 vitest (live API)

完整的模拟单元测试（vi.mock("groq-sdk")）与由 GROQ_INTEGRATION 控制的实时集成测试，见 references/examples.md。

资源

references/implementation.md — 完整项目脚手架、客户端、模型常量与环境模板。
references/examples.md — 完整的单元与集成测试文件。
groq-sdk npm
Vitest Documentation
tsx Documentation

生产级代码模式请参考 groq-sdk-patterns 技能。