From 1d2b4b3e1e38297d43725cc8ba233d759b40869c Mon Sep 17 00:00:00 2001 From: hypercross Date: Wed, 18 Mar 2026 13:48:19 +0800 Subject: [PATCH] feat: layer docs --- src/cli/commands/mcp.ts | 8 +++--- src/cli/tools/frontmatter/read-frontmatter.ts | 27 +++++++++++++++++++ src/cli/tools/generate-card-deck.ts | 27 +++++++++++++++++++ 3 files changed, 58 insertions(+), 4 deletions(-) diff --git a/src/cli/commands/mcp.ts b/src/cli/commands/mcp.ts index 3440e17..a0f70f3 100644 --- a/src/cli/commands/mcp.ts +++ b/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: { diff --git a/src/cli/tools/frontmatter/read-frontmatter.ts b/src/cli/tools/frontmatter/read-frontmatter.ts index 4f405dc..509cebb 100644 --- a/src/cli/tools/frontmatter/read-frontmatter.ts +++ b/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; } diff --git a/src/cli/tools/generate-card-deck.ts b/src/cli/tools/generate-card-deck.ts index 1da0446..d15fc31 100644 --- a/src/cli/tools/generate-card-deck.ts +++ b/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; } /**