bingo-light 2.0.1 → 2.1.1

package/README.md

@@ -2,130 +2,149 @@
   <br>
   <img src="docs/logo.svg" alt="bingo-light logo" width="200">
   <br><br>
-  <strong>Fork maintenance for humans and AI agents.<br>One command to sync. Zero dependencies.</strong>
+  <strong>Fork 同步，一条命令搞定。<br>人用、AI 用，零依赖。</strong>
   <br><br>
-  <b>English</b> | <a href="README.zh-CN.md">简体中文</a>
+  <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>
-  <br>
-  <a href="#for-ai-agents"><img src="https://img.shields.io/badge/MCP_Server-29_tools-blueviolet.svg" alt="MCP: 29 tools"></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's "Sync fork" button breaks the moment you have customizations. `git rebase` is a 6-step ritual. And none of it works from an AI agent.
+GitHub 的 "Sync fork" 按钮？你一改代码它就废了。手动 `git rebase`？六步操作，每次都得记。AI 想帮你同步？没接口可调。
 
-**bingo-light fixes all three.**
+**bingo-light 把这三个问题一锅端。**
 
-Your patches live as a clean, named stack on top of upstream. Syncing is `bingo-light sync`. Conflicts get remembered so you never solve the same one twice. And if something goes sideways, `bingo-light undo` puts everything back in one second.
+改动以补丁栈的形式叠在上游之上，干干净净。同步一句 `bingo-light sync`。冲突解过一次就记住了，下次自动跳过。搞砸了 `bingo-light undo` 秒回。
 
-Every command speaks JSON. The built-in MCP server gives AI agents 29 tools to manage your fork autonomously -- from init through conflict resolution. No human in the loop required.
+所有命令支持 `--json` 输出。内置 MCP 服务器 29 个工具，AI 从初始化到冲突解决全程自主，不用人盯。
 
 ---
 
