dsh-json-yaml-toolkit

dsh-json-yaml-toolkit

结构化数据工具箱（v0.3.0）：JSON/YAML/TOML 互转、点路径查询、JSON Schema 校验；支持 YAML 多文档（--- 分隔）拆分与 CSV 引号风格控制。

主要功能介绍

dsh-json-yaml-toolkit 面向 JSON / YAML / TOML / CSV 的解析、转换与校验，共 6 个工具：

工具	功能	要点
convert_format	格式互转	JSON / YAML / TOML 互转，源格式自动嗅探；TOML 做往返校验，有信息损失输出 ⚠
query_json	点路径查询	address.city、tags.0、users[*].name（通配与嵌套通配展开）
validate_schema	Schema 校验	按 JSON Schema（JSON/YAML）校验，allErrors 模式列出全部错误路径
diff_data	结构化比对	递归比对两份数据，报告增/删/改路径与新旧值
convert_csv	CSV 互转	CSV↔JSON，RFC 4180 引号转义、跨行字段、类型推断；引号风格（minimal/all/nonnumeric/none）、分隔符别名、LF/CRLF 可配
yaml_documents	YAML 多文档	拆分 --- 分隔的多文档，输出文档目录或指定文档（支持负索引）

主要特性

• 格式自动嗅探：多数工具无需显式指定源格式，降低调用门槛
• 保真优先：前导零纯整数按字符串保留（"007" 不会被变成 7）
• 查询省 token：按路径提取字段，避免把整段数据塞进对话
• 往返校验：格式转换有损时显式告警，不静默丢信息
• 安全解析：YAML 不执行自定义标签与对象构造，规避反序列化风险
• 多文档友好：k8s 清单、多环境配置这类一份文件多个文档的场景，可按索引取用，不必手工切分
• 导出可控：CSV 引号风格与换行符可选，quote=none 遇到必须加引号的字段直接报错，不静默产出坏数据

安装

npm install dsh-json-yaml-toolkit

工具

convert_format

参数	类型	说明
to	string	必填，目标格式：json / yaml / toml
doc	string	可选，YAML 多文档选择：整数索引（从 0 起，负数从末尾）或 "all"（默认）
text	string	源内容（与 file 二选一，优先）
file	string	源文件路径（工作目录内）
from	string	可选，源格式；缺省自动嗅探

TOML 对顶层嵌套数组/null 支持有限：转换时做往返校验，有信息损失会输出 ⚠ 警告。

YAML 源含多个文档（--- 分隔）时：默认按数组输出并给出提示；用 doc=N 只取其中一个，doc=-1 取末尾文档。

query_json

点路径查询，源格式自动嗅探（JSON/YAML/TOML）：

• address.city — 取字段
• tags.0 — 数组下标
• users[*].name — 通配展开数组（支持嵌套，如 a[*].b[*] 扁平展开）
• 单值直接返回；多值编号列表；无匹配提示 0 项（查询语义不报错）

validate_schema

参数	类型	说明
data	string	待校验数据（JSON/YAML/TOML 自动嗅探）
schema	string	JSON Schema（JSON 或 YAML 字符串）

校验失败时列出全部错误路径与原因（ajv，allErrors 模式）。

convert_csv

