PraisonAI Doctor 健康检查与诊断系统：从 CLI 到 CI/CD 的完整实战指南

PraisonAI Doctor 健康检查与诊断系统从 CLI 到 CI/CD 的完整实战指南【免费下载链接】PraisonAIPraisonAI — Hire a 24/7 AI Workforce. Stop writing boilerplate and start shipping autonomous self-improving agents that research, plan, code, and execute tasks. Deployed in 5 lines of code with built-in memory, RAG, and support for 100 LLMs.项目地址: https://gitcode.com/GitHub_Trending/pr/PraisonAIPraisonAI Doctor 是 PraisonAI 生态内置的健康检查与诊断子系统用于快速验证 Python 环境、API Key、配置文件、工具链、数据库驱动、MCP 服务器、可观测性提供方等运行前置条件是否就绪。本文以 examples/doctor/README.md 为主线结合 praisonai-code 包的 doctor 源码实现完整讲解 CLI 命令、全局参数、退出码语义、底层执行引擎、编程式调用与 CI/CD 集成帮助你在一分钟内定位环境问题、在流水线里自动拦截坏部署。PraisonAI Doctor 是什么PraisonAI Doctor 是一套可扩展的体检框架它以Check检查项为最小单元每个检查项拥有独立 ID、标题、描述、类别Category、严重级别Severity和可选依赖以Registry注册中心统一管理检查项的定义与实现以Engine执行引擎负责运行检查、超时控制、依赖排序与报告生成最终由Formatter格式化器输出人类可读的彩色文本或机器可解析的 JSON。从源码结构看Doctor 模块位于 praisonai_code/cli/features/doctor/由以下核心文件组成文件职责models.py数据模型CheckStatus、CheckCategory、CheckSeverity、CheckResult、DoctorReport、DoctorConfigregistry.py检查项注册中心单例提供register_check装饰器与依赖解析engine.pyDoctorEngine执行引擎负责超时、依赖、失败快速短路与报告生成handler.pyDoctorHandlerCLI 入口负责参数解析、子命令映射与输出写入formatters.py文本/JSON 格式化器内置密钥脱敏redactionchecks/21 个按类别组织的检查实现模块checks/目录下的init.py 通过register_all_checks()一次性注册env_checks、config_checks、tools_checks、db_checks、mcp_checks、obs_checks、skills_checks、memory_checks、permissions_checks、network_checks、performance_checks、selftest_checks、serve_checks、lsp_checks、acp_checks、bot_checks、gateway_checks、packaging_checks、runtime_checks、runtime_migration_checks等模块这也是所有检查项都能被praisonai doctor发现并运行的机制基础。快速上手从零开始体检原文档给出的 Quick Start 是最高频的四种用法逐条说明如下# 运行全部快速健康检查默认 fast 模式不包含 --deep 深层探测 praisonai doctor # 以 JSON 格式输出便于脚本解析 praisonai doctor --json # 只运行指定的检查项逗号分隔多个 ID praisonai doctor --only python_version,openai_api_key # CI 模式自动切换为 JSON 无颜色 安静输出供流水线使用 praisonai doctor ci # 将报告写入文件结合 --json 可生成可上传的构建产物 praisonai doctor --output report.json在 handler.py 中可以看到ci子命令的底层行为它会把config.format强制设为json、no_color置为True、quiet置为True保证输出是纯净的机器可读 JSON。而--output则由 handler 负责将格式化后的报告写入指定文件路径同时--json与--format json等价见_build_config中formatjson if args.json else args.format的逻辑。CLI 子命令全览原文档列出了 15 个可用子命令它们与 models.py 中定义的CheckCategory一一对应并通过 handler.py 的_get_categories_for_subcommand完成映射命令说明对应类别Categorypraisonai doctor运行全部快速健康检查全部跳过requires_deep项praisonai doctor --version显示 Doctor 模块版本-praisonai doctor --list-checks列出所有可用检查项 ID-praisonai doctor env检查环境配置Python、包、API Keyenvironmentpraisonai doctor config校验配置文件agents.yaml 等configpraisonai doctor tools检查工具可用性toolspraisonai doctor db检查数据库驱动与连通性databasepraisonai doctor mcp检查 MCP 配置mcppraisonai doctor obs检查可观测性提供方observabilitypraisonai doctor skills检查 Agent 技能skillsskillspraisonai doctor memory检查记忆/会话存储memorypraisonai doctor permissions检查文件系统权限permissionspraisonai doctor network检查网络连通性networkpraisonai doctor performance检查模块导入耗时performancepraisonai doctor ciCI 模式JSON 输出运行全部检查全部praisonai doctor selftest最小化 Agent 干跑mock 模式selftest此外handler.py 的get_actions()还声明了bots、packaging、runtime、fix四个附加动作。其中fix是配置迁移模式它扫描当前目录或--file指定的文件下的 YAML检测已废弃的cli_backend配置并提示迁移配合--execute可自动执行迁移默认生成.bak备份可用--no-backup跳过详见 handler.py 的_run_fix_mode。全局参数详解原文档的全局参数表在实际实现中由 handler.py 的 argparse 定义并逐一映射进DoctorConfig参数说明源码细节--json以 JSON 格式输出等价于--format json且 JSON 输出强制无色--format text\|json指定输出格式默认text--output PATH/-o将报告写入文件写入成功后在非 quiet 模式下打印路径--deep启用深层探测数据库连接、网络检查、可选依赖导入等fast 模式会过滤掉requires_deepTrue的检查项--timeout SEC单个检查项超时时间秒默认10.0注意fast 模式下实际取min(timeout, 10.0)只有--deep时才允许更长超时见 handler.py--strict将警告视为失败影响退出码计算有 warning 时返回 1--quiet/-q最小化输出隐藏头部、分隔线、耗时与 Next steps--no-color禁用 ANSI 颜色非 TTY 输出时自动禁用--only IDS只运行指定检查项逗号分隔通过 registry 的filter_checks实现--skip IDS跳过指定检查项逗号分隔同上与--only可组合除此之外handler 还为各子命令准备了专用参数env子命令的--show-keys显示掩码后的 Key、--require要求必须存在的环境变量config子命令的--file、--schema打印期望的配置结构db子命令的--dsn、--provider、--read-only默认Trueperformance子命令的--budget-ms、--topci子命令的--fail-fast首个失败立即停止selftest子命令的--mock默认True与--live真实 API 调用等。退出码语义退出码是 Doctor 与脚本/流水线交互的核心契约由 models.py 的calculate_exit_code定义0全部通过允许存在警告除非开启--strict1存在失败项或--strict下存在警告2存在内部错误check 抛出的异常或超时。检查状态本身则由CheckStatus枚举定义pass、warn、fail、skip、error五种见 models.py其中skip通常用于依赖项不存在导致无法执行或可选组件未安装的场景error则代表检查执行过程本身出错如超时、异常二者语义不同在 CI 汇总时需区分对待。底层执行原理Engine Registry Formatter编程式使用与 CLI 背后的核心调用链是DoctorEngine.run() → run_checks() → run_check()见 engine.py筛选run_checks调用registry.filter_checks(only, skip, categories, deep_mode)按 ID、类别和 deep 标记过滤检查项registry.py排序registry.resolve_dependencies()基于每个检查项的dependencies字段做深度优先拓扑排序保证被依赖的检查先执行如agents_yaml_syntax依赖agents_yaml_exists执行run_check将每个检查函数提交到ThreadPoolExecutor(max_workers1)以config.timeout为上限等待结果超时会返回error状态并附 remediation 提示engine.py依赖失败短路若某检查失败其依赖链上的后续检查直接标记为skipSkipped due to failed dependency若开启fail_fast遇到首个失败即中断整个执行engine.py汇总与退出码generate_report计算ReportSummarytotal/passed/warnings/failed/skipped/errors并计算退出码engine.py。DoctorReport的 JSON 结构to_dict()包含version、timestamp、duration_ms、environmentPython 版本、可执行文件路径、OS、架构、PraisonAI 版本、工作目录、虚拟环境、results每个检查项的 id/title/category/status/message/details/remediation/duration_ms/severity/metadata、summary、exit_code、modefast/deep、filtersonly/skip——这也是ci_integration.py中解析 JSON 的字段依据。密钥脱敏输出安全设计formatters.py 内置了一组密钥正则OpenAIsk-、Anthropicsk-ant-、GoogleAIza、Tavilytvly-、xAIxai-以及*_key...、*_token...、password...等模式所有输出在渲染前都会经过redact_secrets()/redact_dict()处理默认替换为***REDACTED***仅当传入--show-keys时才显示前 4 位与后 4 位。这意味着即使某个检查在details中带出了敏感信息报告也不会泄露密钥。编程式使用Python API 详解原文档提供了 examples/doctor/basic_doctor.py演示了如何不经过 CLI、直接以 Python 代码驱动 Doctor。核心导入如下from praisonai.cli.features.doctor import DoctorEngine from praisonai.cli.features.doctor.models import DoctorConfig, CheckCategory from praisonai.cli.features.doctor.registry import get_registry from praisonai.cli.features.doctor.checks import register_all_checks from praisonai.cli.features.doctor.formatters import get_formatter需要说明的是示例文件首部的sys.path.insert(0, /Users/praison/...)是开发者本机路径实际使用时应通过pip install praisonai安装后在任意目录直接导入本仓库中 Doctor 的真实实现位于 praisonai_code 包模块结构与上述导入路径一一对应。basic_doctor.py展示了四种典型用法1. 运行全部快速检查register_all_checks()注册检查项后构造DoctorConfig(deepFalse, timeout10.0, strictFalse, quietFalse)创建DoctorEngine(config)并调用engine.run()最后用get_formatter(text, no_colorTrue)格式化打印返回report.exit_code。2. 只跑某一类别engine.run_checks(categories[CheckCategory.ENVIRONMENT])后调用engine.generate_report()等价于 CLI 的praisonai doctor env。3. 只跑指定检查 IDDoctorConfig(only[python_version, openai_api_key, os_info])传给引擎等价于praisonai doctor --only python_version,openai_api_key。4. JSON 输出DoctorConfig(only[python_version, os_info], formatjson)配合get_formatter(json)得到 JSON 字符串后再json.loads美化打印。此外示例还演示了list_available_checks()通过get_registry().get_all_checks()获取全部检查定义按类别分组并按check.id排序输出带[deep]标记的即为需要--deep才会执行的检查项。检查项示例env 类别到底查什么以 env_checks.py 为例environment类别下包含从register_check装饰器可见其 ID、标题、严重级别检查 ID作用严重级别python_versionPython 必须 ≥ 3.9CRITICALpraisonai_packagepraisonai 包已安装CRITICALpraisonaiagents_packagepraisonaiagents 包已安装CRITICALopenai_api_keyOPENAI_API_KEY已配置且格式合法HIGHanthropic_api_key/google_api_key可选 Key未设置时返回skipLOWos_info/virtual_env系统信息与虚拟环境检测INFOgit_available/docker_available/npx_available外部工具可用性Docker 未响应返回warnLOWoptional_deps可选依赖chromadb、mem0ai、litellm、praisonaiui、gradio、crawl4ai、tavily、duckduckgo_search探测需--deepINFOstale_packages检测 site-packages 中残留的praisonaiagents命名空间目录会导致包遮蔽导入错误CRITICALmodel_env_vars检查MODEL_NAME、OPENAI_MODEL_NAME、OPENAI_BASE_URL等模型相关变量INFO值得注意的是openai_api_key检查的智能降级逻辑若未设置 OpenAI Key会依次探测ANTHROPIC_API_KEY、GOOGLE_API_KEY/GEMINI_API_KEY、OllamaOLLAMA_HOST或 ollama 可执行文件找到替代提供方时返回warn而非fail提示OpenAI 是默认提供方其他提供方需显式配置全部缺失时才返回fail并建议运行praisonai setup。而optional_deps检查见 env_checks.py 的 check_optional_deps采用了每包独立 daemon 线程 单包超时上限的并发探测策略避免某个慢速导入如 chromadb阻塞整轮 deep 检查损坏的安装import 抛非 ImportError 异常会被标记为warn并给出重装建议缺失或缓慢的包仅作信息记录、不影响通过。该行为有专门的回归测试保障见 tests/unit/doctor/test_optional_deps.py其测试用例test_optional_deps_slow_import_does_not_block模拟了 chromadb 挂起 30 秒的场景验证整个检查仍会在预算时间内完成。CI/CD 集成把体检搬进流水线原文档提供的 examples/doctor/ci_integration.py 给出了三个可直接复用的流水线模式模式一CI 模式解析。用subprocess执行python -m praisonai doctor ci注意文档使用sys.executable -m praisonai即通过模块方式调用等价于praisonai命令解析 stdout 的 JSON读取summary中的total/passed/warnings/failed/skipped/errors并遍历results中status fail的项打印title、message与remediation修复建议最后以子进程的 returncode 作为整个步骤的退出码——这保证了流水线可以自动失败。模式二关键检查白名单。将python_version、praisonai_package、openai_api_key三个关键项通过--only组合执行输出passed/total统计。这是快速门禁的典型用法部署前只验证最小必要条件避免全量检查拖慢流水线。模式三报告落盘。--json --output /tmp/doctor-report.json将报告写入文件作为构建产物便于事后审计returncode in [0, 1]均视为检查已正常完成1 表示有失败项但报告有效随后从文件中读取summary展示。结合 CLI 的--fail-fast与--strict可以进一步定制流水线语义--strict让任何警告都触发失败适合对安全/密钥配置敏感的场景--fail-fast在首个失败时立即中止节省 CI 时间。完整的 CI 用法组合示例如下# 部署前门禁关键检查 严格模式 报告归档 python -m praisonai doctor --json --strict --only python_version,praisonai_package,openai_api_key --output doctor-report.json # 失败即停的全量检查 python -m praisonai doctor ci --fail-fast常见问题与建议praisonai doctor耗时过长默认 fast 模式每项超时上限为 10 秒若仍需加速可用--only收窄检查范围或用--skip跳过已知无关项如--skip docker_available,npx_available。出现error状态而非fail说明检查执行本身超时或抛异常engine.py 会返回带 remediation 的error结果可先用--timeout调大超时再排查是否为导入挂起如 chromadb或使用--deep观察optional_deps的 slow 列表。导入报错但包明明装了运行praisonai doctor env重点看stale_packages检查——它专门识别 site-packages 中缺少__init__.py的残留praisonaiagents目录这类命名空间包遮蔽是导致ImportError的常见根因。想在 CI 里看修复建议输出中的remediation字段已内置修复提示如Run praisonai setup to configure API keysci_integration.py的模式一展示了如何将其打印到流水线日志。PraisonAI Doctor 的价值在于把环境是否就绪这个模糊问题变成一组可枚举、可依赖排序、可机器解析的确定性检查。无论是本地调试praisonai doctor还是通过 basic_doctor.py 嵌入自有工具链抑或通过 ci_integration.py 接入流水线它都能以统一的报告结构与退出码契约让 Agent 环境的健康状态一目了然。【免费下载链接】PraisonAIPraisonAI — Hire a 24/7 AI Workforce. Stop writing boilerplate and start shipping autonomous self-improving agents that research, plan, code, and execute tasks. Deployed in 5 lines of code with built-in memory, RAG, and support for 100 LLMs.项目地址: https://gitcode.com/GitHub_Trending/pr/PraisonAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考