contribbot /kənˈtrɪbɒt/，contrib + bot，两个 b 合并只读一个。
写给开源贡献者、仓库维护者、以及对开源贡献感兴趣的开发者。如果你同时维护多个仓库、需要追踪上游变更、和其他人协调谁在做什么——这个工具可能对你有用。
痛点
contribbot 起源于我参与 antdv-next 的维护经历。antdv-next 的上游是 ant-design——一个优秀的 React 组件库，我们要在 Vue 里实现对应的功能。
antdv-next 维护中的痛点：
- 跨栈追踪：ant-design 出了新功能，我要在 antdv-next 里实现 Vue 版本。但没有工具帮我追踪"哪些 React 功能还没有 Vue 版本"，只能手动翻 release notes 逐条对比
- 多人协调：一个 issue 里有多个任务，谁领了哪些？不是没人说，而是要自己去翻评论才能知道，效率很低
- 任务记录：我做到一半切到另一个项目，回来后忘了进度，得重新翻 GitHub issue 和 PR 理上下文。需要一个本地的 todo 系统，记录我在做什么、做到哪了
同时维护多个项目后发现的通用痛点：
- fork 二开：我 fork 了一个仓库做二次开发，在自己的分支上加了仅自己需要的功能。main 分支全量同步上游没问题，但二开分支怎么办？上游每次更新几十个 commit，哪些和我的二开有关需要 cherry-pick、哪些可以跳过？手动逐条看太痛苦了
- 知识沉淀：每个仓库都有自己的"潜规则"——CI 怎么配的、某个模块为什么这么设计、某个 API 的坑在哪。这些知识散落在脑子里、聊天记录里、commit message 里，换个人来维护又要从头摸索
现有的工具（gh CLI、GitHub MCP Server 等）能读写 issue 和 PR，但不追踪过程——不知道你在做什么，不知道上游改了什么，不知道谁在做什么，更不会帮你沉淀知识。
contribbot 是什么
一个开源维护助手，分三个阶段演进：
- Phase 1（已完成）：MCP 工具集 — 原子操作，读写 GitHub、管理 todo、追踪上游
- Phase 2（已完成）：Skills 工作流 — 编排工具完成复杂任务，通过 Claude Code Plugin 分发
- Phase 3（规划中）：Agents — 多 Agent 协同，定时巡检、自主决策、聊天入口等
现在开源出来的是 Phase 1 + 2。通过 MCP 协议提供工具集，通过 Claude Code Plugin 提供工作流。也支持 Gemini CLI、Codex CLI、Cursor 等 MCP 兼容平台。
为什么现在开源：核心功能跑通了，但只在我自己的几个仓库上验证过。需要更多真实场景的反馈——不同规模的仓库、不同的维护模式、不同的团队协作方式。如果你有想法或需求，欢迎提 Issue。
核心能力三句话：
- 追踪你在做什么 — 本地 todo 管理，每个任务有实现文档
- 追踪上游改了什么 — commit 级别的变更追踪 + triage 决策
- 追踪谁在做什么 — 领取工作项，自动评论到 GitHub
和 gh CLI 的区别
| gh CLI | contribbot | |
|---|---|---|
| 读写 Issue/PR | ✅ | ✅ + 自动关联本地 todo |
| 追踪个人任务 | ❌ | ✅ todo 全生命周期 + 实现文档 |
| 追踪上游变更 | ❌ | ✅ commit 级追踪 + 噪音过滤 |
| 多人协调 | ❌ | ✅ 领取工作项，评论到 GitHub |
| Fork 对齐 | ❌ | ✅ 同步 fork + cherry-pick 决策 |
| 跨栈追踪 | ❌ | ✅ React → Vue 功能对齐 |
快速开始
前置：安装 GitHub CLI 并登录（gh auth login）。
# 安装 contribbot
claude plugin marketplace add https://github.com/darkingtail/contribbot
claude plugin install contribbot
也支持 Gemini CLI、Codex CLI、Cursor 等 MCP 兼容平台，详见仓库文档。
安装后自动获得 Skills（引导式工作流）+ MCP 工具集。推荐使用 Claude Code，体验最完整。
四种项目模式
contribbot 自动检测你的仓库和上游的关系：
| 模式 | 条件 | 能做什么 |
|---|---|---|
| none | 无 fork、无 upstream | 基础的 issue/PR/todo 管理 |
| fork | 有 fork 来源 | 同步 fork + cherry-pick 决策 |
| upstream | 有外部 upstream | 跨栈 commit 追踪 |
| fork+upstream | 两者都有 | fork 同步 + 跨栈追踪 |
我自己同时维护的几个项目，刚好覆盖了不同模式：
| 项目 | 模式 | 说明 |
|---|---|---|
| contribbot | none | 自己的项目，无上游 |
| antdv-next | fork+upstream | fork of antdv-next 组织仓库，upstream: ant-design（React → Vue 跨栈） |
| antdv-next/x | fork+upstream | 同上，另一个子项目 |
| antdv-style | upstream | 非 fork，从零追踪 antd-style |
| plane | fork | fork of makeplane/plane，main 全量同步上游，feature/dev 分支是我的二开——加了仅自己需要的功能，上游更新时需要选择性 cherry-pick |
每个项目的 todo、upstream tracking、知识沉淀都是独立的，但可以用 project_list 跨项目总览，weekly-review 跨项目回顾。这就是 contribbot 解决"同时维护多个项目"的方式——每个项目独立追踪，全局统一视图。
典型工作流
1. 接入新项目
/contribbot:project-onboard darkingtail/my-repo
自动检测 fork/upstream 关系、初始化配置、引导选择追踪锚点。
2. 每日巡检
/contribbot:daily-sync darkingtail/my-repo
- 同步 fork 到上游最新
- 拉取上游新 commits
- 自动跳过 CI/deps/build 等噪音
- 逐条 triage：skip / 建 issue / 建 todo
3. 开始一个任务
/contribbot:start-task darkingtail/my-repo
- 列出待做 todo，选择一个
- 激活：拉取 issue 详情，AI 编码工具生成实现方案大纲
- 你确认方案后写入实现文档
- 如果 issue 有多个工作项，领取你要做的，自动评论到 GitHub
4. 日常维护（不依赖上游追踪）
即使你的仓库没有 fork、没有 upstream——纯粹的 none 模式，contribbot 一样有用：
- 用
/contribbot:todo管理你要做的事，每个 todo 自动关联 issue、生成实现文档 - 用
/contribbot:issue//contribbot:pr快速浏览、创建、回复 - 用
/contribbot:pre-submit合并前检查 CI、review、安全告警 - 用
knowledge_write记录仓库的"潜规则"，下次不用重新摸索
不需要上游追踪也能用，这是 contribbot 最基础的能力。
5. 周回顾
/contribbot:weekly-review
贡献统计、todo 进展、上游同步覆盖率、归档已完成项。
数据都在本地
所有数据存在 ~/.contribbot/{owner}/{repo}/：
~/.contribbot/antdv-next/antdv-next/
├── config.yaml # 仓库配置
│ # role: 你的权限（admin/write/read...）
│ # fork: 你的 fork 仓库
│ # upstream: 跨栈追踪的外部仓库
│
├── todos.yaml # 活跃任务索引
│ # 每条 todo 有 ref、title、type、status、difficulty、branch 等字段
│ # status: idea → backlog → active → pr_submitted → done | not_planned
│
├── todos/ # 实现文档（每个 todo 一个文件）
│ └── 123.md # 对应 issue #123，todo_add 时创建，todo_activate 时补充 issue 详情
│
├── todos.archive.yaml # 已归档的 todo（done + not_planned）
│ # 用 todo_compact 按日期或条数清理
│
├── upstream.yaml # 上游变更追踪
│ # versions: release 级同步状态（active/done）
│ # daily: commit 级 triage（action: skip/todo/issue/pr/synced）
│
├── upstream.archive.yaml # 已归档的上游 daily commits
│ # 由 upstream_compact 从 upstream.yaml 移入
│
├── templates/ # 自定义模板（首次使用自动生成带变量说明的默认模板）
│ ├── todo_record.md # todo 实现文档格式
│ └── todo_claim.md # 领取工作项时的 GitHub 评论格式
│
└── knowledge/ # 仓库知识沉淀（通过 knowledge_write 写入）
└── {name}/README.md # 每条知识一个目录
注意一个设计：fork 仓库的数据存在 parent 目录下。
比如你 fork 了 antdv-next/antdv-next，数据存在 ~/.contribbot/antdv-next/antdv-next/，不是你的 fork 路径 ~/.contribbot/darkingtail/antdv-next/。原因：你 fork 是为了 contribute，contribbot 的出发点就是围绕贡献——数据自然应该以上游仓库为基准。多人 fork 同一个仓库时，大家的本地数据也对齐到同一个目录结构。你的 fork 记录在 config.yaml 的 fork 字段里。
当然，contribbot 也支持 none 模式——没有上游的项目（比如 contribbot 自己），用来管理 todo、追踪 issue/PR、沉淀知识，同样好用。
多人协调：todo_claim
这是我最想解决的问题。
场景：一个仓库多人维护，上游出了一批新 commit，每个人本地有自己的追踪记录，但互相不知道谁在做什么。
contribbot 的做法：
- 领取时：
todo_claim自动在 GitHub issue 上评论，声明你要做哪些 - 激活时：
todo_activate自动检测 issue 评论中的领取记录，告诉你已有人领取了什么
I'll work on the following:
- 重构 Cascader 组件
- 修复 loadData 兼容性
其他维护者看到评论就知道这两项有人在做了。评论的可见内容可以通过 templates/todo_claim.md 自定义，机器标记由工具自动追加。
诚实地说一个局限：contribbot 的数据是本地的。每个维护者各自有自己的 upstream.yaml，A 在本地标记了某个 commit 为 "todo"，B 不知道。todo_claim 评论到 GitHub 是目前的协调方式——它解决了"谁在做什么"的可见性，但不是实时同步。
一定会有更好的方式来解决这个问题，我也在持续探索。如果你有想法，欢迎用 contribbot 来 contrib contribbot :)
工具架构
工具分三层，和 GitHub MCP Server 的关系明确：
tools/
├── core/ contribbot 独有（todo、upstream、knowledge、config）
├── linkage/ GitHub 操作 + 本地数据联动
└── compat/ GitHub API 封装，保证开箱即用
- 核心层不可替代——todo 管理、上游追踪、知识沉淀，GitHub MCP Server 做不了
- 联动层做 GitHub 操作时自动更新本地数据（比如
issue_create自动创建对应的 todo） - 兼容层保证不装 GitHub MCP Server 也能正常使用 issue/PR 读写
设计原则
几个在开发过程中形成的原则：
- 工具不做定性 — 工作项识别（issue 里的子任务可能是 checklist、表格、纯文本，格式不统一）、分支命名（不同仓库规范不同）、噪音过滤（哪些 commit 和我有关），这些需要"理解力"的判断交给 AI 编码工具，工具只负责数据读写
- 用户确认优先 — activate 时先出方案大纲，用户确认后再写入，不擅自决定
- 模板文件化 — 可自定义的格式用独立文件，首次使用自动生成带注释的默认模板
- todo 即有文档 — 添加 todo 时立即创建实现文档，不等 activate
路线图
Phase 1: Tools ✅ MCP 工具集 — 原子操作
Phase 2: Skills ✅ 工作流编排层 — 引导式工作流
Phase 3: Agents 🔲 多 Agent 协同 — 自主运行
Phase 3 还在规划阶段，以下是初步设计。目标是让 contribbot 从"人驱动"变成"自主运行"：
- 定时巡检：Agent 自动定时拉取上游变更、跳噪音、对有价值的 commit 建 issue
- 多 Agent 协同：上游巡检 Agent、triage 决策 Agent、通知 Agent 各司其职，协同工作
- 多人状态同步：改善当前 claim 只是公开信号的局限，Agent 主动扫描 GitHub 评论，识别谁在做什么
- 记忆系统：跨会话的项目上下文，不需要每次重新"进入"项目
- 聊天入口：飞书等，不依赖特定 IDE 或 CLI
- 更智能的 triage：基于历史决策学习，自动判断哪些上游变更和你有关
源码
GitHub: github.com/darkingtail…
欢迎 Star、提 Issue。更欢迎用 contribbot 来 contrib contribbot。
