koishi-plugin-noah 1.1.1 → 1.1.3

package/lib/constants.d.ts

@@ -1,13 +1,13 @@
 import { Context } from 'koishi';
 /**
- * Initialize global constants with application context
- * @param ctx Koishi Context
+ * 使用应用程序上下文初始化全局常量
+ * @param ctx - Koishi 上下文对象
  */
 export declare function initConstants(ctx: Context): void;
 /**
- * Get the full asset path combining baseDir and asset data path
- * @param ctx Koishi Context
- * @param assetPath Relative path within the asset directory
- * @returns Full resolved path to the asset
+ * 获取完整的资源路径，将基础目录和资源数据路径组合
+ * @param ctx - Koishi 上下文对象
+ * @param assetPath - 资源目录中的相对路径
+ * @returns 完整的资源文件路径
  */
 export declare function getAssetPath(ctx: Context, assetPath: string): string;

package/lib/core/services/card-service.d.ts

@@ -6,45 +6,60 @@ export declare class CardService {
     constructor(ctx: Context);
     /**
      * 获取所有卡片列表
+     * @returns 包含所有卡片的数组
      */
     getAllCards(): Promise<Card[]>;
     /**
-     * 根据 user id 获取卡片列表
-     * @param uid 用户的 user id
-     * @returns 该用户绑定的卡片的完整信息列表
+     * 根据用户ID获取卡片列表
+     * @param uid - 用户ID
+     * @returns 该用户绑定的卡片完整信息列表
      */
     getCardsByUid(uid: number): Promise<Card[]>;
     /**
-     * 根据 id 获取卡片信息
+     * 根据卡片ID获取卡片信息
+     * @param id - 卡片ID
+     * @returns 卡片信息，不存在则返回null
      */
     getCardById(id: number): Promise<Card | null>;
     /**
-     * 根据 code 获取卡片信息
+     * 根据卡号获取卡片信息
+     * @param code - 卡号
+     * @returns 卡片信息，不存在则返回null
      */
     getCardByCode(code: string): Promise<Card | null>;
     /**
-     * 根据 name 获取卡片信息
+     * 根据卡片名称获取卡片信息
+     * @param name - 卡片名称
+     * @returns 卡片信息，不存在则返回null
      */
     getCardByName(name: string): Promise<Card | null>;
     /**
-     * 创建一张新的卡
-     * @param uid 用户的 uid
-     * @param code 卡片的卡号
-     * @param name 卡片的名称
-     * @param defaultServerId 默认服务器 ID（若没有默认服务器则为 0）
-     * @returns 创建成功后包含自动填充 id 等字段的完整对象
+     * 创建一张新卡片
+     * @param uid - 用户ID
+     * @param code - 卡片卡号
+     * @param name - 卡片名称
+     * @param defaultServerId - 默认服务器ID（若没有默认服务器则为0）
+     * @returns 创建成功后包含自动填充ID等字段的完整对象
      */
     createCard(uid: number, code: string, name: string, defaultServerId?: number): Promise<Card>;
     /**
-     * 更新卡片的信息
-     * - 可更新 code、name、defaultServerId
-     * @param id 卡片的 id
-     * @param partial 更新字段
+     * 更新卡片信息
+     * 可更新 code、name、defaultServerId
+     * @param id - 卡片ID
+     * @param partial - 要更新的字段
+     * @returns 无返回值的Promise
      */
     updateCard(id: number, partial: Partial<Omit<Card, 'id'>>): Promise<void>;
     /**
      * 删除卡片
-     * @param id 卡片 id
+     * @param id - 卡片ID
+     * @returns 无返回值的Promise
      */
     removeCard(id: number): Promise<void>;
+    /**
+     * 根据用户ID获取默认卡片
+     * @param uid - 用户ID
+     * @returns 用户设置的默认卡片，若不存在则返回null
+     */
+    getDefaultCardByUid(uid: number): Promise<Card | null>;
 }

package/lib/core/services/server-service.d.ts

