ErisPulse.CLI.utils.config_wizard 模块
模块概述
ErisPulse CLI 配置向导共享工具
基于声明式配置(ConfigClass / AccountConfigClass)生成 schema 驱动的
交互式表单,供 epsdk config 命令与 install / init 安装后衔接复用。
模块与适配器共用同一套渲染逻辑;适配器额外包含多账户(bot 账户)配置环节。
提示
- load_config_targets() 发现所有可配置目标(entry-points + 本地 plugins/)
- get_target_status() 检查目标的配置状态(未配置/必填缺失/就绪)
- run_wizard() 对单个目标运行交互式配置向导并写入 config.toml
- post_install_configure() 在安装包后衔接配置引导
函数列表
_normalize_dist_name(name: str | None) -> str
按 PEP 503 规范化 PyPI 发行包名称
大小写不敏感,- / _ / . 连续序列统一为单个 -,
用于安装包名与 entry-point 所属包名的宽松匹配。
- name: 原始包名
返回值: 规范化后的包名
is_interactive() -> bool
检测当前是否处于可交互的终端环境
返回值 (stdin): 与 stdout 均为 TTY 时返回 True
_resolve_adapter_config_key(cls) -> str
在不实例化适配器类的前提下解析其配置键
默认实现(继承自 BaseAdapter)返回类名;子类覆写 _get_config_key
时以伪 self 对象调用(大多数覆写是 self 属性的纯函数),
调用失败则回退类名。
- cls: 适配器类
返回值: 配置键名字符串
_target_from_class(kind: Literal['adapter', 'module'], name: str, cls, package = None, source = 'entrypoint') -> ConfigTarget | None
从目标类构造 ConfigTarget(读取类属性声明,不实例化)
- kind: 目标类型
- name: 目标名
- cls: 适配器/模块类
- package: 所属包名
- source: 来源标识
返回值: ConfigTarget;类不合法时返回 None
_plugin_module_class(module_obj) -> type | None
从本地插件模块对象中提取模块类
- module_obj: 插件模块对象(声明
moduleInfo字典)
返回值: 模块类;未声明或类型不合法时返回 None
load_config_targets() -> list[ConfigTarget]
发现当前环境中所有可配置目标
覆盖 entry-points(erispulse.adapter / erispulse.module 组)
与本地插件目录(plugins/)。加载失败的条目跳过并提示。
返回值 (ConfigTarget): 列表(含未声明配置的目标,调用方按需过滤)
get_target_status(target: ConfigTarget, config = None) -> tuple[str, list[str]]
检查目标的配置状态
- target: ConfigTarget
- config (
ConfigManager): 实例(None 时使用全局单例)
返回值: (状态, 错误列表)。状态取值:
- ok:已配置且校验通过
- incomplete:必填项缺失或校验失败
- unconfigured:配置键不存在(从未生成)
- none:目标未声明任何配置
_sort_fields(schema_fields: dict) -> list[tuple[str, dict]]
按 schema 的 order 元数据稳定排序字段(未声明 order 的保持声明顺序靠前)
- schema_fields: get_config_schema()["fields"] 字典
返回值: (字段名, 字段 schema) 列表
_coerce_scalar(raw: str, type_name: str)
将用户输入字符串转换为目标类型的标量值
- raw: 原始输入
- type_name (
TOML): 类型名(integer/float/boolean/string)
返回值: 转换后的值;无法转换时抛出 ValueError
_plain_options(options: list) -> list
提取 select 选项的纯值列表(兼容字符串与 {label, value} 字典两种格式)
- options (
schema): 中的 options 列表
返回值: 选项值列表
_option_label(option) -> str
获取 select 选项的显示标签
- option: 单个选项(字符串或 {label, value} 字典)
返回值: 标签字符串
_with_source(label: str, source: str) -> str
在 label 行尾追加来源标注(当前值 / 默认值)
- label: 已构造的字段标签行
- source: 来源标注文本(空则不追加)
返回值: 带标注的显示文本
_source_label(has_value: bool, value, bool_text: str = '') -> str
生成字段值来源标注文本(当前值 / 默认值)
- has_value: 字段是否已有当前配置值(存储中存在)
- value: 值(布尔传入 bool_text 已本地化)
- bool_text: 布尔值本地化"是/否"文本
返回值: 标注字符串;无值则返回空串
_prompt_field(name: str, field_schema: dict, current, has_value: bool = False)
交互式询问单个配置字段的值
按 widget / 类型渲染控件(password / select / switch / 数值 / 文本),
输入即时校验(options / min / max / required),非法时重新询问;
空输入表示保留当前值(secret 字段不回显当前值)。
值来源(已有配置 / schema 默认)以 (当前:x) / (默认:x) 标注。
- name: 字段名
- field_schema: 字段 schema(来自 resolve_config_schema)
- current: 当前值(默认值兜底为 schema default)
- has_value: 字段是否已有当前配置值(决定标注"当前"/"默认")
返回值: 用户确认后的字段值
_values_equal(a, b) -> bool
宽松比较两个标量是否相等(容忍 int/str 形式差异)
- a: 值 a
- b: 值 b
返回值: 是否相等
fill_config_fields(config_class, current_values: dict) -> dict
渲染整个配置类的表单并收集用户输入
example 字段不进入向导(默认值不落盘,仅记录在 config.full.example);
嵌套 dataclass 字段(schema 含 fields 子树)递归渲染为子表单。
- config_class (
dataclass): 配置类 - current_values: 当前存储的配置字典(作为各字段初值)
返回值: 收集后的配置字典
_fill_from_schema_fields(fields_dict: dict, values: dict) -> None
内部方法 按 schema 字段树渲染表单并就地收集到 values(嵌套子树递归)
_validate_dataclass(config_class, data: dict) -> list[str]
校验字典是否能通过配置类的完整约束
- config_class (
dataclass): 配置类 - data: 配置字典
返回值: 错误列表(空列表表示通过)
_prompt_account_name(existing: dict, default: str = '') -> str | None
询问新的账户名(非空且不与现有账户重名)
- existing: 现有账户字典
- default: 默认账户名
返回值: 合法账户名;用户中断返回 None
_pick_account_name(names: list[str]) -> str | None
从账户名列表中交互选择一个账户
显示 1. xxx 编号列表,输入序号选择;空输入返回(None),
非法序号重新询问。
- names: 账户名列表
返回值: 选中的账户名;用户留空/中断返回 None
_resolve_accounts_key(target: ConfigTarget, config) -> str
解析适配器多账户配置的存储键
新键为 <config_key>.accounts;旧版使用 <config_key>.bots,
仅当新键不存在而旧键存在时回退(兼容既有 config.toml)。
- target: 适配器 ConfigTarget
- config (
ConfigManager): 实例
返回值: 账户配置存储键
_run_accounts_section(target: ConfigTarget, config) -> dict
运行多账户配置环节(添加 / 编辑 / 删除循环)
- target: 适配器 ConfigTarget
- config (
ConfigManager): 实例
返回值: 编辑后的账户字典 {账户名: 字段字典}
run_wizard(target: ConfigTarget, config = None) -> bool
对单个目标运行交互式配置向导
流程:同步字段 i18n 语言 → 就绪提示 → 全局配置表单 →(适配器) 账户管理环节 →(适配器)启用开关 → 整体校验 → 写入 config.toml (立即落盘),末尾统一打印保存结果;全局表单校验失败且放弃重填 时直接中止(不写入任何配置)。
- target: ConfigTarget
- config (
ConfigManager): 实例(None 时使用全局单例)
返回值: 是否成功写入了配置
post_install_configure(dist_names: list[str] | None, config = None, *, interactive: bool | None = None) -> None
安装完成后衔接配置向导
刷新 entry-points 缓存后,按 PyPI 名称规范化匹配刚安装的包,
仅对包含配置声明的目标逐个询问是否立即配置。非交互环境跳过并
打印 epsdk config <name> 指引。
- dist_names: 本次成功安装的发行包名列表
- config (
ConfigManager): 实例(None 时使用全局单例) - interactive: 是否交互(None 时自动检测 TTY)
类列表
class ConfigTarget
可配置目标(适配器或模块)的元信息
仅承载类级别的声明信息(ConfigClass / AccountConfigClass), 不实例化目标类,避免在 CLI 上下文触发配置模板生成等副作用。
方法列表
__init__(kind: Literal['adapter', 'module'], name: str, *, config_class = None, account_class = None, config_key: str = '', package: str | None = None, source: str = 'entrypoint')
- kind: 目标类型:"adapter" | "module"
- name: 目标名(适配器为平台名,模块为注册名)
- config_class (
ConfigClass): 声明(未声明为 None) - account_class (
AccountConfigClass): 声明(仅适配器,未声明为 None) - config_key: 配置存储键(适配器默认类名,模块为注册名)
- package: 所属 PyPI 包名(本地插件为 None)
- source: 来源:"entrypoint" | "plugins"
configurable -> bool(property)
是否包含任何配置声明
kind_label -> str(property)
目标类型显示名(适配器/模块)