Wasp 框架项目开发实操从 TypeScript Spec 到 CLI 工作流的完整指南以 Ask The Documents 示例为蓝本【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/wasp导读本文以 Wasp 仓库中 examples/ask-the-documents 示例项目附带的 AGENTS.md 为主线系统讲解 Wasp 项目的核心开发规范与实操流程如何借助llms.txt索引对齐版本文档、如何用main.wasp.ts中的 TypeScript Spec 声明式定义应用、全新检出Fresh checkout后如何正确初始化环境以及为什么用wasp compile而非tsc校验应用。读完本文你将掌握一套可直接复用的 Wasp 项目上手方法论并透过 ask-the-documents 的源码看清这些规范在真实 RAG检索增强生成应用中的落地形态。一、先认识这个项目Wasp 框架下的 AI 全栈示例ask-the-documents是 Wasp 官方仓库中的示例应用其定位是用 Wasp PG Vector 实现文档问答Embeddings / RAG / ChatGPT支持抓取整个链接层级非常适合文档站、抓取单个链接、为页面内容生成向量嵌入、使用 PG Vector 做语义搜索以及借助 OpenAI ChatGPT 与文档对话。而 AGENTS.md 则是该示例为开发者尤其是 AI 编码 Agent准备的项目操作手册。它并不长却浓缩了 Wasp 项目最核心的几条约定文档怎么查、应用规范怎么写、新环境怎么搭、验证怎么做。这正是本文要逐条展开并深化到源码层的内容。二、文档查阅策略通过 llms.txt 索引对齐 Wasp 版本AGENTS.md 的第一条建议是通过 Wasp 的llms.txt索引查找文档而不是凭记忆猜测wasp.sh/docs下的 URL并且要选择与main.wasp.ts中声明的 Wasp 版本相匹配的文档地图。这在实践中非常关键。Wasp 的 API 演进较快不同大版本的语法尤其是 TypeScript Spec 的写法可能不兼容。以本示例为例main.wasp.ts 中声明wasp: { version: 0.26.0 },这意味着查阅文档时应优先参考 0.26.x 对应的文档版本而不是最新的文档或老旧的教程。同时 AGENTS.md 还给出了一条兜底原则如果本文件AGENTS.md/CLAUDE.md与版本化 Wasp 文档冲突以官方文档为准并主动提示用户该文件可能已过时。这体现了项目内说明优先服务于上手权威性仍归于官方文档的工程态度。对应地CLAUDE.md 与 AGENTS.md 内容一致即同一套约定面向 Claude Code 与通用 Agent 同时生效说明 Wasp 官方在示例中普遍内置了面向 AI 编码工具的协作规范。三、Wasp TypeScript Spec以main.wasp.ts为中心的声明式应用规范AGENTS.md 强调main.wasp.ts同时包含 Wasp 版本号与完整的应用规范app specification。这是理解整个示例的关键入口。我们逐条拆解其中的约定并对照源码验证。3.1 应用声明与基础配置main.wasp.ts 的骨架如下export default app({ name: askTheDocuments, wasp: { version: 0.26.0 }, title: PG Vector Example, auth: { userEntity: User, methods: { google: { userSignupFields: googleUserSignupFields, configFn: getGoogleAuthConfig, }, }, onAuthFailedRedirectTo: /, }, client: { rootComponent: Layout }, server: { envValidationSchema: serverEnvValidation }, spec: [ /* routes, actions, queries */ ], });可以看到认证Google 登录、客户端根组件、服务端环境变量校验都集中在此声明。认证相关的实现位于 src/auth/google.tsgoogleUserSignupFields通过defineUserSignupFields把 Google profile 中的 email 映射为用户字段getGoogleAuthConfig返回scopes: [profile, email]服务端环境变量校验则在 src/env.ts 中用 zod 定义了OPENAI_API_KEY为必填项。3.2 关键语法约定显式命名 vs 导入标识符命名AGENTS.md 给出了两条极易踩坑的规则route(name, ...)与crud(name, ...)必须显式传名称。本示例中的路由就是典型route(RootRoute, /, page(Main), { prerender: true }),这里显式命名RootRoute路径为/页面组件为Main来自src/pages/MainPage并开启了prerender预渲染。其他构造函数不接收名称参数声明名就是导入的标识符。例如job(sendReminder, { ... })声明了一个名为sendReminder的 Job。同理本示例中的操作operations声明如下action(embedDocument, { entities: [Document] }), action(getScrapeCandidates, { entities: [Document] }), query(getDocuments, { entities: [Document] }), action(searchDocuments, { entities: [Document] }), action(askDocuments, { entities: [Document] }), action(deleteDocument, { entities: [Document] }), action(deleteAllDocuments, { entities: [Document] }),这些embedDocument、getDocuments等标识符来自./src/documents的with { type: ref }导入因此操作名与其 TS 实现函数名完全一致。3.3 引用与生成with { type: ref }与wasp.sh/specAGENTS.md 明确了两点当main.wasp.ts引用应用组件/函数时必须从src/用with { type: ref }导入。这是为了让 Wasp 编译器能够区分纯导入与引用 Wasp 管理的源码从而正确生成类型与调用链。例如import { Layout } from ./src/Layout with { type: ref }; import { Main } from ./src/pages/MainPage with { type: ref };wasp.sh/spec是由 Wasp 生成的不要从 npm 手动安装。在 package.json 中可以看到它的安装方式是本地文件引用wasp.sh/spec: file:.wasp/spec即每次 Wasp 编译后生成的 spec 包这正是规格即产物的体现。3.4 从源码看 Spec 如何驱动业务实现Spec 中的每个操作都在 src/documents.ts 有对应实现且统一从wasp/server/operations导入类型embedDocument抓取 URL 内容 → 用 OpenAItext-embedding-3-small生成向量 → 通过 Prisma$queryRaw与pgvector的toSql工具写入Document表。searchDocuments对查询文本生成向量用ORDER BY embedding - ${embedding}::vector做余弦距离排序-即向量距离运算符取前 10 条并附带 score。askDocuments先取最相近的 2 篇文档再构造一个名为answer_with_sources的 function calling 工具让gpt-4o基于文档内容作答并结构化返回{ answer, sources }。这与 Spec 中声明的输入/输出类型一一对应是声明式规范 类型安全 RPC最直观的示例。数据库侧的支撑在 schema.prisma数据源启用了extensions [pgvector(map: vector)]与previewFeatures [postgresqlExtensions]Document模型中的embedding字段类型为Unsupported(vector(1536))即 1536 维向量列。四、全新检出Fresh Checkout三步走AGENTS.md 规定在全新 clone 或 worktree 中运行任何其他 Wasp 命令之前必须依次完成以下步骤。对照 README.md 的Running it locally部分可以得到完整实操版本第一步wasp installnpm i -g wasp.sh/wasp-clilatest wasp installwasp install会安装项目依赖并构建生成wasp.sh/spec等本地包这也是 package.json 中file:.wasp/spec得以存在的前提。注意 README 要求先安装最新版 Wasp CLI再执行wasp install。第二步配置环境变量从示例文件或项目 README准备.env.server与.env.client。本示例在 src/env.ts 用 zod 校验服务端变量核心必填项为OPENAI_API_KEYyour_openai_key GOOGLE_CLIENT_IDyour_google_client_id GOOGLE_CLIENT_SECRETyour_google_client_secret其中OPENAI_API_KEY由serverEnvValidation强制要求缺失时启动即报错Google 凭证用于社交登录。客户端变量则按项目需要放入.env.client。第三步启动数据库并迁移本示例使用 PG Vector 扩展因此数据库镜像必须带 vector 支持wasp start db --db-image pgvector/pgvector:pg18 wasp db migrate-devwasp start db以pgvector/pgvector:pg18启动数据库容器wasp db migrate-dev应用 Prisma 迁移仓库migrations/目录下的 SQL 迁移会自动执行。README 中还用wasp start同时启动客户端与服务端即完成了本地全栈运行。是否需要 seed 数据以项目 README 说明为准——本示例无需 seed直接通过页面录入文档。五、验证方式用wasp compile不要直接跑tscAGENTS.md 给出了明确指令运行wasp compile检查应用是否合法不要直接用tsc做校验。原因在于 Wasp 项目是多层代码的拼合main.wasp.ts中的 Spec、src/下的实现、wasp/entities、wasp/server/operations等生成模块只有经过 Wasp 编译生成.wasp/out后才是完整可类型检查的工程。直接tsc会因为缺少生成模块而误报或漏检。wasp compile会执行完整的 Spec 解析、类型检查与代码生成是唯一的官方校验入口。这也解释了为何仓库根目录存在tsconfig.wasp.json、tsconfig.src.json等多套 TS 配置——它们服务于不同的编译阶段统一由 Wasp 编排。在 CI 或 e2e 层面本示例还配套了 e2e-tests/tests/simple.spec.ts用 Playwright 验证首页搜索框可正常渲染是对应用可编译可运行的端到端补充。六、从示例源码反推Spec 约定如何保证端到端类型安全最后做一个收束性的源码印证。整套 Spec 约定的最终受益者是类型安全操作类型src/documents.ts中每个操作都标注了泛型如embedDocument: EmbedDocumentEmbedDocumentInput, EmbedDocumentOutput输入输出类型在 main.wasp.ts 的 Spec 中登记后前端即可获得完全对齐的调用签名。客户端调用页面组件如 MainPage.tsx通过useAuth()判断登录态登录前仅展示问答表单登录后则提供 Ask / Add Document / Search 三个标签页对应askDocuments、embedDocument、searchDocuments等操作——前后端由 Spec 生成同一套类型契约。环境与认证Google 登录的userSignupFields、环境校验的 zod schema 同样进入 Spec成为应用声明的一部分。这一闭环正是 Wasp batteries-included 理念的体现开发者只写声明式规范与纯业务函数auth、RPC、数据库向量检索等全栈复杂性由框架抽象。结语Wasp 项目的上手门槛并不在于写业务代码而在于理解它独特的声明式 Spec CLI 工作流用llms.txt对齐版本文档在main.wasp.ts中按显式命名与导入标识符命名两条规则声明路由与操作以wasp install→ 环境变量 →wasp db migrate-dev完成新环境初始化并始终以wasp compile作为合法性校验。围绕 ask-the-documents 的源码可以看到这套约定在真实的 RAG 应用中完全成立Spec 里的每个 action/query 都有对应实现、每处导入都带with { type: ref }、每个环境变量都有 schema 约束。把这套方法论带回你自己的 Wasp 项目无论是本地开发、Agent 协作还是 CI 校验都能少踩大量弯路。【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/wasp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考