前言¶

在 DSH 插件生態中，Steno 專注於解決高頻指令重複輸入的問題。它通過 message.beforeSend 鉤子，在消息發送前將 #tag 替換爲預定義的完整文本。該插件由 JohnXu22786 維護，開源協議爲 MIT。

核心功能¶

• 即時展開：消息中的 #tag 會在發送前被替換爲配置的完整文本。
• 多庫管理：支持多個 YAML snippet 庫，按加載順序優先，重複標籤會觸發警告。
• 別名支持：單個 snippet 可綁定多個觸發名稱（aliases）。
• 變量佔位符：支持 {{name}} 和 {{name:default}}，由宿主提供值。
• 遞歸組合：snippet body 可引用其他 #tag，內置循環檢測、深度限制（默認 8）和展開次數限制（默認 200）。
• 代碼保護：fenced 代碼塊（``）和 inline code（）內的標籤不會展開。
• CLI 工具：提供 steno.save、steno.remove、steno.search 等命令行工具。

安裝與初始化¶

安裝插件需要 Node.js 版本 >= 22.18。

1. 安裝插件：

dsh plugin --profile demo add github:JohnXu22786/snippet-expander

2. 初始化配置文件：

npx dsh-steno init

初始化後，默認配置文件位於 ~/.dsh/steno/core.yaml。

配置與用法¶

編輯 YAML 文件添加 snippet：

name: core
entries:
  - tag: careful
    aliases: [safe]
    description: strict mode
    body: |
      Reason step by step, self-check before output, ask when in doubt, do not speculate.

在消息中輸入 #careful，系統會自動將其替換爲定義的 body 文本。

匹配規則¶

• 觸發格式爲 # + tag 名稱。
• Tag 必須以字母開頭（區分大小寫），可包含字母、數字、_ 和 -。
• #123 和 markdown 標題（如 # Heading）不會被匹配。
• 在中文等無空格語言中，#tag 可直接跟在漢字後（如 請#專注模式）。
• 轉義符 \#tag 會輸出字面量 #tag。
• 代碼塊內的標籤不會展開。

遞歸與限制¶

當 snippet body 引用其他 tag 時，插件會進行遞歸展開，但受到以下限制：
1. 循環檢測：同一 tag 不會出現在自身展開鏈中。
2. 深度限制：默認最大深度爲 8。
3. 次數限制：單條消息默認最多展開 200 次。

注意事項¶

• Node 版本：必須滿足 Node.js >= 22.18。
• 庫優先級：Library 文件按加載順序優先，前面的文件覆蓋後面的同名 tag。
• 佔位符行爲：{{name}} 在無值時保持原樣；{{name:default}} 使用默認值；佔位符內部不支持 tag 展開。
• 重複標籤：同一庫內重複 tag 會報錯；不同庫內重複 tag 僅警告，使用先加載的版本。

參考資源¶

• GitHub 倉庫：https://github.com/JohnXu22786/snippet-expander