@kkutysllb/dsh-terminal 1.0.0 → 1.0.1

package/README.md

@@ -4,6 +4,27 @@
 
 自 KCoder 内置包独立发布的 dsh 插件（v1.0.0 起独立版本线）。
 
+## 真实终端语义（模式平移自 dsh-coding-sidebar 的 pty-deps / pty-manager）
+
+- **内核级伪终端**：node-pty `spawn`（macOS/Linux 走 forkpty，Windows 走
+  ConPTY），`TERM=xterm-256color` + `COLORTERM=truecolor`——vim/htop/
+  配色/交互程序完整可用；
+- **依赖降级**：node-pty 懒加载永不抛错；缺失/损坏时插件保持挂载，
+  `GET /dsh-terminal/api/deps` 返回 cause + 可粘贴修复命令，终端面板
+  渲染降级卡（复制 + 重试），不再无声失败；
+- **spawn-helper 修复**：插件激活时幂等补回包管理器剥掉的 macOS prebuilt
+  助手可执行位（缺失时每个 spawn 都会 `posix_spawnp failed`）；
+- **transcript 回放**：每标签服务端维护 1MB 环形缓冲；页面刷新/面板重建
+  后经 `snapshot` RPC 回放历史，回放在途的新输出由 client 侧 pending
+  队列保序（不重不漏）；restart 清空历史；
+- **shell 解析链**：POSIX `$SHELL` → passwd 登录 shell → `/bin/bash`；
+  Windows `DSH_TERMINAL_SHELL` → pwsh 探测链（PATH + 已知安装目录）→
+  `powershell.exe`；POSIX 以登录 shell 启动（读 profile 文件）。
+
+node-pty 版本契约：`^1.1.0`，与 DSH core（`@deepseek-ai/dsh-subprocess-local`）
+同 range——同 range 同 integrity 让 pnpm 两侧解析到同一物理包（一份
+native 绑定，无漂移）。
+
 ## 安装
 
 ```bash
@@ -18,7 +39,12 @@ dsh plugin install @kkutysllb/dsh-terminal
 ## 开发
 
 - 本仓为开发真源；改动后跑 `node scripts/sync-to-dsh-plugins.mjs` 同步 dsh-plugins 镜像并提交推送。
+- 本地跑真 pty 集成用例需 `node-pty` 可解析（开发目录可
+  `ln -sfn ~/.dsh/profiles/web/node_modules/node-pty node_modules/node-pty`）；
+  沙箱环境会拦 forkpty/exec（`posix_spawnp failed`），需在无沙箱终端跑。
 - `pnpm smoke`（prepack 自动）做契约形态校验；`node scripts/create-github-releases.mjs` 同步 release/ 到 GitHub Releases。
+- 单测：`node tests/run-tests.mjs`（依赖层 / shell 链 / transcript 回放 /
+  桶管理真 pty 用例）。
 
 ## 许可
 

package/client.js

@@ -13,6 +13,12 @@
  *   （client 直设，无需主进程 executeJavaScript）；
  * - 多标签：每标签一个 shell（server PtyHost 会话），"+" 新建、× 关闭、
  *   restart 重建；隐藏标签持续收数据（SSE 全量广播按桶路由）；
+ * - 真实终端回放（模式平移自 dsh-coding-sidebar）：注册标签即拉服务端
+ *   transcript（snapshot RPC）回放历史——页面刷新/面板重建不再丢输出；
+ *   回放在途期间到达的 SSE 新帧进 pending 队列，历史写完再 flush（严格
+ *   保序，不重不漏）；
+ * - 依赖降级：开面板前探 /api/deps，node-pty 缺失/损坏时渲染降级卡
+ *   （原因 + 可复制的修复命令 + 重试），不再无声失败；
  * - header 上缘 4px 拖条调高（clamp + localStorage 持久化）；
  * - 右键菜单：复制/粘贴/清屏/新建/关闭（navigator.clipboard，页面
  *   同源权限；宿主 bridge IPC 不再存在）。
@@ -285,6 +291,16 @@ body[data-ds-dark-theme] #${BTN_ID}{color:rgba(232,234,237,.8)}
 .kt-menu button:hover{background:rgba(128,128,128,.18)}
 .kt-menu button:disabled{opacity:.35;cursor:default}
 .kt-menu .kt-sep{height:1px;margin:4px 6px}
+.kt-deps{position:absolute;inset:0;display:flex;flex-direction:column;gap:8px;padding:16px 20px;overflow:auto}
+.kt-deps-title{font-weight:700;font-size:13px}
+.kt-deps-cause{opacity:.75;font-size:12px;word-break:break-all}
+.kt-deps-cmd{display:flex;align-items:center;gap:8px}
+.kt-deps-cmd code{flex:0 1 auto;max-width:100%;overflow-x:auto;padding:4px 8px;border-radius:6px;background:rgba(128,128,128,.14);font:500 12px Menlo,Monaco,monospace;white-space:nowrap}
+.kt-deps-cmd button{all:unset;box-sizing:border-box;cursor:pointer;padding:3px 10px;border-radius:6px;font-weight:600;flex:none}
+.kt-deps-cmd button:hover{background:rgba(128,128,128,.25)}
+.kt-deps-note{opacity:.6;font-size:11px;max-width:640px}
+.kt-deps-retry{all:unset;box-sizing:border-box;cursor:pointer;align-self:flex-start;padding:5px 14px;border-radius:7px;font-weight:600;background:rgba(77,107,254,.15);color:#4D6BFE}
+.kt-deps-retry:hover{background:rgba(77,107,254,.28)}
 `
       document.head.append(style)
 
