OpenRig 技能库镜像与变更治理机制：从 skills/CHANGELOG.md 读懂 _canonical 技能集的发布与漂移防护-平芜编程栈

人工智能
AI Agent
多智能体
Agent 编排
代码智能体
CLI

【免费下载链接】openrig

Build your own network of agents from Claude Code, Codex and Pi: persistent teams with roles, shared context and owned work.

项目地址：https://gitcode.com/GitHub_Trending/op/openrig

点击查看免费下载

导读

OpenRig 在仓库根目录维护了一个公开的技能库镜像skills/_canonical/，并配套一份按策展周期（curation cycle）追加的变更日志skills/CHANGELOG.md。本文以这份变更日志为核心线索，完整拆解 OpenRig 技能集的发布链路——技能如何从 daemon 内置目录镜像到仓库根目录、mirror-skills脚本如何做内容级漂移检测、变更日志为何必须手工维护且新条目置顶，以及当前仓库中 spec / canonical / plugin 三 edge 布局的演进形态。读完本文，你将掌握 OpenRig 技能库的目录所有权约定、镜像命令与 CI 门禁、变更治理规范，并能对照源码自行验证镜像是否漂移。

背景：OpenRig 的 skills 是什么

在进入变更日志之前，先建立一个最小上下文。OpenRig 的 skill 不是字典意义上的“能力单元”，而是一种渐进式披露（progressive-disclosure）的上下文注入原语：

每个 skill 是带 YAML frontmatter 的 Markdown 文档，核心文件名为SKILL.md；
frontmatter 里的description是触发条件（trigger），常驻在 Agent 的“热层”（hot tier），用于廉价模式匹配；
正文（body）在触发时加载；
文件夹内的 references 等附属文件按需加载。

OpenRig Agent 会自动发现技能，一般不需要显式调用——编写一个 skill 的本质，是用足够精确的触发词命名一个反复出现的需求，让 Agent 在正确时机“够到”它。这一机制在 skills/README.md 中有完整说明，也可直接阅读 skills/_canonical/core/openrig-skills/SKILL.md 这份索引来观察真实 skill 的形态。

技能库目录结构与严格所有权约定

skills/目录是 OpenRig 技能集的公开可见镜像（publicly-visible mirror），其结构如下：

路径	内容	所有权
`skills/_canonical/`	镜像出的技能集，按`core/`、`pm/`、`pods/`、`process/`分类，另有少量未分类项	严格复制品，禁止直接编辑
`skills/CHANGELOG.md`	技能变更的追加式日志，按策展周期收尾记录	手工维护（hand-authored）
`skills/README.md`	技能库使用与作者指南	手工维护
`skills/LICENSE`	Apache-2.0，与父项目一致	手工维护

这里的“严格所有权（strict-ownership）”约定是整套机制的地基：镜像脚本只会触碰_canonical/内部，绝不会覆盖与_canonical/平级的手工文件。正如 skills/CHANGELOG.md 初始发布条目所记录的——这样做的目的是让 README、CHANGELOG、LICENSE 以及未来可能出现的插件清单等顶层文件在每次镜像运行后都得以存活，而不是被镜像脚本当作目标目录的一部分清掉。对应地，scripts/mirror-skills.mjs 头部注释也明确写了这一约定。

变更日志的定位与格式规范

skills/CHANGELOG.md本身是一份追加式（append-only）日志，其角色由技能库运营规范operating-the-skill-library/SKILL.mdv1.9 第 8 节的两条规则定义：“In-repo skills hub（仓库内技能枢纽）”与“skills/CHANGELOG.md”。该规范位于技能库运营层的 substrate 工厂目录（详见 skills/README.md 中的 Authoring 小节），不在公开镜像树内，但变更日志首页明确引用了它作为治理依据。

日志的格式与用途在文件头有精确表述：

新条目永远落在顶部（New entries land at the top），保持“越新越靠前”的阅读顺序；
每个条目必须记录三要素：策展周期日期（cycle date）、变更内容（what changed）、受影响技能（which skills affected）；
之所以要独立维护这样一份日志，是为了让跟踪技能集的用户可以独立于 daemon 二进制版本拉取技能更新——技能可以随一个 PR 原子性地与加载它的 daemon 一起发布，但阅读者不必翻 daemon 版本号就能知道技能集发生了什么变化。

一个典型的条目骨架如下：

## YYYY-MM-DD — <版本/主题> <curation 标题> <本次变更的一句话概括> Mechanism: <底层机制描述，例如从哪个目录移除、更新了什么资源池、镜像到了哪里> Why: <为什么做这次变更> References: - <依据的规范规则> - <机制对比文档>

两条历史条目：从初始发布到 0.3.0 策展

变更日志目前收录了两条完整记录，恰好构成“从无到有、再到第一次收敛”的完整叙事。

2026-05-09 — Initial publish: skills hub bootstrap

这是技能库的初始发布，记录了三个关键事实：

