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

package/src/services/github.ts

@@ -0,0 +1,189 @@
+import { setTimeout as delay } from 'node:timers/promises'
+import type { Context } from 'koishi'
+import type { Config } from '../config'
+import type { Actor, Outcome, Repository, TokenStatus } from '../types'
+import { BridgeError, redact } from '../utils/errors'
+
+interface Issue { number: number; state: 'open' | 'closed'; html_url: string; pull_request?: unknown }
+interface Pull extends Issue { merged: boolean }
+
+function metadata(value: string): string {
+  return value.slice(0,80).replace(/[\r\n\u0000-\u001f\u007f-\u009f\u200b-\u200f\u202a-\u202e\u2066-\u2069]/g, ' ')
+    .replace(/[&<>"'`*_\[\]{}()|@#!\\]/g, character => `&#${character.codePointAt(0)};`)
+}
+
+export class GitHub {
+  private readonly abort = new AbortController()
+  private readonly base: string
+  private blockedUntil = 0
+  private lastMutation = 0
+
+  constructor(private readonly ctx: Context, private readonly config: Config) {
+    this.base = config.apiBaseUrl.replace(/\/+$/, '')
+  }
+
+  dispose() { this.abort.abort() }
+
+  private async sleep(ms: number) {
+    try { await delay(ms, undefined, { signal: this.abort.signal }) } catch {
+      throw new BridgeError('disposed', '插件正在停用，请稍后再试。')
+    }
+  }
+
+  private async request<T>(method: 'GET' | 'POST' | 'PATCH', path: string, data?: object): Promise<T> {
+    if (this.abort.signal.aborted) throw new BridgeError('disposed', '插件正在停用，请稍后再试。')
+    if (this.blockedUntil > Date.now()) throw new BridgeError('rate-limit', `GitHub 限流中，请在约 ${Math.ceil((this.blockedUntil - Date.now()) / 1000)} 秒后再试。`)
+    const writing = method !== 'GET'
+    if (writing) {
+      const wait = 1000 - (Date.now() - this.lastMutation)
+      if (wait > 0) await this.sleep(wait)
+      this.lastMutation = Date.now()
+    }
+    for (let attempt = 0; ; attempt++) {
+      let response: { status: number; data: unknown; headers: Headers }
+      try {
+        response = await this.ctx.http(this.base + path, {
+          method, data,
+          headers: {
+            Authorization: `Bearer ${this.config.token}`,
+            Accept: 'application/vnd.github+json',
+            'X-GitHub-Api-Version': this.config.apiVersion,
+            'User-Agent': 'koishi-plugin-qq-github-bridge/1.0.0',
+          },
+          timeout: this.config.requestTimeout,
+          signal: this.abort.signal,
+          // Never send credentials or execute writes at a redirected/unbound repository.
+          redirect: 'manual',
+          validateStatus: () => true,
+        })
+      } catch {
+        if (!writing && attempt < this.config.readRetries && !this.abort.signal.aborted) {
+          await this.sleep(300 * 2 ** attempt)
+          continue
+        }
+        throw new BridgeError(writing ? 'write-unknown' : 'network', writing
+          ? 'GitHub 写入请求未得到确认（网络超时、连接失败或插件停用）。操作可能已成功；请先到 GitHub 核对，不要直接重发。'
+          : '无法连接 GitHub（超时、DNS 或连接故障），请稍后重试或联系部署者。', writing)
+      }
+      if (response.status >= 200 && response.status < 300) return response.data as T
+      const status = response.status
+      const getHeader = (name: string) => response.headers?.get?.(name)
+      const serverMessage = (response.data as { message?: unknown } | null)?.message
+      const rateLimited = status === 429 || (status === 403 && (getHeader('x-ratelimit-remaining') === '0' ||
+        !!getHeader('retry-after') || (typeof serverMessage === 'string' && /rate limit|abuse/i.test(serverMessage))))
+      if (rateLimited) {
+        const retryHeader = getHeader('retry-after')
+        const seconds = Number(retryHeader)
+        const retryAt = retryHeader && !Number.isFinite(seconds) ? Date.parse(retryHeader) : Date.now() + seconds * 1000
+        const resetAt = getHeader('x-ratelimit-remaining') === '0' ? Number(getHeader('x-ratelimit-reset')) * 1000 : 0
+        this.blockedUntil = Math.max(Date.now() + 60000, Number.isFinite(retryAt) ? retryAt : 0, Number.isFinite(resetAt) ? resetAt : 0)
+        throw new BridgeError('rate-limit', 'GitHub 请求限流，已暂停后续请求，请稍后再试。')
+      }
+      if (status >= 500) {
+        if (!writing && attempt < this.config.readRetries) {
+          await this.sleep(300 * 2 ** attempt)
+          continue
+        }
+        throw new BridgeError(writing ? 'write-unknown' : 'github-server', writing
+          ? 'GitHub 服务端异常，写入结果无法确认。请先到 GitHub 核对，插件不会自动重试。'
+          : 'GitHub 服务端暂时异常，有限重试后仍未恢复。', writing)
+      }
+      const errors: Record<number, [string, string]> = {
+        401: ['token-invalid', 'GitHub Token 无效或已过期，请部署者在后台更新。'],
+        403: ['github-forbidden', 'GitHub 拒绝访问：Token 权限不足、仓库或组织访问受限；请部署者检查权限和组织审批。'],
+        404: ['not-found', 'GitHub 仓库或目标不存在，或当前 Token 无权访问。'],
+        410: ['gone', '目标功能或资源已不可用（例如仓库关闭了 Issues）。'],
+        422: ['validation', 'GitHub 拒绝请求：数据不合法、触发反滥用限制，或当前目标不允许此状态转换。请在 GitHub 核对目标状态和 PR 源分支。'],
+      }
+      if (status >= 300 && status < 400) throw new BridgeError('redirect', 'GitHub 返回重定向；为保持群绑定边界已停止请求，请部署者更新仓库绑定或 API 地址。')
+      const [code, message] = errors[status] || ['github-error', `GitHub 请求失败（HTTP ${status}）。请部署者检查配置。`]
+      throw new BridgeError(code, message)
+    }
+  }
+
+  private path(repo: Repository): string {
+    return `/repos/${encodeURIComponent(repo.owner)}/${encodeURIComponent(repo.repo)}`
+  }
+
+  private link(value: unknown): string | undefined {
+    if (typeof value !== 'string' || value.length > 2000 || value.includes(this.config.token)) return
+    try {
+      const url = new URL(value)
+      // html_url is returned by the trusted API, never used as a request target.
+      // Proxies / Enterprise Cloud can have a different API and web hostname.
+      if (url.username || url.password || url.search || decodeURIComponent(value).includes(this.config.token)) return
+      if (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname))) return
+      return url.href
+    } catch { return }
+  }
+
+  private async target(repo: Repository, number: number): Promise<Issue> {
+    const issue = await this.request<Issue>('GET', `${this.path(repo)}/issues/${number}`)
+    if (!issue || issue.number !== number || !['open', 'closed'].includes(issue.state)) {
+      throw new BridgeError('github-response', 'GitHub 返回了不符合预期的目标数据，已停止操作。')
+    }
+    return issue
+  }
+
+  formatComment(actor: Actor, body: string, eventKey: string): string {
+    if (body.includes(this.config.token)) throw new BridgeError('secret-in-body', '评论包含部署 Token，已拒绝发送。请移除敏感信息。')
+    const nickname = metadata(redact(actor.nickname, this.config.token))
+    const header = `<sub>QQ Bridge 已验证发送者 · 昵称：「${nickname}」 · QQ：${actor.qq} · QQ群：${actor.groupId}</sub>`
+    const comment = `${header}\n\n---\n\n${this.config.commentTemplate.replace('{body}', () => body)}\n\n<!-- qq-github-bridge:${eventKey} -->`
+    // GitHub imposes its own limit; also bound bytes to safely accommodate Unicode text.
+    if (comment.length > 65000 || Buffer.byteLength(comment, 'utf8') > 65000) {
+      throw new BridgeError('comment-too-large', '渲染后的评论过长，请缩短正文或评论模板。')
+    }
+    return comment
+  }
+
+  async comment(repo: Repository, number: number, actor: Actor, body: string, eventKey: string): Promise<Outcome> {
+    const comment = this.formatComment(actor, body, eventKey)
+    const issue = await this.target(repo, number)
+    const result = await this.request<{ id?: number; html_url?: unknown }>('POST', `${this.path(repo)}/issues/${number}/comments`, { body: comment })
+    const link = this.link(result?.html_url)
+    if (!link || !Number.isSafeInteger(result?.id) || result.id! <= 0) {
+      throw new BridgeError('write-unknown', 'GitHub 返回了成功状态，但评论标识或链接不完整，无法确认评论结果。请先到 GitHub 核对，不要直接重发。', true)
+    }
+    return {
+      message: `已在 ${repo.fullName} ${issue.pull_request ? 'PR' : 'Issue'} #${number} 发布评论。\n${link}`,
+      result: 'success',
+    }
+  }
+
+  async state(repo: Repository, number: number, desired: 'open' | 'closed'): Promise<Outcome> {
+    let target: Issue | Pull = await this.target(repo, number)
+    const isPR = !!target.pull_request
+    if (isPR) {
+      target = await this.request<Pull>('GET', `${this.path(repo)}/pulls/${number}`)
+      if (!target || target.number !== number || !['open', 'closed'].includes(target.state) || typeof (target as Pull).merged !== 'boolean') {
+        throw new BridgeError('github-response', 'GitHub 返回了不符合预期的 PR 状态，已停止操作。')
+      }
+      if (desired === 'open' && (target as Pull).merged) throw new BridgeError('pr-merged', '该 PR 已合并，不能重新打开。')
+    }
+    const label = `${repo.fullName} ${isPR ? 'PR' : 'Issue'} #${number}`
+    if (target.state === desired) return { message: `${label} 当前已经${desired === 'open' ? '打开' : '关闭'}，无需重复操作。`, result: 'noop' }
+    const updated = await this.request<Issue>('PATCH', `${this.path(repo)}/${isPR ? 'pulls' : 'issues'}/${number}`, { state: desired })
+    if (updated?.number !== number || updated?.state !== desired) {
+      throw new BridgeError('write-unknown', 'GitHub 未确认预期状态，操作结果不确定；请到 GitHub 核对。', true)
+    }
+    return { message: `已${desired === 'open' ? '重新打开' : '关闭'} ${label}。`, result: 'success' }
+  }
+
+  async validate(repo?: Repository): Promise<TokenStatus> {
+    const user = await this.request<{ login: string }>('GET', '/user')
+    if (!user || !/^[A-Za-z0-9][A-Za-z0-9-]{0,99}$/.test(user.login)) throw new BridgeError('github-response', 'Token 验证响应无效，请检查 API 地址。')
+    const repositories: TokenStatus['repositories'] = []
+    if (repo) {
+      try {
+        const data = await this.request<{ full_name: string }>('GET', this.path(repo))
+        if (data?.full_name?.toLowerCase() !== repo.fullName.toLowerCase()) throw new BridgeError('repo-mismatch', '仓库响应与群绑定不一致。')
+        repositories.push({ repository: repo.fullName, accessible: true, message: '仓库可读取。' })
+      } catch (error) {
+        if (!(error instanceof BridgeError)) throw error
+        repositories.push({ repository: repo.fullName, accessible: false, message: error.message })
+      }
+    }
+    return { login: redact(user.login, this.config.token), repositories, message: 'Token 身份已验证。只读检测不能证明写权限；Issues 和 Pull requests 均需 Read and write。' }
+  }
+}

