常见错误

npm install 失败

先确认 Node 版本：

node -v

本项目建议 Node 22+。如果依赖下载失败，先重试：

npm install

VitePress 构建失败

运行：

npm run docs:build

常见原因：

现象	处理
找不到页面	检查 docs/.vitepress/config.ts 里的 link
Mermaid 图不显示	检查代码块是否使用 mermaid 语言
Vue SSR 报 window 不存在	客户端逻辑必须放进 onMounted

Demo 运行失败

运行单个 Demo：

npm run demo:01

如果 TypeScript 报错：

npm run typecheck

Mastra Studio 启动失败

运行：

npm run final:dev

常见原因：

错误	处理
OPENAI_API_KEY 缺失	复制 .env.example 为 .env 并填写
Agent 不显示	检查 apps/study-agent/src/mastra/index.ts
Tool 不显示	检查 tools 是否注册到 Mastra
Workflow 不显示	检查 workflows 是否注册
端口占用	关闭已有 Mastra 进程或换端口配置
ENOENT: ... .mastra/.build/entry-0.mjs	见下方「mastra dev 的 --root 半残问题」

mastra dev 的 --root 半残问题

现象:运行 npm run final:dev 报 ENOENT: no such file or directory, open '.../.mastra/.build/entry-0.mjs',且 apps/study-agent/.mastra/.build/ 是空目录。

根因:mastra@1.10.2 的 dev 命令对 --root 支持不完整 —— bundler 把 bundler-config.mjs 和 output/ 写到 --root 指定的目录,但底层 esbuild 仍按 process.cwd() 输出/读取 .mastra/.build/entry-0.mjs,两边路径对不上,.build/ 一直是空的。

修复(已落到根目录 package.json 的 final:dev 脚本):用 cd 让 cwd 和 root 一致,不要再用 --root:

"final:dev": "cd apps/study-agent && mastra dev --dir src/mastra"

后续如果升级 mastra CLI,可以重新尝试 --root 是否已修复;在那之前都用 cd 这种写法。

Agent 不调用工具

先检查三件事：

1. Tool description 是否说明“什么时候调用”。
2. Agent instructions 是否要求先查资料。
3. 用户问题是否真的需要工具。

可以用这个提示词让 AI 帮你排查：

请检查这个 Mastra Agent 为什么没有调用工具。
只关注：
- Agent instructions
- tool description
- inputSchema
- 用户问题是否匹配工具能力
不要重写整个项目。

Memory 不生效

检查：

• 是否配置了 storage。
• Agent 是否设置了 memory。
• 调用时是否传入稳定的 resource 和 thread。
• 是否把不同用户复用了同一个 thread。

RAG 答非所问

先不要调 prompt，先看检索结果：

• topK 是否太小。
• chunk 是否太长或太短。
• 查询词是否能命中资料。
• score 是否能把相关片段排在前面。

如果检索结果错了，模型回答再怎么改也很难稳定。

离线评估失败

运行：

npm run final:eval

如果 passed 为 false，先看失败 scorer：

Scorer	先查
toolUseCorrectness	工具是否被调用，工具名是否和脚本预期一致
topicCoverage	检索命中的资料 topic 是否正确
expectedSignals	输出是否缺少关键业务信号
forbiddenSignals	是否出现编造、危险或不该展示的内容
planCompleteness	学习计划是否有天数、任务和验收标准
refusalQuality	资料不足时是否明确拒绝编造

不要只看平均分。单个安全样例失败时，即使总分还不错，也应该先修边界行为。