@@ -7,55 +7,77 @@ export declare class ServerService {
     constructor(ctx: Context);
     /**
      * 获取所有服务器列表
+     * @returns 服务器列表
      */
     getAllServers(): Promise<Server[]>;
     /**
-     * 根据 user id 获取服务器列表
-     * @param uid 用户的 user id
-     * @returns 该用户绑定的服务器的完整信息列表
+     * 根据用户ID获取服务器列表
+     * @param uid - 用户ID
+     * @returns 该用户绑定的服务器完整信息列表
      */
     getServersByUid(uid: number): Promise<Server[]>;
     /**
-     * 根据 channel id 获取服务器列表
-     * @param cid 频道的 channel id
-     * @returns 该频道绑定的服务器的完整信息列表
+     * 根据频道ID获取服务器列表
+     * @param cid - 频道ID
+     * @returns 该频道绑定的服务器完整信息列表
      */
     getServersByCid(cid: string): Promise<Server[]>;
     /**
-     * 根据 id 获取服务器信息
+     * 根据服务器ID获取服务器信息
+     * @param id - 服务器ID
+     * @returns 服务器信息，不存在则返回null
      */
     getServerById(id: number): Promise<Server | null>;
     /**
      * 根据名称查找服务器
+     * @param name - 服务器名称
+     * @returns 服务器信息，不存在则返回null
      */
     getServerByName(name: string): Promise<Server | null>;
     /**
      * 根据类型筛选服务器
+     * @param type - 服务器类型
+     * @returns 筛选后的服务器列表
      */
     getServersByType(type: TServer): Promise<Server[]>;
     /**
      * 创建一个新的服务器记录并关联到用户
-     * @param serverData 要插入的数据 (不含 id)
-     * @param uid 用户的 ID
+     * @param serverData - 要插入的数据(不含ID)
+     * @param uid - 用户ID
      * @returns 插入后的完整数据
      */
     createServerForUser(serverData: Omit<Server, 'id'>, uid: number): Promise<Server>;
     /**
      * 创建一个新的服务器记录并关联到频道
-     * @param serverData 要插入的数据 (不含 id)
-     * @param cid 频道的 ID
+     * @param serverData - 要插入的数据(不含ID)
+     * @param cid - 频道ID
      * @returns 插入后的完整数据
      */
     createServerForChannel(serverData: Omit<Server, 'id'>, cid: string): Promise<Server>;
     /**
      * 更新服务器记录
-     * @param id 服务器 id
-     * @param partial 要更新的字段
+     * @param id - 服务器ID
+     * @param partial - 要更新的字段
+     * @returns 无返回值的Promise
      */
     updateServer(id: number, partial: Partial<Omit<Server, 'id'>>): Promise<void>;
     /**
      * 删除服务器记录
-     * @param id 服务器 id
+     * @param id - 服务器ID
+     * @returns 无返回值的Promise
      */
     removeServer(id: number): Promise<void>;
+    /**
+     * 根据用户ID获取默认服务器
+     * @param uid - 用户ID
+     * @returns 用户设置的默认服务器，若不存在则返回null
+     */
+    getDefaultServerByUid(uid: number): Promise<Server | null>;
+    /**
+     * 根据频道ID获取默认服务器
+     * @param platform - 平台标识
+     * @param cid - 频道ID
+     * @returns 频道设置的默认服务器，若不存在则返回null
+     */
+    getDefaultServerByCid(platform: string, cid: string): Promise<Server | null>;
 }

package/lib/core/services/user-service.d.ts

@@ -3,21 +3,25 @@ export declare class UserService {
     private ctx;
     constructor(ctx: Context);
     /**
-     * Update a user's default server ID
-     * @param uid User ID
-     * @param serverId Server ID
+     * 更新用户的默认服务器ID
+     * @param uid - 用户ID
+     * @param serverId - 服务器ID
+     * @returns 无返回值的Promise
      */
     updateUserDefaultServer(uid: number, serverId: number): Promise<void>;
     /**
-     * Update a user's default card ID
-     * @param uid User ID
-     * @param cardId Card ID
+     * 更新用户的默认卡片ID
+     * @param uid - 用户ID
+     * @param cardId - 卡片ID
+     * @returns 无返回值的Promise
      */
     updateUserDefaultCard(uid: number, cardId: number): Promise<void>;
     /**
-     * Update a channel's default server ID
-     * @param cid Channel ID
-     * @param serverId Server ID
+     * 更新频道的默认服务器ID
+     * @param platform - 平台标识
+     * @param cid - 频道ID
+     * @param serverId - 服务器ID
+     * @returns 无返回值的Promise
      */
     updateChannelDefaultServer(platform: string, cid: string, serverId: number): Promise<void>;
 }

package/lib/core/utils/card.d.ts

