Skip to content
Python
17.4 KB
Raw Blame
import type {
  LiveSyncHealth,
  MemoryProcessingSummary,
  ModelProfile,
  SourceResponse,
} from "@one-memory/contracts";
import type {
  BackgroundHealth,
  RuntimeStatus,
} from "@one-memory/runtime-control";
import { sdkMigrationLogPath } from "@one-memory/runtime-control";
import type { CoreReader, ReadOutcome } from "./core-client.js";
import {
  type SdkHomeSummary,
  validateHomeSummary,
  validateLiveSync,
  validateModelProfiles,
  validateProcessing,
  validateSources,
} from "./core-responses.js";
import { describeEmbeddingSwitchSummary } from "./embedding-switch-flow.js";
import { PRODUCT } from "./version.js";

const MIGRATION_ISSUES_URL =
  "https://github.com/Tencent-Hunyuan/Hy-Memory/issues/new";

export type SectionState =
  | "ok"
  | "denied"
  | "unavailable"
  | "invalid"
  | "not_checked";

export type Section = { state: SectionState; code?: string } & Record<
  string,
  unknown
>;

export interface StatusDocument {
  schema_version: 1;
  product: string;
  data_dir: string;
  runtime: {
    state: RuntimeStatus["state"];
    code: string;
    instance_id?: string;
    host?: string;
    port?: number;
    version?: string;
    /** Set only when an unfinished upgrade migration is why nothing serves. */
    log_file?: string;
    issues_url?: string;
  };
  bridge: {
    state: BackgroundHealth["state"] | "not_checked";
    code: string;
    core?: BackgroundHealth["core"];
    broker?: BackgroundHealth["broker"];
  };
  sections: Record<string, Section>;
  /** R10: the SDK mode and System 2 state; null when the Runtime is not read
   * or is older than the setting. */
  pipeline?: PipelineSummary | null;
  summary: {
    state: "ok" | "partial";
    degraded: string[];
    not_checked: string[];
  };
}

export interface PipelineSummary {
  mode: "lite" | "pro" | "ultra";
  configured_mode: "lite" | "pro" | "ultra";
  forced_by_env: boolean;
  last_evolve_at: string | null;
  evolve_schedule: { enabled: boolean; time: string } | null;
  evolve_running: number;
  evolve_users: Record<
    string,
    {
      last_run_at: string | null;
      last_error: string | null;
      state: string | null;
    }
  >;
  graph_build: string | null;
  /** SDK features (`memory_features`) whose value differs from the default. */
  features: Record<string, boolean>;
  /** The App's display language; null = never chosen or "follow the system". */
  ui_language: string | null;
  /** The SDK prompt language: `auto` (zh/en detection) or the code passed. */
  sdk_language: string;
}

const MODES = new Set(["lite", "pro", "ultra"]);

/** Projection of `pipeline` in `/api/v1/memory-processing`; null if absent or malformed. */
export function describePipeline(value: unknown): PipelineSummary | null {
  if (!value || typeof value !== "object") return null;
  const pipeline = (value as { pipeline?: unknown }).pipeline;
  if (!pipeline || typeof pipeline !== "object") return null;
  const item = pipeline as Record<string, unknown>;
  if (
    !MODES.has(String(item.mode)) ||
    !MODES.has(String(item.configured_mode))
  ) {
    return null;
  }
  const evolve =
    item.evolve && typeof item.evolve === "object"
      ? (item.evolve as Record<string, unknown>)
      : {};
  const schedule =
    evolve.schedule && typeof evolve.schedule === "object"
      ? (evolve.schedule as Record<string, unknown>)
      : null;
  const users: PipelineSummary["evolve_users"] = {};
  if (evolve.users && typeof evolve.users === "object") {
    for (const [userId, raw] of Object.entries(
      evolve.users as Record<string, unknown>,
    )) {
      const user =
        raw && typeof raw === "object" ? (raw as Record<string, unknown>) : {};
      const result =
        user.last_result && typeof user.last_result === "object"
          ? (user.last_result as Record<string, unknown>)
          : {};
      users[userId] = {
        last_run_at:
          typeof user.last_run_at === "string" ? user.last_run_at : null,
        last_error:
          typeof user.last_error === "string" ? user.last_error : null,
        state: typeof result.state === "string" ? result.state : null,
      };
    }
  }
  const features: Record<string, boolean> = {};
  if (item.features && typeof item.features === "object") {
    for (const [name, value] of Object.entries(
      item.features as Record<string, unknown>,
    )) {
      if (typeof value === "boolean") features[name] = value;
    }
  }
  const graph =
    item.graph_build && typeof item.graph_build === "object"
      ? (item.graph_build as Record<string, unknown>)
      : {};
  return {
    mode: item.mode as PipelineSummary["mode"],
    configured_mode: item.configured_mode as PipelineSummary["mode"],
    forced_by_env: item.forced_by_env === true,
    last_evolve_at:
      typeof item.last_evolve_at === "string" ? item.last_evolve_at : null,
    evolve_schedule:
      schedule &&
      typeof schedule.enabled === "boolean" &&
      typeof schedule.time === "string"
        ? { enabled: schedule.enabled, time: schedule.time }
        : null,
    evolve_running: Array.isArray(evolve.running) ? evolve.running.length : 0,
    evolve_users: users,
    graph_build: typeof graph.state === "string" ? graph.state : null,
    features,
    ui_language: typeof item.ui_language === "string" ? item.ui_language : null,
    // An older Runtime has no setting: it always left the SDK on auto.
    sdk_language:
      typeof item.sdk_language === "string" ? item.sdk_language : "auto",
  };
}

