@@ -0,0 +1,47 @@
+<!-- en -->
+v0.2.0 is a feature release: a redesigned local dashboard with in-browser configuration editing, Codex session titles aligned with the app's own index, WorkBuddy session titles with playground projects and an expert-client split, estimated per-request duration and output-speed metrics, layout-aware reading of OpenCode 2.x databases, and a substantially faster collection write path. Beyond the removed dashboard capabilities listed below, the one command-behavior break is `serve restart`.
+
+### Breaking changes
+- `serve restart` no longer starts a dashboard when none is running. If no dashboard is running (no `serve.json`, or a stale/corrupt one), the command now exits nonzero with an error pointing at `serve start` — the same semantics `daemon restart` already had. Previously it silently started a dashboard. The stop-phase progress lines are still printed on stdout (with the stale/corrupt cleanup note when applicable); `--addr` and `--open` have no effect on the error path. `serve stop` on a not-running dashboard, `serve restart` on a running one, and `update`'s dashboard handling are unchanged.
+
+### Highlights
+- **Redesigned dashboard with configuration editing.** The `serve` dashboard is rebuilt around server-shaped payloads (top-9 dimensions plus one "other" row, top-19 custom-view combos, top-20 sessions), client-side charts, light/dark themes, five accent palettes, and bilingual UI — plus a Config page that edits client, router, daemon, log, query, and refresh settings through the same locked, revision-checked write chain as `config set` (the data directory stays CLI-only: `data_dir` is not shown or editable on the page, and directory migration keeps its confirmed CLI flow). Per-surface refresh intervals (`[refresh]` → `dashboard_interval` / `watch_interval`) are now configurable, and table row caps keep long pages fast with per-table detail buttons behind the truncation.
+- **Session titles that match what the apps show.** Codex session titles now follow the app's own `session_index.jsonl` (source-priority merge with an anti-regression timestamp, stable fallback titles for untitled child threads, periodic resync that survives app renames that only touch the index). WorkBuddy sessions gain real titles, playground sessions group under `(unclassified)` instead of a directory name, expert sessions split into a separate `WorkBuddy Expert:<id>` client, and the local assistant gets a stable `本地助理` title.
+- **Estimated request duration and output speed.** Claude and Codex session logs now yield a per-request duration estimate (covering the whole request including the first-token wait); `avg_dur` and `speed` are optional metric columns in table reports and appear on the dashboard. Only requests with output ≥ 200 tokens and a 1s–1h estimate take part; groups without one show `—`. Rows collected by older versions carry no duration until their files are re-read.
+- **Faster and forward-compatible collection.** Hot-path writes are batched (measured roughly 7–8× faster on a full 11k-message write, ~2.4s → ~0.3s), and the OpenCode collector reads both the pre-2.x and the 2.x table layouts, switching automatically when the source database migrates.
+
+### New & Changed
+- **Dashboard**: full visual redesign with an embedded Config page (same write chain and revision protection as `config set`; the loopback HTTP surface's only write path remains the config save); server-side payload shaping (the browser no longer re-truncates or re-aggregates); table row caps with gated truncation detail; `[refresh]` section with `dashboard_interval` and `watch_interval` (an explicit `watch --interval` still overrides per run). Removed with the redesign: the period-over-period compare panel, the usage forecast panel, per-page CSV export (there is currently no replacement entry point for any of these), the `GET /api/chart/{kind}.svg` endpoints, and the compare/forecast blocks of the `/api/dashboard` payload (dimension and trend blocks were also reshaped) — anything that read the old payload or SVG endpoints needs to migrate to the numeric rows of the current payload. The default `watch` refresh interval also changed from 5s to 30s when `[refresh]` is unconfigured or `watch_interval = 0`; set `refresh.watch_interval = 5` or run `watch --interval 5s` to keep the old pace.
+- **Model names display in uppercase** in every dimension view that shows a model (stored values, grouping, and case-insensitive merging are unchanged — this is display only).
+- **Codex titles** (schema v6, applied automatically on first database open, no backfill): index hits apply only when their record time is strictly newer, so a truncated or rebuilt index cannot roll a synced title back; child threads without any title get a stable fallback; a bounded periodic poll retries failed syncs without waiting for files to change. No dedicated command is needed; every codex collection round also runs the sync.
+- **WorkBuddy attribution** (applied on the next WorkBuddy collection after upgrade, single-transaction and idempotent): per-session metadata from the source database decides the project (`is_playground` → unclassified), the client (expert sessions → `WorkBuddy Expert:<hex>`), and the title; the local assistant is titled `本地助理`. A periodic full review re-converges sessions whose metadata changed later, and family history is re-keyed in the same write transaction, so an expert↔normal transition cannot double-count tokens.
+- **Duration & speed metrics** (schema v7, `messages.duration_ms`, default 0 = not recorded, no backfill): Claude estimates from the reply's parent chain, Codex from an event-order state machine (replayed snapshots produce no estimate; the endpoint prefers the matched usage-record time and, in old logs where the count lands right after a tool result, falls back to the last model-output time so trailing tool wait is not counted — tool time inside the request span still is); the three per-group components (duration sum / count / output sum) are additive, so merged rows and totals are exact and never averaged averages.
+- **OpenCode 2.x layout awareness**: the collector detects the table layout on every scan (`message`+`event` vs `session_message`+`session_v2`) and handles the switch itself — a date-less incremental round that sees a layout transition performs a full sweep and rebuilds the message cursor, so migrated or downgraded databases stay complete without double counting; explicit-date collection keeps its date range. Note the verification boundary: the V2 read path is validated against synthetic test data only; compatibility with real 2.x databases (table shapes, migration behavior, event usage, and the `tokens.total` composition) is still to be confirmed. In the meantime, a terminal V2 message that has usage but a missing or `null` `tokens.total` is not booked — the round reports a partial failure, keeps the cursor for a later retry, and never guesses the total or overwrites an existing amount.
+- **Write-path batching**: `UpsertMessages` / `UpsertSessionMeta` / `UpsertRawRouterLogs` use multi-value inserts (chunked under the SQLite variable limit) and router-attribution backfill groups rows per distinct attribution value with a duplicate-key guard (duplicate input keys fall back to row-by-row updates, preserving the last-write-wins semantics). The failure contract is unchanged: any failed statement aborts the whole round's transaction.
+
+### Installation
+See the [README Quick Start](https://github.com/YuLaiZ/token-usage#quick-start). Existing users update in place with `token-usage update`.
+
+<!-- zh -->
+v0.2.0 是一次功能性版本：本地仪表板全面重设计并支持浏览器内配置编辑、Codex 会话标题与应用内索引对齐、WorkBuddy 会话标题与 playground 项目及专家客户端拆分、每请求估算时长与输出速度指标、OpenCode 2.x 数据库的布局感知读取，以及大幅提速的采集写路径。除下文列出的仪表板能力移除外，命令行为层面的破坏性变更为 `serve restart` 一项。
+
+### 破坏性变更
+- `serve restart` 在仪表板未运行时不再直接启动一个。未运行（无 `serve.json`，或文件陈旧/损坏）时命令以非零退出码报错并指引 `serve start`——与 `daemon restart` 既有语义对齐；此前它会静默启动一个仪表板。stop 阶段的过程行仍输出到 stdout（陈旧/损坏形态附带清理说明）；报错路径上 `--addr`、`--open` 不生效。未运行时的 `serve stop`、运行中实例的 `serve restart`、以及 `update` 的仪表板处理行为不变。
+
+### 亮点
+- **重设计的仪表板与配置编辑。** `serve` 仪表板围绕服务端塑形载荷重建（前 9 个维度 + 唯一「其他」行、前 19 个自定义视图组合、前 20 个会话）、客户端图表、深浅主题、五套配色与中英双语界面——并新增配置页，经与 `config set` 同一条带锁与 revision 校验的写入链路编辑客户端、路由、daemon、日志、查询与刷新配置（数据目录仅 CLI：配置页不展示、不接受 `data_dir`，目录迁移仍走 CLI 的确认链路）。分面刷新间隔（`[refresh]` → `dashboard_interval` / `watch_interval`）可配置；表格行数上限让长页面保持流畅，截断明细收在详情按钮后。
+- **与应用所见一致的会话标题。** Codex 会话标题跟随应用自身的 `session_index.jsonl`（来源优先级合并 + 防倒退时间戳；无标题子线程获得稳定兜底；周期性重同步覆盖只在索引里改名的场景）。WorkBuddy 会话获得真实标题，playground 会话归入「(未分类)」而非目录名，专家会话拆分为独立的 `WorkBuddy Expert:<id>` 客户端，本地助理固定标题「本地助理」。
+- **估算请求时长与输出速度。** Claude / Codex 会话日志现在产出每请求的估算时长（覆盖含等待首 token 的请求全程）；`avg_dur` 与 `speed` 作为表格报表的可选指标列，并在仪表板中展示。仅 output ≥ 200 token 且时长 1s–1h 的请求参与统计；无有效样本的分组显示 `—`。旧版本采集的行在源文件被重新读取前不记录时长。
+- **更快、更面向未来的采集。** 热路径写入批量化（11k 消息的全量写入实测约 7–8 倍提速，约 2.4s → 0.3s）；OpenCode collector 同时读取 2.x 前与 2.x 的表布局，源库迁移后自动切换。
+
+### 新增与变更
+- **仪表板**：全面视觉重设计 + 内嵌配置页（与 `config set` 同写入链路与 revision 保护；回环 HTTP 面唯一写路径仍是配置保存）；服务端载荷塑形（浏览器不再二次截断或聚合）；表格行数上限与门控的截断详情；新增 `[refresh]` 段（`dashboard_interval`、`watch_interval`；显式 `watch --interval` 仍按次覆盖）。随重做移除的能力：环比对比面板、用量预测面板、页面级 CSV 导出（以上当前均无替代入口）、`GET /api/chart/{kind}.svg` 独立取图端点，以及 `/api/dashboard` 载荷中的 compare/forecast 区块（维度与趋势区块结构亦已调整）——依赖旧载荷或 SVG 端点的调用方需迁移到当前载荷的数值行。`watch` 的默认刷新周期也从 5 秒变为 30 秒（`[refresh]` 未配置或 `watch_interval = 0` 时）；设置 `refresh.watch_interval = 5` 或运行 `watch --interval 5s` 可保持旧节奏。
+- **模型名在所有维度视图中统一大写显示**（库内存储值、分组与大小写折叠合并不变——纯显示层）。
+- **Codex 标题**（schema v6，首次打开数据库时自动迁移，无回填）：索引命中仅在记录时间严格更新时应用，索引截断/重建不会把已同步标题倒退；无任何来源标题的子线程获得稳定兜底；有界周期轮询在同步失败后自动重试，无需文件再次变化。无需专门命令；每轮 codex 采集也会执行同步。
+- **WorkBuddy 归属**（升级后下一次 WorkBuddy 采集时应用，单事务、幂等）：源库逐会话元数据决定 project（`is_playground` → 未分类）、client（专家会话 → `WorkBuddy Expert:<十六进制>`）与标题；本地助理固定标题「本地助理」。周期性全量复核让元数据后来变化的会话重新收敛；家族历史在同一写事务内重归属，专家↔普通互转不会双计 token。
+- **时长与速度指标**（schema v7，`messages.duration_ms`，默认 0 = 未记录，无回填）：Claude 按回复的消息父链估算，Codex 按事件序状态机估算（重播快照不产出估算；终点优先取匹配的用量记录时刻，旧日志的结算紧随工具完成时回退到最后模型输出时刻，避免把尾部工具等待计入——请求跨度中途的工具耗时仍包含在内）；每分组三个可加分量（时长和 / 有效请求数 / 有效 output 和）聚合，合并行与总计精确，绝不平均平均值。
+- **OpenCode 2.x 布局感知**：collector 每次扫描探测表布局（`message`+`event` vs `session_message`+`session_v2`）并自行处理切换——无日期的增量采集发现布局转换时执行全量兜底并重建 message 游标，迁移或降级后的数据库不漏不重；显式日期采集保持其日期范围。注意验证边界：V2 读取路径仅经合成测试数据验证，真实 2.x 数据库的兼容性（表结构、迁移行为、event 用法与 `tokens.total` 构成）仍待核实。此期间，带用量但 `tokens.total` 缺失或为 `null` 的终态消息暂不入账——该轮报告部分失败、游标保留供后续重试；不会猜测 total，也不会覆盖既有账目。
+- **写路径批量化**：`UpsertMessages` / `UpsertSessionMeta` / `UpsertRawRouterLogs` 改多值插入（按 SQLite 变量上限分块）；router 归因回填按归因值分组批量执行，重复输入键整批回退逐行更新（保持后写覆盖语义）。失败合同不变：任一语句失败即整轮回滚。
+
+### 安装
+见 [README 快速开始](https://github.com/YuLaiZ/token-usage/blob/main/README.zh-CN.md#快速开始)。已有用户用 `token-usage update` 原地升级。