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

apps/web/src/api.test.ts

@@ -1,8 +1,10 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import {
+  createResponse,
   deleteOIDCBrowserSession,
   GatewayApiError,
   gatewayErrorMessage,
+  getAPITask,
   getCurrentUser,
   getOpsManagementSkillMetadata,
   OIDC_BROWSER_SESSION_CREDENTIAL,
@@ -96,3 +98,39 @@ describe('Public Agent resources', () => {
     expect(new Headers(init.headers).has('Authorization')).toBe(false);
   });
 });
+
+describe('API documentation runner transports', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('runs Responses against the public OpenAI-compatible endpoint', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(new Response(JSON.stringify({ id: 'resp-test', object: 'response' }), {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' },
+    }));
+    vi.stubGlobal('fetch', fetchMock);
+
+    await createResponse('sk-test', { model: 'gpt-test', input: 'hello', store: true, stream: false });
+
+    const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(url).toContain('/v1/responses');
+    expect(init.method).toBe('POST');
+    expect(new Headers(init.headers).get('Authorization')).toBe('Bearer sk-test');
+    expect(JSON.parse(String(init.body))).toMatchObject({ model: 'gpt-test', input: 'hello', store: true, stream: false });
+  });
+
+  it('retrieves a task from the documented API path', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(new Response(JSON.stringify({ id: 'task-123', status: 'running' }), {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' },
+    }));
+    vi.stubGlobal('fetch', fetchMock);
+
+    await getAPITask('sk-test', 'task-123');
+
+    const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(url).toContain('/api/v1/tasks/task-123');
+    expect(init.method).toBe('GET');
+  });
+});