koishi-plugin-cchess 1.1.1 → 1.3.0

package/README.md

@@ -14,19 +14,15 @@ yarn add koishi-plugin-cchess
 
 | 指令 | 说明 |
 | --- | --- |
-| `cchess.加入 [红/黑]` | 入座 |
-| `cchess.退出` | 开局前离席 |
-| `cchess.开始 [人人/人机]` | 开局，默认人人对战 |
-| `cchess.移动 <着法>` | 落子 |
-| `cchess.悔棋` | 请求悔棋 |
-| `cchess.悔棋 <同意/拒绝>` | 表决悔棋 |
+| `cchess.开始 [红/黑] [人人/人机]` | 入座并开局，双方就位后自动开战 |
+| `cchess.开始 <FEN>` | 摆谱，导入局面后再 `cchess.开始` 即可 |
+| `cchess.悔棋 [同意/拒绝]` | 请求悔棋，也可直接回复同意或拒绝表决 |
 | `cchess.认输` | 认输 |
 | `cchess.结束` | 强制结束棋局 |
-| `cchess.编辑棋盘 <FEN>` | 导入局面 |
-| `cchess.编辑棋盘.导出` | 导出局面 |
+| `cchess.棋绩 [@某人/榜] [胜场/输场] [人数]` | 查询战绩与排行榜 |
 | `cchess.查看云库残局 [DTM/DTC]` | 云库残局统计 |
-| `cchess.排行榜 [胜场/输场] [人数]` | 排行榜 |
-| `cchess.查询玩家记录 [@某人]` | 战绩 |
+
+发送 `cchess.开始` 即入座，双方就位后自动开局，无需单独的加入与退出指令。
 
 着法可直接发送，例如 `炮二平五` 或 `b2e2`。
 

package/lib/index.d.ts

@@ -1,6 +1,6 @@
 import { Context, Schema } from 'koishi';
 export declare const name = "cchess";
