企业官网建设流程全解析

Diagram Design 环境医生（doctor）：一次性只读诊断的运行契约与实现解析

【免费下载链接】diagram-design38 editorial diagram types for Claude Code, Codex, and Pi. Self-contained HTML + SVG. No shadows. No Mermaid slop.项目地址: https://gitcode.com/GitHub_Trending/di/diagram-design

本指南围绕 diagram-design 项目中的环境诊断机制展开：当用户在 Claude Code / Codex / Pi 等 Agent 环境中执行/diagram-design:doctor（或/doctor）时，Agent 会读取本项目中的权威诊断规范 skills/diagram-design/references/doctor.md，以一次只读运行的方式检查本机对 Diagram Design 导入/导出与命令路由的"就绪度"，输出pass / warn / fail三态报告，并支持--strict与--json两种扩展模式。读完本文，你将掌握该诊断命令的完整检查清单、输出契约、安装态与维护者态两种模式的判定逻辑，以及它在scripts/verify-doctor.py中的源码级实现与 CI 验证方式，能够据此排查本地环境、理解报告语义甚至编写自己的环境自检。

一、文档脉络：从命令入口到权威参照

在 diagram-design 仓库中，诊断功能由三层文档共同定义，各司其职：

两个入口文件的描述均给出相同的参数提示[--strict] [--json]，并一致强调：诊断必须只读——不安装依赖、不修改文件、不执行破坏性 git 命令；某条检查失败时应捕获 stderr、按规范归类为warn或fail，然后继续剩余检查，而不是中断整个流程。prompts/doctor.md还特别要求"只报告本次运行中验证过的结果"（Report only verified results from this run）。

权威参照 skills/diagram-design/references/doctor.md 的触发条件覆盖三种场景：用户请求运行诊断/健康检查/首次运行排障，或用户显式调用/diagram-design:doctor、/doctor。其目标非常明确：在不改动用户文件、不安装依赖的前提下，产出一份一次性报告，确认本机对 Diagram Design 的导入/导出与命令路由的本地就绪度。同时规范强调：应从"已加载的参照"解析 Diagram Design 的安装位置，而不是从用户当前工作目录推断——普通的项目目录正是调用 doctor 的预期场所，不应被视为"仓库路径错误"。

二、两种诊断模式：安装态与维护者态

参照规范的核心设计是双模式判定，其区分依据在源码中有精确体现：

• Installed-skill mode（安装态，默认）：只检查运行时与解析到的技能安装本身，不要求维护者专属的仓库文件。
• Maintainer-checkout mode（维护者检出态）：仅当解析出的安装根目录同时包含CONTRIBUTING.md、.github/workflows/ci.yml、scripts/verify-plugin-package.py三个标记文件时启用，此时追加仓库完整性检查。

在 scripts/verify-doctor.py 中，这一判定被实现为MAINTAINER_MARKERS常量与is_maintainer_checkout()函数：

MAINTAINER_MARKERS = ( Path("CONTRIBUTING.md"), Path(".github/workflows/ci.yml"), Path("scripts/verify-plugin-package.py"), ) def is_maintainer_checkout(root: Path) -> bool: """Return whether root is a source checkout with maintainer-only surfaces.""" return all((root / marker).is_file() for marker in MAINTAINER_MARKERS)

也就是说：普通用户通过市场安装技能后，其安装目录中不存在这三个维护者文件，is_maintainer_checkout返回 False，医生自动收敛到安装态检查；只有源码检出目录才会触发完整检查。resolve_skill_file()（scripts/verify-doctor.py）则负责在"仓库/插件根目录下的skills/diagram-design/SKILL.md"与"独立技能根目录下的SKILL.md"之间二选一，确保无论安装形态如何都能定位到技能主文件。

三、五项必查项目：从运行时到路径陷阱

无论哪种模式，医生都按固定顺序执行五项检查，每项输出pass、warn、fail之一。以下按规范顺序展开，并对照源码说明其判定细节。

3.1 Python 运行时

• 先解析python3，再回退到python；
• 要求版本≥ 3.10；
• 找不到任何解释器 →fail；
• 版本低于 3.10 →fail。

源码 scripts/verify-doctor.py 中的probe_python_command()使用shutil.which按("python3", "python")顺序探测；随后通过python3 -c "import sys; print(...)"查询版本并解析major.minor.patch，(major, minor) < (3, 10)时给出fail及"升级 Python 3.10+ 后重跑"的修复建议。解析失败（非语义化版本号）同样判fail，修复建议是使用标准 CPython 安装。

