lyxy-document/openspec/specs/cli-advice/spec.md

Purpose

CLI 执行建议生成功能，根据文件类型返回 uv 和 python 命令，帮助 AI 快速获取准确的执行建议，无需翻阅文档。

Requirements

Requirement: 依赖配置结构

依赖配置必须同时包含 python 版本要求和依赖包列表，按文件类型和平台组织。

Scenario: 配置结构包含 python 和 dependencies

• WHEN 访问 config.DEPENDENCIES 时
• THEN 每个文件类型配置包含多个平台配置
• AND 每个平台配置包含 python 字段（可为 None）和 dependencies 列表字段

Scenario: default 平台配置

• WHEN 平台无特殊配置时
• THEN 使用 default 配置
• AND python 为 None 表示不需要指定 --python 参数

---

Requirement: CLI 支持 --advice 参数

命令行工具必须支持 -a/--advice 参数，当指定该参数时不执行实际解析，仅输出执行建议。

Scenario: 用户指定 --advice 参数

• WHEN 用户执行 scripts/lyxy_document_reader.py --advice <input_path>
• THEN 工具输出执行建议，不解析文件内容

---

Requirement: 轻量文件类型检测

--advice 参数必须复用 Reader 实例的 supports 方法识别文件类型，不打开文件。

Scenario: 复用 Reader 实例

• WHEN 检测文件类型时
• THEN 使用已实例化的 readers 列表
• AND 调用每个 reader 的 supports() 方法
• AND 根据第一个支持的 reader 类名识别文件类型

Scenario: 检测 PDF 文件

• WHEN 输入路径以 .pdf 结尾（不区分大小写）
• THEN PdfReader.supports() 返回 True
• AND 识别为 PDF 类型

Scenario: 检测 DOCX 文件

• WHEN 输入路径以 .docx 结尾（不区分大小写）
• THEN DocxReader.supports() 返回 True
• AND 识别为 DOCX 类型

Scenario: 检测 XLSX 文件

• WHEN 输入路径以 .xlsx 结尾（不区分大小写）
• THEN XlsxReader.supports() 返回 True
• AND 识别为 XLSX 类型

Scenario: 检测 PPTX 文件

• WHEN 输入路径以 .pptx 结尾（不区分大小写）
• THEN PptxReader.supports() 返回 True
• AND 识别为 PPTX 类型

Scenario: 检测 HTML 文件

• WHEN 输入路径以 .html 或 .htm 结尾（不区分大小写）
• THEN HtmlReader.supports() 返回 True
• AND 识别为 HTML 类型

Scenario: 检测 URL

• WHEN 输入路径以 http:// 或 https:// 开头
• THEN HtmlReader.supports() 返回 True
• AND 识别为 HTML 类型

Scenario: 不验证文件存在

• WHEN 输入路径指向不存在的文件
• THEN 仍根据 reader.supports() 返回建议，不报错

---

Requirement: 平台检测

必须检测当前平台并返回适配的命令。

Scenario: 检测平台格式

• WHEN 工具执行时
• THEN 返回格式为 {system}-{machine}，例如 Darwin-arm64、Linux-x86_64、Windows-AMD64

Scenario: macOS x86_64 PDF 特殊命令

• WHEN 平台为 Darwin-x86_64 且文件类型为 PDF
• THEN 返回包含 --python 3.12 和特定版本依赖的命令

---

Requirement: 输出 uv 命令

必须输出使用 uv run --with ... 格式的命令。

Scenario: 生成 uv 命令

• WHEN 检测到文件类型
• THEN 输出格式为：uv run [--python X.Y] --with <dep1> --with <dep2> ... scripts/lyxy_document_reader.py <input_path>

---

Requirement: 输出 python 命令

必须输出直接使用 python 的命令及 pip 安装命令。

Scenario: 生成 python 命令

• WHEN 检测到文件类型
• THEN 输出 python 命令：python scripts/lyxy_document_reader.py <input_path>
• AND 输出 pip 安装命令：pip install <dep1> <dep2> ...

---

Requirement: 输出格式规范

输出必须包含文件类型、输入路径、平台（如需要）、uv 命令、python 命令和 pip 安装命令。

Scenario: 普通平台输出格式

• WHEN 平台无特殊配置
• THEN 输出格式为：

  文件类型: <type>
  输入路径: <input>
  
  [uv 命令]
  <uv_command>
  
  [python 命令]
  python scripts/lyxy_document_reader.py <input>
  pip install <deps>
  

Scenario: 特殊平台输出格式

• WHEN 平台有特殊配置
• THEN 输出格式为：

  文件类型: <type>
  输入路径: <input>
  平台: <system-machine>
  
  [uv 命令]
  <uv_command>
  
  [python 命令]
  python scripts/lyxy_document_reader.py <input>
  pip install <deps>