@chainlesschain/personal-data-hub 0.3.9 → 0.4.1

package/lib/adapters/game-honor-of-kings/index.js

@@ -0,0 +1,259 @@
+/**
+ * FAMILY-23 v0.1 — 王者荣耀 (Honor of Kings) adapter, snapshot mode.
+ *
+ * 家庭守护 telemetry：家长看孩子玩什么游戏/玩多久。v0.1 cookie-scrape 占位 —
+ * [HonorOfKingsApiClient.extractUid] 抽 openid/uin；snapshot 模式消费手机端 collector
+ * 快照 (profile + play-session)。战绩 HTTP fetcher（营地接口 + 腾讯签名）留 v0.2，
+ * 故无 inputPath 时 sync 抛 NO_INPUT（同 social-kuaishou snapshot 先例）。
+ *
+ * Snapshot schema (v1):
+ *   { schemaVersion:1, snapshottedAt, account:{uid,displayName}, events:[
+ *     { kind:"profile", id, capturedAt, uid, nickname, level, rank, avatarUrl },
+ *     { kind:"play", id, capturedAt, durationMs, mode, startAt } ] }
+ *
+ * Sensitivity: "medium"。
+ */
+"use strict";
+
+const fs = require("node:fs");
+const { newId } = require("../../ids");
+const {
+  ENTITY_TYPES,
+  PERSON_SUBTYPES,
+  EVENT_SUBTYPES,
+  CAPTURED_BY,
+} = require("../../constants");
+const { HonorOfKingsApiClient } = require("./api-client");
+
+const NAME = "game-honor-of-kings";
+const VERSION = "0.1.0";
+const SNAPSHOT_SCHEMA_VERSION = 1;
+const KIND_PROFILE = "profile";
+const KIND_PLAY = "play";
+const VALID_SNAPSHOT_KINDS = Object.freeze([KIND_PROFILE, KIND_PLAY]);
+
+function stableOriginalId(kind, id) {
+  const safe =
+    (typeof id === "string" && id.length > 0 && id) ||
+    (typeof id === "number" && Number.isFinite(id) && String(id)) ||
+    `unknown-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  return `hok:${kind}:${safe}`;
+}
+
+function parseTime(v) {
+  if (Number.isFinite(v)) return v > 1e12 ? v : v * 1000;
+  if (typeof v === "string") {
+    if (/^\d+$/.test(v)) {
+      const n = parseInt(v, 10);
+      return n > 1e12 ? n : n * 1000;
+    }
+    const t = Date.parse(v);
+    return Number.isFinite(t) ? t : null;
+  }
+  return null;
+}
+
+class HonorOfKingsAdapter {
+  constructor(opts = {}) {
+    this.account = opts.account || null;
+    this.name = NAME;
+    this.version = VERSION;
+    this.capabilities = [
+      "sync:snapshot",
+      "parse:hok-profile",
+      "parse:hok-play-session",
+    ];
+    this.extractMode = "web-api";
+    this.rateLimits = {};
+    this.dataDisclosure = {
+      fields: [
+        "hok:profile (uid / nickname / level / rank / avatar)",
+        "hok:play_session (start / duration / mode)",
+      ],
+      sensitivity: "medium",
+      legalGate: false,
+      defaultInclude: { profile: true, play: true },
+    };
+    this.apiClient = new HonorOfKingsApiClient();
+    this._deps = { fs };
+  }
+
+  async authenticate(ctx = {}) {
+    if (ctx && typeof ctx.inputPath === "string" && ctx.inputPath.length > 0) {
+      try {
+        this._deps.fs.accessSync(ctx.inputPath, this._deps.fs.constants.R_OK);
+      } catch (err) {
+        return {
+          ok: false,
+          reason: "INPUT_PATH_UNREADABLE",
+          message: `snapshot not readable at ${ctx.inputPath}: ${err.message}`,
+        };
+      }
+      return { ok: true, mode: "snapshot-file" };
+    }
+    return {
+      ok: false,
+      reason: "NO_INPUT",
+      message:
+        "game-honor-of-kings.authenticate: v0.1 needs opts.inputPath (snapshot mode); live HTTP fetcher 待 v0.2",
+    };
+  }
+
+  async healthCheck() {
+    return { ok: true, lastChecked: Date.now() };
+  }
+
+  async *sync(opts = {}) {
+    if (typeof opts.inputPath === "string" && opts.inputPath.length > 0) {
+      yield* this._syncViaSnapshot(opts);
+      return;
+    }
+    throw new Error(
+      "game-honor-of-kings.sync: v0.1 needs opts.inputPath (snapshot mode); 营地战绩 HTTP fetcher 待 v0.2",
+    );
+  }
+
+  async *_syncViaSnapshot(opts) {
+    const raw = this._deps.fs.readFileSync(opts.inputPath, "utf-8");
+    const snapshot = JSON.parse(raw);
+    if (
+      !snapshot ||
+      typeof snapshot !== "object" ||
+      snapshot.schemaVersion !== SNAPSHOT_SCHEMA_VERSION
+    ) {
+      throw new Error(
+        `game-honor-of-kings.sync: snapshot schemaVersion mismatch (got ${snapshot && snapshot.schemaVersion}, expected ${SNAPSHOT_SCHEMA_VERSION})`,
+      );
+    }
+    const fallbackCapturedAt =
+      Number.isFinite(snapshot.snapshottedAt) && snapshot.snapshottedAt > 0
+        ? Math.floor(snapshot.snapshottedAt)
+        : Date.now();
+    const account =
+      snapshot.account && typeof snapshot.account === "object"
+        ? snapshot.account
+        : null;
+    const include = opts.include || {};
+    const limit =
+      Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : Infinity;
+    const events = Array.isArray(snapshot.events) ? snapshot.events : [];
+    let emitted = 0;
+    for (const ev of events) {
+      if (emitted >= limit) return;
+      if (!ev || typeof ev !== "object") continue;
+      const kind = ev.kind;
+      if (!VALID_SNAPSHOT_KINDS.includes(kind)) continue;
+      if (include[kind] === false) continue;
+      const capturedAt = parseTime(ev.capturedAt) || fallbackCapturedAt;
+      const id =
+        (typeof ev.id === "string" && ev.id.length > 0 && ev.id) ||
+        ev.uid ||
+        null;
+      yield {
+        adapter: NAME,
+        kind,
+        originalId: stableOriginalId(kind, id),
+        capturedAt,
+        payload: { ...ev, account },
+      };
+      emitted += 1;
+    }
+  }
+
+  normalize(raw) {
+    if (!raw || !raw.payload) {
+      throw new Error("HonorOfKingsAdapter.normalize: payload missing");
+    }
+    const ingestedAt = Date.now();
+    const kind = raw.kind || raw.payload.kind;
+    const p = raw.payload;
+    if (kind === KIND_PROFILE) return normalizeProfile(p, raw, ingestedAt);
+    if (kind === KIND_PLAY) return normalizePlay(p, raw, ingestedAt);
+    throw new Error(`HonorOfKingsAdapter.normalize: unknown kind ${kind}`);
+  }
+}
+
+function buildSource(raw, occurredAt) {
+  return {
+    adapter: NAME,
+    adapterVersion: VERSION,
+    originalId: raw.originalId,
+    capturedAt: raw.capturedAt || occurredAt,
+    capturedBy: CAPTURED_BY.API,
+  };
+}
+
+function normalizeProfile(p, raw, ingestedAt) {
+  const uid = p.uid || (p.account && p.account.uid) || null;
+  const nickname =
+    p.nickname || (p.account && p.account.displayName) || "(unnamed)";
+  const occurredAt = parseTime(p.capturedAt) || raw.capturedAt || ingestedAt;
+  const identifiers = {};
+  if (uid) identifiers["hok-uid"] = [String(uid)];
+  return {
+    events: [],
+    persons: [
+      {
+        id: uid ? `person-hok-${uid}` : `person-hok-self-${newId()}`,
+        type: ENTITY_TYPES.PERSON,
+        subtype: PERSON_SUBTYPES.SELF,
+        names: [nickname],
+        ingestedAt,
+        source: buildSource(raw, occurredAt),
+        identifiers,
+        extra: {
+          platform: "honor-of-kings",
+          level: p.level != null ? p.level : null,
+          rank: p.rank || null,
+          avatarUrl: p.avatarUrl || null,
+          snapshottedAt: occurredAt,
+        },
+      },
+    ],
+    places: [],
+    items: [],
+    topics: [],
+  };
+}
+
+function normalizePlay(p, raw, ingestedAt) {
+  const occurredAt =
+    parseTime(p.startAt) ||
+    parseTime(p.capturedAt) ||
+    raw.capturedAt ||
+    ingestedAt;
+  return {
+    events: [
+      {
+        id: newId(),
+        type: ENTITY_TYPES.EVENT,
+        subtype: EVENT_SUBTYPES.MEDIA,
+        occurredAt,
+        actor: "person-self",
+        content: { title: "王者荣耀 游戏时长" },
+        ingestedAt,
+        source: buildSource(raw, occurredAt),
+        extra: {
+          platform: "honor-of-kings",
+          kind: "play",
+          durationMs: Number.isFinite(p.durationMs) ? p.durationMs : 0,
+          mode: p.mode || null,
+        },
+      },
+    ],
+    persons: [],
+    places: [],
+    items: [],
+    topics: [],
+  };
+}
+
+module.exports = {
+  HonorOfKingsAdapter,
+  NAME,
+  VERSION,
+  SNAPSHOT_SCHEMA_VERSION,
+  VALID_SNAPSHOT_KINDS,
+  KIND_PROFILE,
+  KIND_PLAY,
+};

package/lib/adapters/netease-music/index.js

@@ -0,0 +1,227 @@
+"use strict";
+
+/**
+ * 网易云音乐 (NetEase Cloud Music) adapter — snapshot mode.
+ *
+ * Mirrors the social snapshot adapters (bilibili/douyin): a device-side
+ * collector (Android in-app, or a desktop helper hitting the cookie web API
+ * `/user/record` `/user/playlist`) writes a snapshot JSON; this adapter
+ * ingests it. Schema is OUR contract, so normalize is fully testable and the
+ * vault path is reliable regardless of how the bytes were captured.
+ *
+ * Snapshot schema (schemaVersion 1):
+ *   {
+ *     schemaVersion: 1, snapshottedAt: <ms>,
+ *     account: { uid, nickname },
+ *     events: [
+ *       { kind: "play",     id, capturedAt, song, artist, album, songId, playCount },
+ *       { kind: "favorite", id, capturedAt, song, artist, album, songId },
+ *       { kind: "playlist", id, capturedAt, name, playlistId, trackCount, creator }
+ *     ]
+ *   }
+ *
+ * play     → EVENT(media, "听了 <song>") + ITEM(song)
+ * favorite → EVENT(like)                 + ITEM(song)
+ * playlist → TOPIC(歌单)
+ */
+
+const fs = require("node:fs");
+const { newId } = require("../../ids");
+const {
+  ENTITY_TYPES,
+  EVENT_SUBTYPES,
+  ITEM_SUBTYPES,
+  CAPTURED_BY,
+} = require("../../constants");
+
+const NAME = "netease-music";
+const VERSION = "0.1.0";
+const SNAPSHOT_SCHEMA_VERSION = 1;
+
+const KIND_PLAY = "play";
+const KIND_FAVORITE = "favorite";
+const KIND_PLAYLIST = "playlist";
+const VALID_KINDS = Object.freeze([KIND_PLAY, KIND_FAVORITE, KIND_PLAYLIST]);
+
+function parseTime(v) {
+  if (Number.isFinite(v)) return v > 1e12 ? v : v * 1000;
+  if (typeof v === "string" && /^\d+$/.test(v)) {
+    const n = parseInt(v, 10);
+    return n > 1e12 ? n : n * 1000;
+  }
+  return null;
+}
+
+function stableOriginalId(kind, id) {
+  const safe =
+    (typeof id === "string" && id.length > 0 && id) ||
+    (typeof id === "number" && Number.isFinite(id) && String(id)) ||
+    `unknown-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  return `netease-music:${kind}:${safe}`;
+}
+
+class NeteaseMusicAdapter {
+  constructor(opts = {}) {
+    this._dataPath = opts.inputPath || null;
+    this.name = NAME;
+    this.version = VERSION;
+    this.capabilities = [
+      "sync:snapshot",
+      "parse:netease-play",
+      "parse:netease-favorite",
+      "parse:netease-playlist",
+    ];
+    this.extractMode = "web-api";
+    this.rateLimits = {};
+    this.dataDisclosure = {
+      fields: [
+        "netease:play (歌名 / 歌手 / 专辑 / 播放次数)",
+        "netease:favorite (收藏的歌)",
+        "netease:playlist (歌单名 / 曲目数)",
+      ],
+      sensitivity: "low",
+      legalGate: false,
+    };
+    this._deps = { fs };
+  }
+
+  async authenticate(ctx = {}) {
+    if (ctx && ctx.readinessOnly) {
+      return {
+        ok: false,
+        reason: "NO_INPUT",
+        message: "netease-music: 需手机 App 内采集听歌记录/歌单快照后回传",
+      };
+    }
+    const inputPath = (ctx && ctx.inputPath) || this._dataPath;
+    if (inputPath) {
+      try {
+        this._deps.fs.accessSync(inputPath, this._deps.fs.constants.R_OK);
+      } catch (err) {
+        return { ok: false, reason: "INPUT_PATH_UNREADABLE", message: `snapshot not readable: ${err.message}` };
+      }
+      return { ok: true, mode: "snapshot-file" };
+    }
+    return { ok: false, reason: "NO_INPUT", message: "netease-music.authenticate: needs opts.inputPath" };
+  }
+
+  async healthCheck() {
+    return { ok: true, lastChecked: Date.now() };
+  }
+
+  async *sync(opts = {}) {
+    const inputPath = opts.inputPath || this._dataPath;
+    if (!inputPath) throw new Error("netease-music.sync: needs opts.inputPath (snapshot JSON)");
+    if (!this._deps.fs.existsSync(inputPath)) return;
+    const snapshot = JSON.parse(this._deps.fs.readFileSync(inputPath, "utf-8"));
+    if (!snapshot || snapshot.schemaVersion !== SNAPSHOT_SCHEMA_VERSION) {
+      throw new Error(
+        `netease-music.sync: snapshot schemaVersion mismatch (got ${snapshot && snapshot.schemaVersion}, expected ${SNAPSHOT_SCHEMA_VERSION})`,
+      );
+    }
+    const fallback =
+      Number.isFinite(snapshot.snapshottedAt) && snapshot.snapshottedAt > 0
+        ? Math.floor(snapshot.snapshottedAt)
+        : Date.now();
+    const account = snapshot.account && typeof snapshot.account === "object" ? snapshot.account : null;
+    const include = opts.include || {};
+    const limit = Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : Infinity;
+    const events = Array.isArray(snapshot.events) ? snapshot.events : [];
+    let emitted = 0;
+    for (const ev of events) {
+      if (emitted >= limit) return;
+      if (!ev || typeof ev !== "object" || !VALID_KINDS.includes(ev.kind)) continue;
+      if (include[ev.kind] === false) continue;
+      const id = (typeof ev.id === "string" && ev.id) || ev.songId || ev.playlistId || null;
+      yield {
+        adapter: NAME,
+        kind: ev.kind,
+        originalId: stableOriginalId(ev.kind, id),
+        capturedAt: parseTime(ev.capturedAt) || fallback,
+        payload: { ...ev, account },
+      };
+      emitted += 1;
+    }
+  }
+
+  normalize(raw) {
+    if (!raw || !raw.payload) throw new Error("NeteaseMusicAdapter.normalize: payload missing");
+    const kind = raw.kind || raw.payload.kind;
+    const ingestedAt = Date.now();
+    if (kind === KIND_PLAY) return normalizeSong(raw.payload, raw, ingestedAt, EVENT_SUBTYPES.MEDIA, "听了");
+    if (kind === KIND_FAVORITE) return normalizeSong(raw.payload, raw, ingestedAt, EVENT_SUBTYPES.LIKE, "收藏");
+    if (kind === KIND_PLAYLIST) return normalizePlaylist(raw.payload, raw, ingestedAt);
+    throw new Error(`NeteaseMusicAdapter.normalize: unknown kind ${kind}`);
+  }
+}
+
+function buildSource(raw, occurredAt) {
+  return {
+    adapter: NAME,
+    adapterVersion: VERSION,
+    originalId: raw.originalId,
+    capturedAt: raw.capturedAt || occurredAt,
+    capturedBy: CAPTURED_BY.API,
+  };
+}
+
+function normalizeSong(p, raw, ingestedAt, subtype, verb) {
+  const occurredAt = parseTime(p.capturedAt) || raw.capturedAt || ingestedAt;
+  const source = buildSource(raw, occurredAt);
+  const song = p.song || "(未知歌曲)";
+  const artist = p.artist || "";
+  const songId = p.songId != null ? String(p.songId) : null;
+  const itemId = songId ? `item-netease-song-${songId}` : `item-netease-song-${newId()}`;
+  return {
+    events: [{
+      id: newId(),
+      type: ENTITY_TYPES.EVENT,
+      subtype,
+      occurredAt,
+      actor: "person-self",
+      content: { title: `${verb}: ${song}${artist ? " - " + artist : ""}`, text: `${song} ${artist}`.trim() },
+      ingestedAt,
+      source,
+      extra: {
+        platform: "netease-music",
+        song, artist, album: p.album || null, songId,
+        playCount: p.playCount != null ? p.playCount : null,
+        itemRef: itemId,
+      },
+    }],
+    items: [{
+      id: itemId,
+      type: ENTITY_TYPES.ITEM,
+      subtype: ITEM_SUBTYPES.MEDIA,
+      name: artist ? `${song} - ${artist}` : song,
+      ingestedAt,
+      source,
+      extra: { platform: "netease-music", kind: "song", song, artist, album: p.album || null, songId },
+    }],
+    persons: [], places: [], topics: [],
+  };
+}
+
+function normalizePlaylist(p, raw, ingestedAt) {
+  const occurredAt = parseTime(p.capturedAt) || raw.capturedAt || ingestedAt;
+  const source = buildSource(raw, occurredAt);
+  const pid = p.playlistId != null ? String(p.playlistId) : null;
+  return {
+    events: [], persons: [], places: [], items: [],
+    topics: [{
+      id: pid ? `topic-netease-playlist-${pid}` : `topic-netease-playlist-${newId()}`,
+      type: ENTITY_TYPES.TOPIC,
+      name: p.name || "(未命名歌单)",
+      ingestedAt,
+      source,
+      extra: {
+        platform: "netease-music",
+        playlistId: pid,
+        trackCount: p.trackCount != null ? p.trackCount : null,
+        creator: p.creator || null,
+      },
+    }],
+  };
+}
+
+module.exports = { NeteaseMusicAdapter, NAME, VERSION, SNAPSHOT_SCHEMA_VERSION, VALID_KINDS };

