morluto/gitcontribute

GitContribute

面向代理的贡献研究：在编写补丁之前，检查仓库指南、相关工作、代码上下文和验证。

CI
npm
Go
License
Platforms

快速开始 · 工作流 · CLI · MCP · 安全性 · 文档

GitContribute 贡献工作台

gitcontribute 可作为 CLI、终端 UI 和 MCP 服务器供编码代理使用。

GitHub 可以向你展示未解决的 issue。但它无法告诉你某个 issue 是否仍然相关、是否已在实现中、是否适合外部贡献者，或者是否有足够的证据支持安全地开展工作。

GitContribute 在本地 SQLite 语料库中收集仓库指南、相关 issue 和 pull request、代码上下文、已接受的贡献模式以及验证结果。结果会标识缺失或过时的覆盖范围。

find work -> understand it -> check competing work -> prove the change -> prepare the handoff

[!IMPORTANT]
GitContribute 从不写入 GitHub。它准备本地研究和草稿供你审阅。

快速开始

使用 Node.js 18 或更高版本运行引导式设置：

npx --yes gitcontribute@latest setup

选择 MCP 以从受支持的编码代理使用 GitContribute，选择 CLI 以使用终端和 TUI，或选择 Both。向导会在应用每项计划变更之前显示它们。在设置期间添加仓库不会联系 GitHub 或启动同步。

设置完成后，从仓库或确切的 issue 开始：

| 任务 | 编码代理 | CLI |
| --- | --- | --- |
| 查找候选 | Find contribution candidates in owner/repo. Rank them by contribution fit, evidence, scope, and coordination risk. | gitcontribute archive sync owner/repogitcontribute radar owner/repo --limit 10 |
| 研究 issue | Investigate owner/repo#42. Check guidance, discussion, code, prior fixes, competing work, and missing evidence. | gitcontribute archive sync owner/repo --numbers 42gitcontribute research brief issue:owner/repo#42 |

结果包含来源引用、覆盖缺口和建议的后续步骤。

其他安装选项

安装持久命令：

npm install --global gitcontribute@latest
gitcontribute setup

将 GitContribute 固定到项目：

npm install --save-dev gitcontribute
npm exec -- gitcontribute setup --mode mcp --codex --token-source none --yes

使用 Go 1.26 或更高版本从源码构建：

go install github.com/morluto/gitcontribute/cmd/gitcontribute@latest

原生 npm 二进制文件包含适用于 macOS ARM64/x64、Linux ARM64/x64 和
Windows x64 的版本。你还需要 git。gh CLI 是可选的，可以通过
gh auth token 提供身份验证。

贡献工作流

1. 寻找候选对象

搜索仓库，或根据可用证据、范围、风险、阻碍因素以及需要维护者协调的迹象，
对其未解决问题进行排序。

在 golang/go 中寻找贡献候选对象。排除已有活跃实现工作的问题，
并解释为什么每个剩余候选对象值得调查。

排序仅涵盖已存储的观察结果。结果会报告覆盖不完整。

2. 研究问题

根据问题、仓库指南、讨论、关联工作、已索引代码和历史贡献构建研究简报。
提取的维护者文本和复选框不会作为完整的验收标准呈现。

调查问题 owner/repo#42。总结已确认的问题、可能范围、
相关代码、维护者指南和未决问题。

3. 检查相关工作

在投入实现之前，查找重复报告、关联的拉取请求、关闭关系以及语义上重叠的工作。

检查 owner/repo#42 是否有重复报告或竞争性实现工作。
告诉我你检查了什么，并指出任何缺失的覆盖范围。

覆盖不完整会被报告，而不会被当作不存在竞争性工作的证据。在 MCP 工作流中，
请遵循返回的类型化恢复操作，轮询持久作业，并在得出该结论之前重新阅读受影响的
确切线程或仓库。

4. 验证变更

记录复现、测试、基准测试或其他验证，并将未修改的基线
与候选变更进行比较。验证命令仅在明确批准后运行。

根据基线验证我的候选变更。运行已批准的检查，
记录两项结果，并解释证据是否支持该变更。

存储的运行记录包括命令、结果、耗时和可用的进程指标。

5. 准备草稿

创建与已收集的研究和验证证据相关联的本地问题、拉取请求或审查草稿。

为此贡献准备一份拉取请求草稿。将其主张与
记录的证据关联起来，包含验证结果，并且不要发布任何内容。

草稿修订会保留其确切的渲染字节和来源。

接口与存储

GitContribute 将仓库、线程、代码快照、调查、证据、验证结果和贡献成果
存储在 SQLite 中。网络访问是显式的；一旦信息已同步，语料库搜索和
检查即可离线进行。

