@morlay/ui-conversation-manager 0.0.2-alpha.0

package/src/client/controller.ts

@@ -0,0 +1,216 @@
+import type { SessionId } from "@deepseek-ai/dsh-session";
+
+/** host 侧已存在的会话路由。 */
+export const SESSION_DELETE_PATH = "/api/session.delete";
+export const SESSION_IMPORT_PATH = "/api/session.import";
+export const SESSION_EXPORT_PATH = "/api/session.export";
+export const SESSION_GC_PATH = "/api/session.gc";
+export const SESSION_USAGE_PATH = "/api/session.usage";
+
+/** 时间范围的语义键（与 session-rdb `./usage` 的 `UsageRangeKey` 镜像）。 */
+export type UsageRangeKey = "all" | "day" | "week" | "7d" | "30d" | "90d";
+
+/** 一段用量合计（与 session-rdb `./usage` 的回报结构镜像）。 */
+export interface UsageTotals {
+  events: number;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  reasoningTokens: number;
+  totalTokens: number;
+}
+
+/** 一天 × 一个模型 × 是否子代理 的用量桶。 */
+export interface UsageBucket extends UsageTotals {
+  day: string;
+  provider: string | null;
+  model: string | null;
+  subagent: boolean;
+}
+
+/** 一条会话的用量行。 */
+export interface UsageSessionRow extends UsageTotals {
+  sessionId: string;
+  title: string | null;
+  subagent: boolean;
+  archived: boolean;
+}
+
+/** 一次统计请求的回报：总览 + subagent 拆分 + 桶 + 会话行。 */
+export interface SessionUsageReport {
+  totals: UsageTotals;
+  subagent: UsageTotals;
+  /** 只被人类会话引用的部分。 */
+  human: UsageTotals;
+  buckets: UsageBucket[];
+  sessions: UsageSessionRow[];
+}
+
+/** 页面之外的服务面：归档状态与列表刷新都归它们的既有 owner。 */
+export interface ConversationManagerPorts {
+  archiveSession(sessionId: SessionId): Promise<void>;
+  unarchiveSession(sessionId: SessionId): Promise<void>;
+  refresh(): Promise<void>;
+}
+
+/** GC 一次执行的回报。 */
+export interface ConversationManagerGcResult {
+  orphanSessions: number;
+  orphanEvents: number;
+  stoppedAgents: number;
+}
+
+/** 页面从注入面拿到的动作（属性语法：页面解构后直接调用，不绑 this）。 */
+export interface ConversationManagerFace {
+  archive: (sessionId: SessionId) => Promise<void>;
+  unarchive: (sessionId: SessionId) => Promise<void>;
+  remove: (sessionId: SessionId) => Promise<void>;
+  exportZip: (sessionId: SessionId) => Promise<void>;
+  importZip: (file: File) => Promise<SessionId>;
+  collectGarbage: () => Promise<ConversationManagerGcResult>;
+  loadUsage: (range: UsageRangeKey) => Promise<SessionUsageReport>;
+}
+
+/** 带 host 错误码的请求失败：页面据此选本地化文案。 */
+export class ConversationManagerRequestError extends Error {
+  constructor(
+    message: string,
+    readonly code: string | undefined,
+  ) {
+    super(message);
+    this.name = "ConversationManagerRequestError";
+  }
+}
+
+async function postJson(path: string, body: unknown): Promise<Record<string, unknown>> {
+  const response = await fetch(path, {
+    method: "POST",
+    headers: { accept: "application/json", "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const value = (await response.json().catch(() => ({}))) as {
+    error?: unknown;
+    code?: unknown;
+  };
+  if (!response.ok) {
+    throw new ConversationManagerRequestError(
+      typeof value.error === "string" ? value.error : `请求失败：HTTP ${response.status}`,
+      typeof value.code === "string" ? value.code : undefined,
+    );
+  }
+  return value;
+}
+
+async function zipBase64(file: File): Promise<string> {
+  const dataUrl = await new Promise<string>((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => {
+      resolve(typeof reader.result === "string" ? reader.result : "");
+    };
+    reader.onerror = () => {
+      reject(reader.error ?? new Error("failed to read the selected file"));
+    };
+    reader.readAsDataURL(file);
+  });
+  const comma = dataUrl.indexOf(",");
+  return comma < 0 ? dataUrl : dataUrl.slice(comma + 1);
+}
+
+/** 页面的动作：host 交互收在这里，页面只见数据与回调。 */
+export class ConversationManagerController {
+  readonly face: ConversationManagerFace;
+
+  constructor(private readonly ports: ConversationManagerPorts) {
+    this.face = {
+      archive: (sessionId) => this.ports.archiveSession(sessionId),
+      unarchive: (sessionId) => this.ports.unarchiveSession(sessionId),
+      remove: (sessionId) => this.remove(sessionId),
+      exportZip: (sessionId) => this.exportZip(sessionId),
+      importZip: (file) => this.importZip(file),
+      collectGarbage: () => this.collectGarbage(),
+      loadUsage: (range) => this.loadUsage(range),
+    };
+  }
+
+  private async remove(sessionId: SessionId): Promise<void> {
+    await postJson(SESSION_DELETE_PATH, { sessionId });
+    await this.ports.refresh();
+  }
+
+  private async exportZip(sessionId: SessionId): Promise<void> {
+    const response = await fetch(SESSION_EXPORT_PATH, {
+      method: "POST",
+      headers: { accept: "application/zip", "content-type": "application/json" },
+      body: JSON.stringify({ sessionId }),
+    });
+    if (!response.ok) {
+      const value = (await response.json().catch(() => ({}))) as {
+        error?: unknown;
+        code?: unknown;
+      };
+      throw new ConversationManagerRequestError(
+        typeof value.error === "string" ? value.error : `请求失败：HTTP ${response.status}`,
+        typeof value.code === "string" ? value.code : undefined,
+      );
+    }
+    downloadBlob(
+      await response.blob(),
+      filenameOf(response.headers.get("content-disposition"), String(sessionId)),
+    );
+  }
+
+  private async importZip(file: File): Promise<SessionId> {
+    const zip = await zipBase64(file);
+    const value = await postJson(SESSION_IMPORT_PATH, { zip });
+    await this.ports.refresh();
+    return value["sessionId"] as SessionId;
+  }
+
+  private async collectGarbage(): Promise<ConversationManagerGcResult> {
+    const value = await postJson(SESSION_GC_PATH, {});
+    await this.ports.refresh();
+    return {
+      orphanSessions: typeof value["orphanSessions"] === "number" ? value["orphanSessions"] : 0,
+      orphanEvents: typeof value["orphanEvents"] === "number" ? value["orphanEvents"] : 0,
+      stoppedAgents: typeof value["stoppedAgents"] === "number" ? value["stoppedAgents"] : 0,
+    };
+  }
+
+  /**
+   * 用量统计：host 侧聚合，前端各维度本地折叠。
+   * @param range - 时间范围语义键（`all` 不限、`day`/`week` 自然日/周、其余最近 N 天）。
+   */
+  private async loadUsage(range: UsageRangeKey): Promise<SessionUsageReport> {
+    const value = await postJson(SESSION_USAGE_PATH, { range });
+    const report = value as unknown as Partial<SessionUsageReport>;
+    if (
+      report.totals === undefined ||
+      !Array.isArray(report.buckets) ||
+      !Array.isArray(report.sessions)
+    ) {
+      throw new ConversationManagerRequestError("用量统计响应不可用", undefined);
+    }
+    return report as SessionUsageReport;
+  }
+}
+
+/** 导出文件名优先取 host 给的 Content-Disposition。 */
+function filenameOf(disposition: string | null, sessionId: string): string {
+  const matched = disposition === null ? null : /filename="([^"]+)"/u.exec(disposition);
+  return matched?.[1] ?? `${sessionId}.zip`;
+}
+
+/** 浏览器下载：blob URL + 一次性 anchor；URL 在下一轮事件循环回收。 */
+function downloadBlob(blob: Blob, filename: string): void {
+  const url = URL.createObjectURL(blob);
+  const anchor = document.createElement("a");
+  anchor.href = url;
+  anchor.download = filename;
+  anchor.rel = "noopener";
+  document.body.append(anchor);
+  anchor.click();
+  anchor.remove();
+  window.setTimeout(() => {
+    URL.revokeObjectURL(url);
+  }, 0);
+}

