@fg-lab/amadeus-qq 0.0.0-stage → 1.2.1

package/src/lease.js

@@ -0,0 +1,42 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { randomUUID } from 'node:crypto'
+
+function processExists(pid) {
+  if (!Number.isSafeInteger(pid) || pid < 1) return false
+  try { process.kill(pid, 0); return true } catch (error) { return error?.code === 'EPERM' }
+}
+
+export function acquireInstanceLease(stateFile) {
+  if (typeof stateFile !== 'string' || !path.isAbsolute(stateFile)) throw new TypeError('stateFile must be absolute')
+  const file = `${stateFile}.lock`
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 })
+  const token = randomUUID()
+  const record = JSON.stringify({ pid: process.pid, token, acquiredAt: Date.now() })
+  let fd
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      fd = fs.openSync(file, 'wx', 0o600)
+      break
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error
+      let existing
+      try { existing = JSON.parse(fs.readFileSync(file, 'utf8')) } catch { throw new Error('QQ_INSTANCE_LOCKED: unreadable lock requires manual inspection') }
+      if (processExists(existing.pid)) throw new Error('QQ_INSTANCE_LOCKED: another QQ sender is active')
+      if (attempt > 0) throw new Error('QQ_INSTANCE_LOCKED: could not acquire after stale lock cleanup')
+      // Only a dead process's lock is removed; wx still arbitrates the new owner.
+      fs.unlinkSync(file)
+    }
+  }
+  if (fd === undefined) throw new Error('QQ_INSTANCE_LOCKED')
+  try { fs.writeFileSync(fd, record); fs.fsyncSync(fd) } finally { fs.closeSync(fd) }
+  let released = false
+  return () => {
+    if (released) return
+    released = true
+    try {
+      const current = JSON.parse(fs.readFileSync(file, 'utf8'))
+      if (current.token === token) fs.unlinkSync(file)
+    } catch { /* never remove a lock that cannot be verified as ours */ }
+  }
+}

package/src/media.js

