Skip to content

About

给任意开源项目提一个维护者愿意合的 PR:读懂上游规矩 → 挖真实信号 → 最小改动 → 跑上游检查 → 开 PR → 跟 CI 与 review

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

6 Commits

Folders and files

Repository files navigation

🔀 PR Contributor

个人仓代码交付与外部贡献的统一技能。自有 GitHub/GitLab 仓从隔离修改一直验收到远端主干;外部项目遵循上游规则,跟进 PR/MR。基础交付工具只需要 Git 和 Python 3.9+,不依赖任何私有系统。

个人仓交付(0.2.0)

# 公开仓无需账号即可下载;也可自行改用 SSH 克隆。
git clone https://github.com/webkubor/pr-contributor-skill.git
cd pr-contributor-skill
bash install.sh --target hermes  # 覆盖已有默认 home 与 profile
# 自定义框架目录也可:bash install.sh --skills-dir /absolute/path/to/skills
python3 scripts/delivery.py audit --repo /path/to/project --base main --json
python3 scripts/delivery.py verify --repo /path/to/project --base main
python3 scripts/delivery.py receipt --repo /path/to/project --base main \
  --output /path/outside/project/receipt.json

审计遍历 Git 登记的全部 worktree,包括仓外目录;区分未提交、只在本地、远端分支已保存、目标主干已交付。刷新远端失败返回 unknown;离线缓存永远不能证明交付成功。audit 完整取证返回 0 不代表无待办,verify/receipt 对待办返回 1、未知返回 2。

回执包含主机/仓库与工作目录信息,应留在私有运维目录。其他任务的 WIP 会阻止全仓 verify 通过,需按归属核实,不能自动提交或删除。工具不隐式推送、合并、部署或回收。

完整执行流程见 个人仓交付。公司仓保留公司流程;外部贡献的严格限制只作用于外部模式。不同机器从远端取得同一版本,无需共享任何私有 API 或工具。

这个仓同时是「技能安装器」的规范源

scripts/install_skill.py 不只是本仓的安装脚本 —— 它是 webkubor 名下所有技能仓 安装器的公开规范源。其他仓(charmoji / deadcode-reaper / logo-brand-designer / release-sync)同步同一份文件;本机总控由 CortexOS 的 cs skill install 负责:

https://raw.githubusercontent.com/webkubor/pr-contributor-skill/main/scripts/install_skill.py

为什么要有规范源:技能仓各自独立发布,仓与仓之间不能互相依赖,安装器只能复制过去。 复制就会漂移 —— 改了这里忘了同步某个仓,那个仓的安装行为就悄悄变成旧的, 没有报错、没有告警,只是「某个仓装出来的样子跟别的不一样」。

漂移怎么防:各仓 CI 校验提交时固定的安装器摘要;CortexOS 的 node scripts/skill/check-installer-copies.mjs 跨仓比对规范源, 修改本文件后运行该检查的 --fix 选项分发,再分别提交各仓。

安装器本身无任何包名硬编码(marker / stage 前缀 / 备份路径都从 skill 名派生), 所以同一份文件拷到任何技能包里都能正确工作。

release skill version MIT node any agent

给开源项目提一个维护者愿意合的 PR。
读懂上游规矩 → 从真实信号里挖出该改的点 → 最小改动 → 跑上游自己的检查 → 开 PR → 跟到合。

安装 · 为什么需要它 · 它做什么 · 快速开始 · 参考文档


Why This

Agent 写代码很强,但提 PR 是另一门手艺。会写代码 ≠ 会贡献。

让 Agent 直接提 PR PR Contributor
改什么 Agent 自己挑「看着能改」的地方 只从外部可见信号里选(issue / CI 红 / 用户报错 / 文档不一致)
上游规矩 提完才知道有 CONTRIBUTING 动手前先读出来(提交格式 / 分支名 / DCO / 必跑门禁)
改动范围 容易夹带无关重构 越界文件(CI 配置、许可证、lock)机械拦下
PR 正文 复制 commit message 五块结构模板,维护者 30 秒能判断
CI 挂了 不知道看哪 排障手册 + 区分「确定性失败」和「环境抖动」
被 review 打回 不知道怎么回 逐条回应模板,给证据不争论

一句话:把「提了个维护者不想要的 PR」这个最大失败模式,变成流程里可判定、可拦截的环节。


为什么需要它

真实的上游贡献,失败很少发生在「代码写错了」,绝大多数发生在提交前的判断:

  • 提了纯格式化 PR —— 维护者直接 close,你在这个 repo 的信誉归零
  • 改了 package-lock.json —— 噪音,没人想 review
  • 没跑上游的 lint/typecheck —— CI 才炸,浪费维护者一轮 CI 配额
  • 正文只写「修复了 bug」 —— 维护者得反问「怎么验证的」
  • 同一 issue 已经有别人的 PR —— 重复劳动,两边打架
  • 分支基于自己 fork 的旧版本 —— diff 里混着无关改动

这些每一条都能机械判定。所以本 skill 不写「要善于发现问题」这种废话,而是给出可执行的判据和可跑的脚本。


它做什么

七阶段闭环,每阶段都有可执行的入口:

