core package

Submodules

core.base_sentence_generator module

句子生成器基类模块 定义所有生成器的统一接口和通用方法

class core.base_sentence_generator.BaseSentenceGenerator(translator: ParamTranslator, engine_config: EngineConfig)

基类：ABC

句子生成器基类 - 管道模式

can_process(data: Dict[str, Any]) → bool

判断是否可以处理给定的数据

参数:

data -- 参数字典

返回:

是否可以处理

返回类型:

bool

abstract property category: str

返回生成器处理的句子类型

返回:

类型名称

返回类型:

str

do_translate(row_data: dict) → dict

翻译行数据中的参数

参数:

row_data -- 原始行数据

返回:

翻译后的行数据

返回类型:

dict

exists_param(name: str, data: Dict[str, Any]) → bool

检查参数是否存在

参数:

• name -- 参数名

• data -- 数据字典

返回:

参数是否存在

返回类型:

bool

get_format_in_config(name: str) → str | None

获取参数配置中的格式字符串

参数:

name -- 参数名

返回:

格式字符串

返回类型:

Optional[str]

get_int(num: str) → Any

将字符串转换为整数

参数:

num -- 数字字符串

返回:

转换后的整数，如果转换失败则返回原值

返回类型:

int 或原值

get_sentence(name: str, data: Dict[str, Any], use_default: bool = False) → str

根据格式字符串生成句子

参数:

• name -- 参数名

• data -- 数据字典

• use_default -- 是否使用配置中的默认值

返回:

格式化后的句子

返回类型:

str

get_value(name: str, data: Dict[str, Any], use_default: bool = False) → str

从数据中获取参数值

参数:

• name -- 参数名

• data -- 数据字典

• use_default -- 是否使用配置中的默认值

返回:

参数值

返回类型:

str

param_config: Dict[str, Dict] = {}

property priority: int

生成器执行优先级

返回:

优先级数字，越小越先执行

返回类型:

int

abstractmethod process(data: Dict[str, Any]) → List[str] | None

处理参数并生成命令（管道模式）

参数:

data -- 参数字典

返回:

生成的命令列表，如果无法处理则返回 None

返回类型:

Optional[List[str]]

core.config_manager module

配置管理模块 提供类型安全的配置管理功能

class core.config_manager.AppConfig(paths: ~core.config_manager.PathConfig = <factory>, processing: ~core.config_manager.ProcessingConfig = <factory>, engine: ~core.config_manager.EngineConfig = <factory>)

基类：object

应用总配置

classmethod create_default(engine_type: str = 'naninovel') → AppConfig

创建默认配置

参数:

engine_type -- 引擎类型

返回:

默认配置对象

返回类型:

AppConfig

engine: EngineConfig

classmethod from_dict(data: Dict[str, Any]) → AppConfig

从字典创建配置

参数:

data -- 配置字典

返回:

配置对象

返回类型:

AppConfig

classmethod from_file(config_path: Path) → AppConfig

从配置文件加载

参数:

config_path -- 配置文件路径

返回:

配置对象

返回类型:

AppConfig

抛出:

ValueError -- 不支持的配置文件格式

paths: PathConfig

processing: ProcessingConfig

to_file(config_path: Path)

保存到配置文件

参数:

config_path -- 配置文件路径

class core.config_manager.EngineConfig(engine_type: str, file_extension: str, indent_size: int = 0)

基类：object

引擎配置基类

engine_type: str

file_extension: str

get_output_filename(sheet_name: str) → str

生成输出文件名

参数:

sheet_name -- 工作表名称

返回:

输出文件名

返回类型:

str

indent_size: int = 0

class core.config_manager.NaninovelConfig(engine_type: str = 'naninovel', file_extension: str = '.nani', indent_size: int = 0, command_prefix: str = '@')

基类：EngineConfig

Naninovel 引擎配置

command_prefix: str = '@'

engine_type: str = 'naninovel'

file_extension: str = '.nani'

class core.config_manager.PathConfig(input_dir: Path = WindowsPath('input'), output_dir: Path = WindowsPath('output'), param_config_dir: Path = WindowsPath('param_config'), log_dir: Path = WindowsPath('logs'))

