doctor-diagnostics

name	doctor-diagnostics
description	系统诊断与修复：全面检查认证、配置、Gateway、安全、沙箱、工作区等 17 个诊断模块。当需要排查系统问题、执行自动修复或查看系统健康度时使用此技能。
tools	gateway, bash
metadata	{"category":"operations","emoji":"🩺","tree_id":"system/gateway","tree_group":"system","min_tier":"task_write","intent_priority":10,"intent_keywords":{"zh":["系统诊断","诊断问题","系统体检","排查问题","自动修复","doctor","健康检查","系统问题","出错了","不正常","排查"],"en":["diagnostics","system diagnosis","health check","troubleshooting","auto repair","doctor"]},"scene_hint":"全面系统诊断用此→只看运行状态用crabclaw status→具体配置问题用system-config→认证报错用auth-management"}

系统诊断技能

适用场景

用户遇到系统问题需要排查，或需要全面检查系统健康度时触发。

选择原则

场景	工具/技能
全面系统诊断	本技能
仅查看运行状态	crabclaw status CLI
配置问题	→ system-config
认证问题	→ auth-management
插件问题	→ plugins-management

一、基础诊断

crabclaw doctor

运行所有诊断模块，输出检查结果。

二、诊断选项

标志	说明
--deep	深度扫描，包含文件系统权限和完整性检查
--repair	自动修复检测到的问题
--force	允许激进修复（含破坏性操作）
--yes	自动确认所有修复提示
--non-interactive	无交互模式运行

常用组合

# 仅诊断，不修复
crabclaw doctor

# 深度诊断 + 安全修复
crabclaw doctor --deep --repair

# CI/自动化环境
crabclaw doctor --non-interactive --repair --yes

# 严重问题强制修复（谨慎使用）
crabclaw doctor --deep --repair --force --yes

三、诊断模块清单

Doctor 包含 17 个诊断模块，按顺序执行：

模块	检查内容
auth	认证状态、API Key 有效性、Token 过期
completion	Shell 补全安装与修复
config_flow	配置文件格式、必填字段、JSON5 语法
gateway_daemon_flow	Daemon 服务安装状态与运行状态
gateway_health	Gateway 健康检查（HTTP 连通性、响应时间）
gateway_services	Gateway 各子服务状态（频道、MCP、浏览器等）
install	安装完整性（二进制文件、Native Messaging Host）
legacy_config	旧版配置迁移检查
platform_notes	平台特定注意事项（macOS/Linux/Windows）
sandbox	沙箱环境可用性（Docker/原生沙箱）
security	安全配置审计（文件权限、绑定地址、TLS）
state_integrity	状态文件完整性（数据库、缓存、会话存储）
state_migrations	状态目录迁移状态
ui	UI 协议版本与前端资源新鲜度
update	更新可用性检查
workspace	工作区配置
workspace_status	工作区运行状态

四、诊断结果级别

级别	图标	说明
PASS	✓	检查通过
WARN	⚠	警告，不影响核心功能
FAIL	✗	失败，需要修复
SKIP	-	跳过（不适用于当前平台/配置）

五、常见问题与自动修复

5.1 认证类

问题	自动修复
API Key 格式无效	提示重新配置
OAuth Token 过期	刷新 Token
提供商不可达	切换到回退提供商

5.2 配置类

问题	自动修复
配置文件语法错误	提示手动修复
缺少必填字段	填入默认值
旧版格式	自动迁移

5.3 服务类

问题	自动修复
Daemon 未安装	--repair 自动安装
Gateway 端口被占用	提示更换端口
Native Host 未安装	--repair 自动安装

5.4 安全类

问题	自动修复
状态目录权限过宽	--repair 修正为 0700
Gateway 绑定 0.0.0.0	警告提示
TLS 证书过期	提示重新生成

5.5 沙箱类

问题	自动修复
Docker 未安装	提示安装或切换到原生沙箱
沙箱容器损坏	--repair 重建容器

六、与其他诊断工具的关系

工具	范围	使用场景
crabclaw doctor	全面诊断	首次安装、系统异常
crabclaw status	运行状态概览	快速查看
crabclaw health	Gateway 健康检查	连通性验证
crabclaw security audit	安全专项审计	安全审查
crabclaw plugins doctor	插件专项诊断	插件加载问题

七、CLI 命令对照

CLI 命令	说明
crabclaw doctor	标准诊断
crabclaw doctor --deep	深度诊断（含文件系统）
crabclaw doctor --repair	诊断 + 自动修复
crabclaw doctor --force --repair	含激进修复
crabclaw doctor --non-interactive --yes	无交互诊断