@chainlesschain/personal-data-hub 0.1.0 → 0.2.1

package/lib/analysis-skills/index.js

@@ -0,0 +1,58 @@
+/**
+ * Phase 11 — internal analysis skills entry point.
+ *
+ * Each skill is a small focused class that the hub dispatches to via
+ * `runAnalysisSkill(name, options)`. Skills work over the vault +
+ * optional LLM and respect the same privacy gate as AnalysisEngine.
+ */
+
+"use strict";
+
+const { AnalysisSkill } = require("./base");
+const { SpendingSkill, SUPPORTED_DIMENSIONS: SPENDING_DIMENSIONS } = require("./spending");
+const { RelationsSkill } = require("./relations");
+const { FootprintSkill } = require("./footprint");
+const { InterestsSkill } = require("./interests");
+const { TimelineSkill } = require("./timeline");
+
+const SKILL_REGISTRY = Object.freeze({
+  "analysis.spending": SpendingSkill,
+  "analysis.relations": RelationsSkill,
+  "analysis.footprint": FootprintSkill,
+  "analysis.interests": InterestsSkill,
+  "analysis.timeline": TimelineSkill,
+});
+
+const SKILL_NAMES = Object.freeze(Object.keys(SKILL_REGISTRY));
+
+/**
+ * Run a single skill by name. Convenience over instantiating Skill
+ * classes directly — the same {vault, llm} pair gets reused.
+ *
+ * @param {{vault, llm?}} deps
+ * @param {string} skillName
+ * @param {object} options
+ */
+async function runAnalysisSkill(deps, skillName, options = {}) {
+  if (!deps || !deps.vault) throw new Error("runAnalysisSkill: deps.vault required");
+  const Cls = SKILL_REGISTRY[skillName];
+  if (!Cls) {
+    throw new Error(`unknown analysis skill: ${skillName}. Known: ${SKILL_NAMES.join(", ")}`);
+  }
+  const skill = new Cls({ vault: deps.vault, llm: deps.llm });
+  return await skill.run(options);
+}
+
+module.exports = {
+  AnalysisSkill,
+  SpendingSkill,
+  RelationsSkill,
+  FootprintSkill,
+  InterestsSkill,
+  TimelineSkill,
+  SKILL_REGISTRY,
+  SKILL_NAMES,
+  ANALYSIS_SKILL_NAMES: SKILL_NAMES,
+  SPENDING_DIMENSIONS,
+  runAnalysisSkill,
+};

package/lib/analysis-skills/interests.js

