docs: 优化 skill 文档并添加更新原则

优化 skill/SKILL.md 遵循 Claude Skill 构建指南： - 重写 YAML frontmatter，添加触发词和 compatibility 字段 - 新增 Purpose、When to Use、Quick Reference、Workflow 章节 - 说明双路径执行策略（lyxy-runner-python 优先，回退主机 Python） - 修正依赖说明，使用具体 pip 包名在 README.md 中添加 Skill 文档规范章节，明确更新原则新增 openspec/specs/skill-documentation/ 规范文件
2026-03-08 18:43:07 +08:00
parent 8063e24f99
commit c35bbc90b5
3 changed files with 226 additions and 76 deletions
--- 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
--- a/openspec/specs/skill-documentation/spec.md
+++ 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** 错误处理表格说明检查文件扩展名
--- 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 <name>` | 提取指定标题及其内容 |
-| `-s <pattern>` | 正则搜索 |
+| `-tc <name>` | 提取指定标题的章节内容 |
+| `-s <pattern>` | 正则表达式搜索 |
+| `-n <num>` / `--context <num>` | 与 `-s` 配合，指定上下文行数（默认2） |

-## 辅助选项
+## Workflow

-| 选项 | 说明 | 配合 |
-|------|------|------|
-| `-n <num>` / `--context <num>` | 搜索结果上下文行数（默认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`