dsh-oh-my-terminal 0.2.7 → 0.2.8

package/CLAUDE.md

@@ -65,6 +65,8 @@ src/
 │   ├── dropdown.tsx        # +号旁下拉菜单组件（新建/拆分/按种类新建）
 │   ├── side-list.tsx       # 右侧终端列表面板（树形前缀 + 右键重命名 + useMemo 缓存）
 │   ├── shortcut-bridge.ts  # shortcuts 服务接入信号桥（命令注册状态 + 面板切换回调，软探测兼容旧宿主）
+│   ├── compat.ts          # DSH-better-sidebar 兼容模式检测（软探测 ctx.betterSidebar + 服务最小接口声明）
+│   ├── sidebar-tab.tsx    # 侧边栏终端 tab 组件（兼容模式：嵌入 DSH-better-sidebar 底部工作台，不绑定 DSH sessionId）
 │   ├── terminal/
 │   │   ├── reducer.ts          # 终端状态 reducer（terminalReducer 纯函数 + createInitialState）
 │   │   ├── use-terminal-state.ts # 终端状态管理 Hook（useTerminalState：useReducer 封装 + 启动恢复）
@@ -117,9 +119,13 @@ src/
   client.tsx → client/types.ts, client/icons.tsx, client/clipboard.ts,
                client/dropdown.tsx, client/side-list.tsx, client/hooks.ts,
                client/styles.ts, client/term-pane.tsx, client/settings/,
-               client/shortcut-bridge.ts, logger.ts
+               client/shortcut-bridge.ts, client/compat.ts, client/sidebar-tab.tsx,
+               logger.ts
   client/hooks.ts → client/terminal/*（re-export 兼容壳：reducer/use-terminal-state/use-panel-geometry/use-tabs）
   client/shortcut-bridge.ts → client/types.ts, constants.ts, logger.ts
+  client/compat.ts → logger.ts（软探测 ctx.betterSidebar，声明服务最小接口）
+  client/sidebar-tab.tsx → client/hooks.ts, client/term-pane.tsx, client/dropdown.tsx,
+                           client/side-list.tsx, client/icons.tsx, client/compat.ts, logger.ts
   client/terminal/reducer.ts → client/types.ts, logger.ts
   client/terminal/use-terminal-state.ts → client/terminal/reducer.ts, client/types.ts, logger.ts
   client/terminal/use-panel-geometry.ts → client/types.ts, constants.ts, logger.ts

package/README.md

@@ -1,6 +1,6 @@
 # dsh-oh-my-terminal
 
-[![version](https://img.shields.io/badge/version-0.2.7-blue)](package.json)
+[![version](https://img.shields.io/badge/version-0.2.8-blue)](package.json)
 [![license](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE)
 [![node](https://img.shields.io/badge/node-%5E20.19.0%20%7C%7C%20%3E%3D22.0.0-brightgreen)](package.json)
 
@@ -18,6 +18,7 @@ A bottom terminal panel plugin for DSH Web GUI. Powered by `@lydell/node-pty`, i
 - **Cross-platform**: Windows ConPTY and POSIX openpty are selected automatically by `@lydell/node-pty`; pre-compiled binaries ship with the package, nothing to compile
 - **Profile-driven terminals**: a configurable terminal profile table (type / name / path) drives new-terminal creation; profiles are auto-detected at startup and can be added, renamed, and edited in the settings UI
 - **Configurable fonts**: font family, size, and line height are adjustable and hot-reload on open terminals
+- **DSH-better-sidebar compatibility**: auto-detects [DSH-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar) at runtime and switches to compat mode — registers a "Terminal" tab in its bottom workbench instead of the standalone dock; PTY sessions are not bound to the DSH session write handle, eliminating conflicts with DSH-better-sidebar's own terminal. When the host supports `TabDescriptor.rightActions` (v0.25.0+), the terminal's action buttons (new / split / restart) are injected into the tab strip's right end, VSCode-style; otherwise it falls back to a header row inside the tab content area
 
 ## Installation
 
@@ -96,6 +97,8 @@ src/
 │   ├── icons.tsx         # SVG icon components
 │   ├── clipboard.ts      # Clipboard utility functions
 │   ├── shortcut-bridge.ts # Shortcuts service integration (command registration + toggle bridge)
+│   ├── compat.ts          # DSH-better-sidebar compat mode detection (soft-probe ctx.betterSidebar + service interface)
+│   ├── sidebar-tab.tsx    # Sidebar terminal tab (compat mode: embed in DSH-better-sidebar bottom workbench, no DSH session binding)
 │   ├── settings/         # Settings UI (types / store / card / profile-table / api / styles)
 │   └── terminal/         # Terminal tab state (use-tabs / reducer / use-terminal-state / geometry)
 ├── persistence.ts        # Session persistence (log storage, metadata, startup restore)

package/README.zh.md

@@ -1,6 +1,6 @@
 # dsh-oh-my-terminal
 
-[![version](https://img.shields.io/badge/version-0.2.7-blue)](package.json)
+[![version](https://img.shields.io/badge/version-0.2.8-blue)](package.json)
 [![license](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE)
 [![node](https://img.shields.io/badge/node-%5E20.19.0%20%7C%7C%20%3E%3D22.0.0-brightgreen)](package.json)
 
@@ -16,6 +16,7 @@ DSH Web GUI 的底部终端面板插件，基于 `@lydell/node-pty` 提供多终
 - **跨平台**：Windows ConPTY / POSIX openpty，由 `@lydell/node-pty` 自动选择，二进制随 tarball 分发，安装即用
 - **配置表驱动终端**：终端配置表（type / name / path）驱动新建终端；启动时自动探测 $PATH 中的终端，可在设置界面新增、改名、编辑路径
 - **字体可配置**：字体族、字号、行高可配置，配置变更对已打开终端即时生效
+- **DSH-better-sidebar 兼容**：运行时自动检测 [DSH-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar)，检测到时切换为兼容模式——通过 `ctx.betterSidebar.registerTab()` 注册"终端"tab 嵌入其底部工作台，替代独立底部面板；PTY 会话不绑定 DSH session 的 write handle，从根源消除与 DSH-better-sidebar 自带终端的冲突。当宿主支持 `TabDescriptor.rightActions`（v0.25.0+）时，终端操作按钮（新建 / 拆分 / 重启）注入 tab 标签条右端，VSCode 风格单层栏；不支持时回退为 tab 内容区顶部头部栏（两层显示）
 
 ## 安装
 
@@ -94,6 +95,8 @@ src/
 │   ├── icons.tsx         # SVG 图标组件
 │   ├── clipboard.ts      # 剪贴板工具函数
 │   ├── shortcut-bridge.ts # shortcuts 服务接入桥（命令注册 + 面板切换回调）
+│   ├── compat.ts          # DSH-better-sidebar 兼容模式检测（软探测 ctx.betterSidebar + 服务最小接口声明）
+│   ├── sidebar-tab.tsx    # 侧边栏终端 tab 组件（兼容模式：嵌入 DSH-better-sidebar 底部工作台，不绑定 DSH sessionId）
 │   ├── settings/         # 设置界面（types / store / card / profile-table / api / styles）
 │   └── terminal/         # 终端标签页状态（use-tabs / reducer / use-terminal-state / geometry）
 ├── persistence.ts        # 会话持久化层（日志落盘 / 元数据 / 启动恢复）

package/lib/client.js

@@ -166,7 +166,7 @@ __export(client_exports, {
   name: () => name
 });
 module.exports = __toCommonJS(client_exports);
-var React10 = __toESM(require("react"), 1);
+var React11 = __toESM(require("react"), 1);
 
 // src/client/icons.tsx
 var React = __toESM(require("react"), 1);
@@ -1203,6 +1203,11 @@ var TERM_THEME = {
   brightWhite: "#f2f2f2"
 };
 var PANEL_CSS = `.dshTermRoot{position:fixed;bottom:0;z-index:50;font-family:Inter,var(--dsw-font-family)}
+/* \u517C\u5BB9\u6A21\u5F0F\u6839\u5BB9\u5668\uFF1A\u5D4C\u5165 DSH-better-sidebar \u5E95\u90E8\u5DE5\u4F5C\u53F0 tab \u5185\u5BB9\u533A\u3002
+ * \u8986\u76D6 .dshTermRoot \u7684 position:fixed/bottom:0/z-index\u2014\u2014\u8FD9\u4E9B\u662F\u72EC\u7ACB\u6A21\u5F0F
+ * \u5E95\u90E8\u56FA\u5B9A\u9762\u677F\u7684\u5B9A\u4F4D\uFF0C\u5728 tab \u5185\u5BB9\u533A\u91CC\u4F1A\u5BFC\u81F4\u7EC4\u4EF6\u8131\u79BB\u6587\u6863\u6D41\u8986\u76D6\u6574\u4E2A\u4FA7\u8FB9\u680F\u3002
+ * \u6539\u4E3A position:relative \u586B\u6EE1 tab \u5185\u5BB9\u533A\uFF08flex column \u5E03\u5C40\uFF09 */
+.dshTermSidebarRoot{position:relative;bottom:auto;z-index:auto;width:100%;height:100%;display:flex;flex-direction:column;min-height:0;overflow:hidden;background:var(--dsw-specific-tip)}
 .dshTermBar{box-sizing:border-box;width:100%;height:34px;display:flex;align-items:center;gap:10px;padding:0 14px;background:var(--dsw-specific-tip);border-top:1px solid var(--dsw-alias-border-l1);cursor:pointer;color:var(--dsw-alias-label-primary);text-align:left;user-select:none;-webkit-user-select:none}
 .dshTermBar:focus-visible{outline:2px solid var(--dsw-alias-label-tertiary);outline-offset:-2px}
 .dshTermBarLead{color:var(--dsw-alias-label-tertiary);flex:none;place-items:center;display:grid}
