codex-work-receipt 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -1,6 +1,13 @@
 # Changelog
 
-## Unreleased
+## 0.7.0 - 2026-07-19
+
+- 新增 Codex 原生桌宠“票仔 · AI 小票工”，提供夜班绿票风格的核心状态与左右移动动画，并支持通过 `--install-pet`、`--uninstall-pet` 和 `--install-companion` 安装管理。
+- AI 打工小票 Skill 新增“票仔，开今天的票”等自然语言入口。
+- 新增 `--hours <1-168>` 滚动小时统计；“最近几个小时”默认按最近 3 小时处理。
+- 滚动小时小票使用兼容 cwr1 摘要，避免与 cwr2 的“会话 × 自然日”规范事实冲突。
+
+## 0.6.1
 
 - 将 HTML 小票底部的重复渐变装饰替换为按小票编号生成的真实 Code 128 B 条形码，并保留适合浏览器和长图导出的静区与清晰度。
 - 优化 multipart 扫码交互：单数据码继续与小程序码并排，多分片时先展示小程序码，再自动逐张轮播唯一可见的数据码，避免镜头同时识别多个二维码。

package/README.en.md

@@ -6,7 +6,7 @@
 
 <p align="center">
   <strong>Turn local Codex activity into a work receipt you can keep and share.</strong><br>
-  One command · Local-first · Chinese & English · Three themes · Mobile QR import
+  One command · Local-first · Codex pet · Three themes · Mobile QR import
 </p>
 
 <p align="center">
@@ -26,7 +26,7 @@ Version `0.6.0` uses the cwr2 protocol to create stable privacy-safe facts for e
 
 ## Quickstart
 
-Requires Node.js 20+ and local Codex session records. No clone required; choose today, the last 7 days, this week, or a specific session:
+Requires Node.js 20+ and local Codex session records. No clone required; choose today, the last 3 hours, the last 7 days, this week, or a specific session:
 
 ```bash
 npx codex-work-receipt@latest --lang en
@@ -38,11 +38,29 @@ Summarize all Codex activity from today:
 npx codex-work-receipt@latest --today --lang en
 ```
 
+Summarize the last 3 hours:
+
+```bash
+npx codex-work-receipt@latest --hours 3 --lang en
+```
+
 HTML and structured data are written to `./codex-work-receipt-output/` by default. The generated page can save a high-resolution PNG containing the full receipt and QR import stub. Non-interactive options such as `--latest` and `--today` remain available; see the [CLI guide](docs/cli.en.md).
 
 ## Ask Codex directly
 
-Install the AI Work Receipt skill once:
+Install the AI Work Receipt skill and Ticket Buddy Codex pet together:
+
+```bash
+npx codex-work-receipt@latest --install-companion --lang en
+```
+
+Restart Codex, open `Settings > Pets`, select Refresh, choose “票仔 · AI 小票工” (Ticket Buddy), and use `/pet` to wake it. Then ask:
+
+> Ticket Buddy, create today's receipt.
+
+> Ticket Buddy, create a receipt for the last three hours.
+
+To install only the skill:
 
 ```bash
 npx codex-work-receipt@latest --install-skill --lang en
@@ -62,6 +80,7 @@ The desktop page generates one or more privacy-safe data QR codes. The companion
 
 - [CLI usage and options](docs/cli.en.md)
 - [Codex Skill](docs/codex-skill.en.md)
+- [Ticket Buddy Codex pet](docs/codex-pet.en.md)
 - [Mobile QR import](docs/mobile-import.en.md)
 - [Data schema and QR protocol](docs/data-schema.en.md)
 - [Local data and privacy](docs/privacy.en.md)

package/README.md

@@ -6,7 +6,7 @@
 
 <p align="center">
   <strong>把本机 Codex 的工作记录，开成一张可以带走的 AI 打工小票。</strong><br>
-  一行命令 · 完全本地 · 中英双语 · 三种主题 · 扫码传到手机
+  一行命令 · 完全本地 · Codex 桌宠 · 三种主题 · 扫码传到手机
 </p>
 
 <p align="center">
@@ -26,7 +26,7 @@
 
 ## Quickstart
 
-需要 Node.js 20 或更高版本，并且本机已经使用过 Codex。无需克隆仓库，运行后选择“今天 / 近 7 日 / 本周 / 指定会话”：
+需要 Node.js 20 或更高版本，并且本机已经使用过 Codex。无需克隆仓库，运行后选择“今天 / 最近 3 小时 / 近 7 日 / 本周 / 指定会话”：
 
 ```bash
 npx codex-work-receipt@latest
