ibill-ai-ledger 1.0.0

package/plugin.js

@@ -0,0 +1,814 @@
+#!/usr/bin/env node
+/**
+ * AI Ledger — Anna Executa 插件（Node.js，零第三方依赖）
+ *
+ * 协议：JSON-RPC 2.0 over stdio（换行分隔）
+ *   宿主 → 插件：initialize / describe / health / invoke
+ *   插件 → 宿主（反向 RPC）：storage/*（APS KV）、sampling/createMessage（LLM）
+ *
+ * 数据（APS scope=app self，key 前缀 ai-ledger/）：
+ *   ai-ledger/meta            -> { schema: 1 }
+ *   ai-ledger/budgets         -> { monthly_total?: number(元), categories?: {catId: 元} }
+ *   ai-ledger/month/<YYYY-MM> -> { entries: [Entry] }
+ *   Entry = { id, type:'expense'|'income', amountCents, categoryId, note,
+ *             date:'YYYY-MM-DD', source:'manual'|'voice'|'chat', createdAt }
+ */
+"use strict";
+
+const readline = require("node:readline");
+const { randomUUID } = require("node:crypto");
+const path = require("node:path");
+const { pathToFileURL } = require("node:url");
+
+// 共享领域核心（ESM）：npm 包内自带 lib/ledger-core.mjs（发布后自包含）；
+// 仓库本地开发时回退到仓库根 shared/ledger-core.js
+let Core = null;
+async function loadCore() {
+  if (Core) return Core;
+  const candidates = [
+    path.join(__dirname, "lib", "ledger-core.mjs"),
+    path.join(__dirname, "..", "..", "shared", "ledger-core.js"),
+  ];
+  for (const p of candidates) {
+    try { Core = await import(pathToFileURL(p).href); return Core; } catch { /* next */ }
+  }
+  throw new Error("cannot load ledger-core.js");
+}
+
+const PLUGIN_VERSION = "1.0.0";
+const STORE_PREFIX = "ai-ledger";
+const K = {
+  meta: `${STORE_PREFIX}/meta`,
+  budgets: `${STORE_PREFIX}/budgets`,
+  month: (m) => `${STORE_PREFIX}/month/${m}`,
+  monthPrefix: `${STORE_PREFIX}/month/`,
+  year: (y) => `${STORE_PREFIX}/year/${y}`,
+  yearPrefix: `${STORE_PREFIX}/year/`,
+};
+
+// ---------------------------------------------------------------------------
+// JSON-RPC 基础
+// ---------------------------------------------------------------------------
+function send(obj) {
+  process.stdout.write(JSON.stringify(obj) + "\n");
+}
+function reply(id, result) {
+  send({ jsonrpc: "2.0", id, result });
+}
+function replyError(id, code, message, data) {
+  send({ jsonrpc: "2.0", id, error: { code, message, ...(data ? { data } : {}) } });
+}
+
+/** 反向 RPC（插件 → 宿主），等待宿主在 stdin 上回传 result/error */
+const pending = new Map();
+function reverse(method, params, timeoutMs = 30000) {
+  return new Promise((resolve, reject) => {
+    const id = randomUUID();
+    const timer = setTimeout(() => {
+      pending.delete(id);
+      reject(Object.assign(new Error(`reverse RPC timeout: ${method}`), { code: -32005 }));
+    }, timeoutMs);
+    pending.set(id, { resolve, reject, timer });
+    send({ jsonrpc: "2.0", id, method, params });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// APS 存储封装（scope=app self，按应用-用户隔离；host_capabilities: aps.kv）
+// ---------------------------------------------------------------------------
+async function kvGet(key) {
+  const r = await reverse("storage/get", { key }, 15000);
+  // 宿主 storage/get 只回 {value}（legacy/APS 均无 exists 字段），
+  // value 为 null/undefined 即视为不存在。
+  const exists = !!(r && r.value !== null && r.value !== undefined);
+  return { value: exists ? r.value : null, exists, etag: r?.etag ?? null };
+}
+async function kvSetRaw(key, value, ifMatch) {
+  const params = { key, value };
+  if (ifMatch) params.if_match = ifMatch;
+  const r = await reverse("storage/set", params, 15000);
+  return { etag: r.etag ?? null };
+}
+async function kvList(prefix) {
+  const r = await reverse("storage/list", { prefix, limit: 100 }, 15000);
+  return r.items || [];
+}
+async function kvDelete(key) {
+  await reverse("storage/delete", { key }, 15000);
+  return { deleted: true };
+}
+
+async function readBudgets() {
+  const r = await kvGet(K.budgets);
+  return r.exists && r.value ? r.value : {};
+}
+async function writeBudgets(budgets, etag) {
+  try {
+    return await kvSetRaw(K.budgets, budgets, etag);
+  } catch (e) {
+    if (e && (e.code === -32023 || /precondition/i.test(String(e.message || "")))) {
+      const cur = await kvGet(K.budgets);
+      const merged = Object.assign({}, cur.value || {}, budgets);
+      return await kvSetRaw(K.budgets, merged, cur.etag);
+    }
+    throw e;
+  }
+}
+
+async function readMonth(m) {
+  const r = await kvGet(K.month(m));
+  if (!r.exists || !r.value || !Array.isArray(r.value.entries)) {
+    return { etag: r.etag, entries: [] };
+  }
+  return { etag: r.etag, entries: r.value.entries };
+}
+
+// ---------------------------------------------------------------------------
+// 归档：压缩/解压 entry + 年度读写
+// ---------------------------------------------------------------------------
+// 全字段 entry → 紧凑归档格式（省 ~60% 空间）
+function compactEntry(e) {
+  return {
+    d: e.date,
+    t: e.type,
+    a: e.amountCents,
+    c: e.categoryId,
+    ...(e.note ? { n: e.note } : {}),
+  };
+}
+// 紧凑归档 → 全字段 entry（解档时还原）
+function expandEntry(c, fallbackId) {
+  return {
+    id: fallbackId,
+    type: c.t || "expense",
+    amountCents: c.a || 0,
+    categoryId: c.c || "other_exp",
+    note: c.n || null,
+    date: c.d,
+    source: "archived",
+    createdAt: null,
+  };
+}
+
+async function readYear(y) {
+  const r = await kvGet(K.year(y));
+  if (!r.exists || !r.value) return { etag: null, archive: null };
+  return { etag: r.etag, archive: r.value };
+}
+async function writeYear(y, archive, etag) {
+  return kvSetRaw(K.year(y), archive, etag);
+}
+
+// 检查某月是否已归档（属于某年的归档）
+async function findArchiveForMonth(month) {
+  const year = month.slice(0, 4);
+  const { archive } = await readYear(year);
+  if (archive && archive.months && archive.months[month]) {
+    return { archive, year, compactEntries: archive.months[month] };
+  }
+  return null;
+}
+/** 读-改-写月分片，冲突时重读并重放 mutation 一次 */
+async function mutateMonth(m, mutate) {
+  let cur = await readMonth(m);
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const next = mutate(cur.entries.map((e) => ({ ...e })));
+    try {
+      await kvSetRaw(K.month(m), { entries: next }, cur.etag);
+      return next;
+    } catch (e) {
+      if (attempt === 0 && (e.code === -32023 || /precondition/i.test(String(e.message || "")))) {
+        cur = await readMonth(m); // 重新拉取，再重放
+        continue;
+      }
+      throw e;
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// LLM 采样（sampling/createMessage）——不可用时返回 null，由调用方降级
+// ---------------------------------------------------------------------------
+const PARSE_SYSTEM_PROMPT = `你是中文记账解析助手。把用户口语化的账单描述抽取为结构化 JSON。
+规则：
+- 金额单位：人民币元，输出数字（如 238.5）。
+- 日期：依据系统提示中的“今天”日期换算相对日期（昨天/前天/上周X），输出 YYYY-MM-DD。
+- type：支出=expense，收入=income。
+- category 取下列 id 之一（也可给中文名）：
+  支出：food餐饮 transport交通 shopping购物 housing居家 entertainment娱乐
+        health医疗 education教育 communication通讯 travel旅行 gifts人情 other_exp其他
+  收入：salary工资 freelance兼职 investment理财 redpacket_in红包 refund退款 other_inc其他
+- 一句话可能包含多笔（“午餐35打车20”输出两条）。
+- note 为去掉金额/日期后的消费内容简述（≤20字），没有可留空。
+- confidence：0~1 的置信度。
+只输出 JSON，不要解释。`;
+
+async function llmParse(text, today) {
+  const yesterday = Core.dateToStr(new Date(new Date(today).getTime() - 86400000));
+  const userPrompt = `今天是 ${today}（昨天 ${yesterday}）。\n记账描述：${text}\n` +
+    `输出 JSON：{"records":[{"type":"expense|income","amount":数字,"category":"id或中文名","date":"YYYY-MM-DD","note":"","confidence":0.9}]}`;
+  const resp = await reverse("sampling/createMessage", {
+    messages: [{ role: "user", content: { type: "text", text: userPrompt } }],
+    maxTokens: 800,
+    systemPrompt: PARSE_SYSTEM_PROMPT,
+    temperature: 0.1,
+    includeContext: "none",
+    responseFormat: { type: "json_object" },
+    onUnsupported: "json_object",
+    metadata: { executa_invoke_id: currentInvokeId() },
+  }, 25000);
+  const raw = resp?.content?.text;
+  if (!raw) throw new Error("sampling returned empty content");
+  const json = JSON.parse(extractJson(raw));
+  const records = Array.isArray(json.records) ? json.records : [json];
+  const drafts = [];
+  for (const r of records) {
+    const amountCents = Core.yuanToCents(r.amount);
+    if (amountCents <= 0) continue;
+    const type = r.type === "income" ? "income" : "expense";
+    drafts.push({
+      type,
+      amountCents,
+      categoryId: Core.normalizeCategory(r.category, type),
+      date: isValidDate(r.date) ? r.date : today,
+      note: r.note ? String(r.note).slice(0, 40) : null,
+      confidence: typeof r.confidence === "number" ? r.confidence : 0.85,
+    });
+  }
+  return drafts;
+}
+function extractJson(s) {
+  const start = s.indexOf("{");
+  const end = s.lastIndexOf("}");
+  return start >= 0 && end > start ? s.slice(start, end + 1) : s;
+}
+function isValidDate(s) {
+  return typeof s === "string" && /^\d{4}-\d{2}-\d{2}$/.test(s);
+}
+function currentInvokeId() {
+  return global.__invokeId || null;
+}
+
+// ---------------------------------------------------------------------------
+// 工具方法
+// ---------------------------------------------------------------------------
+function toolError(code, message, details) {
+  return { success: false, error: { code, message, ...(details ? { details } : {}) } };
+}
+
+async function toolAddEntry(args) {
+  const type = args.type === "income" ? "income" : "expense";
+  const amountCents = Core.yuanToCents(args.amount);
+  if (amountCents <= 0) return toolError("invalid_amount", "金额必须为大于 0 的数字");
+  const today = Core.todayStr();
+  const date = isValidDate(args.date) ? args.date
+    : (typeof args.date_hint === "string" ? Core.resolveDate(args.date_hint, new Date()) : today);
+  const categoryId = Core.normalizeCategory(args.category || args.categoryId, type);
+  const entry = {
+    id: randomUUID(),
+    type,
+    amountCents,
+    categoryId,
+    note: args.note ? String(args.note).slice(0, 60) : null,
+    date,
+    source: ["manual", "voice", "chat"].includes(args.source) ? args.source : "chat",
+    createdAt: new Date().toISOString(),
+  };
+  const month = Core.monthKeyOf(date);
+  await mutateMonth(month, (entries) => entries.concat(entry));
+  const summary = await buildSummary(month);
+  return { success: true, data: { entry, summary } };
+}
+
+function extractMonthKeys(items, prefix) {
+  // items 可能是：
+  //   1. string[]    (Anna APS 真实返回)
+  //   2. [key,value][]  (Map entries 形式)
+  //   3. [{key, etag, ...}]  (harness mock 形式)
+  return items
+    .map((k) => {
+      if (typeof k === "string") return k;
+      if (k && typeof k === "object" && typeof k.key === "string") return k.key; // 形式 3
+      if (Array.isArray(k) && typeof k[0] === "string") return k[0];             // 形式 2
+      return null;
+    })
+    .filter((k) => typeof k === "string" && k.startsWith(prefix))
+    .map((k) => k.slice(prefix.length));
+}
+
+async function toolDeleteEntry(args) {
+  if (!args.id) return toolError("invalid_arg", "缺少 id");
+  let scanMonths;
+  if (args.month) {
+    scanMonths = [args.month];
+  } else {
+    const allItems = await kvList(K.monthPrefix);
+    scanMonths = extractMonthKeys(allItems, K.monthPrefix);
+    const now = new Date();
+    for (let i = 0; i < 6; i++) {
+      const d = new Date(now.getFullYear(), now.getMonth() - i, 1);
+      const m = `${d.getFullYear()}-${Core.pad2(d.getMonth() + 1)}`;
+      if (!scanMonths.includes(m)) scanMonths.push(m);
+    }
+  }
+  let removed = null, removedMonth = null;
+  for (const m of scanMonths) {
+    const found = await findAndRemoveFromMonth(m, args.id);
+    if (found) { removed = found.entry; removedMonth = m; break; }
+  }
+  if (!removed) return toolError("not_found", "未找到该条记录");
+  return { success: true, data: { deleted: removed, month: removedMonth } };
+}
+
+async function findAndRemoveFromMonth(month, id) {
+  let found = null;
+  await mutateMonth(month, (entries) => {
+    const e = entries.find((x) => x.id === id);
+    if (e) { found = e; return entries.filter((x) => x.id !== id); }
+    return entries;
+  });
+  return found ? { entry: found } : null;
+}
+
+async function toolUpdateEntry(args) {
+  if (!args.id) return toolError("invalid_arg", "缺少 id");
+  // 1. 找原记录：扫所有已知月份 key
+  const allItems = await kvList(K.monthPrefix);
+  const scanMonths = extractMonthKeys(allItems, K.monthPrefix);
+  // 兜底：近 6 个月
+  const now = new Date();
+  for (let i = 0; i < 6; i++) {
+    const d = new Date(now.getFullYear(), now.getMonth() - i, 1);
+    const m = `${d.getFullYear()}-${Core.pad2(d.getMonth() + 1)}`;
+    if (!scanMonths.includes(m)) scanMonths.push(m);
+  }
+  let oldEntry = null, oldMonth = null;
+  for (const m of scanMonths) {
+    const { entries } = await readMonth(m);
+    const found = entries.find((e) => e.id === args.id);
+    if (found) { oldEntry = found; oldMonth = m; break; }
+  }
+  if (!oldEntry) return toolError("not_found", "未找到该条记录");
+
+  // 2. 合并新值
+  const patched = { ...oldEntry };
+  if (args.type) patched.type = args.type;
+  if (typeof args.amountCents === "number") patched.amountCents = args.amountCents;
+  if (args.amount != null) {
+    const c = Math.round(Number(args.amount) * 100);
+    if (c > 0) patched.amountCents = c;
+  }
+  if (args.categoryId) patched.categoryId = args.categoryId;
+  if (args.category) {
+    const m = /^(expense|income):(.+)$/.exec(String(args.category));
+    patched.categoryId = m ? m[2] : String(args.category);
+  }
+  if (args.date) patched.date = String(args.date);
+  if ("note" in args) patched.note = args.note ? String(args.note).slice(0, 60) : null;
+
+  const newMonth = Core.monthKeyOf(patched.date);
+
+  // 3. 同月份 — 原地替换；跨月份 — 删旧月 + 加新月
+  if (oldMonth === newMonth) {
+    await mutateMonth(newMonth, (entries) =>
+      entries.map((e) => (e.id === patched.id ? patched : e)));
+  } else {
+    await mutateMonth(oldMonth, (entries) => entries.filter((e) => e.id !== patched.id));
+    await mutateMonth(newMonth, (entries) => entries.concat(patched));
+  }
+
+  // 4. summary 返回（按新月份）
+  const summary = await buildSummary(newMonth);
+  return { success: true, data: { entry: patched, summary, movedMonth: oldMonth !== newMonth } };
+}
+
+async function toolListEntries(args) {
+  const month = args.month || Core.todayStr().slice(0, 7);
+  const { entries } = await readMonth(month);
+  const sorted = [...entries].sort((a, b) =>
+    (b.date + b.createdAt).localeCompare(a.date + a.createdAt));
+  return { success: true, data: { month, entries: sorted } };
+}
+
+async function toolGetState() {
+  const budgets = await readBudgets();
+  // 扫所有已知月份 key（跨月数据也能加载）
+  const allMonthItems = await kvList(K.monthPrefix);
+  const months = extractMonthKeys(allMonthItems, K.monthPrefix);
+  // 兜底：近 6 个月
+  const now = new Date();
+  for (let i = 0; i < 6; i++) {
+    const d = new Date(now.getFullYear(), now.getMonth() - i, 1);
+    const m = `${d.getFullYear()}-${Core.pad2(d.getMonth() + 1)}`;
+    if (!months.includes(m)) months.push(m);
+  }
+  const all = [];
+  for (const m of months) {
+    const { entries } = await readMonth(m);
+    all.push(...entries);
+  }
+
+  // 加载已归档的往年数据（从 year key 还原为 entries）
+  const allYearItems = await kvList(K.yearPrefix);
+  const years = extractMonthKeys(allYearItems, K.yearPrefix);
+  const archivedYears = [];
+  for (const y of years) {
+    const { archive } = await readYear(y);
+    if (archive && archive.months) {
+      archivedYears.push({ year: y, entryCount: archive.summary?.entryCount || 0 });
+      for (const [monthKey, compactEntries] of Object.entries(archive.months)) {
+        if (!Array.isArray(compactEntries)) continue;
+        const expanded = compactEntries.map((c, i) =>
+          expandEntry(c, `${monthKey}-arc-${i}`));
+        all.push(...expanded);
+      }
+    }
+  }
+
+  const entries = all.sort((a, b) =>
+    (b.date + (b.createdAt || "")).localeCompare(a.date + (a.createdAt || "")));
+  return { success: true, data: { budgets, months, entries, archivedYears } };
+}
+
+async function toolSetBudget(args) {
+  const cur = await kvGet(K.budgets);
+  const curVal = cur.exists && cur.value ? cur.value : {};
+  const next = { ...curVal };
+  if (args.monthly_total !== undefined && args.monthly_total !== null) {
+    const c = Core.yuanToCents(args.monthly_total);
+    if (c <= 0) return toolError("invalid_amount", "月预算必须为大于 0 的数字");
+    next.monthly_total = args.monthly_total; // 预算以「元」存储
+  }
+  if (args.categories && typeof args.categories === "object") {
+    next.categories = { ...(curVal.categories || {}) };
+    for (const [cat, val] of Object.entries(args.categories)) {
+      const c = Core.yuanToCents(val);
+      if (c > 0) next.categories[cat] = val;
+      else delete next.categories[cat];
+    }
+  }
+  // 携带读到的 etag 做乐观锁；writeBudgets 冲突时会重读合并重试
+  await writeBudgets(next, cur.etag);
+  return { success: true, data: { budgets: next } };
+}
+
+async function buildSummary(month) {
+  const m = month || Core.todayStr().slice(0, 7);
+  // 先尝试月度 key
+  let { entries } = await readMonth(m);
+  // 如果月度 key 为空，尝试从年度归档读
+  if (entries.length === 0) {
+    const found = await findArchiveForMonth(m);
+    if (found) {
+      entries = found.compactEntries.map((c, i) =>
+        expandEntry(c, `${m}-arc-${i}`));
+    }
+  }
+  const budgets = await readBudgets();
+  const s = Core.summarize(entries, budgets, m);
+  return {
+    month: s.month,
+    expenseCents: s.expenseCents,
+    incomeCents: s.incomeCents,
+    balanceCents: s.balanceCents,
+    byCategory: s.byCategory,
+    daily: s.daily,
+    budget: s.budget,
+  };
+}
+
+async function toolGetSummary(args) {
+  const summary = await buildSummary(args.month);
+  return { success: true, data: { summary } };
+}
+
+async function toolParseText(args, ctx) {
+  const text = String(args.text || "").trim();
+  if (!text) return toolError("invalid_arg", "缺少 text");
+  const today = Core.todayStr();
+  let drafts = null;
+  let engine = "rules";
+  if (ctx?.sampling_token) {
+    try {
+      drafts = await llmParse(text, today);
+      engine = "llm";
+    } catch (e) {
+      process.stderr.write(`[ai-ledger] sampling failed, fallback to rules: ${e.message || e}\n`);
+      drafts = null;
+    }
+  }
+  if (!drafts || drafts.length === 0) {
+    const r = Core.parseRules(text, new Date());
+    drafts = r.drafts;
+    engine = r.engine; // "rules"
+  }
+  if (drafts.length === 0) return { success: false, error: { code: "no_amount", message: "没能从这句话里听出金额，换个说法试试？" } };
+  return { success: true, data: { drafts, engine } };
+}
+
+// ---------------------------------------------------------------------------
+// archive_year — 将指定年份的12个月度记录归档为1个年度 key
+// ---------------------------------------------------------------------------
+async function toolArchiveYear(args) {
+  const year = String(args.year || (new Date().getFullYear() - 1));
+  const yearNum = parseInt(year, 10);
+  if (!yearNum || yearNum < 2000 || yearNum > 2100) {
+    return toolError("invalid_arg", `无效的年份: ${year}`);
+  }
+
+  // 1. 检查是否已归档
+  const existing = await readYear(year);
+  if (existing.archive) {
+    return toolError("already_archived", `${year} 年已归档`);
+  }
+
+  // 2. 读 12 个月的数据
+  const monthsData = {};
+  let totalEntries = 0;
+  let expenseCents = 0, incomeCents = 0;
+  const byCategory = {};
+
+  for (let m = 1; m <= 12; m++) {
+    const monthKey = `${year}-${Core.pad2(m)}`;
+    const { entries } = await readMonth(monthKey);
+    if (entries.length === 0) continue;
+    monthsData[monthKey] = entries.map(compactEntry);
+    totalEntries += entries.length;
+    for (const e of entries) {
+      if (e.type === "expense") {
+        expenseCents += e.amountCents;
+        byCategory[e.categoryId] = (byCategory[e.categoryId] || 0) + e.amountCents;
+      } else {
+        incomeCents += e.amountCents;
+      }
+    }
+  }
+
+  if (totalEntries === 0) {
+    return toolError("no_data", `${year} 年没有可归档的记录`);
+  }
+
+  // 3. 构建归档对象
+  const archive = {
+    year: yearNum,
+    archivedAt: new Date().toISOString(),
+    months: monthsData,
+    summary: {
+      expenseCents,
+      incomeCents,
+      balanceCents: incomeCents - expenseCents,
+      byCategory,
+      entryCount: totalEntries,
+    },
+  };
+
+  // 4. 写年度 key
+  await writeYear(year, archive, null);
+
+  // 5. 删除 12 个月度 key（释放 KV 空间）
+  let deletedKeys = [];
+  for (let m = 1; m <= 12; m++) {
+    const monthKey = `${year}-${Core.pad2(m)}`;
+    if (monthsData[monthKey]) {
+      try {
+        await kvDelete(K.month(monthKey));
+        deletedKeys.push(monthKey);
+      } catch (e) {
+        // 删除失败不阻断，记录即可
+        process.stderr.write(`[ai-ledger] archive: 删除 ${monthKey} 失败: ${e.message}\n`);
+      }
+    }
+  }
+
+  return {
+    success: true,
+    data: {
+      year: yearNum,
+      archivedAt: archive.archivedAt,
+      entryCount: totalEntries,
+      deletedMonthKeys: deletedKeys,
+      summary: archive.summary,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// unarchive_year — 解档：把年度 key 还原回月度 key（需要编辑往年记录时用）
+// ---------------------------------------------------------------------------
+async function toolUnarchiveYear(args) {
+  const year = String(args.year);
+  if (!year) return toolError("invalid_arg", "缺少 year 参数");
+
+  const { archive, etag } = await readYear(year);
+  if (!archive) {
+    return toolError("not_found", `${year} 年未找到归档`);
+  }
+
+  // 还原每个月的 entries
+  let restoredMonths = 0, restoredEntries = 0;
+  for (const [monthKey, compactEntries] of Object.entries(archive.months || {})) {
+    if (!Array.isArray(compactEntries) || compactEntries.length === 0) continue;
+    // 还原全字段 entries
+    const entries = compactEntries.map((c, i) =>
+      expandEntry(c, `${monthKey}-${i}-${Math.random().toString(36).slice(2, 8)}`));
+    await mutateMonth(monthKey, (existing) => existing.concat(entries));
+    restoredMonths++;
+    restoredEntries += entries.length;
+  }
+
+  // 删除年度 key
+  try {
+    await kvDelete(K.year(year));
+  } catch (e) {
+    process.stderr.write(`[ai-ledger] unarchive: 删除 year key 失败: ${e.message}\n`);
+  }
+
+  return {
+    success: true,
+    data: {
+      year: parseInt(year, 10),
+      restoredMonths,
+      restoredEntries,
+    },
+  };
+}
+
+const TOOLS = {
+  add_entry: toolAddEntry,
+  update_entry: toolUpdateEntry,
+  delete_entry: toolDeleteEntry,
+  list_entries: toolListEntries,
+  get_state: toolGetState,
+  set_budget: toolSetBudget,
+  get_summary: toolGetSummary,
+  parse_text: toolParseText,
+  archive_year: toolArchiveYear,
+  unarchive_year: toolUnarchiveYear,
+};
+
+// ---------------------------------------------------------------------------
+// 插件 manifest（describe）
+// ---------------------------------------------------------------------------
+const MANIFEST = {
+  display_name: "AI Ledger 记账本",
+  version: PLUGIN_VERSION,
+  description: "AI-native personal bookkeeping: record expenses/income via chat or voice, "
+    + "monthly stats, category budgets, and durable per-user cloud storage. "
+    + "AI 记账工具：聊天/语音记账、月度统计、分类预算，数据云端保存。",
+  author: "ai-ledger",
+  tags: ["productivity", "finance", "ledger", "anna-app", "ai-native"],
+  host_capabilities: ["aps.kv", "llm.sample"],
+  runtime: { type: "node", min_version: "18.0.0" },
+  tools: [
+    {
+      name: "parse_text",
+      description: "把用户一句自然语言（中文口语，如“昨天和朋友吃火锅花了238块”“工资发了12000”）"
+        + "解析为一条或多条结构化记账草稿（金额/收支类型/分类/日期/备注）。"
+        + "返回 drafts 供用户确认，不直接入账。Parse a free-text bookkeeping sentence into "
+        + "structured draft entry(s); does NOT save anything.",
+      parameters: [
+        { name: "text", type: "string", description: "用户的记账描述原文 / the raw sentence", required: true },
+      ],
+    },
+    {
+      name: "add_entry",
+      description: "Save one ledger entry. Amount is in USD dollars. Use after the user confirms a parsed draft or states all details.",
+      parameters: [
+        { name: "type", type: "string", description: "expense (default) or income", required: false, default: "expense" },
+        { name: "amount", type: "number", description: "Amount in USD, e.g. 35 or 86.5", required: true },
+        { name: "category", type: "string", description: "Category id or name: food/transport/shopping/housing/entertainment/health/education/communication/travel/gifts/other_exp (expense); salary/freelance/investment/redpacket_in/refund/other_inc (income)", required: false },
+        { name: "note", type: "string", description: "Optional note, ≤ 60 chars", required: false },
+        { name: "date", type: "string", description: "Date YYYY-MM-DD, default today", required: false },
+        { name: "source", type: "string", description: "manual/voice/chat, default chat", required: false },
+      ],
+    },
+    { name: "list_entries",
+      description: "列出指定月份（默认本月）的全部账目，按日期倒序。List entries of a month (YYYY-MM, default current).",
+      parameters: [
+        { name: "month", type: "string", description: "月份 YYYY-MM，如 2026-09", required: false },
+      ] },
+    { name: "delete_entry",
+      description: "按 id 删除一条账目。Delete one entry by id.",
+      parameters: [
+        { name: "id", type: "string", description: "条目 id", required: true },
+        { name: "month", type: "string", description: "条目所在月份 YYYY-MM（可选，不传则在近4个月查找）", required: false },
+      ] },
+    { name: "update_entry",
+      description: "修改一条已有账目（金额、类型、分类、日期、备注）。可以跨月份移动，插件自动处理旧月/新月的搬迁。Update an existing entry's fields (amount/type/category/date/note). Cross-month moves are handled automatically.",
+      parameters: [
+        { name: "id", type: "string", description: "要修改的条目 id", required: true },
+        { name: "type", type: "string", description: "expense / income（可选）", required: false },
+        { name: "amount", type: "number", description: "新金额（美元），如 15 或 8.5（可选）", required: false },
+        { name: "categoryId", type: "string", description: "新分类 id（可选）", required: false },
+        { name: "date", type: "string", description: "新日期 YYYY-MM-DD（可选，跨月会自动搬迁）", required: false },
+        { name: "note", type: "string", description: "新备注，最多 60 字符，传空字符串即清空（可选）", required: false },
+      ] },
+    { name: "get_summary",
+      description: "获取某月汇总：支出/收入/结余总额、分类占比、每日支出、预算进度与是否超支。"
+        + "Monthly summary for answering questions like “这个月花了多少”.",
+      parameters: [
+        { name: "month", type: "string", description: "月份 YYYY-MM，默认本月", required: false },
+      ] },
+    { name: "set_budget",
+      description: "设置月度预算：月总额和/或分类预算（单位元）。Set monthly total budget and/or per-category budgets.",
+      parameters: [
+        { name: "monthly_total", type: "number", description: "每月总预算（元），如 3000", required: false },
+        { name: "categories", type: "object", description: "分类预算映射，如 {\"food\":1500,\"transport\":300}", required: false },
+      ] },
+    { name: "get_state",
+      description: "获取预算与最近3个月的全部账目（App 窗口打开时水合用）。Hydrate the app window state.",
+      parameters: [] },
+    { name: "archive_year",
+      description: "将指定年份的12个月度记录归档为1个年度key（紧凑格式），删除原月度key以节省KV存储容量。归档后记录变为只读，可通过 unarchive_year 解档。"
+        + "Archive a year's monthly records into a single compact yearly key, deleting the monthly keys to save KV storage. "
+        + "Archived records become read-only; use unarchive_year to restore.",
+      parameters: [
+        { name: "year", type: "string", description: "要归档的年份 YYYY，如 2025。不传则默认去年。Year to archive, default last year.", required: false },
+      ] },
+    { name: "unarchive_year",
+      description: "将年度归档还原回月度记录，使其可再次编辑。Unarchive a year: restore monthly records from the yearly archive key, making them editable again.",
+      parameters: [
+        { name: "year", type: "string", description: "要解档的年份 YYYY，如 2025。Year to unarchive.", required: true },
+      ] },
+  ],
+};
+
+// ---------------------------------------------------------------------------
+// stdio 主循环
+// ---------------------------------------------------------------------------
+async function main() {
+  await loadCore();
+  const rl = readline.createInterface({ input: process.stdin });
+
+  rl.on("line", (line) => {
+  const trimmed = line.trim();
+  if (!trimmed) return;
+  let msg;
+  try { msg = JSON.parse(trimmed); } catch { return; }
+
+  // 反向 RPC 的响应（宿主回传）：无 method 字段
+  if (!msg.method) {
+    const p = pending.get(msg.id);
+    if (!p) return;
+    pending.delete(msg.id);
+    clearTimeout(p.timer);
+    if (msg.error) {
+      const err = new Error(msg.error.message || "reverse RPC error");
+      err.code = msg.error.code;
+      err.data = msg.error.data;
+      p.reject(err);
+    } else {
+      p.resolve(msg.result);
+    }
+    return;
+  }
+
+  // 宿主 → 插件 的请求
+  (async () => {
+    try {
+      switch (msg.method) {
+        case "initialize":
+          reply(msg.id, {
+            protocolVersion: "2.0",
+            serverInfo: { name: "ai-ledger", version: PLUGIN_VERSION },
+            capabilities: { sampling: {}, storage: {} },
+          });
+          break;
+        case "describe":
+          reply(msg.id, MANIFEST);
+          break;
+        case "health":
+          reply(msg.id, { status: "ready", message: "", details: {} });
+          break;
+        case "invoke": {
+          const params = msg.params || {};
+          const ctx = params.context || {};
+          global.__invokeId = ctx.invoke_id || null;
+          const handler = TOOLS[params.tool];
+          if (!handler) {
+            replyError(msg.id, -32601, `unknown tool: ${params.tool}`);
+          } else {
+            const result = await handler(params.arguments || {}, ctx);
+            reply(msg.id, result);
+          }
+          break;
+        }
+        default:
+          replyError(msg.id, -32601, `unknown method: ${msg.method}`);
+      }
+    } catch (e) {
+      process.stderr.write(`[ai-ledger] handler error: ${e.stack || e}\n`);
+      replyError(msg.id, e.code ?? -32603, e.message || String(e));
+    } finally {
+      global.__invokeId = null;
+    }
+  })();
+  });
+
+  rl.on("close", () => process.exit(0));
+}
+
+main().catch((e) => {
+  process.stderr.write(`[ai-ledger] fatal: ${e.stack || e}\n`);
+  process.exit(1);
+});