| slug | deskclaw-xlsx |
| version | 3.0.0 |
| displayName | Excel 表格工具（DeskClaw XLSX） |
| summary | DeskClaw 自研 Excel 全能工具。基于 openpyxl 与 LibreOffice 公式引擎，支持创建、读取、编辑、公式重算与校验、unpack/pack 高级编辑、列行插入、pandas 数据分析与财务建模规范。 |
| tags | office, xlsx, excel, spreadsheet, formulas, pandas, openpyxl, libreoffice, financial-modeling |
| name | deskclaw-xlsx |
| description | 专业 Excel 文件（.xlsx）创建、读取、编辑、公式验证和格式化。覆盖数据表、财务模型、报表、统计分析等场景。当用户要求创建、编辑、分析任何 Excel 表格时使用此技能。 |
| setup | bootstrap.py |
DeskClaw XLSX v3.0
创建、读取、编辑和验证 Excel 表格。
第零步：Bootstrap
python bootstrap.py
幂等，已装跳过。检查：python -c "import openpyxl; print('READY')"
命令速查表（Agent 必读）
| 任务 | 方法 |
|---|
| 创建新表格 | from openpyxl import Workbook; wb = Workbook() → 添加数据/公式/格式 → wb.save() |
| 读取分析 | python scripts/xlsx_reader.py file.xlsx 或 pandas |
| 编辑已有文件 | from openpyxl import load_workbook; wb = load_workbook('file.xlsx') |
| 添加列（带公式） | python scripts/xlsx_add_column.py |
| 插入行 | python scripts/xlsx_insert_row.py |
| 公式重算 | python scripts/recalc.py output.xlsx（创建后必须执行） |
| 公式验证 | python scripts/formula_check.py file.xlsx --json |
| 保存路径 | wb.save(os.path.expanduser('~/Desktop/output.xlsx')) |
创建新表格
from openpyxl import Workbook
from openpyxl.styles import Font, PatternFill, Alignment, Border, Side
import os
wb = Workbook()
ws = wb.active
ws.title = "数据表"
headers = ["姓名", "部门", "销售额", "占比"]
header_font = Font(bold=True, color="FFFFFF", name="Microsoft YaHei")
header_fill = PatternFill("solid", fgColor="4472C4")
for col, h in enumerate(headers, 1):
cell = ws.cell(row=1, column=col, value=h)
cell.font = header_font
cell.fill = header_fill
cell.alignment = Alignment(horizontal="center")
data = [["张三", "销售部", 85000], ["李四", "市场部", 72000]]
for r, row_data in enumerate(data, 2):
for c, val in enumerate(row_data, 1):
ws.cell(row=r, column=c, value=val)
ws['C4'] = '=SUM(C2:C3)'
ws['C4'].font = Font(bold=True)
for r in range(2, 4):
ws.cell(row=r, column=4, value=f'=C{r}/C$4')
ws.cell(row=r, column=4).number_format = '0.0%'
for col in ["A", "B", "C", "D"]:
ws.column_dimensions[col].width = 15
wb.save(os.path.expanduser("~/Desktop/output.xlsx"))
创建后必须执行公式重算：
python scripts/recalc.py ~/Desktop/output.xlsx
核心规则
1. 公式优先（最重要）
total = sum([85000, 72000])
ws['C4'] = total
ws['C4'] = '=SUM(C2:C3)'
每个计算值都必须用 Excel 公式。 硬编码的数字无法在 Excel 中更新。
2. 公式重算（必须）
openpyxl 写入的公式只是字符串，保存后必须执行 scripts/recalc.py 让值生效。如果有公式错误（#REF!、#DIV/0!），recalc 会返回详细位置。
3. 编辑完整性
- 创建：
Workbook() 新建
- 编辑已有文件：必须
load_workbook('existing.xlsx')，绝对不要 Workbook() 新建
- 输出必须保留原有所有 sheet 和数据
- 保存后用
xlsx_reader.py 验证
4. 财务配色
| 角色 | 颜色 | 用法 |
|---|
| 输入/假设 | 蓝色 Font(color="0000FF") | 用户会改的数字 |
| 公式结果 | 黑色 Font(color="000000") | 所有计算值 |
| 跨 Sheet 引用 | 绿色 Font(color="00B050") | ='Sheet2'!A1 类公式 |
5. 数字格式
cell.number_format = '¥#,##0'
cell.number_format = '0.0%'
cell.number_format = '@'
cell.number_format = '#,##0;(#,##0);"-"'
任务路由
用户任务
├─ 读取/分析 → xlsx_reader.py + pandas
├─ 从零创建 → openpyxl Workbook() → save → recalc.py
├─ 编辑已有文件
│ ├─ 简单修改 → openpyxl load_workbook()
│ └─ 添加列/插入行 → scripts/xlsx_add_column.py, xlsx_insert_row.py
├─ 修复公式 → XML unpack → 修 <f> 节点 → pack
└─ 验证公式 → formula_check.py（静态）+ recalc.py（动态）
编辑已有文件的工具脚本
添加列（带公式、样式自动复制）
python scripts/xlsx_unpack.py input.xlsx /tmp/xlsx_work/
python scripts/xlsx_add_column.py /tmp/xlsx_work/ --col G \
--sheet "Sheet1" --header "占比" \
--formula '=F{row}/$F$10' --formula-rows 2:9 \
--total-row 10 --total-formula '=SUM(G2:G9)' --numfmt '0.0%'
python scripts/xlsx_pack.py /tmp/xlsx_work/ output.xlsx
插入行（自动移位、更新 SUM 公式）
python scripts/xlsx_unpack.py input.xlsx /tmp/xlsx_work/
python scripts/xlsx_insert_row.py /tmp/xlsx_work/ --at 5 \
--sheet "Sheet1" --text A=新项目 \
--values B=3000 C=3000 --formula 'D=SUM(B{row}:C{row})'
python scripts/xlsx_pack.py /tmp/xlsx_work/ output.xlsx
参考文档索引
