| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324 |
- /** Python 工具服务的 HTTP 客户端(BFF 与工具层之间唯一的通信通道)。 */
- import { settings } from '../config.js';
- import { HttpError, logger } from '../util/common.js';
- const log = logger('tools-client');
- export interface ToolServiceHealth {
- ok: boolean;
- service: string;
- version: string;
- data_dir: string;
- }
- export interface WorkspaceInfo {
- id: string;
- name: string;
- description: string;
- created_at: string;
- object_count?: number;
- }
- export interface TableInfo {
- name: string;
- sqlite_name: string;
- rows: number;
- columns: string[];
- }
- export interface ObjectInfo {
- id: string;
- workspace_id: string;
- name: string;
- kind: 'raw' | 'stat';
- media_type: string;
- path: string;
- sha256: string;
- bytes: number;
- rows: number;
- columns: string[];
- producer: string;
- parents: string[];
- meta: Record<string, any>;
- created_at: string;
- tables: TableInfo[];
- }
- export interface RunInfo {
- id: string;
- object_id: string | null;
- input_object: string;
- status: 'queued' | 'running' | 'succeeded' | 'failed';
- operation: string;
- progress: number;
- message: string;
- error: string;
- started_at: string;
- finished_at: string | null;
- params: Record<string, unknown>;
- }
- export interface DataReadPayload {
- object_id: string;
- table?: string;
- columns?: string[];
- filters?: Array<{ column: string; op?: string; value: unknown }>;
- order_by?: Array<{ column: string; dir?: string }>;
- limit?: number;
- offset?: number;
- aggregate?: Record<string, unknown>;
- /** 由工具层传入,让 Python 台账用同一个 call_id 记录 */
- call_id?: string;
- session_id?: string;
- }
- export class ToolsClient {
- constructor(
- readonly baseUrl: string = settings.toolsUrl,
- private readonly defaultTimeoutMs = 30_000,
- ) {}
- async request<T>(pathname: string, init: RequestInit = {}, timeoutMs = this.defaultTimeoutMs): Promise<T> {
- const url = `${this.baseUrl}${pathname}`;
- const started = Date.now();
- let response: Response;
- try {
- response = await fetch(url, {
- ...init,
- signal: AbortSignal.timeout(timeoutMs),
- });
- } catch (error) {
- const message = error instanceof Error ? error.message : String(error);
- throw new HttpError(502, `工具服务不可用(${url}):${message}`, 'TOOLS_UNAVAILABLE');
- }
- const elapsed = Date.now() - started;
- if (elapsed > 5000) log.warn(`工具服务调用较慢: ${pathname} ${elapsed}ms`);
- if (!response.ok) {
- const text = await response.text().catch(() => '');
- let detail: unknown = text.slice(0, 800);
- try {
- const parsed = JSON.parse(text) as { detail?: unknown };
- if (parsed.detail !== undefined) detail = parsed.detail;
- } catch {
- /* 非 JSON 错误体,保留原文 */
- }
- throw new HttpError(response.status, typeof detail === 'string' ? detail : JSON.stringify(detail), 'TOOLS_ERROR', detail);
- }
- if (response.status === 204) return undefined as T;
- const text = await response.text();
- if (!text) return undefined as T;
- try {
- return JSON.parse(text) as T;
- } catch (error) {
- throw new HttpError(502, `工具服务返回了非 JSON 内容: ${text.slice(0, 200)}`, 'TOOLS_BAD_RESPONSE');
- }
- }
- // ---------------------------------------------------------------- 基础
- health(): Promise<ToolServiceHealth> {
- return this.request<ToolServiceHealth>('/health', {}, 5000);
- }
- meta(): Promise<Record<string, unknown>> {
- return this.request('/meta', {}, 5000);
- }
- // ---------------------------------------------------------------- 工作区
- listWorkspaces(): Promise<{ items: WorkspaceInfo[] }> {
- return this.request('/workspaces');
- }
- createWorkspace(name: string, description = ''): Promise<WorkspaceInfo> {
- return this.request('/workspaces', {
- method: 'POST',
- headers: { 'Content-Type': 'application/json' },
- body: JSON.stringify({ name, description }),
- });
- }
- deleteWorkspace(id: string): Promise<{ ok: boolean }> {
- return this.request(`/workspaces/${encodeURIComponent(id)}`, { method: 'DELETE' });
- }
- // ---------------------------------------------------------------- 对象
- listObjects(workspaceId: string, kind?: string): Promise<{ items: ObjectInfo[] }> {
- const query = kind ? `?kind=${encodeURIComponent(kind)}` : '';
- return this.request(`/workspaces/${encodeURIComponent(workspaceId)}/objects${query}`);
- }
- getObject(objectId: string): Promise<ObjectInfo> {
- return this.request(`/objects/${encodeURIComponent(objectId)}`);
- }
- deleteObject(objectId: string): Promise<{ ok: boolean }> {
- return this.request(`/objects/${encodeURIComponent(objectId)}`, { method: 'DELETE' });
- }
- async uploadObject(workspaceId: string, filename: string, bytes: Uint8Array, contentType = 'application/octet-stream'): Promise<ObjectInfo> {
- const form = new FormData();
- // 用 fetch 的 FormData:Blob 的类型声明在 Node 与 DOM 之间不一致,这里显式收敛
- const blob = new Blob([bytes as unknown as ArrayBuffer], { type: contentType });
- form.append('file', blob, filename);
- return this.request(
- `/workspaces/${encodeURIComponent(workspaceId)}/objects`,
- { method: 'POST', body: form },
- 120_000,
- );
- }
- preview(
- objectId: string,
- table = 'raw',
- limit = 20,
- offset = 0,
- ): Promise<{
- columns: string[];
- rows: unknown[];
- row_indexes: number[];
- row_hashes: string[];
- offset: number;
- limit: number;
- total: number;
- }> {
- const query = new URLSearchParams({ table, limit: String(limit), offset: String(offset) });
- return this.request(`/objects/${encodeURIComponent(objectId)}/preview?${query}`);
- }
- /** 按行号取一行:溯源 chip 点开详情时用(原文 + 行哈希 + 行级血缘)。 */
- row(
- objectId: string,
- table: string,
- rowIndex: number,
- ): Promise<{
- object_id: string;
- table: string;
- row_index: number;
- row_hash: string;
- values: Record<string, unknown>;
- lineage: Record<string, unknown> | null;
- }> {
- const query = new URLSearchParams({ table, row: String(rowIndex) });
- return this.request(`/objects/${encodeURIComponent(objectId)}/row?${query}`);
- }
- lineage(objectId: string, table?: string, row?: number): Promise<Record<string, unknown>> {
- const query = new URLSearchParams();
- if (table) query.set('table', table);
- if (row !== undefined) query.set('row', String(row));
- const suffix = query.toString() ? `?${query}` : '';
- return this.request(`/objects/${encodeURIComponent(objectId)}/lineage${suffix}`);
- }
- /** 下载对象内的文件(透传流,BFF 直接转发给浏览器)。 */
- async download(objectId: string, name: string): Promise<Response> {
- const query = new URLSearchParams({ name });
- const response = await fetch(`${this.baseUrl}/objects/${encodeURIComponent(objectId)}/file?${query}`, {
- signal: AbortSignal.timeout(120_000),
- });
- if (!response.ok) {
- throw new HttpError(response.status, `下载失败: ${name}`, 'DOWNLOAD_FAILED');
- }
- return response;
- }
- // ---------------------------------------------------------------- 处理任务
- createRun(payload: {
- workspace_id: string;
- input_object_id: string;
- operation?: string;
- options?: Record<string, unknown>;
- output_name?: string;
- }): Promise<RunInfo> {
- return this.request('/runs', {
- method: 'POST',
- headers: { 'Content-Type': 'application/json' },
- body: JSON.stringify(payload),
- }, 30_000);
- }
- getRun(runId: string): Promise<RunInfo> {
- return this.request(`/runs/${encodeURIComponent(runId)}`, {}, 10_000);
- }
- listRuns(limit = 20): Promise<{ items: RunInfo[] }> {
- return this.request(`/runs?limit=${limit}`);
- }
- /** 同步执行(Agent 工具用,允许长时间)。 */
- processCustoms(payload: {
- workspace_id: string;
- input_object_id: string;
- operation?: string;
- params?: Record<string, unknown>;
- output_filename?: string;
- call_id?: string;
- session_id?: string;
- }): Promise<{
- run_id: string;
- object_id: string;
- name: string;
- sheets: TableInfo[];
- lineage: Record<string, unknown>;
- stats: Record<string, unknown>;
- warnings: string[];
- files: string[];
- }> {
- return this.request('/tools/customs_process', {
- method: 'POST',
- headers: { 'Content-Type': 'application/json' },
- body: JSON.stringify(payload),
- }, 1_800_000);
- }
- // ---------------------------------------------------------------- 工具
- dataRead(payload: DataReadPayload): Promise<{
- object_id: string;
- table: string;
- columns: string[];
- rows: Array<{ values: Record<string, unknown>; _trace: Record<string, unknown> }>;
- total: number;
- offset: number;
- limit: number;
- exhausted: boolean;
- aggregate?: boolean;
- }> {
- return this.request('/tools/data_read', {
- method: 'POST',
- headers: { 'Content-Type': 'application/json' },
- body: JSON.stringify(payload),
- }, 120_000);
- }
- calculate(payload: {
- op: string;
- inputs?: Array<Record<string, unknown>>;
- expression?: string;
- session_id?: string;
- label?: string;
- }): Promise<Record<string, unknown>> {
- return this.request('/tools/calculator', {
- method: 'POST',
- headers: { 'Content-Type': 'application/json' },
- body: JSON.stringify(payload),
- }, 30_000);
- }
- // ---------------------------------------------------------------- 台账
- ledgerStats(): Promise<Record<string, unknown>> {
- return this.request('/ledger/stats');
- }
- ledgerCalls(sessionId: string): Promise<{ items: Array<Record<string, unknown>> }> {
- return this.request(`/ledger/calls?session_id=${encodeURIComponent(sessionId)}`);
- }
- ledgerValue(value: string, sessionId: string): Promise<{ items: Array<Record<string, unknown>> }> {
- return this.request(`/ledger/value?value=${encodeURIComponent(value)}&session_id=${encodeURIComponent(sessionId)}`);
- }
- ledgerCall(callId: string): Promise<Record<string, unknown>> {
- return this.request(`/ledger/call/${encodeURIComponent(callId)}`);
- }
- }
- export const toolsClient = new ToolsClient();
|