TableForge v0.6.1

智能表格排版与打印系统。从 CSV/Excel 读取数据，通过 YAML 配置自动生成美观的 Typst/PDF 和打印友好 Excel。

安装

pip install tableforge
# 依赖: polars openpyxl pyyaml jsonschema openai
# PDF 需要 Typst CLI: https://github.com/typst/typst
# AI 生成需要: export DEEPSEEK_API_KEY="sk-..."

快速开始

# AI 智能生成配置（推荐）
tableforge ai-gen data.csv

# 交互式流程：AI 生成配置 → [Y] 生成 PDF 看效果
# → 查看 PDF → [M] 提修改意见 → AI 修改 → 重新生成 PDF
# → 满意后 [OK] 完成

# 一键生成（跳过确认）
tableforge ai-gen data.csv -y

# 或手动配置
tableforge init -o config/my.yaml
tableforge run config/my.yaml

功能特性

数据输入

• Excel 多级复杂表头自动解析（合并单元格 → 树状结构），JSON 缓存
• 多 sheet 支持 (sheets: "*" + exclude_sheets)
• 支持 CSV / Excel (.xlsx) / Markdown 表格
• 数据列类型自动识别（PK/数值/文本/日期）

视图与排版

• 按主键拆分视图，每视图独立纸张方向、字号、列宽
• 自适应引擎 v2：数据采样 → 列分类 → 决策树（换行→缩字→挤压→拆分）
• 强制挤压 (force-squeeze)：自动收紧 longtext/pk 列宽，优先一页显示
• 超宽自动拆分：仅当挤压后仍超 15% 时才拆分
• 纵向合并：merge_repeated 同列连续相同值自动合并（含空行继承）
• 手动列宽：绝对 mm 值或 Nfr 权重比例（如 3fr），精确填满页面

格式化

• 数字：千位符、小数位、货币前后缀 (prefix/suffix)、单位 (unit)
• 百分比：符号、小数位
• 日期：自定义格式
• 条件着色：正值绿 / 负值红（Typst + Excel）
• 空值占位符 (null_placeholder)
• 长文本：type: longtext 自动换行渲染（Typst 多行 / Excel 自动换行）

样式

• 5 套预置主题：compact / academic / boardroom / mono / dashboard
• 样式继承 (inherits) + 覆盖 (overrides) 深度合并
• 表格标题：黑体居中 + 单位注释

输出

• Typst：多级合并表头 (colspan/rowspan)、跨页表头重复、条件颜色、主题样式
• PDF：奇偶页交替页码、横向页面
• Excel：合并表头、冻结窗格、斑马纹、主题边框/字体、打印缩放、多 sheet Tab

AI 智能配置生成 (v0.6.0 → v0.6.1)

• tableforge ai-gen <data-file> 自动分析数据并生成配置
• DeepSeek V4 Pro 驱动，修改轮切 Flash 快速迭代
• v0.6.1: 同目录同名 yaml 检测 — 发现已有配置时询问从第二轮开始
• v0.6.1: 强制挤压 (force-squeeze) — 优先在一页显示，提高 auto_split 阈值
• v0.6.1: 提示词外置 — config/prompts/system.md + user.md，无需改代码
• v0.6.1: 全局 title 修复 — PDF/Excel 现正确使用配置中的 title
• 交互式多轮修改：生成 PDF → 查看效果 → 提意见 → AI 修改 → 循环至满意
• 配置文件双写至 config/ 和源文件目录
• 纸张默认 A4 横向，长文本列压缩至 ~20 字符/行
• Schema 校验 + 自动重试修正（最多 3 次）

工程

• JSON Schema (Draft 2020-12) 配置校验，中文错误提示
• 结构化 logging，分级输出 (INFO/DEBUG/WARNING/ERROR)
• Parquet 数据缓存 (L1) + 视图缓存 (L2)，MD5 哈希校验
• SQLite 统计日志 (tableforge stats / stats --run-id N)
• 多版本管理（时间戳目录 + latest 链接 + 滚动清理）
• CLI 子命令：run / preview / init / ai-gen / stats / version / cache

配置示例

source:
  file: "data/sales.xlsx"
  sheets: "*"                   # 所有 sheet
  exclude_sheets: ["封面"]
  header_rows: 2

primary_keys: ["区域", "日期"]

page:
  size: "a3"                    # 默认 A3 横向，优先一页显示
  orientation: landscape
  margin: [1.0, 1.0, 1.0, 1.0]
  numbering:
    enabled: true
    position: alternating

column_formats:
  target:
    type: number
    thousands: true
    decimals: 0
    unit: "万元"
  growth:
    type: percentage
    decimals: 1
    sign: true
    cond_color: true

split_views:
  - name: "业绩"
    data_columns: ["target", "actual", "growth"]
    column_widths:             # fr 权重精确填满页面
      区域: 1fr
      日期: 1fr
      target: 0.8fr
      actual: 0.8fr
      growth: 0.8fr

merge_repeated: ["区域"]
row_number: true
styling:
  theme: "compact"

CLI 命令

tableforge run       <config>    # 完整流程
tableforge preview   <config>    # 适配预览（--dry-run）
tableforge ai-gen    <data>      # AI 智能生成配置
tableforge init      [-o PATH]   # 生成配置草案
tableforge stats     [--run-id]  # 运行统计
tableforge version   list|clean  # 版本管理
tableforge cache     list|clean  # 缓存管理

选项: --dry-run  -v  --no-cache  --refresh-data  --tag TAG

AI 配置生成

# 交互生成（默认 V4 Pro，修改轮切 Flash 加速）
tableforge ai-gen data.csv

# 一键生成
tableforge ai-gen data.csv -y

# 自定义提示
tableforge ai-gen data.csv --title "销售报表" --hint "按区域分组，金额用万元"

# 指定模型
tableforge ai-gen data.csv -m deepseek-v4-flash

# 仅预览
tableforge ai-gen data.xlsx --dry-run

# 要求: export DEEPSEEK_API_KEY="sk-..."
# 支持: .csv / .xlsx / .md

开发

python -m pytest tests/ -v       # 24 tests
python scripts/generate_test_data.py

许可证

MIT