codex-work-receipt 0.3.0 → 0.5.0

package/docs/cli.md

@@ -0,0 +1,137 @@
+# CLI 使用
+
+<p><strong>中文</strong> · <a href="./cli.en.md">English</a> · <a href="../README.md">返回 README</a></p>
+
+## 环境要求
+
+- Node.js 20 或更高版本
+- 本机已经使用过 Codex，并存在 `~/.codex/sessions/` 会话记录
+
+无需克隆仓库或全局安装。
+
+## 交互选择统计范围
+
+直接运行：
+
+```bash
+npx codex-work-receipt@latest
+```
+
+命令行会让你选择：今天全部活动、最近 7 个自然日、本周，或最近的某个具体会话。选择具体会话时会展示起止时间、轮次、工具调用和模型，帮助辨认。
+
+## 非交互统计范围
+
+统计最近一次活跃会话，并自动打开小票：
+
+```bash
+npx codex-work-receipt@latest --latest
+```
+
+汇总本地时区今天发生的全部 Codex 活动：
+
+```bash
+npx codex-work-receipt@latest --today
+```
+
+最近 7 个自然日（含今天）：
+
+```bash
+npx codex-work-receipt@latest --range last-7-days
+```
+
+本周周一至今：
+
+```bash
+npx codex-work-receipt@latest --range this-week
+```
+
+## 语言与主题
+
+生成英文小票：
+
+```bash
+npx codex-work-receipt@latest --latest --lang en
+```
+
+选择默认主题：
+
+```bash
+npx codex-work-receipt@latest --latest --theme diner
+```
+
+可用主题：
+
+- `classic`：经典白票
+- `diner`：复古粉票
+- `payroll`：夜班绿票
+
+网页生成后仍然可以即时切换主题，统计口径不会改变。
+
+## 输出文件
+
+默认输出：
+
+```text
+./codex-work-receipt-output/
+├── codex-receipt-today-2026-07-18.html
+└── codex-receipt-today-2026-07-18.json
+```
+
+默认文件名会携带统计日期范围；最近会话和指定会话则携带短编号，避免不同日期或会话的小票互相覆盖。
+
+打开生成的 HTML 后，点击“保存完整长图”即可下载高清 PNG。图片包含主小票、小程序码和数据二维码导入联，并自动使用当前选择的主题；主题按钮、网页背景和底部说明不会进入图片。
+
+指定时区和输出路径：
+
+```bash
+npx codex-work-receipt@latest --today \
+  --timezone Asia/Shanghai \
+  --output ./my-receipt.html
+```
+
+只生成文件，不自动打开浏览器：
+
+```bash
+npx codex-work-receipt@latest --latest --no-open
+```
+
+## 全部参数
+
+| 参数 | 说明 |
+| --- | --- |
+| `--range <name>` | `latest`、`today`、`last-7-days` 或 `this-week` |
+| `--latest` | 统计最近活跃的 Codex 会话，默认模式 |
+| `--today` | 汇总指定时区今天发生的 Codex 活动 |
+| `--session <id>` | 统计指定的 Codex 会话 |
+| `--timezone <name>` | 指定 IANA 时区，例如 `Asia/Shanghai` |
+| `--lang <name>` | `zh-CN`（默认）或 `en` |
+| `--theme <name>` | `classic`、`diner` 或 `payroll` |
+| `--output <file>` | 指定 HTML 输出路径 |
+| `--data-dir <directory>` | 指定本地结构历史目录 |
+| `--install-skill` | 安装 AI 打工小票 Codex Skill |
+| `--no-open` | 生成后不自动打开浏览器 |
+
+也可以随时运行：
+
+```bash
+npx codex-work-receipt@latest --help
+```
+
+## 本地历史
+
+每次运行会生成或更新：
+
+- `codex-work-receipt-output/codex-receipt-*.html`：可切换主题的小票网页
+- `codex-work-receipt-output/codex-receipt-*.json`：当前小票的版本化结构数据
+- `~/.codex-work-receipt/receipts/*.json`：本机历史快照
+- `~/.codex-work-receipt/latest.json`：最近生成的小票
+- `~/.codex-work-receipt/history.jsonl`：去重后的本地历史
+
+结构说明见 [数据结构与二维码协议](data-schema.md)。
+
+## 当前限制
+
+- 当前只支持 Codex；Cursor、WorkBuddy 等数据源仍在规划中
+- 暂不统计修改文件数和代码行数，避免不同工具调用方式产生误导
+- 时间范围按每条事件的本地日期筛选，并分别计算每个会话的 Token 区间增量
+- 桌面网页导出 PNG 使用浏览器本地渲染，不上传小票数据

