numable-codex-usage 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,6 @@
 # Codex 用量采集器
 
-在电脑上统计 Codex 用量，并按需同步到 Numable。首发版本为 `0.1.0`；各平台验证范围见文末兼容矩阵。
+在电脑上统计 Codex 用量，并按需同步到 Numable。当前版本为 `0.1.2`；各平台验证范围见文末兼容矩阵。
 
 需要 Node.js 18.17 或以上；建议使用当前长期支持版本。采集器不假设 Codex 自带可供外部使用的 Node.js。
 
@@ -28,7 +28,7 @@ node codex/cli.cjs status
 
 Codex 的设备删除同时清除历史统计和实时视图。删除不撤销该电脑已有的写入凭证，也不清理它的本机历史；仍在同步的电脑有新活动或下一次实时补偿上报时可以重新出现。想持续移除一台电脑，应先在那台电脑运行 `pause` 或 `uninstall`，再从另一台电脑执行 `forget`。服务在 24 小时内保留删除前的实时序号，拒绝旧包复活会话；更新的正常上报仍可恢复。
 
-本机采集默认不联网。配置与历史保存在 `~/.numable/codex-usage/`，目录及文件分别以仅当前用户可访问的权限创建。
+本机统计默认不向 Numable 同步。已开启的额度检查会在采集时通过本机 Codex 协议请求官方额度，可用 `quota-auto-off` 关闭。配置与历史保存在 `~/.numable/codex-usage/`，目录及文件分别以仅当前用户可访问的权限创建。
 
 首次扫描需要读取现有会话；之后只处理追加的完整行。支持 `sessions/` 与 `archived_sessions/`，gzip 归档可直接读取；zstd 归档需要系统提供 `zstd`。缺少解码器时会标注未读取，不伪装成零用量。
 
@@ -54,6 +54,20 @@ node codex/cli.cjs quota-auto-on
 
 主动读取通过本机 Codex 协议完成，不创建会话，不要求复制 OpenAI 登录凭证。账号标识在本机匿名化；加入同一空间后使用空间范围的匿名标识，以便服务端合并同账号多台电脑的额度。不能识别账号的日志快照按设备分别展示。
 
+0.1.1 的 `init` 在首次配置或旧版未设置时开启每五分钟只读额度检查；明确执行过 `quota-auto-off` 的选择保持不变。初始化本身不启动协议读取或后台进程，也不自动上传历史。
+
+从0.1.0升级后，请运行以下命令；已运行的后台进程必须重启才能使用新版本：
+
+```sh
+npm install -g numable-codex-usage@0.1.2
+numable-codex stop
+numable-codex init
+numable-codex start
+numable-codex status
+```
+
+`status` 会显示 `quotaAuto`、`quotaStatus` 和开启指引；如需主动开启，可运行 `numable-codex quota-auto-on`。额度观测超过15分钟或窗口到期后，页面只保留带过期标识的上次值，不将其当作当前额度。电脑休眠、离线、采集停止或读取失败均可能导致观测过期。
+
 `quota-auto-on` 显式开启每五分钟读取，需后台采集运行；`quota-auto-off` 关闭。多个目录分别连接，单个目录失败会保留其旧观测并标注不完整。macOS 的命令行启动器不可用时，会尝试已安装桌面端的内置可执行文件；也可显式指定路径。
 
 ## 手机同步
@@ -160,3 +174,27 @@ Windows 上默认使用系统 Windows PowerShell，并额外经 cmd / PowerShell
 默认后台采集只在当前用户会话中运行；`start` 不注册开机启动服务。电脑重启后需再次运行。真实钩子和定时补偿互补，钩子尚未信任时仍可手动 `collect` 或运行 `start` 采集历史。
 
 Windows、不同 Codex 入口、四端真机与线上发布进度见 meta 仓 `doc/codex-usage-impl-plan.md`，不能用本机测试通过代替。
