107 lines
4.8 KiB
Markdown
107 lines
4.8 KiB
Markdown
## 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.md` skill 定义文件，符合项目规范
|
||
- 封装 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
|
||
|
||
无重大未决问题。设计清晰明确，可以直接进入实现阶段。
|