koishi-plugin-guild-request-approval 0.0.0-stage → 0.1.0

package/index.js

@@ -0,0 +1,427 @@
+// ESM 模块（见 package.json 的 "type": "module"）。想用 CommonJS 就把下面这行换成
+// const { Schema } = require('koishi')，再把两个 export const 改成 module.exports = { ... }
+import { Schema } from 'koishi'
+
+export const name = 'guild-request-approval'
+
+// 故意不 inject database / http：所有状态放内存，装上就能跑，进程重启后挂起的申请会丢。
+export const inject = []
+
+export const Config = Schema.object({
+  mode: Schema.union([
+    Schema.const('accept').description('自动通过'),
+    Schema.const('reject').description('自动拒绝'),
+    Schema.const('manual').description('转发给管理员，人工回复审批'),
+    Schema.const('auto').description('按条件筛选，不满足时走 fallback'),
+  ]).default('manual').description('审批模式'),
+
+  target: Schema.string().default('')
+    .description('人工审批的转发目标：`group:123456`、`private:10001`，只写数字默认当群号。'),
+
+  admins: Schema.array(Schema.string()).default([])
+    .description('有权回复审批的管理员 QQ；留空表示“转发目标所在会话里的任何人都能批”。'),
+
+  timeout: Schema.natural().default(300).description('人工审批等待时长（秒），0 = 永不超时。'),
+
+  timeoutAction: Schema.union([
+    Schema.const('reject').description('自动拒绝'),
+    Schema.const('accept').description('自动通过'),
+    Schema.const('none').description('不处理，留在 QQ 那边自然过期'),
+  ]).default('reject').description('超时后的动作'),
+
+  minLevel: Schema.natural().default(0).description('auto 模式：最低 QQ 等级，0 = 不检查。'),
+
+  minAgeYears: Schema.number().default(0).description('auto 模式：最短注册年限（可写 0.5），0 = 不检查。'),
+
+  unknownAs: Schema.union([
+    Schema.const('fail').description('当作不满足，转 fallback'),
+    Schema.const('pass').description('当作满足，放行'),
+  ]).default('fail').description('auto 模式拿不到等级/注册时间时怎么办'),
+
+  fallback: Schema.union([
+    Schema.const('manual').description('转人工审批'),
+    Schema.const('reject').description('直接拒绝'),
+  ]).default('manual').description('auto 模式条件不满足时的去向'),
+
+  maxPending: Schema.natural().default(200).description('同时挂起的申请上限，超了就先结算最旧的。'),
+
+  acceptComment: Schema.string().default('').description('通过时的附言，可空。'),
+
+  rejectComment: Schema.string().default('').description('拒绝 / 超时拒绝的默认理由。'),
+
+  forwardTemplate: Schema.string().role('textarea').default(
+    '【入群申请 #{id}】\n群号：{guildId}\n申请人：{userId}\n附言：{comment}\n{reason}\n时间：{time}\n\n回复「同意 {id}」或「拒绝 {id} 理由」',
+  ).description('转发文案，支持 {id} {guildId} {userId} {comment} {reason} {time}'),
+
+  replyOnResult: Schema.boolean().default(true).description('处理完是否在回复处回执一句。'),
+})
+
+const MODES = ['accept', 'reject', 'manual', 'auto']
+const YEAR_MS = 365.25 * 24 * 3600 * 1000
+
+// `group:123` / `123` / `private:456` / `qq：789`（中文冒号也认）
+function parseTarget(raw) {
+  const s = String(raw ?? '').trim()
+  if (!s) return { type: 'group', id: '' }
+  const m = /^(group|private|user|qq|guild|channel)\s*[:：]\s*(.+)$/i.exec(s)
+  if (!m) return { type: 'group', id: s }
+  const type = /^(private|user|qq)$/i.test(m[1]) ? 'private' : 'group'
+  return { type, id: m[2].trim() }
+}
+
+function firstNumber(obj, keys) {
+  if (!obj) return null
+  for (const key of keys) {
+    const v = obj[key]
+    if (v === null || v === undefined || v === '') continue
+    const n = Number(v)
+    if (Number.isFinite(n)) return n
+  }
+  return null
+}
+
+// 秒 / 毫秒 / YYYYMMDD / 日期字符串，都当成时间戳吃掉
+function toTimestamp(input) {
+  if (input === null || input === undefined || input === '') return null
+  if (input instanceof Date) return Number.isNaN(input.getTime()) ? null : input.getTime()
+  const n = Number(input)
+  if (Number.isFinite(n)) {
+    if (n > 1e12) return n
+    if (n > 1e9) return n * 1000
+    if (n >= 19000101 && n <= 29991231) {
+      const s = String(Math.trunc(n))
+      return new Date(+s.slice(0, 4), +s.slice(4, 6) - 1, +s.slice(6, 8)).getTime()
+    }
+    return null
+  }
+  const t = Date.parse(String(input))
+  return Number.isNaN(t) ? null : t
+}
+
+function renderTemplate(tpl, rec) {
+  return String(tpl ?? '').replace(/\{(\w+)\}/g, (_, key) => {
+    if (key === 'time') return new Date(rec.createdAt).toLocaleString('zh-CN', { hour12: false })
+    if (key === 'comment') return rec.comment || '（无）'
+    if (key === 'reason') return rec.reason ? `筛选未过：${rec.reason}` : ''
+    const v = rec[key]
+    return v === null || v === undefined ? '' : String(v)
+  })
+}
+
+// 等级 / 注册时间只能“有就用”：官方 QQ 机器人接口根本不给这两项，
+// 这里按 事件字段 → bot.internal（OneBot 的 getGroupMemberInfo）的顺序碰运气。
+async function resolveProfile(bot, guildId, userId, event) {
+  const out = { level: null, ageYears: null }
+  const pools = [event?.user, event?.member, event?.d, event].filter(Boolean)
+
+  for (const pool of pools) {
+    if (out.level === null) {
+      out.level = firstNumber(pool, ['level', 'qqLevel', 'qq_level', 'userLevel', 'user_level'])
+    }
+    if (out.ageYears === null) {
+      const raws = ['regTime', 'registerTime', 'register_time', 'regTimestamp', 'createTime', 'createdAt', 'created_at']
+      for (const key of raws) {
+        const ts = toTimestamp(pool[key])
+        if (ts) {
+          out.ageYears = (Date.now() - ts) / YEAR_MS
+          break
+        }
+      }
+    }
+  }
+
+  if (out.level === null && bot?.internal && typeof bot.internal.getGroupMemberInfo === 'function') {
+    try {
+      const info = await bot.internal.getGroupMemberInfo(guildId, userId)
+      out.level = firstNumber(info, ['level', 'qq_level', 'qqLevel'])
+    } catch (e) {
+      // 拿不到很正常（官方接口没有这个能力），不用当错误
+    }
+  }
+
+  return out
+}
+
+function evaluate(profile, config) {
+  const fails = []
+  const minLevel = Number(config.minLevel) || 0
+  const minAgeYears = Number(config.minAgeYears) || 0
+
+  if (minLevel > 0) {
+    if (profile.level === null) {
+      if (config.unknownAs === 'fail') fails.push('拿不到 QQ 等级')
+    } else if (profile.level < minLevel) {
+      fails.push(`QQ 等级 ${profile.level} 低于 ${minLevel}`)
+    }
+  }
+
+  if (minAgeYears > 0) {
+    if (profile.ageYears === null) {
+      if (config.unknownAs === 'fail') fails.push('拿不到注册时间')
+    } else if (profile.ageYears < minAgeYears) {
+      fails.push(`注册 ${profile.ageYears.toFixed(1)} 年，不足 ${minAgeYears} 年`)
+    }
+  }
+
+  return fails
+}
+
+async function sendTo(bot, target, content) {
+  const { type, id } = parseTarget(target)
+  if (!id) throw new Error('没有配置转发目标 target')
+  if (!bot) throw new Error('没有可用的 bot')
+  if (type === 'private') {
+    // 官方 QQ 适配器的私聊必须走 sendPrivateMessage，sendMessage('private:x') 在它上面不成立
+    if (typeof bot.sendPrivateMessage !== 'function') throw new Error('当前适配器不支持私聊，改成 group:<群号>')
+    return bot.sendPrivateMessage(id, content)
+  }
+  return bot.sendMessage(id, content)
+}
+
+export function apply(ctx, config) {
+  const logger = ctx.logger('guild-request-approval')
+  const pending = new Map()
+  const seen = new Set() // adapter-qq-crack 偶尔会把同一条申请推两次
+  let seq = 0
+
+  const safeSend = async (session, text) => {
+    try {
+      await session.send(text)
+    } catch (e) {
+      logger.warn('回执发送失败：%s', e?.message ?? e)
+    }
+  }
+
+  const findPending = (input) => {
+    const key = String(input ?? '').trim().replace(/^[#＃]/, '')
+    if (!key) return null
+    if (pending.has(key)) return pending.get(key)
+    for (const rec of pending.values()) {
+      if (String(rec.messageId) === key) return rec
+    }
+    return null
+  }
+
+  const settle = async (rec, approve, comment, by) => {
+    if (rec.status !== 'pending') return false
+    rec.status = approve ? 'accepted' : 'rejected'
+    if (rec.timer) {
+      clearTimeout(rec.timer)
+      rec.timer = null
+    }
+    pending.delete(rec.id)
+    try {
+      await rec.bot.handleGuildMemberRequest(rec.messageId, approve, comment || undefined)
+      logger.info('申请 #%s %s@%s → %s%s', rec.id, rec.userId, rec.guildId,
+        approve ? '通过' : '拒绝', by ? `（${by}）` : '')
+      return true
+    } catch (e) {
+      // 适配器没实现 handleGuildMemberRequest 时只会在这里炸，不会把插件带崩
+      logger.warn('申请 #%s 调用 handleGuildMemberRequest 失败：%s', rec.id, e?.message ?? e)
+      rec.status = 'error'
+      return false
+    }
+  }
+
+  const armTimeout = (rec) => {
+    const seconds = Number(config.timeout) || 0
+    if (seconds <= 0) return
+    // unref：别让挂起的定时器拖住进程退出
+    rec.timer = setTimeout(async () => {
+      rec.timer = null
+      if (config.timeoutAction === 'none') {
+        rec.status = 'expired'
+        pending.delete(rec.id)
+        logger.info('申请 #%s 超时，按配置留在 QQ 侧', rec.id)
+        return
+      }
+      const ok = await settle(rec, config.timeoutAction === 'accept', config.rejectComment || '超时未处理', '超时')
+      if (ok && config.replyOnResult) {
+        try {
+          await sendTo(rec.bot, config.target, `申请 #${rec.id} 超时，已自动${config.timeoutAction === 'accept' ? '通过' : '拒绝'}`)
+        } catch (e) {
+          // 回执失败无所谓，主流程已经完成了
+        }
+      }
+    }, seconds * 1000)
+    rec.timer.unref?.()
+  }
+
+  const fromTarget = (session) => {
+    const { type, id } = parseTarget(config.target)
+    if (!id) return false
+    if (type === 'private') return String(session.userId) === id
+    return [session.guildId, session.channelId].some((v) => v !== null && v !== undefined && String(v) === id)
+  }
+
+  const allowed = (session) => {
+    const admins = (config.admins ?? []).map(String).map((s) => s.trim()).filter(Boolean)
+    if (admins.length) return admins.includes(String(session.userId))
+    return fromTarget(session)
+  }
+
+  const forward = async (rec) => {
+    const text = renderTemplate(config.forwardTemplate, rec)
+    const { id } = parseTarget(config.target)
+    if (!id) throw new Error('没有配置转发目标 target')
+    await sendTo(rec.bot || ctx.bots[0], config.target, text)
+  }
+
+  ctx.on('guild-member-request', async (session) => {
+    // adapter-qq-crack 的事件字段不保证齐全：缺一个就跳，别猜
+    const guildId = session.guildId
+    const userId = session.userId
+    const messageId = session.messageId || session.event?.message?.id || session.event?.messageId
+    const comment = session.event?.comment || session.event?.message?.content || session.content || ''
+
+    if (!guildId || !userId || !messageId) {
+      logger.warn('入群申请字段缺失，已跳过：guildId=%o userId=%o messageId=%o', guildId, userId, messageId)
+      return
+    }
+
+    if (seen.has(String(messageId))) {
+      logger.debug('重复的申请事件 %s，忽略', messageId)
+      return
+    }
+    seen.add(String(messageId))
+    if (seen.size > 1000) seen.delete(seen.values().next().value)
+
+    const bot = session.bot || ctx.bots[0]
+    if (!bot) {
+      logger.warn('没有可用的 bot，跳过 %s 的申请', userId)
+      return
+    }
+
+    const mode = MODES.includes(config.mode) ? config.mode : 'manual'
+    seq += 1
+    const rec = {
+      id: String(seq),
+      guildId,
+      userId,
+      messageId,
+      comment,
+      reason: '',
+      bot,
+      createdAt: Date.now(),
+      status: 'pending',
+      timer: null,
+    }
+
+    if (mode === 'accept') {
+      await settle(rec, true, config.acceptComment)
+      return
+    }
+
+    if (mode === 'reject') {
+      await settle(rec, false, config.rejectComment || '本群暂不开放')
+      return
+    }
+
+    if (mode === 'auto') {
+      const profile = await resolveProfile(bot, guildId, userId, session.event)
+      const fails = evaluate(profile, config)
+      logger.debug('auto 判定 #%s level=%o ageYears=%o fails=%o', rec.id, profile.level, profile.ageYears, fails)
+      if (!fails.length) {
+        await settle(rec, true, config.acceptComment)
+        return
+      }
+      if (config.fallback === 'reject') {
+        await settle(rec, false, fails.join('；') || config.rejectComment)
+        return
+      }
+      rec.reason = fails.join('；')
+    }
+
+    // manual（auto 转人工也走这儿）
+    pending.set(rec.id, rec)
+    const cap = Number(config.maxPending) || 200
+    if (pending.size > cap) {
+      const oldest = pending.values().next().value
+      if (oldest && oldest.id !== rec.id) {
+        logger.warn('挂起申请超过 %s 条，先结算最旧的 #%s', cap, oldest.id)
+        if (config.timeoutAction === 'none') {
+          oldest.status = 'expired'
+          pending.delete(oldest.id)
+        } else {
+          await settle(oldest, config.timeoutAction === 'accept', config.rejectComment || '积压超限')
+        }
+      }
+    }
+
+    try {
+      await forward(rec)
+    } catch (e) {
+      // 转不出去就等于没人能批，按超时策略收掉，别让申请一直吊在 QQ 那边
+      logger.warn('转发申请 #%s 失败：%s', rec.id, e?.message ?? e)
+      if (config.timeoutAction === 'none') {
+        rec.status = 'expired'
+        pending.delete(rec.id)
+      } else {
+        await settle(rec, config.timeoutAction === 'accept', config.rejectComment || '无人可审批')
+      }
+      return
+    }
+
+    armTimeout(rec)
+  })
+
+  // 手写正则而不是 ctx.command：审批人是在群里随口回一句，不该被全局前缀绑住
+  const REJECT_RE = /^(?:不同意|拒绝|驳回|reject|deny)\s*[#＃]?([0-9A-Za-z_-]+)\s*([\s\S]*)$/i
+  const APPROVE_RE = /^(?:同意|通过|批准|approve|accept)\s*[#＃]?([0-9A-Za-z_-]+)\s*([\s\S]*)$/i
+
+  ctx.on('message', async (session) => {
+    if (!session.content) return
+    if (session.userId && session.selfId && session.userId === session.selfId) return
+
+    // QQ 消息里会混进 <at id="..."/> 这类片段，先剥掉再匹配
+    let text = String(session.content).replace(/<[^>]*>/g, ' ').trim()
+    text = text.replace(/^[!！/／.。、,，\s]+/, '')
+    if (!text) return
+
+    let approved = false
+    let matched = REJECT_RE.exec(text)
+    if (matched) {
+      approved = false
+    } else {
+      matched = APPROVE_RE.exec(text)
+      if (matched) approved = true
+    }
+    if (!matched) return
+
+    const input = matched[1]
+    const comment = (matched[2] || '').trim()
+    const rec = findPending(input)
+
+    if (!rec) {
+      if (allowed(session)) await safeSend(session, `没找到待处理的申请 #${input.replace(/^[#＃]/, '')}`)
+      return
+    }
+    if (!allowed(session)) {
+      await safeSend(session, '你没有审批权限')
+      return
+    }
+
+    const ok = await settle(rec, approved, approved ? (comment || config.acceptComment) : (comment || config.rejectComment), `by ${session.userId}`)
+    if (!ok) {
+      await safeSend(session, `申请 #${rec.id} 处理失败，看看日志`)
+      return
+    }
+    if (config.replyOnResult) {
+      await safeSend(session, approved
+        ? `已同意 #${rec.id}`
+        : `已拒绝 #${rec.id}${comment ? '：' + comment : ''}`)
+    }
+    // 私聊里批的，顺手在转发目标那边播报一句，其他管理员不至于重复操作
+    if (!fromTarget(session)) {
+      try {
+        await sendTo(rec.bot, config.target, `申请 #${rec.id} 已被 ${session.userId} ${approved ? '同意' : '拒绝'}`)
+      } catch (e) {
+        // 播报失败不影响结果
+      }
+    }
+  })
+
+  if (['manual', 'auto'].includes(config.mode) && !parseTarget(config.target).id) {
+    logger.warn('当前是 %s 模式但没配置 target，申请会被直接按超时策略处理', config.mode)
+  }
+}

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "koishi-plugin-guild-request-approval",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "QQ 群入群申请审批：自动通过 / 自动拒绝 / 转发人工审批 / 条件筛选，适配 adapter-qq",
+  "main": "index.js",
+  "type": "module",
+  "files": [
+    "index.js",
+    "readme.md"
+  ],
+  "keywords": [
+    "chatbot",
+    "koishi",
+    "plugin",
+    "qq",
+    "guild",
+    "request",
+    "adapter-qq"
+  ],
+  "license": "MIT",
+  "author": "7-Ice",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/7-Ice/koishi-plugin-guild-request-approval.git"
+  },
+  "homepage": "https://github.com/7-Ice/koishi-plugin-guild-request-approval",
+  "bugs": {
+    "url": "https://github.com/7-Ice/koishi-plugin-guild-request-approval/issues"
+  },
+  "peerDependencies": {
+    "koishi": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "koishi": {
+    "description": {
+      "zh": "群入群申请审批：accept / reject / manual / auto 四种模式，可转发给管理员回复「同意 1」「拒绝 1 理由」，支持超时兜底",
+      "en": "Guild member request approval with accept / reject / manual / auto modes and timeout fallback"
+    },
+    "service": {
+      "required": [],
+      "optional": []
+    }
+  }
+}

package/readme.md

@@ -0,0 +1,43 @@
+# koishi-plugin-guild-request-approval
+
+处理 QQ 群入群申请，四种模式随便挑：直接过、直接拒、丢给管理员、按条件筛。
+
+[![npm](https://img.shields.io/npm/v/koishi-plugin-guild-request-approval?style=flat-square&logo=npm&color=cb3837)](https://www.npmjs.com/package/koishi-plugin-guild-request-approval)
+[![downloads](https://img.shields.io/npm/dm/koishi-plugin-guild-request-approval?style=flat-square&color=blue)](https://www.npmjs.com/package/koishi-plugin-guild-request-approval)
+[![license](https://img.shields.io/npm/l/koishi-plugin-guild-request-approval?style=flat-square&color=3da639)](package.json)
+[![koishi](https://img.shields.io/badge/koishi-%5E4.0.0-ff6b6b?style=flat-square)](https://koishi.chat)
+
+## 装
+
+```bash
+npm i koishi-plugin-guild-request-approval
+```
+
+或者 Koishi 控制台 → 插件市场搜 `guild-request-approval`。装完点开配置，选模式、填目标就行，不用 database。
+
+## 配置项
+
+| 项 | 说明 |
+| --- | --- |
+| `mode` | `accept` 直接过 / `reject` 直接拒 / `manual` 转人工 / `auto` 条件筛 |
+| `target` | 转人工的落地位置：`group:123456`、`private:10001`，只写数字当群号 |
+| `admins` | 能回复审批的 QQ 列表；留空 = 转发目标会话里谁都能批 |
+| `timeout` | 等多久（秒），`0` = 一直等 |
+| `timeoutAction` | 超时后 `reject` / `accept` / `none` |
+| `minLevel` | `auto` 用，最低 QQ 等级，`0` 不检查 |
+| `minAgeYears` | `auto` 用，最短注册年限，`0` 不检查 |
+| `unknownAs` | `auto` 拿不到等级/注册时间时：`fail` 当不满足，`pass` 放行 |
+| `fallback` | `auto` 不满足条件时：`manual` 转人工，`reject` 直接拒 |
+| `maxPending` | 最多挂起多少条，超了先结算最旧的 |
+| `acceptComment` / `rejectComment` | 通过/拒绝附言 |
+| `forwardTemplate` | 转发文案，占位 `{id} {guildId} {userId} {comment} {reason} {time}` |
+| `replyOnResult` | 处理完回不回一句 |
+
+官方机器人接口不提供 QQ 等级和注册时间，`auto` 模式在这类适配器上会一直走“拿不到数据”分支——要么把 `unknownAs` 设成 `pass`，要么就用 `manual`。
+
+## 验证
+
+- `accept` / `reject`：小号发申请，群里立刻进人 / 立刻被拒。
+- `manual`：申请转发到 `target`，回复 `同意 1` 或 `拒绝 1 太新了`，回执出现即生效；不管它，到点看 `timeoutAction` 有没有执行。
+- `auto`：把 `minLevel` 设成 999，申请必然转人工或直接拒，然后把 `unknownAs` 改成 `pass` 再试一次，行为应当翻转。
+- 日志标签 `guild-request-approval` 里能看到每条申请的判定结果，字段缺失会打 warn。

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.