Hive 框架 Bounty 贡献者指南:从领取赏金到晋升 Core Contributor 的完整实战手册
Hive 框架 Bounty 贡献者指南:从领取赏金到晋升 Core Contributor 的完整实战手册
本文是 Hive(Multi-Agent Harness for Production AI)开源仓库中 docs/bounty-program/contributor-guide.md 的深度展开版。它面向希望参与 Hive 生态共建的开发者,系统讲解赏金(Bounty)计划的完整参与链路:如何完成 GitHub 与 Discord 身份绑定、如何认领并交付各类型赏金、积分与角色晋升机制,以及每条路径背后对应的真实代码位置(工具实现、凭证规格、健康检查器、自动化计分脚本等)。读完本文,你将能够独立完成"测试工具 → 撰写文档 → 提交代码修复 → 构建全新集成 → 推动工具晋升 verified"的完整贡献流程。
一、Bounty 计划概览:为什么值得参与
Hive 的 Bounty 计划通过 GitHub Issues 承载任务、通过 Discord(Lurkr 机器人)结算积分与角色,为贡献者提供了从"快速修复"到"重大功能"的阶梯式回报路径:
- XP 与 Discord 角色:PR 合并后由 GitHub Action 自动推送 XP 到 Discord,达到等级自动解锁角色;
- 可见的荣誉:工具晋升 verified 后,贡献者的 GitHub 昵称会写入该工具 README 的
Contributed by字段,永久保留在生产级代码库中; - 通向付费之路:Core Contributor 由维护者提名,解锁按完成次数计费的美元赏金(具体流程见 docs/bounty-program/game-master-manual.md)。
整个计划的落地机制可以追溯至仓库内的自动化实现:scripts/bounty-tracker.ts 负责积分计算与排行榜生成,.github/workflows/bounty-completed.yml 在带 bounty:* 标签的 PR 合并后触发流程:读取标签 → 计算分值 → 通过 MongoDB hive.contributors 集合解析 GitHub→Discord 映射 → 调用 Lurkr API 推送 XP → 向 #integrations-announcements 发送通知。
二、第一步:绑定 GitHub 与 Discord 身份
在领取任何赏金之前,必须先打通身份链路,否则 Lurkr 无法把 XP 推送到你的 Discord 账户:
- 在 Discord 服务器中运行
/link-github your-github-username; - 机器人会返回一个验证码,请创建一个公开 Gist 填入该验证码;
- 运行
/verify完成绑定。
从源码看,这一步的产物是 GitHub→Discord 的映射,最终被持久化到 MongoDB 的 hive.contributors 集合(参见 docs/bounty-program/README.md 中的 "Identity Linking" 与 scripts/bounty-tracker.ts 中 Contributor 接口的 github/discord 字段)。即使未绑定,GitHub 侧的贡献记录依然有效,但会缺失 Lurkr XP 与 Discord 角色。
三、认领第一个赏金:从何入手
- 浏览 GitHub Issues 中带
bounty:*标签的开放任务; - 新手优先选择
bounty:docs或difficulty:easy标签的任务; - 在 Issue 下评论 "I'd like to work on this"(我想认领此任务),等待维护者将任务分配给你,不要未经认领直接开工;
- 每次最多同时持有 3 个未完成的认领,避免囤积任务。
仓库为难度打了标签:difficulty:easy(良好的首次贡献入口)、difficulty:medium(需要一定熟悉度)、difficulty:hard(显著工作量或专业经验),见 docs/bounty-program/README.md 的 Labels 一节。
四、贡献者层级:积分如何转化为身份
| 层级 | 达成条件 | 回报 |
|---|---|---|
| Agent Builder | 约 500 XP(Lurkr 5 级) | Discord 角色、赏金面板访问权 |
| Open Source Contributor | 约 2,000 XP(Lurkr 15 级) | Discord 角色、名字写入 CONTRIBUTORS.md 与工具 README |
| Core Contributor | 维护者提名 | 赏金附带美元标价、按完成付费 |
XP 来源有两个:GitHub 赏金(PR 合并后自动推送)与 #integrations-help 频道的 Discord 活跃度。前两个角色由 Lurkr 自动分配;Core Contributor 需要跨多个赏金类型持续贡献(文档建议 4 周以上),并由维护者担保提名。排行榜每周一由机器人自动发布到 #integrations-announcements,前 3 名获得奖牌 emoji,随时可用 /rank 查询自己的排名。
五、赏金类型总览
赏金分为两大类别:
- Integration Bounties(集成赏金):面向工具生态,包括测试、文档、代码贡献与全新集成;
- Standard Bounties(标准赏金):面向框架本身的一般性贡献,按工作量与影响面分档。
两类任务在工具晋升流程上是贯通的:工具从 unverified(未验证)晋升到 verified(已验证)是集成类贡献的最终目标,须完成 docs/bounty-program/promotion-checklist.md 中的全部必选项,由维护者把注册从 _register_unverified() 移动到 _register_verified()(位于 tools/src/aden_tools/tools/init.py)。
5.1 集成赏金
测试一个工具(20 分)
用真实 API Key 测试未验证工具并汇报结果:
- 获取服务的 API Key(赏金 Issue 中会附带申请入口;多数服务提供免费额度);
- 用真实数据运行工具函数;
- 按 docs/bounty-program/templates/agent-test-report-template.md 填写测试报告;
- 以 Issue 评论或 PR 内文件形式提交。
报告既记录成功也记录失败——发现 Bug 本身就是有价值的产出。报告模板要求覆盖:工具名、测试者、日期、结论(Pass/Partial/Fail)、环境(OS/Python/Hive 版本/API 层级)、凭证设置方式与健康检查结果、Agent 工作流测试(含 Session ID)、发现的边界情况(表格列 Edge Case / Behavior / Severity)、问题清单与改进建议,最后附上日志或截图作为证据。
撰写文档(20 分)
为缺失 README 的工具补齐文档:
- 阅读 tools/src/aden_tools/tools/{tool_name}/ 下该工具的源码;
- 阅读 tools/src/aden_tools/credentials/ 中的凭证规格;
- 按 docs/bounty-program/templates/tool-readme-template.md 填写;
- 提交 PR,在工具目录新增
README.md。
模板要求的内容包括:工具一句话简介与典型用途、Setup 小节(export {ENV_VAR}=your-api-key 及获取 Key 的分步指引、可选 CredentialStoreAdapter 方式)、工具函数表格(Tool / Description)、每个函数的 Python 调用示例与返回值说明、Scope(当前覆盖能力)、Rate Limits 表格(如适用)、以及官方 API 文档链接。特别要求:函数名与 API 地址必须与实际一致,禁止 AI 幻觉。
代码贡献(30 分)
包括添加健康检查器、修复 Bug 或改进集成。
健康检查器(Health Checker)路径:
- 找到一个轻量的、可校验凭证的 API 端点(GET 请求、无写入副作用);
- 在工具的
CredentialSpec中添加health_check_endpoint字段; - 在 tools/src/aden_tools/credentials/health_check.py 中实现
HealthChecker类; - 注册进
HEALTH_CHECKERS字典,运行uv run pytest tools/tests/test_credential_registry.py验证。
Bug 修复路径:
- 测试中发现 Bug 先提 Issue;
- 用 PR 修复,并附带覆盖该 Bug 的测试用例。
全新集成(75 分)
从零构建完整集成:
- 遵循 tools/BUILDING_TOOLS.md 指南;
- 产出物包括:工具 + 凭证规格(CredentialSpec)+ 健康检查器 + 测试 + README;
- 在 tools/src/aden_tools/tools/init.py 的
_register_unverified()中注册; - 运行
make check && make test。
预期会经历多轮 Review。
5.2 标准赏金
Small(10 分)
快速、聚焦的修复,适合首次贡献者:
- 修复文档中的错别字或失效链接;
- 改进错误消息,加入可操作的指引;
- 为模块补充缺失的类型注解;
- 复现并确认 Bug 报告(附环境细节);
- 修复 lint 或 CI 警告。
方式:直接开 PR,打上 bounty:small 标签。
Medium(30 分)
需要阅读理解既有代码的有意义改进:
- 修复非关键 Bug 并附带回归测试;
- 撰写 how-to 指南或教程;
- 为核心模块新增或显著提升测试覆盖;
- 改进 CLI 帮助文本、参数校验或 UX;
- 为模块增加结构化日志或可观测性。
方式:先在 Issue 认领,提交带测试的 PR,打 bounty:medium 标签。
Large(75 分)
显著提升项目能力的重要工作:
- 端到端实现新的用户可见功能;
- 带前后基准数据的性能优化;
- 新增 CLI 命令或子命令;
- 为子系统撰写完整架构文档;
- 新增凭证适配器类型(credential adapter type)。
方式:先认领 Issue,并在开工前于 Issue 中讨论方案,提交 PR 时打 bounty:large 标签。
Extreme(150 分)
塑造项目方向的重磅贡献,必须经维护者预先批准:
- 设计并实现重大子系统(如插件系统、缓存层);
- 对核心模块做安全审计并给出发现与修复;
- 核心架构的大规模重构;
- 构建完整的示例应用或参考实现;
- 为 Agent 工作流建设端到端测试框架。
方式:在 Issue 中评论设计提案,等待维护者批准后再开工,PR 打 bounty:extreme 标签。
六、硬性规则:认领、时限与质量门槛
- 先认领再开工——评论 Issue、等待分配;
- 7 天窗口——认领后 7 天内无 PR,赏金将被重新开放;
- 最多 3 个活跃认领——禁止囤积;
- 质量优先——PR 必须通过 CI 并遵循模板;
- 禁止自我审查、禁止未经验证的纯 AI 提交——维护者合并 PR,不允许自合并,也不允许把一个改动拆成多个 PR 刷分。
从代码层面看,"质量门槛"由两套机制兜底:其一是 tools/BUILDING_TOOLS.md 中描述的 CI 一致性测试(tests/integrations/test_spec_conformance.py,覆盖 TestModuleStructure、TestRegisterToolsSignature、TestCredentialSpecFields、TestSpecToolsMatchRegistered、TestCredentialCoverage,其中 TestCredentialCoverage 会强制"凡 register_tools 带 credentials 参数的工具,其名称必须出现在某个 CredentialSpec.tools 列表中");其二是 tools/tests/test_credential_registry.py 中的注册表完整性测试(如 TestRegistryCompleteness、TestSpecRequiredFields、TestNoDuplicateEnvVars),校验"有 health_check_endpoint 的规格必有对应检查器""env_var 不冲突"等不变量。
七、工具晋升:从 unverified 到 verified
这是一个值得单独强调的终局路径,也是测试、文档、代码三类集成赏金成果的汇聚点(详见 docs/bounty-program/promotion-checklist.md):
必选项包括:
- 代码质量:
register_tools遵循标准签名;所有工具以{"error": ...}字典返回错误而非抛异常;凭证缺失时优雅降级并提供可操作的"help"消息;调用 API 前先做输入校验;无硬编码密钥; - 凭证规格:
CredentialSpec存在于 tools/src/aden_tools/credentials/{category}.py;env_var唯一;tools列表覆盖模块注册的全部函数;help_url指向 Key 申请页;credential_id/credential_key已设置;规格已合并进 tools/src/aden_tools/credentials/init.py 的CREDENTIAL_SPECS; - 健康检查:
health_check_endpoint已设置;HealthChecker类已实现并注册进HEALTH_CHECKERS;正确区分 200(有效)、401(无效/过期)、429(限流但有效);uv run pytest tools/tests/test_credential_registry.py -v通过; - 文档:工具目录含遵循模板的 README,含 Setup 说明、工具函数表格、每函数至少一个使用示例、API 参考链接;
- 测试:tools/tests/tools/test_{tool_name}.py 存在单测,mock 外部 API(不做真实调用),覆盖每个函数的 happy path 与错误路径(缺凭证、非法输入、API 错误);
make check && make test通过; - 社区测试:至少 1 名社区成员用真实 API Key 测试过,提交了按模板填写的测试报告,工具在真实 Agent 工作流中可用,且无阻塞性问题。
晋升流程:贡献者开 PR 勾选全部必选项 → PR 描述附 README、健康检查器、测试报告链接 → 维护者逐项核验 → 维护者将注册从 _register_unverified() 移到 _register_verified()(tools/src/aden_tools/tools/init.py)→ 维护者给 PR 添加 bounty:code 标签触发 XP 自动发放 → #integrations-announcements 自动播报。
在 tools/src/aden_tools/tools/init.py 中可以看到这一机制的实现细节:_VERIFIED_TOOL_NAMES 集合记录 verified 工具名,_register_verified() 注册稳定工具(web_search、github、email、slack、google_sheets 等),_register_unverified() 注册待验证工具;通过 __aden_verified_manifest 哨兵工具,下游注册表(如 queen 的 MCP loader)可以按 verified 状态对免费/无凭证工具做门控。
关于健康检查器的实现深度
以 tools/src/aden_tools/credentials/health_check.py 为参照,一个合格的检查器通常基于以下骨架:
HealthCheckResult数据类:valid(是否有效)、message(人类可读状态)、details(附加信息,如状态码、限流标记);CredentialHealthChecker协议:check(credential_value) -> HealthCheckResult;- 针对不同认证方式的具体实现,例如
BraveSearchHealthChecker(X-Subscription-Token头 +q=test&count=1最小请求)、HubSpotHealthChecker(Bearer+ 单条 contacts 请求)、ZohoCRMHealthChecker(对 429 返回valid=True并标记rate_limited)、GitHubHealthChecker(GET /user)、SlackHealthChecker(auth.test)、DiscordHealthChecker(GET /users/@me,Bot前缀)等; BaseHttpHealthChecker基类:用类常量(ENDPOINT、SERVICE_NAME、AUTH_TYPE、VALID_STATUSES、RATE_LIMITED_STATUSES、INVALID_STATUSES、FORBIDDEN_STATUSES等)减少样板代码,支持 Bearer、自定义 Header、Query 参数、Basic Auth、URL 模板五种认证模式,且会在错误消息中脱敏 Bearer/Authorization/token 等敏感信息;OAuthBearerHealthChecker:通用的 Bearer 令牌检查器,同时作为"规格定义了health_check_endpoint但无专属检查器"时的自动兜底。
八、FAQ 速查
Q:测试每个工具都需要 API Key 吗? A:是的。多数服务有免费额度,赏金 Issue 中会给出 Key 申请入口。
Q:如何成为 Core Contributor? A:连续 4 周以上跨不同类型稳定贡献,维护者会提名。
Q:还没绑定 Discord 怎么办?
A:GitHub 侧贡献仍会被记录,但不会有 Lurkr XP 和 Discord 角色。在 Discord 中运行 /link-github 即可补齐。
九、快速参考
| 内容 | 仓库位置 |
|---|---|
| 工具 README 模板 | docs/bounty-program/templates/tool-readme-template.md |
| 测试报告模板 | docs/bounty-program/templates/agent-test-report-template.md |
| 晋升检查清单 | docs/bounty-program/promotion-checklist.md |
| 工具构建指南 | tools/BUILDING_TOOLS.md |
| 健康检查器实现 | tools/src/aden_tools/credentials/health_check.py |
| 凭证规格聚合 | tools/src/aden_tools/credentials/init.py |
| 工具注册(verified/unverified) | tools/src/aden_tools/tools/init.py |
| 注册表完整性测试 | tools/tests/test_credential_registry.py |
| 积分计算与排行榜脚本 | scripts/bounty-tracker.ts |
| 管理员搭建指南 | docs/bounty-program/setup-guide.md |
| 维护者操作手册 | docs/bounty-program/game-master-manual.md |
| 计划总览(含标签颜色、自动化链路) | docs/bounty-program/README.md |
十、推荐的上手路线
对于刚接触 Hive Bounty 计划的开发者,推荐的实践顺序是:
- 完成
/link-github身份绑定; - 从
bounty:docs或difficulty:easy入手,先阅读 tools/src/aden_tools/tools/ 下某个工具的源码与对应CredentialSpec,用模板补齐 README——这是熟悉工具生态成本最低的方式; - 申请一个
bounty:test任务,用真实 API Key 走一遍工具并提交测试报告,为后续晋升提供社区测试证据; - 尝试
bounty:code:参照 health_check.py 中现有检查器为工具补健康检查,并让uv run pytest tools/tests/test_credential_registry.py全绿; - 当 README、健康检查、测试报告齐备后,推动该工具按 promotion-checklist.md 晋升 verified——你的 GitHub 昵称将随该工具永久留在生产代码库中。
每一步的产出都有明确的验收标准与对应的仓库文件可以对照,这使得 Hive 的 Bounty 计划不仅是一个激励计划,更是一套可审计、可自动化的开源协作流水线。