# Yy Read XLSX
> 读取并解析 .xlsx 文件内容，提取工作表、表头、单元格文本和表格数据。 用于：用户提供 Excel .xlsx 文件路径并要求读取、汇总或转换表格内容；不用于编辑 Excel、读取 .xls/.csv，或处理需要公式重算、样式还原的场景。
- Skill: `bulls-cows/yy-read-xlsx` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add bulls-cows/yy-read-xlsx`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bulls-cows/yy-read-xlsx/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: bulls-cows (https://skillmd.com/u/bulls-cows)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bulls-cows/yy-read-xlsx
---
# 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` 文件安装第三方依赖。
```bash
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 表格中转换为 `
`。
### 步骤 4. 整理输出内容
根据用户目标调整输出粒度。
**决策分支**：
- **用户要求完整内容**：输出所有非空工作表及其有效行。
- **用户只关心某个工作表**：只输出指定工作表。
- **用户要用于文档表格**：输出 Markdown 表格，并将单元格换行转换为 `
`。
- **用户要保留原始结构**：输出 JSON，保留空单元格和行列索引信息。
- **工作表为空**：明确说明该工作表未读取到有效数据，不编造内容。
### 步骤 5. 说明限制与风险
输出结果时说明以下限制中与当前文件相关的部分：
- `.xlsx` 中日期可能以数字序列保存，脚本不根据样式自动还原日期格式。
- 公式单元格只能读取文件中已有的缓存值，不重新计算公式。
- 合并单元格、颜色、字体、筛选、图表和图片不作为表格内容还原。
- 如果工作簿受密码保护或 XML 结构异常，需要用户提供可读取版本。
### 步骤 6. 输出结果
按以下格式输出读取结果：
```markdown
## XLSX 文件信息
- 文件：xxx.xlsx
- 工作表：Sheet1、Sheet2
- 有效工作表：1 个
- 空工作表：Sheet2
## 提取内容
### Sheet1
| 列1 | 列2 |
| --- | --- |
| 值1 | 值2 |
## 读取说明
- 使用 Python 标准库解析 `.xlsx` 内部 XML。
- 未还原样式、图表和公式重算结果。
```
## 相关资源
本技能包含以下辅助资源：
- `scripts/read_xlsx.py`：使用 Python 标准库读取 `.xlsx` 的执行脚本。