Mastra 模板实战从 PDF 自动生成教学闪卡flash-cards-from-pdf 完整解析【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本文围绕 Mastra monorepo 中的templates/template-flash-cards-from-pdf模板展开它是一个上传 PDF → 自动解析 → 生成带难度分级的教学闪卡 → 可选 AI 配图的完整 Agent 应用。读完本文你将掌握该模板的运行与配置方式脚手架命令、环境变量、Mastra Studio 交互流程并能基于仓库源码理解其背后的两个核心工具——PDF 文本抽取工具与图像生成工具——的实现细节从而把它改造成适配自己学习/培训场景的闪卡系统。一、模板定位它想演示什么模板 READMEREADME.md开宗明义这是一个从 PDF 文档生成教育闪卡的模板。用户在 Mastra Studio 中附加一个 PDF 文件Agent 就会创建闪卡并支持按需生成 AI 配图。README 在 Why we built this 一节说明该模板刻意展示了两个典型能力让 Agent 生成图像通过工具调用触发图像模型而不是让 Agent 直接画图构建一个解析 PDF 的工具把二进制文件解析逻辑封装成结构化工具供 Agent 在推理过程中按需调用。因此这个模板的价值不仅是一个学习卡生成器更是一份 Mastra 中文档解析工具 多模态生成工具 长期记忆 Agent组合模式的参考实现。二、运行前提与快速启动环境前提根据 package.json该模板要求Node.js 22.13.0并且默认依赖一个 OpenAI API keyREADME 指出默认使用 OpenAI但可以替换为任意模型。仓库中的.env.example内容极简只有一个占位项OPENAI_API_KEYyour-api-key即模板同时用 OpenAI 完成两件事驱动对话 Agent默认模型openai/gpt-5-mini与生成配图DALL-E 3所以单个 OpenAI key 即可跑通全流程。三步启动按照 README 的 Quickstart克隆模板执行npx create-mastralatest --template flash-cards-from-pdf在本地脚手架化项目配置密钥复制.env.example为.env并填入 key启动开发服务器执行npm run dev对应 package.json 中dev: mastra dev脚本然后打开http://localhost:4111体验。package.json中另外提供buildmastra build与startmastra start脚本用于生产构建与启动。核心依赖包括mastra/core、mastra/memory、mastra/libsql、mastra/loggers、mastra/observability、aivNext AI SDK^6.0.101、pdf-parse^2.4.5与zod^4.3.6。三、在 Mastra Studio 中实际操作README 的 Making it yours 一节给出了完整的交互路径在 Studio 中选择Flash Card Agent使用聊天界面的附件按钮附加一个 PDF 文件仓库内提供了 assets/example.pdf 供测试约 128KB对 Agent 说Create flash cards from this PDF可选地追加一句Generate flash cards with images for the key concepts此时 Agent 才会调用图像生成工具为关键概念配图。这一步的顺序设计是有意的图像生成在 Agent 指令中被限定为仅在用户明确要求时才生成详见下文指令分析默认只产出文字闪卡避免不必要的图像生成开销。README 同时说明演示在 Mastra Studio 中运行但同一套 workflow 可以通过 Mastra Client SDK 接入 React、Next.js 或 Vue 应用也可以配合 AI SDK UI、CopilotKit、Assistant UI 等 agentic UI 库使用——即 Studio 只是调试入口不是运行时绑定。四、Agent 实现剖析flash-card-agent.tsAgent 定义在 flash-card-agent.ts是一个标准的mastra/core/agent实例export const flashCardAgent new Agent({ id: flash-card-agent, name: Flash Card Generator, description: Generates educational flash cards from PDF documents, model: openai/gpt-5-mini, instructions: You are an educational flash card generator. ..., tools: { extractPdfText, generateImage }, memory: new Memory(), });几个关键配置点model: openai/gpt-5-mini默认对话模型替换成其他 provider 只需改这一行memory: new Memory()挂载了mastra/memory的记忆能力配合下面的 LibSQL 存储实现多轮会话上下文tools注册了extractPdfText与generateImage两个工具Agent 的能力边界就由这两个工具 指令共同决定。instructions是整个模板的业务规则引擎值得逐条看原文为英文此处归纳要点工作流程用户附加 PDF → Agent 收到 base64 文件内容 → 用extract-pdf-text工具提取文本 → 分析文本生成闪卡 → 用户要求时再为关键概念调用generate-image生成规则每份 PDF 默认生成10–20 张卡除非用户指定数量每张卡正面是清晰的question、背面是简洁的answer每张卡标注难度easy / medium / hard和分类/主题问题类型需多样化定义、解释、对比、应用答案必须忠实于 PDF 原文不得虚构输出格式规定了一套 Markdown 结构如### Flash Cards: [Subject Area]标题下逐卡输出**Card N** (difficulty) — [Category]- **Q:** .../- **A:** ...保证下游Studio 或自己的前端可以稳定解析图像约束仅当用户明确要求时生成图片每次挑选3–5 个最适合图示的概念并在卡片输出中带上图片路径异常处理没有 PDF 时提示用户附加PDF 文本过少时告知用户并尽力而为。从源码结构看这套指令把质量约束数量、难度、忠实度与格式约束Markdown 模板都写死在 prompt 里而不是依赖后处理脚本——这是典型的用指令约束输出的 Agent 工程实践。五、工具一PDF 文本抽取extract-pdf-text实现见 extract-pdf-text.ts使用createToolmastra/core/tools定义底层用pdf-parse的PDFParse类。输入/输出 Schemazod 定义同时充当工具的API 契约方向字段说明inputpdfBase64: stringBase64 编码的 PDF 数据可带或不带data:application/pdf;base64,前缀outputtext: string提取出的全部文本outputpageCount: numberPDF 总页数outputtitle: stringPDF 元数据中的标题无则为空串执行逻辑对应源码 L16–L40用正则^data:application/pdf;base64,剥离可能存在的 data URI 前缀再Buffer.from(base64Data, base64)还原字节new PDFParse({ data: new Uint8Array(buffer) })创建解析器getInfo()拿到总页数逐页parser.getText({ partial: [i] })提取第 i 页文本trim()后非空才收集——跳过空白页parser.destroy()释放解析器资源各页文本用\n\n拼接连同页数、标题一起返回。两个工程细节值得借鉴兼容带/不带 data URI 的 base64 输入Studio 附件通常以 data URI 形式给出文件内容工具侧统一做了前缀剥离调用方模型不必关心格式差异输出 Schema 附带pageCount与title这让 Agent 在生成闪卡时能感知文档规模比如配合指令中PDF 文本过少时告知用户的规则而不只拿到一坨纯文本。六、工具二图像生成generate-image实现见 generate-image.ts是 README 所说演示 Agent 生成图像的核心。输入/输出 Schema方向字段说明inputconcept: string要可视化的概念inputsubjectArea: string学科领域如 biology、physics、historyoutputimagePath: string生成图片的本地文件路径outputrevisedPrompt: string实际使用的提示词执行逻辑对应源码 L22–L42提示词模板化不是把concept直接丢给图像模型而是套用一个固定的教学风格模板Create a clear, educational diagram or illustration about ${concept} in the subject of ${subjectArea}. ... Use clean visuals, labels where helpful, and no walls of text. Style: educational, clean, minimal.——保证出图风格统一为清晰、带标注、无大段文字的教学插画调用ai包的generateImage模型为openai.image(dall-e-3)尺寸固定1024x1024输出目录为进程工作目录下的output/imagesmkdir时带recursive: true文件名为randomUUID().png避免覆盖冲突把返回的 base64 写盘返回{ imagePath, revisedPrompt }Agent 随后把imagePath放进卡片输出前端/Studio 即可引用该图片。替换图像 provider 的切入点就在这里把openai.image(dall-e-3)换成ai包支持的其他图像模型或改为读取远端 API 的 base64其余保存/返回逻辑可以原样保留——这也是 README 中 Swap in a different image generation provider 提示的具体落点。七、服务装配存储、日志与可观测性Mastra 实例装配在 index.ts把 Agent 与基础设施一次性组合export const mastra new Mastra({ agents: { flashCardAgent }, storage: new LibSQLStore({ id: flash-cards-storage, url: file:./mastra.db }), logger: new PinoLogger({ name: Mastra, level: info }), observability: new Observability({ configs: { default: { serviceName: mastra, exporters: [new MastraStorageExporter(), new MastraPlatformExporter()], spanOutputProcessors: [new SensitiveDataFilter()], }, }, }), });各部分职责LibSQLStoremastra/libsql本地文件数据库file:./mastra.db为new Memory()提供会话/消息持久化——Agent 的对话记忆落到这个 SQLite 兼容库里这也是多轮追问如先出卡、再要图能保持上下文的原因PinoLoggerinfo级别的结构化日志开发时终端可见Observability同时挂MastraStorageExportertrace 落存储与MastraPlatformExporter两个 exporter并用SensitiveDataFilter对 span 输出做敏感数据过滤。对模板而言这是生产级可观测性的默认配置示范直接改配置即可接入不同 exporter。八、定制与集成到你自己的应用README 给出的改造路径有三条均对应明确代码位置换模型/换图像 provider改 flash-card-agent.ts 的model字段或改 generate-image.ts 的图像模型改生成规则直接编辑 Agent 的instructions比如把默认 10–20 张改为 5 张、调整难度分级、变更 Markdown 输出结构无需动任何工具代码接入自己的前端Agent 在src/mastra/agents下README 提示edit it directly to fit your use case对外暴露则通过 Mastra Client SDK 或 agentic UI 库接入 React / Next.js / Vue 应用Studio 交互流程与 API 调用消费的是同一个 Agent。TypeScript 配置tsconfig.json采用ES2022target、bundler模块解析与strict: trueinclude仅覆盖src/**/*改造时保持src目录约定即可。九、模板机制与贡献说明Mastra 模板templates是一组开箱即用的参考项目存放在 Mastra monorepo 中并自动同步到独立仓库以便npx create-mastra --template name直接克隆。需要注意的是 CONTRIBUTING.md 的说明该目录下的仓库是自动生成的在此直接开 PR 会被忽略正确贡献路径是先 Fork Mastra monorepo在其中的templates/template-flash-cards-from-pdf目录修改再向 monorepo 提 PR由同步机器人把合入变更带到独立仓库。十、小结与文件索引该模板用一个约 150 行的 Agent 定义 两个不到 50 行的工具完整演示了 Mastra 中文档理解型 Agent的构建范式关注点参考文件模板说明与快速启动README.mdAgent 与闪卡生成规则flash-card-agent.tsPDF 解析工具pdf-parse 分页提取extract-pdf-text.ts图像生成工具DALL-E 3 本地落盘generate-image.ts存储/日志/可观测性装配index.ts依赖与脚本Node 22.13.0package.json测试用示例 PDFassets/example.pdf环境变量模板.env.example如果你想在此基础上扩展如把闪卡输出落库、支持多语言、或换成非 OpenAI 的文本/图像模型所有改动点都收敛在上述少量文件中这正是该模板作为教学样例的设计意图。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
)