package/src/client/format.ts

@@ -0,0 +1,22 @@
+// token 数字的紧凑显示：表格里以总量为主，明细用 K/M/B 压缩。
+
+/** 一位小数；三位数以上不留小数。 */
+function trim(value: number): string {
+  return value >= 100 ? String(Math.round(value)) : value.toFixed(1).replace(/\.0$/u, "");
+}
+
+/** @param value - token 数（非负整数）。 @returns 紧凑文本，例如 `1.2K`、`44.2B`。 */
+export function formatTokens(value: number): string {
+  if (!Number.isFinite(value) || value <= 0) return "0";
+  if (value < 1_000) return String(Math.round(value));
+  if (value < 1_000_000) return `${trim(value / 1_000)}K`;
+  if (value < 1_000_000_000) return `${trim(value / 1_000_000)}M`;
+  return `${trim(value / 1_000_000_000)}B`;
+}
+
+/** @param value - 百分点（0~100）。 @returns 紧凑百分比，例如 `98.4%`、`100%`。 */
+export function formatPercent(value: number): string {
+  if (!Number.isFinite(value) || value <= 0) return "0%";
+  const rounded = value >= 100 ? Math.round(value) : Math.round(value * 10) / 10;
+  return `${rounded}%`;
+}

package/src/client/index.ts