-export declare const usage = "## \u4F7F\u7528\n\n`cchess.\u52A0\u5165` \u5165\u5EA7\uFF0C`cchess.\u5F00\u59CB \u4EBA\u4EBA` \u6216 `cchess.\u5F00\u59CB \u4EBA\u673A` \u5F00\u5C40\u3002\u7740\u6CD5\u53EF\u76F4\u63A5\u53D1\u9001\uFF0C\u4F8B\u5982 `\u70AE\u4E8C\u5E73\u4E94` \u6216 `b2e2`\u3002\n\n\u6094\u68CB\u8BF7\u6C42\u9001\u51FA\u540E\uFF0C\u5BF9\u65B9\u65E0\u9700\u5E26\u6307\u4EE4\u524D\u7F00\uFF0C\u76F4\u63A5\u56DE\u590D `\u540C\u610F` \u6216 `\u62D2\u7EDD` \u5373\u53EF\u8868\u51B3\u3002\n\n## \u6307\u4EE4\n\n| \u6307\u4EE4 | \u8BF4\u660E |\n| --- | --- |\n| `cchess.\u52A0\u5165 [\u7EA2/\u9ED1]` | \u5165\u5EA7 |\n| `cchess.\u9000\u51FA` | \u5F00\u5C40\u524D\u79BB\u5E2D |\n| `cchess.\u5F00\u59CB [\u4EBA\u4EBA/\u4EBA\u673A]` | \u5F00\u5C40\uFF0C\u9ED8\u8BA4\u4EBA\u4EBA\u5BF9\u6218 |\n| `cchess.\u79FB\u52A8 <\u7740\u6CD5>` | \u843D\u5B50 |\n| `cchess.\u6094\u68CB` | \u8BF7\u6C42\u6094\u68CB |\n| `cchess.\u6094\u68CB <\u540C\u610F/\u62D2\u7EDD>` | \u8868\u51B3\u6094\u68CB\uFF0C\u4E5F\u53EF\u76F4\u63A5\u56DE\u590D\u540C\u610F\u6216\u62D2\u7EDD |\n| `cchess.\u8BA4\u8F93` | \u8BA4\u8F93 |\n| `cchess.\u7ED3\u675F` | \u5F3A\u5236\u7ED3\u675F\u68CB\u5C40 |\n| `cchess.\u7F16\u8F91\u68CB\u76D8 <FEN>` | \u5BFC\u5165\u5C40\u9762\uFF0C\u4E0D\u5E26\u53C2\u6570\u65F6\u67E5\u770B FEN \u7528\u6CD5 |\n| `cchess.\u7F16\u8F91\u68CB\u76D8.\u5BFC\u51FA` | \u5BFC\u51FA\u5C40\u9762 |\n| `cchess.\u67E5\u770B\u4E91\u5E93\u6B8B\u5C40 [DTM/DTC]` | \u4E91\u5E93\u6B8B\u5C40\u7EDF\u8BA1 |\n| `cchess.\u6392\u884C\u699C [\u80DC\u573A/\u8F93\u573A] [\u4EBA\u6570]` | \u6392\u884C\u699C |\n| `cchess.\u67E5\u8BE2\u73A9\u5BB6\u8BB0\u5F55 [@\u67D0\u4EBA]` | \u6218\u7EE9 |";
+export declare const usage = "## \u4F7F\u7528\n\n`cchess.\u5F00\u59CB` \u5373\u53EF\u5165\u5EA7\uFF0C\u53CC\u65B9\u5C31\u4F4D\u540E\u81EA\u52A8\u5F00\u5C40\uFF1B`cchess.\u5F00\u59CB \u4EBA\u673A` \u76F4\u63A5\u6311\u6218\u76AE\u5361\u9C7C\u3002\u7740\u6CD5\u53EF\u76F4\u63A5\u53D1\u9001\uFF0C\u4F8B\u5982 `\u70AE\u4E8C\u5E73\u4E94` \u6216 `b2e2`\u3002\n\n\u6094\u68CB\u8BF7\u6C42\u9001\u51FA\u540E\uFF0C\u5BF9\u65B9\u65E0\u9700\u5E26\u6307\u4EE4\u524D\u7F00\uFF0C\u76F4\u63A5\u56DE\u590D `\u540C\u610F` \u6216 `\u62D2\u7EDD` \u5373\u53EF\u8868\u51B3\u3002\n\n## \u6307\u4EE4\n\n| \u6307\u4EE4 | \u8BF4\u660E |\n| --- | --- |\n| `cchess.\u5F00\u59CB [\u7EA2/\u9ED1] [\u4EBA\u4EBA/\u4EBA\u673A]` | \u5165\u5EA7\u5E76\u5F00\u5C40\uFF0C\u53CC\u65B9\u5C31\u4F4D\u540E\u81EA\u52A8\u5F00\u6218 |\n| `cchess.\u5F00\u59CB <FEN>` | \u6446\u8C31\uFF0C\u5BFC\u5165\u5C40\u9762\u540E\u518D `cchess.\u5F00\u59CB` \u5373\u53EF |\n| `cchess.\u6094\u68CB [\u540C\u610F/\u62D2\u7EDD]` | \u8BF7\u6C42\u6094\u68CB\uFF0C\u4E5F\u53EF\u76F4\u63A5\u56DE\u590D\u540C\u610F\u6216\u62D2\u7EDD\u8868\u51B3 |\n| `cchess.\u8BA4\u8F93` | \u8BA4\u8F93 |\n| `cchess.\u7ED3\u675F` | \u5F3A\u5236\u7ED3\u675F\u68CB\u5C40 |\n| `cchess.\u68CB\u7EE9 [@\u67D0\u4EBA/\u699C] [\u80DC\u573A/\u8F93\u573A] [\u4EBA\u6570]` | \u67E5\u8BE2\u6218\u7EE9\u4E0E\u6392\u884C\u699C |\n| `cchess.\u67E5\u770B\u4E91\u5E93\u6B8B\u5C40 [DTM/DTC]` | \u4E91\u5E93\u6B8B\u5C40\u7EDF\u8BA1 |";
 export declare const inject: string[];
 export interface Config {
     boardSkin: string;

package/lib/index.js

@@ -38,12 +38,215 @@ __export(src_exports, {
 });
 module.exports = __toCommonJS(src_exports);
 var import_koishi = require("koishi");
+
+// src/m3.ts
+var WHITE_X = 95.047;
+var WHITE_Y = 100;
+var WHITE_Z = 108.883;
+function labToXyz(l, a, b) {
+  const fy = (l + 16) / 116;
+  const fx = fy + a / 500;
+  const fz = fy - b / 200;
+  const f = /* @__PURE__ */ __name((t) => t > 6 / 29 ? t * t * t : 3 * (6 / 29) ** 2 * (t - 4 / 29), "f");
+  return [f(fx) * WHITE_X, f(fy) * WHITE_Y, f(fz) * WHITE_Z];
+}
+__name(labToXyz, "labToXyz");
+function gamma(value) {
+  return value <= 31308e-7 ? value * 12.92 : 1.055 * value ** (1 / 2.4) - 0.055;
+}
+__name(gamma, "gamma");
+function xyzToRgb(x, y, z) {
+  x /= 100;
+  y /= 100;
+  z /= 100;
+  return [
+    gamma(3.2406 * x - 1.5372 * y - 0.4986 * z),
+    gamma(-0.9689 * x + 1.8758 * y + 0.0415 * z),
+    gamma(0.0557 * x - 0.204 * y + 1.057 * z)
+  ];
+}
+__name(xyzToRgb, "xyzToRgb");
+var EPSILON = 1 / 512;
+function lch(tone, chroma, hue) {
+  const radian = hue * Math.PI / 180;
+  const at = /* @__PURE__ */ __name((c) => xyzToRgb(...labToXyz(tone, Math.cos(radian) * c, Math.sin(radian) * c)), "at");
+  const inGamut = /* @__PURE__ */ __name((rgb2) => rgb2.every((value) => value >= -EPSILON && value <= 1 + EPSILON), "inGamut");
+  let rgb = at(chroma);
+  if (!inGamut(rgb)) {
+    let low = 0;
+    let high = chroma;
+    while (high - low > 0.05) {
+      const mid = (low + high) / 2;
+      if (inGamut(at(mid))) low = mid;
+      else high = mid;
+    }
+    rgb = at(low);
+  }
+  return "#" + rgb.map((value) => Math.round(Math.min(1, Math.max(0, value)) * 255).toString(16).padStart(2, "0")).join("");
+}
+__name(lch, "lch");
+function degamma(value) {
+  value /= 255;
+  return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+}
+__name(degamma, "degamma");
+function lchOf(hex) {
+  const value = parseInt(hex.replace("#", "").slice(0, 6), 16) || 0;
+  const r = degamma(value >> 16 & 255);
+  const g = degamma(value >> 8 & 255);
+  const b = degamma(value & 255);
+  const x = (0.4124 * r + 0.3576 * g + 0.1805 * b) * 100 / WHITE_X;
+  const y = (0.2126 * r + 0.7152 * g + 0.0722 * b) * 100 / WHITE_Y;
+  const z = (0.0193 * r + 0.1192 * g + 0.9505 * b) * 100 / WHITE_Z;
+  const f = /* @__PURE__ */ __name((t) => t > (6 / 29) ** 3 ? Math.cbrt(t) : t / (3 * (6 / 29) ** 2) + 4 / 29, "f");
+  const [fx, fy, fz] = [f(x), f(y), f(z)];
+  const a = 500 * (fx - fy);
+  const bb = 200 * (fy - fz);
+  return {
+    tone: 116 * fy - 16,
+    chroma: Math.hypot(a, bb),
+    hue: (Math.atan2(bb, a) * 180 / Math.PI + 360) % 360
+  };
+}
+__name(lchOf, "lchOf");
+function harmonize(hex, tone, chroma = 48, fallbackHue = 0) {
+  const source = lchOf(hex);
+  const hue = source.chroma < 4 ? fallbackHue : source.hue;
+  return lch(tone, source.chroma < 4 ? Math.min(chroma, 6) : chroma, hue);
+}
+__name(harmonize, "harmonize");
+function palette(hue, chroma) {
+  const cache = /* @__PURE__ */ new Map();
+  return (tone) => {
+    const hit = cache.get(tone);
+    if (hit) return hit;
+    const value = lch(tone, chroma, hue);
+    cache.set(tone, value);
+    return value;
+  };
+}
+__name(palette, "palette");
+function palettesOf(hue, options = {}) {
+  const { chroma = 56, tertiaryShift = 60 } = options;
+  return {
+    primary: palette(hue, chroma),
+    secondary: palette(hue, Math.max(16, chroma / 3.2)),
+    tertiary: palette(hue + tertiaryShift, Math.max(28, chroma / 1.8)),
+    neutral: palette(hue, 4),
+    neutralVariant: palette(hue, 9),
+    error: palette(36, 68)
+  };
+}
+__name(palettesOf, "palettesOf");
+function scheme(hue, dark = false, options = {}) {
+  const p = palettesOf(hue, options);
+  const { primary: P, secondary: S, tertiary: T, neutral: N, neutralVariant: V, error: E } = p;
+  if (dark) {
+    return {
+      primary: P(80),
+      onPrimary: P(20),
+      primaryContainer: P(30),
+      onPrimaryContainer: P(90),
+      secondary: S(80),
+      onSecondary: S(20),
+      secondaryContainer: S(30),
+      onSecondaryContainer: S(90),
+      tertiary: T(80),
+      onTertiary: T(20),
+      tertiaryContainer: T(30),
+      onTertiaryContainer: T(90),
+      error: E(80),
+      onError: E(20),
+      errorContainer: E(30),
+      onErrorContainer: E(90),
+      background: N(6),
+      onBackground: N(90),
+      surface: N(6),
+      onSurface: N(90),
+      surfaceVariant: V(30),
+      onSurfaceVariant: V(80),
+      surfaceDim: N(6),
+      surfaceBright: N(24),
+      surfaceContainerLowest: N(4),
+      surfaceContainerLow: N(10),
+      surfaceContainer: N(12),
+      surfaceContainerHigh: N(17),
+      surfaceContainerHighest: N(22),
+      outline: V(60),
+      outlineVariant: V(30),
+      inverseSurface: N(90),
+      inverseOnSurface: N(20),
+      inversePrimary: P(40),
+      scrim: N(0),
+      shadow: N(0)
+    };
+  }
+  return {
+    primary: P(40),
+    onPrimary: P(100),
+    primaryContainer: P(90),
+    onPrimaryContainer: P(30),
+    secondary: S(40),
+    onSecondary: S(100),
+    secondaryContainer: S(90),
+    onSecondaryContainer: S(30),
+    tertiary: T(40),
+    onTertiary: T(100),
+    tertiaryContainer: T(90),
+    onTertiaryContainer: T(30),
+    error: E(40),
+    onError: E(100),
+    errorContainer: E(90),
+    onErrorContainer: E(30),
+    background: N(98),
+    onBackground: N(10),
+    surface: N(98),
+    onSurface: N(10),
+    surfaceVariant: V(90),
+    onSurfaceVariant: V(30),
+    surfaceDim: N(87),
+    surfaceBright: N(98),
+    surfaceContainerLowest: N(100),
+    surfaceContainerLow: N(96),
+    surfaceContainer: N(94),
+    surfaceContainerHigh: N(92),
+    surfaceContainerHighest: N(90),
+    outline: V(50),
+    outlineVariant: V(80),
+    inverseSurface: N(20),
+    inverseOnSurface: N(95),
+    inversePrimary: P(80),
+    scrim: N(0),
+    shadow: N(0)
+  };
+}
+__name(scheme, "scheme");
+var SHAPE = {
+  none: 0,
+  extraSmall: 4,
+  small: 8,
+  medium: 12,
+  large: 16,
+  largeIncreased: 20,
+  extraLarge: 28,
+  extraLargeIncreased: 32,
+  extraExtraLarge: 48,
+  full: 9999
+};
+var FONT_STACK = '"Roboto Flex", "Roboto", "Noto Sans SC", "PingFang SC", "Microsoft YaHei", "Source Han Sans SC", system-ui, sans-serif';
+var MEDAL = {
+  gold: lch(58, 52, 85),
+  silver: lch(66, 5, 260),
+  bronze: lch(48, 36, 48)
+};
+
+// src/index.ts
 var path = __toESM(require("path"));
 var fs = __toESM(require("fs"));
 var name = "cchess";
 var usage = `## 使用
 
-\`cchess.加入\` 入座，\`cchess.开始 人人\` 或 \`cchess.开始 人机\` 开局。着法可直接发送，例如 \`炮二平五\` 或 \`b2e2\`。
+\`cchess.开始\` 即可入座，双方就位后自动开局；\`cchess.开始 人机\` 直接挑战皮卡鱼。着法可直接发送，例如 \`炮二平五\` 或 \`b2e2\`。
 
 悔棋请求送出后，对方无需带指令前缀，直接回复 \`同意\` 或 \`拒绝\` 即可表决。
 
@@ -51,26 +254,20 @@ var usage = `## 使用
 
 | 指令 | 说明 |
 | --- | --- |
-| \`cchess.加入 [红/黑]\` | 入座 |
-| \`cchess.退出\` | 开局前离席 |
-| \`cchess.开始 [人人/人机]\` | 开局，默认人人对战 |
-| \`cchess.移动 <着法>\` | 落子 |
-| \`cchess.悔棋\` | 请求悔棋 |
-| \`cchess.悔棋 <同意/拒绝>\` | 表决悔棋，也可直接回复同意或拒绝 |
+| \`cchess.开始 [红/黑] [人人/人机]\` | 入座并开局，双方就位后自动开战 |
+| \`cchess.开始 <FEN>\` | 摆谱，导入局面后再 \`cchess.开始\` 即可 |
+| \`cchess.悔棋 [同意/拒绝]\` | 请求悔棋，也可直接回复同意或拒绝表决 |
 | \`cchess.认输\` | 认输 |
 | \`cchess.结束\` | 强制结束棋局 |
-| \`cchess.编辑棋盘 <FEN>\` | 导入局面，不带参数时查看 FEN 用法 |
-| \`cchess.编辑棋盘.导出\` | 导出局面 |
-| \`cchess.查看云库残局 [DTM/DTC]\` | 云库残局统计 |
-| \`cchess.排行榜 [胜场/输场] [人数]\` | 排行榜 |
-| \`cchess.查询玩家记录 [@某人]\` | 战绩 |`;
+| \`cchess.棋绩 [@某人/榜] [胜场/输场] [人数]\` | 查询战绩与排行榜 |
+| \`cchess.查看云库残局 [DTM/DTC]\` | 云库残局统计 |`;
 var inject = ["database", "canvas"];
 var pieceSkins = ["棋弈无限图形棋子", "云库木制棋子", "刘炳森红黑牛角隶书棋子", "木制棋子", "本纹隶书棋子", "银灰将军体棋子", "棋弈无限红绿正棋子", "棋弈无限红绿棋子", "棋天大圣棋子", "棋者象棋棋子", "楷书玉石棋子", "水墨青瓷棋子", "牛皮纸华康金文棋子", "皮卡鱼棋子", "红蓝祥隶棋子", "红黑精典无阴影棋子", "红黑精典棋子", "行书玉石棋子", "象甲棋子", "金属棋子篆体棋子", "镌刻华彩棋子", "鹏飞红黑棋子", "鹏飞经典棋子", "鹏飞绿龙棋子", "龙腾四海棋子"];
 var boardSkins = ["棋弈无限红绿棋盘", "一鸣惊人棋盘", "三星堆棋盘", "云库木制棋盘", "云心鹤眼棋盘", "兰亭集序无字棋盘", "兰亭集序棋盘", "凤舞九天棋盘", "卯兔添福棋盘", "叱咤风云棋盘", "君临天下棋盘", "壁画古梦棋盘", "大闹天宫棋盘", "天山共色棋盘", "女神之约棋盘", "小吕飞刀棋盘", "山海绘卷棋盘", "护眼绿棋盘", "星河璀璨棋盘", "木制棋盘", "本纹隶书白棋盘", "本纹隶书黑棋盘", "桃花源记棋盘", "棋天大圣棋盘", "棋天无大圣棋盘", "武侠江湖棋盘", "水墨青瓷棋盘", "清悠茶道棋盘", "游园惊梦棋盘", "牛转乾坤棋盘", "玉石太极棋盘", "皓月无痕棋盘", "皮卡鱼棋盘", "盲棋神迹棋盘", "空城计棋盘", "竹波烟雨棋盘", "经典木棋盘棋盘", "绿色棋盘", "象甲2023棋盘", "象甲征程棋盘", "象甲重燃棋盘", "金牛降世棋盘", "金虎贺岁棋盘", "金虎贺岁（王天一签名版）棋盘", "鎏金岁月棋盘", "霸王别姬棋盘", "鸿门宴棋盘", "鹏飞红黑棋盘", "鹏飞经典棋盘", "鹏飞绿龙棋盘", "龙腾天坛棋盘"];
 var Config = import_koishi.Schema.object({
   boardSkin: import_koishi.Schema.union(boardSkins).default("象甲2023棋盘").description(`棋盘皮肤。`),
   pieceSkin: import_koishi.Schema.union(pieceSkins).default("象甲棋子").description(`棋子皮肤。`),
-  allowFreePieceMovementInHumanMachineMode: import_koishi.Schema.boolean().default(false).description(`是否允许在人机模式下所有用户都可以自由移动棋子，开启后可以不需要加入游戏直接开始玩人机模式。`),
+  allowFreePieceMovementInHumanMachineMode: import_koishi.Schema.boolean().default(false).description(`是否允许在人机模式下所有用户都可以自由移动棋子，开启后可以不入座直接开始人机对局。`),
   defaultEngineThinkingDepth: import_koishi.Schema.number().min(0).max(100).default(10).description(`默认引擎思考深度，越高 AI 棋力越强，耗时也越长（小于 1 时按 1 计算）。由于 Nodejs 不支持 SIMD，所以不建议设置过高。`),
   defaultMaxLeaderboardEntries: import_koishi.Schema.number().min(0).default(10).description(`显示排行榜时默认的最大人数。`),
   retractDelay: import_koishi.Schema.number().min(0).default(0).description(`自动撤回等待的时间，单位是秒。值为 0 时不启用自动撤回功能。`),
@@ -121,6 +318,22 @@ function apply(ctx, config) {
       }
     });
   });
