CodeWhale doctor --json：5 步快速编写机器可读的健康检查脚本

CodeWhale doctor --json5 步快速编写机器可读的健康检查脚本【免费下载链接】CodeWhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/CodeWhaleCodeWhale 是一款开源的终端编码智能体coding agent其codewhale doctor --json子命令能以纯 JSON 格式输出当前安装的完整健康状态——配置路径、密钥来源、MCP 服务器、技能目录、沙箱能力一应俱全。本文将带你用 5 个步骤把它变成 CI 巡检、定时监控和故障诊断脚本里的一块即插即用的健康检查积木。一、为什么需要机器可读的健康检查codewhale doctor默认面向人类彩色符号、换行、提示语肉眼友好但没法被程序解析。加上--json后输出变成一段可被jq等工具直接操作的 JSON 对象并且默认严格离线、只读不读取工作区.env中的凭据值不打开密钥/OAuth 文件不探测系统钥匙串、不联系任何 Provider、不启动 MCP 进程不修改任何状态目录。这意味着你可以放心地在任何环境包括 CI 容器里运行它把它当作能力探测端点来轮询。官方对响应契约的完整说明见 docs/RUNTIME_API.mdJSON 报告的生成逻辑位于 run_doctor_json结构化的诊断数据模型在 crates/tui/src/doctor.rs。二、读懂 JSON 报告的关键字段运行一次看看codewhale doctor --json报告包含 30 个顶层字段脚本中最常用的是这些完整字段表见 docs/RUNTIME_API.md字段类型脚本中的典型用途versionstring版本巡检锁定最低可用版本config_presentbool判断配置是否初始化pathsobject校验配置、会话、日志等 14 条标准路径api_key.availabilitystring凭据就绪判断只有present/not_required代表可用mcp.present/mcp.serversbool / arrayMCP 配置结构与服务器清单仅结构不启动进程skills.*.countnumber技能目录健康度统计sandbox.availablebool当前 OS 是否支持沙箱api_connectivity.statusstring恒为not_probed离线默认值提示你按需加探针capability.resolved_providerstring确认 Provider/模型路由解析结果一个典型片段{ version: 0.8.9, config_path: /Users/you/.codewhale/config.toml, config_present: true, api_key: { source: secret_store_unprobed, availability: not_probed }, sandbox: { available: true, kind: macos_seatbelt } }三、用 jq 编写第一个健康检查脚本只需三步取字段、设阈值、返回退出码。下面是一个可直接粘贴使用的巡检脚本#!/usr/bin/env bash # codewhale-health.sh — CI / 定时任务通用健康巡检 set -euo pipefail REPORT$(codewhale doctor --json) FAIL0 # 1. 版本不低于下限 MIN0.9.0 VER$(jq -r .version $REPORT) if ! [ $(printf %s\n%s\n $MIN $VER | sort -V | head -n1) $MIN ]; then echo ✗ 版本过低: $VER $MIN; FAIL1 fi # 2. 配置文件必须存在 [ $(jq -r .config_present $REPORT) true ] || { echo ✗ config.toml 缺失; FAIL1; } # 3. 凭据就绪present 或 not_required 均视为通过 AVAIL$(jq -r .api_key.availability $REPORT) case $AVAIL in present|not_required) echo ✓ 凭据状态: $AVAIL ;; *) echo ✗ 凭据不可用: $AVAIL; FAIL1 ;; esac # 4. 沙箱可用性 [ $(jq -r .sandbox.available $REPORT) true ] echo ✓ 沙箱可用 || echo ! 沙箱不可用 exit $FAIL把退出码交给 CI 或 cron即可实现绿灯放行 / 红灯告警。常见坑CI 里codewhale: command not found通常不是程序问题而是 PATH 配置问题。巡检脚本建议先command -v codewhale前置检查。四、进阶按需加活探针默认--json完全离线api_connectivity永远是not_probed。如果你的监控需要确认端点真的可达显式追加探针开关# 探测已配置的云端 Provider 端点 codewhale doctor --probe-api # 探测本地服务注意可能唤醒本地守护进程JSON 与活探针互斥会输出人类可读报告 codewhale doctor --probe-local # 探测搜索 Provider 可达性仅传输层不发查询、不读凭据 codewhale doctor --probe-search另外还有一个姊妹命令codewhale doctor --context-json输出上下文来源映射携带entries数组适合做 Prompt 上下文审计。两者的行为约束由集成测试固化见 crates/cli/tests/diagnostic_dispatch_read_only.rs。五、接入定时任务的完整模板把上面的脚本放进crontab或 CI 流水线每天巡检一次并归档结果# 每天 08:00 巡检保留 JSON 快照 30 天 0 8 * * * /opt/codewhale-health.sh /var/log/codewhale-health.log 21建议的监控指标清单版本漂移version与基线对比可配合codewhale doctor --check-updates查看最新发行版凭据健康api_key.availability从present跌落为unavailable时告警MCP 结构变化mcp.servers数量与名称 diff防止配置被误改路径完整性paths中 14 条标准路径是否存在沙箱降级sandbox.available由 true 变 false 时提示 OS 层问题。小结场景命令说明机器可读巡检codewhale doctor --json离线、只读、纯 JSON上下文来源审计codewhale doctor --context-json带entries数组端点可达性codewhale doctor --probe-api显式选择联网最新版本检查codewhale doctor --check-updates显式选择联网核心要点只有三条先离线跑--json取结构用jq设阈值断言退出码驱动告警。需要联网能力时再显式加探针参数——这既安全也让你对每一次网络访问都有完整预期。想深入了解各字段契约与响应示例推荐阅读 docs/RUNTIME_API.md 中的 Capability endpoint 章节。【免费下载链接】CodeWhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/CodeWhale创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考