增加lyxy-reader-office skill

2026-02-17 22:50:06 +08:00
parent 9f686270c2
commit 9f04dac50b
25 changed files with 609 additions and 1282 deletions
--- a/openspec/changes/archive/2026-02-17-create-lyxy-reader-office/.openspec.yaml
+++ b/openspec/changes/archive/2026-02-17-create-lyxy-reader-office/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-17
--- a/openspec/changes/archive/2026-02-17-create-lyxy-reader-office/design.md
+++ b/openspec/changes/archive/2026-02-17-create-lyxy-reader-office/design.md
@@ -0,0 +1,76 @@
+## Context
+
+当前项目中存在 `lyxy-reader-docx` skill，仅支持 DOCX 格式的文档解析。`skills/lyxy-reader-office/scripts/` 目录下已完成全部解析脚本的开发（parser.py、common.py、docx_parser.py、pptx_parser.py、xlsx_parser.py、pdf_parser.py、README.md），支持 DOCX、PPTX、XLSX、PDF 四种格式。现在需要创建 `SKILL.md` 作为 skill 的入口文件，并清理被替代的旧 skill。
+
+已有资源：
+- `skills/lyxy-reader-docx/SKILL.md`：参考模板，已验证的 skill 结构
+- `skills/lyxy-runner-python/SKILL.md`：Python 执行 skill，与本 skill 协作
+- `skills/lyxy-reader-office/scripts/README.md`：完整的脚本使用文档
+- `document/specification.md`：skill 格式规范
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- 创建 `skills/lyxy-reader-office/SKILL.md`，遵循 skill 格式规范
+- SKILL.md 的 description 能覆盖 .docx、.xlsx、.pptx、.pdf 四种文件扩展名关键词，确保大模型在发现阶段能正确匹配
+- 引导大模型优先使用该 skill 读取这四种格式的文件
+- 引导大模型阅读 `scripts/README.md` 获取详细的脚本使用说明
+- 引导大模型在 `lyxy-runner-python` skill 可用时必须使用该 skill 来运行 Python 脚本
+- 删除 `skills/lyxy-reader-docx` 目录
+
+**Non-Goals:**
+
+- 不修改已有的解析脚本代码
+- 不修改 `lyxy-runner-python` skill
+- 不新增任何解析功能
+- 不创建单独的文档说明文件（如旧 skill 的 `docx_parser.md`），详细用法通过引导阅读 README.md 解决
+
+## Decisions
+
+### 决策 1：SKILL.md 结构参考 lyxy-reader-docx 但大幅精简
+
+**选择**：SKILL.md 专注于发现（description）、激活引导（何时使用、触发条件）和执行入口（指向 README.md），不在 SKILL.md 中重复 README.md 的内容。
+
+**理由**：
+- 规范建议 SKILL.md 保持在 500 行以下
+- README.md 已包含完整的命令行用法、参数说明、安装指南、错误处理等
+- 重复内容会导致维护负担，且增加不必要的 token 消耗
+- 渐进式披露：SKILL.md 负责激活判断，README.md 负责执行细节
+
+**替代方案**：将 README.md 全部内容嵌入 SKILL.md — 拒绝，因为会超过 500 行限制且违反渐进式披露原则。
+
+### 决策 2：强制引导使用 lyxy-runner-python
+
+**选择**：在 SKILL.md 中明确要求大模型在 `lyxy-runner-python` skill 可用时**必须**使用该 skill 来运行 parser.py，不提供直接 Python 执行的选项。仅在 `lyxy-runner-python` 不可用时降级到直接 Python 执行。
+
+**理由**：
+- lyxy-runner-python 使用 uv 管理依赖，能自动安装解析器所需的第三方库
+- 环境隔离，不污染系统 Python
+- 与 lyxy-reader-docx 保持一致的执行策略
+
+**替代方案**：将 lyxy-runner-python 作为可选推荐 — 拒绝，因为用户明确要求"必须使用"。
+
+### 决策 3：通过引导阅读 README.md 提供详细用法
+
+**选择**：SKILL.md 中仅给出基本的执行命令格式和常见示例，详细的参数说明、依赖安装、解析器对比等内容通过引导大模型阅读 `scripts/README.md` 获取。
+
+**理由**：
+- 符合渐进式披露原则：SKILL.md 是指令层，README.md 是资源层
+- README.md 已有完整且结构化的文档，无需重复
+- 减少 SKILL.md 的体积，提高激活阶段的效率
+
+### 决策 4：删除 lyxy-reader-docx 而非保留兼容
+
+**选择**：直接删除整个 `skills/lyxy-reader-docx/` 目录。
+
+**理由**：
+- lyxy-reader-office 完全覆盖了 lyxy-reader-docx 的功能
+- 保留旧 skill 会导致两个 skill 争抢 .docx 文件的处理权，造成歧义
+- 用户明确要求删除
+
+## Risks / Trade-offs
+
+- **[旧 skill 引用残留]** → 检查项目中是否有其他地方引用了 `lyxy-reader-docx`（如 .claude/settings 中的 skill 配置），删除时需同步清理
+- **[description 覆盖度]** → description 需要包含 docx、xlsx、pptx、pdf 等关键词，确保大模型在发现阶段能匹配到四种文件类型。但 description 有 1024 字符限制，需要精简表达
+- **[SKILL.md 体积控制]** → 需在"提供足够的执行引导"和"保持 500 行以内"之间平衡。通过引导阅读 README.md 解决详细信息的需求
--- a/openspec/changes/archive/2026-02-17-create-lyxy-reader-office/proposal.md
+++ b/openspec/changes/archive/2026-02-17-create-lyxy-reader-office/proposal.md
@@ -0,0 +1,30 @@
+## Why
+
+当前项目中仅有 `lyxy-reader-docx` skill 用于解析 DOCX 文档，无法覆盖 XLSX、PPTX、PDF 等常见办公文档格式。用户在日常工作中经常需要大模型读取多种格式的文档，缺少统一的多格式文档解析能力会导致大模型无法有效处理这些文件。需要创建一个统一的办公文档解析 skill，覆盖四种主流格式，并替换功能已被覆盖的旧 skill。
+
+## What Changes
+
+- 新增 `lyxy-reader-office` skill，支持解析 DOCX、XLSX、PPTX、PDF 四种格式
+- 该 skill 使用 `scripts/parser.py` 作为统一入口，自动识别文件类型并分派到对应的格式解析器
+- 引导大模型在遇到这四种文件时优先激活并使用该 skill
+- 引导大模型通过阅读 `scripts/README.md` 了解脚本的详细使用方式
+- 引导大模型在环境中存在 `lyxy-runner-python` skill 时，必须使用该 skill 来运行 Python 脚本
+- **BREAKING**：删除 `skills/lyxy-reader-docx` 目录，因为其功能已完全被 `lyxy-reader-office` 覆盖
+
+## Capabilities
+
+### New Capabilities
+
+- `office-document-parsing`: 统一的办公文档解析能力，覆盖 DOCX、XLSX、PPTX、PDF 四种格式，支持全文提取、标题提取、章节提取、正则搜索、字数统计、行数统计等功能，PDF 额外支持 OCR 高精度模式
+
+### Modified Capabilities
+
+- `docx-text-extraction`: 该能力将被 `office-document-parsing` 完全替代，原 spec 不再适用
+
+## Impact
+
+- **新增文件**：`skills/lyxy-reader-office/SKILL.md`（skill 主文件）
+- **脚本文件**：`skills/lyxy-reader-office/scripts/` 下的所有解析脚本已就绪（parser.py、common.py、docx_parser.py、pptx_parser.py、xlsx_parser.py、pdf_parser.py、README.md）
+- **删除目录**：`skills/lyxy-reader-docx/`（整个目录，包含 SKILL.md、docx_parser.md、scripts/docx_parser.py）
+- **依赖关系**：运行时依赖 Python 3.6+，推荐通过 `lyxy-runner-python` skill 使用 `uv` 自动管理依赖
+- **Spec 变更**：`docx-text-extraction` spec 将被废弃，新增 `office-document-parsing` spec
--- a/openspec/changes/archive/2026-02-17-create-lyxy-reader-office/specs/docx-text-extraction/spec.md
+++ b/openspec/changes/archive/2026-02-17-create-lyxy-reader-office/specs/docx-text-extraction/spec.md
@@ -0,0 +1,29 @@
+## REMOVED Requirements
+
+### Requirement: Delegate execution to lyxy-runner-python skill
+**Reason**: 该能力已被 `office-document-parsing` spec 中的「必须通过 lyxy-runner-python 执行脚本」需求完全替代
+**Migration**: 使用 lyxy-reader-office skill 替代 lyxy-reader-docx skill
+
+### Requirement: Extract full text from DOCX file
+**Reason**: 该能力已被 `office-document-parsing` spec 中的「支持多格式文档解析」需求完全替代
+**Migration**: 使用 lyxy-reader-office skill 的 parser.py 解析 DOCX 文件
+
+### Requirement: Extract document metadata
+**Reason**: 该能力已被 `office-document-parsing` spec 中的「统一的查询功能」需求完全替代
+**Migration**: 使用 lyxy-reader-office skill 的 `-c` 和 `-l` 参数
+
+### Requirement: Extract document titles
+**Reason**: 该能力已被 `office-document-parsing` spec 中的「统一的查询功能」需求完全替代
+**Migration**: 使用 lyxy-reader-office skill 的 `-t` 参数
+
+### Requirement: Extract chapter content by title name
+**Reason**: 该能力已被 `office-document-parsing` spec 中的「统一的查询功能」需求完全替代
+**Migration**: 使用 lyxy-reader-office skill 的 `-tc` 参数
+
+### Requirement: Search document with regex
+**Reason**: 该能力已被 `office-document-parsing` spec 中的「统一的查询功能」需求完全替代
+**Migration**: 使用 lyxy-reader-office skill 的 `-s` 参数
+
+### Requirement: Multi-strategy parsing fallback
+**Reason**: 该能力已被 `office-document-parsing` spec 中的「多策略解析降级」需求完全替代，且新版本支持更多格式和更多解析策略
+**Migration**: 使用 lyxy-reader-office skill，支持 DOCX/PPTX/XLSX/PDF 四种格式的多策略降级
--- a/openspec/changes/archive/2026-02-17-create-lyxy-reader-office/specs/office-document-parsing/spec.md
+++ b/openspec/changes/archive/2026-02-17-create-lyxy-reader-office/specs/office-document-parsing/spec.md
@@ -0,0 +1,115 @@
+## ADDED Requirements
+
+### Requirement: 优先使用 lyxy-reader-office 解析办公文档
+大模型在遇到 .docx、.xlsx、.pptx、.pdf 文件时，SHALL 优先激活并使用 lyxy-reader-office skill 来读取文件内容。
+
+#### Scenario: 用户请求读取支持的文件格式
+- **WHEN** 用户请求读取或解析 .docx、.xlsx、.pptx 或 .pdf 文件
+- **THEN** 大模型 SHALL 激活 lyxy-reader-office skill
+- **AND** 使用 skill 目录下的 `scripts/parser.py` 执行解析
+
+#### Scenario: 文件扩展名自动识别
+- **WHEN** 用户提供的文件路径以 .docx、.xlsx、.pptx 或 .pdf 结尾
+- **THEN** 大模型 SHALL 自动识别为 lyxy-reader-office skill 的处理范围
+- **AND** 无需用户显式指定使用哪个 skill
+
+### Requirement: 必须通过 lyxy-runner-python 执行脚本
+当环境中存在 lyxy-runner-python skill 时，大模型 SHALL 必须使用该 skill 来运行 parser.py 脚本。
+
+#### Scenario: lyxy-runner-python 可用
+- **WHEN** 大模型环境中存在 lyxy-runner-python skill
+- **THEN** 大模型 SHALL 通过 lyxy-runner-python skill 执行 parser.py
+- **AND** 利用 lyxy-runner-python 的自动依赖管理功能（uv）安装所需的 Python 包
+
+#### Scenario: lyxy-runner-python 不可用
+- **WHEN** 大模型环境中不存在 lyxy-runner-python skill
+- **THEN** 大模型 SHALL 降级到直接使用 Python 执行 parser.py
+- **AND** 提示用户当前使用直接执行模式
+- **AND** 禁止自动执行 pip install 安装依赖
+
+### Requirement: 引导阅读 README 获取详细用法
+大模型在需要了解 parser.py 的详细使用方式时，SHALL 阅读 `scripts/README.md` 文件。
+
+#### Scenario: 首次使用 skill 执行解析
+- **WHEN** 大模型首次使用 lyxy-reader-office skill 或不确定具体参数用法
+- **THEN** 大模型 SHALL 阅读 `scripts/README.md` 获取命令行参数、依赖安装和使用示例等详细信息
+
+#### Scenario: 遇到特殊参数需求
+- **WHEN** 用户请求使用特殊功能（如 PDF OCR、章节提取、正则搜索等）
+- **THEN** 大模型 SHALL 参考 `scripts/README.md` 中的对应参数说明
+
+### Requirement: 支持多格式文档解析
+系统 SHALL 支持 DOCX、PPTX、XLSX、PDF 四种格式的文档解析，将文件转换为 Markdown 格式输出。
+
+#### Scenario: 解析 DOCX 文件
+- **WHEN** 用户请求解析 .docx 文件
+- **THEN** 系统返回完整的 Markdown 格式文本
+- **AND** 保留标题、列表、表格、粗体、斜体等格式
+- **AND** 移除图片
+
+#### Scenario: 解析 PPTX 文件
+- **WHEN** 用户请求解析 .pptx 文件
+- **THEN** 系统返回完整的 Markdown 格式文本
+- **AND** 每张幻灯片以 `## Slide N` 为标题
+- **AND** 幻灯片之间以 `---` 分隔
+
+#### Scenario: 解析 XLSX 文件
+- **WHEN** 用户请求解析 .xlsx 文件
+- **THEN** 系统返回完整的 Markdown 格式文本
+- **AND** 以 `## SheetName` 区分工作表
+- **AND** 数据以 Markdown 表格呈现
+
+#### Scenario: 解析 PDF 文件
+- **WHEN** 用户请求解析 .pdf 文件
+- **THEN** 系统返回完整的 Markdown 格式文本
+- **AND** 默认使用普通文本提取模式
+
+#### Scenario: PDF OCR 高精度模式
+- **WHEN** 用户请求对 PDF 文件启用 OCR 或高精度解析
+- **THEN** 系统使用 `--high-res` 参数启用 OCR 版面分析
+- **AND** 通过 Docling OCR 或 unstructured hi_res 策略处理
+
+### Requirement: 统一的查询功能
+系统 SHALL 对所有支持的文件格式提供统一的查询接口，包括全文提取、元数据查询、标题提取、章节提取和正则搜索。
+
+#### Scenario: 获取文档字数
+- **WHEN** 用户请求获取文档的字数
+- **THEN** 系统使用 `-c` 参数返回文档的总字符数
+
+#### Scenario: 获取文档行数
+- **WHEN** 用户请求获取文档的行数
+- **THEN** 系统使用 `-l` 参数返回文档的总行数
+
+#### Scenario: 提取所有标题
+- **WHEN** 用户请求提取文档的标题结构
+- **THEN** 系统使用 `-t` 参数返回所有 1-6 级标题
+
+#### Scenario: 提取指定章节内容
+- **WHEN** 用户请求提取特定标题名称的章节内容
+- **THEN** 系统使用 `-tc` 参数返回该章节的完整内容
+- **AND** 包含完整的上级标题链和所有下级内容
+
+#### Scenario: 正则表达式搜索
+- **WHEN** 用户请求在文档中搜索关键词或模式
+- **THEN** 系统使用 `-s` 参数返回所有匹配结果及上下文
+- **AND** 默认包含前后各 2 行非空行上下文
+- **AND** 支持 `-n` 参数自定义上下文行数
+
+### Requirement: 多策略解析降级
+系统 SHALL 对每种文件格式按优先级尝试多种解析策略，确保最大的兼容性。
+
+#### Scenario: 解析器按优先级降级
+- **WHEN** 优先级最高的解析器不可用或解析失败
+- **THEN** 系统自动尝试下一优先级的解析器
+- **AND** 记录每个解析器的失败原因
+
+#### Scenario: 所有解析器失败
+- **WHEN** 某种格式的所有解析策略均失败
+- **THEN** 系统返回详细的失败信息
+- **AND** 列出每种解析策略的失败原因
+- **AND** 以退出码 1 退出
+
+#### Scenario: DOCX/PPTX/XLSX 无依赖运行
+- **WHEN** 未安装任何第三方解析库
+- **THEN** DOCX、PPTX、XLSX 文件 SHALL 仍可通过内置 XML 原生解析工作
+- **AND** PDF 至少需要 pypdf 才能解析
--- a/openspec/changes/archive/2026-02-17-create-lyxy-reader-office/tasks.md
+++ b/openspec/changes/archive/2026-02-17-create-lyxy-reader-office/tasks.md
@@ -0,0 +1,22 @@
+## 1. 创建 SKILL.md
+
+- [x] 1.1 创建 `skills/lyxy-reader-office/SKILL.md` 文件，包含符合规范的 YAML frontmatter（name、description、compatibility）
+- [x] 1.2 编写 SKILL.md 正文：Purpose 部分，说明 skill 用途及与 lyxy-runner-python 的协作关系（必须使用 lyxy-runner-python，不可用时降级到直接 Python 执行）
+- [x] 1.3 编写 SKILL.md 正文：When to Use 部分，列出典型场景、触发词和支持的文件扩展名（.docx、.xlsx、.pptx、.pdf）
+- [x] 1.4 编写 SKILL.md 正文：Capabilities 部分，概述四种格式的解析能力和统一查询功能（全文提取、元数据、标题、章节、搜索）
+- [x] 1.5 编写 SKILL.md 正文：Execution 部分，给出基本的执行命令格式，并引导大模型阅读 `scripts/README.md` 获取详细参数说明和依赖安装指南
+- [x] 1.6 编写 SKILL.md 正文：Examples 部分，给出各格式的基本使用示例
+- [x] 1.7 编写 SKILL.md 正文：Notes 部分，说明限制和注意事项
+- [x] 1.8 验证 SKILL.md 总行数不超过 500 行，符合渐进式披露原则
+
+## 2. 清理旧 Skill
+
+- [x] 2.1 删除 `skills/lyxy-reader-docx/` 整个目录（包含 SKILL.md、docx_parser.md、scripts/docx_parser.py）
+- [x] 2.2 检查项目中是否有其他位置引用了 `lyxy-reader-docx`（如 .claude/settings 配置），如有则清理引用
+
+## 3. 验证
+
+- [x] 3.1 确认 `skills/lyxy-reader-office/SKILL.md` 存在且 frontmatter 格式正确
+- [x] 3.2 确认 `skills/lyxy-reader-office/scripts/` 下所有脚本文件完整（parser.py、common.py、docx_parser.py、pptx_parser.py、xlsx_parser.py、pdf_parser.py、README.md）
+- [x] 3.3 确认 `skills/lyxy-reader-docx/` 目录已被删除
+- [x] 3.4 使用各格式的测试文件（temp/test.docx、temp/test.xlsx、temp/test.pptx、temp/test.pdf）验证 parser.py 可正常运行
--- a/openspec/specs/docx-text-extraction/spec.md
+++ b/openspec/specs/docx-text-extraction/spec.md
@@ -1,132 +0,0 @@
-## 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** 列出每种解析策略的失败原因
--- a/openspec/specs/office-document-parsing/spec.md
+++ b/openspec/specs/office-document-parsing/spec.md
@@ -0,0 +1,115 @@
+## Requirements
+
+### Requirement: 优先使用 lyxy-reader-office 解析办公文档
+大模型在遇到 .docx、.xlsx、.pptx、.pdf 文件时，SHALL 优先激活并使用 lyxy-reader-office skill 来读取文件内容。
+
+#### Scenario: 用户请求读取支持的文件格式
+- **WHEN** 用户请求读取或解析 .docx、.xlsx、.pptx 或 .pdf 文件
+- **THEN** 大模型 SHALL 激活 lyxy-reader-office skill
+- **AND** 使用 skill 目录下的 `scripts/parser.py` 执行解析
+
+#### Scenario: 文件扩展名自动识别
+- **WHEN** 用户提供的文件路径以 .docx、.xlsx、.pptx 或 .pdf 结尾
+- **THEN** 大模型 SHALL 自动识别为 lyxy-reader-office skill 的处理范围
+- **AND** 无需用户显式指定使用哪个 skill
+
+### Requirement: 必须通过 lyxy-runner-python 执行脚本
+当环境中存在 lyxy-runner-python skill 时，大模型 SHALL 必须使用该 skill 来运行 parser.py 脚本。
+
+#### Scenario: lyxy-runner-python 可用
+- **WHEN** 大模型环境中存在 lyxy-runner-python skill
+- **THEN** 大模型 SHALL 通过 lyxy-runner-python skill 执行 parser.py
+- **AND** 利用 lyxy-runner-python 的自动依赖管理功能（uv）安装所需的 Python 包
+
+#### Scenario: lyxy-runner-python 不可用
+- **WHEN** 大模型环境中不存在 lyxy-runner-python skill
+- **THEN** 大模型 SHALL 降级到直接使用 Python 执行 parser.py
+- **AND** 提示用户当前使用直接执行模式
+- **AND** 禁止自动执行 pip install 安装依赖
+
+### Requirement: 引导阅读 README 获取详细用法
+大模型在需要了解 parser.py 的详细使用方式时，SHALL 阅读 `scripts/README.md` 文件。
+
+#### Scenario: 首次使用 skill 执行解析
+- **WHEN** 大模型首次使用 lyxy-reader-office skill 或不确定具体参数用法
+- **THEN** 大模型 SHALL 阅读 `scripts/README.md` 获取命令行参数、依赖安装和使用示例等详细信息
+
+#### Scenario: 遇到特殊参数需求
+- **WHEN** 用户请求使用特殊功能（如 PDF OCR、章节提取、正则搜索等）
+- **THEN** 大模型 SHALL 参考 `scripts/README.md` 中的对应参数说明
+
+### Requirement: 支持多格式文档解析
+系统 SHALL 支持 DOCX、PPTX、XLSX、PDF 四种格式的文档解析，将文件转换为 Markdown 格式输出。
+
+#### Scenario: 解析 DOCX 文件
+- **WHEN** 用户请求解析 .docx 文件
+- **THEN** 系统返回完整的 Markdown 格式文本
+- **AND** 保留标题、列表、表格、粗体、斜体等格式
+- **AND** 移除图片
+
+#### Scenario: 解析 PPTX 文件
+- **WHEN** 用户请求解析 .pptx 文件
+- **THEN** 系统返回完整的 Markdown 格式文本
+- **AND** 每张幻灯片以 `## Slide N` 为标题
+- **AND** 幻灯片之间以 `---` 分隔
+
+#### Scenario: 解析 XLSX 文件
+- **WHEN** 用户请求解析 .xlsx 文件
+- **THEN** 系统返回完整的 Markdown 格式文本
+- **AND** 以 `## SheetName` 区分工作表
+- **AND** 数据以 Markdown 表格呈现
+
+#### Scenario: 解析 PDF 文件
+- **WHEN** 用户请求解析 .pdf 文件
+- **THEN** 系统返回完整的 Markdown 格式文本
+- **AND** 默认使用普通文本提取模式
+
+#### Scenario: PDF OCR 高精度模式
+- **WHEN** 用户请求对 PDF 文件启用 OCR 或高精度解析
+- **THEN** 系统使用 `--high-res` 参数启用 OCR 版面分析
+- **AND** 通过 Docling OCR 或 unstructured hi_res 策略处理
+
+### Requirement: 统一的查询功能
+系统 SHALL 对所有支持的文件格式提供统一的查询接口，包括全文提取、元数据查询、标题提取、章节提取和正则搜索。
+
+#### Scenario: 获取文档字数
+- **WHEN** 用户请求获取文档的字数
+- **THEN** 系统使用 `-c` 参数返回文档的总字符数
+
+#### Scenario: 获取文档行数
+- **WHEN** 用户请求获取文档的行数
+- **THEN** 系统使用 `-l` 参数返回文档的总行数
+
+#### Scenario: 提取所有标题
+- **WHEN** 用户请求提取文档的标题结构
+- **THEN** 系统使用 `-t` 参数返回所有 1-6 级标题
+
+#### Scenario: 提取指定章节内容
+- **WHEN** 用户请求提取特定标题名称的章节内容
+- **THEN** 系统使用 `-tc` 参数返回该章节的完整内容
+- **AND** 包含完整的上级标题链和所有下级内容
+
+#### Scenario: 正则表达式搜索
+- **WHEN** 用户请求在文档中搜索关键词或模式
+- **THEN** 系统使用 `-s` 参数返回所有匹配结果及上下文
+- **AND** 默认包含前后各 2 行非空行上下文
+- **AND** 支持 `-n` 参数自定义上下文行数
+
+### Requirement: 多策略解析降级
+系统 SHALL 对每种文件格式按优先级尝试多种解析策略，确保最大的兼容性。
+
+#### Scenario: 解析器按优先级降级
+- **WHEN** 优先级最高的解析器不可用或解析失败
+- **THEN** 系统自动尝试下一优先级的解析器
+- **AND** 记录每个解析器的失败原因
+
+#### Scenario: 所有解析器失败
+- **WHEN** 某种格式的所有解析策略均失败
+- **THEN** 系统返回详细的失败信息
+- **AND** 列出每种解析策略的失败原因
+- **AND** 以退出码 1 退出
+
+#### Scenario: DOCX/PPTX/XLSX 无依赖运行
+- **WHEN** 未安装任何第三方解析库
+- **THEN** DOCX、PPTX、XLSX 文件 SHALL 仍可通过内置 XML 原生解析工作
+- **AND** PDF 至少需要 pypdf 才能解析