AG Kit/create命令全解析从一句话需求到可运行应用的 Agent 工作流【免费下载链接】ag-kit项目地址: https://gitcode.com/GitHub_Trending/an/ag-kit本文以 AG Kit 的 .agents/workflows/create.md 为核心系统讲解/create命令如何把一句自然语言需求转化为完整应用从需求澄清、任务规划、DESIGN.md设计源到多智能体协同构建与本地预览的完整流水线。读完本文你将掌握 AG Kit 中创建新应用的标准工作流、每一步的触发机制与产物规范并能结合实际源码理解其底层实现。一、/create是什么一个命令一条应用生产流水线在 AG Kit 中/create是一个入口级工作流命令workflow command用于启动新的应用创建流程。它的定义位于 .agents/workflows/create.md文件头部的 YAML Front Matter 直接声明了这个命令的契约--- name: create description: Create new application command. Triggers App Builder skill and starts interactive dialogue with user. version: 1.0.0 requires_agents: orchestrator, project-planner requires_skills: app-builder, design-spec, verify-changes artifact_outputs: implementation-plan, changed-files, verification-report ---这四行元信息值得逐项拆解它们决定了命令运行时 AG Kit 会拉起哪些能力字段值含义requires_agentsorchestrator, project-planner命令必须依赖编排者与项目规划两个 Agent 协同工作requires_skillsapp-builder, design-spec, verify-changes需要应用构建、设计规格、变更验证三项技能的支撑artifact_outputsimplementation-plan, changed-files, verification-report命令结束时应产出三类产物实现计划、变更文件清单、验证报告也就是说/create并不仅仅是写代码而是一条覆盖需求 → 计划 → 设计 → 构建 → 预览 → 验证六阶段的完整生产流水线。命令体中的$ARGUMENTS占位符意味着用户在输入/create后直接附上的自然语言描述例如/create blog site会被注入此处成为后续所有步骤的输入。二、Step 1需求分析 —— 信息不足时先问不猜/create的第一步是理解用户到底想要什么。文档中明确给出规则Request AnalysisUnderstand what the user wantsIf information is missing, use thebrainstormingskill to ask clarifying questions当需求信息不完整时AG Kit 会触发 brainstorming 技能其核心是一套强制的Socratic Gate苏格拉底式提问门禁STOP—— 不要立刻开始写代码CHECK—— 先检查.agents/memory/中是否已有关于该主题的历史决策避免重复提问ASK—— 最少提出 3 个问题已被记忆回答过的问题可以跳过WAIT—— 等待用户回复后再继续SAVE—— 澄清完成后通过/remember保存关键决策。create.md 在 Before Starting 一节给出了默认的提问清单可作为起始模板What type of application?什么类型的应用What are the basic features?基本功能有哪些Who will use it?目标用户是谁同时强调Use defaults, add details later先用默认值细节后续再补——这保证了流程不会被无限澄清拖死而是通过渐进式细化推进。三、Step 2项目规划 —— 生成{task-slug}.md计划文件需求确认后/create进入规划阶段由project-plannerAgent 负责见 .agents/agent/project-planner.mdProject PlanningUseproject-planneragent for task breakdownDetermine tech stackPlan file structureCreate the{task-slug}.mdplan file in the project root, then proceed to building规划阶段的产物是位于项目根目录的动态命名计划文件{task-slug}.md。注意它不是固定名plan.md而是从用户需求中提取 23 个关键词、转成小写 kebab-case 短横线命名的 slug最长 30 字符。例如用户请求计划文件名e-commerce site with cartecommerce-cart.mdadd dark mode featuredark-mode.mdfix login buglogin-fix.md规划阶段有一条绝对红线PLAN MODE 下禁止写任何代码ABSOLUTE BAN。规划期间只允许写{task-slug}.md这一个文件禁止创建.ts/.js/.vue组件、禁止实现功能、禁止执行代码。这一约束从机制上把想清楚和写出来两个阶段严格分离避免边想边写导致的返工。project-planner还定义了 4 阶段工作流BMAD 风格/create的规划步骤正对应其中间两个阶段阶段名称焦点产物是否写代码1ANALYSIS调研、头脑风暴、探索决策记录❌2PLANNING创建计划根目录{task-slug}.md❌3SOLUTIONING架构与设计设计文档❌4IMPLEMENTATION按计划编码可运行代码✅计划的必备章节包括Overview是什么与为什么、Project TypeWEB/MOBILE/BACKEND 显式声明、Success Criteria可度量结果、Tech Stack技术选型及理由、File Structure目录布局、Task Breakdown任务拆解、Phase X最终验证清单。规划完成后还有一道EXIT GATE退出门禁必须确认计划文件已写入根目录、可读回内容、所有必需章节齐全才能退出规划阶段进入下一步。四、Step 3设计源仅 UI 项目—— 先有DESIGN.md再写界面/create对带 UI 的应用有一条硬性要求在开始构建 UI 之前必须在项目根目录创建DESIGN.mdDesign Source-of-Truth (UI projects only)If the app has a UI, createDESIGN.mdat the project root BEFORE building UI — follow thedesign-specskill (readcollection.mdfor real-world references first).Skip only for headless/CLI/API-only projects.这条规则由 design-spec 技能定义它把DESIGN.md定位为项目视觉语言的唯一事实来源single source of truth是 UI 工作的硬门禁写组件、页面、样式之前必须先存在DESIGN.md已存在则先读再遵循。DESIGN.md采用双层结构机器可读的 YAML Front Matter 设计令牌design tokens 人类可读的 Markdown 说明正文。其令牌 Schema 核心如下version: alpha # 可选 name: Daylight Prestige colors: token-name: #RRGGBB typography: token-name: fontFamily: Public Sans fontSize: 48px fontWeight: 600 lineHeight: 1.1 letterSpacing: -0.02em rounded: scale: 8px spacing: scale: 16px components: component-name: backgroundColor: {colors.primary} rounded: {rounded.md} padding: 12px这里体现了三个关键设计令牌引用系统{colors.primary}这种花括号语法允许组件令牌引用颜色、间距等基础令牌且组件内允许引用复合值如{typography.label-md}形成层级化的设计系统类型系统颜色为# hexsRGB尺寸为数值 单位px/em/rem字重可用裸数字行高推荐无单位的倍数规范化的正文章节顺序Overview → Colors → Typography → Layout → Elevation Depth → Shapes → Components → Dos and Donts且允许省略无关章节、允许扩展未知章节但重复章节标题会被拒绝。design-spec还要求在实际编写前先阅读collection.md70 个真实世界的 DESIGN.md 参考库找到与需求气质最接近的 12 个案例研读其令牌组织方式再借鉴而非照抄。作为仓库内的真实范例web/DESIGN.md 就是 AG Kit 官网自己的一份DESIGN.md——它定义了primary: #18181B、brand: #2DD4BF等颜色令牌body-md等排版令牌以及 dark 模式的完整令牌族展示了该格式在实际项目中的落地形态。无 UI 的纯后端 / CLI / API 项目可以跳过本步骤这也印证了文档中 Skip only for headless/CLI/API-only projects 的取舍逻辑。五、Step 4应用构建审批后—— 多 Agent 协同装配计划与设计就绪后/create进入构建阶段。文档明确了编排方式与分工Application Building (After Approval)Orchestrate withapp-builderskillCoordinate expert agents:database-architect→ Schemabackend-specialist→ APIfrontend-specialist→ UI (builds againstDESIGN.mdtokens)构建的编排者是 app-builder 技能其自我定位是 Main application building orchestrator负责判断项目类型、选择技术栈、协调各专家 Agent。它内置了一份选择性阅读地图只按需读取相关子文档子文档用途何时读取project-detection.md关键词矩阵、项目类型识别启动新项目时tech-stack.md默认技术栈与替代方案选型时agent-coordination.mdAgent 流水线与执行顺序协调多 Agent 时scaffolding.md目录结构与核心文件创建项目结构时feature-building.md功能分析与错误处理给既有项目加功能时templates/SKILL.md项目模板脚手架新项目时关键设计只读与需求相关的文件。这一选择性阅读规则Selective Reading Rule避免了 Agent 在 13 套模板中被无关内容淹没直接提升 token 利用效率。专家 Agent 的分工遵循严格边界见 project-planner 中的 Agent 选择规则Web 应用→frontend-specialist禁用mobile-developer移动应用→mobile-developer禁用frontend-specialist纯 API 项目→ 只用backend-specialist不用前端、不用移动端。构建优先级Implementation Priority Order为P0 基础层database-architect→security-auditor需要数据库时→P1 核心层backend-specialist有后端时→P2 UI 层frontend-specialist或mobile-developer二选一→P3 打磨层test-engineer、performance-optimizer、seo-specialist按需。app-builder还内置了13 套项目模板见 .agents/skills/app-builder/templates/覆盖了从 Web 到移动端、从桌面到 CLI 的主流形态模板技术栈适用场景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博客 / 文档站app-builder的 Usage Example 演示了这条流水线如何把一句话需求翻译成可执行计划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注意文档措辞中的After Approval审批后构建不是自动全速进行的而是穿插了用户审批关卡——与规划阶段的 EXIT GATE 一起构成关键节点必停、请示后继续的流程节奏。六、Step 5预览 —— 一条命令拉起本地服务器构建完成后/create自动进入预览环节PreviewStart withauto_preview.pywhen completePresent URL to user预览由 .agents/scripts/auto_preview.py 脚本承载它管理本地开发服务器的启动、停止与状态查询python .agents/scripts/auto_preview.py start [port] # 启动预览默认端口 3000 python .agents/scripts/auto_preview.py stop # 停止预览 python .agents/scripts/auto_preview.py status # 查询预览状态从脚本源码看其工作逻辑非常务实get_start_command()读取项目根目录package.json的scripts字段优先使用npm run dev否则回退到npm start若两者都没有则报错退出start_server()通过环境变量注入PORT使用subprocess.Popen后台拉起服务并将 PID 写入.agents/preview.pid、日志写入.agents/preview.log若已有存活进程则提示 Preview already running 而非重复启动stop_server()先尝试SIGTERM优雅终止Windows 下使用taskkill /F /T最后清理 PID 文件status_server()读取 PID 文件判断进程存活输出运行状态、PID、URL 与日志路径。这套脚本为/create的完成即预览提供了可复现的基建Agent 构建完应用后无需手动记忆启动命令统一交给auto_preview.py管理然后把http://localhost:{port}呈现给用户。七、验证收尾从代码存在到代码可用/create的 Front Matter 中声明了第三类产物verification-report验证报告对应requires_skills中的verify-changes。该技能的核心主张是一句话原则Code that exists ≠ Code that works.verify-changes 区分了三种验证方式并明确否定前两种❌Verification by inspection我看到函数存在应该能用❌Verification by assumption类型检查过了所以是对的✅Verification by execution我运行了这是输出它工作是因为 [证据]它针对不同变更类型给出了验证方法映射Bug 修复→ 复现原始 bug 场景确认不再出现新功能→ 运行功能确认输出符合预期重构→ 跑既有测试确认没有破坏API 变更→ 调用端点确认响应形状。在完整项目中这一验证理念由 .agents/scripts/verify_all.py 等脚本工具链落地为可执行命令优先级从 P0 到 P4 排列# P0: Lint Type Check npm run lint npx tsc --noEmit # P0: Security Scan python .agents/skills/vulnerability-scanner/scripts/security_scan.py . # P1: UX Audit python .agents/skills/frontend-design/scripts/ux_audit.py . # P3: Lighthouse需先启动服务 python .agents/skills/performance-profiling/scripts/lighthouse_audit.py http://localhost:3000 # P4: Playwright E2E需先启动服务 python .agents/skills/webapp-testing/scripts/playwright_runner.py http://localhost:3000 --screenshot项目规划阶段还会把验证结果写回计划文件只有 Lint、安全扫描、构建、运行测试全部通过后才在{task-slug}.md中标记## ✅ PHASE X COMPLETE并附上通过清单与日期——这就是verification-report的落点。八、使用示例一句话触发完整流水线/create的使用方式非常直接——在对话中输入命令并附带自然语言描述$ARGUMENTS会被替换为用户输入/create blog site /create e-commerce app with product listing and cart /create todo app /create Instagram clone /create crm system with customer management综合整个工作流一次/create调用的完整生命周期如下需求分析解析用户意图信息缺失时通过 brainstorming 技能按 Socratic Gate 提问类型、功能、用户并用默认值兜底项目规划project-planner拆解任务、确定技术栈、规划文件结构在根目录产出{task-slug}.md计划文件规划期间禁写代码设计源仅 UI 项目按design-spec在根目录产出DESIGN.md先令牌后正文作为 UI 构建的唯一事实来源应用构建用户审批后app-builder根据项目类型选择模板与技术栈协调database-architectSchema、backend-specialistAPI、frontend-specialist按 DESIGN.md 令牌构建 UI等专家 Agent 并行推进预览调用auto_preview.py start拉起本地服务向用户呈现访问 URL验证按 verify-changes 的执行式验证原则运行安全扫描、UX 审计、构建与 E2E 测试产出验证报告并标记 Phase X 完成。九、小结/create的设计哲学纵观 .agents/workflows/create.md 及其依赖的技能与 Agent 定义可以提炼出这条工作流的三条核心设计原则关卡制推进杜绝先做再说需求不清 → Socratic Gate 提问规划未完成 → 禁止写代码设计未就绪 → 禁止画 UI未经审批 → 不进入构建。每一个质量关卡都有对应的硬性产物计划文件、DESIGN.md、验证报告和退出门禁EXIT GATE。专业化分工与边界约束web 与 mobile 的 Agent 选择互斥、数据库与 API 与 UI 各归其位、任务必须包含 INPUT → OUTPUT → VERIFY 三个要素——职责清晰才能并行不冲突。机器可读 人类可读的双轨文档DESIGN.md的 YAML 令牌层可直接转换为tokens.json、Figma variables 与 Tailwind 主题配置是设计意图与代码实现之间的桥梁而 Markdown 正文则为人类保留了设计决策的上下文。对于希望以 Agent 驱动应用开发的团队来说/create演示了一套可复制的范式用结构化的元信息Front Matter声明依赖用强制的关卡控制质量用动态命名的计划文件承载上下文用脚本工具链完成验证与预览闭环。相关定义与实现均可在仓库的 .agents/workflows/、.agents/agent/、.agents/skills/ 与 .agents/scripts/ 目录中继续深入研读。【免费下载链接】ag-kit项目地址: https://gitcode.com/GitHub_Trending/an/ag-kit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考