feat(web): 完善 API 文档与异步任务说明

2026-07-17 15:42:46 +08:00
parent 2d6c16fec0
commit cc3bbeccc2
9 changed files with 1182 additions and 101 deletions
@@ -43,11 +43,19 @@ const adminPaths: Record<AdminSection, string> = {
 };

 const docsPaths: Record<ApiDocSection, string> = {
+  guideBaseUrl: '/docs/auth',
+  guideWebhook: '/docs/webhook',
+  guideErrors: '/docs/errors',
+  guideTesting: '/docs/testing',
  chat: '/docs/chat',
+  responses: '/docs/responses',
  embeddings: '/docs/embeddings',
  reranks: '/docs/reranks',
  imageGeneration: '/docs/images/generations',
  imageEdit: '/docs/images/edits',
+  videoGeneration: '/docs/videos/generations',
+  asyncMode: '/docs/async',
+  taskRetrieve: '/docs/tasks/retrieve',
  pricing: '/docs/pricing',
  files: '/docs/files',
 };
@@ -63,8 +71,9 @@ const adminSections = reverseMap(adminPaths);
 const docsSections = reverseMap(docsPaths);
 const playgroundSections = reverseMap(playgroundPaths);

-export function parseAppRoute(input = `${window.location.pathname}${window.location.search}`): AppRouteState {
-  const url = new URL(input, window.location.origin);
+export function parseAppRoute(input = currentLocationPath()): AppRouteState {
+  const origin = typeof window === 'undefined' ? 'http://localhost' : window.location.origin;
+  const url = new URL(input, origin);
  const path = normalizePath(url.pathname);
  const workspaceTaskQuery = parseWorkspaceTaskQuery(url.searchParams);
  if (path === '/') return { ...defaultRouteState };
@@ -84,6 +93,11 @@ export function parseAppRoute(input = `${window.location.pathname}${window.locat
  return { ...defaultRouteState };
 }

+function currentLocationPath() {
+  if (typeof window === 'undefined') return '/';
+  return `${window.location.pathname}${window.location.search}`;
+}
+
 export function pathForPage(page: PageKey, route: AppRouteState): string {
  if (page === 'playground') return pathForPlaygroundMode(route.playgroundMode);
  if (page === 'models') return '/models';
@@ -135,11 +149,14 @@ function parseAdminSection(path: string): AdminSection {

 function parseDocSection(path: string): ApiDocSection {
  if (path === '/docs') return 'chat';
+  if (path === '/docs/playground') return 'guideTesting';
  if (path === '/docs/api/chat') return 'chat';
+  if (path === '/docs/api/responses') return 'responses';
  if (path === '/docs/api/embeddings') return 'embeddings';
  if (path === '/docs/api/reranks') return 'reranks';
  if (path === '/docs/api/media') return 'imageGeneration';
-  if (path === '/docs/playground') return 'chat';
+  if (path === '/docs/api/videos') return 'videoGeneration';
+  if (path === '/docs/api/tasks') return 'taskRetrieve';
  return docsSections[path] ?? 'chat';
 }