git-courer

<!-- mcp-name: io.github.blak0p/git-courer --> <!-- markdownlint-disable MD041 --> <img width="1259" height="619" alt="Gemini_Generated_Image_g9lcw7g9lc" src="https://github.com/user-attachments/assets/2e9c0e64-b0de-4b83-9159-3a5906f9f3f4" /> <p align="center"> <a href="https://github.com/blak0p/git-courer/releases/latest"> <img src="https://img.shields.io/github/v/release/blak0p/git-courer?color=%2300BFFF&label=latest" alt="Release"> </a> <a href="https://github.com/blak0p/git-courer/actions"> <img src="https://img.shields.io/github/actions/workflow/status/blak0p/git-courer/test.yml?branch=main" alt="Build"> </a> <a href="https://github.com/blak0p/git-courer/blob/main/LICENSE"> <img src="https://img.shields.io/github/license/blak0p/git-courer" alt="MIT License"> </a> </p> > **问题和错误**: [@blak0p/git-courer/issues](https://github.com/blak0p/git-courer/issues) · **讨论**: [@blak0p/git-courer/discussions](https://github.com/blak0p/git-courer/discussions) | 文档 | 描述 | | --- | --- | | [网站](https://blak0p.github.io/git-courer/) | 访问官方网站 | | [路线图](docs/roadmap.md) | 即将推出的功能和战略愿景 | | [架构](docs/architecture.md) | 代码库结构、模式和如何添加功能 | | [故障排除](docs/troubleshooting.md) | 修复：Ollama 未运行、MCP 未检测到、权限错误 | | [MCP 客户端](docs/mcp-clients.md) | 所有 5 个支持的 CLI 代理、配置格式、手动设置 | | [配置选项](docs/config.md) | 所有 `~/.config/git-courer/config.yaml` 和 `.git/git-courer/config.json` 设置 | | [命令](docs/commands.md) | 所有 13 个 MCP 工具的完整参考 | | [贡献](docs/contributing.md) | 设置、运行测试和如何协作 | --- # git-courer **Git，但代理无法破坏它。** 一个 MCP 服务器，为 AI 代理提供一个完整、安全的 Git 接口 - 不仅仅是提交，还有整个界面：状态、差异、分支、stash、历史记录、同步。每个变体都会自动备份。没有任何内容通过 Bash 路由，因此不会在您不知情的情况下发生 `git reset --hard`。 13 种工具。结构化 JSON 输入，结构化 JSON 输出。没有分页器，没有文本解析，没有猜测代理实际对您的仓库执行了什么操作。 --- ## 安装 ```bash curl -fsSL https://raw.githubusercontent.com/blak0p/git-courer/main/scripts/install.sh | sh ``` ```go go install github.com/blak0p/git-courer@latest ``` **Homebrew:** ```bash brew install blak0p/tap/git-courer ``` ### 快速入门 ```bash git-courer mcp setup # 自动配置您的代理（OpenCode、Claude Code、Codex、pi、Antigravity） ``` 重启您的代理，然后要求它在任何仓库上运行 `status`。如果它返回结构化 JSON 而不是原始 `git status` 输出，则表示您已连接。 ### 诊断和生命周期 ```bash git-courer doctor # 每个检测到的 MCP 客户端的只读健康报告 git-courer hook-check "git status" # 分类 shell 命令（代理钩子；永远不会拒绝） git-courer init # TUI 向导，创建/更新项目配置 git-courer version --predict # 从约定提交中预测下一个发布标签 git-courer remove # 删除项目级配置（保留二进制文件） git-courer update # 自我更新到最新版本 + 重新配置 MCP ``` `doctor` 报告每个客户端：配置路径、MCP 配置、注入的提示块、安装的钩子（`yes`/`no`/`partial`）和 Claude 内联钩子（仅 Claude Code）。 --- ## 代理如何与 git-courer 交互 ``` 代理接收任务 ↓ 会话启动 → 创建隔离的工作树 + 分支 ↓ 所有 MCP 工具（差异、状态、提交、分支...） 自动重定向到该工作树 ↓ 提交预览 → Go 解析 AST + 依赖图 分类类型（feat/fix/breaking...） ↓ 提交应用 → 根据配置分为两种模式： ┌─ 使用 LLM ──────────────────────────────┐ │ 本地 LLM 编写 WHY/WHAT 消息 │ │ Go 决定类型（代理可以 │ │ 如果错误则覆盖 type=） │ └─────────────────────────────────────────┘ ┌─ 不使用 LLM（关闭） ─────────────┐ │ 适用于 modest 笔记本，无 GPU │ │ 代理直接编写消息 │ │ 预览、应用和类型覆盖 │ │ 仍然有效 │ └─────────────────────────────────────────┘ ↓ 安全检查 → 自动备份 → 提交 ↓ "✓ 修复：重构会话完成工作流以停止自动合并 WHY 以前的实现自动尝试将会话 分支合并到基准分支，这强制执行特定的集成 策略并需要管理两个不同的 Git 仓库。 WHAT * 删除了自动合并逻辑和对第二个 Git 实例（mainGit）的依赖 会话处理程序和工作流中。 * 更新清理以删除工作树，同时保留会话分支 为手动集成而活跃。 * 切换到 PreviewLight 验证以防止数据丢失 未提交的更改。 * 更新 FinishResult 以包含 BranchAlive 状态。" 会话完成 → 关闭会话 + 清理工作树 ``` --- ## LLM 开关 modest 笔记本，无 GPU？ 翻转开关，git-courer 完全在无 LLM 的情况下运行。代理直接编写消息，Go 仍然决定类型。 ```yaml llm: enabled: false ``` 无 LLM：使用 `message` 提交，预览和类型覆盖有效。发布版本不可用。其他所有功能（状态、差异、分支、会话、备份）正常工作。 --- ## 为什么它与众不同 ### 1. 提交类型由 Go 决定，而不是 LLM AST 分析 + 确定性规则。LLM 只编写消息。如果类型错误，代理可以覆盖它，输入 `type=`。 ### 2. 依赖图 在提交之前，它会映射您的更改在整个代码库中的影响。实际影响，而不仅仅是“您触及了 3 个文件”。 ### 3. 隔离的工作树 每个代理都有自己的目录和分支。不会相互干扰。`session start` 创建，会话完成`关闭并清理。 ### 4. 提交作为 LLM 上下文 带有 WHY/WHAT 的结构化摘要。任何 LLM 都可以直接使用它。更少的 token，更少的幻觉。 ### 5. 自动备份 每次写入操作在执行前都会备份。 一个命令可以撤销任何操作。 ### 6. 释放后仍存活的版本 提交存储在 `refs/courer/*` 中。压碎、变基、强制推送 — 您的变更日志不会消失。 --- ## 版本发布 ``` ❯ git-courer release Tag? [v3.0.0]: Add guidance for changelog generation? (y/N): n 📦 发布预览 Tag: v3.0.0 版本增量: major --- 变更日志 --- ... Apply? (y/N/r/e): ``` 这是它编写的变更日志： > **v2.8.0** — 此更新引入了使用 git 工作树的高级会话管理系统，以实现并行工作流，并提高了代理执行规则的鲁棒性。 > > **会话管理和隔离** > - 使用 git 工作树实现隔离会话，以防止代理之间相互干扰；包括使用 slugified 标识符的完整生命周期、列表、选择和自动清理。 > - 将 sessionGit 包装器集成到 MCP 服务器中，用于自动目录重定向。 > > **开发者体验和配置** > - 精炼了黄金规则，现在禁止在仓库根目录工作以强制严格的工作空间隔离。 > - 自动将提示规则块注入客户端配置文件中。 > - 修复了 TUI MCP 设置错误，客户端未正确配置。 > > **系统鲁棒性和重构** > - 重构了代理指令结构，删除了不必要的工具映射。 > - 使用强大的基名改进了文件清理，以防止复杂路径出错。 --- ## 工作流 ### 会话 `session start` → 隔离的工作树 + 分支。所有 MCP 工具重定向到那里。`session finish` 关闭并清理。`session discard` 丢弃它。 ### 提交 `PREVIEW` → 审查提议的提交。`APPLY` → 执行它们。Go 将文件按依赖图分成原子提交。 ### PR 审查 `pr-review` → 测试 + 冲突 + 差异统计 + 分歧。全部在一个调用中。 ### 发布 `git-courer release` → 交互式。选择标签，指导 LLM，预览变更日志，确认。提交存储在 `refs/courer/*` 中 - 它们在压碎后仍然存在。 ### 撤销 `backup RESTORE` → 撤销任何操作。 --- ## 工具（13） | 工具 | 子命令 | 功能 | | --- | --- | --- | | `status` | — | 完整的仓库状态：分支、更改、冲突、stash 等 | | `diff` | — | 带有 AST 标签的差异（`NEW_FUNC`、`MOD_SIG`、`DEPS`、`DEL`） | | `commit` | `PREVIEW` → `APPLY` | 3 阶段 LLM 管道：预览、审查、应用 | | `branch` | `CREATE` / `SWITCH` / `DELETE` / `RENAME` / `LIST` | 分支管理 | | `stage` | `RM` / `RESTORE` / `CLEAN` | 暂存区控制 | | `stash` | `SAVE` / `POP` / `SHOW` | stash 管理 | | `history` | `LOG` / `REFLOG` / `BLAME` | 历史记录检查 | | `sync` | `PUSH` / `PULL` / `FETCH` | 远程同步 | | `pr-review` | — | 测试 + 冲突 + 差异统计 + 分歧，一次调用 | | `backup` | `RESTORE` / `LIST` | 撤销 amend/merge/rebase | | `rewrite` | `AMEND` / `REVERT` / `SOFT` / `HARD` | 历史记录重写 | | `integrate` | `MERGE` / `UPDATE` / `PICK` / `CONTINUE` / `ABORT` | 分支集成 | | `session` | `start` / `finish` / `status` / `select` / `discard` | 隔离工作树生命周期 | 完整参考和示例：[docs/commands.md](docs/commands.md)。 --- ## 支持的客户端 | 工具 | 自动配置 | |------|----------------| | OpenCode | ✓ | | Claude Code | ✓ | | Codex | ✓ | | pi | ✓ | | Antigravity | ✓ | `git-courer mcp setup` 一次配置所有客户端。手动设置和配置格式：[docs/mcp-clients.md](docs/mcp-clients.md)。 --- ## 钩子和黄金规则 `mcp setup` 不仅注册 MCP 服务器，还注入防护措施，使代理通过 git-courer 而不是原始 Bash 路由 git 操作。 **注入黄金规则。** 在每个客户端的指令文件中注入 `<!-- git-courer start -->` / `<!-- git-courer end -->` 块（OpenCode 的 `AGENTS.md`，Claude Code 的 `CLAUDE.md`，Antigravity 的 `GEMINI.md`）。该块编码黄金规则：检查 `status` 前的变体，运行 `diff` + `review` 前的 PR，始终 `session start`。 **钩子。** 支持 shell 钩子的客户端会获得连接到 git-courer 子命令的条目： | 事件 | 匹配器 | 命令 | 触发时 | |-------|---------|---------|------------| | PreToolUse | `git *` | `git-courer hook-check` | 在任何 Bash `git ...` 运行前 | | SessionStart | — | `git-courer session-start-hook` | 代理会话打开 | | SubagentStart | — | `git-courer subagent-start-hook` | 子代理启动 | | PreInvocation | — | `git-courer pre-invocation-hook` | 每个模型调用前（Antigravity） | `hook-check` 分类命令并发出 `additionalContext`，建议匹配的 git-courer MCP 工具 - **永远不会拒绝**。 会话/子代理/预调用钩子将黄金规则作为 `additionalContext` 注入。Claude Code 使用内联 `settings.json` 钩子（`UserPromptSubmit` 而不是 PreInvocation）；Codex 使用单独的 `hooks.json`；Antigravity 使用单独的 `hooks.json`，带有 `run_command` 匹配器和仅 2 个事件。完整参考：[docs/hooks.md](docs/hooks.md)。 **OpenCode 策略。** 对于 OpenCode（没有 shell 钩子），`mcp setup` 合并到 `opencode.json`： - `permission.bash["git *"] = "ask"` - OpenCode 在任何 `git` Bash 命令之前提示用户，因此代理被引导到 MCP 工具。 - `instructions` 数组包括 `AGENTS.md` 路径（旧的 `GIT_COURER.md` 条目被删除）。合并是幂等的；在任何更改之前都会写入 `.bak` 备份。 运行 `git-courer doctor` 验证客户端的所有内容。 --- ## 常见问题 **谁决定提交类型？** Go。LLM 只编写消息。代理可以覆盖它，输入 `type=`。 **我需要 GPU 或本地 LLM 吗？** 否。翻转开关 (`llm.enabled: false`)，它在任何笔记本上运行。代理直接编写消息。 **我的代码会离开我的机器吗？** 否。所有操作都在本地运行 - git-courer、Ollama 和您的数据。 **没有 LLM 的版本发布怎么办？** 不可用。发布需要 LLM 来生成变更日志。 **如何标记重大更改？** `feat!:` 或 `BREAKING CHANGE:` 在正文中。Go 自动检测它。