feat: layer docs

src/cli/commands/mcp.ts

@@ -144,12 +144,12 @@ async function mcpServeAction(host: string, options: MCPOptions) {
                     description: 'Deck 配置',
                     properties: {
                       size: { type: 'string', description: '卡牌尺寸，格式 "宽 x 高"' },
-                      grid: { type: 'string', description: '网格布局，格式 "列 x 行"' },
+                      grid: { type: 'string', description: '网格布局，格式 "列 x 行"，表示卡牌排版区域分成多少行多少列，用于显示字段。默认使用5x8。' },
                       bleed: { type: 'number', description: '出血边距（mm）' },
                       padding: { type: 'number', description: '内边距（mm）' },
                       shape: { type: 'string', enum: ['rectangle', 'circle', 'hex', 'diamond'] },
-                      layers: { type: 'string', description: '正面图层配置' },
-                      back_layers: { type: 'string', description: '背面图层配置' },
+                      layers: { type: 'string', description: '字段的显示图层配置。如`title:1,1-5,1f8n body:1,3-5,8f3n`表示将title字段的内容，显示在第1列1行到第5列1行的区域，8mm字体，上侧朝向北，body覆盖1列3行到5列行，3mm字体，上侧朝向北。通常希望重要的辨识字段放在左侧，如`rank:1,1-1,1f6 suit:1,2-1,2f6`。' },
+                      back_layers: { type: 'string', description: '背面显示图层配置，与正面类似' },
                     },
                   },
                 },
@@ -183,7 +183,7 @@ async function mcpServeAction(host: string, options: MCPOptions) {
                 description: '卡牌数据（单张或数组）',
                 items: {
                   type: 'object',
-                  additionalProperties: { type: 'string' },
+                  additionalProperties: { type: 'string', description: "字段内容可以使用markdown语法。使用:[attack]来表示名为attack的图标。使用{{prop}}来引用另一个字段，或者frontmatter里的内容。" },
                 },
               },
               label: {

src/cli/tools/frontmatter/read-frontmatter.ts

@@ -29,6 +29,32 @@ export interface DeckFrontmatter {
   [key: string]: unknown;
 }
 
+/**
+ * 字段样式配置
+ *
+ * 位置按照卡牌网格，安排 x,y,w,h 四个整数
+ * 如 5x8 网格中 1,1,5,8 表示覆盖整个卡牌的区域
+ *
+ * 字体使用 f:8 来表示 8mm 字体
+ *
+ * 朝向使用 u:n/w/s/e 表示字段的上侧朝向北西南东
+ */
+export interface CardFieldStyle {
+  /**
+   * 位置：[x, y, w, h] 网格坐标和尺寸
+   * 例如：[1, 1, 5, 8] 表示从 (1,1) 开始，宽 5 格，高 8 格
+   */
+  pos?: [number, number, number, number];
+  /**
+   * 字体大小：格式 "f:8" 表示 8mm 字体
+   */
+  font?: string;
+  /**
+   * 朝向：上侧朝向 "n" | "w" | "s" | "e"（北/西/南/东）
+   */
+  up?: 'n' | 'w' | 's' | 'e';
+}
+
 /**
  * 卡牌字段定义
  */
@@ -36,6 +62,7 @@ export interface CardField {
   name: string;
   description?: string;
   examples?: string[];
+  style?: CardFieldStyle;
   [key: string]: unknown;
 }
 

src/cli/tools/generate-card-deck.ts

@@ -1,6 +1,32 @@
 import { writeFileSync, mkdirSync, existsSync } from 'fs';
 import { join } from 'path';
 
+/**
+ * 字段样式配置
+ *
+ * 位置按照卡牌网格，安排 x,y,w,h 四个整数
+ * 如 5x8 网格中 1,1,5,8 表示覆盖整个卡牌的区域
+ *
+ * 字体使用 f:8 来表示 8mm 字体
+ *
+ * 朝向使用 u:n/w/s/e 表示字段的上侧朝向北西南东
+ */
+export interface CardFieldStyle {
+  /**
+   * 位置：[x, y, w, h] 网格坐标和尺寸
+   * 例如：[1, 1, 5, 8] 表示从 (1,1) 开始，宽 5 格，高 8 格
+   */
+  pos?: [number, number, number, number];
+  /**
+   * 字体大小：格式 "f:8" 表示 8mm 字体
+   */
+  font?: string;
+  /**
+   * 朝向：上侧朝向 "n" | "w" | "s" | "e"（北/西/南/东）
+   */
+  up?: 'n' | 'w' | 's' | 'e';
+}
+
 /**
  * 卡牌字段定义
  */
@@ -8,6 +34,7 @@ export interface CardField {
   name: string;
   description?: string;
   examples?: string[];
+  style?: CardFieldStyle;
 }
 
 /**