@flotiarenor/dsh-tool-text-editor 1.0.0 → 1.1.0

package/README.md

@@ -17,7 +17,9 @@ byte by default) and `writeText` does not restore a file's line-ending style.
 
 On top of fidelity: **unified diffs** (with a `dry_run` preview), **automatic backups**, an **edit
 ledger**, **`grep` / `lines` anchors** so old text never has to be copied by hand, **ambiguity
-refusal**, and **near-miss candidates** when an anchor does not match.
+refusal**, **near-miss candidates** when an anchor does not match, and a **token-budgeted result
+text**: the model sees one stat line plus a line-budgeted diff body, while the full diff goes to the
+UI card (see "Result text and the token budget").
 
 ## Implementation and requirements
 
@@ -79,17 +81,34 @@ Both installs may coexist: the preset layer shadows the host layer with an ident
 `file_path` and `new_text` are required; give **exactly one** anchor: `old_text` (literal, copied from
 `read`), `grep` (regex; the matched line/block including its trailing newline), or `lines` (e.g.
 `"263:270"`). `mode` is `replace` (default) / `after` / `before` / `append` / `prepend`; also `count`
-(require exactly N occurrences and replace all), `nth` (k-th occurrence), `strict`, `dry_run`, `note`.
-`count` and `nth` are mutually exclusive.
+(require exactly N occurrences and replace all), `nth` (k-th occurrence), `strict`, `diff` (`auto` /
+`full` / `none`), `dry_run`, `note`. `count` and `nth` are mutually exclusive.
 
 ### `write_text` — create or fully replace a file
 
-`file_path` + `content`; creation needs no flag, an overwrite is backed up first, and a brand-new file
-follows the **majority** line-ending style of its siblings (same extension first) with no BOM by
-default.
+`file_path` + `content` (plus the same `diff` / `dry_run` / `note`); creation needs no flag, an
+overwrite is backed up first, and a brand-new file follows the **majority** line-ending style of its
+siblings (same extension first) with no BOM by default.
 
-Both **write by default** (like the built-ins); pass `dry_run: true` to preview. The returned text
-always includes the diff.
+Both **write by default** (like the built-ins); pass `dry_run: true` to preview.
+
+### Result text and the token budget
+
+Tool results land in the **append-only session history, which is never prefix-cached**, so every byte
+returned per call accumulates. The result is therefore split into layers:
+
+| Layer | Content | Where it goes |
+|---|---|---|
+| Model-facing (`brief` / `diff`) | warnings + one stat line (e.g. `replace@60 +1/-1`) + a budgeted diff body (0 context lines) | the model context |
+| Full record (`stdout`) | path header, the complete diff with context lines, the backup name | UI / logs / human triage |
+| UI card (`presentationMeta`) | the same `{ path, oldText, newText }` hunk list the built-in `edit` / `write` project | the Web UI, never the model context |
+
+- The path appears **exactly once** in the model-facing text, and the backup filename is no longer
+  echoed (it stays in `stdout` and in the ledger).
+- The body is returned only when the change is genuinely small (`diff: auto`, threshold
+  `maxDiffLines`); otherwise the model gets the stat line plus a one-line hint and decides for itself
+  whether to `read`. `diff: full` forces the body, but **it is still capped** — uncapped, a 400-line
+  rewrite echoes 7.5k tokens straight back (a measured ~1.0x amplification of the content just sent).
 
 ## Deliberate limitations
 
@@ -98,8 +117,9 @@ the tools.
 
 - **Writes bypass `ctx.fs`.** The file is written by the plugin itself, so the fs-observation policy
   (read-before-write, version freshness), the sandbox, `sandbox_permissions` escalation and Windows
-  DACL preservation are all skipped — and the Web UI therefore shows no diff card (the model still
-  receives the textual diff).
+  DACL preservation are all skipped. The atomic write is the plugin's own (same-directory temp file +
+  fsync + rename) and the diff card comes from its own `presentationMeta` (the built-ins project the
+  `ctx.fs` `before` / `after` instead).
 - **Line anchors are not content-verified.** `lines` and `before` / `after <line>` locate text by line
   number alone: a wrong number does not fail, it edits somewhere else. When the anchor has to be
   verifiable, use `old_text` or `grep`.
@@ -119,7 +139,9 @@ There is no Config schema: the preset row's `config:` mapping is passed through
 | `ledger` | `true` | append a JSONL record to `artifactsDir/edits.log` |
 | `artifactsDir` | `<workspace>/.dsh` | where backups and the ledger live |
 | `newFileBom` | `false` | write a UTF-8 BOM when creating a new file |
