dsh-open-path

简体中文 · English

/open — 用系统默认程序打开文件与 http(s) 链接、用文件管理器打开文件夹，支持路径直达、URL 直达与工作区模糊搜索。

dsh-TUI · 一个为 dsh-TUI 生态打造的插件

本插件为 dsh-TUI 生态插件，生态站点：https://dshtui.com/。Community v0.15 manifest，MIT 许可，支持 Windows / macOS / Linux（含 WSL）。

能力

• /open（无参数）→ 在系统文件管理器中打开当前会话工作目录
• /open https://example.com → 用默认浏览器/处理程序打开 http(s) 链接（大小写不敏感；仅放行 http/https，file:/ftp:/javascript: 等协议会明确报错拒绝）
• /open github.com → 裸域名自动补全协议：域名补 https://，localhost:5173/127.0.0.1:8080 补 http://（本地开发）；工作区内同名真实文件优先；常见文件扩展名（.md/.ts/.json…）不会被误判为域名
• /open src/index.ts → 打开存在的相对路径 / 绝对路径
• /open ~/docs → ~ / ~/… 展开为主目录（~user 不展开）
• /open readme → 模糊搜索当前工作区（文件名/目录名，中文与大小写不敏感，Unicode NFD/NFC 归一化）
  • 唯一命中 → 直接打开
  • 多个命中 → 托管对话框（TUI 接缝十）列出候选，不限条数：弹窗按终端高度开窗，↑/↓ 上下翻（带滚动箭头），Enter 打开，Esc 取消
  • 命中超过宿主弹窗上限（100 条）→ 只显示排名前 100 条，标题明确写出「共 N 个匹配，仅显示前 100 个」，绝不静默吞掉
  • 零命中 → 明确报错：工作区中找不到与 “…” 相关的文件或文件夹
• 目录命中 → 文件管理器打开该目录；文件命中 → 关联的默认程序打开

安装

# 从 npm 安装（名称：dsh-open-path）
dsh plugin --profile dsh-tui add dsh-open-path

# 本仓库本地安装（开发）
pnpm install --frozen-lockfile && pnpm build
cd ~/.dsh/profiles/dsh-tui && pnpm add <本仓库路径>
# 并把 dsh-open-path 加入 package.json 的 dsh.profile.bundles

安装后需在 TUI 内 /restart（或重开窗口）生效。

平台支持

打开动作按有序启动器链执行：链上第一个能成功启动（且未在宽限窗口内非 0 退出）的候选胜出，否则自动回退下一个；整链失败时明确报错并列出已尝试的启动器。链也可能是空的——Windows 上含 % 的文件/URL 没有可用的 cmd-free 通道——此时按「拒绝」明确报错并说明原因，而不是当作一次已尝试的交接。

| 平台 | 文件夹 | 文件 / http(s) 链接 | 备注 | |---|---|---|---| | Windows | Shell.Application COM，回退 cmd /c start | cmd /d /s /c start "" "<目标>" | 单实例 Explorer 会吞掉 start <目录> 请求，COM 通道是唯一可靠的文件夹打开方式；该 COM 子进程不能 detached（无控制台的 PowerShell 会丢调用），仅 windowsHide；含 % 的目标在 start 通道上被拒绝（cmd 即使加引号也会展开 %VAR%），而文件夹仍可经 COM 通道打开——其 PowerShell 单引号字面量不展开 % | | macOS | open | open | 文件名 NFD（磁盘）/NFC（键入）差异已在匹配层归一化 | | Linux | xdg-open → gio open → kde-open5 → kde-open → exo-open | 同左 | 需装其中任一（多数发行版带 xdg-utils）；三者都处理文件、目录与 URL | | WSL | wslview → 上述 Linux 链 | wslview → 上述链 → cmd.exe /c start | 没有 WSLg（无 DISPLAY/WAYLAND_DISPLAY）也判定为可用图形会话，改走 Windows 侧处理程序；含 % 的 URL 会跳过 cmd.exe 兜底，原因同 cmd 展开 |

