@morlay/session-rdb 0.1.0 → 0.1.2

package/src/log.ts

@@ -133,11 +133,9 @@ const SURFACE_EVENT_TYPES = new Set([
 
 const METERING_EVENT_TYPES = new Set(["compaction/summary", "compaction/prune"]);
 
-/**
- * 升序的 surface 事件 seq 索引：读视图修复里的溯源（replace 的 `sourceEventSeqs` 与
- * metering 的 `shadowedSeqs`）共用这一份，避免每个 replace 各扫一遍全量事件。
- * 前提是输入按 seq 有序（`readLog` 与 live snapshot 都如此）。
- */
+// 升序的 surface 事件 seq 索引：读视图修复里的溯源（replace 的 `sourceEventSeqs` 与
+// metering 的 `shadowedSeqs`）共用这一份，避免每个 replace 各扫一遍全量事件。
+// 前提是输入按 seq 有序（`readLog` 与 live snapshot 都如此）。
 function surfaceSeqIndex(events: readonly SessionEvent[]): number[] {
   const seqs: number[] = [];
   for (const event of events) {
@@ -146,7 +144,7 @@ function surfaceSeqIndex(events: readonly SessionEvent[]): number[] {
   return seqs;
 }
 
-/** `[startSeq, endSeq]` 内的 surface seq（含端点），二分定位后切片。 */
+// `[startSeq, endSeq]` 内的 surface seq（含端点），二分定位后切片。
 function surfaceSeqsInRange(seqs: readonly number[], startSeq: number, endSeq: number): number[] {
   let low = 0;
   let high = seqs.length;
@@ -461,20 +459,11 @@ export function renameLegacyPtcEvents(events: SessionEvent[]): void {
   }
 }
 
-/**
- * 把**旧代（v3 及更早）的消息形状**归一到当前格式（v4）：迁移链（严格）拒绝那些形状时，读路径仍要
- * 能把它们读出来——只动字段与标记，不改坐标、不改内容。
- *
- * 三件事：
- * - `system/message` 的 source：`{ kind: 'plugin', plugin: '@deepseek-ai/dsh-system-prompt' }` → `{ kind: 'system-prompt' }`
- *   （v4 起 system 消息只认这个 kind）；
- * - `tool/result` 的消息：v3 是 user 角色、结果块包在 `content[0]`；v4 是 `role: 'tool'` + 顶层
- *   `toolCallId` + `content` 就是结果块；
- * - **本仓库自造、上游不认识的事件类型**（见 `OWN_EVENT_TYPES`：历史遗留的与我们当前在写的）标
- *   `ignorable: true`——v4 的校验对未知类型只接受可忽略信封。
- *
- * 只认这张白名单：**其它未知类型保持 fail loud**（那是「数据来自更新的 harness」的信号，不能吞掉）。
- */
+// 把**旧代（v3 及更早）的消息形状**归一到当前格式（v4）：迁移链（严格）拒绝那些形状时，读路径仍要能把它们
+// 读出来——只动字段与标记，不改坐标、不改内容。三件事：`system/message` 的 source 去掉 plugin 形状（v4 只认
+// `{ kind: 'system-prompt' }`）、`tool/result` 改成 `role: 'tool'` + 顶层 `toolCallId`、`OWN_EVENT_TYPES` 里的
+// 事件补 `ignorable: true` 信封。
+// 只认这张白名单：**其它未知类型保持 fail loud**（那是「数据来自更新的 harness」的信号，不能吞掉）。
 export function normalizeToCurrentShape(events: SessionEvent[]): void {
   for (const event of events) {
     const type = (event as { type: string }).type;
@@ -520,15 +509,9 @@ function liftToolResultMessage(message: unknown): void {
   record["source"] = { kind: "tool", callId };
 }
 
-/**
- * 落库前给**本仓库自造的事件类型**补上 `ignorable: true` 信封。
- *
- * 上游的持久化校验（`validateStoredEvents`）只放行「已知类型」或「带可忽略信封的未知类型」，我们的类型
- * 按构造就在已知表之外——不补的话连**写入**都会被拒（`appendBatch` 里那道校验）。上游 `Session.append`
- * 没有承载这个信封的口子（第三个参数只服务 surface 事件），所以这一笔由持久化层补：canonical log 里的
- * 形状不变，落库的那一份带上信封。
- * @param events - 即将落库的批次（`materializeAppendBatch` 的 JSON 快照副本，可写）。
- */
+// 落库前给**本仓库自造的事件类型**补上 `ignorable: true` 信封：上游持久化校验（`validateStoredEvents`）只放行
+// 「已知类型」或「带可忽略信封的未知类型」，不补连写入都会被拒。`Session.append` 没有承载信封的口子，所以这一笔
+// 由持久化层补——canonical log 的形状不变，落库的那一份带上信封；`events` 是即将落库的批次（可写）。
 export function sealOwnEvents(events: readonly SessionEvent[]): void {
   for (const event of events) {
     if (OWN_EVENT_TYPES.has((event as { type: string }).type)) {
@@ -537,25 +520,19 @@ export function sealOwnEvents(events: readonly SessionEvent[]): void {
   }
 }
 
-/**
- * 本仓库自造、上游不认识的事件类型：读的时候标 `ignorable: true`，v4 的持久化校验才肯跳过它们
- * （`validateStoredEvents` 只放行「已知类型」或「带可忽略信封的未知类型」）。
- *
- * 两类都在这张表里：
- * - **历史遗留**：写过、后来连同机制一起删除的（`session-branch/version`）；
- * - **当前在写**：本仓库的插件自己声明的事件类型（`session-mode/selected`）——上游的
- *   `KNOWN_SESSION_EVENT_TYPES` 由上游仓库的声明生成，外部插件的事件按构造就在它之外。
- *
- * 新增自造事件类型时**必须**登记到这里，否则读路径 fail loud（真回归：`session-mode/selected` 漏登记，
- * 会话打不开）。**不要**用「所有未知类型」代替（那会掩盖更新版本的未知事件——那种必须拒读）。
- */
+// 本仓库自造、上游不认识的事件类型：读的时候标 `ignorable: true`，v4 的持久化校验才肯跳过它们
+// （`validateStoredEvents` 只放行「已知类型」或「带可忽略信封的未知类型」）。两类都在表里：既有日志里会出现、
+// 但本仓库不再产出的 `session-branch/version`，与当前在写的 `session-mode/selected`（上游已知类型表由上游仓库
+// 的声明生成，外部插件的事件按构造就在它之外）。
+// 新增自造事件类型时**必须**登记到这里，否则读路径 fail loud。**不要**用「所有未知类型」代替（那会掩盖更新
+// 版本的未知事件——那种必须拒读）。
 export const OWN_EVENT_TYPES: ReadonlySet<string> = new Set([
   "session-branch/version",
   "session-mode/selected",
 ]);
 
-/** 这批事件是否需要按当前形状归一（旧代消息形状，或尚未标 `ignorable` 的自造事件类型）——写路径曾把回退
- * 视图的结果以当前版本号落库，所以**版本号不可信**，读之前要按内容判一次。 */
+// 这批事件是否需要按当前形状归一（旧代消息形状，或尚未标 `ignorable` 的自造事件类型）——既有日志里可能有以
+// 当前版本号落库的回退视图结果，所以**版本号不可信**，读之前要按内容判一次。
 export function needsShapeAdoption(events: readonly SessionEvent[]): boolean {
   for (const event of events) {
     const type = (event as { type: string }).type;
@@ -745,7 +722,7 @@ export function titleOfEventData(data: string): string | undefined {
   }
 }
 
-/** 用量行的列（`t_event_usage`）：读侧维度（本地日与两个归属标记）在写入时一起物化。 */
+// 用量行的列（`t_event_usage`）：读侧维度（本地日与两个归属标记）在写入时一起物化。
 export interface EventUsageRow {
   fEventId: string;
   fCreatedAt: number;
@@ -769,15 +746,9 @@ function textField(value: unknown): string | null {
   return typeof value === "string" && value !== "" ? value : null;
 }
 
-/**
- * 一条事件行的用量（只有带 `usage` 的 `assistant/message` 才有）：写路径据此记录
- * `t_event_usage`，统计因此不必逐行解析 JSON。两种 `f_data` 结构（带信封 / 老格式）都认。
- * 读侧维度一起物化：本地日由事件时间算，`f_referenced` 直接 1（这一批事件行与桥接行同事务，
- * 提交即被引用），`f_subagent` 取写入它的会话是否子代理。
- * @param event - 待写入的事件行。
- * @param subagent - 写入它的会话是否 `origin === 'subagent'`。
- * @returns 用量行，或该事件没有用量时的 undefined。
- */
+// 一条事件行的用量（只有带 `usage` 的 `assistant/message` 才有；没有用量时为 undefined）：写路径据此记录
+// `t_event_usage`，统计因此不必逐行解析 JSON，两种 `f_data` 结构（带信封 / 老格式）都认。读侧维度一起物化：
+// 本地日由事件时间算，`f_referenced` 直接 1（这一批事件行与桥接行同事务），`f_subagent` 取写入它的会话是否子代理。
 export function usageRowOf(
   event: {
     fEventId: string;

package/src/postgres.ts

@@ -38,7 +38,10 @@ const postgresMigrationsDir = fileURLToPath(new URL("../drizzle/postgres/", impo
 
 const pgWriteQueues = new Map<string, Promise<void>>();
 
-/** 按介质（连接串 + schema）串行化写事务，与 SQLite 侧的 `enqueueSqliteTx` 同形。 */
+// 引用标记的分批重算：一次绑定的参数有上限，按块走（与 sqlite 侧同值）。
+const REFRESH_FLAG_CHUNK = 400;
+
+// 按介质（连接串 + schema）串行化写事务，与 SQLite 侧的 `enqueueSqliteTx` 同形。
 function enqueuePgWrite<T>(key: string, fn: () => Promise<T>): Promise<T> {
   const tail = pgWriteQueues.get(key) ?? Promise.resolve();
   const run = tail.then(fn);
@@ -52,18 +55,18 @@ function enqueuePgWrite<T>(key: string, fn: () => Promise<T>): Promise<T> {
   return run;
 }
 
-/** pg 的 text 列窄化：非字符串（含 null）都不当作文本。 */
+// pg 的 text 列窄化：非字符串（含 null）都不当作文本。
 function text(value: unknown): string | null {
   return typeof value === "string" ? value : null;
 }
 
-/** pg 的 count/sum 回落成字符串：统一转成有限数。 */
+// pg 的 count/sum 回落成字符串：统一转成有限数。
 function numeric(value: unknown): number {
   const parsed = typeof value === "number" ? value : Number(value ?? 0);
   return Number.isFinite(parsed) ? parsed : 0;
 }
 
-/** SQL 的缺失求和是 NULL：没有 usage 字段的行使该字段计 0。 */
+// SQL 的缺失求和是 NULL：没有 usage 字段的行使该字段计 0。
 function tokenTotalsOf(row: Record<string, unknown>): UsageTokenTotals {
   return {
     inputTokens: numeric(row["input_tokens"]),
@@ -78,7 +81,7 @@ function emptyActivity(): UsageActivityTotals {
   return { turns: 0, steps: 0, userInputs: 0, toolCalls: 0 };
 }
 
-/** `t_session_counts` 的四项计数折成活动计数（pg 的 sum 回落成字符串）。 */
+// `t_session_counts` 的四项计数折成活动计数（pg 的 sum 回落成字符串）。
 function activityTotalsOf(row: Record<string, unknown>): UsageActivityTotals {
   return {
     turns: numeric(row["turns"]),
@@ -88,7 +91,7 @@ function activityTotalsOf(row: Record<string, unknown>): UsageActivityTotals {
   };
 }
 
-/** `IN (...)` 用的类型字面量（与 `COUNTED_EVENT_TYPES` 同源）。 */
+// `IN (...)` 用的类型字面量（与 `COUNTED_EVENT_TYPES` 同源）。
 const COUNTED_EVENT_TYPE_SQL = COUNTED_EVENT_TYPES.map((type) => `'${type}'`).join(", ");
 
 export interface PostgresBackendOptions {
@@ -124,10 +127,9 @@ export class PostgresBackend implements Backend {
     });
 
     this.opened.catch(() => {});
-    // 写事务按介质串行（与 SQLite 侧的 enqueueSqliteTx 同形）：并发 `writeAtomically`
-    // 会互相覆盖实例级的 `txOverride`，让先开始的事务的语句落到别人的事务（一次失败
-    // 会把另一个成功事务一起拖垮），或退化成 autocommit。介质身份用 `identityBase`
-    // （宿主 + 库 + schema）——同一进程内多实例连同一库时也共用同一条队列。
+    // 写事务按介质串行（与 SQLite 侧 `enqueueSqliteTx` 同形）：并发 `writeAtomically` 会互相覆盖实例级的
+    // `txOverride`，让语句落进别人的事务或退化成 autocommit；介质身份用 `identityBase`（宿主 + 库 + schema），
+    // 同一进程内多实例连同一库时共用同一条队列。
     const writeQueueKey = options.identityBase;
     this.storage = createStorageRepository({
       db: () => this.opened.then(() => this.txOverride ?? this.db),
@@ -486,26 +488,22 @@ export class PostgresBackend implements Backend {
     exec: PgAsyncDatabase<NodePgQueryResultHKT>,
     id: SessionId,
     fromSequence: number,
-  ): Promise<void> {
-    await exec
-      .delete(this.tables["t_session_events"])
-      .where(
-        and(
-          eq(this.tables["t_session_events"].fSessionId, id),
-          gte(this.tables["t_session_events"].fSequence, fromSequence),
-        ),
-      )
-      .execute();
+  ): Promise<readonly string[]> {
+    const table = this.tables["t_session_events"];
+    const result = (await exec.execute(sql`
+      DELETE FROM ${table} WHERE f_session_id = ${id} AND f_sequence >= ${fromSequence}
+      RETURNING f_event_id
+    `)) as unknown as { rows: Array<{ f_event_id: string }> };
+    return result.rows.map((row) => row.f_event_id);
   }
 
   private async deleteSession(
     exec: PgAsyncDatabase<NodePgQueryResultHKT>,
     id: SessionId,
-  ): Promise<void> {
-    await exec
-      .delete(this.tables["t_session_events"])
-      .where(eq(this.tables["t_session_events"].fSessionId, id))
-      .execute();
+  ): Promise<readonly string[]> {
+    const result = (await exec.execute(sql`
+      DELETE FROM ${this.tables["t_session_events"]} WHERE f_session_id = ${id} RETURNING f_event_id
+    `)) as unknown as { rows: Array<{ f_event_id: string }> };
     await exec
       .delete(this.tables["t_workspace_sessions"])
       .where(eq(this.tables["t_workspace_sessions"].fSessionId, id))
@@ -518,9 +516,10 @@ export class PostgresBackend implements Backend {
       .delete(this.tables["t_sessions"])
       .where(eq(this.tables["t_sessions"].fSessionId, id))
       .execute();
+    return result.rows.map((row) => row.f_event_id);
   }
 
-  /** 事件行可能被多个会话共享（fork 派生），所以孤儿只能在全库范围内判定。 */
+  // 事件行可能被多个会话共享（fork 派生），所以孤儿只能在全库范围内判定。
   async collectOrphans(): Promise<number> {
     const tEvents = this.tables["t_events"];
     const tEventUsage = this.tables["t_event_usage"];
@@ -547,7 +546,7 @@ export class PostgresBackend implements Backend {
     return result.rowCount ?? 0;
   }
 
-  /** 父会话被删后留下的 subagent 会话：父已不在表里，或本来就没有父。 */
+  // 父会话被删后留下的 subagent 会话：父已不在表里，或本来就没有父。
   async listOrphanSubagentSessions(): Promise<SessionId[]> {
     const tSessions = this.tables["t_sessions"];
     const result = (await this.db.execute(sql`
@@ -562,12 +561,16 @@ export class PostgresBackend implements Backend {
   private async deleteSessions(
     exec: PgAsyncDatabase<NodePgQueryResultHKT>,
     ids: SessionId[],
-  ): Promise<number> {
-    if (ids.length === 0) return 0;
-    await exec
-      .delete(this.tables["t_session_events"])
-      .where(inArray(this.tables["t_session_events"].fSessionId, ids))
-      .execute();
+  ): Promise<{ deleted: number; eventIds: readonly string[] }> {
+    if (ids.length === 0) return { deleted: 0, eventIds: [] };
+    const removed = (await exec.execute(sql`
+      DELETE FROM ${this.tables["t_session_events"]}
+       WHERE f_session_id IN (${sql.join(
+         ids.map((id) => sql`${id}`),
+         sql`, `,
+       )})
+      RETURNING f_event_id
+    `)) as unknown as { rows: Array<{ f_event_id: string }> };
     await exec
       .delete(this.tables["t_workspace_sessions"])
       .where(inArray(this.tables["t_workspace_sessions"].fSessionId, ids))
@@ -580,14 +583,17 @@ export class PostgresBackend implements Backend {
       .delete(this.tables["t_sessions"])
       .where(inArray(this.tables["t_sessions"].fSessionId, ids))
       .execute()) as unknown as { rowCount?: number | null };
-    return result.rowCount ?? 0;
+    return {
+      deleted: Number(result.rowCount ?? 0),
+      eventIds: removed.rows.map((row) => row.f_event_id),
+    };
   }
 
   async vacuum(): Promise<void> {
     await this.db.execute(sql`VACUUM ANALYZE`);
   }
 
-  /** 派生统计表的回填：任一表为空即按事件表全量重算（幂等，迁移删表重建后自愈）。 */
+  // 派生统计表的回填：任一表为空即按事件表全量重算（幂等，迁移删表重建后自愈）。
   private async backfillUsageTables(): Promise<void> {
     // 顺序有依赖：用量行（带物化列）先落，两张会话汇总表再从它 / 事件表重算。
     await this.backfillEventUsage();
@@ -602,10 +608,8 @@ export class PostgresBackend implements Backend {
     return Number(existing.rows[0]?.["n"] ?? 0) === 0;
   }
 
-  /**
-   * 用量行：一条 `assistant/message` 事件行一行，物化本地日与两个归属标记。
-   * 本地日按数据库会话时区渲染（部署前提是它与 host 时区一致，`localDayKey` 同口径）。
-   */
+  // 用量行：一条 `assistant/message` 事件行一行，物化本地日与两个归属标记。
+  // 本地日按数据库会话时区渲染（部署前提是它与 host 时区一致，`localDayKey` 同口径）。
   private async backfillEventUsage(): Promise<void> {
     if (!(await this.tableIsEmpty(this.qualifiedTable("t_event_usage")))) return;
     const tEventUsage = this.tables["t_event_usage"];
@@ -645,7 +649,7 @@ export class PostgresBackend implements Backend {
     `);
   }
 
-  /** 会话 × 本地日 × 模型的 token 汇总：从桥接行 × 用量行重算（含 fork 继承前缀）。 */
+  // 会话 × 本地日 × 模型的 token 汇总：从桥接行 × 用量行重算（含 fork 继承前缀）。
   private async backfillSessionUsage(): Promise<void> {
     if (!(await this.tableIsEmpty(this.qualifiedTable("t_session_usage")))) return;
     const tSessionUsage = this.tables["t_session_usage"];
@@ -665,7 +669,7 @@ export class PostgresBackend implements Backend {
     `);
   }
 
-  /** 会话 × 本地日的活动计数：从桥接行 × 事件类型重算。 */
+  // 会话 × 本地日的活动计数：从桥接行 × 事件类型重算。
   private async backfillSessionCounts(): Promise<void> {
     if (!(await this.tableIsEmpty(this.qualifiedTable("t_session_counts")))) return;
     const tSessionCounts = this.tables["t_session_counts"];
@@ -688,7 +692,7 @@ export class PostgresBackend implements Backend {
     `);
   }
 
-  /** 用量聚合：与 SQLite 侧同形，读 `t_event_usage`，数值列回来是字符串。 */
+  // 用量聚合：与 SQLite 侧同形，读 `t_event_usage`，数值列回来是字符串。
   async listSessionRows(query: SessionListRowsQuery = {}): Promise<SessionListRowsPage> {
     const needle = query.query?.trim().toLowerCase() ?? "";
     const like = `%${needle}%`;
@@ -741,10 +745,8 @@ export class PostgresBackend implements Backend {
     };
   }
 
-  /**
-   * 用量聚合：与 SQLite 侧同形——只读三张派生统计表（用量行给去重口径的总量与「天 × 模型」桶，
-   * 两张会话汇总表给按会话的行），数值列回来是字符串。物化列让这里不做 `EXISTS`、不回连事件表。
-   */
+  // 用量聚合：与 SQLite 侧同形——只读三张派生统计表（用量行给去重口径的总量与「天 × 模型」桶，
+  // 两张会话汇总表给按会话的行），数值列回来是字符串。物化列让这里不做 `EXISTS`、不回连事件表。
   async usageReport(sinceMs?: number): Promise<UsageAggregate> {
     const usageSince = sinceMs === undefined ? sql`` : sql` AND f_created_at >= ${sinceMs}`;
     const dayFilter = (column: string): ReturnType<typeof sql> =>
@@ -846,13 +848,13 @@ export class PostgresBackend implements Backend {
     };
   }
 
-  /** 表名限定到配置的 schema。 */
+  // 表名限定到配置的 schema。
   private qualifiedTable(name: string): string {
     const schema = this.options.schema ?? "public";
     return schema === "public" ? name : `"${schema}".${name}`;
   }
 
-  /** token 用量旁路累加：派生表 `t_session_usage`，不在写事务里（失败可丢，表可销毁重建）。 */
+  // token 用量旁路累加：派生表 `t_session_usage`，不在写事务里（失败可丢，表可销毁重建）。
   async incrementSessionUsage(
     id: SessionId,
     buckets: readonly SessionUsageBucket[],
@@ -877,7 +879,7 @@ export class PostgresBackend implements Backend {
     }
   }
 
-  /** 活动计数旁路累加：派生表 `t_session_counts`，同上（四项计数一次落）。 */
+  // 活动计数旁路累加：派生表 `t_session_counts`，同上（四项计数一次落）。
   async incrementSessionCounts(
     id: SessionId,
     buckets: readonly SessionCountBucket[],
@@ -899,7 +901,7 @@ export class PostgresBackend implements Backend {
     }
   }
 
-  /** 按会话重算两张汇总表（rewind / fork 之后）：先删该会话的行，再从事件表重算。 */
+  // 按会话重算两张汇总表（rewind / fork 之后）：先删该会话的行，再从事件表重算。
   async rebuildSessionStats(id: SessionId): Promise<void> {
     const tSessionUsage = this.tables["t_session_usage"];
     const tSessionCounts = this.tables["t_session_counts"];
@@ -936,20 +938,27 @@ export class PostgresBackend implements Backend {
     `);
   }
 
-  /** 全量重算用量行的引用标记（rewind / fork / 会话删除之后）。 */
-  async refreshEventUsageFlags(): Promise<void> {
+  // 重算这些用量行的引用标记（会话删除 / 日志重写之后；撤回与 fork 都不该动统计）。
+  async refreshEventUsageFlags(eventIds: readonly string[]): Promise<void> {
     const tEventUsage = this.tables["t_event_usage"];
     const tSessionEvents = this.tables["t_session_events"];
     const tSessions = this.tables["t_sessions"];
-    await this.db.execute(sql`
-      UPDATE ${tEventUsage} SET
-        f_referenced = (EXISTS (SELECT 1 FROM ${tSessionEvents} rb
-                                 WHERE rb.f_event_id = ${tEventUsage}.f_event_id))::int,
-        f_subagent = (EXISTS (SELECT 1 FROM ${tSessionEvents} sb
-                                JOIN ${tSessions} ss ON ss.f_session_id = sb.f_session_id
-                               WHERE sb.f_event_id = ${tEventUsage}.f_event_id
-                                 AND ss.f_origin = 'subagent'))::int
-    `);
+    for (let at = 0; at < eventIds.length; at += REFRESH_FLAG_CHUNK) {
+      const chunk = eventIds.slice(at, at + REFRESH_FLAG_CHUNK);
+      await this.db.execute(sql`
+        UPDATE ${tEventUsage} SET
+          f_referenced = (EXISTS (SELECT 1 FROM ${tSessionEvents} rb
+                                   WHERE rb.f_event_id = ${tEventUsage}.f_event_id))::int,
+          f_subagent = (EXISTS (SELECT 1 FROM ${tSessionEvents} sb
+                                  JOIN ${tSessions} ss ON ss.f_session_id = sb.f_session_id
+                                 WHERE sb.f_event_id = ${tEventUsage}.f_event_id
+                                   AND ss.f_origin = 'subagent'))::int
+         WHERE f_event_id IN (${sql.join(
+           chunk.map((id) => sql`${id}`),
+           sql`, `,
+         )})
+      `);
+    }
   }
 
   async deleteSessionStats(id: SessionId): Promise<void> {

package/src/routes.ts

@@ -0,0 +1,16 @@
+// 本仓库会话管理面 HTTP 路径的 home：整族挂在同一前缀下，与上游的 `/api` 面（connection 的 prefix 路由）
+// 分开。同路径的 exact 路由会遮蔽上游同名路由的 GET/HEAD 通道（官方会话日志下载因此 405），
+// 见 ADR-管理面HTTP路由前缀与上游分家。
+export const MORLAY_SESSION_API_PREFIX = "/api/morlay/v1/session";
+
+export const SESSION_ROWS_PATH = `${MORLAY_SESSION_API_PREFIX}/rows`;
+
+export const SESSION_EXPORT_PATH = `${MORLAY_SESSION_API_PREFIX}/export`;
+
+export const SESSION_IMPORT_PATH = `${MORLAY_SESSION_API_PREFIX}/import`;
+
+export const SESSION_DELETE_PATH = `${MORLAY_SESSION_API_PREFIX}/delete`;
+
+export const SESSION_GC_PATH = `${MORLAY_SESSION_API_PREFIX}/gc`;
+
+export const SESSION_USAGE_PATH = `${MORLAY_SESSION_API_PREFIX}/usage`;

package/src/rows.ts

@@ -1,32 +1,28 @@
 import type { Context } from "@deepseek-ai/cordis";
 import type { Backend } from "./backend.ts";
+import { SESSION_ROWS_PATH } from "./routes.ts";
 
-/**
- * 管理面的会话列表：**我们自己的**一条路由（完整语料，含归档），与官方 `session/list` 分开。
- *
- * 官方那条（`session/list` → `ctx.sessionQuery.listSessions`）按部署策略默认排除已归档——那是给上游
- * UI 用的。归档集的管理动作要有完整列表，所以这里单独给一条：标题直接从会话列取，最后活动时间用
- * 该会话最后一个事件的时间。
- */
-export const SESSION_ROWS_PATH = "/api/session.rows";
+// 管理面的会话列表路由：完整语料（含归档）+ 标题 + 最后活动时间，与官方 `session/list` 分开
+// （见 ADR-会话列表两条路）。
+export { SESSION_ROWS_PATH };
 
 export interface SessionRowsItem {
   sessionId: string;
   title: string | null;
-  /** 会话 header 的 origin（`subagent` 表示子代理会话）。 */
+  // 会话 header 的 origin（`subagent` 表示子代理会话）。
   origin: string | null;
   cwd: string | null;
   createdAt: number;
-  /** 最后一个事件的时间（无事件时等于 `createdAt`）。 */
+  // 最后一个事件的时间（无事件时等于 `createdAt`）。
   updatedAt: number;
   archived: boolean;
-  /** 所属工作区标题；不属于任何工作区时为 null。 */
+  // 所属工作区标题；不属于任何工作区时为 null。
   workspace: string | null;
 }
 
-/** 请求：搜索、子代理过滤与分页都在后端做——前端分页等于每次拉全量，数据一多就崩。 */
+// 请求：搜索、子代理过滤与分页都在后端做——前端分页等于每次拉全量，数据一多就崩。
 export interface SessionRowsRequest {
-  /** 匹配标题或所属工作区标题（大小写不敏感）。 */
+  // 匹配标题或所属工作区标题（大小写不敏感）。
   query?: string;
   includeSubagents?: boolean;
   page?: number;
@@ -35,13 +31,13 @@ export interface SessionRowsRequest {
 
 export interface SessionRowsValue {
   items: SessionRowsItem[];
-  /** 过滤后的总数（分页前），前端据此算页数。 */
+  // 过滤后的总数（分页前），前端据此算页数。
   total: number;
   page: number;
   pageSize: number;
 }
 
-/** 一页的条数上限：超过就按上限截断（这个接口给页面用，不是导出通道）。 */
+// 一页的条数上限：超过就按上限截断（这个接口给页面用，不是导出通道）。
 const MAX_PAGE_SIZE = 200;
 const DEFAULT_PAGE_SIZE = 20;
 

package/src/session-query.ts

@@ -11,12 +11,8 @@ export class SessionQueryRdb extends SessionQueryEngine {
     super(ctx, config);
   }
 
-  /**
-   * 官方列表（`session/list`）**默认不含已归档**：归档是「收起来」的会话，列表与搜索都不该把它混进
-   * 日常集合（上游 client 再用 workspace registry 的归档集做「只看归档」的派生）。
-   *
-   * 完整语料（含归档）走我们自己的管理面路由 `SESSION_ROWS_PATH`——两条路分开，不在一处混。
-   */
+  // 官方列表（`session/list`）**默认不含已归档**：归档是「收起来」的会话，上游 client 用 workspace registry
+  // 的归档集做「只看归档」的派生；完整语料走管理面路由 `SESSION_ROWS_PATH`。
   override async listSessions(signal?: AbortSignal): Promise<SessionRecord[]> {
     const records = await super.listSessions(signal);
     const archived = this.archivedSessionIds();
@@ -24,7 +20,7 @@ export class SessionQueryRdb extends SessionQueryEngine {
     return records.filter((record) => !archived.has(String(record.header.id)));
   }
 
-  /** 归档集合来自 workspace registry；服务未就绪时保守返回空集（宁可多给，不可漏掉可见会话）。 */
+  // 归档集合来自 workspace registry；服务未就绪时保守返回空集（宁可多给，不可漏掉可见会话）。
   private archivedSessionIds(): ReadonlySet<string> {
     const registry = this.ctx.get("workspaceRegistry" as never) as unknown as
       | { archivedSessionIds?: readonly string[] }