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

canvasight-troubleshooting

GitHub

诊断并修复Canvasight插件、MCP、原生组件就绪、主机桥接、守护进程及连接等问题。涵盖运行时故障、安装缓存、版本不匹配及工具传输关闭等场景，确保通过真实渲染证据验证状态。

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

触发场景

Widget卡在Opening Canvasight await_canvasight_widget_ready超时或失败出现Transport closed错误工具缺失或版本陈旧 localhost连接失败

安装

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.