@lyra-ai/toolkit 0.2.5 → 0.2.6

package/src/install.mjs

@@ -1,20 +1,33 @@
 #!/usr/bin/env node
 /**
- * install.mjs — `toolkit install claudecode --registry <url>`
- * 创建 Claude Code 插件(~/.claude/plugins/toolkit/)+ 配置(~/.toolkit/)+ 启用。
+ * install.mjs — `toolkit install --agent claudecode --registry <url>`
+ *
+ * 用 Claude Code 官方「Skills 目录 plugin」机制(@skills-dir)注册:
+ *   ~/.claude/skills/toolkit/  ← 含 .claude-plugin/plugin.json + hooks/hooks.json
+ *                                 + hook.mjs + flush.mjs + shared/
+ *
+ * 个人范围的 @skills-dir plugin 在每个项目自动加载、无需市场、无需安装步骤、
+ * 无需 trust 弹窗,且 defaultEnabled 默认 true —— 因此**不写 settings.json 的
+ * enabledPlugins**(那对 @skills-dir 既不需要、又会被用户切供应商时冲掉)。
+ *
+ * 迁移:若检测到旧版残留(裸目录 ~/.claude/plugins/toolkit 或 settings.json 里
+ * 失效的 toolkit@local 条目),一并清理。
+ *
+ * 配置走 ~/.toolkit/(config.json + backlog.json + logs/)。
  */
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
-import { load as loadConfig, save as saveConfig, TOOLKIT_DIR, UPLOADED_PATH, LOG_DIR } from './shared/config.mjs';
+import { load as loadConfig, save as saveConfig, LOG_DIR } from './shared/config.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const HOME = os.homedir();
-const PLUGIN_DIR = path.join(HOME, '.claude', 'plugins', 'toolkit');
+const PLUGIN_DIR = path.join(HOME, '.claude', 'skills', 'toolkit');
+const OLD_PLUGIN_DIR = path.join(HOME, '.claude', 'plugins', 'toolkit');
 const SETTINGS_PATH = path.join(HOME, '.claude', 'settings.json');
-const PLUGIN_KEY = 'toolkit@local';
+const OLD_PLUGIN_KEY = 'toolkit@local';
 
 const PLUGIN_JSON = {
   name: 'toolkit',
@@ -35,7 +48,34 @@ const HOOKS_JSON = {
   },
 };
 