const SECTION_NAMES = [
  "sources",
  "sync",
  "processing",
  "model",
  "memories",
] as const;

const BRIDGE_LABELS: Record<StatusDocument["bridge"]["state"], string> = {
  healthy: "正常",
  stopped: "未运行",
  degraded: "降级",
  untrusted: "身份不可信",
  unknown: "未知",
  not_checked: "未检查",
};

const SECTION_LABELS: Record<string, string> = {
  sources: "来源",
  sync: "同步",
  processing: "生成任务",
  model: "模型",
  memories: "记忆",
};

export async function composeStatusReport(options: {
  dataDir: string;
  runtime: RuntimeStatus;
  background: BackgroundHealth | null;
  reader: CoreReader | null;
  attachFailure?: string;
}): Promise<StatusDocument> {
  const sections: Record<string, Section> = {};
  let pipeline: PipelineSummary | null = null;
  if (options.reader === null) {
    const state: SectionState =
      options.attachFailure === undefined ? "not_checked" : "unavailable";
    const code = options.attachFailure ?? options.runtime.code;
    for (const name of SECTION_NAMES) sections[name] = { state, code };
  } else {
    const reader = options.reader;
    const [sources, sync, processing, model, memories] = await Promise.all([
      reader<unknown>("/api/v1/sources"),
      reader<unknown>("/api/v1/live-sync"),
      reader<unknown>("/api/v1/memory-processing"),
      reader<unknown>("/api/v1/model-profiles"),
      reader<unknown>("/api/v2/home-summary"),
    ]);
    sections.sources = section(sources, validateSources, describeSources);
    sections.sync = section(sync, validateLiveSync, describeSync);
    sections.processing = section(
      processing,
      validateProcessing,
      describeProcessing,
    );
    pipeline =
      processing.state === "ok" ? describePipeline(processing.data) : null;
    sections.model = section(model, validateModelProfiles, describeModel);
    sections.memories = section(
      memories,
      validateHomeSummary,
      describeMemories,
    );
  }
  // A bridge we could not inspect is unknown, not broken and not fine.
  const bridge: StatusDocument["bridge"] =
    options.background === null
      ? { state: "not_checked", code: "bridge_inspection_failed" }
      : {
          state: options.background.state,
          code: options.background.code,
          core: options.background.core,
          broker: options.background.broker,
        };
  const degraded: string[] = SECTION_NAMES.filter((name) =>
    ["denied", "unavailable", "invalid"].includes(
      String(sections[name]?.state),
    ),
  );
  if (bridge.state === "degraded" || bridge.state === "untrusted") {
    degraded.push("bridge");
  }
  const notChecked: string[] = SECTION_NAMES.filter(
    (name) => sections[name]?.state === "not_checked",
  );
  if (bridge.state === "not_checked" || bridge.state === "unknown") {
    notChecked.push("bridge");
  }
  return {
    schema_version: 1,
    product: PRODUCT,
    data_dir: options.dataDir,
    runtime: {
      state: options.runtime.state,
      code: options.runtime.code,
      instance_id: options.runtime.instanceId,
      host: options.runtime.host,
      port: options.runtime.port,
      version: options.runtime.version,
      ...(options.runtime.code.startsWith("sdk_migration_")
        ? {
            log_file: sdkMigrationLogPath(options.dataDir),
            issues_url: MIGRATION_ISSUES_URL,
          }
        : {}),
    },
    bridge,
    sections,
    pipeline,
    summary: {
      state:
        degraded.length === 0 && notChecked.length === 0 ? "ok" : "partial",
      degraded,
      not_checked: notChecked,
    },
  };
}