@@ -11598,19 +11603,327 @@ function injectSettingsStyles() {
   document.head.appendChild(tag);
 }
 
+// src/client/compat.ts
+var BETTER_SIDEBAR_SERVICE = "betterSidebar";
+function detectBetterSidebar(ctx) {
+  if (typeof ctx.get !== "function") return void 0;
+  const service = ctx.get(BETTER_SIDEBAR_SERVICE);
+  if (service === void 0) return void 0;
+  if (typeof service.registerTab !== "function") return void 0;
+  return service;
+}
+
+// src/client/sidebar-tab.tsx
+var React10 = __toESM(require("react"), 1);
+var log4 = createLogger("terminal-sidebar-tab");
+var SIDEBAR_TAB_ORDER = 40;
+function TerminalSidebarTab(props) {
+  const { scope, visible, useHeader = false } = props;
+  const { useEffect, useRef, useCallback } = React10;
+  const sessionId = void 0;
+  const workspaceCwd = scope.cwd;
+  const rootRef = useRef(null);
+  const { state, dispatch } = useTerminalState(sessionId);
+  const { instances, groups, activeInstanceId, busy, bootReady } = state;
+  const activeInstance = instances.find((t) => t.id === activeInstanceId) ?? null;
+  const activeGroup = groups.find((g) => g.instances.some((i) => i.id === activeInstanceId)) ?? null;
+  const { newTab, closeTab, restartActive, splitTerminal, onExit } = useTerminalTabs({
+    state,
+    dispatch,
+    activeInstance,
+    activeGroup,
+    workspaceCwd,
+    sessionId
+  });
+  const { fontFamily, fontSize, lineHeight, terminalProfiles } = useConfig(
+    /* setOpen 在侧边栏模式下无意义（展开/折叠由 DSH-better-sidebar 工作台控制），
+     * 传一个空操作 setter 满足 useConfig 签名 */
+    () => {
+    }
+  );
+  const openHandled = useRef(false);
+  useEffect(() => {
+    if (!visible) {
+      openHandled.current = false;
+      return;
+    }
+    if (!bootReady || instances.length > 0 || openHandled.current) return;
+    openHandled.current = true;
+    void newTab();
+  }, [visible, bootReady, instances.length, newTab]);
+  const stateLabel = busy ? "\u542F\u52A8\u4E2D\u2026" : activeInstance === null ? instances.length === 0 ? "\u65E0\u4F1A\u8BDD" : "\u7A7A\u95F2" : activeInstance.exited ? instanceLabel(activeInstance) + " \u5DF2\u9000\u51FA\uFF0C\u70B9 \u27F3 \u91CD\u542F" : instanceLabel(activeInstance);
+  const handleNewByType = useCallback((profileId) => {
+    const profile = terminalProfiles.find((p) => p.id === profileId);
+    if (profile === void 0) {
+      log4.warn(`\u672A\u77E5\u7684\u7EC8\u7AEF\u914D\u7F6E id\uFF1A${profileId}`);
+      return;
+    }
+    void newTab(profile.id);
+  }, [newTab, terminalProfiles]);
+  const handleRename = useCallback((instanceId, newName) => {
+    dispatch({ type: "RENAME_INSTANCE", id: instanceId, title: newName });
+  }, [dispatch]);
+  const handleSelectInstance = useCallback((instanceId) => {
+    dispatch({ type: "SET_ACTIVE", id: instanceId });
+  }, [dispatch]);
+  return React10.createElement(
+    "div",
+    {
+      className: "dshTermSidebarRoot",
+      ref: rootRef
+    },
+    /* 降级模式头部栏：引导符 + 状态 + 右侧按钮组（rightActions 不可用时回退） */
+    useHeader ? React10.createElement(
+      "div",
+      { className: "dshTermHeader", style: { flexShrink: 0 } },
+      React10.createElement("span", { className: "dshTermHeaderState", title: stateLabel }, stateLabel),
+      React10.createElement(
+        "div",
+        { className: "dshTermHeaderActions" },
+        React10.createElement(
+          "div",
+          { className: "dshTermNewWrap" },
+          React10.createElement(
+            "button",
+            {
+              className: "dshTermNew",
+              title: "\u65B0\u5EFA\u7EC8\u7AEF",
+              "aria-label": "\u65B0\u5EFA\u7EC8\u7AEF",
+              disabled: busy,
+              onClick: () => {
+                void newTab();
+              }
+            },
+            Plus12()
+          ),
+          React10.createElement("div", { className: "dshTermNewSep" }),
+          React10.createElement(DropdownMenu, {
+            busy,
+            onNewTerminal: () => {
+              void newTab();
+            },
+            onSplitTerminal: () => {
+              void splitTerminal();
+            },
+            terminalProfiles,
+            onNewByType: handleNewByType
+          })
+        ),
+        React10.createElement(RestartButton, { active: activeInstance, busy, onRestart: () => {
+          void restartActive();
+        } })
+      )
+    ) : null,
+    /* Body：左侧终端显示区域 + 右侧终端列表 */
+    React10.createElement(
+      "div",
+      {
+        className: "dshTermBodyWithList",
+        style: { flex: 1, minHeight: 0, overflow: "hidden" }
+      },
+      /* 左侧终端显示区域 */
+      React10.createElement(
+        "div",
+        { className: "dshTermTerminalArea" },
+        ...groups.map((g) => {
+          if (g.instances.length === 1) {
+            const inst = g.instances[0];
+            return React10.createElement(TermPane, {
+              key: inst.id,
+              instance: inst,
+              active: inst.id === activeInstanceId,
+              fontFamily,
+              fontSize,
+              lineHeight,
+              onExit
+            });
+          }
+          return React10.createElement(
+            "div",
+            { key: g.id, className: "dshTermSplitGroup" },
+            ...g.instances.flatMap((inst, idx) => {
+              const elements = [];
+              if (idx > 0) {
+                elements.push(React10.createElement("div", { key: g.id + "-div-" + idx, className: "dshTermSplitDivider" }));
+              }
+              elements.push(
+                React10.createElement(
+                  "div",
+                  { key: inst.id, className: "dshTermSplitPane" },
+                  React10.createElement(TermPane, {
+                    instance: inst,
+                    active: inst.id === activeInstanceId,
+                    fontFamily,
+                    fontSize,
+                    lineHeight,
+                    onExit
+                  })
+                )
+              );
+              return elements;
+            })
+          );
+        }),
+        instances.length === 0 ? React10.createElement(
+          "div",
+          { className: "dshTermEmpty" },
+          React10.createElement("span", null, "\u6CA1\u6709\u7EC8\u7AEF\u4F1A\u8BDD"),
+          React10.createElement(
+            "button",
+            { className: "dshTermEmptyBtn", onClick: () => {
+              void newTab();
+            } },
+            Plus12(),
+            "\u65B0\u5EFA\u7EC8\u7AEF"
+          )
+        ) : null
+      ),
+      /* 右侧终端列表（仅多于一个终端时显示） */
+      instances.length > 1 ? React10.createElement(SideList, {
+        groups,
+        activeInstanceId,
+        onSelect: handleSelectInstance,
+        onClose: closeTab,
+        onRename: handleRename
+      }) : null
+    )
+  );
+}
+function TerminalSidebarRightActions(props) {
+  const { scope, visible } = props;
+  const { useCallback } = React10;
+  const sessionId = void 0;
+  const workspaceCwd = scope.cwd;
+  const { state, dispatch } = useTerminalState(sessionId);
+  const { instances, activeInstanceId, busy } = state;
+  const activeInstance = instances.find((t) => t.id === activeInstanceId) ?? null;
+  const activeGroup = state.groups.find((g) => g.instances.some((i) => i.id === activeInstanceId)) ?? null;
+  const { newTab, restartActive, splitTerminal } = useTerminalTabs({
+    state,
+    dispatch,
+    activeInstance,
+    activeGroup,
+    workspaceCwd,
+    sessionId
+  });
+  const { terminalProfiles } = useConfig(() => {
+  });
+  const handleNewByType = useCallback((profileId) => {
+    const profile = terminalProfiles.find((p) => p.id === profileId);
+    if (profile === void 0) {
+      log4.warn(`\u672A\u77E5\u7684\u7EC8\u7AEF\u914D\u7F6E id\uFF1A${profileId}`);
+      return;
+    }
+    void newTab(profile.id);
+  }, [newTab, terminalProfiles]);
+  return React10.createElement(
+    "div",
+    { className: "dshTermHeaderActions", style: { padding: "0 4px" } },
+    /* 新建终端组合按钮（+ / 下拉） */
+    React10.createElement(
+      "div",
+      { className: "dshTermNewWrap" },
+      React10.createElement(
+        "button",
+        {
+          className: "dshTermNew",
+          title: "\u65B0\u5EFA\u7EC8\u7AEF",
+          "aria-label": "\u65B0\u5EFA\u7EC8\u7AEF",
+          disabled: busy,
+          onClick: () => {
+            void newTab();
+          }
+        },
+        Plus12()
+      ),
+      React10.createElement("div", { className: "dshTermNewSep" }),
+      React10.createElement(DropdownMenu, {
+        busy,
+        onNewTerminal: () => {
+          void newTab();
+        },
+        onSplitTerminal: () => {
+          void splitTerminal();
+        },
+        terminalProfiles,
+        onNewByType: handleNewByType
+      })
+    ),
+    /* 重启按钮 */
+    React10.createElement(RestartButton, { active: activeInstance, busy, onRestart: () => {
+      void restartActive();
+    } })
+  );
+}
+function createTerminalTabDescriptor(supportsRightActions) {
+  return {
+    id: "dsh-oh-my-terminal",
+    title: () => "\u7EC8\u7AEF",
+    icon: (size) => React10.createElement("span", {
+      style: {
+        display: "inline-flex",
+        alignItems: "center",
+        color: "var(--dsw-alias-label-primary)"
+      }
+    }, TerminalGlyph14()),
+    order: SIDEBAR_TAB_ORDER,
+    single: true,
+    component: (props) => React10.createElement(TerminalSidebarTab, { ...props, useHeader: !supportsRightActions }),
+    ...supportsRightActions ? {
+      // rightActions 签名是 (ctx, scope, state) => ReactNode（三个独立参数，
+      // 不是 props 对象——与 DSH-better-sidebar 的 TabDescriptor.rightActions
+      // 调用约定一致）。这里把它们组装成 TabComponentPropsLike 传给组件。
+      rightActions: (ctx, scope, _state) => React10.createElement(TerminalSidebarRightActions, { ctx, scope, visible: true, tab: { id: "", type: "", title: "" } })
+    } : {}
+  };
+}
+
 // src/client.tsx