@@ -0,0 +1,246 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { normalizeMessageId } from './storage.js'
+import { sanitizeInboundSegments } from './onebot.js'
+
+const MAX_IMAGE_BYTES = 5 * 1024 * 1024
+const MAX_RESPONSE_BYTES = 32 * 1024 * 1024
+const MAX_BASE64_CHARS = Math.ceil(MAX_IMAGE_BYTES / 3) * 4
+const READ_TIMEOUT_MS = 5_000
+const PLATFORM_TIMEOUT_MS = 10_000
+
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+const JPEG_SIGNATURE = Buffer.from([0xff, 0xd8, 0xff])
+
+function mediaError(code) {
+  const error = new Error(code)
+  error.code = code
+  return error
+}
+
+function permissionError(code = 'QQ_PERMISSION_DENIED') {
+  return mediaError(`${code}: qq.media.read`)
+}
+
+function assertMediaRead(core, sessionId, changed = false) {
+  let allowed = false
+  try {
+    allowed = core.authorizeSessionCapability(sessionId, 'qq.media.read') === true
+  } catch {
+    allowed = false
+  }
+  if (!allowed) throw permissionError(changed ? 'QQ_PERMISSION_CHANGED' : 'QQ_PERMISSION_DENIED')
+}
+
+function resolveMediaRoot(mediaRoot) {
+  if (typeof mediaRoot !== 'string' || !path.isAbsolute(mediaRoot)) throw mediaError('QQ_MEDIA_ROOT_INVALID')
+  let root
+  try {
+    root = fs.realpathSync(mediaRoot)
+    if (!fs.statSync(root).isDirectory()) throw new Error('not a directory')
+  } catch {
+    throw mediaError('QQ_MEDIA_ROOT_INVALID')
+  }
+  return root
+}
+
+function resolveLocalImage(file, root, mediaRoot) {
+  if (typeof file !== 'string' || file.length === 0 || file.includes('\u0000')) throw mediaError('QQ_MEDIA_PATH_INVALID')
+  // Reject UNC paths and URI schemes. A Windows drive path is the only
+  // scheme-like form accepted, and it must still be absolute.
+  if (/^[\\/]{2}/.test(file)) throw mediaError('QQ_MEDIA_PATH_INVALID')
+  if (!/^[A-Za-z]:[\\/]/.test(file) && /^[A-Za-z][A-Za-z0-9+.-]*:/.test(file)) throw mediaError('QQ_MEDIA_PATH_INVALID')
+  if (!path.isAbsolute(file)) throw mediaError('QQ_MEDIA_PATH_INVALID')
+  const lexical = path.relative(mediaRoot, file)
+  if (lexical === '' || lexical === '..' || lexical.startsWith(`..${path.sep}`) || path.isAbsolute(lexical)) {
+    throw mediaError('QQ_MEDIA_PATH_OUTSIDE_ROOT')
+  }
+
+  let entry
+  try {
+    entry = fs.lstatSync(file)
+  } catch {
+    throw mediaError('QQ_MEDIA_PATH_INVALID')
+  }
+  if (entry.isSymbolicLink() || !entry.isFile()) throw mediaError('QQ_MEDIA_PATH_INVALID')
+
+  let real
+  try {
+    real = fs.realpathSync(file)
+  } catch {
+    throw mediaError('QQ_MEDIA_PATH_INVALID')
+  }
+  const relative = path.relative(root, real)
+  if (relative === '' || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw mediaError('QQ_MEDIA_PATH_OUTSIDE_ROOT')
+  }
+
+  // A link anywhere on the submitted path makes the accepted object
+  // ambiguous. Check the lexical path below mediaRoot as well as the resolved
+  // path; realpath containment separately rejects any link that escapes root.
+  let cursor = mediaRoot
+  for (const part of lexical.split(path.sep)) {
+    cursor = path.join(cursor, part)
+    try {
+      if (fs.lstatSync(cursor).isSymbolicLink()) throw mediaError('QQ_MEDIA_PATH_INVALID')
+    } catch (error) {
+      if (error.code === 'QQ_MEDIA_PATH_INVALID') throw error
+      throw mediaError('QQ_MEDIA_PATH_INVALID')
+    }
+  }
+  return real
+}
+
+function sniffImageMediaType(data) {
+  if (data.length >= PNG_SIGNATURE.length && data.subarray(0, PNG_SIGNATURE.length).equals(PNG_SIGNATURE)) return 'image/png'
+  if (data.length >= JPEG_SIGNATURE.length && data.subarray(0, JPEG_SIGNATURE.length).equals(JPEG_SIGNATURE)) return 'image/jpeg'
+  if (data.length >= 6) {
+    const header = data.subarray(0, 6).toString('latin1')
+    if (header === 'GIF87a' || header === 'GIF89a') return 'image/gif'
+  }
+  if (data.length >= 12 &&
+    data.subarray(0, 4).toString('latin1') === 'RIFF' &&
+    data.subarray(8, 12).toString('latin1') === 'WEBP') return 'image/webp'
+  return null
+}
+
+function withTimeout(promise, timeoutMs, code) {
+  let timer
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(mediaError(code)), timeoutMs)
+    timer.unref?.()
+  })
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer))
+}
+
+async function readBoundedImage(file) {
+  let handle
+  try {
+    handle = await fs.promises.open(file, 'r')
+    const stats = await handle.stat()
+    if (!stats.isFile()) throw mediaError('QQ_MEDIA_READ_FAILED')
+    if (stats.size <= 0) throw mediaError('QQ_MEDIA_EMPTY')
+    if (stats.size > MAX_IMAGE_BYTES) throw mediaError('QQ_MEDIA_TOO_LARGE')
+    const data = Buffer.alloc(stats.size)
+    let offset = 0
+    while (offset < data.length) {
+      const { bytesRead } = await handle.read(data, offset, data.length - offset, offset)
+      if (bytesRead <= 0) throw mediaError('QQ_MEDIA_READ_FAILED')
+      offset += bytesRead
+    }
+    return data
+  } catch (error) {
+    if (typeof error?.code === 'string' && error.code.startsWith('QQ_MEDIA_')) throw error
+    throw mediaError('QQ_MEDIA_READ_FAILED')
+  } finally {
+    if (handle) await handle.close().catch(() => {})
+  }
+}
+
+function decodeInlineImage(value) {
+  if (typeof value !== 'string' || value.length === 0) throw mediaError('QQ_MEDIA_INLINE_INVALID')
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(value) || /^data:/i.test(value)) {
+    throw mediaError('QQ_MEDIA_INLINE_INVALID')
+  }
+  if (value.length > MAX_BASE64_CHARS) throw mediaError('QQ_MEDIA_INLINE_TOO_LARGE')
+  let data
+  try { data = Buffer.from(value, 'base64') } catch { throw mediaError('QQ_MEDIA_INLINE_INVALID') }
+  if (data.length === 0) throw mediaError('QQ_MEDIA_INLINE_INVALID')
+  if (data.length > MAX_IMAGE_BYTES) throw mediaError('QQ_MEDIA_INLINE_TOO_LARGE')
+  if (data.toString('base64') !== value) throw mediaError('QQ_MEDIA_INLINE_INVALID')
+  return data
+}
+
+/**
+ * Read one inbound QQ image through the bound Scene and hand bounded bytes to
+ * the official attachment service. The model supplies only messageId and an
+ * image ordinal; Scene, file handle, and local path never come from model args.
+ */
+export async function readMessageImage({
+  core,
+  store,
+  transport,
+  attachments,
+  mediaRoot,
+  sessionId,
+  messageId,
+  index = 0,
+}) {
+  if (!Number.isSafeInteger(index) || index < 0) throw mediaError('QQ_MEDIA_INDEX_INVALID')
+  if (!attachments || typeof attachments.saveImage !== 'function') throw mediaError('QQ_MEDIA_ATTACHMENTS_UNAVAILABLE')
+  if (!transport || typeof transport.action !== 'function') throw mediaError('QQ_MEDIA_BACKEND_UNAVAILABLE')
+  if (transport.status !== undefined && transport.status !== 'connected') throw mediaError('QQ_MEDIA_BACKEND_UNAVAILABLE')
+
+  let scene
+  try {
+    scene = core.authorizedScene(sessionId)
+  } catch {
+    throw permissionError('QQ_PERMISSION_DENIED')
+  }
+  assertMediaRead(core, sessionId)
+
+  const root = resolveMediaRoot(mediaRoot)
+
+  let id
+  try {
+    id = normalizeMessageId(messageId, 'messageId')
+  } catch {
+    throw mediaError('QQ_MEDIA_MESSAGE_INVALID')
+  }
+  const row = store.getScene(scene)
+  const message = row?.messages?.find(item => item.messageId === id)
+  if (!message) throw mediaError('QQ_MESSAGE_SCOPE')
+
+  let segments
+  try {
+    segments = sanitizeInboundSegments(message.segments)
+  } catch {
+    throw mediaError('QQ_MEDIA_MESSAGE_INVALID')
+  }
+  const image = segments.filter(segment => segment.type === 'image')[index]
+  const file = image?.data?.file
+  if (typeof file !== 'string' || file.length === 0) throw mediaError('QQ_MEDIA_UNAVAILABLE')
+
+  let response
+  try {
+    response = await transport.action('get_image', { file }, PLATFORM_TIMEOUT_MS, MAX_RESPONSE_BYTES)
+  } catch (error) {
+    throw mediaError(error?.code === 'ONEBOT_RESPONSE_TOO_LARGE'
+      ? 'QQ_MEDIA_RESPONSE_TOO_LARGE'
+      : 'QQ_MEDIA_BACKEND_UNAVAILABLE')
+  }
+
+  // The platform call is the last unbounded external step: a Scene revocation
+  // while it was in flight must stop path access and attachment admission.
+  assertMediaRead(core, sessionId, true)
+  if (!response || typeof response !== 'object' || Array.isArray(response)) {
+    throw mediaError('QQ_MEDIA_LOCAL_FILE_UNAVAILABLE')
+  }
+
+  let data
+  if (typeof response.file === 'string') {
+    const localFile = resolveLocalImage(response.file, root, mediaRoot)
+    data = await withTimeout(readBoundedImage(localFile), READ_TIMEOUT_MS, 'QQ_MEDIA_TIMEOUT')
+  } else if (typeof response.base64 === 'string') {
+    data = decodeInlineImage(response.base64)
+  } else {
+    throw mediaError('QQ_MEDIA_LOCAL_FILE_UNAVAILABLE')
+  }
+  const mediaType = sniffImageMediaType(data)
+  if (mediaType === null) throw mediaError('QQ_MEDIA_UNSUPPORTED_IMAGE')
+
+  assertMediaRead(core, sessionId, true)
+  let attachment
+  try {
+    attachment = await attachments.saveImage({ data, mediaType })
+  } catch {
+    throw mediaError('QQ_MEDIA_ATTACHMENT_REJECTED')
+  }
+  // Host admission can itself be asynchronous. A revocation during that wait
+  // must not hand the image block to the Agent, even if the Host cached bytes.
+  assertMediaRead(core, sessionId, true)
+  if (!attachment || typeof attachment !== 'object' || typeof attachment.attachmentId !== 'string') {
+    throw mediaError('QQ_MEDIA_ATTACHMENT_INVALID')
+  }
+  return { attachment }
+}