基类：object

路径配置

ensure_dirs_exist()

确保所有目录存在

input_dir: Path = WindowsPath('input')

log_dir: Path = WindowsPath('logs')

output_dir: Path = WindowsPath('output')

param_config_dir: Path = WindowsPath('param_config')

class core.config_manager.ProcessingConfig(ignore_mode: bool = True, ignore_words: ~typing.List[str] = <factory>, batch_size: int = 100, enable_progress_bar: bool = True)

基类：object

处理配置

batch_size: int = 100

enable_progress_bar: bool = True

ignore_mode: bool = True

ignore_words: List[str]

class core.config_manager.RenpyConfig(engine_type: str = 'renpy', file_extension: str = '.rpy', indent_size: int = 4, label_indent: bool = False, default_transition: str = 'dissolve')

基类：EngineConfig

Ren'Py 引擎配置

default_transition: str = 'dissolve'

engine_type: str = 'renpy'

file_extension: str = '.rpy'

indent_size: int = 4

label_indent: bool = False

core.constants module

常量定义模块 集中管理项目中使用的所有常量

class core.constants.ColumnName(value)

基类：str, Enum

Excel 列名

BACKGROUND = 'Background'

CHARACTER = 'Character'

IGNORE = 'Ignore'

NOTE = 'Note'

SPEAKER = 'Speaker'

TEXT = 'Text'

class core.constants.FileType(value)

基类：str, Enum

文件类型

BACKGROUND = 'Background'

CHARACTER = 'Character'

EVENT = 'Event'

MUSIC = 'Music'

SOUND = 'Sound'

VOICE = 'Voice'

class core.constants.Marker(value)

基类：str, Enum

标记符号

END = 'END'

class core.constants.SheetName(value)

基类：str, Enum

特殊工作表名称

PARAM_SHEET = '参数表'

class core.constants.SpecialSpeaker(value)

基类：str, Enum

特殊说话者（用于直接输入引擎命令）

LABEL_CAMMAND = 'label'

NANINOVEL_COMMAND = 'naninovel'

RENPY_COMMAND = 'renpy'

class core.constants.WindowMode(value)

基类：str, Enum

对话框模式

HIDE = '隐藏'

SHOW = '显示'

SHOW_AND_HIDE = '显示和隐藏'

core.engine_processor module

引擎处理器模块 基于管道模式的协调器，负责协调数据在生成器管道中的流动

class core.engine_processor.EngineProcessor(engine_type: str, translator: ParamTranslator, engine_config: EngineConfig)

基类：object

引擎处理器 - 基于管道模式的协调器

职责： 1. 管理生成器管道（固定顺序） 2. 协调数据在管道中的流动 3. 处理异常和日志

get_generator_manager() → SentenceGeneratorManager

获取生成器管理器实例

get_pipeline_info() → Dict[str, Any]

获取管道信息，用于调试

process_row(row_data: Series) → List[str]

处理单行数据 - 管道模式

参数:

row_data -- pandas Series，一行的所有数据

返回:

生成的命令列表

返回类型:

List[str]

setup()

设置处理器，初始化生成器和参数提取器

core.engine_registry module

引擎注册表模块 实现引擎的动态注册和管理

class core.engine_registry.EngineMetadata(name: str, display_name: str, file_extension: str, config_class: Type[EngineConfig], processor_factory: Callable, validator_factory: Callable | None = None, description: str = '')

基类：object

引擎元数据

config_class: Type[EngineConfig]

description: str = ''

display_name: str

file_extension: str

name: str

processor_factory: Callable

validator_factory: Callable | None = None

class core.engine_registry.EngineRegistry

基类：object

引擎注册表（单例模式）

classmethod get(engine_name: str) → EngineMetadata

获取引擎元数据

参数:

engine_name -- 引擎名称

返回:

引擎元数据

返回类型:

EngineMetadata

抛出:

EngineNotRegisteredError -- 引擎未注册

classmethod is_registered(engine_name: str) → bool

检查引擎是否已注册

参数:

engine_name -- 引擎名称

返回:

是否已注册

返回类型:

bool

