# textkit.ansi 库模块帮助文档

<details>  <summary>只操作文件</summary>  <p>
## 定位

四个入口均接收包含 path 的参数表，仅操作文件，不提供内存文本 API。
文件固定按 codepage=0 读写；参数、返回数据和编辑引擎中的文本均为 UTF-8。
内存文本直接使用 textkit / textkit.patch / textkit.editor。本库不依赖或修改 Autos 工具。

## 边界

- 不检测或猜测编码，不选择 GBK/BIG5，不做乱码修复或不可表示字符审计；转换遵循默认 ANSI 规则。
- 不自动添加 BOM、不统一文件换行、不编译或运行脚本。含 NUL 的文件不支持，VB6 的 .frx 等二进制资源不支持。
- patch/edit 默认 backup=true；save 覆盖已有文件也默认备份。备份为原始字节，路径见 backupPath；请用 io.copy 原样恢复，不要交给 UTF-8 文本工具。
- dryRun 不创建暂存文件或备份；无字节变化不写入。父目录须已存在，save 不自动建目录。
- 同目录独占暂存、校验、提交前复查、ReplaceFileW 替换。复查不是跨进程锁，也不承诺跨文件事务或断电持久性。
- originalBytes/resultBytes 是磁盘 ANSI 字节数；预览、诊断及 read 的 maxBytes 按 UTF-8 计。
- 改动文本保留未编辑处的文本与换行，但不承诺异常字节经整份转码后逐字节不变。
</p></details>

[» ANSI 文件编辑](https://www.aardio.com/zh-cn/docs/library/textkit/ansi/index.html) [» 修复乱码](https://www.aardio.com/zh-cn/docs/examples/Text/IMultiLanguage2.html)

## textkit.ansi 成员列表 <a id="textkit.ansi" href="#textkit.ansi">&#x23;</a>

默认 ANSI 文件接口，专用于 AI 自动化中的 bat、VB6 等遗留文本文件。  
只操作文件，不处理传入的内存文本；内存文本仍使用 textkit。固定 codepage=0，不检测编码、不修复乱码、不编译执行；参数与返回文本均为 UTF-8。  
均返回结果表，先检查 ok；失败读 code/error/hint。patch/edit/save 默认原始字节备份，dryRun 无写入；无需修改 Autos 的 UTF-8 工具。

### textkit.ansi.edit(args) <a id="textkit.ansi.edit" href="#textkit.ansi.edit">&#x23;</a>
对 ANSI 文件执行结构化字面编辑，字段与 edit_text_file 对齐但没有 compile。  
公共字段 path/operation/backup=true/dryRun=false/previewMaxBytes=1024。replace: oldText,newText；insertBefore/insertAfter: anchor,newText；replaceLines: startLine,endLine?,expectedOldText?,newText；replaceBetween: beginAnchor,endAnchor,newText；deleteBetween: beginAnchor,endAnchor。  
默认唯一；expectedCount=N要求恰好N处，不是上限；replaceAll=true全部非重叠命中，0命中仍失败。newText必须显式传入，空串删除，deleteBetween不传newText。  
区间默认保留锚点，includeAnchors=true含锚点；嵌套/缺尾拒绝。replaceLines两端含，空串删整行；保留原末行EOL。插入不自动加换行。  
preserveEol默认true仅忽略换行差异，新内容适配局部EOL；false禁用换行等价。只传适用字段，不模糊重试。返回结果表同patch。

### textkit.ansi.patch(args) <a id="textkit.ansi.patch" href="#textkit.ansi.patch">&#x23;</a>
对 ANSI 文件应用 Aider SEARCH/REPLACE 补丁。  
{path;patches;backup=true;dryRun=false;previewMaxBytes=1024}，预览0..4096。全部块匹配同一份修改前原文，SEARCH非空、唯一、区间不重叠；任一失败整单不写。  
标记独占行 <<<<<<< SEARCH / ======= / >>>>>>> REPLACE；只传块，不传路径行。大小写/空白严格，仅CRLF/LF/CR等价；旧片段原样复制，不trim/dedent。标记冲突改用 edit。  
返回 ok/written/changed/path/backupPath/count/changedCount/preview 等；预览预算只限制回显，诊断候选不授权模糊修改。

### textkit.ansi.read(args) <a id="textkit.ansi.read" href="#textkit.ansi.read">&#x23;</a>
读取 ANSI 文件的有界 UTF-8 视图。  
{path;startLine=1;lineCount=120;maxBytes=20000;lineNumbers=true}。data 带行号，复制 SEARCH 时去掉行号；lineNumbers=false 仅去行号，展示换行仍为 LF，不是原文件全文备份。  
返回 ok/path/data/startLine/endLine/totalLines/truncated/clipped/textBytes/originalBytes；clipped 表示字节预算截断，0预算可仅取元数据。空文件1行，末尾换行后有空逻辑行，与 replaceLines 一致。

### textkit.ansi.save(args) <a id="textkit.ansi.save" href="#textkit.ansi.save">&#x23;</a>
新建或明确全文覆盖 ANSI 文件，不追加。  
{path;content;backup=true;dryRun=false}，父目录须已存在。content是UTF-8字符串，内部转为默认ANSI，不添加BOM、不改变换行；空串创建/清空文件。创建bat建议显式CRLF。  
已有文件默认保留原始字节备份，无字节变化不写入；已有源码局部修改优先patch/edit。返回ok/written/changed/path/originalBytes/resultBytes/backupPath。