Use when dsh needs to inspect,…

# dsh norms spec 校验报告

前置说明（重要）

我无法直接访问你的文件系统，docs/norms/ 下的 yaml 文件我看不到，且 "dsh" 与 "dsh-norm-spec" 并非我能确证的公开标准工具，我无法编造其字段规范。以下提供可直接执行的校验方案，你跑完把输出贴回来，我帮你精确定位问题。

一、结构层面的通用校验清单

yaml spec 文件常见缺失字段，按此自查：

• 元信息块：name、version、description 是否齐全
• 字段类型声明：每个字段是否有 type（string/int/enum 等）
• 必填标记：required 字段列表是否完整
• 枚举约束：取值是否在 enum 白名单内
• 引用完整性：$ref / 交叉引用的目标是否存在
• 命名规范：snake_case vs camelCase 是否统一

二、推荐校验步骤

1. 语法校验

```bash

python -c "import yaml,sys; [yaml.safe_load(open(f)) for f in ['docs/norms/a.yaml','docs/norms/b.yaml','docs/norms/c.yaml']]"

```

先排除缩进、重复键、tab 字符等基础错误。

2. Schema 校验（若 dsh 提供 JSON Schema）

```bash

dsh norms validate docs/norms/ # 或对应子命令，用 dsh --help 确认

```

备选：yamllint + 自定义规则，或用 jsonschema 库套用 spec 定义。

3. diff 对照：与仓库中已通过校验的旧 norms 文件 git diff，快速定位最近改动引入的字段差异。

三、诊断报错的常见根因（按概率排序）

• 字段缺失：新增 required 字段未同步到旧文件
• 类型不匹配：yaml 自动把 1.0 解析为 float、yes 解析为 bool
• schema 版本漂移：spec 升级后文件头部 spec_version 未更新
• 编码/换行符：CRLF 或 BOM 导致解析器报错

四、下一步

请提供：① dsh --help 或 dsh norms --help 输出；② 校验命令的报错信息；③ 任一 yaml 文件内容。有这些我即可给出逐字段的修复方案。