@cteno/sdk-linux-x64 0.0.0-stage → 2.10.14

package/skills/xlsx/SKILL.md

@@ -0,0 +1,63 @@
+---
+id: xlsx
+name: xlsx
+version: "2.0.0"
+description: "Create, read, analyze, edit, clean and restructure Excel workbooks (.xlsx/.xlsm/.csv/.tsv) with live formulas, native tables/charts/validation, recalculation and formula-error checks."
+when_to_use: "Use whenever a spreadsheet is the input or deliverable: 表格, Excel, 报表, 预算, 财务模型, pivot-style summaries, cleaning messy CSV/Excel data, adding columns/rows/formulas, charts in a workbook, converting CSV↔XLSX. Not when the deliverable is a Word report, slides or a chart image."
+license: MIT (see LICENSE; scripts adapted from Nous Research and MiniMax, MIT)
+tags: [xlsx, excel, spreadsheet, csv, 表格, 报表]
+---
+
+# Excel workbooks (.xlsx)
+
+| Task | Route |
+|---|---|
+| New workbook | JSON spec → `${SKILL_DIR}/scripts/xlsx_create.py spec.json out.xlsx` (formulas, formats, widths, freeze panes, merges, conditional formats, native tables, charts, validation, notes, protection) |
+| Larger logic | Write an `openpyxl` script; bulk data in/out with `pandas` |
+| Edit existing | `${SKILL_DIR}/scripts/xlsx_edit.py book.xlsx --set B2=… / --append ROWJSON / --insert-rows / --add-table / --define-name … --out new.xlsx` |
+| Move rows/cols keeping references | `${SKILL_DIR}/scripts/xlsx_restructure.py` (read `${SKILL_DIR}/references/restructuring.md`) |
+| Read | `${SKILL_DIR}/scripts/xlsx_read.py book.xlsx --sheets / --json [--data-only] / --formulas / --csv` |
+| CSV ↔ XLSX | `${SKILL_DIR}/scripts/csv_to_xlsx.py`, `${SKILL_DIR}/scripts/xlsx_to_csv.py` |
+| Recalculate | `${SKILL_DIR}/scripts/xlsx_recalc.py book.xlsx` (LibreOffice) |
+| Formula errors | `${SKILL_DIR}/scripts/formula_check.py book.xlsx --summary` |
+| Look at it | `${SKILL_DIR}/scripts/render.py book.xlsx` |
+
+Scripts take `--help`, print JSON (formula_check prints a report), exit non-zero on failure. Always call scripts by the absolute paths shown here (not a copy found elsewhere on disk).
+Dependencies: `python3 -m pip install openpyxl pandas lxml`. Recalc/render: LibreOffice.
+
+## Rules for every workbook you produce
+
+- **Formulas, not pasted results.** `=SUM(B2:B9)`, not the number Python computed — the sheet must update when inputs change. Python is for cleaning and reshaping data before it goes in.
+- **Recalculate before delivery.** openpyxl writes formulas without cached values, so pandas, previews and `--data-only` reads show empty cells until `xlsx_recalc.py` runs.
+- **Zero formula errors.** `formula_check.py` must report PASS. A clean recalc proves formulas *evaluate*, not that they are *right*: check 2–3 results by hand before filling a whole grid.
+- **Follow the user's spec literally** — exact sheet names, headers, and the formula they described.
+- **Editing someone's file**: match its conventions (fonts, colors, number formats, input-cell markings); write only to input cells; never overwrite their formulas; save under a new name unless told otherwise. `.xlsm`: keep macros (`keep_vba=True`).
+- **Document assumptions** next to the numbers (a note or a labeled cell), with a source when one exists. Unknown inputs are marked, never invented.
+
+## Layout and formatting (details and openpyxl snippets: `${SKILL_DIR}/references/format.md`)
+
+- Header row bold, frozen (`freeze_panes: "A2"`), with an autofilter or a native table for lists.
+- Column widths set for the content (CJK characters are about 2× the width of Latin: width ≈ 2 × 字数 + 2).
+- Number formats: thousands separators `#,##0.00`, percentages stored as fractions with `0.0%`, dates as real dates (`yyyy-mm-dd`), negatives in parentheses or red for finance, units in the header (`金额（万元）`).
+- Text left, numbers right; one font throughout (Arial / 微软雅黑 / 等线); totals row bold with a top border.
+- Financial models: blue font for hard-coded inputs, black for formulas, green for cross-sheet links; every assumption in its own cell referenced by formulas (`=B5*(1+$B$6)`, never `=B5*1.05`); guard divisions (`IFERROR`).
+
+## Formula compatibility
+
+- Prefer Excel-2007 functions: `SUMIFS`, `COUNTIFS`, `INDEX`/`MATCH`, `IFERROR`, `SUMPRODUCT`, `VLOOKUP`.
+- Post-2007 functions written through openpyxl need the `_xlfn.` prefix (`_xlfn.TEXTJOIN`, `_xlfn.IFS`, `_xlfn.MAXIFS` …) or they become `#NAME?`.
+- Avoid dynamic-array functions (`XLOOKUP`, `FILTER`, `SORT`, `UNIQUE`, `SEQUENCE`) in files you generate: no spill metadata, and LibreOffice/WPS may not compute them. Sort, filter and de-duplicate in Python first.
+- Sheet names with spaces or Chinese need quotes in references: `='销售 数据'!B2`.
+
+## openpyxl gotchas
+
+- `data_only=True` gives values without formulas; **saving that workbook destroys every formula**. Read formulas and values with two loads.
+- Merged cells: write only the top-left cell.
+- Workbooks linked to other files lose those links' cached values when re-saved with openpyxl — copy the values first, and tell the user.
+- Very large data (> 100k rows): write with pandas/`write_only` mode; skip per-cell styling.
+
+## Verify before delivery (required)
+
+1. `python3 ${SKILL_DIR}/scripts/xlsx_recalc.py out.xlsx` then `python3 ${SKILL_DIR}/scripts/formula_check.py out.xlsx --summary` → PASS.
+2. `python3 ${SKILL_DIR}/scripts/xlsx_read.py out.xlsx --json --data-only` → spot-check totals and a few rows against the source.
+3. For workbooks people will read on screen or print: `python3 ${SKILL_DIR}/scripts/render.py out.xlsx` and look at the pages (truncated `####` columns, wrapped headers, wrong number formats).

