apiskill 0.1.0

package/src/DocumentVersionManager.tsx

@@ -0,0 +1,264 @@
+import { useEffect, useMemo, useState } from 'react';
+import { Check, Download, Pencil, RefreshCcw, Server, Trash2, X } from 'lucide-react';
+import { VERSION_EXPORT_API_URL } from './swagger';
+
+export type DocumentVersionMeta = {
+  versionId?: string;
+  mode?: string;
+  inputUrl?: string;
+  resolvedUrl?: string;
+  title?: string;
+  version?: string;
+  savedAt?: string;
+  paths?: number;
+  schemas?: number;
+  environmentName?: string;
+  environmentBaseUrl?: string;
+};
+
+export function DocumentVersionManager({
+  versions,
+  selectedVersionId,
+  currentVersion,
+  disabled,
+  onSelect,
+  onPrepareUpdate,
+  onUpdateEnvironment,
+  onDelete,
+}: {
+  versions: DocumentVersionMeta[];
+  selectedVersionId: string;
+  currentVersion?: DocumentVersionMeta;
+  disabled?: boolean;
+  onSelect: (versionId: string) => void;
+  onPrepareUpdate: (version: DocumentVersionMeta) => Promise<void> | void;
+  onUpdateEnvironment: (versionId: string, environmentName: string, environmentBaseUrl: string) => Promise<void>;
+  onDelete: (versionId: string) => Promise<void>;
+}) {
+  const [open, setOpen] = useState(false);
+  const [editingVersionId, setEditingVersionId] = useState('');
+  const [environmentName, setEnvironmentName] = useState('');
+  const [environmentBaseUrl, setEnvironmentBaseUrl] = useState('');
+  const [busyVersionId, setBusyVersionId] = useState('');
+  const [message, setMessage] = useState('');
+
+  const selectedVersion = useMemo(
+    () => currentVersion ?? versions.find((version) => version.versionId === selectedVersionId),
+    [currentVersion, selectedVersionId, versions],
+  );
+
+  useEffect(() => {
+    if (!open) {
+      setEditingVersionId('');
+      setMessage('');
+    }
+  }, [open]);
+
+  function beginEdit(version: DocumentVersionMeta) {
+    setMessage('');
+    setEditingVersionId(version.versionId || '');
+    setEnvironmentName(version.environmentName || '');
+    setEnvironmentBaseUrl(version.environmentBaseUrl || '');
+  }
+
+  async function saveEnvironment(versionId: string) {
+    setBusyVersionId(versionId);
+    setMessage('');
+    try {
+      await onUpdateEnvironment(versionId, environmentName, environmentBaseUrl);
+      setEditingVersionId('');
+      setMessage('环境已保存');
+    } catch (error) {
+      setMessage(error instanceof Error ? error.message : '环境保存失败');
+    } finally {
+      setBusyVersionId('');
+    }
+  }
+
+  async function deleteVersion(version: DocumentVersionMeta) {
+    const versionId = version.versionId;
+    if (!versionId) return;
+    if (!window.confirm(`确认删除文档版本 ${formatVersionTitle(version)}？`)) return;
+
+    setBusyVersionId(versionId);
+    setMessage('');
+    try {
+      await onDelete(versionId);
+      setMessage('版本已删除');
+    } catch (error) {
+      setMessage(error instanceof Error ? error.message : '版本删除失败');
+    } finally {
+      setBusyVersionId('');
+    }
+  }
+
+  async function prepareUpdate(version: DocumentVersionMeta) {
+    const versionId = version.versionId;
+    if (!versionId) return;
+
+    setBusyVersionId(versionId);
+    setMessage('');
+    try {
+      await onPrepareUpdate(version);
+      setOpen(false);
+    } catch (error) {
+      setMessage(error instanceof Error ? error.message : '准备更新失败');
+    } finally {
+      setBusyVersionId('');
+    }
+  }
+
+  function exportVersion(versionId?: string) {
+    if (!versionId) return;
+    const anchor = document.createElement('a');
+    anchor.href = `${VERSION_EXPORT_API_URL}?versionId=${encodeURIComponent(versionId)}`;
+    anchor.download = `${versionId}.json`;
+    document.body.appendChild(anchor);
+    anchor.click();
+    document.body.removeChild(anchor);
+  }
+
+  return (
+    <div className="version-manager">
+      <button className="version-manager-trigger" onClick={() => setOpen(true)} disabled={disabled || !versions.length}>
+        <Server size={16} />
+        <span>
+          <strong>{selectedVersion ? formatVersionTitle(selectedVersion) : '无缓存版本'}</strong>
+          <small>
+            {selectedVersion
+              ? [
+                  selectedVersion.environmentName || '未设置环境',
+                  selectedVersion.paths === undefined ? '' : `${selectedVersion.paths} paths`,
+                  selectedVersion.savedAt ? formatVersionDate(selectedVersion.savedAt) : '',
+                ]
+                  .filter(Boolean)
+                  .join(' · ')
+              : '导入或爬取文档后可管理版本'}
+          </small>
+        </span>
+      </button>
+
+      {open ? (
+        <div className="modal-backdrop" role="dialog" aria-modal="true" aria-labelledby="version-manager-title">
+          <div className="version-manager-dialog">
+            <div className="import-dialog-header">
+              <div>
+                <p className="eyebrow">Document Versions</p>
+                <h2 id="version-manager-title">文档版本管理</h2>
+              </div>
+              <button className="icon-secondary-button" onClick={() => setOpen(false)} aria-label="关闭">
+                <X size={17} />
+              </button>
+            </div>
+
+            <div className="version-manager-body">
+              {message ? <div className={message.includes('失败') || message.includes('不支持') ? 'version-message error' : 'version-message'}>{message}</div> : null}
+              {!versions.length ? (
+                <p className="muted">暂无缓存版本。</p>
+              ) : (
+                versions.map((version) => {
+                  const versionId = version.versionId || '';
+                  const editing = editingVersionId === versionId;
+                  const busy = busyVersionId === versionId;
+                  const selected = versionId === selectedVersionId;
+
+                  return (
+                    <section key={versionId} className={`version-item ${selected ? 'active' : ''}`}>
+                      <div className="version-item-main">
+                        <div>
+                          <div className="version-item-title">
+                            <strong>{formatVersionTitle(version)}</strong>
+                            {selected ? <span>当前</span> : null}
+                          </div>
+                          <p>{versionId}</p>
+                        </div>
+                        <div className="version-item-stats">
+                          <span>{version.mode || 'unknown'}</span>
+                          <span>{version.paths ?? 0} paths</span>
+                          <span>{version.schemas ?? 0} schemas</span>
+                          <span>{version.savedAt ? formatVersionDate(version.savedAt) : '-'}</span>
+                        </div>
+                      </div>
+
+                      {editing ? (
+                        <div className="version-env-editor">
+                          <label>
+                            环境名称
+                            <input value={environmentName} onChange={(event) => setEnvironmentName(event.target.value)} placeholder="例如 dev / test / prod" />
+                          </label>
+                          <label>
+                            Base URL
+                            <input
+                              value={environmentBaseUrl}
+                              onChange={(event) => setEnvironmentBaseUrl(event.target.value)}
+                              placeholder="https://api.example.com"
+                            />
+                          </label>
+                        </div>
+                      ) : (
+                        <div className="version-env-summary">
+                          <span>{version.environmentName || '未设置环境'}</span>
+                          <code>{version.environmentBaseUrl || '未设置 Base URL'}</code>
+                        </div>
+                      )}
+
+                      <div className="version-item-actions">
+                        <button className="secondary-button" onClick={() => onSelect(versionId)} disabled={selected || busy || !versionId}>
+                          <RefreshCcw size={15} />
+                          切换
+                        </button>
+                        <button className="primary-button" onClick={() => prepareUpdate(version)} disabled={busy || !versionId}>
+                          <RefreshCcw size={15} />
+                          更新
+                        </button>
+                        {editing ? (
+                          <>
+                            <button className="primary-button" onClick={() => saveEnvironment(versionId)} disabled={busy || !versionId}>
+                              <Check size={15} />
+                              保存环境
+                            </button>
+                            <button className="secondary-button" onClick={() => setEditingVersionId('')} disabled={busy}>
+                              取消
+                            </button>
+                          </>
+                        ) : (
+                          <button className="secondary-button" onClick={() => beginEdit(version)} disabled={busy || !versionId}>
+                            <Pencil size={15} />
+                            环境
+                          </button>
+                        )}
+                        <button className="secondary-button" onClick={() => exportVersion(versionId)} disabled={!versionId}>
+                          <Download size={15} />
+                          导出
+                        </button>
+                        <button className="danger-button" onClick={() => deleteVersion(version)} disabled={busy || !versionId}>
+                          <Trash2 size={15} />
+                          删除
+                        </button>
+                      </div>
+                    </section>
+                  );
+                })
+              )}
+            </div>
+          </div>
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+function formatVersionTitle(version: DocumentVersionMeta) {
+  return version.title || version.inputUrl || version.versionId || '未命名版本';
+}
+
+function formatVersionDate(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',
+  });
+}

package/src/main.tsx

@@ -0,0 +1,10 @@
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { App } from './App';
+import './styles.css';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+);

package/src/manualApiConfig.ts

@@ -0,0 +1,401 @@
+import type { HttpMethod, SwaggerDocument, SwaggerOperation, SwaggerParameter, SwaggerSchema } from './types';
+import { parse as parseYaml } from 'yaml';
+
+export type ManualApiFieldLocation = 'query' | 'path' | 'header' | 'cookie' | 'body';
+
+export type ManualApiFieldConfig = {
+  name: string;
+  location?: ManualApiFieldLocation;
+  required?: boolean;
+  type?: string;
+  format?: string;
+  description?: string;
+  defaultValue?: string;
+  enumValue?: string;
+  children?: ManualApiFieldConfig[];
+};
+
+export type ManualApiResponseConfig = {
+  status: string;
+  description?: string;
+  contentType?: string;
+  fields?: ManualApiFieldConfig[];
+};
+
+export type ManualApiOperationConfig = {
+  method: HttpMethod;
+  path: string;
+  summary: string;
+  description?: string;
+  operationId?: string;
+  tags?: string[];
+  parameters?: ManualApiFieldConfig[];
+  requestBody?: {
+    required?: boolean;
+    contentType?: string;
+    fields?: ManualApiFieldConfig[];
+  };
+  responses?: ManualApiResponseConfig[];
+};
+
+const HTTP_METHODS = new Set<HttpMethod>(['get', 'post', 'put', 'delete', 'patch', 'options', 'head']);
+
+export function parseManualApiCliText(value: string): ManualApiOperationConfig {
+  const cleaned = stripCliText(value);
+  if (!cleaned) throw new Error('请输入 API CLI 配置文本');
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(cleaned);
+  } catch {
+    parsed = parseYaml(cleaned);
+  }
+
+  const record = parsed && typeof parsed === 'object' ? (parsed as Record<string, unknown>) : {};
+  return normalizeManualApiOperationConfig(record.api ?? record.config ?? record.operation ?? parsed);
+}
+
+export function createManualApiCliTemplate() {
+  return formatManualApiCliConfig({
+    method: 'post',
+    path: '/api/v1/example/{id}',
+    summary: '创建示例',
+    operationId: 'createExample',
+    tags: ['示例', '后台管理'],
+    description: '接口用途、业务约束、鉴权说明等。',
+    parameters: [
+      {
+        name: 'id',
+        location: 'path',
+        required: true,
+        type: 'string',
+        description: '示例 ID',
+      },
+    ],
+    requestBody: {
+      required: true,
+      contentType: 'application/json',
+      fields: [
+        {
+          name: 'name',
+          type: 'string',
+          required: true,
+          description: '名称',
+        },
+        {
+          name: 'profile',
+          type: 'object',
+          description: '扩展信息',
+          children: [
+            {
+              name: 'email',
+              type: 'string',
+              description: '邮箱',
+            },
+          ],
+        },
+      ],
+    },
+    responses: [
+      {
+        status: '200',
+        description: 'OK',
+        contentType: 'application/json',
+        fields: [
+          {
+            name: 'data',
+            type: 'object',
+            description: '响应数据',
+            children: [
+              {
+                name: 'id',
+                type: 'string',
+                description: '记录 ID',
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  });
+}
+
+export function formatManualApiCliConfig(config: ManualApiOperationConfig) {
+  return JSON.stringify({ api: normalizeManualApiOperationConfig(config) });
+}
+
+export function normalizeManualApiOperationConfig(input: unknown): ManualApiOperationConfig {
+  if (!input || typeof input !== 'object') throw new Error('接口配置不能为空');
+  const record = input as Record<string, unknown>;
+  const method = text(record.method).toLowerCase() as HttpMethod;
+  if (!HTTP_METHODS.has(method)) throw new Error('请选择有效的请求方法');
+
+  const path = normalizePath(text(record.path));
+  const summary = text(record.summary);
+  if (!path) throw new Error('接口路径不能为空');
+  if (!summary) throw new Error('接口名称不能为空');
+
+  const parameters = array(record.parameters).map(normalizeField).filter((field) => field.name);
+  const requestBodyRecord = record.requestBody && typeof record.requestBody === 'object' ? (record.requestBody as Record<string, unknown>) : {};
+  const requestFields = array(requestBodyRecord.fields).map(normalizeField).filter((field) => field.name);
+  const responses = array(record.responses).map(normalizeResponse).filter((response) => response.status);
+  if (!responses.length) responses.push({ status: '200', description: 'Success', contentType: 'application/json', fields: [] });
+
+  return {
+    method,
+    path,
+    summary,
+    description: text(record.description),
+    operationId: text(record.operationId),
+    tags: splitTags(record.tags),
+    parameters,
+    requestBody: {
+      required: Boolean(requestBodyRecord.required),
+      contentType: text(requestBodyRecord.contentType) || 'application/json',
+      fields: requestFields,
+    },
+    responses,
+  };
+}
+
+export function createManualApiDocument(title = 'Manual API Config'): SwaggerDocument {
+  return {
+    openapi: '3.0.3',
+    info: {
+      title,
+      version: 'manual',
+      description: 'Created from API Skill Console manual configuration.',
+    },
+    paths: {},
+    components: {
+      schemas: {},
+    },
+  };
+}
+
+export function applyManualApiOperationConfig(document: SwaggerDocument, config: ManualApiOperationConfig): SwaggerDocument {
+  const nextDoc = cloneDocument(document);
+  const normalized = normalizeManualApiOperationConfig(config);
+  const pathItem = nextDoc.paths?.[normalized.path] ?? {};
+  pathItem[normalized.method] = buildOperation(normalized);
+  nextDoc.paths = {
+    ...(nextDoc.paths ?? {}),
+    [normalized.path]: pathItem,
+  };
+  return nextDoc;
+}
+
+export function deleteManualApiOperation(document: SwaggerDocument, method: HttpMethod, path: string): SwaggerDocument {
+  const nextDoc = cloneDocument(document);
+  const normalizedPath = normalizePath(path);
+  const pathItem = nextDoc.paths?.[normalizedPath];
+  if (!pathItem) return nextDoc;
+
+  delete pathItem[method];
+  if (!Object.keys(pathItem).length) {
+    delete nextDoc.paths?.[normalizedPath];
+  } else {
+    nextDoc.paths = {
+      ...(nextDoc.paths ?? {}),
+      [normalizedPath]: pathItem,
+    };
+  }
+  return nextDoc;
+}
+
+export function openApiStats(document: SwaggerDocument) {
+  return {
+    paths: Object.keys(document.paths ?? {}).length,
+    schemas: Object.keys(document.components?.schemas ?? document.definitions ?? {}).length,
+  };
+}
+
+function buildOperation(config: ManualApiOperationConfig): SwaggerOperation {
+  const bodyFields = config.requestBody?.fields?.filter((field) => field.name) ?? [];
+  const operation: SwaggerOperation = {
+    tags: config.tags?.length ? config.tags : ['手动配置'],
+    summary: config.summary,
+    description: config.description || undefined,
+    operationId: config.operationId || undefined,
+    parameters: (config.parameters ?? []).filter((field) => field.name).map(fieldToParameter),
+    responses: Object.fromEntries((config.responses ?? []).map((response) => [response.status, responseToOpenApi(response)])),
+  };
+
+  if (bodyFields.length) {
+    operation.requestBody = {
+      required: Boolean(config.requestBody?.required),
+      content: {
+        [config.requestBody?.contentType || 'application/json']: {
+          schema: fieldsToObjectSchema(bodyFields),
+        },
+      },
+    };
+  }
+
+  return operation;
+}
+
+function fieldToParameter(field: ManualApiFieldConfig): SwaggerParameter {
+  return {
+    name: field.name,
+    in: field.location === 'body' || !field.location ? 'query' : field.location,
+    required: Boolean(field.required),
+    description: field.description || undefined,
+    schema: fieldToSchema(field),
+  };
+}
+
+function responseToOpenApi(response: ManualApiResponseConfig) {
+  const fields = response.fields?.filter((field) => field.name) ?? [];
+  const value: NonNullable<SwaggerOperation['responses']>[string] = {
+    description: response.description || 'Success',
+  };
+  if (fields.length) {
+    value.content = {
+      [response.contentType || 'application/json']: {
+        schema: fieldsToObjectSchema(fields),
+      },
+    };
+  }
+  return value;
+}
+
+function fieldsToObjectSchema(fields: ManualApiFieldConfig[]): SwaggerSchema {
+  const schema: SwaggerSchema = {
+    type: 'object',
+    properties: {},
+    required: [],
+  };
+
+  fields.forEach((field) => {
+    if (!field.name) return;
+    setSchemaProperty(schema, field.name, fieldToSchema(field), Boolean(field.required));
+  });
+
+  if (!schema.required?.length) delete schema.required;
+  return schema;
+}
+
+function setSchemaProperty(root: SwaggerSchema, path: string, schema: SwaggerSchema, required: boolean) {
+  const parts = path.split('.').map((part) => part.trim()).filter(Boolean);
+  if (!parts.length) return;
+
+  let current = root;
+  parts.forEach((part, index) => {
+    current.properties ??= {};
+    if (index === parts.length - 1) {
+      current.properties[part] = schema;
+      if (required) current.required = [...new Set([...(current.required ?? []), part])];
+      return;
+    }
+
+    const next = current.properties[part] ?? { type: 'object', properties: {}, required: [] };
+    next.type = next.type || 'object';
+    next.properties ??= {};
+    current.properties[part] = next;
+    current = next;
+  });
+}
+
+function fieldToSchema(field: ManualApiFieldConfig): SwaggerSchema {
+  const schema: SwaggerSchema = {
+    type: field.type || 'string',
+    format: field.format || undefined,
+    description: field.description || undefined,
+  };
+  const enumValue = parseEnum(field.enumValue);
+  if (enumValue.length) schema.enum = enumValue;
+  if (field.defaultValue) schema.default = coerceValue(field.defaultValue, schema.type);
+  if (schema.type === 'object') {
+    const children = field.children?.filter((child) => child.name) ?? [];
+    if (children.length) {
+      const childSchema = fieldsToObjectSchema(children);
+      schema.properties = childSchema.properties;
+      schema.required = childSchema.required;
+    }
+  }
+  if (schema.type === 'array') {
+    const children = field.children?.filter((child) => child.name) ?? [];
+    schema.items = children.length ? fieldsToObjectSchema(children) : { type: 'string' };
+  }
+  return schema;
+}
+
+function normalizeResponse(input: unknown): ManualApiResponseConfig {
+  const record = input && typeof input === 'object' ? (input as Record<string, unknown>) : {};
+  return {
+    status: text(record.status) || '200',
+    description: text(record.description) || 'Success',
+    contentType: text(record.contentType) || 'application/json',
+    fields: array(record.fields).map(normalizeField).filter((field) => field.name),
+  };
+}
+
+function normalizeField(input: unknown): ManualApiFieldConfig {
+  const record = input && typeof input === 'object' ? (input as Record<string, unknown>) : {};
+  const location = text(record.location) as ManualApiFieldLocation;
+  return {
+    name: text(record.name),
+    location: ['query', 'path', 'header', 'cookie', 'body'].includes(location) ? location : 'query',
+    required: Boolean(record.required),
+    type: text(record.type) || 'string',
+    format: text(record.format),
+    description: text(record.description),
+    defaultValue: text(record.defaultValue),
+    enumValue: text(record.enumValue),
+    children: array(record.children).map(normalizeField).filter((field) => field.name),
+  };
+}
+
+function stripCliText(value: string) {
+  return value
+    .trim()
+    .replace(/^```(?:json|ya?ml|yaml)?\s*/i, '')
+    .replace(/```$/i, '')
+    .trim();
+}
+
+function splitTags(value: unknown) {
+  if (Array.isArray(value)) return value.map(text).filter(Boolean);
+  return text(value)
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function parseEnum(value?: string) {
+  return (value || '')
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean)
+    .map((item) => coerceValue(item));
+}
+
+function coerceValue(value: string, type?: string): unknown {
+  if (type === 'number' || type === 'integer') {
+    const numeric = Number(value);
+    return Number.isFinite(numeric) ? numeric : value;
+  }
+  if (type === 'boolean') {
+    if (value === 'true') return true;
+    if (value === 'false') return false;
+  }
+  return value;
+}
+
+function normalizePath(value: string) {
+  if (!value) return '';
+  return value.startsWith('/') ? value : `/${value}`;
+}
+
+function text(value: unknown) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function array(value: unknown) {
+  return Array.isArray(value) ? value : [];
+}
+
+function cloneDocument(document: SwaggerDocument): SwaggerDocument {
+  return JSON.parse(JSON.stringify(document || createManualApiDocument())) as SwaggerDocument;
+}