SuperAPI AI 工具集

contribute-skill

编程与开发

查看项目

更新于 10-15 17:52

技能介绍

用途

contribute-skill 用于把本地改修过的 skills/<skill-name>/ 目录,作为 PR 提交到 skills-lock.json 中记录的上游仓库(例如 Fandhe-AI/agent-cli-skills)。

它与 create-pr 的职责相互分离:

  • create-pr:在当前仓库内,从当前分支向 base 创建 PR。
  • contribute-skill:面向另一个仓库(upstream),执行 clone → 变更反映 → push → PR 创建。

由于外部仓库贡献涉及 clone、路径转换以及不同的认证边界,因此被拆分为独立技能。

前提条件

  • 已安装并认证 gh CLI(需要对目标 org 具有 push / PR 权限)。
  • 目标技能已登记在 skills-lock.json 中并带有 source。未登记、source 缺失、lock 不存在或解析失败时,脚本会在 clone 之前中止。新技能的首次贡献不在本技能范围内。
  • 目标技能目录下的内容与最新提交一致。存在未提交变更、未跟踪文件或 ignore 对象文件时,脚本会在 clone 之前中止。目标技能以外的位置发生的变更不会被检查。

主要流程

Step 1:校验参数

  • 若参数为空,则不进行路径解析,列出 skills/、.agents/skills/、.claude/skills/(仅实际目录,symlink 会在实体侧候选中出现,因此排除)的候选列表后退出。
  • 对技能名进行 kebab-case 校验(防止路径穿越),在路径解析之前执行。
  • 若环境变量 LOCAL_SKILL_DIR 已设置,则校验其是否为允许的三个路径之一、路径的所有元素(含中间父目录)均非 symlink、且实际存在,然后采用并跳过自动解析。
  • 自动解析时,若 skills/、.agents/skills/、.claude/skills/ 中存在多个实体目录,则中止,并提示通过环境变量 LOCAL_SKILL_DIR 指定改修对象路径后重新执行(不会静默优先选择 skills/)。

Step 2:确定 upstream

  • 读取根目录的 skills-lock.json,取出 skills.<SKILL_NAME>.source。
  • 未登记或 source 缺失时 fail-closed 中止。
  • 安全阀:拒绝向 Fandhe-AI org 以外的仓库 push。先做规范化(URL 形式转换为 OWNER/REPO,短形式直接采用),去除末尾 .git,再进行严格校验:owner 固定为 Fandhe-AI,repo 仅允许单段 [A-Za-z0-9._-]+。
  • 含 ../ 的路径穿越、查询(?x=1)、片段(#frag)、多余路径段(/extra)等值均不匹配正则,会报错中止。
  • sourceType 非 github 时也报错中止。
  • 规范化后的 REPO_SLUG 会在后续步骤中用于 gh repo clone 与 gh pr create --repo。

Step 3:确认变更内容

  • 先确认复制来源与 HEAD 一致。使用 git status --porcelain=v1 --untracked-files=all --ignored 检查目标目录,非零退出或存在输出时中止。
  • 显示 git log --oneline 与 git diff(无父提交时与空树比较)。
  • 检查中止时,Claude 不会自动 stash、删除或提交,而是向用户展示列出的路径,由用户选择处理方式(提交或移除)后重新执行。
  • 向用户确认「是否以此改修内容向上游创建 PR」。

Step 4:安全检查(必须)

与 create-pr 相同,审查以下内容:

  • 认证、授权实现遗漏
  • API 密钥、机密信息的硬编码
  • XSS 可能性(文档中若含外部嵌入)
  • 输入校验缺失
  • OWASP Top 10

发现问题时中止上游贡献并向用户告警。

Step 5:反映变更

  • skills-contribute.sh 自行完成从 upstream 的 gh repo clone 到工作目录(WORKDIR)创建与反映的全过程,无需手动预先 clone。
  • 本步骤必须执行本技能自身的脚本 skills-contribute.sh,不要单独逐条执行片段。该脚本内置了 rm -rf 前的 symlink 边界校验(含 TOCTOU 对策)。
  • 脚本内部判定 upstream 侧技能所处的路径结构(UPSTREAM_SKILL_PATH;skills-lock.json 的 skillPath 是本地 install 路径,并非 upstream 内配置,因此不使用),并执行 cp -R 的 delete-then-copy 反映。
  • LOCAL_SKILL_DIR 是 Step 1 解析出的贡献对象技能路径,与本技能(contribute-skill)自身的配置无关。执行脚本自身的配置应通过另一变量 CONTRIBUTE_SKILL_DIR,从本技能自身的安装位置解析。
  • 脚本以调用时的当前目录作为贡献源仓库根目录,探索 LOCAL_SKILL_DIR 与 skills-lock.json,并在内部新建自身的 gh repo clone 与 WORKDIR。执行前需在本步骤内捕获 ORIG_DIR(贡献源本地仓库根目录)。
  • 捕获脚本标准输出最后几行返回的 CONTRIBUTE_SKILL_WORKDIR=<path> 与 CONTRIBUTE_SKILL_UPSTREAM_PATH=<path>,后续步骤中 ${WORKDIR}/upstream 与 ${UPSTREAM_SKILL_PATH} 仅以这些值为唯一准绳。
  • 获取默认分支(用于 Step 8 的 gh pr create --base)。origin/HEAD 未设置时 symbolic-ref 会非零退出,因此用 || true 吸收。

适用场景

  • 在本地改修了某个已登记技能目录,希望将其作为 PR 提交回上游 Fandhe-AI 组织下的仓库。
  • 需要与当前仓库内的 create-pr 区分开,面向外部仓库进行贡献。

限制

  • 仅支持向 Fandhe-AI org 下的仓库 push,其他 org 会被安全阀拒绝。
  • 仅支持 sourceType 为 github 的 source。
  • 新技能的首次贡献不在本技能范围内。
  • 目标技能必须已登记在 skills-lock.json 中且带有 source。
  • 目标技能目录必须与最新提交一致,存在未提交、未跟踪或 ignore 对象文件时会中止。
  • 关于收费、价格、平台支持范围、具体效果等,资料中暂未提供。