bulls-cows 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的执行脚本。