koishi-plugin-qq-github-bridge 0.0.0-stage → 1.0.0

package/src/config.ts

@@ -0,0 +1,111 @@
+import { Schema } from 'koishi'
+import { BridgeError } from './utils/errors'
+
+export const QQ_PATTERN = /^[1-9][0-9]{4,19}$/
+export const DEFAULT_TEMPLATE = '以下正文由 QQ 群成员通过 GitHub Bridge 提交。\n\n{body}'
+
+export interface Binding {
+  groupId: string
+  owner: string
+  repo: string
+  enabled: boolean
+}
+
+export interface Config {
+  token: string
+  apiBaseUrl: string
+  apiVersion: string
+  requestTimeout: number
+  readRetries: number
+  commentTemplate: string
+  bindings: Binding[]
+  replyPrefix: string
+  replyPattern: string
+  closePrefix: string
+  openPrefix: string
+  adminPrefix: string
+  superAdmins: string[]
+  enableAdminCommands: boolean
+  userCooldown: number
+  maxCommentLength: number
+  allowMultiline: boolean
+  auditEnabled: boolean
+  auditRetentionDays: number
+  dedupWindow: number
+  confirmHighRisk: boolean
+  confirmationTimeout: number
+}
+
+const prefix = (value: string, description: string) => Schema.string().default(value).description(description)
+const qq = () => Schema.string().pattern(QQ_PATTERN).description('真实数字 QQ 号，按字符串填写。')
+
+export const Config: Schema<Partial<Config>, Config> = Schema.intersect([
+  Schema.object({
+    token: Schema.string().role('secret').default('').description('统一 GitHub Personal Access Token。支持 Fine-grained PAT；不要在 QQ 中发送。'),
+    apiBaseUrl: Schema.string().default('https://api.github.com').description('GitHub REST API 根地址；企业版通常为 https://主机/api/v3。必须使用 HTTPS（本机测试除外）。'),
+    apiVersion: Schema.string().default('2026-03-10').description('GitHub API 版本。企业版可按服务器支持情况修改。'),
+    requestTimeout: Schema.number().min(1000).max(60000).step(1).default(15000).description('单次请求超时（毫秒）。写入不会自动重试。'),
+    readRetries: Schema.number().min(0).max(3).step(1).default(2).description('只读请求遇到网络故障或 5xx 时的重试次数。'),
+    commentTemplate: Schema.string().role('textarea').default(DEFAULT_TEMPLATE).description('正文模板，必须且只能包含一次 {body}。固定身份头由插件生成，不可覆盖；原始正文原样替换。'),
+  }).description('GitHub 设置'),
+  Schema.object({
+    bindings: Schema.array(Schema.object({
+      groupId: qq().description('QQ群号；一个群仅能出现一次。'),
+      owner: Schema.string().required().description('仓库所属用户或组织，不填 URL。'),
+      repo: Schema.string().required().description('仓库名称，不填 URL 或 owner/。'),
+      enabled: Schema.boolean().default(true).description('启用此群的仓库绑定。'),
+    })).role('table').default([]).description('多个群可绑定同一仓库；未绑定或禁用的群完全忽略。'),
+  }).description('仓库绑定'),
+  Schema.object({
+    replyPrefix: prefix('re', '普通评论前缀，例如 re1003 内容。'),
+    replyPattern: Schema.string().role('textarea').default('').description('留空使用回复前缀。自定义 RE2 表达式须以 ^ 开始、$ 结束，并有命名组 (?<number>...) 和 (?<body>...)。不支持回溯引用与前后查找；固定使用 u 模式。'),
+    closePrefix: prefix('close', '关闭前缀，例如 close1003。'),
+    openPrefix: prefix('open', '重开前缀，例如 open1003。'),
+    adminPrefix: prefix('ghadmin', '管理员指令前缀，例如 ghadmin add 123456789。二次确认使用此前缀 confirm 确认码。'),
+  }).description('命令设置'),
+  Schema.object({
+    superAdmins: Schema.array(qq()).min(1).required().description('至少配置一个超级管理员 QQ。通过本页恢复控制权；QQ 指令不能撤销。'),
+    enableAdminCommands: Schema.boolean().default(true).description('允许在已绑定群使用管理员新增、撤销和列表命令。'),
+  }).description('独立权限设置'),
+  Schema.object({
+    userCooldown: Schema.number().min(0).max(3600000).step(1).default(5000).description('每位 QQ 用户的操作冷却（毫秒），跨群共用；确认指令不额外冷却。'),
+    maxCommentLength: Schema.number().min(1).max(30000).step(1).default(6000).description('评论正文最大字符长度（UTF-16 单元）。'),
+    allowMultiline: Schema.boolean().default(true).description('允许多行评论和 Markdown。'),
+    auditEnabled: Schema.boolean().default(true).description('保存操作审计到 Koishi 数据库；不存 Token、昵称或评论正文。'),
+    auditRetentionDays: Schema.number().min(1).max(365).step(1).default(30).description('审计保留天数，每小时自动清理过期记录。'),
+    dedupWindow: Schema.number().min(300000).max(604800000).step(1).default(86400000).description('消息去重时间窗口（毫秒），默认 24 小时。过期事件不执行；记录跨重启保留。'),
+    confirmHighRisk: Schema.boolean().default(true).description('关闭、重开、新增和撤销管理员前要求同一 QQ、同一群在限时内确认。'),
+    confirmationTimeout: Schema.number().min(10000).max(300000).step(1).default(60000).description('高风险操作确认有效期（毫秒）；重载后失效。'),
+  }).description('安全与可靠性'),
+])
+
+export function validateConfig(config: Config) {
+  const invalid = (message: string): never => { throw new BridgeError('config', message) }
+  if (!config.token || config.token.length > 500 || /\s|[^\x21-\x7e]/.test(config.token)) {
+    invalid('请在后台填写有效格式的 GitHub Token（不可为空或包含空白）。')
+  }
+  let base: URL
+  try { base = new URL(config.apiBaseUrl) } catch { return invalid('GitHub API 地址不是有效 URL。') }
+  const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(base.hostname)
+  if (base.protocol !== 'https:' && !(base.protocol === 'http:' && loopback)) invalid('GitHub API 必须使用 HTTPS。')
+  if (base.username || base.password || base.search || base.hash) invalid('GitHub API 地址不得包含用户名、密码、查询参数或片段。')
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(config.apiVersion)) invalid('API 版本必须采用 YYYY-MM-DD 格式。')
+  const prefixes = [config.replyPrefix, config.closePrefix, config.openPrefix, config.adminPrefix]
+  if (prefixes.some(value => !/^[A-Za-z][A-Za-z0-9_-]{0,31}$/.test(value))) invalid('指令前缀须以英文字母开头，最多 32 位，仅含英文字母、数字、下划线和连字符。')
+  if (prefixes.some((p, i) => prefixes.some((q, j) => i !== j && p.startsWith(q)))) invalid('指令前缀不得相同或互为前缀。')
+  if (!config.superAdmins.length || config.superAdmins.some(id => !QQ_PATTERN.test(id))) invalid('必须配置至少一个有效的超级管理员 QQ。')
+  if (new Set(config.superAdmins).size !== config.superAdmins.length) invalid('超级管理员列表存在重复 QQ。')
+  const groups = new Set<string>()
+  if (config.bindings.length > 500) invalid('最多允许配置 500 个群绑定。')
+  for (const binding of config.bindings) {
+    if (!QQ_PATTERN.test(binding.groupId)) invalid('群绑定中存在无效的 QQ 群号。')
+    if (groups.has(binding.groupId)) invalid('同一 QQ 群只能绑定一次。')
+    groups.add(binding.groupId)
+    if (!/^[A-Za-z0-9][A-Za-z0-9-]{0,99}$/.test(binding.owner) ||
+      !/^[A-Za-z0-9_.-]{1,100}$/.test(binding.repo) || ['.', '..'].includes(binding.repo)) invalid('仓库 Owner 或名称不合法；请分别填写名称，不要填写 URL。')
+  }
+  if (config.commentTemplate.length > 4000 || config.commentTemplate.split('{body}').length !== 2) invalid('评论模板最多 4000 字符，并且必须且只能包含一次 {body}。')
+  if (/\{(?!body\})[^{}]*\}/.test(config.commentTemplate)) invalid('评论模板仅支持 {body} 占位符。')
+  if (config.commentTemplate.includes(config.token)) invalid('评论模板不能包含 GitHub Token。')
+  return config
+}

