@flotiarenor/dsh-tool-text-editor 1.1.2 → 1.3.0

package/scripts/install-preset.mjs

@@ -2,22 +2,15 @@
 // SPDX-FileCopyrightText: 2026 Flotiarenor
 // SPDX-License-Identifier: Apache-2.0
 /**
- * install-preset.mjs —— 把 `edit_text` / `write_text` 装成一个**用户 preset**。
+ * install-preset.mjs —— 把 `edit_text` / `write_text` 装成一个用户 preset：读本机 dsh 自带的 preset 组合
+ * （默认 `standard`），插入 `tool-text-editor` 行，连同 `preset/preset.yml` 写到
+ * `<DSH_HOME>/.agent-presets/<id>/`。
  *
- * 做法：读**本机 dsh 自带的 preset 组合**（默认 `standard`），把 `tool-text-editor` 那一行插进去，
- * 再连同本仓库的 `preset/preset.yml` 写到 `<DSH_HOME>/.agent-presets/<id>/`。
+ * 组合必须从用户自己的 dsh 派生，不在仓库里放拷贝：自带组合是别人（MIT, Copyright (c) 2026 DeepSeek）的
+ * 作品，随包分发要连带履行其署名义务。
  *
- * 为什么不在仓库里放一份 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            # 只打印会做什么，不落盘
+ * 用法：`node scripts/install-preset.mjs [--id <id>] [--base <id>] [--from <组合路径>] [--force] [--dry-run]
+ * [--mask-native]`；`--id` 默认 `texteditor`，`--base` 默认 `standard`。
  *
  * 退出码：0 成功，1 失败，2 用法错误 / 找不到 dsh 自带的 preset 组合。
  */
@@ -30,8 +23,17 @@ 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 MASK = join(REPO, 'lib', 'mask.mjs').replace(/\\/g, '/')
 const META = join(REPO, 'preset', 'preset.yml')
