ttrpg-tools/docs/csv.md

# CSV 编写说明

TTRPG Tools 使用带有 YAML Front Matter 的 CSV 格式来定义卡牌/表格数据。这种格式支持在 CSV 文件头部定义元数据、字段配置和共享属性。

## 文件结构

```csv
---
# YAML Front Matter（可选）
fields:
  - name: 字段名
    description: 字段描述
deck:
  size: 54x86
  grid: 5x8
shared_prop: 共享属性值
---
# CSV 数据
label,body,field1,field2
1，内容，值 1，值 2
```

---

## YAML Front Matter

Front Matter 是可选的，位于文件开头，使用 `---` 包裹的 YAML 格式内容。

### 基本结构

```yaml
---
fields:
  - name: name
    description: 卡牌名称
  - name: effect
    description: 效果描述
    examples: ["造成 5d6 伤害", "恢复 2d4 生命值"]
deck:
  size: 63x88
  grid: 5x5
  bleed: 1
  padding: 2
custom_prop: 自定义属性
---
```

### Front Matter 属性

#### `fields` - 字段定义

定义 CSV 中各列的含义和配置。

```yaml
fields:
  - name: name          # 字段名称（英文，用于 CSV 列名）
    description: 卡牌名称  # 字段描述
    examples:           # 示例值列表（可选）
      - 火球术卷轴
      - 治疗药水
    dataType: word      # 数据类型（可选）：word/paragraph/number/symbol/symbol_list
    function: identify  # 字段功能（可选）：identify/compare/flavor/rule
```

**数据类型说明：**

| 类型 | 说明 | 示例 |
|------|------|------|
| `word` | 词语 - 短文本 | "火球术"、"战士"、"传说" |
| `paragraph` | 文本段落 - 长描述 | "造成 5d6 点火焰伤害，范围内的所有生物进行敏捷豁免" |
| `number` | 数字 - 可比较的数值 | 3、5、10 |
| `symbol` | 单一符号 - 图标/标记 | 🔥、⚔️、🛡️ |
| `symbol_list` | 符号列表 - 多个图标/标记 | 🔥🔥🔥、⚔️🛡️💫 |

**字段功能说明：**

| 功能 | 说明 | 示例 |
|------|------|------|
| `identify` | 辨识 - 用于识别卡牌身份 | 名称、编号、唯一标识 |
| `compare` | 比较 - 用于游戏机制中的数值比较 | 费用、攻击力、防御力 |
| `flavor` | 游戏风味描述 - 提供背景故事/氛围 | 背景故事、引言、lore |
| `rule` | 规则确认 - 明确游戏规则相关的信息 | 效果文本、触发条件、限制 |

#### `deck` - 卡牌显示配置

用于 `:md-deck` 组件的默认配置。

```yaml
deck:
  size: 63x88           # 卡牌尺寸（mm），格式 "宽 x 高"
  grid: 5x5             # 网格布局，格式 "列 x 行"
  bleed: 1              # 出血边距（mm）
  padding: 2            # 内边距（mm）
  shape: rectangle      # 卡牌形状：rectangle/circle/hex/diamond
  layers: "name:1-2,14" # 图层配置（可选）
  back_layers: ""       # 背面图层配置（可选）
```

图层配置语法遵循`layer:1,1-5,8f8s`格式：
- `layer`：图层名称，多个图层用空格分隔
- `1,1-5,8`：网格范围，覆盖卡牌排版网格中的指定区域。
- `f8`：字体大小，使用8mm字体。可选。
- `s`：图层朝向，有nwse东西南北四种方向，描述文字上侧的朝向，默认为n北方。

#### 自定义属性

可以在 Front Matter 中定义任意自定义属性，这些属性会被自动应用到所有卡牌行。

```yaml
---
game_system: 龙与地下城 5e
author: DM_Name
version: 1.0
---
```

---

## CSV 数据部分

### 基本格式

```csv
label,body,field1,field2
1，内容，值 1，值 2
```

### 必需列

#### `label`

每行的唯一标识，用于查找和修改卡牌。

- 可以是数字：`1`, `2`, `3`
- 可以是文本：`card_001`, `npc_villager`
- 支持分组前缀：`forest_1`, `dungeon_1`

#### `body`

卡牌的主要内容，支持 Markdown 格式。

```csv
label,body
1,"### 标题

**加粗文本**

- 列表项 1
- 列表项 2"
```

### 可选列

除 `label` 和 `body` 外，可以定义任意自定义列，列名在 Front Matter 的 `fields` 中定义。

```csv
label,body,name,type,cost,effect
1，完整内容，火球术，法术，3，造成 5d6 火焰伤害
```

---

## 变量语法

在 `body` 列或 Front Matter 中，可以使用 `{{prop}}` 语法引用其他列的值或 Front Matter 中的属性。

### 引用同行其他列

```csv
label,body,adj,noun
1,"**{{adj}}** 的{{noun}}",高大，战士
2,"{{adj}}的{{noun}}",矮小，法师
```

渲染后：
- 第 1 行：**高大** 的战士
- 第 2 行：矮小的法师

### 引用 Front Matter 属性

```yaml
---
game_system: D&D 5e
author: DM_Name
---
```

```csv
label,body
1,"这是一个{{game_system}}冒险，由{{author}}创建"
```

渲染后：这是一个 D&D 5e 冒险，由 DM_Name 创建

### 随机引用（remix 模式）

