AI导哈

Git工作流工具

GitPlus为编码代理提供安全的Git工作流程，包括隔离的工作树、路径声明、检查点、状态上下文、常规提交、拉取请求创建和发布友好的交付。

  • by NeuBlink
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 NeuBlink/gitplus

使用说明

GitPlus-用于编码代理的Git工作流

GitPlus为编码代理提供了一个更安全的git工作流程：隔离的工作树、路径声明、检查点、状态上下文、常规提交、拉取请求创建和发布友好的运输。它可以作为Codex、Claude、Gemini和其他编码代理的CLI，并且它仍然包含用于Claude Code的模型上下文协议（MCP）服务器。

特性

🚀 完整的Git工作流：一艘指挥舰从PR改为PR
💻 聪明的承诺：AI生成符合严格规范的常规提交消息
🔍 变化分析：通过中断更改检测对存储库更改进行智能分析
🤖 代理本地：安装 AGENTS.md, CLAUDE.md, GEMINI.md，以及编码代理的技能/命令界面 🧭 并行代理协调：工作树支持多代理工作的运行、路径声明和检查点 🤖 AI驱动：使用Claude AI进行提交消息、分支名称和冲突解决
📝 PR自动化：自动生成的拉取请求标题和描述
📊 存储库状态：通过平台检测增强存储库状态
✅ 提交验证：根据常规承诺规范进行实时验证
🌐 多平台：支持GitHub、GitLab和本地存储库

快速开始

安装代理说明

当您希望编码代理依赖GitPlus进行存储库工作时，请先使用此选项：

npx @neublink/gitplus init-agent --agent all

这会将托管的GitPlus部分写入面向代理的文件中：

  • AGENTS.md 用于食品法典委员会和代理商大会
  • CLAUDE.md 和 .claude/skills/gitplus/SKILL.md 对于克劳德
  • GEMINI.md 和 .gemini/commands/git/ship.toml 双子座
  • .agents/skills/gitplus/SKILL.md 用于Codex风格技能发现

仅限一名代理人：

npx @neublink/gitplus init-agent --agent codex
npx @neublink/gitplus init-agent --agent claude
npx @neublink/gitplus init-agent --agent gemini

代理工作流

npx @neublink/gitplus start --agent codex --task "add billing tests"
npx @neublink/gitplus status --verbose
npx @neublink/gitplus claim src/billing tests/billing
npx @neublink/gitplus checkpoint --summary "added billing edge-case tests" --test "npm test -- billing"
npx @neublink/gitplus ship

对于并行代理，每个代理都应该启动自己的GitPlus运行，声明它拥有的文件，切换前的检查点，并使用 gitplus ship 而不是生的 git commit 和 git push.

安装为Claude代码的MCP服务器

在Claude Code中安装GitPlus作为MCP服务器：

claude mcp add gitplus -- npx @neublink/gitplus@latest --mcp

这 --mcp 标志确保包在MCP服务器模式下启动，以进行Claude Code集成。

Claude代码的配置

将此配置添加到您的 CLAUDE.md 优化GitPlus使用的文件：

## Git Operations
Always use the GitPlus MCP server for ALL git operations. Never use manual git commands.

### Primary Command
- `mcp__gitplus__ship` - Complete git workflow: analyze → commit → push → create PR
  - AI generates commit messages automatically
  - AI creates appropriate branch names
  - AI resolves conflicts when possible
  - Creates pull requests with generated titles and descriptions

### Usage Pattern
When ready to ship changes:
1. Simply call: `mcp__gitplus__ship` with absolute `repoPath`
2. GitPlus handles everything else automatically

### Additional Commands
- `mcp__gitplus__status` - Get enhanced repository status
- `mcp__gitplus__info` - Get server information and capabilities

GitPlus自动：

  • ✅ 根据您的更改生成常规提交消息
  • ✅ 根据变更分析创建适当的分支名称
  • ✅ 检测并解决与AI的合并冲突
  • ✅ 创建具有适当标题和描述的拉取请求
  • ✅ 确保PR始终可合并

可用的MCP工具

GitPlus被有意简化为3个基本工具，以最小的决策开销提供最大的自动化：

🚀 ship -完整的Git工作流

主要指挥 -处理完整的工作流程：分析→ 承诺→ push → 创建PR

