Files

lanyuanxiaoyao aaa1171e60 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 规范文档

2026-03-09 18:13:00 +08:00

4.4 KiB

Raw Blame History

name, description, license, metadata, compatibility

name

description

license

metadata

compatibility

lyxy-document-reader

统一文档解析工具 - 将 DOCX、XLSX、PPTX、PDF、HTML/URL 转换为 Markdown。支持全文输出、字数统计、行数统计、标题提取、章节提取、正则搜索。当用户要求"读取/解析/打开文档"、上传 .docx/.xlsx/.pptx/.pdf/.html 文件、或提供 URL 时使用。

MIT

version	author
1.0	lyxy

Requires Python 3.11+. 使用 uv run --with 方式按需加载依赖。

统一文档解析 Skill

将 DOCX、XLSX、PPTX、PDF、HTML 文件或 URL 网页内容解析为 Markdown 格式，支持多种查询模式。

Purpose

统一入口：使用 scripts/lyxy_document_reader.py 作为统一的命令行入口，自动识别文件类型并执行解析。

快速获取建议（必须优先使用）：使用 -a/--advice 参数获取准确的执行建议，包含 uv run --with ... 命令和 python 命令，无需阅读此文档的后续内容。

支持的文档类型：

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

参数	说明
`-a` / `--advice`	仅显示执行建议，不实际解析文件（必须优先使用）
（无参数）	输出完整 Markdown 内容
`-c` / `--count`	字数统计
`-l` / `--lines`	行数统计
`-t` / `--titles`	提取所有标题（1-6级）
`-tc <name>`	提取指定标题的章节内容
`-s <pattern>`	正则表达式搜索
`-n <num>` / `--context <num>`	与 `-s` 配合，指定上下文行数（默认2）

Workflow

获取执行建议（必须优先执行）：
```
python scripts/lyxy_document_reader.py --advice <文件路径或URL>
```
- 根据建议中的命令执行即可，无需继续阅读后续内容
检测执行环境：
- 优先检测 lyxy-runner-python skill 是否可用
- 可用 → 使用 lyxy-runner-python skill 执行
- 不可用 → 回退到主机 Python 环境
识别文件类型：
- 根据文件扩展名自动选择对应的解析器
- URL 自动识别为 HTML/网页类型
输出结果：
- 返回 Markdown 格式内容或统计信息

使用示例

# 获取执行建议（必须优先执行此命令）
python scripts/lyxy_document_reader.py --advice document.docx

# 读取 Word 文档
python scripts/lyxy_document_reader.py document.docx

# 解析网页内容
python scripts/lyxy_document_reader.py https://example.com

# 统计字数
python scripts/lyxy_document_reader.py document.docx -c

# 提取所有标题
python scripts/lyxy_document_reader.py document.docx -t

# 提取指定章节
python scripts/lyxy_document_reader.py document.docx -tc "第三章"

# 搜索内容
python scripts/lyxy_document_reader.py document.docx -s "关键词"

# 正则搜索
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

错误处理

错误信息	原因	解决
错误: input_path 不能为空	未提供输入	提供 file_path 或 URL
错误: 不支持的文件类型	无对应 reader	检查文件扩展名
所有解析方法均失败	所有解析器失败	检查文件是否损坏
错误: 无效的正则表达式	正则语法错误	检查正则语法
错误: 未找到匹配	搜索无结果	检查搜索词或正则
ModuleNotFoundError: No module named 'xxx'	缺少依赖	使用 lyxy-runner-python 或 pip 安装对应依赖

4.4 KiB Raw Blame History Unescape Escape