77 lines
4.2 KiB
Markdown
77 lines
4.2 KiB
Markdown
## Context
|
||
|
||
当前项目中存在 `lyxy-reader-docx` skill，仅支持 DOCX 格式的文档解析。`skills/lyxy-reader-office/scripts/` 目录下已完成全部解析脚本的开发（parser.py、common.py、docx_parser.py、pptx_parser.py、xlsx_parser.py、pdf_parser.py、README.md），支持 DOCX、PPTX、XLSX、PDF 四种格式。现在需要创建 `SKILL.md` 作为 skill 的入口文件，并清理被替代的旧 skill。
|
||
|
||
已有资源：
|
||
- `skills/lyxy-reader-docx/SKILL.md`：参考模板，已验证的 skill 结构
|
||
- `skills/lyxy-runner-python/SKILL.md`：Python 执行 skill，与本 skill 协作
|
||
- `skills/lyxy-reader-office/scripts/README.md`：完整的脚本使用文档
|
||
- `document/specification.md`：skill 格式规范
|
||
|
||
## Goals / Non-Goals
|
||
|
||
**Goals:**
|
||
|
||
- 创建 `skills/lyxy-reader-office/SKILL.md`，遵循 skill 格式规范
|
||
- SKILL.md 的 description 能覆盖 .docx、.xlsx、.pptx、.pdf 四种文件扩展名关键词，确保大模型在发现阶段能正确匹配
|
||
- 引导大模型优先使用该 skill 读取这四种格式的文件
|
||
- 引导大模型阅读 `scripts/README.md` 获取详细的脚本使用说明
|
||
- 引导大模型在 `lyxy-runner-python` skill 可用时必须使用该 skill 来运行 Python 脚本
|
||
- 删除 `skills/lyxy-reader-docx` 目录
|
||
|
||
**Non-Goals:**
|
||
|
||
- 不修改已有的解析脚本代码
|
||
- 不修改 `lyxy-runner-python` skill
|
||
- 不新增任何解析功能
|
||
- 不创建单独的文档说明文件（如旧 skill 的 `docx_parser.md`），详细用法通过引导阅读 README.md 解决
|
||
|
||
## Decisions
|
||
|
||
### 决策 1：SKILL.md 结构参考 lyxy-reader-docx 但大幅精简
|
||
|
||
**选择**：SKILL.md 专注于发现（description）、激活引导（何时使用、触发条件）和执行入口（指向 README.md），不在 SKILL.md 中重复 README.md 的内容。
|
||
|
||
**理由**：
|
||
- 规范建议 SKILL.md 保持在 500 行以下
|
||
- README.md 已包含完整的命令行用法、参数说明、安装指南、错误处理等
|
||
- 重复内容会导致维护负担，且增加不必要的 token 消耗
|
||
- 渐进式披露：SKILL.md 负责激活判断，README.md 负责执行细节
|
||
|
||
**替代方案**：将 README.md 全部内容嵌入 SKILL.md — 拒绝，因为会超过 500 行限制且违反渐进式披露原则。
|
||
|
||
### 决策 2：强制引导使用 lyxy-runner-python
|
||
|
||
**选择**：在 SKILL.md 中明确要求大模型在 `lyxy-runner-python` skill 可用时**必须**使用该 skill 来运行 parser.py，不提供直接 Python 执行的选项。仅在 `lyxy-runner-python` 不可用时降级到直接 Python 执行。
|
||
|
||
**理由**：
|
||
- lyxy-runner-python 使用 uv 管理依赖，能自动安装解析器所需的第三方库
|
||
- 环境隔离，不污染系统 Python
|
||
- 与 lyxy-reader-docx 保持一致的执行策略
|
||
|
||
**替代方案**：将 lyxy-runner-python 作为可选推荐 — 拒绝，因为用户明确要求"必须使用"。
|
||
|
||
### 决策 3：通过引导阅读 README.md 提供详细用法
|
||
|
||
**选择**：SKILL.md 中仅给出基本的执行命令格式和常见示例，详细的参数说明、依赖安装、解析器对比等内容通过引导大模型阅读 `scripts/README.md` 获取。
|
||
|
||
**理由**：
|
||
- 符合渐进式披露原则：SKILL.md 是指令层，README.md 是资源层
|
||
- README.md 已有完整且结构化的文档，无需重复
|
||
- 减少 SKILL.md 的体积，提高激活阶段的效率
|
||
|
||
### 决策 4：删除 lyxy-reader-docx 而非保留兼容
|
||
|
||
**选择**：直接删除整个 `skills/lyxy-reader-docx/` 目录。
|
||
|
||
**理由**：
|
||
- lyxy-reader-office 完全覆盖了 lyxy-reader-docx 的功能
|
||
- 保留旧 skill 会导致两个 skill 争抢 .docx 文件的处理权，造成歧义
|
||
- 用户明确要求删除
|
||
|
||
## Risks / Trade-offs
|
||
|
||
- **[旧 skill 引用残留]** → 检查项目中是否有其他地方引用了 `lyxy-reader-docx`（如 .claude/settings 中的 skill 配置），删除时需同步清理
|
||
- **[description 覆盖度]** → description 需要包含 docx、xlsx、pptx、pdf 等关键词，确保大模型在发现阶段能匹配到四种文件类型。但 description 有 1024 字符限制，需要精简表达
|
||
- **[SKILL.md 体积控制]** → 需在"提供足够的执行引导"和"保持 500 行以内"之间平衡。通过引导阅读 README.md 解决详细信息的需求
|