用途
TinyFish Doctor 用于诊断并修复用户的 TinyFish 配置问题，覆盖 MCP 注册、认证和连接性。它主张由 TinyFish CLI 自身的 tinyfish doctor（CLI 0.22+）来负责诊断，技能本身负责运行该命令、补做 CLI 无法完成的那一项检查，并依据返回结果采取行动。资料明确要求：不要手动编辑配置文件，所有修复都应通过 CLI 完成，因为 CLI 自带备份与合并的严谨性。
主要能力
- 版本感知的 JSON 解析：doctor 在 stdout 输出 JSON，包含
schema_version、cli_version、ok_harnesses、ok_cli、checks[]、harnesses[]、repairs[]。技能描述针对 schema 版本 3；高于 3 时停止逐字段读取，改为向用户展示--pretty输出并依赖实际调用验证；低于 3 时只读checks[]和退出码。 - 双结论区分：
ok_harnesses表示用户智能体能否访问 TinyFish，ok_cli表示 CLI 自身凭据是否有效；checks[].scope（harness、cli、info）标明每项检查归属，只有 harness 作用域影响退出码。ok_cli: false且退出码为 0 是真实存在的状态，应报告为 CLI 自身凭据问题，而非智能体连接损坏。 - 退出码语义：0 表示没有 harness 检查失败（
ok_cli仍可能为 false）；1 表示有 harness 检查失败，需查看checks[]；2 表示 doctor 无法运行，stdout 为空，原因在 stderr。 - warn 处理：warn 不是失败，不影响退出码，仅表示某项内容无法检查，不应据此修复。
- 实际连通性验证（doctor 无法完成的部分）：当
harnesses[].proves_harness_reach为 false 时，需由技能补证。先统计已注册的 TinyFish 服务器数量（插件、CLI 写入条目、账号级连接器可同时注册且指向同一端点），再发起一次低成本的 search 查询，根据响应的工具命名空间判断是哪个服务器应答，并对照 doctor 报告的那个服务器判断结果含义。 - pass 的含义取决于版本：schema 2 和 3 上，API-key 注册会经实际网络测试，因此过期的 key 头已属失败并附带 connect 修复；带
proves_harness_reach: true的 pass 表示 harness 自身客户端报告了实时连接；其余 pass 仅代表配置存在，过期 key 仍可能通过而实际调用返回 401。
使用方式
无 shell 的沙箱环境（如 Claude.ai、Desktop、Cowork）无法运行 npx，应跳过命令执行，直接做第 2 步的实际连通性检查，再把第 1 步的命令交给用户自行运行。
第 1 步，运行诊断：
npx -y @tiny-fish/cli@latest doctor --harness claude-code
--pretty 仅用于向人展示列表；--debug 输出包含原始堆栈和绝对路径，不得放入报告。
第 2 步，证明智能体实际连通：先统计数据源服务器，再发起一次低成本 search，记录由哪个服务器应答，对照 doctor 报告结果判断：结果来自 doctor 报告的服务器说明端到端可用；来自其他 TinyFish 服务器则不能证明被标记的注册可用；认证报错但注册状态为 yes 说明凭据损坏；工具完全缺失说明服务器未在本次会话加载，需用户重启智能体。
第 3 步，修复：仅运行 repairs[] 中出现的命令，运行前向用户展示命令；命令以裸 tinyfish … 形式到达，无全局安装时需将开头替换为 npx -y @tiny-fish/cli@latest；保持到达顺序，auth-login 在 connect 之前。交互终端可运行：
npx -y @tiny-fish/cli@latest doctor --fix --harness claude-code
非交互环境可运行：
npx -y @tiny-fish/cli@latest doctor --fix --yes
此时只运行 unattended_safe: true 的修复，其余返回 skipped，不得把 skipped 报告为已修复。unattended_safe: false 的修复应交由用户，不要自行运行；资料指出多数修复为 false，认证登录始终如此，connect <harness> 除 Cursor 外对其他 harness 均不安全，而 Cursor 仅在 CLI 自身认证调用通过时才安全。OAuth 凭据失败没有 CLI 修复，需让用户运行 /mcp，选择 tinyfish 并登录。任何修复后需重跑第 2 步，成功以展示真实搜索结果为准。
第 4 步，仍未解决：原样附上 doctor 的 stdout JSON，它是版本化且已脱敏的，不要自行构建报告、添加字段或粘贴配置内容；退出码 2 时没有 JSON，应如实说明。随后可提供 /tinyfish:feedback 供用户提交。
适用场景
适用于用户报告 TinyFish 无法使用、MCP 注册异常、认证失败或智能体无法访问网络时的排查与修复；也适用于在升级 CLI 后确认配置仍然有效。
限制
文档针对 CLI 0.22+ 与 schema 版本 3 编写，版本不匹配时字段含义可能不同；doctor 看不见同名的其他 TinyFish 服务器注册，也无法借用 OAuth token 验证 harness 连接，因此实际连通必须由搜索调用证明；沙箱环境不能执行 npx 命令，需用户自行运行；修复仅限 repairs[] 列出且标记为可无人值守的项。