-| `context` | `3` | context lines in the unified diff |
+| `context` | `3` | context lines in the **human-facing** diff (affects `stdout` and the UI card only; the model-facing body always uses 0) |
+| `diff` | `'auto'` | default policy for the model-facing diff body; a per-call `diff` argument overrides it |
+| `maxDiffLines` | `30` | line budget for the model-facing diff body: `auto` drops it when exceeded, `full` truncates at it |
 | `root` | `process.cwd()` | fallback workspace when a call has no agent session |
 
 `DSH_TEXT_EDITOR_EOL` (`lf` \| `crlf`) overrides the line-ending inference for **new** files.
@@ -128,7 +150,7 @@ There is no Config schema: the preset row's `config:` mapping is passed through
 
 ```powershell
 # run from the root of a clone of this repository
-node tools/selftest.mjs        # 75/75 on Windows + Node 24
+node tools/selftest.mjs        # 92/92 on Windows + Node 24
 node tools/check-license.mjs   # license / dependency / Node-only gate
 node tools/gen-schema.mjs      # embedded schemas still match the DSL
 ```
@@ -141,7 +163,11 @@ refusal, usage errors, binary/invalid-UTF-8 refusal, `.dsh/` and outside-workspa
 EOL inference, multi-hunk diffs, end-of-file newline changes and concurrent writes — **plus a
 plugin-layer suite** that drives `apply()` with a fake context and asserts tool registration, the
 guidance section, that every returned value satisfies `OUTPUT_SCHEMA`, the `render()` text, and the
-config plumbing (`root` / `backup` / `ledger` / `newFileBom`).
+config plumbing (`root` / `backup` / `ledger` / `newFileBom`) — **and a token-budget suite**: a
+full-file rewrite must not echo the content back, a small edit still shows the changed lines, the
+`diff: none` / `full` boundaries hold, the path appears once, and the complete diff flows only into
+the UI card. The token budget is a design constraint rather than an implementation detail, so it
+carries its own regression test; otherwise one "let me print a bit more here" quietly removes it.
 
 `tools/gen-schema.mjs` needs an installed `@deepseek-ai/dsh-tools`: it looks for one under the dsh
 profile's `node_modules` and under the npm global prefix, and `DSH_TOOLS_ENTRY` overrides that lookup.
