从自然语言需求到全栈应用AG Kit App Builder 多智能体编排机制解析【免费下载链接】ag-kit项目地址: https://gitcode.com/GitHub_Trending/an/ag-kitApp Builder.agents/skills/app-builder/SKILL.md是 AG Kit 中负责从零构建全栈应用的核心编排技能它接收一段自然语言描述判定项目类型、选定技术栈、规划目录结构再调度project-planner、database-architect、backend-specialist、frontend-specialist、devops-engineer等专职 Agent 协同产出可运行的应用。读完本文你将掌握这套技能的内容地图、项目识别规则、2026 技术栈默认值与备选方案、13 套项目模板、多智能体流水线的执行顺序与强制门禁以及既有项目功能迭代的完整方法论。一、App Builder 是什么一次请求驱动的应用编排器打开 SKILL.md 的 Frontmatter可以看到这个技能在 AG Kit 中的正式定义name: app-builder description: Main application building orchestrator. Creates full-stack applications from natural language requests. Determines project type, selects tech stack, coordinates agents. when_to_use: When creating a new full-stack application from scratch, selecting tech stack, or scaffolding project structure. Use with /create workflow. allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Agent version: 1.1.0几个字段直接决定了它的工作边界description明确它是主应用构建编排器职责是从自然语言请求创建全栈应用、确定项目类型、选择技术栈、协调多个 Agent——它自己并不直接写完所有代码而是负责决策与调度。when_to_use触发条件是从零创建全栈应用、选择技术栈、搭建项目结构并且与/create工作流绑定使用。allowed-tools除了读写、搜索、执行命令外还允许调用Agent工具——这是它能编排其他专职 Agent 的权限基础。version采用 SemVer 严格版本管理AG Kit 中所有 skill/agent/workflow 的 Frontmatter 均要求 SemVer见 ARCHITECTURE.md。与 /create 工作流的绑定关系when_to_use中提到的/create工作流定义在 .agents/workflows/create.md。该工作流明确声明requires_skills: app-builder, design-spec, verify-changes其执行步骤正是 App Builder 方法论的外层包装请求分析理解用户需求信息缺失时用brainstorming技能追问澄清项目规划由project-planner拆解任务、确定技术栈、规划文件结构并在项目根目录生成{task-slug}.md计划文件设计真相源仅 UI 项目先按design-spec技能在根目录创建DESIGN.md再开始写 UI应用构建用app-builder技能编排database-architectSchema、backend-specialistAPI、frontend-specialistUI严格对齐DESIGN.md中的 token预览通过 auto_preview.py 启动本地预览并把 URL 交给用户。在 AG Kit 的 47 个技能中App Builder 被归入架构与规划类是唯一带 20 个关联文件的增强型技能含 13 套模板与 5 份方法论文档这也说明了它在整个工具链中的枢纽地位。二、选择性读取规则按需加载的内容地图App Builder 目录下包含多份说明文档与模板如果全部加载会消耗大量上下文。因此 SKILL.md 开篇就立下选择性读取规则只读取与当前请求相关的文件先查内容地图再决定读什么。文件说明何时读取project-detection.md关键词矩阵、项目类型判定开启新项目时tech-stack.md2026 默认技术栈与备选方案选择技术栈时agent-coordination.mdAgent 流水线、执行顺序协调多 Agent 工作时scaffolding.md目录结构、核心文件创建项目结构时feature-building.md特性分析、错误处理为既有项目添加功能时templates/SKILL.md13 套项目模板脚手架搭建时这套先看目录、按需读取的设计与 AG Kit 的条件化技能加载协议一脉相承。据 ARCHITECTURE.md每个技能都要求提供when_to_useFrontmatter加载流程为User Request → Check when_to_use frontmatter → Match? → Load full SKILL.md ↓ No match Skip (save tokens)也就是说App Builder 的选择性读取规则是 AG Kit 全局 token 效率策略在单一技能内部的落地请求命中哪个阶段就只加载那一份文档。三、第一步项目类型识别project-detection.md构建应用的第一步是把自然语言请求映射为具体的项目类型。project-detection.md提供了一张关键词矩阵覆盖 16 类常见项目关键词项目类型模板blog, post, articleBlogastro-statice-commerce, product, cart, paymentE-commercenextjs-saasdashboard, panel, managementAdmin Dashboardnextjs-fullstackai, chat, bot, llm, rag, agent appAI / Chatbot Appnextjs-fullstackAI SDK / Streaminggame, 2d, 3d, canvas, phaser, godotGame Applicationgame-development skill经game-developerapi, backend, service, restAPI Serviceexpress-apipython, fastapi, djangoPython APIpython-fastapimobile, android, ios, react nativeMobile App (RN)react-native-appflutter, dartMobile App (Flutter)flutter-appportfolio, personal, cvPortfolionextjs-staticcrm, customer, salesCRMnextjs-fullstacksaas, subscription, stripeSaaSnextjs-saaslanding, promotional, marketingLanding Pagenextjs-staticdocs, documentationDocumentationastro-staticextension, plugin, chromeBrowser Extensionchrome-extensiondesktop, electronDesktop Appelectron-desktopcli, command line, terminalCLI Toolcli-toolmonorepo, workspaceMonorepomonorepo-turborepo检测流程识别过程本身是一个流水线1. Tokenize user request # 对请求做分词 2. Extract keywords # 提取关键词 3. Determine project type # 判定项目类型 4. Detect missing information → forward to project-planner / orchestrator # 信息缺失时转交规划/编排 Agent 追问 5. Suggest tech stack # 给出技术栈建议值得注意游戏类请求并不直接映射到某个模板而是路由到game-development技能并经由game-developerAgent 处理说明 App Builder 的识别结果也可以指向另一个技能 专职 Agent而非模板。冲突消解多条关键词同时命中时怎么办真实需求常同时命中多个关键词例如 a CLI to manage my e-commerce products 同时含cli与e-commerce。文档定义了三条按优先级执行的消解规则优先级规则示例1平台优先于业务域具体的平台形态mobile / desktop / cli / extension优先于 Web/业务域e-commerce、crm、blogCLI to manage e-commerce →cli-toole-commerce 只是数据域不是交付物2中心名词优先描述要构建什么的语法主语优先于修饰语adashboardfor my Shopify store →nextjs-fullstackdashboard 才是主体Shopify 只是背景3仍有歧义就询问规则无法消解时绝不猜通过 Socratic GatePhase 0把选项抛给用户选择an app for my shop → 询问Web、移动端还是桌面端第 3 条规则的背后是 Socratic Gate 机制见下文执行顺序表 Phase 0即构建前最多问 3 个澄清问题用最小交互成本换取需求确定性。四、第二步技术栈选择tech-stack.md项目类型确定后tech-stack.md给出 Web 应用在 2026 年的默认技术栈YAML 配置Frontend: framework: Next.js 16 (Stable) language: TypeScript 5.7 styling: Tailwind CSS v4 state: React 19 Actions / Server Components caching: Next.js 16 Cache Components (Stable) bundler: Turbopack (Stable for Dev Build) Backend: runtime: Node.js 24 (Krypton LTS) framework: Next.js API Routes / Hono (for Edge) validation: Zod / TypeBox Database: primary: PostgreSQL orm: Prisma / Drizzle hosting: Supabase / Neon Auth: provider: Auth.js (v5) / Clerk Monorepo: tool: Turborepo 2.0备选方案对照表当默认方案不满足特定需求时按需替换对应组件需求默认备选实时能力Supabase RealtimeSocket.io, Ably文件存储Supabase StorageCloudinary, AWS S3支付StripeLemonSqueezy, Paddle邮件ResendSendGrid, Postmark搜索AlgoliaTypesense, OramaAI / LLM SDKVercel AI SDKaiai-sdk/*LangChain.js、直接调用 REST API向量数据库PostgreSQL经 Supabase / Neon 启用 pgvectorPinecone, QdrantORMSQL 优先Prisma ORMDrizzle ORMdrizzle-ormdrizzle-kitAI 应用构建模式2026 标准对于 AI / LLM 驱动的应用文档给出了四条落地准则流式输出在 Route Handlers 或 Server Actions 中使用 Vercel AI SDK 的streamText/streamUIUI 状态用useChat/useCompletion配合 React 19 的乐观更新optimistic updates管理聊天 UIEmbeddings 与向量检索向量存入 PostgreSQL 的pgvector扩展用余弦相似度查询安全与限流AI 端点必须做速率限制参照 api-patterns/rate-limiting.md并用 Zod schema 做输入解析。这一模式同样体现在关键词矩阵中AI/Chatbot 类项目默认落在nextjs-fullstack模板上并按上述标准叠加 AI SDK 与流式能力。五、13 套项目模板不同技术栈的快速脚手架App Builder 内置13 套项目模板每套对应一种技术栈与典型场景。SKILL.md 明确要求只读取与用户项目匹配的那一套模板的加载同样走 templates/SKILL.md 的选择性读取规则。模板技术栈适用场景nextjs-fullstackNext.js Prisma全栈 Web 应用nextjs-saasNext.js StripeSaaS 产品nextjs-staticNext.js Framer落地页nuxt-appNuxt 4 PiniaVue 全栈应用express-apiExpress JWTREST APIpython-fastapiFastAPIPython APIreact-native-appExpo Zustand移动应用flutter-appFlutter Riverpod跨平台移动应用electron-desktopElectron React桌面应用chrome-extensionChrome MV3浏览器扩展cli-toolNode.js CommanderCLI 应用monorepo-turborepoTurborepo pnpmMonorepoastro-staticAstro MDX博客 / 文档站模板的使用流程源自 templates/SKILL.md1. User says create [type] app 2. Match to appropriate template 3. Read ONLY that templates TEMPLATE.md 4. Follow its tech stack and structure代表性模板详解nextjs-fullstack2026 版以最常用的 nextjs-fullstack/TEMPLATE.md 为例其技术栈为 Next.js v16App Router、Turbopack Node.js 24Krypton LTS TypeScript 5Strict Mode PostgreSQLPrisma ORM Tailwind CSS v4.0零配置、CSS-first Auth.js v5 / Clerk React 19Server Actions、useActionState Zod。核心概念强调Server Components默认服务端渲染可直接用 Prisma 访问数据库无需额外 API 层Server Actions处理表单变更取代传统 API Routes挂在action{}上React 19 HooksuseActionState、useFormStatus、useOptimistic管理表单状态Data Access Layer把 DB 逻辑封装成 DTO 以安全复用Tailwind v4不再有tailwind.config.js配置直接写在 CSS 里。环境变量方面模板要求至少配置DATABASE_URLPostgreSQL 连接串、NEXT_PUBLIC_APP_URL应用公开 URL、AUTH_SECRETAuth.js v5 会话密钥若改用 Clerk 则换成NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY与CLERK_SECRET_KEY。脚手架命令npx create-next-applatest my-app --typescript --tailwind --eslint # 选择 Yes 启用 App Routersrc 目录按模板约定选择 Yes npm install prisma prisma/client zod npm install -D ts-node # 运行 seed 脚本 npx prisma init # 初始化数据库更新 schema.prisma npm run db:push npm run dev --turbo # --turbo 启用更快的 TurbopackTailwind v4 的 CSS 配置直接写入src/app/globals.cssimport tailwindcss; theme { --color-primary: oklch(0.5 0.2 240); --font-sans: Inter, sans-serif; }代表性模板详解nextjs-saasnextjs-saas/TEMPLATE.md 面向商业化产品在 fullstack 基础上叠加 Stripe 支付与 Resend 事务邮件。目录结构新增src/actions/auth-actions.ts、billing-actions.ts、user-actions.ts、src/lib/stripe.tsStripe 单例、src/components/emails/React Email 模板。SaaS 功能映射功能实现认证Auth.js v5 Passkeys OAuth数据变更Server Actions不再用 API Routes订阅Stripe Checkout 与 Customer PortalWebhooks异步 Stripe 事件处理邮件经 Resend 发送事务邮件校验Zod服务端校验数据库核心模型为User含stripeCustomerId、subscriptionId、plan、AccountGoogle/GitHub 等 OAuth 数据、Session数据库策略会话。环境变量比 fullstack 版多出STRIPE_SECRET_KEY、STRIPE_WEBHOOK_SECRET、RESEND_API_KEY。本地联调时用npm run stripe:listen监听 Webhook。代表性模板详解express-api 与 python-fastapiexpress-api/TEMPLATE.md 面向纯 REST APIExpress 5 TypeScript PostgreSQL/Prisma Zod JWT/bcrypt。它特别强调分层架构routes → controllers → services与可测试性拆分——app.ts只做中间件装配不listenserver.ts负责启动这样应用可以被测试直接 import。中间件栈顺序固定为 helmet → cors → compression → body parsing → morgan → routes → 错误处理最后注册4 参数签名。API 响应格式统一为成功{ success: true, data: {...} }、失败{ error: message, details: [...] }。python-fastapi/TEMPLATE.md 则采用 Python 3.12 / FastAPI / SQLAlchemy 2.0async/ Pydantic v2 / Alembic / JWTpasslib并推荐按业务域domain而非按文件类型组织目录每个域自持router.py、schemas.py、models.py、service.py、dependencies.py、exceptions.py。启动步骤为uvicorn src.main:app --reload。六、第三步脚手架结构规划scaffolding.md模板选定后scaffolding.md提供 Next.js 16 优化版的标准目录结构作为全栈项目的骨架蓝图project-name/ ├── src/ │ ├── app/ # 仅放路由薄层 │ │ ├── layout.tsx │ │ ├── page.tsx │ │ ├── globals.css # Tailwind v4 配置theme写在这里 │ │ ├── (auth)/ # 路由组 - 认证页面 │ │ │ ├── login/page.tsx │ │ │ └── register/page.tsx │ │ ├── (dashboard)/ # 路由组 - 仪表盘布局 │ │ │ ├── layout.tsx │ │ │ └── page.tsx │ │ └── api/ # Route Handlers仅 webhook/外部集成 │ │ └── [resource]/route.ts │ │ │ ├── components/ # UI 组件 │ │ ├── ui/ # 可复用原语Button, Input │ │ └── forms/ # 客户端表单useActionState │ │ │ ├── lib/ # 共享工具与服务端专属逻辑 │ │ ├── db.ts # Prisma 单例客户端 │ │ ├── dal.ts # 数据访问层server-only, DTOs │ │ └── utils.ts # 辅助函数 │ │ │ ├── actions/ # Server Actions变更操作 │ │ │ └── types/ # 全局 TypeScript 类型 │ ├── prisma/ │ ├── schema.prisma │ ├── migrations/ │ └── seed.ts │ ├── public/ ├── proxy.ts # 网络边界认证、重定向 ├── DESIGN.md # 设计真相源token 与理由UI 项目强制 ├── .env.example ├── .env.local ├── package.json ├── next.config.ts ├── tsconfig.json └── README.md结构原则与文件职责原则落地方式薄路由app/只负责路由与布局逻辑放在actions/和lib/服务端/客户端分离服务端专属逻辑放lib/dal.ts防止被客户端意外 import数据访问层lib/dal.ts集中数据库访问并返回 DTO 以安全复用变更走 Server Actionsactions/存放 Server Actions表单用useActionState调用路由组(groupName)/共享布局且不影响 URL可复用 UIcomponents/ui/放原语components/forms/放客户端表单关键文件定位proxy.ts是 Next.js 16 的网络边界逻辑认证、重定向由middleware.ts更名而来跑在 Node.js 运行时DESIGN.md是视觉 tokenYAML frontmatter与设计理由的唯一真相源UI 开发前必须存在src/app/globals.css承载 Tailwind v4 的theme配置不再需要tailwind.config.js。路径别名与何时放哪tsconfig.json中建议统一路径别名{ compilerOptions: { paths: { /*: [./src/*], /components/*: [./src/components/*], /lib/*: [./src/lib/*], /actions/*: [./src/actions/*] } } }该把代码放哪的速查表需求位置新页面/路由app/(group)/page.tsx可复用按钮/输入框components/ui/客户端表单components/forms/Server Action变更actions/数据获取 / DB 查询lib/dal.tsPrisma 客户端lib/db.ts辅助函数lib/utils.ts认证 / 重定向逻辑proxy.ts七、多智能体协作流水线agent-coordination.md项目类型、技术栈、目录结构齐备之后真正编写应用的工作由专职 Agent 承担App Builder 作为编排器把控节奏。agent-coordination.md给出了完整的流水线视图┌─────────────────────────────────────────────────────────────┐ │ APP BUILDER (Orchestrator) │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ PROJECT PLANNER │ │ • Task breakdown / Dependency graph / File structure │ │ • Create {task-slug}.md in project root (MANDATORY) │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ CHECKPOINT: PLAN VERIFICATION │ │ VERIFY: Does {task-slug}.md exist in project root? │ │ If NO → STOP → Create plan file first │ │ If YES → Proceed to specialist agents │ └─────────────────────────────────────────────────────────────┘ │ ┌───────────────────┼───────────────────┐ ▼ ▼ ▼ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ DATABASE │ │ BACKEND │ │ DESIGN SOURCE │ │ ARCHITECT │ │ SPECIALIST │ │ OF TRUTH │ │ • Schema design │ │ • API routes │ │ • Read design- │ │ • Migrations │ │ • Controllers │ │ spec refs │ │ • Seed data │ │ • Middleware │ │ • Create │ │ │ │ │ │ DESIGN.md │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ ▼ │ │ ┌─────────────────┐ │ │ │ FRONTEND │ │ │ │ SPECIALIST │ │ │ │ • UI Components │ │ │ │ • Pages │ │ │ │ • Strict tokens │ └───────────────────┼───────────────────┘ ▼ ┌─────────────────────────────────────────────────────────────┐ │ PARALLEL PHASE (Optional) │ │ • Security Auditor → Vulnerability check │ │ • Test Engineer → Unit tests │ │ • Performance Optimizer → Bundle analysis │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ DEVOPS ENGINEER │ │ • Environment setup │ │ • Preview deployment (python .agents/scripts/auto_preview.py)│ │ • Health check report URL │ └─────────────────────────────────────────────────────────────┘执行顺序总表阶段Agent / 步骤可并行前置条件检查点0Socratic Gate❌-✅ 问 3 个问题1Project Planner❌问题已答✅ 创建{task-slug}.md1.5计划验证❌{task-slug}.md存在✅ 文件位于项目根目录1.8设计真相源❌计划已验证UI 项目✅ 根目录创建DESIGN.md2Database Architect❌计划就绪Schema 已定义3Backend Specialist❌Schema 就绪API 路由已创建4Frontend Specialist✅DESIGN.md API 就绪部分UI 组件与 token 一致5Security Auditor, Test Engineer✅代码就绪测试与审计通过6DevOps Engineer❌全部代码就绪部署与预览就绪两道强制门禁MANDATORY Gates流水线中有两个被文档标记为 CRITICAL 的关卡Phase 1.5计划验证任何专职 Agent 都不得在{task-slug}.md未经验证前开工——没有计划文件就立刻停止先补计划。Phase 1.8设计真相源凡带 UI 的项目Web、移动、桌面根目录必须先存在DESIGN.md才能写 UI 组件或页面依据 rules/design-rules.md 与 design-spec仅无头 API 或 CLI 工具可以跳过。这两道门禁与/create工作流中先计划、后设计、再构建的顺序完全一致其目的是把想清楚再动手固化成不可跳过的工程约束。关联的专职 AgentSKILL.md 在 Related Agents 一节列出了协作对象及职责Agent角色project-planner任务拆解、依赖图frontend-specialistUI 组件、页面backend-specialistAPI、业务逻辑database-architectSchema、迁移devops-engineer部署、预览在 ARCHITECTURE.md 的 20 个 Agent 清单中这些角色分别挂载了对应技能如frontend-specialist使用frontend-design、nextjs-react-expert、tailwind-patternsbackend-specialist使用api-patterns、nodejs-best-practices、database-designdatabase-architect使用database-design。八、既有项目的功能迭代feature-building.mdApp Builder 不只服务从零创建同样指导既有项目的新功能开发。feature-building.md以添加支付系统为例演示了特性分析方法Request: add payment system Analysis: ├── Required Changes: │ ├── Database: orders, payments tables │ ├── Backend: /api/checkout, /api/webhooks/stripe │ ├── Frontend: CheckoutForm, PaymentSuccess │ └── Config: Stripe API keys │ ├── Dependencies: │ ├── stripe package │ └── Existing user authentication │ └── Scope: DB 2 API routes 2 components config迭代增强流程1. Analyze existing project architecture # 先分析既有项目与架构 2. Create change plan ({task-slug}.md) # 创建变更计划 3. If UI modified/added: check align with DESIGN.md # 改 UI 先对齐设计真相源 4. Present plan to user get approval # 向用户展示计划并获批 5. Apply changes with specialist agents # 由专职 Agent 落地 6. Test validate (lint, typecheck, unit tests) # 测试与校验 7. Start preview (python .agents/scripts/auto_preview.py) # 启动预览可见迭代开发同样复用流水线核心要素变更也要先有计划文件、涉及 UI 就要对齐DESIGN.md、完成后统一走预览。错误处理与恢复策略错误类型解决策略TypeScript 错误修复类型、补缺失 import依赖缺失执行npm install端口冲突建议更换端口数据库错误检查迁移、验证连接恢复策略是一个降级链1. Detect error # 检测到错误 2. Try automatic fix # 先尝试自动修复 3. If failed, report to user # 失败则上报用户 4. Suggest alternative # 给出备选方案 5. Rollback if necessary # 必要时回滚九、端到端示例从需求到预览SKILL.md 用一个 Instagram 克隆示例把整条链路串了起来这也是when_to_use中从自然语言到全栈应用的直观演示User: Make an Instagram clone with photo sharing and likes App Builder Process: 1. Project type: Social Media App 2. Tech stack: Next.js Prisma Cloudinary Clerk 3. Create plan: ├─ Database schema (users, posts, likes, follows) ├─ API routes (auth, posts, likes, follows) ├─ Pages (feed, profile, upload) └─ Components (PostCard, Feed, LikeButton) 4. Coordinate agents 5. Report progress 6. Start preview对应到前文的方法论这条链路可以完整拆解为类型识别关键词photo sharing、likes命中社交类项目映射为全栈应用技术栈选择按tech-stack.md默认值选定 Next.js Prisma叠加 Cloudinary图片存储替代默认 Supabase Storage与 Clerk认证替代默认 Auth.js计划编制project-planner产出数据库 Schemausers/posts/likes/follows、API 路由、页面与组件清单写入{task-slug}.mdPhase 1.5 门禁设计真相源UI 项目先建根目录DESIGN.mdPhase 1.8 门禁专职 Agent 协作database-architect→backend-specialist→frontend-specialist依次/并行推进收尾报告进度由devops-engineer经python .agents/scripts/auto_preview.py启动预览。十、在 AG Kit 中的落地与验证App Builder 不是孤立文档而是 AG Kit 组件注册表中的受管技能。据 ARCHITECTURE.md技能的 Frontmattername、description、when_to_use、allowed-tools由manifest.json记录manifest.lock.json以 SHA-256 锁定完整性任何对.agents/的受管修改都必须重新生成注册表否则校验失败python .agents/scripts/generate_manifest.py --check python .agents/scripts/dependency_graph.py --check python .agents/scripts/validate_kit.py与app-builder配套的/create、/plan、/preview、/verify等工作流可以在 AG Kit 中通过斜杠命令直接调用。使用 App Builder 的完整姿势在实际项目中使用时建议按如下方式操作输入/create 需求描述触发创建流程create.md例如/create e-commerce app with product listing and cart让 App Builder 依据关键词矩阵与冲突消解规则确定项目类型与技术栈确认{task-slug}.md计划与UI 项目DESIGN.md落地再允许专职 Agent 开工功能完成后运行校验与预览python .agents/scripts/checklist.py .、python .agents/scripts/verify_all.py . --url http://localhost:3000、python .agents/scripts/auto_preview.py。这套机制的价值在于把需求理解 → 技术选型 → 结构规划 → 多智能体协作 → 质量校验固化成可复现的工程流水线让每个从自然语言出发的应用构建请求都有章可循、有门禁可守、有模板可依。【免费下载链接】ag-kit项目地址: https://gitcode.com/GitHub_Trending/an/ag-kit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
