诊断（doctor）

mogick doctor 扫描当前 Mogick CLI 运行环境，生成结构化诊断报告。报告默认以 Markdown 格式输出；可通过 --json 或 --format json 切换为 JSON，也可通过 --export <path> 直接写入文件。默认报告包含终端兼容性探测，但不会主动执行网络请求或交互式字体确认。

诊断覆盖了从底层系统环境到上层功能模块的完整链路：操作系统与 Shell、配置文件完整性、本地模型与 Provider 配置、Memory 数据库状态、MCP 服务器连接、Skills 加载情况等。网络连通、Chat、Streaming、usage 等能力检测需要通过 --check-network 显式启用。每次诊断结果都是一个可复现的排查快照，建议在提问技术问题时附上报告内容。

用法

mogick doctor                          # 运行诊断，终端输出 Markdown 报告
mogick doctor --json                   # 运行诊断，终端输出 JSON 报告
mogick doctor --format json            # 同上，通过 --format 切换输出格式
mogick doctor --export ./report.md      # 将原始报告写入指定文件
mogick doctor --check-network          # 额外探测网络服务可达性
mogick doctor --check-terminal-font    # 交互检查字体与终端网格
mogick doctor --all                    # 同时执行网络与交互式终端检查

选项

选项	说明
--json	将输出格式切换为 JSON（与 --format json 等效）
--format md|json	指定输出格式：md（Markdown，默认）或 json
--export <path>	将原始报告写入指定文件；路径必填
--check-network	探测网络服务（如 API 端点）的可达性
--check-terminal-font	交互确认 Unicode 边框、中文宽度和状态符号
--all	同时执行网络探测和交互式终端/字体检查
--verbose	提高输出详细程度，显示更多诊断细节
--logs-path <file>	将诊断日志写入指定文件

输出格式

诊断报告默认以 Markdown 格式在终端渲染输出，可通过 --json 或 --format json 切换为 JSON 格式。JSON 输出的顶层结构为：

字段	说明
schema_version	报告格式版本
generated_at	生成时间戳
request	诊断请求参数（verbose、check_network）
summary	汇总状态（status、warning_count、error_count）
sections	诊断模块数组，每个模块含 id、title、status、items、details

每个状态值可能为 ok（正常）、warn（警告）、error（错误）、exception（异常）。

检查项

一次完整的诊断覆盖以下模块：

section id	检测内容
runtime	操作系统、架构、Go 版本、CLI 版本、工作目录、可执行文件路径
config	全局与项目级 config.json 路径及是否存在
models	本地模型与 Provider 配置（模型列表、Provider 类型和数量）
memory	sessions.sqlite 路径、是否存在、文件大小
mcp	各 MCP 服务器名称、类型、Transport、启用状态
skills	Skills 目录及文件状态
auth	认证 Token 状态及过期时间
terminal	stdin/stdout、TERM、终端尺寸、UTF-8 locale 与 Windows VT 能力

没有配置任何 MCP server 是正常空状态，不计为警告。报告摘要的 warning 数量与 “Needs attention” 列表按同一检查项统计。

网络检查

--check-network 会执行真实网络请求，报告中会额外出现 network 检查项。排查模型连接问题时，重点看这些字段：

字段或检查项	含义
base_url	实际用于请求模型服务的 API base
server_url	Provider 原始服务地址；llm-store 场景可能不同于 base_url
provider	当前生效的 Provider 类型
timeout_seconds	本次 doctor 网络探测的总超时
server_reachable	对 base_url 的基础 HTTP 可达性检查
chat_completion	非流式 Chat Completions 请求是否成功
chat_usage	非流式响应是否返回 usage 元数据
chat_tool_call	模型是否能按工具调用格式返回结果
stream_response	流式响应是否能完成并返回文本
stream_usage	流式响应是否返回 usage 元数据
embeddings	配置了 embedding 模型时，检查 embedding 请求
rerank	配置了 rerank 模型时，检查 rerank 请求
llm_store_modelinfo	llm-store 场景下拉取远端模型目录

usage 元数据中常见字段包括 prompt_tokens、completion_tokens、total_tokens 和 cached_tokens。如果 chat_completion 成功但 chat_usage 或 stream_usage 警告，通常说明模型服务可用，但未返回完整 token 用量信息。

示例

最基础的用法是直接执行诊断，终端输出 Markdown 格式报告。

mogick doctor

切换为 JSON 格式输出，适合自动化工具解析。

mogick doctor --json

导出原始报告到文件，适合 CI 流水线归档或团队间分享。

mogick doctor --export ./mogick-doctor-report.md

在 CI 环境中获取详细诊断信息，并结合网络探测。

mogick doctor --verbose --check-network

如需在自动化脚本中解析诊断结果，可直接处理 JSON 输出。

mogick doctor --json | jq '.sections[] | select(.status == "error")'