@@ -150,7 +176,7 @@ It exits 2 when it cannot find one.
 ## Layout
 
 ```
-lib/core.mjs             # the core: BOM/EOL, anchors, matching, diff, backups, ledger, atomic write, per-target lock
+lib/core.mjs             # the core: BOM/EOL, anchors, matching, diff (with the result budget), backups, ledger, atomic write, per-target lock
 lib/editor.mjs           # the plugin: schemas, validation, tool registration (zero-dep ESM, no build)
 preset/preset.yml        # preset name/description, as dsh lists it
 scripts/install-preset.mjs  # derives the user preset from the local dsh installation

package/README.zh.md

@@ -16,7 +16,9 @@
 BOM 字节），且 `writeText` 不按原文件风格还原行尾。
 
 在保真之外，本插件还提供：**统一 diff**（可用 dry-run 预览）、**写入前自动备份**、**编辑台账**、
-**`grep` / `lines` 锚点**（无需人工誊抄原文）、**歧义时拒绝写入**，以及**最接近候选**提示。
+**`grep` / `lines` 锚点**（无需人工誊抄原文）、**歧义时拒绝写入**、**最接近候选**提示，以及
+**面向 token 预算的结果文本**：模型只看到一行统计加受行数预算约束的 diff 正文，完整 diff 走 UI 卡片
+（见「结果文本与 token 预算」）。
 
 ## 实现与依赖
 
@@ -80,6 +82,7 @@ dsh --profile web --dump-config   # 应当能看到 "# == @flotiarenor/dsh-tool-
 | `count`     | -    | 要求恰好 N 处命中并全部替换（不符则拒绝写入）。                |
 | `nth`       | -    | 只替换第 k 处（1-based）。                                               |
 | `strict`    | -    | 禁用宽松匹配（只接受精确匹配）。                                         |
+| `diff`      | -    | 结果里 diff 正文的详细程度：`auto`（默认，改动小时才给）/ `full`（总给，仍封顶）/ `none`（不给）。 |
 | `dry_run`   | -    | 只输出 diff，不写入文件。                                                |
 | `note`      | -    | 一行说明，记入编辑台账。                                                 |
 
@@ -88,16 +91,33 @@ dsh --profile web --dump-config   # 应当能看到 "# == @flotiarenor/dsh-tool-
 
 ### `write_text` —— 整文件新建/覆盖
 
-`file_path` + `content`；目标不存在时自动新建，覆盖前先备份。新建文件的行尾风格取自
-同目录的多数派（同扩展名优先），默认不写 BOM。
+`file_path` + `content`（另接受与 `edit_text` 相同的 `diff` / `dry_run` / `note`）；目标不存在时自动
+新建，覆盖前先备份。新建文件的行尾风格取自同目录的多数派（同扩展名优先），默认不写 BOM。
+
+### 结果文本与 token 预算
+
+工具结果会进入 **append-only 的会话历史，永远不会被前缀缓存**，所以每次调用回吐的字节逐次累积。
+因此本插件把结果分成两层：
+
+| 层                       | 内容                                                                            | 去向                        |
+| ------------------------ | ------------------------------------------------------------------------------- | --------------------------- |
+| 模型可见（`brief` / `diff`） | 警告 + 一行统计（如 `replace@60 +1/-1`）+ 受预算约束的 diff 正文（0 上下文行）    | 模型上下文                  |
+| 完整版（`stdout`）        | 路径头、含上下文行的完整 diff、备份名                                            | UI / 日志 / 人工排查        |
+| UI 卡片（`presentationMeta`） | 与原生 `edit` / `write` 同形的 `{ path, oldText, newText }` hunk 列表         | Web UI（**不进模型上下文**） |
+
+- 路径在模型可见文本里**只出现一次**，备份文件名不再回吐（它留在 `stdout` 与编辑台账里）。
+- 正文默认只在改动确实很小时才给（`diff: auto`，阈值见 `maxDiffLines`）；否则只给统计行并提供一行提示，
+  让模型自己决定要不要 `read`。`diff: full` 强制给正文，但**仍然封顶** —— 没有封顶时，一次"整体重写
+  400 行"会把 7.5k tokens 原样回吐（实测回吐量 ≈ 输入内容的 1.0x）。
 
 ## 已知限制
 
 以下均为有意的设计取舍，而非缺陷；采用前请对照自身场景确认。
 
 - **写入不经由 `ctx.fs`。** 文件由本插件直接写入，因此不经过 fs 观察策略（先读后写、版本新鲜度校验）、
-  沙箱与 `sandbox_permissions` 审批升权，也不保留 Windows DACL。对应地，Web UI 不会生成 diff 卡片
-  （模型仍可读到文本 diff）。
+  沙箱与 `sandbox_permissions` 审批升权，也不保留 Windows DACL。原子写由本插件自己保证
+  （同目录临时文件 + fsync + rename），diff 卡片则由 `presentationMeta` 自行提供（原生工具用的是
+  `ctx.fs` 的 `before` / `after`）。
 - **行号锚点不做内容校验。** `lines` 与 `before` / `after <行号>` 仅按行号定位：行号有误不会报错，
   改动会落在非预期位置；定位需要可校验时，请改用 `old_text` 或 `grep`。
 - **同目标串行仅限本进程。** 进程内按目标路径排队，并配合原子写，故并行的工具调用不会相互覆盖；
@@ -115,7 +135,9 @@ dsh --profile web --dump-config   # 应当能看到 "# == @flotiarenor/dsh-tool-
 | `ledger`       | `true`          | 往 `artifactsDir/edits.log` 追加一条 JSONL 记录 |
 | `artifactsDir` | `<工作区>/.dsh` | 备份与台账所在目录                               |
 | `newFileBom`   | `false`         | 新建文件时是否写 UTF-8 BOM                       |
-| `context`      | `3`             | unified diff 的上下文行数                        |
+| `context`      | `3`             | **人读** diff 的上下文行数（只影响 `stdout` 与 UI 卡片；模型可见正文固定 0 行） |
+| `diff`         | `'auto'`        | 模型可见 diff 正文的默认策略，可被逐调用的 `diff` 参数覆盖 |
+| `maxDiffLines` | `30`            | 模型可见 diff 正文的行数预算：`auto` 超了就只给统计行，`full` 按它截断 |
 | `root`         | `process.cwd()` | 无 agent 会话时的回退工作区                      |
 
 环境变量 `DSH_TEXT_EDITOR_EOL`（`lf` \| `crlf`）可覆盖**新建文件**的行尾推断。
@@ -124,7 +146,7 @@ dsh --profile web --dump-config   # 应当能看到 "# == @flotiarenor/dsh-tool-
 
 ```powershell
 # 在本仓库根目录执行
