新增docx解析
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-02-12
|
||||
@@ -0,0 +1,106 @@
|
||||
## Context
|
||||
|
||||
当前项目是一个专门用于开发大模型工具 skill 的项目。`skills/docx-reader` 目录已经存在，其中包含：
|
||||
- `scripts/docx_parser.py` - 完整的 DOCX 解析脚本，支持多策略解析（MarkItDown、python-docx、XML 原生）
|
||||
- `docx_parser.md` - 脚本使用文档
|
||||
|
||||
需要将这些现有资源封装为一个标准的 skill，让大模型能够识别并优先使用该工具处理 .docx 文件。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- 创建 `skills/docx-reader/skill.md` skill 定义文件，符合项目规范
|
||||
- 封装 docx_parser.py 的核心功能为 skill 的能力描述
|
||||
- 确保大模型在遇到 .docx 文件时能够识别并优先使用该 skill
|
||||
- 执行时优先委托给 python-runner skill，利用其依赖管理和环境隔离能力
|
||||
- 支持多种解析模式：全文提取、标题提取、章节内容提取、关键词搜索
|
||||
|
||||
**Non-Goals:**
|
||||
- 修改现有的 docx_parser.py 脚本逻辑
|
||||
- 添加图片或格式提取功能
|
||||
- 实现 docx 文件的编辑或修改功能
|
||||
- 支持 .doc 或其他文档格式
|
||||
|
||||
## Decisions
|
||||
|
||||
### 1. Skill 定义结构
|
||||
**决策**: 采用标准的 skill.md 格式，包含 description、capabilities 等核心字段
|
||||
|
||||
**理由**: 遵循项目现有 skill 的统一规范，便于大模型理解和调用。查看 `skills/` 目录下的其他 skill 示例（如 `python-runner`、`js-runner`）可知项目有一致的定义格式。
|
||||
|
||||
### 2. 依赖声明
|
||||
**决策**: 在 skill.md 的 Compatibility 字段中声明 Python 运行时依赖
|
||||
|
||||
**理由**: docx_parser.py 需要 Python 3.6+ 环境，并且需要至少安装 `markitdown` 或 `python-docx` 之一。明确这些依赖可以帮助大模型判断环境是否就绪。
|
||||
|
||||
### 3. 能力映射
|
||||
**决策**: 将 docx_parser.py 的所有功能映射为 skill 的 capabilities
|
||||
|
||||
**理由**: 脚本提供了丰富的功能（全文、字数、行数、标题、章节、搜索），全部暴露给大模型可以提供更灵活的使用方式。能力包括：
|
||||
- 全文转换为 Markdown
|
||||
- 获取文档元信息（字数、行数）
|
||||
- 标题列表提取
|
||||
- 指定章节内容提取
|
||||
- 正则表达式搜索
|
||||
|
||||
### 4. 触发器设计
|
||||
**决策**: 设置明确的触发器（Trigger phrases），包括中文和英文
|
||||
|
||||
**理由**: 用户可能使用中文或英文请求解析 docx 文档。触发器包括：
|
||||
- "读取 docx", "解析 docx", "打开 word 文档"（中文）
|
||||
- "read docx", "parse docx", "extract from word document"（英文）
|
||||
- 文件扩展名 `.docx` 出现时
|
||||
|
||||
### 5. 执行委托策略
|
||||
**决策**: docx-reader skill 执行时优先委托给 python-runner skill
|
||||
|
||||
**理由**: python-runner skill 提供了统一的 Python 脚本执行环境，具有以下优势：
|
||||
- 使用 uv 管理依赖，自动安装 markitdown 或 python-docx
|
||||
- 环境隔离，不污染系统 Python
|
||||
- 跨平台兼容
|
||||
|
||||
**执行策略**:
|
||||
此 skill 的执行决策由大模型在调用时判断，不在 skill 定义或脚本中实现检查逻辑。
|
||||
|
||||
当大模型决定执行 docx_reader skill 时：
|
||||
- 如果环境中存在 python-runner skill，优先使用 python-runner 执行 docx_parser.py
|
||||
- 如果环境中不存在 python-runner skill，直接使用 Python 执行 docx_parser.py
|
||||
|
||||
**好处**:
|
||||
- 最大化复用现有 skill
|
||||
- 自动处理 Python 依赖管理（通过 python-runner）
|
||||
- 提供更好的错误处理和用户体验
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
### 风险 1: python-runner skill 不可用
|
||||
**风险**: 目标环境可能没有安装 python-runner skill 或其依赖（uv 工具）
|
||||
|
||||
**缓解措施**:
|
||||
- 大模型在执行时判断 python-runner skill 是否存在
|
||||
- 如果 python-runner 不可用，自动降级为直接使用 Python 执行脚本
|
||||
- 在 skill.md 中说明降级策略和直接执行的条件
|
||||
|
||||
### 风险 2: 依赖库未安装（降级场景）
|
||||
**风险**: 当 python-runner 不可用时，直接执行脚本可能遇到 `markitdown` 或 `python-docx` 未安装的情况
|
||||
|
||||
**缓解措施**:
|
||||
- 在 skill.md 的 Compatibility 字段中明确列出可选依赖
|
||||
- 在降级场景中，脚本本身已实现多策略降级（MarkItDown → python-docx → XML 原生）
|
||||
- 提示用户安装 python-runner 获得更好的体验
|
||||
|
||||
### 风险 2: 大文件处理性能
|
||||
**风险**: 大型 .docx 文件解析可能耗时较长
|
||||
|
||||
**缓解措施**:
|
||||
- 在能力描述中提示可以使用章节提取或关键词搜索来限制处理范围
|
||||
- docx_parser.py 已实现流式处理，内存占用相对较低
|
||||
|
||||
### 权衡: 纯文本 vs 格式保留
|
||||
**权衡**: 选择只提取纯文本，不保留图片和复杂格式
|
||||
|
||||
**理由**: 用户明确要求"只能将docx文档转换为文字"，且大模型主要关注文本内容。虽然脚本支持 Markdown 格式转换（表格、粗体、斜体等），但图片会被自动移除，符合需求。
|
||||
|
||||
## Open Questions
|
||||
|
||||
无重大未决问题。设计清晰明确，可以直接进入实现阶段。
|
||||
@@ -0,0 +1,25 @@
|
||||
## Why
|
||||
|
||||
大模型在处理 Word 文档时缺乏统一的解析工具，需要能够直接识别并解析 .docx 文件能力的 skill。现有的 docx_parser.py 脚本已经实现了完整的解析功能，将其封装为 skill 可以让大模型在遇到需要读取 docx 文档的场景时优先使用该工具。
|
||||
|
||||
## What Changes
|
||||
|
||||
- 新增 `docx-reader` skill，封装现有的 `skills/docx-reader/scripts/docx_parser.py` 脚本
|
||||
- 创建 skill 定义文件，支持将 .docx 文件转换为纯文本内容
|
||||
- skill 定位为 docx 文档解析的优先选择工具
|
||||
- 仅支持文本内容提取，不处理图片和格式信息
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `docx-text-extraction`: 将 DOCX 文档转换为 Markdown 格式文本的能力，支持全文提取、标题提取、章节内容提取和关键词搜索
|
||||
|
||||
### Modified Capabilities
|
||||
- 无
|
||||
|
||||
## Impact
|
||||
|
||||
- 新增 `skills/docx-reader/skill.md` - skill 定义文件
|
||||
- 依赖现有的 `skills/docx-reader/scripts/docx_parser.py` 解析脚本
|
||||
- 新增 Python 依赖：`markitdown` 或 `python-docx`（至少需要安装其一）
|
||||
- 影响大模型的技能调用策略，在遇到 .docx 文件时会优先使用该 skill
|
||||
@@ -0,0 +1,132 @@
|
||||
## 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** 列出每种解析策略的失败原因
|
||||
@@ -0,0 +1,27 @@
|
||||
## 1. 准备工作
|
||||
|
||||
- [x] 1.1 研究现有 skill 定义格式，查看 `skills/` 目录下的其他 skill 示例（如 `python-runner`、`js-runner`）了解标准结构
|
||||
- [x] 1.2 阅读 `skills/docx-reader/docx_parser.md` 了解解析脚本的详细功能和使用方式
|
||||
|
||||
## 2. 创建 skill 定义文件
|
||||
|
||||
- [x] 2.1 创建 `skills/docx-reader/skill.md` 文件
|
||||
- [x] 2.2 编写 skill 的 description 字段，描述该 skill 的用途和定位（优先解析 docx 文档）
|
||||
- [x] 2.3 编写 skill 的 capabilities 字段，列出所有支持的解析功能：
|
||||
- 全文转换为 Markdown
|
||||
- 获取文档元信息（字数、行数）
|
||||
- 标题列表提取
|
||||
- 指定章节内容提取
|
||||
- 正则表达式搜索
|
||||
- [x] 2.4 编写 skill 的 Compatibility 字段，声明 Python 3.6+ 和依赖库要求（markitdown 或 python-docx 至少安装其一）
|
||||
- [x] 2.5 编写 skill 的 Triggers 字段，包含中文和英文触发短语：
|
||||
- 中文："读取 docx", "解析 docx", "打开 word 文档"
|
||||
- 英文："read docx", "parse docx", "extract from word document"
|
||||
- 文件扩展名 ".docx"
|
||||
|
||||
## 3. 验证和测试
|
||||
|
||||
- [x] 3.1 验证 skill.md 文件格式是否符合项目规范
|
||||
- [x] 3.2 确认 skill.md 中的触发器能够正确识别 docx 解析需求
|
||||
- [x] 3.3 确认 skill.md 中的依赖说明清晰准确
|
||||
- [x] 3.4 确认 skill.md 的 capabilities 覆盖了 docx_parser.py 的所有功能
|
||||
Reference in New Issue
Block a user