diagram-design 多宿主插件发布架构ADR 0008 单一插件根与同步版本门禁实践【免费下载链接】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-designDiagram Design 同时服务 Claude Code、Codex、Pi 与 Factory Droid 四个 AI 宿主而本文要解析的 ADR 0008acceptedv2.5.14正是这套多宿主打包与发布体系的架构基石它规定每个原生宿主只携带最小的原生清单 marketplace 元数据所有 marketplace 统一解析到仓库根目录让skills/diagram-design/与commands/被全部宿主共享而不产生任何副本。读完本文你将理解该 ADR 的决策动因、清单字段契约、同步版本门禁的校验逻辑、新宿主接入的 bootstrap 特例以及如何在 Claude Code / Codex / Factory Droid 中完成安装与更新。1. 背景多宿主时代的发布困境Diagram Design 是一个以单一 Skill 同时面向多个 AI 编程宿主分发的项目Claude Code、Codex、Factory Droid以及通过标准skills/目录发现的 Pi。多宿主分发天然会面临两条歧路依赖翻译兜底Factory Droid 本身可以翻译 Claude 的插件布局但依赖这一兜底意味着 Droid 的安装方式既没有文档化也没有进入包版本门禁package-version gate的管控范围——版本发布时无法验证 Factory 侧是否真的可用、是否真的升级。逐宿主复制把 Skill 或 commands 分别拷贝进各宿主专属目录会造成多个事实来源sources of truth。同一份行为在不同宿主上漂移、修 bug 时漏改某一份都是必然结局。此外还有一个更隐蔽的诉求行为必须单一来源single-sourced。Diagram Design 的 Skill 本体、commands如export-diagram.md、import-drawio.md应当是仓库中唯一的一份所有宿主引用同一份而不是各自维护一份。2. 决策最小原生清单 单一插件根ADR 0008 给出的答案是分而治之 归一化Claude、Codex、Factory 各自接收其宿主所需要的最小的原生清单native manifest与 marketplace 元数据每一个 marketplace 都解析到仓库根目录三个宿主在根目录下复用同一个skills/diagram-design/与commands/不产生任何复制。Pi 继续使用同一个根级包面root package surfaces。这句话可以拆成三层清单按宿主定制但保持最小每个宿主的插件清单只包含该宿主识别的字段不强行统一成一个万能清单marketplace 全部指向仓库根三个 marketplace 文件中的插件 source 都指向.仓库根目录于是所有宿主共享根下的同一份内容Pi 走标准目录Pi 通过仓库标准skills/包目录发现 SkillREADME 中明确说明Pi discovers it through the repos standardskills/package directory与其余宿主看到的是同一份文件。2.1 仓库中的清单与 marketplace 布局从仓库根目录看这套布局清晰可辨宿主原生清单marketplace 元数据插件源指向Claude.claude-plugin/plugin.json.claude-plugin/marketplace.json./仓库根Codex.codex-plugin/plugin.json.agents/plugins/marketplace.json{source:local,path:./}Factory.factory-plugin/plugin.json.factory-plugin/marketplace.json./仓库根而共享面则始终是仓库根下的两份内容skills/diagram-design/Skill 本体SKILL.md references/参考文档 scripts/辅助脚本 assets/模板commands/插件命令doctor.md、export-diagram.md、import-drawio.md、import-mermaid.md、profile.md。验证器代码也印证了这一布局verify-plugin-package.py中硬编码了MANIFEST_PATHS {Claude: .claude-plugin/plugin.json, Codex: .codex-plugin/plugin.json, Factory: .factory-plugin/plugin.json}与三份 marketplace 路径并检查skills/diagram-design/SKILL.md和commands/目录必须存在于这个被所有 marketplace 共同指向的插件根中——从源码结构看单一插件根不是一个口头约定而是被校验脚本强制执行的布局事实。3. 三份原生清单共享身份元数据的字段契约最小清单不等于内容随意。ADR 0008 明确规定三份原生清单必须携带完全相同的共享身份元数据identity、description、version、author、repository、license、keywords。verify-plugin-package.py中的SHARED_MANIFEST_FIELDS元组给出了这份契约的精确字段集合SHARED_MANIFEST_FIELDS ( name, description, version, author, homepage, repository, license, keywords, )校验逻辑verify_manifest_identity以 Claude 清单为参照系逐字段比对其余清单任一字段不一致即报错{label} manifest {field!r} must match Claude。仓库当前版本2.6.5下三份plugin.json的共享字段确实逐字一致例如name:diagram-designversion:2.6.5author:{name: Cathryn Lavery, url: ...}license:MITkeywords:[diagrams, svg, architecture, flowchart, visualization, editorial, drawio, mermaid, import, animation, semantic-patterns]Codex 清单是唯一超出共享面的它额外携带skills: ./skills/与interfacedisplayName、category、capabilities、defaultPrompt、brandColor 等 Codex 生态需要的展示与能力声明。这正是最小原生清单的体现——各宿主只加载自己认识的字段公共身份字段统一、宿主特有字段按需存在。4. 同步版本门禁验证器如何拒绝漂移ADR 0008 的核心保障是 scripts/verify-plugin-package.py 实现的包版本门禁。它以一个 git refbase ref如HEAD或发布基线为参照执行以下几类检查任何一项失败都会让main()以非零退出码失败并打印FAIL plugin package4.1 版本必须同步且必须前进verify_versions的规则三份清单的version必须完全一致否则报plugin manifest versions must match: Claude..., Codex..., Factory...每个版本必须是严格MAJOR.MINOR.PATCH语义化版本正则SEMVER全匹配1.2这类不完整版本会被拒绝相对 base ref只要该清单在基线处存在当前版本就必须严格大于基线版本否则报must increase relative to base-ref: 1.2.3 - 1.2.3若 base ref 处不存在任何已同步清单base_manifest_count 0则无法证明包版本前进过同样判失败。4.2 身份字段零漂移verify_manifest_identity以 Claude 为参照逐字段比对共享身份字段见第 3 节防止某一次发布只改了 Claude 清单而漏改其他宿主。4.3 marketplace 路径安全与一致性verify_marketplaces对三份 marketplace 文件做严格检查这部分直接落实 ADR 中拒绝不安全 marketplace 路径的要求插件源必须是本地相对路径source必须等于././或以./开头含..、绝对路径、或解析后逃出 marketplace 根目录的路径一律拒绝resolve_local_path用Path.resolve()is_relative_to双重确认Codex 条目有专属契约source必须是{source: local, path: ./}形态policy.installation必须为AVAILABLE、policy.authentication必须为ON_INSTALL且必须提供非空categoryFactory 的 source 必须是原生本地路径字符串测试test-plugin-package.py专门构造了把 Factory source 改成{source:local,path:./}的用例验证器会以must be a non-empty local path string拒绝——这是因为 Factory 走 Claude 翻译兜底时不需要本地 source而 ADR 的意图恰恰是让 Factory 拥有原生路径三个 marketplace 必须打包同一个插件根解析出的 claude_root / codex_root / factory_root 必须全部相等否则报must package the same plugin root打包面必须完整插件根下必须存在skills/diagram-design/SKILL.md与至少一个commands/*.md缺任一即失败对应测试packaged skill is missing、packaged commands are missing。4.4 SKILL.md 元数据版本跟踪verify_skill_metadata_version是一个容易踩坑的隐性门禁SKILL.md frontmatter 的metadata.version必须跟踪清单版本的MAJOR.MINOR。例如当前清单为 2.6.5 时SKILL.md 的 frontmatter 必须是metadata: version: 2.6。注释中记载了这条规则的历史原因清单由脚本统一 bump而 SKILL.md 的 metadata 是手工维护的曾出现过 2.4 对 2.5.0 清单的静默漂移直到合流清扫才被发现。为此验证器实现了一个不依赖 YAML 运行时的 frontmatter 解析器parse_frontmatter_metadata_version只接受该包使用的映射子集遇到重复键、未闭合引号、非法转义、越界 Unicode 转义等一律fail closed。5. 同步版本升级bump-plugin-version.py既然版本必须同步就不该靠手工改三份 JSON。scripts/bump-plugin-version.py 把同步 bump固化成单一入口python3 scripts/bump-plugin-version.py # patch2.6.5 → 2.6.6 python3 scripts/bump-plugin-version.py --minor # minor2.6.5 → 2.7.0 python3 scripts/bump-plugin-version.py --major # major2.6.5 → 3.0.0其行为要点先读取三份清单并断言版本已同步若发现Claude2.6.5, Codex2.6.6这类漂移直接抛出PackageVersionError(manifest versions are not synchronized)拒绝写入在同步前提下按major/minor/patch计算新版本并一次性写回三份清单返回新版本号成功后输出Updated Claude, Codex, and Factory plugin manifests to version。test-plugin-package.py的test_bumper验证了三个档位的 bump 结果1.2.3→ patch1.2.4/ minor1.3.0/ major2.0.0并确认漂移清单会被拒之门外。注意bump 脚本只改版本号SKILL.md 的metadata.versionMAJOR.MINOR仍由验证器把关。6. Bootstrap 特例新宿主接入的准入条件ADR 0008 为某个原生清单首次被纳入跟踪设计了一个边界情况一个刚被纳入跟踪的原生清单在 base ref 处可能并不存在例如 Factory 清单是本次发布才新增的。此时相对 base ref 必须前进无从谈起但门禁不能因此放水。ADR 给出的规则是仅在 bootstrap 期间新跟踪的原生清单可以缺席于 base ref但其当前元数据与版本必须与已确立的清单established manifests一致且这些已确立的清单必须前进。test-plugin-package.py用include_factoryFalse的夹具精确复现了这一场景合法 bootstrap已有 Claude/Codex 清单1.2.3 → 1.2.4新增 Factory 清单且版本同为 1.2.4、字段与 Claude 一致 → 通过OK: synchronized Factory bootstrap accepted无版本前进的 bootstrap已有清单未 bump仅新增 Factory 清单 → 报must increase失败字段漂移的 bootstrap新增 Factory 清单版本对齐但 description 被改 → 报must match Claude失败清单被删除任何已跟踪清单缺失 → 报could not read失败。由此可见bootstrap 不是新宿主免检入场券而是对齐既有清单 既有清单必须按正常节奏 bump的受控例外。7. 后果与发布模型ADR 0008 的 Consequences 部分定义了该决策的长期约束每个原生宿主都有显式的安装路径而行为仍单一来源安装方式可查、可测、可进门禁但 Skill 与 commands 只有一份新增宿主是一套完整的准入清单需要原生元数据native metadata、包门禁覆盖package-gate coverage、文档以及一次同步版本 bump——永远不构成复制 Skill 或命令面的理由Git 型 Factory 安装由 marketplace 提交驱动更新Droid 按 commit 而非清单显示版本跟踪插件因此同步清单版本的角色是发布元数据 评审门禁release metadata and a review gate真正的更新传播靠 marketplace 的新提交。这与 README 中的安装指令相互印证Factory Droid 侧执行droid plugin marketplace update diagram-design后再droid plugin update diagram-designdiagram-design --scope user即可拉取合入的更新并开启新会话生效。8. 各宿主安装与更新实操结合 README.md 中的安装章节四个宿主的使用路径如下Claude Code通过 marketplace 添加并安装/plugin marketplace add cathrynlavery/diagram-design /plugin install diagram-designdiagram-design随后在/plugin的 Marketplaces 面板中为 diagram-design 开启Enable auto-updateClaude Code 默认对第三方 marketplace 关闭自动更新之后会在启动后后台刷新 marketplace 与已装插件并按提示/reload-plugins或于下一会话加载更新。Codexcodex plugin marketplace add cathrynlavery/diagram-design codex plugin add diagram-designdiagram-designCodex 在启动时刷新已配置的 Git marketplace如需立即拉取执行codex plugin marketplace upgrade diagram-design并开启新会话。Factory Droiddroid plugin marketplace add https://github.com/cathrynlavery/diagram-design droid plugin install diagram-designdiagram-design --scope userDroid 按 commit 跟踪 Git 插件合入新版本后执行droid plugin marketplace update diagram-design、再droid plugin update diagram-designdiagram-design --scope user并开启新会话。Pi无需 marketplace直接经由仓库标准skills/包目录发现 skills/diagram-design/ 这份共享 Skill。迁移提醒README 中的一次性迁移说明已通过独立npx skills add安装的副本不会自动跟随 Codex marketplace——需移除独立副本后改用 marketplace 安装Cowork 个人副本同理需卸载后改从组织 marketplace 安装此后每次版本 bump 都会沿各客户端的原生更新路径流动。这一迁移路径之所以成立正是 ADR 0008单一插件根 原生更新路径设计的直接收益。9. 门禁的对抗性测试scripts/test-plugin-package.py 是这套门禁的对抗性回归套件覆盖了本文提到的几乎每个失败模式有效同步 bump 通过、缺 bump 拒绝、双清单版本漂移拒绝、Factory 单独漂移拒绝、非严格 semver 拒绝、marketplace 目标缺失拒绝、Factory 非原生 source 拒绝、共享命令面缺失拒绝、bootstrap 合法/非法场景以及 SKILL.md frontmatter 的一系列畸形输入重复 metadata.version、正文中的 version 行不算数、未闭合引号、非法转义、\U00110000越界转义等。任何一条规则被悄悄放宽都会被这些用例当场戳穿。10. 小结ADR 0008 用一句话概括每个宿主一份最小的原生清单与 marketplace 元数据所有 marketplace 指向同一个仓库根行为永远只有一份。它的工程价值体现在三个层面布局上清单目录.claude-plugin/、.codex-plugin/、.factory-plugin/与共享面skills/、commands/职责分明从文件结构即可读出发布策略流程上bump-plugin-version.py保证三份清单版本同步verify-plugin-package.py保证身份、路径、打包面与 SKILL.md 元数据零漂移bootstrap 特例为新宿主接入提供了受控通道发布上Git 型宿主Factory按提交更新同步清单版本退化为发布元数据与评审门禁真正驱动用户更新的是 marketplace 的新提交。对于任何一个 Skill 分发到多个 AI 宿主的项目这份 ADR 与其配套脚本、测试构成了一套可以直接借鉴的完整方案最小原生清单、单一插件根、同步版本门禁、受控 bootstrap。延伸阅读仓库中其余 ADR 记录着同一套治理思路的姊妹决策例如 ADR 0001静态输出默认 唯一受审控的 motion 控制器它们共同勾勒出 Diagram Design 把行为收敛到单一来源、用脚本与测试封死漂移的工程哲学。【免费下载链接】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），仅供参考 diagram-design 多宿主插件发布架构：ADR 0008 单一插件根与同步版本门禁实践
diagram-design 多宿主插件发布架构ADR 0008 单一插件根与同步版本门禁实践【免费下载链接】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-designDiagram Design 同时服务 Claude Code、Codex、Pi 与 Factory Droid 四个 AI 宿主而本文要解析的 ADR 0008acceptedv2.5.14正是这套多宿主打包与发布体系的架构基石它规定每个原生宿主只携带最小的原生清单 marketplace 元数据所有 marketplace 统一解析到仓库根目录让skills/diagram-design/与commands/被全部宿主共享而不产生任何副本。读完本文你将理解该 ADR 的决策动因、清单字段契约、同步版本门禁的校验逻辑、新宿主接入的 bootstrap 特例以及如何在 Claude Code / Codex / Factory Droid 中完成安装与更新。1. 背景多宿主时代的发布困境Diagram Design 是一个以单一 Skill 同时面向多个 AI 编程宿主分发的项目Claude Code、Codex、Factory Droid以及通过标准skills/目录发现的 Pi。多宿主分发天然会面临两条歧路依赖翻译兜底Factory Droid 本身可以翻译 Claude 的插件布局但依赖这一兜底意味着 Droid 的安装方式既没有文档化也没有进入包版本门禁package-version gate的管控范围——版本发布时无法验证 Factory 侧是否真的可用、是否真的升级。逐宿主复制把 Skill 或 commands 分别拷贝进各宿主专属目录会造成多个事实来源sources of truth。同一份行为在不同宿主上漂移、修 bug 时漏改某一份都是必然结局。此外还有一个更隐蔽的诉求行为必须单一来源single-sourced。Diagram Design 的 Skill 本体、commands如export-diagram.md、import-drawio.md应当是仓库中唯一的一份所有宿主引用同一份而不是各自维护一份。2. 决策最小原生清单 单一插件根ADR 0008 给出的答案是分而治之 归一化Claude、Codex、Factory 各自接收其宿主所需要的最小的原生清单native manifest与 marketplace 元数据每一个 marketplace 都解析到仓库根目录三个宿主在根目录下复用同一个skills/diagram-design/与commands/不产生任何复制。Pi 继续使用同一个根级包面root package surfaces。这句话可以拆成三层清单按宿主定制但保持最小每个宿主的插件清单只包含该宿主识别的字段不强行统一成一个万能清单marketplace 全部指向仓库根三个 marketplace 文件中的插件 source 都指向.仓库根目录于是所有宿主共享根下的同一份内容Pi 走标准目录Pi 通过仓库标准skills/包目录发现 SkillREADME 中明确说明Pi discovers it through the repos standardskills/package directory与其余宿主看到的是同一份文件。2.1 仓库中的清单与 marketplace 布局从仓库根目录看这套布局清晰可辨宿主原生清单marketplace 元数据插件源指向Claude.claude-plugin/plugin.json.claude-plugin/marketplace.json./仓库根Codex.codex-plugin/plugin.json.agents/plugins/marketplace.json{source:local,path:./}Factory.factory-plugin/plugin.json.factory-plugin/marketplace.json./仓库根而共享面则始终是仓库根下的两份内容skills/diagram-design/Skill 本体SKILL.md references/参考文档 scripts/辅助脚本 assets/模板commands/插件命令doctor.md、export-diagram.md、import-drawio.md、import-mermaid.md、profile.md。验证器代码也印证了这一布局verify-plugin-package.py中硬编码了MANIFEST_PATHS {Claude: .claude-plugin/plugin.json, Codex: .codex-plugin/plugin.json, Factory: .factory-plugin/plugin.json}与三份 marketplace 路径并检查skills/diagram-design/SKILL.md和commands/目录必须存在于这个被所有 marketplace 共同指向的插件根中——从源码结构看单一插件根不是一个口头约定而是被校验脚本强制执行的布局事实。3. 三份原生清单共享身份元数据的字段契约最小清单不等于内容随意。ADR 0008 明确规定三份原生清单必须携带完全相同的共享身份元数据identity、description、version、author、repository、license、keywords。verify-plugin-package.py中的SHARED_MANIFEST_FIELDS元组给出了这份契约的精确字段集合SHARED_MANIFEST_FIELDS ( name, description, version, author, homepage, repository, license, keywords, )校验逻辑verify_manifest_identity以 Claude 清单为参照系逐字段比对其余清单任一字段不一致即报错{label} manifest {field!r} must match Claude。仓库当前版本2.6.5下三份plugin.json的共享字段确实逐字一致例如name:diagram-designversion:2.6.5author:{name: Cathryn Lavery, url: ...}license:MITkeywords:[diagrams, svg, architecture, flowchart, visualization, editorial, drawio, mermaid, import, animation, semantic-patterns]Codex 清单是唯一超出共享面的它额外携带skills: ./skills/与interfacedisplayName、category、capabilities、defaultPrompt、brandColor 等 Codex 生态需要的展示与能力声明。这正是最小原生清单的体现——各宿主只加载自己认识的字段公共身份字段统一、宿主特有字段按需存在。4. 同步版本门禁验证器如何拒绝漂移ADR 0008 的核心保障是 scripts/verify-plugin-package.py 实现的包版本门禁。它以一个 git refbase ref如HEAD或发布基线为参照执行以下几类检查任何一项失败都会让main()以非零退出码失败并打印FAIL plugin package4.1 版本必须同步且必须前进verify_versions的规则三份清单的version必须完全一致否则报plugin manifest versions must match: Claude..., Codex..., Factory...每个版本必须是严格MAJOR.MINOR.PATCH语义化版本正则SEMVER全匹配1.2这类不完整版本会被拒绝相对 base ref只要该清单在基线处存在当前版本就必须严格大于基线版本否则报must increase relative to base-ref: 1.2.3 - 1.2.3若 base ref 处不存在任何已同步清单base_manifest_count 0则无法证明包版本前进过同样判失败。4.2 身份字段零漂移verify_manifest_identity以 Claude 为参照逐字段比对共享身份字段见第 3 节防止某一次发布只改了 Claude 清单而漏改其他宿主。4.3 marketplace 路径安全与一致性verify_marketplaces对三份 marketplace 文件做严格检查这部分直接落实 ADR 中拒绝不安全 marketplace 路径的要求插件源必须是本地相对路径source必须等于././或以./开头含..、绝对路径、或解析后逃出 marketplace 根目录的路径一律拒绝resolve_local_path用Path.resolve()is_relative_to双重确认Codex 条目有专属契约source必须是{source: local, path: ./}形态policy.installation必须为AVAILABLE、policy.authentication必须为ON_INSTALL且必须提供非空categoryFactory 的 source 必须是原生本地路径字符串测试test-plugin-package.py专门构造了把 Factory source 改成{source:local,path:./}的用例验证器会以must be a non-empty local path string拒绝——这是因为 Factory 走 Claude 翻译兜底时不需要本地 source而 ADR 的意图恰恰是让 Factory 拥有原生路径三个 marketplace 必须打包同一个插件根解析出的 claude_root / codex_root / factory_root 必须全部相等否则报must package the same plugin root打包面必须完整插件根下必须存在skills/diagram-design/SKILL.md与至少一个commands/*.md缺任一即失败对应测试packaged skill is missing、packaged commands are missing。4.4 SKILL.md 元数据版本跟踪verify_skill_metadata_version是一个容易踩坑的隐性门禁SKILL.md frontmatter 的metadata.version必须跟踪清单版本的MAJOR.MINOR。例如当前清单为 2.6.5 时SKILL.md 的 frontmatter 必须是metadata: version: 2.6。注释中记载了这条规则的历史原因清单由脚本统一 bump而 SKILL.md 的 metadata 是手工维护的曾出现过 2.4 对 2.5.0 清单的静默漂移直到合流清扫才被发现。为此验证器实现了一个不依赖 YAML 运行时的 frontmatter 解析器parse_frontmatter_metadata_version只接受该包使用的映射子集遇到重复键、未闭合引号、非法转义、越界 Unicode 转义等一律fail closed。5. 同步版本升级bump-plugin-version.py既然版本必须同步就不该靠手工改三份 JSON。scripts/bump-plugin-version.py 把同步 bump固化成单一入口python3 scripts/bump-plugin-version.py # patch2.6.5 → 2.6.6 python3 scripts/bump-plugin-version.py --minor # minor2.6.5 → 2.7.0 python3 scripts/bump-plugin-version.py --major # major2.6.5 → 3.0.0其行为要点先读取三份清单并断言版本已同步若发现Claude2.6.5, Codex2.6.6这类漂移直接抛出PackageVersionError(manifest versions are not synchronized)拒绝写入在同步前提下按major/minor/patch计算新版本并一次性写回三份清单返回新版本号成功后输出Updated Claude, Codex, and Factory plugin manifests to version。test-plugin-package.py的test_bumper验证了三个档位的 bump 结果1.2.3→ patch1.2.4/ minor1.3.0/ major2.0.0并确认漂移清单会被拒之门外。注意bump 脚本只改版本号SKILL.md 的metadata.versionMAJOR.MINOR仍由验证器把关。6. Bootstrap 特例新宿主接入的准入条件ADR 0008 为某个原生清单首次被纳入跟踪设计了一个边界情况一个刚被纳入跟踪的原生清单在 base ref 处可能并不存在例如 Factory 清单是本次发布才新增的。此时相对 base ref 必须前进无从谈起但门禁不能因此放水。ADR 给出的规则是仅在 bootstrap 期间新跟踪的原生清单可以缺席于 base ref但其当前元数据与版本必须与已确立的清单established manifests一致且这些已确立的清单必须前进。test-plugin-package.py用include_factoryFalse的夹具精确复现了这一场景合法 bootstrap已有 Claude/Codex 清单1.2.3 → 1.2.4新增 Factory 清单且版本同为 1.2.4、字段与 Claude 一致 → 通过OK: synchronized Factory bootstrap accepted无版本前进的 bootstrap已有清单未 bump仅新增 Factory 清单 → 报must increase失败字段漂移的 bootstrap新增 Factory 清单版本对齐但 description 被改 → 报must match Claude失败清单被删除任何已跟踪清单缺失 → 报could not read失败。由此可见bootstrap 不是新宿主免检入场券而是对齐既有清单 既有清单必须按正常节奏 bump的受控例外。7. 后果与发布模型ADR 0008 的 Consequences 部分定义了该决策的长期约束每个原生宿主都有显式的安装路径而行为仍单一来源安装方式可查、可测、可进门禁但 Skill 与 commands 只有一份新增宿主是一套完整的准入清单需要原生元数据native metadata、包门禁覆盖package-gate coverage、文档以及一次同步版本 bump——永远不构成复制 Skill 或命令面的理由Git 型 Factory 安装由 marketplace 提交驱动更新Droid 按 commit 而非清单显示版本跟踪插件因此同步清单版本的角色是发布元数据 评审门禁release metadata and a review gate真正的更新传播靠 marketplace 的新提交。这与 README 中的安装指令相互印证Factory Droid 侧执行droid plugin marketplace update diagram-design后再droid plugin update diagram-designdiagram-design --scope user即可拉取合入的更新并开启新会话生效。8. 各宿主安装与更新实操结合 README.md 中的安装章节四个宿主的使用路径如下Claude Code通过 marketplace 添加并安装/plugin marketplace add cathrynlavery/diagram-design /plugin install diagram-designdiagram-design随后在/plugin的 Marketplaces 面板中为 diagram-design 开启Enable auto-updateClaude Code 默认对第三方 marketplace 关闭自动更新之后会在启动后后台刷新 marketplace 与已装插件并按提示/reload-plugins或于下一会话加载更新。Codexcodex plugin marketplace add cathrynlavery/diagram-design codex plugin add diagram-designdiagram-designCodex 在启动时刷新已配置的 Git marketplace如需立即拉取执行codex plugin marketplace upgrade diagram-design并开启新会话。Factory Droiddroid plugin marketplace add https://github.com/cathrynlavery/diagram-design droid plugin install diagram-designdiagram-design --scope userDroid 按 commit 跟踪 Git 插件合入新版本后执行droid plugin marketplace update diagram-design、再droid plugin update diagram-designdiagram-design --scope user并开启新会话。Pi无需 marketplace直接经由仓库标准skills/包目录发现 skills/diagram-design/ 这份共享 Skill。迁移提醒README 中的一次性迁移说明已通过独立npx skills add安装的副本不会自动跟随 Codex marketplace——需移除独立副本后改用 marketplace 安装Cowork 个人副本同理需卸载后改从组织 marketplace 安装此后每次版本 bump 都会沿各客户端的原生更新路径流动。这一迁移路径之所以成立正是 ADR 0008单一插件根 原生更新路径设计的直接收益。9. 门禁的对抗性测试scripts/test-plugin-package.py 是这套门禁的对抗性回归套件覆盖了本文提到的几乎每个失败模式有效同步 bump 通过、缺 bump 拒绝、双清单版本漂移拒绝、Factory 单独漂移拒绝、非严格 semver 拒绝、marketplace 目标缺失拒绝、Factory 非原生 source 拒绝、共享命令面缺失拒绝、bootstrap 合法/非法场景以及 SKILL.md frontmatter 的一系列畸形输入重复 metadata.version、正文中的 version 行不算数、未闭合引号、非法转义、\U00110000越界转义等。任何一条规则被悄悄放宽都会被这些用例当场戳穿。10. 小结ADR 0008 用一句话概括每个宿主一份最小的原生清单与 marketplace 元数据所有 marketplace 指向同一个仓库根行为永远只有一份。它的工程价值体现在三个层面布局上清单目录.claude-plugin/、.codex-plugin/、.factory-plugin/与共享面skills/、commands/职责分明从文件结构即可读出发布策略流程上bump-plugin-version.py保证三份清单版本同步verify-plugin-package.py保证身份、路径、打包面与 SKILL.md 元数据零漂移bootstrap 特例为新宿主接入提供了受控通道发布上Git 型宿主Factory按提交更新同步清单版本退化为发布元数据与评审门禁真正驱动用户更新的是 marketplace 的新提交。对于任何一个 Skill 分发到多个 AI 宿主的项目这份 ADR 与其配套脚本、测试构成了一套可以直接借鉴的完整方案最小原生清单、单一插件根、同步版本门禁、受控 bootstrap。延伸阅读仓库中其余 ADR 记录着同一套治理思路的姊妹决策例如 ADR 0001静态输出默认 唯一受审控的 motion 控制器它们共同勾勒出 Diagram Design 把行为收敛到单一来源、用脚本与测试封死漂移的工程哲学。【免费下载链接】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），仅供参考