@flotiarenor/dsh-tool-text-editor 1.1.2 → 1.3.0

package/lib/core.mjs

@@ -3,30 +3,19 @@
 /**
  * core.mjs —— 文本编辑核心。纯 Node，只用 `node:` 内置模块，不启动任何子进程。
  *
- * 它承担 dsh 原生 `write`/`edit` 在 Windows 上做不到的事：
- *   * **保留 UTF-8 BOM**（原生工具会丢）；
- *   * **行尾跟随文件**（原生 `write` 会把 CRLF 文件拍成 LF）；
- *   * unified diff **分两层**：模型只看到一行统计加受预算约束的 diff 正文（`brief` / `diff`），
- *     完整细节留在 `stdout`（人类与 UI 卡片用）。落盘前自动备份，记编辑台账；
- *   * 锚点可以从目标取（`grep` 正则 / `lines` 行号），不必手抄旧文本；
- *   * 匹配失败时给"最接近的候选"，歧义时拒绝写盘而不是猜。
+ * 它承担 dsh 原生 `write` / `edit` 做不到的事：
+ *   * **保留 UTF-8 BOM**（原生 `edit` / `write` 都会丢）；
+ *   * **行尾跟随文件**（原生不还原原文件风格：给 LF 写 LF，CRLF 文件就此变成 LF）；
+ *   * **宽松匹配**：精确 → 宽松 → 最接近候选，命中不确定时拒绝写盘而不是猜（原生只做精确匹配）；
+ *   * **锚点可以从目标取**（`grep` 正则 / `lines` 行号），不必手抄旧文本。
  *
- * 两条落盘保证：
- *   * **原子写**：同目录临时文件 + fsync + rename —— 中途被杀不会留下半个文件，也不会出现
- *     截断写造成的空文件；
- *   * **同目标串行**：进程内按目标路径排队，并行工具调用不会互相覆盖（跨进程不串行，
- *     那是另一件事，README 里写明了）。
+ * 两条落盘保证：**原子写**（同目录临时文件 + fsync + rename，中途被杀不会留下半个文件），
+ * **同目标串行**（进程内按目标路径排队；跨进程不串行，见 README）。
  *
- * 备份与台账的格式：`<工作区>/.dsh/backups/<扁平化绝对路径>@<时间戳>` 与
- * `<工作区>/.dsh/edits.log` 里的 JSONL 记录（字段见 `appendLedger`）。
- *
- * `diff` / `maxDiffLines` 的由来：工具结果按追加方式进入会话历史，不参与前缀缓存，因此单次调用
- * 回吐的字节随调用次数累积。"新建 / 整体重写" 的 unified diff 每一行都带 `+`，等同于整文件回显
- * ——实测回吐量与输入内容同量级（放大率 ≈ 1.0x）。故模型可见正文默认仅在改动较小时给出
- * （`auto`），其余情况只给统计行，由调用方决定是否另行读取文件；`none` 不给出正文，`full` 始终
- * 给出正文，但同样受行数上限约束。
+ * 模型可见文本只有 `brief`：一行统计（`replace@17 +1/-1`）加必要的警告，**既不回显改动内容，也不回显
+ * 路径**——工具结果按追加方式进入会话历史，回显会随调用次数累积，而调用方刚发过 `new_text` 与
+ * `file_path`。改动本身不落任何旁路记录：本包不写备份也不写台账。
  */
