tokenforbes-cli 0.1.5 → 0.1.6

package/bin.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-// TokenBoard 上报命令行。只上报数字和设备型号,不读、不传你的任何项目内容。
-// 命令:register <昵称> | login <密钥> | report(默认)
+// CEO Rank(tokenforbes)上报命令行。只上报用量数字和设备型号,不读、不传你的任何项目内容。
+// 命令:link | register <昵称> | login <密钥> | report(默认) | daemon <install|status|uninstall>
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -11,29 +11,88 @@ import { daemon, ensureDaemonInstalled } from './daemon.js';
 
 const CONFIG = path.join(os.homedir(), '.tokenboard.json');
 const DEFAULT_SERVER = process.env.TB_SERVER || 'https://ceorank.cn';
+const CMD_PLAIN = 'npx -y tokenforbes-cli@latest';       // 万能命令:没登录带你登录,登录过直接上报
+const CMD_LINK = CMD_PLAIN + ' link';                     // 中断后接着来,统一推荐这条
 
 const loadConfig = () => { try { return JSON.parse(fs.readFileSync(CONFIG, 'utf8')); } catch { return {}; } };
 const saveConfig = (c) => fs.writeFileSync(CONFIG, JSON.stringify(c, null, 2));
 
+// ---- Ctrl+C 善后 ----
+// 任何阶段按 Ctrl+C:说清进行到哪一步、怎么继续,然后干净退出(130),绝不甩堆栈。
+// stage 跟着流程走:start(刚起步) → usage(统计用量) → approve(等浏览器批准) → upload(上传) → done。
+let stage = 'start';
+const STAGE_BYE = {
+  start: '刚起步，还什么都没动，一切照旧。',
+  usage: '刚才正在统计本地用量，还没统计完；没有上传任何数据，也没改动任何东西。',
+  approve: '刚才正在等你去浏览器点批准，还没上传任何数据。',
+  upload: '刚才正在上传，可能只传了一部分——不要紧，重跑一次会自动补齐，不会重复计数。',
+  done: '该办的都已经办完了，用量传上去了。',
+};
+function bye() {
+  console.log('\n\n好，先停在这儿。' + (STAGE_BYE[stage] || ''));
+  console.log('想继续的时候，随时跑这一条，接着帮你办完：\n');
+  console.log('  ' + CMD_LINK + '\n');
+  process.exit(130);
+}
+process.on('SIGINT', bye);
+
 const [cmd, arg] = process.argv.slice(2);
 
