codex-work-receipt 0.6.1 → 0.7.1

package/CHANGELOG.md

@@ -1,6 +1,17 @@
 # Changelog
 
-## Unreleased
+## 0.7.1 - 2026-07-19
+
+- 修正 HTML 长图导出：PNG 只保留完整小票和微信小程序码，不再包含数据二维码或分片数据码。
+
+## 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">
@@ -24,9 +24,19 @@ Codex Work Receipt summarizes turns, tool calls, Tokens, duration, and models, t
 
 Version `0.6.0` uses the cwr2 protocol to create stable privacy-safe facts for each session and calendar day. Overlapping today, last-seven-days, and this-week receipts can be deduplicated by the receiver, and oversized payloads are automatically split into reorderable multipart QR codes that rotate one at a time in the HTML so the camera never sees multiple data codes at once.
 
+## Meet Ticket Buddy
+
+<p align="center">
+  <a href="docs/codex-pet.en.md"><img src="docs/images/codex-pet-showcase.png" alt="Ticket Buddy in idle, working, needs-input, ready, and failed states" width="920"></a>
+</p>
+
+<p align="center">
+  <sub>Ticket Buddy changes expression as Codex becomes idle, runs a task, needs input, finishes, or gets blocked. Select the image for setup and state details.</sub>
+</p>
+
 ## 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 +48,29 @@ Summarize all Codex activity from today:
 npx codex-work-receipt@latest --today --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).
+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 only the full receipt and WeChat mini-program code; data QR codes are excluded. 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 +90,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">
@@ -24,9 +24,19 @@
 
 `0.6.0` 使用 cwr2 协议，按“会话 × 自然日”生成稳定的脱敏事实。今日、近 7 日和本周小票即使范围重叠，接收端也能识别相同工作；数据过大时会自动生成多张可重组的分片二维码，并在 HTML 中逐张自动轮播，避免镜头同时识别多个数据码。
 
+## 认识票仔
+
+<p align="center">
+  <a href="docs/codex-pet.md"><img src="docs/images/codex-pet-showcase.png" alt="票仔 AI 小票工的待机、打工、等待确认、完成和失败状态" width="920"></a>
+</p>
+
+<p align="center">
+  <sub>票仔会跟随 Codex 的空闲、执行、等待确认、完成和失败状态切换表情。点击图片查看安装与状态说明。</sub>
+</p>
+
 ## Quickstart
 
-需要 Node.js 20 或更高版本，并且本机已经使用过 Codex。无需克隆仓库，运行后选择“今天 / 近 7 日 / 本周 / 指定会话”：
+需要 Node.js 20 或更高版本，并且本机已经使用过 Codex。无需克隆仓库，运行后选择“今天 / 最近 3 小时 / 近 7 日 / 本周 / 指定会话”：
 
 ```bash
 npx codex-work-receipt@latest
@@ -38,11 +48,29 @@ npx codex-work-receipt@latest
 npx codex-work-receipt@latest --today
 ```
 
-网页和结构数据默认保存在 `./codex-work-receipt-output/`。生成的网页支持一键保存包含主小票和二维码导入联的高清长图。也可以继续使用 `--latest`、`--today` 等非交互参数，详见 [CLI 使用文档](docs/cli.md)。
+查看最近 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 +90,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
@@ -79,7 +87,7 @@ Default output:
 
 Default filenames include the calendar range. Latest-session and selected-session receipts include a short identifier so receipts from different dates or sessions do not overwrite one another.
 
-Open the generated HTML and click “Save full PNG” to download a high-resolution image. It includes the main receipt, mini-program code, and data QR import stub in the currently selected theme. Theme controls, the page background, and the footer note are excluded. With one data QR, the mini-program code and data code remain side by side. When cwr2 exceeds the safe capacity of one QR code, the page shows the mini-program code first and then rotates multipart data codes one at a time without desktop clicks. The full PNG still includes every numbered part so the offline payload remains complete.
+Open the generated HTML and click “Save full PNG” to download a high-resolution image. It contains only the complete main receipt and WeChat mini-program code in the currently selected theme. Data QR codes, multipart data codes, theme controls, the page background, and the footer note are excluded. The HTML page still presents data codes normally: a single code stays beside the mini-program code, while oversized cwr2 payloads rotate their parts after the mini program has been opened so they can be imported on the phone.
 
 Set a timezone and output path:
 
@@ -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
@@ -79,7 +87,7 @@ npx codex-work-receipt@latest --latest --theme diner
 
 默认文件名会携带统计日期范围；最近会话和指定会话则携带短编号，避免不同日期或会话的小票互相覆盖。
 
-打开生成的 HTML 后，点击“保存完整长图”即可下载高清 PNG。图片包含主小票、小程序码和数据二维码导入联，并自动使用当前选择的主题；主题按钮、网页背景和底部说明不会进入图片。只有一个数据二维码时，小程序码与数据码继续并排展示。cwr2 数据超过单码安全容量时，网页先单独展示小程序码，随后自动逐张轮播分片数据码；用户无需在电脑上切换上一张或下一张，但仍需在小程序中收齐全部分片。完整长图为保留离线数据，会继续包含全部带序号的分片二维码。
+打开生成的 HTML 后，点击“保存完整长图”即可下载高清 PNG。图片只包含完整主小票和微信小程序码，并自动使用当前选择的主题；数据二维码、分片数据码、主题按钮、网页背景和底部说明都不会进入图片。网页本身仍会正常展示数据二维码：单码时与小程序码并排，cwr2 超出单码安全容量时则在打开小程序后自动逐张轮播分片数据码，供用户在小程序中完成导入。
 
 指定时区和输出路径：
 
@@ -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.1",
   "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);