-node tools/selftest.mjs        # Windows + Node 24 参考结果 75/75
+node tools/selftest.mjs        # Windows + Node 24 参考结果 92/92
 node tools/check-license.mjs   # 许可证 / 依赖 / 纯 Node 门禁
 node tools/gen-schema.mjs      # 内嵌 schema 是否仍与作者 DSL 一致
 ```
@@ -133,7 +155,9 @@ node tools/gen-schema.mjs      # 内嵌 schema 是否仍与作者 DSL 一致
 二进制与非法 UTF-8、路径护栏（`.dsh/`、工作区之外）、行尾多数派推断、跨多个 hunk、末尾换行差异、
 并发写入不产生半截文件；**并含一层插件层断言**：以模拟 ctx 驱动 `apply()`，验证工具注册、引导段
 身份、每个返回值均满足 `OUTPUT_SCHEMA`、`render()` 输出，以及 config 透传（`root` / `backup` /
-`ledger` / `newFileBom`）。
+`ledger` / `newFileBom`）；**还有一层回吐预算断言**：整体重写不得回吐内容、小改动仍给改动行、
+`diff: none` / `full` 的边界、路径只出现一次、完整 diff 只走 UI 卡片。token 预算是设计约束而非实现
+细节，因此它自带回归测试 —— 否则一次"顺手多打印一点"就能把它悄悄取消掉。
 
 `tools/gen-schema.mjs` 需要一份装有 `@deepseek-ai/dsh-tools` 的 dsh：它会在 dsh profile 的
 `node_modules` 与 npm 全局目录中自动查找，也可用 `DSH_TOOLS_ENTRY` 显式指定；找不到入口时退出码为 2。
@@ -141,7 +165,7 @@ node tools/gen-schema.mjs      # 内嵌 schema 是否仍与作者 DSL 一致
 ## 目录结构
 
 ```
-lib/core.mjs             # 编辑核心：BOM/行尾、锚点、匹配、diff、备份、台账、原子写、同目标串行
+lib/core.mjs             # 编辑核心：BOM/行尾、锚点、匹配、diff（含回吐预算）、备份、台账、原子写、同目标串行
 lib/editor.mjs           # 插件本体：schema、参数校验、工具注册（零依赖 ESM，无构建）
 preset/preset.yml        # preset 的名字/描述（dsh 列表里显示的内容）
 scripts/install-preset.mjs  # 从本机 dsh 派生用户 preset

package/lib/core.mjs

@@ -6,7 +6,8 @@
  * 它承担 dsh 原生 `write`/`edit` 在 Windows 上做不到的事：
  *   * **保留 UTF-8 BOM**（原生工具会丢）；
  *   * **行尾跟随文件**（原生 `write` 会把 CRLF 文件拍成 LF）；
- *   * 默认先出 unified diff，落盘前自动备份，记编辑台账；
+ *   * unified diff **分两层**：模型只看到一行统计加受预算约束的 diff 正文（`brief` / `diff`），
+ *     完整细节留在 `stdout`（人类与 UI 卡片用）。落盘前自动备份，记编辑台账；
  *   * 锚点可以从目标取（`grep` 正则 / `lines` 行号），不必手抄旧文本；
  *   * 匹配失败时给"最接近的候选"，歧义时拒绝写盘而不是猜。
  *
@@ -18,6 +19,12 @@
  *
  * 备份与台账的格式：`<工作区>/.dsh/backups/<扁平化绝对路径>@<时间戳>` 与
  * `<工作区>/.dsh/edits.log` 里的 JSONL 记录（字段见 `appendLedger`）。