阶段 做什么 入口
0 · 判定目标与权限 你是维护者?有没有写权限?仓归档了没?没有权限就别急着改代码 scripts/pr-preflight.sh
1 · 读懂项目 提交格式 / 分支名 / PR 标题 / 必跑门禁 / DCO·CLA —— 动手前全读出来 references/pr-conventions.md
2 · 挖信号 issue 标签、CI 失败、依赖告警、文档不一致、TODO —— 汇成带优先级的候选表 scripts/scan-contribution-signals.mjs
3 · 价值门禁 信号门 / 范围门 / 可验证门 / 相关门 —— 四道门任一不过就别提 SKILL.md §阶段 3
4 · 搭分支 fork + upstream 远端 + 从 upstream 默认分支开分支(不夹带旧 diff) scripts/setup-upstream.sh
5 · 写改动 同风格、最小、带回归测试、不碰生成物与密钥 SKILL.md §阶段 5
6 · 开 PR 五块结构正文 + 机械门禁(格式 / 越界 / 密钥 / 规模) scripts/pr-lint.mjs
7 · 跟进到终局 CI 排障、review 逐条回应、拆分、被 close 的处理 references/review-and-ci.md

三个脚本

# 0. 体检:鉴权 / 权限 / 仓库状态 / API 配额
bash scripts/pr-preflight.sh OWNER/REPO

# 2. 挖信号:候选表(纯只读,不改任何东西)
node scripts/scan-contribution-signals.mjs --repo OWNER/REPO

# 4. 接上游:fork + upstream + 从上游开分支(幂等)
bash scripts/setup-upstream.sh OWNER/REPO --branch fix/issue-123

# 6. 开 PR 前机械门禁
node scripts/pr-lint.mjs --title "fix(parser): ..." --body-file body.md --auto

脚本都是只读或幂等的:不会替你开 PR、不会评论 issue、不会改上游。


快速开始

# 1. 放进你的 Agent skill 目录
git clone git@github.com:webkubor/pr-contributor-skill.git
cp -r pr-contributor-skill ~/.claude/skills/pr-contributor

# 2. 体检目标仓
cd /path/to/target-repo && bash ~/.claude/skills/pr-contributor/scripts/pr-preflight.sh OWNER/REPO

# 3. 挖信号,看有哪些值得做的
node ~/.claude/skills/pr-contributor/scripts/scan-contribution-signals.mjs --repo OWNER/REPO

装到各个 Agent 框架

框架 位置 说明
Claude Code ~/.claude/skills/pr-contributor 软链或拷贝都行
Codex CLI ~/.codex/skills/pr-contributor 同上
通用 agents ~/.agents/skills/pr-contributor 多数新框架读这里
DeepSeek Harness ~/.dsh/skills/pr-contributor 或项目内 .dsh/skills/
Hermes 通过 external_dirs 指向本仓 见其配置

规范只有一条:目录里有 SKILL.md,Agent 从这里读起。所以任何框架都能用,不需要插件。

⚠️ 版本更新说明(重要)

软链安装的 skill 不会自动更新,也不会提示你更新。

各 Agent 读的是本地工作区(软链指向的 git clone),不会去 GitHub 拉。所以:

你的动作 会发生什么
在 GitHub 上推了新版本 Agent 不会主动提示,但维护者的机器有每日自动快进任务(launchd,07:17,只做 fast-forward)→ 第二天自动生效
想知道是不是最新版 bash scripts/check-update.sh(退出码 1 = 有更新)
想立刻更新 bash scripts/check-update.sh --update(只快进,不覆盖本地改动)
用 --copy 拷贝安装 永远不会更新,得手动重新拷贝

这是软链方案的固有边界,不是 bug —— 换来的是「改完真源,所有 Agent 立刻生效」。 代价是更新不会主动提示。两道保险:

  • 自动(维护者的机器):每日 launchd 快进,只做 fast-forward;本地有未推送提交就跳过并记录, 永不静默覆盖改动。
  • 手动(任何机器):check-update.sh 一条命令,不用记 git 命令。

给 Agent 使用者的提示:如果你觉得某个脚本行为和文档不符,先跑 check-update.sh, 可能是本地版本旧了 —— 先告知用户有更新、确认后再 --update,不要擅自更新。


参考文档

文档 何时读
references/finding-work.md 不知道该改什么 —— 信号源清单 + 挖掘流程 + 打分表
references/guardrails.md 哪些 PR 会被 close,以及越权文件怎么识别
references/pr-conventions.md 怎么把上游的提交格式 / 分支名 / DCO / 门禁探测出来
references/pr-description.md 标题与正文怎么写(含正反例)
references/review-and-ci.md CI 挂了怎么排、review 意见怎么回

模板在 templates/:PR 正文五块结构、提交信息、标题候选。


设计原则

  1. 只从真实信号起手 —— 没有外部可见理由的改动,不提。
  2. 机械能判的交给机器 —— 格式、越界、密钥、规模,让脚本拦,不靠 Agent 自觉。
  3. 价值判断留给人和有判断力的 Agent —— 脚本不替你决定「这个改动值不值得」。
  4. 不越权 —— CI 配置、许可证、治理文件、发布流程,一律先在 issue 里问。
  5. 每条规则都带命令 —— 规则不能落到命令上,就等于没有。

许可

MIT © webkubor

About

给任意开源项目提一个维护者愿意合的 PR:读懂上游规矩 → 挖真实信号 → 最小改动 → 跑上游检查 → 开 PR → 跟 CI 与 review

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages