aura-basetools 0.19.0 → 0.21.0

package/README.md

@@ -1,4 +1,4 @@
-# aura-basetools 0.19.0
+# aura-basetools 0.21.0
 
 Byte-exact file tools for coding agents: read by intent, edit by address, and write whole files without corrupting bytes. One engine shared by a standalone CLI and an MCP server.
 
@@ -21,7 +21,7 @@ The engine is intentionally not a general file manager: it reads and edits UTF-8
 ### Install
 
 ```bash
-npm i -g aura-basetools@0.19.0
+npm i -g aura-basetools@0.21.0
 aura --version
 ```
 
@@ -91,6 +91,7 @@ Compared with the DSH built-in `dsh-tool-fs` tools, the differences are delibera
 - **Edits refuse stale bases.** A region-level gate rejects an edit when the addressed region changed after the read that authorized it, and points at the lines to re-read; `expect` makes the intended text explicit.
 - **Writes are verified, not assumed.** Every write goes through a temp file, flush, rename, and a byte-for-byte read-back; multi-target edits plan first and write nothing if any target fails.
 - **Changes can prove themselves.** `edit` / `write` accept an explicit `verify` command; a non-zero exit or timeout rolls the transaction back and returns the command output plus the rollback state. No auto-discovery of repo scripts.
+- **MCP clients get a server-side nudge.** `initialize.instructions` asks the client to prefer `aura_basetools_*` and to use `aura_basetools_tx` for multi-call changes; whether it is honored is the client's choice.
 - **Changes can span calls, and concurrent changes merge.** `tx begin` opens a transaction; `edit` / `write` with `--tx <id>` append to it; `tx commit` three-way-merges non-overlapping external edits, refuses overlapping ones (`TX_CONFLICT`) without writing, and can run `verify`; `tx rollback` restores all of them. MCP exposes the same lifecycle as `aura_basetools_tx` plus the `transaction` field on edit/write.
 - **Addressing is structural.** `target` / `lines` / `old` / `expect` / handles replace "copy the literal text exactly"; failure receipts include ready-to-use retry addresses.
 - **The core is DSH-free.** `aura-basetools` has no runtime dependencies and no DSH imports; the DSH adapter is a separate optional package.
@@ -136,7 +137,7 @@ MIT.
 ### 安装
 
 ```bash
-npm i -g aura-basetools@0.19.0
+npm i -g aura-basetools@0.21.0
 aura --version
 ```
 

package/bin/aura-mcp.mjs

@@ -21,6 +21,20 @@
  */
 import { readFileSync, realpathSync } from 'node:fs'
 import process from 'node:process'
