@yiyi_zhang/reactflow-ui 1.1.0 → 1.2.0

package/dist/AiWorkflowIDE.d.ts

@@ -10,6 +10,7 @@ import type { WorkflowDef, WorkflowInstance } from './types/conductor';
 import type { AiConfig } from './services/ai/protocolAdapter';
 import type { AiMetrics } from './store/aiStore';
 import type { WorkflowLibraryItem } from './types/workflowLibrary';
+import type { LibraryProvider } from './library/types';
 import type { ExecutionActions, ThemeMode, ThemeColor, LayoutDirection, ViewMode, WorkflowExecutionInput } from './types/workflow';
 import type { CustomTool } from './services/ai/toolRegistry';
 import type { CustomValidationRule } from './services/ai/ruleEngine';
@@ -42,6 +43,26 @@ export interface AiWorkflowIDEProps {
      * ```
      */
     workflowLibrary?: WorkflowLibraryItem[];
+    /**
+     * 流程库数据源（LibraryProvider）。提供后，库内流程 / 任务定义经规范化后同时投影为
+     * AI 目录（`workflowLibrary`）、任务 Schema（`taskSchemas`）与检索工具的数据来源；
+     * 同名条目 Provider 优先于静态 prop，静态 prop 仍可单独使用。
+     *
+     * `libraryProvider` 引用变化时重新加载，组件卸载时中止进行中的请求。
+     * AI 新建的 SUB_WORKFLOW 会固定为目录当前最新版本，已有版本号不会被自动改变。
+     *
+     * ```tsx
+     * const provider = createConductorLibraryProvider({ baseUrl, headers });
+     * <AiWorkflowIDE libraryProvider={provider} />
+     * ```
+     */
+    libraryProvider?: LibraryProvider;
+    /**
+     * 流程库目录注入系统提示词的条数上限，默认 50（按层级 L3 -> L1 截断）。
+     * 超出部分会提示 AI 改用 `search_workflow_library` 检索。
+     * 提供 `libraryProvider` 时，任务 Schema 段落同样受此上限约束。
+     */
+    promptCatalogLimit?: number;
     /**
      * AI 模型配置（集成方提供）。
      *

package/dist/WorkflowIDE.d.ts

@@ -2,6 +2,8 @@ import { ThemeMode, ThemeColor, LayoutDirection, ValidationResults, ExecutionAct
 import { WorkflowDef, WorkflowInstance } from './types/conductor';
 import { AIServiceConfig } from './services/aiService';
 import { ActionDefinition } from './actions/types';
+import type { WorkflowLevel } from './types/workflowLibrary';
+import type { LibraryProvider } from './library/types';
 import './styles/tokens.css';
 import './styles/executionStyles.css';
 /**
@@ -105,6 +107,25 @@ export interface WorkflowIDEProps {
      * 宿主可传入自定义业务动作（如私有云/特定系统连接器）。
      */
     actions?: ActionDefinition[];
+    /**
+     * 流程库数据源（LibraryProvider）。提供后，库内流程 / 任务定义会生成业务动作并注册到本实例的动作库：
+     * 流程库能力编译为 `SUB_WORKFLOW`，步骤在首次引用时固定为目录当前最新版本，
+     * 库发布新版本后步骤不会自动跟随，徽标提示「有新版本」，由用户确认差异后手动升级。
+     *
+     * 同名动作 Provider 优先于 `actions`；不传时 `actions` 的行为完全不变。
+     * `libraryProvider` 引用变化时重新加载，组件卸载时中止进行中的请求。
+     *
+     * ```tsx
+     * const provider = createConductorLibraryProvider({ baseUrl, headers });
+     * <WorkflowIDE uiMode="business" libraryProvider={provider} />
+     * ```
+     */
+    libraryProvider?: LibraryProvider;
+    /**
+     * 当前正在编辑的工作流层级（L1 / L2 / L3）。
+     * 提供时，动作选择器隐藏违反分层调用规则的流程库动作（L1 不显示 L2/L3，L2 不显示 L3）；未提供则不过滤。
+     */
+    currentWorkflowLevel?: WorkflowLevel;
     /**
      * 组件容器高度。
      * @default '100%'

package/dist/actions/fromDefinitions.d.ts

@@ -0,0 +1,70 @@
+import type { SchemaDef, WorkflowDef } from '../types/conductor';
+import type { ActionCategory, ActionDefinition, ActionField, ActionOutputField } from './types';
+import type { WorkflowLevel } from '../types/workflowLibrary';
+/**
+ * 从 Conductor OSS 标准定义（WorkflowDef / 已注册 TaskDef）生成业务动作。
+ *
+ * 设计原则：
+ * - 库本身不发请求：定义数据由接入方从治理层取得（权限过滤也在治理层完成）。
+ * - 标准结构给不了的信息（中文名、分类、图标、风险等级、特殊控件、层级、标签）
+ *   通过可选的 ActionExtension 补充；缺省时按合理默认值降级，保证任何定义都能出现在动作库里。
+ */
+/** 治理层/接入方提供的补充字段（均可选，按名称一一对应） */
+export interface ActionExtension {
+    /** 业务展示名（缺省使用定义名称） */
+    label?: string;
+    description?: string;
+    category?: ActionCategory;
+    icon?: string;
+    riskLevel?: 'safe' | 'sensitive';
+    connector?: string;
+    level?: WorkflowLevel;
+    /** 业务域展示名 */
+    domain?: string;
+    tags?: string[];
+    /** 为 true 时不进入动作库（例如用户无权限、已下线） */
+    hidden?: boolean;
+    /** 按入参 key 覆盖表单字段属性（中文标签、控件类型、下拉选项等） */
+    fieldOverrides?: Record<string, Partial<ActionField>>;
+    /** 按出参 key 覆盖出参说明（中文标签、示例值） */
+    outputOverrides?: Record<string, Partial<ActionOutputField>>;
+}
+/** Conductor `/metadata/taskdefs` 返回的已注册任务定义（只列本模块用到的标准字段） */
+export interface RegisteredTaskDef {
+    name: string;
+    description?: string;
+    /** 仅文档用途，不强制 */
+    inputKeys?: string[];
+    outputKeys?: string[];
+    inputTemplate?: Record<string, any>;
+    inputSchema?: SchemaDef;
+    outputSchema?: SchemaDef;
+    ownerEmail?: string;
+}
+/**
+ * 将 JSON Schema 的 properties 转为表单字段；没有 schema 时退化为仅有 key 列表
+ * （Conductor 的 inputKeys / inputParameters 只有名称），类型一律按文本处理。
+ */
+export declare function buildFields(schema: SchemaDef | undefined, fallbackKeys: string[], inputTemplate?: Record<string, any>): ActionField[];
+/** 出参：优先 outputSchema；其次 outputKeys / outputParameters 的 key（后者是输出模板，其 key 即对外接口） */
+export declare function buildOutputs(schema: SchemaDef | undefined, fallbackKeys: string[], outputTemplate?: Record<string, any>): ActionOutputField[];
+/**
+ * 把流程库中的一个工作流定义生成为动作：业务用户只面对入参表单与出参，
+ * 编译为 SUB_WORKFLOW 引用。版本由步骤上的 libraryRef 决定（首次引用时固定）。
+ * 被 extension.hidden 标记时返回 null。
+ */
+export declare function buildActionFromWorkflowDef(def: WorkflowDef, ext?: ActionExtension): ActionDefinition | null;
+/** 已注册任务定义生成原子动作，编译为同名 SIMPLE 任务。 */
+export declare function buildActionFromTaskDef(def: RegisteredTaskDef, ext?: ActionExtension): ActionDefinition | null;
+export interface LibraryWorkflowEntry {
+    workflowDef: WorkflowDef;
+    extension?: ActionExtension;
+}
+export interface RegisteredTaskEntry {
+    taskDef: RegisteredTaskDef;
+    extension?: ActionExtension;
+}
+/** 批量生成流程库动作（自动跳过 hidden） */
+export declare function buildActionsFromLibrary(entries: LibraryWorkflowEntry[]): ActionDefinition[];
+/** 批量生成原子任务动作（自动跳过 hidden） */
+export declare function buildActionsFromTaskDefs(entries: RegisteredTaskEntry[]): ActionDefinition[];

package/dist/actions/registry.d.ts

@@ -5,6 +5,7 @@ export declare class ActionRegistry {
     constructor(initialActions?: ActionDefinition[]);
     register(action: ActionDefinition): void;
     registerAll(actions: ActionDefinition[]): void;
+    unregister(id: string): void;
     getAction(id: string): ActionDefinition | undefined;
     getAllActions(): ActionDefinition[];
     getActionsByCategory(category?: ActionCategory): ActionDefinition[];

package/dist/actions/types.d.ts

@@ -1,4 +1,5 @@
 import type { TaskDef } from '../types/conductor';
+import type { WorkflowLevel } from '../types/workflowLibrary';
 export type ActionCategory = 'compute' | 'storage' | 'network' | 'monitor' | 'notify' | 'logic' | 'human' | 'custom';
 export type ActionFieldType = 'text' | 'textarea' | 'number' | 'select' | 'boolean' | 'account' | 'cron-friendly';
 export interface ActionFieldOption {
@@ -28,6 +29,16 @@ export interface CompileCtx {
     taskReferenceName: string;
     stepIndex: number;
     workflowName?: string;
+    /**
+     * 该步骤引用流程库能力时记录的 {名称, 版本}。
+     * 版本在首次引用时固定，库升级后不会自动跟随；version 缺省表示沿用原定义（不显式指定版本）。
+     */
+    libraryRef?: LibraryRef;
+}
+/** 步骤对流程库能力（SUB_WORKFLOW）的引用记录 */
+export interface LibraryRef {
+    name: string;
+    version?: number;
 }
 export interface ActionDefinition {
     id: string;
@@ -36,6 +47,21 @@ export interface ActionDefinition {
     icon: string;
     description: string;
     connector?: string;
+    /** 动作来源：task = 原子任务（默认），workflow = 流程库能力（以 SUB_WORKFLOW 引用） */
+    kind?: 'task' | 'workflow';
+    /** kind = workflow 时：库中该能力的当前最新版本，用于提示“有新版本可升级” */
+    workflowRef?: {
+        name: string;
+        version: number;
+    };
+    /** 流程库层级 L1 / L2 / L3（调用方向规则见 workflowLibrary） */
+    level?: WorkflowLevel;
+    /** 业务域展示名（流程库动作）；动作选择器据此分组，缺省归入「其他」 */
+    domain?: string;
+    /** 已下线 / 不建议新引用：动作选择器隐藏，但已引用的步骤照常显示与编译 */
+    deprecated?: boolean;
+    tags?: string[];
+    ownerEmail?: string;
     riskLevel: 'safe' | 'sensitive';
     fields: ActionField[];
     outputs: ActionOutputField[];

package/dist/ai.d.ts

@@ -21,6 +21,15 @@ export type { CustomTool } from './services/ai/toolRegistry';
 export type { CustomValidationRule } from './services/ai/ruleEngine';
 export type { TaskSchema } from './services/ai/schemaRegistry';
 export type { WorkflowLevel, WorkflowLibraryItem, WorkflowLibraryDetail } from './types/workflowLibrary';
+export type { LibraryProvider, LibraryExtension, LibraryWorkflowRecord, LibraryTaskRecord, LibraryListResult, LibrarySearchOptions, LibraryLoadStatus, } from './library/types';
+export { LibraryCatalog } from './library/catalog';
+export type { LibraryEntry, LibraryCatalogSnapshot, LibraryCatalogOptions } from './library/catalog';
+export { toActions, toTaskSchemas, toLibraryItems } from './library/projections';
+export { parseWorkflowName, validateWorkflowName } from './library/naming';
+export type { ParsedWorkflowName, WorkflowNameType } from './library/naming';
+export { createConductorLibraryProvider } from './library/conductorProvider';
+export type { ConductorLibraryProviderOptions } from './library/conductorProvider';
+export { DEFAULT_PROMPT_CATALOG_LIMIT } from './services/ai/systemPrompt';
 export type { AiEvent, AiEventType } from './types/aiEvents';
 export type { DiffSummary, PartialAcceptSelection, PatchOp } from './services/ai/toolExecutor';
 export { applyPartialProposal, describeDiff, computeDiff } from './services/ai/toolExecutor';

package/dist/components/AiNative/AiCommandCenter.d.ts

@@ -12,6 +12,10 @@ import type { AiEvent } from '../../types/aiEvents';
 interface AiCommandCenterProps {
     systemPrompt?: string;
     systemPromptExtra?: string;
+    /** 流程库目录注入提示词的条数上限（缺省 50） */
+    promptCatalogLimit?: number;
+    /** 任务 Schema 注入提示词的条数上限（缺省不限制） */
+    promptSchemaLimit?: number;
     showConfigButton?: boolean;
     onShowConfig: () => void;
     executionActions?: ExecutionActions;

package/dist/components/business/ActionPickerModal.d.ts

@@ -0,0 +1,25 @@
+import React from 'react';
+import type { ActionRegistry } from '../../actions/registry';
+import type { ActionDefinition } from '../../actions/types';
+import type { WorkflowLevel } from '../../types/workflowLibrary';
+import type { LibraryCatalog } from '../../library/catalog';
+export interface ActionPickerModalProps {
+    registry: ActionRegistry;
+    /** 展示用的步骤序号（从 1 开始） */
+    stepNumber: number;
+    onClose: () => void;
+    onSelect: (action: ActionDefinition) => void;
+    /**
+     * 当前正在编辑的工作流层级。提供时隐藏违反分层调用规则的流程库动作
+     * （L1 不显示 L2/L3，L2 不显示 L3）；未提供则不按层级过滤。
+     */
+    currentWorkflowLevel?: WorkflowLevel;
+    /** 流程库目录：用于显示「加载中 / 加载失败，点击重试」状态 */
+    libraryCatalog?: LibraryCatalog;
+}
+/**
+ * 业务动作选择弹窗：分类筛选 + 关键字搜索。
+ * 筛选状态与过滤计算都放在弹窗内部：仅在弹窗打开时才会随输入重新计算，
+ * 不再拖累编辑器每次渲染（动作库可能有成百上千项）。
+ */
+export declare const ActionPickerModal: React.FC<ActionPickerModalProps>;

package/dist/components/business/DataPillInput.d.ts

@@ -10,5 +10,7 @@ export interface DataPillInputProps {
     registry?: ActionRegistry;
     workflowInputParams?: any[];
     disabled?: boolean;
+    /** 初始即展开「插入数据」选择面板（例如下拉字段刚切换为动态取值时） */
+    defaultShowPicker?: boolean;
 }
 export declare const DataPillInput: React.FC<DataPillInputProps>;

package/dist/components/business/DecisionBranchCard.d.ts

@@ -9,5 +9,7 @@ export interface DecisionBranchCardProps {
     disabled?: boolean;
     onChange: (updated: BusinessStep) => void;
     onOpenInsertModal: (callback: (action: ActionDefinition) => void) => void;
+    /** 嵌套深度：顶层卡片为 0，其内部子控制流依次 +1 */
+    depth?: number;
 }
 export declare const DecisionBranchCard: React.FC<DecisionBranchCardProps>;

package/dist/components/business/ForkJoinCard.d.ts

@@ -9,5 +9,7 @@ export interface ForkJoinCardProps {
     disabled?: boolean;
     onChange: (updated: BusinessStep) => void;
     onOpenInsertModal: (callback: (action: ActionDefinition) => void) => void;
+    /** 嵌套深度：顶层卡片为 0，其内部子控制流依次 +1 */
+    depth?: number;
 }
 export declare const ForkJoinCard: React.FC<ForkJoinCardProps>;

package/dist/components/business/LibraryVersionBadge.d.ts

@@ -0,0 +1,29 @@
+import React from 'react';
+import type { BusinessStep } from '../../stepmodel/types';
+import type { ActionDefinition } from '../../actions/types';
+import type { LibraryCatalog } from '../../library/catalog';
+import { type WorkflowVersionDiff } from '../../library/diff';
+export interface LibraryVersionBadgeProps {
+    step: BusinessStep;
+    action?: ActionDefinition;
+    disabled?: boolean;
+    /**
+     * 流程库目录。提供后：
+     * - 升级前取旧、新两个版本的定义，展示入参 / 出参差异再确认
+     * - 固定版本在库中不存在 / 已下线时显示「⚠ 版本不可用」
+     * 未提供时沿用旧行为（只按动作上记录的最新版本提示升级）。
+     */
+    catalog?: LibraryCatalog;
+    /** 其它步骤中引用了本步骤哪些出参 key（用于差异里的「下游引用将失效」提示） */
+    getReferencedOutputs?: () => Iterable<string>;
+    /** 用户确认升级后回调：库中最新版本号，以及（能取到两个版本定义时的）升级差异 */
+    onUpgrade: (latestVersion: number, diff?: WorkflowVersionDiff) => void;
+}
+/**
+ * 流程库能力的版本标记：
+ * - 显示步骤引用时固定的版本（库升级后不会自动跟随）
+ * - 库中有更新版本时，提示并允许用户在看过升级差异后手动升级
+ * - 固定版本不可用（不存在 / 已下线）时给出警示，保持原样编译，不自动改版本
+ * - 目录加载失败时不显示新版本提示，不影响编辑与编译
+ */
+export declare const LibraryVersionBadge: React.FC<LibraryVersionBadgeProps>;

package/dist/components/business/LoopDoWhileCard.d.ts

@@ -9,5 +9,7 @@ export interface LoopDoWhileCardProps {
     disabled?: boolean;
     onChange: (updated: BusinessStep) => void;
     onOpenInsertModal: (callback: (action: ActionDefinition) => void) => void;
+    /** 嵌套深度：顶层卡片为 0，其内部子控制流依次 +1 */
+    depth?: number;
 }
 export declare const LoopDoWhileCard: React.FC<LoopDoWhileCardProps>;

package/dist/components/business/NestedControlStep.d.ts

@@ -0,0 +1,22 @@
+import React from 'react';
+import type { BusinessStep } from '../../stepmodel/types';
+import { ActionRegistry } from '../../actions/registry';
+import type { ActionDefinition } from '../../actions/types';
+export interface NestedControlStepProps {
+    step: BusinessStep;
+    index: number;
+    /** 当前嵌套层级（顶层卡片内的第一层子控制流为 1），用于缩进与视觉区分 */
+    depth?: number;
+    upstreamSteps: BusinessStep[];
+    registry?: ActionRegistry;
+    disabled?: boolean;
+    onChange: (updated: BusinessStep) => void;
+    onDelete: () => void;
+    onOpenInsertModal: (callback: (action: ActionDefinition) => void) => void;
+}
+/**
+ * 分支 / 并行泳道 / 循环体内部的"子控制流"渲染器。
+ * 通过它，DecisionBranchCard / ForkJoinCard / LoopDoWhileCard 可以互相递归嵌套，
+ * 支持例如「分支 A 内再包含一个分支」「泳道内再有并行或循环」等任意层级。
+ */
+export declare const NestedControlStep: React.FC<NestedControlStepProps>;

package/dist/components/business/StepFlowEditor.d.ts

@@ -1,11 +1,20 @@
 import React from 'react';
 import type { WorkflowDef, WorkflowInstance } from '../../types/conductor';
+import type { BusinessStep } from '../../stepmodel/types';
 import { ActionRegistry } from '../../actions/registry';
+import type { LibraryCatalog } from '../../library/catalog';
+import type { WorkflowLevel } from '../../types/workflowLibrary';
 export interface StepFlowEditorProps {
     workflowDef: WorkflowDef | null;
     onChange: (def: WorkflowDef) => void;
     registry?: ActionRegistry;
     readOnly?: boolean;
     workflowExecution?: WorkflowInstance;
+    /** 流程库目录（由 WorkflowIDE 按 libraryProvider 创建）：用于动作选择器状态与版本徽标 */
+    libraryCatalog?: LibraryCatalog;
+    /** 当前正在编辑的工作流层级：提供时选择器隐藏违反分层调用规则的流程库动作 */
+    currentWorkflowLevel?: WorkflowLevel;
+    /** 提供时，步骤头部显示「🤖」按钮，点击请 AI 介绍该步骤（AI IDE 中使用） */
+    onAskAi?: (step: BusinessStep) => void;
 }
 export declare const StepFlowEditor: React.FC<StepFlowEditorProps>;

package/dist/components/business/StepListEditor.d.ts

@@ -0,0 +1,29 @@
+import React from 'react';
+import type { BusinessStep } from '../../stepmodel/types';
+import { ActionRegistry } from '../../actions/registry';
+import type { ActionDefinition } from '../../actions/types';
+export interface StepListEditorProps {
+    steps: BusinessStep[];
+    onStepsChange: (next: BusinessStep[]) => void;
+    /** 本列表之前的所有上游步骤（用于参数胶囊联想）；列表内前序步骤会自动追加 */
+    upstreamSteps: BusinessStep[];
+    registry?: ActionRegistry;
+    disabled?: boolean;
+    /** 本列表所在容器的嵌套深度（顶层容器为 0） */
+    depth: number;
+    onOpenInsertModal: (callback: (action: ActionDefinition) => void) => void;
+    /** regular：分支 / 循环体内的宽松行；compact：并行泳道内的窄列行 */
+    variant?: 'regular' | 'compact';
+    /** 行背景色调；展开区域使用相反色调，保持层次 */
+    rowTone?: 'primary' | 'secondary';
+    /** 序号徽标前缀，如「轮内 」 */
+    indexPrefix?: string;
+    /** 序号徽标是否使用强调色（默认为中性底色） */
+    accentIndexBadge?: boolean;
+}
+/**
+ * 分支 / 并行泳道 / 循环体共用的"子步骤列表"：
+ * - 普通动作渲染为可展开的表单行
+ * - 控制流步骤（分支 / 并行 / 循环）交给 NestedControlStep 递归渲染，因此可任意层级嵌套
+ */
+export declare const StepListEditor: React.FC<StepListEditorProps>;

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { WorkflowIDE } from './WorkflowIDE';
 export type { WorkflowIDEProps, WorkflowIDERef } from './WorkflowIDE';
-export type { WorkflowDef, TaskDef, WorkflowInputParam, WorkflowInstance } from './types/conductor';
+export type { WorkflowDef, TaskDef, WorkflowInputParam, WorkflowInstance, SchemaDef } from './types/conductor';
 export { parseWorkflowInputParams } from './types/conductor';
 export type { AIServiceConfig } from './services/aiService';
 export type { ExecutionActions, RestartOptions, ViewMode, RunState, WorkflowExecutionInput } from './types/workflow';
@@ -12,6 +12,9 @@ export * from './actions/types';
 export { ActionRegistry, defaultActionRegistry } from './actions/registry';
 export { BUILTIN_ECS_ACTIONS } from './actions/builtin/ecs';
 export { BUILTIN_COMMON_ACTIONS } from './actions/builtin/common';
+export { buildActionFromWorkflowDef, buildActionFromTaskDef, buildActionsFromLibrary, buildActionsFromTaskDefs, } from './actions/fromDefinitions';
+export type { ActionExtension, RegisteredTaskDef, LibraryWorkflowEntry, RegisteredTaskEntry, } from './actions/fromDefinitions';
+export { createStepFromAction } from './stepmodel/factory';
 export * from './stepmodel/types';
 export { compileStepToTaskDef, compileStepModelToWorkflowDef, } from './stepmodel/compile';
 export { decompileTaskDefToStep, decompileWorkflowDefToStepModel, } from './stepmodel/decompile';
@@ -37,3 +40,6 @@ export { FriendlyErrorCard } from './components/business/FriendlyErrorCard';
 export type { FriendlyErrorCardProps } from './components/business/FriendlyErrorCard';
 export { RunStoryTimeline } from './components/business/RunStoryTimeline';
 export type { RunStoryTimelineProps } from './components/business/RunStoryTimeline';
+export * from './library';
+export type { WorkflowLevel, WorkflowLibraryItem } from './types/workflowLibrary';
+export type { TaskSchema } from './services/ai/schemaRegistry';

package/dist/library/catalog.d.ts

@@ -0,0 +1,93 @@
+import type { WorkflowLevel, WorkflowLibraryItem } from '../types/workflowLibrary';
+import type { TaskSchema } from '../services/ai/schemaRegistry';
+import type { LibraryLoadStatus, LibraryProvider, LibrarySearchOptions, LibraryTaskRecord, LibraryWorkflowRecord } from './types';
+/** 规范化后的目录条目（每个 name 只有一个最新版本） */
+export interface LibraryEntry {
+    name: string;
+    /** 统一为整数 */
+    version: number;
+    versionLabel?: string;
+    description?: string;
+    level?: WorkflowLevel;
+    /** 业务域展示名：优先取 extension.domain，缺省时从流程名称解析 */
+    domain?: string;
+    tags: string[];
+    deprecated: boolean;
+    record: LibraryWorkflowRecord;
+    /** 条目来源：Provider 提供，或静态 prop（workflowLibrary）。同名时 Provider 优先 */
+    source: 'provider' | 'static';
+}
+/** 目录状态快照（引用在每次变化时更新，供 useSyncExternalStore 使用） */
+export interface LibraryCatalogSnapshot {
+    status: LibraryLoadStatus;
+    error?: Error;
+    /** 每次数据 / 状态变化递增，便于作为 useMemo 依赖 */
+    revision: number;
+}
+export interface LibraryCatalogOptions {
+    /** 兼容旧 `workflowLibrary` prop 的静态条目 */
+    staticItems?: WorkflowLibraryItem[];
+    /** 兼容旧 `taskSchemas` prop 的静态 Schema */
+    staticTaskSchemas?: TaskSchema[];
+}
+/** 把一条记录规范化为目录条目 */
+export declare function entryFromRecord(record: LibraryWorkflowRecord, source: LibraryEntry['source'], onLossy?: (name: string, label: string) => void): LibraryEntry;
+/**
+ * 流程库目录：把 Provider 与静态 prop 规范化成一份数据。
+ * 每个实例独立（不是全局单例）；通过 subscribe / getSnapshot 接入 React。
+ */
+export declare class LibraryCatalog {
+    private provider?;
+    private staticItems;
+    private staticSchemas;
+    private providerEntries;
+    private providerTasks;
+    private merged;
+    private versionCache;
+    private warned;
+    private listeners;
+    /** 每次 load / setProvider 递增，用于丢弃过期的异步结果 */
+    private generation;
+    private controller;
+    private snapshot;
+    constructor(provider?: LibraryProvider, options?: LibraryCatalogOptions);
+    /** 更换数据源：丢弃旧数据与缓存，状态回到 idle（需再调用 load） */
+    setProvider(provider?: LibraryProvider): void;
+    /** 更新静态条目 / Schema（对应旧 prop 变化） */
+    setStatic(options: LibraryCatalogOptions): void;
+    hasProvider(): boolean;
+    /** Provider 是否支持服务端检索 */
+    hasServerSearch(): boolean;
+    /**
+     * 拉取目录：同名多版本去重取最大 version。
+     * 同一时刻只保留最新一次加载：新的 load / reload / setProvider / abort 会取消上一次（abort 其请求并丢弃其结果）；
+     * 传入的 signal 被 abort 时同样取消。网络错误记为 error 状态，不抛出。
+     */
+    load(signal?: AbortSignal): Promise<void>;
+    /** 重新加载（供 UI「点击重试」使用） */
+    reload(): Promise<void>;
+    /** 取消进行中的加载（组件卸载时调用）；已加载的数据保留 */
+    abort(): void;
+    latest(name: string): LibraryEntry | undefined;
+    entries(): LibraryEntry[];
+    /** Provider 提供的原子任务定义 */
+    tasks(): LibraryTaskRecord[];
+    /** 静态 Schema（Provider 未覆盖的部分由 projections 合并） */
+    staticTaskSchemas(): TaskSchema[];
+    /**
+     * 取指定版本的完整定义（历史版本按需获取并缓存）。
+     * 找不到返回 null；网络错误向上抛出，由调用方决定如何提示。
+     */
+    getVersion(name: string, version: number, signal?: AbortSignal): Promise<LibraryWorkflowRecord | null>;
+    /**
+     * 服务端检索。Provider 未实现 search 时返回 null，调用方应退回本地匹配。
+     * 结果不并入目录（只是一次查询的命中）。
+     */
+    search(query: string, opts?: LibrarySearchOptions, signal?: AbortSignal): Promise<LibraryEntry[] | null>;
+    getSnapshot: () => LibraryCatalogSnapshot;
+    subscribe: (listener: () => void) => (() => void);
+    private warnLossy;
+    /** Provider 条目优先，静态条目补充同名之外的部分 */
+    private rebuild;
+    private setState;
+}

package/dist/library/conductorProvider.d.ts

@@ -0,0 +1,41 @@
+import type { WorkflowDef } from '../types/conductor';
+import type { RegisteredTaskDef } from '../actions/fromDefinitions';
+import type { LibraryExtension, LibraryProvider } from './types';
+export interface ConductorLibraryProviderOptions {
+    /** Conductor API 根地址，如 `https://conductor.example.com/api`（尾部斜杠可有可无） */
+    baseUrl: string;
+    /**
+     * 认证头等，由宿主在每次请求前注入（组件库不保存任何凭据）。
+     * 可返回 Promise，便于异步刷新 token。
+     */
+    headers?: () => Record<string, string> | Promise<Record<string, string>>;
+    /** 自定义 fetch（测试 / 网关封装）；缺省使用全局 fetch */
+    fetch?: typeof fetch;
+    /** 是否同时拉取已注册的原子任务定义（`/metadata/taskdefs`），默认 false */
+    includeTaskDefs?: boolean;
+    /** 只暴露「流程库」内的工作流（如按名前缀 / ownerEmail）；对列表与单个获取都生效 */
+    filter?: (def: WorkflowDef) => boolean;
+    /** 补充字段（层级、分类、图标、是否下线等）的来源由宿主决定 */
+    resolveExtension?: (def: WorkflowDef) => LibraryExtension | undefined;
+    /** 原子任务的补充字段来源（仅 includeTaskDefs 时使用） */
+    resolveTaskExtension?: (def: RegisteredTaskDef) => LibraryExtension | undefined;
+    /**
+     * 网关路径不同可覆盖（相对 baseUrl）。
+     * `workflow` 为单个工作流的路径：含 `{name}` 时按模板替换，否则在其后追加 `/{name}`。
+     */
+    paths?: {
+        workflows?: string;
+        workflow?: string;
+        taskDefs?: string;
+    };
+}
+/**
+ * Conductor OSS 默认的流程库数据源：
+ * - `GET {baseUrl}/metadata/workflow`            列出工作流（同名多版本时客户端取最大 version）
+ * - `GET {baseUrl}/metadata/workflow/{name}?version={v}`  取指定版本，404 返回 null
+ * - `GET {baseUrl}/metadata/taskdefs`            已注册任务（includeTaskDefs 时）
+ *
+ * 不内置 `search`（Conductor OSS 元数据接口没有检索能力）；需要服务端检索请自行实现 LibraryProvider。
+ * 网络错误 / 非 404 的 HTTP 错误会抛出，由目录层捕获为 `error` 状态。
+ */
+export declare function createConductorLibraryProvider(options: ConductorLibraryProviderOptions): LibraryProvider;

