codex-work-receipt 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.4.0
+
+- 新增无参数命令行范围选择器。
+- 新增今日、最近 7 个自然日、本周和指定会话统计。
+- 多会话汇总改为按事件时间筛选，并按会话计算 Token 区间增量。
+- 小票和二维码显式携带统计范围与自然日边界。
+- Codex Skill 支持“最近七天”和“本周”等自然语言请求。
+
 ## 0.3.0
 
 - 新增中文、英文两套完整 HTML 小票文案。

package/README.en.md

@@ -10,73 +10,33 @@
 </p>
 
 <p align="center">
+  <a href="https://www.npmjs.com/package/codex-work-receipt"><img alt="npm" src="https://img.shields.io/npm/v/codex-work-receipt?color=42CDA7"></a>
   <img alt="Node.js 20+" src="https://img.shields.io/badge/Node.js-20%2B-339933?logo=node.js&logoColor=white">
-  <img alt="Local first" src="https://img.shields.io/badge/data-local--first-17231F">
-  <img alt="Privacy first" src="https://img.shields.io/badge/privacy-no%20prompts%20or%20code-42CDA7">
+  <img alt="GPL-3.0" src="https://img.shields.io/badge/license-GPL--3.0-17231F">
+  <img alt="Local first" src="https://img.shields.io/badge/data-local--first-42CDA7">
 </p>
 
 <p align="center">
   <img src="docs/images/readme-hero.jpg" alt="Three Codex Work Receipt themes" width="920">
 </p>
 
-The tool reads timestamps and numerical metadata from local Codex sessions. Generated receipts do not contain prompts, responses, source code, project paths, or file names.
+Codex Work Receipt summarizes turns, tool calls, Tokens, duration, and models, then turns them into playful AI work points, a job title, and a review. Receipts never include prompts, responses, source code, project paths, or file names.
 
-## Sponsor
-
-<p align="center">
-  <a href="https://modelflare.dev/">
-    <img src="docs/images/sponsors/modelflare-logo.png" alt="ModelFlare Logo" width="72">
-  </a>
-</p>
-
-<p align="center">
-  <a href="https://modelflare.dev/"><strong>ModelFlare</strong></a><br>
-  <a href="https://modelflare.dev/">modelflare.dev</a><br>
-  <sub>Stable access to leading AI model APIs at a very low cost, with developer-friendly pricing, transparent billing, and clear usage visibility.</sub>
-</p>
-
-## Receipt themes
+## Quickstart
 
-<table>
-  <tr>
-    <td align="center"><strong>Classic</strong></td>
-    <td align="center"><strong>Vintage Diner</strong></td>
-    <td align="center"><strong>Night Payroll</strong></td>
-  </tr>
-  <tr>
-    <td><img src="docs/images/receipts/receipt-classic.jpg" alt="Classic work receipt" width="320"></td>
-    <td><img src="docs/images/receipts/receipt-diner.jpg" alt="Vintage diner work receipt" width="320"></td>
-    <td><img src="docs/images/receipts/receipt-payroll.jpg" alt="Night payroll work receipt" width="320"></td>
-  </tr>
-</table>
-
-## Quick start
-
-Requires Node.js 20+ and local Codex session records.
+Requires Node.js 20+ and local Codex session records. No clone required; choose today, the last 7 days, this week, or a specific session:
 
 ```bash
-npx codex-work-receipt@latest --latest --lang en
+npx codex-work-receipt@latest --lang en
 ```
 
-Summarize all Codex activity from today in your local timezone:
+Summarize all Codex activity from today:
 
 ```bash
 npx codex-work-receipt@latest --today --lang en
 ```
 
-Outputs are written to `./codex-work-receipt-output/` by default.
-
-## Desktop-to-mobile flow
-
-```text
-Local Codex sessions
-  → run one command
-  → generate an HTML receipt and data QR code
-  → scan from the companion mini program
-  → change themes, save, and share
-```
-
-The companion mini program supports QR import, local history, themes, and image export. Scan the official mini-program code with WeChat, then scan the adjacent data QR code to import the current receipt.
+HTML and structured data are written to `./codex-work-receipt-output/` by default. Non-interactive options such as `--latest` and `--today` remain available; see the [CLI guide](docs/cli.en.md).
 
 ## Ask Codex directly
 
