Skill/openspec/changes/archive/2026-02-12-develop-docx-reader-skill/design.md

Context

当前项目是一个专门用于开发大模型工具 skill 的项目。skills/docx-reader 目录已经存在，其中包含：

• scripts/docx_parser.py - 完整的 DOCX 解析脚本，支持多策略解析（MarkItDown、python-docx、XML 原生）
• docx_parser.md - 脚本使用文档

需要将这些现有资源封装为一个标准的 skill，让大模型能够识别并优先使用该工具处理 .docx 文件。

Goals / Non-Goals

Goals:

• 创建 skills/docx-reader/skill.md skill 定义文件，符合项目规范
• 封装 docx_parser.py 的核心功能为 skill 的能力描述
• 确保大模型在遇到 .docx 文件时能够识别并优先使用该 skill
• 执行时优先委托给 python-runner skill，利用其依赖管理和环境隔离能力
• 支持多种解析模式：全文提取、标题提取、章节内容提取、关键词搜索

Non-Goals:

• 修改现有的 docx_parser.py 脚本逻辑
• 添加图片或格式提取功能
• 实现 docx 文件的编辑或修改功能
• 支持 .doc 或其他文档格式

Decisions

1. Skill 定义结构

决策: 采用标准的 skill.md 格式，包含 description、capabilities 等核心字段

理由: 遵循项目现有 skill 的统一规范，便于大模型理解和调用。查看 skills/ 目录下的其他 skill 示例（如 python-runner、js-runner）可知项目有一致的定义格式。

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. 执行委托策略

决策: docx-reader skill 执行时优先委托给 python-runner skill

理由: python-runner skill 提供了统一的 Python 脚本执行环境，具有以下优势：

• 使用 uv 管理依赖，自动安装 markitdown 或 python-docx
• 环境隔离，不污染系统 Python
• 跨平台兼容

执行策略: 此 skill 的执行决策由大模型在调用时判断，不在 skill 定义或脚本中实现检查逻辑。

当大模型决定执行 docx_reader skill 时：

• 如果环境中存在 python-runner skill，优先使用 python-runner 执行 docx_parser.py
• 如果环境中不存在 python-runner skill，直接使用 Python 执行 docx_parser.py

好处:

• 最大化复用现有 skill
• 自动处理 Python 依赖管理（通过 python-runner）
• 提供更好的错误处理和用户体验

Risks / Trade-offs

风险 1: python-runner skill 不可用

风险: 目标环境可能没有安装 python-runner skill 或其依赖（uv 工具）

缓解措施:

• 大模型在执行时判断 python-runner skill 是否存在
• 如果 python-runner 不可用，自动降级为直接使用 Python 执行脚本
• 在 skill.md 中说明降级策略和直接执行的条件

风险 2: 依赖库未安装（降级场景）

风险: 当 python-runner 不可用时，直接执行脚本可能遇到 markitdown 或 python-docx 未安装的情况

缓解措施:

• 在 skill.md 的 Compatibility 字段中明确列出可选依赖
• 在降级场景中，脚本本身已实现多策略降级（MarkItDown → python-docx → XML 原生）
• 提示用户安装 python-runner 获得更好的体验

风险 2: 大文件处理性能

风险: 大型 .docx 文件解析可能耗时较长

缓解措施:

• 在能力描述中提示可以使用章节提取或关键词搜索来限制处理范围
• docx_parser.py 已实现流式处理，内存占用相对较低

权衡: 纯文本 vs 格式保留

权衡: 选择只提取纯文本，不保留图片和复杂格式

理由: 用户明确要求"只能将docx文档转换为文字"，且大模型主要关注文本内容。虽然脚本支持 Markdown 格式转换（表格、粗体、斜体等），但图片会被自动移除，符合需求。

Open Questions

无重大未决问题。设计清晰明确，可以直接进入实现阶段。