classmethod list_engines() → Dict[str, EngineMetadata]

列出所有已注册引擎

返回:

引擎字典

返回类型:

Dict[str, EngineMetadata]

classmethod register(metadata: EngineMetadata)

注册引擎

参数:

metadata -- 引擎元数据

classmethod reset()

重置注册表（主要用于测试）

core.engine_registry.register_engine(name: str, display_name: str, file_extension: str, config_class: Type[EngineConfig], validator_factory: Callable | None = None, description: str = '')

引擎注册装饰器

参数:

• name -- 引擎名称

• display_name -- 显示名称

• file_extension -- 文件扩展名

• config_class -- 配置类

• validator_factory -- 验证器工厂函数

• description -- 描述

返回:

装饰器函数

core.exceptions module

自定义异常类模块 定义项目中使用的所有异常类型

exception core.exceptions.ConfigError

基类：ScenarioToolError

配置相关错误

exception core.exceptions.EngineError

基类：ScenarioToolError

引擎相关错误

exception core.exceptions.EngineNotRegisteredError

基类：EngineError

引擎未注册错误

exception core.exceptions.ExcelParseError

基类：ScenarioToolError

Excel 解析错误

exception core.exceptions.FileValidationError

基类：ScenarioToolError

文件验证错误

exception core.exceptions.GeneratorError

基类：ScenarioToolError

生成器错误

exception core.exceptions.InvalidParameterError

基类：ScenarioToolError

无效参数错误

exception core.exceptions.ScenarioToolError

基类：Exception

基础异常类

exception core.exceptions.TranslationError

基类：ScenarioToolError

参数翻译错误

core.logger module

日志管理模块 提供统一的日志记录功能

class core.logger.ColoredFormatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)

基类：Formatter

彩色日志格式化器

BOLD = '\x1b[1m'

COLORS = {'CRITICAL': '\x1b[35m', 'DEBUG': '\x1b[36m', 'ERROR': '\x1b[31m', 'INFO': '\x1b[32m', 'WARNING': '\x1b[33m'}

RESET = '\x1b[0m'

format(record)

Format the specified record as text.

The record's attribute dictionary is used as the operand to a string formatting operation which yields the returned string. Before formatting the dictionary, a couple of preparatory steps are carried out. The message attribute of the record is computed using LogRecord.getMessage(). If the formatting string uses the time (as determined by a call to usesTime(), formatTime() is called to format the event time. If there is exception information, it is formatted using formatException() and appended to the message.

class core.logger.ScenarioToolLogger

基类：object

统一的日志管理器（单例模式）

classmethod get_logger(name: str = 'scenario_tool') → Logger

获取日志实例（单例模式）

参数:

name -- 日志器名称

返回:

日志器实例

返回类型:

logging.Logger

classmethod reset()

重置日志器（主要用于测试）

core.logger.get_logger(name: str = 'scenario_tool') → Logger

获取日志器的便捷函数

core.param_translator module

参数翻译器模块 负责将用户友好的参数名称翻译为引擎特定的语法

class core.param_translator.LayerTranslator(module_file: str = 'param_config/param_mappings.py', varient_module_file: str = 'param_config/varient_mappings.py')

基类：ParamTranslator

Layer参数翻译器

get_layer_params() → list

获取所有Layer原始参数

get_layer_translations() → list

获取所有Layer翻译后参数

translate_layer(param: str) → str

翻译Layer参数

class core.param_translator.ParamTranslator(module_file: str = 'param_config/param_mappings.py', varient_module_file: str = 'param_config/varient_mappings.py')

基类：object

参数翻译器类，用于加载参数映射并提供翻译功能

get_available_types() → list

获取可用的参数类型列表

返回:

参数类型列表

返回类型:

list

get_params_for_type(param_type: str) → list

获取指定参数类型的所有原始参数

参数:

param_type -- 参数类型

返回:

原始参数列表，如果类型不存在则返回空列表

返回类型:

list

get_translations_for_type(param_type: str) → list

获取指定参数类型的所有翻译后参数

参数:

param_type -- 参数类型

返回:

翻译后参数列表，如果类型不存在则返回空列表

返回类型:

list

