前言¶

在 DSH 里，输入框上方的空间有限。一些信息（比如当前环境、运行状态、插件更新）需要一直可见，但又不想占掉一整段对话。如果每个插件各自在输入框附近找位置，样式会打架、主题也会不一致。dsh-plugin-status-bar 把这个位置统一成一条状态条：宽度比输入卡片略窄、居中、与卡片上沿贴合，由宿主的令牌决定尺寸和材质。任何客户端插件都可以往这个条里放自己的状态段。

是什么¶

这是一个 DSH 客户端插件（vianvio 维护），当前版本 0.2.1。它不包含任何业务逻辑，只负责维护那条状态条容器，并向其它插件提供一个注册面 inputStatusBar。使用方插件往注册面里注册段，就能在输入框上方展示自己的状态信息。

核心功能¶

• 维护输入框上方的状态条容器：宽度、圆角、材质与贴合方式全部由宿主令牌推导，不写死。
• 提供注册面 inputStatusBar，任何客户端插件都可以往里注册自己的段。
• 没有段时整条容器不渲染，不会在界面上留下空壳占位。
• 段之间自动插 1px 分隔线；align: "end" 的段会被推到右侧。
• 同一时间只展开一个面板；Esc / 点击外部关闭；↑ ↓ 在面板项之间移动焦点。
• 使用方插件被回收时，它注册的段会自动注销。
• 提供一套样式契约，包括容器外壳类名、段内容与面板内容的公开积木类名，以及主题令牌。

安装与启用¶

推荐使用 npm 安装：

dsh plugin --profile desktop add dsh-plugin-status-bar

--profile 填你实际在用的那个（桌面端是 desktop，Web 端是 web）。安装后重启 DSH 生效。

如果需要安装来自 GitHub 最新提交的版本（还没发版），或者从本地目录安装（用于开发），可以使用：

dsh plugin --profile desktop add github:vianvio/dsh-plugin-status-bar

或者：

git clone https://github.com/vianvio/dsh-plugin-status-bar.git ~/dsh-plugin-status-bar
dsh plugin --profile desktop add link:$HOME/dsh-plugin-status-bar

以后升级或卸载：

dsh plugin --profile desktop update dsh-plugin-status-bar
dsh plugin --profile desktop remove dsh-plugin-status-bar

典型用法¶

在你的客户端插件中，通过 ctx.inputStatusBar 注册一个段。下面是一个使用 React 的示例：

// 你的客户端插件 client.js
window.__ModuleLoader__.load({
  id: "your-plugin",
  factory: (require) => {
    var module = { exports: {} };
    var exports = module.exports;
    var react = require("react");

    function CafeSegment(props) {
      return react.createElement(props.Segment, {
        id: "cafe",
        open: props.open,
        onToggle: props.toggle,
        title: "咖啡",
        menu: props.open ? react.createElement("div", { className: "dshStatusHint" }, "面板内容") : null,
        menuAvailable: true
      },
        react.createElement("span", { className: "dshStatusDot", style: { background: "#f59e0b" } }),
        react.createElement("span", { className: "dshStatusLabel" }, "咖啡"),
        react.createElement("span", { className: "dshStatusText" }, "2 杯")
      );
    }

    exports.name = "your-plugin";
    exports.inject = ["inputStatusBar"];
    exports.apply = (ctx) => {
      ctx.effect(() => ctx.inputStatusBar.register({
        id: "cafe",
        order: 120,
        component: CafeSegment
      }));
    };
    return module.exports;
  }
});

也可以完全走数据驱动，只提供数据而由容器渲染：

ctx.inputStatusBar.register({
  id: "market",
  order: 200,
  align: "start",
  label: "插件市场",
  status: "3 条更新",
  tone: "pass",
  dot: true,
  menu: MarketPanel,
  onSelect: (api) => {},
});

注册面 API 提供了 register(item)、unregister(id)、update(id, patch)、list()、subscribe(fn) 和 revision() 等方法，可以用来管理段的生命周期、更新内容和监听变更。

几何与样式契约¶

尺寸不写死，全部由宿主 composer 的令牌推导：

• --dsh-composer-side-clearance：输入卡片距 composer 栈边缘的留白（0.2.0-rc.2 为 16px）。
• --dsh-composer-dock-inset：dock 面板相对卡片边缘的内缩单位（0.2.0-rc.2 为 8px）。
• --dsh-composer-card-max-width：输入卡片宽度上限。
• --dsh-composer-stack-gap：堆叠间距，被负 margin 吃掉，让状态条贴住卡片上沿。
• 主题提供 --dsw-radius-lg、--dsw-specific-menu、--dsw-menu-backdrop-filter 等变量。

推导式：相对 composer 栈边缘内缩 side-clearance + 2 × dock-inset，也就是相对输入卡片边缘内缩 2 × dock-inset。

如果想自己调整宽窄，可以覆盖 --dsh-status-bar-inset（相对 composer 栈边缘）。

容器外壳类名包括 .dshStatusDockRow、.dshStatusBar、.dshStatusSeg、.dshStatusSegButton、.dshStatusSegStatic、.dshStatusSegBody、.dshStatusChevron、.dshStatusPanel 等。段内容与面板内容可以直接复用的公开积木类名包括 .dshStatusDot、.dshStatusLabel、.dshStatusText、.dshStatusHead、.dshStatusBadge、.dshStatusRow、.dshStatusSep、.dshStatusCell、.dshStatusHint 等。

适用场景与注意¶

适合需要持续显示状态信息的客户端插件，比如环境信息、运行状态、更新提示等。它是一个基础设施，不认识任何业务，文案、颜色语义、面板内容都由使用方决定。

注意：只负责输入卡片上方那一条，不碰卡片内部的工具行（模型选择、权限、附件等），以免抢位次导致输入框抖动。容器几何依赖宿主的 --dsh-composer-* 令牌，如果宿主改掉这些令牌名称，宽度会退回回退值。安装前建议检查源码与许可证。

小结¶

dsh-plugin-status-bar 把输入框上方的状态展示统一到一个容器里，通过 inputStatusBar 注册面让其它插件可以按自己的方式注入状态段。它不包含业务逻辑，只保证外壳、交互与主题一致，适合需要长期可见、又不值得占一段对话的信息展示场景。

• 目录页：https://www.skillhub.cn/plugins/vianvio/dsh-plugin-status-bar
• GitHub：https://github.com/vianvio/dsh-plugin-status-bar