package/src/console.ts

@@ -0,0 +1,65 @@
+import { resolve } from 'node:path'
+import type { Context } from 'koishi'
+import type { Client } from '@koishijs/plugin-console'
+import type {} from '@koishijs/plugin-auth'
+import { QQ_PATTERN } from './config'
+import type { Actor } from './types'
+import type {} from './rpc'
+import type { Bridge } from './handlers/commands'
+import { BridgeError, publicError, redact } from './utils/errors'
+
+/** Web deployer access is separate from the QQ administrator model. No QQ authority is used. */
+export async function authenticateConsole(ctx: Context, client: Client): Promise<Actor> {
+  if (!ctx.get('auth')) throw new BridgeError('console-auth', '控制台登录服务未启用，管理接口已停用。')
+  const auth = client.auth
+  if (!auth || auth.expiredAt <= Date.now()) throw new BridgeError('console-auth', '请先以部署管理员账号登录控制台。')
+  const [token] = await ctx.database.get('token', { id: auth.id, token: auth.token, expiredAt: { $gt: Date.now() } }, ['id'])
+  const [user] = await ctx.database.get('user', { id: auth.id }, ['id', 'authority'])
+  if (!token || !user || user.authority < 5) throw new BridgeError('console-auth', '只有已登录的控制台部署管理员（等级 5）可以维护此插件。')
+  const [binding] = await ctx.database.get('binding', { aid: user.id, platform: 'onebot' }, { limit: 1 })
+  return {
+    source: 'console', id: String(user.id), qq: binding && QQ_PATTERN.test(binding.pid) ? binding.pid : '',
+    nickname: '', groupId: '', repository: '',
+  }
+}
+
+export function registerConsole(ctx: Context, bridge: Bridge) {
+  // Without the official auth service, even the listeners do not exist.
+  ctx.inject(['console', 'auth'], ctx => {
+    ctx.console.addEntry({ dev: resolve(__dirname, '../client/index.ts'), prod: resolve(__dirname, '../dist') })
+    const safe = async <T>(task: () => Promise<T>): Promise<T> => {
+      try { return await task() } catch (error) {
+        // Console logs thrown objects, so replace them rather than rethrowing raw errors.
+        throw new Error(redact(publicError(error).message, bridge.config.token))
+      }
+    }
+    ctx.console.addListener('qq-github-bridge/dashboard', function (page = 1) {
+      return safe(async () => {
+        if (!Number.isSafeInteger(page) || page < 1 || page > 100000) throw new BridgeError('input', '页码无效。')
+        return bridge.dashboard(() => authenticateConsole(ctx, this), page)
+      })
+    }, { authority: 5 })
+    ctx.console.addListener('qq-github-bridge/admin', function (action, qq) {
+      return safe(async () => {
+        if (!['add', 'remove'].includes(action) || typeof qq !== 'string' || !QQ_PATTERN.test(qq)) throw new BridgeError('input', '管理员操作或 QQ 号无效。')
+        return bridge.manage(() => authenticateConsole(ctx, this), action, qq)
+      })
+    }, { authority: 5 })
+    ctx.console.addListener('qq-github-bridge/validate', function (groupId) {
+      return safe(async () => {
+        if (groupId !== undefined && (typeof groupId !== 'string' || !QQ_PATTERN.test(groupId))) throw new BridgeError('input', 'QQ群号无效。')
+        return bridge.validateToken(() => authenticateConsole(ctx, this), groupId)
+      })
+    }, { authority: 5 })
+    // Console 5.30 addListener() assigns into a dictionary and does NOT register
+    // a disposal effect. Explicitly remove only this activation's own listeners.
+    const listeners = ctx.console.listeners
+    const owned = ['dashboard', 'admin', 'validate'].map(name => {
+      const key = `qq-github-bridge/${name}`
+      return [key, listeners[key]] as const
+    })
+    ctx.on('dispose', () => {
+      for (const [key, listener] of owned) if (listeners[key] === listener) delete listeners[key]
+    })
+  })
+}

