@chainlesschain/personal-data-hub 0.4.4 → 0.4.5

package/lib/adapters/edu-huawei-learning/api-client.js

@@ -1,15 +1,37 @@
 /**
- * HuaweiLearningApiClient — FAMILY-23 v0.1 cookie-scrape（无签名）。
+ * HuaweiLearningApiClient — FAMILY-23 华为学习中心采集客户端。
  *
- * 华为学习中心走华为账号登录；v0.1 从 accountId / userId / huaweiUid 抽数字 uid。
- * 课程/学习时长 走 v0.2（华为教育接口 + 账号签名）。
+ * 华为学习中心走华为账号登录；v0.1 仅 cookie-scrape（extractUid，从 accountId /
+ * userId / huaweiUid 抽数字 uid）。**v0.2 接通 live HTTP fetcher**：cookie（华为
+ * 账号 web 会话）直拉 用户信息 + 课程学习记录（课程名 / 学习时长）。
+ *
+ * ⚠️ **best-effort**：学习中心接口无公开稳定文档，下方端点/字段按 hicloud 教育
+ *    服务常见形态实现（envelope `{code|resultCode, message, data}`，0 = ok），
+ *    做了多字段名兼容（pick 回退），**未经真实华为账号登录态实地验证** —
+ *    端点/字段漂移时改常量 / opts 覆盖（同 SignProvider 轮转思路）。
  */
 "use strict";
 