镜像方向：从 daemon 内置技能目录packages/daemon/specs/agents/shared/skills/首次镜像到<repo-root>/skills/_canonical/；
初始规模：共发布27 个技能，横跨 4 个分类（core/、pm/、pods/、process/），另有未分类的顶层技能，例如claude-compact-in-place/与rig-architect/。需要说明的是，这 27 个是 2026-05-09 当日的基线数量；当前仓库的_canonical/已进一步演进（见下文“当前清单”小节）；
Why：把技能集暴露在仓库根目录，让公开技能库无需在packages/daemon/specs/里掘地三尺即可发现；同时遵循_canonical/严格所有权约定，保证手工维护的顶层文件在每次镜像后存活。

2026-05-10 — 0.3.0 starter-skill curation

这是第一次策展收敛：从内置 starter 技能集中移除了一个已废弃的 HA 取向（HA-oriented）技能。starter Agent 转而依赖与其随附启动指引相匹配的更窄的角色（role）、流程（process）与原地压缩（compact-in-place）技能。

该条目同样记录了机制细节：

从packages/daemon/specs/agents/shared/移除该技能；
更新共享的 AgentSpec 资源池；
将更新后的 canonical 清单重新镜像到skills/_canonical/。

从这条记录可以读出技能集治理的完整闭环：策展决策 → 产品源（product source）变更 → 资源池更新 → 重新镜像公开副本，任何一步缺失都会造成产品源与公开镜像之间的漂移——这正是下一节源码级拆解要解决的问题。

镜像机制源码级拆解

变更日志指明的机制是：npm run mirror-skills调用 scripts/mirror-skills.mjs（一个封装 rsync 的 Node 脚本）。其核心常量与参数如下（对应 scripts/mirror-skills.mjs）：

