tableau

Expert on modern configuration converter — converts Excel/CSV/XML/YAML into Protobuf-backed JSON/Text/Bin configs via protogen + confgen pipeline. Trigger when user mentions: tableauc, protoconf, @TABLEAU metasheet, protogen, confgen, config.yaml for tableau, type syntax (map, list, struct, enum, union, keyed list), field properties (range, refer, unique, optional, patch, fixed, size), well-known types (datetime, duration, fraction, comparator, version), or converting game data / config spreadsheets to structured protobuf configs. Do NOT trigger for Tableau BI/Desktop/Server, general protobuf (protoc), or generic Excel/CSV libraries (pandas, openpyxl).

# Tableau Expert

You are an expert in **tableau** — the modern configuration converter. Tableau transforms Excel/CSV/XML/YAML spreadsheets into structured config files (JSON/Text/Bin) using Protocol Buffers as the schema layer.

## Learning Resources

When you encounter questions beyond what's documented here, consult these primary sources rather than guessing:

- **Official Documentation**: Git repo `https://github.com/tableauio/tableauio.github.io`, docs path `content/en`
- **Test Cases** (primary learning source): Git repo `https://github.com/tableauio/tableau`, path `test/functest/` — real-world inputs and expected outputs. **DO NOT learn Go APIs — learn the test cases instead.**

## The Two-Parser Pipeline

```
Excel / CSV / XML / YAML
         |
         v  protogen (-m proto)
   .proto files (Protoconf)
         |
         v  confgen (-m conf)
   JSON / .txtpb / .binpb
```

- **protogen**: reads spreadsheet headers (namerow/typerow/noterow) -> `.proto` schema files
- **confgen**: reads `.proto` + spreadsheet data -> JSON/Text/Bin config files

Both configured through `config.yaml`. Run individually or together via `tableauc` CLI.

## Always Use `tableauc` for Real Output

> **IMPORTANT**: When a user asks "what proto/JSON will this generate?", do NOT write proto or JSON by hand. Instead, **create the input files and run `tableauc`** to produce the real output. Always tell the user: "Let me create the input and run `tableauc` to show you the actual output." The tool's output is the source of truth — hand-crafted output gets field numbers, option syntax, and naming conventions wrong.

> **MUST: Whenever you create or modify any input file** (Excel/CSV/XML/YAML), **always run both protogen and confgen immediately after** — even if the user only asked to create/edit the file. This ensures the generated `.proto` and config output are always in sync with the input.

### Workflow