+  const FRAME = scheme(60);
+  function roundRect(context, x, y, width, height, radius) {
+    const r = Math.max(0, Math.min(radius, width / 2, height / 2));
+    context.beginPath();
+    context.moveTo(x + r, y);
+    context.lineTo(x + width - r, y);
+    context.arcTo(x + width, y, x + width, y + r, r);
+    context.lineTo(x + width, y + height - r);
+    context.arcTo(x + width, y + height, x + width - r, y + height, r);
+    context.lineTo(x + r, y + height);
+    context.arcTo(x, y + height, x, y + height - r, r);
+    context.lineTo(x, y + r);
+    context.arcTo(x, y, x + r, y, r);
+    context.closePath();
+  }
+  __name(roundRect, "roundRect");
   const CELL_WIDTH = 54;
   const ARROW_OFFSET = 33;
   const BOARD_PADDING = 33;
@@ -138,8 +351,14 @@ function apply(ctx, config) {
   const thinkingDepth = Math.max(1, Math.round(config.defaultEngineThinkingDepth) || 1);
   const ENGINE_TIMEOUT = 120 * 1e3;
   const piecesImgResources = loadPiecesImageResources(config.pieceSkin);
-  const outerFrameImg = fs.readFileSync(path.join(__dirname, "assets", "棋盘皮肤", `外框.png`));
   const boardSkinImg = fs.readFileSync(path.join(__dirname, "assets", "棋盘皮肤", `${config.boardSkin}.webp`));
+  const FRAME_WIDTH = 620;
+  const FRAME_HEIGHT = 780;
+  const FRAME_BOARD = { x: 36.5, y: 90, width: 550, height: 605 };
+  const FRAME_ZOOM = FRAME_BOARD.width / BOARD_WIDTH;
+  const FILES = ["a", "b", "c", "d", "e", "f", "g", "h", "i"];
+  const RED_FILES = ["九", "八", "七", "六", "五", "四", "三", "二", "一"];
+  const ARROW_COLOR = harmonize("#80ab45", 58, 56);
   const possibleFigureNames = ["将", "士", "象", "车", "马", "炮", "卒", "帅", "仕", "相", "兵"];
   ctx.model.extend("cchess_game_records", {
     id: "unsigned",
@@ -238,131 +457,82 @@ function apply(ctx, config) {
     if (playerRecord.length !== 0 && playerRecord[0].side !== convertTurnToString(gameRecord.turn)) {
       return next();
     }
-    await session.execute(`cchess.移动 ${moveOperation}`);
+    await handleMove(session, moveOperation);
   });
   ctx.command("cchess", "中国象棋游戏指令帮助").action(async ({ session }) => {
     await session.execute(`cchess -h`);
   });
-  ctx.command("cchess.加入 [choice:string]", "加入游戏并选择红黑方").action(async ({ session }, choice) => {
+  ctx.command("cchess.开始 [args:text]", "入座并开局；可选「红 / 黑」「人人 / 人机」，也可直接粘贴 FEN 摆谱").action(async ({ session }, args) => {
     const { username, userId, channelId } = session;
     await updateNameInPlayerRecord(userId, username);
     const gameRecord = await getGameRecord(channelId);
     if (gameRecord.isStarted) {
+      return await sendMessage(session, alreadyStartedPanel(username));
+    }
+    const text = (args ?? "").trim();
+    if (text && isValidateFen(text)) {
+      const startFen = text.includes("moves") ? text.split("moves")[0].trim() : text;
+      await ctx.database.set("cchess_game_records", { channelId }, {
+        turn: fenToTurn(text),
+        board: fenToBoard(text),
+        moveList: [],
+        movesAfterLastEat: [],
+        boardAfterLastEat: fenToBoard(text),
+        turnAfterLastEat: fenToTurn(text),
+        lastMove: null,
+        isHistoryMode: false,
+        originalState: {},
+        startFen
+      });
+      await parseFen(channelId, text);
+      const record = await getGameRecord(channelId);
       return await sendMessage(session, panel({
-        icon: "⚠️",
-        title: "棋局已经开战",
+        icon: "✅",
+        title: "棋盘摆放完毕",
         at: username,
-        body: ["本局正在进行，无法中途加入。"],
-        tips: ["本局结束后可再加入。"],
+        body: [field("轮走方", withSideIcon(convertTurnToString(record.turn)))],
+        tips: ["发送「cchess.开始」由此局面开战"],
         image: await renderBoard(channelId)
       }));
     }
-    void checkEngine(channelId);
-    if (choice?.includes("红") && choice.includes("黑")) {
+    if (text.includes("红") && text.includes("黑")) {
       return await sendMessage(session, panel({
         icon: "⚠️",
         title: "一次只能选一方",
         at: username,
         body: ["请只选择红方或黑方。"],
-        tips: ["「cchess.加入 红」执红先行", "「cchess.加入 黑」执黑应招"]
-      }));
-    }
-    if (choice?.includes("红")) choice = "红方";
-    else if (choice?.includes("黑")) choice = "黑方";
-    else choice = Math.random() < 0.5 ? "红方" : "黑方";
-    const selfRecords = await ctx.database.get("cchess_gaming_player_records", { channelId, userId });
-    const allRecords = await ctx.database.get("cchess_gaming_player_records", { channelId });
-    const playersNum = allRecords.length;
-    if (selfRecords.length === 0) {
-      await ctx.database.create("cchess_gaming_player_records", { channelId, userId, username, side: choice });
-      return await sendMessage(session, panel({
-        icon: "✅",
-        title: "入座成功",
-        at: username,
-        body: [field("阵营", withSideIcon(choice)), field("当前人数", `${playersNum + 1} 人`)],
-        tips: ["再次发送「cchess.加入 红 / 黑」即可换边", "人齐后发送「cchess.开始 人人」开局"]
-      }));
-    } else {
-      await ctx.database.set("cchess_gaming_player_records", { channelId, userId }, { side: choice });
-      return await sendMessage(session, panel({
-        icon: "✅",
-        title: "换边成功",
-        at: username,
-        body: [field("新的阵营", withSideIcon(choice)), field("当前人数", `${playersNum} 人`)]
+        tips: ["「cchess.开始 红」执红先行", "「cchess.开始 黑」执黑应招"]
       }));
     }
-  });
-  ctx.command("cchess.退出", "退出游戏").action(async ({ session }) => {
-    const { username, userId, channelId } = session;
-    await updateNameInPlayerRecord(userId, username);
-    const gameRecord = await getGameRecord(channelId);
-    if (gameRecord.isStarted) {
-      return await sendMessage(session, panel({
-        icon: "⚠️",
-        title: "棋局已经开战",
-        at: username,
-        body: ["对局进行中，无法退出。"],
-        tips: ["可发送「cchess.认输」结束本局"]
-      }));
-    }
-    const selfRecords = await ctx.database.get("cchess_gaming_player_records", { channelId, userId });
-    const allRecords = await ctx.database.get("cchess_gaming_player_records", { channelId });
-    const playersNum = allRecords.length;
-    if (selfRecords.length === 0) {
-      return await sendMessage(session, notJoinedPanel(username));
-    } else {
-      await ctx.database.remove("cchess_gaming_player_records", { channelId, userId });
-      return await sendMessage(session, panel({
-        icon: "✅",
-        title: "已离席",
-        at: username,
-        body: ["已退出本局。", field("剩余人数", `${playersNum - 1} 人`)]
-      }));
-    }
-  });
-  ctx.command("cchess.开始 [mode:string]", "开始对局，mode 可选「人人」或「人机」").action(async ({ session }, mode) => {
-    const { username, userId, channelId } = session;
-    await updateNameInPlayerRecord(userId, username);
-    const gameRecord = await getGameRecord(channelId);
-    if (gameRecord.isStarted) {
-      return await sendMessage(session, alreadyStartedPanel(username));
-    }
-    const playerRecords = await ctx.database.get("cchess_gaming_player_records", { channelId });
-    const playersNum = playerRecords.length;
-    if (/机|电脑|ai|engine|pve/i.test(mode ?? "")) {
-      return await startVersusEngine(session, gameRecord, playerRecords);
-    }
+    const chosenSide = text.includes("红") ? "红方" : text.includes("黑") ? "黑方" : "";
     void checkEngine(channelId);
-    let redPlayers = playerRecords.filter((player) => player.side === "红方");
-    let blackPlayers = playerRecords.filter((player) => player.side === "黑方");
-    let assignNotice = "";
-    if (playersNum < 2) {
+    if (/机|电脑|ai|engine|pve/i.test(text)) {
+      const players2 = await seatPlayer(channelId, userId, username, chosenSide);
+      return await startVersusEngine(session, gameRecord, players2);
+    }
+    const players = await seatPlayer(channelId, userId, username, chosenSide);
+    const redPlayers = players.filter((player) => player.side === "红方");
+    const blackPlayers = players.filter((player) => player.side === "黑方");
+    const selfSide = players.find((player) => player.userId === userId)?.side ?? "";
+    if (!redPlayers.length || !blackPlayers.length) {
       return await sendMessage(session, panel({
-        icon: "⚠️",
-        title: "棋差一手，人差一位",
+        icon: "⏳",
+        title: "已入座，静候对手",
         at: username,
-        body: ["人人对战至少需要 2 位棋手。", field("当前人数", `${playersNum} 人`)],
-        tips: ["邀请好友发送「cchess.加入」一同入座"]
+        body: [
+          field("阵营", withSideIcon(selfSide)),
+          field("当前人数", `${players.length} 人`),
+          !blackPlayers.length ? "黑方尚无人。" : "红方尚无人。"
+        ],
+        tips: ["好友发送「cchess.开始」补位，双方就位即自动开局", "「cchess.开始 黑」可指定阵营"]
       }));
     }
-    if (redPlayers.length !== 1 || blackPlayers.length !== 1) {
-      const randomPlayer = playerRecords[Math.floor(Math.random() * playerRecords.length)];
-      randomPlayer.side = redPlayers.length < 1 ? "红方" : "黑方";
-      assignNotice = `🎲 @${randomPlayer.username} 被随机分配至 ${withSideIcon(randomPlayer.side)}`;
-      await ctx.database.set("cchess_gaming_player_records", {
-        channelId,
-        userId: randomPlayer.userId
-      }, { side: randomPlayer.side });
-      redPlayers = playerRecords.filter((player) => player.side === "红方");
-      blackPlayers = playerRecords.filter((player) => player.side === "黑方");
-    }
     await ctx.database.set("cchess_game_records", { channelId }, { isStarted: true });
     const sideString = convertTurnToString(gameRecord.turn);
     return await sendMessage(session, panel({
       icon: "✅",
       title: "楚河汉界，对局开始",
       body: [
-        ...assignNotice ? [assignNotice, ""] : [],
         `${withSideIcon("红方")}（${redPlayers.length}）`,
         ...redPlayers.map((player) => `　@${player.username}`),
         "",
@@ -385,7 +555,7 @@ function apply(ctx, config) {
         title: "棋盘尚且空空",
         at: username,
         body: ["当前没有进行中的对局，无需收拾残局。"],
-        tips: ["发送「cchess.加入」入座，再开一局"]
+        tips: ["发送「cchess.开始」入座，再开一局"]
       }));
     }
     await endGame(channelId);
@@ -394,10 +564,10 @@ function apply(ctx, config) {
       title: "对局已强制结束",
       at: username,
       body: ["棋盘已收，胜负不计。"],
-      tips: ["发送「cchess.加入」重整旗鼓"]
+      tips: ["发送「cchess.开始」重整旗鼓"]
     }));
   });
-  ctx.command("cchess.移动 <moveOperation:text>", "进行移动操作").action(async ({ session }, moveOperation) => {
+  async function handleMove(session, moveOperation) {
     const { username, userId, channelId } = session;
     await updateNameInPlayerRecord(userId, username);
     moveOperation = moveOperation?.trim();
@@ -519,7 +689,8 @@ function apply(ctx, config) {
     } finally {
       busyChannels.delete(channelId);
     }
-  });
+  }
+  __name(handleMove, "handleMove");
   ctx.command("cchess.悔棋 [decision:string]", "请求悔棋；待决时由对方以「同意 / 拒绝」表决").action(async ({ session }, decision) => {
     const { username, userId, channelId } = session;
     await updateNameInPlayerRecord(userId, username);
@@ -635,109 +806,30 @@ function apply(ctx, config) {
       body: isDtc ? ["DTC：距吃子的步数统计。", "https://www.chessdb.cn/egtb_info.html"] : ["DTM：距将死的步数统计。", "https://www.chessdb.cn/egtb_info_dtm.html"]
     }));
   });
-  ctx.command("cchess.编辑棋盘 [fen:text]", "导入 FEN 局面，不带参数时查看 FEN 用法").action(async ({ session }, fen) => {
-    const { username, userId, channelId } = session;
-    await updateNameInPlayerRecord(userId, username);
-    if (!fen) {
-      return await sendMessage(session, panel({
-        icon: "📋",
-        title: "FEN 串使用方法",
-        at: username,
-        body: ["中国象棋 FEN 格式规范：", "https://www.xqbase.com/protocol/cchess_fen.htm"]
-      }));
-    }
-    const gameRecord = await getGameRecord(channelId);
-    if (gameRecord.isStarted) {
-      return await sendMessage(session, panel({
-        icon: "⚠️",
-        title: "棋局进行中",
-        at: username,
-        body: ["对弈期间不可改动棋盘。"],
-        tips: ["发送「cchess.结束」收局后再行摆谱"]
-      }));
-    }
-    fen = fen?.trim();
-    if (!fen || !isValidateFen(fen)) {
-      return await sendMessage(session, panel({
-        icon: "❌",
-        title: "FEN 串无法解析",
-        at: username,
-        body: ["请检查局面串的格式是否完整。"],
-        tips: [
-          "示例：rnbakabnr/9/1c5c1/p1p1p1p1p/9/9/P1P1P1P1P/1C5C1/9/RNBAKABNR w",
-          "发送「cchess.编辑棋盘」查看规范"
-        ]
-      }));
-    }
-    const newStartFen = fen.includes("moves") ? fen.split("moves")[0].trim() : fen;
-    await ctx.database.set("cchess_game_records", { channelId }, {
-      turn: fenToTurn(fen),
-      board: fenToBoard(fen),
-      moveList: [],
-      movesAfterLastEat: [],
-      boardAfterLastEat: fenToBoard(fen),
-      turnAfterLastEat: fenToTurn(fen),
-      lastMove: null,
-      isHistoryMode: false,
-      originalState: {},
-      startFen: newStartFen
-    });
-    await parseFen(channelId, fen);
-    const record = await getGameRecord(channelId);
-    return await sendMessage(session, panel({
-      icon: "✅",
-      title: "棋盘摆放完毕",
-      at: username,
-      body: [field("轮走方", withSideIcon(convertTurnToString(record.turn)))],
-      tips: ["发送「cchess.开始 人人」或「cchess.开始 人机」由此局面开战"],
-      image: await renderBoard(channelId)
-    }));
-  });
-  ctx.command("cchess.编辑棋盘.导出", "导出FEN串").action(async ({ session }) => {
-    const { username, userId, channelId } = session;
-    await updateNameInPlayerRecord(userId, username);
-    const gameRecord = await getGameRecord(channelId);
-    if (!gameRecord.isStarted) {
-      return await sendMessage(session, notStartedPanel(username));
-    }
-    if (gameRecord.isAnalyzing || busyChannels.has(channelId)) {
-      return await sendMessage(session, analyzingPanel(username));
-    }
-    const fenWithFullMove = await getFenWithFullMove(channelId);
-    return await sendMessage(session, panel({
-      icon: "📋",
-      title: "当前局面 FEN",
-      at: username,
-      body: [fenWithFullMove],
-      tips: ["可用「cchess.编辑棋盘 <FEN>」还原此局面"]
-    }));
-  });
-  ctx.command("cchess.排行榜 [type:string] [number:number]", "查看玩家排行榜").action(async ({ session }, type, number = config.defaultMaxLeaderboardEntries) => {
-    const { userId, username } = session;
-    await updateNameInPlayerRecord(userId, username);
-    if (type && /^\d+$/.test(type)) {
-      number = Number(type);
-      type = "";
-    }
-    if (typeof number !== "number" || isNaN(number) || number < 0) {
-      return await sendMessage(session, invalidLeaderboardSizePanel(username));
-    }
-    const byLose = !!type && /负|输|lose/i.test(type);
-    return await getLeaderboard(
-      session,
-      byLose ? "lose" : "win",
-      byLose ? "总输场排行榜" : "总胜场排行榜",
-      byLose ? "🍂" : "🏆",
-      number
-    );
-  });
-  ctx.command("cchess.查询玩家记录 [targetUser:text]", "查询玩家记录").action(async ({ session }, targetUser) => {
+  ctx.command("cchess.棋绩 [args:text]", "查询战绩；带「榜」看排行榜，@某人 可查看对方战绩").action(async ({ session }, args) => {
     let { userId, username } = session;
     await updateNameInPlayerRecord(userId, username);
-    if (targetUser) {
-      targetUser = await replaceAtTags(session, targetUser);
-      const userIdRegex = /<at id="([^"]+)"(?: name="([^"]+)")?\/>/;
-      const match = targetUser.match(userIdRegex);
+    const text = (args ?? "").trim();
+    const byLose = /负|输|lose/i.test(text);
+    const numberMatch = text.match(/\d+/);
+    const hasTarget = text.includes("<at");
+    const isLeaderboard = !hasTarget && (/榜|排行|排名|leaderboard/i.test(text) || byLose || !!numberMatch);
+    if (isLeaderboard) {
+      const size = numberMatch ? Number(numberMatch[0]) : config.defaultMaxLeaderboardEntries;
+      if (isNaN(size) || size < 0) {
+        return await sendMessage(session, invalidLeaderboardSizePanel(username));
+      }
+      return await getLeaderboard(
+        session,
+        byLose ? "lose" : "win",
+        byLose ? "总输场排行榜" : "总胜场排行榜",
+        byLose ? "🍂" : "🏆",
+        size
+      );
+    }
+    if (hasTarget) {
+      const replaced = await replaceAtTags(session, text);
+      const match = replaced.match(/<at id="([^"]+)"(?: name="([^"]+)")?\/>/);
       userId = match?.[1] ?? userId;
       username = match?.[2] ?? username;
     }
@@ -754,7 +846,7 @@ function apply(ctx, config) {
         title: "棋士档案",
         at: session.username,
         body: [field("查询对象", username), "尚无对局记录，静待首战。"],
-        tips: ["发送「cchess.加入」开启第一局"]
+        tips: ["发送「cchess.开始」开启第一局"]
       }));
     }
     const { win, lose } = targetUserRecord[0];
@@ -779,7 +871,7 @@ function apply(ctx, config) {
       title: "棋局尚未开始",
       at: username,
       body: ["当前频道还没有进行中的对局。"],
-      tips: ["「cchess.加入」入座", "「cchess.开始 人人」与好友手谈", "「cchess.开始 人机」挑战皮卡鱼"]
+      tips: ["「cchess.开始」入座并对弈", "「cchess.开始 人机」挑战皮卡鱼"]
     });
   }
   __name(notStartedPanel, "notStartedPanel");
@@ -798,8 +890,8 @@ function apply(ctx, config) {
       icon: "⚠️",
       title: "你尚未入座",
       at: username,
-      body: ["请先加入对局。"],
-      tips: ["发送「cchess.加入」加入对局"]
+      body: ["请先入座再落子。"],
+      tips: ["发送「cchess.开始」入座"]
     });
   }
   __name(notJoinedPanel, "notJoinedPanel");
