lanyuanxiaoyao
aaa1171e60
- 新增 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 规范文档
141 lines
4.4 KiB
Markdown
141 lines
4.4 KiB
Markdown
## 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>
|
||
```
|