-var log4 = createLogger("terminal-client");
+var log5 = createLogger("terminal-client");
 injectStyles();
 injectSettingsStyles();
 var name = "dsh-oh-my-terminal";
 var inject = ["slots"];
 function apply(ctx) {
-  registerToggleShortcut(ctx);
-  ctx.slots.inject("conversation.input.dock", () => ctx.slots.register(
-    { name: "conversation.input.dock", id: "terminal", order: 10 },
-    TerminalPanel
-  ));
   registerSettingsPage(ctx);
+  const betterSidebar = detectBetterSidebar(ctx);
+  if (betterSidebar !== void 0) {
+    registerSidebarTab(ctx, betterSidebar);
+    return;
+  }
+  const dockDisposer = registerStandaloneDock(ctx);
+  registerToggleShortcut(ctx);
+  const seat = ctx.inject(["betterSidebar"], (injected) => {
+    const service = detectBetterSidebar(injected);
+    if (service === void 0) return;
+    dockDisposer();
+    registerSidebarTab(ctx, service);
+  });
+  ctx.effect(() => () => {
+    void seat.dispose();
+  }, "dsh-oh-my-terminal.better-sidebar-inject");
+}
+function registerStandaloneDock(ctx) {
+  return ctx.slots.inject("conversation.input.dock", () => {
+    const regDispose = ctx.slots.register(
+      { name: "conversation.input.dock", id: "terminal", order: 10 },
+      TerminalPanel
+    );
+    return regDispose;
+  });
+}
+function registerSidebarTab(ctx, service) {
+  try {
+    const supportsRightActions = service.features?.includes("rightActions") ?? false;
+    const descriptor = createTerminalTabDescriptor(supportsRightActions);
+    const dispose = service.registerTab(descriptor);
+    ctx.effect(() => dispose, "dsh-oh-my-terminal.sidebar-tab");
+    log5.info(`\u5DF2\u63A5\u5165 DSH-better-sidebar \u517C\u5BB9\u6A21\u5F0F\uFF08\u7EC8\u7AEF tab \u6CE8\u518C\u5230\u5E95\u90E8\u5DE5\u4F5C\u53F0\uFF0CrightActions=${supportsRightActions}\uFF09`);
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    log5.warn(`betterSidebar registerTab \u5931\u8D25\uFF0C\u964D\u7EA7\u4E3A\u72EC\u7ACB\u6A21\u5F0F\uFF1A${msg}`);
+    registerStandaloneDock(ctx);
+  }
 }
 var SETTINGS_ROW_ID = "terminal-panel";
 function registerSettingsPage(ctx) {
@@ -11639,14 +11952,14 @@ function registerToggleShortcut(ctx) {
     });
     ctx.effect(() => dispose, "dsh-oh-my-terminal.shortcut");
     markShortcutsActive(shortcuts.catalog);