@@ -86,79 +46,36 @@ Install the AI Work Receipt skill once:
 npx codex-work-receipt@latest --install-skill --lang en
 ```
 
-Then ask Codex naturally:
+Then ask Codex:
 
 > Create an AI work receipt for my latest Codex session.
 
-> Generate today's AI work receipt with the diner theme.
-
-Codex will select the correct mode and theme, run the CLI, and open the generated page. You can also invoke `$ai-work-receipt` explicitly.
-
-The skill is installed at `~/.agents/skills/ai-work-receipt/` and does not modify the current repository. Restart Codex if the current session does not detect it.
+Codex will choose the range and theme, run the CLI, and open the receipt. See the [Codex Skill guide](docs/codex-skill.en.md).
 
-## Features
+## Desktop to mobile
 
-- Latest-session and today summaries
-- Complete Chinese and English receipt copy
-- Three visual receipt themes
-- Turns, user messages, tool calls, interruptions, Tokens, duration, and models
-- Playful AI work points, job titles, and reviews
-- Versioned `cwr1` QR payload for mobile import
-- Local JSON snapshots and deduplicated history
-- Installable Codex skill for natural-language generation
-- No prompt, response, code, path, or file-name export
+The desktop page generates a privacy-safe data QR code. The companion WeChat mini program supports QR import, local history, themes, and image export. See [mobile import](docs/mobile-import.en.md).
 
-## Common options
+## Docs
 
-```bash
-npx codex-work-receipt@latest --latest --lang en --theme diner
-npx codex-work-receipt@latest --latest --lang en --no-open
-npx codex-work-receipt@latest --today --lang en --timezone Asia/Shanghai --output ./my-receipt.html
-```
-
-Run `npx codex-work-receipt@latest --help` for the full option list.
-
-## Privacy
-
-- Reads `~/.codex/sessions/**/*.jsonl` by default
-- Extracts event types, timestamps, model names, and numerical statistics only
-- Does not store prompts, responses, source code, project paths, or file names
-- Does not send session data over the network while running
-- Saves HTML and structured history locally
-
-See [docs/privacy.md](docs/privacy.md) and [docs/data-schema.md](docs/data-schema.md).
-
-## Open-source boundary
-
-This repository contains the desktop CLI, receipt renderer, QR data protocol, tests, and documentation. It does not contain the companion mini-program source code or server implementation.
+- [CLI usage and options](docs/cli.en.md)
+- [Codex Skill](docs/codex-skill.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)
+- [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) · [Changelog](CHANGELOG.md)
 
-## Local development
-
-```bash
-git clone https://github.com/a-bai-2026/ai-work-receipt.git
-cd codex-work-receipt
-npm install
-npm test
-npm run receipt -- --latest
-```
-
-Please read [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md) before contributing. Never submit real Codex sessions.
-
-## Roadmap
+## Sponsor
 
-- More receipt themes
-- Cursor and WorkBuddy data sources
-- Cross-tool activity reports
-- Weekly and monthly AI work archives
-- More parser fixtures and end-to-end compatibility tests
+<p align="center">
+  <a href="https://modelflare.dev/"><img src="docs/images/sponsors/modelflare-logo.png" alt="ModelFlare Logo" width="56"></a><br>
+  <a href="https://modelflare.dev/"><strong>ModelFlare</strong></a> · <a href="https://modelflare.dev/">modelflare.dev</a><br>
+  <sub>Stable access to leading AI model APIs at a very low cost, with transparent pricing and clear usage.</sub>
+</p>
 
-## License and disclaimer
+## License
 
-- The desktop source code in this repository is licensed under [GNU GPL v3](LICENSE) (`GPL-3.0-only`)
-- Modified or redistributed versions must continue to comply with GPLv3 and provide the corresponding source code
-- GPLv3 applies only to the desktop project in this repository; it does not cover the companion mini program, backend services, or other independent products
-- This is an unofficial community project and is not affiliated with or endorsed by OpenAI
-- Codex and other product names belong to their respective owners
+The desktop source is licensed under [GNU GPL v3](LICENSE) (`GPL-3.0-only`). This repository does not contain the companion mini-program or backend source code. This is an unofficial community project and is not affiliated with OpenAI.
 
 ---
 

package/README.md

@@ -10,102 +10,37 @@
 </p>
 
 <p align="center">
+  <a href="https://www.npmjs.com/package/codex-work-receipt"><img alt="npm" src="https://img.shields.io/npm/v/codex-work-receipt?color=42CDA7"></a>
   <img alt="Node.js 20+" src="https://img.shields.io/badge/Node.js-20%2B-339933?logo=node.js&logoColor=white">
-  <img alt="Local first" src="https://img.shields.io/badge/data-local--first-17231F">
-  <img alt="Privacy first" src="https://img.shields.io/badge/privacy-no%20prompts%20or%20code-42CDA7">
+  <img alt="GPL-3.0" src="https://img.shields.io/badge/license-GPL--3.0-17231F">
+  <img alt="Local first" src="https://img.shields.io/badge/data-local--first-42CDA7">
 </p>
 
 <p align="center">
   <img src="docs/images/readme-hero.jpg" alt="Codex AI 打工小票三种主题效果" width="920">
 </p>
 
-<p align="center">
-  只读取本机 Codex 会话中的时间和数字统计。<br>
-  不会把 Prompt、回复正文、代码、项目路径或文件名写入小票。
-</p>
-
-## 赞助商
-
-<p align="center">
-  <a href="https://modelflare.dev/">
-    <img src="docs/images/sponsors/modelflare-logo.png" alt="ModelFlare Logo" width="72">
-  </a>
-</p>
-
-<p align="center">
-  <a href="https://modelflare.dev/"><strong>ModelFlare</strong></a><br>
-  <a href="https://modelflare.dev/">modelflare.dev</a><br>
-  <sub>让个人开发者也能以很低的成本稳定接入前沿 AI 模型 API，价格友好、计费透明、用量清晰可见。</sub>
-</p>
-
-## 三种小票主题
-
-<table>
-  <tr>
-    <td align="center"><strong>经典白票</strong></td>
-    <td align="center"><strong>复古粉票</strong></td>
-    <td align="center"><strong>夜班绿票</strong></td>
-  </tr>
-  <tr>
-    <td><img src="docs/images/receipts/receipt-classic.jpg" alt="AI 打工小票经典白票" width="320"></td>
-    <td><img src="docs/images/receipts/receipt-diner.jpg" alt="AI 打工小票复古粉票" width="320"></td>
-    <td><img src="docs/images/receipts/receipt-payroll.jpg" alt="AI 打工小票夜班绿票" width="320"></td>
-  </tr>
-</table>
+它会统计 Codex 会话中的轮次、工具调用、Token、时长和模型，生成带有 AI 工分、今日工种和点评的小票。不会把 Prompt、回复正文、代码、项目路径或文件名写入小票。
 
-三种主题只改变视觉表达，不改变统计口径。生成网页后也可以即时切换主题。
+## Quickstart
 
-## 30 秒快速开始
-
-需要 Node.js 20 或更高版本，并且本机已经使用过 Codex。
-
-不需要克隆仓库，统计最近一次会话并自动打开小票：
+需要 Node.js 20 或更高版本，并且本机已经使用过 Codex。无需克隆仓库，运行后选择“今天 / 近 7 日 / 本周 / 指定会话”：
 
 ```bash
