aura-basetools 0.20.0 → 0.21.0

package/locator-lab/doc-structure.mjs

@@ -0,0 +1,382 @@
+/**
+ * doc-structure.mjs —— 文档 / 配置的结构目录（`map` 用）。
+ *
+ * ## 为什么需要它
+ *
+ * `map` 现在只认代码扩展名；`.md` / `.json` / `.yaml` / `.toml` 一律回一句
+ * “unsupported extension — no symbol index”。而实测最近 62 个会话里 **1,836 次 read**
+ * 有 330 次 `.md`（18%）、55 次 `.json`、13 次 `.yml`——约 22% 的目标是文档/配置，
+ * 它们拿到的地图是一句拒绝。
+ *
+ * ## 为什么不是“再写一个解析器”
+ *
+ * 这层的目标不是完整语法，而是**目录**：给出行号、层级与名字，让人能挑一段用
+ * `mode=lines` 取回。所以：
+ *   · Markdown：ATX 标题（跳过围栏代码块里的 `#`）；setext 标题不认（降级为正文）。
+ *   · JSON：字符串/注释感知的轻量扫描，给对象键与数组元素；解析不完整时**降级**而不是抛。
+ *   · YAML：缩进 + `key:` 行；锚点/多行块不展开（目录仍然可用）。
+ *   · TOML：`[table]` 与 `key =` 行。
+ *
+ * 每条 entry 都有 `startLine` / `endLine`：目录本身要可执行（下一步是 `mode=lines`）。
+ */
+
+/** 扩展名 → 文档种类。故意不含 `.txt`：纯文本没有结构，给了目录也是假的。 */
+export const DOC_KINDS = {
+  md: 'markdown',
+  markdown: 'markdown',
+  mdx: 'markdown',
+  json: 'json',
+  jsonc: 'json',
+  json5: 'json',
+  yaml: 'yaml',
+  yml: 'yaml',
+  toml: 'toml',
+}
+
+/** `filePath` 的扩展名决定用哪套结构索引；不是文档类型返回 null。 */
+export function docKindOf(filePath) {
+  if (typeof filePath !== 'string') return null
+  const dot = filePath.lastIndexOf('.')
+  if (dot < 0) return null
+  const ext = filePath.slice(dot + 1).toLowerCase()
+  return DOC_KINDS[ext] ?? null
+}
+
+/**
+ * 索引一篇文档。
+ *
+ * @returns {{entries: Array<{name:string, kind:string, depth:number, startLine:number, endLine:number}>, unit:string, note?:string}}
+ */
+export function indexDocument(source, docKind) {
+  const lines = String(source).split(/\r?\n/)
+  if (docKind === 'markdown') return indexMarkdown(lines)
+  if (docKind === 'json') return indexJson(String(source), lines)
+  if (docKind === 'yaml') return indexYaml(lines)
+  if (docKind === 'toml') return indexToml(lines)
+  return { entries: [], unit: 'entries', note: `no structure index for ${docKind}` }
+}
+
+/* ── Markdown ─────────────────────────────────────────────────────────────── */
+
+function indexMarkdown(lines) {
+  const entries = []
+  let fence = null
+  /** YAML front matter：只在第 1 行 `---` 起算，到下一个 `---` / `...` 结束。 */
+  let frontMatter = false
+  /**
+   * 上一行是否是一个“可以升级为 setext 标题的段落行”。
+   *
+   * 为什么不能只看“下一行是不是 `===`/`---`”：`---` 同时是**分隔线**、也是 YAML
+   * front matter 的边界。CommonMark 的消歧规则是：setext 下划线只能接在**段落**后面
+   * （列表项、引用、缩进代码、标题、分隔线都不行），而分隔线前面又必须是空行。
+   * 所以这里维护一个“上一行是段落行”的状态，而不是做简单的向前看。
+   */
+  let paragraph = -1
+  /** 当前段落的起始行：setext 标题取的是**整段**，不是最后一行（CommonMark）。 */
+  let paragraphStart = -1
+  const isParagraph = (line) => {
+    if (line.trim() === '') return false
+    if (/^\s{4,}/.test(line)) return false // 缩进代码块
+    if (/^\s*>/.test(line)) return false // 引用
+    if (/^\s*(?:[-*+]|\d+[.)])\s+/.test(line)) return false // 列表项
+    if (/^\s*(```+|~~~+)/.test(line)) return false
+    if (/^ {0,3}#{1,6}(?:\s|$)/.test(line)) return false // ATX 标题
+    if (/^\s*(?:(?:\*\s*){3,}|(?:-\s*){3,}|(?:_\s*){3,})$/.test(line)) return false // 分隔线
+    if (/^\s*<[^>]+>/.test(line)) return false // HTML 块（粗略）
+    return true
+  }
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i]
+    if (i === 0 && /^---\s*$/.test(line)) {
+      frontMatter = true
+      continue
+    }
+    if (frontMatter) {
+      if (/^(?:---|\.\.\.)\s*$/.test(line)) frontMatter = false
+      continue
+    }
+    const fenceHit = /^\s*(```+|~~~+)/.exec(line)
+    if (fenceHit !== null) {
+      const mark = fenceHit[1][0]
+      if (fence === null) fence = mark
+      else if (fence === mark) fence = null
+      paragraph = -1
+      continue
+    }
+    if (fence !== null) continue
+    // setext：上一行是段落 ⇒ 本行是它的下划线（`=` 一级，`-` 二级）
+    const setext = /^ {0,3}(=+|-+)\s*$/.exec(line)
+    if (setext !== null && paragraph === i - 1) {
+      // 多行段落 → 标题文本是整段（行间用空格接起来），区间从段首算起。
+      const name = lines.slice(paragraphStart, paragraph + 1).map((row) => row.trim()).filter(Boolean).join(' ')
+      entries.push({
+        kind: 'heading',
+        name: name || '(untitled)',
+        depth: setext[1][0] === '=' ? 1 : 2,
+        startLine: paragraphStart + 1,
+        endLine: i + 1,
+      })
+      paragraph = -1
+      paragraphStart = -1
+      continue
+    }
+    const heading = /^(#{1,6})\s+(.*?)\s*#*\s*$/.exec(line)
+    if (heading !== null) {
+      entries.push({
+        kind: 'heading',
+        name: heading[2].length === 0 ? '(untitled)' : heading[2],
+        depth: heading[1].length,
+        startLine: i + 1,
+        endLine: i + 1,
+      })
+      paragraph = -1
+      paragraphStart = -1
+      continue
+    }
+    if (isParagraph(line)) {
+      // 连续段落行：保持 paragraphStart，直到段落被中断。
+      // 注意 `paragraph === -1` 与“上一行正好是 -1”会撞车（第 1 行时 i-1 也是 -1），
+      // 所以用 paragraphStart 的哨兵值把“段落还没开始”区分开。
+      if (paragraphStart === -1 || paragraph !== i - 1) paragraphStart = i
+      paragraph = i
+    } else {
+      paragraph = -1
+      paragraphStart = -1
+    }
+  }
+  // 每节的范围 = 到下一个标题（任意层级）之前；最后一节到文件尾。
+  for (let k = 0; k < entries.length; k += 1) entries[k].endLine = (entries[k + 1]?.startLine ?? lines.length + 1) - 1
+  return { entries, unit: 'sections' }
+}
+
+/* ── JSON / JSONC ─────────────────────────────────────────────────────────── */
+
+/**
+ * 轻量扫描：不建 AST，只记录“键/元素在哪几行”。
+ *
+ * 关键取舍：**不抛**。配置里出现尾逗号、注释、甚至半份文件时，已经扫到的目录仍然有用，
+ * 比一句“解析失败”有用得多；扫不动的部分在 `note` 里说。
+ */
+function indexJson(source, lines) {
+  const entries = []
+  /** 每层容器记自己的目录项（由父层创建）；闭合时把它的 endLine 收到闭合行。 */
+  const stack = [] // { type:'object'|'array', path:string, entry:entry|null, index:number }
+  let i = 0
+  let line = 1
+  let note = null
+  let expectKey = false
+  let pendingKey = null
+  let pendingKeyLine = 0
+
+  /**
+   * 键里有 `.` / 空格 / `[` 时不能拼成 `a.b`（`exports."."` 会读成 `exports..`——实测就撞上了）：
+   * 改用 `parent["key"]`，与 JS/JSONPath 的习惯一致。
+   */
+  const seg = (key) => (/^[A-Za-z0-9_$-]+$/.test(key) ? key : `[${JSON.stringify(key)}]`)
+  const pathOf = (parent, key) => (parent === '' ? seg(key) : `${parent}${seg(key).startsWith('[') ? seg(key) : `.${seg(key)}`}`)
+  const add = (entry) => {
+    entries.push(entry)
+    return entry
+  }
+  const skipTrivia = () => {
+    while (i < source.length) {
+      const c = source[i]
+      if (c === '\n') {
+        line += 1
+        i += 1
+      } else if (c === ' ' || c === '\t' || c === '\r') {
+        i += 1
+      } else if (c === '/' && source[i + 1] === '/') {
+        while (i < source.length && source[i] !== '\n') i += 1
+      } else if (c === '/' && source[i + 1] === '*') {
+        i += 2
+        while (i < source.length && !(source[i] === '*' && source[i + 1] === '/')) {
+          if (source[i] === '\n') line += 1
+          i += 1
+        }
+        i += 2
+      } else break
+    }
+  }
+  const readString = (quote = '"') => {
+    // 调用方已在引号上
+    const startLine = line
+    i += 1
+    let value = ''
+    while (i < source.length) {
+      const c = source[i]
+      if (c === '\\') {
+        value += source[i + 1] ?? ''
+        i += 2
+        continue
+      }
+      if (c === quote) {
+        i += 1
+        return { value, line: startLine }
+      }
+      if (c === '\n') line += 1
+      value += c
+      i += 1
+    }
+    note = note ?? 'unterminated string — the directory stops where the text does'
+    return { value, line: startLine }
+  }
+
+  while (i < source.length) {
+    skipTrivia()
+    if (i >= source.length) break
+    const c = source[i]
+    const top = stack[stack.length - 1]
+    if (c === '{' || c === '[') {
+      const isObject = c === '{'
+      const name = top === undefined
+        ? ''
+        : top.type === 'array'
+          ? `${top.path}[${top.index}]`
+          : pathOf(top.path, pendingKey ?? '?')
+      const ownEntry = top === undefined
+        ? null
+        : add({ kind: isObject ? 'object' : 'array', name, depth: stack.length + 1, startLine: line, endLine: line })
+      stack.push({ type: isObject ? 'object' : 'array', path: name, entry: ownEntry, index: 0 })
+      expectKey = isObject
+      pendingKey = null
+      i += 1
+      continue
+    }
+    if (c === '}' || c === ']') {
+      const closed = stack.pop()
+      if (closed !== undefined && closed.entry !== null && closed.entry !== undefined) closed.entry.endLine = line
+      expectKey = stack.length > 0 && stack[stack.length - 1].type === 'object'
+      i += 1
+      continue
+    }
+    if (c === ',') {
+      expectKey = top !== undefined && top.type === 'object'
+      pendingKey = null
+      if (top !== undefined && top.type === 'array') top.index += 1
+      i += 1
+      continue
+    }
+    if (c === ':') {
+      i += 1
+      continue
+    }
+    /**
+     * JSON5：无引号键（`{name: 1}`）。必须在“标量跳过”之前认，否则整个 `name: 1`
+     * 会被当成标量吞到下一个逗号，目录里就少了这个键。
+     */
+    if (expectKey && /[A-Za-z_$]/.test(c)) {
+      let key = ''
+      while (i < source.length && /[A-Za-z0-9_$]/.test(source[i])) {
+        key += source[i]
+        i += 1
+      }
+      pendingKey = key
+      pendingKeyLine = line
+      expectKey = false
+      continue
+    }
+    if (c === '"' || c === "'") {
+      const str = readString(c)
+      if (expectKey) {
+        pendingKey = str.value
+        pendingKeyLine = str.line
+        expectKey = false
+      } else if (top !== undefined && top.type === 'object' && pendingKey !== null) {
+        // 对象键的值是字符串：目录行就是键所在的那一行（与标量值同一条规则）。
+        add({ kind: 'key', name: pathOf(top.path, pendingKey), depth: stack.length, startLine: pendingKeyLine, endLine: str.line })
+        pendingKey = null
+      } else if (top !== undefined && top.type === 'array') {
+        // 数组里的字符串元素：只有对象/数组元素才值得进目录；标量元素跳过。
+        top.index += 1
+      }
+      continue
+    }
+    // 标量：跳过到下一个分隔符
+    while (i < source.length && !',}]'.includes(source[i])) {
+      if (source[i] === '\n') line += 1
+      i += 1
+    }
+    if (top !== undefined && top.type === 'object' && pendingKey !== null) {
+      // 对象键的值是标量：目录行就是键所在行
+      add({ kind: 'key', name: pathOf(top.path, pendingKey), depth: stack.length, startLine: pendingKeyLine, endLine: line })
+      pendingKey = null
+    } else if (top !== undefined && top.type === 'array') {
+      top.index += 1
+    }
+  }
+  if (stack.length > 0) note = note ?? 'the document ends inside an open container — the directory is partial'
+  return { entries, unit: 'keys', ...(note === null ? {} : { note }) }
+}
+
+/* ── YAML ─────────────────────────────────────────────────────────────────── */
+
+function indexYaml(lines) {
+  const entries = []
+  const stack = [] // { indent, name }
+  let blockScalarIndent = null
+  for (let i = 0; i < lines.length; i += 1) {
+    const raw = lines[i]
+    if (raw.trim() === '' || /^\s*#/.test(raw)) continue
+    const indent = raw.length - raw.trimStart().length
+    if (blockScalarIndent !== null && indent > blockScalarIndent) continue
+    blockScalarIndent = null
+    if (/^---(\s|$)/.test(raw) || /^\.\.\.(\s|$)/.test(raw)) {
+      stack.length = 0
+      continue
+    }
+    const body = raw.trimStart()
+    const match = /^(-\s+)?([^#\s][^:]*?):(\s|$)/.exec(body)
+    if (match === null) continue
+    while (stack.length > 0 && stack[stack.length - 1].indent >= indent) stack.pop()
+    const key = match[2]
+    const path = stack.length === 0 ? key : `${stack[stack.length - 1].name}.${key}`
+    const entry = { kind: 'key', name: path, depth: stack.length + 1, startLine: i + 1, endLine: i + 1 }
+    entries.push(entry)
+    // 值是否是多行块标量：`key: |` / `key: >`
+    if (/\s[|>][-+]?\s*$/.test(body)) blockScalarIndent = indent
+    stack.push({ indent, name: path })
+  }
+  // 一节的范围 = 到**下一个同级或更高级**的键之前（中间的深一级键属于它）。
+  for (let k = 0; k < entries.length; k += 1) {
+    let j = k + 1
+    while (j < entries.length && entries[j].depth > entries[k].depth) j += 1
+    entries[k].endLine = j < entries.length ? Math.max(entries[k].startLine, entries[j].startLine - 1) : lines.length
+  }
+  return { entries, unit: 'keys' }
+}
+
+/* ── TOML ─────────────────────────────────────────────────────────────────── */
+
+function indexToml(lines) {
+  const entries = []
+  let table = ''
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i].trim()
+    if (line === '' || line.startsWith('#')) continue
+    const tableHit = /^\[\[?([^\]]+)\]\]?$/.exec(line)
+    if (tableHit !== null) {
+      table = tableHit[1].trim()
+      entries.push({ kind: 'table', name: table, depth: table.split('.').length, startLine: i + 1, endLine: i + 1 })
+      continue
+    }
+    const keyHit = /^([A-Za-z0-9_.-]+)\s*=/.exec(line)
+    if (keyHit !== null) {
+      const name = table === '' ? keyHit[1] : `${table}.${keyHit[1]}`
+      entries.push({ kind: 'key', name, depth: name.split('.').length, startLine: i + 1, endLine: i + 1 })
+    }
+  }
+  /**
+   * TOML 的范围规则与 YAML 不同：表（`[a.b]`）是扁平段，深度按点名数算，
+   * 但 `[db.pool]` 与 `[server]` 是**同级**——它们之间没有父子关系。
+   * 所以：表到下一张表之前；键只占自己那一行（多行值不进目录，mode=lines 拿）。
+   */
+  for (let k = 0; k < entries.length; k += 1) {
+    if (entries[k].kind !== 'table') continue
+    let j = k + 1
+    while (j < entries.length && entries[j].kind !== 'table') j += 1
+    entries[k].endLine = j < entries.length ? Math.max(entries[k].startLine, entries[j].startLine - 1) : lines.length
+  }
+  return { entries, unit: 'keys' }
+}
+

package/locator-lab/read-core.mjs

@@ -22,6 +22,7 @@
  */
 
 import { indexStructure, langOf, listSymbols, rankSymbols, resolveTarget } from './struct-core.mjs'
+import { docKindOf, indexDocument } from './doc-structure.mjs'
 /**
  * 区间句柄（HD1）：本文件只**发**句柄，编辑侧怎么解析是另一张单的事。
  *
@@ -185,7 +186,7 @@ function serializedSize(envelope) {
  * 模式。刻意做成显式枚举而不是"有参数就切换"——后者会让"我到底要什么"变得含糊，
  * 而含糊正是信息浪费的源头。
  */
-export const MODES = ['map', 'digest', 'full', 'around', 'lines', 'search', 'changed']
+export const MODES = ['map', 'digest', 'full', 'around', 'lines', 'search', 'changed', 'probe']
 
 /**
  * 摘要：**看懂一个文件**所需的最小信息集。
@@ -198,10 +199,26 @@ export const MODES = ['map', 'digest', 'full', 'around', 'lines', 'search', 'cha
  */
 function renderDigest(base, source, lines, lang, request, symbolsIndex = null) {
   if (lang === null) {
+    /**
+     * 文档没有签名，但有**结构**。`digest` 的承诺是“无正文的结构”，
+     * 所以文档的 digest = 结构目录（与 `map` 同源），而不是一句“没有结构”。
+     */
+    const docKind = docKindOf(request.filePath)
+    if (docKind !== null) {
+      return {
+        ...renderDocMap(base, lines, docKind, request),
+        mode: 'digest',
+        note: 'documents have no signatures; this is their structure directory (same as mode=map)',
+      }
+    }
+    /**
+     * 正文放 `text`（不是 `note`）：`metrics.chars` 量的是 `text` 的长度（read-test 钉着这条等式），
+     * 只给 `note` 时 `chars` 会报 0，与 note 里的实际信息矛盾（反馈 D8）。
+     */
     return {
       ...base,
       mode: 'digest',
-      note: `unsupported extension — no structure available; ${base.totalLines} lines`,
+      text: `unsupported extension — no structure available; ${base.totalLines} lines`,
       next: 'mode=lines lines=[a,b]',
     }
   }
@@ -1524,7 +1541,23 @@ function planIncremental(request, lines, version) {
       : { kind: 'skip' }
   }
   if (entry.version === version) {
-    return { kind: 'no-change', baseline: entry.version, asked, partial: entry.covered !== true, bomChanged: false }
+    /**
+     * 同一版重读：**只有账本里那份是完整交付时**，“不发正文”才成立。
+     *
+     * 上一次被预算截断（`covered = false`）时，调用方手里只有前半份。旧实现仍走
+     * `no-change`，只回一句“去用 lines 拿剩下的”，于是**显式提高 budget 的请求被吞掉**：
+     * 实测 401 行文件第二次 `full` + `budget: 60000` 只拿到 155 字符，且 `truncated: false`——
+     * 程序化调用方会把它当成“已拿全”。（反馈 D4）
+     *
+     * 现在：没被显式要求增量 ⇒ `skip`（普通 full 渲染，按本次 budget 出正文）；
+     * 被显式要求增量 ⇒ `degrade`（全文 + 为何不能给差量）。两者都不会再谎报“没变化”。
+     */
+    if (entry.covered !== true) {
+      return asked
+        ? { kind: 'degrade', asked: true, reason: 'your earlier read of this file was cut at the content budget, so the ledger copy is not a complete baseline; the full text follows' }
+        : { kind: 'skip' }
+    }
+    return { kind: 'no-change', baseline: entry.version, asked, bomChanged: false }
   }
   if (entry.covered !== true) {
     return asked
@@ -1563,15 +1596,9 @@ function planIncremental(request, lines, version) {
 
 /** 文件没变时的回执：**明写 no change、明写基准令牌，不给正文**。 */
 function noChangeEnvelope(base, plan, total) {
-  const partial = plan.partial === true
   const bom = plan.bomChanged === true ? ' (the byte-order mark changed; the text itself is unchanged)' : ''
-  const note = partial
-    ? `no change since baseline ${plan.baseline} — but your earlier read of this file was cut at the content budget, so it is not the whole file`
-    : `no change since baseline ${plan.baseline} — the file is byte-identical to the copy you already have${bom}`
-  const text = partial
-    ? `no change since baseline ${plan.baseline}; your earlier copy was truncated at the content budget — ask for the missing lines with mode=lines if you need them`
-    : `no change since baseline ${plan.baseline} — nothing to send${bom}`
-  return { ...base, mode: 'full', note, text, next: `mode=lines lines=[1,${total}] to get the whole text again` }
+  const note = `no change since baseline ${plan.baseline} — the file is byte-identical to the copy you already have${bom}`
+  return { ...base, mode: 'full', note, text: `no change since baseline ${plan.baseline} — nothing to send${bom}`, next: `mode=lines lines=[1,${total}] to get the whole text again` }
 }
 
 /**
@@ -2262,6 +2289,7 @@ export function readWith(source, request = {}) {
     // 符号索引只建一次：`map`/`digest`/`around` 本来就要用，而 `lines`/`search` 现在也要
     // （给裸行号附上可重新定位的引用）。没语言配置（未索引扩展名）时为 null，各处自行降级。
     const symbolsIndex = lang === null ? null : indexStructure(source, lang)
+    if (mode === 'probe') return renderProbe(base, source, lang, docKindOf(request.filePath), request)
     if (mode === 'map') return renderMap(base, source, lines, lang, request, symbolsIndex)
     if (mode === 'digest') return renderDigest(base, source, lines, lang, request, symbolsIndex)
     /**
@@ -2427,6 +2455,94 @@ export function readWith(source, request = {}) {
   return result
 }
 
+/**
+ * probe —— 只回答“这是什么文件”，不重复正文。
+ *
+ * 用途：调用方先判断“值不值得读”。行数、字节数、行尾风格、编码、语言/文档类型、
+ * 结构规模（符号数或节/键数）都在这一行里；正文一律不发。
+ *
+ * 它不是 `map` 的替代：`map` 给的是**可追问的目录**，`probe` 给的是一句**元信息摘要**。
+ * 代价也只有本地 IO——但对于“先看一眼再决定”这种意图，它省的是整份回执的 token。
+ */
+/** 1 symbols / 1 sections 这种复数噪声一律收掉（回执是给人读的）。 */
+const unitWord = (n, unit) => (n === 1 && unit.endsWith('s') ? unit.slice(0, -1) : unit)
+
+function renderProbe(base, source, lang, docKind, request) {
+  const bytes = Number.isSafeInteger(request.fileSize) ? request.fileSize : new TextEncoder().encode(source).length
+  const hasCrlf = source.includes('\r\n')
+  const hasLf = source.replaceAll('\r\n', '').includes('\n')
+  const lineEndings = hasCrlf && hasLf ? 'mixed' : hasCrlf ? 'crlf' : 'lf'
+  const encoding = typeof request.sourceEncoding === 'string' ? request.sourceEncoding : null
+  /**
+   * `lang` 是**语法配置对象**（`langOf` 的返回值），不是名字；直接拼进摘要会得到
+   * `[object Object]`（实测）。名字取扩展名，与 `langOf` 判定的是同一个东西。
+   */
+  const dot = typeof request.filePath === 'string' ? request.filePath.lastIndexOf('.') : -1
+  const language = lang !== null && dot >= 0 ? request.filePath.slice(dot + 1).toLowerCase() : null
+  let structure = null
+  if (lang !== null) {
+    const n = listSymbols(indexStructure(source, lang)).length
+    structure = `${n} ${unitWord(n, 'symbols')}`
+  } else if (docKind !== null) {
+    const index = indexDocument(source, docKind)
+    structure = `${index.entries.length} ${unitWord(index.entries.length, index.unit)}`
+  }
+  const parts = [`${base.totalLines} lines`, `${bytes} bytes`, lineEndings === 'mixed' ? 'mixed line endings' : lineEndings.toUpperCase()]
+  if (encoding !== null) parts.push(encoding)
+  if (language !== null) parts.push(language)
+  else if (docKind !== null) parts.push(docKind)
+  if (structure !== null) parts.push(structure)
+  return {
+    ...base,
+    mode: 'probe',
+    bytes,
+    lineEndings,
+    ...(encoding === null ? {} : { encoding }),
+    ...(language === null ? {} : { language }),
+    ...(docKind === null ? {} : { docKind }),
+    ...(structure === null ? {} : { structure }),
+    text: parts.join(' · '),
+    next: 'mode=map for a directory; mode=lines lines=[a,b] for a section; mode=full for every line',
+  }
+}
+
+/**
+ * 文档 / 配置的目录：行号 + 层级 + 名字，不复制正文。
+ *
+ * 与代码地图同一套预算与续读语义：超出预算时 `omitted` 点名区间，下一步是 `mode=lines`。
+ */
+function renderDocMap(base, lines, docKind, request) {
+  const index = indexDocument(lines.join('\n'), docKind)
+  const kindFilter = typeof request.kind === 'string' ? request.kind : null
+  const entries = kindFilter === null ? index.entries : index.entries.filter((entry) => entry.kind === kindFilter)
+  if (entries.length === 0) {
+    return {
+      ...base,
+      mode: 'map',
+      text: `${base.totalLines} lines · no ${index.unit} found in this ${docKind} file`,
+      ...(index.note === undefined ? {} : { note: index.note }),
+      next: 'use mode=full or mode=lines to read content',
+    }
+  }
+  const byKind = {}
+  for (const entry of entries) byKind[entry.kind] = (byKind[entry.kind] ?? 0) + 1
+  const header = `${base.totalLines} lines · ${index.entries.length} ${unitWord(index.entries.length, index.unit)} (${Object.entries(byKind).map(([kind, n]) => `${kind}:${n}`).join(' ')})`
+  const rows = entries.map((entry) => `${'  '.repeat(Math.max(0, entry.depth - 1))}${entry.name}  ${entry.startLine}-${entry.endLine}`)
+  const kept = fitWithin([header, ...rows].join('\n'), base.contentBudget)
+  const shown = Math.max(0, kept.kept - 1)
+  return {
+    ...base,
+    mode: 'map',
+    symbols: index.entries.length,
+    shown,
+    byKind,
+    text: kept.text,
+    ...(index.note === undefined ? {} : { note: index.note }),
+    ...(shown < rows.length ? { omitted: `${index.unit} ${shown + 1}..${rows.length} of ${rows.length} beyond the content budget; read them with mode=lines over their line range` } : {}),
+    next: 'mode=lines lines=[a,b] to read a section; mode=map kind=<kind> to filter',
+  }
+}
+
 /**
  * map —— 先给地图。
  *
@@ -2437,10 +2553,18 @@ export function readWith(source, request = {}) {
  */
 function renderMap(base, source, lines, lang, request, symbolsIndex = null) {
   if (lang === null) {
+    /**
+     * 文档 / 配置（.md/.json/.yaml/.toml）也应有目录：实测 22% 的读取目标是这几类扩展名
+     * （最近 62 个会话 / 1,836 次 read），而旧实现只回一句“unsupported extension”。
+     * 结构索引在 `doc-structure.mjs`；这里只负责渲染与续读。
+     */
+    const docKind = docKindOf(request.filePath)
+    if (docKind !== null) return renderDocMap(base, lines, docKind, request)
+    // 同上：正文进 `text`，否则 `metrics.chars` 为 0 而同一条回执的说明里写着实际字符数。
     return {
       ...base,
       mode: 'map',
-      note: `unsupported extension — no symbol index; ${base.totalLines} lines, ${source.length} chars`,
+      text: `unsupported extension — no symbol index; ${base.totalLines} lines, ${source.length} chars`,
       next: 'use mode=full or mode=lines to read content',
     }
   }

package/locator-lab/write-path.mjs

@@ -3099,7 +3099,13 @@ async function verifyWriteBack(service, target, written, displayPath, signal) {
   let actual
   try {
     if (level === 'bytes') {
-      expected = new TextEncoder().encode(written)
+      /**
+       * 期望字节由**提供方**回答（可选 `encodeFor`）：非 UTF-8 存储下，引擎不能假设
+       * `TextEncoder` 就是落盘字节。没有这个方法的提供方（DSH 壳）仍走 UTF-8，行为不变。
+       */
+      expected = typeof service.encodeFor === 'function'
+        ? Buffer.from(await service.encodeFor(target, written))
+        : new TextEncoder().encode(written)
       actual = await service.readByteRange(
         target,
         { offset: 0, length: expected.length + READBACK_PROBE_EXTRA_BYTES },
@@ -3190,14 +3196,25 @@ function errorCodeOf(error) {
  *
  * @throws PatchError('PATCH_UNOBSERVED')
  */
-export function requireObservedRevision({ displayPath, identityKey, content, byteOrderMark = false }) {
+export function requireObservedRevision({ displayPath, identityKey, content, byteOrderMark = false, allowBlindHint = false }) {
   const ledgerKey = ledgerIdentityKey(displayPath, identityKey)
   const observation = latestObservation(ledgerKey, { source: content })
   const currentToken = contentToken(content, byteOrderMark)
   if (observation !== null && observation.version === currentToken) return
   const changed = observation !== null
+  /**
+   * 回执里直接给**下一次调用**，而不是只说“先读”：实测 5 天内 22 次 PATCH_UNOBSERVED，
+   * 每次都要模型自己挑读法（多半选 full，5k+ 字符）。这里按当前内容的体量挑一个装得下预算
+   * 的模式；整份覆写还可以走已有的显式逃生口 `allow_unobserved`，把“读一遍再写”折成
+   * “一次带标记的写”——代价（unverified_region）写在回执里，而不是藏在 schema 描述里。
+   */
+  const readHint = content.length <= 6000 ? 'full' : 'map'
   throw new PatchError(
-    `cannot patch "${displayPath}": ${changed ? 'the file changed since your last read' : 'this file has not been read in this session'} — read it first (aura_basetools_read), then retry${changed ? ' against the current revision' : ''} — nothing was written`,
+    `cannot patch "${displayPath}": ${changed ? 'the file changed since your last read' : 'this file has not been read in this session'} — read it first (aura_basetools_read), then retry${changed ? ' against the current revision' : ''} — nothing was written` +
+      `\nnext: aura_basetools_read { file_path: "${displayPath}", mode: "${readHint}" } — then retry` +
+      (allowBlindHint
+        ? `\n      or pass allow_unobserved: true if this is a deliberate whole-file overwrite; the receipt will be marked unverified_region`
+        : ''),
     'PATCH_UNOBSERVED',
     {
       reason: changed ? 'changed-since-read' : 'never-read',
@@ -3273,6 +3290,8 @@ async function planEditToProvider(provider, request) {
       ...(request.identityKey === undefined ? {} : { identityKey: request.identityKey }),
       content,
       byteOrderMark: byteOrderMarks > 0,
+      // 只有整份覆写才有显式逃生口（`allow_unobserved`）；edit 的严格模式不提供它。
+      allowBlindHint: typeof request.wholeFile === 'string',
     })
   }
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aura-basetools",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Byte-exact read, edit and write tools for coding agents. Standalone CLI and MCP server; no DSH required. 面向 coding agent 的逐字节读写工具；独立 CLI / MCP，可选 DSH 适配器。",
   "license": "MIT",
   "type": "module",

package/test/doctor-test.mjs

@@ -49,6 +49,12 @@ say('=== A. 正常环境 ===')
   check('A4 所有检查项通过', (report?.checks ?? []).every((c) => c.ok === true), JSON.stringify((report?.checks ?? []).filter((c) => !c.ok)))
   check('A5 MCP 握手列出两个工具', /aura_basetools_read/.test(JSON.stringify(report?.checks)) && /aura_basetools_edit/.test(JSON.stringify(report?.checks)))
   check('A6 缓存目录真的被创建', fs.existsSync(cache), cache)
+  // strict 是“提示”而不是“检查项”：工具侧开不了它（那是 provider 配置），但装完就应该看得到怎么开。
+  check(
+    'A7 doctor 给出 strict 启用提示',
+    report?.strict?.compatible === true && typeof report?.strict?.deepseek === 'string' && typeof report?.strict?.convert === 'string',
+    JSON.stringify(report?.strict).slice(0, 140),
+  )
 }
 
 say('')