From 53707efaf0ff2d2c7b1b95935b570d9f9873f65e Mon Sep 17 00:00:00 2001 From: lanyuanxiaoyao Date: Thu, 12 Feb 2026 16:23:23 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E5=A2=9Edocx=E8=A7=A3=E6=9E=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../.openspec.yaml | 2 + .../design.md | 106 +++++++ .../proposal.md | 25 ++ .../specs/docx-text-extraction/spec.md | 132 +++++++++ .../tasks.md | 27 ++ openspec/specs/docx-text-extraction/spec.md | 132 +++++++++ skills/docx-reader/SKILL.md | 279 ++++++++++++++++++ 7 files changed, 703 insertions(+) create mode 100644 openspec/changes/archive/2026-02-12-develop-docx-reader-skill/.openspec.yaml create mode 100644 openspec/changes/archive/2026-02-12-develop-docx-reader-skill/design.md create mode 100644 openspec/changes/archive/2026-02-12-develop-docx-reader-skill/proposal.md create mode 100644 openspec/changes/archive/2026-02-12-develop-docx-reader-skill/specs/docx-text-extraction/spec.md create mode 100644 openspec/changes/archive/2026-02-12-develop-docx-reader-skill/tasks.md create mode 100644 openspec/specs/docx-text-extraction/spec.md create mode 100644 skills/docx-reader/SKILL.md diff --git a/openspec/changes/archive/2026-02-12-develop-docx-reader-skill/.openspec.yaml b/openspec/changes/archive/2026-02-12-develop-docx-reader-skill/.openspec.yaml new file mode 100644 index 0000000..95d284a --- /dev/null +++ b/openspec/changes/archive/2026-02-12-develop-docx-reader-skill/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-12 diff --git a/openspec/changes/archive/2026-02-12-develop-docx-reader-skill/design.md b/openspec/changes/archive/2026-02-12-develop-docx-reader-skill/design.md new file mode 100644 index 0000000..8371f1d --- /dev/null +++ b/openspec/changes/archive/2026-02-12-develop-docx-reader-skill/design.md @@ -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 + +无重大未决问题。设计清晰明确，可以直接进入实现阶段。 diff --git a/openspec/changes/archive/2026-02-12-develop-docx-reader-skill/proposal.md b/openspec/changes/archive/2026-02-12-develop-docx-reader-skill/proposal.md new file mode 100644 index 0000000..f7a1201 --- /dev/null +++ b/openspec/changes/archive/2026-02-12-develop-docx-reader-skill/proposal.md @@ -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 diff --git a/openspec/changes/archive/2026-02-12-develop-docx-reader-skill/specs/docx-text-extraction/spec.md b/openspec/changes/archive/2026-02-12-develop-docx-reader-skill/specs/docx-text-extraction/spec.md new file mode 100644 index 0000000..c89a130 --- /dev/null +++ b/openspec/changes/archive/2026-02-12-develop-docx-reader-skill/specs/docx-text-extraction/spec.md @@ -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** 列出每种解析策略的失败原因 diff --git a/openspec/changes/archive/2026-02-12-develop-docx-reader-skill/tasks.md b/openspec/changes/archive/2026-02-12-develop-docx-reader-skill/tasks.md new file mode 100644 index 0000000..00bb16f --- /dev/null +++ b/openspec/changes/archive/2026-02-12-develop-docx-reader-skill/tasks.md @@ -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 的所有功能 diff --git a/openspec/specs/docx-text-extraction/spec.md b/openspec/specs/docx-text-extraction/spec.md new file mode 100644 index 0000000..883c6a8 --- /dev/null +++ b/openspec/specs/docx-text-extraction/spec.md @@ -0,0 +1,132 @@ +## 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** 列出每种解析策略的失败原因 diff --git a/skills/docx-reader/SKILL.md b/skills/docx-reader/SKILL.md new file mode 100644 index 0000000..f99435c --- /dev/null +++ b/skills/docx-reader/SKILL.md @@ -0,0 +1,279 @@ +--- +name: docx-reader +description: 优先解析 docx 文档的 skill，将 DOCX 文件转换为纯文本内容，不支持图片和格式提取。 +compatibility: Requires Python 3.6+ and at least one of: markitdown or python-docx +--- + +# DOCX 文档解析 Skill + +将 Microsoft Word (.docx) 文档解析为纯文本内容，支持多种解析模式和检索功能。 + +## Purpose + +**依赖选项**: 此 skill 可以使用 python-runner skill（推荐）或直接使用 Python 执行。 + +### 优先使用 python-runner + +如果环境中存在 python-runner skill，应优先使用它来执行 docx_parser.py 脚本： +- python-runner 使用 uv 管理依赖，自动安装 markitdown 或 python-docx +- 环境隔离，不污染系统 Python +- 跨平台兼容（Windows/macOS/Linux） + +### 降级到直接执行 + +如果环境中不存在 python-runner skill，则直接使用 Python 执行 docx_parser.py： +- 需要手动安装 markitdown 或 python-docx +- 脚本内部实现了多策略解析降级：MarkItDown → python-docx → XML 原生 + +## When to Use + +任何需要读取或解析 .docx 文件内容的任务都应使用此 skill。 + +### 典型场景 +- **文档内容提取**: 将 Word 文档转换为可读的文本内容 +- **文档元数据**: 获取文档的字数、行数等信息 +- **标题分析**: 提取文档的标题结构 +- **章节提取**: 提取特定章节的内容 +- **内容搜索**: 在文档中搜索关键词或模式 + +### 不适用场景 +- ✗ 需要提取图片内容（仅支持纯文本） +- ✗ 需要保留复杂的格式信息（如字体、颜色、布局） +- ✗ 需要编辑或修改 .docx 文件 +- ✗ 需要处理 .doc 或其他文档格式 + +## Capabilities + +### 1. 全文转换为 Markdown +将完整的 DOCX 文档解析为 Markdown 格式文本，移除所有图片但保留文本格式。 + +**支持格式转换**: +- 标题（1-6级） +- 列表（有序和无序） +- 表格 +- 粗体、斜体、下划线 +- 连续空行规范化 + +### 2. 获取文档元信息 +提供文档的基本统计信息： +- 字数统计（使用 `-c` 参数） +- 行数统计（使用 `-l` 参数） + +### 3. 标题列表提取 +提取文档中的所有标题（1-6级），按原始层级关系返回。 + +### 4. 指定章节内容提取 +根据标题名称提取特定章节的完整内容，包括： +- 完整的上级标题链 +- 该标题下的所有下级内容 + +支持同名标题提取，返回所有匹配章节。 + +### 5. 正则表达式搜索 +在文档中搜索关键词或模式： +- 支持标准正则表达式 +- 可自定义上下文行数（默认前后各 2 行） +- 多个匹配结果用 `---` 分隔 +- 上下文行数不包含空行 + +## Triggers + +### 中文触发词 +- "读取 docx" +- "解析 docx" +- "打开 word 文档" +- "提取 word 文档内容" +- "解析 word 文件" + +### 英文触发词 +- "read docx" +- "parse docx" +- "extract from word document" +- "parse word file" +- "read word document" + +### 文件扩展名 +- `.docx` 文件 + +## Execution + +### 优先使用 python-runner + +**推荐执行方式**（如果 python-runner skill 可用）: + +```bash +# 使用 python-runner 执行（推荐） +uv run --with markitdown skills/docx-reader/scripts/docx_parser.py /path/to/document.docx + +# 或使用 python-docx +uv run --with python-docx skills/docx-reader/scripts/docx_parser.py /path/to/document.docx +``` + +**大模型应优先检查 python-runner skill 是否存在，如果存在则使用它执行。** + +### 降级到直接执行 + +如果 python-runner skill 不可用，则直接使用 Python： + +```bash +# 直接使用 Python 执行 +python3 skills/docx-reader/scripts/docx_parser.py /path/to/document.docx +``` + +**提示用户**: 建议用户安装 markitdown 或 python-docx 以获得更好的解析效果： +``` +建议：安装 markitdown 或 python-docx 以获得更好的解析效果 + +安装命令： + pip install markitdown # 推荐 + pip install python-docx # 备选 +``` + +**禁止自动安装**: 不得自动执行 pip install 命令安装依赖。仅向用户提示安装建议即可。 + +**降级策略说明**: 脚本内部实现了多策略解析降级（MarkItDown → python-docx → XML 原生），即使未安装第三方库也能通过 XML 原生解析工作，只是功能可能受限。 + +## Command Usage + +### 基本语法 +```bash +python3 docx_parser.py [options] +``` + +### 参数说明 + +| 参数 | 说明 | +| ----------- | ------------------- | +| `file_path` | DOCX 文件的绝对路径 | + +### 选项参数 + +| 参数 | 长参数 | 类型 | 默认值 | 说明 | +| ---- | ----------- | ---- | ------ | -------------------------------------------------------------- | +| `-n` | `--context` | 整数 | 2 | 与 `-s` 配合使用，指定每个检索结果包含的前后行数（不包含空行） | + +### 互斥参数（只能使用其中一个） + +| 参数 | 长参数 | 说明 | +| ----- | ----------------- | ----------------------------------------------------- | +| `-c` | `--count` | 返回解析后的 markdown 文档的总字数 | +| `-l` | `--lines` | 返回解析后的 markdown 文档的总行数 | +| `-t` | `--titles` | 返回解析后的 markdown 文档的标题行（1-6级） | +| `-tc` | `--title-content` | 指定标题名称，输出该标题及其下级内容（不包含#号） | +| `-s` | --search | 使用正则表达式搜索文档，返回所有匹配结果（用---分隔） | + +## Examples + +### 示例 1: 提取完整文档内容 +```bash +# 提取完整文档 +python3 docx_parser.py /path/to/document.docx +``` + +输出：完整的 Markdown 格式文档内容 + +### 示例 2: 获取文档字数 +```bash +# 获取字数 +python3 docx_parser.py -c /path/to/document.docx +``` + +输出：文档总字数（数字） + +### 示例 3: 提取所有标题 +```bash +# 提取标题 +python3 docx_parser.py -t /path/to/document.docx +``` + +输出：所有 1-6 级标题列表 + +### 示例 4: 提取指定章节 +```bash +# 提取 "第一章" 内容 +python3 docx_parser.py -tc "第一章" /path/to/document.docx +``` + +输出：该章节的完整内容（包含上级标题链和所有下级内容） + +### 示例 5: 搜索关键词 +```bash +# 搜索关键词（默认 2 行上下文） +python3 docx_parser.py -s "关键词" /path/to/document.docx + +# 自定义 5 行上下文 +python3 docx_parser.py -s "关键词" -n 5 /path/to/document.docx +``` + +输出：所有匹配结果及其上下文，用 `---` 分隔 + +## 依赖安装 + +### 推荐方式：使用 python-runner + +如果使用 python-runner skill，依赖会自动管理，无需手动安装。 + +### 手动安装（降级模式） + +如果直接使用 Python 执行，需要手动安装至少一个解析库： + +```bash +# 安装 MarkItDown（推荐） +pip install markitdown + +# 安装 python-docx（备选） +pip install python-docx +``` + +**重要限制**: +- ✗ **禁止自动安装**: 不得自动执行 pip install 命令安装依赖 +- ✗ **仅提示即可**: 向用户展示安装建议，但由用户决定是否安装 +- ✗ **不阻塞执行**: 即使未安装依赖，脚本也能通过 XML 原生解析运行 + +### 多策略解析 + +脚本自动尝试以下解析方法，确保最大兼容性： +1. **MarkItDown**（微软官方库，效果最佳） +2. **python-docx**（成熟的 Python 库） +3. **XML 原生解析**（备选方案，无需任何依赖） + +即使未安装任何依赖库，脚本也会尝试使用 XML 原生解析，但功能可能受限。 + +## Error Handling + +### 常见错误 + +| 错误类型 | 说明 | 解决方案 | +| --------- | ---- | -------- | +| 文件不存在 | 提供的文件路径无效 | 检查文件路径是否正确 | +| 无效的 DOCX | 文件不是有效的 DOCX 格式或已损坏 | 确认文件格式正确 | +| 未找到标题 | 指定的标题名称不存在 | 使用 `-t` 参数查看所有标题 | +| 正则表达式无效 | 提供的正则表达式格式错误 | 检查正则表达式语法 | +| 解析库未安装 | 未安装 markitdown 或 python-docx | 提示用户安装以获得更好的解析效果，但禁止自动安装。脚本会自动降级到 XML 原生解析。 | + +## Notes + +### 为什么选择 python-runner？ + +| 特性 | 优势 | +| ------ | ------ | +| 环境隔离 | 不污染系统 Python | +| 自动依赖 | 自动安装 markitdown 或 python-docx | +| 快速启动 | 比 venv 快 10-100 倍 | +| 跨平台 | 自动适配 Windows/macOS/Linux | +| 零配置 | 开箱即用，无需预安装依赖 | + +### 最佳实践 + +1. **优先使用 python-runner**: 如果环境中存在，应优先使用 python-runner 执行脚本 +2. **大文件处理**: 对于大文档，建议使用章节提取或关键词搜索来限制处理范围 +3. **依赖管理**: 使用 python-runner 可以自动管理依赖，避免环境配置问题 +4. **错误处理**: 脚本会自动尝试多种解析方法，确保最大兼容性 +5. **禁止自动安装**: 在降级到直接 Python 执行时，仅向用户提示安装依赖，不得自动执行 pip install + +### 限制 + +- ✗ 不支持图片提取（仅纯文本） +- ✗ 不支持复杂的格式保留（字体、颜色、布局等） +- ✗ 不支持文档编辑或修改 +- ✗ 仅支持 .docx 格式（不支持 .doc 或其他格式）