skillpack-harvest

skillpack-harvest — 将宿主技能提升到 gbrain 的编辑工作流

约定： 文件放置规则见 _brain-filing-rules.md。本技能写入的是 gbrain 自身的目录树，而不是 brain 仓库的笔记。

本技能是 gbrain skillpack scaffold 的逆向操作。Scaffold 将技能下发到下游（gbrain → 宿主），Harvest 则将经过验证的模式上传到上游（宿主 → gbrain），使其成为其他所有客户端都可以 scaffold 的参考。

合约

当满足以下条件时，一次 harvest 才算“完整完成”：

1. 宿主技能已经成熟（在生产环境中使用过，近期的路由评估用例全部通过）。
2. Phase 3 的编辑式通用化已经清除了所有分支特有的引用（名称、真实实体、内部频道）。
3. gbrain skillpack harvest --dry-run 已预览过文件集合。
4. 真正的 gbrain skillpack harvest <slug> --from <host> 已成功执行，状态为 status: harvested（没有隐私检查命中）。
5. 新的 skills/<slug>/SKILL.md 通过了 bun test test/skills-conformance.test.ts。
6. 用户已审阅 gbrain 中的差异，并明确批准提交。

如果其中任何一项未完成，则该技能尚未 harvest：文件可能仍留在 gbrain 的工作树中，但并未正式落地。

输出格式

本技能会在 gbrain 的工作树中生成三类产物：

1. skills/<harvested-slug>/SKILL.md（以及任何同级文件，例如 routing-eval.jsonl）
2. 位于镜像路径上的配对源文件（例如 src/commands/<slug>.ts），前提是宿主 SKILL.md 在 frontmatter 的 sources: 中声明了它们
3. 更新后的 openclaw.plugin.json，其中新 slug 已添加到 skills: 中（并排序）

返回给用户的会话输出是一行成功摘要，加上已写入文件的列表。JSON 模式（--json）会返回完整的 HarvestResult 结构，供机器读取。

失败时如何处理

对于任何 gbrain 错误 code、退出码、[AGENT] 块或提示块，请遵循 agent 操作协议。针对本技能的具体情况：

• lint_failed：隐私检查器发现了真实姓名或私密细节；返回 Phase 3，用占位符替换它们（alice-example、acme-example、fund-a）。
• harvest 之后 gbrain skillpack check --strict 报告漂移：重新生成 bundle 并再次运行；永远不要发布存在漂移的 skillpack。

反模式

• 跳过 dry-run。 务必先预览。文件会落到 gbrain 的工作树中；清理只需一次 git checkout，但你本不应该需要它。
• 只信任检查器。 默认正则集能覆盖常见情况，但无法覆盖所有专有名词。Phase 3（编辑通过）是主要防线。
• 无正当理由就使用 --no-lint 进行 harvest。 检查存在是有原因的。如果绕过它，请在提交信息中说明原因。
• harvest 仍在变动中的技能。 等待宿主版本稳定。否则你会先 harvest、再重新 harvest、再重新 harvest，这只会让 gbrain 的 bundle 反复变动，毫无益处。
• 移动文件而非复制。 Harvest 是复制操作。宿主仍保留其技能。harvest 之后不要对源文件执行 rm -rf。
• 批量 harvest（一次多个技能）。 不受支持，原因充分：每个技能的编辑审阅都是实实在在的工作。

何时调用

• 用户在其宿主分支（你的 OpenClaw 或任何私有下游分支）中开发了一个技能，并希望其他 gbrain 客户端也能使用它
• 某个技能已在生产中证明了自身价值，并准备好进行通用化
• 用户明确要求将技能“harvest”或“发布”到上游

以下情况不要调用：

• 技能在本地仍在变动中，应先让其稳定
• 技能引用了无法通用化的私有内容
• 用户只想分享一份一次性草稿（应改用 gist）

前置条件

运行此 skill 之前，请确认：

1. 该 skill 已经成熟。 近期的 routing-eval.jsonl 用例均能通过；该 skill 已在生产环境中至少使用过几次。

2. 该 skill 具有通用性。 在脑中做一次去特定化测试：把每个 fork 专属名称都替换掉，它作为 skill 是否依然成立？

3. 用户拥有 gbrain 检出副本。 收割操作会写入 gbrain 的工作树，由用户审阅并提交。不要把内容收割到用户并不打算从中提交的检出副本里。

工作流程

阶段 1 — 规划

询问用户：

• 收割得到的 skill 应使用什么 slug？（slug 必须为 kebab-case，并且在 gbrain 包中全局唯一。）
• 源宿主仓库是哪一个？（应为仓库根目录的路径，而不是 skill 目录的路径，例如 ~/git/agent-fork，而非 ~/git/agent-fork/skills/foo。）
• 配对的源文件是否需要一并带上？（检查宿主 SKILL.md 前置元数据中的 sources: 数组。）

阶段 2 — 试运行与隐私检查预览

使用 --dry-run 运行 CLI：

gbrain skillpack harvest <slug> --from <host-repo-root> --dry-run

输出内容包括：

• 哪些文件会被写入 gbrain 的目录树
• 是否包含配对的源文件
• （隐含）skill 前置元数据中的触发条件——请阅读并检查它们是否具有通用性

