@yiyi_zhang/reactflow-ui 1.1.0 → 1.3.0

package/dist/components/onboarding/WorkflowNameBuilder.d.ts

@@ -0,0 +1,19 @@
+import type { ProductInfo } from '../../providers/types';
+import type { WorkflowNameParts } from '../../onboarding/naming';
+export interface WorkflowNameBuilderProps {
+    /** 可选的所属产品（我的产品）；业务域取自所选产品 */
+    products: ProductInfo[];
+    /** 允许的业务域列表；提供时参与校验 */
+    domains?: string[];
+    /** 试用环境：类型固定为 tmp；否则可选 custom / std */
+    trial: boolean;
+    value: WorkflowNameParts;
+    onChange: (next: WorkflowNameParts) => void;
+    disabled?: boolean;
+}
+/**
+ * 五段式命名生成器：`类型-层级-业务域-产品-功能`。
+ * 受控组件：类型（试用固定 tmp）、层级、产品（下拉我的产品，业务域随产品带出）、功能（自由输入，推荐 snake_case），
+ * 实时预览完整名称并用 `validateWorkflowName` 校验。
+ */
+export declare function WorkflowNameBuilder({ products, domains, trial, value, onChange, disabled }: WorkflowNameBuilderProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/onboarding/index.d.ts

@@ -0,0 +1,8 @@
+export { WorkflowNameBuilder } from './WorkflowNameBuilder';
+export type { WorkflowNameBuilderProps } from './WorkflowNameBuilder';
+export { OnboardingWizard } from './OnboardingWizard';
+export type { OnboardingWizardProps, OnboardingCreateResult } from './OnboardingWizard';
+export { PromotionPanel } from './PromotionPanel';
+export type { PromotionPanelProps } from './PromotionPanel';
+export { OnboardingGuideCard } from './OnboardingGuideCard';
+export type { OnboardingGuideCardProps } from './OnboardingGuideCard';

package/dist/components/onboarding/styles.d.ts

@@ -0,0 +1,11 @@
+import type { CSSProperties } from 'react';
+/** 自助接入组件共用的内联样式：只使用主题 CSS 变量，弹窗根节点另行设置 data-mode / data-brand */
+export declare const labelStyle: CSSProperties;
+export declare const inputStyle: CSSProperties;
+export declare const hintStyle: CSSProperties;
+export declare const errorStyle: CSSProperties;
+export declare const buttonBase: CSSProperties;
+export declare const primaryButton: CSSProperties;
+export declare const ghostButton: CSSProperties;
+export declare function disabledStyle(base: CSSProperties, disabled: boolean): CSSProperties;
+export declare const noticeStyle: (kind: "error" | "warning" | "success") => CSSProperties;

package/dist/components/onboarding/useOnboardingData.d.ts

@@ -0,0 +1,17 @@
+import type { OnboardingContext, OnboardingProvider, ProductInfo } from '../../providers/types';
+export interface OnboardingData {
+    status: 'idle' | 'loading' | 'ready' | 'error';
+    context: OnboardingContext | null;
+    domains: string[];
+    products: ProductInfo[];
+    error: string | null;
+    /** 重新加载（失败后重试） */
+    reload: () => void;
+    /** 新登记产品后本地追加，避免再请求一次 */
+    addProduct: (p: ProductInfo) => void;
+}
+/**
+ * 按 provider 实例加载一次：上下文、业务域、我的产品。
+ * provider 引用变化时重新加载；卸载或切换时中止进行中的请求。没有 provider 时保持 idle。
+ */
+export declare function useOnboardingData(provider: OnboardingProvider | undefined): OnboardingData;

package/dist/components/template/TemplateGallery.d.ts

@@ -6,5 +6,7 @@ export interface TemplateGalleryProps {
     onClose: () => void;
     onSelectTemplate: (configuredDef: WorkflowDef) => void;
     templateStore?: TemplateStore;
+    /** 试跑结束（快捷试跑或向导内试跑）：参数为最终状态或 'error'，用于接入埋点，不含数据 */
+    onSandboxRun?: (result: string) => void;
 }
 export declare const TemplateGallery: React.FC<TemplateGalleryProps>;

package/dist/components/template/TemplateSetupWizard.d.ts

@@ -5,5 +5,7 @@ export interface TemplateSetupWizardProps {
     template: WorkflowTemplate;
     onApply: (configuredDef: WorkflowDef) => void;
     onClose: () => void;
+    /** 向导内试跑结束：最终状态或 'error'（埋点用，不含数据） */
+    onSandboxRun?: (result: string) => void;
 }
 export declare const TemplateSetupWizard: React.FC<TemplateSetupWizardProps>;

package/dist/import/buildAction.d.ts

@@ -0,0 +1,23 @@
+/**
+ * ImportedOperation → 业务动作（ActionDefinition）。
+ *
+ * - 字段：路径参数 / 查询参数 / 请求头参数 / 请求体属性，沿用 `buildFields` 规则（title → 标签、enum → 下拉、
+ *   类型 → 控件），全部支持插入数据胶囊；
+ * - 出参：2xx 响应 schema，沿用 `buildOutputs`，键为 Conductor HTTP 任务的真实输出路径
+ *   `response.body.<字段>`，因此数据胶囊引用 `${ref.output.response.body.xxx}` 运行时可直接取到；
+ * - 编译：Conductor `HTTP` 任务，`inputParameters` 里保留 `_actionId` 与各字段值，
+ *   使步骤重新打开时能被 `decompile` 还原为同一动作（动作未注册时退回「专业步骤」卡片，定义无损）。
+ */
+import type { ActionDefinition } from '../actions/types';
+import type { ImportedOperation } from './types';
+export interface BuildHttpActionOptions {
+    /** 已存在的动作 id（完整 id，如 `import.get_tickets`）：冲突时自动追加 `_2` 等后缀 */
+    existingIds?: Iterable<string>;
+    /** 动作 id 前缀，默认 `import` */
+    idPrefix?: string;
+}
+/**
+ * 由导入的接口生成 HTTP 业务动作。
+ * 固定请求头会再做一次敏感值检查（解析器已处理时这里是空操作），保证动作定义里不会出现凭据。
+ */
+export declare function buildHttpAction(op: ImportedOperation, opts?: BuildHttpActionOptions): ActionDefinition;

package/dist/import/common.d.ts

@@ -0,0 +1,17 @@
+/** 各格式解析器共用的收尾逻辑（纯函数）。 */
+import type { ImportedOperation } from './types';
+import type { ImportedParam } from './types';
+/** 收尾：替换固定请求头里的敏感值，并把提示并入接口的 warnings */
+export declare function finishOperation(op: ImportedOperation): ImportedOperation;
+/** 接口的展示标识：`GET /tickets/{id}` */
+export declare function operationLabel(op: Pick<ImportedOperation, 'method' | 'path'>): string;
+/** 汇总所有接口的提示（带接口前缀，去重） */
+export declare function collectWarnings(ops: ImportedOperation[], extra?: string[]): string[];
+/** 把 JSON 示例的顶层属性作为默认值写入 schema；敏感字段名的默认值换成占位 */
+export declare function schemaWithDefaults(example: unknown, warnings: string[]): Record<string, any>;
+/** 把查询串解析为 query 参数（字面量作为默认值；敏感参数名的值替换为占位） */
+export declare function queryParamsFromString(query: string, warnings: string[]): ImportedParam[];
+/** Content-Type / Accept 由 body.contentType 与 accept 统一输出，不再作为固定头 */
+export declare function dropContentHeaders(headers: Record<string, string>): Record<string, string>;
+/** 不区分大小写取请求头的值 */
+export declare function findHeader(headers: Record<string, string>, name: string): string | undefined;

package/dist/import/curl.d.ts

@@ -0,0 +1,12 @@
+/**
+ * curl 命令 → ImportedOperation[]（恒为 0 或 1 个接口）。
+ * 支持：-X、-H（多个）、-d / --data / --data-raw / --data-binary、-u、--url、-G、行尾 `\` 续行、
+ * 单引号 / 双引号 / `$'…'`（浏览器「复制为 cURL」）。不执行任何命令。
+ */
+import type { ParseResult } from './types';
+/** 把命令行切成 token（兼容续行与常见引号写法） */
+export declare function tokenizeCurl(input: string): string[];
+/** 提示用的 curl 示例（对话框 placeholder 使用） */
+export declare const CURL_SAMPLE = "curl -X POST 'https://api.example.com/v1/tickets' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Authorization: Bearer <token>' \\\n  -d '{\"title\":\"\u78C1\u76D8\u544A\u8B66\",\"priority\":\"high\"}'";
+/** 解析一条 curl 命令 */
+export declare function parseCurl(command: string): ParseResult;

package/dist/import/detect.d.ts

@@ -0,0 +1,9 @@
+/** 输入格式识别与统一入口（纯函数，不抛异常）。 */
+import type { DetectedFormat, ParseResult } from './types';
+/** 识别输入文本的格式 */
+export declare function detectFormat(text: string): DetectedFormat;
+/**
+ * 识别并解析：返回 ParseResult，永不抛异常。
+ * YAML 不受支持，返回固定提示 {@link YAML_HINT}。
+ */
+export declare function parseApiText(text: string): ParseResult;

package/dist/import/index.d.ts

@@ -0,0 +1,10 @@
+export * from './types';
+export { detectFormat, parseApiText } from './detect';
+export { parseOpenApi3, parseSwagger2 } from './openapi';
+export { parsePostman21 } from './postman';
+export { parseCurl, tokenizeCurl, CURL_SAMPLE } from './curl';
+export { buildHttpAction } from './buildAction';
+export type { BuildHttpActionOptions } from './buildAction';
+export { appendImportedActions, blankImportWorkflow, collectWorkflowInputRefs } from './insert';
+export { resolveSchema } from './schema';
+export { isSensitiveHeader, sanitizeHeaders, inputPlaceholder } from './sensitive';

package/dist/import/insert.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 把导入生成的动作作为步骤追加到流程末尾（纯函数，业务模式与专业模式共用）。
+ * B2 向导的「从接口导入」也可直接复用。
+ */
+import type { ActionDefinition } from '../actions/types';
+import type { TaskDef, WorkflowDef } from '../types/conductor';
+/** 没有当前流程时使用的空白骨架 */
+export declare function blankImportWorkflow(name?: string): WorkflowDef;
+/** 取出任务里引用的 `${workflow.input.xxx}` 的顶层入参名 */
+export declare function collectWorkflowInputRefs(tasks: TaskDef[]): string[];
+/**
+ * 为每个动作按默认值生成一个步骤并追加到 `def.tasks` 末尾；
+ * 步骤引用的 `${workflow.input.xxx}`（敏感头占位、路径参数默认值等）会补进流程的入参声明。
+ * 不修改入参，返回新的定义。
+ */
+export declare function appendImportedActions(def: WorkflowDef | null | undefined, actions: ActionDefinition[]): WorkflowDef;

package/dist/import/openapi.d.ts

@@ -0,0 +1,9 @@
+/**
+ * OpenAPI 3.x / Swagger 2.0（JSON 文档对象）→ ImportedOperation[]。
+ * 只做解析，不发请求；解析失败返回 { ok: false }，不抛异常。
+ */
+import type { ParseResult } from './types';
+/** 解析 OpenAPI 3.x 文档对象 */
+export declare function parseOpenApi3(doc: unknown): ParseResult;
+/** 解析 Swagger 2.0 文档对象 */
+export declare function parseSwagger2(doc: unknown): ParseResult;

package/dist/import/postman.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Postman Collection v2.1（JSON 文档对象）→ ImportedOperation[]。
+ * Postman 变量 `{{var}}` 转为 `${workflow.input.var}`；认证配置只生成占位，不读取凭据值。
+ */
+import type { ParseResult } from './types';
+/** `{{var}}` → `${workflow.input.var}`；记录用到的变量名 */
+export declare function convertPostmanVars(text: string, used?: Set<string>): string;
+/** 解析 Postman Collection v2.1 文档对象 */
+export declare function parsePostman21(doc: unknown): ParseResult;

package/dist/import/schema.d.ts

@@ -0,0 +1,15 @@
+/**
+ * JSON Schema 本地 `$ref` 解析（OpenAPI 3 `#/components/schemas/...`、Swagger 2 `#/definitions/...`）。
+ * 防循环引用，最大展开深度 6；不处理远程引用。
+ */
+import type { JsonSchema } from './types';
+export declare const MAX_SCHEMA_DEPTH = 6;
+/** 按 JSON Pointer（`#/a/b`）取值，找不到返回 undefined */
+export declare function resolvePointer(root: unknown, ref: string): unknown;
+/** 解开非 schema 对象（parameter / requestBody / response）上的 `$ref`，最多跳 10 次 */
+export declare function derefObject<T = any>(node: unknown, root: unknown): T | undefined;
+/**
+ * 解析 schema：展开本地 `$ref` 与 allOf，oneOf / anyOf 取第一个分支。
+ * 超过深度上限的节点只保留类型；循环引用处截断为 `{ type: 'object' }` 并在 warnings 中提示一次。
+ */
+export declare function resolveSchema(schema: unknown, root: unknown, warnings?: string[], maxDepth?: number): JsonSchema;

package/dist/import/sensitive.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 敏感信息处理：请求头 / 查询参数 / 请求体字段里的凭据不落入流程定义，
+ * 一律替换为 `${workflow.input.xxx}` 占位，并给出提示。
+ */
+export declare function isSensitiveHeader(name: string): boolean;
+/** 查询参数 / 请求体字段名是否敏感 */
+export declare function isSensitiveName(name: string): boolean;
+/** 占位表达式：`${workflow.input.<camelName>}` */
+export declare function inputPlaceholder(name: string): string;
+export declare function sensitiveHeaderWarning(name: string): string;
+/**
+ * 替换请求头中的敏感值。已是 `${...}` 表达式的值视为已处理，原样保留。
+ * 返回新对象，不修改入参。
+ */
+export declare function sanitizeHeaders(headers: Record<string, string>): {
+    headers: Record<string, string>;
+    warnings: string[];
+};

package/dist/import/types.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 接口导入：解析结果的公共类型（纯数据，无 React 依赖）。
+ * 设计见 docs/design/v1.3.0-自助接入设计.md 第 4 节。
+ */
+/** 可导入的来源格式 */
+export type ImportFormat = 'openapi3' | 'swagger2' | 'postman21' | 'curl';
+/** detectFormat 的结果：除可导入格式外，还可能是 YAML（不支持）或无法识别 */
+export type DetectedFormat = ImportFormat | 'yaml' | 'unknown';
+/** JSON Schema 片段（已解析本地 $ref，保持宽松类型） */
+export type JsonSchema = Record<string, any>;
+export type ParamLocation = 'path' | 'query' | 'header';
+export interface ImportedParam {
+    name: string;
+    in: ParamLocation;
+    required: boolean;
+    schema: JsonSchema;
+    description?: string;
+    /** 导入时带入的默认值（curl / Postman 中的字面量；敏感名称已替换为占位） */
+    defaultValue?: string;
+}
+export interface ImportedBody {
+    /** 例如 application/json */
+    contentType: string;
+    /** object 且含 properties 时拆成多个字段；否则整体作为单个 `body` 字段 */
+    schema: JsonSchema;
+}
+export interface ImportedOperation {
+    /** 同一次解析内唯一，形如 `get_tickets_id`，用于动作 id（`import.<id>`） */
+    id: string;
+    /** 大写 HTTP 方法 */
+    method: string;
+    /** 服务地址（不含路径），可能为空或含 `${workflow.input.xxx}` */
+    baseUrl: string;
+    /** 路径模板，路径参数写作 `{id}` */
+    path: string;
+    summary?: string;
+    description?: string;
+    operationId?: string;
+    tags: string[];
+    params: ImportedParam[];
+    /** 固定请求头（敏感头的值已替换为 `${workflow.input.xxx}` 占位） */
+    headers: Record<string, string>;
+    body?: ImportedBody;
+    /** 2xx 响应的 JSON Schema */
+    responseSchema?: JsonSchema;
+    /** 与该接口相关的提示（敏感头替换、不支持的部分等） */
+    warnings: string[];
+}
+export type ParseResult = {
+    ok: true;
+    format: ImportFormat;
+    operations: ImportedOperation[];
+    /** 汇总提示（含各接口的提示，已带接口前缀） */
+    warnings: string[];
+} | {
+    ok: false;
+    format?: DetectedFormat;
+    /** 面向用户的中文错误信息 */
+    error: string;
+};
+/** 提示用户把 YAML 转成 JSON 的固定文案 */
+export declare const YAML_HINT = "YAML \u8BF7\u5148\u8F6C\u4E3A JSON \u540E\u518D\u5BFC\u5165";

package/dist/import/util.d.ts

@@ -0,0 +1,23 @@
+/** 接口导入内部的小工具（纯函数）。 */
+import type { JsonSchema } from './types';
+export declare const HTTP_METHODS: readonly ["get", "post", "put", "delete", "patch", "head", "options"];
+export declare function isPlainObject(v: unknown): v is Record<string, any>;
+/** 去 BOM、首尾空白 */
+export declare function normalizeText(text: string): string;
+/** 把任意名称转为 snake_case 片段（只保留字母数字） */
+export declare function slugify(raw: string, maxLen?: number): string;
+/** 把名称转为 camelCase（用于 `${workflow.input.xxx}`） */
+export declare function camelName(raw: string): string;
+/** 在已有 id 集合内取唯一 id（冲突时追加 _2、_3…），并登记到集合 */
+export declare function uniqueId(base: string, used: Set<string>): string;
+/** 由一个 JSON 示例值推断简单 schema（不含 default） */
+export declare function inferSchema(value: unknown, depth?: number): JsonSchema;
+/** 取 schema 的主类型（忽略 null） */
+export declare function schemaType(schema: JsonSchema | undefined): string;
+/** 简单的 URL 拆分：baseUrl（协议+主机 或 `${...}` 变量）、路径、查询串 */
+export declare function splitUrl(raw: string): {
+    baseUrl: string;
+    path: string;
+    query: string;
+};
+export declare function safeDecode(s: string): string;

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,22 @@ 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';
+export { WorkflowIdeProvider, useIdeProviders } from './providers/WorkflowIdeProvider';
+export type { WorkflowIdeProviderProps } from './providers/WorkflowIdeProvider';
+export { resolveProviders, stabilizeProviders } from './providers/resolve';
+export type { ProviderSources } from './providers/resolve';
+export type { IdeProviders, OnboardingProvider, OnboardingContext, ProductInfo, StartTrialResult, PromotionStatus, } from './providers/types';
+export { WorkflowNameBuilder, OnboardingWizard, PromotionPanel, OnboardingGuideCard } from './components/onboarding';
+export type { WorkflowNameBuilderProps, OnboardingWizardProps, OnboardingCreateResult, PromotionPanelProps, OnboardingGuideCardProps, } from './components/onboarding';
+export { buildWorkflowName, validateNameParts, suggestFuncSlug, promotionTargetName, isPromotableName, buildSkeletonWorkflow, nextPollDelay, isTerminalPromotionState, buildPromotionTimeline, promotionStateLabel, pollPromotion, } from './onboarding';
+export type { WorkflowNameParts, PromotionTargetType, SkeletonInput, TimelineItem, PromotionState, StartSource } from './onboarding';
+export { createTelemetryBuffer } from './telemetry/buffer';
+export type { TelemetryBuffer, TelemetryBufferOptions } from './telemetry/buffer';
+export type { TelemetrySink, IdeEvent, IdeEventName } from './telemetry/types';
+export { detectFormat, parseApiText, parseOpenApi3, parseSwagger2, parsePostman21, parseCurl, buildHttpAction, appendImportedActions, sanitizeHeaders, } from './import';
+export type { ImportFormat, DetectedFormat, ImportedOperation, ImportedParam, ImportedBody, ParseResult, BuildHttpActionOptions, } from './import';
+export { ApiImportDialog } from './components/import/ApiImportDialog';
+export type { ApiImportDialogProps, ApiImportInsertInfo } from './components/import/ApiImportDialog';

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;

package/dist/library/naming.d.ts

@@ -0,0 +1,28 @@
+import type { WorkflowLevel } from '../types/workflowLibrary';
+/**
+ * 治理平台的流程命名规范：`类型-层级-业务域-产品-功能`，以 `-` 分隔。
+ * - 类型：std（通用）/ proxy（代理）/ tmp（临时，自动清理）/ custom（自定义）
+ * - 层级：L1 / L2 / L3
+ * - 业务域：来自全局可调整的列表（由服务端提供，这里不写死，只当字符串处理）
+ * - 产品：自由名称（内部不含 `-`）
+ * - 功能：第 4 个 `-` 之后的全部内容（自身可含 `-`）
+ */
+export type WorkflowNameType = 'std' | 'proxy' | 'tmp' | 'custom';
+export interface ParsedWorkflowName {
+    type: WorkflowNameType;
+    level: WorkflowLevel;
+    domain: string;
+    product: string;
+    func: string;
+}
+export declare const WORKFLOW_NAME_TYPES: readonly WorkflowNameType[];
+/**
+ * 解析流程名称。段数不足 5、类型或层级不合法时返回 null（不抛错）。
+ * 业务域 / 产品 / 功能只做切分，不在此校验是否为空或是否在白名单内（见 validateWorkflowName）。
+ */
+export declare function parseWorkflowName(name: string): ParsedWorkflowName | null;
+/**
+ * 校验流程名称，返回中文错误列表（空数组 = 合法）。
+ * 仅当提供 allowedDomains 时才校验业务域是否在列表内。
+ */
+export declare function validateWorkflowName(name: string, allowedDomains?: string[]): string[];