3.2 Playwright 可用性（PNG 导出依赖）

• 检查当前解释器能否import playwright；
• 检查 Chromium 是否已安装（playwright install --help可证明命令存在即可；条件允许时优先检查浏览器缓存）；
• 缺失时标记为warn，并给出精确的设置提示：

  pip install playwright && playwright install chromium

• 绝不自动安装依赖。

源码 scripts/verify-doctor.py 的实现更细：先探测import playwright; print(playwright.__version__)，导入失败直接WARN；导入成功后再调用playwright.sync_api.sync_playwright解析p.chromium.executable_path，若该路径对应的文件真实存在才判PASS，否则仍然WARN——这比"命令存在即通过"更严格，能捕获"包已装但浏览器内核未下载"的常见半成品状态。

3.3 期望脚本存在性（仅维护者态）

维护者态下必须验证以下仓库脚本存在：

• scripts/verify-drawio-import.py
• scripts/verify-mermaid-import.py
• scripts/verify-motion.py
• scripts/lint-skin.py
• scripts/verify-docs-sync.py

缺失即fail；而安装态下直接报告"维护者脚本不适用"，其缺失不构成警告或失败。源码中对应EXPECTED_SCRIPTS常量与check_expected_scripts()（scripts/verify-doctor.py）。这些脚本分别守护 draw.io 导入、Mermaid 导入、可选动效契约、皮肤/调色板与文档同步，是仓库本身的质量闸门。

3.4 插件接线表面（仅维护者态）

验证 Claude 命令文件存在并指向正确的参照：

• commands/export-diagram.md→references/export.md
• commands/import-drawio.md→references/import-drawio.md
• commands/import-mermaid.md→references/import-mermaid.md
• commands/profile.md→references/profiles.md
• commands/doctor.md→references/doctor.md

验证 Pi 提示词文件存在并指向正确参照：

• prompts/export-diagram.md→references/export.md
• prompts/import-mermaid.md→references/import-mermaid.md
• prompts/profile.md→references/profiles.md
• prompts/doctor.md→references/doctor.md

文件缺失 →fail；参照路由不匹配 →fail；安装态下报告"维护者命令/提示词接线不适用"，部分或缺失的路由树不是失败。

源码中这一映射被建模为ROUTING_SURFACES字典（scripts/verify-doctor.py），check_routing_surfaces()逐项检查文件存在性，并读取文件内容确认目标参照字符串出现在正文中——只检查文件存在是不够的，路由必须真实生效。对抗性测试 scripts/test-verify-doctor.py 专门验证了这一点：把一个路由文件内容改写为"陈旧的独立说明"后，检查必须报reference mismatches并判fail。

3.5 常见路径错误

• 验证解析出的安装根目录之下存在SKILL.md——不要相对用户当前项目搜索，也不要指示用户进入维护者仓库；
• 检测 Windows 路径含空格但示例命令未加引号的情况；
• 检测命令输出中指向不存在的本地安装技能路径的引用；
• 上述均标记为warn并给出精确修复建议；
• 解析不到SKILL.md时应建议重装或更新Diagram Design，而不是让用户切进仓库检出。

源码 scripts/verify-doctor.py 的check_common_path_mistakes()同时接收root与cwd：先用resolve_skill_file()定位失败给出"重装/更新"建议；再通过platform.system()判断 Windows 平台且cwd含空格时提示使用带引号路径，例如"C:/path with spaces/diagram.html"。这条检查独立于当前目录生效，正是规范中"普通项目目录不是仓库路径错误"这一设计的具体落地。

四、输出契约：人类可读 + 机器可读

规范要求无论成功与否都输出如下内容：

1. 紧凑摘要行：

   Doctor summary: <PASS|WARN|FAIL> (<pass_count> pass, <warn_count> warn, <fail_count> fail)

2. 逐项检查清单，每项一行：

   [PASS] Python 3.11.9 found at ... [WARN] Playwright not installed ... [FAIL] Missing scripts/verify-docs-sync.py

3. Next actions小节，仅当存在warn/fail时输出。
4. --json附加 JSON 对象，包含status、counts、checks[]（每项含name、status、message、可选fix）、timestamp。

源码 scripts/verify-doctor.py 揭示了摘要与退出码的精确语义：

• FAIL存在 → 状态FAIL，退出码 1；
• 否则有WARN→ 状态WARN，非 strict 模式下退出码 0，--strict下提升为 1；
• 全PASS→ 状态PASS，退出码 0。

