codex-work-receipt 0.6.0 → 0.7.0

package/src/cli.mjs

@@ -9,12 +9,13 @@ import QRCode from "qrcode";
 import { parseArgs, printHelp } from "./core/args.mjs";
 import { buildCanonicalFacts } from "./core/fact-buckets.mjs";
 import { collectMetrics } from "./core/metrics.mjs";
-import { getReceiptCopy } from "./core/presentation.mjs";
+import { getScopeLabel } from "./core/presentation.mjs";
 import { encodeReceiptPayloads } from "./core/qr-payload.mjs";
 import { outputSlugForRange, resolveRange } from "./core/range.mjs";
 import { buildReceiptRecord, persistReceiptRecord } from "./core/receipt-record.mjs";
 import { promptForRange } from "./core/selector.mjs";
 import { installCodexSkill } from "./core/skill-installer.mjs";
+import { installCodexPet, uninstallCodexPet } from "./core/pet-installer.mjs";
 import { formatNumber } from "./lib/time.mjs";
 import { listRecentCodexSessions, loadCodexSessions } from "./parsers/codex.mjs";
 import { renderHtml } from "./renderers/html.mjs";
@@ -64,6 +65,33 @@ async function main() {
     }
     return;
   }
+  if (options.installPet || options.installCompanion) {
+    const installedPet = installCodexPet({ projectDir: PROJECT_DIR });
+    const installedSkill = options.installCompanion
+      ? installCodexSkill({ projectDir: PROJECT_DIR })
+      : null;
+    if (options.locale === "en") {
+      if (installedSkill) console.log(`AI Work Receipt skill installed: ${installedSkill.targetDir}`);
+      console.log(`Codex pet installed: ${installedPet.targetDir}`);
+      console.log("Restart Codex, open Settings > Pets, select Refresh, then choose 票仔 · AI 小票工 (Ticket Buddy).");
+      console.log("Use /pet to wake it. You can then ask: Ticket Buddy, create a receipt for today.");
+    } else {
+      if (installedSkill) console.log(`AI 打工小票 Skill 已安装：${installedSkill.targetDir}`);
+      console.log(`Codex 桌宠已安装：${installedPet.targetDir}`);
+      console.log("请重启 Codex，打开 Settings > Pets，点击 Refresh 后选择“票仔 · AI 小票工”。");
+      console.log("输入 /pet 唤醒票仔；以后可以说：票仔，开今天的票。");
+    }
+    return;
+  }
+  if (options.uninstallPet) {
+    const removed = uninstallCodexPet();
+    if (options.locale === "en") {
+      console.log(removed.existed ? `Codex pet removed: ${removed.targetDir}` : "Codex pet was not installed.");
+    } else {
+      console.log(removed.existed ? `Codex 桌宠已卸载：${removed.targetDir}` : "尚未安装 AI 打工小票桌宠。");
+    }
+    return;
+  }
 
   if (!options.modeExplicit && process.stdin.isTTY && process.stdout.isTTY) {
     const selected = await promptForRange({
@@ -73,13 +101,16 @@ async function main() {
     });
     options.mode = selected.mode;
     options.sessionId = selected.sessionId;
+    options.hours = selected.hours || options.hours;
   }
 
-  const range = resolveRange(options.mode, options.timezone, new Date(), options.sessionId);
+  const range = resolveRange(options.mode, options.timezone, new Date(), options.sessionId, options.hours);
   const sessions = loadCodexSessions(range);
   const metrics = collectMetrics(sessions, range);
   const observedAt = new Date().toISOString();
-  const canonical = buildCanonicalFacts(sessions, range, { observedAt });
+  const canonical = range.scope === "last-hours"
+    ? {}
+    : buildCanonicalFacts(sessions, range, { observedAt });
   const record = buildReceiptRecord(metrics, options.theme, options.locale, canonical);
   const qrPayloads = encodeReceiptPayloads(record);
   const dataQrDataUrls = await Promise.all(qrPayloads.map((payload) => QRCode.toDataURL(payload, {
@@ -109,17 +140,21 @@ async function main() {
     console.log(`Generated HTML: ${outputFile}`);
     console.log(`Structured data: ${persisted.companionPath}`);
     console.log(`Local history: ${persisted.receiptPath}`);
-    console.log(`Range: ${getReceiptCopy(options.locale).scope[record.source.scope]} · ${record.stats.session_count} session(s)`);
+    console.log(`Range: ${getScopeLabel(record.source.scope, options.locale, record.source.hours)} · ${record.stats.session_count} session(s)`);
     console.log(`Stats: ${record.stats.completed_turns} turns · ${formatNumber(record.stats.tokens.total_tokens, options.locale)} Tokens · ${record.stats.tool_calls} tool calls`);
-    console.log(`Data QR: ${qrPayloads.length} code(s) · ${record.manifest.fact_count} canonical fact(s) · schema v${record.schema_version}`);
+    console.log(record.manifest
+      ? `Data QR: ${qrPayloads.length} code(s) · ${record.manifest.fact_count} canonical fact(s) · schema v${record.schema_version}`
+      : `Data QR: ${qrPayloads.length} code(s) · rolling summary · schema v${record.schema_version}`);
     if (!miniProgramCodeDataUrl) console.log("Mini-program code: not configured; using the explicit placeholder");
   } else {
     console.log(`已生成网页：${outputFile}`);
     console.log(`结构数据：${persisted.companionPath}`);
     console.log(`本地历史：${persisted.receiptPath}`);
-    console.log(`统计范围：${getReceiptCopy(options.locale).scope[record.source.scope]} · ${record.stats.session_count} 个会话`);
+    console.log(`统计范围：${getScopeLabel(record.source.scope, options.locale, record.source.hours)} · ${record.stats.session_count} 个会话`);
     console.log(`统计：${record.stats.completed_turns} 轮 · ${formatNumber(record.stats.tokens.total_tokens, options.locale)} Token · ${record.stats.tool_calls} 次工具调用`);
-    console.log(`数据二维码：${qrPayloads.length} 个 · ${record.manifest.fact_count} 条规范事实 · schema v${record.schema_version}`);
+    console.log(record.manifest
+      ? `数据二维码：${qrPayloads.length} 个 · ${record.manifest.fact_count} 条规范事实 · schema v${record.schema_version}`
+      : `数据二维码：${qrPayloads.length} 个 · 滚动摘要 · schema v${record.schema_version}`);
     if (!miniProgramCodeDataUrl) console.log("小程序码：尚未配置，页面使用明确占位符");
   }
   if (options.open) openFile(outputFile);

package/src/core/args.mjs

@@ -7,13 +7,16 @@ Codex AI Work Receipt
 Usage:
   npx codex-work-receipt@latest
   npx codex-work-receipt@latest --latest --lang en
+  npx codex-work-receipt@latest --hours 3 --lang en
   npx codex-work-receipt@latest --today --lang en
   npx codex-work-receipt@latest --range last-7-days --lang en
   npx codex-work-receipt@latest --range this-week --lang en
   npx codex-work-receipt@latest --install-skill --lang en
+  npx codex-work-receipt@latest --install-companion --lang en
 
 Options:
-  --range <name>              Range: latest, today, last-7-days, this-week
+  --range <name>              Range: latest, last-hours, today, last-7-days, this-week
+  --hours <number>            Summarize the last 1-168 hours
   --latest                    Summarize the latest active Codex session (default)
   --today                     Summarize all Codex activity from today
   --session <id>              Summarize one specific Codex session
@@ -23,6 +26,9 @@ Options:
   --output <file>             Set the generated HTML path
   --data-dir <directory>      Set the local structured-history directory
   --install-skill             Install the natural-language Codex skill
+  --install-pet               Install the Codex pet only
+  --uninstall-pet             Remove the installed Codex pet
+  --install-companion         Install both the skill and Codex pet
   --no-open                   Do not open the browser after generation
   --help                      Show help
 ` : `
@@ -31,13 +37,16 @@ Codex AI 打工小票
 用法：
   npx codex-work-receipt@latest
   npx codex-work-receipt@latest --latest
+  npx codex-work-receipt@latest --hours 3
   npx codex-work-receipt@latest --today
   npx codex-work-receipt@latest --range last-7-days
   npx codex-work-receipt@latest --range this-week
   npx codex-work-receipt@latest --install-skill
+  npx codex-work-receipt@latest --install-companion
 
 选项：
-  --range <name>              统计范围：latest、today、last-7-days、this-week
+  --range <name>              统计范围：latest、last-hours、today、last-7-days、this-week
+  --hours <number>            统计最近 1～168 小时
   --latest                    统计最近活跃的 Codex 会话（默认）
   --today                     统计本地时区今天发生的全部 Codex 活动
   --session <id>              统计指定的 Codex 会话
@@ -47,6 +56,9 @@ Codex AI 打工小票
   --output <file>             指定生成的 HTML 文件，默认写入 ./codex-work-receipt-output/
   --data-dir <directory>      指定本地结构数据目录
   --install-skill             安装可通过自然语言调用的 Codex Skill
+  --install-pet               只安装 Codex 桌宠
+  --uninstall-pet             卸载 AI 打工小票 Codex 桌宠
+  --install-companion         同时安装 Skill 和 Codex 桌宠
   --no-open                   生成后不自动打开浏览器
   --help                      显示帮助
 `);
@@ -57,12 +69,16 @@ export function parseArgs(argv) {
     mode: "latest",
     modeExplicit: false,
     sessionId: null,
+    hours: null,
     timezone: Intl.DateTimeFormat().resolvedOptions().timeZone || "Asia/Shanghai",
     locale: "zh-CN",
     theme: "classic",
     output: null,
     dataDir: null,
     installSkill: false,
+    installPet: false,
+    uninstallPet: false,
+    installCompanion: false,
     open: true,
   };
 
@@ -73,6 +89,7 @@ export function parseArgs(argv) {
     ["--output", "output"],
     ["--data-dir", "dataDir"],
     ["--session", "sessionId"],
+    ["--hours", "hours"],
   ]);
 
   for (let index = 0; index < argv.length; index += 1) {
@@ -83,7 +100,10 @@ export function parseArgs(argv) {
     } else if (argument === "--today") {
       result.mode = "today";
       result.modeExplicit = true;
-    } else if (argument === "--range") {
+    } else if (argument === "--install-pet") result.installPet = true;
+    else if (argument === "--uninstall-pet") result.uninstallPet = true;
+    else if (argument === "--install-companion") result.installCompanion = true;
+    else if (argument === "--range") {
       const value = argv[++index];
       if (!value) throw new Error("--range 需要提供值");
       const scope = normalizeScope(value);
@@ -101,6 +121,9 @@ export function parseArgs(argv) {
       if (key === "sessionId") {
         result.mode = "session";
         result.modeExplicit = true;
+      } else if (key === "hours") {
+        result.mode = "last-hours";
+        result.modeExplicit = true;
       }
     } else throw new Error(`不认识的参数：${argument}`);
   }
@@ -111,5 +134,12 @@ export function parseArgs(argv) {
   if (!new Set(["zh-CN", "en"]).has(result.locale)) {
     throw new Error(`不支持的语言：${result.locale}`);
   }
+  if (result.hours !== null) {
+    result.hours = Number(result.hours);
+    if (!Number.isInteger(result.hours) || result.hours < 1 || result.hours > 168) {
+      throw new Error("--hours 需要 1 至 168 之间的整数");
+    }
+  }
+  if (result.mode === "last-hours" && result.hours === null) result.hours = 3;
   return result;
 }

package/src/core/barcode.mjs

@@ -0,0 +1,52 @@
+const CODE128_PATTERNS = [
+  "212222", "222122", "222221", "121223", "121322", "131222", "122213", "122312", "132212", "221213", "221312", "231212",
+  "112232", "122132", "122231", "113222", "123122", "123221", "223211", "221132", "221231", "213212", "223112", "312131",
+  "311222", "321122", "321221", "312212", "322112", "322211", "212123", "212321", "232121", "111323", "131123", "131321",
+  "112313", "132113", "132311", "211313", "231113", "231311", "112133", "112331", "132131", "113123", "113321", "133121",
+  "313121", "211331", "231131", "213113", "213311", "213131", "311123", "311321", "331121", "312113", "312311", "332111",
+  "314111", "221411", "431111", "111224", "111422", "121124", "121421", "141122", "141221", "112214", "112412", "122114",
+  "122411", "142112", "142211", "241211", "221114", "413111", "241112", "134111", "111242", "121142", "121241", "114212",
+  "124112", "124211", "411212", "421112", "421211", "212141", "214121", "412121", "111143", "111341", "131141", "114113",
+  "114311", "411113", "411311", "113141", "114131", "311141", "411131", "211412", "211214", "211232", "2331112",
+];
+
+const START_CODE_B = 104;
+const STOP_CODE = 106;
+
+function normalizeCode128Value(value) {
+  return [...String(value)]
+    .map((character) => {
+      const code = character.charCodeAt(0);
+      return code >= 32 && code <= 126 ? character : "?";
+    })
+    .join("")
+    .slice(0, 48) || "CWR";
+}
+
+export function buildCode128B(value) {
+  const normalized = normalizeCode128Value(value);
+  const dataCodes = [...normalized].map((character) => character.charCodeAt(0) - 32);
+  const checksum = dataCodes.reduce(
+    (total, code, index) => total + code * (index + 1),
+    START_CODE_B,
+  ) % 103;
+  const codes = [START_CODE_B, ...dataCodes, checksum, STOP_CODE];
+  const segments = [];
+
+  for (const code of codes) {
+    const pattern = CODE128_PATTERNS[code];
+    for (const [index, width] of [...pattern].entries()) {
+      segments.push({
+        isBar: index % 2 === 0,
+        width: Number(width),
+      });
+    }
+  }
+
+  return {
+    value: normalized,
+    checksum,
+    segments,
+    totalModules: segments.reduce((total, segment) => total + segment.width, 0),
+  };
+}

package/src/core/fact-identity.mjs

@@ -28,12 +28,19 @@ export function buildLogicalReceiptKey(metrics) {
   if (metrics.mode === "latest" || metrics.mode === "session") {
     return `${metrics.mode}:${sessionPart}:${metrics.timezone}`;
   }
+  if (metrics.mode === "last-hours") {
+    return `last-hours:${metrics.windowHours}:${metrics.windowStartAt.toISOString()}:${metrics.windowEndAt.toISOString()}:${metrics.timezone}`;
+  }
   if (metrics.mode === "this-week") {
     return `this-week:${metrics.rangeStartDate}:${metrics.timezone}`;
   }
   return `${metrics.mode}:${metrics.rangeStartDate}:${metrics.rangeEndDate}:${metrics.timezone}`;
 }
 
+export function buildSummaryReceiptId(logicalReceiptKey) {
+  return stableId("cwr", "codex-work-receipt/receipt/v1", [logicalReceiptKey]);
+}
+
 export function buildProtocolReceiptId(sourceVersion, logicalReceiptKey) {
   return stableId("cwr2", "codex-work-receipt/receipt/v2", [sourceVersion, logicalReceiptKey]);
 }

package/src/core/metrics.mjs

@@ -1,5 +1,10 @@
 import { dateKey, rowDate } from "../lib/time.mjs";
-import { calendarDayCount, isCalendarScope, isDateInRange } from "./range.mjs";
+import {
+  calendarDayCount,
+  isCalendarScope,
+  isDateInRange,
+  isTimeWindowScope,
+} from "./range.mjs";
 import { selectWorkProfileId } from "./presentation.mjs";
 
 function zeroUsage() {
@@ -28,7 +33,8 @@ function sessionTokenUsage(rows, range) {
   for (const row of events) {
     const currentUsage = row.payload.info.total_token_usage;
     const date = rowDate(row);
-    const selected = !isCalendarScope(range.scope) || isDateInRange(date, range);
+    const selected = (!isCalendarScope(range.scope) && !isTimeWindowScope(range.scope))
+      || isDateInRange(date, range);
 
     for (const key of Object.keys(totals)) {
       const current = Math.max(0, Number(currentUsage[key] || 0));
@@ -56,6 +62,7 @@ function calculateWorkPoints(metrics) {
 }
 
 function emptyRangeMessage(range) {
+  if (range.scope === "last-hours") return `最近 ${range.hours} 小时没有找到 Codex 活动`;
   if (range.scope === "today") return `没有找到 ${range.targetDate} 的 Codex 活动`;
   if (range.scope === "last-7-days") return `没有找到 ${range.startDate} 至 ${range.endDate} 的 Codex 活动`;
   if (range.scope === "this-week") return `本周暂时没有找到 Codex 活动`;
@@ -78,7 +85,7 @@ export function collectMetrics(sessions, range) {
   const models = new Set();
 
   for (const session of sessions) {
-    const scopedRows = isCalendarScope(range.scope)
+    const scopedRows = isCalendarScope(range.scope) || isTimeWindowScope(range.scope)
       ? session.rows.filter((row) => isDateInRange(rowDate(row), range))
       : session.rows;
 
@@ -134,6 +141,9 @@ export function collectMetrics(sessions, range) {
     targetDate: range.targetDate,
     rangeStartDate,
     rangeEndDate,
+    windowStartAt: range.startAt,
+    windowEndAt: range.endAt,
+    windowHours: range.hours,
     calendarDayCount: isCalendarScope(range.scope) ? calendarDayCount(range) : 1,
     activeDayCount: Math.max(1, activeDateKeys.size),
     sessionIds,

package/src/core/pet-installer.mjs

@@ -0,0 +1,50 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const CODEX_PET_NAME = "ai-work-receipt";
+
+export function getCodexPetHome({ homeDir = os.homedir(), codexHome = null } = {}) {
+  return path.resolve(codexHome || process.env.CODEX_HOME || path.join(homeDir, ".codex"));
+}
+
+export function getCodexPetInstallPath(options = {}) {
+  return path.join(getCodexPetHome(options), "pets", CODEX_PET_NAME);
+}
+
+export function installCodexPet({ projectDir, homeDir = os.homedir(), codexHome = null } = {}) {
+  if (!projectDir) throw new Error("安装 Pet 时缺少项目目录");
+
+  const sourceDir = path.join(projectDir, "assets", "codex-pet", CODEX_PET_NAME);
+  const sourceManifest = path.join(sourceDir, "pet.json");
+  const sourceSpritesheet = path.join(sourceDir, "spritesheet.webp");
+  if (!fs.existsSync(sourceManifest) || !fs.existsSync(sourceSpritesheet)) {
+    throw new Error(`发布包中缺少 Codex Pet：${sourceDir}`);
+  }
+
+  const targetDir = getCodexPetInstallPath({ homeDir, codexHome });
+  const targetParent = path.dirname(targetDir);
+  const stagingDir = path.join(
+    targetParent,
+    `.${CODEX_PET_NAME}.install-${process.pid}-${Date.now()}`,
+  );
+
+  fs.mkdirSync(targetParent, { recursive: true });
+  try {
+    fs.cpSync(sourceDir, stagingDir, { recursive: true });
+    fs.rmSync(targetDir, { recursive: true, force: true });
+    fs.renameSync(stagingDir, targetDir);
+  } catch (error) {
+    fs.rmSync(stagingDir, { recursive: true, force: true });
+    throw error;
+  }
+
+  return { sourceDir, targetDir };
+}
+
+export function uninstallCodexPet({ homeDir = os.homedir(), codexHome = null } = {}) {
+  const targetDir = getCodexPetInstallPath({ homeDir, codexHome });
+  const existed = fs.existsSync(targetDir);
+  fs.rmSync(targetDir, { recursive: true, force: true });
+  return { targetDir, existed };
+}

package/src/core/presentation.mjs

@@ -93,6 +93,7 @@ const RECEIPT_COPY = {
     scope: {
       latest: "最近一次会话",
       session: "指定会话",
+      "last-hours": "最近 {hours} 小时",
       today: "今日全部会话",
       "last-7-days": "最近 7 个自然日",
       "this-week": "本周全部会话",
@@ -133,6 +134,12 @@ const RECEIPT_COPY = {
     openMiniProgramHint: "微信扫码进入 AI 打工图鉴",
     importData: "2 · 扫描导入数据",
     importDataHint: "在小程序里点击“从电脑导入”后扫描",
+    multipartOpenTitle: "先打开小程序",
+    multipartOpenHint: "数据码将在 {seconds} 秒后自动开始轮播，无需点击电脑",
+    multipartTransferTitle: "保持手机对准屏幕",
+    multipartTransferHint: "数据码会自动逐张轮播；漏扫或重复都没关系",
+    multipartPartLabel: "数据分片 {current}/{total}",
+    multipartRestart: "重新显示小程序码",
     dataQrAlt: "当前小票数据二维码",
     miniProgramAlt: "微信小程序码",
     placeholderLabel: "小程序码",
@@ -159,6 +166,7 @@ const RECEIPT_COPY = {
     scope: {
       latest: "Latest session",
       session: "Selected session",
+      "last-hours": "Last {hours} hours",
       today: "All sessions today",
       "last-7-days": "Last 7 calendar days",
       "this-week": "All sessions this week",
@@ -199,6 +207,12 @@ const RECEIPT_COPY = {
     openMiniProgramHint: "Scan with WeChat to open AI Work Archive",
     importData: "2 · Import receipt data",
     importDataHint: "Tap “从电脑导入小票” in the mini program, then scan this code",
+    multipartOpenTitle: "Open the mini program first",
+    multipartOpenHint: "The data codes will start rotating automatically in {seconds}s. No desktop click is required.",
+    multipartTransferTitle: "Keep your phone pointed at the screen",
+    multipartTransferHint: "Data codes rotate automatically. Missed or duplicate scans are safe.",
+    multipartPartLabel: "Data part {current}/{total}",
+    multipartRestart: "Show mini-program code again",
     dataQrAlt: "Current receipt data QR code",
     miniProgramAlt: "WeChat mini-program code",
     placeholderLabel: "Mini program",
@@ -213,6 +227,7 @@ const COMPENSATION_COPY = {
   "zh-CN": {
     latest: "本单工资",
     session: "本单工资",
+    "last-hours": "本段工资",
     today: "本日工资",
     "last-7-days": "近七日工资",
     "this-week": "本周工资",
@@ -222,6 +237,7 @@ const COMPENSATION_COPY = {
   en: {
     latest: "SHIFT PAY",
     session: "SHIFT PAY",
+    "last-hours": "WINDOW PAY",
     today: "TODAY'S PAY",
     "last-7-days": "7-DAY PAY",
     "this-week": "THIS WEEK'S PAY",
@@ -250,6 +266,11 @@ export function getReceiptCopy(locale = DEFAULT_LOCALE) {
   return RECEIPT_COPY[SUPPORTED_LOCALES.has(locale) ? locale : DEFAULT_LOCALE];
 }
 
+export function getScopeLabel(scope, locale = DEFAULT_LOCALE, hours = null) {
+  const template = getReceiptCopy(locale).scope[scope] || getReceiptCopy(locale).scope.latest;
+  return String(template).replaceAll("{hours}", String(hours || 3));
+}
+
 export function buildCompensation(scope, amount, locale = DEFAULT_LOCALE) {
   const copy = COMPENSATION_COPY[SUPPORTED_LOCALES.has(locale) ? locale : DEFAULT_LOCALE];
   return {

package/src/core/range.mjs

@@ -3,6 +3,7 @@ import { dateKey } from "../lib/time.mjs";
 export const RECEIPT_SCOPES = new Set([
   "latest",
   "session",
+  "last-hours",
   "today",
   "last-7-days",
   "this-week",
@@ -11,6 +12,8 @@ export const RECEIPT_SCOPES = new Set([
 const SCOPE_ALIASES = new Map([
   ["latest", "latest"],
   ["session", "session"],
+  ["hours", "last-hours"],
+  ["last-hours", "last-hours"],
   ["today", "today"],
   ["7d", "last-7-days"],
   ["last-7-days", "last-7-days"],
@@ -38,7 +41,13 @@ function mondayDateKey(value) {
   return shiftDateKey(value, -daysSinceMonday);
 }
 
-export function resolveRange(scope, timezone, now = new Date(), sessionId = null) {
+function floorToMinute(value) {
+  const date = new Date(value);
+  date.setUTCSeconds(0, 0);
+  return date;
+}
+
+export function resolveRange(scope, timezone, now = new Date(), sessionId = null, hours = null) {
   const normalizedScope = normalizeScope(scope);
   if (!normalizedScope || !RECEIPT_SCOPES.has(normalizedScope)) {
     throw new Error(`不支持的统计范围：${scope}`);
@@ -47,8 +56,20 @@ export function resolveRange(scope, timezone, now = new Date(), sessionId = null
   const targetDate = dateKey(now, timezone);
   let startDate = null;
   let endDate = null;
+  let startAt = null;
+  let endAt = null;
+  let windowHours = null;
 
-  if (normalizedScope === "today") {
+  if (normalizedScope === "last-hours") {
+    windowHours = Number(hours ?? 3);
+    if (!Number.isInteger(windowHours) || windowHours < 1 || windowHours > 168) {
+      throw new Error("最近小时数必须是 1 至 168 之间的整数");
+    }
+    endAt = floorToMinute(now);
+    startAt = new Date(endAt.getTime() - windowHours * 60 * 60 * 1000);
+    startDate = dateKey(startAt, timezone);
+    endDate = dateKey(endAt, timezone);
+  } else if (normalizedScope === "today") {
     startDate = targetDate;
     endDate = targetDate;
   } else if (normalizedScope === "last-7-days") {
@@ -65,6 +86,9 @@ export function resolveRange(scope, timezone, now = new Date(), sessionId = null
     targetDate,
     startDate,
     endDate,
+    startAt,
+    endAt,
+    hours: windowHours,
     sessionId: sessionId || null,
   };
 }
@@ -73,8 +97,15 @@ export function isCalendarScope(scope) {
   return scope === "today" || scope === "last-7-days" || scope === "this-week";
 }
 
+export function isTimeWindowScope(scope) {
+  return scope === "last-hours";
+}
+
 export function isDateInRange(date, range) {
   if (!date) return false;
+  if (isTimeWindowScope(range.scope)) {
+    return date >= range.startAt && date <= range.endAt;
+  }
   if (!isCalendarScope(range.scope)) return true;
   const key = dateKey(date, range.timezone);
   return key >= range.startDate && key <= range.endDate;
@@ -107,6 +138,13 @@ export function outputSlugForRange(range, receiptId = "") {
   const endDate = range?.endDate || range?.targetDate || startDate;
 
   if (scope === "today") return `today-${safeSlugSegment(endDate, "today")}`;
+  if (scope === "last-hours") {
+    const endAt = range?.endAt instanceof Date ? range.endAt : new Date(range?.endAt || 0);
+    const endStamp = Number.isNaN(endAt.getTime())
+      ? safeSlugSegment(endDate, "window")
+      : endAt.toISOString().replace(/[-:]/g, "").slice(0, 13);
+    return `last-${Number(range?.hours || 3)}-hours-${safeSlugSegment(endStamp, "window")}`;
+  }
   if (scope === "last-7-days" || scope === "this-week") {
     const dateSpan = startDate === endDate ? endDate : `${startDate}-to-${endDate}`;
     return `${scope}-${safeSlugSegment(dateSpan, scope)}`;

package/src/core/receipt-record.mjs

@@ -4,7 +4,11 @@ import os from "node:os";
 import path from "node:path";
 
 import { canonicalStringify, sha256Hex } from "./canonical.mjs";
-import { buildLogicalReceiptKey, buildProtocolReceiptId } from "./fact-identity.mjs";
+import {
+  buildLogicalReceiptKey,
+  buildProtocolReceiptId,
+  buildSummaryReceiptId,
+} from "./fact-identity.mjs";
 import {
   buildCompensation,
   DEFAULT_LOCALE,
@@ -22,7 +26,12 @@ function fingerprintSessionIds(sessionIds) {
 export function buildReceiptRecord(metrics, defaultTheme = "classic", locale = DEFAULT_LOCALE, canonical = {}) {
   const sessionFingerprint = fingerprintSessionIds(metrics.sessionIds);
   const logicalKey = buildLogicalReceiptKey(metrics);
-  const id = buildProtocolReceiptId(SOURCE_VERSION, logicalKey);
+  const summaryOnly = metrics.mode === "last-hours";
+  const schemaVersion = summaryOnly ? 1 : SCHEMA_VERSION;
+  const sourceVersion = summaryOnly ? "cwr1" : SOURCE_VERSION;
+  const id = summaryOnly
+    ? buildSummaryReceiptId(logicalKey)
+    : buildProtocolReceiptId(SOURCE_VERSION, logicalKey);
   const snapshotHash = sha256Hex({
     start: metrics.startAt.toISOString(),
     end: metrics.endAt.toISOString(),
@@ -33,6 +42,8 @@ export function buildReceiptRecord(metrics, defaultTheme = "classic", locale = D
     scope: metrics.mode,
     rangeStartDate: metrics.rangeStartDate,
     rangeEndDate: metrics.rangeEndDate,
+    windowStartAt: metrics.windowStartAt?.toISOString() || null,
+    windowEndAt: metrics.windowEndAt?.toISOString() || null,
   });
   const workProfileId = metrics.workProfileId || "temporary-hire";
   const workProfile = getWorkProfileCopy(workProfileId, locale);
@@ -59,23 +70,24 @@ export function buildReceiptRecord(metrics, defaultTheme = "classic", locale = D
     manifest_hash: sha256Hex(canonicalStringify(manifestCore)),
   };
 
-  return {
-    schema_version: SCHEMA_VERSION,
+  const record = {
+    schema_version: schemaVersion,
     locale,
     id,
     generated_at: new Date().toISOString(),
     source: {
       type: "codex",
-      version: SOURCE_VERSION,
+      version: sourceVersion,
       scope: metrics.mode,
+      hours: metrics.windowHours || null,
       collector_version: COLLECTOR_VERSION,
       logical_key: logicalKey,
       session_fingerprint: sessionFingerprint,
       snapshot_hash: snapshotHash,
     },
     period: {
-      start_at: metrics.startAt.toISOString(),
-      end_at: metrics.endAt.toISOString(),
+      start_at: (metrics.windowStartAt || metrics.startAt).toISOString(),
+      end_at: (metrics.windowEndAt || metrics.endAt).toISOString(),
       timezone: metrics.timezone,
       range_start_date: metrics.rangeStartDate,
       range_end_date: metrics.rangeEndDate,
@@ -107,9 +119,12 @@ export function buildReceiptRecord(metrics, defaultTheme = "classic", locale = D
       contains_paths: false,
       contains_filenames: false,
     },
-    manifest,
-    facts,
   };
+  if (!summaryOnly) {
+    record.manifest = manifest;
+    record.facts = facts;
+  }
+  return record;
 }
 
 export function persistReceiptRecord(record, outputHtmlPath, requestedDataDir = null) {

package/src/core/selector.mjs

@@ -37,21 +37,23 @@ export async function promptForRange({ locale, timezone, loadRecentSessions }) {
   try {
     console.log(isEnglish ? "\nChoose a receipt range:\n" : "\n请选择小票统计范围：\n");
     console.log(isEnglish ? "1. All activity today (recommended)" : "1. 今天全部活动（推荐）");
-    console.log(isEnglish ? "2. Last 7 calendar days" : "2. 最近 7 个自然日");
-    console.log(isEnglish ? "3. This week (Monday to now)" : "3. 本周（周一至今）");
-    console.log(isEnglish ? "4. Choose a specific session" : "4. 选择一个具体会话");
+    console.log(isEnglish ? "2. Last 3 hours" : "2. 最近 3 小时");
+    console.log(isEnglish ? "3. Last 7 calendar days" : "3. 最近 7 个自然日");
+    console.log(isEnglish ? "4. This week (Monday to now)" : "4. 本周（周一至今）");
+    console.log(isEnglish ? "5. Choose a specific session" : "5. 选择一个具体会话");
 
     const choice = await askForNumber(
       readline,
-      isEnglish ? "\nEnter 1–4 (default 1): " : "\n请输入 1–4（默认 1）：",
+      isEnglish ? "\nEnter 1–5 (default 1): " : "\n请输入 1–5（默认 1）：",
       1,
-      4,
+      5,
       1,
     );
 
     if (choice === 1) return { mode: "today", sessionId: null };
-    if (choice === 2) return { mode: "last-7-days", sessionId: null };
-    if (choice === 3) return { mode: "this-week", sessionId: null };
+    if (choice === 2) return { mode: "last-hours", sessionId: null, hours: 3 };
+    if (choice === 3) return { mode: "last-7-days", sessionId: null };
+    if (choice === 4) return { mode: "this-week", sessionId: null };
 
     const sessions = await loadRecentSessions();
     if (!sessions.length) throw new Error(isEnglish ? "No Codex sessions found" : "没有找到可选择的 Codex 会话");