@@ -38,11 +38,29 @@ npx codex-work-receipt@latest
 npx codex-work-receipt@latest --today
 ```
 
+查看最近 3 小时的工作：
+
+```bash
+npx codex-work-receipt@latest --hours 3
+```
+
 网页和结构数据默认保存在 `./codex-work-receipt-output/`。生成的网页支持一键保存包含主小票和二维码导入联的高清长图。也可以继续使用 `--latest`、`--today` 等非交互参数，详见 [CLI 使用文档](docs/cli.md)。
 
 ## 直接跟 Codex 说
 
-安装一次 AI 打工小票 Skill：
+一次安装 AI 打工小票 Skill 和“票仔”Codex 桌宠：
+
+```bash
+npx codex-work-receipt@latest --install-companion
+```
+
+重启 Codex 后，在 `Settings > Pets` 中点击 Refresh，选择“票仔 · AI 小票工”，再输入 `/pet` 唤醒。以后可以说：
+
+> 票仔，开今天的票。
+
+> 票仔，开最近三个小时的票。
+
+如果只想安装 Skill：
 
 ```bash
 npx codex-work-receipt@latest --install-skill
@@ -62,6 +80,7 @@ Codex 会选择统计范围和主题、执行命令并打开小票。详见 [Cod
 
 - [CLI 使用与全部参数](docs/cli.md)
 - [Codex Skill](docs/codex-skill.md)
+- [Codex 桌宠“票仔”](docs/codex-pet.md)
 - [手机扫码导入](docs/mobile-import.md)
 - [数据结构与二维码协议](docs/data-schema.md)
 - [本地数据与隐私说明](docs/privacy.md)

package/assets/codex-pet/ai-work-receipt/pet.json

@@ -0,0 +1,6 @@
+{
+  "id": "ai-work-receipt",
+  "displayName": "票仔 · AI 小票工",
+  "description": "一只陪 Codex 搬砖、完工后提醒你开票的小票工。",
+  "spritesheetPath": "spritesheet.webp"
+}

package/docs/cli.en.md

@@ -17,7 +17,7 @@ Run:
 npx codex-work-receipt@latest --lang en
 ```
 
-Choose all activity today, the last 7 calendar days, this week, or a specific recent session. Session choices include their time range, turns, tool calls, and model for identification.
+Choose all activity today, the last 3 hours, the last 7 calendar days, this week, or a specific recent session. Session choices include their time range, turns, tool calls, and model for identification.
 
 ## Non-interactive ranges
 
@@ -33,6 +33,14 @@ Summarize all Codex activity from today in your local timezone:
 npx codex-work-receipt@latest --today --lang en
 ```
 
+Summarize the last 3 hours:
+
+```bash
+npx codex-work-receipt@latest --hours 3 --lang en
+```
+
+`--hours` accepts an integer from 1 to 168 and filters exact timestamps, including windows that cross midnight. Rolling-hour receipts use the compatible cwr1 summary protocol and do not create cwr2 session-day canonical facts.
+
 Last 7 calendar days, including today:
 
 ```bash
@@ -99,7 +107,8 @@ npx codex-work-receipt@latest --latest --lang en --no-open
 
 | Option | Description |
 | --- | --- |
-| `--range <name>` | `latest`, `today`, `last-7-days`, or `this-week` |
+| `--range <name>` | `latest`, `last-hours`, `today`, `last-7-days`, or `this-week` |
+| `--hours <number>` | Summarize the last 1-168 hours |
 | `--latest` | Summarize the latest active Codex session; default mode |
 | `--today` | Summarize activity from today in the selected timezone |
 | `--session <id>` | Summarize one specific Codex session |
@@ -109,6 +118,9 @@ npx codex-work-receipt@latest --latest --lang en --no-open
 | `--output <file>` | Set the HTML output path |
 | `--data-dir <directory>` | Set the local structured-history directory |
 | `--install-skill` | Install the Codex AI Work Receipt skill |
+| `--install-pet` | Install only the Ticket Buddy Codex pet |
+| `--uninstall-pet` | Remove Ticket Buddy without deleting the skill or receipts |
+| `--install-companion` | Install both the skill and Ticket Buddy Codex pet |
 | `--no-open` | Do not open the generated page |
 
 Run the built-in help at any time:
@@ -133,5 +145,5 @@ See the [data schema and QR protocol](data-schema.en.md).
 
 - Codex is the only supported data source; Cursor and WorkBuddy are planned
 - Changed-file and line counts are intentionally omitted until they can be measured consistently
-- Calendar ranges filter individual events by local date and calculate a Token delta for each session
+- Calendar ranges filter events by local date, rolling-hour ranges use exact timestamps, and both calculate per-session Token deltas
 - Desktop PNG export is rendered locally in the browser and does not upload receipt data

package/docs/cli.md

@@ -17,7 +17,7 @@
 npx codex-work-receipt@latest
 ```
 
-命令行会让你选择：今天全部活动、最近 7 个自然日、本周，或最近的某个具体会话。选择具体会话时会展示起止时间、轮次、工具调用和模型，帮助辨认。
+命令行会让你选择：今天全部活动、最近 3 小时、最近 7 个自然日、本周，或最近的某个具体会话。选择具体会话时会展示起止时间、轮次、工具调用和模型，帮助辨认。
 
 ## 非交互统计范围
 
@@ -33,6 +33,14 @@ npx codex-work-receipt@latest --latest
 npx codex-work-receipt@latest --today
 ```
 
+最近 3 小时：
+
+```bash
+npx codex-work-receipt@latest --hours 3
+```
+
+`--hours` 支持 1～168 的整数，并按精确时间戳筛选，可以跨越午夜。滚动小时小票使用兼容的 cwr1 摘要协议，不会写入 cwr2 的“会话 × 自然日”规范事实。
+
 最近 7 个自然日（含今天）：
 
 ```bash
@@ -99,7 +107,8 @@ npx codex-work-receipt@latest --latest --no-open
 
 | 参数 | 说明 |
 | --- | --- |
-| `--range <name>` | `latest`、`today`、`last-7-days` 或 `this-week` |
+| `--range <name>` | `latest`、`last-hours`、`today`、`last-7-days` 或 `this-week` |
+| `--hours <number>` | 统计最近 1～168 小时；等价于 `last-hours` 范围 |
 | `--latest` | 统计最近活跃的 Codex 会话，默认模式 |
 | `--today` | 汇总指定时区今天发生的 Codex 活动 |
 | `--session <id>` | 统计指定的 Codex 会话 |
@@ -109,6 +118,9 @@ npx codex-work-receipt@latest --latest --no-open
 | `--output <file>` | 指定 HTML 输出路径 |
 | `--data-dir <directory>` | 指定本地结构历史目录 |
 | `--install-skill` | 安装 AI 打工小票 Codex Skill |
+| `--install-pet` | 只安装“票仔”Codex 桌宠 |
+| `--uninstall-pet` | 卸载“票仔”，不删除 Skill 或历史小票 |
+| `--install-companion` | 同时安装 Skill 和“票仔”Codex 桌宠 |
 | `--no-open` | 生成后不自动打开浏览器 |
 
 也可以随时运行：
@@ -133,5 +145,5 @@ npx codex-work-receipt@latest --help
 
 - 当前只支持 Codex；Cursor、WorkBuddy 等数据源仍在规划中
 - 暂不统计修改文件数和代码行数，避免不同工具调用方式产生误导
-- 时间范围按每条事件的本地日期筛选，并分别计算每个会话的 Token 区间增量
+- 自然日范围按本地日期筛选，滚动小时范围按精确时间戳筛选，并分别计算每个会话的 Token 区间增量
 - 桌面网页导出 PNG 使用浏览器本地渲染，不上传小票数据

package/docs/codex-pet.en.md

@@ -0,0 +1,60 @@
+# Ticket Buddy Codex Pet
+
+<p><a href="./codex-pet.md">中文</a> · <strong>English</strong> · <a href="../README.en.md">Back to README</a></p>
+
+“Ticket Buddy · AI Work Receipt” is a custom companion for Codex's native Pets feature. It is a night-green thermal receipt printer with tiny ox horns and animated idle, working, waiting, ready, failed, and review states.
+
+Ticket Buddy only presents Codex activity and provides companionship. It does not collect extra data, generate receipts automatically, or alter the current task. Receipt generation continues through the AI Work Receipt skill.
+
+## Install the skill and pet together
+
+```bash
+npx codex-work-receipt@latest --install-companion --lang en
+```
+
+After installation:
+
+1. Restart Codex.
+2. Open `Settings > Pets`.
+3. Select Refresh.
+4. Choose “票仔 · AI 小票工” (Ticket Buddy).
+5. Use `/pet` to wake it.
+
+Then ask:
+
+> Ticket Buddy, create today's receipt.
+
+> Ticket Buddy, create a receipt for the latest session.
+
+> Ticket Buddy, create a receipt for the last three hours.
+
+“The last few hours” defaults to three hours.
+
+## Install or remove only the pet
+
+```bash
+npx codex-work-receipt@latest --install-pet --lang en
+```
+
+```bash
+npx codex-work-receipt@latest --uninstall-pet --lang en
+```
+
+Removal only deletes `~/.codex/pets/ai-work-receipt/`. It leaves the skill, saved receipts, and other pets untouched.
+
+## States
+
+- Idle: quiet breathing and blinking.
+- Running: focused button work shows that Codex is executing a task.
+- Needs input: an open paw and head tilt show that Codex needs approval, a choice, or an answer.
+- Ready: the pet scans the attached receipt to show that the task is complete and waiting for review.
+- Failed or blocked: the pet looks deflated.
+- Movement: separate leftward and rightward walking loops follow its movement direction.
+
+Codex automatically controls state transitions and movement direction; a command cannot select an individual action row. A custom pet currently supplies only its name, description, and animation atlas. Selecting the pet returns to Codex or opens activity; it cannot run the receipt CLI directly.
+
+## Availability
+
+- Codex desktop app: floating companion and activity states.
+- Codex CLI: terminal pets in compatible iTerm2, Kitty Graphics, or Sixel terminals.
+- Codex IDE extension: no pet picker or floating pet overlay currently.

package/docs/codex-pet.md

@@ -0,0 +1,64 @@
+# Codex 桌宠“票仔”
+
+<p><strong>中文</strong> · <a href="./codex-pet.en.md">English</a> · <a href="../README.md">返回 README</a></p>
+
+“票仔 · AI 小票工”是 AI 打工小票为 Codex 原生 Pets 功能制作的自定义桌宠。它是一台长着小牛角的夜班绿热敏打印机，会跟随 Codex 的空闲、工作、等待、完成和失败状态切换动画。
+
+票仔只负责状态展示和陪伴，不会自动读取额外数据、生成小票或改变 Codex 的任务。开票仍然通过 AI 打工小票 Skill 完成。
+
+## 一次安装 Skill 和票仔
+
+```bash
+npx codex-work-receipt@latest --install-companion
+```
+
+安装完成后：
+
+1. 重启 Codex。
+2. 打开 `Settings > Pets`。
+3. 点击 Refresh。
+4. 选择“票仔 · AI 小票工”。
+5. 输入 `/pet` 唤醒票仔。
+
+以后可以直接说：
+
+> 票仔，开今天的票。
+
+> 票仔，开最近一个会话的票。
+
+> 票仔，开最近三个小时的票。
+
+“最近几个小时”默认表示最近 3 小时。
+
+## 只安装或卸载桌宠
+
+只安装票仔：
+
+```bash
+npx codex-work-receipt@latest --install-pet
+```
+
+卸载票仔：
+
+```bash
+npx codex-work-receipt@latest --uninstall-pet
+```
+
+卸载只会删除 `~/.codex/pets/ai-work-receipt/`，不会删除 Skill、历史小票或其他宠物。
+
+## 状态
+
+- 空闲：安静呼吸和眨眼。
+- 正在打工：专注操作打印按钮，表示 Codex 正在执行任务。
+- 等你确认：抬手并歪头等待，表示 Codex 需要批准、选择或回答。
+- 任务完成：查看票纸并左右扫视，表示任务已经完成、等待你回来查看。
+- 失败或阻塞：小票工露出沮丧表情。
+- 左右移动：根据移动方向播放对应步行动画。
+
+Codex 会自动决定状态和移动方向，不能通过命令指定播放某一行动画。当前自定义 Pet 只能提供名称、描述和动画图集；点击票仔会返回 Codex 或打开活动列表，不能改成直接运行 CLI。
+
+## 使用范围
+
+- Codex 桌面端：支持悬浮桌宠和活动状态。
+- Codex CLI：在支持 iTerm2、Kitty Graphics 或 Sixel 的终端里提供终端宠物。
+- Codex IDE 扩展：当前不提供宠物选择器或悬浮桌宠。

package/docs/codex-skill.en.md

@@ -26,16 +26,24 @@ After installation, ask Codex:
 
 > Generate today's AI work receipt with the diner theme.
 
+> Ticket Buddy, create a receipt for the last three hours.
+
+> Ticket Buddy, create a receipt for the last few hours.
+
 > Generate an AI work receipt for the last seven days.
 
 > Show how much Codex worked this week.
 
 > Create a Chinese receipt for my latest session.
 
-Codex will choose a specific session, today, the last seven days, or this week, plus the language and theme, then run the CLI and open the generated page.
+Codex will choose a specific session, the last 1-168 hours, today, the last seven days, or this week, plus the language and theme, then run the CLI and open the generated page. “The last few hours” defaults to three hours.
+
+If another Codex task is still running and you want the receipt immediately, start a separate local Codex chat. A message sent to the active chat may steer the current run or wait in its queue, depending on Follow-up behavior.
 
 You can also invoke the skill explicitly with `$ai-work-receipt`.
 
+See [Ticket Buddy Codex pet](codex-pet.en.md) for the companion setup.
+
 ## Update
 
 Run the installation command again to safely replace an older version:

package/docs/codex-skill.md

@@ -26,16 +26,24 @@ Skill 会安装到：
 
 > 生成我今天的 AI 打工小票，使用复古粉票。
 
+> 票仔，开最近三个小时的票。
+
+> 票仔，开最近几个小时的票。
+
 > 生成我最近七天的 AI 打工小票。
 
 > 看看本周 Codex 一共打了多少工。
 
 > 用英文生成刚刚这次工作的 AI 打工小票。
 
-Codex 会根据表达选择单次会话、今天、近七日或本周，以及语言和主题，然后执行命令并打开生成的网页。
+Codex 会根据表达选择单次会话、最近 1～168 小时、今天、近七日或本周，以及语言和主题，然后执行命令并打开生成的网页。“最近几个小时”默认统计最近 3 小时。
+
+如果当前 Codex 任务仍在运行，而你希望立刻查看小票，建议新开一个本地 Codex 会话再说“开今天的票”；在当前运行会话中发送的消息可能根据 Follow-up behavior 被用于 Steer 或 Queue。
 
 也可以通过 `$ai-work-receipt` 显式调用这个 Skill。
 
+桌宠安装和使用见 [Codex 桌宠“票仔”](codex-pet.md)。
+
 ## 更新
 
 重新运行安装命令即可安全覆盖旧版本：

package/docs/data-schema.en.md

@@ -32,7 +32,7 @@ cwr2p.<transferId>.<partIndex>.<partCount>.<totalChecksum>.<partChecksum>.<chunk
 
 The mini program validates the prefix and checksum before decompressing and parsing the payload. Future schema versions use the compact `v` field for compatibility.
 
-Compact field `o` explicitly carries `latest`, `session`, `today`, `last-7-days`, or `this-week`. `d[3]` and `d[4]` carry the calendar boundaries. These additive fields keep the `cwr1` prefix and schema version `1`, so the updated mini program can still import older QR codes.
+Compact field `o` explicitly carries `latest`, `session`, `last-hours`, `today`, `last-7-days`, or `this-week`. `d[3]` and `d[4]` carry date boundaries. Today, last-seven-days, and this-week receipts continue to use cwr2 canonical facts. `last-hours` is a rolling window, so it uses the compatible cwr1 summary payload to avoid colliding with session-day fact identities. The updated mini program can still import older QR codes.
 
 `presentation.compensation` contains playful AI work points, not real API cost. For compatibility with the current Chinese mini program, QR display copy remains Chinese while compact fields `l` and `r` carry the desktop locale and language-neutral role ID. English HTML and local JSON remain fully localized.
 

package/docs/data-schema.md

@@ -32,7 +32,7 @@ cwr2p.<transferId>.<partIndex>.<partCount>.<totalChecksum>.<partChecksum>.<chunk
 
 小程序应检查前缀和校验值，再解压并解析数据。未来结构升级通过 `v` 字段兼容。
 
-精简字段 `o` 显式携带 `latest`、`session`、`today`、`last-7-days` 或 `this-week`；`d[3]` 和 `d[4]` 携带自然日边界。新增字段保持 `cwr1` 和结构版本 `1`，旧二维码仍可由新版小程序导入。
+精简字段 `o` 显式携带 `latest`、`session`、`last-hours`、`today`、`last-7-days` 或 `this-week`；`d[3]` 和 `d[4]` 携带日期边界。今日、近 7 日和本周继续使用 cwr2 canonical facts。`last-hours` 是滚动时间窗，为避免与“会话 × 自然日”事实发生身份冲突，使用兼容的 cwr1 摘要载荷。旧二维码仍可由新版小程序导入。
 
 `presentation.compensation` 是娱乐化 AI 工分，不代表真实 API 费用。为兼容当前中文小程序，二维码展示文案继续使用中文，并通过精简字段 `l` 和 `r` 携带桌面语言及工种语义 ID；英文 HTML 和本地 JSON 不受影响。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-work-receipt",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "type": "module",
   "description": "Generate a privacy-first Codex work receipt from local session metadata.",
   "author": "a-bai-2026",
@@ -27,7 +27,7 @@
   "scripts": {
     "receipt": "node src/cli.mjs",
     "test": "node --test",
-    "check": "node --check src/cli.mjs && node --check src/core/skill-installer.mjs",
+    "check": "node --check src/cli.mjs && node --check src/core/skill-installer.mjs && node --check src/core/pet-installer.mjs && node --check src/core/range.mjs",
     "prepublishOnly": "npm test && npm run check"
   },
   "files": [

package/skills/ai-work-receipt/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ai-work-receipt
-description: Generate and open a privacy-first local AI work receipt from Codex session metadata. Use when the user asks Codex to create, regenerate, open, or locate an “AI 打工小票” or “AI work receipt” for the latest session, today, the last seven days, or this week, in Chinese or English. Do not use for real invoices, salary calculations, API billing, or non-Codex activity.
+description: Generate and open a privacy-first local AI work receipt from Codex session metadata. Use when the user asks Codex or 票仔 to create, regenerate, open, or locate an “AI 打工小票”, “工票”, or “AI work receipt” for the latest session, the last few hours, today, the last seven days, or this week, in Chinese or English. Do not use for real invoices, salary calculations, API billing, or non-Codex activity.
 ---
 
 # AI 打工小票
@@ -10,6 +10,9 @@ Use the published `codex-work-receipt` CLI as the only statistics and rendering
 ## Interpret the request
 
 - Use `--latest` for “刚刚”“这次”“最近一次”“上一段工作” or an unspecified request for one receipt.
+- Use `--hours <N>` for “最近 N 小时”“过去 N 小时” or “近 N 小时”. Accept integers from 1 to 168.
+- Use `--hours 3` for an unspecified “最近几个小时”“过去几个小时” request.
+- Use `--hours 12` for “最近半天”.
 - Use `--today` for “今天”“今日”“今天全部工作” or a daily summary.
 - Use `--range last-7-days` for “最近七天”“近 7 日” or a rolling seven-calendar-day summary.
 - Use `--range this-week` for “本周”“这周” or a Monday-to-now summary.
@@ -21,6 +24,7 @@ Use the published `codex-work-receipt` CLI as the only statistics and rendering
 - Use `--lang en` when the user requests English or asks for the receipt in English. Use `--lang zh-CN` otherwise.
 - If the user asks to choose interactively, run the CLI without a range flag so it can show the local selector.
 - If the user asks for an unsupported custom date range, explain the available ranges and do not invent flags.
+- Treat requests addressed to “票仔” the same as direct AI work receipt requests, for example “票仔，开今天的票”.
 
 ## Execute
 

package/skills/ai-work-receipt/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "AI 打工小票"
-  short_description: "使用自然语言生成中英文 AI 打工小票并扫码导入手机"
-  default_prompt: "使用 $ai-work-receipt 给我刚刚这次 Codex 工作生成一张 AI 打工小票。"
+  short_description: "让票仔按会话、小时或自然日生成 AI 打工小票"
+  default_prompt: "使用 $ai-work-receipt 让票仔给我刚刚这次 Codex 工作生成一张 AI 打工小票。"

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/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": "本周全部会话",
@@ -165,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",
@@ -225,6 +227,7 @@ const COMPENSATION_COPY = {
   "zh-CN": {
     latest: "本单工资",
     session: "本单工资",
+    "last-hours": "本段工资",
     today: "本日工资",
     "last-7-days": "近七日工资",
     "this-week": "本周工资",
@@ -234,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",
@@ -262,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 会话");

package/src/renderers/html.mjs

@@ -3,7 +3,12 @@ import { createRequire } from "node:module";
 
 import { buildCode128B } from "../core/barcode.mjs";
 import { formatDate, formatDuration, formatNumber, formatTime } from "../lib/time.mjs";
-import { buildCompensation, DEFAULT_LOCALE, getReceiptCopy } from "../core/presentation.mjs";
+import {
+  buildCompensation,
+  DEFAULT_LOCALE,
+  getReceiptCopy,
+  getScopeLabel,
+} from "../core/presentation.mjs";
 
 const require = createRequire(import.meta.url);
 const DOM_TO_IMAGE_SOURCE = fs.readFileSync(require.resolve("dom-to-image-more"), "utf8");
@@ -65,7 +70,7 @@ export function renderHtml({ record, dataQrDataUrl = null, dataQrDataUrls = null
   const rangeEndDate = record.period.range_end_date || formatDateKey(record.period.end_at.slice(0, 10), "zh-CN").replaceAll("/", "-");
   const isCalendarScope = new Set(["today", "last-7-days", "this-week"]).has(record.source.scope);
   const spansMultipleDates = rangeStartDate !== rangeEndDate;
-  const scopeLabel = copy.scope[record.source.scope] || copy.scope.latest;
+  const scopeLabel = getScopeLabel(record.source.scope, locale, record.source.hours);
   const dateRange = spansMultipleDates
     ? `${formatDateKey(rangeStartDate, locale)}—${formatDateKey(rangeEndDate, locale)}`
     : formatDateKey(rangeEndDate, locale);