-<p align="center">
-  <img src="docs/demo.svg" alt="bingo-light demo" width="850">
-</p>
+## 目录
+
+- [快速开始](#快速开始)
+- [演示](#演示)
+- [安装](#安装)
+- [功能特性](#功能特性)
+- [工作原理](#工作原理)
+- [MCP 服务器](#mcp-服务器)
+- [命令参考](#命令参考)
+- [集成指南](#集成指南)
+- [配置](#配置)
+- [常见问题](#常见问题)
+- [与其他方案对比](#与其他方案对比)
+- [项目生态](#项目生态)
+- [参与贡献](#参与贡献)
+- [许可证](#许可证)
 
 ---
 
-## Quick Start
+## 快速开始
 
 ```bash
-# Install (pick one)
+# 安装（任选一种）
 pip install bingo-light             # Python
 npm install -g bingo-light          # Node.js
 brew install DanOps-1/tap/bingo-light  # Homebrew
 
-# Point at upstream
-cd your-forked-project
+# 初始化 Fork 追踪
+cd my-forked-project
 bingo-light init https://github.com/original/project.git
 
-# Sync whenever you want -- patches rebase on top automatically
+# 改代码，创建命名补丁
+vim src/feature.py
+bingo-light patch new my-feature
+
+# 上游有更新？一句话同步
 bingo-light sync
 ```
 
-That's it. Three commands and your fork stays in sync forever.
+就这么简单。补丁永远干净地叠在最新上游之上。
 
-## Demo
+## 演示
 
-### Basic workflow: init, patch, sync
+### 日常操作：初始化 → 建补丁 → 同步
 
 <p align="center">
-  <img src="docs/demo.svg" alt="bingo-light basic demo" width="850">
+  <img src="docs/demo.svg" alt="bingo-light 基本演示" width="850">
 </p>
 
-### Conflict resolution: sync, analyze, resolve
+### 冲突处理：同步 → 分析 → 搞定
 
 <p align="center">
-  <img src="docs/demo-conflict.svg" alt="bingo-light conflict resolution demo" width="850">
+  <img src="docs/demo-conflict.svg" alt="bingo-light 冲突解决演示" width="850">
 </p>
 
-> The AI calls `conflict-analyze --json`, reads the structured ours/theirs data, writes the merged file, and the rebase continues. No human needed.
+> AI 调 `conflict-analyze --json` 拿到双方代码，写好合并结果，rebase 自动继续。全程零人工。
 
----
+### AI 拿到的是结构化数据
 
-## Key Features
-
-### For Humans
-
-- :wrench: **Zero deps** -- just Python 3 + git. `pip install bingo-light` and go.
-- :bookmark_tabs: **Named patch stack** -- each customization is one atomic, named commit. No more guessing which changes are yours.
-- :zap: **One-command sync** -- `bingo-light sync` fetches upstream and rebases your patches on top. Done.
-- :brain: **Conflict memory** -- git rerere auto-enabled. Resolve a conflict once, never resolve it again.
-- :rewind: **Instant undo** -- `bingo-light undo` restores pre-sync state. No reflog spelunking.
-- :crystal_ball: **Conflict prediction** -- `status` warns you about risky files before you sync.
-- :test_tube: **Dry-run mode** -- `sync --dry-run` tests on a throwaway branch first.
-- :stethoscope: **Built-in doctor** -- full diagnostic with test rebase to catch problems early.
-- :package: **Export/Import patches** -- share as `.patch` files, quilt-compatible format.
-- :robot: **Auto-sync CI** -- generates a GitHub Actions workflow with conflict alerting.
-- :tv: **TUI dashboard** -- curses-based real-time monitoring via `contrib/tui.py`.
-- :globe_with_meridians: **Multi-repo workspace** -- manage multiple forks from one place.
-- :bell: **Notification hooks** -- Slack, Discord, webhooks on sync/conflict/test events.
-- :label: **Patch metadata** -- tags, reasons, expiry dates, upstream PR tracking.
-- :tab: **Shell completions** -- tab completion for bash, zsh, and fish.
-
-### For AI Agents
-
-- :electric_plug: **MCP server (29 tools)** -- full fork management from init through conflict resolution.
-- :bar_chart: **`--json` on everything** -- every command returns structured JSON. Parse, don't scrape.
-- :mute: **`--yes` flag** -- fully non-interactive. No TTY required. No prompts. Ever.
-- :gear: **Auto-detect non-TTY** -- pipes and subprocesses trigger non-interactive mode automatically.
-- :memo: **`BINGO_DESCRIPTION` env var** -- set patch descriptions without stdin.
-- :mag: **`conflict-analyze --json`** -- structured conflict data: file, ours, theirs, resolution hints.
-- :white_check_mark: **`conflict-resolve`** -- write resolved content via MCP, auto-stage, continue rebase. Zero manual intervention.
-- :satellite: **Advisor agent** -- `contrib/agent.py` monitors drift, analyzes risk, auto-syncs when safe.
+```
+$ 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 直接消费）
 
-## Installation
+```
+$ 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": "上游重构了调度器核心；补丁需要适配新结构。"
+    }
+  ]
+}
+```
 
-Install with any package manager, then run `bingo-light setup` to interactively configure MCP for your AI tools (Claude Code, Cursor, Windsurf, VS Code/Copilot, Zed, Gemini CLI, etc.).
+## 安装
+
+装完跑 `bingo-light setup`，交互式配好 MCP 和 AI Skill（Claude Code、Cursor、Windsurf、VS Code/Copilot、Gemini CLI 等一键选配）。
 
 ### pip / pipx
 
 ```bash
-pip install bingo-light        # or: pipx install bingo-light
-bingo-light setup              # interactive — pick which AI tools to configure
+pip install bingo-light        # 或: pipx install bingo-light
+bingo-light setup              # 选配 AI 工具
 ```
 
 ### npm / npx
 
 ```bash
-npm install -g bingo-light     # global install
+npm install -g bingo-light     # 全局安装
 bingo-light setup
 
-# Or use npx — no install needed:
+# 或 npx 免装：
 npx bingo-light setup
 ```
 
-MCP clients can use npx directly:
+MCP 客户端直接用 npx：
 ```json
 {"command": "npx", "args": ["-y", "bingo-light-mcp"]}
 ```
@@ -143,20 +162,20 @@ bingo-light setup
 # CLI
 docker run --rm -v "$PWD:/repo" -w /repo ghcr.io/danops-1/bingo-light status
 
-# MCP server (stdio transport)
+# MCP 服务器（stdio）
 docker run --rm -i -v "$PWD:/repo" -w /repo ghcr.io/danops-1/bingo-light mcp-server.py
 ```
 
-### Shell installer
+### Shell 安装器
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/DanOps-1/bingo-light/main/install.sh | sh
 
-# Non-interactive (CI / Docker)
+# 非交互模式（CI / Docker）
 curl -fsSL .../install.sh | sh -s -- --yes
 ```
 
-### From source
+### 从源码安装
 
 ```bash
 git clone https://github.com/DanOps-1/bingo-light.git
@@ -164,46 +183,78 @@ cd bingo-light
 make install && bingo-light setup
 ```
 
-**Requirements:** Python 3.8+, git 2.20+. Zero pip dependencies.
-
----
-
-## How It Works
+**依赖：** 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 ──────── exact mirror of upstream, never touched
+  upstream-tracking ─────── 上游的精确镜像，从不手动碰
       |
       |  git rebase
       v
-  bingo-patches ────────────  your customizations stacked here
+  bingo-patches ─────────── 你的改动叠在这里
       |
-      +── [bl] custom-scheduler:  O(1) task scheduling
-      +── [bl] perf-monitoring:   eBPF tracing hooks
-      +── [bl] fix-logging:       structured JSON logs
+      +── [bl] custom-scheduler:  O(1) 任务调度
+      +── [bl] perf-monitoring:   eBPF 追踪钩子
+      +── [bl] fix-logging:       结构化 JSON 日志
       |
       v
-    HEAD (your working fork)
+    HEAD (你的工作 Fork)
 ```
 
-**Sync flow:** fetch upstream, fast-forward the tracking branch, rebase your patches on top. Your patches always sit cleanly on the latest upstream.
-
-**Conflict memory:** `init` auto-enables git rerere. Resolve a conflict once and git remembers the resolution. Next sync applies it automatically. bingo-light detects auto-resolved conflicts and continues the rebase without stopping.
+**同步：** fetch 上游 → 快进追踪分支 → rebase 补丁到最新上游。补丁永远干净地叠在最新代码上。
 
-**AI conflict flow:** rebase hits a conflict, the AI calls `conflict-analyze` for structured data (ours/theirs/hints per file), writes the resolution via `conflict-resolve`, and rebase continues. No human in the loop.
+**冲突记忆：** 初始化时自动开 rerere。解过一次，git 就记住了——下次碰到同样的冲突直接跳过。
 
----
+**AI 解冲突：** rebase 卡住时，AI 调 `conflict-analyze` 拿双方代码和提示，写好合并结果扔给 `conflict-resolve`，rebase 自动继续，不用人管。
 
-## For AI Agents
+## MCP 服务器
 
-bingo-light was designed from day one for AI agents. Every command speaks JSON. The MCP server exposes 29 tools covering the full lifecycle from `init` to `conflict-resolve`. Non-interactive mode is the default when stdin is not a TTY.
+`mcp-server.py`，纯 Python 3，零依赖，stdio 传输，29 个工具，JSON-RPC 2.0。
 
-### MCP setup -- Claude Code
+运行 `bingo-light setup` 自动配置，或手动添加：
 
-Add to `.mcp.json` in your project root or `~/.claude/settings.json`:
+**Claude Code**（`.mcp.json` 或 `~/.claude/settings.json`）：
 
 ```json
 {
@@ -216,9 +267,7 @@ Add to `.mcp.json` in your project root or `~/.claude/settings.json`:
 }
 ```
 
-### MCP setup -- Claude Desktop
-
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+**Claude Desktop**（`~/Library/Application Support/Claude/claude_desktop_config.json`）：
 
 ```json
 {
@@ -231,105 +280,102 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 }
 ```
 
-**Any MCP client** (VS Code Copilot, Cursor, custom agents): connect via stdio to `python3 mcp-server.py`.
-
-### 29 MCP Tools
-
-| Tool | Purpose |
-|------|---------|
-| `bingo_init` | Initialize fork tracking |
-| `bingo_status` | Fork health: drift, patches, conflict risk |
-| `bingo_sync` | Fetch upstream + rebase patches |
-| `bingo_undo` | Revert to pre-sync state |
-| `bingo_patch_new` | Create a named patch |
-| `bingo_patch_list` | List patch stack with stats |
-| `bingo_patch_show` | Show patch diff |
-| `bingo_patch_drop` | Remove a patch |
-| `bingo_patch_export` | Export as `.patch` files |
-| `bingo_patch_import` | Import `.patch` files |
-| `bingo_patch_meta` | Get/set patch metadata |
-| `bingo_patch_squash` | Merge two patches into one |
-| `bingo_patch_reorder` | Reorder patches non-interactively |
-| `bingo_doctor` | Full diagnostic with test rebase |
-| `bingo_diff` | Combined diff vs upstream |
-| `bingo_auto_sync` | Generate GitHub Actions workflow |
-| `bingo_conflict_analyze` | Structured conflict data for AI resolution |
-| `bingo_conflict_resolve` | Write resolution, stage, continue rebase |
-| `bingo_config` | Get/set configuration |
-| `bingo_history` | Sync history with hash mappings |
-| `bingo_test` | Run configured test suite |
-| `bingo_workspace_status` | Multi-repo workspace overview |
-| `bingo_patch_edit` | Amend an existing patch |
-| `bingo_workspace_init` | Initialize multi-repo workspace |
-| `bingo_workspace_add` | Add a repo to workspace |
-| `bingo_workspace_sync` | Sync all workspace repos |
-| `bingo_workspace_list` | List workspace repos |
-
-### JSON examples
+**其他客户端**（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` | 列出工作区仓库 |
+
+## 命令参考
 
-```bash
-# Fork status (AI-friendly)
-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"]
-}
+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                             打印帮助
 ```
 
-```bash
-# Conflict analysis (structured data for AI resolution)
-bingo-light conflict-analyze --json
-```
+**全局标志：** `--json`（结构化 JSON 输出） | `--yes`（跳过所有确认提示）
 
-```json
-{
-  "rebase_in_progress": true,
-  "current_patch": "custom-scheduler",
-  "conflicts": [
-    {
-      "file": "kernel/sched/core.c",
-      "conflict_count": 2,
-      "ours": "... upstream version ...",
-      "theirs": "... your patch version ...",
-      "hint": "Upstream refactored scheduler core; patch needs to target new structure."
-    }
-  ]
-}
-```
+## 集成指南
+
+### Claude Code (MCP)
 
-### End-to-end AI workflow
+MCP 配好后，Claude Code 全程接管：
 
 ```
-User: "Sync my fork and fix any conflicts."
-
-AI Agent:
-  1. bingo_status(cwd)                   -> 47 behind, risk: core.c
-  2. bingo_sync(cwd, dry_run=true)       -> 1 conflict predicted
-  3. bingo_sync(cwd)                     -> rebase stops at conflict
-  4. bingo_conflict_analyze(cwd)         -> structured ours/theirs/hints
-  5. AI reads both versions, generates merge
-  6. bingo_conflict_resolve(cwd, file, content)  -> resolved, rebase continues
-  7. bingo_status(cwd)                   -> 0 behind, all patches clean
+你: "同步上游，冲突帮我修了。"
+
+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 落后，补丁干净
 ```
 
-### CLI integration (Aider, custom agents)
+### Aider / CLI 代理
 
 ```bash
-bingo-light status --json          # Parse fork state
-bingo-light sync --yes             # Non-interactive sync
-bingo-light conflict-analyze --json # Structured conflict data
+bingo-light status --json          # 解析 Fork 状态
+bingo-light sync --yes             # 非交互同步
+bingo-light conflict-analyze --json # 结构化冲突数据
 ```
 
+### 自定义 Python 代理
+
 ```python
 import subprocess, json
 
@@ -345,178 +391,144 @@ if status["behind"] > 0:
     result = bingo("sync")
     if result.get("conflicts"):
         analysis = bingo("conflict-analyze")
-        # AI resolves each conflict...
+        for c in analysis["conflicts"]:
+            resolved = my_llm_resolve(c["ours"], c["theirs"], c["hint"])
+            # 通过 CLI 或 MCP 写入解决内容
 ```
 
----
+## 配置
 
-## Command Reference
+配置存在 `.bingolight`（git-config 格式），自动排除在版本控制外。
 
-```
-bingo-light init <upstream-url> [branch]      Set up upstream tracking
-bingo-light sync [--dry-run] [--force]        Sync with upstream
-bingo-light sync --test                       Sync + run tests, undo on failure
-bingo-light undo                              Revert to pre-sync state
-bingo-light status                            Fork health + conflict prediction
-bingo-light diff                              Combined patch diff vs upstream
-bingo-light doctor                            Full diagnostic
-bingo-light log                               Sync history
-bingo-light history                           Detailed sync history with hash mappings
-bingo-light patch new <name>                  Create named patch from staged changes
-bingo-light patch list [-v]                   List patch stack
-bingo-light patch show <name|index>           Show patch diff
-bingo-light patch edit <name|index>           Amend a patch (stage changes first)
-bingo-light patch drop <name|index>           Remove a patch
-bingo-light patch reorder [--order "3,1,2"]   Reorder patches
-bingo-light patch export [dir]                Export as .patch files
-bingo-light patch import <file|dir>           Import .patch files
-bingo-light patch squash <idx1> <idx2>        Merge two patches
-bingo-light patch meta <name> [key] [value]   Get/set patch metadata
-bingo-light conflict-analyze                  Structured conflict data for AI
-bingo-light config get|set|list [key] [val]   Manage configuration
-bingo-light test                              Run configured test suite
-bingo-light workspace init|add|status|sync    Multi-repo management
-bingo-light auto-sync                         Generate GitHub Actions workflow
-bingo-light version                           Print version
-bingo-light help                              Show usage
+```bash
+bingo-light config set sync.auto-test true     # 同步后自动跑测试
+bingo-light config set test.command "make test" # 测试命令
+bingo-light config list                         # 查看所有配置
 ```
 
-**Global flags:** `--json` (structured output) | `--yes` / `-y` (skip all prompts)
+### 通知 Hook
 
----
+在 `.bingo/hooks/` 放可执行脚本：
 
-## Why not just...
+| Hook | 触发时机 |
+|------|---------|
+| `on-sync-success` | 同步成功后 |
+| `on-conflict` | rebase 碰到冲突时 |
+| `on-test-fail` | 同步后测试失败时 |
 
-<details>
-<summary><b>...click GitHub's "Sync fork" button?</b></summary>
-<br>
+Hook 通过 stdin 接 JSON。示例见 [contrib/hooks/](contrib/hooks/)（Slack / Discord / Webhook）。
 
-It only does fast-forward. The moment you have any customizations (commits on your fork that aren't in upstream), it either refuses or creates a merge commit that buries your changes. It has no concept of a patch stack, no conflict memory, and no API for AI agents.
-</details>
+## 常见问题
 
 <details>
-<summary><b>...use <code>git rebase</code> manually?</b></summary>
-<br>
+<summary><b>为什么不直接 <code>git rebase</code>？</b></summary>
 
-You can. It takes 6 steps: fetch, checkout tracking branch, pull, checkout patches branch, rebase, push. You need to remember which branch is which, manually enable rerere, and hope you don't mess up the reflog if something goes wrong. bingo-light wraps all of this into `bingo-light sync` with automatic undo, conflict prediction, and structured output.
+可以。bingo-light 包的是 rebase 周边那些烦事：追踪上游、维护补丁分支、开 rerere、预测冲突、输出结构化数据。偶尔 rebase 一次用不着它，但长期维护好几个补丁的话，省心省力。
 </details>
 
 <details>
-<summary><b>...use StGit / quilt / TopGit?</b></summary>
-<br>
+<summary><b>能用在已有的 Fork 上吗？</b></summary>
 
-StGit (649 stars) manages patch stacks but has no AI integration, no MCP server, no JSON output, and no conflict prediction. quilt operates outside git entirely -- no rerere, no history. TopGit is effectively abandoned. None of them were designed for the AI-agent era.
+能。进你的 Fork 目录，`bingo-light init <upstream-url>`，再 `bingo-light patch new <name>` 把现有改动转成补丁。标准 git 仓库就行。
 </details>
 
-## Comparison
-
-| | **bingo-light** | GitHub Sync | git rebase | quilt | StGit |
-|---|:---:|:---:|:---:|:---:|:---:|
-| Named patch stack | **Yes** | No | No | Yes | Yes |
-| One-command sync | **Yes** | Click only | No (6 steps) | No | No |
-| Handles customizations | **Yes** | **No** | Manual | Manual | Manual |
-| Conflict memory (rerere) | **Auto** | No | Manual | No | No |
-| Conflict prediction | **Yes** | No | No | No | No |
-| AI / MCP integration | **29 tools** | No | No | No | No |
-| JSON output | **All commands** | No | No | No | No |
-| Non-interactive mode | **Native** | No | Partial | Partial | Partial |
-| Undo sync | **One command** | No | git reflog | Manual | Manual |
-| Install | One command | Built-in | Built-in | Package mgr | Package mgr |
-
----
+<details>
+<summary><b>只给 AI 用？</b></summary>
 
-## FAQ
+人和 AI 用的是同一套命令。`bingo-light sync` 谁跑都一样。`--json`、`--yes`、MCP 这些是给 AI 加的接口，不加就是正常的人类输出。
+</details>
 
 <details>
-<summary><b>Why not just <code>git rebase</code>?</b></summary>
-<br>
+<summary><b>冲突记忆怎么回事？</b></summary>
 
-You can. bingo-light automates everything around it: tracking the upstream remote, maintaining a dedicated patch branch, enabling rerere, predicting conflicts before you sync, and exposing structured output for automation. For a one-off rebase it's overkill. For ongoing fork maintenance with 3+ patches across months of upstream drift, it saves serious time and eliminates an entire class of mistakes.
+`init` 时自动开了 git 的 `rerere`（reuse recorded resolution）。你解一次冲突，git 记住解法。下次碰到一样的冲突，直接套用，不再问你。bingo-light 还会检测到自动解决的冲突后自己继续 rebase，不会卡着等人。
 </details>
 
 <details>
-<summary><b>Can I use this on an existing fork?</b></summary>
-<br>
+<summary><b>同步搞砸了？</b></summary>
 
-Yes. Run `bingo-light init <upstream-url>` in your fork. Convert your existing changes into named patches with `bingo-light patch new <name>`. The tool works with any standard git repository -- it doesn't care how you got here.
+`bingo-light undo`。补丁分支秒回同步前的状态。底层用 reflog，再复杂的 rebase 也能回。
 </details>
 
 <details>
-<summary><b>Is this only for AI agents?</b></summary>
-<br>
+<summary><b>支持 GitHub/GitLab/Bitbucket 吗？</b></summary>
 
-No. The CLI is designed for humans first. `bingo-light sync` is the same command whether you run it or an AI does. The AI-native features (`--json`, `--yes`, MCP server) are purely additive -- without them you get normal, human-readable output with colors and progress indicators.
+都支持。底层就是标准 git 操作（fetch、rebase、push），什么 git 远程都能用。`auto-sync` 能生成 GitHub Actions 流水线，但核心功能不绑平台。
 </details>
 
 <details>
-<summary><b>How does conflict memory work?</b></summary>
-<br>
+<summary><b>和 <code>git format-patch</code> / quilt 有什么区别？</b></summary>
 
-bingo-light enables git's `rerere` (reuse recorded resolution) on `init`. When you resolve a conflict, git records the resolution. Next time the exact same conflict appears during sync, it's applied automatically. bingo-light detects when rerere has auto-resolved all conflicts and continues the rebase without stopping. You solve each conflict exactly once.
+`format-patch` 能导出但不管活的补丁栈。quilt 管栈但脱离了 git。bingo-light 的补丁就是真正的 git commit，享受完整历史、冲突解决、rerere 记忆，同时支持 quilt 格式导出导入。
 </details>
 
+## 为什么不用...
+
 <details>
-<summary><b>What if sync goes wrong?</b></summary>
+<summary><b>...GitHub 的 "Sync fork" 按钮？</b></summary>
 <br>
 
-Run `bingo-light undo`. It restores your patches branch to exactly where it was before the sync. This works via git reflog, so it's reliable even after complex rebases. You can also use `sync --dry-run` to test on a throwaway branch first, or `sync --test` to auto-undo if your test suite fails after sync.
+只能 fast-forward。你一有自己的改动，它要么拒绝要么生成 merge commit 把你的代码埋了。没有补丁栈，没有冲突记忆，没有 API。
 </details>
 
 <details>
-<summary><b>Does it work with GitHub / GitLab / Bitbucket?</b></summary>
+<summary><b>...手动 <code>git rebase</code>？</b></summary>
 <br>
 
-Yes. bingo-light uses standard git operations (fetch, rebase, push). It works with any git remote on any platform. The `auto-sync` command generates a GitHub Actions workflow specifically, but the core tool is completely platform-agnostic.
+可以，6 步：fetch、切 tracking 分支、pull、切 patches 分支、rebase、push。得记住分支名、手动开 rerere、搞砸了自己从 reflog 里捞。`bingo-light sync` 一条命令包了，还带撤销、冲突预测和结构化输出。
 </details>
 
 <details>
-<summary><b>How is this different from <code>git format-patch</code> / quilt?</b></summary>
+<summary><b>...StGit / quilt / TopGit？</b></summary>
 <br>
 
-`git format-patch` exports patches but doesn't manage them as a living stack. quilt manages patch stacks but operates outside git -- no conflict resolution, no rerere, no history. bingo-light keeps patches as real git commits so you get full git history, proper conflict resolution, and automatic rerere, while still supporting export/import in quilt-compatible `.patch` format. Best of both worlds.
+StGit 管栈但没 AI 集成、没 MCP、没 JSON 输出、没冲突预测。quilt 脱离 git 体系，没 rerere 没历史。TopGit 基本废弃了。这些工具都不是为 AI 时代设计的。
 </details>
 
----
+## 与其他方案对比
 
-## Project Ecosystem
+| | **bingo-light** | GitHub Sync | git rebase | quilt | StGit |
+|---|:---:|:---:|:---:|:---:|:---:|
+| 命名补丁栈 | **有** | 无 | 无 | 有 | 有 |
+| 一键同步 | **有** | 仅按钮 | 无（6 步） | 无 | 无 |
+| 处理定制化改动 | **有** | **不行** | 手动 | 手动 | 手动 |
+| 冲突记忆 (rerere) | **自动** | 无 | 需手动启用 | 无 | 无 |
+| 冲突预测 | **有** | 无 | 无 | 无 | 无 |
+| AI/MCP 集成 | **29 个工具** | 无 | 无 | 无 | 无 |
+| JSON 输出 | **所有命令** | 无 | 无 | 无 | 无 |
+| 非交互模式 | **原生支持** | 无 | 部分 | 部分 | 部分 |
+| 撤销同步 | **一条命令** | 无 | git reflog | 手动 | 手动 |
+| 安装方式 | 一条命令 | 内置 | 内置 | 包管理器 | 包管理器 |
+
+## 项目生态
 
 ```
-bingo-light          CLI tool (Python 3, zero deps)
-bingo_core/          Core library package (all business logic)
-mcp-server.py        MCP server (zero-dep Python 3, 29 tools, JSON-RPC 2.0)
-contrib/agent.py     Advisor agent (monitors drift, auto-syncs when safe)
-contrib/tui.py       Terminal dashboard (curses TUI, real-time monitoring)
-install.sh           Installer (--yes for CI, --help for options)
-completions/         Shell completions (bash / zsh / fish)
-contrib/hooks/       Notification hook examples (Slack / Discord / Webhook)
-tests/test.sh        Test suite (70 tests)
-docs/                Documentation + demo SVG
-docs/llms.txt        Complete LLM-consumable reference
+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/                文档
 ```
 
----
-
-## Documentation
-
-- [Getting Started](docs/getting-started.md) -- 5-minute quickstart guide
-- [Concepts](docs/concepts.md) -- branch model, patch stack, sync flow
-- [Changelog](CHANGELOG.md) -- version history
-- [Security](.github/SECURITY.md) -- security model and vulnerability reporting
-
-## Contributing
+## 参与贡献
 
-Pure Python, zero dependencies, no build step. If you can read Python, you can contribute.
+欢迎 PR。纯 Python，零依赖，不用构建。
 
 ```bash
 git clone https://github.com/DanOps-1/bingo-light.git
 cd bingo-light
-make test       # core test suite
-make test-all   # all 250 tests (core + fuzz + edge + MCP + unit)
-make lint       # python syntax + flake8 + shellcheck
+make test       # 核心测试
+make test-all   # 全部 250 个测试
+make lint       # Python 语法 + flake8 + shellcheck
 ```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+详见 [CONTRIBUTING.md](CONTRIBUTING.md)。
 
-## License
+## 许可证
 
-[MIT](LICENSE) -- do whatever you want.
+[MIT](LICENSE)