package/src/services/permission.ts

@@ -0,0 +1,47 @@
+import type { Context } from 'koishi'
+import type { Config } from '../config'
+import { QQ_PATTERN } from '../config'
+import type { Actor, Outcome } from '../types'
+import { BridgeError } from '../utils/errors'
+
+export class Permissions {
+  private readonly superAdmins: Set<string>
+  constructor(private readonly ctx: Context, config: Config) {
+    this.superAdmins = new Set(config.superAdmins)
+  }
+
+  async requireAdmin(actor: Actor, superOnly = false) {
+    // Console actors are constructed only after a fresh authenticated deployer check.
+    if (actor.source === 'console') return
+    if (this.superAdmins.has(actor.qq)) return
+    if (superOnly) throw new BridgeError('forbidden', '只有超级管理员可以撤销管理员权限。')
+    const [admin] = await this.ctx.database.get('qgh_admin', actor.qq)
+    if (!admin) throw new BridgeError('forbidden', '此操作需要 GitHub Bridge 管理员权限。')
+  }
+
+  async add(actor: Actor, qq: string): Promise<Outcome> {
+    await this.requireAdmin(actor)
+    if (!QQ_PATTERN.test(qq)) throw new BridgeError('qq', '请输入有效的数字 QQ 号。')
+    if (this.superAdmins.has(qq)) return { message: `${qq} 已是后台配置的超级管理员。`, result: 'noop' }
+    const [existing] = await this.ctx.database.get('qgh_admin', qq)
+    if (existing) return { message: `${qq} 已是管理员，无需重复添加。`, result: 'noop' }
+    await this.ctx.database.create('qgh_admin', {
+      qq, addedBy: actor.source === 'console' ? `console:${actor.id}` : actor.qq, createdAt: new Date(),
+    })
+    return { message: `已添加管理员 ${qq}，权限立即生效。`, result: 'success' }
+  }
+
+  async remove(actor: Actor, qq: string): Promise<Outcome> {
+    await this.requireAdmin(actor, true)
+    if (!QQ_PATTERN.test(qq)) throw new BridgeError('qq', '请输入有效的数字 QQ 号。')
+    if (this.superAdmins.has(qq)) throw new BridgeError('super-admin', '超级管理员只能通过插件后台配置修改，不能在管理员列表或 QQ 指令中撤销。')
+    const [existing] = await this.ctx.database.get('qgh_admin', qq)
+    if (!existing) return { message: `${qq} 当前不是管理员。`, result: 'noop' }
+    await this.ctx.database.remove('qgh_admin', qq)
+    return { message: `已撤销管理员 ${qq}。此前由其添加的其他管理员保持不变。`, result: 'success' }
+  }
+
+  async list(offset = 0, limit = 50) {
+    return this.ctx.database.get('qgh_admin', {}, { sort: { createdAt: 'asc', qq: 'asc' }, offset, limit })
+  }
+}

