codex-work-receipt 0.7.3 → 0.8.0

package/CHANGELOG.md

@@ -1,13 +1,29 @@
 # Changelog
 
+## 0.8.0
+
+- 首次交互式运行新增“自动保存 / 仅手动”选择；显式范围命令继续保持非交互兼容。
+- 自动保存通过 Codex `Stop` Hook 静默刷新当天同一张 HTML、完整 JSON 和 `.cwr.json` 微信导入文件，不使用定时器、空闲判断或常驻监听。
+- 新增 `--setup`、`--enable-auto`、`--disable-auto` 和 `--auto-status`，支持安全合并、检查和移除本工具自己的用户级 Hook。
+- 自动模式安装可离线运行的稳定本地执行器，合并前备份现有 Hooks，并在并发触发时合并任务、保护同一日输出。
+- 新增 `cwr-file-v1` 微信导入文件：每张小票在 HTML 旁边输出一个带完整 SHA-256 校验的 `.cwr.json`，网页也可直接下载同一份文件。
+- 桌面导入流程改为“下载文件 → 发送到文件传输助手 → 小程序选择聊天文件”，并补充小程序接入规范和跨仓库兼容夹具。
+- 数据二维码降级为可选单码：只有完整载荷能放进安全 QR version 时才显示扫码入口，不再生成或轮播新的 multipart 二维码。
+- 保留 `cwr1`、`cwr2` 和历史 `cwr2p` 解码兼容；二维码容量不足不再阻止 HTML、JSON、导入文件或本地历史生成。
+- 修复 HTML 长图导出时文字节点被固化宽高后发生的数值换行与错位问题。
+- 更新 HTML 工具栏并新增响应式侧栏，集中展示 GitHub、更新日志和赞助伙伴入口；这些网页控件不会进入导出图片。
+- 更新中英文 CLI、手机导入、协议、隐私和 Codex Skill 文档。
+
+## 0.7.4
+
+- 修复部分 bug。
+
 ## 0.7.3
 
 - Codex 会话日志改为分块逐行解析，避免超大 `.jsonl` 在转成单个 JavaScript 字符串时触发 V8 长度上限。
 - 会话行解析后立即丢弃 Prompt、回复、图片和工具输出，只在内存中保留统计所需的时间、事件、模型与 Token 字段。
 - 单行异常过大时带文件路径和行号跳过；文件读取失败时补充路径与体积，便于定位具体日志。
 - 本地 `history.jsonl` 改为逐条写入，避免历史增长后形成同类的大字符串拼接风险。
-- 小票生成或票仔安装成功后在终端展示开源仓库地址，并用对应的中英文文案邀请用户为项目点 Star。
-- 修正 npm 包的 repository、homepage 和 issues 地址，使其统一指向 `a-bai-2026/codex-work-receipt`。
 
 ## 0.7.2
 

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 · Codex pet · Three themes · Mobile QR import
+  One command · Local-first · Codex pet · Three themes · WeChat file import
 </p>
 
 <p align="center">
@@ -22,7 +22,7 @@
 
 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.
 
-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.
+The cwr2 protocol creates stable privacy-safe facts for each session and calendar day, allowing overlapping today, last-seven-days, and this-week receipts to be deduplicated. Every receipt also produces one `.cwr.json` WeChat import file. Scan import appears only when the complete payload fits in one data QR code.
 
 ## Meet Ticket Buddy
 