@@ -0,0 +1,76 @@
+// 「对话管理」页面：nav 行（sidebar.panellist）与主面板（main keyed）用同一个 id 成对
+// 注册；点击 nav 行经 ctx.layout.selectPanel 校验该 id 在 main 里已注册。
+import type { Context as ClientContext } from "@deepseek-ai/cordis";
+import type { ISessions } from "@deepseek-ai/dsh-api-session-controller/client";
+import type { MainPanelId } from "@deepseek-ai/dsh-client-ui-layout/client";
+import type {} from "@deepseek-ai/dsh-client-locale/client";
+import type {} from "@deepseek-ai/dsh-client-ui-renderer/client";
+import type {} from "@deepseek-ai/dsh-client-ui-sidebar/client";
+import type {} from "@deepseek-ai/dsh-client-ui-session/client";
+import type {} from "@deepseek-ai/dsh-client-ui-workspace/client";
+import type {} from "@deepseek-ai/dsh-api-session-controller/client";
+import { ConversationManagerController } from "./controller.ts";
+import { ConversationManagerPage } from "./ConversationManagerPage.tsx";
+import { ConversationManagerIcon } from "./ConversationManagerIcon.tsx";
+import { en, zh, type ConversationManagerKey } from "./locales.ts";
+
+export type { ConversationManagerFace, ConversationManagerPorts } from "./controller.ts";
+export { ConversationManagerController, ConversationManagerRequestError } from "./controller.ts";
+export type { ConversationManagerIconProps } from "./ConversationManagerIcon.tsx";
+export type { ConversationManagerPageProps } from "./ConversationManagerPage.tsx";
+export type { ConversationManagerKey } from "./locales.ts";
+
+declare module "@deepseek-ai/dsh-client-ui-slots" {
+  interface LocaleNamespaceMap {
+    conversationManager: ConversationManagerKey;
+  }
+}
+
+/** 本包字典的 namespace。 */
+export const NS = "conversationManager";
+
+/** nav 行与主面板共用的 id。 */
+export const PANEL_ID = "conversations" as MainPanelId;
+
+/** nav 行的位置：紧邻官方 Plugins 行（order 0）。 */
+export const PANEL_ORDER = 1;
+
+/** 页面用到的服务。 */
+export const inject = ["slots", "locale", "uiWorkspace", "sessions"];
+
+export function apply(ctx: ClientContext): void {
+  ctx.effect(() => ctx.locale.register(NS, { zh, en }), "ui-conversation-manager: dictionaries");
+  const t = ctx.locale.bind(NS);
+  // ctx.sessions 的类型被别的 client 半的声明占住（SessionStore），按既有做法从服务面取。
+  const sessions = ctx.get("sessions") as unknown as ISessions;
+  const controller = new ConversationManagerController({
+    archiveSession: (sessionId) => ctx.uiWorkspace.archiveSession(sessionId),
+    unarchiveSession: (sessionId) => ctx.uiWorkspace.unarchiveSession(sessionId),
+    refresh: () => sessions.refresh(),
+  });
+
+  ctx.slots.inject("main", () =>
+    ctx.slots.register(
+      {
+        name: "main",
+        key: PANEL_ID,
+        locale: NS,
+        inject: () => controller.face,
+      },
+      ConversationManagerPage,
+    ),
+  );
+
+  ctx.slots.inject("sidebar.panellist", () =>
+    ctx.slots.register(
+      {
+        name: "sidebar.panellist",
+        id: PANEL_ID,
+        order: PANEL_ORDER,
+        label: () => t("panel"),
+        locale: NS,
+      },
+      ConversationManagerIcon,
+    ),
+  );
+}

