Doctor - 完整API参考

运行系统诊断，检查健康状态，以及故障排除。

---

聊天命令

健康检查

/doctor                                     运行所有诊断
/doctor quick                               快速健康检查
/doctor full                                完整诊断扫描
/doctor <组件>                         检查特定组件

组件检查

/doctor system                              操作系统，内存，磁盘
/doctor node                                Node.js版本，内存
/doctor network                            连接测试
/doctor api                                 API密钥验证
/doctor database                           数据库连接
/doctor channels                           频道健康

状态

/health                                    快速健康状态
/status                                    系统状态概览
/status verbose                             详细状态

---

TypeScript API参考

创建Doctor服务

import { createDoctorService } from 'clodds/doctor';

const doctor = createDoctorService({
  // 运行检查
  checks: ['system', 'node', 'network', 'api', 'database', 'channels'],

  // 阈值
  thresholds: {
    memoryWarning: 80,    // %内存使用率
    memoryCritical: 95,
    diskWarning: 80,      // %磁盘使用率
    diskCritical: 95,
    latencyWarning: 1000, // ms
    latencyCritical: 5000,
  },

  // 超时
  timeoutMs: 30000,
});

运行诊断

// 运行所有检查
const report = await doctor.runDiagnostics();

console.log(`总体：${report.status}`);  // 'healthy' | 'degraded' | 'unhealthy'
console.log(`通过检查：${report.passed}/${report.total}`);

for (const check of report.checks) {
  const icon = check.status === 'pass' ? '✓' : check.status === 'warn' ? '⚠' : '✗';
  console.log(`${icon} ${check.name}: ${check.message}`);
  if (check.details) {
    console.log(`  ${JSON.stringify(check.details)}`);
  }
}

运行特定检查

// 检查系统资源
const system = await doctor.checkSystem();

console.log(`操作系统：${system.os} ${system.version}`);
console.log(`CPU：${system.cpuUsage}%`);
console.log(`内存：${system.memoryUsage}% (${system.memoryUsedGB}/${system.memoryTotalGB} GB)`);
console.log(`磁盘：${system.diskUsage}% (${system.diskUsedGB}/${system.diskTotalGB} GB)`);

检查Node.js

const node = await doctor.checkNode();

console.log(`Node.js: ${node.version}`);
console.log(`堆：${node.heapUsed}/${node.heapTotal} MB`);
console.log(`RSS: ${node.rss} MB`);
console.log(`正常运行时间：${node.uptime} 秒`);

检查网络

const network = await doctor.checkNetwork();

console.log(`互联网：${network.internet ? '已连接' : '断开连接'}`);
console.log(`DNS: ${network.dns ? '工作正常' : '失败'}`);

for (const [endpoint, result] of Object.entries(network.endpoints)) {
  console.log(`${endpoint}: ${result.reachable ? 'OK' : '失败'} (${result.latencyMs}ms)`);
}

检查API密钥

const api = await doctor.checkApiKeys();

for (const [provider, status] of Object.entries(api)) {
  console.log(`${provider}: ${status.valid ? '有效' : '无效'}`);
  if (status.error) {
    console.log(`  错误：${status.error}`);
  }
  if (status.quota) {
    console.log(`  配额：${status.quota.used}/${status.quota.limit}`);
  }
}

检查数据库

const db = await doctor.checkDatabase();

console.log(`已连接：${db.connected}`);
console.log(`延迟：${db.latencyMs}ms`);
console.log(`版本：${db.version}`);
console.log(`表：${db.tables}`);
console.log(`大小：${db.sizeMB} MB`);

检查频道

const channels = await doctor.checkChannels();

for (const channel of channels) {
  console.log(`${channel.name}: ${channel.status}`);
  if (channel.error) {
    console.log(`  错误：${channel.error}`);
  }
  console.log(`  已连接：${channel.connected}`);
  console.log(`  最后消息：${channel.lastMessage}`);
}

格式化报告

// 获取格式化报告
const report = await doctor.runDiagnostics();
const formatted = doctor.formatReport(report);

console.log(formatted);
// 输出格式良好的诊断报告

---

诊断检查

检查	测试内容
system	操作系统，CPU，内存，磁盘
node	Node.js版本，堆，内存
network	互联网，DNS，API端点
api	API密钥有效性和配额
database	连接，延迟，架构
channels	频道连接，健康
mcp	MCP服务器连接
dependencies	npm包，版本

---

状态级别

状态	含义
healthy	所有检查通过
degraded	一些警告，仍可功能
unhealthy	严重故障，需要采取行动

检查结果

结果	含义
pass	检查成功
warn	超过警告阈值
fail	严重故障
skip	检查跳过（不适用）

---

CLI命令

# 运行所有诊断
clodds doctor

# 快速检查
clodds doctor --quick

# 检查特定组件
clodds doctor --check system

# JSON输出
clodds doctor --json

---

常见问题

高内存使用率

⚠ 内存：85%已使用

解决方案：重启服务或增加可用内存

API密钥无效

✗ Anthropic API：无效密钥

解决方案：检查.env中的ANTHROPIC_API_KEY

数据库连接失败

✗ 数据库：连接被拒绝

解决方案：检查DATABASE_URL并确保PostgreSQL正在运行

频道断开连接

⚠ Telegram：已断开连接

解决方案：检查TELEGRAM_BOT_TOKEN和网络连接

---

最佳实践

1. 定期运行 —— 日常检查健康或更改后
2. 监控趋势 —— 注意逐渐退化
3. 设置警报 —— 在不健康状态时发出警报
4. 修复警告 —— 不要等到失败
5. 部署前审查 —— 在生产变更前运行医生