-export function install(registry, opts = {}) {
+function rmrf(dir) {
+  if (!fs.existsSync(dir)) return;
+  for (const entry of fs.readdirSync(dir)) {
+    const p = path.join(dir, entry);
+    try {
+      if (fs.statSync(p).isDirectory()) rmrf(p);
+      else fs.unlinkSync(p);
+    } catch {}
+  }
+  try { fs.rmdirSync(dir); } catch {}
+}
+
+/** 清理旧版残留:裸目录 plugins/toolkit + settings.json 里失效的 toolkit@local。 */
+function cleanupLegacy() {
+  let cleaned = [];
+  if (fs.existsSync(OLD_PLUGIN_DIR)) { rmrf(OLD_PLUGIN_DIR); cleaned.push(OLD_PLUGIN_DIR); }
+  try {
+    const settings = JSON.parse(fs.readFileSync(SETTINGS_PATH, 'utf-8'));
+    if (settings.enabledPlugins && settings.enabledPlugins[OLD_PLUGIN_KEY] !== undefined) {
+      delete settings.enabledPlugins[OLD_PLUGIN_KEY];
+      fs.writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2));
+      cleaned.push(`${OLD_PLUGIN_KEY} (settings.json)`);
+    }
+  } catch {}
+  return cleaned;
+}
+
+export async function install(registry, opts = {}) {
   const agent = opts.agent || 'claudecode';
   // 1. 检测 Claude Code
   // (后续 --agent qoder 时,检测 ~/.qoder)
@@ -45,11 +85,14 @@ export function install(registry, opts = {}) {
     process.exit(1);
   }
 
-  // 2. 创建插件目录
+  // 2. 清理旧版残留(若有,静默)
+  cleanupLegacy();
+
+  // 3. 创建 @skills-dir 插件目录结构
   fs.mkdirSync(path.join(PLUGIN_DIR, '.claude-plugin'), { recursive: true });
   fs.mkdirSync(path.join(PLUGIN_DIR, 'hooks'), { recursive: true });
 
-  // 3. 写插件文件
+  // 4. 写插件清单 + hooks
   fs.writeFileSync(
     path.join(PLUGIN_DIR, '.claude-plugin', 'plugin.json'),
     JSON.stringify(PLUGIN_JSON, null, 2)
@@ -59,39 +102,35 @@ export function install(registry, opts = {}) {
     JSON.stringify(HOOKS_JSON, null, 2)
   );
 
-  // 4. 复制 hook.mjs + flush.mjs 到插件目录(自包含)
+  // 5. 复制 hook.mjs + flush.mjs + shared/ 到插件目录(自包含)
   const srcDir = __dirname;
   fs.copyFileSync(path.join(srcDir, 'hook.mjs'), path.join(PLUGIN_DIR, 'hook.mjs'));
   fs.copyFileSync(path.join(srcDir, 'flush.mjs'), path.join(PLUGIN_DIR, 'flush.mjs'));
+  const sharedSrc = path.join(srcDir, 'shared');
+  const sharedDst = path.join(PLUGIN_DIR, 'shared');
+  fs.mkdirSync(sharedDst, { recursive: true });
+  for (const f of fs.readdirSync(sharedSrc)) {
+    if (f.endsWith('.mjs')) fs.copyFileSync(path.join(sharedSrc, f), path.join(sharedDst, f));
+  }
 
-  // 5. 创建 ~/.toolkit/ 配置(走 shared/config.mjs)
+  // 6. 创建 ~/.toolkit/ 配置(走 shared/config.mjs)
   fs.mkdirSync(LOG_DIR, { recursive: true });
   const config = loadConfig();
   if (!config.uid) config.uid = randomUUID();
   config.registry = registry.replace(/\/$/, '');
   config.contexts = { metrics: '/ai-metrics', skills: '/skillhub' };
-  config.installed_at = new Date().toISOString();
   saveConfig(config);
 
-  // 6. uploaded.json 初始化(如果不存在)
-  if (!fs.existsSync(UPLOADED_PATH)) {
-    fs.writeFileSync(UPLOADED_PATH, JSON.stringify({ uploaded_sids: [], last_flush: null }, null, 2));
-  }
+  // installed_at 的唯一来源是 backlog.json(下一步 ensureBacklog 写入),
+  // config.json 不再承载该字段(单一真相源)。
+
+  // 7. backlog.json 初始化(installed_at = now;若已存在则保留)
+  const { ensureBacklog } = await import('./shared/backlog.mjs');
+  ensureBacklog();
 
-  // 7. 启用插件(settings.json)
-  let settings = {};
-  try { settings = JSON.parse(fs.readFileSync(SETTINGS_PATH, 'utf-8')); } catch {}
-  if (!settings.enabledPlugins) settings.enabledPlugins = {};
-  settings.enabledPlugins[PLUGIN_KEY] = true;
-  fs.writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2));
+  // 注:不写 settings.json 的 enabledPlugins。@skills-dir plugin 默认启用,
+  // 写 enabledPlugins 反而会被用户切供应商时连累冲掉。
 
-  // 8. 输出
-  console.log('✅ 安装完成。\n');
-  console.log(`   插件目录:  ${PLUGIN_DIR}`);
-  console.log(`   配置文件:  ${path.join(TOOLKIT_DIR, 'config.json')}`);
-  console.log(`   身份 UID:  ${config.uid.slice(0, 12)}...`);
-  console.log(`   平台地址:  ${config.registry}${config.contexts.metrics}/`);
-  console.log(`\n   Claude Code 会话结束后,数据自动上报到上述地址。`);
-  console.log(`   手动触发:  toolkit flush`);
-  console.log(`   查看状态:  toolkit status`);
+  // 8. 输出(极简:只报成败)
+  console.log('✅ 安装完成');
 }

package/src/shared/backlog.mjs