+
+
+## macOS 系统托管与退出诊断（0.1.2）
+
+```sh
+npm install -g numable-codex-usage@0.1.2
+numable-codex autostart-on
+numable-codex status
+```
+
+`autostart-on` 为当前用户安装 LaunchAgent，并将已有手动采集进程切换到系统托管：登录后自动启动，进程退出后由系统恢复（节流约15秒）。无需管理员权限；不会创建同步空间、修改凭证或开启已暂停的同步。首次使用仍需先 `init`，是否同步由 `connect/pause/resume` 控制。开机后需要登录该用户，退出登录或电脑休眠期间不保证上传。
+
+托管使用明确的命令参数，不经过 Shell，登录项不含同步令牌。启用时将当前已验证的 Node.js 可执行文件固定到状态目录的 `runtime/node`，先验证能够独立运行，避免原桌面应用升级或启动器路径失效影响后台。需要 Node.js 18.17 或以上；全局 npm 程序被移除或目录改名后，需重新安装并运行 `autostart-on`。Node.js 安全更新后应再次运行该命令刷新固定运行时。
+
+- `stop` 会先卸载本次已加载的系统任务，再确认采集进程停止，避免刚停就被拉起；登录项文件保留，下次登录恢复。
+- `start` 在有登录项时重新加载系统任务；未配置托管时沿用手动后台方式。
+- `autostart-off` 移除登录项并停止后台，保留配置、历史与同步开关。
+- `uninstall` 同时移除本工具系统托管和事件钩子、暂停同步，保留历史。直接 `npm uninstall` 前请先执行 `numable-codex uninstall`。
+
+本版系统托管支持 **macOS**。Windows / Linux 仍用原有 `start/watch/stop`，新增诊断日志同样可用；不宣称这些平台已有系统自启，Windows 原生仍待验。
+
+`status` 新增 `background.running`、`heartbeatAt`、系统托管 `enabled/loaded`、系统记录的运行次数/最近退出码或信号、最后采集/统计上传时间与日志路径。开关开启、进程存活、心跳更新和上传成功是四个不同状态，不能只凭同步开关判断在线。
+
+诊断日志位于状态目录 `logs/diagnostic.jsonl`，仅当前用户可读；单文件约1 MiB，最多保留三个轮换备份。记录启动、正常停止原因、采集开始/成功/失败、耗时、连续失败次数、HTTP状态码和固定错误分类；不写错误原文、堆栈、令牌、项目/文件路径、命令参数、账号标识或会话内容。安静模式致命失败也会记录并返回非零，便于系统恢复。日志写入失败不阻止采集；SIGKILL、系统关机等可能没有退出事件，不能据此编造退出原因。

package/cli.cjs

@@ -5,6 +5,8 @@ const path = require('node:path');
 const os = require('node:os');
 const crypto = require('node:crypto');
 const { spawn } = require('node:child_process');
+const background = require('./lib/background.cjs');
+const { diagnostic, errorKind, watcher } = require('./lib/diagnostics.cjs');
 const { collect, initialState, atomicWrite, hash } = require('./lib/collect.cjs');
 const { readQuotaHomes } = require('./lib/quota.cjs');
 const { sanitizeHook, absorbHook, buildLive } = require('./lib/live.cjs');
