Skip to content
Python
26.5 KB
Raw Blame
import type { ProviderKind } from "@one-memory/contracts";
import { ChevronDown, ChevronUp } from "lucide-react";
import { useEffect, useId, useRef, useState } from "react";
import { OptionMenu } from "./OptionMenu";
import { useOnboardingTranslation } from "./onboarding-language";
import { R6ColdStartFrame } from "./R6ColdStartFrame";
import { R6Button } from "./R6Controls";
import "./onboarding-model-r6.css";

/** Strings preserve partial numeric edits. The owner validates and maps to API payloads. */
export interface OnboardingModelDraft {
  provider_id: string;
  name: string;
  provider_kind: ProviderKind;
  model: string;
  base_url: string;
  api_key: string;
  disable_thinking: boolean;
  embedding_mode: "local" | "custom";
  embedding_provider_kind: "openai_compatible" | "ollama";
  embedding_model: string;
  embedding_base_url: string;
  timeout_seconds: string;
  max_concurrency: string;
  context_window: string;
}
export interface OnboardingModelProvider {
  id: string;
  label: string;
  keyRequired: boolean;
  supported: boolean;
}
type Action = "test" | "save-draft" | "save-and-enable";
export interface OnboardingModelStepProps {
  draft: OnboardingModelDraft;
  providers: readonly OnboardingModelProvider[];
  advancedOpen: boolean;
  onAdvancedChange(open: boolean): void;
  onDraftChange(patch: Partial<OnboardingModelDraft>): void;
  phase: "idle" | "testing" | "saving" | "enabling";
  capability: { saveAndEnable: boolean; reason?: string };
  canTest: boolean;
  canSaveDraft: boolean;
  /** Owner validation/current revision gate; absence fails closed. */
  canSaveAndEnable?: boolean;
  enableActionLabel?: string;
  testActionLabel?: string;
  inputsLocked?: boolean;
  fieldErrors?: Partial<Record<keyof OnboardingModelDraft, string>>;
  error?: string | null;
  probe?: { state: "passed" | "failed" | "stale"; message: string } | null;
  profile?: {
    profile_id: string;
    revision: number;
    has_configured_api_key: boolean;
    credential_state?: "available" | "missing" | "unavailable";
  } | null;
  sourceNames: readonly string[];
  importedConversationCount?: number;
  connectionSummary?: string;
  generationRecipient: string;
  embeddingRecipient: string;
  onTest(): Promise<void>;
  onSaveAndEnable(): Promise<void>;
  onSaveDraft(): Promise<void>;
  onRecoverCreation?(): Promise<void>;
  onDiscardMissingCreation?(): Promise<void>;
  onBack(): void;
  onSkip?(): void;
  /** Owner must preserve receipts/unknown results and supply a safe display error. */
  onActionError?(action: Action): void;
}