@@ -838,7 +930,7 @@ function apply(ctx, config) {
       title: "皮卡鱼尚未就绪",
       at: username,
       body: ["引擎启动失败，暂时无法进行人机对战。"],
-      tips: ["稍后重试，或改用「cchess.开始 人人」"]
+      tips: ["稍后重试，或改用「cchess.开始」人人对战"]
     });
   }
   __name(engineUnavailablePanel, "engineUnavailablePanel");
@@ -848,7 +940,7 @@ function apply(ctx, config) {
       title: "榜单人数有误",
       at: username,
       body: ["请输入不小于 0 的整数。"],
-      tips: ["例如：cchess.排行榜 胜场 10"]
+      tips: ["例如：cchess.棋绩 榜 10"]
     });
   }
   __name(invalidLeaderboardSizePanel, "invalidLeaderboardSizePanel");
@@ -874,7 +966,7 @@ function apply(ctx, config) {
         field("胜方", withSideIcon(convertTurnToString(winSide))),
         field("棋手", winners.length ? winners.map((player) => `@${player.username}`).join("、") : "皮卡鱼")
       ],
-      tips: ["发送「cchess.加入」再战一局"],
+      tips: ["发送「cchess.开始」再战一局"],
       image
     });
   }
@@ -884,15 +976,6 @@ function apply(ctx, config) {
     const playersNum = playerRecords.length;
     const redPlayers = playerRecords.filter((player) => player.side === "红方");
     const blackPlayers = playerRecords.filter((player) => player.side === "黑方");
-    if (playersNum < 1 && !config.allowFreePieceMovementInHumanMachineMode) {
-      return await sendMessage(session, panel({
-        icon: "⚠️",
-        title: "尚无棋手入座",
-        at: username,
-        body: ["人机对战至少需要 1 位棋手。"],
-        tips: ["发送「cchess.加入」即可入座挑战皮卡鱼"]
-      }));
-    }
     if (!await checkEngine(channelId)) {
       return await sendMessage(session, engineUnavailablePanel(username));
     }
@@ -1027,7 +1110,7 @@ function apply(ctx, config) {
       icon,
       title,
       body: topPlayers.length ? topPlayers.map((player, index) => `${MEDALS[index] ?? `${index + 1}.`} ${player.username}　${player[sortField]} 局`) : ["榜上尚无名姓，快去手谈一局。"],
-      tips: topPlayers.length ? [] : ["发送「cchess.加入」开启对局"]
+      tips: topPlayers.length ? [] : ["发送「cchess.开始」开启对局"]
     }));
   }
   __name(getLeaderboard, "getLeaderboard");
