4.8 KiB
Context
当前项目是一个专门用于开发大模型工具 skill 的项目。skills/lyxy-reader-docx 目录已经存在，其中包含：
scripts/docx_parser.py- 完整的 DOCX 解析脚本，支持多策略解析（MarkItDown、python-docx、XML 原生）docx_parser.md- 脚本使用文档
需要将这些现有资源封装为一个标准的 skill，让大模型能够识别并优先使用该工具处理 .docx 文件。
Goals / Non-Goals
Goals:
- 创建
skills/lyxy-reader-docx/skill.mdskill 定义文件，符合项目规范 - 封装 docx_parser.py 的核心功能为 skill 的能力描述
- 确保大模型在遇到 .docx 文件时能够识别并优先使用该 skill
- 执行时优先委托给 lyxy-runner-python skill，利用其依赖管理和环境隔离能力
- 支持多种解析模式：全文提取、标题提取、章节内容提取、关键词搜索
Non-Goals:
- 修改现有的 docx_parser.py 脚本逻辑
- 添加图片或格式提取功能
- 实现 docx 文件的编辑或修改功能
- 支持 .doc 或其他文档格式
Decisions
1. Skill 定义结构
决策: 采用标准的 skill.md 格式，包含 description、capabilities 等核心字段
理由: 遵循项目现有 skill 的统一规范，便于大模型理解和调用。查看 skills/ 目录下的其他 skill 示例（如 lyxy-runner-python、lyxy-runner-js）可知项目有一致的定义格式。
2. 依赖声明
决策: 在 skill.md 的 Compatibility 字段中声明 Python 运行时依赖
理由: docx_parser.py 需要 Python 3.6+ 环境，并且需要至少安装 markitdown 或 python-docx 之一。明确这些依赖可以帮助大模型判断环境是否就绪。
3. 能力映射
决策: 将 docx_parser.py 的所有功能映射为 skill 的 capabilities
理由: 脚本提供了丰富的功能（全文、字数、行数、标题、章节、搜索），全部暴露给大模型可以提供更灵活的使用方式。能力包括：
- 全文转换为 Markdown
- 获取文档元信息（字数、行数）
- 标题列表提取
- 指定章节内容提取
- 正则表达式搜索
4. 触发器设计
决策: 设置明确的触发器（Trigger phrases），包括中文和英文
理由: 用户可能使用中文或英文请求解析 docx 文档。触发器包括：
- "读取 docx", "解析 docx", "打开 word 文档"（中文）
- "read docx", "parse docx", "extract from word document"（英文）
- 文件扩展名
.docx出现时
5. 执行委托策略
决策: lyxy-reader-docx skill 执行时优先委托给 lyxy-runner-python skill
理由: lyxy-runner-python skill 提供了统一的 Python 脚本执行环境，具有以下优势：
- 使用 uv 管理依赖，自动安装 markitdown 或 python-docx
- 环境隔离，不污染系统 Python
- 跨平台兼容
执行策略: 此 skill 的执行决策由大模型在调用时判断，不在 skill 定义或脚本中实现检查逻辑。
当大模型决定执行 docx_reader skill 时：
- 如果环境中存在 lyxy-runner-python skill，优先使用 lyxy-runner-python 执行 docx_parser.py
- 如果环境中不存在 lyxy-runner-python skill，直接使用 Python 执行 docx_parser.py
好处:
- 最大化复用现有 skill
- 自动处理 Python 依赖管理（通过 lyxy-runner-python）
- 提供更好的错误处理和用户体验
Risks / Trade-offs
风险 1: lyxy-runner-python skill 不可用
风险: 目标环境可能没有安装 lyxy-runner-python skill 或其依赖（uv 工具）
缓解措施:
- 大模型在执行时判断 lyxy-runner-python skill 是否存在
- 如果 lyxy-runner-python 不可用，自动降级为直接使用 Python 执行脚本
- 在 skill.md 中说明降级策略和直接执行的条件
风险 2: 依赖库未安装（降级场景）
风险: 当 lyxy-runner-python 不可用时，直接执行脚本可能遇到 markitdown 或 python-docx 未安装的情况
缓解措施:
- 在 skill.md 的 Compatibility 字段中明确列出可选依赖
- 在降级场景中，脚本本身已实现多策略降级（MarkItDown → python-docx → XML 原生）
- 提示用户安装 lyxy-runner-python 获得更好的体验
风险 2: 大文件处理性能
风险: 大型 .docx 文件解析可能耗时较长
缓解措施:
- 在能力描述中提示可以使用章节提取或关键词搜索来限制处理范围
- docx_parser.py 已实现流式处理，内存占用相对较低
权衡: 纯文本 vs 格式保留
权衡: 选择只提取纯文本，不保留图片和复杂格式
理由: 用户明确要求"只能将docx文档转换为文字"，且大模型主要关注文本内容。虽然脚本支持 Markdown 格式转换（表格、粗体、斜体等），但图片会被自动移除，符合需求。
Open Questions
无重大未决问题。设计清晰明确，可以直接进入实现阶段。