@chainlesschain/personal-data-hub 0.3.9 → 0.4.1

package/README.md

@@ -4,25 +4,38 @@ Personal Data Hub — UnifiedSchema, validators, batch helpers, SQLCipher
 LocalVault, and AdapterRegistry for the "data back to the individual"
 middleware.
 
-> **Phase 0 + Phase 1 + Phase 2 + Phase 3 + Phase 3.5 landed** of the 13-phase plan in
-> [`docs/design/Personal_Data_Hub_Architecture.md`](../../docs/design/Personal_Data_Hub_Architecture.md).
-> Phase 0 covers schema + validation + ID generation.
-> Phase 1 adds SQLCipher LocalVault + pluggable key providers + migrations.
-> Phase 2 adds AdapterRegistry + KG/RAG derivation + MockAdapter (1000
-> events ingest in ~600ms — 50× under the 30s target).
-> Phase 3 adds the natural-language AnalysisEngine: query parser → vault
-> facts → prompt builder → LLM → citation validation, with a privacy gate
-> that refuses non-local LLMs unless caller opts in. **MockLLMClient**
-> for tests, **OllamaClient** for standalone use.
-> Phase 3.5 wires production bridges: **CcLLMAdapter** wraps the existing
-> cc llm-manager (Ollama / Volcengine / Anthropic / Gemini / DeepSeek)
-> via dependency injection; **CcKgSink** translates hub triples into the
-> existing knowledge-graph addEntity + addRelation; **CcRagSink** feeds
-> hub RagDocs into BM25 (Qdrant vector store wiring left as future work).
-> Hub package stays decoupled — bridges take cc functions as constructor
-> args rather than importing cc modules directly.
-> Sync engine UI, real KG/RAG wiring, and the actual adapters (Email,
-> Alipay, AI Chat × 8, WeChat, ...) come in later phases.
+> **v0.4.0 (ships with ChainlessChain v5.0.3.99, 2026-06-08).** Phase 0–13
+> of the 13-phase plan in
+> [`docs/design/Personal_Data_Hub_Architecture.md`](../../docs/design/Personal_Data_Hub_Architecture.md)
+> have landed, plus the multi-platform collection layer. The foundation is
+> unchanged: schema + validation + UUID v7 (Phase 0); SQLCipher LocalVault +
+> pluggable key providers + migrations (Phase 1); AdapterRegistry + KG/RAG
+> derivation (Phase 2); the natural-language AnalysisEngine with a hard
+> privacy gate that refuses non-local LLMs unless the caller opts in
+> (Phase 3); and production bridges — **CcLLMAdapter** (wraps cc llm-manager:
+> Ollama / Volcengine / Anthropic / Gemini / DeepSeek), **CcKgSink**, **CcRagSink**
+> — injected at the desktop/CLI entry so this package stays decoupled (Phase 3.5).
+>
+> **51 adapters are now live** (no longer "later phases"): Email IMAP,
+> Alipay bill, 9 AI-chat vendors, WeChat / QQ / Weibo / Bilibili / Douyin /
+> Xiaohongshu / Toutiao / Kuaishou social, Telegram / WhatsApp messaging,
+> Taobao / JD / Meituan / Pinduoduo shopping, Amap / Baidu-map / Tencent-map /
+> Ctrip / 12306 travel, system-data (contacts / calls / sms / location),
+> and the developer-activity set (git / shell / vscode / browser-history /
+> local-files / win-recent).
+>
+> **New in v0.4.0 (v5.0.3.99):** adapter **readiness** — split out from the
+> loose `healthCheck` sync gate into a real ready/needs_setup/unavailable
+> judgment (`registry.readiness()`) with a one-line reason, so "config looks
+> fine but nothing collects" is no longer silent; an `adapter-guide.js`
+> single-source of import steps reused across web-shell / desktop / CLI /
+> Android; new local-direct-read sources (Douyin, WeChat PC, QQ-NT, DingTalk,
+> Feishu, WeRead, Apple Health, NetEase Music); email-bill LLM gap-fill
+> (Phase 5.5); and iOS encrypted-backup decryption (Phase 7.5b).
+>
+> Editing `lib/**` requires bumping the package version + `npm publish` +
+> the Android `USR_VERSION` sentinel, or real devices keep running stale code
+> (see hidden-risk-traps #27/#28).
 
 ## What's in here
 
@@ -40,6 +53,14 @@ lib/
 │                     typed put/get, queryEvents, watermarks, audit, key
 │                     rotation (WAL-safe), destroy
 ├── adapter-spec.js   PersonalDataAdapter contract + assertAdapter check
+├── adapter-readiness.js readiness() — ready/needs_setup/unavailable + reason,
+│                     split out from the loose healthCheck sync gate
+├── adapter-guide.js  category-driven import guides (single source of import
+│                     steps reused across web-shell / desktop / CLI / Android)
+├── adapters/         51 live adapters (email-imap, alipay-bill, ai-chat-history,
+│                     wechat / wechat-pc, qq-pc, dingtalk-pc, feishu-pc, weread,
+│                     apple-health, netease-music, social-*, shopping-*,
+│                     travel-*, system-data, git-activity, vscode, ...)
 ├── kg-derive.js      UnifiedSchema → KG triples (rdf:type / by / involves /
 │                     happened-at / etc.) — engine-agnostic
 ├── rag-derive.js     UnifiedSchema → RAG (text, metadata) docs for indexing
@@ -217,7 +238,7 @@ cd packages/personal-data-hub
 npm test
 ```
 
-**268 tests** across 17 files covering ID generation, all 5 entity validators,
+**2040 tests** across 121 files covering ID generation, all 5 entity validators,
 batch helpers, key providers, vault open/migrations, entity round-trips,
 transactional putBatch with rollback, raw_events archive, queryEvents
 filters + pagination, sync watermarks, audit log, key rotation (WAL-safe),
@@ -230,11 +251,10 @@ tolerance), and the 1k events <30s ingest perf gate.
 
 | Concern               | Lives in                                          |
 |-----------------------|---------------------------------------------------|
-| Platform KeyProviders (DPAPI/Keychain/Keystore) | Phase 1.5 — desktop-app-vue main process bridge |
-| AdapterRegistry       | Phase 2 — same package or sibling                  |
-| KG ingestor / RAG     | Phase 2/4 — wired into existing KG / RAG engines  |
-| Email/Alipay/AI/WeChat adapters | Phase 5-12 — separate sub-packages       |
-| AI analysis skills    | Phase 11 — `skills/personal-analysis-*/`          |
+| Platform KeyProviders (DPAPI/Keychain/Keystore) | desktop-app-vue main-process bridge (the package ships the contract + InMemory/File providers) |
+| Qdrant vector retrieval | wired into the existing RAG engine at the cc entry (BM25 derivation ships here) |
+| AI analysis skills    | `skills/personal-analysis-*/` (the 5 built-in analysis skills) |
+| Native SQLCipher build | `better-sqlite3-multiple-ciphers` — host/Electron ABI dual-load handled at the cc entry |
 
 ## License
 

package/__tests__/adapters/apple-health.test.js

@@ -0,0 +1,95 @@
+"use strict";
+
+import { describe, it, expect } from "vitest";
+
+const { AppleHealthAdapter } = require("../../lib/adapters/apple-health");
+const { partitionBatch } = require("../../lib/batch");
+
+const XML = [
+  '<?xml version="1.0" encoding="UTF-8"?>',
+  '<HealthData locale="zh_CN">',
+  ' <Record type="HKQuantityTypeIdentifierStepCount" sourceName="iPhone" unit="count" creationDate="2024-01-15 08:36:00 +0800" startDate="2024-01-15 08:30:00 +0800" endDate="2024-01-15 08:35:00 +0800" value="123"/>',
+  ' <Record type="HKCategoryTypeIdentifierSleepAnalysis" sourceName="Watch" startDate="2024-01-15 23:00:00 +0800" endDate="2024-01-16 07:00:00 +0800" value="HKCategoryValueSleepAnalysisAsleep"/>',
+  ' <Workout workoutActivityType="HKWorkoutActivityTypeRunning" duration="30" durationUnit="min" totalDistance="5" totalDistanceUnit="km" startDate="2024-01-15 18:00:00 +0800" endDate="2024-01-15 18:30:00 +0800"/>',
+  ' <SomethingElse foo="bar"/>',
+  "</HealthData>",
+].join("\n");
+
+function adapter(xml = XML, { exists = true } = {}) {
+  const a = new AppleHealthAdapter();
+  a._deps.fs = {
+    existsSync: () => exists,
+    readFileSync: () => xml,
+    accessSync: () => {},
+    constants: { R_OK: 4 },
+  };
+  return a;
+}
+
+async function collect(iter) {
+  const out = [];
+  for await (const r of iter) out.push(r);
+  return out;
+}
+
+describe("AppleHealthAdapter", () => {
+  it("readinessOnly → NO_FILE (file-import, not 手机采集)", async () => {
+    const a = new AppleHealthAdapter();
+    const r = await a.authenticate({ readinessOnly: true });
+    expect(r.reason).toBe("NO_FILE");
+    expect(a.extractMode).toBe("file-import");
+  });
+
+  it("parses Record + Workout lines, ignores other elements", async () => {
+    const raws = await collect(adapter().sync({ inputPath: "/fake/export.xml" }));
+    expect(raws.map((r) => r.kind)).toEqual(["record", "record", "workout"]);
+  });
+
+  it("normalizes to valid events (metrics → other, workout → trip)", async () => {
+    const a = adapter();
+    const raws = await collect(a.sync({ inputPath: "/fake/export.xml" }));
+    const merged = { events: [], persons: [], places: [], items: [], topics: [] };
+    for (const r of raws) {
+      const n = a.normalize(r);
+      for (const k of Object.keys(merged)) merged[k].push(...n[k]);
+    }
+    const { valid, invalidReasons } = partitionBatch(merged);
+    expect(invalidReasons).toHaveLength(0);
+    expect(valid.events).toHaveLength(3);
+    const subtypes = valid.events.map((e) => e.subtype).sort();
+    expect(subtypes).toEqual(["other", "other", "trip"]);
+    const steps = valid.events.find((e) => e.extra.metric === "HKQuantityTypeIdentifierStepCount");
+    expect(steps.content.title).toContain("步数");
+    expect(steps.content.title).toContain("123");
+    const workout = valid.events.find((e) => e.subtype === "trip");
+    expect(workout.extra.activityType).toBe("Running");
+    expect(workout.content.title).toContain("5km");
+  });
+
+  it("parses the +0800 timezone offset correctly", async () => {
+    const a = adapter();
+    const raws = await collect(a.sync({ inputPath: "/fake/export.xml" }));
+    // 2024-01-15 08:30:00 +0800 == 2024-01-15T00:30:00Z
+    expect(raws[0].capturedAt).toBe(Date.parse("2024-01-15T00:30:00Z"));
+  });
+
+  it("respects limit + include", async () => {
+    const a = adapter();
+    const capped = await collect(a.sync({ inputPath: "/x", limit: 1 }));
+    expect(capped).toHaveLength(1);
+    const noWorkout = await collect(a.sync({ inputPath: "/x", include: { workout: false } }));
+    expect(noWorkout.every((r) => r.kind === "record")).toBe(true);
+  });
+
+  it("emits truncated progress when maxRecords exceeded", async () => {
+    const a = adapter();
+    const events = [];
+    await collect(a.sync({ inputPath: "/x", maxRecords: 1, onProgress: (e) => events.push(e) }));
+    expect(events.find((e) => e.phase === "truncated")).toBeTruthy();
+  });
+
+  it("missing file yields nothing", async () => {
+    const raws = await collect(adapter(XML, { exists: false }).sync({ inputPath: "/x" }));
+    expect(raws).toHaveLength(0);
+  });
+});

package/__tests__/adapters/email-templates.test.js

@@ -262,6 +262,129 @@ describe("extractBill — bank statement", () => {
   });
 });
 
+// ─── bill.js Phase 5.5 — LLM gap-fill ─────────────────────────────────────
+
+describe("extractBill — Phase 5.5 LLM gap-fill", () => {
+  // A body the regex can't crack (HTML-stripped marketing-style prose with
+  // no recognizable keywords) so coverage stays under 0.6 and the LLM fires.
+  // from:[] so even `institution` (otherwise derived from sender domain)
+  // is missing — keeps regex coverage at 0 so the LLM path is exercised.
+  const opaqueEmail = () => emailOf({
+    from: [],
+    subject: "Your statement is ready",
+    textBody: "Hello, your latest statement is now available. Please sign in to view the details of your account activity for this period.",
+  });
+
+  const llmReturning = (obj, sink) => ({
+    async chat(messages, _opts) {
+      if (sink) sink.messages = messages;
+      return { text: JSON.stringify(obj) };
+    },
+  });
+
+  it("fills missing fields from LLM when regex coverage < 60%", async () => {
+    const r = await extractBill(opaqueEmail(), {
+      llm: llmReturning({
+        amount: { value: 1234.5, currency: "CNY" },
+        dueAmount: { value: 1000, currency: "CNY" },
+        dueDate: "2026-12-20",
+        billingPeriod: { start: "2026-11-01", end: "2026-11-30" },
+        accountIdentifier: "6225 8801 2345 6789",
+        institution: "Example Bank",
+        billingMonth: "2026-11",
+      }),
+    });
+    expect(r.fields.amount.value).toBe(1234.5);
+    expect(r.fields.amount.direction).toBe("out");
+    expect(r.fields.dueAmount.value).toBe(1000);
+    expect(r.fields.dueDate).toBeGreaterThan(0);
+    expect(r.fields.billingPeriod.startMs).toBeLessThan(r.fields.billingPeriod.endMs);
+    // accountIdentifier coerced to last-4 only — never the full PAN
+    expect(r.fields.accountIdentifier).toBe("**** 6789");
+    expect(r.fields.institution).toBe("Example Bank");
+    expect(r.fields.billingMonth).toBe("2026-11");
+    expect(r.llmFilled).toEqual(
+      expect.arrayContaining(["amount", "dueAmount", "dueDate", "accountIdentifier", "institution", "billingMonth"]),
+    );
+  });
+
+  it("regex wins: LLM fills only the gaps, never overwrites a regex field", async () => {
+    // Only an amount is regex-extractable → coverage 1/7 < 0.6, LLM fires.
+    const r = await extractBill(emailOf({
+      from: [],
+      subject: "statement",
+      textBody: "您的账单金额为 ¥3,256.78。",
+    }), {
+      llm: llmReturning({ amount: { value: 99999, currency: "USD" }, institution: "LLM Bank" }),
+    });
+    // regex amount retained, LLM's bogus 99999/USD ignored
+    expect(r.fields.amount.value).toBe(3256.78);
+    expect(r.fields.amount.currency).toBe("CNY");
+    // institution was missing → LLM allowed to fill it
+    expect(r.fields.institution).toBe("LLM Bank");
+    expect(r.llmFilled).toEqual(["institution"]);
+  });
+
+  it("does NOT call the LLM when regex coverage already ≥ 60%", async () => {
+    let called = false;
+    const r = await extractBill(emailOf({
+      from: [{ address: "ebank@ccb.com.cn" }],
+      subject: "建设银行 11 月对账单",
+      textBody: "本期应还金额 ¥800 元，尾号 5555，账单周期 2026-10-01 至 2026-10-31，最后还款日 2026-11-25。",
+    }), {
+      llm: { async chat() { called = true; return { text: "{}" }; } },
+    });
+    expect(called).toBe(false);
+    expect(r.llmFilled).toBeUndefined();
+  });
+
+  it("drops malformed LLM values (bad dates, zero amounts, short account)", async () => {
+    const r = await extractBill(opaqueEmail(), {
+      llm: llmReturning({
+        amount: { value: 0 },              // non-positive → dropped
+        dueDate: "2026-13-45",             // impossible date → dropped
+        accountIdentifier: "12",           // < 4 digits → dropped
+        billingMonth: "2026-99",           // bad month → dropped
+        institution: "   ",                // blank → dropped
+      }),
+    });
+    expect(r.fields.amount).toBeUndefined();
+    expect(r.fields.dueDate).toBeUndefined();
+    expect(r.fields.accountIdentifier).toBeUndefined();
+    expect(r.fields.billingMonth).toBeUndefined();
+    expect(r.fields.institution).toBeUndefined();
+    expect(r.llmFilled).toBeUndefined();
+  });
+
+  it("records a warning when the LLM returns unparseable output", async () => {
+    const r = await extractBill(opaqueEmail(), {
+      llm: { async chat() { return { text: "sorry, I can't help with that" }; } },
+    });
+    expect(r.warnings.some((w) => w.includes("not parseable JSON"))).toBe(true);
+  });
+
+  it("records a warning when the LLM call throws", async () => {
+    const r = await extractBill(opaqueEmail(), {
+      llm: { async chat() { throw new Error("rate limited"); } },
+    });
+    expect(r.warnings.some((w) => w.includes("LLM bill fill failed") && w.includes("rate limited"))).toBe(true);
+  });
+
+  it("tolerates LLM output wrapped in ```json fences", async () => {
+    const r = await extractBill(opaqueEmail(), {
+      llm: { async chat() { return { text: "```json\n{\"institution\":\"Fenced Bank\"}\n```" }; } },
+    });
+    expect(r.fields.institution).toBe("Fenced Bank");
+    expect(r.llmFilled).toEqual(["institution"]);
+  });
+
+  it("no LLM provided → behaves exactly as before (no llmFilled, no warning)", async () => {
+    const r = await extractBill(opaqueEmail());
+    expect(r.llmFilled).toBeUndefined();
+    expect(r.warnings.every((w) => !w.includes("LLM"))).toBe(true);
+  });
+});
+
 // ─── order.js ───────────────────────────────────────────────────────────
 
 describe("extractOrder — e-commerce", () => {

package/__tests__/adapters/family-23-collectors-scaffold.test.js

@@ -0,0 +1,178 @@
+/**
+ * FAMILY-23 v0.1 — 王者荣耀 / 作业帮 / 支付宝 / 华为学习中心 collector scaffold 测试。
+ * 各平台: 契约 + extractUid + sync NO_INPUT throw + snapshot sync + normalize → 合法 batch。
+ */
+import { describe, it, expect } from "vitest";
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const lib = require("../../lib");
+const { assertAdapter } = require("../../lib/adapter-spec");
+const { validateBatch } = require("../../lib/batch");
+
+const {
+  HonorOfKingsApiClient,
+} = require("../../lib/adapters/game-honor-of-kings/api-client");
+const {
+  ZuoyebangApiClient,
+} = require("../../lib/adapters/edu-zuoyebang/api-client");
+const { AlipayApiClient } = require("../../lib/adapters/finance-alipay/api-client");
+const {
+  HuaweiLearningApiClient,
+} = require("../../lib/adapters/edu-huawei-learning/api-client");
+
+function writeSnapshot(obj) {
+  const p = path.join(
+    os.tmpdir(),
+    `fam23-snap-${Date.now()}-${Math.random().toString(36).slice(2)}.json`,
+  );
+  fs.writeFileSync(p, JSON.stringify(obj), "utf-8");
+  return p;
+}
+
+// platform → { Adapter, name, sensitivity, eventKind, eventSubtype, idKey }
+const PLATFORMS = [
+  {
+    label: "王者荣耀",
+    Adapter: lib.HonorOfKingsAdapter,
+    name: "game-honor-of-kings",
+    sensitivity: "medium",
+    eventKind: "play",
+    eventSubtype: "media",
+    idKey: "hok-uid",
+    sample: { kind: "play", id: "p1", durationMs: 1800000, mode: "rank", startAt: 1700000000000 },
+  },
+  {
+    label: "作业帮",
+    Adapter: lib.ZuoyebangAdapter,
+    name: "edu-zuoyebang",
+    sensitivity: "medium",
+    eventKind: "study",
+    eventSubtype: "other",
+    idKey: "zuoyebang-uid",
+    sample: { kind: "study", id: "s1", subject: "math", durationMs: 1200000, startAt: 1700000000000 },
+  },
+  {
+    label: "支付宝",
+    Adapter: lib.AlipayAdapter,
+    name: "finance-alipay",
+    sensitivity: "high",
+    eventKind: "order",
+    eventSubtype: "payment",
+    idKey: "alipay-uid",
+    sample: { kind: "order", id: "o1", merchant: "便利店", amountFen: 350, direction: "out", startAt: 1700000000000 },
+  },
+  {
+    label: "华为学习中心",
+    Adapter: lib.HuaweiLearningAdapter,
+    name: "edu-huawei-learning",
+    sensitivity: "medium",
+    eventKind: "study",
+    eventSubtype: "other",
+    idKey: "huawei-learning-uid",
+    sample: { kind: "study", id: "h1", course: "物理", durationMs: 900000, startAt: 1700000000000 },
+  },
+];
+
+for (const P of PLATFORMS) {
+  describe(`${P.label} (${P.name}) — FAMILY-23 v0.1`, () => {
+    it("contract conformance + sensitivity", () => {
+      const a = new P.Adapter();
+      expect(assertAdapter(a).ok).toBe(true);
+      expect(a.name).toBe(P.name);
+      expect(a.version).toBe("0.1.0");
+      expect(a.dataDisclosure.sensitivity).toBe(P.sensitivity);
+      expect(a.capabilities).toContain("sync:snapshot");
+    });
+
+    it("sync throws NO_INPUT without inputPath", async () => {
+      const a = new P.Adapter();
+      await expect(async () => {
+        for await (const _ of a.sync({})) void _;
+      }).rejects.toThrow(/inputPath/);
+    });
+
+    it("sync via snapshot yields profile + platform event", async () => {
+      const snapPath = writeSnapshot({
+        schemaVersion: 1,
+        snapshottedAt: 1700000000000,
+        account: { uid: "12345", displayName: "kid" },
+        events: [
+          { kind: "profile", id: "profile-12345", uid: "12345", nickname: "kid" },
+          P.sample,
+        ],
+      });
+      try {
+        const a = new P.Adapter();
+        const raws = [];
+        for await (const r of a.sync({ inputPath: snapPath })) raws.push(r);
+        expect(raws).toHaveLength(2);
+        expect(raws[0].kind).toBe("profile");
+        expect(raws[1].kind).toBe(P.eventKind);
+      } finally {
+        fs.unlinkSync(snapPath);
+      }
+    });
+
+    it("normalize profile → person-self with platform uid; event → valid subtype", () => {
+      const a = new P.Adapter();
+      const profileBatch = a.normalize({
+        adapter: P.name,
+        kind: "profile",
+        originalId: `${P.name}:profile:12345`,
+        capturedAt: 1700000000000,
+        payload: { kind: "profile", uid: "12345", nickname: "kid" },
+      });
+      expect(validateBatch(profileBatch).valid).toBe(true);
+      expect(profileBatch.persons[0].subtype).toBe("self");
+      expect(profileBatch.persons[0].identifiers[P.idKey]).toEqual(["12345"]);
+
+      const eventBatch = a.normalize({
+        adapter: P.name,
+        kind: P.eventKind,
+        originalId: `${P.name}:${P.eventKind}:1`,
+        capturedAt: 1700000000000,
+        payload: P.sample,
+      });
+      expect(validateBatch(eventBatch).valid).toBe(true);
+      expect(eventBatch.events[0].subtype).toBe(P.eventSubtype);
+    });
+
+    it("normalize throws on missing payload", () => {
+      const a = new P.Adapter();
+      expect(() => a.normalize({})).toThrow(/payload missing/);
+    });
+  });
+}
+
+describe("FAMILY-23 extractUid cookie scrape", () => {
+  it("王者荣耀: openid > uin > tencent_uid", () => {
+    const c = new HonorOfKingsApiClient();
+    expect(c.extractUid("openid=oABC1234XYZ; foo=bar")).toBe("oABC1234XYZ");
+    expect(c.extractUid("uin=o0012345; x=y")).toBe("12345");
+    expect(c.extractUid("tencent_uid=678; z=1")).toBe("678");
+    expect(c.extractUid("foo=bar")).toBeNull();
+    expect(c.lastError.code).toBe(-7);
+  });
+
+  it("作业帮: uid / student_id / passport_uid (opaque ZYBUSS → null)", () => {
+    const c = new ZuoyebangApiClient();
+    expect(c.extractUid("uid=111; ZYBUSS=opaque")).toBe("111");
+    expect(c.extractUid("student_id=222")).toBe("222");
+    expect(c.extractUid("ZYBUSS=onlyopaquetoken")).toBeNull();
+  });
+
+  it("支付宝: alipay_uid / userId / loginUserId", () => {
+    const c = new AlipayApiClient();
+    expect(c.extractUid("alipay_uid=2088123; t=x")).toBe("2088123");
+    expect(c.extractUid("userId=999")).toBe("999");
+    expect(c.extractUid("ALIPAYJSESSIONID=abc")).toBeNull();
+  });
+
+  it("华为学习中心: accountId / userId / huaweiUid", () => {
+    const c = new HuaweiLearningApiClient();
+    expect(c.extractUid("accountId=555; deviceId=abc")).toBe("555");
+    expect(c.extractUid("huaweiUid=777")).toBe("777");
+    expect(c.extractUid("deviceId=nonnumeric")).toBeNull();
+  });
+});

package/__tests__/adapters/game-genshin-scaffold.test.js

@@ -0,0 +1,107 @@
+/**
+ * FAMILY-23 v0.1 — game-genshin adapter scaffold tests.
+ * 契约 + extractUid cookie scrape + snapshot sync + normalize → 合法 batch。
+ */
+import { describe, it, expect } from "vitest";
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { GenshinAdapter } = require("../../lib");
+const { GenshinApiClient } = require("../../lib/adapters/game-genshin/api-client");
+const { assertAdapter } = require("../../lib/adapter-spec");
+const { validateBatch } = require("../../lib/batch");
+
+function writeSnapshot(obj) {
+  const p = path.join(
+    os.tmpdir(),
+    `genshin-snap-${Date.now()}-${Math.random().toString(36).slice(2)}.json`,
+  );
+  fs.writeFileSync(p, JSON.stringify(obj), "utf-8");
+  return p;
+}
+
+describe("GenshinAdapter — FAMILY-23 v0.1 cookie-scrape placeholder", () => {
+  it("contract conformance + sensitivity medium", () => {
+    const a = new GenshinAdapter();
+    expect(assertAdapter(a).ok).toBe(true);
+    expect(a.name).toBe("game-genshin");
+    expect(a.version).toBe("0.1.0");
+    expect(a.extractMode).toBe("web-api");
+    expect(a.dataDisclosure.sensitivity).toBe("medium");
+    expect(a.capabilities).toContain("sync:snapshot");
+  });
+
+  it("extractUid parses HoYoLAB cookie keys (priority + null)", () => {
+    const c = new GenshinApiClient();
+    expect(c.extractUid("account_id_v2=12345; ltoken_v2=abc")).toBe("12345");
+    expect(c.extractUid("ltuid_v2=67890; foo=bar")).toBe("67890");
+    expect(c.extractUid("account_id=111; x=y")).toBe("111");
+    expect(c.extractUid("ltuid=222")).toBe("222");
+    // 优先级: account_id_v2 先于 ltuid
+    expect(c.extractUid("ltuid=999; account_id_v2=12345")).toBe("12345");
+    expect(c.extractUid("foo=bar")).toBeNull();
+    expect(c.lastError.code).toBe(-7);
+    expect(c.extractUid("")).toBeNull();
+    expect(c.lastError.code).toBe(-1);
+  });
+
+  it("sync throws NO_INPUT without inputPath (v0.1 no live HTTP)", async () => {
+    const a = new GenshinAdapter();
+    await expect(async () => {
+      for await (const _ of a.sync({})) void _;
+    }).rejects.toThrow(/inputPath/);
+  });
+
+  it("sync via snapshot yields profile + play raws", async () => {
+    const snapPath = writeSnapshot({
+      schemaVersion: 1,
+      snapshottedAt: 1700000000000,
+      account: { uid: "12345", displayName: "旅行者" },
+      events: [
+        { kind: "profile", id: "profile-12345", uid: "12345", nickname: "旅行者", level: 58 },
+        { kind: "play", id: "play-s1", durationMs: 3600000, mode: "single", startAt: 1700000000000 },
+      ],
+    });
+    try {
+      const a = new GenshinAdapter();
+      const raws = [];
+      for await (const r of a.sync({ inputPath: snapPath })) raws.push(r);
+      expect(raws).toHaveLength(2);
+      expect(raws[0].kind).toBe("profile");
+      expect(raws[0].originalId).toBe("genshin:profile:profile-12345");
+      expect(raws[1].kind).toBe("play");
+    } finally {
+      fs.unlinkSync(snapPath);
+    }
+  });
+
+  it("normalize profile → person-self with genshin-uid; play → MEDIA event (valid batch)", () => {
+    const a = new GenshinAdapter();
+    const profileBatch = a.normalize({
+      adapter: "game-genshin",
+      kind: "profile",
+      originalId: "genshin:profile:profile-12345",
+      capturedAt: 1700000000000,
+      payload: { kind: "profile", uid: "12345", nickname: "旅行者", level: 58 },
+    });
+    expect(validateBatch(profileBatch).valid).toBe(true);
+    expect(profileBatch.persons[0].subtype).toBe("self");
+    expect(profileBatch.persons[0].identifiers["genshin-uid"]).toEqual(["12345"]);
+
+    const playBatch = a.normalize({
+      adapter: "game-genshin",
+      kind: "play",
+      originalId: "genshin:play:play-s1",
+      capturedAt: 1700000000000,
+      payload: { kind: "play", durationMs: 3600000, mode: "single", startAt: 1700000000000 },
+    });
+    expect(validateBatch(playBatch).valid).toBe(true);
+    expect(playBatch.events[0].subtype).toBe("media");
+    expect(playBatch.events[0].extra.durationMs).toBe(3600000);
+  });
+
+  it("normalize throws on missing payload", () => {
+    const a = new GenshinAdapter();
+    expect(() => a.normalize({})).toThrow(/payload missing/);
+  });
+});

package/__tests__/adapters/git-activity.test.js

@@ -1,11 +1,17 @@
 "use strict";
 
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
 import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { execFileSync } from "node:child_process";
 
+// Every test here spawns real `git` (init/config/commit) across throwaway
+// repos. On Windows, under the full-suite parallel worker pool, that subprocess
+// fan-out routinely blows past the 10s default and flakes. Give the whole file
+// generous headroom — the work is real, the default timeout is just too tight.
+vi.setConfig({ testTimeout: 30000, hookTimeout: 30000 });
+
 const {
   GitActivityAdapter,
   GIT_ACTIVITY_NAME,