dsh-config-manager 0.1.78 → 0.1.79

package/src/core/text-fidelity.test.ts

@@ -0,0 +1,189 @@
+/**
+ * 文本保真原语的单元测试（2026-10-18 保真缺陷）：**保真只能靠字节证明**。
+ *
+ * 每条断言都用**真实字节**收口 —— 尤其是判据 1（decode ∘ encode 逐字节恒等），
+ * 因为「函数返回了 ok:true」对「文件没被写坏」不构成任何证据。
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  decodeTextBytes,
+  encodeTextBytes,
+  isUtf8RoundTrippable,
+  probeTextForm,
+  type TextShape,
+} from './text-fidelity.ts'
+
+const enc = (text: string): number[] => [...new TextEncoder().encode(text)]
+/** 组装字节：可选 BOM 前缀 + 文本的 UTF-8 字节 */
+const bytesOf = (text: string, bom = false): number[] => [...(bom ? [0xef, 0xbb, 0xbf] : []), ...enc(text)]
+
+/** 断言「可解码」并取出文本与形态（失败即测试失败，不做 any 兜底） */
+function decodeOk(bytes: number[] | Uint8Array): { text: string; shape: TextShape } {
+  const result = decodeTextBytes(bytes instanceof Uint8Array ? bytes : Uint8Array.from(bytes))
+  if (!result.ok) throw new Error('期望解码成功，实际被拒：' + result.reason)
+  return { text: result.text, shape: result.shape }
+}
+
+/** 断言「被拒绝」并回传 reason */
+function decodeReason(bytes: number[] | Uint8Array): 'binary' | 'non-utf8' {
+  const result = decodeTextBytes(bytes instanceof Uint8Array ? bytes : Uint8Array.from(bytes))
+  if (result.ok) throw new Error('期望被拒绝，实际解码成功：' + JSON.stringify(result.text))
+  return result.reason
+}
+
+/** 判据 1：解码再编码必须逐字节回到原字节 */
+function assertByteExactRoundTrip(bytes: number[], label: string): void {
+  const decoded = decodeOk(bytes)
+  const again = encodeTextBytes(decoded.text, decoded.shape)
+  assert.deepEqual([...again], bytes, label + '：decode ∘ encode 必须逐字节恒等')
+}
+
+test('F-01 空文件：0 字节可解码、形态取缺省、往返仍是 0 字节', () => {
+  const { text, shape } = decodeOk([])
+  assert.equal(text, '')
+  assert.deepEqual(shape, { eol: '\n', bom: false })
+  assert.deepEqual([...encodeTextBytes(text, shape)], [])
+})
+
+test('F-02 单行无尾换行：可往返，主导行尾取缺省 LF', () => {
+  const bytes = bytesOf('const a = 1')
+  const { text, shape } = decodeOk(bytes)
+  assert.equal(text, 'const a = 1')
+  assert.equal(shape.eol, '\n')
+  assertByteExactRoundTrip(bytes, 'F-02')
+})
+
+test('F-03 LF 多行 + 尾换行：主导行尾 LF', () => {
+  const bytes = bytesOf('a\nb\nc\n')
+  const { text, shape } = decodeOk(bytes)
+  assert.equal(text, 'a\nb\nc\n')
+  assert.equal(shape.eol, '\n')
+  assertByteExactRoundTrip(bytes, 'F-03')
+})
+
+test('F-04 CRLF：text 原样保留 CRLF（不改写行尾）、主导行尾 CRLF、往返逐字节相同', () => {
+  const bytes = bytesOf('a\r\nb\r\nc\r\n')
+  const { text, shape } = decodeOk(bytes)
+  assert.equal(text, 'a\r\nb\r\nc\r\n', 'decode 绝不把 CRLF 折成 LF')
+  assert.equal(shape.eol, '\r\n')
+  assertByteExactRoundTrip(bytes, 'F-04')
+})
+
+test('F-05 混合行尾：主导取严格多者、text 逐字节保留混合形态（往返仍恒等）', () => {
+  // 2 个 CRLF + 1 个 LF ⇒ 主导 CRLF
+  const bytes = bytesOf('a\r\nb\r\nc\nd\r\n')
+  const { text, shape } = decodeOk(bytes)
+  assert.equal(shape.eol, '\r\n')
+  assert.equal(text, 'a\r\nb\r\nc\nd\r\n')
+  assert.equal(probeTextForm(text).eols.length, 2, '如实报告「两种行尾都出现过」')
+  assertByteExactRoundTrip(bytes, 'F-05')
+  // 反例方向：2 个 LF + 1 个 CRLF ⇒ 主导 LF
+  const reversed = bytesOf('a\nb\nc\r\nd\n')
+  assert.equal(decodeOk(reversed).shape.eol, '\n')
+  assertByteExactRoundTrip(reversed, 'F-05b')
+})
+
+test('F-06 混合行尾平局（1 CRLF + 1 LF）⇒ 取 LF（不猜、且往返恒等）', () => {
+  const bytes = bytesOf('a\r\nb\nc\n')
+  const { shape } = decodeOk(bytes)
+  assert.equal(shape.eol, '\n', '严格多者胜：相等时回落到 LF')
+  assertByteExactRoundTrip(bytes, 'F-06')
+})
+
+test('F-07 带 BOM：decode 剥掉 3 字节 BOM 并记账，encode 原样补回（逐字节恒等）', () => {
+  const bytes = bytesOf('a\r\nb\r\n', true)
+  const { text, shape } = decodeOk(bytes)
+  assert.equal(shape.bom, true)
+  assert.equal(text, 'a\r\nb\r\n', '正文里不再残留 U+FEFF')
+  assert.equal(text.startsWith('\uFEFF'), false)
+  assert.deepEqual([...encodeTextBytes(text, shape)].slice(0, 3), [0xef, 0xbb, 0xbf])
+  assertByteExactRoundTrip(bytes, 'F-07')
+})
+
+test('F-08 无 BOM：shape.bom 为 false，encode 不加前缀', () => {
+  const bytes = bytesOf('a\nb\n')
+  const { shape } = decodeOk(bytes)
+  assert.equal(shape.bom, false)
+  assert.deepEqual([...encodeTextBytes('x', { eol: '\n', bom: false })], [0x78])
+})
+
+test('F-09 Latin-1（0xE9）⇒ non-utf8（fail-closed，绝不按 U+FFFD 读出再写回）', () => {
+  // "café" 的 Latin-1 字节：0xE9 不是合法 UTF-8 起始字节
+  assert.equal(decodeReason([0x63, 0x61, 0x66, 0xe9]), 'non-utf8')
+})
+
+test('F-10 GBK 中文（D6 D0 CE C4）⇒ non-utf8', () => {
+  assert.equal(decodeReason([0xd6, 0xd0, 0xce, 0xc4]), 'non-utf8')
+})
+
+test('F-11 UTF-16LE 带 BOM（FF FE …）⇒ non-utf8', () => {
+  assert.equal(decodeReason([0xff, 0xfe, 0x2d, 0x4e, 0x87, 0x65]), 'non-utf8')
+})
+
+test('F-12 已知口径：无 BOM 且恰好也是合法 UTF-8 的 UTF-16LE 不做猜测（往返仍恒等 ⇒ 不会写坏字节）', () => {
+  // '你好' 的 UTF-16LE = 60 4F 7D 59 —— 4 个合法 ASCII 字节，字节层面无法与 UTF-8 区分。
+  const bytes = [0x60, 0x4f, 0x7d, 0x59]
+  const { text, shape } = decodeOk(bytes)
+  assert.deepEqual([...text].map((char) => char.charCodeAt(0)), bytes, '不猜编码：按 UTF-8 如实读出')
+  assert.deepEqual([...encodeTextBytes(text, shape)], bytes, '关键：往返逐字节相同，绝不写坏')
+  assertByteExactRoundTrip(bytes, 'F-12')
+})
+
+test('F-13 含 NUL ⇒ binary（口径 = 前 8 KiB，与既有实现一致）', () => {
+  assert.equal(decodeReason([0x61, 0x00, 0x62]), 'binary')
+  assert.equal(decodeReason([0x00]), 'binary')
+  // 边界：第 8193 个字节才是 NUL —— 与既有「前 8 KiB」口径一致，不额外扩大判定
+  const late = [...enc('a'.repeat(8192)), 0x00]
+  assert.equal(decodeOk(late).text.length, 8193)
+})
+
+test('F-14 孤立 CR（老 Mac 行尾）⇒ non-utf8（TextShape 表示不了 ⇒ 拒绝，绝不悄悄改成 LF）', () => {
+  assert.equal(decodeReason(bytesOf('a\rb\r')), 'non-utf8')
+  // 但 CRLF 里的 CR 不算孤立
+  assert.equal(decodeOk(bytesOf('a\r\nb')).shape.eol, '\r\n')
+})
+
+test('F-15 表驱动：判据 1（逐字节恒等）覆盖 LF / CRLF / 混合 / BOM / 中文 / emoji / 空行', () => {
+  const fixtures: Array<{ label: string; bytes: number[] }> = [
+    { label: '空文件', bytes: [] },
+    { label: '只有换行', bytes: bytesOf('\n') },
+    { label: '空行夹杂', bytes: bytesOf('a\n\nb\n') },
+    { label: '中文 LF', bytes: bytesOf('你好\n世界\n') },
+    { label: 'emoji（合法代理对）', bytes: bytesOf('ok 😀 done\n') },
+    { label: 'CRLF 中文', bytes: bytesOf('你好\r\n世界\r\n') },
+    { label: 'BOM + CRLF', bytes: bytesOf('a\r\nb\r\n', true) },
+    { label: 'BOM + 中文 LF', bytes: bytesOf('你好\n', true) },
+    { label: '混合行尾', bytes: bytesOf('a\r\nb\nc\r\n') },
+    { label: '单行无尾换行', bytes: bytesOf('x = 1') },
+    { label: '尾随空行', bytes: bytesOf('a\n\n') },
+  ]
+  for (const fixture of fixtures) assertByteExactRoundTrip(fixture.bytes, 'F-15 ' + fixture.label)
+})
+
+test('F-16 代理项判据：合法代理对不误判，孤立代理项必须判 false', () => {
+  assert.equal(isUtf8RoundTrippable('😀'), true)
+  assert.equal(isUtf8RoundTrippable('\uD83D\uDE00'), true)
+  assert.equal(isUtf8RoundTrippable('\uD83D'), false, '孤立高代理项')
+  assert.equal(isUtf8RoundTrippable('\uDE00'), false, '孤立低代理项')
+  assert.equal(isUtf8RoundTrippable('a\uD83Db'), false, '高代理项后面不是低代理项')
+  // 这就是必须拒绝的原因：TextEncoder 会把孤立代理项写成 U+FFFD（内容损毁）
+  assert.deepEqual([...new TextEncoder().encode('\uD83D')], [0xef, 0xbf, 0xbd])
+})
+
+test('F-17 encodeTextBytes：bom=false 不动字节；bom=true 恰好加 3 字节前缀且不改行尾', () => {
+  const text = 'a\r\nb'
+  assert.deepEqual([...encodeTextBytes(text, { eol: '\n', bom: false })], enc(text), 'eol 不参与字节生成')
+  assert.deepEqual([...encodeTextBytes(text, { eol: '\r\n', bom: false })], enc(text))
+  assert.deepEqual([...encodeTextBytes(text, { eol: '\n', bom: true })], [0xef, 0xbb, 0xbf, ...enc(text)])
+})
+
+test('F-18 probeTextForm：纯描述（主导行尾 / BOM 前缀 / 出现过的行尾 / 孤立 CR 计数）', () => {
+  assert.deepEqual(probeTextForm('a\nb\n'), { eol: '\n', bom: false, eols: ['\n'], loneCr: 0 })
+  assert.deepEqual(probeTextForm('a\r\nb\r\n'), { eol: '\r\n', bom: false, eols: ['\r\n'], loneCr: 0 })
+  assert.deepEqual(probeTextForm('a\r\nb\n'), { eol: '\n', bom: false, eols: ['\r\n', '\n'], loneCr: 0 })
+  assert.deepEqual(probeTextForm('a\rb'), { eol: '\n', bom: false, eols: [], loneCr: 1 })
+  assert.deepEqual(probeTextForm('\uFEFFa\n'), { eol: '\n', bom: true, eols: ['\n'], loneCr: 0 })
+  assert.deepEqual(probeTextForm(''), { eol: '\n', bom: false, eols: [], loneCr: 0 })
+})

