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

package/README.md

@@ -19,6 +19,9 @@ On top of fidelity: **unified diffs** (with a `dry_run` preview), **automatic ba
 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.
 
+The canonical return value of both tools, the composition of the model-facing text, and the UI card
+projection are documented under "Return value".
+
 ## Implementation and requirements
 
 The implementation is **in-process Node** (`lib/core.mjs`): `node:` builtins only, no subprocess, no
@@ -79,17 +82,48 @@ 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.
+
+### Return value
+
+Both tools return the same canonical value (`OUTPUT_SCHEMA`). Field contents and destinations:
+
+| Field | Content | Destination |
+|---|---|---|
+| `path` | the target path as supplied by the caller, echoed back | — |
+| `ok` / `wrote` / `dryRun` | outcome flags | — |
+| `brief` | warning lines plus one stat line, e.g. `replace@60 +1/-1` | model context |
+| `diff` | a unified diff of the changed lines only (0 context lines), limited by `maxDiffLines` | model context |
+| `stdout` | the full human record: path header, complete diff with context lines, backup filename | UI / logs / triage |
+| `stderr` | failure reason (non-empty on failure) | model context |
+
+The model-facing text consists of `brief` and `diff`, with the path appearing once in the leading
+line. The complete diff is additionally projected by `output.presentationMeta` into a list of
+`{ path, oldText, newText }`, the same card vocabulary the built-in `edit` / `write` tools use, and
+handed to the Web UI by `presentResult`; that metadata is persisted with `tool/result` and never
+enters the model context.
+
+The `diff` argument selects the detail level of the `diff` field:
+
+| Value | Behavior |
+|---|---|
+| `auto` | default. The body is returned when it fits within `maxDiffLines`; otherwise it is omitted with a one-line note |
+| `full` | the body is always returned; it is truncated with a one-line note when it exceeds `maxDiffLines` |
+| `none` | no body is returned |
 
-Both **write by default** (like the built-ins); pass `dry_run: true` to preview. The returned text
-always includes the diff.
+The body always uses 0 context lines; the `context` setting affects `stdout` and the UI card only.
+`maxDiffLines` bounds the bytes returned to the model context by a single call: tool results are
+appended to the session history and are not prefix-cached, so without a bound a full-file rewrite
+produces a return of the same order as the content just sent (a measured ~1.0x amplification).
 
 ## Deliberate limitations
 
@@ -98,8 +132,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 implemented by the plugin (same-directory
+  temp file + fsync + rename), and the diff card is projected by the plugin's `presentationMeta`
+  whereas the built-ins use the `before` / `after` returned by `ctx.fs`.
 - **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 +154,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 diff of `stdout` and the UI card (the model-facing body always uses 0) |
+| `diff` | `'auto'` | default policy for the `diff` field (`auto` / `full` / `none`); a per-call `diff` argument takes precedence |
+| `maxDiffLines` | `30` | line limit for the `diff` field: `auto` omits the body 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 +165,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 +178,10 @@ 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 return-value suite**: a
+full-file rewrite must not echo the content back, a small edit must still report the changed lines,
+the three `diff` values must hold their documented boundaries, the path must appear once, and the
+complete diff must be projected only through `presentationMeta`.
 
 `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.

package/README.zh.md

@@ -18,6 +18,8 @@ BOM 字节），且 `writeText` 不按原文件风格还原行尾。
 在保真之外，本插件还提供：**统一 diff**（可用 dry-run 预览）、**写入前自动备份**、**编辑台账**、
 **`grep` / `lines` 锚点**（无需人工誊抄原文）、**歧义时拒绝写入**，以及**最接近候选**提示。
 
+两个工具的规范返回值、模型可见文本的构成与 UI 卡片的投影方式见「返回值」。
+
 ## 实现与依赖
 
 实现是**进程内 Node**（`lib/core.mjs`）：只用 `node:` 内置模块，不启动任何子进程，无构建步骤、
@@ -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,46 @@ dsh --profile web --dump-config   # 应当能看到 "# == @flotiarenor/dsh-tool-
 
 ### `write_text` —— 整文件新建/覆盖
 
-`file_path` + `content`；目标不存在时自动新建，覆盖前先备份。新建文件的行尾风格取自
-同目录的多数派（同扩展名优先），默认不写 BOM。
+`file_path` + `content`（另接受与 `edit_text` 相同的 `diff` / `dry_run` / `note`）；目标不存在时自动
+新建，覆盖前先备份。新建文件的行尾风格取自同目录的多数派（同扩展名优先），默认不写 BOM。
+
+### 返回值
+
+两个工具返回同一份规范值（`OUTPUT_SCHEMA`）。字段内容与去向如下：
+
+| 字段                  | 内容                                                                     | 去向             |
+| --------------------- | ------------------------------------------------------------------------ | ---------------- |
+| `path`              | 调用方给出的目标路径（原样回填）                                         | —                |
+| `ok` / `wrote` / `dryRun` | 执行结果标志                                                       | —                |
+| `brief`             | 警告行与一行统计，如 `replace@60 +1/-1`                              | 模型上下文       |
+| `diff`              | 只由改动行组成的 unified diff（0 上下文行），受 `maxDiffLines` 限制 | 模型上下文       |
+| `stdout`            | 人读全文：路径头、含上下文行的完整 diff、备份文件名                      | UI / 日志 / 排查 |
+| `stderr`            | 失败原因（失败时非空）                                                   | 模型上下文       |
+
+模型可见文本由 `brief` 与 `diff` 组成，路径在起始行出现一次。完整 diff 另经
+`output.presentationMeta` 投影为 `{ path, oldText, newText }` 列表，与原生 `edit` / `write` 的卡片
+词汇同形，由 `presentResult` 交给 Web UI；该元数据随 `tool/result` 持久化，不进入模型上下文。
+
+`diff` 参数决定 `diff` 字段的详细程度：
+
+| 取值      | 行为                                                                             |
+| --------- | -------------------------------------------------------------------------------- |
+| `auto`  | 默认。正文不超过 `maxDiffLines` 行时给出；超出时不给出正文，附一行省略提示       |
+| `full`  | 始终给出正文；超过 `maxDiffLines` 行时截断，附一行截断提示                       |
+| `none`  | 不给出正文                                                                       |
+
+正文固定使用 0 上下文行；`context` 配置只影响 `stdout` 与 UI 卡片。`maxDiffLines` 的作用是限制单次
+调用回吐到模型上下文的字节数——工具结果按追加方式进入会话历史，不参与前缀缓存，因此不含上限时，
+整文件重写会产生与输入内容等量级的回吐（实测放大率 ≈ 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 +148,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`             | `stdout` 与 UI 卡片中 diff 的上下文行数（模型可见正文固定 0 行） |
+| `diff`         | `'auto'`        | `diff` 字段的默认策略（`auto` / `full` / `none`）；逐调用的 `diff` 参数优先 |
+| `maxDiffLines` | `30`            | `diff` 字段的行数上限：`auto` 超出时不给出正文，`full` 超出时截断 |
 | `root`         | `process.cwd()` | 无 agent 会话时的回退工作区                      |
 
 环境变量 `DSH_TEXT_EDITOR_EOL`（`lf` \| `crlf`）可覆盖**新建文件**的行尾推断。