-const SHIPPED_PRESET_DIR = ['config', 'agent-presets']
+/**
+ * 自带 preset 组合的两种布局（按版本从上到下试）：`@deepseek-ai/dsh/config/agent-presets/<base>/`
+ * （≤ 0.1.0-rc.6）与 `@deepseek-ai/dsh-agent-presets/presets/<base>/`（0.1.5-rc.2 起自带组合搬进另一个
+ * 包，该包按 `new URL('../presets/', import.meta.url)` 定位，旧路径在新版里已不存在）。
+ */
+const SHIPPED_LAYOUTS = [
+  ['dsh', 'config', 'agent-presets'],
+  ['dsh-agent-presets', 'presets'],
+]
 const COMPOSITION = 'agent.cordis.yml'
 
 function flagValue(name) {
@@ -39,30 +41,29 @@ function flagValue(name) {
   if (index < 0) return undefined
   const value = process.argv[index + 1]
   if (value === undefined || value.startsWith('--')) {
-    console.error('FAIL ' + name + ' 缺少取值')
+    console.error('FAIL ' + name + ' needs a value')
     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 候选绝对路径（按优先级）。
+ * 枚举自带 preset 组合的候选路径（dsh 可能装在任何位置，故不写死本机路径）：`--from` /
+ * `DSH_PRESET_SOURCE` → profile 的 node_modules（`<DSH_HOME>` 与默认 `~/.dsh` 都试：`DSH_HOME` 可能被指到
+ * 别处如临时目录，而 dsh 本体仍在默认 home 下）→ npm 全局前缀。
+ * @param explicitPath - 显式指定的源组合（已确认存在）。
  */
-function findCompositions(base) {
-  const candidates = []
-  const explicit = flagValue('--from') ?? process.env.DSH_PRESET_SOURCE
-  if (typeof explicit === 'string' && explicit !== '') candidates.push(resolve(explicit))
+function findCompositions(base, explicitPath, dshHome) {
+  const candidates = explicitPath === undefined ? [] : [explicitPath]
   const add = (nodeModules) => {
-    if (typeof nodeModules !== 'string' || nodeModules === '') return
-    candidates.push(join(nodeModules, '@deepseek-ai', 'dsh', ...SHIPPED_PRESET_DIR, base, COMPOSITION))
+    if (nodeModules === '') return
+    for (const layout of SHIPPED_LAYOUTS) {
+      candidates.push(join(nodeModules, '@deepseek-ai', ...layout, base, COMPOSITION))
+    }
+  }
+  for (const home of new Set([dshHome, join(homedir(), '.dsh')])) {
+    add(join(home, 'profiles', 'node_modules'))
   }
-  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')]
@@ -70,40 +71,64 @@ function findCompositions(base) {
   return candidates
 }
 
-/** 我们插进组合里的那一段（只有这一段是我们自己的文字 + 行）。 */
-function pluginBlock(sourcePath) {
-  return [
+/**
+ * 插进组合里的那一段（只有这一段是本仓库自己的文字与行）。
+ * @param sourcePath - 源组合路径（写进注释，便于升级后重跑）。
+ * @param maskNative - 是否插入屏蔽原生 write/edit 的门禁行，并让编辑行改用短引导。
+ * @returns 插件段文本（以单个换行结尾）。
+ */
+function pluginBlock(sourcePath, maskNative) {
+  const lines = [
     '# ── 字节保真的文本编辑工具（edit_text / write_text）─────────────────────────',
     '#',
-    '# 存在理由：原生 `write` 会丢掉 UTF-8 BOM 并把 CRLF 文件改写成 LF，原生 `edit` 也会丢掉 BOM；',
-    '# 这两个工具把 BOM 与行尾都保住，另外带上 dry-run diff、落盘前备份、编辑台账、grep/lines 锚点',
-    '# 与"匹配失败给最接近候选"。实现是**进程内 Node**：零依赖、零外部运行时、每次调用没有进程',
-    '# 启动开销（不启动任何解释器或外部命令）。',
+    '# 原生 `edit` / `write` 都会丢 UTF-8 BOM，且不还原文件自身的行尾（往 CRLF 文件写 LF 内容就变成 LF）；',
+    '# 原生 `edit` 还只做精确匹配（`old_string` 差一个空格就报 FS_EDIT_NOT_FOUND）。本行两个工具保 BOM 与文件',
+    '# 自身行尾，精确失败时按行块相似度回退并给出最接近的候选。read-only 会话下在任何 I/O 之前拒写；模型可见',
+    '# 文本只有一行统计。',
     '#',
-    '# 原生 `edit`/`write` **保留不动**：本行注册的是两个**不同名**工具，同一层不会同名冲突，',
-    '# 想回退只需给这一行加 `disabled: true`（或整行删掉）。',
+    ...(maskNative
+      ? ['# 原生 `edit`/`write` 由下面的门禁行按 agent 作用域屏蔽，本行因此改用 `guidance: short`。']
+      : ['# 原生 `edit`/`write` 保留不动：注册的是两个不同名工具，同一层不会同名冲突（回退：给本行加',
+        '# `disabled: true`，或整行删掉）。']),
     '#',
-    '# 本文件由 `scripts/install-preset.mjs` 生成：源 = 本机 dsh 自带的 preset 组合',
+    '# 由 `scripts/install-preset.mjs` 从本机 dsh 自带的 preset 组合派生：',
     `#   ${sourcePath}`,
-    '# 行名写的是本仓库 `lib/editor.mjs` 的绝对路径 —— preset 行的**裸包名**会从宿主组装基址解析，',
-    '# 但模块**内部的**裸 import 由 Node 按文件真实路径解析，而 preset 目录下没有 node_modules，',
-    '# 所以该插件刻意零依赖（只用 node: 内置模块），可以放在任何位置。',
-    '#',
-    '# 该插件消费宿主服务（tools / systemPrompt），不发布任何服务，因此不需要 isolate realm。',
+    '# 行名写绝对路径：preset 行的裸包名由宿主组装基址解析，模块内部的裸 import 由 Node 按文件真实路径解析，',
+    '# 而 preset 目录下没有 node_modules —— 该插件刻意零依赖（只用 node: 内置模块），可放任何位置。',
     '#',
     '# 可选 config（插件没有 Config schema，字段原样透传）：',
-    '#   backup / ledger: boolean   默认都 true（备份到 artifactsDir/backups，台账 artifactsDir/edits.log）',
-    '#   artifactsDir: <路径>       默认 <会话工作区>/.dsh',
     '#   newFileBom: boolean        默认 false（新建文件是否写 BOM）',
-    '#   context: number            diff 上下文行数，默认 3',
     '#   root: <路径>               没有 agent 会话时的回退工作区',
+    '#   guidance: full|short|false 默认 full；short 去掉"优先于原生"那半句',
     '- id: tool-text-editor',
     `  name: '${PLUGIN}'`,
-    '',
-  ].join('\n')
+    ...(maskNative ? ['  config:', '    guidance: short'] : []),
+  ]
+  if (maskNative) {
+    lines.push(
+      '',
+      '# ── 屏蔽原生的 write / edit（每个 agent 的作用域）──────────────────────────',
+      '#',
+      '# 原生两个工具仍在工具表里：每次请求付 1754 B 的两个 schema 加 608 B 的两段引导，只为劝模型别用它们。',
+      '# 本行按 agent 作用域收窄，三条通路任一条先到就先收窄（早先只挂 `agent/created`，而 GUI 是"先建 agent、',
+      '# 后换 preset"，重挂是父级 re-link，那个事件早已发完）：',
+      '#   * `apply` 阶段就挂守卫：与创建顺序无关，第一次直呼原生工具即被否决并顺手收窄；',
+      '#   * `agent/created`：建档时收窄本 preset 的 agent（含 subagent）；',
+      '#   * `tools/change`：换 preset 时 `recompose()` 发它，此时枚举活 agent 收窄属于本组合的，反向换出的成对撤销。',
+      '#',
+      '# 收窄用 `agent.ctx.tools.restrict({ deny })`：注册表只有一套可见性解析器，被拒的名字既不在工具表里也调不动',
+      '# （直呼得到 UNKNOWN_TOOL）；另注册同名空段遮蔽 tool:write / tool:edit 引导。只影响选了本 preset 的会话，',
+      '# 其它 preset 照旧可用（天然对照组）；只点名本 agent 真的看得见的工具，归属判据靠探测对象的身份。',
+      '# 回退：删掉本行，或给编辑行加 `guidance: full`。',
+      '- id: tool-native-edit-mask',
+      `  name: '${MASK}'`,
+    )
+  }
+  lines.push('')
+  return lines.join('\n')
 }
 
-/** 插入位置：dsh 自带组合里"文件系统"之后、"后台任务"之前；找不到锚点就追加到末尾。 */
+/** 插入位置：自带组合里"文件系统"之后、"后台任务"之前；找不到锚点就追加到末尾。 */
 const ANCHORS = [
   { pattern: /^# ── background jobs/m, label: 'background jobs 段之前' },
   { pattern: /^- id: tool-jobs$/m, label: 'tool-jobs 行之前' },
@@ -114,11 +139,11 @@ const ANCHORS = [
  * @returns `{ text, anchor }`
  * @throws {Error} 源组合看起来已经打过补丁时。
  */
-function inject(source, sourcePath) {
+function inject(source, sourcePath, maskNative) {
   if (/^- id: tool-text-editor$/m.test(source)) {
-    throw new Error('源组合里已经有 tool-text-editor 行了 —— 请指向 dsh 自带的原始组合')
+    throw new Error('the source composition already has a tool-text-editor row -- point at the unmodified composition shipped with dsh')
   }
-  const block = pluginBlock(sourcePath)
+  const block = pluginBlock(sourcePath, maskNative)
   for (const { pattern, label } of ANCHORS) {
     const match = pattern.exec(source)
     if (match !== null) {
@@ -130,59 +155,82 @@ function inject(source, sourcePath) {
   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')
+const maskNative = process.argv.includes('--mask-native')
+/** `--from` / `DSH_PRESET_SOURCE`：显式源组合，给定时不再枚举自带布局。 */
+const explicitSource = (flagValue('--from') ?? process.env.DSH_PRESET_SOURCE ?? '').trim()
+const explicitPath = explicitSource === '' ? undefined : resolve(explicitSource)
+/** 生效的用户目录：`DSH_HOME` 非空则用它，否则 `~/.dsh`。 */
+const dshHome = process.env.DSH_HOME?.trim() || join(homedir(), '.dsh')
 
 if (!/^[a-z0-9][a-z0-9-]*$/.test(id)) {
-  console.error('FAIL preset id 必须是 [a-z0-9][a-z0-9-]*（会作为目录名），收到：' + id)
+  console.error('FAIL the preset id must match [a-z0-9][a-z0-9-]* (it becomes a directory name), got: ' + id)
   process.exit(2)
 }
 if (!/^[a-z0-9][a-z0-9-]*$/.test(base)) {
-  console.error('FAIL --base 必须是 dsh 自带 preset 的 id（如 standard / code / minimal），收到：' + base)
+  console.error('FAIL --base must be the id of a preset shipped with dsh (standard / minimal / cordis / ptc), got: ' + base)
   process.exit(2)
 }
 if (!existsSync(PLUGIN)) {
-  console.error('FAIL 找不到插件文件：' + PLUGIN)
+  console.error('FAIL plugin file not found: ' + PLUGIN)
+  process.exit(1)
+}
+if (maskNative && !existsSync(MASK)) {
+  console.error('FAIL mask file not found: ' + MASK + ' (--mask-native needs it)')
   process.exit(1)
 }
 if (!existsSync(META)) {
-  console.error('FAIL 找不到 preset 元数据：' + META)
+  console.error('FAIL preset metadata not found: ' + META)
   process.exit(1)
 }
+if (explicitPath !== undefined && !existsSync(explicitPath)) {
+  console.error('FAIL --from / DSH_PRESET_SOURCE points at a composition that does not exist: ' + explicitPath)
+  process.exit(2)
+}
 
-const candidates = findCompositions(base)
+const candidates = findCompositions(base, explicitPath, dshHome)
 const sourcePath = candidates.find((candidate) => existsSync(candidate))
 if (sourcePath === undefined) {
-  console.error(`FAIL 找不到本机 dsh 自带的 preset 组合（--base ${base}）；试过：`)
+  console.error(`FAIL no preset composition shipped with the local dsh (--base ${base}); tried:`)
   for (const candidate of candidates) console.error('  ' + candidate)
-  console.error('     装了 dsh 就有；也可以用 --from <agent.cordis.yml 路径> 或 DSH_PRESET_SOURCE 指定。')
+  console.error('     installing dsh provides it; you can also point --from <agent.cordis.yml path> or DSH_PRESET_SOURCE at one.')
   process.exit(2)
 }
 
 const source = readFileSync(sourcePath, 'utf8')
 let injected
 try {
-  injected = inject(source, sourcePath)
+  injected = inject(source, sourcePath, maskNative)
 } 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')
+/**
+ * 写出的 `preset.yml` 必须与实际组合一致：仓库那份与模式无关，而"原生工具是否被屏蔽"随 `--mask-native` 变
+ * （旧版原样拷贝，开着门禁的描述里也写着"原生 edit/write 保持不变"）。状态句接在 `preset/preset.yml` 的最后
+ * 一行 `description:` 之后；它是 YAML 纯标量，不能出现 `: ` 或 ` #`。
+ */
+function metadataText() {
+  const state = maskNative
+    ? '；原生 `edit`/`write` 已被门禁行按 agent 作用域屏蔽：既不出现在工具表里，也调不动。'
+    : '；原生 edit/write 保持不变。'
+  return readFileSync(META, 'utf8').trimEnd() + state + '\n'
+}
+
 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}）` : ''))
+if (maskNative) console.log('门禁        : ' + MASK + '（屏蔽原生 write/edit，编辑行 guidance: short）')
+console.log('源组合      : ' + sourcePath + (explicitPath === undefined ? `（--base ${base}）` : ''))
 console.log('插入位置    : ' + injected.anchor)
 console.log('DSH_HOME    : ' + dshHome)
 console.log('目标 preset : ' + targetDir)
@@ -195,18 +243,18 @@ if (dryRun) {
   console.log('  ' + targetComposition + `（源组合 ${source.split('\n').length} 行 + 插件段）`)
   console.log('  ' + targetMeta)
   if (exists && !force) {
+    // 只预告冲突：dry-run 不落盘，退出码按契约仍为 0。
     console.error('')
-    console.error('[dry-run] 但目标已存在，真跑会被拒绝：' + targetComposition)
-    console.error('          要覆盖请加 --force（只覆盖 agent.cordis.yml 与 preset.yml，同目录其它文件不动）。')
-    process.exit(1)
+    console.error('[dry-run] but the target already exists, so a real run would be refused: ' + targetComposition)
+    console.error('          add --force to overwrite (only agent.cordis.yml and preset.yml are replaced; other files in that directory are left alone).')
   }
   process.exit(0)
 }
 
 if (exists && !force) {
   console.error('')
-  console.error('FAIL 该 preset 已存在：' + targetComposition)
-  console.error('      要覆盖请加 --force（只覆盖 agent.cordis.yml 与 preset.yml，同目录其它文件不动）。')
+  console.error('FAIL that preset already exists: ' + targetComposition)
+  console.error('      add --force to overwrite (only agent.cordis.yml and preset.yml are replaced; other files in that directory are left alone).')
   process.exit(1)
 }
 if (exists) {
@@ -215,7 +263,7 @@ if (exists) {
 
 mkdirSync(targetDir, { recursive: true })
 writeFileSync(targetComposition, injected.text, 'utf8')
-writeFileSync(targetMeta, readFileSync(META, 'utf8'), 'utf8')
+writeFileSync(targetMeta, metadataText(), 'utf8')
 
 console.log('')
 console.log('OK 已安装 preset "' + id + '"')
@@ -223,5 +271,10 @@ console.log('下一步：')
 console.log('  1. 重启 dsh web（preset 名单在启动时读取；运行中的会话不会换 preset）')
 console.log('  2. 新建一个会话，preset 选 "' + id + '"')
 console.log('  3. 会话里直接用 edit_text / write_text（纯 Node 进程内实现：零依赖、零外部运行时）')
+if (maskNative) {
+  console.log('     该 preset 的会话里原生 write/edit 既不出现在工具表里、也调不动（直呼得到 UNKNOWN_TOOL）；')
+  console.log('     想对比或观察原生行为，用别的 preset（如 standard）新建会话即可 —— 门禁只作用于本 preset。')
+}
 console.log('升级 dsh 后重跑本脚本（加 --force）即可让 preset 跟上新版自带组合。')
 console.log('回退：给 ' + targetComposition + ' 里的 tool-text-editor 行加 disabled: true，或删掉 ' + targetDir)
+if (maskNative) console.log('      只想撤掉屏蔽：删掉同文件里的 tool-native-edit-mask 行，并把编辑行的 guidance 改回 full。')