refactor: 重构解析器架构并添加编码检测和配置管理
简化 parse_input() 为纯调度器,通过遍历 readers 的 supports() 方法识别输入类型,移除 URL 特殊处理和文件检查逻辑。各 reader 的 parse() 方法负责完整验证(文件存在、格式有效性)。 新增功能: - 添加 chardet 编码自动检测,支持多种中文编码回退机制 - 创建统一配置类管理编码、下载超时、日志等级等配置项 - HTML reader 支持本地文件编码检测和 URL 统一处理 安全性改进: - 修复 safe_open_zip() 路径遍历漏洞,使用 pathlib 规范化路径 - 添加边界检查,search_markdown() 检查负数参数 其他改进: - 修复类型注解(argparse.Namespace) - 日志系统仅输出 ERROR 级别,避免干扰 Markdown 输出 - 更新 BaseReader 接口文档,明确 supports() 和 parse() 职责划分 - 同步 delta specs 到主 specs(document-reading、html-reader、configuration、encoding-detection)
This commit is contained in:
83
openspec/specs/configuration/spec.md
Normal file
83
openspec/specs/configuration/spec.md
Normal file
@@ -0,0 +1,83 @@
|
||||
## Purpose
|
||||
|
||||
统一配置管理能力,提供集中的配置类管理所有配置项。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 统一配置类
|
||||
系统 SHALL 提供统一的配置类,集中管理所有配置项。
|
||||
|
||||
#### Scenario: 配置类在独立文件
|
||||
- **WHEN** 使用配置项
|
||||
- **THEN** 从 config.py 模块导入 Config 类
|
||||
|
||||
#### Scenario: 配置类为简单常量类
|
||||
- **WHEN** 访问配置项
|
||||
- **THEN** 通过 Config.ITEM_NAME 直接访问类属性
|
||||
|
||||
### Requirement: 编码配置
|
||||
系统 SHALL 在配置类中提供编码相关配置项。
|
||||
|
||||
#### Scenario: 提供回退编码列表
|
||||
- **WHEN** 需要回退编码列表
|
||||
- **THEN** 系统提供 Config.FALLBACK_ENCODINGS 配置项
|
||||
|
||||
#### Scenario: 回退编码列表为列表类型
|
||||
- **WHEN** 访问 Config.FALLBACK_ENCODINGS
|
||||
- **THEN** 返回字符串列表,包含编码名称
|
||||
|
||||
#### Scenario: 回退编码列表默认值
|
||||
- **WHEN** 使用默认配置
|
||||
- **THEN** Config.FALLBACK_ENCODINGS 默认为 ['utf-8', 'gbk', 'gb2312', 'latin-1']
|
||||
|
||||
### Requirement: HTML 下载配置
|
||||
系统 SHALL 在配置类中提供 HTML 下载相关配置项。
|
||||
|
||||
#### Scenario: 提供下载超时配置
|
||||
- **WHEN** 需要下载超时设置
|
||||
- **THEN** 系统提供 Config.DOWNLOAD_TIMEOUT 配置项
|
||||
|
||||
#### Scenario: 下载超时为整数秒数
|
||||
- **WHEN** 访问 Config.DOWNLOAD_TIMEOUT
|
||||
- **THEN** 返回整数,表示超时秒数
|
||||
|
||||
#### Scenario: 下载超时默认值
|
||||
- **WHEN** 使用默认配置
|
||||
- **THEN** Config.DOWNLOAD_TIMEOUT 默认为 30 秒
|
||||
|
||||
#### Scenario: 提供 User-Agent 配置
|
||||
- **WHEN** 需要 HTTP User-Agent
|
||||
- **THEN** 系统提供 Config.USER_AGENT 配置项
|
||||
|
||||
#### Scenario: User-Agent 默认值
|
||||
- **WHEN** 使用默认配置
|
||||
- **THEN** Config.USER_AGENT 默认为 "lyxy-document/0.1.0"
|
||||
|
||||
### Requirement: 日志配置
|
||||
系统 SHALL 在配置类中提供日志相关配置项。
|
||||
|
||||
#### Scenario: 提供日志等级配置
|
||||
- **WHEN** 需要日志等级设置
|
||||
- **THEN** 系统提供 Config.LOG_LEVEL 配置项
|
||||
|
||||
#### Scenario: 日志等级为字符串
|
||||
- **WHEN** 访问 Config.LOG_LEVEL
|
||||
- **THEN** 返回字符串,表示日志等级名称
|
||||
|
||||
#### Scenario: 日志等级默认值
|
||||
- **WHEN** 使用默认配置
|
||||
- **THEN** Config.LOG_LEVEL 默认为 "ERROR"
|
||||
|
||||
### Requirement: 配置项类型安全
|
||||
系统 SHALL 确保配置项具有明确的类型,便于 IDE 提供自动补全。
|
||||
|
||||
#### Scenario: 配置项有类型注解
|
||||
- **WHEN** 在 IDE 中访问配置项
|
||||
- **THEN** IDE 提供准确的类型提示和自动补全
|
||||
|
||||
### Requirement: 配置项文档
|
||||
系统 SHALL 为每个配置项提供清晰的注释说明。
|
||||
|
||||
#### Scenario: 配置项有注释
|
||||
- **WHEN** 查看配置类源码
|
||||
- **THEN** 每个配置项都有注释说明其用途和默认值
|
||||
Reference in New Issue
Block a user