vibesdk V1 Dev API Postman 集合实战指南OAuth、CSRF 与 AI 生成接口的端到端调试【免费下载链接】vibesdkAn open-source vibe coding platform that helps you build your own vibe-coding platform, built entirely on Cloudflare stack项目地址: https://gitcode.com/GitHub_Trending/vi/vibesdk本指南基于 vibesdk 仓库中的 docs/POSTMAN_COLLECTION_README.md 及其配套的 Postman Collection 文件 与 Postman 环境文件系统讲解这套覆盖 100 个端点的遗留 V1 Dev/phasic API 接口集合的导入、认证、调试与自动化测试方法。读完本文你将掌握如何在 Postman 中完成邮箱登录与浏览器内 OAuth 认证、如何利用集合内置的 CSRF 双提交令牌自动化机制安全地发起写操作、如何调用 AI 应用生成、应用管理、模型配置与密钥管理等核心工作流并学会对照 worker/api/routes/ 下的真实路由实现核验接口契约。前置说明该集合记录的是遗留的 V1 Dev/phasic API 表面尚未迁移到当前的 Think 行为。用于当前集成之前请务必对照 worker/api/routes/ 中的路由文件核验端点与请求体。集合保留用于对受支持的遗留端点、OAuth 配置和 CSRF 行为做兼容性测试。集合总览100 端点的逻辑分组该 Postman 集合将全部端点按业务域组织为 9 个逻辑分组便于按功能模块逐组调试分组功能端点数量按文档标注 认证OAuth、邮箱认证、会话管理16 Agent 与代码生成AI 驱动的 Web 应用创建5 应用管理CRUD、公共 Feed、收藏10 用户管理个人资料、带分页的应用列表2 分析与统计用户统计、AI Gateway 分析4 模型配置AI 模型设置、BYOK 供应商8 自定义模型供应商OpenAI 兼容 API 管理6 密钥管理API 密钥、带模板的凭据5 GitHub 集成仓库导出、OAuth2这些分组与仓库中的实际路由文件一一对应认证对应 authRoutes.ts应用管理对应 appRoutes.tsAgent 与代码生成对应 codegenRoutes.ts模型配置对应 modelConfigRoutes.ts自定义供应商对应 modelProviderRoutes.ts统计与分析分别对应 statsRoutes.ts 和 analyticsRoutes.tsGitHub 集成对应 githubExporterRoutes.ts。所有路由统一在 worker/api/routes/index.ts 的setupRoutes()中挂载其中还包含无需认证的GET /api/health健康检查。快速上手导入集合与配置环境1. 导入集合与环境打开 Postman → 点击Import→ 上传v1dev-api-collection.postman_collection.json对应仓库文件 docs/v1dev-api-collection.postman_collection.json继续Import→ 上传v1dev-environment.postman_environment.json对应仓库文件 docs/v1dev-environment.postman_environment.json在 Postman 右上角环境下拉框中选择V1 Dev Environment。2. 配置 baseUrl集合中所有请求都通过{{baseUrl}}变量拼接完整 URL因此只需维护一个环境变量即可切换目标环境生产环境https://your-production-domain.com本地开发http://localhost:8787Wrangler dev server由bun run dev启动环境文件里还预留了一个默认关闭的localUrl变量http://localhost:8787需要切换本地环境时直接启用它并把baseUrl指向它即可。3. 环境变量一览环境文件中定义了以下变量其中绝大多数由集合的脚本自动填充只有provider_id与secret_id需要手动设置变量说明自动填充baseUrlAPI 基础地址生产或本地❌ 手动配置localUrl本地开发地址默认禁用❌ 手动配置csrf_tokenCSRF 防护令牌✅ 预请求脚本自动获取user_id当前用户 ID✅ 注册/登录后自动写入session_id当前会话 ID✅ 注册/登录后自动写入agent_id当前 Agent/应用 ID✅ 创建应用后自动写入app_id当前应用 ID✅ 获取应用详情后自动写入provider_id模型供应商 ID手动测试供应商端点时secret_id密钥 ID手动测试密钥端点时OAuth 测试策略为什么 OAuth 端点不能在 Postman 里直接点⚠️重要OAuth 端点会 302 重定向到外部提供商Google/GitHubPostman 不会跟进浏览器级重定向直接点击会看到一段 HTML 而非 JSON 响应。这是正常行为——OAuth 必须走浏览器流程。推荐方案OAuth Helper 请求集合内置了两个 Helper 请求用于规避这一限制运行 OAuth Helper - Get Google URL或 GitHub 版本打开 Postman 底部的Console 标签页脚本会把形如{{baseUrl}}/api/auth/oauth/google的完整 OAuth URL 打印到控制台复制该 URL 到浏览器中打开完成 Google/GitHub 的授权流程认证成功后浏览器会重定向回你的应用域名该域名的会话 Cookie 已就绪回到 Postman对同一域名即baseUrl的请求会自动携带 Cookie直接运行Get User Profile即可验证认证是否生效。该 Helper 的脚本逻辑提取自集合 JSON会在测试阶段把 OAuth URL 打印到控制台const baseUrl pm.environment.get(baseUrl); const googleOAuthUrl ${baseUrl}/api/auth/oauth/google; console.log( COPY THIS URL TO YOUR BROWSER:); console.log(googleOAuthUrl); pm.test(OAuth URL generated, () { pm.expect(googleOAuthUrl).to.include(/api/auth/oauth/google); });备选方案手动拼接 URL如果 Helper 不可用直接在浏览器中打开以下地址即可Google OAuth{{baseUrl}}/api/auth/oauth/googleGitHub OAuth{{baseUrl}}/api/auth/oauth/github从源码看这两个端点由 authRoutes.ts 中的GET /oauth/:provider统一路由到AuthController.initiateOAuth属于public级别无需登录即可发起并在发起后重定向到外部提供商。集合中的 OAuth 请求还预留了一个可选的redirect_url查询参数默认{{baseUrl}}/dashboard用于指定认证完成后的回跳地址。本地开发时的注意事项本地跑 OAuth 时由于localhost回调 URL 的限制可能需要借助 ngrok 等内网穿透工具暴露本地服务而邮箱认证不涉及外部跳转可以直接在本地环境测试。CSRF 令牌自动化双提交 Cookie 模式的工程实现集合的一大亮点是开箱即用的 CSRF 防护自动化预请求脚本会自动获取 CSRF 令牌存入csrf_token变量所有状态变更请求POST/PUT/DELETE都会自动带上X-CSRF-Token请求头。预请求脚本原理集合在 Collection 级注册了一个prerequest脚本见集合 JSON 的event段逻辑如下当全局变量中不存在csrf_token时先向{{baseUrl}}/api/auth/csrf-token发起 GET 请求把响应中的data.token存入全局变量if (!pm.globals.get(csrf_token)) { const getCsrfRequest { url: pm.environment.get(baseUrl) /api/auth/csrf-token, method: GET, header: { Content-Type: application/json } }; pm.sendRequest(getCsrfRequest, (error, response) { if (!error response.json().success) { pm.globals.set(csrf_token, response.json().data.token); } }); }对应的服务端实现位于 worker/services/csrf/CsrfService.ts采用标准的double-submit cookie双提交 Cookie模式令牌存放在名为csrf-token的 Cookie 中同时要求请求头携带X-CSRF-Token服务端校验二者是否存在且值完全一致validateDoubleSubmitToken缺失或不一致都会记录csrf_violation安全事件并拒绝请求默认配置见 worker/config/security.ts 的getCSRFConfigtokenTTL为 2 小时2 * 60 * 60 * 1000msrotateOnAuth为true登录/登出等认证状态变化时轮换令牌Cookie 名csrf-token请求头名X-CSRF-Token。全局 CSRF 中间件在 worker/app.ts 中注册GET/HEAD/OPTIONS 请求在成功响应后由CsrfService.enforce负责种下令牌非安全方法POST/PUT/DELETE 等则先校验再放行。同时该中间件做了三项合理豁免WebSocket 升级请求、携带Authorization: Bearer头的请求、携带X-API-Key头的请求后两者属于显式凭证不属于 Cookie 冒用场景。注意集合中部分请求使用的是pm.globals而非pm.environment存储令牌因此如果你在多个环境间切换建议在切换后手动运行一次Get CSRF Token请求以确保令牌与当前 Cookie 匹配。三种认证方式详解1. 邮箱认证注册与登录均向public级路由发起注册成功后集合的测试脚本会自动提取user_id与session_id存入变量POST /api/auth/register { email: userexample.com, password: SecurePassword123!, name: Test User } POST /api/auth/login { email: userexample.com, password: SecurePassword123! }对应的路由声明在 authRoutes.tsPOST /register与POST /login均标记为public而GET /profile、PUT /profile、POST /logout等则需要authenticated级别。2. OAuth 认证Google OAuthGET /api/auth/oauth/googleGitHub OAuthGET /api/auth/oauth/github按上文OAuth 测试策略一节在浏览器中完成认证会话 Cookie 即自动生效。3. 基于会话的认证使用安全的 HTTP-only Cookie 维持会话请求间自动保持登录态所有状态变更请求通过X-CSRF-Token请求头提供 CSRF 防护认证级别在 worker/middleware/auth/routeAuth.ts 中定义为public、authenticated、owner-only三档详见下文认证级别小节并在 worker/app.ts 中默认对所有/api/*路由强制要求认证再按各路由显式声明的级别放行。核心 API 工作流工作流一用 AI 创建应用这是平台的核心能力涉及 HTTP 启动、WebSocket 实时推送、沙箱预览三步。相关路由全部位于 codegenRoutes.ts。# 1. 登录或走 OAuth POST /api/auth/login # 2. 启动代码生成需要认证 POST /api/agent { query: Create a React todo app with TypeScript and Tailwind CSS, agentMode: smart, language: typescript, frameworks: [react, tailwindcss], selectedTemplate: react-typescript } # 3. 连接 WebSocket 接收实时进度 GET /api/agent/{agentId}/ws (WebSocket) # 4. 就绪后部署预览 GET /api/agent/{agentId}/preview从源码角度补充几点实现事实POST /api/agent映射到CodingAgentController.startCodeGeneration要求authenticated级别成功后返回的data.agentId会被集合的测试脚本自动写入agent_id变量供后续请求使用GET /api/agent/:agentId/ws是owner-only的 WebSocket 端点支持基于票据ticket的认证SDK 场景或基于 JWT 的认证浏览器场景GET /api/agent/:agentId/preview为authenticated级别部署的是临时的沙箱预览不会改动生产部署状态——这保证了公开应用的预览可被任意登录用户触发同时私有应用的所有权校验在控制器内部完成同一路由文件还提供了数据库只读查看/db/tables、/db/query、/db/wipe、分支列表/branches与制品仓库代理/api/artifacts/*等端点均为 owner-only 或按控制器内部逻辑做归属校验。工作流二浏览与互动应用# 获取公开应用无需认证 GET /api/apps/public?page1limit20sortstarsorderdesc # 获取应用详情无需认证 GET /api/apps/{appId} # 收藏/星标应用需要认证 POST /api/apps/{appId}/star # Fork 应用需要认证 POST /api/apps/{appId}/fork对照 appRoutes.ts 的实现事实GET /api/apps/public是公开端点支撑前端/apps公共应用列表页GET /api/apps/:id同样是公开端点路由声明在具体路由之后以避免冲突允许未登录用户查看和预览应用POST /api/apps/:id/star为authenticated级别可对任何公开应用收藏⚠️Fork 接口的现状集合文档与 JSON 中保留了POST /api/apps/:id/fork但当前 appRoutes.ts 中该路由已被注释禁用注释注明因安全原因在初期 alpha 版本中禁用。因此在当前版本中调用该端点会得到 404 或 403这正体现了文档开头使用前务必对照worker/api/routes/核验的警告价值此外源码中还有/recent、/favorites、/:id/favorite收藏切换、/:id/visibility可见性owner-only、DELETE /:idowner-only、/:id/git/token与/:id/preview-tokenowner-only等集合未收录的端点可作为扩展测试对象。工作流三配置 AI 模型模型配置支持按 Agent 动作维度精细化覆盖模型参数并可接入 BYOKBring Your Own Key供应商# 获取可用模型与供应商 GET /api/model-configs/byok-providers # 更新指定 Agent 动作的模型配置 PUT /api/model-configs/planner { modelName: claude-3-5-sonnet-20241022, maxTokens: 4096, temperature: 0.7, reasoningEffort: medium, fallbackModel: gpt-4o, isUserOverride: true } # 测试模型配置 POST /api/model-configs/test { agentActionName: planner, useUserKeys: true }modelConfigRoutes.ts 的实现比集合收录的更加完整除上述三个端点外还包含GET /全部配置、GET /defaults默认值、GET /:agentAction单动作配置、DELETE /:agentAction删除配置、POST /reset-all重置全部。所有模型配置端点均要求authenticated级别。其中PUT /api/model-configs/:agentAction中的:agentAction是路径参数集合里以planner为例实际可传值取决于 Agent 的动作清单可先调用GET /api/model-configs或GET /api/model-configs/defaults查看。工作流四管理密钥与自定义模型供应商# 获取密钥模板 GET /api/secrets/templates # 存储 API 密钥历史版本 POST /api/secrets { templateId: openai_api_key, name: My OpenAI API Key, envVarName: OPENAI_API_KEY, value: sk-your-api-key-here } # 创建自定义模型供应商 POST /api/user/providers { name: My Custom OpenAI Provider, baseUrl: https://api.openai.com/v1, apiKey: sk-your-key, models: [...] }源码核验结论自定义供应商路由在 modelProviderRoutes.ts 中完整存在GET/POST /api/user/providers、GET/PUT/DELETE /api/user/providers/:id外加POST /api/user/providers/test用于连通性测试全部要求认证⚠️密钥管理端点的现状当前 worker/api/routes/index.ts 中setupSecretsRoutes(app)与setupUserSecretsRoutes(app)均已被注释掉注释注明legacy D1-basedsecretsRoutes.ts 中也只保留了GET /api/secrets/templates。也就是说集合里收录的GET /api/secrets与POST /api/secrets属于历史版本端点在当前代码中未必可调用。这与集合本身的遗留定位一致——使用前务必按当前路由文件核验。高级特性请求自动化与 WebSocket 测试请求自动化机制集合通过 Pre-request Script 与 Test Script 实现了完整的请求自动化链路CSRF 令牌预请求脚本自动获取并注入会话管理Cookie 由 Postman 透明维持变量填充注册/登录后写入user_id、session_id创建应用后写入agent_id获取应用详情后写入app_id错误处理各请求的测试脚本会校验 HTTP 状态码与响应结构例如注册请求的脚本会断言response.data.user.email存在CSRF 请求会断言data.token已保存。典型的变量提取测试脚本模式摘自集合 JSON 的注册请求if (pm.response.code 200) { const response pm.response.json(); if (response.success response.data.user) { pm.globals.set(user_id, response.data.user.id); pm.globals.set(session_id, response.data.sessionId); } } pm.test(Status code is 200, () { pm.response.to.have.status(200); });WebSocket 端点测试AI 代码生成过程中的实时消息通过 WebSocket 推送Postman 对 WebSocket 的支持有限推荐使用wscat等专用客户端使用支持 WebSocket 的客户端wscat、Postman WebSocket 等连接ws://localhost:8787/api/agent/{agentId}/ws请求需携带认证 Cookie或 SDK 场景下的票据参数在代码生成期间收发实时消息。源码侧该端点由 codegenRoutes.ts 中的GET /api/agent/:agentId/ws提供标记为owner-only并开启了ticketAuth资源类型agent参数名agentId因此连接前必须确保已登录且拥有该应用。本地与生产环境搭建本地开发启动 Wrangler 开发服务器仓库根目录执行bun run dev更新 Postman 环境将baseUrl设为http://localhost:8787确保.dev.vars中包含所需的环境变量OAuth 客户端 ID/Secret、数据库绑定等确保 D1 迁移已应用bun run db:migrate:local前端 Vite 开发服务器需保持运行同样由bun run dev管理或单独启动否则页面资源不可用邮箱认证可直接在 localhost 上测试OAuth 可能需要 ngrok 等工具暴露回调地址。生产测试将baseUrl更新为你的生产域名确保 OAuth 应用配置了正确的回调 URL与redirect_url参数及服务端配置一致使用真实的 OAuth 凭据完成端到端验证。API 设计规范认证级别、通用参数与响应格式认证级别集合覆盖了三种访问级别对应 routeAuth.ts 中AuthConfig的定义Public无需认证即可访问如GET /api/health、GET /api/auth/providers、GET /api/auth/csrf-token、GET /api/apps/public、GET /api/apps/:idAuthenticated要求有效会话如个人应用列表、模型配置、密钥/供应商管理Owner Only除认证外还要求资源归属校验checkAppOwnership通过AppService.checkAppOwnership验证agentId/user.id如DELETE /api/apps/:id、GET /api/agent/:agentId/ws、GET /api/user/:id/analytics等。通用查询参数参数说明示例page分页页码1limit每页条数20sort排序字段createdAt、starsorder排序方向asc、descperiod时间周期过滤today、week、month、allsearch搜索关键词todo app成功响应格式集合文档约定的统一成功响应结构为{ success: true, data: { ... }, message: Optional message, pagination: { page: 1, limit: 20, total: 100, totalPages: 5 } }这与 worker/api/responses.ts 中successResponse()的实现一致{ success: true, data, message }为统一外壳pagination仅出现在分页接口中。错误响应格式文档约定{ success: false, error: Error message, code: ERROR_CODE, details: { ... } }需要说明的是当前实现worker/api/responses.ts 的errorResponse()将error设计为对象而非字符串结构为{ message, name, type?, errorType?, exceededLimits?, hasUserToken? }并携带 HTTP 状态码401/403/429/500 等。此外认证失败时 routeAuth.ts 会返回{ success: false, error: { type: AUTHENTICATION_REQUIRED | FORBIDDEN, message, action } }这样的标准化错误其中type字段即对应文档中的code语义。测试脚本与自动化集成时应以实际响应结构为准做兼容。故障排查指南常见问题与对策CSRF 令牌错误确认预请求脚本已启用Import 时默认保留脚本手动运行一次Get CSRF Token请求刷新令牌检查 POST/PUT/DELETE 请求是否带上了X-CSRF-Token请求头确认csrf_token变量值未过期服务端默认 TTL 为 2 小时见 worker/config/security.ts。认证问题在 Postman 中确认 Cookie 已启用Settings → Allow cookies for your domain检查 OAuth 回调 URL 是否与你的配置一致会话过期时先运行Get User Profile验证再重新登录。WebSocket 连接失败WebSocket 要求有效的会话认证owner-onlyPostman WebSocket 支持有限时改用wscat等外部客户端确认agentId属于当前登录用户。本地开发异常确认 Vite 前端已运行bun run dev检查.dev.vars是否包含所需环境变量确认 D1 迁移已应用bun run db:migrate:local。获取帮助的常规步骤查看 API 响应体错误信息通常包含具体原因与类型核验环境确认baseUrl指向正确的环境测试认证运行Check Auth StatusGET /api/auth/check验证会话有效性查看日志浏览器 DevTools 或 Wrangler 日志中通常有更详细的服务端上下文。端到端测试工作流与健康检查完整用户旅程验证按以下顺序执行集合中的请求即可覆盖一条完整的用户旅程注册/登录→ 验证认证链路创建应用→ 验证 AI 生成链路浏览公开应用→ 验证公共 Feed收藏/Fork 应用→ 验证社交功能注意 Fork 当前版本已禁用配置模型→ 验证 AI 定制能力管理密钥→ 验证安全功能注意 secrets 写接口当前路由未挂载导出到 GitHub→ 验证集成能力POST /api/github-app/export。快速健康检查运行以下 5 个请求即可快速判断系统各模块是否正常GET /api/auth/providers— 系统状态GET /api/apps/public— 公共 API 可用性POST /api/auth/login— 认证可用性GET /api/model-configs— AI 系统可用性GET /api/stats— 统计/分析可用性。与当前 Think 行为的兼容性提示最后再强调一次集合的定位这是一套遗留 V1 Dev/phasic API的文档化集合尚未迁移到当前的 Think 行为。从源码看V1 阶段的部分路由如 secrets 写接口、fork已在新版本中停用或注释而新增能力如GET /api/agent/:agentId/branches、/api/artifacts/*、WebSocket 票据认证并未收录进集合。因此做兼容性回归测试时本集合是绝佳基线请务必结合 worker/api/routes/index.ts 确认目标端点当前是否已挂载做新功能联调时建议在集合基础上按 codegenRoutes.ts 等最新路由文件补充请求集合内置的 CSRF 双提交令牌自动化与 OAuth 浏览器跳转方案是理解 vibesdk 认证安全模型CsrfService、routeAuth.ts的直观入口可长期保留用于安全行为验证。【免费下载链接】vibesdkAn open-source vibe coding platform that helps you build your own vibe-coding platform, built entirely on Cloudflare stack项目地址: https://gitcode.com/GitHub_Trending/vi/vibesdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考