textkit.ansi：默认 ANSI 文件编辑

textkit.ansi 操作的是文件，不是内存文本。适用于已确认使用系统默认 ANSI 的 .bat、.cmd、VB6 .bas / .cls / .frm 等遗留文本文件，主要供 aardio Autos 按需调用。

磁盘：固定按 codepage=0 读写。
内存：调用参数、读取结果、补丁及诊断都是 UTF-8。
已经在内存中的文本：直接使用 textkit、textkit.patch、textkit.editor，无需本库。
不检测编码、不选择 GBK/BIG5、不修复乱码、不做不可表示字符审计。转换遵循默认 ANSI 规则。
不修改或扩展 Autos 的 UTF-8 工具；遇到 ANSI 文件时，通过 execute_code 调用本库并 return 结果表。

四个文件入口

所有入口只接受一个参数表，且必须包含 path；成功和失败都返回结果表，首先检查 ok。

入口	用途	参数
`read`	有界读取，给 AI 查看、定位	`path, startLine, lineCount, maxBytes, lineNumbers`
`patch`	精确 SEARCH/REPLACE 补丁	`path, patches, backup, dryRun, previewMaxBytes`
`edit`	行、锚点、区间及明确批量替换	`path` 加现有 `edit_text_file` 的编辑字段；不接受 `compile`
`save`	新建或明确全文覆盖	`path, content, backup, dryRun`

未知参数会被拒绝，不接受 codepage、encoding、compile。不自动运行 .bat 或编译 VB6 源码。

读取文件

import textkit.ansi;
return textkit.ansi.read({
    path = "/legacy/build.bat";
    startLine = 1;
    lineCount = 80
});

默认 startLine=1、lineCount=120、maxBytes=20000、lineNumbers=true。

data 是带行号的 UTF-8 展示文本；复制 SEARCH/旧片段时去掉行号。
lineNumbers=false 去掉行号。仍是展示视图，不是原文件的无损全文读取：展示行之间用 LF 连接，且可能截断，不能直接拿来 save 覆盖文件。
startLine/endLine 是实际展示的行区间；没有展示行时 endLine=startLine-1。
truncated 表示后面还有未展示内容，或展示行被裁剪；clipped 专指字节预算裁剪。
maxBytes=0 可仅获取元数据。字节预算包括行号和展示换行，截断不会切开 UTF-8 字符。
行号与 editor.replaceLines 一致：CRLF、LF、CR 都是换行；空文件有第 1 行，末尾换行后还有一个空逻辑行。
读取超范围起始行会返回 line_out_of_range。本库不是流式大文件编辑器：分页只限制输出，内部仍读取完整文件。

精确补丁

import textkit.ansi;
var patches = "<<<<<<< SEARCH
echo 编译开始
=======
echo 开始构建
>>>>>>> REPLACE";

return textkit.ansi.patch({
    path = "/legacy/build.bat";
    patches = patches;
    dryRun = true
});

确认预览后，移除 dryRun 或设为 false 再提交。

与 patch_text_file 相同：

只传独占行的 <<<<<<< SEARCH / ======= / >>>>>>> REPLACE 块，不传路径行。
所有块匹配同一份修改前原文，后块不能搜索前块输出。
SEARCH 非空、恰好匹配一处；区间不能重叠；任一块失败整单不写入。
字面、区分大小写和空白，仅 CRLF/LF/CR 差异等价；不 trim/dedent 旧片段、不做模糊回退。
插入时保留锚点并增加内容；删除时 REPLACE 留空。
内容含补丁标记行时改用 edit，不发明转义规则。

结构化编辑

import textkit.ansi;
return textkit.ansi.edit({
    path = "/legacy/Module1.bas";
    operation = "replace";
    oldText = "旧提示";
    newText = "新提示";
    expectedCount = 2
});

与 edit_text_file 对齐的操作字段：

