gitcontribute

gitcontribute 可作为 CLI、终端 UI 和 MCP 服务，供编码 Agent 使用。

GitHub 可以显示未关闭的问题，但无法告诉你某个问题是否仍然相关、是否已经有人在实现、是否适合外部贡献者处理，或是否有足够证据支持安全地着手解决。

GitContribute 会将仓库指南、相关问题和拉取请求、代码上下文、已接受的贡献模式以及验证结果收集到本地 SQLite 语料库中。结果会指出覆盖缺失或过时之处。

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

重要

GitContribute 不会向 GitHub 写入任何内容。它会准备本地研究资料和草稿， 供你审核。

快速开始

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

npx --yes gitcontribute@latest setup

选择 MCP，即可通过受支持的编码 Agent 使用 GitContribute；选择 CLI，即可用于 终端和 TUI；也可以选择 两者。向导会在应用前显示所有计划的更改。设置期间添加仓库不会联系 GitHub，也不会开始同步。

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

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

npm install --global gitcontribute@latest
gitcontribute setup

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

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

贡献工作流

1. 查找候选项

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

Find contribution candidates in golang/go. Exclude issues with active
implementation work and explain why each remaining candidate is worth
investigating.

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

2. 研究问题

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

Investigate issue owner/repo#42. Summarize the confirmed problem, likely scope,
relevant code, maintainer guidance, and open questions.

3. 检查相关工作

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

Check whether owner/repo#42 has duplicate reports or competing implementation
work. Tell me what you checked and identify any missing coverage.

如果覆盖不完整，会明确报告，而不会将其视为不存在竞争工作的证据。在 MCP 工作流中，按照返回的类型化恢复操作执行，轮询持久化任务，并重新读取受影响的确切讨论串或代码库，然后再得出结论。

4. 验证更改

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

Validate my candidate change against the baseline. Run the approved checks,
record both results, and explain whether the evidence supports the change.

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

5. 准备草稿

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

Prepare a pull-request draft for this contribution. Tie its claims to the
recorded evidence, include the validation results, and do not post anything.

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

接口与存储

GitContribute 使用 SQLite 存储代码库、讨论串、代码快照、调查、证据、验证结果和贡献结果。网络访问是显式的；信息同步后，语料库搜索和检查可离线进行。

 GitHub read APIs                  Local checkout
       |                                |
       | explicit sync / hydrate        | explicit index / acquire
       v                                v
  +------------------------------------------------+
  |              Local SQLite corpus               |
  | observations · coverage · evidence · outcomes  |
  +------------------------+-----------------------+
                           | offline reads
                 +---------+---------+
                 v                   v
              CLI / TUI          Coding agents

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

CLI

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

# Sync repository context and current threads
gitcontribute archive sync-context owner/repo
gitcontribute archive sync owner/repo

# Find and inspect contribution candidates
gitcontribute radar owner/repo --limit 10
gitcontribute research brief issue:owner/repo#42

# Search stored threads and indexed code
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 <investigation-id>
gitcontribute validation define --kind=test --command="go test ./..." \
  --working-dir=/path/to/workspace <investigation-id>
gitcontribute validation run <validation-id> --kind=base --execute
gitcontribute validation run <validation-id> --kind=candidate --execute
gitcontribute validation compare <base-run-id> <candidate-run-id>
gitcontribute readiness opportunity <opportunity-id>
gitcontribute prepare pr --approach="Bound retries with context" \
  --workspace <workspace-id> <opportunity-id>

运行 gitcontribute --help 或 gitcontribute <command> --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 用户会作为一等参与者存储。实时发现只记录身份；个人资料、社交账号、组织、置顶项目、代码库和贡献事实会分别同步。有关数据和新鲜度模型，请参阅参与者语料库。

副作用边界

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

• 语料库读取绝不会获取数据。
• 爬取和索引绝不会执行由代码库控制的代码。
• 明确指定的验证命令会在你的主机上以你的用户权限运行。
• GitContribute 不具备修改 GitHub 的能力。
• 不存在托管语料库或产品遥测。

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

文档

• 入门与配置
• MCP 目录与组合
• 参与者语料库
• 架构与副作用边界
• 运维手册
• 安全政策
• 贡献指南

存储

GitContribute 遵循平台惯例：

默认语料库是数据目录中的 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。