package/docs/codex-skill.en.md

@@ -0,0 +1,45 @@
+# Codex Skill
+
+<p><a href="./codex-skill.md">中文</a> · <strong>English</strong> · <a href="../README.en.md">Back to README</a></p>
+
+AI Work Receipt includes a Codex Skill that converts natural-language requests into the appropriate CLI options.
+
+## Install
+
+```bash
+npx codex-work-receipt@latest --install-skill --lang en
+```
+
+The skill is installed at:
+
+```text
+~/.agents/skills/ai-work-receipt/
+```
+
+It does not modify the current repository. Restart Codex if the current session does not detect the newly installed skill.
+
+## Use
+
+After installation, ask Codex:
+
+> Create an AI work receipt for my latest Codex session.
+
+> Generate today's AI work receipt with the diner theme.
+
+> 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.
+
+You can also invoke the skill explicitly with `$ai-work-receipt`.
+
+## Update
+
+Run the installation command again to safely replace an older version:
+
+```bash
+npx codex-work-receipt@latest --install-skill --lang en
+```

package/docs/codex-skill.md

@@ -0,0 +1,45 @@
+# Codex Skill
+
+<p><strong>中文</strong> · <a href="./codex-skill.en.md">English</a> · <a href="../README.md">返回 README</a></p>
+
+AI 打工小票内置了一个 Codex Skill，让 Codex 可以根据自然语言替你选择参数并运行 CLI。
+
+## 安装
+
+```bash
+npx codex-work-receipt@latest --install-skill
+```
+
+Skill 会安装到：
+
+```text
+~/.agents/skills/ai-work-receipt/
+```
+
+它不会修改当前代码仓库。如果当前会话没有识别到新 Skill，请重启 Codex。
+
+## 使用
+
+安装后可以直接说：
+
+> 给刚刚这次工作开一张 AI 打工小票。
+
+> 生成我今天的 AI 打工小票，使用复古粉票。
+
+> 生成我最近七天的 AI 打工小票。
+
+> 看看本周 Codex 一共打了多少工。
+
+> 用英文生成刚刚这次工作的 AI 打工小票。
+
+Codex 会根据表达选择单次会话、今天、近七日或本周，以及语言和主题，然后执行命令并打开生成的网页。
+
+也可以通过 `$ai-work-receipt` 显式调用这个 Skill。
+
+## 更新
+
+重新运行安装命令即可安全覆盖旧版本：
+
+```bash
+npx codex-work-receipt@latest --install-skill
+```

package/docs/data-schema.en.md