package/src/core/text-fidelity.ts

@@ -0,0 +1,197 @@
+/**
+ * 文本保真（text fidelity）—— 字节 ↔ 文本的**无损往返**与「形态」（行尾 / BOM）判定。
+ *
+ * 为什么需要它（2026-10-18 保真缺陷）：
+ *  回滚 / 跨对话三方合并是**文本**级算法，但工作区文件是**字节**。用 'Buffer.toString("utf8")' 去解一个
+ *  GBK / Latin-1 文件**不会抛错**（非法字节被替换成 U+FFFD），合并结果再按 UTF-8 写回 ⇒ 原文件被
+ *  **mojibake 覆盖、内容不可逆损毁**。换行符同理：把 CRLF 折成 LF 再 join('\n')，整份文件的行尾被
+ *  静默改写（Windows 上 = 全文件 diff）。
+ *
+ * 两条硬规矩：
+ *  ① **无损或拒绝**：解出来的文本必须能逐字节编码回原字节（decodeTextBytes 自己证明这一点，见判据 1）；
+ *     做不到就 ok:false，调用方必须**零写入** —— 绝不「差不多就行」。
+ *  ② **形态不猜**：行尾只有 '\n' | '\r\n' 两种可无损表示的形式；孤立 '\r'（老 Mac 风格）无法用它们表示
+ *     ⇒ 同样 ok:false，而不是悄悄把它当 LF 写掉。
+ *
+ * ── 归一化口径（**唯一的契约**，判据 1 就建立在这三条上）──
+ *  · decodeTextBytes **只做一件事**：剥掉开头的 UTF-8 BOM（EF BB BF）。**不改写任何行尾** ——
+ *    返回的 text 里 CRLF / LF 原样保留，因此**混合行尾**的文件也能逐字节往返。
+ *  · shape.eol 描述这份文本的**主导行尾**（完整的 CRLF 数**严格多于**纯 LF 数时为 '\r\n'；
+ *    相等 / 没有整行行尾 / 空文本一律 '\n'）。它供「需要新建行」的一方（三方合并）决定输出行尾，
+ *    **不影响** encodeTextBytes 的字节。
+ *  · encodeTextBytes(text, shape) **只做一件事**：shape.bom 为真时补回 3 字节 BOM。**不改写任何行尾**。
+ *    于是恒有 encodeTextBytes(d.text, d.shape) 逐字节等于原始 bytes（d = decodeTextBytes(bytes)）。
+ *  · 行尾的**归一化只发生在三方合并**（rollback-merge.ts）：输出按 shape.eol 统一，并用 eolMixed /
+ *    eolRewritten 如实标注，绝不假装「原样保留」。
+ *
+ * ── 已知口径（**不猜、不谎报**）──
+ *  · 前 8 KiB 出现 NUL 字节 ⇒ 'binary'（与 utils/line-diff.ts、rollback-point.ts 同一口径）。
+ *  · 非法 UTF-8（超长编码、孤立代理项的 CESU/WTF-8 编码、UTF-16 的 FF FE 前缀等）⇒ 'non-utf8'。
+ *  · 「恰好也是合法 UTF-8 的无 BOM UTF-16LE」在**字节层面无法与 UTF-8 区分**（例：UTF-16LE 的
+ *    你好 = 60 4F 7D 59，是 4 个合法 ASCII 字节）。本模块**不猜编码**：它会被当作合法 UTF-8 读出，
+ *    但往返仍逐字节相同 ⇒ **不会写坏字节**（要「猜编码」需要额外启发式，那才是真正的越权）。
+ */
+
+/** 行尾形态：只有 LF 与 CRLF 两种能被无损表示的换行符（孤立 CR 一律拒绝，见模块头 ②）。 */
+export type TextEol = '\n' | '\r\n'
+
+/** 一份文本的「形态」：主导行尾 + 是否带 UTF-8 BOM。 */
+export interface TextShape {
+  /** 主导行尾（严格多者胜；相等 / 无行尾 / 空文本 ⇒ '\n'） */
+  eol: TextEol
+  /** 是否带 UTF-8 BOM（EF BB BF） */
+  bom: boolean
+}
+
+/** 已解码文本的形态探测结果（合并侧用：只如实描述，不做任何改写）。 */
+export interface TextForm extends TextShape {
+  /** 这份文本里**出现过**的行尾风格（同一份文件可能两种都有 ⇒ 长度为 2） */
+  eols: TextEol[]
+  /** 孤立 CR（其后不是 LF）的个数；> 0 ⇒ 行尾无法用 TextShape 无损表示 */
+  loneCr: number
+}
+
+/** 解码结论。ok:false 时调用方必须**零写入**（绝不 mojibake 写回）。 */
+export type DecodeTextResult =
+  | { ok: true; text: string; shape: TextShape }
+  | { ok: false; reason: 'binary' | 'non-utf8' }
+
+/** NUL 探测窗口（与 line-diff / rollback-point 同口径：只看前 8 KiB） */
+const NUL_PROBE_BYTES = 8192
+
+/** UTF-8 BOM 字节 */
+const UTF8_BOM = new Uint8Array([0xef, 0xbb, 0xbf])
+
+/** 解码器：fatal = 非法 UTF-8 直接抛错（不替换成 U+FFFD）；ignoreBOM = 不代我们剥 BOM（剥与不剥由本模块决定）。 */
+const UTF8_DECODER = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true })
+
+const UTF8_ENCODER = new TextEncoder()
+
+/** 前 8 KiB 是否出现 NUL 字节（与既有 binary 判据一致） */
+function containsNul(bytes: Uint8Array): boolean {
+  const head = bytes.subarray(0, NUL_PROBE_BYTES)
+  for (let i = 0; i < head.length; i += 1) {
+    if (head[i] === 0) return true
+  }
+  return false
+}
+
+/** 是否以 UTF-8 BOM（EF BB BF）开头 */
+function startsWithUtf8Bom(bytes: Uint8Array): boolean {
+  return bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf
+}
+
+/** 逐字节相等（保真自证用） */
+function bytesEqual(left: Uint8Array, right: Uint8Array): boolean {
+  if (left.length !== right.length) return false
+  for (let i = 0; i < left.length; i += 1) {
+    if (left[i] !== right[i]) return false
+  }
+  return true
+}
+
+/**
+ * 文本能否无损编码成 UTF-8 字节。
+ * 唯一会失败的形态是**孤立代理项**（TextEncoder 会把它替换成 U+FFFD ⇒ 写回即内容损毁）。
+ */
+export function isUtf8RoundTrippable(text: string): boolean {
+  for (let i = 0; i < text.length; i += 1) {
+    const code = text.charCodeAt(i)
+    if (code >= 0xd800 && code <= 0xdbff) {
+      // 高代理项后面必须紧跟低代理项，否则是孤立代理项
+      const next = text.charCodeAt(i + 1)
+      if (!(next >= 0xdc00 && next <= 0xdfff)) return false
+      i += 1
+      continue
+    }
+    if (code >= 0xdc00 && code <= 0xdfff) return false
+  }
+  return true
+}
+
+/** 扫描行尾：完整 CRLF / 纯 LF / 孤立 CR 各计数（三者互斥） */
+function scanEol(text: string): { crlf: number; lf: number; loneCr: number } {
+  let crlf = 0
+  let lf = 0
+  let loneCr = 0
+  for (let i = 0; i < text.length; i += 1) {
+    const code = text.charCodeAt(i)
+    if (code === 13) {
+      if (text.charCodeAt(i + 1) === 10) {
+        crlf += 1
+        i += 1
+      } else {
+        loneCr += 1
+      }
+      continue
+    }
+    if (code === 10) lf += 1
+  }
+  return { crlf, lf, loneCr }
+}
+
+/**
+ * 探测一段**已解码文本**的形态：主导行尾、BOM 前缀、出现过的行尾风格、孤立 CR 计数。
+ * 纯描述、零改写（shape.eol 只用来决定「新建行」的行尾）。
+ */
+export function probeTextForm(text: string): TextForm {
+  const bom = text.startsWith('\uFEFF')
+  const body = bom ? text.slice(1) : text
+  const scan = scanEol(body)
+  const eols: TextEol[] = []
+  if (scan.crlf > 0) eols.push('\r\n')
+  if (scan.lf > 0) eols.push('\n')
+  return {
+    // 严格多者胜：相等 / 没有整行行尾 / 空文本 ⇒ '\n'
+    eol: scan.crlf > scan.lf ? '\r\n' : '\n',
+    bom,
+    eols,
+    loneCr: scan.loneCr,
+  }
+}
+
+/**
+ * 字节 → 文本（**无损或拒绝**）。
+ *
+ * 自证（判据 1）：成功时一定有 encodeTextBytes(result.text, result.shape) **逐字节等于**入参 bytes。
+ *
+ * 拒绝的两种形态（调用方**必须零写入**并按 reason 如实报告）：
+ *  · 'binary'：前 8 KiB 含 NUL（不是文本，行 / 合并算法对它没有定义）；
+ *  · 'non-utf8'：非法 UTF-8，或解码结果无法逐字节往返，或含孤立 CR（超出两种 EOL 的表示能力）。
+ */
+export function decodeTextBytes(bytes: Uint8Array): DecodeTextResult {
+  if (containsNul(bytes)) return { ok: false, reason: 'binary' }
+  const bom = startsWithUtf8Bom(bytes)
+  const body = bom ? bytes.subarray(UTF8_BOM.length) : bytes
+  let text: string
+  try {
+    text = UTF8_DECODER.decode(body)
+  } catch {
+    return { ok: false, reason: 'non-utf8' }
+  }
+  // 自证：解出来的文本必须能逐字节编码回原字节（防「解码器接受了、编码器却写不回」的边角形态）
+  if (!bytesEqual(UTF8_ENCODER.encode(text), body)) return { ok: false, reason: 'non-utf8' }
+  const form = probeTextForm(text)
+  // 孤立 CR：TextShape 表达不了 ⇒ 宁可拒绝，也绝不悄悄把它改成 LF
+  if (form.loneCr > 0) return { ok: false, reason: 'non-utf8' }
+  return { ok: true, text, shape: { eol: form.eol, bom } }
+}
+
+/**
+ * 文本 → 字节（**保真**）。
+ *
+ * 契约：text 必须是 decodeTextBytes 输出的形态（BOM 已剥）。本函数**不改写任何行尾**，只在
+ * shape.bom 为真时补回 3 字节 BOM ⇒ 与 decodeTextBytes 互逆（判据 1）。
+ *
+ * 注意：shape.eol 在这里**不参与**字节生成 —— 行尾归一化只发生在三方合并里；在这里归一化就意味着
+ * 混合行尾 / CRLF 文件无法逐字节往返。含孤立代理项的文本按 UTF-8 替换字符写出（与 TextEncoder 一致）：
+ * 调用方应先在 decodeTextBytes / mergeThreeWay 处把好关。
+ */
+export function encodeTextBytes(text: string, shape: TextShape): Uint8Array {
+  const body = UTF8_ENCODER.encode(text)
+  if (!shape.bom) return body
+  const out = new Uint8Array(body.length + UTF8_BOM.length)
+  out.set(UTF8_BOM, 0)
+  out.set(body, UTF8_BOM.length)
+  return out
+}

