68 lines
2.2 KiB
Markdown
68 lines
2.2 KiB
Markdown
|
---
|
|||
|
|
title: Patch Tool 模糊补丁工具
|
|||
|
|
created: 2026-04-16
|
|||
|
|
updated: 2026-04-16
|
|||
|
|
type: entity
|
|||
|
|
tags: [tool, agent]
|
|||
|
|
sources: [packages/backend/src/modules/netaclaw/tools/builtin/patch.ts, packages/backend/src/modules/netaclaw/tools/fuzzy_match.ts]
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# Patch Tool 模糊补丁工具
|
|||
|
|
|
|||
|
|
## 概述
|
|||
|
|
|
|||
|
|
文件局部查找替换工具，支持 9 级模糊匹配。比 `write_file` 更安全（只改局部）、更省 token（不需要传完整文件内容）。注册在 [[tool-catalog]] 的 `base` 工具集。
|
|||
|
|
|
|||
|
|
## Schema 定义（TypeBox）
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
const PatchParams = Type.Object({
|
|||
|
|
path: Type.String({ description: '文件绝对路径' }),
|
|||
|
|
old_string: Type.String({ description: '要查找的文本片段' }),
|
|||
|
|
new_string: Type.String({ description: '替换为的文本' }),
|
|||
|
|
replace_all: Type.Optional(Type.Boolean({ description: '替换所有匹配，默认 false' })),
|
|||
|
|
});
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 执行流程
|
|||
|
|
|
|||
|
|
1. 读取目标文件内容
|
|||
|
|
2. 调用 `fuzzyFindAll()` 进行模糊匹配
|
|||
|
|
3. 验证匹配结果（0个报错 / 多个且非 replace_all 报错 / 唯一通过）
|
|||
|
|
4. 从后往前替换（避免索引偏移）
|
|||
|
|
5. 写回文件
|
|||
|
|
|
|||
|
|
## 9 级模糊匹配引擎
|
|||
|
|
|
|||
|
|
**文件**: `tools/fuzzy_match.ts`（~304行）
|
|||
|
|
|
|||
|
|
| 级别 | 策略 | 说明 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| 1 | `exact` | 精确字符串匹配 |
|
|||
|
|
| 2 | `line_trimmed` | 每行 trim 后匹配 |
|
|||
|
|
| 3 | `whitespace_normalized` | 所有空白压缩为单空格 |
|
|||
|
|
| 4 | `indent_flexible` | 去除行首缩进 |
|
|||
|
|
| 5 | `escape_normalized` | 转义字符还原（`\n` → 换行） |
|
|||
|
|
| 6 | `trimmed_boundary` | 首尾行 trim |
|
|||
|
|
| 7 | `unicode_normalized` | Unicode 标点归一化（智能引号等） |
|
|||
|
|
| 8 | `block_anchor` | 首尾行锚定 + 中间相似度 |
|
|||
|
|
| 9 | `context_aware` | 逐行相似度滑动窗口 |
|
|||
|
|
|
|||
|
|
**核心算法**: Levenshtein 编辑距离 → `similarity = 1 - (distance / maxLen)`
|
|||
|
|
|
|||
|
|
**返回结构**:
|
|||
|
|
```typescript
|
|||
|
|
interface FuzzyMatchResult {
|
|||
|
|
strategy: string; // 匹配策略名
|
|||
|
|
startIndex: number; // 原始文本起始位置
|
|||
|
|
endIndex: number; // 原始文本结束位置
|
|||
|
|
matchedText: string; // 匹配的原始文本
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 关联页面
|
|||
|
|
|
|||
|
|
- [[tool-catalog]] — 工具目录系统（注册在 base 工具集）
|
|||
|
|
- [[tool-system]] — 工具系统总览
|
|||
|
|
- [[agent-runtime]] — Agent 运行时执行
|