测试 scripts/test-verify-doctor.py 对此有专门断言：非 strict 时 WARN 语义保留（状态 WARN、退出码 0），strict 时 WARN 提升为失败退出码 1。JSON 载荷中还额外携带strict、platform（含system、release、python、cwd、root）字段，便于 CI 或日志系统做机器归因。

规范的示例输出（skills/diagram-design/references/doctor.md）如下：

Doctor summary: WARN (6 pass, 2 warn, 0 fail) [PASS] Python 3.11.9 found at /usr/bin/python3 [WARN] Playwright package not found in active interpreter [PASS] scripts/verify-drawio-import.py present ... Next actions - Install PNG export dependencies: pip install playwright && playwright install chromium - Re-run: /diagram-design:doctor --strict

注意 "Re-run with--strict" 这一模式：strict 模式下把警告升级为失败，适合接入 CI 前做一次更严苛的最终确认。

五、安全与行为规则

参照规范为医生行为划定了硬边界，这也是prompts/doctor.md与commands/doctor.md两个入口共同强调的原则：

• 只读诊断：不修改文件、不安装包、不执行破坏性 git 命令；
• 容错继续：某命令意外失败时捕获 stderr 并继续剩余检查；
• 不虚报：除非本次运行中直接验证过，否则绝不宣称某检查通过；
• 修复建议可复制：优先给出明确、可直接复制粘贴的修复命令（如pip install playwright && playwright install chromium）。

这套规则在仓库中被自动化执行：prompts/doctor.md在 front-matter 中声明参数[--strict] [--json]，并要求 Agent "只报告本次运行验证过的结果"；而.github/workflows/ci.yml（.github/workflows/ci.yml）在validate作业中显式运行python scripts/verify-doctor.py与python scripts/test-verify-doctor.py，并把结果计入 CI 汇总表，确保诊断逻辑本身始终被测试覆盖、不会悄悄腐化。

六、从医生到生产环境：诊断结果的落地闭环

诊断报告中的warn/fail并非终点，它直接关联 Diagram Design 的日常使用链路：

• Python ≥ 3.10是所有仓库脚本（导入提取器、皮肤 lint、几何校验等）的运行时底线，CI 矩阵在 Python 3.11 / 3.12 上运行全部闸门；
• Playwright只服务于 PNG 导出。完整导出规范见 skills/diagram-design/references/export.md：导出是手动触发的，默认device_scale_factor=2，PNG 像素尺寸 =viewBox× 缩放系数；缺少 Playwright 时规范要求向用户原样展示pip install playwright+playwright install chromium两条命令并停止，绝不自动安装——这与医生的warn语义完全一致；
• SKILL.md解析是导入/导出/风格引导等所有命令的路由起点，skills/diagram-design/SKILL.md 声明了技能的 39 种视觉类型、可换肤设计系统与references/按需加载机制；
• 安装态用户若想自查生成的 HTML 文件，可运行随技能分发的 skills/diagram-design/scripts/self_check.py（python3 <skill-dir>/scripts/self_check.py my-diagram.html），它无需第三方依赖即可校验无障碍 SVG 契约、单文件安全规则与动效结构，是仓库闸门（lint-skin.py、verify-motion.py）在安装目录内的蒸馏子集——这也解释了为什么医生的安装态模式不强制要求维护者脚本存在。

七、小结：一次运行，两种视角

/diagram-design:doctor的设计哲学是"最小权限、最大信息"：一次只读运行，不碰用户环境，却能把 Python 运行时、PNG 导出依赖、维护者脚本完整性、命令/提示词接线和常见路径陷阱五项就绪度一次性摸清，并通过三态状态、摘要行、Next actions 与 JSON 载荷同时服务人类排障与机器集成。无论你是通过市场安装技能后做首次环境体检，还是在源码检出里运行 CI 前检查接线完整性，都可以直接执行：

/diagram-design:doctor # 标准模式 /diagram-design:doctor --strict # 警告升级为失败 /diagram-design:doctor --json # 追加机器可读报告

诊断报告的每个结论都可在本仓库的 scripts/verify-doctor.py 与 scripts/test-verify-doctor.py 中找到对应实现与对抗性测试，这也让该命令本身成为一个可审计、可回归的健康检查范本。

【免费下载链接】diagram-design38 editorial diagram types for Claude Code, Codex, and Pi. Self-contained HTML + SVG. No shadows. No Mermaid slop.项目地址: https://gitcode.com/GitHub_Trending/di/diagram-design