排障

优先运行能隔离故障层的最小确定性检查，而不是先删缓存、删 data root 或重装全部依赖。

make dev 提示 API 一直未就绪

运行：

make backend-workspace-smoke
make backend-smoke

如果临时干净 data root 能启动，而当前 workspace data 失败，先检查持久化状态诊断，不要直接删数据。可选集成只要契约允许，就应 fail-soft。

Agent 已经生成计划，但随后出现内部协议错误

查看 task trace。Tool 可能在执行前因为 call ID、kind、availability 或 arguments 不符合 model/tool protocol 而被拒绝。

对于 direct-path object store，只要路径是用户明确给出的且 source 已授权，即使 object list 为空也可以继续检查 metadata；provider-backed relation 仍必须明确 discovery。

模型只会输出文字，不执行 Tool

生产 Agent 要求原生 tool/function calling。确认当前 transport 和模型支持结构化 tool call，并使用 设置 → 模型 → 测试 验证。

UI 里看不到某个功能

UI 通过 capability 协商。检查 GET /api/v1/bootstrap，确认 Server 是否声明对应稳定 capability。缺少已知 capability 时 UI 会主动隐藏/禁用，而不是先发请求再等待 404。

Cloudflare 报 site-dist 不存在

Wrangler deploy 前必须先构建：

Build command:  bash scripts/build-cloudflare-website.sh
Deploy command: npx wrangler deploy

wrangler.toml 发布的是 ./site-dist。如果使用 Cloudflare Workers Builds / Git integration，需要在 Worker 的 Settings → Build 中显式配置上述 Build command。Workers Builds 当前不会读取 Wrangler Custom Builds，因此仅在 wrangler.toml 增加 [build] 并不能替代这个设置。构建根目录应保持为仓库根目录，确保脚本路径和 site-dist 输出位置一致。

网站构建报 dead link

本地运行网站构建并修源 Markdown。Renderer 会校验生成后的内部链接，故意阻止带死链的站点发布。

报表能打开但底层数据不可用

大 query payload 有独立 TTL，可能比 report/artifact metadata 更早过期。ReportSpec 与 provenance 会保留，但 dataset 会显示不可用。需要最新数据时重新执行对应 evidence。