dsh-xml-toolkit

v0.1.0

Published

18 days ago

Lightweight XML toolkit for DeepSeek Harness: parse XML into readable JSON or a raw tree, query nodes with a simplified path syntax, and pretty-print or minify XML while keeping comments and CDATA. Zero runtime dependencies, read-only.

0High
0Medium
0Low

geeklei

dsh plugin xml parser query format pretty-print minify

dsh-xml-toolkit

DeepSeek Harness 的 XML 工具箱：parse_xml 把 XML 解析为易读 JSON 或原始节点树，query_xml 用简化路径精准取出节点与属性，format_xml 做缩进美化或压成一行。支持注释、CDATA、DOCTYPE 与处理指令，属性自动映射为 @name。只读、零运行时依赖。

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

功能说明

XML 常在配置、接口报文与文档格式里出现，但它在对话里很难直接看：嵌套一层套一层，属性混在标签里，注释和 CDATA 又常常是关键信息。本插件把它拆成三个动作——看结构、取字段、整格式。

parse_xml —— 看清整体结构

给出元素数、最大深度、属性数与树形内容。shape=json 把属性映射为 @name、纯文本映射为 #text、同名子元素自动合并为数组，读起来和 JSON 一样自然：

来源：config.xml
根元素：config
元素数：8，最大深度：3，属性数：7

{
  "@env": "prod",
  "server": [
    {
      "@host": "10.0.0.1",
      "@port": "8080",
      "name": "api-gateway",
      "timeout": {
        "@unit": "ms",
        "#text": "3000"
      }
    },
    {
      "@host": "10.0.0.2",
      "@port": "9090",
      "name": "worker",
      "timeout": {
        "@unit": "ms",
        "#text": "15000"
      }
    }
  ],
  "remark": "仅内网访问 & 需白名单"
}

shape=tree 则保留节点原始形态（name / attrs / text / children），适合需要看到节点身份而不只是值的场景：

{
  "name": "a",
  "attrs": { "id": "1" },
  "text": "tx",
  "children": [
    { "name": "b", "attrs": {} }
  ]
}

query_xml —— 从大文件里精准取一个字段

路径语法尽量贴近日常习惯：a/b/c 逐级下钻、name[0] 取第 n 个同名元素、@attr 取属性、* 通配任意子元素、//name 任意深度搜索。属性也可以用点号写法 a.b 代替 a/b：

来源：config.xml
表达式：config/server[1]/timeout/@unit
匹配：1 个节点

[1] @unit = "ms"

来源：config.xml
表达式：//name
匹配：2 个节点

[1] <name>
"api-gateway"

[2] <name>
"worker"

format_xml —— 美化或压缩

pretty 按层级缩进、纯文本元素压成单行、注释与 CDATA 原样保留；minify 去掉元素间空白压成一行。属性统一为双引号，实体自动转义且不会二次转义（原文里已是 & 的不会变成 &amp;）：

模式：pretty（缩进 2 空格）
字符数：25 → 32

<a x="1">
  <b>t</b>
  <c/>
</a>

模式：minify
字符数：358 → 320

<?xml version="1.0" encoding="UTF-8"?><!-- 服务配置 --><config env="prod"><server ...

注意：format_xml 只返回格式化后的文本，不写回文件。

安装

npm install dsh-xml-toolkit

安装后在 cordis.patch.yml 中加入：

- insert:
    - id: xml-toolkit
      name: "dsh-xml-toolkit"

使用说明

三个工具都支持 path（文件路径）或 text（内联文本）二选一，text 优先。

parse_xml

| 参数 | 类型 | 说明 | |---|---|---| | path | string | XML 文件路径 | | text | string | 内联 XML 文本（优先于 path） | | shape | string | json（默认，易读）| tree（保留节点结构） | | max_nodes | number | 元素数上限，默认 200000，上限 2000000 | | max_depth | number | 嵌套深度上限，默认 100，上限 500 | | max_chars | number | 输出字符上限，默认 20000，上限 200000 | | max_size | number | 文件大小上限（KB），默认 10240，上限 51200 |