package/src/database/models.ts

@@ -0,0 +1,45 @@
+import type { Context } from 'koishi'
+
+export interface AdminRow { qq: string; addedBy: string; createdAt: Date }
+export interface EventRow { id: string; expiresAt: Date }
+export interface CooldownRow { qq: string; expiresAt: Date }
+export interface AuditRow {
+  id: string
+  actorId: string
+  actorQQ: string
+  source: string
+  action: string
+  target: string
+  groupId: string
+  repository: string
+  createdAt: Date
+  result: string
+  detail: string
+}
+
+declare module 'koishi' {
+  interface Tables {
+    qgh_admin: AdminRow
+    qgh_event: EventRow
+    qgh_cooldown: CooldownRow
+    qgh_audit: AuditRow
+  }
+}
+
+/** Additive schema, stable keys. Future renamed fields should use Minato's legacy migration. */
+export function registerModels(ctx: Context) {
+  ctx.model.extend('qgh_admin', {
+    qq: 'string(20)', addedBy: 'string(64)', createdAt: 'timestamp',
+  }, { primary: 'qq' })
+  ctx.model.extend('qgh_event', {
+    id: 'string(64)', expiresAt: 'timestamp',
+  }, { primary: 'id' })
+  ctx.model.extend('qgh_cooldown', {
+    qq: 'string(20)', expiresAt: 'timestamp',
+  }, { primary: 'qq' })
+  ctx.model.extend('qgh_audit', {
+    id: 'string(36)', actorId: 'string(64)', actorQQ: 'string(20)', source: 'string(16)',
+    action: 'string(32)', target: 'string(100)', groupId: 'string(20)', repository: 'string(201)',
+    createdAt: 'timestamp', result: 'string(24)', detail: 'string(255)',
+  }, { primary: 'id' })
+}

