koishi-plugin-bns-rate 1.1.0 → 1.2.0

package/README.md

@@ -0,0 +1,71 @@
+# koishi-plugin-bns-rate
+
+从 [dd373.com](https://www.dd373.com/s-d5gqt8.html) 获取剑灵怀旧服**神石**实时汇率，输出当前时段最低比例前 N 条。
+
+支持**官方 QQ 机器人 Markdown 卡片**回复：标题 + 横幅图 + 红绿报价 + 跳转按钮，全部可在插件设置页配置。
+
+## 命令
+
+| 命令 | 说明 |
+| --- | --- |
+| `bnsrate` / `神石` / `shenshi` | 查询当前时段最低神石比例 |
+| `bnsrate -f` | 忽略缓存，强制刷新 |
+| `bnsrate.preview` | 只输出卡片 Markdown 源码（不发送卡片），调试用 |
+
+## 卡片效果
+
+官方 QQ 机器人的**群聊 / 私聊**下，命令回复会变成 Markdown 卡片，形如：
+
+```
+# 神石比例实时播报
+
+![DD373 DATA #560px #120px](<横幅图片直链>)
+
+大家关注的 DD373 最低神石比例前5条来啦！当前时段（2026/9/10 10:46）最优价格如下：
+
+1元 = <font color="#E60012">151.51</font>神石　|　1神石 = <font color="#00A650">0.0066</font>元
+...
+***
+如需查看完整详情或进行交易，请点击下方按钮直接跳转至 DD373 官网。
+[ 点此直达DD373网站 ]
+```
+
+其它平台（OneBot / Telegram 等）、QQ 频道（`qqguild`）、以及卡片发送失败时，都会**自动回退为纯文本**，不会发不出消息。
+
+## 配置项
+
+| 配置 | 默认值 | 说明 |
+| --- | --- | --- |
+| `url` | dd373 剑灵怀旧服页面 | 目标区服页面 URL |
+| `cacheSeconds` | `60` | 缓存时间（秒），缓存期内重复查询不再请求页面 |
+| `count` | `5` | 显示的条目数量（1–10） |
+| `markdown` | `true` | 用 QQ 官方 Markdown 卡片回复 |
+| `title` | `神石比例实时播报` | 卡片标题 |
+| `bannerUrl` | 空 | **卡片横幅图片直链**，必须是公网可访问的 URL；留空则不显示图片 |
+| `bannerAlt` | `DD373 DATA` | 横幅图片替代文字 |
+| `bannerWidth` / `bannerHeight` | `560` / `120` | 横幅显示尺寸(px)，`0` = 交给 QQ 自动缩放。建议与图片原始宽高比一致 |
+| `intro` | 见插件 | 标题下方引导语，可用 `{count}` `{time}` `{date}` 变量 |
+| `footer` | 见插件 | 报价列表下方说明文字（仅在开启按钮时显示） |
+| `button` | `true` | 是否显示底部跳转按钮 |
+| `buttonText` | `点此直达DD373网站` | 按钮文字 |
+| `buttonUrl` | `https://www.dd373.com/s-d5gqt8.html` | 按钮跳转链接 |
+| `colorForward` | `#E60012` | 「1元=xx神石」数字颜色，留空不染色 |
+| `colorReverse` | `#00A650` | 「1神石=xx元」数字颜色，留空不染色 |
+| `decimalsForward` | `2` | 「1元=xx神石」保留小数位（**截断**，不四舍五入），`0` = 原始值 |
+| `decimalsReverse` | `4` | 「1神石=xx元」保留小数位（截断），`0` = 原始值 |
+
+## ⚠️ 注意事项
+
+1. **颜色只在桌面端生效**。QQ 官方 Markdown 的[支持格式](https://bot.qq.com/wiki/develop/api-v2/server-inter/message/type/markdown.html)中没有字体颜色，颜色依赖 HTML 标签，**只有桌面端 QQNT 会渲染**；安卓 / iOS 会显示为普通文字（卡片本身不会出错）。
+2. **横幅图片必须是公网直链**，QQ 会下载并转存该资源。请勿使用官方的 `server-temp`（首次访问后即删除文件，群里多人同时查看会出现白图）。
+3. 群聊/单聊自定义 Markdown 自 2026/04/23 起已开放给所有机器人，**无需申请 Markdown 模板**；QQ 频道（`qqguild`）场景仍需内邀开通，本插件在频道下自动回退纯文本。
+4. 命令回复属被动消息，不占用主动消息配额。
+
+## 依赖
+
+- `koishi` ^4.18.0
+- 需要 `http` 服务（`ctx.http`）
+
+## License
+
+MIT

package/index.js

@@ -1,26 +1,93 @@
-const { Schema } = require('koishi')
+const { Schema, h } = require('koishi')
 
 const DEFAULT_URL = 'https://www.dd373.com/s-d5gqt8-0-0-0-0-0-0-0-0-0-0-0-1-0-5-0.html'
+const DEFAULT_BUTTON_URL = 'https://www.dd373.com/s-d5gqt8.html'
 
 const FORWARD_RE = /1元\s*=\s*(\d+\.?\d*)神石/g
+const REVERSE_RE = /(?<!\d)1神石\s*=\s*(\d+\.\d+)元/
+
+// ===== 配置 Schema =====
 
 const Config = Schema.object({
   url: Schema.string()
     .default(DEFAULT_URL)
-    .description('dd373 page URL for the target game server'),
+    .description('dd373 目标区服页面 URL'),
   cacheSeconds: Schema.number()
     .default(60)
     .min(10)
     .max(300)
-    .description('Cache TTL in seconds'),
+    .description('缓存时间（秒），缓存内重复查询不再请求页面'),
   count: Schema.number()
     .default(5)
     .min(1)
     .max(10)
     .description('显示的条目数量'),
+
+  markdown: Schema.boolean()
+    .default(true)
+    .description('💬 用 QQ官方 Markdown 卡片回复（仅官方QQ机器人「群/私聊」生效；频道机器人、OneBot 等其它平台自动回退纯文本，发送失败也会回退）'),
+  title: Schema.string()
+    .default('神石比例实时播报')
+    .description('卡片顶部标题（# 一级标题）'),
+
+  bannerUrl: Schema.string()
+    .default('')
+    .description('🖼️ 卡片横幅图片 URL：必须是公网可直接访问的直链（QQ 会下载转存）。留空则不显示图片'),
+  bannerAlt: Schema.string()
+    .default('DD373 DATA')
+    .description('横幅图片的替代文字（图片加载失败时显示）'),
+  bannerWidth: Schema.number()
+    .default(560)
+    .min(0)
+    .max(2000)
+    .description('横幅宽度(px)。0 = 不指定，交给 QQ 自动缩放'),
+  bannerHeight: Schema.number()
+    .default(120)
+    .min(0)
+    .max(2000)
+    .description('横幅高度(px)。建议与图片原始宽高比一致，否则会被拉伸。0 = 不指定'),
+
+  intro: Schema.string()
+    .role('textarea', { rows: [2, 4] })
+    .default('大家关注的 DD373 最低神石比例前{count}条来啦！当前时段（{time}）最优价格如下：')
+    .description('📝 标题下方的引导语。可用变量：{count} 条数、{time} 日期时间、{date} 日期'),
+  footer: Schema.string()
+    .role('textarea', { rows: [2, 4] })
+    .default('如需查看完整详情或进行交易，请点击下方按钮直接跳转至 DD373 官网。')
+    .description('📝 报价列表下方的说明文字（仅在开启按钮时显示）'),
+
+  button: Schema.boolean()
+    .default(true)
+    .description('🔘 在卡片底部显示跳转按钮'),
+  buttonText: Schema.string()
+    .default('点此直达DD373网站')
+    .description('按钮文字'),
+  buttonUrl: Schema.string()
+    .default(DEFAULT_BUTTON_URL)
+    .description('按钮跳转的链接'),
+
+  colorForward: Schema.string()
+    .default('#E60012')
+    .description('「1元=xx神石」数字的颜色，如 #E60012（红）。留空 = 不染色。⚠️ 颜色仅在桌面端 QQ 显示，安卓/iOS 会显示为普通文字'),
+  colorReverse: Schema.string()
+    .default('#00A650')
+    .description('「1神石=xx元」数字的颜色，如 #00A650（绿）。留空 = 不染色'),
+  decimalsForward: Schema.number()
+    .default(2)
+    .min(0)
+    .max(8)
+    .description('「1元=xx神石」保留几位小数（直接截断，不四舍五入）。0 = 显示原始值'),
+  decimalsReverse: Schema.number()
+    .default(4)
+    .min(0)
+    .max(8)
+    .description('「1神石=xx元」保留几位小数（直接截断）。0 = 显示原始值'),
 })
 
+// ===== 抓取与解析 =====
+
 async function fetchRates(ctx, url, count) {
+  const limit = Math.max(1, Math.min(10, Number(count) || 5))
   const response = await ctx.http.get(url, {
     responseType: 'text',
     headers: {
@@ -38,12 +105,14 @@ async function fetchRates(ctx, url, count) {
   const forwardMatches = [...html.matchAll(FORWARD_RE)]
   const rates = []
   for (const m of forwardMatches) {
-    const ctx = html.substring(Math.max(0, m.index - 50), m.index + 100)
-    if (ctx.includes('1神石=')) {
+    const context = html.substring(Math.max(0, m.index - 50), m.index + 100)
+    if (context.includes('1神石=')) {
       const forward = parseFloat(m[1])
-      const reverse = Math.round((1 / forward) * 10000) / 10000
+      // 从同一个上下文中提取反向汇率，避免浮点计算误差
+      const revMatch = context.match(REVERSE_RE)
+      const reverse = revMatch ? parseFloat(revMatch[1]) : Math.round((1 / forward) * 10000) / 10000
       rates.push({ forward, reverse })
-      if (rates.length >= count) break
+      if (rates.length >= limit) break
     }
   }
 
@@ -54,47 +123,179 @@ async function fetchRates(ctx, url, count) {
   return rates
 }
 
-function formatMessage(rates, timestamp) {
-  const time = new Date(timestamp).toLocaleString('zh-CN', {
-    timeZone: 'Asia/Shanghai',
-  })
+// ===== 格式化 =====
+
+function pad2(n) {
+  return String(n).padStart(2, '0')
+}
+
+// 固定按东八区（UTC+8）显示，避免依赖运行环境的时区设置
+function formatTime(timestamp, withSeconds) {
+  const d = new Date(timestamp + 8 * 3600 * 1000)
+  const date = `${d.getUTCFullYear()}/${d.getUTCMonth() + 1}/${d.getUTCDate()}`
+  const time = `${pad2(d.getUTCHours())}:${pad2(d.getUTCMinutes())}`
+  return withSeconds ? `${date} ${time}:${pad2(d.getUTCSeconds())}` : `${date} ${time}`
+}
+
+function colorize(text, color) {
+  const c = String(color || '').trim()
+  return c ? `<font color="${c}">${text}</font>` : String(text)
+}
+
+// 按位截断（不四舍五入），并补足小数位；decimals 为 0 时返回原始值
+// 先定点到 d+2 位消除浮点误差（否则 0.0066 * 10000 会得到 65.9999 这种值）
+function truncate(value, decimals) {
+  const d = Math.max(0, Math.min(8, Math.floor(Number(decimals) || 0)))
+  if (!d) return String(value)
+  const fixed = Number(value).toFixed(d + 2)
+  const [int, frac = ''] = fixed.split('.')
+  return `${int}.${frac.slice(0, d)}`
+}
+
+function fillTemplate(tpl, vars) {
+  let out = String(tpl || '')
+  for (const [k, v] of Object.entries(vars)) out = out.split('{' + k + '}').join(String(v))
+  return out
+}
+
+// 纯文本格式（非官方QQ平台 / 卡片发送失败时的回退，也是历史版本的表现）
+function formatText(rates, timestamp, opts = {}) {
   const lines = [`DD373当前时段最低神石比例前${rates.length}条如下：`]
   for (const r of rates) {
     lines.push(`1元 = ${r.forward}神石  1神石 = ${r.reverse}元`)
   }
-  lines.push(`查询时间: ${time}`)
-  lines.push('详情: https://www.dd373.com/s-d5gqt8.html')
+  lines.push(`查询时间: ${formatTime(timestamp, true)}`)
+  lines.push(`详情: ${DEFAULT_BUTTON_URL}`)
+  if (opts.stale) {
+    lines.push(`[警告] 汇率数据已过期，刷新失败: ${opts.error || '未知错误'}`)
+  }
   return lines.join('\n')
 }
 
+// QQ官方 Markdown 卡片源码
+function buildCardMarkdown(rates, timestamp, config) {
+  const time = formatTime(timestamp, false)
+  const lines = [`# ${config.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})`)
+  }
+
+  const intro = fillTemplate(config.intro, {
+    count: rates.length,
+    time,
+    date: time.split(' ')[0],
+  }).trim()
+  if (intro) lines.push('', intro)
+
+  lines.push('', ...rates.map(r => (
+    `1元 = ${colorize(truncate(r.forward, config.decimalsForward), config.colorForward)}神石　|　`
+    + `1神石 = ${colorize(truncate(r.reverse, config.decimalsReverse), config.colorReverse)}元`
+  )))
+
+  const footer = String(config.footer || '').trim()
+  if (config.button && footer) {
+    lines.push('', '***', '', footer)
+  }
+
+  return lines.join('\n')
+}
+
+// 组装成 koishi 元素：qq:markdown = 原生 markdown 正文，button-group/button = 卡片底部按钮
+// 注意：必须用 qq:markdown 元素包裹，否则适配器会把 # * - > 等符号全部转义成纯文本
+function buildCardElements(markdown, config) {
+  const elements = [h('qq:markdown', {}, markdown)]
+  if (config.button && String(config.buttonUrl || '').trim()) {
+    elements.push(h('button-group', {},
+      h('button', {
+        type: 'link',
+        href: String(config.buttonUrl).trim(),
+        class: 'primary',
+      }, config.buttonText || '点此查看详情')))
+  }
+  return elements
+}
+
+// 只有官方QQ机器人的「群聊 / 私聊」支持自定义 markdown + 自定义按钮
+// 频道机器人 platform 是 qqguild（且 markdown 需内邀开通），其它适配器一律走纯文本
+function supportsCard(session) {
+  const bot = (session && session.bot) || {}
+  return bot.platform === 'qq'
+    && !!bot.internal
+    && typeof bot.internal.sendMessage === 'function'
+}
+
+// ===== 插件主体 =====
+
 function apply(ctx, config) {
+  const logger = ctx.logger('bns-rate')
   let cache = null
 
+  // 取数据：优先缓存，失败时回退到过期缓存
+  async function resolveRates(force) {
+    const ttl = config.cacheSeconds * 1000
+    if (!force && cache && Date.now() - cache.timestamp < ttl) {
+      return { rates: cache.rates, timestamp: cache.timestamp, stale: false }
+    }
+    try {
+      const rates = await fetchRates(ctx, config.url, config.count)
+      cache = { rates, timestamp: Date.now() }
+      return { rates, timestamp: cache.timestamp, stale: false }
+    } catch (e) {
+      const message = e instanceof Error ? e.message : String(e)
+      if (cache) {
+        logger.warn(`刷新失败，使用过期缓存: ${message}`)
+        return { rates: cache.rates, timestamp: cache.timestamp, stale: true, error: message }
+      }
+      throw e
+    }
+  }
+
   ctx.command('bnsrate', '查询剑灵怀旧服神石汇率')
     .alias('神石')
     .alias('shenshi')
-    .action(async () => {
-      const ttl = config.cacheSeconds * 1000
-
-      if (cache && Date.now() - cache.timestamp < ttl) {
-        return formatMessage(cache.rates, cache.timestamp)
-      }
-
+    .option('force', '-f  忽略缓存，强制刷新')
+    .action(async ({ session, options }) => {
+      let data
       try {
-        const rates = await fetchRates(ctx, config.url, config.count)
-        cache = { rates, timestamp: Date.now() }
-        return formatMessage(rates, cache.timestamp)
+        data = await resolveRates(!!(options && options.force))
       } catch (e) {
         const message = e instanceof Error ? e.message : String(e)
+        return '获取汇率失败: ' + message
+      }
 
-        if (cache) {
-          return formatMessage(cache.rates, cache.timestamp)
-            + '\n[警告] 汇率数据已过期，刷新失败: ' + message
+      // 官方QQ机器人的群聊/私聊：发 Markdown 卡片
+      if (config.markdown && session && supportsCard(session) && typeof session.send === 'function') {
+        const markdown = buildCardMarkdown(data.rates, data.timestamp, config)
+        try {
+          await session.send(buildCardElements(markdown, config))
+          return
+        } catch (e) {
+          logger.warn('Markdown 卡片发送失败，回退纯文本:', (e && e.message) || e)
         }
+      }
 
+      return formatText(data.rates, data.timestamp, { stale: data.stale, error: data.error })
+    })
+
+  // 调试用：只看卡片源码，不发送卡片（在控制台执行时也能看）
+  ctx.command('bnsrate.preview', '预览神石 Markdown 卡片源码（不发送卡片）')
+    .action(async () => {
+      try {
+        const data = await resolveRates(false)
+        return buildCardMarkdown(data.rates, data.timestamp, config)
+      } catch (e) {
+        const message = e instanceof Error ? e.message : String(e)
         return '获取汇率失败: ' + message
       }
     })
 }
 
-module.exports = { Config, apply }
+module.exports = {
+  Config,
+  apply,
+  _test: { fetchRates, formatText, buildCardMarkdown, buildCardElements, supportsCard, fillTemplate, truncate },
+}

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "koishi-plugin-bns-rate",
-  "version": "1.1.0",
-  "description": "Fetch BNS Classic Divine Stone exchange rate from dd373.com",
+  "version": "1.2.0",
+  "description": "Fetch BNS Classic Divine Stone exchange rate from dd373.com, with QQ official Markdown card support",
   "main": "index.js",
+  "files": [
+    "index.js",
+    "README.md"
+  ],
   "license": "MIT",
-  "keywords": ["koishi", "koishi-plugin", "bns", "dd373", "exchange-rate", "神石", "剑灵"],
+  "keywords": ["koishi", "koishi-plugin", "bns", "dd373", "exchange-rate", "神石", "剑灵", "markdown"],
   "peerDependencies": {
     "koishi": "^4.18.0"
   },
@@ -13,8 +17,8 @@
   },
   "koishi": {
     "description": {
-      "zh": "从 dd373.com 获取剑灵怀旧服神石实时汇率，输入命令即可查询最低比例。支持 神石/bnsrate/shenshi 命令。",
-      "en": "Fetch BNS Classic Divine Stone exchange rate from dd373.com"
+      "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."
     },
     "service": {
       "required": ["http"]

package/.github/workflows/publish.yml

@@ -1,18 +0,0 @@
-name: Publish to npm
-
-on:
-  push:
-    branches: [master]
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '22'
-          registry-url: 'https://registry.npmjs.org'
-      - run: npm publish
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.gitignore

@@ -1,6 +0,0 @@
-# Ignore everything except plugin files
-/*
-!.gitignore
-!/.github
-!/index.js
-!/package.json