package/lib/adapters/qq-pc/index.js

@@ -0,0 +1,200 @@
+"use strict";
+
+/**
+ * QQ NT **desktop (PC)** adapter — 本地直读样板 (ported from social-douyin /
+ * wechat-pc). Reads 新版电脑 QQ 的 nt_msg.db (c2c_msg_table / group_msg_table)
+ * straight into the vault as MESSAGE events.
+ *
+ * Distinct from the Android `messaging-qq` adapter (per-uin <uin>.db, plain
+ * SQLite + XOR-IMEI content). QQ NT is SQLCipher-encrypted with numeric
+ * obfuscated columns + protobuf message bodies — see nt-db-reader.js for the
+ * honest v0.1 caveats. We preserve the full raw row in extra so nothing is
+ * lost even when text extraction is partial.
+ *
+ * Modes:
+ *   opts.dbPath / opts.inputPath — a (decrypted) nt_msg.db. opts.key (hex)
+ *   lets the reader attempt SQLCipher directly; otherwise a plaintext DB is
+ *   expected (decrypt first — the reliable path).
+ */
+
+const fs = require("node:fs");
+const { newId } = require("../../ids");
+const { ENTITY_TYPES, EVENT_SUBTYPES, CAPTURED_BY } = require("../../constants");
+
+const NAME = "qq-pc";
+const VERSION = "0.1.0";
+const KIND_MESSAGE = "message";
+
+function stableOriginalId(id) {
+  const safe =
+    (typeof id === "string" && id.length > 0 && id) ||
+    (typeof id === "number" && Number.isFinite(id) && String(id)) ||
+    `unknown-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  return `qq-pc:message:${safe}`;
+}
+
+class QQPcAdapter {
+  constructor(opts = {}) {
+    this._dbPath = opts.dbPath || null;
+    this._key = opts.key || null;
+
+    this.name = NAME;
+    this.version = VERSION;
+    this.capabilities = [
+      "sync:sqlite",
+      "decrypt:sqlcipher-qqnt",
+      "parse:qq-nt-message",
+    ];
+    this.extractMode = "device-pull";
+    this.rateLimits = {};
+    this.dataDisclosure = {
+      fields: [
+        "qq-pc:messages (time / type / sender / peer / best-effort text from nt_msg.db; raw row preserved)",
+      ],
+      sensitivity: "high",
+      legalGate: true,
+    };
+
+    this._deps = {
+      fs,
+      dbDriverFactory: opts.dbDriverFactory || null,
+    };
+  }
+
+  async authenticate(ctx = {}) {
+    if (ctx && ctx.readinessOnly) {
+      if (this._dbPath) return { ok: true, mode: "configured" };
+      return {
+        ok: false,
+        reason: "DB_NOT_PULLED",
+        message:
+          "qq-pc: 需提供电脑版 QQ 的 nt_msg.db 路径（加密库需先解密或提供 key）",
+      };
+    }
+    const dbPath = (ctx && ctx.inputPath) || (ctx && ctx.dbPath) || this._dbPath;
+    if (dbPath) {
+      try {
+        this._deps.fs.accessSync(dbPath, this._deps.fs.constants.R_OK);
+      } catch (err) {
+        return {
+          ok: false,
+          reason: "INPUT_PATH_UNREADABLE",
+          message: `qq-pc: db not readable at ${dbPath}: ${err.message}`,
+        };
+      }
+      return { ok: true, mode: "sqlite" };
+    }
+    return {
+      ok: false,
+      reason: "DB_NOT_PULLED",
+      message: "qq-pc.authenticate: needs opts.dbPath / inputPath (nt_msg.db)",
+    };
+  }
+
+  async healthCheck() {
+    return { ok: true, lastChecked: Date.now() };
+  }
+
+  async *sync(opts = {}) {
+    const dbPath = opts.dbPath || opts.inputPath || this._dbPath;
+    if (!dbPath) {
+      throw new Error("qq-pc.sync: needs opts.dbPath / opts.inputPath (nt_msg.db)");
+    }
+    if (!this._deps.fs.existsSync(dbPath)) return;
+
+    // eslint-disable-next-line global-require
+    const { readQqNt } = require("./nt-db-reader");
+    const readOpts = { key: opts.key || this._key || null };
+    if (Number.isInteger(opts.limitMessages)) readOpts.limitMessages = opts.limitMessages;
+    if (this._deps.dbDriverFactory) readOpts._databaseClass = this._deps.dbDriverFactory();
+
+    const { messages, diagnostic } = readQqNt(dbPath, readOpts);
+    if (typeof opts.onProgress === "function") {
+      try {
+        opts.onProgress({ phase: "qq-nt-read", adapter: NAME, ...diagnostic });
+      } catch (_e) { /* progress best-effort */ }
+    }
+
+    const limit = Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : Infinity;
+    const fallbackCapturedAt = Date.now();
+    let emitted = 0;
+    for (const m of messages) {
+      if (emitted >= limit) return;
+      if (!m || typeof m !== "object") continue;
+      const capturedAt =
+        typeof m.createdTimeMs === "number" && m.createdTimeMs > 0
+          ? m.createdTimeMs
+          : fallbackCapturedAt;
+      const idPart =
+        m.msgId ||
+        (m.peerUin && m.createdTimeMs ? `${m.peerUin}-${m.createdTimeMs}` : `msg-${emitted}`);
+      yield {
+        adapter: NAME,
+        kind: KIND_MESSAGE,
+        originalId: stableOriginalId(idPart),
+        capturedAt,
+        payload: { kind: KIND_MESSAGE, ...m },
+      };
+      emitted += 1;
+    }
+  }
+
+  normalize(raw) {
+    if (!raw || !raw.payload) {
+      throw new Error("QQPcAdapter.normalize: payload missing");
+    }
+    const kind = raw.kind || raw.payload.kind;
+    if (kind !== KIND_MESSAGE) {
+      throw new Error(`QQPcAdapter.normalize: unknown kind ${kind}`);
+    }
+    const p = raw.payload;
+    const ingestedAt = Date.now();
+    const occurredAt =
+      (typeof p.createdTimeMs === "number" && p.createdTimeMs) || raw.capturedAt || ingestedAt;
+    const source = {
+      adapter: NAME,
+      adapterVersion: VERSION,
+      originalId: raw.originalId,
+      capturedAt: raw.capturedAt || occurredAt,
+      capturedBy: CAPTURED_BY.SQLITE,
+    };
+    const text = typeof p.text === "string" ? p.text : "";
+    return {
+      events: [{
+        id: newId(),
+        type: ENTITY_TYPES.EVENT,
+        subtype: EVENT_SUBTYPES.MESSAGE,
+        occurredAt,
+        actor: "person-self",
+        content: {
+          title: text ? text.slice(0, 80) : "(待解析消息体)",
+          text,
+        },
+        ingestedAt,
+        source,
+        extra: {
+          platform: "qq",
+          source: "pc-nt",
+          peerUin: p.peerUin || null,
+          senderUin: p.senderUin || null,
+          isGroup: !!p.isGroup,
+          qqMsgType: typeof p.type === "number" ? p.type : null,
+          // Full raw row preserved — protobuf bodies + unknown columns — so a
+          // later decoder can backfill text without re-reading the DB.
+          rawRow: p.rawRow || null,
+          textResolved: typeof p.text === "string" && p.text.length > 0,
+        },
+      }],
+      persons: [],
+      places: [],
+      items: [],
+      topics: [],
+    };
+  }
+}
+
+module.exports = {
+  QQPcAdapter,
+  NAME,
+  VERSION,
+};