@@ -1,24 +1,26 @@
 /**
  * 将 e-Amusement 卡号（16 个十六进制字符，对应 8 字节）转换为 KONAMI ID（16字符，从 ALPHABET 中取值）
- * @param uid e-Amusement 卡号（十六进制字符串，必须为 16 位，大写或小写皆可）
+ * @param uid - e-Amusement 卡号（十六进制字符串，必须为 16 位，大写或小写皆可）
  * @returns KONAMI ID 字符串
+ * @throws 当卡号前缀无效、长度不是16位或解析后不是8字节时抛出异常
  */
 export declare function toKonamiId(uid: string): string;
 /**
  * 将 KONAMI ID（16字符）转换回 e-Amusement 卡号（16 个十六进制字符）
- * @param konamiId KONAMI ID 字符串
+ * @param konamiId - KONAMI ID 字符串
  * @returns e-Amusement 卡号（16 位十六进制字符串，大写）
+ * @throws 当 KONAMI ID 格式无效、长度不是16位、校验和不匹配等情况时抛出异常
  */
 export declare function toUid(konamiId: string): string;
 /**
- * 判断给定的字符串是 UID、KONAMI ID 还是非法字符串。
- * @param input 待判断的字符串
- * @returns "uid" 表示 e-Amusement UID, "konamiid" 表示 KONAMI ID, "invalid" 表示非法字符串.
+ * 判断给定的字符串是 UID、KONAMI ID 还是非法字符串
+ * @param input - 待判断的字符串
+ * @returns "uid" 表示 e-Amusement UID, "konamiid" 表示 KONAMI ID, "invalid" 表示非法字符串
  */
 export declare function classifyCardId(input: string): "uid" | "konamiid" | "invalid";
 /**
- * 处理用户输入的卡号。
- * @param input 用户输入的卡号
- * @returns 删去空格的全大写字符串
+ * 处理用户输入的卡号
+ * @param input - 用户输入的卡号
+ * @returns 删去空格的全大写字符串，并转换特殊字符(I→1, O/Q→0, V→U)
  */
 export declare function processInputCardCode(input: string): string;

package/lib/core/utils/role.d.ts

@@ -1,5 +1,21 @@
 import { Session } from 'koishi';
 import { CoreConfig } from '../../types/config';
+/**
+ * 检查是否具有权限
+ * @param perms - 权限布尔值列表
+ * @returns 如果任一权限为true则返回true
+ */
 export declare function hasPermission(...perms: boolean[]): boolean;
+/**
+ * 检查用户是否为插件管理员
+ * @param session - 会话对象
+ * @param config - 核心配置
+ * @returns 用户是否为管理员
+ */
 export declare function isPluginAdmin(session: Session, config: CoreConfig): boolean;
+/**
+ * 检查用户是否为群组管理员
+ * @param session - 会话对象
+ * @returns 用户是否为群组管理员
+ */
 export declare function isGuildAdmin(session: Session): boolean;

package/lib/drawer/BaseDrawer.d.ts