@@ -299,6 +315,23 @@ body[data-ds-dark-theme] #${BTN_ID}{color:rgba(232,234,237,.8)}
         return res.json()
       }
 
+      /* ---- node-pty 依赖状态（ok:true 缓存；不 ok 每次重查，修复后自然恢复） ---- */
+      let depsOk = null // null = 尚未查询
+      const fetchDeps = async () => {
+        if (depsOk === true) return { ok: true }
+        try {
+          const res = await fetch(`${API}/deps`)
+          const body = res.ok ? await res.json() : null
+          depsOk = body !== null && body !== undefined && body.ok === true
+          if (depsOk) return { ok: true }
+          return body != null && body.ok === false
+            ? body
+            : { ok: false, cause: 'deps ' + res.status, command: '' }
+        } catch (error) {
+          return { ok: false, cause: String(error?.message ?? error), command: '' }
+        }
+      }
+
       /* ---- 单工作区面板（平移 WorkspaceView + mountTerminal） ---- */
       const panels = new Map() // bucket → PanelState
       const xtermReady = ensureXterm()
@@ -334,6 +367,50 @@ body[data-ds-dark-theme] #${BTN_ID}{color:rgba(232,234,237,.8)}
         for (const st of panel.tabs.values()) st.term.options.theme = p.xterm
       }
 
+      /** 依赖降级面板（panel-shaped：与 layout/applyPalette/开合协议兼容）。 */
+      const ensureDepsPanel = (bucket, deps) => {
+        const root = el('div', 'kt-panel')
+        root.id = bucket === NO_WORKSPACE_KEY ? '__dsh_kc_term_panel' : '__dsh_kc_term_panel_deps_' + panels.size
+        const grip = el('div', 'kt-grip')
+        const header = el('div', 'kt-header')
+        const termHost = el('div', 'kt-term')
+        const exitBar = el('div', 'kt-exit')
+        const menu = el('div', 'kt-menu')
+        menu.style.display = 'none'
+        const card = el('div', 'kt-deps')
+        card.append(el('div', 'kt-deps-title', '终端依赖不可用（降级模式）'))
+        card.append(el('div', 'kt-deps-cause', deps.cause || 'node-pty 加载失败'))
+        const cmdRow = el('div', 'kt-deps-cmd')
+        const code = el('code', '', deps.command || 'dsh plugin install')
+        const copy = el('button', '', '复制')
+        copy.type = 'button'
+        copy.onclick = () => { void navigator.clipboard?.writeText(code.textContent ?? '').catch(() => {}) }
+        cmdRow.append(code, copy)
+        card.append(cmdRow)
+        if (deps.note) card.append(el('div', 'kt-deps-note', deps.note))
+        const retry = el('button', 'kt-deps-retry', '重试')
+        retry.type = 'button'
+        retry.onclick = () => {
+          depsOk = null
+          panels.delete(bucket)
+          root.remove()
+          show(bucket)
+        }
+        card.append(retry)
+        termHost.append(card)
+        root.append(grip, header, termHost, exitBar, menu)
+        // 挂 documentElement：上游 SPA 重渲染重写 body 不清外部节点（同教训）。
+        document.documentElement.append(root)
+        const panel = {
+          bucket, root, grip, header, termHost, exitBar, menu,
+          tabs: new Map(), activeId: -1, open: false, shown: false, loaded: true,
+          palette: null, depsMode: true,
+          resyncTabs: () => {},
+        }
+        panels.set(bucket, panel)
+        return panel
+      }
+
       /** 懒建指定工作区面板 DOM（vendor 就绪后；已存在直接返回）。 */
       const ensurePanel = async (bucket) => {
         let panel = panels.get(bucket)
@@ -344,6 +421,10 @@ body[data-ds-dark-theme] #${BTN_ID}{color:rgba(232,234,237,.8)}
           panel = undefined
         }
         if (panel !== undefined) return panel
