yy-read-xlsx

name	yy-read-xlsx
description	读取并解析 .xlsx 文件内容，提取工作表、表头、单元格文本和表格数据。 用于：用户提供 Excel .xlsx 文件路径并要求读取、汇总或转换表格内容；不用于编辑 Excel、读取 .xls/.csv，或处理需要公式重算、样式还原的场景。

yy-read-xlsx

描述

读取 Office Open XML 格式的 .xlsx 文件内容，提取工作表名称、有效行列、单元格文本和表格数据，并按用户需求输出为 Markdown、JSON 或结构化摘要。

使用场景

• 用户提供 .xlsx 文件路径并要求读取内容
• 用户需要把 Excel 工作表转换为 Markdown 表格或 JSON 数据
• 用户需要查看工作表名称、表头、有效行和有效列
• 用户需要从 .xlsx 附件中提取信息后写入文档

不应触发：

• 用户要求创建、编辑或写回 Excel 文件
• 用户提供的是 .xls、.csv、.ods 或其他非 .xlsx 文件
• 用户要求保留字体、颜色、合并单元格样式、筛选器或图表
• 用户要求重新计算公式结果，而文件中没有可读取的缓存值

指令

步骤 1. 确认文件路径

• 验证用户提供的文件路径是否存在。
• 确认文件扩展名为 .xlsx。
• 说明本技能读取的是工作簿中保存的单元格值，不还原样式和图表。

决策分支：

• 路径存在且扩展名为 .xlsx：进入步骤 2。
• 路径不存在：提示用户提供正确路径，退出执行。
• 扩展名不是 .xlsx：提示用户当前技能仅支持 .xlsx，退出执行。

步骤 2. 选择读取方式

优先使用本技能附带的 Python 标准库脚本读取，避免为读取普通 .xlsx 文件安装第三方依赖。

python skills/yy-read-xlsx/scripts/read_xlsx.py --file "文件路径" --format markdown

常用参数：

• --file：.xlsx 文件路径，必填。
• --sheet：仅读取指定工作表名称，不传则读取全部工作表。
• --format：输出格式，支持 markdown、json、text。
• --forward-fill：对指定列做向下填充，适合 Excel 用空白单元格表示同一分组的表格。
• --fill-columns：配合 --forward-fill 使用，指定从 0 开始的列索引，如 0,1。

决策分支：

• 只需快速查看内容：使用 --format text 输出工作表和行数据。
• 需要写入 Markdown 文档：使用 --format markdown 输出 Markdown 表格。
• 需要后续加工或校验：使用 --format json 输出结构化数据。
• 表格存在分组列空白：使用 --forward-fill --fill-columns "0,1" 向下填充分组列。

步骤 3. 理解解析流程

读取 .xlsx 时按 Office Open XML 文件结构处理：

1. 使用 zipfile 将 .xlsx 作为压缩包打开。
2. 读取 xl/workbook.xml 和 xl/_rels/workbook.xml.rels 获取工作表名称与 XML 文件路径。
3. 读取 xl/sharedStrings.xml，建立共享字符串索引表。
4. 逐个读取 xl/worksheets/sheetN.xml，按单元格引用解析列号和行号。
5. 根据单元格类型读取共享字符串、内联字符串、数字、布尔值或公式缓存值。
6. 保留中间空列和空单元格，去掉完全为空的尾部行列。

这也是读取 2025.6.24浦东新区助听类辅具适配项目服务点信息.xlsx 时采用的方法：先解析 Sheet1 的有效行，再根据表头生成 Markdown 表格；对“序号”和“品牌”这类分组列，用向下填充保留每一行的所属分组；对单元格内换行，在 Markdown 表格中转换为 <br>。

步骤 4. 整理输出内容

根据用户目标调整输出粒度。

决策分支：

• 用户要求完整内容：输出所有非空工作表及其有效行。
• 用户只关心某个工作表：只输出指定工作表。
• 用户要用于文档表格：输出 Markdown 表格，并将单元格换行转换为 <br>。
• 用户要保留原始结构：输出 JSON，保留空单元格和行列索引信息。
• 工作表为空：明确说明该工作表未读取到有效数据，不编造内容。

步骤 5. 说明限制与风险

输出结果时说明以下限制中与当前文件相关的部分：

• .xlsx 中日期可能以数字序列保存，脚本不根据样式自动还原日期格式。
• 公式单元格只能读取文件中已有的缓存值，不重新计算公式。
• 合并单元格、颜色、字体、筛选、图表和图片不作为表格内容还原。
• 如果工作簿受密码保护或 XML 结构异常，需要用户提供可读取版本。

步骤 6. 输出结果

按以下格式输出读取结果：

## XLSX 文件信息

- 文件：xxx.xlsx
- 工作表：Sheet1、Sheet2
- 有效工作表：1 个
- 空工作表：Sheet2

## 提取内容

### Sheet1

| 列1 | 列2 |
| --- | --- |
| 值1 | 值2 |

## 读取说明

- 使用 Python 标准库解析 `.xlsx` 内部 XML。
- 未还原样式、图表和公式重算结果。

相关资源

本技能包含以下辅助资源：

• scripts/read_xlsx.py：使用 Python 标准库读取 .xlsx 的执行脚本。