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

ADDED Requirements

Requirement: Delegate execution to python-runner skill

当大模型执行 docx-reader skill 时，应优先使用 python-runner skill 来运行 docx_parser.py 脚本。如果 python-runner skill 不可用，则直接使用 Python 执行。

Scenario: python-runner available

• WHEN 大模型环境中存在 python-runner skill
• THEN 大模型通过 python-runner skill 执行 docx_parser.py
• AND 利用 python-runner 的自动依赖管理功能安装所需的 Python 包（markitdown 或 python-docx）

Scenario: python-runner unavailable

• WHEN 大模型环境中不存在 python-runner skill
• THEN 大模型直接使用 Python 执行 docx_parser.py
• AND 提示用户正在使用直接执行模式（未使用 python-runner）
• 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 列出每种解析策略的失败原因