ErisPulse ErisPulse
Open in interactive docs →
On this page
Static mirror — the interactive version is canonical Open in interactive docs →

ErisPulse.CLI.hints 模块


模块概述

ErisPulse CLI 友好提示引擎

CLI 完全独立于框架本体(包括 runtime.hints)。本模块提供 CLI 专用的 模糊匹配 / 拼写建议能力,避免 CLI 反向依赖框架运行时。

提示

  1. best_match_with_prefix: 用于"未知命令 → 你是不是想用 xxx"场景, 对前缀匹配(如 ins → install)给予加成。
  2. 其余函数与框架 runtime.hints 行为一致,便于跨模块复用思路。

函数列表

suggest_similar(name: str, candidates: Sequence[str], *, max_suggestions: int = 3, cutoff: float = 0.5) -> list[str]

找出与给定名称最相似的候选词

使用 difflib 进行模糊匹配,不区分大小写比较、返回原始大小写。

  • name: 用户输入的(可能有误的)名称
  • candidates: 候选词列表
  • max_suggestions: 最多返回的建议数量
  • cutoff: 相似度阈值 (0.0 ~ 1.0),低于此值的候选会被过滤

返回值: 按相似度从高到低排序的建议列表(保留原始大小写)


best_match(name: str, candidates: Sequence[str], *, cutoff: float = 0.6) -> str | None

返回单个最佳匹配建议

  • name: 用户输入的名称
  • candidates: 候选词列表
  • cutoff: 相似度阈值(默认 0.6,确保只返回高置信度匹配)

返回值: 最佳匹配的候选词,无匹配时返回 None


best_match_with_prefix(name: str, candidates: Sequence[str], *, cutoff: float = 0.5, prefix_bonus: float = 0.85) -> str | None

带前缀加成的模糊匹配

当输入是候选词的前缀时(如 ins -> install),给予更高的相似度分数。 专用于 CLI 子命令拼写纠错场景。

  • name: 用户输入的名称
  • candidates: 候选词列表
  • cutoff: 基础相似度阈值
  • prefix_bonus: 当输入是候选前缀时使用的固定高分(应大于 cutoff)

返回值: 最佳匹配的候选词,无匹配时返回 None


suggest_for_exception(exc: BaseException) -> str | None

为 CLI 命令执行中的异常生成场景化提示

根据 Python 异常类型返回对应的 i18n key,由调用方翻译为最终提示。 仅覆盖 CLI 场景下高频出现的异常类型,与框架 runtime.hints 的职责区分。

  • exc: 捕获的异常实例

返回值: i18n key 字符串,不匹配时返回 None