@@ -36,7 +36,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 3 hours, the last 7 days, this week, or a specific session:
+Requires Node.js 20+ and local Codex session records. No clone is required. The first interactive run asks whether to save automatically or use manual-only mode. Manual mode then offers today, the last 3 hours, the last 7 days, this week, or a specific session:
 
 ```bash
 npx codex-work-receipt@latest --lang en
@@ -56,7 +56,27 @@ npx codex-work-receipt@latest --hours 3 --lang en
 
 “Last N hours” is a rolling summary for private history only. It does not participate in AI Work Cooperative deduplicated accounting. Use today, this week, the last seven days, or a specific session when you want accountable canonical facts.
 
-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).
+HTML, structured data, and the WeChat import file are written to `./codex-work-receipt-output/` by default. The page can download its `.cwr.json` file and save a high-resolution PNG containing only the full receipt and WeChat mini-program code. See the [CLI guide](docs/cli.en.md).
+
+## Automatic saving or manual only
+
+Automatic saving uses the Codex `Stop` hook. Whenever a Codex turn stops, it quietly refreshes the same daily HTML, full JSON, and `.cwr.json` WeChat import file on this computer. It does not open a browser, upload files, or run a persistent watcher. The automatic path is file-first and does not generate a data QR.
+
+Choose the mode again:
+
+```bash
+npx codex-work-receipt@latest --setup --lang en
+```
+
+Or enable, disable, and inspect automatic saving directly:
+
+```bash
+npx codex-work-receipt@latest --enable-auto --lang en
+npx codex-work-receipt@latest --disable-auto --lang en
+npx codex-work-receipt@latest --auto-status --lang en
+```
+
+Automatic receipts live under `~/.codex-work-receipt/auto/YYYY-MM-DD/`. Switching to manual-only mode removes only the AI Work Receipt hook; it keeps existing receipts and unrelated Codex hooks. Restart Codex after installing the hook. If Codex asks you to review it, use `/hooks` to inspect and trust it. See the official [Codex hooks documentation](https://learn.chatgpt.com/docs/hooks).
 
 ## Ask Codex directly
 
@@ -86,15 +106,15 @@ Codex will choose the range and theme, run the CLI, and open the receipt. See th
 
 ## Desktop to mobile
 
-The desktop page generates one or more privacy-safe data QR codes. The companion WeChat mini program supports multipart scanning, private history, themes, and image export. See [mobile import](docs/mobile-import.en.md).
+The desktop page generates one privacy-safe `.cwr.json` file. Send it to WeChat File Transfer, then choose “Import from chat file” in the companion mini program. A single data QR remains available only for receipts that fit completely in one code. See [mobile import](docs/mobile-import.en.md).
 
 ## Docs
 
 - [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)
+- [Mobile file and single-QR import](docs/mobile-import.en.md)
+- [Data schema, file, 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)
 

package/README.md

@@ -6,7 +6,7 @@
 
 <p align="center">
   <strong>把本机 Codex 的工作记录，开成一张可以带走的 AI 打工小票。</strong><br>
-  一行命令 · 完全本地 · Codex 桌宠 · 三种主题 · 扫码传到手机
+  一行命令 · 完全本地 · Codex 桌宠 · 三种主题 · 微信聊天文件导入
 </p>
 
 <p align="center">
@@ -22,7 +22,7 @@
 
 它会统计 Codex 会话中的轮次、工具调用、Token、时长和模型，生成带有 AI 工分、今日工种和点评的小票。不会把 Prompt、回复正文、代码、项目路径或文件名写入小票。
 
-`0.6.0` 使用 cwr2 协议，按“会话 × 自然日”生成稳定的脱敏事实。今日、近 7 日和本周小票即使范围重叠，接收端也能识别相同工作；数据过大时会自动生成多张可重组的分片二维码，并在 HTML 中逐张自动轮播，避免镜头同时识别多个数据码。
+cwr2 协议按“会话 × 自然日”生成稳定的脱敏事实。今日、近 7 日和本周小票即使范围重叠，接收端也能识别相同工作。每张小票还会生成一个 `.cwr.json` 微信导入文件；只有完整数据能放进一个二维码时，网页才额外提供扫码导入。
 
 ## 认识票仔
 
@@ -36,7 +36,7 @@
 
 ## Quickstart
 
-需要 Node.js 20 或更高版本，并且本机已经使用过 Codex。无需克隆仓库，运行后选择“今天 / 最近 3 小时 / 近 7 日 / 本周 / 指定会话”：
+需要 Node.js 20 或更高版本，并且本机已经使用过 Codex。无需克隆仓库。首次交互式运行会先让你选择“自动保存”或“仅手动”；选择手动后，再选择“今天 / 最近 3 小时 / 近 7 日 / 本周 / 指定会话”：
 
 ```bash
 npx codex-work-receipt@latest
@@ -56,7 +56,27 @@ npx codex-work-receipt@latest --hours 3
 
 “最近 N 小时”是滚动摘要，只用于查看和保存私人历史，不参与 AI 供销社的去重统计。需要进入供销社时，请生成“今日 / 本周 / 近 7 日 / 指定会话”小票。
 