package/src/services/repository.ts

@@ -0,0 +1,22 @@
+import type { Binding } from '../config'
+import type { Repository } from '../types'
+
+export class RepositoryResolver {
+  private readonly groups = new Map<string, Repository>()
+
+  constructor(bindings: Binding[]) {
+    for (const item of bindings) {
+      if (item.enabled) this.groups.set(item.groupId, {
+        owner: item.owner,
+        repo: item.repo,
+        fullName: `${item.owner}/${item.repo}`,
+      })
+    }
+  }
+
+  resolve(groupId: string): Repository | undefined { return this.groups.get(groupId) }
+
+  all(): Repository[] {
+    return [...new Map([...this.groups.values()].map(repo => [repo.fullName.toLowerCase(), repo])).values()]
+  }
+}

package/src/services/storage.ts

@@ -0,0 +1,67 @@
+import { randomUUID } from 'node:crypto'
+import type { Context } from 'koishi'
+import type { Config } from '../config'
+import type { Actor, IncomingMessage } from '../types'
+import { BridgeError } from '../utils/errors'
+
+export class Storage {
+  constructor(private readonly ctx: Context, private readonly config: Config) {}
+
+  async claim(message: IncomingMessage): Promise<boolean> {
+    // The primary key is the atomic claim, including across reconnects / plugin reloads.
+    const [existing] = await this.ctx.database.get('qgh_event', message.eventKey)
+    if (existing) return false
+    try {
+      await this.ctx.database.create('qgh_event', {
+        id: message.eventKey,
+        // Allow clock skew and avoid cleanup racing a still-valid incoming event.
+        expiresAt: new Date(Math.max(Date.now(), message.timestamp) + this.config.dedupWindow + 60000),
+      })
+      return true
+    } catch {
+      const [winner] = await this.ctx.database.get('qgh_event', message.eventKey)
+      if (winner) return false
+      throw new BridgeError('database', '数据库去重记录写入失败，未执行操作。')
+    }
+  }
+
+  async cooldown(qq: string) {
+    if (!this.config.userCooldown) return
+    const [existing] = await this.ctx.database.get('qgh_cooldown', qq)
+    const now = Date.now()
+    if (existing && +existing.expiresAt > now) {
+      throw new BridgeError('cooldown', `操作过于频繁，请在 ${Math.ceil((+existing.expiresAt - now) / 1000)} 秒后重试。`)
+    }
+    await this.ctx.database.upsert('qgh_cooldown', [{ qq, expiresAt: new Date(now + this.config.userCooldown) }])
+  }
+
+  async begin(actor: Actor, action: string, target: string): Promise<string | undefined> {
+    if (!this.config.auditEnabled) return
+    const id = randomUUID()
+    await this.ctx.database.create('qgh_audit', {
+      id, actorId: actor.id, actorQQ: actor.qq, source: actor.source, action, target,
+      groupId: actor.groupId, repository: actor.repository, createdAt: new Date(),
+      result: 'pending', detail: '',
+    })
+    return id
+  }
+
+  async finish(id: string | undefined, result: string, detail: string): Promise<boolean> {
+    if (!id) return true
+    try {
+      // detail is an internal error code or constant, never exception text / API response data.
+      await this.ctx.database.set('qgh_audit', id, { result, detail })
+      return true
+    } catch {
+      this.ctx.logger('qq-github-bridge').warn('审计结果写入失败，原始记录保留为 pending；请核对操作结果。')
+      return false
+    }
+  }
+
+  async cleanup() {
+    const now = Date.now()
+    await this.ctx.database.remove('qgh_event', { expiresAt: { $lt: new Date(now) } })
+    await this.ctx.database.remove('qgh_cooldown', { expiresAt: { $lt: new Date(now) } })
+    await this.ctx.database.remove('qgh_audit', { createdAt: { $lt: new Date(now - this.config.auditRetentionDays * 86400000) } })
+  }
+}