-npx codex-work-receipt@latest --latest
+npx codex-work-receipt@latest
 ```
 
-汇总本地时区今天发生的全部 Codex 活动：
+汇总今天的全部 Codex 活动：
 
 ```bash
 npx codex-work-receipt@latest --today
 ```
 
-生成英文版小票：
-
-```bash
-npx codex-work-receipt@latest --latest --lang en
-```
-
-生成结果默认保存在：
-
-```text
-./codex-work-receipt-output/
-├── codex-receipt-latest.html
-└── codex-receipt-latest.json
-```
-
-## 从电脑到手机
-
-```text
-Codex 本地会话
-  ↓
-运行一行命令
-  ↓
-生成 AI 打工小票网页和数据二维码
-  ↓
-在配套小程序中扫码导入
-  ↓
-换模板、保存图片、分享
-```
-
-配套小程序已经支持扫码导入、本地历史、主题切换和保存图片。微信扫码即可进入配套小程序，再扫描旁边的数据二维码导入当前小票。
-
-数据二维码只携带版本化的脱敏统计，不携带图片和原始会话。桌面端与小程序端分别根据同一份结构数据渲染小票。
+网页和结构数据默认保存在 `./codex-work-receipt-output/`。也可以继续使用 `--latest`、`--today` 等非交互参数，详见 [CLI 使用文档](docs/cli.md)。
 
 ## 直接跟 Codex 说
 
-只需安装一次 AI 打工小票 Skill：
+安装一次 AI 打工小票 Skill：
 
 ```bash
 npx codex-work-receipt@latest --install-skill
@@ -115,130 +50,35 @@ npx codex-work-receipt@latest --install-skill
 
 > 给刚刚这次工作开一张 AI 打工小票。
 