export function statusExitCode(report: StatusDocument): number {
  if (report.runtime.state === "stopped") return 3;
  if (report.runtime.state !== "running") return 1;
  return report.summary.state === "ok" ? 0 : 1;
}

export function renderStatusText(
  report: StatusDocument,
  heading: string,
): string {
  const lines = [
    `${heading}:${runtimeLine(report)}`,
    ...(report.runtime.log_file
      ? [
          `升级迁移没有完成(错误码:${report.runtime.code}),MemHub 不会启动。`,
          `请把迁移日志附在 GitHub 反馈里发给我们:${report.runtime.log_file}`,
          `反馈地址:${report.runtime.issues_url}`,
        ]
      : []),
    `资料空间:${report.data_dir}`,
    `应用连接:${BRIDGE_LABELS[report.bridge.state]}`,
  ];
  for (const name of SECTION_NAMES) {
    lines.push(
      `${SECTION_LABELS[name]}:${sectionLine(report.sections[name])}`,
    );
  }
  if (report.pipeline) lines.push(`记忆模式:${pipelineLine(report.pipeline)}`);
  const embeddingSwitch = describeEmbeddingSwitchSummary(
    report.sections.processing?.embedding_switch,
  );
  if (embeddingSwitch !== null) lines.push(`向量模型:${embeddingSwitch}`);
  if (report.summary.state === "partial") {
    const notes = [
      report.summary.degraded.length > 0
        ? `${report.summary.degraded.join("、")} 异常`
        : "",
      report.summary.not_checked.length > 0
        ? `${report.summary.not_checked.join("、")} 未能读到`
        : "",
    ].filter((note) => note.length > 0);
    lines.push(`注意:${notes.join(";")},以上不是完整状态。`);
  }
  lines.push("");
  return lines.join("\n");
}

export function pipelineLine(pipeline: PipelineSummary): string {
  const parts: string[] = [pipeline.mode];
  if (pipeline.forced_by_env)
    parts.push("(ONE_MEMORY_GRAPH_STORE 强制 ultra)");
  if (pipeline.mode === "ultra") {
    const schedule = pipeline.evolve_schedule;
    parts.push(
      schedule?.enabled
        ? `,每日 ${schedule.time} 自动进化`
        : ",自动进化已关闭",
    );
    parts.push(
      pipeline.last_evolve_at
        ? `,上次进化 ${pipeline.last_evolve_at}`
        : ",尚未进化",
    );
    if (pipeline.evolve_running > 0)
      parts.push(`,进行中 ${pipeline.evolve_running}`);
  }
  const changed = Object.entries(pipeline.features);
  if (changed.length > 0) {
    parts.push(
      `;SDK 功能:${changed
        .map(([name, value]) => `${name}=${value ? "开" : "关"}`)
        .join("、")}`,
    );
  }
  parts.push(
    `;界面语言 ${pipeline.ui_language ?? "跟随系统"},SDK 提示语言 ${
      pipeline.sdk_language === "auto"
        ? "auto(自动识别中/英)"
        : pipeline.sdk_language
    }`,
  );
  return parts.join("");
}

function runtimeLine(report: StatusDocument): string {
  if (report.runtime.state !== "running") {
    return report.runtime.state === "stopped" ? "未运行" : "暂时无法确认";
  }
  return `运行中(${report.runtime.host}:${report.runtime.port}${
    report.runtime.version ? `,版本 ${report.runtime.version}` : ""
  })`;
}

function sectionLine(section: Section | undefined): string {
  if (!section) return "未检查";
  if (section.state === "not_checked") return "未检查";
  if (section.state !== "ok") return "暂时不可用,请稍后重试";
  return Object.entries(section)
    .filter(
      ([key]) =>
        key !== "state" && key !== "code" && key !== "embedding_switch",
    )
    .map(([key, value]) => `${fieldLabel(key)} ${formatValue(value)}`)
    .join(" ");
}

function formatValue(value: unknown): string {
  if (Array.isArray(value))
    return value.length === 0
      ? "无"
      : value.map((item) => formatValue(item)).join(";");
  if (value === null || value === undefined) return "无";
  if (typeof value === "object") {
    return Object.entries(value as Record<string, unknown>)
      .map(([key, item]) => `${fieldLabel(key)} ${formatValue(item)}`)
      .join("/");
  }
  return valueLabel(String(value));
}