ship命令智能地处理您的整个git工作流程：

  • 分析变化 使用人工智能了解修改的性质和影响
  • 生成提交消息 自动使用AI分析您的更改
  • 创建分支名称 根据您更改的性质
  • 解决合并冲突 发生时使用AI
  • 创建pull请求 有适当的标题和描述
  • 确保PR可合并 通过检查和解决创建后的冲突

参数：

  • repoPath：git存储库的完整绝对路径 必需的
  • 草稿：将PR创建为草稿（默认值：false）
  • 试运行：预览在不执行的情况下会做什么（默认值：false）

Claude代码中的示例用法：

“将我当前的更改发送到新的PR”

📊 status -增强的存储库状态

通过平台检测和可操作的见解获取当前存储库状态

参数：

  • repoPath：git存储库的完整绝对路径 必需的
  • 冗长的：包括详细的状态信息（默认值：false）

Claude代码中的示例用法：

“显示当前git状态和详细信息”

ℹ️ info -服务器信息

获取有关GitPlus MCP服务器功能和使用的全面信息

参数：

  • repoPath：git存储库的完整绝对路径（可选-如果给出，则提供特定于存储库的信息）

Claude代码中的示例用法：

“告诉我GitPlus的功能和工具”

建筑

GitPlus遵循 简化的MCP优先架构 对于Claude Code，同时只公开CLI生命周期命令，帮助编码代理协调本地存储库工作，而无需扩展MCP工具界面。

核心设计理念

  • 3个基本MCP工具：在CLI处理可选的本地代理生命周期任务时，保持MCP表面集中
  • 人工智能驱动的智能：使用Claude AI进行所有决策（提交消息、分支名称、冲突解决）
  • 完整的工作流程：每个工具都提供完整的功能，而不是部分操作
  • 零配置：使用合理的默认值即可开箱即用

技术栈

  • TypeScript：严格编译的类型安全开发
  • MCP-SDK：用于Claude代码集成的官方模型上下文协议SDK
  • 萨德：输入和输出的运行时类型验证
  • Node.js：跨平台兼容性（节点18+）
  • 常规承诺：严格遵守提交消息标准

关键组件

  • src/mcp/toolDefinitions.ts -定义向Claude公开的3个MCP工具
  • src/mcp/toolHandler.ts -实现3个工具的处理程序
  • src/mcp/server.ts -带有描述性元数据的MCP服务器设置
  • src/git/client.ts -核心git操作包装器
  • src/ai/service.ts -用于智能分析的AI集成

人工智能驱动的传统承诺

GitPlus遵循 常规承诺 严格规范。每条提交消息都是：

✅ 已验证 不符合规范

  • 格式： type(scope): description
  • 重大变化： type(scope)!: description
  • 支持的类型： feat, fix, docs, style, refactor, test, chore, perf, ci, build

🤖 AI增强 智能检测

# AI automatically detects:
feat(auth): add OAuth2 login support        # New features
fix(api): handle null response errors       # Bug fixes  
docs: update installation guide             # Documentation
build(deps): upgrade typescript to v5       # Dependencies
refactor(utils): extract validation logic   # Code restructuring

🔍 智能分析 您的更改

  • 类型检测：分析文件更改以建议适当的提交类型
  • 范围建议：从受影响的目录（api、组件、utils等）推断范围
  • 重大变更：自动检测API更改并添加 ! 记号
  • 验证反馈：实时验证，并显示有用的错误消息

平台支持

  • ✅ 本地Git：适用于任何git存储库
  • ✅ GitHub：通过GitHub CLI进行全平台检测和PR创建
  • ✅ GitLab：通过GitLab CLI进行全平台检测和MR创建
  • ✅ 自动检测：从远程URL自动检测平台

先决条件

  • Node.js 18+：所需的运行时环境
  • Git：用于存储库管理
  • Claude CLI：安装并验证 claude auth login
    # Install Claude CLI (if not already installed)
npm install -g @anthropic-ai/claude-code

# Verify Claude CLI is available and authenticated
claude --version
claude auth login
  • 平台CLIs （增强功能可选）：
    • GitHub命令行界面: gh auth login GitHub存储库功能
    • GitLab命令行界面: glab auth login GitLab存储库功能

