diff --git a/README.md b/README.md index f2ca4e7..e9cd36d 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,39 @@ uv run mypy . - 错误处理：自定义异常 + 清晰信息 + 位置上下文 - Git 提交：类型: 简短描述（feat/fix/refactor/docs/style/test/chore） +## Skill 文档规范 + +skill/SKILL.md 面向 AI 用户，必须遵循 Claude Skill 构建指南的最佳实践： + +### YAML frontmatter + +- **name**: kebab-case 格式 +- **description**: 包含功能说明、触发词、文件类型、典型任务 +- **license**: MIT +- **metadata**: 包含 version、author +- **compatibility**: 说明 Python 版本要求和依赖情况 + +### 文档章节结构 + +1. **Purpose**: 说明统一入口和双路径执行策略 +2. **When to Use**: 典型场景和触发词列表（中英文、文件扩展名） +3. **Quick Reference**: 命令参数表格 +4. **Workflow**: 4 步工作流程（检测环境、识别类型、执行解析、输出结果） +5. **使用示例**: 各文档类型的基本用法和高级用法 +6. **错误处理**: 常见错误及解决方案 +7. **References**: 指向项目文档的链接 + +### 双路径执行策略 + +- **优先**: 使用 lyxy-runner-python skill（自动管理依赖） +- **回退**: 主机 Python 环境（需手动安装依赖） + +### 依赖说明 + +- 必须使用具体的 pip 包名 +- 不能使用 lyxy-document[xxx] 形式（发布时没有 pyproject.toml） +- 按文档类型分组说明 + ## 解析器架构 ### DOCX diff --git a/openspec/specs/skill-documentation/spec.md b/openspec/specs/skill-documentation/spec.md new file mode 100644 index 0000000..8cc9297 --- /dev/null +++ b/openspec/specs/skill-documentation/spec.md @@ -0,0 +1,78 @@ +## ADDED Requirements + +### Requirement: SKILL.md 遵循 Claude Skill 构建指南 +SKILL.md 文档必须遵循 Claude 官方 Skill 构建指南的最佳实践，包括渐进式披露的三级系统、清晰的触发词和完整的章节结构。 + +#### Scenario: Claude 正确加载 skill +- **WHEN** 用户询问与文档解析相关的问题 +- **THEN** Claude 应根据 YAML frontmatter 中的触发词自动加载此 skill + +#### Scenario: AI 了解 skill 的用途 +- **WHEN** skill 被加载 +- **THEN** AI 应能从 Purpose 和 When to Use 章节了解何时使用此 skill + +### Requirement: YAML frontmatter 包含完整元数据 +YAML frontmatter 必须包含 name、description（带触发词）、license、metadata 和 compatibility 字段。 + +#### Scenario: description 包含触发词 +- **WHEN** 查看 YAML frontmatter +- **THEN** description 应包含功能说明、触发条件和用户可能说的具体任务 + +#### Scenario: compatibility 说明依赖 +- **WHEN** 查看 YAML frontmatter +- **THEN** compatibility 应说明 Python 版本要求和两种执行路径的依赖情况 + +### Requirement: 双路径执行策略 +skill 文档必须说明两种执行路径：优先使用 lyxy-runner-python skill，回退到主机 Python 环境。 + +#### Scenario: lyxy-runner-python 可用 +- **WHEN** lyxy-runner-python skill 已安装 +- **THEN** 文档说明使用 lyxy-runner-python 自动管理依赖 + +#### Scenario: lyxy-runner-python 不可用 +- **WHEN** lyxy-runner-python skill 不可用 +- **THEN** 文档说明如何手动安装具体依赖包并使用主机 Python + +### Requirement: 依赖说明使用具体包名 +文档必须列出每个文档类型需要的具体 pip 包名，不能使用 lyxy-document[xxx] 形式（因为发布时没有 pyproject.toml）。 + +#### Scenario: 用户安装 DOCX 依赖 +- **WHEN** 用户需要解析 DOCX 文档 +- **THEN** 文档列出具体命令：pip install docling unstructured markitdown pypandoc-binary python-docx markdownify chardet + +#### Scenario: 用户安装 PDF 依赖 +- **WHEN** 用户需要解析 PDF 文档 +- **THEN** 文档列出具体命令：pip install docling unstructured unstructured-paddleocr markitdown pypdf markdownify chardet + +### Requirement: 文档包含关键章节 +SKILL.md 必须包含 Purpose、When to Use、Quick Reference、Workflow 等章节，遵循渐进式披露原则。 + +#### Scenario: 快速查找用法 +- **WHEN** AI 需要了解如何使用此 skill +- **THEN** Quick Reference 表格提供命令参数概览 + +#### Scenario: 了解执行流程 +- **WHEN** AI 需要理解解析流程 +- **THEN** Workflow 章节说明 4 步工作流程 + +### Requirement: 触发词覆盖多种表达方式 +description 和 When to Use 章节必须包含中文和英文的触发词，以及文件扩展名。 + +#### Scenario: 中文触发词 +- **WHEN** 用户说"读取文档"、"解析 Word"、"打开 PDF"等 +- **THEN** skill 应被触发 + +#### Scenario: 文件扩展名触发 +- **WHEN** 用户上传 .docx、.xlsx、.pptx、.pdf、.html 文件 +- **THEN** skill 应被触发 + +### Requirement: 错误处理指引 +文档必须包含常见错误的处理方法，帮助用户排查问题。 + +#### Scenario: 依赖缺失错误 +- **WHEN** 出现 ModuleNotFoundError +- **THEN** 错误处理表格说明需要安装对应的依赖包 + +#### Scenario: 文件类型不支持 +- **WHEN** 出现"不支持的文件类型"错误 +- **THEN** 错误处理表格说明检查文件扩展名 diff --git a/skill/SKILL.md b/skill/SKILL.md index a8afe16..8cfe0ce 100644 --- a/skill/SKILL.md +++ b/skill/SKILL.md @@ -1,120 +1,150 @@ --- name: lyxy-document-reader -description: 统一文档解析工具 - DOCX/XLSX/PPTX/PDF/HTML/URL 转 Markdown +description: 统一文档解析工具 - 将 DOCX、XLSX、PPTX、PDF、HTML/URL 转换为 Markdown。支持全文输出、字数统计、行数统计、标题提取、章节提取、正则搜索。当用户要求"读取/解析/打开文档"、上传 .docx/.xlsx/.pptx/.pdf/.html 文件、或提供 URL 时使用。 license: MIT metadata: version: "1.0" + author: lyxy +compatibility: Requires Python 3.11+. 优先使用 lyxy-runner-python skill 执行（自动管理依赖）。回退到主机 Python 时需手动安装依赖：DOCX(docling unstructured markitdown pypandoc-binary python-docx markdownify chardet) / XLSX(docling unstructured markitdown pandas tabulate chardet) / PPTX(docling unstructured markitdown python-pptx markdownify chardet) / PDF(docling unstructured unstructured-paddleocr markitdown pypdf markdownify chardet) / HTML(trafilatura domscribe markitdown html2text beautifulsoup4 httpx chardet) / HTTP增强(pyppeteer selenium) --- -# 快速开始 +# 统一文档解析 Skill -```bash -# 基本解析 -uv run lyxy-document-reader document.docx +将 DOCX、XLSX、PPTX、PDF、HTML 文件或 URL 网页内容解析为 Markdown 格式，支持多种查询模式。 -# URL 解析 -uv run lyxy-document-reader https://example.com -``` +## Purpose -# 命令选项 +**统一入口**：使用 `scripts/lyxy_document_reader.py` 作为统一的命令行入口，自动识别文件类型并执行解析。 -## 基本参数 +**双路径执行**：此 skill 必须优先使用 **lyxy-runner-python skill** 执行脚本，该 skill 会自动管理 uv 隔离环境和依赖。当 lyxy-runner-python 不可用时，回退到主机 Python 环境执行。 -- `input_path`：文件路径或 URL（必需） +**支持的文档类型**： +- **DOCX**：Word 文档 +- **XLSX**：Excel 表格 +- **PPTX**：PowerPoint 演示文稿 +- **PDF**：PDF 文档（支持 OCR） +- **HTML/URL**：HTML 文件或网页地址 -## 互斥操作（选其一） +## When to Use -| 选项 | 说明 | +任何需要读取或解析 Office 文档、PDF、HTML 文件、URL 网页内容的任务都应使用此 skill。 + +### 典型场景 +- **文档转换**：将各类文档转换为可读的 Markdown 文本 +- **文档元数据**：获取文档的字数、行数等信息 +- **标题分析**：提取文档的标题结构 +- **章节提取**：提取特定章节的内容 +- **内容搜索**：在文档中搜索关键词或正则模式 + +### 触发词 +- **中文**："读取/解析/打开 文档/Word/Excel/PPT/PDF/网页" +- **英文**："read/parse/extract document/docx/xlsx/pptx/pdf/html" +- **文件扩展名**：`.docx`、`.xlsx`、`.pptx`、`.pdf`、`.html`、`.htm` +- **URL 模式**：`http://`、`https://` + +## Quick Reference + +| 参数 | 说明 | |------|------| -| 无 | 输出完整 Markdown | -| `-c` / `--count` | 统计字数 | -| `-l` / `--lines` | 统计行数 | +| （无参数） | 输出完整 Markdown 内容 | +| `-c` / `--count` | 字数统计 | +| `-l` / `--lines` | 行数统计 | | `-t` / `--titles` | 提取所有标题（1-6级） | -| `-tc ` | 提取指定标题及其内容 | -| `-s ` | 正则搜索 | +| `-tc ` | 提取指定标题的章节内容 | +| `-s ` | 正则表达式搜索 | +| `-n ` / `--context ` | 与 `-s` 配合，指定上下文行数（默认2） | -## 辅助选项 +## Workflow -| 选项 | 说明 | 配合 | -|------|------|------| -| `-n ` / `--context ` | 搜索结果上下文行数（默认2） | `-s` | +1. **检测执行环境**： + - 优先检测 **lyxy-runner-python skill** 是否可用 + - 可用 → 使用 uv 隔离环境执行 + - 不可用 → 回退到主机 Python 环境 -# 按文档类型使用 +2. **识别文件类型**： + - 根据文件扩展名自动选择对应的解析器 + - URL 自动识别为 HTML/网页类型 -## DOCX +3. **执行解析**： + - 按优先级尝试多个解析器，直到成功 + - DOCX：docling → unstructured → pypandoc → MarkItDown → python-docx → XML + - XLSX：docling → unstructured → MarkItDown → pandas → XML + - PPTX：docling → unstructured → MarkItDown → python-pptx → XML + - PDF：docling OCR → unstructured OCR → docling → unstructured → MarkItDown → pypdf + - HTML：trafilatura → domscribe → MarkItDown → html2text + +4. **输出结果**： + - 返回 Markdown 格式内容或统计信息 + +### 基本语法 ```bash -uv run lyxy-document-reader file.docx +# 方式 1：使用 lyxy-runner-python（推荐） +# lyxy-runner-python 会自动分析脚本依赖并使用 uv --with 安装 +# AI 只需执行： +python scripts/lyxy_document_reader.py <文件路径或URL> + +# 方式 2：回退到主机 Python（需要预先手动安装依赖） +# 根据文档类型安装对应依赖后执行： +python scripts/lyxy_document_reader.py <文件路径或URL> ``` -## PDF +### 使用示例 ```bash -uv run lyxy-document-reader file.pdf -``` +# 读取 Word 文档 +python scripts/lyxy_document_reader.py document.docx -## HTML/URL +# 解析网页内容 +python scripts/lyxy_document_reader.py https://example.com -```bash -# 本地文件 -uv run lyxy-document-reader page.html +# 统计字数 +python scripts/lyxy_document_reader.py document.docx -c -# URL -uv run lyxy-document-reader https://example.com -``` +# 提取所有标题 +python scripts/lyxy_document_reader.py document.docx -t -## XLSX +# 提取指定章节 +python scripts/lyxy_document_reader.py document.docx -tc "第三章" -```bash -uv run lyxy-document-reader file.xlsx -``` +# 搜索内容 +python scripts/lyxy_document_reader.py document.docx -s "关键词" -## PPTX - -```bash -uv run lyxy-document-reader file.pptx -``` - -# 高级用法 - -## 搜索内容 - -```bash -# 搜索关键词 -uv run lyxy-document-reader file.docx -s "关键词" +# 正则搜索 +python scripts/lyxy_document_reader.py document.docx -s "\d{4}-\d{2}-\d{2}" # 指定上下文行数 -uv run lyxy-document-reader file.docx -s "关键词" -n 5 - -# 正则表达式 -uv run lyxy-document-reader file.docx -s "\d{4}-\d{2}-\d{2}" +python scripts/lyxy_document_reader.py document.docx -s "关键词" -n 5 ``` -## 提取标题 +### 主机 Python 环境依赖安装 + +当 lyxy-runner-python 不可用时，需要根据文档类型手动安装依赖： ```bash -# 列出所有标题 -uv run lyxy-document-reader file.docx -t +# DOCX 文档 +pip install docling unstructured markitdown pypandoc-binary python-docx markdownify chardet -# 提取指定标题内容 -uv run lyxy-document-reader file.docx -tc "第三章" +# XLSX 表格 +pip install docling unstructured markitdown pandas tabulate chardet + +# PPTX 演示文稿 +pip install docling unstructured markitdown python-pptx markdownify chardet + +# PDF 文档 +pip install docling unstructured unstructured-paddleocr markitdown pypdf markdownify chardet + +# HTML/URL 网页 +pip install trafilatura domscribe markitdown html2text beautifulsoup4 httpx chardet + +# 网页（需要 JS 渲染时，额外添加） +pip install pyppeteer selenium + +# 安装所有文档类型支持 +pip install docling unstructured unstructured-paddleocr markitdown pypandoc-binary python-docx python-pptx pandas tabulate pypdf markdownify trafilatura domscribe html2text beautifulsoup4 httpx pyppeteer selenium chardet ``` -# Python API - -```python -from scripts.core import parse_input, process_content -from scripts.readers import READERS - -readers = [ReaderCls() for ReaderCls in READERS] -content, failures = parse_input("document.docx", readers) - -if content: - content = process_content(content) - print(content) -``` - -# 错误处理 +## 错误处理 | 错误信息 | 原因 | 解决 | |---------|------|------| @@ -123,3 +153,12 @@ if content: | 所有解析方法均失败 | 所有解析器失败 | 检查文件是否损坏 | | 错误: 无效的正则表达式 | 正则语法错误 | 检查正则语法 | | 错误: 未找到匹配 | 搜索无结果 | 检查搜索词或正则 | +| ModuleNotFoundError: No module named 'xxx' | 缺少依赖 | 使用 lyxy-runner-python 或 pip 安装对应依赖 | + +## References + +详细文档请参阅项目文件： +- 依赖声明：`pyproject.toml` +- 代码结构：`scripts/` 目录 +- 项目规范：`openspec/config.yaml` +- 开发文档：`README.md`