失败判定不是"进程起来了就算成功"：启动器无法 spawn（如未安装 xdg-open → ENOENT）或快速非 0 退出（无关联程序）都会被识别并触发回退；目标路径本身不存在时直接明确报错，不会谎报 已打开。

回执还会写明成功依据是哪一种：只有启动器在宽限窗口内以 0 退出才写 已打开；窗口到期而启动器仍存活时写 已启动 …（未确认退出码）——超时绝不会被升格成「已确认打开」。

兼容性

• 依赖下限：@deepseek-harness-tui/dsh-tui >= 0.10.0-beta.5（命令注册面 C-041 托管面 + 回退；托管对话框为「稳定候选」接缝）
• Manifest：Community v0.15（commands.dsh/v1alpha1#Command 必需；commands.invoke 已声明，默认允许、可经授权文件 denies 撤销）
• 命令注册：优先 ctx.tuiPluginHost.registerCommand（C-041 归属 + invoke 检查点）；宿主未提供时回退到直接 commands 服务（C-070 边界，功能等效但无归属印记）
• 对话框：ctx.get('tuiDialogs', false) 软探测（#183 纪律）；服务缺失时降级为清晰报错并列出候选，绝不崩溃、不影响 TUI 启动
• 诊断日志：~/.dsh-tui/dsh-open-path.log —— 模块导入 / apply 开始 / 接缝探测（tuiPluginHost·commands·tuiDialogs 各 0/1）/ 注册结果 / 卸载各一行，超 128 KiB 裁剪保留最新一半；测试运行与 node --test 下不写
• 零依赖污染：不 import 上游包类型（结构式最小接口），上游版本漂移不会破坏本插件；也不复用 TUI 内部私有模块
• 无图形会话：Windows/macOS 恒可用（Windows 侧是假定而非探测，见 Known Limitations）；Linux 需 DISPLAY/WAYLAND_DISPLAY；WSL 例外（走 Windows 侧）。不可用时明确报错而非静默失败
• CI：ubuntu-latest / windows-latest / macos-latest（Node 24，另加 Ubuntu × Node 22 覆盖 engines 下限）

语言

命令回执、错误提示、候选项与命令提示都跟随宿主语言，解析链与 dsh-TUI 自身一致：

DSH_TUI_LANG → 运行中的 dsh-tui 设置命名空间（/lang 的落点）→ ~/.dsh-tui/lang.json → 系统 locale → 中文。

• 语言存在但不支持（例如 fr）时回落英文；完全没有信息时沿用中文，保证中文宿主的行为与加入双语之前逐字一致。
• 回执在每次调用时重新解析语言，所以 /lang 切换无需重启；命令补全里的提示文字是注册时的快照，重启后跟随新语言。
• DSH_OPEN_PATH_LANG_FILE 可覆盖偏好文件路径（测试与诊断用）。

配置

| 键 | 默认 | 说明 | |---|---|---| | maxCandidates | 0 | 选择框最多展示的候选数；0 = 不限量（全部模糊匹配，仍受宿主弹窗上限 100 条约束），也可设成正整数自己收窄 | | includeHidden | false | 是否索引隐藏（点开头）文件/目录 |

配置经 /settings 或 profile 的 cordis 配置覆盖；所有键都有默认值，缺失时降级为默认行为。

工作目录语义

命令以接收会话的工作目录（agent.session.header.cwd，DSH 会话头记录的 host-side cwd）为基准，而非进程 cwd——TUI 里 /workspace 切换会新建会话，新会话头即新目录，所以 /open 始终跟手；极端情况下按 session.meta.cwd（旧版宿主别名）→ 进程启动目录依次回退。

模糊索引的相对路径统一以 / 分隔（Windows 下同样成立），因此同一份索引在三个平台语义一致。