function fieldLabel(key: string): string {
  const labels: Record<string, string> = {
    total: "共",
    authorized: "已授权",
    available: "已发现",
    imported_conversations: "会话",
    imported_messages: "原文",
    sources: "来源",
    running: "进行中",
    idle: "空闲",
    degraded: "需留意",
    unavailable: "不可用",
    pending: "待处理",
    fresh_pending: "新对话待处理",
    backlog_pending: "历史待处理",
    outside_window_pending: "稍后处理",
    waiting_for_model: "等待模型",
    completed: "已完成",
    failed: "失败",
    blocked: "卡住",
    kind: "类型",
    reason: "原因",
    count: "数量",
    profiles: "配置",
    active: "当前",
    memory_count: "记忆",
  };
  return labels[key] ?? key;
}

function valueLabel(value: string): string {
  const labels: Record<string, string> = {
    extract: "整理对话",
    waiting_for_model: "等待模型",
    input_too_long: "内容过长",
    background_verified: "后台正常",
    additions_only: "只同步新增内容",
  };
  return labels[value] ?? value;
}

function section<T>(
  outcome: ReadOutcome<unknown>,
  validate: (value: unknown) => T | null,
  describe: (data: T) => Record<string, unknown>,
): Section {
  if (outcome.state !== "ok") {
    // A status route that is missing is a Runtime we cannot read, not an empty one.
    return {
      state: outcome.state === "denied" ? "denied" : "unavailable",
      code: outcome.code,
    };
  }
  const data = validate(outcome.data);
  // Answered, but not with something we can read: not a smaller truth.
  return data === null
    ? { state: "invalid", code: "response_invalid" }
    : { state: "ok", ...describe(data) };
}

function describeSources(sources: SourceResponse[]): Record<string, unknown> {
  return {
    total: sources.length,
    authorized: sources.filter((source) => source.authorized).length,
    available: sources.filter((source) => source.available).length,
    imported_conversations: sum(sources, "imported_conversations"),
    imported_messages: sum(sources, "imported_messages"),
  };
}

function describeSync(health: LiveSyncHealth[]): Record<string, unknown> {
  return {
    sources: health.length,
    running: health.filter((item) => item.state === "running").length,
    idle: health.filter((item) => item.state === "idle").length,
    degraded: health.filter((item) => item.state === "degraded").length,
    unavailable: health.filter((item) => item.state === "unavailable").length,
  };
}

function describeProcessing(
  summary: MemoryProcessingSummary,
): Record<string, unknown> {
  return {
    pending: summary.pending,
    fresh_pending: summary.fresh_pending,
    backlog_pending: summary.backlog_pending,
    outside_window_pending: summary.outside_window_pending,
    running: summary.running,
    waiting_for_model: summary.waiting_for_model,
    completed: summary.completed,
    failed: summary.failed,
    blocked: (summary.blocked_stages ?? []).map((block) => ({
      kind: block.kind,
      reason: block.reason,
      count: block.count,
    })),
    ...embeddingSwitchField(summary),
  };
}

/** The running switch or merge, projected; absent when none runs. */
function embeddingSwitchField(
  summary: MemoryProcessingSummary,
): Record<string, unknown> {
  const value = (summary as unknown as Record<string, unknown>)
    .embedding_switch;
  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
  const item = value as Record<string, unknown>;
  const kind = item.kind === "merge" ? "merge" : "switch";
  const state =
    typeof item.state === "string" && /^[a-z_]{1,32}$/.test(item.state)
      ? item.state
      : "unknown";
  const percent =
    typeof item.percent === "number" && Number.isFinite(item.percent)
      ? Math.min(100, Math.max(0, item.percent))
      : 0;
  return { embedding_switch: { kind, state, percent } };
}

/** Projection, not passthrough: a Core that leaks a key must not make us leak. */
function describeModel(profiles: ModelProfile[]): Record<string, unknown> {
  const active = profiles.find((profile) => profile.is_active);
  return {
    profiles: profiles.length,
    active: active
      ? {
          name: active.name,
          model: active.model,
        }
      : null,
  };
}

function describeMemories(summary: SdkHomeSummary): Record<string, unknown> {
  return {
    memory_count: summary.memory_count,
  };
}

function sum(
  sources: SourceResponse[],
  key: "imported_conversations" | "imported_messages",
): number {
  return sources.reduce((total, source) => total + (source[key] ?? 0), 0);
}