aura-basetools 0.7.0 → 0.13.0

package/bin/aura.mjs

@@ -2,19 +2,23 @@
 /**
  * aura CLI（薄壳）：参数解析 → `lib/ops.mjs` → 一行 JSON。
  *
- *   aura read  --file F [--mode …] [--around X] [--lines a,b] [--search S] [--since V] [--max-chars N]
- *   aura edit  --file F (--hunks '<json>' | --hunks-file P) [--dry-run] [--create <文本|@文件>]
- *   aura read  --targets '[...]|@spec.json'                    一次读多个目标（与 --file 互斥）
- *   aura edit  --targets '[...]|@spec.json'                    一次改多个文件（与 --file 互斥；任一规划失败 ⇒ 零写入）
- *   aura undo [--id <事务 id>] [--force]                      撤销最近一次/指定写事务
- *   aura transactions                                         列出当前工作区写事务
- *   aura mcp
+ *   aura basetools read  --file F [--mode …] [--around X] [--lines a,b] [--search S] [--since V] [--max-chars N]
+ *   aura basetools edit  --file F (--hunks '<json>' | --hunks-file P) [--dry-run] [--create <文本|@文件>]
+ *   aura basetools read  --targets '[...]|@spec.json'                    一次读多个目标（与 --file 互斥）
+ *   aura basetools edit  --targets '[...]|@spec.json'                    一次改多个文件（与 --file 互斥；任一规划失败 ⇒ 零写入）
+ *   aura basetools undo [--id <事务 id>] [--force]                      撤销最近一次/指定写事务
+ *   aura basetools transactions                                         列出当前工作区写事务
+ *   aura basetools mcp
  *   aura --help | --version
  *
  * 退出码：0 成功；2 结构化拒绝（回执带 code/next 一类信息）；1 用法错误。
  */
 import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
 import process from 'node:process'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
 import {
   openProvider,
   readEnvelope,
@@ -25,9 +29,13 @@ import {
   editManyEnvelope,
   undoEnvelope,
   transactionsEnvelope,
+  capabilitiesEnvelope,
+  writeEnvelope,
   assertReadTargets,
   assertEditTargets,
   assertKnownArgs,
+  MT_READ_ELEMENT_KEYS,
+  MT_EDIT_ELEMENT_KEYS,
   errorEvidence,
 } from '../lib/ops.mjs'
 // `flatHunk` 是 `locator-lab/args.mjs` 里那一份容错规则（DSH 壳与 CLI 共用），但**不在这里定位引擎**：
@@ -42,7 +50,17 @@ const VERSION = (() => {
     return 'dev'
   }
 })()
-const argv = process.argv.slice(2)
+const rootArgv = process.argv.slice(2)
+/**
+ * CLI 命名空间：`aura basetools <verb>`。
+ *
+ * 顶层 `read` / `edit` / `write` ... 不再保留别名：以后会有多个 aura 产品共用 `aura`
+ * 这个入口，顶层动词迟早撞名。命名空间只改**调用写法**，引擎与回执不变。
+ */
+let argv = rootArgv
+const namespaced = rootArgv[0] === 'basetools'
+if (namespaced) argv = argv.slice(1)
+let command = argv[0]
 
 /**
 /**
@@ -56,9 +74,72 @@ const argv = process.argv.slice(2)
  * 有了这份名单，“下一个是已知布尔旗标”才当没带值，**其它以 `--` 开头的东西都当值**。
  * 代价是名单要维护；收益是那个静默丢值的路径从根上消失，而不是靠叫用户改写法。
  */
-const BOOLEAN_FLAGS = new Set(['pretty', 'dry-run', 'transaction', 'force'])
+const BOOLEAN_FLAGS = new Set(['pretty', 'dry-run', 'plan', 'transaction', 'force', 'no-overwrite', 'replace-all', 'require-observation', 'allow-unobserved', 'json'])
 const isBooleanFlag = (token) => typeof token === 'string' && BOOLEAN_FLAGS.has(token.replace(/^--/, ''))
 
