@metad/contracts 3.6.2 → 3.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metad/contracts",
-  "version": "3.6.2",
+  "version": "3.7.0",
   "license": "AGPL-3.0",
   "repository": {
     "type": "git",
@@ -14,4 +14,4 @@
   },
   "module": "./index.esm.js",
   "main": "./index.cjs.js"
-}
+}

package/src/agent/graph.d.ts

@@ -15,6 +15,9 @@ export declare const GRAPH_NODE_SUMMARIZE_CONVERSATION = "summarize_conversation
 export declare const GRAPH_NODE_TITLE_CONVERSATION = "title_conversation";
 export declare const STATE_VARIABLE_FILES = "files";
 export declare const STATE_VARIABLE_INPUT = "input";
+export declare const STATE_SYS_VOLUME = "volume";
+export declare const STATE_SYS_WORKSPACE_PATH = "workspace_path";
+export declare const STATE_SYS_WORKSPACE_URL = "workspace_url";
 export declare const STATE_VARIABLE_TITLE_CHANNEL: string;
 export type TMessageChannel = {
     system: string;

package/src/agent/variables.d.ts

@@ -1,4 +1,5 @@
-import { TWorkflowVarGroup } from "../ai";
+import { TWorkflowVarGroup } from "../ai/xpert-workflow.model";
+import { TXpertParameter } from "../ai/xpert.model";
 /**
  *
  * Returns the variable schema for a given variable name.
@@ -10,5 +11,6 @@ import { TWorkflowVarGroup } from "../ai";
  */
 export declare function getVariableSchema(variables: TWorkflowVarGroup[], variable: string): {
     group: TWorkflowVarGroup;
-    variable: import("../ai").TStateVariable;
+    variable: import("../ai/xpert.model").TStateVariable;
 };
+export declare const FILE_VARIABLES: TXpertParameter[];

package/src/ai/index.d.ts

@@ -23,6 +23,7 @@ export * from './xpert-agent.model';
 export * from './xpert-tool.model';
 export * from './xpert-toolset.model';
 export * from './xpert-workspace.model';
+export * from './xpert-table.model';
 export * from './xpert.model';
 export * from './xpert.utils';
 export * from './types';
@@ -37,3 +38,5 @@ export * from './knowledgebase-task.model';
 export * from './knowledge-pipeline';
 export * from './knowledge-retrieval-log.model';
 export * from './knowledge-doc-chunk.model';
+export * from './skill.model';
+export * from './middleware.model';

package/src/ai/knowledge-doc-chunk.model.d.ts

@@ -29,6 +29,7 @@ export interface IDocChunkMetadata {
     isVector?: boolean;
     score?: number;
     relevanceScore?: number;
+    tokens?: number;
     [key: string]: any;
 }
 /**

package/src/ai/knowledge-doc.model.d.ts

@@ -3,11 +3,12 @@ import { IIntegration } from '../integration.model';
 import { IStorageFile } from '../storage-file.model';
 import { IKnowledgeDocumentPage } from './knowledge-doc-page.model';
 import { IKnowledgebaseTask } from './knowledgebase-task.model';
-import { IKnowledgebase } from './knowledgebase.model';
+import { IKnowledgebase, KBMetadataFieldDef } from './knowledgebase.model';
 import { TRagWebOptions } from './rag-web';
 import { IKnowledgeDocumentChunk } from './knowledge-doc-chunk.model';
 import { DocumentSourceProviderCategoryEnum } from './knowledge-pipeline';
 import { TCopilotModel } from './copilot-model.model';
+import { I18nObject } from '../types';
 export type DocumentParserConfig = {
     pages?: number[][];
     replaceWhitespace?: boolean;
@@ -170,14 +171,34 @@ export type TKnowledgeDocument = {
 /**
  * Document, include file, web pages, folder, virtual, etc.
  */
-export interface IKnowledgeDocument<T = Metadata> extends TKnowledgeDocument, IBasePerTenantAndOrganizationEntityModel {
+export interface IKnowledgeDocument<T extends KnowledgeDocumentMetadata = KnowledgeDocumentMetadata> extends TKnowledgeDocument, IBasePerTenantAndOrganizationEntityModel {
     parent?: IKnowledgeDocument | null;
     children?: IKnowledgeDocument[];
     knowledgebase?: IKnowledgebase;
     draft?: TKnowledgeDocument;
     metadata?: T;
 }
-export type Metadata = any;
+/**
+ * System built-in standard document Metadata structure
+ */
+export interface StandardDocumentMetadata {
+    originalFileName?: string;
+    originalFileSize?: string | null;
+    uploadTime?: string;
+    lastUpdatedTime?: string;
+    source?: string;
+    segmentRule?: string;
+    segmentLength?: number;
+    averageSegmentLength?: string;
+    segmentCount?: number;
+    recallRate?: string;
+    embedTime?: string;
+    embedCost?: string | null;
+    tokens?: number;
+}
+export interface KnowledgeDocumentMetadata extends StandardDocumentMetadata {
+    [key: string]: any;
+}
 export interface IKnowledgeDocumentCreateInput extends IKnowledgeDocument, IBasePerTenantAndOrganizationEntityModel {
 }
 export interface IKnowledgeDocumentUpdateInput extends Partial<IKnowledgeDocumentCreateInput> {
@@ -190,3 +211,12 @@ export declare function isImageType(type: string): boolean;
 export declare function isVideoType(type: string): boolean;
 export declare function isAudioType(type: string): boolean;
 export declare function classificateDocumentCategory(entity: Partial<IKnowledgeDocument>): KBDocumentCategoryEnum;
+/**
+ * System standard Metadata field definition constants
+ * It can be used for rendering, validation, sorting, displaying descriptions, etc.
+ */
+export declare const STANDARD_METADATA_FIELDS: {
+    group: I18nObject;
+    fields: KBMetadataFieldDef[];
+}[];
+export type StandardMetadataFieldKey = typeof STANDARD_METADATA_FIELDS[number]['fields'][number]['key'];

package/src/ai/knowledgebase.model.d.ts

@@ -1,5 +1,5 @@
 import { ICopilotModel } from './copilot-model.model';
-import { TAvatar } from '../types';
+import { I18nObject, TAvatar } from '../types';
 import { IBasePerWorkspaceEntityModel } from './xpert-workspace.model';
 import { IKnowledgeDocument } from './knowledge-doc.model';
 import { IXpert } from './xpert.model';
@@ -89,6 +89,10 @@ export type TKnowledgebase = {
      */
     recall?: TKBRecallParams;
     status?: string;
+    /**
+     * Metadata custom field definition array
+     */
+    metadataSchema?: KBMetadataFieldDef[];
     /**
      * API service enabled
      */
@@ -145,6 +149,14 @@ export type DocumentMetadata = IDocChunkMetadata & {
     score?: number;
     relevanceScore?: number;
 } & Record<string, any>;
+export type MetadataFieldType = 'string' | 'number' | 'boolean' | 'enum' | 'datetime' | 'string[]' | 'number[]' | 'object';
+export type KBMetadataFieldDef = {
+    key: string;
+    label?: I18nObject;
+    type: MetadataFieldType;
+    enumValues?: string[];
+    description?: string;
+};
 /**
  * Channel name for knowledgebase pipeline
  */

package/src/ai/middleware.model.d.ts

@@ -0,0 +1,18 @@
+import { IWorkflowNode, WorkflowNodeTypeEnum } from "./xpert-workflow.model";
+import { I18nObject, IconDefinition } from "../types";
+import { TXpertGraph, TXpertTeamNode } from "./xpert.model";
+import { JsonSchemaObjectType } from "./types";
+export interface IWFNMiddleware extends IWorkflowNode {
+    type: WorkflowNodeTypeEnum.MIDDLEWARE;
+    provider: string;
+    options?: Record<string, any>;
+}
+export declare function genXpertMiddlewareKey(): string;
+export type TAgentMiddlewareMeta = {
+    name: string;
+    label: I18nObject;
+    icon?: IconDefinition;
+    description?: I18nObject;
+    configSchema?: JsonSchemaObjectType;
+};
+export declare function getAgentMiddlewareNodes(graph: TXpertGraph, agentKey: string): TXpertTeamNode[];

package/src/ai/skill.model.d.ts

@@ -0,0 +1,181 @@
+import { IBasePerTenantAndOrganizationEntityModel } from "../base-entity.model";
+import { I18nObject, IconDefinition } from "../types";
+import { JsonSchemaObjectType } from "./types";
+import { IWorkflowNode, WorkflowNodeTypeEnum } from "./xpert-workflow.model";
+import { IBasePerWorkspaceEntityModel } from "./xpert-workspace.model";
+export type SkillId = string;
+export interface SkillMetadata {
+    name: string;
+    displayName?: I18nObject;
+    version: string;
+    summary?: I18nObject;
+    description?: I18nObject;
+    tags?: string[];
+    author?: {
+        name: string;
+        email?: string;
+        org?: string;
+    };
+    license?: string;
+    visibility: 'private' | 'team' | 'tenant' | 'public';
+    categories?: string[];
+    runtime?: {
+        entry?: string;
+        language?: 'js' | 'py' | 'bash';
+        permissions?: string[];
+        tools?: string[];
+    };
+    mcp?: {
+        servers?: string[];
+    };
+}
+export interface SkillResourcesIndex {
+    files: Array<{
+        path: string;
+        kind: 'script' | 'template' | 'doc' | 'asset';
+        hash: string;
+        size: number;
+    }>;
+    chunks?: Array<{
+        id: string;
+        path: string;
+        summary: string;
+        tokens: number;
+    }>;
+}
+export interface TSkillPackage {
+    metadata: SkillMetadata;
+    instructions: {
+        system?: string;
+        developer?: string;
+        examples?: Array<{
+            user: string;
+            assistant: string;
+        }>;
+        guidelines?: string[];
+    };
+    resources?: SkillResourcesIndex;
+    abac?: {
+        owners: string[];
+        readers: string[];
+        writers: string[];
+        policies?: any;
+    };
+    signatures?: string[];
+    provenance?: any;
+}
+/**
+ * 表示一个仓库（如 anthropics/skills）
+ */
+export interface ISkillRepository<O = Record<string, any>, C = Record<string, any>> extends IBasePerTenantAndOrganizationEntityModel {
+    name: string;
+    provider: string;
+    /**
+     * Provider credentials such as GitHub tokens
+     */
+    credentials?: C;
+    /**
+     * Options configured using the strategy's configSchema
+     */
+    options?: O;
+    lastSyncAt?: string;
+    deletedAt?: Date;
+}
+/**
+ * 仓库同步扫描得到的技能索引（每个技能目录一条）
+ */
+export interface ISkillRepositoryIndex extends IBasePerTenantAndOrganizationEntityModel {
+    repositoryId: string;
+    repository?: ISkillRepository;
+    skillPath: string;
+    skillId: string;
+    name?: string;
+    description?: string;
+    license?: string;
+    tags?: string[];
+    version?: string;
+    resources?: any[];
+    deletedAt?: Date;
+}
+/**
+ * 安装后的技能包主记录（skill.yaml）
+ */
+export interface ISkillPackage extends IBasePerWorkspaceEntityModel, TSkillPackage {
+    skillIndexId?: SkillId;
+    skillIndex?: ISkillRepositoryIndex;
+    name?: any;
+    visibility: 'private' | 'team' | 'tenant';
+    packagePath?: string;
+}
+/**
+ * 技能的版本（1个 Skill 多版本共存）
+ */
+export interface ISkillVersion extends IBasePerWorkspaceEntityModel {
+    packageId: string;
+    version: string;
+    metadata: any;
+    instructions: any;
+    installedAt?: string;
+}
+/**
+ * 技能资源文件（scripts/templates/assets）记录
+ */
+export interface ISkillResource extends IBasePerWorkspaceEntityModel {
+    versionId: string;
+    path: string;
+    type: 'script' | 'template' | 'asset' | 'doc';
+    hash?: string;
+    size?: number;
+    meta?: any;
+}
+/**
+ * 租户/组织/团队/用户安装行为记录
+ */
+export interface ISkillInstallation extends IBasePerTenantAndOrganizationEntityModel {
+    versionId: string;
+    installedBy: string;
+    visibility: 'private' | 'team' | 'tenant';
+    targetScope?: string;
+    status: 'pending' | 'installed' | 'failed';
+}
+/**
+ * 技能安装过程中详细日志
+ */
+export interface ISkillInstallLog extends IBasePerTenantAndOrganizationEntityModel {
+    installationId: string;
+    level: 'info' | 'warn' | 'error';
+    message: string;
+    timestamp: string;
+}
+/**
+ * 技能运行期审计日志
+ */
+export interface ISkillAuditLog extends IBasePerTenantAndOrganizationEntityModel {
+    skillId: string;
+    versionId: string;
+    sessionId: string;
+    eventType: string;
+    metadata: any;
+}
+export type TSkillSourceMeta = {
+    /**
+     * Provider name, e.g. github / git / zip / marketplace
+     */
+    name: string;
+    label: I18nObject;
+    icon?: IconDefinition;
+    description?: I18nObject;
+    /**
+     * Optional configuration schema for frontend forms
+     */
+    configSchema?: JsonSchemaObjectType;
+    /**
+     * Credential schema for source authentication
+     */
+    credentialSchema?: JsonSchemaObjectType;
+};
+export interface IWFNSkill extends IWorkflowNode {
+    type: WorkflowNodeTypeEnum.SKILL;
+    skills?: string[];
+}
+export declare function genXpertSkillKey(): string;

package/src/ai/types.d.ts

@@ -1,4 +1,5 @@
-import { TSelectOption } from "../types";
+import { JsonSchema7TypeUnion } from "zod-to-json-schema";
+import { I18nObject, TSelectOption } from "../types";
 import { TXpertAttachmentType, XpertParameterTypeEnum } from "./xpert.model";
 export type TErrorHandling = {
     type?: null | 'defaultValue' | 'failBranch';
@@ -37,3 +38,34 @@ export declare enum EmbeddingStatusEnum {
     REQUIRED = "required"
 }
 export declare const Attachment_Type_Options: TSelectOption<string, TXpertAttachmentType>[];
+type JsonSchema7Meta = {
+    title?: I18nObject;
+    default?: any;
+    description?: I18nObject;
+    markdownDescription?: I18nObject;
+    /**
+     * UI schema extensions
+     */
+    'x-ui'?: {
+        /**
+         * UI component variant, or custom component name
+         */
+        component?: 'textarea' | 'select' | 'radio' | 'checkbox' | 'switch' | 'password' | string;
+        /**
+         * UI component display span (for grid layouts)
+         */
+        span?: number;
+        /**
+         * Additional inputs for the Custom UI component
+         */
+        inputs?: Record<string, unknown>;
+    };
+};
+export type JsonSchemaObjectType = {
+    type: "object";
+    properties: Record<string, JsonSchema7Type>;
+    additionalProperties?: boolean | JsonSchema7Type;
+    required?: string[];
+};
+type JsonSchema7Type = (JsonSchema7TypeUnion | JsonSchemaObjectType) & JsonSchema7Meta;
+export {};

package/src/ai/xpert-agent.model.d.ts

@@ -144,9 +144,21 @@ export type TXpertAgentOptions = {
      */
     vision?: {
         enabled?: boolean;
+        /**
+         * Variable name that store the list of files to be understood
+         */
         variable?: string;
+        /**
+         * Image resolution for vision tasks
+         */
         resolution?: 'high' | 'low';
     };
+    /**
+     * Config of middlewares for agent
+     */
+    middlewares?: {
+        order: string[];
+    };
 };
 export type TAgentPromptTemplate = {
     id: string;

package/src/ai/xpert-table.model.d.ts

@@ -0,0 +1,84 @@
+import { IWorkflowNode, WorkflowNodeTypeEnum } from './xpert-workflow.model';
+import { IBasePerWorkspaceEntityModel } from './xpert-workspace.model';
+/**
+ * Table status
+ */
+export declare enum XpertTableStatus {
+    DRAFT = "draft",
+    READY = "ready",
+    PENDING_ACTIVATION = "pendingActivation",
+    ACTIVE = "active",
+    NEEDS_MIGRATION = "needsMigration",
+    DEPRECATED = "deprecated",
+    ERROR = "error"
+}
+/**
+ * Custom Table for Xpert
+ */
+export interface IXpertTable extends IBasePerWorkspaceEntityModel, TXpertTable {
+}
+export type TXpertTable = {
+    name: string;
+    description?: string;
+    database?: string;
+    schema?: string;
+    columns?: TXpertTableColumn[];
+    status: XpertTableStatus;
+    version?: number;
+    activatedAt?: Date;
+    message?: string;
+};
+/**
+ * Union type for all supported database types
+ * Used when database type is not yet determined or needs to support multiple databases
+ */
+export type DatabaseDataType = string;
+export type TXpertTableColumn = {
+    name: string;
+    type: DatabaseDataType;
+    label?: string;
+    required?: boolean;
+    isPrimaryKey?: boolean;
+    isUnique?: boolean;
+    autoIncrement?: boolean;
+    defaultValue?: string;
+    length?: number;
+    precision?: number;
+    scale?: number;
+    enumValues?: string[];
+    setValues?: string[];
+};
+export interface IWorkflowNodeDBOperation extends IWorkflowNode {
+    tableId: string;
+}
+export interface IWFNDBInsert extends IWorkflowNodeDBOperation {
+    type: WorkflowNodeTypeEnum.DB_INSERT;
+    columns?: Record<string, {
+        type: DatabaseDataType;
+        value?: any;
+        valueSelector?: string;
+    }>;
+}
+export declare function genXpertDBInsertKey(): string;
+export interface IWFNDBUpdate extends IWorkflowNodeDBOperation {
+    type: WorkflowNodeTypeEnum.DB_UPDATE;
+    columns?: Record<string, {
+        type: DatabaseDataType;
+        value?: any;
+        valueSelector?: string;
+    }>;
+}
+export declare function genXpertDBUpdateKey(): string;
+export interface IWFNDBDelete extends IWorkflowNodeDBOperation {
+    type: WorkflowNodeTypeEnum.DB_DELETE;
+}
+export declare function genXpertDBDeleteKey(): string;
+export interface IWFNDBQuery extends IWorkflowNodeDBOperation {
+    type: WorkflowNodeTypeEnum.DB_QUERY;
+}
+export declare function genXpertDBQueryKey(): string;
+export interface IWFNDBSql extends IWorkflowNodeDBOperation {
+    type: WorkflowNodeTypeEnum.DB_SQL;
+    sqlTemplate?: string;
+}
+export declare function genXpertDBSqlKey(): string;

package/src/ai/xpert-tool-mcp.model.d.ts

@@ -51,6 +51,11 @@ export type TMCPServer = {
     url?: string;
     headers?: Record<string, string>;
     useNodeEventSource?: boolean;
+    /**
+     * Default timeout in milliseconds for tool execution. Must be greater than 0.
+     * If not specified, tools will use their own configured timeout values.
+     */
+    defaultToolTimeout?: number;
     files?: {
         name: string;
         content: string;

package/src/ai/xpert-tool.model.d.ts

@@ -1,3 +1,4 @@
+import type { JSONSchema4 } from "json-schema";
 import { IBasePerTenantAndOrganizationEntityModel } from '../base-entity.model';
 import { I18nObject } from '../types';
 import { AiProviderRole } from './copilot.model';
@@ -10,6 +11,7 @@ export interface IXpertTool extends IBasePerTenantAndOrganizationEntityModel, Xp
 }
 export type XpertToolType = {
     name: string;
+    label?: I18nObject | string;
     description?: string;
     avatar?: TAvatar;
     /**
@@ -93,7 +95,12 @@ export interface ApiToolBundle {
     method: string;
     summary?: string;
     operation_id?: string;
+    /**
+     * parameters
+     * @deprecated use schema
+     */
     parameters?: TToolParameter[];
+    schema?: JSONSchema4;
     author: string;
     icon?: string;
     openapi: Record<string, any>;

package/src/ai/xpert-workflow.model.d.ts

@@ -2,7 +2,7 @@ import { I18nObject, IconDefinition } from "../types";
 import { ICopilotModel } from "./copilot-model.model";
 import { TKBRecallParams } from "./knowledgebase.model";
 import { ApiAuthType, TErrorHandling, TXpertRefParameter } from "./types";
-import { TStateVariable, TXpertParameter } from "./xpert.model";
+import { TKBRetrievalSettings, TStateVariable, TXpertParameter } from "./xpert.model";
 export type TWorkflowNodeMeta = {
     name: string;
     label: I18nObject;
@@ -26,13 +26,8 @@ export declare enum WorkflowNodeTypeEnum {
     LIST_OPERATOR = "list-operator",
     VARIABLE_AGGREGATOR = "variable-aggregator",
     ITERATING = "iterating",
-    ANSWER = "answer",
-    CODE = "code",
     HTTP = "http",
-    KNOWLEDGE = "knowledge",
     SUBFLOW = "subflow",
-    TEMPLATE = "template",
-    CLASSIFIER = "classifier",
     TOOL = "tool",
     AGENT_TOOL = "agent-tool",
     NOTE = "note",
@@ -44,7 +39,36 @@ export declare enum WorkflowNodeTypeEnum {
     PROCESSOR = "processor",
     CHUNKER = "chunker",
     UNDERSTANDING = "understanding",
-    KNOWLEDGE_BASE = "knowledgebase"
+    KNOWLEDGE_BASE = "knowledgebase",
+    CLASSIFIER = "classifier",
+    KNOWLEDGE = "knowledge",
+    CODE = "code",
+    TEMPLATE = "template",
+    ANSWER = "answer",
+    JSON_STRINGIFY = "json-stringify",
+    JSON_PARSE = "json-parse",
+    /**
+     * Custom SQL
+     */
+    DB_SQL = "db-sql",
+    /**
+     * Insert data (INSERT)
+     */
+    DB_INSERT = "db-insert",
+    /**
+     * Update data (UPDATE)
+     */
+    DB_UPDATE = "db-update",
+    /**
+     * Delete data (DELETE)
+     */
+    DB_DELETE = "db-delete",
+    /**
+     * Query data (SELECT)
+     */
+    DB_QUERY = "db-query",
+    MIDDLEWARE = "middleware",
+    SKILL = "skill"
 }
 export interface IWorkflowNode {
     id: string;
@@ -270,6 +294,7 @@ export interface IWFNKnowledgeRetrieval extends IWorkflowNode {
     queryVariable: string;
     knowledgebases: string[];
     recall?: TKBRecallParams;
+    retrieval?: TKBRetrievalSettings;
 }
 export interface IWFNSubflow extends IWorkflowNode {
     inputParams?: TXpertRefParameter[];
@@ -355,9 +380,19 @@ export interface IWFNTask extends IWorkflowNode {
     descriptionPrefix?: string;
     descriptionSuffix?: string;
 }
+export interface IWFNJSONStringify extends IWorkflowNode {
+    type: WorkflowNodeTypeEnum.JSON_STRINGIFY;
+    inputVariable: string;
+}
+export interface IWFNJSONParse extends IWorkflowNode {
+    type: WorkflowNodeTypeEnum.JSON_PARSE;
+    inputVariable: string;
+}
 export declare function genXpertTriggerKey(): string;
 export declare function genListOperatorKey(): string;
 export declare function genVariableAggregatorKey(): string;
+export declare function genJSONStringifyKey(): string;
+export declare function genJSONParseKey(): string;
 export declare function isAgentKey(key: string): boolean;
 export declare function isRouterKey(key: string): boolean;
 export declare function isIteratingKey(key: string): boolean;