package/src/types.ts

@@ -0,0 +1,75 @@
+export interface Repository {
+  owner: string
+  repo: string
+  fullName: string
+}
+
+export interface Actor {
+  source: 'qq' | 'console'
+  id: string
+  qq: string
+  nickname: string
+  groupId: string
+  repository: string
+}
+
+export interface IncomingMessage {
+  actor: Actor
+  repository: Repository
+  eventKey: string
+  timestamp: number
+  text: string
+}
+
+export type Command =
+  | { type: 'comment'; number: number; body: string }
+  | { type: 'close'; number: number }
+  | { type: 'open'; number: number }
+  | { type: 'admin-add'; qq: string }
+  | { type: 'admin-remove'; qq: string }
+  | { type: 'admin-list'; page: number }
+  | { type: 'confirm'; code: string }
+  | { type: 'invalid'; message: string }
+
+export type MutatingCommand = Exclude<Command, { type: 'invalid' | 'confirm' | 'admin-list' }>
+
+export interface Outcome {
+  message: string
+  result?: 'success' | 'noop'
+}
+
+export interface AdminView {
+  qq: string
+  addedBy: string
+  createdAt: string
+}
+
+export interface AuditView {
+  id: string
+  actorId: string
+  actorQQ: string
+  source: string
+  action: string
+  target: string
+  groupId: string
+  repository: string
+  createdAt: string
+  result: string
+  detail: string
+}
+
+export interface Dashboard {
+  admins: AdminView[]
+  hasMoreAdmins: boolean
+  superAdmins: string[]
+  bindings: Array<{ groupId: string; repository: string; enabled: boolean }>
+  audits: AuditView[]
+  auditEnabled: boolean
+  auditRetentionDays: number
+}
+
+export interface TokenStatus {
+  login: string
+  repositories: Array<{ repository: string; accessible: boolean; message: string }>
+  message: string
+}