用户：看一下这个 pom.xml 的整体结构

parse_xml(path="pom.xml")

用户：我要直接处理节点层级，不要合并成 JSON

parse_xml(path="layout.xml", shape="tree")

query_xml

| 参数 | 类型 | 说明 | |---|---|---| | path / text | string | 同上 | | expr | string | 查询表达式（必填），如 catalog/book[0]/title、//price、book/@id | | limit | number | 最多返回匹配数，默认 20，上限 200 | | max_chars | number | 输出字符上限，默认 20000，上限 200000 | | max_size | number | 文件大小上限（KB），默认 10240，上限 51200 |

用户：第二个 server 的超时单位是什么

query_xml(path="config.xml", expr="config/server[1]/timeout/@unit")

用户：把所有 name 都列出来

query_xml(path="config.xml", expr="//name")

用户：取第一个 book 的 id 属性

query_xml(path="catalog.xml", expr="catalog/book[0]/@id")

format_xml

| 参数 | 类型 | 说明 | |---|---|---| | path / text | string | 同上 | | mode | string | pretty（默认，缩进美化）| minify（压缩成一行） | | indent | number | 缩进空格数，默认 2，上限 8 | | max_chars | number | 输出字符上限，默认 20000，上限 200000 | | max_size | number | 文件大小上限（KB），默认 10240，上限 51200 |

用户：把这段 XML 排好版给我看

format_xml(text="<a x=\"1\"><b>t</b><c/></a>", mode="pretty")

用户：要贴到一行里，去掉所有缩进

format_xml(path="config.xml", mode="minify")

典型场景

配置排查：parse_xml 一眼看层级与关键属性，不用在几十行尖括号里找。
从大报文里取字段：query_xml 用路径直接定位，避免整份打印。
格式统一：format_xml(mode="pretty") 处理手工编辑后缩进混乱的 XML。
报文瘦身：format_xml(mode="minify") 压掉无用空白，用于传输前预览。
属性批量核查：//name、* 通配等方式快速枚举同名节点。
结构比对：shape=tree 输出稳定，便于两次解析结果逐节点对比。
CDATA 内容确认：CDATA 会作为文本保留并正确解码，可用于核对脚本片段等内容。

安全边界

只读：三个工具都不写入、不修改、不删除文件；format_xml 只返回文本，不回写源文件。测试含只读性断言。
不访问网络：全部解析在本地完成，无任何外部请求。
不执行输入：只做词法扫描与树构建，不 eval、不加载模块、不解释 XML 中的任何内容（含 DOCTYPE 内部子集仅做跳过处理，不解析实体定义）。
不解析外部实体：不加载 DTD 外部文件，不展开自定义实体定义，避免 XXE 风险。
二进制拒绝：读取时检测 NUL 字节，疑似二进制文件直接拒绝解析并报错。
多层上限：文件大小 max_size 上限 51200 KB、元素数 max_nodes 上限 2000000、深度 max_depth 上限 500、输出 max_chars 上限 200000；query_xml 匹配数上限 200。超限即拒绝或截断并显式提示。
结构错误快速失败：标签未闭合、属性未加引号等结构错误直接报错并指明位置，不产出半成品结果。
不收集敏感值：解析结果原样输出，不做脱敏。若 XML 中含密钥等敏感信息，请改用 dsh-credential-scan 先做泄露检查。

其他插件集成说明

