lanyuanxiaoyao/lyxy-document
1
0
Fork 0
Code Releases Activity
Files
c35bbc90b52394124e80d76b34c38d7c7ca237d9
lyxy-document/openspec/specs/encoding-detection/spec.md
lanyuanxiaoyao 750ef50a8d 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）
2026-03-08 16:33:40 +08:00

2.9 KiB
Raw Blame History

Purpose

文件编码自动检测能力，支持多种编码格式的自动识别和回退机制。

Requirements

Requirement: 文件编码自动检测

系统 SHALL 使用 chardet 库自动检测文件编码，支持多种常见编码格式。

Scenario: 使用 chardet 检测编码

  • WHEN 需要读取文本文件
  • THEN 系统使用 chardet 库检测文件编码

Scenario: 检测成功返回编码

  • WHEN chardet 成功检测编码
  • THEN 系统返回检测到的编码名称

Scenario: chardet 库未安装

  • WHEN chardet 库未安装
  • THEN 系统返回错误信息 "chardet 库未安装"

Scenario: 检测失败返回错误

  • WHEN chardet 检测失败
  • THEN 系统返回错误信息包含失败原因

Requirement: 编码回退机制

系统 SHALL 在 chardet 检测失败时，按配置的编码列表依次尝试读取文件。

Scenario: chardet 失败时尝试回退编码

  • WHEN chardet 检测失败或返回错误
  • THEN 系统按 Config.FALLBACK_ENCODINGS 列表依次尝试编码

Scenario: 回退编码成功

  • WHEN 某个回退编码成功读取文件
  • THEN 系统返回文件内容

Scenario: 所有编码均失败

  • WHEN 所有回退编码均无法读取文件
  • THEN 系统返回错误信息 "无法识别文件编码"

Requirement: 统一文本文件读取接口

系统 SHALL 提供统一的文本文件读取函数，自动处理编码检测和回退。

Scenario: 调用 read_text_file 读取文件

  • WHEN 调用 read_text_file(file_path)
  • THEN 系统自动检测编码并返回文件内容

Scenario: 读取成功返回内容

  • WHEN 文件读取成功
  • THEN 系统返回 (content, None)

Scenario: 读取失败返回错误

  • WHEN 文件读取失败
  • THEN 系统返回 (None, error_message)

Requirement: 支持常见中文编码

系统 SHALL 在回退编码列表中包含常见中文编码格式。

Scenario: 回退编码包含 UTF-8

  • WHEN 使用回退编码列表
  • THEN 列表包含 'utf-8'

Scenario: 回退编码包含 GBK

  • WHEN 使用回退编码列表
  • THEN 列表包含 'gbk'

Scenario: 回退编码包含 GB2312

  • WHEN 使用回退编码列表
  • THEN 列表包含 'gb2312'

Scenario: 回退编码包含 Latin-1

  • WHEN 使用回退编码列表
  • THEN 列表包含 'latin-1'

Requirement: 编码检测模块独立

系统 SHALL 将编码检测功能实现为独立模块，便于复用。

Scenario: 编码检测在独立文件

  • WHEN 使用编码检测功能
  • THEN 从独立的 encoding_detection.py 模块导入

Scenario: 提供 detect_encoding 函数

  • WHEN 需要仅检测编码不读取内容
  • THEN 系统提供 detect_encoding(file_path) 函数

Scenario: 提供 read_text_file 函数

  • WHEN 需要检测编码并读取内容
  • THEN 系统提供 read_text_file(file_path) 函数
View Git Blame Copy Permalink