@@ -0,0 +1,35 @@
+# Data schema and QR protocol
+
+<p><a href="./data-schema.md">中文</a> · <strong>English</strong> · <a href="../README.en.md">Back to README</a></p>
+
+The current schema version is `1`. Each generation saves a structured receipt record locally.
+
+## Main fields
+
+- `schema_version`: schema version
+- `locale`: desktop receipt language, `zh-CN` or `en`
+- `id`: anonymous ID derived from the metrics snapshot
+- `generated_at`: generation time
+- `source`: data source, selected `scope`, and collector version
+- `period`: actual activity times, timezone, and `range_start_date` / `range_end_date` calendar boundaries
+- `stats`: turns, messages, tools, Tokens, duration, and related metrics
+- `presentation`: default theme, language-neutral `work_profile`, localized role, review, and AI work points
+- `privacy`: explicit declaration of excluded sensitive content
+
+The `id` remains stable for the same session, day, or calendar-boundary pair. Regeneration updates the record rather than creating duplicate history. `source.snapshot_hash` detects metric changes.
+
+## QR format
+
+The QR payload uses compact fields:
+
+```text
+cwr1.<checksum>.<Base64URL of deflateRaw(JSON)>
+```
+
+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.
+
+`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.
+
+See [mobile QR import](mobile-import.en.md).

package/docs/data-schema.md

@@ -1,25 +1,35 @@
-# Receipt data schema
+# 数据结构与二维码协议
+
+<p><strong>中文</strong> · <a href="./data-schema.en.md">English</a> · <a href="../README.md">返回 README</a></p>
 
 当前结构版本为 `1`。每次生成都会在本机保存一份结构记录。
 
-主要字段：
+## 主要字段
 
 - `schema_version`：结构版本
-- `locale`：当前桌面小票语言，支持 `zh-CN` 和 `en`
-- `id`：根据统计快照生成的匿名ID
+- `locale`：桌面小票语言，支持 `zh-CN` 和 `en`
+- `id`：根据统计快照生成的匿名 ID
 - `generated_at`：生成时间
-- `source`：数据来源和统计范围
-- `period`：开始、结束和时区
+- `source`：数据来源、`scope` 统计范围和采集器版本
+- `period`：实际活动起止时间、时区，以及 `range_start_date` / `range_end_date` 自然日边界
 - `stats`：轮次、消息、工具、Token、时长等统计
 - `presentation`：默认主题、语言无关的 `work_profile`、本地化工种、点评和 AI 工分
 - `privacy`：明确声明不包含的敏感内容
 
-同一个最近会话、或同一天的 `id` 保持稳定；重复生成会更新该记录，而不是不断制造重复历史。`source.snapshot_hash` 用于识别统计内容是否发生变化。
+同一个会话、同一天或同一组自然日边界的 `id` 保持稳定；重复生成会更新该记录。`source.snapshot_hash` 用于识别统计内容是否发生变化。
+
+## 二维码格式
 
-二维码使用精简字段，并采用以下格式：
+二维码使用精简字段：
 
 ```text
 cwr1.<checksum>.<deflateRaw(JSON) 的 Base64URL>
 ```
 
-二维码中的 `presentation.compensation` 为娱乐化 AI 工分，不代表真实 API 费用。为兼容当前中文小程序，二维码中的展示文案继续使用中文，同时通过精简字段 `l` 和 `r` 携带桌面语言及工种语义 ID；英文 HTML 和本地 JSON 不受影响。小程序应先检查前缀和校验值，再解析数据。未来结构升级通过 `v` 字段兼容。
+小程序应检查前缀和校验值，再解压并解析数据。未来结构升级通过 `v` 字段兼容。
+
+精简字段 `o` 显式携带 `latest`、`session`、`today`、`last-7-days` 或 `this-week`；`d[3]` 和 `d[4]` 携带自然日边界。新增字段保持 `cwr1` 和结构版本 `1`，旧二维码仍可由新版小程序导入。
+
+`presentation.compensation` 是娱乐化 AI 工分，不代表真实 API 费用。为兼容当前中文小程序，二维码展示文案继续使用中文，并通过精简字段 `l` 和 `r` 携带桌面语言及工种语义 ID；英文 HTML 和本地 JSON 不受影响。
+
+手机端流程见 [手机扫码导入](mobile-import.md)。

package/docs/images/social-preview-source.svg

@@ -0,0 +1,84 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="1280" height="640" viewBox="0 0 1280 640">
+  <defs>
+    <pattern id="grid" width="32" height="32" patternUnits="userSpaceOnUse">
+      <path d="M32 0H0V32" fill="none" stroke="#42CDA7" stroke-opacity="0.09" stroke-width="1"/>
+    </pattern>
+    <filter id="shadow" x="-30%" y="-30%" width="160%" height="180%">
+      <feDropShadow dx="0" dy="16" stdDeviation="18" flood-color="#15342C" flood-opacity="0.19"/>
+    </filter>
+    <clipPath id="classicClip"><rect x="0" y="0" width="240" height="320" rx="6"/></clipPath>
+    <clipPath id="dinerClip"><rect x="0" y="0" width="240" height="320" rx="6"/></clipPath>
+    <clipPath id="payrollClip"><rect x="0" y="0" width="240" height="320" rx="6"/></clipPath>
+  </defs>
+
+  <rect width="1280" height="640" fill="#F5F1E8"/>
+  <rect width="1280" height="640" fill="url(#grid)"/>
+  <circle cx="1040" cy="310" r="288" fill="#42CDA7" fill-opacity="0.12"/>
+  <circle cx="1120" cy="116" r="86" fill="#F2A7B6" fill-opacity="0.19"/>
+
+  <g font-family="-apple-system, BlinkMacSystemFont, 'PingFang SC', 'Microsoft YaHei', Arial, sans-serif">
+    <rect x="68" y="70" width="216" height="40" rx="20" fill="#17231F"/>
+    <text x="176" y="96" text-anchor="middle" fill="#F8F4EA" font-size="16" font-weight="700" letter-spacing="1.6">OPEN SOURCE · v0.3.0</text>
+
+    <text x="68" y="210" fill="#17231F" font-size="70" font-weight="800" letter-spacing="-2">Codex AI</text>
+    <text x="68" y="292" fill="#17231F" font-size="76" font-weight="800" letter-spacing="-2">打工小票</text>
+
+    <rect x="68" y="326" width="62" height="6" rx="3" fill="#42CDA7"/>
+    <text x="68" y="376" fill="#41514B" font-size="25" font-weight="500">把本机 Codex 的工作记录，</text>
+    <text x="68" y="414" fill="#41514B" font-size="25" font-weight="500">开成一张可以带走的小票。</text>
+
+    <rect x="68" y="468" width="590" height="72" rx="14" fill="#17231F"/>
+    <circle cx="101" cy="504" r="7" fill="#42CDA7"/>
+    <text x="124" y="512" fill="#F8F4EA" font-size="21" font-family="SFMono-Regular, Menlo, Monaco, Consolas, monospace">npx codex-work-receipt@latest --latest</text>
+    <text x="68" y="580" fill="#65736E" font-size="16" font-weight="600" letter-spacing="0.7">LOCAL-FIRST · PRIVACY-FIRST · BILINGUAL</text>
+  </g>
+
+  <g filter="url(#shadow)" transform="translate(758 104) rotate(-8 120 160)" font-family="Menlo, Monaco, Consolas, monospace">
+    <rect width="240" height="320" rx="6" fill="#FFFEFA"/>
+    <text x="120" y="38" text-anchor="middle" fill="#17231F" font-size="15" font-weight="700">AI WORK RECEIPT</text>
+    <text x="120" y="57" text-anchor="middle" fill="#65736E" font-size="8" letter-spacing="1.4">CODEX · LOCAL SHIFT</text>
+    <path d="M24 76H216M24 100H216M24 168H216M24 222H216" stroke="#17231F" stroke-width="1" stroke-dasharray="4 3"/>
+    <text x="25" y="92" fill="#17231F" font-size="9">SESSION</text><text x="215" y="92" text-anchor="end" fill="#17231F" font-size="9">#0037</text>
+    <text x="25" y="121" fill="#65736E" font-size="8">ROUNDS</text><text x="215" y="121" text-anchor="end" fill="#17231F" font-size="10">42</text>
+    <text x="25" y="143" fill="#65736E" font-size="8">TOOL CALLS</text><text x="215" y="143" text-anchor="end" fill="#17231F" font-size="10">118</text>
+    <text x="25" y="160" fill="#65736E" font-size="8">AI SCORE</text><text x="215" y="160" text-anchor="end" fill="#17231F" font-size="10">3,862</text>
+    <text x="25" y="192" fill="#17231F" font-size="10" font-weight="700">TODAY'S ROLE</text>
+    <text x="25" y="211" fill="#17231F" font-size="13" font-weight="700">TOOL CONDUCTOR</text>
+    <g fill="#17231F">
+      <rect x="35" y="244" width="3" height="42"/><rect x="42" y="244" width="7" height="42"/><rect x="54" y="244" width="2" height="42"/><rect x="61" y="244" width="5" height="42"/><rect x="72" y="244" width="3" height="42"/><rect x="81" y="244" width="8" height="42"/><rect x="94" y="244" width="2" height="42"/><rect x="101" y="244" width="5" height="42"/><rect x="112" y="244" width="7" height="42"/><rect x="124" y="244" width="3" height="42"/><rect x="132" y="244" width="8" height="42"/><rect x="145" y="244" width="2" height="42"/><rect x="152" y="244" width="6" height="42"/><rect x="164" y="244" width="3" height="42"/><rect x="172" y="244" width="8" height="42"/><rect x="185" y="244" width="2" height="42"/><rect x="192" y="244" width="6" height="42"/>
+    </g>
+    <text x="120" y="302" text-anchor="middle" fill="#65736E" font-size="7" letter-spacing="1">KEEP SHIPPING</text>
+  </g>
+  <g filter="url(#shadow)" transform="translate(974 86) rotate(8 120 160)" font-family="Menlo, Monaco, Consolas, monospace">
+    <rect width="240" height="320" rx="6" fill="#F5B2BF"/>
+    <rect x="18" y="18" width="204" height="284" rx="3" fill="none" stroke="#7A233D" stroke-width="2"/>
+    <text x="120" y="48" text-anchor="middle" fill="#7A233D" font-size="15" font-weight="700">LATE NIGHT DINER</text>
+    <text x="120" y="67" text-anchor="middle" fill="#7A233D" font-size="8" letter-spacing="1.2">AI SHIFT · OPEN 24/7</text>
+    <path d="M34 86H206M34 176H206M34 225H206" stroke="#7A233D" stroke-width="1" stroke-dasharray="3 3"/>
+    <text x="36" y="108" fill="#7A233D" font-size="9">PROMPT TURNS</text><text x="204" y="108" text-anchor="end" fill="#7A233D" font-size="10">28</text>
+    <text x="36" y="132" fill="#7A233D" font-size="9">TOOL ORDERS</text><text x="204" y="132" text-anchor="end" fill="#7A233D" font-size="10">96</text>
+    <text x="36" y="156" fill="#7A233D" font-size="9">OVERTIME</text><text x="204" y="156" text-anchor="end" fill="#7A233D" font-size="10">02:17</text>
+    <text x="36" y="199" fill="#7A233D" font-size="11" font-weight="700">TOTAL AI SCORE</text>
+    <text x="204" y="218" text-anchor="end" fill="#7A233D" font-size="24" font-weight="700">6,420</text>
+    <g fill="#7A233D">
+      <rect x="43" y="244" width="4" height="32"/><rect x="51" y="244" width="7" height="32"/><rect x="63" y="244" width="2" height="32"/><rect x="70" y="244" width="5" height="32"/><rect x="80" y="244" width="3" height="32"/><rect x="88" y="244" width="8" height="32"/><rect x="101" y="244" width="3" height="32"/><rect x="109" y="244" width="6" height="32"/><rect x="120" y="244" width="2" height="32"/><rect x="127" y="244" width="8" height="32"/><rect x="140" y="244" width="3" height="32"/><rect x="148" y="244" width="6" height="32"/><rect x="159" y="244" width="2" height="32"/><rect x="166" y="244" width="8" height="32"/><rect x="179" y="244" width="4" height="32"/><rect x="188" y="244" width="6" height="32"/>
+    </g>
+    <text x="120" y="291" text-anchor="middle" fill="#7A233D" font-size="7" letter-spacing="1">THANK YOU, BOSS</text>
+  </g>
+  <g filter="url(#shadow)" transform="translate(858 246) rotate(1 120 160)" font-family="Menlo, Monaco, Consolas, monospace">
+    <rect width="240" height="320" rx="6" fill="#163B32"/>
+    <text x="120" y="40" text-anchor="middle" fill="#94EACD" font-size="16" font-weight="700">AI PAYROLL</text>
+    <text x="120" y="61" text-anchor="middle" fill="#D8FFF1" font-size="8" letter-spacing="1.4">NIGHT SHIFT REPORT</text>
+    <path d="M24 80H216M24 108H216M24 182H216M24 235H216" stroke="#94EACD" stroke-opacity="0.65" stroke-width="1" stroke-dasharray="4 3"/>
+    <text x="25" y="99" fill="#D8FFF1" font-size="9">EMPLOYEE</text><text x="215" y="99" text-anchor="end" fill="#94EACD" font-size="9">GPT-5.6</text>
+    <text x="25" y="132" fill="#D8FFF1" font-size="8">TOKENS</text><text x="215" y="132" text-anchor="end" fill="#94EACD" font-size="10">284,920</text>
+    <text x="25" y="154" fill="#D8FFF1" font-size="8">TOOLS</text><text x="215" y="154" text-anchor="end" fill="#94EACD" font-size="10">137</text>
+    <text x="25" y="174" fill="#D8FFF1" font-size="8">ROUNDS</text><text x="215" y="174" text-anchor="end" fill="#94EACD" font-size="10">51</text>
+    <text x="25" y="207" fill="#D8FFF1" font-size="10">AI SCORE</text>
+    <text x="215" y="226" text-anchor="end" fill="#94EACD" font-size="27" font-weight="700">8,888</text>
+    <g fill="#94EACD">
+      <rect x="35" y="253" width="3" height="35"/><rect x="42" y="253" width="7" height="35"/><rect x="54" y="253" width="2" height="35"/><rect x="61" y="253" width="5" height="35"/><rect x="72" y="253" width="3" height="35"/><rect x="81" y="253" width="8" height="35"/><rect x="94" y="253" width="2" height="35"/><rect x="101" y="253" width="5" height="35"/><rect x="112" y="253" width="7" height="35"/><rect x="124" y="253" width="3" height="35"/><rect x="132" y="253" width="8" height="35"/><rect x="145" y="253" width="2" height="35"/><rect x="152" y="253" width="6" height="35"/><rect x="164" y="253" width="3" height="35"/><rect x="172" y="253" width="8" height="35"/><rect x="185" y="253" width="2" height="35"/><rect x="192" y="253" width="6" height="35"/>
+    </g>
+    <text x="120" y="306" text-anchor="middle" fill="#D8FFF1" font-size="7" letter-spacing="1">CLOCKED OUT</text>
+  </g>
+</svg>

package/docs/mobile-import.en.md

@@ -0,0 +1,19 @@
+# Mobile QR import
+
+<p><a href="./mobile-import.md">中文</a> · <strong>English</strong> · <a href="../README.en.md">Back to README</a></p>
+
+The desktop page shows both the fixed mini-program code and a data QR code for the current receipt. The companion mini program can complete the MVP import without a server:
+
+1. Scan the fixed mini-program code in WeChat and open the companion mini program.
+2. Tap the desktop-import action.
+3. Scan the adjacent data QR code.
+4. Validate the `cwr1` prefix, checksum, and schema version.
+5. Decompress and parse the privacy-safe metrics.
+6. Recognize a session, today, last-seven-days, or this-week range, then deduplicate by receipt ID and store it locally.
+7. Render the selected template with Canvas and save it to the phone.
+
+The QR code does not transfer an image. The desktop page and mini program independently render the same structured receipt data. Older QR codes without an explicit range field remain supported through the legacy label fallback.
+
+The companion mini program is a separate product. This repository does not contain its source code, AppID, backend code, or server credentials.
+
+See the [data schema and QR protocol](data-schema.en.md).

package/docs/mobile-import.md

@@ -1,15 +1,19 @@
-# Mobile import
+# 手机扫码导入
 
-当前桌面网页会生成真实的数据二维码，配套小程序已经支持无服务器导入：
+<p><strong>中文</strong> · <a href="./mobile-import.en.md">English</a> · <a href="../README.md">返回 README</a></p>
 
-1. 扫描固定小程序码并打开小程序。
+桌面网页会同时展示固定小程序码和当前小票的数据二维码。配套小程序无需服务器即可完成 MVP 导入：
+
+1. 微信扫描固定小程序码并打开配套小程序。
 2. 点击“从电脑导入”。
-3. 使用小程序扫码能力扫描网页右侧的数据二维码。
-4. 校验 `cwr1` 前缀、checksum 和结构版本。
-5. 解压并解析统计数据。
-6. 写入小程序本地历史，并根据小票 ID 去重。
-7. 使用 Canvas 重新绘制选定模板并保存到手机相册。
+3. 扫描网页旁边的数据二维码。
+4. 小程序校验 `cwr1` 前缀、checksum 和结构版本。
+5. 解压并解析脱敏统计数据。
+6. 识别单会话、今日、近七日或本周范围，并按小票 ID 去重写入本地历史。
+7. 使用 Canvas 重新绘制所选模板并保存到手机相册。
 
-二维码不传输图片。桌面端与小程序端分别根据同一份结构数据渲染。
+二维码不会传输图片。桌面端和小程序端根据同一份结构数据分别渲染小票；旧版二维码没有显式范围字段时仍按原有文案兼容识别。
 
 配套小程序是独立产品，本仓库不包含其源码、AppID、后台代码或服务端密钥。
+
+协议细节见 [数据结构与二维码协议](data-schema.md)。

package/docs/privacy.en.md

@@ -0,0 +1,30 @@
+# Local data and privacy
+
+<p><a href="./privacy.md">中文</a> · <strong>English</strong> · <a href="../README.en.md">Back to README</a></p>
+
+AI Work Receipt reads Codex sessions, computes metrics, and renders receipts locally.
+
+## What it reads
+
+- `~/.codex/sessions/**/*.jsonl` by default
+- Event types, timestamps, model names, and numerical metadata
+- Metrics such as turns, tool calls, Tokens, duration, and interruptions
+
+## What receipts exclude
+
+- Prompts and response text
+- Source code
+- Project paths and file names
+- API keys, account credentials, and environment variables
+
+## Where data is saved
+
+Generated HTML and JSON files are written to `codex-work-receipt-output/` by default. Deduplicated history is stored under `~/.codex-work-receipt/`. Use `--output` and `--data-dir` to change these locations.
+
+The runtime does not upload Codex session data to a project server. The initial or updated package download performed by `npx` is a normal package-manager network request and does not contain local session data.
+
+## QR payload
+
+The QR code contains versioned, privacy-safe receipt metrics only. It does not contain the original session or an image. Treat the QR code as a scannable data file and share it only with people you trust.
+
+See the [data schema and QR protocol](data-schema.en.md).

package/docs/privacy.md

@@ -1,12 +1,30 @@
-# Privacy model
+# 本地数据与隐私
 
-默认行为：
+<p><strong>中文</strong> · <a href="./privacy.en.md">English</a> · <a href="../README.md">返回 README</a></p>
 
-- 只读取 `~/.codex/sessions/**/*.jsonl`
-- 只提取事件类型、时间和数字统计
-- 不保存 Prompt、回复正文、代码、项目路径或文件名
-- 不向网络发送数据
-- 结构数据保存在 `~/.codex-work-receipt/`
+AI 打工小票在本机读取 Codex 会话，并在本机完成统计和渲染。
 
-二维码只包含当前小票的脱敏统计。二维码等同于一份可扫描的数据文件，请只向信任的人展示。
+## 会读取什么
 
+- 默认读取 `~/.codex/sessions/**/*.jsonl`
+- 提取事件类型、时间、模型名称和数字统计
+- 计算轮次、工具调用、Token、时长和中断次数等指标
+
+## 不会写入小票什么
+
+- Prompt 和回复正文
+- 源代码
+- 项目路径和文件名
+- API Key、账号凭据或环境变量
+
+## 会保存在哪里
+
+生成的 HTML 和 JSON 默认位于当前目录的 `codex-work-receipt-output/`，去重历史保存在 `~/.codex-work-receipt/`。可以使用 `--output` 和 `--data-dir` 修改位置。
+
+运行期间不会把 Codex 会话数据上传到本项目的服务器。通过 `npx` 首次下载或更新 npm 包属于包管理器的正常网络请求，不包含本地会话内容。
+
+## 二维码
+
+二维码只包含当前小票的版本化脱敏统计，不包含原始会话或图片。二维码等同于一份可扫描的数据文件，请只向信任的人展示。
+
+格式说明见 [数据结构与二维码协议](data-schema.md)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-work-receipt",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "Generate a privacy-first Codex work receipt from local session metadata.",
   "author": "a-bai-2026",
@@ -52,6 +52,7 @@
     "node": ">=20"
   },
   "dependencies": {
+    "dom-to-image-more": "^3.10.2",
     "qrcode": "^1.5.4"
   }
 }

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 or today, in Chinese or English, including requests for the classic, diner, or payroll theme. 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 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.
 ---
 
 # AI 打工小票
@@ -11,13 +11,16 @@ Use the published `codex-work-receipt` CLI as the only statistics and rendering
 
 - Use `--latest` for “刚刚”“这次”“最近一次”“上一段工作” or an unspecified request for one receipt.
 - 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.
 - Use `--theme classic` for “经典白票” or no specified theme.
 - Use `--theme diner` for “复古粉票”“粉色小票” or “diner”.
 - Use `--theme payroll` for “夜班绿票”“绿色小票” or “payroll”.
 - Add `--no-open` only when the user asks not to open the browser.
 - Add `--timezone <IANA name>` only when the user explicitly requests another timezone.
 - Use `--lang en` when the user requests English or asks for the receipt in English. Use `--lang zh-CN` otherwise.
-- If the user asks for an unsupported date range, explain that the current version supports only the latest session or today. Do not invent flags.
+- 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.
 
 ## Execute
 

package/src/cli.mjs

@@ -8,11 +8,14 @@ import QRCode from "qrcode";
 
 import { parseArgs, printHelp } from "./core/args.mjs";
 import { collectMetrics } from "./core/metrics.mjs";
+import { getReceiptCopy } from "./core/presentation.mjs";
 import { encodeReceiptPayload } 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 { formatNumber } from "./lib/time.mjs";
-import { loadCodexSessions } from "./parsers/codex.mjs";
+import { listRecentCodexSessions, loadCodexSessions } from "./parsers/codex.mjs";
 import { renderHtml } from "./renderers/html.mjs";
 
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
@@ -61,8 +64,19 @@ async function main() {
     return;
   }
 
-  const sessions = loadCodexSessions(options.mode);
-  const metrics = collectMetrics(sessions, options.mode, options.timezone);
+  if (!options.modeExplicit && process.stdin.isTTY && process.stdout.isTTY) {
+    const selected = await promptForRange({
+      locale: options.locale,
+      timezone: options.timezone,
+      loadRecentSessions: () => listRecentCodexSessions(10),
+    });
+    options.mode = selected.mode;
+    options.sessionId = selected.sessionId;
+  }
+
+  const range = resolveRange(options.mode, options.timezone, new Date(), options.sessionId);
+  const sessions = loadCodexSessions(range);
+  const metrics = collectMetrics(sessions, range);
   const record = buildReceiptRecord(metrics, options.theme, options.locale);
   const qrPayload = encodeReceiptPayload(record);
   const dataQrDataUrl = await QRCode.toDataURL(qrPayload, {
@@ -72,7 +86,10 @@ async function main() {
     color: { dark: "#171713", light: "#ffffff" },
   });
 
-  const requestedOutput = options.output || path.join(DEFAULT_OUTPUT_DIR, `codex-receipt-${options.mode}.html`);
+  const requestedOutput = options.output || path.join(
+    DEFAULT_OUTPUT_DIR,
+    `codex-receipt-${outputSlugForRange(range, record.id)}.html`,
+  );
   const outputFile = path.resolve(/\.html?$/i.test(requestedOutput) ? requestedOutput : `${requestedOutput}.html`);
   fs.mkdirSync(path.dirname(outputFile), { recursive: true });
 
@@ -89,6 +106,7 @@ 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(`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: ${qrPayload.length} characters · schema v${record.schema_version}`);
     if (!miniProgramCodeDataUrl) console.log("Mini-program code: not configured; using the explicit placeholder");
@@ -96,6 +114,7 @@ async function main() {
     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(`统计：${record.stats.completed_turns} 轮 · ${formatNumber(record.stats.tokens.total_tokens, options.locale)} Token · ${record.stats.tool_calls} 次工具调用`);
     console.log(`数据二维码：${qrPayload.length} 字符 · schema v${record.schema_version}`);
     if (!miniProgramCodeDataUrl) console.log("小程序码：尚未配置，页面使用明确占位符");