用途
FiftyOne Troubleshoot 用于自动诊断和修复 FiftyOne 使用过程中的常见问题。它把用户描述的现象与内置的 Issue Index（问题索引）匹配，解释根因，给出修复方案，并在获得用户确认后执行，最后验证环境是否恢复正常。该技能设计为可持续扩充，新遇到的问题可追加到索引底部。
主要能力
技能覆盖的问题类别包括：
- 数据集持久化：数据集重启后消失（默认非持久化，Python 退出即删除）。
- App 连接：App 无法打开或未连接，可能原因包括脚本在 App 加载前退出、Windows 多进程需要
__main__保护、端口被占用、存在陈旧进程。 - 改动未保存：样本编辑与数据集级属性需要显式
.save()；批量更新使用set_values则无需.save()。 - 视频编解码：浏览器 HTML5 播放器不支持某些编解码（需 MP4/H.264、WebM 或 Ogg），可重新编码；注意重编码会覆盖磁盘文件，需先展示将被修改的确切路径并获得确认。
- macOS 打开文件数限制：通过
ulimit -n临时或永久提升。 - Notebook / 远程环境：远程 Jupyter 需设置
fo.app_config.proxy_url；Colab / Databricks 开箱即用；SSH 远程需端口转发。 - Notebook 图表不显示：需安装 plotly 及 jupyterlab-plotly 扩展并初始化。
- MongoDB 连接错误：ConnectionFailure、ServerSelectionTimeoutError、导入卡住、27017 端口错误等；排查 MongoDB 是否运行、磁盘是否写满，并给出重启内部 MongoDB、使用外部 MongoDB、重置内部 MongoDB 等方案。
- 插件与算子缺失：通过
fo.list_plugins()/ MCP 列出插件与算子，下载并启用对应插件；技能中提供了算子前缀与插件名的对应表（如@voxel51/brain/*对应@voxel51/brain）。 - No executor available：Brain、评估与标注算子在 App 需以执行器身份运行，需先
launch_app()，等待 5-10 秒后再执行算子。 - 只读数据集：通过 clone 出可写副本并设为持久化。
- 大数据集性能慢：使用视图而非全量遍历、批量更新代替逐样本保存、为高频过滤字段创建索引。
- App 显示陈旧数据：
dataset.reload()、重设 session.dataset 并 refresh，或浏览器强制刷新。 - 降级 FiftyOne：
pip install fiftyone==X.Y.Z后执行数据库迁移；降级前应导出重要数据集。 - 数据库版本不匹配：同一机器上所有 FiftyOne 安装共享同一 MongoDB 数据库，新版本写入的前向标记旧版本无法读取；提供隔离环境变量、按会话隔离、升级版本、全局配置等修复方式。
- Teams 与 OSS 客户端类型不匹配：两者数据库类型不兼容，不能共享数据库；提供隔离 OSS 环境与检查 Teams 配置的方法。
使用方式
技能定义了明确的工作流：
- 诊断：运行 Diagnostic Quick-Check，输出 Python 路径与版本、FiftyOne 版本、数据库名与 URI，并尝试列出数据集与检查连接，连接失败时给出错误信息以匹配问题索引。
- 解释：用通俗语言描述根因。
- 提出方案：展示修复内容及其会改变什么。
- 确认：询问用户“Should I apply this fix?”，等待明确确认。
- 执行：仅在批准后应用修复。
- 验证：运行 Health Check。Health Check 会创建并销毁临时测试数据集
_fo_health_check（不触碰用户数据集），验证写入、列表与连接往返是否正常。
适用场景与限制
适用于使用 FiftyOne 进行数据集管理、可视化与算子运行的过程中遇到上述常见故障时的排查与修复。技能提供了安装前提：pip install fiftyone；MCP 服务器为可选项，用于与插件相关的修复。
限制与安全约束包括：未经用户明确直接指示，绝不修改、编辑、删除或克隆用户数据集，绝不调用 fo.delete_dataset()，绝不为诊断而清空或改动数据集内容；绝不直接操作 MongoDB（不使用 pymongo、db.drop_collection() 或原始 MongoDB shell 命令）；不得静默修改 database_uri、database_name 或配置文件；向 shell 配置文件追加内容前必须展示确切改动并获得确认。环境变量或配置修复只对新进程生效，需识别并重启相关 FiftyOne 进程；pkill -f "fiftyone" 需先经用户确认。技能中的 shell 命令面向 macOS/Linux，Windows 非 WSL 环境需改用 PowerShell 等价命令或使用 WSL。