@@ -0,0 +1,161 @@
+/**
+ * Phase 11 — analysis.interests skill.
+ *
+ * Extracts the user's interest profile from:
+ *   - Topic entities (already-categorized by adapter)
+ *   - Item entities (product / content names)
+ *   - Event content.title from order/payment/visit events
+ *
+ * LLM is used to cluster + name interest categories. Without LLM,
+ * falls back to topic-frequency + most-purchased-item ranking (no
+ * generalization).
+ *
+ * Inputs:
+ *   - timeWindow:  optional; default all-time
+ *   - topN:        default 15
+ *
+ * Output:
+ *   {
+ *     topTopics: [{ name, eventCount, lastSeen }, ...],
+ *     topItems:  [{ name, occurrences, totalSpend }, ...],
+ *     llmInterests?: [{ category, evidenceCount, examples }, ...],
+ *     citations,
+ *     llm_commentary,
+ *   }
+ */
+
+"use strict";
+
+const { AnalysisSkill } = require("./base");
+
+class InterestsSkill extends AnalysisSkill {
+  constructor(opts) {
+    super({ ...opts, name: "analysis.interests" });
+  }
+
+  async run(options = {}) {
+    const { since, until } = this.resolveTimeWindow(options);
+    const topN = Number.isFinite(options.topN) && options.topN > 0 ? options.topN : 15;
+
+    const topTopics = this._topTopics(since, until, topN);
+    const topItems = this._topItems(since, until, topN);
+    const events = this._sampleEvents(since, until, 200);
+    const llmInterests = (options.commentary !== false && this.llm)
+      ? await this._clusterInterests(topTopics, topItems, events, options)
+      : null;
+
+    return {
+      skill: "analysis.interests",
+      topTopics,
+      topItems,
+      llmInterests,
+      citations: events.slice(0, 50).map((e) => e.id),
+      llm_commentary: null,
+    };
+  }
+
+  _topTopics(since, until, topN) {
+    // Topics are stored in their own table — eventCount is derived from
+    // the JSON `derived_from_events` array length; lastSeen is the
+    // topic's ingested_at (proxy until we add a real last_seen column).
+    let topics = [];
+    try {
+      const db = this.vault._requireOpen();
+      topics = db.prepare(
+        "SELECT id, name, derived_from_events, ingested_at FROM topics ORDER BY ingested_at DESC LIMIT ?"
+      ).all(topN * 3);
+    } catch (_e) {
+      // Older vaults may not have topics; non-fatal.
+    }
+    const mapped = topics.map((t) => {
+      let eventCount = 0;
+      try {
+        const arr = t.derived_from_events ? JSON.parse(t.derived_from_events) : [];
+        if (Array.isArray(arr)) eventCount = arr.length;
+      } catch (_e) {}
+      return {
+        id: t.id,
+        name: t.name,
+        eventCount,
+        lastSeen: t.ingested_at || null,
+      };
+    });
+    return mapped
+      .sort((a, b) => (b.eventCount - a.eventCount) || ((b.lastSeen || 0) - (a.lastSeen || 0)))
+      .slice(0, topN);
+  }
+
+  _topItems(since, until, topN) {
+    let items = [];
+    try {
+      const db = this.vault._requireOpen();
+      items = db.prepare(
+        "SELECT id, name FROM items ORDER BY ingested_at DESC LIMIT ?"
+      ).all(topN * 3);
+    } catch (_e) {}
+    // Re-bucket by name (multiple Item rows often share the same product
+    // name across adapters). Phase 8 EntityResolver doesn't dedup items
+    // yet — that's Phase 9+.
+    const buckets = new Map();
+    for (const row of items) {
+      const item = this.vault.getItem ? this.vault.getItem(row.id) : null;
+      if (!item) continue;
+      const key = item.name || "(unknown)";
+      const cur = buckets.get(key) || { name: key, occurrences: 0, totalSpend: 0 };
+      cur.occurrences += 1;
+      if (item.price && Number.isFinite(item.price.value)) cur.totalSpend += item.price.value;
+      buckets.set(key, cur);
+    }
+    return Array.from(buckets.values())
+      .sort((a, b) => b.occurrences - a.occurrences)
+      .slice(0, topN)
+      .map((b) => ({ ...b, totalSpend: Math.round(b.totalSpend * 100) / 100 }));
+  }
+
+  _sampleEvents(since, until, limit) {
+    const q = { limit };
+    if (since != null) q.since = since;
+    if (until != null) q.until = until;
+    return this.vault.queryEvents(q) || [];
+  }
+
+  async _clusterInterests(topTopics, topItems, events, options) {
+    if (topTopics.length === 0 && topItems.length === 0) return null;
+    const userMsg = `用户的互动数据样本：
+
+Topics (按出现频次):
+${topTopics.slice(0, 10).map((t) => `- ${t.name} (${t.eventCount}次)`).join("\n") || "(无)"}
+
+Items (购买/收到):
+${topItems.slice(0, 10).map((i) => `- ${i.name} (${i.occurrences}次, ¥${i.totalSpend})`).join("\n") || "(无)"}
+
+最近事件 titles (抽样):
+${events.slice(0, 20).map((e) => `- ${e.content?.title || "(无标题)"}`).join("\n")}
+
+请将以上抽 3-5 个兴趣类别（如"咖啡"、"科技阅读"、"户外旅行"），每个给出 1-2 个 evidence 引用。
+输出 JSON 数组：[{"category": "类别名", "evidenceCount": N, "examples": ["..."]}, ...]
+只输出 JSON，不要其它文字。`;
+
+    const resp = await this.callLlmCommentary([
+      { role: "system", content: "你是一个克制的兴趣画像分析助手。基于明示数据归纳类别，不臆造。" },
+      { role: "user", content: userMsg },
+    ], { acceptNonLocal: options.acceptNonLocal });
+
+    if (!resp) return null;
+    // Parse JSON array (strict → fenced → regex)
+    try {
+      return JSON.parse(resp.trim());
+    } catch (_e) {}
+    const fence = resp.match(/```(?:json)?\s*\n?([\s\S]*?)\n?\s*```/);
+    if (fence) {
+      try { return JSON.parse(fence[1].trim()); } catch (_e) {}
+    }
+    const arrMatch = resp.match(/\[\s*\{[\s\S]*?\}\s*\]/);
+    if (arrMatch) {
+      try { return JSON.parse(arrMatch[0]); } catch (_e) {}
+    }
+    return null;
+  }
+}
+
+module.exports = { InterestsSkill };

