## 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 解决详细信息的需求