在 `:md-table` 组件中，可以使用 `remix` 属性启用随机引用：

```markdown
:md-table[./data.csv]{remix=true}
```

此时 `{{prop}}` 会从所有行中随机选择一行的值，而不是使用当前行的值。

---

## 分组支持

可以使用额外的列来对数据进行分组。

```csv
group,label,body
森林小径，1，狼群袭击
森林小径，2，荆棘陷阱
森林小径，3，迷路
塔楼楼梯，1，台阶坍塌
塔楼楼梯，2，落石
```

在 `:md-table` 组件中，可以使用 `group` 属性来筛选显示特定组的数据：

```markdown
:md-table[./encounters.csv]{group="森林小径"}
```

---

## 特殊字符处理

### 包含逗号的值

使用双引号包裹：

```csv
label,body
1,"Hello, world"
```

### 包含双引号的值

使用两个双引号转义：

```csv
label,body
1,"他说：""你好"""
```

### 包含换行的值

使用双引号包裹，直接写入换行：

```csv
label,body
1,"### 标题

这是第一段

这是第二段"
```

### 包含 `#` 注释

CSV 解析器会将 `#` 开头的行视为注释，但如果 `#` 在双引号内则正常处理：

```csv
label,body
1,"# 这不是注释"
# 这是真正的注释
```

---

## 完整示例

### 示例 1：魔法物品卡牌组

```csv
---
fields:
  - name: name
    description: 物品名称
    dataType: word
    function: identify
  - name: type
    description: 物品类型
    dataType: word
    function: identify
    examples: [武器，防具，饰品，消耗品]
  - name: rarity
    description: 稀有度
    dataType: word
    function: compare
    examples: [普通，稀有，史诗，传说]
  - name: cost
    description: 价格
    dataType: number
    function: compare
  - name: effect
    description: 效果描述
    dataType: paragraph
    function: rule
deck:
  size: 63x88
  grid: 5x5
  shape: rectangle
game_system: D&D 5e
---
label,body,name,type,rarity,cost,effect
1,"### 火球术卷轴

一张泛黄的羊皮纸，上面绘有火焰符文。",火球术卷轴，消耗品，稀有，150,"投掷后对 20 尺内所有生物造成 8d6 火焰伤害（敏捷豁免减半）"
2,"### 治疗药水

红色液体在玻璃瓶中翻滚，散发着温暖的光芒。",治疗药水，消耗品，普通，50,"饮用后恢复 2d4+2 点生命值"
3,"### +1 长剑

剑刃闪烁着微光，握柄包裹着精致的皮革。",+1 长剑，武器，稀有，300,"攻击和伤害检定 +1"
```

### 示例 2：随机遭遇表

```csv
---
fields:
  - name: group
    description: 遭遇地点分组
  - name: title
    description: 遭遇标题
  - name: type
    description: 遭遇类型
deck:
  size: 54x86
  grid: 4x6
---
group,label,body,title,type
森林小径，1,"### 狼群袭击

三只灰狼从灌木丛中扑出。

**交互**：战斗（3 只巨狼）或逃脱（敏捷检定 3/2）

**风险**：失败受到 d8 撕咬伤害",狼群袭击，战斗
森林小径，2,"### 荆棘陷阱

带刺藤蔓缠住你的双腿。

**交互**：挣脱（力量检定 3/2）

**风险**：失败受到 1 点体质损伤",荆棘陷阱，陷阱
森林小径，3,"### 迷路

浓雾弥漫，你失去了方向。

**交互**：寻找路径（感知检定 3/2）

**风险**：失败受到 1 点感知损伤",迷路，事件
塔楼楼梯，1,"### 台阶坍塌

脚下的石阶突然碎裂。

**交互**：保持平衡（敏捷检定 3/1）

**风险**：失败受到 1 点敏捷损伤",台阶坍塌，陷阱
```

### 示例 3：NPC 名录

```csv
---
fields:
  - name: name
    description: NPC 名称
  - name: role
    description: 角色定位
  - name: location
    description: 出现地点
deck:
  size: 54x86
  grid: 4x6
---
label,body,name,role,location
1,"### 老妇人玛拉

**类型**：信息提供者/商人

**位置**：村庄入口

**出售**：草药、治疗药水

**情报**：知道关于森林的警告",老妇人玛拉，商人，村庄入口
2,"### 护卫队长塞里克

**类型**：任务发布者

**位置**：酒馆二楼

**任务**：调查废弃庄园

**秘密**：知道血契的真相",塞里克，任务发布者，酒馆
```

---

## 与组件集成

### `:md-deck` 组件

```markdown
:md-deck[./magic-items.csv]{size="63x88" grid="5x5" roll=true}
```

- `roll=true`：添加随机抽卡按钮

### `:md-table` 组件

```markdown
:md-table[./encounters.csv]{group="森林小径" remix=true}
```

- `group`：筛选特定组的数据
- `remix=true`：启用随机引用模式

---

## 最佳实践

1. **使用有意义的 label**：便于后续查找和修改
2. **在 Front Matter 中定义所有字段**：便于工具理解和处理
3. **使用 `{{prop}}` 变量**：减少重复内容，支持动态组合
4. **合理使用分组**：便于筛选和管理大量数据
5. **保持 body 的 Markdown 格式一致**：确保渲染效果统一
6. **为字段添加 `examples`**：帮助 AI 工具生成内容时参考