package/src/utils/errors.ts

@@ -0,0 +1,18 @@
+/** Only deliberately authored messages may cross the chat / console boundary. */
+export class BridgeError extends Error {
+  constructor(public readonly code: string, message: string, public readonly uncertain = false) {
+    super(message)
+    this.name = 'BridgeError'
+  }
+}
+
+export function publicError(error: unknown): BridgeError {
+  return error instanceof BridgeError
+    ? error
+    : new BridgeError('internal', '内部服务或数据库暂不可用，操作未能确认完成。请联系部署者检查服务。')
+}
+
+export function redact(text: string, token: string): string {
+  if (token) text = text.split(token).join('[已隐藏敏感信息]')
+  return text.replace(/(?:gh[pousr]_[A-Za-z0-9_]+|github_pat_[A-Za-z0-9_]+)/g, '[已隐藏敏感信息]')
+}

package/src/utils/lock.ts

@@ -0,0 +1,30 @@
+import { BridgeError } from './errors'
+
+/** Bounded, instance-owned queue. A rejected task never poisons the next one. */
+export class SerialQueue {
+  private tail: Promise<void> = Promise.resolve()
+  private pending = 0
+  private closed = false
+
+  constructor(private readonly capacity = 64) {}
+
+  async run<T>(task: () => Promise<T>): Promise<T> {
+    if (this.closed) throw new BridgeError('disposed', '插件正在停用，请稍后再试。')
+    if (this.pending >= this.capacity) throw new BridgeError('busy', '当前操作较多，请稍后再试。')
+    this.pending++
+    const previous = this.tail
+    let release!: () => void
+    this.tail = new Promise<void>(resolve => { release = resolve })
+    try {
+      await previous
+      if (this.closed) throw new BridgeError('disposed', '插件正在停用，请稍后再试。')
+      return await task()
+    } finally {
+      this.pending--
+      release()
+    }
+  }
+
+  close() { this.closed = true }
+  drain() { return this.tail }
+}

