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

Compare commits

base: hypercross:c38d9bdc4f4da72bbd4338f48d1759b243ba4489
Branches Tags
hypercross:master
..
compare: hypercross:c071cad50a4f0786f6337629320c89fcca68a894
Branches Tags
hypercross:master

3 Commits
c38d9bdc4f ... c071cad50a

Author SHA1 Message Date
hyper c071cad50a refactor: Reformat code and update z-index class 
Reformat md-table.tsx to use double quotes and consistent code style.
Change z-index class in PrintPreview from `z-[60]` to `z-60`.
 2026-07-09 16:03:41 +08:00
hyper a20063c624 refactor(cli): Extract shared deck and frontmatter utils 
Create deck-utils.ts and frontmatter/shared.ts to consolidate
duplicated logic. Rename ensure-deck-preview.ts to preview-deck.ts.
 2026-07-09 14:31:08 +08:00
hyper 06c3916a95 feat: rename project to TTTK 
- Update package name and CLI binary to 'tttk'
- Revise documentation to reflect new name
- Add default serve behavior when no subcommand is given
- Add directory existence check in serve command
- Refactor inline comments to Chinese
 2026-07-09 14:14:45 +08:00
19 changed files with 722 additions and 959 deletions
Show Stats Expand all files Collapse all files

17
README.md
View File