operation	定位字段	写入字段
`replace`	`oldText`	`newText`
`insertBefore` / `insertAfter`	`anchor`	`newText`
`replaceBetween`	`beginAnchor, endAnchor`	`newText`
`deleteBetween`	`beginAnchor, endAnchor`	不传 `newText`
`replaceLines`	`startLine`，可选 `endLine, expectedOldText`	`newText`

默认唯一；expectedCount=N 是准确次数断言，不是替换上限或第 N 个。replaceAll=true 替换全部非重叠命中，仍可用 expectedCount 加断言。零命中始终失败。
newText 必须显式指定；空字符串表示删除。插入不会自动添加换行。
区间默认保留锚点，includeAnchors=true 才一起替换。anchor 可代替 beginAnchor，不要传冲突的两者。嵌套或缺少结束锚点会拒绝。
replaceLines 使用从 1 开始的闭区间整行，空字符串删除整行。新文本缺末尾 EOL 时保留原区间末尾 EOL；expectedOldText 可以带或不带该 EOL。
preserveEol 默认 true：仅换行形式等价，新内容适配局部 EOL；设为 false 禁用等价与适配，但不取消整行替换的 EOL 衔接规则。
只传当前操作需要的字段，不填充无关参数。

新建或全文覆盖

import textkit.ansi;
return textkit.ansi.save({
    path = "/legacy/build.bat";
    content = '@echo off\r\necho 开始编译\r\nexit /b 0\r\n'
});

save 不追加、不自动建父目录、不添加 BOM、不改变换行。创建批处理文件时建议显式用 \r\n（aardio 中控制字符写在单引号内）。空字符串表示创建空文件或清空已有文件。

已有源码的局部修改优先用 patch/edit，不要用全文覆盖代替精确编辑。

返回结果与安全边界

写接口常见字段：

ok：操作是否成功；失败查看 code/error/hint。
written：是否已经提交文件；dryRun 或无变化时为 false。
changed：拟写入的 ANSI 字节与原文件是否不同；新建空文件也为 true。
dryRun：是否仅验证和预览。
originalBytes/resultBytes：实际磁盘 ANSI 字节数，不是 UTF-8 内存大小。
backupPath：实际保留的原始字节备份路径。
count/changedCount/locations/preview：patch/edit 引擎返回的匹配数、文本改动数、位置和预览。预览是转码落盘之前的 UTF-8 文本；不保证无法用默认 ANSI 表示的字符落盘后原样保留。

patch/edit 的 previewMaxBytes 默认 1024，范围 0～4096，0 禁止文本回显。预算按 UTF-8 计，只限制预览及诊断，不限制实际编辑数量。诊断候选仅供定位，不能用于模糊写入。

文件提交规则：

backup 默认 true；备份名称为 <path>.ansi.bak.<时间戳>.<随机后缀>，不会沿用 Autos 的 .aa.bak.* 名称。
dryRun 不产生备份或暂存文件；无字节变化不写入。patch/edit 无文本变化时直接保留原始字节，不重复转码回写。
同目录独占创建暂存文件，写入、刷新并校验后再提交；不先截断原文件。
提交前复查原文件，变化则取消。这不是跨进程锁，复查与替换之间仍有很短的竞争窗口；不承诺多文件事务或断电持久性。
已有文件用 ReplaceFileW 替换，新文件用不覆盖现有目标的移动提交。backup=false 在提交期间仍保留恢复原件，成功后才删除；删不掉的备份仍通过 backupPath 返回。
特殊提交故障可能返回 recoveryRequired、backupPath、stagedPath。此时停止继续编辑，先检查和恢复，不要盲目重试。

备份是原始字节。可用 io.copy(backupPath, targetPath) 原样恢复，不要让 UTF-8 文本编辑/回滚工具读取 ANSI 备份。恢复前自行确认目标是否已有新修改。

本库拒绝含 NUL 的文件和写入内容，不处理 VB6 .frx 等二进制资源。对于有效默认 ANSI 文本，编辑保留未修改部分的文本与换行；对于异常字节或特殊编码映射，不承诺整份转码后的逐字节可逆性。

Markdown 格式