Model Experience

命令在 UI 命令平面执行，结果文本由适配器直接渲染：不产生模型消息、不计入模型 token、不进入模型 KV 缓存。command/run / command/done 仅以 log-only 事件记录到会话日志。

Known Limitations

• 只接受 http:// / https:// 链接（含裸域名自动补全）；file:、ftp:、javascript:、mailto: 等其它协议明确报错拒绝，不会交给系统处理。裸域名猜测豁免常见文件扩展名（.md/.ts/.json 等按文件处理），单字符 TLD（如 a.b）与版本号（v2.0.1）也不会被当作网址。
• 模糊索引受深度（≤6 层）、条目数（≤20000）上限约束；超大仓库下扫描在取消信号/上限处截止，超出的部分不被检索。
• 托管选择框的条数由宿主兜底：dsh-tui 0.10.x 的 tuiDialogs.select 只保留请求里的前 100 个选项（超出静默丢弃，插件拿不到该常量）。本插件因此主动对齐 100 条并在命中更多时于标题写明，但超过 100 条的候选在当前宿主上无法展示；需要真·不限量得改走 tuiScenes 自绘选择器。
• 指向目录的符号链接会被索引为目录，但不会被递归遍历（防环、防越出工作区）。
• ~ 展开仅支持 ~ / ~/… / ~\…，不解析 ~user（无 passwd 查询）。
• 打开目标是文件但系统无关联程序时，行为由系统决定（Windows 可能弹出「如何打开」对话框）——保持平台默认，不擅自选择程序。
• 打开动作仍是 fire-and-forget：只在 180ms 宽限窗口内观测失败并回退，之后不再等待目标程序加载完成；窗口后仍崩溃的启动器不会被察觉。窗口最多只能证明「仍在运行」，所以回执把两种读法区分开——已打开 要求窗口内以 0 退出，窗口到期而启动器仍存活时报 已启动 …（未确认退出码）。
• Windows 上含 % 的目标无法交给 cmd：%VAR% 即使加双引号也会被展开，因此百分号编码的 URL（https://x.com/a%20b%20c）或形如 50%off 的路径会被静默改写成另一个目标，这正是拒绝它的原因。此类文件/URL 会被明确报错拒绝并点明 %；含 % 的文件夹仍可打开，因为它走的是 PowerShell COM 调用，单引号字面量不展开 %。macOS/Linux/WSL 通道原样透传 %。
• Windows 侧假定总有图形会话（hasGraphicalSession() 恒定返回 true），因此无桌面的 Windows 主机——纯 SSH 会话、服务账户——不会被报「无图形会话」；这类主机上的打开结果可能不准确。
• xdg-open 在部分桌面环境会阻塞到应用退出——本插件不受影响（宽限窗口后即视为已打开）。

发布

• 仓库：https://github.com/VviLliAm-qwq/dsh-open-path（公开）
• 版本：语义化版本；发布由 v* tag 驱动（.github/workflows/release.yml：校验 tag 与 package.json 版本一致 → build/test/校验 → npm publish --provenance → GitHub Release）
• 前置：npm 包已配置 Trusted Publisher（GitHub Actions · 本仓库 · release.yml）——发布走 OIDC，无需在仓库里存放任何令牌
• 生态收录：按 https://dshtui.com/plugins/ 的收录要求，本 README 顶部带有 dsh-TUI 链接（该站给出的固定写法：[dsh-TUI](https://github.com/ccch1mneyyy/dsh-TUI) · 一个为 dsh-TUI 生态打造的插件）

开发与验证

pnpm install
pnpm build             # tsc -> lib/
pnpm test              # vitest（平台分支通过注入 platform/env 实现跨平台覆盖）
pnpm validate:manifest # dsh-plugin.json 准入形状检查
pnpm pack:verify       # 发布包布局检查
pnpm prepublishOnly    # 四合一

License

MIT