前言¶
在 DSH 里跑命令，常见做法是写一条规则：Linux 工具走 WSL，结构化管道用 nushell，MSYS 里用 bash，交互式安装脚本要真终端。规则写在文档里并不等于会话能稳定执行——过去往往只能再拼一条 pwsh 命令字符串，引号与路径在多层转义里很容易坏掉。维护者 Nesarf 的客户端插件 dsh-shell-surfaces 把这些「执行面」做成一个可调用工具 shell_surfaces：先查本机有哪些面，再按面名执行，形状与内置 shell 类工具在沙箱、后台任务、持久会话上对齐。插件归类为客户端，可在 SkillHub 目录页 查看条目；社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。
这是什么¶
一句话：把当前机器上的 WSL Linux 用户态、nushell 结构化管道、MSYS2 用户态（bash / zsh / fish / brush）、PowerShell 本身，以及供交互程序使用的真实控制台，统一暴露为一个 DSH 工具。
插件自述动机是：只写在纸面上的选择规则不是能力；这里把规则变成可调用接口，避免「例外情况再换另一个 shell 工具」成为默认路径。README 也说明，这是跑命令时的首选工具之一，而不是仅用于边角场景。
许可证为 MIT（见仓库 badge 与 package.json）。当前 package.json 中版本号为 0.1.0；对 DSH 的 peer 依赖为 @deepseek-ai/dsh >=0.2.0-rc.2 <0.3.0-0，并可选依赖 @deepseek-ai/dsh-sandbox 0.2.0-rc.2。运行环境要求 Node >=20。
核心功能¶
单一工具、多种 surface¶
所有面通过同一工具名调用，用 action 区分行为：
action="surfaces"：列出当前可运行的面，以及扫描发现了什么。action="run"：在指定surface上执行command。
README 给出的示例覆盖了 WSL、nushell（nu）、MSYS（msys）、PowerShell（pwsh）以及带伪终端的交互（pty，可用 send 发送输入）：
shell_surfaces(action="surfaces")
shell_surfaces(action="run", surface="wsl", command="grep -P '(?<=Linux )[0-9.]+' /proc/version")
shell_surfaces(action="run", surface="nu", command="open data.json | where n > 3 | to json")
shell_surfaces(action="run", surface="msys", command="pacman -Q | wc -l")
shell_surfaces(action="run", surface="pwsh", command="Get-CimInstance Win32_OperatingSystem | Select-Object Caption")
shell_surfaces(action="run", surface="pty", command="powershell -File install.ps1", send=["y\n"])
PowerShell 也是普通一面¶
pwsh 面让 PowerShell 命令与其它面同一调用形状，不必为了「这条是 PowerShell」就离开本工具。README 明确区分：内置 pwsh 工具仍负责审批、沙箱升级和持久会话等能力；本插件的 pwsh 面不携带这些，但「命令本身是 PowerShell」不应成为换工具的理由。某面缺失、无法拉起或超时时，工具会说明原因，并提示可再调 action="surfaces"，失败归因于面而非工具本身。
后台任务与超时升格¶
run_in_background: true 以作业方式启动并返回 id；输出经 ring 流式给出，可用 job_output 读取、job_kill 终止，且无超时限制。promote_on_timeout: true 在超时时把进程升格为同类作业，而不是直接杀掉：超时前已收集的输出一次性交出，其余继续流式输出。若组合环境没有 jobs 服务，后台请求会被拒绝；pty 面不支持后台模式。
沙箱与一次性放宽¶
与内置 shell 工具相同：受约束部署下，每次调用经 ctx.sandboxPolicy 解析策略，对即将 spawn 的 argv 走 ctx.sandbox.confine，并以同一套词汇汇报模式、 enforcement 与拒绝事实。danger-full-access 不咨询 provider；无沙箱服务时行为与从前一致。策略拒绝的文件效应是策略结论，不是命令执行失败。可通过 sandbox_permissions 加 justification 向 ctx.approval 申请单次放宽，授予仅消费于该次调用。同轮结果里会带拒绝提示，便于 sanctioned 重试。
持久会话¶
传入 session: <name> 可在每个（agent, surface, name）上维持长驻 shell：工作目录、变量与模块跨调用保留；session_reset: true 可开新会话。会话是带管道的进程而非终端，用随机 nonce 行标记单次命令输出结束。会话与作业标志互斥；pty 无会话模式。
本机 shell 发现与刷新¶
内置候选表结合 PATH 与机器上的安装位置做扫描（模型借鉴 mega-index-map 的 library_detect），代价约为每个 PATH 目录一次列举、少量 stat 以及一次 wsl -l -q，而非全盘遍历。扫描结果会扩展或修正表项，例如：非默认 WSL 发行版成为 wsl-<distro> 面；Git-for-Windows 或 Cygwin bash 成为 git-bash（MSYS2 仍用 msys）；cmd.exe 成为 cmd 面；终端程序（wt、mintty、wezterm 等）出现在 discovered 中，不作为可执行面。action="surfaces" 同时返回可运行面与 discovered 报告。refresh: true 可在查询时重新扫描；surface 为开放字符串，由扫描决定 id，执行时对照当前持有的扫描结果校验。
客户端展示¶
插件通过 lib/client.js 注册 tool.call.toolview，调用行展示为「面 · 命令」式句子，而不是仅显示线缆工具名（README 截断示例中有 WSL · grep ... 等形式）。package.json 中 dsh.client 面向 web 平台，并注入 @deepseek-ai/dsh-client-locale 与 @deepseek-ai/dsh-client-ui-tool。
安装与启用¶
安装命令以 README 原文为准（需指定 profile）：
dsh plugin --profile <profile> add github:Nesarf/dsh-shell-surfaces
安装前建议阅读仓库源码与 MIT 许可证。插件在 DSH 进程权限下运行，与本机其它 DSH 工具相同；在受信环境外启用前应自行评估风险。
典型用法¶
先做环境探测，再按面执行，是 README 演示的基本顺序。
- 调用
shell_surfaces(action="surfaces")（必要时加refresh: true）确认本机可用的surface标识。 - 对 Linux 专属命令选
wsl（或扫描得到的wsl-<distro>）；结构化数据处理选nu；MSYS 包管理或 POSIX 环境选msys；纯 PowerShell cmdlet 选pwsh。 - 需要程序读 stdin 或类似交互时，用
pty面，并通过send传入换行结尾的输入序列。 - 长时间命令考虑
run_in_background: true或promote_on_timeout: true，并确保环境提供 jobs 相关能力。
避免在 pwsh 字符串里再嵌套一层其它 shell——README 强调多余引号层是路径被弄乱的主要来源；应直接选对应 surface。
适用场景与注意¶
适合需要在同一 DSH 会话里按规则切换 WSL、nushell、MSYS、PowerShell 或真控制台、又不想为每种环境单独注册七个工具描述的开发者与智能体编排场景。Windows 与 Linux 上仓库 CI（test.yml）包含自测与双 runner 探针，badge 为绿表示表结构与 argv 形状仍成立且两平台均有应答，而不只是 linter 通过。
注意：pty 无后台与会话；持久会话与作业标志不能同时使用。无 sandbox / approval / jobs 服务时，相关能力会按 README 描述降级或拒绝。SkillHub 条目星标为 0，不代表功能完备度，仅反映目录统计。
链接¶
- 目录页：https://www.skillhub.cn/plugins/Nesarf/dsh-shell-surfaces
- GitHub：https://github.com/Nesarf/dsh-shell-surfaces
经过上面的步骤，可以把「本机有哪些 shell、该用哪一个」从文档规则变成一次工具调用；在 DSH「一切皆插件」的生态里，这是客户端侧对多执行面的一次收口。
