133 lines
5.8 KiB
Markdown
133 lines
5.8 KiB
Markdown
## 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** 列出每种解析策略的失败原因
|