用途：本技能汇总 Pireel MCP 工具各类已知错误的含义与恢复步骤。Pireel MCP 工具在用户打开的 studio 浏览器标签页中执行，经桥接转发，多数失败属于连接状态问题而非缺陷，应先诊断、不要盲目重试。
主要错误与恢复： studio_not_open（HTTP 409）：无 studio 标签页连接桥接。数据级工具（剪辑、块编辑、字幕、BYO compose/apply、plan）会自动回退到 OFFLINE MODE，直接编辑最近更新的云端项目，结果带 offline: true 与项目名；仅视频相关工具（extract_asr、analyze_visual、capture_frame、lay_out、Pireel-LLM 生成）会硬失败。此时可调用 create_browser_handoff 并用自带内嵌浏览器打开返回的 url（一次性票据，约 60 秒，勿用系统打开命令或用户默认浏览器，勿展示给用户）；无内嵌浏览器则请用户打开 https://pireel.com。 studio_tab_closed：标签页中途断开。重新打开标签页后，先调用 get_state 核实已落地的变更，再继续，避免重复变更。 tool_timeout：桥接等待超时，即时操作 60 秒、慢速生成/分析 600 秒。请用户将标签页置于前台并保持机器唤醒，调用 get_state 确认是否已完成，再重试一次。 HTTP 401：OAuth 会话缺失或过期，属传输层，无工具执行。重新登录（codex mcp login pireel，或在 Claude Code 中重连服务器）。 apply_block lint 拒绝：校验循环正常工作，按响应列出的问题仅修正对应部分，用相同 blockId/atSec 重新调用；多次仍失败可回退 add_block/edit_block（消耗 Pireel 积分）。 submit_plan 拒绝：无场景通过校验，按 plan_brief 契约重新生成 DraftPlan 后再次提交；回退 analyze_narration（消耗积分）。 instruction required：对非占位目标缺少指令，补上具体指令或确认 blockId 确为占位符。 unknown tool / invalid-params（-32602）：工具名或参数不存在，核对 tools/list，id 须来自 get_state、工具回执、list_frames 或字幕目录。
通用规则：任何变更失败后优先用 get_state 而非记忆；错误返回 isError 与 ok:false JSON，常含 hint 字段，应读取；用户拒绝已生效的变更应使用 undo（每次一步）。