+/**
+ * 每个命令认识的旗标（唯一一份）。`flag()` 只读取它要找的那个名字；**不在这里的 `--xxx`
+ * 以前会被静默忽略**——`--dryrun` 于是变成“没传 dry-run”的一次真写盘。
+ *
+ * 这里同时承担两件事：未知旗标拒绝（`ARGS_UNKNOWN_KEY`）与扫描时的“这个旗标要不要吃值”。
+ * 合法键名与命令实现放在同一张表里，新增旗标不会出现“parser 认、校验不认”的分叉。
+ */
+const COMMAND_FLAGS = {
+  read: {
+    value: ['cwd', 'file', 'targets', 'mode', 'around', 'lines', 'start-line', 'end-line', 'search', 'since', 'context', 'kind', 'budget', 'max-chars', 'offset', 'limit'],
+    bool: ['pretty'],
+  },
+  edit: {
+    value: ['cwd', 'file', 'targets', 'hunks', 'hunks-file', 'create', 'target', 'intent', 'lines', 'start-line', 'end-line', 'line-cue', 'anchor', 'old', 'context', 'handle', 'line', 'position', 'replace', 'expect', 'near', 'eol'],
+    bool: ['pretty', 'dry-run', 'plan', 'transaction', 'replace-all', 'require-observation'],
+  },
+  write: {
+    value: ['cwd', 'file', 'content', 'eol'],
+    bool: ['pretty', 'dry-run', 'plan', 'transaction', 'no-overwrite', 'allow-unobserved'],
+  },
+  undo: { value: ['cwd', 'id'], bool: ['pretty', 'force'] },
+  transactions: { value: ['cwd'], bool: ['pretty'] },
+  doctor: { value: ['cwd'], bool: ['pretty', 'json'] },
+  capabilities: { value: ['cwd'], bool: ['pretty'] },
+  mcp: { value: ['cwd'], bool: ['pretty'] },
+}
+
+/**
+ * 扫一遍命令后的 argv：未知旗标 / 裸位置参数 / 布尔旗标带值 一律拒绝。
+ *
+ * **值旗标吃下一个 token**（与 `flag()` 的既有语义一致）：`--content "---"` 这种以 `--`
+ * 开头的正文不能被误判成旗标。没有值的值旗标不在这一层判（各命令会给出自己的错误）。
+ */
+function validateCommandFlags(command, tokens) {
+  const spec = COMMAND_FLAGS[command]
+  if (spec === undefined) return undefined
+  const valueFlags = new Set(spec.value)
+  const boolFlags = new Set(spec.bool)
+  for (let i = 0; i < tokens.length; i += 1) {
+    const token = tokens[i]
+    if (typeof token !== 'string' || !token.startsWith('--')) {
+      return `unexpected argument ${JSON.stringify(token)} — this command takes flags only`
+    }
+    const eq = token.indexOf('=')
+    const name = token.slice(2, eq === -1 ? undefined : eq)
+    if (boolFlags.has(name)) {
+      if (eq !== -1) return `--${name} is a boolean flag and takes no value (got ${JSON.stringify(token.slice(eq + 1))})`
+      continue
+    }
+    if (!valueFlags.has(name)) {
+      const legal = [...spec.value, ...spec.bool].sort().map((flag) => `--${flag}`).join(', ')
+      return `unknown flag --${name}; this command accepts: ${legal}`
+    }
+    if (eq === -1) {
+      const next = tokens[i + 1]
+      // 与 `flag()` 同一条：下一个 token 若是本命令的布尔旗标，就当“这个值旗标没带值”，
+      // 不去吃它（否则 `--content --dry-run` 会把 dry-run 藏进正文里）。
+      if (next !== undefined && !(next.startsWith('--') && boolFlags.has(next.slice(2)))) i += 1
+    }
+  }
+  return undefined
+}
+
 const flag = (name, fallback = undefined) => {
   const i = argv.indexOf(`--${name}`)
   if (i >= 0) {
@@ -73,38 +154,51 @@ const emit = (obj, code) => {
   process.stdout.write(`${has('pretty') ? JSON.stringify(obj, null, 2) : JSON.stringify(obj)}\n`)
   process.exit(code)
 }
+/** `@文件` 参数读不到时回一条 JSON 回执，而不是把 Node 栈抛给调用方。 */
+const readArgumentFile = (target, flagName) => {
+  try {
+    return fs.readFileSync(target, 'utf8')
+  } catch (error) {
+    emit({ ok: false, error: `${flagName} 读不到 ${target}：${error.message}`, code: 'USAGE' }, 1)
+  }
+}
 
 const USAGE = [
   `aura ${VERSION} —— 按意图读写文件（独立版：不依赖 DeepSeek Harness，Windows / macOS / Linux 同形）`,
   '',
-  '  aura read  --file <路径> [--mode map|digest|full|around|lines|search|changed]',
+  '  aura basetools read  --file <路径> [--mode map|digest|full|around|lines|search|changed]',
   '             [--around <符号>] [--lines <a,b>|<a-b>|<n>] [--start-line <n> --end-line <n>]',
-  '             [--search <子串>] [--since <令牌>] [--max-chars <n>]',
+  '             [--search <子串>] [--context <n>] [--kind <类型>] [--budget <字符数>] [--since <令牌>] [--max-chars <n>] [--offset <n> --limit <n>]',
   // `--file` 指向**目录**时直接给一张仓库地图（模块/目录/依赖方向），不需要额外旗标。
   '             （--file 传目录 ⇒ 仓库地图：模块清单 + 目录骨架 + 被依赖最多的模块 + 入口点）',
-  '  aura read  --targets <json|@文件>                               # 一次读多个目标（≤32 项；与 --file 互斥）',
-  '  aura edit  --targets <json|@文件> [--dry-run]                  # 一次改多个文件（先全量规划，任一失败则零写入）',
-  "  aura edit  --file <路径> --create <内容|@文件>                     # 建文件（不必再给 --hunks）",
-  "  aura edit  --file <路径> (--hunks '<json>' | --hunks-file <路径>) [--dry-run]",
-  '   aura edit  --file <路径> --lines <a,b> --replace <文本> [--expect <文本>] [--near <n>]',
-  "              （只改一处时不必包成 JSON：--target / --lines / --start-line+--end-line / --line-cue / --anchor 任选其一）",
+  '  aura basetools read  --targets <json|@文件>                               # 一次读多个目标（≤32 项；与 --file 互斥）',
+  '  aura basetools edit  --targets <json|@文件> [--dry-run|--plan]          # 一次改多个文件（先全量规划，任一失败则零写入）',
+  "  aura basetools edit  --file <路径> --create <内容|@文件>                     # 建文件（不必再给 --hunks）",
+  "  aura basetools edit  --file <路径> (--hunks '<json>' | --hunks-file <路径>) [--dry-run|--plan] [--eol auto|preserve|lf|crlf] [--require-observation]",
+  '   aura basetools edit  --file <路径> --lines <a,b> --replace <文本> [--expect <文本>] [--near <n>]',
+  '   aura basetools edit  --file <路径> --old <原文> --replace <文本> --replace-all        # 改全部非重叠出现',
+  "              （只改一处时不必包成 JSON：--target / --intent / --lines / --start-line+--end-line / --line-cue / --anchor 任选其一）",
   // 句柄（fs-contract-v2 §5）：读侧发的柄 + 三种定位写法。下面三行是三种**用法**，不是三种键。
-  '   aura edit  --file <路径> --handle <h…> --replace <文本>                          # 整段替换：区间由柄定，不靠转述',
-  '   aura edit  --file <路径> --handle <h…> --line <段内行号> --replace <文本>            # 只换区间内第 k 行（1-based，从区间首行数起）',
-  '   aura edit  --file <路径> --handle <h…> --position before|after --replace <文本>  # 在区间边界插入，区间本身不动',
+  '   aura basetools edit  --file <路径> --handle <h…> --replace <文本>                          # 整段替换：区间由柄定，不靠转述',
+  '   aura basetools edit  --file <路径> --handle <h…> --line <段内行号> --replace <文本>            # 只换区间内第 k 行（1-based，从区间首行数起）',
+  '   aura basetools edit  --file <路径> --handle <h…> --position before|after --replace <文本>  # 在区间边界插入，区间本身不动',
   "              （--line / --position 是从属键：只有与 --handle 同时给才成立，单独给不构成一次编辑）",
-  '  aura mcp                    启动 MCP stdio 服务',
+  '  aura basetools mcp                    启动 MCP stdio 服务',
+  '  aura basetools write --file <路径> --content <文本|@文件> [--no-overwrite] [--dry-run|--plan] [--transaction] [--allow-unobserved] [--eol auto|preserve|lf|crlf]',
+  '             （覆写默认要求先读过这一版；--allow-unobserved 才允许盲写）',
+  '  aura basetools doctor [--json]        自检：Node/版本/MCP 握手/缓存与锁目录可写',
+  '  aura basetools capabilities [--pretty] 能力清单：读模式/地址档/语言/限制（JSON）',
   '  aura --help | --version',
   '',
-  'hunks 形状：[{"target":"符号名"|"lines":[a,b]|"line_cue":"唯一词"|"anchor":"记得的原文",',
+  'hunks 形状：[{"target":"符号名"|"intent":"模糊意图（符号片段/短语/近似原文）"|"lines":[a,b]|"line_cue":"唯一词"|"anchor":"记得的原文",',
   '              "replace":"替换文本","expect":"该处应是什么","near":行号}]',
   '',
   '例：',
-  "  aura edit --file a.mjs --hunks '[{\"lines\":[5,5],\"replace\":\"x\"}]'   # 单引号包住整段 JSON",
-  '  aura edit --file a.mjs --hunks-file hunks.json                        # 内容走文件，绕开引号',
-  '  aura edit --file new.md --create @body.md                             # @文件 ——推荐给长内容',
-  '  aura edit --file new.md --create=---                                  # 值以 -- 开头时必须用 = 形式',
-  '  aura read --file ./src                                                # 目录 ⇒ 仓库地图',
+  "  aura basetools edit --file a.mjs --hunks '[{\"lines\":[5,5],\"replace\":\"x\"}]'   # 单引号包住整段 JSON",
+  '  aura basetools edit --file a.mjs --hunks-file hunks.json                        # 内容走文件，绕开引号',
+  '  aura basetools edit --file new.md --create @body.md                             # @文件 ——推荐给长内容',
+  '  aura basetools edit --file new.md --create=---                                  # 值以 -- 开头时必须用 = 形式',
+  '  aura basetools read --file ./src                                                # 目录 ⇒ 仓库地图',
   '',
   'PowerShell 两个已踩过的坑：',
   '  · 反引号 `n 写进 JSON 字符串会变成控制字符（JSON 不允许）⇒ 用 --hunks-file 或单引号 heredoc；',
@@ -126,10 +220,10 @@ const USAGE = [
  * （于是“两个都给”由那条唯一判据说话）、把引擎抛的参数面错接到 exit 1 那一档。
  *
  * @param assertShape - 读侧 `assertReadTargets`、写侧 `assertEditTargets`（同一个判据，两套提示语）
- * @param toolName - 回执里点名的工具（`aura_read` / `aura_edit`）
+ * @param toolName - 回执里点名的工具（`aura_basetools_read` / `aura_basetools_edit`）
  * @returns `{ targets, dryRun }`（逐项判决在引擎里，这里只递参数）
  */
-const engineTargets = (assertShape, toolName) => {
+const engineTargets = (assertShape, toolName, elementKeys) => {
   const raw = flag('targets')
   const where = typeof raw === 'string' && raw.startsWith('@') ? `--targets @${raw.slice(1)}` : '--targets'
   if (typeof raw !== 'string') {
@@ -183,7 +277,7 @@ const engineTargets = (assertShape, toolName) => {
   if (typeof flag('file') === 'string') source.file_path = flag('file')
   let targets
   try {
-    targets = assertShape(source, { toolName })
+    targets = assertShape(source, { toolName, elementKeys })
   } catch (error) {
     refuseShape(where, error)
   }
@@ -211,9 +305,28 @@ const refuseShape = (where, error) =>
     1,
   )
 
-const command = argv[0]
 if (command === undefined || command === '--help' || command === '-h') emit({ ok: true, usage: USAGE }, 0)
 if (command === '--version' || command === '-v') emit({ ok: true, version: VERSION }, 0)
+/**
+ * 旧顶层动词只给**迁移提示**，不再作为别名执行——保留别名等于保留未来的撞名。
+ * 只提示、不执行：`aura basetools read` 不会偷偷改文件。
+ */
+const MOVED_COMMANDS = new Set(['read', 'outline', 'edit', 'write', 'undo', 'transactions', 'mcp', 'doctor', 'capabilities'])
+if (!namespaced && MOVED_COMMANDS.has(command)) {
+  emit(
+    {
+      ok: false,
+      error: `command moved: use \`aura basetools ${command}\` (top-level verbs are reserved for product namespaces)`,
+      code: 'USAGE',
+      shape: 'CLI_NAMESPACE_REQUIRED',
+    },
+    1,
+  )
+}
+const flagProblem = validateCommandFlags(command, argv.slice(1))
+if (flagProblem !== undefined) {
+  emit({ ok: false, error: flagProblem, code: 'USAGE', shape: 'ARGS_UNKNOWN_KEY' }, 1)
+}
 if (command === 'mcp') {
   const { serve } = await import('./aura-mcp.mjs')
   await serve()
@@ -222,6 +335,34 @@ if (command === 'mcp') {
 
 const provider = openProvider(typeof flag('cwd') === 'string' ? flag('cwd') : process.cwd())
 
+if (command === 'capabilities') {
+  const env = { ok: true, version: VERSION, ...capabilitiesEnvelope() }
+  process.stdout.write(`${JSON.stringify(env, null, has('pretty') ? 2 : 0)}\n`)
+  process.exit(0)
+}
+
+if (command === 'write') {
+  const file = flag('file')
+  if (typeof file !== 'string') emit({ ok: false, error: 'write 需要 --file <路径>', code: 'USAGE' }, 1)
+  const raw = flag('content')
+  if (typeof raw !== 'string') emit({ ok: false, error: 'write 需要 --content <文本|@文件>', code: 'USAGE' }, 1)
+  const content = raw.startsWith('@') ? readArgumentFile(raw.slice(1), '--content') : raw
+  const eol = flag('eol')
+  if (eol !== undefined && typeof eol !== 'string') {
+    emit({ ok: false, error: 'write 的 --eol 需要跟一个值：auto|preserve|lf|crlf', code: 'USAGE' }, 1)
+  }
+  const env = await writeEnvelope(provider, {
+    file,
+    content,
+    dryRun: has('dry-run') || has('plan'),
+    noOverwrite: has('no-overwrite'),
+    includeTransaction: has('transaction'),
+    allowUnobserved: has('allow-unobserved'),
+    ...(typeof eol === 'string' ? { eol } : {}),
+  })
+  emit(env, env.ok ? 0 : 2)
+}
+
 if (command === 'undo') {
   const env = await undoEnvelope(provider, {
     id: typeof flag('id') === 'string' ? flag('id') : undefined,
@@ -235,13 +376,77 @@ if (command === 'transactions') {
   emit(env, 0)
 }
 
+if (command === 'doctor') {
+  /**
+   * `aura basetools doctor`：把“装完能不能用”的机械检查放在 CLI 自己身上。
+   * 与安装器的 `--doctor` 不同：这里不假设 DSH profile，只查这个包自己的入口、MCP 握手与缓存目录。
+   */
+  const checks = []
+  const add = (id, ok, detail) => checks.push({ id, ok, detail })
+  const nodeMajor = Number.parseInt(process.versions.node.split('.')[0], 10)
+  add('node', nodeMajor >= 18, `node ${process.versions.node} (need >=18)`)
+  add('version', typeof VERSION === 'string' && VERSION.length > 0, VERSION)
+  const mcpPath = fileURLToPath(new URL('./aura-mcp.mjs', import.meta.url))
+  add('mcp-bin', fs.existsSync(mcpPath), mcpPath)
+  const cacheDir = process.env.AURA_CACHE_DIR ?? path.join(os.homedir(), '.aura')
+  if (fs.existsSync(mcpPath)) {
+    const frames = [
+      JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'aura-doctor', version: '1' } } }),
+      JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }),
+      JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} }),
+      '',
+    ].join('\n')
+    const res = spawnSync(process.execPath, [mcpPath], {
+      input: frames,
+      encoding: 'utf8',
+      timeout: 30000,
+      env: { ...process.env, AURA_CACHE_DIR: cacheDir },
+    })
+    const tools = String(res.stdout ?? '').split('\n').flatMap((line) => {
+      try { return JSON.parse(line).result?.tools?.map((tool) => tool.name) ?? [] } catch { return [] }
+    })
+    add('mcp-handshake', res.status === 0 && tools.includes('aura_basetools_read') && tools.includes('aura_basetools_edit'), `exit=${res.status} tools=${tools.join(',') || '(none)'}`)
+  } else {
+    add('mcp-handshake', false, 'skipped: mcp bin missing')
+  }
+  const probeWritable = (dir, id) => {
+    try {
+      fs.mkdirSync(dir, { recursive: true })
+      const probe = path.join(dir, `.doctor-${process.pid}`)
+      fs.writeFileSync(probe, 'ok')
+      const text = fs.readFileSync(probe, 'utf8')
+      fs.rmSync(probe, { force: true })
+      add(id, text === 'ok', dir)
+    } catch (error) {
+      add(id, false, `${dir}: ${String(error?.message ?? error)}`)
+    }
+  }
+  probeWritable(cacheDir, 'cache-writable')
+  probeWritable(path.join(cacheDir, 'locks'), 'lock-writable')
+  const ok = checks.every((check) => check.ok)
+  const report = {
+    ok,
+    version: VERSION,
+    node: process.versions.node,
+    checks,
+    ...(process.env.AURA_NO_LOCK === '1' ? { notes: ['AURA_NO_LOCK=1: workspace lock is disabled'] } : {}),
+  }
+  if (has('json')) {
+    process.stdout.write(`${JSON.stringify(report)}\n`)
+    process.exit(ok ? 0 : 2)
+  }
+  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.exit(ok ? 0 : 2)
+}
+
 if (command === 'read' || command === 'outline') {
   /**
    * 多目标（fs-contract-v2 §2.1）：`--targets` 在场 ⇒ 引擎的批入口。
    * `--file` 那条路一个字不动（就在下面，含它自己的 `USAGE` 与 `outline ⇒ map`）。
    */
   if (has('targets')) {
-    const { targets } = engineTargets(assertReadTargets, 'aura_read')
+    const { targets } = engineTargets(assertReadTargets, 'aura_basetools_read', MT_READ_ELEMENT_KEYS)
     const env = await readManyWith(provider, targets)
     emit(env, env.ok ? 0 : 2)
   }
@@ -262,7 +467,13 @@ if (command === 'read' || command === 'outline') {
     start_line: flag('start-line'),
     end_line: flag('end-line'),
     search: flag('search'),
+    context: typeof flag('context') === 'string' ? Number(flag('context')) : undefined,
+    kind: typeof flag('kind') === 'string' ? flag('kind') : undefined,
+    budget: typeof flag('budget') === 'string' ? Number(flag('budget')) : undefined,
     since: flag('since'),
+    // 0.10.0：内置 Read 的分页形状（offset 0-based；limit 行数；默认 2000）。
+    offset: typeof flag('offset') === 'string' ? Number(flag('offset')) : undefined,
+    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,
   })
@@ -277,11 +488,12 @@ if (command === 'edit') {
    * `dryRun` 两个来源都认：spec 里的 `dryRun`（与 DSH 壳同名）与既有的 `--dry-run` 旗标。
    */
   if (has('targets')) {
-    const spec = engineTargets(assertEditTargets, 'aura_edit')
+    const spec = engineTargets(assertEditTargets, 'aura_basetools_edit', MT_EDIT_ELEMENT_KEYS)
     const env = await editManyEnvelope(provider, {
       targets: spec.targets,
-      dryRun: has('dry-run') || spec.dryRun,
+      dryRun: has('dry-run') || has('plan') || spec.dryRun,
       includeTransaction: has('transaction'),
+      ...(has('require-observation') ? { requireObservation: true } : {}),
     })
     emit(env, env.ok ? 0 : 2)
   }
@@ -297,6 +509,8 @@ if (command === 'edit') {
    */
   const flat = flatHunk({
     target: flag('target'),
+    // 意图地址（T16）：`--intent 'config loader'` 一句话定位一处改动，不要求符号全名或原文。
+    intent: flag('intent'),
     lines: flag('lines'),
     start_line: flag('start-line'),
     end_line: flag('end-line'),
@@ -309,8 +523,13 @@ if (command === 'edit') {
     handle: flag('handle'),
     line: flag('line'),
     position: flag('position'),
+    // 内容地址（0.10.2）：平铺 CLI 也能直接给逐字原文；`--replace-all` 用它改全部出现。
+    old: flag('old'),
+    context: flag('context'),
     replace: flag('replace'),
     expect: flag('expect'),
+    eol: flag('eol'),
+    replace_all: has('replace-all') ? true : undefined,
     // 旗标值天然是字符串：`--near 42` ⇒ `'42'`。收敛层只认整数，所以在这里转一次
     near: typeof flag('near') === 'string' && flag('near').trim() !== '' ? Number(flag('near')) : flag('near'),
   })
@@ -374,7 +593,7 @@ if (command === 'edit') {
       {
         ok: false,
         error:
-          'edit 需要 --hunks/--hunks-file，或平铺一组地址旗标（--target / --lines / --start-line+--end-line / --line-cue / --anchor / --handle（配 --line 或 --position），外加 --replace），或 --create <整份内容>',
+          'edit 需要 --hunks/--hunks-file，或平铺一组地址旗标（--target / --intent / --lines / --start-line+--end-line / --line-cue / --anchor / --handle（配 --line 或 --position），外加 --replace），或 --create <整份内容>',
         code: 'USAGE',
       },
       1,
@@ -382,13 +601,14 @@ if (command === 'edit') {
   }
   const createRaw = flag('create')
   // `@文件` 形式：内容完全不经过命令行引号。创建含引号/换行/front matter 的内容时这是最稳的路。
-  const create = typeof createRaw === 'string' && createRaw.startsWith('@') ? fs.readFileSync(createRaw.slice(1), 'utf8') : createRaw
+  const create = typeof createRaw === 'string' && createRaw.startsWith('@') ? readArgumentFile(createRaw.slice(1), '--create') : createRaw
   const env = await editEnvelope(provider, {
     file,
     hunks: hunks ?? [],
-    dryRun: has('dry-run'),
+    dryRun: has('dry-run') || has('plan'),
     create,
     includeTransaction: has('transaction'),
+    ...(has('require-observation') ? { requireObservation: true } : {}),
   })
   emit(env, env.ok ? 0 : 2)
 }

package/lib/observation-store.mjs

@@ -147,6 +147,100 @@ export function createDiskStore(file = observationsPath()) {
     for (const [spelling, target] of aliases) if (!alive.has(target)) aliases.delete(spelling)
   }
 
+  /**
+   * 落盘状态的新鲜度标记。多个 CLI/MCP 进程会同时读写同一个 `observations.json`；
+   * 旧实现“启动时读一次、结束时整份写回”会让后写的进程覆盖先写的观测（并发读两个文件，
+   * 最后只剩一条）——严格新鲜度随后对刚读过的文件报 `never-read`。
+   */
+  let lastStamp = null
+  const fileStamp = () => {
+    try {
+      const st = fs.statSync(file)
+      return `${st.mtimeMs}:${st.size}`
+    } catch {
+      return 'missing'
+    }
+  }
+  lastStamp = fileStamp()
+
+  /** 从盘上重新读一份合法缓存；坏文件/不存在都当空（“没观测过”是合法状态）。 */
+  const loadDisk = () => {
+    try {
+      const raw = JSON.parse(fs.readFileSync(file, 'utf8'))
+      if (raw !== null && typeof raw === 'object' && Array.isArray(raw.seen) && typeof raw.latest === 'object') return raw
+    } catch {
+      /* 落到 null */
+    }
+    return null
+  }
+
+  /** 把盘上条目并进内存：seen 按 key 去重（本地优先），latest/aliases 本地优先。 */
+  const mergeDisk = (disk) => {
+    if (disk === null) return
+    const seen = new Map()
+    for (const entry of disk.seen) seen.set(entry.key, entry)
+    for (const entry of data.seen) seen.set(entry.key, entry)
+    data.seen = [...seen.values()]
+    data.latest = { ...disk.latest, ...data.latest }
+    if (typeof disk.aliases === 'object' && disk.aliases !== null) {
+      for (const [spelling, target] of Object.entries(disk.aliases)) {
+        if (!aliases.has(spelling)) aliases.set(spelling, target)
+      }
+    }
+  }
+
+  /** 查询前刷新：长进程（MCP）也能看见别的进程刚写下的观测。 */
+  const refresh = () => {
+    const stamp = fileStamp()
+    if (stamp === lastStamp) return
+    mergeDisk(loadDisk())
+    lastStamp = stamp
+  }
+
+  /**
+   * 写锁：同一个缓存文件同时只允许一个进程做 read-merge-write。
+   *
+   * 锁是**旁路文件**（`observations.json.lock`，`wx` 原子创建），不引入平台分支；
+   * 陈旧锁（进程崩溃留下）超过 `LOCK_STALE_MS` 后清掉。拿不到锁时仍做一次尽力而为的
+   * 合并写入——缓存损坏/丢一条都不该让编辑失败，但正常情况下不会走到这条。
+   */
+  const LOCK_STALE_MS = 5000
+  const LOCK_WAIT_MS = 2000
+  const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
+  const acquireLock = () => {
+    const lock = `${file}.lock`
+    const deadline = Date.now() + LOCK_WAIT_MS
+    try {
+      fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 })
+    } catch {
+      return null
+    }
+    for (;;) {
+      try {
+        const fd = fs.openSync(lock, 'wx', 0o600)
+        try { fs.writeFileSync(fd, String(process.pid)) } finally { fs.closeSync(fd) }
+        return lock
+      } catch (error) {
+        if (error?.code !== 'EEXIST') return null
+        try {
+          const st = fs.statSync(lock)
+          if (Date.now() - st.mtimeMs > LOCK_STALE_MS) {
+            fs.unlinkSync(lock)
+            continue
+          }
+        } catch {
+          continue
+        }
+        if (Date.now() >= deadline) return null
+        sleep(10)
+      }
+    }
+  }
+  const releaseLock = (lock) => {
+    if (lock === null) return
+    try { fs.unlinkSync(lock) } catch { /* 已被清理：没有需要撤销的状态 */ }
+  }
+
   const save = () => {
     try {
       const dir = path.dirname(file)
@@ -161,6 +255,7 @@ export function createDiskStore(file = observationsPath()) {
         try { fs.chmodSync(tmp, 0o600) } catch { /* 同上 */ }
       }
       fs.renameSync(tmp, file)
+      lastStamp = fileStamp()
       if (path.sep !== '\\') {
         try { fs.chmodSync(file, 0o600) } catch { /* 同上 */ }
       }
@@ -172,21 +267,44 @@ export function createDiskStore(file = observationsPath()) {
 
   return {
     remember(filePath, version, source, byteOrderMark = false) {
-      if (typeof source !== 'string' || source.length > MAX_SOURCE) return
-      const accounted = accountKeys(filePath, aliases)
-      if (accounted.canonical !== null) aliases.set(accounted.canonical, accounted.key)
-      const key = `${accounted.key}@${version}`
-      data.seen = data.seen.filter((e) => e.key !== key)
-      data.seen.push({ key, version, source, byteOrderMark: byteOrderMark === true })
-      while (data.seen.length > LIMIT) data.seen.shift()
-      data.latest[accounted.key] = key
-      // 指针指向已被淘汰的条目时一并清掉：留着它只会让"最近观测"指向不存在的全文
-      const alive = new Set(data.seen.map((e) => e.key))
-      for (const [p, k] of Object.entries(data.latest)) if (!alive.has(k)) delete data.latest[p]
-      dropDanglingAliases()
-      save()
+      if (typeof source !== 'string') return
+      /**
+       * 超过 `MAX_SOURCE` 的文件**仍然记令牌**，只是不存全文。
+       *
+       * 旧行为是整条丢掉，于是严格新鲜度（`requireObservedRevision`）对大文件永远返回
+       * `never-read`——而它要求的恢复动作（先读一次）根本不可能成功。令牌足够回答
+       * “这一版读过没有”；区域级闸门拿不到全文时如实退回 `basis:'none'`（见 `regionGate`）。
+       */
+      const omitted = source.length > MAX_SOURCE
+      const lock = acquireLock()
+      try {
+        // 先合并盘上条目，再算键与写入：否则两个并发进程会各自用旧快照覆盖对方。
+        mergeDisk(loadDisk())
+        const accounted = accountKeys(filePath, aliases)
+        if (accounted.canonical !== null) aliases.set(accounted.canonical, accounted.key)
+        const key = `${accounted.key}@${version}`
+        data.seen = data.seen.filter((e) => e.key !== key)
+        data.seen.push({
+          key,
+          version,
+          source: omitted ? null : source,
+          ...(omitted ? { source_omitted: true } : {}),
+          byteOrderMark: byteOrderMark === true,
+          at: Date.now(),
+        })
+        while (data.seen.length > LIMIT) data.seen.shift()
+        data.latest[accounted.key] = key
+        // 指针指向已被淘汰的条目时一并清掉：留着它只会让"最近观测"指向不存在的全文
+        const alive = new Set(data.seen.map((e) => e.key))
+        for (const [p, k] of Object.entries(data.latest)) if (!alive.has(k)) delete data.latest[p]
+        dropDanglingAliases()
+        save()
+      } finally {
+        releaseLock(lock)
+      }
     },
     latest(filePath) {
+      refresh()
       /**
        * 快路：**精确键**命中就直接返回（引擎传进来的通常是它自己登记过的那个键）。
        * 只有查不到时才用文件系统事实再问一次"这个写法是不是盘上那一份" —— 于是常见形态下
@@ -203,16 +321,27 @@ export function createDiskStore(file = observationsPath()) {
       if (stored === undefined) return null
       const entry = data.seen.find((e) => e.key === stored)
       if (entry === undefined) return null
-      return { version: entry.version, source: entry.source, byteOrderMark: entry.byteOrderMark === true }
+      return {
+        version: entry.version,
+        source: entry.source,
+        byteOrderMark: entry.byteOrderMark === true,
+        source_omitted: entry.source_omitted === true,
+      }
     },
     entry(filePath, version) {
+      refresh()
       const direct = findEntry(filePath, version)
-      if (direct !== null) return { source: direct.source, byteOrderMark: direct.byteOrderMark === true }
+      if (direct !== null) {
+        return { source: direct.source, byteOrderMark: direct.byteOrderMark === true, source_omitted: direct.source_omitted === true }
+      }
       const accounted = accountKeys(filePath, aliases)
       const entry = findEntry(accounted.key, version) ?? (accounted.canonical === null ? null : findEntry(accounted.canonical, version))
-      return entry === null ? null : { source: entry.source, byteOrderMark: entry.byteOrderMark === true }
+      return entry === null
+        ? null
+        : { source: entry.source, byteOrderMark: entry.byteOrderMark === true, source_omitted: entry.source_omitted === true }
     },
     recall(filePath, version) {
+      refresh()
       const direct = findEntry(filePath, version)
       if (direct !== null) return direct.source
       const accounted = accountKeys(filePath, aliases)
@@ -227,10 +356,14 @@ export function createDiskStore(file = observationsPath()) {
      * 模型手上的行号来自更早的一版，且没有任何东西能替它发现这件事。
      */
     has(filePath, version) {
+      refresh()
       if (findEntry(filePath, version) !== null) return true
       const accounted = accountKeys(filePath, aliases)
       return findEntry(accounted.key, version) !== null || (accounted.canonical !== null && findEntry(accounted.canonical, version) !== null)
     },
-    count: () => data.seen.length,
+    count: () => {
+      refresh()
+      return data.seen.length
+    },
   }
 }