export const SOURCE_DIR = "packages/daemon/specs/agents/shared/skills/"; export const TARGET_DIR = "skills/_canonical/"; export const EXCLUDES = [ "feedback.md", // 策展周期的记账文件，不进入公开面 "evals/", // 每个技能的评价试点基础设施，可能泄漏测试夹具 ".DS_Store", "*.local.md", ];

rsync 的调用参数（scripts/mirror-skills.mjs）值得逐项解释：

return [ "-a", // archive 模式，保留权限与时间戳 "--delete", // 目标端多余文件一律删除（严格镜像语义） "--delete-excluded", // 被排除的模式在目标端同样删除 "--itemize-changes", // 输出逐项变更明细，供解析 ...(dryRun ? ["-n", "--checksum"] : []), // 检查模式加 -n 与 --checksum ...EXCLUDES.map((p) => `--exclude=${p}`), SOURCE_DIR, TARGET_DIR, ];

这里有一个值得注意的工程细节：检查模式（--check）使用--checksum，按文件内容哈希而非 mtime+size 判断差异。这意味着git checkout或cp这类只更新 mtime 的操作不会误报漂移——只要字节一致就算同步；而在应用模式下保持默认的 mtime+size 以追求速度，同时 archive 标志保留 mtime，保证后续检查依然干净。

EXCLUDES中的每一项都有明确的治理理由（见 scripts/mirror-skills.test.mjs 中的测试注释）：feedback.md是策展周期记账文件；evals/是技能评价试点基础设施（cases.yaml、harness、outcomes），其中可能嵌套.agents/skills/测试夹具，会干扰技能盘点工具。

变更解析与漂移判定

parseChanges（scripts/mirror-skills.mjs）从 rsync 的--itemize-changes输出中提取真正的变更行，按 rsync(1) 首列编码过滤：

</>— 文件内容已传输（内容变更）；
c— 新建条目（文件/目录/符号链接/设备）；
.f...p.....— 纯权限变更（镜像必须保留的唯一元数据字段），mtime 漂移则被忽略；
*deleting— 目标端删除。

对应测试（scripts/mirror-skills.test.mjs）用一个包含>f+++++++++ core/openrig-user/SKILL.md、.f...p.....与*deleting行的样例验证了解析结果，并断言干净的同步输出返回空数组。测试还覆盖了 rsync 3.x 的 11 位 itemization 与 openrsync 的 9 位宽度差异（scripts/mirror-skills.test.mjs），保证解析器对字段宽度不敏感。

一旦检测到漂移，buildStaleMessage（scripts/mirror-skills.mjs）会生成明确指引：

Skills mirror is stale at skills/_canonical/. Run: npm run mirror-skills Changes that would land: >f+++++++++ core/openrig-user/SKILL.md *deleting removed/SKILL.md

检查模式与 CI 门禁

镜像脚本支持两种运行模式：

命令	行为
`npm run mirror-skills`	应用模式：执行 rsync，将产品源同步到`_canonical/`
`npm run mirror-skills:check`	检查模式：以`--checksum`做内容级 dry-run 漂移检测，漂移则退出码为 1

两条命令定义在 package.json。更关键的是，mirror-skills --check已被接入仓库级测试门禁：npm run test:repo的脚本链中包含node scripts/mirror-skills.mjs --check（package.json）。因此，如果有人在产品源改了技能却没有重跑镜像，npm run test:repo会直接失败，并用上面那条 stale 消息指明修复命令。测试文件中的“mirror is in sync with source”用例（scripts/mirror-skills.test.mjs）正是这条门禁的承载断言，注释明确写着：失败意味着“有人在未运行npm run mirror-skills的情况下编辑了源”。

从镜像到三 edge 布局：机制的演进

变更日志记录的是 0.2 版机制（单一 rsync 镜像），而当前 scripts/mirror-skills.mjs 已经演进为三 edge（canonical / plugin / spec）布局 + 控制面清单（control-plane manifests）驱动的流水线。生成的控制面文件包括：

scripts/skill-edge-layout.generated.json — 定义三个 edge 的路径与布局；
scripts/skill-edge-digests.generated.json — 每个 edge 下每个文件的 SHA-256 摘要；
scripts/product-public-skills.generated.json — 技能成员资格（哪些技能属于产品公开集、哪些 not_public）；
scripts/internal-tokens.generated.json — 内部令牌与路径规则，用于公开面泄漏扫描。

从布局文件（scripts/skill-edge-layout.generated.json）可以看到三个 edge 的分工：

edge	路径	布局
`spec`	`packages/daemon/specs/agents/shared/skills`	categorized（按分类组织）
`canonical`	`skills/_canonical`	mirror-of-spec（规范镜像）
`plugin`	`packages/daemon/assets/plugins/openrig-core/skills`	flat（扁平）

即：同一技能集在“产品源（spec）→ 公开镜像（canonical）→ 插件分发（plugin）”三处保持内容一致，checkGeneratedEdges（scripts/mirror-skills.mjs）按布局与摘要双向比对，能区分missing（缺文件）、digest（内容漂移）、unexpected（多余文件）、layout-missing（布局要求但磁盘缺失）、layout-category（分类不符）等各类漂移。此外，公开面发布前还会经过scanInternalLeaks（内部泄漏扫描）与 frontmatter 清洗（stripPublicSkill），确保operator-agent@、openrig-work/等内部令牌、distribution_scope等内部键不会泄漏到公开镜像——详见 scripts/mirror-skills.mjs 及对应的多条stagePublicSkills测试（scripts/mirror-skills.test.mjs）。

当前 _canonical 清单与分类概况

对照当前仓库的 skills/_canonical/ 目录，公开技能集已从初始 27 个增长到35 个 SKILL.md，分布如下：

core/（17 个）：agent-starters、agent-startup-and-context-ingestion、cross-host-rig-commands、human-in-the-loop、messaging-the-human、openrig-architect、openrig-cmux、openrig-herdr、openrig-skills、openrig-software-factory、openrig-upgrade、rig-bundles-and-shareable-artifacts、rig-lifecycle、session-source-fork、specification-system、topology-mutation-and-seat-management、watchdog；
pm/（7 个）：backlog-capture、context-builder、exec-summary、office-hours、plan-review、requirements-writer、ui-mockup；
pods/（4 个）：development-team、orchestration-team、oversight-team、review-team；
process/（7 个）：agent-browser、context-engineering、dogfood、frontend-design、systematic-debugging、test-driven-development、verification-before-completion。

部分技能携带附属资产，例如openrig-software-factory/references/worked-example.md、openrig-upgrade/scripts/下的迁移脚本、process/dogfood/的报告模板、process/systematic-debugging/的find-polluter.sh等——这些附属文件同样由镜像脚本负责同步。值得一提的是，初始发布条目中提到的顶层未分类技能claude-compact-in-place/与rig-architect/已不在当前清单中：rig-architect已演进为分类内的core/openrig-architect，这本身就是策展日志后续应记录的“迁移”类变更样本。

作者工作流：从 substrate 工厂到公开镜像

skills/README.md 的 Authoring 小节给出了技能的两段生命周期，这也是理解变更日志“为什么存在”的关键：

Substrate 工厂（substrate/shared-docs/openrig-work/skills/）——新技能的创作、审计与策展循环发生地，每个技能带feedback.md（策展记账）与evals/（评价试点基础设施）。这是技能团队持续工作的真相源；
产品源（packages/daemon/specs/agents/shared/skills/）——随 daemon 发布的那部分技能。技能从工厂毕业后进入产品源，才会被打包进 npm 包。

<repo-root>/skills/_canonical/从产品源镜像而来，严格是一份复制品。规则是：永远不要直接编辑_canonical/；产品源中的编辑必须在提交前重跑镜像脚本。这套“工厂 → 产品源 → 公开镜像”的流水线，加上mirror-skills --check的 CI 门禁，构成了技能集的事实单一来源保证。

Future-state：为 git subtree split 预留的形态

变更日志与 README 都提到了技能库的未来形态：当前目录结构被刻意组织成“仿佛它自己就是一个独立仓库”，以便在规模增长到合适时机时，git subtree split --prefix=skills HEAD可以机械地完成拆分。在拆分之前，仓库内镜像就是正确的作用域：技能变更与加载它们的 daemon 二进制原子性地一起发布，无版本错位风险，一个 PR 同时覆盖技能与其加载器。