package/lib/analysis-skills/relations.js

@@ -0,0 +1,226 @@
+/**
+ * Phase 11 — analysis.relations skill.
+ *
+ * Per-Person interaction profile. Either:
+ *   - `personId`: scope to one specific Person (uses merge-group expansion
+ *     so cross-source identities count together) — returns single
+ *     person's interaction profile vs self.
+ *   - no `personId`: ranks ALL Persons by total interaction count and
+ *     returns the top-N.
+ *
+ * "Interaction" = any Event where the Person is actor or participant.
+ * Counts include payments, messages, emails — adapter-agnostic.
+ *
+ * Output:
+ *   {
+ *     mode: "single" | "ranked",
+ *     personId: ...,
+ *     profile?: {                   // single mode
+ *       personId, names,
+ *       totalInteractions, byAdapter, byMonth,
+ *       outboundCount, inboundCount, outboundShare,
+ *       totalSpend, totalIncome,
+ *       firstInteraction, lastInteraction,
+ *     },
+ *     ranked?: [...],               // ranked mode
+ *     citations,
+ *     llm_commentary,
+ *   }
+ */
+
+"use strict";
+
+const { AnalysisSkill } = require("./base");
+
+class RelationsSkill extends AnalysisSkill {
+  constructor(opts) {
+    super({ ...opts, name: "analysis.relations" });
+  }
+
+  async run(options = {}) {
+    if (typeof options.personId === "string" && options.personId.length > 0) {
+      return await this._runSingle(options);
+    }
+    return await this._runRanked(options);
+  }
+
+  async _runSingle(options) {
+    const { since, until } = this.resolveTimeWindow(options);
+    const members = this.expandToMergeGroup(options.personId);
+    const memberSet = new Set(members);
+
+    const events = this._fetchAllRelevant({ since, until, memberSet });
+    const profile = this._buildProfile(options.personId, members, events);
+    const citations = events.slice(0, 50).map((e) => e.id);
+
+    let llmCommentary = null;
+    if (options.commentary !== false && this.llm) {
+      llmCommentary = await this._llmCommentary(profile, options);
+    }
+
+    return {
+      skill: "analysis.relations",
+      mode: "single",
+      personId: options.personId,
+      profile,
+      citations,
+      llm_commentary: llmCommentary,
+    };
+  }
+
+  async _runRanked(options) {
+    const { since, until } = this.resolveTimeWindow(options);
+    const topN = Number.isFinite(options.topN) && options.topN > 0 ? options.topN : 20;
+
+    // Pull all events in window then bucket by counterparty
+    const allEvents = this._fetchAllRelevant({ since, until, memberSet: null });
+    const buckets = new Map();
+    for (const e of allEvents) {
+      const ids = (e.participants || []).concat(e.actor ? [e.actor] : []);
+      for (const pid of new Set(ids)) {
+        if (pid === "person-self" || !pid) continue;
+        const cur = buckets.get(pid) || {
+          personId: pid, totalInteractions: 0, totalSpend: 0, totalIncome: 0,
+          byAdapter: {}, firstSeen: e.occurredAt, lastSeen: e.occurredAt,
+        };
+        cur.totalInteractions += 1;
+        if (e.content?.amount?.direction === "out") cur.totalSpend += e.content.amount.value;
+        if (e.content?.amount?.direction === "in") cur.totalIncome += e.content.amount.value;
+        const adapter = (e.source && e.source.adapter) || "unknown";
+        cur.byAdapter[adapter] = (cur.byAdapter[adapter] || 0) + 1;
+        if (e.occurredAt < cur.firstSeen) cur.firstSeen = e.occurredAt;
+        if (e.occurredAt > cur.lastSeen) cur.lastSeen = e.occurredAt;
+        buckets.set(pid, cur);
+      }
+    }
+    // Resolve display names per top bucket; ignore self if it sneaks in
+    const ranked = Array.from(buckets.values())
+      .sort((a, b) => b.totalInteractions - a.totalInteractions)
+      .slice(0, topN)
+      .map((b) => ({
+        ...b,
+        totalSpend: Math.round(b.totalSpend * 100) / 100,
+        totalIncome: Math.round(b.totalIncome * 100) / 100,
+        name: this._lookupName(b.personId),
+      }));
+
+    return {
+      skill: "analysis.relations",
+      mode: "ranked",
+      ranked,
+      citations: allEvents.slice(0, 50).map((e) => e.id),
+      llm_commentary: null,
+    };
+  }
+
+  _fetchAllRelevant({ since, until, memberSet }) {
+    // No subtype filter — relations cares about ALL events. Limit guards
+    // memory for big vaults.
+    const q = { limit: 10_000 };
+    if (since != null) q.since = since;
+    if (until != null) q.until = until;
+    const events = this.vault.queryEvents(q) || [];
+    if (!memberSet) return events;
+    return events.filter((e) => {
+      if (memberSet.has(e.actor)) return true;
+      if (Array.isArray(e.participants) && e.participants.some((p) => memberSet.has(p))) return true;
+      return false;
+    });
+  }
+
+  _buildProfile(personId, members, events) {
+    let outboundCount = 0;
+    let inboundCount = 0;
+    let totalSpend = 0;
+    let totalIncome = 0;
+    let firstInteraction = Infinity;
+    let lastInteraction = -Infinity;
+    const byAdapter = {};
+    const byMonth = {};
+    const memberSet = new Set(members);
+
+    for (const e of events) {
+      const t = e.occurredAt || 0;
+      if (t < firstInteraction) firstInteraction = t;
+      if (t > lastInteraction) lastInteraction = t;
+      // Outbound = self → them (actor=self, target=them); inbound = them → self
+      if (e.actor === "person-self" || memberSet.has(e.actor)) {
+        if (e.actor === "person-self") outboundCount += 1;
+        else inboundCount += 1;
+      } else {
+        // Participant-only event; counts as both? Most adapters keep
+        // actor+participants consistent so this branch is rare.
+        outboundCount += 1;
+      }
+      if (e.content?.amount) {
+        if (e.content.amount.direction === "out") totalSpend += e.content.amount.value;
+        else if (e.content.amount.direction === "in") totalIncome += e.content.amount.value;
+      }
+      const adapter = (e.source && e.source.adapter) || "unknown";
+      byAdapter[adapter] = (byAdapter[adapter] || 0) + 1;
+      const d = new Date(t);
+      if (Number.isFinite(d.getTime())) {
+        const m = `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}`;
+        byMonth[m] = (byMonth[m] || 0) + 1;
+      }
+    }
+    const total = outboundCount + inboundCount;
+
+    return {
+      personId,
+      members,
+      names: this._lookupNames(members),
+      totalInteractions: total,
+      byAdapter,
+      byMonth,
+      outboundCount,
+      inboundCount,
+      outboundShare: total > 0 ? Math.round((outboundCount / total) * 100) / 100 : 0,
+      totalSpend: Math.round(totalSpend * 100) / 100,
+      totalIncome: Math.round(totalIncome * 100) / 100,
+      firstInteraction: firstInteraction === Infinity ? null : firstInteraction,
+      lastInteraction: lastInteraction === -Infinity ? null : lastInteraction,
+    };
+  }
+
+  _lookupName(personId) {
+    try {
+      const p = this.vault.getPerson ? this.vault.getPerson(personId) : null;
+      return (p && p.names && p.names[0]) || personId;
+    } catch (_e) {
+      return personId;
+    }
+  }
+
+  _lookupNames(personIds) {
+    const set = new Set();
+    for (const id of personIds) {
+      try {
+        const p = this.vault.getPerson ? this.vault.getPerson(id) : null;
+        if (p && Array.isArray(p.names)) {
+          for (const n of p.names) if (n) set.add(n);
+        }
+      } catch (_e) {}
+    }
+    return Array.from(set);
+  }
+
+  async _llmCommentary(profile, options) {
+    if (!profile.totalInteractions) return "No interactions found in this period.";
+    const userMsg = `分析与某人的关系：
+- 姓名/别名: ${profile.names.join(", ") || profile.personId}
+- 互动总数: ${profile.totalInteractions}
+- 主动占比: ${(profile.outboundShare * 100).toFixed(0)}% (${profile.outboundCount} 主动 vs ${profile.inboundCount} 收到)
+- 钱款来往: 支出 ¥${profile.totalSpend} / 收入 ¥${profile.totalIncome}
+- 跨源: ${Object.keys(profile.byAdapter).join(", ")}
+- 时间跨度: ${profile.firstInteraction ? new Date(profile.firstInteraction).toISOString().slice(0,10) : "?"} 到 ${profile.lastInteraction ? new Date(profile.lastInteraction).toISOString().slice(0,10) : "?"}
+
+请用 2-3 句话总结关系特征（亲密 / 疏远 / 单向 / 平等）。中文回答。`;
+    return await this.callLlmCommentary([
+      { role: "system", content: "你是一个克制的人际分析助手。仅基于提供的数据给出温和的描述性总结，不评价、不臆断情感。" },
+      { role: "user", content: userMsg },
+    ], { acceptNonLocal: options.acceptNonLocal });
+  }
+}
+
+module.exports = { RelationsSkill };