has_mapping(param_type: str, param: str) → bool

检查是否存在指定参数的映射

参数:

• param_type -- 参数类型

• param -- 参数值

返回:

是否存在映射

返回类型:

bool

translate(param_type: str, param: str) → str

翻译单个参数

参数:

• param_type -- 参数类型（如"Layer", "Transform", "Transition"）

• param -- 要翻译的参数值

返回:

翻译后的参数值，如果找不到映射则返回原值

返回类型:

str

translate_batch(param_type: str, params: list) → list

批量翻译参数

参数:

• param_type -- 参数类型

• params -- 要翻译的参数列表

返回:

翻译后的参数列表

返回类型:

list

translate_varient(param: str, role: str | None = None) → str

翻译差分参数

参数:

• param -- 要翻译的差分参数值

• role -- 角色名

返回:

翻译后的参数值

返回类型:

str

class core.param_translator.TransformTranslator(module_file: str = 'param_config/param_mappings.py', varient_module_file: str = 'param_config/varient_mappings.py')

基类：ParamTranslator

Transform参数翻译器

get_transform_params() → list

获取所有Transform原始参数

get_transform_translations() → list

获取所有Transform翻译后参数

translate_transform(param: str) → str

翻译Transform参数

class core.param_translator.TransitionTranslator(module_file: str = 'param_config/param_mappings.py', varient_module_file: str = 'param_config/varient_mappings.py')

基类：ParamTranslator

Transition参数翻译器

get_transition_params() → list

获取所有Transition原始参数

get_transition_translations() → list

获取所有Transition翻译后参数

translate_transition(param: str) → str

翻译Transition参数

core.sentence_generator_manager module

句子生成器管理器模块 负责发现、加载和管理引擎特定的生成器

class core.sentence_generator_manager.SentenceGeneratorManager(engine_type: str)

基类：object

句子生成器管理器

create_generator_instances(translator: ParamTranslator, engine_config: EngineConfig) → List[BaseSentenceGenerator]

创建生成器实例

get_all_param_names() → List[str]

获取所有参数名称

get_validate_params() → Dict[str, list[str]]

收集所有参数配置中的translate_type值和validate_type值

返回:

去重后的数据验证参数列表词典

返回类型:

Dict[str, list[str]]

load()

加载所有生成器类和参数配置

Module contents

Core module 核心模块，提供基础设施和框架功能

class core.AppConfig(paths: ~core.config_manager.PathConfig = <factory>, processing: ~core.config_manager.ProcessingConfig = <factory>, engine: ~core.config_manager.EngineConfig = <factory>)

基类：object

应用总配置

classmethod create_default(engine_type: str = 'naninovel') → AppConfig

创建默认配置

参数:

engine_type -- 引擎类型

返回:

默认配置对象

返回类型:

AppConfig

engine: EngineConfig

classmethod from_dict(data: Dict[str, Any]) → AppConfig

从字典创建配置

参数:

data -- 配置字典

返回:

配置对象

返回类型:

AppConfig

classmethod from_file(config_path: Path) → AppConfig

从配置文件加载

参数:

config_path -- 配置文件路径

返回:

配置对象

返回类型:

AppConfig

抛出:

ValueError -- 不支持的配置文件格式

paths: PathConfig

processing: ProcessingConfig

to_file(config_path: Path)

保存到配置文件

参数:

config_path -- 配置文件路径

class core.BaseSentenceGenerator(translator: ParamTranslator, engine_config: EngineConfig)

基类：ABC

句子生成器基类 - 管道模式

can_process(data: Dict[str, Any]) → bool

判断是否可以处理给定的数据

参数:

data -- 参数字典

返回:

是否可以处理

返回类型:

bool

abstract property category: str

返回生成器处理的句子类型

返回:

类型名称

返回类型:

str

do_translate(row_data: dict) → dict

翻译行数据中的参数

参数:

row_data -- 原始行数据

返回:

翻译后的行数据

返回类型:

dict

exists_param(name: str, data: Dict[str, Any]) → bool

检查参数是否存在

参数:

• name -- 参数名

• data -- 数据字典

返回:

参数是否存在

返回类型:

bool