package/skills/xlsx/references/format.md

@@ -0,0 +1,71 @@
+# Formatting workbooks with openpyxl
+
+Apply formatting last, after data and formulas are in place. Work at the cell/column level with openpyxl; never hand-edit `styles.xml`.
+
+## Number formats
+
+| Content | Format string | Notes |
+|---|---|---|
+| Money, 2 decimals | `#,##0.00` | thousands separator |
+| Money, finance style | `#,##0;(#,##0);"-"` | negatives in parentheses, zero as dash |
+| RMB | `"¥"#,##0.00` | or put the unit in the header: `金额（元）` |
+| Large units | `#,##0.0,,"M"` / `#,##0.0,"K"` | or divide in a formula and say `（万元）` in the header |
+| Percent | `0.0%` | store 0.15, not 15 |
+| Multiple | `0.0"x"` | valuation multiples |
+| Date | `yyyy-mm-dd` (or `yyyy"年"m"月"d"日"`) | write real `datetime`/`date` values, not strings |
+| Year as label | text `"2026"` | a number would display `2,026` with separators |
+
+```python
+cell.number_format = "#,##0.00"
+```
+
+## Fonts, fills, borders, alignment
+
+```python
+from openpyxl.styles import Font, PatternFill, Border, Side, Alignment
+hdr_font = Font(name="Arial", bold=True, color="FFFFFF")       # for CJK files: name="微软雅黑" or "等线"
+hdr_fill = PatternFill("solid", fgColor="1F4E79")
+thin = Side(style="thin", color="BFBFBF")
+for c in ws[1]:
+    c.font, c.fill = hdr_font, hdr_fill
+    c.alignment = Alignment(horizontal="center", vertical="center", wrap_text=True)
+    c.border = Border(bottom=thin)
+```
+
+- One font family for the whole workbook. Headers bold; totals bold with a top border.
+- Text left-aligned, numbers right-aligned (default), headers centered.
+- Fills sparingly: header row, input cells (light yellow `FFF2CC`), key outputs. No rainbow tables.
+- Build a new `Font`/`Fill` object rather than mutating a shared one (openpyxl styles are immutable proxies).
+
+## Financial-model color code (unless the file has its own)
+
+| Meaning | Style |
+|---|---|
+| Hard-coded input / scenario lever | blue font `0000FF` |
+| Formula | black font |
+| Link to another sheet | green font `008000` |
+| Link to another file | red font `FF0000` |
+| Key assumption / cell to fill in | yellow fill `FFFF00` |
+
+## Layout
+
+- Column widths: `ws.column_dimensions["A"].width = 18`. Latin text ≈ characters + 2; CJK ≈ 2 × characters + 2. Never leave numbers showing `####`.
+- Freeze the header: `ws.freeze_panes = "A2"` (or `"B2"` to also freeze the label column).
+- Lists of records: make a native table (`xlsx_create.py` `tables`, or `openpyxl.worksheet.table.Table`) — filters, banding and structured references come free.
+- Wrap long text in a few columns only (`wrap_text=True`) and set a row height if needed.
+- Merged cells only for titles; never inside data ranges (they break sorting/filtering).
+- Print setup for sheets people print: `ws.page_setup.orientation = "landscape"`, `ws.page_setup.fitToWidth = 1`, `ws.sheet_properties.pageSetUpPr.fitToPage = True`, `ws.print_title_rows = "1:1"`.
+
+## Conditional formatting
+
+Use for signal, not decoration: negative variances red, top values highlighted, a data bar for one key column.
+
+```python
+from openpyxl.formatting.rule import CellIsRule, ColorScaleRule, DataBarRule
+ws.conditional_formatting.add("D2:D100", CellIsRule(operator="lessThan", formula=["0"], font=Font(color="C00000")))
+ws.conditional_formatting.add("E2:E100", DataBarRule(start_type="min", end_type="max", color="5B9BD5"))
+```
+
+## Charts
+
+Native charts (`openpyxl.chart`) stay live with the data. Give them a title and axis titles, one series color per meaning, and anchor them beside the table, not on top of it. Prefer a column/bar chart for comparisons, a line for trends over time, and avoid pies with more than 5 slices.

