Metadata-Version: 2.4
Name: bingo-light
Version: 2.1.1
Summary: AI-native fork maintenance — manage customizations as a clean patch stack on top of upstream
Author: bingo-light contributors
License: MIT
Project-URL: Homepage, https://github.com/DanOps-1/bingo-light
Project-URL: Issues, https://github.com/DanOps-1/bingo-light/issues
Keywords: git,fork,patch,mcp,ai,maintenance
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

<p align="center">
  <br>
  <img src="docs/logo.svg" alt="bingo-light logo" width="200">
  <br><br>
  <strong>Fork 同步，一条命令搞定。<br>人用、AI 用，零依赖。</strong>
  <br><br>
  <a href="README.en.md">English</a> | <b>简体中文</b>
  <br><br>
  <a href="https://github.com/DanOps-1/bingo-light/actions"><img src="https://github.com/DanOps-1/bingo-light/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
  <a href="https://github.com/DanOps-1/bingo-light/releases"><img src="https://img.shields.io/github/v/release/DanOps-1/bingo-light?label=Release&color=orange" alt="Release"></a>
  <a href="#mcp-服务器"><img src="https://img.shields.io/badge/MCP_Server-29_tools-blueviolet.svg" alt="MCP: 27 tools"></a>
  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.8+-3776ab.svg" alt="Python 3.8+"></a>
  <img src="https://img.shields.io/badge/Dependencies-Zero-brightgreen.svg" alt="Zero deps">
  <a href="https://github.com/DanOps-1/bingo-light/stargazers"><img src="https://img.shields.io/github/stars/DanOps-1/bingo-light?style=social" alt="Stars"></a>
  <br><br>
</p>

GitHub 的 "Sync fork" 按钮？你一改代码它就废了。手动 `git rebase`？六步操作，每次都得记。AI 想帮你同步？没接口可调。

**bingo-light 把这三个问题一锅端。**

改动以补丁栈的形式叠在上游之上，干干净净。同步一句 `bingo-light sync`。冲突解过一次就记住了，下次自动跳过。搞砸了 `bingo-light undo` 秒回。

所有命令支持 `--json` 输出。内置 MCP 服务器 29 个工具，AI 从初始化到冲突解决全程自主，不用人盯。

---

## 目录