@@ -124,7 +159,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 +168,8 @@ node tools/gen-schema.mjs      # 内嵌 schema 是否仍与作者 DSL 一致
 二进制与非法 UTF-8、路径护栏（`.dsh/`、工作区之外）、行尾多数派推断、跨多个 hunk、末尾换行差异、
 并发写入不产生半截文件；**并含一层插件层断言**：以模拟 ctx 驱动 `apply()`，验证工具注册、引导段
 身份、每个返回值均满足 `OUTPUT_SCHEMA`、`render()` 输出，以及 config 透传（`root` / `backup` /
-`ledger` / `newFileBom`）。
+`ledger` / `newFileBom`）；**以及一层返回值约束断言**：整文件重写不回显内容、小改动仍给出改动行、
+`diff` 三种取值的行为边界、路径仅出现一次、完整 diff 只经 `presentationMeta` 投影。
 
 `tools/gen-schema.mjs` 需要一份装有 `@deepseek-ai/dsh-tools` 的 dsh：它会在 dsh profile 的
 `node_modules` 与 npm 全局目录中自动查找，也可用 `DSH_TOOLS_ENTRY` 显式指定；找不到入口时退出码为 2。

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` / `maxDiffLines` 的由来：工具结果按追加方式进入会话历史，不参与前缀缓存，因此单次调用
+ * 回吐的字节随调用次数累积。"新建 / 整体重写" 的 unified diff 每一行都带 `+`，等同于整文件回显
+ * ——实测回吐量与输入内容同量级（放大率 ≈ 1.0x）。故模型可见正文默认仅在改动较小时给出
+ * （`auto`），其余情况只给统计行，由调用方决定是否另行读取文件；`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 正文。
+ *
+ * `none` 不返回正文；`auto` 仅在正文不超过上限时返回；`full` 始终返回正文，超过上限时截断并附
+ * 一行说明。上限的作用是避免整文件重写产生与输入内容同量级的回吐（实测放大率 ≈ 1.0x）。
+ *
+ * @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 上下文行：调用方刚完成这次编辑，周边内容或已读取过，或可自行读取。
+    // 完整 diff（含上下文行）只出现在 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 写明。
+ *   * 模型可见文本受上限约束：路径仅出现一次，正文为一行统计加经 `diffBudget` 裁剪的 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,18 @@ 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 正文**。
+ *
+ * 成功路径只返回 `brief` 与 `diff`：路径仅出现一次，备份文件名只保留在台账与 `stdout` 中，
+ * 完整 diff 由 UI 卡片承载。失败路径相反——原因必须完整，它决定调用方的下一次调用。
+ */
 function renderResult(_args, value) {
   const where = value.path === '' ? '' : ' ' + value.path
   if (!value.ok) {
@@ -123,8 +139,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 +186,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 +235,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 +249,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 +270,8 @@ function fail(path, message) {
     dryRun: false,
     stdout: '',
     stderr: message,
+    brief: '',
+    diff: '',
   }
 }
 
@@ -244,7 +291,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 +311,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 +320,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 +339,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.1",
+  "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 bounded result: one stat line plus a diff body limited by maxDiffLines, while the complete diff is projected to the UI card and never enters 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"
   }
-}
+}