# Troubleshooting

## Skill 能触发但看不到 MCP Tool

重新运行工作区安装，检查工作区 `.mcp.json` 中 `cwd` 和 Server 路径是否为实际绝对路径，然后重启 Claude Code。

## `needs_token`

为 Claude Code/MCP 进程配置 `FMODE_LLM_API_KEY` 或 `LLM_API_KEY`。不要把 Key 写入仓库。

## 远程 HTTP 被阻断

API Key 会在 HTTP 连接中明文传输。优先要求网关提供 HTTPS；如果目标是明确受信的内网网关，设置 `FMODE_ALLOW_INSECURE_HTTP=true` 后重启 MCP。

## `[Unsupported Image]`

不要让 Skill Glob 或猜测历史图片。首选把商品图保存到当前项目内，并在对话中粘贴图片的显式绝对路径或相对路径。带精确 `sessionId + promptId + cwd` 的旧附件解析仅作为兼容回退。

## `submission_unknown`

请求是否已被网关接收无法确定。执行器会为当前 outputId 使用同一稳定幂等键最多自动尝试三次；耗尽后记录该项并继续后续图片，不自动切换模型。任务结束后保留 `runId`，只询问是否重试失败 outputId；确认后在原 run 续跑，不重新规划整套。

## `quality_rejected` / `unverified`

- `quality_rejected`：Gemini 发现身份漂移或明显质量问题；文件仍会保留，但不会作为主图锚点。
- `unverified`：Gemini Key、服务或结构化响应不可用；不能当作质量通过，需人工复核。

## 状态查询

当前 New API 链路同步返回图片，不再轮询旧即梦 workId。`fmode_image_set_status` 默认读取脱敏本地状态；若响应已持久化远程结果 URL，可用 `refresh=true` 恢复下载，但不会再次调用生图接口。

## 输出路径被拒绝

新输出根目录固定为调用方项目的 `输出/商品套图/`，不能由 Tool 参数改写，也不能经过符号链接写入 Skill 源码、其他运行目录或项目外路径。旧 `outputs/fmode-image-set/` 仅用于读取既有运行。