agentic-awesome-skills App Builder 项目类型检测机制：从关键词矩阵到工程脚手架

• AI 技能
• AI 插件
• 人工智能

本文以 AAS（agentic-awesome-skills）插件库中 App Builder 技能的 project-detection.md 为核心，系统讲解 Agent 如何从一段自然语言需求中识别项目类型、匹配脚手架模板，并联动技术栈选择与多 Agent 编排，最终生成可运行的完整工程。读完本文，你将掌握一套可直接复用的关键词→项目类型→模板映射方法，以及围绕它的检测流程、缺失信息兜底与技术栈决策机制。

一、为什么要做项目类型检测

在 Agent 驱动的应用构建流程中，第一步也是最容易出错的环节，就是从用户的一句"帮我做一个博客站""写个电商后台"之类的自然语言中，判断他真正想要的是什么形态的产物。App Builder 将这一环节抽象为独立的Project Type Detection（项目类型检测）模块，其职责定义非常克制：Analyze user requests to determine project type and template——只做两件事：判定项目类型、匹配对应模板。

从源码结构看，app-builder 技能目录 采用"按需精读"的模块化设计：project-detection.md只负责类型判定，tech-stack.md负责技术选型，scaffolding.md负责目录骨架，agent-coordination.md负责多 Agent 编排，feature-building.md负责已有项目上的增量迭代。这种拆分使每个子文档都可以被 Agent 单独检索、单独引用，也构成了本项目"选择性阅读规则"（Selective Reading Rule）的实践基础。

二、核心机制：关键词矩阵（Keyword Matrix）

项目类型检测的技术内核是一张关键词 → 项目类型 → 模板的三列映射表。Agent 将用户请求分词后，在矩阵中命中关键词，即可锁定目标类型与对应脚手架模板。下表完整收录了 project-detection.md 中的 14 条映射规则：

这张矩阵本身蕴含了三条可复用的设计经验：

1. 同类型多模板的分流：例如blog与docs都映射到astro-static（内容型站点），而e-commerce与saas都映射到nextjs-saas（需要鉴权与支付能力的商业型应用）。这说明映射的依据是工程能力需求而非字面语义：需要登录、下单、订阅的功能型 Web 应用统一落到 Next.js 商业模板，纯内容展示则落到静态生成模板。
2. 关键词具有领域信号强度：stripe、subscription这类词汇几乎可以直接锁定 SaaS，flutter、dart直接锁定 Flutter 移动端，属于高置信度信号；而service、management这类词存在歧义，需要配合上下文或后续澄清环节消解。
3. 模板名即技术栈预告：矩阵中的模板名与 templates 目录 下真实存在的 13 个脚手架模板一一对应（含nuxt-app），检测结果可以直接作为后续读取模板文件的索引，形成"检测→选模板→读模板→搭骨架"的无缝衔接。

三、检测流程：从 Token 到技术栈建议

project-detection.md 给出的检测流程是一个五步流水线：

1. Tokenize user request # 对用户请求分词 2. Extract keywords # 提取关键词 3. Determine project type # 判定项目类型 4. Detect missing information → forward to conversation-manager # 检测缺失信息 → 转交对话管理器 5. Suggest tech stack # 给出技术栈建议

3.1 分词与关键词提取（步骤 1–2）

对用户请求做分词（Tokenize）并按上表提取关键词（Extract keywords）。这一阶段建议同时进行归一化处理（小写、去除停用词、合并同义词），使"I want a shopping cart and payment"与"e-commerce with cart"能命中同一组关键词cart/payment→ E-commerce。

3.2 类型判定（步骤 3）

根据命中结果确定项目类型。多关键词冲突时（例如同时出现api与mobile），应从优先级更高的具体领域信号（如flutter、react native）出发，或在第 4 步交由澄清环节裁决。

3.3 缺失信息兜底（步骤 4）

当信息不足（例如只有"make a website"，无法确定是 landing、blog 还是 dashboard）时，检测模块不会擅自猜测，而是将缺失信息转发给对话管理器（conversation-manager）。这是整个流程中最重要的兜底设计——它把"信息不全"从错误降级为一次正常的对话交互，避免 Agent 在错误的方向上浪费整条流水线。

3.4 技术栈建议（步骤 5）

类型确定后，检测模块给出技术栈建议。其依据是 tech-stack.md 中定义的 2025 默认技术栈，适用于 Web 应用的推荐组合如下：

