故障排查

1. 部署成功但 /mcp 无响应

可能原因：

• 边缘函数路径不正确
• cloud-functions/mcp.js 未被 Makers 文件路由识别
• 路由未发布到最新版本

排查步骤：

1. 确认目录结构是否正确
2. 在平台查看最近一次部署日志
3. 用 curl -i https://<你的域名>/mcp 检查状态码

2. tools/list 正常，但 tools/call 报错

可能原因：

• 请求体 JSON-RPC 格式不完整
• 工具参数不符合 inputSchema
• 后端请求知识库 API 失败

排查步骤：

1. 检查 method 是否为 tools/call
2. 检查 params.name 与工具名是否完全一致
3. 检查 arguments 字段类型与必填参数

3. 知识库检索结果为空

可能原因：

• 文档尚未完成向量化
• include 规则未覆盖目标 markdown
• 查询词过短或语义不明确

排查步骤：

1. 确认流水线“向量化数据”阶段成功
2. 检查 .cnb.yml 的 include 配置
3. 用更完整问题重试（并适当提高 top_k）

4. 本地预览正常，线上页面异常

可能原因：

• Node 版本不一致
• 构建命令与包管理器不匹配
• 静态资源路径配置差异

排查步骤：

1. 对齐 edgeone.json 里的 nodeVersion
2. 确认 buildCommand 与 installCommand 可在 CI 运行
3. 查看构建日志中的资源路径错误

5. 外部 AI 工具无法连接 MCP

可能原因：

• URL 配置错误
• 传输类型配置错误（应为 streamable-http）
• 客户端缓存旧配置

排查步骤：

1. 再次核对配置文件中的 URL
2. 重启客户端后重试
3. 先用 curl 验证服务可用，再排查客户端

6. 网页 Agent 返回 400

可能原因：/chat 请求缺少 makers-conversation-id。

排查步骤：

1. 在浏览器 Network 中检查请求头
2. 确认 conversation ID 由 crypto.randomUUID() 生成
3. 确认请求发往 Makers 代理地址而不是裸 VitePress 端口

7. Agent 返回环境变量错误

运行 edgeone makers env ls，确认 CNB_KNOWLEDGE_BASE_URL 与 CNB_KNOWLEDGE_BASE_TOKEN 已配置。AI Gateway 的变量需要在 .env.example 中声明，才能由 Makers 部署流程自动注入。

8. 停止生成无效

确认 /stop 的 body 传入 { "conversation_id": "..." }，并在 makers-conversation-id 请求头携带同一个 ID。EdgeOne CLI/runtime 1.6.8 会在缺少该请求头时，于 handler 之前返回 AGENT_CONVERSATION_ID_REQUIRED。