-    log4.info(`\u5DF2\u63A5\u5165 DSH shortcuts \u670D\u52A1\uFF08\u547D\u4EE4 ${SHORTCUT_COMMAND_ID}\uFF09`);
+    log5.info(`\u5DF2\u63A5\u5165 DSH shortcuts \u670D\u52A1\uFF08\u547D\u4EE4 ${SHORTCUT_COMMAND_ID}\uFF09`);
   } catch (error) {
     const msg = error instanceof Error ? error.message : String(error);
-    log4.warn(`shortcuts \u547D\u4EE4\u6CE8\u518C\u5931\u8D25\uFF0C\u964D\u7EA7\u4E3A\u88F8 keydown \u76D1\u542C\uFF1A${msg}`);
+    log5.warn(`shortcuts \u547D\u4EE4\u6CE8\u518C\u5931\u8D25\uFF0C\u964D\u7EA7\u4E3A\u88F8 keydown \u76D1\u542C\uFF1A${msg}`);
   }
 }
 function TerminalPanel(props) {
-  const { useEffect, useRef, useState, useCallback } = React10;
+  const { useEffect, useRef, useState, useCallback } = React11;
   const { sessionId, useWorkspaces } = props ?? {};
   const [open, setOpen] = useState(false);
   const workspaceCwd = useWorkspaces?.((s15) => {
@@ -11690,7 +12003,7 @@ function TerminalPanel(props) {
   const handleNewByType = useCallback((profileId) => {
     const profile = terminalProfiles.find((p) => p.id === profileId);
     if (profile === void 0) {
-      log4.warn(`\u672A\u77E5\u7684\u7EC8\u7AEF\u914D\u7F6E id\uFF1A${profileId}`);
+      log5.warn(`\u672A\u77E5\u7684\u7EC8\u7AEF\u914D\u7F6E id\uFF1A${profileId}`);
       return;
     }
     void newTab(profile.id);
@@ -11701,36 +12014,36 @@ function TerminalPanel(props) {
   const handleSelectInstance = useCallback((instanceId) => {
     dispatch({ type: "SET_ACTIVE", id: instanceId });
   }, [dispatch]);
-  return React10.createElement(
+  return React11.createElement(
     "div",
     {
       className: "dshTermRoot",
       ref: rootRef,
       style: { left: geo.left + "px", width: geo.width + "px" }
     },
-    open ? React10.createElement(
+    open ? React11.createElement(
       "div",
       { className: "dshTermPanel", id: "dshTermPanel", style: { height: height + "px" } },
-      React10.createElement("div", {
+      React11.createElement("div", {
         className: "dshTermResize",
         title: "\u62D6\u52A8\u8C03\u6574\u9AD8\u5EA6",
         onPointerDown: startResize
       }),
       /* 头部：引导符 + 状态(flex:1 撑满) + 右侧按钮组(margin-left:auto 右对齐) */
-      React10.createElement(
+      React11.createElement(
         "div",
         { className: "dshTermHeader" },
-        React10.createElement("span", { className: "dshTermHeaderLead", "aria-hidden": true }, TerminalGlyph14()),
-        React10.createElement("span", { className: "dshTermHeaderState", title: stateLabel }, stateLabel),
+        React11.createElement("span", { className: "dshTermHeaderLead", "aria-hidden": true }, TerminalGlyph14()),
+        React11.createElement("span", { className: "dshTermHeaderState", title: stateLabel }, stateLabel),
         /* 右侧按钮组：+号/下拉 + 重启 + 收起，统一右对齐 */
-        React10.createElement(
+        React11.createElement(
           "div",
           { className: "dshTermHeaderActions" },
           /* 新建组合按钮：+ 主按钮 + 分隔线 + 下拉箭头 */
-          React10.createElement(
+          React11.createElement(
             "div",
             { className: "dshTermNewWrap" },
-            React10.createElement(
+            React11.createElement(
               "button",
               {
                 className: "dshTermNew",
@@ -11743,8 +12056,8 @@ function TerminalPanel(props) {
               },
               Plus12()
             ),
-            React10.createElement("div", { className: "dshTermNewSep" }),
-            React10.createElement(DropdownMenu, {
+            React11.createElement("div", { className: "dshTermNewSep" }),
+            React11.createElement(DropdownMenu, {
               busy,
               onNewTerminal: () => {
                 void newTab();
@@ -11757,10 +12070,10 @@ function TerminalPanel(props) {
             })
           ),
           /* 重启对已退出历史终端也需可达 */
-          React10.createElement(RestartButton, { active: activeInstance, busy, onRestart: () => {
+          React11.createElement(RestartButton, { active: activeInstance, busy, onRestart: () => {
             void restartActive();
           } }),
-          React10.createElement(
+          React11.createElement(
             "button",
             {
               className: "dshTermCollapse",
@@ -11773,17 +12086,17 @@ function TerminalPanel(props) {
         )
       ),
       /* Body：左侧终端显示区域 + 右侧终端列表 */
-      React10.createElement(
+      React11.createElement(
         "div",
         { className: "dshTermBodyWithList" },
         /* 左侧终端显示区域 */
-        React10.createElement(
+        React11.createElement(
           "div",
           { className: "dshTermTerminalArea" },
           ...groups.map((g) => {
             if (g.instances.length === 1) {
               const inst = g.instances[0];
-              return React10.createElement(TermPane, {
+              return React11.createElement(TermPane, {
                 key: inst.id,
                 instance: inst,
                 active: inst.id === activeInstanceId,
@@ -11793,19 +12106,19 @@ function TerminalPanel(props) {
                 onExit
               });
             }
-            return React10.createElement(
+            return React11.createElement(
               "div",
               { key: g.id, className: "dshTermSplitGroup" },
               ...g.instances.flatMap((inst, idx) => {
                 const elements = [];
                 if (idx > 0) {
-                  elements.push(React10.createElement("div", { key: g.id + "-div-" + idx, className: "dshTermSplitDivider" }));
+                  elements.push(React11.createElement("div", { key: g.id + "-div-" + idx, className: "dshTermSplitDivider" }));
                 }
                 elements.push(
-                  React10.createElement(
+                  React11.createElement(
                     "div",
                     { key: inst.id, className: "dshTermSplitPane" },
-                    React10.createElement(TermPane, {
+                    React11.createElement(TermPane, {
                       instance: inst,
                       active: inst.id === activeInstanceId,
                       fontFamily,
@@ -11819,11 +12132,11 @@ function TerminalPanel(props) {
               })
             );
           }),
-          instances.length === 0 ? React10.createElement(
+          instances.length === 0 ? React11.createElement(
             "div",
             { className: "dshTermEmpty" },
-            React10.createElement("span", null, "\u6CA1\u6709\u7EC8\u7AEF\u4F1A\u8BDD"),
-            React10.createElement(
+            React11.createElement("span", null, "\u6CA1\u6709\u7EC8\u7AEF\u4F1A\u8BDD"),
+            React11.createElement(
               "button",
               { className: "dshTermEmptyBtn", onClick: () => {
                 void newTab();
@@ -11834,7 +12147,7 @@ function TerminalPanel(props) {
           ) : null
         ),
         /* 右侧终端列表（仅多于一个终端时显示） */
-        instances.length > 1 ? React10.createElement(SideList, {
+        instances.length > 1 ? React11.createElement(SideList, {
           groups,
           activeInstanceId,
           onSelect: handleSelectInstance,
@@ -11842,7 +12155,7 @@ function TerminalPanel(props) {
           onRename: handleRename
         }) : null
       )
-    ) : React10.createElement(
+    ) : React11.createElement(
       "div",
       {
         className: "dshTermBar",
@@ -11859,18 +12172,18 @@ function TerminalPanel(props) {
           }
         }
       },
-      React10.createElement("span", { className: "dshTermBarLead", "aria-hidden": true }, TerminalGlyph14()),
-      React10.createElement("span", { className: "dshTermBarTitle" }, "\u7EC8\u7AEF"),
+      React11.createElement("span", { className: "dshTermBarLead", "aria-hidden": true }, TerminalGlyph14()),
+      React11.createElement("span", { className: "dshTermBarTitle" }, "\u7EC8\u7AEF"),
       /* flex:1 spacer 把右侧按钮推到最右 */
-      React10.createElement("span", { style: { flex: 1 } }),
-      React10.createElement(
+      React11.createElement("span", { style: { flex: 1 } }),
+      React11.createElement(
         "span",
         { className: "dshTermBarActions", onClick: (e) => e.stopPropagation() },
-        React10.createElement(RestartButton, { active: activeInstance, busy, onRestart: () => {
+        React11.createElement(RestartButton, { active: activeInstance, busy, onRestart: () => {
           void restartActive();
         } })
       ),
-      React10.createElement("span", { className: "dshTermBarChevron", "aria-hidden": true }, ChevronUp14())
+      React11.createElement("span", { className: "dshTermBarChevron", "aria-hidden": true }, ChevronUp14())
     )
   );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-oh-my-terminal",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "DSH Web GUI 底部终端面板插件——node-pty 驱动的多标签交互式终端（Windows ConPTY / POSIX openpty）",
   "type": "module",
   "license": "Apache-2.0",

package/src/client/compat.ts

@@ -0,0 +1,107 @@
+/**
+ * @file DSH-better-sidebar 兼容模式检测模块
+ * @description 当本插件与 DSH-better-sidebar 同时安装时，两者都会在底部区域管理终端，
+ *              竞争同一个 DSH session 的 write handle，导致
+ *              `session "xxx" is already owned by an active write handle` 报错。
+ *
+ *              本模块软探测 DSH-better-sidebar 发布的 `ctx.betterSidebar` 服务：
+ *              命中时本插件切换为兼容模式——不再注册 `conversation.input.dock`
+ *              底部面板，改为通过 `service.registerTab()` 注册"终端"tab 嵌入
+ *              DSH-better-sidebar 的底部工作台。
+ *
+ *              兼容模式下的 PTY session 不绑定 DSH sessionId（ownerSessionId = null），
+ *              完全由本插件独立管理，不进入 DSH session 的 write handle 体系——
+ *              从根源上消除两个终端插件的 session 冲突。
+ *
+ *              软探测模式与 shortcuts 服务接入（shortcut-bridge.ts）一致：
+ *              不写入顶层 inject，旧宿主或未安装 DSH-better-sidebar 时降级为
+ *              原有独立模式，面板功能不受影响。
+ */
+
+import type { Context } from '@deepseek-ai/cordis';
+import type { ReactNode } from 'react';
+
+// —— DSH-better-sidebar 服务的最小本地接口声明 ——
+// DSH-better-sidebar 通过 ctx.provide('betterSidebar', service) 发布注册服务，
+// 非 npm 包依赖——独立插件无法 import 它的类型。用本地接口声明其最小形状，
+// 使 ctx.get('betterSidebar') 通过类型检查。esbuild 打包时整体擦除，运行期
+// 服务实例由 DSH-better-sidebar 提供。
+
+/** DSH-better-sidebar 的会话作用域（TabComponentProps.scope 的形状） */
+export interface SessionScopeLike {
+  /** 当前 DSH 会话 id */
+  sessionId: string;
+  /** 会话工作目录（可能缺省） */
+  cwd?: string;
+}
+
+/** tab 组件接收的 props 子集（本插件实际消费的字段） */
+export interface TabComponentPropsLike {
+  /** cordis 客户端上下文 */
+  ctx: Context;
+  /** 会话作用域（含 sessionId 与 cwd） */
+  scope: SessionScopeLike;
+  /** 当前 tab 是否可见（面板展开且 tab 活跃） */
+  visible: boolean;
+  /** tab 记录（含 id/type/title） */
+  tab: { id: string; type: string; title: string };
+}
+
+/** 注册 tab 时需提供的描述符（本插件用到的字段子集） */
+export interface BetterSidebarTabDescriptorLike {
+  /** tab 类型唯一 id（也是 SidebarTab.type 值） */
+  id: string;
+  /** tab 标题（字符串或返回字符串的函数） */
+  title: string | (() => string);
+  /** tab 图标（ReactNode 或返回 ReactNode 的函数） */
+  icon?: ReactNode | ((size: number) => ReactNode);
+  /** + 菜单排序权重（小者先） */
+  order?: number;
+  /** 单实例：true = 同类型只保留一个 tab */
+  single?: boolean;
+  /** tab 内容渲染组件 */
+  component: (props: TabComponentPropsLike) => ReactNode;
+  /**
+   * tab 栏右侧操作区（v0.25.0+）：tab 激活时，返回的 ReactNode 渲染在 tab 栏
+   * 右端（+ 按钮右侧、面板关闭按钮左侧，右对齐）。让 tab 把自己的工具栏直接
+   * 放进 tab 标签条，不在内容区顶部单独渲染头部行。
+   *
+   * 签名与 DSH-better-sidebar 的 TabDescriptor.rightActions 一致：
+   * `(ctx, scope, state) => ReactNode`，三个独立参数（不是 props 对象）。
+   */
+  rightActions?: (ctx: unknown, scope: SessionScopeLike, state: unknown) => ReactNode;
+}
+
+/** DSH-better-sidebar 注册服务的最小接口 */
+export interface BetterSidebarServiceLike {
+  /** 注册一个 tab 类型，返回注销函数 */
+  registerTab(descriptor: BetterSidebarTabDescriptorLike): () => void;
+  /**
+   * 能力列表（v0.12.0+）：单调递增，能力只增不删。消费方用 includes 探测
+   * 新能力是否可用，不可用时降级。本插件用 'rightActions' 探测 tab 栏
+   * 右侧操作注入是否可用，不可用时回退到内容区顶部两层显示方案。
+   */
+  readonly features?: readonly string[];
+}
+
+/** DSH-better-sidebar 发布到 cordis 上下文的服务名 */
+export const BETTER_SIDEBAR_SERVICE = 'betterSidebar';
+
+/**
+ * 软探测 DSH-better-sidebar 是否已安装并发布服务。
+ *
+ * 与 shortcuts 服务接入模式一致：不写入顶层 inject（硬依赖会让未安装
+ * DSH-better-sidebar 的宿主上插件浏览器半直接不激活），用 ctx.get 软探测。
+ * 命中时返回服务实例，未命中时返回 undefined（调用方降级为独立模式）。
+ *
+ * @param ctx - 远端页面的 cordis 上下文
+ * @returns betterSidebar 服务实例，未安装时 undefined
+ */
+export function detectBetterSidebar(ctx: Context): BetterSidebarServiceLike | undefined {
+  if (typeof ctx.get !== 'function') return undefined;
+  const service = ctx.get(BETTER_SIDEBAR_SERVICE);
+  if (service === undefined) return undefined;
+  // 形状校验：只认有 registerTab 方法的对象，避免误判
+  if (typeof (service as BetterSidebarServiceLike).registerTab !== 'function') return undefined;
+  return service as BetterSidebarServiceLike;
+}

package/src/client/sidebar-tab.tsx

@@ -0,0 +1,394 @@
+/**
+ * @file 侧边栏终端 tab 组件（DSH-better-sidebar 兼容模式）
+ * @description 当检测到 DSH-better-sidebar 已安装时，本插件不再注册
+ *              `conversation.input.dock` 底部面板，改为通过
+ *              `ctx.betterSidebar.registerTab()` 注册一个"终端"tab，
+ *              嵌入 DSH-better-sidebar 的底部工作台。
+ *
+ *              本组件是该 tab 的内容渲染器：复用现有 hooks
+ *              （useTerminalState/useConfig/useTerminalTabs），但与独立模式的
+ *              TerminalPanel 有三处关键差异：
+ *
+ *              1. 不绑定 DSH sessionId——`useTerminalState(undefined)` 与
+ *                 `useTerminalTabs` 的 sessionId 传 undefined，PTY session 的
+ *                 ownerSessionId 为 null，不进入 DSH session 的 write handle
+ *                 管理体系，从根源上消除与 DSH-better-sidebar 终端的 session 冲突
+ *              2. 工作目录从 tab 接收的 scope.cwd 取值（DSH-better-sidebar
+ *                 传入当前工作区路径），而非 useWorkspaces 查询
+ *              3. 操作按钮通过 descriptor.rightActions 注入 tab 栏右端（+ 按钮
+ *                 右侧、关闭按钮左侧），不在内容区顶部单独渲染头部行——
+ *                 与 VSCode 风格一致，操作按钮直接在 tab 标签条上
+ *
+ *              终端输入/输出数据绝不进日志。
+ */
+
+import * as React from 'react';
+import type { ReactElement } from 'react';
+import {
+  useTerminalState, useConfig, useTerminalTabs,
+} from './hooks.js';
+import { TermPane, RestartButton } from './term-pane.js';
+import { DropdownMenu } from './dropdown.js';
+import { SideList, instanceLabel } from './side-list.js';
+import { TerminalGlyph14, Plus12 } from './icons.js';
+import type { TabComponentPropsLike, BetterSidebarTabDescriptorLike } from './compat.js';
+import { createLogger } from '../logger.js';
+
+const log = createLogger('terminal-sidebar-tab');
+
+/** 侧边栏终端 tab 在 + 菜单中的排序权重（排在内置 tab 之后） */
+const SIDEBAR_TAB_ORDER = 40;
+
+/**
+ * 侧边栏终端 tab 内容组件。
+ *
+ * 复用独立模式 TerminalPanel 的核心 hooks，但适配 DSH-better-sidebar 底部
+ * 工作台的 tab 内容区布局，且不绑定 DSH sessionId（防 write handle 冲突）。
+ *
+ * @param props - DSH-better-sidebar 注入的 tab 组件 props + useHeader 降级标记
+ * @returns 终端 tab 内容根元素
+ */
+function TerminalSidebarTab(props: TabComponentPropsLike & { useHeader?: boolean }): ReactElement {
+  const { scope, visible, useHeader = false } = props;
+  const { useEffect, useRef, useCallback } = React;
+
+  /*
+   * 兼容模式防冲突核心：sessionId 传 undefined。
+   *
+   * useTerminalState(undefined)：/sessions 恢复时不按 DSH 会话过滤（恢复全部
+   * 存活终端）；useTerminalTabs 的 sessionId 为 undefined 时，POST /sessions
+   * 不带 sessionId 字段，宿主半 createSession 的 ownerSessionId 为 null——
+   * PTY session 完全由本插件独立管理，不进入 DSH session 的 write handle
+   * 体系，从根源上消除与 DSH-better-sidebar 终端的 session 冲突。
+   */
+  const sessionId = undefined;
+
+  /** 工作目录：从 tab 接收的 scope.cwd 取值（DSH-better-sidebar 传入工作区路径） */
+  const workspaceCwd = scope.cwd;
+
+  /** 根元素 ref */
+  const rootRef = useRef<HTMLDivElement | null>(null);
+
+  /* —— 统一状态管理（useReducer 封装 + 不按会话过滤恢复） —— */
+  const { state, dispatch } = useTerminalState(sessionId);
+  const { instances, groups, activeInstanceId, busy, bootReady } = state;
+
+  const activeInstance = instances.find(t => t.id === activeInstanceId) ?? null;
+  const activeGroup = groups.find(g => g.instances.some(i => i.id === activeInstanceId)) ?? null;
+
+  /* —— 终端 CRUD —— */
+  const { newTab, closeTab, restartActive, splitTerminal, onExit } = useTerminalTabs({
+    state, dispatch,
+    activeInstance, activeGroup,
+    workspaceCwd, sessionId,
+  });
+
+  /* —— 统一配置拉取（/config） —— */
+  const { fontFamily, fontSize, lineHeight, terminalProfiles } = useConfig(
+    /* setOpen 在侧边栏模式下无意义（展开/折叠由 DSH-better-sidebar 工作台控制），
+     * 传一个空操作 setter 满足 useConfig 签名 */
+    () => { /* 侧边栏模式下快捷键不切换面板 */ },
+  );
+
+  /** 首次可见已处理标记（只在首次可见时创建终端，避免每次切 tab 都新建） */
+  const openHandled = useRef(false);
+
+  /* 首次可见且无恢复的终端：创建一个会话。tab 切换隐藏→显示时不重复创建 */
+  useEffect(() => {
+    if (!visible) {
+      openHandled.current = false;
+      return;
+    }
+    if (!bootReady || instances.length > 0 || openHandled.current) return;
+    openHandled.current = true;
+    void newTab();
+  }, [visible, bootReady, instances.length, newTab]);
+
+  /** 状态标签（降级模式下头部栏显示） */
+  const stateLabel = busy
+    ? '启动中…'
+    : activeInstance === null
+      ? (instances.length === 0 ? '无会话' : '空闲')
+      : (activeInstance.exited ? instanceLabel(activeInstance) + ' 已退出，点 ⟳ 重启' : instanceLabel(activeInstance));
+
+  /**
+   * 按配置 id 新建终端。
+   *
+   * 下拉菜单传进来的是配置 id，从 /config 下发的 terminalProfiles 里找到该配置，
+   * 调用宿主半的 POST /sessions 新建终端。
+   */
+  const handleNewByType = useCallback((profileId: string): void => {
+    const profile = terminalProfiles.find(p => p.id === profileId);
+    if (profile === undefined) {
+      log.warn(`未知的终端配置 id：${profileId}`);
+      return;
+    }
+    void newTab(profile.id);
+  }, [newTab, terminalProfiles]);
+
+  /** 重命名终端实例 */
+  const handleRename = useCallback((instanceId: string, newName: string): void => {
+    dispatch({ type: 'RENAME_INSTANCE', id: instanceId, title: newName });
+  }, [dispatch]);
+
+  /** 选择终端实例（从右侧列表点击） */
+  const handleSelectInstance = useCallback((instanceId: string): void => {
+    dispatch({ type: 'SET_ACTIVE', id: instanceId });
+  }, [dispatch]);
+
+  /*
+   * 侧边栏 tab 布局：填满 DSH-better-sidebar 底部工作台的 tab 内容区。
+   * useHeader=true（降级模式，rightActions 不可用）：渲染头部栏 + Body（两层）
+   * useHeader=false（正常模式，rightActions 可用）：只渲染 Body（操作按钮在 tab 栏）
+   */
+  return React.createElement(
+    'div',
+    {
+      className: 'dshTermSidebarRoot',
+      ref: rootRef,
+    },
+    /* 降级模式头部栏：引导符 + 状态 + 右侧按钮组（rightActions 不可用时回退） */
+    useHeader
+      ? React.createElement(
+        'div',
+        { className: 'dshTermHeader', style: { flexShrink: 0 } },
+        React.createElement('span', { className: 'dshTermHeaderState', title: stateLabel }, stateLabel),
+        React.createElement(
+          'div',
+          { className: 'dshTermHeaderActions' },
+          React.createElement(
+            'div',
+            { className: 'dshTermNewWrap' },
+            React.createElement(
+              'button',
+              {
+                className: 'dshTermNew',
+                title: '新建终端',
+                'aria-label': '新建终端',
+                disabled: busy,
+                onClick: () => { void newTab(); },
+              },
+              Plus12(),
+            ),
+            React.createElement('div', { className: 'dshTermNewSep' }),
+            React.createElement(DropdownMenu, {
+              busy,
+              onNewTerminal: () => { void newTab(); },
+              onSplitTerminal: () => { void splitTerminal(); },
+              terminalProfiles,
+              onNewByType: handleNewByType,
+            }),
+          ),
+          React.createElement(RestartButton, { active: activeInstance, busy, onRestart: () => { void restartActive(); } }),
+        ),
+      )
+      : null,
+    /* Body：左侧终端显示区域 + 右侧终端列表 */
+    React.createElement(
+      'div',
+      {
+        className: 'dshTermBodyWithList',
+        style: { flex: 1, minHeight: 0, overflow: 'hidden' },
+      },
+      /* 左侧终端显示区域 */
+      React.createElement(
+        'div',
+        { className: 'dshTermTerminalArea' },
+        ...groups.map(g => {
+          if (g.instances.length === 1) {
+            const inst = g.instances[0];
+            return React.createElement(TermPane, {
+              key: inst.id,
+              instance: inst,
+              active: inst.id === activeInstanceId,
+              fontFamily,
+              fontSize,
+              lineHeight,
+              onExit,
+            });
+          }
+          /* 多实例组：水平并排 */
+          return React.createElement(
+            'div',
+            { key: g.id, className: 'dshTermSplitGroup' },
+            ...g.instances.flatMap((inst, idx) => {
+              const elements: ReactElement[] = [];
+              if (idx > 0) {
+                elements.push(React.createElement('div', { key: g.id + '-div-' + idx, className: 'dshTermSplitDivider' }));
+              }
+              elements.push(
+                React.createElement(
+                  'div',
+                  { key: inst.id, className: 'dshTermSplitPane' },
+                  React.createElement(TermPane, {
+                    instance: inst,
+                    active: inst.id === activeInstanceId,
+                    fontFamily,
+                    fontSize,
+                    lineHeight,
+                    onExit,
+                  }),
+                ),
+              );
+              return elements;
+            }),
+          );
+        }),
+        instances.length === 0
+          ? React.createElement(
+            'div',
+            { className: 'dshTermEmpty' },
+            React.createElement('span', null, '没有终端会话'),
+            React.createElement(
+              'button',
+              { className: 'dshTermEmptyBtn', onClick: () => { void newTab(); } },
+              Plus12(),
+              '新建终端',
+            ),
+          )
+          : null,
+      ),
+      /* 右侧终端列表（仅多于一个终端时显示） */
+      instances.length > 1
+        ? React.createElement(SideList, {
+          groups,
+          activeInstanceId,
+          onSelect: handleSelectInstance,
+          onClose: closeTab,
+          onRename: handleRename,
+        })
+        : null,
+    ),
+  );
+}
+
+/**
+ * 侧边栏终端 tab 栏右侧操作区组件。
+ *
+ * 通过 descriptor.rightActions 注入 DSH-better-sidebar 的 tab 栏右端（+ 按钮
+ * 右侧、关闭按钮左侧，右对齐）。渲染新建终端组合按钮（+ / 下拉）+ 重启按钮，
+ * 与 VSCode 风格一致——操作按钮直接在 tab 标签条上，不在内容区单独渲染头部。
+ *
+ * 复用与 TerminalSidebarTab 相同的 hooks，保持操作与内容区状态同步。
+ *
+ * @param props - DSH-better-sidebar 注入的 tab 组件 props
+ * @returns tab 栏右侧操作区根元素
+ */
+function TerminalSidebarRightActions(props: TabComponentPropsLike): ReactElement {
+  const { scope, visible } = props;
+  const { useCallback } = React;
+
+  /* 与 TerminalSidebarTab 完全相同的 hooks 调用——rightActions 与 component
+   * 是同一 descriptor 的两个渲染面，各自独立挂载（DSH-better-sidebar 分别
+   * 渲染它们），所以 hooks 状态各自独立。但这不会造成问题：两者都从同一
+   * /sessions 恢复同一批终端（ownerSessionId=null 的全局终端），操作的是
+   * 同一批宿主半 PTY 会话。rightActions 里的按钮触发 HTTP CRUD，内容区
+   * 通过 WebSocket 实时感知变化（newTab/closeTab/restart 的 HTTP 响应更新
+   * 内容区 state，WebSocket onExit 同步退出状态）。 */
+  const sessionId = undefined;
+  const workspaceCwd = scope.cwd;
+
+  const { state, dispatch } = useTerminalState(sessionId);
+  const { instances, activeInstanceId, busy } = state;
+
+  const activeInstance = instances.find(t => t.id === activeInstanceId) ?? null;
+  const activeGroup = state.groups.find(g => g.instances.some(i => i.id === activeInstanceId)) ?? null;
+
+  const { newTab, restartActive, splitTerminal } = useTerminalTabs({
+    state, dispatch,
+    activeInstance, activeGroup,
+    workspaceCwd, sessionId,
+  });
+
+  const { terminalProfiles } = useConfig(() => { /* 侧边栏模式不切换面板 */ });
+
+  const handleNewByType = useCallback((profileId: string): void => {
+    const profile = terminalProfiles.find(p => p.id === profileId);
+    if (profile === undefined) {
+      log.warn(`未知的终端配置 id：${profileId}`);
+      return;
+    }
+    void newTab(profile.id);
+  }, [newTab, terminalProfiles]);
+
+  /*
+   * rightActions 容器：DSH-better-sidebar 的 .tabBarRightActions 已提供
+   * flex:1 + justify-content:flex-end 右对齐。这里只渲染操作按钮组，
+   * 复用独立模式的 .dshTermHeaderActions 等样式（按钮尺寸/颜色一致）。
+   */
+  return React.createElement(
+    'div',
+    { className: 'dshTermHeaderActions', style: { padding: '0 4px' } },
+    /* 新建终端组合按钮（+ / 下拉） */
+    React.createElement(
+      'div',
+      { className: 'dshTermNewWrap' },
+      React.createElement(
+        'button',
+        {
+          className: 'dshTermNew',
+          title: '新建终端',
+          'aria-label': '新建终端',
+          disabled: busy,
+          onClick: () => { void newTab(); },
+        },
+        Plus12(),
+      ),
+      React.createElement('div', { className: 'dshTermNewSep' }),
+      React.createElement(DropdownMenu, {
+        busy,
+        onNewTerminal: () => { void newTab(); },
+        onSplitTerminal: () => { void splitTerminal(); },
+        terminalProfiles,
+        onNewByType: handleNewByType,
+      }),
+    ),
+    /* 重启按钮 */
+    React.createElement(RestartButton, { active: activeInstance, busy, onRestart: () => { void restartActive(); } }),
+  );
+}
+
+/**
+ * 创建侧边栏终端 tab 的描述符，供 DSH-better-sidebar 的 registerTab 注册。
+ *
+ * 描述符字段说明：
+ * - id: 'dsh-oh-my-terminal'（与插件包名一致，避免与其他插件 tab 冲突）
+ * - title: '终端'（中文，与独立模式 bar 标题一致）
+ * - icon: TerminalGlyph14（着 DSH 的 --dsw-alias-label-primary 色，与
+ *   DSH-better-sidebar 内置终端图标风格一致）
+ * - single: true（单实例 tab——打开时聚焦已有而非重复创建）
+ * - order: 40（排在 DSH-better-sidebar 内置 tab 之后：editor 10 / git 20 / subagent 30 / sidechat 35）
+ * - rightActions: TerminalSidebarRightActions（注入 tab 栏右端，操作按钮不在内容区单独渲染头部）
+ *
+ * **能力探测降级**：当 DSH-better-sidebar 版本不支持 rightActions 能力时，
+ * descriptor 不提供 rightActions 字段，component 回退到内容区顶部两层显示
+ * 方案（渲染头部栏 + 终端区）。
+ *
+ * @param supportsRightActions - DSH-better-sidebar 是否支持 rightActions 能力
+ * @returns tab 描述符
+ */
+export function createTerminalTabDescriptor(supportsRightActions: boolean): BetterSidebarTabDescriptorLike {
+  return {
+    id: 'dsh-oh-my-terminal',
+    title: () => '终端',
+    icon: (size: number) => React.createElement('span', {
+      style: {
+        display: 'inline-flex',
+        alignItems: 'center',
+        color: 'var(--dsw-alias-label-primary)',
+      },
+    }, TerminalGlyph14()),
+    order: SIDEBAR_TAB_ORDER,
+    single: true,
+    component: (props) => React.createElement(TerminalSidebarTab, { ...props, useHeader: !supportsRightActions }),
+    ...(supportsRightActions
+      ? {
+        // rightActions 签名是 (ctx, scope, state) => ReactNode（三个独立参数，
+        // 不是 props 对象——与 DSH-better-sidebar 的 TabDescriptor.rightActions
+        // 调用约定一致）。这里把它们组装成 TabComponentPropsLike 传给组件。
+        rightActions: (ctx: unknown, scope: { sessionId: string; cwd?: string }, _state: unknown) =>
+          React.createElement(TerminalSidebarRightActions, { ctx: ctx as TabComponentPropsLike['ctx'], scope, visible: true, tab: { id: '', type: '', title: '' } }),
+      }
+      : {}),
+  };
+}

package/src/client/styles.ts

@@ -114,6 +114,11 @@ export const TERM_THEME: Record<string, string> = {
 
 /** 面板全局 CSS 字符串（含所有 .dshTerm* 样式规则） */
 export const PANEL_CSS = `.dshTermRoot{position:fixed;bottom:0;z-index:50;font-family:Inter,var(--dsw-font-family)}
+/* 兼容模式根容器：嵌入 DSH-better-sidebar 底部工作台 tab 内容区。
+ * 覆盖 .dshTermRoot 的 position:fixed/bottom:0/z-index——这些是独立模式
+ * 底部固定面板的定位，在 tab 内容区里会导致组件脱离文档流覆盖整个侧边栏。
+ * 改为 position:relative 填满 tab 内容区（flex column 布局） */
+.dshTermSidebarRoot{position:relative;bottom:auto;z-index:auto;width:100%;height:100%;display:flex;flex-direction:column;min-height:0;overflow:hidden;background:var(--dsw-specific-tip)}
 .dshTermBar{box-sizing:border-box;width:100%;height:34px;display:flex;align-items:center;gap:10px;padding:0 14px;background:var(--dsw-specific-tip);border-top:1px solid var(--dsw-alias-border-l1);cursor:pointer;color:var(--dsw-alias-label-primary);text-align:left;user-select:none;-webkit-user-select:none}
 .dshTermBar:focus-visible{outline:2px solid var(--dsw-alias-label-tertiary);outline-offset:-2px}
 .dshTermBarLead{color:var(--dsw-alias-label-tertiary);flex:none;place-items:center;display:grid}

package/src/client.tsx

@@ -60,6 +60,9 @@ import {
   resetShortcutsState, markShortcutsActive,
   registerPanelToggler, notifyPanelToggle,
 } from './client/shortcut-bridge.js';
+import { detectBetterSidebar } from './client/compat.js';
+import type { BetterSidebarServiceLike } from './client/compat.js';
+import { createTerminalTabDescriptor } from './client/sidebar-tab.js';
 import { SHORTCUT_COMMAND_ID, SHORTCUT_DEFAULTS } from './constants.js';
 import { createLogger } from './logger.js';
 
@@ -116,15 +119,97 @@ export const inject = ['slots'];
  * DSH 设置界面统一配置）；旧宿主无 shortcuts 服务时软探测不命中，维持裸
  * keydown 降级路径。
  *
+ * **DSH-better-sidebar 兼容模式**：用 `ctx.inject(['betterSidebar'], ...)` 等待
+ * DSH-better-sidebar 的注册服务可用。服务可用时切换为兼容模式——注销
+ * `conversation.input.dock` 底部面板（避免与 DSH-better-sidebar 底部工作台的
+ * 终端竞争同一 DSH session 的 write handle），改为通过 `service.registerTab()`
+ * 注册"终端"tab 嵌入 DSH-better-sidebar 底部工作台。兼容模式下 PTY session
+ * 不绑定 DSH sessionId，从根源上消除 session 冲突。
+ *
+ * 激活顺序自适应：DSH-better-sidebar 可能先于或后于本插件激活。
+ * - 先激活：`ctx.get('betterSidebar')` 即时命中，直接走兼容模式
+ * - 后激活：先注册 dock 降级，`ctx.inject` 回调触发时切换为兼容模式
+ * - 永不安装：`ctx.inject` 回调不触发，保持 dock 独立模式
+ *
  * @param ctx - 远端页面的 cordis 上下文
  */
 export function apply(ctx: ClientContext): void {
-  registerToggleShortcut(ctx);
-  ctx.slots.inject('conversation.input.dock', () => ctx.slots.register(
-    { name: 'conversation.input.dock', id: 'terminal', order: 10 },
-    TerminalPanel,
-  ));
+  // 设置页始终注册（两种模式用户都需配置终端种类/字体等）
   registerSettingsPage(ctx);
+
+  // 即时探测：DSH-better-sidebar 先激活时直接走兼容模式
+  const betterSidebar = detectBetterSidebar(ctx);
+  if (betterSidebar !== undefined) {
+    registerSidebarTab(ctx, betterSidebar);
+    return;
+  }
+
+  // DSH-better-sidebar 尚未激活：先注册独立模式（dock + shortcuts），
+  // 再用 ctx.inject 等待服务可用时切换为兼容模式
+  const dockDisposer = registerStandaloneDock(ctx);
+  registerToggleShortcut(ctx);
+
+  // ctx.inject(['betterSidebar'], cb)：服务可用时回调，永不安装时不触发。
+  // 返回 Fiber（带 dispose 方法），随插件销毁清理（与 DSH-better-sidebar 自身
+  // native surface 的 ctx.inject 用法一致——不用 ctx.effect 包裹）
+  const seat = ctx.inject(['betterSidebar'], (injected: Context) => {
+    const service = detectBetterSidebar(injected);
+    if (service === undefined) return;
+    // 切换：注销独立模式 dock（shortcuts 命令保留——兼容模式下快捷键无害）
+    dockDisposer();
+    // 注册兼容模式 tab
+    registerSidebarTab(ctx, service);
+  });
+  ctx.effect(() => () => { void seat.dispose(); }, 'dsh-oh-my-terminal.better-sidebar-inject');
+}
+
+/**
+ * 注册独立模式底部面板（`conversation.input.dock`），返回注销函数。
+ *
+ * 封装为独立函数，供动态切换时注销。
+ *
+ * @param ctx - 远端页面的 cordis 上下文
+ * @returns 注销 dock 注册的 disposer
+ */
+function registerStandaloneDock(ctx: ClientContext): () => void {
+  // ctx.slots.inject 返回的是声明监听的 disposer，内部 ctx.slots.register
+  // 返回的 disposer 需要在回调里捕获——但 slots.inject 的回调在声明存在时
+  // 触发，返回的 disposer 会注销整条声明。这里直接用 slots.inject 的返回值。
+  return ctx.slots.inject('conversation.input.dock', () => {
+    const regDispose = ctx.slots.register(
+      { name: 'conversation.input.dock', id: 'terminal', order: 10 },
+      TerminalPanel,
+    );
+    return regDispose;
+  }) as () => void;
+}
+
+/**
+ * 兼容模式：通过 DSH-better-sidebar 的 registerTab 注册"终端"tab。
+ *
+ * 不注册 conversation.input.dock（避免与底部工作台终端冲突）。PTY session
+ * 不绑定 DSH sessionId（sidebar-tab 组件内 sessionId 传 undefined），不进入
+ * DSH session 的 write handle 管理体系。
+ *
+ * @param ctx - 远端页面的 cordis 上下文
+ * @param service - DSH-better-sidebar 的 betterSidebar 服务实例
+ */
+function registerSidebarTab(ctx: ClientContext, service: BetterSidebarServiceLike): void {
+  try {
+    // 能力探测：DSH-better-sidebar v0.25.0+ 支持 rightActions（操作按钮注入 tab 栏右端）；
+    // 旧版本不支持时回退到内容区顶部两层显示方案（useHeader=true）
+    const supportsRightActions = service.features?.includes('rightActions') ?? false;
+    const descriptor = createTerminalTabDescriptor(supportsRightActions);
+    const dispose = service.registerTab(descriptor);
+    // 命令随插件销毁注销（registerTab 返回幂等 disposer）
+    ctx.effect(() => dispose, 'dsh-oh-my-terminal.sidebar-tab');
+    log.info(`已接入 DSH-better-sidebar 兼容模式（终端 tab 注册到底部工作台，rightActions=${supportsRightActions}）`);
+  } catch (error) {
+    // 注册抛错（如 tab id 已被其他插件占用）→ 降级为独立模式
+    const msg = error instanceof Error ? error.message : String(error);
+    log.warn(`betterSidebar registerTab 失败，降级为独立模式：${msg}`);
+    registerStandaloneDock(ctx);
+  }
 }
 
 /** 插件在 profile patch 中的条目 id（rowConfigKey 的后半段，不可随意改动） */