参数	类型	说明
direction	string	必填，to_json（CSV→JSON）或 from_json（JSON→CSV）
input / file	string	源内容或工作目录内文件路径
delimiter	string	单字符、别名（comma/semicolon/tab/pipe）或 auto（默认嗅探 `, ; \t
header	boolean	可选，首行是否为表头（默认 true，仅 to_json）
quote	string	可选，引号风格（仅 from_json）：minimal（默认）/ all / nonnumeric / none
eol	string	可选，换行符（仅 from_json）：lf（默认）/ crlf

quote=none 遇到含分隔符、引号或换行的字段会直接报错，避免产出无法再解析的 CSV。

yaml_documents

参数	类型	说明
text / file	string	YAML 文本或工作目录内文件路径
doc	string	可选，要输出的文档索引（从 0 起，负数从末尾）；不传则返回文档目录
to	string	可选，输出格式：json（默认）/ yaml / toml

只有 --- 没有内容的空文档会被跳过；显式 null 文档保留。

安全与限制

• 文件路径必须在工作目录内
• 输入上限 1MB；输出超 10000 字符自动截断
• 依赖：yaml、smol-toml、ajv（均轻量、同步 API）

测试

npm test

覆盖三种格式互转往返、嗅探、点路径/通配/嵌套通配查询、schema 通过与失败措辞、路径越界拒绝、CSV 引号风格与分隔符别名、YAML 多文档拆分与索引选择等 60 项断言。

版本历史

0.3.0（2026-09-30）

• 新增 yaml_documents 工具：YAML 多文档（--- 分隔）拆分，输出文档目录或按索引取单个文档（支持负索引）
• convert_format 支持多文档 YAML：默认按数组输出，doc=N 指定单个文档（doc=-1 取末尾）
• convert_csv 新增引号风格 quote（minimal/all/nonnumeric/none）与换行符 eol（lf/crlf）
• convert_csv 分隔符支持别名 comma/semicolon/tab/pipe 与 \t 转义写法
• 其他工具（query_json / validate_schema / diff_data）遇到多文档 YAML 时按数组处理，可用 0.field 形式索引
• 测试扩展到 60 项断言

0.2.0（2026-09-13）

• 新增 diff_data 工具：递归比对两份 JSON/YAML/TOML，报告增/删/改路径与新旧值
• 新增 convert_csv 工具：CSV↔JSON 互转（RFC 4180 引号转义、跨行字段、类型推断、前导零保真）

Roadmap（v0.4 候选）

• JSONPath 完整语法（过滤器/递归下降）
• CSV 导入时的列裁剪与重命名
• YAML 多文档的批量筛选输出

源码与发布地址

• 源码：https://github.com/geeklei/dsh-plugins/tree/main/dsh-json-yaml-toolkit
• npm：https://www.npmjs.com/package/dsh-json-yaml-toolkit

典型场景

1. 配置格式互转

用户：把这份 YAML 转成 JSON

convert_format 支持 JSON/YAML 双向转换，保留结构与注释策略明确。

2. 从大 JSON 里取字段

用户：这个响应里 data.items 的第一项是什么

query_json 按路径提取，避免整段 JSON 塞进对话。

3. Schema 校验

用户：这份配置符合 schema 吗

validate_schema 按给定 schema 校验并列出不合法字段。

4. 两份配置比对

用户：这两个环境的配置差在哪

diff_data 递归比对，输出新增/删除/变更路径。

5. CSV 与 JSON 互转

用户：把这个 CSV 转成 JSON 数组

convert_csv 按 RFC4180 处理引号与转义；数字推断时保留前导零（"007" 不会被变成 7）。反过来导出时可指定引号风格：给 Excel/BI 用 quote=all，给程序解析用 minimal。

6. 一份文件多个 YAML 文档

用户：这份 k8s 清单里有几个资源？把 Deployment 那个转成 JSON

yaml_documents 先列出文档目录（索引、类型、规模），再用 doc=N 取指定文档；convert_format 同样支持 doc=-1 取末尾文档。

安全边界

• 只读：仅做解析、转换、比对，不修改源文件。
• 不做隐式类型强转：前导零的纯整数按字符串保留，避免单号/身份证号被破坏。
• YAML 安全解析：不执行 YAML 中的自定义标签与对象构造，规避反序列化风险。
• 规模保护：超大文件解析会受上限保护并显式提示，避免内存耗尽。

其他插件集成说明

协作插件	集成方式
dsh-csv-explorer	先用 csv-explorer 摸清 CSV 结构，再用 convert_csv 做格式转换
dsh-http-client	接口响应 JSON 交给 query_json 提取字段
dsh-base64-codec	JWT payload 解码后是 JSON，可用 query_json 进一步取值
dsh-text-diff	结构化比对用 diff_data（按路径），纯文本比对用 text-diff
dsh-table-render	提取出的数组数据可渲染为对齐表格

FAQ

Q：转换会丢注释吗？ JSON 本身不支持注释；YAML→JSON 时注释无法保留，转换结果会明确提示这一点。

Q：为什么 "007" 没被转成数字？ 这是刻意的保真设计：前导零通常意味着它是编号而非数值，强转会造成不可逆的信息丢失。

Q：能处理超大 JSON 吗？ 受解析上限保护，超大文件建议先用 dsh-fs-inspector 评估规模，或切分后处理。

Q：query_json 支持什么路径语法？ 支持点路径与数组下标（如 data.items[0].name）；复杂 JSONPath 语法（过滤、递归下降）计划在后续版本支持。

Q：多文档 YAML 里空文档怎么算？ 只有 --- 没有内容的空文档会被跳过、不计入索引；显式写 null 的文档会保留为一个 null 文档。

Q：quote=none 为什么报错？ 不报错就会产出含裸分隔符的坏 CSV，且无法再解析回来。这里选择显式失败，让调用方改用 minimal 或 all。