apiskill 0.1.5 → 0.1.6

package/src/CacheSettingsDialog.tsx

@@ -0,0 +1,166 @@
+import { useState } from 'react';
+import { AlertCircle, FolderCog, RotateCcw, Save, X } from 'lucide-react';
+import { CACHE_SETTINGS_API_URL } from './swagger';
+
+export type CacheSettings = {
+  activeCacheDir: string;
+  defaultCacheDir: string;
+  configuredCacheDir: string;
+  builtInCacheDir: string;
+  environmentCacheDir: string;
+  environmentOverride: boolean;
+  effectiveNextCacheDir: string;
+  source: 'environment' | 'config' | 'default';
+  configPath: string;
+  restartRequired: boolean;
+  activeMatchesDefault: boolean;
+};
+
+export function CacheSettingsDialog({
+  settings,
+  onSettingsChange,
+}: {
+  settings?: CacheSettings;
+  onSettingsChange: (settings: CacheSettings) => void;
+}) {
+  const [open, setOpen] = useState(false);
+  const [cacheDir, setCacheDir] = useState('');
+  const [loading, setLoading] = useState(false);
+  const [message, setMessage] = useState('');
+  const [error, setError] = useState('');
+
+  async function openDialog() {
+    setOpen(true);
+    setMessage('');
+    setError('');
+    setLoading(true);
+    try {
+      const next = await loadCacheSettings();
+      onSettingsChange(next);
+      setCacheDir(next.defaultCacheDir);
+    } catch (loadError) {
+      setError(loadError instanceof Error ? loadError.message : '缓存设置读取失败');
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  async function saveSettings(reset = false) {
+    setLoading(true);
+    setMessage('');
+    setError('');
+    try {
+      const response = await fetch(CACHE_SETTINGS_API_URL, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(reset ? { reset: true } : { cacheDir }),
+      });
+      const payload = await response.json();
+      if (!response.ok) throw new Error(payload.error || '缓存设置保存失败');
+      const next = payload as CacheSettings;
+      onSettingsChange(next);
+      setCacheDir(next.defaultCacheDir);
+      setMessage(reset ? '已恢复内置默认地址，现有缓存文件未改动' : '默认缓存地址已保存，现有缓存文件未改动');
+    } catch (saveError) {
+      setError(saveError instanceof Error ? saveError.message : '缓存设置保存失败');
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  return (
+    <>
+      <button className="secondary-button cache-settings-trigger" onClick={openDialog} title="设置接口文档默认缓存地址">
+        <FolderCog size={16} />
+        缓存设置
+      </button>
+
+      {open ? (
+        <div className="modal-backdrop" role="dialog" aria-modal="true" aria-labelledby="cache-settings-title">
+          <div className="cache-settings-dialog">
+            <div className="import-dialog-header">
+              <div>
+                <p className="eyebrow">Cache Settings</p>
+                <h2 id="cache-settings-title">接口文档缓存设置</h2>
+              </div>
+              <button className="icon-secondary-button" onClick={() => setOpen(false)} aria-label="关闭">
+                <X size={17} />
+              </button>
+            </div>
+
+            <div className="cache-settings-body">
+              {error ? <div className="version-message error">{error}</div> : null}
+              {message ? <div className="version-message">{message}</div> : null}
+
+              <div className="cache-location-row">
+                <span>当前会话缓存位置</span>
+                <code>{settings?.activeCacheDir || (loading ? '读取中...' : '-')}</code>
+              </div>
+
+              <label className="cache-settings-field">
+                默认缓存地址
+                <input
+                  value={cacheDir}
+                  onChange={(event) => setCacheDir(event.target.value)}
+                  placeholder="例如 ~/.apiskill/cache"
+                  autoComplete="off"
+                  disabled={loading}
+                />
+              </label>
+
+              <div className="cache-settings-notice">
+                <AlertCircle size={18} />
+                <div>
+                  <strong>修改地址不会移动或删除已有缓存文件</strong>
+                  <p>新的 CLI、MCP 进程会读取该默认地址；Web 端重启后切换。需要保留的版本可在版本管理中使用“更新缓存地址”复制过去。</p>
+                </div>
+              </div>
+
+              {settings?.environmentOverride ? (
+                <div className="cache-settings-notice warning">
+                  <AlertCircle size={18} />
+                  <div>
+                    <strong>环境变量正在覆盖默认设置</strong>
+                    <p>当前 `APISKILL_CACHE_DIR` 为 {settings.environmentCacheDir}。只要该变量存在，重启后仍优先使用它。</p>
+                  </div>
+                </div>
+              ) : null}
+
+              <dl className="cache-settings-details">
+                <div>
+                  <dt>内置默认地址</dt>
+                  <dd>{settings?.builtInCacheDir || '-'}</dd>
+                </div>
+                <div>
+                  <dt>配置文件</dt>
+                  <dd>{settings?.configPath || '-'}</dd>
+                </div>
+              </dl>
+            </div>
+
+            <div className="import-dialog-actions cache-settings-actions">
+              <button className="secondary-button" onClick={() => void saveSettings(true)} disabled={loading}>
+                <RotateCcw size={16} />
+                恢复默认
+              </button>
+              <div>
+                <button className="secondary-button" onClick={() => setOpen(false)} disabled={loading}>取消</button>
+                <button className="primary-button" onClick={() => void saveSettings(false)} disabled={loading || !cacheDir.trim()}>
+                  <Save size={16} />
+                  {loading ? '保存中' : '保存设置'}
+                </button>
+              </div>
+            </div>
+          </div>
+        </div>
+      ) : null}
+    </>
+  );
+}
+
+export async function loadCacheSettings(): Promise<CacheSettings> {
+  const response = await fetch(CACHE_SETTINGS_API_URL, { cache: 'no-store' });
+  const payload = await response.json();
+  if (!response.ok) throw new Error(payload.error || '缓存设置读取失败');
+  return payload as CacheSettings;
+}

package/src/DocumentVersionManager.tsx

@@ -1,5 +1,6 @@
 import { useEffect, useMemo, useState } from 'react';
-import { Check, Download, Pencil, RefreshCcw, Server, Trash2, X } from 'lucide-react';
+import { Check, Download, FolderSync, Pencil, RefreshCcw, Server, Trash2, X } from 'lucide-react';
+import type { CacheSettings } from './CacheSettingsDialog';
 import { VERSION_EXPORT_API_URL } from './swagger';
 
 export type DocumentVersionMeta = {
@@ -14,6 +15,7 @@ export type DocumentVersionMeta = {
   schemas?: number;
   environmentName?: string;
   environmentBaseUrl?: string;
+  savedPath?: string;
 };
 
 export function DocumentVersionManager({
@@ -25,6 +27,8 @@ export function DocumentVersionManager({
   onPrepareUpdate,
   onUpdateEnvironment,
   onDelete,
+  cacheSettings,
+  onSyncCache,
 }: {
   versions: DocumentVersionMeta[];
   selectedVersionId: string;
@@ -34,6 +38,12 @@ export function DocumentVersionManager({
   onPrepareUpdate: (version: DocumentVersionMeta) => Promise<void> | void;
   onUpdateEnvironment: (versionId: string, environmentName: string, environmentBaseUrl: string) => Promise<void>;
   onDelete: (versionId: string) => Promise<void>;
+  cacheSettings?: CacheSettings;
+  onSyncCache: (versionId: string) => Promise<{
+    status: 'synced' | 'already-current';
+    targetCacheDir: string;
+    targetDocumentPath: string;
+  }>;
 }) {
   const [open, setOpen] = useState(false);
   const [editingVersionId, setEditingVersionId] = useState('');
@@ -118,6 +128,38 @@ export function DocumentVersionManager({
     document.body.removeChild(anchor);
   }
 
+  async function syncVersionCache(version: DocumentVersionMeta) {
+    const versionId = version.versionId;
+    if (!versionId) return;
+    if (!cacheSettings) {
+      setMessage('缓存设置尚未读取，请稍后重试');
+      return;
+    }
+
+    const sourceLocation = version.savedPath || cacheSettings.activeCacheDir;
+    const targetLocation = cacheSettings.defaultCacheDir;
+    if (cacheSettings.activeMatchesDefault) {
+      window.alert(`当前缓存位置：\n${sourceLocation}\n\n该版本已位于默认缓存地址：\n${targetLocation}`);
+      return;
+    }
+
+    const confirmed = window.confirm(
+      `当前缓存位置：\n${sourceLocation}\n\n默认缓存地址：\n${targetLocation}\n\n确认将该文档版本复制到默认缓存地址吗？源文件不会被移动或删除；目标中同版本内容将被更新。`,
+    );
+    if (!confirmed) return;
+
+    setBusyVersionId(versionId);
+    setMessage('');
+    try {
+      const result = await onSyncCache(versionId);
+      setMessage(result.status === 'already-current' ? '该版本已位于默认缓存地址' : `已同步到 ${result.targetDocumentPath}`);
+    } catch (error) {
+      setMessage(error instanceof Error ? error.message : '更新缓存地址失败');
+    } finally {
+      setBusyVersionId('');
+    }
+  }
+
   return (
     <div className="version-manager">
       <button className="version-manager-trigger" onClick={() => setOpen(true)} disabled={disabled || !versions.length}>
@@ -231,6 +273,10 @@ export function DocumentVersionManager({
                           <Download size={15} />
                           导出
                         </button>
+                        <button className="secondary-button" onClick={() => void syncVersionCache(version)} disabled={busy || !versionId}>
+                          <FolderSync size={15} />
+                          更新缓存地址
+                        </button>
                         <button className="danger-button" onClick={() => deleteVersion(version)} disabled={busy || !versionId}>
                           <Trash2 size={15} />
                           删除

package/src/styles.css

@@ -75,7 +75,10 @@ p {
 .topbar-actions {
   display: flex;
   align-items: center;
+  justify-content: flex-end;
+  flex-wrap: wrap;
   gap: 14px;
+  min-width: 0;
 }
 
 .version-switcher {
@@ -1542,6 +1545,110 @@ td code {
   box-shadow: 0 18px 60px rgba(18, 25, 35, 0.22);
 }
 
+.cache-settings-dialog {
+  width: min(680px, 100%);
+  max-height: calc(100vh - 40px);
+  overflow: auto;
+  border: 1px solid #d7dde4;
+  border-radius: 8px;
+  background: #fff;
+  box-shadow: 0 18px 60px rgba(18, 25, 35, 0.22);
+}
+
+.cache-settings-body {
+  display: grid;
+  gap: 16px;
+  padding: 18px 20px;
+}
+
+.cache-location-row,
+.cache-settings-details > div {
+  display: grid;
+  grid-template-columns: 150px minmax(0, 1fr);
+  align-items: start;
+  gap: 14px;
+}
+
+.cache-location-row > span,
+.cache-settings-details dt {
+  color: #657181;
+  font-size: 12px;
+  font-weight: 800;
+}
+
+.cache-location-row code,
+.cache-settings-details dd {
+  min-width: 0;
+  margin: 0;
+  overflow-wrap: anywhere;
+  color: #1d2a36;
+  font-size: 12px;
+}
+
+.cache-settings-field {
+  display: grid;
+  gap: 7px;
+  color: #334152;
+  font-size: 12px;
+  font-weight: 800;
+}
+
+.cache-settings-field input {
+  width: 100%;
+  min-height: 40px;
+  padding: 0 11px;
+  border: 1px solid #bdc8d4;
+  border-radius: 6px;
+  outline: 0;
+  color: #15202c;
+  background: #fff;
+}
+
+.cache-settings-field input:focus {
+  border-color: #1b6b65;
+  box-shadow: 0 0 0 3px rgba(27, 107, 101, 0.12);
+}
+
+.cache-settings-notice {
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr);
+  gap: 10px;
+  padding: 12px 0;
+  border-block: 1px solid #dbe7e4;
+  color: #285c55;
+}
+
+.cache-settings-notice.warning {
+  border-color: #ead9ad;
+  color: #765b16;
+}
+
+.cache-settings-notice strong {
+  font-size: 13px;
+}
+
+.cache-settings-notice p {
+  margin: 4px 0 0;
+  color: #657181;
+  font-size: 12px;
+  line-height: 1.55;
+}
+
+.cache-settings-details {
+  display: grid;
+  gap: 9px;
+  margin: 0;
+}
+
+.cache-settings-actions {
+  justify-content: space-between;
+}
+
+.cache-settings-actions > div {
+  display: flex;
+  gap: 8px;
+}
+
 .api-config-dialog {
   width: 80vw;
   min-width: 1000px;
@@ -2260,6 +2367,18 @@ td code {
     gap: 8px;
   }
 
+  .cache-location-row,
+  .cache-settings-details > div {
+    grid-template-columns: 1fr;
+    gap: 5px;
+  }
+
+  .cache-settings-actions,
+  .cache-settings-actions > div {
+    display: grid;
+    width: 100%;
+  }
+
   .endpoint-title-line {
     align-items: flex-start;
     flex-direction: column;

package/src/swagger.ts

@@ -19,6 +19,8 @@ export const VERSION_SELECT_API_URL = '/api/openapi/version-select';
 export const VERSION_META_API_URL = '/api/openapi/version-meta';
 export const VERSION_DELETE_API_URL = '/api/openapi/version-delete';
 export const VERSION_EXPORT_API_URL = '/api/openapi/version-export';
+export const VERSION_SYNC_CACHE_API_URL = '/api/openapi/version-sync-cache';
+export const CACHE_SETTINGS_API_URL = '/api/cache-settings';
 export const MOCK_START_API_URL = '/api/mock/start';
 export const MOCK_STATUS_API_URL = '/api/mock/status';
 export const MOCK_STOP_API_URL = '/api/mock/stop';

package/vite.config.ts

@@ -15,7 +15,7 @@ import {
   openApiStats,
 } from './src/manualApiConfig';
 import { startMockServer } from './scripts/lib/mock-server.mjs';
-import { getDefaultCacheDir } from './scripts/lib/cache-paths.mjs';
+import { getCacheSettings, getDefaultCacheDir, resetDefaultCacheDir, setDefaultCacheDir } from './scripts/lib/cache-paths.mjs';
 
 const appRootDir = process.env.APISKILL_ROOT || process.cwd();
 const cacheDir = getDefaultCacheDir();
@@ -91,6 +91,26 @@ function openapiImportPlugin() {
         }
       });
 
+      server.middlewares.use('/api/cache-settings', async (req, res) => {
+        try {
+          if (req.method === 'GET') {
+            sendJson(res, 200, webCacheSettings());
+            return;
+          }
+          if (req.method !== 'POST') {
+            sendJson(res, 405, { error: 'Method Not Allowed' });
+            return;
+          }
+
+          const body = (await readJsonBody(req)) as { cacheDir?: unknown; reset?: boolean };
+          if (body.reset) await resetDefaultCacheDir();
+          else await setDefaultCacheDir(requiredText(body.cacheDir, '请输入默认缓存地址'));
+          sendJson(res, 200, webCacheSettings());
+        } catch (error) {
+          sendJson(res, 400, { error: error instanceof Error ? error.message : 'Save cache settings failed' });
+        }
+      });
+
       server.middlewares.use('/api/openapi/version-select', async (req, res) => {
         if (req.method !== 'POST') {
           sendJson(res, 405, { error: 'Method Not Allowed' });
@@ -197,6 +217,66 @@ function openapiImportPlugin() {
         }
       });
 
+      server.middlewares.use('/api/openapi/version-sync-cache', 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 settings = getCacheSettings();
+          const targetCacheDir = settings.defaultCacheDir;
+          const payload = await readCachedDocument(versionId);
+          const sourceDocumentPath = typeof payload.meta?.savedPath === 'string'
+            ? payload.meta.savedPath
+            : resolve(versionsDir, `${versionId}.json`);
+
+          if (resolve(targetCacheDir) === resolve(cacheDir)) {
+            sendJson(res, 200, {
+              status: 'already-current',
+              versionId,
+              sourceCacheDir: cacheDir,
+              sourceDocumentPath,
+              targetCacheDir,
+              targetDocumentPath: sourceDocumentPath,
+            });
+            return;
+          }
+
+          const targetVersionsDir = resolve(targetCacheDir, 'versions');
+          const targetDocumentPath = resolve(targetVersionsDir, `${versionId}.json`);
+          const targetMetaPath = resolve(targetVersionsDir, `${versionId}.meta.json`);
+          const syncedAt = new Date().toISOString();
+          const targetMeta = {
+            ...(payload.meta ?? {}),
+            versionId,
+            savedFile: basename(targetDocumentPath),
+            savedPath: targetDocumentPath,
+            cacheSyncedAt: syncedAt,
+            cacheSyncedFrom: sourceDocumentPath,
+          };
+
+          await mkdir(targetVersionsDir, { recursive: true });
+          await writeFile(targetDocumentPath, JSON.stringify(payload.document, null, 2));
+          await writeFile(targetMetaPath, JSON.stringify(targetMeta, null, 2));
+          await writeFile(resolve(targetCacheDir, 'latest-import.json'), JSON.stringify(targetMeta, null, 2));
+          sendJson(res, 200, {
+            status: 'synced',
+            versionId,
+            sourceCacheDir: cacheDir,
+            sourceDocumentPath,
+            targetCacheDir,
+            targetDocumentPath,
+            syncedAt,
+          });
+        } catch (error) {
+          sendJson(res, 400, { error: error instanceof Error ? error.message : 'Sync version cache failed' });
+        }
+      });
+
       server.middlewares.use('/api/openapi/auth-check', async (req, res) => {
         if (req.method !== 'POST') {
           sendJson(res, 405, { error: 'Method Not Allowed' });
@@ -536,6 +616,17 @@ function openapiImportPlugin() {
   };
 }
 
+function webCacheSettings() {
+  const settings = getCacheSettings();
+  return {
+    ...settings,
+    activeCacheDir: cacheDir,
+    effectiveNextCacheDir: settings.cacheDir,
+    restartRequired: resolve(cacheDir) !== resolve(settings.cacheDir),
+    activeMatchesDefault: resolve(cacheDir) === resolve(settings.defaultCacheDir),
+  };
+}
+
 async function readCachedDocument(versionId?: string) {
   if (versionId) {
     assertSafeVersionId(versionId);