Harness 版本发布审计实战从三重版本不一致到标签化发布v1.2.0 全流程解析【免费下载链接】harnessA meta-skill that designs domain-specific agent teams, defines specialized agents, and generates the skills they use.项目地址: https://gitcode.com/GitHub_Trending/harness/harness本文以 Harness 仓库的发布审计记录audit-2026-04-18.md为主体完整还原一次真实的多源版本一致性修复过程审计发现 README 徽章、插件清单、市场清单与 git tag 四个信息源之间存在三重不一致随后依据 plugin.json 权威源完成同步、规划 4 个版本的标签化发布并产出 GitHub Release 草稿。读完本文你将掌握一套可复用的开源项目版本卫生审计方法如何定位版本 gap、如何判定 SemVer 级别、如何用 annotated tag 做追溯打标、如何安全推送与起草 Release以及如何在多 Agent 并行修改时用独立审计文件做回查。一、背景为什么一个插件项目需要版本发布审计Harness 是一个面向 Claude Code 的团队架构工厂Team-Architecture Factory元技能输入一句领域描述例如build a harness for a fintech risk-assessment team它会自动生成.claude/agents/下的专业 Agent 定义与.claude/skills/下的技能文件。作为以 Claude Code 插件形式分发的开源项目Harness 的版本信息散布在多个文件中而它们各自承担不同的读者信息源谁在读取文件位置当前仓库README 徽章仓库访问者、搜索引擎README.md / README_KO.md / README_JA.mdplugin.jsonClaude Code 运行时权限最高.claude-plugin/plugin.jsonmarketplace.json插件市场marketplace发现与安装.claude-plugin/marketplace.jsongit tag / CHANGELOG版本追踪、CVE·SBOM·审计链CHANGELOG.md审计文档将这种状态命名为多源版本不一致tag·version mismatch并指出在面向企业采购与市场信任积累的场景下这是第一轮就会被淘汰的卫生问题。因为企业方验证一个插件是否可信通常依次看 README 徽章、marketplace 元数据、git tag 与 CHANGELOG——任何一个对不上都会触发这项目连版本都管不好的直觉性否决。二、现状审计Before四源版本状态的完整盘点审计第一步是列出所有版本源的当前值逐行比对。原文档的状态表如下路径行号均已对照当前仓库核实来源版本文件路径备注README.md 徽章1.0.1README.mdversion-1.0.1-brightgreen.svgREADME_KO.md 徽章1.0.1README_KO.md与 EN 同字符串README_JA.md 徽章1.0.1README_JA.md与 EN 同字符串plugin.json1.2.0.claude-plugin/plugin.jsonClaude Code 实际读取的权威源marketplace.json1.1.0.claude-plugin/marketplace.jsonplugins[0].versionCHANGELOG 最新[1.2.0]CHANGELOG.md2026-04-08 日期git tag 最新无—git tag -l空输出标签化发布 0 条最新提交3bfc442HEAD (main)v1.2.0: CLAUDE.md 指针策略简化…2.1 三重不一致摘要盘点结果被概括为三重不一致3-way mismatchREADME 徽章3 种语言 vs plugin.json2 级 gap1.0.1 → 1.2.0marketplace.json vs plugin.json1 级 gap1.1.0 → 1.2.0plugin.json vs git tag标签缺失声明了 1.2.0但可追溯的发布产物为 0 条2.2 不一致的影响度评估原文档对每个 gap 的影响做了映射这是审计报告最有价值的部分——不一致不只是难看而是有明确的下游后果影响领域症状可信度访问者看到 README 徽章会误以为1.0.1 是最新版形成旧版本先入为主的印象安装体验通过市场安装时以 1.1.0 元数据注册实际插件却是 1.2.0后续更新无法追踪发布追踪git tag -l为空 →gh release list为空 → 用户无法按版本追踪 CHANGELOG企业采购没有标签化发布就无法构建 CVE / SBOM / 审计轨迹2.3 仓库侧的事实印证对照当前仓库可以确认审计结论成立且修复已完成如今 README.md 徽章已是Version-1.2.0-brightgreen并新增了Layer: L3 Meta-Factory、Sub-layer: Team-Architecture Factory、README: EN | KO | JA三枚定位徽章plugin.json 的version字段为1.2.0marketplace.json 中plugins[0].version同样为1.2.0CHANGELOG.md 顶部已出现[1.2.1] - 2026-04-18条目。这就是审计驱动的一致性修复落地后的最终形态。三、正解版本的决定plugin.json 优先原则面对四个互相打架的版本号审计必须给出一个唯一正解版本canonical version。原文档的裁定是v1.2.0依据三条优先级规则plugin.json 优先原则——Claude Code 插件系统实际读取的就是 plugin.json因此它是最权威的版本源与 CHANGELOG 最新条目一致——[1.2.0] - 2026-04-08是 CHANGELOG 中最新条目与 plugin.json 吻合与最新提交信息互相印证——HEAD 提交3bfc442的提交信息即为v1.2.0: CLAUDE.md 指针策略简化…两个独立来源交叉确认。由此得到同步方向README 徽章 3 种1.0.1与 marketplace.json1.1.0全部向 v1.2.0 向上对齐。3.1 本次修复工作的版本判定为何是 1.2.1 而不是 1.3.0同步本身也是一次代码变更需要在 CHANGELOG 中登记。原文档判定本次工作记录为[1.2.1] - 2026-04-18并给出了明确的 SemVer 论证无 breaking change用户的技能执行面skill execution surface完全不变有新增内容CONTRIBUTING、docs/ 等为 additive 变更结论按 patch 处理。虽然歧义时默认 minor但本仓库用户可见的技能运行表面没有任何变化因此维持 patch 级别。这一判例与 CONTRIBUTING.md 中规定的提交类型—SemVer 映射表完全自洽fix:→ patch、feat:→ minor、feat!:/BREAKING CHANGE:→ major。也就是说一个修版本号的提交对应fix:级别天然是 patch——审计文档把这一规则用到了自己身上。四、同步落地After5 个文件的修改明细正解版本确定后执行同步。原文档给出了完整的 Before / After 对照表文件BeforeAfter变更方式README.mdversion-1.0.1-brightgreenversion-1.2.0-brightgreenEdit替换徽章 URL 字符串README_KO.mdversion-1.0.1-brightgreenversion-1.2.0-brightgreenEditREADME_JA.mdversion-1.0.1-brightgreenversion-1.2.0-brightgreenEdit.claude-plugin/marketplace.jsonversion: 1.1.0version: 1.2.0Edit.claude-plugin/plugin.jsonversion: 1.2.0无变更已是正解版本CHANGELOG.md最新[1.2.0]新增[1.2.1] - 2026-04-18Edit插入到顶部4.1 修改文件清单5 种与新文件1 种M CHANGELOG.md M README.md M README_JA.md M README_KO.md M .claude-plugin/marketplace.json ?? _workspace/release/audit-2026-04-18.md 本审计文档新增4.2 核心纪律plugin.json 保持不动审计特别强调plugin.json 已持有正解版本1.2.0本次不触碰留待下一个版本1.2.1发布时再做独立 bump。这条纪律在后续的 post-M0 审计中引发了唯一一个 Critical 级问题见第七节——说明声明不修改某个文件本身就是需要书面化、并在合并前用git diff复核的承诺这比同步版本号本身更有方法论价值。4.3 与后续版本的衔接CHANGELOG 已登记的 1.2.1 实际内容对照当前 CHANGELOG.md 可以看到 [1.2.1] 条目的最终落稿除了版本同步Fixed之外还包含三块与发布直接相关的变更Fixed三重版本不一致统一到 v1.2.0为标签化发布 0 条编写追溯标签计划Addedharness factory定位声明、CONTRIBUTING.md、docs/ 目录、Issue #3 响应策略Changedmarketplace.json 与 README 徽章版本上移plugin.json的 description 重写为 The team-architecture factory for Claude Code…ENKO 双语keywords 由 5 个扩展为 17 个新增harness-factory、team-architecture-factory、6 种架构模式关键词等见 plugin.json。这说明一次只改版本号的审计最终会牵连出定位与元数据的一致性因为它们共同构成插件在市场和搜索引擎中的可见表面。五、git tag 计划追溯打标与安全推送版本号同步只是纸面一致真正的发布链路需要 git tag。审计发现仓库历史上从未打过任何标签git tag -l为空因此制定了3 个追溯标签 1 个新标签的计划并严格标注为待主编排者审批后执行——审计文档只负责记录不负责执行。5.1 追溯标签3 个标签目标提交提交日期依据v1.0.0dd0d0db2026-03-27市场提交准备CHANGELOG 新增、description 英文并记、需求整理——CHANGELOG 首次出现 [1.0.0] 章节的提交v1.0.122bdbff2026-03-29README 徽章新增及 plugin.json 版本 1.0.1 同步——plugin.json 1.0.0→1.0.1 的实际 bump 提交v1.1.02d848632026-04-05v1.1.0: Phase 0 现状审计、CLAUDE.md 自动同步、运营/维护工作流新增——v1.1.0 最终发布提交同日先行提交8604b11为中间态5.2 新标签1 个标签目标提交依据v1.2.03bfc442当前 HEADv1.2.0: CLAUDE.md 指针策略简化、混合执行模式新增5.3 待审批的执行命令annotated tag 专用原文档给出的命令模板如下其中cd路径为审计执行环境的本机路径实际使用时替换为你自己的仓库路径即可cd /Users/robin/IdeaProjects/harness # 追溯标签 —— 只使用 annotated 标签禁止 lightweight见角色定义 §6 git tag -a v1.0.0 dd0d0db -m v1.0.0: 初始 harness 元技能公开 - 基于 6 Phase 工作流的 harness 构成 - 6 种 Agent 架构模式 - Agent 团队 / 子 Agent 执行模式 - 基于 Progressive Disclosure 的技能生成指南 git tag -a v1.0.1 22bdbff -m v1.0.1: SKILL.md 重复内容去除及 plugin.json 版本同步 - SKILL.md ↔ references 重复内容去除330 行 → 285 行 - Phase 2-1、2-3、3、5-2 references 指针转换 git tag -a v1.1.0 2d84863 -m v1.1.0: Phase 0 现状审计、CLAUDE.md 同步、harness 进化机制 - Phase 0: 现状审计及 3 分路路由新增/扩展/维护 - Phase 5-4: CLAUDE.md harness 上下文注册 - Phase 7: harness 进化机制反馈→反映→变更历史 - 编排器后续工作支持 git tag -a v1.2.0 3bfc442 -m v1.2.0: CLAUDE.md 指针策略、混合执行模式 - CLAUDE.md 注册策略简化上下文 → 指针 - Phase 2-1 混合执行模式团队 子 Agent 组合 - Phase 5-0 混合编排器模式 - Phase 5-1 基于返回值的传递子模式 # 确认 git tag -l --sort-v:refname git show v1.2.0 --stat | head -20几点值得展开的操作要点只用 annotated 标签git tag -a会写入标签对象包含打标人、时间、消息lightweight 标签只是裸指针。对于企业审计链annotated 标签的完整元数据是必需的这也与 CONTRIBUTING.md 的发布规则从 main 打vMAJOR.MINOR.PATCH格式标签呼应。追溯标签选点原则每个历史版本选择该版本首次落地的那个提交如 v1.0.1 选 plugin.json 实际 bump 的提交而不是同日期的任意提交v1.1.0 还特别排除了先行提交8604b11只标记最终发布提交。消息体承担 release notes 职责-m消息直接结构化列出每个版本的核心能力这些内容之后可复用到 GitHub Release 的--notes。5.4 远程推送双审批 逐个标签推送# ⚠️ 验证上述本地 4 个标签后获得主编排者二次审批方可执行 git push origin v1.0.0 v1.0.1 v1.1.0 v1.2.0原则不使用git push --tags全量推送而是把 4 个标签显式逐个 push防止误推无关标签、防止意外把未验证的引用推到远端。结合上文的执行需审批与这里的二次审批整条发布链是文档化 → 审批 → 验证 → 显式推送的渐进闸门。六、GitHub Release 草稿Experimental 警告与 pin-to-tag 策略标签是发布的技术载体Release 是发布的可读面。原文档同样以待审批、仅提供命令文本的形式起草了 Release。6.1 v1.2.0 Release 创建命令cd /Users/robin/IdeaProjects/harness gh release create v1.2.0 \ --title v1.2.0 — CLAUDE.md 指针策略 混合执行模式 \ --notes $(cat EOF ⚠️ **Experimental**: Claude Code 插件系统目前处于 Experimental 阶段。生产环境引入时推荐采用 pin-to-tag 策略。 ## Changed - **CLAUDE.md 注册策略简化去重** — Phase 5-4 由上下文注册转为指针注册。从 CLAUDE.md 中移除 Agent 列表、技能列表、目录结构、执行规则详情仅保留**触发规则 变更历史** - **Phase 3/4 临时同步阶段删除** — 降低 CLAUDE.md 同步负担 - **核心原则 3 重新定义** — 上下文注册 → 指针注册 ## Added - **Phase 2-1: 混合执行模式** — 在 Agent 团队 / 子 Agent 之外新增混合模式 - **Phase 2-1 执行模式对比表** — 团队/子/混合 3 种的决策顺序 - **Phase 5-0 混合编排器模式** - **Phase 5-1 基于返回值的传递**仅子 Agent 模式 ## Migration 从 v1.1.0 升级、且 CLAUDE.md 中harness 上下文章节已膨胀的用户请参考 docs/migration-1.2.md编写中转换为指针块。 ## Full Changelog [CHANGELOG.md §1.2.0](https://link.gitcode.com/i/e728686294103caf1ccb3e3afc174324) EOF ) \ --draft6.2 这份草稿中的三条发布最佳实践Experimental 警告置顶Claude Code 插件系统本身处于 experimental 阶段Release 首行即声明并给出生产环境采用 pin-to-tag 策略的建议——即用户按精确标签而非latest锁定插件版本保证可复现。--draft草稿先行gh release create --draft不会立即对公众可见给内容审核与横幅图片附件留出窗口避免发布即翻车。Migration 指引 Full Changelog对 v1.1.0 老用户给出迁移路径指向编写中的docs/migration-1.2.md并链接 CHANGELOG 全文作为变更清单的单一事实源。需要说明docs/migration-1.2.md在当前仓库中尚未创建原文档标注编写中引用时应保持这一前提不要当作已存在文件使用。6.3 执行审批清单发布前 4 项硬检查原文档要求主编排者在批准gh release create前确认本地 4 个标签是否挂在正确的 SHA 上git show tag验证git push origin v*完成后GitHub 上是否能看到标签Release 说明顶部是否包含 Experimental 警告见角色定义 Step 6content-creator 是否确认可为 Release 附带横幅图片6.4 追溯 Releasev1.0.0 / v1.0.1 / v1.1.0对 3 个历史版本策略是标签创建后将 CHANGELOG 中对应章节提取为--notes正文。原文档明确该批操作放在 v1.2.0 批准之后的第二批次处理避免一次引入过多变更面。七、发布后验证Post-M0 审计如何回查版本一致性release-engineer 的审计文档本身不是终点。它提交后由 repo-auditor 以只读方式git diff、git status、逐文件 Read禁止 Edit/Write对 M0 阶段的全部改动做了回查形成了配套的 post-m0-audit-2026-04-18.md。其中与版本一致性直接相关的 A 区 7 项验证结果如下区域验证项结果备注A-1README.md徽章Version-1.2.0PASS由1.0.1变更确认A-2README_KO.md徽章Version-1.2.0PASS三语言字符串一致A-3README_JA.md徽章Version-1.2.0PASS三语言字符串一致A-4marketplace.jsonversion: 1.2.0PASS由1.1.0变更确认A-5plugin.jsonversion: 1.2.0保持PASS数值/ FAIL策略version 未变但 description·keywords 被改动——见冲突审计A-6CHANGELOG.md[1.2.1] 条目PASS顶部存在 Fixed/Added/Changed 三块A-7audit-2026-04-18.md存在PASS228 行5 章节 2 附录完整7.1 这次回查最有价值的一个发现声明与实际的偏差Post-M0 审计暴露了一个 Critical 问题audit 文档 §3.3 声明plugin.json 未触碰但实际git diff .claude-plugin/plugin.json显示 description 被重写、keywords 从 5 个扩到 17 个——这很可能是 content-creator 在统一定位声明时顺手改的。审计给出的两条出路极具工程参考价值选项 A推荐接受——在 audit §3 与 §3.3 中把未触碰修正为version 保持 1.2.0description·keywords 由 content-creator 调整并在 CHANGELOG [1.2.1] 的 Changed 块补充该说明选项 B回滚——git restore .claude-plugin/plugin.json还原后拆成独立 PR 再走正式请求。repo-auditor 推荐选项 A理由是改动内容与定位一致性目标相符且无害version 字段保持 1.2.0 不影响 Claude Code 运行时行为回滚反而会在 README/marketplace 的新 description 与 plugin.json 的旧 description 之间制造新的不一致。这个案例说明审计的价值不止于发现版本号错了更在于把谁改了什么、为什么改、与声明是否一致固化为可复核的记录——这正是多 Agent 协作仓库release-engineer / content-creator / launch-strategist / community-scout 并行修改同一批文件避免混乱的关键机制。整场 M0 并行修改最终以1 Critical 2 Minor收官且版本同步全部 PASS可以条件性提交。八、给下一次审计的检查清单附录 A原文档在附录中留下了一份可直接复用的巡检清单任何开源项目都可以照此建立自己的版本卫生例行检查本次审计之后的新增提交数plugin.json 版本是否在此期间发生变化CHANGELOG 是否新增了条目最近一个已打标签版本与 plugin.json 之间的 gap3 种语言 README 徽章的同步状态同时附录 B 说明了本次审计的上游依据链战略报告 §3.2 P-04版本·发布一致性是直接触发器§4.7企业采购路径提出标签化发布要求研究报告 §1.5仓库定量指标记录了发布 0 条的状态§4.7 弱点 4标签·版本不一致则是本次工作的解决对象。这套战略 → 研究 → 执行 → 验证的闭环保证了审计工作始终有据可依而非拍脑袋修复。九、方法论提炼一次可复用的版本一致性修复流程将本仓库这次实战抽象为通用流程共六步盘点列出所有版本信息源README 徽章、插件清单、市场清单、CHANGELOG、git tag、最新提交形成 Before 状态表定权按运行时实际读取的文件 CHANGELOG 提交信息的优先级确定正解版本其余源向其对齐判级用 SemVer 规则CONTRIBUTING.md 的提交类型映射表判定修复本身的版本级别写入 CHANGELOG打标对历史版本按该版本落地提交选点做追溯 annotated 标签新版本标签打在 HEAD消息体结构化承载 release notes发布gh release create --draft草稿先行顶部保留 experimental 警告与 pin-to-tag 建议审批清单逐项打勾后显式 push 标签回查由独立角色只读复核重点比对审计文档的声明与git diff 的实际发现偏差后给出接受或回滚二选一建议。这套流程在当前仓库中留下了完整可查的档案审计主文档 _workspace/release/audit-2026-04-18.md、回查文档 _workspace/release/post-m0-audit-2026-04-18.md、变更结果 CHANGELOG.md、版本元数据 plugin.json 与 marketplace.json以及发布纪律的长期约定 CONTRIBUTING.md。如果你正在维护任何以插件/包形式分发的开源项目本文的三重不一致案例就是一面镜子——版本号的一致性本质上是项目工程纪律可见度的最低门槛。【免费下载链接】harnessA meta-skill that designs domain-specific agent teams, defines specialized agents, and generates the skills they use.项目地址: https://gitcode.com/GitHub_Trending/harness/harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考