package/lib/analysis-skills/spending.js

@@ -0,0 +1,219 @@
+/**
+ * Phase 11 — analysis.spending skill.
+ *
+ * Inputs:
+ *   - timeWindow:  { since, until } | { sinceDays N } | { sinceMonths N }
+ *   - dimension:   "merchant" | "category" | "counterparty" | "month"
+ *                  Default "merchant".
+ *   - merchantFilter:   optional substring (e.g. "美团" to scope to one
+ *                       merchant family)
+ *   - personId:         optional — scope to spending TO this person (uses
+ *                       merge-group expansion)
+ *   - topN:             default 10
+ *
+ * Output:
+ *   {
+ *     summary: {
+ *       totalSpend, totalIncome, netFlow, currency,
+ *       eventCount, uniqueCounterparties, period,
+ *     },
+ *     breakdown: [{ key, totalSpend, eventCount, percentOfTotal }, ...],
+ *     trend: [{ monthKey, totalSpend, eventCount }, ...],
+ *     citations: [eventId, ...],
+ *     llm_commentary: "..." | null,
+ *   }
+ */
+
+"use strict";
+
+const { AnalysisSkill } = require("./base");
+
+const SUPPORTED_DIMENSIONS = new Set(["merchant", "category", "counterparty", "month"]);
+
+class SpendingSkill extends AnalysisSkill {
+  constructor(opts) {
+    super({ ...opts, name: "analysis.spending" });
+  }
+
+  async run(options = {}) {
+    const { since, until } = this.resolveTimeWindow(options);
+    const dimension = SUPPORTED_DIMENSIONS.has(options.dimension)
+      ? options.dimension
+      : "merchant";
+    const topN = Number.isFinite(options.topN) && options.topN > 0 ? options.topN : 10;
+
+    // Pull events with subtype = payment / transfer / refund / utility /
+    // redenvelope / investment / income. These are the ones with content.amount.
+    const events = this._fetchPaymentEvents({ since, until });
+    const filtered = this._applyFilters(events, options);
+
+    const summary = this._summarize(filtered, since, until);
+    const breakdown = this._breakdown(filtered, dimension, topN);
+    const trend = this._monthlyTrend(filtered);
+    const citations = filtered.slice(0, 50).map((e) => e.id);
+
+    let llmCommentary = null;
+    if (options.commentary !== false && this.llm) {
+      llmCommentary = await this._llmCommentary(summary, breakdown, dimension, options);
+    }
+
+    return {
+      skill: "analysis.spending",
+      summary,
+      breakdown,
+      trend,
+      citations,
+      llm_commentary: llmCommentary,
+    };
+  }
+
+  _fetchPaymentEvents({ since, until }) {
+    const events = [];
+    // Phase 7 shopping adapters emit subtype="order" — must include so
+    // spending aggregates cover Taobao/JD/Meituan along with Alipay
+    // (payment/transfer) + Email (refund) etc.
+    const subtypes = ["payment", "transfer", "refund", "utility", "redenvelope", "investment", "income", "order"];
+    for (const subtype of subtypes) {
+      const q = { subtype, limit: 5000 };
+      if (since != null) q.since = since;
+      if (until != null) q.until = until;
+      const batch = this.vault.queryEvents(q) || [];
+      for (const e of batch) {
+        // queryEvents may strip extra; we already get full row from vault
+        if (e && e.content && e.content.amount && Number.isFinite(e.content.amount.value)) {
+          events.push(e);
+        }
+      }
+    }
+    return events;
+  }
+
+  _applyFilters(events, options) {
+    let out = events;
+    if (typeof options.merchantFilter === "string" && options.merchantFilter.length > 0) {
+      const needle = options.merchantFilter.toLowerCase();
+      out = out.filter((e) => {
+        const title = (e.content && e.content.title) || "";
+        const counterparty = (e.extra && e.extra.counterparty) || "";
+        return title.toLowerCase().includes(needle)
+          || counterparty.toLowerCase().includes(needle);
+      });
+    }
+    if (typeof options.personId === "string" && options.personId.length > 0) {
+      const memberSet = new Set(this.expandToMergeGroup(options.personId));
+      out = out.filter((e) => {
+        if (memberSet.has(e.actor)) return true;
+        if (Array.isArray(e.participants) && e.participants.some((p) => memberSet.has(p))) return true;
+        return false;
+      });
+    }
+    if (options.direction === "out" || options.direction === "in") {
+      out = out.filter((e) => e.content.amount.direction === options.direction);
+    }
+    return out;
+  }
+
+  _summarize(events, since, until) {
+    let totalSpend = 0;
+    let totalIncome = 0;
+    const counterparties = new Set();
+    for (const e of events) {
+      const v = e.content.amount.value;
+      if (e.content.amount.direction === "in") totalIncome += v;
+      else if (e.content.amount.direction === "out") totalSpend += v;
+      // Identify counterparty for distinctness
+      const cp = (e.extra && e.extra.counterparty) || e.actor;
+      if (cp && cp !== "person-self") counterparties.add(cp);
+    }
+    return {
+      totalSpend: Math.round(totalSpend * 100) / 100,
+      totalIncome: Math.round(totalIncome * 100) / 100,
+      netFlow: Math.round((totalIncome - totalSpend) * 100) / 100,
+      currency: events[0]?.content?.amount?.currency || "CNY",
+      eventCount: events.length,
+      uniqueCounterparties: counterparties.size,
+      period: { since: since || null, until: until || null },
+    };
+  }
+
+  _breakdown(events, dimension, topN) {
+    const buckets = new Map();
+    for (const e of events) {
+      // Only count "out" for spending breakdown — income tracked separately
+      if (e.content.amount.direction !== "out") continue;
+      const key = this._keyFor(e, dimension);
+      if (!key) continue;
+      const cur = buckets.get(key) || { key, totalSpend: 0, eventCount: 0 };
+      cur.totalSpend += e.content.amount.value;
+      cur.eventCount += 1;
+      buckets.set(key, cur);
+    }
+    const totalOut = Array.from(buckets.values()).reduce((s, b) => s + b.totalSpend, 0);
+    const sorted = Array.from(buckets.values())
+      .map((b) => ({
+        ...b,
+        totalSpend: Math.round(b.totalSpend * 100) / 100,
+        percentOfTotal: totalOut > 0 ? Math.round((b.totalSpend / totalOut) * 1000) / 10 : 0,
+      }))
+      .sort((a, b) => b.totalSpend - a.totalSpend)
+      .slice(0, topN);
+    return sorted;
+  }
+
+  _monthlyTrend(events) {
+    const buckets = new Map();
+    for (const e of events) {
+      if (e.content.amount.direction !== "out") continue;
+      const d = new Date(e.occurredAt);
+      if (!Number.isFinite(d.getTime())) continue;
+      const monthKey = `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}`;
+      const cur = buckets.get(monthKey) || { monthKey, totalSpend: 0, eventCount: 0 };
+      cur.totalSpend += e.content.amount.value;
+      cur.eventCount += 1;
+      buckets.set(monthKey, cur);
+    }
+    return Array.from(buckets.values())
+      .map((b) => ({ ...b, totalSpend: Math.round(b.totalSpend * 100) / 100 }))
+      .sort((a, b) => a.monthKey.localeCompare(b.monthKey));
+  }
+
+  _keyFor(event, dimension) {
+    if (dimension === "merchant" || dimension === "counterparty") {
+      return (event.extra && event.extra.counterparty)
+        || (event.content && event.content.title)
+        || "(unknown)";
+    }
+    if (dimension === "category") {
+      return (event.extra && event.extra.category)
+        || event.subtype
+        || "(uncategorized)";
+    }
+    if (dimension === "month") {
+      const d = new Date(event.occurredAt);
+      if (!Number.isFinite(d.getTime())) return "(unknown date)";
+      return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}`;
+    }
+    return null;
+  }
+
+  async _llmCommentary(summary, breakdown, dimension, options) {
+    if (summary.eventCount === 0) return "No spending events found in this period.";
+    const topItems = breakdown.slice(0, 5).map((b) => `${b.key} ¥${b.totalSpend} (${b.percentOfTotal}%)`).join(", ");
+    const periodStr = summary.period.since
+      ? `${new Date(summary.period.since).toISOString().slice(0, 10)} 至 ${new Date(summary.period.until).toISOString().slice(0, 10)}`
+      : "全部时间";
+    const userMsg = `用户的消费数据：
+- 期间：${periodStr}
+- 总支出 ¥${summary.totalSpend} (${summary.currency}), 总收入 ¥${summary.totalIncome}, 净流 ¥${summary.netFlow}
+- 共 ${summary.eventCount} 笔交易, ${summary.uniqueCounterparties} 个独特对方
+- 按 ${dimension} 排名 top 5：${topItems}
+
+请用 2-3 句话点评消费习惯，指出最大支出方向和异常（如有）。中文回答。`;
+    return await this.callLlmCommentary([
+      { role: "system", content: "你是一个理性、克制的财务分析助手。基于事实给出简短结论，不夸张、不臆断。" },
+      { role: "user", content: userMsg },
+    ], { acceptNonLocal: options.acceptNonLocal });
+  }
+}
+
+module.exports = { SpendingSkill, SUPPORTED_DIMENSIONS };