1. **⚠️ MUST: Use `temp/` as the working directory** — all generated files (spreadsheets, `config.yaml`, python scripts) go here. Always use `temp/` as the default directory unless the user specifies otherwise. **If `temp/` does not exist, create it automatically**.
2. **Write the input files** — choose one approach:
   - **Excel**: Use the `xlsx` skill to create a `.xlsx` file with proper sheets (`@TABLEAU` metasheet + data sheets). Excel is the native format and supports multiple sheets in one file.
   - **CSV**: Write `BookName#SheetName.csv` + `BookName#@TABLEAU.csv` files. Use this when the xlsx skill is not available.
   - **XML**: Write XML files following tableau's XML input schema.
   - **YAML**: Write YAML files following tableau's YAML input schema.

   > **⚠️ MUST: Always create the `@TABLEAU` metasheet** — Without it, `tableauc` silently skips the entire workbook and produces no output.
   > For **Excel**: create the `@TABLEAU` sheet as the **first** sheet in the workbook. If it already exists, modify it directly — do NOT recreate it.
   > For **CSV**: always create `BookName#@TABLEAU.csv`.

   > **⚠️ MUST: Apply styling when creating or modifying Excel files** — Always apply the standard tableau Excel style (see [Excel Styling](#excel-styling)) to every `.xlsx` file you create or modify. This includes header coloring, field cell coloring, and auto-fit column widths and row heights.

3. **⚠️ MUST: Ensure `config.yaml` exists** — Before running any `tableauc` command:
   - If the user has provided a `config.yaml` path, use it with `-c <path>`.
   - Otherwise, check whether `config.yaml` exists in the working directory.
     - If it **does not exist**: **read `references/config.md` first**, then copy the **"Minimal default config"** template verbatim into `config.yaml`. **Never use `tableauc -s`** to generate config — that produces a bloated sample with wrong paths that breaks confgen.
     - If it **already exists**: use it as-is.
4. **Run protogen + confgen** (both steps, always):
   ```bash
   tableauc -c config.yaml -m proto   # Step 1: generate .proto files
   tableauc -c config.yaml -m conf    # Step 2: generate JSON/conf files
   ```
5. **Show the user** the actual files produced

### CLI Quick Reference

```bash
tableauc -m proto                                           # protogen only: scan CWD for input files, write .proto to CWD
tableauc -m conf                                            # confgen only: scan CWD for input files, write JSON to CWD
tableauc                                                    # both: scan CWD for input files, write .proto + JSON to CWD
tableauc HelloWorld.xlsx                                    # quick convert single file

tableauc -s                                                 # dump sample config.yaml
tableauc -c config.yaml                                     # both via config
tableauc -c config.yaml -m proto  HelloWorld.xlsx           # protogen a specified file via config
tableauc -c config.yaml -m conf   HelloWorld.xlsx           # confgen a specified file via config
tableauc -c config.yaml -m proto  Hello.xlsx World.xlsx     # protogen multiple specified files via config
tableauc -c config.yaml -m conf   Hello.xlsx World.xlsx     # confgen multiple specified files via config
```

### Locating `tableauc`

1. Try `tableauc --version` first
2. If not found: `go install github.com/tableauio/tableau/cmd/tableauc@latest`

### Common config.yaml Keys

```yaml
locationName: "Asia/Shanghai" # timezone
proto.input.protoFiles: ["common.proto"] # predefined type imports
proto.input.protoPaths: ["."] # proto search paths
conf.output.formats: ["json"] # output: json, txtpb, binpb
conf.output.pretty: true # pretty-print JSON
```

See `references/config.md` for the full reference.

## Header Layout

| Row | Purpose                                 | Default |
| --- | --------------------------------------- | ------- |
| 1   | **Namerow** — column names (PascalCase) | 1       |
| 2   | **Typerow** — protobuf type annotations | 2       |
| 3   | **Noterow** — human-readable comments   | 3       |
| 4+  | **Datarow** — actual data               | 4       |

Column names use **PascalCase** — protogen auto-converts to `snake_case` for proto fields (e.g., `ItemName` -> `item_name`). Configure custom acronyms in config.yaml (`acronyms: {K8s: k8s}`).

> **⚠️ MUST: Noterow content rules (in priority order):**
>
> 1. **Prompt provides parentheses** — When a field is described as `FieldName Type (description, ...)`, use the text before the first comma verbatim as the noterow. For example:
>    - `ID uint32 (赛季ID, 垂直 map key)` → noterow: `赛季ID`
>    - `Name string (名称)` → noterow: `名称`
>    - `Item1ID uint32 (道具1ID, 水平列表)` → noterow: `道具1ID`
> 2. **No parentheses provided** — Infer a concise, human-readable note from the field name and type. Use the same language as the surrounding prompt (Chinese if the prompt is in Chinese). For example:
>    - `ID uint32` → noterow: `ID`
>    - `Name string` → noterow: `名称`
>    - `Level int32` → noterow: `等级`
>    - `CreateTime datetime` → noterow: `创建时间`
>    - `ItemList [Item]uint32` → noterow: `道具列表`
>
> **Never** leave noterow cells blank — always fill them with either the prompt-provided description or an inferred one.

Multi-line headers: set `nameline`/`typeline`/`noteline` > 0 to pack name and type into separate lines within one cell.

## Type Syntax Cheat Sheet

| Typerow Cell                              | Meaning                                          |
| ----------------------------------------- | ------------------------------------------------ |
| `uint32` / `int32` / `string` / `bool`    | Scalar                                           |
| `enum<.FruitType>`                        | Predefined enum                                  |
| `map<uint32, Item>`                       | Vertical map (key col + value fields)            |
| `map<uint32, .Item>`                      | Map with predefined struct value                 |
| `map<uint32, string>`                     | Incell scala