用途
本技能用于在 mir CLI 执行出错时进行故障排查。当用户在使用 mir 命令过程中遇到错误,或希望查明错误原因时使用。
主要能力:错误一览与处理办法
SnippetNotFoundError
表示找不到 snippet。
- 确认 .mir/snippets/<name>.yaml 与 .mir/snippets/<name>/ 目录是否同时存在;只有其中一方无法正常工作。
- 确认 snippet 名称是否有拼写错误。
- 确认 snippet 名称是否合法:需符合 ^[a-zA-Z0-9][a-zA-Z0-9-]*$,即仅由英数字和连字符组成,且以英数字开头。
RegistryNotFoundError
表示找不到 registry。
- 确认 mirconfig.yaml 中的 registries 配置。
- 确认通过 --registry 指定的名称是否存在。
- 使用 mir list 查看可用的 registry。
FileConflictError
表示安装目标位置已存在同名文件。
- 在交互模式下执行时会显示覆盖确认提示(yes/no/all)。
- 使用 --no-interactive 时会跳过覆盖(与 --safe 相同)。
- 也可以手动将已有文件移走后重新执行。
PathTraversalError
表示模板文件名中包含 ..。
- 检查模板目录内的文件路径是否包含 ..。
- 修正模板的文件路径。
变量未指定(非交互模式)
表示使用 --no-interactive 时未指定必需变量。
- 通过 CLI 参数指定 --变量名=值。
- 或在 snippet.yaml 的变量定义中设置 default。
远程 registry 发布失败
- 401:publish_token 无效。重新获取 token 并更新 mirconfig.yaml。
- 403:权限不足。确认 token 的权限。
- 409:存在同名 snippet。使用 --force 覆盖发布。
YAML 校验错误
- 确认 snippet.yaml 是否符合 schema/v1/snippet.schema.json。
- 确认是否设置了必填字段 name。
- 确认 name 字段是否与文件名一致。
使用方式(处理步骤)
- 确认错误信息。
- 从上述一览中定位对应的错误。
- 按照处理办法进行修正。
- 修正后重新执行命令,确认是否正常。
无法解决时
- 使用 mir --help 或 mir <command> --help 查看命令用法。
- 若仍无法解决,可在 GitHub 提交 issue:https://github.com/TBSten/mir/issues
适用场景
适用于用户在执行 mir 命令时遭遇错误、或需要调查错误原因的场景。
限制
本技能仅针对资料中列出的错误类型提供排查指引;其他错误类型、具体平台与版本要求等暂未提供。