lyxy-document/openspec/specs/document-reading/spec.md

Purpose

统一文档读取核心能力，包含 CLI 入口、解析调度、Markdown 后处理。

Requirements

Requirement: 统一 CLI 入口

系统 SHALL 提供 lyxy_document_reader.py 作为统一的命令行入口，支持处理所有文档类型。

Scenario: 调用 CLI 帮助信息

• WHEN 用户执行 uv run python lyxy_document_reader.py --help
• THEN 系统显示完整的命令行参数帮助信息

Scenario: CLI 接受输入路径

• WHEN 用户执行 uv run python lyxy_document_reader.py <input_path>
• THEN 系统识别输入类型并解析文档

Requirement: 输入类型自动识别

系统 SHALL 自动识别输入类型，包括 URL 和本地文件。

Scenario: 识别 HTTP URL

• WHEN 输入以 http:// 或 https:// 开头
• THEN 系统识别为 URL，使用 html-reader 处理

Scenario: 识别 DOCX 文件

• WHEN 输入文件扩展名为 .docx 或 .doc，或文件内容为 OOXML Word 格式
• THEN 系统识别为 DOCX，使用 docx-reader 处理

Scenario: 识别 XLSX 文件

• WHEN 输入文件扩展名为 .xlsx、.xls 或 .xlsm，或文件内容为 OOXML Excel 格式
• THEN 系统识别为 XLSX，使用 xlsx-reader 处理

Scenario: 识别 PPTX 文件

• WHEN 输入文件扩展名为 .pptx 或 .ppt，或文件内容为 OOXML PowerPoint 格式
• THEN 系统识别为 PPTX，使用 pptx-reader 处理

Scenario: 识别 PDF 文件

• WHEN 输入文件扩展名为 .pdf，或文件头为 %PDF
• THEN 系统识别为 PDF，使用 pdf-reader 处理

Scenario: 识别 HTML 文件

• WHEN 输入文件扩展名为 .html、.htm 或 .xhtml
• THEN 系统识别为 HTML，使用 html-reader 处理

Requirement: 输出完整 Markdown

系统 SHALL 能够输出解析后的完整 Markdown 内容。

Scenario: 无查询参数时输出完整内容

• WHEN 用户不使用任何查询参数（-c/-l/-t/-tc/-s）
• THEN 系统输出完整的 Markdown 文档内容

Requirement: 字数统计

系统 SHALL 支持统计解析后文档的总字数。

Scenario: 使用 -c 参数统计字数

• WHEN 用户使用 -c 或 --count 参数
• THEN 系统输出解析后文档的总字数（不含换行符）

Requirement: 行数统计

系统 SHALL 支持统计解析后文档的总行数。

Scenario: 使用 -l 参数统计行数

• WHEN 用户使用 -l 或 --lines 参数
• THEN 系统输出解析后文档的总行数

Requirement: 标题提取

系统 SHALL 支持提取文档中的所有标题行。

Scenario: 使用 -t 参数提取标题

• WHEN 用户使用 -t 或 --titles 参数
• THEN 系统输出解析后文档的所有 1-6 级标题行

Requirement: 指定标题内容提取

系统 SHALL 支持提取指定标题及其下级内容。

Scenario: 使用 -tc 参数提取标题内容

• WHEN 用户使用 -tc <name> 或 --title-content <name> 参数
• THEN 系统输出所有匹配标题名称的标题及其下级内容，包含上级标题上下文，多个匹配用 --- 分隔

Scenario: 标题未找到时提示错误

• WHEN 指定的标题名称未找到
• THEN 系统输出错误信息并退出非零状态码

Requirement: 正则搜索

系统 SHALL 支持使用正则表达式搜索文档内容。

Scenario: 使用 -s 参数搜索

• WHEN 用户使用 -s <pattern> 或 --search <pattern> 参数
• THEN 系统输出所有匹配结果及其上下文，多个匹配用 --- 分隔

Scenario: 使用 -n 参数指定上下文行数

• WHEN 用户同时使用 -s <pattern> 和 -n <num> 或 --context <num> 参数
• THEN 系统输出匹配结果及其前后指定行数的上下文（不含空行）

Scenario: 无效正则表达式提示错误

• WHEN 提供的正则表达式无效
• THEN 系统输出错误信息并退出非零状态码

Scenario: 无匹配结果提示错误

• WHEN 未找到任何匹配
• THEN 系统输出错误信息并退出非零状态码

Requirement: Markdown 图片移除

系统 SHALL 自动移除解析结果中的 Markdown 图片标记。

Scenario: 移除图片标记

• WHEN 解析结果包含 ![alt](url) 格式的图片标记
• THEN 系统移除这些图片标记

Requirement: Markdown 空白规范化

系统 SHALL 规范化解析结果中的空白字符，保留单行空行。

Scenario: 规范化连续空行

• WHEN 解析结果包含连续 3 个或更多换行符
• THEN 系统将其替换为 2 个换行符（保留单行空行）

Requirement: 使用 logging 模块

系统 SHALL 使用 Python logging 模块进行日志输出，而非简单 print。

Scenario: 日志输出

• WHEN 系统运行时
• THEN 所有日志信息通过 logging 模块输出

Requirement: 自定义异常

系统 SHALL 使用自定义异常类处理错误，提供清晰的错误信息和位置上下文。

Scenario: 抛出 FileDetectionError

• WHEN 文件类型检测失败
• THEN 系统抛出 FileDetectionError 异常

Scenario: 抛出 ReaderNotFoundError

• WHEN 未找到适配的阅读器
• THEN 系统抛出 ReaderNotFoundError 异常

Scenario: 抛出 ParseError

• WHEN 文档解析失败
• THEN 系统抛出 ParseError 异常

Scenario: 抛出 DownloadError

• WHEN URL 下载失败
• THEN 系统抛出 DownloadError 异常