# Changelog

本项目的所有重要变更记录在此文件中。

格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。

## [Unreleased]

## [0.5.3] - 2026-09-20

### Fixed
- 适配 Harness 0.1.6-alpha.2：从 `retainedBy.mainView` 选择主会话，兼容旧版
  `current`，空白主视图不会误选侧边会话。
- 消息费用角标按各自会话共享独立轮询，侧边会话可直接恢复历史账本，
  不再依赖主计费卡；最后一个角标卸载时取消请求和定时器。

### Changed
- 兼容矩阵新增 0.1.6-alpha.2；检查实际会话列表形状，并执行多会话回归测试。
- 更新已审查的上游监控基线，新增客户端会话选择与引用生命周期监控。
- 更新后重启 Harness，无需迁移设置或历史账本。

### Validation
- 95 项测试通过；兼容检查覆盖 0.1.1-rc.2 至 0.1.6-alpha.2 的 6 个指定版本。
- 使用真实 0.1.6-alpha.2 Web 宿主及本机模拟模型，检查会话切换、消息角标、
  会话费用及插件停用/重新启用；供应商目录和官方价格检查无漂移。

## [0.5.2] - 2026-09-11

### Fixed
- 适配 Harness 0.1.5 的 `{eventState, events}` 历史读取结果，兼容旧数组格式；
  无效结果不缓存，所有路径释放读取句柄，历史快照与实时去重保持不变。
- 新增 2026-09-10 12:00 北京时间生效的 V4.1 Flash 双币峰谷价格及旧 Flash
  名称映射；Pro 价格不变，已落账历史不重新计价。
- 定价校验按官网表头顺序读取模型列，并与当前政策对比；新增模型会提示差异，
  模型服务日期不再误识别为调价日期。

### Changed
- pi-ai 目录同步到上游锁定的 0.85.1（26 家供应商），移除上游已删除的 xAI 预置。
- 兼容门禁增加 dsh-v0.1.5-rc.2，并根据指定版本实际读取类型执行回放测试；
  更新已审查的上游监控基线，新增 SessionHandle 源文件监控。

### Upgrade notes
- 新 Flash 价格按消息时间生效；已落账记录（包括此前标记为未计价的记录）
  保留原快照，本次升级不迁移、不重算历史消费。
- 更新后重启 Harness。DeepSeek Pro 继续使用独立价格，不安排 9 月 14 日自动切换。

### Validation
- 91 项测试通过，类型检查、lint 和生成文件一致性检查通过。
- 在真实 Harness 0.1.5-rc.2、独立配置和本机模拟模型下验证：5 条新 Flash
  响应合计 ¥0.602，重启后费用、模型标签与价格快照恢复，未重复记账。
- 生产源码契约检查覆盖 0.1.1-rc.2、0.1.2-alpha.1、0.1.2-rc.1、
  0.1.3-alpha.1、0.1.5-rc.2，以及 master 提交 c291e7961a51。

## [0.5.1] - 2026-09-06

### Fixed
- 从历史请求恢复会话的供应商和模型标签，修复重启宿主后标签消失、供应商
  跟随回退到全局默认值的问题；实时请求仍优先，未知供应商继续明确提示。
- 适配 Harness `dsh-v0.1.3-alpha.1` 的 SessionPersistence：通过 `stat` 与
  `open(id, 'read')` / `SessionHandle.read()` 恢复历史费用回放，成功或失败都
  释放句柄；继续支持旧版 `readRaw` / `readStoredRevision`。
- 回放 revision 缓存限定在同一持久化服务实例内，避免服务替换后复用旧结果；
  历史价格快照、实时消息去重及回放节流保持原有语义。
- 宿主契约门禁覆盖 0.1.2-rc.1 与 0.1.3-alpha.1，按指定 tag 的生产源码
  分别检查新旧读取接口，避免测试或文档中的旧符号掩盖接口移除。

## [0.5.0] - 2026-08-28

### Added
- 每条账本记录持久化首次计价的目录来源、单价与 token 桶小计；历史回放复用
  该快照，目录升级不再重算并改写旧消费。
- state 响应与卡片展示 pi-ai 价格目录版本，明确费用为本地估算。

### Changed
- 上游目录中三类 token 单价全为 0 的模型改判为订阅/额度套餐并标记未计价，
  不再显示成「免费按量」。
- 会话回放缓存和浏览器消息缓存增加容量上限；账本按 session 建索引并缓存
  日/月/总计聚合，避免轮询时重复全表扫描。

## [0.4.2] - 2026-08-28

### Changed
- 适配 DeepSeek Harness `dsh-v0.1.2-alpha.1`：精确 `/api` 路由在新宿主上复用
  connection 的 launch-token 与 Host/Origin 拒绝策略，同时保留 v0.1.1 兼容。