Frontend: framework: Next.js 16 (Stable) language: TypeScript 5.7+ styling: Tailwind CSS v4 state: React 19 Actions / Server Components bundler: Turbopack (Stable for Dev) Backend: runtime: Node.js 23 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 Realtime、Socket.io；文件存储可选 Cloudinary、S3；支付以 Stripe 为默认，备选 LemonSqueezy、Paddle；邮件可选 Resend、SendGrid；搜索可选 Algolia、Typesense。检测模块输出的技术栈建议即来自这套默认/备选体系，具体落地时再结合用户环境验证。

四、检测结果如何驱动模板与工程骨架

检测完成后，App Builder 会只读取与项目类型匹配的那一个模板文件（Selective Reading Rule），而不是把 13 个模板全部载入上下文。模板清单定义在 templates/SKILL.md：

以检测到 Blog / astro-static 为例，astro-static/TEMPLATE.md 会给出从创建到部署的完整路径：npm create astro@latest {{name}}→npx astro add mdx tailwind sitemap→ 配置astro.config.mjs→ 创建 Content Collections →npm run dev，并强调"Zero JS by default"与 Islands 架构（按需局部水合）两大原则。

若检测到 E-commerce / nextjs-saas，nextjs-saas/TEMPLATE.md 则覆盖鉴权（NextAuth.js v5）、支付（Stripe Checkout / Portal / Webhooks）、邮件（Resend）三件套，并给出完整的环境变量清单：DATABASE_URL、NEXTAUTH_SECRET、STRIPE_SECRET_KEY、STRIPE_WEBHOOK_SECRET、RESEND_API_KEY。

对于 Python 侧需求，python-fastapi/TEMPLATE.md 定义了 FastAPI + SQLAlchemy 2.0 + Pydantic v2 + Alembic 的分层结构（routers / dependencies / services / models / schemas），安装与启动命令为pip install fastapi uvicorn sqlalchemy alembic pydantic→alembic upgrade head→uvicorn app.main:app --reload。

工程目录骨架的通用规范见 scaffolding.md，它定义了五条结构原则：功能隔离（features/内聚组件、hooks、actions）、服务端/客户端分离（server/杜绝意外客户端导入）、薄路由（app/只做路由，逻辑下沉features/）、路由组（(group)/共享布局不污染 URL）、共享代码（shared/承载可复用 UI 与工具），并提供了@/features/*、@/shared/*、@/server/*等 tsconfig 路径别名配置示例。

五、检测之后的编排：多 Agent 流水线

类型与模板确定后，App Builder 进入 agent-coordination.md 定义的编排流水线。执行顺序如下表：

值得注意的两点工程约束：其一，Phase 0 的 Socratic Gate 要求先提出 3 个澄清问题——这与检测流程第 4 步"缺失信息转交对话管理器"的设计一脉相承，都是"先问清、再动手"；其二，Phase 1.5 的 PLAN 校验是强制检查点（🔴 CRITICAL），任何专家 Agent 在{task-slug}.md计划文件未落盘之前不得开工，这从流程上杜绝了"边猜边写"的失控状态。检测阶段给出的项目类型与技术栈建议，正是 Phase 0 澄清问题与 Phase 1 制定计划时的输入依据。

六、小结：这套检测机制的复用价值

Project Type Detection 的核心价值不在于那张关键词表本身，而在于它体现的三层设计：

1. 查表代替推理：用一张可维护、可扩充的关键词矩阵把"意图→类型→模板"的映射显式化，任何 Agent（或人）都能零成本理解与修改；
2. 先对齐再执行：通过 conversation-manager 转发与 Socratic Gate 双重机制，把信息缺失问题前置化解，避免整条流水线返工；
3. 检测与执行解耦：检测模块只输出"类型 + 模板 + 技术栈建议"，具体搭骨架交给 templates 下的模板、多 Agent 协作交给 agent-coordination.md，各司其职、互不侵入。

实际引用本项目时，可按 app-builder/SKILL.md 的约定按需精读：新项目起步读project-detection.md，选技术栈读tech-stack.md，搭结构读scaffolding.md，多 Agent 协作读agent-coordination.md，增量加功能读feature-building.md，脚手架只读匹配的那一个TEMPLATE.md。这套"主题文档 + 按需精读 + 强制检查点"的组合，同样适用于任何希望让 Agent 稳定产出工程代码的技能编排场景。

• AI 技能
• AI 插件
• 人工智能