实用插件合集 tkwkeven/dsh-utility-plugins

dsh-utility-plugins

DeepSeek Harness（DSH）实用小插件合集。三个插件各自独立、零依赖或近零依赖，按需取用：

| 插件 | 文件 | 作用 |
| ytdlp | plugins/ytdlp.mjs + plugins/ytdlp_cli.py | 视频/音频查询与下载工具（yt-dlp 桥接） |
| reasoning-effort-auto | plugins/reasoning-effort-auto.mjs | 模型推理强度（reasoning effort）跨 Provider 自动适配 |
| preflight | plugins/preflight.mjs | 插件源码预检：BOM / UTF-8 / mojibake / 语法检查 |

三个插件都通过 cordis.patch.yml 挂载，注册的工具对所有会话（Web GUI、飞书/Lark 等）可用。

1. ytdlp — 视频/音频查询与下载工具

解决什么问题

DSH 会话中经常需要「查一下这个视频是什么 / 下载这段视频发给用户」，但：

- 让模型直接拼 shell 命令调 yt-dlp 非常危险：URL 与格式串会经过 shell 命令行，存在注入风险，且参数一多就容易出错；
- yt-dlp 输出大、格式杂，原始 stdout 灌给模型既浪费 token 又难以结构化消费；
- 下载目标目录缺少边界校验，模型可能把文件写到任意位置。

功能

注册两个工具（全会话可用）：

- video_info：不下载，仅查询链接元信息——标题、上传者、时长、清晰度（最高分辨率）、可用格式数、播放列表条目数等。下载前先确认链接有效与内容。
- video_download：下载视频或提取音频，返回本地文件路径（可与飞书 [lark-file:] 标记配合直接发送给用户）。支持播放列表、音频提取（mp3/m4a/opus）、cookies、代理。

安全设计：

- stdin/stdout JSON 桥接：URL、格式串、输出路径一律不经过 shell 命令行（无注入面）；
- 路径越界校验：output_dir 必须落在下载根目录内，否则拒绝；
- 格式白名单化：format 拒绝以 - 开头的选项串、拒绝超长输入；
- URL 校验：仅接受 http/https，长度上限 8KB；
- 支持 1000+ 站点（YouTube、Bilibili 等，由 yt-dlp 项目提供）。

安装

- insert:
- id: ytdlp
name: ./plugins/ytdlp.mjs
config:
cliPath: 可选，ytdlp_cli.py 的绝对路径（默认：与插件同目录的 ytdlp_cli.py） pythonBin: 可选，Python 解释器（默认 "python"） downloadDir: 可选，下载根目录；绝对路径原样使用，相对路径相对工作目录解析（默认 "downloads"）

把 ytdlp.mjs 与 ytdlp_cli.py 放在同一目录（ytdlp_cli.py 会被自动找到）。依赖：Python 3 + yt-dlp（pip install yt-dlp）；音频提取与格式合并需要 ffmpeg（缺省时纯音频按原始流下载）。

输出示例

video_download 返回 { ok, filepath, title, duration, download_dir, ... }，可直接用 [lark-file: <filepath>] 发到飞书会话。

2. reasoning-effort-auto — 模型推理强度自动适配

解决什么问题

DSH 在多个模型供应商之间切换时，各家的「推理强度」档位并不一致，例如：

- DeepSeek 路由（deepseek-v4-flash）：支持 off | high | max
- MiMo Token Plan 路由（mimo-）：只支持 off | minimal | low | medium | high

若某个会话/插件固定请求 max（例如飞书任务会话默认请求最高强度），切到 MiMo 路由后请求会直接失败：UNSUPPORTED_REASONING_EFFORT。用户只切换了模型，会话却创建不出来。

功能

注册一个宿主服务 ctx.reasoningEffortAuto.clamp(selection, desired)：

- 查询目标 provider/model 实际支持的能力（ctx.llm.resolveModelInfo），
- 若 desired 已被支持则原样返回；否则向下收敛到支持列表里最强的档位（如 max → high），
- 能力查询失败时保持原值返回——宁可让下游按原档位请求，也不因本服务导致会话创建失败。

任何插件（如 lark-channel）在组合新会话的模型选择时调用 clamp；本插件未挂载时请求原样透传。

安装

- insert:
- id: reasoning-effort-auto
name: ./plugins/reasoning-effort-auto.mjs

依赖：DSH 宿主的 llm 服务（ctx.llm.resolveModelInfo）。需在依赖它的插件（如 lark-channel）之前挂载。

3. preflight — 插件源码预检

解决什么问题

Windows 上编辑/部署 DSH 插件文件时有一套经典的「编码三连坑」，会直接导致 DSH 启动失败：

1. PowerShell 5.1 的 Get-Content 默认按 ANSI/GBK 读 UTF-8 文件 → 内容变成乱码；
2. Set-Content -Encoding UTF8 写出带 BOM 的文件（Node ESM 通常能容忍 BOM，但叠加第 1 条时内容已经坏了）；
3. 两者叠加 → 插件文件变成「带 BOM + 内容错乱」（mojibake）→ DSH 启动时 SyntaxError，日志却可能一片空白，静默宕机、无人知道为什么。

功能

双模式复用：
- 命令行：node preflight.mjs [--fix] [--no-syntax] <file...> — 检查并报告（--fix 自动剥离 BOM）；exit 0 = 全部通过 / 已修复，exit 1 = 存在不可自动修复的问题，调用方应拒绝启动。输出为纯 ASCII JSON，避免 PowerShell 按 ANSI 读取输出时二次乱码。
- import：checkText(text, { name })（检查字符串源码）、checkFile(path, { fix, syntax })
（检查单个文件）、checkFiles(paths, opts)（批量检查），供其他工具（如
dsh-sim-restart-tester）复用。

检查项：

| 检查项 | 判定 |
| UTF-8 BOM（EF BB BF） | 检出即告警；--fix 自动剥离 |
| 非法 UTF-8（GBK/ANSI 或损坏） | 拒绝（启动必失败） |
| 解码替换符 U+FFFD | 拒绝 |
| GBK 二次编码（mojibake 特征字） | 命中特征字即拒绝，提示用 UTF-8 重新保存 |
| 语法检查 | .mjs / .js 执行 node --check，失败给出前 3 行错误 |

安装

无需挂载为插件（无运行时副作用），适合作为启动前预检脚本或集成进其他插件：

node preflight.mjs --fix plugins/.mjs

目录结构

dsh-utility-plugins/
├── plugins/
│ ├── ytdlp.mjs 视频下载工具（宿主插件） │ ├── ytdlp_cli.py yt-dlp 桥接命令行（stdin JSON -> stdout JSON） │ ├── reasoning-effort-auto.mjs 推理强度适配服务（宿主插件） │ └── preflight.mjs 源码预检模块（命令行 + import 双模式） ├── LICENSE ├── package.json └── README.md

许可

MIT License，见 LICENSE。