- pi-ai 快照升级到 Harness lockfile 实际解析的 `0.84.2`，目录更新为 27 家供应商；
  上游检查器不再把 semver 区间内后来发布的版本误当作 release 的锁定版本。

## [0.4.1] - 2026-08-23

### Added
- **契约哨兵监控**（check-upstream 第 4 类检测）：对事件词汇表、持久化契约、
  TokenUsage 形状、deepseek 适配器 README 四个接缝锚点做 sha256 基线对比
  （`scripts/upstream-sentinels.json` 入库，`--update-baseline` 重录）；变化
  以 advisory 区块提示人工复查，不计入漂移。另含官方用量 API 关键词增量
  扫描——出现正式 usage/billing 接口时报告迁移机会。
- **state 路由 golden 快照**：聚合响应归一化后与基线深比较，意外契约漂移
  在测试期暴露；`UPDATE_SNAPSHOT=1` 重录（diff 须在 PR 中审查）。
- 决策档案 `docs/decisions/0001–0004`：峰谷周一口径回溯、隐含汇率与兜底
  常数、漂移监控设计、fail-closed 计价——只增不改的"为什么"记录。

### Changed
- 品牌合规（对照官方 BRAND_GUIDELINES）：双语 README 增加非官方社区插件
  声明行；徽章文案改为 "DSH-community plugin"（避免完整商标与官方背书
  暗示；项目名 dsh-* 缩写符合官方推荐用法）。
- CONTRIBUTING 新增决策文件约定与发布纪律（feature 先 -rc）。

## [0.4.0] - 2026-08-23

### Added
- **上游漂移自动监控**：`scripts/check-upstream.mjs` + 每日定时 workflow
  （`upstream-watch.yml`）。监控三类漂移——Harness 最新 release 所需的 pi-ai
  版本 vs 插件 devDep、用上游数据重建目录 vs 已提交 catalog、官方定价页 vs
  内置价格政策链；发现漂移自动创建/追加 GitHub Issue，无漂移时自动关闭遗留
  issue。本地入口 `npm run check:upstream`。
- **设置卡片**（Harness v0.1.0-rc.7+）：设置面板新增「计费悬浮卡」页，可关闭
  悬浮胶囊 / 每条消息费用角标、一键恢复悬浮卡默认位置；偏好存 localStorage。
- 视觉实验模型 `deepseek-v4-flash-vision-exp` 计价（与 v4-flash 同价同峰谷）；
  型号徽章新增 "Flash-Vision"。
- 官方隐含汇率 `impliedFxRate()`：消费统计混合币种换算不再使用写死的 7.2，
  而是取现行政策双币价之比；支持 env `DSH_BILLING_FX_CNY_PER_USD` 覆盖。
- `ledger.summary()` 每桶新增按原生币种分组的 `native` 合计——单币种账本精确
  展示，无需任何汇率换算。
- refresh-pricing 响应附带 `pageHash`（定价页内容指纹，审计用）。
- TypeScript strict 类型检查（JSDoc + checkJs，零构建安装不变）与 oxlint
  门禁进入 CI；全仓 JSDoc 注解。

### Changed
- `lib/index.js` 纯计价管道拆分至 `lib/session-costing.js`（index.js 761→541 行）。
- sync-providers 数据源探测顺序：显式参数 > 本地 Harness 安装 > devDep 兜底；
  provenance 新增 `sourceKind` 字段（CHECK 模式继承已提交值，保证跨环境一致）。
- package.json 声明 `engines: node >=20`。

## [0.3.0] - 2026-08-23

### Added
- 对齐 Harness v0.1.1-rc.x：新视觉模型、峰谷"周一至周五"限定（以 2026-08-23
  官方页脚注为准）、三列峰谷矩阵解析器重写。
- sessionPersistence 能力位守卫（`supportsRawArtifacts === false` 时降级 live-only）。
- pi-ai 目录对齐 harness 内置 0.82.1（27→25 家 provider）。

## [0.2.0] - 2026-08-15

### Added
- 多供应商自动切换（header > 配置 > 注册表默认）；27 家官方目录预置供应商。
- 定价校验按钮（DeepSeek 官方页快照对比，60s 防抖）。
- 峰谷定价政策链（2026-08-17 生效）；未知模型 fail closed（unpricedCalls）。
- append-only JSONL 消费账本（幂等/压缩/坏行修复）；今日消费走官方平台接口。
- 双语 README 与 CI 门禁（test / check:generated / pack:check）。

## [0.1.0] - 2026-08-13

### Added
- 首个可用版本：液态玻璃胶囊常驻余额展示；点击展开完整计费卡（会话费用/
  token 三桶/供应商列表）；每条消息费用角标；可拖动卡片（localStorage 记忆）。