package/src/handlers/commands.ts

@@ -0,0 +1,177 @@
+import { randomBytes } from 'node:crypto'
+import type { Context } from 'koishi'
+import type { Config } from '../config'
+import type { Actor, Command, Dashboard, IncomingMessage, MutatingCommand, Outcome } from '../types'
+import { GitHub } from '../services/github'
+import { Permissions } from '../services/permission'
+import { RepositoryResolver } from '../services/repository'
+import { Storage } from '../services/storage'
+import { MessageParser } from '../utils/parser'
+import { SerialQueue } from '../utils/lock'
+import { BridgeError, publicError, redact } from '../utils/errors'
+
+interface Confirmation { command: MutatingCommand; code: string; expires: number; actorId: string; groupId: string; repository: string }
+
+export class Bridge {
+  readonly repositories: RepositoryResolver
+  private readonly parser: MessageParser
+  private readonly permissions: Permissions
+  private readonly storage: Storage
+  private readonly github: GitHub
+  // One bounded queue serializes permission changes and state writes in this instance.
+  // It also prevents different bound groups racing against the same target.
+  private readonly queue = new SerialQueue()
+  private readonly confirmations = new Map<string, Confirmation>()
+
+  constructor(private readonly ctx: Context, readonly config: Config) {
+    this.repositories = new RepositoryResolver(config.bindings)
+    this.parser = new MessageParser(config)
+    this.permissions = new Permissions(ctx, config)
+    this.storage = new Storage(ctx, config)
+    this.github = new GitHub(ctx, config)
+  }
+
+  async dispose() {
+    this.queue.close()
+    this.github.dispose()
+    this.confirmations.clear()
+    await this.queue.drain()
+  }
+
+  private target(command: Command) {
+    if ('number' in command) return String(command.number)
+    if ('qq' in command) return command.qq
+    return ''
+  }
+
+  private async authorize(actor: Actor, command: Command) {
+    if (command.type.startsWith('admin-') && actor.source === 'qq' && !this.config.enableAdminCommands) {
+      throw new BridgeError('admin-disabled', '部署者已关闭 QQ 管理员指令，请使用后台管理。')
+    }
+    if (command.type !== 'comment') await this.permissions.requireAdmin(actor, command.type === 'admin-remove')
+  }
+
+  private async audited(actor: Actor, command: Command, task: () => Promise<Outcome>): Promise<string> {
+    const id = await this.storage.begin(actor, command.type, this.target(command))
+    try {
+      const outcome = await task()
+      const saved = await this.storage.finish(id, outcome.result || 'success', 'completed')
+      return outcome.message + (saved ? '' : '\n操作已完成，但审计结果更新失败；后台记录暂为 pending。')
+    } catch (error) {
+      const safe = publicError(error)
+      await this.storage.finish(id, safe.uncertain ? 'unknown' : 'failed', safe.code)
+      throw safe
+    }
+  }
+
+  private async perform(message: IncomingMessage, command: MutatingCommand): Promise<Outcome> {
+    await this.authorize(message.actor, command)
+    if (command.type === 'comment') return this.github.comment(message.repository, command.number, message.actor, command.body, message.eventKey)
+    if (command.type === 'close' || command.type === 'open') return this.github.state(message.repository, command.number, command.type === 'close' ? 'closed' : 'open')
+    if (command.type === 'admin-add') return this.permissions.add(message.actor, command.qq)
+    return this.permissions.remove(message.actor, command.qq)
+  }
+
+  private confirmKey(message: IncomingMessage) { return `${message.actor.qq}:${message.actor.groupId}` }
+
+  private pruneConfirmations() {
+    for (const [key, pending] of this.confirmations) if (pending.expires < Date.now()) this.confirmations.delete(key)
+  }
+
+  async handle(message: IncomingMessage): Promise<string | null> {
+    const command = this.parser.parse(message.text)
+    if (!command) return null
+    try {
+      const result = await this.queue.run(async () => {
+        if (Date.now() - message.timestamp > this.config.dedupWindow) return ''
+        if (!await this.storage.claim(message)) return ''
+        if (command.type === 'invalid') return command.message
+        this.pruneConfirmations()
+        if (command.type === 'confirm') {
+          const key = this.confirmKey(message)
+          const pending = this.confirmations.get(key)
+          if (!pending || pending.code !== command.code || pending.actorId !== message.actor.qq ||
+            pending.groupId !== message.actor.groupId || pending.repository !== message.repository.fullName) {
+            throw new BridgeError('confirmation', '确认码无效或已过期。请由原操作者在原群重新发起操作。')
+          }
+          // Consume before any asynchronous work; a failed / uncertain write cannot reuse it.
+          this.confirmations.delete(key)
+          return this.audited(message.actor, pending.command, () => this.perform(message, pending.command))
+        }
+        await this.storage.cooldown(message.actor.qq)
+        return this.audited(message.actor, command, async () => {
+          await this.authorize(message.actor, command)
+          if (command.type === 'admin-list') {
+            const admins = await this.permissions.list((command.page - 1) * 20, 21)
+            const rows = admins.slice(0, 20).map(row => `${row.qq}（添加者：${row.addedBy}；${row.createdAt.toISOString()}）`)
+            return { message: `超级管理员：${this.config.superAdmins.join('、')}\n普通管理员（第 ${command.page} 页）：\n${rows.join('\n') || '无'}${admins.length > 20 ? `\n下一页：${this.config.adminPrefix} list ${command.page + 1}` : ''}` }
+          }
+          if (command.type !== 'comment' && this.config.confirmHighRisk) {
+            if (this.confirmations.size >= 1000) throw new BridgeError('busy', '待确认操作过多，请稍后再试。')
+            const code = randomBytes(6).toString('hex')
+            this.confirmations.set(this.confirmKey(message), {
+              command, code, expires: Date.now() + this.config.confirmationTimeout,
+              actorId: message.actor.qq, groupId: message.actor.groupId, repository: message.repository.fullName,
+            })
+            const action = { close: '关闭', open: '重新打开', 'admin-add': '添加管理员', 'admin-remove': '撤销管理员' }[command.type]
+            return {
+              message: `待确认：${action} ${this.target(command)}${'number' in command ? `（${message.repository.fullName}）` : ''}。\n请在 ${this.config.confirmationTimeout / 1000} 秒内由 QQ ${message.actor.qq} 在本群发送：\n${this.config.adminPrefix} confirm ${code}`,
+              result: 'noop',
+            }
+          }
+          return this.perform(message, command)
+        })
+      })
+      return redact(result, this.config.token)
+    } catch (error) {
+      const safe = publicError(error)
+      // Do not give HTTP errors (including headers) to Koishi's logger.
+      this.ctx.logger('qq-github-bridge').warn('操作未完成，错误类别：%s', safe.code)
+      return redact(safe.message, this.config.token)
+    }
+  }
+
+  async dashboard(authenticate: () => Promise<Actor>, page: number): Promise<Dashboard> {
+    return this.queue.run(async () => {
+      await authenticate()
+      const rows = await this.permissions.list((page - 1) * 50, 51)
+      const audits = await this.ctx.database.get('qgh_audit', {}, { sort: { createdAt: 'desc', id: 'desc' }, limit: 100 })
+      return {
+        admins: rows.slice(0, 50).map(row => ({ ...row, createdAt: row.createdAt.toISOString() })),
+        hasMoreAdmins: rows.length > 50,
+        superAdmins: [...this.config.superAdmins],
+        bindings: this.config.bindings.map(b => ({ groupId: b.groupId, repository: `${b.owner}/${b.repo}`, enabled: b.enabled })),
+        audits: audits.map(row => ({ ...row, createdAt: row.createdAt.toISOString() })),
+        auditEnabled: this.config.auditEnabled, auditRetentionDays: this.config.auditRetentionDays,
+      }
+    })
+  }
+
+  async manage(authenticate: () => Promise<Actor>, action: 'add' | 'remove', qq: string) {
+    return this.queue.run(async () => {
+      const actor = await authenticate()
+      const command: Command = { type: action === 'add' ? 'admin-add' : 'admin-remove', qq }
+      return this.audited(actor, command, () => action === 'add' ? this.permissions.add(actor, qq) : this.permissions.remove(actor, qq))
+    })
+  }
+
+  async validateToken(authenticate: () => Promise<Actor>, groupId?: string) {
+    return this.queue.run(async () => {
+      await authenticate()
+      const repository = groupId ? this.repositories.resolve(groupId) : undefined
+      if (groupId && !repository) throw new BridgeError('binding', '所选群没有启用的仓库绑定。')
+      return this.github.validate(repository)
+    })
+  }
+
+  async cleanup() {
+    try {
+      await this.queue.run(async () => {
+        this.pruneConfirmations()
+        await this.storage.cleanup()
+      })
+    } catch {
+      this.ctx.logger('qq-github-bridge').warn('过期记录清理未完成，将在下一周期重试。')
+    }
+  }
+}

