@lyra-ai/toolkit 0.2.5 → 0.2.7

package/QUICKSTART.md

@@ -134,9 +134,6 @@ skillhub list --json
 # 诊断问题
 skillhub doctor
 
-# 更新技能包
-skillhub update --scope user
-
 # 移除
 skillhub remove code-review --scope user
 ```
@@ -150,7 +147,7 @@ skillhub publish ./my-skill
 ## skillhub 工作流
 
 ```
-login（认证） → search（发现） → install（安装） → list/doctor（管理） → update（更新）
+login（认证） → search（发现） → install（安装） → list/doctor（管理）
 ```
 
 - **`login`** 存储 registry token

package/README.md

@@ -13,7 +13,7 @@
 安装后，你的 AI 编码数据自动进入组织分析平台，生成专属的多维度效能看板。
 
 ```bash
-toolkit install --agent claudecode --registry http://your-platform:38000
+toolkit install --registry http://your-platform:38000
 ```
 
 - 会话结束后自动同步，无需手动操作
@@ -117,7 +117,6 @@ AI 技能包管理器：搜索、安装、发布、管理 AI coding agent 技能
 - `skillhub remove <slug> [--scope user|project] [--agent <profile>] [--json]` → 移除技能包
 - `skillhub doctor [--fix] [--json]` → 诊断技能包安装状态
 - `skillhub publish <path> [--json]` → 发布技能包到 registry
-- `skillhub update [--scope user|project] [--agent <profile>] [--json]` → 更新已安装技能包
 
 ### Agent profiles（`--agent`）
 

package/bin/toolkit.mjs

@@ -3,7 +3,7 @@
  * toolkit — 研发工具集 CLI 入口
  *
  * 用法:
- *   toolkit install claudecode --registry <url>   安装插件
+ *   toolkit install --registry <url>   安装插件(自动检测 AI Coding Agent)
  *   toolkit status                                 查看状态
  *   toolkit flush                                  手动上传
  *   toolkit uninstall [--purge]                    卸载
@@ -23,8 +23,8 @@ const cmd = args[0];
 const HELP = `toolkit — 研发工具集
 
 命令:
-  install --agent <name> --registry <url>  安装插件(适配指定 AI Coding Agent)
-    --agent claudecode                      Claude Code(SessionEnd hook 插件)
+  install --registry <url>                安装插件(自动检测本机 AI Coding Agent)
+                                            当前支持: Claude Code (~/.claude)
   status                                    查看安装状态 + 待同步会话
   flush                                     手动触发一次同步
   config                                    配置管理
@@ -44,29 +44,18 @@ async function main() {
     return;
   }
 
-  // toolkit install --agent <name> --registry <url>
+  // toolkit install --registry <url>(自动检测 AI Coding Agent)
   if (cmd === 'install') {
-    const agentIdx = args.indexOf('--agent');
-    const agent = agentIdx >= 0 ? args[agentIdx + 1] : null;
-    if (!agent) {
-      console.error('ERROR: 缺少 --agent <name>');
-      console.error('  用法: toolkit install --agent claudecode --registry <url>');
-      console.error('  支持: claudecode');
-      process.exit(2);
-    }
-    if (agent !== 'claudecode') {
-      console.error(`ERROR: 暂不支持 agent "${agent}"。目前支持: claudecode`);
-      process.exit(2);
-    }
     const regIdx = args.indexOf('--registry');
     let registry = regIdx >= 0 ? args[regIdx + 1] : null;
     if (!registry) {
       console.error('ERROR: 缺少 --registry <url>');
-      console.error('  用法: toolkit install --agent claudecode --registry <url>');
+      console.error('  用法: toolkit install --registry <url>');
+      console.error('  (自动检测本机 AI Coding Agent,当前支持: Claude Code)');
       process.exit(2);
     }
     const { install } = await import(pathToFileURL(path.join(srcDir, 'install.mjs')).href);
-    install(registry, { agent });
+    await install(registry);
     return;
   }
 
