VibeSDK 仓库 AI 协作开发指南Cloudflare 全栈 Agentic 平台的架构模式与工程规范【免费下载链接】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/vibesdkVibeSDK 是一个开源的全栈应用构建平台Agentic Full-Stack Application Builder整套系统运行在 Cloudflare 技术栈之上。本文以仓库根目录的 CLAUDE.md 为核心骨架系统讲解 VibeSDK 的架构模式、目录约定、常见开发任务的操作路径以及面向 AI Agent 协作的硬性工程规范并结合 worker、src、space、sdk 等目录下的真实源码进行纵深印证。读完本文你将掌握在 VibeSDK 仓库中安全地进行模型切换、Agent 行为定制、WebSocket 协议扩展、工具链注册与 API 端点新增的完整方法同时理解其底层的关键设计约束。项目概览VibeSDK 是什么VibeSDK 定位为 Cloudflare 上的Agentic 全栈应用构建器用户用自然语言描述需求AI Agent 负责规划、编辑文件、部署预览、检查错误并持续迭代全程有人类在环Human-in-the-loop。整个工作流完全运行在 Cloudflare 平台上Agent 引擎Cloudflare Think 驱动模型与工具的循环model-and-tool loop并通过 AI Gateway 做模型路由工作区每个项目由 Durable ObjectSpaceDO提供隔离的工作区与文件系统预览运行时通过 Worker Loader 绑定将打包后的代码加载为 Dynamic Worker 预览应用数据生成的每个 App 通过 Durable Object Facet 获得隔离的 SQLite 存储版本历史Cloudflare Artifacts 保存持久的 git 历史与恢复点。技术栈一览CLAUDE.md 明确列出的技术栈如下层次技术选型前端React 19、TypeScript、Vite、TailwindCSS、React Router v7后端Cloudflare Workers、Durable Objects、Hono、D1、R2、KVAgentCloudflare Think AI Gateway 模型路由工作区SpaceDO Durable Objects版本历史Cloudflare Artifacts预览运行时Worker Loader 绑定 Dynamic Workers生成应用数据Durable Object Facets隔离 SQLite实时通信PartySocket从 README.md 的架构表可以进一步确认各组件职责ThinkAgent负责模型与工具循环、SpaceDO提供项目隔离工作区、Cloudflare Artifacts 存储提交与分支、Worker Loader 加载 Dynamic Worker 预览、生成的App以 Durable Object Facet 形式承载隔离 SQLite、AI Gateway 负责模型路由与可观测性。项目结构导航CLAUDE.md 给出了顶层目录的职责划分与仓库实际布局一致srcReact 前端、API 类型与 API clientworker/agents/thinkThinkAgent、提示词prompts、技能skills、工作区适配器与工具worker/agents/core/behaviors/think.tsThink 宿主编排Think host orchestrationworker/api路由、控制器、处理器与 WebSocket 类型worker/databaseD1 schema 与数据服务spaceSpaceDO、Artifacts 同步、预览打包与 App FacetssdkTypeScript 客户端 SDKmigrationsD1 迁移脚本scripts环境搭建与部署工具。其中 Agent 相关的代码体量最大worker/agents下还包含core行为基类与状态机、operations各生成/调试策略、inferutils模型推断与推理配置、tools工具注册与资源、thinkThink 专用提示词与技能等子目录开发前建议先浏览 worker/agents 的整体结构。关键架构模式ThinkAgent一个 App 会话对应一个 Durable ObjectCLAUDE.md 指出ThinkAgent 是由一个 Durable Object 支撑、按 app 会话隔离的 Agent 实例它负责对话上下文、上下文选择、技能skills、流式输出、工具调用与步数限制step limits。它使用显式的 SpaceDO 支撑工具工作区 bash 被禁用。源码印证了这一设计。在 worker/agents/think/ThinkAgent.ts 中export class ThinkAgent extends ThinkEnv { /** Step budget per turn (Thinks default is 10). */ override maxSteps 25; /** SpaceDO has no shell; expose only the explicit file tools. */ override workspaceBash false;两个关键覆盖点值得注意maxSteps 25将 Think 默认的每轮步数上限从 10 提高到 25给长链路工具调用留出空间当步数耗尽时prompts.ts 会注入一个强制收尾的max-steps.txt提示词作为最后一条用户消息迫使模型进行无工具的总结输出。workspaceBash false彻底关闭 shell 类工具Agent 只能通过显式的文件工具readFile/writeFile/editFile/list/find/grep/delete等来自cloudflare/think/tools/workspace操作 SpaceDO 工作区这是安全隔离的关键一环。ThinkAgent 的宿主编排由 worker/agents/core/behaviors/think.ts 中的ThinkCodingBehavior承担它每 App 持有一个ThinkAgentDOagentic 循环 消息持久化和一个SpaceDOgit 文件 预览/部署通过configureVibe()把解析好的 AI Gateway 模型配置推入 ThinkAgent再以ThinkAgent.chat()驱动每轮对话并将流式UIMessageChunk翻译为 VibeSDK 的 WebSocket 事件。该行为同时实现了ICodingAgent接口说明它是整个 Agent 编排链路上可替换的一环。工作区与版本控制SpaceDO Cloudflare ArtifactsCLAUDE.md 明确了分层职责SpaceDO 拥有隔离的实时工作区与文件workspace layerCloudflare Artifacts 拥有持久的提交、分支、历史与恢复点git/history layercommit只保存不部署deploy_space则提交并重建预览回滚Rollback将选中的 commit tree 应用到当前分支、创建新提交并重新部署不会改写已有历史。从 worker/agents/think/space-workspace-ops.ts 可以看到 SpaceDO 对外暴露的 RPC 面readFile、readFileBytes、writeFile、mkdir、rm、readDir、glob、stat以及 git/部署相关方法gitCommit、gitStatus、deploy、rollbackToCommit。这些方法被封装成 Think 工作区工具createSpaceWorkspaceOps是 Agent 触碰文件的唯一通道。Artifacts 的同步逻辑位于 space/src/space/artifacts-sync.ts。预览运行时打包 → Worker Loader → Dynamic WorkerCLAUDE.md 描述的三步链路为cloudflare/worker-bundler构建已提交的项目文件 → Worker Loader 将打包后的模块加载为 Dynamic Worker → 生成的App类以 Durable Object Facet 运行并持有隔离 SQLite。结合 README.md 的补充静态资源由 SpaceDO 提供后端请求与 WebSocket 转发到生成的AppFacet每个 Facet 的 SQLite 可被用户查看与重置。WebSocket 通信PartySocket 会话恢复实时通道由 PartySocket 承载传输 Agent 实时输出、工具调用、文件变化与部署状态会话状态在重连后恢复。消息类型的定义与处理分散在三处这与下文添加新 WebSocket 消息的开发流程一一对应。常见开发任务实战CLAUDE.md 用大量篇幅给出了五类高频开发任务的完成路径下面逐项结合源码展开。任务一更换运行所用的 LLM 模型操作入口编辑 worker/agents/inferutils/config.ts 中的AGENT_CONFIG对象。深入源码可以看到AGENT_CONFIG的最终取值由环境变量PLATFORM_MODEL_PROVIDERS决定config.tsexport const AGENT_CONFIG: AgentConfig env.PLATFORM_MODEL_PROVIDERS ? PLATFORM_AGENT_CONFIG : DEFAULT_AGENT_CONFIG;未设置PLATFORM_MODEL_PROVIDERS时走DEFAULT_AGENT_CONFIG纯 Gemini 的开箱即用配置各操作统一以GEMINI_3_FLASH_PREVIEW为主模型GEMINI_2_5_PRO/GEMINI_2_5_FLASH作 fallback设置后走PLATFORM_AGENT_CONFIG这是build.cloudflare.dev生产环境的配置混用 Gemini、Grok 等多个供应商模型如GEMINI_3_PRO_PREVIEW负责 blueprint、GROK_4_1_FAST负责 projectSetup 与 deepDebugger、OPENAI_5_MINI作 fallback需要为各模型提供 API Key或使用 AI Gateway 统一计费免去多 Key 管理。每个操作agent action的配置结构包含四个维度字段含义典型取值name主模型 ID来自AIModels枚举AIModels.GEMINI_3_FLASH_PREVIEW等reasoning_effort推理强度low/medium/highmax_tokens单次输出的 token 上限2000templateSelection 64000blueprinttemperature采样温度0.0修复类 1生成类fallbackModel主模型失败时的降级模型同一配置内成对出现以DEFAULT_AGENT_CONFIG中的blueprint为例config.tsblueprint: { name: AIModels.GEMINI_3_FLASH_PREVIEW, reasoning_effort: high, max_tokens: 64000, fallbackModel: AIModels.GEMINI_2_5_PRO, temperature: 1, },此外config.ts 还通过AGENT_CONSTRAINTS对部分操作做模型白名单约束例如templateSelection只允许LiteModels、conversationalResponse只允许RegularModels、fastCodeFixer与realtimeCodeFixer默认被DISABLED关闭。修改模型时务必同步检查该 Map避免配置与约束冲突。注意config.ts 头部注释明确提示平台级配置依赖特定 API Key 与 Cloudflare AI Gateway 环境本地开发默认走 Gemini-only 配置即可。任务二修改 Think Agent 行为CLAUDE.md 给出的修改面有三个编辑 worker/agents/think/ThinkAgent.tsAgent 本体负责模型实例化getModel()、会话配置configureSession()、步数预算与工具装配编辑 worker/agents/core/behaviors/think.ts宿主行为负责将模型配置推入 AgentconfigureVibe()、驱动chat()并把流式事件翻译成 WebSocket 事件更新相关的 prompt 或 skill提示词按模型家族分文件存放于 worker/agents/think/prompts*.txt由 prompts.ts 的selectSystemPrompt()按模型 ID 自动选择——例如gemini前缀命中gemini.txt、claude命中anthropic.txt、codex命中codex.txt未命中任何家族则回落default.txt。值得注意的实现细节ThinkAgent 的getModel()ThinkAgent.ts使用createOpenAI指向 AI Gateway 的/compat/chat/completions兼容端点而非默认的 Responses API并通过自定义fetch包装完成三件事BYOK/stored-keys 模式下剥离供应商Authorization头避免覆盖网关存储的密钥、修补 Google 兼容流中缺失的tool_calls[].index字段、以及在请求历史中往返注入 Gemini 的thought_signature否则 Gemini 3 会以400 INVALID_ARGUMENT拒绝缺少签名的函数调用历史。修改模型行为时这些兼容层不应被破坏。任务三添加新的 WebSocket 消息CLAUDE.md 给出了严格的三步流程在 worker/api/websocketTypes.ts 添加消息类型在 worker/agents/core/websocket.ts 处理该消息在 src/routes/chat/utils/handle-websocket-message.ts 处理前端收到的对应消息。从 worker/agents/core/websocket.ts 可以看到服务端消息处理的骨架handleWebSocketMessage()解析 JSON 后按parsedMessage.type进入 switch 分支如SESSION_INIT、GENERATE_ALL等消息类型常量集中在worker/agents/constants.ts的WebSocketMessageRequests/WebSocketMessageResponses中。新增消息时遵循同样的类型定义 → switch 分支 → 前端解析三段式保证协议两端始终同步。任务四添加新的 Think 工具CLAUDE.md 给出的步骤是在 worker/agents/think 下创建工具在 worker/agents/think/space-workspace-ops.ts 补充所需的 SpaceDO RPC 类型在ThinkAgent.getTools()中注册更新相关 prompt 或 skill让模型知道何时使用补充聚焦的测试。仓库中已有工具可作为模板参考ask-questions-tool.ts澄清提问、browser-logs-tool.ts读取浏览器控制台日志配合get_browser_console_logs、commit-tool.ts保存恢复点、deploy-tool.ts部署预览、set-title-tool.ts设置会话标题。由于 SpaceDO 是唯一的文件事实源新增工具应通过createSpaceWorkspaceOps(getStub)提供的文件操作原语组合实现而非直接访问底层存储。任务五新增 API 端点CLAUDE.md 给出了端到端的六步链路在 src/api-types.ts 定义类型前端唯一类型来源在 src/lib/api-client.ts 添加 API client 方法在 worker/database/services 创建 service在 worker/api/controllers 创建 controller在 worker/api/routes 添加路由在 worker/api/routes/index.ts 注册路由。这套约定在 CLAUDE.md 的遵循现有模式规则中再次被强调前端 API 全部收敛在api-client.ts后端路由采用 controllers routes 分层数据库访问统一走worker/database/services/类型则区分共享类型shared/types与 API 类型src/api-types.ts。新增端点时按此链路逐层补齐即可保证前后端契约一致。重要上下文与实现细节User Secrets StoreDurable ObjectCLAUDE.md 对密钥存储模块给出了详细说明源码位于 worker/services/secrets位置/worker/services/secrets/仓库相对路径 worker/services/secrets用途以加密方式存储用户 API Key支持密钥轮换架构每个用户一个 DO采用 XChaCha20-Poly1305 加密SQLite 作为后端存储密钥派生链MEK → UMK → DEK 的分层 PBKDF2 派生功能密钥轮换、软删除、访问跟踪、过期支持RPC 约定出错时返回null/boolean绝不抛异常测试CLAUDE.md 记载有 90 个测试用例仓库中的测试文件为 worker/services/secrets/UserSecretsStore.test.ts。该模块由 SecretsClient.ts 等客户端封装对外暴露前端侧配合 src/contexts/vault-context.tsx 与 src/components/vault 的 Vault 界面使用。工作区与 GitSpaceDO 提供工作区与文件操作Cloudflare Artifacts 存储持久的 git 历史Artifacts 同步逻辑在 space/src/space/artifacts-sync.ts回滚通过创建新提交保留历史而不是重写历史。Abort Controller 模式CLAUDE.md 描述的取消语义在 worker/agents/core/behaviors/base.ts 中有对应实现getOrCreateAbortController()为嵌套操作复用同一个 controller不重复创建已中止的 controller在顶层操作完成后清理父工具调用与嵌套工具调用共享同一信号用户中止会取消整棵操作树agentic.ts 中通过抛出 abort error 打断工具调用链。该模式保证了用户取消 → 级联取消所有嵌套工具调用的一致性是长链路 Agent 任务中的关键基础设施。消息去重Message DeduplicationCLAUDE.md 解释了重复 AI 消息的产生与处理机制工具执行会导致 AI 消息重复后端会跳过冗余的 LLM 调用空工具结果时前端工具负责对实时与恢复的消息去重见 src/routes/chat/utils/deduplicate-messages.ts系统提示词教导 LLM 不要重复system prompt teaches LLM not to repeat。核心工程规则Non-NegotiableCLAUDE.md 将以下规则标记为不可协商是面向 AI Agent 协作时最需要严格执行的部分1. 严格类型安全永远不要使用any类型找不到类型就创建合适的类型前端统一从/api-types导入类型单一事实来源创建新类型前先搜索代码库中是否已有。2. DRY 原则实现前先搜索是否存在相似功能将可复用逻辑抽取为工具函数、hooks 与组件绝不复制粘贴代码一律重构为共享函数。3. 遵循现有模式关注点约定位置前端 API全部集中在 src/lib/api-client.ts后端路由controller 在 worker/api/controllers路由在 worker/api/routes数据库服务worker/database/services类型共享类型在 shared/typesAPI 类型在 src/api-types.ts4. 代码质量只产出生产级代码不允许 TODO 或占位符不做 hacky workaround注释解释为什么不做叙述性注释避免冗长、类 AI 生成的注释。5. 文件命名约定文件类型命名规范React 组件PascalCase.tsx工具函数 / Hookskebab-case.ts后端服务PascalCase.ts常见陷阱与最佳实践CLAUDE.md 用Dont / Do对照表总结了开发时的红线不要Dont使用any类型——应查找或创建合适的类型复制粘贴代码——应抽取为公共工具在 Worker 代码中使用 Vite 环境变量import.meta.env等——Vite 变量只属于前端构建修改 API 时忘记同步更新类型在未搜索现有实现的情况下新建实现在代码或注释中使用 emoji编写冗长、类 AI 的注释。要Do在创建新代码前彻底搜索代码库始终遵循现有模式保持一致性注释保持简洁且有目的只写生产级代码提交前充分测试。沟通风格约定CLAUDE.md 开篇即定义了面向 AI 编码助手Claude Code 等的沟通规范也适用于所有仓库贡献者专业、简洁、直接在代码评审、变更日志或任何生成内容中不使用 emoji可改用专业的视觉标识或 Markdown 格式内容重于形式substance over style使用清晰的技术语言。结语把 CLAUDE.md 当作协作契约对 VibeSDK 这类AI 原生项目而言CLAUDE.md 不只是给 Claude Code 的提示词它实际上是一份浓缩的架构文档与协作契约worker/agents/think与worker/agents/core/behaviors/think.ts定义了 Agent 的运行时形态worker/agents/inferutils/config.ts定义了模型路由策略worker/services/secrets定义了密钥安全边界而严格类型安全 DRY 遵循现有模式三原则则保证了在多 Agent 协作下代码库仍能保持结构一致性。在动手修改前先通读本指南对应的源码路径尤其是 ThinkAgent.ts、think.ts、config.ts 与 space-workspace-ops.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），仅供参考
VibeSDK 仓库 AI 协作开发指南Cloudflare 全栈 Agentic 平台的架构模式与工程规范【免费下载链接】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/vibesdkVibeSDK 是一个开源的全栈应用构建平台Agentic Full-Stack Application Builder整套系统运行在 Cloudflare 技术栈之上。本文以仓库根目录的 CLAUDE.md 为核心骨架系统讲解 VibeSDK 的架构模式、目录约定、常见开发任务的操作路径以及面向 AI Agent 协作的硬性工程规范并结合 worker、src、space、sdk 等目录下的真实源码进行纵深印证。读完本文你将掌握在 VibeSDK 仓库中安全地进行模型切换、Agent 行为定制、WebSocket 协议扩展、工具链注册与 API 端点新增的完整方法同时理解其底层的关键设计约束。项目概览VibeSDK 是什么VibeSDK 定位为 Cloudflare 上的Agentic 全栈应用构建器用户用自然语言描述需求AI Agent 负责规划、编辑文件、部署预览、检查错误并持续迭代全程有人类在环Human-in-the-loop。整个工作流完全运行在 Cloudflare 平台上Agent 引擎Cloudflare Think 驱动模型与工具的循环model-and-tool loop并通过 AI Gateway 做模型路由工作区每个项目由 Durable ObjectSpaceDO提供隔离的工作区与文件系统预览运行时通过 Worker Loader 绑定将打包后的代码加载为 Dynamic Worker 预览应用数据生成的每个 App 通过 Durable Object Facet 获得隔离的 SQLite 存储版本历史Cloudflare Artifacts 保存持久的 git 历史与恢复点。技术栈一览CLAUDE.md 明确列出的技术栈如下层次技术选型前端React 19、TypeScript、Vite、TailwindCSS、React Router v7后端Cloudflare Workers、Durable Objects、Hono、D1、R2、KVAgentCloudflare Think AI Gateway 模型路由工作区SpaceDO Durable Objects版本历史Cloudflare Artifacts预览运行时Worker Loader 绑定 Dynamic Workers生成应用数据Durable Object Facets隔离 SQLite实时通信PartySocket从 README.md 的架构表可以进一步确认各组件职责ThinkAgent负责模型与工具循环、SpaceDO提供项目隔离工作区、Cloudflare Artifacts 存储提交与分支、Worker Loader 加载 Dynamic Worker 预览、生成的App以 Durable Object Facet 形式承载隔离 SQLite、AI Gateway 负责模型路由与可观测性。项目结构导航CLAUDE.md 给出了顶层目录的职责划分与仓库实际布局一致srcReact 前端、API 类型与 API clientworker/agents/thinkThinkAgent、提示词prompts、技能skills、工作区适配器与工具worker/agents/core/behaviors/think.tsThink 宿主编排Think host orchestrationworker/api路由、控制器、处理器与 WebSocket 类型worker/databaseD1 schema 与数据服务spaceSpaceDO、Artifacts 同步、预览打包与 App FacetssdkTypeScript 客户端 SDKmigrationsD1 迁移脚本scripts环境搭建与部署工具。其中 Agent 相关的代码体量最大worker/agents下还包含core行为基类与状态机、operations各生成/调试策略、inferutils模型推断与推理配置、tools工具注册与资源、thinkThink 专用提示词与技能等子目录开发前建议先浏览 worker/agents 的整体结构。关键架构模式ThinkAgent一个 App 会话对应一个 Durable ObjectCLAUDE.md 指出ThinkAgent 是由一个 Durable Object 支撑、按 app 会话隔离的 Agent 实例它负责对话上下文、上下文选择、技能skills、流式输出、工具调用与步数限制step limits。它使用显式的 SpaceDO 支撑工具工作区 bash 被禁用。源码印证了这一设计。在 worker/agents/think/ThinkAgent.ts 中export class ThinkAgent extends ThinkEnv { /** Step budget per turn (Thinks default is 10). */ override maxSteps 25; /** SpaceDO has no shell; expose only the explicit file tools. */ override workspaceBash false;两个关键覆盖点值得注意maxSteps 25将 Think 默认的每轮步数上限从 10 提高到 25给长链路工具调用留出空间当步数耗尽时prompts.ts 会注入一个强制收尾的max-steps.txt提示词作为最后一条用户消息迫使模型进行无工具的总结输出。workspaceBash false彻底关闭 shell 类工具Agent 只能通过显式的文件工具readFile/writeFile/editFile/list/find/grep/delete等来自cloudflare/think/tools/workspace操作 SpaceDO 工作区这是安全隔离的关键一环。ThinkAgent 的宿主编排由 worker/agents/core/behaviors/think.ts 中的ThinkCodingBehavior承担它每 App 持有一个ThinkAgentDOagentic 循环 消息持久化和一个SpaceDOgit 文件 预览/部署通过configureVibe()把解析好的 AI Gateway 模型配置推入 ThinkAgent再以ThinkAgent.chat()驱动每轮对话并将流式UIMessageChunk翻译为 VibeSDK 的 WebSocket 事件。该行为同时实现了ICodingAgent接口说明它是整个 Agent 编排链路上可替换的一环。工作区与版本控制SpaceDO Cloudflare ArtifactsCLAUDE.md 明确了分层职责SpaceDO 拥有隔离的实时工作区与文件workspace layerCloudflare Artifacts 拥有持久的提交、分支、历史与恢复点git/history layercommit只保存不部署deploy_space则提交并重建预览回滚Rollback将选中的 commit tree 应用到当前分支、创建新提交并重新部署不会改写已有历史。从 worker/agents/think/space-workspace-ops.ts 可以看到 SpaceDO 对外暴露的 RPC 面readFile、readFileBytes、writeFile、mkdir、rm、readDir、glob、stat以及 git/部署相关方法gitCommit、gitStatus、deploy、rollbackToCommit。这些方法被封装成 Think 工作区工具createSpaceWorkspaceOps是 Agent 触碰文件的唯一通道。Artifacts 的同步逻辑位于 space/src/space/artifacts-sync.ts。预览运行时打包 → Worker Loader → Dynamic WorkerCLAUDE.md 描述的三步链路为cloudflare/worker-bundler构建已提交的项目文件 → Worker Loader 将打包后的模块加载为 Dynamic Worker → 生成的App类以 Durable Object Facet 运行并持有隔离 SQLite。结合 README.md 的补充静态资源由 SpaceDO 提供后端请求与 WebSocket 转发到生成的AppFacet每个 Facet 的 SQLite 可被用户查看与重置。WebSocket 通信PartySocket 会话恢复实时通道由 PartySocket 承载传输 Agent 实时输出、工具调用、文件变化与部署状态会话状态在重连后恢复。消息类型的定义与处理分散在三处这与下文添加新 WebSocket 消息的开发流程一一对应。常见开发任务实战CLAUDE.md 用大量篇幅给出了五类高频开发任务的完成路径下面逐项结合源码展开。任务一更换运行所用的 LLM 模型操作入口编辑 worker/agents/inferutils/config.ts 中的AGENT_CONFIG对象。深入源码可以看到AGENT_CONFIG的最终取值由环境变量PLATFORM_MODEL_PROVIDERS决定config.tsexport const AGENT_CONFIG: AgentConfig env.PLATFORM_MODEL_PROVIDERS ? PLATFORM_AGENT_CONFIG : DEFAULT_AGENT_CONFIG;未设置PLATFORM_MODEL_PROVIDERS时走DEFAULT_AGENT_CONFIG纯 Gemini 的开箱即用配置各操作统一以GEMINI_3_FLASH_PREVIEW为主模型GEMINI_2_5_PRO/GEMINI_2_5_FLASH作 fallback设置后走PLATFORM_AGENT_CONFIG这是build.cloudflare.dev生产环境的配置混用 Gemini、Grok 等多个供应商模型如GEMINI_3_PRO_PREVIEW负责 blueprint、GROK_4_1_FAST负责 projectSetup 与 deepDebugger、OPENAI_5_MINI作 fallback需要为各模型提供 API Key或使用 AI Gateway 统一计费免去多 Key 管理。每个操作agent action的配置结构包含四个维度字段含义典型取值name主模型 ID来自AIModels枚举AIModels.GEMINI_3_FLASH_PREVIEW等reasoning_effort推理强度low/medium/highmax_tokens单次输出的 token 上限2000templateSelection 64000blueprinttemperature采样温度0.0修复类 1生成类fallbackModel主模型失败时的降级模型同一配置内成对出现以DEFAULT_AGENT_CONFIG中的blueprint为例config.tsblueprint: { name: AIModels.GEMINI_3_FLASH_PREVIEW, reasoning_effort: high, max_tokens: 64000, fallbackModel: AIModels.GEMINI_2_5_PRO, temperature: 1, },此外config.ts 还通过AGENT_CONSTRAINTS对部分操作做模型白名单约束例如templateSelection只允许LiteModels、conversationalResponse只允许RegularModels、fastCodeFixer与realtimeCodeFixer默认被DISABLED关闭。修改模型时务必同步检查该 Map避免配置与约束冲突。注意config.ts 头部注释明确提示平台级配置依赖特定 API Key 与 Cloudflare AI Gateway 环境本地开发默认走 Gemini-only 配置即可。任务二修改 Think Agent 行为CLAUDE.md 给出的修改面有三个编辑 worker/agents/think/ThinkAgent.tsAgent 本体负责模型实例化getModel()、会话配置configureSession()、步数预算与工具装配编辑 worker/agents/core/behaviors/think.ts宿主行为负责将模型配置推入 AgentconfigureVibe()、驱动chat()并把流式事件翻译成 WebSocket 事件更新相关的 prompt 或 skill提示词按模型家族分文件存放于 worker/agents/think/prompts*.txt由 prompts.ts 的selectSystemPrompt()按模型 ID 自动选择——例如gemini前缀命中gemini.txt、claude命中anthropic.txt、codex命中codex.txt未命中任何家族则回落default.txt。值得注意的实现细节ThinkAgent 的getModel()ThinkAgent.ts使用createOpenAI指向 AI Gateway 的/compat/chat/completions兼容端点而非默认的 Responses API并通过自定义fetch包装完成三件事BYOK/stored-keys 模式下剥离供应商Authorization头避免覆盖网关存储的密钥、修补 Google 兼容流中缺失的tool_calls[].index字段、以及在请求历史中往返注入 Gemini 的thought_signature否则 Gemini 3 会以400 INVALID_ARGUMENT拒绝缺少签名的函数调用历史。修改模型行为时这些兼容层不应被破坏。任务三添加新的 WebSocket 消息CLAUDE.md 给出了严格的三步流程在 worker/api/websocketTypes.ts 添加消息类型在 worker/agents/core/websocket.ts 处理该消息在 src/routes/chat/utils/handle-websocket-message.ts 处理前端收到的对应消息。从 worker/agents/core/websocket.ts 可以看到服务端消息处理的骨架handleWebSocketMessage()解析 JSON 后按parsedMessage.type进入 switch 分支如SESSION_INIT、GENERATE_ALL等消息类型常量集中在worker/agents/constants.ts的WebSocketMessageRequests/WebSocketMessageResponses中。新增消息时遵循同样的类型定义 → switch 分支 → 前端解析三段式保证协议两端始终同步。任务四添加新的 Think 工具CLAUDE.md 给出的步骤是在 worker/agents/think 下创建工具在 worker/agents/think/space-workspace-ops.ts 补充所需的 SpaceDO RPC 类型在ThinkAgent.getTools()中注册更新相关 prompt 或 skill让模型知道何时使用补充聚焦的测试。仓库中已有工具可作为模板参考ask-questions-tool.ts澄清提问、browser-logs-tool.ts读取浏览器控制台日志配合get_browser_console_logs、commit-tool.ts保存恢复点、deploy-tool.ts部署预览、set-title-tool.ts设置会话标题。由于 SpaceDO 是唯一的文件事实源新增工具应通过createSpaceWorkspaceOps(getStub)提供的文件操作原语组合实现而非直接访问底层存储。任务五新增 API 端点CLAUDE.md 给出了端到端的六步链路在 src/api-types.ts 定义类型前端唯一类型来源在 src/lib/api-client.ts 添加 API client 方法在 worker/database/services 创建 service在 worker/api/controllers 创建 controller在 worker/api/routes 添加路由在 worker/api/routes/index.ts 注册路由。这套约定在 CLAUDE.md 的遵循现有模式规则中再次被强调前端 API 全部收敛在api-client.ts后端路由采用 controllers routes 分层数据库访问统一走worker/database/services/类型则区分共享类型shared/types与 API 类型src/api-types.ts。新增端点时按此链路逐层补齐即可保证前后端契约一致。重要上下文与实现细节User Secrets StoreDurable ObjectCLAUDE.md 对密钥存储模块给出了详细说明源码位于 worker/services/secrets位置/worker/services/secrets/仓库相对路径 worker/services/secrets用途以加密方式存储用户 API Key支持密钥轮换架构每个用户一个 DO采用 XChaCha20-Poly1305 加密SQLite 作为后端存储密钥派生链MEK → UMK → DEK 的分层 PBKDF2 派生功能密钥轮换、软删除、访问跟踪、过期支持RPC 约定出错时返回null/boolean绝不抛异常测试CLAUDE.md 记载有 90 个测试用例仓库中的测试文件为 worker/services/secrets/UserSecretsStore.test.ts。该模块由 SecretsClient.ts 等客户端封装对外暴露前端侧配合 src/contexts/vault-context.tsx 与 src/components/vault 的 Vault 界面使用。工作区与 GitSpaceDO 提供工作区与文件操作Cloudflare Artifacts 存储持久的 git 历史Artifacts 同步逻辑在 space/src/space/artifacts-sync.ts回滚通过创建新提交保留历史而不是重写历史。Abort Controller 模式CLAUDE.md 描述的取消语义在 worker/agents/core/behaviors/base.ts 中有对应实现getOrCreateAbortController()为嵌套操作复用同一个 controller不重复创建已中止的 controller在顶层操作完成后清理父工具调用与嵌套工具调用共享同一信号用户中止会取消整棵操作树agentic.ts 中通过抛出 abort error 打断工具调用链。该模式保证了用户取消 → 级联取消所有嵌套工具调用的一致性是长链路 Agent 任务中的关键基础设施。消息去重Message DeduplicationCLAUDE.md 解释了重复 AI 消息的产生与处理机制工具执行会导致 AI 消息重复后端会跳过冗余的 LLM 调用空工具结果时前端工具负责对实时与恢复的消息去重见 src/routes/chat/utils/deduplicate-messages.ts系统提示词教导 LLM 不要重复system prompt teaches LLM not to repeat。核心工程规则Non-NegotiableCLAUDE.md 将以下规则标记为不可协商是面向 AI Agent 协作时最需要严格执行的部分1. 严格类型安全永远不要使用any类型找不到类型就创建合适的类型前端统一从/api-types导入类型单一事实来源创建新类型前先搜索代码库中是否已有。2. DRY 原则实现前先搜索是否存在相似功能将可复用逻辑抽取为工具函数、hooks 与组件绝不复制粘贴代码一律重构为共享函数。3. 遵循现有模式关注点约定位置前端 API全部集中在 src/lib/api-client.ts后端路由controller 在 worker/api/controllers路由在 worker/api/routes数据库服务worker/database/services类型共享类型在 shared/typesAPI 类型在 src/api-types.ts4. 代码质量只产出生产级代码不允许 TODO 或占位符不做 hacky workaround注释解释为什么不做叙述性注释避免冗长、类 AI 生成的注释。5. 文件命名约定文件类型命名规范React 组件PascalCase.tsx工具函数 / Hookskebab-case.ts后端服务PascalCase.ts常见陷阱与最佳实践CLAUDE.md 用Dont / Do对照表总结了开发时的红线不要Dont使用any类型——应查找或创建合适的类型复制粘贴代码——应抽取为公共工具在 Worker 代码中使用 Vite 环境变量import.meta.env等——Vite 变量只属于前端构建修改 API 时忘记同步更新类型在未搜索现有实现的情况下新建实现在代码或注释中使用 emoji编写冗长、类 AI 的注释。要Do在创建新代码前彻底搜索代码库始终遵循现有模式保持一致性注释保持简洁且有目的只写生产级代码提交前充分测试。沟通风格约定CLAUDE.md 开篇即定义了面向 AI 编码助手Claude Code 等的沟通规范也适用于所有仓库贡献者专业、简洁、直接在代码评审、变更日志或任何生成内容中不使用 emoji可改用专业的视觉标识或 Markdown 格式内容重于形式substance over style使用清晰的技术语言。结语把 CLAUDE.md 当作协作契约对 VibeSDK 这类AI 原生项目而言CLAUDE.md 不只是给 Claude Code 的提示词它实际上是一份浓缩的架构文档与协作契约worker/agents/think与worker/agents/core/behaviors/think.ts定义了 Agent 的运行时形态worker/agents/inferutils/config.ts定义了模型路由策略worker/services/secrets定义了密钥安全边界而严格类型安全 DRY 遵循现有模式三原则则保证了在多 Agent 协作下代码库仍能保持结构一致性。在动手修改前先通读本指南对应的源码路径尤其是 ThinkAgent.ts、think.ts、config.ts 与 space-workspace-ops.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），仅供参考