-
 import {
   closeSync,
   existsSync,
@@ -38,18 +27,13 @@ import {
   renameSync,
   statSync,
   unlinkSync,
-  writeFileSync,
   writeSync,
 } from 'node:fs'
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
 
 export const UTF8_BOM_BYTES = Buffer.from([0xef, 0xbb, 0xbf])
-export const GUARD_DIRS = ['.git', '.dsh']
+/** 生成 unified diff 时的默认上下文行数（只喂 `diffStat` 的 `+N/-M`）。 */
 export const DEFAULT_CONTEXT = 3
-/** 模型可见 diff 正文的默认行数预算：`auto` 超了就不给正文，`full` 也按它截断。 */
-export const DEFAULT_MAX_DIFF_LINES = 30
-/** `diff` 的取值：`auto` 小改动才给正文 / `full` 总给（仍封顶）/ `none` 只给统计行。 */
-export const DIFF_MODES = ['auto', 'full', 'none']
 /** LCS 动态规划的格子上限：超过就退化成"整块替换"，避免大文件吃光内存。 */
 const MAX_DIFF_CELLS = 4_000_000
 
@@ -67,9 +51,12 @@ export function toLf(text) {
 }
 
 /**
- * 只看字节，判断 BOM / 行尾风格 / 是否可编辑。
+ * 只看字节，判断 BOM / 行尾风格 / 能否按文本处理。
+ *
+ * 非法 UTF-8 不在这里判：它只在真正解码时才知道（`decodeText` 用 `fatal: true` 解），所以本函数不返回
+ * 一个永远为假的标志位。
  * @param bytes - 文件原始字节。
- * @returns { bom, eol, crlf, lf, mixed, binary, invalidUtf8 }
+ * @returns { bom, eol, crlf, lf, mixed, binary }
  */
 export function analyzeBytes(bytes) {
   const bom = bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf
@@ -87,7 +74,7 @@ export function analyzeBytes(bytes) {
   }
   // 判定规则：有 CRLF 且 CRLF >= 独立 LF ⇒ CRLF（跟随多数派，平局算 CRLF）
   const eol = crlf > 0 && crlf >= lf ? '\r\n' : '\n'
-  return { bom, eol, crlf, lf, mixed: crlf > 0 && lf > 0, binary, invalidUtf8: false }
+  return { bom, eol, crlf, lf, mixed: crlf > 0 && lf > 0, binary }
 }
 
 /**
@@ -100,14 +87,14 @@ export function analyzeBytes(bytes) {
 export function decodeText(bytes, label) {
   const info = analyzeBytes(bytes)
   if (info.binary) {
-    throw new UsageError(`${label}: 含 NUL 字节，看起来是二进制文件，拒绝编辑（本工具只处理 UTF-8 文本）`)
+    throw new UsageError(`${label}: contains NUL bytes, so this looks like a binary file; refusing to edit (these tools handle UTF-8 text only)`)
   }
   const body = info.bom ? bytes.subarray(3) : bytes
   let text
   try {
     text = new TextDecoder('utf-8', { fatal: true }).decode(body)
   } catch (error) {
-    throw new UsageError(`${label}: 不是合法 UTF-8（${error && error.message ? error.message : 'decode error'}），拒绝写盘以免损坏文件`)
+    throw new UsageError(`${label}: not valid UTF-8 (${error && error.message ? error.message : 'decode error'}); refusing to write so the file is not corrupted`)
   }
   return { text: toLf(text), info }
 }
@@ -128,12 +115,6 @@ export function splitLines(text) {
   return { lines, endsWithNl }
 }
 
-/** splitLines 的逆运算。 */
-export function joinLines(lines, endsWithNl) {
-  if (lines.length === 0) return ''
-  return lines.join('\n') + (endsWithNl ? '\n' : '')
-}
-
 /** 逻辑文本 → 字符下标 → 行号（1-based）的查找表。 */
 function lineStarts(text) {
   const starts = [0]
@@ -153,35 +134,16 @@ function offsetToLine(starts, offset) {
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
-// 二、路径护栏与显示
+// 二、路径与显示
 // ─────────────────────────────────────────────────────────────────────────────
-
-function normalizeKey(path) {
-  return resolve(path).replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase()
-}
-
-/**
- * 危险路径护栏：拒绝 `.git/`、`.dsh/` 内部，以及工作区之外的路径。
- * @param absPath - 绝对目标路径。
- * @param root - 工作区根。
- * @returns 错误说明，`null` 表示放行。
- */
-export function guardTarget(absPath, root) {
-  const norm = normalizeKey(absPath)
-  const parts = norm.split('/')
-  for (const dir of GUARD_DIRS) {
-    if (parts.includes(dir)) {
-      return `拒绝写入 ${dir}/ 内部（${absPath}）——那是 git / dsh 自己的地盘`
-    }
-  }
-  const rootKey = normalizeKey(root)
-  if (rootKey !== '' && norm !== rootKey && !norm.startsWith(rootKey + '/')) {
-    return `目标在工作区之外：${absPath}（工作区根=${root}）`
-  }
-  return null
-}
-
-/** 工作区内的相对路径（用 / 分隔），用于 diff 头与台账。 */
+//
+// 这里**没有**路径护栏：工作区之外、`.git/`、`.dsh/` 内部都能写。理由是能力取舍——本插件不经
+// `ctx.fs`，宿主沙箱、fs 观察策略与 `sandbox_permissions` 升权拦不到它；而自带的"字符串前缀"护栏既拦不住
+// 符号链接（工作区里的 junction 照样能写到外面），又会在 full-access 会话里禁掉模型本来有权限写的位置。
+// 护栏留给宿主策略与调用方，本包不假装自己是安全边界。唯一保留的是**会话策略**的镜像：
+// `read-only` 会话下两个工具在任何 I/O 之前拒写（见 lib/editor.mjs）。
+
+/** 工作区内的相对路径（用 / 分隔），用于 diff 头与台账；工作区之外回落到绝对路径。 */
 export function relativeLabel(root, absPath) {
   const rel = relative(root, absPath)
   if (rel === '') return basename(absPath)
@@ -195,9 +157,11 @@ export function relativeLabel(root, absPath) {
 
 /**
  * `263` | `263:270` | `263-270` | 负数从末尾算 → 1-based 闭区间。
- * @throws {UsageError} 格式错或越界。
+ * `count` 给定时按"声明的命中行数"校验：`lines` 锚点是一次点名一段行号，声明数与实际行数不符就拒绝
+ * ——与 `grep` / `old_text` 上的 `count` 语义一致（三处都是"声明期望命中数，不符即拒绝"）。
+ * @throws {UsageError} 格式错、越界，或与声明的 count 不符。
  */
-export function parseLinespec(spec, text) {
+export function parseLinespec(spec, text, count = undefined) {
   const cleaned = String(spec).trim()
   const range = /^(-?\d+)\s*[:,-]\s*(-?\d+)$/.exec(cleaned)
   const single = /^-?\d+$/.exec(cleaned)
@@ -210,15 +174,19 @@ export function parseLinespec(spec, text) {
     a = Number(single[0])
     b = a
   } else {
-    throw new UsageError(`lines 格式应为 263 或 263:270，收到 ${JSON.stringify(spec)}`)
+    throw new UsageError(`lines must look like 263 or 263:270, got ${JSON.stringify(spec)}`)
   }
   const total = splitLines(text).lines.length
   if (a < 0) a = total + 1 + a
   if (b < 0) b = total + 1 + b
   if (a < 1 || b < 1 || a > total || b > total) {
-    throw new UsageError(`lines ${spec} 超出范围（该文件共 ${total} 行）`)
+    throw new UsageError(`lines ${spec} is out of range (the file has ${total} lines)`)
+  }
+  const span = a > b ? { start: b, end: a } : { start: a, end: b }
+  if (count !== undefined && span.end - span.start + 1 !== count) {
+    throw new UsageError(`lines ${spec} covers ${span.end - span.start + 1} lines, which does not match the declared count=${count} — refusing to write`)
   }
-  return a > b ? { start: b, end: a } : { start: a, end: b }
+  return span
 }
 
 /** 取第 startLine..endLine 行的**原文**（含各行的换行符，因此替换/删除不会留下空行）。 */
@@ -229,15 +197,21 @@ function rawRange(text, starts, startLine, endLine) {
 }
 
 /**
- * 正则锚点：命中的那一行（多行正则取整块）。命中多处且未声明 count 时报错并列出候选行号。
- * @throws {UsageError} 未命中或多处歧义。
+ * 正则锚点：命中的那一行（多行正则取整块）。`count` 是声明的命中数：不符即拒绝，配对的多处命中逐处替换。
+ * @throws {UsageError} 未命中、命中数不符，或命中多处而未声明 count。
  */
 export function grepSpan(pattern, text, ctx = 0, count = undefined) {
+  // 本函数已经按 `gm` 编译，所以调用方再写一个内联 `(?m)` 只会让 `new RegExp` 抛"Invalid group"——
+  // 而那正是从别处抄来的正则最常见的写法。剥掉它即可（`m` 已生效；`i` / `s` 一并识别）。
+  const source = String(pattern)
+  const inline = /^\(\?([ims]+)\)/.exec(source)
+  const cleaned = inline === null ? source : source.slice(inline[0].length)
+  const flags = `gm${inline !== null && inline[1].includes('i') ? 'i' : ''}${inline !== null && inline[1].includes('s') ? 's' : ''}`
   let re
   try {
-    re = new RegExp(pattern, 'gm')
+    re = new RegExp(cleaned, flags)
   } catch (error) {
-    throw new UsageError(`grep 不是合法正则：${error.message}`)
+    throw new UsageError(`grep is not a valid regex: ${error.message}`)
   }
   const starts = lineStarts(text)
   const { lines } = splitLines(text)
@@ -248,17 +222,21 @@ export function grepSpan(pattern, text, ctx = 0, count = undefined) {
     if (match[0].length === 0) re.lastIndex += 1
     if (hits.length > 5000) break
   }
-  if (hits.length === 0) throw new UsageError(`grep ${JSON.stringify(pattern)} 在目标文件中没有命中`)
-  if (hits.length > 1 && count !== hits.length) {
-    const where = hits.slice(0, 8).map((h) => offsetToLine(starts, h.start)).join('、')
-    throw new UsageError(`grep ${JSON.stringify(pattern)} 命中 ${hits.length} 处（行 ${where}）——写得更精确，或改用 lines/old_text，或用 count 声明命中数`)
+  if (hits.length === 0) throw new UsageError(`grep ${JSON.stringify(pattern)} matched nothing in the target file`)
+  // `count` 就是"声明期望命中数"（与 `old_text` 一致）：不匹配即拒绝，配对的多处命中则逐处替换。
+  // 没有这一句，`grep` 上的 `count` 会被**静默忽略**——命中一处却声明五处照样写盘，与契约相反。
+  if (count !== undefined ? hits.length !== count : hits.length > 1) {
+    const where = hits.slice(0, 8).map((h) => offsetToLine(starts, h.start)).join(', ')
+    throw new UsageError(count === undefined
+      ? `grep ${JSON.stringify(pattern)} matched ${hits.length} times (lines ${where}) — write a tighter pattern, use lines/old_text, or declare the hit count with count`
+      : `grep ${JSON.stringify(pattern)} matched ${hits.length} times (lines ${where}), which does not match the declared count=${count} — refusing to write`)
   }
   const spans = hits.map((h) => ({
     start: Math.max(1, offsetToLine(starts, h.start) - ctx),
     end: Math.min(lines.length, offsetToLine(starts, Math.max(h.start, h.end - 1)) + ctx),
   }))
   if (spans.length === 1) {
-    return { ...spans[0], raw: rawRange(text, starts, spans[0].start, spans[0].end) }
+    return { ...spans[0], blocks: [spans[0]], raw: rawRange(text, starts, spans[0].start, spans[0].end) }
   }
   spans.sort((x, y) => x.start - y.start)
   const merged = []
@@ -267,17 +245,24 @@ export function grepSpan(pattern, text, ctx = 0, count = undefined) {
     if (last && span.start <= last.end) last.end = Math.max(last.end, span.end)
     else merged.push({ ...span })
   }
+  // `raw` 是给"整块一次替换"用的合并文本；`blocks` 是**每一次命中自己的行块**，供声明了 count 的多处命中
+  // 逐处替换——把非相邻的行块拼成一段文本，那段文本在全文里并不存在，拿它去匹配必然失败。
   const raw = merged.map((span) => rawRange(text, starts, span.start, span.end)).join('')
-  return { start: merged[0].start, end: merged[merged.length - 1].end, raw }
+  return { start: merged[0].start, end: merged[merged.length - 1].end, blocks: merged, raw }
 }
 
-/** `lines`（纯数字/区间）与 `grep`（正则）统一入口。 */
+/** `lines`（纯数字/区间）与 `grep`（正则）统一入口；`count` 是"声明的命中数"，两条路径都校验。 */
 export function resolveAnchor(spec, text, ctx = 0, count = undefined) {
   const cleaned = String(spec).trim()
-  const numeric = /^-?\d+(\s*[:,-]\s*-?\d+)?$/.test(cleaned)
-  const span = numeric ? parseLinespec(cleaned, text) : grepSpan(cleaned, text, ctx, count)
+  const numeric = /^-?\d+(?:\s*[:,-]\s*-?\d+)?$/.test(cleaned)
+  const span = numeric ? parseLinespec(cleaned, text, count) : grepSpan(cleaned, text, ctx, count)
   const starts = lineStarts(text)
-  return { start: span.start, end: span.end, raw: span.raw ?? rawRange(text, starts, span.start, span.end) }
+  return {
+    start: span.start,
+    end: span.end,
+    blocks: span.blocks ?? [{ start: span.start, end: span.end }],
+    raw: span.raw ?? rawRange(text, starts, span.start, span.end),
+  }
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -324,36 +309,81 @@ function findAllExact(text, old) {
   return spans
 }
 
-/** 宽松匹配：滑窗比较归一化后的行块，相似度 ≥ 0.9 视为命中。 */
-function relaxedMatch(text, old, kind) {
+/**
+ * 宽松命中的 span 是**整行块**（含行尾空白与换行符），而 `old` 可能没有换行结尾——抄自 `read` 的锚点
+ * 看不到行尾空白，`old_text: 'gamma'` 在文件里其实是 `'gamma   '`。原样用它换掉整块会连带吃掉那些看不见
+ * 的字节：行尾空白留下（`GAMMA   `），换行符也没了，下一行被并进替换结果——改一行变成删一行，而 `+1/-2`
+ * 是模型唯一的线索。
+ *
+ * 判据只取两条，都是匹配层已知的事实：锚点**没有**以换行结尾（调用方换的是行内容，不是行边界），却命中
+ * 了一个尾部含空白的 span。此时收掉 span 的尾部空白，`old` / `new` 的语义就对称了：换行内容，行边界不动，
+ * 行数不变。例外是收完就空（`old` 本身全是空白）——那种锚点没有内容可言，不该被"修"成删掉整行。
+ *
+ * 收的只是**尾部空白**：按行边界寻址的调用方（`lines` / `grep` 锚点，以及抄全整行块的 `old`）不受影响，
+ * README 里"`new_text` 也要以换行结尾"的约定对那两条路径照旧。
+ *
+ * @param text - 逻辑文本（\n 行尾）。
+ * @param old - 旧文本；以换行结尾表示调用方在按行边界寻址。
+ * @param span - 宽松匹配给出的 `[start, end]` 字符区间。
+ * @returns 该收就收过的区间。
+ */
+function clipFuzzySpan(text, old, span) {
+  if (old.endsWith('\n')) return span
+  let end = span[1]
+  // 先收掉行尾空白；span 恰好落在换行符之后时，那个换行符也是这次宽松匹配顺手带上的。
+  while (end > span[0] && (text[end - 1] === ' ' || text[end - 1] === '\t')) end -= 1
+  if (end === span[0]) return span
+  if (text[end - 1] === '\n') end -= 1
+  return end > span[0] ? [span[0], end] : span
+}
+
+/**
+ * 宽松匹配：滑窗比较归一化后的行块，相似度 ≥ 0.9 视为命中。
+ *
+ * 返回**全部**达标候选（相似度降序，同分按行号升序），不只挑最好的那一个：宽松命中的置信度本就低于精确
+ * 命中，多处都能命中时"悄悄挑第一处"等于把决定权交给文件顺序——精确命中多于一处时本模块会拒绝写盘，
+ * 宽松匹配没有理由更宽松。命中数由调用方用 `count` 确认。
+ *
+ * @param text - 逻辑文本。
+ * @param old - 旧片段。
+ * @param kind - 归一化方式（`trail` / `loose` / `ws`）。
+ * @returns `[{ ratio, start, end }]`，无命中时为 `[]`。
+ */
+function relaxedMatches(text, old, kind) {
   const { lines } = splitLines(text)
   const oldLines = splitLines(old).lines
-  if (oldLines.length === 0) return null
+  if (oldLines.length === 0) return []
   const keys = lines.map((line) => normalizeLine(kind, line))
   const oldKeys = oldLines.map((line) => normalizeLine(kind, line))
   const n = oldKeys.length
   const starts = lineStarts(text)
-  let best = null
+  const found = []
   for (let i = 0; i + n <= lines.length; i += 1) {
     if (keys[i] !== oldKeys[0] || keys[i + n - 1] !== oldKeys[n - 1]) continue
     const ratio = similarity(keys.slice(i, i + n).join('\n'), oldKeys.join('\n'))
-    if (ratio >= 0.9 && (best === null || ratio > best.ratio)) best = { ratio, index: i }
+    if (ratio < 0.9) continue
+    found.push({
+      ratio,
+      index: i,
+      start: starts[i],
+      end: i + n < starts.length ? starts[i + n] : text.length,
+    })
   }
-  if (best === null) return null
-  const startOffset = starts[best.index]
-  const endOffset = best.index + n < starts.length ? starts[best.index + n] : text.length
-  return [startOffset, endOffset]
+  found.sort((a, b) => b.ratio - a.ratio || a.start - b.start)
+  return found
 }
 
 /** 失败时给最接近的几处（行号 + 相似度 + 期望 vs 实际）。 */
 export function nearestCandidates(text, old, limit = 3) {
   const { lines } = splitLines(text)
-  const oldLines = splitLines(old).lines.length > 0 ? splitLines(old).lines : [old]
-  const n = oldLines.length
-  const firstKey = normalizeLine('loose', oldLines[0])
+  // `old` 为空时 `splitLines` 给不出候选行，退化成拿 `old` 自己当一行（否则下面的窗口宽度会是 0）。
+  const oldLines = splitLines(old).lines
+  const wanted = oldLines.length > 0 ? oldLines : [old]
+  const n = wanted.length
+  const firstKey = normalizeLine('loose', wanted[0])
   const scored = []
   for (let i = 0; i + n <= lines.length; i += 1) {
-    const ratio = similarity(lines.slice(i, i + n).join('\n'), oldLines.join('\n'))
+    const ratio = similarity(lines.slice(i, i + n).join('\n'), wanted.join('\n'))
     const anchored = normalizeLine('loose', lines[i]) === firstKey ? 0.05 : 0
     scored.push({ index: i, ratio: ratio + anchored })
   }
@@ -365,60 +395,75 @@ export function nearestCandidates(text, old, limit = 3) {
       line: entry.index + 1,
       endLine: Math.min(entry.index + n, lines.length),
       ratio: Math.round(entry.ratio * 1000) / 1000,
-      expected: oldLines.slice(0, 12).join('\n'),
+      expected: wanted.slice(0, 12).join('\n'),
       actual: lines.slice(entry.index, Math.min(entry.index + n, lines.length)).slice(0, 12).join('\n'),
     }))
 }
 
 /**
- * 在 text 里定位 old。
+ * 在 text 里定位 old：精确 → 宽松（`trail` / `loose` / `ws`）→ 失败时给最接近候选。
+ *
+ * 只有一个消歧旋钮：`expect`（声明的命中数）。没有"只取第 k 次出现"这类入口——那是**选择**而非**确认**，
+ * 与"命中多处即拒绝、由调用方把锚点写准"的契约相反（此前的 `nth` 正因绕过它，才让错锚点变成静默的错编辑）。
+ *
  * @param text - 逻辑文本。
  * @param old - 旧片段。
- * @param options - `nth`（只取第 k 次）/ `strict`（禁用宽松匹配）/ `expect`（要求恰好 N 处）。
+ * @param options - `expect`（要求恰好 N 处；不符即拒绝）。
  * @returns { ok, spans, mode, note, hits, candidates }
  */
 export function matchLiteral(text, old, options = {}) {
-  const { nth = 0, strict = false, expect } = options
+  const { expect } = options
+  // 空锚点必须**先**判：`findAllExact` 的 `from = index + max(1, 0)` 会在原地打转并撑爆内存，
+  // 下面几条宽松路径也要先 `splitLines(old)`。空锚点没有内容可寻址。
+  if (old === '') return { ok: false, spans: [], mode: 'miss', hits: [], note: 'old must not be empty', candidates: [] }
   const hits = findAllExact(text, old)
-  if (old === '') return { ok: false, spans: [], mode: 'miss', hits, note: 'old 不能为空', candidates: [] }
-  if (nth > 0) {
-    if (hits.length < nth) {
-      return { ok: false, spans: [], mode: 'miss', hits, note: `old 只出现 ${hits.length} 次，取不到第 ${nth} 次`, candidates: nearestCandidates(text, old) }
-    }
-    return { ok: true, spans: [hits[nth - 1]], mode: nth === 1 ? 'exact' : `exact:nth(${nth})`, hits, note: nth === 1 ? '' : `取第 ${nth} 次出现`, candidates: [] }
-  }
   if (expect !== undefined && hits.length === expect) {
-    return { ok: true, spans: hits, mode: expect === 1 ? 'exact' : `exact:count(${expect})`, hits, note: expect === 1 ? '' : `命中 ${expect} 处，全部替换`, candidates: [] }
+    return { ok: true, spans: hits, mode: expect === 1 ? 'exact' : `exact:count(${expect})`, hits, note: expect === 1 ? '' : `${expect} hits, all replaced`, candidates: [] }
   }
   if (hits.length === 1) return { ok: true, spans: hits, mode: 'exact', hits, note: '', candidates: [] }
   if (hits.length > 1) {
     const starts = lineStarts(text)
-    const where = hits.slice(0, 10).map(([s]) => offsetToLine(starts, s)).join('、')
+    const where = hits.slice(0, 10).map(([s]) => offsetToLine(starts, s)).join(', ')
     const reason = expect !== undefined
-      ? `old 出现 ${hits.length} 次（行 ${where}），与要求的 ${expect} 次不符 —— 已拒绝写盘`
-      : `old 出现 ${hits.length} 次（行 ${where}）—— 用 nth 指定第几次，用 count 声明命中数，或写更长的 old`
+      ? `old occurs ${hits.length} times (lines ${where}), which does not match the expected ${expect} — refusing to write`
+      : `old occurs ${hits.length} times (lines ${where}) — declare the hit count with count, or quote a longer old to narrow it down`
     return { ok: false, spans: [], mode: 'ambiguous', hits, note: reason, candidates: [] }
   }
   if (expect !== undefined) {
-    return { ok: false, spans: [], mode: 'miss', hits, note: `old 精确出现 0 处，要求 ${expect} 处`, candidates: nearestCandidates(text, old) }
+    return { ok: false, spans: [], mode: 'miss', hits, note: `old occurs exactly 0 times, expected ${expect}`, candidates: nearestCandidates(text, old) }
   }
-  if (strict) {
-    return { ok: false, spans: [], mode: 'miss', hits, note: 'old 在目标文件中不存在（strict 已禁用宽松匹配）', candidates: nearestCandidates(text, old) }
-  }
-  for (const [kind, label] of [['trail', '忽略行尾空白'], ['loose', '忽略行首/行尾空白'], ['ws', '忽略全部空白差异']]) {
-    const span = relaxedMatch(text, old, kind)
-    if (span) {
+  for (const [kind, label] of [['trail', 'ignoring trailing whitespace'], ['loose', 'ignoring leading/trailing whitespace'], ['ws', 'ignoring all whitespace differences']]) {
+    const found = relaxedMatches(text, old, kind)
+    if (found.length === 0) continue
+    if (found.length > 1) {
+      // 宽松命中多于一处：与精确命中同样拒绝写盘，绝不按文件顺序悄悄挑一处。
+      const starts = lineStarts(text)
+      const where = found.slice(0, 8).map((entry) => offsetToLine(starts, entry.start)).join(', ')
       return {
-        ok: true,
-        spans: [span],
-        mode: kind,
-        hits,
-        note: `精确匹配失败，已用宽松模式命中（${label}）—— 请核对 diff 的行号`,
-        candidates: [],
+        ok: false,
+        spans: [],
+        mode: 'ambiguous',
+        hits: found.map((entry) => [entry.start, entry.end]),
+        note: `old does not match exactly; the relaxed mode (${label}) hit ${found.length} places (lines ${where}) —`
+          + ' quote a longer old to narrow it down, or use a lines / grep anchor (a relaxed hit is never a choice: there is no way to know it picked the same place)',
+        candidates: nearestCandidates(text, old),
       }
     }
+    // 锚点没写换行结尾、宽松命中却落在整行块上时，把行尾空白留给文件（见 clipFuzzySpan）。
+    const best = found[0]
+    const span = clipFuzzySpan(text, old, [best.start, best.end])
+    const trimmed = span[1] !== best.end
+    return {
+      ok: true,
+      spans: [span],
+      mode: kind,
+      hits,
+      note: `exact match failed; the relaxed mode (${label}) matched instead — check that the change landed where you meant`
+        + (trimmed ? '; the anchor had no trailing newline, so trailing whitespace and the newline stayed in place (otherwise the next line would have been joined)' : ''),
+      candidates: [],
+    }
   }
-  return { ok: false, spans: [], mode: 'miss', hits, note: 'old 在目标文件中不存在（精确与宽松匹配均失败）', candidates: nearestCandidates(text, old) }
+  return { ok: false, spans: [], mode: 'miss', hits, note: 'old does not exist in the target file (both exact and relaxed matching failed)', candidates: nearestCandidates(text, old) }
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -491,8 +536,28 @@ function diffOpsFor(a, b) {
 }
 
 /**
- * unified diff 文本；`label` 只用于 `a/` `b/` 头。
- * 与 GNU diff 一样标出"末尾没有换行"的那一侧。
+ * 把"改动 op 的下标"按上下文并成 hunk（相邻改动之间不超过 2×context+1 就并进同一块），供
+ * `unifiedDiff` 切片用。
+ *
+ * @param changeIndexes - `ops` 中非 `=` 的下标（升序）。
+ * @param context - 每个 hunk 前后保留的上下文行数。
+ * @returns 每个 hunk 的 op 下标区间（闭区间）。
+ */
+function changeRanges(changeIndexes, context) {
+  const blocks = []
+  for (const index of changeIndexes) {
+    const last = blocks[blocks.length - 1]
+    if (last && index - last[last.length - 1] <= context * 2 + 1) last.push(index)
+    else blocks.push([index])
+  }
+  return blocks
+}
+
+/**
+ * unified diff 文本；`label` 只用于 `a/` `b/` 头。与 GNU diff 一样标出"末尾没有换行"的那一侧。
+ *
+ * 输出不进入模型上下文，也不落盘：它是 `diffStat` 计算 `+N/-M` 的依据（行级 LCS 保证计数与真实改动一致）。
+ * 保留它而不换成粗略的行数比较，是为了让统计行在多 hunk、重复行等情形下仍然准确。
  */
 export function unifiedDiff(label, before, after, context = DEFAULT_CONTEXT) {
   if (before === after) return ''
@@ -519,12 +584,7 @@ export function unifiedDiff(label, before, after, context = DEFAULT_CONTEXT) {
     return out.join('\n') + '\n'
   }
 
-  const blocks = []
-  for (const index of changeIndexes) {
-    const last = blocks[blocks.length - 1]
-    if (last && index - last[last.length - 1] <= context * 2 + 1) last.push(index)
-    else blocks.push([index])
-  }
+  const blocks = changeRanges(changeIndexes, context)
 
   const out = [`--- a/${label}`, `+++ b/${label}`]
   for (const block of blocks) {
@@ -576,130 +636,60 @@ export function diffStat(before, after) {
   return { added, removed }
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// 六、原子写、同目标串行
+// ─────────────────────────────────────────────────────────────────────────────
+
 /**
- * 按上限裁剪**模型可见**的 diff 正文。
+ * 系统调用失败的**模型可读**表述。
  *
- * `none` 不返回正文；`auto` 仅在正文不超过上限时返回；`full` 始终返回正文，超过上限时截断并附
- * 一行说明。上限的作用是避免整文件重写产生与输入内容同量级的回吐（实测放大率 ≈ 1.0x）。
- *
- * @param text - 已生成的 unified diff 文本（调用方传 0 上下文行的那份，只保留改动行）。
- * @param mode - `auto` | `full` | `none`（见 `DIFF_MODES`）。
- * @param maxLines - 正文行数上限，默认 `DEFAULT_MAX_DIFF_LINES`。
- * @returns 模型可见的正文；裁剪时附一行说明（省略或截断），可能为空字符串。
+ * Node 原始 `error.message` 同时携带内部临时文件名（`.<名字>.<pid><ts>.tmp`）与绝对路径，二者都不该进入
+ * 模型上下文，而且它不提供可操作信息。这里只保留 errno 与一句原因。
  */
-export function diffBudget(text, mode, maxLines = DEFAULT_MAX_DIFF_LINES) {
-  if (mode === 'none' || text === '') return ''
-  const lines = text.trimEnd().split('\n')
-  if (lines.length <= maxLines) return lines.join('\n')
-  if (mode === 'auto') {
-    return `[diff omitted: ${lines.length} lines > budget ${maxLines}; pass diff:"full" or read the file]`
-  }
-  return [
-    ...lines.slice(0, maxLines),
-    `[diff truncated: ${lines.length} lines total, budget ${maxLines}]`,
-  ].join('\n')
+const FS_ERROR_REASONS = {
+  EACCES: 'no write permission',
+  EBUSY: 'the file is in use by another process',
+  EISDIR: 'the target is a directory',
+  EMFILE: 'out of file handles',
+  ENAMETOOLONG: 'the path is too long',
+  ENOENT: 'no such directory',
+  ENOSPC: 'no space left on the device',
+  ENOTDIR: 'a segment of the path is not a directory',
+  EPERM: 'no write permission',
+  EROFS: 'the file system is read-only',
 }
 
-/**
- * 去掉 unified diff 顶部的 `--- a/…` 与 `+++ b/…` 头两行。
- *
- * 模型可见正文里路径已在结果首行出现过一次，头部两行属于重复；标准形式仍完整保留在 `stdout`
- * 与 UI 卡片中。
- *
- * @param text - unified diff 文本。
- * @returns 去掉文件头之后的文本（没有头部时原样返回）。
- */
-function withoutDiffHeaders(text) {
-  const lines = text.split('\n')
-  let from = 0
-  while (from < lines.length && (lines[from].startsWith('---') || lines[from].startsWith('+++'))) {
-    from += 1
-  }
-  return lines.slice(from).join('\n')
+/** 兜底：把任何仍带内部临时文件名的文本抹掉（未知 errno 时才用得到）。 */
+function scrubTempNames(text) {
+  return String(text ?? '').replace(/\S*\.tmp\b/g, '<temp file>')
+}
+
+/** 一次落盘相关的系统调用失败 → 一句完整、可操作、不含内部细节的失败原因。 */
+function ioFailure(what, label, error) {
+  const code = error !== null && typeof error === 'object' && typeof error.code === 'string' ? error.code : ''
+  if (code === '') return `${label}: could not ${what} (${scrubTempNames(error && error.message ? error.message : error)})`
+  const reason = FS_ERROR_REASONS[code]
+  return `${label}: could not ${what} (${code}${reason === undefined ? '' : ': ' + reason})`
 }
 
 /**
- * 把 unified diff 文本解析为 UI diff 卡片的词汇：`{ path, oldText, newText }` 列表，
- * 与原生 `edit` / `write` 的 `presentationMeta` 同形（纯新增的 hunk 用 `oldText: null`）。
+ * 新建文件时补齐缺失的父目录（`write_text` 的"新建无需任何开关"包括目录）。
  *
- * 该投影面向人类，不经过模型上下文：完整 diff（含上下文行）由此提供，模型侧使用经
- * `diffBudget` 裁剪的正文。
+ * 父目录存在但不是目录（路径中间夹着一个文件）时抛 `ENOTDIR`：不做这项检查时 Windows 报 `ENOENT`
+ * （"目录不存在"），而该位置实际存在一份同名文件，错误码对调用方具有误导性。
  *
- * @param text - unified diff 文本。
- * @param path - 卡片上标注的路径。
- * @returns 每个 hunk 一个条目；没有可解析的 hunk 时返回空数组。
+ * @returns 真正创建过目录时返回该目录的工作区相对路径，否则 `null`。
  */
-export function hunksFromDiff(text, path) {
-  const hunks = []
-  let current = null
-  for (const line of text.split('\n')) {
-    if (line.startsWith('@@')) {
-      current = { old: [], next: [] }
-      hunks.push(current)
-      continue
-    }
-    if (current === null || line.startsWith('\\')) continue
-    if (line.startsWith('-')) current.old.push(line.slice(1))
-    else if (line.startsWith('+')) current.next.push(line.slice(1))
-    else if (line.startsWith(' ')) {
-      current.old.push(line.slice(1))
-      current.next.push(line.slice(1))
+function ensureParentDir(absPath, root) {
+  const dir = dirname(absPath)
+  if (existsSync(dir)) {
+    if (!statSync(dir).isDirectory()) {
+      throw Object.assign(new Error('parent exists but is not a directory'), { code: 'ENOTDIR' })
     }
+    return null
   }
-  return hunks.map((hunk) => ({
-    path,
-    oldText: hunk.old.length > 0 ? hunk.old.join('\n') : null,
-    newText: hunk.next.join('\n'),
-  }))
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// 六、备份、台账、原子写、同目标串行
-// ─────────────────────────────────────────────────────────────────────────────
-
-function two(n, width = 2) {
-  return String(n).padStart(width, '0')
-}
-
-function stamp(date) {
-  return `${date.getFullYear()}${two(date.getMonth() + 1)}${two(date.getDate())}-`
-    + `${two(date.getHours())}${two(date.getMinutes())}${two(date.getSeconds())}-`
-    + `${two(date.getMilliseconds(), 3)}`
-}
-
-/** 备份文件名：<绝对路径扁平化>@<时间戳>。 */
-export function backupFileNameFor(absPath, date = new Date()) {
-  const flat = resolve(absPath).replace(/:/g, '').replace(/[\\/]/g, '_')
-  return `${flat}@${stamp(date)}`
-}
-
-/** 落盘前的原件备份。 */
-export function makeBackup(artifactsDir, absPath, bytes, date = new Date()) {
-  const dir = join(artifactsDir, 'backups')
   mkdirSync(dir, { recursive: true })
-  const name = backupFileNameFor(absPath, date)
-  writeFileSync(join(dir, name), bytes)
-  return name
-}
-
-/** 追加一条 JSONL 台账：每行一个对象，字段见 record。 */
-export function appendLedger(artifactsDir, entry) {
-  const file = join(artifactsDir, 'edits.log')
-  mkdirSync(artifactsDir, { recursive: true })
-  const time = new Date()
-  const record = {
-    time: `${time.getFullYear()}-${two(time.getMonth() + 1)}-${two(time.getDate())} `
-      + `${two(time.getHours())}:${two(time.getMinutes())}:${two(time.getSeconds())}`,
-    ...entry,
-  }
-  let id = 1
-  if (existsSync(file)) {
-    const raw = readFileSync(file, 'utf8')
-    id = raw.split('\n').filter((line) => line.trim() !== '').length + 1
-  }
-  record.id = id
-  writeFileSync(file, JSON.stringify(record) + '\n', { encoding: 'utf8', flag: 'a' })
-  return record
+  return relativeLabel(root, dir)
 }
 
 /**
@@ -751,7 +741,8 @@ export function inferNewline(absPath) {
   if (configured === 'lf') return '\n'
   if (configured === 'crlf' || configured === 'cr') return '\r\n'
   const dir = dirname(absPath)
-  const ext = basename(absPath).includes('.') ? basename(absPath).slice(basename(absPath).lastIndexOf('.')) : ''
+  const dot = basename(absPath).lastIndexOf('.')
+  const ext = dot > 0 ? basename(absPath).slice(dot) : ''
   let sameExtCrlf = 0
   let sameExtLf = 0
   let otherCrlf = 0
@@ -783,7 +774,11 @@ export function inferNewline(absPath) {
     const lf = countLf(sample) - crlf
     if (crlf === 0 && lf === 0) continue
     const isCrlf = crlf > 0 && crlf >= lf
-    if (name.endsWith(ext)) {
+    // 目标没有扩展名时（`ext === ''`）同扩展名那一档退化为"同样没有扩展名的兄弟文件"。
+    if (ext !== '' && name.endsWith(ext)) {
+      if (isCrlf) sameExtCrlf += 1
+      else sameExtLf += 1
+    } else if (ext === '' && !name.includes('.')) {
       if (isCrlf) sameExtCrlf += 1
       else sameExtLf += 1
     } else if (isCrlf) otherCrlf += 1
@@ -811,67 +806,58 @@ function countLf(buffer) {
 // ─────────────────────────────────────────────────────────────────────────────
 
 function fail(path, message) {
-  return { path, ok: false, wrote: false, dryRun: false, stdout: '', stderr: message, brief: '', diff: '' }
+  return { path, ok: false, brief: '', stderr: message }
 }
 
 function hintText(match) {
   if (match.mode === 'ambiguous') {
-    const spans = match.hits.slice(0, 12).map(([s]) => s)
-    return `  候选：old 命中 ${match.hits.length} 处。用 nth 指定第几次，或 count 声明命中数。`
+    return `  Candidates: old occurs ${match.hits.length} times. Declare the hit count with count (all of them are replaced), or quote a longer old to make it unique.`
   }
   if (!match.candidates || match.candidates.length === 0) {
-    return '  没有近似候选：核对文件是否搞错，或用 grep/lines 直接从目标取锚点（不必手抄）。'
+    return '  No near candidates: check that this is the right file, or take the anchor straight from the target with grep/lines (no need to copy it by hand).'
   }
-  const lines = ['  最接近的候选（行号 | 相似度）：']
+  const lines = ['  Closest candidates (lines | similarity):']
   for (const candidate of match.candidates) {
-    lines.push(`  - 行 ${candidate.line}-${candidate.endLine}  相似度 ${candidate.ratio.toFixed(2)}`)
-    lines.push(`      目标实际：${JSON.stringify(candidate.actual.slice(0, 200))}`)
-    lines.push(`      你给的 old：${JSON.stringify(candidate.expected.slice(0, 200))}`)
+    lines.push(`  - lines ${candidate.line}-${candidate.endLine}  similarity ${candidate.ratio.toFixed(2)}`)
+    lines.push(`      in the file: ${JSON.stringify(candidate.actual.slice(0, 200))}`)
+    lines.push(`      your old:    ${JSON.stringify(candidate.expected.slice(0, 200))}`)
   }
   return lines.join('\n')
 }
 
 /**
- * 执行一次编辑/写入。后端无关：调用方只需给出归一后的 plan。
+ * 执行一次编辑 / 写入。后端无关：调用方只需给出归一后的 plan。
  *
- * plan（edit）：`{ kind:'edit', filePath, mode, newText, oldText, anchor:{value}|null, count, nth, strict, dryRun, note }`
- * plan（write）：`{ kind:'write', filePath, content, dryRun, note }`
+ * plan（edit）：`{ kind:'edit', filePath, mode, newText, oldText, anchor:{value}|null, count }`；
+ * plan（write）：`{ kind:'write', filePath, content }`。
  *
- * @param context - `{ root, artifactsDir, backup, log, tool, context, newFileBom, diff, maxDiffLines }`
- * @returns 规范结果 `{ path, ok, wrote, dryRun, stdout, stderr, brief, diff }`
- *   `stdout` = 完整人读文本（含路径头、完整 diff、备份名），`stderr` = 失败原因；
- *   `brief` / `diff` = **模型可见**的那一份（统计行与受预算约束的正文）。
+ * @param context - `{ root, newFileBom }`
+ * @returns 规范结果 `{ path, ok, brief, stderr }`：`brief` 是模型可见的全部内容（一行统计加警告），
+ *   `stderr` 是失败原因（失败时非空，同样模型可见）。
  */
 export async function applyPlan(plan, context) {
-  const {
-    root,
-    artifactsDir = join(root, '.dsh'),
-    backup = true,
-    log = true,
-    tool = 'edit_text',
-    context: diffContext = DEFAULT_CONTEXT,
-    newFileBom = false,
-    diff: diffMode = 'auto',
-    maxDiffLines = DEFAULT_MAX_DIFF_LINES,
-  } = context
+  const { root, newFileBom = false } = context
   const absPath = isAbsolute(plan.filePath) ? resolve(plan.filePath) : resolve(root, plan.filePath)
   const label = relativeLabel(root, absPath)
 
-  const guarded = guardTarget(absPath, root)
-  if (guarded) return fail(plan.filePath, guarded)
-
   return await withTargetLock(absPath, async () => {
     const exists = existsSync(absPath)
     const kind = plan.kind === 'write' ? 'write' : 'edit'
     if (kind === 'edit' && !exists) {
-      return fail(plan.filePath, `目标不存在：${plan.filePath}（新建请用 write_text）`)
+      return fail(plan.filePath, `target does not exist: ${plan.filePath} (use write_text to create it)`)
     }
 
     let original = ''
     let info
     let bytesBefore = Buffer.alloc(0)
     if (exists) {
-      bytesBefore = readFileSync(absPath)
+      // 目标可能是目录（EISDIR）或不可读（EACCES）：这类失败只回一句 errno 说法，
+      // 不把 Node 的原始 message（含绝对路径）塞进模型上下文。
+      try {
+        bytesBefore = readFileSync(absPath)
+      } catch (error) {
+        return fail(plan.filePath, ioFailure('read the target', label, error))
+      }
       try {
         const decoded = decodeText(bytesBefore, label)
         original = decoded.text
@@ -886,7 +872,7 @@ export async function applyPlan(plan, context) {
 
     const warnings = []
     if (info.mixed) {
-      warnings.push(`[warn] 目标文件行尾混用；写回统一为 ${info.eol === '\r\n' ? 'CRLF' : 'LF'}`)
+      warnings.push(`[warn] the target mixes line endings; writing it back as ${info.eol === '\r\n' ? 'CRLF' : 'LF'}`)
     }
 
     let output
@@ -895,74 +881,96 @@ export async function applyPlan(plan, context) {
     if (kind === 'write') {
       output = toLf(plan.content ?? '')
       if (output === original && exists) {
-        return fail(plan.filePath, '没有产生任何变化（新内容与现有内容一致）')
+        return fail(plan.filePath, 'no change (the new content is identical to the current content)')
       }
       if (!output.endsWith('\n') && output !== '') {
-        warnings.push('[warn] 新内容不以换行结尾，文件末尾将没有换行符')
+        warnings.push('[warn] the new content does not end with a newline, so the file will not either')
       }
-      applied.push(['write', 1, Math.max(1, splitLines(output).lines.length), 'write', plan.note ?? ''])
+      applied.push(['write', 1, Math.max(1, splitLines(output).lines.length), 'write', ''])
     } else {
-      const usage = []
-      const { lines } = splitLines(original)
       if (plan.mode === 'append' || plan.mode === 'prepend') {
         output = plan.mode === 'append' ? original : ''
         if (plan.mode === 'append') {
           let add = plan.newText
           if (output !== '' && !output.endsWith('\n')) {
             add = '\n' + add
-            warnings.push('[warn] 目标末尾本来没有换行符，已在追加前补一个')
+            warnings.push('[warn] the target did not end with a newline; one was added before appending')
           }
-          if (add !== '' && !add.endsWith('\n')) warnings.push('[warn] 追加内容不以换行结尾，文件末尾将没有换行符')
+          if (add !== '' && !add.endsWith('\n')) warnings.push('[warn] the appended content does not end with a newline, so the file will not either')
           output += add
         } else {
           let add = plan.newText
           if (original !== '' && add !== '' && !add.endsWith('\n')) add += '\n'
           output += add + original
         }
-        applied.push([plan.mode, 1, 1, plan.mode, plan.note ?? ''])
+        applied.push([plan.mode, 1, 1, plan.mode, ''])
       } else {
         const plans = []
         if (plan.mode === 'replace') {
-          let target = plan.oldText
           let match
+          let anchorSpan
+          // 行首下标表：多处命中要按行块换算成字符区间，单处命中要换算成行号。
+          const charStarts = lineStarts(original)
           if (plan.anchor) {
-            let anchorSpan
             try {
-              anchorSpan = resolveAnchor(plan.anchor.value, original, 0)
+              // `count` 必须传进来：`grep` 命中多处时报错原文就写着"用 count 声明命中数"。
+              anchorSpan = resolveAnchor(plan.anchor.value, original, 0, plan.count)
             } catch (error) {
-              usage.push(error instanceof UsageError ? error.message : String(error))
-              anchorSpan = null
+              return fail(plan.filePath, error instanceof UsageError ? error.message : String(error))
             }
-            if (anchorSpan === null) return fail(plan.filePath, usage.join('\n'))
-            target = anchorSpan.raw
-            const exact = matchLiteral(original, target, { nth: plan.nth ?? 0, strict: true })
-            match = exact.ok ? exact : matchLiteral(original, target, { nth: plan.nth ?? 0, strict: false })
-            if (match.ok) match.mode = `anchor:${match.mode}`
+            // 声明的多处命中逐处替换：`count` 已在上面校验过命中数，每一次命中都有自己的行块，拿它替换
+            // 即可（把多个非相邻行块拼成一段文本去匹配只会得到"old 不存在"）。
+            const blocks = anchorSpan.blocks ?? []
+            match = blocks.length > 1
+              ? {
+                ok: true,
+                spans: blocks.map((block) => [
+                  charStarts[block.start - 1],
+                  block.end < charStarts.length ? charStarts[block.end] : original.length,
+                ]),
+                mode: `exact:count(${plan.count})`,
+                hits: [],
+                note: '',
+                candidates: [],
+              }
+              : matchLiteral(original, anchorSpan.raw, {})
+            if (match.ok) match.mode = match.mode.startsWith('exact:count(') ? match.mode : `anchor:${match.mode}`
           } else {
-            match = matchLiteral(original, target ?? '', {
-              nth: plan.nth ?? 0,
-              strict: plan.strict === true,
-              expect: plan.count,
-            })
+            match = matchLiteral(original, plan.oldText ?? '', { expect: plan.count })
           }
           if (!match.ok) {
             return fail(plan.filePath, `${label}：${match.note}\n${hintText(match)}`)
           }
-          if (plan.count !== undefined && (plan.nth ?? 0) === 0 && match.hits.length !== plan.count) {
-            return fail(plan.filePath, `${label}：old 出现 ${match.hits.length} 次，要求 ${plan.count} 次 —— 拒绝写盘`)
-          }
+          // 锚点路径的 mode 带 `anchor:` 前缀；去掉它之后，"是不是精确命中"才可判。
+          const hitMode = String(match.mode).replace(/^anchor:/, '')
+          // 不拿 `match.hits.length` 比 `plan.count`：`count` 的校验各有其主——`grep` / `lines` 由
+          // `resolveAnchor` 在命中处校验，`old_text` 由 `matchLiteral` 的 `expect` 校验。锚点路径的
+          // hits 是"锚点文本在全文出现几次"，逐处替换时天然为 1，拿它比 `count` 只会把正当的多处替换
+          // 误判成失败。
           for (const [start, end] of match.spans) {
-            const startLine = offsetToLine(lineStarts(original), start)
-            const endLine = end > start ? offsetToLine(lineStarts(original), end - 1) : startLine
-            plans.push({ start, end, mode: match.mode, startLine, endLine })
+            const startLine = offsetToLine(charStarts, start)
+            const endLine = end > start ? offsetToLine(charStarts, end - 1) : startLine
+            plans.push({ start, end, mode: hitMode, startLine, endLine })
           }
-          if (match.mode === 'trail' || match.mode === 'loose' || match.mode === 'ws' || String(match.mode).includes('trail') || String(match.mode).includes('loose')) {
+          // 只通报宽松命中：`exact` 与 `exact:count(N)` 带的是"命中 N 处，全部替换"这类说明，不是警告。
+          if (hitMode !== 'exact' && !hitMode.startsWith('exact:count(')) {
             warnings.push(`[warn] ${match.note}`)
           }
+          // 锚点带着行尾换行符、替换文本却没有：被换掉的那一行会和下一行并成一行。只对 `old_text` 说
+          // 这一句——`lines`/`grep` 是调用方点名要的整行行块，README 已把"`new_text` 也要以换行结尾"
+          // 写成前置约定，每次调用都重复提示只是噪声；而抄来的 `old_text` 带着换行、`new_text` 忘了带
+          // 换行时，`+1/-2` 说明不了"少了一行"。
+          if (plan.anchor === null && match.spans.length === 1 && match.spans[0][1] > match.spans[0][0]
+            && original.startsWith('\n', match.spans[0][1] - 1)
+            && plan.newText !== '' && !plan.newText.endsWith('\n')) {
+            warnings.push('[warn] the anchor ends with a newline but the replacement does not — the replaced line has been joined with the next one;'
+              + ' to keep the line boundary, end new_text with a newline too')
+          }
         } else {
           let anchorSpan
           try {
-            anchorSpan = resolveAnchor(plan.anchor.value, original, 0)
+            // `count` 同样要传：声明了命中行数就与 `replace` 档一样校验，不能悄悄忽略。
+            anchorSpan = resolveAnchor(plan.anchor.value, original, 0, plan.count)
           } catch (error) {
             return fail(plan.filePath, error instanceof UsageError ? error.message : String(error))
           }
@@ -984,92 +992,50 @@ export async function applyPlan(plan, context) {
           const previous = sorted[i - 1]
           const current = sorted[i]
           if (current.start < previous.end) {
-            return fail(plan.filePath, `两次编辑区间重叠（行 ${previous.startLine} 与 ${current.startLine}）——请拆成两次调用`)
+            return fail(plan.filePath, `two edit ranges overlap (lines ${previous.startLine} and ${current.startLine}) — split this into two calls`)
           }
         }
 
-        output = original
-        for (const item of [...plans].sort((a, b) => b.start - a.start)) {
-          output = output.slice(0, item.start) + plan.newText + output.slice(item.end)
-          applied.push(['replace', item.startLine, item.endLine, item.mode, plan.note ?? ''])
+        // 按 `start` 升序把原文的"间隙"与替换文本拼起来。逐段推进游标，不做任何坐标换算——先前的
+        // "从后往前替换 + 位移修正"等价于这里的一次遍历，却要在每处替换后重算下标，容易写错。
+        const ordered = [...plans].sort((a, b) => a.start - b.start)
+        const parts = []
+        let cursor = 0
+        for (const item of ordered) {
+          parts.push(original.slice(cursor, item.start), plan.newText)
+          cursor = item.end
+          applied.push(['replace', item.startLine, item.endLine, item.mode, ''])
         }
-        void lines
+        parts.push(original.slice(cursor))
+        output = parts.join('')
       }
     }
 
     if (output === original && exists) {
-      return fail(plan.filePath, '没有产生任何变化（old 与 new 相同，或内容已一致）')
-    }
-    if (!exists && output === '') {
-      return fail(plan.filePath, '新建内容为空 —— 没有产生任何变化')
+      return fail(plan.filePath, 'no change (old and new are identical, or the content already matches)')
     }
 
-    const diff = unifiedDiff(label, original, output, diffContext)
     const stat = diffStat(original, output)
     const created = !exists
-    const head = plan.dryRun
-      ? `=== ${label}${created ? '（新建）' : ''} | DRY RUN（未落盘）===`
-      : `=== ${label}${created ? '（新建）' : ''} | 已写入 ===`
     const kinds = [...new Set(applied.map(([k, s, e]) => (k === 'replace' ? `replace@${s}${e !== s ? `-${e}` : ''}` : k)))]
-      .join('、')
-
-    // 模型可见部分：警告 + 一行统计（+A/-B）+ 经上限裁剪的正文。
-    // 正文使用 0 上下文行：调用方刚完成这次编辑，周边内容或已读取过，或可自行读取。
-    // 完整 diff（含上下文行）只出现在 stdout 与 UI 卡片中，不进入这条路径。
-    const brief = [...warnings, `${kinds} +${stat.added}/-${stat.removed}`].join('\n')
-    const visibleDiff = diffBudget(withoutDiffHeaders(unifiedDiff(label, original, output, 0)), diffMode, maxDiffLines)
+      .join(', ')
 
-    if (plan.dryRun) {
-      return {
-        path: plan.filePath,
-        ok: true,
-        wrote: false,
-        dryRun: true,
-        stdout: [...warnings, head, diff.trimEnd(), `DRY RUN ${label}：${kinds}（+${stat.added}/-${stat.removed}）`].filter((s) => s !== '').join('\n') + '\n',
-        stderr: '',
-        brief,
-        diff: visibleDiff,
+    if (created) {
+      try {
+        ensureParentDir(absPath, root)
+      } catch (error) {
+        return fail(plan.filePath, ioFailure('create the directory', label, error))
       }
     }
 
-    let backupName = null
-    if (exists && backup) {
-      backupName = makeBackup(artifactsDir, absPath, bytesBefore)
-    }
     try {
       writeFileAtomic(absPath, encodeText(output, info))
     } catch (error) {
-      return fail(plan.filePath, `写入失败：${error && error.message ? error.message : String(error)}`)
-    }
-
-    if (log) {
-      const first = applied[0] ?? ['?', 0, 0, '', '']
-      appendLedger(artifactsDir, {
-        tool,
-        file: label,
-        abspath: absPath,
-        action: created ? 'create' : 'write',
-        kinds: applied.map(([k]) => k),
-        line_start: first[1],
-        line_end: first[2],
-        added: stat.added,
-        removed: stat.removed,
-        bom: info.bom,
-        eol: info.eol === '\r\n' ? 'CRLF' : 'LF',
-        backup: backupName,
-        summary: `${kinds}${plan.note ? `；${plan.note}` : ''}`,
-      })
+      return fail(plan.filePath, ioFailure('write the target', label, error))
     }
 
-    return {
-      path: plan.filePath,
-      ok: true,
-      wrote: true,
-      dryRun: false,
-      stdout: [...warnings, head, diff.trimEnd(), `OK ${label}：${kinds}（+${stat.added}/-${stat.removed}）${backupName ? `；备份 ${backupName}` : ''}`].filter((s) => s !== '').join('\n') + '\n',
-      stderr: '',
-      brief,
-      diff: visibleDiff,
-    }
+    // 模型可见文本：警告行 + 一行统计（如 `replace@17 +1/-1`）。不回显改动内容（理由见文件头）。
+    const brief = [...warnings, `${kinds} +${stat.added}/-${stat.removed}`].join('\n')
+    return { path: plan.filePath, ok: true, brief, stderr: '' }
   })
 }