From faf179a4fdabc31742d81979b6c0b82bac73b5bf Mon Sep 17 00:00:00 2001 From: hypercross Date: Thu, 26 Mar 2026 11:24:28 +0800 Subject: [PATCH] docs: update --- README.md | 2 ++ docs/cli.md | 1 + docs/markdown.md | 70 +++++++++++++++++++++++++++++++++++++++++++++++- docs/mcp.md | 17 +++++++++--- 4 files changed, 85 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index eee1166..2a4f574 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,8 @@ ttrpg serve ./content | [📖 CLI 使用说明](./docs/cli.md) | CLI 安装、命令和用法 | | [🛠️ 开发指南](./docs/development.md) | 项目结构、开发规范和构建 | | [📝 Markdown 编写说明](./docs/markdown.md) | Markdown 语法和组件用法 | +| [📊 CSV 编写说明](./docs/csv.md) | CSV 文件格式、字段定义、变量语法 | +| [🤖 MCP 服务器说明](./docs/mcp.md) | AI 助手集成、卡牌生成工具 | ## 功能概览 diff --git a/docs/cli.md b/docs/cli.md index 9b63beb..d58d2c2 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -37,6 +37,7 @@ ttrpg serve [dir] -p 3000 | 选项 | 说明 | 默认值 | |------|------|--------| | `-p, --port ` | 端口号 | `3000` | +| `-h, --host ` | 主机地址 | `0.0.0.0` | **功能：** diff --git a/docs/markdown.md b/docs/markdown.md index ce2e596..0726c13 100644 --- a/docs/markdown.md +++ b/docs/markdown.md @@ -27,7 +27,7 @@ | `[content]` | 内容参数 | `[2d6+d8]` | | `{attrs}` | 属性对象 | `{key="attack"}` | -### 嵌套指令 +支持多个嵌套指令： ```markdown ::: container @@ -36,6 +36,40 @@ ::: ``` +## 分栏布局 + +使用简单的分隔符语法创建多栏布局： + +```markdown +|--- +左侧栏内容 +-|- +右侧栏内容 +--- +``` + +**语法说明：** + +| 分隔符 | 说明 | +|--------|------| +| `\|---` | 开始分栏容器 | +| `-|-` | 分隔各栏 | +| `---` | 结束分栏容器 | + +**多栏示例：** + +```markdown +|--- +第一栏 +-|- +第二栏 +-|-- +第三栏（更宽） +--- +``` + +`-|--` 中的额外 `-` 会添加 `-N` 后缀到 CSS 类名（如 `col-2`），可用于自定义宽度。 + ## 图标语法 使用简单的 `:[icon-name]` 语法插入图标： @@ -273,6 +307,27 @@ label,name,description :md-table[./quests.csv]{roll=true remix=true} ``` +**自动表格转换：** + +标准 Markdown 表格会自动转换为 `md-table` 组件，当表头包含 `label` 或 `md-table-label` 列时： + +```markdown +| label | name | description | +|-------|------|-------------| +| 1 | 战士 | 近战专家 | +| 2 | 法师 | 奥术施法者 | +``` + +自动转换为 `:md-table` 组件。 + +**特殊表头标识：** + +| 表头 | 效果 | +|------|------| +| `label` 或 `md-table-label` | 转换为 md-table | +| `md-roll-label` 或骰子格式（如 `1d6`） | 添加 `roll=true` | +| `md-remix-label` | 添加 `roll=true remix=true` | + ### 🃏 卡牌组件 (md-deck) ```markdown @@ -318,6 +373,19 @@ layers="字段：起始行，起始列 - 结束列，字体大小" :md-token[./token.png] ``` +### 🎨 代币预览组件 (md-token-viewer) + +用于 3D 预览 3MF 格式的代币模型。 + +```markdown +:md-token-viewer[./token.3mf] +``` + +**功能：** +- 使用 Three.js 渲染 3D 模型 +- 支持鼠标拖拽旋转 +- 自动旋转展示 + ### 📋 命令追踪器 (md-commander) 支持命令历史和状态追踪。 diff --git a/docs/mcp.md b/docs/mcp.md index 430125d..8a75013 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -230,9 +230,9 @@ ttrpg mcp generate-card-deck \ } ``` -#### `deck_ensure_preview` - 确保 Markdown 预览文件存在 +#### `deck_preview` - 保存并预览卡牌组 -确保 CSV 对应的 Markdown 预览文件存在，如果不存在则创建。 +保存 CSV 对应的 Markdown 预览文件并打开浏览器预览。 | 参数 | 类型 | 必需 | 说明 | |------|------|------|------| @@ -241,6 +241,15 @@ ttrpg mcp generate-card-deck \ | `title` | string | ✗ | 标题（可选，默认从 CSV 文件名推断） | | `description` | string | ✗ | 描述（可选） | +**返回示例：** +```json +{ + "success": true, + "message": "预览文件已创建", + "preview_url": "http://localhost:3000/#/content/cards.md" +} +``` + ## CSV 文件格式 CSV 文件使用 YAML frontmatter 定义模板和配置： @@ -475,7 +484,7 @@ Prompt 会引导 AI 助手配置： 1. **设计模板**：调用 `design-card-game` Prompt 引导设计字段结构 2. **定义模板**：调用 `deck_frontmatter_write` 创建 CSV 和 frontmatter -3. **创建预览**：调用 `deck_ensure_preview` 创建 Markdown 预览文件 +3. **创建预览**：调用 `deck_preview` 创建 Markdown 预览文件 4. **填充内容**：调用 `populate-deck` Prompt 引导生成卡牌内容 5. **添加卡牌**：调用 `deck_card_crud`（action=create）添加卡牌 6. **配置显示**：调用 `setup-deck-display` Prompt 配置显示参数 @@ -486,7 +495,7 @@ Prompt 会引导 AI 助手配置： 1. **读取模板**：调用 `deck_frontmatter_read` 获取当前配置 2. **读取卡牌**：调用 `deck_card_crud`（action=read）获取卡牌数据 3. **修改卡牌**：调用 `deck_card_crud`（action=update）更新卡牌 -4. **更新预览**：调用 `deck_ensure_preview` 更新 Markdown 文件 +4. **更新预览**：调用 `deck_preview` 更新 Markdown 文件 ### 快捷生成