+ *
+ * 为什么要给 diff 定预算（`diff` / `maxDiffLines`）：工具结果是 **append-only 的会话历史，
+ * 永远不会被前缀缓存**，所以每次调用回吐的字节会逐次累积。而"新建/整体重写"的 unified diff
+ * 是每一行都带 `+` 的整文件回显 —— 实测回吐量 ≈ 输入内容的 1.0x，等于把刚发出去的内容再发
+ * 一遍。因此正文默认只在改动确实很小时才给（`auto`），其余情况只给统计行，让模型自己决定
+ * 要不要 `read` 文件；`none` 完全不回吐，`full` 强制回吐但仍受行数封顶。
  */
 
 import {
@@ -39,6 +46,10 @@ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'nod
 export const UTF8_BOM_BYTES = Buffer.from([0xef, 0xbb, 0xbf])
 export const GUARD_DIRS = ['.git', '.dsh']
 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
 
@@ -565,6 +576,65 @@ export function diffStat(before, after) {
   return { added, removed }
 }
 
+/**
+ * 按预算裁剪**模型可见**的 diff 正文。
+ *
+ * 只有 `full` 会强制给正文，且仍然封顶 —— 封顶是这里存在的全部理由：没有它，一次"整体重写
+ * 400 行"就会把 7.5k tokens 原样回吐（实测放大率 1.02x），而模型刚刚才把这段内容发出去。
+ *
+ * @param text - 已生成的 unified diff 文本（调用方传 0 上下文行的那份，只保留改动行）。
+ * @param mode - `auto` | `full` | `none`（见 `DIFF_MODES`）。
+ * @param maxLines - 正文行数预算，默认 `DEFAULT_MAX_DIFF_LINES`。
+ * @returns 模型可见的正文；裁剪时带一行提示（省略或截断），可能为空字符串。
+ */
+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')
+}
+
+/**
+ * 把 unified diff 文本解析成 UI diff 卡片的词汇：`{ path, oldText, newText }` 列表，
+ * 与原生 `edit` / `write` 的 `presentationMeta` 同形（纯新增的 hunk 用 `oldText: null`）。
+ *
+ * 只服务**人类**：这条路径不经过模型上下文，所以完整 diff（含上下文行）走这里，模型拿到的
+ * 是 `diffBudget` 裁过的那份。
+ *
+ * @param text - unified diff 文本。
+ * @param path - 卡片上标注的路径。
+ * @returns 每个 hunk 一个条目；没有可解析的 hunk 时返回空数组。
+ */
+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))
+    }
+  }
+  return hunks.map((hunk) => ({
+    path,
+    oldText: hunk.old.length > 0 ? hunk.old.join('\n') : null,
+    newText: hunk.next.join('\n'),
+  }))
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // 六、备份、台账、原子写、同目标串行
 // ─────────────────────────────────────────────────────────────────────────────
