From bbe96d35a553e70fd5f5432ce16fa93f76c99554 Mon Sep 17 00:00:00 2001
From: "zeyu.fz" <zeyu.fz@alibaba-inc.com>
Date: Sat, 15 Aug 2026 18:30:06 +0800
Subject: [PATCH] feat: endpoint builder and API types

---
 packages/tool-bailian-kb/src/api-types.ts     | 53 +++++++++++++++++++
 packages/tool-bailian-kb/src/endpoints.ts     | 19 +++++++
 .../tool-bailian-kb/tests/endpoints.test.ts   | 14 +++++
 3 files changed, 86 insertions(+)
 create mode 100644 packages/tool-bailian-kb/src/api-types.ts
 create mode 100644 packages/tool-bailian-kb/src/endpoints.ts
 create mode 100644 packages/tool-bailian-kb/tests/endpoints.test.ts

diff --git a/packages/tool-bailian-kb/src/api-types.ts b/packages/tool-bailian-kb/src/api-types.ts
new file mode 100644
index 0000000..73534e4
--- /dev/null
+++ b/packages/tool-bailian-kb/src/api-types.ts
@@ -0,0 +1,53 @@
+/** Request/response fields of the three DashScope knowledge endpoints, mirrored from the verified kscli types. */
+
+export interface ServiceListRequest {
+  agent_scene: 'chat' | 'search'
+  agent_name?: string
+  page_number: number
+  page_size: number
+}
+
+export interface ServiceListRow {
+  agent_id?: string
+  agent_name?: string
+  agent_scene?: string
+  agent_status?: string
+  pipeline_list?: { pipeline_id?: string; pipeline_name?: string }[]
+}
+
+export interface ServiceListResponse {
+  code?: string
+  message?: string
+  data?: { total_count?: number; rows?: ServiceListRow[] }
+}
+
+export interface SearchRequest {
+  query: string
+  agent_id: string
+  agent_version?: string
+  images?: string[]
+}
+
+export interface SearchResponse {
+  request_id?: string
+  data?: {
+    total?: number
+    nodes?: { score: number; text: string; metadata?: Record<string, unknown> }[]
+  }
+}
+
+export interface ChatRequest {
+  input: { messages: { role: 'user' | 'assistant'; content: string }[] }
+  parameters: { agent_options: { agent_id: string; agent_version?: string } }
+  stream: true
+}
+
+export interface ChatStreamChunk {
+  output?: {
+    choices?: {
+      message?: { content?: string; extra?: { step_change?: string } }
+      finish_reason?: string
+    }[]
+  }
+  request_id?: string
+}
diff --git a/packages/tool-bailian-kb/src/endpoints.ts b/packages/tool-bailian-kb/src/endpoints.ts
new file mode 100644
index 0000000..3ecce53
--- /dev/null
+++ b/packages/tool-bailian-kb/src/endpoints.ts
@@ -0,0 +1,19 @@
+/** Protocol path constants and the workspace-subdomain URL builder (external API spec; not configurable). */
+
+/** DashScope knowledge API paths, mirrored from the verified kscli endpoint table. */
+export const KB_PATHS = {
+  serviceList: '/api/v1/indices/rag/app/list',
+  search: '/api/v1/indices/knowledge/search',
+  chat: '/api/v2/apps/knowledge/chat',
+} as const
+
+/**
+ * Build one knowledge API endpoint.
+ * @param endpointHost - host suffix, e.g. `cn-beijing.maas.aliyuncs.com`.
+ * @param workspaceId - Bailian workspace id used as the subdomain.
+ * @param path - one {@link KB_PATHS} value.
+ * @returns the absolute endpoint URL.
+ */
+export function kbEndpoint(endpointHost: string, workspaceId: string, path: string): string {
+  return `https://${workspaceId}.${endpointHost}${path}`
+}
diff --git a/packages/tool-bailian-kb/tests/endpoints.test.ts b/packages/tool-bailian-kb/tests/endpoints.test.ts
new file mode 100644
index 0000000..a64ee98
--- /dev/null
+++ b/packages/tool-bailian-kb/tests/endpoints.test.ts
@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest'
+import { KB_PATHS, kbEndpoint } from '../src/endpoints.js'
+
+describe('kbEndpoint', () => {
+  it('builds the workspace-subdomain URL', () => {
+    expect(kbEndpoint('cn-beijing.maas.aliyuncs.com', 'ws-1', KB_PATHS.search))
+      .toBe('https://ws-1.cn-beijing.maas.aliyuncs.com/api/v1/indices/knowledge/search')
+  })
+
+  it('keeps protocol paths as constants', () => {
+    expect(KB_PATHS.chat).toBe('/api/v2/apps/knowledge/chat')
+    expect(KB_PATHS.serviceList).toBe('/api/v1/indices/rag/app/list')
+  })
+})