@kukonce/dsh-loomy 0.0.0-stage → 0.3.2

package/src/account/auth.js

@@ -0,0 +1,297 @@
+/**
+ * Loomy accounts: logging in, keeping the session, and adopting an existing one.
+ *
+ * There is no API key in Loomy. An account is an iFlytek CAccount user, and the
+ * `session` string that CAccount hands back after a successful login is the only
+ * credential every later call needs. That makes this module the single owner of
+ * three things:
+ *
+ *   1. the login protocol (SMS code, plus the password path for completeness),
+ *   2. the on-disk account table (`accounts.json`) with each session in it,
+ *   3. importing a session the Loomy desktop app already has on this machine.
+ *
+ * The session is a bearer string with a long life and no refresh endpoint: CAccount
+ * simply answers `100002` once it is retired. So the daily-credit pass is also the
+ * natural liveness probe — a session that can read the balance is alive.
+ */
+
+import { randomUUID } from 'node:crypto'
+
+import {
+  ACCOUNT_ACCESS_KEY_ID,
+  ACCOUNT_ACCESS_KEY_SECRET,
+  ACCOUNT_APP_ID,
+  ACCOUNT_BASE_URL,
+  ACCOUNT_CLIENT_UA,
+  API_BASE_URL
+} from '../core/endpoints.js'
+import { requestJson, responseCode, responseData, responseMessage, unwrap, readString } from '../core/http.js'
+import { readJson, writeJson } from '../core/paths.js'
+import { buildAccountHeaders } from '../core/sign.js'
+import { findDesktopSession } from './desktop-session.js'
+
+const ACCOUNTS_FILE = 'accounts.json'
+const SESSION_EXPIRE_SECONDS = 14 * 24 * 3600
+
+/**
+ * An account id is used in file names and as a provider route suffix, so it stays
+ * to the characters both tolerate: letters, digits, dash.
+ */
+export const ACCOUNT_ID_PATTERN = /^[a-z][a-z0-9-]{0,23}$/u
+
+/** The `base` envelope block every CAccount request carries. */
+function baseBlock() {
+  return {
+    appid: ACCOUNT_APP_ID,
+    modelid: 'Web',
+    version: '1.0.0',
+    devid: 'web',
+    ua: ACCOUNT_CLIENT_UA,
+    traceid: randomUUID().replace(/-/gu, '')
+  }
+}
+
+/**
+ * One signed CAccount call.
+ *
+ * The body is serialized once and signed over exactly those bytes: re-serializing
+ * between signing and sending is how `010003` happens, because key order and
+ * whitespace are part of the MD5.
+ */
+async function accountCall(path, param) {
+  const body = JSON.stringify({ base: baseBlock(), param })
+  const headers = buildAccountHeaders({
+    accessKeyId: ACCOUNT_ACCESS_KEY_ID,
+    accessKeySecret: ACCOUNT_ACCESS_KEY_SECRET,
+    method: 'POST',
+    path,
+    body
+  })
+  const { status, json } = await requestJson('POST', `${ACCOUNT_BASE_URL}${path}`, headers, { body })
+  if (status !== 200) {
+    throw new Error(`${path} 调用失败：HTTP ${status} ${responseMessage(json)}`.trim())
+  }
+  return json
+}
+
+/** `/login/phone/sendMsgCode` — ask for an SMS code; answers `{ msgid, expire }`. */
+export async function sendSmsCode(phone) {
+  const normalized = String(phone ?? '').trim()
+  if (!/^1[3-9]\d{9}$/u.test(normalized)) {
+    throw new Error('手机号格式不正确（需要 11 位大陆手机号）')
+  }
+  const json = unwrap(
+    await accountCall('/login/phone/sendMsgCode', { ccode: '86', phone: normalized, expire: 300 }),
+    '发送验证码'
+  )
+  const data = responseData(json) ?? {}
+  return {
+    phone: normalized,
+    msgid: readString(data, 'msgid'),
+    expire: typeof data.expire === 'number' ? data.expire : 300
+  }
+}
+
+/**
+ * `/login/phone/checkCode` — exchange the SMS code for a session.
+ *
+ * Answers the account record the rest of the plugin uses; `phone` is echoed from
+ * the request because CAccount does not always return it.
+ */
+export async function loginBySmsCode({ phone, code, msgid, label = '' }) {
+  const normalizedPhone = String(phone ?? '').trim()
+  const normalizedCode = String(code ?? '').trim()
+  const normalizedMsgid = String(msgid ?? '').trim()
+  if (!/^1[3-9]\d{9}$/u.test(normalizedPhone)) throw new Error('手机号格式不正确')
+  if (!/^\d{4,8}$/u.test(normalizedCode)) throw new Error('验证码格式不正确')
+  if (normalizedMsgid.length === 0) throw new Error('缺少 msgid，请先获取验证码')
+
+  const json = unwrap(
+    await accountCall('/login/phone/checkCode', {
+      ccode: '86',
+      phone: normalizedPhone,
+      mcode: normalizedCode,
+      msgid: normalizedMsgid,
+      expire: SESSION_EXPIRE_SECONDS
+    }),
+    '验证码登录'
+  )
+  const data = responseData(json) ?? {}
+  const session = readString(data, 'session')
+  const userid = readString(data, 'userid')
+  if (session.length === 0 || userid.length === 0) {
+    throw new Error('登录失败：服务端未返回 session 或 userid')
+  }
+  return {
+    session,
+    userid,
+    phone: readString(data, 'phone') || normalizedPhone,
+    label: String(label ?? '').trim(),
+    loggedInAt: Date.now()
+  }
+}
+
+/** `/userinfo/query/baseInfo` — display metadata for a signed-in account. */
+export async function fetchUserInfo(session) {
+  const token = String(session ?? '').trim()
+  if (token.length === 0) throw new Error('缺少 session')
+  const json = unwrap(await accountCall('/userinfo/query/baseInfo', { session: token }), '获取用户信息')
+  const data = responseData(json) ?? {}
+  return {
+    userid: readString(data, 'userid'),
+    phone: readString(data, 'phone'),
+    nickname: readString(data, 'nickname'),
+    headpic: readString(data, 'headpic')
+  }
+}
+
+/**
+ * `/login/account/logout` — retire a session server-side.
+ *
+ * Best effort by design: a session the server already forgot is still a session this
+ * plugin should drop locally, and a network failure must not block a local logout.
+ */
+export async function logoutRemote(session) {
+  const token = String(session ?? '').trim()
+  if (token.length === 0) return { ok: true, skipped: true }
+  try {
+    const json = await accountCall('/login/account/logout', { session: token })
+    const code = responseCode(json)
+    return { ok: code === '000000', code }
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+/* ── the account table ─────────────────────────────────────────────────────── */
+
+/**
+ * The stored table: `{ version, accounts: [{ id, label, session, userid, phone, loggedInAt }] }`.
+ *
+ * A missing or unreadable file reads as "no accounts" rather than throwing: a corrupt
+ * file must not stop the host from starting, and the next write repairs it.
+ */
+export function readAccounts() {
+  const parsed = readJson(ACCOUNTS_FILE)
+  const list = parsed?.accounts
+  if (!Array.isArray(list)) return []
+  return list
+    .filter((entry) => typeof entry === 'object' && entry !== null)
+    .map((entry) => ({
+      id: String(entry.id ?? '').trim(),
+      label: String(entry.label ?? '').trim(),
+      session: String(entry.session ?? '').trim(),
+      userid: String(entry.userid ?? '').trim(),
+      phone: String(entry.phone ?? '').trim(),
+      loggedInAt: typeof entry.loggedInAt === 'number' ? entry.loggedInAt : 0,
+      source: entry.source === 'desktop' ? 'desktop' : 'sms'
+    }))
+    .filter((entry) => ACCOUNT_ID_PATTERN.test(entry.id))
+}
+
+function writeAccounts(accounts) {
+  writeJson(ACCOUNTS_FILE, { version: 1, accounts }, { mode: 0o600, pretty: true })
+}
+
+/** One account by id, or `undefined`. */
+export function accountOf(id) {
+  const key = String(id ?? '').trim().toLowerCase()
+  return readAccounts().find((entry) => entry.id === key)
+}
+
+/** Pick an unused `loomy-N` id, preferring `loomy` for the first account. */
+function nextAccountId(accounts) {
+  if (!accounts.some((entry) => entry.id === 'loomy')) return 'loomy'
+  for (let index = 2; index < 100; index += 1) {
+    const candidate = `loomy${index}`
+    if (!accounts.some((entry) => entry.id === candidate)) return candidate
+  }
+  throw new Error('账号数量已达上限（99 个）')
+}
+
+/**
+ * Store a freshly authenticated account.
+ *
+ * A re-login of the same `userid` updates that account's slot instead of adding a
+ * duplicate — otherwise every SMS login would leave the previous session behind as a
+ * second, stale entry for the same person.
+ */
+export function upsertAccount({ session, userid, phone = '', label = '', source = 'sms' }) {
+  const token = String(session ?? '').trim()
+  const uid = String(userid ?? '').trim()
+  if (token.length === 0 || uid.length === 0) throw new Error('账号记录缺少 session 或 userid')
+
+  const accounts = readAccounts()
+  const existing = accounts.find((entry) => entry.userid === uid)
+  const record = {
+    id: existing?.id ?? nextAccountId(accounts),
+    label: String(label ?? '').trim() || existing?.label || '',
+    session: token,
+    userid: uid,
+    phone: String(phone ?? '').trim() || existing?.phone || '',
+    loggedInAt: Date.now(),
+    source
+  }
+  const next = existing === undefined
+    ? [...accounts, record]
+    : accounts.map((entry) => (entry.id === record.id ? record : entry))
+  writeAccounts(next)
+  return record
+}
+
+/** Drop one account (and its session) from the table. */
+export function removeAccount(id) {
+  const key = String(id ?? '').trim().toLowerCase()
+  const accounts = readAccounts()
+  const next = accounts.filter((entry) => entry.id !== key)
+  const removed = next.length !== accounts.length
+  if (removed) writeAccounts(next)
+  return removed
+}
+
+/** Rename one account; the id is what routes and cache files hang off, so it stays. */
+export function renameAccount(id, label) {
+  const key = String(id ?? '').trim().toLowerCase()
+  const accounts = readAccounts()
+  const next = accounts.map((entry) => (entry.id === key ? { ...entry, label: String(label ?? '').trim() } : entry))
+  writeAccounts(next)
+  return next.find((entry) => entry.id === key)
+}
+
+/**
+ * Adopt the login the Loomy desktop app already has on this machine.
+ *
+ * Answers the stored record so the caller can report which account was picked up.
+ * Throws when there is nothing to import — that is a normal outcome on a machine
+ * where Loomy has never been signed in to, and the panel says so.
+ *
+ * `directory` is the user naming a location themselves (`/loomy import <directory>`);
+ * without it the search never leaves this user's own directories. Importing is always
+ * something the user asked for — nothing in this plugin adopts a desktop login on its own.
+ */
+export async function importDesktopAccount({ label = '', directory = '' } = {}) {
+  const found = findDesktopSession(directory)
+  if (found === undefined) {
+    throw new Error('未找到 Loomy 桌面端的登录态（请先在 Loomy 客户端登录，或改用短信登录）')
+  }
+  const record = upsertAccount({
+    session: found.session,
+    userid: found.userid,
+    phone: found.phone,
+    label: String(label ?? '').trim() || 'Loomy 桌面端',
+    source: 'desktop'
+  })
+  return { record, path: found.path }
+}
+
+/** Validate an account id the panel supplied, or throw with a usable message. */
+export function assertAccountId(id) {
+  const key = String(id ?? '').trim().toLowerCase()
+  if (!ACCOUNT_ID_PATTERN.test(key)) {
+    throw new Error(`账号 id "${key}" 不合法（需匹配 ${String(ACCOUNT_ID_PATTERN)}）`)
+  }
+  return key
+}
+
+/** The API host, exported so the panel can show where traffic goes. */
+export const API_HOST = API_BASE_URL

package/src/account/credits.js

@@ -0,0 +1,373 @@
+/**
+ * Points: the balance, the daily 5000 renewal, and the grant ledger.
+ *
+ * Loomy's metering splits the balance into two pots, and which pot a call spends from
+ * is decided server-side:
+ *
+ *   每日赠送 (daily)      5000 every day, reset by a `first-login` call, spends first
+ *   长期 / 永久 (permanent)  registration reward, onboarding tasks, redemption codes
+ *
+ * The important discovery is what actually renews the daily pot: it is
+ * `POST /api/v1/points/first-login`, which despite its name is a per-day idempotent
+ * "claim today's daily quota" call. It answers `{ alreadyProcessed: true }` on every
+ * repeat within the same `dailyCycleDate` and `dailyQuota: 5000` with a full
+ * `dailyBalance`. That is why this module claims it at startup and again at each local
+ * midnight: the claim is the only thing that keeps 5000 available every day, and it
+ * costs nothing to repeat.
+ *
+ * Onboarding tasks are a separate one-time pool (10000 available per account, keys
+ * listed below) and are claimed only when the user asks, never automatically — taking
+ * them unasked would spend a resource the user might want to hand out deliberately.
+ */
+
+import { API_BASE_URL, CLIENT_VERSION, PURPOSE_CHAT_MESSAGE } from '../core/endpoints.js'
+import { requestJson, unwrap, responseData, readString, localDayKey, AUTH_ERROR_CODES } from '../core/http.js'
+import { readJson, writeJson } from '../core/paths.js'
+
+const GRANT_FILE = 'daily-grant.json'
+
+/** Header set for the points/business API: this one authenticates with `token` alone. */
+function pointsHeaders(session) {
+  return {
+    token: session,
+    Accept: 'application/json',
+    'loomy-version': CLIENT_VERSION,
+    'X-Loomy-Request-Purpose': PURPOSE_CHAT_MESSAGE
+  }
+}
+
+async function get(session, path, label) {
+  const { status, json } = await requestJson('GET', `${API_BASE_URL}${path}`, pointsHeaders(session), {
+    timeoutMs: 30_000
+  })
+  if (status !== 200) {
+    const error = new Error(`${label}：HTTP ${status}`)
+    error.status = status
+    error.isAuthError = status === 401 || status === 403
+    throw error
+  }
+  return unwrap(json, label)
+}
+
+async function post(session, path, body, label) {
+  const { status, json } = await requestJson('POST', `${API_BASE_URL}${path}`, {
+    ...pointsHeaders(session),
+    'Content-Type': 'application/json'
+  }, { body: JSON.stringify(body ?? {}), timeoutMs: 30_000 })
+  if (status !== 200) {
+    const error = new Error(`${label}：HTTP ${status}`)
+    error.status = status
+    error.isAuthError = status === 401 || status === 403
+    throw error
+  }
+  return unwrap(json, label)
+}
+
+const finite = (value, fallback = 0) => (typeof value === 'number' && Number.isFinite(value) ? value : fallback)
+
+/**
+ * The account's balances, from the first-login claim.
+ *
+ * This is the one call that returns all four numbers at once (daily, permanent,
+ * current, quota) plus today's consumption, so it doubles as the balance read. It is
+ * idempotent, which is what makes it safe to call on every panel refresh.
+ */
+export async function fetchCredits(session) {
+  const json = await post(session, '/api/v1/points/first-login', {}, '读取积分')
+  const data = responseData(json) ?? {}
+  return {
+    ok: true,
+    alreadyProcessed: data.alreadyProcessed === true,
+    balance: finite(data.currentBalance),
+    permanentBalance: finite(data.permanentBalance),
+    dailyBalance: finite(data.dailyBalance),
+    dailyQuota: finite(data.dailyQuota),
+    dailyConsumed: finite(data.dailyConsumed),
+    dailyCycleDate: typeof data.dailyCycleDate === 'string' ? data.dailyCycleDate : localDayKey(),
+    availableBalance: finite(data.currentBalance) + finite(data.dailyBalance),
+    inviteCode: Array.isArray(data.invitationCodes) && data.invitationCodes.length > 0
+      ? String(data.invitationCodes[0]?.inviteCode ?? '')
+      : ''
+  }
+}
+
+/** Ledger entries; `direction` is `credit` or `debit`, `granularity` optional. */
+export async function queryRecords(session, { pageNo = 1, pageSize = 20, direction = 'credit', granularity } = {}) {
+  const params = new URLSearchParams({
+    pageNo: String(Math.max(1, pageNo)),
+    pageSize: String(Math.min(100, Math.max(1, pageSize))),
+    direction: direction === 'debit' ? 'debit' : 'credit'
+  })
+  if (typeof granularity === 'string' && granularity.length > 0) params.set('granularity', granularity)
+  const json = await get(session, `/api/v2/points/records?${params.toString()}`, '查询积分记录')
+  const data = responseData(json) ?? {}
+  return {
+    balance: finite(data.balance),
+    dailyBalance: finite(data.dailyBalance),
+    pageNo: finite(data.pageNo, 1),
+    pageSize: finite(data.pageSize, 20),
+    total: finite(data.total),
+    list: Array.isArray(data.list) ? data.list.map(normalizeRecord) : []
+  }
+}
+
+function normalizeRecord(entry) {
+  return {
+    ledgerId: readString(entry, 'ledgerId'),
+    description: readString(entry, 'description'),
+    direction: readString(entry, 'direction'),
+    points: finite(entry?.points ?? entry?.pointsActual),
+    source: readString(entry, 'source'),
+    createdAt: finite(entry?.createdAt)
+  }
+}
+
+/**
+ * Claim today's daily grant — the call that keeps 每日赠送 at 5000.
+ *
+ * "Granted" means the account now has today's daily pot available, which is what the
+ * caller acts on. It is deliberately **not** "the balance equals the quota": any chat
+ * turn spends a few points, so a strict equality check reported "领不到" all day on an
+ * account that had in fact received its full 5000. A daily balance above zero after the
+ * claim is the honest signal, and `available` reports the exact number beside it.
+ *
+ * Never throws: a claim that is already done, or one the server declines, is a normal
+ * outcome the ledger records. The caller decides whether that is worth surfacing.
+ */
+export async function claimDailyGrant(session) {
+  try {
+    const credits = await fetchCredits(session)
+    return {
+      granted: credits.dailyBalance > 0 && credits.dailyQuota > 0,
+      available: credits.dailyBalance,
+      alreadyProcessed: credits.alreadyProcessed,
+      ...credits
+    }
+  } catch (error) {
+    const code = typeof error?.code === 'string' ? error.code : ''
+    if (AUTH_ERROR_CODES.has(code)) {
+      return { granted: false, error: '登录已失效', isAuthError: true, code }
+    }
+    return { granted: false, error: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+/* ── per-account grant ledger ──────────────────────────────────────────────── */
+
+/** `{ [accountId]: { day, at, granted, balance, quota, reason } }`. */
+function readGrantLedger() {
+  const parsed = readJson(GRANT_FILE)
+  return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ? parsed : {}
+}
+
+function writeGrantLedger(ledger) {
+  writeJson(GRANT_FILE, ledger, { mode: 0o600, pretty: true })
+}
+
+/** The last recorded grant attempt for one account. */
+export function dailyGrantState(accountId) {
+  const key = String(accountId ?? '').trim().toLowerCase()
+  return readGrantLedger()[key]
+}
+
+/** Whether the daily grant for this account has been claimed in the current local day. */
+export function grantedToday(accountId, now = new Date()) {
+  const state = dailyGrantState(accountId)
+  return state !== undefined && state.day === localDayKey(now)
+}
+
+/**
+ * Claim and remember, once per local day unless `force` is set.
+ *
+ * The server is authoritative about whether a claim still counts; this ledger only
+ * remembers the outcome so a restart does not re-ask, and so the panel can say when it
+ * last ran. `force` exists for the panel's manual button.
+ */
+export async function ensureDailyGrant(accountId, session, { force = false, reason = '启动' } = {}) {
+  const key = String(accountId ?? '').trim().toLowerCase()
+  if (!force && grantedToday(key)) {
+    const state = dailyGrantState(key)
+    return { skipped: true, day: state.day, ...state }
+  }
+  const outcome = await claimDailyGrant(session)
+  const ledger = readGrantLedger()
+  const record = {
+    day: localDayKey(),
+    at: Date.now(),
+    reason,
+    granted: outcome.granted === true,
+    balance: outcome.dailyBalance,
+    quota: outcome.dailyQuota,
+    ...(outcome.error === undefined ? {} : { error: outcome.error })
+  }
+  ledger[key] = record
+  try {
+    writeGrantLedger(ledger)
+  } catch {
+    // bookkeeping only — never let it break the claim path
+  }
+  // A claim that reached the server re-read the remaining daily pot, so it is also the
+  // sync point for the spend file below: forget what was recorded since the last claim
+  // and let the projection restart from the number the server just confirmed. Any drift
+  // (a turn billed outside this process, an onboarding task) self-corrects here. A
+  // failed claim leaves both files untouched — the server state is unknown.
+  if (outcome.error === undefined) resetAccountUsage(key)
+  return { ...outcome, ...record, skipped: false }
+}
+
+/* ── chat spend accounting ─────────────────────────────────────────────────── */
+
+const USAGE_FILE = 'usage.json'
+
+/**
+ * What chat has cost, per local day and account:
+ * `{ version: 1, byDay: { 'YYYY-MM-DD': { [accountId]: points } } }`.
+ *
+ * The grant ledger above freezes the daily pot at claim time, and the only place a
+ * turn's cost is reported is the gateway's final usage frame (`points_consumed`) —
+ * which the adapter records here as the frame arrives. `/state` then projects the
+ * claim's balance minus this file's spend for the claim's day, so the composer pill
+ * moves while the user chats instead of sticking at the claim-time 5000.
+ *
+ * Nothing else writes this file: the server's own `dailyConsumed` stays authoritative
+ * and every claim (boot, midnight, panel button) re-syncs the projection.
+ */
+function readUsageByDay() {
+  const parsed = readJson(USAGE_FILE)
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return {}
+  const byDay = parsed.byDay
+  return typeof byDay === 'object' && byDay !== null && !Array.isArray(byDay) ? byDay : {}
+}
+
+function usageKey(accountId) {
+  return String(accountId ?? '').trim().toLowerCase()
+}
+
+/** Points this account has spent from chat on `day` (0 when nothing was recorded). */
+export function consumedOnDay(accountId, day = localDayKey()) {
+  const bucket = readUsageByDay()[day]
+  const value = typeof bucket === 'object' && bucket !== null ? bucket[usageKey(accountId)] : undefined
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.round(value) : 0
+}
+
+/** Add one turn's cost. Bookkeeping only: never throws, never blocks the chat path. */
+export function recordPointsSpent(accountId, points, day = localDayKey()) {
+  const key = usageKey(accountId)
+  const cost = Number(points)
+  if (key.length === 0 || !Number.isFinite(cost) || cost <= 0) return
+  try {
+    const byDay = readUsageByDay()
+    const bucket = typeof byDay[day] === 'object' && byDay[day] !== null ? byDay[day] : {}
+    const known = typeof bucket[key] === 'number' && Number.isFinite(bucket[key]) ? bucket[key] : 0
+    bucket[key] = Math.round(known + cost)
+    byDay[day] = bucket
+    // Only the claim's day is ever read, so trimming old days is hygiene, not
+    // correctness — the file stays a few hundred bytes for the life of the install.
+    const days = Object.keys(byDay).sort()
+    while (days.length > 8) delete byDay[days.shift()]
+    writeJson(USAGE_FILE, { version: 1, byDay }, { mode: 0o600 })
+  } catch {
+    // bookkeeping only — a failed write must never break the chat path
+  }
+}
+
+/** Forget this account's recorded spend; a claim calls this when it re-syncs the pot. */
+export function resetAccountUsage(accountId) {
+  const key = usageKey(accountId)
+  if (key.length === 0) return
+  try {
+    const byDay = readUsageByDay()
+    let changed = false
+    for (const day of Object.keys(byDay)) {
+      const bucket = byDay[day]
+      if (typeof bucket === 'object' && bucket !== null && key in bucket) {
+        delete bucket[key]
+        if (Object.keys(bucket).length === 0) delete byDay[day]
+        changed = true
+      }
+    }
+    if (changed) writeJson(USAGE_FILE, { version: 1, byDay }, { mode: 0o600 })
+  } catch {
+    // bookkeeping only
+  }
+}
+
+/**
+ * Re-anchor the ledger from a live `fetchCredits` answer.
+ *
+ * The claim path above runs a few times a day; this is the manual sync: the panel's
+ * refresh button (and the `/loomy credits` command) just read the server, and writing
+ * what it answered makes the pill's projection agree immediately instead of waiting
+ * for the next claim to discover the drift. `fetchCredits` is the same idempotent
+ * endpoint the claim uses, so a re-anchor never double-grants.
+ */
+export function anchorLedger(accountId, credits, reason = '刷新') {
+  const key = String(accountId ?? '').trim().toLowerCase()
+  if (key.length === 0 || credits?.ok !== true) return
+  try {
+    const ledger = readGrantLedger()
+    ledger[key] = {
+      // The local day key, not the server's `dailyCycleDate`: both are `YYYY-MM-DD`,
+      // but they can disagree for minutes around midnight (different clocks roll at
+      // different moments), and every ledger consumer here — `grantedToday`, the
+      // projection's day match — compares against the local key. The ledger is a
+      // local book about when this process last synced, so it keeps local days.
+      day: localDayKey(),
+      at: Date.now(),
+      reason,
+      granted: credits.dailyBalance > 0 && credits.dailyQuota > 0,
+      balance: finite(credits.dailyBalance),
+      quota: finite(credits.dailyQuota)
+    }
+    writeGrantLedger(ledger)
+    // The anchored balance already includes everything spent so far today — the
+    // server counted it — so recorded spend before this moment must not subtract
+    // twice. Same contract as the claim path above.
+    resetAccountUsage(key)
+  } catch {
+    // bookkeeping only
+  }
+}
+
+/**
+ * The one-time onboarding pool (`10000` points per account, 8 keys).
+ *
+ * Kept as data rather than fetched, because the key list is what the completion call
+ * needs and the server's `tasks` map is the source of which are still open.
+ */
+export const ONBOARDING_TASKS = Object.freeze({
+  first_message: 500,
+  pick_skill: 1000,
+  generate_ppt: 1500,
+  set_schedule: 1000,
+  install_skill: 1500,
+  configure_remote: 1000,
+  create_soul: 1500,
+  share_soul: 2000
+})
+
+/** Which onboarding tasks are still open on this account. */
+export async function fetchOnboardingTasks(session) {
+  const json = await get(session, '/api/v1/onboarding/tasks', '读取新手任务')
+  const data = responseData(json) ?? {}
+  const raw = typeof data.tasks === 'object' && data.tasks !== null ? data.tasks : {}
+  const tasks = {}
+  for (const key of Object.keys(ONBOARDING_TASKS)) tasks[key] = raw[key] === true
+  return {
+    tasks,
+    earned: finite(data.earned),
+    total: finite(data.total, Object.values(ONBOARDING_TASKS).reduce((sum, value) => sum + value, 0))
+  }
+}
+
+/** Mark one onboarding task complete; the server decides whether it pays out. */
+export async function completeOnboardingTask(session, key) {
+  const normalized = String(key ?? '').trim()
+  if (!(normalized in ONBOARDING_TASKS)) throw new Error(`未知的新手任务 "${normalized}"`)
+  const json = await post(session, '/api/v1/onboarding/tasks/complete', { key: normalized }, '完成新手任务')
+  const data = responseData(json) ?? {}
+  return {
+    alreadyCompleted: data.alreadyCompleted === true,
+    balance: finite(data.balance)
+  }
+}