扩展方向

1. 替换真实 RAG

教学版使用关键词重叠。下一步可以替换为：

• Mastra RAG 的 MDocument chunk。
• embedding 模型。
• PostgreSQL pgvector、Pinecone、Qdrant 等向量库。
• rerank，用于从候选结果里选出更贴题的上下文。
• source metadata，用于回答时引用资料来源。

替换原则：保持 searchCourseTool 的输入输出不变，只替换内部检索实现。

2. 增强 Memory

当前项目只启用最近消息。可以逐步加入：

• working memory：记录学习目标、偏好、薄弱点。
• schema-based working memory：让 UI 读取学习状态。
• semantic recall：跨 thread 找回相似学习历史。
• memory processors：控制长对话进入上下文的内容。

升级时先设计 resource/thread 命名规则，避免用户间串话。

3. 加入 RequestContext 和 Streaming

真实应用通常需要按请求改变行为：

• 免费用户只允许资料搜索。
• Pro 用户可以生成计划和练习。
• 企业用户使用更大的 RAG topK 或更强模型。
• 中文和英文用户使用不同 instructions。

这些用 RequestContext 传入，不要写进长期 Memory。

前端 UI 接入时，优先用 .stream()，并在调试模式下显示 tool-call、tool-result、finish 等事件。正式 UI 再把内部事件转成进度条、工具状态或引用来源。

4. 增加模型策略

当前项目通过 MASTRA_MODEL 选择默认模型。真实应用可以继续扩展：

• fast 模式：低成本、低延迟模型，用于摘要和普通问答。
• reasoning 模式：更强推理模型，用于复杂计划和多步分析。
• fallback 模型：主模型不可用时保证服务可用。
• embedding 模型：单独记录，用于 RAG 和 semantic recall。
• 本地模型：通过 OpenAI-compatible endpoint 接入，适合隐私或离线实验。

模型策略要配合 eval cases 验证。不能只因为某个模型回答更长，就判断它更好。

5. 加入 Web UI

当 Studio 验证稳定后，可以接入：

• Next.js
• React + Vite
• Astro

前端只需要调用 Mastra 暴露的 Agent 或 Workflow endpoint。不要在前端重写 Agent 逻辑。

6. 增加评估

可以加入固定测试集：

• 问题是否引用资料。
• 学习计划是否覆盖目标。
• 练习题是否和 topic 匹配。
• 不知道时是否拒绝编造。

先从本地断言开始，再迁移到 Mastra Scorers。Scorers 适合在 Studio 或 CI 中持续比较 Agent 输出质量，尤其适合判断 prompt、模型和工具描述改动是否真的有效。

本教程已经提供离线起点：

npm run final:eval

扩展时优先新增 eval cases，不要直接替换已有样例。这样才能比较改动前后的行为。

7. 接入 MCP

如果学习资料来自外部系统，可以用 MCPClient 接：

• 文档系统。
• GitHub 仓库。
• Notion 或知识库。
• 内部搜索服务。

如果需要把 Study Agent 的能力开放给编辑器或其他 Agent，可以用 MCPServer 暴露 tools 和 workflows。

多用户系统优先使用请求级 listToolsets()，不要把某个用户的外部工具凭证静态挂到 Agent 上。

8. 加入 Processors 和 Guardrails

可以逐步加入：

• TokenLimiter：控制上下文长度和成本。
• PromptInjectionDetector：识别「忽略系统提示」等攻击。
• PIIDetector：遮蔽邮箱、电话、密钥等敏感内容。
• SystemPromptScrubber：避免模型输出内部 instructions。
• 自定义 output processor：检查回答是否引用资料，失败时要求重试或安全退出。

新增 guardrail 前，先写出正常样例和违规样例，避免误杀正常学习问题。

9. 加入人工确认

当前项目不执行写操作。如果扩展为「写日历」「发邮件」「删除学习记录」，需要：

• 在对应 Tool 上加 requireApproval: true。
• 在 UI 或命令行里展示工具名、参数和影响范围。
• 明确 approve、decline 和超时后的行为。
• 确保 Mastra storage 已配置，否则审批恢复状态可能丢失。

10. 服务化和生产化注意事项

方向	注意
鉴权	不要让任意用户访问所有 memory
数据隔离	resource 应绑定用户或租户
成本控制	限制 topK、token、循环次数
可观测性	记录工具调用和失败原因
安全	工具不要执行任意命令或访问未授权文件
API 边界	自定义路由不要绕开 Agent / Tool / Workflow 设计
请求上下文	权限、语言、租户放 RequestContext，不放 Memory

继续练习

可以尝试让 AI 生成一个小扩展：

请在 Study Agent 中新增一个 summarizeProgressTool。
要求：
- 输入 resource 和 thread。
- 输出最近学习目标、完成内容和下一步建议。
- 如果没有记忆，返回清楚的空状态说明。
- 不要新增依赖。