koishi-plugin-bns-rate 1.2.2 → 1.2.4

package/README.md

@@ -2,7 +2,7 @@
 
 从 [dd373.com](https://www.dd373.com/s-d5gqt8.html) 获取剑灵怀旧服**神石**实时汇率，输出当前时段最低比例前 N 条。
 
-支持**官方 QQ 机器人 Markdown 卡片**回复：标题 + 横幅图 + 红绿报价 + 跳转按钮，全部可在插件设置页配置。
+支持**官方 QQ 机器人 Markdown 卡片**回复：标题 + 横幅图 + 灰框报价 + 跳转按钮，全部可在插件设置页配置。
 
 ## 命令
 
@@ -10,6 +10,7 @@
 | --- | --- |
 | `bnsrate` / `神石` / `shenshi` | 查询当前时段最低神石比例 |
 | `bnsrate -f` | 忽略缓存，强制刷新 |
+| `bnsrate.box` | **报价区排版对照**：一条消息里给出 code / quote / list / none 四种样式，在手机上挑一个填进 `ratesBox` |
 | `bnsrate.preview` | 只输出卡片 Markdown 源码（不发送卡片），调试用 |
 
 ## 卡片效果
@@ -33,11 +34,20 @@
 [ 点此直达DD373网站 ]
 ````
 
-报价列表默认用**代码块**包起来，在客户端渲染成**灰色框**（`ratesBox: code`）。代码块是等宽字体，插件会用空格把两列**对齐**（数字位数不同也对齐）。
+报价区默认用**代码块**包起来，在客户端渲染成**灰色框**（`ratesBox: code`）。代码块是等宽字体，插件会用空格把两列**对齐**（数字位数不同也对齐）。
 
-> ⚠️ 手机端（安卓 / iOS）**不渲染 HTML 标签**：`<font color="#E60012">` 会**原样显示成一串字符**。因此默认的 `code` 模式**不输出任何颜色标签**；只有把 `ratesBox` 改成 `quote` / `none` 时才会输出颜色（桌面端有颜色，手机端会露出标签，自行取舍）。
+### 报价区排版可选四种（`ratesBox`）
 
-若手机上把 ` ``` ` 显示成了原文（不支持代码块），把 `ratesBox` 改成 `quote`，即可换成引用样式的外框。
+| 值 | 效果 | QQ 官方文档支持 | 颜色 |
+| --- | --- | --- | --- |
+| **`code`（默认）** | 代码块 → 均匀灰底圆角框、等宽字体、两列对齐 | ❌ 不在[支持清单](https://bot.qq.com/wiki/develop/api-v2/server-inter/message/type/markdown.html)（客户端能力，安卓新版本 / iOS 才有） | ❌ 代码块内不支持 |
+| `quote` | 块引用 → 灰底 + 左侧竖条 | ✅ 明确支持 | ✅ 桌面端 |
+| `list` | 无序列表 → 无底色，缩进 + 圆点 | ✅ 明确支持 | ✅ 桌面端 |
+| `none` | 不包裹，纯文本行 | — | ✅ 桌面端 |
+
+拿不准就在群里发 **`bnsrate.box`**：它会发一条含四种样式的对照卡片，挑一个填进设置页即可。若手机上 ` ``` ` 显示成了原文，说明该客户端不支持代码块，换成 `quote`。
+
+> ⚠️ 手机端（安卓 / iOS）**不渲染 HTML 标签**：`<font color="#E60012">` 会**原样显示成一串字符**。因此默认的 `code` 模式**不输出任何颜色标签**；`quote` / `list` / `none` 会输出颜色（桌面端有颜色，手机端会露出标签，自行取舍）。
 
 其它平台（OneBot / Telegram 等）、QQ 频道（`qqguild`）、以及卡片发送失败时，都会**自动回退为纯文本**，不会发不出消息。
 
@@ -80,8 +90,8 @@
 | `button` | `true` | 是否显示底部跳转按钮 |
 | `buttonText` | `点此直达DD373网站` | 按钮文字 |
 | `buttonUrl` | `https://www.dd373.com/s-d5gqt8.html` | 按钮跳转链接 |
-| `ratesBox` | `code` | 报价列表外框：`code` 代码块（灰色框、等宽、两列对齐、**无颜色**）／`quote` 引用（灰底+左侧竖条，桌面端可上色）／`none` 不加框 |
-| `colorForward` | `#E60012` | 「1元=xx神石」数字颜色，留空不染色。**仅在 `ratesBox != code` 时生效** |
+| `ratesBox` | `code` | 报价区排版：`code` 代码块（灰框／等宽／对齐／无颜色）／`quote` 块引用／`list` 列表／`none` 不包裹。发 `bnsrate.box` 可看四种对照 |
+| `colorForward` | `#E60012` | 「1元=xx神石」数字颜色，留空不染色。**仅 `ratesBox` 不是 `code` 时才生效** |
 | `colorReverse` | `#00A650` | 「1神石=xx元」数字颜色，留空不染色。同上 |
 | `decimalsForward` | `2` | 「1元=xx神石」保留小数位（**截断**，不四舍五入），`0` = 原始值 |
 | `decimalsReverse` | `4` | 「1神石=xx元」保留小数位（截断），`0` = 原始值 |

package/index.js

@@ -28,7 +28,7 @@ const Config = Schema.object({
     .description('💬 用 QQ官方 Markdown 卡片回复（仅官方QQ机器人「群/私聊」生效；频道机器人、OneBot 等其它平台自动回退纯文本，发送失败也会回退）'),
   title: Schema.string()
     .default('神石比例实时播报')
-    .description('卡片顶部标题（# 一级标题）'),
+    .description('卡片顶部标题（# 一级标题）。留空则不输出标题——若横幅图上已经有标题文字，把这里清空即可'),
 
   bannerUrl: Schema.string()
     .default('')
@@ -68,13 +68,13 @@ const Config = Schema.object({
 
   colorForward: Schema.string()
     .default('#E60012')
-    .description('「1元=xx神石」数字的颜色，如 #E60012（红）。留空 = 不染色。⚠️ ① 颜色只在桌面端 QQ 渲染；② 安卓/iOS 会把 <font> 标签当纯文本显示出来，所以仅在 ratesBox != code 时才有意义；③ 代码块内不支持颜色'),
+    .description('「1元=xx神石」数字颜色，如 #E60012，留空即不染色。⚠️ 仅当 ratesBox 不是 code 时才有意义；手机端不渲染颜色，会把这串标签当文字显示出来'),
   colorReverse: Schema.string()
     .default('#00A650')
-    .description('「1神石=xx元」数字的颜色，如 #00A650（绿）。留空 = 不染色'),
-  ratesBox: Schema.union(['code', 'quote', 'none'])
+    .description('「1神石=xx元」数字颜色，如 #00A650，留空即不染色。同上'),
+  ratesBox: Schema.union(['code', 'quote', 'list', 'none'])
     .default('code')
-    .description('📦 报价列表的外框样式：code = 代码块（灰色框，等宽字体，行列对齐，不支持颜色）；quote = 引用（灰底 + 左侧竖条，桌面端可显示颜色）；none = 不加框。</br>若手机上把 ``` 显示成了原文，改成 quote 即可'),
+    .description('📦 报价区排版：code = 代码块（灰色框、等宽、两列对齐，但不支持颜色，且代码块不在 QQ 官方支持清单里）；quote = 块引用（官方支持，灰底+左侧竖条，桌面端有颜色）；list = 无序列表（官方支持，无底色）；none = 不包裹。</br>拿不准就在群里发 bnsrate.box 看对照图，挑一个填这里'),
   decimalsForward: Schema.number()
     .default(2)
     .min(0)
@@ -176,15 +176,20 @@ function formatText(rates, timestamp, opts = {}) {
 }
 
 // QQ官方 Markdown 卡片源码
+// 按"块"拼装、块之间用空行分隔：任何一块留空/关闭就整块不输出，
+// 这样不会出现空标题（`# `）、也不会在开头/结尾留下多余空行
 function buildCardMarkdown(rates, timestamp, config) {
   const time = formatTime(timestamp, false)
-  const lines = [`# ${config.title}`]
+  const blocks = []
+
+  const title = String(config.title || '').trim()
+  if (title) blocks.push(`# ${title}`)
 
   const banner = String(config.bannerUrl || '').trim()
   if (banner) {
     const w = Math.max(0, Math.round(Number(config.bannerWidth) || 0))
     const ht = Math.max(0, Math.round(Number(config.bannerHeight) || 0))
-    lines.push('', `![${config.bannerAlt} #${w}px #${ht}px](${banner})`)
+    blocks.push(`![${String(config.bannerAlt || '').trim()} #${w}px #${ht}px](${banner})`)
   }
 
   const intro = fillTemplate(config.intro, {
@@ -192,34 +197,42 @@ function buildCardMarkdown(rates, timestamp, config) {
     time,
     date: time.split(' ')[0],
   }).trim()
-  if (intro) lines.push('', intro)
+  if (intro) blocks.push(intro)
+
+  blocks.push(buildRateBlock(rates, config).join('\n'))
+
+  const footer = String(config.footer || '').trim()
+  if (config.button && footer) blocks.push(footer)
 
-  // 报价列表
-  const box = String(config.ratesBox || 'code')
+  return blocks.join('\n\n').trim()
+}
+
+// 报价区排版。box 省略时取 config.ratesBox
+// code  = 代码块（灰色框 / 等宽 / 两列对齐，代码块内不支持颜色）
+// quote = 块引用（官方支持，灰底 + 左侧竖条，桌面端可上色）
+// list  = 无序列表（官方支持，无底色，缩进 + 圆点）
+// none  = 不加任何包裹
+function buildRateBlock(rates, config, box) {
+  const mode = box || String(config.ratesBox || 'code')
   const rows = rates.map(r => ({
     fwd: truncate(r.forward, config.decimalsForward),
     rev: truncate(r.reverse, config.decimalsReverse),
   }))
 
-  if (box === 'code') {
-    // 代码块 = 灰色框（等宽字体，正好可以用空格把两列对齐）
-    // ⚠️ 代码块内部不支持颜色，塞 <font> 标签只会被原样显示，所以这里不加颜色
+  if (mode === 'code') {
     const wf = Math.max(...rows.map(r => r.fwd.length))
     const wr = Math.max(...rows.map(r => r.rev.length))
     const body = rows.map(r => `1元 = ${r.fwd.padEnd(wf)} 神石  |  1神石 = ${r.rev.padEnd(wr)}元`)
-    lines.push('', '```', ...body, '```')
-  } else {
-    const body = rows.map(r => (
-      `1元 = ${colorize(r.fwd, config.colorForward)}神石　|　`
-      + `1神石 = ${colorize(r.rev, config.colorReverse)}元`
-    ))
-    lines.push('', ...(box === 'quote' ? body.map(l => '> ' + l) : body))
+    return ['```', ...body, '```']
   }
 
-  const footer = String(config.footer || '').trim()
-  if (config.button && footer) lines.push('', footer)
-
-  return lines.join('\n')
+  const body = rows.map(r => (
+    `1元 = ${colorize(r.fwd, config.colorForward)}神石　|　`
+    + `1神石 = ${colorize(r.rev, config.colorReverse)}元`
+  ))
+  if (mode === 'quote') return body.map(l => '> ' + l)
+  if (mode === 'list') return body.map(l => '- ' + l)
+  return body
 }
 
 // —— QQ 官方 internal API 发送（单条 payload 内同时带 markdown 与 keyboard，避免被拆成两条消息）——
@@ -354,6 +367,27 @@ function apply(ctx, config) {
     }
   }
 
+  // 发卡片：带按钮 → 不带按钮（按钮能力/权限不可用时仍出卡片）→ 返回 false 让调用方回退纯文本
+  async function sendCard(session, markdown, cfg) {
+    const plain = toPlainText(markdown, cfg.button ? cfg.buttonUrl : '')
+    const passive = passiveMeta(session)
+    const hasButtons = !!(cfg.button && String(cfg.buttonUrl || '').trim())
+    for (const withButtons of (hasButtons ? [true, false] : [false])) {
+      try {
+        await sendQqCard(session, buildCardPayload(markdown, plain, cfg, passive, withButtons))
+        logger.debug(`已发送 Markdown 卡片到 ${session.channelId}${withButtons ? '（含按钮）' : '（无按钮）'}`)
+        return true
+      } catch (e) {
+        const code = errCode(e)
+        const detail = code !== undefined ? `code=${code}` : ((e && e.message) || e)
+        const level = isKnownIgnoreError(e) ? 'debug' : 'warn'
+        logger[level](`Markdown 卡片发送失败（${withButtons ? '含按钮' : '无按钮'}）: ${detail}`)
+      }
+    }
+    logger.warn('Markdown 卡片全部尝试失败，回退纯文本')
+    return false
+  }
+
   ctx.command('bnsrate', '查询剑灵怀旧服神石汇率')
     .alias('神石')
     .alias('shenshi')
@@ -370,23 +404,7 @@ function apply(ctx, config) {
       // 官方QQ机器人的群聊/私聊：发 Markdown 卡片（markdown + 按钮在同一条消息里）
       if (config.markdown && session && supportsCard(session)) {
         const markdown = buildCardMarkdown(data.rates, data.timestamp, config)
-        const plain = toPlainText(markdown, config.button ? config.buttonUrl : '')
-        const passive = passiveMeta(session)
-        const hasButtons = !!(config.button && String(config.buttonUrl || '').trim())
-        // 依次尝试：带按钮 → 不带按钮（按钮能力/权限不可用时仍出卡片），都失败才回退纯文本
-        for (const withButtons of (hasButtons ? [true, false] : [false])) {
-          try {
-            await sendQqCard(session, buildCardPayload(markdown, plain, config, passive, withButtons))
-            logger.debug(`已发送 Markdown 卡片到 ${session.channelId}${withButtons ? '（含按钮）' : '（无按钮）'}`)
-            return
-          } catch (e) {
-            const code = errCode(e)
-            const detail = code !== undefined ? `code=${code}` : ((e && e.message) || e)
-            const level = isKnownIgnoreError(e) ? 'debug' : 'warn'
-            logger[level](`Markdown 卡片发送失败（${withButtons ? '含按钮' : '无按钮'}）: ${detail}`)
-          }
-        }
-        logger.warn('Markdown 卡片全部尝试失败，回退纯文本')
+        if (await sendCard(session, markdown, config)) return
       }
 
       return formatText(data.rates, data.timestamp, { stale: data.stale, error: data.error })
@@ -403,6 +421,40 @@ function apply(ctx, config) {
         return '获取汇率失败: ' + message
       }
     })
+
+  // 排版对照：一条消息里同时给出 4 种报价区排版，在手机上挑一个填进 ratesBox
+  ctx.command('bnsrate.box', '报价区排版对照：一条消息看 4 种样式，挑一个填到 ratesBox')
+    .action(async ({ session }) => {
+      let data
+      try {
+        data = await resolveRates(false)
+      } catch (e) {
+        const message = e instanceof Error ? e.message : String(e)
+        return '获取汇率失败: ' + message
+      }
+      const sample = data.rates.slice(0, 2)
+      const parts = [
+        '# 报价区排版对照',
+        '',
+        '把下面最好看的那一项填到插件设置页的 ratesBox：',
+      ]
+      const labels = {
+        code: 'A. code —— 代码块（灰色框 / 等宽 / 两列对齐 / 无颜色）',
+        quote: 'B. quote —— 块引用（灰底 + 左侧竖条 / 桌面端有颜色）',
+        list: 'C. list —— 无序列表（无底色 / 缩进 + 圆点）',
+        none: 'D. none —— 不包裹（纯文本行）',
+      }
+      for (const box of ['code', 'quote', 'list', 'none']) {
+        parts.push('', `## ${labels[box]}`, '', ...buildRateBlock(sample, config, box))
+      }
+
+      const markdown = parts.join('\n')
+      // 对照图不需要按钮，避免误触
+      if (session && supportsCard(session)) {
+        if (await sendCard(session, markdown, { ...config, button: false })) return
+      }
+      return markdown
+    })
 }
 
 module.exports = {
@@ -413,6 +465,7 @@ module.exports = {
     formatText,
     buildCardMarkdown,
     buildCardPayload,
+    buildRateBlock,
     buildKeyboard,
     toPlainText,
     passiveMeta,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koishi-plugin-bns-rate",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "Fetch BNS Classic Divine Stone exchange rate from dd373.com, with QQ official Markdown card support",
   "main": "index.js",
   "files": [
@@ -17,8 +17,8 @@
   },
   "koishi": {
     "description": {
-      "zh": "从 dd373.com 获取剑灵怀旧服神石实时汇率，输入 神石/bnsrate/shenshi 即可查询最低比例。支持官方QQ机器人 Markdown 卡片（标题+横幅图+红绿报价+跳转按钮），横幅图片与配色均可在插件设置页配置。",
-      "en": "Fetch BNS Classic Divine Stone exchange rate from dd373.com. Supports QQ official bot Markdown cards (title, banner image, colored rates, jump button), all configurable."
+      "zh": "从 dd373.com 获取剑灵怀旧服神石实时汇率，输入 神石/bnsrate/shenshi 即可查询最低比例。支持官方QQ机器人 Markdown 卡片：标题 + 横幅图 + 代码块灰框报价（等宽对齐）+ 跳转按钮，正文与按钮同一条消息；横幅图片、外框样式、配色、小数位均可在插件设置页配置。",
+      "en": "Fetch BNS Classic Divine Stone exchange rate from dd373.com. QQ official bot Markdown card: title, banner image, gray code-box rate table, jump button — all in a single message and fully configurable."
     },
     "service": {
       "required": ["http"]