package/src/handlers/message.ts

@@ -0,0 +1,60 @@
+import { createHash } from 'node:crypto'
+import type { Session } from 'koishi'
+import { QQ_PATTERN } from '../config'
+import type { IncomingMessage } from '../types'
+import type { RepositoryResolver } from '../services/repository'
+
+/** Narrow subset of the trusted OneBot transport payload, not message-supplied JSON. */
+interface OneBotMessage {
+  post_type?: string
+  message_type?: string
+  sub_type?: string
+  anonymous?: unknown
+  self_id?: number | string
+  user_id?: number | string
+  group_id?: number | string
+  message_id?: number | string
+  time?: number
+  sender?: { user_id?: number | string; nickname?: string; card?: string }
+}
+
+function numericId(value: unknown): string | undefined {
+  if (typeof value === 'number' && !Number.isSafeInteger(value)) return
+  if (typeof value !== 'string' && typeof value !== 'number') return
+  const text = String(value)
+  if (QQ_PATTERN.test(text)) return text
+}
+
+export function readMessage(session: Session, resolver: RepositoryResolver, window: number, now = Date.now()): IncomingMessage | null {
+  // Satori 4 normalizes the legacy 'message' event to 'message-created' at dispatch.
+  if (session.platform !== 'onebot' || !['message', 'message-created'].includes(session.type) || session.isDirect || !session.guildId) return null
+  // setInternal('onebot', payload) is how the official OneBot adapter exposes raw events.
+  const raw = (session as Session & { onebot?: OneBotMessage }).onebot
+  if (!raw || raw.post_type !== 'message' || raw.message_type !== 'group' || raw.anonymous || raw.sub_type === 'anonymous') return null
+  const qq = numericId(raw.user_id)
+  const sender = numericId(raw.sender?.user_id)
+  const groupId = numericId(raw.group_id)
+  if (!qq || qq !== sender || qq !== session.userId || !groupId || groupId !== session.guildId || groupId !== session.channelId) return null
+  if (numericId(raw.self_id) !== session.selfId || qq === session.selfId) return null
+  if (session.bot.ctx.bots.some(bot => bot.platform === 'onebot' && bot.selfId === qq)) return null
+  const repository = resolver.resolve(groupId)
+  if (!repository) return null
+  const messageId = raw.message_id
+  if ((typeof messageId !== 'string' && typeof messageId !== 'number') ||
+    !/^-?[0-9]{1,30}$/.test(String(messageId)) || (typeof messageId === 'number' && !Number.isSafeInteger(messageId))) return null
+  if (String(messageId) !== session.messageId) return null
+  const timestamp = typeof raw.time === 'number' && Number.isSafeInteger(raw.time) ? raw.time * 1000 : 0
+  if (!timestamp || now - timestamp > window || timestamp - now > 60000) return null
+  // Parse decoded text elements, never serialized Satori markup or raw CQ codes.
+  // Attachments / quotes / mentions are ignored as a whole so nothing is silently discarded.
+  if (session.quote || !session.elements?.length || session.elements.some(element => element.type !== 'text')) return null
+  const text = session.elements.map(element => element.attrs.content as string).join('')
+  const eventKey = createHash('sha256').update(`onebot:${groupId}:${messageId}`).digest('hex')
+  return {
+    actor: {
+      source: 'qq', id: qq, qq, groupId, repository: repository.fullName,
+      nickname: raw.sender?.nickname || raw.sender?.card || qq,
+    },
+    repository, eventKey, timestamp, text,
+  }
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+import { Context, h } from 'koishi'
+import { Config, validateConfig } from './config'
+import { registerModels } from './database/models'
+import { registerConsole } from './console'
+import { Bridge } from './handlers/commands'
+import { readMessage } from './handlers/message'
+
+export { Config } from './config'
+export const name = 'qq-github-bridge'
+export const inject = ['database', 'http']
+export const usage = `
+通过 OneBot / NapCat QQ 群评论、关闭和重开 GitHub Issue / PR。
+
+1. 启用持久数据库（推荐 database-sqlite）、OneBot 适配器。
+2. 填写统一 GitHub Token、至少一位超级管理员、群与仓库绑定。
+3. 启用官方 console 和 auth，并用部署管理员账号登录，左侧即可打开「QQ GitHub Bridge」维护管理员、查看审计和验证 Token。
+
+默认高风险操作需要同一 QQ 在原群发送确认码。详细命令与权限说明见 README。
+`
+
+export function apply(ctx: Context, config: Config) {
+  validateConfig(config)
+  registerModels(ctx)
+  const bridge = new Bridge(ctx, config)
+  ctx.middleware(async (session, next) => {
+    const message = readMessage(session, bridge.repositories, config.dedupWindow)
+    if (!message) return next()
+    const reply = await bridge.handle(message)
+    if (reply === null) return next()
+    // Treat responses as literal text, so API links / database fields cannot inject CQ elements.
+    if (reply) return h.text(reply)
+  }, true)
+  registerConsole(ctx, bridge)
+  ctx.on('ready', () => bridge.cleanup())
+  ctx.setInterval(() => void bridge.cleanup(), 3600000)
+  ctx.on('dispose', () => bridge.dispose())
+}

package/src/rpc.ts

@@ -0,0 +1,10 @@
+import type { Client } from '@koishijs/plugin-console'
+import type { Dashboard, TokenStatus } from './types'
+
+declare module '@koishijs/console' {
+  interface Events {
+    'qq-github-bridge/dashboard'(this: Client, page?: number): Promise<Dashboard>
+    'qq-github-bridge/admin'(this: Client, action: 'add' | 'remove', qq: string): Promise<string>
+    'qq-github-bridge/validate'(this: Client, groupId?: string): Promise<TokenStatus>
+  }
+}