@chainlesschain/personal-data-hub 0.3.6 → 0.3.8

package/__tests__/query-parser.test.js

@@ -7,7 +7,9 @@ const {
   parseTimeWindow,
   parseFilters,
   parseIntent,
+  parseEntityFocus,
   extractEntityTerm,
+  extractPersonNameCandidate,
 } = require("../lib/query-parser");
 
 // Pin "now" to 2026-05-19 12:00:00 UTC for deterministic windows
@@ -126,6 +128,38 @@ describe("parseIntent", () => {
   });
 });
 
+describe("parseEntityFocus", () => {
+  it("returns 'persons' for 联系人 / 通讯录 phrasing", () => {
+    expect(parseEntityFocus("我有哪些联系人")).toBe("persons");
+    expect(parseEntityFocus("通讯录里有多少人")).toBe("persons");
+    expect(parseEntityFocus("好友列表谁是张三")).toBe("persons");
+  });
+
+  it("returns 'persons' for phone-number phrasing", () => {
+    expect(parseEntityFocus("妈手机号是多少")).toBe("persons");
+    expect(parseEntityFocus("王医生的电话号码")).toBe("persons");
+    expect(parseEntityFocus("show me my contacts")).toBe("persons");
+  });
+
+  it("returns 'items' for installed-app phrasing", () => {
+    expect(parseEntityFocus("我装了哪些 app")).toBe("items");
+    expect(parseEntityFocus("有哪些游戏")).toBe("items");
+    expect(parseEntityFocus("installed apps")).toBe("items");
+  });
+
+  it("returns null when no focus signal", () => {
+    expect(parseEntityFocus("上个月在淘宝花了多少")).toBeNull();
+    expect(parseEntityFocus("最近的订单")).toBeNull();
+    expect(parseEntityFocus("hello")).toBeNull();
+  });
+
+  it("returns null for non-string / empty input", () => {
+    expect(parseEntityFocus("")).toBeNull();
+    expect(parseEntityFocus(null)).toBeNull();
+    expect(parseEntityFocus(undefined)).toBeNull();
+  });
+});
+
 describe("parseQuery (integration)", () => {
   it("full parse for spending question", () => {
     const r = parseQuery("上个月在淘宝总共花了多少钱？", { now: NOW });
@@ -133,6 +167,13 @@ describe("parseQuery (integration)", () => {
     expect(r.filters.subtype).toBe("payment");
     expect(r.filters.adapter).toBe("taobao");
     expect(r.intent).toBe("sum-amount");
+    expect(r.entityFocus).toBeNull();
+  });
+
+  it("contact question carries entityFocus=persons", () => {
+    const r = parseQuery("我有哪些联系人", { now: NOW });
+    expect(r.entityFocus).toBe("persons");
+    expect(r.intent).toBe("list");
   });
 
   it("full parse for footprint question", () => {
@@ -214,3 +255,48 @@ describe("extractEntityTerm", () => {
     expect(r).toBeNull();
   });
 });
+
+// ─── extractPersonNameCandidate — persons-branch name search ─────────────
+//
+// 2026-05-27 — Powers AnalysisEngine entityFocus=persons name-search
+// short-circuit. Differs from extractEntityTerm in two ways: strips
+// person-FOCUS framing words first (联系人/手机号/etc.) and allows
+// single-char Chinese names from a relation whitelist (妈/爸/姐/...).
+
+describe("extractPersonNameCandidate", () => {
+  it("extracts multi-char name when present", () => {
+    expect(extractPersonNameCandidate("张三的电话号码")).toBe("张三");
+    expect(extractPersonNameCandidate("王医生手机号是多少")).toBe("王医生");
+  });
+
+  it("falls back to single-char relation word ('妈', '爸', '姐')", () => {
+    expect(extractPersonNameCandidate("妈手机号是多少")).toBe("妈");
+    expect(extractPersonNameCandidate("爸的电话")).toBe("爸");
+    expect(extractPersonNameCandidate("姐姐的号码")).toBe("姐姐");
+  });
+
+  it("multi-char wins over single-char fallback", () => {
+    // "王医生" (3 char) preferred over leaked single "医" / "生".
+    expect(extractPersonNameCandidate("王医生的手机号")).toBe("王医生");
+  });
+
+  it("returns null when no name candidate (pure framing)", () => {
+    expect(extractPersonNameCandidate("我有哪些联系人")).toBeNull();
+    expect(extractPersonNameCandidate("通讯录里有多少人")).toBeNull();
+  });
+
+  it("ignores single-char Chinese outside the relation whitelist", () => {
+    // "说" / "看" are not relation chars — should NOT slip through as names.
+    expect(extractPersonNameCandidate("说手机号")).toBeNull();
+  });
+
+  it("returns null for non-string / empty input", () => {
+    expect(extractPersonNameCandidate("")).toBeNull();
+    expect(extractPersonNameCandidate(null)).toBeNull();
+    expect(extractPersonNameCandidate(undefined)).toBeNull();
+  });
+
+  it("handles ASCII names ≥2 chars", () => {
+    expect(extractPersonNameCandidate("Alice 的电话号码")).toBe("Alice");
+  });
+});

package/__tests__/vault.test.js

@@ -425,6 +425,94 @@ describe("LocalVault.queryEvents + countEvents", () => {
   });
 });
 
+// ─── searchPersons (LIKE name search) ────────────────────────────────────
+//
+// 2026-05-27 — AnalysisEngine entityFocus="persons" routes to searchPersons
+// when the question carries a name candidate ("妈手机号", "张三的电话").
+// LIKE on names / identifiers / notes / relation, no FTS5 migration.
+
+describe("LocalVault.searchPersons", () => {
+  it("matches against names column (JSON-serialized array)", () => {
+    freshVault();
+    vault.putPerson(personOk({ names: ["妈妈", "陈某某"] }));
+    vault.putPerson(personOk({ names: ["张三"] }));
+    vault.putPerson(personOk({ names: ["王医生"] }));
+
+    const r = vault.searchPersons({ q: "妈" });
+    expect(r.length).toBe(1);
+    expect(r[0].names).toContain("妈妈");
+  });
+
+  it("matches against identifiers (phone numbers)", () => {
+    freshVault();
+    vault.putPerson(personOk({
+      names: ["张三"],
+      identifiers: { phone: ["13800001111"] },
+    }));
+    vault.putPerson(personOk({
+      names: ["李四"],
+      identifiers: { phone: ["13900002222"] },
+    }));
+
+    const r = vault.searchPersons({ q: "13800" });
+    expect(r.length).toBe(1);
+    expect(r[0].names).toContain("张三");
+  });
+
+  it("matches against notes + relation", () => {
+    freshVault();
+    vault.putPerson(personOk({
+      names: ["陈某某"], relation: "母亲", notes: "best mom ever",
+    }));
+    vault.putPerson(personOk({ names: ["路人甲"], relation: "stranger" }));
+
+    expect(vault.searchPersons({ q: "母亲" }).length).toBe(1);
+    expect(vault.searchPersons({ q: "best mom" }).length).toBe(1);
+  });
+
+  it("empty q delegates to queryPersons (ingest-ordered)", () => {
+    freshVault();
+    vault.putPerson(personOk({ names: ["A"] }));
+    vault.putPerson(personOk({ names: ["B"] }));
+    vault.putPerson(personOk({ names: ["C"] }));
+
+    const r = vault.searchPersons({ q: "", limit: 2 });
+    expect(r.length).toBe(2);
+  });
+
+  it("LIKE meta-characters in user input are escaped (no wildcard injection)", () => {
+    freshVault();
+    vault.putPerson(personOk({ names: ["100%棉"] }));
+    vault.putPerson(personOk({ names: ["AAA"] }));
+
+    // "100%" should match only the literal "100%棉" row, not everything.
+    const r = vault.searchPersons({ q: "100%" });
+    expect(r.length).toBe(1);
+    expect(r[0].names).toContain("100%棉");
+  });
+
+  it("respects subtype + adapter filters", () => {
+    freshVault();
+    vault.putPerson(personOk({
+      subtype: "contact", names: ["张三"],
+      source: source({ adapter: "wechat" }),
+    }));
+    vault.putPerson(personOk({
+      subtype: "merchant", names: ["张三"],
+      source: source({ adapter: "system-data-android" }),
+    }));
+
+    expect(vault.searchPersons({ q: "张三", subtype: "merchant" }).length).toBe(1);
+    expect(vault.searchPersons({ q: "张三", adapter: "wechat" }).length).toBe(1);
+  });
+
+  it("returns empty array when no match", () => {
+    freshVault();
+    vault.putPerson(personOk({ names: ["张三"] }));
+    expect(vault.searchPersons({ q: "完全不存在的名字" })).toEqual([]);
+  });
+});
+
 // ─── sync watermarks ──────────────────────────────────────────────────────
 
 describe("LocalVault sync watermarks", () => {

package/lib/adapters/ai-chat-history/health-checker.js

@@ -172,7 +172,18 @@ function createAIChatHealthChecker({
           deps.logger.error("[aichat-health] interval run failed", err && err.message),
         );
       }, intervalMs);
+      // Don't keep the event loop alive on the periodic check alone. Without
+      // unref a one-shot `cc hub list-adapters --json` from in-APK Android
+      // sits idle in epoll_wait until Kotlin LocalCcRunner.waitFor 240s
+      // timeout → false "写入本地数据库失败". Real-device repro 2026-05-27
+      // Xiaomi 24115RA8EC (PID 24828 lingered with vault.db RW handles).
+      if (intervalHandle && typeof intervalHandle.unref === "function") {
+        intervalHandle.unref();
+      }
     }, firstRunDelayMs);
+    if (firstRunHandle && typeof firstRunHandle.unref === "function") {
+      firstRunHandle.unref();
+    }
     return true;
   }
 