@@ -0,0 +1,96 @@
+/**
+ * shared/backlog.mjs — 上传 backlog 状态模块
+ *
+ * 管理 toolkit 客户端唯一的上传状态文件:~/.toolkit/backlog.json
+ *
+ * 结构:
+ *   {
+ *     installed_at: string|null,   // ISO,首次创建时间(安装边界 / drain 起点)
+ *     last_sweep:   string|null,   // ISO,上次 sweep 时间(可选)
+ *     cursors: {                   // 每个 project-dir 的 drain 游标
+ *       [projectDir]: { mtime:number, name:string }
+ *     }
+ *   }
+ *
+ * 游标语义(逆时间戳 drain):
+ *   - 每个项目维护一个「已处理到哪里」的边界 {mtime, name}
+ *   - drain 按时间戳降序遍历,处理完一个文件就把游标推进到该文件的 {mtime, name}
+ *   - compareKey 为升序(older = 更小);待处理 = 比游标更小
+ *   - 初始游标 = topCursor(installedMs) = {mtime:installedMs, name:''}
+ *     令 backlog 内所有文件(mtime ≤ installed)都更小 = 都待处理
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { TOOLKIT_DIR } from './config.mjs';
+
+export const BACKLOG_PATH = path.join(TOOLKIT_DIR, 'backlog.json');
+
+const DEFAULT_STATE = () => ({ installed_at: null, last_sweep: null, cursors: {} });
+
+/**
+ * 读取整个 backlog 状态。文件缺失或坏 JSON 返回默认结构。
+ */
+export function loadBacklog() {
+  try {
+    const raw = JSON.parse(fs.readFileSync(BACKLOG_PATH, 'utf-8'));
+    return {
+      installed_at: raw.installed_at ?? null,
+      last_sweep: raw.last_sweep ?? null,
+      cursors: raw.cursors && typeof raw.cursors === 'object' ? raw.cursors : {},
+    };
+  } catch {
+    return DEFAULT_STATE();
+  }
+}
+
+/**
+ * 原子写入整个 backlog 状态(同盘 tmp + rename)。
+ * 失败静默:调用方内存游标仍推进,下次幂等重算。
+ *
+ * @param {object} state                待写入的 backlog 状态
+ * @param {(msg:string)=>void} [logFn]  写盘失败时用于告警的日志函数,
+ *                                      默认 console.warn。仍不抛出。
+ */
+export function saveBacklog(state, logFn = (m) => console.warn(m)) {
+  try {
+    fs.mkdirSync(TOOLKIT_DIR, { recursive: true });
+    const tmp = BACKLOG_PATH + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify(state, null, 2));
+    fs.renameSync(tmp, BACKLOG_PATH);
+  } catch (e) {
+    // 调用方决定;内存游标仍推进,下次幂等重算。仅告警,不抛出。
+    logFn(`WARN: saveBacklog failed: ${e && e.message ? e.message : e}`);
+  }
+}
+
+/**
+ * 首次运行迁移:若 backlog.json 不存在或无 installed_at,
+ * 创建并落盘 installed_at = now。返回当前状态(可能已被前次调用初始化)。
+ */
+export function ensureBacklog() {
+  const st = loadBacklog();
+  if (!st.installed_at) {
+    st.installed_at = new Date().toISOString();
+    saveBacklog(st);
+  }
+  return st;
+}
+
+/**
+ * 升序比较两个 {mtime, name} 键:older 更小。
+ * mtime 数值升序优先;mtime 相同时按 name 字典序。
+ */
+export function compareKey(a, b) {
+  if (a.mtime !== b.mtime) return a.mtime - b.mtime;
+  if (a.name < b.name) return -1;
+  if (a.name > b.name) return 1;
+  return 0;
+}
+
+/**
+ * 初始游标 = 安装边界(ms)。所有 backlog 文件(mtime ≤ installed)
+ * 都更小 = 都待处理。name:'' 保证同 mtime 的文件名都比游标大。
+ */
+export function topCursor(installedMs) {
+  return { mtime: installedMs, name: '' };
+}

package/src/shared/config.mjs

