excel-scout

This skill is read-only, no side effects. Uses openpyxl read_only + pandas sampling for fast scanning. It is the prerequisite step for all other operation skills. 本技能只读不写，安全无副作用。用 openpyxl read_only + pandas 采样快速扫描，是其他所有操作技能的前置步骤。

Excel Pre-Operation Scout / Excel 操作前勘察

Purpose / 定位

This skill solves a high-frequency pain point: users describe needs in business language ("convert dates to yyyymmdd", "change country codes to Chinese names"), but don't know which column corresponds to what or what the current values are. Figure out the target columns before operating, to avoid modifying wrong columns.

本技能解决一个高频痛点：用户描述需求时用的是业务语言（"把日期转成 yyyymmdd""国别代码改中文"），但不知道文件里哪一列对应、当前值是什么。 在动手前先搞清楚目标列，避免改错列。

User Request (business language) / 用户需求（业务语言）
    │
    ▼
excel-scout: Scan file → Locate target columns → Show current values → Confirm operation scope
             扫描文件 → 定位目标列 → 展示当前值 → 确认操作范围
    │
    ▼
Other skills: Execute operations on confirmed target columns / 其他技能: 在已确认的目标列上执行操作

Workflow / 工作流程

1. Receive Requirements / 接收需求

Extract the following from user requirements: / 从用户需求中提取以下信息：

To Extract / 要提取的	User Says / 用户说	Example / 示例
File Path / 文件路径	"test-files/xxx.xlsx" / "测试文件/xxx.xlsx"	Must be explicit / 必须明确
Operation Intent / 操作意图	"dates to text" / "country codes to Chinese" / "renumber" / "日期转文本""国别改中文""序号重排"	One target column per intent / 每项一个目标列
Column Characteristics / 操作列特征	Column name keywords / data type / position / 列名关键字 / 数据类型 / 位置	Infer / 推断

2. Scan File / 扫描文件

import os, sys
from openpyxl import load_workbook
from openpyxl.utils import get_column_letter
from datetime import datetime
import pandas as pd

FILE = 'target.xlsx' / FILE = '目标文件.xlsx'
size_mb = os.path.getsize(FILE) / 1024 / 1024

# ====== A. Read headers (fast with read_only) / 读表头 ======
wb = load_workbook(FILE, read_only=True)
ws = wb.active

headers = {}
for cell in ws[1]:
    if cell.value:
        headers[cell.column] = str(cell.value).strip()

total_cols = len(headers)
print(f'File: {os.path.basename(FILE)} ({size_mb:.0f}MB) / 文件: {os.path.basename(FILE)} ({size_mb:.0f}MB)')
print(f'Columns: {total_cols} / 列数: {total_cols}')

# Print full header inventory / 打印完整表头清单
print(f'\n=== Header Inventory / 表头清单 ===')
for col_idx in sorted(headers.keys()):
    cl = get_column_letter(col_idx)
    print(f'  {cl}({col_idx}): {headers[col_idx]}')

wb.close()

# ====== B. data_only sample scan for date columns / data_only 采样扫描日期列 ======
wb2 = load_workbook(FILE, read_only=True, data_only=True)
ws2 = wb2.active

date_cols = {}
for row in ws2.iter_rows(min_row=2, max_row=min(500, ws2.max_row or 999999)):
    for cell in row:
        if isinstance(cell.value, datetime) and cell.column not in date_cols:
            date_cols[cell.column] = headers.get(cell.column, '?')

wb2.close()
if date_cols:
    print(f'\nFound {len(date_cols)} date columns / 发现 {len(date_cols)} 个日期列:')
    for c in sorted(date_cols):
        print(f'  {get_column_letter(c)}({c}): {date_cols[c]}')

# ====== C. pandas sample read (first N rows only) / pandas 采样读数据 ======
df_sample = pd.read_excel(FILE, nrows=5000)
print(f'\nTotal rows (sample cap): {len(df_sample)} / 总行数(采样上限): {len(df_sample)}')

# ====== D. Locate target columns per user requirements / 针对用户需求定位目标列 ======
# For each operation intent, match target columns and display current values
# 对每一项操作意图，匹配目标列并展示当前值

for intent in ['Dates→yyyymmdd / 日期→yyyymmdd', 'Country codes→Chinese / 国别代码→中文', 'Renumber / 序号重排']:
    # Match by keyword or data type / 按关键字或数据类型匹配
    # Show target column + current value samples / 展示目标列 + 当前值样本
    pass