| 协作插件 | 集成方式 | |---|---| | dsh-json-yaml-toolkit | parse_xml(shape="json") 的结果交给 json-yaml-toolkit 做格式转换或校验 | | dsh-file-search | 先用 file-search 定位含关键属性的 XML 文件，再用 query_xml 精确取值 | | dsh-credential-scan | 解析前先扫描 XML 中是否混入凭据、密钥 | | dsh-text-diff | 用 format_xml 统一格式后再做 diff，避免缩进差异干扰结果 | | dsh-text-stats | 对 XML 原文做体量与标签词频统计，与结构化解析互补 | | dsh-table-render | 把 query_xml 的匹配列表交给 table-render 渲染成对齐表格 | | dsh-fs-inspector | 解析前查看文件体量，据此设置合适的 max_size / max_nodes | | dsh-regex-lab | XML 中非常规文本（如日志片段）可交给 regex-lab 做正则提取 |

版本说明

0.1.0（2026-09-29）：初始版本。
- parse_xml：JSON / tree 双形态输出，元素数、最大深度、属性数统计，支持注释、CDATA、DOCTYPE、处理指令
- query_xml：简化路径查询（逐级下钻、下标、属性、通配、任意深度搜索），返回节点结构与匹配位置
- format_xml：pretty / minify 双向格式化，保留注释与 CDATA，属性统一双引号，实体不二次转义
- 二进制拒绝、文件大小 / 元素数 / 深度 / 字符数多层上限、结构错误快速失败

RoadMap

v0.2（计划）

validate_xml：按 XSD 子集校验结构，输出不符合的节点路径
convert_xml：XML ⇄ JSON ⇄ YAML ⇄ CSV 双向转换
diff_xml：按结构而非文本比对两份 XML，输出新增 / 删除 / 变更节点
query_xml 支持属性选择条件（如 server[@port="8080"]）与谓词过滤

v0.3（展望）

流式解析：按块读取超大 XML，突破整体载入内存的限制
命名空间感知：ns:tag 前缀匹配与命名空间归一化
支持 XPath 常用子集（[]、//、text()、last()）
压缩文件直读（.xml.gz），内部解压后解析

FAQ

Q：解析时提示「XML 结构错误」怎么办？ 先看报错中的位置信息。最常见的原因是标签未闭合、属性值没加引号、或 < & 没转义。用 format_xml 无法修复结构错误，需要先修正源文件。

Q：为什么文本里的 & 没有被转成 &？ 在 parse_xml 中是会被解码的（输出 &）；在 format_xml 输出源文本时会保留原实体，避免二次转义。两处行为不同是刻意的。

Q：同名子元素为什么会变成数组？ 这是 JSON 形态的简化处理：同名出现多次时合并为数组，只出现一次时是普通值。用 shape=tree 可以避免这一层映射。

Q：query_xml 的 a/b 和 a.b 有区别吗？ 没有。点号只是斜杠的等价写法，a.b.c 与 a/b/c 完全相同。路径里的下标 [n] 从 0 开始计数。

Q：//name 会不会很慢？ 它会遍历所有后代节点，属于全树扫描。在 max_nodes 上限内（默认 20 万）是毫秒级；超大文件建议先用更具体的路径缩小子树。

Q：CDATA 内容在查询结果里能看到吗？ 能。CDATA 会被视为该节点的文本内容保留，parse_xml 与 query_xml 都会返回，format_xml 也会原样输出。

Q：能处理带命名空间的 XML 吗？ 当前版本把 ns:tag 当作普通标签名匹配，可以原样读出，但暂不支持按命名空间归一化匹配（在 RoadMap 的 v0.3）。

Q：会解析 DTD 或外部实体吗？ 不会。DOCTYPE 仅做跳过处理，不加载外部文件、不展开自定义实体，这是出于安全（XXE）考虑的有意设计。

Q：format_xml 格式化后会写回文件吗？ 不会。它只返回处理后的文本，源文件保持原样。需要落盘请自行保存返回值。

源码与发布地址

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

许可证

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

dsh-xml-toolkit

功能说明

安装

使用说明

parse_xml

query_xml

format_xml

典型场景

安全边界

其他插件集成说明

版本说明

RoadMap

FAQ

源码与发布地址

许可证