koishi-plugin-cchess 2.4.0 → 2.4.1

package/DESIGN_SYSTEM.md

@@ -7,13 +7,13 @@
 - 视觉、组件、形状、排版与语义颜色以 [Material 3 / Expressive](https://m3.material.io/) 为准。
 - [Apple HIG](https://developer.apple.com/design/human-interface-guidelines/accessibility) 用于操作反馈、平台惯例、可恢复性与可访问性，不引入 Apple 视觉组件。
 - [WCAG 2.2 AA](https://www.w3.org/TR/WCAG22/) 用于非文本内容、颜色与对比度、时间限制、输入错误和破坏性操作审查。
-- 色彩使用 Google Material Color Utilities 0.4.0 的 HCT 与 Tonal Spot 动态角色，明确使用 2025 色彩规范。历史 `lch` API 名仅用于源码兼容，计算已经统一为 HCT。
+- 色彩使用 Google Material Color Utilities 0.4.0 的 HCT 与 Tonal Spot 动态角色，明确使用 2025 色彩规范。历史 `lch` API 名仅用于源码兼容，计算已经统一为 HCT。彩色角色（primary / secondary / tertiary / error 及其容器）走官方 Tonal Spot；中性面（surface 系列、on-surface 系列、outline 系列）由 HCT 按本设计系统的色调重算——表面留住一点源色味道、文字取深色档，避免成片近白、文字偏浅的发晃感。
 - `m3.ts` 是角色颜色、字阶、间距、圆角、层级和基础组件的唯一源文件。`material-color*.ts` 是固定版本的官方算法生成物，授权见 `THIRD_PARTY_NOTICES.md`。
 - 不额外添加静态截图无法表达的动画；基础 CSS 禁用减少动态效果偏好下的动画和过渡。
 
 ## 输出、交互与内容
 
-1. 图片是信息的增强形式。信息卡、榜单、棋盘在图文模式中附带文字；文字模式保留信息，减少对截图的依赖。
+1. 图文模式只发渲染图，不附文字；完整文字只在用户切到「文字」模式时出现。图片的等价文字随图片标记，切换到文字模式时展开，因此不会在群里重复刷屏。
 2. `插件主指令.显示 文字` / `插件主指令.显示 图文` 切换个人显示偏好；同一机器人中的这些插件共享选择。设置保存在内存，重启恢复图文。文本回复不能把后续条目无提示地压掉；较长管理列表分页。
 3. 裸输入必须符合词法、对局状态及参与条件。多个插件匹配时不执行，要求明确完整指令；完整指令继续可用。
 4. 回复说明当前结果、未完成原因和可执行的下一步，不用管理员日志替代用户可用的反馈。退款、赔付与渲染失败不能伪装成功。

package/lib/index.js

@@ -57,9 +57,10 @@ function usePresentation(ctx, command) {
   });
   return {
     textOnly: /* @__PURE__ */ __name((session) => shared.modes.get(userKey(session)) === true, "textOnly"),
+    /** 图文模式只给图片；图片缺失或用户选了文字模式时才退回文字。 */
     present(session, image, text) {
       if (!image || shared.modes.get(userKey(session))) return text;
-      return [...import_koishi.h.normalize(image), (0, import_koishi.h)("p", {}, import_koishi.h.normalize(text))];
+      return import_koishi.h.normalize(image);
     }
   };
 }
@@ -86,15 +87,42 @@ async function directInputConflict(ctx, session) {
   return true;
 }
 __name(directInputConflict, "directInputConflict");
+var IMAGE_TEXT_TYPE = "ux-image-text";
+function imageText(text) {
+  return (0, import_koishi.h)(IMAGE_TEXT_TYPE, {}, import_koishi.h.normalize(text));
+}
+__name(imageText, "imageText");
+function isImage(element) {
+  return element.type === "img" || element.type === "image";
+}
+__name(isImage, "isImage");
+function isImageText(element) {
+  return element.type === IMAGE_TEXT_TYPE;
+}
+__name(isImageText, "isImageText");
+function imagesOnly(content) {
+  const walk = /* @__PURE__ */ __name((elements) => elements.flatMap((element) => {
+    if (isImageText(element)) return [];
+    if (isImage(element) || !element.children.length) return [element];
+    return [(0, import_koishi.h)(element.type, element.attrs, walk(element.children))];
+  }), "walk");
+  return walk(import_koishi.h.normalize(content));
+}
+__name(imagesOnly, "imagesOnly");
 function withoutImages(content) {
   const walk = /* @__PURE__ */ __name((elements) => elements.flatMap((element) => {
-    if (element.type === "img" || element.type === "image") return [];
+    if (isImage(element)) return [];
+    if (isImageText(element)) return walk(element.children);
     if (element.children.length) return [(0, import_koishi.h)(element.type, element.attrs, walk(element.children))];
     return [element];
   }), "walk");
   return walk(import_koishi.h.normalize(content));
 }
 __name(withoutImages, "withoutImages");
+function choosePresentation(content, textOnly) {
+  return textOnly ? withoutImages(content) : imagesOnly(content);
+}
+__name(choosePresentation, "choosePresentation");
 
 // src/index.ts
 var import_koishi2 = require("koishi");
@@ -5106,9 +5134,13 @@ function harmonize(hex, tone, chroma = 48, fallbackHue = 0) {
 }
 __name(harmonize, "harmonize");
 var SPACING = { xs: 4, sm: 8, md: 12, lg: 16, xl: 24, xxl: 32 };
+var NEUTRAL_CHROMA = 6;
+var NEUTRAL_VARIANT_CHROMA = 12;
 function scheme(hue, dark = false, options = {}) {
   const source = Hct.from(hue, options.chroma ?? 56, 50);
   const dynamic = new SchemeTonalSpot(source, dark, 0, "2025");
+  const neutral = /* @__PURE__ */ __name((tone) => hexFromArgb(Hct.from(hue, NEUTRAL_CHROMA, tone).toInt()), "neutral");
+  const variant = /* @__PURE__ */ __name((tone) => hexFromArgb(Hct.from(hue, NEUTRAL_VARIANT_CHROMA, tone).toInt()), "variant");
   return {
     primary: hexFromArgb(dynamic.primary),
     onPrimary: hexFromArgb(dynamic.onPrimary),
@@ -5126,23 +5158,23 @@ function scheme(hue, dark = false, options = {}) {
     onError: hexFromArgb(dynamic.onError),
     errorContainer: hexFromArgb(dynamic.errorContainer),
     onErrorContainer: hexFromArgb(dynamic.onErrorContainer),
-    background: hexFromArgb(dynamic.background),
-    onBackground: hexFromArgb(dynamic.onBackground),
-    surface: hexFromArgb(dynamic.surface),
-    onSurface: hexFromArgb(dynamic.onSurface),
-    surfaceVariant: hexFromArgb(dynamic.surfaceVariant),
-    onSurfaceVariant: hexFromArgb(dynamic.onSurfaceVariant),
-    surfaceDim: hexFromArgb(dynamic.surfaceDim),
-    surfaceBright: hexFromArgb(dynamic.surfaceBright),
-    surfaceContainerLowest: hexFromArgb(dynamic.surfaceContainerLowest),
-    surfaceContainerLow: hexFromArgb(dynamic.surfaceContainerLow),
-    surfaceContainer: hexFromArgb(dynamic.surfaceContainer),
-    surfaceContainerHigh: hexFromArgb(dynamic.surfaceContainerHigh),
-    surfaceContainerHighest: hexFromArgb(dynamic.surfaceContainerHighest),
-    outline: hexFromArgb(dynamic.outline),
-    outlineVariant: hexFromArgb(dynamic.outlineVariant),
-    inverseSurface: hexFromArgb(dynamic.inverseSurface),
-    inverseOnSurface: hexFromArgb(dynamic.inverseOnSurface),
+    background: dark ? neutral(6) : neutral(97),
+    onBackground: dark ? neutral(90) : neutral(10),
+    surface: dark ? neutral(6) : neutral(97),
+    onSurface: dark ? neutral(90) : neutral(10),
+    surfaceVariant: dark ? variant(30) : variant(90),
+    onSurfaceVariant: dark ? variant(80) : variant(30),
+    surfaceDim: dark ? neutral(6) : neutral(88),
+    surfaceBright: dark ? neutral(24) : neutral(98),
+    surfaceContainerLowest: dark ? neutral(4) : neutral(100),
+    surfaceContainerLow: dark ? neutral(10) : neutral(96),
+    surfaceContainer: dark ? neutral(12) : neutral(94),
+    surfaceContainerHigh: dark ? neutral(17) : neutral(92),
+    surfaceContainerHighest: dark ? neutral(22) : neutral(90),
+    outline: dark ? variant(60) : variant(50),
+    outlineVariant: dark ? variant(30) : variant(80),
+    inverseSurface: dark ? neutral(90) : neutral(20),
+    inverseOnSurface: dark ? neutral(20) : neutral(95),
     inversePrimary: hexFromArgb(dynamic.inversePrimary),
     scrim: hexFromArgb(dynamic.scrim),
     shadow: hexFromArgb(dynamic.shadow)
@@ -5970,13 +6002,12 @@ function apply(ctx, config) {
     }));
     const text = `棋盘：轮到${convertTurnToString(game.turn)}。坐标 a–i 自左向右，0–9 自红方底线向黑方。
 ${pieces.join("；")}`;
-    const description = (0, import_koishi2.h)("p", {}, import_koishi2.h.text(text)).toString();
-    if (config.disableImages) return description;
+    if (config.disableImages) return text;
     try {
-      return import_koishi2.h.image(await drawChessBoard(channelId), imageMimeType).toString() + description;
+      return import_koishi2.h.image(await drawChessBoard(channelId), imageMimeType).toString() + imageText(import_koishi2.h.text(text)).toString();
     } catch (error) {
       logger.warn("棋盘图片生成失败：%s", error.message);
-      return description;
+      return text;
     }
   }
   __name(renderBoard, "renderBoard");
@@ -7261,7 +7292,7 @@ ${pieces.join("；")}`;
   const sentMessages = {};
   async function sendMessage(session, message) {
     const { bot, channelId } = session;
-    const [messageId] = await session.send(presentation.textOnly(session) ? withoutImages(message) : message);
+    const [messageId] = await session.send(choosePresentation(message, presentation.textOnly(session)));
     if (presentation.textOnly(session) || config.retractDelay === 0 || !messageId) return;
     const previousMessageId = sentMessages[channelId];
     sentMessages[channelId] = messageId;

package/lib/ux.d.ts

@@ -3,9 +3,10 @@ type Owner = {
     name: string;
     matches: (session: Session) => boolean | Promise<boolean>;
 };
-/** Default output is an image plus its usable text equivalent. Preferences affect this user only. */
+/** 图文模式默认只发渲染图；完整文字只在用户切到「文字」模式时出现。偏好只影响本人。 */
 export declare function usePresentation(ctx: Context, command: string): {
     textOnly: (session: Session) => boolean;
+    /** 图文模式只给图片；图片缺失或用户选了文字模式时才退回文字。 */
     present(session: Session, image: h.Fragment | null | undefined, text: h.Fragment): h.Fragment;
 };
 /** Plugins register their active input grammar; overlapping messages are never executed. */
@@ -14,7 +15,17 @@ export declare function directInputConflict(ctx: Context, session: Session): Pro
 /** No hidden time limit: users can extend the non-game input step without losing context. */
 export declare function promptInput(session: Session, instruction: string): Promise<string | undefined>;
 export declare const IMAGE_FAILURE = "\u56FE\u7247\u6682\u65F6\u65E0\u6CD5\u751F\u6210\uFF0C\u5DF2\u4FDD\u7559\u6587\u5B57\u5185\u5BB9\u3002\u53EF\u4EE5\u7A0D\u540E\u91CD\u8BD5\uFF1B\u82E5\u6301\u7EED\u5931\u8D25\uFF0C\u8BF7\u8054\u7CFB\u7BA1\u7406\u5458\u3002";
-/** Preserve companion text when image messages are switched to text mode. */
+/**
+ * 渲染图的等价文字。图文模式随图片一起丢掉、文字模式展开成正文，
+ * 因此它永远不会原样发到聊天平台。
+ */
+export declare const IMAGE_TEXT_TYPE = "ux-image-text";
+export declare function imageText(text: h.Fragment): h;
+/** 图文模式：保留图片与普通文字，去掉图片的等价文字。 */
+export declare function imagesOnly(content: h.Fragment): h[];
+/** 文字模式：去掉图片，把等价文字展开成普通文本。 */
 export declare function withoutImages(content: h.Fragment): h[];
+/** 发送前的统一选择：文字模式去掉图片，图文模式去掉等价文字。 */
+export declare function choosePresentation(content: h.Fragment, textOnly: boolean): h[];
 export declare function isTextOnly(ctx: Context, session: Session): boolean;
 export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "koishi-plugin-cchess",
   "description": "Koishi 中国象棋：支持玩家对战、皮卡鱼引擎和 FEN 局面导入。",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
   "files": [