+        // 依赖预检：node-pty 缺失/损坏时渲染降级卡（原因 + 修复命令 + 重试），
+        // 不再无声失败；修复后重试自然恢复。
+        const deps = await fetchDeps()
+        if (!deps.ok) return ensureDepsPanel(bucket, deps)
         // 现取而非用预热常量：预热失败置空 vendorPromise 后，这里重拉新 promise
         const { Terminal, FitAddon } = await ensureXterm()
         const root = el('div', 'kt-panel')
@@ -413,13 +494,29 @@ body[data-ds-dark-theme] #${BTN_ID}{color:rgba(232,234,237,.8)}
           x.innerHTML = '<svg viewBox="0 0 16 16" width="10" height="10" fill="none"><path d="m4.5 4.5 7 7m0-7-7 7" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/></svg>'
           tabEl.append(label, x)
           tabsBar.append(tabEl)
-          const st = { id: tab.id, term, fit, host, el: tabEl, exited: !tab.alive }
+          const st = { id: tab.id, term, fit, host, el: tabEl, exited: !tab.alive, replaying: true, pending: [], disposed: false }
           tabEl.dataset.exited = st.exited ? '1' : '0'
           tabEl.onclick = () => setActive(panel, st.id)
           x.onclick = e => { e.stopPropagation(); void closeTab(panel, st.id) }
           term.onData(data => { void rpc({ op: 'write', id: st.id, data }).catch(() => {}) })
           term.onResize(({ cols, rows }) => { void rpc({ op: 'resize', id: st.id, cols, rows }).catch(() => {}) })
           panel.tabs.set(st.id, st)
+          // 真实终端回放：注册即拉服务端 transcript 写历史（页面刷新/面板
+          // 重建后不再丢输出）。回放在途期间到达的 SSE 新帧进 pending，
+          // 历史写完统一 flush——严格保序，不重不漏。
+          void rpc({ op: 'snapshot', id: st.id }).then(out => {
+            if (st.disposed) return
+            if (out != null && out.ok && typeof out.chunk === 'string' && out.chunk !== '') {
+              try { st.term.write(out.chunk) } catch { /* term 已释放 */ }
+            }
+          }).catch(() => {}).finally(() => {
+            st.replaying = false
+            if (st.pending.length > 0) {
+              const queued = st.pending
+              st.pending = []
+              for (const c of queued) { try { st.term.write(c) } catch { break } }
+            }
+          })
           return st
         }
 
@@ -453,6 +550,7 @@ body[data-ds-dark-theme] #${BTN_ID}{color:rgba(232,234,237,.8)}
           if (st === undefined) return
           const out = await rpc({ op: 'close', id, cwd: p.bucket === NO_WORKSPACE_KEY ? '' : p.bucket }).catch(() => null)
           if (out === null) return
+          st.disposed = true
           st.term.dispose()
           st.host.remove()
           st.el.remove()
