dsh-prompt-snippets

dsh plugin --profile web add dsh-prompt-snippets

提示词片段库（Prompt Snippets）





<p align="center">

<img src="docs/feature-map.svg" alt="Prompt Snippets 占位符三态填充流程" width="800">

</p>

保存并一键插入可复用的提示词片段，支持分类与 {{占位符}}。

一个让「常用提示词」随手可得、不重复造轮子的 DSH 插件。片段数据保存在本机

<DSH_HOME>/data/prompt-snippets/snippets.json。默认只存本机、不上传任何内容；

仅当你主动点击 ✨ AI 优化时，才会把当前那一条片段文本发送给你配置的模型服务

（用于生成优化建议），除此之外不与网络通信。

安装

dsh plugin --profile web add dsh-prompt-snippets

web 换成你实际使用的 profile 名即可（本机 profile 在 ~/.dsh/profiles/<名字>）。

装完重启 DSH，刷新页面，输入框工具条那一行会出现「📋 片段库」按钮（与模型选择器、权限控件同排，位于发送按钮之前）。

也可以从 GitHub 装（版本由仓库 HEAD 决定，不跟随 npm 发布）：

dsh plugin --profile web add github:dadazhangn/dsh-prompt-snippets

本地源码调试用路径安装：

dsh plugin --profile web add link:C:/path/to/dsh-prompt-snippets

Install (English)

dsh plugin --profile web add dsh-prompt-snippets

Or install straight from GitHub (github:dadazhangn/dsh-prompt-snippets), which

tracks the repository HEAD instead of the published npm version. Then restart DSH

and reload the page.

功能

• 保存片段：/snippet add <名称> <内容> 保存一段提示词（同名即更新）。
• 分类：用 --cat=<分类>（或 -c=<分类>）指定分类，例如

/snippet add 代码审查 请审查以下代码：{{代码}} --cat=开发；面板按分类分组展示。

分类参数只认行尾：正文中间的 --cat 会按字面保留，不会被当成参数吃掉。

想在正文结尾真的写 --cat，用 -- 结束选项：/snippet add 说明 结尾是 -- --cat。

更新内容时不带 --cat 会保留原分类，不会被清空。

• 列出 / 查看 / 删除 / 恢复 / 改名：/snippet list、/snippet show <名称>、

/snippet rm <名称>、/snippet undo <名称>、/snippet mv <旧名> <新名>。

重名时不会瞎删，会列出候选让你用 #id前缀 精确指定。

• 一键插入：输入框工具条上的「📋 片段库」按钮展开面板，按分类浏览，点击片段即插入当前

草稿。插入失败（草稿在面板打开期间被改动、或输入框正在提交）会在面板内说明原因。

• 面板内编辑 / 新建：点 ✏️ 在原行下方展开编辑器，改名称、分类、正文，并直接维护

变量（必填勾选 + 默认值）；面板底部「＋ 新建」同样在面板内完成创建，全程不用敲命令。

保存走乐观锁：两个标签同时改同一条时，后保存者看到冲突横幅，可选「覆盖」或

「重新载入」服务器版本。草稿没保存时点面板外部不会关闭面板，取消也要二次确认。

• 搜索：按名称、分类、正文实时筛选，打开面板自动聚焦。命中词在名称里高亮标记，

右侧实时显示 当前/总数 命中计数；键盘 ↑ ↓ 移动选中、Enter 插入选中项、Esc 逐层退出。

无命中时给出「＋ 新建『搜索词』」按钮，点一下把搜索词预填为新片段名。

• 删除可撤销：点 🗑 删除后底部出现撤销条，记住最近 5 条，可逐条恢复或一键全部撤销。
• AI 优化（对比后决定）：点 ✨ 用当前默认模型改写片段，结果进「原文 / 优化后」双栏对比，

不直接插入、也不自动落盘。优化后那一栏可直接编辑——微调后再决定怎么用。对比视图里给出

字节数变化与占位符保全标记（丢了哪个 {{x}} 会点名，字节数随编辑实时重算），

按钮为「插入优化版」「替换片段正文」「再试」「保留原文插入」「✕」：

• 「插入优化版」只进输入框，不动库里的片段；插入的是你编辑后的文本；
• 「替换片段正文」是唯一会落盘的动作，带 expectedRevision 乐观锁；冲突时只提供

「用优化版覆盖（force）」与「放弃」，不做自动合并；

• 优化结果超长或丢了占位符时「替换片段正文」禁用，title 写明原因；把超长部分删短后自动解除；
• 「再试」最多 3 次，之后置灰；「取消」走 AbortController，host 回 aborted 时静默收起；
• 当前未配置默认模型时 ✨ 直接置灰，title 说明原因，不会等到点击才报错。
• {{占位符}} 智能填充：正文里写 {{主题}} 之类占位符，点击片段时：
• 无占位符 → 直接插入；
• 占位符全部非必填且都有默认值 → 按默认值直接插入，并提示「可在 ✏️ 里改」；
• 有必填占位符（或旧数据缺变量元数据）→ 弹表单逐项填写，必填为空时「插入」禁用，

也可选「保留占位符插入」原样插入。

\{{字面量}} 转义后插入的是字面 {{字面量}}；同名占位符只问一次，全实例填同一个值。