不要跳过试运行。隐私检查器只会在真正的收割时运行，但试运行预览可以让你在文件落地之前查看它们。请抽查 SKILL.md 以及任何配对源文件，查找隐私检查器可能漏掉的内容（专有名词、内部项目名称等）。

阶段 3 — 通用化检查清单（编辑审阅步骤）

在运行真正的收割之前，逐一检查宿主 skills/<slug>/ 下的文件，并应用此清单。如果有任何匹配项，请先编辑宿主文件，然后再运行收割。

1. fork 专属名称 → 通用表述

   • <personal-fork-name> → your OpenClaw（或 OpenClaw deployment）；用户私人 Agent 的任何昵称都做同样处理
   • 个人的名字（如 garry、jane 等）→ the user / you / 通用占位词

2. 真实实体 → 占位符

   • 真实的人物、公司、交易、基金 → 占位 slug（alice-example、acme-example、fund-a 等）
   • 电子邮件地址 → 整体删除，或使用 [email protected]
   • 内部 Slack 频道 → #some-channel 或直接删除
   • 具体的工单系统 ID / Linear 工单编号 → 删除

3. fork 专属约定 → 引用

   • 提及 <host-repo>/docs/... 文件的内容 → 要么将该文档纳入 gbrain，要么替换为通用的占位说明
   • 提及 <host-repo>/skills/<other-fork-only-skill> → 要么决定一并收割该 skill，要么替换为通用模式的引用

4. triggers 数组具有通用性

   • 逐条阅读前置元数据中的 triggers:。其中不应出现用户姓名、fork 名称或内部工具名称。
   • “Have garry sign off on it” → “have the user sign off on it”

5. routing-eval.jsonl 示例已脱敏

   • 打开 skills/<slug>/routing-eval.jsonl。每个 intent 字段都需要与 triggers: 做同样的脱敏处理。

6. 代码注释与日志字符串

   • 如果要收割配对的源代码，请逐行检查其中是否存在同样的私有信息泄露。注释是最常见的藏匿位置。

Phase 4 — 正式收割

Phase 3 完成后，运行正式收割：

gbrain skillpack harvest <slug> --from <host-repo-root>

默认行为：

• 文件复制时进行路径限制与符号链接拒绝
• 隐私检查器会针对 ~/.gbrain/harvest-private-patterns.txt 运行 （以及内置默认规则：规范的私有分支名称、电子邮件地址、Slack 频道；参见 src/core/skillpack/harvest-lint.ts）
• 一旦命中任何匹配 → 回滚（删除已收割的文件）并以非零状态退出
• openclaw.plugin.json 会被更新，按排序加入该 slug

结果：

• harvested —— 成功，清单已更新，文件位于 gbrain 目录树中
• lint_failed —— 隐私检查器发现了问题。返回 Phase 3，清理宿主文件后重试。
• slug_collision —— gbrain 中已存在该 slug 的技能。可以改用其他 slug，或者如果确实要替换，传入 --overwrite-local。

Phase 5 — 在 gbrain 中验证

成功收割后：

1. bun test test/skills-conformance.test.ts —— 确认新的 SKILL.md 符合 frontmatter 约定。
2. gbrain skillpack check --strict —— 确认捆绑包与 gbrain 自身检出目录之间没有偏差。
3. gbrain skillpack list —— 确认该 slug 出现在捆绑包中。
4. 检查差异：cd <gbrainRoot> && git diff -- skills/<slug>/
5. 在 gbrain 中提交新增内容（不要提交宿主仓库中残留的任何文件，收割是复制，不是移动）。

Phase 6 — 下游公告（可选）

如果其他 gbrain 客户端应当获取新技能：

• 在下一个版本的 CHANGELOG.md 中，于 "Skills added" 下记录此变更
• 如果该技能来自核心团队之外的人，在 PR 中 @ 对方用户或贡献者

绕过：--no-lint

隐私检查器是安全网，编辑审校才是主要防线。如果你已彻底完成 Phase 3，而检查器仍对误报触发，可使用 --no-lint：

gbrain skillpack harvest <slug> --from <host-repo-root> --no-lint

请在提交信息中记录绕过原因。 未来的维护者应当能看出为何绕过了检查（例如"该分支名称出现在引用中，并非真实指代，已人工核实"）。

切勿随意绕过检查器。默认开启检查的全部意义在于：真实名称偶尔会漏过编辑审校。

收割不会做的事

• 它不会移动文件（而是复制）。宿主的 skills/<slug>/ 保持原位。
• 它不会自动清除名称。编辑审校由人工完成。
• 它不会发布到 npm 或远程捆绑包。它写入 gbrain 的工作树；用户通过常规 gbrain 发布流程提交并发布。
• 它不支持 --all（不做批量收割）。每次一个技能，才能让编辑审阅保持可控。

本技能涉及的文件

• gbrain 的 skills/<slug>/ —— 宿主技能目录中的每个文件（复制）
• 已声明配对源的 gbrain 镜像路径 （例如宿主 SKILL.md 在 frontmatter 中声明了 src/commands/<slug>.ts 时）
• gbrain 的 openclaw.plugin.json —— 将 slug 按字母顺序加入 skills: 数组，且不删除 id、configSchema、contracts 等 OpenClaw 原生插件字段