4.2 KiB
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-pythonskill 可用时必须使用该 skill 来运行 Python 脚本 - 删除
skills/lyxy-reader-docx目录
Non-Goals:
- 不修改已有的解析脚本代码
- 不修改
lyxy-runner-pythonskill - 不新增任何解析功能
- 不创建单独的文档说明文件（如旧 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 解决详细信息的需求