| 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 文件结构处理：
- 使用
zipfile 将 .xlsx 作为压缩包打开。
- 读取
xl/workbook.xml 和 xl/_rels/workbook.xml.rels 获取工作表名称与 XML 文件路径。
- 读取
xl/sharedStrings.xml，建立共享字符串索引表。
- 逐个读取
xl/worksheets/sheetN.xml，按单元格引用解析列号和行号。
- 根据单元格类型读取共享字符串、内联字符串、数字、布尔值或公式缓存值。
- 保留中间空列和空单元格，去掉完全为空的尾部行列。
这也是读取 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 的执行脚本。