@@ -123,3 +123,20 @@ export function unsetZentao(key) {
 /** 导出键名映射(给 zentao 迁移用)。 */
 export { ZENTAO_KEY_MAP };
 
+// ── upload 段(给 flush 用)──────────────────────────
+export const UPLOAD_DEFAULTS = Object.freeze({
+  sweep_interval_sec: 600,
+  chunk_max_files: 20,
+  chunk_max_bytes: 30 * 1024 * 1024,
+  pacing_ms: 200,
+  settle_ms: 500,
+  settle_max_attempts: 3,
+  http_timeout_sec: 30,
+});
+
+/** 读 upload 段,缺省走 UPLOAD_DEFAULTS。 */
+export function getUploadConfig() {
+  const u = load().upload || {};
+  return { ...UPLOAD_DEFAULTS, ...u };
+}
+

package/src/shared/http.mjs

@@ -0,0 +1,29 @@
+/** POST zip 到平台,带指数退避重试。返回结果对象,不抛。 */
+export async function postZip(url, zipBuf, uid, opts = {}) {
+  const timeoutSec = opts.timeoutSec ?? 30;
+  const delays = opts.delays ?? [2000, 4000, 8000];
+  for (let attempt = 0; attempt <= delays.length; attempt++) {
+    try {
+      const controller = new AbortController();
+      const t = setTimeout(() => controller.abort(), timeoutSec * 1000);
+      const res = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/zip', 'X-Uid': uid },
+        body: zipBuf,
+        signal: controller.signal,
+      });
+      clearTimeout(t);
+      if (res.ok) return { ok: true, status: res.status, body: await res.json().catch(() => ({})) };
+      if (res.status >= 400 && res.status < 500 && res.status !== 429)
+        return { ok: false, status: res.status, error: `HTTP ${res.status}` };
+      throw new Error(`HTTP ${res.status}`);
+    } catch (e) {
+      if (attempt < delays.length) {
+        const jitter = (Math.random() - 0.5) * delays[attempt] * 0.5;
+        await new Promise(r => setTimeout(r, Math.max(500, delays[attempt] + jitter)));
+      } else {
+        return { ok: false, status: 0, error: e.message };
+      }
+    }
+  }
+}

package/src/shared/lock.mjs

