Agent Skills › Niall-Young/Canvasight › canvasight-troubleshooting

canvasight-troubleshooting

GitHub

用于诊断和修复 Canvasight 插件、MCP 传输、原生组件就绪状态、宿主桥接及安装缓存等运行时问题，提供标准化排查清单与恢复步骤。

plugins/canvasight/skills/canvasight-troubleshooting/SKILL.md Niall-Young/Canvasight

触发场景

Widget 卡在 Opening 状态或超时工具调用返回 Transport closed 插件版本不匹配或行为异常原生组件未挂载或 Run 交付失败

安装

npx skills add Niall-Young/Canvasight --skill canvasight-troubleshooting -g -y

更多选项

非标准路径

npx skills add https://github.com/Niall-Young/Canvasight/tree/main/plugins/canvasight/skills/canvasight-troubleshooting -g -y

不安装直接使用

npx skills use Niall-Young/Canvasight@canvasight-troubleshooting

指定 Agent (Claude Code)

npx skills add Niall-Young/Canvasight --skill canvasight-troubleshooting -a claude-code -g -y

安装 repo 全部 skill

npx skills add Niall-Young/Canvasight --all -g -y

预览 repo 内 skill

npx skills add Niall-Young/Canvasight --list

SKILL.md

Frontmatter

{
    "name": "canvasight-troubleshooting",
    "description": "Diagnose and fix Canvasight plugin, MCP, native-widget readiness, host bridge, daemon, browser fallback, Run delivery, install, cache, or connection problems. Use when the widget is stuck on Opening Canvasight, await_canvasight_widget_ready returns timeout or failed, React never mounts, a tool falsely appears successful while the canvas is unusable, tools are missing or stale, Transport closed appears, Run does not reach the current task, localhost fails, or Canvasight behavior does not match the installed version."
}

Canvasight Troubleshooting

Use this skill for Canvasight runtime, install, native readiness, and recovery problems.

Checklist

Reproduce the normal path with the current CODEX_THREAD_ID: call open_canvasight, capture sessionId and openAttemptId, then call await_canvasight_widget_ready with both values and the same threadId.
Treat only verified fullscreen readiness with all render evidence true as success. Otherwise record attempt/session/instance identity, display mode, stage, render evidence, error, and timestamp before changing anything.
Classify the failing layer: tool discovery/live MCP transport, session/task binding, widget bootstrap/React mount, initial session API, host bridge/Run delivery, browser fallback, daemon, installed cache, or .scatter data.
If required tools are missing, call tool_search for canvasight open_canvasight await_canvasight_widget_ready render_canvasight_canvas_widget before declaring them unavailable.
If a callable Canvasight tool returns Transport closed, report canvasight_mcp_transport_closed and inspect mcp-lifecycle.log when available. If the plugin version changed while Codex Desktop was running, reload/restart the host before creating and tagging a new task; a new task alone can retain the old app-level registry. Do not substitute browser fallback.
If the result reports a missing or mismatched task id, reopen with the active task's exact CODEX_THREAD_ID.
Verify the installed source and version with codex plugin list when behavior is stale. When an install or upgrade changes the resolved version, reload/restart the Codex host, then create a new task and tag the plugin again; creating a task alone is not a sufficient refresh guarantee.
Use browser fallback only to isolate browser/daemon behavior. It cannot verify native readiness or native Run delivery.
Run the narrowest relevant automated checks, then perform the real native-host acceptance gate. Automated checks remain supporting evidence.

Never say the widget is opened, ready, or fixed based only on tool completion, resource reads, daemon health, browser fallback, build output, or smoke tests.

Read references/troubleshooting.md for symptom-specific evidence and recovery.