@flotiarenor/dsh-tool-text-editor 1.0.0

package/lib/editor.mjs

@@ -0,0 +1,301 @@
+// SPDX-FileCopyrightText: 2026 Flotiarenor
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * editor.mjs —— dsh 模型工具插件：`edit_text` / `write_text`。
+ *
+ * 为什么存在：dsh 原生的 `write` / `edit` 在 Windows 上会丢掉 UTF-8 BOM，原生 `write` 还会把
+ * CRLF 文件改写成 LF（实测确认；`@deepseek-ai/dsh-fs-local` 全文没有 BOM 处理，Node 的
+ * `TextDecoder` 默认吞掉前导 BOM 字节）。本插件用**进程内 Node 实现**（`lib/core.mjs`）做同样
+ * 的事，但把 BOM 与行尾保真、dry-run diff、自动备份、编辑台账、grep/lines 锚点一起带上。
+ *
+ * 与原生工具的关系：注册的是两个**不与原生重名**的工具，原生 `edit`/`write` 原样保留，
+ * 因此没有同名注册冲突，回退就是给 preset 行加 `disabled: true`。
+ *
+ * 依赖：**零**。只用 `node:` 内置模块 —— 不启动解释器或外部命令，不 import 任何包，没有构建
+ * 步骤、没有第三方依赖、没有外部运行时。因此本文件既能被 preset 行用绝对路径加载，也能被 link
+ * 进 profile 后按包名加载（preset 行的裸包名走宿主基址解析，模块内部的裸 import 走文件真实路径
+ * 解析；零依赖让两种挂载方式都成立）。内嵌的 JSON Schema 是用 dsh 自己的
+ * `parameterSchemaSpecToJsonSchema` / `valueSchemaSpecToJsonSchema` 生成的（生成脚本在仓库里，见
+ * `tools/gen-schema.mjs`；它不随包发布）。
+ *
+ * 有意为之的取舍：
+ *   * 写盘**不经过** `ctx.fs`：绕过 fs 观察策略（先读后写 / 版本新鲜度）、沙箱与
+ *     `sandbox_permissions` 审批升权、原生原子写与 Windows DACL 保留，也不产生 Web UI 的
+ *     diff 卡片（模型仍能看到文本 diff）。
+ *   * `lines` / `before <行号>` 是**盲锚点**：行号错了不会报错，会改在别的地方。
+ *   * 同目标串行只覆盖**本进程内**；跨进程（另一个 dsh 实例、你手边的编辑器）仍可能互相覆盖。
+ *
+ * 配置（本插件没有 Config schema，preset 行的 `config:` 字段原样透传）：
+ *   backup: boolean               默认 true（落盘前备份到 artifactsDir/backups）
+ *   ledger: boolean               默认 true（追加 artifactsDir/edits.log）
+ *   artifactsDir: string          默认 <工作区>/.dsh
+ *   newFileBom: boolean           默认 false（新建文件是否写 BOM）
+ *   context: number               diff 上下文行数，默认 3
+ *   root: string                  没有 agent 会话时的回退工作区
+ * 新建文件的行尾推断可用环境变量 `DSH_TEXT_EDITOR_EOL` = lf | crlf 覆盖（见 lib/core.mjs）。
+ */
+
+import { UsageError, applyPlan, toLf } from './core.mjs'
+
+export const name = 'tool-text-editor'
+
+/** 只消费宿主服务（工具注册表 / 系统提示词）；不发布任何服务。 */
+export const inject = ['tools', 'systemPrompt']
+
+const EDIT_TOOL = 'edit_text'
+const WRITE_TOOL = 'write_text'
+const TIMEOUT_MS = 60_000
+const EDIT_MODES = ['replace', 'after', 'before', 'append', 'prepend']
+
+/** 工具引导（order 116，落在工具引导区间 100–199）。文本里不能出现双花括号（会被当提示词变量）。 */
+const GUIDANCE =
+  'Prefer `edit_text` and `write_text` for text changes in this workspace: they preserve a UTF-8 BOM and '
+  + 'the file existing CRLF/LF style, print a unified diff, back the previous content up, and accept `grep` '
+  + 'or `lines` anchors so the old text never has to be copied by hand. The built-in `write` tool drops the '
+  + 'BOM and rewrites a CRLF file as LF, and the built-in `edit` tool drops the BOM; use the built-ins '
+  + '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, '
+  + '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 '
+  + 'number does not fail, it edits the wrong place. A literal that occurs more than once is refused unless '
+  + '`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: '
+  + '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.'
+
+/** 参数 schema（等价于 defineTool 对 `tools/gen-schema.mjs` 里 DSL 的产物；那里会校验二者一致）。 */
+export const EDIT_PARAMETERS = {
+  type: 'object',
+  properties: {
+    file_path: { type: 'string', description: 'Target file, resolved against the session working directory when relative.' },
+    new_text: { type: 'string', description: 'Replacement / inserted text.' },
+    old_text: { type: 'string', description: 'Literal anchor text to replace (exactly one anchor source).' },
+    grep: { type: 'string', description: 'Regular-expression anchor: the matching line or line block is replaced.' },
+    lines: { type: 'string', description: 'Line anchor, e.g. "263:270" or "120".' },
+    mode: { type: 'string', description: 'Edit kind. Default replace.', enum: EDIT_MODES },
+    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.' },
+    dry_run: { type: 'boolean', description: 'Print the diff without writing.' },
+    note: { type: 'string', description: 'One-line reason recorded in the edit ledger.' },
+  },
+  required: ['file_path', 'new_text'],
+}
+
+export const WRITE_PARAMETERS = {
+  type: 'object',
+  properties: {
+    file_path: { type: 'string', description: 'Target file, resolved against the session working directory when relative.' },
+    content: { type: 'string', description: 'Complete new file content.' },
+    dry_run: { type: 'boolean', description: 'Print the diff without writing.' },
+    note: { type: 'string', description: 'One-line reason recorded in the edit ledger.' },
+  },
+  required: ['file_path', 'content'],
+}
+
+/** 两个工具共用的规范返回值。一切都在进程内完成，所以只有结果，没有退出码或后端标记。 */
+export const OUTPUT_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    path: { type: 'string' },
+    ok: { type: 'boolean' },
+    wrote: { type: 'boolean' },
+    dryRun: { type: 'boolean' },
+    stdout: { type: 'string' },
+    stderr: { type: 'string' },
+  },
+  required: ['path', 'ok', 'wrote', 'dryRun', 'stdout', 'stderr'],
+}
+
+/** 模型可见的结果文本：失败给 stderr + stdout，成功给头部 + unified diff。 */
+function renderResult(_args, value) {
+  const where = value.path === '' ? '' : ' ' + value.path
+  if (!value.ok) {
+    const detail = [value.stderr.trim(), value.stdout.trim()].filter((part) => part !== '').join('\n')
+    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 }]
+}
+
+function stringArg(value, label, { required = false } = {}) {
+  if (value === undefined) {
+    if (required) throw new UsageError(`${label} is required`)
+    return undefined
+  }
+  if (typeof value !== 'string') throw new UsageError(`${label} must be a string`)
+  if (required && value.trim() === '') throw new UsageError(`${label} must be a non-empty string`)
+  return value
+}
+
+function integerArg(value, label, minimum) {
+  if (value === undefined) return undefined
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < minimum) {
+    throw new UsageError(`${label} must be an integer >= ${minimum}`)
+  }
+  return value
+}
+
+function booleanArg(value, label) {
+  if (value === undefined) return undefined
+  if (typeof value !== 'boolean') throw new UsageError(`${label} must be a boolean`)
+  return value
+}
+
+/**
+ * 校验并归一 `edit_text` 入参。
+ * @throws {UsageError} 参数不合法（不会落盘）。
+ */
+export function planEdit(args) {
+  const filePath = stringArg(args.file_path, 'file_path', { required: true })
+  if (typeof args.new_text !== 'string') throw new UsageError('new_text must be a string')
+  const mode = args.mode === undefined ? 'replace' : args.mode
+  if (typeof mode !== 'string' || !EDIT_MODES.includes(mode)) {
+    throw new UsageError('mode must be one of ' + EDIT_MODES.join(' / '))
+  }
+  const oldText = stringArg(args.old_text, 'old_text')
+  const grep = stringArg(args.grep, 'grep')
+  const lines = args.lines === undefined ? undefined : String(args.lines)
+  const anchors = []
+  if (oldText !== undefined) anchors.push('old_text')
+  if (grep !== undefined) anchors.push('grep')
+  if (lines !== undefined) anchors.push('lines')
+  if (mode === 'replace') {
+    if (anchors.length === 0) throw new UsageError('replace requires exactly one anchor: old_text, grep or lines')
+    if (anchors.length > 1) throw new UsageError('give exactly one anchor, got ' + anchors.join(' + '))
+  } else if (mode === 'after' || mode === 'before') {
+    if (oldText !== undefined) throw new UsageError(mode + ' takes grep or lines, not old_text')
+    if (anchors.length !== 1) throw new UsageError(mode + ' requires exactly one of grep / lines')
+  } else if (anchors.length > 0) {
+    throw new UsageError(mode + ' takes no anchor, got ' + anchors.join(' + '))
+  }
+  const count = integerArg(args.count, 'count', 1)
+  const nth = integerArg(args.nth, 'nth', 1)
+  if (count !== undefined && nth !== undefined) throw new UsageError('count and nth are mutually exclusive')
+  return {
+    kind: 'edit',
+    filePath,
+    mode,
+    newText: toLf(args.new_text),
+    oldText: oldText === undefined ? null : toLf(oldText),
+    anchor: grep !== undefined ? { value: grep } : lines !== undefined ? { value: lines } : null,
+    count,
+    nth,
+    strict: booleanArg(args.strict, 'strict') === true,
+    dryRun: booleanArg(args.dry_run, 'dry_run') === true,
+    note: stringArg(args.note, 'note') ?? '',
+  }
+}
+
+/** 校验并归一 `write_text` 入参。 */
+export function planWrite(args) {
+  const filePath = stringArg(args.file_path, 'file_path', { required: true })
+  if (typeof args.content !== 'string') throw new UsageError('content must be a string')
+  return {
+    kind: 'write',
+    filePath,
+    content: toLf(args.content),
+    dryRun: booleanArg(args.dry_run, 'dry_run') === true,
+    note: stringArg(args.note, 'note') ?? '',
+  }
+}
+
+/** 会话工作区；没有 agent 时退化为给出的 fallback。 */
+function workspaceRoot(exec, fallback) {
+  const session = exec && exec.agent && exec.agent.session
+  const cwd = session && session.header ? session.header.cwd : undefined
+  if (typeof cwd === 'string' && cwd.trim() !== '') return cwd
+  return fallback
+}
+
+function fail(path, message) {
+  return {
+    path: typeof path === 'string' ? path : '',
+    ok: false,
+    wrote: false,
+    dryRun: false,
+    stdout: '',
+    stderr: message,
+  }
+}
+
+/**
+ * 注册 `edit_text` / `write_text` 与工具引导段。
+ * @param ctx - 插件上下文（注册随其 fiber 释放）。
+ * @param config - preset 行配置（见文件头注释）。
+ */
+export function apply(ctx, config) {
+  const settings = config === undefined || config === null ? {} : config
+  const fallbackRoot = typeof settings.root === 'string' && settings.root !== '' ? settings.root : process.cwd()
+  const artifactsDir = typeof settings.artifactsDir === 'string' && settings.artifactsDir !== ''
+    ? settings.artifactsDir
+    : undefined
+  const planOptions = {
+    backup: settings.backup !== false,
+    log: settings.ledger !== false,
+    context: Number.isFinite(settings.context) ? settings.context : undefined,
+    newFileBom: settings.newFileBom === true,
+  }
+
+  ctx.systemPrompt.section({ name: 'tool:edit_text', order: 116, text: GUIDANCE })
+
+  /**
+   * 组装上下文并执行。
+   * @param plan - `planEdit` / `planWrite` 的结果。
+   * @param exec - 工具执行上下文（提供会话工作区）。
+   */
+  async function run(plan, exec) {
+    const root = workspaceRoot(exec, fallbackRoot)
+    return await applyPlan(plan, {
+      root,
+      ...(artifactsDir === undefined ? {} : { artifactsDir }),
+      ...planOptions,
+      tool: plan.kind === 'write' ? WRITE_TOOL : EDIT_TOOL,
+    })
+  }
+
+  ctx.tools.register({
+    name: EDIT_TOOL,
+    description: EDIT_DESCRIPTION,
+    parameters: EDIT_PARAMETERS,
+    output: { schema: OUTPUT_SCHEMA, render: renderResult },
+    timeoutMs: TIMEOUT_MS,
+    async execute(args, exec) {
+      let plan
+      try {
+        plan = planEdit(args)
+      } catch (error) {
+        if (error instanceof UsageError) return fail(args.file_path, error.message)
+        throw error
+      }
+      return await run(plan, exec)
+    },
+  })
+
+  ctx.tools.register({
+    name: WRITE_TOOL,
+    description: WRITE_DESCRIPTION,
+    parameters: WRITE_PARAMETERS,
+    output: { schema: OUTPUT_SCHEMA, render: renderResult },
+    timeoutMs: TIMEOUT_MS,
+    async execute(args, exec) {
+      let plan
+      try {
+        plan = planWrite(args)
+      } catch (error) {
+        if (error instanceof UsageError) return fail(args.file_path, error.message)
+        throw error
+      }
+      return await run(plan, exec)
+    },
+  })
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "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.",
+  "type": "module",
+  "main": "lib/editor.mjs",
+  "exports": {
+    ".": "./lib/editor.mjs",
+    "./core": "./lib/core.mjs",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "files": [
+    "lib",
+    "preset",
+    "scripts",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek",
+    "deepseek-harness",
+    "cordis",
+    "cordis-plugin",
+    "tool",
+    "editor",
+    "bom",
+    "crlf"
+  ],
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Flotiarenor",
+    "url": "https://github.com/Flotiarenor"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-tools": ">=0.1.0-rc.6"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "homepage": "https://github.com/Flotiarenor/dsh-tool-text-editor#readme",
+  "bugs": {
+    "url": "https://github.com/Flotiarenor/dsh-tool-text-editor/issues"
+  },
+  "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"
+  }
+}

