前言¶

在 DSH 插件生態中，智能體經常需要處理結構化文本。dsh-fmt 作爲一個客戶端插件提供，通過 format_text 工具解決了格式化和校驗 JSON、YAML、TOML 和 SQL 文本的問題。

是什麼¶

這是 ZhijiangTang 維護的一個 DSH 插件。它實現了 format_text 工具。它原生支持 JSON、YAML、TOML 和 SQL。它返回一個規範 JSON 值，包含 format、ok、output 和 error。它是純 ESM、無構建、無原生依賴。

安裝與啓用¶

首先執行以下命令將插件安裝到指定的配置文件中：

dsh plugin --profile <name> add file:./plugins/dsh-fmt

使用方法¶

調用 format_text 工具。必須提供 text 和 format。其他參數是可選的。

• text：要格式化/校驗的文本（必填）。
• format：目標格式（必填）：json、yaml、toml 或 sql。
• indent：縮進寬度。JSON/YAML 使用空格；SQL 使用製表符。默認爲 2。
• sqlDialect：SQL 方言。默認爲 standard。
• keywordCase：SQL 關鍵字大小寫。默認爲 upper。

返回值¶

工具總是返回一個規範 JSON 值：

{
  "format": "json",
  "ok": true,
  "output": "...",
  "error": {
    "message": "...",
    "line": 1,
    "column": 2
  }
}

如果解析成功，ok 爲 true，output 包含格式化後的文本。
如果解析失敗（例如 JSON 語法錯誤），ok 爲 false，output 不存在，error 包含錯誤消息和位置信息（如果可用）。這不會中斷智能體工作流。

示例¶

1. JSON 美化
   輸入 {"b":1,"a":[1,2]}，format=json，indent=2。

   {
     "b": 1,
     "a": [
       1,
       2
     ]
   }

2. YAML 校驗與美化
   輸入 YAML，format=yaml。它首先解析以校驗，然後序列化。

3. TOML 校驗與規範化
   輸入 TOML，format=toml。

4. SQL 格式化
   輸入 select a,b from t where x=1 order by b，format=sql，keywordCase=upper。

   SELECT
     a,
     b
   FROM
     t
   WHERE
     x = 1
   ORDER BY
     b

注意事項¶

• 純 ESM：該插件沒有構建步驟或原生依賴，可以直接加載。
• SQL 行爲：SQL 分支本身不做主動語法校驗。它直接將文本傳遞給 sql-formatter。如果文本無法解析，它返回 ok:false，而不是拋出異常。
• 錯誤處理：解析失敗不會中斷智能體。它返回 ok:false 和 error 對象。

結尾¶

這個工具解決了 DSH 智能體在處理結構化數據時的格式化和校驗需求。

• 目錄頁
• GitHub 倉庫