koishi-plugin-wordle-game 4.3.0 → 4.4.0

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+# 4.4.0 · 2026-10-02
+
+修复未启用 help 插件时发送 `wordle` 会让指令无限调用自己、Koishi 收不到任何消息的问题。主指令现在自带帮助：按常用顺序列出各子指令并提示如何开局，不再依赖 help 插件；带 `-h` 时仍由 help 插件接手。发送 `wordle` 不再顺带登记玩家名（首次游玩时照常登记）。
+
 # 4.3.0 · 2026-09-26
 
 无前缀猜测只接手确定有效的猜测（在词库中、未猜过），其余静默放行；汉兜提示色改为清晰的绿 / 琥珀，下划线对齐拼音；模式清单上下留白对称。 主指令在 help 列表里补回描述；去掉「.显示」显示模式指令，有图只发图、出图失败才退回文字；多轮输入不再追加计时说明。

package/README.md

@@ -1,19 +1,25 @@
 # 猜单词
 
-Koishi 猜词插件，包含多种词库和游戏模式。
+Koishi 插件：猜词游戏，支持单词、成语、数字与方程式等多种模式
+
+[![GitHub](https://img.shields.io/badge/GitHub-araea%2Fkoishi--plugin--wordle--game-181717?logo=github&logoColor=white)](https://github.com/araea/koishi-plugin-wordle-game)
+[![npm](https://img.shields.io/npm/v/koishi-plugin-wordle-game?logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/koishi-plugin-wordle-game)
 
 ## 安装
 
 ```sh
-yarn add koishi-plugin-wordle-game
+npm i koishi-plugin-wordle-game
 ```
 
-在 Koishi 中启用，并安装 `database` 与 `puppeteer` 服务。
+启用插件，并安装 `database` 与 `puppeteer` 服务。
+
+## 快速使用
 
-## 指令
+发送 `wordle.开始` 选择模式开局，之后直接发送猜测词即可续猜（默认开启 `enableDirectInput`）。
 
 | 指令 | 说明 |
 | --- | --- |
+| `wordle` | 查看指令列表 |
 | `wordle.开始 [长度]` | 开始模式选择 |
 | `wordle.开始.<模式> [长度]` | 指定模式开局 |
 | `wordle.猜 <内容>` | 提交猜测 |
@@ -26,14 +32,35 @@ yarn add koishi-plugin-wordle-game
 | `wordle.拼音速查表` | 查看拼音速查表 |
 | `wordle.玩法介绍` | 查看玩法 |
 
-模式包括经典、汉兜、词影、Numberle、Math 和 Lewdle 等。部分模式支持 `--hard`、`--uhard`、`--absurd`、`--challenge`、`--wordles`、`--free` 和 `--all` 选项。
+模式包括经典、汉兜、词影、Numberle、Math 与 Lewdle 等。部分模式支持 `--hard`、`--uhard`、`--absurd`、`--challenge`、`--wordles`、`--free` 和 `--all` 选项。
+
+## 配置
+
+| 配置项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `isDarkThemeEnabled` | boolean | `false` | 使用黑暗主题 |
+| `isHighContrastThemeEnabled` | boolean | `false` | 使用高对比度主题，为色觉障碍准备 |
+| `compositeImagePageWidth` | number | `800` | 多词合成图的页面宽度（像素） |
+| `compositeImagePageHeight` | number | `100` | 多词合成图的页面高度（像素） |
+| `maxSimultaneousGuesses` | number | `4` | 同时猜测的单词数量上限 |
+| `defaultMaxLeaderboardEntries` | number | `10` | 排行榜默认显示的人数 |
+| `defaultWordLengthForGuessing` | number | `5` | 非经典模式下默认的猜测长度 |
+| `enableDirectInput` | boolean | `true` | 对局中直接发送猜测词即可续猜 |
+| `isPreventUserDuplicateGuessInput` | boolean | `true` | 拦截重复提交的猜测词 |
+| `shouldPromptWordLengthInput` | boolean | `true` | 引导式开局时追问一次单词长度 |
+| `shouldPromptForWordLengthOnNonClassicStart` | boolean | `true` | 非经典模式开局时追问一次单词长度 |
+| `enableWordGuessTimeLimit` | boolean | `false` | 给每次作答加上时间限制 |
+| `wordGuessTimeLimitInSeconds` | number | `120` | 每次作答的时间限制（秒） |
+| `retractDelay` | number | `0` | 自动撤回延迟（秒），0 表示不撤回 |
+| `imageType` | `png` / `jpeg` / `webp` | `png` | 发送的图片格式 |
 
-## 许可证
+## 限制 / 风险
 
-可按 [Apache-2.0](LICENSE-APACHE) 或 [MIT](LICENSE-MIT) 使用。
+需要 `database` 服务保存战绩，以及 `puppeteer` 服务渲染图片。
 
-## 显示与交互
+`wordle.查成语` 依赖外部汉典数据，拼音查询依赖配置的拼音 API。
 
-有渲染图时只发图片，不再附带同内容的文字；图片生成失败时才退回文字。作品素材与感官测试的适用边界见 [设计系统](./DESIGN_SYSTEM.md)。
+## 必要链接
 
-本次更新：无前缀猜测只接手确定有效的猜测（在词库中、未猜过），其余静默放行；汉兜提示色改为清晰的绿 / 琥珀，下划线对齐拼音；模式清单上下留白对称。 主指令在 help 列表里补回描述；去掉「.显示」显示模式指令，有图只发图、出图失败才退回文字；多轮输入不再追加计时说明。
+- [设计系统](DESIGN_SYSTEM.md)
+- [MIT](LICENSE-MIT) / [Apache-2.0](LICENSE-APACHE)

package/lib/config.d.ts

@@ -1,5 +1,5 @@
 import { Schema } from "koishi";
-export declare const usage = "## \u4F7F\u7528\n\n\u53D1\u9001 `wordle.\u5F00\u59CB` \u5F00\u5C40\uFF0C\u4E4B\u540E\u76F4\u63A5\u53D1\u9001\u731C\u6D4B\u8BCD\u5373\u53EF\u3002\n\n## \u6307\u4EE4\n\n| \u6307\u4EE4 | \u8BF4\u660E |\n| --- | --- |\n| `wordle.\u5F00\u59CB [\u957F\u5EA6]` | \u5F15\u5BFC\u5F0F\u5F00\u5C40 |\n| `wordle.\u5F00\u59CB.<\u6A21\u5F0F> [\u957F\u5EA6]` | \u6307\u5B9A\u6A21\u5F0F\u5F00\u5C40 |\n| `wordle.\u731C <\u5185\u5BB9>` | \u63D0\u4EA4\u731C\u6D4B |\n| `wordle.\u67E5\u8BE2\u8FDB\u5EA6` | \u67E5\u770B\u5F53\u524D\u5BF9\u5C40\u8FDB\u5EA6 |\n| `wordle.\u7ED3\u675F` | \u7ED3\u675F\u5F53\u524D\u5BF9\u5C40 |\n| `wordle.\u6392\u884C\u699C [\u4EBA\u6570]` | \u67E5\u770B\u6392\u884C\u699C |\n| `wordle.\u6218\u7EE9 [@\u67D0\u4EBA]` | \u67E5\u8BE2\u73A9\u5BB6\u6218\u7EE9 |\n| `wordle.\u67E5\u5355\u8BCD <\u8BCD>` | \u5F15\u5BFC\u5F0F\u67E5\u5355\u8BCD |\n| `wordle.\u67E5\u6210\u8BED <\u6210\u8BED>` | \u67E5\u8BE2\u6210\u8BED\u7684\u62FC\u97F3\u4E0E\u89E3\u91CA\uFF08\u6C49\u5178\uFF09 |\n| `wordle.\u62FC\u97F3\u901F\u67E5\u8868` | \u67E5\u770B\u62FC\u97F3\u901F\u67E5\u8868 |\n| `wordle.\u73A9\u6CD5\u4ECB\u7ECD` | \u67E5\u770B\u73A9\u6CD5\u4ECB\u7ECD |\n\n\u6A21\u5F0F\u5305\u62EC\u7ECF\u5178\u3001\u6C49\u515C\u3001\u8BCD\u5F71\u3001Numberle\u3001Math\u3001Lewdle \u53CA\u5176\u4ED6\u8BCD\u5E93\u3002\n\n\u53EF\u7528\u9009\u9879\uFF1A`--hard`\u3001`--uhard`\u3001`--absurd`\u3001`--challenge`\u3001`--wordles`\u3001`--free`\u3001`--all`\u3002";
+export declare const usage = "## \u4F7F\u7528\n\n\u53D1\u9001 `wordle.\u5F00\u59CB` \u5F00\u5C40\uFF0C\u4E4B\u540E\u76F4\u63A5\u53D1\u9001\u731C\u6D4B\u8BCD\u5373\u53EF\u3002\n\n## \u6307\u4EE4\n\n| \u6307\u4EE4 | \u8BF4\u660E |\n| --- | --- |\n| `wordle` | \u67E5\u770B\u6307\u4EE4\u5217\u8868 |\n| `wordle.\u5F00\u59CB [\u957F\u5EA6]` | \u5F00\u59CB\u6A21\u5F0F\u9009\u62E9 |\n| `wordle.\u5F00\u59CB.<\u6A21\u5F0F> [\u957F\u5EA6]` | \u6307\u5B9A\u6A21\u5F0F\u5F00\u5C40 |\n| `wordle.\u731C <\u5185\u5BB9>` | \u63D0\u4EA4\u731C\u6D4B |\n| `wordle.\u67E5\u8BE2\u8FDB\u5EA6` | \u67E5\u770B\u5F53\u524D\u8FDB\u5EA6 |\n| `wordle.\u7ED3\u675F` | \u7ED3\u675F\u6E38\u620F |\n| `wordle.\u6392\u884C\u699C [\u4EBA\u6570]` | \u67E5\u770B\u6392\u884C\u699C |\n| `wordle.\u6218\u7EE9 [@\u67D0\u4EBA]` | \u67E5\u8BE2\u73A9\u5BB6\u8BB0\u5F55 |\n| `wordle.\u67E5\u5355\u8BCD <\u8BCD>` | \u67E5\u8BE2\u5355\u8BCD\u5E76\u5F00\u59CB\u5F15\u5BFC |\n| `wordle.\u67E5\u6210\u8BED <\u6210\u8BED>` | \u67E5\u8BE2\u62FC\u97F3\u548C\u91CA\u4E49\uFF08\u6C49\u5178\uFF09 |\n| `wordle.\u62FC\u97F3\u901F\u67E5\u8868` | \u67E5\u770B\u62FC\u97F3\u901F\u67E5\u8868 |\n| `wordle.\u73A9\u6CD5\u4ECB\u7ECD` | \u67E5\u770B\u73A9\u6CD5 |\n\n\u6A21\u5F0F\u5305\u62EC\u7ECF\u5178\u3001\u6C49\u515C\u3001\u8BCD\u5F71\u3001Numberle\u3001Math \u548C Lewdle \u7B49\u3002\u90E8\u5206\u6A21\u5F0F\u652F\u6301 `--hard`\u3001`--uhard`\u3001`--absurd`\u3001`--challenge`\u3001`--wordles`\u3001`--free` \u548C `--all` \u9009\u9879\u3002";
 export interface Config {
     isDarkThemeEnabled: boolean;
     isHighContrastThemeEnabled: boolean;

package/lib/help.d.ts

@@ -0,0 +1,14 @@
+import { Session } from 'koishi';
+export interface HelpEntry {
+    name: string;
+    description: string;
+}
+/**
+ * 主指令帮助的内容：从已注册的指令树现取标题与直接子指令，不依赖 help 插件，也不会和指令脱节。
+ * `order` 列出希望靠前的子指令（完整指令名），没列到的按注册顺序排在后面；排版交给各插件。
+ * 不要在动作里 `session.execute('… -h')` 转发：`-h` 由 help 插件提供，缺它指令会无限调用自己。
+ */
+export declare function helpOf(session: Session, name: string, order?: string[]): {
+    title: string;
+    entries: HelpEntry[];
+};

package/lib/index.js

@@ -50,21 +50,20 @@ var usage = `## 使用
 
 | 指令 | 说明 |
 | --- | --- |
-| \`wordle.开始 [长度]\` | 引导式开局 |
+| \`wordle\` | 查看指令列表 |
+| \`wordle.开始 [长度]\` | 开始模式选择 |
 | \`wordle.开始.<模式> [长度]\` | 指定模式开局 |
 | \`wordle.猜 <内容>\` | 提交猜测 |
-| \`wordle.查询进度\` | 查看当前对局进度 |
-| \`wordle.结束\` | 结束当前对局 |
+| \`wordle.查询进度\` | 查看当前进度 |
+| \`wordle.结束\` | 结束游戏 |
 | \`wordle.排行榜 [人数]\` | 查看排行榜 |
-| \`wordle.战绩 [@某人]\` | 查询玩家战绩 |
-| \`wordle.查单词 <词>\` | 引导式查单词 |
-| \`wordle.查成语 <成语>\` | 查询成语的拼音与解释（汉典） |
+| \`wordle.战绩 [@某人]\` | 查询玩家记录 |
+| \`wordle.查单词 <词>\` | 查询单词并开始引导 |
+| \`wordle.查成语 <成语>\` | 查询拼音和释义（汉典） |
 | \`wordle.拼音速查表\` | 查看拼音速查表 |
-| \`wordle.玩法介绍\` | 查看玩法介绍 |
+| \`wordle.玩法介绍\` | 查看玩法 |
 
-模式包括经典、汉兜、词影、Numberle、Math、Lewdle 及其他词库。
-
-可用选项：\`--hard\`、\`--uhard\`、\`--absurd\`、\`--challenge\`、\`--wordles\`、\`--free\`、\`--all\`。`;
+模式包括经典、汉兜、词影、Numberle、Math 和 Lewdle 等。部分模式支持 \`--hard\`、\`--uhard\`、\`--absurd\`、\`--challenge\`、\`--wordles\`、\`--free\` 和 \`--all\` 选项。`;
 var Config = import_koishi.Schema.intersect([
   import_koishi.Schema.object({
     isDarkThemeEnabled: import_koishi.Schema.boolean().default(false).description(`使用黑暗主题。`),
@@ -339,6 +338,24 @@ async function updateDataInTargetFile(logger, newFilePath, targetFilePath, missi
 }
 __name(updateDataInTargetFile, "updateDataInTargetFile");
 
+// src/help.ts
+function helpOf(session, name2, order = []) {
+  const describe = /* @__PURE__ */ __name((command) => session.text([`commands.${command}.description`, ""]), "describe");
+  const rank = /* @__PURE__ */ __name((command) => {
+    const i = order.indexOf(command);
+    return i < 0 ? order.length : i;
+  }, "rank");
+  const entries = [];
+  for (const child of session.app.$commander.get(name2)?.children ?? []) {
+    const { hidden } = child.config;
+    if (!child.match(session) || session.resolve(hidden)) continue;
+    entries.push({ name: child.name, description: describe(child.name) });
+  }
+  entries.sort((a, b) => rank(a.name) - rank(b.name));
+  return { title: describe(name2), entries };
+}
+__name(helpOf, "helpOf");
+
 // src/utils/string.ts
 function removeDuplicates(inputString) {
   let result = "";
@@ -693,10 +710,22 @@ __name(getSessionUserName, "getSessionUserName");
 function register(g) {
   const { ctx, config } = g;
   ctx.command("wordle", "猜单词 · 多词库多模式").alias("wordleGame").action(async ({ session }) => {
-    let { userId, username } = session;
-    username = await getSessionUserName(g, session);
-    await updateNameInPlayerRecord(g, session, userId, username);
-    await session.execute(`wordle -h`);
+    const { title, entries } = helpOf(
+      session,
+      "wordle",
+      ["开始", "猜", "查询进度", "结束", "排行榜", "战绩", "查单词", "查成语", "拼音速查表", "玩法介绍"].map(
+        (name2) => `wordle.${name2}`
+      )
+    );
+    return await sendMessage(
+      g,
+      session,
+      [
+        title,
+        ...entries.map(({ name: name2, description }) => `　${name2}　${description}`),
+        "发送「wordle.开始」开局，之后直接发送猜测词即可。"
+      ].join("\n")
+    );
   });
   ctx.command("wordle.玩法介绍", "查看玩法介绍").action(async ({ session }) => {
     let { userId, username } = session;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "koishi-plugin-wordle-game",
-  "description": "Koishi 多词库猜词游戏，包含经典、汉兜、Numberle 等模式。",
-  "version": "4.3.0",
+  "description": "Koishi 插件：猜词游戏，支持单词、成语、数字与方程式等多种模式。",
+  "version": "4.4.0",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
   "files": [