GitHub 读取 API                  本地检出
|                                |
| 显式同步 / 水合                 | 显式索引 / 获取
v                                v
+------------------------------------------------+
|              本地 SQLite 语料库                  |
| 观察 · 覆盖 · 证据 · 结果                        |
+------------------------+-----------------------+
| 离线读取
+---------+---------+
v                   v
CLI / TUI          编码代理

CLI 和 MCP 服务器使用相同的应用服务和副作用边界。

CLI

CLI 无需 MCP 客户端即可暴露相同的工作流：

同步仓库上下文和当前线程
gitcontribute archive sync-context owner/repo
gitcontribute archive sync owner/repo

查找并检查贡献候选
gitcontribute radar owner/repo --limit 10
gitcontribute research brief issue:owner/repo#42

搜索存储的线程和已索引的代码
gitcontribute search threads "connection timeout" --repo owner/repo
gitcontribute search code "context.WithTimeout" --repo owner/repo

用于实现工作：

gitcontribute investigation start-thread issue:owner/repo#42 --json
gitcontribute workspace create
gitcontribute validation define --kind=test --command="go test ./..." \
--working-dir=/path/to/workspace
gitcontribute validation run  --kind=base --execute
gitcontribute validation run  --kind=candidate --execute
gitcontribute validation compare
gitcontribute readiness opportunity
gitcontribute prepare pr --approach="Bound retries with context" \
--workspace

运行 gitcontribute --help 或 gitcontribute  --help 获取完整的命令和标志参考。大多数非交互式命令接受 --json；机器可读输出发送到 stdout，进度发送到 stderr。

使用以下命令启动本地 TUI：

gitcontribute tui

MCP

MCP 服务器通告一个统一目录。Codex 和 Claude Code 等宿主可以通过原生工具搜索发现大型 MCP 目录，因此设置不会要求用户选择永久的能力配置文件。

gitcontribute setup --mode mcp --codex --token-source none --yes
gitcontribute setup --mode mcp --all-clients --token-source none --yes

直接启动 stdio 服务器：

gitcontribute mcp serve --transport=stdio

添加 --read-only 以移除允许网络访问、本地写入或执行的工具。有关能力边界、快照恢复、资源交接和常见工具序列，请参阅 MCP 目录与组合。

GitHub 用户被存储为一等参与者。实时发现仅记录身份；个人资料、社交账户、组织、固定项目、仓库和贡献事实均独立同步。请参阅
actor corpus 用于了解数据和新鲜度模型。

副作用边界

GitContribute 将语料库读取、GitHub 读取、本地写入、进程执行和外部变更分开。

| 操作 | 网络 | 本地写入 | 运行进程 | GitHub 写入 |
| --- | :---: | :---: | :---: | :---: |
| 搜索和检查已存储的研究 | 否 | 否 | 否 | 否 |
| 记录调查和证据 | 否 | 是 | 否 | 否 |
| 同步或补充 GitHub 上下文 | 是 | 是 | 否 | 否 |
| 获取并索引代码 | 是 | 是 | 仅 git | 否 |
| 运行明确批准的验证 | 默认否 | 是 | 是 | 否 |

- 语料库读取从不获取数据。
- 爬取和索引从不执行仓库控制的代码。
- 显式验证命令在你的主机上以你的用户权限运行。
- GitContribute 没有 GitHub 变更能力。
- 没有托管语料库或产品遥测。

有关完整的边界定义，请参阅 Architecture。

文档

- 入门和配置
- MCP 目录和组合
- Actor corpus
- 架构和副作用边界
- 运维手册
- 安全策略
- 贡献

存储

GitContribute 遵循平台约定：

| 平台 | 配置 | 数据 |
| --- | --- | --- |
| Linux | $XDG_CONFIG_HOME/gitcontribute 或 ~/.config/gitcontribute | $XDG_DATA_HOME/gitcontribute 或 ~/.local/share/gitcontribute |
| macOS | ~/Library/Application Support/gitcontribute | ~/Library/Application Support/gitcontribute/Data |
| Windows | %APPDATA%\gitcontribute | %LOCALAPPDATA%\gitcontribute\Data |

默认语料库是数据目录中的 gitcontribute.db。运行
gitcontribute metadata 或 gitcontribute doctor --json 来检查本地
设置。

平台支持

Linux 和 macOS 是主要的开发和测试目标。Windows 构建
在 CI 中测试，并使用标准的 %APPDATA% 和 %LOCALAPPDATA%
位置。

开发

make verify
go run ./cmd/gitcontribute --help

在更改包边界或副作用之前，请阅读
docs/architecture.md。有关仓库工作流，请参阅
CONTRIBUTING.md。