apiskill 0.1.0

package/vite.config.ts

@@ -0,0 +1,1380 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { basename, dirname, resolve } from 'node:path';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { parse as parseYaml } from 'yaml';
+import {
+  applyManualApiOperationConfig,
+  createManualApiDocument,
+  deleteManualApiOperation,
+  normalizeManualApiOperationConfig,
+  openApiStats,
+} from './src/manualApiConfig';
+import { startMockServer } from './scripts/lib/mock-server.mjs';
+
+const appRootDir = process.env.APISKILL_ROOT || process.cwd();
+const cacheDir = process.env.APISKILL_CACHE_DIR || resolve(appRootDir, 'cache');
+const versionsDir = resolve(cacheDir, 'versions');
+const latestMetaPath = resolve(cacheDir, 'latest-import.json');
+const legacyCachePath = resolve(cacheDir, 'openapi-cache.json');
+const legacyCacheMetaPath = resolve(cacheDir, 'import-meta.json');
+
+type ImportAuth = {
+  type: 'none' | 'basic';
+  username?: string;
+  password?: string;
+};
+
+type SwaggerResource = {
+  name?: string;
+  location?: string;
+  url?: string;
+  swaggerVersion?: string;
+};
+
+export default defineConfig({
+  plugins: [openapiImportPlugin(), react()],
+  server: {
+    port: 8888,
+    strictPort: false, // 如果端口被占用，会自动尝试下一个可用端口
+  },
+});
+
+function openapiImportPlugin() {
+  let mockServerState: Awaited<ReturnType<typeof startMockServer>> | undefined;
+
+  async function stopMockServer() {
+    if (!mockServerState) return;
+    const current = mockServerState;
+    mockServerState = undefined;
+    await new Promise<void>((resolveStop) => current.server.close(() => resolveStop()));
+  }
+
+  return {
+    name: 'apiskill-openapi-importer',
+    configureServer(server) {
+      server.httpServer?.once('close', () => {
+        void stopMockServer();
+      });
+
+      server.middlewares.use('/api/openapi/cache', async (req, res) => {
+        if (req.method !== 'GET') {
+          sendJson(res, 405, { error: 'Method Not Allowed' });
+          return;
+        }
+
+        try {
+          const versionId = new URL(req.url || '', 'http://localhost').searchParams.get('versionId') || undefined;
+          const payload = await readCachedDocument(versionId);
+          sendJson(res, 200, payload);
+        } catch (error) {
+          const message = error instanceof Error ? error.message : 'Read cache failed';
+          sendJson(res, message.includes('No cached') ? 404 : 500, { error: message });
+        }
+      });
+
+      server.middlewares.use('/api/openapi/versions', async (req, res) => {
+        if (req.method !== 'GET') {
+          sendJson(res, 405, { error: 'Method Not Allowed' });
+          return;
+        }
+
+        try {
+          sendJson(res, 200, { versions: await listCachedVersions() });
+        } catch (error) {
+          sendJson(res, 500, { error: error instanceof Error ? error.message : 'Read versions failed' });
+        }
+      });
+
+      server.middlewares.use('/api/openapi/version-select', async (req, res) => {
+        if (req.method !== 'POST') {
+          sendJson(res, 405, { error: 'Method Not Allowed' });
+          return;
+        }
+
+        try {
+          const body = (await readJsonBody(req)) as { versionId?: string };
+          const versionId = requiredText(body.versionId, '请选择要切换的文档版本');
+          const payload = await readCachedDocument(versionId);
+          await writeFile(latestMetaPath, JSON.stringify(payload.meta, null, 2));
+          sendJson(res, 200, { ...payload, versions: await listCachedVersions() });
+        } catch (error) {
+          sendJson(res, 400, { error: error instanceof Error ? error.message : 'Select version failed' });
+        }
+      });
+
+      server.middlewares.use('/api/openapi/version-meta', async (req, res) => {
+        if (req.method !== 'POST') {
+          sendJson(res, 405, { error: 'Method Not Allowed' });
+          return;
+        }
+
+        try {
+          const body = (await readJsonBody(req)) as { versionId?: string; environmentName?: unknown; environmentBaseUrl?: unknown };
+          const versionId = requiredText(body.versionId, '请选择要更新的文档版本');
+          assertSafeVersionId(versionId);
+          const metaPath = resolve(versionsDir, `${versionId}.meta.json`);
+          if (!existsSync(metaPath)) throw new Error('缓存版本不存在');
+
+          const currentMeta = JSON.parse(await readFile(metaPath, 'utf8'));
+          const meta = {
+            ...currentMeta,
+            environmentName: optionalText(body.environmentName).slice(0, 80),
+            environmentBaseUrl: normalizeOptionalBaseUrl(body.environmentBaseUrl),
+            environmentUpdatedAt: new Date().toISOString(),
+          };
+
+          await writeFile(metaPath, JSON.stringify(meta, null, 2));
+          const latestMeta = await readLatestMeta();
+          if (latestMeta?.versionId === versionId) {
+            await writeFile(latestMetaPath, JSON.stringify(meta, null, 2));
+          }
+          sendJson(res, 200, { meta, versions: await listCachedVersions() });
+        } catch (error) {
+          sendJson(res, 400, { error: error instanceof Error ? error.message : 'Update version meta failed' });
+        }
+      });
+
+      server.middlewares.use('/api/openapi/version-delete', async (req, res) => {
+        if (req.method !== 'POST') {
+          sendJson(res, 405, { error: 'Method Not Allowed' });
+          return;
+        }
+
+        try {
+          const body = (await readJsonBody(req)) as { versionId?: string };
+          const versionId = requiredText(body.versionId, '请选择要删除的文档版本');
+          assertSafeVersionId(versionId);
+          const metaPath = resolve(versionsDir, `${versionId}.meta.json`);
+          const versionPath = resolve(versionsDir, `${versionId}.json`);
+          if (!existsSync(metaPath) && !existsSync(versionPath)) throw new Error('缓存版本不存在');
+
+          await rm(metaPath, { force: true });
+          await rm(versionPath, { force: true });
+
+          const latestMeta = await readLatestMeta();
+          const versions = await listCachedVersions();
+          let nextVersionId = '';
+          if (latestMeta?.versionId === versionId || !latestMeta?.versionId) {
+            const nextLatest = versions[0];
+            if (nextLatest) {
+              await writeFile(latestMetaPath, JSON.stringify(nextLatest, null, 2));
+              nextVersionId = nextLatest.versionId || '';
+            } else {
+              await rm(latestMetaPath, { force: true });
+            }
+          } else {
+            nextVersionId = latestMeta.versionId || versions[0]?.versionId || '';
+          }
+
+          sendJson(res, 200, { versions, nextVersionId });
+        } catch (error) {
+          sendJson(res, 400, { error: error instanceof Error ? error.message : 'Delete version failed' });
+        }
+      });
+
+      server.middlewares.use('/api/openapi/version-export', async (req, res) => {
+        if (req.method !== 'GET') {
+          sendJson(res, 405, { error: 'Method Not Allowed' });
+          return;
+        }
+
+        try {
+          const versionId = new URL(req.url || '', 'http://localhost').searchParams.get('versionId') || '';
+          const payload = await readCachedDocument(requiredText(versionId, '请选择要导出的文档版本'));
+          const safeVersionId = payload.meta?.versionId || versionId;
+          res.statusCode = 200;
+          res.setHeader('content-type', 'application/json; charset=utf-8');
+          res.setHeader('content-disposition', `attachment; filename="${safeVersionId}.json"`);
+          res.end(JSON.stringify(payload.document, null, 2));
+        } catch (error) {
+          sendJson(res, 400, { error: error instanceof Error ? error.message : 'Export version failed' });
+        }
+      });
+
+      server.middlewares.use('/api/openapi/auth-check', async (req, res) => {
+        if (req.method !== 'POST') {
+          sendJson(res, 405, { error: 'Method Not Allowed' });
+          return;
+        }
+
+        try {
+          const body = (await readJsonBody(req)) as { url?: string; mode?: 'file' | 'crawl' | 'curl' };
+          const sourceUrl = normalizeUrl(body.url);
+          const mode = body.mode === 'crawl' ? 'crawl' : 'file';
+          const result = await checkDocumentAuth(sourceUrl, mode);
+          sendJson(res, 200, result);
+        } catch (error) {
+          sendJson(res, 400, { error: error instanceof Error ? error.message : 'Auth check failed' });
+        }
+      });
+
+      server.middlewares.use('/api/mock/status', async (req, res) => {
+        if (req.method !== 'GET') {
+          sendJson(res, 405, { error: 'Method Not Allowed' });
+          return;
+        }
+
+        sendJson(res, 200, {
+          running: Boolean(mockServerState),
+          mock: mockServerState ? mockInfo(mockServerState) : undefined,
+        });
+      });
+
+      server.middlewares.use('/api/mock/start', async (req, res) => {
+        if (req.method !== 'POST') {
+          sendJson(res, 405, { error: 'Method Not Allowed' });
+          return;
+        }
+
+        try {
+          const body = (await readJsonBody(req)) as { versionId?: string; port?: unknown; host?: unknown };
+          const payload = await readCachedDocument(optionalText(body.versionId) || undefined);
+          await stopMockServer();
+          mockServerState = await startMockServer({
+            document: payload.document,
+            meta: payload.meta,
+            host: optionalText(body.host) || '127.0.0.1',
+            port: Number(body.port) || 4010,
+          });
+          sendJson(res, 200, { running: true, mock: mockInfo(mockServerState) });
+        } catch (error) {
+          sendJson(res, 400, { error: error instanceof Error ? error.message : 'Start mock server failed' });
+        }
+      });
+
+      server.middlewares.use('/api/mock/stop', async (req, res) => {
+        if (req.method !== 'POST') {
+          sendJson(res, 405, { error: 'Method Not Allowed' });
+          return;
+        }
+
+        await stopMockServer();
+        sendJson(res, 200, { running: false });
+      });
+
+      server.middlewares.use('/api/openapi/import', async (req, res) => {
+        if (req.method !== 'POST') {
+          sendJson(res, 405, { error: 'Method Not Allowed' });
+          return;
+        }
+
+        try {
+          const body = (await readJsonBody(req)) as {
+            url?: string;
+            mode?: 'file' | 'crawl' | 'curl' | 'upload';
+            auth?: unknown;
+            content?: unknown;
+            versionId?: string;
+          };
+          const mode = body.mode === 'crawl' ? 'crawl' : body.mode === 'curl' ? 'curl' : body.mode === 'upload' ? 'upload' : 'file';
+          const sourceInput = requiredText(
+            body.url,
+            mode === 'curl' ? '请输入 CURL 命令' : mode === 'upload' ? '请选择 JSON 或 YAML 文件' : '请输入文档地址',
+          );
+          const existing = body.versionId ? await readCachedDocument(body.versionId) : undefined;
+          const sourceUrl = mode === 'curl' || mode === 'upload' ? sourceInput : normalizeUrl(sourceInput);
+          const auth = normalizeImportAuth(body.auth);
+          const result =
+            mode === 'crawl'
+              ? await crawlOpenApi(sourceUrl, auth)
+              : mode === 'curl'
+                ? await fetchOpenApiFromCurl(sourceInput)
+                : mode === 'upload'
+                  ? parseOpenApiFromUpload(requiredText(body.content, '上传文件内容为空'), sourceInput)
+                  : await fetchOpenApiJson(sourceUrl, auth);
+          const savedAt = new Date();
+          const versionId = existing?.meta?.versionId || `${formatVersionDate(savedAt)}-${mode}-${slugify(resultSourceName(result.url, sourceInput))}`;
+          const versionPath = existing?.meta?.savedPath || resolve(versionsDir, `${versionId}.json`);
+          const versionMetaPath = resolve(versionsDir, `${versionId}.meta.json`);
+          const meta = {
+            ...(existing?.meta ?? {}),
+            versionId,
+            mode,
+            inputUrl: sourceInput,
+            resolvedUrl: result.url,
+            title: result.document.info?.title || '',
+            version: result.document.info?.version || '',
+            paths: Object.keys(result.document.paths ?? {}).length,
+            schemas: Object.keys(result.document.components?.schemas ?? result.document.definitions ?? {}).length,
+            savedFile: basename(versionPath),
+            savedPath: versionPath,
+            savedAt: savedAt.toISOString(),
+          };
+
+          await mkdir(dirname(versionPath), { recursive: true });
+          await writeFile(versionPath, JSON.stringify(result.document, null, 2));
+          await writeFile(versionMetaPath, JSON.stringify(meta, null, 2));
+          await writeFile(latestMetaPath, JSON.stringify(meta, null, 2));
+          sendJson(res, 200, { document: result.document, meta, versions: await listCachedVersions() });
+        } catch (error) {
+          sendJson(res, 400, { error: error instanceof Error ? error.message : 'Import failed' });
+        }
+      });
+
+      server.middlewares.use('/api/openapi/document', async (req, res) => {
+        if (req.method !== 'POST') {
+          sendJson(res, 405, { error: 'Method Not Allowed' });
+          return;
+        }
+
+        try {
+          const body = (await readJsonBody(req)) as {
+            title?: unknown;
+            version?: unknown;
+            description?: unknown;
+            environmentName?: unknown;
+            environmentBaseUrl?: unknown;
+            versionId?: string;
+          };
+          const title = requiredText(body.title, '请输入文档名称');
+          const existing = body.versionId ? await readCachedDocument(body.versionId) : undefined;
+          const document = createManualApiDocument(title);
+          document.info.version = optionalText(body.version) || '1.0.0';
+          document.info.description = optionalText(body.description) || 'Created from API Skill blank document.';
+          const savedAt = new Date();
+          const versionId = existing?.meta?.versionId || `${formatVersionDate(savedAt)}-document-${slugify(title)}`;
+          const versionPath = existing?.meta?.savedPath || resolve(versionsDir, `${versionId}.json`);
+          const versionMetaPath = resolve(versionsDir, `${versionId}.meta.json`);
+          const stats = openApiStats(document);
+          const meta = {
+            ...(existing?.meta ?? {}),
+            versionId,
+            mode: 'document',
+            inputUrl: 'manual-document',
+            resolvedUrl: 'manual-document',
+            title: document.info?.title || '',
+            version: document.info?.version || '',
+            paths: stats.paths,
+            schemas: stats.schemas,
+            environmentName:
+              body.environmentName === undefined ? existing?.meta?.environmentName || '' : optionalText(body.environmentName).slice(0, 80),
+            environmentBaseUrl:
+              body.environmentBaseUrl === undefined ? existing?.meta?.environmentBaseUrl || '' : normalizeOptionalBaseUrl(body.environmentBaseUrl),
+            savedFile: basename(versionPath),
+            savedPath: versionPath,
+            savedAt: savedAt.toISOString(),
+          };
+
+          await mkdir(dirname(versionPath), { recursive: true });
+          await writeFile(versionPath, JSON.stringify(document, null, 2));
+          await writeFile(versionMetaPath, JSON.stringify(meta, null, 2));
+          await writeFile(latestMetaPath, JSON.stringify(meta, null, 2));
+          sendJson(res, 200, { document, meta, versions: await listCachedVersions() });
+        } catch (error) {
+          sendJson(res, 400, { error: error instanceof Error ? error.message : 'Create document failed' });
+        }
+      });
+
+      server.middlewares.use('/api/openapi/custom-operation', async (req, res, next) => {
+        if (new URL(req.url || '/', 'http://localhost').pathname !== '/') {
+          next();
+          return;
+        }
+
+        if (req.method !== 'POST') {
+          sendJson(res, 405, { error: 'Method Not Allowed' });
+          return;
+        }
+
+        try {
+          const body = (await readJsonBody(req)) as { versionId?: string; config?: unknown; replaceTarget?: { method?: string; path?: string } };
+          const config = normalizeManualApiOperationConfig(body.config);
+          const existing = body.versionId ? await readCachedDocument(body.versionId) : undefined;
+          let baseDocument = existing?.document ?? createManualApiDocument();
+          if (body.replaceTarget?.method && body.replaceTarget?.path) {
+            const method = body.replaceTarget.method.toLowerCase();
+            if (['get', 'post', 'put', 'delete', 'patch', 'options', 'head'].includes(method)) {
+              baseDocument = deleteManualApiOperation(baseDocument, method as 'get' | 'post' | 'put' | 'delete' | 'patch' | 'options' | 'head', body.replaceTarget.path);
+            }
+          }
+          const document = applyManualApiOperationConfig(baseDocument, config);
+          const savedAt = new Date();
+          const versionId = existing?.meta?.versionId || `${formatVersionDate(savedAt)}-manual-${slugify(config.operationId || config.summary || config.path)}`;
+          const versionPath = existing?.meta?.savedPath || resolve(versionsDir, `${versionId}.json`);
+          const versionMetaPath = resolve(versionsDir, `${versionId}.meta.json`);
+          const stats = openApiStats(document);
+          const meta = {
+            ...(existing?.meta ?? {}),
+            versionId,
+            mode: existing?.meta?.mode || 'manual',
+            inputUrl: existing?.meta?.inputUrl || 'manual-api-config',
+            resolvedUrl: existing?.meta?.resolvedUrl || 'manual-api-config',
+            title: document.info?.title || 'Manual API Config',
+            version: document.info?.version || 'manual',
+            paths: stats.paths,
+            schemas: stats.schemas,
+            savedFile: basename(versionPath),
+            savedPath: versionPath,
+            savedAt: savedAt.toISOString(),
+          };
+
+          await mkdir(dirname(versionPath), { recursive: true });
+          await writeFile(versionPath, JSON.stringify(document, null, 2));
+          await writeFile(versionMetaPath, JSON.stringify(meta, null, 2));
+          await writeFile(latestMetaPath, JSON.stringify(meta, null, 2));
+          sendJson(res, 200, { document, meta });
+        } catch (error) {
+          sendJson(res, 400, { error: error instanceof Error ? error.message : 'Save custom operation failed' });
+        }
+      });
+
+      server.middlewares.use('/api/openapi/operation-links', async (req, res) => {
+        if (req.method !== 'POST') {
+          sendJson(res, 405, { error: 'Method Not Allowed' });
+          return;
+        }
+
+        try {
+          const body = (await readJsonBody(req)) as { versionId?: string; method?: string; path?: string; links?: unknown };
+          const versionId = requiredText(body.versionId, '请选择要更新的文档版本');
+          const method = requiredText(body.method, '请选择请求方法').toLowerCase();
+          if (!['get', 'post', 'put', 'delete', 'patch', 'options', 'head'].includes(method)) {
+            throw new Error('请求方法无效');
+          }
+          const path = requiredText(body.path, '接口路径不能为空');
+          const existing = await readCachedDocument(versionId);
+          const document = JSON.parse(JSON.stringify(existing.document));
+          const operation = document.paths?.[path]?.[method];
+          if (!operation) throw new Error('接口不存在，无法保存关联配置');
+
+          operation['x-apiskill-links'] = normalizeOperationLinks(body.links);
+
+          const savedAt = new Date();
+          const versionPath = existing.meta?.savedPath || resolve(versionsDir, `${versionId}.json`);
+          const versionMetaPath = resolve(versionsDir, `${versionId}.meta.json`);
+          const stats = openApiStats(document);
+          const meta = {
+            ...(existing.meta ?? {}),
+            versionId,
+            title: document.info?.title || existing.meta?.title || '',
+            version: document.info?.version || existing.meta?.version || '',
+            paths: stats.paths,
+            schemas: stats.schemas,
+            savedFile: basename(versionPath),
+            savedPath: versionPath,
+            savedAt: savedAt.toISOString(),
+          };
+
+          await mkdir(dirname(versionPath), { recursive: true });
+          await writeFile(versionPath, JSON.stringify(document, null, 2));
+          await writeFile(versionMetaPath, JSON.stringify(meta, null, 2));
+          await writeFile(latestMetaPath, JSON.stringify(meta, null, 2));
+          sendJson(res, 200, { document, meta, versions: await listCachedVersions() });
+        } catch (error) {
+          sendJson(res, 400, { error: error instanceof Error ? error.message : 'Save operation links failed' });
+        }
+      });
+
+      server.middlewares.use('/api/openapi/custom-operation/delete', async (req, res) => {
+        if (req.method !== 'POST') {
+          sendJson(res, 405, { error: 'Method Not Allowed' });
+          return;
+        }
+
+        try {
+          const body = (await readJsonBody(req)) as { versionId?: string; method?: string; path?: string };
+          const versionId = requiredText(body.versionId, '请选择要修改的本地版本');
+          const method = requiredText(body.method, '请选择请求方法').toLowerCase();
+          if (!['get', 'post', 'put', 'delete', 'patch', 'options', 'head'].includes(method)) {
+            throw new Error('请求方法无效');
+          }
+          const path = requiredText(body.path, '接口路径不能为空');
+          const existing = await readCachedDocument(versionId);
+          const document = deleteManualApiOperation(existing.document, method as 'get' | 'post' | 'put' | 'delete' | 'patch' | 'options' | 'head', path);
+          const savedAt = new Date();
+          const versionPath = existing.meta?.savedPath || resolve(versionsDir, `${versionId}.json`);
+          const versionMetaPath = resolve(versionsDir, `${versionId}.meta.json`);
+          const stats = openApiStats(document);
+          const meta = {
+            ...(existing.meta ?? {}),
+            versionId,
+            title: document.info?.title || existing.meta?.title || '',
+            version: document.info?.version || existing.meta?.version || '',
+            paths: stats.paths,
+            schemas: stats.schemas,
+            savedFile: basename(versionPath),
+            savedPath: versionPath,
+            savedAt: savedAt.toISOString(),
+          };
+
+          await mkdir(dirname(versionPath), { recursive: true });
+          await writeFile(versionPath, JSON.stringify(document, null, 2));
+          await writeFile(versionMetaPath, JSON.stringify(meta, null, 2));
+          await writeFile(latestMetaPath, JSON.stringify(meta, null, 2));
+          sendJson(res, 200, { document, meta });
+        } catch (error) {
+          sendJson(res, 400, { error: error instanceof Error ? error.message : 'Delete custom operation failed' });
+        }
+      });
+
+      server.middlewares.use('/api/request/send', async (req, res) => {
+        if (req.method !== 'POST') {
+          sendJson(res, 405, { error: 'Method Not Allowed' });
+          return;
+        }
+
+        try {
+          const body = (await readJsonBody(req)) as {
+            url?: string;
+            method?: string;
+            headers?: Record<string, string>;
+            body?: string;
+          };
+          const result = await sendApiRequest(body);
+          sendJson(res, 200, result);
+        } catch (error) {
+          sendJson(res, 400, { error: error instanceof Error ? error.message : 'Request failed' });
+        }
+      });
+    },
+  };
+}
+
+async function readCachedDocument(versionId?: string) {
+  if (versionId) {
+    assertSafeVersionId(versionId);
+    const metaPath = resolve(versionsDir, `${versionId}.meta.json`);
+    if (!existsSync(metaPath)) throw new Error('No cached OpenAPI document');
+    const meta = JSON.parse(await readFile(metaPath, 'utf8'));
+    const documentPath = typeof meta.savedPath === 'string' ? meta.savedPath : resolve(versionsDir, `${versionId}.json`);
+    const documentText = await readFile(documentPath, 'utf8');
+    return {
+      document: JSON.parse(documentText),
+      meta,
+    };
+  }
+
+  if (!existsSync(latestMetaPath) && !existsSync(legacyCachePath)) {
+    throw new Error('No cached OpenAPI document');
+  }
+
+  const meta = existsSync(latestMetaPath)
+    ? JSON.parse(await readFile(latestMetaPath, 'utf8'))
+    : existsSync(legacyCacheMetaPath)
+      ? JSON.parse(await readFile(legacyCacheMetaPath, 'utf8'))
+      : {};
+  const documentPath = typeof meta.savedPath === 'string' ? meta.savedPath : legacyCachePath;
+  const documentText = await readFile(documentPath, 'utf8');
+  return {
+    document: JSON.parse(documentText),
+    meta,
+  };
+}
+
+async function listCachedVersions() {
+  if (!existsSync(versionsDir)) return [];
+  const files = await readdir(versionsDir);
+  const metas = await Promise.all(
+    files
+      .filter((file) => file.endsWith('.meta.json'))
+      .map(async (file) => {
+        try {
+          return JSON.parse(await readFile(resolve(versionsDir, file), 'utf8'));
+        } catch {
+          return undefined;
+        }
+      }),
+  );
+  return metas.filter(Boolean).sort((a, b) => String(b.savedAt || '').localeCompare(String(a.savedAt || '')));
+}
+
+async function readLatestMeta() {
+  if (!existsSync(latestMetaPath)) return undefined;
+  try {
+    return JSON.parse(await readFile(latestMetaPath, 'utf8'));
+  } catch {
+    return undefined;
+  }
+}
+
+function assertSafeVersionId(versionId: string) {
+  if (!/^[a-zA-Z0-9_.-]+$/.test(versionId)) throw new Error('Invalid version id');
+}
+
+async function checkDocumentAuth(sourceUrl: string, mode: 'file' | 'crawl') {
+  const direct = await inspectDocumentUrl(sourceUrl, {
+    accept: mode === 'crawl' ? 'text/html,application/xhtml+xml,application/json,*/*' : 'application/json,text/plain,*/*',
+    userAgent: 'apiskill-openapi-auth-check/1.0',
+    timeoutMs: 5000,
+  });
+  const directAuth = authRequirementFromResponse(direct);
+  if (directAuth) return directAuth;
+
+  if (mode !== 'crawl' || direct.status < 200 || direct.status >= 300) {
+    return { requiresAuth: false, status: direct.status };
+  }
+  if (isOpenApiText(direct.text)) return { requiresAuth: false, status: direct.status };
+
+  const resourceProbe = await fetchKnife4jOpenApiUrls(direct.url || sourceUrl, { type: 'none' }, true);
+  if (resourceProbe.requiresAuth) {
+    return {
+      requiresAuth: true,
+      status: resourceProbe.status,
+      message: `Knife4j 分组接口返回 ${resourceProbe.status}，需要输入用户名和密码后继续`,
+    };
+  }
+
+  const candidates = discoverOpenApiUrls(direct.url || sourceUrl, direct.text);
+  for (const candidate of candidates.slice(0, 12)) {
+    const candidateResponse = await inspectDocumentUrl(candidate, {
+      accept: 'application/json,text/plain,*/*',
+      userAgent: 'apiskill-openapi-auth-check/1.0',
+      referer: direct.url || sourceUrl,
+      timeoutMs: 3000,
+    });
+    const candidateAuth = authRequirementFromResponse(candidateResponse);
+    if (candidateAuth) return candidateAuth;
+  }
+
+  return { requiresAuth: false, status: direct.status };
+}
+
+async function inspectDocumentUrl(
+  sourceUrl: string,
+  options: { accept: string; userAgent: string; referer?: string; timeoutMs?: number },
+) {
+  try {
+    return await readUrlText(sourceUrl, options);
+  } catch {
+    return { status: 0, url: sourceUrl, text: '', contentType: '' };
+  }
+}
+
+function authRequirementFromResponse(response: { status: number; text: string; contentType: string }) {
+  if (response.status === 401 || response.status === 403) {
+    return {
+      requiresAuth: true,
+      status: response.status,
+      message: `该文档地址返回 ${response.status}，需要输入用户名和密码后继续`,
+    };
+  }
+
+  if (response.status >= 200 && response.status < 300 && looksLikeLoginPage(response.text, response.contentType)) {
+    return {
+      requiresAuth: true,
+      status: response.status,
+      message: '该文档地址打开后显示登录页，需要输入用户名和密码后继续',
+    };
+  }
+
+  return undefined;
+}
+
+function looksLikeLoginPage(text: string, contentType: string) {
+  const normalizedContentType = contentType.toLowerCase();
+  const sample = text.slice(0, 20000).toLowerCase();
+  return (
+    normalizedContentType.includes('text/html') &&
+    /<input\b[^>]+type=["']?password/i.test(text) &&
+    (sample.includes('login') || sample.includes('username') || sample.includes('password') || sample.includes('登录') || sample.includes('密码'))
+  );
+}
+
+function isOpenApiText(text: string) {
+  try {
+    return isOpenApiDocument(parseOpenApiText(text));
+  } catch {
+    return false;
+  }
+}
+
+function sendApiRequest(input: {
+  url?: string;
+  method?: string;
+  headers?: Record<string, string>;
+  body?: string;
+}): Promise<{ status: number; statusText: string; headers: Record<string, string | string[]>; body: string; elapsedMs: number; url: string }> {
+  return new Promise((resolveRequest, rejectRequest) => {
+    const targetUrl = normalizeUrl(input.url);
+    const url = new URL(targetUrl);
+    const method = (input.method || 'GET').toUpperCase();
+    const requestImpl = url.protocol === 'https:' ? httpsRequest : httpRequest;
+    const start = Date.now();
+    const headers = Object.fromEntries(
+      Object.entries(input.headers ?? {}).filter(([key, value]) => key.trim() && String(value).trim()),
+    );
+    const requestBody = ['GET', 'HEAD'].includes(method) ? undefined : input.body;
+
+    const req = requestImpl(
+      url,
+      {
+        method,
+        rejectUnauthorized: false,
+        headers: requestBody && !headers['content-length']
+          ? {
+              ...headers,
+              'content-length': Buffer.byteLength(requestBody),
+            }
+          : headers,
+      },
+      (res) => {
+        const chunks: Buffer[] = [];
+        res.on('data', (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+        res.on('end', () => {
+          resolveRequest({
+            status: res.statusCode ?? 0,
+            statusText: res.statusMessage || '',
+            headers: normalizeHeaders(res.headers),
+            body: Buffer.concat(chunks).toString('utf8'),
+            elapsedMs: Date.now() - start,
+            url: targetUrl,
+          });
+        });
+      },
+    );
+
+    req.setTimeout(30000, () => req.destroy(new Error('请求超时')));
+    req.on('error', rejectRequest);
+    if (requestBody) req.write(requestBody);
+    req.end();
+  });
+}
+
+function mockInfo(mock: Awaited<ReturnType<typeof startMockServer>>) {
+  return {
+    url: mock.url,
+    host: mock.host,
+    port: mock.port,
+    versionId: mock.versionId,
+    title: mock.title,
+    routesCount: mock.routesCount,
+    routes: mock.routes.slice(0, 20),
+  };
+}
+
+function normalizeOperationLinks(input: unknown) {
+  const record = input && typeof input === 'object' ? (input as Record<string, unknown>) : {};
+  return {
+    prototype: normalizeAssociatedLink(record.prototype),
+    ui: normalizeAssociatedLink(record.ui),
+  };
+}
+
+function normalizeAssociatedLink(input: unknown) {
+  const record = input && typeof input === 'object' ? (input as Record<string, unknown>) : {};
+  const sourceType = optionalText(record.sourceType);
+  const authType = optionalText(record.authType);
+  return {
+    sourceType: sourceType === 'online' || sourceType === 'curl' ? sourceType : 'local',
+    title: optionalText(record.title).slice(0, 120),
+    url: optionalText(record.url),
+    curl: optionalText(record.curl),
+    authType: ['browser', 'bearer', 'header'].includes(authType) ? authType : 'none',
+    token: optionalText(record.token),
+    headerName: optionalText(record.headerName).slice(0, 80),
+    note: optionalText(record.note).slice(0, 1000),
+  };
+}
+
+async function crawlOpenApi(sourceUrl: string, auth: ImportAuth) {
+  const direct = await tryFetchOpenApi(sourceUrl, auth, sourceUrl);
+  if (direct) return direct;
+
+  const response = await readUrlText(sourceUrl, {
+    accept: 'text/html,application/xhtml+xml,application/json,*/*',
+    userAgent: 'apiskill-openapi-crawler/1.0',
+    auth,
+    authOrigin: new URL(sourceUrl).origin,
+  });
+  if (response.status < 200 || response.status >= 300) throw new Error(`爬取页面失败: ${response.status}`);
+
+  const html = response.text;
+  const pageUrl = response.url || sourceUrl;
+  const knife4jCandidates = await fetchKnife4jOpenApiUrls(pageUrl, auth);
+  const scriptCandidates = await fetchScriptOpenApiUrls(pageUrl, html, auth);
+  const candidates = uniqueUrls([...knife4jCandidates.urls, ...scriptCandidates, ...discoverOpenApiUrls(pageUrl, html)]);
+  for (const url of candidates) {
+    const result = await tryFetchOpenApi(url, auth, pageUrl);
+    if (result) return result;
+  }
+
+  throw new Error('未在页面中识别到可用的 OpenAPI/Swagger JSON 地址');
+}
+
+async function fetchOpenApiJson(sourceUrl: string, auth: ImportAuth) {
+  const result = await tryFetchOpenApi(sourceUrl, auth, sourceUrl);
+  if (!result) throw new Error('该地址未返回有效的 OpenAPI/Swagger JSON 文档');
+  return result;
+}
+
+async function fetchOpenApiFromCurl(curlText: string) {
+  const parsed = parseCurlCommand(curlText);
+  const response = await readTextRequest({
+    url: parsed.url,
+    method: parsed.method,
+    headers: parsed.headers,
+    body: parsed.body,
+    timeoutMs: 30000,
+  });
+  if (response.status < 200 || response.status >= 300) {
+    throw new Error(`CURL 请求返回 ${response.status}`);
+  }
+
+  const document = parseOpenApiText(response.text);
+  if (!isOpenApiDocument(document)) {
+    throw new Error('CURL 响应不是有效的 OpenAPI/Swagger JSON 或 YAML 文档');
+  }
+
+  return { url: response.url || parsed.url, document };
+}
+
+function parseOpenApiFromUpload(content: string, fileName: string) {
+  if (!/\.(json|ya?ml)$/i.test(fileName)) {
+    throw new Error('仅支持 JSON、YAML 或 YML 文件');
+  }
+
+  const document = parseOpenApiText(content);
+  if (!isOpenApiDocument(document)) {
+    throw new Error('上传文件不是有效的 OpenAPI/Swagger JSON 或 YAML 文档');
+  }
+
+  return { url: fileName, document };
+}
+
+async function tryFetchOpenApi(sourceUrl: string, auth: ImportAuth, authSourceUrl: string) {
+  try {
+    const response = await readUrlText(sourceUrl, {
+      accept: 'application/json,text/plain,*/*',
+      userAgent: 'apiskill-openapi-importer/1.0',
+      referer: sourceUrl,
+      auth,
+      authOrigin: new URL(authSourceUrl).origin,
+    });
+    if (response.status < 200 || response.status >= 300) return undefined;
+
+    const document = parseOpenApiText(response.text);
+    if (!isOpenApiDocument(document)) return undefined;
+    return { url: response.url || sourceUrl, document };
+  } catch {
+    return undefined;
+  }
+}
+
+function readTextRequest(input: {
+  url: string;
+  method: string;
+  headers: Record<string, string>;
+  body?: string;
+  timeoutMs?: number;
+}): Promise<{ status: number; url: string; text: string; contentType: string }> {
+  return new Promise((resolveRequest, rejectRequest) => {
+    const url = new URL(input.url);
+    const requestImpl = url.protocol === 'https:' ? httpsRequest : httpRequest;
+    const headers = { ...input.headers };
+    const requestBody = ['GET', 'HEAD'].includes(input.method) ? undefined : input.body;
+    if (requestBody && !headerExists(headers, 'content-length')) {
+      headers['content-length'] = String(Buffer.byteLength(requestBody));
+    }
+
+    const req = requestImpl(
+      url,
+      {
+        method: input.method,
+        rejectUnauthorized: false,
+        headers,
+      },
+      (res) => {
+        const chunks: Buffer[] = [];
+        res.on('data', (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+        res.on('end', () => {
+          resolveRequest({
+            status: res.statusCode ?? 0,
+            url: url.toString(),
+            text: Buffer.concat(chunks).toString('utf8'),
+            contentType: String(res.headers['content-type'] ?? ''),
+          });
+        });
+      },
+    );
+
+    req.setTimeout(input.timeoutMs ?? 30000, () => req.destroy(new Error('请求超时')));
+    req.on('error', rejectRequest);
+    if (requestBody) req.write(requestBody);
+    req.end();
+  });
+}
+
+function parseCurlCommand(curlText: string) {
+  const tokens = tokenizeShell(curlText.replace(/\\\r?\n/g, ' '));
+  if (!tokens.length || tokens[0] !== 'curl') {
+    throw new Error('请输入以 curl 开头的命令');
+  }
+
+  const headers: Record<string, string> = {};
+  let method = 'GET';
+  let body: string | undefined;
+  let url = '';
+
+  for (let index = 1; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    const next = () => {
+      index += 1;
+      if (index >= tokens.length) throw new Error(`CURL 参数 ${token} 缺少值`);
+      return tokens[index];
+    };
+
+    if (token === '-H' || token === '--header') {
+      applyHeader(headers, next());
+      continue;
+    }
+    if (token.startsWith('-H') && token.length > 2) {
+      applyHeader(headers, token.slice(2));
+      continue;
+    }
+    if (token === '-X' || token === '--request') {
+      method = next().toUpperCase();
+      continue;
+    }
+    if (token === '--url') {
+      url = next();
+      continue;
+    }
+    if (['-d', '--data', '--data-raw', '--data-binary', '--data-urlencode'].includes(token)) {
+      body = next();
+      if (method === 'GET') method = 'POST';
+      continue;
+    }
+    if (token === '-A' || token === '--user-agent') {
+      headers['user-agent'] = next();
+      continue;
+    }
+    if (token === '-e' || token === '--referer') {
+      headers.referer = next();
+      continue;
+    }
+    if (token === '-u' || token === '--user') {
+      headers.authorization = `Basic ${Buffer.from(next(), 'utf8').toString('base64')}`;
+      continue;
+    }
+    if (token === '-b' || token === '--cookie') {
+      headers.cookie = next();
+      continue;
+    }
+    if (token === '-I' || token === '--head') {
+      method = 'HEAD';
+      continue;
+    }
+    if (['-o', '--output', '--connect-timeout', '--max-time'].includes(token)) {
+      next();
+      continue;
+    }
+    if (token.startsWith('-')) {
+      continue;
+    }
+    if (!url) url = token;
+  }
+
+  if (!url) throw new Error('CURL 命令中没有找到请求 URL');
+  const normalizedUrl = normalizeUrl(url);
+  return { url: normalizedUrl, method, headers, body };
+}
+
+function tokenizeShell(value: string) {
+  const tokens: string[] = [];
+  let current = '';
+  let quote: '"' | "'" | '' = '';
+  let escaping = false;
+
+  for (const char of value.trim()) {
+    if (escaping) {
+      current += char;
+      escaping = false;
+      continue;
+    }
+    if (char === '\\' && quote !== "'") {
+      escaping = true;
+      continue;
+    }
+    if ((char === '"' || char === "'") && !quote) {
+      quote = char;
+      continue;
+    }
+    if (char === quote) {
+      quote = '';
+      continue;
+    }
+    if (!quote && /\s/.test(char)) {
+      if (current) {
+        tokens.push(current);
+        current = '';
+      }
+      continue;
+    }
+    current += char;
+  }
+  if (quote) throw new Error('CURL 命令存在未闭合的引号');
+  if (current) tokens.push(current);
+  return tokens;
+}
+
+function applyHeader(headers: Record<string, string>, rawHeader: string) {
+  const index = rawHeader.indexOf(':');
+  if (index <= 0) return;
+  const key = rawHeader.slice(0, index).trim();
+  const value = rawHeader.slice(index + 1).trim();
+  if (key) headers[key] = value;
+}
+
+function headerExists(headers: Record<string, string>, target: string) {
+  return Object.keys(headers).some((key) => key.toLowerCase() === target.toLowerCase());
+}
+
+function readUrlText(
+  sourceUrl: string,
+  options: { accept: string; userAgent: string; referer?: string; auth?: ImportAuth; authOrigin?: string; timeoutMs?: number },
+  redirectCount = 0,
+): Promise<{ status: number; url: string; text: string; contentType: string }> {
+  return new Promise((resolveRequest, rejectRequest) => {
+    const url = new URL(sourceUrl);
+    const requestImpl = url.protocol === 'https:' ? httpsRequest : httpRequest;
+    const normalizedSourceUrl = url.toString();
+    const headers: Record<string, string> = {
+      accept: options.accept,
+      referer: normalizeHeaderUrl(options.referer || normalizedSourceUrl),
+      'user-agent': options.userAgent,
+    };
+    const authorization = basicAuthorizationHeader(normalizedSourceUrl, options.auth, options.authOrigin);
+    if (authorization) headers.authorization = authorization;
+    const req = requestImpl(
+      url,
+      {
+        method: 'GET',
+        rejectUnauthorized: false,
+        headers,
+      },
+      (res) => {
+        const status = res.statusCode ?? 0;
+        const location = res.headers.location;
+        if (location && [301, 302, 303, 307, 308].includes(status)) {
+          res.resume();
+          if (redirectCount >= 5) {
+            rejectRequest(new Error('重定向次数过多'));
+            return;
+          }
+          resolveRequest(readUrlText(new URL(location, sourceUrl).toString(), options, redirectCount + 1));
+          return;
+        }
+
+        const chunks: Buffer[] = [];
+        res.on('data', (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+        res.on('end', () => {
+          resolveRequest({
+            status,
+            url: normalizedSourceUrl,
+            text: Buffer.concat(chunks).toString('utf8'),
+            contentType: String(res.headers['content-type'] ?? ''),
+          });
+        });
+      },
+    );
+
+    req.setTimeout(options.timeoutMs ?? 20000, () => req.destroy(new Error('请求超时')));
+    req.on('error', rejectRequest);
+    req.end();
+  });
+}
+
+function discoverOpenApiUrls(pageUrl: string, html: string) {
+  const urls = new Set<string>();
+  const urlPatterns = [
+    /spec-url\s*=\s*["'`]([^"'`]+)["'`]/gi,
+    /specUrl\s*[:=]\s*["'`]([^"'`]+)["'`]/g,
+    /spec-url\s*:\s*["'`]([^"'`]+)["'`]/gi,
+    /spec\s*[:=]\s*["'`]([^"'`]+\.(?:ya?ml|json)(?:\?[^"'`]*)?)["'`]/gi,
+    /url\s*:\s*["'`]([^"'`]+)["'`]/g,
+    /urls\s*:\s*\[[\s\S]*?url\s*:\s*["'`]([^"'`]+)["'`]/g,
+    /href=["']([^"']+(?:api-docs|swagger|openapi|api\.json|swagger\.json|\.ya?ml|\.json)[^"']*)["']/gi,
+    /src=["']([^"']+(?:api-docs|swagger|openapi|api\.json|swagger\.json|\.ya?ml|\.json)[^"']*)["']/gi,
+    /["'`]([^"'`]+(?:api-docs|swagger|openapi|api\.json|swagger\.json|\.ya?ml)[^"'`]*)["'`]/gi,
+  ];
+
+  urlPatterns.forEach((pattern) => {
+    for (const match of html.matchAll(pattern)) {
+      addCandidate(urls, pageUrl, match[1]);
+    }
+  });
+
+  [
+    'swagger-resources',
+    '/api.json',
+    '/swagger.json',
+    '/openapi.json',
+    '/openapi.yaml',
+    '/swagger.yaml',
+    '/v2/api-docs',
+    '/v3/api-docs',
+    'api.json',
+    'swagger.json',
+    'openapi.json',
+    'openapi.yaml',
+    'swagger.yaml',
+    '../api.json',
+    '../swagger.json',
+    '../openapi.json',
+    '../openapi.yaml',
+    '../swagger.yaml',
+  ].forEach((candidate) => addCandidate(urls, pageUrl, candidate));
+
+  return [...urls];
+}
+
+async function fetchScriptOpenApiUrls(pageUrl: string, html: string, auth: ImportAuth) {
+  const urls = new Set<string>();
+  for (const scriptUrl of discoverScriptUrls(pageUrl, html)) {
+    try {
+      const response = await readUrlText(scriptUrl, {
+        accept: 'application/javascript,text/javascript,text/plain,*/*',
+        userAgent: 'apiskill-openapi-crawler/1.0',
+        referer: pageUrl,
+        auth,
+        authOrigin: new URL(pageUrl).origin,
+        timeoutMs: 8000,
+      });
+      if (response.status < 200 || response.status >= 300) continue;
+      discoverOpenApiUrls(response.url || scriptUrl, response.text).forEach((url) => urls.add(url));
+      discoverBundledSpecUrls(response.url || scriptUrl, response.text).forEach((url) => urls.add(url));
+    } catch {
+      // External scripts are optional discovery hints.
+    }
+  }
+  return [...urls];
+}
+
+function discoverScriptUrls(pageUrl: string, html: string) {
+  const urls = new Set<string>();
+  const pattern = /<script\b[^>]*\bsrc=["']([^"']+\.js(?:\?[^"']*)?)["'][^>]*>/gi;
+  for (const match of html.matchAll(pattern)) {
+    addCandidate(urls, pageUrl, match[1]);
+  }
+  return [...urls].slice(0, 8);
+}
+
+function discoverBundledSpecUrls(scriptUrl: string, scriptText: string) {
+  const urls = new Set<string>();
+  const patterns = [
+    /value\s*:\s*["'`]([^"'`]+\.(?:ya?ml|json)(?:\?[^"'`]*)?)["'`]/gi,
+    /["'`]([^"'`]+\.(?:ya?ml|json)(?:\?[^"'`]*)?)["'`]/gi,
+  ];
+  patterns.forEach((pattern) => {
+    for (const match of scriptText.matchAll(pattern)) {
+      addCandidate(urls, scriptUrl, match[1]);
+    }
+  });
+  return [...urls];
+}
+
+async function fetchKnife4jOpenApiUrls(pageUrl: string, auth: ImportAuth, probeOnly = false) {
+  const urls = new Set<string>();
+  const resourceUrls = discoverSwaggerResourceUrls(pageUrl);
+  let requiresAuth = false;
+  let status = 0;
+
+  for (const resourceUrl of resourceUrls) {
+    try {
+      const response = await readUrlText(resourceUrl, {
+        accept: 'application/json,text/plain,*/*',
+        userAgent: probeOnly ? 'apiskill-openapi-auth-check/1.0' : 'apiskill-openapi-crawler/1.0',
+        referer: pageUrl,
+        auth,
+        authOrigin: new URL(pageUrl).origin,
+        timeoutMs: probeOnly ? 3000 : 20000,
+      });
+      status = response.status;
+      if (response.status === 401 || response.status === 403) {
+        requiresAuth = true;
+        continue;
+      }
+      if (response.status < 200 || response.status >= 300) continue;
+
+      const resources = JSON.parse(stripBom(response.text));
+      if (!Array.isArray(resources)) continue;
+
+      resources.forEach((resource) => {
+        const location = resourceLocation(resource);
+        if (!location) return;
+        urls.add(resolveKnife4jResourceLocation(response.url || resourceUrl, pageUrl, location));
+      });
+      if (urls.size) break;
+    } catch {
+      // Keep trying the other common Knife4j resource locations.
+    }
+  }
+
+  return { urls: [...urls], requiresAuth, status };
+}
+
+function discoverSwaggerResourceUrls(pageUrl: string) {
+  const urls = new Set<string>();
+  addCandidate(urls, pageUrl, 'swagger-resources');
+  addCandidate(urls, pageUrl, './swagger-resources');
+  addCandidate(urls, pageUrl, '/swagger-resources');
+  return [...urls];
+}
+
+function resourceLocation(resource: unknown) {
+  if (!resource || typeof resource !== 'object') return '';
+  const record = resource as SwaggerResource;
+  return typeof record.location === 'string' ? record.location : typeof record.url === 'string' ? record.url : '';
+}
+
+function resolveKnife4jResourceLocation(resourceUrl: string, pageUrl: string, location: string) {
+  if (/^https?:\/\//i.test(location)) return location;
+  if (!location.startsWith('/')) return new URL(location, resourceUrl).toString();
+
+  const contextPath = knife4jContextPath(resourceUrl) || knife4jContextPath(pageUrl);
+  const origin = new URL(resourceUrl).origin;
+  return `${origin}${contextPath}${location}`.replace(/([^:]\/)\/+/g, '$1');
+}
+
+function knife4jContextPath(value: string) {
+  const pathname = new URL(value).pathname;
+  const marker = pathname.indexOf('/swagger-resources');
+  if (marker > 0) return pathname.slice(0, marker);
+  if (pathname.endsWith('/doc.html')) return pathname.slice(0, -'/doc.html'.length);
+  return '';
+}
+
+function addCandidate(urls: Set<string>, pageUrl: string, candidate?: string) {
+  if (!candidate) return;
+  const cleaned = candidate.replace(/\\u002F/g, '/').replace(/&amp;/g, '&').trim();
+  if (!cleaned || cleaned.startsWith('data:') || cleaned.startsWith('javascript:')) return;
+
+  try {
+    urls.add(new URL(cleaned, pageUrl).toString());
+  } catch {
+    // Ignore malformed URLs found in page scripts.
+  }
+}
+
+function isOpenApiDocument(value: unknown): value is { openapi?: string; swagger?: string; info?: { title?: string; version?: string }; paths?: object; components?: { schemas?: object }; definitions?: object } {
+  if (!value || typeof value !== 'object') return false;
+  const record = value as Record<string, unknown>;
+  return Boolean((record.openapi || record.swagger) && record.paths && typeof record.paths === 'object');
+}
+
+function normalizeUrl(value?: string) {
+  if (!value?.trim()) throw new Error('请输入文档地址');
+  const url = new URL(value.trim());
+  if (!['http:', 'https:'].includes(url.protocol)) {
+    throw new Error('仅支持 http 或 https 地址');
+  }
+  return url.toString();
+}
+
+function requiredText(value: unknown, message: string) {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(message);
+  return value.trim();
+}
+
+function optionalText(value: unknown) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function normalizeOptionalBaseUrl(value: unknown) {
+  const text = optionalText(value);
+  if (!text) return '';
+  const url = new URL(text);
+  if (!['http:', 'https:'].includes(url.protocol)) {
+    throw new Error('环境 Base URL 仅支持 http 或 https 地址');
+  }
+  return url.toString().replace(/\/$/, '');
+}
+
+function normalizeHeaderUrl(value: string) {
+  try {
+    return new URL(value).toString();
+  } catch {
+    return value;
+  }
+}
+
+function normalizeImportAuth(value: unknown): ImportAuth {
+  if (!value || typeof value !== 'object') return { type: 'none' };
+  const record = value as Record<string, unknown>;
+  if (record.type !== 'basic') return { type: 'none' };
+  return {
+    type: 'basic',
+    username: typeof record.username === 'string' ? record.username : '',
+    password: typeof record.password === 'string' ? record.password : '',
+  };
+}
+
+function basicAuthorizationHeader(sourceUrl: string, auth?: ImportAuth, authOrigin?: string) {
+  if (auth?.type !== 'basic') return undefined;
+  if (!auth.username && !auth.password) return undefined;
+
+  try {
+    if (authOrigin && new URL(sourceUrl).origin !== authOrigin) return undefined;
+  } catch {
+    return undefined;
+  }
+
+  return `Basic ${Buffer.from(`${auth.username ?? ''}:${auth.password ?? ''}`, 'utf8').toString('base64')}`;
+}
+
+function stripBom(value: string) {
+  return value.charCodeAt(0) === 0xfeff ? value.slice(1) : value;
+}
+
+function parseOpenApiText(text: string) {
+  const cleaned = stripBom(text);
+  try {
+    return JSON.parse(cleaned);
+  } catch {
+    return parseYaml(cleaned);
+  }
+}
+
+function uniqueUrls(urls: string[]) {
+  return [...new Set(urls)];
+}
+
+function formatVersionDate(value: Date) {
+  return value.toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
+}
+
+function resultSourceName(value: string, fallback: string) {
+  try {
+    return new URL(value).hostname || fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+function slugify(value: string) {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48) || 'openapi';
+}
+
+function normalizeHeaders(headers: IncomingMessage['headers']) {
+  const normalized: Record<string, string | string[]> = {};
+  Object.entries(headers).forEach(([key, value]) => {
+    if (Array.isArray(value)) normalized[key] = value;
+    else if (value !== undefined) normalized[key] = String(value);
+  });
+  return normalized;
+}
+
+async function readJsonBody(req: IncomingMessage) {
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+
+  const text = Buffer.concat(chunks).toString('utf8');
+  return text ? JSON.parse(text) : {};
+}
+
+function sendJson(res: ServerResponse, status: number, body: unknown) {
+  res.statusCode = status;
+  res.setHeader('content-type', 'application/json; charset=utf-8');
+  res.end(JSON.stringify(body));
+}