apiskill 0.1.0

package/scripts/lib/apiskill-core.mjs

@@ -0,0 +1,520 @@
+import { readFile } from 'node:fs/promises';
+import {
+  createBlankDocument,
+  deleteManualOperation,
+  endpointToManualConfig,
+  findEndpoint,
+  formatManualCli,
+  listCachedVersions,
+  listEndpoints,
+  parseManualCliText,
+  readCachedDocument,
+  saveImportedDocument,
+  saveManualOperation,
+} from './openapi-store.mjs';
+import { crawlOpenApi, importFromCurl, importFromLocalFile, importFromUrl } from './openapi-importer.mjs';
+
+const MAX_DEPTH = 12;
+
+export const importExamples = {
+  web: [
+    'apiskill run web',
+    'Open the local URL, then import a direct OpenAPI JSON/YAML URL, crawl Swagger UI / Knife4j / Redoc, upload a file, or paste a curl command.',
+  ],
+  cli: [
+    'npm run cli -- import https://example.com/openapi.json',
+    'npm run cli -- crawl https://example.com/swagger',
+    'npm run cli -- import-file ./openapi.yaml',
+    'npm run cli -- import-curl --file ./request.curl',
+  ],
+  mcp: [
+    { tool: 'apiskill_import_url', arguments: { url: 'https://example.com/openapi.json' } },
+    { tool: 'apiskill_crawl_openapi', arguments: { url: 'https://example.com/swagger' } },
+    { tool: 'apiskill_import_file', arguments: { file: '/absolute/path/openapi.yaml' } },
+    { tool: 'apiskill_import_curl', arguments: { curlText: 'curl https://example.com/openapi.json' } },
+  ],
+};
+
+export async function checkCache() {
+  const versions = await listCachedVersions();
+  try {
+    const { document, meta } = await readCachedDocument();
+    const paths = Object.keys(document.paths ?? {}).length;
+    const schemas = Object.keys(schemaMap(document)).length;
+    if (!paths) {
+      return {
+        ok: false,
+        message: 'No usable cached OpenAPI document found. The latest cache exists, but it has no paths.',
+        versionsCount: versions.length,
+        latestVersion: metaSummary(meta),
+        importExamples,
+      };
+    }
+    return {
+      ok: true,
+      message: 'API Skill cache is ready.',
+      versionsCount: versions.length,
+      latestVersion: {
+        ...metaSummary(meta),
+        paths,
+        schemas,
+      },
+      importExamples,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      message: 'No usable cached OpenAPI document found. Import or crawl a document first.',
+      error: error instanceof Error ? error.message : 'Unknown cache read error',
+      versionsCount: versions.length,
+      latestVersion: versions.find((version) => version.latest) ?? versions[0],
+      importExamples,
+    };
+  }
+}
+
+export function formatCheckText(result) {
+  const lines = [];
+  if (result.ok) {
+    lines.push('OK: API Skill cache is ready.');
+    if (result.latestVersion?.versionId) lines.push(`Latest version: ${result.latestVersion.versionId}`);
+    lines.push(`Versions: ${result.versionsCount ?? 0}`);
+    lines.push(`Paths: ${result.latestVersion?.paths ?? 0}`);
+    lines.push(`Schemas: ${result.latestVersion?.schemas ?? 0}`);
+    return lines.join('\n');
+  }
+
+  lines.push('No usable cached OpenAPI document found.');
+  if (result.error) lines.push(`Reason: ${result.error}`);
+  lines.push('');
+  lines.push('Import a document first:');
+  lines.push('');
+  lines.push('Web:');
+  result.importExamples.web.forEach((example) => lines.push(`  ${example}`));
+  lines.push('');
+  lines.push('CLI:');
+  result.importExamples.cli.forEach((example) => lines.push(`  ${example}`));
+  lines.push('');
+  lines.push('MCP:');
+  result.importExamples.mcp.forEach((example) => lines.push(`  ${example.tool} ${JSON.stringify(example.arguments)}`));
+  return lines.join('\n');
+}
+
+export async function listVersions({ limit = 20 } = {}) {
+  return listCachedVersions().then((versions) => versions.slice(0, clampLimit(limit, 20, 200)));
+}
+
+export async function searchEndpoints({ query = '', method = '', tag = '', versionId, limit = 20 } = {}) {
+  const { document, meta } = await readCachedDocument(versionId);
+  const normalizedQuery = String(query).trim().toLowerCase();
+  const normalizedMethod = String(method).trim().toLowerCase();
+  const normalizedTag = String(tag).trim();
+  const endpoints = listEndpoints(document)
+    .filter((endpoint) => !normalizedQuery || endpoint.searchable.includes(normalizedQuery))
+    .filter((endpoint) => !normalizedMethod || endpoint.method === normalizedMethod)
+    .filter((endpoint) => !normalizedTag || endpoint.tags.includes(normalizedTag))
+    .slice(0, clampLimit(limit, 20, 100))
+    .map(toEndpointSummary);
+
+  return {
+    version: metaSummary(meta),
+    count: endpoints.length,
+    endpoints,
+  };
+}
+
+export async function getEndpointDetails({ method, path, versionId, includeRaw = false } = {}) {
+  const normalizedMethod = requiredString({ method }, 'method').toLowerCase();
+  const normalizedPath = requiredString({ path }, 'path');
+  const { document, meta } = await readCachedDocument(versionId);
+  const endpoint = findEndpoint(document, normalizedMethod, normalizedPath);
+  if (!endpoint) throw new Error(`Endpoint not found: ${normalizedMethod.toUpperCase()} ${normalizedPath}`);
+  return endpointDetails(document, endpoint, meta, includeRaw);
+}
+
+export async function getAiContext({ method, path, versionId } = {}) {
+  const normalizedMethod = requiredString({ method }, 'method').toLowerCase();
+  const normalizedPath = requiredString({ path }, 'path');
+  const { document } = await readCachedDocument(versionId);
+  const endpoint = findEndpoint(document, normalizedMethod, normalizedPath);
+  if (!endpoint) throw new Error(`Endpoint not found: ${normalizedMethod.toUpperCase()} ${normalizedPath}`);
+  return buildAiMarkdown(document, endpoint);
+}
+
+export async function getSchemaDetails({ name, versionId } = {}) {
+  const schemaNameOrSuffix = requiredString({ name }, 'name');
+  const { document, meta } = await readCachedDocument(versionId);
+  const schemas = schemaMap(document);
+  const schemaName = Object.keys(schemas).find((key) => key === schemaNameOrSuffix) ?? Object.keys(schemas).find((key) => key.endsWith(schemaNameOrSuffix));
+  if (!schemaName) throw new Error(`Schema not found: ${schemaNameOrSuffix}`);
+  return {
+    version: metaSummary(meta),
+    name: schemaName,
+    fields: flattenSchema(document, schemas[schemaName]),
+    rawSchema: schemas[schemaName],
+  };
+}
+
+export async function queryApi({ pathOrKeyword, method = '', versionId, limit = 20, format = 'json' } = {}) {
+  const keyword = requiredString({ pathOrKeyword }, 'pathOrKeyword');
+  const { document, meta } = await readCachedDocument(versionId);
+  const result = queryEndpoints(document, keyword, { method, limit });
+  if (result.kind === 'single') {
+    if (format === 'cli') {
+      return {
+        kind: 'single',
+        version: metaSummary(meta),
+        cli: formatManualCli(endpointToManualConfig(result.endpoint, document)),
+      };
+    }
+    if (format === 'raw') {
+      return {
+        kind: 'single',
+        version: metaSummary(meta),
+        endpoint: result.endpoint,
+      };
+    }
+    return {
+      kind: 'single',
+      version: metaSummary(meta),
+      endpoint: endpointDetails(document, result.endpoint, meta, false),
+    };
+  }
+  return {
+    kind: 'multiple',
+    version: metaSummary(meta),
+    count: result.endpoints.length,
+    endpoints: result.endpoints.map(toEndpointSummary),
+  };
+}
+
+export async function importOpenApiUrl({ url, auth, versionId } = {}) {
+  const sourceUrl = requiredString({ url }, 'url');
+  const result = await importFromUrl(sourceUrl, { basicAuth: auth });
+  return saveImportedDocument({ document: result.document, mode: 'file', inputUrl: sourceUrl, resolvedUrl: result.resolvedUrl, versionId });
+}
+
+export async function crawlOpenApiUrl({ url, auth, versionId } = {}) {
+  const pageUrl = requiredString({ url }, 'url');
+  const result = await crawlOpenApi(pageUrl, { basicAuth: auth });
+  return saveImportedDocument({ document: result.document, mode: 'crawl', inputUrl: pageUrl, resolvedUrl: result.resolvedUrl, versionId });
+}
+
+export async function importOpenApiFile({ file, versionId } = {}) {
+  const filePath = requiredString({ file }, 'file');
+  const result = await importFromLocalFile(filePath);
+  return saveImportedDocument({ document: result.document, mode: 'upload', inputUrl: filePath, resolvedUrl: result.resolvedUrl, versionId });
+}
+
+export async function importOpenApiCurl({ curlText, curlFile, versionId } = {}) {
+  const text = curlFile ? await readFile(curlFile, 'utf8') : curlText;
+  const command = requiredString({ curlText: text }, 'curlText');
+  const result = await importFromCurl(command);
+  return saveImportedDocument({ document: result.document, mode: 'curl', inputUrl: command, resolvedUrl: result.resolvedUrl, versionId });
+}
+
+export async function createDocument({ title, version, description, environmentName, environmentBaseUrl } = {}) {
+  return createBlankDocument({ title, version, description, environmentName, environmentBaseUrl });
+}
+
+export async function createApi({ config, configText, versionId } = {}) {
+  const normalized = config ?? parseManualCliText(requiredString({ configText }, 'configText'));
+  return saveManualOperation({ versionId, config: normalized });
+}
+
+export async function editApi({ method, path, config, configText, versionId } = {}) {
+  const normalizedMethod = requiredString({ method }, 'method');
+  const normalizedPath = requiredString({ path }, 'path');
+  const targetVersionId = versionId || (await readCachedDocument()).meta?.versionId;
+  const normalized = config ?? parseManualCliText(requiredString({ configText }, 'configText'));
+  return saveManualOperation({ versionId: targetVersionId, config: normalized, replaceTarget: { method: normalizedMethod, path: normalizedPath } });
+}
+
+export async function deleteApi({ method, path, versionId } = {}) {
+  const normalizedMethod = requiredString({ method }, 'method');
+  const normalizedPath = requiredString({ path }, 'path');
+  const targetVersionId = versionId || (await readCachedDocument()).meta?.versionId;
+  return deleteManualOperation({ versionId: targetVersionId, method: normalizedMethod, path: normalizedPath });
+}
+
+export function queryEndpoints(document, pathOrKeyword, options = {}) {
+  const keyword = String(pathOrKeyword || '').trim();
+  const normalized = keyword.toLowerCase();
+  const method = String(options.method || '').trim().toLowerCase();
+  const limit = clampLimit(options.limit, 20, 200);
+  const endpoints = listEndpoints(document).filter((endpoint) => !method || endpoint.method === method);
+  const exactMatches = endpoints.filter((endpoint) => endpoint.path === keyword);
+  if (exactMatches.length === 1) return { kind: 'single', endpoint: exactMatches[0] };
+  if (exactMatches.length > 1) return { kind: 'multiple', endpoints: exactMatches.slice(0, limit) };
+
+  const fuzzyMatches = endpoints.filter((endpoint) => endpoint.path.includes(keyword) || endpoint.searchable.includes(normalized));
+  if (fuzzyMatches.length === 1) return { kind: 'single', endpoint: fuzzyMatches[0] };
+  if (!fuzzyMatches.length) throw new Error(`没有找到匹配接口: ${keyword}`);
+  return { kind: 'multiple', endpoints: fuzzyMatches.slice(0, limit) };
+}
+
+export function formatSavedResult(saved) {
+  return {
+    meta: saved.meta,
+    versionId: saved.meta.versionId,
+    paths: saved.meta.paths,
+    schemas: saved.meta.schemas,
+    file: saved.meta.savedPath,
+  };
+}
+
+function endpointDetails(document, endpoint, meta, includeRaw) {
+  const operation = endpoint.operation;
+  return {
+    version: metaSummary(meta),
+    method: endpoint.method.toUpperCase(),
+    path: endpoint.path,
+    summary: endpoint.summary,
+    tags: endpoint.tags,
+    parameters: parameterRows(document, operation.parameters),
+    requestBody: requestBodyRows(document, operation),
+    responses: responseRows(document, operation),
+    manualConfig: endpointToManualConfig(endpoint, document),
+    rawOperation: includeRaw ? operation : undefined,
+  };
+}
+
+function toEndpointSummary(endpoint) {
+  return {
+    method: endpoint.method.toUpperCase(),
+    path: endpoint.path,
+    summary: endpoint.summary,
+    tags: endpoint.tags,
+    hasBody: endpoint.hasBody,
+  };
+}
+
+function schemaMap(document) {
+  return document.components?.schemas ?? document.definitions ?? {};
+}
+
+function getSchemaName(ref) {
+  if (!ref) return '';
+  return decodeURIComponent(ref.split('/').pop() ?? ref);
+}
+
+function resolveSchema(document, schema, seen = new Set()) {
+  if (!schema) return undefined;
+  if (schema.$ref) {
+    if (seen.has(schema.$ref)) return { type: 'object', description: `循环引用: ${getSchemaName(schema.$ref)}` };
+    seen.add(schema.$ref);
+    const resolved = schema.$ref.startsWith('#/')
+      ? schema.$ref
+          .slice(2)
+          .split('/')
+          .reduce((current, key) => (current && typeof current === 'object' ? current[decodeURIComponent(key)] : undefined), document)
+      : undefined;
+    return resolveSchema(document, resolved, seen);
+  }
+  if (schema.allOf?.length) return mergeSchemas(document, schema.allOf, schema);
+  return schema;
+}
+
+function mergeSchemas(document, schemas, base) {
+  return schemas.reduce(
+    (merged, item) => {
+      const resolved = resolveSchema(document, item) ?? {};
+      return {
+        ...merged,
+        ...resolved,
+        description: [merged.description, resolved.description].filter(Boolean).join('；') || merged.description,
+        required: [...new Set([...(merged.required ?? []), ...(resolved.required ?? [])])],
+        properties: { ...(merged.properties ?? {}), ...(resolved.properties ?? {}) },
+      };
+    },
+    { ...base, allOf: undefined },
+  );
+}
+
+function schemaType(document, schema) {
+  if (!schema) return '-';
+  if (schema.$ref) return getSchemaName(schema.$ref);
+  const resolved = resolveSchema(document, schema) ?? schema;
+  if (resolved.enum?.length) return `${resolved.type ?? 'enum'}<${resolved.enum.map(formatValue).join(' | ')}>`;
+  if (resolved.type === 'array') return `${schemaType(document, resolved.items)}[]`;
+  if (resolved.anyOf?.length) return resolved.anyOf.map((item) => schemaType(document, item)).join(' | ');
+  if (resolved.oneOf?.length) return resolved.oneOf.map((item) => schemaType(document, item)).join(' | ');
+  if (resolved.additionalProperties && typeof resolved.additionalProperties === 'object') {
+    return `Record<string, ${schemaType(document, resolved.additionalProperties)}>`;
+  }
+  return [resolved.type, resolved.format].filter(Boolean).join(':') || 'object';
+}
+
+function flattenSchema(document, schema, options = {}) {
+  const depth = options.depth ?? 0;
+  if (!schema || depth > MAX_DEPTH) return [];
+  if (schema.$ref) {
+    if (options.seen?.has(schema.$ref)) {
+      return [fieldRow(options.prefix || getSchemaName(schema.$ref), options.prefix || getSchemaName(schema.$ref), getSchemaName(schema.$ref), '循环引用，已停止展开', false, depth, options.location)];
+    }
+    const nextSeen = new Set(options.seen ?? []);
+    nextSeen.add(schema.$ref);
+    return flattenSchema(document, resolveSchema(document, schema), { ...options, seen: nextSeen });
+  }
+
+  const resolved = resolveSchema(document, schema) ?? schema;
+  const properties = resolved.properties ?? {};
+  const rows = [];
+  const requiredFields = resolved.required ?? options.requiredFields ?? [];
+  if (resolved.type === 'array') {
+    const name = options.prefix || '[]';
+    rows.push(toRow(document, name, name, resolved, false, depth, options.location));
+    rows.push(...flattenSchema(document, resolved.items, { ...options, prefix: `${name}[]`, depth: depth + 1 }));
+    return rows;
+  }
+  if (!Object.keys(properties).length) {
+    if (options.prefix) rows.push(toRow(document, options.prefix.split('.').pop() ?? options.prefix, options.prefix, resolved, false, depth, options.location));
+    return rows;
+  }
+  Object.entries(properties).forEach(([name, property]) => {
+    const path = options.prefix ? `${options.prefix}.${name}` : name;
+    const child = resolveSchema(document, property) ?? property;
+    rows.push(toRow(document, name, path, property, requiredFields.includes(name), depth, options.location));
+    const nested = child.type === 'array' || Boolean(child.properties && Object.keys(child.properties).length) || Boolean(child.$ref);
+    if (nested) {
+      rows.push(...flattenSchema(document, property, { ...options, prefix: child.type === 'array' ? `${path}[]` : path, requiredFields: child.required, depth: depth + 1 }));
+    }
+  });
+  return rows;
+}
+
+function fieldRow(name, path, type, description, required, depth, location) {
+  return { name, path, location, required, type, description, defaultValue: '', enumValue: '', depth };
+}
+
+function toRow(document, name, path, schema, required, depth, location) {
+  const resolved = resolveSchema(document, schema) ?? schema;
+  return {
+    name,
+    path,
+    location,
+    required,
+    type: schemaType(document, schema),
+    description: schema?.description?.trim() || resolved.description?.trim() || '',
+    defaultValue: resolved.default === undefined ? '' : formatValue(resolved.default),
+    enumValue: resolved.enum?.map(formatValue).join(', ') ?? '',
+    depth,
+  };
+}
+
+function parameterRows(document, parameters = []) {
+  return parameters.map((parameter) => ({
+    name: parameter.name,
+    path: parameter.name,
+    location: parameter.in,
+    required: Boolean(parameter.required),
+    type: schemaType(document, parameter.schema ?? parameter),
+    description: parameter.description || parameter.schema?.description || '',
+    defaultValue: parameter.schema?.default === undefined ? '' : formatValue(parameter.schema.default),
+    enumValue: parameter.schema?.enum?.map(formatValue).join(', ') ?? '',
+    depth: 0,
+  }));
+}
+
+function requestBodyRows(document, operation) {
+  return Object.fromEntries(
+    Object.entries(operation.requestBody?.content ?? {}).map(([mediaType, media]) => [
+      mediaType,
+      flattenSchema(document, media.schema).map((row) => ({ ...row, location: 'body' })),
+    ]),
+  );
+}
+
+function responseRows(document, operation) {
+  return Object.fromEntries(
+    Object.entries(operation.responses ?? {}).map(([status, response]) => [
+      status,
+      Object.fromEntries(
+        Object.entries(response.content ?? {}).map(([mediaType, media]) => [
+          mediaType,
+          flattenSchema(document, media.schema).map((row) => ({ ...row, location: `response ${status}` })),
+        ]),
+      ),
+    ]),
+  );
+}
+
+function buildAiMarkdown(document, endpoint) {
+  const operation = endpoint.operation;
+  const parameterText = rowsToMarkdown(parameterRows(document, operation.parameters), '无参数');
+  const requestBodies = requestBodyRows(document, operation);
+  const responses = responseRows(document, operation);
+  const requestText = Object.keys(requestBodies).length
+    ? Object.entries(requestBodies)
+        .map(([mediaType, rows]) => `### Request Body: ${mediaType}\n${rowsToMarkdown(rows, '空对象或无字段说明')}`)
+        .join('\n\n')
+    : '### Request Body\n无请求体';
+  const responseText = Object.entries(operation.responses ?? {})
+    .map(([status, response]) => {
+      const medias = responses[status] ?? {};
+      const rows = Object.entries(medias);
+      if (!rows.length) return `### Response ${status}\n- Description: ${response.description || '无'}\n- Fields: 无字段说明`;
+      return rows.map(([mediaType, fields]) => `### Response ${status}: ${mediaType}\n- Description: ${response.description || '无'}\n${rowsToMarkdown(fields, '空对象或无字段说明')}`).join('\n\n');
+    })
+    .join('\n\n');
+
+  return [
+    `# API: ${endpoint.method.toUpperCase()} ${endpoint.path}`,
+    `- Summary: ${endpoint.summary}`,
+    `- Tags: ${endpoint.tags.join(', ')}`,
+    operation.operationId ? `- OperationId: ${operation.operationId}` : '',
+    operation.description ? `- Description: ${operation.description}` : '',
+    '',
+    '## Request Parameters',
+    parameterText,
+    '',
+    requestText,
+    '',
+    '## Responses',
+    responseText || '无响应说明',
+  ]
+    .filter((line) => line !== '')
+    .join('\n');
+}
+
+function rowsToMarkdown(rows, emptyText) {
+  if (!rows.length) return emptyText;
+  return [
+    '| 字段 | 位置 | 必填 | 类型 | 默认值 | 枚举 | 说明 |',
+    '| --- | --- | --- | --- | --- | --- | --- |',
+    ...rows.map((row) => `| ${escapeCell(row.depth > 0 ? `${'  '.repeat(row.depth)}${row.name}` : row.name)} | ${escapeCell(row.location || '-')} | ${row.required ? '是' : '否'} | ${escapeCell(row.type)} | ${escapeCell(row.defaultValue || '-')} | ${escapeCell(row.enumValue || '-')} | ${escapeCell(row.description || '-')} |`),
+  ].join('\n');
+}
+
+function metaSummary(meta) {
+  if (!meta) return {};
+  return {
+    versionId: meta.versionId,
+    savedAt: meta.savedAt,
+    inputUrl: meta.inputUrl,
+    resolvedUrl: meta.resolvedUrl,
+    paths: meta.paths,
+    schemas: meta.schemas,
+  };
+}
+
+function requiredString(args, key) {
+  const value = args?.[key];
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`Missing required argument: ${key}`);
+  return value.trim();
+}
+
+function clampLimit(value, fallback, max) {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric) || numeric <= 0) return fallback;
+  return Math.min(Math.floor(numeric), max);
+}
+
+function formatValue(value) {
+  if (typeof value === 'string') return value;
+  return JSON.stringify(value);
+}
+
+function escapeCell(value) {
+  return String(value).replace(/\|/g, '\\|').replace(/\n/g, '<br />');
+}