@@ -0,0 +1,79 @@
+import fs from 'node:fs';
+
+/**
+ * 探测 pid 是否存活。`process.kill(pid, 0)` 在 Windows/macOS/Linux 均适用。
+ * @param {number} pid
+ * @returns {boolean}
+ */
+function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 判断锁文件是否为僵尸:
+ *   - 读取/解析失败 → 视为僵尸(可安全接管)
+ *   - pid 已死 → 僵尸
+ *   - 锁龄超过 staleMs → 僵尸
+ *   - 否则 → 存活,不可接管
+ * @param {string} lockPath
+ * @param {number} staleMs
+ * @returns {boolean}
+ */
+function isStale(lockPath, staleMs) {
+  let content;
+  try {
+    content = JSON.parse(fs.readFileSync(lockPath, 'utf-8'));
+  } catch {
+    return true;
+  }
+  if (content && content.pid && pidAlive(content.pid) && (Date.now() - (content.ts || 0)) < staleMs) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * 抢 O_EXCL 锁。原子创建锁文件,内容为 `JSON({pid, ts})`。
+ * 冲突时若现存锁为僵尸(pid 已死 / 锁龄超时 / 损坏)则接管,否则放弃。
+ *
+ * @param {string} lockPath 锁文件路径
+ * @param {{ staleMs?: number }} [opts] 选项,`staleMs` 默认 30 分钟
+ * @returns {(() => void)|null} 成功返回 release()(unlink,幂等);失败返回 null
+ */
+export function acquireLock(lockPath, opts = {}) {
+  const staleMs = opts.staleMs ?? 30 * 60 * 1000;
+
+  const take = () => {
+    try {
+      const fd = fs.openSync(lockPath, 'wx');
+      try {
+        fs.writeSync(fd, JSON.stringify({ pid: process.pid, ts: Date.now() }));
+      } finally {
+        fs.closeSync(fd);
+      }
+      let released = false;
+      return () => {
+        if (released) return;
+        released = true;
+        try { fs.unlinkSync(lockPath); } catch {}
+      };
+    } catch {
+      return null;
+    }
+  };
+
+  const rel = take();
+  if (rel) return rel;
+
+  if (isStale(lockPath, staleMs)) {
+    try { fs.unlinkSync(lockPath); } catch {}
+    return take();
+  }
+
+  return null;
+}

package/src/shared/settle.mjs

@@ -0,0 +1,20 @@
+import fs from 'node:fs';
+
+/** 两次 stat 比较 size;稳定才认为文件写完。避免 async flush 滞后的残缺快照。 */
+export async function isSettled(filePath, opts = {}) {
+  const settleMs = opts.settleMs ?? 500;
+  const maxAttempts = opts.maxAttempts ?? 3;
+  // maxAttempts <= 1:单次 stat,无法比较;存在即视为稳定。
+  if (maxAttempts <= 1) {
+    try { fs.statSync(filePath); return true; } catch { return false; }
+  }
+  let prev = -1;
+  for (let i = 0; i < maxAttempts; i++) {
+    let size;
+    try { size = fs.statSync(filePath).size; } catch { return false; }
+    if (i > 0 && size === prev) return true;
+    prev = size;
+    if (i < maxAttempts - 1) await new Promise(r => setTimeout(r, settleMs));
+  }
+  return false;
+}

package/src/shared/zip.mjs

@@ -0,0 +1,89 @@
+/** 零依赖 zip(单文件,DEFLATE,无数据描述符)。 */
+import { deflateRawSync } from 'node:zlib';
+
+// CRC32 查表法
+const CRC_TABLE = (() => {
+  const t = new Uint32Array(256);
+  for (let i = 0; i < 256; i++) {
+    let c = i;
+    for (let j = 0; j < 8; j++) c = (c & 1) ? (0xEDB88320 ^ (c >>> 1)) : (c >>> 1);
+    t[i] = c;
+  }
+  return t;
+})();
+
+export function crc32(buf) {
+  let crc = 0xFFFFFFFF;
+  for (let i = 0; i < buf.length; i++) {
+    crc = CRC_TABLE[(crc ^ buf[i]) & 0xFF] ^ (crc >>> 8);
+  }
+  return (crc ^ 0xFFFFFFFF) >>> 0;
+}
+
+export function createZip(files) {
+  // files: [{ name: string, data: Buffer | string }]
+  const localParts = [];
+  const centralParts = [];
+  let offset = 0;
+
+  for (const file of files) {
+    const data = Buffer.isBuffer(file.data) ? file.data : Buffer.from(file.data);
+    const compressed = deflateRawSync(data);
+    const crc = crc32(data);
+    const nameBuf = Buffer.from(file.name);
+
+    // Local file header (30 bytes)
+    const lh = Buffer.alloc(30);
+    lh.writeUInt32LE(0x04034b50, 0);
+    lh.writeUInt16LE(20, 4);           // version needed
+    lh.writeUInt16LE(0, 6);            // flags
+    lh.writeUInt16LE(8, 8);            // compression: deflate
+    lh.writeUInt16LE(0, 10);           // mod time
+    lh.writeUInt16LE(0x0021, 12);      // mod date (1980-01-01 safe)
+    lh.writeUInt32LE(crc, 14);
+    lh.writeUInt32LE(compressed.length, 18);
+    lh.writeUInt32LE(data.length, 22);
+    lh.writeUInt16LE(nameBuf.length, 26);
+    lh.writeUInt16LE(0, 28);           // extra length
+
+    const localPart = Buffer.concat([lh, nameBuf, compressed]);
+    localParts.push(localPart);
+
+    // Central directory header (46 bytes)
+    const ch = Buffer.alloc(46);
+    ch.writeUInt32LE(0x02014b50, 0);
+    ch.writeUInt16LE(20, 4);
+    ch.writeUInt16LE(20, 6);
+    ch.writeUInt16LE(0, 8);
+    ch.writeUInt16LE(8, 10);
+    ch.writeUInt16LE(0, 12);
+    ch.writeUInt16LE(0x0021, 14);
+    ch.writeUInt32LE(crc, 16);
+    ch.writeUInt32LE(compressed.length, 20);
+    ch.writeUInt32LE(data.length, 24);
+    ch.writeUInt16LE(nameBuf.length, 28);
+    ch.writeUInt16LE(0, 30);           // extra
+    ch.writeUInt16LE(0, 32);           // comment
+    ch.writeUInt16LE(0, 34);           // disk
+    ch.writeUInt16LE(0, 36);           // internal attrs
+    ch.writeUInt32LE(0, 38);           // external attrs
+    ch.writeUInt32LE(offset, 42);      // local header offset
+    centralParts.push(Buffer.concat([ch, nameBuf]));
+
+    offset += localPart.length;
+  }
+
+  // End of central directory (22 bytes)
+  const centralBuf = Buffer.concat(centralParts);
+  const eocd = Buffer.alloc(22);
+  eocd.writeUInt32LE(0x06054b50, 0);
+  eocd.writeUInt16LE(0, 4);
+  eocd.writeUInt16LE(0, 6);
+  eocd.writeUInt16LE(files.length, 8);
+  eocd.writeUInt16LE(files.length, 10);
+  eocd.writeUInt32LE(centralBuf.length, 12);
+  eocd.writeUInt32LE(offset, 16);
+  eocd.writeUInt16LE(0, 20);
+
+  return Buffer.concat([...localParts, centralBuf, eocd]);
+}

package/src/status.mjs

@@ -1,66 +1,133 @@
 #!/usr/bin/env node
 /**
  * status.mjs — `toolkit status`
+ *
+ * 报告 backlog 模型下的安装状态:
+ *   - registry / uid(来自 config.json)
+ *   - installed_at / last_sweep(来自 backlog.json)
+ *   - 每 project 剩余 backlog 文件数(mtime ≤ installed_at 且
+ *     compareKey(file, cursor) < 0 = 待排干)
+ *
+ * `collectStatus()` 返回字符串,`status()` 为 CLI 入口,调用 console.log。
  */
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
-import { load as loadConfig, UPLOADED_PATH } from './shared/config.mjs';
+import { fileURLToPath } from 'node:url';
+import { load as loadConfig } from './shared/config.mjs';
+import {
+  loadBacklog,
+  compareKey,
+  topCursor,
+} from './shared/backlog.mjs';
 
 const HOME = os.homedir();
-const PLUGIN_DIR = path.join(HOME, '.claude', 'plugins', 'toolkit');
+const PLUGIN_DIR = path.join(HOME, '.claude', 'skills', 'toolkit');
 
-export function status() {
-  const pluginExists = fs.existsSync(path.join(PLUGIN_DIR, '.claude-plugin', 'plugin.json'));
+/**
+ * 收集状态文本。
+ * @returns {string}
+ */
+export function collectStatus() {
   const config = loadConfig();
   const configExists = !!config.registry || !!config.uid;
 
-  console.log('Toolkit Status');
-  console.log('════════════════════════════════════════');
+  const pluginExists = fs.existsSync(
+    path.join(PLUGIN_DIR, '.claude-plugin', 'plugin.json'),
+  );
+
+  const lines = [];
+  lines.push('Toolkit Status');
+  lines.push('════════════════════════════════════════');
 
   if (!pluginExists && !configExists) {
-    console.log('  ❌ 未安装。运行: toolkit install claudecode --registry <url>');
-    return;
+    lines.push('  ❌ 未安装。运行: toolkit install claudecode --registry <url>');
+    return lines.join('\n');
   }
 
   // 插件状态
-  console.log(`  插件:        ${pluginExists ? '✅ 已安装' : '❌ 缺失'}`);
+  lines.push(`  插件:        ${pluginExists ? '✅ 已安装' : '❌ 缺失'}`);
   if (pluginExists) {
-    const pj = JSON.parse(fs.readFileSync(path.join(PLUGIN_DIR, '.claude-plugin', 'plugin.json'), 'utf-8'));
-    console.log(`  版本:        ${pj.version}`);
+    try {
+      const pj = JSON.parse(
+        fs.readFileSync(
+          path.join(PLUGIN_DIR, '.claude-plugin', 'plugin.json'),
+          'utf-8',
+        ),
+      );
+      lines.push(`  版本:        ${pj.version || '(未知)'}`);
+    } catch {
+      lines.push('  版本:        (读取失败)');
+    }
   }
 
-  // 配置(走 shared/config.mjs)
+  // 配置
   if (configExists) {
-    console.log(`  平台地址:    ${config.registry}${config.contexts?.metrics || '/ai-metrics'}/`);
-    console.log(`  身份 UID:    ${config.uid?.slice(0, 12)}...`);
+    lines.push(
+      `  平台地址:    ${config.registry}${config.contexts?.metrics || '/ai-metrics'}/`,
+    );
+    lines.push(`  身份 UID:    ${(config.uid || '').slice(0, 12)}...`);
   }
 
-  // 上传状态
-  try {
-    const up = JSON.parse(fs.readFileSync(UPLOADED_PATH, 'utf-8'));
-    console.log(`  已同步:      ${up.uploaded_sids?.length || 0} 个会话`);
-    console.log(`  上次同步:    ${up.last_flush || '从未'}`);
-  } catch {
-    console.log('  同步状态:    未初始化');
-  }
+  // backlog 状态(只读:status 不应有写副作用,installed_at 边界由 install 写入)
+  const st = loadBacklog();
+  lines.push(`  installed_at: ${st.installed_at || '(无)'}`);
+  lines.push(`  last_sweep:   ${st.last_sweep || '(从未)'}`);
 
-  // 待传会话计数
-  const projectsDir = path.join(HOME, '.claude', 'projects');
-  let pending = 0;
-  if (fs.existsSync(projectsDir) && configExists) {
-    const up = JSON.parse(fs.readFileSync(UPLOADED_PATH, 'utf-8'));
-    const uploadedSet = new Set(up.uploaded_sids || []);
-    for (const projDir of fs.readdirSync(projectsDir)) {
-      const pp = path.join(projectsDir, projDir);
+  // 每 project 剩余 backlog 文件计数
+  const base =
+    process.env.CLAUDE_PROJECTS_DIR ||
+    path.join(HOME, '.claude', 'projects');
+  const installedMs = st.installed_at
+    ? new Date(st.installed_at).getTime()
+    : null;
+
+  if (installedMs != null && fs.existsSync(base)) {
+    lines.push('  backlog 剩余 (按 project):');
+    let total = 0;
+    for (const proj of fs.readdirSync(base)) {
+      const pp = path.join(base, proj);
+      let stat;
       try {
-        if (!fs.statSync(pp).isDirectory()) continue;
-        for (const f of fs.readdirSync(pp)) {
-          if (f.endsWith('.jsonl') && !uploadedSet.has(f.slice(0, -6))) pending++;
+        stat = fs.statSync(pp);
+      } catch {
+        continue;
+      }
+      if (!stat.isDirectory()) continue;
+
+      const cursor = st.cursors[proj] || topCursor(installedMs);
+      let remain = 0;
+      for (const f of fs.readdirSync(pp)) {
+        if (!f.endsWith('.jsonl')) continue;
+        let s;
+        try {
+          s = fs.statSync(path.join(pp, f));
+        } catch {
+          continue;
         }
-      } catch {}
+        if (s.mtimeMs > installedMs) continue; // current 负责
+        if (compareKey({ mtime: s.mtimeMs, name: f }, cursor) < 0) remain++;
+      }
+      total += remain;
+      lines.push(`    ${proj}: ${remain}`);
     }
+    lines.push(`  合计待排干:  ${total}`);
   }
-  console.log(`  待同步:      ${pending} 个会话`);
-  console.log('════════════════════════════════════════');
+
+  lines.push('════════════════════════════════════════');
+  return lines.join('\n');
+}
+
+/**
+ * CLI 入口。
+ */
+export function status() {
+  console.log(collectStatus());
+}
+
+// self-invocation guard:被 import 时不触发 main()
+const invoked =
+  process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
+if (invoked) {
+  status();
 }