package/src/core/types.ts

@@ -248,9 +248,17 @@ export interface PluginInfo {
 
 export interface PluginsFacade {
   listInstalled(): Promise<PluginInfo[]>;
-  /** 安装/更新插件；spec 为来源记录的声明依赖 spec（如 github:user/repo），缺省按裸包名装 npm 最新版。
-   * signal 可选：中止时宿主应 kill 子进程并清理半装状态（恢复 package.json + 删 node_modules/<pkg>）。 */
-  install(pkg: string, spec?: string, signal?: AbortSignal): Promise<{ needsRestart: boolean }>;
+  /**
+   * 安装/更新插件。`target` 是**已经推导好的完整安装目标**（`name@1.2.3`、`github:user/repo`、
+   * `file:/abs/path.tgz`），由 `core/plugin-cli.ts` 的 `pluginInstallTarget()` 统一决策 ——
+   * 门面只负责执行，不再二次推导（否则「执行日志里写的」与「真正跑的命令」会分叉，issue #101）。
+   * 缺省按裸包名装 npm 最新版（旧调用方 / 旧备份）。
+   *
+   * `installedVersion`：安装后回读 `node_modules/<pkg>/package.json` 的实际版本（读不到为 null）。
+   * 调用方据此校验升级是否真的落地，而不是「子进程返回 0 就当成功」（issue #101）。
+   * signal 可选：中止时宿主应 kill 子进程并清理半装状态（恢复 package.json + 删 node_modules/<pkg>）。
+   */
+  install(pkg: string, target?: string, signal?: AbortSignal): Promise<{ needsRestart: boolean; installedVersion?: string | null }>;
 }
 
 export interface WorkspaceFacade {

package/src/core/update-check.ts

@@ -17,7 +17,7 @@
  * 不读代理设置（Node 的 fetch 默认不认 HTTP_PROXY/HTTPS_PROXY）：公司网络下可能直接失败 ——
  * 这时如实报「检查失败」，其余功能不受影响（本模块与插件主干零耦合）。
  */
-import { compareVersionStrings } from './validator.ts'
+import { compareVersionStrings, isConcreteVersion } from './validator.ts'
 
 /** 被检查的 npm 包名（= package.json 的 name；单点常量，勿在别处再写一份） */
 export const PLUGIN_NPM_PACKAGE = 'dsh-config-manager'
@@ -51,9 +51,6 @@ export type PluginUpdateResult =
   | { ok: true; info: PluginUpdateInfo; cached: boolean }
   | { ok: false; current: string; error: string }
 
-/** semver 形态判定（允许 1.2.3 / 1.2.3-rc.1 / 1.2.3+build；不允许多余字符） */
-const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/
-
 /**
  * 解析 registry 的 latest 响应体（只认 `{ version: 'x.y.z' }`）。
  * 畸形 / 缺字段 / 版本号不是 semver 形态 → null（调用方据此报「响应异常」，不猜）。
@@ -63,7 +60,7 @@ export function parseLatestVersion(payload: unknown): string | null {
   const version = (payload as Record<string, unknown>)['version']
   if (typeof version !== 'string') return null
   const trimmed = version.trim()
-  return SEMVER_RE.test(trimmed) ? trimmed : null
+  return isConcreteVersion(trimmed) ? trimmed : null
 }
 
 /**

package/src/core/validator.ts

@@ -49,6 +49,20 @@ export function compareVersionStrings(a: string, b: string): -1 | 0 | 1 {
   return compareVersions(parseVersion(a), parseVersion(b));
 }
 
+/**
+ * semver 形态判定（`1.2.3` / `1.2.3-rc.1` / `1.2.3+build`；区间 `^1.2.3`、dist-tag 与空串一律 false）。
+ *
+ * 与上面的 `compareVersionStrings` 分工不同：那个是**容错比较**（为了让 `0.2.1` 与 `0.2.1-rc.2`
+ * 也能排出大小，解析用宽松正则），这个是**严格形态判定** —— 只有它是具体版本时才允许拿来
+ * 拼 `<pkg>@<version>` 精确安装（issue #101）。导出为唯一实现，`self-update.ts`（是否接受目标
+ * 版本）与 `update-check.ts`（registry 返回值是否认得）都必须复用它，不许各留一份正则。
+ */
+export function isConcreteVersion(v: string): boolean {
+  return SEMVER_RE.test(v.trim());
+}
+
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+
 /**
  * 兼容性判定的**结构化原因**（与 `computeCompatibility` 同源：评分由本函数派生）。
  *