-> 生成我今天的 AI 打工小票，使用复古粉票。
-
-> 用英文生成刚刚这次工作的 AI 打工小票。
-
-Codex 会自动判断 `--latest` 或 `--today`、选择主题、执行命令并打开生成的网页。也可以通过 `$ai-work-receipt` 显式调用。
-
-Skill 安装在用户目录 `~/.agents/skills/ai-work-receipt/`，不会写入当前代码仓库；如果当前会话没有识别到，请重启 Codex。
-
-## 它能做什么
-
-- 统计最近一次 Codex 会话，或汇总今天的全部活动
-- 生成经典白票、复古粉票、夜班绿票三种主题
-- 支持中文和英文两套完整小票文案
-- 统计会话、轮次、用户消息、工具调用和中断次数
-- 展示 Token、缓存输入、AI 工作时长和模型
-- 根据工作量生成娱乐化的 AI 工分、今日工种和点评
-- 生成可供配套小程序扫描的 `cwr1` 数据二维码
-- 在本机保存结构 JSON 和去重后的历史记录
-- 安装可通过自然语言触发的 Codex Skill
-- 全程不上传 Prompt、回复、代码或项目路径
+Codex 会选择统计范围和主题、执行命令并打开小票。详见 [Codex Skill 使用文档](docs/codex-skill.md)。
 
-## 常用命令
-
-选择默认主题：
-
-```bash
-npx codex-work-receipt@latest --latest --theme diner
-```
-
-仅生成文件，不自动打开浏览器：
-
-```bash
-npx codex-work-receipt@latest --latest --no-open
-```
-
-指定时区和输出路径：
-
-```bash
-npx codex-work-receipt@latest --today \
-  --timezone Asia/Shanghai \
-  --output ./my-receipt.html
-```
-
-可用参数：
-
-| 参数 | 说明 |
-| --- | --- |
-| `--latest` | 统计最近活跃的 Codex 会话，默认模式 |
-| `--today` | 汇总指定时区今天发生的 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 打工小票 Skill 安装到当前用户的 Codex |
-| `--no-open` | 生成后不自动打开浏览器 |
-
-## 本地保存的数据
-
-每次运行会生成或更新：
-
-- `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`：去重后的本地历史，方便未来批量迁移
-
-数据结构和二维码协议见 [docs/data-schema.md](docs/data-schema.md)。
-
-## 隐私设计
-
-- 默认只读取 `~/.codex/sessions/**/*.jsonl`
-- 只提取事件类型、时间、模型名称和数字统计
-- 不保存 Prompt、回复正文、代码、项目路径或文件名
-- 运行期间不向网络发送会话数据
-- HTML、结构 JSON 和历史记录全部保存在本机
-- 二维码等同于一份可扫描的数据文件，请只向信任的人展示
-
-更完整的隐私说明见 [docs/privacy.md](docs/privacy.md)。
-
-## 当前限制
-
-- 暂不统计修改文件数和代码行数，避免在不同工具调用方式下产生误导
-- `--today` 默认扫描最近 72 小时有变动的会话文件，再按事件日期筛选
-- 当前只支持 Codex；Cursor、WorkBuddy 等数据源仍在规划中
-- 网页端不直接导出图片，移动端渲染和保存由配套小程序完成
-
-## 本地开发
-
-```bash
-git clone https://github.com/a-bai-2026/ai-work-receipt.git
-cd codex-work-receipt
-npm install
-npm test
-npm run receipt -- --latest
-```
+## 从电脑到手机
 
-贡献前请阅读：
+桌面网页会生成脱敏的数据二维码。配套微信小程序支持扫码导入、本地历史、主题切换和保存图片。详见 [手机扫码导入](docs/mobile-import.md)。
 
-- [CONTRIBUTING.md](CONTRIBUTING.md)
-- [SECURITY.md](SECURITY.md)
-- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
+## 文档
 
-测试数据必须是人工构造或彻底脱敏的 fixture，禁止提交真实 Codex 会话。
+- [CLI 使用与全部参数](docs/cli.md)
+- [Codex Skill](docs/codex-skill.md)
+- [手机扫码导入](docs/mobile-import.md)
+- [数据结构与二维码协议](docs/data-schema.md)
+- [本地数据与隐私说明](docs/privacy.md)
+- [参与贡献](CONTRIBUTING.md) · [安全说明](SECURITY.md) · [更新日志](CHANGELOG.md)
 
-## Roadmap
+## 赞助商
 
-- 增加更多可传播的小票主题
-- 支持 Cursor、WorkBuddy 等 AI 工作工具
-- 完善跨工具的统一数据结构
-- 支持周报、月报和长期 AI 工作档案
-- 改进 Codex 不同版本的日志兼容性和端到端测试
+<p align="center">
+  <a href="https://modelflare.dev/"><img src="docs/images/sponsors/modelflare-logo.png" alt="ModelFlare Logo" width="56"></a><br>
+  <a href="https://modelflare.dev/"><strong>ModelFlare</strong></a> · <a href="https://modelflare.dev/">modelflare.dev</a><br>
+  <sub>以很低的成本稳定接入前沿 AI 模型 API，价格友好、计费透明、用量清晰可见。</sub>
+</p>
 
