@morlay/session-rdb 0.1.0 → 0.1.2

package/src/sqlite.ts

@@ -52,7 +52,7 @@ import type { StorageRepository } from "./storage-takeover/types.ts";
 
 type SqliteDb = NodeSQLiteDatabase & { $client: DatabaseSync };
 
-/** 用量聚合的原始行（列名是 SQL 别名）。 */
+// 用量聚合的原始行（列名是 SQL 别名）。
 interface RawBucketRow {
   day: string;
   provider: string | null;
@@ -65,17 +65,17 @@ interface RawBucketRow {
   total_tokens: number | null;
 }
 
-/** 「是否子代理」两组的 token 合计行。 */
+// 「是否子代理」两组的 token 合计行。
 interface RawScopeRow extends RawBucketRow {}
 
-/** 按会话的行：token 一条查询、活动一条查询，按 session_id 合并。 */
+// 按会话的行：token 一条查询、活动一条查询，按 session_id 合并。
 interface RawSessionTokenRow extends RawBucketRow {
   session_id: string;
   title: string | null;
   archived: number;
 }
 
-/** `t_session_counts` 的原始行（四项计数，列名是 SQL 别名）。 */
+// `t_session_counts` 的原始行（四项计数，列名是 SQL 别名）。
 interface RawCountRow {
   turns: number | null;
   steps: number | null;
@@ -83,36 +83,37 @@ interface RawCountRow {
   tool_calls: number | null;
 }
 
-/** 按会话的活动计数行。 */
+// 按会话的活动计数行。
 interface RawSessionCountRow extends RawCountRow {
   session_id: string;
 }
 
-/** 活动总览行：是否子代理 + 四项计数。 */
+// 活动总览行：是否子代理 + 四项计数。
 interface RawActivityScopeRow extends RawCountRow {
   subagent: number | null;
 }
 
-/** 用量行的「被引用」物化表达式（`%EVENT%` 换成事件 id 列）。 */
+// 用量行的「被引用」物化表达式（`%EVENT%` 换成事件 id 列）。
 const EVENT_REFERENCED_SQL = `EXISTS (SELECT 1 FROM t_session_events rb
                                        WHERE rb.f_event_id = %EVENT%)`;
 
-/** 用量行的「被 subagent 会话引用」物化表达式（`%EVENT%` 换成事件 id 列）。 */
+// 用量行的「被 subagent 会话引用」物化表达式（`%EVENT%` 换成事件 id 列）。
 const EVENT_SUBAGENT_SQL = `EXISTS (SELECT 1 FROM t_session_events sb
                                      JOIN t_sessions ss ON ss.f_session_id = sb.f_session_id
                                     WHERE sb.f_event_id = %EVENT% AND ss.f_origin = 'subagent')`;
 
-/** `IN (...)` 用的类型字面量（与 `COUNTED_EVENT_TYPES` 同源）。 */
+// `IN (...)` 用的类型字面量（与 `COUNTED_EVENT_TYPES` 同源）。
 const COUNTED_EVENT_TYPE_SQL = COUNTED_EVENT_TYPES.map((type) => `'${type}'`).join(", ");
 
+// 引用标记的分批重算：一次绑定的参数有上限，按块走。
+const REFRESH_FLAG_CHUNK = 400;
+
 function withEvent(expression: string, column: string): string {
   return expression.replace("%EVENT%", column);
 }
 
-/**
- * 派生统计表的回填：任一表为空即按事件表全量重算（幂等；迁移删表重建后、手动清空后都靠它自愈）。
- * 顺序有依赖：用量行（带物化列）先落，两张会话汇总表再从它 / 事件表重算。
- */
+// 派生统计表的回填：任一表为空即按事件表全量重算（幂等；迁移删表重建后、手动清空后都靠它自愈）。
+// 顺序有依赖：用量行（带物化列）先落，两张会话汇总表再从它 / 事件表重算。
 function backfillUsageTables(db: DatabaseSync): void {
   backfillEventUsage(db);
   backfillSessionUsage(db);
@@ -124,7 +125,7 @@ function tableIsEmpty(db: DatabaseSync, table: string): boolean {
   return row.n === 0;
 }
 
-/** 用量行：一条 `assistant/message` 事件行一行，物化本地日与两个归属标记。 */
+// 用量行：一条 `assistant/message` 事件行一行，物化本地日与两个归属标记。
 function backfillEventUsage(db: DatabaseSync): void {
   if (!tableIsEmpty(db, "t_event_usage")) return;
   db.exec(`INSERT OR IGNORE INTO t_event_usage (
@@ -154,7 +155,7 @@ function backfillEventUsage(db: DatabaseSync): void {
             OR json_extract(e.f_data, '$.usage') IS NOT NULL)`);
 }
 
-/** 会话 × 本地日 × 模型的 token 汇总：从桥接行 × 用量行重算（含 fork 继承前缀）。 */
+// 会话 × 本地日 × 模型的 token 汇总：从桥接行 × 用量行重算（含 fork 继承前缀）。
 function backfillSessionUsage(db: DatabaseSync): void {
   if (!tableIsEmpty(db, "t_session_usage")) return;
   db.exec(`INSERT OR IGNORE INTO t_session_usage (
@@ -168,7 +169,7 @@ function backfillSessionUsage(db: DatabaseSync): void {
      GROUP BY b.f_session_id, u.f_day, coalesce(u.f_provider, ''), coalesce(u.f_model, '')`);
 }
 
-/** 会话 × 本地日的活动计数：从桥接行 × 事件类型重算。 */
+// 会话 × 本地日的活动计数：从桥接行 × 事件类型重算。
 function backfillSessionCounts(db: DatabaseSync): void {
   if (!tableIsEmpty(db, "t_session_counts")) return;
   db.exec(`INSERT OR IGNORE INTO t_session_counts (
@@ -200,7 +201,7 @@ function sessionListRowOf(row: Record<string, unknown>): SessionListRowRecord {
   };
 }
 
-/** SQL 的缺失求和是 NULL：没有 usage 字段的行使该字段计 0。 */
+// SQL 的缺失求和是 NULL：没有 usage 字段的行使该字段计 0。
 function tokenTotalsOf(row: {
   input_tokens: number | null;
   output_tokens: number | null;
@@ -217,7 +218,7 @@ function tokenTotalsOf(row: {
   };
 }
 
-/** `t_session_counts` 的原始行（列名是 SQL 别名）折成四项活动计数。 */
+// `t_session_counts` 的原始行（列名是 SQL 别名）折成四项活动计数。
 function activityTotalsOf(row: {
   turns: number | null;
   steps: number | null;
@@ -232,12 +233,12 @@ function activityTotalsOf(row: {
   };
 }
 
-/** 一行的整套指标：token 用量 + 活动计数（轮次 / 步骤 / 用户输入 / 工具调用）。 */
+// 一行的整套指标：token 用量 + 活动计数（轮次 / 步骤 / 用户输入 / 工具调用）。
 function emptyActivity(): UsageActivityTotals {
   return { turns: 0, steps: 0, userInputs: 0, toolCalls: 0 };
 }
 
-/** 有 token 用量的会话：活动计数与列表都限定在这一批会话里，口径一致（读汇总表，几百行）。 */
+// 有 token 用量的会话：活动计数与列表都限定在这一批会话里，口径一致（读汇总表，几百行）。
 function hasUsageSession(column: string): string {
   return `EXISTS (SELECT 1 FROM t_session_usage ub WHERE ub.f_session_id = ${column})`;
 }
@@ -694,11 +695,13 @@ export class SqliteBackend implements Backend {
       .run();
   }
 
-  private async deleteBridgeTail(id: SessionId, fromSequence: number): Promise<void> {
-    this.db
-      .delete(tSessionEvents)
-      .where(and(eq(tSessionEvents.fSessionId, id), gte(tSessionEvents.fSequence, fromSequence)))
-      .run();
+  private async deleteBridgeTail(id: SessionId, fromSequence: number): Promise<readonly string[]> {
+    const rows = this.db.$client
+      .prepare(
+        "DELETE FROM t_session_events WHERE f_session_id = ? AND f_sequence >= ? RETURNING f_event_id",
+      )
+      .all(id, fromSequence) as Array<{ f_event_id: string }>;
+    return rows.map((row) => row.f_event_id);
   }
 
   private async getPrevBridge(
@@ -712,14 +715,17 @@ export class SqliteBackend implements Backend {
       .get() as { fEventId: string; fSequence: number } | undefined;
   }
 
-  private async deleteSession(id: SessionId): Promise<void> {
-    this.db.delete(tSessionEvents).where(eq(tSessionEvents.fSessionId, id)).run();
+  private async deleteSession(id: SessionId): Promise<readonly string[]> {
+    const rows = this.db.$client
+      .prepare("DELETE FROM t_session_events WHERE f_session_id = ? RETURNING f_event_id")
+      .all(id) as Array<{ f_event_id: string }>;
     this.db.delete(tWorkspaceSessions).where(eq(tWorkspaceSessions.fSessionId, id)).run();
     this.db.delete(tSessionProjcacheRows).where(eq(tSessionProjcacheRows.fSessionId, id)).run();
     this.db.delete(tSessions).where(eq(tSessions.fSessionId, id)).run();
+    return rows.map((row) => row.f_event_id);
   }
 
-  /** 事件行可能被多个会话共享（fork 派生），所以孤儿只能在全库范围内判定。 */
+  // 事件行可能被多个会话共享（fork 派生），所以孤儿只能在全库范围内判定。
   async collectOrphans(): Promise<number> {
     const referenced = this.db.select({ fEventId: tSessionEvents.fEventId }).from(tSessionEvents);
     const info = this.db.delete(tEvents).where(notInArray(tEvents.fEventId, referenced)).run();
@@ -736,7 +742,7 @@ export class SqliteBackend implements Backend {
     return Number(info.changes);
   }
 
-  /** 父会话被删后留下的 subagent 会话：父已不在表里，或本来就没有父。 */
+  // 父会话被删后留下的 subagent 会话：父已不在表里，或本来就没有父。
   async listOrphanSubagentSessions(): Promise<SessionId[]> {
     const rows = this.db.$client
       .prepare(
@@ -749,23 +755,28 @@ export class SqliteBackend implements Backend {
     return rows.map((row) => row.id as SessionId);
   }
 
-  private async deleteSessions(ids: SessionId[]): Promise<number> {
-    if (ids.length === 0) return 0;
-    this.db.delete(tSessionEvents).where(inArray(tSessionEvents.fSessionId, ids)).run();
+  private async deleteSessions(
+    ids: SessionId[],
+  ): Promise<{ deleted: number; eventIds: readonly string[] }> {
+    if (ids.length === 0) return { deleted: 0, eventIds: [] };
+    const placeholders = ids.map(() => "?").join(", ");
+    const rows = this.db.$client
+      .prepare(
+        `DELETE FROM t_session_events WHERE f_session_id IN (${placeholders}) RETURNING f_event_id`,
+      )
+      .all(...ids) as Array<{ f_event_id: string }>;
     this.db.delete(tWorkspaceSessions).where(inArray(tWorkspaceSessions.fSessionId, ids)).run();
     this.db
       .delete(tSessionProjcacheRows)
       .where(inArray(tSessionProjcacheRows.fSessionId, ids))
       .run();
     const info = this.db.delete(tSessions).where(inArray(tSessions.fSessionId, ids)).run();
-    return Number(info.changes);
+    return { deleted: Number(info.changes), eventIds: rows.map((row) => row.f_event_id) };
   }
 
-  /**
-   * 用量聚合：token 用量沿 `t_event_usage` 的用量行，活动计数（轮次 / 步骤 / 用户输入 / 工具调用）
-   * 沿 `t_events` 的事件类型数——两者限定在**有 token 用量的会话**里，时间范围各自按自己的
-   * `f_created_at`（同一时刻写入，口径一致）。
-   */
+  // 用量聚合：token 用量沿 `t_event_usage` 的用量行，活动计数（轮次 / 步骤 / 用户输入 / 工具调用）
+  // 沿 `t_events` 的事件类型数——两者限定在**有 token 用量的会话**里，时间范围各自按自己的
+  // `f_created_at`（同一时刻写入，口径一致）。
   async listSessionRows(query: SessionListRowsQuery = {}): Promise<SessionListRowsPage> {
     const needle = query.query?.trim().toLowerCase() ?? "";
     const like = `%${needle}%`;
@@ -812,12 +823,9 @@ export class SqliteBackend implements Backend {
     };
   }
 
-  /**
-   * 用量聚合：只读三张派生统计表——事件级用量行给去重口径的总量与「天 × 模型」桶，
-   * `t_session_usage` / `t_session_counts` 给按会话的行（含 fork 继承前缀）。
-   * 归属、本地日与「是否被引用」都是物化列，这里不再现算、也不回连事件表。
-   * 事件级按毫秒时间戳过滤、汇总表按本地日过滤——`sinceMs` 对齐到本地零点时两者等价。
-   */
+  // 用量聚合：只读三张派生统计表——事件级用量行给去重口径的总量与「天 × 模型」桶，`t_session_usage` /
+  // `t_session_counts` 给按会话的行（含 fork 继承前缀）；归属、本地日与「是否被引用」都是物化列，不再现算、也不
+  // 回连事件表。事件级按毫秒过滤、汇总表按本地日过滤，`sinceMs` 对齐本地零点时两者等价。
   async usageReport(sinceMs?: number): Promise<UsageAggregate> {
     const usageSince = sinceMs === undefined ? "" : " AND f_created_at >= ?";
     const params = sinceMs === undefined ? [] : [sinceMs];
@@ -932,7 +940,7 @@ export class SqliteBackend implements Backend {
     };
   }
 
-  /** token 用量旁路累加：派生表 `t_session_usage`，不在写事务里（失败可丢，表可销毁重建）。 */
+  // token 用量旁路累加：派生表 `t_session_usage`，不在写事务里（失败可丢，表可销毁重建）。
   async incrementSessionUsage(
     id: SessionId,
     buckets: readonly SessionUsageBucket[],
@@ -964,7 +972,7 @@ export class SqliteBackend implements Backend {
     }
   }
 
-  /** 活动计数旁路累加：派生表 `t_session_counts`，同上（四项计数一次落）。 */
+  // 活动计数旁路累加：派生表 `t_session_counts`，同上（四项计数一次落）。
   async incrementSessionCounts(
     id: SessionId,
     buckets: readonly SessionCountBucket[],
@@ -991,7 +999,7 @@ export class SqliteBackend implements Backend {
     }
   }
 
-  /** 按会话重算两张汇总表（rewind / fork 之后）：先删该会话的行，再从事件表重算。 */
+  // 按会话重算两张汇总表（rewind / fork 之后）：先删该会话的行，再从事件表重算。
   async rebuildSessionStats(id: SessionId): Promise<void> {
     this.db.$client.prepare("DELETE FROM t_session_usage WHERE f_session_id = ?").run(id);
     this.db.$client
@@ -1027,17 +1035,21 @@ export class SqliteBackend implements Backend {
       .run(id);
   }
 
-  /**
-   * 全量重算用量行的引用标记：rewind 截断 / fork 复用 / 会话删除都会让「引用」跨会话变化，
-   * 只按本会话判定不够。低频路径，一次全表 UPDATE（3 万行量级）。
-   */
-  async refreshEventUsageFlags(): Promise<void> {
-    const eventId = "t_event_usage.f_event_id";
-    this.db.$client.exec(
-      `UPDATE t_event_usage SET
-         f_referenced = ${withEvent(EVENT_REFERENCED_SQL, eventId)},
-         f_subagent = ${withEvent(EVENT_SUBAGENT_SQL, eventId)}`,
-    );
+  // 重算这些用量行的引用标记：引用只会在「这些事件行的桥接行集合变化」时才变，所以按事件 id 收口。
+  // 全表 UPDATE（3 万行量级、秒级）没有调用点了：撤回与 fork 都不该动统计。
+  async refreshEventUsageFlags(eventIds: readonly string[]): Promise<void> {
+    for (let at = 0; at < eventIds.length; at += REFRESH_FLAG_CHUNK) {
+      const chunk = eventIds.slice(at, at + REFRESH_FLAG_CHUNK);
+      const placeholders = chunk.map(() => "?").join(", ");
+      this.db.$client
+        .prepare(
+          `UPDATE t_event_usage SET
+             f_referenced = ${withEvent(EVENT_REFERENCED_SQL, "f_event_id")},
+             f_subagent = ${withEvent(EVENT_SUBAGENT_SQL, "f_event_id")}
+           WHERE f_event_id IN (${placeholders})`,
+        )
+        .run(...chunk);
+    }
   }
 
   async deleteSessionStats(id: SessionId): Promise<void> {

package/src/storage-takeover/projection-cache.ts

@@ -27,7 +27,7 @@ type CurrentCheckpointIdentity = CheckpointIdentity & {
   inheritedEventCount: number;
 };
 
-/** header 能证明的生命周期身份（上游 0.1.7 的 header-only 匹配口径）。 */
+// header 能证明的生命周期身份（header-only 匹配口径）。
 type LifecycleIdentity = CheckpointIdentity & {
   formatVersion: number;
   isSeeded: boolean;
@@ -101,10 +101,8 @@ export class SessionProjectionCacheRdb extends Service {
     return identityMatches(record.identity, expected) ? record : undefined;
   }
 
-  /**
-   * header-only 读（会话列表这类）：上游 0.1.7 起只给 header 与 keys——它要求的是**生命周期**身份，
-   * 不再要求调用方提供 inherited cut（那个 cut 只有写路径与 hydration 用得上）。
-   */
+  // header-only 读（会话列表这类）：只给 header 与 keys，要求的是**生命周期**身份，不需要调用方提供
+  // inherited cut（那个只有写路径与 hydration 用得上）。
   cachedSnapshot(
     meta: SessionHeader,
     keys?: readonly Extract<keyof SessionProjectionMap, string>[],
@@ -336,7 +334,7 @@ function detachJson(
   return JSON.parse(text) as Record<string, ProjectionCheckpointRow>;
 }
 
-/** header 能证明的生命周期身份（不含 inherited cut）：header-only 读只比对它。 */
+// header 能证明的生命周期身份（不含 inherited cut）：header-only 读只比对它。
 function lifecycleIdentityOf(header: SessionHeader): LifecycleIdentity {
   return {
     formatVersion: header.version,
@@ -382,8 +380,8 @@ function lifecycleIdentityMatches(
   stored: CheckpointIdentity,
   expected: LifecycleIdentity,
 ): boolean {
-  // header-only 读的匹配口径（上游 0.1.7）：只看 formatVersion 与生命周期字段，**不比对 inherited cut**
-  // ——那个 cut 只有写路径与 hydration 用得上。
+  // header-only 读的匹配口径：只看 formatVersion 与生命周期字段，**不比对 inherited cut**（那个只有写路径与
+  // hydration 用得上）。
   return (
     stored.createdAt === expected.createdAt &&
     stored.cwd === expected.cwd &&

package/src/storage-takeover/repository.ts

@@ -21,7 +21,7 @@ import type {
 export interface StorageRepositoryHost {
   db: () => Promise<unknown>;
 
-  /** 不经 await、直接拿到的数据库句柄；未开放时只走异步的 `db`。 */
+  // 不经 await、直接拿到的数据库句柄；未开放时只走异步的 `db`。
   dbDirect?: () => unknown;
 
   tables: Record<string, unknown>;
@@ -273,7 +273,7 @@ export function createStorageRepository(host: StorageRepositoryHost): StorageRep
 
         // 钉住：未在集合里的清掉，集合里的按数组位置写序号（读回即按它排序）。
         // 找不到会话行的 id 跳过：pin 只作用于已存在的会话（与归档不同，不凭空造行）。
-        // 旧 storages 文档（0.1.6 时代）没有这个集合，导入路径按空处理。
+        // 既有 storages 文档里可能没有这个集合，导入路径按空处理。
         const pinned = state.pinnedSessionIds ?? [];
         await runQuery(
           pinned.length === 0

package/src/storage-takeover/types.ts

@@ -37,7 +37,7 @@ export interface StorageRepository {
 
   loadProjcache(): Promise<StoredProjcacheEntry[]>;
 
-  /** 不经 await、直接读的路径（供同步的 `cachedSnapshot` 消费）；宿主提供不了则缺省。 */
+  // 不经 await、直接读的路径（供同步的 `cachedSnapshot` 消费）；宿主提供不了则缺省。
   readProjcacheDirect?(sessionId: string): StoredProjcacheEntry | undefined;
 
   readSessionTitleDirect?(sessionId: string): { title: string; seq: number } | undefined;

package/src/usage.ts

@@ -1,12 +1,11 @@
 import type { Context } from "@deepseek-ai/cordis";
+import { SESSION_USAGE_PATH } from "./routes.ts";
 import type { SessionPersistenceRdb } from "./index.ts";
 
-export const SESSION_USAGE_PATH = "/api/session.usage";
+export { SESSION_USAGE_PATH };
 
-/**
- * 时间范围的语义键：`all` 不限；`day` / `week` 是**本地自然日 / 自然周**（周一起算）；
- * `7d` / `30d` / `90d` 是**最近 N 个自然日**（含今天）。
- */
+// 时间范围的语义键：`all` 不限；`day` / `week` 是**本地自然日 / 自然周**（周一起算）；
+// `7d` / `30d` / `90d` 是**最近 N 个自然日**（含今天）。
 export type UsageRangeKey = "all" | "day" | "week" | "7d" | "30d" | "90d";
 
 const ROLLING_DAYS: Record<"7d" | "30d" | "90d", number> = { "7d": 7, "30d": 30, "90d": 90 };
@@ -17,14 +16,9 @@ function localDayStart(now: number): Date {
   return start;
 }
 
-/**
- * 范围起点（含），不限时为 undefined。**所有起点都对齐到 host 本地时区的零点**——`day` / `week` 是
- * 今天 / 本周一的零点，`7d` / `30d` / `90d` 是「今天零点往前 N-1 天」（含今天共 N 个自然日）。
- * 对齐的意义：事件级表按毫秒过滤、会话汇总表按本地日过滤，两者因此严格等价。
- * @param range - 语义键。
- * @param now - 当前时刻。
- * @returns 起点毫秒时间戳，或 undefined。
- */
+// 范围起点（含），`all` 时 undefined。**所有起点都对齐到 host 本地时区的零点**——`day` / `week` 是今天 / 本周一
+// 的零点，`7d` / `30d` / `90d` 是「今天零点往前 N-1 天」（含今天共 N 个自然日）：事件级表按毫秒过滤、会话汇总表
+// 按本地日过滤，两者因此严格等价。
 export function resolveUsageSince(range: UsageRangeKey, now: number): number | undefined {
   switch (range) {
     case "all":
@@ -52,7 +46,7 @@ function parseUsageRange(value: unknown): UsageRangeKey {
     : "all";
 }
 
-/** 一段 token 用量（字段直接取事件里模型报的 usage）。 */
+// 一段 token 用量（字段直接取事件里模型报的 usage）。
 export interface UsageTokenTotals {
   inputTokens: number;
   outputTokens: number;
@@ -61,10 +55,8 @@ export interface UsageTokenTotals {
   totalTokens: number;
 }
 
-/**
- * 活动计数：与 token 用量同一时间范围、同一去重口径（只算被会话引用的事件行），
- * 按事件类型数出来——「轮次 / 步骤 / 用户输入 / 工具调用」比「事件行数」有信息量。
- */
+// 活动计数：与 token 用量同一时间范围、同一去重口径（只算被会话引用的事件行），
+// 按事件类型数出来——「轮次 / 步骤 / 用户输入 / 工具调用」比「事件行数」有信息量。
 export interface UsageActivityTotals {
   turns: number;
   steps: number;
@@ -72,13 +64,11 @@ export interface UsageActivityTotals {
   toolCalls: number;
 }
 
-/** 总量与按会话行用的一整套指标（token + 活动）。 */
+// 总量与按会话行用的一整套指标（token + 活动）。
 export interface UsageTotals extends UsageTokenTotals, UsageActivityTotals {}
 
-/**
- * 一天 × 一个模型 × 是否子代理 的用量桶：总览、按天、按模型都由它折叠。
- * 只有 token 用量——活动计数没有模型归属（一个轮次可能跨模型），挂在总量与按会话行上。
- */
+// 一天 × 一个模型 × 是否子代理 的用量桶：总览、按天、按模型都由它折叠。
+// 只有 token 用量——活动计数没有模型归属（一个轮次可能跨模型），挂在总量与按会话行上。
 export interface UsageBucket extends UsageTokenTotals {
   day: string;
   provider: string | null;
@@ -86,7 +76,7 @@ export interface UsageBucket extends UsageTokenTotals {
   subagent: boolean;
 }
 
-/** 一条会话的用量行。 */
+// 一条会话的用量行。
 export interface UsageSessionRow extends UsageTotals {
   sessionId: string;
   title: string | null;
@@ -94,7 +84,7 @@ export interface UsageSessionRow extends UsageTotals {
   archived: boolean;
 }
 
-/** 后端的原始聚合结果（总量 / 其中子代理 / 人类、按天×模型的桶、按会话的行）。 */
+// 后端的原始聚合结果（总量 / 其中子代理 / 人类、按天×模型的桶、按会话的行）。
 export interface UsageAggregate {
   totals: UsageTotals;
   subagent: UsageTotals;
@@ -103,10 +93,10 @@ export interface UsageAggregate {
   sessions: UsageSessionRow[];
 }
 
-/** 一次统计请求的完整回报。 */
+// 一次统计请求的完整回报。
 export type SessionUsageReport = UsageAggregate;
 
-/** 计入活动计数的事件类型（轮次 / 步骤 / 用户输入 / 工具调用）。 */
+// 计入活动计数的事件类型（轮次 / 步骤 / 用户输入 / 工具调用）。
 export const COUNTED_EVENT_TYPES = [
   "turn/start",
   "step/start",
@@ -114,7 +104,7 @@ export const COUNTED_EVENT_TYPES = [
   "tool/call",
 ] as const;
 
-/** 按事件类型把计数累加到活动指标上（表里按类型存，读的时候折成四项）。 */
+// 按事件类型把计数累加到活动指标上（表里按类型存，读的时候折成四项）。
 export function addActivityCount(
   target: UsageActivityTotals,
   type: string,
@@ -138,7 +128,7 @@ export function addActivityCount(
   }
 }
 
-/** 毫秒时间戳 → host 本地日（`YYYY-MM-DD`，与 SQL 的 localtime 口径一致）。 */
+// 毫秒时间戳 → host 本地日（`YYYY-MM-DD`，与 SQL 的 localtime 口径一致）。
 export function localDayKey(ms: number): string {
   const date = new Date(ms);
   const pad = (value: number): string => String(value).padStart(2, "0");
@@ -179,17 +169,15 @@ export function addActivityTotals(
   return target;
 }
 
-/** 把一行的整套指标累加进目标（后端合并「是否子代理」两组时用）。 */
+// 把一行的整套指标累加进目标（后端合并「是否子代理」两组时用）。
 export function addTotals(target: UsageTotals, row: UsageTotals): UsageTotals {
   addActivityTotals(target, row);
   addTokenTotals(target, row);
   return target;
 }
 
-/**
- * 用量统计通道：一次请求回报总览（含 subagent 拆分）、按天 × 模型的桶与按会话的行。
- * 聚合只算被会话引用的事件行——fork 共享行因此只计一次，已删会话留下的孤儿行不计。
- */
+// 用量统计通道：一次请求回报总览（含 subagent 拆分）、按天 × 模型的桶与按会话的行。
+// 聚合只算被会话引用的事件行——fork 共享行因此只计一次，已删会话留下的孤儿行不计。
 export function registerSessionUsage(ctx: Context, persistence: SessionPersistenceRdb): void {
   ctx.inject(["webServer", "connection"] as const, (webCtx) => {
     const webServer = webCtx.webServer as unknown as {

package/src/write-guard.ts

@@ -7,7 +7,7 @@ export class WriteGuard {
     this.headSeqs.set(id, head);
   }
 
-  /** 本实例有没有这条会话的 head 记录（迁移重写用它决定是"登记基准"还是"严格比较"）。 */
+  // 本实例有没有这条会话的 head 记录（迁移重写用它决定是"登记基准"还是"严格比较"）。
   has(id: SessionId): boolean {
     return this.headSeqs.has(id);
   }