dsh-cost-meter 1.7.6 → 1.7.8

package/README.en.md

@@ -6,7 +6,7 @@
 
 Per-conversation cost · daily totals · OpenCode Go subscription quota display · budget with usage percentage · official account balance · custom provider balance · balance progress bar · history · peak/off-peak pricing hours display (peak hours UTC 01:00–04:00, 06:00–10:00; from Aug 23, 2026 weekends are billed at off-peak prices all day, shown as “Weekend — all off-peak”) · pre-switch popup & system-notification alerts for peak/off-peak changes (position / lead time / alert type configurable) · one-click price sync from the official docs · Codex-style token usage heat grid · multi-vendor model pricing (built-in 90+ model price catalog with auto-matching) · mainstream Coding Plan quota queries & display (Anthropic / Z.ai / MiniMax / Kimi / OpenRouter / SiliconFlow / CommandCode / SCNet) plan/API dual-track billing (subscription quota vs pay-as-you-go money separated, per-1% & full-window token/equivalent-cost estimates with daily/weekly/monthly curves) · · quota strip above the input box (budget / Go / coding-plan usage in one row, toggleable)
 
-[![version](https://img.shields.io/badge/version-1.7.6-4176E6)](https://github.com/Han-1413141/dsh-cost-meter)
+[![version](https://img.shields.io/badge/version-1.7.8-4176E6)](https://github.com/Han-1413141/dsh-cost-meter)
 [![npm](https://img.shields.io/npm/v/dsh-cost-meter?label=npm)](https://www.npmjs.com/package/dsh-cost-meter)
 [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![dsh](https://img.shields.io/badge/DeepSeek%20Harness-dsh--plugin-4176E6)](https://github.com/deepseek-ai/deepseek-harness)
@@ -87,13 +87,27 @@ For NewApi `GET /api/usage/token` (response `{ "code": 200, "data": { "total_gra
 - Unlimited-quota tokens (`unlimited_quota: true`) have no `total_available`, so `remaining` cannot be extracted and the query reports “remaining is missing or not numeric” — use a limited-quota token or a middle-layer endpoint that converts the units;
 - Entry point: Settings → Cost (Quota tab) → “Custom provider balance” → expand config; or write `config.customBalance` in `storages/cost-meter/ledger.json`.
 
-### Credentials & security (v1.7.6)
+### Credentials & security (v1.7.8)
 
 - **Variable naming**: `{{VAR_NAME}}` follows the `<ROUTE>_API_KEY` convention — `<ROUTE>` is the Provider ID from the DSH Models page (Settings → Models), uppercased with non-alphanumeric characters replaced by underscores, e.g. `openai`→`{{OPENAI_API_KEY}}`, `anthropic`→`{{ANTHROPIC_API_KEY}}`, `abc23-d`→`{{ABC23_D_API_KEY}}`. Sharing a name with the Models page means the balance query and model calls **share the same key** (both resolve from the DSH credential store). This note is also shown above the “Headers (JSON)” input in Settings.
 - **Credential input fields**: after expanding an entry, the “Credential input” section renders one write-only field per `{{VAR}}` placeholder found in the headers — the key goes straight into the DSH credential store (never written to disk, never echoed back, never stored in `ledger.json`); no need to hand-edit environment variables or credential files.
-- **Automatic plaintext migration**: older versions let a literal `Bearer sk-…` in the headers leak into `ledger.json` in plaintext. Since v1.7.6 the plugin imports such keys into the DSH credential store at startup and replaces the header value with a `{{CUSTOM_BALANCE_KEY_…}}` placeholder (derived from the entry's host + header name, stable across restarts) — nothing breaks. From now on `ledger.json` and the config shipped to the browser **never contain plaintext keys**: suspected secret headers (Authorization / X-Api-Key / Bearer / sk- prefixes / long opaque strings) are blanked, while placeholders and ordinary headers pass through.
+- **Automatic plaintext migration**: older versions let a literal `Bearer sk-…` in the headers leak into `ledger.json` in plaintext. Since v1.7.8 the plugin imports such keys into the DSH credential store at startup and replaces the header value with a `{{CUSTOM_BALANCE_KEY_…}}` placeholder (derived from the entry's host + header name, stable across restarts) — nothing breaks. From now on `ledger.json` and the config shipped to the browser **never contain plaintext keys**: suspected secret headers (Authorization / X-Api-Key / Bearer / sk- prefixes / long opaque strings) are blanked, while placeholders and ordinary headers pass through.
 - **Credential allowlist `allowedHosts`**: when headers carry credentials (placeholders or plaintext), the outbound host must be on this list or the request is refused — protection against leaked keys when importing someone else's config. Without a list, requests proceed with a one-time logged warning. The entry panel provides an “Allowed hosts” input (comma-separated).
 
+## CLIProxyAPI Gateway Quotas and WorkBuddy Credits (Issue #87)
+
+Connects to a local or LAN-deployed [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) proxy gateway to observe quotas across upstream providers and WorkBuddy plugin credits in one place:
+
+- **Native Multi-Provider Discovery & Quotas**: Auto-discovers active credentials via the CPA Management API and queries official native endpoints for Antigravity, Claude, Codex, Kimi, and xAI (Grok). Normalized into standard 5h / 7d / weekly / monthly usage percentage windows with ISO reset timestamps.
+- **WorkBuddy Plugin Credits**: Queries WorkBuddy's read-only management route (`/v0/management/plugins/workbuddy/credits`) to display total, used, and remaining credit balances alongside package lifecycle end-dates, preserving separate account cards.
+- **Zero Metering Side-Effects Guarantee**: Completely read-only — strictly avoids mutating actions such as Codex reset-credit consume, xAI token-consuming chat completion probes, and any WorkBuddy POST routes.
+- **Strict Credential Isolation & Transport Security**:
+  - Management Keys are stored strictly write-only in the DSH credential store (`CLIPROXYAPI_MANAGEMENT_KEY_<SOURCE_ID>_<HASH>`), never exposed in config, state, or browser views.
+  - Management calls are strictly restricted to 3 fixed paths (`/v0/management/auth-files`, `/v0/management/api-call`, `/v0/management/plugins/workbuddy/credits`). Arbitrary upstream URLs are forbidden.
+  - Outbound host whitelist (`allowedHosts`): Non-loopback origins require exact host matches, and plain HTTP requires an explicit `allowInsecureHttp` opt-in.
+  - HTTP redirects are strictly forbidden (`redirect: 'manual'`; any 3xx response is rejected) to guard against credential leakage or request hijacking.
+  - Privacy and metadata sanitization: Strips raw tokens, cookies, and identity claims from auth-files discovery; emails are masked in public state (`s***@domain`).
+
 ## Bilingual UI
 
 The plugin UI (session badge, sidebar balance row & budget box, and the entire Settings page) supports **Simplified Chinese** and **English**:
@@ -238,22 +252,22 @@ Real captures from an actual DSH sidebar of the period strip and collapsed verti
 dsh plugin --profile web add dsh-cost-meter
 ```
 
-**PowerShell one-click script** (copy the whole line, paste, press Enter; pnpm is provisioned automatically, git is auto-detected — no clone needed; the install chain is **pinned to the release tag `v1.7.6`** — review the script before running):
+**PowerShell one-click script** (copy the whole line, paste, press Enter; pnpm is provisioned automatically, git is auto-detected — no clone needed; the install chain is **pinned to the release tag `v1.7.8`** — review the script before running):
 
 ```powershell
-irm https://raw.githubusercontent.com/Han-1413141/dsh-cost-meter/v1.7.6/install.ps1 | iex
+irm https://raw.githubusercontent.com/Han-1413141/dsh-cost-meter/v1.7.8/install.ps1 | iex
 ```
 
 **Or a plain command line** (the machine must already have pnpm and git; also pinned to the tag):
 
 ```sh
-dsh plugin --profile web add github:Han-1413141/dsh-cost-meter#v1.7.6
+dsh plugin --profile web add github:Han-1413141/dsh-cost-meter#v1.7.8
 ```
 
 Without git, use the GitHub tag archive:
 
 ```sh
-dsh plugin --profile web add https://github.com/Han-1413141/dsh-cost-meter/archive/refs/tags/v1.7.6.tar.gz
+dsh plugin --profile web add https://github.com/Han-1413141/dsh-cost-meter/archive/refs/tags/v1.7.8.tar.gz
 ```
 
 After installing, **restart** `dsh web` (plugin rows, the Typert manifest and the client bundle are all scanned at startup):

package/README.md

@@ -6,7 +6,7 @@
 
 本会话费用 · 当日费用 · OpenCode Go 订阅额度显示 · 预算与已用百分比 · 官方账户余额 · 自定义 Provider 余额查询(可配任意 HTTP 端点) · 余额三段进度条 · 历史记录 · 峰谷计价时段显示(UTC 01:00–04:00、06:00–10:00 为峰时段;2026-08-23 起周末全天按谷价,显示「周末时段——全谷价」) · 峰/谷切换前弹窗与系统通知提醒(位置/提前量/提醒类型可配) · 官方价格一键同步 · 类 Codex Token 用量热图 · 多厂商多模型价格计费(内置 90+ 模型价格目录与自动匹配) · 主流 Coding Plan 额度查询与显示(Anthropic / Z.ai / MiniMax / Kimi / OpenRouter / SiliconFlow / CommandCode / SCNet / 火山方舟 九家,含 Volcano Ark AK/SK 签名) · Plan/API 双轨计费(订阅额度与按量金额分离统计,每 1% 额度与满窗的 token/等值金额估算及日/周/月曲线) · 输入框上方额度横条(预算/Go/Coding Plan 用量一条横排显示,可开关)
 
-[![version](https://img.shields.io/badge/version-1.7.6-4176E6)](https://github.com/Han-1413141/dsh-cost-meter)
+[![version](https://img.shields.io/badge/version-1.7.8-4176E6)](https://github.com/Han-1413141/dsh-cost-meter)
 [![npm](https://img.shields.io/npm/v/dsh-cost-meter?label=npm)](https://www.npmjs.com/package/dsh-cost-meter)
 [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![dsh](https://img.shields.io/badge/DeepSeek%20Harness-dsh--plugin-4176E6)](https://github.com/deepseek-ai/deepseek-harness)
@@ -88,13 +88,27 @@
 - 无限额度 token(`unlimited_quota: true`)没有 `total_available`,无法提取 `remaining`,查询会报「remaining is missing or not numeric」——请改用有限额度 token,或在中间层端点换算;
 - 配置入口:设置 → 费用(额度标签)→「自定义 Provider 余额」展开配置;或直接改 `storages/cost-meter/ledger.json` 的 `config.customBalance`。
 
-### 凭据与安全(v1.7.6)
+### 凭据与安全(v1.7.8)
 
 - **变量名命名规则**:`{{VAR_NAME}}` 的参考格式为 `<ROUTE>_API_KEY`——`<ROUTE>` 对应 DSH 模型配置页(设置 → 模型)里的 Provider ID,把 ID 大写、非字母数字字符替换为下划线,例如 `openai`→`{{OPENAI_API_KEY}}`、`anthropic`→`{{ANTHROPIC_API_KEY}}`、`abc23-d`→`{{ABC23_D_API_KEY}}`。与模型页共用同一变量名,自定义余额查询与模型调用即**共用同一把密钥**(都从 DSH 凭据库解析)。该说明也展示在设置页「请求头 (JSON)」输入框上方。
 - **凭据输入框**:展开条目配置后,「凭据输入」区会为请求头里出现的每个 `{{VAR}}` 占位符显示一行 write-only 输入框,密钥直接存入 DSH 凭据库(不落盘、不回显、不经 `ledger.json`),无需再手改环境变量或凭据文件。
-- **明文密钥自动迁移**:旧版本把 `Bearer sk-…` 明文写在请求头里时会明文落盘;v1.7.6 起插件在启动时自动把这类明文导入 DSH 凭据库,并把头值替换为 `{{CUSTOM_BALANCE_KEY_…}}` 占位符(名称由条目 host + 头名派生,跨重启稳定),功能不受影响。此后 `ledger.json` 与下发给浏览器的配置**永不包含明文密钥**——疑似密钥头(Authorization / X-Api-Key / Bearer / sk- 前缀 / 长不透明串)一律置空,占位符与普通头照常保留。
+- **明文密钥自动迁移**:旧版本把 `Bearer sk-…` 明文写在请求头里时会明文落盘;v1.7.8 起插件在启动时自动把这类明文导入 DSH 凭据库,并把头值替换为 `{{CUSTOM_BALANCE_KEY_…}}` 占位符(名称由条目 host + 头名派生,跨重启稳定),功能不受影响。此后 `ledger.json` 与下发给浏览器的配置**永不包含明文密钥**——疑似密钥头(Authorization / X-Api-Key / Bearer / sk- 前缀 / 长不透明串)一律置空,占位符与普通头照常保留。
 - **凭据白名单 `allowedHosts`**:请求头携带密钥(占位符或明文)时,出站主机必须命中该白名单,否则直接拒绝——用于防止「导入他人配置」导致密钥外带。未配置白名单时放行并在日志警告一次。设置页条目面板内有「凭据白名单主机」输入框(逗号分隔)。
 
+## CLIProxyAPI 网关额度与 WorkBuddy 积分 (Issue #87)
+
+支持对接本地或局域网部署的 [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) 代理网关,集中观测代理的多个 Provider 账号额度与 WorkBuddy 插件积分:
+
+- **多 Provider 账号原生适配**:自动通过 CPA Management API 发现账号,接入 Antigravity、Claude、Codex、Kimi、xAI (Grok) 官方原生配额/用量接口。统一归一化为 5h / 7d / weekly / monthly 等用量百分比窗口与 ISO 重置时刻。
+- **WorkBuddy 插件积分**:只读接入 WorkBuddy 插件 `/v0/management/plugins/workbuddy/credits` 路由,展示账户总积分、已用/剩余与套餐周期,保留独立账号卡片。
+- **零计费副作用保证**:严禁并杜绝任何产生计费消耗的操作——不调用 Codex 的 reset-credit consume 端点,不向 xAI 发送消耗 token 的 chat probe,不调用 WorkBuddy 的任何变更性 POST 路由。
+- **严格凭据隔离与安全门禁**:
+  - Management Key 通过只写 (write-only) 形式托管于 DSH 凭据库 (`CLIPROXYAPI_MANAGEMENT_KEY_<SOURCE_ID>_<HASH>`),永不存入配置文件、账本或浏览器 state。
+  - 请求路径严格限制为三条固定管理路径 (`/v0/management/auth-files`、`/v0/management/api-call`、`/v0/management/plugins/workbuddy/credits`),禁止任意 URL 拼接。
+  - 严格出站白名单 (`allowedHosts`):非 loopback 来源必须精确命中白名单,非 loopback HTTP 必须显式开启 `allowInsecureHttp`。
+  - 强制禁止 HTTP 重定向 (`redirect: 'manual'`, 3xx 状态码坚决拒绝),防止网关重定向劫持或凭据外带。
+  - 账号隐私与元数据过滤:auth-files 响应仅提取必需字段,剔除 raw tokens / cookies / ID claims,展示层邮箱自动脱敏掩码 (`s***@domain`)。
+
 ## 双语界面
 
 插件界面(会话徽章、侧边栏余额与预算图框、设置页全部文案)支持**简体中文**与**English**:
@@ -240,22 +254,22 @@
 dsh plugin --profile web add dsh-cost-meter
 ```
 
-**PowerShell 一键脚本**(复制整行粘贴回车;自动补齐 pnpm、自动探测 git,无需克隆仓库;安装链**固定到发布 tag `v1.7.6`**,建议先下载审阅再运行):
+**PowerShell 一键脚本**(复制整行粘贴回车;自动补齐 pnpm、自动探测 git,无需克隆仓库;安装链**固定到发布 tag `v1.7.8`**,建议先下载审阅再运行):
 
 ```powershell
-irm https://raw.githubusercontent.com/Han-1413141/dsh-cost-meter/v1.7.6/install.ps1 | iex
+irm https://raw.githubusercontent.com/Han-1413141/dsh-cost-meter/v1.7.8/install.ps1 | iex
 ```
 
 **或直接命令行**(机器上需已有 pnpm 与 git;同样固定到 tag):
 
 ```sh
-dsh plugin --profile web add github:Han-1413141/dsh-cost-meter#v1.7.6
+dsh plugin --profile web add github:Han-1413141/dsh-cost-meter#v1.7.8
 ```
 
 没有 git 时可用 GitHub tag 打包直链:
 
 ```sh
-dsh plugin --profile web add https://github.com/Han-1413141/dsh-cost-meter/archive/refs/tags/v1.7.6.tar.gz
+dsh plugin --profile web add https://github.com/Han-1413141/dsh-cost-meter/archive/refs/tags/v1.7.8.tar.gz
 ```
 
 安装后**重启** `dsh web`(插件行、Typert 清单与客户端 bundle 均在启动时扫描):

package/lib/backfill.js

@@ -10,7 +10,8 @@
  * 避免与实时计费重复计数。会话日志是宿主的只读数据,本模块从不写入。
  */
 
-import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { readdirSync, statSync } from 'node:fs'
+import { open } from 'node:fs/promises'
 import { join } from 'node:path'
 import * as zlib from 'node:zlib'
 import { costOf, providerPriceEntryFor, usdFromCost, isWrapperProviderId, wrapperUpstreamProvider } from './pricing.js'
@@ -22,6 +23,61 @@ const ZSTD_MAGIC = 4247762216
 /** 打包行(文本/推理/工具调用增量游程)不含 header 与 usage,回放时跳过。 */
 const PACKED_ROW_TYPES = new Set(['text-chunks', 'reasoning-chunks', 'tool-call-chunks'])
 
+// ── 内存与事件循环守卫(v1.7.7,issue #88) ───────────────────────────────
+//
+// 用户实测:一份 168MB(压缩后)的 session.jsonl.zstd 在启动回填时把 Electron
+// 主进程堆耗尽(STATUS_BREAKPOINT 崩溃),且同步解压全程占住事件循环(agent
+// 界面整体卡死)。旧缓解(逐帧解压代替全文拼接)只压住了解压峰值,仍有两个
+// 洞:records 数组物化全部解压后事件(堆)与巨长打包行的 JSON.parse(瞬时峰值)。
+// 现三层防御:
+//   · 打包行探针:超 4096 字节的行先看头部 512 字符,命中打包行模式直接跳过,
+//     不再付出 JSON.parse 的整行解析峰值(探针只做加速,短行/未命中仍走解析+过滤,
+//     行为不变);
+//   · 流式迭代器 iterateSessionRecords:分块读文件 + 增量扫描帧边界,逐帧解压
+//     逐行产出记录,任一时刻只持有单帧解压结果;配合定期 setImmediate 让出,
+//     回填期间宿主 UI 不再被卡死;
+//   · 解压预算:单文件累计解压字节数超上限(默认 4GB,防解压炸弹)抛错,
+//     调用方按「单文件损坏」跳过该文件,绝不把主进程拖崩。
+
+/** 打包行探针:巨长行头部出现 "type":"text-chunks" 等即判打包行,免整行解析。 */
+const PACKED_ROW_PROBE = /"type"\s*:\s*"(?:text|reasoning|tool-call)-chunks"/
+const PACKED_ROW_PROBE_HEAD = 512
+const PACKED_ROW_PROBE_MIN_LINE = 4096
+/** 单文件解压累计上限(防解压炸弹;正常会话日志解压后数百 MB~2GB)。 */
+const MAX_DECOMPRESSED_PER_FILE = 4 * 1024 * 1024 * 1024
+/** 流式读文件的分块大小。 */
+const READ_CHUNK_BYTES = 8 * 1024 * 1024
+/** 每 N 帧解压/每 N 条事件让出一次事件循环(保持宿主 UI 响应)。 */
+const YIELD_EVERY_FRAMES = 64
+const YIELD_EVERY_EVENTS = 4096
+
+/** 巨长行探针判定(仅加速路径,未命中仍走 JSON.parse + 类型过滤)。 */
+function lineLooksPacked(line) {
+  if (line.length <= PACKED_ROW_PROBE_MIN_LINE) return false
+  return PACKED_ROW_PROBE.test(line.slice(0, PACKED_ROW_PROBE_HEAD))
+}
+
+/**
+ * 解析单行日志为事件对象;空行、打包行与坏行返回 null。
+ * 短行走「解析后按类型丢弃」;巨长行先探针,命中打包行直接跳过(免解析峰值)。
+ * @param {string} line
+ * @returns {object | null}
+ */
+export function parseRecordLine(line) {
+  if (line.length === 0) return null
+  if (lineLooksPacked(line)) return null
+  try {
+    const rec = JSON.parse(line)
+    // 打包行(text/reasoning/tool-call 增量游程)在解析入口就丢弃:它们是
+    // 大日志的体积主体,回放阶段反正会跳过,提前过滤才能兑现 OOM 缓解。
+    if (rec !== null && typeof rec === 'object' && !PACKED_ROW_TYPES.has(rec.type)) return rec
+    return null
+  } catch {
+    // 坏行跳过:回放是尽力而为,不让单行损坏阻断整个会话。
+    return null
+  }
+}
+
 /**
  * 结构化扫描拼接的 Zstandard frame 边界(不解压块内容),与宿主
  * dsh-session-persistence-jsonl 的容器格式一致:每个追加批次一个独立
@@ -73,57 +129,117 @@ export function scanZstdFrames(buffer) {
 }
 
 /**
- * 读取一份会话日志的全部事件行(zstd 逐 frame 解压;明文直接按行)。
+ * 流式逐行读取一份会话日志(异步生成器,v1.7.7 issue #88 的核心原语)。
+ *
+ * zstd 容器按帧边界增量扫描:分块读入原始字节(READ_CHUNK_BYTES),已确认完整的
+ * 帧立即解压并逐行产出、随后释放引用——任一时刻只持有「单帧解压结果 + 尾部
+ * 跨块/跨帧的行缓冲 + 已积累的记录数组」,不再物化全文。巨长打包行经探针
+ * 跳过(免 JSON.parse 峰值)。每 YIELD_EVERY_FRAMES 帧让出一次事件循环。
  *
- * 内存约束:宿主会话日志可含数万帧(每次追加批次一个独立 zstd frame,
- * 长期会话可达 10 万+ 帧)且解压后数百 MB。旧实现把所有帧一次性解压、
- * Buffer.concat 拼成全文再 split——峰值内存可达数 GB,4GB 堆限制下
- * 会 OOM(实测一份 50MB / 11.5 万帧日志即 ~3GB)。现改为逐帧解压、
- * 逐帧按行切片解析:任一时刻只保留单帧解压结果(通常 ≤ 数 MB),行缓冲
- * 跨帧拼接兜底半行(追加批次以换行结尾,实际不会出现)。
+ * 单文件累计解压字节数超过 maxDecompressed(默认 4GB,防解压炸弹)抛
+ * RangeError,调用方按单文件损坏处理。
  * @param path - session.jsonl.zstd 或 session.jsonl 路径。
- * @returns 逐行 JSON.parse 后的记录数组(坏行跳过)。
+ * @param options - { maxDecompressed?: number, yieldEvery?: number }。
+ * @yields {object} 逐行解析出的记录(空行/打包行/坏行已过滤)。
  */
-export function readSessionRecords(path) {
-  const buffer = readFileSync(path)
-  const records = []
-  let pending = '' // 跨帧行缓冲:上一帧末尾未换行的残行拼接进下一帧首行。
-  const consumeText = (text) => {
-    if (text.length === 0) return
-    const lines = text.split('\n')
-    lines[0] = pending + lines[0]
-    pending = lines[lines.length - 1]
-    for (let i = 0; i < lines.length - 1; i++) {
-      const line = lines[i]
-      if (line.length === 0) continue
-      try {
-        const rec = JSON.parse(line)
-        // 打包行(text/reasoning/tool-call 增量游程)在解析入口就丢弃:它们是
-        // 大日志的体积主体,回放阶段反正会跳过,提前过滤才能兑现 OOM 缓解。
-        if (rec !== null && typeof rec === 'object' && !PACKED_ROW_TYPES.has(rec.type)) records.push(rec)
-      } catch {
-        // 坏行跳过:回放是尽力而为,不让单行损坏阻断整个会话。
+export async function* iterateSessionRecords(path, options = {}) {
+  const maxDecompressed = Number(options.maxDecompressed) > 0 ? Number(options.maxDecompressed) : MAX_DECOMPRESSED_PER_FILE
+  const yieldEvery = Number(options.yieldEvery) > 0 ? Number(options.yieldEvery) : YIELD_EVERY_FRAMES
+  const isZstd = path.endsWith('.zstd')
+  if (isZstd && typeof zlib.zstdDecompressSync !== 'function') return
+  const handle = await open(path, 'r')
+  try {
+    let pending = '' // 跨块/跨帧行缓冲:上一段末尾未换行的残行拼接进下一段首行。
+    let tail = Buffer.alloc(0) // 压缩字节尾部缓冲:块边界落在帧中间时拼接后继续扫。
+    let decompressedTotal = 0
+    let framesSinceYield = 0
+    const consumeText = (text, out) => {
+      if (text.length === 0) return
+      const lines = text.split('\n')
+      lines[0] = pending + lines[0]
+      pending = lines[lines.length - 1]
+      for (let i = 0; i < lines.length - 1; i++) {
+        const rec = parseRecordLine(lines[i])
+        if (rec !== null) out.push(rec)
       }
     }
-  }
-  if (path.endsWith('.zstd')) {
-    if (typeof zlib.zstdDecompressSync !== 'function') return []
-    const frames = scanZstdFrames(buffer)
-    for (const f of frames) {
-      consumeText(zlib.zstdDecompressSync(buffer.subarray(f.start, f.end)).toString('utf8'))
-    }
-  } else {
-    consumeText(buffer.toString('utf8'))
-  }
-  if (pending.length > 0) {
-    try {
-      const rec = JSON.parse(pending)
-      // 与上方 consumeText 同规则:打包行不入记录(文件末尾无换行的残行兜底)。
-      if (rec !== null && typeof rec === 'object' && !PACKED_ROW_TYPES.has(rec.type)) records.push(rec)
-    } catch {
-      // 文件末尾无换行的残行:同上,尽力而为。
+    const records = []
+    // 结构损坏标志:一旦出现「一个完整分块里连一个可解帧都没有」,按旧版
+    // 全量扫描的语义(在首个非法结构处停止)忽略文件后续内容——否则坏字节
+    // 会在 tail 里无限拼接,且行为与旧版不一致。
+    let stopped = false
+    for (;;) {
+      const chunk = await handle.read(Buffer.allocUnsafe(READ_CHUNK_BYTES), 0, READ_CHUNK_BYTES, null)
+      if (chunk.bytesRead === 0) break
+      const data = tail.length > 0 ? Buffer.concat([tail, chunk.buffer.subarray(0, chunk.bytesRead)]) : chunk.buffer.subarray(0, chunk.bytesRead)
+      tail = Buffer.alloc(0)
+      if (stopped) continue
+      if (!isZstd) {
+        consumeText(data.toString('utf8'), records)
+        if (records.length >= YIELD_EVERY_EVENTS) {
+          yield* drain(records)
+          await new Promise(resolve => setImmediate(resolve))
+        }
+        continue
+      }
+      // 增量消费完整帧:从 data 头部起逐帧取边界(帧区间相对 subarray 起点),
+      // 解压→逐行→释放引用;剩余不完整帧(块边界截断)留在 tail 等下一块。
+      let offset = 0
+      while (offset < data.length) {
+        const frames = scanZstdFrames(data.subarray(offset))
+        if (frames.length === 0) {
+          // 剩余字节连不出完整帧:未满一个分块 = 尾部截断,留 tail 等下一块;
+          // 已满一个分块仍无帧 = 结构损坏(与旧版全量扫描停在非法结构同语义),
+          // 标记停止,忽略文件后续。
+          if (data.length - offset >= READ_CHUNK_BYTES) stopped = true
+          else tail = data.subarray(offset)
+          break
+        }
+        for (const f of frames) {
+          decompressedTotal += f.end - f.start
+          if (decompressedTotal > maxDecompressed) {
+            throw new RangeError(`session log decompress budget exceeded (${decompressedTotal} > ${maxDecompressed} bytes): ${path}`)
+          }
+          const plain = zlib.zstdDecompressSync(data.subarray(offset + f.start, offset + f.end))
+          consumeText(plain.toString('utf8'), records)
+          framesSinceYield += 1
+        }
+        offset += frames[frames.length - 1].end
+      }
+      if (framesSinceYield >= yieldEvery || records.length >= YIELD_EVERY_EVENTS) {
+        yield* drain(records)
+        framesSinceYield = 0
+        await new Promise(resolve => setImmediate(resolve))
+      }
+    }
+    // 文件读完:tail 里剩的残帧(崩溃截断)按既有语义忽略;行缓冲兜底末行。
+    if (pending.length > 0) {
+      const rec = parseRecordLine(pending)
+      if (rec !== null) records.push(rec)
     }
+    yield* drain(records)
+  } finally {
+    await handle.close()
   }
+}
+
+/** 把 records 数组逐条 yield 出去并清空(内部助手)。 */
+function* drain(records) {
+  for (const rec of records) yield rec
+  records.length = 0
+}
+
+/**
+ * 读取一份会话日志的全部事件行(zstd 逐 frame 解压;明文直接按行)。
+ * 同步兼容包装:逐行收集成数组。新的回填路径应改用流式 iterateSessionRecords
+ * (issue #88:records 数组本身在大日志下仍是堆压力,收集形态只留给需要数组
+ * 随机访问的调用方)。
+ * @param path - session.jsonl.zstd 或 session.jsonl 路径。
+ * @returns 逐行 JSON.parse 后的记录数组(坏行跳过)。
+ */
+export async function readSessionRecordsAsync(path, options = {}) {
+  const records = []
+  for await (const rec of iterateSessionRecords(path, options)) records.push(rec)
   return records
 }
 
@@ -448,14 +564,15 @@ export async function backfillLegacyLedger(ledger, sessionsRoot) {
     }
   }
   for (const path of listSessionLogs(sessionsRoot, onlySessionIds)) {
-    // 会话日志多时逐份解压会长时间占住事件循环:每 8 份让出一次,不卡宿主 UI。
+    // 会话日志多时逐份解压会长时间占住事件循环:每 8 份让出一次,不卡宿主 UI;
+    // 单文件内部亦为流式读取(v1.7.7,issue #88:解压期间周期性让出,大日志不再卡死宿主)。
     if ((scannedCount += 1) % 8 === 0) await new Promise(resolve => setImmediate(resolve))
     result.scanned += 1
     let replayed
     try {
-      replayed = replaySessionRecords(readSessionRecords(path), ledger.config, needDates.size > 0 ? needDates : new Set(['-']))
+      replayed = replaySessionRecords(await readSessionRecordsAsync(path), ledger.config, needDates.size > 0 ? needDates : new Set(['-']))
     } catch {
-      continue // 单文件损坏不阻断整体回填。
+      continue // 单文件损坏(含解压预算超限)不阻断整体回填。
     }
     if (replayed.sessionId.length === 0) continue
     if (replayed.title.length > 0 && !titles.has(replayed.sessionId)) titles.set(replayed.sessionId, replayed.title)
@@ -692,9 +809,9 @@ export async function importLegacyHistory(ledger, sessionsRoot) {
     result.scanned += 1
     let replayed
     try {
-      replayed = replaySessionRecords(readSessionRecords(path), ledger.config, null)
+      replayed = replaySessionRecords(await readSessionRecordsAsync(path), ledger.config, null)
     } catch {
-      continue // 单文件损坏不阻断整体导入。
+      continue // 单文件损坏(含解压预算超限)不阻断整体导入。
     }
     if (replayed.sessionId.length === 0) continue
     const existing = bySession.get(replayed.sessionId)
@@ -785,9 +902,9 @@ export async function recomputeLedgerPricingBasis(ledger, sessionsRoot) {
     if ((result.scanned += 1) % 8 === 0) await new Promise(resolve => setImmediate(resolve))
     let replayed
     try {
-      replayed = replaySessionRecords(readSessionRecords(path), ledger.config, null)
+      replayed = replaySessionRecords(await readSessionRecordsAsync(path), ledger.config, null)
     } catch {
-      continue // 单文件损坏不阻断整体重算。
+      continue // 单文件损坏(含解压预算超限)不阻断整体重算。
     }
     if (replayed.sessionId.length === 0) continue
     const existing = bySession.get(replayed.sessionId)
@@ -874,13 +991,14 @@ function subtractBucketInto(target, source) {
 export async function repairForkSeed(ledger, sessionsRoot) {
   const result = { sessions: 0, days: 0, scanned: 0 }
   for (const path of listSessionLogs(sessionsRoot)) {
-    // 全量同步扫描会长时间占住事件循环:每 8 份让出一次(与回填/导入同策略)。
+    // 全量同步扫描会长时间占住事件循环:每 8 份让出一次(与回填/导入同策略);
+    // 单文件内部亦为流式读取(v1.7.7,issue #88)。
     if ((result.scanned += 1) % 8 === 0) await new Promise(resolve => setImmediate(resolve))
     let records
     try {
-      records = readSessionRecords(path)
+      records = await readSessionRecordsAsync(path)
     } catch {
-      continue // 单文件损坏不阻断整体清洗。
+      continue // 单文件损坏(含解压预算超限)不阻断整体清洗。
     }
     // 只处理 fork 会话(header 带 parentSession);普通会话日志无种子段。
     const header = records.find(r => r?.type === 'session')