- [快速开始](#快速开始)
- [演示](#演示)
- [安装](#安装)
- [功能特性](#功能特性)
- [工作原理](#工作原理)
- [MCP 服务器](#mcp-服务器)
- [命令参考](#命令参考)
- [集成指南](#集成指南)
- [配置](#配置)
- [常见问题](#常见问题)
- [与其他方案对比](#与其他方案对比)
- [项目生态](#项目生态)
- [参与贡献](#参与贡献)
- [许可证](#许可证)

---

## 快速开始

```bash
# 安装（任选一种）
pip install bingo-light             # Python
npm install -g bingo-light          # Node.js
brew install DanOps-1/tap/bingo-light  # Homebrew

# 初始化 Fork 追踪
cd my-forked-project
bingo-light init https://github.com/original/project.git

# 改代码，创建命名补丁
vim src/feature.py
bingo-light patch new my-feature

# 上游有更新？一句话同步
bingo-light sync
```

就这么简单。补丁永远干净地叠在最新上游之上。

## 演示

### 日常操作：初始化 → 建补丁 → 同步

<p align="center">
  <img src="docs/demo.svg" alt="bingo-light 基本演示" width="850">
</p>

### 冲突处理：同步 → 分析 → 搞定

<p align="center">
  <img src="docs/demo-conflict.svg" alt="bingo-light 冲突解决演示" width="850">
</p>

> AI 调 `conflict-analyze --json` 拿到双方代码，写好合并结果，rebase 自动继续。全程零人工。

### AI 拿到的是结构化数据

```
$ bingo-light status --json
```
```json
{
  "ok": true,
  "upstream_url": "https://github.com/torvalds/linux.git",
  "behind": 47,
  "patch_count": 2,
  "patches": [
    {"name": "custom-scheduler", "hash": "a3f7c21", "subject": "O(1) task scheduling", "files": 3},
    {"name": "perf-monitoring", "hash": "b8e2d4f", "subject": "eBPF tracing hooks", "files": 5}
  ],
  "conflict_risk": ["kernel/sched/core.c"]
}
```

### 冲突分析（AI 直接消费）

```
$ bingo-light conflict-analyze --json
```
```json
{
  "rebase_in_progress": true,
  "current_patch": "custom-scheduler",
  "conflicts": [
    {
      "file": "kernel/sched/core.c",
      "conflict_count": 2,
      "ours": "... 上游版本 ...",
      "theirs": "... 你的补丁版本 ...",
      "hint": "上游重构了调度器核心；补丁需要适配新结构。"
    }
  ]
}
```

## 安装

装完跑 `bingo-light setup`，交互式配好 MCP 和 AI Skill（Claude Code、Cursor、Windsurf、VS Code/Copilot、Gemini CLI 等一键选配）。

### pip / pipx

```bash
pip install bingo-light        # 或: pipx install bingo-light
bingo-light setup              # 选配 AI 工具
```

### npm / npx

```bash
npm install -g bingo-light     # 全局安装
bingo-light setup

# 或 npx 免装：
npx bingo-light setup
```

MCP 客户端直接用 npx：
```json
{"command": "npx", "args": ["-y", "bingo-light-mcp"]}
```

### Homebrew

```bash
brew install DanOps-1/tap/bingo-light
bingo-light setup
```

### Docker

```bash
# CLI
docker run --rm -v "$PWD:/repo" -w /repo ghcr.io/danops-1/bingo-light status

# MCP 服务器（stdio）
docker run --rm -i -v "$PWD:/repo" -w /repo ghcr.io/danops-1/bingo-light mcp-server.py
```

### Shell 安装器

```bash
curl -fsSL https://raw.githubusercontent.com/DanOps-1/bingo-light/main/install.sh | sh

# 非交互模式（CI / Docker）
curl -fsSL .../install.sh | sh -s -- --yes
```

### 从源码安装

```bash
git clone https://github.com/DanOps-1/bingo-light.git
cd bingo-light
make install && bingo-light setup
```

**依赖：** Python 3.8+ / git 2.20+，没了。

## 功能特性

### AI 侧

| 功能 | 说明 |
|------|------|
| **MCP 服务器** | 29 个工具，初始化到冲突解决全覆盖 |
| **`--json`** | 所有命令输出结构化 JSON |
| **`--yes`** | 跳过一切确认，不需要 TTY |
| **非 TTY 自适应** | 管道或子进程调用时自动静默 |
| **`BINGO_DESCRIPTION`** | 环境变量设补丁描述 |
| **`conflict-analyze`** | 冲突数据结构化：文件、双方代码、解决提示 |
| **`conflict-resolve`** | MCP 直接写入解决内容，自动暂存 + 继续 rebase |
| **Advisor 代理** | `contrib/agent.py` 自动监控、分析、安全时自动同步 |

### 人类侧

| 功能 | 说明 |
|------|------|
| **零依赖** | Python 3 + git，一行装完 |
| **命名补丁** | 每个改动是独立的、有名字的 commit |
| **一键同步** | `bingo-light sync`，补丁自动 rebase 到最新上游 |
| **先试后跑** | `sync --dry-run` 临时分支预演，不碰真代码 |
| **冲突记忆** | rerere 自动开，解一次就记住，再也不问 |
| **秒级撤销** | `bingo-light undo` 恢复同步前状态 |
| **冲突预警** | `status` 提前告诉你哪些文件会出事 |
| **自检修复** | `doctor` 全面体检 + 试跑 rebase |
| **导出导入** | `.patch` 文件，quilt 兼容 |
| **CI 自动同步** | 生成 GitHub Actions 流水线，冲突自动告警 |
| **TUI 面板** | curses 实时仪表盘（`contrib/tui.py`） |
| **多仓管理** | `workspace` 统一管所有 Fork |
| **补全** | bash / zsh / fish |
| **通知推送** | Discord、Slack、Webhook，事件触发 |
| **补丁元数据** | 标签、原因、过期时间、关联上游 PR |
| **测试联动** | 同步后自动跑测试，挂了自动回滚 |

## 工作原理

```
  upstream (github.com/original/project)
      |
      |  git fetch
      v
  upstream-tracking ─────── 上游的精确镜像，从不手动碰
      |
      |  git rebase
      v
  bingo-patches ─────────── 你的改动叠在这里
      |
      +── [bl] custom-scheduler:  O(1) 任务调度
      +── [bl] perf-monitoring:   eBPF 追踪钩子
      +── [bl] fix-logging:       结构化 JSON 日志
      |
      v
    HEAD (你的工作 Fork)
```

**同步：** fetch 上游 → 快进追踪分支 → rebase 补丁到最新上游。补丁永远干净地叠在最新代码上。

**冲突记忆：** 初始化时自动开 rerere。解过一次，git 就记住了——下次碰到同样的冲突直接跳过。

**AI 解冲突：** rebase 卡住时，AI 调 `conflict-analyze` 拿双方代码和提示，写好合并结果扔给 `conflict-resolve`，rebase 自动继续，不用人管。

## MCP 服务器

`mcp-server.py`，纯 Python 3，零依赖，stdio 传输，29 个工具，JSON-RPC 2.0。

运行 `bingo-light setup` 自动配置，或手动添加：

**Claude Code**（`.mcp.json` 或 `~/.claude/settings.json`）：

```json
{
  "mcpServers": {
    "bingo-light": {
      "command": "python3",
      "args": ["/path/to/bingo-light/mcp-server.py"]
    }
  }
}
```

**Claude Desktop**（`~/Library/Application Support/Claude/claude_desktop_config.json`）：

```json
{
  "mcpServers": {
    "bingo-light": {
      "command": "python3",
      "args": ["/path/to/bingo-light/mcp-server.py"]
    }
  }
}
```

**其他客户端**（Cursor、Windsurf、VS Code Copilot 等）：stdio 连 `python3 mcp-server.py`，或跑 `bingo-light setup` 一键配。

### 全部工具

| 工具 | 用途 |
|------|------|
| `bingo_init` | 初始化 Fork 追踪 |
| `bingo_status` | 健康检查：漂移、补丁、冲突风险 |
| `bingo_sync` | 拉取上游并变基补丁 |
| `bingo_undo` | 恢复到同步前状态 |
| `bingo_patch_new` | 创建命名补丁 |
| `bingo_patch_list` | 列出补丁栈 |
| `bingo_patch_show` | 查看补丁 diff |
| `bingo_patch_drop` | 移除补丁 |
| `bingo_patch_export` | 导出为 `.patch` 文件 |
| `bingo_patch_import` | 导入 `.patch` 文件 |
| `bingo_patch_meta` | 获取/设置补丁元数据 |
| `bingo_patch_squash` | 合并两个补丁 |
| `bingo_patch_reorder` | 非交互式重排补丁 |
| `bingo_doctor` | 全面诊断 + 测试变基 |
| `bingo_diff` | 补丁总 diff vs 上游 |
| `bingo_auto_sync` | 生成 GitHub Actions 工作流 |
| `bingo_conflict_analyze` | AI 用的结构化冲突数据 |
| `bingo_conflict_resolve` | 写入解决内容，暂存，继续 rebase |
| `bingo_config` | 获取/设置配置 |
| `bingo_history` | 同步历史 + hash 映射 |
| `bingo_test` | 运行测试套件 |
| `bingo_workspace_status` | 多仓库工作区概览 |
| `bingo_patch_edit` | 修改已有补丁 |
| `bingo_workspace_init` | 初始化多仓库工作区 |
| `bingo_workspace_add` | 添加仓库到工作区 |
| `bingo_workspace_sync` | 同步工作区所有仓库 |
| `bingo_workspace_list` | 列出工作区仓库 |

## 命令参考

```
bingo-light init <upstream-url> [branch]     初始化上游追踪
bingo-light patch new <name>                 创建命名补丁
bingo-light patch list [-v]                  列出补丁栈
bingo-light patch show <name|index>          查看补丁 diff
bingo-light patch edit <name|index>          修改补丁（先暂存变更）
bingo-light patch drop <name|index>          移除补丁
bingo-light patch reorder [--order "3,1,2"]  重排补丁
bingo-light patch export [dir]               导出为 .patch 文件
bingo-light patch import <file|dir>          导入 .patch 文件
bingo-light patch squash <idx1> <idx2>       合并两个补丁
bingo-light patch meta <name> [key] [value]  获取/设置补丁元数据
bingo-light sync [--dry-run] [--force]       与上游同步
bingo-light sync --test                      同步后跑测试，失败自动回滚
bingo-light undo                             恢复到同步前状态
bingo-light status                           健康检查 + 冲突预测
bingo-light doctor                           全面诊断
bingo-light diff                             补丁总 diff vs 上游
bingo-light log                              同步历史
bingo-light conflict-analyze                 分析 rebase 冲突
bingo-light config get|set|list [key] [val]  管理配置
bingo-light history                          详细同步历史 + 映射
bingo-light test                             运行测试套件
bingo-light workspace init|add|status|sync   多仓库管理
bingo-light auto-sync                        生成 GitHub Actions 工作流
bingo-light version                          打印版本
bingo-light help                             打印帮助
```

**全局标志：** `--json`（结构化 JSON 输出） | `--yes`（跳过所有确认提示）

## 集成指南

### Claude Code (MCP)

MCP 配好后，Claude Code 全程接管：

```
你: "同步上游，冲突帮我修了。"

Claude Code:
  1. bingo_status(cwd)        → 落后 47 commit，risk: core.c
  2. bingo_sync(cwd, dry_run) → 预判 1 个冲突
  3. bingo_sync(cwd)          → rebase 卡在冲突
  4. bingo_conflict_analyze() → 拿到双方代码 + 提示
  5. 读两边，写合并结果
  6. bingo_conflict_resolve(cwd, file, content) → 搞定
  7. bingo_status(cwd)        → 0 落后，补丁干净
```

### Aider / CLI 代理

```bash
bingo-light status --json          # 解析 Fork 状态
bingo-light sync --yes             # 非交互同步
bingo-light conflict-analyze --json # 结构化冲突数据
```

### 自定义 Python 代理

```python
import subprocess, json

def bingo(cmd, cwd="/path/to/repo"):
    result = subprocess.run(
        ["bingo-light"] + cmd.split() + ["--json", "--yes"],
        cwd=cwd, capture_output=True, text=True
    )
    return json.loads(result.stdout)

status = bingo("status")
if status["behind"] > 0:
    result = bingo("sync")
    if result.get("conflicts"):
        analysis = bingo("conflict-analyze")
        for c in analysis["conflicts"]:
            resolved = my_llm_resolve(c["ours"], c["theirs"], c["hint"])
            # 通过 CLI 或 MCP 写入解决内容
```

## 配置

配置存在 `.bingolight`（git-config 格式），自动排除在版本控制外。

```bash
bingo-light config set sync.auto-test true     # 同步后自动跑测试
bingo-light config set test.command "make test" # 测试命令
bingo-light config list                         # 查看所有配置
```

### 通知 Hook

在 `.bingo/hooks/` 放可执行脚本：

| Hook | 触发时机 |
|------|---------|
| `on-sync-success` | 同步成功后 |
| `on-conflict` | rebase 碰到冲突时 |
| `on-test-fail` | 同步后测试失败时 |

Hook 通过 stdin 接 JSON。示例见 [contrib/hooks/](contrib/hooks/)（Slack / Discord / Webhook）。

## 常见问题

<details>
<summary><b>为什么不直接 <code>git rebase</code>？</b></summary>

可以。bingo-light 包的是 rebase 周边那些烦事：追踪上游、维护补丁分支、开 rerere、预测冲突、输出结构化数据。偶尔 rebase 一次用不着它，但长期维护好几个补丁的话，省心省力。
</details>

<details>
<summary><b>能用在已有的 Fork 上吗？</b></summary>

能。进你的 Fork 目录，`bingo-light init <upstream-url>`，再 `bingo-light patch new <name>` 把现有改动转成补丁。标准 git 仓库就行。
</details>

<details>
<summary><b>只给 AI 用？</b></summary>

人和 AI 用的是同一套命令。`bingo-light sync` 谁跑都一样。`--json`、`--yes`、MCP 这些是给 AI 加的接口，不加就是正常的人类输出。
</details>

<details>
<summary><b>冲突记忆怎么回事？</b></summary>

`init` 时自动开了 git 的 `rerere`（reuse recorded resolution）。你解一次冲突，git 记住解法。下次碰到一样的冲突，直接套用，不再问你。bingo-light 还会检测到自动解决的冲突后自己继续 rebase，不会卡着等人。
</details>

<details>
<summary><b>同步搞砸了？</b></summary>

`bingo-light undo`。补丁分支秒回同步前的状态。底层用 reflog，再复杂的 rebase 也能回。
</details>

<details>
<summary><b>支持 GitHub/GitLab/Bitbucket 吗？</b></summary>

都支持。底层就是标准 git 操作（fetch、rebase、push），什么 git 远程都能用。`auto-sync` 能生成 GitHub Actions 流水线，但核心功能不绑平台。
</details>

<details>
<summary><b>和 <code>git format-patch</code> / quilt 有什么区别？</b></summary>

`format-patch` 能导出但不管活的补丁栈。quilt 管栈但脱离了 git。bingo-light 的补丁就是真正的 git commit，享受完整历史、冲突解决、rerere 记忆，同时支持 quilt 格式导出导入。
</details>

## 为什么不用...

<details>
<summary><b>...GitHub 的 "Sync fork" 按钮？</b></summary>
<br>

只能 fast-forward。你一有自己的改动，它要么拒绝要么生成 merge commit 把你的代码埋了。没有补丁栈，没有冲突记忆，没有 API。
</details>

<details>
<summary><b>...手动 <code>git rebase</code>？</b></summary>
<br>

可以，6 步：fetch、切 tracking 分支、pull、切 patches 分支、rebase、push。得记住分支名、手动开 rerere、搞砸了自己从 reflog 里捞。`bingo-light sync` 一条命令包了，还带撤销、冲突预测和结构化输出。
</details>

<details>
<summary><b>...StGit / quilt / TopGit？</b></summary>
<br>

StGit 管栈但没 AI 集成、没 MCP、没 JSON 输出、没冲突预测。quilt 脱离 git 体系，没 rerere 没历史。TopGit 基本废弃了。这些工具都不是为 AI 时代设计的。
</details>

## 与其他方案对比

| | **bingo-light** | GitHub Sync | git rebase | quilt | StGit |
|---|:---:|:---:|:---:|:---:|:---:|
| 命名补丁栈 | **有** | 无 | 无 | 有 | 有 |
| 一键同步 | **有** | 仅按钮 | 无（6 步） | 无 | 无 |
| 处理定制化改动 | **有** | **不行** | 手动 | 手动 | 手动 |
| 冲突记忆 (rerere) | **自动** | 无 | 需手动启用 | 无 | 无 |
| 冲突预测 | **有** | 无 | 无 | 无 | 无 |
| AI/MCP 集成 | **29 个工具** | 无 | 无 | 无 | 无 |
| JSON 输出 | **所有命令** | 无 | 无 | 无 | 无 |
| 非交互模式 | **原生支持** | 无 | 部分 | 部分 | 部分 |
| 撤销同步 | **一条命令** | 无 | git reflog | 手动 | 手动 |
| 安装方式 | 一条命令 | 内置 | 内置 | 包管理器 | 包管理器 |

## 项目生态

```
bingo-light          CLI 入口（Python 3，零依赖）
bingo_core/          核心库包（全部业务逻辑）
mcp-server.py        MCP 服务器（零依赖 Python 3，29 个工具）
contrib/agent.py     Advisor 代理（监控 + 分析 + 安全时自动同步）
contrib/tui.py       终端面板（curses TUI）
install.sh           安装器（--yes 支持 CI，--help 查看选项）
completions/         Shell 补全（bash/zsh/fish）
contrib/hooks/       通知 Hook 示例（Slack/Discord/Webhook）
tests/               测试套件（250 个测试，5 个文件）
docs/                文档
```

## 参与贡献

欢迎 PR。纯 Python，零依赖，不用构建。

```bash
git clone https://github.com/DanOps-1/bingo-light.git
cd bingo-light
make test       # 核心测试
make test-all   # 全部 250 个测试
make lint       # Python 语法 + flake8 + shellcheck
```

详见 [CONTRIBUTING.md](CONTRIBUTING.md)。

## 许可证

[MIT](LICENSE)