@@ -460,7 +558,7 @@ body[data-ds-dark-theme] #${BTN_ID}{color:rgba(232,234,237,.8)}
           // 对齐服务端剩余标签（防御：本地与远端应一致）
           const ids = new Set((out.tabs ?? []).map(t => t.id))
           for (const [kid, kst] of [...p.tabs]) {
-            if (!ids.has(kid)) { kst.term.dispose(); kst.host.remove(); kst.el.remove(); p.tabs.delete(kid) }
+            if (!ids.has(kid)) { kst.disposed = true; kst.term.dispose(); kst.host.remove(); kst.el.remove(); p.tabs.delete(kid) }
           }
           if (p.tabs.size === 0) {
             // 全部关闭 → 收起面板（下次打开 ensureFirst 新建全新会话）
@@ -476,7 +574,17 @@ body[data-ds-dark-theme] #${BTN_ID}{color:rgba(232,234,237,.8)}
 
         const newTab = async (p) => {
           const out = await rpc({ op: 'new', cwd: p.bucket === NO_WORKSPACE_KEY ? '' : p.bucket }).catch(() => null)
-          if (out === null || out.tab === undefined) return
+          if (out === null || out.tab === undefined) {
+            // 新建失败可能是 node-pty 缺失/损坏（spawn 加载失败）：探测 deps，
+            // 确认缺失则把面板替换为降级卡（修复命令 + 重试）。
+            const deps = await fetchDeps().catch(() => null)
+            if (deps !== null && !deps.ok) {
+              panels.delete(p.bucket)
+              if (p.root.isConnected) p.root.remove()
+              show(p.bucket)
+            }
+            return
+          }
           const st = registerTab(out.tab)
           setActive(p, st.id)
           st.term.focus()
@@ -491,6 +599,7 @@ body[data-ds-dark-theme] #${BTN_ID}{color:rgba(232,234,237,.8)}
           const freshIds = new Set(fresh.map(t => t.id))
           for (const [kid, kst] of [...p.tabs]) {
             if (!freshIds.has(kid)) {
+              kst.disposed = true
               kst.term.dispose(); kst.host.remove(); kst.el.remove(); p.tabs.delete(kid)
             }
           }
@@ -692,7 +801,13 @@ body[data-ds-dark-theme] #${BTN_ID}{color:rgba(232,234,237,.8)}
           if (msg === null || msg === undefined) return
           const p = panels.get(msg.bucket)
           if (p === undefined) return
-          if (msg.type === 'data') p.tabs.get(msg.id)?.term.write(msg.chunk)
+          if (msg.type === 'data') {
+            const st = p.tabs.get(msg.id)
+            if (st === undefined || st.disposed) return
+            // 回放在途：新帧先入 pending 队列，snapshot 历史写完再 flush。
+            if (st.replaying) st.pending.push(msg.chunk)
+            else st.term.write(msg.chunk)
+          }
           else if (msg.type === 'exit') {
             const st = p.tabs.get(msg.id)
             if (st === undefined) return

package/entry.js

@@ -4,32 +4,43 @@
  * 嵌入式终端 RPC（逻辑平移自退役宿主 desktop/main/pty-host.ts +
  * terminal-panel.ts，语义保持一致）：
  * - POST /dsh-terminal/api/rpc     pty 操作（tabs/new/write/resize/
- *   restart/close，cwd 为工作区桶键）
+ *   restart/close/snapshot，cwd 为工作区桶键）
  * - GET  /dsh-terminal/api/stream  SSE 输出流（data/exit 事件带 bucket，
  *   全局一条广播，client 按当前桶路由；15s 心跳防代理断连）
  * - GET  /dsh-terminal/api/vendor/<name>  xterm vendor 静态托管
  *   （client.js 自包含无 import，运行时懒拉 + eval；白名单三件）
+ * - GET  /dsh-terminal/api/deps    node-pty 依赖状态（降级模式：缺失时
+ *   返回 cause + 可粘贴的修复命令，前端渲染降级卡）
  *
  * 安全边界与 dsh-git-panel 同款：isTrusted（loopback 放行 +
  * webRuntime.trustedHosts）；写操作 POST-only；SSE 为只读推送。
  *
- * pty 引擎：node-pty（VS Code 同款），经 createRequire 从运行时
- * node_modules 解析（bundle 物化在 profiles/web/node_modules/@kcoder/
- * terminal/，向上可达 profiles/node_modules/node-pty——dsh-tool-bash
- * 已带）。延迟加载：模块导入不触发 native 绑定加载，首次 create 才
- * require，环境异常时报错仅影响终端功能不拖垮宿主。
+ * pty 引擎：node-pty（VS Code 同款，内核级伪终端 openpty/ConPTY），经
+ * createRequire 从运行时 node_modules 解析（bundle 物化在 profile 的
+ * node_modules 下，向上可达 profiles/node_modules/node-pty——dsh-tool-bash
+ * 已带）。真实终端健壮性（模式平移自 dsh-coding-sidebar 的 pty-deps/
+ * pty-manager）：
+ * - 懒加载永不抛错：模块导入不触发 native 绑定加载；加载失败缓存原因，
+ *   插件保持挂载（降级态），deps 路由给出修复命令，不拖垮宿主；
+ * - ensureSpawnHelper：补回包管理器剥掉的 spawn-helper 可执行位（缺失
+ *   时每个 spawn 都会 posix_spawnp failed），激活时幂等执行；
+ * - transcript 环形缓冲（1MB/标签）：页面刷新 / 面板重建后经 snapshot
+ *   RPC 回放历史，回放在途期间的新输出由 client 侧 pending 队列保序；
+ * - shell 解析链：$SHELL → passwd 登录 shell → bash 兜底；Windows 上
+ *   DSH_TERMINAL_SHELL env → pwsh 探测链 → powershell.exe 兜底。
  *
- * 纯逻辑（桶管理/参数校验）导出供 tests/run-tests.mjs node 直跑；
- * spawn 集成用例走真 pty。
+ * 纯逻辑（桶管理/参数校验/依赖层/shell 链）导出供 tests/run-tests.mjs
+ * node 直跑；spawn 集成用例走真 pty。
  *
  * @module @kkutysllb/dsh-terminal/entry
  */
 
 import { createRequire } from 'node:module'
 import { EventEmitter } from 'node:events'
-import { statSync } from 'node:fs'
-import { homedir } from 'node:os'
-import { basename } from 'node:path'
+import { chmodSync, existsSync, realpathSync, statSync } from 'node:fs'
+import { homedir, userInfo } from 'node:os'
+import { basename, dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { readFile } from 'node:fs/promises'
 
 /** client-modules 集成对应的 cordis 依赖：RPC 注册必需 webServer。 */
@@ -53,19 +64,250 @@ export const PANEL_MIN_H = 140
 export const PANEL_MAX_H = 620
 export const PANEL_DEFAULT_H = 280
 
-/** 延迟解析 node-pty（native 模块，导入期不加载）。 */
-let ptyModule = null
-function getPty() {
-  if (ptyModule === null) {
-    ptyModule = createRequire(import.meta.url)('node-pty')
+/* ---------------------------------------------------------------- *
+ * node-pty 依赖层（模式平移自 dsh-coding-sidebar src/pty-deps.ts）
+ * ---------------------------------------------------------------- */
+
+/**
+ * node-pty 版本契约：须与 DSH core（@deepseek-ai/dsh-subprocess-local）
+ * 声明同 range——同 range 同 integrity 让 pnpm 把两侧解析到同一物理包
+ * （一份 native 绑定，无漂移）。换 fork 或改 range 前先核对 core 声明。
+ */
+export const DSH_NODE_PTY_RANGE = '^1.1.0'
+
+/** 懒加载缓存：undefined=未加载；{ok:true,module} | {ok:false,cause}。 */
+let ptyLoadCache
+
+/**
+ * 加载 node-pty（同步、单次、永不抛错）。模块缺失、native 绑定损坏、
+ * pnpm 11 strict-dep-builds 跳过 install script 等都只会被记进缓存——
+ * 插件保持挂载（降级态），由 deps 路由给出修复命令。
+ */
+export function loadNodePty() {
+  if (ptyLoadCache === undefined) {
+    try {
+      ptyLoadCache = { ok: true, module: createRequire(import.meta.url)('node-pty') }
+    } catch (cause) {
+      ptyLoadCache = { ok: false, cause }
+    }
+  }
+  return ptyLoadCache.ok ? ptyLoadCache.module : null
+}
+
+/** 已记录的加载失败原因（成功或未加载时 undefined）。 */
+export function nodePtyLoadCause() {
+  return ptyLoadCache !== undefined && !ptyLoadCache.ok ? ptyLoadCache.cause : undefined
+}
+
+/** 加载失败的一行人读描述。 */
+function describeCause(cause) {
+  if (cause instanceof Error) return cause.message
+  return String(cause)
+}
+
+/** 加载 node-pty 或抛规范错误（create/restart 路径；消息指向 deps 路由）。 */
+function loadRequiredNodePty() {
+  const m = loadNodePty()
+  if (m === null) {
+    throw new Error(
+      'node-pty (' + DSH_NODE_PTY_RANGE + ') failed to load: ' + describeCause(nodePtyLoadCause())
+      + ' -- see GET ' + RPC_PREFIX + '/deps for the repair command',
+    )
+  }
+  return m
+}
+
+/** 解析到物理位置（symlink/link 安装），供 walk-up 探测。 */
+function realDir(file) {
+  try { return dirname(realpathSync(file)) } catch { return dirname(file) }
+}
+
+/** 从 dir 向上找满足条件的祖先根（限深 16 层）。 */
+function walkUp(dir, isRoot) {
+  let current = dir
+  for (let depth = 0; depth < 16; depth += 1) {
+    if (isRoot(current)) return current
+    const parent = dirname(current)
+    if (parent === current) break
+    current = parent
+  }
+  return null
+}
+
+/** 是否 DSH profile 根（package.json + pnpm-workspace.yaml 双证）。 */
+function isProfileRoot(dir) {
+  return existsSync(join(dir, 'package.json')) && existsSync(join(dir, 'pnpm-workspace.yaml'))
+}
+
+/**
+ * 探测本插件安装所在的 profile 目录：插件模块的最近双证祖先（profile
+ * 根，插件从其 node_modules 解析）；探测不到回退 $DSH_HOME/profiles/web
+ * （标准 web profile）；仍不像则 null。
+ */
+export function findProfileDir(fromFile = fileURLToPath(import.meta.url)) {
+  const detected = walkUp(realDir(fromFile), isProfileRoot)
+  if (detected !== null) return detected
+  const home = process.env.DSH_HOME !== undefined && process.env.DSH_HOME.trim() !== ''
+    ? process.env.DSH_HOME
+    : join(homedir(), '.dsh')
+  const web = join(home, 'profiles', 'web')
+  return isProfileRoot(web) ? realpathSync(web) : null
+}
+
+/**
+ * node-pty 安装损坏时的可粘贴修复命令。本插件不随包发 install 脚本
+ * （依赖 DSH core 侧的 node-pty），因此始终走 dsh plugin 重装兜底，
+ * 并附 allowBuilds 提示（pnpm 11 拦 native 构建 scripts 的常见病因）。
+ */
+export function buildRepairCommand(options = {}) {
+  const profileDir = options.profileDir !== undefined ? options.profileDir : findProfileDir()
+  const name = profileDir !== null ? basename(profileDir) : 'web'
+  return {
+    command: 'dsh plugin --profile "' + name + '" install',
+    note: "If pnpm 11 blocked node-pty's build script, ensure allowBuilds: node-pty: true"
+      + " in the profile's pnpm-workspace.yaml, then rerun the install command.",
   }
-  return ptyModule
+}
+
+/** deps 路由的响应形态：{ok:true} | {ok:false, cause, command, profile, note?}。 */
+export function depsStatus() {
+  const m = loadNodePty()
+  if (m !== null) return { ok: true }
+  const profileDir = findProfileDir()
+  const { command, note } = buildRepairCommand({ profileDir })
+  return {
+    ok: false,
+    cause: describeCause(nodePtyLoadCause()),
+    command,
+    profile: profileDir !== null ? basename(profileDir) : null,
+    note,
+  }
+}
+
+/**
+ * 补回包管理器剥掉的 spawn-helper 可执行位（平移自 dsh-coding-sidebar
+ * ensureSpawnHelper）：spawn-helper 是 macOS 侧 fork 并装配 pty 的
+ * prebuilt 助手，丢执行位时每个 spawn 都报 posix_spawnp failed。幂等；
+ * 解析或 chmod 失败静默——由 spawn 自身的报错暴露问题。
+ */
+export function ensureSpawnHelper() {
+  if (process.platform === 'win32') return
+  try {
+    const require = createRequire(import.meta.url)
+    const entry = require.resolve('node-pty')
+    const packageRoot = dirname(dirname(entry))
+    const candidates = [
+      join(packageRoot, 'prebuilds', process.platform + '-' + process.arch, 'spawn-helper'),
+      join(packageRoot, 'build', 'Release', 'spawn-helper'),
+    ]
+    for (const helper of candidates) {
+      if (existsSync(helper)) chmodSync(helper, 0o755)
+    }
+  } catch {
+    // 解析失败（依赖缺失）留给 deps 降级路径；chmod 失败由 spawn 报错暴露。
+  }
+}
+
+/* ---------------------------------------------------------------- *
+ * shell 解析链（平移自 dsh-coding-sidebar defaultShell 系）
+ * ---------------------------------------------------------------- */
+
+/**
+ * Windows 侧可能装着 pwsh.exe 的目录：PATH 条目优先，其后机器/用户级
+ * 已知安装位置（含 preview 通道与 per-user 布局）。机器级同时读
+ * ProgramW6432 与 ProgramFiles（32 位 Node 的 ProgramFiles 指向 (x86)，
+ * 仍要能找到 64 位 PowerShell 7）。去重且保持优先序。
+ */
+function windowsPwshCandidateDirs(env) {
+  const dirs = []
+  const pathEntries = env.PATH
+  if (pathEntries !== undefined) {
+    // win32 分支固定用 Windows PATH 分隔符；硬编码保证跨平台可测。
+    for (const entry of pathEntries.split(';')) {
+      const trimmed = entry.trim()
+      if (trimmed !== '') dirs.push(trimmed)
+    }
+  }
+  for (const programFiles of [env.ProgramW6432, env.ProgramFiles]) {
+    if (programFiles === undefined || programFiles.trim() === '') continue
+    dirs.push(join(programFiles, 'PowerShell', '7'))
+    dirs.push(join(programFiles, 'PowerShell', '7-preview'))
+  }
+  const localAppData = env.LOCALAPPDATA
+  if (localAppData !== undefined && localAppData.trim() !== '') {
+    dirs.push(join(localAppData, 'Microsoft', 'PowerShell', '7'))
+    dirs.push(join(localAppData, 'Microsoft', 'PowerShell', '7-preview'))
+    dirs.push(join(localAppData, 'Programs', 'PowerShell', '7'))
+    dirs.push(join(localAppData, 'Programs', 'PowerShell', '7-preview'))
+  }
+  return [...new Set(dirs)]
+}
+
+/**
+ * 交互 shell 解析（像终端模拟器那样）：
+ * - POSIX：$SHELL → passwd 登录 shell（userInfo().shell；服务管理器/
+ *   容器 init 常不带 SHELL 启动 dsh，这一步让标签仍开用户的登录 shell
+ *   而非静默降级 bash）→ /bin/bash 兜底；
+ * - Windows：DSH_TERMINAL_SHELL env → PATH/已知目录的 pwsh.exe 探测链
+ *   （PowerShell 7 用户不再拿到老 5.1）→ powershell.exe 兜底。
+ * options 显式传参仅供测试注入平台/env/存在性探测。
+ */
+export function defaultShell(options = {}) {
+  const platform = options.platform ?? process.platform
+  const env = options.env ?? process.env
+  const exists = options.exists ?? existsSync
+  if (platform === 'win32') {
+    const envShell = env.DSH_TERMINAL_SHELL
+    if (envShell !== undefined && envShell.trim() !== '') return envShell.trim()
+    for (const dir of windowsPwshCandidateDirs(env)) {
+      const candidate = join(dir, 'pwsh.exe')
+      if (exists(candidate)) return candidate
+    }
+    return 'powershell.exe'
+  }
+  const envShell = env.SHELL
+  if (envShell !== undefined && envShell.trim() !== '') return envShell.trim()
+  // uid 无 passwd 条目时 userInfo() 会抛（罕见 chroot）：兜底 /bin/bash。
+  try {
+    const loginShell = userInfo().shell
+    if (typeof loginShell === 'string' && loginShell.trim() !== '') return loginShell
+  } catch { /* 无 passwd 条目：落到 bash 兜底 */ }
+  return '/bin/bash'
+}
+
+/**
+ * spawn 参数：POSIX 走登录 shell（读 ~/.profile ~/.zprofile 等 profile
+ * 文件）；Windows PowerShell 不收登录旗标。显式传入时整体替换默认。
+ */
+export function shellSpawnArgs(configured = []) {
+  if (configured.length > 0) return [...configured]
+  return process.platform === 'win32' ? [] : ['-l']
+}
+
+/** 标签标题用的 shell 短名：/bin/zsh → zsh，C:\...\pwsh.exe → pwsh。 */
+export function shellDisplayName(shell) {
+  const normalized = shell.replace(/\\/g, '/')
+  const base = normalized.slice(normalized.lastIndexOf('/') + 1)
+  if (base === '') return shell
+  return base.replace(/\.(exe|cmd|bat)$/i, '')
+}
+
+/* ---------------------------------------------------------------- *
+ * transcript（回放缓冲；平移自 dsh-coding-sidebar 的环形裁剪语义）
+ * ---------------------------------------------------------------- */
+
+/** 单标签 transcript 上限（字符；超出丢头保尾）。 */
+export const TRANSCRIPT_LIMIT = 1 << 20
+
+/** 追加一块输出并裁剪到上限（纯函数，供测试）。 */
+export function appendTranscript(prev, chunk) {
+  const next = prev + chunk
+  return next.length > TRANSCRIPT_LIMIT ? next.slice(next.length - TRANSCRIPT_LIMIT) : next
 }
 
 /** 标签信息（tabs/rpc 响应；与宿主 TerminalTab 契约一致）。 */
 function tabOf(s) {
-  const shell = process.platform === 'win32' ? 'powershell.exe' : (process.env.SHELL || '/bin/zsh')
-  return { id: s.id, alive: !s.exited, cwd: s.cwd, title: basename(shell) }
+  return { id: s.id, alive: !s.exited, cwd: s.cwd, title: shellDisplayName(s.shell ?? defaultShell()) }
 }
 
 function killPty(s) {
@@ -102,6 +344,8 @@ export function clampH(h) {
  * （buckets = Map<cwd, Map<id, session>>），不同工作区互不干扰；
  * id 全局唯一跨桶可寻址；面板关闭仅隐藏不杀进程，restart 销毁重建
  * 同 id，close 关单标签。事件：data(chunk, id, bucket) / exit(id, bucket)。
+ * 每会话维护 transcript 环形缓冲（snapshot RPC 供 client 回放历史，
+ * 退出会话仍可回放）；spawn 失败时 create 回滚入桶、restart 如实标退出。
  */
 export class PtyHost {
   constructor() {
@@ -151,12 +395,17 @@ export class PtyHost {
     return null
   }
 
-  /** 新建标签到指定工作区桶（shell 进程立即启动）。 */
+  /** 新建标签到指定工作区桶（shell 进程立即启动；spawn 失败回滚入桶）。 */
   create(cwd) {
     const bucket = this.bucketOf(cwd)
-    const s = { id: this.nextId++, pty: null, cwd: usableDir(cwd) ?? homedir(), bucket, exited: false }
+    const s = { id: this.nextId++, pty: null, cwd: usableDir(cwd) ?? homedir(), bucket, exited: false, transcript: '', shell: null }
     this.bucket(bucket).set(s.id, s)
-    this.spawn(s)
+    try {
+      this.spawn(s)
+    } catch (error) {
+      this.bucket(bucket).delete(s.id)
+      throw error
+    }
     return tabOf(s)
   }
 
@@ -177,9 +426,17 @@ export class PtyHost {
     s.cwd = cwd
     s.bucket = bucket
     s.exited = false
+    s.transcript = ''
     for (const m of this.buckets.values()) m.delete(id)
     this.bucket(bucket).set(id, s)
-    this.spawn(s)
+    try {
+      this.spawn(s)
+    } catch (error) {
+      // 重建失败：标签如实标退出并发 exit（前端显示退出条），错误上抛给 rpc。
+      s.exited = true
+      this.events.emit('exit', s.id, s.bucket)
+      throw error
+    }
     return tabOf(s)
   }
 
@@ -197,6 +454,12 @@ export class PtyHost {
     }
   }
 
+  /** 标签的回放缓冲（退出会话仍可回放；未知 id 返回 null）。 */
+  snapshot(id) {
+    const s = this.find(id)
+    return s === null ? null : s.transcript
+  }
+
   /** 关闭单个标签（仅限 cwd 桶内：跨桶 id 一律不动），返回剩余标签。 */
   close(id, cwd) {
     const bucket = this.bucketOf(cwd)
@@ -215,9 +478,10 @@ export class PtyHost {
   }
 
   spawn(s) {
-    const pty = getPty()
-    const shell = process.platform === 'win32' ? 'powershell.exe' : (process.env.SHELL || '/bin/zsh')
-    const args = process.platform === 'win32' ? [] : ['--login']
+    const pty = loadRequiredNodePty()
+    const shell = defaultShell()
+    const args = shellSpawnArgs()
+    s.shell = shell
     s.pty = pty.spawn(shell, args, {
       name: 'xterm-256color',
       cwd: s.cwd,
@@ -225,7 +489,10 @@ export class PtyHost {
       cols: this.cols,
       rows: this.rows,
     })
-    s.pty.onData(chunk => { this.events.emit('data', chunk, s.id, s.bucket) })
+    s.pty.onData(chunk => {
+      s.transcript = appendTranscript(s.transcript, chunk)
+      this.events.emit('data', chunk, s.id, s.bucket)
+    })
     s.pty.onExit(() => {
       s.exited = true
       s.pty = null
@@ -302,12 +569,19 @@ export function dispatchRpc(host, body) {
       if (typeof body.id !== 'number') return { ok: false, error: 'bad id' }
       return { ok: true, tabs: host.close(body.id, cwd) }
     }
+    case 'snapshot': {
+      if (typeof body.id !== 'number') return { ok: false, error: 'bad id' }
+      return { ok: true, chunk: host.snapshot(body.id) }
+    }
     default: return { ok: false, error: 'unknown op' }
   }
 }
 
-/** dsh web 插件入口：注册 RPC + SSE + vendor 托管（effect 包裹随 dispose 摘除）。 */
+/** dsh web 插件入口：注册 RPC + SSE + vendor + deps（effect 包裹随 dispose 摘除）。 */
 export function apply(ctx) {
+  // 真实终端前置换修：macOS 侧 prebuilt spawn-helper 的可执行位可能被
+  // 包管理器剥掉（幂等，失败静默，由 spawn 自身报错兜底暴露）。
+  ensureSpawnHelper()
   const host = new PtyHost()
   /** 活跃 SSE 客户端（res 集；断开即摘除）。 */
   const sseClients = new Set()
@@ -381,6 +655,16 @@ export function apply(ctx) {
             return
           }
 
+          // node-pty 依赖状态（降级模式：cause + 可粘贴修复命令）
+          if (tail === 'deps') {
+            if (req.method !== 'GET') {
+              writeJson(res, 405, { ok: false, error: 'method not allowed' })
+              return
+            }
+            writeJson(res, 200, depsStatus())
+            return
+          }
+
           // pty 操作 RPC（写操作 POST-only）
           if (tail === 'rpc') {
             if (req.method !== 'POST') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kkutysllb/dsh-terminal",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "dsh-external in-box dsh bundle: embedded terminal panel (node-pty backed multi-tab shells, per-workspace buckets, xterm.js UI) as a bottom dock inside the dsh web page, replacing the retired Electron host terminal-panel.",
   "license": "MIT",
   "type": "module",