Diagram Design 环境医生(doctor):一次性只读诊断的运行契约与实现解析 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 仓库中诊断功能由三层文档共同定义各司其职文件角色内容定位commands/doctor.mdClaude 插件命令入口声明allowed-toolsRead / Bash / Glob要求 Agent 遵循references/doctor.md并不要把逻辑在此重写prompts/doctor.mdPi 提示词入口与命令入口等价定位SKILL.md路径、读取references/doctor.md将其视为事实来源source of truth不假设包位于当前工作目录skills/diagram-design/references/doctor.md权威诊断规范定义两种诊断模式、五项必查项目、输出契约与安全规则两个入口文件的描述均给出相同的参数提示[--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.pyscripts/verify-mermaid-import.pyscripts/verify-motion.pyscripts/lint-skin.pyscripts/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.mdcommands/import-drawio.md→references/import-drawio.mdcommands/import-mermaid.md→references/import-mermaid.mdcommands/profile.md→references/profiles.mdcommands/doctor.md→references/doctor.md验证 Pi 提示词文件存在并指向正确参照prompts/export-diagram.md→references/export.mdprompts/import-mermaid.md→references/import-mermaid.mdprompts/profile.md→references/profiles.mdprompts/doctor.md→references/doctor.md文件缺失 →fail参照路由不匹配 →fail安装态下报告维护者命令/提示词接线不适用部分或缺失的路由树不是失败。源码中这一映射被建模为ROUTING_SURFACES字典scripts/verify-doctor.pycheck_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。这条检查独立于当前目录生效正是规范中普通项目目录不是仓库路径错误这一设计的具体落地。四、输出契约人类可读 机器可读规范要求无论成功与否都输出如下内容紧凑摘要行Doctor summary: PASS|WARN|FAIL (pass_count pass, warn_count warn, fail_count fail)逐项检查清单每项一行[PASS] Python 3.11.9 found at ... [WARN] Playwright not installed ... [FAIL] Missing scripts/verify-docs-sync.pyNext actions小节仅当存在warn/fail时输出。--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、退出码 0strict 时 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_factor2PNG 像素尺寸 viewBox× 缩放系数缺少 Playwright 时规范要求向用户原样展示pip install playwrightplaywright install chromium两条命令并停止绝不自动安装——这与医生的warn语义完全一致SKILL.md解析是导入/导出/风格引导等所有命令的路由起点skills/diagram-design/SKILL.md 声明了技能的 39 种视觉类型、可换肤设计系统与references/按需加载机制安装态用户若想自查生成的 HTML 文件可运行随技能分发的 skills/diagram-design/scripts/self_check.pypython3 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创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考