# mpatch

**Repository Path**: studioustiger/mpatch

## Basic Information

- **Project Name**: mpatch
- **Description**: MPatch（Match-Patch） 是一个高性能、轻量级的 Java 代码增量更新引擎。它专为 AI 辅助编程场景设计，能够解析 AI 生成的 SEARCH/REPLACE 指令，并以极高的可靠性将其应用到源代码中。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-02-06
- **Last Updated**: 2026-02-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Java, Git, AI, 增量引擎, 增量更新

## README

# MPatch

[![License](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
[![Java Version](https://img.shields.io/badge/java-17%2B-orange.svg)](https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html)

MPatch（Match-Patch） 是一个高性能、轻量级的 Java 代码增量更新引擎。它专为 AI 辅助编程场景设计，能够解析 AI 生成的 `SEARCH/REPLACE` 指令，并以极高的可靠性将其应用到源代码中。

## 为什么选择 MPatch？

在与大语言模型（LLM）交互时，请求模型返回整个文件既耗费 Token 又容易因上下文限制导致代码截断。Match-Patch 采用增量更新方案：
- **极致效率**：只传输和修改变化的部分。
- **保护代码结构**：避免不必要的全量重写导致的格式丢失或意外改动。
- **容错性强**：内置智能匹配算法，自动处理缩进差异和空白字符。

## 核心特性详解

### 1. 智能匹配算法
- **精确匹配**：首先尝试在源码中定位完全一致的代码块。
- **模糊匹配**：如果精确匹配失败，引擎会自动进入模糊模式：
    - 忽略换行符差异（CRLF vs LF）。
    - 忽略连续空格、制表符的差异。
    - 忽略标点符号（如 `{`, `}`, `(`, `)`）周围的冗余空白。
    - 确保在 AI 略微改变代码格式的情况下依然能精准定位。

### 2. 灵活的更新模式
- **增量模式 (SEARCH/REPLACE)**：解析专有的指令块进行局部修改。
- **全量回退**：如果输入内容不包含指令标记，引擎会自动将其视为全量新代码进行更新。

### 3. 安全与健壮性
- **唯一性校验**：默认要求 `SEARCH` 内容在源文件中必须是唯一的，防止误改。
- **代码块提取**：自动识别并提取 Markdown 代码块（如 ` ```java ` ）中的内容，直接支持 AI 原生输出。
- **残留标记检测**：应用更新后自动扫描代码，确保没有 `------- SEARCH` 等标记残留，防止破坏编译。

### 4. 批量操作
支持在单次指令中包含多个 `SEARCH/REPLACE` 块，引擎会按顺序依次应用，确保原子性。

---

## 快速上手

### 1. 引入依赖 (Maven)

```xml
<dependency>
  <groupId>com.hxh</groupId>
  <artifactId>match-patch</artifactId>
  <version>1.0-SNAPSHOT</version>
</dependency>
```

### 2. 核心 API 演示

```java
import com.hxh.mpatch.core.CodeIncrementalUpdater;
import com.hxh.mpatch.model.UpdateResult;

public class MatchPatchDemo {
  public static void main(String[] args) {
    CodeIncrementalUpdater updater = CodeIncrementalUpdater.getInstance();

    String sourceCode = """
            public class Calculator {
                public int add(int a, int b) {
                    return a + b;
                }
            }
            """;

    String instructions = """
            ------- SEARCH
                public int add(int a, int b) {
                    return a + b;
                }
            =======
                /**
                 * 执行加法运算
                 */
                public int add(int a, int b) {
                    return a + b;
                }
            +++++++ REPLACE
            """;

    UpdateResult result = updater.apply(instructions, sourceCode);

    if (result.isSuccess()) {
      System.out.println("更新成功：\n" + result.getUpdatedCode());
    } else {
      System.err.println("更新失败：" + result.getError());
    }
  }
}
```

---

## 多样化示例

### 场景 A：新增方法（利用现有方法作为锚点）
```text
------- SEARCH
    public void existingMethod() {
    }
=======
    public void existingMethod() {
    }

    public void newMethod() {
        System.out.println("Hello New Method!");
    }
+++++++ REPLACE
```

### 场景 B：删除代码
```text
------- SEARCH
    @Deprecated
    private void oldLogic() {
        // ...
    }
=======

+++++++ REPLACE
```

### 场景 C：批量修改多个位置
```text
------- SEARCH
import java.util.List;
=======
import java.util.List;
import java.util.ArrayList;
+++++++ REPLACE
------- SEARCH
    private List<String> items;
=======
    private List<String> items = new ArrayList<>();
+++++++ REPLACE
```

---

## 高级配置 (MatchOptions)

你可以通过 `MatchOptions` 自定义引擎的行为：

| 配置项 | 默认值 | 说明 |
| :--- | :--- | :--- |
| `requireUniqueMatch` | `true` | 是否要求搜索内容在源文件中唯一 |
| `allowFuzzyMatch` | `true` | 是否开启模糊匹配（忽略空白差异） |
| `contextLines` | `3` | 错误信息中显示的上下文行数 |

```java
MatchOptions options = MatchOptions.builder()
    .requireUniqueMatch(true)
    .allowFuzzyMatch(false) // 强制要求精确匹配
    .build();

// 在应用时使用特定选项
// UpdateResult result = updater.applySearchReplace(source, search, replace, options);
```

---

## 指令格式规范

引擎识别的增量更新指令必须满足以下结构：

1.  **起始标记**：至少 7 个 `-` 紧跟 `SEARCH`。
2.  **搜索内容**：紧接在起始标记后的代码片段。
3.  **分割标记**：至少 7 个 `=`。
4.  **替换内容**：紧接在分割标记后的新代码。
5.  **结束标记**：至少 7 个 `+` 紧跟 `REPLACE`。

> **提示**：关于如何应用这些格式进行复杂场景（如删除、批量修改）的实战范例，请参阅 [Skill.md](./Skill.md)。

---

## 详细操作指南 (Skill)

为了让用户（或 AI 助手）更好地掌握增量更新的各种技巧，我们提供了一份详细的技能指南：[Skill.md](./Skill.md)。

该指南涵盖了：
- **六种核心操作模式**：新增单个/多个、编辑单个/多个、删除单个/多个。
- **原始内容演示**：通过具体的代码示例展示转换过程。
- **非代码文件支持**：如何在 Markdown、JSON 等文本文档中使用增量更新。
- **最佳实践建议**：如何编写高质量的 SEARCH 块以提高匹配成功率。

---

## 许可证

本项目采用 [MIT License](LICENSE) 许可证。

## 贡献与支持

作者: [huxuehao](https://github.com/huxuehao)