textkit.utf16：UTF-16LE 文件编辑

textkit.utf16 操作文件，不操作传入的内存文本。适用于已确认使用 UTF-16LE（codepage=1200）的 Windows 工具 Unicode 日志、文本输出和配置文件。Windows 中“Unicode”并不总是指 UTF-16LE；请先确认来源，不要仅凭文件名或扩展名推断编码。

磁盘： 固定 UTF-16LE；支持带 FF FE BOM 或无 BOM。
内存： 参数、读取结果、补丁、预览与诊断都是 UTF-8。
接口： 与 textkit.ansi 相同，只有 read/patch/edit/save(args) 四个文件入口；每次必须指定 path。
隔离： 不改变 Autos 的 UTF-8 工具、textkit.ansi 或 textkit.patch/editor。在 Autos 中按需通过 execute_code 调用，并 return 结果表。
内存文本直接使用 textkit、textkit.patch、textkit.editor，无需本库。

编码与 BOM 规则

新建文件默认写入 UTF-16LE BOM（FF FE），便于 Windows 工具识别。新建空文本只有 2 字节 BOM。
读取不把文件开头的 BOM 作为正文，不影响第一行匹配和行号。
编辑或覆盖已有文件，保留原来的有/无 BOM 状态；零字节原文件按无 BOM 空文本处理，不擅自增加 BOM。
bom 是读取及成功写操作结果中的布尔字段，不是可设置参数。不提供 codepage、encoding、bom 或 compile 参数。
只支持 UTF-16LE，不猜测编码、不自动切换 UTF-16BE/UTF-32，也不修复乱码。带 FE FF BOM 的 UTF-16BE 文件明确拒绝。
拒绝奇数字节、不配对的代理码元及正文中的 U+0000，避免转换器用替换字符悄悄修复原文。正常 UTF-16 零字节不受影响；emoji、扩展汉字和合法的 U+FFFD 均可使用。
无 BOM 文件不能写入以 U+FEFF/U+FFFE 开头的正文，否则会与 BOM 混淆；这种修改会被拒绝，不会静默丢字或改变端序。有 BOM 文件允许正文以这些字符开头，读取只去掉最外层文件 BOM。

本库不是编码转换或二进制文件修复工具。覆盖前也会验证原文件，不能用 save 绕过错误编码保护。

四个文件入口

所有入口都接收单个参数表，成功和失败都返回结果表，首先检查 ok。

入口	用途	参数
`read`	有界 UTF-8 视图，供 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`

未知或不适用的编辑参数会被拒绝；不编译或执行文件。

读取 Unicode 日志

import textkit.utf16;
return textkit.utf16.read({
    path = "/logs/unicode.log";
    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 按返回的 UTF-8 字节数计算，包括行号和展示换行；不会切开 UTF-8 字符，maxBytes=0 可仅取元数据。
originalBytes 是含 BOM 的磁盘字节数，textBytes 是实际返回的展示文本字节数，bom 表示原文件有无 BOM。
CRLF、LF、CR 都按换行计数；空文本有第 1 行，末尾换行后还有一个空逻辑行，与 editor.replaceLines 一致。起始行超范围返回 line_out_of_range。

分页只限制输出，内部仍完整读取和解码文件。 本库不是流式大日志读取器或 tail 工具。持续追加的日志可能读到半个码元或半个代理对，此时返回 invalid_text，不会自动补字节或忽略尾部。

精确补丁

import textkit.utf16;
var patches = "<<<<<<< SEARCH
[信息] 开始处理
=======
[信息] 开始构建
>>>>>>> REPLACE";

return textkit.utf16.patch({
    path = "/logs/unicode.log";
    patches = patches;
    dryRun = true
});

确认预览后去掉 dryRun 或设为 false 再提交。补丁中的中文等内容是普通 UTF-8，不要手工转成 UTF-16，也不要包含文件 BOM。

语义与 patch_text_file 一致：

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

结构化编辑

import textkit.utf16;
return textkit.utf16.edit({
    path = "/logs/unicode.log";
    operation = "replace";
    oldText = "旧提示";
    newText = "新提示";
    expectedCount = 2;
    dryRun = true
});

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.utf16;
return textkit.utf16.save({
    path = "/logs/unicode.log";
    content = '[信息] 开始处理\r\n[信息] 处理完成 😀\r\n'
});

content 为 UTF-8 字符串，落盘才转 UTF-16LE。新文件带 BOM，已有文件保留 BOM 状态；空字符串表示空文本。既不追加，也不统一换行、不自动创建父目录。控制字符在 aardio 中用单引号，例如 '\r\n'。

已有文件的局部修改优先 patch/edit；read 展示结果不能当作 save 的完整内容来源。

返回结果与文件保护

写接口常见字段：

ok：操作是否成功；失败查看 code/error/hint。
written：是否实际提交；dryRun 或无变化时为 false。
changed：拟写入字节与原文件是否不同；新建空文本也为 true。
dryRun：是否仅验证和预览。
bom：拟写入文件是否带 BOM；无变化时为原状态。
originalBytes/resultBytes：含 BOM 的磁盘 UTF-16LE 字节数，不是内存 UTF-8 大小。
backupPath：实际保留的原始字节备份。
count/changedCount/locations/preview：patch/edit 引擎返回的匹配数、文本改动数、位置和预览。

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

文件提交规则沿用 textkit.ansi：

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

备份恢复使用 io.copy(backupPath,targetPath) 原样复制。不要让 Autos 的 UTF-8 文本编辑或回滚工具处理 UTF-16 文件及其备份。 恢复前应确认目标没有需要保留的新修改。

编辑日志时建议先停止日志写入，或创建稳定副本；本库不会锁住日志生产进程，也不会把它改成日志清理服务。

Markdown 格式