export function OnboardingModelStep(props: OnboardingModelStepProps) {
  const { text, t, locale } = useOnboardingTranslation();
  const { draft, advancedOpen, onDraftChange, fieldErrors = {}, phase } = props;
  const id = useId();
  // The Chinese label already names the destination; shorter translated labels
  // need it as a description for assistive technology.
  const skipDestination =
    locale === "zh-Hans" ? "" : t("onboardingModelSkipDestination");
  const fields = useRef<HTMLElement>(null);
  const advancedToggle = useRef<HTMLButtonElement>(null);
  const restoreToggleFocus = useRef(false);
  const flight = useRef(false);
  const alive = useRef(true);
  const [pending, setPending] = useState<Action | null>(null);
  const [callbackFailed, setCallbackFailed] = useState(false);
  useEffect(() => {
    alive.current = true;
    return () => {
      alive.current = false;
    };
  }, []);
  const locked = phase !== "idle" || pending !== null;
  const fieldsLocked = locked || props.inputsLocked === true;
  // biome-ignore lint/correctness/useExhaustiveDependencies: Restore only after the controlled mode change has rendered its replacement toggle.
  useEffect(() => {
    if (!restoreToggleFocus.current) return;
    restoreToggleFocus.current = false;
    if (fields.current) fields.current.scrollTop = 0;
    advancedToggle.current?.focus({ preventScroll: true });
  }, [advancedOpen]);
  function changeAdvanced(open: boolean) {
    restoreToggleFocus.current = true;
    props.onAdvancedChange(open);
  }
  const provider = props.providers.find(
    (item) => item.id === draft.provider_id,
  );
  const canEnable =
    (props.probe?.state === "passed" ||
      props.enableActionLabel === "核对提交状态") &&
    props.capability.saveAndEnable &&
    props.canSaveAndEnable === true &&
    !!props.generationRecipient.trim() &&
    !!props.embeddingRecipient.trim() &&
    provider?.supported;
  const sourceSummary =
    props.sourceNames.length <= 3
      ? props.sourceNames.join(" · ")
      : t("onboardingSourcesSummary", {
          names: props.sourceNames.slice(0, 3).join(" · "),
          count: props.sourceNames.length,
        });
  async function run(action: Action) {
    if (flight.current || locked) return;
    if (action === "save-and-enable" && !canEnable) return;
    if (action === "test" && (!props.canTest || !provider?.supported)) return;
    if (action === "save-draft" && !props.canSaveDraft) return;
    flight.current = true;
    setPending(action);
    setCallbackFailed(false);
    try {
      await (action === "test"
        ? props.onTest()
        : action === "save-draft"
          ? props.onSaveDraft()
          : props.onSaveAndEnable());
    } catch {
      if (alive.current) {
        setCallbackFailed(true);
        props.onActionError?.(action);
      }
    } finally {
      flight.current = false;
      if (alive.current) setPending(null);
    }
  }
  function field(
    key: keyof OnboardingModelDraft,
    label: string,
    options: {
      type?: string;
      min?: number;
      max?: number;
      maxLength?: number;
      required?: boolean;
      placeholder?: string;
    } = {},
  ) {
    const error = fieldErrors[key];
    return (
      <label className="onboarding-model-field" htmlFor={`${id}-${key}`}>
        <span>{text(label)}</span>
        <input
          id={`${id}-${key}`}
          name={key}
          aria-label={text(label)}
          type={options.type ?? "text"}
          autoComplete="off"
          spellCheck={false}
          value={String(draft[key])}
          disabled={fieldsLocked}
          aria-invalid={!!error}
          aria-describedby={error ? `${id}-${key}-error` : undefined}
          min={options.min}
          max={options.max}
          maxLength={options.maxLength}
          required={options.required}
          placeholder={
            options.placeholder ? text(options.placeholder) : undefined
          }
          onChange={(event) => {
            if (!flight.current && !fieldsLocked)
              onDraftChange({ [key]: event.target.value });
          }}
        />
        {error && (
          <small id={`${id}-${key}-error`} className="onboarding-model-error">
            {text(error)}
          </small>
        )}
      </label>
    );
  }
  const displayedPhase =
    phase !== "idle"
      ? phase
      : pending === "test"
        ? "testing"
        : pending === "save-draft"
          ? "saving"
          : pending
            ? "enabling"
            : "idle";
  const connectionFailed = props.probe?.state === "failed";
  const pageTitle = advancedOpen
    ? "配置详情,按需要调整"
    : connectionFailed
      ? "连接未通过,配置已保留"
      : "选好模型,让记忆开始沉淀";
  const connectionReceipt = props.connectionSummary?.includes("已启用")
    ? "连接设置已保存\n成功项保留,不重复执行。"
    : props.connectionSummary === "持续同步 · 一键接入"
      ? "已选择:持续同步 · 一键接入"
      : props.connectionSummary;
  return (
    <div
      className="onboarding-model-r6"
      data-integration={
        props.capability.saveAndEnable
          ? "capability-provided"
          : "not-integrated"
      }
    >
      <R6ColdStartFrame
        step={3}
        eyebrow={text("沉淀记忆 · 使用你选择的模型")}
        title={text(pageTitle)}
        footer={
          <>
            <p className="onboarding-model-footer-note">
              {text(
                !props.capability.saveAndEnable
                  ? "当前无法启用模型,已填写内容保留。"
                  : props.probe?.state === "passed"
                    ? "模型连接测试通过,可以启用并开始沉淀记忆。"
                    : "先测试模型连通性;测试通过后再启用。",
              )}
            </p>
            <div className="onboarding-model-footer-actions">
              {skipDestination && (
                <span id={`${id}-skip-destination`} hidden>
                  {skipDestination}
                </span>
              )}
              <R6Button
                aria-describedby={
                  skipDestination ? `${id}-skip-destination` : undefined
                }
                disabled={locked}
                onClick={() => {
                  if (!flight.current && !locked)
                    (props.onSkip ?? props.onBack)();
                }}
              >
                {text("跳过,先进入应用")}
              </R6Button>
              <R6Button
                disabled={locked || !props.canTest}
                onClick={() => void run("test")}
              >
                {text(
                  displayedPhase === "testing"
                    ? "正在测试模型…"
                    : (props.testActionLabel ?? "测试模型连通性"),
                )}
              </R6Button>
              <R6Button
                variant="primary"
                disabled={locked || !canEnable}
                onClick={() => void run("save-and-enable")}
              >
                {text(
                  displayedPhase === "enabling"
                    ? "正在启用…"
                    : (props.enableActionLabel ?? "确认启用"),
                )}
              </R6Button>
            </div>
          </>
        }
      >
        <div className="onboarding-model-layout">
          <section
            className="onboarding-model-form"
            aria-label={text("模型配置")}
            data-advanced={advancedOpen}
          >
            <section
              ref={fields}
              id={`${id}-fields`}
              className="onboarding-model-fields"
              aria-label={text("模型参数")}
              // biome-ignore lint/a11y/noNoninteractiveTabindex: The parameter pane needs keyboard scrolling.
              tabIndex={0}
            >
              {!advancedOpen ? (
                <>
                  <p className="onboarding-model-intro">
                    {text("选择服务商,填入 API Key。核对已有配置后再继续。")}
                  </p>
                  <label
                    className="onboarding-model-field onboarding-model-provider"
                    htmlFor={`${id}-provider`}
                  >
                    <span id={`${id}-provider-label`}>
                      {text("模型服务商")}
                    </span>
                    <OptionMenu
                      id={`${id}-provider`}
                      labelledBy={`${id}-provider-label`}
                      value={draft.provider_id}
                      disabled={fieldsLocked}
                      options={[
                        ...(!provider
                          ? [{ value: "", label: text("选择服务商") }]
                          : []),
                        ...props.providers.map((item) => ({
                          value: item.id,
                          label: text(item.label),
                          disabled: !item.supported,
                        })),
                      ]}
                      onChange={(value) => {
                        if (!flight.current)
                          onDraftChange({ provider_id: value });
                      }}
                    />
                  </label>
                  <div className="onboarding-model-key">
                    {field("api_key", "API Key", {
                      type: "password",
                      required:
                        provider?.keyRequired &&
                        !props.profile?.has_configured_api_key,
                      placeholder: props.profile?.has_configured_api_key
                        ? "已安全保存,留空保留"
                        : "输入服务商提供的 API Key",
                    })}
                  </div>
                  <p
                    className="onboarding-model-key-note"
                    data-state={connectionFailed ? "failed" : "idle"}
                  >
                    {text(
                      connectionFailed
                        ? "连接未通过,请检查 API Key、模型与接口地址后重试。配置已保留。"
                        : props.profile?.credential_state === "unavailable"
                          ? "需要允许 MemHub 访问钥匙串。系统询问时请选择“始终允许”。"
                          : props.profile?.has_configured_api_key
                            ? "留空保留已保存密钥;填写新密钥后需重新测试。"
                            : "密钥保存在系统安全存储中,不写入对话或日志。",
                    )}
                  </p>
                  <button
                    ref={advancedToggle}
                    type="button"
                    className="onboarding-model-toggle"
                    aria-expanded={false}
                    aria-controls={`${id}-fields`}
                    disabled={fieldsLocked}
                    onClick={() => changeAdvanced(true)}
                  >
                    {text("配置详情与高级设置")}{" "}
                    <ChevronDown size={16} aria-hidden="true" />
                  </button>
                  <p className="onboarding-model-profile">
                    {provider ? text(provider.label) : text("服务商待选择")} ·{" "}
                    {draft.model || text("模型待填写")}
                    <br />
                    {text(safeEndpoint(draft.base_url))} ·{" "}
                    {draft.embedding_mode === "local"
                      ? text("本地向量模型")
                      : draft.embedding_model || text("向量模型待填写")}{" "}
                    ·{" "}
                    {text(draft.disable_thinking ? "思考已关闭" : "思考未关闭")}
                  </p>
                </>
              ) : (
                <>
                  <div className="onboarding-model-advanced-head">
                    <p>
                      {text("预设已填好,只有自定义服务或特殊需求才需要修改。")}
                    </p>
                    <button
                      ref={advancedToggle}
                      type="button"
                      className="onboarding-model-toggle"
                      aria-expanded={true}
                      aria-controls={`${id}-fields`}
                      disabled={fieldsLocked}
                      onClick={() => changeAdvanced(false)}
                    >
                      {text("返回服务商选择")}{" "}
                      <ChevronUp size={16} aria-hidden="true" />
                    </button>
                  </div>
                  <div className="onboarding-model-advanced-grid">
                    {field("name", "配置名称", { maxLength: 128 })}
                    {field("model", "模型名称", {
                      required: true,
                      maxLength: 256,
                    })}
                    <div className="onboarding-model-wide">
                      {field("base_url", "Base URL", {
                        type: "url",
                        required: true,
                      })}
                    </div>
                    <div className="onboarding-model-wide onboarding-model-key">
                      {field("api_key", "API Key", {
                        type: "password",
                        required:
                          provider?.keyRequired &&
                          !props.profile?.has_configured_api_key,
                        placeholder: props.profile?.has_configured_api_key
                          ? "已安全保存,留空保留"
                          : "输入服务商提供的 API Key",
                      })}
                      <p
                        className="onboarding-model-key-note"
                        data-state={connectionFailed ? "failed" : "idle"}
                      >
                        {text(
                          props.profile?.has_configured_api_key
                            ? "留空保留已保存密钥;填写新密钥后需重新测试。"
                            : "密钥保存在系统安全存储中,不写入对话或日志。",
                        )}
                      </p>
                    </div>
                    <label className="onboarding-model-field">
                      <span>{text("协议")}</span>
                      <select
                        aria-label={text("协议")}
                        value={draft.provider_kind}
                        disabled={fieldsLocked}
                        onChange={(e) => {
                          if (!flight.current)
                            onDraftChange({
                              provider_kind: e.target.value as ProviderKind,
                            });
                        }}
                      >
                        <option value="openai_compatible">
                          OpenAI-compatible
                        </option>
                        <option value="ollama">Ollama</option>
                        <option value="anthropic" disabled>
                          {text("Anthropic(暂不支持)")}
                        </option>
                        <option value="hy_default" disabled>
                          {text("HY 托管(当前不可用)")}
                        </option>
                      </select>
                    </label>
                    <label className="onboarding-model-field">
                      <span>{text("向量模型")}</span>
                      <select
                        aria-label={text("向量模型")}
                        value={draft.embedding_mode}
                        disabled={fieldsLocked}
                        onChange={(e) => {
                          if (!flight.current)
                            onDraftChange({
                              embedding_mode: e.target.value as
                                | "local"
                                | "custom",
                            });
                        }}
                      >
                        <option value="local">
                          {text("本地 ONNX · 内置")}
                        </option>
                        <option value="custom">{text("自定义向量")}</option>
                      </select>
                    </label>
                    <div className="onboarding-model-numbers">
                      {field("timeout_seconds", "超时(秒)", {
                        type: "number",
                        min: 1,
                        max: 600,
                      })}
                      {field("max_concurrency", "最大并发", {
                        type: "number",
                        min: 1,
                        max: 32,
                      })}
                      {field("context_window", "上下文窗口", {
                        type: "number",
                        min: 1024,
                        max: 10000000,
                        placeholder: "自动 / 可选",
                      })}
                    </div>
                    <label className="onboarding-model-thinking">
                      <input
                        type="checkbox"
                        checked={draft.disable_thinking}
                        disabled={fieldsLocked}
                        onChange={(e) => {
                          if (!flight.current)
                            onDraftChange({
                              disable_thinking: e.target.checked,
                            });
                        }}
                      />
                      {text("关闭思考模式")}
                    </label>
                    <p className="onboarding-model-vector-note">
                      {text(
                        "自定义向量配置可展开;远程向量服务须遵守凭据边界。",
                      )}
                      <br />
                      {text("切换服务商或模型后,需要重新测试并启用。")}
                    </p>
                    {draft.embedding_mode === "custom" && (
                      <>
                        {field("embedding_model", "向量模型名称", {
                          required: true,
                          maxLength: 256,
                        })}
                        <label className="onboarding-model-field">
                          <span>{text("向量协议")}</span>
                          <select
                            aria-label={text("向量协议")}
                            value={draft.embedding_provider_kind}
                            disabled={fieldsLocked}
                            onChange={(e) => {
                              if (!flight.current)
                                onDraftChange({
                                  embedding_provider_kind: e.target.value as
                                    | "ollama"
                                    | "openai_compatible",
                                });
                            }}
                          >
                            <option value="openai_compatible">
                              {text("同源 OpenAI-compatible(共用 Key)")}
                            </option>
                            <option value="ollama">
                              {text("本机 Ollama")}
                            </option>
                          </select>
                        </label>
                        <div className="onboarding-model-wide">
                          {field("embedding_base_url", "向量 Base URL", {
                            type: "url",
                            required: true,
                          })}
                          <small>
                            {text(
                              "远程向量地址须与生成服务同源;本机地址仍需校验。",
                            )}
                          </small>
                        </div>
                      </>
                    )}
                  </div>
                </>
              )}
            </section>
            <div className="onboarding-model-recovery-actions">
              {props.onRecoverCreation && (
                <R6Button
                  disabled={locked}
                  onClick={() => void props.onRecoverCreation?.()}
                >
                  {text("核对创建结果")}
                </R6Button>
              )}
              {props.onDiscardMissingCreation && (
                <R6Button
                  variant="secondary"
                  disabled={locked}
                  onClick={() => void props.onDiscardMissingCreation?.()}
                >
                  {text("放弃旧记录,重新配置")}
                </R6Button>
              )}
            </div>
            <div className="onboarding-model-feedback" tabIndex={-1}>
              {(displayedPhase === "testing" ||
                displayedPhase === "enabling") && (
                <p role="status" aria-label={text("模型提交状态")}>
                  {text(
                    displayedPhase === "testing"
                      ? "正在测试连接…"
                      : "正在提交保存与启用,请等待回执…",
                  )}
                </p>
              )}
              {props.probe && (
                <p
                  className="onboarding-model-probe"
                  data-state={props.probe.state}
                  role="status"
                >
                  {text(props.probe.message)}
                </p>
              )}
              {(props.error || callbackFailed) && (
                <p className="onboarding-model-error" role="alert">
                  {text(
                    props.error ||
                      "操作结果未确认,已填写内容保留,请核对后重试。",
                  )}
                </p>
              )}
            </div>
          </section>
          <aside
            className="onboarding-model-summary"
            aria-label={text("本次沉淀")}
            data-full-height={advancedOpen || connectionFailed}
            // biome-ignore lint/a11y/noNoninteractiveTabindex: Keyboard users must be able to scroll the full permission disclosure.
            tabIndex={0}
          >
            <div className="onboarding-model-summary-heading">
              <p>{text("本次沉淀")}</p>
              <h2>{text("让记忆从这里开始")}</h2>
            </div>
            <div className="onboarding-model-connections">
              <p>{text("对话来源")}</p>
              <strong>{sourceSummary || text("尚无已选来源")}</strong>
              <small>
                {t("onboardingImportedConversations", {
                  count: props.importedConversationCount ?? 0,
                })}
              </small>
            </div>
            <div className="onboarding-model-summary-status">
              {connectionReceipt && (
                <small className="onboarding-model-connection-receipt">
                  {text(connectionReceipt)}
                </small>
              )}
              <small>
                {text("处理服务:")}
                {text(provider?.label ?? "待选择")}
                <br />
                {text("相关对话会发送给所选服务商。")}
              </small>
              <small>
                {text(
                  "测试连接只发送测试内容。启用后会使用此模型整理已导入和之后同步的会话。",
                )}
              </small>
            </div>
            {!props.capability.saveAndEnable && (
              <p role="status">
                {text(props.capability.reason || "当前不能在此启用模型。")}
              </p>
            )}
          </aside>
        </div>
      </R6ColdStartFrame>
    </div>
  );
}

function safeEndpoint(value: string): string {
  try {
    const url = new URL(value);
    if (
      !["http:", "https:"].includes(url.protocol) ||
      url.username ||
      url.password ||
      url.search ||
      url.hash
    )
      return "接口地址待核对";
    return `${url.origin}${url.pathname.replace(/\/$/, "")}`;
  } catch {
    return "接口地址待核对";
  }
}