get_format_in_config(name: str) → str | None

获取参数配置中的格式字符串

参数:

name -- 参数名

返回:

格式字符串

返回类型:

Optional[str]

get_int(num: str) → Any

将字符串转换为整数

参数:

num -- 数字字符串

返回:

转换后的整数，如果转换失败则返回原值

返回类型:

int 或原值

get_sentence(name: str, data: Dict[str, Any], use_default: bool = False) → str

根据格式字符串生成句子

参数:

• name -- 参数名

• data -- 数据字典

• use_default -- 是否使用配置中的默认值

返回:

格式化后的句子

返回类型:

str

get_value(name: str, data: Dict[str, Any], use_default: bool = False) → str

从数据中获取参数值

参数:

• name -- 参数名

• data -- 数据字典

• use_default -- 是否使用配置中的默认值

返回:

参数值

返回类型:

str

param_config: Dict[str, Dict] = {}

property priority: int

生成器执行优先级

返回:

优先级数字，越小越先执行

返回类型:

int

abstractmethod process(data: Dict[str, Any]) → List[str] | None

处理参数并生成命令（管道模式）

参数:

data -- 参数字典

返回:

生成的命令列表，如果无法处理则返回 None

返回类型:

Optional[List[str]]

exception core.ConfigError

基类：ScenarioToolError

配置相关错误

class core.EngineConfig(engine_type: str, file_extension: str, indent_size: int = 0)

基类：object

引擎配置基类

engine_type: str

file_extension: str

get_output_filename(sheet_name: str) → str

生成输出文件名

参数:

sheet_name -- 工作表名称

返回:

输出文件名

返回类型:

str

indent_size: int = 0

exception core.EngineError

基类：ScenarioToolError

引擎相关错误

exception core.EngineNotRegisteredError

基类：EngineError

引擎未注册错误

class core.EngineProcessor(engine_type: str, translator: ParamTranslator, engine_config: EngineConfig)

基类：object

引擎处理器 - 基于管道模式的协调器

职责： 1. 管理生成器管道（固定顺序） 2. 协调数据在管道中的流动 3. 处理异常和日志

get_generator_manager() → SentenceGeneratorManager

获取生成器管理器实例

get_pipeline_info() → Dict[str, Any]

获取管道信息，用于调试

process_row(row_data: Series) → List[str]

处理单行数据 - 管道模式

参数:

row_data -- pandas Series，一行的所有数据

返回:

生成的命令列表

返回类型:

List[str]

setup()

设置处理器，初始化生成器和参数提取器

class core.EngineRegistry

基类：object

引擎注册表（单例模式）

classmethod get(engine_name: str) → EngineMetadata

获取引擎元数据

参数:

engine_name -- 引擎名称

返回:

引擎元数据

返回类型:

EngineMetadata

抛出:

EngineNotRegisteredError -- 引擎未注册

classmethod is_registered(engine_name: str) → bool

检查引擎是否已注册

参数:

engine_name -- 引擎名称

返回:

是否已注册

返回类型:

bool

classmethod list_engines() → Dict[str, EngineMetadata]

列出所有已注册引擎

返回:

引擎字典

返回类型:

Dict[str, EngineMetadata]

classmethod register(metadata: EngineMetadata)

注册引擎

参数:

metadata -- 引擎元数据

classmethod reset()

重置注册表（主要用于测试）

exception core.ExcelParseError

基类：ScenarioToolError

Excel 解析错误

exception core.FileValidationError

基类：ScenarioToolError

文件验证错误

exception core.GeneratorError

基类：ScenarioToolError

生成器错误

exception core.InvalidParameterError

基类：ScenarioToolError

无效参数错误

class core.NaninovelConfig(engine_type: str = 'naninovel', file_extension: str = '.nani', indent_size: int = 0, command_prefix: str = '@')

基类：EngineConfig

Naninovel 引擎配置

command_prefix: str = '@'

engine_type: str = 'naninovel'

file_extension: str = '.nani'

class core.ParamTranslator(module_file: str = 'param_config/param_mappings.py', varient_module_file: str = 'param_config/varient_mappings.py')

基类：object