package/src/napcat-action-names.js

@@ -0,0 +1,186 @@
+// API identifiers inventoried from the installed local NapCat bundle on 2026-10-26.
+// Presence in the bundle does not prove that the currently running backend supports an action.
+export const NAPCAT_ACTION_NAMES = Object.freeze([
+  "_del_group_notice",
+  "_get_group_notice",
+  "_get_model_show",
+  "_mark_all_as_read",
+  "_send_group_notice",
+  "_set_model_show",
+  ".get_word_slices",
+  ".handle_quick_operation",
+  ".ocr_image",
+  "add_custom_face",
+  "ArkShareGroup",
+  "ArkSharePeer",
+  "bot_exit",
+  "can_send_image",
+  "can_send_record",
+  "cancel_group_album_media_like",
+  "cancel_group_todo",
+  "cancel_online_file",
+  "check_url_safely",
+  "clean_cache",
+  "clean_stream_temp_file",
+  "click_inline_keyboard_button",
+  "complete_group_todo",
+  "create_collection",
+  "create_flash_task",
+  "create_group_file_folder",
+  "del_group_album_media",
+  "delete_custom_face",
+  "delete_essence_msg",
+  "delete_friend",
+  "delete_group_file",
+  "delete_group_folder",
+  "delete_msg",
+  "delete_qzone_msg",
+  "do_group_album_comment",
+  "download_file",
+  "download_file_image_stream",
+  "download_file_record_stream",
+  "download_file_stream",
+  "download_fileset",
+  "fetch_custom_face",
+  "fetch_custom_face_detail",
+  "fetch_emoji_like",
+  "fetch_ptt_text",
+  "forward_friend_single_msg",
+  "forward_group_single_msg",
+  "friend_poke",
+  "get_ai_characters",
+  "get_ai_record",
+  "get_clientkey",
+  "get_collection_list",
+  "get_cookies",
+  "get_credentials",
+  "get_csrf_token",
+  "get_doubt_friends_add_request",
+  "get_emoji_likes",
+  "get_essence_msg_list",
+  "get_file",
+  "get_fileset_id",
+  "get_fileset_info",
+  "get_flash_file_list",
+  "get_flash_file_url",
+  "get_forward_msg",
+  "get_friend_list",
+  "get_friend_msg_history",
+  "get_friends_with_category",
+  "get_group_album_media_list",
+  "get_group_at_all_remain",
+  "get_group_detail_info",
+  "get_group_file_system_info",
+  "get_group_file_url",
+  "get_group_files_by_folder",
+  "get_group_honor_info",
+  "get_group_ignore_add_request",
+  "get_group_ignored_notifies",
+  "get_group_info",
+  "get_group_info_ex",
+  "get_group_list",
+  "get_group_member_info",
+  "get_group_member_list",
+  "get_group_msg_history",
+  "get_group_root_files",
+  "get_group_share_link",
+  "get_group_shut_list",
+  "get_group_signed_list",
+  "get_group_system_msg",
+  "get_guild_list",
+  "get_guild_service_profile",
+  "get_image",
+  "get_login_info",
+  "get_mini_app_ark",
+  "get_msg",
+  "get_online_clients",
+  "get_online_file_msg",
+  "get_private_file_url",
+  "get_profile_like",
+  "get_qun_album_list",
+  "get_recent_contact",
+  "get_record",
+  "get_rkey",
+  "get_rkey_server",
+  "get_robot_uin_range",
+  "get_share_link",
+  "get_status",
+  "get_stranger_info",
+  "get_unidirectional_friend_list",
+  "get_version_info",
+  "group_poke",
+  "mark_group_msg_as_read",
+  "mark_msg_as_read",
+  "mark_private_msg_as_read",
+  "move_group_file",
+  "nc_get_packet_status",
+  "nc_get_rkey",
+  "nc_get_user_status",
+  "ocr_image",
+  "receive_online_file",
+  "refuse_online_file",
+  "rename_group_file",
+  "send_ark_share",
+  "send_flash_msg",
+  "send_forward_msg",
+  "send_group_ai_record",
+  "send_group_ark_share",
+  "send_group_forward_msg",
+  "send_group_msg",
+  "send_group_sign",
+  "send_like",
+  "send_msg",
+  "send_online_file",
+  "send_online_folder",
+  "send_packet",
+  "send_poke",
+  "send_private_forward_msg",
+  "send_private_msg",
+  "send_qzone_msg",
+  "set_custom_face_desc",
+  "set_diy_online_status",
+  "set_doubt_friends_add_request",
+  "set_essence_msg",
+  "set_friend_add_request",
+  "set_friend_remark",
+  "set_group_add_option",
+  "set_group_add_request",
+  "set_group_admin",
+  "set_group_album_media_like",
+  "set_group_ban",
+  "set_group_card",
+  "set_group_kick",
+  "set_group_kick_members",
+  "set_group_leave",
+  "set_group_member_invite_policy",
+  "set_group_member_permissions",
+  "set_group_name",
+  "set_group_new_member_history_visibility",
+  "set_group_portrait",
+  "set_group_remark",
+  "set_group_robot_add_option",
+  "set_group_search",
+  "set_group_sign",
+  "set_group_special_title",
+  "set_group_todo",
+  "set_group_whole_ban",
+  "set_input_status",
+  "set_msg_emoji_like",
+  "set_online_status",
+  "set_qq_avatar",
+  "set_qq_profile",
+  "set_restart",
+  "set_self_longnick",
+  "test_auto_register_01",
+  "test_auto_register_02",
+  "test_download_stream",
+  "trans_group_file",
+  "translate_en2zh",
+  "unknown",
+  "upload_file_stream",
+  "upload_group_file",
+  "upload_image_to_qun_album",
+  "upload_images_to_qun_album",
+  "upload_private_file",
+  "upload_video_to_qun_album",
+])