package/src/utils/parser.ts

@@ -0,0 +1,71 @@
+import { RE2 } from 're2-wasm'
+import type { Config } from '../config'
+import { QQ_PATTERN } from '../config'
+import type { Command } from '../types'
+import { BridgeError } from './errors'
+
+export class MessageParser {
+  private readonly reply: RE2
+
+  constructor(private readonly config: Config) {
+    const pattern = config.replyPattern || `^${config.replyPrefix}(?<number>\\d+)\\s+(?<body>[\\s\\S]+)$`
+    if (pattern.length > 1024 || !pattern.startsWith('^') || !pattern.endsWith('$') ||
+      !pattern.includes('(?<number>') || !pattern.includes('(?<body>')) {
+      throw new BridgeError('config-regex', '回复正则最多 1024 字符，须使用 ^ 和 $ 全文匹配，并声明 number 和 body 命名捕获组。')
+    }
+    try { this.reply = new RE2(pattern, 'u') } catch {
+      // Never expose the pattern: a misconfigured pattern could itself contain secrets.
+      throw new BridgeError('config-regex', '回复正则无效或使用了 RE2 不支持的语法（如回溯引用、前后查找）。')
+    }
+  }
+
+  parse(text: string): Command | null {
+    if (text.length > this.config.maxCommentLength + 4096) return null
+    const { adminPrefix, closePrefix, openPrefix } = this.config
+    // Reserve privileged command namespaces before trying any custom comment expression.
+    if (text.startsWith(adminPrefix) && /^(?:\s|$)/.test(text.slice(adminPrefix.length))) {
+      const parts = text.split(/\s+/)
+      if (parts[1] === 'confirm' && parts.length === 3 && /^[a-f0-9]{12}$/.test(parts[2])) {
+        return { type: 'confirm', code: parts[2] }
+      }
+      if (parts[1] === 'list' && (parts.length === 2 || (parts.length === 3 && /^[1-9][0-9]{0,5}$/.test(parts[2])))) {
+        return { type: 'admin-list', page: parts[2] ? Number(parts[2]) : 1 }
+      }
+      if (parts.length === 3 && QQ_PATTERN.test(parts[2])) {
+        if (parts[1] === 'add') return { type: 'admin-add', qq: parts[2] }
+        if (parts[1] === 'remove') return { type: 'admin-remove', qq: parts[2] }
+      }
+      return { type: 'invalid', message: `用法：${adminPrefix} add/remove QQ号；${adminPrefix} list [页码]；${adminPrefix} confirm 确认码。` }
+    }
+    for (const [prefix, type] of [[closePrefix, 'close'], [openPrefix, 'open']] as const) {
+      if (!text.startsWith(prefix)) continue
+      const suffix = text.slice(prefix.length)
+      // Ordinary words starting with the prefix are not commands.
+      if (suffix && !/^[0-9\s]/.test(suffix)) continue
+      const number = this.number(suffix)
+      return number ? { type, number } : { type: 'invalid', message: `用法：${prefix}1003（编号须为正整数）。` }
+    }
+    const match = this.reply.exec(text)
+    // An alternative branch or a terminal newline must not defeat full matching.
+    if (match && match.index === 0 && match[0] === text) {
+      const number = this.number(match.groups?.number)
+      const body = match.groups?.body
+      if (!number) return { type: 'invalid', message: 'Issue / PR 编号必须是有效的正整数。' }
+      if (!body?.trim()) return { type: 'invalid', message: '评论正文不能为空。' }
+      if (body.length > this.config.maxCommentLength) return { type: 'invalid', message: `评论过长，最多 ${this.config.maxCommentLength} 字符。` }
+      if (!this.config.allowMultiline && /[\r\n]/.test(body)) return { type: 'invalid', message: '当前配置不允许多行评论。' }
+      if (/\u0000/.test(body)) return { type: 'invalid', message: '评论包含不支持的空字符。' }
+      return { type: 'comment', number, body }
+    }
+    if (!this.config.replyPattern && new RegExp(`^${this.config.replyPrefix}[0-9]+\\s*$`).test(text)) {
+      return { type: 'invalid', message: '评论正文不能为空。' }
+    }
+    return null
+  }
+
+  private number(value?: string): number | undefined {
+    if (!value || !/^[1-9][0-9]*$/.test(value)) return
+    const number = Number(value)
+    if (Number.isSafeInteger(number)) return number
+  }
+}