@@ -77,11 +66,11 @@ async function main() {
     return;
   }
 
-  // toolkit flush
+  // toolkit flush  →  跑 sweep 模式(排干 backlog)
   if (cmd === 'flush') {
     const flushScript = path.join(srcDir, 'flush.mjs');
-    // 同步运行 flush(显示输出)
-    const child = spawn(process.execPath, [flushScript], {
+    // 同步运行 flush(显示输出);必须传 'sweep' mode,否则新 flush.mjs 报 unknown mode
+    const child = spawn(process.execPath, [flushScript, 'sweep'], {
       stdio: 'inherit',
       env: { ...process.env, TOOLKIT_VERBOSE: '1' },
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lyra-ai/toolkit",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "面向 AI agent 的零依赖开发工具集",
   "type": "module",
   "bin": {

package/src/config-cmd.mjs

@@ -27,7 +27,7 @@ export function configCmd(args) {
   if (!sub || sub === 'list' || sub === 'help' || sub === '--help') {
     const config = load();
     if (!config.registry && !config.uid) {
-      console.error('配置文件不存在。先运行: toolkit install claudecode --registry <url>');
+      console.error('配置文件不存在。先运行: toolkit install --registry <url>');
       process.exit(1);
     }
     const pf = config['project-filter'];

package/src/flush.mjs

@@ -1,19 +1,41 @@
 #!/usr/bin/env node
 /**
- * flush.mjs — 扫描 Claude Code 会话 JSONL → 零依赖 zip → POST 平台。
- * 被 hook.mjs(SessionEnd)detached spawn 调用,或 `toolkit flush` 手动调用。
- * 自包含:零依赖,只用 Node 内置模块。
+ * flush.mjs — current / sweep 双模式上报入口。
+ *
+ *   flush current <sid> <filePath>  上传单文件(无锁,无状态写)
+ *   flush sweep                      扫描 backlog(逆游标排干)
+ *
+ * current 语义: settle-check → 读 → 单文件 zip → POST → 退出。
+ *   成功/失败都不写本地状态。若 last_sweep 距今超过 sweep_interval_sec,
+ *   piggyback 一次 runSweep。
+ *
+ * sweep 语义: 抢 flush.lock;对每个命中 project-filter 的项目,按 compareKey
+ *   降序排干 mtime ≤ installed_at 的 .jsonl 文件(待处理 = compareKey < cursor),
+ *   分块 settle→zip→POST;每块后推进游标到块内最老文件 key 并原子写 backlog.json。
+ *   POST 失败仍推进游标(漏报可接受,避免卡死)。返回 {chunks, files}。
  */
 import fs from 'node:fs';
-import path from 'node:path';
 import os from 'node:os';
-import { deflateRawSync } from 'node:zlib';
-import { randomUUID } from 'node:crypto';
+import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { load as loadConfig, UPLOADED_PATH, LOG_DIR } from './shared/config.mjs';
+import { load as loadConfig, getUploadConfig, LOG_DIR } from './shared/config.mjs';
+import {
+  ensureBacklog,
+  loadBacklog,
+  saveBacklog,
+  compareKey,
+  topCursor,
+  BACKLOG_PATH,
+} from './shared/backlog.mjs';
+import { acquireLock } from './shared/lock.mjs';
+import { createZip } from './shared/zip.mjs';
+import { postZip } from './shared/http.mjs';
+import { isSettled } from './shared/settle.mjs';
 
 const HOME = os.homedir();
-const CLAUDE_PROJECTS = path.join(HOME, '.claude', 'projects');
+const CLAUDE_PROJECTS =
+  process.env.CLAUDE_PROJECTS_DIR || path.join(HOME, '.claude', 'projects');
+const LOCK_PATH = path.join(path.dirname(BACKLOG_PATH), 'flush.lock');
 
 // ── 日志 ──────────────────────────────────────────────
 function log(...args) {
@@ -26,248 +48,248 @@ function log(...args) {
   if (process.env.TOOLKIT_VERBOSE) process.stderr.write(line);
 }
 
-// ── 读配置(走 shared/config.mjs)─────────────────────
-// loadConfig 从 shared/config.mjs 导入
-
-function loadUploaded() {
-  try {
-    return JSON.parse(fs.readFileSync(UPLOADED_PATH, 'utf-8'));
-  } catch {
-    return { uploaded_sids: [], last_flush: null };
-  }
+function uploadUrl(config) {
+  const base = `${config.registry.replace(/\/$/, '')}${config.contexts?.metrics || '/ai-metrics'}`;
+  return `${base}/api/upload`;
 }
 
-function saveUploaded(state) {
-  state.last_flush = new Date().toISOString();
-  // 只保留最近 500 个 sid(防膨胀)
-  if (state.uploaded_sids.length > 500) {
-    state.uploaded_sids = state.uploaded_sids.slice(-500);
-  }
-  try {
-    fs.writeFileSync(UPLOADED_PATH, JSON.stringify(state, null, 2));
-  } catch (e) {
-    log('WARN: cannot save uploaded.json:', e.message);
-  }
-}
+/**
+ * current:上传单个文件(无锁,无状态写)。
+ * @param {string} sid       会话 id(用于日志)
+ * @param {string} filePath  JSONL 文件绝对路径
+ * @param {{config:object, uploadConfig:object, logFn?:Function}} ctx
+ * @returns {Promise<{uploaded:boolean}>}
+ */
+export async function runCurrent(sid, filePath, ctx) {
+  const config = ctx.config;
+  const u = ctx.uploadConfig;
+  const logFn = ctx.logFn || log;
 
-// ── 扫描新会话 ────────────────────────────────────────
-function scanNewSessions(uploadedSet, includeKeywords) {
-  const found = [];
-  if (!fs.existsSync(CLAUDE_PROJECTS)) return found;
-  for (const projDir of fs.readdirSync(CLAUDE_PROJECTS)) {
-    // project-filter:配了关键词时,项目目录名必须命中至少一个(子串,大小写不敏感)
-    if (includeKeywords && includeKeywords.length > 0) {
-      const lower = projDir.toLowerCase();
-      if (!includeKeywords.some(kw => lower.includes(kw.toLowerCase()))) continue;
-    }
-    const projPath = path.join(CLAUDE_PROJECTS, projDir);
-    let st;
-    try { st = fs.statSync(projPath); } catch { continue; }
-    if (!st.isDirectory()) continue;
-    for (const file of fs.readdirSync(projPath)) {
-      if (!file.endsWith('.jsonl')) continue;
-      const sid = file.slice(0, -6); // 去掉 .jsonl
-      if (uploadedSet.has(sid)) continue;
-      const fp = path.join(projPath, file);
-      // 跳过空文件(<100 字节,可能是刚创建的)
-      try { if (fs.statSync(fp).size < 100) continue; } catch { continue; }
-      found.push({ sid, path: fp, project: projDir, name: file });
-    }
+  // project-filter 对 current 同样生效:刚结束的会话若不在过滤范围内,跳过。
+  // (与 sweep 一致 —— filter 控制「哪些 project 上报」,两条路都不能绕过。)
+  const project = path.basename(path.dirname(filePath));
+  const keywords = config['project-filter'] || [];
+  if (
+    keywords.length &&
+    !keywords.some((kw) => project.toLowerCase().includes(kw.toLowerCase()))
+  ) {
+    logFn(`skip project-filter: ${project}`);
+    return { uploaded: false };
   }
-  return found;
-}
 
-// ── 零依赖 zip ────────────────────────────────────────
-// 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;
+  const settled = await isSettled(filePath, {
+    settleMs: u.settle_ms,
+    maxAttempts: u.settle_max_attempts,
+  });
+  if (!settled) {
+    logFn(`skip not-settled: ${sid}`);
+    return { uploaded: false };
   }
-  return t;
-})();
 
-function crc32(buf) {
-  let crc = 0xFFFFFFFF;
-  for (let i = 0; i < buf.length; i++) {
-    crc = CRC_TABLE[(crc ^ buf[i]) & 0xFF] ^ (crc >>> 8);
+  let data;
+  try {
+    data = fs.readFileSync(filePath);
+  } catch (e) {
+    logFn(`skip read-fail: ${sid} ${e.message}`);
+    return { uploaded: false };
   }
-  return (crc ^ 0xFFFFFFFF) >>> 0;
-}
 
-function createZip(files) {
-  // files: [{ name: string, data: Buffer }]
-  const localParts = [];
-  const centralParts = [];
-  let offset = 0;
+  // zip 内 name = <projectDir>/<file>(project 已在上方 filter 处求得)
+  const name = path.basename(filePath);
+  const zip = createZip([{ name: `${project}/${name}`, data }]);
 
-  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);
+  const r = await postZip(uploadUrl(config), zip, config.uid, {
+    timeoutSec: u.http_timeout_sec,
+  });
+  logFn(r.ok ? `current OK: ${sid}` : `current FAIL: ${sid} ${r.error || r.status}`);
+  return { uploaded: !!r.ok };
+}
 
-    // 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]));
+/**
+ * sweep:持锁,逆时间戳游标排干 mtime ≤ installed_at 的 backlog。
+ *
+ * 对每个 project(命中 project-filter):
+ *   - 列出 .jsonl 文件,mtime ≤ installed_at 且 compareKey(file, cursor) < 0
+ *   - 按 compareKey 降序(最新待处理优先)分块:≤ chunk_max_files 且
+ *     累计原始字节 ≤ chunk_max_bytes
+ *   - 每块 settle → 读 → zip → POST;成功则计数。
+ *   - 无论 POST 成败,推进游标到本块最老文件 key(漏报可接受,避免卡死),
+ *     原子写 backlog.json → pacing。
+ *
+ * @param {{config:object, uploadConfig:object, logFn?:Function}} ctx
+ * @returns {Promise<{chunks:number, files:number}>}
+ */
+export async function runSweep(ctx) {
+  const config = ctx.config;
+  const u = ctx.uploadConfig;
+  const logFn = ctx.logFn || log;
 
-    offset += localPart.length;
+  const release = acquireLock(LOCK_PATH);
+  if (!release) {
+    logFn('sweep: lock busy, exit');
+    return { chunks: 0, files: 0 };
   }
+  try {
+    const st = ensureBacklog();
+    const installedMs = new Date(st.installed_at).getTime();
+    const url = uploadUrl(config);
+    const keywords = config['project-filter'] || [];
+    let chunks = 0;
+    let files = 0;
 
-  // 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);       // central dir offset
-  eocd.writeUInt16LE(0, 20);
-
-  return Buffer.concat([...localParts, centralBuf, eocd]);
-}
+    if (!fs.existsSync(CLAUDE_PROJECTS)) {
+      st.last_sweep = new Date().toISOString();
+      saveBacklog(st, logFn);
+      return { chunks, files };
+    }
 
-// ── HTTP POST(带重试)────────────────────────────────
-async function postZip(url, zipBuf, uid) {
-  const delays = [2000, 4000, 8000]; // 重试间隔
-  for (let attempt = 0; attempt <= delays.length; attempt++) {
-    try {
-      const controller = new AbortController();
-      const timeout = setTimeout(() => controller.abort(), 30000);
-      const res = await fetch(url, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/zip', 'X-Uid': uid },
-        body: zipBuf,
-        signal: controller.signal,
-      });
-      clearTimeout(timeout);
-      if (res.ok) {
-        const j = await res.json().catch(() => ({}));
-        return j;
+    for (const projDir of fs.readdirSync(CLAUDE_PROJECTS)) {
+      if (
+        keywords.length &&
+        !keywords.some((kw) => projDir.toLowerCase().includes(kw.toLowerCase()))
+      ) {
+        continue;
       }
-      if (res.status >= 400 && res.status < 500 && res.status !== 429) {
-        throw new Error(`HTTP ${res.status}: ${await res.text().catch(() => '')}`);
+      const projPath = path.join(CLAUDE_PROJECTS, projDir);
+      let projStat;
+      try {
+        projStat = fs.statSync(projPath);
+      } catch {
+        continue;
+      }
+      if (!projStat.isDirectory()) continue;
+
+      const cursor = st.cursors[projDir] || topCursor(installedMs);
+
+      // 列出 backlog 文件(mtime ≤ installed)且尚未排干
+      const pending = [];
+      for (const file of fs.readdirSync(projPath)) {
+        if (!file.endsWith('.jsonl')) continue;
+        const fp = path.join(projPath, file);
+        let s;
+        try {
+          s = fs.statSync(fp);
+        } catch {
+          continue;
+        }
+        if (s.size < 1) continue;
+        if (s.mtimeMs > installedMs) continue; // current 负责
+        const key = { mtime: s.mtimeMs, name: file };
+        if (compareKey(key, cursor) >= 0) continue; // 已排干
+        pending.push({ fp, key, size: s.size });
       }
-      throw new Error(`HTTP ${res.status}`);
-    } catch (e) {
-      if (attempt < delays.length) {
-        const jitter = (Math.random() - 0.5) * delays[attempt] * 0.5;
-        const wait = Math.max(1000, delays[attempt] + jitter);
-        log(`attempt ${attempt + 1} failed: ${e.message}, retry in ${Math.round(wait)}ms`);
-        await new Promise(r => setTimeout(r, wait));
-      } else {
-        throw e;
+      pending.sort((a, b) => compareKey(b.key, a.key)); // 降序:最新待处理优先
+
+      // 分块
+      let i = 0;
+      while (i < pending.length) {
+        const chunk = [];
+        let bytes = 0;
+        while (
+          i < pending.length &&
+          chunk.length < u.chunk_max_files &&
+          (chunk.length === 0 || bytes + pending[i].size <= u.chunk_max_bytes)
+        ) {
+          chunk.push(pending[i]);
+          bytes += pending[i].size;
+          i++;
+        }
+        // settle + 读 + zip + POST
+        const zipFiles = [];
+        for (const c of chunk) {
+          if (
+            !(await isSettled(c.fp, {
+              settleMs: u.settle_ms,
+              maxAttempts: u.settle_max_attempts,
+            }))
+          ) {
+            logFn(`skip not-settled: ${c.key.name}`);
+            continue;
+          }
+          try {
+            zipFiles.push({
+              name: `${projDir}/${c.key.name}`,
+              data: fs.readFileSync(c.fp),
+            });
+          } catch (e) {
+            logFn(`skip read-fail: ${c.key.name} ${e.message}`);
+          }
+        }
+        if (zipFiles.length === 0) {
+          // 整块 settle/read 全失败 → 不推进游标,留待下次 sweep 重试(spec §7 settle-skip)
+          logFn(`sweep chunk produced no uploadable files, will retry next sweep: ${projDir}`);
+          break;
+        }
+        const zip = createZip(zipFiles);
+        const r = await postZip(url, zip, config.uid, {
+          timeoutSec: u.http_timeout_sec,
+        });
+        if (r.ok) {
+          chunks++;
+          files += zipFiles.length;
+          logFn(`sweep chunk OK: ${projDir} +${zipFiles.length}`);
+        } else {
+          logFn(`sweep chunk FAIL: ${projDir} ${r.error || r.status}`);
+        }
+        // 无论 POST 成败:推进游标到本块最老文件(spec D3:漏报可接受,避免卡死)
+        st.cursors[projDir] = chunk[chunk.length - 1].key;
+        saveBacklog(st, logFn);
+        if (u.pacing_ms > 0) {
+          await new Promise((r) => setTimeout(r, u.pacing_ms));
+        }
       }
     }
+
+    st.last_sweep = new Date().toISOString();
+    saveBacklog(st, logFn);
+    logFn(`sweep done: ${files} files, ${chunks} chunks`);
+    return { chunks, files };
+  } finally {
+    release();
   }
 }
 
 // ── 主流程 ────────────────────────────────────────────
 async function main() {
+  const mode = process.argv[2];
   const config = loadConfig();
-  const { registry, uid } = config;
-  const metricsBase = `${registry.replace(/\/$/, '')}${config.contexts?.metrics || '/ai-metrics'}`;
-  const uploadUrl = `${metricsBase}/api/upload`;
+  const uploadConfig = getUploadConfig();
+  const ctx = { config, uploadConfig, logFn: log };
 
-  log(`flush start: registry=${registry} uid=${uid.slice(0, 8)}...`);
-
-  const uploaded = loadUploaded();
-  const uploadedSet = new Set(uploaded.uploaded_sids);
-  const includeKeywords = config['project-filter'] || [];
-  const newSessions = scanNewSessions(uploadedSet, includeKeywords);
-
-  if (newSessions.length === 0) {
-    log('no new sessions to upload');
-    saveUploaded(uploaded);
-    return;
-  }
-
-  log(`found ${newSessions.length} new session(s)`);
-
-  // 按项目分组,每组一次上传(平台按项目分)
-  const byProject = new Map();
-  for (const s of newSessions) {
-    if (!byProject.has(s.project)) byProject.set(s.project, []);
-    byProject.get(s.project).push(s);
-  }
-
-  let totalUploaded = 0;
-  for (const [project, sessions] of byProject) {
-    log(`uploading project=${project}: ${sessions.length} session(s)`);
-
-    // 读文件 + 创建 zip
-    const zipFiles = [];
-    for (const s of sessions) {
-      try {
-        const data = fs.readFileSync(s.path);
-        zipFiles.push({ name: `${project}/${s.name}`, data });
-      } catch (e) {
-        log(`WARN: cannot read ${s.path}: ${e.message}`);
-      }
+  if (mode === 'current') {
+    const sid = process.argv[3];
+    const filePath = process.argv[4];
+    if (!sid || !filePath) {
+      log('current: missing args');
+      process.exit(0);
     }
-    if (zipFiles.length === 0) continue;
-
-    const zipBuf = createZip(zipFiles);
-    log(`zip created: ${zipFiles.length} files, ${Math.round(zipBuf.length / 1024)}KB`);
+    await runCurrent(sid, filePath, ctx);
 
-    // 上传
-    try {
-      const result = await postZip(uploadUrl, zipBuf, uid);
-      log(`upload OK: dataset=${result.dataset_id}, sessions=${result.files || '?'}`);
-      for (const s of sessions) {
-        uploadedSet.add(s.sid);
-        uploaded.uploaded_sids = [...uploadedSet];
-      }
-      totalUploaded += sessions.length;
-    } catch (e) {
-      log(`upload FAILED for ${project}: ${e.message}`);
-      // 不更新 uploaded — 下次重试
+    // piggyback:节流到期则转 sweep
+    ensureBacklog();
+    const st = loadBacklog();
+    const since = st.last_sweep
+      ? Date.now() - new Date(st.last_sweep).getTime()
+      : Infinity;
+    if (since > uploadConfig.sweep_interval_sec * 1000) {
+      await runSweep(ctx);
     }
+    process.exit(0);
+  } else if (mode === 'sweep') {
+    await runSweep(ctx);
+    process.exit(0);
+  } else {
+    log(`unknown mode: ${mode}`);
+    process.exit(0);
   }
-
-  saveUploaded(uploaded);
-  log(`flush done: ${totalUploaded}/${newSessions.length} uploaded`);
 }
 
-main().catch(e => {
-  log(`FATAL: ${e.message}`);
-  process.exit(1);
-});
+// self-invocation guard:被 import 时不触发 main()
+const invoked =
+  process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
+if (invoked) {
+  main().catch(e => {
+    log(`FATAL: ${e.message}`);
+    process.exit(1);
+  });
+}