@ -1,18 +1,12 @@
# TTRPG Tools # TTTK — Tabletop Toolkit
一个基于 `solid.js` 和 `rsbuild` 的 TTRPG 工具箱，支持 Markdown 解析、自定义组件和 CLI 工具。 A TTRPG content preview and compilation tool based on `solid.js` and `rsbuild`. Write markdown, preview in browser.
## 快速开始 ## 快速开始
```bash ```bash
# 安装依赖 # 无需安装，直接使用
npm install npx tttk serve ./content
# 全局安装 CLI
npm link
# 预览内容
ttrpg serve ./content
``` ```
## 文档导航 ## 文档导航
@ -20,6 +14,7 @@ ttrpg serve ./content
| 文档 | 说明 | | 文档 | 说明 |
|------|------| |------|------|
| [📖 CLI 使用说明](./docs/cli.md) | CLI 安装、命令和用法 | | [📖 CLI 使用说明](./docs/cli.md) | CLI 安装、命令和用法 |
| [📦 npm](https://www.npmjs.com/package/tttk) | `npx tttk serve ./content` |
| [🛠️ 开发指南](./docs/development.md) | 项目结构、开发规范和构建 | | [🛠️ 开发指南](./docs/development.md) | 项目结构、开发规范和构建 |
| [📝 Markdown 编写说明](./docs/markdown.md) | Markdown 语法和组件用法 | | [📝 Markdown 编写说明](./docs/markdown.md) | Markdown 语法和组件用法 |
| [📊 CSV 编写说明](./docs/csv.md) | CSV 文件格式、字段定义、变量语法 | | [📊 CSV 编写说明](./docs/csv.md) | CSV 文件格式、字段定义、变量语法 |
@ -27,7 +22,7 @@ ttrpg serve ./content
## 功能概览 ## 功能概览
- **CLI 工具**: `serve` 预览模式 和 `compile` 编译模式 - **CLI 工具**: `tttk serve` 预览模式 和 `tttk compile` 编译模式
- **Markdown 解析**: 支持指令语法、YAML 标签、mermaid 图表 - **Markdown 解析**: 支持指令语法、YAML 标签、mermaid 图表
- **TTRPG 组件**: 骰子、表格、卡牌、标记、命令追踪器等 - **TTRPG 组件**: 骰子、表格、卡牌、标记、命令追踪器等

32
docs/cli.md
View File

@ -1,18 +1,18 @@
# CLI 使用说明 # CLI 使用说明
TTRPG Tools 提供一个 CLI 工具，用于将目录内的各种 TTRPG 文档编译为 HTML。 TTTK 提供一个 CLI 工具，用于将目录内的各种 TTRPG 文档编译为 HTML。
## 安装 ## 安装
```bash ```bash
# 克隆仓库后安装依赖 # 无需安装，直接运行
npm install npx tttk serve ./content
# 全局链接 CLI 工具 # 或全局安装
npm link npm install -g tttk
``` ```
安装完成后，可在任意目录使用 `ttrpg` 命令。 安装完成后，可在任意目录使用 `tttk` 命令。
## 命令 ## 命令
@ -23,7 +23,7 @@ CLI 使用子命令组织：
运行一个 Web 服务器预览目录中的内容，并实时监听文件更新。 运行一个 Web 服务器预览目录中的内容，并实时监听文件更新。
```bash ```bash
ttrpg serve [dir] -p 3000 tttk serve [dir] -p 3000
``` ```
**参数：** **参数：**
@ -50,13 +50,13 @@ ttrpg serve [dir] -p 3000
```bash ```bash
# 预览当前目录 # 预览当前目录
ttrpg serve tttk serve
# 预览指定目录 # 预览指定目录
ttrpg serve ./my-ttrpg-content tttk serve ./my-ttrpg-content
# 指定端口 # 指定端口
ttrpg serve ./docs -p 8080 tttk serve ./docs -p 8080
``` ```
### compile - 编译模式 ### compile - 编译模式
@ -64,7 +64,7 @@ ttrpg serve ./docs -p 8080
将目录中的内容输出为带 hash 路由、单个 HTML 入口的 Web 应用。 将目录中的内容输出为带 hash 路由、单个 HTML 入口的 Web 应用。
```bash ```bash
ttrpg compile [dir] -o ./dist/output tttk compile [dir] -o ./dist/output
``` ```
**参数：** **参数：**
@ -90,13 +90,13 @@ ttrpg compile [dir] -o ./dist/output
```bash ```bash
# 编译当前目录 # 编译当前目录
ttrpg compile tttk compile
# 编译指定目录并输出到指定位置 # 编译指定目录并输出到指定位置
ttrpg compile ./content -o ./build tttk compile ./content -o ./build
# 编译并部署 # 编译并部署
ttrpg compile ./docs -o ./public && npm run preview tttk compile ./docs -o ./public && npm run preview
``` ```
## 输入文件 ## 输入文件
@ -162,7 +162,7 @@ my-ttrpg-content/
```bash ```bash
# 使用其他端口 # 使用其他端口
ttrpg serve -p 8080 tttk serve -p 8080
``` ```
### 编译输出为空 ### 编译输出为空
@ -174,5 +174,5 @@ ttrpg serve -p 8080
ls -R ./content ls -R ./content
# 重新编译 # 重新编译
ttrpg compile ./content -o ./dist/output tttk compile ./content -o ./dist/output
``` ```

2
docs/development.md
View File

@ -28,7 +28,7 @@ npm test
## 项目结构 ## 项目结构
``` ```
ttrpg-tools/ tttk/
├── src/ ├── src/
│ ├── cli/ # CLI 工具源码 │ ├── cli/ # CLI 工具源码
│ │ ├── commands/ # 命令实现 (serve, compile) │ │ ├── commands/ # 命令实现 (serve, compile)

3
docs/mcp.md
View File

@ -535,7 +535,8 @@ src/cli/
│ │ └── write-frontmatter.ts │ │ └── write-frontmatter.ts
│ ├── card/ │ ├── card/
│ │ └── card-crud.ts │ │ └── card-crud.ts
│ ├── ensure-deck-preview.ts │ ├── deck-utils.ts
│ ├── preview-deck.ts
│ └── generate-card-deck.ts │ └── generate-card-deck.ts
└── index.ts └── index.ts
``` ```

8
package.json
View File

@ -1,11 +1,10 @@
{ {
"name": "ttrpg-tools", "name": "tttk",
"version": "0.0.1", "version": "0.0.1",
"description": "A tabletop RPG toolbox based on solid.js and rsbuild", "description": "A tabletop RPG toolkit for previewing and compiling TTRPG campaign content",
"type": "module", "type": "module",
"bin": { "bin": {
"ttrpg": "./dist/cli/index.js", "tttk": "./dist/cli/index.js"
"ttt": "./dist/cli/index.js"
}, },
"main": "./dist/index.js", "main": "./dist/index.js",
"module": "./dist/index.js", "module": "./dist/index.js",
@ -22,6 +21,7 @@
"cli:dev": "tsc -p tsconfig.cli.json --watch", "cli:dev": "tsc -p tsconfig.cli.json --watch",
"cli:build": "tsc -p tsconfig.cli.json", "cli:build": "tsc -p tsconfig.cli.json",
"ttrpg": "node --loader ts-node/esm ./src/cli/index.ts", "ttrpg": "node --loader ts-node/esm ./src/cli/index.ts",
"tttk": "node --loader ts-node/esm ./src/cli/index.ts",
"test": "jest", "test": "jest",
"prepare": "npx husky" "prepare": "npx husky"
}, },

8
src/cli/commands/compile.ts
View File

@ -1,8 +1,8 @@
import type { CompileCommandHandler } from '../types.js'; import type { CompileCommandHandler } from "../types.js";
export const compileCommand: CompileCommandHandler = async (dir, options) => { export const compileCommand: CompileCommandHandler = async (dir, options) => {
console.log(`开始编译...`); console.log("开始编译...");
console.log(`目录：${dir}`); console.log(`源目录：${dir}`);
console.log(`输出目录：${options.output}`); console.log(`输出目录：${options.output}`);
// TODO: 实现编译逻辑 // TODO: 实现编译逻辑
@ -10,5 +10,5 @@ export const compileCommand: CompileCommandHandler = async (dir, options) => {
// 2. 解析 markdown 并生成路由 // 2. 解析 markdown 并生成路由
// 3. 打包为带 hash 路由的单个 HTML 入口 // 3. 打包为带 hash 路由的单个 HTML 入口
console.log('编译完成！'); console.log("编译完成！");
}; };

52
src/cli/commands/serve.ts
View File

@ -22,14 +22,14 @@ interface ContentIndex {
} }
/** /**
* 获取 CLI 脚本文件所在目录路径（用于定位 dist 文件夹） * 获取 CLI 脚本文件所在目录路径（用于定位 dist 目录）
*/ */
const __filename = fileURLToPath(import.meta.url); const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename); const __dirname = dirname(__filename);
const distDir = resolve(__dirname, "..", "..", "..", "dist", "web"); const distDir = resolve(__dirname, "..", "..", "..", "dist", "web");
/** /**
* MIME 类型映射 * MIME 类型映射表
*/ */
const MIME_TYPES: Record<string, string> = { const MIME_TYPES: Record<string, string> = {
".html": "text/html", ".html": "text/html",
@ -48,7 +48,7 @@ const MIME_TYPES: Record<string, string> = {
}; };
/** /**
* 获取文件扩展名对应的 MIME 类型 * 根据文件扩展名获取对应的 MIME 类型
*/ */
function getMimeType(filePath: string): string { function getMimeType(filePath: string): string {
const ext = extname(filePath).toLowerCase(); const ext = extname(filePath).toLowerCase();
@ -56,7 +56,7 @@ function getMimeType(filePath: string): string {
} }
/** /**
* Get the best network IP for display (prefer LAN IPv4, fallback to localhost). * 获取最佳网络 IP 用于显示（优先局域网 IPv4，回退到 localhost）
*/ */
function getBestIP(): string { function getBestIP(): string {
const interfaces = networkInterfaces(); const interfaces = networkInterfaces();
@ -85,7 +85,7 @@ function getBestIP(): string {
} }
/** /**
* Extract the <title> from an SVG string, or null if absent. * 从 SVG 字符串中提取 <title> 内容，无则返回 null
*/ */
function extractSvgTitle(svg: string): string | null { function extractSvgTitle(svg: string): string | null {
const m = /<title[^>]*>([\s\S]*?)<\/title>/i.exec(svg); const m = /<title[^>]*>([\s\S]*?)<\/title>/i.exec(svg);
@ -93,17 +93,15 @@ function extractSvgTitle(svg: string): string | null {
} }
/** /**
* Derive a human-readable label from a filename. * 从文件名生成可读标签
* "character-sheet" -> "Character Sheet" * 如 "character-sheet" -> "Character Sheet"
*/ */
function labelFromId(id: string): string { function labelFromId(id: string): string {
return id return id.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
.replace(/[-_]/g, " ")
.replace(/\b\w/g, (c) => c.toUpperCase());
} }
/** /**
* 扫描目录内的 .md 文件，生成索引 * 扫描目录内的 .md 等文件，生成内容索引与块数据
*/ */
export function scanDirectory(dir: string): { export function scanDirectory(dir: string): {
index: ContentIndex; index: ContentIndex;
@ -170,7 +168,7 @@ export function scanDirectory(dir: string): {
} }
/** /**
* 发送文件响应 * 发送文件响应（流式传输）
*/ */
function sendFile(res: ServerResponse, filePath: string) { function sendFile(res: ServerResponse, filePath: string) {
res.writeHead(200, { res.writeHead(200, {
@ -181,7 +179,7 @@ function sendFile(res: ServerResponse, filePath: string) {
} }
/** /**
* 发送 404 响应 * 发送 404 未找到响应
*/ */
function send404(res: ServerResponse) { function send404(res: ServerResponse) {
res.writeHead(404, { "Content-Type": "text/plain" }); res.writeHead(404, { "Content-Type": "text/plain" });
@ -189,7 +187,7 @@ function send404(res: ServerResponse) {
} }
/** /**
* 发送 JSON 响应 * 发送 JSON 格式的响应
*/ */
function sendJson(res: ServerResponse, data: unknown) { function sendJson(res: ServerResponse, data: unknown) {
res.writeHead(200, { res.writeHead(200, {
@ -201,7 +199,7 @@ function sendJson(res: ServerResponse, data: unknown) {
/** /**
* 尝试提供静态文件 * 尝试提供静态文件
* @returns 如果文件存在并已成功发送则返回 true * @returns 文件存在并成功发送时返回 true
*/ */
function tryServeStatic( function tryServeStatic(
res: ServerResponse, res: ServerResponse,
@ -224,7 +222,7 @@ function tryServeStatic(
} }
/** /**
* 创建请求处理器 * 创建 HTTP 请求处理器
*/ */
function createRequestHandler( function createRequestHandler(
contentDir: string, contentDir: string,
@ -274,7 +272,7 @@ function createRequestHandler(
} }
/** /**
* 内容服务器接口 * 内容服务器实例接口
*/ */
export interface ContentServer { export interface ContentServer {
/** /**
@ -300,7 +298,7 @@ export interface ContentServer {
} }
/** /**
* 创建内容服务器 * 创建内容服务器（HTTP + WebSocket + 文件监听）
*/ */
export function createContentServer( export function createContentServer(
contentDir: string, contentDir: string,
@ -324,7 +322,7 @@ export function createContentServer(
statSheets: [], statSheets: [],
}; };
/** Re-scan completions from current content index and collected blocks */ /** 从当前内容索引和已收集的块重新扫描补全数据 */
function recomputeCompletions(): void { function recomputeCompletions(): void {
completionsIndex = scanCompletions(contentIndex, collectedBlocks); completionsIndex = scanCompletions(contentIndex, collectedBlocks);
console.log( console.log(
@ -333,7 +331,7 @@ export function createContentServer(
} }
// 扫描内容目录生成索引 // 扫描内容目录生成索引
console.log("扫描内容目录..."); console.log("正在扫描内容目录...");
const scanResult = scanDirectory(contentDir); const scanResult = scanDirectory(contentDir);
contentIndex = scanResult.index; contentIndex = scanResult.index;
collectedBlocks = scanResult.blocks; collectedBlocks = scanResult.blocks;
@ -341,7 +339,7 @@ export function createContentServer(
recomputeCompletions(); recomputeCompletions();
// 监听文件变化 // 监听文件变化
console.log("监听文件变化..."); console.log("正在监听文件变化...");
const watcher = watch(contentDir, { const watcher = watch(contentDir, {
ignored: /(^|[\/\\])\./, ignored: /(^|[\/\\])\./,
persistent: true, persistent: true,
@ -431,7 +429,7 @@ export function createContentServer(
// ---- Journal / MQTT broker ---- // ---- Journal / MQTT broker ----
let journal: Awaited<ReturnType<typeof createJournalServer>> | null = null; let journal: Awaited<ReturnType<typeof createJournalServer>> | null = null;
// 创建 HTTP 服务器 BEFORE journal so we can pass it in // 在 journal 之前创建 HTTP 服务器，以便传入给 journal
const handleRequest = createRequestHandler( const handleRequest = createRequestHandler(
contentDir, contentDir,
distPath, distPath,
@ -454,7 +452,7 @@ export function createContentServer(
} }
console.log(`内容目录：${contentDir}`); console.log(`内容目录：${contentDir}`);
console.log(`静态资源目录：${distPath}`); console.log(`静态资源目录：${distPath}`);
console.log(`Journal 连接：ws://${bestIP}:${port}\n`); console.log(`日志连接：ws://${bestIP}:${port}\n`);
}); });
return { return {
@ -463,7 +461,7 @@ export function createContentServer(
index: contentIndex, index: contentIndex,
completions: completionsIndex, completions: completionsIndex,
close() { close() {
console.log("关闭内容服务器..."); console.log("正在关闭内容服务器...");
server.close(); server.close();
watcher.close(); watcher.close();
if (journal) journal.close(); if (journal) journal.close();
@ -476,6 +474,12 @@ export function createContentServer(
*/ */
export const serveCommand: ServeCommandHandler = async (dir, options) => { export const serveCommand: ServeCommandHandler = async (dir, options) => {
const contentDir = resolve(dir); const contentDir = resolve(dir);
if (!existsSync(contentDir)) {
console.error(`错误：目录不存在：${contentDir}`);
process.exit(1);
}
const port = parseInt(options.port, 10); const port = parseInt(options.port, 10);
const host = options.host || "0.0.0.0"; const host = options.host || "0.0.0.0";

29
src/cli/index.ts
View File

@ -8,25 +8,42 @@ import type { ServeOptions, CompileOptions } from "./types.js";
const program = new Command(); const program = new Command();
program program
.name("ttrpg") .name("tttk")
.description("TTRPG 工具箱 - 用于编译和预览 TTRPG 文档") .description(
"TTRPG 内容预览服务器。不带参数运行时默认启动当前目录的预览服务。",
)
.version("0.0.1"); .version("0.0.1");
program program
.command("serve") .command("serve")
.description("运行一个 web 服务器预览目录中的内容，并实时监听更新") .description("启动 web 服务器预览目录中的内容，并实时监听文件更新")
.argument("[dir]", "要预览的目录", ".") .argument("[dir]", "要预览的目录", ".")
.option("-p, --port <port>", "HTTP 端口号", "3000") .option("-p, --port <port>", "HTTP 端口号", "3000")
.option("-h, --host <host>", "主机地址", "0.0.0.0") .option("--host <host>", "主机地址", "0.0.0.0")
.action(serveCommand); .action(serveCommand);
program program
.command("compile") .command("compile")
.description("将目录中的内容输出为带 hash 路由、单个 html 入口的 web 应用") .description("[实验性] 将目录内容编译为带 hash 路由的单页 Web 应用 (开发中)")
.argument("[dir]", "要编译的目录", ".") .argument("[dir]", "要编译的目录", ".")
.option("-o, --output <dir>", "输出目录", "./dist/output") .option("-o, --output <dir>", "输出目录", "./dist/output")
.action(compileCommand); .action(compileCommand);
program.addCommand(mcpCommand); program.addCommand(mcpCommand);
program.parse(); // 无子命令时默认执行 serve（即 `npx tttk` 等同于 `npx tttk serve .`）
const args = process.argv.slice(2);
if (args.length > 0) {
const first = args[0];
const isKnownCommand =
!first.startsWith("-") &&
program.commands.some(
(c) => c.name() === first || c.aliases().includes(first),
);
if (!isKnownCommand) {
args.unshift("serve");
}
} else {
args.unshift("serve");
}
program.parse([process.argv[0], process.argv[1], ...args]);

54
src/cli/journal.ts
View File

@ -1,14 +1,14 @@
/** /**
* Journal stream persistence — MQTT broker + JSONL append + session manifest * 日志流持久化 — MQTT 代理 + JSONL 追加写入 + 会话清单
* *
* Runs an aedes MQTT broker over WebSocket, attached to the existing * 在现有 HTTP 服务器上挂载 aedes MQTT 代理（WebSocket 传输），
* HTTP server. Uses ws v8's built-in createWebSocketStream. * 使用 ws v8 内置的 createWebSocketStream。
* *
* Pattern from aedes docs: * 实现参考 aedes 文档：
* https://github.com/moscajs/aedes#mqtt-server-over-websocket * https://github.com/moscajs/aedes#mqtt-server-over-websocket
* *
* Persistence uses aedes's internal subscribe/publish API, so the * 持久化使用 aedes 内部 subscribe/publish API，无需服务器进程
* server process doesn't need to connect to itself as an MQTT client. * 以 MQTT 客户端身份连接自身。
*/ */
import { join, resolve } from "path"; import { join, resolve } from "path";
@ -26,7 +26,7 @@ import type { AedesPublishPacket } from "aedes";
import { WebSocketServer, createWebSocketStream } from "ws"; import { WebSocketServer, createWebSocketStream } from "ws";
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
// Types // 类型定义
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
interface SessionMeta { interface SessionMeta {
@ -46,7 +46,7 @@ export interface JournalServer {
} }
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
// Path helpers // 路径工具函数
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
function dataDir(contentDir: string): string { function dataDir(contentDir: string): string {
@ -88,7 +88,7 @@ function appendStream(dataRoot: string, id: string, line: string): void {
} }
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
// Server factory // 服务器工厂
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
const $SESSIONS = "ttrpg/$SESSIONS"; const $SESSIONS = "ttrpg/$SESSIONS";
@ -98,15 +98,15 @@ export async function createJournalServer(
httpServer: HttpServer, httpServer: HttpServer,
): Promise<JournalServer> { ): Promise<JournalServer> {
const root = dataDir(contentDir); const root = dataDir(contentDir);
console.log(`[journal] data dir: ${root}`); console.log(`[日志] 数据目录：${root}`);
// ---- MQTT Broker ---- // ---- MQTT 代理 ----
const { Aedes: AedesFactory } = await import("aedes"); const { Aedes: AedesFactory } = await import("aedes");
// aedes requires listen() to initialize persistence before handling connections. // aedes 需要先 listen() 初始化持久化，再处理连接
const broker = await AedesFactory.createBroker(); const broker = await AedesFactory.createBroker();
// ---- WebSocket server (attached to the existing HTTP server) ---- // ---- WebSocket 服务器（挂载到现有 HTTP 服务器上） ----
// Pattern from aedes docs: pass { server } to WSS, use 'connection' event // 参考 aedes 文档：给 WSS 传入 { server }，使用 'connection' 事件
const wss = new WebSocketServer({ server: httpServer }); const wss = new WebSocketServer({ server: httpServer });
wss.on("connection", (ws, req) => { wss.on("connection", (ws, req) => {
@ -115,13 +115,13 @@ export async function createJournalServer(
}); });
broker.on("client", (client: import("aedes").Client) => { broker.on("client", (client: import("aedes").Client) => {
console.log(`[journal] client ready: ${client.id}`); console.log(`[日志] 客户端已连接：${client.id}`);
}); });
broker.on("clientDisconnect", (client: import("aedes").Client) => { broker.on("clientDisconnect", (client: import("aedes").Client) => {
console.log(`[journal] client disconnected: ${client.id}`); console.log(`[日志] 客户端已断开：${client.id}`);
}); });
// ---- Persistence (internal subscribe, no separate MQTT client) ---- // ---- 持久化（内部订阅，无需独立 MQTT 客户端） ----
broker.subscribe( broker.subscribe(
"ttrpg/+/stream", "ttrpg/+/stream",
(packet, cb) => { (packet, cb) => {
@ -130,7 +130,7 @@ export async function createJournalServer(
try { try {
appendStream(root, sessionId, packet.payload.toString()); appendStream(root, sessionId, packet.payload.toString());
} catch (e) { } catch (e) {
console.error(`[journal] stream append err for ${sessionId}:`, e); console.error(`[日志] 会话 ${sessionId} 流记录写入失败：`, e);
} }
} }
cb(); cb();
@ -150,7 +150,7 @@ export async function createJournalServer(
() => {}, () => {},
); );
// Publish the initial manifest on startup so clients see existing sessions // 启动时发布初始清单，让客户端能看到已有会话
const initialManifest = loadManifest(root); const initialManifest = loadManifest(root);
broker.publish( broker.publish(
{ {
@ -164,14 +164,14 @@ export async function createJournalServer(
() => {}, () => {},
); );
console.log("[journal] persistence listener active"); console.log("[日志] 持久化监听已启动");
console.log("[journal] broker available at ws://<host>:<port>"); console.log("[日志] MQTT 代理已就绪：ws://<host>:<port>");
return { return {
broker, broker,
wsServer: wss, wsServer: wss,
async close() { async close() {
console.log("[journal] shutting down..."); console.log("[日志] 正在关闭...");
await new Promise<void>((r) => wss.close(() => r())); await new Promise<void>((r) => wss.close(() => r()));
await new Promise<void>((r) => broker.close(() => r())); await new Promise<void>((r) => broker.close(() => r()));
}, },
@ -179,7 +179,7 @@ export async function createJournalServer(
} }
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
// Helpers // 工具函数
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
function extractSessionId(topic: string): string | null { function extractSessionId(topic: string): string | null {
@ -188,7 +188,7 @@ function extractSessionId(topic: string): string | null {
} }
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
// Session lifecycle // 会话生命周期管理
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
function handleMetaChange( function handleMetaChange(
@ -212,7 +212,7 @@ function handleMetaChange(
} catch { } catch {
/* */ /* */
} }
console.log(`[journal] session deleted: ${sessionId}`); console.log(`[日志] 会话已删除：${sessionId}`);
} }
} else { } else {
manifest.sessions[sessionId] = { manifest.sessions[sessionId] = {
@ -220,7 +220,7 @@ function handleMetaChange(
created: meta.created || Date.now(), created: meta.created || Date.now(),
players: meta.players || [], players: meta.players || [],
}; };
console.log(`[journal] session updated: ${sessionId} (${meta.name})`); console.log(`[日志] 会话已更新：${sessionId} (${meta.name})`);
} }
saveManifest(root, manifest); saveManifest(root, manifest);
@ -236,6 +236,6 @@ function handleMetaChange(
() => {}, () => {},
); );
} catch (e) { } catch (e) {
console.error(`[journal] meta parse err for ${sessionId}:`, e); console.error(`[日志] 会话 ${sessionId} 元数据解析失败：`, e);
} }
} }

144
src/cli/tools/card/card-crud.ts
View File

@ -1,8 +1,11 @@
import { readFileSync, writeFileSync, existsSync } from 'fs'; import { readFileSync, writeFileSync, existsSync } from "fs";
import { parse } from 'csv-parse/browser/esm/sync'; import { parse } from "csv-parse/browser/esm/sync";
import { stringify } from 'csv-stringify/browser/esm/sync'; import { stringify } from "csv-stringify/browser/esm/sync";
import yaml from 'js-yaml'; import type { DeckFrontmatter } from "../frontmatter/read-frontmatter.js";
import type { DeckFrontmatter } from '../frontmatter/read-frontmatter.js'; import {
parseFrontMatter,
serializeFrontMatter,
} from "../frontmatter/shared.js";
/** /**
* 卡牌数据 * 卡牌数据
@ -23,7 +26,7 @@ export interface CardCrudParams {
/** /**
* 操作类型 * 操作类型
*/ */
action: 'create' | 'read' | 'update' | 'delete'; action: "create" | "read" | "update" | "delete";
/** /**
* 卡牌数据（单张或数组） * 卡牌数据（单张或数组）
*/ */
@ -44,41 +47,6 @@ export interface CardCrudResult {
count?: number; count?: number;
} }
/**
* 解析 CSV 文件的 frontmatter
*/
function parseFrontMatter(content: string): { frontmatter?: DeckFrontmatter; csvContent: string } {
const parts = content.trim().split(/(?:^|\n)---\s*\n/g);
if (parts.length !== 3 || parts[0] !== '') {
return { csvContent: content };
}
try {
const frontmatterStr = parts[1].trim();
const frontmatter = yaml.load(frontmatterStr) as DeckFrontmatter | undefined;
const csvContent = parts.slice(2).join('---\n').trimStart();
return { frontmatter, csvContent };
} catch (error) {
console.warn('Failed to parse front matter:', error);
return { csvContent: content };
}
}
/**
* 序列化 frontmatter 为 YAML 字符串
*/
function serializeFrontMatter(frontmatter: DeckFrontmatter): string {
const yamlStr = yaml.dump(frontmatter, {
indent: 2,
lineWidth: -1,
noRefs: true,
quotingType: '"',
forceQuotes: false
});
return `---\n${yamlStr}---\n`;
}
/** /**
* 加载 CSV 数据（包含 frontmatter） * 加载 CSV 数据（包含 frontmatter）
*/ */
@ -87,19 +55,19 @@ function loadCSVWithFrontmatter(filePath: string): {
records: CardData[]; records: CardData[];
headers: string[]; headers: string[];
} { } {
const content = readFileSync(filePath, 'utf-8'); const content = readFileSync(filePath, "utf-8");
const { frontmatter, csvContent } = parseFrontMatter(content); const { frontmatter, csvContent } = parseFrontMatter(content);
const records = parse(csvContent, { const records = parse(csvContent, {
columns: true, columns: true,
comment: '#', comment: "#",
trim: true, trim: true,
skipEmptyLines: true skipEmptyLines: true,
}) as CardData[]; }) as CardData[];
// 获取表头 // 获取表头
const firstLine = csvContent.split('\n')[0]; const firstLine = csvContent.split("\n")[0];
const headers = firstLine.split(',').map(h => h.trim()); const headers = firstLine.split(",").map((h) => h.trim());
return { frontmatter, records, headers }; return { frontmatter, records, headers };
} }
@ -111,30 +79,30 @@ function saveCSVWithFrontmatter(
filePath: string, filePath: string,
frontmatter: DeckFrontmatter | undefined, frontmatter: DeckFrontmatter | undefined,
records: CardData[], records: CardData[],
headers?: string[] headers?: string[],
): void { ): void {
// 序列化 frontmatter // 序列化 frontmatter
const frontmatterStr = frontmatter ? serializeFrontMatter(frontmatter) : ''; const frontmatterStr = frontmatter ? serializeFrontMatter(frontmatter) : "";
// 确定表头 // 确定表头
if (!headers || headers.length === 0) { if (!headers || headers.length === 0) {
// 从 records 和 frontmatter.fields 推断表头 // 从 records 和 frontmatter.fields 推断表头
headers = ['label']; headers = ["label"];
if (frontmatter?.fields && Array.isArray(frontmatter.fields)) { if (frontmatter?.fields && Array.isArray(frontmatter.fields)) {
for (const field of frontmatter.fields) { for (const field of frontmatter.fields) {
if (field.name && typeof field.name === 'string') { if (field.name && typeof field.name === "string") {
headers.push(field.name); headers.push(field.name);
} }
} }
} }
headers.push('body'); headers.push("body");
} }
// 确保所有 record 都有 headers 中的列 // 确保所有 record 都有 headers 中的列
for (const record of records) { for (const record of records) {
for (const header of headers) { for (const header of headers) {
if (!(header in record)) { if (!(header in record)) {
record[header] = ''; record[header] = "";
} }
} }
} }
@ -142,11 +110,11 @@ function saveCSVWithFrontmatter(
// 序列化 CSV // 序列化 CSV
const csvContent = stringify(records, { const csvContent = stringify(records, {
header: true, header: true,
columns: headers columns: headers,
}); });
// 写入文件 // 写入文件
writeFileSync(filePath, frontmatterStr + csvContent, 'utf-8'); writeFileSync(filePath, frontmatterStr + csvContent, "utf-8");
} }
/** /**
@ -167,10 +135,10 @@ export function cardCrud(params: CardCrudParams): CardCrudResult {
const { csv_file, action, cards, label } = params; const { csv_file, action, cards, label } = params;
// 检查文件是否存在（create 操作可以不存在） // 检查文件是否存在（create 操作可以不存在）
if (action !== 'create' && !existsSync(csv_file)) { if (action !== "create" && !existsSync(csv_file)) {
return { return {
success: false, success: false,
message: `文件不存在：${csv_file}` message: `文件不存在：${csv_file}`,
}; };
} }
@ -189,8 +157,8 @@ export function cardCrud(params: CardCrudParams): CardCrudResult {
// 执行操作 // 执行操作
switch (action) { switch (action) {
case 'create': { case "create": {
const newCards = Array.isArray(cards) ? cards : (cards ? [cards] : []); const newCards = Array.isArray(cards) ? cards : cards ? [cards] : [];
for (const card of newCards) { for (const card of newCards) {
if (!card.label) { if (!card.label) {
card.label = generateNextLabel(records); card.label = generateNextLabel(records);
@ -202,16 +170,22 @@ export function cardCrud(params: CardCrudParams): CardCrudResult {
success: true, success: true,
message: `成功创建 ${newCards.length} 张卡牌`, message: `成功创建 ${newCards.length} 张卡牌`,
cards: newCards, cards: newCards,
count: newCards.length count: newCards.length,
}; };
} }
case 'read': { case "read": {
const labelsToRead = Array.isArray(label) ? label : (label ? [label] : null); const labelsToRead = Array.isArray(label)
? label
: label
? [label]
: null;
let resultCards: CardData[]; let resultCards: CardData[];
if (labelsToRead && labelsToRead.length > 0) { if (labelsToRead && labelsToRead.length > 0) {
resultCards = records.filter(r => labelsToRead.includes(r.label || '')); resultCards = records.filter((r) =>
labelsToRead.includes(r.label || ""),
);
} else { } else {
resultCards = records; resultCards = records;
} }
@ -220,20 +194,26 @@ export function cardCrud(params: CardCrudParams): CardCrudResult {
success: true, success: true,
message: `成功读取 ${resultCards.length} 张卡牌`, message: `成功读取 ${resultCards.length} 张卡牌`,
cards: resultCards, cards: resultCards,
count: resultCards.length count: resultCards.length,
}; };
} }
case 'update': { case "update": {
const labelsToUpdate = Array.isArray(label) ? label : (label ? [label] : null); const labelsToUpdate = Array.isArray(label)
const updateCards = Array.isArray(cards) ? cards : (cards ? [cards] : []); ? label
: label
? [label]
: null;
const updateCards = Array.isArray(cards) ? cards : cards ? [cards] : [];
let updatedCount = 0; let updatedCount = 0;
if (labelsToUpdate && labelsToUpdate.length > 0) { if (labelsToUpdate && labelsToUpdate.length > 0) {
// 按 label 更新 // 按 label 更新
for (const updateCard of updateCards) { for (const updateCard of updateCards) {
const targetLabel = updateCard.label || labelsToUpdate[updatedCount % labelsToUpdate.length]; const targetLabel =
const index = records.findIndex(r => r.label === targetLabel); updateCard.label ||
labelsToUpdate[updatedCount % labelsToUpdate.length];
const index = records.findIndex((r) => r.label === targetLabel);
if (index !== -1) { if (index !== -1) {
records[index] = { ...records[index], ...updateCard }; records[index] = { ...records[index], ...updateCard };
updatedCount++; updatedCount++;
@ -243,7 +223,9 @@ export function cardCrud(params: CardCrudParams): CardCrudResult {
// 按 cards 中的 label 更新 // 按 cards 中的 label 更新
for (const updateCard of updateCards) { for (const updateCard of updateCards) {
if (updateCard.label) { if (updateCard.label) {
const index = records.findIndex(r => r.label === updateCard.label); const index = records.findIndex(
(r) => r.label === updateCard.label,
);
if (index !== -1) { if (index !== -1) {
records[index] = { ...records[index], ...updateCard }; records[index] = { ...records[index], ...updateCard };
updatedCount++; updatedCount++;
@ -257,23 +239,29 @@ export function cardCrud(params: CardCrudParams): CardCrudResult {
success: true, success: true,
message: `成功更新 ${updatedCount} 张卡牌`, message: `成功更新 ${updatedCount} 张卡牌`,
cards: updateCards, cards: updateCards,
count: updatedCount count: updatedCount,
}; };
} }
case 'delete': { case "delete": {
const labelsToDelete = Array.isArray(label) ? label : (label ? [label] : null); const labelsToDelete = Array.isArray(label)
? label
: label
? [label]
: null;
let deletedCount = 0; let deletedCount = 0;
if (labelsToDelete && labelsToDelete.length > 0) { if (labelsToDelete && labelsToDelete.length > 0) {
const beforeCount = records.length; const beforeCount = records.length;
records = records.filter(r => !labelsToDelete.includes(r.label || '')); records = records.filter(
(r) => !labelsToDelete.includes(r.label || ""),
);
deletedCount = beforeCount - records.length; deletedCount = beforeCount - records.length;
} else if (cards) { } else if (cards) {
const cardsToDelete = Array.isArray(cards) ? cards : [cards]; const cardsToDelete = Array.isArray(cards) ? cards : [cards];
const beforeCount = records.length; const beforeCount = records.length;
records = records.filter(r => records = records.filter(
!cardsToDelete.some(c => c.label && r.label === c.label) (r) => !cardsToDelete.some((c) => c.label && r.label === c.label),
); );
deletedCount = beforeCount - records.length; deletedCount = beforeCount - records.length;
} }
@ -282,20 +270,20 @@ export function cardCrud(params: CardCrudParams): CardCrudResult {
return { return {
success: true, success: true,
message: `成功删除 ${deletedCount} 张卡牌`, message: `成功删除 ${deletedCount} 张卡牌`,
count: deletedCount count: deletedCount,
}; };
} }
default: default:
return { return {
success: false, success: false,
message: `未知操作：${action}` message: `未知操作：${action}`,
}; };
} }
} catch (error) { } catch (error) {
return { return {
success: false, success: false,
message: `操作失败：${error instanceof Error ? error.message : '未知错误'}` message: `操作失败：${error instanceof Error ? error.message : "未知错误"}`,
}; };
} }
} }

134
src/cli/tools/deck-utils.ts Normal file
View File

@ -0,0 +1,134 @@
/**
* Shared deck utility functions — used by generate-card-deck and preview-deck.
*/
import { dirname, join, basename, extname, relative } from "path";
import type {
DeckConfig,
DeckFrontmatter,
} from "./frontmatter/read-frontmatter.js";
import { parseFrontMatter } from "./frontmatter/shared.js";
import { readFileSync } from "fs";
/**
* Build a `:md-deck[path]{attrs}` directive string from a CSV path and config.
*/
export function buildDeckComponent(
csvPath: string,
config?: DeckConfig,
): string {
const parts = [`:md-deck[${csvPath}]`];
const attrs: string[] = [];
if (config?.size) {
attrs.push(`size="${config.size}"`);
}
if (config?.grid) {
attrs.push(`grid="${config.grid}"`);
}
if (config?.bleed !== undefined && config.bleed !== 1) {
attrs.push(`bleed="${config.bleed}"`);
}
if (config?.padding !== undefined && config.padding !== 2) {
attrs.push(`padding="${config.padding}"`);
}
if (config?.shape && config.shape !== "rectangle") {
attrs.push(`shape="${config.shape}"`);
}
if (config?.layers) {
attrs.push(`layers="${config.layers}"`);
}
if (config?.back_layers) {
attrs.push(`back-layers="${config.back_layers}"`);
}
if (attrs.length > 0) {
parts.push(`{${attrs.join(" ")}}`);
}
return parts.join("");
}
/**
* Derive a human-readable title from a CSV filename.
* e.g. "my-deck.csv" → "My Deck"
*/
export function titleFromCsvPath(csvPath: string): string {
const name = basename(csvPath, extname(csvPath));
return name.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
}
/**
* Compute the relative path from a markdown file to its CSV.
* Handles the case where they are in the same or different directories.
*/
export function relativeCsvPath(
mdFilePath: string,
csvFilePath: string,
): string {
const mdDir = dirname(mdFilePath);
const rel = relative(mdDir, csvFilePath);
return rel.startsWith(".") ? rel : `./${rel}`;
}
/**
* Determine the default markdown file path for a CSV.
* e.g. "foo/bar.csv" → "foo/bar.md"
*/
export function defaultMdPath(csvFilePath: string): string {
const dir = dirname(csvFilePath);
const name = basename(csvFilePath, extname(csvFilePath));
return join(dir, `${name}.md`);
}
/**
* Read DeckConfig from a CSV file's frontmatter, if present.
*/
export function readDeckConfig(csvFilePath: string): DeckConfig | undefined {
try {
const content = readFileSync(csvFilePath, "utf-8");
const { frontmatter } = parseFrontMatter(content);
return frontmatter?.deck;
} catch {
return undefined;
}
}
/**
* Generate the standard markdown content for a deck preview file.
*/
export function generateDeckPreviewMd(
deckTitle: string,
deckComponent: string,
description?: string,
): string {
const lines: string[] = [];
lines.push(`# ${deckTitle}`);
lines.push("");
if (description) {
lines.push(description);
lines.push("");
}
lines.push("## 卡牌预览");
lines.push("");
lines.push(deckComponent);
lines.push("");
lines.push("## 使用说明");
lines.push("");
lines.push("- 点击卡牌可以查看详情");
lines.push("- 使用右上角的按钮可以随机抽取卡牌");
lines.push("- 可以通过编辑面板调整卡牌样式和布局");
lines.push("");
return lines.join("\n");
}

217
src/cli/tools/ensure-deck-preview.ts
View File

@ -1,217 +0,0 @@
import { readFileSync, writeFileSync, existsSync } from 'fs';
import { dirname, join, basename, extname } from 'path';
import yaml from 'js-yaml';
import type { DeckFrontmatter, DeckConfig } from './frontmatter/read-frontmatter.js';
/**
* 确保 Deck 预览文件的参数
*/
export interface EnsureDeckPreviewParams {
/**
* CSV 文件路径
*/
csv_file: string;
/**
* Markdown 文件路径（可选，默认与 CSV 同名）
*/
md_file?: string;
/**
* 标题（可选，默认从 CSV 文件名推断）
*/
title?: string;
/**
* 描述（可选）
*/
description?: string;
}
/**
* 确保 Deck 预览文件的结果
*/
export interface EnsureDeckPreviewResult {
success: boolean;
message: string;
md_file?: string;
created?: boolean;
}
/**
* 解析 CSV 文件的 frontmatter
*/
function parseFrontMatter(content: string): { frontmatter?: DeckFrontmatter; csvContent: string } {
const parts = content.trim().split(/(?:^|\n)---\s*\n/g);
if (parts.length !== 3 || parts[0] !== '') {
return { csvContent: content };
}
try {
const frontmatterStr = parts[1].trim();
const frontmatter = yaml.load(frontmatterStr) as DeckFrontmatter | undefined;
const csvContent = parts.slice(2).join('---\n').trimStart();
return { frontmatter, csvContent };
} catch (error) {
console.warn('Failed to parse front matter:', error);
return { csvContent: content };
}
}
/**
* 构建 md-deck 组件代码
*/
function buildDeckComponent(csvPath: string, config?: DeckConfig): string {
const parts = [`:md-deck[${csvPath}]`];
const attrs: string[] = [];
if (config?.size) {
attrs.push(`size="${config.size}"`);
}
if (config?.grid) {
attrs.push(`grid="${config.grid}"`);
}
if (config?.bleed !== undefined && config.bleed !== 1) {
attrs.push(`bleed="${config.bleed}"`);
}
if (config?.padding !== undefined && config.padding !== 2) {
attrs.push(`padding="${config.padding}"`);
}
if (config?.shape && config.shape !== 'rectangle') {
attrs.push(`shape="${config.shape}"`);
}
if (config?.layers) {
attrs.push(`layers="${config.layers}"`);
}
if (config?.back_layers) {
attrs.push(`back-layers="${config.back_layers}"`);
}
if (attrs.length > 0) {
parts.push(`{${attrs.join(' ')}}`);
}
return parts.join('');
}
/**
* 确保 Markdown 预览文件存在
*/
export function ensureDeckPreview(params: EnsureDeckPreviewParams): EnsureDeckPreviewResult {
const { csv_file, md_file, title, description } = params;
// 检查 CSV 文件是否存在
if (!existsSync(csv_file)) {
return {
success: false,
message: `CSV 文件不存在：${csv_file}`
};
}
// 确定 Markdown 文件路径
let mdFilePath = md_file;
if (!mdFilePath) {
// 使用与 CSV 相同的路径和文件名，只是扩展名不同
const dir = dirname(csv_file);
const name = basename(csv_file, extname(csv_file));
mdFilePath = join(dir, `${name}.md`);
}
const created = !existsSync(mdFilePath);
// 如果文件已存在，检查是否已有 md-deck 组件
if (!created) {
try {
const existingContent = readFileSync(mdFilePath, 'utf-8');
// 如果已有 md-deck 组件引用该 CSV，直接返回
if (existingContent.includes(`:md-deck[${csv_file}]`) ||
existingContent.includes(`:md-deck[./${basename(csv_file)}]`)) {
return {
success: true,
message: `预览文件 ${mdFilePath} 已存在`,
md_file: mdFilePath,
created: false
};
}
} catch (error) {
// 读取失败，继续创建
}
}
// 读取 CSV 的 frontmatter 获取配置
let deckConfig: DeckConfig | undefined;
try {
const csvContent = readFileSync(csv_file, 'utf-8');
const { frontmatter } = parseFrontMatter(csvContent);
deckConfig = frontmatter?.deck;
} catch (error) {
// 忽略错误，使用默认配置
}
// 确定标题
let deckTitle = title;
if (!deckTitle) {
// 从 CSV 文件名推断
const name = basename(csv_file, extname(csv_file));
deckTitle = name.replace(/[-_]/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
}
// 构建 md-deck 组件代码（使用相对路径）
const mdDir = dirname(mdFilePath);
const csvDir = dirname(csv_file);
let relativeCsvPath: string;
if (mdDir === csvDir) {
relativeCsvPath = `./${basename(csv_file)}`;
} else {
relativeCsvPath = `./${basename(csv_file)}`;
}
const deckComponent = buildDeckComponent(relativeCsvPath, deckConfig);
// 生成 Markdown 内容
const mdLines: string[] = [];
mdLines.push(`# ${deckTitle}`);
mdLines.push('');
if (description) {
mdLines.push(description);
mdLines.push('');
}
mdLines.push('## 卡牌预览');
mdLines.push('');
mdLines.push(deckComponent);
mdLines.push('');
mdLines.push('## 使用说明');
mdLines.push('');
mdLines.push('- 点击卡牌可以查看详情');
mdLines.push('- 使用右上角的按钮可以随机抽取卡牌');
mdLines.push('- 可以通过编辑面板调整卡牌样式和布局');
mdLines.push('');
// 写入文件
try {
writeFileSync(mdFilePath, mdLines.join('\n'), 'utf-8');
return {
success: true,
message: created
? `创建预览文件 ${mdFilePath}`
: `更新预览文件 ${mdFilePath}`,
md_file: mdFilePath,
created
};
} catch (error) {
return {
success: false,
message: `写入失败：${error instanceof Error ? error.message : '未知错误'}`
};
}
}

44
src/cli/tools/frontmatter/read-frontmatter.ts
View File

@ -1,5 +1,5 @@
import { readFileSync, existsSync } from 'fs'; import { readFileSync, existsSync } from "fs";
import yaml from 'js-yaml'; import { parseFrontMatter } from "./shared.js";
/** /**
* 读取 CSV frontmatter 的参数 * 读取 CSV frontmatter 的参数
@ -52,7 +52,7 @@ export interface CardFieldStyle {
/** /**
* 朝向：上侧朝向 "n" | "w" | "s" | "e"（北/西/南/东） * 朝向：上侧朝向 "n" | "w" | "s" | "e"（北/西/南/东）
*/ */
up?: 'n' | 'w' | 's' | 'e'; up?: "n" | "w" | "s" | "e";
} }
/** /**
@ -74,7 +74,7 @@ export interface DeckConfig {
grid?: string; grid?: string;
bleed?: number; bleed?: number;
padding?: number; padding?: number;
shape?: 'rectangle' | 'circle' | 'hex' | 'diamond'; shape?: "rectangle" | "circle" | "hex" | "diamond";
layers?: string; layers?: string;
back_layers?: string; back_layers?: string;
[key: string]: unknown; [key: string]: unknown;
@ -89,45 +89,25 @@ export interface ReadFrontmatterResult {
message: string; message: string;
} }
/**
* 解析 CSV 文件的 frontmatter
*/
function parseFrontMatter(content: string): { frontmatter?: DeckFrontmatter; csvContent: string } {
const parts = content.trim().split(/(?:^|\n)---\s*\n/g);
// 至少需要三个部分：空字符串、front matter、CSV 内容
if (parts.length !== 3 || parts[0] !== '') {
return { csvContent: content };
}
try {
const frontmatterStr = parts[1].trim();
const frontmatter = yaml.load(frontmatterStr) as DeckFrontmatter | undefined;
const csvContent = parts.slice(2).join('---\n').trimStart();
return { frontmatter, csvContent };
} catch (error) {
console.warn('Failed to parse front matter:', error);
return { csvContent: content };
}
}
/** /**
* 读取 CSV 文件的 frontmatter * 读取 CSV 文件的 frontmatter
*/ */
export function readFrontmatter(params: ReadFrontmatterParams): ReadFrontmatterResult { export function readFrontmatter(
params: ReadFrontmatterParams,
): ReadFrontmatterResult {
const { csv_file } = params; const { csv_file } = params;
// 检查文件是否存在 // 检查文件是否存在
if (!existsSync(csv_file)) { if (!existsSync(csv_file)) {
return { return {
success: false, success: false,
message: `文件不存在：${csv_file}` message: `文件不存在：${csv_file}`,
}; };
} }
try { try {
// 读取文件内容 // 读取文件内容
const content = readFileSync(csv_file, 'utf-8'); const content = readFileSync(csv_file, "utf-8");
// 解析 frontmatter // 解析 frontmatter
const { frontmatter } = parseFrontMatter(content); const { frontmatter } = parseFrontMatter(content);
@ -136,19 +116,19 @@ export function readFrontmatter(params: ReadFrontmatterParams): ReadFrontmatterR
return { return {
success: true, success: true,
frontmatter: {}, frontmatter: {},
message: `文件 ${csv_file} 没有 frontmatter，返回空对象` message: `文件 ${csv_file} 没有 frontmatter，返回空对象`,
}; };
} }
return { return {
success: true, success: true,
frontmatter, frontmatter,
message: `成功读取 ${csv_file} 的 frontmatter` message: `成功读取 ${csv_file} 的 frontmatter`,
}; };
} catch (error) { } catch (error) {
return { return {
success: false, success: false,
message: `读取失败：${error instanceof Error ? error.message : '未知错误'}` message: `读取失败：${error instanceof Error ? error.message : "未知错误"}`,
}; };
} }
} }

48
src/cli/tools/frontmatter/shared.ts Normal file
View File

@ -0,0 +1,48 @@
/**
* Shared frontmatter utilities — used by read-frontmatter, write-frontmatter,
* card-crud, preview-deck, and generate-card-deck.
*/
import yaml from "js-yaml";
import type { DeckFrontmatter } from "./read-frontmatter.js";
/**
* Parse YAML frontmatter from a CSV file's raw content.
* Expects `---\n...\n---\n` delimited frontmatter at the top of the file.
*/
export function parseFrontMatter(content: string): {
frontmatter?: DeckFrontmatter;
csvContent: string;
} {
const parts = content.trim().split(/(?:^|\n)---\s*\n/g);
if (parts.length !== 3 || parts[0] !== "") {
return { csvContent: content };
}
try {
const frontmatterStr = parts[1].trim();
const frontmatter = yaml.load(frontmatterStr) as
| DeckFrontmatter
| undefined;
const csvContent = parts.slice(2).join("---\n").trimStart();
return { frontmatter, csvContent };
} catch (error) {
console.warn("Failed to parse front matter:", error);
return { csvContent: content };
}
}
/**
* Serialize a DeckFrontmatter object to YAML frontmatter string.
*/
export function serializeFrontMatter(frontmatter: DeckFrontmatter): string {
const yamlStr = yaml.dump(frontmatter, {
indent: 2,
lineWidth: -1,
noRefs: true,
quotingType: '"',
forceQuotes: false,
});
return `---\n${yamlStr}---\n`;
}

73
src/cli/tools/frontmatter/write-frontmatter.ts
View File

@ -1,6 +1,6 @@
import { readFileSync, writeFileSync, existsSync } from 'fs'; import { readFileSync, writeFileSync, existsSync } from "fs";
import yaml from 'js-yaml'; import type { DeckFrontmatter } from "./read-frontmatter.js";
import type { DeckFrontmatter } from './read-frontmatter.js'; import { parseFrontMatter, serializeFrontMatter } from "./shared.js";
/** /**
* 写入 CSV frontmatter 的参数 * 写入 CSV frontmatter 的参数
@ -29,70 +29,37 @@ export interface WriteFrontmatterResult {
csv_file?: string; csv_file?: string;
} }
/**
* 解析 CSV 文件的 frontmatter
*/
function parseFrontMatter(content: string): { frontmatter?: DeckFrontmatter; csvContent: string } {
const parts = content.trim().split(/(?:^|\n)---\s*\n/g);
// 至少需要三个部分：空字符串、front matter、CSV 内容
if (parts.length !== 3 || parts[0] !== '') {
return { csvContent: content };
}
try {
const frontmatterStr = parts[1].trim();
const frontmatter = yaml.load(frontmatterStr) as DeckFrontmatter | undefined;
const csvContent = parts.slice(2).join('---\n').trimStart();
return { frontmatter, csvContent };
} catch (error) {
console.warn('Failed to parse front matter:', error);
return { csvContent: content };
}
}
/**
* 序列化 frontmatter 为 YAML 字符串
*/
function serializeFrontMatter(frontmatter: DeckFrontmatter): string {
const yamlStr = yaml.dump(frontmatter, {
indent: 2,
lineWidth: -1, // 不限制行宽
noRefs: true, // 不使用引用
quotingType: '"',
forceQuotes: false
});
return `---\n${yamlStr}---\n`;
}
/** /**
* 写入/更新 CSV 文件的 frontmatter * 写入/更新 CSV 文件的 frontmatter
*/ */
export function writeFrontmatter(params: WriteFrontmatterParams): WriteFrontmatterResult { export function writeFrontmatter(
params: WriteFrontmatterParams,
): WriteFrontmatterResult {
const { csv_file, frontmatter, merge = true } = params; const { csv_file, frontmatter, merge = true } = params;
let csvContent = ''; let csvContent = "";
let existingFrontmatter: DeckFrontmatter | undefined; let existingFrontmatter: DeckFrontmatter | undefined;
// 如果文件存在且需要合并，先读取现有内容 // 如果文件存在且需要合并，先读取现有内容
if (merge && existsSync(csv_file)) { if (merge && existsSync(csv_file)) {
try { try {
const content = readFileSync(csv_file, 'utf-8'); const content = readFileSync(csv_file, "utf-8");
const result = parseFrontMatter(content); const result = parseFrontMatter(content);
existingFrontmatter = result.frontmatter; existingFrontmatter = result.frontmatter;
csvContent = result.csvContent; csvContent = result.csvContent;
} catch (error) { } catch (error) {
return { return {
success: false, success: false,
message: `读取现有文件失败：${error instanceof Error ? error.message : '未知错误'}` message: `读取现有文件失败：${error instanceof Error ? error.message : "未知错误"}`,
}; };
} }
} }
// 合并或替换 frontmatter // 合并或替换 frontmatter
const finalFrontmatter = merge && existingFrontmatter const finalFrontmatter =
? { ...existingFrontmatter, ...frontmatter } merge && existingFrontmatter
: frontmatter; ? { ...existingFrontmatter, ...frontmatter }
: frontmatter;
// 序列化 frontmatter // 序列化 frontmatter
const frontmatterStr = serializeFrontMatter(finalFrontmatter); const frontmatterStr = serializeFrontMatter(finalFrontmatter);
@ -100,32 +67,32 @@ export function writeFrontmatter(params: WriteFrontmatterParams): WriteFrontmatt
// 如果文件不存在或没有 CSV 内容，创建一个空的 CSV 内容 // 如果文件不存在或没有 CSV 内容，创建一个空的 CSV 内容
if (!csvContent.trim()) { if (!csvContent.trim()) {
// 从 frontmatter 推断 CSV 表头 // 从 frontmatter 推断 CSV 表头
const headers = ['label']; const headers = ["label"];
if (finalFrontmatter.fields && Array.isArray(finalFrontmatter.fields)) { if (finalFrontmatter.fields && Array.isArray(finalFrontmatter.fields)) {
for (const field of finalFrontmatter.fields) { for (const field of finalFrontmatter.fields) {
if (field.name && typeof field.name === 'string') { if (field.name && typeof field.name === "string") {
headers.push(field.name); headers.push(field.name);
} }
} }
} }
headers.push('body'); headers.push("body");
csvContent = headers.join(',') + '\n'; csvContent = headers.join(",") + "\n";
} }
// 写入文件 // 写入文件
try { try {
const fullContent = frontmatterStr + csvContent; const fullContent = frontmatterStr + csvContent;
writeFileSync(csv_file, fullContent, 'utf-8'); writeFileSync(csv_file, fullContent, "utf-8");
return { return {
success: true, success: true,
message: `成功写入 frontmatter 到 ${csv_file}`, message: `成功写入 frontmatter 到 ${csv_file}`,
csv_file csv_file,
}; };
} catch (error) { } catch (error) {
return { return {
success: false, success: false,
message: `写入失败：${error instanceof Error ? error.message : '未知错误'}` message: `写入失败：${error instanceof Error ? error.message : "未知错误"}`,
}; };
} }
} }

196
src/cli/tools/generate-card-deck.ts
View File

@ -1,5 +1,7 @@
import { writeFileSync, mkdirSync, existsSync } from 'fs'; import { writeFileSync, mkdirSync, existsSync } from "fs";
import { join } from 'path'; import { join } from "path";
import { buildDeckComponent, generateDeckPreviewMd } from "./deck-utils.js";
import type { DeckConfig } from "./frontmatter/read-frontmatter.js";
/** /**
* 字段样式配置 * 字段样式配置
@ -24,7 +26,7 @@ export interface CardFieldStyle {
/** /**
* 朝向：上侧朝向 "n" | "w" | "s" | "e"（北/西/南/东） * 朝向：上侧朝向 "n" | "w" | "s" | "e"（北/西/南/东）
*/ */
up?: 'n' | 'w' | 's' | 'e'; up?: "n" | "w" | "s" | "e";
} }
/** /**
@ -45,18 +47,7 @@ export interface CardTemplate {
examples?: Record<string, string>[]; examples?: Record<string, string>[];
} }
/** export type { DeckConfig };
* Deck 配置
*/
export interface DeckConfig {
size?: string;
grid?: string;
bleed?: number;
padding?: number;
shape?: 'rectangle' | 'circle' | 'hex' | 'diamond';
layers?: string;
backLayers?: string;
}
/** /**
* 生成卡牌组的参数 * 生成卡牌组的参数
@ -73,14 +64,11 @@ export interface GenerateCardDeckParams {
/** /**
* 生成卡牌数据 CSV * 生成卡牌数据 CSV
*/ */
function generateCardCSV( function generateCardCSV(template: CardTemplate, cardCount: number): string {
template: CardTemplate,
cardCount: number
): string {
const fields = template.fields; const fields = template.fields;
// 构建 CSV 表头 // 构建 CSV 表头
const headers = ['label', ...fields.map(f => f.name), 'body']; const headers = ["label", ...fields.map((f) => f.name), "body"];
// 生成示例数据 // 生成示例数据
const rows: string[][] = []; const rows: string[][] = [];
@ -91,13 +79,16 @@ function generateCardCSV(
// 为每个字段生成值 // 为每个字段生成值
for (const field of fields) { for (const field of fields) {
let value = ''; let value = "";
if (examples.length > 0) { if (examples.length > 0) {
// 从示例中循环取值 // 从示例中循环取值
const exampleIndex = i % examples.length; const exampleIndex = i % examples.length;
const example = examples[exampleIndex]; const example = examples[exampleIndex];
value = example[field.name] || field.examples?.[i % (field.examples?.length || 1)] || ''; value =
example[field.name] ||
field.examples?.[i % (field.examples?.length || 1)] ||
"";
} else if (field.examples && field.examples.length > 0) { } else if (field.examples && field.examples.length > 0) {
// 从字段的示例中取值 // 从字段的示例中取值
value = field.examples[i % field.examples.length]; value = field.examples[i % field.examples.length];
@ -114,117 +105,35 @@ function generateCardCSV(
for (const field of fields) { for (const field of fields) {
bodyParts.push(`**${field.name}:** {{${field.name}}}`); bodyParts.push(`**${field.name}:** {{${field.name}}}`);
} }
row.push(bodyParts.join('\n\n')); row.push(bodyParts.join("\n\n"));
rows.push(row); rows.push(row);
} }
// 组合 CSV 内容 // 组合 CSV 内容
const csvLines = [headers.join(',')]; const csvLines = [headers.join(",")];
for (const row of rows) { for (const row of rows) {
csvLines.push(row.map(cell => { csvLines.push(
// 处理包含逗号或换行的单元格 row
if (cell.includes(',') || cell.includes('\n') || cell.includes('"')) { .map((cell) => {
return `"${cell.replace(/"/g, '""')}"`; // 处理包含逗号或换行的单元格
} if (cell.includes(",") || cell.includes("\n") || cell.includes('"')) {
return cell; return `"${cell.replace(/"/g, '""')}"`;
}).join(',')); }
return cell;
})
.join(","),
);
} }
return csvLines.join('\n'); return csvLines.join("\n");
}
/**
* 生成卡牌介绍的 Markdown 文件
*/
function generateDeckMarkdown(
deckName: string,
csvFileName: string,
deckConfig: DeckConfig,
description?: string
): string {
const mdLines: string[] = [];
// 标题
mdLines.push(`# ${deckName}`);
mdLines.push('');
// 描述
if (description) {
mdLines.push(description);
mdLines.push('');
}
// 卡牌预览组件
mdLines.push('## 卡牌预览');
mdLines.push('');
// 构建 :md-deck 组件代码
const deckComponent = buildDeckComponent(csvFileName, deckConfig);
mdLines.push(deckComponent);
mdLines.push('');
// 使用说明
mdLines.push('## 使用说明');
mdLines.push('');
mdLines.push('- 点击卡牌可以查看详情');
mdLines.push('- 使用右上角的按钮可以随机抽取卡牌');
mdLines.push('- 可以通过编辑面板调整卡牌样式和布局');
mdLines.push('');
return mdLines.join('\n');
}
/**
* 构建 :md-deck 组件代码
*/
function buildDeckComponent(
csvFileName: string,
config: DeckConfig
): string {
const parts = [`:md-deck[${csvFileName}]`];
const attrs: string[] = [];
if (config.size) {
attrs.push(`size="${config.size}"`);
}
if (config.grid) {
attrs.push(`grid="${config.grid}"`);
}
if (config.bleed !== undefined && config.bleed !== 1) {
attrs.push(`bleed="${config.bleed}"`);
}
if (config.padding !== undefined && config.padding !== 2) {
attrs.push(`padding="${config.padding}"`);
}
if (config.shape && config.shape !== 'rectangle') {
attrs.push(`shape="${config.shape}"`);
}
if (config.layers) {
attrs.push(`layers="${config.layers}"`);
}
if (config.backLayers) {
attrs.push(`back-layers="${config.backLayers}"`);
}
if (attrs.length > 0) {
parts.push(`{${attrs.join(' ')}}`);
}
return parts.join('');
} }
/** /**
* 自动生成图层配置 * 自动生成图层配置
*/ */
function autoGenerateLayers(fields: CardField[]): string { function autoGenerateLayers(fields: CardField[]): string {
if (fields.length === 0) return ''; if (fields.length === 0) return "";
const layers: string[] = []; const layers: string[] = [];
const totalHeight = 8; const totalHeight = 8;
@ -238,7 +147,7 @@ function autoGenerateLayers(fields: CardField[]): string {
layers.push(`${field.name}:1,${y1}-${y2},${fontSize}`); layers.push(`${field.name}:1,${y1}-${y2},${fontSize}`);
} }
return layers.join(' '); return layers.join(" ");
} }
/** /**
@ -256,7 +165,7 @@ export function generateCardDeck(params: GenerateCardDeckParams): {
card_count = 10, card_count = 10,
card_template, card_template,
deck_config = {}, deck_config = {},
description description,
} = params; } = params;
// 确保输出目录存在 // 确保输出目录存在
@ -265,52 +174,57 @@ export function generateCardDeck(params: GenerateCardDeckParams): {
} }
// 生成文件名 // 生成文件名
const safeName = deck_name.toLowerCase().replace(/\s+/g, '-'); const safeName = deck_name.toLowerCase().replace(/\s+/g, "-");
const csvFileName = `${safeName}.csv`; const csvFileName = `${safeName}.csv`;
const mdFileName = `${safeName}.md`; const mdFileName = `${safeName}.md`;
// 创建默认模板（如果没有提供） // 创建默认模板（如果没有提供）
const template: CardTemplate = card_template || { const template: CardTemplate = card_template || {
fields: [ fields: [
{ name: 'name', description: '卡牌名称', examples: ['示例卡牌 1', '示例卡牌 2'] }, {
{ name: 'type', description: '卡牌类型', examples: ['物品', '法术'] }, name: "name",
{ name: 'cost', description: '费用', examples: ['1', '2'] }, description: "卡牌名称",
{ name: 'description', description: '效果描述', examples: ['这是一个效果描述', '这是另一个效果'] } examples: ["示例卡牌 1", "示例卡牌 2"],
] },
{ name: "type", description: "卡牌类型", examples: ["物品", "法术"] },
{ name: "cost", description: "费用", examples: ["1", "2"] },
{
name: "description",
description: "效果描述",
examples: ["这是一个效果描述", "这是另一个效果"],
},
],
}; };
// 创建默认配置（如果没有提供） // 创建默认配置（如果没有提供）
const config: DeckConfig = { const config: DeckConfig = {
size: deck_config.size || '54x86', size: deck_config.size || "54x86",
grid: deck_config.grid || '5x8', grid: deck_config.grid || "5x8",
bleed: deck_config.bleed ?? 1, bleed: deck_config.bleed ?? 1,
padding: deck_config.padding ?? 2, padding: deck_config.padding ?? 2,
shape: deck_config.shape || 'rectangle', shape: deck_config.shape || "rectangle",
layers: deck_config.layers || autoGenerateLayers(template.fields) layers: deck_config.layers || autoGenerateLayers(template.fields),
}; };
// 生成 CSV 内容 // 生成 CSV 内容
const csvContent = generateCardCSV(template, card_count); const csvContent = generateCardCSV(template, card_count);
const csvPath = join(output_dir, csvFileName); const csvPath = join(output_dir, csvFileName);
writeFileSync(csvPath, csvContent, 'utf-8'); writeFileSync(csvPath, csvContent, "utf-8");
// 生成 Markdown 内容 // 生成 Markdown 内容
const mdContent = generateDeckMarkdown( const deckComponent = buildDeckComponent(`./${csvFileName}`, config);
const mdContent = generateDeckPreviewMd(
deck_name, deck_name,
`./${csvFileName}`, deckComponent,
config, description,
description
); );
const mdPath = join(output_dir, mdFileName); const mdPath = join(output_dir, mdFileName);
writeFileSync(mdPath, mdContent, 'utf-8'); writeFileSync(mdPath, mdContent, "utf-8");
// 构建完整的 deck 组件代码
const deckComponent = buildDeckComponent(`./${csvFileName}`, config);
return { return {
mdFile: mdPath, mdFile: mdPath,
csvFile: csvPath, csvFile: csvPath,
deckComponent, deckComponent,
message: `已生成卡牌组 "${deck_name}":\n- Markdown 文件：${mdPath}\n- CSV 数据：${csvPath}\n- 组件代码：${deckComponent}` message: `已生成卡牌组 "${deck_name}":\n- Markdown 文件：${mdPath}\n- CSV 数据：${csvPath}\n- 组件代码：${deckComponent}`,
}; };
} }

201
src/cli/tools/preview-deck.ts
View File

@ -1,8 +1,13 @@
import { readFileSync, writeFileSync, existsSync } from 'fs'; import { readFileSync, writeFileSync, existsSync } from "fs";
import { dirname, join, basename, extname, relative } from 'path'; import { relative } from "path";
import { execSync } from 'child_process'; import { execSync } from "child_process";
import yaml from 'js-yaml'; import {
import type { DeckFrontmatter, DeckConfig } from './frontmatter/read-frontmatter.js'; buildDeckComponent,
titleFromCsvPath,
defaultMdPath,
readDeckConfig,
generateDeckPreviewMd,
} from "./deck-utils.js";
/** /**
* 预览 Deck 的参数 * 预览 Deck 的参数
@ -37,88 +42,35 @@ export interface PreviewDeckResult {
preview_url?: string; preview_url?: string;
} }
/**
* 解析 CSV 文件的 frontmatter
*/
function parseFrontMatter(content: string): { frontmatter?: DeckFrontmatter; csvContent: string } {
const parts = content.trim().split(/(?:^|\n)---\s*\n/g);
if (parts.length !== 3 || parts[0] !== '') {
return { csvContent: content };
}
try {
const frontmatterStr = parts[1].trim();
const frontmatter = yaml.load(frontmatterStr) as DeckFrontmatter | undefined;
const csvContent = parts.slice(2).join('---\n').trimStart();
return { frontmatter, csvContent };
} catch (error) {
console.warn('Failed to parse front matter:', error);
return { csvContent: content };
}
}
/**
* 构建 md-deck 组件代码
*/
function buildDeckComponent(csvPath: string, config?: DeckConfig): string {
const parts = [`:md-deck[${csvPath}]`];
const attrs: string[] = [];
if (config?.size) {
attrs.push(`size="${config.size}"`);
}
if (config?.grid) {
attrs.push(`grid="${config.grid}"`);
}
if (config?.bleed !== undefined && config.bleed !== 1) {
attrs.push(`bleed="${config.bleed}"`);
}
if (config?.padding !== undefined && config.padding !== 2) {
attrs.push(`padding="${config.padding}"`);
}
if (config?.shape && config.shape !== 'rectangle') {
attrs.push(`shape="${config.shape}"`);
}
if (config?.layers) {
attrs.push(`layers="${config.layers}"`);
}
if (config?.back_layers) {
attrs.push(`back-layers="${config.back_layers}"`);
}
if (attrs.length > 0) {
parts.push(`{${attrs.join(' ')}}`);
}
return parts.join('');
}
/** /**
* 打开浏览器 * 打开浏览器
*/ */
function openBrowser(url: string) { function openBrowser(url: string) {
try { try {
// Windows 使用 start 命令 if (process.platform === "win32") {
if (process.platform === 'win32') { execSync(`start "" "${url}"`, { stdio: "ignore" });
execSync(`start "" "${url}"`, { stdio: 'ignore' }); } else if (process.platform === "darwin") {
} else if (process.platform === 'darwin') { execSync(`open "${url}"`, { stdio: "ignore" });
execSync(`open "${url}"`, { stdio: 'ignore' });
} else { } else {
execSync(`xdg-open "${url}"`, { stdio: 'ignore' }); execSync(`xdg-open "${url}"`, { stdio: "ignore" });
} }
console.error(`已打开浏览器：${url}`); console.error(`已打开浏览器：${url}`);
} catch (error) { } catch (error) {
console.error('打开浏览器失败:', error); console.error("打开浏览器失败:", error);
} }
} }
/**
* 计算预览 URL
*/
function computePreviewUrl(mdFilePath: string): string {
const relativeMdPath = relative(process.cwd(), mdFilePath)
.split("\\")
.join("/")
.replace(/\.md$/, "");
return `http://localhost:3000/${relativeMdPath}`;
}
/** /**
* 预览 Deck - 保存 Markdown 并打开浏览器 * 预览 Deck - 保存 Markdown 并打开浏览器
*/ */
@ -129,108 +81,61 @@ export function previewDeck(params: PreviewDeckParams): PreviewDeckResult {
if (!existsSync(csv_file)) { if (!existsSync(csv_file)) {
return { return {
success: false, success: false,
message: `CSV 文件不存在：${csv_file}` message: `CSV 文件不存在：${csv_file}`,
}; };
} }
// 确定 Markdown 文件路径 // 确定 Markdown 文件路径
let mdFilePath = md_file; const mdFilePath = md_file || defaultMdPath(csv_file);
if (!mdFilePath) {
// 使用与 CSV 相同的路径和文件名，只是扩展名不同
const dir = dirname(csv_file);
const name = basename(csv_file, extname(csv_file));
mdFilePath = join(dir, `${name}.md`);
}
const created = !existsSync(mdFilePath); const created = !existsSync(mdFilePath);
// 如果文件已存在，检查是否已有 md-deck 组件 // 如果文件已存在，检查是否已有 md-deck 组件
if (!created) { if (!created) {
try { try {
const existingContent = readFileSync(mdFilePath, 'utf-8'); const existingContent = readFileSync(mdFilePath, "utf-8");
// 如果已有 md-deck 组件引用该 CSV，直接返回 if (
if (existingContent.includes(`:md-deck[${csv_file}]`) || existingContent.includes(`:md-deck[${csv_file}]`) ||
existingContent.includes(`:md-deck[./${basename(csv_file)}]`)) { existingContent.includes(`:md-deck[./${csv_file.split("/").pop()}]`)
// 仍然打开浏览器 ) {
const relativeMdPath = relative(process.cwd(), mdFilePath).split('\\').join('/'); const previewUrl = computePreviewUrl(mdFilePath);
const previewUrl = `http://localhost:3000/${relativeMdPath}`;
openBrowser(previewUrl); openBrowser(previewUrl);
return { return {
success: true, success: true,
message: `预览文件 ${mdFilePath} 已存在`, message: `预览文件 ${mdFilePath} 已存在`,
md_file: mdFilePath, md_file: mdFilePath,
created: false, created: false,
preview_url: previewUrl preview_url: previewUrl,
}; };
} }
} catch (error) { } catch {
// 读取失败，继续创建 // 读取失败，继续创建
} }
} }
// 读取 CSV 的 frontmatter 获取配置 // 读取 CSV 的 frontmatter 获取配置
let deckConfig: DeckConfig | undefined; const deckConfig = readDeckConfig(csv_file);
try {
const csvContent = readFileSync(csv_file, 'utf-8');
const { frontmatter } = parseFrontMatter(csvContent);
deckConfig = frontmatter?.deck;
} catch (error) {
// 忽略错误，使用默认配置
}
// 确定标题 // 确定标题
let deckTitle = title; const deckTitle = title || titleFromCsvPath(csv_file);
if (!deckTitle) {
// 从 CSV 文件名推断
const name = basename(csv_file, extname(csv_file));
deckTitle = name.replace(/[-_]/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
}
// 构建 md-deck 组件代码（使用相对路径） // 构建 md-deck 组件代码
const mdDir = dirname(mdFilePath); const deckComponent = buildDeckComponent(
const csvDir = dirname(csv_file); `./${csv_file.split("/").pop()}`,
let relativeCsvPath: string; deckConfig,
);
if (mdDir === csvDir) {
relativeCsvPath = `./${basename(csv_file)}`;
} else {
relativeCsvPath = `./${basename(csv_file)}`;
}
const deckComponent = buildDeckComponent(relativeCsvPath, deckConfig);
// 生成 Markdown 内容 // 生成 Markdown 内容
const mdLines: string[] = []; const mdContent = generateDeckPreviewMd(
deckTitle,
mdLines.push(`# ${deckTitle}`); deckComponent,
mdLines.push(''); description,
);
if (description) {
mdLines.push(description);
mdLines.push('');
}
mdLines.push('## 卡牌预览');
mdLines.push('');
mdLines.push(deckComponent);
mdLines.push('');
mdLines.push('## 使用说明');
mdLines.push('');
mdLines.push('- 点击卡牌可以查看详情');
mdLines.push('- 使用右上角的按钮可以随机抽取卡牌');
mdLines.push('- 可以通过编辑面板调整卡牌样式和布局');
mdLines.push('');
// 写入文件 // 写入文件
try { try {
writeFileSync(mdFilePath, mdLines.join('\n'), 'utf-8'); writeFileSync(mdFilePath, mdContent, "utf-8");
// 计算预览 URL const previewUrl = computePreviewUrl(mdFilePath);
const relativeMdPath = relative(process.cwd(), mdFilePath).split('\\').join('/');
const previewUrl = `http://localhost:3000/${relativeMdPath.slice(0, -3)}`;
// 打开浏览器
openBrowser(previewUrl); openBrowser(previewUrl);
return { return {
@ -240,12 +145,12 @@ export function previewDeck(params: PreviewDeckParams): PreviewDeckResult {
: `更新预览文件 ${mdFilePath}`, : `更新预览文件 ${mdFilePath}`,
md_file: mdFilePath, md_file: mdFilePath,
created, created,
preview_url: previewUrl preview_url: previewUrl,
}; };
} catch (error) { } catch (error) {
return { return {
success: false, success: false,
message: `写入失败：${error instanceof Error ? error.message : '未知错误'}` message: `写入失败：${error instanceof Error ? error.message : "未知错误"}`,
}; };
} }
} }

2
src/components/md-deck/PrintPreview.tsx
View File

@ -115,7 +115,7 @@ export function PrintPreview(props: PrintPreviewProps) {
<PltPreview pltCode={pltCode()} onClose={handleClosePltPreview} /> <PltPreview pltCode={pltCode()} onClose={handleClosePltPreview} />
} }
> >
<div class="fixed inset-0 bg-black/50 z-[60] overflow-auto"> <div class="fixed inset-0 bg-black/50 z-60 overflow-auto">
<div class="min-h-screen py-20 px-4"> <div class="min-h-screen py-20 px-4">
<PrintPreviewHeader <PrintPreviewHeader
store={store} store={store}

371
src/components/md-table.tsx
View File

@ -1,9 +1,19 @@
import { customElement, noShadowDOM } from 'solid-element'; import { customElement, noShadowDOM } from "solid-element";
import { createSignal, For, Show, createEffect, createMemo, createResource } from 'solid-js'; import {
import { marked } from '../markdown'; createSignal,
import { loadCSV, CSV, processVariables, isCSV } from './utils/csv-loader'; For,
import { resolvePath } from './utils/path'; Show,
import { areAllLabelsNumeric, weightedRandomIndex } from './utils/weighted-random'; createEffect,
createMemo,
createResource,
} from "solid-js";
import { marked } from "../markdown";
import { loadCSV, CSV, processVariables, isCSV } from "./utils/csv-loader";
import { resolvePath } from "./utils/path";
import {
areAllLabelsNumeric,
weightedRandomIndex,
} from "./utils/weighted-random";
export interface TableProps { export interface TableProps {
roll?: boolean; roll?: boolean;
@ -16,191 +26,208 @@ interface TableRow {
[key: string]: string; [key: string]: string;
} }
customElement('md-table', { roll: false, remix: false }, (props, { element }) => { customElement(
noShadowDOM(); "md-table",
const [rows, setRows] = createSignal<CSV<TableRow>>([] as unknown as CSV<TableRow>); { roll: false, remix: false },
const [activeTab, setActiveTab] = createSignal(0); (props, { element }) => {
const [activeGroup, setActiveGroup] = createSignal<string | null>(null); noShadowDOM();
const [bodyHtml, setBodyHtml] = createSignal(''); const [rows, setRows] = createSignal<CSV<TableRow>>(
let tabsContainer: HTMLDivElement | undefined; [] as unknown as CSV<TableRow>,
);
const [activeTab, setActiveTab] = createSignal(0);
const [activeGroup, setActiveGroup] = createSignal<string | null>(null);
const [bodyHtml, setBodyHtml] = createSignal("");
let tabsContainer: HTMLDivElement | undefined;
// 从 element 的 textContent 获取 CSV 路径或 inline CSV 数据 // 从 element 的 textContent 获取 CSV 路径或 inline CSV 数据
const rawContent = element?.textContent?.trim() || ''; const rawContent = element?.textContent?.trim() || "";
// 隐藏原始文本内容 // 隐藏原始文本内容
if (element) { if (element) {
element.textContent = ''; element.textContent = "";
}
// 从父节点 article 的 data-src 获取当前 markdown 文件完整路径
const articleEl = element?.closest('article[data-src]');
const articlePath = articleEl?.getAttribute('data-src') || '';
// 如果是 inline CSV，直接使用；否则解析相对路径
const contentOrPath = isCSV(rawContent) ? rawContent : resolvePath(articlePath, rawContent);
// 使用 createResource 加载 CSV，自动响应路径变化并避免重复加载
const [csvData] = createResource(() => contentOrPath, loadCSV);
// 当数据加载完成后更新 rows
createEffect(() => {
const data = csvData();
if (data) {
// 将加载的数据赋值给 rows，CSV 类型已经包含 sourcePath 等属性
setRows(data as unknown as CSV<TableRow>);
} }
});
// 检测是否有 group 列 // 从父节点 article 的 data-src 获取当前 markdown 文件完整路径
const hasGroup = createMemo(() => { const articleEl = element?.closest("article[data-src]");
const allRows = rows(); const articlePath = articleEl?.getAttribute("data-src") || "";
return allRows.length > 0 && 'group' in allRows[0];
});
// 获取所有分组 // 如果是 inline CSV，直接使用；否则解析相对路径
const groups = createMemo(() => { const contentOrPath = isCSV(rawContent)
if (!hasGroup()) return []; ? rawContent
const allRows = rows(); : resolvePath(articlePath, rawContent);
const groupSet = new Set<string>();
for (const row of allRows) { // 使用 createResource 加载 CSV，自动响应路径变化并避免重复加载
if (row.group) { const [csvData] = createResource(() => contentOrPath, loadCSV);
groupSet.add(row.group);
// 当数据加载完成后更新 rows
createEffect(() => {
const data = csvData();
if (data) {
// 将加载的数据赋值给 rows，CSV 类型已经包含 sourcePath 等属性
setRows(data as unknown as CSV<TableRow>);
} }
} });
return Array.from(groupSet).sort();
});
// 根据当前选中的分组过滤行 // 检测是否有 group 列
const filteredRows = createMemo(() => { const hasGroup = createMemo(() => {
const allRows = rows(); const allRows = rows();
const group = activeGroup(); return allRows.length > 0 && "group" in allRows[0];
if (!group) return allRows; });
return allRows.filter(row => row.group === group);
});
// 处理 body 内容中的 {{prop}} 语法并解析 markdown // 获取所有分组
const processBody = (body: string, currentRow: TableRow): string => { const groups = createMemo(() => {
// 使用 marked 解析 markdown if (!hasGroup()) return [];
return marked.parse(processVariables(body, currentRow, rows(), filteredRows(), props.remix)) as string; const allRows = rows();
}; const groupSet = new Set<string>();
for (const row of allRows) {
if (row.group) {
groupSet.add(row.group);
}
}
return Array.from(groupSet).sort();
});
// 更新 body 内容 // 根据当前选中的分组过滤行
const updateBodyContent = () => { const filteredRows = createMemo(() => {
const filtered = filteredRows(); const allRows = rows();
if (!csvData.loading && filtered.length > 0) { const group = activeGroup();
const index = Math.min(activeTab(), filtered.length - 1); if (!group) return allRows;
const currentRow = filtered[index]; return allRows.filter((row) => row.group === group);
setBodyHtml(processBody(currentRow.body, currentRow)); });
}
};
// 监听 activeTab 和 activeGroup 变化并更新内容 // 处理 body 内容中的 {{prop}} 语法并解析 markdown
createEffect(() => { const processBody = (body: string, currentRow: TableRow): string => {
activeTab(); // 使用 marked 解析 markdown
activeGroup(); return marked.parse(
updateBodyContent(); processVariables(body, currentRow, rows(), filteredRows(), props.remix),
}); ) as string;
};
// 切换分组时重置 tab 索引 // 更新 body 内容
const handleGroupChange = (group: string | null) => { const updateBodyContent = () => {
setActiveGroup(group); const filtered = filteredRows();
setActiveTab(0); if (!csvData.loading && filtered.length > 0) {
}; const index = Math.min(activeTab(), filtered.length - 1);
const currentRow = filtered[index];
setBodyHtml(processBody(currentRow.body, currentRow));
}
};
// 随机切换 tab // 监听 activeTab 和 activeGroup 变化并更新内容
const handleRoll = () => { createEffect(() => {
const filtered = filteredRows(); activeTab();
if (filtered.length === 0) return; activeGroup();
updateBodyContent();
});
// 检查所有 label 是否都是整数/整数范围格式 // 切换分组时重置 tab 索引
const labels = filtered.map(row => row.label); const handleGroupChange = (group: string | null) => {
if (areAllLabelsNumeric(labels)) { setActiveGroup(group);
// 使用加权随机 setActiveTab(0);
const randomIndex = weightedRandomIndex(labels); };
if (randomIndex !== -1) {
// 随机切换 tab
const handleRoll = () => {
const filtered = filteredRows();
if (filtered.length === 0) return;
// 检查所有 label 是否都是整数/整数范围格式
const labels = filtered.map((row) => row.label);
if (areAllLabelsNumeric(labels)) {
// 使用加权随机
const randomIndex = weightedRandomIndex(labels);
if (randomIndex !== -1) {
setActiveTab(randomIndex);
}
} else {
// 使用简单随机
const randomIndex = Math.floor(Math.random() * filtered.length);
setActiveTab(randomIndex); setActiveTab(randomIndex);
} }
} else {
// 使用简单随机
const randomIndex = Math.floor(Math.random() * filtered.length);
setActiveTab(randomIndex);
}
// 滚动到可视区域 // 滚动到可视区域
setTimeout(() => { setTimeout(() => {
const activeButton = tabsContainer?.querySelector('.border-blue-600'); const activeButton = tabsContainer?.querySelector(".border-blue-600");
activeButton?.scrollIntoView({ behavior: 'smooth', block: 'nearest', inline: 'nearest' }); activeButton?.scrollIntoView({
}, 50); behavior: "smooth",
}; block: "nearest",
inline: "nearest",
});
}, 50);
};
return ( return (
<div class="ttrpg-table"> <div class="ttrpg-table">
<div class="flex items-center gap-2 border-b border-gray-200"> <div class="flex items-center gap-2 border-b border-gray-200">
<div class="flex flex-col overflow-x-auto"> <div class="flex flex-col overflow-x-auto">
{/* 分组 tabs */} {/* 分组 tabs */}
<Show when={hasGroup()}> <Show when={hasGroup()}>
<div class="flex gap-2 border-b border-gray-100 pb-2"> <div class="flex gap-2 border-b border-gray-100 pb-2">
<button <button
onClick={() => handleGroupChange(null)} onClick={() => handleGroupChange(null)}
class={`font-medium transition-colors ${ class={`font-medium transition-colors ${
activeGroup() === null activeGroup() === null
? 'text-blue-600 border-b-2 border-blue-600' ? "text-blue-600 border-b-2 border-blue-600"
: 'text-gray-500 hover:text-gray-700' : "text-gray-500 hover:text-gray-700"
}`} }`}
> >
全部 全部
</button> </button>
<For each={groups()}> <For each={groups()}>
{(group) => ( {(group) => (
<button <button
onClick={() => handleGroupChange(group)} onClick={() => handleGroupChange(group)}
class={`font-medium transition-colors ${ class={`font-medium transition-colors ${
activeGroup() === group activeGroup() === group
? 'text-blue-600 border-b-2 border-blue-600' ? "text-blue-600 border-b-2 border-blue-600"
: 'text-gray-500 hover:text-gray-700' : "text-gray-500 hover:text-gray-700"
}`} }`}
> >
{group} {group}
</button> </button>
)} )}
</For> </For>
</div> </div>
</Show>
{/* 内容 tabs */}
<div class="flex items-center gap-2">
<Show when={props.roll}>
<button
onClick={handleRoll}
class="text-gray-500 hover:text-gray-700 flex-shrink-0 cursor-pointer"
title="随机切换"
>
🎲
</button>
</Show> </Show>
<div ref={tabsContainer} class="flex gap-1 overflow-x-auto flex-1 min-w-0"> {/* 内容 tabs */}
<For each={filteredRows()}> <div class="flex items-center gap-2">
{(row, index) => ( <Show when={props.roll}>
<button <button
onClick={() => setActiveTab(index())} onClick={handleRoll}
class={`font-medium transition-colors flex-shrink-0 min-w-[1.6em] cursor-pointer ${ class="text-gray-500 hover:text-gray-700 shrink-0 cursor-pointer"
activeTab() === index() title="随机切换"
? 'text-blue-600 border-b-2 border-blue-600' >
: 'text-gray-500 hover:text-gray-700' 🎲
}`} </button>
> </Show>
{row.label} <div
</button> ref={tabsContainer}
)} class="flex gap-1 overflow-x-auto flex-1 min-w-0"
</For> >
<For each={filteredRows()}>
{(row, index) => (
<button
onClick={() => setActiveTab(index())}
class={`font-medium transition-colors shrink-0 min-w-[1.6em] cursor-pointer ${
activeTab() === index()
? "text-blue-600 border-b-2 border-blue-600"
: "text-gray-500 hover:text-gray-700"
}`}
>
{row.label}
</button>
)}
</For>
</div>
</div> </div>
</div> </div>
</div> </div>
<div class="p-4 prose max-w-none">
<Show when={!csvData.loading && filteredRows().length > 0}>
<div innerHTML={bodyHtml()} />
</Show>
</div>
</div> </div>
<div class="p-4 prose max-w-none"> );
<Show when={!csvData.loading && filteredRows().length > 0}> },
<div innerHTML={bodyHtml()} /> );
</Show>
</div>
</div>
);
});