package/dist/library/diff.d.ts

@@ -0,0 +1,62 @@
+import type { WorkflowDef } from '../types/conductor';
+import type { ActionField } from '../actions/types';
+/**
+ * 流程库能力升级差异（纯函数）：对比旧、新两个版本的入参 / 出参，
+ * 让用户在确认升级前看清「哪些已填内容会受影响」。
+ */
+export interface InputChange {
+    key: string;
+    /** 旧版本的类型描述，如「数字，必填」「可选值 a|b」 */
+    from: string;
+    /** 新版本的类型描述 */
+    to: string;
+    /** 该入参是否已填写过值（类型变化后已填值可能不再有效） */
+    valueFilled: boolean;
+}
+export interface WorkflowVersionDiff {
+    /** 新增入参（field.required 标出必填） */
+    addedInputs: ActionField[];
+    /** 删除的入参 */
+    removedInputs: ActionField[];
+    /** 类型 / 枚举 / 必填变化 */
+    changedInputs: InputChange[];
+    addedOutputs: string[];
+    removedOutputs: string[];
+    /** removedInputs 中已填值的 key：升级后这些值将丢失 */
+    lostValueKeys: string[];
+    /** removedOutputs 中被其它步骤引用的 key：升级后下游引用将失效 */
+    brokenOutputRefs: string[];
+}
+export interface DiffOptions {
+    /** 其它步骤中引用了本步骤哪些出参 key（见 collectReferencedOutputKeys）；缺省视为没有引用 */
+    referencedOutputs?: Iterable<string>;
+}
+/**
+ * @param oldDef       步骤当前固定版本的定义
+ * @param newDef       目录最新版本的定义
+ * @param filledValues 步骤上已填写的入参值
+ */
+export declare function diffWorkflowVersions(oldDef: WorkflowDef, newDef: WorkflowDef, filledValues?: Record<string, unknown>, options?: DiffOptions): WorkflowVersionDiff;
+/** 没有任何入参 / 出参变化 */
+export declare function isDiffEmpty(diff: WorkflowVersionDiff): boolean;
+/**
+ * 在若干结构（其它步骤的入参值等）中查找对 `${ref.output.<key>...}` 的引用，返回被引用的出参 key。
+ * 用于判断升级删除某个出参后，下游引用是否会失效。
+ */
+export declare function collectReferencedOutputKeys(taskReferenceName: string, parts: unknown[]): Set<string>;
+export interface DiffSummary {
+    /** 会影响已填内容的条目（置顶显示） */
+    impacts: string[];
+    /** 其它变化 */
+    changes: string[];
+}
+/** 把差异整理为面向用户的文字条目：会影响已填内容的置顶 */
+export declare function summarizeDiff(diff: WorkflowVersionDiff): DiffSummary;
+/** 升级确认框文案（含升级差异）。无差异时提示「入参出参未变化」。 */
+export declare function buildUpgradeConfirmMessage(name: string, pinned: number | undefined, latest: number, diff: WorkflowVersionDiff): string;
+/**
+ * 升级后调整步骤已填的入参值：
+ * - 删除的入参：移除其值（与差异中「值将丢失」一致）
+ * - 新增且有默认值的入参：补上默认值（用户已填的不覆盖）
+ */
+export declare function applyUpgradeToValues(values: Record<string, any>, diff: WorkflowVersionDiff): Record<string, any>;

