零依赖 · 离线优先的 unified diff 补丁引擎与三方合并工具箱 让 AI Agent 的每一次代码改动都「可校验、可应用、可撤回、可追溯」。
当一个仓库里跑着多个 AI Agent、或者你在 CI 里自动消费 LLM 生成的补丁时,往往会遇到这些糟心事:
| 痛点 | 后果 |
|---|---|
🤖 Agent 吐出的 diff 格式野得很(带时间戳、CRLF、\ No newline、正文里混着 ---) |
解析器把正文误判成文件头,补丁直接报废 |
| 💥 打到一半失败了,前面几个文件已经写进磁盘 | 仓库处于「半应用」的脏状态,只能手工回滚 |
🪟 目标机器是 Windows,没装 Git / patch(1) |
现成工具链压根跑不起来 |
| 🔀 两个 Agent 同时改了同一份配置 | 谁改了哪几行、冲突在哪,全靠肉眼比对 |
| 🧾 想让 CI 判断「这次合并有没有冲突」 | 只拿到一堆人类可读文本,没法程序化处理 |
PatchWeave 就是把这条链路做成一个纯 Python 标准库、零依赖、单仓可落地的确定性引擎:解析 → 校验 → 应用 / 撤回 → 三方合并 → 结构化报告,全程离线,不依赖 Git 二进制。
与 git apply、patch(1)、pyasn1 之类的现成方案相比,PatchWeave 的取舍很明确:
- 🧠 按计数精确解析:hunk 区块由
@@ -a,b +c,d @@声明的行数界定,因此正文里出现--- xxx不会被误判成新文件头;同时完整保留\ No newline at end of file、CRLF、BOM 等真实世界脏输入。 - 🛡️ 真·原子事务:所有文件先在内存里算完,任一 hunk 失败则整个补丁零落盘;写盘阶段异常还会自动把已改动文件恢复成原始字节。
- 🔍 可控的模糊匹配:
--fuzz 0..3允许上下文偏移与首尾裁剪(GNU patch 语义),但每次模糊命中都会留下FUZZY_MATCH审计记录,绝不静默猜错。 - 🔀 结构化三方合并:diff3 不只是吐冲突标记,还输出带 base 行号 + 两侧内容 的 JSON 冲突清单,Agent / CI 可以直接据此决策。
- 🪶 零依赖、真跨平台:只用标准库,Python 3.8+,Windows 上不需要 Git;可作为库嵌入,也可当 CLI 用。
- 🔐 路径逃逸防护:绝对路径、盘符、
..、以及通过符号链接越出工作目录,一律拒绝。
来自 GitHub Trending 上 max-sixty/worktrunk ——「为并行 AI Agent 设计的 Git worktree 管理 CLI」所指向的并行协作与变更合并痛点。
本项目账号下已有
grove/gitworktree两款 worktree 编排工具(功能定位相似度 ≥ 90%,按去重规则一票否决)。因此 PatchWeave 不复制其任何功能,只借鉴痛点,把问题下沉到账号完全空白的补丁算法层:unified diff 解析、确定性应用、diff3 三方合并。 全部代码 100% 独立自研,未复用任何现有实现。
| 模块 | 能力 | 亮点 |
|---|---|---|
📥 解析 parser.py |
标准 ---/+++/@@、Git 扩展头(新建/删除/重命名/二进制)、多文件、时间戳、空上下文行 |
按 hunk 计数界定区块,抗脏输入 |
✅ 校验 lint_patch |
hunk 行数一致性、路径安全、重复文件段、空 hunk | 返回结构化 Issue 列表 |
⚙️ 应用 apply.py |
严格 / 模糊匹配、反向撤回、dry-run、备份、原子落盘、回滚 | 失败保证零落盘 |
🔀 合并 merge3.py |
diff3 三方合并、4 种冲突策略、||||||| base 三段式标记、JSON 冲突清单 |
Agent 友好 |
📊 报告 report.py |
终端文本、diffstat、JSON 报告落盘 | 可直接被 CI 解析 |
🖥️ CLI cli.py |
inspect / check / stat / apply / reverse / merge3 |
统一退出码语义 |
其他细节 🧩:保留 LF/CRLF 换行风格、UTF-8 BOM、文件末尾无换行状态;surrogateescape 兜底任意字节;os.replace 原子写;.pw-bak 备份;Python 库 API 与 CLI 能力完全对等。
| 项目 | 要求 |
|---|---|
| 🐍 Python | 3.8 或更高(3.8 / 3.9 / 3.10 / 3.11 / 3.12 均在 CI 覆盖) |
| 📦 第三方依赖 | 无,requirements.txt 为空 |
| 💻 操作系统 | Linux / macOS / Windows 全平台 |
| 🔧 是否需要 Git | 不需要 |
# 方式一:从 PyPI(发布后)
pip install patchweave
# 方式二:从源码
git clone https://github.com/gitstq/PatchWeave.git
cd PatchWeave
pip install -e .
# 方式三:不安装,直接用(零依赖的好处)
python -m patchweave --version# 1️⃣ 校验补丁是否完整
python -m patchweave check examples/basic.patch
# 2️⃣ 先预览,不碰磁盘
python -m patchweave apply examples/basic.patch -d ./myrepo --dry-run
# 3️⃣ 确认无误后真正应用
python -m patchweave apply examples/basic.patch -d ./myrepo
# 4️⃣ 后悔了?原样撤回
python -m patchweave reverse examples/basic.patch -d ./myrepo
# 5️⃣ 一键跑通全部演示
bash examples/demo.shWindows PowerShell 用户把最后一行换成:
powershell -File scripts/build.ps1 # 构建
python -m patchweave check examples/basic.patchfrom patchweave import parse_patch, apply_patch, merge3_text
patch = parse_patch(open("change.patch", encoding="utf-8").read())
result = apply_patch(patch, "./myrepo", fuzz=2, backup=True)
print(result.ok, result.to_json())
merged = merge3_text(base_text, ours_text, theirs_text)
if not merged.ok:
for c in merged.conflicts:
print(f"冲突:base 第 {c.base_start}-{c.base_end} 行", c.ours, c.theirs)| 命令 | 作用 | 典型用法 |
|---|---|---|
inspect |
解析并打印结构 | patchweave inspect change.patch --json |
check |
静态校验补丁 | patchweave check change.patch |
stat |
diffstat 统计 | patchweave stat change.patch --json |
apply |
应用补丁 | patchweave apply change.patch -d ./repo --fuzz 2 --backup |
reverse |
反向撤回 | patchweave reverse change.patch -d ./repo |
merge3 |
三方合并 | patchweave merge3 base.py ours.py theirs.py -o merged.py |
| 参数 | 默认值 | 说明 |
|---|---|---|
-d, --dir |
. |
工作目录,补丁里的相对路径以此为准 |
--fuzz N |
0 |
模糊因子 0..3;0 为严格匹配 |
--no-strict |
关闭 | 允许宽松匹配(配合 --fuzz 使用) |
--dry-run |
关闭 | 只计算、只输出计划,不写盘 |
--backup |
关闭 | 为每个改动文件生成 *.pw-bak |
--no-create-dirs |
关闭 | 禁止自动创建新文件所在目录 |
--json |
关闭 | 输出结构化 JSON 结果 |
--report PATH |
— | 把 JSON 报告写入文件 |
| 参数 | 默认值 | 说明 |
|---|---|---|
-o, --output |
stdout | 合并结果写入文件 |
--strategy |
merge |
merge / ours / theirs / base |
--show-base |
关闭 | 冲突块加入 ` |
--label-ours / --label-theirs / --label-base |
ours / theirs / base |
自定义冲突标记名称 |
--json |
关闭 | 只输出 JSON 冲突报告 |
--report PATH |
— | 把 JSON 报告写入文件 |
| 码 | 含义 |
|---|---|
0 |
✅ 成功(合并零冲突) |
1 |
|
2 |
❌ 参数或解析错误 |
场景 A · CI 里安全消费 Agent 生成的补丁
python -m patchweave check agent.patch --json > check.json || exit 1
python -m patchweave apply agent.patch -d . --dry-run --json > plan.json || exit 1
python -m patchweave apply agent.patch -d . --report apply-report.json场景 B · 上下文漂移了但补丁仍然有效
# 文件被人在开头插了一行,严格匹配会失败;fuzz=2 允许偏移并留下审计
python -m patchweave apply change.patch -d . --fuzz 2 --json场景 C · 两个 Agent 改了同一份配置
python -m patchweave merge3 base.py agent_a.py agent_b.py \
-o merged.py --show-base --report conflicts.json
# 冲突数 > 0 时退出码为 1,CI 可据此转人工或再交给 Agent 决策场景 D · 把冲突交给程序处理
from patchweave import merge3_text
r = merge3_text(base, ours, theirs, strategy="merge")
for c in r.conflicts:
print(c.base_start, c.base_end, c.base, c.ours, c.theirs)
print(r.to_json()) # 结构化,可直接塞进下游 Agent 的上下文{
"ok": true,
"conflict_count": 0,
"strategy": "merge",
"conflicts": []
}应用结果的 JSON 还包含 changed_files、planned_files、issues(含 FUZZY_MATCH 审计)、backups 等字段。
📸
docs/screenshots/cli-demo.png—— 计划补充check → dry-run → apply → reverse的终端录屏与merge3冲突高亮截图,欢迎贡献。
patchweave/
├── model.py # 纯数据模型:Patch / FilePatch / Hunk / PatchLine / *Result
├── parser.py # unified diff 解析 + lint 静态校验 + diffstat
├── apply.py # 确定性应用 / 反向 / 模糊匹配 / 原子事务 / 回滚
├── merge3.py # diff3 三方合并 + 冲突清单
├── report.py # 文本 / Markdown / JSON 报告渲染
├── cli.py # argparse CLI(6 个子命令)
└── __main__.py # python -m patchweave
数据流:文本 → Patch → lint → ApplyResult/MergeResult → JSON/终端。
模型层与 I/O 层解耦,apply_patch 先把所有文件算进内存再统一落盘,这是「原子性」能成立的结构前提。
| 决策 | 原因 |
|---|---|
| 🐍 纯 Python 标准库 | 零安装摩擦,Windows / 离线 / 嵌入 Agent 都能跑 |
| 📐 按 hunk 计数解析 | 比「靠前缀猜文件头」健壮得多,能扛住真实补丁里的各种脏行 |
🧮 difflib.SequenceMatcher 做 diff3 |
标准库自带、行为确定;在其上做区间聚类与映射,避免引入 LibGit2 |
🧱 数据类 + to_dict() |
让每个结果天然可 JSON 序列化,下游无需再解析人类文本 |
🔒 realpath 校验 + os.replace |
同时解决路径逃逸与写盘半途失败 |
- 📦 支持
GIT binary patch的二进制内容应用(当前明确报错,不静默跳过) - 🧩 支持 context diff / ed 格式,以及
@@@组合 diff - 🤖 内置「冲突自动裁决」插件接口,让 Agent 注册自定义 resolver
- 📊 输出 SARIF 报告,直接接入 GitHub Code Scanning
- 🌐 提供可选的 Web UI 用于可视化冲突块
- 🧠 大文件场景下的流式解析与内存优化
最欢迎的三类贡献:更多真实世界补丁样本(用于回归测试)、跨平台 CI 反馈、冲突策略的边界用例。详见 CONTRIBUTING.md。
PatchWeave 属于库 / CLI 工具类项目:纯 Python、py3-none-any 通用 wheel,无需按平台编译原生二进制。
因此按规则不强制上传平台可执行文件,但仍在 Release 附上 sdist + wheel 便于离线安装。
# Linux / macOS / WSL / Git Bash
bash scripts/build.sh
# Windows PowerShell
powershell -File scripts/build.ps1
# 或直接用 Make
make build脚本会依次:跑 44 项单元测试 → 清理旧产物 → 构建 wheel → 构建 sdist → 校验 dist/ 产物数量。
产物示例:
dist/
├── patchweave-1.0.0-py3-none-any.whl 约 22 KB
└── patchweave-1.0.0.tar.gz 约 23 KB
| 场景 | 做法 |
|---|---|
| 🖥️ 本机 CLI | pip install patchweave,然后 patchweave check ... |
| 🧱 嵌入 Agent | 把 patchweave/ 目录直接拷进项目(零依赖,无需 pip) |
| 🐳 容器 / 离线环境 | pip install --no-index --find-links dist/ patchweave |
| 🔁 CI | pip install -e . 后调用 python -m patchweave ...,用退出码判定 |
python -m unittest discover -s tests -v # 44 项测试,覆盖解析/应用/合并/CLI
python -m patchweave check examples/basic.patch
bash examples/demo.sh # 端到端演示
bash scripts/build.sh # 构建 + 产物校验CI 矩阵覆盖 3 个操作系统 × 5 个 Python 版本(3.8–3.12),配置见 .github/workflows/ci.yml。
欢迎 PR!简要规则:
- 📝 提交信息遵循 Angular 规范:
feat(apply): .../fix(parser): .../docs: .../test: ... - 🚫 不要引入运行时第三方依赖(这是项目的核心约束)
- ✅ 新增行为必须配单元测试;合并前跑通
python -m unittest discover -s tests -v - 🌏 若改变公开 API 或 CLI,请同步更新三语 README
- 🐛 提 Issue 请附:系统 / Python 版本、复现命令、最小可复现补丁、期望与实际行为
完整说明见 CONTRIBUTING.md。
本项目采用 MIT License,详见 LICENSE。
你可以自由使用、复制、修改、合并、发布、分发、再授权及销售本软件, 只需保留版权声明与许可声明。软件按「原样」提供,不含任何明示或默示担保。
🧵 PatchWeave — 让补丁不再是「祈祷式操作」。