开发者文档介绍
面向 AI Agent 产品开发的全栈脚手架：从模型调用、工具编排到数据、鉴权、文档与 Cloudflare 部署。
从一句想法，到一个能工作的 Agent
你可能已经有了一个想法：让 Agent 读懂一份简历，帮用户把经历改写得更清楚；让它根据岗位要求追问，再把回答整理成下一轮面试的准备材料。真正困难的地方，通常不是写出第一条 prompt，而是把这条 prompt 变成一个可信、可保存、可恢复、能上线的产品。
AgentDevKit 就是为这段路准备的起点。它是一套基于 Next.js 的全栈脚手架，把 AI Agent 产品中反复出现的基础设施放进同一个项目：模型与流式响应、结构化输入输出、用户与会话、数据库、积分、文件、国际化、文档和多平台部署。你可以从一个页面开始，也可以直接沿着现成的边界扩展出完整的工作流。
面向 AI Agent 产品的工程底座
AgentDevKit 关注的是一条完整的产品工程链路，而不是一个孤立的聊天 Demo：营销页负责解释价值，Better Auth 负责身份与会话，AI 工作区负责完成任务，积分和订阅负责控制用量，Webhook 负责确认权益，邮件和文档负责让用户持续使用。各部分都有清晰的代码边界，便于 AI Coding 工具理解、修改和复用。
这套组织方式把重复的工程工作收进脚手架：你可以把自己的领域知识放在 Agent、工具和提示词里，把登录、支付、额度、邮件和部署等通用能力接到既有边界。做求职助手、研究助理、客服 Copilot、内容工作台或内部知识 Agent 时，可以更快从业务问题进入可运行的功能。
技术栈地图
这张地图的价值在于边界清楚：换模型时主要修改 AI provider 和模型注册；换支付服务时替换 provider 与 webhook；换部署平台时保留业务层，只调整适配器和资源绑定。详细版本和配置入口见技术栈与环境变量。
最新技术栈为什么是优势
Next.js 16 + React 19 让页面、服务端数据和 AI 交互使用同一套 TypeScript 心智模型。App Router 的布局和路由分组适合把营销页、登录页、工作区和管理页拆开，服务器组件减少不必要的客户端 JavaScript，React 19 的表单与异步能力也更适合承接流式 Agent 结果。
Vercel AI SDK 7 把模型供应商差异收进统一接口。产品可以先用成本较低的模型验证工作流，再为复杂任务切换推理模型；结构化输出和 provider registry 让结果更容易进入 Zod schema、数据库和 UI。对 AI IDE 来说，稳定、公开、示例丰富的 SDK 也意味着更高的代码生成命中率。
Tailwind CSS 4、Radix UI 和 shadcn/ui 让界面保持可修改。组件代码留在项目里，设计令牌和响应式规则清晰可见，AI 可以沿用现有组件继续生成页面，不会把产品锁在黑盒主题中。Drizzle ORM + D1/LibSQL 则把类型安全和边缘运行时结合起来，迁移文件可审阅，SQL 关系也不会被 ORM 抽象隐藏。
AI Elements 是 AgentDevKit 的 AI 专用 UI 组件层。它不是另一个封闭的 UI 框架，而是基于项目现有 shadcn/ui 约定、从 AI SDK Elements registry 引入并本地维护的可组合组件：message 负责 Markdown、中文和代码块渲染，conversation 处理流式消息与自动贴底，reasoning、tool、sources、suggestion、prompt-input 和 model-selector 分别承接推理过程、工具状态、引用来源、快捷建议、附件输入和模型切换。这样，Agent 的每个中间状态都有对应的界面，而不是等模型结束后才显示一段静态文本。
这套组件位于 src/components/ai-elements，业务功能从 src/features/chat、src/features/ai-resume 和 src/features/career 组合使用。Streamdown 的 CJK 与代码插件保证流式 Markdown 在中文和代码场景下可读，use-stick-to-bottom 让长对话在用户没有主动滚动时保持最新内容。要扩展新的 Agent 工具，通常只需增加工具状态组件和对应的消息数据映射，不必重写整个聊天工作区。更多接入细节见AI 集成。
Better Auth、Fumadocs 和 OpenNext 覆盖了“能用、能解释、能上线”的最后一公里：认证逻辑有成熟边界，文档与代码同仓库维护，Next.js 应用可以通过 OpenNext 适配到 Cloudflare Workers。最新版本的意义不只是新，而是让框架能力、AI 工具生态和部署平台保持在同一条开发路径上。
产品工程能力矩阵
支付 provider、模型权限、邮件域名和 Cloudflare 资源都需要在目标环境中自行开通并联调；仓库中的适配代码和文档提供接入路径，不代表第三方服务已经完成注册或生产验收。具体边界见支付订阅、海外登录与邮件、部署与数据边界 和上线检查。
先跑通一条真实的 Agent 路径
想象第一次启动项目的你。终端里运行 pnpm install 和 pnpm dev，浏览器打开本地应用。你看到的不是一堆孤立的示例，而是一条可以继续生长的产品路径：用户进入营销页，注册账户，打开工作区，提交资料，等待模型流式返回结果，再决定保存、修改或继续追问。
这条路径对应仓库里的真实分层：src/app/[locale] 负责 App Router 页面和语言路由，src/components 承载可复用界面，src/features 放置按业务组织的 AI、简历和面试逻辑，src/lib 连接模型、数据库、存储与第三方服务。先看本地开发，再看项目结构，你会更容易判断一次改动应该落在哪一层。
Agent 的“思考”与“动作”
AgentDevKit 的核心不是一个聊天框，而是一条可验证的 AI 管道。请求从界面进入服务层后，先通过 Zod 和业务契约校验，再由 Vercel AI SDK 统一模型调用；结果可以流式返回给 React UI，也可以按结构化 schema 解析成简历字段、面试问题或修改建议。模型供应商通过 @ai-sdk/anthropic、@ai-sdk/google 和 OpenAI-compatible provider 接入，具体模型由运行环境配置决定。
这样做的好处，是把“模型会说什么”和“产品允许保存什么”分开。Agent 可以提出建议，但业务层仍然决定哪些字段可写入、一次操作消耗多少额度、用户是否需要确认。阅读 AI 架构总览、模型接入 和提示词，可以看到从请求、验证到持久化的完整路径。
让每个结论都有来处
一个真正有用的求职 Agent，不应该凭空编造经历。它需要把岗位要求、用户提供的事实和生成结果放在同一张桌面上：先读取 PDF、DOCX、TXT 或 Markdown，提取可以核对的证据；再把职位描述拆成技能、职责和成果；最后给出改写草稿，并标记修改原因，让用户逐条确认。
仓库中的 AI 简历工作区和面试工作区正沿着这个方向组织：输入可以保存，任务可以恢复，回答之后才会产生反馈，用户也始终能回到原始事实。这里的“Agent”不是替用户做决定，而是把复杂的整理工作拆成一连串可检查的步骤。相关实现入口见简历数据与编辑、编辑器改写 和求职工作流。
记住用户，也记住边界
当一次生成结果值得保留时，它需要进入可靠的数据层，而不是停留在浏览器的临时状态。AgentDevKit 使用 Drizzle ORM 描述 schema 和迁移，兼容 SQLite、LibSQL 与 Cloudflare D1；使用 Better Auth 管理账户、会话和登录；用 next-safe-action、Zod 与业务服务把输入校验放在服务器边界。
这让“暂停后继续”与“重新生成”有了清晰的归属：数据库保存事实、草稿和操作状态，AI 服务只负责一次明确的生成任务，额度服务记录消耗。你可以从数据库与迁移、认证 和API 分层 开始，理解这些边界如何协作。
让 Agent 有一个可读的家
Agent 产品的体验不只发生在对话窗口。用户需要看见进度、理解工具正在做什么、比较修改前后的文本，也需要在移动端继续工作。界面基于 React 19、Tailwind CSS 4、Radix UI primitives 和 shadcn/ui 组织，表单使用 React Hook Form，局部状态使用 Zustand；AI 对话与流式内容使用 Vercel AI SDK React hooks、AI Elements 和 Streamdown。
开发者也需要同样清晰的说明。当前项目文档由 Fumadocs、Fumadocs MDX 和本地内容源驱动，src/content/project 里的每篇文章都对应一个可追溯的实现入口。先读这篇总览，再按任务进入快速开始、技术栈 或项目架构，比从目录里猜文件更快。
从本地原型走到边缘部署
Agent 的第一次回答可以在本地完成，但产品最终要面对真实的并发、文件和成本。AgentDevKit 以 Next.js 16 App Router 为应用骨架，通过 OpenNext Cloudflare 适配器构建到 Workers；D1 保存关系数据，R2 负责对象存储，KV 可用于缓存与轻量状态。OpenNext 的 Cloudflare 文档说明现有 Next.js 应用可以通过适配器部署，并使用 Workers 提供的 Node.js API；项目里的 opennextjs:build、preview 和 deploy 脚本把这条路径固定下来。
部署前先读环境变量 和Cloudflare 部署，再按质量检查 验证类型、迁移、存储边界和构建产物。这样你交付的不是“在我的电脑上能聊天”的演示，而是一条能被复现、能被维护的发布流程。
你接下来要走哪一段？
写给正在动手的你
脚手架的价值，不是替你决定 Agent 应该成为什么，而是让你把时间花在那些真正有差异的地方：任务如何拆解，工具如何授权，结果如何被人确认，失败时如何恢复。AgentDevKit 把重复的工程问题摆在可见的位置，也把修改入口留在你的代码里。
当你准备好时，从一条最小的用户任务开始：输入一段真实材料，完成一次可解释的生成，保存一个用户愿意继续修改的结果。 然后沿着本指南的链接，逐步把它变成一个可靠的 Agent 产品。