统一skill命名

openspec/changes/archive/2026-02-12-develop-lyxy-reader-docx-skill/specs/docx-text-extraction/spec.md

@@ -0,0 +1,132 @@
+## ADDED Requirements
+
+### Requirement: Delegate execution to lyxy-runner-python skill
+当大模型执行 lyxy-reader-docx skill 时，应优先使用 lyxy-runner-python skill 来运行 docx_parser.py 脚本。如果 lyxy-runner-python skill 不可用，则直接使用 Python 执行。
+
+#### Scenario: lyxy-runner-python available
+- **WHEN** 大模型环境中存在 lyxy-runner-python skill
+- **THEN** 大模型通过 lyxy-runner-python skill 执行 docx_parser.py
+- **AND** 利用 lyxy-runner-python 的自动依赖管理功能安装所需的 Python 包（markitdown 或 python-docx）
+
+#### Scenario: lyxy-runner-python unavailable
+- **WHEN** 大模型环境中不存在 lyxy-runner-python skill
+- **THEN** 大模型直接使用 Python 执行 docx_parser.py
+- **AND** 提示用户正在使用直接执行模式（未使用 lyxy-runner-python）
+- **AND** 依赖 docx_parser.py 内部的多策略解析降级机制
+
+### Requirement: Extract full text from DOCX file
+系统 SHALL 能够将 DOCX 文件完整解析为 Markdown 格式的文本内容，移除所有图片但保留文本格式（如标题、列表、粗体、斜体、表格）。
+
+#### Scenario: Successful full text extraction
+- **WHEN** 用户请求解析一个有效的 .docx 文件
+- **THEN** 系统返回完整的 Markdown 格式文本
+- **AND** 所有文本内容被保留
+- **AND** 所有图片被移除
+- **AND** 表格、列表、粗体、斜体等格式被转换为 Markdown 语法
+- **AND** 连续的空行被合并为一个空行
+
+#### Scenario: Invalid DOCX file
+- **WHEN** 提供的文件不是有效的 DOCX 格式或已损坏
+- **THEN** 系统返回错误信息
+- **AND** 错误信息明确说明文件格式问题
+
+#### Scenario: Empty DOCX file
+- **WHEN** 提供的 DOCX 文件为空或无文本内容
+- **THEN** 系统返回空字符串或相应的提示信息
+
+### Requirement: Extract document metadata
+系统 SHALL 能够提供 DOCX 文档的元数据信息，包括字数和行数。
+
+#### Scenario: Get word count
+- **WHEN** 用户请求获取 DOCX 文档的字数
+- **THEN** 系统返回文档的总字数（数字）
+- **AND** 字数统计基于解析后的 Markdown 内容
+
+#### Scenario: Get line count
+- **WHEN** 用户请求获取 DOCX 文档的行数
+- **THEN** 系统返回文档的总行数（数字）
+- **AND** 行数统计基于解析后的 Markdown 内容
+
+### Requirement: Extract document titles
+系统 SHALL 能够提取 DOCX 文档中的所有标题（1-6级标题），并按原始层级关系返回。
+
+#### Scenario: Extract all titles
+- **WHEN** 用户请求提取 DOCX 文档的所有标题
+- **THEN** 系统返回所有 1-6 级标题
+- **AND** 每个标题以 Markdown 标题格式返回（如 `# 主标题`、`## 二级标题`）
+- **AND** 标题按文档中的原始顺序返回
+- **AND** 保留原始标题层级关系
+
+#### Scenario: Document with no titles
+- **WHEN** DOCX 文档中不包含任何标题
+- **THEN** 系统返回空列表或无标题提示
+
+### Requirement: Extract chapter content by title name
+系统 SHALL 能够根据标题名称提取指定章节的内容，包括完整的上级标题链和所有下级内容。
+
+#### Scenario: Extract single chapter content
+- **WHEN** 用户请求提取特定标题名称的章节内容
+- **THEN** 系统返回该章节的完整内容
+- **AND** 包含完整的上级标题链（如：主标题 -> 章标题 -> 小节）
+- **AND** 包含该标题下的所有下级内容
+- **AND** 返回内容使用 Markdown 格式
+
+#### Scenario: Extract multiple chapters with same name
+- **WHEN** 文档中存在多个同名标题且用户请求提取该标题内容
+- **THEN** 系统返回所有同名标题的章节内容
+- **AND** 每个章节都包含其完整的上级标题链
+- **AND** 各章节内容之间有明确的分隔
+
+#### Scenario: Title not found
+- **WHEN** 用户请求提取的标题名称在文档中不存在
+- **THEN** 系统返回未找到标题的错误信息
+
+### Requirement: Search document with regex
+系统 SHALL 能够使用正则表达式在 DOCX 文档中搜索关键词，并返回所有匹配结果及其上下文。
+
+#### Scenario: Basic keyword search
+- **WHEN** 用户使用关键词搜索 DOCX 文档
+- **THEN** 系统返回所有匹配的文本片段
+- **AND** 每个结果包含默认的上下文（前后各 2 行）
+- **AND** 各结果之间使用 `---` 分隔
+- **AND** 上下文行数不包含空行
+
+#### Scenario: Custom context lines
+- **WHEN** 用户指定上下文行数进行搜索
+- **THEN** 系统按指定行数返回上下文
+- **AND** 支持 0 行上下文（仅返回匹配行）
+- **AND** 上下文行数不包含空行
+
+#### Scenario: Regex pattern search
+- **WHEN** 用户使用正则表达式模式搜索
+- **THEN** 系统支持 Python 标准正则表达式语法
+- **AND** 正确处理特殊字符的转义
+- **AND** 返回所有匹配模式的文本片段
+
+#### Scenario: No matches found
+- **WHEN** 搜索关键词或模式在文档中无匹配
+- **THEN** 系统返回未找到匹配的提示信息
+
+#### Scenario: Invalid regex pattern
+- **WHEN** 用户提供的正则表达式格式无效
+- **THEN** 系统返回正则表达式无效的错误信息
+
+### Requirement: Multi-strategy parsing fallback
+系统 SHALL 按优先级尝试多种解析策略，确保最大的兼容性。
+
+#### Scenario: Prefer MarkItDown parser
+- **WHEN** 系统检测到 `markitdown` 库已安装
+- **THEN** 系统优先使用 MarkItDown 解析器解析 DOCX 文件
+
+#### Scenario: Fallback to python-docx
+- **WHEN** MarkItDown 解析失败或未安装，且 `python-docx` 库已安装
+- **THEN** 系统使用 python-docx 作为备选解析器
+
+#### Scenario: Fallback to XML parsing
+- **WHEN** MarkItDown 和 python-docx 均未安装或解析失败
+- **THEN** 系统使用 XML 原生解析作为最后备选方案
+
+#### Scenario: All parsers failed
+- **WHEN** 所有解析策略均失败
+- **THEN** 系统返回详细的失败信息
+- **AND** 列出每种解析策略的失败原因