• 动态变量：{{date}} / {{time}} / {{datetime}} 是内置宏变量，插入时用本地时间实时

替换（date = YYYY-MM-DD、time = HH:mm、datetime = YYYY-MM-DD HH:mm:ss），

不弹表单、也不进变量元数据；正文里只有动态变量的片段点一下即可直插。

• 内置模板包：首次运行（数据文件尚不存在）自动预置一组高频片段（代码审查、Git 提交信息、

Bug 排查、周报、日报、翻译润色、会议纪要、学习计划），给你一个冷启动起点。删掉后不重灌，

已有数据文件（哪怕清空成 0 条）也不会再注入。

• 导入 / 导出：/snippet export [文件名] 把全部片段导出成 JSON，落在

<DSH_HOME>/data/prompt-snippets/exports/ 下；/snippet import <文件路径> 导回来，

--replace 用文件内容替换现有库（未出现在文件里的片段软删除，仍可 /snippet undo），

--dry 只预演不写入。面板底部同样有「⬇ 导出」「⬆ 导入」两个按钮，导入填路径即可

（面板拿不到宿主文件系统，路径由 host 侧读取；省略目录与 .json 后缀时回落到 exports/）。

• 深浅色主题跟随：面板全部使用 DSH 主题 token，浅色 / 深色自动适配，无白底刺眼。
• 窄屏可用：面板宽度取 min(340px, 100vw - 16px)，窗口缩到 320px 也不溢出，

并会在视口变化后自动拉回可视区。

• 可拖动可记忆：拖标题栏移动面板，位置记在浏览器本地，下次打开还在原处。
• 可缩放可记忆：面板四条边和四个角都能拖（像 Windows 窗口），拖边缘调宽高（最小 200×160），

松手后尺寸记在浏览器本地，下次打开沿用上次大小；缩到超出视口会自动收窄拉回。

• 标签：/snippet tag <名称> <标签1、标签2…> 给片段打标签（逗号/顿号/空格分隔，最多 32 个、

每个最长 24 字）；add/save 也能用 --tag= 带上。面板里标签以圆角 chip 显示在名称后。

• 收藏置顶：/snippet pin <名称> 收藏、/snippet unpin <名称> 取消（add 也可 --pin）。

面板顶部有「全部 / ★ 收藏 / 最近使用」三个视图切换按钮，收藏视图只看置顶项，

最近使用按 lastUsedAt 降序、最多 20 条。

• 版本历史：每次保存前的旧内容自动留档（每片段最多 20 版、单片段历史体积超限丢最旧）。

面板里点 🕘 展开该片段的历史，可回看历次正文；/snippet show 也会显示 revision 号。

• 命令面板（全局快捷唤起）：任意时刻按 Ctrl+Shift+K（或 Ctrl+Shift+P）弹出片段搜索

浮层，输入关键字即时过滤（名称/分类/标签/正文），↑ ↓ 选择、Enter 插入、Esc 关闭；

收藏片段自动置顶，无需先点开片段库面板。选中后按 Ctrl+Enter（Mac Cmd+Enter）则是

插入并立即发送；带必填占位符的片段仍需先填表单，无法直接发送。↑ ↓ 切换选中项时

列表自动滚动跟随，始终把选中项保持在可视区内。

使用

/snippet add 代码审查  请审查以下代码并指出问题：{{代码}}
/snippet add 周报  总结本周工作：{{要点}} --cat=写作
/snippet list
/snippet show 周报
/snippet rm 代码审查
/snippet undo 代码审查
/snippet mv 周报 日报
/snippet pin 周报
/snippet tag 周报 工作、总结
/snippet optimize 周报
/snippet export 我的片段
/snippet import 我的片段.json --dry
/snippet import 我的片段.json

然后在任意会话里，点击输入框工具条上的「📋 片段库」→ 点击片段名 → 内容插入草稿。

要改内容或改分类，不必再敲命令：面板里点 ✏️ 直接改，改完点「保存」。

数据

• 文件：<DSH_HOME>/data/prompt-snippets/snippets.json（DSH_HOME 未设置时为 ~/.dsh）。
• 结构（version: 4）：

  {
    "version": 4,
    "snippets": [
      {
        "id": "uuid",
        "name": "名称",
        "category": "分类或 null",
        "content": "正文",
        "variables": { "变量名": { "label": "…", "default": "…", "options": ["…"], "required": false } },
        "tags": ["标签"],
        "pinned": false,
        "pinnedAt": null,
        "createdAt": 0,
        "updatedAt": 0,
        "deletedAt": null,
        "revision": 1,
        "useCount": 0,
        "lastUsedAt": null
      }
    ]
  }

• 写入是原子的：先写同目录临时文件 → fsync → 轮换 .bak → rename 覆盖。

进程中断不会留下半个 JSON，最坏情况是文件停在上一份完整内容。

• 写入是串行的：并发保存/删除排队执行，不会互相覆盖。
• 每次都留 .bak：snippets.json.bak 永远是上一次成功写入的完整 JSON，

手滑改坏也能逐字节恢复。

• 备份轮换：.bak 写新值前先逐级后移成 .bak.1 /

…(truncated)