client.ts 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324
  1. /** Python 工具服务的 HTTP 客户端(BFF 与工具层之间唯一的通信通道)。 */
  2. import { settings } from '../config.js';
  3. import { HttpError, logger } from '../util/common.js';
  4. const log = logger('tools-client');
  5. export interface ToolServiceHealth {
  6. ok: boolean;
  7. service: string;
  8. version: string;
  9. data_dir: string;
  10. }
  11. export interface WorkspaceInfo {
  12. id: string;
  13. name: string;
  14. description: string;
  15. created_at: string;
  16. object_count?: number;
  17. }
  18. export interface TableInfo {
  19. name: string;
  20. sqlite_name: string;
  21. rows: number;
  22. columns: string[];
  23. }
  24. export interface ObjectInfo {
  25. id: string;
  26. workspace_id: string;
  27. name: string;
  28. kind: 'raw' | 'stat';
  29. media_type: string;
  30. path: string;
  31. sha256: string;
  32. bytes: number;
  33. rows: number;
  34. columns: string[];
  35. producer: string;
  36. parents: string[];
  37. meta: Record<string, any>;
  38. created_at: string;
  39. tables: TableInfo[];
  40. }
  41. export interface RunInfo {
  42. id: string;
  43. object_id: string | null;
  44. input_object: string;
  45. status: 'queued' | 'running' | 'succeeded' | 'failed';
  46. operation: string;
  47. progress: number;
  48. message: string;
  49. error: string;
  50. started_at: string;
  51. finished_at: string | null;
  52. params: Record<string, unknown>;
  53. }
  54. export interface DataReadPayload {
  55. object_id: string;
  56. table?: string;
  57. columns?: string[];
  58. filters?: Array<{ column: string; op?: string; value: unknown }>;
  59. order_by?: Array<{ column: string; dir?: string }>;
  60. limit?: number;
  61. offset?: number;
  62. aggregate?: Record<string, unknown>;
  63. /** 由工具层传入,让 Python 台账用同一个 call_id 记录 */
  64. call_id?: string;
  65. session_id?: string;
  66. }
  67. export class ToolsClient {
  68. constructor(
  69. readonly baseUrl: string = settings.toolsUrl,
  70. private readonly defaultTimeoutMs = 30_000,
  71. ) {}
  72. async request<T>(pathname: string, init: RequestInit = {}, timeoutMs = this.defaultTimeoutMs): Promise<T> {
  73. const url = `${this.baseUrl}${pathname}`;
  74. const started = Date.now();
  75. let response: Response;
  76. try {
  77. response = await fetch(url, {
  78. ...init,
  79. signal: AbortSignal.timeout(timeoutMs),
  80. });
  81. } catch (error) {
  82. const message = error instanceof Error ? error.message : String(error);
  83. throw new HttpError(502, `工具服务不可用(${url}):${message}`, 'TOOLS_UNAVAILABLE');
  84. }
  85. const elapsed = Date.now() - started;
  86. if (elapsed > 5000) log.warn(`工具服务调用较慢: ${pathname} ${elapsed}ms`);
  87. if (!response.ok) {
  88. const text = await response.text().catch(() => '');
  89. let detail: unknown = text.slice(0, 800);
  90. try {
  91. const parsed = JSON.parse(text) as { detail?: unknown };
  92. if (parsed.detail !== undefined) detail = parsed.detail;
  93. } catch {
  94. /* 非 JSON 错误体,保留原文 */
  95. }
  96. throw new HttpError(response.status, typeof detail === 'string' ? detail : JSON.stringify(detail), 'TOOLS_ERROR', detail);
  97. }
  98. if (response.status === 204) return undefined as T;
  99. const text = await response.text();
  100. if (!text) return undefined as T;
  101. try {
  102. return JSON.parse(text) as T;
  103. } catch (error) {
  104. throw new HttpError(502, `工具服务返回了非 JSON 内容: ${text.slice(0, 200)}`, 'TOOLS_BAD_RESPONSE');
  105. }
  106. }
  107. // ---------------------------------------------------------------- 基础
  108. health(): Promise<ToolServiceHealth> {
  109. return this.request<ToolServiceHealth>('/health', {}, 5000);
  110. }
  111. meta(): Promise<Record<string, unknown>> {
  112. return this.request('/meta', {}, 5000);
  113. }
  114. // ---------------------------------------------------------------- 工作区
  115. listWorkspaces(): Promise<{ items: WorkspaceInfo[] }> {
  116. return this.request('/workspaces');
  117. }
  118. createWorkspace(name: string, description = ''): Promise<WorkspaceInfo> {
  119. return this.request('/workspaces', {
  120. method: 'POST',
  121. headers: { 'Content-Type': 'application/json' },
  122. body: JSON.stringify({ name, description }),
  123. });
  124. }
  125. deleteWorkspace(id: string): Promise<{ ok: boolean }> {
  126. return this.request(`/workspaces/${encodeURIComponent(id)}`, { method: 'DELETE' });
  127. }
  128. // ---------------------------------------------------------------- 对象
  129. listObjects(workspaceId: string, kind?: string): Promise<{ items: ObjectInfo[] }> {
  130. const query = kind ? `?kind=${encodeURIComponent(kind)}` : '';
  131. return this.request(`/workspaces/${encodeURIComponent(workspaceId)}/objects${query}`);
  132. }
  133. getObject(objectId: string): Promise<ObjectInfo> {
  134. return this.request(`/objects/${encodeURIComponent(objectId)}`);
  135. }
  136. deleteObject(objectId: string): Promise<{ ok: boolean }> {
  137. return this.request(`/objects/${encodeURIComponent(objectId)}`, { method: 'DELETE' });
  138. }
  139. async uploadObject(workspaceId: string, filename: string, bytes: Uint8Array, contentType = 'application/octet-stream'): Promise<ObjectInfo> {
  140. const form = new FormData();
  141. // 用 fetch 的 FormData:Blob 的类型声明在 Node 与 DOM 之间不一致,这里显式收敛
  142. const blob = new Blob([bytes as unknown as ArrayBuffer], { type: contentType });
  143. form.append('file', blob, filename);
  144. return this.request(
  145. `/workspaces/${encodeURIComponent(workspaceId)}/objects`,
  146. { method: 'POST', body: form },
  147. 120_000,
  148. );
  149. }
  150. preview(
  151. objectId: string,
  152. table = 'raw',
  153. limit = 20,
  154. offset = 0,
  155. ): Promise<{
  156. columns: string[];
  157. rows: unknown[];
  158. row_indexes: number[];
  159. row_hashes: string[];
  160. offset: number;
  161. limit: number;
  162. total: number;
  163. }> {
  164. const query = new URLSearchParams({ table, limit: String(limit), offset: String(offset) });
  165. return this.request(`/objects/${encodeURIComponent(objectId)}/preview?${query}`);
  166. }
  167. /** 按行号取一行:溯源 chip 点开详情时用(原文 + 行哈希 + 行级血缘)。 */
  168. row(
  169. objectId: string,
  170. table: string,
  171. rowIndex: number,
  172. ): Promise<{
  173. object_id: string;
  174. table: string;
  175. row_index: number;
  176. row_hash: string;
  177. values: Record<string, unknown>;
  178. lineage: Record<string, unknown> | null;
  179. }> {
  180. const query = new URLSearchParams({ table, row: String(rowIndex) });
  181. return this.request(`/objects/${encodeURIComponent(objectId)}/row?${query}`);
  182. }
  183. lineage(objectId: string, table?: string, row?: number): Promise<Record<string, unknown>> {
  184. const query = new URLSearchParams();
  185. if (table) query.set('table', table);
  186. if (row !== undefined) query.set('row', String(row));
  187. const suffix = query.toString() ? `?${query}` : '';
  188. return this.request(`/objects/${encodeURIComponent(objectId)}/lineage${suffix}`);
  189. }
  190. /** 下载对象内的文件(透传流,BFF 直接转发给浏览器)。 */
  191. async download(objectId: string, name: string): Promise<Response> {
  192. const query = new URLSearchParams({ name });
  193. const response = await fetch(`${this.baseUrl}/objects/${encodeURIComponent(objectId)}/file?${query}`, {
  194. signal: AbortSignal.timeout(120_000),
  195. });
  196. if (!response.ok) {
  197. throw new HttpError(response.status, `下载失败: ${name}`, 'DOWNLOAD_FAILED');
  198. }
  199. return response;
  200. }
  201. // ---------------------------------------------------------------- 处理任务
  202. createRun(payload: {
  203. workspace_id: string;
  204. input_object_id: string;
  205. operation?: string;
  206. options?: Record<string, unknown>;
  207. output_name?: string;
  208. }): Promise<RunInfo> {
  209. return this.request('/runs', {
  210. method: 'POST',
  211. headers: { 'Content-Type': 'application/json' },
  212. body: JSON.stringify(payload),
  213. }, 30_000);
  214. }
  215. getRun(runId: string): Promise<RunInfo> {
  216. return this.request(`/runs/${encodeURIComponent(runId)}`, {}, 10_000);
  217. }
  218. listRuns(limit = 20): Promise<{ items: RunInfo[] }> {
  219. return this.request(`/runs?limit=${limit}`);
  220. }
  221. /** 同步执行(Agent 工具用,允许长时间)。 */
  222. processCustoms(payload: {
  223. workspace_id: string;
  224. input_object_id: string;
  225. operation?: string;
  226. params?: Record<string, unknown>;
  227. output_filename?: string;
  228. call_id?: string;
  229. session_id?: string;
  230. }): Promise<{
  231. run_id: string;
  232. object_id: string;
  233. name: string;
  234. sheets: TableInfo[];
  235. lineage: Record<string, unknown>;
  236. stats: Record<string, unknown>;
  237. warnings: string[];
  238. files: string[];
  239. }> {
  240. return this.request('/tools/customs_process', {
  241. method: 'POST',
  242. headers: { 'Content-Type': 'application/json' },
  243. body: JSON.stringify(payload),
  244. }, 1_800_000);
  245. }
  246. // ---------------------------------------------------------------- 工具
  247. dataRead(payload: DataReadPayload): Promise<{
  248. object_id: string;
  249. table: string;
  250. columns: string[];
  251. rows: Array<{ values: Record<string, unknown>; _trace: Record<string, unknown> }>;
  252. total: number;
  253. offset: number;
  254. limit: number;
  255. exhausted: boolean;
  256. aggregate?: boolean;
  257. }> {
  258. return this.request('/tools/data_read', {
  259. method: 'POST',
  260. headers: { 'Content-Type': 'application/json' },
  261. body: JSON.stringify(payload),
  262. }, 120_000);
  263. }
  264. calculate(payload: {
  265. op: string;
  266. inputs?: Array<Record<string, unknown>>;
  267. expression?: string;
  268. session_id?: string;
  269. label?: string;
  270. }): Promise<Record<string, unknown>> {
  271. return this.request('/tools/calculator', {
  272. method: 'POST',
  273. headers: { 'Content-Type': 'application/json' },
  274. body: JSON.stringify(payload),
  275. }, 30_000);
  276. }
  277. // ---------------------------------------------------------------- 台账
  278. ledgerStats(): Promise<Record<string, unknown>> {
  279. return this.request('/ledger/stats');
  280. }
  281. ledgerCalls(sessionId: string): Promise<{ items: Array<Record<string, unknown>> }> {
  282. return this.request(`/ledger/calls?session_id=${encodeURIComponent(sessionId)}`);
  283. }
  284. ledgerValue(value: string, sessionId: string): Promise<{ items: Array<Record<string, unknown>> }> {
  285. return this.request(`/ledger/value?value=${encodeURIComponent(value)}&session_id=${encodeURIComponent(sessionId)}`);
  286. }
  287. ledgerCall(callId: string): Promise<Record<string, unknown>> {
  288. return this.request(`/ledger/call/${encodeURIComponent(callId)}`);
  289. }
  290. }
  291. export const toolsClient = new ToolsClient();