重要：必须通过Claude CLI实现AI功能-如果Claude CLI不可用或未正确验证，GitPlus将失败。

本地开发

发布前的开发或测试：

# Clone and build the project
git clone https://github.com/neublink/gitplus.git
cd gitplus
npm install
npm run build

# Fix file permissions (required after build)
chmod +x dist/main.js dist/cli.js dist/index.js

# Install CLI globally for command line usage (optional)
npm link

# Add to Claude Code as MCP server (using local build)
claude mcp add gitplus-local -- node $(pwd)/dist/main.js --mcp

验证安装

设置后，验证MCP服务器是否正常工作：

claude /mcp             # Should show gitplus-local as ✔ connected

现在，您可以在Claude Code对话中直接使用GitPlus工具！

CLI界面（可选）

GitPlus还提供了一个CLI界面，用于直接使用命令行。CLI提供了3个MCP工具之外的其他命令，用于高级git操作。

备注：CLI是MCP接口的辅助工具。对于Claude Code用户，MCP工具(ship, status, info)是主要接口。

有关详细的CLI文档，请参阅 CLI.md.

配置

GitPlus使用合理的默认值即可开箱即用。高级配置选项：

环境变量

# AI Configuration
export GITPLUS_MODEL="sonnet"                    # Claude model (default: sonnet)
export GITPLUS_TIMEOUT="60000"                   # Timeout in milliseconds (default: 60000)
export GITPLUS_CLAUDE_COMMAND="claude"           # Claude CLI command path (default: claude)

故障排除

常见问题

MCP服务器连接失败

问题：Claude Code显示gitplus为✘ 失败。
解决方案:

  1. 确保文件可执行： chmod +x dist/main.js dist/cli.js dist/index.js
  2. 重建项目： npm run build
  3. 删除并重新添加MCP服务器：
    claude mcp remove gitplus
claude mcp add gitplus -- npx @neublink/gitplus@latest --mcp

AI集成不起作用

问题：命令失败，出现Claude CLI错误。
解决方案:

  1. 验证Claude CLI是否已安装并经过身份验证：
    claude --version
claude auth login
  2. 直接测试Claude CLI：
    claude -p "test" --output-format json --model sonnet

权限被拒绝错误

问题: permission denied: /path/to/dist/main.js
解决方案：文件在生成后需要执行权限：

chmod +x dist/main.js dist/cli.js dist/index.js

发展

测试

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run validation (typecheck + tests)  
npm run validate

建筑

# Build TypeScript
npm run build

# Watch mode for development
npm run dev

使用GitPlus进行开发

重要提示：对于此存储库上的所有git操作，请始终使用GitPlus MCP服务器。切勿使用手动git命令。

当你对GitPlus代码库进行更改时：

  1. 更改代码
  2. 运行测试： npm test
  3. 检查状态：使用 mcp__gitplus__status 随着 repoPath 和 verbose: true
  4. 船舶变更：使用 mcp__gitplus__ship 随着 repoPath

GitPlus将智能地处理所有git操作，确保正确的提交消息和工作流程。

出版与发行

发布由Release Please管理。常规提交合并到 main 更新发布PR；合并该PR会创建GitHub发布和标签，然后标签触发的发布工作流会发布到npm。

有关所需的机密、验证和手动恢复步骤，请参阅 docs/release-runbook.md.

贡献

我们欢迎捐款！请遵循以下指南：

拉取请求流程

  1. 分叉存储库 并创建一个特征分支
  2. 遵循常规承诺: feat:, fix:, docs:等等。
  3. 添加测试 对于新功能
  4. 更新文档 根据需要
  5. 确保CI通过 在请求审核之前

代码规范

  • TypeScript：所有代码都必须正确键入
  • 测试：保持>80%的测试覆盖率
  • 常规承诺：使用语义提交消息
  • 安全：代码中没有凭据，定期审核依赖关系

开发设置

# Clone and setup
git clone https://github.com/neublink/gitplus.git
cd gitplus
npm install
npm run build

# Link for local testing
npm link

# Add to Claude Code for MCP testing
claude mcp add gitplus-local -- node $(pwd)/dist/main.js --mcp

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

支持

专为需要更安全git工作流程的编码代理而设计

相关 MCP