+
+/**
+ * MCP `initialize.instructions`: the only standard server-side nudge many MCP clients will
+ * prepend to their prompt. Keep it imperative and factual; it must not promise client behavior
+ * the client does not implement.
+ */
+const SERVER_INSTRUCTIONS = [
+  'Prefer the aura_basetools_* tools over built-in Read/Edit/Write for file work when they are available.',
+  'Read with aura_basetools_read; edit with aura_basetools_edit; create or overwrite with aura_basetools_write.',
+  'Keep tool arguments small — long, deeply nested JSON is what the provider\'s stream parser fails on (MALFORMED_RESPONSE). For a single change pass the hunk FLAT at the top level (`old`+`replace`, or `start_line`+`end_line`+`replace`, or a `handle` from a previous read + `replace`); use `hunks: [...]` only for several changes. If you already hold a `handle`, do not repeat the old text in `old`.',
+  'For changes spanning multiple calls use aura_basetools_tx begin -> edit/write with transaction -> commit; rollback on failure.',
+  'These tools preserve BOM and per-line endings, gate only the addressed region for staleness, verify writes, and keep multi-target edits atomic.',
+  'If your client can enforce provider-side strict tool schemas (DeepSeek `/beta` + `strict: true` per function, OpenAI strict), enable it: strict decoding makes malformed tool-call JSON impossible instead of merely rarer. The schemas convert cleanly with `locator-lab/strict-schema.mjs` (toStrictSchema / strictToolList); `aura basetools doctor` prints the recipe.',
+].join(' ')
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import {
   openProvider,
@@ -34,12 +48,15 @@ import {
   commitTransactionEnvelope,
   rollbackTransactionEnvelope,
   statusTransactionEnvelope,
+  MODES,
   assertReadTargets,
   assertEditTargets,
   assertTargetShape,
   assertKnownArgs,
   MT_READ_ELEMENT_KEYS,
   MT_EDIT_ELEMENT_KEYS,
+  // 平铺形状的拼装规则与 DSH 壳 / CLI 共用这一份（`locator-lab/args.mjs` 的 `flatHunk`）。
+  flatHunk,
 } from '../lib/ops.mjs'
 
 // 版本从包自己的 package.json 读：写死过一次，结果 0.4.0 的服务对外还报 0.2.1。
@@ -77,12 +94,19 @@ const TARGETS_SCHEMA = {
     '一次调用、逐项回执、输出按输入序；一个目标失败不连坐其余（写侧例外：先全部规划，任一规划失败 ⇒ 一个字都不写）。',
 }
 
+/**
+ * 为什么 `lines` 用 `anyOf` 而不是 `oneOf`：
+ *   四个分支按 `type` 互斥，语义完全等价；但 `oneOf` 在部分 provider 的严格模式里不受支持
+ *   （DeepSeek strict / OpenAI strict 只认 `anyOf`），而 MCP 这一面是**多 agent 共用**的。
+ *   DSH 适配器保留 `oneOf` —— 它的参数校验器认这个、静默忽略 `anyOf`（见 `aura-edit/index.js`）。
+ */
+
 const HUNK_SCHEMA = {
   type: 'object',
   properties: {
     target: { type: 'string', description: '符号名，如 `toTodoList` 或 `function:apply`；跳过全部文本匹配' },
     lines: {
-      oneOf: [
+      anyOf: [
         { type: 'array' },
         { type: 'string' },
         { type: 'integer' },
@@ -97,7 +121,7 @@ const HUNK_SCHEMA = {
     old: {
       type: 'string',
       description:
-        '内容地址：你正在替换的**逐字原文**（+ 可选 context 消歧）。给了它，坐标/符号名降为提示；引擎按内容定位，不唯一时拒绝并给候选。',
+        '内容地址：你正在替换的**逐字原文**（+ 可选 context 消歧）。给了它，坐标/符号名降为提示；引擎按内容定位，不唯一时拒绝并给候选。手里已有上次回执的 `handle` 时优先用 handle + replace —— 不必把旧文本再抄一遍，参数更短。',
     },
     context: { type: 'string', description: '与 old 同用：紧邻被替换区域的原文，只在 old 多处命中时用来消歧。' },
     /**
@@ -149,19 +173,19 @@ const TOOLS = [
   {
     name: 'aura_basetools_read',
     description:
-      'Read a file the way you actually need it. Modes: map (symbol directory), digest (interface only), full, around, lines, search, changed. `auto` picks one for you. Prefer this over reading the whole file.',
+      'Read a file the way you actually need it. Modes: probe (metadata only: lines, bytes, line endings, encoding, language, structure size — no content), map (symbol/section directory), digest (interface only), full (up to the content budget, not necessarily the whole file), around, lines, search, changed. `auto` picks one for you. Prefer this over reading the whole file.',
     inputSchema: {
       type: 'object',
       properties: {
         file_path: { type: 'string', description: '要读的文件路径（绝对或相对 cwd）' },
         mode: {
           type: 'string',
-          enum: ['map', 'digest', 'full', 'around', 'lines', 'search', 'changed'],
+      enum: ['auto', ...MODES],
           description: '省略时按你给的参数自动判断：行区间→lines、around→around、search→search、since→changed',
         },
         around: { type: 'string', description: 'mode=around：以该符号或短语为中心开窗' },
         lines: {
-          oneOf: [
+          anyOf: [
             { type: 'array' },
             { type: 'string' },
             { type: 'integer' },
@@ -175,6 +199,7 @@ const TOOLS = [
         context: { type: 'integer', description: 'mode=around：上下各留几行（默认 8）' },
         kind: { type: 'string', description: 'mode=map：只保留某一类符号（function / class / …）' },
         budget: { type: 'integer', description: '宿主剪枝阈值（字符）；省略用默认 8192' },
+        encoding: { type: 'string', description: '源编码覆盖（默认自动探测）：gb18030 / shift_jis / euc-kr / big5 / utf-16le / utf-16be / windows-1252。只对本次调用生效；显式指定过一次后会被记住（文件未被外部改动时）。' },
         since: { type: 'string', description: 'mode=changed：上次回执里的 version 令牌' },
         max_chars: { type: 'integer' },
         offset: { type: 'integer', description: '与 limit 同用：0-based 行偏移（内置 Read 的分页形状）；与 lines 互斥' },
@@ -193,12 +218,16 @@ const TOOLS = [
   {
     name: 'aura_basetools_edit',
     description:
-      'Edit or create a UTF-8 text file with hunks in one call. Address each hunk by target (symbol), lines, line_cue, anchor, or old (verbatim content + optional context). With `old`, set `replace_all: true` to replace every non-overlapping occurrence. Writes back byte-for-byte (BOM and per-line endings preserved), refuses a hunk whose addressed region changed since your last read, and reads the file back to verify. All hunks must locate or nothing is written.',
+      'Edit or create a text file in one call. PREFER THE FLAT FORM for a single change: put the hunk fields at the top level (`old`+`replace`, or `start_line`/`end_line`+`replace`, or `handle` from a previous read + `replace`) and omit `hunks` entirely — one JSON object instead of an array of objects, which is smaller and survives the provider\'s stream parser more reliably. Use `hunks: [...]` only when a call changes several places. Address each hunk by target (symbol), lines, line_cue, anchor, handle, or old (verbatim content + optional context). With `old`, set `replace_all: true` to replace every non-overlapping occurrence. Writes back byte-for-byte (BOM and per-line endings preserved), refuses a hunk whose addressed region changed since your last read, and reads the file back to verify. All hunks must locate or nothing is written. A single hunk may also be passed flat at the top level (`file_path` + the hunk fields) instead of wrapped in `hunks: [...]`. JSON/JSONC edits: prefer `lines`/`start_line`+`end_line` and put only the new text in `replace` — re-typing the old text doubles the escaped quotes/newlines the call must carry.',
     inputSchema: {
       type: 'object',
       properties: {
         file_path: { type: 'string' },
-        hunks: { type: 'array', items: HUNK_SCHEMA },
+        hunks: {
+          type: 'array',
+          items: HUNK_SCHEMA,
+          description: '多次修改时用；**单处修改请用平铺形式**（把 hunk 字段直接放顶层、不传 hunks）：一个对象比“对象数组”少一层嵌套，参数更短、更不容易在流式解码时坏掉。',
+        },
         dry_run: { type: 'boolean', description: '只定位不落盘' },
         require_observation: {
           type: 'boolean',
@@ -208,9 +237,18 @@ const TOOLS = [
           type: 'string',
           description: '写后验证命令（显式给出才执行；在 workspace 根下、受超时/输出上限约束）。非零退出 ⇒ 自动回滚并返回 PATCH_VERIFY_FAILED。不自动发现/执行仓库脚本。',
         },
-        transaction: { type: 'string', description: '跨调用事务 id（tx begin 返回）；本次修改追加到该事务，不立即 commit' },
+        transaction: { type: 'string', description: '跨调用事务 id（tx begin 返回）；本次修改追加到该事务的回滚日志。**写入立即可见**（tx 不是隔离事务，pending 期间盘上已是新字节），commit 只做 afterVersion 校验与可选 verify' },
         create: { type: 'string', description: '文件不存在时用它创建（整份内容）' },
+        encoding: { type: 'string', description: '源编码覆盖（默认自动探测）；猜不准时写会拒绝，用它显式指定。只对本次调用生效。' },
         targets: TARGETS_SCHEMA,
+        /**
+         * 平铺形状：单个 hunk 的键**也**声明在顶层（与 DSH 壳、CLI 同一份容错）。
+         *
+         * 此前只有 DSH 壳声明了这些键：同一份载荷 `{file_path, start_line, end_line, replace}`
+         * 在 DSH 面被执行、在 MCP 面被未知参数守卫拒掉——而 MCP 正是 Codex/Claude Code/Cursor/ZCode
+         * 共用的那一面。声明与实装现在同源（拼装仍走 `flatHunk`，不另写一份判据）。
+         */
+        ...HUNK_SCHEMA.properties,
       },
       /**
        * `hunks` **不在 required 里**：`create` 就是在建一个新文件，那时没有 hunk 可给。
@@ -235,6 +273,7 @@ const TOOLS = [
       properties: {
         file_path: { type: 'string', description: '要写的文件路径（绝对或相对 cwd）；不存在则创建' },
         content: { type: 'string', description: '整份内容；覆盖已有文件时替换全部行' },
+        encoding: { type: 'string', description: '源编码覆盖（默认自动探测）；写回沿用该编码。只对本次调用生效。' },
         dry_run: { type: 'boolean', description: '只规划不落盘：新建报 create，覆盖校验换行与字节数' },
         no_overwrite: { type: 'boolean', description: '文件已存在时拒绝（WRITE_EXISTS）' },
         allow_unobserved: {
@@ -248,9 +287,9 @@ const TOOLS = [
         },
         verify: {
           type: 'string',
-          description: '写后验证命令（显式给出才执行；非零退出 ⇒ 自动回滚并返回 PATCH_VERIFY_FAILED）。',
+          description: '写后验证命令（显式给出才执行；在**工作区根目录**执行；无超时参数——MCP 传输上限约 30s，慢命令不要放进来；非零退出 ⇒ 自动回滚并返回 PATCH_VERIFY_FAILED）。',
         },
-        transaction: { type: 'string', description: '跨调用事务 id（tx begin 返回）；本次修改追加到该事务，不立即 commit' },
+        transaction: { type: 'string', description: '跨调用事务 id（tx begin 返回）；本次修改追加到该事务的回滚日志。**写入立即可见**（tx 不是隔离事务），commit 只做 afterVersion 校验与可选 verify' },
       },
       required: ['file_path', 'content'],
     },
@@ -258,13 +297,13 @@ const TOOLS = [
   {
     name: 'aura_basetools_tx',
     description:
-      'Begin, commit, rollback, or inspect a cross-call transaction. Begin returns an id; pass it to edit/write `transaction` to append changes; commit checks each written file was not changed externally and can run `verify`; rollback restores all files.',
+      'Begin, commit, rollback, or inspect a cross-call transaction. Begin returns an id; pass it to edit/write `transaction` to append changes. Writes are visible immediately: a transaction is a cross-file ROLLBACK JOURNAL, not isolation — while it is pending the file on disk already holds the new bytes. `commit` checks each written file was not changed externally and can run `verify`; `rollback` restores all files.',
     inputSchema: {
       type: 'object',
       properties: {
         action: { type: 'string', enum: ['begin', 'commit', 'rollback', 'status'] },
         transaction: { type: 'string', description: 'tx begin 返回的事务 id（begin 时不需要）' },
-        verify: { type: 'string', description: 'commit 时的写后验证命令；失败 ⇒ 整个事务回滚' },
+        verify: { type: 'string', description: 'commit 时的写后验证命令（在**工作区根目录**执行、无超时参数；MCP 传输上限约 30s）；失败 ⇒ 整个事务回滚' },
       },
       required: ['action'],
     },
@@ -404,6 +443,11 @@ async function callTool(provider, name, args = {}) {
       }
     }
   }
+  /**
+   * 逐调用编码覆盖（0.21）：长驻进程里 provider 是同一个，环境变量没法按调用改。
+   * 不传时复位到环境变量——不能把上一次调用的 hint 泄漏给下一次。
+   */
+  if (typeof provider.setEncodingHint === 'function') provider.setEncodingHint(args.encoding)
   if (name === 'aura_basetools_tx') {
     const action = args.action
     if (action === 'begin') return beginTransactionEnvelope(provider)
@@ -433,7 +477,10 @@ async function callTool(provider, name, args = {}) {
      * 多目标形状不走这一条：每个 target 自带 hunks/create（契约 §2.2）。
      */
     const creating = typeof args.create === 'string'
-    if (!Array.isArray(args.hunks) && !creating) {
+    // 平铺形状（单 hunk 直接写在顶层）：拼装规则只认 `flatHunk` 那一份，不在 bin 里另写。
+    const flat = Array.isArray(args.hunks) ? null : flatHunk(args)
+    const hunks = Array.isArray(args.hunks) ? args.hunks : flat === null ? [] : [flat]
+    if (hunks.length === 0 && !creating) {
       return {
         ok: false,
         error: 'aura_basetools_edit 需要 hunks 数组，或 create（整份内容建文件）二选一；只建文件时直接给 create 即可',
@@ -442,7 +489,7 @@ async function callTool(provider, name, args = {}) {
     }
     return await editEnvelope(provider, {
       file: args.file_path,
-      hunks: Array.isArray(args.hunks) ? args.hunks : [],
+      hunks,
       dryRun: args.dry_run === true,
       create: creating ? args.create : undefined,
       ...(args.require_observation === true ? { requireObservation: true } : {}),
@@ -504,6 +551,7 @@ export async function serve() {
           supportedProtocolVersions: SUPPORTED_PROTOCOLS,
           capabilities: { tools: { listChanged: false } },
           serverInfo: { name: 'aura-basetools', version: VERSION },
+          instructions: SERVER_INSTRUCTIONS,
         })
       }
       if (method === 'ping') return reply(id, {})

package/bin/aura.mjs

@@ -87,15 +87,15 @@ const isBooleanFlag = (token) => typeof token === 'string' && BOOLEAN_FLAGS.has(
  */
 const COMMAND_FLAGS = {
   read: {
-    value: ['cwd', 'file', 'targets', 'mode', 'around', 'lines', 'start-line', 'end-line', 'search', 'since', 'context', 'kind', 'budget', 'max-chars', 'offset', 'limit'],
+    value: ['cwd', 'file', 'targets', 'mode', 'around', 'lines', 'start-line', 'end-line', 'search', 'since', 'context', 'kind', 'budget', 'max-chars', 'offset', 'limit', 'encoding'],
     bool: ['pretty'],
   },
   edit: {
-    value: ['cwd', 'file', 'targets', 'hunks', 'hunks-file', 'create', 'target', 'lines', 'start-line', 'end-line', 'line-cue', 'anchor', 'old', 'context', 'handle', 'line', 'position', 'replace', 'expect', 'near', 'eol', 'verify', 'tx'],
+    value: ['cwd', 'file', 'targets', 'hunks', 'hunks-file', 'create', 'target', 'lines', 'start-line', 'end-line', 'line-cue', 'anchor', 'old', 'context', 'handle', 'line', 'position', 'replace', 'expect', 'near', 'eol', 'verify', 'tx', 'encoding'],
     bool: ['pretty', 'dry-run', 'plan', 'replace-all', 'require-observation'],
   },
   write: {
-    value: ['cwd', 'file', 'content', 'eol', 'verify', 'tx'],
+    value: ['cwd', 'file', 'content', 'eol', 'verify', 'tx', 'encoding'],
     bool: ['pretty', 'dry-run', 'plan', 'no-overwrite', 'allow-unobserved'],
   },
   tx: { value: ['cwd', 'id', 'verify'], bool: ['pretty', 'json'] },
@@ -339,7 +339,8 @@ if (command === 'mcp') {
   process.exit(0)
 }
 
-const provider = openProvider(typeof flag('cwd') === 'string' ? flag('cwd') : process.cwd())
+const encodingFlag = typeof flag('encoding') === 'string' && flag('encoding').length > 0 ? flag('encoding') : undefined
+const provider = openProvider(typeof flag('cwd') === 'string' ? flag('cwd') : process.cwd(), { encoding: encodingFlag })
 
 if (command === 'tx') {
   const action = argv[1]
@@ -441,11 +442,29 @@ if (command === 'doctor') {
   probeWritable(cacheDir, 'cache-writable')
   probeWritable(path.join(cacheDir, 'locks'), 'lock-writable')
   const ok = checks.every((check) => check.ok)
+  /**
+   * strict 提示（不是检查项）：让“能不能把参数解析失败归零”这件事在装完就能看到。
+   *
+   * 工具侧不能替宿主开 strict（那是 provider/客户端配置），但能说清楚“我们的 schema 转得过去”
+   * 与“怎么开”。转换器导出在 `locator-lab/strict-schema.mjs`（`toStrictSchema` / `strictToolList`），
+   * 已随包发布（package.json 的 `./locator-lab/*`）。
+   *
+   * 为什么放在 doctor 而不是新开一个命令：doctor 是“装完跑一下”的那条路径，
+   * 而 strict 能不能开决定了“参数解析失败”是否还会中断任务。
+   */
+  const strict = {
+    compatible: true,
+    convert: 'aura-basetools/locator-lab/strict-schema.mjs',
+    deepseek: 'base_url=https://api.deepseek.com/beta + "strict": true on every function (server validates the schema)',
+    openai: 'strict: true (all properties required + additionalProperties:false)',
+    note: 'strict 让模型不可能输出非法 JSON；不开时工具侧只能降低概率（P1 发生在工具被调用之前）',
+  }
   const report = {
     ok,
     version: VERSION,
     node: process.versions.node,
     checks,
+    strict,
     ...(process.env.AURA_NO_LOCK === '1' ? { notes: ['AURA_NO_LOCK=1: workspace lock is disabled'] } : {}),
   }
   if (has('json')) {
@@ -454,6 +473,10 @@ if (command === 'doctor') {
   }
   process.stdout.write(`aura basetools doctor: ${ok ? 'ok' : 'FAILED'} (${VERSION}, node ${process.versions.node})\n`)
   for (const check of checks) process.stdout.write(`  ${check.ok ? '✓' : '✗'} ${check.id}: ${check.detail}\n`)
+  process.stdout.write(`  • strict: schemas 可转成 provider strict 变体（全 required + nullable + anyOf）——\n`)
+  process.stdout.write(`    DeepSeek: ${strict.deepseek}\n`)
+  process.stdout.write(`    OpenAI:   ${strict.openai}\n`)
+  process.stdout.write(`    转换器: ${strict.convert}｜不开 strict 时“参数不是合法 JSON”仍会中断任务（工具看不到那段字节）\n`)
   process.exit(ok ? 0 : 2)
 }
 
@@ -493,6 +516,7 @@ if (command === 'read' || command === 'outline') {
     limit: typeof flag('limit') === 'string' ? Number(flag('limit')) : undefined,
     // 光写 `--max-chars` 不带值时 flag() 回 true，Number(true)=1 会变成"预算 1 字符"这种怪值
     maxChars: typeof flag('max-chars') === 'string' ? Number(flag('max-chars')) : undefined,
+    encoding: encodingFlag,
   })
   emit(env, env.ok ? 0 : 2)
 }

package/lib/encoding-memory.mjs

@@ -0,0 +1,87 @@
+/**
+ * encoding-memory.mjs —— 记住“这个文件是什么编码”，设一次就够。
+ *
+ * ## 为什么需要它
+ *
+ * 探测在中/低置信度时会**拒绝写**（`ENCODING_AMBIGUOUS`）——这是对的：写错编码等于写坏字节。
+ * 但用户每次都要 `AURA_ENCODING=gb18030` 才能改同一个文件，体验很差。
+ *
+ * 所以：**显式指定过一次，就记住**。下次同一文件（大小与 mtime 都没变）自动沿用，
+ * 不需要再设环境变量。
+ *
+ * ## 为什么不无条件信任记忆
+ *
+ * 文件被别的工具重写后，编码可能变了（甚至从 GBK 改成 UTF-8）。所以记忆条目带
+ * `{size, mtimeMs}` 指纹：**对不上就忽略**，回到探测。宁可再问一次，不可写错。
+ *
+ * 存放位置：`AURA_CACHE_DIR`（默认 `~/.aura`）下的 `encodings.json`；目录不可写时静默跳过
+ * ——记忆是加速器，不是正确性依赖。
+ */
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+const MAX_ENTRIES = 500
+
+function storePath() {
+  const dir = process.env.AURA_CACHE_DIR ?? path.join(os.homedir(), '.aura')
+  return path.join(dir, 'encodings.json')
+}
+
+function readAll() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(storePath(), 'utf8'))
+    return parsed !== null && typeof parsed === 'object' ? parsed : {}
+  } catch {
+    return {}
+  }
+}
+
+function writeAll(map) {
+  try {
+    const file = storePath()
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    const tmp = `${file}.${process.pid}.${Date.now().toString(36)}.tmp`
+    fs.writeFileSync(tmp, JSON.stringify(map))
+    fs.renameSync(tmp, file)
+  } catch {
+    /* 记忆是加速器，不是正确性依赖 */
+  }
+}
+
+/** 指纹：大小 + mtime；任一缺失就当作“不知道”，不冒险复用。 */
+function stampOf(stat) {
+  if (stat === undefined || stat === null) return null
+  const size = Number(stat.size)
+  const mtimeMs = Number(stat.mtimeMs)
+  if (!Number.isFinite(size) || !Number.isFinite(mtimeMs)) return null
+  return { size, mtimeMs: Math.trunc(mtimeMs) }
+}
+
+/** 记住一个文件的编码（UTF-8 不记：它是默认值，记住只会让表变脏）。 */
+export function rememberEncoding(displayPath, encoding, stat) {
+  if (typeof displayPath !== 'string' || typeof encoding !== 'string') return
+  if (encoding === 'utf-8') return
+  const stamp = stampOf(stat)
+  if (stamp === null) return
+  const all = readAll()
+  all[path.resolve(displayPath)] = { encoding, ...stamp }
+  // 简单的 LRU：超上限时按 mtime 丢掉最旧的一半。
+  const keys = Object.keys(all)
+  if (keys.length > MAX_ENTRIES) {
+    keys.sort((a, b) => (all[a].mtimeMs ?? 0) - (all[b].mtimeMs ?? 0))
+    for (const key of keys.slice(0, keys.length - MAX_ENTRIES)) delete all[key]
+  }
+  writeAll(all)
+}
+
+/** 取回记忆的编码；指纹对不上返回 undefined。 */
+export function recallEncoding(displayPath, stat) {
+  if (typeof displayPath !== 'string') return undefined
+  const entry = readAll()[path.resolve(displayPath)]
+  if (entry === undefined || typeof entry.encoding !== 'string') return undefined
+  const stamp = stampOf(stat)
+  if (stamp === null) return undefined
+  if (entry.size !== stamp.size || entry.mtimeMs !== stamp.mtimeMs) return undefined
+  return entry.encoding
+}