package/skills/xlsx/references/restructuring.md

@@ -0,0 +1,71 @@
+# Reference-aware restructuring (xlsx_restructure.py)
+
+`scripts/xlsx_restructure.py` performs one row/column insert or delete
+and rewrites everything that references the moved cells. This document
+gives the exact rewrite rules and honest limits.
+
+## What gets rewritten
+
+| Artifact | Scope | Behavior |
+|---|---|---|
+| Formula references | ALL sheets | A1 refs into the edited sheet are shifted; refs into a fully deleted region become `#REF!` |
+| Merged-cell ranges | edited sheet | shifted; expanded when they span the insertion point; dropped (reported `to: null`) when fully deleted |
+| Autofilter ref | edited sheet | shifted/expanded like a range |
+| Freeze panes | edited sheet | anchor cell shifted (never below row/col of the pane's own minimum) |
+| Data validations | edited sheet | each range in the sqref shifted; deleted ranges removed |
+| Conditional formats | edited sheet | applied range (sqref) shifted |
+| Native tables | edited sheet | table `ref` shifted/expanded |
+| Defined names | workbook scope | `attr_text` refs into the edited sheet rewritten |
+| Row heights / column widths | edited sheet | dimension keys re-indexed |
+
+## Reference grammar handled
+
+- Relative and absolute coordinates in any mix: `B2`, `$B2`, `B$2`,
+  `$B$2` — the `$` flags are preserved through the shift.
+- Ranges `B2:D9`, including partial-absolute endpoints.
+- Cross-sheet refs: `Data!B2`, `'My Sheet'!$A$1:$C$9` (quoted names may
+  contain doubled quotes `''`). Only refs whose sheet qualifier matches
+  the edited sheet are touched; unqualified refs are interpreted
+  relative to the formula's own sheet.
+- String literals inside formulas (`"See B2"`) are never rewritten.
+- Function names that look like cells (`LOG10(...)`) are not touched
+  (a reference is never followed by `(`).
+- Whole-row/column refs (`B:B`, `2:2`) pass through unchanged — Excel
+  semantics keep them valid across inserts within the span.
+
+## Shift semantics
+
+Insert of N at index i: every coordinate >= i moves +N; range endpoints
+move independently, so a range spanning i grows by N.
+
+Delete of N at index i: coordinates before i are unchanged; coordinates
+past the deleted block move -N; a single cell inside the block becomes
+`#REF!`; a RANGE partially covering the block is clamped (Excel does the
+same); a range entirely inside the block becomes `#REF!` (formulas) or
+is removed (merges/validations).
+
+## What it CANNOT shift (honest limits)
+
+- **Chart anchors and plotted ranges** — openpyxl chart objects are not
+  reliably round-tripped; anchors stay where they were. Re-create
+  charts after restructuring if their data moved.
+- **Images / drawings** — same reason.
+- **Conditional-format RULE formulas** — the applied range (sqref) is
+  shifted, but formulas inside `cell_is`/`expression` rules (e.g.
+  `$B1>100`) are left as-is. Review them if they reference moved cells.
+- **Sheet-local defined names** and names using R1C1 or union/
+  intersection operators are rewritten only if they parse as plain A1
+  refs; anything else passes through untouched.
+- **Structured table references** in formulas (`Table1[Sales]`) don't
+  need shifting (they follow the table), and are left alone.
+
+Every run prints a JSON report listing exactly which formulas, merges,
+tables, names, and ranges were changed, plus a fixed `not_shifted` list
+of the above limits — inspect it after any structural edit.
+
+## One op per invocation
+
+The CLI takes exactly one of `--insert-rows/--delete-rows/
+--insert-cols/--delete-cols` (as `IDX[:N]`; columns accept letters).
+For multiple operations run it repeatedly — ordering compound shifts in
+one pass is where spreadsheet tools historically corrupt references.

package/skills/xlsx/scripts/csv_to_xlsx.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""Convert a CSV file to a styled .xlsx workbook with type inference.
+
+Type inference per cell (disable with --no-infer):
+  int, float, bool ("true"/"false", case-insensitive), ISO date
+  (YYYY-MM-DD) and ISO datetime; everything else stays a string.
+
+Styling applied by default (disable with --plain):
+  bold header row with a light fill, frozen top row, autofilter over the
+  data range, and column widths sized to the longest cell (capped at 60).
+
+Usage:
+  csv_to_xlsx.py data.csv out.xlsx
+  csv_to_xlsx.py data.csv out.xlsx --sheet-name Import --encoding cp1252
+  csv_to_xlsx.py data.csv out.xlsx --delimiter ';' --no-infer
+"""
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import sys
+from datetime import date, datetime
+
+from openpyxl import Workbook
+from openpyxl.styles import Font, PatternFill
+from openpyxl.utils import get_column_letter
+
+MAX_COL_WIDTH = 60
+COL_PADDING = 2
+DEFAULT_COL_WIDTH = 8
+
+
+def infer(text):
+    if text == "":
+        return None
+    low = text.lower()
+    if low in ("true", "false"):
+        return low == "true"
+    for caster in (int, float):
+        try:
+            return caster(text)
+        except ValueError:
+            pass
+    for parser in (date.fromisoformat, datetime.fromisoformat):
+        try:
+            return parser(text)
+        except ValueError:
+            pass
+    return text
+
+
+def main(argv=None):
+    # Text I/O is UTF-8 regardless of the locale (GBK on Chinese Windows).
+    for stream in (sys.stdin, sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8")
+        except Exception:
+            pass
+    ap = argparse.ArgumentParser(description="CSV -> styled .xlsx converter.")
+    ap.add_argument("csv_file", help="input CSV path")
+    ap.add_argument("output", help="output .xlsx path")
+    ap.add_argument("--sheet-name", default="Sheet1")
+    ap.add_argument("--encoding", default="utf-8",
+                    help="CSV file encoding (default utf-8)")
+    ap.add_argument("--delimiter", default=",")
+    ap.add_argument("--no-infer", action="store_true",
+                    help="keep every cell as a string")
+    ap.add_argument("--plain", action="store_true",
+                    help="skip header styling / freeze / autofilter")
+    args = ap.parse_args(argv)
+
+    with open(args.csv_file, newline="", encoding=args.encoding) as fh:
+        rows = list(csv.reader(fh, delimiter=args.delimiter))
+
+    wb = Workbook()
+    ws = wb.active
+    ws.title = args.sheet_name
+    for i, row in enumerate(rows):
+        if args.no_infer or i == 0:
+            ws.append(row)
+        else:
+            ws.append([infer(cell) for cell in row])
+
+    if rows and not args.plain:
+        header_font = Font(bold=True)
+        header_fill = PatternFill("solid", fgColor="DDEBF7")
+        for cell in ws[1]:
+            cell.font = header_font
+            cell.fill = header_fill
+        ws.freeze_panes = "A2"
+        ws.auto_filter.ref = ws.dimensions
+        for col_idx in range(1, ws.max_column + 1):
+            longest = max((len(str(r[col_idx - 1])) for r in rows
+                           if len(r) >= col_idx), default=DEFAULT_COL_WIDTH)
+            ws.column_dimensions[get_column_letter(col_idx)].width = \
+                min(longest + COL_PADDING, MAX_COL_WIDTH)
+
+    wb.save(args.output)
+    print(json.dumps({"ok": True, "output": args.output,
+                      "rows": len(rows)}, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except Exception as exc:
+        print(json.dumps({"ok": False, "error": str(exc)}), file=sys.stderr)
+        sys.exit(1)