@@ -1080,18 +1163,29 @@ function apply(ctx, config) {
     return false;
   }
   __name(requestEngineMove, "requestEngineMove");
-  async function getFenWithFullMove(channelId, separator = " ") {
-    const gameRecord = await getGameRecord(channelId);
-    const { startFen, moveList } = gameRecord;
-    let moves = [];
-    for (let move of moveList) moves.push(move.move);
-    let fullFen = startFen;
-    if (moves.length > 0) {
-      fullFen += " moves " + moves.join(separator);
+  async function seatPlayer(channelId, userId, username, chosenSide) {
+    const players = await ctx.database.get("cchess_gaming_player_records", { channelId });
+    const self = players.find((player) => player.userId === userId);
+    if (!self) {
+      await ctx.database.create("cchess_gaming_player_records", {
+        channelId,
+        userId,
+        username,
+        side: chosenSide || balancedSide(players)
+      });
+    } else if (chosenSide && self.side !== chosenSide) {
+      await ctx.database.set("cchess_gaming_player_records", { channelId, userId }, { side: chosenSide });
     }
-    return fullFen;
+    return await ctx.database.get("cchess_gaming_player_records", { channelId });
+  }
+  __name(seatPlayer, "seatPlayer");
+  function balancedSide(players) {
+    const redNum = players.filter((player) => player.side === "红方").length;
+    const blackNum = players.length - redNum;
+    if (redNum === blackNum) return Math.random() < 0.5 ? "红方" : "黑方";
+    return redNum < blackNum ? "红方" : "黑方";
   }
-  __name(getFenWithFullMove, "getFenWithFullMove");
+  __name(balancedSide, "balancedSide");
   function fenToTurn(t) {
     let e = t.split(" ");
     return "b" == e[1] ? "b" : "w";
@@ -1520,12 +1614,42 @@ function apply(ctx, config) {
   }
   __name(convertTurnToString, "convertTurnToString");
   async function createImage(buffer) {
-    const canvas = await ctx.canvas.createCanvas(620 * scale, 780 * scale);
+    const canvas = await ctx.canvas.createCanvas(FRAME_WIDTH * scale, FRAME_HEIGHT * scale);
     const context = canvas.getContext("2d");
-    const outerFrame = await ctx.canvas.loadImage(outerFrameImg);
-    context.drawImage(outerFrame, 0, 0, 620 * scale, 780 * scale);
+    context.scale(scale, scale);
+    context.fillStyle = FRAME.surfaceContainer;
+    roundRect(context, 0, 0, FRAME_WIDTH, FRAME_HEIGHT, SHAPE.extraLarge);
+    context.fill();
     const boardImg = await ctx.canvas.loadImage(buffer);
-    context.drawImage(boardImg, 36.5 * scale, 90 * scale, 550 * scale, 605 * scale);
+    context.drawImage(
+      boardImg,
+      FRAME_BOARD.x,
+      FRAME_BOARD.y,
+      FRAME_BOARD.width,
+      FRAME_BOARD.height
+    );
+    const columnAt = /* @__PURE__ */ __name((col) => FRAME_BOARD.x + (col * CELL_WIDTH + BOARD_PADDING) * FRAME_ZOOM, "columnAt");
+    const rowAt = /* @__PURE__ */ __name((row) => FRAME_BOARD.y + (row * CELL_WIDTH + BOARD_PADDING) * FRAME_ZOOM, "rowAt");
+    context.textAlign = "center";
+    context.textBaseline = "middle";
+    const label = /* @__PURE__ */ __name((text, x, y, size, color) => {
+      context.font = `600 ${size}px ${FONT_STACK}`;
+      context.fillStyle = color;
+      context.fillText(text, x, y);
+    }, "label");
+    for (let col = 0; col < 9; col++) {
+      const x = columnAt(isFlipBoard ? 8 - col : col);
+      label(FILES[col], x, 30, 22, FRAME.onSurfaceVariant);
+      label(String(col + 1), x, 64, 22, FRAME.outline);
+      label(RED_FILES[col], x, FRAME_HEIGHT - 62, 24, FRAME.onSurfaceVariant);
+      label(FILES[col], x, FRAME_HEIGHT - 26, 22, FRAME.outline);
+    }
+    for (let row = 0; row < 10; row++) {
+      const y = rowAt(isFlipBoard ? 9 - row : row);
+      const text = String(9 - row);
+      label(text, 19, y, 22, FRAME.outline);
+      label(text, FRAME_WIDTH - 19, y, 22, FRAME.outline);
+    }
     return canvas.toBuffer(imageMimeType);
   }
   __name(createImage, "createImage");
@@ -1995,7 +2119,7 @@ function apply(ctx, config) {
       let dist = Math.sqrt((startX - endX) ** 2 + (startY - endY) ** 2);
       let adjustedEndX = startX + (endX - startX) * (dist - 30) / dist;
       let adjustedEndY = startY + (endY - startY) * (dist - 30) / dist;
-      await drawLineArrow(context, startX * scale, startY * scale, adjustedEndX * scale, adjustedEndY * scale, "rgba(128, 171, 69, 0.7)", 15 * scale);
+      await drawLineArrow(context, startX * scale, startY * scale, adjustedEndX * scale, adjustedEndY * scale, ARROW_COLOR + "b3", 15 * scale);
     }
     if (moveList.length > 0) {
       const currentMoveId = moveList[moveList.length - 1].moveId;

package/lib/m3.d.ts

@@ -0,0 +1,256 @@
+/**
+ * Material 3 Expressive 设计系统。
+ *
+ * 只依赖标准库，输出纯 CSS 变量与常量，任何渲染后端（puppeteer / canvas）都能用。
+ * 色板按 M3 的做法从一个源色推出六套色调板，再按角色映射成明暗两套配色。
+ */
+/** M3 的「色调」就是 CIE L*，0 为黑、100 为白。 */
+export type Tone = number;
+/** LCh -> #rrggbb。超出 sRGB 色域时按二分法降低彩度，色调与色相保持不变。 */
+export declare function lch(tone: Tone, chroma: number, hue: number): string;
+/** `#rrggbb` -> LCh，`lch()` 的逆运算。 */
+export declare function lchOf(hex: string): {
+    tone: number;
+    chroma: number;
+    hue: number;
+};
+/**
+ * 把一个任意来源的颜色（头像主色、用户自选色）收进本设计系统。
+ *
+ * 只保留它的色相，色调与彩度一律换成设计系统里的取值——于是每个人都还有
+ * 自己的颜色，整张图的明度节奏却是齐的，不会因为某个头像特别暗就糊成一团。
+ * 彩度太低的灰色头像没有可用的色相，退回主色。
+ */
+export declare function harmonize(hex: string, tone: Tone, chroma?: number, fallbackHue?: number): string;
+/** 一套色调板：固定色相与彩度，按色调取色。 */
+export type Palette = (tone: Tone) => string;
+export declare function palette(hue: number, chroma: number): Palette;
+export interface Palettes {
+    primary: Palette;
+    secondary: Palette;
+    tertiary: Palette;
+    neutral: Palette;
+    neutralVariant: Palette;
+    error: Palette;
+}
+export interface SourceOptions {
+    /** 主色彩度，默认 56，够鲜艳又不至于在浅色调上大面积溢出色域。 */
+    chroma?: number;
+    /**
+     * 第三色相对主色的相位差，默认 +60°。
+     * 这个值规范里是个经验值，并非永远合适：暖橙 +60° 会落到发闷的橄榄绿，
+     * 这种时候改成 -60° 取玫红，强调色才跳得出来。
+     */
+    tertiaryShift?: number;
+}
+/**
+ * 按 M3 的推导规则从源色相生成六套色调板。
+ *
+ * Expressive 相比基础风格更敢用彩度：第三色比规范里的保守取值更高，
+ * 中性色也留了一点源色的味道，成片的表面不会灰得发死。
+ */
+export declare function palettesOf(hue: number, options?: SourceOptions): Palettes;
+export interface Scheme {
+    primary: string;
+    onPrimary: string;
+    primaryContainer: string;
+    onPrimaryContainer: string;
+    secondary: string;
+    onSecondary: string;
+    secondaryContainer: string;
+    onSecondaryContainer: string;
+    tertiary: string;
+    onTertiary: string;
+    tertiaryContainer: string;
+    onTertiaryContainer: string;
+    error: string;
+    onError: string;
+    errorContainer: string;
+    onErrorContainer: string;
+    background: string;
+    onBackground: string;
+    surface: string;
+    onSurface: string;
+    surfaceVariant: string;
+    onSurfaceVariant: string;
+    surfaceDim: string;
+    surfaceBright: string;
+    surfaceContainerLowest: string;
+    surfaceContainerLow: string;
+    surfaceContainer: string;
+    surfaceContainerHigh: string;
+    surfaceContainerHighest: string;
+    outline: string;
+    outlineVariant: string;
+    inverseSurface: string;
+    inverseOnSurface: string;
+    inversePrimary: string;
+    scrim: string;
+    shadow: string;
+}
+/** 生成一套完整的角色配色。`dark` 为真时返回暗色方案。 */
+export declare function scheme(hue: number, dark?: boolean, options?: SourceOptions): Scheme;
+/**
+ * M3 Expressive 形状刻度（px）。
+ * Expressive 把圆角整体推大了一档，容器之间靠「圆角差」而不是分隔线来分层。
+ */
+export declare const SHAPE: {
+    readonly none: 0;
+    readonly extraSmall: 4;
+    readonly small: 8;
+    readonly medium: 12;
+    readonly large: 16;
+    readonly largeIncreased: 20;
+    readonly extraLarge: 28;
+    readonly extraLargeIncreased: 32;
+    readonly extraExtraLarge: 48;
+    readonly full: 9999;
+};
+/** 正文与标题字体栈，覆盖 Windows / macOS / Linux 与随包字体三种情况。 */
+export declare const FONT_STACK = "\"Roboto Flex\", \"Roboto\", \"Noto Sans SC\", \"PingFang SC\", \"Microsoft YaHei\", \"Source Han Sans SC\", system-ui, sans-serif";
+/** 等宽字体栈，用于比分、倒计时这类需要对齐的数字。 */
+export declare const MONO_STACK = "\"Roboto Mono\", \"JetBrains Mono\", \"SF Mono\", \"Cascadia Mono\", Consolas, \"Noto Sans Mono\", monospace";
+export interface TypeStyle {
+    size: number;
+    line: number;
+    weight: number;
+    tracking: number;
+}
+/**
+ * M3 Expressive 字阶。`emphasized` 档提高字重，用在需要被一眼看到的地方，
+ * 这是 Expressive 与基础风格最直观的差别之一。
+ */
+export declare const TYPE: {
+    displayLarge: {
+        size: number;
+        line: number;
+        weight: number;
+        tracking: number;
+    };
+    displayMedium: {
+        size: number;
+        line: number;
+        weight: number;
+        tracking: number;
+    };
+    displaySmall: {
+        size: number;
+        line: number;
+        weight: number;
+        tracking: number;
+    };
+    headlineLarge: {
+        size: number;
+        line: number;
+        weight: number;
+        tracking: number;
+    };
+    headlineMedium: {
+        size: number;
+        line: number;
+        weight: number;
+        tracking: number;
+    };
+    headlineSmall: {
+        size: number;
+        line: number;
+        weight: number;
+        tracking: number;
+    };
+    titleLarge: {
+        size: number;
+        line: number;
+        weight: number;
+        tracking: number;
+    };
+    titleMedium: {
+        size: number;
+        line: number;
+        weight: number;
+        tracking: number;
+    };
+    titleSmall: {
+        size: number;
+        line: number;
+        weight: number;
+        tracking: number;
+    };
+    bodyLarge: {
+        size: number;
+        line: number;
+        weight: number;
+        tracking: number;
+    };
+    bodyMedium: {
+        size: number;
+        line: number;
+        weight: number;
+        tracking: number;
+    };
+    bodySmall: {
+        size: number;
+        line: number;
+        weight: number;
+        tracking: number;
+    };
+    labelLarge: {
+        size: number;
+        line: number;
+        weight: number;
+        tracking: number;
+    };
+    labelMedium: {
+        size: number;
+        line: number;
+        weight: number;
+        tracking: number;
+    };
+    labelSmall: {
+        size: number;
+        line: number;
+        weight: number;
+        tracking: number;
+    };
+};
+/**
+ * Expressive 的强调字重。取 600 而非规范里的 500：很多机器上只装了 400 / 700 两档，
+ * 500 会回落成常规字重，强调就白做了；600 在这种字体集下会匹配到 700，效果才稳定。
+ * 正文维持 400，字重拉高反而伤可读性。
+ */
+export declare const EMPHASIZED_WEIGHT: {
+    readonly display: 600;
+    readonly headline: 600;
+    readonly title: 600;
+    readonly label: 600;
+};
+/** 阴影高度（dp -> box-shadow），M3 只有 0 ~ 5 六档。 */
+export declare const ELEVATION: readonly ["none", "0 1px 2px 0 rgba(0,0,0,.30), 0 1px 3px 1px rgba(0,0,0,.15)", "0 1px 2px 0 rgba(0,0,0,.30), 0 2px 6px 2px rgba(0,0,0,.15)", "0 1px 3px 0 rgba(0,0,0,.30), 0 4px 8px 3px rgba(0,0,0,.15)", "0 2px 3px 0 rgba(0,0,0,.30), 0 6px 10px 4px rgba(0,0,0,.15)", "0 4px 4px 0 rgba(0,0,0,.30), 0 8px 12px 6px rgba(0,0,0,.15)"];
+/** 把配色方案铺成 `--md-sys-color-*` 变量。 */
+export declare function colorVars(s: Scheme): string;
+/** 形状、字阶、高度的变量，与配色一起构成完整的令牌集。 */
+export declare function systemVars(): string;
+/** 一段可直接塞进 `<style>` 的基础样式：令牌 + 排版重置。 */
+export declare function baseline(s: Scheme): string;
+/**
+ * 通用组件样式。各插件按需挑用，命名统一为 `m3-` 前缀。
+ *
+ * Expressive 的取向体现在三处：圆角整体偏大且同一张图里刻意拉开层次、
+ * 强调元素用高彩度的容器色而不是描边、以及成组元素之间用间距而不是分隔线来断句。
+ */
+/** 金银铜。色调依次 58 / 66 / 48，深浅本身就排出了名次。 */
+export declare const MEDAL: {
+    readonly gold: string;
+    readonly silver: string;
+    readonly bronze: string;
+};
+export declare function components(): string;
+/**
+ * 浏览器端的配色小库，序列化进页面脚本用。
+ *
+ * 有些图是在页面里用 canvas 画的，那边拿不到这个模块。与其在客户端另写一套
+ * HSL 近似，不如把同一套 LCh 运算原样送过去——服务端与浏览器端算出来的颜色
+ * 必须一致，否则「同一支色相」的承诺在两边会对不上。
+ *
+ * 暴露的接口与本模块同名：`M3.lch` / `M3.lchOf` / `M3.harmonize`。
+ */
+export declare function clientColorScript(): string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "koishi-plugin-cchess",
   "description": "Koishi 的中国象棋插件。",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
   "files": [