@@ -1,16 +1,16 @@
 import { Context } from 'koishi';
 import { IDrawer } from '../types';
 /**
- * Base drawer class that provides common functionality for all drawers
+ * 基础绘图类，为所有绘图器提供通用功能
  */
 export declare abstract class BaseDrawer implements IDrawer {
     ctx: Context;
     constructor(ctx: Context);
     /**
-     * Compress an image buffer
-     * @param canvas The canvas object to compress
-     * @param compression Compression options
-     * @returns Promise resolving to a compressed buffer
+     * 压缩图片缓冲区
+     * @param canvas - 要压缩的canvas对象
+     * @param compression - 压缩选项
+     * @returns 压缩后的缓冲区
      */
     protected compressImage(canvas: any, compression?: {
         lossless: boolean;

package/lib/drawer/DrawerFactory.d.ts

@@ -4,5 +4,11 @@ export declare class DrawerFactory {
     private ctx;
     private drawerInstances;
     constructor(ctx: Context);
+    /**
+     * 根据绘图类型获取绘图实例，如果不存在则创建新实例
+     * @param drawerType - 绘图类型（游戏类型或核心类型）
+     * @returns 对应的绘图实例
+     * @throws 当请求不支持的绘图类型时抛出异常
+     */
     getDrawer(drawerType: TGame | 'core'): IDrawer;
 }

package/lib/drawer/core/index.d.ts

@@ -1,13 +1,16 @@
 import { Context } from 'koishi';
 import { BaseDrawer } from '../BaseDrawer';
+/**
+ * Core 绘图类，提供 Core 图像生成功能
+ */
 export declare class CoreDrawer extends BaseDrawer {
     ctx: Context;
     constructor(ctx: Context);
     /**
-     * Generate a generic image for core functionality
-     * @param options Configuration options for image generation
-     * @param compression Compression options
-     * @returns Promise resolving to a Buffer containing the image data
+     * 生成通用图像
+     * @param options - 图像生成配置选项
+     * @param compression - 压缩选项
+     * @returns 包含图像数据的Buffer
      */
     generateImage(options?: {
         width?: number;

package/lib/drawer/iidx/index.d.ts

@@ -1,13 +1,16 @@
 import { Context } from 'koishi';
 import { BaseDrawer } from '../BaseDrawer';
+/**
+ * IIDX绘图类，提供IIDX游戏相关图像生成功能
+ */
 export declare class IIDXDrawer extends BaseDrawer {
     ctx: Context;
     constructor(ctx: Context);
     /**
-     * Generate an image for IIDX data
-     * @param options Configuration options for image generation
-     * @param compression Compression options
-     * @returns Promise resolving to a Buffer containing the image data
+     * 生成IIDX游戏数据图像
+     * @param options - 图像生成配置选项
+     * @param compression - 压缩选项
+     * @returns 包含图像数据的Buffer
      */
     generateImage(options?: {
         width?: number;
@@ -23,7 +26,13 @@ export declare class IIDXDrawer extends BaseDrawer {
         quality?: number;
     }): Promise<Buffer>;
     /**
-     * Draw ranking information
+     * 绘制段位信息
+     * @param ctx - Canvas上下文
+     * @param centerX - 中心X坐标
+     * @param y - 起始Y坐标
+     * @param sp_dan - sp 段位
+     * @param dp_dan - dp 段位
+     * @param textColor - 文字颜色
      */
     private drawRankingInfo;
 }

package/lib/drawer/index.d.ts

@@ -7,7 +7,22 @@ export declare class DrawerManager {
     private factory;
     private logger;
     private constructor();
+    /**
+     * 获取绘图管理器实例
+     * @param ctx - Koishi上下文
+     * @returns 绘图管理器的唯一实例
+     */
     static getInstance(ctx: Context): DrawerManager;
-    getDrawer(gameType: TGame | 'core'): import("../types").IDrawer;
+    /**
+     * 根据插件类型获取对应的绘图实例
+     * @param pluginType - 插件类型
+     * @returns 对应的绘图实例
+     */
+    getDrawer(pluginType: TGame | 'core'): import("../types").IDrawer;
 }
+/**
+ * 应用函数，初始化插件
+ * @param ctx - Koishi上下文
+ * @param config - 应用配置
+ */
 export declare function apply(ctx: Context, config: AppConfig): void;

package/lib/drawer/sdvx/index.d.ts

@@ -2,14 +2,17 @@ import { Context } from 'koishi';
 import { BaseDrawer } from '../BaseDrawer';
 import { SDVXScore } from '../../games/sdvx/types';
 import { SDVXConfig } from '../../types/config';
+/**
+ * SDVX绘图类，提供SDVX游戏相关图像生成功能
+ */
 export declare class SDVXDrawer extends BaseDrawer {
     ctx: Context;
     constructor(ctx: Context);
     /**
-     * Generate a Recent image for SDVX scores
-     * @param options Configuration options for image generation
-     * @param compression Compression options
-     * @returns Promise resolving to a Buffer containing the image data
+     * 生成SDVX最近成绩图像
+     * @param options - 图像生成配置选项
+     * @param compression - 压缩选项
+     * @returns 包含图像数据的Buffer
      */
     generateRecentImage(options: {
         score: SDVXScore;
@@ -19,10 +22,10 @@ export declare class SDVXDrawer extends BaseDrawer {
         lossless: boolean;
     }): Promise<Buffer>;
     /**
-     * Generate a Volforce image for SDVX scores
-     * @param options Configuration options for image generation
-     * @param compression Compression options
-     * @returns Promise resolving to a Buffer containing the image data
+     * 生成SDVX Volforce图像
+     * @param options - 图像生成配置选项
+     * @param compression - 压缩选项
+     * @returns 包含图像数据的Buffer
      */
     generateVFImage(options: {
         scores: SDVXScore[];
@@ -32,7 +35,12 @@ export declare class SDVXDrawer extends BaseDrawer {
         lossless: boolean;
     }): Promise<Buffer>;
     /**
-     * Draw score cards on the canvas
+     * 在画布上绘制成绩卡片
+     * @param ctx - Canvas上下文
+     * @param scores - 成绩数组
+     * @param cardBgImage - 卡片背景图像
+     * @param loadImage - 图像加载函数
+     * @param config - SDVX配置
      */
     private drawScoreCards;
     /**

package/lib/games/sdvx/config.d.ts

@@ -1,2 +1,7 @@
 import { SDVXConfig } from '../../types/config';
+/**
+ * SDVX 配置模式定义
+ * @property default_model - 默认模型版本
+ * @property sdvx_data_url - SDVX 数据 URL
+ */
 export declare const sdvxConfig: SDVXConfig;

package/lib/games/sdvx/services/music-service.d.ts

@@ -5,6 +5,17 @@ export declare class MusicService {
     private static instance;
     private sdvx_data_url;
     private constructor();
+    /**
+     * 获取 MusicService 实例
+     * @param config - SDVX 配置对象
+     * @returns MusicService 实例
+     */
     static getInstance(config: SDVXConfig): MusicService;
+    /**
+     * 获取音乐信息
+     * @param ctx - Koishi 上下文对象
+     * @param musicIds - 音乐 ID 数组
+     * @returns 音乐信息数组
+     */
     getMusic(ctx: Context, musicIds: number[]): Promise<SDVXMusic[]>;
 }

package/lib/games/sdvx/services/score-service.d.ts

@@ -2,17 +2,21 @@ import { SDVXScore } from '../types';
 export declare class ScoreService {
     private static instance;
     private constructor();
+    /**
+     * 获取 ScoreService 实例
+     * @returns ScoreService 实例
+     */
     static getInstance(): ScoreService;
     /**
-     * Sort scores by volforce in descending order
-     * @param scores Array of SDVX scores to sort
-     * @returns New array of scores sorted by volforce (highest to lowest)
+     * 按 Volforce 降序排序分数
+     * @param scores - 待排序的 SDVX 分数数组
+     * @returns 按 Volforce 降序排序的新数组
      */
     sortByVolforce(scores: SDVXScore[]): SDVXScore[];
     /**
-     * Get the top 50 scores by volforce, including ties
-     * @param scores Array of SDVX scores to process
-     * @returns Array of scores with highest volforce values (may exceed 50 if there are ties)
+     * 获取前 50 名分数（包括并列）
+     * @param scores - 待处理的 SDVX 分数数组
+     * @returns 包含最高 Volforce 值的分数数组（如果存在并列，可能超过 50 个）
      */
     getBest50(scores: SDVXScore[]): SDVXScore[];
 }

package/lib/games/sdvx/types/index.d.ts

@@ -1,5 +1,11 @@
+/**
+ * SDVX 用户档案接口
+ */
 export interface SDVXProfile {
 }
+/**
+ * SDVX 分数记录接口
+ */
 export interface SDVXScore {
     music: {
         music_id: number;
@@ -22,8 +28,17 @@ export interface SDVXScore {
     music_data: SDVXMusic;
     difficulty_data: SDVXMusicDifficulty;
 }
+/**
+ * SDVX 分数等级类型
+ */
 export type SDVXGrade = 'S' | 'AAA+' | 'AAA' | 'AA+' | 'AA' | 'A+' | 'A' | 'B' | 'C' | 'D';
+/**
+ * SDVX 通关类型
+ */
 export type SDVXClearType = 'S-PUC' | 'PUC' | 'UC' | 'HC' | 'NC' | 'PLAYED' | 'NO PLAY';
+/**
+ * SDVX 音乐难度数据接口
+ */
 export interface SDVXMusicDifficulty {
     difstr: string;
     difnum: number;
@@ -53,6 +68,9 @@ export interface SDVXMusicDifficulty {
     chart_url: string;
     mirror_chart_url: string;
 }
+/**
+ * SDVX 音乐数据接口
+ */
 export interface SDVXMusic {
     id: number;
     label: string;

package/lib/games/sdvx/utils/vf.d.ts

@@ -1,19 +1,19 @@
 import { SDVXGrade, SDVXClearType, SDVXScore } from '../types';
 /**
- * Calculate volforce based on score, level, grade, and clear type
- * @param raw_score score object from the API
- * @returns The calculated volforce value
+ * 计算 Volforce 值
+ * @param raw_score - API 返回的分数对象
+ * @returns 计算后的 Volforce 值
  */
 export declare function calculateVolforce(raw_score: SDVXScore): number;
 /**
- * Get grade factor for a given grade
- * @param grade The grade to get the factor for
- * @returns The grade factor
+ * 获取指定等级的系数
+ * @param grade - 要获取系数的等级
+ * @returns 等级系数
  */
 export declare function getGradeFactor(grade: SDVXGrade): number;
 /**
- * Get clear factor for a given clear type
- * @param clearType The clear type to get the factor for
- * @returns The clear factor
+ * 获取指定通关类型的系数
+ * @param clearType - 要获取系数的通关类型
+ * @returns 通关类型系数
  */
 export declare function getClearFactor(clearType: SDVXClearType): number;