Onlook 仓库 Agent 开发指南在 AI 优先的 React 设计工具 monorepo 中安全高效地提交代码【免费下载链接】onlookThe Cursor for Designers • An Open-Source AI-First Design tool • Visually build, style, and edit your React App with AI项目地址: https://gitcode.com/GitHub_Trending/on/onlookOnlook 是一个开源、AI 优先的可视化设计工具目标是让设计师像使用 Cursor 一样直接编辑 React 应用并把改动实时写回代码。本指南基于仓库根目录的 AGENTS.md面向在仓库内工作的自动化编码 Agent也适用于人类贡献者系统讲解仓库结构、技术栈约束、tRPC API 与 Supabase 的接入规范、环境变量校验、MobX 状态管理模式以及最小化、安全、省 token 的上下文纪律。读完本文你将掌握在该 monorepo 中新增功能、修复缺陷而不破坏架构约定的完整方法论与可验证的源码依据。一、定位这份指南给谁、要解决什么问题AGENTS.md的第一节直接声明了它的目的与边界受众Audience在仓库内工作的自动化编码 Agent目标Goal产出与项目架构一致的小而正确的 diffsmall, correct diffs非目标Non-goals绝不修改生成产物generated artifacts、锁文件lockfiles或node_modules。换句话说任何 Agent 的每一次改动都应遵循三条铁律diff 最小化、操作安全、token 高效。这三个词minimal, safe, token-efficient贯穿全文是判断一切编码行为是否合规的总纲。二、仓库地图Bun workspaces 驱动的 monorepo从根目录 package.json 可以看到这是一个由Bun workspaces管理的 monorepoworkspaces覆盖了packages/*、apps/*、tooling/*、apps/web/*和docs{ name: onlook/repo, version: 0.0.0, private: true, type: module, workspaces: [ packages/*, apps/*, tooling/*, apps/web/*, docs ], packageManager: bun1.3.1 }AGENTS.md 给出的核心导航信息如下应用入口apps/web/clientNext.js App Router TailwindCSSAPI 路由apps/web/client/src/server/api/routers/*统一在apps/web/client/src/server/api/root.ts聚合导出共享工具库packages/*例如packages/utility。实际从仓库看packages下还包含ai、db、models、parser、ui即onlook/ui等大量可复用包而apps/下还有admin、backend等应用但就 Agent 日常改动而言Web 客户端是最核心的战场。三、技术栈与运行时约束只用 BunAGENTS.md 明确定义了技术栈UINext.js App Router TailwindCSSAPItRPC Zodapps/web/client/src/server/api/*包管理器只用 Bun——所有安装与脚本都使用 Bun禁止 npm、yarn 或 pnpm。这一点在根package.json的脚本中得到印证所有命令都以bun --filter package形式组织例如build: client、dev、test、typecheck等。packageManager字段也锁定了bun1.3.1。因此在仓库内安装依赖、运行脚本时必须使用bun如bun install、bun run script、bun test不要引入其他包管理器的锁文件。四、Next.js App Router 规范Server Component 优先4.1 组件边界默认 RSC按需use client默认使用Server Components只有涉及事件events、state/effects、浏览器 API 或仅客户端库时才添加use client应用结构位于apps/web/client/src/app/**page.tsx、layout.tsx、route.ts客户端 Provider 必须待在客户端边界之后例如apps/web/client/src/trpc/react.tsx使用mobx-react-lite的observer的组件必须是客户端组件包含use client。一个典型的边界示例是 trpc/react.tsx其第一行就是use client然后在组件内通过useState(() api.createClient({ links }))惰性创建 tRPC 客户端并包裹QueryClientProvider与api.Provider。RSC shell 的示范则是 apps/web/client/src/app/layout.tsx它在 Server Component 里把TRPCReactProvider、FeatureFlagsProvider、TelemetryProvider、ThemeProvider强制forcedThemedark保持暗色主题默认值、AuthProvider、NextIntlClientProvider全部接线同时用env.NODE_ENV production门控第三方脚本如 zaraz、RB2BLoader的注入。4.2 为什么“缺use client”是高频坑AGENTS.md 在 Common Pitfalls 中指出该加use client而没加会导致事件无法绑定unbound events而一个位于 feature 根部的边界就足够了子 observer 组件无需再写use client。示例路径是apps/web/client/src/app/project/[id]/_components/main.tsx。五、tRPC API路由、过程与序列化5.1 路由必须导出自 root.tsAGENTS.md 强调Routers 位于apps/web/client/src/server/api/routers/**且必须从apps/web/client/src/server/api/root.ts导出否则端点不可达。查看 root.ts 可以看到它手动聚合了 16 个 routerexport const appRouter createTRPCRouter({ sandbox: sandboxRouter, user: userRouter, invitation: invitationRouter, project: projectRouter, branch: branchRouter, settings: settingsRouter, chat: chatRouter, frame: frameRouter, userCanvas: userCanvasRouter, utils: utilsRouter, member: memberRouter, domain: domainRouter, github: githubRouter, subscription: subscriptionRouter, usage: usageRouter, publish: publishRouter, }); export type AppRouter typeof appRouter; export const createCaller createCallerFactory(appRouter);这意味着每新增一个 router都需要在此处手动注册与 Next.js 路由的约定式聚合不同tRPC 是显式注册。5.2 过程Procedure体系在 trpc.ts 中仓库定义了完整的上下文与过程体系上下文createTRPCContext通过createClient()Supabase 服务端客户端解析当前用户出错即抛UNAUTHORIZED并把db、supabase、user注入上下文初始化initTRPC.contexttypeof createTRPCContext().create({ transformer: superjson, ... })使用SuperJSON做序列化并对 Zod 校验错误做扁平化zodError以提升前端类型安全publicProcedure基础过程附带timingMiddleware开发环境模拟 100–500ms 随机延迟并打印[TRPC] path took Xms日志不保证用户已登录但可读取会话数据protectedProcedure在 public 基础上校验ctx.user存在且拥有 email否则抛UNAUTHORIZED并把 user 类型收窄为SetRequiredDeepUser, emailadminProcedure额外用createAdminClient()以 service role 覆盖ctx.supabase绕过 RLS必须极度谨慎使用源码注释明确标注 Use with extreme caution as it bypasses RLS policies。5.3 输入校验与返回值使用publicProcedure/protectedProcedure时用 Zod 校验输入由于 SuperJSON 处理序列化返回普通对象/数组即可客户端通过apps/web/client/src/trpc/react.tsx使用React Query tRPC links并提供RouterInputs/RouterOutputs类型推导辅助。以 routers/user/user.ts 为例一个典型的 protected 查询与带 Zod 输入的过程长这样export const userRouter createTRPCRouter({ get: protectedProcedure.query(async ({ ctx }) { ... }), getById: protectedProcedure.input(z.string()).query(async ({ ctx, input }) { ... }), upsert: protectedProcedure .input(userInsertSchema) .mutation(async ({ ctx, input }) { ... }), });而 routers/user/user-settings.ts 则展示了 upsert 模式先查findFirst不存在则insert合并createDefaultUserSettings存在则update最后统一经过fromDbUserSettings映射器返回。实现注意routers 目录下并非每个 router 都是单个文件——例如user/、project/、domain/、publish/、subscription/、usage/均为子目录组织见 routers 目录新增 router 时需先确认是加文件还是加子目录。六、认证与 Supabase服务端/浏览器客户端的分界AGENTS.md 给出两条明确的客户端规范服务端客户端apps/web/client/src/utils/supabase/server.ts基于 Next 的 headers/cookies用于 Server Components、Server Actions 和路由浏览器客户端apps/web/client/src/utils/supabase/client/index.ts用于客户端组件绝不把服务端专用客户端传入客户端代码。查看 server.ts它通过supabase/ssr的createServerClient绑定next/headers的 cookieStoregetAll读取、setAll回写并在 Server Component 场景下静默捕获setAll异常此时依赖 middleware 刷新会话。而 trpc.ts 的上下文正是复用这个服务端客户端来完成supabase.auth.getUser()的鉴权。七、环境变量与配置t3-oss/env-nextjs统一校验7.1 规范要点所有环境变量在apps/web/client/src/env.ts中用t3-oss/env-nextjs定义并校验浏览器可见变量必须以NEXT_PUBLIC_*前缀并声明在clientschema 中优先从/env导入env服务端专用 helper如src/trpc/helpers.ts中的 base URL读取process.env仅限部署类变量如VERCEL_URL/PORT客户端代码中绝不使用process.env共享模块需用typeof window undefined守卫在apps/web/client/next.config.ts中导入./src/env以强制校验生效。7.2 源码级参数一览env.ts 将变量分为两组服务端server schemaNODE_ENV枚举校验、CSB_API_KEY、SUPABASE_DATABASE_URLURL 校验、SUPABASE_SERVICE_ROLE_KEY、可选配置包括RESEND_API_KEY邮件、FREESTYLE_API_KEY托管、Stripe 的STRIPE_WEBHOOK_SECRET/STRIPE_SECRET_KEY、AI 应用模型MORPH_API_KEY/RELACE_API_KEY、AWS Bedrock 的AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_REGION、Google Vertex AI 的GOOGLE_CLIENT_EMAIL/GOOGLE_PRIVATE_KEY/GOOGLE_PRIVATE_KEY_ID、模型提供商OPENROUTER_API_KEY必填与ANTHROPIC_API_KEY/GOOGLE_AI_STUDIO_API_KEY/OPENAI_API_KEY可选、n8n 的N8N_WEBHOOK_URL/N8N_API_KEY等、FIRECRAWL_API_KEY、EXA_API_KEY、Langfuse 的LANGFUSE_SECRET_KEY/LANGFUSE_PUBLIC_KEY/LANGFUSE_BASEURL、GitHub App 的GITHUB_APP_ID/GITHUB_APP_PRIVATE_KEY/GITHUB_APP_SLUG。客户端client schemaNEXT_PUBLIC_SITE_URL默认http://localhost:3000、NEXT_PUBLIC_SUPABASE_URL、NEXT_PUBLIC_SUPABASE_ANON_KEY以及可选的NEXT_PUBLIC_POSTHOG_KEY/NEXT_PUBLIC_POSTHOG_HOST、NEXT_PUBLIC_GLEAP_API_KEY、NEXT_PUBLIC_FEATURE_COLLABORATIONz.coerce.boolean()默认false、NEXT_PUBLIC_HOSTING_DOMAIN、NEXT_PUBLIC_RB2B_ID。此外env.ts还提供两个实用开关skipValidation: !!process.env.SKIP_ENV_VALIDATION——构建时传SKIP_ENV_VALIDATION可跳过校验便于 Docker 构建emptyStringAsUndefined: true——空字符串视为 undefined避免SOME_VAR被z.string()误判。常见坑环境变量未在src/env.ts中声明/暴露类型会导致运行时或 edge 运行时失败AGENTS.md 明确列出新增变量时应优先扩展env.ts避免在客户端代码里新增process.env读取。八、导入路径别名使用路径别名/*和~/*二者都映射到apps/web/client/src/*依据在 apps/web/client/tsconfig.json 的paths配置中paths: { /*: [./src/*], /*: [./*], ~/*: [./src/*] }禁止把服务端专用模块导入客户端组件。唯一例外是已经使用path的编辑器模块且只允许在那些区域复用任何客户端代码不得导入process若环境不同应按环境拆分代码server file vs client file。一个与“base URL 仅读部署变量”对应的实例是 apps/web/client/src/trpc/helpers.ts它用typeof window ! undefined判断浏览器环境回退到process.env.VERCEL_URL再回退到http://localhost:${process.env.PORT ?? 3000}随后用httpBatchStreamLinkloggerLink组装 tRPC links。九、MobX React Stores状态管理的正确姿势AGENTS.md 对 MobX 状态管理给出了非常具体、可操作的模式约束用useState(() new Store())创建 store 实例保证跨渲染稳定活跃 store 放在useRef路由切换时用setTimeout(() storeRef.current?.clear(), 0)做异步清理避免路由切换竞态避免用useMemo创建 store 实例——React 可能丢弃 memoized 值导致数据丢失若把 store 实例放进 effect 依赖会造成循环则拆分关注点如 project 与 branch 分开observer组件仅限客户端在 feature 入口放一个客户端边界即可子 observer 无需再加use client示例 storeapps/web/client/src/components/store/editor/engine.ts使用makeAutoObservable。查看 engine.ts 开头EditorEngine类通过makeAutoObservable实现响应式并组合了大量 ManagerBranchManager、CanvasManager、ChatManager、CodeManager、StyleManager、TextEditingManager等还提供了get activeSandbox()等派生 getter。这印证了 AGENTS.md 的指引store 是组合式引擎而非单一大类。十、样式与国际化样式Styling UITailwindCSS 优先全局样式已在apps/web/client/src/app/layout.tsx导入/styles/globals.css与onlook/ui/globals.css优先复用onlook/ui的既有组件与本地模式通过 layout 中的ThemeProvider保持暗色主题默认值forcedThemedark。国际化Internationalization已配置next-intlProvider 位于apps/web/client/src/app/layout.tsxNextIntlClientProvidergetLocale()文案放在apps/web/client/messages/*仓库内可见en.json、zh.json、es.json、ja.json、ko.json等多语言文件新增/修改 key 都在那里进行避免硬编码面向用户的文本保持 key 稳定优先“新增”而非“破坏性重命名”。从仓库看messages/下还有类型声明文件en.d.json.ts并被tsconfig.json的include引用确保多语言 key 的类型安全。十一、常见坑速查表AGENTS.md 汇总了六类高频问题均已在前面各节给出源码级解释汇总如下坑表现/后果规避方式缺少use client事件无法绑定、浏览器 API 失效在 feature 根部放一个use client边界即可新 router 未导出到root.ts端点不可达在 root.ts 手动注册环境变量未在env.ts声明类型运行时/edge 失败优先扩展 env.ts客户端代码不读process.env客户端组件导入服务端代码打包/运行时错误按环境拆分文件path仅限既有编辑器模块绕过 i18n 硬编码字符串多语言失效使用messages/*与 hooks用useMemo创建 MobX store / 路由切换同步清理store 引用丢失、竞态用useState(() new Store())useRefsetTimeout清理十二、Agent 的上下文纪律与运维命令12.1 Context Discipline上下文纪律为控制 token 消耗并保证改动精准AGENTS.md 要求 Agent用ripgrep精准搜索对应仓库内可用的search_in_files能力只打开需要的文件只读小段代码避开node_modules、.next与大型资源提出与既有约定一致的最小 diff避免大范围重构。12.2 常用命令根package.json与 AGENTS.md 共同确认的命令bun test——运行单元测试仓库内packages/*下每个包都有test/目录例如packages/utility/test/、packages/ai/test/bun run typecheck——类型检查实际映射为bun --filter onlook/web-client typecheckbun run db:push——将数据库更新应用到本地开发库内部为cd packages/db bun db:push不要运行 dev server自动化上下文中避免禁止运行db:gen——该命令仅保留给维护者除非必要不要使用任何额外类型DO NOT use any type unless necessary。十三、小结给 Agent 的落地检查单在 Onlook 仓库提交任何改动前可以对照这份清单快速自检diff 是否最小是否只动了必要文件且未触碰生成产物、锁文件、node_modules安装与脚本是否全部走bunServer Component 是否保持默认需要事件/浏览器 API 的组件是否已加use client新 tRPC router 是否已在root.ts注册是否用publicProcedure/protectedProcedure Zod 校验输入并返回可被 SuperJSON 序列化的普通对象服务端/浏览器 Supabase 客户端是否用对位置是否把服务端客户端泄漏给了客户端组件新增环境变量是否已在env.ts声明并暴露浏览器变量是否NEXT_PUBLIC_前缀导入是否走/*/~/*别名客户端代码是否未引入服务端模块与processMobX store 是否用useState创建、useRef持有、异步清理用户可见文案是否走messages/*而非硬编码是否用 ripgrep 精准搜索、只读必要文件避免了无谓的 token 开销遵循这些规则既能保证代码与 Onlook 的架构约定Next.js App Router、tRPC Zod、Supabase、MobX、TailwindCSS、next-intl保持一致也能显著提升自动化 Agent 在仓库内的工作质量与效率。如需了解运行环境的完整搭建步骤可继续阅读 docs/content/docs/developers/running-locally.mdx 与 docs/content/docs/developers/architecture.mdx。【免费下载链接】onlookThe Cursor for Designers • An Open-Source AI-First Design tool • Visually build, style, and edit your React App with AI项目地址: https://gitcode.com/GitHub_Trending/on/onlook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考