package/preset/preset.yml

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: 2026 Flotiarenor
+# SPDX-License-Identifier: Apache-2.0
+name: 字节保真编辑器（BOM/CRLF）
+description: standard 的副本，额外挂载 edit_text / write_text 两个文本编辑工具：保 UTF-8 BOM 与文件自身 CRLF/LF 风格、出 unified diff、落盘前备份、支持 grep/lines 锚点。纯 Node 进程内实现（零依赖、不启动任何外部进程）；原生 edit/write 保持不变。

package/scripts/install-preset.mjs

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+// SPDX-FileCopyrightText: 2026 Flotiarenor
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * install-preset.mjs —— 把 `edit_text` / `write_text` 装成一个**用户 preset**。
+ *
+ * 做法：读**本机 dsh 自带的 preset 组合**（默认 `standard`），把 `tool-text-editor` 那一行插进去，
+ * 再连同本仓库的 `preset/preset.yml` 写到 `<DSH_HOME>/.agent-presets/<id>/`。
+ *
+ * 为什么不在仓库里放一份 preset 组合的拷贝：
+ *   * dsh 自带的组合是**别人（MIT, Copyright (c) 2026 DeepSeek）的作品**，随包分发它就要连带履行
+ *     它的署名义务，而这份拷贝与本插件的功能无关；
+ *   * 从用户自己的 dsh 里取，preset 自然跟着他装的 dsh 版本走 —— 不会像拷贝那样随 dsh 升级而过期。
+ *
+ * 用法：
+ *   node scripts/install-preset.mjs                      # 默认 --id texteditor --base standard
+ *   node scripts/install-preset.mjs --id my-edit --base code
+ *   node scripts/install-preset.mjs --from <path-to-agent.cordis.yml>   # 自己指定源组合
+ *   node scripts/install-preset.mjs --force              # 覆盖已存在的 preset（只覆盖两个文件）
+ *   node scripts/install-preset.mjs --dry-run            # 只打印会做什么，不落盘
+ *
+ * 退出码：0 成功，1 失败，2 用法错误 / 找不到 dsh 自带的 preset 组合。
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const REPO = resolve(HERE, '..')
+const PLUGIN = join(REPO, 'lib', 'editor.mjs').replace(/\\/g, '/')
+const META = join(REPO, 'preset', 'preset.yml')
+const SHIPPED_PRESET_DIR = ['config', 'agent-presets']
+const COMPOSITION = 'agent.cordis.yml'
+
+function flagValue(name) {
+  const index = process.argv.indexOf(name)
+  if (index < 0) return undefined
+  const value = process.argv[index + 1]
+  if (value === undefined || value.startsWith('--')) {
+    console.error('FAIL ' + name + ' 缺少取值')
+    process.exit(2)
+  }
+  return value
+}
+
+/**
+ * dsh 可能装在任何位置，所以按布局枚举"自带 preset 组合"的候选路径（不写死本机路径）：
+ *   1. `--from` / `DSH_PRESET_SOURCE` —— 显式指定，任何布局都能用；
+ *   2. dsh profile 的 node_modules（`<DSH_HOME|~/.dsh>/profiles/node_modules`）；
+ *   3. npm 全局前缀下的 node_modules（Windows `%APPDATA%\npm`；POSIX `/usr/local/lib`、
+ *      `/usr/lib`、`~/.npm-global/lib`）。
+ * @param base - 自带 preset 的 id（standard / code / cordis / minimal）。
+ * @returns 候选绝对路径（按优先级）。
+ */
+function findCompositions(base) {
+  const candidates = []
+  const explicit = flagValue('--from') ?? process.env.DSH_PRESET_SOURCE
+  if (typeof explicit === 'string' && explicit !== '') candidates.push(resolve(explicit))
+  const add = (nodeModules) => {
+    if (typeof nodeModules !== 'string' || nodeModules === '') return
+    candidates.push(join(nodeModules, '@deepseek-ai', 'dsh', ...SHIPPED_PRESET_DIR, base, COMPOSITION))
+  }
+  add(join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'profiles', 'node_modules'))
+  const globalRoots = process.platform === 'win32'
+    ? [process.env.APPDATA === undefined ? '' : join(process.env.APPDATA, 'npm', 'node_modules')]
+    : ['/usr/local/lib/node_modules', '/usr/lib/node_modules', join(homedir(), '.npm-global', 'lib', 'node_modules')]
+  for (const root of globalRoots) add(root)
+  return candidates
+}
+
+/** 我们插进组合里的那一段（只有这一段是我们自己的文字 + 行）。 */
+function pluginBlock(sourcePath) {
+  return [
+    '# ── 字节保真的文本编辑工具（edit_text / write_text）─────────────────────────',
+    '#',
+    '# 存在理由：原生 `write` 会丢掉 UTF-8 BOM 并把 CRLF 文件改写成 LF，原生 `edit` 也会丢掉 BOM；',
+    '# 这两个工具把 BOM 与行尾都保住，另外带上 dry-run diff、落盘前备份、编辑台账、grep/lines 锚点',
+    '# 与"匹配失败给最接近候选"。实现是**进程内 Node**：零依赖、零外部运行时、每次调用没有进程',
+    '# 启动开销（不启动任何解释器或外部命令）。',
+    '#',
+    '# 原生 `edit`/`write` **保留不动**：本行注册的是两个**不同名**工具，同一层不会同名冲突，',
+    '# 想回退只需给这一行加 `disabled: true`（或整行删掉）。',
+    '#',
+    '# 本文件由 `scripts/install-preset.mjs` 生成：源 = 本机 dsh 自带的 preset 组合',
+    `#   ${sourcePath}`,
+    '# 行名写的是本仓库 `lib/editor.mjs` 的绝对路径 —— preset 行的**裸包名**会从宿主组装基址解析，',
+    '# 但模块**内部的**裸 import 由 Node 按文件真实路径解析，而 preset 目录下没有 node_modules，',
+    '# 所以该插件刻意零依赖（只用 node: 内置模块），可以放在任何位置。',
+    '#',
+    '# 该插件消费宿主服务（tools / systemPrompt），不发布任何服务，因此不需要 isolate realm。',
+    '#',
+    '# 可选 config（插件没有 Config schema，字段原样透传）：',
+    '#   backup / ledger: boolean   默认都 true（备份到 artifactsDir/backups，台账 artifactsDir/edits.log）',
+    '#   artifactsDir: <路径>       默认 <会话工作区>/.dsh',
+    '#   newFileBom: boolean        默认 false（新建文件是否写 BOM）',
+    '#   context: number            diff 上下文行数，默认 3',
+    '#   root: <路径>               没有 agent 会话时的回退工作区',
+    '- id: tool-text-editor',
+    `  name: '${PLUGIN}'`,
+    '',
+  ].join('\n')
+}
+
+/** 插入位置：dsh 自带组合里"文件系统"之后、"后台任务"之前；找不到锚点就追加到末尾。 */
+const ANCHORS = [
+  { pattern: /^# ── background jobs/m, label: 'background jobs 段之前' },
+  { pattern: /^- id: tool-jobs$/m, label: 'tool-jobs 行之前' },
+]
+
+/**
+ * 把插件段插进源组合。
+ * @returns `{ text, anchor }`
+ * @throws {Error} 源组合看起来已经打过补丁时。
+ */
+function inject(source, sourcePath) {
+  if (/^- id: tool-text-editor$/m.test(source)) {
+    throw new Error('源组合里已经有 tool-text-editor 行了 —— 请指向 dsh 自带的原始组合')
+  }
+  const block = pluginBlock(sourcePath)
+  for (const { pattern, label } of ANCHORS) {
+    const match = pattern.exec(source)
+    if (match !== null) {
+      const at = match.index
+      return { text: source.slice(0, at) + block + '\n' + source.slice(at), anchor: label }
+    }
+  }
+  const separator = source.endsWith('\n') ? '\n' : '\n\n'
+  return { text: source + separator + block, anchor: '文件末尾' }
+}
+
+// ── 参数与前置检查 ──────────────────────────────────────────────────────────
+
+const id = flagValue('--id') ?? 'texteditor'
+const base = flagValue('--base') ?? 'standard'
+const force = process.argv.includes('--force')
+const dryRun = process.argv.includes('--dry-run')
+const fromFlag = flagValue('--from')
+
+if (!/^[a-z0-9][a-z0-9-]*$/.test(id)) {
+  console.error('FAIL preset id 必须是 [a-z0-9][a-z0-9-]*（会作为目录名），收到：' + id)
+  process.exit(2)
+}
+if (!/^[a-z0-9][a-z0-9-]*$/.test(base)) {
+  console.error('FAIL --base 必须是 dsh 自带 preset 的 id（如 standard / code / minimal），收到：' + base)
+  process.exit(2)
+}
+if (!existsSync(PLUGIN)) {
+  console.error('FAIL 找不到插件文件：' + PLUGIN)
+  process.exit(1)
+}
+if (!existsSync(META)) {
+  console.error('FAIL 找不到 preset 元数据：' + META)
+  process.exit(1)
+}
+
+const candidates = findCompositions(base)
+const sourcePath = candidates.find((candidate) => existsSync(candidate))
+if (sourcePath === undefined) {
+  console.error(`FAIL 找不到本机 dsh 自带的 preset 组合（--base ${base}）；试过：`)
+  for (const candidate of candidates) console.error('  ' + candidate)
+  console.error('     装了 dsh 就有；也可以用 --from <agent.cordis.yml 路径> 或 DSH_PRESET_SOURCE 指定。')
+  process.exit(2)
+}
+
+const source = readFileSync(sourcePath, 'utf8')
+let injected
+try {
+  injected = inject(source, sourcePath)
+} catch (error) {
+  console.error('FAIL ' + error.message)
+  process.exit(2)
+}
+
+const dshHome = process.env.DSH_HOME && process.env.DSH_HOME.trim() !== ''
+  ? process.env.DSH_HOME.trim()
+  : join(homedir(), '.dsh')
+const targetDir = join(dshHome, '.agent-presets', id)
+const targetComposition = join(targetDir, COMPOSITION)
+const targetMeta = join(targetDir, 'preset.yml')
+
+console.log('仓库        : ' + REPO)
+console.log('插件        : ' + PLUGIN)
+console.log('源组合      : ' + sourcePath + (fromFlag === undefined && process.env.DSH_PRESET_SOURCE === undefined ? `（--base ${base}）` : ''))
+console.log('插入位置    : ' + injected.anchor)
+console.log('DSH_HOME    : ' + dshHome)
+console.log('目标 preset : ' + targetDir)
+
+const exists = existsSync(targetComposition)
+
+if (dryRun) {
+  console.log('')
+  console.log('[dry-run] 会写入：')
+  console.log('  ' + targetComposition + `（源组合 ${source.split('\n').length} 行 + 插件段）`)
+  console.log('  ' + targetMeta)
+  if (exists && !force) {
+    console.error('')
+    console.error('[dry-run] 但目标已存在，真跑会被拒绝：' + targetComposition)
+    console.error('          要覆盖请加 --force（只覆盖 agent.cordis.yml 与 preset.yml，同目录其它文件不动）。')
+    process.exit(1)
+  }
+  process.exit(0)
+}
+
+if (exists && !force) {
+  console.error('')
+  console.error('FAIL 该 preset 已存在：' + targetComposition)
+  console.error('      要覆盖请加 --force（只覆盖 agent.cordis.yml 与 preset.yml，同目录其它文件不动）。')
+  process.exit(1)
+}
+if (exists) {
+  console.log('注意        : --force 将覆盖 ' + targetComposition)
+}
+
+mkdirSync(targetDir, { recursive: true })
+writeFileSync(targetComposition, injected.text, 'utf8')
+writeFileSync(targetMeta, readFileSync(META, 'utf8'), 'utf8')
+
+console.log('')
+console.log('OK 已安装 preset "' + id + '"')
+console.log('下一步：')
+console.log('  1. 重启 dsh web（preset 名单在启动时读取；运行中的会话不会换 preset）')
+console.log('  2. 新建一个会话，preset 选 "' + id + '"')
+console.log('  3. 会话里直接用 edit_text / write_text（纯 Node 进程内实现：零依赖、零外部运行时）')
+console.log('升级 dsh 后重跑本脚本（加 --force）即可让 preset 跟上新版自带组合。')
+console.log('回退：给 ' + targetComposition + ' 里的 tool-text-editor 行加 disabled: true，或删掉 ' + targetDir)