package/src/native-asr.js

@@ -0,0 +1,112 @@
+import { normalizeMessageId } from './storage.js'
+import { sanitizeInboundSegments } from './onebot.js'
+
+const MAX_TRANSCRIPT_CHARS = 4000
+const MAX_RESPONSE_BYTES = 64 * 1024
+const PLATFORM_TIMEOUT_MS = 10_000
+
+function asrError(code) {
+  const error = new Error(code)
+  error.code = code
+  return error
+}
+
+function readPermissionError(changed = false) {
+  return asrError(changed ? 'QQ_PERMISSION_CHANGED: qq.read' : 'QQ_PERMISSION_DENIED: qq.read')
+}
+
+function assertRead(core, sessionId, changed = false) {
+  let allowed = false
+  try {
+    allowed = core.authorizeSessionCapability(sessionId, 'qq.read') === true
+  } catch {
+    allowed = false
+  }
+  if (!allowed) throw readPermissionError(changed)
+}
+
+function authorizeScene(core, sessionId) {
+  try {
+    return core.authorizedScene(sessionId)
+  } catch (error) {
+    const changed = String(error?.message ?? '').startsWith('QQ_PERMISSION_CHANGED')
+    throw readPermissionError(changed)
+  }
+}
+
+function boundedText(value) {
+  if (typeof value !== 'string') throw asrError('QQ_NATIVE_ASR_INVALID_RESPONSE')
+  const text = value
+    .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, '')
+    .trim()
+  if (text.length === 0) throw asrError('QQ_NATIVE_ASR_EMPTY')
+  if (text.length > MAX_TRANSCRIPT_CHARS) throw asrError('QQ_NATIVE_ASR_TOO_LONG')
+  return text
+}
+
+/**
+ * Use NapCat/QQ's native PTT transcript for one stored record message. The
+ * model supplies only messageId; Scene, sender and transcript storage target
+ * all come from the current authorized Session.
+ */
+export async function transcribeMessageRecordNative({
+  core,
+  store,
+  transport,
+  sessionId,
+  messageId,
+}) {
+  if (!transport || typeof transport.action !== 'function') throw asrError('QQ_NATIVE_ASR_UNAVAILABLE')
+  if (transport.status !== undefined && transport.status !== 'connected') throw asrError('QQ_NATIVE_ASR_UNAVAILABLE')
+
+  let id
+  try {
+    id = normalizeMessageId(messageId, 'messageId')
+  } catch {
+    throw asrError('QQ_NATIVE_ASR_MESSAGE_INVALID')
+  }
+
+  const scene = authorizeScene(core, sessionId)
+  assertRead(core, sessionId)
+
+  const row = store.getScene(scene)
+  const message = row?.messages?.find(item => item.messageId === id)
+  if (!message) throw asrError('QQ_MESSAGE_SCOPE')
+
+  let segments
+  try {
+    segments = sanitizeInboundSegments(message.segments)
+  } catch {
+    throw asrError('QQ_NATIVE_ASR_MESSAGE_INVALID')
+  }
+  if (!segments.some(segment => segment.type === 'record')) throw asrError('QQ_NATIVE_ASR_NOT_RECORD')
+
+  let response
+  try {
+    response = await transport.action('fetch_ptt_text', { message_id: id }, PLATFORM_TIMEOUT_MS, MAX_RESPONSE_BYTES)
+  } catch (error) {
+    throw asrError(error?.code === 'ONEBOT_RESPONSE_TOO_LARGE'
+      ? 'QQ_NATIVE_ASR_RESPONSE_TOO_LARGE'
+      : 'QQ_NATIVE_ASR_UNAVAILABLE')
+  }
+
+  assertRead(core, sessionId, true)
+  if (!response || typeof response !== 'object' || Array.isArray(response)) {
+    throw asrError('QQ_NATIVE_ASR_INVALID_RESPONSE')
+  }
+  const text = boundedText(response.text)
+  assertRead(core, sessionId, true)
+
+  try {
+    store.setMessageTranscript(scene, id, text)
+  } catch {
+    throw asrError('QQ_NATIVE_ASR_STORAGE_FAILED')
+  }
+
+  return {
+    text,
+    messageId: id,
+    senderId: message.senderId,
+    scene: { botId: scene.botId, kind: scene.kind, peerId: scene.peerId },
+  }
+}