# textkit.patch 库模块帮助文档
预览与原子性
## 调用要点
- Same-original：全部 SEARCH 匹配修改前原文，后块不能搜索前块的输出。
- Unique + atomic：SEARCH 非空、唯一、不重叠；零处、多处、格式错误均整单拒绝。
- Copy old / format new：SEARCH 复制当前原文；不 trim、dedent、手工重建缩进，也不以省略号代替内容。
- Literal-only：区分大小写、SPACE/TAB；只有 CRLF/LF/CR 等价。替换文本不解释模式或捕获引用。
- Minimal write：只回写最小变更区间，不统一整份文件换行。新片段可先显式用 textkit.indent/dedent 调整；库不推测代码缩进。
- 插入：SEARCH 保留锚点，REPLACE 包含锚点及新增内容；删除：REPLACE 为空。
- 内容本身有补丁标记行时用 textkit.editor.process 的 replace；不要发明转义规则。
- 失败按 info.code / hint 重读并修正；diagnostics.approximate 是定位线索，绝不是模糊写入授权。
## 有界返回
previewMaxBytes 默认 1024，0 禁止文本回显，最大 4096。预算是预览/诊断文本的合计 UTF-8 字节数，不含固定有界的 JSON 字段名、行号等元数据。最多 4 个 hunk、6 个定位；远距离改动之间的全文不会回传。
preview.textBytes 为实际展示文本字节数；omittedChanges / omittedBytes / truncated 仅描述展示省略，不表示少改了文件。diagnostics.approximate 只表示建议检查的候选位置，绝不参与写入。
此库只处理字符串；文件工具另行处理 BOM、备份、语法检查和暂存提交。
[精确补丁](https://www.aardio.com/zh-cn/docs/library/textkit/patch/) [textkit 主库](https://www.aardio.com/zh-cn/docs/library/textkit/)
## textkit.patch 成员列表 #
精确补丁引擎，供文件编辑工具使用：literal-only / unique / atomic / same-original。
Copy old, format new：SEARCH 原样复制，不重排空白；仅EOL差异可忽略。内容含标记行→editor。只处理字符串，不读写文件。
### textkit.patch.apply(text,patchText,options) #
→newText,null,info；失败→null,err,info，无部分结果。
所有块匹配同一原文：非空SEARCH恰好一处、不重叠；SPACE/TAB及大小写严格，仅CRLF/LF/CR等价。新文本适配局部EOL，未动部分保留原字节；不自动缩进。
info.count=命中数，changedCount=真实变更数；失败读code/hint，候选诊断不参与写入。
previewMaxBytes 默认1024，0..4096，0关闭文本回显；最多6定位/4预览，预算仅限回显，不限制实际编辑。缺标记或歧义→重新读取，禁止模糊重试。
### textkit.patch.parse(patchText) #
→blocks 或 null,err,info；独占行标记 <<<<<<< SEARCH / ======= / >>>>>>> REPLACE。
SEARCH 非空，REPLACE 空=删除；可去除一层外围Markdown围栏，不容忍残缺块。
### textkit.patch.version #
实现版本