前言¶

在 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 仓库