@@ -101,7 +103,7 @@ async function request(config, route, body, token) {
     const r = await fetch(config.endpoint + route, { method: body === undefined ? 'GET' : 'POST', redirect: 'error', signal: controller.signal,
       headers: { 'content-type': 'application/json', ...(token ? { authorization: `Bearer ${token}` } : {}) },
       ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
-    if (!r.ok) throw new Error(`服务请求失败（${r.status}），请检查连接后重试`);
+    if (!r.ok) throw Object.assign(new Error(`服务请求失败（${r.status}），请检查连接后重试`), { httpStatus: r.status });
     return await r.json();
   } finally { clearTimeout(timer); }
 }
@@ -252,7 +254,7 @@ async function scan(args, p, config) {
 async function main(argv = process.argv.slice(2)) {
   const args = parse(argv), p = paths(args);
   if (args.command === 'help' || args.command === '--help') {
-    console.log('Codex 用量\ninit：初始化本机采集（默认不同步）\ncollect：增量采集；--rebuild：重算\nsummary：查看统计；--json：导出纯数字快照\nstatus：查看采集与同步状态\nquota：主动读取额度；--codex-binary 指定 Codex\nquota-auto-on/off：开启或关闭每五分钟读取额度\nlive-on/off：开启或关闭匿名实时状态；live：查看实时投影\ndevices：列出已接入电脑\nforget：删除 --device 指定的其他电脑数据\nconnect：创建读取凭证并开启同步\ncredentials：显示手机使用的读取凭证\npause：暂停同步\nresume：恢复已绑定的同步\njoin：从标准输入读取另一台电脑生成的加入串\nlink：生成供自己另一台电脑使用的加入串\ninstall：安装事件钩子（之后需在 Codex 中信任）\nuninstall：仅移除本工具安装的钩子，保留本机记录\nstart：后台启动并确认运行；watch：在前台每 60 秒补充采集；stop：请求停止后台采集\n通用选项：--home 目录（可重复）、--state-dir 目录、--timezone 时区、--endpoint 服务地址、--projects on|off');
+    console.log('Codex 用量\ninit：初始化本机采集（默认不同步）\ncollect：增量采集；--rebuild：重算\nsummary：查看统计；--json：导出纯数字快照\nstatus：查看采集与同步状态\nquota：主动读取额度；--codex-binary 指定 Codex\nquota-auto-on/off：开启或关闭每五分钟读取额度\nlive-on/off：开启或关闭匿名实时状态；live：查看实时投影\ndevices：列出已接入电脑\nforget：删除 --device 指定的其他电脑数据\nconnect：创建读取凭证并开启同步\ncredentials：显示手机使用的读取凭证\npause：暂停同步\nresume：恢复已绑定的同步\njoin：从标准输入读取另一台电脑生成的加入串\nlink：生成供自己另一台电脑使用的加入串\ninstall：安装事件钩子（之后需在 Codex 中信任）\nuninstall：仅移除本工具安装的钩子，保留本机记录\nautostart-on/off：开启/移除 macOS 登录自启与退出自动恢复\nstart：后台启动并确认运行；watch：在前台每 60 秒补充采集；stop：请求停止后台采集\n通用选项：--home 目录（可重复）、--state-dir 目录、--timezone 时区、--endpoint 服务地址、--projects on|off');
     return;
   }
   const config = configFor(args, p);
@@ -270,7 +272,12 @@ async function main(argv = process.argv.slice(2)) {
     process.stdout.write('{}\n');
     return;
   }
-  if (args.command === 'init') { await saveConfig(p, config); output('本机采集已初始化，手机同步尚未开启'); return; }
+  if (args.command === 'init') {
+    // 首次配置或旧版未设置时启用只读额度检查，保留用户明确关闭的选择。
+    if (typeof read(p.config, {}).quotaAuto !== 'boolean') config.quotaAuto = true;
+    await saveConfig(p, config);
+    output(`本机采集已初始化；手机同步${config.sync ? '已开启' : '尚未开启'}。${config.quotaAuto ? '已启用每五分钟只读额度检查，运行 start 保持后台采集；可用 quota-auto-off 关闭' : '额度自动读取已关闭；可用 quota-auto-on 开启'}`); return;
+  }
   if (args.command === 'collect') {
     if (args.hookWorker) {
       let release;
@@ -318,10 +325,15 @@ async function main(argv = process.argv.slice(2)) {
     if (!snapshot) throw new Error('还没有用量记录，请先运行 collect');
     output(snapshot); return;
   }
+  if (args.command === 'autostart-on' || args.command === 'autostart-off') {
+    if (!fs.existsSync(p.config)) throw new Error('请先运行 init 初始化本机采集');
+    if (args.command === 'autostart-on') await background.enable(p.dir); else await background.disable(p.dir);
+    output(args.command === 'autostart-on' ? '系统托管已开启：登录后自动启动，异常退出后自动恢复' : '系统托管已移除，后台采集已停止'); return;
+  }
   if (args.command === 'status') {
     const snapshot = read(p.snapshot, null);
-    output({ initialized: fs.existsSync(p.config), sync: config.sync, paired: !!config.writeToken, live: config.live,
-      quotaAuto: config.quotaAuto === true, quotaStatus: config.quotaStatus || null, syncError: config.syncError || null,
+    output({ background: { ...watcher(p.dir), ...background.serviceStatus(p.dir) }, diagnosticLog: path.join(p.dir, 'logs/diagnostic.jsonl'), lastCollect: config.lastCollect || null, lastStatsPush: config.lastStatsPush || null, initialized: fs.existsSync(p.config), sync: config.sync, paired: !!config.writeToken, live: config.live,
+      quotaAuto: config.quotaAuto === true, quotaHint: config.quotaAuto ? '请保持后台采集运行；读取失败时检查 Codex 登录状态' : '运行 numable-codex quota-auto-on，再运行 numable-codex start', quotaStatus: config.quotaStatus || null, syncError: config.syncError ?? null,
       collectedAt: snapshot?.collectedAt || null, timezone: config.timezone, projects: config.projects,
       coverage: snapshot?.coverage || [], diagnostics: snapshot?.diagnostics || null, collection: snapshot?.collection || null,
       hooksInstalled: !!config.installed?.length, hooksTrust: config.installed?.length ? 'check-in-codex' : null });
@@ -376,13 +388,15 @@ async function main(argv = process.argv.slice(2)) {
     output('事件钩子已安装。请在 Codex 中检查并信任新增钩子，信任后才会自动采集'); return;
   }
   if (args.command === 'uninstall') {
+    if (background.installed(p.dir)) await background.disable(p.dir); else await background.stop(p.dir);
     uninstallHooks(config); config.installed = []; config.sync = false; await saveConfig(p, config);
     atomicWrite(path.join(p.dir, 'stop.json'), { at: Date.now() }); output('已移除本工具的事件钩子并暂停同步，本机记录仍保留'); return;
   }
-  if (args.command === 'stop') { atomicWrite(path.join(p.dir, 'stop.json'), { at: Date.now() }); output('已请求停止后台采集'); return; }
+  if (args.command === 'stop') { await background.stop(p.dir); output('后台采集已停止；已配置的登录自启会在下次登录后恢复'); return; }
   if (args.command === 'start') {
     if (!fs.existsSync(p.config)) throw new Error('请先运行 init 初始化本机采集');
-    const watchLock = path.join(p.dir, 'watch.lock'), previous = read(watchLock, null);
+    if (background.installed(p.dir)) { await background.managedStart(p.dir); output('系统托管的后台采集已启动'); return; }
+    const watchLock = path.join(p.dir, 'watch.lock'), previous = watcher(p.dir);
     if (previous?.pid) {
       try { process.kill(previous.pid, 0); output('后台采集已在运行'); return; }
       catch (e) { if (e.code !== 'ESRCH') throw e; }
@@ -390,33 +404,51 @@ async function main(argv = process.argv.slice(2)) {
     const child = spawn(process.execPath, [__filename, 'watch', '--state-dir', p.dir, '--quiet'], { detached: true, stdio: 'ignore', windowsHide: true });
     let failed = false; child.once('error', () => { failed = true; }); child.unref();
     for (let i = 0; i < 40 && !failed; i++) {
-      if (read(watchLock, null)?.pid === child.pid) { output('后台采集已启动'); return; }
+      if (watcher(p.dir).pid === child.pid) { output('后台采集已启动'); return; }
       await new Promise((resolve) => setTimeout(resolve, 50));
     }
     throw new Error('未能确认后台采集启动，请运行 watch 查看状态');
   }
   if (args.command === 'watch') {
     const release = lock(path.join(p.dir, 'watch.lock')), startedAt = Date.now();
-    let stopped = false;
-    process.once('SIGINT', () => { stopped = true; }); process.once('SIGTERM', () => { stopped = true; });
+    let stopped = false, reason = 'normal', failures = 0;
+    diagnostic(p.dir, 'watch_start', { sync: config.sync, quotaAuto: config.quotaAuto });
+    atomicWrite(path.join(p.dir, 'heartbeat.json'), { pid: process.pid, at: Date.now() });
+    process.once('SIGINT', () => { stopped = true; reason = 'signal'; }); process.once('SIGTERM', () => { stopped = true; reason = 'signal'; });
     try {
       while (!stopped) {
-        if ((read(path.join(p.dir, 'stop.json'), {})?.at || 0) >= startedAt) break;
-        try { await scan(args, p, configFor(args, p)); } catch { if (!args.quiet) console.error('本轮采集未完成，将在下一轮重试'); }
+        if ((read(path.join(p.dir, 'stop.json'), {})?.at || 0) >= startedAt) { reason = 'stop_request'; break; }
+        const scanStart = Date.now(); diagnostic(p.dir, 'scan_start');
+        try {
+          await scan(args, p, configFor(args, p)); failures = 0;
+          const latest = read(p.config, {}); diagnostic(p.dir, 'scan_ok', { elapsedMs: Date.now() - scanStart, lastCollect: latest.lastCollect, lastStatsPush: latest.lastStatsPush, sync: latest.sync, quotaStatus: latest.quotaStatus });
+        } catch (error) {
+          failures++; diagnostic(p.dir, 'scan_failed', { elapsedMs: Date.now() - scanStart, failures, kind: errorKind(error), httpStatus: error.httpStatus });
+          if (!args.quiet) console.error('本轮采集未完成，将在下一轮重试');
+        }
         for (let i = 0; i < 60 && !stopped; i++) {
-          if ((read(path.join(p.dir, 'stop.json'), {})?.at || 0) >= startedAt) { stopped = true; break; }
+          if (i % 10 === 0) atomicWrite(path.join(p.dir, 'heartbeat.json'), { pid: process.pid, at: Date.now(), failures });
+          if ((read(path.join(p.dir, 'stop.json'), {})?.at || 0) >= startedAt) { stopped = true; reason = 'stop_request'; break; }
           await new Promise((resolve) => setTimeout(resolve, 1000));
         }
       }
-    } finally { release(); }
+    } finally { diagnostic(p.dir, 'watch_stop', { reason }); release(); }
     return;
   }
   throw new Error('无法识别命令，请运行 help 查看用法');
 }
-if (require.main === module) main().catch((e) => {
+if (require.main === module) {
+  const failure = error => {
+    try { diagnostic(paths(parse(process.argv.slice(2))).dir, 'fatal', { kind: errorKind(error) }); } catch {}
+    process.exit(1);
+  };
+  process.once('uncaughtException', failure); process.once('unhandledRejection', failure);
+  main().catch((e) => {
+  try { diagnostic(paths(parse(process.argv.slice(2))).dir, 'fatal', { kind: errorKind(e), httpStatus: e.httpStatus }); } catch {}
   if (process.argv[2] === 'hook') { process.stdout.write('{}\n'); return; }
-  if (process.argv.includes('--quiet')) return;
+  if (process.argv.includes('--quiet')) { process.exitCode = 1; return; }
   console.error(e.message && !/ENOENT|EACCES|ENOSPC|fetch failed/.test(e.message) ? e.message : '操作未完成，请检查本机目录、网络与可用空间后重试');
   process.exitCode = 1;
-});
+  });
+}
 module.exports = { parse, paths, endpoint, configFor, lock, installHooks, uninstallHooks, scan, request, main, hookCommand };

package/lib/background.cjs

@@ -0,0 +1,71 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
+const { spawnSync } = require('node:child_process');
+const { watcher, diagnostic } = require('./diagnostics.cjs');
+const { atomicWrite } = require('./collect.cjs');
+const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
+function serviceSpec(dir, { home = os.homedir(), uid = process.getuid?.(), node = process.execPath, cli = path.resolve(__dirname, '../cli.cjs'), envPath = process.env.PATH || '' } = {}) {
+  const label = 'app.numable.codex-usage.' + crypto.createHash('sha256').update(path.resolve(dir)).digest('hex').slice(0, 12);
+  const file = path.join(home, 'Library/LaunchAgents', label + '.plist');
+  const escape = value => {
+    if (/[\x00-\x08\x0B\x0C\x0E-\x1F]/.test(value)) throw new Error('启动目录包含不支持的字符');
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&apos;');
+  };
+  const args = [node, cli, 'watch', '--state-dir', path.resolve(dir), '--quiet'];
+  const searchPath = [path.dirname(node), envPath, '/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin'].filter(Boolean).join(':');
+  const xml = `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict><key>Label</key><string>${label}</string><key>ProgramArguments</key><array>${args.map(a => '<string>' + escape(a) + '</string>').join('')}</array><key>RunAtLoad</key><true/><key>KeepAlive</key><true/><key>ThrottleInterval</key><integer>15</integer><key>ExitTimeOut</key><integer>20</integer><key>ProcessType</key><string>Background</string><key>EnvironmentVariables</key><dict><key>PATH</key><string>${escape(searchPath)}</string></dict><key>StandardOutPath</key><string>/dev/null</string><key>StandardErrorPath</key><string>/dev/null</string></dict></plist>\n`;
+  return { label, file, xml, domain: 'gui/' + uid, target: 'gui/' + uid + '/' + label };
+}
+function control(args, allowFailure = false) {
+  const r = spawnSync('/bin/launchctl', args, { encoding: 'utf8', timeout: 25000 });
+  if (r.status !== 0 && !allowFailure) throw new Error('系统托管操作未完成，请运行 status 检查后台状态');
+  return r.status === 0;
+}
+function installed(dir) { return process.platform === 'darwin' && fs.existsSync(serviceSpec(dir).file); }
+function serviceStatus(dir) {
+  const enabled = installed(dir);
+  if (!enabled) return { supported: process.platform === 'darwin', enabled: false, loaded: false };
+  const r = spawnSync('/bin/launchctl', ['print', serviceSpec(dir).target], { encoding: 'utf8', timeout: 10000 });
+  const text = r.stdout || '', number = pattern => { const m = pattern.exec(text); return m ? Number(m[1]) : null; };
+  return { supported: true, enabled, loaded: r.status === 0, runs: number(/\bruns = (\d+)/), lastExitCode: number(/last exit code = (\d+)/), lastSignal: number(/last terminating signal = [^\n]*?:?\s(\d+)/) };
+}
+async function waitRunning(dir) {
+  for (let i = 0; i < 100; i++) { const state = watcher(dir); if (state.running && state.heartbeatAt) return state; await delay(100); }
+  throw new Error('未能确认后台采集启动，请检查 status 与诊断日志');
+}
+async function stop(dir) {
+  if (installed(dir)) { const spec = serviceSpec(dir); if (control(['print', spec.target], true)) control(['bootout', spec.target]); }
+  atomicWrite(path.join(dir, 'stop.json'), { at: Date.now() });
+  for (let i = 0; i < 200; i++) { if (!watcher(dir).running) return; await delay(100); }
+  throw new Error('后台仍在完成本轮采集，请稍后再次运行 stop');
+}
+async function managedStart(dir) {
+  const spec = serviceSpec(dir);
+  if (!control(['print', spec.target], true)) control(['bootstrap', spec.domain, spec.file]);
+  control(['kickstart', spec.target]); return waitRunning(dir);
+}
+async function enable(dir) {
+  if (process.platform !== 'darwin') throw new Error('系统托管目前支持 macOS；当前平台请使用 start 或 watch');
+  const [major, minor] = process.versions.node.split('.').map(Number);
+  if (major < 18 || major === 18 && minor < 17) throw new Error('系统托管需要 Node.js 18.17 或以上');
+  await stop(dir);
+  // 固定本次已验证的运行时，避免启动器或桌面应用更新后原路径消失。
+  const runtime = path.join(dir, 'runtime'); fs.mkdirSync(runtime, { recursive: true, mode: 0o700 });
+  const node = path.join(runtime, 'node'), staged = node + '.tmp-' + process.pid;
+  fs.copyFileSync(process.execPath, staged); fs.chmodSync(staged, 0o700);
+  const probe = spawnSync(staged, ['--version'], { encoding: 'utf8', timeout: 10000 });
+  if (probe.status !== 0 || probe.stdout.trim() !== process.version) { fs.unlinkSync(staged); throw new Error('固定运行时校验失败，系统托管未启用'); }
+  fs.renameSync(staged, node);
+  const spec = serviceSpec(dir, { node }); fs.mkdirSync(path.dirname(spec.file), { recursive: true });
+  const temporary = spec.file + '.tmp-' + process.pid;
+  fs.writeFileSync(temporary, spec.xml, { mode: 0o600 }); fs.chmodSync(temporary, 0o600); fs.renameSync(temporary, spec.file);
+  await managedStart(dir); diagnostic(dir, 'service_on');
+}
+async function disable(dir) {
+  if (process.platform !== 'darwin') throw new Error('当前平台没有本工具的系统托管配置');
+  await stop(dir); const spec = serviceSpec(dir); if (fs.existsSync(spec.file)) fs.unlinkSync(spec.file); diagnostic(dir, 'service_off');
+}
+module.exports = { serviceSpec, serviceStatus, installed, managedStart, enable, disable, stop, waitRunning };

package/lib/diagnostics.cjs

@@ -0,0 +1,47 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const VERSION = require('../package.json').version;
+const EVENTS = new Set(['watch_start', 'watch_stop', 'scan_start', 'scan_ok', 'scan_failed', 'fatal', 'service_on', 'service_off']);
+// 诊断仅接收固定事件与数字/布尔字段，不接受原始错误、路径、凭证或会话内容。
+function diagnostic(dir, event, fields = {}) {
+  if (!EVENTS.has(event)) return;
+  try {
+    const logs = path.join(dir, 'logs'); fs.mkdirSync(logs, { recursive: true, mode: 0o700 });
+    const file = path.join(logs, 'diagnostic.jsonl');
+    if (fs.existsSync(file) && fs.statSync(file).size >= 1024 * 1024) {
+      for (let i = 2; i >= 0; i--) {
+        const from = i ? file + '.' + i : file, to = file + '.' + (i + 1);
+        if (i === 2) { try { fs.unlinkSync(to); } catch {} }
+        if (fs.existsSync(from)) fs.renameSync(from, to);
+      }
+    }
+    const safe = {};
+    for (const key of ['elapsedMs', 'failures', 'quotaAuto', 'sync', 'lastCollect', 'lastStatsPush']) {
+      const value = fields[key]; if (typeof value === 'boolean' || typeof value === 'number' && Number.isFinite(value)) safe[key] = value;
+    }
+    if (Number.isInteger(fields.httpStatus) && fields.httpStatus >= 100 && fields.httpStatus <= 599) safe.httpStatus = fields.httpStatus;
+    if (['ready', 'partial', 'unavailable'].includes(fields.quotaStatus)) safe.quotaStatus = fields.quotaStatus;
+    if (['signal', 'stop_request', 'normal'].includes(fields.reason)) safe.reason = fields.reason;
+    if (['busy', 'network', 'storage', 'operation'].includes(fields.kind)) safe.kind = fields.kind;
+    fs.appendFileSync(file, JSON.stringify({ at: Date.now(), pid: process.pid, version: VERSION, event, ...safe }) + '\n', { mode: 0o600 });
+    fs.chmodSync(file, 0o600);
+  } catch { /* 日志故障不能阻止采集或暴露原始异常。 */ }
+}
+function errorKind(error) {
+  if (error?.code === 'LOCK_BUSY') return 'busy';
+  if (['ENOENT', 'EACCES', 'ENOSPC'].includes(error?.code)) return 'storage';
+  if (error?.name === 'AbortError' || error?.name === 'TypeError' || /^服务请求失败/.test(error?.message || '')) return 'network';
+  return 'operation';
+}
+function watcher(dir) {
+  try {
+    const lock = JSON.parse(fs.readFileSync(path.join(dir, 'watch.lock'), 'utf8'));
+    if (!Number.isSafeInteger(lock.pid) || lock.pid <= 0) return { running: false };
+    process.kill(lock.pid, 0);
+    let heartbeat = null;
+    try { heartbeat = JSON.parse(fs.readFileSync(path.join(dir, 'heartbeat.json'), 'utf8')); } catch {}
+    return { running: true, pid: lock.pid, heartbeatAt: heartbeat?.pid === lock.pid ? heartbeat.at : null };
+  } catch { return { running: false }; }
+}
+module.exports = { diagnostic, errorKind, watcher };

package/lib/quota.cjs

@@ -46,7 +46,7 @@ function readQuota({ binary = process.env.NUMABLE_CODEX_BINARY || 'codex', home,
         finish(null, { observedAt, scope: hash(salt, 'quota-scope'), supported: quotas.length > 0, quotas });
       }
     });
-    send({ id: 1, method: 'initialize', params: { clientInfo: { name: 'numable_codex_usage', version: '0.1.0' }, capabilities: { experimentalApi: true } } });
+    send({ id: 1, method: 'initialize', params: { clientInfo: { name: 'numable_codex_usage', version: '0.1.2' }, capabilities: { experimentalApi: true } } });
   });
 }
 async function readQuotaHomes({ homes, salt, profileSalt = salt, previous, ...options }) {

package/package.json

@@ -1,10 +1,20 @@
 {
   "name": "numable-codex-usage",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "在本机统计 Codex 用量，并按需同步到 Numable",
   "license": "MIT",
-  "engines": { "node": ">=18.17" },
-  "bin": { "numable-codex": "cli.cjs" },
-  "files": ["cli.cjs", "lib/", "README.md"],
-  "scripts": { "test": "node --test ../test/codex-*.test.cjs" }
+  "engines": {
+    "node": ">=18.17"
+  },
+  "bin": {
+    "numable-codex": "cli.cjs"
+  },
+  "files": [
+    "cli.cjs",
+    "lib/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test ../test/codex-*.test.cjs"
+  }
 }