package/lib/adapters/social-kuaishou-adb/api-client.js

@@ -0,0 +1,397 @@
+"use strict";
+
+/**
+ * Phase 6d (Kuaishou C 路径 — 2026-05-25): Node-side KuaishouApiClient.
+ *
+ * Byte-parity port of KuaishouApiClient.kt. **Profile from cookie (no
+ * HTTP) + 3 GraphQL POST endpoints (all signed)**:
+ *   - `kuaishou.web.cp.api_ph` cookie payload → ProfileInfo (parseProfileFromCookie)
+ *   - `/graphql` visionFeedRecommend  — watch history (signed)
+ *   - `/graphql` visionProfilePhotoList — user's posted photos (signed)
+ *   - `/graphql` visionSearchPhoto   — search history (signed)
+ *
+ * **signProvider injection (Phase 6d)**: defaults to NULL_SIGN_PROVIDER —
+ * signUrl returns null, so the 3 signed endpoints short-circuit with
+ * lastErrorCode=-99. Desktop wiring injects KuaishouSignBridge.
+ *
+ * **GraphQL nuances**:
+ *   - POST `/graphql` with body `{operationName, variables, query}`
+ *   - Body MUST match exactly what was signed (NS_sig3 hashes body bytes)
+ *   - signedHeaders returns kpf/kpn that must be sent verbatim
+ *
+ * **Anti-bot signal**: User-Agent must be desktop Chrome 120+. Referer +
+ * Origin = https://www.kuaishou.com/. Without `kpf`/`kpn` headers
+ * GraphQL endpoint returns 403/Errors.
+ */
+
+const { NULL_SIGN_PROVIDER } = require("../../sign-providers");
+
+const DEFAULT_BASE_URL = "https://www.kuaishou.com/";
+
+const BROWSER_UA =
+  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 " +
+  "(KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36";
+
+const BROWSER_HEADERS = Object.freeze({
+  "User-Agent": BROWSER_UA,
+  Referer: "https://www.kuaishou.com/",
+  Origin: "https://www.kuaishou.com",
+  Accept: "application/json, text/plain, */*",
+  "Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8",
+  "Content-Type": "application/json",
+});
+
+const OP_FEED_RECOMMEND = "visionFeedRecommend";
+const OP_PROFILE_PHOTOS = "visionProfilePhotoList";
+const OP_SEARCH_PHOTO = "visionSearchPhoto";
+
+function normalizeMs(v) {
+  if (typeof v !== "number" || !Number.isFinite(v) || v <= 0) return 0;
+  return v > 1e12 ? v : v * 1000;
+}
+
+class KuaishouApiClient {
+  constructor(opts = {}) {
+    this.baseUrl = opts.baseUrl || DEFAULT_BASE_URL;
+    if (!this.baseUrl.endsWith("/")) this.baseUrl += "/";
+    this._fetch = opts.fetch || globalThis.fetch;
+    if (typeof this._fetch !== "function") {
+      throw new Error(
+        "KuaishouApiClient: fetch not available — pass opts.fetch or run on Node 18+",
+      );
+    }
+    this._now = opts.now || Date.now;
+    this.signProvider = opts.signProvider || NULL_SIGN_PROVIDER;
+    this.lastErrorCode = 0;
+    this.lastErrorMessage = null;
+    this._bridgeHits = 0;
+    this._fallbackHits = 0;
+  }
+
+  /**
+   * Extract uid from cookie. Mirror of Kotlin extractUid:
+   *   1. `userId=N` direct cookie
+   *   2. Nested user_id / uid / userId inside `kuaishou.web.cp.api_ph`
+   *      URL-encoded JSON
+   */
+  extractUid(cookie) {
+    if (typeof cookie !== "string" || cookie.length === 0) {
+      this._setLastError(-1, "cookie 为空");
+      return null;
+    }
+    const direct = /(?:^|; ?)userId=(\d+)/.exec(cookie);
+    if (direct && direct[1] && direct[1] !== "0") {
+      this._clearLastError();
+      return direct[1];
+    }
+    const cpMatch = /(?:^|; ?)kuaishou\.web\.cp\.api_ph=([^;]+)/.exec(cookie);
+    if (cpMatch && cpMatch[1]) {
+      const embedded = extractEmbeddedUid(cpMatch[1]);
+      if (embedded) {
+        this._clearLastError();
+        return embedded;
+      }
+    }
+    this._setLastError(
+      -7,
+      "cookie 缺 userId / kuaishou.web.cp.api_ph 嵌套 user_id — 登录未完成或仅游客态",
+    );
+    return null;
+  }
+
+  /**
+   * Parse profile from cookie's `kuaishou.web.cp.api_ph` URL-encoded JSON.
+   * NO HTTP — this is purely cookie-derived (Kuaishou's passport writes
+   * the full profile JSON into the cookie at login time).
+   *
+   * Returns null if api_ph absent / un-decodable / lacks user_id.
+   */
+  async fetchProfile(cookie) {
+    if (typeof cookie !== "string" || cookie.length === 0) {
+      this._setLastError(-1, "cookie 为空");
+      return null;
+    }
+    const cpMatch = /(?:^|; ?)kuaishou\.web\.cp\.api_ph=([^;]+)/.exec(cookie);
+    if (!cpMatch || !cpMatch[1]) {
+      this._setLastError(
+        -8,
+        "cookie 缺 kuaishou.web.cp.api_ph (profile 解析需要)",
+      );
+      return null;
+    }
+    let decoded;
+    try {
+      decoded = decodeURIComponent(cpMatch[1]);
+    } catch {
+      decoded = cpMatch[1];
+    }
+    const trimmed = decoded.trimStart();
+    if (!trimmed.startsWith("{")) {
+      this._setLastError(
+        -9,
+        "kuaishou.web.cp.api_ph 解码后非 JSON (likely base64 — v0.3 加 fallback)",
+      );
+      return null;
+    }
+    let obj;
+    try {
+      obj = JSON.parse(decoded);
+    } catch (e) {
+      this._setLastError(-3, "parse: " + (e.message || String(e)));
+      return null;
+    }
+    const uid =
+      pickString(obj.user_id) ||
+      pickString(obj.userId) ||
+      (Number.isFinite(obj.user_id) && obj.user_id > 0 && String(obj.user_id)) ||
+      (Number.isFinite(obj.userId) && obj.userId > 0 && String(obj.userId)) ||
+      null;
+    if (!uid || uid === "0") {
+      this._setLastError(
+        -7,
+        `api_ph JSON 缺 user_id (keys=[${Object.keys(obj).join(",")}])`,
+      );
+      return null;
+    }
+    this._clearLastError();
+    return {
+      uid,
+      nickname:
+        pickString(obj.user_name) ||
+        pickString(obj.userName) ||
+        pickString(obj.nickname) ||
+        "(unnamed)",
+      kuaishouId:
+        pickString(obj.kuaishou_id) || pickString(obj.kuaishouId) || null,
+      avatarUrl:
+        pickString(obj.headurl) ||
+        pickString(obj.headUrl) ||
+        pickString(obj.avatar) ||
+        null,
+      sex: pickString(obj.sex) || pickString(obj.gender) || null,
+      city: pickString(obj.city) || null,
+      constellation: pickString(obj.constellation) || null,
+      description:
+        pickString(obj.description) || pickString(obj.signature) || null,
+    };
+  }
+
+  async _signedGraphQL(cookie, operationName, variables) {
+    const body = JSON.stringify({
+      operationName,
+      variables,
+      query: "",
+    });
+    const rawUrl = new URL("graphql", this.baseUrl);
+    const purpose = `${operationName}|${body}`;
+    // signProvider.signUrl + signedHeaders sequential. KuaishouSignBridge
+    // caches kpf/kpn from signUrl call so signedHeaders returns them.
+    const signedUrl = await this.signProvider.signUrl(rawUrl, purpose);
+    if (!signedUrl) {
+      this._setLastError(
+        -99,
+        "__NS_sig3 unavailable (signProvider returned null — bridge not warm or rotated)",
+      );
+      this._fallbackHits += 1;
+      return null;
+    }
+    const extraHeaders = await this.signProvider.signedHeaders(rawUrl, purpose);
+    this._bridgeHits += 1;
+    const headers = { ...BROWSER_HEADERS, ...extraHeaders, Cookie: cookie };
+    try {
+      const resp = await this._fetch(signedUrl.toString(), {
+        method: "POST",
+        headers,
+        body,
+      });
+      const respBody = await resp.text();
+      if (!resp.ok) {
+        this._setLastError(resp.status, `HTTP ${resp.status}`);
+        return null;
+      }
+      const trimmed = respBody.trimStart();
+      if (!trimmed.startsWith("{")) {
+        this._setLastError(
+          -4,
+          "non-json (cookie expired or anti-bot triggered)",
+        );
+        return null;
+      }
+      let obj;
+      try {
+        obj = JSON.parse(respBody);
+      } catch (e) {
+        this._setLastError(-3, "parse: " + (e.message || String(e)));
+        return null;
+      }
+      // GraphQL errors come back as {errors: [...]} with HTTP 200.
+      if (Array.isArray(obj.errors) && obj.errors.length > 0) {
+        const first = obj.errors[0];
+        const msg = (first && first.message) || "graphql error";
+        this._setLastError(-5, "graphql: " + msg);
+        return null;
+      }
+      this._clearLastError();
+      return obj.data || null;
+    } catch (e) {
+      this._setLastError(-2, "IO: " + (e.message || String(e)));
+      return null;
+    }
+  }
+
+  /**
+   * /graphql visionFeedRecommend — watch history (recommended feed user
+   * dwelled on). Requires __NS_sig3.
+   */
+  async fetchWatchHistory(cookie, opts = {}) {
+    const limit =
+      Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : 50;
+    const data = await this._signedGraphQL(cookie, OP_FEED_RECOMMEND, {
+      pcursor: "",
+      count: limit,
+    });
+    if (!data) return [];
+    const feeds =
+      (data.visionFeedRecommend && data.visionFeedRecommend.feeds) || [];
+    return extractPhotoList(feeds, limit, (item, photo, photoId, caption, ts) => ({
+      photoId,
+      caption,
+      authorName:
+        (item.author && item.author.name) || null,
+      authorId:
+        (item.author && item.author.id) || null,
+      viewedAt: ts,
+      duration: Number.isFinite(photo.duration) ? photo.duration : 0,
+    }));
+  }
+
+  /**
+   * /graphql visionProfilePhotoList — user's own posted photos. Requires
+   * __NS_sig3.
+   */
+  async fetchProfilePhotos(cookie, userId, opts = {}) {
+    const limit =
+      Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : 100;
+    const data = await this._signedGraphQL(cookie, OP_PROFILE_PHOTOS, {
+      userId,
+      pcursor: "",
+      count: limit,
+      page: "profile",
+    });
+    if (!data) return [];
+    const feeds =
+      (data.visionProfilePhotoList && data.visionProfilePhotoList.feeds) || [];
+    return extractPhotoList(feeds, limit, (_item, _photo, photoId, caption, ts) => ({
+      photoId,
+      caption,
+      postedAt: ts,
+    }));
+  }
+
+  /**
+   * /graphql visionSearchPhoto — user's recent search keywords. Requires
+   * __NS_sig3.
+   *
+   * Two response shapes observed: data.recentSearchList vs data.history.
+   */
+  async fetchSearchHistory(cookie, opts = {}) {
+    const limit =
+      Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : 50;
+    const data = await this._signedGraphQL(cookie, OP_SEARCH_PHOTO, {
+      keyword: "",
+      pcursor: "",
+      page: "search",
+    });
+    if (!data) return [];
+    const root = data.visionSearchPhoto || {};
+    const arr = Array.isArray(root.recentSearchList)
+      ? root.recentSearchList
+      : Array.isArray(root.history)
+        ? root.history
+        : [];
+    const out = [];
+    const cap = Math.min(limit, arr.length);
+    const now = this._now();
+    for (let i = 0; i < cap; i++) {
+      const raw = arr[i];
+      let keyword = null;
+      let ts = 0;
+      if (raw && typeof raw === "object") {
+        keyword = raw.keyword || raw.query || null;
+        ts = normalizeMs(raw.time || raw.searchTime || 0);
+      } else if (typeof raw === "string") {
+        keyword = raw;
+        ts = now - i * 1000;
+      }
+      if (!keyword) continue;
+      out.push({ keyword, searchedAt: ts });
+    }
+    return out;
+  }
+
+  _setLastError(code, message) {
+    this.lastErrorCode = code;
+    this.lastErrorMessage = message;
+  }
+  _clearLastError() {
+    this.lastErrorCode = 0;
+    this.lastErrorMessage = null;
+  }
+}
+
+function extractPhotoList(feeds, limit, build) {
+  if (!Array.isArray(feeds)) return [];
+  const out = [];
+  const cap = Math.min(limit, feeds.length);
+  for (let i = 0; i < cap; i++) {
+    const item = feeds[i];
+    if (!item || typeof item !== "object") continue;
+    // Kuaishou GraphQL nests the photo under `photo`; flat fallback.
+    const photo =
+      item.photo && typeof item.photo === "object" ? item.photo : item;
+    const photoId = pickString(photo.id);
+    if (!photoId) continue;
+    const caption = pickString(photo.caption) || "(no caption)";
+    const ts = normalizeMs(photo.timestamp || photo.createTime || 0);
+    const built = build(item, photo, photoId, caption, ts);
+    if (built) out.push(built);
+  }
+  return out;
+}
+
+function extractEmbeddedUid(cpRaw) {
+  let decoded;
+  try {
+    decoded = decodeURIComponent(cpRaw);
+  } catch {
+    decoded = cpRaw;
+  }
+  for (const pat of [
+    /"?user_id"?\s*:\s*"?(\d+)"?/,
+    /"?uid"?\s*:\s*"?(\d+)"?/,
+    /"?userId"?\s*:\s*"?(\d+)"?/,
+  ]) {
+    const m = pat.exec(decoded);
+    if (m && m[1] && m[1] !== "0") return m[1];
+  }
+  return null;
+}
+
+function pickString(v) {
+  if (typeof v !== "string") return null;
+  return v.length > 0 ? v : null;
+}
+
+module.exports = {
+  KuaishouApiClient,
+  _internals: {
+    BROWSER_UA,
+    BROWSER_HEADERS,
+    OP_FEED_RECOMMEND,
+    OP_PROFILE_PHOTOS,
+    OP_SEARCH_PHOTO,
+    normalizeMs,
+    extractPhotoList,
+    extractEmbeddedUid,
+  },
+};