ETHANKIT

故障排查

EthanKit agent、模型、MCP、飞书、记忆、评测和定时任务出现异常时的排查顺序。

先看权限

如果按钮不存在，或者进入某个页面后被带回 Dashboard，先确认当前账号是否是管理员。Viewer 模式不能运行 agent、保存配置或访问 admin-only 页面。

Agent 不能运行

按这个顺序检查：

  1. Agent 是否选择了可用模型。
  2. 模型配置是否通过 Test。
  3. 当前账号是否是管理员。
  4. Trace 里是否有模型、工具或权限错误。
  5. 如果启用了 MCP，检查对应 MCP 是否连接成功。
  6. 如果启用了 Memory，检查 workspace 和 embedding 配置。

没有模型可选

进入 模型配置，新增至少一个 BYOK 模型。保存后测试连接，再回到 Agent Builder。

如果是 embedding 相关问题，检查是否已经添加 embedding model，并在 workspace 中选择了它。

MCP 工具不可用

检查：

  • MCP 配置是否 Enabled。
  • MCP server id 是否和 agent 挂载的 id 一致。
  • Test 是否显示连接成功和工具数量。
  • HTTP MCP 的 URL 和鉴权 header 是否仍有效。
  • GitHub PAT 是否仍有目标仓库权限。

如果是 workflow 的 Vercel 5xx Logs 节点失败，检查 Vercel PAT 是否启用并通过测试。

素材库没有显示能力块

检查：

  • 当前时间和 HTTP Fetch 是固定内置工具；若缺失，检查前端版本是否与 API 一致。
  • Memory 能力是否本来就是固定能力块。
  • 自定义 MCP 是否 Enabled。
  • GitHub PAT 是否保存成功并生成 MCP server id。
  • Vercel PAT 是否被误认为 agent MCP；它用于 workflow，不出现在 Agent Builder。
  • Sub-agent 后端是否在当前环境可用。

如果工具出现在素材库但 agent 无法调用，确认已经在 Agent Builder 中把该工具挂载到当前 agent 并保存。未绑定的内置工具不会进入运行环境。

看板没有运行任务

看板只展示当前 running 任务。如果任务已经完成或失败，它不会继续留在看板上。去对应 agent 历史、eval 结果或 schedule run history 查看结束后的记录。

如果你确定任务还在运行但看不到，刷新页面，并确认任务来源是 Console 或 Feishu。

飞书群没有回复

检查：

  • 绑定状态是否 ACTIVE。
  • 飞书应用是否已发布最新权限。
  • 机器人是否加入目标群。
  • 事件订阅 callback URL 是否正确。
  • Reply policy 是否要求 @ 机器人。
  • Agent 是否能在 Web 控制台里正常运行。

记忆不生效

检查：

  • Agent 是否启用 Memory。
  • 是否选择了正确的 memory workspace。
  • 召回数量是否过低。
  • 是否配置了 embedding model。
  • Memory 页面里是否存在相关 active records。

如果 agent 持续引用旧信息，清理错误 memory record 后重新运行。

知识库流水线失败

检查：

  • Knowledge 页面是否显示已配置。
  • Source URLs 或 Sitemap URLs 是否可访问。
  • Max URLs 是否过小，导致没有选中目标页面。
  • Dry run 是否能发现 URL。
  • Run logs 里失败发生在 crawl、extract 还是 mine terms。
  • Chunks 是否仍处于 pending 或 rejected，导致可用知识不足。

定时任务没有触发

检查：

  • Task 状态是否 ACTIVE。
  • Cron 表达式是否符合预期。
  • 时区是否正确。
  • 目标 workflow、agent 或 eval experiment 是否仍存在；experiment 引用的 revisions 是否完整。
  • 手动 Run now 是否能成功。
  • ACTIVE 任务是否依赖未配置的 Vercel、GitHub、飞书或模型凭据。

建议先手动运行一次，确认依赖和输出都正常，再打开定时触发。

评测结果异常

检查：

  • Dataset revision 的 case、可信 expected label 和 rubric 是否完整。
  • Candidate/control target revision 是否选对，依赖 hash 是否仍可执行。
  • Grader-set revision 的 implementation、judge model 和 prompt revision 是否可用。
  • Attempt detail 中失败的是 target execution、grader，还是 experiment threshold。

replay_consistency 只说明输出稳定，不代表业务正确。高风险任务要结合 typed metrics、trace evidence 和人工复核。

Sub-agent Lab 无法启动

检查：

  • 当前账号是否是管理员。
  • 是否至少有一个 chat model。
  • 目标 sub-agent 是否显示 configured。
  • Start URL 是否有效。
  • Browser stream 不显示时，先看 Result 和 Trace；有些后端可执行浏览器任务，但不提供实时画面。