Deskclaw XLSX

DeskClaw XLSX v3.0

创建、读取、编辑和验证 Excel 表格。

第零步：Bootstrap

python bootstrap.py

幂等，已装跳过。检查：python -c "import openpyxl; print('READY')"

命令速查表（Agent 必读）

创建新表格

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. 财务配色

5. 数字格式

cell.number_format = '¥#,##0'      # 货币
cell.number_format = '0.0%'         # 百分比
cell.number_format = '@'            # 文本（年份用这个，避免 2026 变 2,026）
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

参考文档索引