distribute-tokens

用途

distribute-tokens 是一个面向开源项目贡献者的链上奖励发放技能，覆盖“谁该拿多少（计划）”与“把钱发出去（发送）”两个环节。它把已合并 PR 的贡献者排名转化为分级定价的发放清单，并通过 Bankr Wallet API 在 Base 链上执行转账。

通过 GitHub API 统计目标 ISO 周内合并的 PR，按作者聚合，剔除机器人账号（[bot]、dependabot、github-actions*）。
按合并 PR 数量降序排名，数量相同则按最早合并时间、再按登录名升序打破平局。
分级定价：第1名 25 USDC、第2名 15 USDC、第3名 10 USDC、第4-5名 5 USDC。
首次 PR 奖励：对首次向该仓库合并 PR 的登录名追加 +5 USDC，每个登录名仅一次，记录在 memory/state/contributor-reward-state.json。
资格门槛：排名 ≤ 5 且至少有一个合并 PR。
将结果写入 memory/distributions.yml 中带标签的列表（如 contributors-2026-W17），并更新计划幂等状态文件。
支持重复处理：若同一周已处理，则对比差异，仅对新增或金额上调的条目补发差额，不追回已降级条目。

从 memory/distributions.yml 读取指定列表（空标签则取第一个列表）。
两阶段执行：RESOLVE（校验配置、密钥、余额，解析所有 handle 为地址，构建计划）→ EXECUTE（逐笔发送，每笔后持久化状态）。RESOLVE 失败会在任何发送前中止。
幂等性：以 (列表, 收件人, UTC 日期) 为键在 memory/state/distributions.json 中记录 txHash，同一 UTC 日内成功的转账不会重复发送，即使重跑或工作流重启。
dry-run 模式输出完整计划但不执行转账。
实际转账仅使用 Bankr Wallet API（其文档已弃用 Agent API 用于转账）；Agent API 仅用于 handle→地址解析。
若 memory/distributions.yml 缺失，会写入带注释的模板并干净退出，提示编辑后重跑。

通过变量选择器控制阶段与目标，语法为 [plan:|all:][dry-run:]<target>：

空 / <label> / dry-run:<label> → 发送阶段：从 memory/distributions.yml 发放列表（空 = 第一个列表）。
plan: / plan:<week> / plan:dry-run / plan:dry-run:<week> → 仅计划阶段。
all: / all:<week> / all:dry-run / all:dry-run:<week> → 先计划再发送。
<label> 为发放列表标签（如 contributors-2026-W17）；<week> 为 ISO 周（如 2026-W17），留空表示最近一个完整 ISO 周。
dry-run: 仅预览，无副作用（计划阶段不写 yml/状态，发送阶段不转账）。

所需密钥：BANKR_API_KEY（bk_...），需具备读写权限并启用 Wallet API；只读密钥会返回 403。计划阶段为纯本地文件 I/O，不需要该密钥。

Base 链代币地址：USDC 为 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913；ETH（原生）tokenAddress 为 0x0000000000000000000000000000000000000000，isNativeToken 为 true。

配置与状态文件：