apiskill 0.1.0

package/src/App.tsx

@@ -0,0 +1,2570 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import {
+  AlertCircle,
+  Braces,
+  Check,
+  ClipboardCopy,
+  Database,
+  FileCode2,
+  Filter,
+  Globe2,
+  KeyRound,
+  Link2,
+  LockKeyhole,
+  Pencil,
+  Plus,
+  RefreshCcw,
+  Search,
+  Send,
+  Server,
+  Trash2,
+  X,
+} from 'lucide-react';
+import {
+  AUTH_CHECK_API_URL,
+  buildApiCliText,
+  buildRawSchemaJson,
+  CACHE_API_URL,
+  CUSTOM_OPERATION_API_URL,
+  DELETE_OPERATION_API_URL,
+  DOCUMENT_CREATE_API_URL,
+  endpointToManualApiOperationConfig,
+  IMPORT_API_URL,
+  listEndpoints,
+  listTags,
+  MOCK_START_API_URL,
+  MOCK_STATUS_API_URL,
+  OPERATION_LINKS_API_URL,
+  parameterRows,
+  requestBodyRows,
+  resolveSchema,
+  responseRows,
+  STORAGE_SOURCE_KEY,
+  STORAGE_SYNC_KEY,
+  VERSION_DELETE_API_URL,
+  VERSION_META_API_URL,
+  VERSION_SELECT_API_URL,
+  VERSIONS_API_URL,
+} from './swagger';
+import { AddApiDialog } from './AddApiDialog';
+import { DocumentVersionManager } from './DocumentVersionManager';
+import type { DocumentVersionMeta } from './DocumentVersionManager';
+import type { ManualApiOperationConfig } from './manualApiConfig';
+import type { Endpoint, EndpointAssociationLinks, FieldRow, HttpMethod, SwaggerDocument, SwaggerParameter, SwaggerSchema } from './types';
+
+const methodOptions: Array<'all' | HttpMethod> = ['all', 'get', 'post', 'put', 'delete', 'patch'];
+const OPEN_ENDPOINT_TABS_STORAGE_KEY = 'apiskill-open-endpoint-tabs';
+
+type LoadState = 'loading' | 'ready' | 'error';
+type DetailTab = 'ai' | 'json' | 'test' | 'links';
+type ImportMode = 'file' | 'crawl' | 'curl' | 'upload';
+type ImportDialogMode = ImportMode | 'blank';
+type CacheMode = ImportMode | 'manual' | 'document';
+type AuthType = 'none' | 'bearer' | 'jwt' | 'apiKey' | 'basic';
+type ApiKeyLocation = 'header' | 'query';
+type DocumentAuthConfig = {
+  type: 'none' | 'basic';
+  username?: string;
+  password?: string;
+};
+type AuthPromptState = {
+  open: boolean;
+  mode: ImportMode;
+  inputUrl: string;
+  message: string;
+  updateVersionId?: string;
+};
+type ImportDialogState = {
+  open: boolean;
+  mode: ImportDialogMode;
+  status: 'running' | 'success' | 'error';
+  progress: number;
+  inputUrl: string;
+  message: string;
+  error?: string;
+  meta?: ImportMeta;
+};
+
+type ImportMeta = {
+  versionId?: string;
+  mode?: CacheMode;
+  inputUrl?: string;
+  resolvedUrl?: string;
+  title?: string;
+  version?: string;
+  savedFile?: string;
+  savedPath?: string;
+  savedAt?: string;
+  paths?: number;
+  schemas?: number;
+  environmentName?: string;
+  environmentBaseUrl?: string;
+};
+
+type ImportResponse = {
+  document: SwaggerDocument;
+  meta?: ImportMeta;
+  versions?: ImportMeta[];
+};
+
+type VersionSelectResponse = ImportResponse & {
+  versions?: ImportMeta[];
+};
+
+type VersionListResponse = {
+  versions: ImportMeta[];
+};
+
+type VersionMetaResponse = {
+  meta: ImportMeta;
+  versions: ImportMeta[];
+};
+
+type VersionDeleteResponse = {
+  versions: ImportMeta[];
+  nextVersionId?: string;
+};
+
+type AuthCheckResponse = {
+  requiresAuth: boolean;
+  status?: number;
+  message?: string;
+};
+
+type RequestTestResponse = {
+  status: number;
+  statusText: string;
+  headers: Record<string, string | string[]>;
+  body: string;
+  elapsedMs: number;
+  url: string;
+};
+
+type MockStatusResponse = {
+  running: boolean;
+  mock?: {
+    url: string;
+    host: string;
+    port: number;
+    versionId: string;
+    title: string;
+    routesCount: number;
+  };
+};
+
+type OpenEndpointTab = {
+  id: string;
+  method: HttpMethod;
+  path: string;
+  summary: string;
+};
+
+type OpenEndpointTabsCache = {
+  versionId: string;
+  tabIds: string[];
+  selectedId: string;
+  allowEmptyDetail: boolean;
+};
+
+function endpointToOpenTab(endpoint: Endpoint): OpenEndpointTab {
+  return {
+    id: endpoint.id,
+    method: endpoint.method,
+    path: endpoint.path,
+    summary: endpoint.summary || endpoint.operation.operationId || endpoint.path,
+  };
+}
+
+function getOperationLinkDraftKey(versionId: string, endpoint: Endpoint) {
+  return `${versionId || 'local'}::${endpoint.id}`;
+}
+
+export function App() {
+  const [doc, setDoc] = useState<SwaggerDocument | null>(null);
+  const [loadState, setLoadState] = useState<LoadState>('loading');
+  const [error, setError] = useState('');
+  const [query, setQuery] = useState('');
+  const [tag, setTag] = useState('all');
+  const [method, setMethod] = useState<'all' | HttpMethod>('all');
+  const [bodyOnly, setBodyOnly] = useState(false);
+  const [selectedId, setSelectedId] = useState('');
+  const [allowEmptyDetail, setAllowEmptyDetail] = useState(false);
+  const [openedEndpointTabs, setOpenedEndpointTabs] = useState<OpenEndpointTab[]>([]);
+  const [tabsCacheReady, setTabsCacheReady] = useState(false);
+  const [syncingMode, setSyncingMode] = useState<ImportDialogMode | ''>('');
+  const [activeSourceTab, setActiveSourceTab] = useState<ImportMode>('file');
+  const [versions, setVersions] = useState<ImportMeta[]>([]);
+  const [selectedVersionId, setSelectedVersionId] = useState('');
+  const [selectedVersionMeta, setSelectedVersionMeta] = useState<ImportMeta | undefined>(undefined);
+  const [lastSync, setLastSync] = useState('');
+  const [fileSourceUrl, setFileSourceUrl] = useState('');
+  const [crawlSourceUrl, setCrawlSourceUrl] = useState('');
+  const [curlSourceText, setCurlSourceText] = useState('');
+  const [uploadFile, setUploadFile] = useState<File | null>(null);
+  const [blankDocTitle, setBlankDocTitle] = useState('API Skill Document');
+  const [blankDocVersion, setBlankDocVersion] = useState('1.0.0');
+  const [blankDocDescription, setBlankDocDescription] = useState('Created from API Skill blank document.');
+  const [blankDocDialogOpen, setBlankDocDialogOpen] = useState(false);
+  const [blankUpdateVersionId, setBlankUpdateVersionId] = useState('');
+  const [resolvedSourceUrl, setResolvedSourceUrl] = useState('');
+  const [docAuthUsername, setDocAuthUsername] = useState('');
+  const [docAuthPassword, setDocAuthPassword] = useState('');
+  const [copied, setCopied] = useState<'ai' | 'json' | ''>('');
+  const [importDialog, setImportDialog] = useState<ImportDialogState | null>(null);
+  const [authPrompt, setAuthPrompt] = useState<AuthPromptState | null>(null);
+  const [addApiOpen, setAddApiOpen] = useState(false);
+  const [mockStatus, setMockStatus] = useState<MockStatusResponse | null>(null);
+  const [mockMessage, setMockMessage] = useState('');
+  const [startingMock, setStartingMock] = useState(false);
+  const [editingApiConfig, setEditingApiConfig] = useState<ManualApiOperationConfig | undefined>(undefined);
+  const [editingApiTarget, setEditingApiTarget] = useState<{ method: HttpMethod; path: string } | undefined>(undefined);
+  const [operationLinkDrafts, setOperationLinkDrafts] = useState<Record<string, EndpointAssociationLinks>>({});
+  const [savingApi, setSavingApi] = useState(false);
+  const uploadInputRef = useRef<HTMLInputElement | null>(null);
+
+  useEffect(() => {
+    async function loadInitialCache() {
+      try {
+        await loadCache();
+      } catch (err) {
+        setError(err instanceof Error ? err.message : '读取最新缓存失败');
+        setLoadState('ready');
+      } finally {
+        void loadVersionList();
+      }
+    }
+
+    loadInitialCache();
+    void loadMockStatus();
+  }, []);
+
+  const endpoints = useMemo(() => (doc ? listEndpoints(doc) : []), [doc]);
+  const endpointById = useMemo(() => new Map(endpoints.map((endpoint) => [endpoint.id, endpoint])), [endpoints]);
+  const tags = useMemo(() => listTags(endpoints), [endpoints]);
+
+  const filteredEndpoints = useMemo(() => {
+    const normalized = query.trim().toLowerCase();
+    return endpoints.filter((endpoint) => {
+      const matchQuery = !normalized || endpoint.searchable.includes(normalized);
+      const matchTag = tag === 'all' || endpoint.tags.includes(tag);
+      const matchMethod = method === 'all' || endpoint.method === method;
+      const matchBody = !bodyOnly || endpoint.hasBody;
+      return matchQuery && matchTag && matchMethod && matchBody;
+    });
+  }, [bodyOnly, endpoints, method, query, tag]);
+
+  const selectedEndpoint = useMemo(() => {
+    if (!selectedId && allowEmptyDetail) return undefined;
+    return endpointById.get(selectedId) ?? filteredEndpoints[0];
+  }, [allowEmptyDetail, endpointById, filteredEndpoints, selectedId]);
+  const selectedVersion = useMemo(
+    () => versions.find((version) => version.versionId === selectedVersionId) ?? selectedVersionMeta,
+    [selectedVersionId, selectedVersionMeta, versions],
+  );
+  const selectedOperationLinkDraftKey = selectedEndpoint ? getOperationLinkDraftKey(selectedVersionId, selectedEndpoint) : '';
+  const selectedOperationLinkDraft = selectedEndpoint
+    ? operationLinkDrafts[selectedOperationLinkDraftKey] ?? normalizeEndpointLinks(selectedEndpoint.operation['x-apiskill-links'])
+    : undefined;
+
+  useEffect(() => {
+    if (selectedEndpoint && selectedEndpoint.id !== selectedId) {
+      setSelectedId(selectedEndpoint.id);
+    }
+  }, [selectedEndpoint, selectedId]);
+
+  useEffect(() => {
+    if (!selectedEndpoint) return;
+    setOpenedEndpointTabs((current) => {
+      if (current.some((tab) => tab.id === selectedEndpoint.id)) return current;
+      return [...current, endpointToOpenTab(selectedEndpoint)];
+    });
+  }, [selectedEndpoint]);
+
+  useEffect(() => {
+    setOpenedEndpointTabs((current) => current.filter((tab) => endpointById.has(tab.id)));
+  }, [endpointById]);
+
+  useEffect(() => {
+    if (!selectedVersionId || !endpointById.size) return;
+
+    try {
+      const raw = localStorage.getItem(OPEN_ENDPOINT_TABS_STORAGE_KEY);
+      if (!raw) {
+        setTabsCacheReady(true);
+        return;
+      }
+
+      const cache = JSON.parse(raw) as OpenEndpointTabsCache;
+      if (cache.versionId !== selectedVersionId) {
+        setTabsCacheReady(true);
+        return;
+      }
+
+      const restoredTabs = cache.tabIds
+        .map((id) => endpointById.get(id))
+        .filter((endpoint): endpoint is Endpoint => Boolean(endpoint))
+        .map(endpointToOpenTab);
+      setOpenedEndpointTabs(restoredTabs);
+
+      const nextSelectedId = cache.selectedId && endpointById.has(cache.selectedId) ? cache.selectedId : restoredTabs[0]?.id ?? '';
+      setSelectedId(nextSelectedId);
+      setAllowEmptyDetail(cache.allowEmptyDetail && !nextSelectedId);
+    } catch {
+      localStorage.removeItem(OPEN_ENDPOINT_TABS_STORAGE_KEY);
+    } finally {
+      setTabsCacheReady(true);
+    }
+  }, [endpointById, selectedVersionId]);
+
+  useEffect(() => {
+    if (!selectedVersionId || !tabsCacheReady) return;
+
+    const cache: OpenEndpointTabsCache = {
+      versionId: selectedVersionId,
+      tabIds: openedEndpointTabs.map((tab) => tab.id),
+      selectedId,
+      allowEmptyDetail,
+    };
+    localStorage.setItem(OPEN_ENDPOINT_TABS_STORAGE_KEY, JSON.stringify(cache));
+  }, [allowEmptyDetail, openedEndpointTabs, selectedId, selectedVersionId, tabsCacheReady]);
+
+  useEffect(() => {
+    if (importDialog?.status !== 'running') return;
+
+    const timer = window.setInterval(() => {
+      setImportDialog((current) => {
+        if (!current || current.status !== 'running') return current;
+        return {
+          ...current,
+          progress: Math.min(88, current.progress + (current.mode === 'crawl' || current.mode === 'curl' ? 4 : 7)),
+        };
+      });
+    }, 600);
+
+    return () => window.clearInterval(timer);
+  }, [importDialog?.status, importDialog?.mode]);
+
+  async function loadCache(versionId?: string) {
+    setTabsCacheReady(false);
+    const response = versionId
+      ? await fetch(VERSION_SELECT_API_URL, {
+          method: 'POST',
+          headers: {
+            'content-type': 'application/json',
+          },
+          body: JSON.stringify({ versionId }),
+        })
+      : await fetch(CACHE_API_URL, { cache: 'no-store' });
+    if (response.status === 404) {
+      setDoc(null);
+      setSelectedVersionId('');
+      setSelectedVersionMeta(undefined);
+      setOpenedEndpointTabs([]);
+      setLoadState('ready');
+      return;
+    }
+    if (!response.ok) {
+      throw new Error(`读取缓存失败: ${response.status}`);
+    }
+
+    const payload = (await response.json()) as VersionSelectResponse;
+    setDoc(payload.document);
+    setAllowEmptyDetail(false);
+    setOpenedEndpointTabs([]);
+    setLastSync(payload.meta?.savedAt || '');
+    setSelectedVersionId(payload.meta?.versionId || '');
+    setSelectedVersionMeta(payload.meta);
+    applySourceDefaults(payload.meta, payload.document);
+    setResolvedSourceUrl(payload.meta?.resolvedUrl || payload.meta?.inputUrl || '');
+    if (payload.versions) {
+      setVersions(payload.versions);
+    }
+    setLoadState('ready');
+  }
+
+  async function loadVersionList() {
+    const response = await fetch(VERSIONS_API_URL, { cache: 'no-store' });
+    if (!response.ok) return;
+    const payload = (await response.json()) as VersionListResponse;
+    setVersions(payload.versions ?? []);
+  }
+
+  function isImportMode(value?: string): value is ImportMode {
+    return value === 'file' || value === 'crawl' || value === 'curl' || value === 'upload';
+  }
+
+  function sourceTabFromCacheMode(value?: string): ImportMode | undefined {
+    if (isImportMode(value)) return value;
+    return undefined;
+  }
+
+  function applySourceDefaults(meta?: DocumentVersionMeta, document?: SwaggerDocument | null) {
+    const sourceTab = sourceTabFromCacheMode(meta?.mode);
+    if (sourceTab) {
+      setActiveSourceTab(sourceTab);
+    }
+    if (isImportMode(meta?.mode)) {
+      setSourceInput(meta.mode, meta.inputUrl || '');
+    }
+    if ((meta?.mode === 'document' || meta?.mode === 'manual') && document?.info) {
+      setBlankDocTitle(document.info.title || 'API Skill Document');
+      setBlankDocVersion(document.info.version || '1.0.0');
+      setBlankDocDescription(document.info.description || '');
+    }
+  }
+
+  function getImportUpdateVersionId(mode: ImportMode) {
+    return selectedVersionId && selectedVersion?.mode === mode ? selectedVersionId : '';
+  }
+
+  function setSourceInput(mode: ImportMode, value: string) {
+    if (mode === 'crawl') setCrawlSourceUrl(value);
+    else if (mode === 'curl') setCurlSourceText(value);
+    else if (mode === 'file') setFileSourceUrl(value);
+  }
+
+  function getActiveSourceValue() {
+    if (activeSourceTab === 'crawl') return crawlSourceUrl.trim();
+    if (activeSourceTab === 'curl') return curlSourceText.trim();
+    if (activeSourceTab === 'upload') return uploadFile?.name || '';
+    return fileSourceUrl.trim();
+  }
+
+  function emptySourceMessage(mode: ImportMode) {
+    if (mode === 'curl') return '请输入 CURL 命令';
+    if (mode === 'upload') return '请选择 JSON 或 YAML 文件';
+    return mode === 'crawl' ? '请输入在线文档页地址' : '请输入 Swagger/OpenAPI 文件地址';
+  }
+
+  function clearActiveSource() {
+    if (activeSourceTab === 'crawl') setCrawlSourceUrl('');
+    else if (activeSourceTab === 'curl') setCurlSourceText('');
+    else if (activeSourceTab === 'upload') {
+      setUploadFile(null);
+      if (uploadInputRef.current) uploadInputRef.current.value = '';
+    } else {
+      setFileSourceUrl('');
+    }
+  }
+
+  async function getImportInput(mode: ImportMode) {
+    if (mode === 'upload') {
+      if (!uploadFile) throw new Error(emptySourceMessage(mode));
+      if (!/\.(json|ya?ml)$/i.test(uploadFile.name)) {
+        throw new Error('仅支持 JSON、YAML 或 YML 文件');
+      }
+      return {
+        input: uploadFile.name,
+        content: await uploadFile.text(),
+      };
+    }
+
+    const input = mode === 'crawl' ? crawlSourceUrl.trim() : mode === 'curl' ? curlSourceText.trim() : fileSourceUrl.trim();
+    if (!input) throw new Error(emptySourceMessage(mode));
+    return { input };
+  }
+
+  async function importSpec(mode: ImportMode, auth: DocumentAuthConfig = { type: 'none' }, skipAuthCheck = false, updateVersionId?: string) {
+    let importInput: { input: string; content?: string };
+    try {
+      importInput = await getImportInput(mode);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : emptySourceMessage(mode);
+      setError(message);
+      setImportDialog({
+        open: true,
+        mode,
+        status: 'error',
+        progress: 100,
+        inputUrl: '',
+        message: '未开始',
+        error: message,
+      });
+      return;
+    }
+    const nextSourceUrl = importInput.input;
+    const matchingVersionId = getImportUpdateVersionId(mode);
+    const targetVersionId = updateVersionId !== undefined ? updateVersionId || undefined : matchingVersionId || undefined;
+    const updating = Boolean(targetVersionId);
+
+    setSyncingMode(mode);
+    setError('');
+    setImportDialog({
+      open: true,
+      mode,
+      status: 'running',
+      progress: mode === 'crawl' && !skipAuthCheck ? 6 : mode === 'curl' ? 14 : mode === 'crawl' ? 12 : 18,
+      inputUrl: nextSourceUrl,
+      message:
+        mode === 'crawl' && !skipAuthCheck
+          ? '正在检测文档访问权限'
+          : mode === 'crawl'
+            ? updating
+              ? '正在爬取并更新当前版本文档'
+              : '正在由 Node 爬取在线文档并识别 OpenAPI JSON 地址'
+            : mode === 'curl'
+              ? updating
+                ? '正在执行 CURL 并更新当前版本文档'
+                : '正在解析并执行 CURL 请求'
+              : mode === 'upload'
+                ? updating
+                  ? '正在解析上传文件并更新当前版本文档'
+                  : '正在读取并解析上传的 JSON / YAML 文件'
+                : updating
+                  ? '正在拉取并更新当前版本文档'
+                  : '正在由 Node 拉取并解析 OpenAPI JSON 文件',
+    });
+
+    try {
+      if (mode !== 'curl' && mode !== 'upload' && !skipAuthCheck && auth.type === 'none') {
+        const authCheck = await checkDocumentAuth(nextSourceUrl, mode);
+        if (authCheck.requiresAuth) {
+          setAuthPrompt({
+            open: true,
+            mode,
+            inputUrl: nextSourceUrl,
+            message: authCheck.message || '该文档地址需要用户名和密码',
+            updateVersionId: targetVersionId,
+          });
+          setImportDialog(null);
+          setSyncingMode('');
+          return;
+        }
+
+        setImportDialog((current) =>
+          current?.status === 'running'
+            ? {
+                ...current,
+                progress: mode === 'crawl' ? 12 : 18,
+                message:
+                  mode === 'crawl'
+                    ? updating
+                      ? '正在爬取并更新当前版本文档'
+                      : '正在由 Node 爬取在线文档并识别 OpenAPI JSON 地址'
+                    : updating
+                      ? '正在拉取并更新当前版本文档'
+                      : '正在由 Node 拉取并解析 OpenAPI JSON 文件',
+              }
+            : current,
+        );
+      }
+
+      const payload = await importOpenApi(nextSourceUrl, mode, auth, importInput.content, targetVersionId);
+      const nextDoc = payload.document;
+      const syncedAt = new Date().toISOString();
+      localStorage.setItem(STORAGE_SYNC_KEY, syncedAt);
+      localStorage.setItem(STORAGE_SOURCE_KEY, nextSourceUrl);
+      if (auth.type === 'basic') setDocAuthPassword('');
+      setTabsCacheReady(false);
+      setDoc(nextDoc);
+      setAllowEmptyDetail(false);
+      setOpenedEndpointTabs([]);
+      setLastSync(syncedAt);
+      setSelectedVersionId(payload.meta?.versionId || '');
+      setSelectedVersionMeta(payload.meta);
+      setResolvedSourceUrl(payload.meta?.resolvedUrl || nextSourceUrl);
+      applySourceDefaults(payload.meta, nextDoc);
+      setLoadState('ready');
+      if (payload.versions) setVersions(payload.versions);
+      else await loadVersionList();
+      setImportDialog({
+        open: true,
+        mode,
+        status: 'success',
+        progress: 100,
+        inputUrl: nextSourceUrl,
+        message: updating ? '文档已更新并覆盖原版本' : '文档已解析并保存为独立版本',
+        meta: payload.meta,
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : '导入失败，请检查地址或文档格式';
+      setError(message);
+      setImportDialog({
+        open: true,
+        mode,
+        status: 'error',
+        progress: 100,
+        inputUrl: nextSourceUrl,
+        message: '处理失败',
+        error: message,
+      });
+    } finally {
+      setSyncingMode('');
+    }
+  }
+
+  async function createBlankApiDocument() {
+    const title = blankDocTitle.trim();
+    if (!title) {
+      setError('请输入文档名称');
+      return;
+    }
+
+    const targetVersionId = blankUpdateVersionId || undefined;
+    const updating = Boolean(targetVersionId);
+    setSyncingMode('blank');
+    setError('');
+    setImportDialog({
+      open: true,
+      mode: 'blank',
+      status: 'running',
+      progress: 45,
+      inputUrl: title,
+      message: updating ? '正在更新当前 OpenAPI 文档' : '正在创建空白 OpenAPI 文档',
+    });
+
+    try {
+      const payload = await createOpenApiDocument({
+        title,
+        version: blankDocVersion.trim() || '1.0.0',
+        description: blankDocDescription.trim(),
+        versionId: targetVersionId,
+      });
+      const syncedAt = payload.meta?.savedAt || new Date().toISOString();
+      setTabsCacheReady(false);
+      setDoc(payload.document);
+      setAllowEmptyDetail(true);
+      setOpenedEndpointTabs([]);
+      setSelectedId('');
+      setLastSync(syncedAt);
+      setSelectedVersionId(payload.meta?.versionId || '');
+      setSelectedVersionMeta(payload.meta);
+      setResolvedSourceUrl(payload.meta?.resolvedUrl || payload.meta?.inputUrl || 'manual-document');
+      applySourceDefaults(payload.meta, payload.document);
+      setLoadState('ready');
+      if (payload.versions) setVersions(payload.versions);
+      else await loadVersionList();
+      setImportDialog({
+        open: true,
+        mode: 'blank',
+        status: 'success',
+        progress: 100,
+        inputUrl: title,
+        message: updating ? '文档已更新并覆盖原版本' : '空白文档已创建，可以继续新增 API 配置',
+        meta: payload.meta,
+      });
+      setBlankDocDialogOpen(false);
+      setBlankUpdateVersionId('');
+    } catch (err) {
+      const message = err instanceof Error ? err.message : '创建文档失败';
+      setError(message);
+      setImportDialog({
+        open: true,
+        mode: 'blank',
+        status: 'error',
+        progress: 100,
+        inputUrl: title,
+        message: '创建失败',
+        error: message,
+      });
+    } finally {
+      setSyncingMode('');
+    }
+  }
+
+  async function copyText(kind: 'ai' | 'json', text: string) {
+    await navigator.clipboard.writeText(text);
+    setCopied(kind);
+    window.setTimeout(() => setCopied(''), 1600);
+  }
+
+  function submitDocumentAuth() {
+    const targetVersionId = authPrompt?.updateVersionId ?? '';
+    setAuthPrompt(null);
+    void importSpec(authPrompt?.mode ?? 'crawl', {
+      type: 'basic',
+      username: docAuthUsername,
+      password: docAuthPassword,
+    }, true, targetVersionId);
+  }
+
+  function closeEndpointTab(tabId: string) {
+    setOpenedEndpointTabs((current) => {
+      const index = current.findIndex((tab) => tab.id === tabId);
+      const next = current.filter((tab) => tab.id !== tabId);
+      if (tabId === selectedId) {
+        const fallback = next[index] ?? next[index - 1];
+        setAllowEmptyDetail(!fallback);
+        setSelectedId(fallback?.id ?? '');
+      }
+      return next;
+    });
+  }
+
+  function selectEndpoint(endpointId: string) {
+    setAllowEmptyDetail(false);
+    setSelectedId(endpointId);
+  }
+
+  function updateOperationLinkDraft(endpoint: Endpoint, links: EndpointAssociationLinks) {
+    const draftKey = getOperationLinkDraftKey(selectedVersionId, endpoint);
+    setOperationLinkDrafts((current) => ({ ...current, [draftKey]: normalizeEndpointLinks(links) }));
+  }
+
+  async function updateVersionEnvironment(versionId: string, environmentName: string, environmentBaseUrl: string) {
+    const response = await fetch(VERSION_META_API_URL, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({ versionId, environmentName, environmentBaseUrl }),
+    });
+    const payload = await response.json();
+    if (!response.ok) throw new Error(payload.error || '环境保存失败');
+    const data = payload as VersionMetaResponse;
+    setVersions(data.versions ?? []);
+    if (versionId === selectedVersionId) {
+      setSelectedVersionMeta(data.meta);
+    }
+  }
+
+  async function deleteVersion(versionId: string) {
+    const response = await fetch(VERSION_DELETE_API_URL, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({ versionId }),
+    });
+    const payload = await response.json();
+    if (!response.ok) throw new Error(payload.error || '版本删除失败');
+    const data = payload as VersionDeleteResponse;
+    setVersions(data.versions ?? []);
+
+    if (versionId !== selectedVersionId) return;
+    if (data.nextVersionId) {
+      await loadCache(data.nextVersionId);
+      return;
+    }
+
+    setDoc(null);
+    setSelectedVersionId('');
+    setSelectedVersionMeta(undefined);
+    setOpenedEndpointTabs([]);
+    setLastSync('');
+    setResolvedSourceUrl('');
+    setLoadState('ready');
+  }
+
+  async function loadMockStatus() {
+    try {
+      const response = await fetch(MOCK_STATUS_API_URL, { cache: 'no-store' });
+      if (!response.ok) return;
+      setMockStatus((await response.json()) as MockStatusResponse);
+    } catch {
+      // Mock status is best-effort; the web app still works when unavailable.
+    }
+  }
+
+  async function startMockService() {
+    if (!doc || !stats.endpoints) {
+      setMockMessage('请先导入、爬取或新建 API 文档，并至少包含一个接口后再启动 MOCK 服务');
+      return;
+    }
+
+    setStartingMock(true);
+    setMockMessage('');
+    setError('');
+    try {
+      const response = await fetch(MOCK_START_API_URL, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+        },
+        body: JSON.stringify({ versionId: selectedVersionId || undefined }),
+      });
+      const payload = await response.json();
+      if (!response.ok) throw new Error(payload.error || 'MOCK 服务启动失败');
+      const status = payload as MockStatusResponse;
+      setMockStatus(status);
+      setMockMessage(status.mock?.url ? `MOCK 服务已启动：${status.mock.url}` : 'MOCK 服务已启动');
+    } catch (err) {
+      setMockMessage(err instanceof Error ? err.message : 'MOCK 服务启动失败');
+    } finally {
+      setStartingMock(false);
+    }
+  }
+
+  async function prepareVersionUpdate(version: DocumentVersionMeta) {
+    const versionId = version.versionId || '';
+    if (!versionId) throw new Error('请选择要更新的文档版本');
+    const versionMode = version.mode || '';
+    if (versionId !== selectedVersionId) {
+      await loadCache(versionId);
+      if (versionMode === 'document' || versionMode === 'manual') {
+        setBlankUpdateVersionId(versionId);
+        setBlankDocDialogOpen(true);
+      }
+      return;
+    }
+    applySourceDefaults(version, doc);
+    if (versionMode === 'document' || versionMode === 'manual') {
+      setBlankUpdateVersionId(versionId);
+      setBlankDocDialogOpen(true);
+    }
+    setError('');
+  }
+
+  async function saveManualApi(config: ManualApiOperationConfig) {
+    setSavingApi(true);
+    setError('');
+    try {
+      const payload = await saveCustomOperation(selectedVersionId || undefined, config, editingApiTarget);
+      const syncedAt = payload.meta?.savedAt || new Date().toISOString();
+      setDoc(payload.document);
+      setLastSync(syncedAt);
+      setSelectedVersionId(payload.meta?.versionId || '');
+      setSelectedVersionMeta(payload.meta);
+      setResolvedSourceUrl(payload.meta?.resolvedUrl || payload.meta?.inputUrl || 'manual-api-config');
+      setLoadState('ready');
+      setAddApiOpen(false);
+      setEditingApiConfig(undefined);
+      setEditingApiTarget(undefined);
+      await loadVersionList();
+    } catch (err) {
+      setError(err instanceof Error ? err.message : '新增接口保存失败');
+    } finally {
+      setSavingApi(false);
+    }
+  }
+
+  async function deleteManualApi(endpoint: Endpoint) {
+    if (!selectedVersionId) {
+      setError('请先选择一个本地缓存版本');
+      return;
+    }
+    if (!window.confirm(`确认删除 ${endpoint.method.toUpperCase()} ${endpoint.path}？`)) return;
+
+    setSavingApi(true);
+    setError('');
+    try {
+      const payload = await deleteCustomOperation(selectedVersionId, endpoint.method, endpoint.path);
+      setDoc(payload.document);
+      setLastSync(payload.meta?.savedAt || new Date().toISOString());
+      setSelectedVersionId(payload.meta?.versionId || selectedVersionId);
+      setSelectedVersionMeta(payload.meta);
+      setResolvedSourceUrl(payload.meta?.resolvedUrl || payload.meta?.inputUrl || 'manual-api-config');
+      setLoadState('ready');
+      setSelectedId('');
+      setOpenedEndpointTabs((current) => current.filter((tab) => tab.id !== endpoint.id));
+      await loadVersionList();
+    } catch (err) {
+      setError(err instanceof Error ? err.message : '删除接口失败');
+    } finally {
+      setSavingApi(false);
+    }
+  }
+
+  async function saveOperationLinks(endpoint: Endpoint, links: EndpointAssociationLinks) {
+    if (!selectedVersionId) {
+      throw new Error('请先选择一个本地缓存版本');
+    }
+
+    const response = await fetch(OPERATION_LINKS_API_URL, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({
+        versionId: selectedVersionId,
+        method: endpoint.method,
+        path: endpoint.path,
+        links,
+      }),
+    });
+    const payload = await response.json();
+    if (!response.ok) throw new Error(payload.error || '关联配置保存失败');
+    const data = payload as VersionSelectResponse;
+    setDoc(data.document);
+    setLastSync(data.meta?.savedAt || new Date().toISOString());
+    setSelectedVersionId(data.meta?.versionId || selectedVersionId);
+    setSelectedVersionMeta(data.meta);
+    setOperationLinkDrafts((current) => ({
+      ...current,
+      [getOperationLinkDraftKey(data.meta?.versionId || selectedVersionId, endpoint)]: normalizeEndpointLinks(links),
+    }));
+    if (data.versions) setVersions(data.versions);
+    else await loadVersionList();
+  }
+
+  const stats = useMemo(() => {
+    const paths = doc?.paths ? Object.keys(doc.paths).length : 0;
+    const schemaSource = doc?.components?.schemas ?? doc?.definitions ?? {};
+    const schemas = Object.keys(schemaSource).length;
+    return { paths, schemas, endpoints: endpoints.length, tags: tags.length };
+  }, [doc, endpoints.length, tags.length]);
+  const activeSourceCanUpdate = Boolean(getImportUpdateVersionId(activeSourceTab));
+
+  if (loadState === 'loading') {
+    return (
+      <main className="state-screen">
+        <Database className="state-icon" />
+        <h1>正在读取最新缓存</h1>
+        <p>如果没有缓存版本，将进入空文档状态。</p>
+      </main>
+    );
+  }
+
+  if (loadState === 'error') {
+    return (
+      <main className="state-screen">
+        <AlertCircle className="state-icon error" />
+        <h1>接口文档加载失败</h1>
+        <p>{error}</p>
+      </main>
+    );
+  }
+
+  return (
+    <div className="app-shell">
+      <header className="topbar">
+        <div>
+          <p className="eyebrow">OpenAPI 3.0 Console</p>
+          <h1>API Skill Console</h1>
+        </div>
+        <div className="topbar-actions">
+          <DocumentVersionManager
+            versions={versions}
+            selectedVersionId={selectedVersionId}
+            currentVersion={selectedVersion}
+            disabled={Boolean(syncingMode)}
+            onSelect={(versionId) => {
+              if (!versionId || versionId === selectedVersionId) return;
+              void loadCache(versionId);
+            }}
+            onPrepareUpdate={prepareVersionUpdate}
+            onUpdateEnvironment={updateVersionEnvironment}
+            onDelete={deleteVersion}
+          />
+          <button
+            className="primary-button"
+            onClick={() => {
+              setEditingApiConfig(undefined);
+              setEditingApiTarget(undefined);
+              setAddApiOpen(true);
+            }}
+          >
+            <Plus size={16} />
+            新增API配置
+          </button>
+          <div className="sync-meta">
+            <span>接口 {stats.endpoints}</span>
+            <span>Schema {stats.schemas}</span>
+            <span>{lastSync ? `同步 ${formatDate(lastSync)}` : '未加载文档'}</span>
+          </div>
+        </div>
+      </header>
+
+      <section className="source-panel">
+        <div className="source-panel-header">
+          <div className="source-tabs" role="tablist" aria-label="文档同步方式">
+            <button
+              className={activeSourceTab === 'file' ? 'active' : ''}
+              onClick={() => setActiveSourceTab('file')}
+              role="tab"
+              aria-selected={activeSourceTab === 'file'}
+            >
+              <RefreshCcw size={15} />
+              在线文档
+            </button>
+            <button
+              className={activeSourceTab === 'crawl' ? 'active' : ''}
+              onClick={() => setActiveSourceTab('crawl')}
+              role="tab"
+              aria-selected={activeSourceTab === 'crawl'}
+            >
+              <Globe2 size={15} />
+              爬取网页
+            </button>
+            <button
+              className={activeSourceTab === 'curl' ? 'active' : ''}
+              onClick={() => setActiveSourceTab('curl')}
+              role="tab"
+              aria-selected={activeSourceTab === 'curl'}
+            >
+              <Send size={15} />
+              执行CURL
+            </button>
+            <button
+              className={activeSourceTab === 'upload' ? 'active' : ''}
+              onClick={() => setActiveSourceTab('upload')}
+              role="tab"
+              aria-selected={activeSourceTab === 'upload'}
+            >
+              <FileCode2 size={15} />
+              导入文件
+            </button>
+          </div>
+          <div className="source-panel-actions">
+            <button className="secondary-button" onClick={startMockService} disabled={startingMock}>
+              <Server size={16} className={startingMock ? 'spin' : ''} />
+              {startingMock ? '启动中' : '启动MOCK服务'}
+            </button>
+            <button
+              className="secondary-button"
+              onClick={() => {
+                setBlankUpdateVersionId('');
+                setBlankDocDialogOpen(true);
+              }}
+              disabled={Boolean(syncingMode)}
+            >
+              <Braces size={16} />
+              新建文档
+            </button>
+          </div>
+        </div>
+        <div className="source-form">
+          {activeSourceTab === 'upload' ? (
+            <label key="source-upload-field" className="source-file-picker">
+              <FileCode2 size={16} />
+              <input
+                key="source-upload-input"
+                ref={uploadInputRef}
+                type="file"
+                accept=".json,.yaml,.yml,application/json,application/yaml,text/yaml,text/x-yaml"
+                onChange={(event) => setUploadFile(event.target.files?.[0] ?? null)}
+              />
+              <span>{uploadFile ? uploadFile.name : '选择 JSON / YAML 文件'}</span>
+            </label>
+          ) : (
+            <label key="source-text-field" className={`source-input ${activeSourceTab === 'curl' ? 'source-input-multiline' : ''}`}>
+              <Link2 size={16} />
+              {activeSourceTab === 'curl' ? (
+                <textarea
+                  key="source-curl-input"
+                  value={curlSourceText}
+                  onChange={(event) => setCurlSourceText(event.target.value)}
+                  placeholder="粘贴 curl 命令，例如 curl 'https://example.com/openapi.yaml' -H 'accept: application/yaml'"
+                  spellCheck={false}
+                />
+              ) : (
+                <input
+                  key="source-url-input"
+                  value={activeSourceTab === 'file' ? fileSourceUrl : crawlSourceUrl}
+                  onChange={(event) => {
+                    if (activeSourceTab === 'file') setFileSourceUrl(event.target.value);
+                    else setCrawlSourceUrl(event.target.value);
+                  }}
+                  placeholder={
+                    activeSourceTab === 'file'
+                      ? '输入 Swagger/OpenAPI JSON 或 YAML 文件地址'
+                      : '输入 Swagger UI / Knife4j / Redoc 在线文档页地址'
+                  }
+                />
+              )}
+            </label>
+          )}
+          <button
+            className="primary-button"
+            onClick={() => {
+              void importSpec(activeSourceTab);
+            }}
+            disabled={Boolean(syncingMode) || !getActiveSourceValue()}
+          >
+            {activeSourceTab === 'crawl' ? (
+              <Globe2 size={16} className={syncingMode === 'crawl' ? 'spin' : ''} />
+            ) : activeSourceTab === 'curl' ? (
+              <Send size={16} className={syncingMode === 'curl' ? 'spin' : ''} />
+            ) : activeSourceTab === 'upload' ? (
+              <FileCode2 size={16} className={syncingMode === 'upload' ? 'spin' : ''} />
+            ) : (
+              <RefreshCcw size={16} className={syncingMode === 'file' ? 'spin' : ''} />
+            )}
+            {syncingMode === activeSourceTab ? '处理中' : activeSourceCanUpdate ? '更新' : '确认'}
+          </button>
+          <button className="secondary-button" onClick={clearActiveSource} disabled={Boolean(syncingMode) || !getActiveSourceValue()}>
+            清空
+          </button>
+        </div>
+        <div className="source-meta">
+          当前文档源：<span>{resolvedSourceUrl || '未加载'}</span>
+        </div>
+        {mockStatus?.running && mockStatus.mock ? (
+          <div className="source-meta">
+            MOCK服务：<span>{mockStatus.mock.url}</span>
+            <small>{mockStatus.mock.routesCount} routes</small>
+          </div>
+        ) : null}
+        {mockMessage ? <div className={`version-message ${mockMessage.includes('失败') || mockMessage.includes('请先') ? 'error' : ''}`}>{mockMessage}</div> : null}
+      </section>
+
+      {error ? (
+        <div className="inline-error">
+          <AlertCircle size={16} />
+          {error}
+        </div>
+      ) : null}
+
+      {importDialog?.open ? <ImportStatusDialog state={importDialog} onClose={() => setImportDialog(null)} /> : null}
+      {authPrompt?.open ? (
+        <DocumentAuthDialog
+          state={authPrompt}
+          username={docAuthUsername}
+          password={docAuthPassword}
+          onUsernameChange={setDocAuthUsername}
+          onPasswordChange={setDocAuthPassword}
+          onClose={() => setAuthPrompt(null)}
+          onSubmit={submitDocumentAuth}
+        />
+      ) : null}
+      {blankDocDialogOpen ? (
+        <BlankDocumentDialog
+          updating={Boolean(blankUpdateVersionId)}
+          title={blankDocTitle}
+          version={blankDocVersion}
+          description={blankDocDescription}
+          saving={syncingMode === 'blank'}
+          onTitleChange={setBlankDocTitle}
+          onVersionChange={setBlankDocVersion}
+          onDescriptionChange={setBlankDocDescription}
+          onClose={() => {
+            if (syncingMode === 'blank') return;
+            setBlankDocDialogOpen(false);
+            setBlankUpdateVersionId('');
+          }}
+          onSubmit={createBlankApiDocument}
+        />
+      ) : null}
+      {addApiOpen ? (
+        <AddApiDialog
+          selectedVersionId={selectedVersionId}
+          saving={savingApi}
+          initialConfig={editingApiConfig}
+          onClose={() => {
+            setAddApiOpen(false);
+            setEditingApiConfig(undefined);
+            setEditingApiTarget(undefined);
+          }}
+          onSave={saveManualApi}
+        />
+      ) : null}
+
+      <section className="workspace">
+        <aside className="sidebar">
+          <div className="search-box">
+            <Search size={17} />
+            <input
+              value={query}
+              onChange={(event) => setQuery(event.target.value)}
+              placeholder="搜索路径、摘要、参数、tag"
+            />
+            {query ? (
+              <button type="button" className="search-clear-button" onClick={() => setQuery('')} aria-label="清空搜索">
+                <X size={15} />
+              </button>
+            ) : null}
+          </div>
+
+          <div className="filters">
+            <label>
+              <Filter size={15} />
+              <select value={tag} onChange={(event) => setTag(event.target.value)}>
+                <option value="all">全部分组 ({stats.tags})</option>
+                {tags.map((item) => (
+                  <option key={item.name} value={item.name}>
+                    {item.name} ({item.count})
+                  </option>
+                ))}
+              </select>
+            </label>
+            <label className="checkbox-line">
+              <input type="checkbox" checked={bodyOnly} onChange={(event) => setBodyOnly(event.target.checked)} />
+              仅看有请求体
+            </label>
+          </div>
+
+          <div className="method-tabs" aria-label="method filters">
+            {methodOptions.map((item) => (
+              <button
+                key={item}
+                className={method === item ? 'active' : ''}
+                onClick={() => setMethod(item)}
+                title={item === 'all' ? '全部方法' : item.toUpperCase()}
+              >
+                {item === 'all' ? 'ALL' : item.toUpperCase()}
+              </button>
+            ))}
+          </div>
+
+          <div className="endpoint-count">
+            显示 {filteredEndpoints.length} / {endpoints.length}
+          </div>
+
+          <div className="endpoint-list">
+            {filteredEndpoints.map((endpoint) => (
+              <button
+                key={endpoint.id}
+                className={`endpoint-item ${endpoint.id === selectedEndpoint?.id ? 'selected' : ''}`}
+                onClick={() => selectEndpoint(endpoint.id)}
+              >
+                <span className={`method method-${endpoint.method}`}>{endpoint.method.toUpperCase()}</span>
+                <span className="endpoint-main">
+                  <strong>{endpoint.summary}</strong>
+                  <small>{endpoint.path}</small>
+                </span>
+              </button>
+            ))}
+          </div>
+        </aside>
+
+        <main className="detail-pane">
+          {openedEndpointTabs.length ? (
+            <div className="opened-api-tabs" aria-label="已打开 API 页签">
+              {openedEndpointTabs.map((tab) => (
+                <div
+                  key={tab.id}
+                  className={`opened-api-tab opened-api-tab-${tab.method} ${tab.id === selectedEndpoint?.id ? 'active' : ''}`}
+                  role="button"
+                  tabIndex={0}
+                  onClick={() => selectEndpoint(tab.id)}
+                  onKeyDown={(event) => {
+                    if (event.key !== 'Enter' && event.key !== ' ') return;
+                    event.preventDefault();
+                    selectEndpoint(tab.id);
+                  }}
+                  title={`${tab.method.toUpperCase()} ${tab.path}`}
+                >
+                  <span className={`opened-api-tab-method method-${tab.method}`}>{tab.method.toUpperCase()}</span>
+                  <span className="opened-api-tab-text">
+                    <strong>{tab.summary}</strong>
+                  </span>
+                  <button
+                    type="button"
+                    className="opened-api-tab-close"
+                    aria-label="关闭页签"
+                    onClick={(event) => {
+                      event.stopPropagation();
+                      closeEndpointTab(tab.id);
+                    }}
+                  >
+                    <X size={14} />
+                  </button>
+                </div>
+              ))}
+            </div>
+          ) : null}
+          {doc && selectedEndpoint ? (
+            <EndpointDetail
+              doc={doc}
+              endpoint={selectedEndpoint}
+              copied={copied}
+              onCopy={(kind, text) => copyText(kind, text)}
+              onEdit={() => {
+                setEditingApiConfig(endpointToManualApiOperationConfig(doc, selectedEndpoint));
+                setEditingApiTarget({ method: selectedEndpoint.method, path: selectedEndpoint.path });
+                setAddApiOpen(true);
+              }}
+              onDelete={() => void deleteManualApi(selectedEndpoint)}
+              onSaveLinks={saveOperationLinks}
+              linksDraft={selectedOperationLinkDraft ?? normalizeEndpointLinks(selectedEndpoint.operation['x-apiskill-links'])}
+              onLinksDraftChange={(links) => updateOperationLinkDraft(selectedEndpoint, links)}
+              environmentBaseUrl={selectedVersion?.environmentBaseUrl || ''}
+            />
+          ) : !doc ? (
+            <div className="empty-state">
+              <FileCode2 size={32} />
+              <h2>暂无 API 文档数据</h2>
+              <p>导入现有 Swagger/OpenAPI 文档，或新建空白文档后从零维护接口。</p>
+            </div>
+          ) : filteredEndpoints.length ? (
+            <div className="empty-state">
+              <FileCode2 size={32} />
+              <h2>未打开接口</h2>
+              <p>从左侧列表选择接口后会在上方生成可关闭页签。</p>
+            </div>
+          ) : (
+            <div className="empty-state">
+              <FileCode2 size={32} />
+              <h2>没有匹配的接口</h2>
+              <p>调整搜索词、分组或方法过滤条件。</p>
+            </div>
+          )}
+        </main>
+      </section>
+    </div>
+  );
+}
+
+function DocumentAuthDialog({
+  state,
+  username,
+  password,
+  onUsernameChange,
+  onPasswordChange,
+  onClose,
+  onSubmit,
+}: {
+  state: AuthPromptState;
+  username: string;
+  password: string;
+  onUsernameChange: (value: string) => void;
+  onPasswordChange: (value: string) => void;
+  onClose: () => void;
+  onSubmit: () => void;
+}) {
+  return (
+    <div className="modal-backdrop" role="dialog" aria-modal="true" aria-labelledby="document-auth-title">
+      <div className="auth-dialog">
+        <div className="import-dialog-header">
+          <div>
+            <p className="eyebrow">Document Auth</p>
+            <h2 id="document-auth-title">输入文档访问凭据</h2>
+          </div>
+          <span className="import-badge running">需要登录</span>
+        </div>
+
+        <div className="auth-dialog-body">
+          <div className="auth-message">
+            <LockKeyhole size={18} />
+            <span>{state.message}</span>
+          </div>
+          <div className="auth-target">
+            <span>文档地址</span>
+            <strong>{state.inputUrl}</strong>
+          </div>
+          <div className="auth-fields">
+            <label>
+              用户名
+              <input value={username} onChange={(event) => onUsernameChange(event.target.value)} autoComplete="username" autoFocus />
+            </label>
+            <label>
+              密码
+              <input
+                value={password}
+                onChange={(event) => onPasswordChange(event.target.value)}
+                type="password"
+                autoComplete="current-password"
+                onKeyDown={(event) => {
+                  if (event.key === 'Enter') onSubmit();
+                }}
+              />
+            </label>
+          </div>
+        </div>
+
+        <div className="import-dialog-actions">
+          <button className="secondary-button" onClick={onClose}>
+            取消
+          </button>
+          <button className="primary-button" onClick={onSubmit}>
+            <KeyRound size={16} />
+            使用凭据继续
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function BlankDocumentDialog({
+  updating,
+  title,
+  version,
+  description,
+  saving,
+  onTitleChange,
+  onVersionChange,
+  onDescriptionChange,
+  onClose,
+  onSubmit,
+}: {
+  updating: boolean;
+  title: string;
+  version: string;
+  description: string;
+  saving: boolean;
+  onTitleChange: (value: string) => void;
+  onVersionChange: (value: string) => void;
+  onDescriptionChange: (value: string) => void;
+  onClose: () => void;
+  onSubmit: () => void;
+}) {
+  return (
+    <div className="modal-backdrop" role="dialog" aria-modal="true" aria-labelledby="blank-document-title">
+      <div className="auth-dialog">
+        <div className="import-dialog-header">
+          <div>
+            <p className="eyebrow">OpenAPI Document</p>
+            <h2 id="blank-document-title">{updating ? '更新文档' : '新建文档'}</h2>
+          </div>
+          <button className="icon-secondary-button" onClick={onClose} aria-label="关闭" disabled={saving}>
+            <X size={17} />
+          </button>
+        </div>
+
+        <div className="blank-document-dialog-body">
+          <label className="source-input">
+            <FileCode2 size={16} />
+            <input
+              value={title}
+              onChange={(event) => onTitleChange(event.target.value)}
+              placeholder="文档名称，例如 Customer Service API"
+              autoFocus
+            />
+          </label>
+          <label className="source-input">
+            <Braces size={16} />
+            <input value={version} onChange={(event) => onVersionChange(event.target.value)} placeholder="文档版本，例如 1.0.0" />
+          </label>
+          <label className="source-input">
+            <Pencil size={16} />
+            <input value={description} onChange={(event) => onDescriptionChange(event.target.value)} placeholder="文档描述，可选" />
+          </label>
+        </div>
+
+        <div className="import-dialog-actions">
+          <button className="secondary-button" onClick={onClose} disabled={saving}>
+            取消
+          </button>
+          <button className="primary-button" onClick={onSubmit} disabled={saving || !title.trim()}>
+            <Braces size={16} className={saving ? 'spin' : ''} />
+            {saving ? '处理中' : updating ? '更新' : '创建'}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function ImportStatusDialog({ state, onClose }: { state: ImportDialogState; onClose: () => void }) {
+  const title =
+    state.mode === 'blank'
+      ? '新建空白文档'
+      : state.mode === 'crawl'
+      ? '爬取在线文档'
+      : state.mode === 'curl'
+        ? '执行 CURL'
+        : state.mode === 'upload'
+          ? '上传 JSON / YAML 文件'
+          : '导入 JSON / YAML 文件';
+  const canClose = state.status !== 'running';
+
+  return (
+    <div className="modal-backdrop" role="dialog" aria-modal="true" aria-labelledby="import-status-title">
+      <div className="import-dialog">
+        <div className="import-dialog-header">
+          <div>
+            <p className="eyebrow">OpenAPI Import</p>
+            <h2 id="import-status-title">{title}</h2>
+          </div>
+          <span className={`import-badge ${state.status}`}>
+            {state.status === 'running' ? '处理中' : state.status === 'success' ? '已完成' : '失败'}
+          </span>
+        </div>
+
+        <div className="progress-track" aria-label="导入进度">
+          <div className={`progress-bar ${state.status}`} style={{ width: `${state.progress}%` }} />
+        </div>
+
+        <div className="import-summary">
+          <div>
+            <span>输入地址</span>
+            <strong>{state.inputUrl || '-'}</strong>
+          </div>
+          <div>
+            <span>当前状态</span>
+            <strong>{state.message}</strong>
+          </div>
+          {state.meta?.resolvedUrl ? (
+            <div>
+              <span>解析地址</span>
+              <strong>{state.meta.resolvedUrl}</strong>
+            </div>
+          ) : null}
+          {state.meta?.versionId ? (
+            <div>
+              <span>版本</span>
+              <strong>{state.meta.versionId}</strong>
+            </div>
+          ) : null}
+          {state.meta?.savedPath ? (
+            <div>
+              <span>保存位置</span>
+              <strong>{state.meta.savedPath}</strong>
+            </div>
+          ) : null}
+          {state.status === 'success' ? (
+            <div className="import-counts">
+              <span>接口路径 {state.meta?.paths ?? 0}</span>
+              <span>Schema {state.meta?.schemas ?? 0}</span>
+            </div>
+          ) : null}
+          {state.error ? (
+            <div className="import-error">
+              <AlertCircle size={16} />
+              {state.error}
+            </div>
+          ) : null}
+        </div>
+
+        <div className="import-dialog-actions">
+          <button className="secondary-button" onClick={onClose} disabled={!canClose}>
+            {canClose ? '关闭' : '处理中'}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+async function importOpenApi(url: string, mode: ImportMode, auth: DocumentAuthConfig, content?: string, versionId?: string) {
+  const response = await fetch(IMPORT_API_URL, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify({ url, mode, auth, content, versionId }),
+  });
+  const payload = await response.json();
+  if (!response.ok) {
+    throw new Error(payload.error || '导入失败');
+  }
+  return payload as ImportResponse;
+}
+
+async function createOpenApiDocument(input: { title: string; version: string; description?: string; versionId?: string }) {
+  const response = await fetch(DOCUMENT_CREATE_API_URL, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify(input),
+  });
+  const payload = await response.json();
+  if (!response.ok) {
+    throw new Error(payload.error || '创建文档失败');
+  }
+  return payload as ImportResponse;
+}
+
+async function checkDocumentAuth(url: string, mode: ImportMode) {
+  const response = await fetch(AUTH_CHECK_API_URL, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify({ url, mode }),
+  });
+  const payload = await response.json();
+  if (!response.ok) {
+    throw new Error(payload.error || '检测文档访问权限失败');
+  }
+  return payload as AuthCheckResponse;
+}
+
+async function saveCustomOperation(versionId: string | undefined, config: ManualApiOperationConfig, replaceTarget?: { method: HttpMethod; path: string }) {
+  const response = await fetch(CUSTOM_OPERATION_API_URL, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify({ versionId, config, replaceTarget }),
+  });
+  const payload = await response.json();
+  if (!response.ok) {
+    throw new Error(payload.error || '新增接口保存失败');
+  }
+  return payload as ImportResponse;
+}
+
+async function deleteCustomOperation(versionId: string, method: HttpMethod, path: string) {
+  const response = await fetch(DELETE_OPERATION_API_URL, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify({ versionId, method, path }),
+  });
+  const payload = await response.json();
+  if (!response.ok) {
+    throw new Error(payload.error || '删除接口失败');
+  }
+  return payload as ImportResponse;
+}
+
+function EndpointDetail({
+  doc,
+  endpoint,
+  copied,
+  onCopy,
+  onEdit,
+  onDelete,
+  onSaveLinks,
+  linksDraft,
+  onLinksDraftChange,
+  environmentBaseUrl,
+}: {
+  doc: SwaggerDocument;
+  endpoint: Endpoint;
+  copied: 'ai' | 'json' | '';
+  onCopy: (kind: 'ai' | 'json', text: string) => void;
+  onEdit: () => void;
+  onDelete: () => void;
+  onSaveLinks: (endpoint: Endpoint, links: EndpointAssociationLinks) => Promise<void>;
+  linksDraft: EndpointAssociationLinks;
+  onLinksDraftChange: (links: EndpointAssociationLinks) => void;
+  environmentBaseUrl: string;
+}) {
+  const params = useMemo(() => parameterRows(doc, endpoint.operation.parameters), [doc, endpoint]);
+  const requestBodies = useMemo(() => requestBodyRows(doc, endpoint.operation), [doc, endpoint]);
+  const responses = useMemo(() => responseRows(doc, endpoint.operation), [doc, endpoint]);
+  const aiText = useMemo(() => buildApiCliText(doc, endpoint), [doc, endpoint]);
+  const rawText = useMemo(() => buildRawSchemaJson(endpoint), [endpoint]);
+  const [activeDetailTab, setActiveDetailTab] = useState<DetailTab>('ai');
+  const [pathCopied, setPathCopied] = useState(false);
+  const activeCopyText = activeDetailTab === 'json' ? rawText : aiText;
+  const activeCopyLabel = activeDetailTab === 'json' ? '复制原始 Operation' : '复制 API CLI';
+
+  function copyEndpointPath() {
+    copyTextWithSelection(endpoint.path);
+    void navigator.clipboard.writeText(endpoint.path).catch(() => undefined);
+    setPathCopied(true);
+    window.setTimeout(() => setPathCopied(false), 1600);
+  }
+
+  return (
+    <article className="endpoint-detail">
+      <div className="detail-header">
+        <div>
+          <div className="endpoint-title-line">
+            <span className={`method method-${endpoint.method}`}>{endpoint.method.toUpperCase()}</span>
+            <h2>{endpoint.summary}</h2>
+                                  <div className="tag-row">
+            {endpoint.tags.map((item) => (
+              <span key={item}>{item}</span>
+            ))}
+          </div>
+          </div>
+          <div className="path-row">
+
+            <code className="path-line">{endpoint.path}</code>
+            <button type="button" className="path-copy-button" onClick={copyEndpointPath} title="复制 API 路由地址">
+              {pathCopied ? <Check size={14} /> : <ClipboardCopy size={14} />}
+              <span>{pathCopied ? '已复制' : '复制'}</span>
+            </button>
+          </div>
+
+        </div>
+        <div className="detail-actions">
+          <button className="secondary-button" onClick={onEdit}>
+            <Pencil size={15} />
+            编辑
+          </button>
+          <button className="danger-button" onClick={onDelete}>
+            <Trash2 size={15} />
+            删除
+          </button>
+        </div>
+      </div>
+
+      {endpoint.operation.description ? <p className="description">{endpoint.operation.description}</p> : null}
+
+      <section className="copy-preview">
+        <div className="copy-preview-toolbar">
+          <div className="copy-tabs" role="tablist" aria-label="可复制内容">
+            <button
+              className={activeDetailTab === 'ai' ? 'active' : ''}
+              onClick={() => setActiveDetailTab('ai')}
+              role="tab"
+              aria-selected={activeDetailTab === 'ai'}
+            >
+              <ClipboardCopy size={15} />
+              API Cli
+            </button>
+            <button
+              className={activeDetailTab === 'json' ? 'active' : ''}
+              onClick={() => setActiveDetailTab('json')}
+              role="tab"
+              aria-selected={activeDetailTab === 'json'}
+            >
+              <Braces size={15} />
+              原始 Operation
+            </button>
+            <button
+              className={activeDetailTab === 'test' ? 'active' : ''}
+              onClick={() => setActiveDetailTab('test')}
+              role="tab"
+              aria-selected={activeDetailTab === 'test'}
+            >
+              <Send size={15} />
+              测试请求
+            </button>
+            <button
+              className={activeDetailTab === 'links' ? 'active' : ''}
+              onClick={() => setActiveDetailTab('links')}
+              role="tab"
+              aria-selected={activeDetailTab === 'links'}
+            >
+              <Link2 size={15} />
+              关联地址
+            </button>
+          </div>
+          {activeDetailTab === 'test' || activeDetailTab === 'links' ? null : (
+            <button className="copy-inline-button" onClick={() => onCopy(activeDetailTab, activeCopyText)}>
+              {copied === activeDetailTab ? <Check size={16} /> : <ClipboardCopy size={16} />}
+              {copied === activeDetailTab ? '已复制' : activeCopyLabel}
+            </button>
+          )}
+        </div>
+        {activeDetailTab === 'test' ? (
+          <RequestTester doc={doc} endpoint={endpoint} environmentBaseUrl={environmentBaseUrl} />
+        ) : activeDetailTab === 'links' ? (
+          <EndpointLinksConfig endpoint={endpoint} links={linksDraft} onChange={onLinksDraftChange} onSave={(links) => onSaveLinks(endpoint, links)} />
+        ) : (
+          <pre className="copy-preview-content">{activeCopyText}</pre>
+        )}
+      </section>
+
+      <Section title="请求参数" count={params.length}>
+        <FieldTable rows={params} empty="无 query / path / header 参数" />
+      </Section>
+
+      <Section title="请求体" count={Object.values(requestBodies).reduce((sum, rows) => sum + rows.length, 0)}>
+        {Object.keys(requestBodies).length ? (
+          Object.entries(requestBodies).map(([mediaType, rows]) => (
+            <div key={mediaType} className="media-block">
+              <h4>{mediaType}</h4>
+              <FieldTable rows={rows} empty="空对象或无字段说明" />
+            </div>
+          ))
+        ) : (
+          <p className="muted">无请求体</p>
+        )}
+      </Section>
+
+      <Section title="响应字段" count={Object.values(responses).reduce((sum, media) => sum + Object.values(media).flat().length, 0)}>
+        {Object.keys(endpoint.operation.responses ?? {}).length ? (
+          Object.entries(endpoint.operation.responses ?? {}).map(([status, response]) => {
+            const mediaRows = responses[status] ?? {};
+            return (
+              <div key={status} className="response-block">
+                <div className="response-heading">
+                  <strong>{status}</strong>
+                  <span>{response.description || '无描述'}</span>
+                </div>
+                {Object.keys(mediaRows).length ? (
+                  Object.entries(mediaRows).map(([mediaType, rows]) => (
+                    <div key={mediaType} className="media-block">
+                      <h4>{mediaType}</h4>
+                      <FieldTable rows={rows} empty="空对象或无字段说明" />
+                    </div>
+                  ))
+                ) : (
+                  <p className="muted">无字段说明</p>
+                )}
+              </div>
+            );
+          })
+        ) : (
+          <p className="muted">无响应说明</p>
+        )}
+      </Section>
+    </article>
+  );
+}
+
+function EndpointLinksConfig({
+  endpoint,
+  links,
+  onChange,
+  onSave,
+}: {
+  endpoint: Endpoint;
+  links: EndpointAssociationLinks;
+  onChange: (links: EndpointAssociationLinks) => void;
+  onSave: (links: EndpointAssociationLinks) => Promise<void>;
+}) {
+  const [saving, setSaving] = useState(false);
+  const [message, setMessage] = useState('');
+
+  useEffect(() => {
+    setMessage('');
+  }, [endpoint.id]);
+
+  async function save() {
+    setSaving(true);
+    setMessage('');
+    try {
+      await onSave(links);
+      setMessage('关联配置已保存');
+    } catch (err) {
+      setMessage(err instanceof Error ? err.message : '关联配置保存失败');
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  return (
+    <div className="endpoint-links-config">
+      {message ? <div className={`version-message ${message.includes('失败') ? 'error' : ''}`}>{message}</div> : null}
+      <div className="links-grid">
+        <AssociatedLinkEditor
+          title="原型地址"
+          value={links.prototype ?? defaultAssociatedLink()}
+          onChange={(value) => onChange({ ...links, prototype: value })}
+        />
+        <AssociatedLinkEditor
+          title="UI地址"
+          value={links.ui ?? defaultAssociatedLink()}
+          onChange={(value) => onChange({ ...links, ui: value })}
+        />
+      </div>
+      <div className="links-actions">
+        <button className="primary-button" onClick={save} disabled={saving}>
+          <Check size={16} />
+          {saving ? '保存中' : '保存关联配置'}
+        </button>
+      </div>
+    </div>
+  );
+}
+
+function AssociatedLinkEditor({
+  title,
+  value,
+  onChange,
+}: {
+  title: string;
+  value: NonNullable<EndpointAssociationLinks['prototype']>;
+  onChange: (value: NonNullable<EndpointAssociationLinks['prototype']>) => void;
+}) {
+  const isOnline = value.sourceType === 'online';
+  const isCurl = value.sourceType === 'curl';
+
+  function patch(next: Partial<NonNullable<EndpointAssociationLinks['prototype']>>) {
+    onChange({ ...value, ...next });
+  }
+
+  function copyLinkValue() {
+    const text = isCurl ? value.curl : value.url;
+    if (!text) return;
+    copyTextWithSelection(text);
+    void navigator.clipboard.writeText(text).catch(() => undefined);
+  }
+
+  return (
+    <section className="tester-panel link-editor-panel">
+      <div className="tester-panel-title">
+        <Link2 size={15} />
+        {title}
+      </div>
+      <div className="tester-form-grid">
+        <label>
+          类型
+          <select value={value.sourceType || 'local'} onChange={(event) => patch({ sourceType: event.target.value as 'local' | 'online' | 'curl' })}>
+            <option value="local">本地文件地址</option>
+            <option value="online">在线地址</option>
+            <option value="curl">CURL</option>
+          </select>
+        </label>
+        <label>
+          标题
+          <input value={value.title || ''} onChange={(event) => patch({ title: event.target.value })} placeholder="例如 Figma 原型 / 用户列表页面" />
+        </label>
+        {isCurl ? (
+          <label className="span-all">
+            CURL 命令
+            <textarea
+              value={value.curl || ''}
+              onChange={(event) => patch({ curl: event.target.value })}
+              placeholder="curl 'https://example.com/prototype' -H 'Authorization: Bearer ...'"
+              spellCheck={false}
+            />
+          </label>
+        ) : (
+          <label className="span-all">
+            地址
+            <input
+              value={value.url || ''}
+              onChange={(event) => patch({ url: event.target.value })}
+              placeholder={isOnline ? 'https://example.com/prototype' : '/Users/name/project/design/user-list.fig'}
+            />
+          </label>
+        )}
+        {isOnline ? (
+          <>
+            <label>
+              访问方式
+              <select value={value.authType || 'none'} onChange={(event) => patch({ authType: event.target.value as NonNullable<typeof value.authType> })}>
+                <option value="none">无需登录</option>
+                <option value="browser">浏览器登录 / Cookie</option>
+                <option value="bearer">Bearer Token</option>
+                <option value="header">自定义 Header</option>
+              </select>
+            </label>
+            {value.authType === 'header' ? (
+              <label>
+                Header 名称
+                <input value={value.headerName || ''} onChange={(event) => patch({ headerName: event.target.value })} placeholder="X-Auth-Token" />
+              </label>
+            ) : null}
+            {value.authType === 'bearer' || value.authType === 'header' ? (
+              <label className="span-all">
+                Token / Header 值
+                <input
+                  value={value.token || ''}
+                  onChange={(event) => patch({ token: event.target.value })}
+                  placeholder="仅保存在本地文档缓存中，用于记录访问凭据"
+                  type="password"
+                />
+              </label>
+            ) : null}
+          </>
+        ) : null}
+        <label className="span-all">
+          备注
+          <input
+            value={value.note || ''}
+            onChange={(event) => patch({ note: event.target.value })}
+            placeholder={
+              isCurl
+                ? '例如 CURL 里的 token 来源、过期方式或请求前置条件'
+                : isOnline
+                  ? '例如需要先登录公司 SSO，或 token 过期时找谁更新'
+                  : '例如本地原型文件位置、分支或打开方式'
+            }
+          />
+        </label>
+      </div>
+      <div className="link-editor-actions">
+        <button className="secondary-button" onClick={copyLinkValue} disabled={!(isCurl ? value.curl : value.url)}>
+          <ClipboardCopy size={15} />
+          {isCurl ? '复制CURL' : '复制地址'}
+        </button>
+        {isOnline && value.url ? (
+          <a className="secondary-button link-button" href={value.url} target="_blank" rel="noreferrer">
+            <Link2 size={15} />
+            打开地址
+          </a>
+        ) : null}
+      </div>
+    </section>
+  );
+}
+
+function normalizeEndpointLinks(value?: EndpointAssociationLinks): EndpointAssociationLinks {
+  return {
+    prototype: normalizeAssociatedLink(value?.prototype),
+    ui: normalizeAssociatedLink(value?.ui),
+  };
+}
+
+function normalizeAssociatedLink(value?: EndpointAssociationLinks['prototype']): NonNullable<EndpointAssociationLinks['prototype']> {
+  const sourceType = value?.sourceType === 'online' || value?.sourceType === 'curl' ? value.sourceType : 'local';
+  return {
+    ...defaultAssociatedLink(),
+    ...(value ?? {}),
+    sourceType,
+    authType: value?.authType || 'none',
+  };
+}
+
+function defaultAssociatedLink(): NonNullable<EndpointAssociationLinks['prototype']> {
+  return {
+    sourceType: 'local',
+    title: '',
+    url: '',
+    curl: '',
+    authType: 'none',
+    token: '',
+    headerName: '',
+    note: '',
+  };
+}
+
+function RequestTester({ doc, endpoint, environmentBaseUrl }: { doc: SwaggerDocument; endpoint: Endpoint; environmentBaseUrl: string }) {
+  const parameters = endpoint.operation.parameters ?? [];
+  const pathParams = parameters.filter((item) => item.in === 'path');
+  const queryParams = parameters.filter((item) => item.in === 'query');
+  const headerParams = parameters.filter((item) => item.in === 'header');
+  const bodyMedia = useMemo(() => pickRequestBodyMedia(endpoint), [endpoint]);
+  const previousAutoBaseUrlRef = useRef('');
+  const [baseUrl, setBaseUrl] = useState('');
+  const [authType, setAuthType] = useState<AuthType>('none');
+  const [authValue, setAuthValue] = useState('');
+  const [apiKeyName, setApiKeyName] = useState('Authorization');
+  const [apiKeyLocation, setApiKeyLocation] = useState<ApiKeyLocation>('header');
+  const [basicUsername, setBasicUsername] = useState('');
+  const [basicPassword, setBasicPassword] = useState('');
+  const [paramValues, setParamValues] = useState<Record<string, string>>({});
+  const [headerValues, setHeaderValues] = useState<Record<string, string>>({});
+  const [bodyText, setBodyText] = useState('');
+  const [customHeadersText, setCustomHeadersText] = useState('{\n  "Content-Type": "application/json"\n}');
+  const [sending, setSending] = useState(false);
+  const [requestError, setRequestError] = useState('');
+  const [response, setResponse] = useState<RequestTestResponse | null>(null);
+
+  useEffect(() => {
+    setParamValues({});
+    setHeaderValues({});
+    setResponse(null);
+    setRequestError('');
+    setBodyText(bodyMedia?.schema ? JSON.stringify(createExampleFromSchema(doc, bodyMedia.schema), null, 2) : '');
+    setCustomHeadersText(bodyMedia ? '{\n  "Content-Type": "application/json"\n}' : '{}');
+  }, [doc, endpoint.id, bodyMedia]);
+
+  useEffect(() => {
+    const nextBaseUrl = environmentBaseUrl.trim();
+    setBaseUrl((current) => {
+      const previousAutoBaseUrl = previousAutoBaseUrlRef.current;
+      previousAutoBaseUrlRef.current = nextBaseUrl;
+      if (!current || current === previousAutoBaseUrl) return nextBaseUrl;
+      return current;
+    });
+  }, [environmentBaseUrl]);
+
+  const previewUrl = useMemo(() => {
+    try {
+      return buildRequestUrl(baseUrl, endpoint.path, parameters, paramValues, apiKeyLocation === 'query' ? { [apiKeyName]: authValue } : {});
+    } catch {
+      return endpoint.path;
+    }
+  }, [apiKeyLocation, apiKeyName, authValue, baseUrl, endpoint.path, parameters, paramValues]);
+
+  function mockData() {
+    const nextParamValues: Record<string, string> = {};
+    const nextHeaderValues: Record<string, string> = {};
+
+    parameters.forEach((parameter, index) => {
+      const key = parameterKey(parameter, index);
+      const value = stringifyMockValue(createParameterMockValue(doc, parameter));
+      if (parameter.in === 'path' || parameter.in === 'query') {
+        nextParamValues[key] = value;
+      }
+      if (parameter.in === 'header') {
+        nextHeaderValues[key] = value;
+      }
+    });
+
+    setParamValues(nextParamValues);
+    setHeaderValues(nextHeaderValues);
+    if (bodyMedia?.schema && !['get', 'head'].includes(endpoint.method)) {
+      setBodyText(JSON.stringify(createMockFromSchema(doc, bodyMedia.schema), null, 2));
+      setCustomHeadersText(JSON.stringify({ ...safeParseHeaderJson(customHeadersText), 'Content-Type': bodyMedia.mediaType }, null, 2));
+    } else {
+      setBodyText('');
+    }
+    setResponse(null);
+    setRequestError('');
+  }
+  async function sendRequest() {
+    setSending(true);
+    setRequestError('');
+    setResponse(null);
+
+    try {
+      const customHeaders = parseHeaderJson(customHeadersText);
+      const headers = buildRequestHeaders({
+        customHeaders,
+        headerParams,
+        headerValues,
+        authType,
+        authValue,
+        apiKeyName,
+        apiKeyLocation,
+        basicUsername,
+        basicPassword,
+      });
+      const url = buildRequestUrl(baseUrl, endpoint.path, parameters, paramValues, apiKeyLocation === 'query' ? { [apiKeyName]: authValue } : {});
+      const requestBody = ['get', 'head'].includes(endpoint.method) ? undefined : bodyText.trim() || undefined;
+      const result = await sendTestRequest({
+        url,
+        method: endpoint.method.toUpperCase(),
+        headers,
+        body: requestBody,
+      });
+      setResponse(result);
+    } catch (err) {
+      setRequestError(err instanceof Error ? err.message : '请求失败');
+    } finally {
+      setSending(false);
+    }
+  }
+
+  return (
+    <div className="request-tester">
+      <div className="request-line">
+        <span className={`method method-${endpoint.method}`}>{endpoint.method.toUpperCase()}</span>
+        <label>
+          Base URL
+          <input value={baseUrl} onChange={(event) => setBaseUrl(event.target.value)} placeholder="https://api.example.com" />
+        </label>
+        <div className="request-actions">
+          <button className="primary-button" onClick={sendRequest} disabled={sending}>
+            <Send size={16} />
+            {sending ? '请求中' : '发送请求'}
+          </button>
+          <button className="secondary-button" onClick={mockData} disabled={sending}>
+            <Braces size={16} />
+            MOCK数据
+          </button>
+        </div>
+      </div>
+
+      <code className="request-preview">{previewUrl}</code>
+
+      <div className="tester-grid">
+        <section className="tester-panel">
+          <div className="tester-panel-title">
+            <KeyRound size={15} />
+            鉴权
+          </div>
+          <div className="tester-form-grid">
+            <label>
+              类型
+              <select value={authType} onChange={(event) => setAuthType(event.target.value as AuthType)}>
+                <option value="none">None</option>
+                <option value="bearer">Bearer Token</option>
+                <option value="jwt">JWT Token</option>
+                <option value="apiKey">API Key</option>
+                <option value="basic">Basic Auth</option>
+              </select>
+            </label>
+            {authType === 'apiKey' ? (
+              <>
+                <label>
+                  Key 名称
+                  <input value={apiKeyName} onChange={(event) => setApiKeyName(event.target.value)} placeholder="X-API-Key" />
+                </label>
+                <label>
+                  位置
+                  <select value={apiKeyLocation} onChange={(event) => setApiKeyLocation(event.target.value as ApiKeyLocation)}>
+                    <option value="header">Header</option>
+                    <option value="query">Query</option>
+                  </select>
+                </label>
+                <label>
+                  Value
+                  <input value={authValue} onChange={(event) => setAuthValue(event.target.value)} placeholder="api key value" />
+                </label>
+              </>
+            ) : authType === 'basic' ? (
+              <>
+                <label>
+                  Username
+                  <input value={basicUsername} onChange={(event) => setBasicUsername(event.target.value)} />
+                </label>
+                <label>
+                  Password
+                  <input value={basicPassword} onChange={(event) => setBasicPassword(event.target.value)} type="password" />
+                </label>
+              </>
+            ) : authType !== 'none' ? (
+              <label>
+                Token
+                <input value={authValue} onChange={(event) => setAuthValue(event.target.value)} placeholder="token" />
+              </label>
+            ) : null}
+          </div>
+        </section>
+
+        <section className="tester-panel">
+          <div className="tester-panel-title">参数</div>
+          <ParameterEditor title="Path" parameters={pathParams} values={paramValues} onChange={setParamValues} />
+          <ParameterEditor title="Query" parameters={queryParams} values={paramValues} onChange={setParamValues} />
+          <ParameterEditor title="Header" parameters={headerParams} values={headerValues} onChange={setHeaderValues} />
+        </section>
+      </div>
+
+      <div className="tester-grid">
+        <section className="tester-panel">
+          <div className="tester-panel-title">请求头 JSON</div>
+          <textarea value={customHeadersText} onChange={(event) => setCustomHeadersText(event.target.value)} spellCheck={false} />
+        </section>
+        <section className="tester-panel">
+          <div className="tester-panel-title">请求体 {bodyMedia ? `(${bodyMedia.mediaType})` : ''}</div>
+          <textarea
+            value={bodyText}
+            onChange={(event) => setBodyText(event.target.value)}
+            disabled={!bodyMedia || ['get', 'head'].includes(endpoint.method)}
+            spellCheck={false}
+            placeholder={bodyMedia ? 'JSON / raw body' : '该接口没有请求体'}
+          />
+        </section>
+      </div>
+
+      {requestError ? (
+        <div className="import-error">
+          <AlertCircle size={16} />
+          {requestError}
+        </div>
+      ) : null}
+
+      <section className="tester-panel response-panel">
+        <div className="tester-panel-title">响应</div>
+        {response ? (
+          <>
+            <div className="response-meta-line">
+              <span className={response.status >= 200 && response.status < 300 ? 'status-ok' : 'status-error'}>
+                {response.status} {response.statusText}
+              </span>
+              <span>{response.elapsedMs}ms</span>
+              <span>{response.url}</span>
+            </div>
+            <pre>{formatResponseBody(response.body)}</pre>
+          </>
+        ) : (
+          <p className="muted">发送请求后显示响应内容。</p>
+        )}
+      </section>
+    </div>
+  );
+}
+
+function ParameterEditor({
+  title,
+  parameters,
+  values,
+  onChange,
+}: {
+  title: string;
+  parameters: SwaggerParameter[];
+  values: Record<string, string>;
+  onChange: (value: Record<string, string>) => void;
+}) {
+  if (!parameters.length) return null;
+
+  return (
+    <div className="param-editor">
+      <h4>{title}</h4>
+      {parameters.map((parameter, index) => {
+        const key = parameterKey(parameter, index);
+        return (
+          <label key={key}>
+            <span>
+              {parameter.name}
+              {parameter.required ? <b>*</b> : null}
+            </span>
+            <input
+              value={values[key] ?? ''}
+              onChange={(event) => onChange({ ...values, [key]: event.target.value })}
+              placeholder={parameter.description || parameter.schema?.description || ''}
+            />
+          </label>
+        );
+      })}
+    </div>
+  );
+}
+
+function pickRequestBodyMedia(endpoint: Endpoint) {
+  const content = endpoint.operation.requestBody?.content ?? {};
+  const entries = Object.entries(content);
+  const jsonEntry = entries.find(([mediaType]) => mediaType.includes('json'));
+  const entry = jsonEntry ?? entries[0];
+  const bodyParameter = endpoint.operation.parameters?.find((parameter) => parameter.in === 'body');
+  if (!entry && bodyParameter?.schema) {
+    return {
+      mediaType: endpoint.operation.consumes?.find((mediaType) => mediaType.includes('json')) ?? endpoint.operation.consumes?.[0] ?? 'application/json',
+      schema: bodyParameter.schema,
+    };
+  }
+  if (!entry) return undefined;
+  return { mediaType: entry[0], schema: entry[1].schema };
+}
+
+function createExampleFromSchema(doc: SwaggerDocument, schema?: SwaggerSchema, depth = 0, seen = new Set<SwaggerSchema>()): unknown {
+  if (!schema || depth > 8) return {};
+  const resolved = resolveSchema(doc, schema) ?? schema;
+  if (seen.has(resolved)) return {};
+  seen.add(resolved);
+
+  if (resolved.default !== undefined) return resolved.default;
+  if (resolved.enum?.length) return resolved.enum[0];
+  if (resolved.type === 'array') return [createExampleFromSchema(doc, resolved.items, depth + 1, seen)];
+  if (resolved.type === 'integer' || resolved.type === 'number') return 0;
+  if (resolved.type === 'boolean') return false;
+  if (resolved.type === 'string') return '';
+
+  const properties = resolved.properties ?? {};
+  return Object.fromEntries(
+    Object.entries(properties).map(([name, property]) => [name, createExampleFromSchema(doc, property, depth + 1, new Set(seen))]),
+  );
+}
+
+function createParameterMockValue(doc: SwaggerDocument, parameter: SwaggerParameter) {
+  if (parameter.default !== undefined) return parameter.default;
+  if (parameter.enum?.length) return parameter.enum[0];
+  const schema = schemaFromParameter(parameter);
+  return createMockFromSchema(doc, schema, parameter.name);
+}
+
+function createMockFromSchema(
+  doc: SwaggerDocument,
+  schema?: SwaggerSchema,
+  fieldName = '',
+  depth = 0,
+  seen = new Set<SwaggerSchema>(),
+): unknown {
+  if (!schema || depth > 8) return mockValueByName(fieldName) ?? 'mock-value';
+  const resolved = resolveSchema(doc, schema) ?? schema;
+  if (seen.has(resolved)) return {};
+  const nextSeen = new Set(seen);
+  nextSeen.add(resolved);
+
+  if (resolved.default !== undefined) return resolved.default;
+  if (schema.default !== undefined) return schema.default;
+  if (resolved.enum?.length) return resolved.enum[0];
+  if (schema.enum?.length) return schema.enum[0];
+
+  const semanticValue = mockValueByName(fieldName, resolved.format || schema.format);
+  const normalizedType = resolved.type || schema.type || (resolved.properties ? 'object' : '');
+  if (semanticValue !== undefined && (!normalizedType || normalizedType === 'string' || normalizedType === 'integer' || normalizedType === 'number')) {
+    return semanticValue;
+  }
+
+  if (resolved.oneOf?.length) return createMockFromSchema(doc, resolved.oneOf[0], fieldName, depth + 1, nextSeen);
+  if (resolved.anyOf?.length) return createMockFromSchema(doc, resolved.anyOf[0], fieldName, depth + 1, nextSeen);
+  if (normalizedType === 'array') return [createMockFromSchema(doc, resolved.items, fieldName, depth + 1, nextSeen)];
+  if (normalizedType === 'integer' || normalizedType === 'number') return mockNumberByName(fieldName);
+  if (normalizedType === 'boolean') return true;
+  if (normalizedType === 'string') return semanticValue ?? 'mock-value';
+
+  const properties = resolved.properties ?? {};
+  if (Object.keys(properties).length) {
+    return Object.fromEntries(
+      Object.entries(properties).map(([name, property]) => [name, createMockFromSchema(doc, property, name, depth + 1, nextSeen)]),
+    );
+  }
+
+  if (resolved.additionalProperties && typeof resolved.additionalProperties === 'object') {
+    return { key: createMockFromSchema(doc, resolved.additionalProperties, 'value', depth + 1, nextSeen) };
+  }
+
+  return semanticValue ?? {};
+}
+
+function schemaFromParameter(parameter: SwaggerParameter): SwaggerSchema | undefined {
+  if (parameter.schema) return parameter.schema;
+  if (!parameter.type && !parameter.format && !parameter.items && !parameter.enum?.length && parameter.default === undefined) return undefined;
+  return {
+    type: parameter.type,
+    format: parameter.format,
+    items: parameter.items,
+    enum: parameter.enum,
+    default: parameter.default,
+    description: parameter.description,
+  };
+}
+
+function mockValueByName(fieldName: string, format = '') {
+  const normalized = fieldName.toLowerCase().replace(/[^a-z0-9]/g, '');
+  if (format === 'date-time') return new Date().toISOString();
+  if (format === 'date') return new Date().toISOString().slice(0, 10);
+  if (format === 'email' || normalized.includes('email')) return 'mock@example.com';
+  if (format === 'uuid' || normalized.includes('uuid')) return '00000000-0000-4000-8000-000000000000';
+  if (normalized === 'id' || normalized.endsWith('id')) return 1;
+  if (normalized === 'page' || normalized === 'pagenum' || normalized === 'pageindex') return 1;
+  if (normalized === 'pagesize' || normalized === 'limit' || normalized === 'size') return 10;
+  if (normalized.includes('phone') || normalized.includes('mobile')) return '13800000000';
+  if (normalized.includes('name') || normalized.includes('title') || normalized.includes('keyword')) return 'mock-name';
+  if (normalized.includes('url')) return 'https://example.com';
+  if (normalized.includes('date')) return new Date().toISOString().slice(0, 10);
+  if (normalized.includes('time')) return new Date().toISOString();
+  return undefined;
+}
+
+function mockNumberByName(fieldName: string) {
+  const value = mockValueByName(fieldName);
+  return typeof value === 'number' ? value : 1;
+}
+
+function stringifyMockValue(value: unknown) {
+  if (value === undefined || value === null) return '';
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  return JSON.stringify(value);
+}
+
+function parameterKey(parameter: SwaggerParameter, index: number) {
+  return `${parameter.in}-${parameter.name}-${index}`;
+}
+
+function buildRequestUrl(
+  baseUrl: string,
+  path: string,
+  parameters: SwaggerParameter[],
+  values: Record<string, string>,
+  extraQuery: Record<string, string>,
+) {
+  if (!baseUrl.trim() && !/^https?:\/\//i.test(path)) {
+    throw new Error('请输入 Base URL，例如 https://api.example.com');
+  }
+
+  const base = baseUrl.trim() || undefined;
+  let requestPath = path;
+  parameters.forEach((parameter, index) => {
+    if (parameter.in !== 'path') return;
+    const value = values[parameterKey(parameter, index)] ?? '';
+    requestPath = requestPath.replace(new RegExp(`\\{${escapeRegExp(parameter.name)}\\}`, 'g'), encodeURIComponent(value));
+  });
+
+  const url = new URL(requestPath, base);
+  parameters.forEach((parameter, index) => {
+    if (parameter.in !== 'query') return;
+    const value = values[parameterKey(parameter, index)] ?? '';
+    if (value) url.searchParams.append(parameter.name, value);
+  });
+  Object.entries(extraQuery).forEach(([key, value]) => {
+    if (key.trim() && value.trim()) url.searchParams.set(key.trim(), value.trim());
+  });
+
+  return url.toString();
+}
+
+function buildRequestHeaders({
+  customHeaders,
+  headerParams,
+  headerValues,
+  authType,
+  authValue,
+  apiKeyName,
+  apiKeyLocation,
+  basicUsername,
+  basicPassword,
+}: {
+  customHeaders: Record<string, string>;
+  headerParams: SwaggerParameter[];
+  headerValues: Record<string, string>;
+  authType: AuthType;
+  authValue: string;
+  apiKeyName: string;
+  apiKeyLocation: ApiKeyLocation;
+  basicUsername: string;
+  basicPassword: string;
+}) {
+  const headers: Record<string, string> = { ...customHeaders };
+  headerParams.forEach((parameter, index) => {
+    const value = headerValues[parameterKey(parameter, index)];
+    if (value) headers[parameter.name] = value;
+  });
+
+  if ((authType === 'bearer' || authType === 'jwt') && authValue.trim()) {
+    headers.Authorization = `Bearer ${authValue.trim()}`;
+  }
+  if (authType === 'apiKey' && apiKeyLocation === 'header' && apiKeyName.trim() && authValue.trim()) {
+    headers[apiKeyName.trim()] = authValue.trim();
+  }
+  if (authType === 'basic' && (basicUsername || basicPassword)) {
+    headers.Authorization = `Basic ${btoa(`${basicUsername}:${basicPassword}`)}`;
+  }
+
+  return headers;
+}
+
+function parseHeaderJson(value: string) {
+  if (!value.trim()) return {};
+  const parsed = JSON.parse(value) as Record<string, unknown>;
+  return Object.fromEntries(Object.entries(parsed).map(([key, item]) => [key, String(item)]));
+}
+
+function safeParseHeaderJson(value: string) {
+  try {
+    return parseHeaderJson(value);
+  } catch {
+    return {};
+  }
+}
+
+async function sendTestRequest(payload: { url: string; method: string; headers: Record<string, string>; body?: string }) {
+  const response = await fetch('/api/request/send', {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify(payload),
+  });
+  const data = await response.json();
+  if (!response.ok) throw new Error(data.error || '请求失败');
+  return data as RequestTestResponse;
+}
+
+function formatResponseBody(value: string) {
+  try {
+    return JSON.stringify(JSON.parse(value), null, 2);
+  } catch {
+    return value;
+  }
+}
+
+function copyTextWithSelection(value: string) {
+  const textarea = document.createElement('textarea');
+  textarea.value = value;
+  textarea.setAttribute('readonly', 'true');
+  textarea.style.position = 'fixed';
+  textarea.style.left = '-9999px';
+  textarea.style.top = '0';
+  document.body.appendChild(textarea);
+  textarea.focus();
+  textarea.select();
+
+  try {
+    return document.execCommand('copy');
+  } finally {
+    document.body.removeChild(textarea);
+  }
+}
+
+function escapeRegExp(value: string) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function Section({ title, count, children }: { title: string; count: number; children: React.ReactNode }) {
+  return (
+    <section className="detail-section">
+      <div className="section-title">
+        <h3>{title}</h3>
+        <span>{count}</span>
+      </div>
+      {children}
+    </section>
+  );
+}
+
+function FieldTable({ rows, empty }: { rows: FieldRow[]; empty: string }) {
+  if (!rows.length) return <p className="muted">{empty}</p>;
+
+  return (
+    <div className="table-wrap">
+      <table>
+        <thead>
+          <tr>
+            <th>字段</th>
+            <th>位置</th>
+            <th>必填</th>
+            <th>类型</th>
+            <th>说明</th>
+            <th>默认值</th>
+            <th>枚举</th>
+          </tr>
+        </thead>
+        <tbody>
+          {rows.map((row, index) => (
+            <tr key={`${row.location}-${row.path}-${row.depth}-${index}`}>
+              <td>
+                <code style={{ paddingLeft: row.depth * 16 }}>{row.name}</code>
+              </td>
+              <td>{row.location || '-'}</td>
+              <td>{row.required ? '是' : '否'}</td>
+              <td>{row.type}</td>
+              <td>{row.description || '-'}</td>
+              <td>{row.defaultValue || '-'}</td>
+              <td>{row.enumValue || '-'}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}
+
+function formatDate(value: string) {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return value;
+  return date.toLocaleString('zh-CN', {
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+  });
+}