@@ -723,7 +793,7 @@ function countLf(buffer) {
 // ─────────────────────────────────────────────────────────────────────────────
 
 function fail(path, message) {
-  return { path, ok: false, wrote: false, dryRun: false, stdout: '', stderr: message }
+  return { path, ok: false, wrote: false, dryRun: false, stdout: '', stderr: message, brief: '', diff: '' }
 }
 
 function hintText(match) {
@@ -749,8 +819,10 @@ function hintText(match) {
  * plan（edit）：`{ kind:'edit', filePath, mode, newText, oldText, anchor:{value}|null, count, nth, strict, dryRun, note }`
  * plan（write）：`{ kind:'write', filePath, content, dryRun, note }`
  *
- * @param context - `{ root, artifactsDir, backup, log, tool, context, newFileBom }`
- * @returns 规范结果 `{ path, ok, wrote, dryRun, stdout, stderr }`
+ * @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` = **模型可见**的那一份（统计行与受预算约束的正文）。
  */
 export async function applyPlan(plan, context) {
   const {
@@ -761,6 +833,8 @@ export async function applyPlan(plan, context) {
     tool = 'edit_text',
     context: diffContext = DEFAULT_CONTEXT,
     newFileBom = false,
+    diff: diffMode = 'auto',
+    maxDiffLines = DEFAULT_MAX_DIFF_LINES,
   } = context
   const absPath = isAbsolute(plan.filePath) ? resolve(plan.filePath) : resolve(root, plan.filePath)
   const label = relativeLabel(root, absPath)
@@ -921,6 +995,12 @@ export async function applyPlan(plan, context) {
     const kinds = [...new Set(applied.map(([k, s, e]) => (k === 'replace' ? `replace@${s}${e !== s ? `-${e}` : ''}` : k)))]
       .join('、')
 
+    // 模型可见的那一份：警告 + 一行统计（+A/-B），加受预算约束的正文。
+    // 正文用 0 上下文行 —— 模型刚做完这次编辑，周边内容它要么已经读过，要么可以再 read；
+    // 完整 diff（带 context 行）只走 stdout 与 UI 卡片，不进这条路径。
+    const brief = [...warnings, `${kinds} +${stat.added}/-${stat.removed}`].join('\n')
+    const visibleDiff = diffBudget(unifiedDiff(label, original, output, 0), diffMode, maxDiffLines)
+
     if (plan.dryRun) {
       return {
         path: plan.filePath,
@@ -929,6 +1009,8 @@ export async function applyPlan(plan, context) {
         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,
       }
     }
 
@@ -968,6 +1050,8 @@ export async function applyPlan(plan, context) {
       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,
     }
   })
 }

package/lib/editor.mjs

@@ -20,8 +20,11 @@
  *
  * 有意为之的取舍：
  *   * 写盘**不经过** `ctx.fs`：绕过 fs 观察策略（先读后写 / 版本新鲜度）、沙箱与
- *     `sandbox_permissions` 审批升权、原生原子写与 Windows DACL 保留，也不产生 Web UI 的
- *     diff 卡片（模型仍能看到文本 diff）。
+ *     `sandbox_permissions` 审批升权、原生原子写与 Windows DACL 保留。原生原子写与本插件的
+ *     临时文件 + fsync + rename 等价，这段绕过的代价已在 README 写明。
+ *   * 模型可见的结果文本**刻意很省**：路径只出现一次，只有一行统计加受预算约束的 diff 正文
+ *     （`brief` / `diff`）；备份名等细节只留在台账与 `stdout` 里。完整 diff 走
+ *     `presentationMeta` 的 UI 卡片 —— 那条路径不进模型上下文。理由见 `lib/core.mjs` 头部。
  *   * `lines` / `before <行号>` 是**盲锚点**：行号错了不会报错，会改在别的地方。
  *   * 同目标串行只覆盖**本进程内**；跨进程（另一个 dsh 实例、你手边的编辑器）仍可能互相覆盖。
  *
@@ -30,12 +33,14 @@
  *   ledger: boolean               默认 true（追加 artifactsDir/edits.log）
  *   artifactsDir: string          默认 <工作区>/.dsh
  *   newFileBom: boolean           默认 false（新建文件是否写 BOM）
- *   context: number               diff 上下文行数，默认 3
+ *   context: number               人读 diff 的上下文行数，默认 3（只影响 stdout 与 UI 卡片）
+ *   diff: 'auto'|'full'|'none'    模型可见 diff 正文的默认策略，默认 'auto'
+ *   maxDiffLines: number          模型可见 diff 正文的行数预算，默认 30
  *   root: string                  没有 agent 会话时的回退工作区
  * 新建文件的行尾推断可用环境变量 `DSH_TEXT_EDITOR_EOL` = lf | crlf 覆盖（见 lib/core.mjs）。
  */
 
-import { UsageError, applyPlan, toLf } from './core.mjs'
+import { DIFF_MODES, UsageError, applyPlan, hunksFromDiff, toLf } from './core.mjs'
 
 export const name = 'tool-text-editor'
 
@@ -56,8 +61,9 @@ const GUIDANCE =
   + 'only when a `_text` call reports that it cannot run.'
 
 const EDIT_DESCRIPTION =
-  'Edit one existing text file. Preserves the UTF-8 BOM and the file line-ending style, prints a unified '
-  + 'diff, and backs the previous content up before writing. Give exactly ONE anchor: `old_text` (literal, '
+  'Edit one existing text file. Preserves the UTF-8 BOM and the file line-ending style, backs the previous '
+  + 'content up, and returns a stat line plus the changed lines when the diff is small (see '
+  + '`diff`). Give exactly ONE anchor: `old_text` (literal, '
   + 'copied from `read`), `grep` (a regular expression whose matching line/block becomes the anchor), or '
   + '`lines` (e.g. "263:270"). `mode` defaults to `replace`; use `after`/`before` to insert beside a '
   + '`grep`/`lines` anchor, `append`/`prepend` for the file ends. Prefer `old_text`/`grep`: a wrong line '
@@ -65,8 +71,9 @@ const EDIT_DESCRIPTION =
   + '`nth` or `count` says which/how many. Set `dry_run` to preview without writing.'
 
 const WRITE_DESCRIPTION =
-  'Create or completely replace one text file. Preserves the UTF-8 BOM and the file line-ending style, '
-  + 'prints a unified diff, and backs the previous content up before overwriting. Creation needs no flag: '
+  'Create or completely replace one text file. Preserves the UTF-8 BOM and the file line-ending style, backs '
+  + 'the previous content up, and returns a stat line instead of echoing the content '
+  + 'back (see `diff`). Creation needs no flag: '
   + 'the tool detects whether the target exists, and a brand-new file follows the line-ending style of its '
   + 'sibling files. Set `dry_run` to preview without writing.'
 
@@ -83,6 +90,7 @@ export const EDIT_PARAMETERS = {
     count: { type: 'number', description: 'Require exactly N occurrences and replace all of them.' },
     nth: { type: 'number', description: 'Replace the k-th occurrence only (1-based).' },
     strict: { type: 'boolean', description: 'Disable relaxed matching.' },
+    diff: { type: 'string', description: 'Diff detail in the result: auto (default, small changes only) | full (always, capped) | none.', enum: DIFF_MODES },
     dry_run: { type: 'boolean', description: 'Print the diff without writing.' },
     note: { type: 'string', description: 'One-line reason recorded in the edit ledger.' },
   },
@@ -94,6 +102,7 @@ export const WRITE_PARAMETERS = {
   properties: {
     file_path: { type: 'string', description: 'Target file, resolved against the session working directory when relative.' },
     content: { type: 'string', description: 'Complete new file content.' },
+    diff: { type: 'string', description: 'Diff detail in the result: auto (default, small changes only) | full (always, capped) | none.', enum: DIFF_MODES },
     dry_run: { type: 'boolean', description: 'Print the diff without writing.' },
     note: { type: 'string', description: 'One-line reason recorded in the edit ledger.' },
   },
@@ -111,11 +120,19 @@ export const OUTPUT_SCHEMA = {
     dryRun: { type: 'boolean' },
     stdout: { type: 'string' },
     stderr: { type: 'string' },
+    brief: { type: 'string' },
+    diff: { type: 'string' },
   },
-  required: ['path', 'ok', 'wrote', 'dryRun', 'stdout', 'stderr'],
+  required: ['path', 'ok', 'wrote', 'dryRun', 'stdout', 'stderr', 'brief', 'diff'],
 }
 
-/** 模型可见的结果文本：失败给 stderr + stdout，成功给头部 + unified diff。 */
+/**
+ * 模型可见的结果文本：**一行统计（+ 受预算约束的 diff 正文）**。
+ *
+ * 这里刻意不复述任何东西：路径只出现一次，备份名只留在台账与 `stdout` 里，完整 diff 交给
+ * UI 卡片。工具结果是 append-only 的会话历史、永不缓存，所以每个字节都要问一句"模型真需要吗"；
+ * 失败时相反 —— 原因必须完整，因为下一次调用要靠它自救。
+ */
 function renderResult(_args, value) {
   const where = value.path === '' ? '' : ' ' + value.path
   if (!value.ok) {
@@ -123,8 +140,27 @@ function renderResult(_args, value) {
     return [{ type: 'text', text: 'FAIL' + where + '\n' + (detail === '' ? '(no output)' : detail) }]
   }
   const head = value.dryRun ? 'DRY RUN' + where + ' (nothing written)' : 'WROTE' + where
-  const body = value.stdout.trim()
-  return [{ type: 'text', text: body === '' ? head : head + '\n' + body }]
+  const body = [value.brief, value.diff].map((part) => part.trim()).filter((part) => part !== '')
+  return [{ type: 'text', text: [head, ...body].join('\n') }]
+}
+
+/**
+ * UI diff 卡片：**完整** diff（含配置的上下文行）只走这条路径。
+ * 元数据随 `tool/result` 持久化，供实时与回放两条路径使用；模型永远看不到它。
+ */
+function presentationMeta(_args, value) {
+  const diffs = value.ok === true && value.wrote === true ? hunksFromDiff(value.stdout, value.path) : []
+  return { diffs, path: value.path }
+}
+
+/** 有 diff 卡片可用就交给 UI；否则返回 `undefined`，让宿主回退到文本渲染。 */
+function presentResult(_args, result) {
+  if (result.isError === true) return undefined
+  const meta = result.meta
+  const diffs = meta !== null && typeof meta === 'object' && Array.isArray(meta.diffs) ? meta.diffs : []
+  if (diffs.length === 0) return undefined
+  const title = typeof meta.path === 'string' && meta.path !== '' ? meta.path : undefined
+  return title === undefined ? { card: 'diff', diffs } : { card: 'diff', title, diffs }
 }
 
 function stringArg(value, label, { required = false } = {}) {
@@ -151,6 +187,14 @@ function booleanArg(value, label) {
   return value
 }
 
+function diffModeArg(value) {
+  if (value === undefined) return undefined
+  if (typeof value !== 'string' || !DIFF_MODES.includes(value)) {
+    throw new UsageError('diff must be one of ' + DIFF_MODES.join(' / '))
+  }
+  return value
+}
+
 /**
  * 校验并归一 `edit_text` 入参。
  * @throws {UsageError} 参数不合法（不会落盘）。
@@ -192,6 +236,7 @@ export function planEdit(args) {
     nth,
     strict: booleanArg(args.strict, 'strict') === true,
     dryRun: booleanArg(args.dry_run, 'dry_run') === true,
+    diff: diffModeArg(args.diff),
     note: stringArg(args.note, 'note') ?? '',
   }
 }
@@ -205,6 +250,7 @@ export function planWrite(args) {
     filePath,
     content: toLf(args.content),
     dryRun: booleanArg(args.dry_run, 'dry_run') === true,
+    diff: diffModeArg(args.diff),
     note: stringArg(args.note, 'note') ?? '',
   }
 }
@@ -225,6 +271,8 @@ function fail(path, message) {
     dryRun: false,
     stdout: '',
     stderr: message,
+    brief: '',
+    diff: '',
   }
 }
 
@@ -244,7 +292,12 @@ export function apply(ctx, config) {
     log: settings.ledger !== false,
     context: Number.isFinite(settings.context) ? settings.context : undefined,
     newFileBom: settings.newFileBom === true,
+    ...(Number.isFinite(settings.maxDiffLines) && settings.maxDiffLines >= 1
+      ? { maxDiffLines: Math.floor(settings.maxDiffLines) }
+      : {}),
   }
+  /** 配置层的默认 diff 策略；逐调用的 `diff` 参数优先于它。 */
+  const diffDefault = DIFF_MODES.includes(settings.diff) ? settings.diff : 'auto'
 
   ctx.systemPrompt.section({ name: 'tool:edit_text', order: 116, text: GUIDANCE })
 
@@ -259,6 +312,7 @@ export function apply(ctx, config) {
       root,
       ...(artifactsDir === undefined ? {} : { artifactsDir }),
       ...planOptions,
+      diff: plan.diff ?? diffDefault,
       tool: plan.kind === 'write' ? WRITE_TOOL : EDIT_TOOL,
     })
   }
@@ -267,7 +321,8 @@ export function apply(ctx, config) {
     name: EDIT_TOOL,
     description: EDIT_DESCRIPTION,
     parameters: EDIT_PARAMETERS,
-    output: { schema: OUTPUT_SCHEMA, render: renderResult },
+    output: { schema: OUTPUT_SCHEMA, render: renderResult, presentationMeta },
+    presentResult,
     timeoutMs: TIMEOUT_MS,
     async execute(args, exec) {
       let plan
@@ -285,7 +340,8 @@ export function apply(ctx, config) {
     name: WRITE_TOOL,
     description: WRITE_DESCRIPTION,
     parameters: WRITE_PARAMETERS,
-    output: { schema: OUTPUT_SCHEMA, render: renderResult },
+    output: { schema: OUTPUT_SCHEMA, render: renderResult, presentationMeta },
+    presentResult,
     timeoutMs: TIMEOUT_MS,
     async execute(args, exec) {
       let plan

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@flotiarenor/dsh-tool-text-editor",
-  "version": "1.0.0",
-  "description": "Byte-faithful text editing tools (edit_text / write_text) for DeepSeek Harness: they preserve a UTF-8 BOM and the file's own CRLF/LF style (the built-in write/edit tools do not), print a unified diff, back the previous content up, and accept grep/lines anchors. Pure Node and in-process: no external runtime, no child process, no third-party package, no build step, no imports beyond node: builtins.",
+  "version": "1.1.0",
+  "description": "Byte-faithful text editing tools (edit_text / write_text) for DeepSeek Harness: they preserve a UTF-8 BOM and the file's own CRLF/LF style (the built-in write/edit tools do not), back the previous content up, accept grep/lines anchors, and return a token-budgeted result (one stat line plus a bounded diff body, with the full diff going to the UI card instead of the model context). Pure Node and in-process: no external runtime, no child process, no third-party package, no build step, no imports beyond node: builtins.",
   "type": "module",
   "main": "lib/editor.mjs",
   "exports": {
@@ -14,6 +14,15 @@
       "patch": "./cordis.patch.yml"
     }
   },
+  "scripts": {
+    "test": "node tools/check-license.mjs && node tools/selftest.mjs",
+    "check": "node tools/check-license.mjs",
+    "check:license": "node tools/check-license.mjs",
+    "check:schema": "node tools/gen-schema.mjs",
+    "selftest": "node tools/selftest.mjs",
+    "install:preset": "node scripts/install-preset.mjs",
+    "prepublishOnly": "node tools/check-license.mjs && node tools/selftest.mjs"
+  },
   "files": [
     "lib",
     "preset",
@@ -57,13 +66,5 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/Flotiarenor/dsh-tool-text-editor.git"
-  },
-  "scripts": {
-    "test": "node tools/check-license.mjs && node tools/selftest.mjs",
-    "check": "node tools/check-license.mjs",
-    "check:license": "node tools/check-license.mjs",
-    "check:schema": "node tools/gen-schema.mjs",
-    "selftest": "node tools/selftest.mjs",
-    "install:preset": "node scripts/install-preset.mjs"
   }
-}
+}