lanyuanxiaoyao/lyxy-document
1
0
Fork 0
Code Releases Activity
Files
c90e1c98bec2dd72d86072f3573aef9aa8ae600e
lyxy-document/openspec/specs/skill-documentation/spec.md
lanyuanxiaoyao 25d748aa17 docs: 重构 README.md 和 SKILL.md，明确文档职责 
- README.md 面向开发者：添加项目概述、核心概念说明、开发指南
- SKILL.md 面向 AI：强化 --advice 作为首选方案，明确三路径执行优先级
- 更新 specs：skill-documentation 和 uv-with-dependency-management
- README 添加 reportlab 测试依赖
2026-03-09 21:56:58 +08:00

3.9 KiB
Raw Blame History

ADDED Requirements

Requirement: SKILL.md 遵循 Claude Skill 构建指南

SKILL.md 文档必须遵循 Claude 官方 Skill 构建指南的最佳实践，包括渐进式披露的三级系统、清晰的触发词和完整的章节结构。SKILL.md 必须将 --advice 参数作为首选方案放在最前面强调。

Scenario: Claude 正确加载 skill

  • WHEN 用户询问与文档解析相关的问题
  • THEN Claude 应根据 YAML frontmatter 中的触发词自动加载此 skill

Scenario: AI 了解 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 字段。

Scenario: description 包含触发词

  • WHEN 查看 YAML frontmatter
  • THEN description 应包含功能说明、触发条件和用户可能说的具体任务

Scenario: compatibility 说明依赖和执行路径优先级

  • WHEN 查看 YAML frontmatter
  • THEN compatibility 应说明 Python 版本要求和三种执行路径的优先级（lyxy-runner-python skill → uv → 主机 Python）

Requirement: 三路径执行策略

skill 文档必须说明三种执行路径，优先级为：1. lyxy-runner-python skill，2. uv run --with，3. 主机 Python 环境。

Scenario: lyxy-runner-python 可用

  • WHEN lyxy-runner-python skill 已安装
  • THEN 文档说明使用 lyxy-runner-python 自动管理依赖

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 文档提供简洁的参数使用示例（不含大段依赖命令）

Requirement: 文档包含关键章节

SKILL.md 必须包含 Purpose、When to Use、Quick Reference、Workflow 等章节，遵循渐进式披露原则。

Scenario: 快速查找用法

  • WHEN AI 需要了解如何使用此 skill
  • THEN Quick Reference 表格提供命令参数概览

Scenario: 了解执行流程

  • WHEN AI 需要理解解析流程
  • THEN Workflow 章节说明 3 步工作流程（获取建议 → 选择执行方式 → 添加参数）

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 错误处理表格说明需要使用 --advice 获取正确的依赖命令

Scenario: 文件类型不支持

  • WHEN 出现"不支持的文件类型"错误
  • THEN 错误处理表格说明检查文件扩展名
View Git Blame Copy Permalink