package/src/client/locales.ts

@@ -0,0 +1,152 @@
+/** 「对话管理」页面的文案字典。 */
+
+/** 简体中文是 key 真源。 */
+export const zh = {
+  panel: "对话管理",
+  title: "对话管理",
+  search: "搜索会话",
+  loading: "正在读取会话…",
+  empty: "暂无会话。",
+  emptySearch: "没有匹配的会话。",
+  archived: "已归档",
+  subagent: "子代理",
+  showSubagents: "显示子代理会话",
+  "view.sessions": "会话",
+  "view.usage": "统计",
+  "usage.overview": "总览",
+  "usage.all": "全部会话",
+  "usage.range": "时间范围",
+  "usage.range.all": "全部",
+  "usage.range.day": "本日",
+  "usage.range.week": "本周",
+  "usage.range.days": "近 {n} 天",
+  "usage.models": "按模型",
+  "usage.sessions": "按会话",
+  "usage.loading": "正在统计…",
+  "usage.empty": "暂无用量数据。",
+  "usage.input": "输入",
+  "usage.inputWithCache": "输入（含缓存）",
+  "usage.output": "输出",
+  "usage.cacheInput": "缓存输入",
+  "usage.cacheRate": "缓存命中率",
+  "usage.reasoning": "推理",
+  "usage.total": "合计",
+  "usage.events": "事件",
+  "usage.subagentOnly": "其中子代理",
+  "usage.unknownModel": "未知模型",
+  archive: "归档",
+  archiveNamed: "归档 {title}",
+  unarchive: "取消归档",
+  unarchiveNamed: "取消归档 {title}",
+  remove: "删除",
+  removeNamed: "删除 {title}",
+  export: "导出",
+  exportNamed: "导出 {title}",
+  ungrouped: "未分组",
+  "page.previous": "上一页",
+  "page.next": "下一页",
+  "page.label": "第 {page} / {total} 页",
+  "gc.button": "清理孤儿数据",
+  "gc.title": "清理孤儿数据",
+  "gc.description":
+    "会先停止所有运行中的 Agent，期间界面不可操作；随后回收孤儿 subagent 会话与孤儿数据，并执行 VACUUM。",
+  "gc.confirm": "开始清理",
+  "gc.cancel": "取消",
+  "gc.running": "正在清理，请稍候…",
+  "gc.done": "已回收 {sessions} 条孤儿会话、{events} 行孤儿数据。",
+  import: "导入对话",
+  importing: "导入中…",
+  imported: "已导入为新会话。",
+  confirmTitle: "删除会话",
+  confirmDescription: "删除后无法恢复：该会话的内容会从存储中移除。",
+  confirmAccept: "删除",
+  confirmCancel: "取消",
+  close: "关闭",
+  "failure.notArchived": "只有已归档的会话可以删除。",
+  "failure.live": "会话正在使用中，无法删除。",
+  "failure.missing": "会话不存在或已被删除。",
+  "failure.other": "操作失败：{reason}",
+  "time.now": "刚刚",
+  "time.minutes": "{n}分钟",
+  "time.hours": "{n}小时",
+  "time.days": "{n}天",
+  "time.months": "{n}个月",
+  "time.years": "{n}年",
+} satisfies Record<string, string>;
+
+/** 「对话管理」页面字典的 key 集合。 */
+export type ConversationManagerKey = keyof typeof zh;
+
+/** 英文对照表。 */
+export const en = {
+  panel: "Conversations",
+  title: "Conversations",
+  search: "Search sessions",
+  loading: "Reading sessions…",
+  empty: "No sessions.",
+  emptySearch: "No matching sessions.",
+  archived: "Archived",
+  subagent: "Subagent",
+  showSubagents: "Show subagent sessions",
+  "view.sessions": "Sessions",
+  "view.usage": "Usage",
+  "usage.overview": "Overview",
+  "usage.all": "All sessions",
+  "usage.range": "Time range",
+  "usage.range.all": "All",
+  "usage.range.day": "Today",
+  "usage.range.week": "This week",
+  "usage.range.days": "Last {n}d",
+  "usage.models": "By model",
+  "usage.sessions": "By session",
+  "usage.loading": "Reading usage…",
+  "usage.empty": "No usage recorded.",
+  "usage.input": "Input",
+  "usage.inputWithCache": "Input (incl. cache)",
+  "usage.output": "Output",
+  "usage.cacheInput": "Cache input",
+  "usage.cacheRate": "Cache hit rate",
+  "usage.reasoning": "Reasoning",
+  "usage.total": "Total",
+  "usage.events": "Events",
+  "usage.subagentOnly": "Subagent share",
+  "usage.unknownModel": "Unknown model",
+  archive: "Archive",
+  archiveNamed: "Archive {title}",
+  unarchive: "Unarchive",
+  unarchiveNamed: "Unarchive {title}",
+  remove: "Delete",
+  removeNamed: "Delete {title}",
+  export: "Export",
+  exportNamed: "Export {title}",
+  ungrouped: "Ungrouped",
+  "page.previous": "Previous",
+  "page.next": "Next",
+  "page.label": "Page {page} / {total}",
+  "gc.button": "Clean orphan data",
+  "gc.title": "Clean orphan data",
+  "gc.description":
+    "Stops every running Agent first — the UI is blocked meanwhile — then reclaims orphan subagent sessions and orphan rows, and runs VACUUM.",
+  "gc.confirm": "Start",
+  "gc.cancel": "Cancel",
+  "gc.running": "Cleaning, please wait…",
+  "gc.done": "Reclaimed {sessions} orphan sessions and {events} orphan rows.",
+  import: "Import conversation",
+  importing: "Importing…",
+  imported: "Imported as a new session.",
+  confirmTitle: "Delete session",
+  confirmDescription: "This cannot be undone: the session's content is removed from storage.",
+  confirmAccept: "Delete",
+  confirmCancel: "Cancel",
+  close: "Close",
+  "failure.notArchived": "Only archived sessions can be deleted.",
+  "failure.live": "The session is in use and cannot be deleted.",
+  "failure.missing": "The session does not exist or was already deleted.",
+  "failure.other": "Action failed: {reason}",
+  "time.now": "now",
+  "time.minutes": "{n}min",
+  "time.hours": "{n}h",
+  "time.days": "{n}d",
+  "time.months": "{n}mo",
+  "time.years": "{n}y",
+} satisfies Record<ConversationManagerKey, string>;

package/src/index.ts

@@ -0,0 +1,2 @@
+/** 「对话管理」页面的 host 半：没有 host 面（页面只读已有服务与路由）。 */
+export function apply(): void {}