package/dist/library/index.d.ts

@@ -0,0 +1,16 @@
+export * from './types';
+export { normalizeVersion } from './version';
+export type { NormalizedVersion } from './version';
+export { canCallLevel } from './level';
+export { parseWorkflowName, validateWorkflowName, WORKFLOW_NAME_TYPES } from './naming';
+export type { ParsedWorkflowName, WorkflowNameType } from './naming';
+export { LibraryCatalog, entryFromRecord } from './catalog';
+export type { LibraryEntry, LibraryCatalogSnapshot, LibraryCatalogOptions } from './catalog';
+export { toActions, toActionExtension, toTaskSchemas, toLibraryItems, entriesToLibraryItems, filterPickableActions, libraryDomainOf, collectLibraryDomains, OTHER_DOMAIN, schemaToTypeStrings, } from './projections';
+export { useLibraryCatalogSnapshot, useLibraryCatalogLoader } from './useLibraryCatalog';
+export { createConductorLibraryProvider } from './conductorProvider';
+export type { ConductorLibraryProviderOptions } from './conductorProvider';
+export { diffWorkflowVersions, isDiffEmpty, summarizeDiff, buildUpgradeConfirmMessage, applyUpgradeToValues, collectReferencedOutputKeys, } from './diff';
+export type { WorkflowVersionDiff, InputChange, DiffOptions, DiffSummary } from './diff';
+export { resolveLibraryBadgeState, describeUnavailable } from './versionStatus';
+export type { LibraryBadgeState, LibraryBadgeInputs } from './versionStatus';

package/dist/library/level.d.ts

@@ -0,0 +1,6 @@
+import type { WorkflowLevel } from '../types/workflowLibrary';
+/**
+ * 分层调用规则：高层可调用低层及同层，禁止反向跨层。
+ * L3 -> L3/L2/L1；L2 -> L2/L1；L1 -> L1。任一方层级未知时视为允许（不做限制）。
+ */
+export declare function canCallLevel(caller: WorkflowLevel | undefined, callee: WorkflowLevel | undefined): boolean;