hypercross/ttrpg-tools
2
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

fix: docs

Browse Source
This commit is contained in:
hypercross
2026-03-18 13:02:50 +08:00
parent 4f9d295bd5
commit 8213092bb6
3 changed files with 609 additions and 170 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/cli/commands/mcp.ts
-105
View File
@@ -90,111 +90,6 @@ async function mcpServeAction(host: string, options: MCPOptions) {
server.setRequestHandler(ListToolsRequestSchema, async () => {
return {
tools: [
{
name: 'generate_card_deck',
description: '生成 TTRPG 卡牌组内容，包括 Markdown 介绍文件、CSV 数据文件和 md-deck 组件配置（一站式快捷工具）',
inputSchema: {
type: 'object',
properties: {
deck_name: {
type: 'string',
description: '卡牌组名称，将用于生成文件名',
},
output_dir: {
type: 'string',
description: '输出目录路径（相对路径相对于 MCP 服务器工作目录）',
},
card_count: {
type: 'number',
description: '卡牌数量',
default: 10,
},
card_template: {
type: 'object',
description: '卡牌模板定义',
properties: {
fields: {
type: 'array',
description: '卡牌字段列表',
items: {
type: 'object',
properties: {
name: {
type: 'string',
description: '字段名称（英文，用于 CSV 列名）',
},
description: {
type: 'string',
description: '字段描述',
},
examples: {
type: 'array',
description: '示例值列表',
items: { type: 'string' },
},
},
required: ['name'],
},
},
examples: {
type: 'array',
description: '完整的卡牌示例数据',
items: {
type: 'object',
additionalProperties: { type: 'string' },
},
},
},
required: ['fields'],
},
deck_config: {
type: 'object',
description: 'md-deck 组件配置',
properties: {
size: {
type: 'string',
description: '卡牌尺寸，格式 "宽 x 高"（单位 mm）',
default: '54x86',
},
grid: {
type: 'string',
description: '网格布局，格式 "列 x 行"',
default: '5x8',
},
bleed: {
type: 'number',
description: '出血边距（mm）',
default: 1,
},
padding: {
type: 'number',
description: '内边距（mm）',
default: 2,
},
shape: {
type: 'string',
description: '卡牌形状',
enum: ['rectangle', 'circle', 'hex', 'diamond'],
default: 'rectangle',
},
layers: {
type: 'string',
description: '正面图层配置，格式 "字段：行，列范围，字体大小"',
},
back_layers: {
type: 'string',
description: '背面图层配置',
},
},
},
description: {
type: 'string',
description: '卡牌组的介绍描述（可选）',
},
},
required: ['deck_name', 'output_dir'],
},
},
{
name: 'deck_frontmatter_read',
description: '读取 CSV 文件的 frontmatter（包含模板定义和 deck 配置）',
src/cli/prompts/design-card-game.ts
+177 -65
View File
@@ -1,6 +1,6 @@
/**
* design-card-game Prompt
*
*
* 引导用户设计新的卡牌游戏系统，定义卡牌模板和字段结构
*/
@@ -55,6 +55,48 @@ export interface ResourceContent {
};
}
/**
* 数据类型
*/
export type DataType = 'word' | 'paragraph' | 'number' | 'symbol' | 'symbol_list';
/**
* 字段功能
*/
export type FieldFunction = 'identify' | 'compare' | 'flavor' | 'rule';
/**
* 字段定义
*/
export interface FieldDefinition {
name: string;
description: string;
dataType: DataType;
function: FieldFunction;
examples?: string[];
}
/**
* 数据类型说明
*/
const DATA_TYPE_DESCRIPTIONS: Record<DataType, string> = {
word: '词语 - 短文本（如名称、类型、职业等）',
paragraph: '文本段落 - 长描述（如效果说明、背景故事等）',
number: '数字 - 可比较的数值（如费用、强度、等级等）',
symbol: '单一符号 - 图标/标记（如阵营符号、元素标志等）',
symbol_list: '符号列表 - 多个图标/标记（如属性加成列表、技能图标等）'
};
/**
* 字段功能说明
*/
const FIELD_FUNCTION_DESCRIPTIONS: Record<FieldFunction, string> = {
identify: '辨识 - 用于识别卡牌身份（如名称、编号等）',
compare: '比较 - 用于游戏机制中的数值比较（如费用、攻击力等）',
flavor: '游戏风味描述 - 提供背景故事/氛围（如背景故事、引言等）',
rule: '规则确认 - 明确游戏规则相关的信息（如效果文本、触发条件等）'
};
/**
* 生成 design-card-game prompt 的消息
*/
@@ -77,80 +119,150 @@ export function designCardGame(options?: DesignCardGameOptions): DesignCardGameR
type: 'text',
text: `好的！我来帮你设计"${deckName}"卡牌组的字段结构。
首先，让我了解一些基本信息：
## 1. 卡牌类型
这个卡牌游戏主要包含什么类型的卡牌？（可多选）
- [ ] 角色卡（Characters）- 代表游戏中的人物或生物
- [ ] 物品卡（Items）- 装备、道具、消耗品等
- [ ] 法术/技能卡（Spells/Abilities）- 魔法、技能、动作等
- [ ] 地点卡（Locations）- 场景、区域、地图等
- [ ] 事件卡（Events）- 随机事件、剧情触发等
- [ ] 其他：_______
## 2. 核心机制
卡牌游戏的核心机制是什么？
- 是否有费用/资源系统？（如：法力值、行动点等）
- 是否有稀有度系统？（如：普通、稀有、史诗、传说）
- 是否有阵营/派系系统？
- 是否有等级/强度系统？
## 3. 卡牌信息
每张卡牌通常需要展示哪些信息？
- 卡牌名称（必填）
- 卡牌描述/效果（必填）
- 插画/图片（可选）
- 其他属性：_______
请告诉我你的选择，我会为你生成合适的字段结构。
我们将通过以下步骤完成设计：
---
**示例参考：**
## 步骤 1：列出卡牌属性
如果你想要快速开始，可以参考以下常见配置：
首先，请列出你的卡牌包含哪些属性（字段）。
### 魔法物品卡牌组
\`\`\`json
{
"fields": [
{"name": "name", "description": "物品名称"},
{"name": "type", "description": "物品类型", "examples": ["武器", "防具", "饰品", "消耗品"]},
{"name": "rarity", "description": "稀有度", "examples": ["普通", "稀有", "史诗", "传说"]},
{"name": "cost", "description": "价格/费用"},
{"name": "effect", "description": "效果描述"}
]
}
**思考方向：**
- 玩家看到这张卡牌时，需要知道什么信息？
- 游戏机制需要用到哪些数据？
- 哪些信息用于区分不同的卡牌？
- 哪些信息用于游戏过程中的判断？
**示例：**
- 名称、费用、类型、效果、稀有度...
---
## 步骤 2：定义每个属性的数据类型
对于每个属性，选择其数据类型：
| 类型 | 说明 | 示例 |
|------|------|------|
| word（词语） | 短文本 | "火球术"、"战士"、"传说" |
| paragraph（文本段落） | 长描述 | "造成 5d6 点火焰伤害，范围内的所有生物进行敏捷豁免" |
| number（数字） | 可比较的数值 | 3、5、10 |
| symbol（单一符号） | 图标/标记 | 🔥、⚔️、🛡️ |
| symbol_list（符号列表） | 多个图标/标记 | 🔥🔥🔥、⚔️🛡️💫 |
---
## 步骤 3：定义每个字段的功能
对于每个属性，说明其在游戏中的功能：
| 功能 | 说明 | 示例 |
|------|------|------|
| identify（辨识） | 用于识别卡牌身份 | 名称、编号、唯一标识 |
| compare（比较） | 用于游戏机制中的数值比较 | 费用、攻击力、防御力 |
| flavor（游戏风味描述） | 提供背景故事/氛围 | 背景故事、引言、 lore |
| rule（规则确认） | 明确游戏规则相关的信息 | 效果文本、触发条件、限制 |
---
## 步骤 4：关于插画/美术设计
**默认设定：** 卡牌的背景部分视为插画或精美的装帧设计，不需要在数据中定义插画字段。
如果你需要在卡牌上显示特定的图标或符号，请使用 symbol 或 symbol_list 类型。
---
## 回复格式
请按以下格式回复（可以复制模板填写）：
\`\`\`
### 属性 1：[属性名称]
- **描述**：[简短说明这个属性的用途]
- **数据类型**：[word/paragraph/number/symbol/symbol_list]
- **字段功能**：[identify/compare/flavor/rule]
- **示例值**：[2-3 个示例值]
### 属性 2：[属性名称]
...
\`\`\`
### NPC 角色卡牌组
\`\`\`json
{
"fields": [
{"name": "name", "description": "角色名称"},
{"name": "class", "description": "职业", "examples": ["战士", "法师", "盗贼", "牧师"]},
{"name": "level", "description": "等级"},
{"name": "background", "description": "背景故事"},
{"name": "ability", "description": "特殊能力"}
]
}
---
## 示例参考
### 魔法物品卡牌组
\`\`\`
### 属性 1：name（名称）
- **描述**：物品的名称
- **数据类型**：word
- **字段功能**：identify
- **示例值**：火球术卷轴、治疗药水、隐形斗篷
### 属性 2：cost（费用）
- **描述**：购买或使用该物品所需的资源
- **数据类型**：number
- **字段功能**：compare
- **示例值**：3、5、2
### 属性 3：type（类型）
- **描述**：物品的分类
- **数据类型**：word
- **字段功能**：identify
- **示例值**：武器、防具、饰品、消耗品
### 属性 4：rarity（稀有度）
- **描述**：物品的稀有程度
- **数据类型**：word
- **字段功能**：compare
- **示例值**：普通、稀有、史诗、传说
### 属性 5：effect（效果）
- **描述**：物品的效果或使用说明
- **数据类型**：paragraph
- **字段功能**：rule
- **示例值**：造成 5d6 点火焰伤害、恢复 2d4+2 点生命值
\`\`\`
### 塔罗牌组
\`\`\`json
{
"fields": [
{"name": "name", "description": "牌名"},
{"name": "number", "description": "编号"},
{"name": "element", "description": "元素", "examples": ["火", "水", "风", "土"]},
{"name": "meaning", "description": "含义"},
{"name": "reversed", "description": "逆位含义"}
]
}
\`\`\``
\`\`\`
### 属性 1：name（牌名）
- **描述**：塔罗牌的名称
- **数据类型**：word
- **字段功能**：identify
- **示例值**：愚者、魔术师、女祭司
### 属性 2：number（编号）
- **描述**：在大阿卡纳中的序号
- **数据类型**：number
- **字段功能**：identify
- **示例值**：0、1、2
### 属性 3：element（元素）
- **描述**：对应的元素
- **数据类型**：symbol
- **字段功能**：flavor
- **示例值**：🔥、💧、💨、🌍
### 属性 4：meaning（含义）
- **描述**：正位时的含义
- **数据类型**：paragraph
- **字段功能**：rule
- **示例值**：新的开始、冒险、自发性
### 属性 5：reversed（逆位含义）
- **描述**：逆位时的含义
- **数据类型**：paragraph
- **字段功能**：rule
- **示例值**：鲁莽、冒险导致的失败、缺乏计划
\`\`\`
---
请开始描述你的卡牌属性吧！`
}
}
];