-网页和结构数据默认保存在 `./codex-work-receipt-output/`。生成的网页支持一键保存只包含完整小票和微信小程序码的高清长图，数据二维码不会进入图片。也可以继续使用 `--latest`、`--today` 等非交互参数，详见 [CLI 使用文档](docs/cli.md)。
+网页、结构数据和微信导入文件默认保存在 `./codex-work-receipt-output/`。生成的网页支持一键下载 `.cwr.json`，也可以保存只包含完整小票和微信小程序码的高清长图。数据二维码不会进入图片。详见 [CLI 使用文档](docs/cli.md)。
+
+## 自动保存或仅手动
+
+自动保存使用 Codex 的 `Stop` Hook：每当 Codex 完成一轮工作，就在本机静默刷新当天同一张 HTML、完整 JSON 和 `.cwr.json` 微信导入文件。它不会打开浏览器、不会上传文件，也不会常驻监听进程。自动路径以微信文件导入为主，不生成数据二维码。
+
+重新选择模式：
+
+```bash
+npx codex-work-receipt@latest --setup
+```
+
+也可以直接启用、关闭或检查自动保存：
+
+```bash
+npx codex-work-receipt@latest --enable-auto
+npx codex-work-receipt@latest --disable-auto
+npx codex-work-receipt@latest --auto-status
+```
+
+自动小票统一保存在 `~/.codex-work-receipt/auto/YYYY-MM-DD/`。切换为仅手动只会移除 AI 打工小票自己的 Hook，不会删除历史小票或其他 Codex Hook。安装 Hook 后请重启 Codex；如果 Codex 提示审查新 Hook，请使用 `/hooks` 确认并信任。Codex Hook 机制见 [官方文档](https://learn.chatgpt.com/docs/hooks)。
 
 ## 直接跟 Codex 说
 
@@ -86,15 +106,15 @@ Codex 会选择统计范围和主题、执行命令并打开小票。详见 [Cod
 
 ## 从电脑到手机
 
-桌面网页会生成一张或多张脱敏数据二维码。配套微信小程序支持分片扫码、私人历史、主题切换和保存图片。详见 [手机扫码导入](docs/mobile-import.md)。
+桌面网页会生成一个脱敏 `.cwr.json` 文件。把它发送到微信文件传输助手后，可在配套小程序中通过“从聊天文件导入”选择；数据足够小时也可以使用唯一的数据二维码快速导入。详见 [手机导入](docs/mobile-import.md)。
 
 ## 文档
 
 - [CLI 使用与全部参数](docs/cli.md)
 - [Codex Skill](docs/codex-skill.md)
 - [Codex 桌宠“票仔”](docs/codex-pet.md)
-- [手机扫码导入](docs/mobile-import.md)
-- [数据结构与二维码协议](docs/data-schema.md)
+- [手机文件与单码导入](docs/mobile-import.md)
+- [数据结构、文件与二维码协议](docs/data-schema.md)
 - [本地数据与隐私说明](docs/privacy.md)
 - [参与贡献](CONTRIBUTING.md) · [安全说明](SECURITY.md) · [更新日志](CHANGELOG.md)
 

package/docs/cli.en.md

@@ -9,7 +9,7 @@
 
 No clone or global installation is required.
 
-## Interactive range selector
+## Interactive mode and range selector
 
 Run:
 
@@ -17,7 +17,43 @@ Run:
 npx codex-work-receipt@latest --lang en
 ```
 
-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.
+The first interactive run asks you to choose:
+
+- `Automatic saving`: quietly refresh today's receipt and `.cwr.json` WeChat import file whenever a Codex turn stops
+- `Manual only`: generate only when you run the command or ask Ticket Buddy
+
+After choosing manual-only mode, 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. Explicit range flags such as `--today` and `--latest` never trigger mode setup.
+
+## Automatic saving
+
+Open the mode selector again:
+
+```bash
+npx codex-work-receipt@latest --setup --lang en
+```
+
+Enable, switch to manual-only mode, or inspect status directly:
+
+```bash
+npx codex-work-receipt@latest --enable-auto --lang en
+npx codex-work-receipt@latest --disable-auto --lang en
+npx codex-work-receipt@latest --auto-status --lang en
+```
+
+Automatic saving uses a user-level Codex `Stop` hook. When a turn stops, the hook launches one short-lived local generation process. It does not use a timer, idle detection, or a persistent watcher. Nearby triggers are coalesced, and a local lock protects concurrent generation.
+
+Automatic mode refreshes only the today range. It does not open a browser, print routine prompts, or generate a data QR. Each refresh updates:
+
+```text
+~/.codex-work-receipt/auto/YYYY-MM-DD/
+├── codex-receipt-today-YYYY-MM-DD.html
+├── codex-receipt-today-YYYY-MM-DD.json
+└── codex-receipt-today-YYYY-MM-DD.cwr.json
+```
+
+The `.cwr.json` file is the mobile import path for automatic receipts. Send it to WeChat File Transfer, then choose “Import from chat file” in the mini program. Automatic saving never sends or uploads the file itself.
+
+Enabling automatic saving installs a stable offline runtime under `~/.codex-work-receipt/runtime/` and safely merges `~/.codex/hooks.json`. Existing hook configuration is backed up first. If the current file cannot be parsed, setup stops instead of replacing it. Restart Codex and use `/hooks` to inspect and trust the hook if prompted. Manual-only mode removes only this tool's hook while preserving history, the local runtime, and unrelated hooks. After upgrading the npm package, run `--enable-auto` again to refresh the local runtime; repeated setup does not duplicate the hook.
 
 ## Non-interactive ranges
 
@@ -82,12 +118,17 @@ Default output:
 ```text
 ./codex-work-receipt-output/
 ├── codex-receipt-today-2026-07-18.html
-└── codex-receipt-today-2026-07-18.json
+├── codex-receipt-today-2026-07-18.json
+└── codex-receipt-today-2026-07-18.cwr.json
 ```
 
 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 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.
+In the generated HTML:
+
+- “Download WeChat import file” downloads the same `.cwr.json` file. Send it to WeChat File Transfer, then choose “Import from chat file” in the mini program.
+- “Or import by scanning” appears only when the complete payload safely fits in one data QR code. The desktop no longer generates multipart QR codes.
+- “Save full PNG” downloads a high-resolution image containing only the complete receipt and WeChat mini-program code. File controls, data QR codes, theme controls, the page background, and footer notes are excluded.
 
 Set a timezone and output path:
 
@@ -121,6 +162,10 @@ npx codex-work-receipt@latest --latest --lang en --no-open
 | `--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 |
+| `--setup` | Interactively choose automatic saving or manual-only mode |
+| `--enable-auto` | Install the local runtime and Codex hook, then enable automatic saving |
+| `--disable-auto` | Remove this tool's hook and switch to manual-only mode |
+| `--auto-status` | Show the mode, runtime, hook, and latest automatic-run status |
 | `--no-open` | Do not open the generated page |
 
 Run the built-in help at any time:
@@ -135,11 +180,15 @@ 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-output/codex-receipt-*.cwr.json`: privacy-safe file to send through WeChat and select in the mini program
 - `~/.codex-work-receipt/receipts/*.json`: local snapshots
 - `~/.codex-work-receipt/latest.json`: latest receipt
 - `~/.codex-work-receipt/history.jsonl`: deduplicated local history
+- `~/.codex-work-receipt/config.json`: automatic or manual-only configuration
+- `~/.codex-work-receipt/auto-state.json`: latest automatic-run status
+- `~/.codex-work-receipt/auto/YYYY-MM-DD/`: automatically refreshed daily HTML, JSON, and WeChat import file
 
-See the [data schema and QR protocol](data-schema.en.md).
+See the [data schema, file, and QR protocol](data-schema.en.md).
 
 ## Current limitations
 
@@ -147,3 +196,4 @@ See the [data schema and QR protocol](data-schema.en.md).
 - Changed-file and line counts are intentionally omitted until they can be measured consistently
 - 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
+- Automatic saving depends on a local Codex client firing the `Stop` hook; cloud tasks do not directly invoke the local hook

package/docs/cli.md

@@ -9,7 +9,7 @@
 
 无需克隆仓库或全局安装。
 
-## 交互选择统计范围
+## 交互选择保存方式与统计范围
 
 直接运行：
 
@@ -17,7 +17,43 @@
 npx codex-work-receipt@latest
 ```
 
-命令行会让你选择：今天全部活动、最近 3 小时、最近 7 个自然日、本周，或最近的某个具体会话。选择具体会话时会展示起止时间、轮次、工具调用和模型，帮助辨认。
+首次交互式运行会先让你选择：
+
+- `自动保存`：Codex 每完成一轮工作，就静默刷新今天的小票和 `.cwr.json` 微信导入文件
+- `仅手动`：只有执行命令或告诉票仔时才生成
+
+选择仅手动后，命令行会继续让你选择今天全部活动、最近 3 小时、最近 7 个自然日、本周，或最近的某个具体会话。选择具体会话时会展示起止时间、轮次、工具调用和模型，帮助辨认。显式使用 `--today`、`--latest` 等范围参数时不会触发模式问答。
+
+## 自动保存
+
+重新打开模式选择：
+
+```bash
+npx codex-work-receipt@latest --setup
+```
+
+直接启用、切换为仅手动或查看状态：
+
+```bash
+npx codex-work-receipt@latest --enable-auto
+npx codex-work-receipt@latest --disable-auto
+npx codex-work-receipt@latest --auto-status
+```
+
+自动保存通过用户级 Codex `Stop` Hook 触发。Hook 收到一轮工作停止事件后只启动一个短生命周期的本地生成进程；没有定时器、空闲判断或常驻监听服务。短时间内的重复触发会被合并，并发生成使用本地锁保护。
+
+自动模式只刷新“今日”范围，并且不打开浏览器、不打印日常提示、不生成数据二维码。每次刷新都会更新同一天的以下文件：
+
+```text
+~/.codex-work-receipt/auto/YYYY-MM-DD/
+├── codex-receipt-today-YYYY-MM-DD.html
+├── codex-receipt-today-YYYY-MM-DD.json
+└── codex-receipt-today-YYYY-MM-DD.cwr.json
+```
+
+`.cwr.json` 是自动模式的手机导入入口：把它发送到微信文件传输助手，再在小程序中选择“从聊天文件导入”。自动保存不会自动发送文件或上传数据。
+
+启用时会把不依赖网络的稳定运行器安装到 `~/.codex-work-receipt/runtime/`，并安全合并 `~/.codex/hooks.json`。如果已有 Hooks，原文件会先备份；无法解析现有配置时安装会停止，不会覆盖它。重启 Codex 后，如果出现 Hook 审查提示，请使用 `/hooks` 检查并信任。切换为仅手动只移除本工具自己的 Hook，保留历史、运行器和其他 Hooks。npm 包升级后重新执行 `--enable-auto` 即可更新本地运行器；重复执行不会重复添加 Hook。
 
 ## 非交互统计范围
 
@@ -82,12 +118,17 @@ npx codex-work-receipt@latest --latest --theme diner
 ```text
 ./codex-work-receipt-output/
 ├── codex-receipt-today-2026-07-18.html
-└── codex-receipt-today-2026-07-18.json
+├── codex-receipt-today-2026-07-18.json
+└── codex-receipt-today-2026-07-18.cwr.json
 ```
 
 默认文件名会携带统计日期范围；最近会话和指定会话则携带短编号，避免不同日期或会话的小票互相覆盖。
 
-打开生成的 HTML 后，点击“保存完整长图”即可下载高清 PNG。图片只包含完整主小票和微信小程序码，并自动使用当前选择的主题；数据二维码、分片数据码、主题按钮、网页背景和底部说明都不会进入图片。网页本身仍会正常展示数据二维码：单码时与小程序码并排，cwr2 超出单码安全容量时则在打开小程序后自动逐张轮播分片数据码，供用户在小程序中完成导入。
+打开生成的 HTML 后：
+
+- 点击“下载微信导入文件”会下载同一份 `.cwr.json`。把它发送到微信文件传输助手，再在小程序中点击“从聊天文件导入”。
+- 只有完整数据能安全放进一个二维码时，页面才显示“也可以扫码导入”；桌面端不会再生成多分片二维码。
+- 点击“保存完整长图”会下载高清 PNG。图片只包含完整主小票和微信小程序码，不包含导入文件按钮、数据二维码、主题按钮、网页背景或底部说明。
 
 指定时区和输出路径：
 
@@ -121,6 +162,10 @@ npx codex-work-receipt@latest --latest --no-open
 | `--install-pet` | 只安装“票仔”Codex 桌宠 |
 | `--uninstall-pet` | 卸载“票仔”，不删除 Skill 或历史小票 |
 | `--install-companion` | 同时安装 Skill 和“票仔”Codex 桌宠 |
+| `--setup` | 交互选择自动保存或仅手动模式 |
+| `--enable-auto` | 安装运行器和 Codex Hook，启用自动保存 |
+| `--disable-auto` | 移除本工具 Hook，切换为仅手动模式 |
+| `--auto-status` | 查看模式、运行器、Hook 和最近自动生成状态 |
 | `--no-open` | 生成后不自动打开浏览器 |
 
 也可以随时运行：
@@ -135,11 +180,15 @@ npx codex-work-receipt@latest --help
 
 - `codex-work-receipt-output/codex-receipt-*.html`：可切换主题的小票网页
 - `codex-work-receipt-output/codex-receipt-*.json`：当前小票的版本化结构数据
+- `codex-work-receipt-output/codex-receipt-*.cwr.json`：发送到微信聊天后由小程序选择的脱敏导入文件
 - `~/.codex-work-receipt/receipts/*.json`：本机历史快照
 - `~/.codex-work-receipt/latest.json`：最近生成的小票
 - `~/.codex-work-receipt/history.jsonl`：去重后的本地历史
+- `~/.codex-work-receipt/config.json`：自动保存或仅手动配置
+- `~/.codex-work-receipt/auto-state.json`：最近一次自动运行状态
+- `~/.codex-work-receipt/auto/YYYY-MM-DD/`：自动刷新的今日 HTML、JSON 和微信导入文件
 
-结构说明见 [数据结构与二维码协议](data-schema.md)。
+结构说明见 [数据结构、文件与二维码协议](data-schema.md)。
 
 ## 当前限制
 
@@ -147,3 +196,4 @@ npx codex-work-receipt@latest --help
 - 暂不统计修改文件数和代码行数，避免不同工具调用方式产生误导
 - 自然日范围按本地日期筛选，滚动小时范围按精确时间戳筛选，并分别计算每个会话的 Token 区间增量
 - 桌面网页导出 PNG 使用浏览器本地渲染，不上传小票数据
+- 自动保存依赖本机 Codex 客户端触发 `Stop` Hook；云端任务不会直接调用本机 Hook

package/docs/codex-pet.en.md

@@ -4,7 +4,7 @@
 
 “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.
+Ticket Buddy itself only presents Codex activity and provides companionship. It does not collect extra data, run the CLI, or alter the current task. Manual receipts use the AI Work Receipt skill. If [automatic saving](cli.en.md#automatic-saving) is enabled separately, an independent Codex `Stop` hook quietly refreshes today's receipt; that behavior is not controlled by the pet animation.
 
 ## Install the skill and pet together
 

package/docs/codex-pet.md

@@ -4,7 +4,7 @@
 
 “票仔 · AI 小票工”是 AI 打工小票为 Codex 原生 Pets 功能制作的自定义桌宠。它是一台长着小牛角的夜班绿热敏打印机，会跟随 Codex 的空闲、工作、等待、完成和失败状态切换动画。
 
-票仔只负责状态展示和陪伴，不会自动读取额外数据、生成小票或改变 Codex 的任务。开票仍然通过 AI 打工小票 Skill 完成。
+票仔本身只负责状态展示和陪伴，不会读取额外数据、运行 CLI 或改变 Codex 的任务。手动开票通过 AI 打工小票 Skill 完成；如果另外启用了[自动保存](cli.md#自动保存)，则由独立的 Codex `Stop` Hook 静默刷新今日小票，与桌宠动画无关。
 
 ## 一次安装 Skill 和票仔
 

package/docs/codex-skill.en.md

@@ -4,6 +4,8 @@
 
 AI Work Receipt includes a Codex Skill that converts natural-language requests into the appropriate CLI options.
 
+The skill remains a manual receipt entry point in either saving mode. With automatic saving enabled, you can still ask Codex for another range such as the latest session or this week. Manual-only mode does not disable the skill. Configure automatic saving with `npx codex-work-receipt@latest --setup --lang en`; see [automatic saving in the CLI guide](cli.en.md#automatic-saving).
+
 ## Install
 
 ```bash

package/docs/codex-skill.md

@@ -4,6 +4,8 @@
 
 AI 打工小票内置了一个 Codex Skill，让 Codex 可以根据自然语言替你选择参数并运行 CLI。
 
+Skill 属于手动开票入口，与保存模式互不冲突：自动保存开启后仍然可以让 Codex 生成最近会话、本周等其他范围；仅手动模式则不会影响 Skill 的正常使用。自动保存模式通过 `npx codex-work-receipt@latest --setup` 配置，详见 [CLI 使用](cli.md#自动保存)。
+
 ## 安装
 
 ```bash

package/docs/data-schema.en.md

@@ -1,8 +1,8 @@
-# Data schema and QR protocol
+# Data schema, file, 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.
+The full receipt schema is currently version `2`; rolling-hour summaries remain on compatible version `1`. Each run saves both the full local record and a privacy-safe WeChat import file.
 
 ## Main fields
 
@@ -18,6 +18,29 @@ The current schema version is `1`. Each generation saves a structured receipt re
 
 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.
 
+## WeChat import file
+
+Each run writes a `*.cwr.json` file beside the HTML:
+
+```json
+{
+  "format": "codex-work-receipt",
+  "file_version": 1,
+  "payload_schema": "cwr2",
+  "payload": {},
+  "integrity": {
+    "algorithm": "sha256",
+    "digest": "..."
+  }
+}
+```
+
+`payload` is exactly the compact structure obtained after decoding a QR payload. `integrity.digest` is a full SHA-256 over canonical payload JSON. It detects corruption but is not a source signature. The mini program must treat every file as untrusted input, enforce a size limit, validate versions, fields, numeric bounds, unique fact IDs, manifests, and content hashes, then persist atomically only after confirmation.
+
+Canonicalization recursively sorts every object's keys using JavaScript's default string order (UTF-16 code units), preserves array order, uses JSON primitive types, and emits no whitespace or trailing newline. Calculate SHA-256 over the resulting UTF-8 bytes. Use the digest in `docs/fixtures/cwr-file-v1.json` to cross-check another implementation.
+
+A cross-repository compatibility fixture is available at `docs/fixtures/cwr-file-v1.json`.
+
 ## QR format
 
 The QR payload uses compact fields:
@@ -28,7 +51,9 @@ cwr2.<checksum>.<Base64URL of deflateRaw(JSON)>
 cwr2p.<transferId>.<partIndex>.<partCount>.<totalChecksum>.<partChecksum>.<chunk>
 ```
 
-`cwr1` and `cwr2` are complete single-code payloads. `cwr2p` splits the cwr2 string into up to 12 reorderable parts. The mini program collects a transfer by transferId, validates the total checksum, reconstructs cwr2, and only then decompresses it. Multipart HTML rotates one data code at a time; the protocol does not require scan order.
+`cwr1` and `cwr2` are complete single-code payloads. The desktop generates one data QR only when the complete payload stays within the safe QR version; otherwise it provides only the `.cwr.json` file and does not generate new multipart codes.
+
+`cwr2p` is the legacy reorderable cwr2 multipart format, limited to 12 parts. Updated mini programs should still collect historical parts by transferId, validate part and total checksums, reconstruct cwr2, and decompress it so existing receipts remain importable.
 
 The mini program validates the prefix and checksum before decompressing and parsing the payload. Future schema versions use the compact `v` field for compatibility.
 
@@ -38,4 +63,4 @@ When the same Codex session has multiple append-only log revisions, the generato
 
 `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).
+See [mobile file and single-QR import](mobile-import.en.md).

package/docs/data-schema.md

@@ -1,8 +1,8 @@
-# 数据结构与二维码协议
+# 数据结构、文件与二维码协议
 
 <p><strong>中文</strong> · <a href="./data-schema.en.md">English</a> · <a href="../README.md">返回 README</a></p>
 
-当前结构版本为 `1`。每次生成都会在本机保存一份结构记录。
+当前完整记录结构版本为 `2`；滚动小时摘要为了兼容继续使用版本 `1`。每次生成都会在本机保存完整结构记录和一份脱敏微信导入文件。
 
 ## 主要字段
 
@@ -18,6 +18,29 @@
 
 同一个会话、同一天或同一组自然日边界的 `id` 保持稳定；重复生成会更新该记录。`source.snapshot_hash` 用于识别统计内容是否发生变化。
 
+## 微信导入文件
+
+每次生成都会在 HTML 旁边写入一个 `*.cwr.json`：
+
+```json
+{
+  "format": "codex-work-receipt",
+  "file_version": 1,
+  "payload_schema": "cwr2",
+  "payload": {},
+  "integrity": {
+    "algorithm": "sha256",
+    "digest": "..."
+  }
+}
+```
+
+`payload` 与二维码解压后的精简结构完全相同。`integrity.digest` 是对规范化 payload JSON 计算的完整 SHA-256，用于发现损坏，但不是来源签名。小程序必须把文件视为不可信输入，限制文件大小，校验版本、字段、数值范围、factId 唯一性、manifest 和 content hash，并在用户确认后原子入库。
+
+规范化规则是：递归按 JavaScript 默认字符串排序（UTF-16 code unit 顺序）排列每个对象的键，保持数组元素顺序，使用 JSON 原始类型，不添加空白或换行，再对生成的 UTF-8 字节计算 SHA-256。兼容实现可用 `docs/fixtures/cwr-file-v1.json` 的 digest 做交叉验证。
+
+兼容测试夹具见 `docs/fixtures/cwr-file-v1.json`。
+
 ## 二维码格式
 
 二维码使用精简字段：
@@ -28,7 +51,9 @@ cwr2.<checksum>.<deflateRaw(JSON) 的 Base64URL>
 cwr2p.<transferId>.<partIndex>.<partCount>.<totalChecksum>.<partChecksum>.<chunk>
 ```
 
-`cwr1` 和 `cwr2` 是完整单码。`cwr2p` 是 cwr2 单码字符串的可乱序分片，最多 12 片；小程序先按 transferId 收集全部分片，再校验总 checksum、拼回 cwr2 并解压。HTML 在多分片时每次只轮播一个数据码，协议本身不依赖扫描顺序。
+`cwr1` 和 `cwr2` 是完整单码。桌面端只有在完整载荷不超过安全 QR version 时才生成一个数据二维码；否则只提供 `.cwr.json` 文件，不再生成新的分片二维码。
+
+`cwr2p` 是旧版桌面端生成的可乱序 cwr2 分片，最多 12 片。新版小程序仍应收集相同 transferId 的历史分片、校验分片和总 checksum、拼回 cwr2 并解压，以兼容已经生成的小票。
 
 小程序应检查前缀和校验值，再解压并解析数据。未来结构升级通过 `v` 字段兼容。
 
@@ -38,4 +63,4 @@ cwr2p.<transferId>.<partIndex>.<partCount>.<totalChecksum>.<partChecksum>.<chunk
 
 `presentation.compensation` 是娱乐化 AI 工分，不代表真实 API 费用。为兼容当前中文小程序，二维码展示文案继续使用中文，并通过精简字段 `l` 和 `r` 携带桌面语言及工种语义 ID；英文 HTML 和本地 JSON 不受影响。
 
-手机端流程见 [手机扫码导入](mobile-import.md)。
+手机端流程见 [手机文件与单码导入](mobile-import.md)。

package/docs/fixtures/cwr-file-v1.json

@@ -0,0 +1,33 @@
+{
+  "format": "codex-work-receipt",
+  "file_version": 1,
+  "payload_schema": "cwr1",
+  "payload": {
+    "v": 1,
+    "i": "cwr_fixture",
+    "g": "2026-07-22T00:00:00.000Z",
+    "o": "latest",
+    "d": [
+      "2026-07-22T00:00:00.000Z",
+      "2026-07-22T01:00:00.000Z",
+      "Asia/Shanghai",
+      "2026-07-22",
+      "2026-07-22"
+    ],
+    "s": [1, 2, 2, 3, 0, 60000, 1200],
+    "t": [100, 80, 20, 10, 120],
+    "m": ["test-model"],
+    "l": "zh-CN",
+    "r": null,
+    "p": [
+      "classic",
+      "测试工种",
+      "测试点评",
+      ["本单工资", 12, "AI 工分", "测试数据", "work_points_v1"]
+    ]
+  },
+  "integrity": {
+    "algorithm": "sha256",
+    "digest": "08fc2306dfc6c6520c9889b0a40db24bb340c7cc7b8d1637f06436a4c925879c"
+  }
+}