feat: 添加 --advice 参数，支持快速获取执行建议
- 新增 scripts/core/advice_generator.py 建议生成器模块 - 在 config.py 中添加 DEPENDENCIES 依赖配置 - 在 lyxy_document_reader.py 中添加 -a/--advice 参数 - 复用 Reader 实例的 supports 方法检测文件类型 - 支持平台检测，对 macOS x86_64 PDF 返回特殊命令 - 添加单元测试和集成测试 - 更新 SKILL.md，引导优先使用 --advice 参数 - 更新 README.md，添加项目结构说明 - 添加 openspec/specs/cli-advice/spec.md 规范文档
This commit is contained in:
106
SKILL.md
106
SKILL.md
@@ -5,7 +5,7 @@ license: MIT
|
||||
metadata:
|
||||
version: "1.0"
|
||||
author: lyxy
|
||||
compatibility: Requires Python 3.11+. 使用 uv run --with 方式按需加载依赖，详见"依赖安装指南"章节。
|
||||
compatibility: Requires Python 3.11+. 使用 uv run --with 方式按需加载依赖。
|
||||
---
|
||||
|
||||
# 统一文档解析 Skill
|
||||
@@ -16,7 +16,7 @@ compatibility: Requires Python 3.11+. 使用 uv run --with 方式按需加载依
|
||||
|
||||
**统一入口**：使用 `scripts/lyxy_document_reader.py` 作为统一的命令行入口，自动识别文件类型并执行解析。
|
||||
|
||||
**依赖管理**：使用 `uv run --with` 方式按需加载解析器依赖。每次执行时根据文档类型指定对应的依赖包。
|
||||
**快速获取建议（必须优先使用）**：使用 `-a/--advice` 参数获取准确的执行建议，包含 `uv run --with ...` 命令和 `python` 命令，无需阅读此文档的后续内容。
|
||||
|
||||
**支持的文档类型**：
|
||||
- **DOCX**：Word 文档
|
||||
@@ -46,6 +46,7 @@ compatibility: Requires Python 3.11+. 使用 uv run --with 方式按需加载依
|
||||
|
||||
| 参数 | 说明 |
|
||||
|------|------|
|
||||
| `-a` / `--advice` | 仅显示执行建议，不实际解析文件（必须优先使用） |
|
||||
| （无参数） | 输出完整 Markdown 内容 |
|
||||
| `-c` / `--count` | 字数统计 |
|
||||
| `-l` / `--lines` | 行数统计 |
|
||||
@@ -56,41 +57,30 @@ compatibility: Requires Python 3.11+. 使用 uv run --with 方式按需加载依
|
||||
|
||||
## Workflow
|
||||
|
||||
0. **获取执行建议（必须优先执行）**：
|
||||
```bash
|
||||
python scripts/lyxy_document_reader.py --advice <文件路径或URL>
|
||||
```
|
||||
- 根据建议中的命令执行即可，无需继续阅读后续内容
|
||||
|
||||
1. **检测执行环境**：
|
||||
- 优先检测 **lyxy-runner-python skill** 是否可用
|
||||
- 可用 → 使用 uv 隔离环境执行
|
||||
- 可用 → 使用 lyxy-runner-python skill 执行
|
||||
- 不可用 → 回退到主机 Python 环境
|
||||
|
||||
2. **识别文件类型**：
|
||||
- 根据文件扩展名自动选择对应的解析器
|
||||
- URL 自动识别为 HTML/网页类型
|
||||
|
||||
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. **输出结果**：
|
||||
3. **输出结果**：
|
||||
- 返回 Markdown 格式内容或统计信息
|
||||
|
||||
### 基本语法
|
||||
|
||||
使用 `uv run --with` 按需加载依赖包：
|
||||
|
||||
```bash
|
||||
# 根据文档类型选择对应的依赖包
|
||||
uv run --with <依赖包1> --with <依赖包2> ... \
|
||||
scripts/lyxy_document_reader.py <文件路径或URL>
|
||||
```
|
||||
|
||||
具体的依赖包列表请参考下方的"依赖安装指南"。
|
||||
|
||||
### 使用示例
|
||||
|
||||
```bash
|
||||
# 获取执行建议（必须优先执行此命令）
|
||||
python scripts/lyxy_document_reader.py --advice document.docx
|
||||
|
||||
# 读取 Word 文档
|
||||
python scripts/lyxy_document_reader.py document.docx
|
||||
|
||||
@@ -116,74 +106,6 @@ python scripts/lyxy_document_reader.py document.docx -s "\d{4}-\d{2}-\d{2}"
|
||||
python scripts/lyxy_document_reader.py document.docx -s "关键词" -n 5
|
||||
```
|
||||
|
||||
### 依赖安装指南
|
||||
|
||||
使用 `uv run --with` 方式按需加载解析器依赖。以下命令适用于大多数平台（macOS ARM、Linux、Windows）。
|
||||
|
||||
#### 平台检测
|
||||
|
||||
在遇到问题时，可以检测你的平台：
|
||||
|
||||
```bash
|
||||
# macOS / Linux
|
||||
uname -m # 显示架构: x86_64 或 arm64
|
||||
uname -s # 显示系统: Darwin 或 Linux
|
||||
|
||||
# Windows PowerShell
|
||||
$env:OS # 或检查环境变量
|
||||
|
||||
# Python 跨平台检测
|
||||
python -c "import platform; print(f'{platform.system()}-{platform.machine()}')"
|
||||
```
|
||||
|
||||
#### PDF 解析
|
||||
|
||||
**默认命令**（适用于 macOS ARM、Linux、Windows）：
|
||||
|
||||
```bash
|
||||
uv run --with docling --with "unstructured[pdf]" --with "markitdown[pdf]" --with pypdf --with markdownify --with chardet scripts/lyxy_document_reader.py file.pdf
|
||||
```
|
||||
|
||||
**macOS x86_64 (Intel) 特殊说明**：
|
||||
|
||||
此平台需要使用 Python 3.12 和特定版本的依赖：
|
||||
|
||||
```bash
|
||||
uv run --python 3.12 --with "docling==2.40.0" --with "docling-parse==4.0.0" --with "numpy<2" --with "markitdown[pdf]" --with pypdf --with markdownify --with chardet scripts/lyxy_document_reader.py file.pdf
|
||||
```
|
||||
|
||||
原因：`docling-parse` 5.x 无 x86_64 wheel，必须使用 4.0.0；`easyocr`（docling 的 OCR 后端）与 NumPy 2.x 不兼容。
|
||||
|
||||
#### DOCX 解析
|
||||
|
||||
```bash
|
||||
uv run --with docling --with "unstructured[docx]" --with "markitdown[docx]" --with pypandoc-binary --with python-docx --with markdownify --with chardet scripts/lyxy_document_reader.py file.docx
|
||||
```
|
||||
|
||||
#### XLSX 解析
|
||||
|
||||
```bash
|
||||
uv run --with docling --with "unstructured[xlsx]" --with "markitdown[xlsx]" --with pandas --with tabulate --with chardet scripts/lyxy_document_reader.py file.xlsx
|
||||
```
|
||||
|
||||
#### PPTX 解析
|
||||
|
||||
```bash
|
||||
uv run --with docling --with "unstructured[pptx]" --with "markitdown[pptx]" --with python-pptx --with markdownify --with chardet scripts/lyxy_document_reader.py file.pptx
|
||||
```
|
||||
|
||||
#### HTML/URL 解析
|
||||
|
||||
```bash
|
||||
uv run --with trafilatura --with domscribe --with markitdown --with html2text --with beautifulsoup4 --with httpx --with chardet scripts/lyxy_document_reader.py https://example.com
|
||||
```
|
||||
|
||||
**需要 JavaScript 渲染的网页**，额外添加：
|
||||
|
||||
```bash
|
||||
--with pyppeteer --with selenium
|
||||
```
|
||||
|
||||
## 错误处理
|
||||
|
||||
| 错误信息 | 原因 | 解决 |
|
||||
|
||||
Reference in New Issue
Block a user