+const { pick, toDurationMs, toEpochMs } = require("../_live-json-helpers");
+
+const DEFAULT_BASE_URL = "https://educenter.hicloud.com";
+// 端点（best-effort，可经 opts 覆盖）。
+const PATH_USER_INFO = "/edu/api/user/v1/info";
+const PATH_STUDY_RECORDS = "/edu/api/study/v1/records";
+
+const BROWSER_UA =
+  "Mozilla/5.0 (Linux; Android 12; HarmonyOS) AppleWebKit/537.36 " +
+  "(KHTML, like Gecko) Chrome/114.0.0.0 Mobile Safari/537.36";
+
 class HuaweiLearningApiClient {
-  constructor() {
+  constructor(opts = {}) {
     this._lastErrorCode = 0;
     this._lastErrorMsg = "";
+    this._fetch =
+      opts.fetch || (typeof globalThis.fetch === "function" ? globalThis.fetch : null);
+    this.baseUrl = (opts.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.userInfoPath = opts.userInfoPath || PATH_USER_INFO;
+    this.studyRecordsPath = opts.studyRecordsPath || PATH_STUDY_RECORDS;
   }
   _setLastError(code, msg) {
     this._lastErrorCode = code;
@@ -42,6 +64,157 @@ class HuaweiLearningApiClient {
     );
     return null;
   }
+
+  /**
+   * live 模式会话探测：华为账号 web 会话 key 形态不稳定（CAS / OAuth 多变体），
+   * 宽松判定 — 有任意 `k=v` 形态的非空 cookie 即放行，真伪交给服务端校验。
+   * @param {string} cookie @returns {boolean}
+   */
+  hasSession(cookie) {
+    if (typeof cookie !== "string" || !/[^=;\s]+=[^;\s]+/.test(cookie)) {
+      this._setLastError(-7, "cookie 为空或非法 — 华为账号未登录");
+      return false;
+    }
+    this._clearLastError();
+    return true;
+  }
+
+  _headers(cookie) {
+    return {
+      Cookie: cookie,
+      "User-Agent": BROWSER_UA,
+      Referer: `${this.baseUrl}/`,
+      Accept: "application/json",
+    };
+  }
+
+  /**
+   * GET <url> with cookie. Parses `{ code|resultCode, message, data }`
+   * (0 = ok). Returns `data` on success, null on error (sets lastError).
+   */
+  async _doGetJson(url, cookie) {
+    if (typeof this._fetch !== "function") {
+      this._setLastError(
+        -2,
+        "HuaweiLearningApiClient: fetch not available — pass opts.fetch or run on Node 18+",
+      );
+      return null;
+    }
+    let resp;
+    try {
+      resp = await this._fetch(url, { method: "GET", headers: this._headers(cookie) });
+    } catch (e) {
+      this._setLastError(-4, "network: " + (e && e.message ? e.message : String(e)));
+      return null;
+    }
+    const txt = await resp.text();
+    if (!resp.ok) {
+      this._setLastError(resp.status, `HTTP ${resp.status}`);
+      return null;
+    }
+    let obj;
+    try {
+      obj = JSON.parse(txt);
+    } catch (e) {
+      this._setLastError(-3, "parse: " + (e && e.message ? e.message : String(e)));
+      return null;
+    }
+    const code = pick(obj, ["code", "resultCode", "errorCode"], 0);
+    if (Number(code) !== 0) {
+      this._setLastError(
+        Number(code),
+        pick(obj, ["message", "msg", "desc", "errorMsg"], `code ${code}`).toString(),
+      );
+      return null;
+    }
+    this._clearLastError();
+    const data = pick(obj, ["data", "result", "value"]);
+    return data !== null ? data : obj;
+  }
+
+  /** 用户信息 → { uid, nickname } or null. */
+  async getUserInfo(cookie) {
+    const data = await this._doGetJson(`${this.baseUrl}${this.userInfoPath}`, cookie);
+    if (data === null) return null;
+    const u = pick(data, ["user", "userInfo", "account"], data);
+    const uid = pick(u, ["uid", "userId", "accountId"]);
+    return {
+      uid: uid != null ? String(uid) : null,
+      nickname: pick(u, ["nickName", "nickname", "displayName", "userName", "name"]),
+    };
+  }
+
+  /**
+   * 课程学习记录 → [{ recordId, course, durationMs, startAt }]. null on error.
+   * @param {string} cookie
+   * @param {object} [opts] { limit, offset }
+   */
+  async getStudyRecords(cookie, opts = {}) {
+    const limit = Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : 20;
+    const offset = Number.isInteger(opts.offset) && opts.offset > 0 ? opts.offset : 0;
+    const url = `${this.baseUrl}${this.studyRecordsPath}?offset=${offset}&limit=${limit}`;
+    const data = await this._doGetJson(url, cookie);
+    if (data === null) return null;
+    const list = pick(data, ["records", "list", "items"], Array.isArray(data) ? data : []);
+    if (!Array.isArray(list)) return [];
+    return list.map((r) => ({
+      recordId: pick(r, ["recordId", "id", "logId"]),
+      course: pick(r, ["courseName", "course", "title", "name"]),
+      durationMs: toDurationMs(
+        pick(r, ["studyDuration", "duration", "learnTime", "durationMs"], 0),
+      ),
+      startAt: toEpochMs(pick(r, ["startTime", "studyTime", "createTime", "beginTime"])),
+    }));
+  }
+
+  /**
+   * High-level: user info + study records → snapshot-shaped { account, events }
+   * so the adapter normalize path is unchanged.
+   * @returns {Promise<{account, events}|null>}
+   */
+  async fetchSnapshot(cookie, opts = {}) {
+    if (!this.hasSession(cookie)) return null; // lastError already set
+    const include = opts.include || {};
+    const events = [];
+    let account = null;
+
+    if (include.profile !== false) {
+      const user = await this.getUserInfo(cookie);
+      if (user === null) return null;
+      account = { uid: user.uid, displayName: user.nickname };
+      events.push({
+        kind: "profile",
+        id: user.uid ? `profile-${user.uid}` : null,
+        uid: user.uid,
+        nickname: user.nickname,
+      });
+    }
+
+    if (include.study !== false) {
+      const records = await this.getStudyRecords(cookie, {
+        limit: opts.limit,
+        offset: opts.offset,
+      });
+      if (records === null) return null;
+      for (const r of records) {
+        events.push({
+          kind: "study",
+          id: r.recordId ? `study-${r.recordId}` : null,
+          course: r.course,
+          durationMs: r.durationMs,
+          startAt: r.startAt,
+        });
+      }
+    }
+
+    this._clearLastError();
+    return { account, events };
+  }
 }
 
-module.exports = { HuaweiLearningApiClient };
+module.exports = {
+  HuaweiLearningApiClient,
+  // Exported for tests / endpoint introspection.
+  PATH_USER_INFO,
+  PATH_STUDY_RECORDS,
+};

package/lib/adapters/edu-huawei-learning/index.js

@@ -1,10 +1,13 @@
 /**
- * FAMILY-23 v0.1 — 华为学习中心 (Huawei Learning Center) adapter, snapshot mode.
+ * FAMILY-23 — 华为学习中心 (Huawei Learning Center) adapter.
  *
- * 家庭守护 telemetry：家长看孩子的课程/学习时长。v0.1 cookie-scrape 占位 —
- * [HuaweiLearningApiClient.extractUid] 抽 uid；snapshot 模式消费手机端 collector
- * 快照 (profile + study-session)。课程历史 HTTP fetcher 留 v0.2，故无 inputPath 时
- * sync 抛 NO_INPUT。
+ * 家庭守护 telemetry：家长看孩子的课程/学习时长。两路互补：
+ *   - snapshot 模式（inputPath）：手机端 collector 快照 (profile + study-session)。
+ *   - **live 模式（cookie，v0.2 接通）**：[HuaweiLearningApiClient.fetchSnapshot]
+ *     经学习中心接口（华为账号 web 会话 cookie）拉 用户信息 + 课程学习记录。
+ *     端点/字段无公开稳定文档，按 hicloud 教育服务常见形态实现 + 多字段名兼容，
+ *     **未实地验证**，漂移时按 api-client 常量/pick 列表调整。
+ * 无 inputPath 且无 cookie 时 sync 抛错。
  *
  * Snapshot schema (v1):
  *   { schemaVersion:1, snapshottedAt, account:{uid,displayName}, events:[
@@ -26,7 +29,7 @@ const {
 const { HuaweiLearningApiClient } = require("./api-client");
 
 const NAME = "edu-huawei-learning";
-const VERSION = "0.1.0";
+const VERSION = "0.2.0";
 const SNAPSHOT_SCHEMA_VERSION = 1;
 const KIND_PROFILE = "profile";
 const KIND_STUDY = "study";
@@ -60,6 +63,7 @@ class HuaweiLearningAdapter {
     this.version = VERSION;
     this.capabilities = [
       "sync:snapshot",
+      "sync:cookie",
       "parse:huawei-learning-profile",
       "parse:huawei-learning-study-session",
     ];
@@ -74,7 +78,10 @@ class HuaweiLearningAdapter {
       legalGate: false,
       defaultInclude: { profile: true, study: true },
     };
-    this.apiClient = new HuaweiLearningApiClient();
+    this.apiClient = new HuaweiLearningApiClient(opts);
+    // Test seam: override how the live client is built per-sync (inject fetch).
+    this._apiClientFactory =
+      typeof opts.apiClientFactory === "function" ? opts.apiClientFactory : null;
     this._deps = { fs };
   }
 
@@ -91,11 +98,21 @@ class HuaweiLearningAdapter {
       }
       return { ok: true, mode: "snapshot-file" };
     }
+    if (ctx && typeof ctx.cookie === "string" && ctx.cookie.length > 0) {
+      if (!this.apiClient.hasSession(ctx.cookie)) {
+        return {
+          ok: false,
+          reason: "INVALID_COOKIE",
+          message: `edu-huawei-learning.authenticate: ${this.apiClient.lastError.message}`,
+        };
+      }
+      return { ok: true, mode: "cookie" };
+    }
     return {
       ok: false,
       reason: "NO_INPUT",
       message:
-        "edu-huawei-learning.authenticate: v0.1 needs opts.inputPath (snapshot mode); live HTTP fetcher 待 v0.2",
+        "edu-huawei-learning.authenticate: needs opts.inputPath (snapshot mode) or opts.cookie (华为账号会话, live fetch)",
     };
   }
 
@@ -108,11 +125,68 @@ class HuaweiLearningAdapter {
       yield* this._syncViaSnapshot(opts);
       return;
     }
+    if (typeof opts.cookie === "string" && opts.cookie.length > 0) {
+      yield* this._syncViaLive(opts);
+      return;
+    }
     throw new Error(
-      "edu-huawei-learning.sync: v0.1 needs opts.inputPath (snapshot mode); 课程历史 HTTP fetcher 待 v0.2",
+      "edu-huawei-learning.sync: needs opts.inputPath (snapshot mode) or opts.cookie (华为账号会话, 课程学习记录 live fetch)",
     );
   }
 
+  async *_syncViaLive(opts) {
+    const client = this._apiClientFactory
+      ? this._apiClientFactory(opts)
+      : new HuaweiLearningApiClient({
+          fetch: opts.fetch,
+          baseUrl: opts.baseUrl,
+          userInfoPath: opts.userInfoPath,
+          studyRecordsPath: opts.studyRecordsPath,
+        });
+    const emit = (phase, extra) => {
+      if (typeof opts.onProgress === "function") {
+        try {
+          opts.onProgress({ phase, adapter: NAME, ...extra });
+        } catch (_e) {
+          /* progress callback errors are best-effort */
+        }
+      }
+    };
+    const result = await client.fetchSnapshot(opts.cookie, {
+      include: opts.include || {},
+      limit: opts.limit,
+      offset: opts.offset,
+    });
+    if (result === null) {
+      const e = client.lastError;
+      throw new Error(
+        `edu-huawei-learning.sync (live): ${e.message || "fetch failed"} (code ${e.code})`,
+      );
+    }
+    const account = result.account || null;
+    emit("fetched", { count: result.events.length });
+    const capturedAt = Date.now();
+    const limit =
+      Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : Infinity;
+    const include = opts.include || {};
+    let emitted = 0;
+    for (const ev of result.events) {
+      if (emitted >= limit) return;
+      if (!ev || !VALID_SNAPSHOT_KINDS.includes(ev.kind)) continue;
+      if (include[ev.kind] === false) continue;
+      const id =
+        (typeof ev.id === "string" && ev.id.length > 0 && ev.id) || ev.uid || null;
+      yield {
+        adapter: NAME,
+        kind: ev.kind,
+        originalId: stableOriginalId(ev.kind, id),
+        capturedAt,
+        payload: { ...ev, capturedAt, account },
+      };
+      emitted += 1;
+    }
+  }
+
   async *_syncViaSnapshot(opts) {
     const raw = this._deps.fs.readFileSync(opts.inputPath, "utf-8");
     const snapshot = JSON.parse(raw);

package/lib/adapters/edu-zuoyebang/api-client.js

@@ -1,16 +1,40 @@
 /**
- * ZuoyebangApiClient — FAMILY-23 v0.1 cookie-scrape（无签名）。
+ * ZuoyebangApiClient — FAMILY-23 作业帮采集客户端。
  *
  * 作业帮 session 主键是 ZYBUSS（不透明 token）；数字 uid 走 uid / student_id /
- * passport_uid。v0.1 仅 extractUid（学习/搜题历史 走 v0.2）。仅 ZYBUSS 无数字 uid
- * 时返 null（v0.1 不解 ZYBUSS）。
+ * passport_uid。v0.1 仅 cookie-scrape（extractUid）。**v0.2 接通 live HTTP
+ * fetcher**：cookie（ZYBUSS 会话）直拉 用户信息 + 学习/搜题记录。
+ *
+ * ⚠️ **best-effort**：作业帮 web 接口无公开稳定文档，下方端点/字段按其 web 端
+ *    常见形态实现（envelope `{errNo, errstr, data}`），做了多字段名兼容（pick
+ *    回退），**未经真实登录态实地验证** — 端点/字段漂移时改常量 / opts 覆盖
+ *    （同 SignProvider 轮转思路）。
+ *
+ * Cookie key 优先级 (extractUid): uid > student_id > passport_uid。
+ * live 模式仅需 ZYBUSS 在场即可（uid 由 user-info 接口返回）。
  */
 "use strict";
 
+const { pick, toDurationMs, toEpochMs } = require("../_live-json-helpers");
+
+const DEFAULT_BASE_URL = "https://www.zuoyebang.com";
+// 端点（best-effort，可经 opts 覆盖）。
+const PATH_USER_INFO = "/session/pc/getuserinfo";
+const PATH_STUDY_RECORDS = "/study/pc/record/list";
+
+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";
+
 class ZuoyebangApiClient {
-  constructor() {
+  constructor(opts = {}) {
     this._lastErrorCode = 0;
     this._lastErrorMsg = "";
+    this._fetch =
+      opts.fetch || (typeof globalThis.fetch === "function" ? globalThis.fetch : null);
+    this.baseUrl = (opts.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.userInfoPath = opts.userInfoPath || PATH_USER_INFO;
+    this.studyRecordsPath = opts.studyRecordsPath || PATH_STUDY_RECORDS;
   }
   _setLastError(code, msg) {
     this._lastErrorCode = code;
@@ -39,10 +63,161 @@ class ZuoyebangApiClient {
     }
     this._setLastError(
       -7,
-      "cookie 缺 uid / student_id / passport_uid — 作业帮未登录 (仅 ZYBUSS 不透明 token, v0.1 不解)",
+      "cookie 缺 uid / student_id / passport_uid — 作业帮未登录 (仅 ZYBUSS 不透明 token, extractUid 不解)",
     );
     return null;
   }
+
+  /**
+   * live 模式会话探测：ZYBUSS 在场（uid 可由接口拿）或数字 uid 可抽即视为有会话。
+   * @param {string} cookie @returns {boolean}
+   */
+  hasSession(cookie) {
+    if (typeof cookie !== "string" || cookie.length === 0) return false;
+    if (/(?:^|; ?)ZYBUSS=[^;\s]+/.test(cookie)) return true;
+    const uid = this.extractUid(cookie);
+    if (uid) return true;
+    this._setLastError(-7, "cookie 缺 ZYBUSS 且无数字 uid — 作业帮未登录");
+    return false;
+  }
+
+  _headers(cookie) {
+    return {
+      Cookie: cookie,
+      "User-Agent": BROWSER_UA,
+      Referer: `${this.baseUrl}/`,
+      Accept: "application/json",
+    };
+  }
+
+  /**
+   * GET <url> with cookie. Parses the zuoyebang web envelope
+   * `{ errNo, errstr, data }` (errNo 0 = ok). Returns `data` on success,
+   * null on transport / API error (sets lastError).
+   */
+  async _doGetJson(url, cookie) {
+    if (typeof this._fetch !== "function") {
+      this._setLastError(
+        -2,
+        "ZuoyebangApiClient: fetch not available — pass opts.fetch or run on Node 18+",
+      );
+      return null;
+    }
+    let resp;
+    try {
+      resp = await this._fetch(url, { method: "GET", headers: this._headers(cookie) });
+    } catch (e) {
+      this._setLastError(-4, "network: " + (e && e.message ? e.message : String(e)));
+      return null;
+    }
+    const txt = await resp.text();
+    if (!resp.ok) {
+      this._setLastError(resp.status, `HTTP ${resp.status}`);
+      return null;
+    }
+    let obj;
+    try {
+      obj = JSON.parse(txt);
+    } catch (e) {
+      this._setLastError(-3, "parse: " + (e && e.message ? e.message : String(e)));
+      return null;
+    }
+    const code = pick(obj, ["errNo", "errno", "code"], 0);
+    if (Number(code) !== 0) {
+      this._setLastError(
+        Number(code),
+        pick(obj, ["errstr", "errStr", "errmsg", "errMsg", "msg"], `errNo ${code}`).toString(),
+      );
+      return null;
+    }
+    this._clearLastError();
+    return obj.data !== undefined && obj.data !== null ? obj.data : obj;
+  }
+
+  /** 用户信息 → { uid, nickname, grade } or null. */
+  async getUserInfo(cookie) {
+    const data = await this._doGetJson(`${this.baseUrl}${this.userInfoPath}`, cookie);
+    if (data === null) return null;
+    // web 端常把用户体包在 data.user / data.userInfo 下，或直接平铺。
+    const u = pick(data, ["user", "userInfo", "loginUser"], data);
+    const uid = pick(u, ["uid", "userId", "studentUid", "cuid"]);
+    return {
+      uid: uid != null ? String(uid) : null,
+      nickname: pick(u, ["uname", "nickName", "nickname", "userName", "name"]),
+      grade: pick(u, ["gradeName", "grade", "gradeId"]),
+    };
+  }
+
+  /**
+   * 学习/搜题记录 → [{ recordId, subject, durationMs, startAt }]. null on error.
+   * @param {string} cookie
+   * @param {object} [opts] { limit, offset }
+   */
+  async getStudyRecords(cookie, opts = {}) {
+    const rn = Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : 20;
+    const pn = Number.isInteger(opts.offset) && opts.offset > 0 ? opts.offset : 0;
+    const url = `${this.baseUrl}${this.studyRecordsPath}?pn=${pn}&rn=${rn}`;
+    const data = await this._doGetJson(url, cookie);
+    if (data === null) return null;
+    const list = pick(data, ["list", "records", "items"], Array.isArray(data) ? data : []);
+    if (!Array.isArray(list)) return [];
+    return list.map((r) => ({
+      recordId: pick(r, ["recordId", "logId", "id"]),
+      subject: pick(r, ["subjectName", "subject", "courseName", "course"]),
+      durationMs: toDurationMs(pick(r, ["studyTime", "duration", "learnTime", "durationMs"], 0)),
+      startAt: toEpochMs(pick(r, ["startTime", "beginTime", "createTime", "time"])),
+    }));
+  }
+
+  /**
+   * High-level: user info + study records → snapshot-shaped { account, events }
+   * so the adapter normalize path is unchanged.
+   * @returns {Promise<{account, events}|null>}
+   */
+  async fetchSnapshot(cookie, opts = {}) {
+    if (!this.hasSession(cookie)) return null; // lastError already set
+    const include = opts.include || {};
+    const events = [];
+    let account = null;
+
+    if (include.profile !== false) {
+      const user = await this.getUserInfo(cookie);
+      if (user === null) return null;
+      account = { uid: user.uid, displayName: user.nickname };
+      events.push({
+        kind: "profile",
+        id: user.uid ? `profile-${user.uid}` : null,
+        uid: user.uid,
+        nickname: user.nickname,
+        grade: user.grade,
+      });
+    }
+
+    if (include.study !== false) {
+      const records = await this.getStudyRecords(cookie, {
+        limit: opts.limit,
+        offset: opts.offset,
+      });
+      if (records === null) return null;
+      for (const r of records) {
+        events.push({
+          kind: "study",
+          id: r.recordId ? `study-${r.recordId}` : null,
+          subject: r.subject,
+          durationMs: r.durationMs,
+          startAt: r.startAt,
+        });
+      }
+    }
+
+    this._clearLastError();
+    return { account, events };
+  }
 }
 
-module.exports = { ZuoyebangApiClient };
+module.exports = {
+  ZuoyebangApiClient,
+  // Exported for tests / endpoint introspection.
+  PATH_USER_INFO,
+  PATH_STUDY_RECORDS,
+};

package/lib/adapters/edu-zuoyebang/index.js

@@ -1,10 +1,13 @@
 /**
- * FAMILY-23 v0.1 — 作业帮 (Zuoyebang) adapter, snapshot mode.
+ * FAMILY-23 — 作业帮 (Zuoyebang) adapter.
  *
- * 家庭守护 telemetry：家长看孩子的学习/搜题情况。v0.1 cookie-scrape 占位 —
- * [ZuoyebangApiClient.extractUid] 抽 uid；snapshot 模式消费手机端 collector 快照
- * (profile + study-session)。搜题/作业历史 HTTP fetcher 留 v0.2，故无 inputPath 时
- * sync 抛 NO_INPUT。
+ * 家庭守护 telemetry：家长看孩子的学习/搜题情况。两路互补：
+ *   - snapshot 模式（inputPath）：手机端 collector 快照 (profile + study-session)。
+ *   - **live 模式（cookie，v0.2 接通）**：[ZuoyebangApiClient.fetchSnapshot] 经
+ *     作业帮 web 接口（ZYBUSS 会话 cookie）拉 用户信息 + 学习/搜题记录。端点/
+ *     字段无公开稳定文档，按 web 端常见形态实现 + 多字段名兼容，**未实地验证**，
+ *     漂移时按 api-client 常量/pick 列表调整。
+ * 无 inputPath 且无 cookie 时 sync 抛错。
  *
  * Snapshot schema (v1):
  *   { schemaVersion:1, snapshottedAt, account:{uid,displayName}, events:[
@@ -26,7 +29,7 @@ const {
 const { ZuoyebangApiClient } = require("./api-client");
 
 const NAME = "edu-zuoyebang";
-const VERSION = "0.1.0";
+const VERSION = "0.2.0";
 const SNAPSHOT_SCHEMA_VERSION = 1;
 const KIND_PROFILE = "profile";
 const KIND_STUDY = "study";
@@ -60,6 +63,7 @@ class ZuoyebangAdapter {
     this.version = VERSION;
     this.capabilities = [
       "sync:snapshot",
+      "sync:cookie",
       "parse:zuoyebang-profile",
       "parse:zuoyebang-study-session",
     ];
@@ -74,7 +78,10 @@ class ZuoyebangAdapter {
       legalGate: false,
       defaultInclude: { profile: true, study: true },
     };
-    this.apiClient = new ZuoyebangApiClient();
+    this.apiClient = new ZuoyebangApiClient(opts);
+    // Test seam: override how the live client is built per-sync (inject fetch).
+    this._apiClientFactory =
+      typeof opts.apiClientFactory === "function" ? opts.apiClientFactory : null;
     this._deps = { fs };
   }
 
@@ -91,11 +98,21 @@ class ZuoyebangAdapter {
       }
       return { ok: true, mode: "snapshot-file" };
     }
+    if (ctx && typeof ctx.cookie === "string" && ctx.cookie.length > 0) {
+      if (!this.apiClient.hasSession(ctx.cookie)) {
+        return {
+          ok: false,
+          reason: "INVALID_COOKIE",
+          message: `edu-zuoyebang.authenticate: ${this.apiClient.lastError.message}`,
+        };
+      }
+      return { ok: true, mode: "cookie" };
+    }
     return {
       ok: false,
       reason: "NO_INPUT",
       message:
-        "edu-zuoyebang.authenticate: v0.1 needs opts.inputPath (snapshot mode); live HTTP fetcher 待 v0.2",
+        "edu-zuoyebang.authenticate: needs opts.inputPath (snapshot mode) or opts.cookie (ZYBUSS 会话, live fetch)",
     };
   }
 
@@ -108,11 +125,68 @@ class ZuoyebangAdapter {
       yield* this._syncViaSnapshot(opts);
       return;
     }
+    if (typeof opts.cookie === "string" && opts.cookie.length > 0) {
+      yield* this._syncViaLive(opts);
+      return;
+    }
     throw new Error(
-      "edu-zuoyebang.sync: v0.1 needs opts.inputPath (snapshot mode); 搜题/作业历史 HTTP fetcher 待 v0.2",
+      "edu-zuoyebang.sync: needs opts.inputPath (snapshot mode) or opts.cookie (ZYBUSS 会话, 学习/搜题记录 live fetch)",
     );
   }
 
+  async *_syncViaLive(opts) {
+    const client = this._apiClientFactory
+      ? this._apiClientFactory(opts)
+      : new ZuoyebangApiClient({
+          fetch: opts.fetch,
+          baseUrl: opts.baseUrl,
+          userInfoPath: opts.userInfoPath,
+          studyRecordsPath: opts.studyRecordsPath,
+        });
+    const emit = (phase, extra) => {
+      if (typeof opts.onProgress === "function") {
+        try {
+          opts.onProgress({ phase, adapter: NAME, ...extra });
+        } catch (_e) {
+          /* progress callback errors are best-effort */
+        }
+      }
+    };
+    const result = await client.fetchSnapshot(opts.cookie, {
+      include: opts.include || {},
+      limit: opts.limit,
+      offset: opts.offset,
+    });
+    if (result === null) {
+      const e = client.lastError;
+      throw new Error(
+        `edu-zuoyebang.sync (live): ${e.message || "fetch failed"} (code ${e.code})`,
+      );
+    }
+    const account = result.account || null;
+    emit("fetched", { count: result.events.length });
+    const capturedAt = Date.now();
+    const limit =
+      Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : Infinity;
+    const include = opts.include || {};
+    let emitted = 0;
+    for (const ev of result.events) {
+      if (emitted >= limit) return;
+      if (!ev || !VALID_SNAPSHOT_KINDS.includes(ev.kind)) continue;
+      if (include[ev.kind] === false) continue;
+      const id =
+        (typeof ev.id === "string" && ev.id.length > 0 && ev.id) || ev.uid || null;
+      yield {
+        adapter: NAME,
+        kind: ev.kind,
+        originalId: stableOriginalId(ev.kind, id),
+        capturedAt,
+        payload: { ...ev, capturedAt, account },
+      };
+      emitted += 1;
+    }
+  }
+
   async *_syncViaSnapshot(opts) {
     const raw = this._deps.fs.readFileSync(opts.inputPath, "utf-8");
     const snapshot = JSON.parse(raw);