-if (cmd === 'login') {
-  if (!arg) die('用法: tokenforbes login <密钥>');
-  const c = loadConfig(); c.key = arg; c.server = c.server || DEFAULT_SERVER; saveConfig(c);
-  console.log('密钥已保存 →', CONFIG);
-} else if (cmd === 'link') {
-  await link();
-} else if (cmd === 'daemon') {
-  daemon(arg);
-} else if (cmd === 'register') {
-  await register(arg);
-} else if (cmd === 'report') {
-  await report();
-} else if (!cmd) {
-  // 一条命令走完:report 内部会兜底——没密钥或密钥失效(服务器重置过)都自动带去登录再上报。
-  await report();
-} else {
-  console.log('命令: link | register <昵称> | login <密钥> | report | daemon <install|status|uninstall>');
+try {
+  if (cmd === 'login') {
+    login(arg);
+  } else if (cmd === 'link') {
+    await link();
+  } else if (cmd === 'daemon') {
+    daemon(arg);
+  } else if (cmd === 'register') {
+    await register(arg);
+  } else if (cmd === 'report') {
+    await report();
+  } else if (!cmd) {
+    // 一条命令走完:report 内部会兜底——没密钥或密钥失效(服务器重置过)都自动带去登录再上报。
+    await report();
+  } else {
+    help();
+  }
+} catch (e) {
+  // 统计用量时按 Ctrl+C,子进程先被打断,错误会带 interrupted 标记辗转到这里——按告别处理,不算出错。
+  if (e?.interrupted) bye();
+  if (e?.friendly) die(e.message); // 自家抛的错,文案已经写好了「出了什么事 + 下一步」
+  die('✗ 出了点意外：' + (e?.message || e) + '\n  重新跑一次通常就能好：  ' + CMD_PLAIN + '\n  要是反复不行，去 https://ceorank.cn 找我们说一声，我们来修。');
+}
+
+function help() {
+  console.log(`
+CEO Rank 用量上报工具（tokenforbes-cli）
+只上报 token 用量数字和设备型号，绝不读取、不上传你的代码和对话内容。
+
+最省事的用法（一条命令全搞定）：
+
+  ${CMD_PLAIN}
+
+  没登录会自动打开浏览器带你登录；登录过就直接上报。
+
+分步命令（想单独控制时用）：
+  link               浏览器一键登录 + 上报（推荐）
+  report             上报一次本地用量
+  register <昵称>    不走浏览器，直接用昵称注册
+  login <密钥>       已有密钥，保存到本机
+  daemon install     开启后台自动同步（每 30 分钟自动上报）
+  daemon status      看后台同步是否在跑
+  daemon uninstall   关闭后台自动同步
+
+上报成功后，去 https://ceorank.cn 看排名；登录后打开「同步数据」页，能看到每台设备的上报明细。
+`);
+}
+
+function login(key) {
+  if (!key) {
+    die('差一个密钥，没法登录。这样用：\n  ' + CMD_PLAIN + ' login <你的密钥>\n\n  手头没有密钥？直接跑  ' + CMD_PLAIN + '  走浏览器登录，更省事。');
+  }
+  const c = loadConfig(); c.key = key; c.server = c.server || DEFAULT_SERVER; saveConfig(c);
+  console.log('✓ 密钥已保存（' + CONFIG + '），这台电脑之后免登录。');
+  console.log('接下来跑  ' + CMD_PLAIN + '  就能把用量传上去了。');
 }
 
 // 设备授权登录:先弹浏览器让你批准 → 趁这工夫后台抓用量 → 批准一到立刻上传。
@@ -45,29 +104,40 @@ async function link(preDays) {
   const s = await post(server + '/api/device/start', { device });
   const url = `${server}/link.html?code=${s.user_code}`;
   // 第一步就把浏览器弹出去,别让用户对着黑终端干等。
-  console.log('\n① 浏览器这就打开,填个昵称、点「注册并批准」就行。没弹出来就手动复制这条链接:');
+  console.log('\n① 去浏览器批准登录');
+  console.log('   浏览器马上会自己弹出来，填个昵称、点「注册并批准」就行。');
+  console.log('   没弹出来？手动打开这条链接：');
   console.log('   → ' + url);
-  console.log('   验证码: ' + s.user_code + '（跟网页上那串核对一致再批准）');
+  console.log('   验证码：' + s.user_code + '（和网页上显示的对上号，再点批准）');
   openBrowser(url);
 
   // 趁你在浏览器填昵称、点批准的工夫,后台把本地用量先抓好,批准一到就能立刻上传。
   let days = preDays;
   if (!days) {
-    process.stdout.write('\n② 正在后台读取本地用量(ccusage)…');
+    stage = 'usage';
+    console.log('\n② 趁这工夫，统计这台电脑的 AI 用量');
+    console.log('   正在读取 Claude Code / Codex 的 token 用量，第一次跑要先下载统计工具，可能要几十秒…');
     days = readUsage();
-    console.log(days.length ? ` 已抓好 ${days.length} 天,就等你在浏览器批准。` : ' 没读到用量。');
+    if (days.length) {
+      console.log(`   ✓ 统计好了，共 ${days.length} 天的用量，你在浏览器一批准就立刻上传。`);
+    } else {
+      console.log('   这台电脑暂时没读到用量——可能还没用 Claude Code / Codex 干过活，不碍事。');
+      console.log('   先把账号批准了；之后有了用量，重跑一次这条命令就会自动传上来。');
+    }
   } else {
-    console.log('\n② 本地用量已经抓好,就等你在浏览器批准。');
+    console.log('\n② 本地用量刚才已经统计好，你一批准就立刻上传。');
   }
 
-  process.stdout.write('   等你点确认…');
+  stage = 'approve';
+  console.log('\n③ 就差你在浏览器里点批准了');
+  process.stdout.write('   等你确认中，点完这边马上继续（不想等就按 Ctrl+C，随时能回来）');
   const until = Date.now() + s.expires_in * 1000;
   while (Date.now() < until) {
     await sleep(s.interval * 1000);
     const p = await post(server + '/api/device/poll', { device_code: s.device_code });
     if (p.status === 'approved') {
       c.key = p.key; c.server = server; saveConfig(c);
-      console.log('\n✓ 已批准,密钥已存到 ' + CONFIG);
+      console.log('\n   ✓ 批准成功！密钥已存好（' + CONFIG + '），这台电脑之后免登录。');
       await uploadDays(days, { server, key: p.key, device });
       ensureDaemonInstalled();
       return;
@@ -75,7 +145,7 @@ async function link(preDays) {
     if (p.status === 'expired') break;
     process.stdout.write('.');
   }
-  die('\n登录超时或验证码已过期，重新跑一次  npx -y tokenforbes-cli');
+  die('✗ 这次的验证码过期了——等得有点久，安全起见每个码只有几分钟有效。\n  没关系，重跑一遍就有新码，一分钟搞定：\n  ' + CMD_LINK);
 }
 
 function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
@@ -88,14 +158,17 @@ function openBrowser(url) {
 }
 
 async function register(nickname) {
-  if (!nickname) die('用法: tokenforbes register <昵称>');
+  if (!nickname) {
+    die('差一个昵称，没法注册。这样用：\n  ' + CMD_PLAIN + ' register <你的昵称>\n\n  更省事的办法：直接跑  ' + CMD_PLAIN + ' ，在浏览器里填昵称就行。');
+  }
   const c = loadConfig();
   const server = c.server || DEFAULT_SERVER;
   const device = detectDevice();
   const j = await post(server + '/api/register', { nickname, device });
   c.key = j.key; c.server = server; saveConfig(c);
-  console.log(`注册成功,昵称「${j.nickname}」。密钥已存到 ${CONFIG}`);
-  console.log('正在读取本地用量(ccusage)…');
+  console.log(`✓ 注册成功，欢迎入榜，「${j.nickname}」！密钥已存好（${CONFIG}），这台电脑之后免登录。`);
+  stage = 'usage';
+  console.log('接着统计这台电脑的 token 用量，统计完马上传上去，第一次要下载统计工具，可能要几十秒…');
   await uploadDays(readUsage(), { server, key: j.key, device }); // 注册完顺手上报,别让用户再跑一条
   ensureDaemonInstalled();
 }
@@ -104,8 +177,11 @@ async function report({ allowRelink = true } = {}) {
   const c = loadConfig();
   // 没密钥:直接带去登录(link 会先弹浏览器,再后台抓用量),不让用户对着报错发愣。
   if (!c.key) {
-    if (allowRelink) return link();
-    die('还没登录。先跑  npx -y tokenforbes-cli  (浏览器一键登录),或 register / login');
+    if (allowRelink) {
+      console.log('这台电脑还没登录过，先带你走一遍浏览器登录，一分钟搞定。');
+      return link();
+    }
+    die('这台电脑还没登录，没法上报。先跑  ' + CMD_PLAIN + '  用浏览器一键登录（也可以 register <昵称> 或 login <密钥>）。');
   }
   const server = c.server || DEFAULT_SERVER;
   const device = detectDevice();
@@ -114,33 +190,58 @@ async function report({ allowRelink = true } = {}) {
   if (!probe.ok) {
     const authFailed = probe.status === 401 || /密钥/.test(probe.json?.error || '');
     if (authFailed && allowRelink) {
-      console.log('本地密钥已失效,这就打开浏览器带你重新登录…');
+      console.log('本机存的密钥不管用了（可能在网站上重置过密钥）。');
+      console.log('不用慌，你的历史数据都在。这就打开浏览器带你重新登录…');
       delete c.key; saveConfig(c);
       return link(); // 密钥无效,还没抓用量;交给 link 先弹浏览器再后台抓
     }
-    die('上报失败:' + (probe.json?.error || probe.netError || probe.status));
+    die(sendFailText(probe));
   }
   // 密钥有效:抓用量并上传。
-  console.log('正在读取本地用量(ccusage)…');
+  stage = 'usage';
+  console.log('正在统计这台电脑的 token 用量（Claude Code / Codex），可能要几十秒…');
   await uploadDays(readUsage(), { server, key: c.key, device });
   ensureDaemonInstalled();
 }
 
 // 把抓好的用量传上去。抽出来给 report / link / register 共用,避免各写一遍、避免重复抓。
 async function uploadDays(days, { server, key, device }) {
-  if (!days || !days.length) return console.log('没读到用量数据(这台电脑还没用过 Claude Code / Codex?)。');
+  if (!days || !days.length) {
+    console.log('\n这台电脑上没读到 token 用量，这次就先不上传了。');
+    console.log('多半是这两种情况，都不用担心：');
+    console.log('  · 这台电脑还没用 Claude Code / Codex 干过活 —— 用起来之后重跑一次就有了');
+    console.log('  · 你平时在另一台电脑上干活 —— 去那台电脑跑同样这条命令');
+    console.log('账号本身没任何问题。之后随时跑  ' + CMD_PLAIN + '  都能补传。');
+    return;
+  }
+  stage = 'upload';
   const total = days.reduce((s, d) => s + d.input + d.output + (d.cacheCreation || 0) + (d.cacheRead || 0), 0);
-  console.log(`设备:${device}`);
-  console.log(`共 ${days.length} 天,合计约 ${Math.round(total / 1e4).toLocaleString()} 万 token,正在上传…`);
+  console.log(`\n设备：${device}`);
+  console.log(`共 ${days.length} 天、约 ${Math.round(total / 1e4).toLocaleString()} 万 token，正在上传（只传数字，不传内容）…`);
   const res = await postRaw(server + '/api/report', { key, device, days });
-  if (res.ok) console.log(`上报成功 ✓ 已记录 ${res.json.days} 天。去 ${server} 看你的排名。`);
-  else die('上报失败:' + (res.json?.error || res.netError || res.status));
+  if (!res.ok) die(sendFailText(res));
+  stage = 'done';
+  console.log(`✓ 上报成功！服务器已记下 ${res.json.days} 天的用量。\n`);
+  console.log('去看看成果：');
+  console.log(`  · 打开 ${server} ，在排行榜上找你的名次`);
+  console.log('  · 登录后进「同步数据」页，能看到这台设备每天的上报明细');
+}
+
+// 统一的「没传上去」文案:说清原因 + 数据没丢 + 下一步。
+function sendFailText(res) {
+  const why = res.netError || res.json?.error || ('服务器回了个 ' + res.status + '，没说原因');
+  return '✗ 这次没传上去：' + why + '\n' +
+    '  你的用量都存在本机，一条都不会丢。\n' +
+    '  等网络稳定了重跑一次就行：  ' + CMD_PLAIN;
 }
 
 // 会抛错就 die 的版本:给登录/注册这类「失败就该停」的调用用。
 async function post(url, body) {
   const res = await postRaw(url, body);
-  if (!res.ok) die('失败:' + (res.json?.error || res.netError || res.status));
+  if (!res.ok) {
+    die('✗ 没连上服务器，这一步没办成：' + (res.netError || res.json?.error || ('服务器回了个 ' + res.status)) + '\n' +
+      '  你这边什么都没丢。检查下网络，稍后重跑：  ' + CMD_PLAIN);
+  }
   return res.json;
 }
 
@@ -150,10 +251,10 @@ async function postRaw(url, body) {
   try {
     res = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) });
   } catch (e) {
-    return { ok: false, netError: `连不上服务器(${url}):${e.message}` };
+    return { ok: false, netError: `连不上服务器（${e.message}），可能是断网、开了代理，或服务器暂时没响应` };
   }
   const json = await res.json().catch(() => ({}));
   return { ok: res.ok, status: res.status, json };
 }
 
-function die(msg) { console.error(msg); process.exit(1); }
+function die(msg) { console.error('\n' + msg); process.exit(1); }

package/ccusage.js

@@ -4,6 +4,8 @@ import { execSync } from 'node:child_process';
 
 const num = (x) => Math.max(0, Math.round(Number(x) || 0));
 const money = (x) => Math.max(0, Number(x) || 0); // 成本是美元小数,别取整
+// friendly 标记 = 文案已经按「出了什么事 + 下一步」写好,上层直接展示,别再包一层「出了点意外」。
+const friendly = (msg) => { const e = new Error(msg); e.friendly = true; return e; };
 
 export function readUsage() {
   let out;
@@ -11,17 +13,23 @@ export function readUsage() {
     out = execSync('npx ccusage@latest daily --breakdown --json', {
       encoding: 'utf8', timeout: 120000, maxBuffer: 64 * 1024 * 1024,
     });
-  } catch {
-    throw new Error('读取用量失败:ccusage 跑不起来。先确认能联网、能跑 npx。');
+  } catch (e) {
+    // 用户按 Ctrl+C 时,这个子进程会先被打断——这不是故障,标记出来让上层好聚好散。
+    if (e && (e.signal === 'SIGINT' || e.signal === 'SIGTERM' || e.status === 130)) {
+      const stop = new Error('interrupted');
+      stop.interrupted = true;
+      throw stop;
+    }
+    throw friendly('✗ 统计工具（ccusage）没跑起来，这次没读到用量。\n  多半是网络不稳——它第一次要联网下载。检查下网络，重跑一次就行；\n  要是反复失败，单独跑一下  npx ccusage@latest daily  看看它报什么。');
   }
   let data;
   try {
     data = JSON.parse(out);
   } catch {
-    throw new Error('读取用量失败:ccusage 输出看不懂(可能版本变了)。');
+    throw friendly('✗ 统计工具（ccusage）的输出这版看不懂了，可能它刚改版。\n  过几个小时再跑一次试试；一直不行就是我们这边要修，去 https://ceorank.cn 说一声。');
   }
   if (!data || !Array.isArray(data.daily)) {
-    throw new Error('读取用量失败:没找到每日数据(ccusage 输出结构变了)。');
+    throw friendly('✗ 统计工具（ccusage）的输出里没找到每日数据，格式可能变了。\n  过几个小时再跑一次试试；一直不行就是我们这边要修，去 https://ceorank.cn 说一声。');
   }
   return data.daily
     .map((d) => {

package/daemon.js

@@ -44,7 +44,7 @@ function supported() {
 
 function ensureSupported() {
   if (!supported()) {
-    console.error('后台自动同步目前支持 macOS / Windows。其它系统可自己挂定时任务跑  npx -y tokenforbes-cli@latest report');
+    console.error('后台自动同步目前只支持 macOS / Windows，你这个系统暂时开不了。\n不过可以自己挂个定时任务，每半小时跑一次：  npx -y tokenforbes-cli@latest report');
     process.exit(1);
   }
 }
@@ -111,34 +111,36 @@ function installWindows() {
 function install() {
   ensureSupported();
   if (!requireKey()) {
-    console.error('还没登录,先跑  npx tokenforbes-cli  登录后再装。');
+    console.error('这台电脑还没登录，先不开后台同步——开了也只会每半小时报一次「未登录」。\n先跑  npx -y tokenforbes-cli@latest  登录，登录成功会自动帮你开启。');
     process.exit(1);
   }
   if (process.platform === 'darwin') installMac();
   else installWindows();
-  console.log('✓ 已开启后台自动同步,每 30 分钟自动上报一次。');
+  console.log('✓ 后台自动同步已开启：每 30 分钟自动上报一次，之后不用你管。');
   if (process.platform === 'darwin') {
     console.log('  任务文件: ' + PLIST);
     console.log('  日志:     ' + LOG);
   }
-  console.log('  查看状态: tokenforbes daemon status');
-  console.log('  关掉它:   tokenforbes daemon uninstall');
+  console.log('  看状态:  npx -y tokenforbes-cli@latest daemon status');
+  console.log('  想关掉:  npx -y tokenforbes-cli@latest daemon uninstall');
 }
 
 function statusMac() {
   if (!fs.existsSync(PLIST)) return false;
   let loaded = false;
   try { loaded = execFileSync('launchctl', ['list'], { encoding: 'utf8' }).includes(LABEL); } catch {}
-  console.log(loaded ? '✓ 已安装并在运行,每 30 分钟自动上报。' : '已安装但未加载(重新 install 一下)。');
+  console.log(loaded
+    ? '✓ 后台自动同步在运行，每 30 分钟自动上报一次，不用你管。'
+    : '装过，但目前没在运行。重跑一次  npx -y tokenforbes-cli@latest daemon install  就能拉起来。');
   console.log('  任务文件: ' + PLIST);
-  console.log('  日志:     ' + LOG + '(看最近几次上报有没有出错)');
+  console.log('  日志:     ' + LOG + '（想看最近几次上报有没有出错就翻它）');
   return true;
 }
 
 function statusWindows() {
   try {
     execFileSync('schtasks', ['/query', '/tn', LABEL], { stdio: 'ignore' });
-    console.log('✓ 已安装,Windows 会每 30 分钟自动上报。');
+    console.log('✓ 后台自动同步在运行，Windows 每 30 分钟自动上报一次，不用你管。');
     return true;
   } catch {
     return false;
@@ -163,23 +165,23 @@ function needsInstall() {
 function status() {
   ensureSupported();
   const ok = process.platform === 'darwin' ? statusMac() : statusWindows();
-  if (!ok) console.log('未安装。装它:  tokenforbes daemon install');
+  if (!ok) console.log('后台自动同步还没开启。想开就跑：  npx -y tokenforbes-cli@latest daemon install');
 }
 
 function uninstallMac() {
   cleanupLegacyMac();
-  if (!fs.existsSync(PLIST)) return console.log('本来就没装。');
+  if (!fs.existsSync(PLIST)) return console.log('后台自动同步本来就没开，不用关。');
   try { execFileSync('launchctl', ['unload', PLIST], { stdio: 'ignore' }); } catch {}
   fs.rmSync(PLIST, { force: true });
-  console.log('✓ 已关闭后台自动同步,删除了任务文件。');
+  console.log('✓ 已关闭后台自动同步，任务文件也删干净了。想再开：  npx -y tokenforbes-cli@latest daemon install');
 }
 
 function uninstallWindows() {
   try {
     execFileSync('schtasks', ['/delete', '/tn', LABEL, '/f'], { stdio: 'ignore' });
-    console.log('✓ 已关闭后台自动同步。');
+    console.log('✓ 已关闭后台自动同步。想再开：  npx -y tokenforbes-cli@latest daemon install');
   } catch {
-    console.log('本来就没装。');
+    console.log('后台自动同步本来就没开，不用关。');
   }
   fs.rmSync(VBS, { force: true });
 }
@@ -199,9 +201,10 @@ export function ensureDaemonInstalled() {
     if (!requireKey()) return;
     if (process.platform === 'darwin') installMac();
     else installWindows();
-    console.log('后台自动同步已开启:之后每 30 分钟自动上报一次。');
+    console.log('顺手帮你开好了后台自动同步：之后每 30 分钟自动上报一次，不用再手动跑命令。');
+    console.log('（想关掉随时跑：  npx -y tokenforbes-cli@latest daemon uninstall ）');
   } catch (e) {
-    console.log('后台自动同步没自动开启,可稍后手动跑: tokenforbes daemon install');
+    console.log('后台自动同步这次没开成（不影响刚才的上报）。想开的话稍后手动跑：  npx -y tokenforbes-cli@latest daemon install');
   }
 }
 
@@ -209,5 +212,8 @@ export function daemon(sub) {
   if (sub === 'install') return install();
   if (sub === 'status') return status();
   if (sub === 'uninstall' || sub === 'remove') return uninstall();
-  console.log('用法: tokenforbes daemon install | status | uninstall');
+  console.log('后台自动同步的开关，这样用：');
+  console.log('  npx -y tokenforbes-cli@latest daemon install     开启（每 30 分钟自动上报）');
+  console.log('  npx -y tokenforbes-cli@latest daemon status      看状态');
+  console.log('  npx -y tokenforbes-cli@latest daemon uninstall   关闭');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenforbes-cli",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "上报本地 AI 编程工具(Claude Code / Codex 等)的 token 用量到 Token 福布斯排行榜(ceorank.cn)。只读用量数字和设备型号，绝不碰你的代码内容。",
   "type": "module",
   "bin": {