参数翻译器类，用于加载参数映射并提供翻译功能

get_available_types() → list

获取可用的参数类型列表

返回:

参数类型列表

返回类型:

list

get_params_for_type(param_type: str) → list

获取指定参数类型的所有原始参数

参数:

param_type -- 参数类型

返回:

原始参数列表，如果类型不存在则返回空列表

返回类型:

list

get_translations_for_type(param_type: str) → list

获取指定参数类型的所有翻译后参数

参数:

param_type -- 参数类型

返回:

翻译后参数列表，如果类型不存在则返回空列表

返回类型:

list

has_mapping(param_type: str, param: str) → bool

检查是否存在指定参数的映射

参数:

• param_type -- 参数类型

• param -- 参数值

返回:

是否存在映射

返回类型:

bool

translate(param_type: str, param: str) → str

翻译单个参数

参数:

• param_type -- 参数类型（如"Layer", "Transform", "Transition"）

• param -- 要翻译的参数值

返回:

翻译后的参数值，如果找不到映射则返回原值

返回类型:

str

translate_batch(param_type: str, params: list) → list

批量翻译参数

参数:

• param_type -- 参数类型

• params -- 要翻译的参数列表

返回:

翻译后的参数列表

返回类型:

list

translate_varient(param: str, role: str | None = None) → str

翻译差分参数

参数:

• param -- 要翻译的差分参数值

• role -- 角色名

返回:

翻译后的参数值

返回类型:

str

class core.PathConfig(input_dir: Path = WindowsPath('input'), output_dir: Path = WindowsPath('output'), param_config_dir: Path = WindowsPath('param_config'), log_dir: Path = WindowsPath('logs'))

基类：object

路径配置

ensure_dirs_exist()

确保所有目录存在

input_dir: Path = WindowsPath('input')

log_dir: Path = WindowsPath('logs')

output_dir: Path = WindowsPath('output')

param_config_dir: Path = WindowsPath('param_config')

class core.ProcessingConfig(ignore_mode: bool = True, ignore_words: ~typing.List[str] = <factory>, batch_size: int = 100, enable_progress_bar: bool = True)

基类：object

处理配置

batch_size: int = 100

enable_progress_bar: bool = True

ignore_mode: bool = True

ignore_words: List[str]

class core.RenpyConfig(engine_type: str = 'renpy', file_extension: str = '.rpy', indent_size: int = 4, label_indent: bool = False, default_transition: str = 'dissolve')

基类：EngineConfig

Ren'Py 引擎配置

default_transition: str = 'dissolve'

engine_type: str = 'renpy'

file_extension: str = '.rpy'

indent_size: int = 4

label_indent: bool = False

exception core.ScenarioToolError

基类：Exception

基础异常类

class core.ScenarioToolLogger

基类：object

统一的日志管理器（单例模式）

classmethod get_logger(name: str = 'scenario_tool') → Logger

获取日志实例（单例模式）

参数:

name -- 日志器名称

返回:

日志器实例

返回类型:

logging.Logger

classmethod reset()

重置日志器（主要用于测试）

class core.SentenceGeneratorManager(engine_type: str)

基类：object

句子生成器管理器

create_generator_instances(translator: ParamTranslator, engine_config: EngineConfig) → List[BaseSentenceGenerator]

创建生成器实例

get_all_param_names() → List[str]

获取所有参数名称

get_validate_params() → Dict[str, list[str]]

收集所有参数配置中的translate_type值和validate_type值

返回:

去重后的数据验证参数列表词典

返回类型:

Dict[str, list[str]]

load()

加载所有生成器类和参数配置

exception core.TranslationError

基类：ScenarioToolError

参数翻译错误

core.get_logger(name: str = 'scenario_tool') → Logger

获取日志器的便捷函数

core.register_engine(name: str, display_name: str, file_extension: str, config_class: Type[EngineConfig], validator_factory: Callable | None = None, description: str = '')

引擎注册装饰器

参数:

• name -- 引擎名称

• display_name -- 显示名称

• file_extension -- 文件扩展名

• config_class -- 配置类

• validator_factory -- 验证器工厂函数

• description -- 描述

返回:

装饰器函数