排障指南

本页按症状列出 AgentHub 官网、Desktop/Web、Hub/Edge、Runtime adapter 和 Feishu/Lark 集成的排查路径。

文档页像纯文本

如果 /zh/docs 看起来像没有正文样式：

确认浏览器访问的是 https://hub.vectorcontrol.tech/zh/docs，不是本地 file://。
打开开发者工具，检查 /_next/static/...css 是否 200。
确认静态服务没有把请求落到错误文件，例如 RSC payload 或文本文件。
清理浏览器缓存后重试。

当前文档页使用 MDX 编译为 HTML，标题、段落、列表和表格都有兜底排版。

登录后没有状态

检查：

是否通过 TokenDance ID 完成登录。
当前页面是否只是低风险官网个性化，而不是 Hub API session。
浏览器是否禁用了必要的 sessionStorage/cookie 行为。
Hub Server callback 和 relying-party 配置是否匹配。

AgentHub 不直接实现 GitHub、Google 或 Feishu 登录。

Desktop 连不上 Local Edge

检查：

Local Edge 是否启动。
Desktop 配置指向的端口是否正确。
端口是否被其他进程占用。
workspace 是否在 allowlist 中。
Edge 健康检查是否返回成功。

本地执行默认不依赖 Hub 登录。

可执行诊断：

powershell

curl.exe http://127.0.0.1:3210/health
curl.exe http://127.0.0.1:3210/v1/health
netstat -ano | findstr :3210

预期结果是健康检查返回 2xx，并且端口由 Local Edge 进程监听。如果端口被其他进程占用，先换 Edge 端口或关闭冲突进程，再同步修改 Desktop 的 Edge URL。

已知错误码

Code	典型原因	第一动作
`runtime_unavailable`	runtime CLI 未安装、未登录、adapter preset 不存在	在同一 shell 运行对应 CLI 自检，确认 provider 凭据不在浏览器里
`workspace_outside_allowlist`	Desktop/Web 请求了 Edge 未授权的路径	选择 allowlisted workspace，或修改本地 Edge policy
`permission_denied`	policy 拒绝了 write、shell、network 或 publish 动作	查看 approval policy，确认是否需要显式用户审批
`approval_rejected`	用户拒绝了 pending action	停止 run 或重新提交更小范围任务
`unauthorized_target`	Hub session 没有目标 Edge 权限	检查 project membership、device registration 和 target authorization
`target_offline`	Hub 认为目标 Edge 不在线	重连 Desktop/Edge，检查心跳和设备状态
`run_timeout`	任务范围过大或 runtime 阻塞	缩小 prompt，调整 timeout policy，保留 run id
`schema_validation_failed`	adapter 输出不是有效 AgentHub event	先修 adapter mapping，再信任 UI 状态

公开 issue 或截图里可以写 code、request id、脱敏 run id、runtime 名称和状态；不要贴 provider key、完整 prompt、真实本机绝对路径或私有文件内容。

Runtime adapter 没有输出

检查：

使用的是 mock、Claude Code、Codex 还是 OpenCode preset。
对应 CLI 是否安装并能在 shell 中直接运行。
模型 API key 是否只在服务端/本地环境变量中配置。
Run event 是否出现 run.started、run.tool.call、run.failed 等状态。
Edge 日志里是否有权限拒绝、超时或工作目录错误。

公开 SDK 包未稳定前，文档里的 adapter import path 只作为架构说明。

可执行诊断：

powershell

claude --version
codex --version
opencode --version

只检查你实际启用的 runtime。若 CLI 自检失败，先修本机安装或登录；若 CLI 自检成功但 AgentHub 没有事件，查看 Edge 日志里是否有 runtime_unavailable、permission_denied、workspace_outside_allowlist、run_timeout 或 schema_validation_failed。

系统差异

系统	注意事项
Windows	PowerShell 示例默认使用 `curl.exe`，避免被 `Invoke-WebRequest` alias 改变行为；端口检查可用 `netstat -ano`
macOS	使用 `curl` 和 `lsof -i :3210` 检查端口；确认 CLI 从同一个 shell profile 读取凭据
Linux	使用 `curl`、`ss -ltnp` 或 `lsof`；如果用容器或 WSL，确认 loopback 地址属于同一个网络命名空间

Local Edge、Desktop dev server、Hub Server 和 Web dev server 是不同进程。不要把 5173 这类 UI 端口当成 Edge API，也不要把 Hub API session 当成本地 Edge token。

Web 看不到本机文件

这是预期边界。AgentHub Web 是 Hub-only 协作面，不能绕过 Hub 直接访问 Local Edge 或本机文件系统。需要本机执行时，请使用 Desktop + Local Edge；Remote/Cloud Edge 仍在开发中。

飞书/Lark 没有响应

检查：

飞书应用是否已经发布并完成租户审批。
Webhook URL challenge、签名、加密解密是否通过。
im.message.receive_v1 是否已订阅。
群聊消息是否 @ 了机器人。
card.action.trigger 是否在 3 秒内响应。
耗时 AgentHub 工作是否异步入队。
用户是否完成 TokenDance ID 绑定。

Feishu/Lark 生产集成仍在开发中，当前文档描述的是目标边界和实现要求。

静态导出后页面 404

检查：

站点是否使用 output: "export" 构建。
static host/router 是否正确处理 /zh/docs 和 /zh/docs/...。
sitemap、robots、llms.txt 是否同步新增路由。
canonical host 是否使用 https://hub.vectorcontrol.tech。构建后可检查输出目录：

powershell

pnpm build
Test-Path .\out\zh\docs\index.html
Test-Path .\out\zh\docs\configuration.html
Test-Path .\out\llms.txt

线上排查时用 cache-busting query string，避免浏览器或 CDN 缓存旧版：

powershell

curl.exe -I "https://hub.vectorcontrol.tech/zh/docs?v=YYYYMMDDTHHMMSS"
curl.exe -I "https://hub.vectorcontrol.tech/zh/docs/configuration?v=YYYYMMDDTHHMMSS"