From 277c14d2e867a44072a49ea6e8d978198be840cb Mon Sep 17 00:00:00 2001 From: lanyuanxiaoyao Date: Wed, 18 Mar 2026 22:54:51 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E7=AE=80=E5=8C=96=20SKILL.md=EF=BC=8C?= =?UTF-8?q?=E7=A7=BB=E9=99=A4=20lyxy-runner-python=20=E5=BC=95=E7=94=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新 compatibility 字段，移除三路径执行优先级说明 - 删除 "执行路径优先级" 章节，统一为脚本自启动方式 - 更新 openspec/skill-documentation spec，移除三路径执行策略需求 --- SKILL.md | 14 ++---- openspec/specs/skill-documentation/spec.md | 57 +++++++--------------- 2 files changed, 20 insertions(+), 51 deletions(-) diff --git a/SKILL.md b/SKILL.md index 7764511..99a54af 100644 --- a/SKILL.md +++ b/SKILL.md @@ -2,27 +2,19 @@ name: lyxy-document-reader description: 统一文档解析工具 - 将 DOC、DOCX、XLS、XLSX、PPT、PPTX、PDF、HTML/URL 转换为 Markdown。支持全文输出、字数统计、行数统计、标题提取、章节提取、正则搜索。当用户要求"读取/解析/打开文档"、上传 .doc/.docx/.xls/.xlsx/.ppt/.pptx/.pdf/.html 文件、或提供 URL 时使用。 license: MIT -compatibility: Requires Python 3.11+。优先使用 lyxy-runner-python skill，次选 uv run --with，降级到主机 Python。 +compatibility: Requires Python 3.11+。脚本自启动，自动检测依赖并使用 uv 执行。 --- # 统一文档解析 Skill -## 🔴 重要：执行路径优先级（必须遵守） +## 推荐用法 -### 执行路径选择（按优先级顺序） -1. **lyxy-runner-python skill（首选）** - 自动管理依赖 -2. **python scripts/lyxy_document_reader.py** - 自启动，自动检测依赖 -3. **uv run --with** - 手动指定依赖 -4. **主机 Python + pip install** - 手动安装依赖 +直接运行脚本即可，它会自动检测文件类型、当前平台，并用正确的 uv 命令执行： -### 推荐用法 ```bash -# 直接运行（自动检测依赖并执行） python scripts/lyxy_document_reader.py <文件路径或URL> ``` -脚本会自动检测文件类型、当前平台，并用正确的 uv 命令执行。 - ## Purpose **支持格式** diff --git a/openspec/specs/skill-documentation/spec.md b/openspec/specs/skill-documentation/spec.md index 398e9fa..af522ba 100644 --- a/openspec/specs/skill-documentation/spec.md +++ b/openspec/specs/skill-documentation/spec.md @@ -1,7 +1,7 @@ ## ADDED Requirements ### Requirement: SKILL.md 遵循 Claude Skill 构建指南 -SKILL.md 文档必须遵循 Claude 官方 Skill 构建指南的最佳实践，包括渐进式披露的三级系统、清晰的触发词和完整的章节结构。SKILL.md 必须将 --advice 参数作为首选方案放在最前面强调。 +SKILL.md 文档必须遵循 Claude 官方 Skill 构建指南的最佳实践，包括渐进式披露的三级系统、清晰的触发词和完整的章节结构。 #### Scenario: Claude 正确加载 skill - **WHEN** 用户询问与文档解析相关的问题 @@ -11,61 +11,38 @@ SKILL.md 文档必须遵循 Claude 官方 Skill 构建指南的最佳实践， - **WHEN** skill 被加载 - **THEN** AI 应能从 Purpose 和 When to Use 章节了解何时使用此 skill -#### Scenario: --advice 放在最前面 -- **WHEN** AI 查看 SKILL.md -- **THEN** Purpose 章节第一部分就是 --advice 的使用说明 - ### Requirement: YAML frontmatter 包含完整元数据 -YAML frontmatter 必须包含 name、description（带触发词）、license、metadata 和 compatibility 字段。 +YAML frontmatter 必须包含 name、description（带触发词）、license 和 compatibility 字段。 #### Scenario: description 包含触发词 - **WHEN** 查看 YAML frontmatter - **THEN** description 应包含功能说明、触发条件和用户可能说的具体任务 -#### Scenario: compatibility 说明依赖和执行路径优先级 +#### Scenario: compatibility 说明依赖和 Python 版本 - **WHEN** 查看 YAML frontmatter -- **THEN** compatibility 应说明 Python 版本要求和三种执行路径的优先级（lyxy-runner-python skill → uv → 主机 Python） +- **THEN** compatibility 应说明 Python 版本要求和脚本自启动特性 -### Requirement: 三路径执行策略 -skill 文档必须说明三种执行路径，优先级为：1. lyxy-runner-python skill，2. uv run --with，3. 主机 Python 环境。 +### Requirement: 推荐用法 +SKILL.md 必须说明直接运行 `python scripts/lyxy_document_reader.py` 即可，脚本会自动检测文件类型、当前平台，并用正确的 uv 命令执行。 -#### Scenario: lyxy-runner-python 可用 -- **WHEN** lyxy-runner-python skill 已安装 -- **THEN** 文档说明使用 lyxy-runner-python 自动管理依赖 +#### Scenario: 直接运行脚本 +- **WHEN** AI 需要执行文档解析 +- **THEN** 运行 `python scripts/lyxy_document_reader.py <文件路径或URL>` -#### Scenario: 使用 uv run --with -- **WHEN** lyxy-runner-python skill 不可用 -- **THEN** 文档说明使用 --advice 获取 uv run --with 命令 - -#### Scenario: 降级到主机 Python -- **WHEN** uv 也不可用 -- **THEN** 文档说明如何手动安装具体依赖包并使用主机 Python - -### Requirement: --advice 是首选方案 -SKILL.md 必须将 --advice 参数作为获取准确命令的首选方案，移除冗余的手动依赖命令示例块（仅保留简洁参考）。 - -#### Scenario: --advice 是第一步 -- **WHEN** AI 阅读 SKILL.md -- **THEN** 首先看到 --advice 的使用说明 - -#### Scenario: 依赖命令以 --advice 输出为准 -- **WHEN** AI 需要了解依赖命令 -- **THEN** 文档引导 AI 使用 --advice 获取，而非阅读文档中的示例 - -#### Scenario: 保留简洁参数示例 -- **WHEN** AI 需要了解参数用法 -- **THEN** 文档提供简洁的参数使用示例（不含大段依赖命令） +#### Scenario: 脚本自动检测 +- **WHEN** 运行脚本 +- **THEN** 脚本自动检测文件类型、当前平台，并用正确的 uv 命令执行 ### Requirement: 文档包含关键章节 -SKILL.md 必须包含 Purpose、When to Use、Quick Reference、Workflow 等章节，遵循渐进式披露原则。 +SKILL.md 必须包含 Purpose、When to Use、Quick Reference、参数使用示例等章节，遵循渐进式披露原则。 #### Scenario: 快速查找用法 - **WHEN** AI 需要了解如何使用此 skill - **THEN** Quick Reference 表格提供命令参数概览 -#### Scenario: 了解执行流程 -- **WHEN** AI 需要理解解析流程 -- **THEN** Workflow 章节说明 3 步工作流程（获取建议 → 选择执行方式 → 添加参数） +#### Scenario: 了解参数用法 +- **WHEN** AI 需要了解参数用法 +- **THEN** 参数使用示例章节提供简洁的命令示例 ### Requirement: 触发词覆盖多种表达方式 description 和 When to Use 章节必须包含中文和英文的触发词，以及文件扩展名。 @@ -83,7 +60,7 @@ description 和 When to Use 章节必须包含中文和英文的触发词，以 #### Scenario: 依赖缺失错误 - **WHEN** 出现 ModuleNotFoundError -- **THEN** 错误处理表格说明需要使用 --advice 获取正确的依赖命令 +- **THEN** 错误处理表格说明脚本会自动检测并安装依赖 #### Scenario: 文件类型不支持 - **WHEN** 出现"不支持的文件类型"错误