-## 许可与声明
+## License
 
-- 本仓库中的电脑端源码采用 [GNU GPL v3](LICENSE)（`GPL-3.0-only`）许可
-- 修改或分发本项目时，必须继续遵守 GPLv3 并提供相应源码
-- GPLv3 仅适用于本仓库中的电脑端项目，不覆盖配套小程序、后台服务或其他独立产品
-- 本项目是非 OpenAI 官方社区工具，与 OpenAI 无隶属或背书关系
-- Codex、Cursor、WorkBuddy 及相关名称和商标归各自权利人所有
+电脑端源码采用 [GNU GPL v3](LICENSE)（`GPL-3.0-only`）。本仓库不包含配套小程序和后台服务源码；本项目是非 OpenAI 官方社区工具。
 
 ---
 
 <p align="center">
-  <strong>如果这张小票让你觉得有点意思，欢迎点一个 Star。</strong><br>
-  让每一次 AI 打工，都留下一张可以带走的记录。
+  <strong>如果这张小票让你觉得有点意思，欢迎点一个 Star。</strong>
 </p>

package/docs/cli.en.md

@@ -0,0 +1,133 @@
+# CLI guide
+
+<p><a href="./cli.md">中文</a> · <strong>English</strong> · <a href="../README.en.md">Back to README</a></p>
+
+## Requirements
+
+- Node.js 20 or later
+- Local Codex session records under `~/.codex/sessions/`
+
+No clone or global installation is required.
+
+## Interactive range selector
+
+Run:
+
+```bash
+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.
+
+## Non-interactive ranges
+
+Summarize the latest active session and open the receipt:
+
+```bash
+npx codex-work-receipt@latest --latest --lang en
+```
+
+Summarize all Codex activity from today in your local timezone:
+
+```bash
+npx codex-work-receipt@latest --today --lang en
+```
+
+Last 7 calendar days, including today:
+
+```bash
+npx codex-work-receipt@latest --range last-7-days --lang en
+```
+
+Monday through now:
+
+```bash
+npx codex-work-receipt@latest --range this-week --lang en
+```
+
+## Language and themes
+
+Generate a Chinese receipt:
+
+```bash
+npx codex-work-receipt@latest --latest --lang zh-CN
+```
+
+Choose the initial theme:
+
+```bash
+npx codex-work-receipt@latest --latest --lang en --theme diner
+```
+
+Available themes:
+
+- `classic`: classic white receipt
+- `diner`: vintage pink diner receipt
+- `payroll`: dark-green night payroll receipt
+
+Themes can still be switched in the generated page without changing the metrics.
+
+## Output
+
+Default output:
+
+```text
+./codex-work-receipt-output/
+├── codex-receipt-latest.html
+└── codex-receipt-latest.json
+```
+
+Set a timezone and output path:
+
+```bash
+npx codex-work-receipt@latest --today --lang en \
+  --timezone Asia/Shanghai \
+  --output ./my-receipt.html
+```
+
+Generate files without opening a browser:
+
+```bash
+npx codex-work-receipt@latest --latest --lang en --no-open
+```
+
+## Options
+
+| Option | Description |
+| --- | --- |
+| `--range <name>` | `latest`, `today`, `last-7-days`, or `this-week` |
+| `--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 |
+| `--timezone <name>` | Set an IANA timezone such as `Asia/Shanghai` |
+| `--lang <name>` | `zh-CN` (default) or `en` |
+| `--theme <name>` | `classic`, `diner`, or `payroll` |
+| `--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 |
+| `--no-open` | Do not open the generated page |
+
+Run the built-in help at any time:
+
+```bash
+npx codex-work-receipt@latest --help
+```
+
+## Local history
+
+Each run creates or updates:
+
+- `codex-work-receipt-output/codex-receipt-*.html`: theme-switchable receipt page
+- `codex-work-receipt-output/codex-receipt-*.json`: versioned receipt data
+- `~/.codex-work-receipt/receipts/*.json`: local snapshots
+- `~/.codex-work-receipt/latest.json`: latest receipt
+- `~/.codex-work-receipt/history.jsonl`: deduplicated local history
+
+See the [data schema and QR protocol](data-schema.en.md).
+
+## Current limitations
+
+- 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
+- Image export is handled by the companion mini program rather than the desktop page